geneseed 3.15.0 → 3.17.0

package/CHANGELOG.md

@@ -8,6 +8,41 @@ 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)).
+
+### Added
+
+- `--exclude-skills <name,…>` leaves skills you never use out of an install, on every host: their files, their catalogue rows and any OpenCode command that runs them. The install records the list on an `Excluded skills:` line, and `upgrade`, `rebuild-all`, `diff`, `setup` and the web console keep it. Unknown skills are refused, and so are the ten the harness links to by path. `status` shows `skills off: …`.
+
+### Fixed
+
+- The context hook (Claude Code, Bob, OpenClaude) now keeps its whole output under 9,000 characters. Claude Code shows the model only a preview of a hook output past ~10k, so a doc-heavy repo lost its context silently — this repo's was 25.6 KB, now 2.5 KB. Eager docs that do not fit are listed lazy with the reason; the lazy listing folds three or more docs in one folder into `dir/ — N docs` and ends in a count if it is still too long. The OpenCode plugin folds its project listing the same way.
+
 ## [3.15.0] — 2026-10-05
 
 **Upgrading:** re-emit (`geneseed rebuild-all`) so OpenCode installs get the hardened plugins and

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.15.0**.
+> string. Current label: **3.17.0**.
 
 ## Capabilities
 

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

@@ -117,6 +117,8 @@ const MAX_DEPTH = 6
 // the head of each file (enough for an H1) rather than the whole thing — a large
 // docs/ tree must not cost one full-file read per entry on every session start.
 const LAZY_HEADING_LIMIT = envNum("GENESEED_LAZY_HEADINGS", 64)
+// Same threshold as the Claude hook's LAZY_FOLD_AT.
+const LAZY_FOLD_AT = 3
 const HEADING_SLICE_BYTES = 4096
 
 // Quiet by default — OpenCode surfaces a plugin's stderr in the UI (red text). Set
@@ -154,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.
@@ -275,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 ""
 }
@@ -423,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)
     }
   }
@@ -446,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.
@@ -467,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)
+      }
     }
   }
 
