@mlmcps/ml-specs 1.0.0

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

@@ -0,0 +1,69 @@
+// Tests for the shared spec parser. Run with: node --test ml-specs/scripts/lib/
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { parseCriteria, splitCell, resolveStatus, LIFECYCLE } from './specs.mjs';
+
+describe('acceptance criteria', () => {
+  test('the template style parses', () => {
+    const acs = parseCriteria('- [ ] **AC1** — Given a key, when replayed, then the original returns.');
+    assert.equal(acs.length, 1);
+    assert.deepEqual(acs[0], { id: 'AC-1', ordinal: 1, text: 'Given a key, when replayed, then the original returns.', checked: false });
+  });
+
+  test('the hand-written style parses too', () => {
+    const acs = parseCriteria('- [x] AC-2: plain style, colon separator');
+    assert.equal(acs[0].id, 'AC-2');
+    assert.equal(acs[0].checked, true);
+  });
+
+  test('criteria come back in ordinal order regardless of file order', () => {
+    const acs = parseCriteria('- [ ] **AC3** — third\n- [ ] **AC1** — first\n- [ ] **AC2** — second');
+    assert.deepEqual(acs.map((a) => a.ordinal), [1, 2, 3]);
+  });
+
+  test('a plain checklist that is not a criterion is ignored', () => {
+    assert.equal(parseCriteria('- [ ] buy milk\n- [x] deploy').length, 0);
+  });
+});
+
+describe('header cells', () => {
+  test('comma and slash separated values split', () => {
+    assert.deepEqual(splitCell('api-neelias, neelias-pos'), ['api-neelias', 'neelias-pos']);
+    assert.deepEqual(splitCell('NFR-03 / NFR-07'), ['NFR-03', 'NFR-07']);
+  });
+
+  test('unfilled template placeholders read as absent', () => {
+    // Treated as a real repo, `<repo or service name>` would fan a pull request
+    // out to a repository that does not exist.
+    assert.deepEqual(splitCell('<repo or service name>'), []);
+    assert.deepEqual(splitCell('_TBD_'), []);
+    assert.deepEqual(splitCell('—'), []);
+    assert.deepEqual(splitCell(null), []);
+  });
+
+  test('backticks and bold are stripped', () => {
+    assert.deepEqual(splitCell('`api-neelias`, **neelias-pos**'), ['api-neelias', 'neelias-pos']);
+  });
+});
+
+describe('status resolution is unchanged by the new fields', () => {
+  test('a canonical status resolves cleanly', () => {
+    const r = resolveStatus('Approved');
+    assert.equal(r.status, 'Approved');
+    assert.equal(r.canonical, true);
+  });
+
+  test('prose leading with a stage word is a claim', () => {
+    assert.equal(resolveStatus('Implemented (2026-07-07) — all 16 ACs met').status, 'Implemented');
+  });
+
+  test('a stage word buried mid-sentence is discussion, not a claim', () => {
+    const r = resolveStatus('Phase 1 done, not yet verified by QA');
+    assert.equal(r.leading, false);
+  });
+
+  test('the lifecycle is the five stages the toolkit ships', () => {
+    assert.deepEqual(LIFECYCLE, ['Draft', 'Approved', 'Implemented', 'Verified', 'Archived']);
+  });
+});

package/ml-specs/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/ml-specs/scripts/lib/trace.test.mjs

