@mlmcps/ml-specs 1.0.0

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

@@ -0,0 +1,108 @@
+// Read docs/ESTATE.md — the index /repo-estate generates — as a contract graph,
+// and answer "who else breaks if this changes".
+//
+// Pure Node, no dependencies. Read-only.
+//
+// Parsing is tolerant by design: this file is written for humans and edited by
+// them, and a parser that demanded exact formatting would fail on the first
+// sensible edit someone makes.
+
+const ROW = /^\|(.+)\|\s*$/;
+const SEP = /^\|[\s:|-]+\|\s*$/;
+const PLACEHOLDER = /^(<.*>|_TBD_|—|-|n\/?a|none|)$/i;
+
+const clean = (v) => String(v ?? '').replace(/[`*]/g, '').replace(/\s*\(.*\)\s*$/, '').trim();
+const names = (v) => String(v ?? '').split(/[,/]| and /).map(clean).filter((n) => n && !PLACEHOLDER.test(n));
+
+function tables(raw) {
+  const out = [];
+  let current = [];
+  for (const line of raw.split('\n')) {
+    const t = line.trim();
+    // The `|---|---|` rule belongs to the table it divides. Treating it as a
+    // break splits every table in two and orphans its header.
+    if (SEP.test(t)) continue;
+    const m = ROW.exec(t);
+    if (!m) { if (current.length) out.push(current); current = []; continue; }
+    current.push(m[1].split('|').map((c) => c.trim()));
+  }
+  if (current.length) out.push(current);
+  return out;
+}
+
+const headerHas = (row, ...required) => {
+  const lower = row.map((c) => c.toLowerCase());
+  return required.every((r) => lower.some((c) => c.includes(r)));
+};
+
+export function parseEstate(raw) {
+  const publishes = new Map();
+  const consumes = new Map();
+  const note = (repo) => {
+    if (!publishes.has(repo)) { publishes.set(repo, new Set()); consumes.set(repo, new Set()); }
+    return repo;
+  };
+
+  for (const table of tables(raw)) {
+    const [header, ...rows] = table;
+    if (!header) continue;
+
+    if (headerHas(header, 'service', 'owns')) {
+      for (const row of rows) for (const n of names(row[0])) note(n);
+
+    } else if (headerHas(header, 'caller', 'callee')) {
+      for (const row of rows) {
+        const contract = clean(row[3]) || clean(row[2]);
+        if (!contract || PLACEHOLDER.test(contract)) continue;
+        for (const callee of names(row[1])) publishes.get(note(callee)).add(contract);
+        for (const caller of names(row[0])) consumes.get(note(caller)).add(contract);
+      }
+
+    } else if (headerHas(header, 'producer', 'consumer')) {
+      for (const row of rows) {
+        const event = clean(row[0]);
+        if (!event || PLACEHOLDER.test(event)) continue;
+        for (const p of names(row[1])) publishes.get(note(p)).add(event);
+        for (const c of names(row[2])) consumes.get(note(c)).add(event);
+      }
+
+    } else if (headerHas(header, 'owner', 'used by')) {
+      for (const row of rows) {
+        const thing = clean(row[0]);
+        if (!thing || PLACEHOLDER.test(thing)) continue;
+        for (const o of names(row[1])) publishes.get(note(o)).add(thing);
+        for (const u of names(row[2])) consumes.get(note(u)).add(thing);
+      }
+    }
+  }
+
+  const generatedAt = (/(?:generated|updated|refreshed)[^\n]*?(\d{4}-\d{2}-\d{2})/i.exec(raw) ?? [])[1] ?? '';
+  return {
+    generatedAt,
+    repos: [...publishes.keys()].sort().map((name) => ({
+      name,
+      publishes: [...publishes.get(name)].sort(),
+      consumes: [...consumes.get(name)].sort(),
+    })),
+  };
+}
+
+/** Who consumes what this change touches — directly, and one hop further out. */
+export function impactOf(index, changed) {
+  const owners = index.repos.filter((r) => r.publishes.some((c) => changed.includes(c))).map((r) => r.name);
+
+  const directlyAffected = index.repos
+    .filter((r) => !owners.includes(r.name))
+    .map((r) => ({ repo: r.name, via: r.consumes.filter((c) => changed.includes(c)) }))
+    .filter((r) => r.via.length);
+
+  const directNames = directlyAffected.map((d) => d.repo);
+  const secondWave = new Set(index.repos.filter((r) => directNames.includes(r.name)).flatMap((r) => r.publishes));
+
+  const transitivelyAffected = index.repos
+    .filter((r) => !owners.includes(r.name) && !directNames.includes(r.name))
+    .map((r) => ({ repo: r.name, via: r.consumes.filter((c) => secondWave.has(c)) }))
+    .filter((r) => r.via.length);
+
+  return { changed, directlyAffected, transitivelyAffected };
+}

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

@@ -0,0 +1,73 @@
+// The seam between an adapter and the network.
+//
+// `request` is the real transport. Injecting `recorder()` instead is what makes
+// the tracker and SCM clients testable without credentials — the documents they
+// build are the part most likely to be wrong (a JSON-patch path, a field written
+// directly that Jira only moves through a transition), and all of that is
+// assertable offline.
+//
+// It also backs --dry-run, so an operator can read the exact request that would
+// hit their organisation before anyone grants an access token.
+//
+// Pure Node, no dependencies. Node 18+ for global fetch.
+
+export const basicAuth = (user, password) =>
+  'Basic ' + Buffer.from(`${user}:${password}`).toString('base64');
+
+/** The real transport. Throws with the response body, which is where the useful
+ *  part of an ADO or Jira error lives. */
+export async function request(url, { method = 'GET', headers = {}, body, contentType = 'application/json', timeout = 30000 } = {}) {
+  const init = { method, headers: { Accept: 'application/json', ...headers } };
+  if (body !== undefined) {
+    init.headers['Content-Type'] = contentType;
+    init.body = JSON.stringify(body);
+  }
+  const res = await fetch(url, { ...init, signal: AbortSignal.timeout(timeout) });
+  if (!res.ok) {
+    throw new Error(`${method} ${new URL(url).pathname} -> ${res.status} ${(await res.text()).slice(0, 500)}`);
+  }
+  const text = await res.text();
+  return text ? JSON.parse(text) : null;
+}
+
+/**
+ * A transport that records instead of sending. Returns canned responses in
+ * order, then a default shaped so every adapter's response parser completes —
+ * which is what lets --dry-run walk a whole flow rather than stopping at the
+ * first read.
+ */
+export function recorder(responses = []) {
+  let cursor = 0;
+  const calls = [];
+
+  const fn = async (url, { method = 'GET', body, contentType = 'application/json' } = {}) => {
+    calls.push({ method, url, body, contentType });
+    return cursor < responses.length ? responses[cursor++] : DEFAULT_RESPONSE;
+  };
+
+  fn.calls = calls;
+  fn.last = () => calls[calls.length - 1];
+  fn.transcript = () => calls.map(render).join('\n\n');
+  return fn;
+}
+
+const render = (c) => {
+  const head = `${c.method} ${c.url}`;
+  if (c.body === undefined) return head;
+  return `${head}\n  content-type: ${c.contentType}\n` +
+    JSON.stringify(c.body, null, 2).split('\n').map((l) => '  ' + l).join('\n');
+};
+
+// Keys are namespaced by their API so they do not collide.
+const SHA = '0f1e2d3c4b5a69788796a5b4c3d2e1f0a9b8c7d6';
+const DEFAULT_RESPONSE = {
+  // trackers
+  id: 1847, key: 'PAY-1847',
+  fields: { 'System.Title': '[SPEC-0031] placeholder', 'System.State': 'New',
+            summary: '[SPEC-0031] placeholder', status: { name: 'To Do' } },
+  workItems: [], issues: [], transitions: [],
+  // source control — ADO returns refs under `value`, GitHub a single `object`
+  value: [{ objectId: SHA, name: 'refs/heads/main' }],
+  object: { sha: SHA },
+  pullRequestId: 4321, number: 4321, html_url: 'https://example.invalid/pull/4321',
+};

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

@@ -0,0 +1,91 @@
+// The knowledge layer: standing constraints on disk, in docs/CONSTRAINTS.md.
+//
+// Pure Node, no dependencies. Writes one file, only when asked.
+//
+// Why a markdown file and not a database: this is read by people during spec
+// review far more often than by this code, and a change to what is in force
+// should diff in a pull request like any other change. A store only a machine
+// can read becomes a store nobody checks — which is worse than none, because it
+// looks like governance while enforcing nothing.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+const BEGIN = '<!-- sdd:constraints -->';
+const END = '<!-- /sdd:constraints -->';
+const REFRESHED = '<!-- sdd:refreshed ';
+const LINE = /^-\s+`([A-Za-z0-9_.-]+)`\s+\[([^\]]*)\]\s+(.+)$/;
+
+const HEADER = `# Standing constraints
+
+Constraints in force while authoring any spec. Generated — change the source
+(the NFR table, or the incident that produced a lesson) rather than this file.
+
+`;
+
+export function read(path) {
+  if (!existsSync(path)) return [];
+  const body = readFileSync(path, 'utf8');
+  if (!body.includes(BEGIN)) return [];
+  const block = body.split(BEGIN)[1].split(END)[0];
+
+  const out = [];
+  for (const line of block.split('\n')) {
+    const m = LINE.exec(line.trim());
+    if (!m) continue;
+    const scope = m[2].split(',').map((s) => s.trim()).filter(Boolean);
+    out.push({ id: m[1], scope: scope.length ? scope : ['*'], text: m[3] });
+  }
+  return out;
+}
+
+/** Days since the file was last written, or null if it never was. */
+export function staleness(path, today = new Date()) {
+  if (!existsSync(path)) return null;
+  const m = readFileSync(path, 'utf8').match(new RegExp(`${REFRESHED}(\\d{4}-\\d{2}-\\d{2})`));
+  if (!m) return null;
+  const then = new Date(`${m[1]}T00:00:00Z`);
+  return Math.floor((today - then) / 86400000);
+}
+
+/**
+ * What a spec touching these repos inherits. A constraint scoped `*` applies
+ * everywhere; a spec that names no repo yet still inherits the estate-wide ones,
+ * which is the common case early in a spec's life.
+ */
+export function forRepos(constraints, repos = []) {
+  if (!repos.length) return constraints.filter((c) => c.scope.includes('*'));
+  return constraints.filter((c) => c.scope.includes('*') || repos.some((r) => c.scope.includes(r)));
+}
+
+/** Upsert by id. Returns the ids that actually changed, so a caller need not
+ *  claim a write that was a no-op. */
+export function write(path, incoming, today = new Date()) {
+  const existing = new Map(read(path).map((c) => [c.id, c]));
+  const changed = [];
+
+  for (const c of incoming) {
+    const prev = existing.get(c.id);
+    if (!prev || prev.text !== c.text || prev.scope.join() !== c.scope.join()) changed.push(c.id);
+    existing.set(c.id, c);
+  }
+
+  const rows = [...existing.values()].sort((a, b) => a.id.localeCompare(b.id));
+  const lines = rows.length
+    ? rows.map((c) => `- \`${c.id}\` [${c.scope.join(', ')}] ${c.text}`)
+    : ['_none — no NFR has been compiled and no incident has produced a lesson._'];
+
+  const stamp = today.toISOString().slice(0, 10);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${HEADER}${REFRESHED}${stamp} -->\n\n${BEGIN}\n${lines.join('\n')}\n${END}\n`);
+  return changed;
+}
+
+/** The block stamped into a new or briefed spec, so constraints are in front of
+ *  whoever writes it rather than in a file they are trusted to have read. */
+export function renderForSpec(constraints) {
+  if (!constraints.length) return '';
+  return ['## Constraints in force', '',
+          '_Read while authoring. Generated from the knowledge layer._', '',
+          ...constraints.map((c) => `- **${c.id}** — ${c.text}`)].join('\n') + '\n';
+}

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

@@ -0,0 +1,70 @@
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { read, write, forRepos, staleness, renderForSpec } from './knowledge.mjs';
+
+let dir, path;
+beforeEach(() => { dir = mkdtempSync(join(tmpdir(), 'sdd-')); path = join(dir, 'docs', 'CONSTRAINTS.md'); });
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+const PERF = { id: 'NFR-03', scope: ['api-neelias'], text: 'stays responsive (p95 < 400ms)' };
+const GLOBAL = { id: 'NFR-07', scope: ['*'], text: 'no high findings' };
+
+describe('round trip', () => {
+  test('a constraint survives write and read', () => {
+    write(path, [PERF]);
+    assert.deepEqual(read(path), [PERF]);
+  });
+
+  test('an absent store reads as empty, not as an error', () => {
+    assert.deepEqual(read(path), []);
+    assert.equal(staleness(path), null);
+  });
+
+  test('write is an upsert and reports only real changes', () => {
+    assert.deepEqual(write(path, [PERF]), ['NFR-03']);
+    assert.deepEqual(write(path, [PERF]), []);            // a no-op says so
+    assert.deepEqual(write(path, [{ ...PERF, text: 'tightened to 200ms' }]), ['NFR-03']);
+    assert.equal(read(path).length, 1);                    // replaced, not duplicated
+  });
+
+  test('an empty store still writes a readable file', () => {
+    write(path, []);
+    assert.match(readFileSync(path, 'utf8'), /_none —/);
+  });
+});
+
+describe('scope decides what a spec inherits', () => {
+  test('estate-wide plus its own', () => {
+    write(path, [PERF, GLOBAL]);
+    assert.deepEqual(forRepos(read(path), ['api-neelias']).map((c) => c.id), ['NFR-03', 'NFR-07']);
+    assert.deepEqual(forRepos(read(path), ['neelias-mobile']).map((c) => c.id), ['NFR-07']);
+  });
+
+  test('a spec with no repos yet still inherits the estate-wide ones', () => {
+    write(path, [PERF, GLOBAL]);
+    assert.deepEqual(forRepos(read(path), []).map((c) => c.id), ['NFR-07']);
+  });
+});
+
+describe('staleness', () => {
+  test('is measured from the recorded date', () => {
+    write(path, [PERF], new Date('2026-08-01T00:00:00Z'));
+    assert.equal(staleness(path, new Date('2026-09-04T00:00:00Z')), 34);
+    assert.equal(staleness(path, new Date('2026-08-01T00:00:00Z')), 0);
+  });
+});
+
+describe('rendering into a spec', () => {
+  test('constraints are put in front of the author', () => {
+    const block = renderForSpec([PERF]);
+    assert.match(block, /## Constraints in force/);
+    assert.match(block, /\*\*NFR-03\*\*/);
+  });
+
+  test('nothing in force renders nothing at all', () => {
+    assert.equal(renderForSpec([]), '');
+  });
+});

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

@@ -0,0 +1,119 @@
+// Non-functional requirements: reading them, and compiling them into the two
+// things that actually enforce them.
+//
+// Pure Node, no dependencies. Read-only; the caller decides what to write.
+//
+// Why this exists: NFRs enter a project at the top — "the API shall be
+// performant" — and then vanish. They do not decompose into user stories, so a
+// story breakdown flattens them into prose that nothing checks. They decompose
+// into exactly two things: a standing constraint read while authoring every
+// spec, and a blocking pipeline gate. `compile` produces both or throws, so an
+// NFR cannot be admitted and then quietly lost.
+
+const TOOL_FOR = {
+  performance: 'load',
+  security: 'sast',
+  availability: 'policy',
+  compliance: 'policy',
+};
+
+export const NFR_KINDS = Object.keys(TOOL_FOR);
+const OPERATORS = ['<', '<=', '>', '>=', '=='];
+
+/**
+ * An NFR without a machine-checkable threshold is a wish. Refusing it here is
+ * the whole point: a wish gets flattened into a feature spec and lost, and
+ * nobody notices until the load test that was never written would have caught it.
+ */
+export function compile(nfr) {
+  const t = nfr.threshold;
+  if (!t || !Number.isFinite(Number(t.value)) || !t.metric) {
+    throw new Error(
+      `${nfr.id} has no machine-checkable threshold, so it cannot become a pipeline gate. ` +
+      `Give it metric/operator/value, or drop it — an NFR nothing can fail is not a requirement.`);
+  }
+  if (!OPERATORS.includes(t.operator)) {
+    throw new Error(`${nfr.id} has operator "${t.operator}"; expected one of ${OPERATORS.join(' ')}`);
+  }
+  const tool = TOOL_FOR[nfr.kind];
+  if (!tool) {
+    throw new Error(`${nfr.id} has kind "${nfr.kind}"; expected one of ${NFR_KINDS.join(', ')}`);
+  }
+
+  const assertion = `${t.metric} ${t.operator} ${t.value}${t.unit ?? ''}`;
+  return {
+    constraint: { id: nfr.id, scope: nfr.appliesTo?.length ? nfr.appliesTo : ['*'],
+                  text: `${nfr.statement} (${assertion})` },
+    gate: { nfr: nfr.id, tool, metric: t.metric, operator: t.operator,
+            value: Number(t.value), unit: t.unit ?? '', assertion, blocking: true },
+  };
+}
+
+/**
+ * The guard that keeps this honest: an NFR id must never appear inside an
+ * acceptance criterion. That is the exact failure mode — the NFR flattened into
+ * a feature spec, where it stops being enforced and starts being a sentence.
+ */
+export function findFlattened(specs) {
+  const hits = [];
+  for (const spec of specs) {
+    for (const ac of spec.criteria ?? []) {
+      for (const id of spec.nfrs ?? []) {
+        if (ac.text.includes(id)) hits.push({ spec: spec.id, criterion: ac.id, nfr: id, text: ac.text });
+      }
+    }
+  }
+  return hits;
+}
+
+/** The gate block a pipeline consumes. */
+export const toPipelineYaml = (gates) =>
+  gates.length === 0
+    ? '# no NFR gates compiled\n'
+    : gates.map((g) =>
+        `- gate: ${g.nfr}\n  tool: ${g.tool}\n  assert: ${g.assertion}\n  blocking: true`).join('\n');
+
+// --- reading -----------------------------------------------------------------
+// A markdown table, to match docs/ESTATE.md — this file is read by people during
+// spec review far more often than by this code, and a format only a machine can
+// read becomes a format nobody checks.
+
+const ROW = /^\|(.+)\|\s*$/;
+const SEP = /^\|[\s:|-]+\|\s*$/;
+const clean = (v) => (v ?? '').replace(/[`*]/g, '').trim();
+const PLACEHOLDER = /^(<.*>|_TBD_|—|-|)$/;
+
+export function parseNfrMarkdown(text) {
+  const out = [];
+  let header = null;
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (SEP.test(trimmed)) continue;
+    const m = ROW.exec(trimmed);
+    if (!m) { header = null; continue; }
+    const cells = m[1].split('|').map(clean);
+
+    if (!header) {
+      const lower = cells.map((c) => c.toLowerCase());
+      header = lower.includes('nfr') && lower.some((c) => c.includes('metric')) ? lower : null;
+      continue;
+    }
+
+    const at = (name) => {
+      const i = header.findIndex((h) => h.includes(name));
+      return i === -1 ? '' : (cells[i] ?? '');
+    };
+    const id = at('nfr');
+    if (!id || PLACEHOLDER.test(id)) continue;
+
+    out.push({
+      id,
+      kind: (at('kind') || 'compliance').toLowerCase(),
+      statement: at('statement'),
+      threshold: { metric: at('metric'), operator: at('op') || '<',
+                   value: Number(at('value')), unit: at('unit') },
+      appliesTo: at('applies').split(',').map(clean).filter((v) => v && !PLACEHOLDER.test(v)),
+    });
+  }
+  return out;
+}

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

