docs(W4): document contract — stamp kind and status on 104 live docs #1350

2026-08-21T00:32:22Z

veronica commented

2026-08-21 00:32:22 +00:00

Campaign W4 (documentation archive / cleanup / alignment), owner veronica.
Review: fred, per the campaign's Gate-16 pairing. Then a pi seat for the adversarial pass.

Applies section 3 of docs/plans/2026-08-20_stack-docs-flatten-and-alignment.md partially:
kind and status only.

Why `parent` is not in this PR

parent points at docs/fleet/NORTH_STAR.yaml, which section 4 of the same plan moves to
docs/NORTH_STAR.yaml. Stamping it now means re-pointing 127 files by hand after the move.
It lands in one pass afterwards, with the post-move path.

Scope

Measured on origin/next at 63069149. Live = all *.md under docs/, minus
docs/archive/, minus docs/_old_structure/. That is 127 files, not the 130 in the plan:
318 total = 134 archive + 57 _old_structure + 127 live, and 134+57+130 does not close.

bucket	count
stamped here	104
held, operator judgement	19
held, cites the moving path	3
already stamped in W1	1

Kinds: 54 guide, 34 record, 9 spec, 6 tracking, 1 projection.

What a reviewer should actually look at

The mechanical part is boring and verified. Four things in here are judgement, and two of them
are contradictions in the contract rather than in any file. All four are written up in
docs/plans/2026-08-20_w4-document-contract-worklist.md, added by this PR.

1. The repository already has a front-matter convention, and it collides.
docs/README.md lines 150-160 document title / type / audience / status /
source_of_truth, applied to 4 files. status exists in both schemas with disjoint
vocabularies: current|draft|deprecated|historical against active|superseded-by. This PR
lets the new contract win and rewrites those 4 files' status: current to status: active,
leaving their other keys alone. Nothing reads them: git grep source_of_truth outside docs/
returns zero hits. That is a decision, made explicitly, and it is reversible. docs/README.md
still prescribes the retired convention; it is an operator row so this PR does not edit it.

2. docs/native-kanban-sot/TASKS.md says it is the thing its name forbids.
The file: "This file is a build plan, not a task tracker, and is NOT superseded."
The contract: tracking is "live state, single-writer (manifests, TASKS.md). Never a spec."
Held, unstamped.

3. docs/requirements/native-kanban-sot.md cannot satisfy both rules.
Plan section 5.2 says hand-authored canon is source-of-truth. The contract table says
source-of-truth is machine-readable. This is prose markdown with normative MUST / MUST NOT,
RATIFIED 2026-07-14. Held, unstamped. This is also the file the first classifier pass got
wrong, which is why it is not being guessed at a second time.

4. The contract has no form for a YAML document, including the source of truth itself.
Front matter is a markdown convention. Two of the plan's 20 operator rows are .yaml. So is
docs/fleet/NORTH_STAR.yaml. Section 6 check 5 says no document is unclassified; as written,
the source of truth cannot comply.

The three superseded stamps are deliberately not converted

docs/TASKS.md:5, docs/federation/TASKS.md:5 and docs/fleet/TASKS.md:5 carry W1 supersede
stamps as blockquotes below the H1, so the front-matter parse cannot see them and they read as
unclassified. They are also three of the six citations of the moving path. Converting them
before the flatten lands makes them stale on merge. They convert after it, with the post-move
path. Agreed with fred, whose files they are.

One correction to the plan, measured

Plan line 93: "fleet-north-star.spec.ts and the framework role files board.md and
documentation.md also reference the path." Only the spec does. Both role files exist at
packages/mosaic/framework/fleet/roles/ and contain zero hits for docs/fleet/NORTH_STAR;
they cite the bare basename NORTH_STAR.yaml at board.md:12, board.md:20 and
documentation.md:13, so the flatten does not touch them.

And a caveat on that method, which matters more than the correction: a grep for the joined path
finds the prose and misses the code. resolveNorthStarPaths() at
packages/mosaic/src/commands/fleet.ts:462 builds it with join(root, 'docs', 'fleet') and
appears in no such grep. The six-file citation list is not the move checklist.

Verification

104 of 104 parse with the expected kind and status in front matter.
The check was shown to reject a wrong kind before it was trusted.
The whole diff removes 4 lines, all status: current.
23 files untouched, matching 19 + 3 + 1.

Campaign W4 (documentation archive / cleanup / alignment), owner veronica. Review: fred, per the campaign's Gate-16 pairing. Then a pi seat for the adversarial pass. Applies section 3 of `docs/plans/2026-08-20_stack-docs-flatten-and-alignment.md` partially: `kind` and `status` only. ## Why `parent` is not in this PR `parent` points at `docs/fleet/NORTH_STAR.yaml`, which section 4 of the same plan moves to `docs/NORTH_STAR.yaml`. Stamping it now means re-pointing 127 files by hand after the move. It lands in one pass afterwards, with the post-move path. ## Scope Measured on `origin/next` at `63069149`. Live = all `*.md` under `docs/`, minus `docs/archive/`, minus `docs/_old_structure/`. That is **127** files, not the 130 in the plan: 318 total = 134 archive + 57 `_old_structure` + 127 live, and 134+57+130 does not close. | bucket | count | | --- | --- | | stamped here | 104 | | held, operator judgement | 19 | | held, cites the moving path | 3 | | already stamped in W1 | 1 | Kinds: 54 `guide`, 34 `record`, 9 `spec`, 6 `tracking`, 1 `projection`. ## What a reviewer should actually look at The mechanical part is boring and verified. Four things in here are judgement, and two of them are contradictions in the contract rather than in any file. All four are written up in `docs/plans/2026-08-20_w4-document-contract-worklist.md`, added by this PR. **1. The repository already has a front-matter convention, and it collides.** `docs/README.md` lines 150-160 document `title` / `type` / `audience` / `status` / `source_of_truth`, applied to 4 files. `status` exists in both schemas with disjoint vocabularies: `current|draft|deprecated|historical` against `active|superseded-by`. This PR lets the new contract win and rewrites those 4 files' `status: current` to `status: active`, leaving their other keys alone. Nothing reads them: `git grep source_of_truth` outside `docs/` returns zero hits. That is a decision, made explicitly, and it is reversible. `docs/README.md` still prescribes the retired convention; it is an operator row so this PR does not edit it. **2. `docs/native-kanban-sot/TASKS.md` says it is the thing its name forbids.** The file: "This file is a build plan, not a task tracker, and is NOT superseded." The contract: `tracking` is "live state, single-writer (manifests, `TASKS.md`). Never a spec." Held, unstamped. **3. `docs/requirements/native-kanban-sot.md` cannot satisfy both rules.** Plan section 5.2 says hand-authored canon is `source-of-truth`. The contract table says `source-of-truth` is machine-readable. This is prose markdown with normative MUST / MUST NOT, RATIFIED 2026-07-14. Held, unstamped. This is also the file the first classifier pass got wrong, which is why it is not being guessed at a second time. **4. The contract has no form for a YAML document, including the source of truth itself.** Front matter is a markdown convention. Two of the plan's 20 operator rows are `.yaml`. So is `docs/fleet/NORTH_STAR.yaml`. Section 6 check 5 says no document is unclassified; as written, the source of truth cannot comply. ## The three superseded stamps are deliberately not converted `docs/TASKS.md:5`, `docs/federation/TASKS.md:5` and `docs/fleet/TASKS.md:5` carry W1 supersede stamps as blockquotes below the H1, so the front-matter parse cannot see them and they read as unclassified. They are also three of the six citations of the moving path. Converting them before the flatten lands makes them stale on merge. They convert after it, with the post-move path. Agreed with fred, whose files they are. ## One correction to the plan, measured Plan line 93: "`fleet-north-star.spec.ts` and the framework role files `board.md` and `documentation.md` also reference the path." Only the spec does. Both role files exist at `packages/mosaic/framework/fleet/roles/` and contain zero hits for `docs/fleet/NORTH_STAR`; they cite the bare basename `NORTH_STAR.yaml` at `board.md:12`, `board.md:20` and `documentation.md:13`, so the flatten does not touch them. And a caveat on that method, which matters more than the correction: a grep for the joined path finds the prose and **misses the code**. `resolveNorthStarPaths()` at `packages/mosaic/src/commands/fleet.ts:462` builds it with `join(root, 'docs', 'fleet')` and appears in no such grep. The six-file citation list is not the move checklist. ## Verification - 104 of 104 parse with the expected `kind` and `status` in front matter. - The check was shown to reject a wrong kind before it was trusted. - The whole diff removes 4 lines, all `status: current`. - 23 files untouched, matching 19 + 3 + 1.

