@mlmcps/ml-specs-mcp 1.0.0

package/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' })),
+    ],
+  };
+}

package/scripts/lib/trace.mjs

@@ -0,0 +1,90 @@
+// The ID spine: one key, derived into every downstream artifact name.
+//
+// Imported by scripts/spec-trace.mjs and scripts/spec-brief.mjs so there is one
+// implementation of "what is this change called everywhere".
+//
+// Pure Node, no dependencies. No I/O, no network — every function here is a
+// string transform, which is what makes the chain checkable offline in CI.
+//
+// Why it matters: without a key carried end to end, "which requirement is
+// covered by which test, and did it ship?" has no answer that survives an audit.
+// Every id below is PRODUCED by a function and RECOVERED by its matching parser,
+// so a link that lost the key is a parse failure rather than a silent divergence.
+
+/** `Payment hold on partial capture` -> `payment-hold-on-partial-capture` */
+export function slugify(title) {
+  return String(title)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48)
+    .replace(/-+$/, '');
+}
+
+export const specId = (id) => `SPEC-${id}`;
+export const branchName = (id, title) => `feat/${id}-${slugify(title)}`;
+export const prTitle = (id, title) => `[${specId(id)}] ${title}`;
+export const testCaseId = (id, ordinal) => `TC-${id}.${ordinal}`;
+
+// A spec id is digits plus an OPTIONAL letter, matching lib/specs.mjs:
+// 0165 and 0165b are different specs, not a clash.
+const KEY = '(\\d{3,4}[a-z]?)';
+
+const PARSERS = {
+  specId: new RegExp(`^SPEC-${KEY}$`),
+  branch: new RegExp(`^(?:feat|fix|chore)/${KEY}-`),
+  prTitle: new RegExp(`^\\[SPEC-${KEY}\\]`),
+  testCase: new RegExp(`^TC-${KEY}\\.\\d+$`),
+  specFile: new RegExp(`^(?:specs/(?:archive/)?)?${KEY}-.+\\.md$`),
+};
+
+/** Recover the key from a downstream artifact name, or null if it carries none. */
+export function keyFrom(kind, value) {
+  const re = PARSERS[kind];
+  if (!re) throw new Error(`unknown artifact kind: ${kind}`);
+  const m = re.exec(String(value ?? ''));
+  return m ? m[1] : null;
+}
+
+export const ARTIFACT_KINDS = Object.keys(PARSERS);
+
+/**
+ * Build the chain for a spec. Links are `derived` (a function above produced the
+ * name, so the key cannot be missing) or `declared` (a human or an external
+ * system supplied it). Only declared links can break — which is exactly why they
+ * are reported separately rather than assumed sound.
+ */
+export function buildChain(spec, { testCases = true } = {}) {
+  const links = [
+    { kind: 'ticket', ref: spec.ticket ?? '(none)', origin: 'declared' },
+    { kind: 'spec', ref: specId(spec.id), origin: 'derived', parseAs: 'specId' },
+    { kind: 'specFile', ref: spec.file, origin: 'derived', parseAs: 'specFile' },
+    { kind: 'branch', ref: spec.branch ?? branchName(spec.id, spec.title), origin: spec.branch ? 'declared' : 'derived', parseAs: 'branch' },
+    { kind: 'pullRequest', ref: prTitle(spec.id, spec.title), origin: 'derived', parseAs: 'prTitle' },
+  ];
+
+  if (testCases && spec.status !== 'Draft') {
+    for (const ac of spec.criteria ?? []) {
+      links.push({ kind: 'testCase', ref: testCaseId(spec.id, ac.ordinal), origin: 'derived', parseAs: 'testCase', from: ac.id });
+    }
+  }
+  return { key: spec.id, links };
+}
+
+/** Does every parseable link carry the chain's key? */
+export function verifyChain(chain) {
+  const broken = [];
+  const unverifiable = [];
+
+  for (const link of chain.links) {
+    if (!link.parseAs) { unverifiable.push(link); continue; }
+    const found = keyFrom(link.parseAs, link.ref);
+    if (found === null) broken.push({ link, reason: 'missing-key', found: null });
+    else if (found !== chain.key) broken.push({ link, reason: 'wrong-key', found });
+  }
+
+  return { ok: broken.length === 0, broken, unverifiable };
+}
+
+export const renderChain = (chain) =>
+  chain.links.map((l) => (l.parseAs ? l.ref : `${l.ref} (unverified)`)).join('  ->  ');

