# 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.