geneseed 3.11.0 → 3.13.0

package/CHANGELOG.md

@@ -8,6 +8,166 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
 
 ## [Unreleased]
 
+## [3.13.0] — 2026-10-04
+
+**Upgrading:** re-emit (`geneseed rebuild-all`) so the installed `loop` skill knows the new
+templates, human gates and note files; then `geneseed web restart` (and a hard reload) for the
+new Loops and Docs pages.
+
+### Added
+- **Template `category`** — `architecture`, `tests`, `development`, `refactoring` or `day-to-day`;
+  every shipped template carries one, and the console's Loops page groups templates by it.
+- **Five loop templates** — `tdd` (plan, then write each failing test before the code that passes
+  it), `legacy-tests` (pin undocumented behaviour with characterization tests, mutation-checked,
+  production code untouched), `legacy-refactor` (pin current behaviour once, then refactor behind
+  that net), `deps-upgrade` (upgrade one package or group per iteration, breaking changes read
+  before the bump, lockfiles excluded from the deletion count so their churn doesn't force a
+  blocking score), and `ci-repair` (triage the current commit's failing CI checks and fix one
+  code failure per iteration).
+- **Five bricks** backing the templates above — `red-test`, `characterize`, `mutation-check`
+  (reports `unavailable` rather than a silent `pass` when no mutation tool is on the stack),
+  `upgrade-scout`, `ci-triage` (reports `done` rather than green when CI has no run for HEAD).
+- **`geneseed loop record --note` / `--note-file`** — carries a `read` brick's finding (a plan, a
+  review finding, a mutation gap, a CI classification) into `LOOP.md`'s notes so it survives into
+  the next brick and the next iteration; `--note-file` for anything multi-line or that mentions
+  `git commit`/`push`, which a shell argument can't carry safely.
+- **Console: Loops › Active tab** — every loop `geneseed loop init` has launched, discovered via a
+  new **loop registry** (`$XDG_CONFIG_HOME/geneseed/loops.json`, identity only — `LOOP.md` stays
+  the source of state) instead of a worktree scan. `GET /api/loops/active` reports each loop's
+  branch, status, iteration, current node and preset; a card per loop, an `awaiting` loop
+  highlighted with what it's waiting on (answered in the agent's session, never the page),
+  finished loops kept muted for 7 days. Selecting a card draws its ring with the current node and
+  its iteration history. A per-loop preset picker (`POST /api/loops/preset`) rewrites `LOOP.md`'s
+  `preset`, applying from the next score on — the tab's only write; no `decide` and no relaunch
+  from the page. Only loops launched on this version or later are registered.
+
+- **Seven more loop templates** — `architecture-decision` (one ADR per decision, challenged by a
+  skeptic brick, reviewed by the user), `enforce-architecture-rule` (encode a rule as a test with
+  an allowlist of today's violations, fix one violation per iteration), `update-contract` (expand,
+  migrate one consumer per iteration, contract, with contract files gated for a human by default),
+  `spec-first-feature` (write the spec first, build one task per iteration, closed by an
+  independent `done-check`), `api-endpoint` (plan, apply, test, a Bruno request and a security
+  review per endpoint), `remove-dead-code` (confirm green, delete one coherent unused group per
+  iteration, deletions scored soft) and `fix-flaky-tests` (confirm by repeated runs, fix the root
+  cause per iteration, never a retry or a sleep).
+- **Nine bricks** backing the templates above — `adr-draft`, `adr-challenge`, `fitness-define`,
+  `migration-plan`, `spec`, `done-check`, `compat-check`, `flake-repro`, `flake-check`.
+- **Human gates** — a brick's frontmatter can carry `gate: human` (optionally `gateOn:
+  <outcomes>`), holding its transition for a person regardless of preset or score. `geneseed loop
+  decide --verdict ok|no|amend` answers it: `ok` follows the reported outcome (a held failure
+  still stops), `no` stops the loop, `amend` re-runs the brick with a note and restarts its ring
+  budget, capped at 3 amends per brick per iteration. A passed gate is named under the closing
+  commit's new `Loop-Gates` trailer. In the console, a gated brick carries a person badge on the
+  loop ring ("Human gate", or "Human gate on pass") and a "human gate" tag in its rows, and the
+  Active section shows a gated loop as `Awaiting gate at <node>`.
+- **Template `contracts` and `ignoreDeletions` globs** — `contracts` names interface/schema files
+  that always escalate a touching iteration to at least the `api` risk weight; copied from the
+  template at `loop init`, extendable with `--contracts` or by hand in `LOOP.md`.
+  `ignoreDeletions` excludes matched files from the >20-deleted-lines escalation only — the write
+  set still applies to them.
+- **`rules` on every node** — a template may carry `rules`, a list of one-line instructions
+  (`loop check` refuses anything else); `geneseed loop next` hands them to every brick it runs,
+  not only the iteration head, so a template-wide proviso is visible everywhere, including to
+  `review`. `description` stays the catalogue blurb and is never sent as rules. The shipped
+  templates' instructions moved out of their descriptions into `rules`.
+- **A guide to running a loop** — `docs/guides/run-a-loop.md`, `loop-running.md` and
+  `loop-finish.md`: what you need, how to ask, which template for which job, the trust preset,
+  answering a blocking score or a human gate, watching, stopping, merging, driving the engine by
+  hand, and a symptom table.
+- **Console: rendered brick view** — the Loops page's Bricks reader renders a brick's body as
+  markdown under its facts (effect, outcomes, gate), with the raw source one click away.
+
+### Changed
+- **Categories nest under the selected rail entry** — on the Library (skill types), Docs
+  (sections) and Loops (template categories, brick origins, run statuses) pages, a selected
+  entry's categories open in the rail beneath it, with counts and a share bar, replacing the
+  full-width banner above the page.
+- **The Docs selector names all four hosts** — OpenCode, Claude Code, OpenClaude and IBM Bob. A
+  page or inline block tagged with a family still shows to every host in it; a page can now name
+  several hosts (`harness: ["claude", "openclaude"]`), so Bob no longer sees the Claude Code /
+  OpenClaude machine page.
+- **Docs in the Library layout** — the console's Docs tab is a rail of parts (Understand, Guides,
+  Concepts, Reference), a filterable list grouped by section, and a reader with a breadcrumb,
+  the page's outline and Previous / Next within its section. Pages carry a new `section` and
+  `description` in their frontmatter.
+- **Long doc pages split into short ones**, each a section of its part: the install guide (one
+  page per host, from a clone, without the wizard), what lands on your machine (one page per
+  host, taking it back out), troubleshooting (installing, hooks, updating, doctor, web console),
+  the OpenCode plugins (one page per plugin), loops (templates, bricks, notes and rules, risk,
+  human gates, contracts, the loop branch) and the run-a-loop guide. The `geneseed loop` actions
+  table moved to Reference. Then the rest of the long ones: choose your setup (voice and working
+  style · doctrine packs and single rules · footprint, loop trust and changing later), MCP servers
+  (a hub, one page per preset, reading non-markdown docs; the won't-connect checklist moved to
+  Troubleshooting), hooks (the hooks · gates, settings and the shim), environment variables (the
+  context and memory ones on their own page; plugin switches live on each plugin's page), the
+  host capability matrix, and which loop template. Every first page keeps its old address.
+- **The Understand track has more pages** — what lands on your machine is now one page per host
+  plus taking it back out, so a returning reader's "New here?" progress shows the new steps
+  as unread.
+- **Console Loops page in the Library layout** — a rail (Templates · Bricks · Active, with
+  counts) replaces the tabs; each section is a filterable list grouped like the Library's
+  (templates by `category`, bricks by origin, active loops by status, awaiting first) beside a
+  detail pane: the ring, the template's `rules`, and its bricks as compact rows that a click on a
+  ring node highlights. Inner-ring nodes no longer overlap (`api-endpoint`).
+- **`feature`** now closes through an independent `done-check` — it maps every requirement to a
+  passing test before `$close` instead of trusting the iterations that already ran.
+- **`deps-upgrade`** marks lockfiles with `ignoreDeletions` instead of a lowered `delete` weight,
+  so lockfile churn stays out of the deletion count without lowering the weight for any other
+  deletion in the same iteration.
+- **Write-set entries accept globs** when they have at least one literal path segment (a tool's
+  generated store, say); a wildcard-only entry (`**`, `**/*.java`) still matches nothing rather
+  than declaring the whole repo writable.
+
+### Fixed
+- **Skill and agent descriptions follow the skill-authoring rules** — no trigger sentence is cut
+  mid-way in any theme, and no description carries XML-like tags (#179).
+- **The install page no longer scrolls on open** — the reader's own host is lit (its link on the
+  Install page, its scope's heading on the OpenCode page) without moving the page.
+- The bricks README link on the loops page pointed at a repository that does not exist; the
+  console's wiki button opened a docs page that does not exist.
+- A read-setup brick's plan or review findings no longer vanish between steps — `record --note`
+  / `--note-file` writes them into `LOOP.md`'s notes instead of leaving them in the brick's own,
+  discarded context.
+
+## [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,11 +37,11 @@ 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.
 
-This page is the overview. **New to agent harnesses?** Start with [Understand](docs/understand/harness.md) — four short pages on what a harness is, what lands on your machine, what changes in your day, and what is enforced versus only asked. Everything else — every install path, configuration knob, and troubleshooting step — is in the **[documentation](docs/README.md)**, which the web console also renders.
+This page is the overview. **New to agent harnesses?** Start with [Understand](docs/understand/harness.md) — a short course on what a harness is, what lands on your machine, what changes in your day, and what is enforced versus only asked. Everything else — every install path, configuration knob, and troubleshooting step — is in the **[documentation](docs/README.md)**, which the web console also renders.
 
 ---
 
@@ -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 |
@@ -199,7 +199,7 @@ Pick with `--theme NAME` or via the setup wizard; upgrades remember it. More in
 
 ### 🪶 Footprint (lean vs full)
 
-A second per-install dial sets how much of the constitution the root file carries *inline* every turn — a token-cost knob, not a change to which Rules apply. **lean** (the default) carries each rule's hand-written short form and points to the full text on disk; **full** inlines every rule with its rationale. Every rule is in force either way. More in [Footprint](docs/concepts/footprint.md) and [Choose your setup](docs/guides/choose-your-setup.md).
+A second per-install dial sets how much of the constitution the root file carries *inline* every turn — a token-cost knob, not a change to which Rules apply. **lean** (the default) carries each rule's hand-written short form and points to the full text on disk; **full** inlines every rule with its rationale. Every rule is in force either way. More in [Footprint](docs/concepts/footprint.md) and [Footprint, loop trust and changing later](docs/guides/setup-footprint.md).
 
 ---
 

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.13.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/bob/README.md

@@ -1,6 +1,6 @@
 # 🤖 IBM Bob adapter
 
-> [← Back to README](../../README.md) · [Install guide](../../docs/guides/install.md) · [Claude Code adapter](../claude-code/README.md) · [OpenCode adapter](../opencode/README.md)
+> [← Back to README](../../README.md) · [Install guide](../../docs/guides/install-bob.md) · [Claude Code adapter](../claude-code/README.md) · [OpenCode adapter](../opencode/README.md)
 
 [IBM Bob](https://bob.ibm.com) is **Claude-Code-shaped**: a project `.bob/`
 layer, an `AGENTS.md` instructions file, `SKILL.md` skills, subagents, and a

package/adapters/claude-code/README.md

@@ -1,6 +1,6 @@
 # 🪝 Claude Code adapter
 
-> [← Back to README](../../README.md) · [Install guide](../../docs/guides/install.md) · [OpenCode adapter](../opencode/README.md)
+> [← Back to README](../../README.md) · [Install guide](../../docs/guides/install-claude-code.md) · [OpenCode adapter](../opencode/README.md)
 
 Optional. Claude Code supports lifecycle **hooks**, so a team using it can make
 parts of the harness fire automatically instead of relying on agent

package/adapters/openclaude/README.md

@@ -1,6 +1,6 @@
 # 🦀 OpenClaude adapter
 
-> [← Back to README](../../README.md) · [Install guide](../../docs/guides/install.md) · [Claude Code adapter](../claude-code/README.md) · [OpenCode adapter](../opencode/README.md)
+> [← Back to README](../../README.md) · [Install guide](../../docs/guides/install-openclaude.md) · [Claude Code adapter](../claude-code/README.md) · [OpenCode adapter](../opencode/README.md)
 
 [OpenClaude](https://openclaude.gitlawb.com/) (`@gitlawb/openclaude`, binary
 `openclaude`) is an open-source coding-agent CLI that "originated from the Claude

package/adapters/opencode/README.md

@@ -1,6 +1,6 @@
 # 🔌 OpenCode adapter
 
-> [← Back to README](../../README.md) · [Install guide](../../docs/guides/install.md) · [How OpenCode loads](HOW-OPENCODE-LOADS.md) · [Global harness spec](GLOBAL-HARNESS-SPEC.md)
+> [← Back to README](../../README.md) · [Install guide](../../docs/guides/install-opencode.md) · [How OpenCode loads](HOW-OPENCODE-LOADS.md) · [Global harness spec](GLOBAL-HARNESS-SPEC.md)
 
 [OpenCode](https://opencode.ai) is `AGENTS.md`-native and has first-class
 **subagents** and **commands**, so Geneseed fits it cleanly. Pick the depth you
@@ -468,9 +468,9 @@ OpenCode runs, so the command has to resolve — the `uvx` form above needs only
 call). No uv? `pipx install markitdown-mcp` and swap the command to `["markitdown-mcp"]`.
 Or drop the block entirely — the skill falls back to a CLI converter (MarkItDown /
 Pandoc / Docling) and never installs one silently. Listed but not connecting? The
-command isn't on PATH — see [the MCP guide](../../docs/guides/mcp.md).
+command isn't on PATH — see [Model, agent and MCP problems](../../docs/reference/troubleshoot-tools.md).
 Full runbook, including the corporate-TLS (`UV_SYSTEM_CERTS`) step and the OCR extras:
-[the MCP guide](../../docs/guides/mcp.md).
+[the MarkItDown guide](../../docs/guides/mcp-markitdown.md).
 
 ## Optional add-on — git-worktree isolation (third-party, not vendored)
 

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/README.md

@@ -2,40 +2,59 @@
 
 [← Back to README](../README.md)
 
-**New to agent harnesses?** Read **Understand** first — four short pages, about ten minutes, and every other page assumes them. The same pages open the **Docs** tab of the web console (`geneseed web`), which adds an interactive map of your own install and filters host-specific passages to the tool you use.
+**New to agent harnesses?** Read **Understand** first — a short track, about ten minutes, that every other page assumes. The same pages open the **Docs** tab of the web console (`geneseed web`), which groups each part into sections, adds an interactive map of your own install, and filters host-specific passages to the tool you use.
 
 ## 1 · Understand
 
-1. **[What a harness is](understand/harness.md)** — git hooks + CI + a runbook, but for your AI agent.
-2. **[What lands on your machine](understand/on-your-machine.md)** — every file and hook an install writes, what it does for you, what it costs, how to turn it off.
-3. **[A day with the harness](understand/a-day.md)** — the moments you will actually meet: a push that asks first, a skill, a delegation, a memory.
-4. **[Enforced vs. asked](understand/enforced-vs-asked.md)** — what is guaranteed by code, and what the model is only asked to do.
+**Start here** — [What a harness is](understand/harness.md): git hooks + CI + a runbook, but for your AI agent.
+
+**On your machine** — [What lands on your machine](understand/on-your-machine.md) · [On OpenCode](understand/machine-opencode.md) · [On Claude Code and OpenClaude](understand/machine-claude.md) · [On Bob, or any AGENT.md tool](understand/machine-bob.md) · [Taking it back out](understand/take-it-out.md): every file and hook an install writes, what it does for you, what it costs, how to turn it off.
+
+**Day to day** — [A day with the harness](understand/a-day.md): the moments you will actually meet · [Enforced vs. asked](understand/enforced-vs-asked.md): what is guaranteed by code, and what the model is only asked to do.
 
 ## 2 · Guides
 
-| Guide | When |
-| --- | --- |
-| [Install](guides/install.md) | First time — npx, a clone, or a specific host |
-| [Choose your setup](guides/choose-your-setup.md) | Theme, doctrine packs, one rule at a time, footprint, posture, mode |
-| [Verify it works](guides/verify.md) | Right after installing, or when something feels off |
-| [Upgrade](guides/upgrade.md) | Getting a new version onto every install |
-| [Uninstall](guides/uninstall.md) | Removing an install — and what stays behind |
-| [Project context](guides/project-context.md) | Choosing which of a repo's docs the agent loads |
-| [Connect your wiki](guides/wiki.md) | Giving the agent your own notes, machine-wide |
-| [MCP servers](guides/mcp.md) | MarkItDown, GitLab, Filesystem — and reading non-markdown docs |
-| [Run geneseed from anywhere](guides/run-anywhere.md) | Putting the CLI on your PATH from a clone |
-| [Start the web console at login](guides/autostart.md) | Keeping the console running |
-| [Run in CI / headless](guides/headless.md) | OpenCode without a terminal |
-| [Add git-worktree isolation](guides/worktree.md) | OpenCode, optional third-party add-on |
-| [Migrate from a clone to npm](guides/migrate.md) | Moving an old clone install to the npm package |
+| Section | Guide | When |
+| --- | --- | --- |
+| Install | [Install](guides/install.md) | First time — one command, and the page for each host |
+| Install | [From a clone](guides/install-clone.md) | npm is out of reach, or you want to change the harness |
+| Install | [OpenCode](guides/install-opencode.md) · [Claude Code](guides/install-claude-code.md) · [OpenClaude](guides/install-openclaude.md) · [IBM Bob](guides/install-bob.md) · [Any AGENT.md tool](guides/install-agent-md.md) | Installing for one host, global or per repo |
+| Install | [Without the wizard](guides/install-scripted.md) | A script, a CI job, a shell with no terminal |
+| Install | [Run geneseed from anywhere](guides/run-anywhere.md) | Putting the CLI on your PATH from a clone |
+| Set up | [Choose your setup](guides/choose-your-setup.md) · [Doctrine packs and single rules](guides/setup-doctrines.md) · [Footprint, loop trust and changing later](guides/setup-footprint.md) | Theme, posture, mode; doctrine packs and single rules; footprint, loop trust, changing a choice |
+| Set up | [Verify it works](guides/verify.md) | Right after installing, or when something feels off |
+| Set up | [Project context](guides/project-context.md) | Choosing which of a repo's docs the agent loads |
+| Set up | [Connect your wiki](guides/wiki.md) | Giving the agent your own notes, machine-wide |
+| Set up | [MCP servers](guides/mcp.md) · [MarkItDown](guides/mcp-markitdown.md) · [GitLab](guides/mcp-gitlab.md) · [Filesystem](guides/mcp-filesystem.md) · [Reading non-markdown docs](guides/read-non-markdown.md) | Where the config lives, the three presets, and reading PDF and Office files |
+| Loops | [Run a loop](guides/run-a-loop.md) · [Which loop template](guides/loop-which-template.md) · [While a loop runs](guides/loop-running.md) · [Finish a loop](guides/loop-finish.md) | Working a requirement as small, validated, committed iterations |
+| Keep it running | [Upgrade](guides/upgrade.md) | Getting a new version onto every install |
+| Keep it running | [Migrate from a clone to npm](guides/migrate.md) | Moving an old clone install to the npm package |
+| Keep it running | [Start the web console at login](guides/autostart.md) | Keeping the console running |
+| Keep it running | [Uninstall](guides/uninstall.md) | Removing an install — and what stays behind |
+| OpenCode extras | [Run in CI / headless](guides/headless.md) | OpenCode without a terminal |
+| OpenCode extras | [Add git-worktree isolation](guides/worktree.md) | OpenCode, optional third-party add-on |
 
 ## 3 · Concepts
 
-[Hosts](concepts/hosts.md) · [Rules](concepts/rules.md) · [Agents](concepts/agents.md) · [Skills](concepts/skills.md) · [Hooks](concepts/hooks.md) · [Memory](concepts/memory.md) · [Notebook](concepts/notebook.md) · [Footprint](concepts/footprint.md) · [Collaboration](concepts/collaboration.md) · [Foreman mode](concepts/foreman-mode.md) · [Exclusions](concepts/exclusions.md) · [Themes](concepts/themes.md) · [Code intelligence (LSP)](concepts/lsp.md)
+**Harness** — [Hosts](concepts/hosts.md) · [What each host automates](concepts/host-matrix.md) · [Rules](concepts/rules.md) · [Agents](concepts/agents.md) · [Skills](concepts/skills.md) · [Hooks](concepts/hooks.md) · [Hook gates, settings and the shim](concepts/hook-gates.md)
+
+**Memory** — [Memory](concepts/memory.md) · [Notebook](concepts/notebook.md)
+
+**Configuration** — [Footprint](concepts/footprint.md) · [Themes](concepts/themes.md) · [Exclusions](concepts/exclusions.md) · [Code intelligence (LSP)](concepts/lsp.md)
+
+**Working together** — [Collaboration](concepts/collaboration.md) · [Foreman mode](concepts/foreman-mode.md)
+
+**Loops** — [Loops](concepts/loops.md) · [Templates](concepts/loop-templates.md) · [Bricks and their origins](concepts/loop-bricks.md) · [Notes and rules](concepts/loop-notes.md) · [Risk, trust and validation levels](concepts/loop-risk.md) · [Human gates](concepts/loop-gates.md) · [Contracts and ignored deletions](concepts/loop-contracts.md) · [LOOP.md, trailers and the loop branch](concepts/loop-branch.md)
 
 ## 4 · Reference
 
-[CLI](reference/cli.md) · [Environment variables](reference/environment.md) · [Glossary](reference/glossary.md) · [Troubleshooting](reference/troubleshooting.md) (by symptom) · [OpenCode plugins](reference/opencode-plugins.md) · [About](reference/about.md)
+**CLI & environment** — [CLI](reference/cli.md) · [Loop actions](reference/loop-actions.md) · [Environment variables](reference/environment.md) · [Context and memory variables](reference/env-context.md)
+
+**Troubleshooting** (by symptom) — [Overview](reference/troubleshooting.md) · [Install](reference/troubleshoot-install.md) · [Hooks, context and memory](reference/troubleshoot-hooks.md) · [Model, agents and MCP](reference/troubleshoot-tools.md) · [Updating](reference/troubleshoot-update.md) · [Doctor findings](reference/troubleshoot-doctor.md) · [Web console](reference/troubleshoot-web.md)
+
+**OpenCode plugins** — [Overview](reference/opencode-plugins.md) · [context](reference/plugin-context.md) · [guard](reference/plugin-guard.md) · [learn](reference/plugin-learn.md) · [workflow](reference/plugin-workflow.md) · [notify](reference/plugin-notify.md) · [ponytail](reference/plugin-ponytail.md) · [activity](reference/plugin-activity.md)
+
+**Glossary & about** — [Glossary](reference/glossary.md) · [About](reference/about.md)
 
 ## For contributors
 

package/docs/concepts/agents.md

@@ -1,8 +1,10 @@
 ---
 group: concepts
-order: 3
+order: 4
 title: "Agents"
 kind: "concept"
+section: "Harness"
+description: "The specialists the main session can hand work to."
 link: {"hash": "#/section/agents", "label": "Browse the catalog →"}
 ---
 An **agent** is a specialist the main session can hand a piece of work to. Each one is a markdown file with its own instructions, installed where your host looks for subagents (`agents/` in the install). It runs in its own context and returns a result, so its reading and searching does not fill your conversation.

package/docs/concepts/collaboration.md

@@ -1,8 +1,10 @@
 ---
 group: concepts
-order: 9
+order: 14
 title: "Collaboration"
 kind: "concept"
+section: "Working together"
+description: "Register, contract, how firmly a memory binds, and who you are."
 ---
 Beside the [rules](rules.md), a few pieces shape *how* the agent works with you: the register it speaks in, the contract between you, how firmly a memory binds, and who you are. All of them are plain text in the install, so they reach every host unchanged.
 

package/docs/concepts/exclusions.md

@@ -1,8 +1,10 @@
 ---
 group: concepts
-order: 11
+order: 12
 title: "Exclusions"
 kind: "concept"
+section: "Configuration"
+description: "Two ways to switch things off: one rule, or every hook in a folder."
 link: {"hash": "#/harness", "label": "Manage in Harness →"}
 ---
 Geneseed has two different ways to switch something off, and they work at different scales:
@@ -52,4 +54,4 @@ The finer switch removes a single doctrine rule from an install while keeping th
 geneseed build --emit claude-global --exclude-rules "process 7"
 ```
 
-The install records it (`Excluded rules: process 7` beside its pack list) and every rebuild and upgrade keeps it. The always-on Rules and the Ethos cannot be excluded. Picking packs and rules is covered in [Choose your setup](../guides/choose-your-setup.md); what the layers are is in [Rules](rules.md).
+The install records it (`Excluded rules: process 7` beside its pack list) and every rebuild and upgrade keeps it. The always-on Rules and the Ethos cannot be excluded. Picking packs and rules is covered in [Doctrine packs and single rules](../guides/setup-doctrines.md); what the layers are is in [Rules](rules.md).