@@ -0,0 +1,89 @@
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { compile, findFlattened, toPipelineYaml, parseNfrMarkdown, NFR_KINDS } from './nfr.mjs';
+
+const PERF = { id: 'NFR-03', kind: 'performance', statement: 'stays responsive',
+               threshold: { metric: 'p95_latency', operator: '<', value: 400, unit: 'ms' },
+               appliesTo: ['api-neelias'] };
+
+describe('compiling an NFR', () => {
+  test('produces both halves — a constraint and a gate', () => {
+    const { constraint, gate } = compile(PERF);
+    assert.match(constraint.text, /p95_latency < 400ms/);
+    assert.deepEqual(constraint.scope, ['api-neelias']);
+    assert.equal(gate.tool, 'load');
+    assert.equal(gate.blocking, true);
+  });
+
+  test('each kind maps to the tool that can actually enforce it', () => {
+    assert.equal(compile({ ...PERF, kind: 'security', threshold: { metric: 'x', operator: '==', value: 0 } }).gate.tool, 'sast');
+    assert.equal(compile({ ...PERF, kind: 'availability', threshold: { metric: 'x', operator: '>=', value: 99 } }).gate.tool, 'policy');
+    assert.deepEqual(NFR_KINDS.sort(), ['availability', 'compliance', 'performance', 'security']);
+  });
+
+  test('no threshold is refused, not silently accepted', () => {
+    // A wish gets flattened into a feature spec and lost.
+    assert.throws(() => compile({ ...PERF, threshold: null }), /no machine-checkable threshold/);
+    assert.throws(() => compile({ ...PERF, threshold: { metric: 'x', operator: '<', value: 'soon' } }), /threshold/);
+  });
+
+  test('a nonsense operator or kind is refused with what was expected', () => {
+    assert.throws(() => compile({ ...PERF, threshold: { ...PERF.threshold, operator: '~' } }), /expected one of/);
+    assert.throws(() => compile({ ...PERF, kind: 'vibes' }), /expected one of/);
+  });
+
+  test('an NFR with no scope applies everywhere rather than nowhere', () => {
+    assert.deepEqual(compile({ ...PERF, appliesTo: [] }).constraint.scope, ['*']);
+  });
+});
+
+describe('the flattening guard', () => {
+  test('an NFR id inside an acceptance criterion is caught', () => {
+    // The exact failure mode: the NFR stops being enforced and becomes a sentence.
+    const hits = findFlattened([{ id: '0031', nfrs: ['NFR-03'],
+      criteria: [{ id: 'AC-1', text: 'The system satisfies NFR-03 under load.' }] }]);
+    assert.equal(hits.length, 1);
+    assert.equal(hits[0].nfr, 'NFR-03');
+  });
+
+  test('an ordinary criterion is not a false positive', () => {
+    assert.equal(findFlattened([{ id: '0031', nfrs: ['NFR-03'],
+      criteria: [{ id: 'AC-1', text: 'A partial capture holds the remainder.' }] }]).length, 0);
+  });
+});
+
+describe('reading the NFR table', () => {
+  const MD = `| NFR | Kind | Statement | Metric | Op | Value | Unit | Applies to |
+|-----|------|-----------|--------|----|-------|------|------------|
+| NFR-03 | performance | stays responsive | p95_latency | < | 400 | ms | api-neelias |
+| NFR-07 | security | no high findings | sast_high | == | 0 |  | * |
+| <NFR-id> | performance | <statement> | x | < | 1 |  | _TBD_ |`;
+
+  test('rows parse into compilable NFRs', () => {
+    const nfrs = parseNfrMarkdown(MD);
+    assert.deepEqual(nfrs.map((n) => n.id), ['NFR-03', 'NFR-07']);
+    assert.equal(nfrs[0].threshold.value, 400);
+    assert.deepEqual(nfrs[0].appliesTo, ['api-neelias']);
+    assert.doesNotThrow(() => compile(nfrs[0]));
+  });
+
+  test('unfilled template rows are skipped', () => {
+    assert.ok(!parseNfrMarkdown(MD).some((n) => n.id.startsWith('<')));
+  });
+
+  test('the separator row does not end the table', () => {
+    assert.equal(parseNfrMarkdown(MD).length, 2);
+  });
+});
+
+describe('pipeline output', () => {
+  test('gates render as blocking yaml', () => {
+    const yaml = toPipelineYaml([compile(PERF).gate]);
+    assert.match(yaml, /- gate: NFR-03/);
+    assert.match(yaml, /blocking: true/);
+  });
+
+  test('no gates says so rather than emitting an empty block', () => {
+    assert.match(toPipelineYaml([]), /no NFR gates compiled/);
+  });
+});

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

