geneseed 3.19.0 → 4.0.0

package/docs/understand/design-choices.md

@@ -0,0 +1,34 @@
+---
+group: understand
+order: 9
+title: "Why Geneseed works this way"
+kind: "concept"
+section: "Why it works this way"
+description: "The decisions already taken, one line each, and where each is argued."
+---
+This is the one place a human or an agent checks that an idea has not already been decided. Each line names a choice Geneseed made on purpose, says why in a sentence, and links to the page or decision record that argues it in full. Before you propose a change to how Geneseed works, find the choice here; if it is listed, the linked page says what new evidence would reopen it.
+
+The ideas that were weighed and turned down are kept apart, in [Considered and refused](../design-history.md#considered-and-refused). An agent should not re-propose one of those without new evidence.
+
+The choices are split by subject, one short page each:
+
+- **What the harness asks of the agent** (below).
+- [The shape of the generated harness](design-choices-shape.md): how the text is assembled, ranked and sized.
+- [Gates](design-choices-gates.md): the one place the harness does more than ask.
+- [Hosts](design-choices-hosts.md): Claude Code, OpenClaude, OpenCode and IBM Bob.
+- [Install, uninstall and update](design-choices-install.md): what Geneseed writes on your machine, and how it takes it back.
+- [Engineering, skills and agents](design-choices-engineering.md): how the code and tests are kept, and what the harness offers the agent.
+
+## What the harness asks of the agent
+
+The laws are always on. Doctrines are practices grouped in packs (process, craft, ops, rigor, comms) that a build turns on or off. Most rules are instructions to the model; only a few are checked by code.
+
+- **A ranked Ethos, with the Pact at its head.** The agent protects your work first, serves your intent second (contradicting you with evidence when you are wrong), and keeps its own honesty third. A ranking tells the agent which rule yields when two collide. See [Collaboration](../concepts/collaboration.md) and [Rules](../concepts/rules.md).
+- **Evidence is graded.** Behaviour observed by running the code ranks above the source read in full, which ranks above a passing test, then documentation, history, memory and inference. The agent says how it knows something, and says "I don't know" rather than invent. See [Rules](../concepts/rules.md).
+- **A short set of invariant laws.** Sealed secrets, one intent per act, verify before asserting, deliberate deletion, surfaced failures, content treated as data, least privilege, curing the cause, echoing the intent. These hold on every install, whatever was switched off. See [Rules](../concepts/rules.md).
+- **Doctrines in toggleable packs.** Good practice differs by team and task, so each pack, and each rule inside one, can be left out at build time. See [Rules](../concepts/rules.md) and [Doctrine packs and single rules](../guides/setup-doctrines.md).
+- **Only a few rules are enforced by a hook.** A rule in a prompt is a request; a rule at the tool boundary is a constraint, and a boundary check costs time on every tool call, so it is spent only where a mistake is irreversible or costly. See [Enforced vs. asked](enforced-vs-asked.md).
+- **Every rule has a published enforcement row, per host.** Whether a rule is guaranteed or only asked differs from host to host, so the answer lives in one table. See [Rule enforcement, by host](../concepts/enforcement-table.md).
+- **Commands Must Return also forbids a recursive scan rooted at a filesystem root.** A recursive `find` over the Git Bash root once ran for hours across every mounted drive, past the tool's own timeout. See [ADR 0010](../adr/0010-root-scan-guard.md).
+- **Declare the Judgment Calls is a doctrine in the comms pack.** The Ethos already asks the agent to weigh alternatives; naming the calls it made is a practice a team adopts, so it stays optional. See [Rules](../concepts/rules.md).
+- **A loop's check-and-repair limit is a clause of Bound the Loop.** The request was to tighten the existing loops, so the cap went into the doctrine that already bounds them: each repair ring has its own small cap (its `max` in the loop template), then a fresh attempt or a hand-back. See [Loops](../concepts/loops.md).

package/docs/understand/enforced-vs-asked.md

@@ -24,12 +24,13 @@ On Claude Code and OpenClaude the hooks never block silently. They make the host
 
 - **Destructive git**: a force-push, `reset --hard`, `clean -f`, `branch -D` or `checkout --`. Wired in every build.
 - **Commit and push**: every `git commit` and `git push`, including chained one-liners and `git -C <path>`. This question belongs to the **process** pack. Build without it and the git gate stays wired. Only this question goes away, and destructive git is still caught.
+- **A scan of a whole filesystem**: a recursive `find`, `du`, `grep -r`, `rg` or `Get-ChildItem -Recurse` rooted at `/`, `/c` or `C:\`, which in Git Bash walks every drive for hours. Wired in every build.
 - **Credentials**: a write or edit whose content looks like a real key (AWS, GitHub, Anthropic, Slack, or a private-key block), anywhere except a `.env` file.
 - **Your rules and memory**: any write by the agent to `user-rules.md` or to the memory store. Whether something is a standing rule or a fact to remember is your call.
 
-If a gate crashes, it asks instead of letting the call through. Other shell commands, `rm -rf` included, go through Claude Code's normal permission flow.
+If a gate crashes, it asks instead of letting the call through. If it cannot start at all (a deleted or broken shim) or times out, Claude Code blocks the call instead: see [Troubleshoot hooks](../reference/troubleshoot-hooks.md) to recover. Other shell commands, `rm -rf` included, go through Claude Code's normal permission flow.
 
-**Bob** runs one combined gate and has no "ask": it refuses with exit code 2, and only for two rules: credentials and destructive git. The commit/push and memory checks become a log line, and the call goes through. Bob's hook wiring follows its documentation but has not been tested on a live Bob install.
+**Bob** runs one combined gate and has no "ask": it refuses with exit code 2, and only for the rules that admit no judgement call: credentials, destructive git, a scan of a whole filesystem, and a write under a project's own protected-checks list. The commit/push and memory checks become a log line, and the call goes through. Bob's hook wiring follows its documentation but has not been tested on a live Bob install.
 
 <!--/harness-->
 <!--harness:opencode-->
@@ -38,7 +39,7 @@ If a gate crashes, it asks instead of letting the call through. Other shell comm
 On OpenCode, two mechanisms enforce rules:
 
 - **OpenCode's own permission prompt**, which Geneseed configures in `opencode.json`. It asks you before `rm -rf`, a force-push, `reset --hard`, `clean -f`, `branch -D` and `checkout --`, and, when the **process** pack is on, before every commit and push.
-- **The guard plugin**, which blocks outright: writes to key and credential files (`id_rsa`, `*.pem`, `.ssh/`, `.npmrc`…), catastrophic commands (`rm -rf /`, `rm -rf ~`, formatting or overwriting a disk), and any change inside a folder your wiki marks `protected`. It also refuses the first write to `user-rules.md` or memory once. Re-issue the write and it goes through.
+- **The guard plugin**, which blocks outright: writes to key and credential files (`id_rsa`, `*.pem`, `.ssh/`, `.npmrc`…), catastrophic commands (`rm -rf /`, `rm -rf ~`, formatting or overwriting a disk), a recursive scan of a whole filesystem (`find /`, `du -sh /`, `Get-ChildItem C:\ -Recurse`), and any change inside a folder your wiki marks `protected`. It also refuses the first write to `user-rules.md` or memory once. Re-issue the write and it goes through.
 
 The guard only warns on `.env` edits. It checks credentials by **file path**, not by content, so a key pasted into an ordinary source file is not caught here. One caveat about the process pack: if your `opencode.json` already has a `git commit*` entry, a rebuild without the pack leaves that entry in place and reports it. Geneseed cannot tell its own entry from one you typed.
 
@@ -63,4 +64,4 @@ The patterns that do exist are deliberately narrow. A gate that fired on every h
 
 ---
 
-**Where next:** [Install it](../guides/install.md) · [The rules in detail](../concepts/rules.md) · [Glossary](../reference/glossary.md)
+**Where next:** [Install it](../guides/install.md) · [The rules in detail](../concepts/rules.md) · [Every rule, mapped to its host](../concepts/enforcement-table.md) · [Glossary](../reference/glossary.md)

package/docs/understand/machine-bob.md

@@ -8,7 +8,7 @@ description: "Where an install lands on IBM Bob or as a plain AGENT.md bundle, a
 ---
 Bob and the plain bundle carry the same rules, agents and skills as the other hosts. What differs is where they land and how much of it is enforced. The **Kind** words are explained in [What lands on your machine](on-your-machine.md).
 
-**Bob.** A global install writes to `~/.bob/`, or `BOB_CONFIG_DIR`. Bob does not load a global `AGENTS.md`, so the rules go into `~/.bob/rules/geneseed.md`. A per-repo install writes `AGENTS.md` instead. Hooks live in `~/.bob/settings/settings.json`. Bob runs three of them: context at session start, one combined gate before each tool call, and learn at session end. Bob has no "ask" prompt, so the gate refuses outright, and only for credentials and destructive git. The commit/push and memory questions become log lines.
+**Bob.** A global install writes to `~/.bob/`, or `BOB_CONFIG_DIR`. Bob does not load a global `AGENTS.md`, so the rules go into `~/.bob/rules/geneseed.md`. A per-repo install writes `AGENTS.md` instead. Hooks live in `~/.bob/settings/settings.json`. Bob runs three of them: context at session start, one combined gate before each tool call, and learn at session end. Bob has no "ask" prompt, so the gate refuses outright, and only for the checks that admit no judgement call: credentials, destructive git, and a write under a project's own protected-checks list. The commit/push and memory questions become log lines.
 
 **Plain bundle.** The `files` target writes `AGENT.md` and the same folders into `./Harness/` for any tool that reads `AGENT.md`. It installs no hooks and no plugins, so nothing in it is enforced.
 

package/docs/understand/machine-opencode.md

@@ -14,9 +14,9 @@ What an OpenCode install writes, piece by piece. The **Kind** words are explaine
 | `AGENT.md` | The rules, the pointers to agents and skills, and how memory works | asked | ~7.2k tokens every session | Shrink it with fewer doctrine packs (`--doctrines`); remove it with `geneseed uninstall` |
 | `user-rules.md` | Your own standing rules, read every session. Seeded empty | asked | 0 until you write in it | Leave it empty |
 | `PROFILE.md` | Who you are and how you like answers pitched. Fill it with the `profile` skill | asked | 0 until you fill it | Leave the seeded text untouched |
-| `opencode.json` entries | `instructions` points OpenCode at `AGENT.md`. `permission.bash` makes OpenCode ask before `rm -rf`, a force-push, `reset --hard`, `clean -f`, `branch -D` or `checkout --`, and before every commit and push when the **process** pack is on | enforced | No tokens | Edit the `permission` block yourself. The commit/push questions follow the **process** pack |
+| `opencode.json` entries | `instructions` points OpenCode at `AGENT.md`. `permission.bash` makes OpenCode ask before `rm -rf`, a force-push, `reset --hard`, `clean -f`, `branch -D` or `checkout --`, and before every commit and push when the **process** pack is on. `permission.skill` denies each user-only skill, so the model never starts it but `/name` still runs it; Geneseed takes back only the denies it wrote | enforced | No tokens | Edit the `permission` block yourself. The commit/push questions follow the **process** pack |
 | context plugin | Puts your repo's README, CONTRIBUTING and a listing of `docs/` in front of the agent, with your rules, profile, memory index and wiki | automatic | Your docs, capped at 16 KB a file and 48 KB a session | `GENESEED_CONTEXT_INJECT=off` |
-| guard plugin | Blocks writes to key and credential files (`id_rsa`, `.pem`, `.ssh/`…), catastrophic commands (`rm -rf /`, formatting a disk), and changes inside your wiki's protected folders. Refuses the first write to `user-rules.md` or memory once, so the choice is yours | enforced | No tokens | `GENESEED_GUARD=off`, or `GENESEED_GUARD=warn` to log instead of block |
+| guard plugin | Blocks writes to key and credential files (`id_rsa`, `.pem`, `.ssh/`…), catastrophic commands (`rm -rf /`, formatting a disk), a recursive scan of a whole filesystem (`find /`), and changes inside your wiki's protected folders. Refuses the first write to `user-rules.md` or memory once, so the choice is yours | enforced | No tokens | `GENESEED_GUARD=off`, or `GENESEED_GUARD=warn` to log instead of block |
 | learn plugin | Once a session has been quiet for 60 seconds, distils durable facts into `memory/` with the model the session already uses | automatic | One model call per quiet session | `geneseed exclude add <folder>` silences it in that folder |
 | activity plugin | Writes one small file per session that the web console's Activity view shows | automatic | No tokens | `GENESEED_ACTIVITY=off` |
 | notify plugin | A desktop notification when a turn took longer than 30 seconds | automatic | No tokens | `GENESEED_NOTIFY=off` |

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.19.0"
+  "version": "4.0.0"
 }

package/js/build/driver.mjs

@@ -47,7 +47,7 @@ import { relPosix } from '../lib/text.mjs';
 // find a global install, and a resolver that decides WHERE a driver writes is the last thing
 // that should exist twice. golden.py's 259 cells are what made the move safe to attempt.
 import {
-  GLOBAL_MANIFEST, resolvePath, opencodeConfigDir, claudeConfigDir, bobConfigDir,
+  GLOBAL_MANIFEST, HOSTS, resolvePath, opencodeConfigDir, claudeConfigDir, bobConfigDir,
   openclaudeConfigDir, hostCatalogsNatively,
 } from '../hosts/hosts.mjs';
 
@@ -103,8 +103,9 @@ export function resolveOut(raw) {
  * `_build_global._preamble_exclude` — the `claudeMdExcludes` entry a PROJECT install writes
  * to suppress the GLOBAL preamble of the same host, or null for a host that gets none.
  *
- * `_PREAMBLE_CONFIG_DIR` has exactly one key, so only a `CLAUDE.md` carrier resolves to a
- * value: Bob's `AGENTS.md` gets null.
+ * Only a `CLAUDE.md` carrier resolves to a value — Bob's `AGENTS.md` gets null. The function
+ * branches on `host` to pick between Claude's and OpenClaude's own global config dir, so "one
+ * key" no longer describes what resolves the directory; the carrier-name rule still holds.
  *
  * Computed HERE and not in the render child, and that is the inverted boundary rule doing
  * real work rather than being restated. P3b's note on the Python original: it resolves
@@ -226,6 +227,15 @@ function readManifest(manifestPath) {
   return { existed, doc };
 }
 
+/**
+ * An OpenCode manifest's `skill_denies` — the `permission.skill` denies Geneseed itself added
+ * (see `opencodeLayer`) — or `[]` when absent or malformed, which sweeps nothing.
+ */
+function recordedDenies(doc) {
+  const d = doc && doc.skill_denies;
+  return Array.isArray(d) ? d.filter((n) => typeof n === 'string') : [];
+}
+
 /** The "+ primary agent, N command(s)" tail both OpenCode summary lines share. */
 function extrasTail(stats) {
   const extras = [...(stats.primary ? ['primary agent'] : []),
@@ -271,6 +281,7 @@ function emitOpencode(cfg, args, out) {
   // rather than deleting them. The prune set is then empty by construction.
   const { existed: manifestExisted, doc } = readManifest(manifestPath);
   const oldOwned = (doc && doc.owned) || [];
+  const oldDenies = recordedDenies(doc);
 
   const agentPathRel = relUnder(out, root);
   const agentPath = agentPathRel ? `${agentPathRel}/AGENT.md` : 'AGENT.md';
@@ -282,8 +293,9 @@ function emitOpencode(cfg, args, out) {
     {
       theme: args.theme, out, root, footprint: args.footprint,
       nativeCatalog: hostCatalogsNatively('opencode'), oldOwned, manifestExisted, agentPath,
+      oldDenies,
     });
-  const { owned, stats, cfgName } = rendered;
+  const { owned, stats, cfgName, skillDenies } = rendered;
 
   phaseLog('PRUNE');
   pruneOwned(oc, oldOwned, owned);
@@ -295,6 +307,7 @@ function emitOpencode(cfg, args, out) {
       + 'list is yours and is never touched.',
     owned: [...owned].sort(),
     scope: 'project',
+    ...(skillDenies.length ? { skill_denies: skillDenies } : {}),
   });
 
   const extra = extrasTail(stats);
@@ -318,7 +331,8 @@ function emitOpencode(cfg, args, out) {
  *     sends a path relative to the project root;
  *   - the manifest carries no `scope` and no `managed` claim set, because the one file this
  *     emit wires is never unwired by any teardown — so there is nothing to record and no
- *     VERIFY stage to re-read it.
+ *     VERIFY stage to re-read it. It does carry `skill_denies`, as the per-repo one does: the
+ *     `permission.skill` denies an uninstall takes back.
  */
 function emitOpencodeGlobal(cfg, args, out) {
   const cfgDir = args.cfgDir ?? opencodeConfigDir();
@@ -326,6 +340,7 @@ function emitOpencodeGlobal(cfg, args, out) {
 
   const { doc } = readManifest(manifestPath);
   const oldOwned = (doc && doc.owned) || [];
+  const oldDenies = recordedDenies(doc);
 
   const agentPath = path.join(cfgDir, 'AGENT.md').split(path.sep).join('/');
 
@@ -334,9 +349,9 @@ function emitOpencodeGlobal(cfg, args, out) {
     {
       theme: args.theme, cfgDir, out,
       footprint: args.footprint, nativeCatalog: hostCatalogsNatively('opencode'),
-      oldOwned, agentPath,
+      oldOwned, agentPath, oldDenies,
     });
-  const { owned, stats, memStatus, nbStatus, cfgName } = rendered;
+  const { owned, stats, memStatus, nbStatus, cfgName, skillDenies } = rendered;
 
   phaseLog('PRUNE');
   pruneOwned(cfgDir, oldOwned, owned);
@@ -347,6 +362,7 @@ function emitOpencodeGlobal(cfg, args, out) {
       + 'Do not edit; removed on re-emit. The memory and notebook '
       + 'stores are NOT listed — they are never deleted.',
     owned: [...owned].sort(),
+    ...(skillDenies.length ? { skill_denies: skillDenies } : {}),
   });
 
   const extra = extrasTail(stats);
@@ -377,9 +393,10 @@ function emitClaudeCore(cfg, args, { cfgDir, claudeMd, scope, host, out, hookOpt
     && !Array.isArray(doc.managed)) ? doc.managed : {};
 
   // RENDER + WIRE in one child's worth of work. `preambleExclude` is null for every
-  // carrier but `CLAUDE.md` — `_PREAMBLE_CONFIG_DIR` has exactly one key — so Bob's
-  // `AGENTS.md` does not resolve to one. Spelling it as a call rather than a literal is what makes that a
-  // measured `null` instead of an assumed one.
+  // carrier but `CLAUDE.md`, so Bob's `AGENTS.md` does not resolve to one; for a `CLAUDE.md`
+  // carrier it branches on `host` to pick Claude's or OpenClaude's own global config dir (see
+  // `preambleExclude`'s own docblock). Spelling it as a call rather than a literal is what
+  // makes that a measured `null` instead of an assumed one.
   const rendered = emitClaudeRender(cfg, {
     theme: args.theme, cfgDir, claudeMd, scope, host,
     out,
@@ -394,9 +411,10 @@ function emitClaudeCore(cfg, args, { cfgDir, claudeMd, scope, host, out, hookOpt
 
   phaseLog('MANIFEST');
   writeManifestAtomic(manifestPath, {
-    _comment: "Files owned by Geneseed's Claude emit. Do not edit; removed on "
+    _comment: "Files owned by Geneseed's Claude/Bob/OpenClaude emit. Do not edit; removed on "
       + 're-emit. The memory and notebook stores are NOT listed — never '
-      + 'deleted. `managed` records the CLAUDE.md block + settings.json '
+      + 'deleted. `managed` records the CLAUDE.md/AGENTS.md block + settings file '
+      + '(settings.json, or settings.local.json at PROJECT scope on Claude/OpenClaude) '
       + 'hooks so uninstall removes exactly those.',
     owned: [...owned].sort(),
     managed,
@@ -474,8 +492,14 @@ const CLAUDE_SHAPED = {
   // Everything under `.openclaude/`, the preamble included. OpenClaude reads the root CLAUDE.md
   // only when the repo has no AGENTS.md, but `.openclaude/CLAUDE.md` always; keeping the root
   // untouched also lets a Claude Code install share the repo.
+  //
+  // `carrierInLayer` reads off `HOSTS`' own column of the same name (`js/hosts/hosts.mjs`)
+  // rather than restating the literal here — `installs.mjs`'s `carriersFor` reads the SAME
+  // column to know where the deployed carrier is, and two booleans naming one fact is exactly
+  // the kind of drift this repo's docblocks keep warning about.
   openclaude: {
-    host: 'openclaude', layer: '.openclaude', carrier: 'CLAUDE.md', carrierInLayer: true,
+    host: 'openclaude', layer: '.openclaude', carrier: 'CLAUDE.md',
+    carrierInLayer: HOSTS.find((h) => h.host === 'openclaude').carrierInLayer,
     summary: (at, r) => `[geneseed] openclaude (folder) -> ${at}: .openclaude/ `
       + `(CLAUDE.md, ${r.nAgents} subagents, ${r.nSkills} skills, ${r.nHooks} hook group(s), `
       + `settings.local.json), ${r.memStatus}, ${r.nbStatus}.\n`,
@@ -746,9 +770,11 @@ function run(argv) {
   writeMarkers(markerDir, args.emit, args.footprint);
   // build() drops a .geneseed-theme in `out` for the emits that call it; the global emits
   // render into the config dir WITHOUT calling build(), so the theme is recorded here.
-  // Deliberately not written for the claude/bob/openclaude PROJECT emits — they carry none,
-  // and `_harness_setup._installed_defaults` detects those by an AGENT.md sigil scan
-  // instead. Writing one for them would change the emitted tree.
+  // Deliberately not written for the claude/bob/openclaude PROJECT emits — they carry none.
+  // Claude and Bob fall back to a sigil scan of their ROOT carrier instead
+  // (`_harness_setup._installed_defaults`); OpenClaude has no root carrier to scan, so its
+  // project theme is read off `.openclaude/CLAUDE.md` (host-narrowed `firstCarrier`, host-compat
+  // B1). Writing one for them would change the emitted tree.
   if (args.emit.endsWith('-global')) {
     try {
       writeText(path.join(markerDir, '.geneseed-theme'), `${args.theme}\n`);

package/js/build/emit-claude.mjs

@@ -1,5 +1,5 @@
 /**
- * The Claude and Bob emits — one renderer, and the settings merge that wires it in.
+ * The Claude, Bob and OpenClaude emits — one renderer, and the settings merge that wires it in.
  *
  * Split out of `emit.mjs` beside `emit-opencode.mjs`, over the shared writers in
  * `emit-common.mjs`. `claudeWire` is the half that touches a file the USER also edits, and
@@ -7,8 +7,8 @@
  */
 import path from 'node:path';
 import { VERSION_MARKER } from '../hosts/hosts.mjs';
-import { loadAgentOverrides, writeNativeLayer } from '../hosts/native.mjs';
-import { ensureAgentOverridesStub } from '../hosts/opencode.mjs';
+import { claimer, loadAgentOverrides, writeNativeLayer } from '../hosts/native.mjs';
+import { ensureAgentOverridesStub, writeAliasCommands } from '../hosts/opencode.mjs';
 import {
   managedBlockRemove, managedBlockWrite, mergeClaudeSettings,
   unwireClaudeExcludes, unwireClaudeSettings, wireClaudeExcludes,
@@ -116,12 +116,27 @@ export function emitClaudeRender(cfg, job) {
   // Bob's and OpenClaude's agents/skills use the Claude dialect verbatim.
   // `manifestExisted` is deliberately not passed: the Python does not pass it either, so
   // the pre-manifest header line is unreachable from this emit on both sides.
+  // One shared `claim` (see `claimer`): the skills/agents writer and the Bob command writer
+  // below both push into the same `owned` list, so a pre-manifest-install warning still
+  // prints once across the whole emit rather than once per writer.
+  const claim = claimer(oldOwned, cfgDir, true);
   const { nAgents, nSkills, written } = writeNativeLayer(
     items, path.join(cfgDir, 'agents'), path.join(cfgDir, 'skills'),
     loadAgentOverrides(cfgDir),
-    { host: 'claude', oldOwned, cfg: cfgDir, src: cfg.src, skillDirOf });
+    { host: 'claude', bobDialect: isBob, oldOwned, cfg: cfgDir, src: cfg.src, skillDirOf, claim });
   for (const p of written) owned.push(relPosix(cfgDir, p));
 
+  // Bob host-compat O2/R1: an alias, or a genuinely user-only skill (unverified
+  // `disable-model-invocation` support — see `bobDialect` above), gets `/<name>` through
+  // `.bob/commands/<name>.md` instead of a model-visible SKILL.md. The command layer
+  // OpenCode built for its own alias problem is exactly the right shape, reused as-is.
+  if (isBob) {
+    const commandDir = path.join(cfgDir, 'commands');
+    for (const p of writeAliasCommands(cfg, items, commandDir, claim, skillDirOf, true)) {
+      owned.push(relPosix(cfgDir, p));
+    }
+  }
+
   const memStatus = globalMemory(cfgDir, items, out, cfg.src);
   ensureMemoryIndex(path.join(cfgDir, 'memory'));
   const nbStatus = globalNotebook(cfgDir, items, out, cfg.src);
@@ -236,8 +251,8 @@ function claudeWire(job, claudeMdText, hasAgentText, doctrines = null, excludeRu
     managedBlockRemove(victim);
   }
 
-  // Hooks embed machine-absolute paths. At PROJECT scope for Claude they go into
-  // settings.local.json — the personal, untracked file — never the team-shared
+  // Hooks embed machine-absolute paths. At PROJECT scope for Claude and OpenClaude they go
+  // into settings.local.json — the personal, untracked file — never the team-shared
   // settings.json, which would hand every teammate failing hooks pointing at this machine's
   // node and this machine's checkout. (Bob documents no local variant, so it keeps
   // settings.json.)
@@ -269,8 +284,9 @@ function claudeWire(job, claudeMdText, hasAgentText, doctrines = null, excludeRu
   );
   managed.settings_hooks = managedHooks;
 
-  // Project-bypasses-global (Claude only): a PROJECT install suppresses the GLOBAL
-  // ~/.claude/CLAUDE.md while cwd is this repo, via Claude's native claudeMdExcludes.
+  // Project-bypasses-global (Claude and OpenClaude): a PROJECT install suppresses the GLOBAL
+  // ~/.claude/CLAUDE.md (or ~/.openclaude/CLAUDE.md) while cwd is this repo, via the shared
+  // claudeMdExcludes dialect.
   // Written only when this run actually emitted the project's own preamble (never
   // suppress with no replacement); GENESEED_STACK_GLOBAL=1 opts out, and a re-emit with
   // it set strips a prior exclude. Bob never gets one: its bypass is the same-named

package/js/build/emit-opencode.mjs

@@ -13,7 +13,7 @@ import {
   copyPlugins, copyWorkflows, ensureAgentOverridesStub, writeColorThemes, writeCommandLayer,
   writeAliasCommands, writePonytailCommand, writePrimaryAgent, writeTheme,
 } from '../hosts/opencode.mjs';
-import { mergeOpencodeJson } from '../hosts/settings.mjs';
+import { mergeOpencodeJson, opencodeSentinelWrite } from '../hosts/settings.mjs';
 import { isFile, readText, writeText } from '../lib/fs.mjs';
 import { relPosix } from '../lib/text.mjs';
 import { assertSourceComplete, build, phaseLog } from './bundle.mjs';
@@ -53,14 +53,14 @@ import { mkdirSync } from 'node:fs';
  */
 function opencodeLayer(cfg, items, themeName, theme, dir, owned, opts) {
   const {
-    oldOwned, manifestExisted, agentPath, wireBase, overridesDir,
+    oldOwned, manifestExisted, agentPath, wireBase, overridesDir, oldDenies = [],
   } = opts;
   ensureAgentOverridesStub(cfg, overridesDir);
   const overrides = loadAgentOverrides(overridesDir);
   // One claim for every writer below whose path lands in `owned` — see `claimer`.
   const claim = claimer(oldOwned, dir, manifestExisted);
 
-  const { nAgents, nSkills, written } = writeNativeLayer(
+  const { nAgents, nSkills, written, userOnlySkills } = writeNativeLayer(
     items, path.join(dir, 'agents'), path.join(dir, 'skills'), overrides,
     { host: 'opencode', theme, src: cfg.src, claim });
   for (const p of written) owned.push(relPosix(dir, p));
@@ -80,19 +80,32 @@ function opencodeLayer(cfg, items, themeName, theme, dir, owned, opts) {
   // Owned but not counted in `nCommands`, as an alias skill is not counted in `nSkills`.
   for (const p of writeAliasCommands(cfg, items, path.join(dir, 'command'), claim, skillDirOf)) owned.push(relPosix(dir, p));
 
-  owned.push(relPosix(dir, writeTheme(path.join(dir, 'themes'), themeName, theme)));
-  for (const p of writeColorThemes(cfg, path.join(dir, 'themes'))) owned.push(relPosix(dir, p));
+  const themeDest = writeTheme(path.join(dir, 'themes'), themeName, theme, claim);
+  if (themeDest) owned.push(relPosix(dir, themeDest));
+  for (const p of writeColorThemes(cfg, path.join(dir, 'themes'), claim)) owned.push(relPosix(dir, p));
 
-  const nPlugins = copyPlugins(cfg, path.join(dir, 'plugins'), owned);
-  const nWorkflows = copyWorkflows(cfg, path.join(dir, 'workflows'), owned);
+  const nPlugins = copyPlugins(cfg, path.join(dir, 'plugins'), owned, claim);
+  const nWorkflows = copyWorkflows(cfg, path.join(dir, 'workflows'), owned, claim);
 
-  // WIRE — the one file of this layer the user co-owns.
+  // WIRE — the one file of this layer the user co-owns. `oldDenies` is the previous manifest's
+  // `skill_denies`: the `permission.skill` denies Geneseed itself ADDED (final review — owning
+  // `skills/<name>/SKILL.md` is not owning a deny the user put on that name). `staleSkillNames`
+  // is the part of it this build no longer wants denied — the skill lost its user-only marker,
+  // or was `--exclude-skills`'d. No record (a first emit, or an older manifest) sweeps nothing.
   phaseLog('WIRE');
+  const staleSkillNames = oldDenies.filter((n) => !userOnlySkills.includes(n));
+  const wired = {};
   const cfgName = path.basename(mergeOpencodeJson(path.join(wireBase, 'opencode.json'),
-    agentPath, cfg.doctrines, cfg.excludeRules));
+    agentPath, cfg.doctrines, cfg.excludeRules, userOnlySkills, staleSkillNames, wired));
+  // The next record: Geneseed's earlier denies still wanted, plus the ones it added now. A merge
+  // that wrote nothing (`skillsAdded` unset) keeps the old record whole.
+  const skillDenies = wired.skillsAdded
+    ? [...new Set([...oldDenies.filter((n) => userOnlySkills.includes(n)), ...wired.skillsAdded])].sort()
+    : oldDenies;
 
   return {
     nAgents, nSkills, nPlugins, nWorkflows, primary, nCommands: commands.length, cfgName,
+    skillDenies,
   };
 }
 
@@ -116,6 +129,7 @@ export function emitOpencodeRender(cfg, job) {
   phaseLog('RENDER');
   const {
     theme: _theme, out, root, footprint, nativeCatalog, oldOwned, manifestExisted, agentPath,
+    oldDenies,
   } = job;
   const oc = path.join(root, '.opencode');
 
@@ -127,12 +141,12 @@ export function emitOpencodeRender(cfg, job) {
   if (isFile(agentMd)) writeText(agentMd, stripCapabilityLinks(readText(agentMd)));
 
   const owned = [];
-  const { theme, items } = renderAll(cfg, _theme);
+  const { theme, items } = renderAll(cfg, _theme, { footprint, nativeCatalog });
 
   const {
-    nAgents, nSkills, nPlugins, nWorkflows, primary, nCommands, cfgName,
+    nAgents, nSkills, nPlugins, nWorkflows, primary, nCommands, cfgName, skillDenies,
   } = opencodeLayer(cfg, items, _theme, theme, oc, owned, {
-    oldOwned, manifestExisted, agentPath, wireBase: root, overridesDir: out,
+    oldOwned, manifestExisted, agentPath, wireBase: root, overridesDir: out, oldDenies,
   });
 
   return {
@@ -141,6 +155,7 @@ export function emitOpencodeRender(cfg, job) {
       nAgents, nSkills, nPlugins, nWorkflows, nCommands, primary: !!primary,
     },
     cfgName,
+    skillDenies,
   };
 }
 
@@ -179,7 +194,7 @@ export function emitOpencodeRender(cfg, job) {
 export function emitOpencodeGlobalRender(cfg, job) {
   phaseLog('RENDER');
   const {
-    theme: themeName, cfgDir, out, footprint, nativeCatalog, oldOwned, agentPath,
+    theme: themeName, cfgDir, out, footprint, nativeCatalog, oldOwned, agentPath, oldDenies,
   } = job;
 
   // No `lawsPrefix`: the standalone laws dir sits beside AGENT.md in <cfg>, so the lean
@@ -198,13 +213,15 @@ export function emitOpencodeGlobalRender(cfg, job) {
     writeText(path.join(cfgDir, 'AGENT.md'), stripCapabilityLinks(agentText));
     owned.push('AGENT.md');
   }
+  // Co-owned, so never in `owned` — see `opencodeSentinelWrite`.
+  opencodeSentinelWrite(cfgDir);
 
   // `manifestExisted` is deliberately not passed — the Python does not pass it either, so
   // the pre-manifest header line is unreachable from this emit on both sides.
   const {
-    nAgents, nSkills, nPlugins, nWorkflows, primary, nCommands, cfgName,
+    nAgents, nSkills, nPlugins, nWorkflows, primary, nCommands, cfgName, skillDenies,
   } = opencodeLayer(cfg, items, themeName, theme, cfgDir, owned, {
-    oldOwned, agentPath, wireBase: cfgDir, overridesDir: cfgDir,
+    oldOwned, agentPath, wireBase: cfgDir, overridesDir: cfgDir, oldDenies,
   });
 
   const memStatus = globalMemory(cfgDir, items, out, cfg.src);
@@ -229,5 +246,6 @@ export function emitOpencodeGlobalRender(cfg, job) {
     memStatus,
     nbStatus,
     cfgName,
+    skillDenies,
   };
 }

package/js/build/generate.mjs

@@ -40,8 +40,8 @@ import { DEFAULT_PRESET } from '../loop/score.mjs';
 import { opencodeConfigDir, resolvePath } from '../hosts/hosts.mjs';
 import {
   EMIT_HOST_SCOPE, defaultMode, defaultPosture, defaultTheme, doctrinesForBuild,
-  excludedRulesOfDir, excludedSkillsOfDir, footprintOfDir, installState, installTargets, modeOfDir, postureOfDir,
-  readMaybe, themeOfDir, trustOfDir,
+  excludedRulesOfDir, excludedSkillsOfDir, footprintOfDir, installState, installTargets,
+  legacyProcessCarrierOfDir, modeOfDir, postureOfDir, readMaybe, themeOfDir, trustOfDir,
 } from '../hosts/installs.mjs';
 import { colorThemeFiles, colorThemeJson, PALETTE_ROLES } from '../hosts/opencode.mjs';
 import { renderAll } from './render.mjs';
@@ -201,10 +201,13 @@ export function installProfile(host, scope, root, notify = null) {
   let marker = raw === null ? '' : raw.trim();
   if (marker && (EMIT_HOST_SCOPE.get(marker) ?? ['', ''])[0] !== host) marker = '';
   const emit = marker || DEFAULT_EMIT.get(`${host} ${scope}`) || 'opencode-global';
-  const theme = themeOfDir(root) || defaultTheme();
+  // Every read-back below is narrowed to `host`'s OWN carrier (host-compat B1): in a repo
+  // shared with another Claude-style host, an un-narrowed scan answers with WHICHEVER host's
+  // carrier the shared `CARRIERS` order favours — the wrong carrier for every host but one.
+  const theme = themeOfDir(root, host) || defaultTheme();
   const footprint = footprintOfDir(root);
-  const posture = postureOfDir(root) || defaultPosture();
-  const mode = modeOfDir(root) || defaultMode();
+  const posture = postureOfDir(root, host) || defaultPosture();
+  const mode = modeOfDir(root, host) || defaultMode();
   // Read off the deployed loop skill; no config fallback — `DEFAULT_PRESET` is the engine's.
   const trust = trustOfDir(root, host) || DEFAULT_PRESET;
   // A rebuild that defaulted the pack selection would re-emit an install into a constitution
@@ -214,13 +217,13 @@ export function installProfile(host, scope, root, notify = null) {
   // `harness.config.json`: a pre-migration carrier has no marker, and resolving that silence
   // out of a machine-wide config narrows every such install on its first upgrade.
   // `doctrinesForBuild` resolves unknown to ALL packs — see its docblock.
-  const doctrines = doctrinesForBuild(root);
+  const doctrines = doctrinesForBuild(root, host);
   // The per-rule axis is preserved for the same reason and with sharper teeth: an upgrade that
   // 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);
+  const excludeRules = excludedRulesOfDir(root, host);
   // Skills left out stay left out: an upgrade that forgot them would put them all back.
-  const excludeSkills = excludedSkillsOfDir(root, notify);
+  const excludeSkills = excludedSkillsOfDir(root, notify, host);
   const out = scope === 'global' ? null : root;
   const argv = setupBuildArgs(theme, emit, out, out, footprint, posture, mode, doctrines,
     PACK_ORDER, excludeRules, trust, excludeSkills);
@@ -263,6 +266,15 @@ export function rebuildCommand(argv) {
  * defaulted any of them would silently re-emit an install into something its owner did not
  * choose — which is the same failure mode `_footprint_of_dir`'s WARN exists to prevent, at a
  * larger scale.
+ *
+ * A LEGACY CARRIER IS SKIPPED, NEVER RE-EMITTED. `installProfile` (through `doctrinesOfDir`/
+ * `excludedRulesOfDir`) no longer migrates a pre-comms carrier — it reads it as written. Calling
+ * `driverMain` on that read-back would WRITE a fresh carrier missing `comms` and still naming
+ * `process 7`/`process 8` nowhere, which deletes the one signal (`legacyProcessCarrierOfDir`)
+ * that could ever have caught it again: a permanent, silent loss, and `upgrade` reaches this
+ * same loop by shelling into `rebuild-all` (`js/maintain/update.mjs`'s `rebuildInstalls`), so
+ * fixing it once here covers both verbs. Checked BEFORE `installProfile`, so no argv is even
+ * built for it.
  */
 export async function cmdRebuildAll() {
   const rc = rebuildAll();
@@ -282,8 +294,16 @@ export function rebuildAll() {
     return 0;
   }
   const failures = [];
+  const skipped = [];
   for (const [host, scope, root] of targets) {
     const label = `${host}:${scope} (${root})`;
+    // Ask BEFORE `installProfile`: a legacy carrier must never reach `driverMain`, see above.
+    if (legacyProcessCarrierOfDir(root, host)) {
+      skipped.push(label);
+      printOut(`[rebuild-all] SKIPPED ${label}: pre-comms carrier (names 'process 8') — `
+        + 'run `geneseed setup` for it.\n');
+      continue;
+    }
     // The one replay that speaks when an excluded skill's name got older: status and the console
     // read the same profile on every refresh and stay silent.
     const p = installProfile(host, scope, root, (n) => printErr(`[rebuild-all] ${label}: ${n}\n`));
@@ -300,7 +320,16 @@ export function rebuildAll() {
       + `${failures.join(', ')}\n`);
     return 1;
   }
-  printOut(`[rebuild-all] rebuilt ${targets.length} install(s).\n`);
+  const rebuilt = targets.length - skipped.length;
+  // Skipping is protective, not a failure — same convention as the install count itself
+  // already filtering to `active` targets without flagging the inactive ones. Exit 0 as long
+  // as nothing that WAS attempted failed; the per-install SKIPPED line above is the record.
+  if (skipped.length) {
+    printOut(`[rebuild-all] rebuilt ${rebuilt} install(s), skipped ${skipped.length}: `
+      + `${skipped.join(', ')}.\n`);
+  } else {
+    printOut(`[rebuild-all] rebuilt ${rebuilt} install(s).\n`);
+  }
   return 0;
 }
 

package/js/build/source.mjs

@@ -27,6 +27,7 @@
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { DEFAULT_PRESET } from '../loop/score.mjs';
+import { blankCodeSpans } from '../lib/text.mjs';
 
 /**
  * One doctrine pack file used to be read three times per render — the survives gate and the
@@ -136,12 +137,50 @@ export function ruleCanon(src = SRC) {
   return canon;
 }
 
+/**
+ * AUTHOR NOTES — `<!-- note: ... -->`, single or multi-line, is maintainer-only prose and must
+ * never reach an agent (user decision 2026-10-11). Stripped here because `resolveRuleIds` is the
+ * one function every text file threads through before a render sees it: `readSource` in
+ * `js/build/render.mjs` for `renderFile` (every file in `src/`, including the on-disk `laws/`,
+ * `ontology/` and `doctrines/` copies and everything an INCLUDE pulls in), `registerBody` there
+ * for a posture/mode, `readPackText` here for a doctrine pack body, and `parseBrick`
+ * (`js/loop/catalog.mjs`) for a brick body, which never goes through `renderFile` at all — the
+ * loop CLI hands it to the model raw, so it calls `stripAuthorNotes` itself. One function, every
+ * reader. `js/inspect/checks-authoring.mjs`'s `authorNoteProblems` is the companion gate: it
+ * scans `src/` directly for a comment that is neither this prefix nor a known functional marker,
+ * so a new author note without the prefix is caught instead of silently shipping.
+ *
+ * MATCHED AGAINST THE BLANKED TEXT, NOT THE RAW ONE. `blankCodeSpans` (`js/lib/text.mjs`, shared
+ * with the doctor arm so the two can never disagree about what counts as "shown as an example")
+ * replaces every fenced block and inline code span with same-length whitespace, so (a) a
+ * `note:` comment that is only a literal example — a skill teaching the syntax — never matches,
+ * and (b) a real comment whose prose quotes a literal marker inside backticks (the
+ * `src/skills/_template.md` landmine: `` `<!-- invocation: user -->` `` closing the OUTER note
+ * at its own inner `-->`) is blanked there too, so the lazy `[\s\S]*?` correctly runs to the
+ * REAL closing `-->` instead of stopping at the quoted one. Blanking preserves every index and
+ * every newline, so a match found in the blanked copy is removed from the SAME range of the
+ * original — never from the blanked copy itself, which would turn the code span's blanks into
+ * removed source.
+ */
+const AUTHOR_NOTE_RE = /[ \t]*<!--[ \t]*note:[\s\S]*?-->[ \t]*\r?\n?/g;
+export function stripAuthorNotes(text) {
+  const masked = blankCodeSpans(text);
+  const ranges = [...masked.matchAll(AUTHOR_NOTE_RE)]
+    .map((m) => [m.index, m.index + m[0].length]);
+  if (!ranges.length) return text;
+  let out = '';
+  let last = 0;
+  for (const [start, end] of ranges) { out += text.slice(last, start); last = end; }
+  return out + text.slice(last);
+}
+
 /**
  * Resolve every declaration and citation in `text` against the canon under `src`. An unknown id
  * is left exactly as written — visible in the output, and named by the doctor — rather than
  * guessed at.
  */
 export function resolveRuleIds(text, src = SRC) {
+  text = stripAuthorNotes(text);
   if (!text.includes('{{LAW:') && !text.includes('{{DOCTRINE:')) return text;
   const { byId } = ruleCanon(src);
   const known = (kind, id) => { const r = byId.get(id); return r && r.kind === kind ? r : null; };

package/js/build/stubs.mjs

@@ -223,7 +223,8 @@ export function ensureContextStub(out) {
 
 /** The wiki manifest's name. `geneseed-` says who owns it in a shared `.claude/`/`.opencode/`. */
 export const WIKI_FILE = 'geneseed-wiki.jsonc';
-/** Its earlier names, newest first. Readers still fall back to them for one release. */
+/** Its earlier names, newest first. Readers still fall back to them, with no end date:
+ * nothing yet tells a user an install missed the rename, so dropping the fallback would lose a wiki in silence. */
 const LEGACY_WIKI_FILES = ['wiki.jsonc', 'wiki.json'];
 
 /**