geneseed 3.8.0 → 3.10.0

package/src/skills/explain-changes/scripts/render_changes.mjs

@@ -0,0 +1,558 @@
+#!/usr/bin/env node
+/**
+ * Render an explain-changes report — one self-contained, offline HTML page that walks a human
+ * through a diff before they commit it.
+ *
+ * WHY A SCRIPT AND NOT THE MODEL. The model writes only the narrative (the brief: intent,
+ * risks, logical units). Every diff line on the page comes from `git diff`, run here, and is
+ * escaped here. A model that retypes a diff pays output tokens in proportion to the diff and
+ * can alter a line of the very thing under review; this file cannot.
+ *
+ * The script only READS git. It never touches the index or the working tree.
+ *
+ * Usage:
+ *   node render_changes.mjs --brief <file.json> [--out <notebook-dir>] [--base <ref>]
+ *   node render_changes.mjs --hash [--base <ref>]
+ * Exit: 0 written (mismatches, if any, go to stderr and onto a banner) · 2 usage · 3 empty diff.
+ */
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// ponytail: the SHA-1 empty tree; a SHA-256 repository has another id. Upgrade if one shows up:
+// `git hash-object -t tree --stdin` on empty input answers for either object format.
+const EMPTY_TREE ='4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+export const MAX_FILE_LINES = 1500;
+
+function git(cwd, args, input) {
+  return execFileSync('git', ['-c', 'core.quotePath=false', ...args], {
+    cwd, input, encoding: 'utf8', maxBuffer: 512 * 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'],
+  });
+}
+
+function gitOr(cwd, args, fallback) {
+  try { return git(cwd, args).trim(); } catch { return fallback; }
+}
+
+/**
+ * Untracked files as the diff `git add` would produce. Read here rather than via `git add -N`,
+ * which would write the index. A nested repository is listed as `sub/` and cannot be read as a
+ * file, and a broken symlink has nothing to read: both are written the way git writes them
+ * (a gitlink header; a symlink's target as its one line), since reading either would throw.
+ */
+function untrackedAsDiff(root) {
+  const paths = git(root, ['ls-files', '--others', '--exclude-standard', '-z'])
+    .split('\0').filter(Boolean);
+  let out = '';
+  for (const listed of paths) {
+    const full = path.join(root, listed);
+    const st = fs.lstatSync(full);
+    const p = listed.replace(/\/$/, '');
+    if (st.isDirectory()) { out += `diff --git a/${p} b/${p}\nnew file mode 160000\n`; continue; }
+    if (st.isSymbolicLink()) {
+      out += `diff --git a/${p} b/${p}\nnew file mode 120000\n--- /dev/null\n+++ b/${p}\n@@ -0,0 +1 @@\n`
+        + `+${fs.readlinkSync(full)}\n\\n`;
+      continue;
+    }
+    const buf = fs.readFileSync(full);
+    out += `diff --git a/${p} b/${p}\nnew file mode 100644\n`;
+    if (buf.includes(0)) { out += `Binary files /dev/null and b/${p} differ\n`; continue; }
+    const text = buf.toString('utf8');
+    if (!text) continue;
+    const lines = text.split('\n');
+    const noEol = lines[lines.length - 1] !== '';
+    if (!noEol) lines.pop();
+    out += `--- /dev/null\n+++ b/${p}\n@@ -0,0 +1,${lines.length} @@\n`
+      + lines.map((l) => `+${l}`).join('\n') + '\n';
+    if (noEol) out += '\\n';
+  }
+  return out;
+}
+
+/** Staged if anything is staged (what the commit will hold), else the working tree. */
+export function selectDiff(root, base) {
+  const common = ['diff', '--no-color', '--no-ext-diff', '-M'];
+  if (base) return { mode: `${base}...HEAD`, text: git(root, [...common, `${base}...HEAD`]) };
+  const head = gitOr(root, ['rev-parse', '--verify', '-q', 'HEAD'], '') ? 'HEAD' : EMPTY_TREE;
+  const staged = git(root, [...common, '--cached', head]);
+  if (staged) return { mode: 'staged', text: staged };
+  return { mode: 'working tree', text: git(root, [...common, head]) + untrackedAsDiff(root) };
+}
+
+export const diffHash = (text) => createHash('sha256').update(text).digest('hex').slice(0, 12);
+
+const C_ESC = { a: 7, b: 8, t: 9, n: 10, v: 11, f: 12, r: 13 };
+
+/**
+ * A path as git prints it. git C-quotes a path holding `"`, `\`, a tab or a newline even with
+ * core.quotePath=false; octal escapes are raw bytes, so they are collected and decoded as UTF-8.
+ */
+export function unquote(s) {
+  if (!s.startsWith('"')) return s;
+  const parts = [];
+  for (const [m, e] of s.slice(1, -1).matchAll(/\\([0-7]{3}|.)|[^\\]+/gs)) {
+    if (e === undefined) parts.push(Buffer.from(m));
+    else parts.push(Buffer.from([/^[0-7]/.test(e) ? parseInt(e, 8) : (C_ESC[e] ?? e.charCodeAt(0))]));
+  }
+  return Buffer.concat(parts).toString('utf8');
+}
+
+export function parseDiff(text) {
+  const files = [];
+  let f = null;
+  let h = null;
+  let o = 0;
+  let n = 0;
+  for (const line of text.split('\n')) {
+    if (line.startsWith('diff --git ')) {
+      // ponytail: an unquoted path containing " b/" splits wrong here; the rename/copy lines correct it
+      const m = /^diff --git (?:"((?:[^"\\]|\\.)*)"|a\/(.*?)) (?:"((?:[^"\\]|\\.)*)"|b\/(.*))$/.exec(line);
+      const a = m && (m[2] ?? unquote(`"${m[1]}"`).slice(2));
+      const b = m && (m[4] ?? unquote(`"${m[3]}"`).slice(2));
+      f = {
+        path: m ? b : line.slice(11), oldPath: m ? a : '', status: 'modified',
+        binary: false, generated: false, truncated: false, hunks: [], add: 0, del: 0, shown: 0,
+      };
+      files.push(f);
+      h = null;
+      continue;
+    }
+    if (!f) continue;
+    const hm = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(line);
+    if (hm) {
+      h = { header: line, lines: [] };
+      f.hunks.push(h);
+      o = Number(hm[1]);
+      n = Number(hm[2]);
+      continue;
+    }
+    if (!h) {
+      if (line.startsWith('new file mode')) f.status = 'added';
+      else if (line.startsWith('deleted file mode')) f.status = 'deleted';
+      else if (line.startsWith('rename from ')) { f.status = 'renamed'; f.oldPath = unquote(line.slice(12)); }
+      else if (line.startsWith('rename to ')) f.path = unquote(line.slice(10));
+      else if (line.startsWith('copy from ')) { f.status = 'copied'; f.oldPath = unquote(line.slice(10)); }
+      else if (line.startsWith('copy to ')) f.path = unquote(line.slice(8));
+      else if (line.startsWith('Binary files ') || line === 'GIT binary patch') f.binary = true;
+      continue;
+    }
+    const t = line[0];
+    if (t === '+') f.add++;
+    else if (t === '-') f.del++;
+    else if (t !== ' ' && t !== '\\') continue;
+    if (f.shown >= MAX_FILE_LINES) { f.truncated = true; continue; }
+    f.shown++;
+    const body = line.slice(1);
+    if (t === '+') h.lines.push({ t: 'add', n: n++, text: body });
+    else if (t === '-') h.lines.push({ t: 'del', o: o++, text: body });
+    else if (t === ' ') h.lines.push({ t: 'ctx', o: o++, n: n++, text: body });
+    else h.lines.push({ t: 'note', text: line });
+  }
+  return files;
+}
+
+const GENERATED = /(^|\/)(package-lock\.json|npm-shrinkwrap\.json|pnpm-lock\.yaml|yarn\.lock|Cargo\.lock|poetry\.lock|composer\.lock|Gemfile\.lock)$|(^|\/)dist\//;
+
+export function markGenerated(root, files) {
+  let attrs = '';
+  try {
+    attrs = git(root, ['check-attr', '--stdin', 'linguist-generated'],
+      files.map((f) => f.path).join('\n') + '\n');
+  } catch { /* no attributes → only the name patterns apply */ }
+  const marked = new Set();
+  for (const l of attrs.split('\n')) {
+    const i = l.lastIndexOf(': linguist-generated: ');
+    if (i > 0 && /: (true|set)$/.test(l)) marked.add(l.slice(0, i));
+  }
+  for (const f of files) f.generated = GENERATED.test(f.path) || marked.has(f.path);
+}
+
+/**
+ * Inline SVG from the model: one <svg> element and nothing after it, no script, no handler, no
+ * foreign HTML, no animation that rewrites a link, nothing outside the page. A denylist can be
+ * bypassed; the page's CSP is what actually stops a script or a fetch. This check exists so an
+ * unsafe diagram raises the mismatch banner instead of rendering inert and unnoticed.
+ */
+export function safeSvg(svg) {
+  const t = String(svg).trim();
+  const close = t.toLowerCase().indexOf('</svg>');
+  const shape = /^<svg[\s>/][\s\S]*<\/svg>$/i.test(t) ? close === t.length - 6 : /^<svg[^>]*\/>$/i.test(t);
+  return shape
+    && !/<script|<foreignObject|\son\w+\s*=|href\s*=\s*(?!["']?#)|url\(\s*(?!["']?#)/i.test(t)
+    && !/attributeName\s*=\s*["']?(xlink:)?href/i.test(t)
+    && !/<(iframe|img|meta|form|link|object|embed|style|base)\b|javascript:/i.test(t);
+}
+
+export const unitFiles = (u) => [...new Set([...(u.files ?? []), ...Object.keys(u.hunks ?? {})])];
+
+const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * The brief with every malformed field reported and dropped, so neither the check nor the page
+ * trips over model-written JSON of the wrong shape. `brief` is null when there is nothing to keep.
+ */
+export function shapeBrief(raw) {
+  if (!isObj(raw)) return { brief: null, problems: ['the brief must be a JSON object'] };
+  const problems = [];
+  const list = (v, name) => {
+    if (v === undefined) return [];
+    if (Array.isArray(v)) return v;
+    problems.push(`${name} must be an array`);
+    return [];
+  };
+  const units = list(raw.units, 'units').flatMap((u, i) => {
+    if (!isObj(u)) { problems.push(`unit ${i + 1} must be an object`); return []; }
+    const c = { ...u };
+    if (u.files !== undefined && !(Array.isArray(u.files) && u.files.every((p) => typeof p === 'string'))) {
+      problems.push(`unit "${u.title}": files must be an array of paths`);
+      delete c.files;
+    }
+    if (u.hunks !== undefined && !isObj(u.hunks)) {
+      problems.push(`unit "${u.title}": hunks must be an object of path → hunk indexes`);
+      delete c.hunks;
+    } else if (u.hunks) {
+      c.hunks = Object.fromEntries(Object.entries(u.hunks).filter(([p, idx]) => {
+        const ok = Array.isArray(idx) && idx.every(Number.isInteger);
+        if (!ok) problems.push(`unit "${u.title}": hunks for ${p} must be an array of hunk indexes`);
+        return ok;
+      }));
+    }
+    return [c];
+  });
+  const risks = list(raw.risks, 'risks').filter((r, i) => {
+    if (!isObj(r) || typeof r.text !== 'string') {
+      problems.push(`risk ${i + 1} must be an object with a string "text"`);
+      return false;
+    }
+    if (!Object.hasOwn(RISK_ORDER, r.level)) {
+      problems.push(`risk "${r.text}" has level "${r.level}" — use high, medium or low`);
+    }
+    return true;
+  });
+  return { brief: { ...raw, units, risks }, problems };
+}
+
+export function checkBrief(raw, files) {
+  const { brief, problems } = shapeBrief(raw);
+  if (!brief) return problems;
+  const byPath = new Map(files.map((f) => [f.path, f]));
+  const covered = new Set();
+  for (const u of brief.units) {
+    for (const p of unitFiles(u)) {
+      if (byPath.has(p)) covered.add(p);
+      else problems.push(`unit "${u.title}" cites ${p}, which is not in the diff`);
+    }
+    for (const [p, idx] of Object.entries(u.hunks ?? {})) {
+      const f = byPath.get(p);
+      if (!f) continue;
+      for (const i of idx) {
+        if (!f.hunks[i]) problems.push(`unit "${u.title}" cites hunk ${i} of ${p}, which has ${f.hunks.length}`);
+      }
+    }
+    if (u.svg && !safeSvg(u.svg)) problems.push(`unit "${u.title}": diagram dropped (unsafe SVG)`);
+  }
+  for (const f of files) {
+    if (!covered.has(f.path) && !f.generated) problems.push(`${f.path} is changed but no unit explains it`);
+  }
+  if (!brief.risks.length && !brief.risks_none_reason) {
+    problems.push('no risks listed and no risks_none_reason given');
+  }
+  return problems;
+}
+
+const TEST_PATH = /(^|\/)(tests?|__tests__|spec)\/|\.(test|spec)\.[^/]+$/;
+const RISK_ORDER = { high: 0, medium: 1, low: 2 };
+
+const LABELS = {
+  en: {
+    request: 'Original request', inShort: 'In short', checkFirst: 'Check first',
+    walkthrough: 'Walkthrough', appendix: 'Appendix — full diff',
+    mismatch: 'The narrative does not match the diff', noRisks: 'No risks listed',
+    files: 'files', tests: 'test files', outOfScope: 'out of scope',
+    high: 'high', medium: 'medium', low: 'low', binary: 'binary', generated: 'generated',
+    truncated: `truncated after ${MAX_FILE_LINES} lines`, light: '☀ Light', dark: '☾ Dark',
+    generatedOn: 'generated',
+    status: { added: 'added', deleted: 'deleted', modified: 'modified', renamed: 'renamed', copied: 'copied' },
+  },
+  fr: {
+    request: "Demande d'origine", inShort: 'En bref', checkFirst: 'À vérifier en priorité',
+    walkthrough: 'Parcours des changements', appendix: 'Annexe — diff complet',
+    mismatch: 'Le récit ne correspond pas au diff', noRisks: 'Aucun risque listé',
+    files: 'fichiers', tests: 'fichiers de test', outOfScope: 'hors périmètre',
+    high: 'élevé', medium: 'moyen', low: 'faible', binary: 'binaire', generated: 'généré',
+    truncated: `tronqué après ${MAX_FILE_LINES} lignes`, light: '☀ Clair', dark: '☾ Sombre',
+    generatedOn: 'généré le',
+    status: { added: 'nouveau', deleted: 'supprimé', modified: 'modifié', renamed: 'renommé', copied: 'copié' },
+  },
+};
+
+const esc = (s) => String(s ?? '').replace(/[&<>"']/g,
+  (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+const code = (s) => esc(s).replace(/\r$/, '<span class="cr" title="CR">␍</span>');
+
+function splitRows(h) {
+  const side = (l, which) => (l
+    ? `<td class="n ${l.t}">${which === 'o' ? l.o : l.n}</td><td class="c ${l.t}">${code(l.text)}</td>`
+    : '<td class="n empty"></td><td class="c empty"></td>');
+  const L = h.lines;
+  let r = '';
+  let i = 0;
+  while (i < L.length) {
+    if (L[i].t === 'ctx') { r += `<tr>${side(L[i], 'o')}${side(L[i], 'n')}</tr>`; i++; continue; }
+    if (L[i].t === 'note') { r += `<tr><td class="note" colspan="4">${esc(L[i].text)}</td></tr>`; i++; continue; }
+    const dels = [];
+    const adds = [];
+    while (i < L.length && L[i].t === 'del') dels.push(L[i++]);
+    while (i < L.length && L[i].t === 'add') adds.push(L[i++]);
+    for (let k = 0; k < Math.max(dels.length, adds.length); k++) {
+      r += `<tr>${side(dels[k], 'o')}${side(adds[k], 'n')}</tr>`;
+    }
+  }
+  return r;
+}
+
+function singleRows(h, added) {
+  return h.lines.map((l) => (l.t === 'note'
+    ? `<tr><td class="note" colspan="3">${esc(l.text)}</td></tr>`
+    : `<tr><td class="n ${l.t}">${added ? l.n : l.o}</td><td class="s ${l.t}">${added ? '+' : '−'}</td>`
+      + `<td class="c ${l.t}">${code(l.text)}</td></tr>`)).join('');
+}
+
+function diffTable(f, hunks) {
+  if (f.binary || !hunks.length) return '';
+  const single = f.status === 'added' || f.status === 'deleted';
+  const rows = hunks.map((h) => `<tr class="hunk"><td colspan="${single ? 3 : 4}">${esc(h.header)}</td></tr>`
+    + (single ? singleRows(h, f.status === 'added') : splitRows(h))).join('');
+  return `<div class="diffwrap"><table class="diff ${single ? 'single' : 'split'}">${rows}</table></div>`;
+}
+
+function fileHead(f, L) {
+  const tags = [f.binary && L.binary, f.generated && L.generated, f.truncated && L.truncated]
+    .filter(Boolean).map((t) => `<span class="tag">${esc(t)}</span> `).join('');
+  return `<div class="fhead"><span class="path">diff --git a/${esc(f.oldPath || f.path)} b/${esc(f.path)}</span>`
+    + `<span>${tags}${esc(L.status[f.status])} · <span class="plus">+${f.add}</span> `
+    + `<span class="minus">−${f.del}</span></span></div>`;
+}
+
+const CSS = `
+:root{--bg:#16181c;--panel:#1d2025;--ink:#e6e7e9;--muted:#9a9ea6;--line:#2e3238;--accent:#8aa4ff;
+--add-bg:#16311f;--add-ink:#8fe0a6;--add-gut:#1d4029;--del-bg:#3a1a1d;--del-ink:#ff9aa2;--del-gut:#4a2226;
+--hunk-bg:#1f2638;--hunk-ink:#8aa4ff;--high:#ff7b6b;--medium:#f0b44c;--low:#a8cf6f;--code-bg:#191b1f;color-scheme:dark}
+:root[data-theme="light"]{--bg:#fbfbfa;--panel:#fff;--ink:#1d1f23;--muted:#62666d;--line:#e3e4e6;--accent:#3a5bd9;
+--add-bg:#e6f6ea;--add-ink:#1a6b33;--add-gut:#cdeed6;--del-bg:#fdebec;--del-ink:#a1232b;--del-gut:#f8d4d7;
+--hunk-bg:#eef2fd;--hunk-ink:#3a5bd9;--high:#c0392b;--medium:#c77c02;--low:#5a7d2a;--code-bg:#f6f7f8;color-scheme:light}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--ink);font:15px/1.55 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif}
+main{padding:32px clamp(16px,3vw,48px) 64px}
+.ask,.summary,.why{max-width:110ch}
+code,.path,.diff,.chip,footer{font-family:ui-monospace,"Cascadia Code","SF Mono",Consolas,monospace;font-size:12.5px}
+h1{font-size:22px;margin:0 0 4px}h2{font-size:17px;margin:40px 0 12px}h3{font-size:15px;margin:0}
+.muted{color:var(--muted)}
+.top{display:flex;justify-content:space-between;align-items:flex-start;gap:16px}
+button{font:inherit;font-size:13px;background:var(--panel);color:var(--ink);border:1px solid var(--line);border-radius:6px;padding:5px 10px;cursor:pointer}
+.ask{margin:16px 0;padding:12px 16px;border-left:3px solid var(--accent);background:var(--panel);border-radius:0 8px 8px 0}
+.label{font-size:12px;text-transform:uppercase;letter-spacing:.06em;color:var(--muted)}
+.stats{display:flex;flex-wrap:wrap;gap:8px;margin-top:12px}
+.stat{background:var(--panel);border:1px solid var(--line);border-radius:8px;padding:6px 12px;font-size:13px}
+.plus{color:var(--add-ink)}.minus{color:var(--del-ink)}
+.summary{background:var(--panel);border:1px solid var(--line);border-radius:10px;padding:16px 20px}
+.mismatch{margin:16px 0;padding:12px 16px;border:1px solid var(--high);border-radius:10px;color:var(--high)}
+.checks{list-style:none;padding:0;margin:0;display:grid;gap:8px}
+.checks li{background:var(--panel);border:1px solid var(--line);border-radius:10px;padding:12px 14px;display:grid;grid-template-columns:auto auto 1fr;gap:10px;align-items:start}
+.checks input{margin-top:4px;width:16px;height:16px}
+.checks li.done{opacity:.55}.checks li.done .what{text-decoration:line-through}
+.checks a{color:var(--accent);text-decoration:none;font-size:13px}
+.sev{font-size:11px;font-weight:600;text-transform:uppercase;padding:2px 7px;border-radius:999px;border:1px solid;white-space:nowrap}
+.sev.high{color:var(--high)}.sev.medium{color:var(--medium)}.sev.low{color:var(--low)}
+.card{background:var(--panel);border:1px solid var(--line);border-radius:12px;margin:16px 0;overflow:hidden}
+.card>.head{padding:16px 20px;border-bottom:1px solid var(--line)}
+.step{font-size:12px;color:var(--muted)}.why{margin:6px 0 0}
+.files{margin-top:8px;display:flex;gap:6px;flex-wrap:wrap}
+.chip{background:var(--code-bg);border:1px solid var(--line);border-radius:6px;padding:1px 7px}
+.diagram{padding:16px 20px;border-bottom:1px solid var(--line);color:var(--ink)}
+.diagram svg{width:100%;height:auto;max-width:900px;display:block;margin:0 auto}
+.file+.file{border-top:1px solid var(--line)}
+.fhead{display:flex;justify-content:space-between;gap:8px;padding:8px 14px;background:var(--code-bg);border-bottom:1px solid var(--line);font-size:12.5px}
+.path{font-weight:600;overflow-wrap:anywhere}
+.tag{font-size:11px;color:var(--muted);border:1px solid var(--line);border-radius:999px;padding:0 6px}
+.diffwrap{overflow-x:auto}
+.diff{width:100%;border-collapse:collapse;table-layout:fixed;tab-size:4}
+.diff td{padding:0 8px;vertical-align:top;white-space:pre-wrap;overflow-wrap:anywhere;line-height:1.6}
+.diff td.n{width:52px;text-align:right;color:var(--muted);user-select:none;padding:0 6px}
+.diff td.s{width:18px;text-align:center;user-select:none;padding:0}
+.diff td.add{background:var(--add-bg);color:var(--add-ink)}.diff td.n.add{background:var(--add-gut)}
+.diff td.del{background:var(--del-bg);color:var(--del-ink)}.diff td.n.del{background:var(--del-gut)}
+.diff td.empty{background:var(--code-bg)}
+.diff tr.hunk td{background:var(--hunk-bg);color:var(--hunk-ink);padding:3px 8px}
+.diff td.note{color:var(--muted);font-style:italic}
+.cr{color:var(--muted)}
+details>summary{cursor:pointer;list-style:none}details>summary::-webkit-details-marker{display:none}
+details>summary .fhead::before{content:"▸ "}details[open]>summary .fhead::before{content:"▾ "}
+footer{margin-top:48px;padding-top:16px;border-top:1px solid var(--line);color:var(--muted)}
+`;
+
+const JS = `
+const R=document.documentElement,B=document.getElementById('theme');
+function set(t){R.dataset.theme=t;B.textContent=t==='dark'?B.dataset.light:B.dataset.dark;
+try{localStorage.setItem('explain-changes-theme',t)}catch(e){}}
+let t='dark';try{t=localStorage.getItem('explain-changes-theme')||'dark'}catch(e){}
+set(t);B.onclick=()=>set(R.dataset.theme==='dark'?'light':'dark');
+document.querySelectorAll('.checks input').forEach(c=>c.onchange=()=>c.closest('li').classList.toggle('done',c.checked));
+`;
+
+// The CSP is the barrier: no script runs but the page's own (pinned by hash, so it must be
+// byte-identical to what sits between <script> and </script>), nothing is fetched, no form posts.
+// safeSvg is only the check that raises the banner.
+const CSP = "default-src 'none'; style-src 'unsafe-inline'; img-src data:; "
+  + `script-src 'sha256-${createHash('sha256').update(JS).digest('base64')}'; form-action 'none'; base-uri 'none'`;
+
+export function renderPage({ brief, files, problems, meta }) {
+  const lang = Object.hasOwn(LABELS, brief.lang) ? brief.lang : 'en';
+  const L = LABELS[lang];
+  const byPath = new Map(files.map((f) => [f.path, f]));
+  const units = (brief.units ?? []).map((u, i) => ({ ...u, id: u.id ?? `u${i + 1}` }));
+  const titleOf = (id) => units.find((u) => u.id === id)?.title ?? id;
+  const add = files.reduce((s, f) => s + f.add, 0);
+  const del = files.reduce((s, f) => s + f.del, 0);
+  const tests = files.filter((f) => TEST_PATH.test(f.path)).length;
+  const oos = units.filter((u) => u.out_of_scope).length;
+
+  const risks = [...(brief.risks ?? [])]
+    .map((r) => ({ ...r, level: Object.hasOwn(RISK_ORDER, r.level) ? r.level : 'low' }))
+    .sort((a, b) => RISK_ORDER[a.level] - RISK_ORDER[b.level]);
+  const riskHtml = risks.length
+    ? `<ul class="checks">${risks.map((r) => `<li><input type="checkbox"><span class="sev ${r.level}">${esc(L[r.level])}</span>`
+      + `<div><div class="what">${esc(r.text)}</div>`
+      + `${r.unit ? `<a href="#${esc(r.unit)}">→ ${esc(titleOf(r.unit))}</a>` : ''}</div></li>`).join('')}</ul>`
+    : `<p class="muted">${esc(L.noRisks)} — ${esc(brief.risks_none_reason)}</p>`;
+
+  const cards = units.map((u, i) => {
+    const paths = unitFiles(u);
+    const diffs = paths.map((p) => {
+      const f = byPath.get(p);
+      if (!f) return '';
+      const idx = u.hunks?.[p];
+      const hunks = idx ? idx.map((k) => f.hunks[k]).filter(Boolean) : f.hunks;
+      return `<div class="file">${fileHead(f, L)}${diffTable(f, hunks)}</div>`;
+    }).join('');
+    const svg = u.svg && safeSvg(u.svg) ? `<div class="diagram">${u.svg}</div>` : '';
+    return `<section class="card" id="${esc(u.id)}"><div class="head">`
+      + `<div class="step">${i + 1} / ${units.length}${u.kind ? ` · ${esc(u.kind)}` : ''}</div>`
+      + `<h3>${esc(u.title)}</h3><p class="why">${esc(u.why)}</p>`
+      + `<div class="files">${paths.map((p) => `<span class="chip">${esc(p)}</span>`).join('')}</div>`
+      + `</div>${svg}${diffs}</section>`;
+  }).join('');
+
+  const appendix = files.map((f) => `<details class="card file"><summary>${fileHead(f, L)}</summary>`
+    + `${f.generated ? '' : diffTable(f, f.hunks)}</details>`).join('');
+  const banner = problems.length
+    ? `<div class="mismatch"><strong>${esc(L.mismatch)}</strong><ul>${problems.map((p) => `<li>${esc(p)}</li>`).join('')}</ul></div>`
+    : '';
+
+  return `<!doctype html>
+<html lang="${lang}" data-theme="dark">
+<head>
+<meta charset="utf-8">
+<meta http-equiv="Content-Security-Policy" content="${CSP}">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(brief.title)} — ${esc(meta.branch)}</title>
+<style>${CSS}</style>
+</head>
+<body>
+<main>
+<header>
+<div class="top"><div><h1>${esc(brief.title)}</h1><div class="muted">${esc(meta.branch)} · ${esc(meta.mode)}</div></div>
+<button id="theme" data-light="${esc(L.light)}" data-dark="${esc(L.dark)}">${esc(L.light)}</button></div>
+<div class="ask"><div class="label">${esc(L.request)}</div>${esc(brief.request)}</div>
+<div class="stats"><span class="stat"><b>${files.length}</b> ${esc(L.files)}</span>
+<span class="stat plus"><b>+${add}</b></span><span class="stat minus"><b>−${del}</b></span>
+<span class="stat"><b>${tests}</b> ${esc(L.tests)}</span><span class="stat"><b>${oos}</b> ${esc(L.outOfScope)}</span></div>
+</header>
+${banner}
+<h2>${esc(L.inShort)}</h2>
+<div class="summary">${esc(brief.summary)}</div>
+<h2>${esc(L.checkFirst)}</h2>
+${riskHtml}
+<h2>${esc(L.walkthrough)}</h2>
+${cards}
+<h2>${esc(L.appendix)}</h2>
+${appendix}
+<footer>diff ${esc(meta.hash)} · base ${esc(meta.base)} (${esc(meta.branch)}) · ${esc(L.generatedOn)} ${esc(meta.generated)} · explain-changes</footer>
+</main>
+<script>${JS}</script>
+</body>
+</html>
+`;
+}
+
+const USAGE = 'usage: render_changes.mjs --brief <file.json> [--out <notebook-dir>] [--base <ref>]\n'
+  + '       render_changes.mjs --hash [--base <ref>]';
+
+function parseArgs(argv) {
+  const a = {};
+  for (let i = 0; i < argv.length; i++) {
+    const k = argv[i];
+    if (k === '--hash') { a.hash = true; continue; }
+    if (k !== '--brief' && k !== '--out' && k !== '--base') return { error: `unknown argument ${k}` };
+    const v = argv[++i];
+    if (v === undefined) return { error: `${k} needs a value` };
+    // A ref starting with "-" would reach git as an option.
+    if (k === '--base' && v.startsWith('-')) return { error: `--base ${v}: not a ref` };
+    a[k.slice(2)] = v;
+  }
+  return a;
+}
+
+/** Warn when a report lands where git could pick it up. Exit 1 = not ignored; 128 = outside. */
+function ignored(root, file) {
+  try { git(root, ['check-ignore', '-q', '--', file]); return true; } catch (e) { return e.status !== 1; }
+}
+
+export function run(argv, cwd = process.cwd()) {
+  const fail = (code, msg) => ({ code, out: [], err: [`explain-changes: ${msg}`, ...(code === 2 ? [USAGE] : [])] });
+  const a = parseArgs(argv);
+  if (a.error) return fail(2, a.error);
+  let root;
+  try { root = git(cwd, ['rev-parse', '--show-toplevel']).trim(); } catch { return fail(2, 'not inside a git repository'); }
+  const d = selectDiff(root, a.base);
+  if (!d.text.trim()) return fail(3, 'nothing to explain — the diff is empty');
+  const hash = diffHash(d.text);
+  if (a.hash) return { code: 0, out: [hash], err: [] };
+  if (!a.brief) return fail(2, '--brief <file.json> is required');
+  let raw;
+  try { raw = JSON.parse(fs.readFileSync(path.resolve(cwd, a.brief), 'utf8')); } catch (e) {
+    return fail(2, `cannot read the brief: ${e.message}`);
+  }
+  const { brief } = shapeBrief(raw);
+  if (!brief) return fail(2, 'the brief must be a JSON object');
+  const files = parseDiff(d.text);
+  markGenerated(root, files);
+  const problems = checkBrief(raw, files);
+  const branch = gitOr(root, ['rev-parse', '--abbrev-ref', 'HEAD'], 'no-commit');
+  const base = gitOr(root, ['rev-parse', '--short', a.base ?? 'HEAD'], 'none');
+  const now = new Date().toISOString();
+  const html = renderPage({ brief, files, problems,
+    meta: { branch, mode: d.mode, hash, base, generated: now.slice(0, 16).replace('T', ' ') } });
+  const dir = a.out
+    ? path.resolve(cwd, a.out, 'changes')
+    : path.resolve(root, git(root, ['rev-parse', '--git-dir']).trim(), 'explain-changes');
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, `${now.slice(0, 10)}-${branch.replace(/[^\w.-]+/g, '-')}-${hash}.html`);
+  fs.writeFileSync(file, html);
+  const err = [];
+  if (a.out && !ignored(root, file)) err.push(`explain-changes: warning — ${file} is not git-ignored, and the report contains code`);
+  if (problems.length) {
+    err.push(`explain-changes: ${problems.length} narrative mismatch(es) — fix the brief and re-run:`,
+      ...problems.map((p) => `  - ${p}`));
+  }
+  return { code: 0, out: [file, `diff ${hash}`], err };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  const r = run(process.argv.slice(2));
+  if (r.out.length) process.stdout.write(`${r.out.join('\n')}\n`);
+  if (r.err.length) process.stderr.write(`${r.err.join('\n')}\n`);
+  process.exitCode = r.code;
+}

package/src/skills/forge-mcp.md

@@ -9,7 +9,7 @@ server — exposing an external API or service to an agent as a set of tools.
 depends on it.
 
 ## Procedure
-1. Research first ({{DOCTRINE}} process 4): read the MCP specification
+1. Research first ({{DOCTRINE:read-the-docs-first}}): read the MCP specification
    (`modelcontextprotocol.io`) and the target service's API docs, then pick the
    SDK — Python (FastMCP) or TypeScript (MCP SDK) — and load its documentation.
 2. Plan the tool surface: list the service's key operations and design
@@ -18,15 +18,15 @@ depends on it.
    real task with it.
 3. Build the core: an authenticated API client, shared error-handling and
    pagination helpers, and response formatting that returns focused, relevant
-   data rather than raw dumps ({{DOCTRINE}} process 3).
+   data rather than raw dumps ({{DOCTRINE:context-economy}}).
 4. Define each tool's input and output schema (Pydantic or Zod), set the
    annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`,
    `openWorldHint`), and write error messages that name the specific, actionable
    fix. A destructive tool's guard is enforced server-side, at the boundary the
-   call must cross — never left to the calling model's judgement ({{DOCTRINE}} rigor 5).
+   call must cross — never left to the calling model's judgement ({{DOCTRINE:external-gate}}).
 5. Review and test: kill duplication, ensure consistent errors and full type
    coverage, then build and exercise every tool with the MCP Inspector — don't
-   assume it works ({{LAW}} III).
+   assume it works ({{LAW:verify-before-asserting}}).
 6. Evaluate: pick ~10 realistic, read-only questions that each need multiple tool
    calls and have one verifiable, stable answer; run them and confirm the server
    actually answers them.

package/src/skills/fresh-eyes.md

@@ -5,12 +5,12 @@
 **Trigger:** a task is claimed done and the solving session believes the artifact works — before merge or handoff, or when the user asks to "validate", "fresh eyes", "prove it meets the spec", "did this actually solve it", or "independent sign-off", and the cost of a confidently-wrong "done" is high. This re-judges the *result* from zero context — distinct from [geneseed-code-review](geneseed-code-review.md), which reviews a *diff* with full knowledge of the change. For an open-ended quality critique use [roast-me](roast-me.md); for a multi-stance debate over an undecided question use [council](council.md).
 
 ## Procedure
-1. Capture the firewall input as TWO things and nothing else: (a) the **verbatim original task/spec** — the raw issue or request text, NOT a solver-written summary or "spec card" (a distilled card launders the solving session's framing into the rubric, the very bias this {{SKILL}} exists to defeat), and (b) a pointer to the **final artifact** as it stands — file paths, built output, or the command to run it. If the raw task is too thin to yield acceptance criteria, have the **user** (never the solver) confirm a one-line acceptance bar, then proceed ({{LAW}} X); if it is too fuzzy even for that, this is a judgement call — convene [council](council.md) instead.
+1. Capture the firewall input as TWO things and nothing else: (a) the **verbatim original task/spec** — the raw issue or request text, NOT a solver-written summary or "spec card" (a distilled card launders the solving session's framing into the rubric, the very bias this {{SKILL}} exists to defeat), and (b) a pointer to the **final artifact** as it stands — file paths, built output, or the command to run it. If the raw task is too thin to yield acceptance criteria, have the **user** (never the solver) confirm a one-line acceptance bar, then proceed ({{LAW:echo-the-intent}}); if it is too fuzzy even for that, this is a judgement call — convene [council](council.md) instead.
 2. Deliberately WITHHOLD everything else and say so in the brief: the diff and changed-files list, the chat transcript, the solver's rationale and commit messages, prior test output, and every "it works because…" claim. Each is a vector for confirmation bias — they transmit the author's conviction, and a validator that inherits it cannot judge independently ({{ONTOLOGY}}: {{ONT_CONDUCT}}). The validator must re-confront the artifact cold, the way an external recipient would.
-3. Dispatch ONE fresh-context validator whose context starts empty — isolation is structural, not promised — using the [reviewer {{AGENT}}](../{{DIR_AGENTS}}/reviewer.md) (read-only, runs the suite, casts a verdict; NOT the [skeptic](../{{DIR_AGENTS}}/skeptic.md), whose charter forbids running commands and casting verdicts), via the dispatch pattern in [parallel-agents {{SKILL}}](parallel-agents.md), keeping the heavy reading out of the main context ({{DOCTRINE}} process 3); a cheaper model suffices for the validator unless the spec is subtle. Dispatch **fresh** — never resume a prior subagent session, which re-inherits its context and breaches the firewall. Where the host has no subagent capability, degrade: write the brief to a file and have the user run it in a separate fresh process; only as a last resort run the persona in-session and **stamp the verdict "SOFT ISOLATION — context bleed possible"** so the user discounts it. Never silently pretend a persona equals a fresh agent.
+3. Dispatch ONE fresh-context validator whose context starts empty — isolation is structural, not promised — using the [reviewer {{AGENT}}](../{{DIR_AGENTS}}/reviewer.md) (read-only, runs the suite, casts a verdict; NOT the [skeptic](../{{DIR_AGENTS}}/skeptic.md), whose charter forbids running commands and casting verdicts), via the dispatch pattern in [parallel-agents {{SKILL}}](parallel-agents.md), keeping the heavy reading out of the main context ({{DOCTRINE:context-economy}}); a cheaper model suffices for the validator unless the spec is subtle. Dispatch **fresh** — never resume a prior subagent session, which re-inherits its context and breaches the firewall. Where the host has no subagent capability, degrade: write the brief to a file and have the user run it in a separate fresh process; only as a last resort run the persona in-session and **stamp the verdict "SOFT ISOLATION — context bleed possible"** so the user discounts it. Never silently pretend a persona equals a fresh agent.
 4. Inside the fresh context, FIRST derive the rubric blind: from the task ALONE — before looking at the artifact — write a numbered list of observable acceptance criteria, each a yes/no test with a stated check method (a command to run, an output to see, a behaviour to exercise), tagged must-have or nice-to-have. FREEZE this list. Deriving it inside the firewall, from the task and not the solution, is what prevents criteria-fitting — the rubric cannot be bent to match what the artifact happens to do.
-5. THEN reveal the artifact and rule each criterion against it under an inverted burden of proof: actively check it — run the command, exercise the behaviour, read the named output ({{LAW}} III — verify by running, never assume) — and record `Cn: PASS | FAIL | UNVERIFIABLE — <evidence: the exact output/behaviour checked>`. Default is NOT-PASS: mark PASS only after actively confirming; a criterion that cannot be checked is UNVERIFIABLE (a finding, not a pass — name the missing evidence). Flag any **Extra** the artifact added beyond the spec, but cut gold-plating both ways — never FAIL the artifact for a requirement the task never asked for. The validator does NOT fix, refactor, or polish; it only rules.
-6. Return the independent verdict: the per-criterion table, then the overall gate — **SATISFIES** (every must-have PASS, no FAIL), **SATISFIES-WITH-GAPS** (must-haves pass, a nice-to-have fails), or **DOES-NOT-SATISFY** (any must-have FAIL or UNVERIFIABLE), listing the failing criteria with evidence. Report "could not find a fault" as not-proven-false, never as "proven correct". Surface it for the user to decide; the gate advises and applies no changes — write no code, push nothing ({{LAW}} IV, {{DOCTRINE}} process 5). On DOES-NOT-SATISFY, hand the failures to the solver (optionally via [review-response](review-response.md)) and re-run fresh-eyes after the fix rather than letting the original context relitigate the ruling.
+5. THEN reveal the artifact and rule each criterion against it under an inverted burden of proof: actively check it — run the command, exercise the behaviour, read the named output ({{LAW:verify-before-asserting}} — verify by running, never assume) — and record `Cn: PASS | FAIL | UNVERIFIABLE — <evidence: the exact output/behaviour checked>`. Default is NOT-PASS: mark PASS only after actively confirming; a criterion that cannot be checked is UNVERIFIABLE (a finding, not a pass — name the missing evidence). Flag any **Extra** the artifact added beyond the spec, but cut gold-plating both ways — never FAIL the artifact for a requirement the task never asked for. The validator does NOT fix, refactor, or polish; it only rules.
+6. Return the independent verdict: the per-criterion table, then the overall gate — **SATISFIES** (every must-have PASS, no FAIL), **SATISFIES-WITH-GAPS** (must-haves pass, a nice-to-have fails), or **DOES-NOT-SATISFY** (any must-have FAIL or UNVERIFIABLE), listing the failing criteria with evidence. Report "could not find a fault" as not-proven-false, never as "proven correct". Surface it for the user to decide; the gate advises and applies no changes — write no code, push nothing ({{LAW:deletion-is-deliberate}}, {{DOCTRINE:consent-before-push}}). On DOES-NOT-SATISFY, hand the failures to the solver (optionally via [review-response](review-response.md)) and re-run fresh-eyes after the fix rather than letting the original context relitigate the ruling.
 
 ## Done when
 - A fresh context that never saw the solving session derived the acceptance criteria from the original task alone, froze them before seeing the artifact, ruled each PASS/FAIL/UNVERIFIABLE with evidence by checking the live artifact, and returned an overall gate (SATISFIES / SATISFIES-WITH-GAPS / DOES-NOT-SATISFY) for the user to weigh — or, where no true isolation was possible, the verdict is stamped soft-isolation so it is discounted.

package/src/skills/frontend-design.md

@@ -29,7 +29,7 @@ preview tool) — the second-pass critique in step 6 cannot run without one.
 5. Avoid the three tells unless the brief truly calls for them: (a) cream
    `#F4F1EA` + high-contrast serif + terracotta accent; (b) near-black + acid-green
    or vermilion accent; (c) broadsheet hairline rules, zero radius, dense columns.
-6. Second pass — critique against the brief ({{LAW}} III): screenshot the result
+6. Second pass — critique against the brief ({{LAW:verify-before-asserting}}): screenshot the result
    and read it. If any part reads like the generic default you'd produce for any
    similar page, revise it. Spend boldness in one place and keep the rest quiet;
    remove one accessory. Hold the quality floor without announcing it — responsive,

package/src/skills/geneseed.md

@@ -5,10 +5,10 @@
 **Trigger:** the user mentions Geneseed, the harness, or `AGENT.md`; asks how the install is set up; asks to change its theme, footprint, posture, mode, doctrine packs or excluded rules — or you need to know what {{LAWS}}, {{AGENTS}}, or {{SKILLS}} this install carries.
 
 ## Procedure
-1. **Locate.** Run `geneseed status --json` first: `installs` lists every install on this machine — host, scope, root, state, theme, footprint, posture, mode, packs, excluded rules — and `rebuild`, the command that reproduces each one exactly. `geneseed` not on PATH → ask the user before using `npx geneseed` (it downloads the package), and prefix every command below the same way. Still nothing → look for a host root file: `~/.config/opencode/AGENT.md` or `.opencode/AGENT.md` (OpenCode), `~/.claude/CLAUDE.md` or `.claude/` (Claude Code), `.openclaude/` (OpenClaude), `AGENTS.md` beside `.bob/` or `.github/` (Bob, Copilot). None → say so; never install to "fix" it.
-2. **Read state** with the read-only verbs, cheapest first ({{DOCTRINE}} process 3): `geneseed status --json`, `geneseed version`, `geneseed catalog` (optionally `agents|skills|laws|ontology|doctrines`), `geneseed doctor`, `geneseed diff`, `geneseed mcp`, `geneseed memory list`, `geneseed exclude list`.
-3. **Read a piece** from disk, not from recall ({{LAW}} III): `<root>/agents/<name>.md`, `<root>/skills/<name>/SKILL.md`, `<root>/memory/`, `<root>/notebook/`. The {{ONTOLOGY}}, the {{LAWS}} and the active {{DOCTRINES}} are numbered `## N. …` sections of the install's root file.
-4. **Change an install only when the user asked for that change** ({{LAW}} II). Take that install's `rebuild` command from step 1, edit only the flag the user named (add it if the command omits it — `--posture` and `--mode` are left out at their defaults) — `--theme`, `--footprint lean|full`, `--posture`, `--mode direct|foreman`, `--doctrines craft,rigor|none`, `--exclude-rules "process 7"|none` — dry-run it first by running the same flags through `geneseed validate`, show the command, and run it once the user agrees. Never rebuild from a bare `geneseed build`: every omitted flag resets that setting to the generator default. Confirm with `geneseed status`.
+1. **Locate.** Run `geneseed status --json` first: `installs` lists every install on this machine — host, scope, root, state, theme, footprint, posture, mode, packs, excluded rules — and `rebuild`, the command that reproduces each one exactly. `geneseed` not on PATH → ask the user before using `npx geneseed` (it downloads the package), and prefix every command below the same way. Still nothing → look for a host root file: `~/.config/opencode/AGENT.md` or `.opencode/AGENT.md` (OpenCode), `~/.claude/CLAUDE.md` or `.claude/` (Claude Code), `.openclaude/` (OpenClaude), `AGENTS.md` beside `.bob/` (Bob). None → say so; never install to "fix" it.
+2. **Read state** with the read-only verbs, cheapest first ({{DOCTRINE:context-economy}}): `geneseed status --json`, `geneseed version`, `geneseed catalog` (optionally `agents|skills|laws|ontology|doctrines`), `geneseed doctor`, `geneseed diff`, `geneseed mcp`, `geneseed memory list`, `geneseed exclude list`.
+3. **Read a piece** from disk, not from recall ({{LAW:verify-before-asserting}}): `<root>/agents/<name>.md`, `<root>/skills/<name>/SKILL.md`, `<root>/memory/`, `<root>/notebook/`. The {{ONTOLOGY}}, the {{LAWS}} and the active {{DOCTRINES}} are numbered `## N. …` sections of the install's root file.
+4. **Change an install only when the user asked for that change** ({{LAW:one-intent-one-act}}). Take that install's `rebuild` command from step 1, edit only the flag the user named (add it if the command omits it — `--posture` and `--mode` are left out at their defaults) — `--theme`, `--footprint lean|full`, `--posture`, `--mode direct|foreman`, `--doctrines craft,rigor|none`, `--exclude-rules "process 7"|none` — dry-run it first by running the same flags through `geneseed validate`, show the command, and run it once the user agrees. Never rebuild from a bare `geneseed build`: every omitted flag resets that setting to the generator default. Confirm with `geneseed status`.
 5. **Other writes also need the user's word:** `geneseed memory rm <name>`, `geneseed exclude add|remove <path>`, `geneseed web start|stop`, `geneseed uninstall --target <root> --yes`. Personal rules and the profile belong to their own {{SKILLS}}; do not edit `user-rules.md` or `PROFILE.md` from here.
 6. **Never on your own initiative:** `geneseed setup` (interactive only), `geneseed upgrade`, `geneseed update`, `geneseed bootstrap`, `geneseed sync-self`, `geneseed rebuild-all`, `geneseed migrate`, `geneseed link`, `geneseed unlink`. `learn`, `context` and the `*-gate` verbs are `geneseed-hook` verbs the host's hooks run — never run them by hand.
 7. Directory and section names are plain English in every theme; only prose changes. Do not search by flavour words.