magicciv/.project/README.md

.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

python3 tools/objectives-report.py     # rebuilds objectives/README.md from frontmatter