geneseed 3.12.0 → 3.14.0

package/js/inspect/checks-counts.mjs

@@ -0,0 +1,242 @@
+/**
+ * The COUNT gates — the hand-written tables, badges and prose that restate how many laws,
+ * agents, skills, themes and plugins ship, held against `src/`.
+ *
+ * Split out of `checks-authoring.mjs`, which still aggregates these (and re-exports them for
+ * its existing importers). `proseMirrorProblems` is pure over its inputs; `countTableProblems`
+ * is the reader that feeds it.
+ */
+import path from 'node:path';
+import { DOCS, DOC_FOLDERS, PLUGIN_SRC, ROOT, SRC, ruleCanon } from '../build/source.mjs';
+import { themeFiles } from '../hosts/installs.mjs';
+import { readText } from '../lib/fs.mjs';
+import { formatRepr } from '../lib/json.mjs';
+import { lawMetaProblems } from './checks-constitution.mjs';
+import { LAW_CLASS, LAW_CLASSES, SKILL_CLASS } from './inventory.mjs';
+import { globSorted, has, isDir, isFile, srcStems } from './scan.mjs';
+import { existsSync, readdirSync } from 'node:fs';
+
+/**
+ * `_harness_build._prose_mirror_problems` — the human-readable count mirrors, the ones the
+ * badge regex never sees.
+ *
+ * The README "What you get" table and the web onboarding copy each restate the law / agent /
+ * skill counts in prose, and the README enumerates the skills by name. Nothing renders these,
+ * so they drift silently — they already had. Pure over its inputs, so the corpus can feed it
+ * crafted drift without touching the tree.
+ */
+export function proseMirrorProblems(readme, web, counts, skillStems, shipped = '') {
+  const problems = [];
+  const { laws, agents, skills, plugins } = counts;
+
+  for (const m of readme.matchAll(/(\d+) universal laws/g)) {
+    if (Number(m[1]) !== laws) {
+      problems.push(`[authoring] README prose says '${m[1]} universal laws' but src has ${laws}`);
+    }
+  }
+  // The README plugin count. It had drifted — the overview sentence said six while seven
+  // shipped — because the project's other plugin count ({N_PLUGINS} in the web docs) reads
+  // a DEPLOYED plugins dir that a markdown file in this repository never has. `plugins` is
+  // optional in `counts` (Python's `.get`, undefined here) because the corpus predates it.
+  if (plugins !== undefined) {
+    for (const m of readme.matchAll(/(\d+) \*{0,2}plugins/g)) {
+      if (Number(m[1]) !== plugins) {
+        problems.push(`[authoring] README prose says '${m[1]} plugins' but `
+          + `adapters/opencode/plugins has ${plugins}`);
+      }
+    }
+  }
+  for (const [label, want] of [['Agents', agents], ['Skills', skills]]) {
+    const m = new RegExp(`${label}\\*\\*\\s*\\((\\d+)\\)`).exec(readme);
+    if (m && Number(m[1]) !== want) {
+      problems.push(`[authoring] README '${label} (${m[1]})' but src has ${want}`);
+    }
+  }
+  // The README Skills row must enumerate EXACTLY the source skills — a dropped name is
+  // invisible to the (N) count alone, which is the off-by-one this gate forbids.
+  const row = readme.split('\n').find((ln) => ln.includes('🛠') && ln.includes('Skills')) ?? '';
+  if (row.includes('workflows:')) {
+    const listed = new Set(row.split('workflows:').slice(1).join('workflows:').split('·')
+      .map((seg) => seg.replace(/[^a-z0-9-]/g, '')));
+    listed.delete('');
+    for (const missing of [...skillStems].filter((s) => !listed.has(s)).sort()) {
+      problems.push(`[authoring] README skills list omits '${missing}'`);
+    }
+    for (const orphan of [...listed].filter((s) => !skillStems.has(s)).sort()) {
+      problems.push(`[authoring] README skills list names '${orphan}' but no `
+        + `skills/${orphan}.md exists`);
+    }
+  }
+
+  for (const m of web.matchAll(/(\d+) universal (?:laws|Rules)/g)) {
+    if (Number(m[1]) !== laws) {
+      problems.push(`[authoring] docs/ prose says '${m[1]} universal laws/Rules' but `
+        + `src has ${laws}`);
+    }
+  }
+  for (const m of web.matchAll(/(\d+) capability specialists/g)) {
+    if (Number(m[1]) !== agents) {
+      problems.push(`[authoring] docs/ prose says '${m[1]} capability specialists' but `
+        + `src has ${agents}`);
+    }
+  }
+  // N is a curated-subset size, not the total, so it is gated against the wikilinks it
+  // introduces rather than against the skill count. `[\s\S]` is Python's `re.S` dot.
+  const m = /(\d+) repeatable workflows the agent can invoke by name([\s\S]*?)playbook under/
+    .exec(web);
+  if (m) {
+    const listedN = (m[2].match(/\[\[[^\]]+\]\]/g) ?? []).length;
+    if (Number(m[1]) !== listedN) {
+      problems.push(`[authoring] docs/ says '${m[1]} repeatable workflows' `
+        + `but its wikilink list has ${listedN}`);
+    }
+  }
+
+  // ⚠ THE ABSENCE OF THIS TRIPLE IS CHECKED BY THE CALLER, NOT HERE. This arm is satisfiable by
+  // DELETING THE SENTENCE — no match, no problem, green — which is a gate failing open. The
+  // presence check lives in `countTableProblems`, beside the read that already knows whether
+  // the file could be opened at all; an empty `shipped` here means "nothing to compare".
+  const s = /(\d+) laws, (\d+) agents, (\d+) skills/.exec(shipped);
+  if (s) {
+    for (const [got, want, label] of [[s[1], laws, 'laws'], [s[2], agents, 'agents'],
+      [s[3], skills, 'skills']]) {
+      if (Number(got) !== want) {
+        problems.push(`[authoring] SHIPPED.md says '${got} ${label}' but src has ${want}`);
+      }
+    }
+  }
+  return problems;
+}
+
+/** `_build_render._TMPL_SPEC_RE`, as the count gate spells it. */
+const TMPL_SPEC_RE = /\{\{DIR_(AGENTS|SKILLS)\}\}\/([A-Za-z0-9_-]+)\.md/g;
+
+/**
+ * `_harness_build._count_table_problems` — the hand-authored AGENT.md tables and the README
+ * badges, against `src/`.
+ *
+ * The tables must list EXACTLY the spec files (no dead row, no orphaned spec) and each
+ * `agents`/`skills`/`laws`/`themes` badge must equal the real count. This is the
+ * authoring-time guarantee that lets tables, badges and prose stay hand-written without
+ * silently drifting from the source tree.
+ */
+export function countTableProblems() {
+  const problems = [];
+  let ttext;
+  try { ttext = readText(path.join(SRC, 'AGENT.md.tmpl')); } catch (e) {
+    return [`[authoring] AGENT.md.tmpl unreadable: ${e.message}`];
+  }
+
+  const linked = { agents: new Set(), skills: new Set() };
+  for (const m of ttext.matchAll(TMPL_SPEC_RE)) {
+    if (m[2] !== '_template') linked[m[1] === 'AGENTS' ? 'agents' : 'skills'].add(m[2]);
+  }
+  for (const folder of ['agents', 'skills']) {
+    const files = srcStems(folder);
+    for (const missing of [...linked[folder]].filter((x) => !files.has(x)).sort()) {
+      problems.push(`[authoring] AGENT.md links ${folder}/${missing}.md but no such spec exists`);
+    }
+    for (const orphan of [...files].filter((x) => !linked[folder].has(x)).sort()) {
+      problems.push(`[authoring] ${folder}/${orphan}.md exists but the AGENT.md table omits it`);
+    }
+  }
+
+  const skillFiles = srcStems('skills');
+  for (const missing of [...skillFiles].filter((s) => !has(SKILL_CLASS, s)).sort()) {
+    problems.push(`[authoring] skills/${missing}.md has no category in SKILL_CLASS`);
+  }
+  for (const stale of Object.keys(SKILL_CLASS).filter((s) => !skillFiles.has(s)).sort()) {
+    problems.push(`[authoring] SKILL_CLASS lists '${stale}' but no skills/${stale}.md exists`);
+  }
+
+  // The numerals the laws RENDER with — positional, off the canon — because LAW_CLASS and the
+  // console's LAW_META are keyed the way the rendered catalogue numbers them.
+  const lawRules = ruleCanon(SRC).rules.filter((r) => r.kind === 'LAW');
+  const lawNums = lawRules.map((r) => r.label);
+  for (const num of lawNums) {
+    if (!has(LAW_CLASS, num)) {
+      problems.push(`[authoring] laws/universal.md rule ${num} has no class in LAW_CLASS`);
+    }
+  }
+  // Sorted by the Roman numeral as a STRING; `doctorCollect` re-sorts every message anyway.
+  for (const num of Object.keys(LAW_CLASS).sort()) {
+    if (!LAW_CLASSES.includes(LAW_CLASS[num])) {
+      problems.push(`[authoring] LAW_CLASS['${num}'] = '${LAW_CLASS[num]}' is not a known `
+        + `class ${formatRepr(LAW_CLASSES)}`);
+    }
+  }
+  problems.push(...lawMetaProblems(lawRules, LAW_CLASS, LAW_CLASSES));
+
+  // WHAT SHIPS, NOT WHAT IS FLAT. A folder skill (`src/skills/<name>/SKILL.md`, vendored with
+  // its scripts or references) ships exactly like a flat one, so the badge, the README list and
+  // the SHIPPED.md triple count it. It is added HERE rather than in `srcStems`, whose other
+  // readers above — the AGENT.md table links and SKILL_CLASS — are about flat specs only.
+  const skillsDir = path.join(SRC, 'skills');
+  const shippedSkills = new Set([...skillFiles, ...(isDir(skillsDir) ? readdirSync(skillsDir) : [])
+    .filter((d) => !d.startsWith('_') && isFile(path.join(skillsDir, d, 'SKILL.md')))]);
+
+  const counts = {
+    agents: srcStems('agents').size,
+    skills: shippedSkills.size,
+    laws: lawNums.length,
+    themes: themeFiles().length,
+    plugins: existsSync(PLUGIN_SRC)
+      ? readdirSync(PLUGIN_SRC).filter((f) => f.startsWith('geneseed-') && f.endsWith('.js')).length
+      : 0,
+  };
+  let readme;
+  try { readme = readText(path.join(ROOT, 'README.md')); } catch { return problems; }
+  // ⚠ PRESENCE FIRST, THEN THE VALUE — the same absence arm the SHIPPED triple needed, for the
+  // same reason: `if (m && …)` is green when there is no badge, so deleting a badge silences its
+  // own gate.
+  for (const [key, n] of Object.entries(counts)) {
+    const m = new RegExp(`badge/${key}-(\\d+)`).exec(readme);
+    if (!m) {
+      problems.push(`[authoring] README has no ${key} badge — deleting one is how this gate `
+        + 'goes green while the reader is told nothing');
+      continue;
+    }
+    if (Number(m[1]) !== n) {
+      problems.push(`[authoring] README ${key} badge says ${m[1]} but src has ${n}`);
+    }
+  }
+
+  // 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/<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
+  // instead of the token, which is the drift that reaches a reader.
+  //
+  // `web` stays fail-soft — a missing docs tree is not an authoring fault.
+  let web = '';
+  try {
+    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 tree
+  // is not an authoring fault — a checkout can legitimately lack it. SHIPPED.md is a tracked,
+  // shipped file whose CONTENT this function asserts, so an unreadable one was
+  // indistinguishable from a deleted claim: swallowing it into `''` handed the triple arm an
+  // empty string and turned a hard read failure into a silent pass.
+  //
+  // AND THE PRESENCE OF THE TRIPLE IS CHECKED HERE rather than inside `proseMirrorProblems`:
+  // this is the caller that already owns the question "could the file be read".
+  let shipped;
+  try {
+    shipped = readText(path.join(ROOT, 'SHIPPED.md'));
+  } catch (e) {
+    problems.push(`[authoring] SHIPPED.md is unreadable (${e.message}) — the counts it carries `
+      + 'cannot be checked, and a gate that cannot read its subject must say so');
+    shipped = '';
+  }
+  if (shipped && !/(\d+) laws, (\d+) agents, (\d+) skills/.test(shipped)) {
+    problems.push('[authoring] SHIPPED.md carries no \'N laws, N agents, N skills\' line — '
+      + 'deleting it is how that gate goes green while the count drifts');
+  }
+  problems.push(...proseMirrorProblems(readme, web, counts, shippedSkills, shipped));
+  return problems;
+}

package/js/inspect/checks-repo.mjs

@@ -9,7 +9,7 @@
 import path from 'node:path';
 import { PLUGIN_SRC, ROOT, SRC, THEMES, WORKFLOW_SRC } from '../build/source.mjs';
 import { VENDORED_SKILL_DIRS } from '../hosts/native.mjs';
-import { hookShimPath, shimDeadPaths } from '../hosts/settings.mjs';
+import { hookShimPath, shimDeadPaths } from '../hosts/shim.mjs';
 import { readText } from '../lib/fs.mjs';
 import { formatRepr, formatValue } from '../lib/json.mjs';
 import { splitLines } from '../lib/udiff.mjs';
@@ -313,11 +313,20 @@ export function moduleMapProblems() {
       + 'checks-repo.mjs asserts it describes every module under js/'];
   }
 