package/scripts/lib/tracker.mjs

@@ -0,0 +1,257 @@
+// Azure DevOps and Jira, behind one seam.
+//
+// Two implementations ship together deliberately. An abstraction with a single
+// implementation is a guess about what varies, and it is usually wrong; the
+// second one is what proves the seam is in the right place. Jira's differences
+// are instructive — status moves through a TRANSITION rather than a field write,
+// and there is no native test-case type — and both would have leaked through a
+// single-adapter design.
+//
+// Pure Node, no dependencies. Every call goes through an injected transport.
+
+import { basicAuth, request } from './http.mjs';
+
+// Which system owns which field. The spec in the repo owns the contract; the
+// tracker owns the schedule. Two stores for one truth diverge silently unless
+// exactly one of them may write each field.
+export const FIELD_OWNER = {
+  title: 'spec', criteria: 'spec', contract: 'spec', nfrs: 'spec', repos: 'spec',
+  status: 'board', assignee: 'board', sprint: 'board', priority: 'board',
+};
+
+export const specKeyFromText = (text) => (/SPEC-(\d{3,4}[a-z]?)/.exec(text ?? '') ?? [])[1] ?? null;
+
+// --- Azure DevOps -----------------------------------------------------------
+
+const ADO_FIELD = {
+  status: 'System.State', assignee: 'System.AssignedTo',
+  sprint: 'System.IterationPath', priority: 'Microsoft.VSTS.Common.Priority',
+};
+
+export function adoTracker({ org, project, pat, apiVersion = '7.1', transport = request }) {
+  const base = `https://dev.azure.com/${org}/${encodeURIComponent(project)}/_apis`;
+  // ADO's documented scheme: empty username, PAT as the password.
+  const headers = { Authorization: basicAuth('', pat) };
+  const patchType = 'application/json-patch+json';
+
+  const toItem = (raw) => ({
+    id: String(raw.id),
+    title: raw.fields?.['System.Title'] ?? '',
+    status: raw.fields?.['System.State'] ?? '',
+    assignee: raw.fields?.['System.AssignedTo']?.uniqueName ?? null,
+    sprint: raw.fields?.['System.IterationPath'] ?? null,
+    url: `https://dev.azure.com/${org}/${encodeURIComponent(project)}/_workitems/edit/${raw.id}`,
+    specKey: specKeyFromText(`${raw.fields?.['System.Title'] ?? ''} ${raw.fields?.['System.Description'] ?? ''}`),
+  });
+
+  return {
+    tool: 'ado',
+
+    async getWorkItem(id) {
+      try { return toItem(await transport(`${base}/wit/workitems/${id}?api-version=${apiVersion}`, { headers })); }
+      catch { return null; }
+    },
+
+    async findBySpec(key) {
+      const res = await transport(`${base}/wit/wiql?api-version=${apiVersion}`, {
+        method: 'POST', headers,
+        body: { query: `SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @project ` +
+                       `AND [System.Title] CONTAINS 'SPEC-${key}'` },
+      });
+      const items = await Promise.all((res.workItems ?? []).map((w) => this.getWorkItem(String(w.id))));
+      return items.filter(Boolean);
+    },
+
+    async createWorkItem({ title, type, description, specKey, parentId }) {
+      const patch = [
+        { op: 'add', path: '/fields/System.Title', value: `[SPEC-${specKey}] ${title}` },
+        { op: 'add', path: '/fields/System.Description', value: description ?? '' },
+      ];
+      if (parentId) patch.push({ op: 'add', path: '/relations/-',
+        value: { rel: 'System.LinkTypes.Hierarchy-Reverse', url: `${base}/wit/workItems/${parentId}` } });
+      return toItem(await transport(
+        `${base}/wit/workitems/$${encodeURIComponent(type)}?api-version=${apiVersion}`,
+        { method: 'POST', headers, body: patch, contentType: patchType }));
+    },
+
+    async updateFields(id, fields) {
+      const patch = Object.entries(fields)
+        .filter(([k]) => ADO_FIELD[k])
+        .map(([k, v]) => ({ op: 'add', path: `/fields/${ADO_FIELD[k]}`, value: v }));
+      return toItem(await transport(`${base}/wit/workitems/${id}?api-version=${apiVersion}`,
+        { method: 'PATCH', headers, body: patch, contentType: patchType }));
+    },
+
+    async createTestCases(workItemId, cases) {
+      const created = [];
+      for (const tc of cases) {
+        const steps = tc.steps.map((s) =>
+          `<step><parameterizedString>${escapeXml(s)}</parameterizedString></step>`).join('');
+        const raw = await transport(`${base}/wit/workitems/$Test%20Case?api-version=${apiVersion}`, {
+          method: 'POST', headers, contentType: patchType,
+          body: [
+            { op: 'add', path: '/fields/System.Title', value: `${tc.id} ${tc.title}` },
+            { op: 'add', path: '/fields/Microsoft.VSTS.TCM.Steps', value: steps },
+            { op: 'add', path: '/relations/-',
+              value: { rel: 'Microsoft.VSTS.Common.TestedBy-Reverse', url: `${base}/wit/workItems/${workItemId}` } },
+          ],
+        });
+        created.push(String(raw.id));
+      }
+      return created;
+    },
+  };
+}
+
+const escapeXml = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+// --- Jira --------------------------------------------------------------------
+
+const JIRA_TYPE = { Epic: 'Epic', Feature: 'Story', 'User Story': 'Story', Task: 'Task' };
+
+/** Jira Cloud wants Atlassian Document Format, not a string. */
+const adf = (text) => ({ type: 'doc', version: 1,
+  content: String(text ?? '').split('\n\n').map((p) => ({ type: 'paragraph', content: [{ type: 'text', text: p || ' ' }] })) });
+
+export function jiraTracker({ baseUrl, email, apiToken, projectKey, testCaseIssueType = 'Test', transport = request }) {
+  const headers = { Authorization: basicAuth(email, apiToken) };
+  const call = (path, opts = {}) => transport(`${baseUrl}${path}`, { headers, ...opts });
+
+  const toItem = (raw) => ({
+    id: raw.key,
+    title: raw.fields?.summary ?? '',
+    status: raw.fields?.status?.name ?? '',
+    assignee: raw.fields?.assignee?.emailAddress ?? null,
+    sprint: raw.fields?.sprint?.name ?? null,
+    url: `${baseUrl}/browse/${raw.key}`,
+    specKey: specKeyFromText(raw.fields?.summary),
+  });
+
+  async function transition(id, toStatus) {
+    const { transitions = [] } = await call(`/rest/api/3/issue/${id}/transitions`);
+    const match = transitions.find((t) =>
+      t.to?.name?.toLowerCase() === toStatus.toLowerCase() || t.name?.toLowerCase() === toStatus.toLowerCase());
+    if (!match) {
+      throw new Error(`Jira ${id} has no transition to "${toStatus}" ` +
+        `(available: ${transitions.map((t) => t.to?.name).join(', ') || 'none'})`);
+    }
+    await call(`/rest/api/3/issue/${id}/transitions`, { method: 'POST', body: { transition: { id: match.id } } });
+  }
+
+  return {
+    tool: 'jira',
+
+    async getWorkItem(id) {
+      try { return toItem(await call(`/rest/api/3/issue/${id}`)); } catch { return null; }
+    },
+
+    async findBySpec(key) {
+      const jql = `project = "${projectKey}" AND summary ~ "SPEC-${key}"`;
+      const res = await call(`/rest/api/3/search?jql=${encodeURIComponent(jql)}&maxResults=50`);
+      return (res.issues ?? []).map(toItem);
+    },
+
+    async createWorkItem({ title, type, description, specKey, parentId }) {
+      const fields = {
+        project: { key: projectKey },
+        summary: `[SPEC-${specKey}] ${title}`,
+        issuetype: { name: JIRA_TYPE[type] ?? 'Task' },
+        description: adf(description),
+        ...(parentId ? { parent: { key: parentId } } : {}),
+      };
+      const created = await call('/rest/api/3/issue', { method: 'POST', body: { fields } });
+      const item = await this.getWorkItem(created.key);
+      if (!item) throw new Error(`Jira created ${created.key} but it could not be read back`);
+      return item;
+    },
+
+    async updateFields(id, fields) {
+      // The instructive difference from ADO: status is a transition, not a write.
+      if (fields.status) await transition(id, fields.status);
+
+      const direct = {};
+      if (fields.assignee) direct.assignee = { emailAddress: fields.assignee };
+      if (fields.priority) direct.priority = { name: fields.priority };
+      if (Object.keys(direct).length) await call(`/rest/api/3/issue/${id}`, { method: 'PUT', body: { fields: direct } });
+
+      const item = await this.getWorkItem(id);
+      if (!item) throw new Error(`no Jira issue ${id}`);
+      return item;
+    },
+
+    async createTestCases(workItemId, cases) {
+      const created = [];
+      for (const tc of cases) {
+        const res = await call('/rest/api/3/issue', { method: 'POST', body: { fields: {
+          project: { key: projectKey },
+          summary: `${tc.id} ${tc.title}`,
+          issuetype: { name: testCaseIssueType },
+          description: adf([`Derived from ${tc.from} of SPEC-${tc.specKey}.`, ...tc.steps].join('\n')),
+        } } });
+        await call('/rest/api/3/issueLink', { method: 'POST', body: {
+          type: { name: 'Relates' }, inwardIssue: { key: res.key }, outwardIssue: { key: workItemId } } });
+        created.push(res.key);
+      }
+      return created;
+    },
+  };
+}
+
+// --- capability split (the ungoverned path) ----------------------------------
+
+/**
+ * What the intent plane is allowed to hold.
+ *
+ * A direct path from planning into the tracker that bypasses the spec becomes
+ * the path everyone uses, because it is faster and nobody is watching. This
+ * returns a FROZEN object carrying only the read methods, so the write methods
+ * are absent at runtime and cannot be re-attached — the shortcut is not policed,
+ * it cannot be expressed.
+ */
+export const readOnly = (tracker) => Object.freeze({
+  tool: tracker.tool,
+  getWorkItem: (id) => tracker.getWorkItem(id),
+  findBySpec: (key) => tracker.findBySpec(key),
+});
+
+/**
+ * The single governed write path: the spec must be past the approval gate, and
+ * only board-owned fields may be written.
+ */
+export function governedWriter(tracker) {
+  const assertWritable = (field) => {
+    const owner = FIELD_OWNER[field];
+    if (owner && owner !== 'board') {
+      throw new Error(`"${field}" is owned by the spec; the board may read it but not write it`);
+    }
+  };
+  const assertApproved = (spec) => {
+    if (!spec.status || spec.status === 'Draft') {
+      throw new Error(`spec ${spec.id} is ${spec.status ?? 'unknown'}; nothing reaches ${tracker.tool} before the approval gate`);
+    }
+  };
+
+  return {
+    tool: tracker.tool,
+
+    async push(spec, fields) {
+      assertApproved(spec);
+      if (!spec.ticket) throw new Error(`spec ${spec.id} has no linked work item to write to`);
+      for (const f of Object.keys(fields)) assertWritable(f);
+      return tracker.updateFields(spec.ticket, fields);
+    },
+
+    async open(spec, type, parentId) {
+      assertApproved(spec);
+      return tracker.createWorkItem({ title: spec.title, type, description: '', specKey: spec.id, parentId });
+    },
+
+    async pushTestCases(spec, cases) {
+      assertApproved(spec);
+      if (!spec.ticket) throw new Error(`spec ${spec.id} has no linked work item`);
+      const foreign = cases.find((c) => c.specKey !== spec.id);
+      if (foreign) throw new Error(`${foreign.id} was not derived from spec ${spec.id}`);
+      return tracker.createTestCases(spec.ticket, cases);
+    },
+  };
+}

