Context
docs/INTEGRITY-AUDIT.md D-04 flags the root README.md status table as stale, and docs/README.md carries "Whether root README Track 2/3 lines will be updated outside this PR" as an open question. Both are still true.
The README currently says:
| Track |
Question |
Status |
| Track 1 |
Do compiled trajectories survive site churn? |
Harness in progress — no gate number yet |
| Track 2 |
Is there a vertical where the counterparty hypothesis holds? |
Search in progress |
| Track 3 |
Narrative / pitch |
Placeholders only until Track 1 + 2 land |
Track 2 is not "search in progress" — it is FAIL, adjudicated in docs/research/vertical-search/DECISION.md and accepted as ADR-0004. Track 3 is not "placeholders only" — the Wave-1 pitch pack landed in docs/pitch/ and was refreshed for C5.
The README is the first thing a reader or a new agent sees, and it currently misdescribes the single most important fact about the project's state.
What to change in README.md
- Status table. Track 2 becomes
FAIL — no vertical locked, linking docs/research/vertical-search/DECISION.md and ADR-0004. Track 3 becomes Wave-1 draft; all performance claims [PENDING TRACK-1], linking docs/pitch/. Track 1 stays honest: harness in progress, no gate number yet.
- Add one line under the table making the dependency explicit: two consecutive vertical FAILs (Week-0 observability, Track-2 counterparty) mean the company now rests on the Track-1 mechanism number. Cite
docs/README-narrative.md section 6.
- Privacy section — already done, do not undo. This was resolved separately: the section is now "Public repo — write accordingly" and cites ADR-0005, which supersedes ADR-0002 and records the repo as public by decision. Leave it as it stands — the secret-hygiene rules in it are load-bearing and must not be softened.
- Layout section. Add
scripts/, tests/, artifacts/, and point at docs/ROADMAP.md and docs/DEVELOPMENT.md.
- Quick start. Describe
npm run ci as the one command that must be green before any PR.
Constraints
- No new metrics, no gate number, no percentages. If a claim cannot cite an in-repo artifact, delete the claim.
- Keep it short. The README is a signpost;
docs/README-narrative.md is the 20-minute read.
How to test
npm run lint:docs # once the docs-lint issue lands
npm run ci
Click every link on the rendered PR diff. A dead link here is worse than a stale sentence.
Before you open the PR
Context
docs/INTEGRITY-AUDIT.mdD-04 flags the rootREADME.mdstatus table as stale, anddocs/README.mdcarries "Whether root README Track 2/3 lines will be updated outside this PR" as an open question. Both are still true.The README currently says:
Track 2 is not "search in progress" — it is FAIL, adjudicated in
docs/research/vertical-search/DECISION.mdand accepted as ADR-0004. Track 3 is not "placeholders only" — the Wave-1 pitch pack landed indocs/pitch/and was refreshed for C5.The README is the first thing a reader or a new agent sees, and it currently misdescribes the single most important fact about the project's state.
What to change in
README.mdFAIL — no vertical locked, linkingdocs/research/vertical-search/DECISION.mdand ADR-0004. Track 3 becomesWave-1 draft; all performance claims [PENDING TRACK-1], linkingdocs/pitch/. Track 1 stays honest: harness in progress, no gate number yet.docs/README-narrative.mdsection 6.scripts/,tests/,artifacts/, and point atdocs/ROADMAP.mdanddocs/DEVELOPMENT.md.npm run cias the one command that must be green before any PR.Constraints
docs/README-narrative.mdis the 20-minute read.How to test
npm run lint:docs # once the docs-lint issue lands npm run ciClick every link on the rendered PR diff. A dead link here is worse than a stale sentence.
Before you open the PR
docs/README.md"Start here" row for the root README updated with a new Last-true datetrack3/d2-readme-status