docs(W4): document contract — stamp kind and status on 104 live docs #1350

Merged
fred merged 10 commits from docs/w4-document-contract into next 2026-08-21 14:07:37 +00:00
2 changed files with 31 additions and 1 deletions
Showing only changes of commit 94a7d5b692 - Show all commits
@@ -324,3 +324,31 @@ contract". The reason this is not applied unilaterally: it decides which documen
other when `docs/README.md` and `docs/plans/2026-08-20_stack-docs-flatten-and-alignment.md` disagree
about the contract, and they already differ (the plan's enum has 7 values, the README's now has 6).
That is an authority question, not a classification one.
## The old schema DID have a consumer, and CI found it
vision's C2 concluded "no consumer found" after searching by parsing primitive rather than by key
name. fred's decision A rested on "no installed base to protect." I accepted both. **All three of
us were wrong, and the full test suite is what proved it.**
`packages/mosaic/src/installation-documentation.spec.ts:39` asserted:
```ts
expect(markdown).toMatch(/^---\n[\s\S]*?\nstatus: current\n[\s\S]*?\n---\n/);
```
That is a raw regex over the markdown text, not a front-matter parse and not a key lookup, which is
exactly why a search organised around parsing primitives could not see it. It pins
`docs/USER-GUIDE/getting-started/quickstart.md` to the old vocabulary. Replacing `status: current`
with `status: active` turned it red.
Updated to `status: active`, the contract's value for "in force", with the reason in a comment
beside it. Verified by evaluating both regexes against the real file: old `false`, new `true`.
Control: a page carrying `superseded-by` still fails the new regex, so the assertion still asserts
something rather than matching anything with front matter.
**The method point, which outlives this file.** CI 2592 ran 1617 tests against the stamped tree: 1
failed, 1616 passed. That is a stronger consumer search than any grep the three of us ran, because
it does not depend on guessing how a consumer reads the file. **Run the suite before concluding a
documentation change has no code consumers.** Two independent seats and a reviewer searching by
hand missed the one that existed.
@@ -36,7 +36,9 @@ describe('current installation documentation safety', (): void => {
async (relativePath): Promise<void> => {
const markdown = await readFile(resolve(repositoryRoot, relativePath), 'utf8');
expect(markdown).toMatch(/^---\n[\s\S]*?\nstatus: current\n[\s\S]*?\n---\n/);
// `status: active` is the document contract's value for "in force"; it replaced the
// old `status: current` when the contract in docs/README.md became the single schema.
expect(markdown).toMatch(/^---\n[\s\S]*?\nstatus: active\n[\s\S]*?\n---\n/);
expect(unsafeRemoteExecutionFindings(markdown)).toEqual([]);
},
);