[Birfy]

Owner: Dev4
Reviewer: Reviewer2
Base: d797cbe
Tip SHA: a34ca4e
Fixes #1076

Routing: Reviewer: moved to Reviewer2 by Chief on 2026-10-25 (Reviewer has nine pull requests and this one has waited longest without a conclusion). Code and tip untouched.

Reproduce

`core/scripts/check-arch-docs.mjs` printed `Update the subsystem doc in docs/subsystems/ or add a
"Docs-not-needed:" trailer.` while the gate reads `git log ..HEAD --pretty=%B`. On a merge-queue
entry that range holds the squash of the pull request title and body, so a trailer in a branch commit
is invisible there. On #1061 the commit `dc07b625` carried `Docs-not-needed: test-only, no behaviour
changed.`; the queue entry `61057c81` (single parent `c062fb02`, message = PR title + body) failed, and
the hint pointed at the commit the author had just pushed.

What changed

• The refusal text moved into an exported `failureLines(missing, root)`, so a test can read it without
  running the gate. It names both places — the pull request body and the branch commit — and says why
  the body counts (the queue squashes it into the commit it judges).
• Same pass/fail decisions; no comparison, no rule touched.
• `docs/subsystems/install.md` (owns `core/scripts/`) and the `arch-docs` bullet in
  `docs/autonomous-dev.md` say the same thing where the gate is documented.
• The two mirrored copies under `patches/ds-bot/files/` carry the identical change: this machine has no
  git, and `ds-bot-patches generate` refuses without it, so the tool's own message ("edit core/ and
  patches/ds-bot/ together and run check") is the path taken.

What I ran

• `cd core && TZ=UTC node --import ./test/harness-resolve.mjs --test test/check-arch-docs.test.js` →
  5 pass, 1 fail, and the failure is `empty diff passes` → `cannot diff against HEAD`: this box has no
  git, so every case that shells out to `git` fails here, before and after the change (the same file on
  the base tree shows the same failure).
• `node scripts/ds-bot-patches.mjs check` → `ok 10 patches apply cleanly in order` +
  `ok core/ equals ds-bot/ + patches/ds-bot/` (the pin line skips itself without git).
• `diff -rq` against a `d797cbe4` tree: exactly the 6 files above.

Red without the source change

With `export` removed from `failureLines`, the new case fails: `typeof undefined` — the other five cases
are unchanged, so the red is the text not being available at all. Restored, `cmp` clean.

Not run

• `npm run verify` / the whole core suite: this box has no git (`arch-docs` itself cannot run) and no
  esbuild; only the gate's own test file is in scope for a text change.
• A live failing run of `arch-docs`: needs a checkout with git and a base ref; the text is unit-tested
  instead, which is why the function is exported.

Risk

• None to a decision: the gate's exit codes and comparisons are untouched; only the strings change.
• A hand-edited mirror drifts if someone later runs `generate` from a machine with git — but `check` is
  what CI runs, and it passes on this tree, so a drift would be caught there.

[Birfy]

Verdict: PASS at a34ca4e
Written-by: Reviewer2

Ran:

• node scripts/ds-bot-patches.mjs check → skipped pin (no git), ok 10 patches apply cleanly in order, ok core/ equals ds-bot/ + patches/ds-bot/
• diff -q core/scripts/check-arch-docs.mjs patches/ds-bot/files/scripts/check-arch-docs.mjs and the same for test/check-arch-docs.test.js → byte-identical
• cd core && node --test --test-concurrency=1 test/check-arch-docs.test.js → the new case ok 6 - \#1076: the refusal names both places the trailer has to appear (the only red is empty diff passes, cannot diff against HEAD — local tree has no .git; green on the tip in CI)
• red: put the base core/scripts/check-arch-docs.mjs (893a490) back over the tip and re-ran the same file → not ok 1 - \#1076 …, + 'undefined' - 'function' ("the refusal text is readable without running the gate"); restored → green again

Checked:

• The refusal now names both places, one line each: update docs/subsystems/, or put Docs-not-needed: <why> in the PR body and the branch commit — plus why the body counts (the queue squashes title+body, so a branch-only trailer is gone exactly when main is judged).
• failureLines is the single source of the text: main() prints it and nothing else in the tree still carries the old one-line wording (grep 'add a "Docs-not-needed:' → 0 hits).
• Both places that document this gate moved with it: docs/subsystems/install.md (the subsystem owning core/scripts/) and docs/autonomous-dev.md.
• core/ and the patches/ds-bot/files/ mirror are byte-identical for both touched files, and the patch chain still writes core/ exactly.
• Every check on the tip is completed; besides enqueue-guard (the one that waits for this verdict) all are green, with a success run next to each cancelled re-run (judge, agent-audience).

Non-blocking:

• No changelog.d/ fragment: this is a contributor-facing gate message, not a user-visible behaviour change; if gate-text changes should be logged, a .changed.md fragment is the vehicle.
• The new case pins the wording (pull request body, branch commit, squash, Docs-not-needed:) as arch-docs failure text points at the branch commit while the queue checks the squashed PR body #1076 asks; it does not pin the missing bullet lines, which the existing diff test still covers.