@mlmcps/ml-specs 1.0.0

package/ml-specs/scripts/tracker-sync.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// Governed sync between a spec and its work item in Azure DevOps or Jira.
+//
+//   node tracker-sync.mjs 0031 --dry-run       # print the exact requests, send nothing
+//   node tracker-sync.mjs 0031
+//   node tracker-sync.mjs 0031 --json
+//
+// Credentials from the environment: ADO_ORG/ADO_PROJECT/ADO_PAT, or
+// JIRA_BASE_URL/JIRA_EMAIL/JIRA_API_TOKEN/JIRA_PROJECT_KEY with SDD_PM_TOOL=jira.
+//
+// Exit code 1 if the link is broken or a write is refused.
+//
+// Why this exists: the spec lives in the repo and the work item lives in the
+// tracker, and both can hold a title, a status and a list of criteria. Two
+// stores for one truth diverge silently. So exactly one system may write each
+// field — the spec owns the CONTRACT, the tracker owns the SCHEDULE — and an
+// attempt to write the other's field is refused rather than winning.
+//
+// Test cases are pushed as a DERIVATION of approved criteria, never authored
+// beside them: that is what turns QA from an author into an auditor of something
+// the Product Owner already signed off.
+
+import { listSpecs } from './lib/specs.mjs';
+import { adoTracker, jiraTracker, governedWriter, readOnly } from './lib/tracker.mjs';
+import { testCaseId } from './lib/trace.mjs';
+import { args, colours, transportFor, trackerConfig, printTranscript } from './lib/cli.mjs';
+
+const { positional, json, dryRun, root } = args();
+const [target] = positional;
+const C = colours(process.stdout.isTTY && !json);
+
+if (!target) { console.error('usage: tracker-sync.mjs <spec-id> [--dry-run] [--json]'); process.exit(1); }
+
+const spec = listSpecs(root).find((s) => s.id === target || s.file.endsWith(target));
+if (!spec) { console.error(`no spec matching "${target}" under ${root}`); process.exit(1); }
+
+const transport = transportFor(dryRun);
+const { tool, config } = trackerConfig(transport);
+const tracker = tool === 'jira' ? jiraTracker(config) : adoTracker(config);
+const writer = governedWriter(tracker);
+
+if (dryRun && !json) console.log(`${C.bold('dry run')} ${C.dim('— nothing is sent')}\n`);
+
+const out = { spec: spec.id, tool, link: null, pushed: 0, refused: [] };
+
+// --- pull: does the tracker still point at this spec? -----------------------
+if (!spec.ticket) {
+  out.link = { ok: false, detail: `spec ${spec.id} has no Ticket in its header table` };
+} else {
+  const item = await readOnly(tracker).getWorkItem(spec.ticket);
+  out.link = !item
+    ? { ok: false, detail: `work item ${spec.ticket} not found in ${tool}` }
+    : item.specKey && item.specKey !== spec.id
+      ? { ok: false, detail: `work item ${item.id} carries SPEC-${item.specKey}, expected ${spec.id}` }
+      : { ok: true, detail: `${spec.id} <-> ${tool}#${item.id}`, status: item.status };
+}
+
+// --- push: test cases, derived only from approved criteria ------------------
+if (!spec.status || spec.status === 'Draft') {
+  out.refused.push('spec is Draft — nothing crosses the approval gate');
+} else if (!(spec.criteria ?? []).length) {
+  out.refused.push('no acceptance criteria to derive test cases from');
+} else if (out.link?.ok) {
+  const cases = spec.criteria.map((ac) => ({
+    id: testCaseId(spec.id, ac.ordinal),
+    title: ac.text,
+    from: ac.id,
+    specKey: spec.id,
+    steps: [
+      `Set up the preconditions described by ${spec.id} "${spec.title}".`,
+      `Exercise the behaviour: ${ac.text}`,
+      `Assert the criterion holds, and record the result against ${ac.id}.`,
+    ],
+  }));
+  try { out.pushed = (await writer.pushTestCases(spec, cases)).length; }
+  catch (e) { out.refused.push(e.message); }
+}
+
+const ok = Boolean(out.link?.ok) && out.refused.length === 0;
+
+if (json) {
+  console.log(JSON.stringify({ ...out, ok }, null, 2));
+} else {
+  console.log(`  ${out.link.ok ? C.green('link  ') : C.red('link  ')} ${out.link.detail}`);
+  if (out.pushed) console.log(`  ${C.green('push  ')} ${out.pushed} test case(s) derived from acceptance criteria`);
+  for (const r of out.refused) console.log(`  ${C.dim(`skip   ${r}`)}`);
+  console.log(`\n  ${C.dim('the spec owns the contract; the tracker owns status, assignee and sprint')}`);
+  printTranscript(transport, C);
+}
+
+process.exit(ok ? 0 : 1);

