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.