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 fd8c51ec..fbf1c05a 100644 --- a/docs/plans/2026-08-20_w4-document-contract-worklist.md +++ b/docs/plans/2026-08-20_w4-document-contract-worklist.md @@ -175,3 +175,97 @@ proposes work not yet built). Those eight are stamped and are the most likely to `kind: record` on a file stamped `guide` fails). - The whole diff removes 4 lines, all of them `status: current`. - 24 files untouched, matching 19 + 3 + 1 + 1. + +## Response to the W5 adversarial pass + +vision ran a refute-first pass on this branch at `37cd00e` from a fresh worktree. Three of its +points changed the branch. Everything is re-measured here before being acted on; where my +measurement disagrees with its stated evidence I say so. + +### 1. `docs/fleet/NORTH_STAR.md` stamp reverted (`bea47543`) + +vision raised this as **latent** and scoped to the flatten PR. It is **live in this PR**, so it +could not wait. + +`fleet-north-star.spec.ts:110-114` is a drift test that reads the committed file from disk and +asserts full-string equality against `renderNorthStarMarkdown()`, whose first emitted line is the +H1 and which emits no front matter. Stamping changed line 1 from the H1 to `---`. + +CI 2589 confirms it directly, no longer by construction: + +``` +× renderNorthStarMarkdown > matches the committed NORTH_STAR.md projection (regenerate if this fails) + → expected '# Mosaic Fleet — NORTH STAR\n\n> **Ge…' to be '---\nkind: projection\nstatus: active…' +``` + +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, so the diff command does report differences. + +The consequence is a contract-level one, recorded in the worklist: **the contract as written +cannot classify any generated document without a matching change to its generator.** A `projection` +is "Generated. Never hand-edited," so its header has to come out of the renderer. That is a code +change and belongs in the flatten PR beside the `resolveNorthStarPaths()` fix. vision's +recommendation, and I agree with it. + +Counts: stamped 104 → **103**. Untouched 23 → **24**. + +### 2. The `docs/` qualifier (vision's C1) + +Stated as asked. **"127 live documentation files" is true for `docs/` only.** Definition: all +`*.md` under `docs/`, minus `docs/archive/` and `docs/_old_structure/`. 318 total = 134 archive + +57 `_old_structure` + 127 live. + +Repo-wide the phrase undercounts: 21 live markdown files sit outside `docs/` and outside any named +exclusion (17 under `guides/`, plus `README.md`, `AGENTS.md`, `CLAUDE.md`, `REPORT-A1207.md` at +root). This PR does not stamp them and does not claim to. + +### 3. `format` failure, and what it says about the header (`8a55c041`) + +CI 2589 also failed `prettier --check` on **exactly one file**: the plan document I hand-wrote. +Reproduced locally, rc=1, same single file. Fixed; the diff is 31 lines in, 31 out, all table +column padding. + +Worth stating for the review rather than burying: **the other 103 stamped documents pass +`prettier --check` unchanged.** The `---\nkind:\nstatus:\n---` block is prettier-clean as applied. +The formatting failure was in my prose, not in the contract header. + +### 4. R1: the evidence inverts, the finding gets stronger + +vision asks for a `kind` change on `docs/DEVELOPER-GUIDE/architecture/channel-protocol.md`, on the +grounds that it "carries 7 normative MUSTs" while the contract says `guide` "decides nothing." + +**The MUST count does not hold.** Uppercase RFC2119 terms (`MUST`, `MUST NOT`, `SHOULD`, +`SHOULD NOT`, `SHALL`, `MAY`, `REQUIRED`) in that file: **0 lines**. Control: the identical grep +returns 25 lines in `docs/requirements/native-kanban-sot.md`, so it finds them where they exist. +The seven lowercase "must" occurrences all _disclaim_ authority rather than assert it: "must not be +used as instructions", "must not be treated as current behavior", "must remain planned work", "must +first specify", "before it can become architecture guidance." The file's own banner reads "it is +not a runtime registry, an API contract, a requirements document." + +**The citation half holds, and is larger than stated.** vision's line numbers are exact. I +restated them earlier with wrong directories, which is worth naming because it is the same method +failure fred and I already wrote up as C3 in the flatten plan: I matched on basename and assumed +the path. The real ones, plus the two vision did not list: + +| citing document | line | words used | +| ------------------------------------------------------- | ---- | --------------------------------------------------- | +| `docs/ADMIN-GUIDE/security/discord-ingress.md` | 141 | "**canonical** shared-contract and parity boundary" | +| `docs/DEVELOPER-GUIDE/integrations/channel-adapters.md` | 28 | "The **canonical** architecture summary is" | +| `docs/DEVELOPER-GUIDE/integrations/channel-adapters.md` | 183 | "**Canonical** channel protocol architecture" | +| `docs/USER-GUIDE/workflows/discord-conversations.md` | 127 | "current shared types ... explicit parity boundary" | +| `docs/SITEMAP.md` | 54 | index entry | +| `docs/DEVELOPER-GUIDE/architecture/README.md` | 18 | index entry | + +So the tension is real. Three live documents outside the two indexes cite it, across four +citations, and three of those four use the word "canonical" for a document that spends its own +banner denying it is canonical. **It is just not a MUST problem, and that +changes what the fix is.** If the file is telling the truth about itself, the three "canonical" +citations are wrong and the edit belongs in those three files, not in this one's `kind`. + +**Left as `kind: guide` in this PR and flagged for the reviewer's call.** Restamping on evidence +that inverts on reading would be worse than leaving it stamped and named. + +### Unchanged + +vision's C2 (no consumer), C4 (holding `parent` blocks nothing) and C5 (a front-mattered `.yaml` +throws in `YAML.parse`) all reverified. C1's arithmetic closes at the stated ref.