The Applied table carried 107 stamped and 17 held, the counts from the first
pass, with nothing telling a reader they had moved. The re-closed arithmetic at
the end of the document was already correct, so the document was not wrong
overall, but a reader hitting the table got a stale count with no forward
pointer. In this PR specifically that is the defect the PR exists to remove,
appearing in the PR's own worklist.
The first-pass numbers are left standing and labelled rather than overwritten,
matching every other correction in this document: a record of what a pass
produced is worth more than a number silently updated to still look right. The
current census follows it, re-measured: 108 stamped + 16 + 3 + 1 = 128, kinds 54
guide / 34 record / 13 spec / 7 tracking, status 106 active / 2 completed, and
the two files carrying source_of_truth: true named.
The paragraph arguing 'run the suite before concluding a docs change has no code
consumers' carried a number: 'CI 2592 ran 1617 tests, 1 failed, 1616 passed'.
That number is wrong and is withdrawn in place rather than deleted.
Extracting per-test totals from these pipeline logs is not a reliable method:
the same regex over the same log format returns 1003 for 2592, 1022 for 2593
and 3471 for 2594, which are runs of the same suite. Three irreconcilable
answers from one method is proof the method does not measure what it claims,
so no corrected count is substituted.
The claim is restated in what the log carries reliably, the named FAIL list and
the turbo task line. The count was decoration on a claim already carried by a
specific name: one named failing spec is what refuted three hand-searches.
fred withdrew decision F after re-measuring channel-protocol.md with a control:
zero uppercase RFC2119 terms, seven lowercase 'must' all disclaiming authority,
under a banner refusing requirements status. F rested on 'the doc graph outranks
the page's own banner', which contradicts decision D, 'kind follows content'.
D is the rule; F was its counterexample. Neither rescue (vision's adjective edit
on the citing docs, or a banner edit) was taken: a kind that survives only by
editing the evidence around it is not a classification.
Q1 answered: docs/README.md prescribes the contract, so by D its content is a
spec, and by B it is the source of truth for that contract. A plan never
outranks the artifact it planned, so the flatten plan's stale 7-value enum is
corrected there rather than competing here.
128 live docs = 108 stamped + 16 operator-held + 3 supersede deferrals + 1 generated.
CI 2592 proved the old front-matter schema HAD a consumer. vision's C2 concluded "no consumer
found", fred's decision A rested on "no installed base to protect", and I accepted both. All three
of us were wrong.
installation-documentation.spec.ts:39 asserted a raw regex over the markdown text:
expect(markdown).toMatch(/^---\n[\s\S]*?\nstatus: current\n[\s\S]*?\n---\n/);
Not a front-matter parse and not a key lookup, which is why a search organised around parsing
primitives could not see it. Stamping docs/USER-GUIDE/getting-started/quickstart.md replaced
`status: current` with `status: active` and turned it red.
Updated to the contract's vocabulary, intent unchanged: the page must still declare itself in
force, and must still teach no curl-pipe-to-shell install. 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.
2592 also confirms the NORTH_STAR revert took: the north-star drift test is green, `format` and
`lint` are green, and this was the only failure in 1617 tests.
Method point worth keeping: the full suite is a stronger consumer search than any grep, because it
does not depend on guessing how a consumer reads the file.
A - docs/README.md:149-190 rewritten. It prescribed a competing front-matter schema
(title/type/audience/status/source_of_truth) adopted by 4 of 128 live documents. Two
documented conventions in one repo is the defect this pass removes, so the README now
documents the contract and the 4 files convert in the same commit: `type` dropped
(kind replaces it), `title`/`audience`/`source_of_truth` kept.
B - source-of-truth leaves the kind enum, which is now 6 values, and returns as an orthogonal
boolean. kind was carrying two independent facts. docs/requirements/native-kanban-sot.md
is stamped `kind: spec` + `source_of_truth: true`, which is what it always was.
C - status gains `completed`. Applied to the two executed plans, on artifact evidence rather
than on their own say-so: --purpose push|merge ships in ci-queue-wait.sh, and every section
the README plan specifies exists in docs/README.md today.
D - kind follows content, never filename. docs/native-kanban-sot/TASKS.md is `kind: spec`
because its body says "a build plan, not a task tracker". The name stays wrong; that is a
rename and it is out of scope here.
E - the contract covers .md only, written into the README as a decision with vision's
YAML.parse measurement as the reason, so the omission does not read as an oversight.
F - channel-protocol.md guide -> spec. Applied, with a correction the reviewer should see: the
ruling cites "7 normative MUSTs" and there are ZERO uppercase RFC2119 terms in that file.
Control: the identical grep returns 25 lines in docs/requirements/native-kanban-sot.md. The
citation half of the finding does hold and is larger than stated. Consequence recorded in
the worklist: the file's own banner now contradicts its header.
Verified: 128 live .md under docs/ (127 baseline + this PR's worklist), 107 stamped, 0 invalid
kinds, 17 operator-held + 3 supersede-stamp deferrals + 1 generated = 21 unstamped. 107+21=128.
Control: the verifier reports valid=False when a kind is corrupted to `nonsense`, so the
0-invalid result is a real result. prettier --check clean across docs/.
pr-review.sh -n 1350 -a comment fails with HTTP 401 'invalid username, password or token'.
Measured cause with a control: veronica's seat token returns 200 on /api/v1/user and the shared
broker credential gitea-mosaicstack returns 401 on the same endpoint. The wrapper logic is fine,
the credential it is handed is dead, so the PR wrappers are down for every seat on this host.
MOSAIC_GIT_IDENTITY appears nowhere in credentials.sh, which is FD-9.
Constitution gate 8 makes that operation blocked, so the corrections land in the branch instead,
where they survive the PR anyway.
CI 2589 step `format` failed on exactly one file: this one, the plan document I hand-wrote.
prettier --check reproduces locally, rc=1, same single file.
That is worth stating for the review: the other 103 stamped documents pass
`prettier --check` unchanged, so the `---\nkind:\nstatus:\n---` front matter block is
already prettier-clean. The formatting failure was in my prose, not in the contract header.
Diff is 31 lines in, 31 out, all table column padding. No content change.
Found by vision's adversarial pass (W5) and re-measured here. The finding was raised as
latent; it is live in this PR.
docs/fleet/NORTH_STAR.md is generated by renderNorthStarMarkdown()
(packages/mosaic/src/commands/fleet.ts:373), whose first emitted line is the H1 and which
emits no front matter at all. fleet-north-star.spec.ts:110-114 is a drift test that reads
the committed file from disk and asserts full-string equality against the renderer output:
expect(rendered).toBe(committed);
Stamping the file changed line 1 from '# Mosaic Fleet - NORTH STAR' to '---', so the
assertion fails. vitest could not be run in this worktree (node_modules empty, 'Cannot find
package yaml'), which is a harness gap and not a test result, so this is shown by
construction: the assertion above, the renderer's first lines.push, and line 1 before
versus after.
Reverted to origin/next verbatim: git diff origin/next -- docs/fleet/NORTH_STAR.md is 0
lines. Control on docs/fleet/reference/cli.md returns 13 lines, so the diff command does
report differences when they exist.
The header for a projection has to come from the renderer, not the file. That is a code
change and belongs in the flatten PR beside the resolveNorthStarPaths() fix.
Stamped count 104 -> 103. Untouched 23 -> 24. Worklist records it as a fourth held row.
Records what the stamping pass applied, what it held and why, and the two
places where the contract contradicts itself or the repository:
- docs/native-kanban-sot/TASKS.md declares itself a build plan; the contract
says TASKS.md is tracking and never a spec.
- docs/requirements/native-kanban-sot.md is hand-authored prose canon; plan
section 5.2 calls that source-of-truth, the contract table requires
source-of-truth to be machine-readable.
- docs/README.md already documents a competing front-matter convention on a
colliding status key, applied to 4 files, with no code consumer.
- The contract has no defined form for a .yaml document, including
docs/fleet/NORTH_STAR.yaml itself.
Applies the document contract from
docs/plans/2026-08-20_stack-docs-flatten-and-alignment.md section 3, partially:
`kind` and `status` only. `parent` is deliberately held until the flatten in
section 4 lands, so that 127 documents do not have to be re-pointed by hand
when docs/fleet/NORTH_STAR.yaml moves to docs/NORTH_STAR.yaml.
Scope, measured on origin/next at 63069149:
127 live docs = all *.md under docs/ minus docs/archive/ minus docs/_old_structure/
104 stamped here
19 held operator judgement (plan section 9), worklist in the same PR
3 held the SUPERSEDED TASKS.md stamps, which cite the moving path
1 untouched docs/fleet/FLEET-DOCTRINE.md, already stamped in W1
Kinds applied: 54 guide, 34 record, 9 spec, 6 tracking, 1 projection.
Every row carries a confidence and a one-line rationale in the worklist.
Two collisions with the existing state, both flagged rather than resolved:
1. docs/README.md:150-160 already documents a front-matter convention
(title/type/audience/status/source_of_truth) with its own allowed values.
It is applied to 4 of 127 files. Its `status` vocabulary is
current|draft|deprecated|historical; the new contract's is active|superseded-by.
The key collides. This commit lets the new contract win and rewrites
`status: current` to `status: active` on those 4 files, keeping their other
legacy keys untouched. No code reads any of them: `git grep source_of_truth`
outside docs/ returns nothing. docs/README.md still prescribes the old
convention and is an operator row, so it is not edited here.
2. Two of the plan's 20 operator rows are YAML files, not markdown
(docs/fleet/examples/roster-v2.yaml, docs/openapi-tess.yaml), and the
contract's front-matter form has no defined meaning for a .yaml document.
That gap also applies to docs/fleet/NORTH_STAR.yaml, the source of truth
itself. Raised in the worklist.
A third row from the plan, docs/fleet/north-star.md, no longer exists: W1
renamed it to docs/fleet/FLEET-DOCTRINE.md.
Verification: 104/104 parse with the expected kind and status in front matter;
the check was shown to reject a wrong kind before it was trusted. The diff
removes 4 lines total, all of them `status: current`.
Docs-only plan PR. FRED_APPROVED_REF=0629361ca39a4dd7fb3e575d11c64bea9e545dae (review 147). Merged by fred (orchestrator) via API: pr-merge.sh policy predates the next lane (main-only hardcode) — wrapper fix tracked separately.
Co-authored-by: Velma <[email protected]>
veronica
mos-dt-0
velmaandmos-dt-0
jason.woltje
jarvis