geneseed 3.12.0 → 3.13.0

package/src/bricks/characterize.md

@@ -0,0 +1,17 @@
+---
+name: characterize
+description: Pin what legacy code does today with characterization tests, touching tests only.
+effect: mutate
+agent: tester
+outcomes: pass, fail
+---
+For the card's change point (with no card, the code the requirement names), write tests that pin
+what the code DOES today, not what it should do: assert a value you expect to be wrong, run it,
+and copy the observed value in. Touch only test files — never production code.
+
+Pin odd behaviour as it is and name it in the test's title; do not fix it here. If LOOP.md's notes
+list surviving mutants for this card, add the assertions that kill them.
+
+Report `pass` once the new tests run green against the unchanged code.
+Report `fail` if the code cannot be put under test without breaking a dependency first — that is
+a refactor in its own right — naming the dependency.

package/src/bricks/ci-fix.md

@@ -11,7 +11,8 @@ guess from the check's title, before changing anything.
 Touch only what that failure requires; this is a repair, not a chance to improve the pipeline
 along the way.
 
-Report `pass` once the named check is fixed and green.
+Report `pass` once the named check is fixed and green LOCALLY — CI itself is re-read after the
+push, not here.
 
 Report `fail` if the check cannot be fixed from this repo alone (an infra outage, a flake with no
 reproducible cause, a required secret that is missing), naming why.

package/src/bricks/ci-triage.md

@@ -0,0 +1,20 @@
+---
+name: ci-triage
+description: Read the failing CI checks for this commit and pick one code failure to fix, or stop.
+effect: read
+agent: explorer
+outcomes: more, done
+---
+Key on the commit, not the branch: `gh run list --commit <HEAD sha> --json databaseId,status,conclusion`.
+A commit pushed moments ago may not have a run yet — poll that command for up to ~2 minutes
+before concluding none exists. Wait on a pending run with `gh run watch <id>`, then read
+`gh run view <id> --log-failed` — never guess from a check's title. Classify each failure as
+code, flaky or infra. Never edit any file. `ci-repair` needs CI to run on `loop/*` branches: if
+still no run after that poll, write "CI does not run for <sha>" to a file in the OS temp
+directory and report `done` with that file's path — never as green.
+
+Write the classification, one failure per line, to a file in the OS temp directory and report
+that file's path with the outcome. Report `more` with a card for ONE code failure:
+{"intent": "<fix check X: cause>", "writeSet": ["<files the fix touches>"],
+ "actions": ["<each of: format, imports, rename, logic, new-file, api, delete, architecture>"]}
+Report `done` when CI is green for HEAD, or only flaky or infra failures remain — naming them.

package/src/bricks/compat-check.md

@@ -0,0 +1,16 @@
+---
+name: compat-check
+description: Confirm consumers of the old and the new interface both still work after this iteration.
+effect: read
+agent: tester
+outcomes: pass, fail
+---
+Run the tests of every consumer this change can reach — those still on the old shape as well as
+those already moved — and, where the repo records consumer contracts (Pact, Spring Cloud
+Contract), the provider verification against them. In a contract step, where the old shape is
+removed on purpose, check instead that no consumer still uses it. Never edit any file: send
+reports to the OS temp directory.
+
+Report `pass` if every consumer works. Report `fail` naming the broken consumer, the check and
+its raw failure, written to a file in the OS temp directory — report that file's path with the
+outcome.

package/src/bricks/done-check.md

@@ -0,0 +1,16 @@
+---
+name: done-check
+description: Verify the requirement is met — every acceptance criterion proven by a passing test or a stated manual check.
+effect: read
+agent: reviewer
+outcomes: pass, fail
+---
+Read the requirement's acceptance criteria — `specs/<slug>/spec.md` when the branch has one, else
+the requirement in LOOP.md — and the branch's full diff against its base. Run the suite. For
+every criterion, name the test that proves it, or the manual check (what to do, what to see) when
+no test can. Never edit any file. Judge only the stated criteria — never style or extras.
+
+Report `pass` only if every criterion maps to a passing test or a stated manual check.
+Report `fail` otherwise: write each unmet criterion, one per line, with what is missing (no test,
+a failing test, a half-built behaviour) to a file in the OS temp directory and report that file's
+path — the next iteration's `identify` builds from it.

