Current state
An agent implementing a feature adjacent to dispatch, session tracking, or task fold-back reads architecture docs that describe a complete, coherent system. Those docs contain "not yet built" notices scattered across individual ADRs and architecture files — there is no single file that lists what actually exists today vs. what is described but unimplemented. The result: agents write code against integration points that don't exist, or skip implementing pieces that are already present.
Observable facts:
docs/architecture/tasks.md, docs/architecture/task-dispatch.md, and individual ADRs (005, 006, 009, 010, 012, 013, 014, 016, 017, 018) each contain their own "not yet built" or "not yet implemented" notices inline.
- No file in
docs/ or CLAUDE.md aggregates these into a cross-cutting built/planned inventory.
CLAUDE.md references the agents/ Rust crate described in Decision 005 but notes it "has not been built yet" — this is representative of a pattern repeated across the docs with no single authoritative view.
Ideal state
- A
docs/status.md file exists and lists every major subsystem (dispatch, session tracking, task fold-back, mining loop, verdict signal, agents crate, etc.) with a binary built / planned marker, a one-line description, and a link to the relevant ADR or issue.
- An agent dropped in cold reads
docs/status.md and immediately knows which code paths are real and which are planned.
CLAUDE.md links to docs/status.md in the "Docs by Area" table so it is discoverable at the start of any session.
- The file is updated whenever a subsystem transitions from planned to built (or is descoped).
Starting points
/docs/architecture/tasks.md — contains inline "not yet built" notices representative of the gap
/docs/decisions/005-agents-and-prompts.md — references the unbuilt agents/ crate
/CLAUDE.md — "Docs by Area" table is where docs/status.md should be linked
QA plan
- Open
docs/status.md — expect a table or list covering every major subsystem mentioned across the architecture docs, each with a built or planned label and a link to its ADR or issue.
- Search
docs/architecture/ and docs/decisions/ for "not yet built" — expect every hit to correspond to a planned entry in docs/status.md.
- Open
CLAUDE.md "Docs by Area" table — expect a row for docs/status.md with a brief description.
- Confirm the file is accurate against the actual codebase: pick three
built entries and verify their corresponding source files exist; pick two planned entries and verify no corresponding source exists.
Done when
docs/status.md exists, covers all major subsystems with accurate built/planned markers, and is linked from CLAUDE.md.
Current state
An agent implementing a feature adjacent to dispatch, session tracking, or task fold-back reads architecture docs that describe a complete, coherent system. Those docs contain "not yet built" notices scattered across individual ADRs and architecture files — there is no single file that lists what actually exists today vs. what is described but unimplemented. The result: agents write code against integration points that don't exist, or skip implementing pieces that are already present.
Observable facts:
docs/architecture/tasks.md,docs/architecture/task-dispatch.md, and individual ADRs (005, 006, 009, 010, 012, 013, 014, 016, 017, 018) each contain their own "not yet built" or "not yet implemented" notices inline.docs/orCLAUDE.mdaggregates these into a cross-cutting built/planned inventory.CLAUDE.mdreferences theagents/Rust crate described in Decision 005 but notes it "has not been built yet" — this is representative of a pattern repeated across the docs with no single authoritative view.Ideal state
docs/status.mdfile exists and lists every major subsystem (dispatch, session tracking, task fold-back, mining loop, verdict signal, agents crate, etc.) with a binarybuilt/plannedmarker, a one-line description, and a link to the relevant ADR or issue.docs/status.mdand immediately knows which code paths are real and which are planned.CLAUDE.mdlinks todocs/status.mdin the "Docs by Area" table so it is discoverable at the start of any session.Starting points
/docs/architecture/tasks.md— contains inline "not yet built" notices representative of the gap/docs/decisions/005-agents-and-prompts.md— references the unbuiltagents/crate/CLAUDE.md— "Docs by Area" table is wheredocs/status.mdshould be linkedQA plan
docs/status.md— expect a table or list covering every major subsystem mentioned across the architecture docs, each with abuiltorplannedlabel and a link to its ADR or issue.docs/architecture/anddocs/decisions/for "not yet built" — expect every hit to correspond to aplannedentry indocs/status.md.CLAUDE.md"Docs by Area" table — expect a row fordocs/status.mdwith a brief description.builtentries and verify their corresponding source files exist; pick twoplannedentries and verify no corresponding source exists.Done when
docs/status.mdexists, covers all major subsystems with accurate built/planned markers, and is linked fromCLAUDE.md.