geneseed 3.16.0 → 3.17.0

package/CHANGELOG.md

@@ -8,6 +8,29 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
 
 ## [Unreleased]
 
+## [3.17.0] — 2026-10-08
+
+### Added
+
+- Docs in AsciiDoc. `document-project`, the docs agent and the `docs-update` brick detect a project's docs format: a `.md`-only tree stays Markdown, an `.adoc`-only tree stays AsciiDoc, a mix asks you, and a project with no docs defaults to AsciiDoc. The choice is recorded as `Docs format:` in `AGENTS.md`. AsciiDoc mode uses header attributes, `.adoc` names and `[source,mermaid]` diagrams that GitHub renders, and it finishes with an `asciidoctor --failure-level=WARN` lint (or an explicit SKIPPED). With no docs yet, `document-project` interviews you first. Agent-runtime files stay Markdown.
+- C4 architecture diagrams in `document-project`. The audience you name sets the levels: L1 and L2 always, L3 only for containers you call complex, never L4. Diagrams are Mermaid `flowchart`s styled as C4 (typed nodes, `intent · protocol` edges, a title and a legend), redrawn only inside their own section. The `AGENTS.md` it writes sends a cross-container change to the L2 diagram first.
+- The context hook and the OpenCode plugin pick up `.adoc` files wherever they pick up `.md`; `README.adoc` and `CONTRIBUTING.adoc` load eagerly.
+- Protected checks. List the checks and tests your agent is judged by in `.geneseed/protected-checks.txt` at the repo root, one path per line, and a write to any of them asks you first on Claude Code, is blocked on Bob and refused on OpenCode, citing *External Gate*. A check the agent can edit is not a check. Nothing changes until a project adds the file. Shell edits are not seen, so keep running the checks in CI.
+
+### Changed
+
+- Loops repair once, then stop for you. The test repair rings of every shipped template (`apply-test`, `fix-test`, `write-run`, `stabilise`) are now `max: 1`: one repair, then the attempt is discarded for one fresh try, then the loop stops. A second revision makes code worse, not better — 0.82 correct after one revision, 0.673 after two ([arXiv 2607.24604](https://arxiv.org/abs/2607.24604)). A ring's `max` now binds its own repair edge even when a wider ring shares its nodes; before, `review-fix` (max 3) quietly let `apply-test` retry four times.
+- The `test` brick runs checks in order — build gate, then every focused check (none hides another), then the full suite only when all passed — and lists each one as `PASS`, `FAIL`, `ERROR` or `SKIPPED (reason)`. Each failure is four lines: purpose, property, a one-line diagnostic, the rerun command.
+- `error` is a reserved loop outcome: a check that crashed or was never wired stops the loop for a human instead of feeding a repair. A brick may declare it without an edge.
+- Each `test` report replaces the earlier `test` notes, so a repair never reads findings about code that has since changed.
+- Doctrine *Bound the Loop* says the same outside the loop engine: one repair, then a fresh attempt or a hand-back; only a verdict on the final artifact counts.
+
+## [3.16.1] — 2026-10-07
+
+### Fixed
+
+- `geneseed upgrade` from a checkout older than the August rename of `bin/geneseed.mjs` to `bin/build-driver.mjs` no longer fails with `Cannot find module '…/bin/geneseed.mjs'` and `[E-BUILD]` after a successful pull and doctor gate. The old updater (and an old web daemon's build jobs) spawn the old path from the code they started with; `bin/geneseed.mjs` is back as a forwarder to the driver. If you already hit it, run `geneseed upgrade` again — it is up to date now and rebuilds with the new code.
+
 ## [3.16.0] — 2026-10-05
 
 **Upgrading:** re-emit (`geneseed rebuild-all`) so the context hook stays under Claude Code's output cap. To drop skills you never use, rebuild an install with `--exclude-skills <name,…>` (see [Exclusions](docs/concepts/exclusions.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.16.0**.
+> string. Current label: **3.17.0**.
 
 ## Capabilities
 

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

@@ -156,8 +156,12 @@ function log(msg) { if (DEBUG) console.error(`[geneseed-context] ${msg}`) }
 // (OpenCode's own native roots) are deliberately absent: OpenCode already has them, and
 // injecting them again re-sent the whole harness on every request until 2026-09.
 const EAGER_ROOT = new Set([
-  ".cursorrules", "README.md", "CONTRIBUTING.md", "user-rules.md", "PROFILE.md",
+  ".cursorrules", "README.md", "README.adoc", "CONTRIBUTING.md", "CONTRIBUTING.adoc",
+  "user-rules.md", "PROFILE.md",
 ])
+// Project docs are Markdown or AsciiDoc (document-project writes AsciiDoc when a project has
+// none yet). Same set as js/hosts/hooks-context.mjs DOC_EXT.
+const isDoc = (name) => /\.(md|adoc)$/i.test(name)
 // Doc trees walked recursively; everything found is lazy (listed, not injected).
 const LAZY_DIRS = ["docs", "doc", "documentation", "architecture", "adr", "ADR"]
 // Never descend into these.
@@ -277,11 +281,13 @@ function globToRegExp(glob) {
   return new RegExp("^" + re + "$")
 }
 
-// First H1 / heading line of a markdown file, for the lazy listing.
+// First heading line of a markdown or AsciiDoc file, for the lazy listing. An AsciiDoc
+// title is "= Title"; the space is required so a setext "====" underline never matches.
 function firstHeading(text) {
   for (const line of text.split("\n")) {
     const s = line.trim()
     if (s.startsWith("#")) return s.replace(/^#+\s*/, "").trim()
+    if (/^=+\s/.test(s)) return s.replace(/^=+\s*/, "").trim()
   }
   return ""
 }
@@ -425,7 +431,7 @@ async function walkMd(dir, root, depth, acc) {
     if (e.isDirectory()) {
       if (EXCLUDE_DIRS.has(e.name)) continue
       await walkMd(full, root, depth + 1, acc)
-    } else if (e.isFile() && e.name.toLowerCase().endsWith(".md")) {
+    } else if (e.isFile() && isDoc(e.name)) {
       acc.push(full)
     }
   }
@@ -448,7 +454,7 @@ async function discover(root) {
     if (!e.isFile()) continue
     const abs = path.join(root, e.name)
     if (EAGER_ROOT.has(e.name)) add(eager, abs)
-    else if (e.name.toLowerCase().endsWith(".md")) add(lazy, abs)   // misc root .md
+    else if (isDoc(e.name)) add(lazy, abs)   // misc root .md / .adoc
   }
 
   // 2. Doc trees (recursive) -> lazy.
@@ -469,8 +475,10 @@ async function discover(root) {
     try { pkgs = await fs.readdir(base, { withFileTypes: true }) } catch { continue }
     for (const p of pkgs) {
       if (!p.isDirectory() || EXCLUDE_DIRS.has(p.name)) continue
-      const readme = path.join(base, p.name, "README.md")
-      if (await isFile(readme) && !eager.has(readme)) add(lazy, readme)
+      for (const name of ["README.md", "README.adoc"]) {
+        const readme = path.join(base, p.name, name)
+        if (await isFile(readme) && !eager.has(readme)) add(lazy, readme)
+      }
     }
   }
 

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

@@ -288,6 +288,32 @@ function ruleStoreTarget(p) {
   return nocase(abs).startsWith(nocase(mem) + "/") ? "memory" : null
 }
 
+// ---- protected checks (External Gate) ------------------------------------------
+// Twin of js/hosts/hooks.mjs's `protectedCheck` — keep in step. A project lists the checks its agent
+// must not edit in `.geneseed/protected-checks.txt` at its git root, one repo-relative path per
+// line; the list protects itself. Found from the WRITE TARGET up to the first `.git`, re-read on
+// every write (a short file, read only on a write call). No ask tier here, so a hit is a deny.
+const SENSOR_LIST = ".geneseed/protected-checks.txt"
+function protectedCheck(p) {
+  try {
+    const target = path.resolve(p)
+    let root = path.dirname(target)
+    while (!existsSync(path.join(root, ".git"))) {
+      const up = path.dirname(root)
+      if (up === root) return null
+      root = up
+    }
+    const text = readFileSync(path.join(root, SENSOR_LIST), "utf8")
+    const fold = (s) => nocase(s.replace(/\\/g, "/"))
+    const rel = fold(path.relative(root, target))
+    const entries = [SENSOR_LIST, ...text.split(/\r?\n/).map((l) => l.trim().replace(/[\\/]+$/, ""))
+      .filter((l) => l && !l.startsWith("#"))]
+    return entries.find((e) => rel === fold(e) || rel.startsWith(fold(e) + "/")) ?? null
+  } catch {
+    return null // no list (the common case) or an unreadable one: nothing is protected
+  }
+}
+
 // Mutation-class tools for the wiki check — wider than WRITE_TOOLS because moving,
 // renaming, or deleting a protected note is as destructive as overwriting it. Same
 // substring stance: over-matching the class is harmless (see WRITE_TOOLS note).
@@ -437,6 +463,8 @@ export const GeneseedGuard = async (ctx) => {
           const p = pickPath(args)
           if (p && SECRET_RE.some((re) => re.test(p))) { await deny(`write to secret/key file ${p} (Sealed Secrets)`, "law-1"); return }
           if (p && SECRET_WARN_RE.some((re) => re.test(p))) log(`WARN: writing ${p} — keep secrets out of tracked files (Sealed Secrets)`)
+          const sensor = p && protectedCheck(p)
+          if (sensor) { await deny(`${p} is a protected check (${sensor}, listed in ${SENSOR_LIST}) — a check the agent can edit is not a check (External Gate)`, "rigor-5"); return }
           const store = p && ruleStoreTarget(p)
           if (store && !RULE_STORE_BUMPED.has(p)) {
             RULE_STORE_BUMPED.add(p)

package/bin/geneseed.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * The generator's PRE-RENAME path, kept as a forwarder to `bin/build-driver.mjs`.
+ *
+ * WHY A RENAMED FILE STILL HAS TO EXIST. `geneseed upgrade` runs the updater it started with:
+ * its module graph is loaded before the `git pull`, so an updater older than the rename
+ * (5c970dc9, 2026-08) pulls the new tree and then spawns `bin/geneseed.mjs` to rebuild —
+ * a file the tree it just pulled no longer has. The doctor gate passes (it spawns
+ * `geneseed-cli.mjs`, which never moved), and the rebuild dies with MODULE_NOT_FOUND and
+ * `[E-BUILD]`. An old web daemon's build jobs spawn the same path. Nothing in this tree
+ * calls it, and it has no npm name on purpose: it is a landing pad for old processes, not a
+ * fourth entry point.
+ *
+ * Importing the driver entry runs it on this process's argv, which is the argv the old
+ * caller passed — so the forwarding is the import and nothing else.
+ */
+import './build-driver.mjs';

package/docs/concepts/hooks.md

@@ -36,6 +36,7 @@ Geneseed writes its hooks into the host's settings file. Every hook calls one pr
 **rule-gate.** Runs before every file write.
 - Content that looks like a credential (a cloud access key, a GitHub or Anthropic token, a Slack token, a private-key block) going into any file other than `.env*` gets a prompt citing *Sealed Secrets*.
 - A write to `user-rules.md`, `MEMORY.md` or a file in the install's `memory/` gets a prompt citing *Persist Insight*: whether something is a standing rule or a fact to remember is your call, settled through the `rule` [skill](skills.md).
+- A write to a check the project protects gets a prompt citing *External Gate* (on Bob, it is blocked). A project opts in with `.geneseed/protected-checks.txt` at its git root: one repo-relative file or folder per line, `#` for comments — the checks and tests the agent is judged by. A check the agent can edit is not a check. The list protects itself. Only file-write tools are seen: a shell `sed -i` or redirect is not, so run the same checks in CI as the boundary that holds.
 - Ordinary edits pass untouched.
 
 **learn.** Takes the tail of the transcript and asks a model to distil what is worth keeping into one-fact-per-file entries under `memory/`, skipping duplicates. It needs `GENESEED_LLM` set to a model command, for example:

package/docs/concepts/loop-notes.md

@@ -21,6 +21,9 @@ brick's behalf. This applies to `plan` and `review` as much as to the newer bric
 brick whose finding the next brick needs writes it to a file in the OS temp directory and reports
 that file's path with the outcome.
 
+One exception keeps the verdict fresh: each `test` report replaces every earlier `test` note, so a
+repair reads only the findings for the code as it stands, never a trace from an older version.
+
 ## `description` and `rules`: what a template is for, and what every brick must do
 
 A template's JSON carries two prose fields, and they are never confused:

package/docs/concepts/loops.md

@@ -47,6 +47,17 @@ all gets exactly 1 — no re-entry — which is also why **every cycle inside an
 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.
 
+**A ring's `max` is also its own repair budget.** The edge that returns to a ring's first node
+from inside it — `test` → `apply` — is charged to the smallest ring holding both ends, and that
+ring stops at its `max` even when a wider ring raises the node's shared budget. The shipped test
+rings (`apply-test`, `fix-test`, `write-run`, `stabilise`) are `max: 1`: one repair, then the
+attempt is discarded for one fresh try, then the loop stops for you. A second revision makes the
+result worse, not better — 0.82 correct after one, 0.673 after two (arXiv 2607.24604).
+
+**`error` always stops.** A brick may declare the outcome `error` without an edge for it; the
+engine sends it to `$stop`. The shipped `test` brick reports it when a check crashed or its
+evidence was never wired — no verdict is not a failure to repair.
+
 ## Limits
 
 - **No parallel nodes.** The graph runs one node at a time; there is no fan-out.

package/docs/guides/headless.md

@@ -11,7 +11,7 @@ Once the harness is installed for OpenCode (global or per repo), OpenCode can ru
 
 ```
 opencode run "review the staged diff and list any correctness bugs"   # one shot, prints to stdout
-opencode run -m anthropic/claude-sonnet-4-5 "…"                       # pin a model for this run
+opencode run -m anthropic/claude-sonnet-5 "…"                         # pin a model for this run
 cat issue.md | opencode run "triage this and propose a fix plan"      # pipe input in
 ```
 

package/docs/guides/project-context.md

@@ -21,8 +21,8 @@ The context step sorts every doc it finds into one of two lists:
 
 With no configuration, the context step finds these files:
 
-- **Eager:** root `AGENTS.md`, `AGENT.md`, `CLAUDE.md` and `.cursorrules`, plus `README.md` and `CONTRIBUTING.md`. The root file your tool already loads by itself is skipped, so you never pay for it twice.
-- **Lazy:** `docs/`, `doc/`, `documentation/`, `architecture/`, `adr/` and `ADR/`, monorepo `packages/*/README.md` and `apps/*/README.md`, and any other root `*.md`.
+- **Eager:** root `AGENTS.md`, `AGENT.md`, `CLAUDE.md` and `.cursorrules`, plus `README.md` and `CONTRIBUTING.md` (or their AsciiDoc `.adoc` twins). The root file your tool already loads by itself is skipped, so you never pay for it twice.
+- **Lazy:** `docs/`, `doc/`, `documentation/`, `architecture/`, `adr/` and `ADR/`, monorepo `packages/*/README.md` and `apps/*/README.md`, and any other root `*.md`. AsciiDoc docs (`.adoc`) are found everywhere a `.md` is.
 - **Never scanned:** `node_modules`, `.git`, `dist`, `build`, `vendor`, `.next`, `target`, `.venv`, `__pycache__`, `.opencode` and `.harness`.
 
 On Claude Code, Bob and OpenClaude the whole injection stays under 9,000 characters, because Claude Code hands the model only a short preview of a hook output past about 10,000 and keeps the rest in a file. Your session files come first, then eager files whole; an eager file that does not fit is listed instead, to be read on demand. On OpenCode eager files share a 48 KB budget. On every host, three or more docs in one folder are listed as that folder with a count (`docs/guides/ — 30 docs`), not file by file.

package/docs/guides/read-non-markdown.md

@@ -6,7 +6,7 @@ kind: "concept"
 section: "Set up"
 description: "Let the agent read PDF, Word, PowerPoint, Excel and HTML through a converter."
 ---
-The agent's doc discovery only sees markdown. The `ingest` skill teaches the agent to convert a PDF, Word, PowerPoint, Excel or HTML file, or a URL, to markdown before reading it. Install one converter and the skill uses it:
+The agent's doc discovery sees markdown (`.md`) and AsciiDoc (`.adoc`) only. The `ingest` skill teaches the agent to convert a PDF, Word, PowerPoint, Excel or HTML file, or a URL, to markdown before reading it. Install one converter and the skill uses it:
 
 - **MarkItDown**: the broadest. Use [its MCP server](mcp-markitdown.md) (preferred on a host with MCP: nothing to install per call, one cheap tool), or `pip install markitdown`.
 - **Pandoc**: excellent for Office and HTML, and a single binary.

package/docs/reference/plugin-context.md

@@ -10,8 +10,8 @@ One of the [OpenCode plugins](opencode-plugins.md). Its switches are also listed
 
 **What it does.** Puts your project's documentation (and your machine wiki) into the agent's context before your first turn, so the agent never has to be trusted to read it. It needs **no per-repo file**: it discovers docs by convention.
 
-- **Injected in full (eager):** root `README.md`, `CONTRIBUTING.md`, `.cursorrules`, `user-rules.md`, `PROFILE.md`. Budget-capped; an oversized file is listed instead, never silently truncated. (`AGENT.md`, `AGENTS.md` and `CLAUDE.md` are not injected — OpenCode already loads them.)
-- **Listed (lazy, path + first heading, read on demand):** `docs/`, `doc/`, `documentation/`, `architecture/`, `adr/`, and `packages/*/README.md` / `apps/*/README.md` in a monorepo. `node_modules`, `.git`, `dist`, `build`, `vendor` and similar are never scanned.
+- **Injected in full (eager):** root `README.md`, `CONTRIBUTING.md` (or `README.adoc`, `CONTRIBUTING.adoc`), `.cursorrules`, `user-rules.md`, `PROFILE.md`. Budget-capped; an oversized file is listed instead, never silently truncated. (`AGENT.md`, `AGENTS.md` and `CLAUDE.md` are not injected — OpenCode already loads them.)
+- **Listed (lazy, path + first heading, read on demand):** `docs/`, `doc/`, `documentation/`, `architecture/`, `adr/`, and `packages/*/README.md` / `apps/*/README.md` in a monorepo, AsciiDoc `.adoc` docs included. `node_modules`, `.git`, `dist`, `build`, `vendor` and similar are never scanned.
 - **Machine wiki:** the wikis declared in `wiki.jsonc` ride in the same block, on the same budgets. See [Wiki](../guides/wiki.md).
 - **Explicit manifest:** `$GENESEED_CONTEXT`, `.harness/context.json` or a root `context.json` takes over from discovery; `"extend": true` layers it on top instead. See [Project context](../guides/project-context.md).
 

package/docs/reference/plugin-guard.md

@@ -10,7 +10,7 @@ One of the [OpenCode plugins](opencode-plugins.md). [Environment variables](envi
 
 **What it does.** Enforces the safety rules at the tool boundary — before a tool call runs, not after. High-confidence patterns only, so legitimate work is not caught.
 
-- **Blocks** writes to private-key and credential files (*Sealed Secrets*), catastrophic shell commands such as deleting the filesystem root (*Deletion Is Deliberate*), and any change — write, move, rename, delete — under a wiki folder declared `protected` in `wiki.jsonc`.
+- **Blocks** writes to private-key and credential files (*Sealed Secrets*), catastrophic shell commands such as deleting the filesystem root (*Deletion Is Deliberate*), and any change — write, move, rename, delete — under a wiki folder declared `protected` in `wiki.jsonc`, and writes to a check listed in the project's `.geneseed/protected-checks.txt` (*External Gate* — see [Hooks](../concepts/hooks.md)).
 - **Warns** (logged, allowed) on `.env` writes and force-push.
 - **Speed-bumps** the *first* write to `user-rules.md` or a memory file: it is refused once, naming *Persist Insight* — whether something is a standing rule or a fact to remember is your call, settled through the `rule` skill. The re-issued write goes through.
 

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.16.0"
+  "version": "3.17.0"
 }

package/js/hosts/hooks-context.mjs

@@ -32,7 +32,8 @@ const _ERRNO = {
 function asOsError(e, filename) {
   const hit = _ERRNO[e && e.code];
   if (!hit) return String((e && e.message) || e);
-  // Python reprs the filename, so a Windows path comes out with its backslashes doubled.
+  // The `[Errno N] text: 'file'` shape this hook has always printed: the filename is quoted,
+  // so a Windows path comes out with its backslashes doubled.
   return `[Errno ${hit[0]}] ${hit[1]}: ${JSON.stringify(filename).replace(/^"|"$/g, "'")
     .replace(/\\"/g, '"')}`;
 }
@@ -57,7 +58,7 @@ function fnTranslate(pat) {
       if (pat[j] === '!') j += 1;
       if (pat[j] === ']') j += 1;
       while (j < pat.length && pat[j] !== ']') j += 1;
-      // An unterminated `[` is a LITERAL bracket in Python's translate, not an error.
+      // An unterminated `[` is a LITERAL bracket (fnmatch semantics), not an error.
       if (j >= pat.length) { out += '\\['; continue; }
       let body = pat.slice(i + 1, j).replaceAll('\\', '\\\\');
       if (body.startsWith('!')) body = `^${body.slice(1)}`;
@@ -77,9 +78,14 @@ function fnTranslate(pat) {
  */
 let HOST = 'claude';
 
-// Kept in step with adapters/opencode/plugins/geneseed-context.js, same as the Python.
+// Kept in step with adapters/opencode/plugins/geneseed-context.js.
 const EAGER_ROOT = ['AGENTS.md', 'AGENT.md', 'CLAUDE.md', '.cursorrules',
-  'README.md', 'CONTRIBUTING.md', 'user-rules.md', 'PROFILE.md'];
+  'README.md', 'README.adoc', 'CONTRIBUTING.md', 'CONTRIBUTING.adoc', 'user-rules.md', 'PROFILE.md'];
+// Project docs are Markdown or AsciiDoc: the document-project skill writes AsciiDoc by default
+// when a project has no docs yet, so a loader blind to `.adoc` would hide every doc it wrote.
+// Agent-runtime files (AGENTS.md, CLAUDE.md, specs) stay Markdown whatever the project uses.
+const DOC_EXT = new Set(['.md', '.adoc']);
+const isDoc = (name) => DOC_EXT.has(path.extname(name).toLowerCase());
 const LAZY_DIRS = ['docs', 'doc', 'documentation', 'architecture', 'adr', 'ADR'];
 const EXCLUDE_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'vendor', '.next',
   'target', '.venv', '__pycache__', '.opencode', '.harness']);
@@ -182,9 +188,8 @@ export function globalHookStandingDown(hookRoot, cwd) {
 
 /** `_disp` — relative to the repo root when it sits under it, else verbatim. */
 function disp(pathStr, root) {
-  // `os.path.relpath` raises ValueError across drives and the Python falls back to the
-  // path as given; `path.relative` silently returns an absolute path instead, which would
-  // print a DIFFERENT string rather than the same one.
+  // A path on another drive has no relative form, so it is printed as given. `path.relative`
+  // would silently return an absolute path instead — a different string, not the same one.
   if (path.parse(path.resolve(pathStr)).root.toLowerCase()
       !== path.parse(path.resolve(root)).root.toLowerCase()) {
     return pathStr;
@@ -193,18 +198,18 @@ function disp(pathStr, root) {
 }
 
 
-function rglobMd(dir, acc = []) {
+function rglobDocs(dir, acc = []) {
   for (const name of listDir(dir)) {
     const full = path.join(dir, name);
-    if (isDir(full)) rglobMd(full, acc);
-    else if (isFile(full) && path.extname(name).toLowerCase() === '.md') acc.push(full);
+    if (isDir(full)) rglobDocs(full, acc);
+    else if (isFile(full) && isDoc(name)) acc.push(full);
   }
   return acc;
 }
 
 /**
  * `_discover_context` — the no-manifest path, mirroring the OpenCode context plugin.
- * Root entry docs are eager; other root markdown, the doc trees and monorepo package
+ * Root entry docs are eager; other root docs (.md or .adoc), the doc trees and monorepo package
  * READMEs are lazy.
  */
 export function discoverContext(root, host = HOST) {
@@ -217,12 +222,12 @@ export function discoverContext(root, host = HOST) {
     const name = path.basename(full);
     if (native.includes(name)) continue;
     if (EAGER_ROOT.includes(name)) eager.set(full, null);
-    else if (path.extname(name).toLowerCase() === '.md') lazy.set(full, null);
+    else if (isDoc(name)) lazy.set(full, null);
   }
   for (const d of LAZY_DIRS) {
     const sub = path.join(root, d);
     if (!isDir(sub)) continue;
-    for (const md of sortPaths(rglobMd(sub))) {
+    for (const md of sortPaths(rglobDocs(sub))) {
       const parts = path.relative(root, md).split(/[\\/]/);
       if (parts.some((part) => EXCLUDE_DIRS.has(part))) continue;
       if (!eager.has(md) && !lazy.has(md)) lazy.set(md, null);
@@ -233,8 +238,10 @@ export function discoverContext(root, host = HOST) {
     if (!isDir(base)) continue;
     for (const pkg of sortPaths(listDir(base).map((n) => path.join(base, n)))) {
       if (!isDir(pkg) || EXCLUDE_DIRS.has(path.basename(pkg))) continue;
-      const readme = path.join(pkg, 'README.md');
-      if (isFile(readme) && !eager.has(readme) && !lazy.has(readme)) lazy.set(readme, null);
+      for (const name of ['README.md', 'README.adoc']) {
+        const readme = path.join(pkg, name);
+        if (isFile(readme) && !eager.has(readme) && !lazy.has(readme)) lazy.set(readme, null);
+      }
     }
   }
   return [
@@ -281,19 +288,18 @@ export function resolveContextSets(root, hookRoot = null) {
   let extend;
   try {
     let data = JSON.parse(raw);
-    // Valid JSON of the wrong SHAPE, guarded on both sides — see the Python original. JS
-    // would not have thrown here (`[].context` is merely undefined), which is exactly why
-    // the guard is written out rather than left to fall out of the language: without it,
-    // the two CLIs disagree about a file a user really does hand-edit.
+    // Valid JSON of the wrong SHAPE (null, a number, an array) is an empty manifest, not a
+    // syntax error. The guard is written out rather than left to fall out of the language:
+    // without it, `null.context` throws into the catch below and a file a user really does
+    // hand-edit is reported as invalid JSON when it is not.
     data = data && typeof data === 'object' && !Array.isArray(data) ? data : {};
     entries = data.context || [];
     if (!Array.isArray(entries)) entries = [];
     extend = Boolean(data.extend);
   } catch {
-    // See the Python original for why the decoder's own message is not quoted: the two
-    // engines disagree on the wording and on the offset, and V8 supplies no offset at all
-    // for the commonest shapes. Reporting the file is what the user needs; reporting
-    // WHICH decoder found it is what makes two implementations impossible.
+    // The decoder's own message is not quoted: its wording and offset are engine details,
+    // and V8 supplies no offset at all for the commonest shapes. Reporting the file is what
+    // the user needs.
     err(`[context] ${manifest} is not valid JSON — no context was loaded `
       + '(fix the syntax, then re-run).\n');
     return [[], [], String(manifest)];

package/js/hosts/hooks.mjs

@@ -201,7 +201,7 @@ const BOB_DENY_EXIT = 2;
  * logs. `gate-error` is a warning too: a crashed gate that blocked every tool call would be
  * a lockout, not a safeguard, and there is no prompt through which the user could clear it.
  */
-const BLOCK_RULES = new Set(['law-1', 'law-4']);
+const BLOCK_RULES = new Set(['law-1', 'law-4', 'rigor-5']);
 
 /**
  * THE GATE LEDGER — one JSON line per ask, nothing per defer.
@@ -358,6 +358,33 @@ const SECRET_RE =
   /\b(?:AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{30,}|sk-ant-[A-Za-z0-9_-]{20,}|xox[abprs]-[0-9A-Za-z-]{10,})\b|-----BEGIN [A-Z ]*PRIVATE KEY-----/;
 const DOTENV_RE = /(^|[\\/])\.env(\.[^\\/]*)?$/;
 
+/**
+ * External Gate's boundary half: the checks an agent is judged by must sit outside what it can
+ * edit, or a failing check is one edit away from a passing one. A project opts in by listing
+ * them, one repo-relative path per line (`#` comments), in `.geneseed/protected-checks.txt` at
+ * its git root — found by walking up from the WRITE TARGET, not the cwd, so a session in one repo
+ * writing into another reads that other repo's list. The list protects itself. Returns the entry
+ * the path falls under, or null. ponytail: a write tool only — a shell `sed -i` or redirect is
+ * not seen here; CI running the checks is the boundary that holds against that.
+ */
+export const SENSOR_LIST = '.geneseed/protected-checks.txt';
+function protectedCheck(p) {
+  try {
+    const target = resolvePath(p);
+    const root = gitRootOf(path.dirname(target));
+    if (!root) return null;
+    const text = readFileSync(path.join(root, SENSOR_LIST), 'utf8');
+    // `normcase` folds case AND slashes on Windows, so both sides go through it, the trailing
+    // separator of the prefix included.
+    const rel = normcase(path.relative(root, target));
+    const entries = [SENSOR_LIST, ...text.split(/\r?\n/).map((l) => l.trim().replace(/[\\/]+$/, ''))
+      .filter((l) => l && !l.startsWith('#'))];
+    return entries.find((e) => rel === normcase(e) || rel.startsWith(normcase(`${e}/`))) ?? null;
+  } catch {
+    return null;   // no list (the common case) or an unreadable one: nothing is protected
+  }
+}
+
 function ruleGate(args) {
   if (sovereignBypass(args.root)) return 0;
   return ruleDecide(args, readPayload());
@@ -378,6 +405,12 @@ function ruleDecide(args, payload) {
       + 'credential-shaped string. Secrets live in .env or a secret manager, never in a '
       + 'tracked file.');
   }
+  const sensor = protectedCheck(p);
+  if (sensor) {
+    return ask(args, 'rule-gate', 'rigor-5', `Geneseed (External Gate) — ${p} is a protected `
+      + `check (${sensor}, listed in ${SENSOR_LIST}). A check the agent can edit is not a `
+      + 'check: fix the code, not the check, unless the user asks for this edit.');
+  }
   const target = ruleGateTarget(p, args.root);
   if (!target) return 0;
   return ask(args, 'rule-gate', 'process-1', `Geneseed (Persist Insight) \u2014 writing to `

package/js/hosts/settings.mjs

@@ -513,7 +513,8 @@ export function claudeHookGroups(cfg, hookOpts, doctrines = null, excluded = [],
       SessionStart: [{ hooks: [{ type: 'command', command: `${run} context --root "${cfg}"${b} || exit 0` }] }],
       // One group, both gates: process 5's consent is a stderr line here (Bob has no ask
       // tier), so the pack toggle that drops Claude's git-gate group has nothing to drop —
-      // `tool-gate` only ever EXITS 2 for Laws I and IV, which every build carries.
+      // `tool-gate` only ever EXITS 2 for Laws I and IV, which every build carries, and for a
+      // write under a project's own `.geneseed/protected-checks.txt` — the project opted in.
       PreToolUse: [{ hooks: [{ type: 'command', command: `${run} tool-gate --root "${cfg}"${b}` }] }],
       Stop: [{ hooks: [{ type: 'command', command: `${run} learn ${mem} || exit 0` }] }],
     };

package/js/inspect/checks-constitution.mjs

@@ -169,14 +169,14 @@ const DOCTRINE_TOKEN_RE = /\{\{DOCTRINE(?:\}\}|:)/;
 /**
  * The rules the hooks enforce at the tool boundary, and the address each is bound to there. The
  * hook path cannot afford to read the canon on every tool call, so its gate-ledger keys
- * (`law-1`, `law-4`, `process-1`, `process-5` in `js/hosts/hooks.mjs` and the OpenCode guard
+ * (`law-1`, `law-4`, `process-1`, `process-5`, `rigor-5` in `js/hosts/hooks.mjs` and the OpenCode guard
  * plugin), `CONSENT_RULE` in `js/hosts/settings.mjs` and the console's `HOOK_GATED` stay
  * number-keyed — and this pin is what turns a renumber that moves one of these rules into a
  * doctor failure instead of a gate silently guarding its neighbour.
  */
 export const HOOK_PINNED = {
   'sealed-secrets': 'I', 'deletion-is-deliberate': 'IV',
-  'persist-insight': 'process 1', 'consent-before-push': 'process 5',
+  'persist-insight': 'process 1', 'consent-before-push': 'process 5', 'external-gate': 'rigor 5',
 };
 
 /**

package/js/loop/graph.mjs

@@ -83,7 +83,8 @@ export function checkGraph(graph, bricks) {
     if (!brick) continue;
     for (const o of brick.outcomes) {
       const count = edges.filter((e) => e.from === n && e.on === o).length;
-      if (count === 0) problems.push(`node ${n}: no edge for outcome ${o}`);
+      // `error` is reserved: with no edge the engine routes it to $stop (`recordOutcome`).
+      if (count === 0 && o !== 'error') problems.push(`node ${n}: no edge for outcome ${o}`);
       else if (count > 1) problems.push(`node ${n}: ${count} edges for outcome ${o}`);
     }
   }

package/js/loop/state.mjs

@@ -288,6 +288,22 @@ function allowedEntries(graph, v) {
   return { allowed: widest ? 1 + widest.max : 1, loop: widest };
 }
 
+// The repair ring an edge closes: the smallest non-iteration loop whose FIRST node is the edge's
+// target and which also holds its source (test -> apply is apply-test's repair, review -> apply
+// review-fix's). Its own counter makes `max` the number of repairs that ring may spend, even when
+// a wider ring sharing the node raises the node budget above it — `max: 1` is one repair, then
+// `exhaust`'s fresh attempt, then a stop (arXiv 2607.24604: a second revision lowers accuracy).
+// Its key lives in `counters`, so every reset of a unit resets it too.
+function repairRing(graph, from, to) {
+  const iteration = iterationLoop(graph);
+  let ring = null;
+  for (const m of graph.loops) {
+    if (m === iteration || m.nodes[0] !== to || !m.nodes.includes(from)) continue;
+    if (!ring || m.nodes.length < ring.nodes.length) ring = m;
+  }
+  return ring;
+}
+
 // Porcelain lines are `XY <path>`; strip the 2-char status + space, slash-normalise, drop
 // LOOP.md rows (the engine rewrites it on every action — it is never part of the scored work)
 // and a lingering LOOP.md.tmp (the atomic writer's own sibling — see `writeLoopFile`'s docblock).
@@ -348,10 +364,17 @@ export function recordOutcome(state, bricks, outcome, { card = null, porcelain =
   // this call closes the unit, re-splits, or stops the loop. `notes` is never reset mid-run
   // (only `exhaust`'s own push and `decideAwaiting` add to it otherwise), so it survives
   // `resetUnit`/`finishUnit` — which a card does not: `resetUnit` clears it.
+  // A fresh verdict: `test`'s latest report supersedes its earlier ones, so a repair never reads
+  // findings about code that has since changed (stale traces broke 34 of 135 correct attempts
+  // in arXiv 2607.24604, fresh ones 4). Every other brick's notes are a record and are kept.
+  if (from === 'test') state.notes = state.notes.filter((n) => !/^iteration \d+ \(test\): /.test(n));
   if (note) state.notes.push(`iteration ${state.iteration} (${from}): ${note}`);
   state.visited.push(from);
 
-  const edge = state.graph.edges.find((e) => e.from === from && e.on === outcome);
+  // `error` is reserved: a check that produced no verdict stops for a human, never a repair. A
+  // brick may declare it without an edge (`checkGraph` allows that); the engine routes it here.
+  const edge = state.graph.edges.find((e) => e.from === from && e.on === outcome)
+    ?? (outcome === 'error' ? { from, on: 'error', to: '$stop' } : null);
   if (!edge) throw new Error(`no edge from ${from} on ${outcome}`);
   if (brick.gate === 'human' && (!brick.gateOn || brick.gateOn.includes(outcome))) {
     state.status = 'awaiting';
@@ -385,6 +408,12 @@ function transition(state, bricks, from, edge) {
     finishUnit(state, false);
     return state.status === 'stopped' ? { stopped: state.reason } : { node: state.node };
   }
+  const ring = repairRing(state.graph, from, edge.to);
+  if (ring) {
+    const key = `ring:${ring.name}`;
+    state.counters[key] = (state.counters[key] ?? 0) + 1;
+    if (state.counters[key] > ring.max) return exhaust(state, ring);
+  }
   state.counters[edge.to] = (state.counters[edge.to] ?? 0) + 1;
   const { allowed, loop } = allowedEntries(state.graph, edge.to);
   if (state.counters[edge.to] > allowed) return exhaust(state, loop ?? { name: edge.to, max: 0 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "Every field here is argued and gated in tests/unit/package_manifest.test.mjs. `files`, `bin` and `engines` each have a test that fails when reality drifts from this file; `version` mirrors harness.config.json and is gated too. Read that docblock before editing this one.",
   "name": "geneseed",
-  "version": "3.16.0",
+  "version": "3.17.0",
   "description": "A portable, theme-able harness you implant once and use everywhere to grow a disciplined AI coding agent.",
   "keywords": [
     "ai",

package/src/agents/docs.md

@@ -24,6 +24,11 @@
    that the code does not implement ({{LAW:verify-before-asserting}}).
 2. Write for the stated audience; lead with what the reader needs to do.
 3. Keep examples runnable; update any example that the change broke.
+4. Write each page in the format it is already in — Markdown or AsciiDoc; never convert one.
+   A new page follows the `Docs format:` line in the root `AGENTS.md`, else the format the
+   project's docs already use (only AsciiDoc when it has none yet). Agent-runtime files —
+   `AGENTS.md`, `CLAUDE.md`, specs, ADRs loops read — stay Markdown. In AsciiDoc, never add
+   an `include::` to a page agents read.
 
 ## Output contract
 - The doc files written/updated, a one-line note of what changed and why,

package/src/bricks/apply.md

@@ -9,6 +9,9 @@ Implement the card's intent exactly, touching only the files in its `writeSet`.
 carries an `amend`, that supersedes the original intent — follow the amendment, not the plan it
 replaced.
 
+When this is a repair after `test`, act on the latest `test` note only — it is the verdict on
+the code as it stands. Fix every finding it lists in this one pass: there is no second repair.
+
 Make no unrelated edits: no drive-by rename, no incidental cleanup, no touching a file the card
 did not declare. If the change genuinely needs a file outside the write set, stop and report that
 rather than widening scope unasked — the diff is scored against the declared set, not your

package/src/bricks/docs-update.md

@@ -10,6 +10,8 @@ flag, a moved file, a behaviour the README or docs still describe the old way.
 
 Update only those docs, only to match what the diff actually changed. Do not rewrite unrelated
 prose, reorganize a page, or fix an unrelated staleness you happen to notice while in there.
+Keep each doc in the format it is already in (Markdown or AsciiDoc) — never convert one; a new
+page follows the `Docs format:` line in the root `AGENTS.md`.
 
 Report `pass` once every doc the diff touched is back in sync, naming the files you changed — or
 that none needed it, if the diff left nothing stale.