package/src/bricks/fitness-define.md

@@ -0,0 +1,22 @@
+---
+name: fitness-define
+description: Encode the requirement's architecture rule as a test, with an allowlist of today's violations.
+effect: mutate
+agent: architect
+gate: human
+outcomes: pass, fail
+---
+Turn the requirement's architecture rule into an executable test in the suite, with the repo's
+own tools first: ArchUnit for Java (a `FreezingArchRule`, whose violation store is the
+allowlist), then dependency-cruiser, import-linter, eslint-plugin-boundaries or size-limit.
+Record today's violations in an allowlist beside the test so the suite stays green — each later
+iteration removes one entry. Touch only the test, its allowlist and the tool's test-scoped setup,
+and declare the tool's generated store as a glob in the write set (`--write-set '**/archunit_store/**'`
+— single-quote it, the same as any glob in `--write-set`).
+
+The user reviews the rule before the loop continues: write the rule in one sentence, the test's
+path, the allowlist's path and its entry count to a file in the OS temp directory and report that
+file's path with the outcome.
+
+Report `pass` once the test runs green with the allowlist in place. Report `fail` if the rule
+cannot be checked deterministically, with the note file naming what is ambiguous.

package/src/bricks/flake-check.md

@@ -0,0 +1,17 @@
+---
+name: flake-check
+description: Rerun the card's test until it proves stable — a retry or a sleep is not a fix.
+effect: read
+agent: tester
+outcomes: stable, flaky
+---
+Rerun the card's test 20 times alone, then 20 with its suite, as `flake-repro` did (Maven: a
+loop of `mvn test -Dtest=<Class>#<method>`, shuffled). Never edit any file.
+
+Read this iteration's diff first. Polling on the awaited condition (Awaitility
+`await().atMost(…).until(…)`, `waitFor`) in place of a fixed sleep is a fix; adding a sleep or
+raising an existing timeout is not, and neither is a retry (`rerunFailingTestsCount`,
+`@RetryingTest`, `jest.retryTimes`) — report `flaky` naming it, whatever the runs say.
+
+Report `stable` only on 0 failures in all runs. Report `flaky` otherwise, with the failure count
+and one failure's output in a file in the OS temp directory — report that file's path.

package/src/bricks/flake-repro.md

@@ -0,0 +1,18 @@
+---
+name: flake-repro
+description: Confirm which suspected tests are flaky by repeated runs, before anything is fixed.
+effect: read
+agent: tester
+outcomes: flaky, stable, broken
+---
+Run each suspected test the requirement names 20 times (or the N it gives) alone, then 20 with
+its suite in a shuffled order — no code change, no retry option. Maven: loop `mvn test
+-Dtest=<Class>#<method>` (multi-module: add `-pl <module> -Dsurefire.failIfNoSpecifiedTests=false`),
+shuffled with `-Dsurefire.runOrder=random` and, under JUnit 5,
+`-Djunit.jupiter.testmethod.order.default=org.junit.jupiter.api.MethodOrderer$Random`. Never
+`-Dsurefire.rerunFailingTestsCount`: it hides the failures you count. Never edit any file. Write
+each test as `<test>: <failures>/<runs>` with one failure's output to a file in the OS temp
+directory and report that file's path.
+
+Report `broken` if any test fails every run — a bug for `bugfix`, not a flake. Report `flaky` if a
+test failed some runs, listing the confirmed ones. Report `stable` if none failed.

package/src/bricks/identify.md

@@ -9,12 +9,15 @@ Read the requirement and the loop's history (LOOP.md, `git log --format=%(traile
 branch). If the requirement is fully met and the suite is green, report `done`.
 
 Otherwise pick the SMALLEST next change that moves the requirement forward and can be tested on
-its own. Report `more` with a card, as JSON:
-{"intent": "<one line>", "writeSet": ["<every file you expect to touch>"],
+its own — when the branch has `specs/*/spec.md`, its next unfinished task. If the latest note is
+`done-check`'s unmet criteria, report `more` with a card for one of them, never `done`. Report
+`more` with a card, as JSON:
+{"intent": "<one line>", "writeSet": ["<every file ANY brick this iteration writes, tests/docs too>"],
  "actions": ["<each of: format, imports, rename, logic, new-file, api, delete, architecture>"]}
 
 Declare every action honestly: the diff is scored again before commit, and anything outside the
 write set or under-declared escalates to a blocking stop. If LOOP.md's notes say the previous
-attempt was re-split, make this card strictly smaller than that one.
+attempt was re-split, make this card strictly smaller than that one. The card obeys every
+instruction in the template's `rules` (e.g. its intent cites the proof that code is unused).
 
 Never edit, create or delete any file: this brick only reads.

package/src/bricks/migration-plan.md

@@ -0,0 +1,21 @@
+---
+name: migration-plan
+description: Plan a breaking interface change as expand, migrate each consumer, contract — for the user to review.
+effect: read
+skill: migrate
+gate: human
+outcomes: pass, fail
+---
+Following the migrate skill, plan the change as ordered steps: expand (add the new shape beside
+the old), migrate (one consumer or call-site group per step), contract (remove the old shape).
+Every step must leave the system deployable and fit one `identify` card. Name the contract files
+the expand and contract steps touch — API specs, schema migrations, event schemas. Never edit any
+file.
+
+The user reviews the plan before the loop continues: write the steps, one per line, then the
+contract files, to a file in the OS temp directory and report that file's path with the outcome.
+Those files belong in LOOP.md's `contracts`, so the expand and contract steps stop for a human:
+the user adds any the template's defaults miss to LOOP.md's `contracts` before answering ok.
+
+Report `pass` with the plan. Report `fail` if no backward-compatible path exists, naming what
+forces the break.

package/src/bricks/mutation-check.md

@@ -0,0 +1,18 @@
+---
+name: mutation-check
+description: Prove the new tests bite, by mutation testing scoped to the code the card names.
+effect: read
+agent: tester
+outcomes: pass, fail, unavailable
+---
+Run the project's mutation tool scoped to the production code the card's intent names. Java: PIT
+first — `mvn test-compile org.pitest:pitest-maven:mutationCoverage -DtargetClasses=<fq.Class*>
+-DreportsDirectory=<OS temp dir> -DtimestampedReports=false`, or Gradle's `pitest` task; else
+Stryker, mutmut or cargo-mutants. Never edit any file — reports and caches (.mutmut-cache,
+mutants.out/, .stryker-tmp/) go to the OS temp dir, or are removed.
+
+Report `pass` if no surviving mutant sits on a line the new tests target. Report `fail` with each
+survivor as `file:line`, the mutation, and the assertion that would kill it, in a file in the OS
+temp directory — report its path. Report `unavailable` when no tool is configured — the pom lacks
+`pitest-junit5-plugin` under JUnit 5, or Gradle does not apply `info.solidsoft.pitest`: never add
+it to the build; write what you checked to a temp file and report its path.

package/src/bricks/plan.md

@@ -8,10 +8,10 @@ outcomes: pass
 Read the requirement and survey the code it touches. Split the work into an ordered list of
 small iterations, each one sized to a single `identify` card — one testable change apiece.
 
-Do not edit any code; this brick only plans it. Report `pass` with a card whose intent carries
-the ordered list, one iteration per line, so it lands in LOOP.md's notes for `identify` to work
-through one at a time:
-{"intent": "<iteration 1>\n<iteration 2>\n...", "writeSet": [], "actions": []}
+Do not edit any code; this brick only plans it. `plan` is not an iteration head, so its card is
+never recorded — write the ordered list, one iteration per line, to a file in the OS temp
+directory (never inside the worktree) and report that file's path with the outcome, so it is
+recorded into LOOP.md's notes. Report `pass`.
 
-If the requirement cannot be split — it is already one atomic change — say so in the intent and
-let the loop proceed with a single iteration.
+If the requirement cannot be split — it is already one atomic change — say so in the note file
+and let the loop proceed with a single iteration.

package/src/bricks/red-test.md

@@ -0,0 +1,16 @@
+---
+name: red-test
+description: Write the failing test for the card's intent before any production code changes.
+effect: mutate
+agent: tester
+outcomes: red, green, untestable
+---
+Write the smallest test that expresses the card's intent at its seam, touching only the test
+files in the card's `writeSet` — never production code; making it pass is `apply`'s job. Run it.
+
+Report `red` if it fails FOR THE REASON the intent states — not an import error, a typo, or a
+broken fixture in the test itself.
+Report `green` if it already passes: the behaviour exists, so keep the test as coverage.
+Report `untestable` if no seam lets a test reach the behaviour without changing production code
+first, naming what blocks it. If the card's `writeSet` names no test file, report `untestable`
+and say so.

package/src/bricks/review.md

@@ -6,12 +6,14 @@ agent: reviewer
 outcomes: pass, fail
 ---
 Read the card's intent and write set, then read the diff this iteration actually produced. Check
-that the diff matches the intent, stays inside the declared write set, and does not smuggle in an
-unrelated change.
+that the diff matches the intent, stays inside the declared write set, does not smuggle in an
+unrelated change, and keeps any rule in `rules` (e.g. a cited proof that code is unused).
 
 Never edit any file — findings go back to `apply`, which makes the fix.
 
 Report `pass` if the diff is a faithful, scoped implementation of the card.
 
 Report `fail` with concrete findings — `file:line`, what is wrong, what to do instead — if the
-diff drifts from the intent, touches an undeclared file, or leaves an obvious defect behind.
+diff drifts from the intent, touches an undeclared file, breaks a rule, or leaves an obvious defect behind.
+The outcome alone does not carry the findings to `apply` — write them to a file in the OS temp
+directory (never inside the worktree) and report that file's path with the outcome.

package/src/bricks/spec.md

@@ -0,0 +1,18 @@
+---
+name: spec
+description: Write the feature's spec — scope, EARS acceptance criteria, ordered tasks — for the user to review.
+effect: mutate
+agent: architect
+gate: human
+outcomes: pass, fail
+---
+Write `specs/<slug>/spec.md` (the slug of the loop's title) and touch nothing else — no code: the
+problem, what is out of scope, acceptance criteria in EARS form ("WHEN <trigger> THE SYSTEM SHALL
+<response>"), each one testable, and an ordered task list sized to one `identify` card apiece,
+ending with an end-to-end verification task. A gate amendment in LOOP.md's notes answers your
+open questions or corrects the spec: revise the spec to follow it.
+
+The user reviews the spec before the loop continues. Report `pass` once every criterion is
+testable, with the spec's path and its criteria count in a file in the OS temp directory — report
+that file's path. Report `fail` if a criterion cannot be stated testably: list the open questions
+in such a file and report its path; the user answers them with an amend.

package/src/bricks/upgrade-scout.md

@@ -0,0 +1,16 @@
+---
+name: upgrade-scout
+description: Pick the next dependency upgrade and read its breaking changes, or declare all done.
+effect: read
+agent: researcher
+outcomes: more, done
+---
+Read the requirement and the loop's history (LOOP.md, `git log --format=%(trailers)` on this
+branch). Pick the next package or group the requirement names that is not yet upgraded, skipping
+any release younger than 14 days, and read its changelog or migration guide. Never edit any file.
+
+Report `done` when every named package is upgraded. Otherwise report `more` with a card:
+{"intent": "<bump X to N and adapt>", "writeSet": ["<manifest, lockfile, every file to adapt>"],
+ "actions": ["<each of: format, imports, rename, logic, new-file, api, delete, architecture>"]}
+Write the breaking changes that hit this repo to a file in the OS temp directory and report that
+file's path with the outcome — the card alone does not carry them to `apply`.

package/src/loops/api-endpoint.json

@@ -0,0 +1,31 @@
+{
+  "name": "api-endpoint",
+  "description": "Build an HTTP API feature (a Spring MVC controller, say) one endpoint change per iteration: plan, apply, test, write or update the endpoint's Bruno request, run a security review, and review.",
+  "category": "development",
+  "rules": [
+    "The card's write set names the endpoint's .bru requests too, not only the code.",
+    "An OpenAPI or Swagger spec edit stops for a human by design; the aggressive preset or trimming LOOP.md's contracts relaxes it."
+  ],
+  "nodes": ["plan", "identify", "apply", "test", "bruno-test", "security-scan", "review"],
+  "start": "plan",
+  "edges": [
+    { "from": "plan", "on": "pass", "to": "identify" },
+    { "from": "identify", "on": "more", "to": "apply" },
+    { "from": "identify", "on": "done", "to": "$close" },
+    { "from": "apply", "on": "pass", "to": "test" },
+    { "from": "test", "on": "pass", "to": "bruno-test" },
+    { "from": "test", "on": "fail", "to": "apply" },
+    { "from": "bruno-test", "on": "pass", "to": "security-scan" },
+    { "from": "bruno-test", "on": "fail", "to": "$stop" },
+    { "from": "security-scan", "on": "pass", "to": "review" },
+    { "from": "security-scan", "on": "fail", "to": "apply" },
+    { "from": "review", "on": "pass", "to": "identify" },
+    { "from": "review", "on": "fail", "to": "apply" }
+  ],
+  "loops": [
+    { "name": "iterations", "nodes": ["identify", "apply", "test", "bruno-test", "security-scan", "review"], "max": 20, "iteration": true },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 5 },
+    { "name": "review-fix", "nodes": ["apply", "test", "bruno-test", "security-scan", "review"], "max": 3 }
+  ],
+  "contracts": ["**/openapi*.yaml", "**/openapi*.yml", "**/openapi*.json", "**/swagger*.yaml", "**/swagger*.yml", "**/swagger*.json"]
+}

package/src/loops/architecture-decision.json

@@ -0,0 +1,22 @@
+{
+  "name": "architecture-decision",
+  "description": "Record one architecture decision record per decision the requirement names: draft it, have a skeptic attack it, and let the user review the ADR that survives, until every decision is recorded as Proposed.",
+  "category": "architecture",
+  "rules": [
+    "Pick the next undocumented decision; the card's write set is its ADR file."
+  ],
+  "nodes": ["identify", "adr-draft", "adr-challenge"],
+  "start": "identify",
+  "edges": [
+    { "from": "identify", "on": "more", "to": "adr-draft" },
+    { "from": "identify", "on": "done", "to": "$close" },
+    { "from": "adr-draft", "on": "pass", "to": "adr-challenge" },
+    { "from": "adr-challenge", "on": "pass", "to": "identify" },
+    { "from": "adr-challenge", "on": "fail", "to": "adr-draft" }
+  ],
+  "loops": [
+    { "name": "iterations", "nodes": ["identify", "adr-draft", "adr-challenge"], "max": 8, "iteration": true },
+    { "name": "challenge-fix", "nodes": ["adr-draft", "adr-challenge"], "max": 3 }
+  ],
+  "weights": { "new-file": 0.2, "architecture": 0.2 }
+}

package/src/loops/bugfix.json

@@ -1,6 +1,7 @@
 {
   "name": "bugfix",
   "description": "Reproduce the bug with a failing test, then iterate: apply the fix, test, and review, until the requirement is met and the reproduction passes.",
+  "category": "development",
   "nodes": ["reproduce", "identify", "apply", "test", "review"],
   "start": "reproduce",
   "edges": [

package/src/loops/ci-repair.json

@@ -0,0 +1,19 @@
+{
+  "name": "ci-repair",
+  "description": "Read the branch's failing CI checks, fix one code failure per iteration, test, and push, until CI is green or only flaky or infra failures remain.",
+  "category": "day-to-day",
+  "nodes": ["ci-triage", "ci-fix", "test"],
+  "start": "ci-triage",
+  "edges": [
+    { "from": "ci-triage", "on": "more", "to": "ci-fix" },
+    { "from": "ci-triage", "on": "done", "to": "$close" },
+    { "from": "ci-fix", "on": "pass", "to": "test" },
+    { "from": "ci-fix", "on": "fail", "to": "$stop" },
+    { "from": "test", "on": "pass", "to": "ci-triage" },
+    { "from": "test", "on": "fail", "to": "ci-fix" }
+  ],
+  "loops": [
+    { "name": "iterations", "nodes": ["ci-triage", "ci-fix", "test"], "max": 10, "iteration": true },
+    { "name": "fix-test", "nodes": ["ci-fix", "test"], "max": 3 }
+  ]
+}

package/src/loops/deps-upgrade.json

@@ -0,0 +1,29 @@
+{
+  "name": "deps-upgrade",
+  "description": "Confirm the suite is green, then upgrade one package or group per iteration: read its breaking changes, bump and adapt, test, audit, and review, until every named package is upgraded.",
+  "category": "day-to-day",
+  "rules": [
+    "The card's write set names the manifest, the lockfile and every file the bump adapts."
+  ],
+  "nodes": ["baseline-green", "upgrade-scout", "apply", "test", "deps-audit", "review"],
+  "start": "baseline-green",
+  "edges": [
+    { "from": "baseline-green", "on": "pass", "to": "upgrade-scout" },
+    { "from": "baseline-green", "on": "fail", "to": "$stop" },
+    { "from": "upgrade-scout", "on": "more", "to": "apply" },
+    { "from": "upgrade-scout", "on": "done", "to": "$close" },
+    { "from": "apply", "on": "pass", "to": "test" },
+    { "from": "test", "on": "pass", "to": "deps-audit" },
+    { "from": "test", "on": "fail", "to": "apply" },
+    { "from": "deps-audit", "on": "pass", "to": "review" },
+    { "from": "deps-audit", "on": "fail", "to": "apply" },
+    { "from": "review", "on": "pass", "to": "upgrade-scout" },
+    { "from": "review", "on": "fail", "to": "apply" }
+  ],
+  "loops": [
+    { "name": "iterations", "nodes": ["upgrade-scout", "apply", "test", "deps-audit", "review"], "max": 20, "iteration": true },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 5 },
+    { "name": "review-fix", "nodes": ["apply", "test", "deps-audit", "review"], "max": 3 }
+  ],
+  "ignoreDeletions": ["**/package-lock.json", "**/yarn.lock", "**/pnpm-lock.yaml", "**/*.lock", "**/gradle.lockfile"]
+}

package/src/loops/enforce-architecture-rule.json

@@ -0,0 +1,28 @@
+{
+  "name": "enforce-architecture-rule",
+  "description": "Confirm the suite is green, encode the requirement's architecture rule as a test with an allowlist of today's violations for the user to review, then fix one violation per iteration, test, and review, until the allowlist is empty.",
+  "category": "architecture",
+  "rules": [
+    "Each fix removes its violation's allowlist entry in the same iteration."
+  ],
+  "nodes": ["baseline-green", "fitness-define", "identify", "apply", "test", "review"],
+  "start": "baseline-green",
+  "edges": [
+    { "from": "baseline-green", "on": "pass", "to": "fitness-define" },
+    { "from": "baseline-green", "on": "fail", "to": "$stop" },
+    { "from": "fitness-define", "on": "pass", "to": "identify" },
+    { "from": "fitness-define", "on": "fail", "to": "$stop" },
+    { "from": "identify", "on": "more", "to": "apply" },
+    { "from": "identify", "on": "done", "to": "$close" },
+    { "from": "apply", "on": "pass", "to": "test" },
+    { "from": "test", "on": "pass", "to": "review" },
+    { "from": "test", "on": "fail", "to": "apply" },
+    { "from": "review", "on": "pass", "to": "identify" },
+    { "from": "review", "on": "fail", "to": "apply" }
+  ],
+  "loops": [
+    { "name": "iterations", "nodes": ["identify", "apply", "test", "review"], "max": 20, "iteration": true },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 5 },
+    { "name": "review-fix", "nodes": ["apply", "test", "review"], "max": 3 }
+  ]
+}

package/src/loops/feature.json

@@ -1,20 +1,23 @@
 {
   "name": "feature",
-  "description": "Plan the feature into ordered iterations, then build each one: apply, test, and review, until the plan is complete.",
-  "nodes": ["plan", "identify", "apply", "test", "review"],
+  "description": "Plan the feature into ordered iterations, then build each one: apply, test, and review, until the plan is complete — and an independent done-check maps every requirement to a passing test before the loop closes.",
+  "category": "development",
+  "nodes": ["plan", "identify", "apply", "test", "review", "done-check"],
   "start": "plan",
   "edges": [
     { "from": "plan", "on": "pass", "to": "identify" },
     { "from": "identify", "on": "more", "to": "apply" },
-    { "from": "identify", "on": "done", "to": "$close" },
+    { "from": "identify", "on": "done", "to": "done-check" },
     { "from": "apply", "on": "pass", "to": "test" },
     { "from": "test", "on": "pass", "to": "review" },
     { "from": "test", "on": "fail", "to": "apply" },
     { "from": "review", "on": "pass", "to": "identify" },
-    { "from": "review", "on": "fail", "to": "apply" }
+    { "from": "review", "on": "fail", "to": "apply" },
+    { "from": "done-check", "on": "pass", "to": "$close" },
+    { "from": "done-check", "on": "fail", "to": "identify" }
   ],
   "loops": [
-    { "name": "iterations", "nodes": ["identify", "apply", "test", "review"], "max": 20, "iteration": true },
+    { "name": "iterations", "nodes": ["identify", "apply", "test", "review", "done-check"], "max": 20, "iteration": true },
     { "name": "apply-test", "nodes": ["apply", "test"], "max": 5 },
     { "name": "review-fix", "nodes": ["apply", "test", "review"], "max": 3 }
   ]

package/src/loops/fix-flaky-tests.json

@@ -0,0 +1,30 @@
+{
+  "name": "fix-flaky-tests",
+  "description": "Confirm the suspected flaky tests by 20 repeated runs, then fix one per iteration at its root cause, re-confirm it with 20 runs, test, and review.",
+  "category": "tests",
+  "rules": [
+    "Fix at the root cause — shared state, ordering, time, concurrency — never with a retry, a sleep or a longer timeout.",
+    "A test that fails every run is a bug for the bugfix template; one that never fails is not fixed."
+  ],
+  "nodes": ["flake-repro", "identify", "apply", "flake-check", "test", "review"],
+  "start": "flake-repro",
+  "edges": [
+    { "from": "flake-repro", "on": "flaky", "to": "identify" },
+    { "from": "flake-repro", "on": "stable", "to": "$stop" },
+    { "from": "flake-repro", "on": "broken", "to": "$stop" },
+    { "from": "identify", "on": "more", "to": "apply" },
+    { "from": "identify", "on": "done", "to": "$close" },
+    { "from": "apply", "on": "pass", "to": "flake-check" },
+    { "from": "flake-check", "on": "stable", "to": "test" },
+    { "from": "flake-check", "on": "flaky", "to": "apply" },
+    { "from": "test", "on": "pass", "to": "review" },
+    { "from": "test", "on": "fail", "to": "apply" },
+    { "from": "review", "on": "pass", "to": "identify" },
+    { "from": "review", "on": "fail", "to": "apply" }
+  ],
+  "loops": [
+    { "name": "iterations", "nodes": ["identify", "apply", "flake-check", "test", "review"], "max": 10, "iteration": true },
+    { "name": "stabilise", "nodes": ["apply", "flake-check"], "max": 4 },
+    { "name": "review-fix", "nodes": ["apply", "flake-check", "test", "review"], "max": 3 }
+  ]
+}

package/src/loops/legacy-refactor.json

@@ -0,0 +1,26 @@
+{
+  "name": "legacy-refactor",
+  "description": "Confirm the suite is green, pin the code's current behaviour with characterization tests in their own commit, then refactor behind that net: apply, test, and review, until the requirement is met.",
+  "category": "refactoring",
+  "nodes": ["baseline-green", "characterize", "identify", "apply", "test", "review"],
+  "start": "baseline-green",
+  "edges": [
+    { "from": "baseline-green", "on": "pass", "to": "characterize" },
+    { "from": "baseline-green", "on": "fail", "to": "$stop" },
+    { "from": "characterize", "on": "pass", "to": "identify" },
+    { "from": "characterize", "on": "fail", "to": "$stop" },
+    { "from": "identify", "on": "more", "to": "apply" },
+    { "from": "identify", "on": "done", "to": "$close" },
+    { "from": "apply", "on": "pass", "to": "test" },
+    { "from": "test", "on": "pass", "to": "review" },
+    { "from": "test", "on": "fail", "to": "apply" },
+    { "from": "review", "on": "pass", "to": "identify" },
+    { "from": "review", "on": "fail", "to": "apply" }
+  ],
+  "loops": [
+    { "name": "iterations", "nodes": ["identify", "apply", "test", "review"], "max": 20, "iteration": true },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 5 },
+    { "name": "review-fix", "nodes": ["apply", "test", "review"], "max": 3 }
+  ],
+  "weights": { "logic": 0.6 }
+}

package/src/loops/legacy-tests.json

@@ -0,0 +1,29 @@
+{
+  "name": "legacy-tests",
+  "description": "Confirm the suite is green, then pin legacy behaviour one change point at a time: characterization tests, a run, and a mutation check that proves they bite.",
+  "category": "tests",
+  "rules": [
+    "Tests only: production code is never touched."
+  ],
+  "nodes": ["baseline-green", "identify", "characterize", "test", "mutation-check"],
+  "start": "baseline-green",
+  "edges": [
+    { "from": "baseline-green", "on": "pass", "to": "identify" },
+    { "from": "baseline-green", "on": "fail", "to": "$stop" },
+    { "from": "identify", "on": "more", "to": "characterize" },
+    { "from": "identify", "on": "done", "to": "$close" },
+    { "from": "characterize", "on": "pass", "to": "test" },
+    { "from": "characterize", "on": "fail", "to": "$stop" },
+    { "from": "test", "on": "pass", "to": "mutation-check" },
+    { "from": "test", "on": "fail", "to": "characterize" },
+    { "from": "mutation-check", "on": "pass", "to": "identify" },
+    { "from": "mutation-check", "on": "fail", "to": "characterize" },
+    { "from": "mutation-check", "on": "unavailable", "to": "identify" }
+  ],
+  "loops": [
+    { "name": "iterations", "nodes": ["identify", "characterize", "test", "mutation-check"], "max": 20, "iteration": true },
+    { "name": "write-run", "nodes": ["characterize", "test"], "max": 3 },
+    { "name": "kill-mutants", "nodes": ["characterize", "test", "mutation-check"], "max": 3 }
+  ],
+  "weights": { "new-file": 0.2 }
+}

package/src/loops/refactor.json

@@ -1,6 +1,10 @@
 {
   "name": "refactor",
-  "description": "Confirm the suite is green before touching anything, then iterate on the shape of the code alone. Tests are not edited by this template — a refactor that needs a different test is a behaviour change, not a refactor.",
+  "description": "Confirm the suite is green before touching anything, then iterate on the shape of the code alone.",
+  "category": "refactoring",
+  "rules": [
+    "Tests are not edited: a refactor that needs a different test is a behaviour change, not a refactor."
+  ],
   "nodes": ["baseline-green", "identify", "apply", "test"],
   "start": "baseline-green",
   "edges": [

package/src/loops/remove-dead-code.json

@@ -0,0 +1,30 @@
+{
+  "name": "remove-dead-code",
+  "description": "Confirm the suite is green, then remove one coherent group of unused code per iteration — exports, classes, files, retired flags — test it, and review it. Deletions score soft, not blocking.",
+  "category": "refactoring",
+  "rules": [
+    "Each card's intent cites the proof it is unused: the requirement's tool output (knip, ts-prune, vulture, PMD or IntelliJ inspections) and a reference search (git grep over code AND resources) for reflection, DI by name, Spring bean names and config.",
+    "Generated sources do not count as unused.",
+    "Public entry points belong in LOOP.md's contracts, not in a deletion."
+  ],
+  "nodes": ["baseline-green", "identify", "apply", "test", "review"],
+  "start": "baseline-green",
+  "edges": [
+    { "from": "baseline-green", "on": "pass", "to": "identify" },
+    { "from": "baseline-green", "on": "fail", "to": "$stop" },
+    { "from": "identify", "on": "more", "to": "apply" },
+    { "from": "identify", "on": "done", "to": "$close" },
+    { "from": "apply", "on": "pass", "to": "test" },
+    { "from": "test", "on": "pass", "to": "review" },
+    { "from": "test", "on": "fail", "to": "apply" },
+    { "from": "review", "on": "pass", "to": "identify" },
+    { "from": "review", "on": "fail", "to": "apply" }
+  ],
+  "loops": [
+    { "name": "iterations", "nodes": ["identify", "apply", "test", "review"], "max": 20, "iteration": true },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 5 },
+    { "name": "review-fix", "nodes": ["apply", "test", "review"], "max": 3 }
+  ],
+  "weights": { "delete": 0.5 },
+  "ignoreDeletions": ["**/generated/**", "**/generated-sources/**", "**/target/**", "**/build/generated/**"]
+}