@mlmcps/ml-specs-mcp 1.0.0

package/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/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)`);
+  }
+}