-  // A row is `| `name.mjs` | … |`. Reading the CODE SPAN and not the whole line keeps a module
-  // named in a "Before editing" paragraph from counting as a row.
-  const documented = new Set(
-    [...text.matchAll(/^\|\s*`([a-z0-9-]+\.mjs)`\s*\|/gm)].map((m) => m[1]),
-  );
+  // A row is `| `name.mjs` | … |`, and it documents `<folder>/name.mjs` for the folder whose
+  // `## `js/<folder>/`` heading it sits under. Keyed by basename alone, a row answered for every
+  // folder holding that name — catalog.mjs, cli.mjs and registry.mjs each live in two — so a
+  // deleted module stayed "documented" by its namesake's row. Reading the CODE SPAN and not the
+  // whole line keeps a module named in a "Before editing" paragraph from counting as a row.
+  const documented = new Set();
+  let folder = null;
+  for (const line of text.split('\n')) {
+    const heading = /^## `js\/([a-z0-9-]+)\/`/.exec(line);
+    if (heading) { folder = heading[1]; continue; }
+    if (line.startsWith('## ')) { folder = null; continue; }
+    const row = /^\|\s*`([a-z0-9-]+\.mjs)`\s*\|/.exec(line);
+    if (row && folder) documented.add(`${folder}/${row[1]}`);
+  }
 
   const onDisk = new Set();
   const jsDir = path.join(String(ROOT), 'js');
