geneseed 3.17.0 → 3.19.0

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`, and writes to a check listed in the project's `.geneseed/protected-checks.txt` (*External Gate* — see [Hooks](../concepts/hooks.md)).
+- **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 `geneseed-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

@@ -4,9 +4,9 @@ What a deployed harness costs in context-window tokens, per host. Token counts a
 chars/4 estimates and shift a little with theme and version.
 
 **Treat every number below as a floor, not a reading.** They were measured on
-2026-09-12 on a `--footprint lean` build (the default) of the neutral theme with
-four doctrine packs, 54 skills and 19 agents, and nothing re-measures this page
-automatically. For a
+2026-10-08 on a `--footprint lean` build (the default) of the neutral theme with
+the default doctrine packs, 47 skills (plus 12 alias stubs) and 18 agents, and nothing
+re-measures this page automatically. For a
 live figure on your own install, ask the agent for the `token-report` skill —
 that is what it is for. A `--footprint full` build runs roughly 5k tokens
 heavier on the root file.
@@ -17,21 +17,21 @@ The context every host injects at session start, before you type anything:
 
 | Component | Claude Code | OpenCode | Bob |
 |---|---|---|---|
-| Root instruction file | ~7.2k (`CLAUDE.md`) | ~7.2k (`AGENT.md`) | ~7.5k (`AGENTS.md`, §3 table inline) |
-| Skill metadata (name + description) | ~4.1k | ~4.1k | ~4.1k (native) |
-| Agent metadata | ~0.5k | ~0.5k | — (no agents directory) |
+| Root instruction file | ~7.7k (`CLAUDE.md`) | ~7.6k (`AGENT.md`) | ~8.0k (`AGENTS.md`, §3 table inline) |
+| Skill metadata (name + description) | ~3.0k | ~3.0k | ~3.0k (native) |
+| Agent metadata | ~1.0k | ~1.0k | — (in the root's §3 table) |
 | Session files (rules, profile, Memory/Notebook indexes, wiki) | 0 fresh, grows with use (SessionStart hook) | 0 fresh, grows with use (context plugin) | 0 fresh, grows with use (SessionStart hook) |
-| **Total** | **~12k** | **~12k** | **~12k** |
+| **Total** | **~12k** | **~12k** | **~11k** |
 
 The emits are at parity by design: ~12k tokens, about 6% of a 200k
-window. Bob catalogues skills natively but has no agents directory, so its
+window. Bob catalogues skills natively but not agents, so its
 root keeps the §3 Agents table and drops the §4 Skills table — the catalogue
 flag is per kind (`hostCatalogsNatively`), not one boolean. Before the 2026-09 footprint pass every hooked host paid roughly double
 this: the context hook re-injected the root file the host had already loaded
 natively, and skill descriptions ran to 900 characters each — see the
-"Where the tokens go" list below for what changed. Bob carries the §3/§4 catalogue tables inline because its host exposes
-no native skill/agent inventory; Claude Code and OpenCode ship a
-pointer to the host's own inventory instead, ~1.9k tokens lighter. A session file still
+"Where the tokens go" list below for what changed. Bob carries the §3 Agents table inline because its host exposes
+no native agent inventory; Claude Code and OpenCode ship a
+pointer to the host's own inventory instead, ~0.3k tokens lighter. A session file still
 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
@@ -85,15 +85,18 @@ until 2026-09 it did, and the whole harness was paid twice per session.
   "dispatched agents never commit or push"), and the folder-Skill list, which
   now sits in the §4 catalogue half and so drops wherever the host catalogues
   Skills natively.
-- **Skill bodies (~53k) and agent bodies (~10k) are lazy** on every host —
+- **Skill bodies (~54k) and agent bodies (~14k) are lazy** on every host —
   loaded only when invoked. A typical skill costs ≤3k per invocation; the
-  heaviest (`react-view-transitions`, ~17.5k with its reference files) loads
+  heaviest (`react-view-transitions`, ~20k with its reference files) loads
   its references progressively.
 - **User-only skills leave the catalogue.** A skill whose source carries
   `<!-- invocation: user -->` renders `disable-model-invocation: true`; Claude
   Code and Bob then drop its description from the always-on skill metadata and
