@mlmcps/ml-specs 1.0.0

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

@@ -0,0 +1,177 @@
+// Contract tests for the tracker clients.
+//
+// These cannot prove a remote accepts the request — only a live organisation can
+// do that. They prove the client builds the document the API DOCUMENTS, which is
+// where the bugs actually are: a wrong JSON-patch path, a field written directly
+// that Jira only moves through a transition, a missing content type.
+//
+// Every call goes through the injected recorder, so none of this touches a network.
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { recorder } from './http.mjs';
+import { adoTracker, jiraTracker, readOnly, governedWriter, specKeyFromText, FIELD_OWNER } from './tracker.mjs';
+
+const ADO = { org: 'contoso', project: 'Payments Core', pat: 's3cret' };
+const JIRA = { baseUrl: 'https://contoso.atlassian.net', email: 'bot@m.example', apiToken: 't0ken', projectKey: 'PAY' };
+const ops = (body) => Object.fromEntries(body.map((o) => [o.path, o.value]));
+const decode = (h) => Buffer.from(h.replace('Basic ', ''), 'base64').toString();
+
+const SPEC = { id: '0031', title: 'Idempotent refund submission', status: 'Approved', ticket: '1847' };
+const CASE = { id: 'TC-0031.1', title: 'replay returns the original', from: 'AC-1', specKey: '0031', steps: ['a < b & c'] };
+
+describe('Azure DevOps', () => {
+  test('auth is Basic with an empty username', async () => {
+    // ADO's documented scheme: empty user, PAT as the password.
+    const { basicAuth } = await import('./http.mjs');
+    assert.equal(decode(basicAuth('', 's3cret')), ':s3cret');
+  });
+
+  test('a project with a space is url-encoded, api-version pinned', async () => {
+    const t = recorder();
+    await adoTracker({ ...ADO, transport: t }).getWorkItem('1847');
+    assert.match(t.last().url, /\/Payments%20Core\/_apis\/wit\/workitems\/1847/);
+    assert.match(t.last().url, /api-version=7\.1/);
+  });
+
+  test('create uses json-patch and stamps the key into the title', async () => {
+    const t = recorder();
+    await adoTracker({ ...ADO, transport: t })
+      .createWorkItem({ title: 'Payment hold', type: 'User Story', description: 'why', specKey: '0031' });
+    assert.equal(t.last().method, 'POST');
+    assert.equal(t.last().contentType, 'application/json-patch+json');
+    assert.match(t.last().url, /\/wit\/workitems\/\$User%20Story/);
+    assert.equal(ops(t.last().body)['/fields/System.Title'], '[SPEC-0031] Payment hold');
+  });
+
+  test('a parent is linked as Hierarchy-Reverse', async () => {
+    const t = recorder();
+    await adoTracker({ ...ADO, transport: t })
+      .createWorkItem({ title: 'child', type: 'Task', specKey: '0031', parentId: '900' });
+    const rel = ops(t.last().body)['/relations/-'];
+    assert.equal(rel.rel, 'System.LinkTypes.Hierarchy-Reverse');
+    assert.match(rel.url, /\/wit\/workItems\/900$/);
+  });
+
+  test('field names map to ADO reference names', async () => {
+    const t = recorder();
+    await adoTracker({ ...ADO, transport: t }).updateFields('1847', { status: 'Active', sprint: 'Payments\\Sprint 4' });
+    const o = ops(t.last().body);
+    assert.equal(o['/fields/System.State'], 'Active');
+    assert.equal(o['/fields/System.IterationPath'], 'Payments\\Sprint 4');
+    assert.equal(t.last().method, 'PATCH');
+  });
+
+  test('a contract-owned field has no mapping, so it cannot be sent', async () => {
+    const t = recorder();
+    await adoTracker({ ...ADO, transport: t }).updateFields('1847', { title: 'rewritten' });
+    assert.deepEqual(ops(t.last().body), {});
+  });
+
+  test('find queries WIQL on the key', async () => {
+    const t = recorder([{ workItems: [] }]);
+    await adoTracker({ ...ADO, transport: t }).findBySpec('0031');
+    assert.match(t.calls[0].body.query, /SPEC-0031/);
+    assert.match(t.calls[0].body.query, /@project/);
+  });
+
+  test('test cases link back and escape their steps', async () => {
+    const t = recorder();
+    await adoTracker({ ...ADO, transport: t }).createTestCases('1847', [CASE]);
+    const o = ops(t.last().body);
+    assert.match(t.last().url, /\$Test%20Case/);
+    assert.equal(o['/fields/System.Title'], 'TC-0031.1 replay returns the original');
+    assert.match(o['/fields/Microsoft.VSTS.TCM.Steps'], /a &lt; b &amp; c/);
+    assert.equal(o['/relations/-'].rel, 'Microsoft.VSTS.Common.TestedBy-Reverse');
+  });
+});
+
+describe('Jira', () => {
+  test('the neutral type is mapped and the description is ADF', async () => {
+    const t = recorder([{ key: 'PAY-9' }, { key: 'PAY-9', fields: {} }]);
+    await jiraTracker({ ...JIRA, transport: t })
+      .createWorkItem({ title: 'Payment hold', type: 'User Story', description: 'why', specKey: '0031' });
+    const f = t.calls[0].body.fields;
+    assert.equal(f.issuetype.name, 'Story');            // not "User Story"
+    assert.equal(f.summary, '[SPEC-0031] Payment hold');
+    assert.equal(f.description.type, 'doc');            // Jira rejects a plain string
+  });
+
+  test('status moves through a transition, never a field write', async () => {
+    // The instructive difference from ADO, and the reason two adapters ship.
+    const t = recorder([
+      { transitions: [{ id: '31', name: 'Start', to: { name: 'In Progress' } }] },
+      null,
+      { key: 'PAY-9', fields: { status: { name: 'In Progress' } } },
+    ]);
+    await jiraTracker({ ...JIRA, transport: t }).updateFields('PAY-9', { status: 'In Progress' });
+    assert.equal(t.calls[0].method, 'GET');
+    assert.match(t.calls[0].url, /\/transitions$/);
+    assert.equal(t.calls[1].body.transition.id, '31');
+    assert.ok(!t.calls.some((c) => c.method === 'PUT'));
+  });
+
+  test('an impossible transition names what is available', async () => {
+    const t = recorder([{ transitions: [{ id: '31', name: 'Start', to: { name: 'In Progress' } }] }]);
+    await assert.rejects(
+      () => jiraTracker({ ...JIRA, transport: t }).updateFields('PAY-9', { status: 'Done' }),
+      /In Progress/);
+  });
+
+  test('find builds JQL on the key', async () => {
+    const t = recorder([{ issues: [] }]);
+    await jiraTracker({ ...JIRA, transport: t }).findBySpec('0031');
+    assert.match(decodeURIComponent(t.last().url), /summary ~ "SPEC-0031"/);
+  });
+
+  test('test cases are created then linked', async () => {
+    const t = recorder([{ key: 'PAY-77' }, null]);
+    const created = await jiraTracker({ ...JIRA, transport: t }).createTestCases('PAY-9', [CASE]);
+    assert.deepEqual(created, ['PAY-77']);
+    assert.match(t.calls[1].url, /\/issueLink$/);
+    assert.equal(t.calls[1].body.inwardIssue.key, 'PAY-77');
+    assert.equal(t.calls[1].body.outwardIssue.key, 'PAY-9');
+  });
+});
+
+describe('the ungoverned write path does not exist', () => {
+  test('a reader has no write methods, and they cannot be re-attached', () => {
+    const reader = readOnly(adoTracker({ ...ADO, transport: recorder() }));
+    assert.equal(reader.createWorkItem, undefined);
+    assert.equal(reader.updateFields, undefined);
+    assert.equal(typeof reader.getWorkItem, 'function');
+    assert.throws(() => { 'use strict'; reader.createWorkItem = () => {}; });
+  });
+
+  test('nothing reaches the tracker before the approval gate', async () => {
+    const w = governedWriter(adoTracker({ ...ADO, transport: recorder() }));
+    await assert.rejects(() => w.push({ id: '0031', status: 'Draft', ticket: '1' }, { status: 'Active' }), /before the approval gate/);
+    await assert.rejects(() => w.open({ id: '0031', status: 'Draft', title: 'x' }, 'Task'), /before the approval gate/);
+  });
+
+  test('a contract-owned field is refused even through the governed path', async () => {
+    const w = governedWriter(adoTracker({ ...ADO, transport: recorder() }));
+    await assert.rejects(() => w.push(SPEC, { criteria: 'rewritten' }), /owned by the spec/);
+    assert.equal(FIELD_OWNER.status, 'board');
+    assert.equal(FIELD_OWNER.criteria, 'spec');
+  });
+
+  test('test cases from another spec cannot be smuggled onto this work item', async () => {
+    const w = governedWriter(adoTracker({ ...ADO, transport: recorder() }));
+    await assert.rejects(() => w.pushTestCases(SPEC, [{ ...CASE, specKey: '0019' }]), /not derived from spec 0031/);
+  });
+
+  test('an approved spec writes board-owned fields', async () => {
+    const t = recorder();
+    const item = await governedWriter(adoTracker({ ...ADO, transport: t })).push(SPEC, { status: 'Active' });
+    assert.equal(t.last().method, 'PATCH');
+    assert.ok(item);
+  });
+});
+
+describe('key recovery', () => {
+  test('the key is read back out of a title or description', () => {
+    assert.equal(specKeyFromText('[SPEC-0031] Idempotent refund'), '0031');
+    assert.equal(specKeyFromText('a suffixed spec SPEC-0165b here'), '0165b');
+    assert.equal(specKeyFromText('no key here'), null);
+  });
+});

