geneseed 3.11.0 → 3.12.0

package/registry.json

@@ -134,6 +134,13 @@
       "added": "2026-06-03",
       "last_verified": "2026-09-06"
     },
+    "skills/brick-forge": {
+      "status": "experimental",
+      "version": "0.1.0",
+      "owner": "Guillaume Lemer",
+      "added": "2026-10-03",
+      "last_verified": ""
+    },
     "skills/bruno-collection-generator": {
       "status": "experimental",
       "version": "1.0.0",
@@ -302,6 +309,13 @@
       "added": "2026-10-02",
       "last_verified": ""
     },
+    "skills/loop": {
+      "status": "experimental",
+      "version": "0.1.0",
+      "owner": "Guillaume Lemer",
+      "added": "2026-10-03",
+      "last_verified": ""
+    },
     "skills/migrate": {
       "status": "approved",
       "version": "1.0.0",

package/src/AGENT.md.tmpl

@@ -266,6 +266,8 @@ the ten council seats are convened by the [council {{SKILL}}]({{DIR_SKILLS}}/cou
 | [council]({{DIR_SKILLS}}/council.md) | a decision, change, or discussion needs debating from several points of view before committing |
 | [workflow]({{DIR_SKILLS}}/workflow.md) | deterministic, code-driven orchestration of subagents (fan-out, find→verify, phased handoff) and the host exposes a workflow tool |
 | [pipeline]({{DIR_SKILLS}}/pipeline.md) | foreman mode triages a substantial task, or the user asks to run a crew (analyst → developer → tester) on one, isolated in its own worktree and merged on mechanical proof |
+| [loop]({{DIR_SKILLS}}/loop.md) | the user asks to run a loop |
+| [brick-forge]({{DIR_SKILLS}}/brick-forge.md) | a new or adapted loop brick |
 | [wiki]({{DIR_SKILLS}}/wiki.md) | consulting or growing the user's machine-wide knowledge base declared in `wiki.jsonc` (§8) |
 | [herdr]({{DIR_SKILLS}}/herdr.md) | running inside a [herdr](https://herdr.dev) pane (`HERDR_ENV=1`) and a task needs another pane — a sibling server, a watched build, a spawned agent |
 | [rule]({{DIR_SKILLS}}/rule.md) | anything the user wants to outlive this session — a standing rule of their own (§1) or a durable fact to remember (§5); also a recurring {{MEMORY}} lesson due for promotion |

package/src/bricks/README.md

@@ -0,0 +1,32 @@
+# Bricks
+
+A brick is one node of a loop graph: a single prompt, handed to one agent or skill, that reports
+back one of a declared set of outcomes. `geneseed loop next` reads the current node's brick and
+hands its body to the model verbatim — the model never sees this file as a file, only as the
+instructions inside it.
+
+A brick is a markdown file, `<name>.md`, with flat YAML-ish frontmatter (`name`, `description`,
+`effect`, exactly one of `agent` or `skill`, `outcomes`) and a plain-prose body. See
+`_template.md` for the field-by-field shape.
+
+## The three origins
+
+A brick's name is looked up across three levels, each one able to override the level before it
+by name:
+
+| origin | path | who writes it |
+|---|---|---|
+| shipped | `src/bricks/` (this directory) | Geneseed itself |
+| global | `$XDG_CONFIG_HOME/geneseed/bricks/` | the user, for every project on this machine |
+| project | `<repo>/.geneseed/bricks/` | a team, committed and shared |
+
+A global or project brick named `apply` replaces the shipped `apply` everywhere a loop template
+references it — the template does not have to change, and `geneseed loop check` reports the
+override rather than hiding it.
+
+## Writing one
+
+Start from `_template.md`, or ask the `brick-forge` skill to draft one for an agent or skill you
+already have. Keep the body to 4-10 lines of direct instruction, and end it with how the model
+should choose among the outcomes you declared — that sentence is what turns a vague brief into a
+loop that actually terminates.

package/src/bricks/_template.md

@@ -0,0 +1,32 @@
+<!--
+  A brick template — copy this file to `<name>.md` (kebab-case, matching the `name:` field
+  below) under `bricks/` at whichever level you are authoring for: shipped (this package's
+  `src/bricks/`), global ($XDG_CONFIG_HOME/geneseed/bricks/), or project (<repo>/.geneseed/bricks/).
+  A later level overrides an earlier one BY NAME. Leading-underscore files (like this one) and
+  README.md are never loaded as bricks.
+
+  Everything below the closing `---` is the brick's BODY: the prompt `geneseed loop next` hands
+  the agent, verbatim, plus the card fields it receives. No double-brace substitution tokens in
+  the body — the loop CLI reads this file raw and hands it straight to the model, unrendered.
+-->
+---
+name: my-brick
+# One line, shown wherever the catalogue is listed. Not the instructions themselves.
+description: One line describing what this brick does.
+# `read` never touches a file — the engine does not score or diff its iteration.
+# `mutate` may change files — its diff is scored against the declared card before commit.
+effect: read
+# Exactly one of agent OR skill (never both, never neither) — who carries out the body below.
+# `agent: <name>` names a spec under `src/agents/`.
+agent: tester
+# `skill: <name>` names a spec under `src/skills/` instead of an agent — delete `agent:` above
+# if you use this.
+# skill: some-skill
+# Every outcome the body can report, comma-separated — these become the edge labels a loop
+# template routes on (`{from, on: "<outcome>", to}`). A loop template's graph check requires
+# exactly one edge per outcome declared here.
+outcomes: pass, fail
+---
+Say, in direct instructions, what the agent or skill should do with the card it receives — 4 to
+10 lines, no more. End with exactly how to choose between the declared outcomes, so the model's
+last read is the decision it has to make.

package/src/bricks/apply.md

@@ -0,0 +1,17 @@
+---
+name: apply
+description: Implement the current card's intent, touching only its declared write set.
+effect: mutate
+agent: developer
+outcomes: pass
+---
+Implement the card's intent exactly, touching only the files in its `writeSet`. If the card
+carries an `amend`, that supersedes the original intent — follow the amendment, not the plan it
+replaced.
+
+Make no unrelated edits: no drive-by rename, no incidental cleanup, no touching a file the card
+did not declare. If the change genuinely needs a file outside the write set, stop and report that
+rather than widening scope unasked — the diff is scored against the declared set, not your
+judgement of what else looked wrong.
+
+Report `pass` once the change is made, with a short account of what changed and where.

package/src/bricks/baseline-green.md

@@ -0,0 +1,17 @@
+---
+name: baseline-green
+description: Confirm the suite and linter are green before the loop changes anything.
+effect: read
+agent: tester
+outcomes: pass, fail
+---
+Run this project's full test suite and its linter, unchanged — no fix, no skip, no retry with
+different flags. This is the loop's starting line, not a chance to tidy up first.
+
+Report `pass` only if every test and the linter both exit clean. Include the raw command output
+in your report either way, so a `fail` carries the actual failure rather than a summary of it.
+
+Report `fail` on the first red suite or linter run, and stop there: a loop that starts on a red
+baseline cannot tell its own changes apart from pre-existing breakage.
+
+Never edit, create or delete any file: this brick only reads.

package/src/bricks/bruno-test.md

@@ -0,0 +1,16 @@
+---
+name: bruno-test
+description: Write or update Bruno requests for the endpoints this iteration touched.
+effect: mutate
+skill: bruno-test-writer
+outcomes: pass, fail
+---
+Follow the bruno-test-writer skill for every endpoint this iteration's diff added or changed.
+Touch only the Bruno collection — new or updated `.bru` requests and their expectations — never
+the application code.
+
+Report `pass` once every touched endpoint has a request that exercises it and asserts on the
+response.
+
+Report `fail` if an endpoint cannot be exercised this way (missing auth fixture, no reachable
+instance, an endpoint the diff removed), naming which one and why.

package/src/bricks/ci-fix.md

@@ -0,0 +1,17 @@
+---
+name: ci-fix
+description: Fix the failing CI check named in the card.
+effect: mutate
+skill: ci-fix
+outcomes: pass, fail
+---
+Follow the ci-fix skill against the failing check the card names — read its actual log, not a
+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 `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/deps-audit.md

@@ -0,0 +1,14 @@
+---
+name: deps-audit
+description: Audit this iteration's dependency changes for known vulnerabilities.
+effect: read
+skill: deps-audit
+outcomes: pass, fail
+---
+Follow the deps-audit skill against the dependency manifest this iteration's diff touched (or the
+whole manifest, if nothing else scopes it). Never edit any file; this brick only observes.
+
+Report `pass` if the audit finds nothing at high severity or above.
+
+Report `fail` on any finding at high severity or above, naming the package, the version, the
+advisory, and the fix the skill recommends (upgrade, pin, or removal).

package/src/bricks/docs-update.md

@@ -0,0 +1,15 @@
+---
+name: docs-update
+description: Update the documentation this iteration's diff made stale.
+effect: mutate
+agent: docs
+outcomes: pass
+---
+Read this iteration's diff and find every doc it made stale: a changed signature, a renamed
+flag, a moved file, a behaviour the README or docs still describe the old way.
+
+Update only those docs, only to match what the diff actually changed. Do not rewrite unrelated
+prose, reorganize a page, or fix an unrelated staleness you happen to notice while in there.
+
+Report `pass` once every doc the diff touched is back in sync, naming the files you changed — or
+that none needed it, if the diff left nothing stale.

package/src/bricks/identify.md

@@ -0,0 +1,20 @@
+---
+name: identify
+description: Choose the next iteration of the loop, or declare the requirement done.
+effect: read
+agent: explorer
+outcomes: more, done
+---
+Read the requirement and the loop's history (LOOP.md, `git log --format=%(trailers)` on this
+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>"],
+ "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.
+
+Never edit, create or delete any file: this brick only reads.

package/src/bricks/lint.md

@@ -0,0 +1,14 @@
+---
+name: lint
+description: Run the project's linter alone, without the test suite.
+effect: read
+agent: tester
+outcomes: pass, fail
+---
+Run this project's linter only — not the test suite, which is `test`'s job. Never edit any file;
+this brick only observes.
+
+Report `pass` if the linter exits clean.
+
+Report `fail` otherwise, with the raw linter output (every violation, not a count or a summary)
+so the next `apply` can act on the actual finding.

package/src/bricks/plan.md

@@ -0,0 +1,17 @@
+---
+name: plan
+description: Split the requirement into an ordered list of iterations before any code changes.
+effect: read
+agent: architect
+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": []}
+
+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.

package/src/bricks/reproduce.md

@@ -0,0 +1,16 @@
+---
+name: reproduce
+description: Write the smallest test that reproduces the bug and watch it fail.
+effect: mutate
+agent: tester
+outcomes: pass, fail
+---
+Write the smallest possible test that demonstrates the bug the requirement describes. Run it and
+confirm it fails, and that it fails FOR THE STATED REASON — not for an unrelated error.
+
+Touch only the new test file; do not change any production code here, and do not try to make the
+test pass. A reproduction that already passes proves nothing.
+
+Report `pass` once a failing reproduction exists, with the test's path and the failure it shows.
+Report `fail` if the bug cannot be reproduced from the requirement as written — say what you
+tried and why each attempt did not fail the way the requirement claims.

package/src/bricks/review.md

@@ -0,0 +1,17 @@
+---
+name: review
+description: Review this iteration's diff against the card it was supposed to implement.
+effect: read
+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.
+
+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.

package/src/bricks/security-scan.md

@@ -0,0 +1,17 @@
+---
+name: security-scan
+description: Security review of this iteration's diff.
+effect: read
+agent: security
+outcomes: pass, fail
+---
+Read this iteration's diff and review it for security issues: injected input reaching a
+dangerous sink, a widened trust boundary, a secret written to disk or logs, a weakened auth or
+permission check — anything that would not survive a real security review.
+
+Never edit any file; this brick only observes and reports.
+
+Report `pass` if nothing in the diff raises a security concern.
+
+Report `fail` with each finding as `file:line`, the concrete risk, and the fix — severe enough to
+block the iteration, not a style nit that belongs in `review` instead.

package/src/bricks/test.md

@@ -0,0 +1,14 @@
+---
+name: test
+description: Run the suite and linter over this iteration's change.
+effect: read
+agent: tester
+outcomes: pass, fail
+---
+Run this project's full test suite and its linter over the current change. Never edit any file —
+this brick only observes; a fix belongs in `apply`, not here.
+
+Report `pass` only if both exit clean.
+
+Report `fail` otherwise, with the raw failures (not a paraphrase) so `apply` can act on the actual
+error rather than your summary of it. Name every failing test and lint violation you saw.

package/src/doctrines/process.md

@@ -85,7 +85,9 @@ time — a personal feature branch included. A one-time approval is not standing
 consent. Consent may cover a **named batch**: "commit as you go on this branch"
 stands for commits on that branch until the session ends or the scope changes; a
 new session, a new branch, or a widened scope re-asks. Push earns no such default
-and stays per-ask unless granted in the same named form. Before each, present in
+and stays per-ask unless granted in the same named form. A launched loop's batch
+covers commit and push on its own `loop/*` branch; merging that branch into a
+shared one never is. Before each, present in
 order (1) a plain-language summary of what changed and why and (2) the exact
 commit message you intend to use, then wait. Never push on your own initiative.
 On a **shared branch** — `main`, `master`, `develop`, `development`, a
@@ -97,13 +99,14 @@ through the git-rescue {{SKILL}} behind a backup. The host gates commit and push
 the tool boundary too, so this consent cannot be lost to a sticky allowlist.
 <!-- LEAN:else -->
 Recording and sharing code is consented, never unilateral: **every** `git commit` and
-`git push` needs the user's **explicit acceptance**, on every branch, every time; a
-one-time approval is not standing consent. A named batch ("commit as you go") stands until
-the session ends or scope changes; push earns no default. Before each, present the plain
-summary of what changed and why, the exact commit message, then wait. Shared branches —
-`main`, `master`, `develop`, `development`, `release`/`hotfix`, any you are unsure of —
-take the same gate. Never force-push, hard-reset, or rebase one: undo with a revert commit
-(git-rescue {{SKILL}} for a legitimate rewrite). The host gates both at the tool boundary.
+`git push` needs **explicit acceptance**, every branch, every time; one-time approval is
+not standing consent. A named batch ("commit as you go") stands until the session ends or
+scope changes; push earns no default. A launched loop's batch covers commit and push on
+its own `loop/*` branch only; merging it never. Show the plain summary and the exact
+commit message before each, then wait. Shared branches — `main`, `master`, `develop`,
+`development`, `release`/`hotfix`, any unsure — take the same gate. Never force-push,
+hard-reset, or rebase one: undo with a revert commit (git-rescue {{SKILL}} for a
+legitimate rewrite). The host gates both at the tool boundary.
 <!-- LEAN:end -->
 
 ### {{DOCTRINE:bound-the-loop}} Bound the Loop

package/src/loops/bugfix.json

@@ -0,0 +1,22 @@
+{
+  "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.",
+  "nodes": ["reproduce", "identify", "apply", "test", "review"],
+  "start": "reproduce",
+  "edges": [
+    { "from": "reproduce", "on": "pass", "to": "identify" },
+    { "from": "reproduce", "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": "fail", "to": "apply" },
+    { "from": "test", "on": "pass", "to": "review" },
+    { "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

@@ -0,0 +1,21 @@
+{
+  "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"],
+  "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": "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/refactor.json

@@ -0,0 +1,20 @@
+{
+  "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.",
+  "nodes": ["baseline-green", "identify", "apply", "test"],
+  "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": "identify" },
+    { "from": "test", "on": "fail", "to": "apply" }
+  ],
+  "loops": [
+    { "name": "iterations", "nodes": ["identify", "apply", "test"], "max": 20, "iteration": true },
+    { "name": "apply-test", "nodes": ["apply", "test"], "max": 5 }
+  ],
+  "weights": { "logic": 0.6 }
+}

package/src/skills/brick-forge.md

@@ -0,0 +1,46 @@
+# {{SKILL}}: brick-forge
+
+> {{DESC_BRICK_FORGE}}
+
+**Trigger:** the user wants a new loop brick, or to adapt an existing one to their stack — "make
+a brick for…", "our tests run differently, change the `test` brick", "the loop needs a step
+that…".
+
+## Procedure
+
+1. **Interview, one question at a time:**
+   - **name** — kebab-case, the file stem.
+   - **what it does** — one line; it becomes `description`.
+   - **effect** — does it ever create, edit or delete a file? Yes → `mutate`; never → `read`;
+     unsure → `mutate`. A `read` brick that writes stops the loop.
+   - **who runs it** — exactly one of an `agent` (one of the {{AGENTS}}) or a `skill`.
+   - **outcomes** — every result it can report, comma-separated. Each becomes an edge label a
+     loop graph must route (`{from, on: "<outcome>", to}`).
+   - **level** — project `<repo>/.geneseed/bricks/` (committed, shared with the team), global
+     `$XDG_CONFIG_HOME/geneseed/bricks/` (default `~/.config/geneseed/bricks/`, every project on
+     this machine), or shipped `src/bricks/` — only inside the Geneseed repository itself.
+2. **Write `<level>/<name>.md`**, the file stem equal to `name`:
+
+   ```
+   ---
+   name: <kebab-name>
+   description: <one line>
+   effect: read | mutate
+   agent: <agent>            (or  skill: <skill> — exactly one of the two)
+   outcomes: <a>, <b>
+   ---
+   <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.
+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
+   `geneseed loop check` from the repository (the whole catalogue, including every template that
+   now routes through it). Fix every listed problem and re-run both.
+
+## Done when
+
+- The brick file exists at the chosen level, and both checks print `ok: true`.
+
+<!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/geneseed.md

@@ -8,7 +8,7 @@
 1. **Locate.** Run `geneseed status --json` first: `installs` lists every install on this machine — host, scope, root, state, theme, footprint, posture, mode, packs, excluded rules — and `rebuild`, the command that reproduces each one exactly. `geneseed` not on PATH → ask the user before using `npx geneseed` (it downloads the package), and prefix every command below the same way. Still nothing → look for a host root file: `~/.config/opencode/AGENT.md` or `.opencode/AGENT.md` (OpenCode), `~/.claude/CLAUDE.md` or `.claude/` (Claude Code), `.openclaude/` (OpenClaude), `AGENTS.md` beside `.bob/` (Bob). None → say so; never install to "fix" it.
 2. **Read state** with the read-only verbs, cheapest first ({{DOCTRINE:context-economy}}): `geneseed status --json`, `geneseed version`, `geneseed catalog` (optionally `agents|skills|laws|ontology|doctrines`), `geneseed doctor`, `geneseed diff`, `geneseed mcp`, `geneseed memory list`, `geneseed exclude list`.
 3. **Read a piece** from disk, not from recall ({{LAW:verify-before-asserting}}): `<root>/agents/<name>.md`, `<root>/skills/<name>/SKILL.md`, `<root>/memory/`, `<root>/notebook/`. The {{ONTOLOGY}}, the {{LAWS}} and the active {{DOCTRINES}} are numbered `## N. …` sections of the install's root file.
-4. **Change an install only when the user asked for that change** ({{LAW:one-intent-one-act}}). Take that install's `rebuild` command from step 1, edit only the flag the user named (add it if the command omits it — `--posture` and `--mode` are left out at their defaults) — `--theme`, `--footprint lean|full`, `--posture`, `--mode direct|foreman`, `--doctrines craft,rigor|none`, `--exclude-rules "process 7"|none` — dry-run it first by running the same flags through `geneseed validate`, show the command, and run it once the user agrees. Never rebuild from a bare `geneseed build`: every omitted flag resets that setting to the generator default. Confirm with `geneseed status`.
+4. **Change an install only when the user asked for that change** ({{LAW:one-intent-one-act}}). Take that install's `rebuild` command from step 1, edit only the flag the user named (add it if the command omits it — `--posture`, `--mode` and `--trust` are left out at their defaults) — `--theme`, `--footprint lean|full`, `--posture`, `--mode direct|foreman`, `--trust prudent|balanced|aggressive`, `--doctrines craft,rigor|none`, `--exclude-rules "process 7"|none` — dry-run it first by running the same flags through `geneseed validate`, show the command, and run it once the user agrees. Never rebuild from a bare `geneseed build`: every omitted flag resets that setting to the generator default. Confirm with `geneseed status`.
 5. **Other writes also need the user's word:** `geneseed memory rm <name>`, `geneseed exclude add|remove <path>`, `geneseed web start|stop`, `geneseed uninstall --target <root> --yes`. Personal rules and the profile belong to their own {{SKILLS}}; do not edit `user-rules.md` or `PROFILE.md` from here.
 6. **Never on your own initiative:** `geneseed setup` (interactive only), `geneseed upgrade`, `geneseed update`, `geneseed bootstrap`, `geneseed sync-self`, `geneseed rebuild-all`, `geneseed migrate`, `geneseed link`, `geneseed unlink`. `learn`, `context` and the `*-gate` verbs are `geneseed-hook` verbs the host's hooks run — never run them by hand.
 7. Directory and section names are plain English in every theme; only prose changes. Do not search by flavour words.

package/src/skills/loop.md

@@ -0,0 +1,99 @@
+# {{SKILL}}: loop
+
+> {{DESC_LOOP}}
+
+**Trigger:** the user asks to run a loop, or to work a requirement in small validated
+iterations, each one committed on its own; or names a loop template (`bugfix`, `refactor`,
+`feature`).
+
+Default trust preset: **{{TRUST_LABEL}}**
+
+The preset passed to `init` is `{{TRUST}}` unless the user names another (`prudent`,
+`balanced`, `aggressive`).
+
+## What it is
+
+`geneseed loop` is a state machine kept in `LOOP.md` at the worktree's root. It decides every
+transition, ceiling, score and stop; you run the node it hands you and report the outcome. Every
+action prints one JSON object — act on its keys, never on your own reading of the graph.
+
+## Setup
+
+1. `git worktree add ../<repo>-loop-<slug> -b loop/<slug>`, then make that worktree the session's
+   working directory with its own command. Every later command runs there **as written below**:
+   no `cd` prefix, no `git -C`, no quoted refspec — any of those makes the git gate ask.
+2. On a `loop/*` branch with a launched loop, the git gate lets exactly the commit form below
+   through without asking. Merging into a shared branch is never yours.
+
+## Compose
+
+3. Use a template when the user names one. Otherwise run `geneseed loop check`: it lists the
+   `templates` and every brick (`name`, `description`, `effect`, `agent`/`skill`, `outcomes`,
+   `available`). Compose a graph JSON from available bricks — skip one marked unavailable or whose
+   `skill` you do not have: `name`, `nodes`, `start`, `edges` of `{from, on, to}` (one per
+   outcome; `$close`/`$stop` are terminals), `loops` with exactly one `"iteration": true`. The
+   iteration loop's first node is where every iteration begins (normally `identify`).
+   Write it to `<name>.json` in the OS temp directory — never inside the worktree, where it would
+   be scored and committed — and validate it: `geneseed loop check --graph <file>`.
+4. `geneseed loop init --title "<title>" --requirement "<requirement>" --graph <template|file> --preset {{TRUST}}`.
+   A refused graph prints `problems` — fix them and retry.
+
+## The cycle
+
+Repeat `geneseed loop next` and act on its JSON:
+
+- **`{awaiting}`** — a person must decide. Present it: `launch` → the graph in `LOOP.md`;
+  `declared` → the card, its score and the threshold; `actual` → `git diff --cached` and the
+  `reasons`. Then **end the run** and wait. On their answer:
+  `geneseed loop decide --verdict ok|no|amend --note "<their words>"` and continue.
+- **`{verify, run}`** — run exactly the `run` command it prints.
+- **`{node, validate: true}`** — score the card before the brick runs:
+  `geneseed loop score --declared` (the card `identify` recorded), or for a setup brick with no
+  card `geneseed loop score --declared --actions <kinds> --write-set <files> --intent <label>`.
+  `blocking` turns into an `{awaiting}` on the next `next`.
+- **`{node}`** — run the brick: dispatch its `agent` (or follow its `skill`) with the `prompt`,
+  the `card` and the `notes`. Then report the outcome, one of its `outcomes`:
+  `git status --porcelain | geneseed loop record --outcome <outcome>` — `identify` adds
+  `--card '<card json>'` when it reports `more`.
+- **`{terminal: "$close"}`** — see *The end*. **`{terminal: "$stop"}`** — report the `reason`
+  and the `summary`, and leave the branch as it is.
+
+What `score --diff`, `decide` and `record` print back:
+
+- **`{commit: true, message_file}`** — close the unit with exactly this command, nothing added:
+  `git add -A && git commit -F <message_file> && git push -u origin HEAD:loop/<slug>`
+  Never `git commit -m`: only this form is exempt; anything else asks. It assumes a remote named
+  `origin` and a `message_file` path without spaces: if the path has a space, quote it and accept
+  that the gate asks; with no remote, report and stop instead of retrying.
+- **`{discard: true}`** (with `resplit` when an inner ring was exhausted) — set the attempt aside,
+  keeping `LOOP.md`: `git stash -u -m loop-discarded -- . :^LOOP.md` (never `git stash push` —
+  the word `push` trips the git gate mid-run).
+- **`{done: true}`**, **`{empty}`**, **`{resumed}`**, **`{dropped}`**, **`{node}`**, **`{verify}`**,
+  **`{stopped}`**, a declared score, and any result with `commit: false` (a blocking diff score
+  included — it surfaces as `{awaiting}`) — call `next` again.
+- **`{error}`** — read it; it names the step you skipped (`score --declared` before a mutate
+  brick, `score --diff` before `record`). Do the step, never edit the state block to get past it.
+  An `{error}` from `record` that mentions JSON means the shell mangled the card's quotes: retry
+  with the card on a single line and no single quotes inside it.
+
+## The end
+
+5. On `$close`: `git rm -f LOOP.md` (the engine rewrote it after the last commit), then
+   `git commit -m "loop(<slug>): close" && git push -u origin HEAD:loop/<slug>`.
+   This final commit is outside the exemption — the loop is no longer running — so the gate
+   asks: that ask is the user's consent to close the loop.
+6. Report: the iteration count, the **soft** iterations from `summary.review` under
+   "to review", the `notes`, and the branch to merge. **Never merge.**
+
+## Resume
+
+After a crash or an answered `awaiting`, from the worktree: `geneseed loop next`. The state is
+`LOOP.md` plus the branch — nothing else to restore. The user may edit `preset` or `contracts`
+in `LOOP.md`; they apply from the next score.
+
+## Done when
+
+- `$close` is reported with the branch pushed and `LOOP.md` removed, or `$stop` is reported with
+  its reason — and in both cases nothing was merged.
+
+<!-- INCLUDE: skills/_self-improvement.md -->

package/themes/_TEMPLATE.json

@@ -56,6 +56,8 @@
   "DESC_PONYTAIL": "<one-line description: force the laziest working solution — minimal, shortest path, stdlib/native before custom code; lite/full/ultra intensity>",
   "DESC_PARALLEL_AGENTS": "<one-line description: fan independent subtasks to concurrent subagents, then converge>",
   "DESC_PIPELINE": "<one-line description: spawn a small crew — analyst, developer, tester — to work a substantial task in isolation, merging only on mechanical proof (tests + lint green)>",
+  "DESC_LOOP": "<one-line description: work a requirement in small scored iterations on a loop/* branch, stepping the geneseed loop state machine>",
+  "DESC_BRICK_FORGE": "<one-line description: author or adapt a loop brick at project, global or shipped level, checked by geneseed loop check>",
   "DESC_DEVELOP": "<one-line description: drive a code change through cover-and-verify — smallest change, tests written for it, affected suite green, committed slice by slice>",
   "DESC_TEACH": "<one-line description: teach toward a result — crash course, decode confusing material, or a day-by-day path to a deadline>",
   "DESC_QUIZ": "<one-line description: test what the user knows instead of explaining — drill, explain-it-back check, or mastery claim stress-tested>",

package/themes/biker.json

@@ -56,6 +56,8 @@
   "DESC_PONYTAIL": "The laziest fix that rides — least code, shortest road; stock parts before custom builds, one line before fifty. lite/full/ultra.",
   "DESC_PARALLEL_AGENTS": "Send several riders on independent runs at once, then bring in what they gather.",
   "DESC_PIPELINE": "Send a small crew of riders — scout, wrench, test rider — to work a job in their own lane, rolling it into the pack only once the road-test comes back clean.",
+  "DESC_LOOP": "Ride a requirement in short, scored laps on its own loop/* lane, the loop engine calling every turn.",
+  "DESC_BRICK_FORGE": "Build or re-tune a loop brick, then run it past geneseed loop check.",
   "DESC_DEVELOP": "Push a change through the run — the smallest turn of the wrench, a test written to cover it, the touched trials green, sealed slice by slice.",
   "DESC_TEACH": "Get a rider road-ready — a crash course from never-ridden to rolling, a confusing manual decoded till it clicks, or a day-by-day route to a deadline.",
   "DESC_QUIZ": "Test what they've actually got instead of explaining it — drill a move to reflex, make them talk you through it, or call the bluff on a claimed skill — with a straight readout of the gaps.",

package/themes/commentator.json

@@ -56,6 +56,8 @@
   "DESC_PONYTAIL": "The laziest line that finishes — least code, shortest path; standard kit before custom builds, one line before fifty. lite/full/ultra.",
   "DESC_PARALLEL_AGENTS": "Send several drivers out on independent stints at once, then bring in what they gather.",
   "DESC_PIPELINE": "Send a small crew — scout, mechanic, test driver — out on their own stint, and only wave them into the results once the timing sheet comes back clean.",
+  "DESC_LOOP": "Run a requirement in short, scored laps on a loop/* branch, the loop engine calling every move.",
+  "DESC_BRICK_FORGE": "Build or adapt a loop brick, then put it through geneseed loop check.",
   "DESC_DEVELOP": "Drive the change through cover-and-verify — the smallest setup tweak, a trial written to time it, the affected laps green, sealed corner by corner.",
   "DESC_TEACH": "Bring a rookie up to speed — a crash course to race-ready, a confusing regulation decoded until it clicks, or a day-by-day programme to the deadline.",
   "DESC_QUIZ": "Test the driver instead of briefing them — a drill to reflex, an explain-it-back debrief, or a claimed mastery stress-tested — with a frank readout of the gaps.",