rework_required has no autonomous exit: pre_check_batch passes but stage_a_passed never fires, and the only offered remedy is the human-only /swarm recover

[andrewjfiore]

Summary

Once a task is in rework_required, there is no autonomous transition back to a state where Stage B can be re-dispatched. The tool's own remediation is a human-only command.

Version

opencode-swarm@7.179.1 on OpenCode 1.18.21, Windows 11. The relevant files are byte-identical on the 7.180.0 release branch.

Reproduction

1. Task 1.1 reaches Stage B with correct code (reviewer APPROVED).
2. test_engineer returns a non-PASS verdict for a tool-argument reason (see the companion issue on SKIPPED). The task moves to rework_required.
3. Architect re-dispatches test_engineer. Refused:

TASK_WORKFLOW_STAGE_A_REQUIRED: cannot dispatch test_engineer for task 1.1 from rework_required.
Stage B (test_engineer) requires the task to be at pre_check_passed (or later) - a state written only
by the stage_a_passed transition, which is emitted when pre_check_batch completes with the task
correctly attributed. Remediation: run pre_check_batch on the task's changed files first. If
pre_check_batch passes but the task remains coder_delegated (typical after /swarm reset-session),
run /swarm recover 1.1 to repair Stage A attribution, then re-dispatch.

4. Architect runs pre_check_batch on the task's changed files. It returns gates_passed: true, but check_gate_status still shows "workflow": { "state": "rework_required", "generation": 1 }. The stage_a_passed transition does not fire from rework_required.
5. Re-dispatching test_engineer is refused again with the identical error.
6. The remaining remedy in the error text is /swarm recover 1.1, which is not available to the architect.

The architect had no legal move left. In our run it stopped correctly (kept the deliverables, wrote a blocked report), but the run could not complete.

Where it happens

• src/hooks/delegation-gate.ts (around line 4459): TASK_WORKFLOW_STAGE_A_REQUIRED for Stage B from a non-pre_check_passed state.
• src/hooks/gate-evidence.ts (around lines 647-655): from rework_required the reducer requires a new coder mutation (TASK_WORKFLOW_CODER_MUTATION_REQUIRED), so a passing pre_check_batch alone does not advance the state.

Expected

One of:

• a passing pre_check_batch from rework_required re-emits stage_a_passed so Stage B can be re-dispatched, or
• an architect-facing repair tool (the analogue of approve_plan_critic / repair_gate_evidence) that performs what /swarm recover <task> does for this case, or
• the error text stops recommending a command the architect cannot run.

Impact

A single tool-argument mistake by a subagent strands a task with correct, reviewed, passing code, and only a human can free it. For unattended runs this is a hard stop caused by state bookkeeping, not by the work.

Related: #2664 (Stage A attribution routes), #2703 (a gate with no recovery tool).

[zaxbysauce]

Fix delivered in #2760 (fix(workflow): architect-only audited exit from rework_required).

What changed

• New architect-only tool recover_rework_task (task_id + audited reason): writes a supervised stage_a_passed for the task's current generation so reviewer/test_engineer can be re-dispatched WITHOUT re-running the coder. Durable transition id is prefixed rework-recovery:; an audit event (stage_a_repair, action rework_recovered, with your reason) lands in .swarm/events.jsonl.
• Fail-closed preconditions: active architect session, exact plan task id, durable state exactly rework_required, and green pre-check proof for the wedged generation (both secretscan and sast_scan bundles green AND newer than the failing verdict — the same bar /swarm recover's Stage A repair uses). SAST-disabled projects fail closed by design (the [Workstream A] PR 10 of 12: Connect existing task recovery and status to authoritative transition receipts #2665 trade-off).
• Guardrail semantics unchanged: the mechanical stage_a_passed path still throws TASK_WORKFLOW_CODER_MUTATION_REQUIRED from rework_required (a real code defect still needs the coder repair loop), and /swarm recover's auto-scan still skips this state.
• The TASK_WORKFLOW_STAGE_A_REQUIRED dispatch refusal is now state-specific: from rework_required it names recover_rework_task instead of the human-only /swarm recover; the coder_delegated attribution-wedge guidance keeps /swarm recover where it genuinely applies.

How to use it: when Stage B fails without a code defect, re-run pre_check_batch (so the green bundles postdate the verdict), then call recover_rework_task with the task id and a reason; re-dispatch the Stage B gates the failed verdict cleared.

Migration: none — no schema, config, or state migration; the new transition is an ordinary durable workflow event.

Sibling scope note: #2756 (SKIPPED scored as stage_b_failed), #2757 (per-task critic gate), and #2758 (guardrails mislabeling CODER_MUTATION_REQUIRED as an attribution miss) remain open and untouched, per this issue's own AC boundary.

[zaxbysauce]

Confirmed against the code in this tree (v7.180.1).

• The durable reducer only accepts the mechanical stage_a_passed transition from coder_delegated (src/gate-evidence.ts:647-653 throws TASK_WORKFLOW_CODER_MUTATION_REQUIRED otherwise), so a passing pre_check_batch genuinely cannot advance a rework_required task — step 4 of the reproduction is the designed reducer behavior, not a fluke.
• The Stage B dispatch refusal at src/hooks/delegation-gate.ts:4459-4461 matches the quoted error and its remediation text recommends pre_check_batch and then /swarm recover <task>.
• Critically, /swarm recover cannot help here either: its Stage A repair (src/workflow/stage-a-repair.ts:221-232) only treats coder_delegated-with-missing-pre-check-proof as wedged and returns skipped_not_wedged for rework_required. So the error text is advertising a remedy that provably does not fire for this state.
• Unlike the plan-critic and gate-evidence wedges, which have agent-facing escapes (approve_plan_critic, repair_gate_evidence, both registered in src/tools/manifest.ts), there is no architect-callable recovery tool for rework_required in this tree — slash commands are human-only by design (see the approve-plan-critic command's note that agents must use the tool instead).

Net effect matches the report: one non-PASS Stage B verdict with no code defect strands a reviewed, green task in rework_required with no autonomous exit, which is a hard stop for unattended runs.

A note on status: a maintainer comment on this issue says the fix landed in #2760 (an architect-only recover_rework_task tool with audited, fail-closed preconditions). That tool does not exist anywhere in this checkout at 7.180.1, so this tree still exhibits the wedge end-to-end. Anyone picking this up should first check whether #2760 is merged downstream and rebase on it; the fix shape described there (re-emit a supervised stage_a_passed for the current generation, keep the mechanical TASK_WORKFLOW_CODER_MUTATION_REQUIRED guardrail intact, and make the TASK_WORKFLOW_STAGE_A_REQUIRED refusal state-specific) addresses all three remedies proposed in the issue. The minimal interim fix is to stop recommending /swarm recover from rework_required in the refusal text.

Related context: #2756 is the trigger cited in the reproduction (SKIPPED verdict scored as stage_b_failed), #2758 is the sibling complaint about guardrails mislabeling TASK_WORKFLOW_CODER_MUTATION_REQUIRED as an attribution miss, and #2757/#2664/#2703 cover adjacent Stage A/routing wedges — all share the same files, so they should be fixed in one pass.