package/ml-specs/skills/knowledge-retrieval/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: knowledge-retrieval
+description: How to navigate a repo's learned knowledge layer (CLAUDE.md, docs/PATTERNS.md, docs/ARCHITECTURE.md, docs/ESTATE.md) without blowing up context — sharded architecture docs, the 1-hop dependency closure for interlinked modules, and designing a change that crosses a module or service boundary. Load when the repo's docs are sharded (docs/architecture/*.md), when a task touches a shared event/API/type/table, or when a change spans more than one module or service.
+---
+
+# Retrieving from a sharded / interlinked knowledge layer
+
+The top-level ladder (read `CLAUDE.md` → `docs/PATTERNS.md` before writing code → `docs/ARCHITECTURE.md`
+to find things → grep last) lives in the repo's `CLAUDE.md`, because it has to be known *before*
+you know you need it. This skill is the part that only matters sometimes, so it loads only then.
+
+The governing rule: **the cost of a task is the context you load, and most of it is loaded by
+reflex.** Every doc you open should answer a question the task actually asked.
+
+## Sharded docs (large apps and monorepos)
+
+When a repo is big, `docs/ARCHITECTURE.md` is not the map — it's a **router**: a blurb plus a
+Structure table whose rows link to `docs/architecture/<module>.md` shards (≤~150 lines each), with
+`docs/patterns/<module>.md` where a module's conventions genuinely differ.
+
+Read, in order:
+1. The **router** — always. It's small and tells you which shard you need.
+2. The **one shard** for the module you're touching.
+3. Nothing else. Never load shards for modules the task doesn't involve — that's the whole reason
+   the docs were sharded.
+
+If a `docs/architecture/_core.md` exists, it holds contracts shared widely enough to be worth
+always reading for cross-cutting work. Read it for cross-cutting work only, not for a change that
+sits inside one module.
+
+## The 1-hop dependency closure (interlinked modules)
+
+Modules have edges, not just contents. A change that looks local is only local until it touches a
+contract someone else depends on.
+
+Each shard carries a `## Depends on / Used by` header; the router carries a **module contract
+index** (shared event / API / type / table → producers and consumers). Use them like this:
+
+1. Open the target shard. Read its `Depends on / Used by`.
+2. Does the change touch anything named there — a shared event, an API the neighbor calls, a type
+   or table you don't solely own?
+   - **No** → you're done. Load nothing else. This is the common case; don't go looking for ripple
+     that isn't there.
+   - **Yes** → for each affected neighbor, load **only that neighbor's contract section** — not its
+     whole shard. That is the 1-hop closure, and it is the whole budget. Do not follow the
+     neighbor's own edges to a second hop unless the change provably reaches that far.
+3. Design against **both sides** of every contract you touched, and write both sides into the
+   spec's §4 contracts and §7 rollout.
+
+## Crossing a service boundary
+
+Same shape, one level up. If the task touches an event, a cross-service HTTP/RPC call, or shared
+data, read `docs/ESTATE.md` — the contract index generated by `/repo-estate`. Find the edge, then
+open the peer's summary doc.
+
+Then be careful about three things the in-repo docs cannot tell you:
+
+- **The peer's side may be `(inferred)`.** The estate index marks rows that were never confirmed
+  against the peer's real code. An inferred contract is a hypothesis — verify it in the peer repo
+  before designing against it, or say in the spec that you didn't.
+- **Deploy order is part of the design.** Two services that must change together need a sequence
+  that is safe at every intermediate step (usually: additive change to the consumer first, then the
+  producer, then remove the old path). That belongs in the spec's §7, not in the PR description.
+- **Backward compatibility is the default assumption.** Something you don't control is already
+  calling the thing you're changing. If the change isn't additive, the spec has to say what happens
+  to in-flight callers and old messages.
+
+## Token discipline (applies throughout)
+
+- Prefer `file:line` references over pasting code.
+- Once a summary tells you where to look, read that **range**, not the whole file.
+- Don't re-read a doc already in context.
+- Don't open a doc to confirm something you already know from the code you just read.
+- If a doc contradicts the code, the **code wins** — and the doc is stale: say so, and recommend
+  `/repo-refresh`. Don't quietly work around a wrong doc and leave it wrong for the next task.

package/ml-specs/templates/CLAUDE.fragment.md

@@ -0,0 +1,87 @@
+<!--
+  Shared CLAUDE.md sections from the ml-specs plugin — merge into each service's CLAUDE.md.
+  Loaded on EVERY session in every repo that adopts it, so every line is paid for continuously:
+  keep only what is specific to this toolkit or this project. The full coding contract lives in
+  the plugin's `coder` agent, which carries it when it runs; don't restate it here.
+-->
+
+## Knowledge layer — indexing, retrieval, summaries
+
+These docs load into context, so load the **least** that answers the task, in this order:
+
+0. **`CLAUDE.md` (this file)** — always in context, so it stays a thin index: stack one-liner,
+   build/test/lint commands, and links. It points; it never inlines.
+1. **`docs/PATTERNS.md`** — when writing/changing code (skip for Q&A or trivial edits). New code
+   MUST match it. In a monorepo, read only the relevant package's section.
+2. **`docs/ARCHITECTURE.md`** — when you need to find where something lives. Read the relevant
+   section, not the file. If **sharded**, it's a router: read it, then only your module's shard.
+3. **`docs/ESTATE.md`** — only when the task touches an event or a cross-service call. Generated
+   by `/repo-estate`; don't hand-maintain it.
+4. **Agentic retrieval last** — `Explore` / grep / glob, for exact lines only.
+
+**Standards are a different axis from these docs, not another rung on the ladder.**
+`docs/PATTERNS.md` **describes** how this repo happens to write code; the architecture standards
+(`.mlskills.json`, the `ml-skills` MCP server, `npx @mlmcps/ml-skills`) **prescribe** how it must.
+Read the relevant standard before writing code the standard governs — an API contract, a migration,
+a Dockerfile, anything touching auth or personal data. When a standard and the local code
+disagree, the **code** is what is wrong: flag the divergence rather than copying local style. That
+is the single case where "match the surrounding code" does not apply.
+
+**Token discipline:** cite `file:line` rather than pasting code; read file *ranges* once a summary
+says where to look; never re-read a doc already in context.
+
+Sharded docs, interlinked modules, or a change crossing a module/service boundary? Load the
+ml-specs **`knowledge-retrieval`** skill for that procedure — and not otherwise.
+
+**Keep summaries fresh** (`/repo-refresh`) after changing endpoints, listeners, external clients, or
+data-access flavor. A stale summary is worse than none.
+
+## Working agreement (coding-agent contract)
+
+The full contract lives in the plugin's `coder` agent. What binds *all* work here:
+
+1. **Inspect before assuming** structure or stack — the code is the source of truth and overrides
+   any default you'd otherwise reach for.
+2. **Smallest correct change**, matching the surrounding file's naming, layering, error handling
+   and tests. Reuse what's there; justify any new dependency or abstraction.
+3. **ASK rather than guess on contracts** — API shape, data model or migration, error/status codes,
+   scope boundary, compatibility. A guessed contract costs more to undo than to ask about.
+
+**Quality gates (run this repo's real commands — never invent them):** test (unit + integration +
+functional/E2E), lint, and typecheck, filled in below; final acceptance runs the full suite end to
+end. Schema changes ship as **migrations** or schema/index updates, never hand edits. Secrets come
+from env.
+
+<!-- /repo-init fills the real commands for this repo, e.g.:
+- Test: `npm test` / `mvn test` / `pytest` …
+- Lint/format: `npm run lint` / `./gradlew spotlessCheck` …
+- Typecheck: `tsc --noEmit` … -->
+
+## Spec-driven development
+
+Non-trivial changes start with a reviewable spec, not code. See `specs/README.md`. The loop:
+`/spec <ticket>` → human reviews → `/spec-advance … Approved` → `/spec-build` (test-first, one
+functional/E2E test per user-facing criterion) → `/spec-verify` (adversarial + full suite green,
+§6.1) → `/code-review` → `/spec-advance … Verified` → `/pr` → merge → `/spec-advance … Archived`.
+
+Status is only ever written by `/spec-advance`, which refuses a transition whose evidence isn't
+there. `/repo-status` shows the board; `/repo-doctor` flags statuses the repo can't back up.
+
+Anything not in the approved spec is out of scope — update the spec first. Trivial one-line fixes
+are exempt: `/code` for those, `/spec` when a change touches an API, data model, event, or several
+files. (`/code-review` and `/security-review` are built-in Claude Code commands.)
+
+## Git & PR workflow
+
+- **Branch** off the default branch; never commit straight to it. Follow the repo's existing branch
+  naming (e.g. `feature/TICKET-slug`). Commits are small, focused, present-tense imperative, and
+  keep the spec in the same branch/PR as its implementation.
+- **Before a PR:** quality gates pass, `/code-review` is clean, every acceptance criterion has a
+  passing test. Don't commit secrets, generated artifacts, or unrelated reformatting.
+- **No AI attribution anywhere in the history.** Commit messages, commit trailers, PR titles and
+  PR bodies name the humans who own the change and nothing else. Never add a `Co-Authored-By:`
+  line for an assistant, a "Generated with"/"Made with" line, a model or vendor name, or a
+  tool badge or emoji. A `Co-Authored-By:` trailer is only ever a real teammate. This holds for
+  every commit on the branch, not just the last one — a squash merge aggregates trailers from
+  all of them, so one stray line resurfaces on the merge commit.
+- Only commit or push when the human asks; surface the diff for review first.

package/ml-specs/templates/ci/azure-pipelines-spec-gate.yml

@@ -0,0 +1,64 @@
+# Spec gate for Azure DevOps — seeded by /repo-init (ml-specs).
+#
+# Wire this as a BUILD VALIDATION POLICY on the target branch with "Block merge
+# when the build fails" enabled. A pipeline that runs and reports changes
+# nothing: the gate is the policy, not the build.
+#
+#   node scripts/branch-policy.mjs install <repo> --dry-run   # read the request first
+#   node scripts/branch-policy.mjs install <repo>
+#   node scripts/branch-policy.mjs audit <repo>               # is it still blocking?
+#
+# Every check below is deterministic — no LLM call, no API key, no network.
+
+trigger: none
+pr:
+  branches:
+    include: [main]
+
+pool:
+  vmImage: ubuntu-latest
+
+steps:
+  - task: NodeTool@0
+    displayName: Node 20
+    inputs:
+      versionSpec: '20.x'
+
+  - script: |
+      set -e
+      BRANCH="$(System.PullRequest.SourceBranch)"
+      BRANCH="${BRANCH#refs/heads/}"
+      if ! echo "$BRANCH" | grep -Eq '^(feat|fix|chore)/[0-9]{4}[a-z]?-'; then
+        echo "##vso[task.logissue type=error]branch '$BRANCH' carries no spec number. Expected feat/NNNN-slug."
+        exit 1
+      fi
+      ID=$(echo "$BRANCH" | sed -E 's#^[a-z]+/([0-9]{4}[a-z]?)-.*#\1#')
+      echo "##vso[task.setvariable variable=SPEC_ID]$ID"
+    displayName: 'Gate: branch carries a spec key'
+
+  - script: |
+      set -e
+      FILE=$(ls specs/$(SPEC_ID)-*.md 2>/dev/null | head -1)
+      [ -z "$FILE" ] && { echo "##vso[task.logissue type=error]no spec file for $(SPEC_ID)."; exit 1; }
+      STATUS=$(grep -m1 -E '^\|\s*\*\*Status\*\*' "$FILE" | sed -E 's/.*\|\s*\*\*Status\*\*\s*\|\s*([^|]*).*/\1/' | xargs)
+      case "$STATUS" in
+        Approved|Implemented|Verified) echo "spec $(SPEC_ID) is $STATUS" ;;
+        *) echo "##vso[task.logissue type=error]spec $(SPEC_ID) is '${STATUS:-unset}', not Approved."; exit 1 ;;
+      esac
+    displayName: 'Gate: spec is approved'
+
+  - script: node scripts/spec-trace.mjs $(SPEC_ID)
+    displayName: 'Gate: trace chain intact'
+
+  - script: node scripts/nfr-compile.mjs
+    displayName: 'Gate: NFRs routed, none flattened into a story'
+
+  # Self-referential on purpose. The commonest way this stops working is someone
+  # demoting the policy to advisory — nothing breaks, no test fails, and merges
+  # quietly stop being gated. So the gate audits itself.
+  - script: node scripts/branch-policy.mjs audit $(Build.Repository.Name)
+    displayName: 'Gate: the branch policy is still blocking'
+    env:
+      ADO_ORG: $(System.TeamFoundationCollectionUri)
+      ADO_PROJECT: $(System.TeamProject)
+      ADO_PAT: $(System.AccessToken)

