geneseed 3.10.0 → 3.12.0

package/js/hosts/hooks.mjs

@@ -56,6 +56,7 @@ import { NO_WINDOW } from '../lib/proc.mjs';
 import {
   GATE_LEDGER, resolveMemoryDir, resolvePath, sovereignBypass,
 } from './hosts.mjs';
+import { currentBranch, gitRootOf, loopLaunched } from './gitref.mjs';
 
 const ROOT = path.resolve(import.meta.dirname, '../..');
 
@@ -599,6 +600,88 @@ const GIT_GATE_RE = /\bgit\b[^\n]*\b(?:commit|push)\b/;
 const DESTRUCTIVE_GIT_RE =
   /\bgit\b[^\n]*\b(?:reset\s+--hard|clean\s+-[a-zA-Z]*f|branch\s+-D|checkout\s+--\s|push\s+[^\n]*--force)/;
 
+// `loopExempt` — a WHITELIST, not the blacklist this replaced. A false ask costs one prompt; a
+// false allow publishes. So the exemption holds only when the ENTIRE command is built from
+// forms read in full below, on a branch a loop was actually launched on (LOOP.md's state
+// marker, left by `geneseed loop init` — not just a name starting with `loop/`, which anyone
+// can type). `currentBranch`/`gitRootOf`/`loopLaunched` live in `./gitref.mjs` — the one
+// fs-only reader this file shares with `js/loop/cli.mjs`'s commit-message writer.
+
+// No newline, backtick, or `$(` substitution anywhere — these can smuggle a second command (or
+// a shared-branch target) past every check below, so the command is refused before it is even
+// split. `<`/`>` are refused too: a redirect can both hide a second effect and, as the review
+// found, trail off the end of an otherwise-whitelisted push (`HEAD:main>/dev/null`). A single
+// `&` — not doubled into `&&` — is refused too: a shell runs `a & b` as TWO commands just like
+// `a && b`, and the review found it unparsed by the splitter below, which only recognised the
+// doubled form. `(?<!&)&(?!&)` matches a lone `&` without also matching either half of `&&`.
+const UNSAFE_CHARS_RE = /[\n`<>]|\$\(|(?<!&)&(?!&)/;
+
+// The only three git shapes a loop's own automation ever needs: adding unquoted paths,
+// committing via `-F`/`--file` (so the message text, which may contain anything, never has to
+// be quoted on this command line at all — see `js/loop/cli.mjs`'s LOOP_COMMIT_MSG), and
+// read-only inspection. The token class `[\w./:@^~=+,-]` excludes quotes, braces, `!`, `*`,
+// `$` and `&` — a brace or glob expansion (`{a,b}`, `*`) is exactly how a shell can turn one
+// whitelisted-looking token into several unknown ones, so no pattern's path/arg tokens may
+// contain them. The SAME class is the `-F`/`--file` path, not the looser `[^\s'"]+` this once
+// was: with that loose class, `git commit -F {m,--amend}` brace-expands to `git commit -F m
+// --amend` and `git commit -F m*` glob-expands to whatever matches — either turns a commit of
+// the loop's own message file into an amend of the last one. `ARG_RE` already accepts a drive
+// letter (`C:/…`) via its `:`, so tightening it here costs nothing the loop's own writer uses.
+const ARG_RE = '[\\w./:@^~=+,-]+';
+const SEG_ADD_RE = new RegExp(`^git\\s+add(\\s+${ARG_RE})*$`);
+const SEG_COMMIT_RE = new RegExp(`^git\\s+commit(\\s+-q)?\\s+(-F\\s+|--file[=\\s])${ARG_RE}(\\s+-q)?$`);
+const SEG_READONLY_RE = new RegExp(`^git\\s+(status|diff|log|rev-parse|show)(\\s+${ARG_RE})*$`);
+
+/**
+ * `git push`, exactly: `[-u|--set-upstream] <remote> HEAD:<branch>` or
+ * `HEAD:refs/heads/<branch>` — the ONLY exempt form. Bare `git push`, a remote alone, a plain
+ * branch name, or bare `HEAD` are no longer enough: every one of those is redirectable by
+ * `push.default`/`remote.*.push`/an upstream config this read cannot see, which is exactly how
+ * the review's re-review turned "looks like it only pushes `loop/x`" into "pushes wherever the
+ * repo's config says". An EXPLICIT `HEAD:<ref>` refspec is immune to both — git ignores
+ * `push.default` once a refspec is given, and a mirror/`+`/`:`-prefixed form refuses to
+ * coexist with one. The remote's first character must be alphanumeric so a flag (`-f`,
+ * `--all`, `--delete`, …) can never be read as a remote name.
+ */
+function pushSegmentOk(seg, branch) {
+  const m = /^git\s+push(?:\s+(.*))?$/.exec(seg);
+  if (!m) return false;
+  const rest = (m[1] || '').trim();
+  if (!rest) return false;
+  const tokens = rest.split(/\s+/);
+  let i = 0;
+  if (tokens[i] === '-u' || tokens[i] === '--set-upstream') i += 1;
+  const remote = tokens[i];
+  if (remote === undefined || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(remote)) return false;
+  i += 1;
+  const ref = tokens[i];
+  i += 1;
+  if (ref === undefined || i !== tokens.length) return false;
+  return ref === `HEAD:${branch}` || ref === `HEAD:refs/heads/${branch}`;
+}
+
+/**
+ * Consent Before Push's loop/* exemption: true only when EVERY clause holds —
+ * (1) the command carries none of the characters that could smuggle a second effect past this
+ * read, (2)-(3) every `&&`/`;`/`||`/`|`-separated segment is one of the three whitelisted git
+ * shapes above, with every push segment also passing `pushSegmentOk`, and (4) the branch
+ * checked out in `cwd` starts with `loop/` AND its git root carries a launched LOOP.md. Splitting
+ * on the separators without respecting quotes is deliberate, not an oversight: (1) and the
+ * per-segment whitelist already refuse any segment a quoted separator could produce, because a
+ * quote character fails every one of the three segment patterns.
+ */
+export function loopExempt(command, cwd) {
+  if (typeof command !== 'string' || UNSAFE_CHARS_RE.test(command)) return false;
+  const branch = currentBranch(cwd);
+  if (!branch || !branch.startsWith('loop/')) return false;
+  const root = gitRootOf(cwd);
+  if (!root || !loopLaunched(root)) return false;
+  const segments = command.split(/&&|\|\||[;|]/).map((s) => s.trim()).filter(Boolean);
+  if (!segments.length) return false;
+  return segments.every((seg) => SEG_ADD_RE.test(seg) || SEG_COMMIT_RE.test(seg)
+    || SEG_READONLY_RE.test(seg) || pushSegmentOk(seg, branch));
+}
+
 /** The `permissionDecision: "ask"` document, in Python's compact `json.dumps` spelling. */
 function askDecision(reason) {
   return `${jsonDumpsCompact({
@@ -739,8 +822,12 @@ function gitDecide(args, payload) {
       + 'discarding git act needs confirmation bound to this specific command');
   }
   // `--no-consent`: the process pack (or process 5 alone) is off, so the commit/push ask has
-  // no rule behind it — but Law IV above is universal and has already run.
+  // no rule behind it — but Law IV above is universal and has already run. Checked before
+  // `loopExempt` so a non-git command, or one with consent off, never pays for the whitelist.
   if (args.noConsent || !GIT_GATE_RE.test(command)) return 0;
+  // Consent Before Push: a loop launched on its own `loop/*` branch is a named batch for a
+  // fixed set of commit/push forms on that branch only — never a merge into anything shared.
+  if (loopExempt(command, (payload && payload.cwd) || process.cwd())) return 0;
   return ask(args, 'git-gate', 'process-5', 'Geneseed (Consent Before Push) \u2014 every git '
     + 'commit/push needs explicit approval; to see the change first, use the explain-changes skill');
 }

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/hosts/mcp.mjs

@@ -68,7 +68,7 @@ export const MCP_PRESETS = {
       + 'install). Edit GITLAB_PERSONAL_ACCESS_TOKEN (scopes: api, read_repository) '
       + 'and GITLAB_API_URL before use. For a second instance (a self-hosted server), '
       + 'copy this block by hand under a new name and point it at the other URL — '
-      + 'SETUP.md has the pattern.',
+      + 'docs/guides/mcp.md has the pattern.',
     block: {
       type: 'local',
       command: ['npx', '-y', '@zereight/mcp-gitlab'],

package/js/hosts/settings.mjs

@@ -483,6 +483,18 @@ export function hookShimPath(platform = process.platform) {
   return path.join(shimHome(), ...shimRel(platform));
 }
 
+/**
+ * The paths the machine's hook shim names that are gone — `[]` when the shim is absent or live.
+ *
+ * Cheap on purpose: `status`, the doctor and EVERY CLI run call it (the run-time warning in
+ * `bin/geneseed-cli.mjs`), because a dead shim disables every hook of every Claude-shaped
+ * install and nothing else would say so. An absent shim is not dead — a checkout that has never
+ * emitted owns none — and an unreadable one is reported by the doctor, not here.
+ */
+export function shimDead() {
+  try { return shimDeadPaths(readText(hookShimPath())); } catch { return []; }
+}
+
 /**
  * `_build_settings._hook_shim_body`, with the two volatile values INJECTED.
  *
@@ -988,7 +1000,7 @@ export function migrateShape(commands, shimBody) {
 /**
  * `_build_settings._autostart_paths` — where a hand-written web-daemon autostart entry lives.
  *
- * NOTHING IN THIS REPOSITORY HAS EVER WRITTEN ONE — `SETUP.md` tells the user to create them
+ * NOTHING IN THIS REPOSITORY HAS EVER WRITTEN ONE — the install guide tells the user to create them
  * by hand, and no .py/.mjs/.sh/.cmd in the tree contains `vbs`, `LaunchAgents` or `plist`. So
  * `migrate` REPORTS a stale one and never rewrites it, on the rule `settingsIntegrityCheck`
  * already states: an entry the manifest does not claim is "possibly user-authored; left alone".

package/js/inspect/checks-authoring.mjs

@@ -13,7 +13,7 @@
  */
 import path from 'node:path';
 import {
-  CONFIG, PACK_ORDER, PLUGIN_SRC, RETIRED_RULE_IDS, ROOT, RULE_ID_RE, SRC, THEMES, canonFiles,
+  CONFIG, DOCS, DOC_FOLDERS, PACK_ORDER, PLUGIN_SRC, RETIRED_RULE_IDS, ROOT, RULE_ID_RE, SRC, THEMES, canonFiles,
   knownRuleIds, ruleCanon, titleKey,
 } from '../build/source.mjs';
 import { themeFiles } from '../hosts/installs.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';
@@ -763,7 +764,7 @@ export function countTableProblems() {
 
   // WHERE THE ONBOARDING COPY LIVES, AND WHY THIS READ MOVED. It used to open the one module
   // that held the web console's onboarding prose. That prose has since moved into
-  // `docs/web/*.md`, and the counts in it render from `{N_LAWS}` / `{N_AGENTS}` / `{N_SKILLS}`
+  // `docs/<folder>/*.md`, and the counts in it render from `{N_LAWS}` / `{N_AGENTS}` / `{N_SKILLS}`
   // — so the read was still succeeding against a file the sentences had left, all three arms
   // below scored zero, and the check looked healthy while gating nothing. A templated count
   // cannot drift; what these arms still catch is a maintainer typing the NUMBER into a page
@@ -773,7 +774,9 @@ export function countTableProblems() {
   // byte moves. `web` stays fail-soft — a missing docs tree is not an authoring fault.
   let web = '';
   try {
-    web = globSorted(path.join(ROOT, 'docs', 'web'), (n) => n.endsWith('.md'))
+    web = DOC_FOLDERS
+      .flatMap((f) => (isDir(path.join(DOCS, f))
+        ? globSorted(path.join(DOCS, f), (n) => n.endsWith('.md')) : []))
       .map(readText).join('\n');
   } catch { web = ''; }
   // ⚠ NOT FAIL-SOFT, UNLIKE `web` ABOVE, AND THE ASYMMETRY IS THE POINT. A missing `docs/web`
@@ -834,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
@@ -283,7 +284,7 @@ export function cmdDoctor(args) {
       // (`js/build/generate.mjs`), which forwards `--theme` and nothing else. So the front door
       // answered `unrecognized arguments: --sync-themes` to anyone who followed doctor's own
       // advice, for as long as the premise went unchecked. The flag belongs to the GENERATOR,
-      // whose binary is `geneseed-build` — which is what `README.md` and `SETUP.md` have said
+      // whose binary is `geneseed-build` — which is what `README.md` and the install guide have said
       // all along. A hint is a command; if it is not runnable it is decoration.
       printOut('  tip: a theme is missing a key another theme defines — run '
         + '`geneseed-build --sync-themes` to fill it from _TEMPLATE.json, '

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',
@@ -108,7 +109,7 @@ export const SKILL_CLASS = {
   // `understand` before, which made that class a grab-bag.
   wiki: 'harness', geneseed: 'harness', rule: 'harness', profile: 'harness',
   herdr: 'harness', 'skill-forge': 'harness', 'consolidate-memory': 'harness',
-  teach: 'learn', quiz: 'learn',
+  teach: 'learn', quiz: 'learn', 'learn-mode': 'learn',
 };
 
 /** `k in dict` — own keys only, where `k in obj` also finds `Object.prototype` members. */

package/js/inspect/registry.mjs

@@ -17,10 +17,10 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync } from 'n
 import path from 'node:path';
 import os from 'node:os';
 
-import { expanduser } from '../hosts/hosts.mjs';
+import { expanduser, resolvePath } from '../hosts/hosts.mjs';
 import { writeText, isFile, isDir } from '../lib/fs.mjs';
 import { parseJson, jsonDumpsIndent } from '../lib/json.mjs';
-import { toPlatformPath } from '../lib/paths.mjs';
+import { toPlatformPath, within } from '../lib/paths.mjs';
 
 /** `_install_registry._path()` — `$XDG_CONFIG_HOME/geneseed/installs.json`. */
 function registryPath() {
@@ -28,6 +28,21 @@ function registryPath() {
   return path.join(base, 'geneseed', 'installs.json');
 }
 
+/**
+ * Is `root` a scratch install — inside the OS temp dir while the registry is not?
+ *
+ * Agent sessions emit into scratchpads under `%TEMP%`; recorded, each one is rebuilt by every
+ * `rebuild-all` and listed by every `status` for as long as the folder survives. The second
+ * clause is what keeps every test and golden cell meaningful: their registry lives in a
+ * sandbox under the temp dir too, so their temp roots are not scratch RELATIVE TO IT.
+ * `within` is case-insensitive on win32, so `C:\Users\X\AppData\Local\Temp` and its
+ * lower-cased spelling are one directory.
+ */
+export function isScratchRoot(root, registryFile) {
+  const tmp = resolvePath(os.tmpdir());
+  return within(resolvePath(root), tmp) && !within(resolvePath(registryFile), tmp);
+}
+
 function registryLoad() {
   try {
     const data = parseJson(readFileSync(registryPath(), 'utf8'));
@@ -59,6 +74,7 @@ export function registryRecord(dir) {
   try {
     let root;
     try { root = realpathSync.native(dir); } catch { root = path.resolve(dir); }
+    if (isScratchRoot(root, registryPath())) return;
     const cur = registryLoad();
     if (!cur.includes(root)) registrySave([...cur, root]);
   } catch { /* a registry hiccup must never fail a build */ }
@@ -75,6 +91,7 @@ export function registryRecord(dir) {
  */
 export function registryRoots() {
   const original = registryLoad();
+  const file = registryPath();
   const out = [];
   const kept = [];
   const seen = new Set();
@@ -96,7 +113,7 @@ export function registryRoots() {
     let key;
     try { key = existsSync(root) ? realpathSync.native(root) : root; } catch { key = root; }
     if (seen.has(key)) continue;
-    if (isDir(root) && isFile(path.join(root, '.geneseed-emit'))) {
+    if (isDir(root) && isFile(path.join(root, '.geneseed-emit')) && !isScratchRoot(root, file)) {
       seen.add(key);
       kept.push(root);
       out.push(root);

package/js/inspect/status.mjs

@@ -73,6 +73,7 @@ import {
   defaultTheme, installedDefaults, installTargets, manifestIsClaude, readJsonMaybe, readMaybe,
 } from '../hosts/installs.mjs';
 import { installProfile, rebuildCommand } from '../build/generate.mjs';
+import { shimDead } from '../hosts/settings.mjs';
 import { printOut } from '../lib/fs.mjs';
 import { codePointLength, padEndToWidth } from '../lib/text.mjs';
 
@@ -208,7 +209,9 @@ export function gateSummary(cfgDirs) {
       total += 1;
     }
   }
-  return { standing_down: standingDown, asks, total };
+  // `dead` is the machine shim's missing targets: every gate below is armed on paper and never
+  // runs, so it outranks `armed` in the row.
+  return { standing_down: standingDown, asks, total, dead: shimDead() };
 }
 
 /** `_harness_status._status_data`. */
@@ -350,7 +353,9 @@ export function statusLines(d, color = false) {
   // panels carry no `gates` key and must render unchanged.
   if (d.gates) {
     const g = d.gates;
-    const armed = g.standing_down.length
+    const armed = g.dead?.length
+      ? `DEAD — hook shim points at ${g.dead.join(', ')}; run: geneseed rebuild-all`
+      : g.standing_down.length
       ? `STANDING DOWN for this cwd (excludes.json in ${g.standing_down.join(', ')})`
       : 'armed';
     const byRule = Object.entries(g.asks).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
@@ -367,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/lib/node-floor.mjs

@@ -0,0 +1,30 @@
+/**
+ * The Node floor — the FIRST import of all three binaries, so an old Node gets one sentence
+ * instead of a stack trace from whichever API it lacks.
+ *
+ * `engines` in package.json only makes npm warn, and `npx geneseed`, a global install and the
+ * hook shim all run the binaries directly. ESM links the whole graph before any body runs, so
+ * this only helps while every file still PARSES on the old Node; it runs before any of them
+ * executes. The hook exits 0: a hook must never block a tool call, and the message on stderr
+ * is what the host surfaces. Nothing here may print to stdout — the hook's decision channel.
+ */
+import path from 'node:path';
+
+export const NODE_FLOOR = '22.3.0';
+
+/** Numeric, not string, comparison: '22.10.0' is above '22.3.0'. */
+export function belowFloor(version, floor = NODE_FLOOR) {
+  const v = version.replace(/^v/, '').split('.').map(Number);
+  const f = floor.split('.').map(Number);
+  for (let i = 0; i < 3; i += 1) {
+    if ((v[i] || 0) !== f[i]) return (v[i] || 0) < f[i];
+  }
+  return false;
+}
+
+if (belowFloor(process.versions.node)) {
+  process.stderr.write(`geneseed needs Node 22.3 or newer; this is Node ${process.versions.node}. `
+    + 'Install a current Node from https://nodejs.org (or your package manager), then run the '
+    + 'command again.\n');
+  process.exit(path.basename(process.argv[1] || '').startsWith('geneseed-hook') ? 0 : 1);
+}

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