@mlmcps/ml-specs 1.0.0

package/ml-specs/scripts/spec-gate.mjs

@@ -0,0 +1,329 @@
+#!/usr/bin/env node
+// Check the MECHANICAL half of a /spec-advance lifecycle gate.
+// Pure Node, no dependencies. Read-only. No network calls — nothing leaves this machine.
+//
+//   node spec-gate.mjs specs/0001-foo.md                  # gate for the next status
+//   node spec-gate.mjs specs/0001-foo.md --to Verified    # gate for a named target
+//   node spec-gate.mjs specs/0001-foo.md --json           # machine-readable
+//   node spec-gate.mjs specs/0001-foo.md --root /path/to/repo
+//
+// Why this exists: /spec-advance's gates are half judgement and half bookkeeping, and the
+// bookkeeping half was being done by a model re-reading the spec and globbing for test files.
+// That is slow, costs tokens per run, and is the half most likely to be done sloppily — a
+// named-but-missing test file is the most common way a status ends up claiming evidence that
+// isn't there. A script does it exactly, every time, for free.
+//
+// What it deliberately does NOT decide: whether the human approved in conversation, whether a
+// §8 question is blocking, whether the reviewer was satisfied, whether the suite ran green.
+// Those are reported as MANUAL. A script that guessed at them would be worse than no script,
+// because its PASS would get believed.
+//
+// Exit codes: 0 = no mechanical gate failed · 1 = at least one FAIL · 2 = could not run.
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join, basename, relative, resolve } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { LIFECYCLE, listSpecs } from './lib/specs.mjs';
+
+// ---------------------------------------------------------------------------- args
+
+// Walked rather than searched, so a positional that happens to equal a flag's value
+// (e.g. `--root specs` then `specs/0001-foo.md`) is still read as the positional.
+const TAKES_VALUE = new Set(['--root', '--to']);
+const opts = { '--root': process.cwd(), '--to': null };
+let specArg = null;
+{
+  const argv = process.argv.slice(2);
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (TAKES_VALUE.has(a)) { opts[a] = argv[++i] ?? null; continue; }
+    if (a === '--json') { opts['--json'] = true; continue; }
+    if (a.startsWith('--')) continue;
+    if (specArg === null) specArg = a;
+  }
+}
+
+const ROOT = resolve(opts['--root'] ?? process.cwd());
+const JSON_OUT = opts['--json'] === true;
+
+if (!specArg) {
+  console.error('usage: spec-gate.mjs <spec-file> [--to <Status>] [--root <dir>] [--json]');
+  process.exit(2);
+}
+
+// ---------------------------------------------------------------------------- load
+
+const specRel = relative(ROOT, resolve(ROOT, specArg)).split('\\').join('/');
+const specAbs = join(ROOT, specRel);
+if (!existsSync(specAbs)) {
+  console.error(`spec-gate: no such file: ${specRel}`);
+  process.exit(2);
+}
+
+// Parse via the shared implementation so this agrees with /repo-status, /repo-doctor, the
+// dashboard and the MCP server about what a spec says. Two parsers would have drifted.
+const spec = listSpecs(ROOT).find((s) => s.file === specRel);
+if (!spec) {
+  console.error(`spec-gate: ${specRel} is not a spec file (expected specs/NNNN-slug.md)`);
+  process.exit(2);
+}
+
+const text = readFileSync(specAbs, 'utf8');
+const current = spec.status;
+const target = opts['--to'] ?? (current && LIFECYCLE.indexOf(current) < LIFECYCLE.length - 1
+  ? LIFECYCLE[LIFECYCLE.indexOf(current) + 1]
+  : null);
+
+const gates = [];
+// Evidence is capped so a badly-drifted spec can't bury the verdict, but a silent cap would
+// read as "that's all of it" — so say when there is more.
+const CAP = 10;
+const add = (name, verdict, detail, evidence = []) => {
+  const shown = evidence.slice(0, CAP);
+  if (evidence.length > CAP) shown.push(`… and ${evidence.length - CAP} more`);
+  gates.push({ name, verdict, detail, evidence: shown, evidenceTotal: evidence.length });
+};
+
+// ---------------------------------------------------------------------------- helpers
+
+function git(args) {
+  try {
+    return execFileSync('git', args, { cwd: ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/** The body of a numbered spec section, e.g. section(6) → everything under "## 6. …". */
+function section(n) {
+  const lines = text.split('\n');
+  const start = lines.findIndex((l) => new RegExp(`^#{1,4}\\s*${n}[.)]?\\s`).test(l));
+  if (start === -1) return null;
+  const level = (lines[start].match(/^#+/) ?? ['##'])[0].length;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    const m = lines[i].match(/^(#+)\s/);
+    if (m && m[1].length <= level) { end = i; break; }
+  }
+  return lines.slice(start + 1, end).join('\n');
+}
+
+const SKIP_DIRS = new Set([
+  '.git', 'node_modules', 'target', 'build', 'dist', 'out', 'vendor', '.venv', 'venv',
+  '__pycache__', '.next', '.nuxt', 'coverage', '.gradle', '.idea', 'bin', 'obj',
+]);
+
+/** Bounded index of basename → relative paths. Built once, only if a gate needs it. */
+let fileIndex = null;
+function indexFiles() {
+  if (fileIndex) return fileIndex;
+  fileIndex = new Map();
+  let budget = 60000; // enough for a large monorepo, bounded so this can't hang a CI job
+  const walk = (dir) => {
+    if (budget <= 0) return;
+    let entries;
+    try { entries = readdirSync(join(ROOT, dir), { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (budget <= 0) return;
+      if (e.name.startsWith('.') && e.name !== '.github') continue;
+      const rel = dir ? `${dir}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        if (SKIP_DIRS.has(e.name)) continue;
+        walk(rel);
+      } else {
+        budget--;
+        if (!fileIndex.has(e.name)) fileIndex.set(e.name, []);
+        fileIndex.get(e.name).push(rel);
+      }
+    }
+  };
+  walk('');
+  return fileIndex;
+}
+
+const TEST_EXT = 'java|kt|kts|ts|tsx|js|jsx|mjs|cjs|py|go|rb|cs|php|scala|swift|rs|dart|ex|exs';
+
+/**
+ * Pull the things a §6 test-plan table claims exist. Two shapes, because projects write both:
+ *   * a path or filename with an extension  — user.service.spec.ts, src/__tests__/foo.test.js
+ *   * a bare Java/C#-style test class name  — CouponExpiryIntegrationTest
+ * Anything else in the cell (prose, a criterion id, a method name) is ignored on purpose:
+ * a false "missing test" would block a legitimate transition, which is worse than a miss.
+ */
+function claimedTests(body) {
+  const out = new Set();
+  for (const m of body.matchAll(new RegExp(`[A-Za-z0-9_./\\\\-]+\\.(?:${TEST_EXT})\\b`, 'g'))) {
+    out.add(m[0].split('\\').join('/'));
+  }
+  for (const m of body.matchAll(/\b([A-Z][A-Za-z0-9]*(?:Test|Tests|Spec|IT|TestCase))\b/g)) {
+    out.add(m[1]);
+  }
+  return [...out];
+}
+
+function resolveTest(token) {
+  if (/[./]/.test(token) && token.includes('/')) {
+    if (existsSync(join(ROOT, token))) return token;
+    // A spec often writes a path relative to a module root rather than the repo root.
+    const hits = indexFiles().get(basename(token)) ?? [];
+    const suffix = hits.find((p) => p.endsWith(token));
+    if (suffix) return suffix;
+    return hits[0] ?? null;
+  }
+  if (/\.(?:[a-z]+)$/i.test(token)) {
+    return (indexFiles().get(token) ?? [])[0] ?? null;
+  }
+  // Bare class name — find a source file whose basename matches.
+  for (const [name, paths] of indexFiles()) {
+    if (name.replace(new RegExp(`\\.(?:${TEST_EXT})$`), '') === token) return paths[0];
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------- gates
+
+// 0. The transition itself.
+if (!current) {
+  add('lifecycle', 'FAIL', `Status cell holds no lifecycle word: ${JSON.stringify(spec.rawStatus ?? '(empty)')}`);
+} else if (!target) {
+  add('lifecycle', 'FAIL', `${current} is the last status — nothing to advance to`);
+} else if (!LIFECYCLE.includes(target)) {
+  add('lifecycle', 'FAIL', `"${target}" is not a lifecycle status (${LIFECYCLE.join(' → ')})`);
+} else {
+  const from = LIFECYCLE.indexOf(current);
+  const to = LIFECYCLE.indexOf(target);
+  if (to === from) add('lifecycle', 'FAIL', `already ${current}`);
+  else if (to < from) add('lifecycle', 'MANUAL', `moving backwards ${current} → ${target} — allowed, but it must add a Revisions row and un-tick criteria that no longer hold`);
+  else if (to - from > 1) add('lifecycle', 'FAIL', `cannot skip: ${current} → ${target} passes ${LIFECYCLE.slice(from + 1, to).join(', ')} — run the gates in order`);
+  else add('lifecycle', 'PASS', `${current} → ${target}`);
+}
+
+const forward = current && target && LIFECYCLE.indexOf(target) > LIFECYCLE.indexOf(current);
+
+// 1. Draft → Approved: unfilled template, and whatever §8 still holds.
+if (forward && target === 'Approved') {
+  const placeholders = [];
+  text.split('\n').forEach((line, i) => {
+    if (/^\s*<!--/.test(line)) return;
+    for (const m of line.matchAll(/<([a-z][a-z0-9 _/-]{2,40})>/gi)) {
+      if (/:\/\//.test(m[1])) continue;
+      placeholders.push(`${specRel}:${i + 1}  <${m[1]}>`);
+    }
+  });
+  if (placeholders.length) {
+    add('placeholders', 'FAIL', `${placeholders.length} unfilled template placeholder(s)`, placeholders);
+  } else {
+    add('placeholders', 'PASS', 'no template placeholders left');
+  }
+
+  const s8 = section(8);
+  if (s8 === null) {
+    add('section-8', 'MANUAL', 'no section 8 found — confirm the spec has an open-questions section');
+  } else {
+    const bullets = s8.split('\n').filter((l) => /^\s*[-*]\s+\S/.test(l) && !/^\s*[-*]\s+(none|n\/a|—)\b/i.test(l));
+    if (bullets.length === 0) add('section-8', 'PASS', 'section 8 holds no open questions');
+    else add('section-8', 'MANUAL', `section 8 holds ${bullets.length} open question(s) — judge whether any is blocking (would change an API shape, data model, error code, scope boundary, or compatibility)`, bullets.map((b) => b.trim()));
+  }
+
+  add('human-approval', 'MANUAL', 'the human must approve in the conversation — a script cannot witness that');
+}
+
+// 2. Approved → Implemented, and still required at Verified: criteria + the named tests.
+if (forward && (target === 'Implemented' || target === 'Verified')) {
+  if (spec.acTotal === 0) {
+    add('criteria', 'FAIL', 'no acceptance criteria — there is nothing to verify against');
+  } else if (spec.acChecked < spec.acTotal) {
+    add('criteria', 'FAIL', `${spec.acTotal - spec.acChecked} of ${spec.acTotal} acceptance criteria unchecked`);
+  } else {
+    add('criteria', 'PASS', `all ${spec.acTotal} acceptance criteria checked`);
+  }
+
+  const s6 = section(6);
+  if (s6 === null) {
+    add('tests-exist', 'FAIL', 'no section 6 (test plan) found — nothing names the tests');
+  } else {
+    const claimed = claimedTests(s6);
+    if (claimed.length === 0) {
+      add('tests-exist', 'FAIL', 'section 6 names no test file or test class — a test plan that names nothing cannot be checked');
+    } else {
+      const missing = [];
+      const found = [];
+      for (const t of claimed) {
+        const hit = resolveTest(t);
+        if (hit) found.push(`${t} → ${hit}`);
+        else missing.push(t);
+      }
+      if (missing.length) {
+        add('tests-exist', 'FAIL', `${missing.length} of ${claimed.length} named test(s) do not exist on disk`, missing);
+      } else {
+        add('tests-exist', 'PASS', `all ${claimed.length} named test(s) exist on disk`, found);
+      }
+    }
+  }
+}
+
+// 3. Implemented → Verified: the parts only a run can establish.
+if (forward && target === 'Verified') {
+  add('suite-green', 'MANUAL', 'the §6.1 full suite must have run green end to end in this session — if it cannot be run here, refuse the transition');
+  add('adversarial-review', 'MANUAL', 'a clean /spec-verify must have marked every criterion satisfied, with a functional/E2E test for each user-facing or contract-level one');
+}
+
+// 4. Verified → Archived: is the branch actually merged?
+if (forward && target === 'Archived') {
+  const branch = spec.branch;
+  if (!branch) {
+    add('branch-merged', 'FAIL', 'no Branch recorded in the header table — cannot check whether it merged');
+  } else if (!git(['rev-parse', '--is-inside-work-tree'])) {
+    add('branch-merged', 'MANUAL', 'not a git work tree — confirm the merge by hand');
+  } else {
+    const head = git(['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD']);
+    const def = (head && head.replace(/^origin\//, ''))
+      ?? ['main', 'master', 'develop'].find((b) => git(['rev-parse', '--verify', '--quiet', b]));
+    const clean = branch.replace(/[`*]/g, '').trim();
+    if (!def) {
+      add('branch-merged', 'MANUAL', `could not determine the default branch — check \`git branch --merged\` for ${clean} by hand`);
+    } else {
+      const merged = (git(['branch', '--merged', def]) ?? '')
+        .split('\n').map((l) => l.replace(/^[*+ ]+/, '').trim());
+      if (merged.includes(clean)) {
+        add('branch-merged', 'PASS', `${clean} is merged into ${def}`);
+      } else {
+        const contains = git(['branch', '--contains', clean]);
+        add('branch-merged', 'FAIL', `${clean} is not in \`git branch --merged ${def}\``,
+          contains ? [`branches containing it: ${contains.replace(/\s+/g, ' ').trim()}`] : []);
+      }
+    }
+  }
+  add('archive-move', 'MANUAL', `on pass, \`git mv ${specRel} specs/archive/${basename(specRel)}\` and fix links that pointed at it — the number is never reused`);
+}
+
+// ---------------------------------------------------------------------------- report
+
+const failed = gates.filter((g) => g.verdict === 'FAIL');
+const manual = gates.filter((g) => g.verdict === 'MANUAL');
+
+if (JSON_OUT) {
+  console.log(JSON.stringify({
+    spec: specRel, title: spec.title, current, target,
+    ok: failed.length === 0, gates,
+  }, null, 2));
+} else {
+  const mark = { PASS: '✓', FAIL: '✗', MANUAL: '·' };
+  console.log(`${specRel} — ${spec.title}`);
+  console.log(`${current ?? '(no status)'} → ${target ?? '(none)'}\n`);
+  for (const g of gates) {
+    console.log(`  ${mark[g.verdict]} ${g.verdict.padEnd(6)} ${g.name.padEnd(18)} ${g.detail}`);
+    for (const e of g.evidence) console.log(`             ${e}`);
+  }
+  console.log();
+  if (failed.length) {
+    console.log(`✗ ${failed.length} gate(s) failed — do not write the status. Report which, and the one command that produces the missing evidence.`);
+  } else {
+    console.log('✓ no mechanical gate failed.');
+  }
+  if (manual.length) {
+    console.log(`· ${manual.length} gate(s) need judgement — this script does not decide them.`);
+  }
+}
+
+process.exit(failed.length ? 1 : 0);

package/ml-specs/scripts/spec-trace.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// Verify the ID chain from ticket to test case for one spec, or every spec.
+// Pure Node, no dependencies. Read-only. No network calls — nothing leaves this machine.
+//
+//   node spec-trace.mjs                          # every spec in the repo
+//   node spec-trace.mjs specs/0031-foo.md        # one spec
+//   node spec-trace.mjs 0031                     # by id
+//   node spec-trace.mjs --json                   # machine-readable
+//   node spec-trace.mjs --root /path/to/repo
+//
+// Exit code 1 if any chain is broken, so it can gate a merge.
+//
+// Why this exists: "which requirement is covered by which test, and did it ship?"
+// is the question an auditor asks and the one a repo usually cannot answer without
+// a week of archaeology. It only stays answerable if every artifact carries the
+// spec's id — and the way that silently stops being true is a hand-typed branch
+// name. This checks it in milliseconds, for free, on every push.
+//
+// It deliberately distinguishes BROKEN from UNVERIFIABLE. A ticket reference a
+// human typed into the header table cannot be checked from inside the repo; saying
+// so is honest, and quietly counting it as passing would make the report a lie.
+
+import { listSpecs } from './lib/specs.mjs';
+import { buildChain, verifyChain, renderChain } from './lib/trace.mjs';
+
+const argv = process.argv.slice(2);
+const flag = (name, fallback = null) => {
+  const i = argv.indexOf(`--${name}`);
+  return i === -1 ? fallback : (argv[i + 1] ?? fallback);
+};
+const has = (name) => argv.includes(`--${name}`);
+
+const root = flag('root', process.cwd());
+const json = has('json');
+const target = argv.find((a) => !a.startsWith('--') && argv[argv.indexOf(a) - 1] !== '--root');
+
+const C = process.stdout.isTTY && !json
+  ? { dim: (s) => `\x1b[2m${s}\x1b[0m`, red: (s) => `\x1b[31m${s}\x1b[0m`,
+      green: (s) => `\x1b[32m${s}\x1b[0m`, bold: (s) => `\x1b[1m${s}\x1b[0m` }
+  : { dim: (s) => s, red: (s) => s, green: (s) => s, bold: (s) => s };
+
+const all = listSpecs(root);
+const specs = target
+  ? all.filter((s) => s.id === target || s.file.endsWith(target) || s.file === target)
+  : all;
+
+if (specs.length === 0) {
+  console.error(target ? `no spec matching "${target}" under ${root}` : `no specs under ${root}`);
+  process.exit(1);
+}
+
+const results = specs.map((spec) => {
+  const chain = buildChain(spec);
+  const report = verifyChain(chain);
+  return { spec, chain, report };
+});
+
+if (json) {
+  console.log(JSON.stringify({
+    root,
+    ok: results.every((r) => r.report.ok),
+    specs: results.map(({ spec, chain, report }) => ({
+      id: spec.id,
+      title: spec.title,
+      status: spec.status,
+      ok: report.ok,
+      links: chain.links.map((l) => ({ kind: l.kind, ref: l.ref, origin: l.origin })),
+      broken: report.broken.map((b) => ({ kind: b.link.kind, ref: b.link.ref, reason: b.reason, found: b.found })),
+      unverifiable: report.unverifiable.map((l) => ({ kind: l.kind, ref: l.ref })),
+    })),
+  }, null, 2));
+} else {
+  for (const { spec, chain, report } of results) {
+    console.log(`${C.bold(`SPEC-${spec.id}`)} ${spec.title}  ${C.dim(spec.status ?? 'unknown')}`);
+    console.log(`  ${renderChain(chain)}`);
+    console.log(report.ok ? `  ${C.green('chain intact')}` : `  ${C.red(`${report.broken.length} broken link(s)`)}`);
+    for (const b of report.broken) {
+      console.log(`    ${C.red('x')} ${b.link.kind} ${b.link.ref} ${C.dim(`(${b.reason}, found ${b.found ?? 'nothing'})`)}`);
+    }
+    for (const u of report.unverifiable) {
+      console.log(`    ${C.dim(`? ${u.kind} ${u.ref} — hand-typed, cannot be verified from the repo`)}`);
+    }
+    console.log();
+  }
+  const broken = results.filter((r) => !r.report.ok).length;
+  console.log(broken === 0
+    ? C.green(`  ${results.length} spec(s), every chain intact`)
+    : C.red(`  ${broken} of ${results.length} spec(s) have a broken chain`));
+}
+
+process.exit(results.every((r) => r.report.ok) ? 0 : 1);

package/ml-specs/scripts/survey-estate.mjs

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+// Survey candidate repos before onboarding the toolkit into them.
+// Pure Node, no dependencies, read-only, no network calls.
+//
+//   node survey-estate.mjs ../                    # survey every git repo under a parent dir
+//   node survey-estate.mjs ../svc-a ../svc-b      # or name them explicitly
+//   node survey-estate.mjs ../ --json             # machine-readable
+//
+// Why this exists: /repo-init is the most expensive single operation in the toolkit — a full
+// codebase scan. Running it blindly across an estate burns a lot of tokens and produces a pile
+// of unreviewed knowledge layers. This does the CHEAP, MECHANICAL part first — what's there,
+// what state it's in, how much cross-service surface it has — so the expensive part is aimed
+// rather than sprayed. It reads files; it never writes.
+//
+// Every judgment here is a heuristic and is labelled as one. It tells you where to look, not
+// what to conclude.
+
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join, basename, resolve } from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+const args = process.argv.slice(2);
+const asJson = args.includes('--json');
+const targets = args.filter((a) => !a.startsWith('--'));
+if (targets.length === 0) {
+  console.error('usage: survey-estate.mjs <parent-dir | repo...> [--json]');
+  process.exit(1);
+}
+
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', 'target', 'build', 'dist', 'vendor', '.next', '.venv', 'venv',
+  '__pycache__', '.gradle', '.idea', 'coverage', 'out', 'bin', 'obj', '.terraform',
+]);
+const SOURCE_EXT = new Set([
+  'js', 'mjs', 'cjs', 'jsx', 'ts', 'tsx', 'java', 'kt', 'py', 'go', 'rb', 'cs', 'php', 'scala',
+]);
+const MAX_FILES = 4000;      // bounded: a survey must stay cheap even on a monorepo
+const MAX_BYTES = 200_000;
+
+// Manifest → stack. First match wins.
+const MANIFESTS = [
+  ['pom.xml', 'Java/Maven'],
+  ['build.gradle', 'Java/Gradle'],
+  ['build.gradle.kts', 'Kotlin/Gradle'],
+  ['package.json', 'Node/JS'],
+  ['pyproject.toml', 'Python'],
+  ['requirements.txt', 'Python'],
+  ['go.mod', 'Go'],
+  ['Gemfile', 'Ruby'],
+  ['composer.json', 'PHP'],
+  ['Cargo.toml', 'Rust'],
+  ['pubspec.yaml', 'Dart/Flutter'],
+];
+
+// Cross-service surface. These are the edges /repo-estate and /repo-impact need — a repo with
+// many of them is worth onboarding early, because it unlocks answers for its peers too.
+const EDGE_PATTERNS = {
+  events: /@SqsListener|@KafkaListener|@RabbitListener|SqsClient|SnsClient|KafkaProducer|kafkajs|amqplib|@nestjs\/microservices|PubSub\(/,
+  httpClients: /@FeignClient|axios\.create|new HttpClient|RestTemplate|WebClient\.builder|got\.extend|httpx\.Client/,
+  contracts: /openapi|swagger|\.proto\b|graphql/i,
+};
+
+const git = (cwd, ...a) => {
+  try {
+    return execFileSync('git', ['-C', cwd, ...a], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch {
+    return '';
+  }
+};
+
+function walk(root) {
+  const files = [];
+  const stack = [root];
+  while (stack.length && files.length < MAX_FILES) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      if (e.name.startsWith('.') && e.name !== '.github') continue;
+      if (SKIP_DIRS.has(e.name)) continue;
+      const full = join(dir, e.name);
+      if (e.isDirectory()) stack.push(full);
+      else files.push(full);
+      if (files.length >= MAX_FILES) break;
+    }
+  }
+  return files;
+}
+
+function surveyRepo(path) {
+  const name = basename(path);
+  const isRepo = git(path, 'rev-parse', '--is-inside-work-tree') === 'true';
+
+  const stack = MANIFESTS.find(([f]) => existsSync(join(path, f)));
+  const has = (p) => existsSync(join(path, p));
+
+  // Knowledge-layer state decides init vs adopt vs nothing-to-do.
+  const claude = has('CLAUDE.md');
+  const patterns = has('docs/PATTERNS.md');
+  const architecture = has('docs/ARCHITECTURE.md') || has('docs/architecture');
+  const specs = has('specs');
+  const specCount = specs
+    ? readdirSync(join(path, 'specs')).filter((f) => /^\d{4}[a-z]?-.*\.md$/.test(f)).length
+    : 0;
+  // Other tools' agent instructions — these are the repos where /repo-init would clobber.
+  const otherAgentDocs = ['AGENTS.md', '.cursorrules', '.github/copilot-instructions.md']
+    .filter(has);
+
+  let layer;
+  if (claude && patterns && architecture) layer = 'full';
+  else if (claude || patterns || architecture) layer = 'partial';
+  else if (otherAgentDocs.length) layer = 'other-tool';
+  else layer = 'none';
+
+  // Activity — a dormant repo is rarely worth the scan.
+  const lastCommit = isRepo ? git(path, 'log', '-1', '--format=%ad', '--date=short') : '';
+  const recent = isRepo
+    ? Number(git(path, 'rev-list', '--count', '--since=90.days', 'HEAD') || 0)
+    : 0;
+  const dirty = isRepo ? git(path, 'status', '--porcelain').split('\n').filter(Boolean).length : 0;
+
+  // Edge signals.
+  const edges = { events: 0, httpClients: 0, contracts: 0 };
+  let scanned = 0;
+  for (const f of walk(path)) {
+    const ext = f.split('.').pop().toLowerCase();
+    const isContractFile = /\.(proto|graphql)$/i.test(f) || /openapi|swagger/i.test(basename(f));
+    if (!SOURCE_EXT.has(ext) && !isContractFile) continue;
+    let text;
+    try {
+      if (statSync(f).size > MAX_BYTES) continue;
+      text = readFileSync(f, 'utf8');
+    } catch { continue; }
+    scanned++;
+    for (const [k, re] of Object.entries(EDGE_PATTERNS)) if (re.test(text)) edges[k]++;
+  }
+
+  // Recommendation. Deliberately conservative: anything ambiguous goes to a human.
+  let action, why;
+  if (!isRepo) { action = 'skip'; why = 'not a git repo'; }
+  else if (!stack) { action = 'review'; why = 'no recognised manifest — may not be a service'; }
+  else if (layer === 'full') { action = 'refresh'; why = 'already onboarded; /repo-refresh keeps it current'; }
+  else if (layer === 'partial' || layer === 'other-tool') { action = 'adopt'; why = `existing docs (${[...(claude ? ['CLAUDE.md'] : []), ...(patterns ? ['PATTERNS'] : []), ...otherAgentDocs].join(', ')}) — /repo-init would clobber them`; }
+  else if (recent === 0) { action = 'review'; why = `no commits in 90 days (last: ${lastCommit || 'unknown'}) — dormant?`; }
+  else { action = 'init'; why = 'no knowledge layer, active repo'; }
+
+  return {
+    name, path, isRepo,
+    stack: stack ? stack[1] : null,
+    layer, claude, patterns, architecture, specs: specCount, otherAgentDocs,
+    lastCommit, commits90d: recent, dirty,
+    edges, edgeTotal: edges.events + edges.httpClients + edges.contracts,
+    filesScanned: scanned, truncated: scanned >= MAX_FILES,
+    action, why,
+  };
+}
+
+// --- resolve targets --------------------------------------------------------
+
+// Expand each target independently: a git repo is itself; any other directory is treated as a
+// parent and scanned one level for repos. Doing this per-target rather than only when exactly
+// one was given means `survey ~/work ~/other` works, and — the case that actually bit — a
+// parent directory still expands when the shell appended stray words to the command.
+const repos = [];
+const missing = [];
+for (const t of targets) {
+  const p = resolve(t);
+  if (!existsSync(p)) { missing.push(t); continue; }
+  if (existsSync(join(p, '.git'))) { repos.push(p); continue; }
+  let children;
+  try { children = readdirSync(p, { withFileTypes: true }); } catch { missing.push(t); continue; }
+  const found = children
+    .filter((e) => e.isDirectory() && !e.name.startsWith('.') && existsSync(join(p, e.name, '.git')))
+    .map((e) => join(p, e.name));
+  if (found.length) repos.push(...found);
+  else missing.push(t);
+}
+
+if (missing.length) {
+  // zsh does not treat `#` as a comment interactively, so a pasted trailing comment arrives as
+  // arguments. Say so plainly instead of reporting six English words as "not a git repo".
+  console.error(`Not a repo and no repos inside: ${missing.join(', ')}`);
+  console.error('If you pasted a trailing `# comment`, zsh passed those words as arguments — drop it.\n');
+}
+
+if (repos.length === 0) {
+  console.error('No git repos found. Point at a parent directory, or name the repos.');
+  process.exit(1);
+}
+
+const results = repos.map(surveyRepo);
+
+if (asJson) {
+  console.log(JSON.stringify(results, null, 2));
+  process.exit(0);
+}
+
+// --- report -----------------------------------------------------------------
+
+const ORDER = { init: 0, adopt: 1, review: 2, refresh: 3, skip: 4 };
+results.sort((a, b) => (ORDER[a.action] - ORDER[b.action]) || (b.edgeTotal - a.edgeTotal));
+
+const pad = (s, n) => String(s ?? '').padEnd(n).slice(0, n);
+console.log(`Surveyed ${results.length} repo(s). Read-only — nothing was modified.\n`);
+console.log(`${pad('REPO', 26)} ${pad('ACTION', 8)} ${pad('STACK', 14)} ${pad('LAYER', 10)} ${pad('SPECS', 6)} ${pad('90d', 5)} ${pad('EDGES', 6)}`);
+console.log('─'.repeat(84));
+for (const r of results) {
+  console.log(
+    `${pad(r.name, 26)} ${pad(r.action, 8)} ${pad(r.stack ?? '—', 14)} ${pad(r.layer, 10)} ` +
+    `${pad(r.specs || '—', 6)} ${pad(r.commits90d, 5)} ${pad(r.edgeTotal || '—', 6)}`,
+  );
+}
+
+console.log('\nWhy, and what needs a human:');
+for (const r of results) {
+  console.log(`  ${r.name}: ${r.why}`);
+  if (r.dirty) console.log(`      ⚠ ${r.dirty} uncommitted change(s) — onboard on a clean tree so the diff is reviewable`);
+  if (r.truncated) console.log(`      note: file scan hit the ${MAX_FILES}-file cap; edge counts are a floor, not a total`);
+}
+
+const init = results.filter((r) => r.action === 'init');
+const adopt = results.filter((r) => r.action === 'adopt');
+console.log(`\nSuggested first wave (most cross-service surface — onboarding these unlocks /repo-impact for their peers):`);
+for (const r of [...init, ...adopt].sort((a, b) => b.edgeTotal - a.edgeTotal).slice(0, 3)) {
+  console.log(`  ${r.name}  (${r.edgeTotal} edge signals: ${r.edges.events} event, ${r.edges.httpClients} http-client, ${r.edges.contracts} contract)`);
+}
+console.log(`\n${init.length} to /repo-init, ${adopt.length} to /repo-adopt, ` +
+  `${results.filter((r) => r.action === 'review').length} needing a decision, ` +
+  `${results.filter((r) => r.action === 'refresh').length} already onboarded.`);
+console.log('Edge counts are FILE counts matching known patterns — a signal of where the contracts are, not a contract inventory.');