geneseed 3.10.0 → 3.12.0

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;
+}