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.