geneseed 3.12.0 → 3.14.0

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/**"]
+}

package/src/loops/spec-first-feature.json

@@ -0,0 +1,29 @@
+{
+  "name": "spec-first-feature",
+  "description": "Write the feature's spec first — specs/<slug>/spec.md with EARS acceptance criteria and an ordered task list — for the user to review, commit it, then build it task by task: apply, test, review. An independent done-check maps every criterion to a passing test before the loop closes.",
+  "category": "development",
+  "rules": [
+    "One spec task per iteration, in the spec's order.",
+    "Open questions in the spec wait for the user's answers; never answer them yourself."
+  ],
+  "nodes": ["spec", "identify", "apply", "test", "review", "done-check"],
+  "start": "spec",
+  "edges": [
+    { "from": "spec", "on": "pass", "to": "identify" },
+    { "from": "spec", "on": "fail", "to": "$stop" },
+    { "from": "identify", "on": "more", "to": "apply" },
+    { "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": "done-check", "on": "pass", "to": "$close" },
+    { "from": "done-check", "on": "fail", "to": "identify" }
+  ],
+  "loops": [
+    { "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/tdd.json

@@ -0,0 +1,25 @@
+{
+  "name": "tdd",
+  "description": "Plan the work, then build it test-first: each iteration writes a failing test, makes it pass, and reviews the diff, until the plan is complete.",
+  "category": "tests",
+  "nodes": ["plan", "identify", "red-test", "apply", "test", "review"],
+  "start": "plan",
+  "edges": [
+    { "from": "plan", "on": "pass", "to": "identify" },
+    { "from": "identify", "on": "more", "to": "red-test" },
+    { "from": "identify", "on": "done", "to": "$close" },
+    { "from": "red-test", "on": "red", "to": "apply" },
+    { "from": "red-test", "on": "green", "to": "test" },
+    { "from": "red-test", "on": "untestable", "to": "$stop" },
+    { "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", "red-test", "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/update-contract.json

@@ -0,0 +1,33 @@
+{
+  "name": "update-contract",
+  "description": "Change an interface with live consumers — an API, a schema, an event — as expand, migrate one consumer per iteration, contract: plan it for the user to review, then apply, test, check old and new consumers, and review.",
+  "category": "architecture",
+  "rules": [
+    "Contract files (OpenAPI, AsyncAPI, protobuf, Avro, GraphQL schemas, Flyway and Liquibase migrations) stop for a human by default; a stop on one is expected, not a failure.",
+    "`geneseed loop init --contracts <globs>` appends more contract globs, and LOOP.md's `contracts` can be trimmed."
+  ],
+  "nodes": ["migration-plan", "identify", "apply", "test", "compat-check", "review"],
+  "start": "migration-plan",
+  "edges": [
+    { "from": "migration-plan", "on": "pass", "to": "identify" },
+    { "from": "migration-plan", "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": "compat-check" },
+    { "from": "test", "on": "fail", "to": "apply" },
+    { "from": "compat-check", "on": "pass", "to": "review" },
+    { "from": "compat-check", "on": "fail", "to": "apply" },
+    { "from": "review", "on": "pass", "to": "identify" },
+    { "from": "review", "on": "fail", "to": "apply" }
+  ],
+  "loops": [
+    { "name": "iterations", "nodes": ["identify", "apply", "test", "compat-check", "review"], "max": 20, "iteration": true },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 5 },
+    { "name": "review-fix", "nodes": ["apply", "test", "compat-check", "review"], "max": 3 }
+  ],
+  "contracts": [
+    "**/openapi*.yaml", "**/openapi*.yml", "**/openapi*.json", "**/asyncapi*.yaml", "**/*.proto", "**/*.avsc",
+    "**/*.graphqls", "**/*.graphql", "**/asyncapi*.yml", "**/asyncapi*.json", "**/db/migration/**", "**/db/changelog/**"
+  ]
+}

package/src/skills/brick-forge.md