package/scripts/nfr-compile.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// Compile non-functional requirements into the two things that enforce them:
+// standing constraints in docs/CONSTRAINTS.md, and blocking pipeline gates.
+// Pure Node, no dependencies. No network calls — nothing leaves this machine.
+//
+//   node nfr-compile.mjs --root /path/to/repo             # dry run: prints, writes nothing
+//   node nfr-compile.mjs --root /path/to/repo --apply     # writes docs/CONSTRAINTS.md
+//   node nfr-compile.mjs --root /path/to/repo --gates ci/nfr-gates.yml
+//   node nfr-compile.mjs --json
+//
+// Exit code 1 if an NFR cannot be compiled, or if one has been flattened into an
+// acceptance criterion.
+//
+// Reads docs/NFRS.md (a markdown table, so it reviews in a pull request like
+// anything else), falling back to nfrs.json.
+//
+// Why this exists: NFRs are the requirements most likely to be agreed and then
+// lost. They do not decompose into user stories — a story breakdown flattens
+// them into prose nothing checks. They decompose into a constraint the author
+// reads and a gate the build fails on, and this produces both or refuses.
+
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { listSpecs } from './lib/specs.mjs';
+import { compile, findFlattened, toPipelineYaml, parseNfrMarkdown } from './lib/nfr.mjs';
+import * as knowledge from './lib/knowledge.mjs';
+
+const 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 root = flag('root', process.cwd());
+const json = has('json');
+const apply = has('apply');
+const gatesOut = flag('gates');
+
+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 };
+
+// --- read -------------------------------------------------------------------
+const md = join(root, 'docs', 'NFRS.md');
+const jsonFile = join(root, 'nfrs.json');
+let nfrs = [];
+let source = null;
+if (existsSync(md)) { nfrs = parseNfrMarkdown(readFileSync(md, 'utf8')); source = 'docs/NFRS.md'; }
+else if (existsSync(jsonFile)) { nfrs = JSON.parse(readFileSync(jsonFile, 'utf8')); source = 'nfrs.json'; }
+
+if (!source) {
+  console.error(`no docs/NFRS.md or nfrs.json under ${root}`);
+  process.exit(1);
+}
+
+// --- compile ----------------------------------------------------------------
+const compiled = [];
+const refused = [];
+for (const nfr of nfrs) {
+  try { compiled.push({ nfr, ...compile(nfr) }); }
+  catch (e) { refused.push({ id: nfr.id ?? '(unnamed)', why: e.message }); }
+}
+
+const specs = listSpecs(root);
+const flattened = findFlattened(specs);
+
+// An NFR named by a spec but absent from the source is worse than an unrouted
+// one: the spec claims a constraint that does not exist anywhere.
+const known = new Set(nfrs.map((n) => n.id));
+const dangling = [];
+for (const s of specs) {
+  for (const id of s.nfrs ?? []) if (!known.has(id)) dangling.push({ spec: s.id, nfr: id });
+}
+
+const constraintsPath = join(root, 'docs', 'CONSTRAINTS.md');
+let changed = [];
+if (apply && refused.length === 0) {
+  changed = knowledge.write(constraintsPath, compiled.map((c) => c.constraint));
+}
+if (gatesOut && refused.length === 0) {
+  const out = join(root, gatesOut);
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, toPipelineYaml(compiled.map((c) => c.gate)) + '\n');
+}
+
+const ok = refused.length === 0 && flattened.length === 0 && dangling.length === 0;
+
+if (json) {
+  console.log(JSON.stringify({ root, source, ok,
+    compiled: compiled.map((c) => ({ id: c.nfr.id, constraint: c.constraint, gate: c.gate })),
+    refused, flattened, dangling, changed, applied: apply }, null, 2));
+} else {
+  console.log(`${C.bold('source')} ${C.dim(source)}\n`);
+  for (const { nfr, constraint, gate } of compiled) {
+    console.log(`  ${C.green(nfr.id)} ${C.dim(nfr.kind.padEnd(12))} ${constraint.text}`);
+    console.log(`         ${C.dim(`gate: ${gate.tool} — ${gate.assertion}  scope: ${constraint.scope.join(', ')}`)}`);
+  }
+  for (const r of refused) console.log(`  ${C.red(r.id)} ${C.red('refused')} ${C.dim(r.why)}`);
+
+  if (flattened.length) {
+    console.log(`\n  ${C.red('flattened into a story — an NFR here stops being enforced:')}`);
+    for (const f of flattened) console.log(`    ${C.dim(`${f.spec} ${f.criterion} mentions ${f.nfr}`)}`);
+  }
+  if (dangling.length) {
+    console.log(`\n  ${C.red('named by a spec but defined nowhere:')}`);
+    for (const d of dangling) console.log(`    ${C.dim(`spec ${d.spec} -> ${d.nfr}`)}`);
+  }
+
+  console.log();
+  if (apply && refused.length === 0) {
+    console.log(changed.length
+      ? `  ${C.green('knowledge layer updated')} ${C.dim(`${changed.join(', ')} -> docs/CONSTRAINTS.md`)}`
+      : `  ${C.dim('knowledge layer already current')}`);
+  } else if (!apply) {
+    console.log(`  ${C.dim('dry run — pass --apply to write docs/CONSTRAINTS.md')}`);
+  }
+  if (gatesOut && refused.length === 0) console.log(`  ${C.green('pipeline gates written')} ${C.dim(gatesOut)}`);
+  console.log(ok ? `  ${C.green('all NFRs routed')}` : `  ${C.red('not every NFR is enforced')}`);
+}
+
+process.exit(ok ? 0 : 1);