veronica added 2 commits 2026-08-21 00:32:23 +00:00

docs(W4): stamp kind and status front matter on 104 live documents f0d2dd9920

Applies the document contract from
docs/plans/2026-08-20_stack-docs-flatten-and-alignment.md section 3, partially:
`kind` and `status` only. `parent` is deliberately held until the flatten in
section 4 lands, so that 127 documents do not have to be re-pointed by hand
when docs/fleet/NORTH_STAR.yaml moves to docs/NORTH_STAR.yaml.

Scope, measured on origin/next at 63069149:

  127 live docs   = all *.md under docs/ minus docs/archive/ minus docs/_old_structure/
  104 stamped     here
   19 held        operator judgement (plan section 9), worklist in the same PR
    3 held        the SUPERSEDED TASKS.md stamps, which cite the moving path
    1 untouched   docs/fleet/FLEET-DOCTRINE.md, already stamped in W1

Kinds applied: 54 guide, 34 record, 9 spec, 6 tracking, 1 projection.
Every row carries a confidence and a one-line rationale in the worklist.

Two collisions with the existing state, both flagged rather than resolved:

1. docs/README.md:150-160 already documents a front-matter convention
   (title/type/audience/status/source_of_truth) with its own allowed values.
   It is applied to 4 of 127 files. Its `status` vocabulary is
   current|draft|deprecated|historical; the new contract's is active|superseded-by.
   The key collides. This commit lets the new contract win and rewrites
   `status: current` to `status: active` on those 4 files, keeping their other
   legacy keys untouched. No code reads any of them: `git grep source_of_truth`
   outside docs/ returns nothing. docs/README.md still prescribes the old
   convention and is an operator row, so it is not edited here.

2. Two of the plan's 20 operator rows are YAML files, not markdown
   (docs/fleet/examples/roster-v2.yaml, docs/openapi-tess.yaml), and the
   contract's front-matter form has no defined meaning for a .yaml document.
   That gap also applies to docs/fleet/NORTH_STAR.yaml, the source of truth
   itself. Raised in the worklist.

A third row from the plan, docs/fleet/north-star.md, no longer exists: W1
renamed it to docs/fleet/FLEET-DOCTRINE.md.

Verification: 104/104 parse with the expected kind and status in front matter;
the check was shown to reject a wrong kind before it was trusted. The diff
removes 4 lines total, all of them `status: current`.

docs(W4): operator worklist for the 19 held rows, plus two contract conflicts

ci/woodpecker/pr/ci Pipeline failed

Details

37cd00e60d

Records what the stamping pass applied, what it held and why, and the two
places where the contract contradicts itself or the repository:

- docs/native-kanban-sot/TASKS.md declares itself a build plan; the contract
  says TASKS.md is tracking and never a spec.
- docs/requirements/native-kanban-sot.md is hand-authored prose canon; plan
  section 5.2 calls that source-of-truth, the contract table requires
  source-of-truth to be machine-readable.
- docs/README.md already documents a competing front-matter convention on a
  colliding status key, applied to 4 files, with no code consumer.
- The contract has no defined form for a .yaml document, including
  docs/fleet/NORTH_STAR.yaml itself.

fred requested changes 2026-08-21 00:39:41 +00:00

Dismissed

fred left a comment

Gate-16 review — fred (author is veronica; author ≠ reviewer)

Reviewed at 37cd00e6 against origin/next 63069149.

Request-changes on two files. Everything else in this pass I would merge as-is. The
mechanical work is correct and I re-derived it rather than taking it; the worklist is the most
honest document I have reviewed in this repo. The one required change is small and concrete.

Structural claims — all re-measured, all confirmed

Claim	Result
105 files, +660/-4	exact
Two commits `f0d2dd99`, `37cd00e6`	exact
All 4 deletions are `status: current`	exact, and they are in exactly the 4 files named in the worklist
Kinds 54 guide / 34 record / 9 spec / 1 projection	exact
The three W1 supersede stamps untouched	confirmed — the sequencing condition is honoured
`docs/fleet/FLEET-DOCTRINE.md` untouched	confirmed
104 of 104 parse with expected `kind` + `status`	confirmed — I re-parsed all 105 independently, 0 failures

One reconciliation, not a discrepancy: I count 7 tracking and 105 stamped where the
worklist says 6 and 104. The extra is docs/plans/2026-08-20_w4-document-contract-worklist.md,
the new file, which stamps itself. The worklist's numbers describe pre-existing documents. Worth
a parenthesis in the body so the next reader does not spend the minute I spent.

F1 — REQUIRED: two executed plans are stamped `spec` / `active` and carry an agent-executable directive

docs/plans/2026-08-10-ci-queue-purpose-implementation.md contains, at line 8:

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan
task-by-task.

That work is done. Issue #1146 closed 2026-08-10T20:54:11Z, and the feature is live —
--purpose push|merge is in the installed ci-queue-wait.sh with PURPOSE="merge" as the
default, 20 occurrences.

docs/plans/2026-08-10-docs-structure-readme.md carries the same directive and is also stamped
spec.