-  only `/name` opens it. Seven skills carry it today (the five teaching drills,
-  `herdr`, `opencode-theme`), roughly a seventh of the ~1.7k skill-metadata line.
+  only `/name` opens it. The three teaching skills (`teach`, `quiz`, `learn-mode`)
+  and `herdr` carry it today.
+- **Aliases cost 0 always-on.** A merged skill's old names (`<!-- aliases: -->`)
+  ship as user-only stubs on Claude Code, Bob and OpenClaude, and as `/name` commands
+  on OpenCode — never in the model's catalogue, so a rename or merge is free.
 - Plugin JavaScript (OpenCode, ~26k on disk) runs in the host runtime and
   never enters the context window.
 

package/docs/understand/take-it-out.md

@@ -6,7 +6,7 @@ kind: "concept"
 section: "On your machine"
 description: "What geneseed uninstall removes, and what it keeps for you."
 ---
-`geneseed uninstall` removes only what Geneseed recorded writing: the rules file or its managed block, `agents/`, `skills/`, plugins, and Geneseed's own hook and config entries. It keeps `memory/` and `notebook/` in place, along with the files it seeded for you to edit (`user-rules.md`, `PROFILE.md`, `wiki.jsonc`). Add `--archive-memory` to move memory and notebook aside instead. It still deletes nothing. See [Uninstall](../guides/uninstall.md).
+`geneseed uninstall` removes only what Geneseed recorded writing: the rules file or its managed block, `agents/`, `skills/`, plugins, and Geneseed's own hook and config entries. It keeps `memory/` and `notebook/` in place, along with the files it seeded for you to edit (`user-rules.md`, `PROFILE.md`, `geneseed-wiki.jsonc`). Add `--archive-memory` to move memory and notebook aside instead. It still deletes nothing. See [Uninstall](../guides/uninstall.md).
 
 ---
 

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.17.0"
+  "version": "3.19.0"
 }

package/js/README.md

@@ -1,6 +1,6 @@
 # `js/` — the module map
 
-Sixty-six modules in eight folders. This page is the address book: **what each one owns**, and
+Sixty-nine modules in eight folders. This page is the address book: **what each one owns**, and
 **which file to open first** for a given task. It is not documentation of behaviour — every module
 has a docblock for that, and the docblock is the thing to read before editing.
 
@@ -109,6 +109,9 @@ Everything that inspects an already-built or already-deployed harness and report
 | `diff.mjs` | `geneseed diff` — what a deployed install has that a fresh render of `src/` does not |
 | `excludes.mjs` | `geneseed exclude add|remove|list` — the WRITER for `excludes.json`; `hooks.mjs` only reads it |
 | `registry.mjs` | `installs.json` under XDG — the persistent deploy-root list `rebuild-all` re-emits into |
+| `scorecard.mjs` | `geneseed scorecard` — a port of the AI Harness Scorecard (upstream pinned in its docblock): the repo walk, the CI-YAML subset parser, `assessRepo`, the text/JSON renderers. Pure: no spawn, no network |
+| `scorecard-svg.mjs` | The scorecard as an SVG card for a README (`geneseed scorecard --svg`): grade plus one bar per pillar, deterministic so doctor can compare the committed card byte for byte |
+| `scorecard-checks.mjs` | The scorecard's 31 checks in five pillars, ported line for line — ids, points, partial scores, evidence and fixes as upstream writes them |
 
 **Before editing:** every check returns an array of problem strings, empty when clean — and since
 deleting any check leaves a clean run **byte-identical**, each one is gated by a PLANTED FAULT, not

package/js/build/args.mjs

@@ -11,7 +11,7 @@ import { parseArgs as nodeParseArgs } from 'node:util';
 import { withPlatformNewlines } from '../lib/fs.mjs';
 import path from 'node:path';
 import {
-  CONFIG, discoverNames, PACK_ORDER, knownRuleIds, knownSkillIds, linkedSkillIds,
+  CONFIG, discoverNames, PACK_ORDER, knownRuleIds, knownSkillIds, linkedSkillIds, resolveSkillNames,
 } 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.
