spec, master: headless roles must not background gates; tell a stalled revise from a declined one

[mkovero]

Problem

Pipeline roles run headless (bin/*.sh → claude -p / codex exec). On 2026-09-15 three rounds on PR #437 were lost the same way. The role started its cargo gate as a background command and ended its turn to wait for a completion notification that never comes in -p mode, so the process exited with nothing posted:

role	time (UTC)	last words	result
qa	10:04	"Holding here — clippy compiling full workspace in a fresh isolated target dir … Will resume automatically once it finishes."	no review
developer	12:28	"Standing by for the cargo test --workspace background run to finish before posting the PR comment."	fix written, never committed or pushed
qa	12:39	"Waiting on background gate run — will continue the review once notified."	no review

master.sh reported the developer case as a decline: "revise pushed nothing … the block is one only you can clear: a rig measurement, acceptance of an assumed criterion, a design call." The developer had declined nothing. The fix was in the worktree, uncommitted.

Changes (rebased onto main after #458)

.agents/AGENTS.md: new every-role section headless sessions, placed after #458's bounded reading discipline:

• no later turn exists, so never background a command whose result you need
• gate steps run in the foreground, one call each, with the tool timeout at maximum; still foreground when a fresh target dir makes them take minutes
• the deliverable (review comment / push / PR comment / labels) must exist before the turn ends
• a step that can't finish in one call is stated in the comment, not parked
• the three excerpts above are quoted as the concrete bad example

.agents/qa.md, developer.md, codex-qa.md: a pointer where each role runs commands.

bin/master.sh (qa_loop, needs-work → revise), fitted to #458's version of that block:

• Reads the PR comment count before the first revise.sh call. If it can't be read, the revise doesn't start. That is the same fail-closed rule as the tip read.
• bin, spec: pipeline providers, SHA-bound approvals, Codex gate in review, rig-before-approval, epic merge wait #458's retry is unchanged. It fires only on a non-zero revise.sh exit other than an interrupt. A session that backgrounded its gate exits 0, so the retry never covers this case, which is why the distinction below is still needed.
• bin, spec: pipeline providers, SHA-bound approvals, Codex gate in review, rig-before-approval, epic merge wait #458's handback checks (needs-design / needs-ux on the issue) still run first when the tip is unchanged.
• After them, tip unchanged:
  • with a new PR comment: the existing "only you can clear" message
  • without one: "the developer session did not finish. this is NOT a decline", plus the count of uncommitted tracked files in $WT_BASE/<branch> and the session-log command
  • comment count unreadable: both possibilities, no guess
• needs-work and STATE=needs-human stay in every one of those cases.

Verification (on the rebased commit)

• bash -n bin/master.sh: clean. shellcheck -x -S warning bin/master.sh: 0 warnings, same as main.
• bin/ has no test harness, so I used a throwaway one. It sources the rebased master.sh with the top-level dispatch removed, and refuses to source it if that removal did not match. It stubs gh_retry and revise.sh (exit 0), and uses a real git repo as $WT_BASE/<branch>:
  • (a) commented → "the developer commented…", STATE=needs-human
  • (b) no comment, dirty worktree → "this is NOT a decline" + "1 uncommitted tracked file(s)", STATE=needs-human
  • (c) comment count unreadable → "cannot count PR comments…", STATE=needs-human
  • (d) tip moved → labels swapped, no pushed-nothing message
  • (a) does not print the stall text, and (b) prints the uncommitted-file line.
• The spec rule is not mechanically enforceable. claude --help (2.1.272) has no flag that disables background Bash, and --disallowedTools works per tool, not per parameter.

Not in this PR

• architect.md template: its **file manifest** block isn't a ```files fence, which manifest_of requires. The architect manifests on it_loopback_ir's daemon clamps at the -10 dBFS default, not the rig ceiling, when driving real ports #442 and epic EPIC: Close confirmed ac-core and ac-daemon audit findings #423 had to be fenced by hand.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FuCG3RuLHArnC8snRZVDYG