@@ -0,0 +1,114 @@
+// The branch policy that makes a pipeline into a gate.
+//
+// A build that runs and reports changes nothing. The load-bearing artifact is
+// the POLICY: build validation, scoped to the protected branch, blocking.
+//
+// The audit half matters more than the install half. A gate quietly demoted to
+// advisory — to unblock a release, reasonably, on a Friday — is how this kind of
+// governance dies: nothing breaks, no test fails, and the first anyone notices
+// is an audit months later.
+//
+// Pure Node, no dependencies. Every call goes through an injected transport.
+
+import { basicAuth, request } from './http.mjs';
+
+/** ADO's well-known policy type for "Build validation". */
+export const BUILD_VALIDATION_TYPE = '0609b952-1397-4640-95ec-e00a01b2c241';
+
+export function adoPolicy({ org, project, pat, apiVersion = '7.1', transport = request }) {
+  const base = `https://dev.azure.com/${org}/${encodeURIComponent(project)}/_apis`;
+  const headers = { Authorization: basicAuth('', pat) };
+
+  return {
+    tool: 'ado-repos',
+
+    async install(repo, branch, buildRef) {
+      await transport(`${base}/policy/configurations?api-version=${apiVersion}`, {
+        method: 'POST', headers,
+        body: {
+          isEnabled: true,
+          isBlocking: true,          // the whole point; there is no flag to turn this off here
+          type: { id: BUILD_VALIDATION_TYPE },
+          settings: {
+            buildDefinitionId: /^\d+$/.test(String(buildRef)) ? Number(buildRef) : buildRef,
+            displayName: 'SDD spec gate',
+            manualQueueOnly: false,
+            queueOnSourceUpdateOnly: true,
+            validDuration: 720,
+            scope: [{ refName: `refs/heads/${branch}`, matchKind: 'Exact', repositoryId: repo }],
+          },
+        },
+      });
+      return { repo, branch, tool: 'ado-repos', present: true, blocking: true, findings: [] };
+    },
+
+    async audit(repo, branch) {
+      const res = await transport(
+        `${base}/policy/configurations?repositoryId=${encodeURIComponent(repo)}` +
+        `&refName=refs/heads/${branch}&api-version=${apiVersion}`, { headers });
+
+      const builds = (res.value ?? []).filter((c) => c.type?.id === BUILD_VALIDATION_TYPE);
+      if (!builds.length) {
+        return { repo, branch, tool: 'ado-repos', present: false, blocking: false,
+                 findings: [{ severity: 'blocker', message: `no build-validation policy on refs/heads/${branch}` }] };
+      }
+
+      const p = builds[0];
+      const s = p.settings ?? {};
+      const findings = [];
+      if (!p.isEnabled) findings.push({ severity: 'blocker', message: 'policy exists but is disabled' });
+      if (!p.isBlocking) findings.push({ severity: 'blocker', message: 'policy is advisory — the build reports but cannot fail the merge' });
+      if (s.manualQueueOnly) findings.push({ severity: 'blocker', message: 'manualQueueOnly is set — the gate only runs if someone remembers' });
+      if (s.queueOnSourceUpdateOnly === false) findings.push({ severity: 'warning', message: 'does not re-run on source update; a later push is ungated' });
+      if (builds.length > 1) findings.push({ severity: 'warning', message: `${builds.length} build policies on this branch — which one is the gate?` });
+
+      return { repo, branch, tool: 'ado-repos', present: true,
+               blocking: Boolean(p.isBlocking && p.isEnabled), findings };
+    },
+  };
+}
+
+export function githubPolicy({ owner, token, apiBase = 'https://api.github.com', transport = request }) {
+  const headers = { Authorization: `Bearer ${token}`, 'X-GitHub-Api-Version': '2022-11-28' };
+  const url = (repo, branch) => `${apiBase}/repos/${owner}/${repo}/branches/${encodeURIComponent(branch)}/protection`;
+
+  return {
+    tool: 'github',
+
+    async install(repo, branch, buildRef) {
+      await transport(url(repo, branch), { method: 'PUT', headers, body: {
+        required_status_checks: { strict: true, contexts: [buildRef] },
+        enforce_admins: true,
+        required_pull_request_reviews: { required_approving_review_count: 1 },
+        restrictions: null,
+      } });
+      return { repo, branch, tool: 'github', present: true, blocking: true, findings: [] };
+    },
+
+    async audit(repo, branch) {
+      const raw = await transport(url(repo, branch), { headers });
+      const contexts = raw.required_status_checks?.contexts ?? [];
+      if (!contexts.length) {
+        return { repo, branch, tool: 'github', present: false, blocking: false,
+                 findings: [{ severity: 'blocker', message: `no required status check on ${branch}` }] };
+      }
+      const findings = [];
+      if (!raw.required_status_checks?.strict) {
+        findings.push({ severity: 'warning', message: 'strict is off — a stale branch can merge without re-running the gate' });
+      }
+      // On GitHub an admin bypass is the equivalent of an advisory policy.
+      if (!raw.enforce_admins?.enabled) {
+        findings.push({ severity: 'blocker', message: 'enforce_admins is off — administrators can merge past the gate' });
+      }
+      return { repo, branch, tool: 'github', present: true,
+               blocking: !findings.some((f) => f.severity === 'blocker'), findings };
+    },
+  };
+}
+
+export const auditOk = (a) => a.present && a.blocking && !a.findings.some((f) => f.severity === 'blocker');
+
+export const auditSummary = (a) =>
+  !a.present ? 'no spec gate on this branch'
+  : !a.blocking ? 'spec gate is ADVISORY — it cannot fail the merge, so it is not a gate'
+  : 'spec gate present and blocking';