@@ -180,30 +180,36 @@ function parseExcludeRules(value) {
 }
 
 /**
- * `--exclude-skills "bruno-test-writer,openscad"` -> the cfg's skill exclusion array.
+ * `--exclude-skills "bruno,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.
+ *
+ * An OLD name is not a typo, and is never refused: `upgrade` and `rebuild-all` replay an
+ * install's `Excluded skills:` line through this flag, so a name that became an alias or was
+ * retired after the install was made would otherwise break every rebuild of it. Those go
+ * through `resolveSkillNames` and leave one stderr line each; the linked refusal stays for a
+ * name typed as itself.
  */
 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);
+  const names = s.split(',').map((x) => x.trim()).filter(Boolean);
+  const { ids, notices, unknown } = resolveSkillNames(names, { known, linked });
+  if (unknown.length) {
+    die(2, `argument --exclude-skills: unknown skill '${unknown[0]}' (choose from `
+      + `${known.filter((k) => !linked.includes(k)).join(', ')}, or 'none')`);
   }
-  return [...new Set(out)].sort();
+  const protectedName = names.find((n) => linked.includes(n));
+  if (protectedName) {
+    die(2, `argument --exclude-skills: '${protectedName}' cannot be excluded — the harness links `
+      + `to it by path (protected: ${linked.join(', ')})`);
+  }
+  for (const n of notices) process.stderr.write(`[geneseed] --exclude-skills: ${n}\n`);
+  return ids;
 }
 
 /**
@@ -315,9 +321,7 @@ export function parseArgs(argv, defaults) {
       // `main`'s catch is what turns either into this process's exit status. A bare
       // `process.exit(0)` here would be the P5f bug in reverse — it takes `rebuild-all`'s
       // loop with it, and skips the stdout flush the text was just written to.
-      const e = new Error('help');
-      e.exitCode = 0;
-      throw e;
+      throw Object.assign(new Error('help'), { exitCode: 0 });
     }
     if (tok.kind === 'option' && VALUED_BY_NAME[tok.name] !== undefined) {
       if (tok.value === undefined) die(2, `argument ${tok.rawName}: expected one argument`);
@@ -400,7 +404,5 @@ function choice(flag, value, allowed) {
  */
 export function die(code, msg) {
   process.stderr.write(`geneseed: error: ${msg}\n`);
-  const e = new Error(msg);
-  e.exitCode = code;
-  throw e;
+  throw Object.assign(new Error(msg), { exitCode: code });
 }

package/js/build/bundle.mjs

@@ -65,9 +65,7 @@ export function assertSourceComplete(cfg, context = '') {
     + 'and a global re-emit would delete the good copies in an existing install.\n'
     + '[geneseed] ✗ Re-sync the source (./geneseed update, or re-run the upgrade) '
     + 'and try again.\n');
-  const e = new Error('source is incomplete');
-  e.exitCode = 1;
-  throw e;
+  throw Object.assign(new Error('source is incomplete'), { exitCode: 1 });
 }
 
 // ---------------------------------------------------------------------------

package/js/build/emit-claude.mjs

@@ -24,7 +24,7 @@ import { renderAll, renderFile } from './render.mjs';
 import {
   BOB_RULES_STUB, ensureContextStub, ensureExcludesStub, ensureMemoryIndex, ensureNotebookIndex,
   ensureProfileStub,
-  ensureRulesStub, ensureWikiStub,
+  ensureRulesStub, ensureWikiStub, WIKI_FILE,
 } from './stubs.mjs';
 import { writeVersion } from './version.mjs';
 import { existsSync, mkdirSync } from 'node:fs';
