geneseed 3.17.0 → 3.18.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;

package/js/cli-table.json

@@ -1079,6 +1079,59 @@
       ],
       "mutex": []
     },
+    {
+      "name": "scorecard",
+      "help": "grade a repo with the AI Harness Scorecard (31 checks, five pillars) — scores the repo itself (CI, tests, docs), not the harness files; a reading, never a gate",
+      "description": "",
+      "positionals": [
+        {
+          "names": [],
+          "dest": "path",
+          "metavar": null,
+          "help": "the repo to score (default: the current directory)",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": "?",
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        }
+      ],
+      "options": [
+        {
+          "names": [
+            "--json"
+          ],
+          "dest": "json",
+          "metavar": null,
+          "help": "print the full assessment as JSON — every check with its score, evidence and fix",
+          "choices": null,
+          "default": false,
+          "required": false,
+          "nargs": "0",
+          "is_flag": true,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": [
+            "--svg"
+          ],
+          "dest": "svg",
+          "metavar": "PATH",
+          "help": "write the scorecard as an SVG card (grade + one bar per pillar) to PATH instead of printing — the README card is docs/assets/scorecard.svg",
+          "choices": null,
+          "default": null,
+          "required": false,
+          "nargs": null,
+          "is_flag": false,
+          "type": null,
+          "hidden": false
+        }
+      ],
+      "mutex": []
+    },
     {
       "name": "setup",
       "help": "interactive install wizard (dependency-free, all OSes)",

package/js/hosts/hooks-context.mjs

@@ -81,8 +81,8 @@ let HOST = 'claude';
 // Kept in step with adapters/opencode/plugins/geneseed-context.js.
 const EAGER_ROOT = ['AGENTS.md', 'AGENT.md', 'CLAUDE.md', '.cursorrules',
   'README.md', 'README.adoc', 'CONTRIBUTING.md', 'CONTRIBUTING.adoc', 'user-rules.md', 'PROFILE.md'];
-// Project docs are Markdown or AsciiDoc: the document-project skill writes AsciiDoc by default
-// when a project has no docs yet, so a loader blind to `.adoc` would hide every doc it wrote.
+// Project docs are Markdown or AsciiDoc: the document-project skill writes AsciiDoc when the
+// user asks for it or the docs already are, so a loader blind to `.adoc` would hide those docs.
 // Agent-runtime files (AGENTS.md, CLAUDE.md, specs) stay Markdown whatever the project uses.
 const DOC_EXT = new Set(['.md', '.adoc']);
 const isDoc = (name) => DOC_EXT.has(path.extname(name).toLowerCase());
@@ -126,7 +126,10 @@ const cost = (s) => s.length + (s.match(/\n/g) || []).length + 2;
 // honoured by `resolveContextSets` (the harness dir is its last candidate). The OpenCode
 // context plugin carries the same list.
 const SESSION_FILES = ['user-rules.md', 'PROFILE.md', 'memory/MEMORY.md', 'anamnesis/MEMORY.md',
-  'notebook/NOTEBOOK.md', 'wiki.jsonc'];
+  'notebook/NOTEBOOK.md', 'geneseed-wiki.jsonc'];
+// The wiki manifest's earlier name, read when the new one is absent (an install not yet re-emitted,
+// or a rename that failed). One release; `wiki.json`, older still, is the build's to rename.
+const LEGACY_WIKI = 'wiki.jsonc';
 // SHA-256 of each seed body in `js/build/stubs.mjs` (`SESSION_SEEDS`), CRLF folded. A file still
 // byte-identical to its seed says nothing, so it is skipped rather than injected as noise.
 // Hashes, not an import: stubs.mjs pulls in the build's writers, and this module loads on every
@@ -134,7 +137,9 @@ const SESSION_FILES = ['user-rules.md', 'PROFILE.md', 'memory/MEMORY.md', 'anamn
 const SEED_SHA256 = new Set([
   '5c2e92fb1acde041e02d9ebf158460d8ff7a07cbc2b447859631604610130721', // user-rules.md
   '29e012c3c4349ea62a9082cbd04bb25599a0ec280d62c33f6e10742809471816', // PROFILE.md
-  'cccc917c34e6b990e821620bdb4739090151885ab71b6e85046f30a3b71fa5e8', // wiki.jsonc
+  '3a82c78ccc5d745033c16c354f5eda9d79350c704e9da8d605d380fb1e108d7a', // geneseed-wiki.jsonc
+  // The wiki seed before the rename: the build renames an untouched one byte for byte.
+  'cccc917c34e6b990e821620bdb4739090151885ab71b6e85046f30a3b71fa5e8', // wiki.jsonc (legacy)
   '99c786049c260f6baf7aec68a5c0f59907861afe9b867da009440613bdddb907', // MEMORY.md
   '9acb5c9d9cb5dac572104480f05b48cc144e676869bd60e86d8a15b1f6308184', // NOTEBOOK.md
 ]);
@@ -150,8 +155,9 @@ export function sessionFiles(hookRoot) {
   const found = [];
   for (const rel of SESSION_FILES) {
     let abs = path.join(hookRoot, rel);
-    if (rel === 'wiki.jsonc' && process.env.GENESEED_WIKI && isFile(process.env.GENESEED_WIKI)) {
-      abs = process.env.GENESEED_WIKI;
+    if (rel === 'geneseed-wiki.jsonc') {
+      if (process.env.GENESEED_WIKI && isFile(process.env.GENESEED_WIKI)) abs = process.env.GENESEED_WIKI;
+      else if (!isFile(abs)) abs = path.join(hookRoot, LEGACY_WIKI);
     }
     if (!isFile(abs)) continue;
     let text;
@@ -256,6 +262,7 @@ export function discoverContext(root, host = HOST) {
  *
  * `recs` is a Map, not an object: JS reorders integer-like keys on a plain object, and
  * these keys are absolute paths whose iteration order becomes the printed order.
+ * @returns {[Array<{path: string, description: string}>, Array<{path: string, description: string}>, string]}
  */
 export function resolveContextSets(root, hookRoot = null) {
   let manifest = null;

package/js/hosts/hosts.mjs

@@ -128,9 +128,7 @@ export function expanduser(p) {
       + "ntpath/posixpath would guess a home directory for 'user' — this port does not); "
       + 'pass an absolute path, or "~" / "~/…" for your own home directory';
     printErr(`${msg}\n`);
-    const e = new Error(msg);
-    e.exitCode = 1;
-    throw e;
+    throw Object.assign(new Error(msg), { exitCode: 1 });
   }
   return p;
 }