package/ml-specs/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);

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

@@ -0,0 +1,182 @@
+// Script-level behaviour: what each CLI does at its boundaries.
+//
+// The lib tests cover the logic; these cover the decision a script makes about
+// whether to act at all. That is where the interesting bugs live — a script that
+// notices a precondition is violated, says so in prose, and proceeds anyway
+// passes every unit test its lib has.
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPTS = dirname(fileURLToPath(import.meta.url));
+
+function repo(specs = {}) {
+  const dir = mkdtempSync(join(tmpdir(), 'sdd-scripts-'));
+  mkdirSync(join(dir, 'specs'), { recursive: true });
+  mkdirSync(join(dir, 'docs'), { recursive: true });
+  for (const [name, body] of Object.entries(specs)) writeFileSync(join(dir, 'specs', name), body);
+  return dir;
+}
+
+/** Run a script; return { code, stdout, stderr } instead of throwing on non-zero. */
+function run(script, args, cwd) {
+  try {
+    const stdout = execFileSync('node', [join(SCRIPTS, script), ...args], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    return { code: 0, stdout, stderr: '' };
+  } catch (e) {
+    return { code: e.status ?? 1, stdout: e.stdout ?? '', stderr: e.stderr ?? '' };
+  }
+}
+
+const spec = ({ status = 'Approved', criteria = '- [ ] **AC1** — Given x, when y, then z.' }) =>
+  `# Spec: Fixture\n\n| | |\n|---|---|\n| **Ticket** | PAY-1 |\n| **Status** | ${status} |\n\n## 5. Acceptance criteria\n\n${criteria}\n`;
+
+describe('spec-brief refuses rather than warns', () => {
+  test('an approved spec with NO criteria is refused', () => {
+    // A brief exists to state the definition of done. Without criteria there is
+    // none, so emitting one under a heading that claims to supply it is worse
+    // than refusing. spec-gate.mjs fails this spec; the two must agree.
+    const dir = repo({ '0200-none.md': spec({ criteria: '' }) });
+    const r = run('spec-brief.mjs', ['0200'], dir);
+    assert.equal(r.code, 1);
+    assert.match(r.stderr, /no acceptance criteria/);
+    assert.doesNotMatch(r.stdout, /Definition of done/);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('spec-gate and spec-brief agree on that spec', () => {
+    const dir = repo({ '0200-none.md': spec({ criteria: '' }) });
+    assert.equal(run('spec-gate.mjs', ['specs/0200-none.md'], dir).code,
+                 run('spec-brief.mjs', ['0200'], dir).code);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('a Draft spec is refused — the contract is still being negotiated', () => {
+    const dir = repo({ '0201-draft.md': spec({ status: 'Draft' }) });
+    const r = run('spec-brief.mjs', ['0201'], dir);
+    assert.equal(r.code, 1);
+    assert.match(r.stderr, /before the approval gate/);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('an approved spec with criteria produces a brief pairing each with its test case', () => {
+    const dir = repo({ '0202-ok.md': spec({}) });
+    const r = run('spec-brief.mjs', ['0202'], dir);
+    assert.equal(r.code, 0);
+    assert.match(r.stdout, /\*\*AC-1\*\* \(TC-0202\.1\)/);
+    assert.match(r.stdout, /Definition of done/);
+    rmSync(dir, { recursive: true, force: true });
+  });
+});
+
+describe('spec-trace', () => {
+  test('a suffixed spec id is a distinct spec, not a clash', () => {
+    const dir = repo({ '0165b-follow-up.md': spec({}) });
+    const r = run('spec-trace.mjs', ['0165b'], dir);
+    assert.equal(r.code, 0);
+    assert.match(r.stdout, /SPEC-0165b/);
+    assert.match(r.stdout, /TC-0165b\.1/);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('a hand-typed ticket is reported unverifiable, not counted as passing', () => {
+    const dir = repo({ '0203-x.md': spec({}) });
+    const r = run('spec-trace.mjs', ['0203'], dir);
+    assert.match(r.stdout, /cannot be verified from the repo/);
+    assert.match(r.stdout, /chain intact/);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('no matching spec is an error, not an empty pass', () => {
+    const dir = repo({ '0204-x.md': spec({}) });
+    assert.equal(run('spec-trace.mjs', ['9999'], dir).code, 1);
+    rmSync(dir, { recursive: true, force: true });
+  });
+});
+
+describe('spec-fanout never gives a false all-clear', () => {
+  const estate = `| Event / queue / topic | Producer | Consumer | Notes | Evidence |
+|---|---|---|---|---|
+| \`payment.captured\` | svc-a | svc-b (\`Listener\`) | n | e |`;
+
+  test('asked who breaks with no estate index, it refuses rather than reporting none', () => {
+    // An empty list plus a zero exit reads as "nothing else is affected". That is
+    // the most expensive wrong answer this script can give.
+    const dir = repo({ '0001-x.md': spec({}) });
+    const r = run('spec-fanout.mjs', ['0001', 'payment.captured', '--plan'], dir);
+    assert.equal(r.code, 1);
+    assert.match(r.stderr, /cannot say who else breaks/);
+    assert.match(r.stderr, /indistinguishable from "nothing is affected"/);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('a spec that fans out to nothing says which reason, not an empty plan', () => {
+    const dir = repo({ '0001-x.md': spec({}) });
+    const r = run('spec-fanout.mjs', ['0001', '--plan'], dir);
+    assert.equal(r.code, 1);
+    assert.match(r.stderr, /fans out to nothing/);
+    assert.doesNotMatch(r.stdout, /would open/);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('with an index present it plans normally', () => {
+    const dir = repo({ '0001-x.md': spec({}) });
+    writeFileSync(join(dir, 'docs', 'ESTATE.md'), estate);
+    const r = run('spec-fanout.mjs', ['0001', 'payment.captured', '--plan'], dir);
+    assert.equal(r.code, 0);
+    assert.match(r.stdout, /svc-b/);
+    assert.match(r.stdout, /consumes payment\.captured/);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('every target shares one branch name', () => {
+    const dir = repo({ '0001-x.md': spec({}) });
+    writeFileSync(join(dir, 'docs', 'ESTATE.md'), estate);
+    const out = run('spec-fanout.mjs', ['0001', 'payment.captured', '--plan'], dir).stdout;
+    const branches = [...out.matchAll(/feat\/0001-[a-z-]+/g)].map((m) => m[0]);
+    assert.ok(branches.length > 0);
+    assert.equal(new Set(branches).size, 1);
+    rmSync(dir, { recursive: true, force: true });
+  });
+});
+
+describe('nfr-compile', () => {
+  const NFRS = `| NFR | Kind | Statement | Metric | Op | Value | Unit | Applies to |
+|-----|------|-----------|--------|----|-------|------|------------|
+| NFR-01 | performance | responsive | p95 | < | 300 | ms | svc-a |
+| NFR-02 | security | no findings |  |  |  |  | * |`;
+
+  test('an NFR with no measurable threshold makes the run fail', () => {
+    const dir = repo({});
+    writeFileSync(join(dir, 'docs', 'NFRS.md'), NFRS);
+    const r = run('nfr-compile.mjs', [], dir);
+    assert.equal(r.code, 1);
+    assert.match(r.stdout, /NFR-02[\s\S]*refused/);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('dry run writes nothing', () => {
+    const dir = repo({});
+    writeFileSync(join(dir, 'docs', 'NFRS.md'),
+      NFRS.split('\n').filter((l) => !l.includes('NFR-02')).join('\n'));
+    run('nfr-compile.mjs', [], dir);
+    assert.throws(() => execFileSync('cat', [join(dir, 'docs', 'CONSTRAINTS.md')], { stdio: 'ignore' }));
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test('--apply writes the constraint and reports what changed', () => {
+    const dir = repo({});
+    writeFileSync(join(dir, 'docs', 'NFRS.md'),
+      NFRS.split('\n').filter((l) => !l.includes('NFR-02')).join('\n'));
+    const r = run('nfr-compile.mjs', ['--apply'], dir);
+    assert.equal(r.code, 0);
+    assert.match(r.stdout, /knowledge layer updated/);
+    // second run is a no-op and must say so rather than claiming a write
+    assert.match(run('nfr-compile.mjs', ['--apply'], dir).stdout, /already current/);
+    rmSync(dir, { recursive: true, force: true });
+  });
+});

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

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+// Package an approved spec for whoever implements it — a person, or an agent.
+// Pure Node, no dependencies. Read-only. No network calls.
+//
+//   node spec-brief.mjs 0031                      # to stdout
+//   node spec-brief.mjs 0031 --repo api-neelias
+//   node spec-brief.mjs 0031 --out brief.md
+//   node spec-brief.mjs 0031 --root /path/to/repo
+//
+// Exit code 1 if the spec is not past the approval gate.
+//
+// Why this exists: an approved spec is a contract, but it is scattered — the
+// criteria are in one section, the constraints in force are in another file, and
+// the gates that will fail the build are in a third. Whoever implements it has
+// to assemble that themselves, and the parts most often skipped are the ones
+// that cause the rework.
+//
+// A brief is deliberately NOT a prompt. It is the same document whether a person
+// or an agent implements the spec, because anything an agent would need that a
+// new engineer would not is a sign the spec is underspecified — and the fix for
+// that belongs in the spec, not in a wrapper around it.
+
+import { readFileSync, existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { listSpecs } from './lib/specs.mjs';
+import { specId, branchName, prTitle, testCaseId } from './lib/trace.mjs';
+import { compile, 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 root = flag('root', process.cwd());
+const target = argv.find((a, i) => !a.startsWith('--') && !String(argv[i - 1] ?? '').startsWith('--'));
+if (!target) { console.error('usage: spec-brief.mjs <spec-id|path> [--repo r] [--out f] [--root path]'); process.exit(1); }
+
+const spec = listSpecs(root).find((s) => s.id === target || s.file.endsWith(target) || s.file === target);
+if (!spec) { console.error(`no spec matching "${target}" under ${root}`); process.exit(1); }
+
+// The contract is still being negotiated until the gate passes; there is nothing
+// stable to build against.
+if (!spec.status || spec.status === 'Draft') {
+  console.error(`spec ${spec.id} is ${spec.status ?? 'unknown'} — nothing is handed to an implementer ` +
+                `before the approval gate. The contract is still being negotiated.`);
+  process.exit(1);
+}
+
+// A brief exists to state the definition of done. Without criteria there is no
+// definition of done, so emitting one that says so in prose and proceeding is
+// worse than refusing: it hands an implementer a document whose whole purpose is
+// missing, over a heading that claims to supply it. spec-gate.mjs already fails
+// this spec; the two must agree, or one of them is lying.
+if (!(spec.criteria ?? []).length) {
+  console.error(`spec ${spec.id} is ${spec.status} but has no acceptance criteria — there is ` +
+                `nothing to build against, and nothing to verify. Fix the spec (and the approval ` +
+                `that let it through) rather than starting from a brief with no definition of done.`);
+  process.exit(1);
+}
+
+const repo = flag('repo', spec.repos?.[0] ?? '.');
+const branch = spec.branch ?? branchName(spec.id, spec.title);
+
+const nfrPath = join(root, 'docs', 'NFRS.md');
+const allNfrs = existsSync(nfrPath) ? parseNfrMarkdown(readFileSync(nfrPath, 'utf8')) : [];
+const gates = (spec.nfrs ?? [])
+  .map((id) => allNfrs.find((n) => n.id === id))
+  .filter(Boolean)
+  .map((n) => { try { return compile(n).gate; } catch { return null; } })
+  .filter(Boolean);
+
+const inForce = knowledge.forRepos(
+  knowledge.read(join(root, 'docs', 'CONSTRAINTS.md')),
+  spec.repos?.length ? spec.repos : [repo]);
+
+const section = (name) => {
+  const body = readFileSync(join(root, spec.file), 'utf8');
+  const re = new RegExp(`^##\\s*(?:\\d+\\.\\s*)?${name}\\b.*$`, 'im');
+  const m = re.exec(body);
+  if (!m) return '';
+  return body.slice(m.index + m[0].length).split(/\n##\s/)[0].trim();
+};
+
+const lines = [
+  `# ${specId(spec.id)} — ${spec.title}`, '',
+  `**Repo:** \`${repo}\`  `,
+  `**Branch:** \`${branch}\`  `,
+  `**Pull request title:** \`${prTitle(spec.id, spec.title)}\`  `,
+  `**Status:** ${spec.status}${spec.ticket ? `  ·  **Ticket:** ${spec.ticket}` : ''}`, '',
+];
+
+const contract = section('Contract') || section('Scope') || section('Problem');
+if (contract) lines.push('## The contract', '', contract, '');
+
+lines.push('## Definition of done', '',
+  'Every criterion below has a test case id already reserved for it. The change is ' +
+  'done when each one passes — not when the code looks finished.', '');
+for (const ac of spec.criteria ?? []) {
+  lines.push(`- **${ac.id}** (${testCaseId(spec.id, ac.ordinal)}) — ${ac.text}`);
+}
+
+
+if (inForce.length) {
+  lines.push('', '## Constraints in force', '',
+    'Not negotiable within this change. They come from the knowledge layer and ' +
+    'apply to every spec touching this repo.', '',
+    ...inForce.map((c) => `- **${c.id}** — ${c.text}`));
+}
+
+if (gates.length) {
+  lines.push('', '## Gates that will run against this', '',
+    'The build fails if any of these does. They are not advisory.', '',
+    ...gates.map((g) => `- \`${g.tool}\` — ${g.assertion}  (${g.nfr})`));
+}
+
+const outOfScope = section('Out of scope');
+if (outOfScope) lines.push('', '## Out of scope', '', outOfScope);
+
+lines.push('', '---', '',
+  'If a decision is needed that this brief does not answer, the spec is incomplete: ' +
+  'stop and amend the spec rather than deciding in the code. An amendment after ' +
+  `approval sends ${specId(spec.id)} back through the approval gate, which is the ` +
+  'cheap outcome, not the expensive one.');
+
+const markdown = lines.join('\n') + '\n';
+const out = flag('out');
+if (out) { writeFileSync(join(root, out), markdown); console.log(`brief written  ${out}  (${branch})`); }
+else console.log(markdown);