@@ -108,10 +108,11 @@ export function emitClaudeRender(cfg, job) {
   // Bob gives the model a skill's text but not its directory, so a folder skill's
   // `<this-skill-directory>` is resolved here. Per repo it is relative to the workspace root,
   // where Bob runs commands, so a committed `.bob/` stays valid on a teammate's checkout;
-  // globally there is no workspace to be relative to, so it is absolute.
+  // globally there is no workspace to be relative to, so it is absolute — and `/`-separated,
+  // like the `/<file>` a pointer appends, so one path never mixes both separators.
   const skillDirOf = !isBob ? null
     : scope === 'project' ? (name) => relPosix(path.dirname(cfgDir), path.join(cfgDir, 'skills', name))
-      : (name) => path.join(cfgDir, 'skills', name);
+      : (name) => path.join(cfgDir, 'skills', name).split(path.sep).join('/');
   // 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.
@@ -142,7 +143,7 @@ export function emitClaudeRender(cfg, job) {
     const gi = path.join(cfgDir, '.gitignore');
     const giLines = (host === 'claude' || host === 'openclaude' ? ['settings.local.json']
       : host === 'bob' ? ['settings.json'] : [])
-      .concat(['context.json', 'wiki.jsonc', 'agent-overrides.json']);
+      .concat(['context.json', WIKI_FILE, 'agent-overrides.json']);
     if (!existsSync(gi)) {
       writeText(gi, `${giLines.join('\n')}\n`);
       owned.push('.gitignore');

package/js/build/emit-opencode.mjs

@@ -11,7 +11,7 @@ import { VERSION_MARKER } from '../hosts/hosts.mjs';
 import { claimer, loadAgentOverrides, writeNativeLayer } from '../hosts/native.mjs';
 import {
   copyPlugins, copyWorkflows, ensureAgentOverridesStub, writeColorThemes, writeCommandLayer,
-  writePonytailCommand, writePrimaryAgent, writeTheme,
+  writeAliasCommands, writePonytailCommand, writePrimaryAgent, writeTheme,
 } from '../hosts/opencode.mjs';
 import { mergeOpencodeJson } from '../hosts/settings.mjs';
 import { isFile, readText, writeText } from '../lib/fs.mjs';
@@ -68,10 +68,17 @@ function opencodeLayer(cfg, items, themeName, theme, dir, owned, opts) {
   const primary = writePrimaryAgent(cfg, path.join(dir, 'agents'), overrides, claim);
   if (primary) owned.push(relPosix(dir, primary));
 
-  const commands = writeCommandLayer(cfg, items, path.join(dir, 'command'), claim);
+  // Where a command's side-file pointer says the skill lives — Bob's rule (`emitClaudeRender`):
+  // per repo relative to the workspace root, so a committed `.opencode/` holds on a teammate's
+  // checkout; globally (`wireBase` IS `dir`) absolute.
+  const skillDirOf = wireBase === dir ? (n) => path.join(dir, 'skills', n).split(path.sep).join('/')
+    : (n) => relPosix(wireBase, path.join(dir, 'skills', n));
+  const commands = writeCommandLayer(cfg, items, path.join(dir, 'command'), claim, skillDirOf);
   const ponytail = writePonytailCommand(path.join(dir, 'command'), claim);   // always-on /ponytail
   if (ponytail) commands.push(ponytail);
   for (const p of commands) owned.push(relPosix(dir, p));
+  // 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));

package/js/build/generate.mjs

@@ -66,9 +66,7 @@ function sysExit(msg) {
   // transport hole P5b measured. A second copy of a translation is exactly what P5d's
   // `pyStrPath`/`toPlatformPath` split was, and it is ungated in precisely the same way.
   printErr(`${msg}\n`);
-  const e = new Error(msg);
-  e.exitCode = 1;
-  throw e;
+  throw Object.assign(new Error(msg), { exitCode: 1 });
 }
 
 // --------------------------------------------------------------------------------------
@@ -198,7 +196,7 @@ const DEFAULT_EMIT = new Map([
  * host's row would otherwise rebuild with the WRONG emit — turning a Claude install into an
  * OpenCode one. `rebuild-all/a-dual-host-repo-rebuilds-each-row-in-its-own-emit` is the cell.
  */
-export function installProfile(host, scope, root) {
+export function installProfile(host, scope, root, notify = null) {
   const raw = readMaybe(path.join(root, '.geneseed-emit'));
   let marker = raw === null ? '' : raw.trim();
   if (marker && (EMIT_HOST_SCOPE.get(marker) ?? ['', ''])[0] !== host) marker = '';
@@ -222,7 +220,7 @@ export function installProfile(host, scope, root) {
   // 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 excludeSkills = excludedSkillsOfDir(root, notify);
   const out = scope === 'global' ? null : root;
   const argv = setupBuildArgs(theme, emit, out, out, footprint, posture, mode, doctrines,
     PACK_ORDER, excludeRules, trust, excludeSkills);
@@ -285,8 +283,10 @@ export function rebuildAll() {
   }
   const failures = [];
   for (const [host, scope, root] of targets) {
-    const p = installProfile(host, scope, root);
     const label = `${host}:${scope} (${root})`;
+    // 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`));
     printOut(`[rebuild-all] ${label}: theme=${p.theme} emit=${p.emit} footprint=${p.footprint} `
       + `posture=${p.posture} mode=${p.mode}\n`);
     const rc = driverMain(p.argv);

package/js/build/render.mjs

@@ -131,9 +131,7 @@ export function loadTheme(cfg, name) {
     // marker — an unvalidated file in a user's install. A bare `throw` there printed a Node
     // stack trace where Python printed one line, and the acceptance matrix is what said so.
     process.stderr.write(`[geneseed] unknown theme '${name}'. available: ${available}\n`);
-    const e = new Error(`unknown theme '${name}'`);
-    e.exitCode = 1;
-    throw e;
+    throw Object.assign(new Error(`unknown theme '${name}'`), { exitCode: 1 });
   }
   // parseJson, not JSON.parse: one rule for every JSON the generator reads, so a numeric
   // theme value keeps the int/float distinction Python's `str()` and `repr()` render
@@ -247,7 +245,17 @@ function readSource(cfg, p) {
   return text;
 }
 
-/** `_build_render.render_file`. */
+/**
+ * `_build_render.render_file`.
+ *
+ * @param {any} cfg
+ * @param {string} filePath
+ * @param {any} theme
+ * @param {string} [footprint]
+ * @param {string} [lawsPrefix]
+ * @param {Set<string>} [visiting]
+ * @param {boolean | { skills?: boolean, agents?: boolean }} [nativeCatalog]
+ */
 export function renderFile(cfg, filePath, theme, footprint = 'full', lawsPrefix = '',
                            visiting = new Set(), nativeCatalog = false) {
   const here = path.resolve(filePath);
@@ -309,19 +317,15 @@ function activeDoctrines(cfg) {
     : [];
   const stray = onDisk.filter((n) => !PACK_ORDER.includes(n));
   if (stray.length) {
-    const e = new Error(`doctrine pack file(s) ${stray.join(', ')} exist under src/doctrines/ `
+    throw Object.assign(new Error(`doctrine pack file(s) ${stray.join(', ')} exist under src/doctrines/ `
       + 'but are missing from PACK_ORDER (js/build/source.mjs) — add them there, or they render '
-      + 'into no install at all');
-    e.exitCode = 1;
-    throw e;
+      + 'into no install at all'), { exitCode: 1 });
   }
   const wanted = cfg.doctrines ?? PACK_ORDER;
   for (const name of wanted) {
     if (!onDisk.includes(name)) {
-      const e = new Error(`doctrine pack '${name}' is selected but src/doctrines/${name}.md `
-        + `does not exist (packs on disk: ${onDisk.join(', ') || 'none'})`);
-      e.exitCode = 1;
-      throw e;
+      throw Object.assign(new Error(`doctrine pack '${name}' is selected but src/doctrines/${name}.md `
+        + `does not exist (packs on disk: ${onDisk.join(', ') || 'none'})`), { exitCode: 1 });
     }
   }
   // ⚠ A PACK WHOSE EVERY RULE IS EXCLUDED IS NOT A PACK, it is a heading over nothing. The
@@ -480,6 +484,9 @@ export function destRel(rel) {
  * themed POSIX output path, `text` is the rendered text or `null` for a binary that the
  * caller copies from `src`. Python returns a tuple of tuples; the object form is the
  * same data with the field names the Python docstring already uses.
+ * @param {any} cfg
+ * @param {string} themeName
+ * @param {{ footprint?: string, lawsPrefix?: string, nativeCatalog?: boolean | { skills?: boolean, agents?: boolean } }} [opts]
  */
 export function renderAll(cfg, themeName, {
   footprint = 'full', lawsPrefix = '', nativeCatalog = false,

package/js/build/source.mjs

@@ -89,6 +89,7 @@ export const RETIRED_RULE_IDS = {
   'absence-is-a-claim': { was: 'Law XI', liveAs: null, note: 'folded into verify-before-asserting' },
 };
 
+/** @type {Array<[number, string]>} */
 const ROMAN = [[1000, 'M'], [900, 'CM'], [500, 'D'], [400, 'CD'], [100, 'C'], [90, 'XC'],
   [50, 'L'], [40, 'XL'], [10, 'X'], [9, 'IX'], [5, 'V'], [4, 'IV'], [1, 'I']];
 export function toRoman(n) {
@@ -194,7 +195,7 @@ export function discoverNames(dir, first) {
       .map((f) => path.basename(f, '.md'))
       .sort();
   } catch { /* missing dir — fall through to the single default below */ }
-  names.sort((a, b) => (a !== first) - (b !== first) || (a < b ? -1 : a > b ? 1 : 0));
+  names.sort((a, b) => Number(a !== first) - Number(b !== first) || (a < b ? -1 : a > b ? 1 : 0));
   return names.length ? names : [first];
 }
 
@@ -241,11 +242,12 @@ export function knownRuleIds() {
  * skills) or a vendored `skills/<name>/` folder. The one enumerator `--exclude-skills` closes
  * against, for the reason `knownRuleIds` is one.
  */
-export function knownSkillIds() {
-  const dir = path.join(SRC, 'skills');
-  return readdirSync(dir, { withFileTypes: true })
+export function knownSkillIds(src = SRC) {
+  const dir = path.join(src, 'skills');
+  // A Set: a skill with side files is both `debug.md` and `debug/`.
+  return [...new Set(readdirSync(dir, { withFileTypes: true })
     .filter((e) => !e.name.startsWith('_') && (e.isDirectory() || e.name.endsWith('.md')))
-    .map((e) => e.name.replace(/\.md$/, '')).sort();
+    .map((e) => e.name.replace(/\.md$/, '')))].sort();
 }
 
 /**
@@ -253,7 +255,7 @@ export function knownSkillIds() {
  * outside the §4 catalogue table. They cannot be excluded: the link would ship dead. Scanned,
  * not listed, so a new link protects its target the day it is written.
  */
-export function linkedSkillIds() {
+export function linkedSkillIds(src = SRC) {
   const linked = new Set();
   const walk = (d) => {
     for (const e of readdirSync(d, { withFileTypes: true })) {
@@ -266,10 +268,83 @@ export function linkedSkillIds() {
       }
     }
   };
-  walk(SRC);
+  walk(src);
   return [...linked].sort();
 }
 
+/**
+ * OLD NAMES KEEP WORKING. When skills merge, the absorbed names live on as aliases, declared in
+ * the surviving spec on a line of their own — `<!-- aliases: deps-audit, migrate -->` — beside
+ * `<!-- invocation: user -->`, for the same reason: a phrase in the spec, not a second manifest
+ * to keep in step. Anchored to a whole line so a skill that merely QUOTES the syntax in its
+ * prose declares nothing. The emit turns each alias into a user-only `/alias` that runs the
+ * target's body (`writeNativeLayer`, `writeAliasCommands`); `--exclude-skills` maps an alias to
+ * its target (`resolveSkillNames`); the doctor keeps the namespace clean (`aliasProblems`).
+ */
+export const ALIASES_RE = /^<!--[ \t]*aliases:[ \t]*(.+?)[ \t]*-->[ \t]*\r?$/m;
+export function aliasesOf(text) {
+  const m = ALIASES_RE.exec(text);
+  return m ? m[1].split(',').map((s) => s.trim()).filter(Boolean) : [];
+}
+
+/** Every declared alias -> the skill that declares it. First declaration wins; the doctor names a duplicate. */
+export function skillAliases(src = SRC) {
+  const map = new Map();
+  const dir = path.join(src, 'skills');
+  for (const f of readdirSync(dir).filter((n) => n.endsWith('.md') && !n.startsWith('_')).sort()) {
+    for (const a of aliasesOf(readFileSync(path.join(dir, f), 'utf8'))) {
+      if (!map.has(a)) map.set(a, f.slice(0, -3));
+    }
+  }
+  return map;
+}
+
+/**
+ * Skill names that were REMOVED outright — no successor to alias them to. Kept because an
+ * install's `Excluded skills:` line outlives the skill: `upgrade` and `rebuild-all` replay it
+ * through `--exclude-skills`, and a name the checkout no longer knows would otherwise refuse
+ * the whole rebuild. A retired name is dropped with a notice instead (excluding a skill that
+ * no longer ships is already true), and the doctor refuses it as a new skill or alias name, so
+ * it never comes back meaning something else — `RETIRED_RULE_IDS`' contract, for skills.
+ */
+export const RETIRED_SKILL_IDS = {
+  tickets: 'removed in the 2026-10 sharpen; plan slices the work now',
+};
+
+/**
+ * `--exclude-skills` names -> what this checkout can exclude, without ever dying on a name that
+ * merely got OLDER. A skill id passes; an alias maps to its target (excluding the merged skill
+ * is what excluding its old half meant); a retired name is dropped. An alias whose target the
+ * harness links to by path is dropped too — the old exclusion cannot be honoured, and refusing
+ * it would break every replay of an install that was valid when it was made. Only `unknown`
+ * (never shipped under any name) is the caller's to refuse. Pure: the tables arrive as
+ * arguments and the notices go back to the caller, so a reader that runs on every status call
+ * can stay silent while the flag speaks.
+ */
+export function resolveSkillNames(names, {
+  known = knownSkillIds(), aliases = skillAliases(), retired = RETIRED_SKILL_IDS, linked = null,
+} = {}) {
+  const ids = [];
+  const notices = [];
+  const unknown = [];
+  for (const name of names) {
+    if (known.includes(name)) ids.push(name);
+    else if (aliases.has(name)) {
+      const target = aliases.get(name);
+      linked ??= linkedSkillIds();
+      if (linked.includes(target)) {
+        notices.push(`'${name}' is now part of '${target}', which cannot be excluded — exclusion dropped`);
+      } else {
+        notices.push(`'${name}' is now part of '${target}' — excluding '${target}'`);
+        ids.push(target);
+      }
+    } else if (Object.hasOwn(retired, name)) {
+      notices.push(`'${name}' no longer ships (${retired[name]}) — exclusion dropped`);
+    } else unknown.push(name);
+  }
+  return { ids: [...new Set(ids)].sort(), notices, unknown };
+}
+
 /**
  * `_build_core.js_cfg()`, originated rather than received.
  *

package/js/build/stubs.mjs

@@ -12,7 +12,7 @@ import { writeText } from '../lib/fs.mjs';
 import { isDir } from '../lib/fs.mjs';
 import { jsonDumpsIndent } from '../lib/json.mjs';
 import { EXCLUDES_FILE } from '../hosts/hosts.mjs';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 
 // ---------------------------------------------------------------------------
 // Seeded stubs. Written once into the bundle and NEVER overwritten — each holds
@@ -34,7 +34,7 @@ const CONTEXT_STUB = {
 
 /** `_build_render.WIKI_STUB`. */
 const WIKI_STUB = `\
-// Geneseed wiki.jsonc — declare your machine-wide knowledge base(s) here, typically
+// geneseed-wiki.jsonc — declare your machine-wide knowledge base(s) here, typically
 // an Obsidian vault (AGENT.md: the Wiki section). Comments are allowed in this file
 // (JSONC). It is host-specific — never commit it. The build created it once, empty,
 // and will never overwrite it.
@@ -183,7 +183,8 @@ const BUNDLE_GITIGNORE = `\
 context.json
 
 # Knowledge-base manifest — holds private machine paths; never commit.
-# (wiki.json is the legacy name from earlier seeds.)
+# (wiki.jsonc and wiki.json are its legacy names from earlier seeds.)
+geneseed-wiki.jsonc
 wiki.jsonc
 wiki.json
 
@@ -220,9 +221,37 @@ export function ensureContextStub(out) {
   seed(path.join(out, 'context.json'), `${jsonDumpsIndent(CONTEXT_STUB, { ensureAscii: false })}\n`);
 }
 
-/** `_build_render.ensure_wiki_stub` — a legacy `wiki.json` counts as present. */
+/** 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. */
+const LEGACY_WIKI_FILES = ['wiki.jsonc', 'wiki.json'];
+
+/**
+ * `_build_render.ensure_wiki_stub`, plus the rename. A legacy manifest is the user's file: it is
+ * RENAMED to `WIKI_FILE` (bytes preserved by construction), never copied and never seeded beside.
+ * A rename that fails (the file held open on Windows) leaves it where it is and seeds nothing —
+ * a seed beside it would fork the user's declarations; the readers' fallback still finds it.
+ * The sibling `.gitignore` follows the rename, or the private paths become committable.
+ */
 export function ensureWikiStub(out) {
-  if (!existsSync(path.join(out, 'wiki.json'))) seed(path.join(out, 'wiki.jsonc'), WIKI_STUB);
+  const dest = path.join(out, WIKI_FILE);
+  if (existsSync(dest)) return;
+  const legacy = LEGACY_WIKI_FILES.find((n) => existsSync(path.join(out, n)));
+  if (!legacy) return seed(dest, WIKI_STUB);
+  try { renameSync(path.join(out, legacy), dest); } catch { return; }
+  ignoreRenamedWiki(path.join(out, '.gitignore'), legacy);
+}
+
+/** Add `WIKI_FILE` to a `.gitignore` that ignores the legacy name and not the new one, in the
+ * file's own line ending. Anything else — no file, no legacy line — is left alone. */
+function ignoreRenamedWiki(gi, legacy) {
+  let text;
+  try { text = readFileSync(gi, 'utf8'); } catch { return; }
+  const lines = text.split(/\r?\n/);
+  if (!lines.includes(legacy) || lines.includes(WIKI_FILE)) return;
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  const sep = text.endsWith('\n') ? '' : eol;
+  writeFileSync(gi, `${text}${sep}${WIKI_FILE}${eol}`);
 }
 
 /** `_build_render.ensure_rules_stub`. */
@@ -264,7 +293,7 @@ export const ensureNotebookIndex = storeIndexWriter('NOTEBOOK.md', NOTEBOOK_INDE
  * the two copies must move with it.
  */
 export const SESSION_SEEDS = {
-  'user-rules.md': RULES_STUB, 'PROFILE.md': PROFILE_STUB, 'wiki.jsonc': WIKI_STUB,
+  'user-rules.md': RULES_STUB, 'PROFILE.md': PROFILE_STUB, [WIKI_FILE]: WIKI_STUB,
   'MEMORY.md': MEMORY_INDEX, 'NOTEBOOK.md': NOTEBOOK_INDEX,
 };
 

package/js/build/themes.mjs

@@ -144,9 +144,7 @@ export function syncThemes(themesDir = THEMES) {
   } catch {
     process.stdout.write(`[sync-themes] ${path.basename(tmplPath)} is missing or unreadable `
       + '— there is nothing to sync against.\n');
-    const e = new Error('template unreadable');
-    e.exitCode = 2;
-    throw e;
+    throw Object.assign(new Error('template unreadable'), { exitCode: 2 });
   }
   const tmplKeys = Object.keys(tmpl);
   let changed = 0;