I0830 — docs/PERFORMANCE.md, README, CONTRIBUTING and CLI reference
Write the reference: goals, phases and counters, batch reads, the flatten cache, cold versus warm, result and baseline schemas, the policy block, the regression workflow, the contributor workflow and the limitations; add the README section and the bench section of docs/CLI.md.
DONE wave 5 · p0 · implementation profile · runs alone
Part of M004 — Performance is executable evidence, and the hot path does no canonical work twice.
Objective
Write the reference: goals, phases and counters, batch reads, the flatten cache, cold versus warm, result and baseline schemas, the policy block, the regression workflow, the contributor workflow and the limitations; add the README section and the bench section of docs/CLI.md.
Why
The workflow must be discoverable from the root, and documentation may claim only what a case proves.
Current state
Nothing documents performance.
Desired state
One reference document, a short README section pointing at it, a CONTRIBUTING entry, and a CLI section generated into the site like every command.
Scope
- docs/PERFORMANCE.md
- README.md
- CONTRIBUTING.md
- docs/CLI.md
- docs/README.md
- site/data/generated
Out of scope
- Numbers in prose
Dependencies
- I0823DONE majordomus bench: targets derived from the command registry
- I0826DONE bench --check refuses a regression by policy
- I0829DONE Performance doctrine as project rules
What waits on this
Acceptance criteria
- Every command in the README works as written
- generate-site-data --check is in sync
- No count in prose, by project.no-counts-in-prose
Validation
- scripts/generate-site-data --check
Evidence required
- docs_integrated
Evidence
| covers | type | command | result | at commit |
|---|---|---|---|---|
| docs_integrated | test | scripts/generate-site-data --check | docs/PERFORMANCE.md explains MJ_TIMING, the shape of every fix, bench with cold and warm kept apart, run versus baseline versus check, the budgets, the policy block and how to work on performance, with no observed number in prose; README gains the bench row and a pointer to the document, CONTRIBUTING the performance step, docs/README.md the row, docs/CLI.md the bench section and docs/SCHEMAS.md the run and baseline schemas; every command written in the document is one the fixture or a case executes; generate-site-data --check is in sync after regeneration | next |
Risk
The measured values belong in the baseline file and the benchmark history, not in prose that goes stale.
Timeline
- started
- 2026-09-05T03:47:33Z
- verified
- 2026-09-05T03:47:33Z
- completed
- 2026-09-05T03:47:33Z
Those three fields, the evidence above and the state of the dependencies are all the status is made of. There is no status field to disagree with them.
Canonical record: .ai/repo/project/issues/I0830.yaml. Read it back with majordomus plan show I0830.