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.
Shipped
Click a lifecycle step above to view its details.
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.