108 lines
2.1 KiB
Markdown
108 lines
2.1 KiB
Markdown
# 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
|
|
```text
|
|
tasks/<project-slug>/
|
|
├── PROJECT.md
|
|
├── docs/
|
|
├── journal/
|
|
├── assets/
|
|
├── meta/
|
|
└── TASKS/
|
|
├── backlog/
|
|
├── active/
|
|
├── blocked/
|
|
├── done/
|
|
└── archive/
|
|
```
|
|
|
|
### Task folder
|
|
```text
|
|
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.
|