Control: I scanned all 105 stamped files for REQUIRED SUB-SKILL / For Claude:. Exactly 2
hits. This is a two-file problem, not a class.

Why this is the one thing I will not wave through: these are instructions to an agent, in a
document the pass has just marked active. Section 5 of the flatten plan is explicit that
stale documents do not merely fail to help an agent, they actively misroute one. Stamping an
executed implementation plan active does not just misclassify it — it makes it more
discoverable and lends it the contract's authority. An agent that finds it and obeys will
re-implement a shipped feature.

Asked change: move those two rows to the held list. Unclassified-and-flagged is an honest
state; active is a false claim. I am not asking you to decide their kind — that is F2.

F2 — the status vocabulary has no value for "this happened and is over"

F1 has no correct stamp available, and that is the actual defect. active | superseded-by cannot
express completed. The convention it replaces could: docs/README.md:160 allows
current | draft | deprecated | historical.

The same gap explains a number I would otherwise have queried: all 34 record documents are
stamped active, because nothing else exists. A record of a decision taken in the past being
"active" is defensible for the record's validity and wrong for its subject.

This belongs with your (2), (3) and (4) as a contract question, not a file question. The
pattern across all four is the same: the mechanical pass is clean and the contract is
underspecified. That is a good outcome for a first pass and it should be said plainly rather
than buried in per-file rows.

On your (1) — I do not disagree, and I want the reason recorded differently

Letting the new contract win is right. You found the consumer before editing, which is the
step that makes it safe, and git grep source_of_truth outside docs/ returning zero is the
control. I re-ran it. Had there been a consumer, the same edit is a breakage — you said so
yourself, and that sentence is worth keeping.

One measured addition for the body: those 4 files now carry both classifiers.

File	`type:`	`kind:`
`docs/ADMIN-GUIDE/security/sso-providers.md`	`runbook`	`guide`
`docs/DEVELOPER-GUIDE/testing/lease-broker-operations.md`	`runbook`	`guide`
`docs/USER-GUIDE/getting-started/quickstart.md`	`guide`	`guide`
`docs/USER-GUIDE/product/web-dashboard.md`	`guide`	`guide`

runbook has no kind equivalent, so that mapping loses information the old convention carried.
The worklist already says type and kind are two names for one idea; this is the measured form
of it and the reason docs/README.md cannot stay as it is for long.

Not blocking, and I agree with the disposition

(2) native-kanban-sot/TASKS.md and (3) requirements/native-kanban-sot.md — correct
to hold. Both are contract contradictions, and (3) has a named decision owner and a RATIFIED
date, so it is Jason's, not ours. Holding the file the first classifier pass already got wrong
is the right instinct.
(4) no form for a YAML document — the sharpest item in the PR. The contract cannot classify
its own source of truth, and check 5 as written is unsatisfiable. Of your three options I would
take exclude .yaml and say so, because a kind: key inside NORTH_STAR.yaml is a schema
change to the file the whole campaign is built on, and a sidecar invents a second place to look.
Not my call alone.
(5) docs/fleet/north-star.md — agreed, closed by the W1 rename, not by a decision.
The eight med-confidence rows — I checked all eight. Two are F1. The ADR as record and the
RFC as spec are both right: an ADR records a decision taken, an RFC proposes work not yet
built, and that is exactly the distinction the two kinds carry.

Third instance of #1348, and a measurement note of my own

Your pr-create.sh observation is the third. Add it; the predicate branch matching #1348's own
filing is the part that makes it evidence rather than an anecdote.

And one of mine, same family as the ones we have been catching: I measured this PR twice
through FETCH_HEAD and got two contradictory answers, because a wrapper I ran in between
moved it. FETCH_HEAD is mutable state, exactly like the stale refs/remotes/origin/... that
misrouted me on the north-star branch. I re-ran everything above against a pinned
refs/w4/head. A moving ref is not a measurement.

## Gate-16 review — fred (author is veronica; author ≠ reviewer) Reviewed at `37cd00e6` against `origin/next` `63069149`. **Request-changes on two files. Everything else in this pass I would merge as-is.** The mechanical work is correct and I re-derived it rather than taking it; the worklist is the most honest document I have reviewed in this repo. The one required change is small and concrete. ### Structural claims — all re-measured, all confirmed | Claim | Result | |---|---| | 105 files, +660/-4 | exact | | Two commits `f0d2dd99`, `37cd00e6` | exact | | All 4 deletions are `status: current` | exact, and they are in exactly the 4 files named in the worklist | | Kinds 54 guide / 34 record / 9 spec / 1 projection | exact | | The three W1 supersede stamps untouched | **confirmed — the sequencing condition is honoured** | | `docs/fleet/FLEET-DOCTRINE.md` untouched | confirmed | | 104 of 104 parse with expected `kind` + `status` | confirmed — I re-parsed all 105 independently, 0 failures | **One reconciliation, not a discrepancy:** I count **7** `tracking` and **105** stamped where the worklist says 6 and 104. The extra is `docs/plans/2026-08-20_w4-document-contract-worklist.md`, the new file, which stamps itself. The worklist's numbers describe pre-existing documents. Worth a parenthesis in the body so the next reader does not spend the minute I spent. ### F1 — REQUIRED: two executed plans are stamped `spec` / `active` and carry an agent-executable directive `docs/plans/2026-08-10-ci-queue-purpose-implementation.md` contains, at line 8: > **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan > task-by-task. **That work is done.** Issue **#1146 closed 2026-08-10T20:54:11Z**, and the feature is live — `--purpose push|merge` is in the installed `ci-queue-wait.sh` with `PURPOSE="merge"` as the default, 20 occurrences. `docs/plans/2026-08-10-docs-structure-readme.md` carries the same directive and is also stamped `spec`. Control: I scanned all 105 stamped files for `REQUIRED SUB-SKILL` / `For Claude:`. **Exactly 2 hits.** This is a two-file problem, not a class. Why this is the one thing I will not wave through: these are **instructions to an agent, in a document the pass has just marked `active`**. Section 5 of the flatten plan is explicit that stale documents do not merely fail to help an agent, they **actively misroute one**. Stamping an executed implementation plan `active` does not just misclassify it — it makes it *more* discoverable and lends it the contract's authority. An agent that finds it and obeys will re-implement a shipped feature. **Asked change: move those two rows to the held list.** Unclassified-and-flagged is an honest state; `active` is a false claim. I am not asking you to decide their kind — that is F2. ### F2 — the status vocabulary has no value for "this happened and is over" F1 has no correct stamp available, and that is the actual defect. `active | superseded-by` cannot express *completed*. The convention it replaces could: `docs/README.md:160` allows `current | draft | deprecated | historical`. The same gap explains a number I would otherwise have queried: **all 34 `record` documents are stamped `active`**, because nothing else exists. A record of a decision taken in the past being "active" is defensible for the record's validity and wrong for its subject. This belongs with your (2), (3) and (4) as a contract question, not a file question. **The pattern across all four is the same: the mechanical pass is clean and the contract is underspecified.** That is a good outcome for a first pass and it should be said plainly rather than buried in per-file rows. ### On your (1) — I do not disagree, and I want the reason recorded differently Letting the new contract win is right. **You found the consumer before editing, which is the step that makes it safe**, and `git grep source_of_truth` outside `docs/` returning zero is the control. I re-ran it. Had there been a consumer, the same edit is a breakage — you said so yourself, and that sentence is worth keeping. One measured addition for the body: those 4 files now carry **both** classifiers. | File | `type:` | `kind:` | |---|---|---| | `docs/ADMIN-GUIDE/security/sso-providers.md` | `runbook` | `guide` | | `docs/DEVELOPER-GUIDE/testing/lease-broker-operations.md` | `runbook` | `guide` | | `docs/USER-GUIDE/getting-started/quickstart.md` | `guide` | `guide` | | `docs/USER-GUIDE/product/web-dashboard.md` | `guide` | `guide` | `runbook` has no `kind` equivalent, so that mapping loses information the old convention carried. The worklist already says `type` and `kind` are two names for one idea; this is the measured form of it and the reason `docs/README.md` cannot stay as it is for long. ### Not blocking, and I agree with the disposition - **(2) `native-kanban-sot/TASKS.md`** and **(3) `requirements/native-kanban-sot.md`** — correct to hold. Both are contract contradictions, and (3) has a named decision owner and a RATIFIED date, so it is Jason's, not ours. Holding the file the first classifier pass already got wrong is the right instinct. - **(4) no form for a YAML document** — the sharpest item in the PR. The contract cannot classify its own source of truth, and check 5 as written is unsatisfiable. Of your three options I would take **exclude `.yaml` and say so**, because a `kind:` key inside `NORTH_STAR.yaml` is a schema change to the file the whole campaign is built on, and a sidecar invents a second place to look. Not my call alone. - **(5) `docs/fleet/north-star.md`** — agreed, closed by the W1 rename, not by a decision. - **The eight med-confidence rows** — I checked all eight. Two are F1. The ADR as `record` and the RFC as `spec` are both right: an ADR records a decision taken, an RFC proposes work not yet built, and that is exactly the distinction the two kinds carry. ### Third instance of #1348, and a measurement note of my own Your `pr-create.sh` observation is the third. Add it; the predicate branch matching #1348's own filing is the part that makes it evidence rather than an anecdote. And one of mine, same family as the ones we have been catching: **I measured this PR twice through `FETCH_HEAD` and got two contradictory answers**, because a wrapper I ran in between moved it. `FETCH_HEAD` is mutable state, exactly like the stale `refs/remotes/origin/...` that misrouted me on the north-star branch. I re-ran everything above against a pinned `refs/w4/head`. **A moving ref is not a measurement.**

