@nurix/etna 0.18.19 → 0.18.20

package/data/harnesses/code/skills/design/scripts/phase-gate.mjs

@@ -0,0 +1,386 @@
+// skills/design/scripts/phase-gate.mjs — create-phase precondition gates (D21/D23): validate the named phase's exit preconditions, exit non-zero printing the exact fix, one green line on pass.
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const PHASES = ['intake', 'structure', 'scaffold', 'tokens', 'fixtures', 'surfaces'];
+const ARCHETYPES = new Set(['list-detail', 'dashboard', 'entity-detail', 'create-edit', 'log-stream', 'command-center']);
+const PROVENANCE = new Set(['project', 'extracted', 'library', 'default']);
+const STATE_SYNONYMS = { loading: ['loading', 'skeleton'], empty: ['empty'], error: ['error'], partial: ['partial', 'degraded', 'stale'] };
+
+const useColor = process.stdout.isTTY;
+// Wrap a string in green/red when writing to a TTY, plain otherwise.
+const green = (s) => (useColor ? `\x1b[32m${s}\x1b[0m` : s);
+const red = (s) => (useColor ? `\x1b[31m${s}\x1b[0m` : s);
+
+// Read a UTF-8 file, returning '' when it is absent.
+function readText(path) {
+  try { return readFileSync(path, 'utf8'); } catch { return ''; }
+}
+
+// Report a passing gate as one green line and exit 0.
+function pass(phase, msg) {
+  console.log(`${green(`PASS  phase-gate[${phase}]`)}  ${msg}`);
+  process.exit(0);
+}
+
+// Report a failing gate with the problem and the exact fix, then exit 1.
+function fail(phase, problem, fixLines) {
+  console.error(`${red(`FAIL  phase-gate[${phase}]`)}  ${problem}`);
+  console.error('');
+  console.error('  Fix:');
+  for (const line of fixLines) {
+    if (line == null || line === '') continue;
+    for (const sub of String(line).split('\n')) console.error(`    ${sub}`);
+  }
+  process.exit(1);
+}
+
+// Lowercase-kebab a display name for route-dir / fixture-module matching.
+function kebab(s) {
+  return String(s).trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+// Return the first non-parameter path segment of a route (/tickets/:id -> tickets).
+function firstStaticSegment(route) {
+  for (const p of String(route).split('/').filter(Boolean)) {
+    if (!p.startsWith(':')) return kebab(p);
+  }
+  return null;
+}
+
+// Return the last non-parameter path segment of a route (/tickets/new -> new).
+function lastStaticSegment(route) {
+  const parts = String(route).split('/').filter(Boolean).filter((p) => !p.startsWith(':'));
+  return parts.length ? kebab(parts[parts.length - 1]) : null;
+}
+
+// Parse leading YAML frontmatter into a flat key->value map, or null when absent.
+function parseFrontmatter(text) {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return null;
+  const out = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const idx = line.indexOf(':');
+    if (idx < 0) continue;
+    out[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+  }
+  return out;
+}
+
+// Split a `[a, b, c]` inline list into trimmed members.
+function parseBracketList(s) {
+  const m = String(s).match(/\[([^\]]*)\]/);
+  if (!m) return [];
+  return m[1].split(',').map((x) => x.trim()).filter(Boolean);
+}
+
+// Store one `key: value` pair onto a list-item object, parsing `states` into an array.
+function applyKV(obj, s) {
+  const idx = s.indexOf(':');
+  if (idx < 0) return;
+  const key = s.slice(0, idx).trim();
+  const value = s.slice(idx + 1).trim();
+  if (key === 'states') obj.states = parseBracketList(value);
+  else obj[key] = value;
+}
+
+// Parse the fenced ```yaml structure block into entities, surfaces, and temporal facts.
+function parseStructureBlock(md) {
+  const m = md.match(/```yaml structure\r?\n([\s\S]*?)```/);
+  if (!m) return null;
+  const result = { unitOfWork: null, coreLoop: null, entities: [], temporal: null, surfaces: [] };
+  let section = null;
+  let itemIndent = -1;
+  let current = null;
+  for (const raw of m[1].split(/\r?\n/)) {
+    if (!raw.trim() || raw.trim().startsWith('#')) continue;
+    const indent = raw.length - raw.trimStart().length;
+    const line = raw.trim();
+    if (indent === 0) {
+      current = null;
+      itemIndent = -1;
+      if (line.startsWith('unit-of-work:')) { result.unitOfWork = line.slice(line.indexOf(':') + 1).trim(); section = null; }
+      else if (line.startsWith('core-loop:')) { result.coreLoop = line.slice(line.indexOf(':') + 1).trim(); section = null; }
+      else if (line === 'entities:') section = 'entities';
+      else if (line === 'surfaces:') section = 'surfaces';
+      else if (line === 'temporal:') { section = 'temporal'; result.temporal = {}; }
+      else section = null;
+      continue;
+    }
+    if (section === 'entities' || section === 'surfaces') {
+      const list = section === 'entities' ? result.entities : result.surfaces;
+      if (line.startsWith('- ')) {
+        if (itemIndent === -1) itemIndent = indent;
+        if (indent === itemIndent) {
+          current = {};
+          list.push(current);
+          const rest = line.slice(2).trim();
+          if (rest && rest.includes(':')) applyKV(current, rest);
+        }
+      } else if (current && itemIndent !== -1 && indent > itemIndent) {
+        applyKV(current, line);
+      }
+    } else if (section === 'temporal') {
+      const idx = line.indexOf(':');
+      if (idx > 0) result.temporal[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+    }
+  }
+  return result;
+}
+
+// Read and parse the structure map, or fail the gate with the structure-phase fix.
+function requireMap(phase, project) {
+  const p = join(project, 'docs/design/structure.md');
+  if (!existsSync(p)) {
+    fail(phase, `No entity/surface map at ${p} — this phase reads it.`, [
+      'Complete the structure phase first: derive docs/design/structure.md with a fenced ```yaml structure block (references/structure.md).',
+    ]);
+  }
+  const blk = parseStructureBlock(readText(p));
+  if (!blk) {
+    fail(phase, `${p} has no parseable "yaml structure" fenced block.`, [
+      'The block must open exactly with the fence info-string `yaml structure` and carry entities[], temporal, and surfaces[].',
+    ]);
+  }
+  return blk;
+}
+
+// Collect all .ts/.tsx source under a route directory into one lowercased blob.
+function routeSource(dir) {
+  let out = '';
+  const stack = [dir];
+  while (stack.length) {
+    const cur = stack.pop();
+    let entries;
+    try { entries = readdirSync(cur, { withFileTypes: true }); } catch { continue; }
+    for (const ent of entries) {
+      const full = join(cur, ent.name);
+      if (ent.isDirectory()) stack.push(full);
+      else if (/\.(tsx|ts)$/.test(ent.name)) out += `\n${readText(full)}`;
+    }
+  }
+  return out.toLowerCase();
+}
+
+// Return the candidate route-dir slugs for a surface (name-kebab, route segments, archetype).
+function routeDirCandidates(s) {
+  const out = [];
+  if (s.name) out.push(kebab(s.name));
+  if (s.route) { const f = firstStaticSegment(s.route); if (f) out.push(f); const l = lastStaticSegment(s.route); if (l) out.push(l); }
+  if (s.archetype) out.push(s.archetype);
+  return [...new Set(out.filter(Boolean))];
+}
+
+// Resolve a surface's route directory to the first existing candidate, or null.
+function resolveRouteDir(s, routesDir) {
+  for (const c of routeDirCandidates(s)) {
+    const d = join(routesDir, c);
+    if (existsSync(d) && statSync(d).isDirectory()) return d;
+  }
+  return null;
+}
+
+// List the declared states whose branch is absent from a route's shell source.
+function missingStates(dir, states) {
+  const text = routeSource(dir);
+  return states.filter((st) => {
+    const words = STATE_SYNONYMS[st] || [st.toLowerCase()];
+    return !words.some((w) => text.includes(w));
+  });
+}
+
+// Validate the load-bearing four-step globals.css import order (Cascade Contract 2).
+function checkImportOrder(rawCss) {
+  const css = rawCss.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^[ \t]*\/\/.*$/gm, '');
+  const marks = [
+    ['@import "./personality.css"', css.indexOf('@import "./personality.css"')],
+    ['@import "tailwindcss"', css.indexOf('@import "tailwindcss"')],
+    ['@import "@nurix/components/styles.css"', css.indexOf('@import "@nurix/components/styles.css"')],
+    ['@theme inline', css.search(/^\s*@theme\s+inline\b/m)],
+  ];
+  const absent = marks.filter(([, i]) => i < 0).map(([n]) => n);
+  if (absent.length) {
+    return { problem: `globals.css is missing: ${absent.join(', ')}.`, fix: [
+      'Emit the four-step cascade order (references/personality.md §4, Cascade Contract 2):',
+      '@import "./personality.css"; -> @import "tailwindcss"; -> @import "@nurix/components/styles.css"; -> @theme inline { ... }',
+    ] };
+  }
+  const [p, t, l, th] = marks.map(([, i]) => i);
+  if (!(p < t && t < l && l < th)) {
+    return { problem: 'globals.css import order is wrong — personality -> tailwindcss -> library -> @theme is load-bearing.', fix: [
+      'Reorder so the consumer @theme inline comes AFTER the @nurix/components/styles.css import, or the library radius scale and token defaults win.',
+    ] };
+  }
+  return null;
+}
+
+// intake gate: a schema-valid design.md with a legal provenance sits at project root.
+function gateIntake(project) {
+  const p = join(project, 'design.md');
+  if (!existsSync(p)) {
+    fail('intake', `No design.md at project root (${p}).`, [
+      `Create ${p} against skills/design/data/design-md/SCHEMA.md.`,
+      'Frontmatter must set schema: design-md/v1 and provenance: project|extracted|library|default.',
+      'Resolve the look design.md-first: the project doc wins, else a confirmed library entry, else the Nurix default.',
+    ]);
+  }
+  const fm = parseFrontmatter(readText(p));
+  if (!fm) fail('intake', `${p} has no YAML frontmatter.`, ['Add a --- delimited frontmatter block with schema, product, provenance, sourced.']);
+  if (fm.schema !== 'design-md/v1') fail('intake', `design.md frontmatter schema is "${fm.schema || '(missing)'}", expected design-md/v1.`, ['Set schema: design-md/v1 in the frontmatter.']);
+  if (!PROVENANCE.has(fm.provenance)) fail('intake', `design.md provenance is "${fm.provenance || '(missing)'}"; must be one of project|extracted|library|default.`, ['Set provenance to one of: project | extracted | library | default (SCHEMA.md).']);
+  pass('intake', `design.md present with schema design-md/v1 and provenance "${fm.provenance}".`);
+}
+
+// structure gate: the map parses, is populated, has a temporal block, and every surface archetype is one of the six.
+function gateStructure(project) {
+  const blk = requireMap('structure', project);
+  if (!blk.entities.length) fail('structure', 'The structure map has no entities — the object pass was skipped.', ['Populate entities[] from the domain nouns (references/structure.md -> object pass); a small brief earns a small pass, never a skipped one.']);
+  if (!blk.surfaces.length) fail('structure', 'The structure map has no surfaces.', ['Assign each surface an archetype from the closed six under surfaces[].']);
+  if (!blk.temporal || !Object.keys(blk.temporal).length) fail('structure', 'The structure map has no temporal block.', ['Add the temporal probe (intermediate-states, read-model-lag, deletion, failure-paths) — model facts, not later polish.']);
+  const bad = blk.surfaces.filter((s) => !ARCHETYPES.has(s.archetype));
+  if (bad.length) {
+    fail('structure', `${bad.length} surface(s) carry an archetype outside the closed six: ${bad.map((s) => `${s.name || '(unnamed)'}="${s.archetype || '(none)'}"`).join(', ')}.`, [
+      `Every surface's archetype must be one of: ${[...ARCHETYPES].join(', ')}.`,
+    ]);
+  }
+  pass('structure', `${blk.surfaces.length} surface(s), all archetypes valid; ${blk.entities.length} entit(ies) and a temporal block present.`);
+}
+
+// scaffold gate: the shell, per-surface route dirs + state-shells, router wiring, and globals.css import order are in place.
+function gateScaffold(project) {
+  const blk = requireMap('scaffold', project);
+  const shellFiles = ['index.html', 'src/main.tsx', 'src/App.tsx'];
+  const missing = shellFiles.filter((f) => !existsSync(join(project, f)));
+  if (missing.length) {
+    fail('scaffold', `Missing shell file(s): ${missing.join(', ')}.`, [
+      `Run scaffold.mjs docs/design/structure.md --out ${project} to emit index.html, src/main.tsx, src/App.tsx, route wiring, and state-shells.`,
+    ]);
+  }
+  const indexHtml = readText(join(project, 'index.html'));
+  if (!/<html[^>]*\bdata-style=/.test(indexHtml)) {
+    fail('scaffold', 'index.html <html> is missing the data-style attribute.', [
+      'Emit <html data-style="..." data-density="..." data-verbosity="..." data-feedback="..." data-theme="light"> (references/personality.md §5).',
+    ]);
+  }
+  const routesDir = join(project, 'src/routes');
+  const app = readText(join(project, 'src/App.tsx'));
+  const noRoute = [];
+  const noWire = [];
+  const noShell = [];
+  for (const s of blk.surfaces) {
+    const dir = resolveRouteDir(s, routesDir);
+    const name = s.name || s.route || '(unnamed)';
+    if (!dir) { noRoute.push(`${name} (expected src/routes/${routeDirCandidates(s).join(' or /')})`); continue; }
+    const seg = s.route ? firstStaticSegment(s.route) : null;
+    if (seg && !app.toLowerCase().includes(seg)) noWire.push(`${name} (route "${s.route}" not referenced in src/App.tsx)`);
+    const states = (s.states && s.states.length) ? s.states : ['loading', 'empty', 'error', 'partial'];
+    const miss = missingStates(dir, states);
+    if (miss.length) noShell.push(`${name} (no ${miss.join(', ')} shell)`);
+  }
+  if (noRoute.length) fail('scaffold', `No route directory for surface(s): ${noRoute.join('; ')}.`, ['scaffold.mjs owns route/nav wiring — emit src/routes/<surface>/ per surface from the map.']);
+  if (noWire.length) fail('scaffold', `Route(s) not wired into the router: ${noWire.join('; ')}.`, ['Every surface route must be registered in src/App.tsx (react-router-dom) — routes and nav derive from the map, never decorated on.']);
+  if (noShell.length) fail('scaffold', `Missing state-shell stubs: ${noShell.join('; ')}.`, ['Each surface needs its loading / empty / error / degraded shells wired (references/create.md -> scaffold).']);
+  const globals = join(project, 'src/styles/globals.css');
+  if (!existsSync(globals)) fail('scaffold', 'Missing src/styles/globals.css (Tailwind glue with the four-step import order).', ['Emit src/styles/globals.css with the Cascade Contract 2 import order (references/personality.md §4).']);
+  const orderErr = checkImportOrder(readText(globals));
+  if (orderErr) fail('scaffold', orderErr.problem, orderErr.fix);
+  pass('scaffold', `Shell, ${blk.surfaces.length} wired route dir(s) with state-shells, and globals.css import order all in place.`);
+}
+
+// tokens gate: design.md clears the coverage gate (derive-personality.mjs --check) and both CSS files are emitted with the cascade order intact.
+function gateTokens(project) {
+  const dm = join(project, 'design.md');
+  if (!existsSync(dm)) fail('tokens', `No design.md at ${dm}.`, ['Resolve and materialize design.md first (intake phase).']);
+  const derive = join(SCRIPT_DIR, 'derive-personality.mjs');
+  if (!existsSync(derive)) fail('tokens', `Coverage-gate sibling not found: ${derive}.`, ['derive-personality.mjs must sit beside phase-gate.mjs in the scripts/ directory.']);
+  const res = spawnSync(process.execPath, [derive, dm, '--check'], { encoding: 'utf8' });
+  if (res.status !== 0) {
+    const detail = `${res.stdout || ''}${res.stderr || ''}`.trim();
+    fail('tokens', `The design.md coverage gate failed (derive-personality.mjs --check exited ${res.status == null ? '(spawn error)' : res.status}).`, [
+      'Assign or hint every named primitive / dial / token below, then re-run this gate:',
+      detail,
+    ]);
+  }
+  const files = ['src/styles/personality.css', 'src/styles/globals.css'];
+  const miss = files.filter((f) => !existsSync(join(project, f)));
+  if (miss.length) {
+    fail('tokens', `Coverage gate passed but emitted CSS is missing: ${miss.join(', ')}.`, [
+      `Run derive-personality.mjs ${dm} --emit ${project} to write src/styles/personality.css and src/styles/globals.css.`,
+    ]);
+  }
+  const orderErr = checkImportOrder(readText(join(project, 'src/styles/globals.css')));
+  if (orderErr) fail('tokens', orderErr.problem, orderErr.fix);
+  pass('tokens', 'Coverage gate green; personality.css + globals.css emitted with the cascade order intact.');
+}
+
+// fixtures gate: src/fixtures/ carries one seeded module per map entity.
+function gateFixtures(project) {
+  const blk = requireMap('fixtures', project);
+  const fdir = join(project, 'src/fixtures');
+  if (!existsSync(fdir)) {
+    fail('fixtures', 'No src/fixtures/ directory.', [
+      `Run generate-fixtures.mjs docs/design/structure.md --seed <n> --out ${join(project, 'src/fixtures/')} to write one seeded module per entity.`,
+    ]);
+  }
+  const bases = readdirSync(fdir).filter((f) => /\.(ts|tsx)$/.test(f)).map((f) => f.replace(/\.(ts|tsx)$/, '').toLowerCase());
+  const missing = [];
+  for (const e of blk.entities) {
+    if (!e.name) continue;
+    const base = e.name.toLowerCase();
+    const k = kebab(e.name);
+    const cands = new Set([base, k, `${base}s`, `${k}s`]);
+    if (/y$/.test(base)) { cands.add(`${base.slice(0, -1)}ies`); cands.add(`${k.slice(0, -1)}ies`); }
+    if (!bases.some((n) => cands.has(n))) missing.push(e.name);
+  }
+  if (missing.length) {
+    fail('fixtures', `No seeded fixture module for entity/ies: ${missing.join(', ')}.`, [
+      'Each map entity needs a seeded module in src/fixtures/ (fixture-before-surface). Re-run generate-fixtures.mjs.',
+    ]);
+  }
+  pass('fixtures', `Seeded fixture module present for all ${blk.entities.length} entit(ies).`);
+}
+
+// surfaces gate: every surface's route dir exists and its shell contains every declared state branch.
+function gateSurfaces(project) {
+  const blk = requireMap('surfaces', project);
+  const routesDir = join(project, 'src/routes');
+  const problems = [];
+  for (const s of blk.surfaces) {
+    const name = s.name || s.route || '(unnamed)';
+    const dir = resolveRouteDir(s, routesDir);
+    if (!dir) { problems.push(`${name}: no route dir under src/routes/ (expected ${routeDirCandidates(s).join(' or ')})`); continue; }
+    const states = (s.states && s.states.length) ? s.states : ['loading', 'empty', 'error'];
+    const miss = missingStates(dir, states);
+    if (miss.length) problems.push(`${name}: shell missing state branch(es) ${miss.join(', ')}`);
+  }
+  if (problems.length) {
+    fail('surfaces', `${problems.length} surface(s) not fully composed:`, [
+      ...problems.map((p) => `- ${p}`),
+      'Fill every declared lifecycle state into its pre-created shell (references/create.md -> surfaces); states are composed with the surface, not bolted on.',
+    ]);
+  }
+  pass('surfaces', `All ${blk.surfaces.length} surface(s) have a route dir with every declared state branch present.`);
+}
+
+const GATES = { intake: gateIntake, structure: gateStructure, scaffold: gateScaffold, tokens: gateTokens, fixtures: gateFixtures, surfaces: gateSurfaces };
+
+// Parse argv, resolve the project dir, and dispatch to the named phase gate.
+function main() {
+  const args = process.argv.slice(2);
+  const phase = args[0];
+  let project = process.cwd();
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--project') project = resolve(args[++i] || '.');
+    else if (args[i].startsWith('--project=')) project = resolve(args[i].slice('--project='.length));
+  }
+  if (!phase || !PHASES.includes(phase)) {
+    console.error(`usage: phase-gate.mjs <${PHASES.join('|')}> [--project <dir>]`);
+    process.exit(2);
+  }
+  GATES[phase](project);
+}
+
+main();

