@mlmcps/ml-specs 1.0.0

package/ml-specs/mcp/ml-specs-server.test.mjs

@@ -0,0 +1,225 @@
+// Tests for the MCP server's protocol surface, driven the way a client drives it: spawn the
+// process, write newline-delimited JSON-RPC to stdin, read the replies. There is nothing to
+// import — the server is a script that owns stdio the moment it loads — so a subprocess is the
+// honest unit here, and it also catches the failure a unit test would miss: the server not
+// starting at all.
+//
+// Run with: node --test ml-specs/mcp/
+import { test, describe, before } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SERVER = join(HERE, 'ml-specs-server.mjs');
+
+const INIT = {
+  jsonrpc: '2.0', id: 0, method: 'initialize',
+  params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'test', version: '1' } },
+};
+
+// Every exchange re-initializes: the server holds no cross-request state worth preserving and a
+// fresh process per case keeps one failure from cascading into the next.
+function rpc(...requests) {
+  const input = [INIT, ...requests].map((r) => JSON.stringify(r)).join('\n') + '\n';
+  const out = execFileSync('node', [SERVER, '--root', HERE], { input, encoding: 'utf8' });
+  const byId = new Map();
+  for (const line of out.trim().split('\n')) {
+    const msg = JSON.parse(line);
+    byId.set(msg.id, msg);
+  }
+  return byId;
+}
+
+/** Same, against an arbitrary repo root — the script-backed tools answer about a repo, not about mcp/. */
+function rpcAt(root, ...requests) {
+  const input = [INIT, ...requests].map((r) => JSON.stringify(r)).join('\n') + '\n';
+  const out = execFileSync('node', [SERVER, '--root', root], { input, encoding: 'utf8' });
+  const byId = new Map();
+  for (const line of out.trim().split('\n')) { const msg = JSON.parse(line); byId.set(msg.id, msg); }
+  return byId;
+}
+
+const EXAMPLE_REPO = join(HERE, '..', '..', 'examples', 'promo-service');
+const payload = (msg) => JSON.parse(msg.result.content[0].text);
+const callAt = (root, name, args = {}) =>
+  rpcAt(root, { jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name, arguments: args } }).get(1);
+
+describe('script-backed tools', () => {
+  test('every deterministic script in scripts/ that ports is exposed', () => {
+    const tools = rpc({ jsonrpc: '2.0', id: 1, method: 'tools/list' }).get(1).result.tools.map((t) => t.name);
+    for (const name of ['spec_gate', 'spec_trace', 'spec_brief', 'nfr_check', 'estate_survey']) {
+      assert.ok(tools.includes(name), `${name} is not exposed`);
+    }
+  });
+
+  test('spec_gate accepts a bare id, not only a path', () => {
+    // spec-gate.mjs itself takes a path; spec-trace and spec-brief take either. A caller cannot
+    // be expected to know which is which, so the server resolves it.
+    const byPath = payload(callAt(EXAMPLE_REPO, 'spec_gate', { spec: 'specs/0001-add-coupon-expiry.md' }));
+    const byId = payload(callAt(EXAMPLE_REPO, 'spec_gate', { spec: '0001' }));
+    assert.equal(byId.spec, byPath.spec);
+    assert.ok(Array.isArray(byId.gates) && byId.gates.length, 'no gates returned');
+  });
+
+  test('spec_gate reports a failed gate as a RESULT, not a tool error', () => {
+    // The scripts exit 1 to mean "the gate failed". Treating that as a crash would turn a
+    // legitimate FAIL into something the caller cannot read.
+    const msg = callAt(EXAMPLE_REPO, 'spec_gate', { spec: '0001', to: 'Archived' });
+    assert.notEqual(msg.result.isError, true, 'a failing gate must not be an error');
+    const body = payload(msg);
+    assert.ok('ok' in body && Array.isArray(body.gates));
+    assert.ok(body.gates.some((g) => ['PASS', 'FAIL', 'MANUAL'].includes(g.verdict)));
+  });
+
+  test('spec_gate refuses an unknown id rather than guessing', () => {
+    const msg = callAt(EXAMPLE_REPO, 'spec_gate', { spec: '9999' });
+    assert.equal(msg.result.isError, true);
+    assert.match(msg.result.content[0].text, /no spec with id 9999/);
+  });
+
+  test('spec_trace returns the chain for every spec', () => {
+    const body = payload(callAt(EXAMPLE_REPO, 'spec_trace'));
+    assert.ok(Array.isArray(body.specs) && body.specs.length > 0);
+    assert.ok('ok' in body);
+  });
+
+  test('spec_brief returns markdown, deliberately not JSON', () => {
+    const body = payload(callAt(EXAMPLE_REPO, 'spec_brief', { spec: '0001' }));
+    assert.match(body.output, /^# SPEC-0001/m);
+    assert.ok(!body.output.trimStart().startsWith('{'), 'a brief is a document, not a payload');
+  });
+
+  test('nfr_check distinguishes "no NFR file" from "no NFR problems"', () => {
+    // Same rule as estate_lookup: absent means UNKNOWN, not zero. A false all-clear here is worse
+    // than no answer, because it gets believed.
+    const body = payload(callAt(EXAMPLE_REPO, 'nfr_check'));
+    assert.equal(body.present, false);
+    assert.match(body.note, /UNKNOWN, not absent/);
+  });
+
+  test('a relative --root is not applied twice', () => {
+    // ROOT is both the spawn cwd and the --root handed to each script. When it was relative the
+    // two composed and every script looked inside <root>/<root>, returning nothing.
+    const rel = 'examples/promo-service';
+    const repoRoot = join(HERE, '..', '..');
+    const input = [INIT, { jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'spec_trace', arguments: {} } }]
+      .map((r) => JSON.stringify(r)).join('\n') + '\n';
+    const out = execFileSync('node', [SERVER, '--root', rel], { input, encoding: 'utf8', cwd: repoRoot });
+    const msg = JSON.parse(out.trim().split('\n').find((l) => JSON.parse(l).id === 1));
+    assert.notEqual(msg.result.isError, true, 'a relative root must work');
+    assert.ok(JSON.parse(msg.result.content[0].text).specs.length > 0);
+  });
+
+  test('write-capable flags are never reachable through a tool', () => {
+    // nfr-compile --apply and spec-brief --out both write. The server promises read-only, and
+    // that promise has to hold by construction, not by convention.
+    const src = readFileSync(SERVER, 'utf8');
+    const dispatch = src.slice(src.indexOf('function callTool'));
+    for (const flag of ["'--apply'", "'--out'", "'--gates'"]) {
+      assert.ok(!dispatch.includes(flag), `${flag} is reachable from a tool`);
+    }
+  });
+});
+
+describe('prompts', () => {
+  let list;
+  before(() => {
+    list = rpc({ jsonrpc: '2.0', id: 1, method: 'prompts/list' }).get(1).result.prompts;
+  });
+
+  test('the server advertises the prompts capability', () => {
+    const caps = rpc().get(0).result.capabilities;
+    assert.ok(caps.prompts, 'a client that sees no prompts capability never calls prompts/list');
+  });
+
+  test('every command file is exposed as a prompt', () => {
+    assert.ok(list.length >= 18, `expected the whole commands/ dir, got ${list.length}`);
+    for (const name of ['spec', 'spec-build', 'spec-verify', 'code', 'fix', 'repo-init']) {
+      assert.ok(list.some((p) => p.name === name), `missing prompt: ${name}`);
+    }
+  });
+
+  test('descriptions come from the command frontmatter', () => {
+    const spec = list.find((p) => p.name === 'spec');
+    assert.match(spec.description, /spec-driven-development spec/);
+  });
+
+  test('a command with no $ARGUMENTS declares no arguments', () => {
+    // Otherwise a client renders a required-looking field for a command that ignores it.
+    assert.deepEqual(list.find((p) => p.name === 'repo-init').arguments, []);
+  });
+
+  test('an argument is never required, so a client cannot block on it', () => {
+    for (const p of list) {
+      for (const a of p.arguments) assert.notEqual(a.required, true, `${p.name} would block`);
+    }
+  });
+
+  test('prompts/get substitutes $ARGUMENTS', () => {
+    const res = rpc({
+      jsonrpc: '2.0', id: 1, method: 'prompts/get',
+      params: { name: 'spec', arguments: { arguments: 'PAY-42 refunds' } },
+    }).get(1).result;
+    const text = res.messages[0].content.text;
+    assert.match(text, /PAY-42 refunds/);
+    assert.ok(!text.includes('$ARGUMENTS'), 'an unsubstituted placeholder reaches the model as literal text');
+  });
+
+  test('omitting arguments leaves no placeholder behind', () => {
+    const text = rpc({
+      jsonrpc: '2.0', id: 1, method: 'prompts/get', params: { name: 'spec' },
+    }).get(1).result.messages[0].content.text;
+    assert.ok(!text.includes('$ARGUMENTS'));
+  });
+
+  test('an agent a command names in bold is inlined', () => {
+    // The client has no subagents; without this the delegation step silently does nothing.
+    const text = rpc({
+      jsonrpc: '2.0', id: 1, method: 'prompts/get', params: { name: 'spec' },
+    }).get(1).result.messages[0].content.text;
+    assert.match(text, /Inlined agent instructions/);
+    assert.match(text, /### Agent: spec-reviewer/);
+  });
+
+  test('a command that delegates to nobody gets no appendix', () => {
+    const text = rpc({
+      jsonrpc: '2.0', id: 1, method: 'prompts/get', params: { name: 'repo-doctor' },
+    }).get(1).result.messages[0].content.text;
+    assert.ok(!text.includes('Inlined agent instructions'));
+  });
+
+  test('an unknown prompt is an error, not an empty prompt', () => {
+    const msg = rpc({ jsonrpc: '2.0', id: 1, method: 'prompts/get', params: { name: 'nope' } }).get(1);
+    assert.ok(msg.error);
+    assert.match(msg.error.message, /no such prompt/);
+  });
+});
+
+describe('the existing surface still works', () => {
+  // Pinned deliberately: the tool list is a published contract, and a tool appearing or vanishing
+  // by accident is exactly what this catches. Changing it is meant to be a decision someone makes
+  // in a diff, which is why this assertion is exhaustive rather than a subset check.
+  test('tools/list is exactly the published surface', () => {
+    const names = rpc({ jsonrpc: '2.0', id: 1, method: 'tools/list' }).get(1).result.tools.map((t) => t.name);
+    assert.deepEqual(names.sort(), [
+      // the original four — facts parsed out of the repo's own docs
+      'estate_lookup', 'knowledge_check', 'spec_list', 'spec_next_number',
+      // the deterministic scripts, which used to be reachable only from Claude Code
+      'estate_survey', 'nfr_check', 'spec_brief', 'spec_gate', 'spec_trace',
+    ].sort());
+  });
+
+  test('every tool declares a usable input schema', () => {
+    const tools = rpc({ jsonrpc: '2.0', id: 1, method: 'tools/list' }).get(1).result.tools;
+    for (const t of tools) {
+      assert.ok(t.description && t.description.length > 40, `${t.name} has no real description`);
+      assert.equal(t.inputSchema.type, 'object', `${t.name} schema is not an object`);
+      for (const req of t.inputSchema.required ?? []) {
+        assert.ok(t.inputSchema.properties?.[req], `${t.name} requires undeclared property ${req}`);
+      }
+    }
+  });
+});

package/ml-specs/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@mlmcps/ml-specs-mcp",
+  "version": "1.0.0",
+  "description": "Read-only MCP server for spec-driven development: estate contract lookup, knowledge-layer checks, and spec inventory over a local repo, plus the toolkit's spec-driven commands served as MCP prompts.",
+  "type": "module",
+  "scripts": {
+    "test": "node --test 'scripts/lib/*.test.mjs' 'scripts/*.test.mjs' 'mcp/*.test.mjs'"
+  },
+  "private": false,
+  "license": "MIT",
+  "bin": {
+    "ml-specs-mcp": "mcp/ml-specs-server.mjs"
+  },
+  "files": [
+    "mcp/",
+    "commands/",
+    "agents/",
+    "scripts/",
+    "!scripts/**/*.test.mjs",
+    "!scripts/lib/*.test.mjs",
+    "!mcp/*.test.mjs",
+    "templates/ci/knowledge-check.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MLMCPS/ml-claude-plugins.git",
+    "directory": "ml-specs"
+  },
+  "keywords": [
+    "mcp",
+    "spec-driven-development",
+    "claude"
+  ],
+  "dependencies": {}
+}

