Three folders, one question each.
| Folder | Question it answers |
|---|---|
design/ |
What should the product be? |
implementation/ |
What is built, and what is left? |
conformance/ |
Does it actually do what the protocol says? |
| File | What it is |
|---|---|
capture-companion-requirements.md |
The PRD. 173 numbered requirements, the scope line, the use cases, the open decisions. The primary artefact — everything else refers back to it |
capability-spike.md |
What the hardware and iOS will actually do, and the parameter set the build is driven from. Every figure carries its provenance, and most are assumed rather than measured |
mockup v1/README.md |
The design handoff. 17 screens, design tokens, copy treated as decisions, and the state semantics each screen encodes |
mockup v1/design/ |
The design reference as HTML — a prototype of look, copy and behaviour. Not production code; none of it is to be ported |
mockup v1/screens/ |
1× board captures of the screens, in flow order |
| File | What it is |
|---|---|
delivery-scope.md |
The scope document. An audit of the current build by architectural layer, then sixteen epics cut into fifty-two capability levels. This is what seeds the GitHub Project board |
traceability.md |
The traceability matrix. Every PRD requirement to its status, owning epic and level, and the evidence — plus a reverse index from level to the requirements it closes |
mvp-online.md |
The delivery plan. ⚠ The only document that answers what is being built next, and in what order — the scope document is organised by capability level, which is the wrong axis for that question. Carries the online MVP's four requirements, the RV-6 work that gates them across three repositories, and the demo that says it is done |
backlog.py |
The board's source. Generates the issue manifest behind the GitHub project — 91 issues and 16 labels. Edit it when a capability level changes in delivery-scope.md, so the board and the document cannot drift |
| File | What it is |
|---|---|
ppcp-conformance.md |
The conformance claim against PPCP-CONF. 47 rows, the findings raised against the specification, the interoperability runs, and an explicit list of what is deferred and on what |
ppcp-conform.{json,md} |
The conformance tool's own output, regenerated by make conform. Generated — do not hand-edit |
interop-*.json |
Run summaries from make interop and make conform-iop. Generated |
bundles/ |
Session bundles written by this implementation and by others, checked in as interoperability evidence |
New to the project: the PRD's §1–§4, then the design handoff, then delivery-scope.md §1.
Picking up work: mvp-online.md for what is next and why, then delivery-scope.md §3 for the epic, traceability.md for the requirements it closes, then the PRD for what those requirements actually say.
Wondering whether something is done: traceability.md. It is the only document that answers that question row by row, and its statuses are checked against the tree rather than against intent.
delivery-scope.md and traceability.md are audits, not plans — they go stale the moment code lands. mvp-online.md is a plan and goes stale differently: it is wrong when the order changes, not when code lands. Re-check them when a capability level closes. The PRD's §18 summarises their position and should be re-checked at the same time.
When a capability level is added, split or reworded, change delivery-scope.md and backlog.py together. The script asserts its own counts, which is what caught a fifty-one-versus-fifty-two disagreement between them the first time round.
The conformance folder is different: ppcp-conformance.md is hand-written and ppcp-conform.* are generated, so a disagreement between them is a real signal rather than drift to be tidied away.