@@ -32,7 +32,9 @@ that…".
    <4-10 lines of direct instructions, ending with exactly how to choose among the outcomes>
    ```
 
-   No double-brace tokens in the body: the loop hands it to the model raw.
+   No double-brace tokens in the body: the loop hands it to the model raw. If the brick finds
+   something the next brick needs, have it write that to a file in the OS temp directory and
+   report the path with the outcome — the loop skill records it as a note.
 3. **Overriding by name** — a project or global brick named like a shipped one replaces it in
    every template. That is allowed; say so to the user. `geneseed loop check` lists overrides under `overridden`.
 4. **Check it:** `geneseed loop check --brick <path>` (this file alone), then

package/src/skills/bruno-collection-generator.md

@@ -3,9 +3,9 @@
 > {{DESC_BRUNO_COLLECTION_GENERATOR}}
 
 **Trigger:** creating, converting, or reorganising a [Bruno](https://www.usebruno.com/)
-collection — requests, folders, environments, request docs — from backend routes, an
-OpenAPI snippet, pasted API docs, curl commands, or a plain endpoint list, as `.bru`
-files or OpenCollection YAML.
+collection as `.bru` files or OpenCollection YAML. The collection covers requests,
+folders, environments and request docs; the source can be backend routes, an OpenAPI
+snippet, pasted API docs, curl commands, or a plain endpoint list.
 
 ## Procedure
 1. Gather the inputs, and state every assumption you fill in ({{LAW:echo-the-intent}}): the source

package/src/skills/bruno-test-writer.md

@@ -3,9 +3,9 @@
 > {{DESC_BRUNO_TEST_WRITER}}
 
 **Trigger:** writing, reviewing, or strengthening tests for a [Bruno](https://www.usebruno.com/)
-request or collection — assertions, `tests` blocks, pre-request and post-response
-scripts, request chaining, schema checks, edge cases — in `.bru` files or
-OpenCollection YAML.
+request or collection in `.bru` files or OpenCollection YAML. Covers assertions, `tests`
+blocks, pre-request and post-response scripts, request chaining, schema checks, and
+edge cases.
 
 ## Procedure
 1. Understand the request or collection first: method, path, auth, body, headers,

package/src/skills/ci-fix.md

@@ -2,9 +2,9 @@
 
 > {{DESC_CI_FIX}}
 
-**Trigger:** a CI run, pipeline job, or pre-merge check is red — on a PR you opened, a
-branch you are on, or one the user points you at — or the user says "CI is failing",
-"fix the build", "why is the pipeline red". The [debug {{SKILL}}](debug.md) drives
+**Trigger:** a CI run, pipeline job, or pre-merge check is red, or the user says "CI is
+failing", "fix the build", "why is the pipeline red". The red run can be on a PR the agent
+opened, the branch it is on, or one the user points at. The [debug {{SKILL}}](debug.md) drives
 the root-causing once the failure reproduces locally; this {{SKILL}} gets it there and
 gets the fix back through the same gate.
 

package/src/skills/consolidate-memory.md

@@ -2,10 +2,10 @@
 
 > {{DESC_CONSOLIDATE_MEMORY}}
 
-**Trigger:** the {{MEMORY}} index has grown past what a session can usefully read
-(~40 lines), two entries say the same or opposite things, a memory names a file, flag,
-or command that no longer exists, a `feedback` lesson keeps recurring, or the user
-says "clean up memory", "consolidate", "what do you actually remember". Also worth a
+**Trigger:** the {{MEMORY}} index has outgrown one useful read (~40 lines) or holds
+duplicate, contradictory, or stale entries. Stale means a memory naming a file, flag, or
+command that no longer exists; a `feedback` lesson that keeps recurring counts too, as
+does the user saying "clean up memory", "consolidate", "what do you actually remember". Also worth a
 pass after a release or a large refactor, when many recorded facts just changed. The
 [rule {{SKILL}}](rule.md) writes one memory or one rule; this {{SKILL}} tends the
 whole set. The user's wiki is out of scope — that is the [wiki {{SKILL}}](wiki.md).

package/src/skills/council.md

@@ -2,7 +2,7 @@
 
 > {{DESC_COUNCIL}}
 
-**Trigger:** the user asks to "convene a council", "debate this", "argue both sides", "stress-test this decision", or wants a change, plan, or claim challenged from several points of view before committing to it.
+**Trigger:** the user asks to "convene a council", "debate this", or "argue both sides", or wants a decision stress-tested from several points of view. A change, plan, or claim all qualify, as long as it is challenged before committing to it.
 
 ## Procedure
 1. Frame the motion in one line — the exact decision, change, or claim under debate — and name what it feeds (a choice to make, a design to accept, a discussion to settle). Ground it in the real artifact and the project's own docs ({{DOCTRINE:read-the-docs-first}}) so the council argues the actual thing; if the motion is unclear or bundles several questions, split it and ask once, then proceed.

package/src/skills/fresh-eyes.md

@@ -2,7 +2,7 @@
 
 > {{DESC_FRESH_EYES}}
 
-**Trigger:** a task is claimed done and the solving session believes the artifact works — before merge or handoff, or when the user asks to "validate", "fresh eyes", "prove it meets the spec", "did this actually solve it", or "independent sign-off", and the cost of a confidently-wrong "done" is high. This re-judges the *result* from zero context — distinct from [geneseed-code-review](geneseed-code-review.md), which reviews a *diff* with full knowledge of the change. For an open-ended quality critique use [roast-me](roast-me.md); for a multi-stance debate over an undecided question use [council](council.md).
+**Trigger:** work is claimed done and needs a blind check against the original ask. That is before merge or handoff, while the solving session believes the artifact works, or when the user asks to "validate", "fresh eyes", "prove it meets the spec", "did this actually solve it", or "independent sign-off" — and the cost of a confidently-wrong "done" is high. This re-judges the *result* from zero context — distinct from [geneseed-code-review](geneseed-code-review.md), which reviews a *diff* with full knowledge of the change. For an open-ended quality critique use [roast-me](roast-me.md); for a multi-stance debate over an undecided question use [council](council.md).
 
 ## Procedure
 1. Capture the firewall input as TWO things and nothing else: (a) the **verbatim original task/spec** — the raw issue or request text, NOT a solver-written summary or "spec card" (a distilled card launders the solving session's framing into the rubric, the very bias this {{SKILL}} exists to defeat), and (b) a pointer to the **final artifact** as it stands — file paths, built output, or the command to run it. If the raw task is too thin to yield acceptance criteria, have the **user** (never the solver) confirm a one-line acceptance bar, then proceed ({{LAW:echo-the-intent}}); if it is too fuzzy even for that, this is a judgement call — convene [council](council.md) instead.

package/src/skills/git-archaeology.md

@@ -2,7 +2,7 @@
 
 > {{DESC_GIT_ARCHAEOLOGY}}
 
-**Trigger:** you need to learn something *from* the history — when a regression was
+**Trigger:** something must be learned *from* the history — when a regression was
 introduced, who last touched a line and why, or where a symbol or string entered the
 codebase. Read-only: this {{SKILL}} investigates, it does not change history (to repair
 or rewrite, use git-rescue.md; to write a new commit, use commit.md).

package/src/skills/git-rescue.md

@@ -2,9 +2,10 @@
 
 > {{DESC_GIT_RESCUE}}
 
-**Trigger:** the repository is in a broken or messy state — a bad rebase/merge/reset,
-lost commits, a detached HEAD, a half-finished operation, work stranded in a stash — or
-you intend to deliberately rewrite history (interactive rebase, squash, amend). For
+**Trigger:** commits are lost, a rebase/merge/reset went wrong, or history is to be
+deliberately rewritten (interactive rebase, squash, amend). The repository can also be
+messy in other ways: a detached HEAD, a half-finished operation, or work stranded in a
+stash. For
 finding *when/why* something changed without altering history, use git-archaeology.md.
 
 ## Procedure

package/src/skills/handoff.md

@@ -2,7 +2,7 @@
 
 > {{DESC_HANDOFF}}
 
-**Trigger:** the context window is filling, a session is ending mid-task, or you're passing work to another agent or developer.
+**Trigger:** the context window is filling, a session is ending mid-task, or work is passing to another agent or developer.
 
 ## Procedure
 1. Capture the state in the worklog (`WORKLOG.md` or the task's plan file): the goal, what's done, the step in progress, and the exact next step.