From bea47543f3aeb3c139fff6c423a62b52d0f06482 Mon Sep 17 00:00:00 2001 From: veronica Date: Thu, 20 Aug 2026 19:46:24 -0500 Subject: [PATCH] docs(W4): revert the NORTH_STAR.md stamp; a projection cannot carry a hand-added header 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. --- docs/fleet/NORTH_STAR.md | 5 --- ...026-08-20_w4-document-contract-worklist.md | 33 ++++++++++++++++--- 2 files changed, 29 insertions(+), 9 deletions(-) diff --git a/docs/fleet/NORTH_STAR.md b/docs/fleet/NORTH_STAR.md index 61ef4ce4..ba066838 100644 --- a/docs/fleet/NORTH_STAR.md +++ b/docs/fleet/NORTH_STAR.md @@ -1,8 +1,3 @@ ---- -kind: projection -status: active ---- - # Mosaic Fleet — NORTH STAR > **Generated file — do not edit by hand.** diff --git a/docs/plans/2026-08-20_w4-document-contract-worklist.md b/docs/plans/2026-08-20_w4-document-contract-worklist.md index eb34f746..d59b5e75 100644 --- a/docs/plans/2026-08-20_w4-document-contract-worklist.md +++ b/docs/plans/2026-08-20_w4-document-contract-worklist.md @@ -21,12 +21,13 @@ files. The flatten plan says 130; the arithmetic does not close (318 total = 134 | bucket | count | note | | --- | --- | --- | -| stamped `kind` + `status: active` | 104 | this pass | +| stamped `kind` + `status: active` | 103 | this pass | | held, operator judgement | 19 | section "Needs a decision" below | | held, cites the moving path | 3 | the three `SUPERSEDED` TASKS.md stamps | +| held, generated file | 1 | `docs/fleet/NORTH_STAR.md`, see below | | already stamped in W1 | 1 | `docs/fleet/FLEET-DOCTRINE.md`, untouched | -Kinds applied: 54 `guide`, 34 `record`, 9 `spec`, 6 `tracking`, 1 `projection`. +Kinds applied: 54 `guide`, 34 `record`, 9 `spec`, 6 `tracking`. `parent` is **not** applied. It points at `docs/fleet/NORTH_STAR.yaml`, which the flatten moves to `docs/NORTH_STAR.yaml`. Stamping it now means re-pointing 127 files by hand later. It lands @@ -50,6 +51,30 @@ Two problems, both real: Converted after the flatten, not before. +## Held: the one generated file + +`docs/fleet/NORTH_STAR.md` is a `projection` and was stamped in the first pass. The stamp was +**reverted before review**, because stamping it is self-contradictory in a way that is not +merely theoretical: + +- The contract says a `projection` is "Generated. Never hand-edited." Adding front matter by + hand is a hand edit of a generated file, and the file's own banner says + "**Generated file — do not edit by hand.**" +- `renderNorthStarMarkdown()` at `packages/mosaic/src/commands/fleet.ts:373` emits the H1 as + its first line and no front matter at all. +- `fleet-north-star.spec.ts:110-114` asserts full-string equality between the renderer's output + and the committed file: `expect(rendered).toBe(committed)`. Before the stamp, line 1 of the + committed file was `# Mosaic Fleet — NORTH STAR`, matching the renderer. After it, line 1 was + `---`. The assertion fails. + +So the header for a projection cannot live in the file. It has to be emitted by +`renderNorthStarMarkdown()`, which is a code change and belongs in the flatten PR alongside the +`resolveNorthStarPaths()` fix, not in a documentation pass. + +This generalises: **the contract as written cannot classify any generated document without a +matching change to its generator.** `NORTH_STAR.md` is the only projection today, so the cost +is one function. It will not stay one. + ## Needs a decision Nineteen rows. Seventeen are the plan's section 9 list, minus `docs/fleet/north-star.md` @@ -145,8 +170,8 @@ proposes work not yet built). Those eight are stamped and are the most likely to ## Verification -- 104 of 104 files parse with the expected `kind` and `status` in front matter. +- 103 of 103 files parse with the expected `kind` and `status` in front matter. - The check was shown to reject a wrong kind before it was trusted (asserting `kind: record` on a file stamped `guide` fails). - The whole diff removes 4 lines, all of them `status: current`. -- 23 files untouched, matching 19 + 3 + 1. +- 24 files untouched, matching 19 + 3 + 1 + 1.