package/ml-specs/scripts/branch-policy.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// Install and audit the branch policy that makes the spec gate blocking.
+//
+//   node branch-policy.mjs audit api-neelias neelias-pos
+//   node branch-policy.mjs install api-neelias --dry-run
+//   node branch-policy.mjs audit api-neelias --json
+//
+// Credentials from the environment: ADO_ORG/ADO_PROJECT/ADO_PAT, or
+// GITHUB_OWNER/GITHUB_TOKEN with SDD_SCM_TOOL=github.
+// Branch from SDD_PROTECTED_BRANCH (default main); build ref from SDD_BUILD_ID.
+//
+// Exit code 1 if any branch is ungated.
+//
+// Why this exists: ci/azure-pipelines.yml describes the checks, but a pipeline
+// that runs and reports changes nothing. The gate is the POLICY. And the way a
+// gate stops being a gate is silent — someone sets it to advisory on a Friday to
+// unblock a release, nothing breaks, no test fails, and merges quietly stop
+// being gated until an audit finds the holes months later.
+
+import { adoPolicy, githubPolicy, auditOk, auditSummary } from './lib/policy.mjs';
+import { args, colours, transportFor, scmConfig, env, printTranscript } from './lib/cli.mjs';
+
+const { positional, json, dryRun } = args();
+const [action, ...repos] = positional;
+const C = colours(process.stdout.isTTY && !json);
+
+if (!['install', 'audit'].includes(action) || repos.length === 0) {
+  console.error('usage: branch-policy.mjs <install|audit> <repo...> [--dry-run] [--json]');
+  process.exit(1);
+}
+
+const transport = transportFor(dryRun);
+const { tool, config } = scmConfig(transport);
+const mgr = tool === 'github' ? githubPolicy(config) : adoPolicy(config);
+const branch = env('SDD_PROTECTED_BRANCH', 'main');
+const buildRef = env('SDD_BUILD_ID', 'sdd-spec-gate');
+
+if (dryRun && !json) console.log(`${C.bold('dry run')} ${C.dim('— nothing is sent')}\n`);
+
+const results = [];
+for (const repo of repos) {
+  try {
+    results.push(action === 'install'
+      ? await mgr.install(repo, branch, buildRef)
+      : await mgr.audit(repo, branch));
+  } catch (e) {
+    results.push({ repo, branch, tool, present: false, blocking: false,
+                   findings: [{ severity: 'blocker', message: e.message }] });
+  }
+}
+
+const allOk = results.every(auditOk);
+
+if (json) {
+  console.log(JSON.stringify({ action, branch, tool, ok: allOk, results }, null, 2));
+} else {
+  for (const r of results) {
+    console.log(`  ${auditOk(r) ? C.green('OK  ') : C.red('FAIL')} ${r.repo.padEnd(22)} ${C.dim(branch)}  ${auditSummary(r)}`);
+    for (const f of r.findings) {
+      const paint = f.severity === 'blocker' ? C.red : C.yellow;
+      console.log(`         ${paint(f.severity.padEnd(8))} ${C.dim(f.message)}`);
+    }
+  }
+  console.log();
+  console.log(allOk
+    ? `  ${C.green('every branch is gated')}`
+    : `  ${C.red('an ungated branch means a pull request can merge with no approved spec')}`);
+  printTranscript(transport, C);
+}
+
+process.exit(allOk ? 0 : 1);

package/ml-specs/scripts/fix-specs.mjs

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+// Repair spec hygiene in a repo that has been using specs/ for a while.
+// Pure Node, no dependencies. Runs entirely on your machine — no network calls.
+//
+//   node fix-specs.mjs --root /path/to/repo              # dry run: prints the plan, writes nothing
+//   node fix-specs.mjs --root /path/to/repo --apply      # actually does it
+//
+// Two repairs, both opt-outable (--no-numbering / --no-status):
+//
+//   NUMBERING  Two specs sharing a number is a filename collision — git merges those badly.
+//              The later-created file is renumbered to the next free number, across ALL
+//              branches, and references to its old filename are rewritten.
+//
+//   STATUS     A Status cell holding prose ("Implemented — all 16 ACs met, gate green…")
+//              is real information in the wrong field: /spec-advance, /repo-status, and the
+//              MCP spec_list tool all read Status as one word. The lifecycle word moves into
+//              Status; the prose is PRESERVED verbatim as a note under the header table.
+//              Nothing is ever deleted.
+//
+// Idempotent: running it twice changes nothing the second time.
+
+import { readFileSync, writeFileSync, existsSync, readdirSync, renameSync, statSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { resolveStatus } from './lib/specs.mjs';
+
+const args = process.argv.slice(2);
+const flag = (n) => { const i = args.indexOf(n); return i === -1 ? null : args[i + 1]; };
+const ROOT = flag('--root') || process.cwd();
+const APPLY = args.includes('--apply');
+const FORCE = args.includes('--force');
+const DO_NUMBERING = !args.includes('--no-numbering');
+const DO_STATUS = !args.includes('--no-status');
+
+const LIFECYCLE = ['Draft', 'Approved', 'Implemented', 'Verified', 'Archived'];
+// A spec id is digits plus an OPTIONAL letter: 0165 and 0165b are different specs, not a clash.
+const SPEC_FILE = /^(\d{4}[a-z]?)-(.+)\.md$/;
+
+const abs = (p) => join(ROOT, p);
+const git = (...a) => {
+  try {
+    return execFileSync('git', ['-C', ROOT, ...a], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch {
+    return '';
+  }
+};
+const isRepo = git('rev-parse', '--is-inside-work-tree') === 'true';
+
+// --- collect specs ----------------------------------------------------------
+
+function collect() {
+  const out = [];
+  for (const dir of ['specs', 'specs/archive']) {
+    if (!existsSync(abs(dir))) continue;
+    for (const f of readdirSync(abs(dir))) {
+      const m = f.match(SPEC_FILE);
+      if (!m) continue;
+      out.push({ dir, file: `${dir}/${f}`, name: f, id: m[1], slug: m[2] });
+    }
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function addedAt(file) {
+  if (isRepo) {
+    const t = git('log', '--diff-filter=A', '--format=%at', '-1', '--', file);
+    if (t) return Number(t);
+  }
+  try { return Math.floor(statSync(abs(file)).mtimeMs / 1000); } catch { return 0; }
+}
+
+// Highest number in use anywhere — working tree plus every branch's history, so a renumber
+// can't land on an id that exists only on a branch nobody has checked out.
+function highestUsed(specs) {
+  let max = 0;
+  const consider = (name) => {
+    const m = basename(name).match(/^(\d{4})/);
+    if (m) max = Math.max(max, Number(m[1]));
+  };
+  specs.forEach((s) => consider(s.name));
+  if (isRepo) {
+    git('log', '--all', '--pretty=format:', '--name-only', '--diff-filter=A', '--', 'specs/[0-9]*')
+      .split('\n').filter(Boolean).forEach(consider);
+  }
+  return max;
+}
+
+// --- repair 1: duplicate numbers -------------------------------------------
+
+function planNumbering(specs) {
+  const byId = new Map();
+  for (const s of specs) {
+    if (!byId.has(s.id)) byId.set(s.id, []);
+    byId.get(s.id).push(s);
+  }
+
+  let next = highestUsed(specs);
+  const renames = [];
+  for (const [id, group] of byId) {
+    if (group.length < 2) continue;
+    // Keep the original; renumber everything created after it.
+    const dated = group.map((s) => ({ ...s, at: addedAt(s.file) })).sort((a, b) => a.at - b.at);
+    for (const later of dated.slice(1)) {
+      next += 1;
+      const id2 = String(next).padStart(4, '0');
+      renames.push({
+        from: later.file,
+        to: `${later.dir}/${id2}-${later.slug}.md`,
+        oldId: id,
+        newId: id2,
+        addedAt: later.at ? new Date(later.at * 1000).toISOString().slice(0, 10) : 'unknown',
+        keeping: dated[0].file,
+      });
+    }
+  }
+  return renames;
+}
+
+// Files that might mention a renamed spec by filename. Deliberately narrow: specs, docs,
+// and top-level markdown. An exact-filename rewrite is safe; guessing at prose is not.
+function referenceCandidates() {
+  const out = [];
+  const walk = (dir, depth) => {
+    if (!existsSync(abs(dir)) || depth > 3) return;
+    for (const f of readdirSync(abs(dir))) {
+      const rel = `${dir}/${f}`;
+      let st;
+      try { st = statSync(abs(rel)); } catch { continue; }
+      if (st.isDirectory()) walk(rel, depth + 1);
+      else if (f.endsWith('.md')) out.push(rel);
+    }
+  };
+  walk('specs', 0);
+  walk('docs', 0);
+  if (existsSync(abs('CLAUDE.md'))) out.push('CLAUDE.md');
+  if (existsSync(abs('README.md'))) out.push('README.md');
+  return [...new Set(out)];
+}
+
+// --- repair 2: status normalization ----------------------------------------
+
+const STATUS_ROW = /^\|\s*\*\*Status\*\*\s*\|/;
+
+function planStatus(specs) {
+  const changes = [];
+  const skipped = [];
+
+  for (const s of specs) {
+    const text = readFileSync(abs(s.file), 'utf8');
+    const lines = text.split('\n');
+    const i = lines.findIndex((l) => STATUS_ROW.test(l));
+    if (i === -1) continue;
+
+    const line = lines[i];
+    // Take everything between the cell delimiter and the LAST pipe: the prose itself often
+    // contains pipes, and truncating at the first one would silently eat content.
+    const start = line.indexOf('|', line.indexOf('**Status**')) + 1;
+    const end = line.lastIndexOf('|');
+    if (start <= 0 || end <= start) continue;
+
+    const raw = line.slice(start, end).trim();
+    const plain = raw.replace(/\*\*/g, '').replace(/`/g, '').trim();
+    if (LIFECYCLE.includes(plain)) continue;               // already canonical
+    if (/^Draft \\?\| Approved/.test(plain)) continue;      // untouched TEMPLATE placeholder
+
+    const r = resolveStatus(plain);
+    if (!r.status) {
+      skipped.push({ file: s.file, raw, why: 'no lifecycle word at all' });
+      continue;
+    }
+    // The word must LEAD the cell. "Implemented (2026-07-07) — …" is an author declaring a
+    // status; a stage word buried mid-sentence is narration, and promoting it writes a claim
+    // they never made. This is not about ambiguity — one buried word is just as much a guess
+    // as three, and this script rewrites files.
+    if (!r.leading) {
+      skipped.push({
+        file: s.file,
+        raw,
+        why: r.candidates.length > 1
+          ? `mentions ${r.candidates.join(', ')} mid-text, none leading`
+          : `"${r.status}" appears mid-text, not as the status`,
+      });
+      continue;
+    }
+    if (text.includes('> **Status note:**')) continue;      // already normalized
+
+    changes.push({ file: s.file, from: raw, to: r.status, lineIndex: i });
+  }
+  return { changes, skipped };
+}
+
+function applyStatus(change) {
+  const lines = readFileSync(abs(change.file), 'utf8').split('\n');
+  const i = change.lineIndex;
+  const line = lines[i];
+  const start = line.indexOf('|', line.indexOf('**Status**')) + 1;
+  const end = line.lastIndexOf('|');
+  lines[i] = `${line.slice(0, start)} ${change.to} ${line.slice(end)}`;
+
+  // Insert the preserved prose immediately after the header table block.
+  let j = i;
+  while (j + 1 < lines.length && lines[j + 1].trimStart().startsWith('|')) j++;
+  lines.splice(j + 1, 0, '', `> **Status note:** ${change.from}`);
+
+  writeFileSync(abs(change.file), lines.join('\n'));
+}
+
+// --- run --------------------------------------------------------------------
+
+const specs = collect();
+if (specs.length === 0) {
+  console.log(`No specs found under ${ROOT}/specs — nothing to do.`);
+  process.exit(0);
+}
+
+if (APPLY && isRepo && !FORCE) {
+  const dirty = git('status', '--porcelain', '--', 'specs', 'docs').split('\n').filter(Boolean);
+  if (dirty.length) {
+    console.error('Refusing to --apply with uncommitted changes under specs/ or docs/.');
+    console.error('Commit or stash first so this script\'s changes are reviewable on their own,');
+    console.error('or pass --force if you know what you are doing.');
+    process.exit(1);
+  }
+}
+
+const renames = DO_NUMBERING ? planNumbering(specs) : [];
+const { changes, skipped } = DO_STATUS ? planStatus(specs) : { changes: [], skipped: [] };
+
+console.log(`repo: ${ROOT}`);
+console.log(`specs: ${specs.length}${isRepo ? '' : '   (not a git repo — using file mtimes, local branches unchecked)'}`);
+console.log(APPLY ? '\nMODE: APPLY — writing changes\n' : '\nMODE: DRY RUN — nothing will be written (pass --apply to do it)\n');
+
+// 1. numbering
+if (DO_NUMBERING) {
+  console.log(`── duplicate spec numbers: ${renames.length} file(s) to renumber`);
+  const candidates = renames.length ? referenceCandidates() : [];
+  for (const r of renames) {
+    console.log(`   ${r.from}`);
+    console.log(`     → ${r.to}     (added ${r.addedAt}; keeping ${basename(r.keeping)} on ${r.oldId})`);
+
+    const refs = candidates.filter((c) => {
+      if (c === r.from) return false;
+      try { return readFileSync(abs(c), 'utf8').includes(basename(r.from)); } catch { return false; }
+    });
+    if (refs.length) console.log(`     ${refs.length} file(s) reference the old filename and will be updated`);
+
+    if (APPLY) {
+      const tracked = isRepo && git('ls-files', '--', r.from) !== '';
+      if (tracked) git('mv', r.from, r.to);
+      else renameSync(abs(r.from), abs(r.to));
+      for (const c of refs) {
+        const t = readFileSync(abs(c), 'utf8');
+        writeFileSync(abs(c), t.split(basename(r.from)).join(basename(r.to)));
+      }
+    }
+  }
+  if (renames.length) {
+    console.log('   NOTE: only exact filename references are rewritten. Prose like "see spec 0043"');
+    console.log('         is left alone — search for the old number by hand if you use that style.');
+  }
+}
+
+// 2. status
+if (DO_STATUS) {
+  console.log(`\n── non-canonical Status values: ${changes.length} file(s)`);
+  for (const c of changes.slice(0, 8)) {
+    const preview = c.from.length > 88 ? c.from.slice(0, 88) + '…' : c.from;
+    console.log(`   ${c.file}`);
+    console.log(`     "${preview}"`);
+    console.log(`     → Status: ${c.to}   (full text preserved as a "Status note" under the table)`);
+  }
+  if (changes.length > 8) console.log(`   … and ${changes.length - 8} more`);
+  if (APPLY) changes.forEach(applyStatus);
+}
+
+if (skipped.length) {
+  console.log(`\n── needs a human: ${skipped.length} file(s) left untouched`);
+  for (const s of skipped.slice(0, 10)) {
+    console.log(`   ${s.file}  (${s.why})`);
+    console.log(`      "${s.raw.length > 70 ? s.raw.slice(0, 70) + '…' : s.raw}"`);
+  }
+  if (skipped.length > 10) console.log(`   … and ${skipped.length - 10} more`);
+}
+
+console.log(
+  APPLY
+    ? `\n✓ applied: ${renames.length} renumbered, ${changes.length} statuses normalized. Review with \`git diff\` / \`git status\` — nothing was committed.`
+    : `\nDry run complete: would renumber ${renames.length}, normalize ${changes.length}. Re-run with --apply to write.`,
+);

package/ml-specs/scripts/lib/cli.mjs

@@ -0,0 +1,43 @@
+// Argument and environment handling shared by the scripts that talk to a tracker
+// or a source-control host. One implementation, so --dry-run and --root behave
+// identically everywhere.
+import { recorder, request } from './http.mjs';
+
+export function args(argv = process.argv.slice(2)) {
+  const flag = (n, d = null) => { const i = argv.indexOf(`--${n}`); return i === -1 ? d : (argv[i + 1] ?? d); };
+  const has = (n) => argv.includes(`--${n}`);
+  const positional = argv.filter((a, i) => !a.startsWith('--') && !String(argv[i - 1] ?? '').startsWith('--'));
+  return { argv, flag, has, positional, root: flag('root', process.cwd()), json: has('json'), dryRun: has('dry-run') };
+}
+
+export const colours = (enabled) => enabled
+  ? { dim: (s) => `\x1b[2m${s}\x1b[0m`, red: (s) => `\x1b[31m${s}\x1b[0m`, green: (s) => `\x1b[32m${s}\x1b[0m`,
+      yellow: (s) => `\x1b[33m${s}\x1b[0m`, bold: (s) => `\x1b[1m${s}\x1b[0m` }
+  : { dim: (s) => s, red: (s) => s, green: (s) => s, yellow: (s) => s, bold: (s) => s };
+
+/** A recording transport for --dry-run, the real one otherwise. */
+export const transportFor = (dryRun) => (dryRun ? recorder() : request);
+
+export const env = (name, fallback = '') => process.env[name] ?? fallback;
+
+/** Credentials are read from the environment, never from a file in the repo. */
+export function trackerConfig(transport) {
+  const tool = env('SDD_PM_TOOL', 'ado');
+  return tool === 'jira'
+    ? { tool, config: { baseUrl: env('JIRA_BASE_URL'), email: env('JIRA_EMAIL'),
+                        apiToken: env('JIRA_API_TOKEN'), projectKey: env('JIRA_PROJECT_KEY', 'PAY'), transport } }
+    : { tool, config: { org: env('ADO_ORG'), project: env('ADO_PROJECT'), pat: env('ADO_PAT'), transport } };
+}
+
+export function scmConfig(transport) {
+  const tool = env('SDD_SCM_TOOL', 'ado-repos');
+  return tool === 'github'
+    ? { tool, config: { owner: env('GITHUB_OWNER'), token: env('GITHUB_TOKEN'), transport } }
+    : { tool, config: { org: env('ADO_ORG'), project: env('ADO_PROJECT'), pat: env('ADO_PAT'), transport } };
+}
+
+export function printTranscript(transport, C) {
+  if (!transport.calls) return;
+  console.log(`\n${C.bold(`requests that would be sent (${transport.calls.length})`)}\n`);
+  console.log(transport.transcript());
+}