Skip to main content
← Back to list
01Issue
FeatureShippedExtensionsPublic
Assigneesskunk-ape

Relationships

#2706 gatorwalk-factory: document loops and their controls

Opened by skunk-ape · 9/29/2026· Shipped 9/29/2026

Part of the gatorwalk-factory rebuild of @swamp/software-factory (gatorwalk-factory/ in swamp-extensions). Read README.md, DESIGN.md and the skill (.claude/skills/gatorwalk-factory/) first.

From a customer conversation: a software factory is not a DAG, because you want controlled looping (rework after review, re-checking after a failure). Gatorwalk already supports and controls loops, but the docs never say so plainly: the word DAG appears nowhere, and the controls are scattered across README (graph-analysis loop warnings), DESIGN.md (circuit breakers, approvals voided by change, per-cycle gate scoping), the skill (stop and tell the person at a limit) and the bundled-lifecycle notes (manual ways back). A reader should not have to assemble it.

Write one section, in DESIGN.md with a short version in README, that states the model: a lifecycle is a directed graph whose loops are allowed and controlled, not a DAG; the swamp workflows that do a stage's work stay DAGs (see #2699 for running work in parallel inside a stage). Then each control, with an example from lifecycles/build-swamp-extension.yaml or swamp-extensions.yaml:

  • a loop is an ordinary transition back; each re-entry is a new cycle;
  • per-cycle evidence: approvals, evidence-recorded and artifact-fresh with recordedThisCycle only count the current pass, and an approval is voided when what it approved changes;
  • loops need a reason: rework exits gated on data (an open blocking finding), manual ways back need a person;
  • the cycle limit (maxCycles, default 5) and cycle overrides (they accumulate; a reset starts fresh counts);
  • the dispatch cap (maxDispatchesPerCycle, default 2) against runaway loops within one pass, and dispatch overrides;
  • routing on loop count with a max-cycles gate (e.g. escalate after N passes);
  • escape hatches: global transitions are exempt from cycle limits so a loop cannot wedge a run; reset starts a new era;
  • design-time checks: what validate's graph analysis warns about for loops, and that it fails if it cannot finish;
  • measurement: rework and re-entries in the per-item metrics (GW-19, #2687).

Link the skill's refusal table to the new section. Verify every claim against the code; where the code and this list differ, the code wins and the difference goes in the PR description. Nothing is published.

02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 5 MOREREVIEW+ 11 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

9/29/2026, 6:46:56 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
skunk-ape assigned skunk-ape9/29/2026, 6:27:44 PM
Editable. Press Enter to edit.

system commented 9/29/2026, 5:41:24 PM

Classified automatically when this issue was filed.

  • Source: Extensions

If you feel this classification is incorrect, add a ripple to tell us so.

skunk-ape commented 9/29/2026, 5:44:12 PM

Correction to the framing in this issue (the body's wording is ambiguous): a DAG is acyclic, and a lifecycle has cycles, so a lifecycle is not a DAG. State it that way. Suggested wording: 'A lifecycle is a directed graph that contains cycles. It is deliberately not a DAG: rework, re-checking and revision are loops back to earlier stages, and every loop is bounded by the controls below.' Then, separately: 'The swamp workflows that do a stage's work are acyclic (they have no loops), which is why parallel work belongs there (#2699). Looping happens between stages; concurrency happens inside one.' Do not describe the lifecycle's loops in DAG terms (e.g. 'a DAG with loops' or 'controlled loops, not a DAG'), since that reads as a contradiction.

Sign in to post a ripple.