package/data/harnesses/code/skills/design/scripts/preship-sweep.mjs

@@ -0,0 +1,280 @@
+// skills/design/scripts/preship-sweep.mjs — verification-ladder rung 1 (D21/D23): whole-app static sweep — detector relay + cross-file machine checks + mandatory-procedures checklist + scope cross-check.
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, dirname, resolve, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const CATALOG = join(SCRIPT_DIR, '..', 'data', 'catalog', 'rules.csv');
+const HARD_RULES = join(SCRIPT_DIR, '..', 'references', 'hard-rules.md');
+
+const useColor = process.stdout.isTTY;
+// Wrap a string in red/yellow/green when writing to a TTY, plain otherwise.
+const red = (s) => (useColor ? `\x1b[31m${s}\x1b[0m` : s);
+const yellow = (s) => (useColor ? `\x1b[33m${s}\x1b[0m` : s);
+const green = (s) => (useColor ? `\x1b[32m${s}\x1b[0m` : s);
+const bold = (s) => (useColor ? `\x1b[1m${s}\x1b[0m` : s);
+
+// Read a UTF-8 file, returning '' when it is absent.
+function readText(path) {
+  try { return readFileSync(path, 'utf8'); } catch { return ''; }
+}
+
+// Recursively collect files under a dir whose name ends with one of the given extensions.
+function walk(dir, exts, acc = []) {
+  if (!existsSync(dir)) return acc;
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return acc; }
+  for (const ent of entries) {
+    if (ent.name === 'node_modules' || ent.name.startsWith('.')) continue;
+    const full = join(dir, ent.name);
+    if (ent.isDirectory()) walk(full, exts, acc);
+    else if (exts.some((e) => ent.name.endsWith(e))) acc.push(full);
+  }
+  return acc;
+}
+
+// Parse RFC-4180-ish CSV (quoted fields, "" escapes) into an array of row arrays.
+function parseCsv(text) {
+  const rows = [];
+  let row = [];
+  let field = '';
+  let inQ = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (inQ) {
+      if (c === '"') { if (text[i + 1] === '"') { field += '"'; i++; } else inQ = false; }
+      else field += c;
+    } else if (c === '"') inQ = true;
+    else if (c === ',') { row.push(field); field = ''; }
+    else if (c === '\n') { row.push(field); rows.push(row); row = []; field = ''; }
+    else if (c === '\r') { /* ignore */ }
+    else field += c;
+  }
+  if (field.length || row.length) { row.push(field); rows.push(row); }
+  return rows;
+}
+
+// Load rules.csv into an array of header-keyed row objects.
+function loadCatalog() {
+  const rows = parseCsv(readText(CATALOG));
+  if (!rows.length) return [];
+  const header = rows[0];
+  return rows.slice(1).filter((r) => r.length > 1).map((r) => Object.fromEntries(header.map((h, i) => [h, r[i] ?? ''])));
+}
+
+// Extract the sequence of heading levels (1-6) appearing in a source blob.
+function headingLevels(text) {
+  const levels = [];
+  const re = /<h([1-6])[\s/>]/g;
+  let m;
+  while ((m = re.exec(text))) levels.push(Number(m[1]));
+  return levels;
+}
+
+// Return the forward heading-level skips (prev -> level jump greater than one) in order.
+function headingSkips(levels) {
+  const skips = [];
+  let prev = 0;
+  for (const l of levels) {
+    if (prev && l > prev + 1) skips.push(`h${prev}->h${l}`);
+    prev = l;
+  }
+  return skips;
+}
+
+// Count the route directories under src/routes that hold at least one view file.
+function countDeliverables(project) {
+  const rd = join(project, 'src/routes');
+  if (!existsSync(rd)) return 0;
+  let n = 0;
+  for (const ent of readdirSync(rd, { withFileTypes: true })) {
+    if (!ent.isDirectory()) continue;
+    if (walk(join(rd, ent.name), ['.tsx']).length) n++;
+  }
+  return n;
+}
+
+// Count surfaces declared in the structure map by its per-surface archetype lines.
+function countSurfaces(project) {
+  const p = join(project, 'docs/design/structure.md');
+  if (!existsSync(p)) return null;
+  const m = readText(p).match(/```yaml structure\r?\n([\s\S]*?)```/);
+  if (!m) return null;
+  return (m[1].match(/^\s*archetype\s*:/gm) || []).length;
+}
+
+// Read the spc-14 nav bound (nav 5-9) from the catalog.
+function navBounds(catalog) {
+  const row = catalog.find((r) => r.id === 'spc-14');
+  const m = row && row.numbers && row.numbers.match(/nav\s*(\d+)\s*[-–]\s*(\d+)/);
+  return m ? { min: Number(m[1]), max: Number(m[2]) } : null;
+}
+
+// Count nav items in src/App.tsx, preferring an explicit <nav> region, else route entries.
+function countNav(project) {
+  const text = readText(join(project, 'src/App.tsx'));
+  const nav = text.match(/<nav[\s\S]*?<\/nav>/i);
+  if (nav) {
+    const items = (nav[0].match(/<(a|NavLink|Link|NavItem|button)\b/gi) || []).length;
+    if (items) return items;
+  }
+  return (text.match(/\bpath\s*=/g) || []).length;
+}
+
+// Try to parse detector --json stdout into a flat findings array, or null.
+function parseDetectorJson(stdout) {
+  const s = (stdout || '').trim();
+  if (!s) return [];
+  try {
+    const parsed = JSON.parse(s);
+    if (Array.isArray(parsed)) return parsed;
+    if (parsed && Array.isArray(parsed.findings)) return parsed.findings;
+    if (parsed && Array.isArray(parsed.violations)) return parsed.violations;
+    return null;
+  } catch { return null; }
+}
+
+// Render one relayed detector finding as a single fix-or-classify line.
+function formatFinding(f, project) {
+  const anchor = f.id || f.anchor || f.rule || f.key || '?';
+  const file = f.file ? relative(project, f.file) || f.file : '';
+  const loc = f.line != null ? `${file}:${f.line}` : file;
+  const evidence = f.excerpt || f.evidence || f.value || '';
+  const msg = f.message || f.statement || f.detail || f.fix || '';
+  const ev = evidence ? `  [${evidence}]` : '';
+  return `  ${red(anchor)}  ${loc}${ev}  ${msg}`.trimEnd();
+}
+
+// Spawn detector.mjs over every source file and relay its findings; returns a violation count or -1 when unavailable.
+function runDetector(project, files, section) {
+  const detector = join(SCRIPT_DIR, 'detector.mjs');
+  if (!existsSync(detector)) {
+    section.push(yellow(`  SWEEP INCOMPLETE: detector.mjs not found at ${detector} — the per-file catalog was not run. Build it before shipping.`));
+    return -1;
+  }
+  if (!files.length) { section.push('  (no src/**/*.{tsx,ts,css,html} files to scan)'); return 0; }
+  const args = [detector, ...files, '--json'];
+  const manifest = join(project, 'design.md');
+  if (existsSync(manifest)) args.push('--manifest', manifest);
+  const res = spawnSync(process.execPath, args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  const findings = parseDetectorJson(res.stdout);
+  if (findings) {
+    if (!findings.length) { section.push(green('  detector: no per-file violations.')); return 0; }
+    section.push(`  detector reported ${findings.length} violation(s) — fix each now, or classify why it does not apply in docs/memory/design-decay.md; never ignore silently:`);
+    for (const f of findings) section.push(formatFinding(f, project));
+    return findings.length;
+  }
+  if (res.stdout) section.push(res.stdout.replace(/\n$/, '').split('\n').map((l) => `  ${l}`).join('\n'));
+  if (res.stderr) section.push(yellow(res.stderr.replace(/\n$/, '').split('\n').map((l) => `  ${l}`).join('\n')));
+  return res.status ? 1 : 0;
+}
+
+// Run the cross-file machine checks (dep-02 one-h1 + heading skips) and the advisory nav-count.
+function crossFileChecks(project, files, catalog, section) {
+  const violations = [];
+  for (const file of files) {
+    if (!/\.(tsx|html)$/.test(file)) continue;
+    const text = readText(file);
+    const rel = relative(project, file) || file;
+    const h1 = (text.match(/<h1[\s/>]/g) || []).length;
+    if (h1 >= 2) violations.push(`  ${red('dep-02')}  ${rel}  ${h1} <h1> elements in one view; exactly one h1 per view.`);
+    const skips = headingSkips(headingLevels(text));
+    if (skips.length) violations.push(`  ${red('dep-02')}  ${rel}  heading level skips (${skips.join(', ')}); heading levels never skip.`);
+  }
+  const routesDir = join(project, 'src/routes');
+  if (existsSync(routesDir)) {
+    for (const ent of readdirSync(routesDir, { withFileTypes: true })) {
+      if (!ent.isDirectory()) continue;
+      const dir = join(routesDir, ent.name);
+      const total = walk(dir, ['.tsx']).reduce((n, f) => n + (readText(f).match(/<h1[\s/>]/g) || []).length, 0);
+      if (total > 1) violations.push(`  ${red('dep-02')}  src/routes/${ent.name}/  ${total} <h1> across the route shell; one h1 per route view.`);
+    }
+  }
+  if (violations.length) { section.push(...violations); }
+  else section.push(green('  cross-file machine checks (dep-02 one-h1, heading-skip): clean.'));
+
+  const bounds = navBounds(catalog);
+  const nav = countNav(project);
+  if (bounds) {
+    const within = nav >= bounds.min && nav <= bounds.max;
+    const note = `  ${within ? '' : yellow('[advisory] ')}nav items: ${nav} (spc-14 advisory band ${bounds.min}-${bounds.max}${within ? ', within' : ', outside — judged, not gated'}).`;
+    section.push(note);
+  }
+  return violations.length;
+}
+
+// Print the proc-* mandatory-procedures checklist, each row's imperative sourced from hard-rules.md.
+function procChecklist(catalog) {
+  const hard = readText(HARD_RULES);
+  const imperatives = new Map();
+  for (const line of hard.split(/\r?\n/)) {
+    const m = line.match(/^- `(proc-\d+)`\s*(.*)$/);
+    if (m) imperatives.set(m[1], m[2].trim());
+  }
+  const procs = catalog.filter((r) => /^proc-\d+$/.test(r.id)).sort((a, b) => a.id.localeCompare(b.id, undefined, { numeric: true }));
+  const lines = [];
+  for (const r of procs) {
+    const text = imperatives.get(r.id) || r.statement || '';
+    lines.push(`  [ ] ${r.id} — ${text}`);
+  }
+  return lines;
+}
+
+// Assemble and print the whole sweep, then exit non-zero when detector or cross-file checks found violations.
+function main() {
+  const args = process.argv.slice(2);
+  let project = process.cwd();
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--project') project = resolve(args[++i] || '.');
+    else if (args[i].startsWith('--project=')) project = resolve(args[i].slice('--project='.length));
+  }
+
+  const catalog = loadCatalog();
+  const files = walk(join(project, 'src'), ['.tsx', '.ts', '.css', '.html']);
+
+  console.log(bold(`preship-sweep — verification ladder rung 1  (project: ${project})`));
+  console.log('');
+
+  console.log(bold('(a) Per-file catalog — detector.mjs relay'));
+  const secA = [];
+  const detectorCount = runDetector(project, files, secA);
+  console.log(secA.join('\n'));
+  console.log('');
+
+  console.log(bold('(b) Cross-file machine checks'));
+  const secB = [];
+  const crossCount = crossFileChecks(project, files, catalog, secB);
+  console.log(secB.join('\n'));
+  console.log('');
+
+  console.log(bold('(c) Mandatory procedures — self-audit checklist (proc-*)'));
+  console.log(procChecklist(catalog).join('\n'));
+  console.log('');
+
+  console.log(bold('(c) Scope cross-check (proc-14)'));
+  const surfaces = countSurfaces(project);
+  const deliverables = countDeliverables(project);
+  if (surfaces == null) {
+    console.log(`  ${yellow('no docs/design/structure.md map found — cannot cross-check scope.')}`);
+  } else {
+    console.log(`  structure map declares ${surfaces} surface(s); found ${deliverables} route deliverable(s) under src/routes/.`);
+    if (surfaces !== deliverables) console.log(`  ${yellow(`[advisory] scope mismatch (${surfaces} vs ${deliverables}) — add or reconcile before responding (proc-14).`)}`);
+  }
+  console.log('');
+
+  const detectorFailed = detectorCount === -1 || detectorCount > 0;
+  const failed = detectorFailed || crossCount > 0;
+  if (failed) {
+    const reasons = [];
+    if (detectorCount === -1) reasons.push('detector.mjs unavailable (sweep incomplete)');
+    if (detectorCount > 0) reasons.push(`${detectorCount} per-file violation(s)`);
+    if (crossCount > 0) reasons.push(`${crossCount} cross-file violation(s)`);
+    console.log(red(`FAIL  preship-sweep — ${reasons.join('; ')}. Resolve, then re-run.`));
+    process.exit(1);
+  }
+  console.log(green('PASS  preship-sweep — no static violations; work the checklist above before ship.'));
+  process.exit(0);
+}
+
+main();