@@ -0,0 +1,110 @@
+// Tests for the ID spine. Run with: node --test ml-specs/scripts/lib/
+// Pure Node's built-in runner — no dependencies, consistent with everything else here.
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  slugify, specId, branchName, prTitle, testCaseId,
+  keyFrom, buildChain, verifyChain, renderChain,
+} from './trace.mjs';
+
+const spec = {
+  id: '0031',
+  title: 'Idempotent refund submission',
+  file: 'specs/0031-idempotent-refund-submission.md',
+  ticket: 'PAY-2204',
+  status: 'Approved',
+  branch: 'feat/0031-idempotent-refund-submission',
+  criteria: [{ id: 'AC-1', ordinal: 1 }, { id: 'AC-2', ordinal: 2 }],
+};
+
+describe('derivation and recovery are symmetric', () => {
+  test('every id a function produces, a parser recovers', () => {
+    assert.equal(branchName('0031', 'Idempotent refund submission'), 'feat/0031-idempotent-refund-submission');
+    assert.equal(prTitle('0031', 'X'), '[SPEC-0031] X');
+    assert.equal(testCaseId('0031', 3), 'TC-0031.3');
+
+    assert.equal(keyFrom('branch', branchName('0031', 'X')), '0031');
+    assert.equal(keyFrom('prTitle', prTitle('0031', 'X')), '0031');
+    assert.equal(keyFrom('testCase', testCaseId('0031', 3)), '0031');
+    assert.equal(keyFrom('specId', specId('0031')), '0031');
+  });
+
+  test('a suffixed spec id is a different spec, not a clash', () => {
+    // Matches lib/specs.mjs: 0165 and 0165b coexist.
+    assert.equal(keyFrom('branch', 'feat/0165b-follow-up'), '0165b');
+    assert.notEqual(keyFrom('branch', 'feat/0165b-x'), keyFrom('branch', 'feat/0165-x'));
+  });
+
+  test('three-digit ids still read, so existing repos are not orphaned', () => {
+    assert.equal(keyFrom('branch', 'feat/023-legacy'), '023');
+    assert.equal(keyFrom('specFile', 'specs/023-legacy.md'), '023');
+    assert.equal(keyFrom('specFile', 'specs/archive/0023-old.md'), '0023');
+  });
+
+  test('an artifact carrying no key returns null rather than guessing', () => {
+    assert.equal(keyFrom('branch', 'feature/payment-thing'), null);
+    assert.equal(keyFrom('prTitle', 'fix the thing'), null);
+    assert.equal(keyFrom('testCase', 'TC-abc.1'), null);
+  });
+
+  test('slugify is bounded and never trails a hyphen', () => {
+    assert.equal(slugify('Payment hold — on partial capture!'), 'payment-hold-on-partial-capture');
+    const long = slugify('x'.repeat(80));
+    assert.ok(long.length <= 48);
+    assert.ok(!long.endsWith('-'));
+  });
+
+  test('an unknown artifact kind is a programming error, not a silent null', () => {
+    assert.throws(() => keyFrom('nonsense', 'x'), /unknown artifact kind/);
+  });
+});
+
+describe('chain verification', () => {
+  test('a well-formed spec produces an intact chain', () => {
+    const report = verifyChain(buildChain(spec));
+    assert.equal(report.ok, true);
+    assert.equal(report.broken.length, 0);
+  });
+
+  test('the hand-typed ticket is reported as unverifiable, not as passing', () => {
+    // Counting it as passing would make the whole report a lie.
+    const report = verifyChain(buildChain(spec));
+    assert.deepEqual(report.unverifiable.map((l) => l.kind), ['ticket']);
+  });
+
+  test('a branch carrying the wrong key is caught with the key it does carry', () => {
+    const report = verifyChain(buildChain({ ...spec, branch: 'feat/0019-wrong' }));
+    assert.equal(report.ok, false);
+    assert.equal(report.broken[0].reason, 'wrong-key');
+    assert.equal(report.broken[0].found, '0019');
+  });
+
+  test('a branch with no key at all is caught as missing', () => {
+    const report = verifyChain(buildChain({ ...spec, branch: 'hotfix-urgent' }));
+    assert.equal(report.broken[0].reason, 'missing-key');
+    assert.equal(report.broken[0].found, null);
+  });
+
+  test('a Draft spec has no test cases in its chain yet', () => {
+    const chain = buildChain({ ...spec, status: 'Draft' });
+    assert.ok(!chain.links.some((l) => l.kind === 'testCase'));
+  });
+
+  test('an approved spec pairs every criterion with a test case', () => {
+    const cases = buildChain(spec).links.filter((l) => l.kind === 'testCase');
+    assert.deepEqual(cases.map((l) => l.ref), ['TC-0031.1', 'TC-0031.2']);
+    assert.deepEqual(cases.map((l) => l.from), ['AC-1', 'AC-2']);
+  });
+
+  test('a spec with no recorded branch falls back to the derived one', () => {
+    const chain = buildChain({ ...spec, branch: null });
+    const branch = chain.links.find((l) => l.kind === 'branch');
+    assert.equal(branch.origin, 'derived');
+    assert.equal(verifyChain(chain).ok, true);
+  });
+
+  test('renderChain marks what it could not check', () => {
+    assert.match(renderChain(buildChain(spec)), /PAY-2204 \(unverified\)/);
+  });
+});

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