geneseed 3.8.0 → 3.9.0

package/js/build/render.mjs

@@ -34,7 +34,7 @@ import { readText } from '../lib/fs.mjs';
 import { parseJson } from '../lib/json.mjs';
 import { normcase, comparePaths } from '../lib/paths.mjs';
 // `js/build/source.mjs` imports nothing but node builtins, so this direction cannot cycle.
-import { PACK_ORDER, readPackText } from './source.mjs';
+import { PACK_ORDER, readPackText, resolveRuleIds } from './source.mjs';
 
 /** Document STRUCTURE is theme-INDEPENDENT — mirrors `_build_render.STRUCTURE`. */
 export const STRUCTURE = {
@@ -216,7 +216,8 @@ function readSource(cfg, p) {
   let seen = SRC_TEXT.get(cfg);
   if (!seen) SRC_TEXT.set(cfg, (seen = new Map()));
   let text = seen.get(p);
-  if (text === undefined) seen.set(p, (text = readText(p)));
+  // Rule ids resolve here, once per file, so every stage after sees the addressed form.
+  if (text === undefined) seen.set(p, (text = resolveRuleIds(readText(p), cfg.src)));
   return text;
 }
 
@@ -250,7 +251,9 @@ export function renderFile(cfg, filePath, theme, footprint = 'full', lawsPrefix
 function registerBody(cfg, theme, dir, selected, fallback) {
   for (const name of [selected, fallback]) {
     const p = path.join(cfg.src, dir, `${name}.md`);
-    if (existsSync(p) && statSync(p).isFile()) return substitute(readText(p), theme).trim();
+    if (existsSync(p) && statSync(p).isFile()) {
+      return substitute(resolveRuleIds(readText(p), cfg.src), theme).trim();
+    }
   }
   return '';
 }

package/js/build/source.mjs

@@ -37,7 +37,7 @@ import path from 'node:path';
  * on raw or folded text, so one behaviour serves both.
  */
 const _packTexts = new Map();
-export function readPackText(file) {
+export function readRawText(file) {
   const key = path.resolve(file);
   const mtime = statSync(file).mtimeMs;
   const hit = _packTexts.get(key);
@@ -47,6 +47,110 @@ export function readPackText(file) {
   return text;
 }
 
+/**
+ * A doctrine pack as the render sees it: ids resolved, so the heading reads
+ * `### {{DOCTRINE}} process 5 — {{DOC_CONSENT_BEFORE_PUSH}}` again. Every reader that keys on the
+ * `<pack> <n>` address (`knownRuleIds`, the exclusion filter, the survives gate) goes through
+ * here and keeps working unchanged — the address is computed, only the source stopped typing it.
+ */
+export function readPackText(file) {
+  return resolveRuleIds(readRawText(file), path.dirname(path.dirname(file)));
+}
+
+/**
+ * STABLE RULE IDS. Every law and doctrine rule is DECLARED by its heading —
+ * `### {{LAW:verify-before-asserting}} Verify Before Asserting` — and CITED by its id —
+ * `{{LAW:verify-before-asserting}}`. The id is permanent; the number is not stored anywhere. It
+ * is the rule's position (Roman in `laws/universal.md`, Arabic within its pack), computed here
+ * at render time, so removing or reordering a rule renumbers every heading after it and rewires
+ * nothing: no citation ever named the number.
+ *
+ * WHY CITATIONS RENDER AS THE NAME, NOT THE NUMBER. A citation is the one place a number would
+ * leak into text that outlives the build — an agent reads "Law III", writes "Law III" into its
+ * memory, and the memory is wrong the day the canon moves. The rendered harness models what it
+ * asks of the agent: a rule is cited by its principle, in English, identical in every voice. The
+ * number survives only where it is structural — the rule's own heading.
+ *
+ * Retired ids live in `RETIRED_RULE_IDS` so the doctor can refuse their reuse: an id that meant
+ * one thing in someone's notes must never come back meaning another.
+ */
+const DECL_RE = /^### \{\{(LAW|DOCTRINE):([a-z0-9]+(?:-[a-z0-9]+)*)\}\}[ \t]+(\S[^\n]*?)[ \t]*$/gm;
+const CITE_RE = /\{\{(LAW|DOCTRINE):([a-z0-9-]+)\}\}/g;
+export const RULE_ID_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/**
+ * Ids that no longer name a live rule, and must never be declared again. `liveAs` names the one
+ * tier that may still declare it — `external-gate` was Law IX before it became a rigor rule, so
+ * the doctrine keeps it and `{{LAW:external-gate}}` is refused; `null` means gone for good.
+ */
+export const RETIRED_RULE_IDS = {
+  'external-gate': { was: 'Law IX', liveAs: 'DOCTRINE', note: 'moved to the rigor pack' },
+  'absence-is-a-claim': { was: 'Law XI', liveAs: null, note: 'folded into verify-before-asserting' },
+};
+
+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) {
+  let out = '';
+  for (const [v, r] of ROMAN) while (n >= v) { out += r; n -= v; }
+  return out;
+}
+
+/** `sealed-secrets` -> `LEX_SEALED_SECRETS`; a doctrine rule's title key is `DOC_<ID>`. */
+export const titleKey = (kind, id) =>
+  `${kind === 'LAW' ? 'LEX' : 'DOC'}_${id.toUpperCase().replaceAll('-', '_')}`;
+
+/** The files that may declare rules, in canon order: `[kind, pack|null, file]`. */
+export function canonFiles(src = SRC) {
+  return [['LAW', null, path.join(src, 'laws', 'universal.md')],
+    ...PACK_ORDER.map((p) => ['DOCTRINE', p, path.join(src, 'doctrines', `${p}.md`)])];
+}
+
+const _canons = new Map();
+/**
+ * Every declared rule, in render order: `{ kind, pack, id, name, n, label }`, where `label` is
+ * the address the heading renders (`III`, `process 5`). Memoised on the raw texts' identity —
+ * `readRawText` hands back the same string until a file's mtime moves.
+ */
+export function ruleCanon(src = SRC) {
+  const files = canonFiles(src);
+  const texts = files.map(([, , f]) => { try { return readRawText(f); } catch { return ''; } });
+  const key = path.resolve(src);
+  const hit = _canons.get(key);
+  if (hit && hit.texts.every((t, i) => t === texts[i])) return hit.canon;
+  const rules = [];
+  files.forEach(([kind, pack], i) => {
+    let n = 0;
+    for (const m of texts[i].matchAll(DECL_RE)) {
+      if (m[1] !== kind) continue;             // a wrong-tier declaration is the doctor's to name
+      n += 1;
+      rules.push({ kind, pack, id: m[2], name: m[3], n, label: kind === 'LAW' ? toRoman(n) : `${pack} ${n}` });
+    }
+  });
+  const byId = new Map();
+  for (const r of rules) if (!byId.has(r.id)) byId.set(r.id, r);
+  const canon = { rules, byId };
+  _canons.set(key, { texts, canon });
+  return canon;
+}
+
+/**
+ * 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) {
+  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; };
+  return text
+    .replace(DECL_RE, (whole, kind, id) => {
+      const r = known(kind, id);
+      return r ? `### {{${kind}}} ${r.label} — {{${titleKey(kind, id)}}}` : whole;
+    })
+    .replace(CITE_RE, (whole, kind, id) => { const r = known(kind, id); return r ? `*${r.name}*` : whole; });
+}
+
 /**
  * `_build_core.ROOT` — the checkout, from this file's own location (`js/..`).
  *

package/js/build/stubs.mjs

@@ -137,8 +137,13 @@ the project's own. Follow the root \`AGENTS.md\`.
 /** `_build_render.PROFILE_FILE`. */
 const PROFILE_FILE = 'PROFILE.md';
 
-/** `_build_render.PROFILE_STUB`. */
-const PROFILE_STUB = `\
+/**
+ * `_build_render.PROFILE_STUB`.
+ *
+ * Exported for the web console: `/api/profile` answers `seeded: true` while PROFILE.md is
+ * still byte-for-byte this text, which is how the Overview knows to ask for it to be filled in.
+ */
+export const PROFILE_STUB = `\
 # Your profile
 
 Who you are and how you like to work — so the agent can meet you where you are

package/js/cli-table.json

@@ -488,7 +488,7 @@
     },
     {
       "name": "git-gate",
-      "help": "PreToolUse hook: ASK before a history-discarding git act (Law IV) and before every git commit/push (process 5 backstop)",
+      "help": "PreToolUse hook: ASK before a history-discarding git act (Deletion Is Deliberate) and before every git commit/push (Consent Before Push backstop)",
       "description": "",
       "positionals": [],
       "options": [
@@ -528,7 +528,7 @@
           ],
           "dest": "no_consent",
           "metavar": null,
-          "help": "skip the process-5 commit/push ask (set by the emit when the process pack or process 5 is off); Law IV still asks",
+          "help": "skip the Consent Before Push commit/push ask (set by the emit when the process pack or that rule is off); Deletion Is Deliberate still asks",
           "choices": null,
           "default": false,
           "required": false,
@@ -766,7 +766,7 @@
     },
     {
       "name": "rule-gate",
-      "help": "PreToolUse hook: force an ASK before any write to user-rules.md or memory (process 1 backstop)",
+      "help": "PreToolUse hook: force an ASK before any write to user-rules.md or memory (Persist Insight backstop)",
       "description": "",
       "positionals": [],
       "options": [

package/js/hosts/hooks.mjs

@@ -700,14 +700,14 @@ function gitDecide(args, payload) {
   const command = ((payload && payload.tool_input) || {}).command;
   if (typeof command !== 'string') return 0;
   if (DESTRUCTIVE_GIT_RE.test(command)) {
-    return ask(args, 'git-gate', 'law-4', 'Geneseed Law IV \u2014 a history-rewriting or '
+    return ask(args, 'git-gate', 'law-4', 'Geneseed (Deletion Is Deliberate) \u2014 a history-rewriting or '
       + 'discarding git act needs confirmation bound to this specific command');
   }
   // `--no-consent`: the process pack (or process 5 alone) is off, so the commit/push ask has
   // no rule behind it — but Law IV above is universal and has already run.
   if (args.noConsent || !GIT_GATE_RE.test(command)) return 0;
-  return ask(args, 'git-gate', 'process-5', 'Geneseed Doctrine process 5 \u2014 every git '
-    + 'commit/push needs explicit approval');
+  return ask(args, 'git-gate', 'process-5', 'Geneseed (Consent Before Push) \u2014 every git '
+    + 'commit/push needs explicit approval; to see the change first, use the explain-changes skill');
 }
 export const cmdGitGate = guardGate(gitGate, 'git-gate');
 
@@ -764,13 +764,13 @@ function ruleDecide(args, payload) {
   const body = [ti.content, ti.new_string, ti.file_text, ti.new_str]
     .find((v) => typeof v === 'string') || '';
   if (body && !DOTENV_RE.test(p) && SECRET_RE.test(body)) {
-    return ask(args, 'rule-gate', 'law-1', `Geneseed Law I — ${p} would carry a `
+    return ask(args, 'rule-gate', 'law-1', `Geneseed (Sealed Secrets) — ${p} would carry a `
       + 'credential-shaped string. Secrets live in .env or a secret manager, never in a '
       + 'tracked file.');
   }
   const target = ruleGateTarget(p, args.root);
   if (!target) return 0;
-  return ask(args, 'rule-gate', 'process-1', `Geneseed Doctrine process 1 \u2014 writing to `
+  return ask(args, 'rule-gate', 'process-1', `Geneseed (Persist Insight) \u2014 writing to `
     + `${target}: a standing rule, or a fact to remember? That choice is the user's. Run the `
     + 'rule skill first.');
 }

package/js/hosts/native.mjs

@@ -34,7 +34,7 @@ import { writeText, copyFile, readText } from '../lib/fs.mjs';
 import { jsonDumps, parseJson, formatValue, formatRepr, isTruthy, isDict } from '../lib/json.mjs';
 
 /** Mirrors `_build_core.VENDORED_SKILL_DIRS`. */
-export const VENDORED_SKILL_DIRS = new Set(['react-view-transitions', 'daydream', 'token-report']);
+export const VENDORED_SKILL_DIRS = new Set(['react-view-transitions', 'daydream', 'token-report', 'explain-changes']);
 
 /**
  * `PurePath(rel).parts` — split on EITHER separator, empties dropped.