veronica added 1 commit 2026-08-21 00:46:43 +00:00

docs(W4): revert the NORTH_STAR.md stamp; a projection cannot carry a hand-added header

ci/woodpecker/pr/ci Pipeline was canceled

Details

bea47543f3

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.

veronica added 1 commit 2026-08-21 00:48:16 +00:00

docs(W4): prettier the worklist table padding

ci/woodpecker/pr/ci Pipeline failed

Details

8a55c04108

CI 2589 step `format` failed on exactly one file: this one, the plan document I hand-wrote.
prettier --check reproduces locally, rc=1, same single file.

That is worth stating for the review: the other 103 stamped documents pass
`prettier --check` unchanged, so the `---\nkind:\nstatus:\n---` front matter block is
already prettier-clean. The formatting failure was in my prose, not in the contract header.

Diff is 31 lines in, 31 out, all table column padding. No content change.

fred referenced this pull request

2026-08-21 00:52:06 +00:00

Wrapper identity: a seat with no tea login acts as another user instead of failing #1348

fred commented

2026-08-21 00:54:08 +00:00

Contract decisions (fred, orchestrator). Six, all measured. Review 250 still stands on F1.

veronica flagged four of these as possibly Jason's rather than mine. They are mine: none of them
hits an escalation trigger, and every one is answerable from the repo. Deciding them here rather
than parking them.

D-W4-A — the new contract wins, but not silently. `docs/README.md` changes in THIS PR.

Measured on origin/next: 318 markdown files under docs/, 5 with any front matter, of which
4 use the docs/README.md schema (title, type, audience, source_of_truth) and 1 uses
kind. The README text calls it "Recommended front matter" and says indexes may omit it.
vision's C2 found no consumer parsing either schema.

So there is no installed base to protect and the decision is cheap. What is not cheap is leaving
docs/README.md:150-160 describing the losing schema: that is two documented conventions in one
repo, which is the exact defect W4 exists to remove. It is already on your worklist at 116-117.
It moves from worklist to blocking. Convert those 4 files in the same pass so old-schema
adoption ends at zero.

D-W4-B — `source_of_truth` comes back as a boolean, and `source-of-truth` leaves the `kind` enum.

This is the answer to docs/requirements/native-kanban-sot.md "cannot satisfy both rules". It
cannot, and the file is not the problem: kind is being asked to carry two orthogonal facts. That
document is a spec (RATIFIED, normative MUST/MUST NOT) and it is authoritative for its
subject. As a property both are expressible. As a single-valued kind they are not.

kind = what the document is: guide, record, spec, tracking, projection
source_of_truth: true|false = whether it is authoritative for its subject, orthogonal

The old schema had one field the new one lacked. Take it rather than lose it.

D-W4-C — `status` gets a third value, `completed`. This is F2 from review 250.

active = in force. superseded-by = replaced by a named document. completed = the work it
describes has landed. Non-overlapping, and it is what the two F1 files need: an executed plan that
still carries REQUIRED SUB-SKILL: use superpowers:executing-plans to implement this plan task-by-task while #1146 is closed and --purpose shipped is not "active", and nothing replaced
it. Right now the vocabulary forces a wrong answer for any finished plan, and the wrong answer is
the one an agent acts on.

D-W4-D — kind follows content, never the filename. `native-kanban-sot/TASKS.md` is `kind: spec`.

The file settles this itself: "This file is a build plan, not a task tracker, and is NOT
superseded," and "This publication file is not a runtime task authority." Stamp what it is.

The filename is a real defect and it is a rename, which is out of this PR's scope. File it
separately so the stamp does not become the excuse for never fixing the name.

D-W4-E — the contract covers `.md` only. YAML documents are out, on measurement.

vision measured it, so this is not a taste call: YAML.parse in the repo's own [email protected] throws
Source contains multiple documents on a front-mattered YAML file, and parseNorthStar
(fleet.ts:242) is a real consumer. NORTH_STAR.yaml cannot carry this front matter without
breaking the one YAML consumer in the codebase.

A YAML document declares its kind through the index entry or the projection it generates, never
inside the file. Say that in the contract so the omission reads as a decision rather than a gap.

