geneseed 3.11.0 → 3.12.0

package/js/hosts/installs.mjs

@@ -230,6 +230,27 @@ function leadOfDir(d, names) {
 export const postureOfDir = (d) => leadOfDir(d, discoverNames('postures', 'peer'));
 export const modeOfDir = (d) => leadOfDir(d, discoverNames('modes', 'direct'));
 
+/**
+ * The loop skill's default trust preset, read back off a deployed install — `null` when no
+ * loop skill is deployed there.
+ *
+ * CARRIED BY THE SKILL, NOT BY A CARRIER: `--trust` is the one build axis with zero always-on
+ * footprint, so it is not in AGENT.md to be found. The skill renders a literal
+ * `Default trust preset: **<Label>**` line, and this scans the places an emit lands it: the
+ * native layer (`skills/loop/SKILL.md`, in the root itself for a global install and under the
+ * host's `projectMarker` for a project one) and the plain bundle (`skills/loop.md`).
+ */
+const TRUST_RE = /^Default trust preset: \*\*(Prudent|Balanced|Aggressive)\*\*/m;
+export function trustOfDir(d) {
+  for (const base of ['', ...HOSTS.map((h) => h.projectMarker)]) {
+    for (const rel of [['skills', 'loop', 'SKILL.md'], ['skills', 'loop.md']]) {
+      const m = TRUST_RE.exec(readMaybe(path.join(d, base, ...rel)) ?? '');
+      if (m) return m[1].toLowerCase();
+    }
+  }
+  return null;
+}
+
 /** The `Active packs:` marker line the template emits, in one of the five carriers. */
 const ACTIVE_PACKS_RE = /^Active packs:[ \t]*(.+?)[ \t]*$/m;
 

package/js/inspect/checks-authoring.mjs

@@ -25,6 +25,7 @@ import { NO_WINDOW } from '../lib/proc.mjs';
 import {
   folderSkillProblems, registryProblems, secretProblems, vendorPinProblems,
 } from './checks-repo.mjs';
+import { catalogProblems } from '../loop/catalog.mjs';
 import { LAW_CLASS, LAW_CLASSES, SKILL_CLASS } from './inventory.mjs';
 import { NOTE, globSorted, has, isDir, isFile, rglob, srcStems } from './scan.mjs';
 import { spawnSync } from 'node:child_process';
@@ -836,6 +837,15 @@ function loadLearnPromptHead() {
     + 'When in doubt, output exactly: NOTHING.';
 }
 
+/**
+ * The shipped loop catalogue parses and every shipped template passes the engine's own graph
+ * rules. Global and project bricks are deliberately out of scope: doctor judges what this
+ * checkout ships, not what a user wrote in their config.
+ */
+export function loopProblems() {
+  return catalogProblems({ projectRoot: null, globalLevel: false });
+}
+
 /**
  * `_harness_build._authoring_problems` — author-time gates on the source specs and plugins.
  *

package/js/inspect/diff.mjs

@@ -46,6 +46,7 @@ import {
 } from '../hosts/hosts.mjs';
 import {
   EMIT_HOST_SCOPE, defaultTheme, doctrinesForBuild, footprintOfDir, modeOfDir, postureOfDir,
+  trustOfDir,
   readJsonMaybe, readMaybe, themeOfDir,
 } from '../hosts/installs.mjs';
 import { unifiedDiff, splitLines } from '../lib/udiff.mjs';
@@ -175,6 +176,8 @@ export function diffCollect({ target = null, theme = null, emit = null, footprin
       // `null` (no marker) means unknown and renders at all four, which `doctrinesForBuild`
       // makes explicit rather than leaving to `makeCfg`'s parameter default two layers down.
       posture: postureOfDir(dir), mode: modeOfDir(dir), doctrines: doctrinesForBuild(dir),
+      // The loop skill's preset, or its `Default trust preset:` line reads as edited.
+      trust: trustOfDir(dir),
     }));
     // The one place a render depends on WHERE it is installed: a global Bob emit writes each
     // folder skill's absolute directory into its SKILL.md (see `writeNativeLayer`), so the

package/js/inspect/doctor.mjs

@@ -36,7 +36,7 @@ import { resolvePath } from '../hosts/hosts.mjs';
 import { installedDefaults, themeFiles } from '../hosts/installs.mjs';
 import { validateIsVendored } from '../hosts/native.mjs';
 import { printOut } from '../lib/fs.mjs';
-import { authoringProblems } from './checks-authoring.mjs';
+import { authoringProblems, loopProblems } from './checks-authoring.mjs';
 import {
   checkBuild, colorThemeProblems, renderedProblems, themeParityProblems,
 } from './checks-build.mjs';
@@ -217,6 +217,7 @@ export function doctorCollect({
   problems = problems.concat(ran('parity', 'Theme parity', themeParityProblems()));
   problems = problems.concat(ran('colors', 'Colour themes', colorThemeProblems()));
   problems = problems.concat(ran('authoring', 'Authoring gates', authoringProblems()));
+  problems = problems.concat(ran('loops', 'Loop catalogue', loopProblems()));
   problems = problems.concat(ran('shim', 'Hook shim', shimProbs));
   problems = problems.concat(ran('map', 'Module map', moduleMapProblems()));
   // P10c's `cli` check is GONE, and the reason is not that it stopped mattering. It hashed

package/js/inspect/inventory.mjs

@@ -91,6 +91,7 @@ export const LAW_CLASSES = ['security', 'process', 'verify', 'craft', 'context',
 export const SKILL_CLASS = {
   brainstorm: 'design', plan: 'design', council: 'design',
   workflow: 'design', 'parallel-agents': 'design', pipeline: 'design',
+  loop: 'design', 'brick-forge': 'design',
   'codebase-design': 'design', 'domain-modeling': 'design', wayfinder: 'design',
   tickets: 'design',
   develop: 'build', refactor: 'build', debug: 'build', migrate: 'build',

package/js/inspect/status.mjs

@@ -372,7 +372,7 @@ export function statusLines(d, color = false) {
     }
     const packs = p.doctrines.length ? p.doctrines.join(',') : 'no packs';
     const excl = p.excludeRules?.length ? `excluding ${p.excludeRules.join(',')}` : 'no rules excluded';
-    rows.push([`${p.host}:${p.scope}`, [p.state, p.theme, p.footprint, `${p.posture}/${p.mode}`,
+    rows.push([`${p.host}:${p.scope}`, [p.state, p.theme, p.footprint, `${p.posture}/${p.mode}/${p.trust}`,
       packs, excl].join(` ${DOT} `) + where]);
   }
 

package/js/loop/catalog.mjs

@@ -0,0 +1,116 @@
+/**
+ * Where bricks and loop templates come from, and which one wins.
+ *
+ * THREE ORIGINS, ONE LADDER. Shipped (this package's own `src/`), global (the user's, beside
+ * `installs.json` under XDG) and project (`<repo>/.geneseed/`, committed, shared with a team).
+ * A later origin replaces an earlier one BY NAME — that is the whole point: a team adapts the
+ * shipped `reproduce` to its stack without copying every template that uses it. The cost is
+ * that a fixed shipped brick stays masked by the override, so the override is reported
+ * (`overridden`), never silent.
+ *
+ * WHY SHIPPED BRICKS ARE READ FROM `src/`, NOT FROM AN INSTALL. The model never reads a brick
+ * file: `geneseed loop next` hands it the brick's prompt. So the CLI reads its own source and no
+ * host emit has to learn a new directory — four hosts get the catalogue for free and cannot drift.
+ *
+ * Templates are parsed with JSON.parse on purpose: they are read, never written back into a
+ * user's file, so the int/float distinction `parseJson` preserves has nowhere to matter.
+ */
+import { readdirSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { readText, isFile, isDir } from '../lib/fs.mjs';
+import { frontmatter } from '../hosts/hooks.mjs';
+import { SRC } from '../build/source.mjs';
+import { checkGraph } from './graph.mjs';
+
+export function userLoopsDir() {
+  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(base, 'geneseed');
+}
+
+const KEBAB = /^[a-z0-9][a-z0-9-]*$/;
+
+export function parseBrick(text, origin) {
+  const [fm, body] = frontmatter(text);
+  const get = (k) => (fm.get(k) ?? '').trim();
+  const name = get('name');
+  const problems = [];
+  if (!KEBAB.test(name)) problems.push(`name ${JSON.stringify(name)} must be kebab-case`);
+  const description = get('description');
+  if (!description) problems.push(`${name}: description is empty`);
+  const effect = get('effect');
+  if (effect !== 'read' && effect !== 'mutate') {
+    problems.push(`${name}: effect must be read or mutate, not ${JSON.stringify(effect)}`);
+  }
+  const agent = get('agent') || null;
+  const skill = get('skill') || null;
+  if (!agent === !skill) problems.push(`${name}: exactly one of agent or skill`);
+  const outcomes = get('outcomes').split(',').map((s) => s.trim()).filter(Boolean);
+  if (!outcomes.length) problems.push(`${name}: outcomes is empty`);
+  return {
+    brick: { name, description, effect, agent, skill, outcomes, body: body.trim(), origin },
+    problems,
+  };
+}
+
+const listFiles = (dir, ext) => (isDir(dir)
+  ? readdirSync(dir).filter((n) => n.endsWith(ext) && !n.startsWith('_') && n !== 'README.md').sort()
+  : []);
+
+function availability(brick, srcRoot) {
+  if (brick.agent && !isFile(path.join(srcRoot, 'agents', `${brick.agent}.md`))) {
+    return { available: false, reason: `agent ${brick.agent} is not shipped` };
+  }
+  if (brick.skill && !isFile(path.join(srcRoot, 'skills', `${brick.skill}.md`))
+    && !isDir(path.join(srcRoot, 'skills', brick.skill))) {
+    return { available: false, reason: `skill ${brick.skill} is not shipped` };
+  }
+  return { available: true };
+}
+
+export function loadCatalog({
+  projectRoot = process.cwd(), srcRoot = SRC, globalLevel = true,
+} = {}) {
+  const levels = [
+    ['shipped', path.join(srcRoot, 'bricks'), path.join(srcRoot, 'loops')],
+  ];
+  if (globalLevel) {
+    levels.push(['global', path.join(userLoopsDir(), 'bricks'), path.join(userLoopsDir(), 'loops')]);
+  }
+  if (projectRoot) {
+    levels.push(['project', path.join(projectRoot, '.geneseed', 'bricks'), path.join(projectRoot, '.geneseed', 'loops')]);
+  }
+  const bricks = new Map(); const templates = new Map(); const problems = []; const overridden = [];
+  for (const [origin, brickDir, loopDir] of levels) {
+    for (const f of listFiles(brickDir, '.md')) {
+      const { brick, problems: p } = parseBrick(readText(path.join(brickDir, f)), origin);
+      problems.push(...p.map((x) => `bricks/${f} (${origin}): ${x}`));
+      if (p.length) continue;
+      const prior = bricks.get(brick.name);
+      if (prior) overridden.push(`${brick.name} (${origin}, overrides ${prior.origin})`);
+      bricks.set(brick.name, { ...brick, ...availability(brick, srcRoot) });
+    }
+    for (const f of listFiles(loopDir, '.json')) {
+      let graph;
+      try { graph = JSON.parse(readText(path.join(loopDir, f))); } catch {
+        problems.push(`loops/${f}: not JSON`); continue;
+      }
+      const stem = f.slice(0, -'.json'.length);
+      if (graph.name !== stem) {
+        problems.push(`loops/${f}: name ${JSON.stringify(graph.name)} does not match the file name`);
+        continue;
+      }
+      templates.set(stem, { ...graph, origin });
+    }
+  }
+  return { bricks, templates, problems, overridden: overridden.sort() };
+}
+
+export function catalogProblems(opts = {}) {
+  const { bricks, templates, problems } = loadCatalog(opts);
+  const out = [...problems];
+  for (const [name, graph] of [...templates].sort(([a], [b]) => (a < b ? -1 : 1))) {
+    out.push(...checkGraph(graph, bricks).map((p) => `loops/${name}: ${p}`));
+  }
+  return out.sort();
+}

package/js/loop/cli.mjs

@@ -0,0 +1,151 @@
+/**
+ * `geneseed loop <action>` — the loop engine's only face. Every action prints exactly one JSON
+ * object: the loop skill is a model reading stdout, and a JSON error it can quote beats a
+ * stack trace it has to interpret. Exit 1 on any refusal so a script can still branch on it.
+ *
+ * NO SPAWN. The CLI's closure may not start processes, so git is the model's job: it pipes
+ * `git diff --cached --numstat` into `score --diff` and `git status --porcelain` into `record`.
+ * stdin is read only when it is not a TTY — a hand-run `geneseed loop record` must not hang.
+ *
+ * NO `--file`. `state.mjs`'s `LOOP_FILE` constant is the ROOT-RELATIVE path the engine filters
+ * out of every diff and porcelain check, so LOOP.md has to live at the git root of the worktree
+ * for that filter to mean anything. This entry finds that root itself — walking up from the cwd
+ * to the first directory holding `.git` (a directory for a normal clone, a FILE for a worktree
+ * or submodule) — rather than taking a path the caller could point anywhere.
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { readText, writeText, isFile, printOut } from '../lib/fs.mjs';
+import { loadCatalog, catalogProblems, parseBrick } from './catalog.mjs';
+import { checkGraph } from './graph.mjs';
+import { parseNumstat, DEFAULT_PRESET } from './score.mjs';
+import { gitRootOf, gitDirOf, currentBranch } from '../hosts/gitref.mjs';
+import {
+  initState, nextStep, scoreDeclared, scoreDiff, recordOutcome, decideAwaiting,
+  renderLoopFile, parseLoopFile, LOOP_FILE,
+} from './state.mjs';
+
+const emit = (obj) => { printOut(`${JSON.stringify(obj)}\n`); return obj.error || obj.ok === false ? 1 : 0; };
+const stdin = () => (process.stdin.isTTY ? '' : readFileSync(0, 'utf8'));
+const list = (s) => (s ? String(s).split(',').map((x) => x.trim()).filter(Boolean) : null);
+
+function requireRoot() {
+  const root = gitRootOf(process.cwd());
+  if (!root) throw new Error('not inside a git repository');
+  return root;
+}
+
+/**
+ * When `score --diff`/`decide` closes a unit (`commit: true`), write the commit message to
+ * `<gitdir>/LOOP_COMMIT_MSG` — never tracked, never part of any diff — so the loop's own
+ * automation never has to quote a message on a command line (`js/hosts/hooks.mjs`'s
+ * `loopExempt` only whitelists `git commit -F <path>`).
+ *
+ * `gitdir` is RESOLVED BY THE CALLER, before `withState` ran the state change (X6, fix round
+ * 2): a malformed `.git` FILE makes `gitDirOf` throw, and that throw must abort the action
+ * before anything about the loop's state has moved, not after. Adds `message_file` to the
+ * result for the skill to read back, with forward slashes (`C:/...`) even on Windows — Git
+ * Bash and git itself both accept that form on every platform, and a backslash-laden path
+ * breaks when a later shell command tries to use it unquoted.
+ */
+function writeCommitMessage(root, gitdir, result) {
+  if (!result || result.commit !== true) return result;
+  const branch = currentBranch(root);
+  const slug = branch && branch.startsWith('loop/') ? branch.slice('loop/'.length) : 'loop';
+  const file = path.join(gitdir, 'LOOP_COMMIT_MSG');
+  writeText(file, `loop(${slug}): iteration ${result.iteration} — ${result.intent || 'setup'}\n\n${result.trailers}\n`);
+  return { ...result, message_file: file.replaceAll('\\', '/') };
+}
+
+function withState(fn) {
+  const root = requireRoot();
+  const file = path.join(root, LOOP_FILE);
+  if (!isFile(file)) throw new Error(`${file} does not exist — run \`geneseed loop init\` first`);
+  const state = parseLoopFile(readText(file));
+  const { bricks } = loadCatalog({ projectRoot: root });
+  const result = fn(state, bricks);
+  writeText(file, renderLoopFile(state));
+  return result;
+}
+
+function resolveGraph(spec, catalog) {
+  if (spec && spec.endsWith('.json')) return JSON.parse(readText(path.resolve(spec)));
+  const g = catalog.templates.get(spec);
+  if (!g) throw new Error(`no loop template named ${JSON.stringify(spec)}`);
+  const { origin, ...graph } = g;
+  return graph;
+}
+
+const ACTIONS = {
+  check(args) {
+    if (args.brick) {
+      const { problems } = parseBrick(readText(path.resolve(args.brick)), 'checked');
+      return { ok: !problems.length, problems };
+    }
+    if (args.graph) {
+      const catalog = loadCatalog({ projectRoot: process.cwd() });
+      const problems = checkGraph(resolveGraph(args.graph, catalog), catalog.bricks);
+      return { ok: !problems.length, problems };
+    }
+    // The bare check doubles as the catalogue LISTING the loop skill composes a free graph
+    // from — frontmatter only: a brick's body reaches the model through `next`, for the node
+    // the engine chose, never as a menu.
+    const problems = catalogProblems({ projectRoot: process.cwd() });
+    const { bricks, templates, overridden } = loadCatalog({ projectRoot: process.cwd() });
+    const byName = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+    return {
+      ok: !problems.length, problems,
+      templates: [...templates.keys()].sort(byName),
+      bricks: [...bricks.values()].sort((a, b) => byName(a.name, b.name))
+        .map(({ body, available, reason, ...b }) => ({ ...b, available, ...(reason ? { reason } : {}) })),
+      overridden,
+    };
+  },
+  init(args) {
+    const root = requireRoot();
+    const file = path.join(root, LOOP_FILE);
+    if (isFile(file)) throw new Error(`${file} already exists — a loop is already running here`);
+    if (!args.title || !args.requirement || !args.graph) throw new Error('init needs --title, --requirement and --graph');
+    const catalog = loadCatalog({ projectRoot: root });
+    const graph = resolveGraph(args.graph, catalog);
+    const problems = checkGraph(graph, catalog.bricks);
+    if (problems.length) return { error: 'the graph does not pass loop check', problems };
+    const state = initState({ title: args.title, requirement: args.requirement, graph, preset: args.preset || DEFAULT_PRESET });
+    writeText(file, renderLoopFile(state));
+    return { file, graph: graph.name, preset: state.preset, status: state.status };
+  },
+  next: () => withState((s, b) => nextStep(s, b)),
+  score(args) {
+    if (args.diff) {
+      // X6: resolve (and validate) the gitdir BEFORE withState runs the state change, so a
+      // malformed `.git` file errors without advancing the loop.
+      const root = requireRoot();
+      const gitdir = gitDirOf(root);
+      return writeCommitMessage(root, gitdir, withState((s) => scoreDiff(s, parseNumstat(stdin()))));
+    }
+    if (!args.declared) throw new Error('score needs --declared or --diff');
+    return withState((s) => scoreDeclared(s, {
+      actions: list(args.actions), writeSet: list(args.writeSet), intent: args.intent ?? null,
+    }));
+  },
+  record(args) {
+    if (!args.outcome) throw new Error('record needs --outcome');
+    const card = args.card ? JSON.parse(args.card) : null;
+    const raw = stdin();
+    return withState((s, b) => recordOutcome(s, b, args.outcome, { card, porcelain: raw ? raw.replace(/\r\n/g, '\n').trimEnd() : null }));
+  },
+  decide(args) {
+    // X6: same ordering as `score --diff` above.
+    const root = requireRoot();
+    const gitdir = gitDirOf(root);
+    return writeCommitMessage(root, gitdir, withState((s, b) => decideAwaiting(s, b, args.verdict, args.note ?? '')));
+  },
+};
+
+export function cmdLoop(args) {
+  try {
+    return emit(ACTIONS[args.action](args));
+  } catch (e) {
+    return emit({ error: e.message });
+  }
+}

package/js/loop/graph.mjs

@@ -0,0 +1,145 @@
+/**
+ * The rules a loop graph must satisfy before a single node runs. ONE function, three callers:
+ * `geneseed loop check`, the doctor over the shipped templates, and `loop init` over a graph the
+ * model composed at run time — the composed graph never meets the doctor, so the engine has to
+ * carry the same check or free composition would be unchecked composition.
+ *
+ * WHY EVERY CYCLE NEEDS A DECLARED LOOP. Edges are free, so a graph can loop anywhere. A loop
+ * that terminates only because the model eventually reports a different outcome is a loop that
+ * may not terminate; a declared `max` is what turns "should stop" into "will stop". The check is
+ * structural (strongly connected components), so it needs no simulation and cannot miss a path.
+ *
+ * Problems are returned in a fixed order — per node, per edge, per outcome, then loops — so a
+ * test can write the expected list out instead of sorting it.
+ *
+ * WHY A CYCLE INSIDE AN ITERATION NEEDS ITS OWN LOOP. The whole-SCC check (rule 4) is satisfied
+ * by the iteration loop alone, since every node in an iteration is reachable from every other —
+ * but the runtime gives a node outside every *inner* loop exactly one entry per iteration (no
+ * re-entry at all), so a cycle that never reaches the iteration head and is not inside its own
+ * declared inner loop would hit that "max of 0" path by construction, not by a model's mistake.
+ * The static check has to refuse that graph, not just the ones the runtime would loop forever on.
+ */
+import { WEIGHTS } from './score.mjs';
+
+export const TERMINALS = new Set(['$close', '$stop']);
+export const ENGINE_MAX_ITERATIONS = 20;
+
+export function iterationLoop(graph) {
+  return (graph.loops ?? []).find((l) => l.iteration === true);
+}
+
+/** Tarjan — the strongly connected components of the node graph (terminals excluded). */
+function components(nodes, edges) {
+  const succ = new Map(nodes.map((n) => [n, []]));
+  for (const e of edges) if (succ.has(e.from) && succ.has(e.to)) succ.get(e.from).push(e.to);
+  let index = 0;
+  const idx = new Map(); const low = new Map(); const stack = []; const on = new Set(); const out = [];
+  const visit = (v) => {
+    idx.set(v, index); low.set(v, index); index += 1; stack.push(v); on.add(v);
+    for (const w of succ.get(v)) {
+      if (!idx.has(w)) { visit(w); low.set(v, Math.min(low.get(v), low.get(w))); }
+      else if (on.has(w)) low.set(v, Math.min(low.get(v), idx.get(w)));
+    }
+    if (low.get(v) === idx.get(v)) {
+      const comp = [];
+      for (;;) { const w = stack.pop(); on.delete(w); comp.push(w); if (w === v) break; }
+      const selfLoop = comp.length === 1 && succ.get(v).includes(v);
+      if (comp.length > 1 || selfLoop) out.push(comp.sort());
+    }
+  };
+  for (const n of nodes) if (!idx.has(n)) visit(n);
+  return out;
+}
+
+export function checkGraph(graph, bricks) {
+  const problems = [];
+  const nodes = Array.isArray(graph.nodes) ? graph.nodes : [];
+  const edges = Array.isArray(graph.edges) ? graph.edges : [];
+  const loops = Array.isArray(graph.loops) ? graph.loops : [];
+  const nodeSet = new Set(nodes);
+
+  // rule 1 — nodes name available bricks
+  for (const n of nodes) {
+    const brick = bricks.get(n);
+    if (!brick) problems.push(`node ${n}: no brick named ${n}`);
+    else if (!brick.available) problems.push(`node ${n}: brick unavailable (${brick.reason})`);
+  }
+  // rule 1 — edge endpoints; rule 2 — edges use declared outcomes
+  for (const e of edges) {
+    const label = `edge ${e.from} --${e.on}--> ${e.to}`;
+    if (!nodeSet.has(e.from)) { problems.push(`${label}: ${e.from} is not a node`); continue; }
+    if (!nodeSet.has(e.to) && !TERMINALS.has(e.to)) {
+      problems.push(`${label}: ${e.to} is not a node, $close or $stop`);
+      continue;
+    }
+    const brick = bricks.get(e.from);
+    if (brick && !brick.outcomes.includes(e.on)) problems.push(`${label}: ${e.on} is not an outcome of ${e.from}`);
+  }
+  // rule 2 — exactly one edge per declared outcome (nodes in sorted order)
+  for (const n of [...nodes].sort()) {
+    const brick = bricks.get(n);
+    if (!brick) continue;
+    for (const o of brick.outcomes) {
+      const count = edges.filter((e) => e.from === n && e.on === o).length;
+      if (count === 0) problems.push(`node ${n}: no edge for outcome ${o}`);
+      else if (count > 1) problems.push(`node ${n}: ${count} edges for outcome ${o}`);
+    }
+  }
+  // rule 3 — start, and $close reachable
+  if (!nodeSet.has(graph.start)) {
+    problems.push(`start ${graph.start} is not a node`);
+  } else {
+    const seen = new Set([graph.start]); const queue = [graph.start];
+    while (queue.length) {
+      const v = queue.shift();
+      for (const e of edges) {
+        if (e.from === v && !seen.has(e.to)) { seen.add(e.to); if (nodeSet.has(e.to)) queue.push(e.to); }
+      }
+    }
+    if (!seen.has('$close')) problems.push(`$close is not reachable from ${graph.start}`);
+  }
+  // rule 5 — loops are well formed
+  for (const l of loops) {
+    if (!Number.isInteger(l.max) || l.max < 1) problems.push(`loop ${l.name}: max must be a positive integer`);
+    else if (l.iteration === true && l.max > ENGINE_MAX_ITERATIONS) {
+      problems.push(`loop ${l.name}: max ${l.max} is above the engine ceiling of ${ENGINE_MAX_ITERATIONS}`);
+    }
+    for (const n of l.nodes ?? []) if (!nodeSet.has(n)) problems.push(`loop ${l.name}: ${n} is not a node`);
+  }
+  const iterations = loops.filter((l) => l.iteration === true).length;
+  if (iterations !== 1) problems.push(`${iterations} loops are marked iteration; exactly one must be`);
+  // rule 4 — every cycle is inside a declared loop
+  for (const comp of components(nodes, edges)) {
+    const covered = loops.some((l) => comp.every((n) => (l.nodes ?? []).includes(n)));
+    if (!covered) problems.push(`cycle ${comp.join(', ')} has no declared loop around it`);
+  }
+  // rule 4b — a cycle that never reaches the iteration head needs its own non-iteration loop
+  const iterationLoops = loops.filter((l) => l.iteration === true);
+  if (iterationLoops.length === 1) {
+    const [iteration] = iterationLoops;
+    const head = iteration.nodes?.[0];
+    const innerEdges = edges.filter((e) => e.to !== head);
+    for (const comp of components(nodes, innerEdges)) {
+      const covered = loops.some((l) => l !== iteration && comp.every((n) => (l.nodes ?? []).includes(n)));
+      if (!covered) problems.push(`cycle ${comp.join(', ')} inside an iteration has no inner loop around it`);
+    }
+    // rule 4c — the iteration is entered only at its head: the runtime opens and closes units
+    // on re-entering nodes[0], so entering anywhere else runs a unit with no head behind it.
+    const inside = new Set(iteration.nodes ?? []);
+    if (head !== undefined) {
+      if (inside.has(graph.start) && graph.start !== head) {
+        problems.push(`start ${graph.start} is inside the iteration but is not its head ${head}`);
+      }
+      for (const e of edges) {
+        if (!inside.has(e.from) && inside.has(e.to) && e.to !== head) {
+          problems.push(`edge ${e.from} --${e.on}--> ${e.to} enters the iteration at ${e.to}, not at its head ${head}`);
+        }
+      }
+    }
+  }
+  // template weight overrides
+  for (const k of Object.keys(graph.weights ?? {})) {
+    if (!Object.hasOwn(WEIGHTS, k)) problems.push(`weights: ${k} is not an action`);
+  }
+  return problems;
+}

package/js/loop/score.mjs

@@ -0,0 +1,143 @@
+/**
+ * The loop's risk arithmetic — pure, and imported by the build driver (the `--trust` choices),
+ * so it must stay free of every import but node builtins: the driver's closure bans
+ * child_process outright.
+ *
+ * WHY MAX AND NOT A SUM. A block that renames ten things and changes one public contract is a
+ * contract change; adding the renames up would let ten trivial edits outvote one critical one
+ * in the wrong direction — or, with a sum, let a pile of trivia trip a blocking stop that no
+ * single edit deserves. One critical action makes the block critical, nothing else does.
+ *
+ * WHY THE DIFF CAN ONLY RAISE THE SCORE. The declared score is the identify brick's account of
+ * what it is about to do; the diff is what it did. The account may be optimistic, never the
+ * other way round, so the actual score is max(declared, escalations) — an iteration never earns
+ * a lower tier by under-delivering.
+ */
+import { Buffer } from 'node:buffer';
+
+export const WEIGHTS = Object.freeze({
+  format: 0.1, imports: 0.1, rename: 0.2, logic: 0.4, 'new-file': 0.4,
+  api: 0.8, delete: 0.8, architecture: 0.9,
+});
+
+/** [silent ceiling, soft ceiling] — above the second is blocking. */
+export const PRESETS = Object.freeze({
+  prudent: Object.freeze([0.1, 0.3]),
+  balanced: Object.freeze([0.2, 0.6]),
+  aggressive: Object.freeze([0.4, 0.8]),
+});
+export const DEFAULT_PRESET = 'balanced';
+
+/** More deleted lines than this in one iteration counts as a code deletion. */
+export const DELETION_LINES = 20;
+
+const RANK = { silent: 0, soft: 1, blocking: 2 };
+
+export function declaredRisk(actions, overrides = {}) {
+  const w = { ...WEIGHTS, ...overrides };
+  let score = 0;
+  for (const a of actions) {
+    if (!Object.hasOwn(w, a)) {
+      throw new Error(`unknown action ${JSON.stringify(a)} — one of ${Object.keys(w).join(', ')}`);
+    }
+    score = Math.max(score, w[a]);
+  }
+  return score;
+}
+
+const C_ESCAPES = { a: 7, b: 8, t: 9, n: 10, v: 11, f: 12, r: 13 };
+
+/**
+ * Undo git's C-quoting (core.quotepath, on by default): `"caf\303\251.js"` is `café.js`, its
+ * octal escapes being the UTF-8 bytes. Decoded here rather than by passing `-c core.quotepath=off`
+ * in the skill's verify command, so every caller of `score --diff` is covered, not just the one
+ * the skill types.
+ */
+function unquote(s) {
+  if (s.length < 2 || !s.startsWith('"') || !s.endsWith('"')) return s;
+  const body = s.slice(1, -1);
+  const bytes = [];
+  for (let i = 0; i < body.length; i += 1) {
+    if (body[i] !== '\\') { bytes.push(...Buffer.from(body[i])); continue; }
+    const octal = /^[0-7]{3}/.exec(body.slice(i + 1));
+    if (octal) { bytes.push(Number.parseInt(octal[0], 8)); i += 3; continue; }
+    i += 1;
+    bytes.push(C_ESCAPES[body[i]] ?? body.charCodeAt(i));
+  }
+  return Buffer.from(bytes).toString('utf8');
+}
+
+/**
+ * A numstat path, as [new, old] for a rename or [path] otherwise. Git prints a rename as
+ * `pre/{a => b}/post` (either side may be empty, leaving a `//` to collapse), or as `old => new`
+ * — always that form, each side quoted, when either side needs quoting.
+ */
+function numstatPaths(raw) {
+  const brace = /^(.*)\{(.*) => (.*)\}(.*)$/.exec(raw);
+  if (brace) {
+    const [, pre, a, b, post] = brace;
+    const join = (mid) => `${pre}${mid}${post}`.replace(/\/{2,}/g, '/').replace(/^\//, '');
+    return [join(b), join(a)];
+  }
+  const arrow = raw.indexOf(' => ');
+  if (arrow >= 0) return [unquote(raw.slice(arrow + 4)), unquote(raw.slice(0, arrow))];
+  return [unquote(raw)];
+}
+
+/**
+ * `git diff --numstat` rows. A binary file reports `-` for both counts; it counts as 0. A rename
+ * yields BOTH paths — the new one with the counts, the old one with 0/0 — so a rename out of or
+ * into the write set is checked on each side without counting its lines twice.
+ */
+export function parseNumstat(text) {
+  const rows = [];
+  for (const line of String(text).split(/\r?\n/)) {
+    const m = /^(\S+)\t(\S+)\t(.+)$/.exec(line);
+    if (!m) continue;
+    const n = (s) => (s === '-' ? 0 : Number.parseInt(s, 10) || 0);
+    const [file, old] = numstatPaths(m[3]);
+    rows.push({ file, added: n(m[1]), deleted: n(m[2]) });
+    if (old !== undefined) rows.push({ file: old, added: 0, deleted: 0 });
+  }
+  return rows;
+}
+
+const slash = (p) => p.replaceAll('\\', '/');
+
+export function actualRisk(declared, files, { writeSet = [], contracts = [], overrides = {} } = {}) {
+  const w = { ...WEIGHTS, ...overrides };
+  let score = declared;
+  const reasons = [];
+  const inSet = new Set(writeSet.map(slash));
+  const outside = files.filter((f) => !inSet.has(slash(f.file)));
+  if (outside.length) {
+    score = Math.max(score, 0.8);
+    reasons.push(`outside the write set: ${outside.map((f) => slash(f.file)).join(', ')}`);
+  }
+  const deleted = files.reduce((n, f) => n + f.deleted, 0);
+  if (deleted > DELETION_LINES) {
+    score = Math.max(score, w.delete);
+    reasons.push(`${deleted} lines deleted`);
+  }
+  const contractSet = new Set(contracts.map(slash));
+  const hit = files.filter((f) => contractSet.has(slash(f.file)));
+  if (hit.length) {
+    score = Math.max(score, w.api);
+    reasons.push(`contract files: ${hit.map((f) => slash(f.file)).join(', ')}`);
+  }
+  return { score, reasons };
+}
+
+export function decide(score, preset) {
+  const t = PRESETS[preset];
+  if (!t) throw new Error(`unknown preset ${JSON.stringify(preset)} — one of ${Object.keys(PRESETS).join(', ')}`);
+  if (score <= t[0]) return 'silent';
+  if (score <= t[1]) return 'soft';
+  return 'blocking';
+}
+
+export function worst(a, b) {
+  if (a === undefined || a === null) return b;
+  if (b === undefined || b === null) return a;
+  return RANK[a] >= RANK[b] ? a : b;
+}