Extract shared readiness-checks spec in pr-flow v1.2.1 by gering · Pull Request #7 · gering/claude-plugins

gering · 2026-06-12T10:36:51Z

Summary

Extracts the duplicated documentation-readiness logic from /open (steps 3c–3f) and /merge (step 8) into one canonical spec, following the proven REVIEW-OUTPUT-FORMAT.md pattern.
Eliminates the drift risk flagged as Prio 4 in the 2026-06 architecture review — /merge step 8 previously had to "mirror /open checks 3c-3f" by hand.
Net reduction of ~674 words of skill prose; both consumer skills shrink (they were near the size limit where instruction-following degrades).

Behavior change (intentional harmonization)

Before this PR, /open and /merge disagreed on the README-freshness check: /open treated touching any *.md file as satisfying it, while /merge counted only README.md. The shared spec adopts /merge's stricter rule, so /open now also warns when user-facing code changed but only a non-README markdown file (e.g. CONTRIBUTING.md) was touched. This is the point of the extraction — one canonical definition — but it does slightly tighten /open's heuristic. The check is advisory only.

Changes

New: plugins/pr-flow/docs/READINESS-CHECKS.md — canonical definitions for the four checks (README freshness, version bump, changelog, knowledge/conventions): detection signals, ✅/⚠️/❌/➖ semantics, auto-fixable vs. manual classification, and a "how consumers apply this" section.
/open 3c–3f now reference the spec; keep only open-specific behavior (auto-resolve fixes in place during the check phase). −563 words.
/merge step 8 now references the spec; keep only merge-specific behavior (read-only inspection, DOC_WARNINGS collection for the step-13 f/m/a decision). −111 words.
README.md: note the shared spec, mirroring how REVIEW-OUTPUT-FORMAT.md is surfaced.
Bump pr-flow 1.2.0 → 1.2.1 (plugin.json + marketplace.json).

Readiness

➖ Uncommitted: only TASK.md (work-system file, intentionally excluded)
✅ README updated
✅ Version bumped 1.2.0 → 1.2.1 (both files in sync)
➖ Changelog: N/A (none in repo)
✅ Knowledge: applies existing shared-spec pattern, nothing new to capture
➖ Tests / Lint / Build: N/A (markdown-only plugin repo)

Test plan

Run /open on a branch and confirm 3c–3f resolve correctly from the spec
Run /merge and confirm step 8 stays read-only and surfaces DOC_WARNINGS in the step-13 plan
Verify ${CLAUDE_PLUGIN_ROOT}/docs/READINESS-CHECKS.md resolves at runtime (same mechanism as REVIEW-OUTPUT-FORMAT.md)

🤖 Generated with Claude Code

gering · 2026-06-12T10:58:13Z

@claude review