package/ml-specs/templates/ci/knowledge-check.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// Knowledge-layer checks — seeded into a repo by /repo-init (ml-specs).
+// Pure Node, no dependencies.
+//
+//   CLI:    node .github/scripts/knowledge-check.mjs [--base <ref>] [--warn-only] [--root <dir>]
+//   Module: import { runChecks } from './knowledge-check.mjs'   (used by the MCP server)
+//
+// This is the MECHANICAL half of /repo-doctor: the checks that need no judgment and so can
+// run in CI on every PR. It does not read code for meaning — it verifies that what the docs
+// claim about the repo is still literally true.
+//
+//   /repo-doctor  = judgment, run by a human on demand ("is this pattern still how we work?")
+//   this script  = facts, run by CI on every PR   ("does docs/PATTERNS.md:42 still exist?")
+//
+// Exit 1 on errors (a doc asserts something false). Warnings never fail the build.
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { execFileSync } from 'node:child_process';
+
+// The knowledge layer, in load order. Missing files are fine — not every repo shards.
+const DOC_FILES = ['CLAUDE.md', 'docs/PATTERNS.md', 'docs/ARCHITECTURE.md', 'docs/ESTATE.md'];
+const DOC_DIRS = ['docs/architecture', 'docs/patterns'];
+
+// A `file:line` reference is only a reference if the path looks like a real repo path.
+// Without this, "example.com:443" and "spring-boot:2.0" become false positives.
+const SOURCE_EXT = new Set([
+  'js', 'mjs', 'cjs', 'jsx', 'ts', 'tsx', 'java', 'kt', 'scala', 'py', 'go', 'rb', 'rs',
+  'cs', 'php', 'swift', 'sql', 'yml', 'yaml', 'json', 'xml', 'sh', 'md', 'tf', 'gradle',
+  'properties', 'toml', 'vue', 'svelte',
+]);
+
+const REF = /(?<![\w:/])([A-Za-z0-9_][\w./-]*\.[A-Za-z0-9]+):(\d+)(?:-(\d+))?\b/g;
+
+/**
+ * Run the knowledge-layer checks. Pure: returns findings, never logs or exits.
+ * @param {{root?: string, base?: string|null}} opts
+ */
+export function runChecks({ root = process.cwd(), base = null } = {}) {
+  const errors = [];
+  const warnings = [];
+  const err = (where, msg) => errors.push({ where, msg });
+  const warn = (where, msg) => warnings.push({ where, msg });
+
+  const abs = (p) => join(root, p);
+  const has = (p) => existsSync(abs(p));
+  const git = (...a) => {
+    try {
+      return execFileSync('git', ['-C', root, ...a], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+    } catch {
+      return '';
+    }
+  };
+
+  const docs = DOC_FILES.filter(has);
+  for (const dir of DOC_DIRS) {
+    if (!has(dir)) continue;
+    for (const f of readdirSync(abs(dir))) {
+      if (f.endsWith('.md')) docs.push(`${dir}/${f}`);
+    }
+  }
+
+  if (docs.length === 0) {
+    return { docs: [], refsChecked: 0, errors, warnings, empty: true };
+  }
+
+  const lineCount = (p) => readFileSync(abs(p), 'utf8').split('\n').length;
+  let refsChecked = 0;
+
+  for (const doc of docs) {
+    const text = readFileSync(abs(doc), 'utf8');
+
+    // 1. file:line references still resolve.
+    for (const m of text.matchAll(REF)) {
+      const [, path, startStr, endStr] = m;
+      const ext = path.split('.').pop().toLowerCase();
+      if (!path.includes('/') && !SOURCE_EXT.has(ext)) continue;
+      if (path.startsWith('http')) continue;
+
+      refsChecked++;
+      if (!has(path)) {
+        err(doc, `references ${path}:${startStr}, but ${path} does not exist`);
+        continue;
+      }
+      const total = lineCount(path);
+      const line = Number(endStr || startStr);
+      if (line > total) {
+        err(doc, `references ${path}:${startStr}${endStr ? '-' + endStr : ''}, but that file is only ${total} lines`);
+      }
+    }
+
+    // 2. Relative markdown links resolve (router → shard is the one that breaks silently).
+    for (const m of text.matchAll(/\[[^\]]*\]\(([^)\s]+)\)/g)) {
+      const href = m[1];
+      if (/^(https?:|mailto:|#)/.test(href)) continue;
+      if (!existsSync(join(dirname(abs(doc)), href.split('#')[0]))) {
+        err(doc, `broken link: ${href}`);
+      }
+    }
+
+    // 3. Budget. These load into context on every task; bloat is a real cost, not a style nit.
+    const lines = text.split('\n').length;
+    const budget = doc === 'CLAUDE.md' ? 200 : 250;
+    if (lines > budget) {
+      warn(doc, `${lines} lines, over the ~${budget}-line budget — trim it (/repo-refresh prunes)`);
+    }
+  }
+
+  // 4. Every shard is reachable from the router, and vice versa.
+  if (has('docs/ARCHITECTURE.md') && has('docs/architecture')) {
+    const router = readFileSync(abs('docs/ARCHITECTURE.md'), 'utf8');
+    for (const f of readdirSync(abs('docs/architecture'))) {
+      if (!f.endsWith('.md') || f.startsWith('_')) continue;
+      if (!router.includes(f)) {
+        warn('docs/ARCHITECTURE.md', `no router row links to docs/architecture/${f} — it will never be loaded`);
+      }
+    }
+  }
+
+  // 5. Advisory: source moved, docs didn't. Not an error — plenty of changes need no doc update.
+  if (base) {
+    const changed = git('diff', '--name-only', `${base}...HEAD`).split('\n').filter(Boolean);
+    if (changed.length) {
+      const docSet = new Set(docs);
+      const touchedDocs = changed.filter((f) => docSet.has(f));
+      const touchedSource = changed.filter(
+        (f) => !docSet.has(f) && !f.endsWith('.md') && !f.startsWith('docs/'),
+      );
+      if (touchedSource.length > 0 && touchedDocs.length === 0) {
+        warn(
+          'knowledge layer',
+          `${touchedSource.length} source file(s) changed and no knowledge doc did — ` +
+          'if this PR moved an endpoint, listener, external client, or data-access flavor, run /repo-refresh',
+        );
+      }
+    }
+  }
+
+  return { docs, refsChecked, errors, warnings, empty: false };
+}
+
+// CLI ------------------------------------------------------------------------
+// Only runs when invoked directly, so importing this module stays silent — an MCP server
+// speaks JSON-RPC on stdout and a stray console.log corrupts the stream.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const args = process.argv.slice(2);
+  const flag = (name) => {
+    const i = args.indexOf(name);
+    return i === -1 ? null : args[i + 1];
+  };
+  const result = runChecks({ root: flag('--root') || process.cwd(), base: flag('--base') });
+
+  if (result.empty) {
+    console.log('knowledge-check: no knowledge layer found (CLAUDE.md / docs/) — nothing to check.');
+    console.log('Run /repo-init to create one, or delete this check.');
+    process.exit(0);
+  }
+
+  for (const w of result.warnings) console.log(`  warning  ${w.where}: ${w.msg}`);
+  for (const e of result.errors) console.error(`  error    ${e.where}: ${e.msg}`);
+
+  const summary = `${result.refsChecked} file:line reference(s) across ${result.docs.length} doc(s)`;
+  if (result.errors.length) {
+    console.error(`\n✗ knowledge layer is stale: ${result.errors.length} error(s), ${result.warnings.length} warning(s) — ${summary}`);
+    console.error('  These are facts the docs assert that are no longer true. Run /repo-refresh to fix,');
+    console.error('  or correct the references by hand. A doc that points at deleted code is worse than none.');
+    if (!args.includes('--warn-only')) process.exit(1);
+    console.error('  (--warn-only: not failing the build)');
+  } else {
+    console.log(`✓ knowledge layer checks out — ${summary}, ${result.warnings.length} warning(s)`);
+  }
+}

