wiki/tasks/ontology-management/docs/ONTLOGY-MANAGEMENT.md

Ontology & Projects Management Documentation

1. Core principles

• Ontology is the source of truth for projects and tasks.
• Stream is the only writer.
• Changes require approval from Слава.
• Tasks do not exist without projects.
• Keep graph history append-only whenever possible.

2. Entity rules

Project

Required:

• name
• folder
• doc_path

Recommended:

• description
• status
• start_date
• end_date
• owner
• team
• goals
• tags

Task

Required:

• title
• status
• project
• folder
• doc_path

Recommended:

• description
• priority
• assignee
• due
• estimate_hours
• blockers
• tags

3. Folder standard

Project folder

tasks/<project-slug>/
├── PROJECT.md
├── docs/
├── journal/
├── assets/
├── meta/
└── TASKS/
    ├── backlog/
    ├── active/
    ├── blocked/
    ├── done/
    └── archive/

Task folder

tasks/<project-slug>/TASKS/<status>/<task-slug>/
├── TASK.md
├── context.md
├── report.md
└── attachments/

Naming convention

• Human-facing names use name / title.
• Internal id remains stable and may be machine-oriented.
• Folder names use readable slugs, not internal ids.
• Task slugs should describe the task, not the database identifier.

4. Document paths

• Project.doc_path points to the main project document, usually PROJECT.md.
• Task.doc_path points to the main task document, usually TASK.md.
• folder is the directory containing the object.

5. Validation workflow

1. Update schema.
2. Migrate graph data if needed.
3. Run validation.
4. Run get/query tests.
5. Fix only the minimum required issues.

6. Migration workflow

1. Backup current files.
2. Compare current schema with reference schema.
3. Normalize entity fields.
4. Add missing required path fields.
5. Revalidate.

7. Testing checklist

• ontology.py validate
• ontology.py get --id <known_id>
• ontology.py query --type Project ...
• ontology.py query --type Task ...
• Check that project and task folders exist on disk.