@@ -328,7 +337,7 @@ export function moduleMapProblems() {
     // that only knew `/` finds ONE part on Windows and therefore zero modules — which is what
     // the vacuity guard below caught the first time this ran.
     const parts = path.relative(jsDir, rel).replaceAll('\\', '/').split('/');
-    if (parts.length === 2) onDisk.add(parts[1]);
+    if (parts.length === 2) onDisk.add(parts.join('/'));
   }
 
   if (onDisk.size < 30) {
@@ -344,7 +353,7 @@ export function moduleMapProblems() {
   }
   for (const mod of [...documented].sort()) {
     if (!onDisk.has(mod)) {
-      problems.push(`[authoring] js/README.md has a row for ${mod}, which does not exist — the map `
+      problems.push(`[authoring] js/README.md has a row for js/${mod}, which does not exist — the map `
         + 'sends a reader to a file that is not there');
     }
   }

package/js/inspect/diff.mjs

@@ -45,7 +45,7 @@ import {
   GLOBAL_MANIFEST, VERSION_MARKER, expanduser, opencodeConfigDir, resolvePath,
 } from '../hosts/hosts.mjs';
 import {
-  EMIT_HOST_SCOPE, defaultTheme, doctrinesForBuild, footprintOfDir, modeOfDir, postureOfDir,
+  EMIT_HOST_SCOPE, defaultTheme, doctrinesForBuild, excludedRulesOfDir, footprintOfDir, modeOfDir, postureOfDir,
   trustOfDir,
   readJsonMaybe, readMaybe, themeOfDir,
 } from '../hosts/installs.mjs';
@@ -178,6 +178,9 @@ export function diffCollect({ target = null, theme = null, emit = null, footprin
       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 excluded rules, or an install built `--exclude-rules "process 5"` reads its
+      // carrier as drift: `expected` would re-state the rule the deployment took away.
+      excludeRules: excludedRulesOfDir(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

@@ -32,7 +32,7 @@
 import path from 'node:path';
 import { emitGlobalInto, emitProjectInto, main as driverMain } from '../build/driver.mjs';
 import { ROOT } from '../build/source.mjs';
-import { resolvePath } from '../hosts/hosts.mjs';
+import { CLAUDE_STYLE, resolvePath } from '../hosts/hosts.mjs';
 import { installedDefaults, themeFiles } from '../hosts/installs.mjs';
 import { validateIsVendored } from '../hosts/native.mjs';
 import { printOut } from '../lib/fs.mjs';
@@ -143,7 +143,7 @@ export function globalEmitProblems(themeName) {
  * skills one level deeper than a bundle does.
  */
 export function claudeBobEmitProblems(themeName) {
-  return emitProblemsOver(['claude', 'bob', 'openclaude'], (tmp, label) => {
+  return emitProblemsOver(CLAUDE_STYLE, (tmp, label) => {
     const root = path.join(tmp, 'root');
     return {
       label: `${themeName} ${label}`,

package/js/inspect/inventory.mjs

@@ -34,10 +34,10 @@ import { parseJson } from '../lib/json.mjs';
  * `_harness_tui.LAW_HEADING_RE` — a heading in the RENDERED laws file, e.g.
  * `### Rule IV — Deletion Is Deliberate`.
  *
- * Not `js/inspect/checks-authoring.mjs`'s `LAW_HEADING_RE`, which matches the `{{LAW}}` token in the
- * unrendered source. Two patterns, two inputs, two names in Python as well.
+ * The rendered side only: the unrendered source declares a rule as `{{LAW:<id>}} <Name>`, and
+ * `ruleCanon` in `js/build/source.mjs` is what reads that.
  */
-export const LAW_HEADING_RE = /^###\s+\S+\s+([IVXLCDM]+)\s+[—-]\s+(.+?)\s*$/;
+const LAW_HEADING_RE = /^###\s+\S+\s+([IVXLCDM]+)\s+[—-]\s+(.+?)\s*$/;
 
 /**
  * A heading in a RENDERED doctrine pack, e.g. `### Doctrine craft 1 — Automate Repetition`.
@@ -52,7 +52,7 @@ export const LAW_HEADING_RE = /^###\s+\S+\s+([IVXLCDM]+)\s+[—-]\s+(.+?)\s*$/;
  * `([a-z]+)` refuses `Rule I`'s uppercase numeral, and `([IVXLCDM]+)` refuses a lowercase pack
  * id. Measured across all fourteen themes — zero cross-matches either way.
  */
-export const DOCTRINE_HEADING_RE = /^###\s+\S+\s+([a-z]+)\s+(\d+)\s+[—-]\s+(.+?)\s*$/;
+const DOCTRINE_HEADING_RE = /^###\s+\S+\s+([a-z]+)\s+(\d+)\s+[—-]\s+(.+?)\s*$/;
 
 /**
  * A section heading in the RENDERED ontology, e.g. `#### Telos`.

package/js/inspect/scan.mjs

@@ -36,7 +36,7 @@ const FENCE_RE = /```[\s\S]*?```/g;
 const INLINE_CODE_RE = /`[^`]*`/g;
 const COMMENT_RE = /<!--[\s\S]*?-->/g;
 
-/** `_harness_core.strip_code` — fenced blocks, inline code and HTML comments, in that order. */
+/** `_harness_core.strip_code` — fenced blocks, then HTML comments, then inline code, in that order. */
 export function stripCode(text) {
   return text.replace(FENCE_RE, '').replace(COMMENT_RE, '').replace(INLINE_CODE_RE, '');
 }

package/js/inspect/status.mjs

@@ -73,7 +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 { shimDead } from '../hosts/shim.mjs';
 import { printOut } from '../lib/fs.mjs';
 import { codePointLength, padEndToWidth } from '../lib/text.mjs';
 

package/js/inspect/validate.mjs

@@ -9,48 +9,36 @@
 import path from 'node:path';
 import { buildInto, emitGlobalInto, emitProjectInto } from '../build/driver.mjs';
 import { resolvePath } from '../hosts/hosts.mjs';
+import {
+  doctrinesOfDir, excludedRulesOfDir, modeOfDir, postureOfDir,
+} from '../hosts/installs.mjs';
 import { validateIsVendored } from '../hosts/native.mjs';
-import { printOut, printErr, readText } from '../lib/fs.mjs';
+import { printOut, printErr } from '../lib/fs.mjs';
 import { comparePaths } from '../lib/paths.mjs';
 import { stripWhitespace } from '../lib/text.mjs';
-import { linkProblems } from './checks-build.mjs';
+import { checkBuild } from './checks-build.mjs';
 import { cmdDoctor } from './doctor.mjs';
-import { TOKEN_RE, isDir, isFile, rglob, sortedUnique, withTempDir, within } from './scan.mjs';
+import { isDir, isFile, rglob, withTempDir, within } from './scan.mjs';
 
 // --------------------------------------------------------------------------------------
 // validate  —  the generator's `--validate-only`, on this binary because it runs the doctor
 // --------------------------------------------------------------------------------------
 
 /**
- * `build._validate_sandbox_problems` — the unresolved-token / dead-link / non-hermetic-link
- * scan over an already-rendered sandbox tree.
- *
- * A NEAR-TWIN OF `checkBuild` ABOVE, AND DELIBERATELY NOT IT, because the reference is two
- * functions and they differ in three observable ways: the token list is `sorted(set(...))`
- * here and bare `set(...)` there, the message carries no `[theme]` prefix (the caller adds
- * `[emit]` instead), and an unreadable file is SKIPPED rather than raised. Python duplicates
- * the loop because `build.py` cannot import the harness tree; here the two live in one file
- * and the two now sit one file apart (`checkBuild` is in `checks-build.mjs`); the
- * duplication is eight lines — every primitive underneath (`rglob`, `stripCode`,
- * `linkProblems`, `readText`) is the shared one, which is the half that could actually drift.
+ * `validate --help`. Its own text, because the parser it borrows is the generator's and that
+ * parser's `-h` prints `usage: geneseed-build …` — naming `--sync-themes`/`--config-dir`, which
+ * this verb refuses, under a program name the user did not type.
  */
-export function validateSandboxProblems(sandbox) {
-  const out = resolvePath(sandbox);
-  const problems = [];
-  for (const md of rglob(out)) {
-    if (!md.endsWith('.md') || !isFile(md)) continue;
-    const rel = path.relative(out, md);
-    if (validateIsVendored(rel)) continue;
-    let text;
-    // `except (OSError, UnicodeDecodeError): continue` — binary or unreadable, nothing here.
-    try { text = readText(md); } catch { continue; }
-    for (const tok of sortedUnique(text.match(TOKEN_RE) ?? [])) {
-      problems.push(`unresolved token ${tok} in ${rel}`);
-    }
-    problems.push(...linkProblems(md, text, out, rel));
-  }
-  return problems;
-}
+export const VALIDATE_USAGE = [
+  'usage: geneseed validate [-h] [--theme THEME] [--emit EMIT] [--out OUT] [--root ROOT]',
+  '                         [--footprint {lean,full}] [--posture POSTURE] [--mode MODE]',
+  '                         [--trust TRUST] [--doctrines DOCTRINES] [--exclude-rules RULES] [-v]',
+  '',
+  "Render and emit into a throwaway sandbox, run the doctor's checks, and write nothing real.",
+  "Takes the generator's render flags (see geneseed-build --help) except --sync-themes and",
+  '--config-dir.',
+  '',
+].join('\n');
 
 /**
  * `subprocess.run(..., capture_output=True, text=True)` around an IN-PROCESS call.
@@ -109,6 +97,17 @@ function captureStreams(fn) {
  * contract absolutely — this verb is deliberately outside the verb table, so nothing else does.
  */
 export function cmdValidate(args) {
+  // Two generator flags with no meaning in a dry run, refused rather than silently ignored:
+  // `--sync-themes` WRITES into the live themes dir, and `--config-dir` names a real install dir
+  // while every render here goes to a sandbox — accepting either would claim a check of
+  // something this verb never touches.
+  for (const [flag, set] of [['--sync-themes', args.syncThemes], ['--config-dir', args.cfgDir]]) {
+    if (set) {
+      printErr(`geneseed: error: validate does not take ${flag} — it renders into a sandbox `
+        + 'and writes nothing real; run `geneseed validate --help` for what it takes\n');
+      return 2;
+    }
+  }
   const problems = [];
   const scan = withTempDir((tmpRaw) => {
     // `.resolve()` mirrors `_check_build`'s: on Windows a temp dir can come back in 8.3
@@ -122,7 +121,13 @@ export function cmdValidate(args) {
     const sandbox = args.root ? path.join(root, 'bundle') : root;
     const cfgDir = path.join(tmp, 'cfg');
     const emit = args.emit;
-    const opts = { theme: args.theme, footprint: args.footprint };
+    // THE FIVE RENDER AXES TRAVEL WITH THE DRY RUN. They were parsed and then dropped, so
+    // `validate --doctrines craft` checked an all-packs render — a pass that said nothing
+    // about the build the operator was about to run.
+    const opts = {
+      theme: args.theme, footprint: args.footprint, posture: args.posture, mode: args.mode,
+      trust: args.trust, doctrines: args.doctrines, excludeRules: args.excludeRules,
+    };
     let scanDirs;
     try {
       if (emit.endsWith('-global')) {
@@ -158,6 +163,14 @@ export function cmdValidate(args) {
       .sort(comparePaths);
     printOut(`[validate-only] theme=${args.theme} emit=${emit} `
       + `footprint=${args.footprint}\n`);
+    // READ BACK OFF THE RENDER, not echoed from `args`: this line is the proof the axes reached
+    // the sandbox, which an echo of the flags would print just as happily if they had not.
+    const at = scanDirs[0];
+    const packs = doctrinesOfDir(at);
+    const excluded = excludedRulesOfDir(at);
+    printOut(`[validate-only] rendered at posture=${postureOfDir(at) ?? '?'} `
+      + `mode=${modeOfDir(at) ?? '?'} packs=${packs ? packs.join(',') || 'none' : '?'} `
+      + `excluded=${excluded.map((id) => id.replace('.', ' ')).join(', ') || 'none'}\n`);
     printOut(`[validate-only] would write ${written.length} file(s) under ${args.out}`
       + (args.root ? ` (root ${args.root})` : '')
       + ' — nothing was actually written (sandboxed).\n');
@@ -170,9 +183,9 @@ export function cmdValidate(args) {
         printOut(`  would write: ${path.relative(base, p)}\n`);
       }
     }
-    for (const d of scanDirs) {
-      for (const p of validateSandboxProblems(d)) problems.push(`[${emit}] ${p}`);
-    }
+    // The doctor's own per-tree scan, prefixed with the emit instead of a theme, and with the
+    // vendored shape every host depth can produce — a sandbox may hold a per-repo native layer.
+    for (const d of scanDirs) problems.push(...checkBuild(emit, d, validateIsVendored));
     return scanDirs;
   }, 'geneseed-validate-');
   if (scan === null) return 1;

package/js/loop/catalog.mjs

@@ -19,7 +19,7 @@ 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 { frontmatter } from '../hosts/memory-files.mjs';
 import { SRC } from '../build/source.mjs';
 import { checkGraph } from './graph.mjs';
 
@@ -47,8 +47,19 @@ export function parseBrick(text, origin) {
   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`);
+  // `gate: human` holds the transition after this brick until the user answers (state.mjs).
+  // Present on the brick only when declared, so an ungated brick's shape is unchanged.
+  const gate = get('gate');
+  if (gate && gate !== 'human') problems.push(`${name}: gate must be human, not ${JSON.stringify(gate)}`);
+  // `gateOn` narrows the gate to the outcomes it lists; any other outcome follows its edge ungated.
+  const gateOn = get('gateOn').split(',').map((s) => s.trim()).filter(Boolean);
+  if (gateOn.length && gate !== 'human') problems.push(`${name}: gateOn needs gate: human`);
+  for (const o of gateOn) if (!outcomes.includes(o)) problems.push(`${name}: gateOn ${o} is not one of its outcomes`);
   return {
-    brick: { name, description, effect, agent, skill, outcomes, body: body.trim(), origin },
+    brick: {
+      name, description, effect, agent, skill, outcomes, ...(gate ? { gate } : {}),
+      ...(gateOn.length ? { gateOn } : {}), body: body.trim(), origin,
+    },
     problems,
   };
 }
@@ -106,8 +117,10 @@ export function loadCatalog({
   return { bricks, templates, problems, overridden: overridden.sort() };
 }
 
-export function catalogProblems(opts = {}) {
-  const { bricks, templates, problems } = loadCatalog(opts);
+/** `catalog`: an already-loaded `loadCatalog(opts)`, for a caller that needs the catalogue
+ * itself too — passing it saves reading every brick and template twice. */
+export function catalogProblems(opts = {}, catalog = loadCatalog(opts)) {
+  const { bricks, templates, problems } = catalog;
   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}`));