Skip to main content
← Back to list
01Issue
FeatureOpenExtensions
AssigneesNone

Relationships

#916 Driving agent can wedge a workflow-stage run irrecoverably (workflow-succeeded vs dispatch limit); skill should prevent it

Opened by atalanta · 7/2/2026

Context

Driving @swamp/software-factory through a real multi-stage run (a workflow-mode testing stage gating on workflow-succeeded), an agent following the bundled software-factory skill (SKILL.md + references/driving.md) still reached an unrecoverable wedge whose only exit was a destructive reset. The skill is the contract the factory offers a generic driving agent; if an agent that reads and follows it can still dead-end a run, the gap is in what the skill/mechanism guarantees, not in the agent. These are framed as outcomes with proposed implementations.

Outcome 1 — a driving agent cannot wedge a run irrecoverably by following the documented loop

Today a workflow-mode stage can enter a state where:

  • pass is gated on workflow-succeeded, which requires the workflow run to be newer than the current stage entry;
  • each record_dispatch re-stamps the stage entry to "now", so a run performed before the (re)dispatch always "predates entry";
  • re-running to satisfy the gate consumes dispatch attempts;
  • at the dispatch limit the runaway-loop breaker refuses further dispatch;
  • cycle-override grants a pass on the cycle-limit gate, which does NOT clear workflow-succeeded;
  • so the run is stuck: cannot dispatch, cannot pass, and the only move left is reset workItem=… confirm=reset (destructive).

Proposed implementation (any one closes the outcome):

  • Make record_dispatch on a workflow/method stage OPTIONALLY trigger/associate the run, so "dispatch then run" is a single, correctly-ordered step the agent can't invert; or
  • Have workflow-succeeded accept any successful run of the named workflow that occurred during the current stage cycle (not strictly after the last dispatch), so re-dispatch ordering can't invalidate a good run; or
  • When the dispatch limit is hit but all products exist and only workflow-succeeded fails, offer a non-destructive recovery (e.g. a cycle-override variant that re-arms the workflow gate, or a re-run action) instead of forcing reset.

Outcome 2 — the failure message names the ORDERING cause, not just the symptom

workflow-succeeded fails with "latest run of workflow 'X' predates the current entry into stage 'S' — run it again for this cycle." Following that literally ("run it again") makes it WORSE when the real cause is order: the run happened before record_dispatch. The message sends the agent into the exact loop that trips the breaker.

Proposed implementation:

  • When the newest run of the workflow exists but predates the entry AND a record_dispatch for this entry postdates that run, say so: "a successful run exists but predates this stage entry — it was run BEFORE record_dispatch; dispatch first, then run the workflow." Point at the ordering, not at "run it again."

Outcome 3 — the skill states the workflow-stage step ORDER explicitly and warns of the trap

references/driving.md describes record_dispatch (step 2) then "execute the stage's work" (step 3), but does not make explicit that for a workflow-mode stage the workflow run MUST come after record_dispatch, nor warn that running first strands the run behind the entry. An agent reasonably runs the workflow to "get the runId to record", inverting the order.

Proposed implementation:

  • In references/driving.md "Executing work → workflow", state the ordering as a hard rule ("dispatch FIRST, then run; a run performed before dispatch will fail workflow-succeeded as 'predates entry'") and note that re-dispatching to fix a gate burns the attempt budget — gate failures are fixed by addressing the gate, never by re-dispatching.

Impact

Without these, a single ordering mistake by a driving agent (a plausible one the current docs invite) escalates through the runaway-loop breaker to a forced destructive reset — losing all run state for a work item whose code was already correct. The factory's value is that a generic agent can drive it safely; an irrecoverable-by-following-the-docs path undercuts that.

Upstream repository: https://github.com/swamp-club/swamp-extensions

Environment

  • Extension: @swamp/software-factory@2026.06.24.1
  • swamp: 20260626.005336.0-sha.f302d18e
  • OS: darwin (aarch64)
  • Deno: 2.8.3
  • Shell: /bin/zsh
02Bog Flow
◉OPEN○TRIAGED○IN PROGRESS○SHIPPED

Open

7/2/2026, 3:07:02 PM

No activity in this phase yet.

03Sludge Pulse

Sign in to post a ripple.