package/ml-specs/templates/ci/knowledge-layer.yml

@@ -0,0 +1,35 @@
+# Knowledge-layer CI gate — seeded by /repo-init (ml-specs).
+# Copy to .github/workflows/knowledge-layer.yml, with knowledge-check.mjs at .github/scripts/.
+#
+# Fails a PR when the docs assert something about the repo that is no longer true — a
+# `file:line` pointing at deleted code, a router row pointing at a missing shard. Those are
+# facts, not judgment, so they belong in CI. The judgment half stays in /repo-doctor.
+#
+# ADOPTING THIS ON AN EXISTING REPO: the first run usually finds real staleness. Start with
+# `--warn-only` below, run /repo-refresh to clear the backlog, then remove the flag. A gate
+# that fails on day one gets disabled on day two.
+
+name: knowledge-layer
+
+on:
+  pull_request:
+  push:
+    branches: [main, master]
+
+jobs:
+  knowledge-layer:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # the advisory check diffs against the base branch
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Check the knowledge layer still matches the code
+        run: |
+          node .github/scripts/knowledge-check.mjs \
+            --base "origin/${{ github.event.pull_request.base.ref || github.event.repository.default_branch }}"
+          # While adopting, append: --warn-only

package/ml-specs/templates/ci/spec-gate.yml

