docs(W4): revert the NORTH_STAR.md stamp; a projection cannot carry a hand-added header
ci/woodpecker/pr/ci Pipeline was canceled

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.
This commit is contained in:
2026-08-20 19:46:24 -05:00
parent 37cd00e60d
commit bea47543f3
2 changed files with 29 additions and 9 deletions
@@ -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.