feat: give issues and PRs an explicit state machine, so the backlog loop can progress work

[johanzander]

Gives issues and PRs an explicit state machine, so every state has one cheap next action and the Product Owner loop can actually progress work.

Why

The fleet had stalled completely: 8 open PRs, all drafts, 6 CONFLICTING, none ever approved. Four causes, each measurable:

1. The PR lifecycle was collapsed into one column. The digest derived an issue's column as if $pr != null then "In Review", tested first, outranking everything. A never-reviewed draft, a conflicted draft and an approved-and-waiting PR all reported the same state.
2. The only exit from draft cost a full session. Every unfinished draft resolved to /implement-issue at $1-4. Nobody spends five of those in a tick, so the queue only grew.
3. The action list sorted alphabetically. sort_by(.action, ...) put dispatchable above resume_implementation because d < m < r -- every pass led with "start new work" and buried "finish started work".
4. Five of eight PRs edited the same three files. The skill already said to queue same-file work, but it was prose with no gate, so it never fired.

A fifth defect surfaced during design: pr_for returned $matches[0], discarding every PR after the first -- while the project's own no-auto-close rule guarantees an issue has several.

What changed

State model. Status is the phase, Awaiting is the wait, and they are now orthogonal. In Verification names the merged-to-main-but-unreleased period that previously had no representation. Awaiting becomes signed: reporter/upstream/discussion stay quiet because someone else owes us; maintainer is loud and ranks first, inverting a field that previously made an item blocked on you quieter.

advance-pr (new skill). The single copy of the review loop, extracted from implement-issue Step 11 -- not duplicated, moved. It advances exactly one PR by one state and exits, never re-reading the implementation context. Three callers: implement-issue, the rhythm pass, and you.

Flow policy. Actions rank right-to-left across the board (escalations first, then finish before start). WIP limit of 3 counting In Progress + In Review together. A collision gate that refuses to dispatch work touching a file already in flight, and clusters two Ready items that would fight over one file into a single unit.

One issue, many PRs. Every PR carries Refs #N; only the graduation PR carries Closes #N. The issue's column derives from all its open PRs.

Test plan

• 138 targeted tests across test_backlog_digest.py, test_backlog_rhythm.py, test_request_pr_review.py
• 591 in the fast suite; ./scripts/quality-check.sh green after merging origin/main
• Every guard added was verified by mutation -- inverted or removed, test confirmed failing, restored, confirmed passing. Two guards were found untested this way and strengthened.
• Not exercised against the live board: the two board-field additions are deliberately left to the maintainer (see below).

Known gaps, deliberately not fixed here

• The collision gate is inert until predicted_files has a producer. The consumption side is specified and tested; nothing populates it yet, so needs_touch_set fires for every Ready item and dispatchable never appears from the script alone. It fails shut -- it blocks dispatch rather than waving collisions through. The tests fabricate that field, so their passing is not coverage of the missing half.
• pr_board is still read by the scripts although the design retires PR cards. Deferral now reads both card types, so this is safe today and safe to remove later.
• The duplicate-review race is narrowed, not closed. request-pr-review.sh now checks for an in-flight run before posting, but GitHub creates the run seconds after the comment lands, so two callers inside that window can still double-trigger. Closing it needs a check on recent review comments, not runs.

Ordering after merge

1. Add the In Verification Status option and the maintainer Awaiting option to Project . #1, then delete the now-stale note in advance-pr/SKILL.md that says maintainer does not exist yet.
2. Script-side pr_board removal.
3. Only then delete PR cards from the board -- doing it earlier empties $pr_board and un-parks every deferred PR.

Until step 1, the digest computes In Verification and move_card fires for it every tick with no valid target.

Unrelated

backend/tests/test_dashboard_api.py::TestHistoricalDataStatus::test_dismiss_persists_across_requests is order-dependent and fails in some suite orderings. Proven unrelated to this branch: the file is byte-identical to the branch base and it fails with this branch's test files excluded entirely. It passes on this branch as it stands.

🤖 Generated with Claude Code

https://claude.ai/code/session_017uvZsYtTvvyhGFxjGc29kM

[bess-agent]

@claude-bot review

[bess-manager-claude-bot]

Review summary

Linked issue: none — this is self-directed infra work (backlog/PR tooling), not tied to a single GitHub issue. It carries its own design doc (docs/superpowers/specs/2026-08-18-issue-pr-state-machine-design.md) and 13-task plan (docs/superpowers/plans/2026-08-18-issue-pr-state-machine.md), which is this project's established substitute for a root-cause writeup on a change this structural — consistent with prior tooling PRs (#656, #654, #651) that also skip an issue link and a CHANGELOG entry.

Scope: Large diff, but coherent — one state-machine redesign (Status/Awaiting orthogonality, WIP limit, collision gate, advance-pr extraction) touching only .claude/skills/, scripts/backlog-*.sh, scripts/request-pr-review.sh, their tests, and the two doc artifacts. No drive-by changes to unrelated code. CI is green (Fast tests, E2E, Docker boot, Code quality all pass); the PR body's "Unrelated" section correctly disclaims a pre-existing flaky test (test_dismiss_persists_across_requests) rather than silently leaving it unmentioned.

Would the tests catch a regression? Yes. I read through test_backlog_digest.py, test_backlog_rhythm.py, and test_request_pr_review.py in full. Coverage is unusually thorough for the new logic:

• prs_for/multi-PR join (test_an_issue_with_several_prs_reports_all_of_them, test_issue_matched_by_two_prs_emits_one_item_with_both_prs) — regression-tests the exact pr_for → $matches[0] bug called out in the PR body.
• column() precedence (test_an_open_pr_outranks_a_merged_one, test_a_wait_no_longer_rewrites_the_phase, test_a_wait_no_longer_outranks_a_live_worktree) — I traced these against the actual column() jq function (scripts/backlog-digest.sh:393-401) and the assertions match its elif order exactly.
• WIP limit boundary (test_over_the_wip_limit_suppresses_dispatch, test_in_verification_does_not_count_as_wip, test_a_branch_and_its_pr_count_as_one) and the collision gate (queued_behind/cluster/needs_touch_set/undiffable_pr) are each exercised at their edges, not just the happy path.
• request-pr-review.sh's new in-flight gate has both a positive and negative test (test_an_in_flight_review_is_not_re_triggered, test_no_in_flight_run_still_triggers_normally), each proven by an independent side channel (empty token → must never reach gh-agent.sh) rather than by re-asserting internal state — satisfies the "test must be seen to fail without its fix" bar.

These tests verify observable behavior (which action/column/detail string comes out) rather than internal field names or algorithm internals, in line with docs/agents/testing.md.

Rule compliance: No Python source files are touched (tests only), so the Optional/hasattr/sensor-mapping/camelCase rules don't apply here. I didn't find a workaround-shaped fix (no new parameter/flag/second construction site added just to route around an ordering problem) — e.g. the request-pr-review.sh in-flight gate fixes the double-trigger race directly by checking run state before posting, rather than adding a retry/backoff band-aid. scripts/backlog-digest.sh's new gh pr diff loop correctly avoids swallowing errors (undiffable_prs records failures as data instead of 2>/dev/null || true, per its own comment) and doesn't let one bad PR abort the whole digest.

Correctness: Traced the core jq logic (column(), prs_for, merged_pr_for, the WIP/collision-gate block in backlog-rhythm.sh) by hand against the tests and found nothing wrong. request-pr-review.sh's > → >= cutoff change is correct given since can now be set to the in-flight run's own createdAt.

No blockers found. Approving.