@@ -0,0 +1,69 @@
+# Spec gate — seeded by /repo-init (ml-specs).
+# Copy to .github/workflows/spec-gate.yml.
+#
+# Fails a pull request that does not trace back to an approved spec. Every check
+# here is deterministic: no LLM call, no API key, no network. Same verdict every
+# run, in well under a second — which matters more than it sounds, because a gate
+# that adds minutes to CI gets disabled within a month, and then you have
+# governance theatre.
+#
+# ADOPTING THIS ON AN EXISTING REPO: start with `continue-on-error: true` on the
+# blocking steps for a fortnight and watch how often it WOULD have failed. A gate
+# that fails on day one gets disabled on day two. Turn it on deliberately, once
+# you can defend the number.
+
+name: spec-gate
+
+on:
+  pull_request:
+
+jobs:
+  spec-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      # --- the branch must carry a spec key --------------------------------
+      # The chain starts here. A branch named `fix/payment-thing` cannot be
+      # traced to anything, and nothing downstream can recover the link.
+      - name: Branch carries a spec key
+        run: |
+          BRANCH="${{ github.head_ref }}"
+          if ! echo "$BRANCH" | grep -Eq '^(feat|fix|chore)/[0-9]{4}[a-z]?-'; then
+            echo "::error::branch '$BRANCH' carries no spec number."
+            echo "Expected feat/NNNN-slug. See specs/README.md."
+            exit 1
+          fi
+          echo "SPEC_ID=$(echo "$BRANCH" | sed -E 's#^[a-z]+/([0-9]{4}[a-z]?)-.*#\1#')" >> "$GITHUB_ENV"
+
+      # --- that spec must exist and be past the approval gate ---------------
+      - name: Spec is approved
+        run: |
+          FILE=$(ls specs/${SPEC_ID}-*.md 2>/dev/null | head -1)
+          if [ -z "$FILE" ]; then
+            echo "::error::no spec file for ${SPEC_ID}."
+            exit 1
+          fi
+          STATUS=$(grep -m1 -E '^\|\s*\*\*Status\*\*' "$FILE" | sed -E 's/.*\|\s*\*\*Status\*\*\s*\|\s*([^|]*).*/\1/' | xargs)
+          case "$STATUS" in
+            Approved|Implemented|Verified) echo "spec ${SPEC_ID} is $STATUS" ;;
+            *)
+              echo "::error::spec ${SPEC_ID} is '${STATUS:-unset}', not Approved."
+              echo "Nothing crosses into execution before the approval gate."
+              exit 1 ;;
+          esac
+
+      # --- the whole chain still resolves ----------------------------------
+      - name: Trace chain intact
+        run: node .github/scripts/spec-trace.mjs "$SPEC_ID"
+
+      # --- NFRs are routed, and none has been flattened into a story --------
+      - name: NFRs routed
+        run: node .github/scripts/nfr-compile.mjs
+
+      # --- the mechanical half of the lifecycle gate ------------------------
+      - name: Spec evidence
+        run: node .github/scripts/spec-gate.mjs "$(ls specs/${SPEC_ID}-*.md | head -1)"