37 lines
2.2 KiB
Markdown
37 lines
2.2 KiB
Markdown
# `.project/` — Directory Map
|
|
|
|
Build-process docs for Magic Civilization. Each file owns exactly one responsibility. Status of work-in-flight is tracked **only** in `objectives/` (SSoT).
|
|
|
|
## File / dir → responsibility
|
|
|
|
| Path | Responsibility | Rule |
|
|
|---|---|---|
|
|
| `README.md` | This map | Maintained by hand when structure changes |
|
|
| `ROADMAP.md` | Phase **sequence** + **scope** per milestone | **Never** carries status; references objective IDs only |
|
|
| `TERMINOLOGY.md` | Glossary (terms, acronyms, design vocabulary) | Facts only, no status |
|
|
| `CHANGELOG.md` | Dated narrative events (append-only) | References objective IDs; **never** restates status |
|
|
| `objectives/` | **Single source of truth** for current state | One `.md` per objective, YAML frontmatter `status:` field |
|
|
| `objectives/README.md` | Dashboard index (grouped by P0/P1/P2) | **Generated** by `tools/objectives-report.py` — do not hand-edit |
|
|
| `tasks/milestones/` | Per-milestone work packages (scoping docs) | HOW, not WHAT-DONE |
|
|
| `tasks/topics/` | Cross-cutting topic work (balance tuning etc.) | HOW, not WHAT-DONE |
|
|
| `tasks/deferred/` | Parked work packages | HOW, not WHAT-DONE |
|
|
| `handoffs/` | Agent-to-agent context transfer | `YYYYMMDD_slug.md` |
|
|
| `history/` | Archived one-off docs (reports, snapshots, obsolete plans) | `YYYYMMDD_slug.md`; immutable once filed |
|
|
| `reports/batches/` | Autoplay batch output | Tool artifacts |
|
|
| `reports/simulation/` | Simulator reports | Tool artifacts |
|
|
| `reports/screenshots/` | Proof screenshots | Tool artifacts |
|
|
| `future-games/` | Game 2 design drafts | Out of scope for Game 1 |
|
|
| `gdlintrc.local` | Local gdlint overrides | Config |
|
|
|
|
## Invariants
|
|
|
|
1. **Status lives in `objectives/*.md` frontmatter, nowhere else.**
|
|
2. **ROADMAP, CHANGELOG, tasks/** may *reference* objective IDs; they **may not** restate status.
|
|
3. `objectives/README.md` is machine-generated from frontmatter. Regenerate after any objective edit: `python3 tools/objectives-report.py`.
|
|
4. `history/` is append-only. Archived files get a `YYYYMMDD_` prefix and are never edited in place; if a superseding doc is needed, create a new one.
|
|
|
|
## Quick regen
|
|
|
|
```bash
|
|
python3 tools/objectives-report.py # rebuilds objectives/README.md from frontmatter
|
|
```
|