@@ -664,7 +674,7 @@ async function wikiSets() {
 // Render one eager+lazy set into `out`. The budget state (eager bytes, heading
 // reads) is SHARED across segments — project context and every wiki draw from the
 // same caps, so the whole block stays bounded no matter how many wikis are declared.
-async function renderSet(out, { eager, lazy }, state) {
+async function renderSet(out, { eager, lazy }, state, { fold = false } = {}) {
   const perFile = EAGER_FILE_KB * 1024
   const total = EAGER_TOTAL_KB * 1024
   const demoted = []
@@ -692,8 +702,26 @@ async function renderSet(out, { eager, lazy }, state) {
     state.injected++
   }
 
+  // The project listing folds like the Claude hook's (js/hosts/hooks-context.mjs): three or more
+  // undescribed docs sharing a parent directory become one `dir/ — N docs` line — a docs/ tree
+  // of 186 files was 186 lines on every session. Root files never fold. A wiki listing keeps its
+  // per-note headings: a vault is navigated by them, and it carries its own cap.
+  const byDir = new Map()
+  if (fold) {
+    for (const l of lazy) {
+      const dir = path.posix.dirname(l.rel.replace(/\\/g, "/"))
+      if (!l.desc && dir !== ".") byDir.set(dir, (byDir.get(dir) || 0) + 1)
+    }
+  }
+  const folded = new Set()
   const lazyLines = []
   for (const l of lazy) {
+    const dir = path.posix.dirname(l.rel.replace(/\\/g, "/"))
+    if (!l.desc && byDir.get(dir) >= LAZY_FOLD_AT) {
+      if (!folded.has(dir)) lazyLines.push(`  - ${dir}/ — ${byDir.get(dir)} docs`)
+      folded.add(dir)
+      continue
+    }
     let head = l.desc
     // Only crack open files we have no description for, and cap how many — bounded by
     // a head-slice read so a big docs/ tree stays cheap on every session start.
@@ -734,7 +762,7 @@ async function buildBlock(sets, wikis = [], commands = [], session = []) {
   }
 
   const proj = []
-  await renderSet(proj, sets, state)
+  await renderSet(proj, sets, state, { fold: true })
 
   if (commands.length) {
     proj.push("--- Project commands (runnable targets discovered in the repo root) ---")

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

@@ -4,18 +4,18 @@ order: 12
 title: "Exclusions"
 kind: "concept"
 section: "Configuration"
-description: "Two ways to switch things off: one rule, or every hook in a folder."
+description: "Three ways to switch things off: one rule, one skill, 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:
+Geneseed has three ways to switch something off, and they work at different scales:
 
-| | Sovereign repo | Per-rule exclusion |
-| --- | --- | --- |
-| **Switches off** | the whole global install, inside one folder | one doctrine rule, everywhere the install applies |
-| **Scope** | a folder and everything under it | the install |
-| **Applies to** | **global** installs only | any install |
-| **Set with** | `geneseed exclude add <path>` | `--exclude-rules` at build time |
-| **Takes effect** | on the next tool call, no rebuild | on rebuild |
+| | Sovereign repo | Per-rule exclusion | Per-skill exclusion |
+| --- | --- | --- | --- |
+| **Switches off** | the whole global install, inside one folder | one doctrine rule, everywhere the install applies | one skill, everywhere the install applies |
+| **Scope** | a folder and everything under it | the install | the install |
+| **Applies to** | **global** installs only | any install | any install |
+| **Set with** | `geneseed exclude add <path>` | `--exclude-rules` at build time | `--exclude-skills` at build time |
+| **Takes effect** | on the next tool call, no rebuild | on rebuild | on rebuild |
 
 > **You already know this:** `.gitignore` versus disabling one lint rule. One makes a tool ignore a whole folder; the other keeps the tool running everywhere with one check turned off.
 
@@ -55,3 +55,15 @@ 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 [Doctrine packs and single rules](../guides/setup-doctrines.md); what the layers are is in [Rules](rules.md).
+
+### Per-skill exclusion — skills you never use
+
+Every installed skill costs a line in the host's skill listing, every session. Skills you never use can be left out of an install:
+
+```bash
+geneseed build --emit claude-global --exclude-skills "bruno-test-writer,bruno-collection-generator,react-view-transitions"
+```
+
+The skill's files are not written, its catalogue row goes, and an OpenCode `/command` that runs it goes too. The install records the list (`Excluded skills: …` under its skill section), and every rebuild and upgrade keeps it. `--exclude-skills none` puts them all back.
+
+A few skills cannot be excluded, because the harness itself links to them by path — `council`, `rule`, `skill-forge`, `workflow` and a handful more. The flag names them when it refuses one. Skills you installed yourself are not Geneseed's to exclude: remove those from the host's skills folder directly.

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/install-scripted.md

@@ -12,7 +12,7 @@ description: "The build command to run in a script, a CI job, or a shell with no
 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`, `--trust`, `--doctrines`, `--exclude-rules`) are covered in [Choose your setup](choose-your-setup.md) and the two pages after it.
+`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) and the two pages after it. `--exclude-skills` leaves skills you never use out of the install; see [Exclusions](../concepts/exclusions.md).
 
 To test a build before writing anything, use `geneseed validate` with the same flags. See [Verify](verify.md).
 

package/docs/guides/project-context.md

@@ -21,11 +21,11 @@ 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`.
 
-Eager files share a 48 KB budget per session. An eager file that would go over the budget is listed instead, to be read on demand.
+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.
 
 On OpenCode the context plugin does this work. On Claude Code, Bob and OpenClaude, the session-start hook does it (`geneseed-hook context`). Both read the same override file, described next.
 

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/docs/token-footprint.md

@@ -35,11 +35,13 @@ pointer to the host's own inventory instead, ~1.9k tokens lighter. A session fil
 byte-identical to its seed is skipped — it says nothing — so a fresh install injects none
 of them; until 2026-10 the hook read them from the repo root, where a Claude-shaped install
 never puts them, and none reached the session at all. The
-eager-injection path is budget-capped identically everywhere — 16 KB per file
-(cut at a line break, with a marker saying so) and 48 KB per session (files past
-the budget are listed lazy with the reason) — so a 40k-character README no
-longer leaves whole every session, and growing Memory degrades every host the
-same way instead of one silently falling behind. The hook also **never injects
+eager-injection path is budget-capped on every host. The SessionStart hook (Claude Code,
+Bob, OpenClaude) keeps its whole payload under 9,000 characters: Claude Code persists a
+hook output past ~10k to a file and shows the model a 2 KB preview, so until 2026-10 a
+doc-heavy repo's context was cut off unannounced. Session files come first, eager docs
+are injected whole or listed lazy with the reason. The OpenCode plugin has no such cap
+and keeps 16 KB per file / 48 KB per session. Both fold a lazy listing: three or more
+docs in one folder become one `dir/ — N docs` line. The hook also **never injects
 the root file the host loads by itself** (`CLAUDE.md` on Claude Code,
 `AGENTS.md` on Bob, `AGENT.md`/`AGENTS.md`/`CLAUDE.md` on OpenCode):
 until 2026-09 it did, and the whole harness was paid twice per session.
@@ -106,11 +108,12 @@ token counter also includes, none of which Geneseed controls:
 2. **Your repo's docs, injected eagerly** — the context delivery
    (plugin on OpenCode, SessionStart hook on Claude Code / Bob / OpenClaude) discovers and
    injects `README.md`, `CONTRIBUTING.md`, and files under `docs/`, up to the
-   48 KB budget (≈12k tokens). A doc-heavy repo fills it.
+   budget: 9,000 characters for the whole hook payload (≈2.3k tokens), 48 KB on
+   OpenCode (≈12k tokens).
 3. **Wiki eager entries** plus the lazy listing of the rest, if a wiki is
    configured.
 4. **Grown Memory/Notebook** — the emitted starter set is ~1.2k, but both
-   accumulate with use (same 48 KB shared budget).
+   accumulate with use (same shared budget).
 5. **Other instruction files the host also loads** — a global install plus a
    per-repo install, a personal `~/.claude/CLAUDE.md`, or MCP servers each add
    their own share.

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

package/js/build/args.mjs

@@ -10,7 +10,9 @@ import { existsSync, readFileSync } from 'node:fs';
 import { parseArgs as nodeParseArgs } from 'node:util';
 import { withPlatformNewlines } from '../lib/fs.mjs';
 import path from 'node:path';
-import { CONFIG, discoverNames, PACK_ORDER, knownRuleIds } from './source.mjs';
+import {
+  CONFIG, discoverNames, PACK_ORDER, knownRuleIds, knownSkillIds, linkedSkillIds,
+} from './source.mjs';
 // The loop engine's trust presets — the `--trust` choices. `score.mjs` imports nothing, which is
 // what lets it sit inside this module's `child_process` ban.
 import { DEFAULT_PRESET, PRESETS } from '../loop/score.mjs';
@@ -30,7 +32,7 @@ const EMITS = ['files', 'opencode', 'opencode-global', 'claude', 'claude-global'
 export function configDefaults() {
   const d = {
     theme: 'neutral', posture: 'peer', mode: 'direct', trust: DEFAULT_PRESET,
-    doctrines: [...PACK_ORDER], excludeRules: [],
+    doctrines: [...PACK_ORDER], excludeRules: [], excludeSkills: [],
   };
   if (!existsSync(CONFIG)) return d;
   try {
@@ -93,7 +95,7 @@ export function configDefaults() {
  */
 const VALUED = {
   '--theme': 'theme', '--posture': 'posture', '--mode': 'mode', '--trust': 'trust',
-  '--doctrines': 'doctrines', '--exclude-rules': 'excludeRules',
+  '--doctrines': 'doctrines', '--exclude-rules': 'excludeRules', '--exclude-skills': 'excludeSkills',
   '--out': 'out', '--target': 'out', '--emit': 'emit',
   '--footprint': 'footprint', '--root': 'root', '--config-dir': 'cfgDir',
 };
@@ -177,6 +179,33 @@ function parseExcludeRules(value) {
   return [...new Set(out)].sort();
 }
 
+/**
+ * `--exclude-skills "bruno-test-writer,openscad"` -> the cfg's skill exclusion array.
+ *
+ * Refused, by name: a skill this checkout does not ship (a typo would exclude nothing in
+ * silence), and a skill the constitution or another skill links to by path — excluding it
+ * would ship that link dead (`linkedSkillIds`). Sorted and deduped for marker stability.
+ */
+function parseExcludeSkills(value) {
+  const s = value.trim();
+  if (s === 'none' || s === '') return [];
+  const known = knownSkillIds();
+  const linked = linkedSkillIds();
+  const out = [];
+  for (const name of s.split(',').map((x) => x.trim()).filter(Boolean)) {
+    if (!known.includes(name)) {
+      die(2, `argument --exclude-skills: unknown skill '${name}' (choose from `
+        + `${known.filter((k) => !linked.includes(k)).join(', ')}, or 'none')`);
+    }
+    if (linked.includes(name)) {
+      die(2, `argument --exclude-skills: '${name}' cannot be excluded — the harness links to it `
+        + `by path (protected: ${linked.join(', ')})`);
+    }
+    out.push(name);
+  }
+  return [...new Set(out)].sort();
+}
+
 /**
  * `--doctrines craft,rigor` / `--doctrines none` -> the cfg's pack array.
  *
@@ -271,6 +300,7 @@ export function parseArgs(argv, defaults) {
     trust: defaults.trust,
     doctrines: defaults.doctrines,
     excludeRules: defaults.excludeRules,
+    excludeSkills: defaults.excludeSkills ?? [],
     out: 'Harness', emit: 'files', footprint: 'lean', root: null,
     syncThemes: false, validateOnly: false, verbose: false,
   };
@@ -314,6 +344,7 @@ export function parseArgs(argv, defaults) {
   // already the array `configDefaults` built, and re-parsing an array would stringify it.
   if (typeof args.doctrines === 'string') args.doctrines = parseDoctrines(args.doctrines);
   if (typeof args.excludeRules === 'string') args.excludeRules = parseExcludeRules(args.excludeRules);
+  if (typeof args.excludeSkills === 'string') args.excludeSkills = parseExcludeSkills(args.excludeSkills);
   return args;
 }
 

package/js/build/driver.mjs

@@ -596,16 +596,17 @@ const PROJECT_EMITS = {
  * mode readers return `null` for "undetectable" too, which an explicit `posture: null` would
  * carry straight past the parameter default.
  */
-function axesCfg({ posture, mode, trust, doctrines, excludeRules }) {
+function axesCfg({ posture, mode, trust, doctrines, excludeRules, excludeSkills }) {
   return makeCfg({
     ...(posture ? { posture } : {}), ...(mode ? { mode } : {}), ...(trust ? { trust } : {}),
     ...(doctrines ? { doctrines } : {}), ...(excludeRules ? { excludeRules } : {}),
+    ...(excludeSkills ? { excludeSkills } : {}),
   });
 }
 
 export function emitProjectInto(host, {
   theme, out, root, footprint = 'full', posture = null, mode = null, trust = null,
-  doctrines = null, excludeRules = null,
+  doctrines = null, excludeRules = null, excludeSkills = null,
 }) {
   const emit = PROJECT_EMITS[host];
   // The axes ride the same rail into every `*Into`, and for the same reason: a drift reader
@@ -613,7 +614,7 @@ export function emitProjectInto(host, {
   // edited on every narrowed install, and `validate --doctrines craft` that ignored its flag
   // checked an all-packs render nobody asked for.
   return withPlatformNewlines(() => emit(
-    axesCfg({ posture, mode, trust, doctrines, excludeRules }), { theme, footprint, root }, out,
+    axesCfg({ posture, mode, trust, doctrines, excludeRules, excludeSkills }), { theme, footprint, root }, out,
   ));
 }
 
@@ -627,15 +628,15 @@ export function emitProjectInto(host, {
  */
 export function buildInto({
   theme, out, footprint = 'lean', posture = null, mode = null, trust = null, doctrines = null,
-  excludeRules = null,
+  excludeRules = null, excludeSkills = null,
 }) {
-  return withPlatformNewlines(() => build(axesCfg({ posture, mode, trust, doctrines, excludeRules }),
+  return withPlatformNewlines(() => build(axesCfg({ posture, mode, trust, doctrines, excludeRules, excludeSkills }),
     theme, out, { footprint, nativeCatalog: false }));
 }
 
 export function emitGlobalInto(host, {
   theme, out, cfgDir, footprint, posture = null, mode = null, doctrines = null, trust = null,
-  excludeRules = null,
+  excludeRules = null, excludeSkills = null,
 }) {
   // `build.HOSTS.get(host, build.HOSTS["opencode"])` — an unknown host falls back rather than
   // raising, because the host comes from a marker file a user can edit.
@@ -651,7 +652,7 @@ export function emitGlobalInto(host, {
   // edited on every install that chose a register, narrowed its packs or excluded a rule —
   // the same scar the footprint left in `diffCollect`, one axis over each time.
   return withPlatformNewlines(() => emit(
-    axesCfg({ posture, mode, trust, doctrines, excludeRules }),
+    axesCfg({ posture, mode, trust, doctrines, excludeRules, excludeSkills }),
     { theme, footprint, root: null, cfgDir }, out,
   ));
 }

package/js/build/generate.mjs

@@ -40,7 +40,7 @@ import { DEFAULT_PRESET } from '../loop/score.mjs';
 import { opencodeConfigDir, resolvePath } from '../hosts/hosts.mjs';
 import {
   EMIT_HOST_SCOPE, defaultMode, defaultPosture, defaultTheme, doctrinesForBuild,
-  excludedRulesOfDir, footprintOfDir, installState, installTargets, modeOfDir, postureOfDir,
+  excludedRulesOfDir, excludedSkillsOfDir, footprintOfDir, installState, installTargets, modeOfDir, postureOfDir,
   readMaybe, themeOfDir, trustOfDir,
 } from '../hosts/installs.mjs';
 import { colorThemeFiles, colorThemeJson, PALETTE_ROLES } from '../hosts/opencode.mjs';
@@ -97,7 +97,7 @@ function sysExit(msg) {
 const BUILD_FORWARD = [
   ['theme', '--theme'], ['emit', '--emit'], ['footprint', '--footprint'],
   ['posture', '--posture'], ['mode', '--mode'], ['trust', '--trust'], ['doctrines', '--doctrines'],
-  ['excludeRules', '--exclude-rules'], ['out', '--out'], ['root', '--root'],
+  ['excludeRules', '--exclude-rules'], ['excludeSkills', '--exclude-skills'], ['out', '--out'], ['root', '--root'],
   ['configDir', '--config-dir'],
 ];
 
@@ -140,7 +140,7 @@ export function cmdBuild(args) {
  */
 export function setupBuildArgs(theme, emit, out = null, root = null, footprint = 'lean',
   posture = 'peer', mode = 'direct', doctrines = null, allPacks = PACK_ORDER,
-  excludeRules = null, trust = DEFAULT_PRESET) {
+  excludeRules = null, trust = DEFAULT_PRESET, excludeSkills = null) {
   const argv = ['--theme', theme, '--emit', emit];
   if (!emit.endsWith('-global')) {
     if (out) argv.push('--out', out);
@@ -164,6 +164,10 @@ export function setupBuildArgs(theme, emit, out = null, root = null, footprint =
   if (Array.isArray(excludeRules)) {
     argv.push('--exclude-rules', excludeRules.length ? excludeRules.join(',') : 'none');
   }
+  // Skills elide when nothing is excluded: the driver's default IS nothing (no config key
+  // feeds it), so the flag's absence and `none` are the same answer, and every argv that
+  // excludes nothing stays the bytes it was before the flag existed.
+  if (excludeSkills?.length) argv.push('--exclude-skills', excludeSkills.join(','));
   return argv;
 }
 
@@ -217,9 +221,11 @@ export function installProfile(host, scope, root) {
   // dropped it would quietly hand back every rule its owner switched off, and `process 5` is
   // one of them. `null` (no marker) stays `null` so the argv omits the flag, as it always did.
   const excludeRules = excludedRulesOfDir(root);
+  // Skills left out stay left out: an upgrade that forgot them would put them all back.
+  const excludeSkills = excludedSkillsOfDir(root);
   const out = scope === 'global' ? null : root;
   const argv = setupBuildArgs(theme, emit, out, out, footprint, posture, mode, doctrines,
-    PACK_ORDER, excludeRules, trust);
+    PACK_ORDER, excludeRules, trust, excludeSkills);
   // A GLOBAL ROW NAMES ITS OWN DIR. `root` came from the host's config-dir resolver, which
   // honours env overrides (`OPENCODE_CONFIG_DIR`, `CLAUDE_CONFIG_DIR`…); without the flag the
   // same argv run from a shell lacking that variable re-emits into the DEFAULT dir — a second
@@ -227,7 +233,7 @@ export function installProfile(host, scope, root) {
   if (scope === 'global') argv.push('--config-dir', root);
   return {
     host, scope, root, state: installState(root, host, scope),
-    emit, theme, footprint, posture, mode, trust, doctrines, excludeRules, argv,
+    emit, theme, footprint, posture, mode, trust, doctrines, excludeRules, excludeSkills, argv,
   };
 }