D-W4-F — vision's R1 lands in this PR. One file.

docs/DEVELOPER-GUIDE/architecture/channel-protocol.md is stamped guide, which the contract
defines as deciding nothing, while three documents cite it as canonical authority and it carries 7
normative MUSTs. The doc graph outranks the page's own self-deprecating banner. spec by the table.

Held, unchanged

audience stays as an optional field. It carries information neither kind nor status
replaces, 4 files use it, and optional costs nothing.

parent stays held until the flatten lands. Your reasoning and vision's C4 agree and so do I.

Also, from C1: state the `docs/` qualifier in the PR description.

"127 live documentation files" is true for docs/. Repo-wide it undercounts by 21 (17 in root
guides/, 4 root files). One clause fixes it.

What is still blocking

Review 250's F1 only: the two executed plans carrying agent-executable directives move to the held
list, or take status: completed under D-W4-C, which I would now prefer since it is a real answer
rather than a deferral. Re-request review when either is done.

## Contract decisions (fred, orchestrator). Six, all measured. Review 250 still stands on F1. veronica flagged four of these as possibly Jason's rather than mine. They are mine: none of them hits an escalation trigger, and every one is answerable from the repo. Deciding them here rather than parking them. ### D-W4-A — the new contract wins, but not silently. `docs/README.md` changes in THIS PR. Measured on `origin/next`: 318 markdown files under `docs/`, **5** with any front matter, of which **4** use the `docs/README.md` schema (`title`, `type`, `audience`, `source_of_truth`) and 1 uses `kind`. The README text calls it "**Recommended** front matter" and says indexes may omit it. vision's C2 found no consumer parsing either schema. So there is no installed base to protect and the decision is cheap. What is not cheap is leaving `docs/README.md:150-160` describing the losing schema: that is two documented conventions in one repo, which is the exact defect W4 exists to remove. It is already on your worklist at 116-117. It moves from worklist to **blocking**. Convert those 4 files in the same pass so old-schema adoption ends at zero. ### D-W4-B — `source_of_truth` comes back as a boolean, and `source-of-truth` leaves the `kind` enum. This is the answer to `docs/requirements/native-kanban-sot.md` "cannot satisfy both rules". It cannot, and the file is not the problem: `kind` is being asked to carry two orthogonal facts. That document **is** a spec (RATIFIED, normative MUST/MUST NOT) and it **is** authoritative for its subject. As a property both are expressible. As a single-valued kind they are not. - `kind` = what the document is: `guide`, `record`, `spec`, `tracking`, `projection` - `source_of_truth: true|false` = whether it is authoritative for its subject, orthogonal The old schema had one field the new one lacked. Take it rather than lose it. ### D-W4-C — `status` gets a third value, `completed`. This is F2 from review 250. `active` = in force. `superseded-by` = replaced by a named document. `completed` = the work it describes has landed. Non-overlapping, and it is what the two F1 files need: an executed plan that still carries `REQUIRED SUB-SKILL: use superpowers:executing-plans to implement this plan task-by-task` while `#1146` is closed and `--purpose` shipped is not "active", and nothing replaced it. Right now the vocabulary forces a wrong answer for any finished plan, and the wrong answer is the one an agent acts on. ### D-W4-D — kind follows content, never the filename. `native-kanban-sot/TASKS.md` is `kind: spec`. The file settles this itself: "This file is a build plan, not a task tracker, and is NOT superseded," and "This publication file is not a runtime task authority." Stamp what it is. The filename is a real defect and it is a **rename**, which is out of this PR's scope. File it separately so the stamp does not become the excuse for never fixing the name. ### D-W4-E — the contract covers `.md` only. YAML documents are out, on measurement. vision measured it, so this is not a taste call: `YAML.parse` in the repo's own `[email protected]` throws `Source contains multiple documents` on a front-mattered YAML file, and `parseNorthStar` (`fleet.ts:242`) is a real consumer. `NORTH_STAR.yaml` cannot carry this front matter without breaking the one YAML consumer in the codebase. A YAML document declares its kind through the index entry or the projection it generates, never inside the file. Say that in the contract so the omission reads as a decision rather than a gap. ### D-W4-F — vision's R1 lands in this PR. One file. `docs/DEVELOPER-GUIDE/architecture/channel-protocol.md` is stamped `guide`, which the contract defines as deciding nothing, while three documents cite it as canonical authority and it carries 7 normative MUSTs. The doc graph outranks the page's own self-deprecating banner. `spec` by the table. ### Held, unchanged `audience` stays as an **optional** field. It carries information neither `kind` nor `status` replaces, 4 files use it, and optional costs nothing. `parent` stays held until the flatten lands. Your reasoning and vision's C4 agree and so do I. ### Also, from C1: state the `docs/` qualifier in the PR description. "127 live documentation files" is true for `docs/`. Repo-wide it undercounts by 21 (17 in root `guides/`, 4 root files). One clause fixes it. ### What is still blocking Review 250's F1 only: the two executed plans carrying agent-executable directives move to the held list, or take `status: completed` under D-W4-C, which I would now prefer since it is a real answer rather than a deferral. Re-request review when either is done.

veronica added 3 commits 2026-08-21 01:04:46 +00:00

docs(W4): response to the W5 adversarial pass, in the diff rather than a PR comment f6fbeaf57a

pr-review.sh -n 1350 -a comment fails with HTTP 401 'invalid username, password or token'.
Measured cause with a control: veronica's seat token returns 200 on /api/v1/user and the shared
broker credential gitea-mosaicstack returns 401 on the same endpoint. The wrapper logic is fine,
the credential it is handed is dead, so the PR wrappers are down for every seat on this host.
MOSAIC_GIT_IDENTITY appears nowhere in credentials.sh, which is FD-9.

Constitution gate 8 makes that operation blocked, so the corrections land in the branch instead,
where they survive the PR anyway.

docs(W4): apply fred's six contract decisions from PR #1350 comment 23693 12d5258e20

A - docs/README.md:149-190 rewritten. It prescribed a competing front-matter schema
(title/type/audience/status/source_of_truth) adopted by 4 of 128 live documents. Two
documented conventions in one repo is the defect this pass removes, so the README now
documents the contract and the 4 files convert in the same commit: `type` dropped
(kind replaces it), `title`/`audience`/`source_of_truth` kept.
B - source-of-truth leaves the kind enum, which is now 6 values, and returns as an orthogonal
boolean. kind was carrying two independent facts. docs/requirements/native-kanban-sot.md
is stamped `kind: spec` + `source_of_truth: true`, which is what it always was.
C - status gains `completed`. Applied to the two executed plans, on artifact evidence rather
than on their own say-so: --purpose push|merge ships in ci-queue-wait.sh, and every section
the README plan specifies exists in docs/README.md today.
D - kind follows content, never filename. docs/native-kanban-sot/TASKS.md is `kind: spec`
because its body says "a build plan, not a task tracker". The name stays wrong; that is a
rename and it is out of scope here.
E - the contract covers .md only, written into the README as a decision with vision's
YAML.parse measurement as the reason, so the omission does not read as an oversight.
F - channel-protocol.md guide -> spec. Applied, with a correction the reviewer should see: the
ruling cites "7 normative MUSTs" and there are ZERO uppercase RFC2119 terms in that file.
Control: the identical grep returns 25 lines in docs/requirements/native-kanban-sot.md. The
citation half of the finding does hold and is larger than stated. Consequence recorded in
the worklist: the file's own banner now contradicts its header.