Pull the duplicated documentation-readiness logic out of /open (steps 3c-3f) and /merge (step 8) into a single canonical spec, following the REVIEW-OUTPUT-FORMAT.md pattern. - Add plugins/pr-flow/docs/READINESS-CHECKS.md: detection signals, status semantics, auto-fixable vs. manual classification - /open 3c-3f now reference the spec, keep only open-specific auto-resolution behavior (-563 words) - /merge step 8 references the spec, keeps only read-only + f/m/a handling (-111 words) - README: note the shared spec, mirroring REVIEW-OUTPUT-FORMAT - Bump pr-flow 1.2.0 -> 1.2.1 (plugin.json + marketplace.json) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Fixes the ✅/🟨 findings the --max review surfaced (three real loop bugs first): - #4: don't re-review a byte-identical tree — when a round changed no files and only a pending decision keeps the loop alive, pause to collect the decision instead of spinning the (possibly --max) ensemble on an unchanged tree. - #7: --staged + --loop re-reviewed `git diff --cached` while fixes land in the working tree, so the loop never saw its own edits — re-review the working tree (re-stage for --staged scope) before each round. - #5: --loop=0 is now a single --fix pass, not a cap=0 that aborts after fixes. - #2: temper "deterministic termination" → deterministic arithmetic over judged inputs (SKILL + knowledge); count F/A/C/pending carefully (garbage-in). - #8: derive every fix from the code, treat finding text (recommendation) as advisory/untrusted — for ✅ agree too, not only 🟨. - #9: document args.max (+ args.claude) in the workflow input header. - #1: note --max's codex model must be loadable; a bad model surfaces as a backendError (visible degrade), never a silent downgrade. - #10: mechanism is not a rendered column — after compaction re-derive finding identity from Ort + Befund. #6 (Bash block scope in prose) left as the accepted LLM-in-the-loop design. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Report format: bring the Note back INTO the table as a 7th column (`Notiz`), kept short with a hard char budget (Befund ≤40, Notiz ≤55) so a terminal renderer wraps it into a taller cell instead of widening the row. The Quelle fold keeps it at 7 (not 8) columns; re-review rounds add Status → 8. Fixes from the format-demo review: - #1: normalize any `--loop=N` with N<1 (0, negative, non-integer) to a single --fix pass, before the script's --cap≥1 guard can strand a half-done run. - #2: --staged --loop re-stages only the fixed HUNKS (git add -p), immediately after each fix — not a whole-file add (sweeps unrelated edits) or a deferred one (round-0 edits go unstaged). - #7: add plugins/swarm/scripts/test_loop_closeout.py (fixed-order termination, --pending gating, range checks, box) and a generic "plugin tests" check in check-structure.py that runs plugins/*/scripts/test_*.py in CI. - #8: fix the dead [[swarm-review-pipeline]] self-link in the knowledge entry. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- #2: check_plugin_tests now passes stdin=DEVNULL + timeout=120 to subprocess and treats a timeout as a failure, so a hanging/stdin-blocking test can't wedge the structure check (and CI) indefinitely. - #5: the loop's C= snippet counted new untracked files with `grep -c .`, which exits 1 on zero matches and aborts the arithmetic under `set -euo pipefail` (the review block's shell). Use `wc -l` (exit 0), symmetric with the first term. Verified under strict shell across clean/modified/new-file cases. - #7: knowledge/ci-structure-checks.md now documents the fifth check (plugin tests) the last commit added. Left as accepted residuals: #1 (C misses edits to pre-existing untracked files — rare, documented), #3 (CI arbitrary-code surface — safe under GH fork-PR defaults), #4/#6 (LLM-in-the-loop scope + in-session loop state, by design). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

First dogfooding run: /swarm:review --fix over its own diff (4 cluster finders + codex + grok-4.5 + composer; 13 findings, 5 cross-family consensus). Fixes the agreed findings: - Keep validly tagged off-cluster lens prefixes: validate against the global lens set, not the finder's subset — coercion could flip kind and route a real defect through the applicability verifier (#1, consensus critical) - Verify design clusters even with cross-family consensus: agreement attests agreement, not repo-grounded applicability (externals cannot open repo files); defect consensus stays auto-accepted (#2) - Untagged external findings ('unspecified' lens) no longer vote in the cluster-kind derivation (#3) - Derive CANDIDATE_LENSES from LENS_CLUSTERS — one list, no unchecked mirror; DRIFT WARNING on the SKILL.md external-prompt copy (#4, #9) - Finder prompt: "issue (defect or substantive improvement)" + all lens prefixes; external prompt lead covers design improvements too (#5, #6) - pr-post.py owns design-row ordering + [lens] prefixing via optional kind/lens row fields, unit-tested; SKILL.md step 5 passes rows through verbatim (#13) - Doc sync: balance-spec finder count, README canonical cluster names + preset teaser wording, knowledge-index line trimmed (#8, #10, #11, #12) Declined: #7 (per-cluster dilutes per-lens depth) — deliberate, documented cost/coverage trade-off; --max is the depth profile. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0126cGxsBYxqgEFH4AcpriNk

