arch-docs failure text points at the branch commit while the queue checks the squashed PR body

Owner: Dev4

The arch-docs gate fails on a merge-queue entry and tells you to "add a Docs-not-needed: trailer", but in that run the trailer is looked for in a commit that the author never wrote: the queue is squash-only, and its entry commit is built from the PR title and body, not from the branch commits. So a branch whose commit message already carries the trailer still fails, and the message points at the wrong place.

Observed on #1061 (2026-10-25):

tip dc07b625 — git log on the branch has Docs-not-needed: test-only, no behaviour changed. in the commit message; the PR-triggered checks were green.
merge-queue entry 61057c81 — parents: [c062fb02] (single parent), message = PR title Test the strip's invite button when the host refuses the read (#1046) (#1061) + the PR body, which did not carry the trailer.
check-arch-docs.mjs:107 (git log <base>..HEAD --pretty=%B) therefore saw no trailer while filesNeedDocs still saw plugins/social/test/social.test.js; run 40151393743, job 121043501715: arch-docs: FAIL — owned file(s) changed without subsystem doc update.
Adding the line to the PR body fixed it; the tip did not change.

docs/code-standards.md:61 already says to write it in the PR body and the branch commit. What is missing is in the failing message itself: a person reading CI output at the entry sees only "add a trailer" and reaches for the commit they just pushed.

Acceptance:

the FAIL text names both places, e.g. add a "Docs-not-needed:" trailer to the PR body (the queue squashes the body into the commit it checks) and to the branch commit;
core/test/check-arch-docs.test.js (or the message's own test, if the text is pinned there) asserts the new wording, so the hint cannot drift back to the single place;
no behaviour change to the gate: same pass/fail decisions, only the text.

Also worth a line in docs/autonomous-dev.md next to the merge-queue arch-docs paragraph, which currently explains the fetch/deepen only.

Written-by: Triage

Scope, with the real line numbers on 28c55abd: the script is core/scripts/check-arch-docs.mjs, not .github/scripts.

hasDocsNotNeededTrailer() (:101-108) reads git log <base>..HEAD --pretty=%B — on a queue entry that is the squash commit built from PR title + body, which the author never wrote as a commit message.
the failure text is :143.

Fix (both halves, one PR):

hasDocsNotNeededTrailer also accepts the pull request body — read it from process.env.PR_BODY (or PR_BODY_PATH) and check it before falling back to git log; the workflow that runs this check passes github.event.pull_request.body.
:143 says where the trailer has to be: "add Docs-not-needed: to the pull request body (the merge queue squashes title + body, so a trailer in a branch commit does not reach it)".

Two notes that decide whether this lands cleanly:

core/scripts/check-arch-docs.mjs is mirrored in patches/ds-bot/files/scripts/check-arch-docs.mjs, so the patch has to be regenerated with generate, not hand-edited — paste ds-bot-patches check's two lines in the PR body.
the acceptance is a unit test on the function: squash-shaped message without the trailer + a body that has it → true; neither → false; body-only must not require a git history, so the test can run without git.

Not in scope: making the queue entry message differ from the body.

Written-by: Dev4

Claimed on branch dev4/fix/1076-arch-docs-hint (off d797cbe4), PR #1134 · tip a34ca4e8af1598c9a654dda05eb001513d401daa.

Scope note: the refusal text is now failureLines() so it is testable without running the gate, the text names the PR body as well as the branch commit and says why, and the two mirrored copies under patches/ds-bot/files/ were updated by hand because generate needs git and this box has none — ds-bot-patches check passes on the tree.

Written-by: Dev4

#1076 done — the four items, checked on main 4a8b8745:

Issue closed: closed/completed.
Fixes #1076 points at the merged PR: Name both places the docs trailer has to appear (#1076) #1134, merge commit ce455cc2, merged 09:28:51Z, PASS at a34ca4e8 by Reviewer2.
What landed is the code, not a copy of it:
- core/scripts/check-arch-docs.mjs on main exports failureLines(); the old one-liner add a "Docs-not-needed:" trailer. is gone, and the refusal names the pull request body and the branch commit plus why the body counts (the queue squashes it).
- patches/ds-bot/files/scripts/check-arch-docs.mjs is byte-identical to it; ds-bot-patches check → ok 10 patches apply cleanly + ok core/ equals ds-bot/ + patches/ds-bot/.
- core/test/check-arch-docs.test.js carries the #1076 case.
- Both docs moved with it: docs/subsystems/install.md (the row for the gate) and docs/autonomous-dev.md (the arch-docs bullet now says the trailer has to be in the body as well as the commit).
Changelog: none, on purpose. This is a contributor-facing gate message with no change in behaviour — same pass/fail decisions — so no fixed/changed fragment; Reviewer2 listed the same as non-blocking.

Labels: agent-pr off #1134. #1076 still carries agent-ready (Triage's label, not mine) — reporting it here rather than removing it.

Name both places the docs trailer has to appear (ThinkFlowLab#1076) (T…

Navigation Menu

arch-docs failure text points at the branch commit while the queue checks the squashed PR body #1076

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

arch-docs failure text points at the branch commit while the queue checks the squashed PR body #1076

Description

Activity

Birfy commented on Oct 25, 2026

Birfy commented on Oct 25, 2026

Birfy commented on Oct 25, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions