@mlmcps/ml-specs 1.0.0

package/ml-specs/scripts/lib/policy.test.mjs

@@ -0,0 +1,139 @@
+// Each test here is a way a gate stops being a gate without anything visibly
+// breaking — which is exactly how this kind of governance dies.
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { recorder } from './http.mjs';
+import { adoPolicy, githubPolicy, auditOk, auditSummary, BUILD_VALIDATION_TYPE } from './policy.mjs';
+
+const ADO = { org: 'contoso', project: 'Payments', pat: 'pat' };
+const GH = { owner: 'motivity', token: 'ghp_x' };
+
+const policy = (over = {}, settings = {}) => ({
+  type: { id: BUILD_VALIDATION_TYPE }, isEnabled: true, isBlocking: true,
+  settings: { buildDefinitionId: 42, manualQueueOnly: false, queueOnSourceUpdateOnly: true, ...settings },
+  ...over,
+});
+const audit = (value) => adoPolicy({ ...ADO, transport: recorder([{ value }]) }).audit('api-neelias', 'main');
+
+describe('Azure DevOps audit', () => {
+  test('a healthy policy passes with no findings', async () => {
+    const a = await audit([policy()]);
+    assert.ok(auditOk(a));
+    assert.deepEqual(a.findings, []);
+    assert.match(auditSummary(a), /present and blocking/);
+  });
+
+  test('no policy at all', async () => {
+    const a = await audit([]);
+    assert.equal(a.present, false);
+    assert.ok(!auditOk(a));
+    assert.match(auditSummary(a), /no spec gate/);
+  });
+
+  test('a policy of another type is not a spec gate', async () => {
+    // A minimum-reviewers policy is not this.
+    const a = await audit([{ type: { id: 'fa4e907d-c16b-4a4c-9dfa-4906e5d171dd' }, isEnabled: true, isBlocking: true }]);
+    assert.equal(a.present, false);
+  });
+
+  test('an advisory policy is reported as not a gate', async () => {
+    // The silent failure: it runs, it reports, it cannot block.
+    const a = await audit([policy({ isBlocking: false })]);
+    assert.equal(a.present, true);
+    assert.equal(a.blocking, false);
+    assert.ok(!auditOk(a));
+    assert.match(auditSummary(a), /ADVISORY/);
+    assert.match(a.findings.map((f) => f.message).join(' '), /cannot fail the merge/);
+  });
+
+  test('a disabled policy is a blocker', async () => {
+    const a = await audit([policy({ isEnabled: false })]);
+    assert.ok(!auditOk(a));
+    assert.match(a.findings.map((f) => f.message).join(' '), /disabled/);
+  });
+
+  test('manualQueueOnly is a blocker — a gate that runs only when someone remembers', async () => {
+    const a = await audit([policy({}, { manualQueueOnly: true })]);
+    assert.ok(!auditOk(a));
+    assert.match(a.findings.map((f) => f.message).join(' '), /only runs if someone remembers/);
+  });
+
+  test('not re-running on push is a warning, not a blocker', async () => {
+    const a = await audit([policy({}, { queueOnSourceUpdateOnly: false })]);
+    assert.ok(auditOk(a));
+    assert.deepEqual(a.findings.map((f) => f.severity), ['warning']);
+    assert.match(a.findings[0].message, /later push is ungated/);
+  });
+
+  test('several build policies are ambiguous', async () => {
+    const a = await audit([policy(), policy()]);
+    assert.ok(auditOk(a));
+    assert.match(a.findings.map((f) => f.message).join(' '), /which one is the gate/);
+  });
+
+  test('the audit queries the specific branch and repo', async () => {
+    const t = recorder([{ value: [] }]);
+    await adoPolicy({ ...ADO, transport: t }).audit('api-neelias', 'release/24');
+    assert.match(t.last().url, /refName=refs\/heads\/release\/24/);
+    assert.match(t.last().url, /repositoryId=api-neelias/);
+  });
+});
+
+describe('Azure DevOps install', () => {
+  test('install always sets blocking — there is no flag to turn it off', async () => {
+    const t = recorder();
+    await adoPolicy({ ...ADO, transport: t }).install('api-neelias', 'main', '42');
+    assert.equal(t.last().body.isBlocking, true);
+    assert.equal(t.last().body.isEnabled, true);
+    assert.equal(t.last().body.type.id, BUILD_VALIDATION_TYPE);
+  });
+
+  test('it scopes to the exact branch and repo', async () => {
+    const t = recorder();
+    await adoPolicy({ ...ADO, transport: t }).install('api-neelias', 'main', '42');
+    const scope = t.last().body.settings.scope[0];
+    assert.equal(scope.refName, 'refs/heads/main');
+    assert.equal(scope.matchKind, 'Exact');
+    assert.equal(scope.repositoryId, 'api-neelias');
+  });
+
+  test('a numeric build id is sent as a number', async () => {
+    const t = recorder();
+    await adoPolicy({ ...ADO, transport: t }).install('api-neelias', 'main', '42');
+    assert.equal(t.last().body.settings.buildDefinitionId, 42);
+  });
+});
+
+describe('GitHub', () => {
+  const gh = (raw) => githubPolicy({ ...GH, transport: recorder([raw]) }).audit('api-neelias', 'main');
+
+  test('healthy protection passes', async () => {
+    const a = await gh({ required_status_checks: { strict: true, contexts: ['sdd-spec-gate'] }, enforce_admins: { enabled: true } });
+    assert.ok(auditOk(a));
+  });
+
+  test('no required check means no gate', async () => {
+    const a = await gh({ required_status_checks: { strict: true, contexts: [] } });
+    assert.equal(a.present, false);
+  });
+
+  test('an admin bypass is GitHub\'s version of an advisory gate', async () => {
+    const a = await gh({ required_status_checks: { strict: true, contexts: ['g'] }, enforce_admins: { enabled: false } });
+    assert.ok(!auditOk(a));
+    assert.match(a.findings.map((f) => f.message).join(' '), /administrators can merge past the gate/);
+  });
+
+  test('non-strict is a warning', async () => {
+    const a = await gh({ required_status_checks: { strict: false, contexts: ['g'] }, enforce_admins: { enabled: true } });
+    assert.ok(auditOk(a));
+    assert.deepEqual(a.findings.map((f) => f.severity), ['warning']);
+  });
+
+  test('install requires the check and enforces admins', async () => {
+    const t = recorder();
+    await githubPolicy({ ...GH, transport: t }).install('api-neelias', 'main', 'sdd-spec-gate');
+    assert.equal(t.last().method, 'PUT');
+    assert.deepEqual(t.last().body.required_status_checks.contexts, ['sdd-spec-gate']);
+    assert.equal(t.last().body.enforce_admins, true);
+  });
+});

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

@@ -0,0 +1,189 @@
+// Source control: branches and pull requests, for ADO Repos and GitHub.
+//
+// Deliberately separate from lib/tracker.mjs. A work item and a pull request are
+// different objects owned by different systems, and they diverge under exactly
+// the load this exists for: one spec fans out to N repositories but links to ONE
+// work item, so the cardinality differs. GitHub-plus-Jira is also an ordinary
+// combination that a merged interface could not express.
+//
+// GitHub ships alongside ADO because these customers migrate there for code
+// while keeping Boards or Jira for work — the two boundaries move independently.
+//
+// Pure Node, no dependencies. Every call goes through an injected transport.
+
+import { basicAuth, request } from './http.mjs';
+import { branchName, prTitle, keyFrom, specId, testCaseId } from './trace.mjs';
+
+const EMPTY_SHA = '0'.repeat(40);
+
+// --- Azure DevOps Repos ------------------------------------------------------
+
+export function adoRepos({ org, project, pat, apiVersion = '7.1', transport = request }) {
+  const repoBase = (repo) =>
+    `https://dev.azure.com/${org}/${encodeURIComponent(project)}/_apis/git/repositories/${encodeURIComponent(repo)}`;
+  const headers = { Authorization: basicAuth('', pat) };
+
+  return {
+    tool: 'ado-repos',
+
+    async defaultBranchSha(repo, branch = 'main') {
+      const res = await transport(`${repoBase(repo)}/refs?filter=heads/${branch}&api-version=${apiVersion}`, { headers });
+      const refs = res.value ?? [];
+      if (!refs.length) throw new Error(`ADO: ${repo} has no branch ${branch}`);
+      return String(refs[0].objectId);
+    },
+
+    async createBranch(repo, name, fromSha) {
+      // ADO has no "create branch" call — a branch is a ref updated from zeros.
+      await transport(`${repoBase(repo)}/refs?api-version=${apiVersion}`, {
+        method: 'POST', headers,
+        body: [{ name: `refs/heads/${name}`, oldObjectId: EMPTY_SHA, newObjectId: fromSha }],
+      });
+      return { repo, name, sha: fromSha };
+    },
+
+    async openPullRequest(repo, { source, target, title, body }) {
+      const raw = await transport(`${repoBase(repo)}/pullrequests?api-version=${apiVersion}`, {
+        method: 'POST', headers,
+        body: { sourceRefName: `refs/heads/${source}`, targetRefName: `refs/heads/${target}`,
+                title, description: body },
+      });
+      const id = String(raw.pullRequestId ?? '');
+      return { repo, id, title, source, target,
+               url: `https://dev.azure.com/${org}/${encodeURIComponent(project)}/_git/${encodeURIComponent(repo)}/pullrequest/${id}` };
+    },
+
+    async findPullRequests(repo, key) {
+      const res = await transport(
+        `${repoBase(repo)}/pullrequests?searchCriteria.status=all&api-version=${apiVersion}`, { headers });
+      return (res.value ?? [])
+        .filter((pr) => keyFrom('prTitle', pr.title ?? '') === key)
+        .map((pr) => ({ repo, id: String(pr.pullRequestId), title: pr.title,
+          source: String(pr.sourceRefName ?? '').replace(/^refs\/heads\//, ''),
+          target: String(pr.targetRefName ?? '').replace(/^refs\/heads\//, ''),
+          url: `https://dev.azure.com/${org}/_git/${encodeURIComponent(repo)}/pullrequest/${pr.pullRequestId}` }));
+    },
+  };
+}
+
+// --- GitHub ------------------------------------------------------------------
+
+export function github({ owner, token, apiBase = 'https://api.github.com', transport = request }) {
+  const headers = { Authorization: `Bearer ${token}`, 'X-GitHub-Api-Version': '2022-11-28' };
+  const url = (repo, path) => `${apiBase}/repos/${owner}/${repo}${path}`;
+
+  return {
+    tool: 'github',
+
+    async defaultBranchSha(repo, branch = 'main') {
+      const raw = await transport(url(repo, `/git/ref/heads/${branch}`), { headers });
+      return String(raw.object.sha);
+    },
+
+    async createBranch(repo, name, fromSha) {
+      await transport(url(repo, '/git/refs'), {
+        method: 'POST', headers, body: { ref: `refs/heads/${name}`, sha: fromSha } });
+      return { repo, name, sha: fromSha };
+    },
+
+    async openPullRequest(repo, { source, target, title, body }) {
+      // The shape difference from ADO: bare head/base, and it is called `body`.
+      const raw = await transport(url(repo, '/pulls'), {
+        method: 'POST', headers, body: { title, head: source, base: target, body } });
+      return { repo, id: String(raw.number ?? ''), title, source, target,
+               url: String(raw.html_url ?? `https://github.com/${owner}/${repo}/pulls`) };
+    },
+
+    async findPullRequests(repo, key) {
+      const raw = await transport(url(repo, '/pulls?state=all&per_page=100'), { headers });
+      return (raw ?? [])
+        .filter((pr) => keyFrom('prTitle', pr.title ?? '') === key)
+        .map((pr) => ({ repo, id: String(pr.number), title: pr.title,
+          source: pr.head?.ref ?? '', target: pr.base?.ref ?? '', url: pr.html_url ?? '' }));
+    },
+  };
+}
+
+// --- the governed path -------------------------------------------------------
+
+/** Reads only. Frozen, so the write methods are absent and stay absent. */
+export const readOnlyScm = (scm) => Object.freeze({
+  tool: scm.tool,
+  defaultBranchSha: (repo, branch) => scm.defaultBranchSha(repo, branch),
+  findPullRequests: (repo, key) => scm.findPullRequests(repo, key),
+});
+
+/**
+ * The only way a branch or pull request gets created. A pull request that cannot
+ * be traced back to an approved contract is exactly what this exists to prevent,
+ * so it is refused here rather than reported later.
+ */
+export function governedScm(scm, { target = 'main' } = {}) {
+  return {
+    tool: scm.tool,
+    async openFor(spec, repo, body) {
+      if (!spec.status || spec.status === 'Draft') {
+        throw new Error(`spec ${spec.id} is ${spec.status ?? 'unknown'}; no branch is cut before the approval gate`);
+      }
+      const name = spec.branch ?? branchName(spec.id, spec.title);
+      const title = prTitle(spec.id, spec.title);
+      // Both are derived, so these can only fail if a derivation changed without
+      // its parser changing with it.
+      if (keyFrom('branch', name) !== spec.id) throw new Error(`branch "${name}" does not carry spec ${spec.id}`);
+      if (keyFrom('prTitle', title) !== spec.id) throw new Error(`title "${title}" does not carry spec ${spec.id}`);
+
+      const sha = await scm.defaultBranchSha(repo, target);
+      const branch = await scm.createBranch(repo, name, sha);
+      const pr = await scm.openPullRequest(repo, { source: name, target, title, body });
+      return { branch, pr };
+    },
+  };
+}
+
+/**
+ * The pull request body. It carries the whole chain so a reviewer never has to
+ * hunt, and the criteria arrive as a checklist — their job is to confirm each
+ * one, not to infer what the change was for.
+ */
+export function pullRequestBody(spec, reason, { constraints = [] } = {}) {
+  const branch = spec.branch ?? branchName(spec.id, spec.title);
+  const lines = [
+    `## ${specId(spec.id)} — ${spec.title}`, '',
+    `**Why this repo:** ${reason}`,
+    `**Spec:** \`${spec.file}\` (status: ${spec.status})`,
+  ];
+  if (spec.ticket) lines.push(`**Ticket:** ${spec.ticket}`);
+  if (spec.repos?.length) lines.push(`**Fan-out:** ${spec.repos.join(', ')}`);
+  if (spec.nfrs?.length) lines.push(`**NFRs in force:** ${spec.nfrs.join(', ')}`);
+
+  lines.push('', '## Acceptance criteria', '');
+  lines.push(...((spec.criteria ?? []).length
+    ? spec.criteria.map((ac) => `- [${ac.checked ? 'x' : ' '}] ${ac.id} (${testCaseId(spec.id, ac.ordinal)}) — ${ac.text}`)
+    : ['_none — this spec should not have been approved._']));
+
+  if (constraints.length) {
+    lines.push('', '## Constraints in force', '', ...constraints.map((c) => `- **${c.id}** — ${c.text}`));
+  }
+
+  lines.push('', '---',
+    `Every branch in this fan-out is \`${branch}\`. Same key, so these pull requests are one change.`);
+  return lines.join('\n');
+}
+
+/** Which repos this change reaches: those named on the spec, plus those the
+ *  estate index says consume what it touches. */
+export function fanOutTargets(spec, impact = null) {
+  const targets = new Map();
+  for (const repo of spec.repos ?? []) targets.set(repo, 'named on the spec');
+  for (const d of impact?.directlyAffected ?? []) {
+    if (!targets.has(d.repo)) targets.set(d.repo, `consumes ${d.via.join(', ')}`);
+  }
+  for (const t of impact?.transitivelyAffected ?? []) {
+    if (!targets.has(t.repo)) targets.set(t.repo, `one hop: consumes ${t.via.join(', ')}`);
+  }
+  return [...targets].map(([repo, reason]) => ({
+    repo, reason,
+    branch: spec.branch ?? branchName(spec.id, spec.title),
+    title: prTitle(spec.id, spec.title),
+  }));
+}

package/ml-specs/scripts/lib/scm.test.mjs

@@ -0,0 +1,155 @@
+// Contract tests for source control, and for the fan-out guarantee.
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { recorder } from './http.mjs';
+import { adoRepos, github, governedScm, readOnlyScm, pullRequestBody, fanOutTargets } from './scm.mjs';
+import { parseEstate, impactOf } from './estate.mjs';
+
+const ADO = { org: 'contoso', project: 'Payments Core', pat: 's3cret' };
+const GH = { owner: 'motivity', token: 'ghp_x' };
+const SPEC = {
+  id: '0031', title: 'Idempotent refund submission', file: 'specs/0031-x.md', status: 'Approved',
+  ticket: 'PAY-2204', repos: ['api-neelias'], nfrs: ['NFR-03'], branch: null,
+  criteria: [{ id: 'AC-1', ordinal: 1, text: 'replay returns the original', checked: false }],
+};
+
+describe('Azure DevOps Repos', () => {
+  test('a branch is a ref updated from the empty object id', async () => {
+    // ADO has no "create branch" call.
+    const t = recorder();
+    await adoRepos({ ...ADO, transport: t }).createBranch('api-neelias', 'feat/0031-x', 'abc123');
+    const row = t.last().body[0];
+    assert.equal(row.name, 'refs/heads/feat/0031-x');
+    assert.equal(row.oldObjectId, '0'.repeat(40));
+    assert.equal(row.newObjectId, 'abc123');
+  });
+
+  test('a pull request uses fully qualified ref names and calls the text description', async () => {
+    const t = recorder();
+    await adoRepos({ ...ADO, transport: t })
+      .openPullRequest('api-neelias', { source: 'feat/0031-x', target: 'main', title: '[SPEC-0031] x', body: 'b' });
+    assert.equal(t.last().body.sourceRefName, 'refs/heads/feat/0031-x');
+    assert.equal(t.last().body.targetRefName, 'refs/heads/main');
+    assert.equal(t.last().body.description, 'b');
+    assert.match(t.last().url, /\/Payments%20Core\/_apis\/git\/repositories\/api-neelias\/pullrequests/);
+  });
+
+  test('a missing default branch is an error, not a silent zero sha', async () => {
+    const t = recorder([{ value: [] }]);
+    await assert.rejects(() => adoRepos({ ...ADO, transport: t }).defaultBranchSha('api-neelias'), /no branch main/);
+  });
+
+  test('pull request search filters on the key and strips the ref prefix', async () => {
+    const t = recorder([{ value: [
+      { pullRequestId: 1, title: '[SPEC-0031] yes', sourceRefName: 'refs/heads/feat/0031-x', targetRefName: 'refs/heads/main' },
+      { pullRequestId: 2, title: 'unrelated hotfix', sourceRefName: 'refs/heads/hf', targetRefName: 'refs/heads/main' },
+    ] }]);
+    const found = await adoRepos({ ...ADO, transport: t }).findPullRequests('api-neelias', '0031');
+    assert.deepEqual(found.map((p) => p.id), ['1']);
+    assert.equal(found[0].source, 'feat/0031-x');
+  });
+});
+
+describe('GitHub', () => {
+  test('auth is a bearer token with a pinned api version', async () => {
+    const t = recorder();
+    await github({ ...GH, transport: t }).defaultBranchSha('api-neelias');
+    // headers are not recorded; assert the call shape instead
+    assert.match(t.last().url, /\/repos\/motivity\/api-neelias\/git\/ref\/heads\/main$/);
+  });
+
+  test('a pull request uses bare head and base, and calls the text body', async () => {
+    // The shape difference from ADO that a single-adapter design would have missed.
+    const t = recorder();
+    await github({ ...GH, transport: t })
+      .openPullRequest('api-neelias', { source: 'feat/0031-x', target: 'main', title: '[SPEC-0031] x', body: 'b' });
+    assert.equal(t.last().body.head, 'feat/0031-x');    // not refs/heads/
+    assert.equal(t.last().body.base, 'main');
+    assert.equal(t.last().body.body, 'b');
+  });
+
+  test('a branch posts a ref', async () => {
+    const t = recorder();
+    await github({ ...GH, transport: t }).createBranch('api-neelias', 'feat/0031-x', 'abc123');
+    assert.deepEqual(t.last().body, { ref: 'refs/heads/feat/0031-x', sha: 'abc123' });
+  });
+});
+
+describe('the governed path', () => {
+  test('no branch is cut before the approval gate', async () => {
+    const scm = governedScm(adoRepos({ ...ADO, transport: recorder() }));
+    await assert.rejects(() => scm.openFor({ ...SPEC, status: 'Draft' }, 'api-neelias', 'b'),
+      /before the approval gate/);
+  });
+
+  test('an approved spec produces a derived branch and title', async () => {
+    const { branch, pr } = await governedScm(adoRepos({ ...ADO, transport: recorder() }))
+      .openFor(SPEC, 'api-neelias', 'b');
+    assert.equal(branch.name, 'feat/0031-idempotent-refund-submission');
+    assert.equal(pr.title, '[SPEC-0031] Idempotent refund submission');
+  });
+
+  test('a branch that lost the key is refused before anything is created', async () => {
+    const t = recorder();
+    await assert.rejects(
+      () => governedScm(adoRepos({ ...ADO, transport: t })).openFor({ ...SPEC, branch: 'hotfix-urgent' }, 'r', 'b'),
+      /does not carry spec 0031/);
+    assert.equal(t.calls.length, 0);   // nothing was sent
+  });
+
+  test('a reader has no write methods and they cannot be re-attached', () => {
+    const r = readOnlyScm(adoRepos({ ...ADO, transport: recorder() }));
+    assert.equal(r.createBranch, undefined);
+    assert.equal(r.openPullRequest, undefined);
+    assert.throws(() => { 'use strict'; r.createBranch = () => {}; });
+  });
+});
+
+describe('fan-out', () => {
+  const INDEX = parseEstate(`
+| Service | Owns | Stack | Summary doc |
+|---|---|---|---|
+| api-neelias | payments | Node | x |
+
+| Event / queue / topic | Producer | Consumer | Notes | Evidence |
+|---|---|---|---|---|
+| \`payment.captured\` | api-neelias | neelias-pos (\`SaleReconciler\`) | n | e |
+| \`pos.sale.completed\` | neelias-pos | neelias-cms-portal (\`SalesFeed\`) | n | e |
+`);
+
+  test('every target shares one branch name, so N pull requests are one change', () => {
+    const targets = fanOutTargets(SPEC, impactOf(INDEX, ['payment.captured']));
+    assert.deepEqual(targets.map((t) => t.repo), ['api-neelias', 'neelias-pos', 'neelias-cms-portal']);
+    assert.equal(new Set(targets.map((t) => t.branch)).size, 1);
+    assert.match(targets[2].reason, /one hop/);
+  });
+
+  test('a repo named on the spec is not duplicated by the impact query', () => {
+    const targets = fanOutTargets({ ...SPEC, repos: ['neelias-pos'] }, impactOf(INDEX, ['payment.captured']));
+    assert.equal(targets.filter((t) => t.repo === 'neelias-pos').length, 1);
+    assert.equal(targets[0].reason, 'named on the spec');
+  });
+});
+
+describe('the pull request body', () => {
+  test('carries the whole chain so a reviewer never has to hunt', () => {
+    const body = pullRequestBody(SPEC, 'consumes payment.captured',
+      { constraints: [{ id: 'INC-4412', text: 'Holds released early.' }] });
+    assert.match(body, /SPEC-0031/);
+    assert.match(body, /\*\*Why this repo:\*\* consumes payment\.captured/);
+    assert.match(body, /\*\*Ticket:\*\* PAY-2204/);
+    assert.match(body, /INC-4412/);
+  });
+
+  test('criteria arrive as a reviewer checklist paired with their test cases', () => {
+    assert.match(pullRequestBody(SPEC, 'x'), /- \[ \] AC-1 \(TC-0031\.1\) — replay returns the original/);
+  });
+
+  test('it states why these pull requests are one change', () => {
+    assert.match(pullRequestBody(SPEC, 'x'), /Same key, so these pull requests are one change/);
+  });
+
+  test('a spec with no criteria says so rather than rendering an empty list', () => {
+    assert.match(pullRequestBody({ ...SPEC, criteria: [] }, 'x'), /should not have been approved/);
+  });
+});

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

@@ -0,0 +1,192 @@
+// Shared spec parsing. Imported by the MCP server (mcp/ml-specs-server.mjs) and the dashboard
+// generator (scripts/spec-dashboard.mjs) so there is exactly one implementation of "what is
+// a spec and what does it say" — two copies of this would have drifted within a release.
+//
+// Pure Node, no dependencies. Read-only.
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const LIFECYCLE = ['Draft', 'Approved', 'Implemented', 'Verified', 'Archived'];
+
+// `- [ ] **AC1** — text`, and the plainer `- [ ] AC-1: text`. Both appear in the
+// wild: the template writes the first, people hand-write the second.
+const AC_LINE = /^\s*-\s*\[([ xX])\]\s*(?:\*\*)?AC-?(\d+)(?:\*\*)?\s*[—–:-]\s*(.+?)\s*$/gm;
+
+/** Acceptance criteria as structured rows, so a script can pair each with a test case. */
+export function parseCriteria(text) {
+  const out = [];
+  for (const m of text.matchAll(AC_LINE)) {
+    out.push({
+      id: `AC-${Number(m[2])}`,
+      ordinal: Number(m[2]),
+      text: m[3],
+      checked: m[1].toLowerCase() === 'x',
+    });
+  }
+  return out.sort((a, b) => a.ordinal - b.ordinal);
+}
+
+// Template placeholders must read as absent. `<repo or service name>` treated as
+// a real repo would fan a pull request out to a repository that does not exist.
+const PLACEHOLDER = /^(<.*>|_TBD_|—|-|n\/?a|none|tbd)$/i;
+
+/** A comma- or slash-separated header cell as a clean list. */
+export function splitCell(value) {
+  if (!value) return [];
+  return value
+    .split(/[,/]/)
+    .map((v) => v.replace(/[`*]/g, '').trim())
+    .filter((v) => v && !PLACEHOLDER.test(v));
+}
+
+// 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$/;
+
+/**
+ * Resolve a Status cell that holds prose down to one lifecycle word.
+ *
+ * Two rules, both learned the hard way:
+ *  1. Match by position in the TEXT, not position in the enum. Picking the first enum member
+ *     that appears anywhere means a status reading "Phase 1 ✓ … verified …" resolves to a stage
+ *     its author never claimed — and this feeds a script that rewrites files.
+ *  2. Trust the word only when it LEADS the cell. "Implemented (2026-07-07) — …long prose…" is
+ *     an author stating a status. A stage word buried mid-sentence is discussion, not a claim,
+ *     so when several appear and none leads, say ambiguous and let a human decide.
+ */
+export function resolveStatus(plain) {
+  const text = (plain ?? '').trim();
+  if (LIFECYCLE.includes(text)) {
+    return { status: text, canonical: true, leading: true, ambiguous: false, candidates: [text] };
+  }
+
+  const found = LIFECYCLE
+    .map((w) => ({ word: w, at: text.search(new RegExp(`\\b${w}\\b`, 'i')) }))
+    .filter((m) => m.at !== -1)
+    .sort((a, b) => a.at - b.at);
+
+  if (found.length === 0) {
+    return { status: null, canonical: false, leading: false, ambiguous: false, candidates: [] };
+  }
+
+  // "Leading" allows for markdown/whitespace the caller already stripped, plus a stray bullet.
+  const leading = found[0].at <= 2;
+  return {
+    status: found[0].word,
+    canonical: false,
+    leading,
+    ambiguous: found.length > 1 && !leading,
+    candidates: found.map((m) => m.word),
+  };
+}
+
+/** Every spec under specs/ and specs/archive/, sorted by id. */
+export function listSpecs(root = process.cwd()) {
+  const out = [];
+  for (const dir of ['specs', 'specs/archive']) {
+    const abs = join(root, dir);
+    if (!existsSync(abs)) continue;
+    for (const f of readdirSync(abs)) {
+      const m = f.match(SPEC_FILE);
+      if (!m) continue;
+      const text = readFileSync(join(abs, f), 'utf8');
+
+      // Header-table cells: take to the LAST pipe on the line — the prose people write in
+      // Status often contains pipes, and stopping at the first would silently truncate it.
+      const field = (name) => {
+        const line = text.split('\n').find((l) =>
+          new RegExp(`^\\|\\s*\\*\\*${name}\\*\\*\\s*\\|`, 'i').test(l));
+        if (!line) return null;
+        const start = line.indexOf('|', line.indexOf(`**${name}**`)) + 1;
+        const end = line.lastIndexOf('|');
+        if (start <= 0 || end <= start) return null;
+        const v = line.slice(start, end).trim();
+        return v === '' || v === '—' ? null : v;
+      };
+
+      const rawStatus = field('Status');
+      const plain = (rawStatus ?? '').replace(/\*\*/g, '').replace(/`/g, '').trim();
+      const resolved = resolveStatus(plain);
+
+      const boxes = [...text.matchAll(/^\s*-\s*\[([ xX])\]/gm)];
+      const criteria = parseCriteria(text);
+
+      out.push({
+        file: `${dir}/${f}`,
+        id: m[1],
+        slug: m[2],
+        title: (text.match(/^#\s+(?:Spec:\s*)?(.+)$/m) ?? [, m[2]])[1].trim(),
+        status: resolved.status,
+        rawStatus,
+        statusIsCanonical: resolved.canonical,
+        statusLeading: resolved.leading,       // the word opens the cell — safe to normalize
+        statusAmbiguous: resolved.ambiguous,   // several stage words present, none clearly leading
+        statusCandidates: resolved.candidates,
+        branch: field('Branch'),
+        ticket: field('Ticket'),
+        acTotal: boxes.length,
+        acChecked: boxes.filter((b) => b[1].toLowerCase() === 'x').length,
+        archived: dir.endsWith('archive'),
+        // Added for the traceability and brief scripts. Existing fields are
+        // untouched — the MCP server and the dashboard both read this shape.
+        criteria,
+        repos: splitCell(field('Project / service') ?? field('Project') ?? field('Repos')),
+        nfrs: splitCell(field('NFRs') ?? field('NFR')),
+        approvedBy: field('Approved by') ?? field('Approver'),
+        author: field('Author'),
+      });
+    }
+  }
+  return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * Everything a human should look at, derived once so the dashboard, /repo-status and
+ * /repo-doctor all flag the same things.
+ */
+export function analyze(specs) {
+  const byStatus = Object.fromEntries(LIFECYCLE.map((s) => [s, 0]));
+  let unknownStatus = 0;
+  for (const s of specs) {
+    if (s.status) byStatus[s.status]++;
+    else unknownStatus++;
+  }
+
+  const byId = new Map();
+  for (const s of specs) {
+    if (!byId.has(s.id)) byId.set(s.id, []);
+    byId.get(s.id).push(s.file);
+  }
+
+  const acTotal = specs.reduce((n, s) => n + s.acTotal, 0);
+  const acChecked = specs.reduce((n, s) => n + s.acChecked, 0);
+
+  return {
+    total: specs.length,
+    active: specs.filter((s) => !s.archived).length,
+    byStatus,
+    unknownStatus,
+    acTotal,
+    acChecked,
+    duplicateIds: [...byId.entries()].filter(([, f]) => f.length > 1).map(([id, files]) => ({ id, files })),
+    nonCanonical: specs.filter((s) => s.rawStatus && !s.statusIsCanonical),
+    // Claims the repo can't back up, in severity order.
+    attention: [
+      ...specs
+        .filter((s) => s.status === 'Implemented' && s.acTotal > 0 && s.acChecked < s.acTotal)
+        .map((s) => ({ level: 'critical', spec: s, why: `Implemented but ${s.acTotal - s.acChecked} of ${s.acTotal} criteria unchecked` })),
+      ...specs
+        .filter((s) => s.status === 'Verified' && !s.archived && s.acTotal > 0 && s.acChecked < s.acTotal)
+        .map((s) => ({ level: 'critical', spec: s, why: 'Verified with unchecked criteria — the status claims evidence that is not there' })),
+      ...specs
+        .filter((s) => !s.status && s.rawStatus)
+        .map((s) => ({ level: 'serious', spec: s, why: `Status has no lifecycle word: "${s.rawStatus.slice(0, 60)}"` })),
+      ...specs
+        .filter((s) => !s.archived && (s.status === 'Draft' || s.status === 'Approved') && !s.branch)
+        .map((s) => ({ level: 'warning', spec: s, why: `${s.status} with no branch recorded — not started` })),
+      ...specs
+        .filter((s) => s.acTotal === 0 && !s.archived)
+        .map((s) => ({ level: 'warning', spec: s, why: 'No acceptance criteria — nothing to verify against' })),
+    ],
+  };
+}