Second dogfooding round at the deepest profile (/swarm:review --max --fix: per-lens split live — gate pruned style, 10 xhigh finders + codex gpt-5.6-sol@xhigh + grok-4.5 + composer; 24 findings, 10 consensus). Fixes the agreed findings: - Never auto-accept an all-untagged consensus cluster: no tagged lens backs it, so it is verified like a solo. Verify/auto-accept now derive from ONE needsVerify predicate (structural exactly-once partition); kind vote in clearer every-form (#1, consensus critical; #21, #22) - Design verifier sees the finding's recommendation — the proposal the applicability rubric actually tests — and carries an escape hatch: a genuine defect mis-filed under a design lens is not refuted away (#12, #3); "solo" dropped from verifier prompts (#4) - Untagged findings from multi-lens cluster finders fall back to 'unspecified' (safe defect bucket), not lenses[0] (#7); merge-agent free-text lens validated, majority-member fallback (#9) - Improvement invitation scoped to design finder units — defect-lens finders stay defect-only (#8); merge prompt clusters by issue, not only defect (#13); schema descriptions generalized for design findings (#14) - LENS_BRIEF startup assertion (#6); gate prompt interpolates LENS_CLUSTERS.design (#19); new test_lens_sync.py guards all lens mirrors: SKILL HDR prompt, LENS_BRIEF, pr-post DESIGN_LENSES (#5) - Workflow assigns stable finding num (defects first, shared sequence); presenter/pr-post render it verbatim (#20) - pr-post.py: design lens is the backup kind signal when the handoff drops kind (explicit defect still wins); single-pass partition (#17, #24) - Balance: REFUTED is its own segment (refuted ⊄ solo since design consensus can be refuted) (#2); LOCKED design-table column precedence in --loop rounds clarified (#11); "verifies solos" doc sweep across manifests/README/knowledge (#4); cluster failure-isolation trade-off documented (#10); knowledge index line trimmed (#15) Declined: #16 (JS test harness for sandbox code; lens-sync test covers the drift class), #18 (gate-fail under --max runs all lenses — the documented never-silently-narrower degrade), #23 (micro-opt vs readability). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0126cGxsBYxqgEFH4AcpriNk

- default get now VALIDATES the committed value against the registry: a stale/ removed/attacker-supplied name (from a cloned repo) reads as "no default" → picker, instead of routing or bricking every no-flag kickoff (#1). kickoff also announces a non-claude project default before launch — visibility, not a prompt, so a committed default can't silently route your code off-Claude (#1 security). - grok probe: when neither `timeout` nor `gtimeout` exists, skip `grok models` and return inconclusive (trust auth) rather than risk an unbounded call that hangs the picker (#2). - kickoff argument grammar: `--agent` consumes the next token as its value, so it isn't mistaken for the task name (#4). - agent-registry.sh committed executable (100755), matching herdr-launch.sh, so the documented direct invocation works (#5). - kickoff "Critical" note: step 12 → step 13 cross-ref (launch was renumbered) (#6). - `supports=` comment marked RESERVED/not-yet-consumed (a seed for the orchestration design), not "already driving" degradation (#7). - herdr-launch bad-mode usage string shows the launch arity incl. [agent-selector] (#8). - continue reopen: note reworded to match behavior (`claude -c` IS always sent) and the codex/grok caveat surfaced inline in the success report (#3). Not changed (reviewed): README model-id duplication (accepted human-facing docs), CHANGELOG paragraph (matches repo style); per-task worker persistence for a true per-CLI resume stays a later idea. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NjTKpmBkXxxYkn7orMfZCC

First dogfooding run: /swarm:review --fix over its own diff (4 cluster finders + codex + grok-4.5 + composer; 13 findings, 5 cross-family consensus). Fixes the agreed findings: - Keep validly tagged off-cluster lens prefixes: validate against the global lens set, not the finder's subset — coercion could flip kind and route a real defect through the applicability verifier (#1, consensus critical) - Verify design clusters even with cross-family consensus: agreement attests agreement, not repo-grounded applicability (externals cannot open repo files); defect consensus stays auto-accepted (#2) - Untagged external findings ('unspecified' lens) no longer vote in the cluster-kind derivation (#3) - Derive CANDIDATE_LENSES from LENS_CLUSTERS — one list, no unchecked mirror; DRIFT WARNING on the SKILL.md external-prompt copy (#4, #9) - Finder prompt: "issue (defect or substantive improvement)" + all lens prefixes; external prompt lead covers design improvements too (#5, #6) - pr-post.py owns design-row ordering + [lens] prefixing via optional kind/lens row fields, unit-tested; SKILL.md step 5 passes rows through verbatim (#13) - Doc sync: balance-spec finder count, README canonical cluster names + preset teaser wording, knowledge-index line trimmed (#8, #10, #11, #12) Declined: #7 (per-cluster dilutes per-lens depth) — deliberate, documented cost/coverage trade-off; --max is the depth profile. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0126cGxsBYxqgEFH4AcpriNk

Second dogfooding round at the deepest profile (/swarm:review --max --fix: per-lens split live — gate pruned style, 10 xhigh finders + codex gpt-5.6-sol@xhigh + grok-4.5 + composer; 24 findings, 10 consensus). Fixes the agreed findings: - Never auto-accept an all-untagged consensus cluster: no tagged lens backs it, so it is verified like a solo. Verify/auto-accept now derive from ONE needsVerify predicate (structural exactly-once partition); kind vote in clearer every-form (#1, consensus critical; #21, #22) - Design verifier sees the finding's recommendation — the proposal the applicability rubric actually tests — and carries an escape hatch: a genuine defect mis-filed under a design lens is not refuted away (#12, #3); "solo" dropped from verifier prompts (#4) - Untagged findings from multi-lens cluster finders fall back to 'unspecified' (safe defect bucket), not lenses[0] (#7); merge-agent free-text lens validated, majority-member fallback (#9) - Improvement invitation scoped to design finder units — defect-lens finders stay defect-only (#8); merge prompt clusters by issue, not only defect (#13); schema descriptions generalized for design findings (#14) - LENS_BRIEF startup assertion (#6); gate prompt interpolates LENS_CLUSTERS.design (#19); new test_lens_sync.py guards all lens mirrors: SKILL HDR prompt, LENS_BRIEF, pr-post DESIGN_LENSES (#5) - Workflow assigns stable finding num (defects first, shared sequence); presenter/pr-post render it verbatim (#20) - pr-post.py: design lens is the backup kind signal when the handoff drops kind (explicit defect still wins); single-pass partition (#17, #24) - Balance: REFUTED is its own segment (refuted ⊄ solo since design consensus can be refuted) (#2); LOCKED design-table column precedence in --loop rounds clarified (#11); "verifies solos" doc sweep across manifests/README/knowledge (#4); cluster failure-isolation trade-off documented (#10); knowledge index line trimmed (#15) Declined: #16 (JS test harness for sandbox code; lens-sync test covers the drift class), #18 (gate-fail under --max runs all lenses — the documented never-silently-narrower degrade), #23 (micro-opt vs readability). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0126cGxsBYxqgEFH4AcpriNk

- default get now VALIDATES the committed value against the registry: a stale/ removed/attacker-supplied name (from a cloned repo) reads as "no default" → picker, instead of routing or bricking every no-flag kickoff (#1). kickoff also announces a non-claude project default before launch — visibility, not a prompt, so a committed default can't silently route your code off-Claude (#1 security). - grok probe: when neither `timeout` nor `gtimeout` exists, skip `grok models` and return inconclusive (trust auth) rather than risk an unbounded call that hangs the picker (#2). - kickoff argument grammar: `--agent` consumes the next token as its value, so it isn't mistaken for the task name (#4). - agent-registry.sh committed executable (100755), matching herdr-launch.sh, so the documented direct invocation works (#5). - kickoff "Critical" note: step 12 → step 13 cross-ref (launch was renumbered) (#6). - `supports=` comment marked RESERVED/not-yet-consumed (a seed for the orchestration design), not "already driving" degradation (#7). - herdr-launch bad-mode usage string shows the launch arity incl. [agent-selector] (#8). - continue reopen: note reworded to match behavior (`claude -c` IS always sent) and the codex/grok caveat surfaced inline in the success report (#3). Not changed (reviewed): README model-id duplication (accepted human-facing docs), CHANGELOG paragraph (matches repo style); per-task worker persistence for a true per-CLI resume stays a later idea. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NjTKpmBkXxxYkn7orMfZCC

First dogfooding run: /swarm:review --fix over its own diff (4 cluster finders + codex + grok-4.5 + composer; 13 findings, 5 cross-family consensus). Fixes the agreed findings: - Keep validly tagged off-cluster lens prefixes: validate against the global lens set, not the finder's subset — coercion could flip kind and route a real defect through the applicability verifier (#1, consensus critical) - Verify design clusters even with cross-family consensus: agreement attests agreement, not repo-grounded applicability (externals cannot open repo files); defect consensus stays auto-accepted (#2) - Untagged external findings ('unspecified' lens) no longer vote in the cluster-kind derivation (#3) - Derive CANDIDATE_LENSES from LENS_CLUSTERS — one list, no unchecked mirror; DRIFT WARNING on the SKILL.md external-prompt copy (#4, #9) - Finder prompt: "issue (defect or substantive improvement)" + all lens prefixes; external prompt lead covers design improvements too (#5, #6) - pr-post.py owns design-row ordering + [lens] prefixing via optional kind/lens row fields, unit-tested; SKILL.md step 5 passes rows through verbatim (#13) - Doc sync: balance-spec finder count, README canonical cluster names + preset teaser wording, knowledge-index line trimmed (#8, #10, #11, #12) Declined: #7 (per-cluster dilutes per-lens depth) — deliberate, documented cost/coverage trade-off; --max is the depth profile. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0126cGxsBYxqgEFH4AcpriNk

Second dogfooding round at the deepest profile (/swarm:review --max --fix: per-lens split live — gate pruned style, 10 xhigh finders + codex gpt-5.6-sol@xhigh + grok-4.5 + composer; 24 findings, 10 consensus). Fixes the agreed findings: - Never auto-accept an all-untagged consensus cluster: no tagged lens backs it, so it is verified like a solo. Verify/auto-accept now derive from ONE needsVerify predicate (structural exactly-once partition); kind vote in clearer every-form (#1, consensus critical; #21, #22) - Design verifier sees the finding's recommendation — the proposal the applicability rubric actually tests — and carries an escape hatch: a genuine defect mis-filed under a design lens is not refuted away (#12, #3); "solo" dropped from verifier prompts (#4) - Untagged findings from multi-lens cluster finders fall back to 'unspecified' (safe defect bucket), not lenses[0] (#7); merge-agent free-text lens validated, majority-member fallback (#9) - Improvement invitation scoped to design finder units — defect-lens finders stay defect-only (#8); merge prompt clusters by issue, not only defect (#13); schema descriptions generalized for design findings (#14) - LENS_BRIEF startup assertion (#6); gate prompt interpolates LENS_CLUSTERS.design (#19); new test_lens_sync.py guards all lens mirrors: SKILL HDR prompt, LENS_BRIEF, pr-post DESIGN_LENSES (#5) - Workflow assigns stable finding num (defects first, shared sequence); presenter/pr-post render it verbatim (#20) - pr-post.py: design lens is the backup kind signal when the handoff drops kind (explicit defect still wins); single-pass partition (#17, #24) - Balance: REFUTED is its own segment (refuted ⊄ solo since design consensus can be refuted) (#2); LOCKED design-table column precedence in --loop rounds clarified (#11); "verifies solos" doc sweep across manifests/README/knowledge (#4); cluster failure-isolation trade-off documented (#10); knowledge index line trimmed (#15) Declined: #16 (JS test harness for sandbox code; lens-sync test covers the drift class), #18 (gate-fail under --max runs all lenses — the documented never-silently-narrower degrade), #23 (micro-opt vs readability). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0126cGxsBYxqgEFH4AcpriNk

- Bound EVERY external-CLI probe: factor out run_bounded (timeout/gtimeout, else a self-watchdog that escalates SIGTERM -> SIGKILL) and use it for codex `login status` (was completely unbounded) and grok `models`. Its stdout goes to a temp file so an orphaned grandchild can't hold the command-substitution pipe open — verified a SIGTERM-ignoring probe is now killed at ~12s, not left to hang the picker (#4). - kickoff manual (non-herdr) block no longer auto-persists the project default: it only prints a command, so no launch is confirmed — tell the user to run `default set` once the worker is up, matching the herdr path's "persist only after a successful launch" rule (#2). - kickoff picker: set OFFER_DEFAULT from the interpreted Yes/No answer, not a literal label match, so the save-as-default gate can't miss on case (#3). - knowledge: add the missing `prime:` key to the new entry (#6); refresh the stale herdr-kickoff-automation entry (step 13, registry-resolved worker argv, not a hardcoded `claude … /continue`) (#7). Not changed: the committed-external-default consent gate (#1) stays announce-not- prompt (a settled product decision); herdr-launch's `${0%/*}` sibling lookup (#5) is latent and matches the file's existing convention (callers always pass an absolute path). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NjTKpmBkXxxYkn7orMfZCC

Mostly real regressions from the round-4 batch, caught by the re-review: - run_bounded: add `-k 1` to the timeout/gtimeout branches. GNU timeout only SIGTERMs at the deadline then waits, so a SIGTERM-ignoring probe ran forever on the COMMON path (any host with a timeout binary — e.g. all Linux CI); --kill-after escalates to SIGKILL like the self-watchdog. Normalize a bounded kill to a single 124 "timed out" code (#4). - codex probe: a run_bounded timeout (124) is now inconclusive -> assume available (mirrors grok), not a genuine auth failure — a slow `codex login status` no longer tells a logged-in user to re-login and disables the backend (#5). - grok probe: match the model id as a SUBSTRING of the raw `grok models` output (here-string, no pipe) instead of a positional awk field + exact-line grep, so a reformatted listing can't yield a wrong token and a false "model not offered" (#6). - project default resolves the MAIN repo root via --git-common-dir, so a `default set` run from inside a linked worktree lands in the main checkout, not the disposable worktree copy (#3). - kickoff manual path: the main-repo session runs `default set` after the user confirms the worker started — not a command for the user's terminal, where $REG is undefined and the cwd is the worktree (#2). - knowledge: correct the herdr-kickoff entry's grok argv (`grok -m …`, not codex) (#7). Not changed: committed-external-default consent gate (#1) — settled announce-not- prompt product decision. Verified: gtimeout -k bounds a SIGTERM-ignoring probe at ~11s; a hung codex probe reads available; `default set` from the worktree writes the main repo. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NjTKpmBkXxxYkn7orMfZCC

- default get now VALIDATES the committed value against the registry: a stale/ removed/attacker-supplied name (from a cloned repo) reads as "no default" → picker, instead of routing or bricking every no-flag kickoff (#1). kickoff also announces a non-claude project default before launch — visibility, not a prompt, so a committed default can't silently route your code off-Claude (#1 security). - grok probe: when neither `timeout` nor `gtimeout` exists, skip `grok models` and return inconclusive (trust auth) rather than risk an unbounded call that hangs the picker (#2). - kickoff argument grammar: `--agent` consumes the next token as its value, so it isn't mistaken for the task name (#4). - agent-registry.sh committed executable (100755), matching herdr-launch.sh, so the documented direct invocation works (#5). - kickoff "Critical" note: step 12 → step 13 cross-ref (launch was renumbered) (#6). - `supports=` comment marked RESERVED/not-yet-consumed (a seed for the orchestration design), not "already driving" degradation (#7). - herdr-launch bad-mode usage string shows the launch arity incl. [agent-selector] (#8). - continue reopen: note reworded to match behavior (`claude -c` IS always sent) and the codex/grok caveat surfaced inline in the success report (#3). Not changed (reviewed): README model-id duplication (accepted human-facing docs), CHANGELOG paragraph (matches repo style); per-task worker persistence for a true per-CLI resume stays a later idea. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NjTKpmBkXxxYkn7orMfZCC

- Bound EVERY external-CLI probe: factor out run_bounded (timeout/gtimeout, else a self-watchdog that escalates SIGTERM -> SIGKILL) and use it for codex `login status` (was completely unbounded) and grok `models`. Its stdout goes to a temp file so an orphaned grandchild can't hold the command-substitution pipe open — verified a SIGTERM-ignoring probe is now killed at ~12s, not left to hang the picker (#4). - kickoff manual (non-herdr) block no longer auto-persists the project default: it only prints a command, so no launch is confirmed — tell the user to run `default set` once the worker is up, matching the herdr path's "persist only after a successful launch" rule (#2). - kickoff picker: set OFFER_DEFAULT from the interpreted Yes/No answer, not a literal label match, so the save-as-default gate can't miss on case (#3). - knowledge: add the missing `prime:` key to the new entry (#6); refresh the stale herdr-kickoff-automation entry (step 13, registry-resolved worker argv, not a hardcoded `claude … /continue`) (#7). Not changed: the committed-external-default consent gate (#1) stays announce-not- prompt (a settled product decision); herdr-launch's `${0%/*}` sibling lookup (#5) is latent and matches the file's existing convention (callers always pass an absolute path). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NjTKpmBkXxxYkn7orMfZCC

Mostly real regressions from the round-4 batch, caught by the re-review: - run_bounded: add `-k 1` to the timeout/gtimeout branches. GNU timeout only SIGTERMs at the deadline then waits, so a SIGTERM-ignoring probe ran forever on the COMMON path (any host with a timeout binary — e.g. all Linux CI); --kill-after escalates to SIGKILL like the self-watchdog. Normalize a bounded kill to a single 124 "timed out" code (#4). - codex probe: a run_bounded timeout (124) is now inconclusive -> assume available (mirrors grok), not a genuine auth failure — a slow `codex login status` no longer tells a logged-in user to re-login and disables the backend (#5). - grok probe: match the model id as a SUBSTRING of the raw `grok models` output (here-string, no pipe) instead of a positional awk field + exact-line grep, so a reformatted listing can't yield a wrong token and a false "model not offered" (#6). - project default resolves the MAIN repo root via --git-common-dir, so a `default set` run from inside a linked worktree lands in the main checkout, not the disposable worktree copy (#3). - kickoff manual path: the main-repo session runs `default set` after the user confirms the worker started — not a command for the user's terminal, where $REG is undefined and the cwd is the worktree (#2). - knowledge: correct the herdr-kickoff entry's grok argv (`grok -m …`, not codex) (#7). Not changed: committed-external-default consent gate (#1) — settled announce-not- prompt product decision. Verified: gtimeout -k bounds a SIGTERM-ignoring probe at ~11s; a hung codex probe reads available; `default set` from the worktree writes the main repo. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NjTKpmBkXxxYkn7orMfZCC

Address swarm review findings on the settings CLI (all in settings.py): - TOML string values now escape control chars (\n, \t, … via short forms + \uXXXX), so a value with a newline no longer writes a file tomllib refuses to reparse (#1). - dump_toml quotes table-name and key segments that aren't bare-key-safe, so a related_projects entry like `web api` / `a.b` survives a rewrite (#7). - config_filename rejects any x-config-file that isn't a plain basename (absolute, `..`, `~`, nested), so a malformed schema can't write/unlink outside the project root (#3). - `set` classifies the target against the schema: setting a section (#5) or descending past a scalar leaf (#8) is now a clear error, not a crash or silent mis-nest. - `set` gates the write on schema validity — a coerced array with wrong element types (#4) or a mistyped dynamic related_projects field (#6) is refused instead of silently writing an invalid config. Tests: serializer round-trip (control chars + non-bare keys), config-filename sandbox, and the four set-path guards. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ToUjTdtMa9oXUwjfgERkXL

External-only swarm review (codex + grok) on PR #42. Apply the agreed findings to the decision record: - AMQ send vs single-sequencer: workers send only to the Manager handle; Manager relays. `amq send --to <peer>` bypasses the sequencer (#1). - Broadcast: reuse AMQ fan-out/presence/federation instead of hand-rolled multi-writer global.jsonl (the model Maildir superseded) (#2). - Lane lifecycle: drain-on-/close + stale-mail guard so a reused path never reconsumes a prior occupant's undrained message (#3). - Soften the "RESOLVES" overclaim: this ADR supersedes the herdr docs' enum; their refresh is pending (#4). - Canonicalize the lane key via git rev-parse --show-toplevel, not raw cwd (#7). - Fix ws-statusline states flag order: `states [--cached] <dir>` (#10). - _index.md blurb: central ~/.agent-mail/ mailbox, not the superseded .mailbox/ protocol (always-loaded surface) (#11). - Note the spike is decided, no open task file (#12). - Trust-model residuals (convention-based identity, home-dir readable store) as accepted for a single-user local tool (#5, #6). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LTZx9DqrXPXQFoTrCvcJmD

Address swarm review findings on the settings CLI (all in settings.py): - TOML string values now escape control chars (\n, \t, … via short forms + \uXXXX), so a value with a newline no longer writes a file tomllib refuses to reparse (#1). - dump_toml quotes table-name and key segments that aren't bare-key-safe, so a related_projects entry like `web api` / `a.b` survives a rewrite (#7). - config_filename rejects any x-config-file that isn't a plain basename (absolute, `..`, `~`, nested), so a malformed schema can't write/unlink outside the project root (#3). - `set` classifies the target against the schema: setting a section (#5) or descending past a scalar leaf (#8) is now a clear error, not a crash or silent mis-nest. - `set` gates the write on schema validity — a coerced array with wrong element types (#4) or a mistyped dynamic related_projects field (#6) is refused instead of silently writing an invalid config. Tests: serializer round-trip (control chars + non-bare keys), config-filename sandbox, and the four set-path guards. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ToUjTdtMa9oXUwjfgERkXL

Apply the agreed findings from a local swarm review (11 ✅ + 1 🟨; the 3 ❌ — a feature version bump, a README inventory line, and a per-subcommand python3 guard — were deliberately left, see the PR discussion). herdr-agent.sh: - Bound herdr list/get/read with a wall-clock timeout (_ha_bounded: timeout → gtimeout → perl alarm), honouring the header's "never a hang" promise. wait stays governed by its own --timeout. (#6) - ha_wait now detects the --timeout=MS form too, so a caller's explicit bound in either spelling is honoured and no duplicate flag is appended. (#7) - A missing <target> returns usage code 2, not 4 (server-unreachable), so a programmer error is not mistaken for a transient outage. (#12) - set -u is enabled only on the executed-CLI path, never at source time, so sourcing for the prelude/helpers no longer mutates the caller's shell. (#13) - classify_cwd returns the resolved path as a third tuple element, so a caller keying by full path reuses it instead of a second realpath. (#14) lanes.sh: - Scrub tab/CR/LF from every TSV cell: agent-derived fields are untrusted, and an embedded tab/newline would forge columns/rows. Mirrors herdr-tab-glyph. (#1) - Guard the agent loop against non-dict (null) elements → never crash, always exit 0. (#2) - flush() now calls the shared classify_cwd instead of re-open-coding the task rule, so the classification can't drift between the two consumers. (#15) - Resolve SCRIPT_DIR via BASH_SOURCE (robust to bare-name invocation). (#5) - Header wording: exit-0 scope clarified; --json emits [] when no lanes. (#3, #8) herdr-tab-glyph.sh: consume classify_cwd's new 3-tuple; same BASH_SOURCE fix (#5). herdr-tab-glyphs.md: point at $HERDR_MATCH_PRELUDE as the shared match SoT. (#10) Tests extended: null-element + TSV-injection (lanes); --timeout= + missing-target exit 2 (herdr-agent). Regression: herdr-tab-glyph output byte-identical vs a live snapshot. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R8crYp6tzRKMiwW63Zt3GG

A second local swarm review (mostly regressions surfaced by the round-1 fixes); 7 agreed findings applied, 3 declined (a misread pluginVersion, the re-raised per-subcommand python3 guard, and a 3-file DRY extraction left as a follow-up). herdr-agent.sh: - ha_wait now runs under _ha_bounded too, sized ABOVE the server --timeout (+5s), so a wedged server can't hang it either — the "never a hang" contract now holds for every wrapper. _ha_bounded takes the bound as an argument. (#1) - get/read/wait reject a leading-dash <target> (usage code 2) so an untrusted id can't be parsed as an option flag, matching herdr-tab-glyph's guard. (#3) lanes.sh: - Coerce every liveness cell to str (_s): a non-string herdr field (e.g. numeric agent_status) no longer crashes the TSV scrub / mistypes the JSON. (#2) - A malformed (non-dict) list element now fails unmatched lanes closed to "unverified" — a partly-untrustworthy list can't assert "no worker". (#4) - Every --json early-exit emits [] (not empty stdout), so json.loads never chokes; the header contract is now fully honoured. (#5) - Drop the dead `import os` from lanes_join (the prelude imports it). (#7) herdr-tab-glyph.sh: cmd_refresh calls the bounded ha_list instead of a raw `herdr agent list`, so a wedged server can't hang a glyph refresh. (#6) Tests extended: leading-dash reject + bounded wait (herdr-agent); non-string field, malformed→unverified, and []-on-empty (lanes). check-structure green, classification byte-identical vs the live snapshot. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R8crYp6tzRKMiwW63Zt3GG

A third swarm review (--fix) over the accumulated diff; 6 agreed findings applied, 4 declined (the recurring feature version bump — user decided against it; a premature _ha_validate_dict helper; a theoretical states-via-argv ARG_MAX; and the 3-file run_bounded DRY extraction, still a follow-up). herdr-agent.sh: - ha_get validates with an explicit if/exit instead of `assert` — `python3 -O` / PYTHONOPTIMIZE strips asserts, which would silently pass a malformed body. (#1) - Factor the <target> guard (empty + leading-dash) into one _ha_check_target helper the three wrappers share, instead of three copy-pasted case lines. (#7) herdr-tab-glyph.sh: - extract_glyph_tabs guards non-dict agents/tabs elements (isinstance), mirroring the lanes.sh hardening, so a null element can't abort a whole refresh. (#3) - Bound `herdr tab list` via _ha_bounded too: ha_list already bounds the agent call, but a server wedging on the tab-list call would still hang refresh. (#4) lanes.sh / herdr-agent.sh: chmod +x — both carry a shebang and a CLI Usage header, so they now match the executable sibling CLIs (ws-statusline.sh, …). (#5) Tests: an INTEGRATION test drives the real HERDR_ENV → ha_list → mktemp → trap → join glue with a fake herdr on PATH (previously only the env seam was covered); classification stays byte-identical vs the live snapshot. (#8) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R8crYp6tzRKMiwW63Zt3GG

gering force-pushed the task/extract-readiness-checks-spec branch from 0f1a13f to aa709ac Compare June 12, 2026 14:25

gering merged commit 1123e95 into main Jun 12, 2026
1 check passed

gering deleted the task/extract-readiness-checks-spec branch June 12, 2026 17:27

Navigation Menu

Extract shared readiness-checks spec in pr-flow v1.2.1 - #7

Extract shared readiness-checks spec in pr-flow v1.2.1#7
gering merged 1 commit into
mainfrom
task/extract-readiness-checks-spec

gering commented Jun 12, 2026 •

edited

Loading

Uh oh!

gering commented Jun 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

gering commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Behavior change (intentional harmonization)

Changes

Readiness

Test plan

Uh oh!

gering commented Jun 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

gering commented Jun 12, 2026 •

edited

Loading