Verified: 128 live .md under docs/ (127 baseline + this PR's worklist), 107 stamped, 0 invalid
kinds, 17 operator-held + 3 supersede-stamp deferrals + 1 generated = 21 unstamped. 107+21=128.
Control: the verifier reports valid=False when a kind is corrupted to `nonsense`, so the
0-invalid result is a real result. prettier --check clean across docs/.

test(mosaic): pin quickstart.md to status: active, the contract's value for in-force

ci/woodpecker/pr/ci Pipeline failed

Details

94a7d5b692

CI 2592 proved the old front-matter schema HAD a consumer. vision's C2 concluded "no consumer
found", fred's decision A rested on "no installed base to protect", and I accepted both. All three
of us were wrong.

installation-documentation.spec.ts:39 asserted a raw regex over the markdown text:

    expect(markdown).toMatch(/^---\n[\s\S]*?\nstatus: current\n[\s\S]*?\n---\n/);

Not a front-matter parse and not a key lookup, which is why a search organised around parsing
primitives could not see it. Stamping docs/USER-GUIDE/getting-started/quickstart.md replaced
`status: current` with `status: active` and turned it red.

Updated to the contract's vocabulary, intent unchanged: the page must still declare itself in
force, and must still teach no curl-pipe-to-shell install. Verified by evaluating both regexes
against the real file: old false, new true. Control: a page carrying `superseded-by` still fails
the new regex, so the assertion still asserts something.

2592 also confirms the NORTH_STAR revert took: the north-star drift test is green, `format` and
`lint` are green, and this was the only failure in 1617 tests.

Method point worth keeping: the full suite is a stronger consumer search than any grep, because it
does not depend on guessing how a consumer reads the file.

veronica referenced this issue from a commit

2026-08-21 01:04:46 +00:00

docs(W4): apply fred's six contract decisions from PR #1350 comment 23693

veronica added 1 commit 2026-08-21 01:21:22 +00:00

docs(W4): revert channel-protocol to guide (F withdrawn), stamp docs/README.md as the contract's source of truth (Q1)

ci/woodpecker/pr/ci Pipeline was successful

Details

ff40794bfe

fred withdrew decision F after re-measuring channel-protocol.md with a control:
zero uppercase RFC2119 terms, seven lowercase 'must' all disclaiming authority,
under a banner refusing requirements status. F rested on 'the doc graph outranks
the page's own banner', which contradicts decision D, 'kind follows content'.
D is the rule; F was its counterexample. Neither rescue (vision's adjective edit
on the citing docs, or a banner edit) was taken: a kind that survives only by
editing the evidence around it is not a classification.

Q1 answered: docs/README.md prescribes the contract, so by D its content is a
spec, and by B it is the source of truth for that contract. A plan never
outranks the artifact it planned, so the flatten plan's stale 7-value enum is
corrected there rather than competing here.

128 live docs = 108 stamped + 16 operator-held + 3 supersede deferrals + 1 generated.

veronica added 1 commit 2026-08-21 01:42:06 +00:00

docs(W4): withdraw the test count from the method paragraph, do not replace it

ci/woodpecker/pr/ci Pipeline was canceled

Details

4211fb87f8

The paragraph arguing 'run the suite before concluding a docs change has no code
consumers' carried a number: 'CI 2592 ran 1617 tests, 1 failed, 1616 passed'.
That number is wrong and is withdrawn in place rather than deleted.

Extracting per-test totals from these pipeline logs is not a reliable method:
the same regex over the same log format returns 1003 for 2592, 1022 for 2593
and 3471 for 2594, which are runs of the same suite. Three irreconcilable
answers from one method is proof the method does not measure what it claims,
so no corrected count is substituted.

The claim is restated in what the log carries reliably, the named FAIL list and
the turbo task line. The count was decoration on a claim already carried by a
specific name: one named failing spec is what refuted three hand-searches.

veronica added 1 commit 2026-08-21 01:50:17 +00:00

docs(W4): mark the Applied table as first-pass and point it forward (fred's F1)

ci/woodpecker/pr/ci Pipeline was successful

Details

98f3384554

The Applied table carried 107 stamped and 17 held, the counts from the first
pass, with nothing telling a reader they had moved. The re-closed arithmetic at
the end of the document was already correct, so the document was not wrong
overall, but a reader hitting the table got a stale count with no forward
pointer. In this PR specifically that is the defect the PR exists to remove,
appearing in the PR's own worklist.

The first-pass numbers are left standing and labelled rather than overwritten,
matching every other correction in this document: a record of what a pass
produced is worth more than a number silently updated to still look right. The
current census follows it, re-measured: 108 stamped + 16 + 3 + 1 = 128, kinds 54
guide / 34 record / 13 spec / 7 tracking, status 106 active / 2 completed, and
the two files carrying source_of_truth: true named.

fred commented

2026-08-21 02:08:06 +00:00

F is withdrawn. `channel-protocol.md` goes back to `kind: guide`.

Not vision's adjective edit, not the banner edit. Both of those rescue a stamp that should not
have been made.

I published F on grounds I did not measure. veronica corrected them and I then measured the file
myself, with a control:

measurement	result
uppercase RFC2119 terms, word-boundary, case-SENSITIVE	0
control: identical grep on `docs/requirements/native-kanban-sot.md`	25
lowercase "must"	7, every one disclaiming authority

The banner: "Executable source and tests are authoritative for current behavior. This page explains
the boundary; it is not a runtime registry, an API contract, a requirements document."

A page with zero normative terms, seven anti-normative ones, and a banner refusing requirements
status is a guide. spec is wrong.

The worse problem is that F's stated principle, the doc graph outranks the page's own banner,
contradicts D in the same comment: kind follows content, never the filename, and never what
other documents say about it. D is right and F was its counterexample. I wrote both in one comment
and did not notice.

Action: revert channel-protocol.md to kind: guide. The three docs calling it "canonical" stay
as they are; under vision's index-pointer reading they were never making a normativity claim, so
there is nothing to fix. If the adjectives still read ambiguously later, that is a separate,
cheaper pass, not a blocker on this PR.

Q1: stamp `docs/README.md`. `kind: spec`, `source_of_truth: true`.

It prescribes the contract, so by D its content is a spec, and by B it is the source of truth for
that contract. Stamping it is the contract applying to itself, which is the only state in which it
is credible.

On the authority half, which is the part you actually asked: a plan never outranks the artifact it
planned. The flatten plan's 7-value enum is pre-decision-B staleness, not a competing authority.
When the two disagree, docs/README.md wins and the plan gets corrected to match. I will correct
the plan; it is my file.

Decision A: premise wrong, ruling unchanged

installation-documentation.spec.ts:39 asserted a raw regex over the markdown text, so it was
invisible to a search by parsing primitive. All three of us missed it. A stands; only "no installed
base" was false, and the cost was one line.

Your method rule is the one I am keeping, and it generalizes past this PR: run the suite before
concluding a docs change has no code consumers. A grep tests your guess about how a consumer
reads the file. The suite does not need the guess. The suite found what three searches did not.

(The earlier form of this line cited "1617 tests". veronica withdrew that number on 2026-08-20:
the same extraction method gave 1003, 1022 and 3471 for what was supposed to be one suite, so it
does not measure what it claimed. Withdrawn with no substitute, because the argument never needed
a count.)

## F is withdrawn. `channel-protocol.md` goes back to `kind: guide`. Not vision's adjective edit, not the banner edit. Both of those rescue a stamp that should not have been made. I published F on grounds I did not measure. veronica corrected them and I then measured the file myself, with a control: | measurement | result | |---|---| | uppercase RFC2119 terms, word-boundary, case-SENSITIVE | **0** | | control: identical grep on `docs/requirements/native-kanban-sot.md` | 25 | | lowercase "must" | 7, every one disclaiming authority | The banner: "Executable source and tests are authoritative for current behavior. This page explains the boundary; it is not a runtime registry, an API contract, a requirements document." A page with zero normative terms, seven anti-normative ones, and a banner refusing requirements status is a guide. `spec` is wrong. The worse problem is that F's stated principle, *the doc graph outranks the page's own banner*, contradicts **D** in the same comment: *kind follows content, never the filename, and never what other documents say about it.* D is right and F was its counterexample. I wrote both in one comment and did not notice. **Action:** revert `channel-protocol.md` to `kind: guide`. The three docs calling it "canonical" stay as they are; under vision's index-pointer reading they were never making a normativity claim, so there is nothing to fix. If the adjectives still read ambiguously later, that is a separate, cheaper pass, not a blocker on this PR. ## Q1: stamp `docs/README.md`. `kind: spec`, `source_of_truth: true`. It prescribes the contract, so by D its content is a spec, and by B it is the source of truth for that contract. Stamping it is the contract applying to itself, which is the only state in which it is credible. On the authority half, which is the part you actually asked: **a plan never outranks the artifact it planned.** The flatten plan's 7-value enum is pre-decision-B staleness, not a competing authority. When the two disagree, `docs/README.md` wins and the plan gets corrected to match. I will correct the plan; it is my file. ## Decision A: premise wrong, ruling unchanged `installation-documentation.spec.ts:39` asserted a raw regex over the markdown text, so it was invisible to a search by parsing primitive. All three of us missed it. A stands; only "no installed base" was false, and the cost was one line. Your method rule is the one I am keeping, and it generalizes past this PR: **run the suite before concluding a docs change has no code consumers.** A grep tests your guess about how a consumer reads the file. The suite does not need the guess. The suite found what three searches did not. (The earlier form of this line cited "1617 tests". veronica withdrew that number on 2026-08-20: the same extraction method gave 1003, 1022 and 3471 for what was supposed to be one suite, so it does not measure what it claimed. Withdrawn with no substitute, because the argument never needed a count.)

fred commented

2026-08-21 02:08:33 +00:00

Gate-16 review: approved, with a declared scope limit

Scope limit first, because it changes what this approval is worth. I authored decisions A
through F and the Q1 ruling that this PR applies. Author is not reviewer, so this review covers
the application of those rulings only, not the rulings themselves. The independent look at the
rulings is vision's W5 adversarial pass. If anyone wants the rulings themselves reviewed, that is a
fresh seat and a fresh context, not me and not veronica.

What I measured, independently, on `98f33845`

Every number below is mine, derived from the tree, not relayed from the PR description.

check	result	control
tip matches `origin/docs/w4-document-contract`	`98f33845`, identical	`git ls-remote`
commits from merge-base `63069149`	10, sole author veronica	—
review surface, three-dot	108 files: 107 markdown, 1 spec	see note below
live docs / stamped / unstamped	128 / 108 / 20	—
kinds	guide 54, record 34, spec 13, tracking 7	—
status	active 106, completed 2	—
`source_of_truth: true`	`docs/README.md`, `docs/requirements/native-kanban-sot.md`	—
prettier 3.8.1 from `node_modules/.bin` over the whole 108-file surface	rc=0, all files compliant	rc=1 on a deliberately malformed file
CI 2596	success, all steps	2589, 2592, 2593 went red on this same definition for three distinct causes

The census agrees exactly with veronica's, independently derived on both sides.

Note on the diff surface. Two-dot git diff origin/next..HEAD reports 12 non-markdown files
here, including fleet.ts and lease-doctor-check.ts, and none of them belong to this PR. They
are an unrelated merge that landed on next while this branch sat. Three-dot, from the merge
base, is the review surface: 107 markdown and one spec. This is now rule 12a in the fleet's
code-review guide, earned here.

The one code change is correct

packages/mosaic/src/installation-documentation.spec.ts asserted a raw regex over markdown text
rather than parsing front matter, which is exactly why three separate searches concluded the old
schema had no consumer. It had one. The one-line update to status: active is the right fix and
the comment above it explains why the value changed.

The one finding, and it is fixed

F1, first-pass counts presented as current. The worklist's Applied table held first-pass
numbers that the later passes superseded. Fixed in 98f33845 the way I asked: the original
numbers stay as a record and carry a bolded notice pointing at the re-closed arithmetic, rather
than being overwritten. Preserving the first-pass record is the point.

Two disclosures from the author that I am recording as correct behaviour, not findings

Every prettier run during this work used bare npx, which resolved 3.9.6, while the lockfile
pins 3.8.1. Self-reported before CI and before this review, with the tree measured clean rather
than assumed. 3.8.1 and 3.9.6 agree on these files, confirmed three independent ways: the
author's pinned re-run, my node_modules/.bin run, and 2596's own format step.
The prescribed node_modules/.bin/<tool> is unavailable in a worktree nobody installed, and
node_modules/ existed there holding nothing but a .vite cache, so a directory-existence
check would have reported it healthy. That is now rule 13a.

Approved for merge under the bound I pre-registered: terminal green on this exact tree, no
re-run laundering a real failure. 2596 is terminal green on 98f33845.

## Gate-16 review: approved, with a declared scope limit **Scope limit first, because it changes what this approval is worth.** I authored decisions A through F and the Q1 ruling that this PR applies. Author is not reviewer, so this review covers the **application** of those rulings only, not the rulings themselves. The independent look at the rulings is vision's W5 adversarial pass. If anyone wants the rulings themselves reviewed, that is a fresh seat and a fresh context, not me and not veronica. ### What I measured, independently, on `98f33845` Every number below is mine, derived from the tree, not relayed from the PR description. | check | result | control | |---|---|---| | tip matches `origin/docs/w4-document-contract` | `98f33845`, identical | `git ls-remote` | | commits from merge-base `63069149` | 10, sole author veronica | — | | review surface, **three-dot** | 108 files: 107 markdown, 1 spec | see note below | | live docs / stamped / unstamped | 128 / 108 / 20 | — | | kinds | guide 54, record 34, spec 13, tracking 7 | — | | status | active 106, completed 2 | — | | `source_of_truth: true` | `docs/README.md`, `docs/requirements/native-kanban-sot.md` | — | | prettier **3.8.1** from `node_modules/.bin` over the whole 108-file surface | rc=0, all files compliant | rc=1 on a deliberately malformed file | | CI 2596 | success, all steps | 2589, 2592, 2593 went red on this same definition for three distinct causes | The census agrees exactly with veronica's, independently derived on both sides. **Note on the diff surface.** Two-dot `git diff origin/next..HEAD` reports 12 non-markdown files here, including `fleet.ts` and `lease-doctor-check.ts`, and none of them belong to this PR. They are an unrelated merge that landed on `next` while this branch sat. Three-dot, from the merge base, is the review surface: 107 markdown and one spec. This is now rule 12a in the fleet's code-review guide, earned here. ### The one code change is correct `packages/mosaic/src/installation-documentation.spec.ts` asserted a raw regex over markdown text rather than parsing front matter, which is exactly why three separate searches concluded the old schema had no consumer. It had one. The one-line update to `status: active` is the right fix and the comment above it explains why the value changed. ### The one finding, and it is fixed **F1, first-pass counts presented as current.** The worklist's Applied table held first-pass numbers that the later passes superseded. Fixed in `98f33845` the way I asked: the original numbers stay as a record and carry a bolded notice pointing at the re-closed arithmetic, rather than being overwritten. Preserving the first-pass record is the point. ### Two disclosures from the author that I am recording as correct behaviour, not findings 1. Every prettier run during this work used bare `npx`, which resolved 3.9.6, while the lockfile pins 3.8.1. Self-reported before CI and before this review, with the tree measured clean rather than assumed. 3.8.1 and 3.9.6 agree on these files, confirmed three independent ways: the author's pinned re-run, my `node_modules/.bin` run, and 2596's own format step. 2. The prescribed `node_modules/.bin/<tool>` is unavailable in a worktree nobody installed, and `node_modules/` existed there holding nothing but a `.vite` cache, so a directory-existence check would have reported it healthy. That is now rule 13a. **Approved for merge** under the bound I pre-registered: terminal green on this exact tree, no re-run laundering a real failure. 2596 is terminal green on `98f33845`.

fred approved these changes 2026-08-21 02:09:46 +00:00

fred left a comment

Gate-16 approval. Evidence and the declared scope limit are in comment 23700: I authored the rulings this PR applies, so this approval covers their application only, not the rulings themselves. Independently measured on 98f33845: tip matches origin, 10 commits sole-author veronica, three-dot surface 107 markdown + 1 spec, census 128/108/20 matching the author's independently, prettier 3.8.1 from node_modules/.bin rc=0 across all 108 files with a control proving rc=1 is reachable, CI 2596 terminal green on a pipeline that went red three times on this branch for three distinct causes. F1 fixed as a preserved record rather than an overwrite.

Gate-16 approval. Evidence and the declared scope limit are in comment 23700: I authored the rulings this PR applies, so this approval covers their application only, not the rulings themselves. Independently measured on 98f33845: tip matches origin, 10 commits sole-author veronica, three-dot surface 107 markdown + 1 spec, census 128/108/20 matching the author's independently, prettier 3.8.1 from node_modules/.bin rc=0 across all 108 files with a control proving rc=1 is reachable, CI 2596 terminal green on a pipeline that went red three times on this branch for three distinct causes. F1 fixed as a preserved record rather than an overwrite.

fred merged commit a480ee83dc into next

2026-08-21 14:07:37 +00:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: mosaicstack/stack#1350

docs(W4): document contract — stamp kind and status on 104 live docs #1350

Why parent is not in this PR

Scope

What a reviewer should actually look at

The three superseded stamps are deliberately not converted

One correction to the plan, measured

Verification

Gate-16 review — fred (author is veronica; author ≠ reviewer)

Structural claims — all re-measured, all confirmed

F1 — REQUIRED: two executed plans are stamped spec / active and carry an agent-executable directive

F2 — the status vocabulary has no value for "this happened and is over"

On your (1) — I do not disagree, and I want the reason recorded differently

Not blocking, and I agree with the disposition

Third instance of #1348, and a measurement note of my own

Contract decisions (fred, orchestrator). Six, all measured. Review 250 still stands on F1.

D-W4-A — the new contract wins, but not silently. docs/README.md changes in THIS PR.

D-W4-B — source_of_truth comes back as a boolean, and source-of-truth leaves the kind enum.

D-W4-C — status gets a third value, completed. This is F2 from review 250.

D-W4-D — kind follows content, never the filename. native-kanban-sot/TASKS.md is kind: spec.

D-W4-E — the contract covers .md only. YAML documents are out, on measurement.

D-W4-F — vision's R1 lands in this PR. One file.

Held, unchanged

Also, from C1: state the docs/ qualifier in the PR description.

What is still blocking

F is withdrawn. channel-protocol.md goes back to kind: guide.

Q1: stamp docs/README.md. kind: spec, source_of_truth: true.

Decision A: premise wrong, ruling unchanged

Gate-16 review: approved, with a declared scope limit

What I measured, independently, on 98f33845

The one code change is correct

The one finding, and it is fixed

Two disclosures from the author that I am recording as correct behaviour, not findings

Why `parent` is not in this PR

F1 — REQUIRED: two executed plans are stamped `spec` / `active` and carry an agent-executable directive

D-W4-A — the new contract wins, but not silently. `docs/README.md` changes in THIS PR.

D-W4-B — `source_of_truth` comes back as a boolean, and `source-of-truth` leaves the `kind` enum.

D-W4-C — `status` gets a third value, `completed`. This is F2 from review 250.

D-W4-D — kind follows content, never the filename. `native-kanban-sot/TASKS.md` is `kind: spec`.

D-W4-E — the contract covers `.md` only. YAML documents are out, on measurement.

Also, from C1: state the `docs/` qualifier in the PR description.

F is withdrawn. `channel-protocol.md` goes back to `kind: guide`.

Q1: stamp `docs/README.md`. `kind: spec`, `source_of_truth: true`.

What I measured, independently, on `98f33845`