geneseed 3.11.0 → 3.12.0

package/CHANGELOG.md

@@ -8,6 +8,45 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
 
 ## [Unreleased]
 
+## [3.12.0] — 2026-10-03
+
+**Upgrading:** re-emit after installing (`geneseed rebuild-all`) to get the `loop` and
+`brick-forge` skills, the loop-branch git-gate rule and the amended consent doctrine; then
+`geneseed web restart` for the Loops page.
+
+### Added
+- **Loops** — work a requirement in small validated iterations on a `loop/*` branch. A loop is a
+  graph of reusable **bricks** (13 shipped in `src/bricks/`; templates `bugfix`, `refactor`,
+  `feature` in `src/loops/`), or a graph the model composes from the catalogue. Your own bricks
+  live in `$XDG_CONFIG_HOME/geneseed/` or a repo's `.geneseed/`, and override shipped ones by name.
+- **`geneseed loop check|init|next|score|record|decide`** — a deterministic state machine: the
+  model only reports outcomes. Each iteration's risk is the max of its declared actions' weights,
+  re-scored on the real diff before commit; `LOOP.md` holds the state and every iteration commit
+  carries `Loop-*` trailers. Ceilings: 20 iterations, 2 empty diffs, one re-split of an exhausted
+  inner ring.
+- **`--trust prudent|balanced|aggressive`** build axis (default balanced, also in the console's
+  install form) — how much a loop may do before it stops: silent (trailers only), soft (listed for
+  review at the end), or blocking (the run ends and `geneseed loop decide` resumes it).
+- **`loop` and `brick-forge` skills.**
+- **Console: Loops page** — templates drawn as rings (inner rings for apply ⇄ test and review ⇄
+  fix, a gate before the first code-changing step), every brick with its source and origin, and
+  catalogue problems.
+- **Documentation for loops** (`docs/concepts/loops.md`): bricks, templates and the three
+  origins, the trust presets and the three validation levels, `LOOP.md` and its trailers, the
+  `loop/*` branch exemption and why merging always asks, and the `geneseed loop` actions table.
+  Cross-linked from `foreman-mode.md`; `glossary.md` gains `brick`, `iteration`, `loop` and
+  `trust preset`.
+
+### Changed
+- **Consent Before Push**: a launched loop's batch covers commit and push on its own `loop/*`
+  branch, in a fixed set of command forms (`git commit -F <file>`, `git push <remote> HEAD:<loop
+  branch>`); anything else asks, the final commit asks, and merging never belongs to the batch.
+  Enforced by the git gate on Claude Code, Bob and OpenClaude, and by `geneseed-guard` on OpenCode.
+
+### Fixed
+- **`geneseed web stop|restart|status --port N`** act on that port only; a stop aimed at a test
+  instance no longer shuts down the console recorded on another port (#175).
+
 ## [3.11.0] — 2026-10-03
 
 **Upgrading:** re-emit after installing (`geneseed rebuild-all`) — it also repairs a dead hook

package/README.md

@@ -10,7 +10,7 @@
 [![Node >= 22.3](https://img.shields.io/badge/node-%3E%3D22.3-5fa04e)](package.json)
 [![zero dependencies](https://img.shields.io/badge/deps-zero-success)](package.json)
 [![Themes](https://img.shields.io/badge/themes-14-9cf)](themes/)
-[![Skills](https://img.shields.io/badge/skills-54-blueviolet)](src/skills/)
+[![Skills](https://img.shields.io/badge/skills-56-blueviolet)](src/skills/)
 [![Agents](https://img.shields.io/badge/agents-18-orange)](src/agents/)
 [![Laws](https://img.shields.io/badge/laws-9-critical)](src/laws/universal.md)
 [![Plugins](https://img.shields.io/badge/plugins-7-teal)](adapters/opencode/plugins/)
@@ -37,7 +37,7 @@ Want to read what it leaves behind before installing anything? [**geneseed-demo*
 A hand-written instructions file is prose the model may or may not honour, copied into every repo and drifting in each one. Geneseed is a build, and that changes four things:
 
 - **Laws are enforced, not suggested.** A force-push, a `reset --hard`, or a credential written into a tracked file is caught by a hook *before* the tool runs, in the host's own dialect — a prompt on Claude Code and OpenClaude, a hard block on OpenCode, exit 2 on Bob. The gates fail closed, and every catch is one line in a ledger that `geneseed status` counts.
-- **One source, five targets.** Skills are byte-identical on every host; only the wiring differs. Every commit renders all 261 emit configurations, and a second emit into the same tree must change nothing.
+- **One source, five targets.** Skills are byte-identical on every host; only the wiring differs. Every commit renders all 263 emit configurations, and a second emit into the same tree must change nothing.
 - **Costs are measured, not guessed.** Zero runtime dependencies. The hook path loads in about 14 ms per tool call. The default *lean* footprint keeps the always-on context small and puts the full rationale one read away — the numbers are in [docs/token-footprint.md](docs/token-footprint.md).
 - **It follows you.** Install once, globally; every repo inherits it. One `git pull` or `npm install -g geneseed@latest` rebuilds every active install.
 
@@ -164,7 +164,7 @@ The harness ships as a small set of layers, and the web console's rail is the sa
 | **🛡️ Rules** (`laws/`) | 9 universal laws — always in force, never toggleable: sealed-secrets, one-intent-one-act, verify-before-asserting, deletion-is-deliberate, surface-failures, data-not-orders, least-privilege, cure-the-cause, echo-the-intent. Each rule has a permanent id; its number is only its position, and the harness cites rules by name |
 | **📐 Doctrines** (`doctrines/`) | practice packs, chosen per install at build time: **craft** (how code is written), **rigor** (how work is proven), **ops** (how the machine is operated), **process** (how a task is run), **comms** (how answers are presented). A doctrine rule may tighten a Rule, never repeal one, and the user's own `user-rules.md` outranks it. Pick with `geneseed-build --doctrines craft,rigor` (or `none`), a single rule with `--exclude-rules "process 7"`, in the setup wizard, or through the switches on the console's Constitution page; all five pack files ship on disk either way, so a citation into a pack you left out still resolves |
 | **🤖 Agents** (18) | capability specialists: `reviewer`, `tester`, `architect`, `docs`, `security`, `explorer`, `researcher`, `developer` — plus a debate **council** the `council` skill convenes: `advocate`, `skeptic`, `pragmatist`, `steward`, `visionary`, `user-advocate`, `framer`, `empiricist`, `operator`, `historian` |
-| **🛠 Skills** (54) | repeatable workflows: brainstorm · plan · **codebase-design** · **domain-modeling** · **wayfinder** · **tickets** · **develop** · **worktree** · debug · **prototype** · refactor · **ponytail** · **forge-mcp** · **bruno-collection-generator** · **bruno-test-writer** · geneseed-code-review · **fresh-eyes** · **security-audit** · **ci-fix** · **deps-audit** · **review-response** · commit · **ship** · **release** · **migrate** · **git-archaeology** · **git-rescue** · repo-map · document-project · **frontend-design** · **prose** · **ingest** · **research** · **teach** · **quiz** · **learn-mode** · handoff · roast-me · **council** · parallel-agents · **workflow** · **wiki** · **geneseed** · **rule** · **profile** · **consolidate-memory** · **skill-forge** · **opencode-theme** · **herdr** · **pipeline** · **daydream** · **react-view-transitions** · **token-report** · **explain-changes** |
+| **🛠 Skills** (56) | repeatable workflows: brainstorm · plan · **codebase-design** · **domain-modeling** · **wayfinder** · **tickets** · **develop** · **worktree** · debug · **prototype** · refactor · **ponytail** · **forge-mcp** · **bruno-collection-generator** · **bruno-test-writer** · geneseed-code-review · **fresh-eyes** · **security-audit** · **ci-fix** · **deps-audit** · **review-response** · commit · **ship** · **release** · **migrate** · **git-archaeology** · **git-rescue** · repo-map · document-project · **frontend-design** · **prose** · **ingest** · **research** · **teach** · **quiz** · **learn-mode** · handoff · roast-me · **council** · parallel-agents · **workflow** · **wiki** · **geneseed** · **rule** · **profile** · **consolidate-memory** · **skill-forge** · **opencode-theme** · **herdr** · **pipeline** · **loop** · **brick-forge** · **daydream** · **react-view-transitions** · **token-report** · **explain-changes** |
 | **🔌 Plugins** (OpenCode) | `geneseed-context` injects project docs *and your machine wiki* every session (and across compaction); `geneseed-learn` distils memory at session end; `geneseed-guard` enforces the safety Laws and protected wiki folders at the tool boundary; `geneseed-workflow` registers the `workflow` tool that runs saved orchestration scripts; `geneseed-notify` sends a native OS notification when a long run finishes; `geneseed-ponytail` holds a minimal-code mode (`/ponytail lite\|full\|ultra\|off`), opt-in, injecting the laziest-that-works ruleset every turn so it doesn't drift; `geneseed-activity` streams what each session is doing to the web console's Activity view |
 | **🧠 Memory** (`memory/`) | one-fact-per-file durable knowledge, indexed by `MEMORY.md` (git-ignored, personal) |
 | **📓 Notebook** (`notebook/`) | the agent's sovereign space — any medium (code, tools, data, notes), self-ruled via a seed-once charter, always git-ignored; only its `.gitignore` is build-asserted |

package/SHIPPED.md

@@ -20,7 +20,7 @@ historical references, not files distributed with the repo.
 > **On version numbers.** [`harness.config.json`](harness.config.json)'s `version` is a
 > human-readable label only. The canonical identity of an installed harness is the
 > **source fingerprint** stamped in `.geneseed-version` (see `geneseed version`), not the
-> string. Current label: **3.11.0**.
+> string. Current label: **3.12.0**.
 
 ## Capabilities
 
@@ -29,7 +29,7 @@ Every row below is present in the tree today; "Spec" names the design record.
 | Capability | What it is | Spec |
 | --- | --- | --- |
 | **Themed generator** | One neutral `src/` → 14 themed bundles via `geneseed-build` (zero dependencies); structure stays theme-independent | [DESIGN.md](DESIGN.md) |
-| **Laws / Agents / Skills / Memory / Notebook** | 9 laws, 18 agents, 54 skills, the memory convention, and the agent's sovereign notebook | `2026-06-11-notebook-sovereign-space` · `2026-06-10-notebook-agent-own-space` |
+| **Laws / Agents / Skills / Memory / Notebook** | 9 laws, 18 agents, 56 skills, the memory convention, and the agent's sovereign notebook | `2026-06-11-notebook-sovereign-space` · `2026-06-10-notebook-agent-own-space` |
 | **Three-tier constitution** | The governance surface splits into an always-on **Ontology** (Telos, Evidence, Decisions, Conduct — the Pact absorbed into Telos), the nine always-on **Invariants**, and five toggleable **Doctrine** packs (craft, rigor, ops, process, comms) addressed `<pack> <n>`. Every rule carries a permanent id; its number is its position, computed at render time, and a citation renders as the rule's principle name. Packs are chosen at build time with `--doctrines` or the setup wizard; the whole catalogue ships on disk either way, so a citation into an inactive pack still resolves. Precedence, in order: Ontology + Invariants, then the user's `user-rules.md`, then the active Doctrines, then `PROFILE.md`. `doctor`'s `constitutionProblems` gates rule ids (declared, unique, never a retired one), the per-rule Principle column, every `{{LAW:<id>}}` / `{{DOCTRINE:<id>}}` citation in `src/`, and the rule that an always-on tier may never cite a toggleable one | `2026-08-19-three-tier-constitution-design` |
 | **`doctor`** | One check: unresolved tokens, dead/non-hermetic links, theme-key parity, authoring gates, rendered-bundle drift | `2026-06-07-theme-aware-doctor-diff` |
 | **`diff` + improvements export** | Deployed-vs-source drift report; export an `improvements.md` back-port | `2026-06-12-improvements-export` |

package/adapters/opencode/plugins/geneseed-guard.js

@@ -16,8 +16,22 @@
 //
 // Install: dropped into the plugins dir by `build --emit opencode[-global]` (the *.js
 // glob), exactly like the context and learn plugins. Errors never break a tool call.
+//
+// `permission.ask` — the loop/* exemption (Consent Before Push). OpenCode's static
+// `permission.bash` globs (`git commit*`/`git push*` = "ask", written by
+// js/hosts/settings.mjs) cannot see which branch is checked out — they are a build-time
+// string match with no request-time context. This hook is the ONLY seam where Geneseed can
+// look at the live branch, and it only DOWNGRADES an ask to allow: only a fixed set of
+// commit/push forms (see `loopExempt` below, the twin of js/hosts/hooks.mjs's) on a `loop/*`
+// branch a loop was actually LAUNCHED on — not just named `loop/...`. It is a WHITELIST, not
+// a blacklist: a false ask costs one prompt, a false allow publishes. It never raises the
+// bar: anything not on the whitelist, anything off a launched loop branch, a status this hook
+// did not itself leave as the default "ask", or any non-bash permission leaves `output.status`
+// untouched and OpenCode's own ask (or another hook's deny) stands. A host version that never
+// fires `permission.ask` simply never reaches this hook — the static ask still fires, so the
+// failure mode is one extra prompt, never a silent allow.
 
-import { promises as fs } from "node:fs"
+import { promises as fs, existsSync, statSync, lstatSync, readFileSync, openSync, readSync, closeSync } from "node:fs"
 import * as path from "node:path"
 import { fileURLToPath } from "node:url"
 import { homedir } from "node:os"
@@ -267,7 +281,131 @@ function ruleStoreTarget(p) {
 // substring stance: over-matching the class is harmless (see WRITE_TOOLS note).
 const WIKI_MUTATE_TOOLS = [...WRITE_TOOLS, "delete", "remove", "rename", "move", "trash"]
 
-export const GeneseedGuard = async () => {
+// ---- the loop/* exemption (Consent Before Push) --------------------------------
+// Twin of js/hosts/gitref.mjs (currentBranch/loopLaunched) and js/hosts/hooks.mjs's
+// git-gate (the rest) — keep in step. Node's native sync `fs` (not the `fs.promises`
+// import above): a worktree's `.git` is read the same way the Claude/Bob hook reads it, so
+// the two decide the exemption identically. This plugin cannot import from `js/` at all
+// (it is copied whole into an OpenCode install, outside this repo's module graph), so it
+// keeps its own standalone copy rather than the single shared owner the Node side has.
+
+const GIT_GATE_RE = /\bgit\b[^\n]*\b(?:commit|push)\b/
+
+// No newline, backtick, or `$(` substitution anywhere, no `<`/`>` redirect, and no single
+// `&` (a shell runs `a & b` as two commands exactly like `a && b`) — these can smuggle a
+// second command (or a shared-branch target) past every check below. `(?<!&)&(?!&)` matches
+// a lone `&` without matching either half of a doubled `&&`.
+const UNSAFE_CHARS_RE = /[\n`<>]|\$\(|(?<!&)&(?!&)/
+
+// The only three git shapes a loop's own automation ever needs — see js/hosts/hooks.mjs's
+// identically-named constants for the full rationale. The token class `[\w./:@^~=+,-]`
+// excludes quotes, braces, `!`, `*`, `$` and `&` — a brace/glob expansion is exactly how a
+// shell turns one whitelisted-looking token into several unknown ones, which is also why the
+// `-F`/`--file` path uses this same class rather than the looser `[^\s'"]+` it once did: that
+// loose class let `git commit -F {m,--amend}` brace-expand into an amend of the last commit.
+const ARG_RE = "[\\w./:@^~=+,-]+"
+const SEG_ADD_RE = new RegExp(`^git\\s+add(\\s+${ARG_RE})*$`)
+const SEG_COMMIT_RE = new RegExp(`^git\\s+commit(\\s+-q)?\\s+(-F\\s+|--file[=\\s])${ARG_RE}(\\s+-q)?$`)
+const SEG_READONLY_RE = new RegExp(`^git\\s+(status|diff|log|rev-parse|show)(\\s+${ARG_RE})*$`)
+
+/**
+ * `git push`, exactly: `[-u|--set-upstream] <remote> HEAD:<branch>` or
+ * `HEAD:refs/heads/<branch>` — the ONLY exempt form, same as js/hosts/hooks.mjs's
+ * `pushSegmentOk`. An explicit refspec is immune to `push.default`/`remote.*.push`
+ * redirection and refuses to coexist with a mirror/`+`/`:`-prefixed form; nothing else is.
+ */
+function pushSegmentOk(seg, branch) {
+  const m = /^git\s+push(?:\s+(.*))?$/.exec(seg)
+  if (!m) return false
+  const rest = (m[1] || "").trim()
+  if (!rest) return false
+  const tokens = rest.split(/\s+/)
+  let i = 0
+  if (tokens[i] === "-u" || tokens[i] === "--set-upstream") i += 1
+  const remote = tokens[i]
+  if (remote === undefined || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(remote)) return false
+  i += 1
+  const ref = tokens[i]
+  i += 1
+  if (ref === undefined || i !== tokens.length) return false
+  return ref === `HEAD:${branch}` || ref === `HEAD:refs/heads/${branch}`
+}
+
+const LOOP_STATE_MARKER = "<!-- loop-state:begin -->"
+
+/**
+ * Whether `<root>/LOOP.md` carries the engine's state marker — read at most 64 KB.
+ * `lstatSync` (never `statSync`, which follows a link) must find an ordinary file: a FIFO
+ * would block the read, a symlink could point anywhere outside the repo.
+ */
+function loopLaunched(gitRoot) {
+  let fd
+  try {
+    const p = path.join(gitRoot, "LOOP.md")
+    if (!lstatSync(p).isFile()) return false
+    fd = openSync(p, "r")
+    const buf = Buffer.alloc(65536)
+    const n = readSync(fd, buf, 0, buf.length, 0)
+    return buf.toString("utf8", 0, n).includes(LOOP_STATE_MARKER)
+  } catch {
+    return false
+  } finally {
+    if (fd !== undefined) { try { closeSync(fd) } catch { /* already gone */ } }
+  }
+}
+
+/**
+ * The branch checked out in `cwd`, and the directory holding `.git` for it, read from
+ * .git/HEAD without spawning git — a worktree's `.git` is a FILE naming its gitdir, so both
+ * shapes are followed. `{ branch: null, root: null }` on anything unexpected (detached HEAD,
+ * no repo, unreadable): the caller then leaves the ask alone.
+ */
+function currentBranch(cwd) {
+  try {
+    let dir = path.resolve(cwd)
+    for (;;) {
+      const dotgit = path.join(dir, ".git")
+      if (existsSync(dotgit)) {
+        let gitdir = dotgit
+        if (statSync(dotgit).isFile()) {
+          const m = /^gitdir:\s*(.+?)\s*$/m.exec(readFileSync(dotgit, "utf8"))
+          if (!m) return { branch: null, root: null }
+          gitdir = path.resolve(dir, m[1])
+        }
+        const ref = /^ref:\s*refs\/heads\/(.+?)\s*$/m.exec(readFileSync(path.join(gitdir, "HEAD"), "utf8"))
+        return { branch: ref ? ref[1] : null, root: dir }
+      }
+      const up = path.dirname(dir)
+      if (up === dir) return { branch: null, root: null }
+      dir = up
+    }
+  } catch {
+    return { branch: null, root: null }
+  }
+}
+
+/**
+ * Consent Before Push's loop/* exemption — the twin of js/hosts/hooks.mjs's `loopExempt`.
+ * True only when the command carries none of the unsafe characters, every `&&`/`;`/`||`/`|`
+ * segment is one of the three whitelisted git shapes (every push segment also passing
+ * `pushSegmentOk`), and the branch checked out in `cwd` starts with `loop/` AND its git root
+ * carries a launched LOOP.md.
+ */
+function loopExempt(command, cwd) {
+  if (typeof command !== "string" || UNSAFE_CHARS_RE.test(command)) return false
+  const { branch, root } = currentBranch(cwd)
+  if (!branch || !branch.startsWith("loop/")) return false
+  if (!root || !loopLaunched(root)) return false
+  const segments = command.split(/&&|\|\||[;|]/).map((s) => s.trim()).filter(Boolean)
+  if (!segments.length) return false
+  return segments.every((seg) => SEG_ADD_RE.test(seg) || SEG_COMMIT_RE.test(seg)
+    || SEG_READONLY_RE.test(seg) || pushSegmentOk(seg, branch))
+}
+
+export const GeneseedGuard = async (ctx) => {
+  // The session's working directory, the same resolution the context plugin uses — a
+  // worktree session's `.git` is a FILE, which `currentBranch` already follows.
+  const root = () => ctx?.worktree || ctx?.directory || process.cwd()
   return {
     "tool.execute.before": async (input, output) => {
       if (OFF) return
@@ -318,6 +456,23 @@ export const GeneseedGuard = async () => {
         log(`inspect error (ignored): ${err?.message ?? err}`)
       }
     },
+    "permission.ask": async (input, output) => {
+      // Never throw from a permission hook — leave `output.status` untouched on any
+      // error, exactly as a crashed check here must default to the static ask standing.
+      try {
+        if (OFF) return
+        // Never loosen anything but the plain "ask" this hook itself would otherwise leave
+        // alone — a deny (or any other status another hook already set) is never overwritten.
+        if (output?.status && output.status !== "ask") return
+        if (input?.type !== "bash") return
+        // ONLY `input.metadata?.command` — no pattern/title fallback. A value this hook did
+        // not itself read in full is a value it must not reason about.
+        const command = input?.metadata?.command
+        if (typeof command !== "string" || !command || !GIT_GATE_RE.test(command)) return
+        if (await sovereignBypass(root())) return
+        if (loopExempt(command, root())) output.status = "allow"
+      } catch { /* leave output.status untouched */ }
+    },
   }
 }
 

package/bin/geneseed-cli.mjs

@@ -149,6 +149,10 @@ const VERBS = {
   catalog: () => import('../js/build/catalog.mjs').then((m) => m.cmdCatalog),
   mcp: () => import('../js/hosts/mcp.mjs').then((m) => m.cmdMcp),
   memory: () => import('../js/maintain/memory.mjs').then((m) => m.cmdMemory),
+  // Task 5. A fourth native verb: there was never a Python subparser for a state machine that
+  // lives entirely inside this port, so — like the three above — it has no recorded cell to
+  // compare against, only the absolute gates named beside it in `NATIVE`.
+  loop: () => import('../js/loop/cli.mjs').then((m) => m.cmdLoop),
 };
 
 function die(code, msg) {

package/docs/concepts/foreman-mode.md

@@ -9,7 +9,7 @@ link: {"hash": "#/harness", "label": "Set the mode in Harness →"}
 
 > **You already know this:** a tech lead with a team. Quick questions get answered on the spot; a real feature becomes a ticket that someone builds on a branch, and the lead reviews the result before it is merged.
 
-Mode is chosen at build time, so it does not drift mid-session, and kept across every rebuild and re-theme. It is separate from [posture](collaboration.md) (the relationship register), the doctrine packs ([Rules](rules.md)) and [footprint](footprint.md).
+Mode is chosen at build time, so it does not drift mid-session, and kept across every rebuild and re-theme. It is separate from [posture](collaboration.md) (the relationship register), the doctrine packs ([Rules](rules.md)) and [footprint](footprint.md). It is also separate from a [loop](loops.md) — a pipeline is a one-shot, uncommitted crew for a single task; a loop is a long-running state machine that commits each validated iteration on its own branch.
 
 ### direct — the default
 

package/docs/concepts/loops.md

@@ -0,0 +1,165 @@
+---
+group: concepts
+order: 11
+title: "Loops"
+kind: "concept"
+link: {"hash": "#/docs/reference/cli", "label": "geneseed loop --help →"}
+---
+A **loop** is a requirement worked as small, validated, committed iterations instead of one long
+turn. `geneseed loop` is the state machine: it decides every transition, ceiling, score and stop,
+and hands the agent one node at a time to run. The `loop` [skill](skills.md) is the only thing
+that talks to it — the agent runs the node it is given and reports the outcome, never its own
+reading of the graph.
+
+> **You already know this:** a checklist a tech lead walks through on a ticket, where some steps
+> need a sign-off before continuing and others don't. The lead doesn't improvise the order; the
+> checklist decides it, and only the risky steps stop for you.
+
+## The ring
+
+A loop is a graph of **bricks** — one node each — wired by **edges**, one per outcome a brick can
+report. One cycle through the graph back to its head is an **iteration**; the graph's `loops`
+array names every cycle that is allowed to exist, each with a `max` number of times a node inside
+it may be re-entered. Picture it as rings: the outer ring is the iteration itself (plan, apply,
+test, review, back to plan), and inner rings sit inside it for retries (apply failed its test, try
+`apply` again without going all the way back around). The three shipped templates —
+`bugfix`, `feature`, `refactor` — all nest a short `apply`↔`test` retry ring inside the iteration
+ring, and `bugfix` and `feature` nest a second, wider `apply`↔`test`↔`review` ring
+(`review-fix`) around that.
+
+Work closes into a commit whenever the graph re-enters the iteration loop's head — so any setup
+work before the loop starts (reproducing a bug, say) is its own unit, numbered iteration 0, kept
+out of iteration 1's diff. For the same reason the iteration has exactly one way in: its
+**head** is the first node listed in the iteration loop (normally `identify`), and every edge that
+enters the iteration from outside it — and `start`, when `start` is inside it — must target that
+head. `geneseed loop check` refuses a graph that enters anywhere else.
+
+**A node's re-entry budget is not each loop's `max` added up.** Every node inside one or more
+inner loops gets a single shared counter: `1 + the largest max among the inner loops that contain
+it`. A node in both a `max: 5` and a `max: 3` loop gets 6 re-entries total, not 8 — the loops don't
+stack, the larger one wins and the `+1` is the node's own first run. A node inside no inner loop at
+all gets exactly 1 — no re-entry — which is also why **every cycle inside an iteration must be a
+named inner loop** in the graph JSON: `geneseed loop check` (and `loop init`, which runs the same
+check) refuses a graph with an undeclared cycle inside an iteration, before a single node runs.
+
+## Bricks, templates, and the three origins
+
+A **brick** is a markdown file: YAML-ish frontmatter (`name`, `description`, `effect` — `read` or
+`mutate` — exactly one of `agent` or `skill`, and `outcomes`) plus a 4-10 line prose body. The
+model never sees the file; `geneseed loop next` hands it the body as the prompt. A **loop
+template** (`bugfix`, `feature`, `refactor`, or one composed by hand) is the graph JSON that wires
+bricks together.
+
+Both are looked up across three origins, each able to override the one before it **by name**:
+
+| origin | path | who writes it |
+|---|---|---|
+| shipped | `src/bricks/`, `src/loops/` | Geneseed itself — read by the CLI from its own source, never emitted into an install |
+| global | `$XDG_CONFIG_HOME/geneseed/{bricks,loops}` (default `~/.config/geneseed/…`) | the user, for every project on this machine |
+| project | `<repo>/.geneseed/{bricks,loops}` | a team, committed and shared |
+
+Precedence is project > global > shipped. A project or global brick named `apply` replaces the
+shipped `apply` everywhere a template references it, without the template changing.
+`geneseed loop check` lists every override it finds, never silently.
+
+A per-install skill exclusion is invisible to the CLI — it has no way to know which skills your
+install carries. The `loop` skill covers the gap itself: when composing a graph it skips a brick
+whose `skill` it doesn't have.
+
+To add or adapt a brick, use the `brick-forge` skill — ask it, or see
+[the bricks README](https://github.com/geneseed-dev/geneseed/blob/main/src/bricks/README.md) in
+the repository.
+
+## Risk, trust, and the three validation levels
+
+Before a `mutate` brick runs, the loop scores the card the brick's setup declared: one risk weight
+per action kind it named, and the score is the **max**, not a sum — one contract change outweighs
+ten trivial renames, and ten trivial renames never add up to one. After the brick runs, the loop
+re-scores against the real diff, and the diff can only raise the score, never lower it:
+
+- a file touched outside the declared write set raises the score to at least **api** (`0.8`);
+- more than 20 deleted lines raises it to at least the **delete** weight;
+- touching a file listed in the loop's `contracts` raises it to at least the **api** weight.
+
+`LOOP.md` itself is excluded from every score and every diff check — it's the engine's own
+bookkeeping, rewritten on every action, never part of the work being judged.
+
+The score is checked against a **trust preset** — `--preset` on `geneseed loop init`, editable
+afterward in `LOOP.md`'s `preset` field, applying from the next score on:
+
+| preset | silent ≤ | soft ≤ | above soft |
+|---|---|---|---|
+| prudent | 0.1 | 0.3 | blocking |
+| balanced (default) | 0.2 | 0.6 | blocking |
+| aggressive | 0.4 | 0.8 | blocking |
+
+Three levels follow from where the score lands:
+
+- **silent** — nothing more than the commit trailers below.
+- **soft** — listed under "to review" in the run's final summary; no notification during the run.
+- **blocking** — the run ends. `LOOP.md` is written with `status: awaiting`, and a person has to
+  answer with `geneseed loop decide --verdict ok|no|amend`. Amending a verdict marks the decision
+  `blocking (amended)` in the trailers rather than silently rewriting it to something else.
+
+## `LOOP.md` and its trailers
+
+`LOOP.md`, at the worktree root, is both the human-readable record (title, requirement, and the
+rule that you may edit `preset` or `contracts` there) and the engine's own JSON state block. Every
+closing commit carries seven trailers, read straight off that state:
+
+```
+Loop-Iteration: <n>
+Loop-Bricks: <every brick name visited this unit, deduplicated>
+Loop-Risk-Declared: <score>
+Loop-Risk-Actual: <score>
+Loop-Threshold: <preset> <silent>/<soft>
+Loop-Decision: silent | soft | blocking[ (amended)]
+Loop-Tests: <what the loop was told about test state>
+```
+
+## The `loop/*` branch, and why merge always asks
+
+A loop runs in its own worktree, on a branch named `loop/<slug>` — the `loop` skill creates both
+with `git worktree add -b loop/<slug>` before `geneseed loop init` writes `LOOP.md` there.
+While that branch is checked out and `LOOP.md` carries the engine's state marker, the git gate lets
+exactly one commit/push form through without asking:
+
+```
+git add -A && git commit -F <message_file> && git push [-u] <remote> HEAD:<loop branch>
+```
+
+Nothing else is exempt — not `git commit -m`, not a quoted refspec, not a plain `git push` with no
+explicit `HEAD:<ref>` — any other shape still asks. The exemption only ever covers a `loop/*`
+branch, and never a shared one (`main`, `master`, `develop`, `development`, `release/*`,
+`hotfix/*`). The **final** commit of a run — the one that removes `LOOP.md` on `$close` — is
+outside the exemption too, because the loop is no longer running when it lands; that ask is your
+consent to close it. **Merging a loop branch into anything else always asks, with no exception.**
+The loop reports the branch to merge and the iterations that landed in "to review" — it never
+merges for you.
+
+## `geneseed loop` actions
+
+| action | what it does |
+|---|---|
+| `check` | lists templates and every brick (available, unavailable, overridden); validates one graph file (`--graph`) or one brick file (`--brick`) |
+| `init` | writes a fresh `LOOP.md` from a template or graph file, under a title, requirement and trust preset |
+| `next` | the only driver of the cycle — returns the next thing to do: run a node, score a card, answer an `awaiting`, or a terminal |
+| `score` | scores a declared card (`--declared`) before a mutate node runs, or the real diff (`--diff`, numstat piped on stdin) before a commit |
+| `record` | records a brick's reported outcome and advances the graph |
+| `decide` | answers an `awaiting` validation with a verdict and a note |
+
+Run `geneseed loop --help` for the full flag list.
+
+## Limits
+
+- **No parallel nodes.** The graph runs one node at a time; there is no fan-out.
+- **A per-install skill exclusion is invisible to the CLI** (see above) — the `loop` skill is
+  responsible for skipping bricks it can't run, not the engine.
+
+## Not foreman mode
+
+A loop and a [foreman-mode](foreman-mode.md) pipeline are both "hand work off and keep going," but
+they solve different problems. A pipeline is a one-shot crew for a single task, uncommitted until
+you accept it. A loop is a long-running, self-scoring state machine that commits each validated
+iteration on its own branch as it goes, and only stops for a person when the risk crosses a
+threshold.

package/docs/extending.md

@@ -748,6 +748,11 @@ handler falls back to `index.html` at 200 with `text/html`, and the browser repo
 "no running server recorded" and exits 0, and `web restart` starts a *second* daemon. Recovery is
 to kill every pid on the port, then `geneseed web start`.
 
+`--port N` on `web stop|restart|status` names *which* daemon: the verb acts only if the record is
+on N, and refuses (exit 1, nothing sent) when it names another port. A test instance on another
+port is therefore stopped with `--port`, never with a bare `web stop` — that one stops whatever
+the record names, usually the live console on 4747.
+
 ---
 
 ## 10 — What to settle before the next wave

package/docs/guides/choose-your-setup.md

@@ -52,6 +52,20 @@ geneseed build --emit opencode-global --mode direct    # back to the default
 
 More in [Foreman mode](../concepts/foreman-mode.md).
 
+## Loop trust: how far a loop goes before it asks
+
+The `loop` skill scores every change it validates and stops to ask once the score passes a threshold. `--trust` sets the preset the skill starts a loop with; the user can still name another one per loop.
+
+- **prudent**: asks early, on anything past a rename.
+- **balanced** *(default)*: logic changes and new files pass with a note; API changes and deletions stop.
+- **aggressive**: only an architecture-level change stops the loop.
+
+The preset lives in the `loop` skill only, so it costs nothing in the always-on instructions.
+
+```
+geneseed build --emit opencode-global --trust prudent
+```
+
 ## Doctrine packs: which practices bind
 
 The harness's rules come in tiers (see [Rules](../concepts/rules.md)). The Ethos and the Rules are always on. The **doctrines** are practices rather than principles, and they ship as packs you choose:

package/docs/guides/install.md

@@ -66,7 +66,7 @@ From a clone, every `geneseed …` command on these pages is `./geneseed …` (W
 geneseed build --emit opencode-global --theme neutral
 ```
 
-`geneseed build` takes the same flags as the generator `geneseed-build`. `--emit` picks the host and its scope: `files`, `opencode`, `opencode-global`, `claude`, `claude-global`, `bob`, `bob-global`, `openclaude` or `openclaude-global`. A `-global` emit writes into the tool's own config directory. A project emit writes into the repo you name with `--out <repo> --root <repo>`. All the other flags (`--theme`, `--footprint`, `--posture`, `--mode`, `--doctrines`, `--exclude-rules`) are covered in [Choose your setup](choose-your-setup.md).
+`geneseed build` takes the same flags as the generator `geneseed-build`. `--emit` picks the host and its scope: `files`, `opencode`, `opencode-global`, `claude`, `claude-global`, `bob`, `bob-global`, `openclaude` or `openclaude-global`. A `-global` emit writes into the tool's own config directory. A project emit writes into the repo you name with `--out <repo> --root <repo>`. All the other flags (`--theme`, `--footprint`, `--posture`, `--mode`, `--trust`, `--doctrines`, `--exclude-rules`) are covered in [Choose your setup](choose-your-setup.md).
 
 To test a build before writing anything, use `geneseed validate` with the same flags. See [Verify](verify.md).
 

package/docs/reference/glossary.md

@@ -26,6 +26,10 @@ Every word Geneseed uses that you would not find in a general programming glossa
 | Posture | — | the relationship register the agent works in (peer, mentor, expert, assistant, artisan) | pairing style |
 | Mode | — | how work gets executed — direct (the agent works every task itself) or foreman (substantial tasks spawn an isolated pipeline) | solo vs. delegating to a sub-team |
 | Footprint | — | how much of the Rules loads inline each turn (full vs lean) | eager vs. lazy loading |
+| Loop | — | a requirement worked as small, validated, committed iterations on their own branch, driven by `geneseed loop` | a state machine over a ticket's steps |
+| Iteration | — | one cycle of a loop back to its head; closes into its own commit | one sprint-of-one through a checklist |
+| Brick | — | one node of a loop graph: a prompt for one agent or skill, reporting one of a declared set of outcomes | a step in a runbook |
+| Trust preset | — | the loop's risk tolerance — prudent, balanced (default) or aggressive — set at `loop init` and editable in `LOOP.md` | how much a reviewer lets through without a second look |
 | Profile | — | who you are — seeded once, colours but never binds | your onboarding notes |
 | Memory force | — | a memory's binding strength (constraint, choice, conviction, tempered) | MUST / SHOULD / MAY |
 | Tagline | TAGLINE | the one-line essence of the theme | — |

package/docs/reference/opencode-plugins.md

@@ -42,7 +42,9 @@ Every plugin swallows its own errors — none can block or crash a session. Each
 
 It ships whole on every install, whatever [doctrine packs](../concepts/rules.md) you chose. On Claude Code and Bob the same checks are hooks, which can *ask* you instead of refusing; OpenCode's tool hook has no ask tier. Protected wiki folders are enforced only here — on the other hosts they are an instruction.
 
-**When it runs.** Before every tool call (`tool.execute.before`).
+A `permission.ask` hook lets through only a fixed set of commit/push forms on a `loop/*` branch with a running loop — anything else still asks, same as the Claude/Bob git-gate's loop/* exemption.
+
+**When it runs.** Before every tool call (`tool.execute.before`), and before a static `permission.bash` ask is shown to you (`permission.ask`).
 
 **What you see.** A refused tool call: `[geneseed-guard] blocked: <reason> — set GENESEED_GUARD=off to allow`. Warnings go to stderr.
 

package/docs/web-ui.md

@@ -51,7 +51,7 @@ The left rail mirrors the harness's own shape:
 | Group | Views |
 | --- | --- |
 | *(ungrouped)* | Dashboard |
-| **📖 Codex** | Constitution · Rules · Profile · Skills · Agents · Library · Docs |
+| **📖 Codex** | Constitution · Rules · Profile · Skills · Agents · Library · Loops · Docs |
 | **🩺 Care** | Activity · Changes · Doctor |
 | **🎨 Setup** | Harness · Settings |
 
@@ -111,6 +111,17 @@ streams the output of background jobs and keeps their history across reloads.
   **Promote to rule** control turns a recurring lesson into a trial rule in
   `user-rules.md` — provenance recorded, the source fact deleted so it isn't loaded
   twice — landing you on the Rules page.
+- **Loops** (`#/loops`) — the loop catalogue `geneseed loop` runs from, read-only.
+  **Templates** draws the selected template as a ring: the iteration turning clockwise from
+  its head, each inner retry loop hung outside on its head node, the ⛨ *validate* gate the
+  engine adds before the first mutate step, setup entering from the left and `done → close`
+  leaving from the head; a card per brick sits under it, and clicking a node scrolls to its
+  card. A graph a ring cannot draw cleanly (more than eight iteration steps, a node in more
+  than three loops) falls back to left-to-right boxes. **Bricks** lists every brick with its
+  origin (shipped / global / project), what it overrides, why it is unavailable, and its
+  source. **Active** (live runs) is announced for v2 and disabled. Reads `GET /api/loops`,
+  resolved from the selected install's root, so a project install shows its
+  `.geneseed/` bricks and templates.
 - **Profile** (`#/profile`) — `PROFILE.md` beside the deployed AGENT.md: who you are and
   how you like to work. Opens rendered; **Edit** is a whole-file editor. The save carries
   the fingerprint it loaded — if an agent session changed the file first, your edit stays

package/harness.config.json

@@ -2,5 +2,5 @@
   "_comment": "version is a human-readable release label only; the canonical identity of an installed harness is the source fingerprint stamped in .geneseed-version (see `harness version`), not this string.",
   "theme": "neutral",
   "product": "Geneseed",
-  "version": "3.11.0"
+  "version": "3.12.0"
 }

package/js/README.md

@@ -1,6 +1,6 @@
 # `js/` — the module map
 
-Fifty-seven modules in seven folders. This page is the address book: **what each one owns**, and
+Sixty-one modules in eight folders. This page is the address book: **what each one owns**, and
 **which file to open first** for a given task. It is not documentation of behaviour — every module
 has a docblock for that, and the docblock is the thing to read before editing.
 
@@ -20,6 +20,7 @@ js/build/     src/ + themes/  →  rendered text  →  a bundle  →  a per-host
 js/hosts/     where it stops being a renderer and touches the machine
 js/inspect/   the read-only half: doctor, status, diff, validate, catalog
 js/lib/       primitives, every one a deliberate divergence from the Node default
+js/loop/      `geneseed loop` — the state machine over LOOP.md, and what it steps through
 js/maintain/  lifecycle verbs that change an install that already exists
 js/ui/        what it prints at a terminal
 js/web/       the `geneseed web` console
@@ -68,10 +69,11 @@ user co-owns, and the hook verbs those emitted configs then run.
 |---|---|
 | `hosts.mjs` | The four host config dirs (opencode/claude/bob/openclaude), plus `resolvePath`/`expanduser` |
 | `hooks.mjs` | The verbs the emitted hooks run every session: `context`, `git-gate`, `rule-gate`, `tool-gate` (the two gates fused, for Bob), `learn`. `--host` picks the verdict dialect |
+| `gitref.mjs` | fs/path-only: `gitRootOf`, `gitDirOf`, `currentBranch`, `loopLaunched` — read straight off `.git`, never spawn git. Shared by `hooks.mjs`'s git-gate and `js/loop/cli.mjs`'s commit-message writer |
 | `settings.mjs` | Merges into user-owned `settings.json`/`opencode.json`; owns the hook shim and the managed blocks |
 | `native.mjs` | Capability specs → host-native subagents and skills. The impure half of the emit |
 | `opencode.mjs` | OpenCode-only extras: colour themes, primary agent, `/commands`, plugins, overrides stub |
-| `installs.mjs` | Detects deployed installs and reads back their theme, footprint, posture and mode |
+| `installs.mjs` | Detects deployed installs and reads back their theme, footprint, posture, mode and loop trust preset |
 | `mcp.mjs` | MCP server presets, the per-host `mcpServers` config read/write, and toggle state |
 | `link.mjs` | `geneseed link`/`unlink` — the PATH shim, and the only Windows USER-Path registry edit |
 
@@ -125,6 +127,26 @@ float `1.0` into one double, and that value gets written into a user's file. Do
 library for `udiff.mjs`: it is not Myers, ties resolve to the earliest match. Every function in
 `paths.mjs` branches on `process.platform`, so green on one OS proves nothing about the other.
 
+## `js/loop/` — the loop engine
+
+`geneseed loop` — a state machine over a brick graph, persisted as a JSON block in `LOOP.md` at
+the git root. The model only ever runs the node it is handed and reports an outcome; every
+transition, score and stop is computed here.
+
+| module | owns |
+|---|---|
+| `graph.mjs` | `checkGraph` — the rules a loop graph must satisfy before a node runs: nodes name real bricks, edges cover every outcome, `$close` is reachable, every cycle is inside a declared loop |
+| `score.mjs` | The risk arithmetic: `WEIGHTS`, `PRESETS`, `declaredRisk`/`actualRisk`/`decide`, `parseNumstat`. Pure — no import but node builtins |
+| `catalog.mjs` | `loadCatalog` — bricks and loop templates from shipped/global/project origins, later overrides earlier BY NAME |
+| `state.mjs` | The engine itself: `initState`, `nextStep`, `scoreDeclared`/`scoreDiff`, `recordOutcome`, `decideAwaiting`, `renderLoopFile`/`parseLoopFile` |
+| `cli.mjs` | `geneseed loop check\|init\|next\|score\|record\|decide` — the only face either a model or a human reaches this engine through |
+
+**Before editing:** `score.mjs` is imported by the build driver (the `--trust` choices), so it must
+stay free of every import but node builtins and `graph.mjs`. `state.mjs` excludes `LOOP.md` itself
+from every score and every read-brick porcelain check — it is the engine's own bookkeeping, never
+part of the work being scored. `cli.mjs` may not spawn: git output is piped in on stdin by the
+model, never read by this entry.
+
 ## `js/maintain/` — lifecycle
 
 Verbs that change an install that already exists, as opposed to rendering one.