cabloy 5.1.194 → 5.1.196

package/repo-agent-governance/tests/spec-audit.test.mjs

@@ -0,0 +1,255 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+import { auditPlanning } from '../tools/spec-audit/audit.mjs';
+
+const CLI = fileURLToPath(new URL('../tools/spec-audit/audit.mjs', import.meta.url));
+const BASELINE = {
+  'README.md': '# Synthetic Planning\n\n[Product](./prd.md#requirements)\n',
+  'prd.md':
+    '# Product\n\n## Requirements\n\n### PRD-DEMO-01: Product outcome\n\nTraceability: `SRS-DEMO-01`\n',
+  'srs.md':
+    '# Technical Contracts\n\n### SRS-DEMO-01: Contract\n\nTraceability: `PRD-DEMO-01`, `WBS-DEMO-10-01`\n',
+  'pdp-wbs.md':
+    '# Delivery\n\n### Phase 10: Baseline\n\nDependencies: none.\n\n#### WBS-DEMO-10-01: Implement contract\n\nTraceability: `SRS-DEMO-01`, `ATP-DEMO-01`\n\nCompletion checks: inspect synthetic output.\n',
+  'test-plan.md':
+    '# Acceptance\n\n## Acceptance Scenarios\n\n### ATP-DEMO-01: Verify contract\n\nSetup: synthetic state.\n\nProcedure: inspect output.\n\nExpected result: contract holds.\n\nMinimum proof: redacted observation.\n\nTraceability: `WBS-DEMO-10-01`\n',
+  'progress.md':
+    '# Progress\n\n| WBS ID | Work item | Status |\n| --- | --- | --- |\n| WBS-DEMO-10-01 | Implement contract | not-started |\n',
+  'decisions/0001-boundary.md': '# Boundary\n\nStatus: Proposed\n',
+};
+
+async function fixture(t, records = BASELINE) {
+  const directory = await mkdtemp(resolve(tmpdir(), 'cabloy-spec-audit-'));
+  t.after(() => rm(directory, { recursive: true, force: true }));
+  for (const [file, markdown] of Object.entries(records)) {
+    await mkdir(dirname(resolve(directory, file)), { recursive: true });
+    await writeFile(resolve(directory, file), markdown);
+  }
+  return directory;
+}
+
+async function snapshot(directory, prefix = '') {
+  const result = {};
+  for (const entry of await readdir(resolve(directory, prefix), { withFileTypes: true })) {
+    const file = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) Object.assign(result, await snapshot(directory, file));
+    else result[file] = await readFile(resolve(directory, file), 'utf8');
+  }
+  return result;
+}
+
+function codes(result) {
+  return result.diagnostics.map(diagnostic => diagnostic.code);
+}
+
+test('complete baseline checks exact traceability without treating a Proposed ADR as accepted', async t => {
+  const directory = await fixture(t);
+  const result = await auditPlanning(directory);
+  assert.deepEqual(result.diagnostics, []);
+  assert.equal(result.definitions, 4);
+  assert.equal(result.ok, true);
+  assert.match(result.limitations, /approval.*evidence authenticity/);
+});
+
+test('canonical atomic bullets carry their own inline traceability', async t => {
+  const records = {
+    ...BASELINE,
+    'prd.md':
+      '# Product\n\n## Requirements\n\n- **PRD-DEMO-01**: Product outcome. Traceability: `SRS-DEMO-01`.\n',
+    'srs.md':
+      '# Technical Contracts\n\n- **SRS-DEMO-01**: Contract. Traceability: `PRD-DEMO-01`, `WBS-DEMO-10-01`.\n',
+  };
+  const result = await auditPlanning(await fixture(t, records));
+  assert.equal(result.ok, true, JSON.stringify(result.diagnostics));
+});
+
+test('explicit four-column matrix supplies exact adjacent traceability', async t => {
+  const records = Object.fromEntries(
+    Object.entries(BASELINE).map(([file, value]) => [
+      file,
+      value.replace(/^Traceability:.*\n/gm, ''),
+    ]),
+  );
+  records['README.md'] +=
+    '\n| PRD | SRS | WBS | ATP |\n| --- | --- | --- | --- |\n| PRD-DEMO-01 | SRS-DEMO-01 | WBS-DEMO-10-01 | ATP-DEMO-01 |\n';
+  const result = await auditPlanning(await fixture(t, records));
+  assert.equal(result.ok, true, JSON.stringify(result.diagnostics));
+});
+
+test('ordinary co-occurrence and wildcard matrices cannot manufacture traceability', async t => {
+  const records = Object.fromEntries(
+    Object.entries(BASELINE).map(([file, value]) => [
+      file,
+      value.replace(/^Traceability:.*\n/gm, ''),
+    ]),
+  );
+  records['README.md'] +=
+    '\nPRD-DEMO-01 SRS-DEMO-01 WBS-DEMO-10-01 ATP-DEMO-01\n\n| PRD | SRS | WBS | ATP |\n| --- | --- | --- | --- |\n| PRD-DEMO-* | SRS-DEMO-* | WBS-DEMO-* | ATP-DEMO-* |\n';
+  const result = await auditPlanning(await fixture(t, records));
+  assert.equal(result.ok, false);
+  assert.equal(
+    result.diagnostics.filter(diagnostic => diagnostic.code.startsWith('traceability-')).length,
+    6,
+  );
+});
+
+test('lightweight records do not require absent baseline files or charts', async t => {
+  const directory = await fixture(t, {
+    'README.md': '# Lightweight\n',
+    'prd.md': '### PRD-DEMO-01: Bounded outcome\n',
+  });
+  const before = await snapshot(directory);
+  const result = await auditPlanning(directory, { lightweight: true });
+  assert.equal(result.ok, true);
+  assert.equal(result.mode, 'lightweight');
+  assert.match(result.coverage, /full-chain coverage not checked/);
+  assert.deepEqual(result.omittedRecords, ['srs.md', 'pdp-wbs.md', 'test-plan.md', 'progress.md']);
+  assert.deepEqual(await snapshot(directory), before);
+  const complete = await auditPlanning(directory);
+  assert.ok(codes(complete).includes('missing-record'));
+  assert.ok(codes(complete).includes('missing-adr'));
+});
+
+test('optional records are audited; fences, comments and evidence files are not authority', async t => {
+  const records = {
+    ...BASELINE,
+    'rollout.md':
+      '# Rollout\n\nUse `ATP-MISSING-01`.\n\n```md\n### ATP-EXAMPLE-01: Example\n```\n<!-- PRD-COMMENT-01 -->\n',
+    'evidence/run.md': 'PRD-EVIDENCE-01\n',
+  };
+  const result = await auditPlanning(await fixture(t, records));
+  assert.deepEqual(
+    result.diagnostics
+      .filter(diagnostic => diagnostic.code === 'undefined-reference')
+      .map(diagnostic => [diagnostic.file, diagnostic.line, diagnostic.id]),
+    [['rollout.md', 3, 'ATP-MISSING-01']],
+  );
+});
+
+test('a mention or evidence table is not a formal ATP declaration', async t => {
+  const records = {
+    ...BASELINE,
+    'test-plan.md':
+      '# Proof\n\n| ATP ID | Evidence | Status |\n| --- | --- | --- |\n| ATP-DEMO-01 | synthetic | verified |\n',
+  };
+  const result = await auditPlanning(await fixture(t, records));
+  assert.ok(codes(result).includes('missing-definition'));
+  assert.ok(
+    result.diagnostics.some(
+      diagnostic => diagnostic.id === 'ATP-DEMO-01' && diagnostic.code === 'undefined-reference',
+    ),
+  );
+});
+
+test('duplicate formal definitions and duplicate progress rows retain diagnostic provenance', async t => {
+  const records = {
+    ...BASELINE,
+    'prd.md': `${BASELINE['prd.md']}\n### PRD-DEMO-01: Duplicate\n`,
+    'progress.md': `${BASELINE['progress.md']}| WBS-DEMO-10-01 | Duplicate | verified |\n`,
+  };
+  const result = await auditPlanning(await fixture(t, records));
+  assert.ok(
+    result.diagnostics.some(
+      diagnostic => diagnostic.file === 'prd.md' && /Duplicate.*line/.test(diagnostic.message),
+    ),
+  );
+  assert.ok(
+    result.diagnostics.some(
+      diagnostic => diagnostic.file === 'progress.md' && /Duplicate.*line/.test(diagnostic.message),
+    ),
+  );
+});
+
+test('progress omissions, extras and explicit WBS status conflicts are structural failures', async t => {
+  const records = {
+    ...BASELINE,
+    'pdp-wbs.md': `${BASELINE['pdp-wbs.md']}\nStatus: in-progress\n\n#### WBS-DEMO-10-02: Additional task\n\nDependencies: none.\n`,
+    'progress.md': `${BASELINE['progress.md']}| WBS-DEMO-99-01 | Unknown | not-started |\n`,
+  };
+  const result = await auditPlanning(await fixture(t, records));
+  for (const code of ['missing-progress', 'unknown-progress', 'status-conflict'])
+    assert.ok(codes(result).includes(code), code);
+});
+
+test('completed tasks cannot hide unfinished recorded prerequisites', async t => {
+  const records = {
+    ...BASELINE,
+    'pdp-wbs.md': `${BASELINE['pdp-wbs.md']}\n#### WBS-DEMO-10-02: Dependent task\n\nDependencies: WBS-DEMO-10-01.\n`,
+    'progress.md': `${BASELINE['progress.md']}| WBS-DEMO-10-02 | Dependent | verified |\n`,
+  };
+  const result = await auditPlanning(await fixture(t, records), { lightweight: true });
+  assert.ok(
+    result.diagnostics.some(
+      diagnostic => diagnostic.id === 'WBS-DEMO-10-02' && diagnostic.code === 'dependency-state',
+    ),
+  );
+});
+
+test('local Markdown destinations, fragments and reference links are checked', async t => {
+  const records = {
+    ...BASELINE,
+    'rollout.md':
+      '# Rollout\n\n[Missing](./absent.md)\n[Bad fragment](./prd.md#absent)\n[Good][product]\n[Unknown][missing]\n\n[product]: ./prd.md#requirements\n\nPlanned source: `zova/src/target/new.ts`.\n',
+  };
+  const result = await auditPlanning(await fixture(t, records));
+  assert.deepEqual(
+    result.diagnostics.map(diagnostic => [diagnostic.code, diagnostic.line]),
+    [
+      ['link-target', 3],
+      ['link-fragment', 4],
+      ['link-reference', 6],
+    ],
+  );
+});
+
+test('exact range endpoints do not masquerade as exact traceability', async t => {
+  const records = {
+    ...BASELINE,
+    'prd.md': BASELINE['prd.md'].replace('`SRS-DEMO-01`', '`SRS-DEMO-01` through `SRS-DEMO-01`'),
+  };
+  // Remove the reverse PRD mapping so the ambiguous range is the sole proposed edge.
+  records['srs.md'] = records['srs.md'].replace('`PRD-DEMO-01`, ', '');
+  const result = await auditPlanning(await fixture(t, records));
+  assert.ok(
+    result.diagnostics.some(
+      diagnostic => diagnostic.code === 'traceability-outgoing' && diagnostic.id === 'PRD-DEMO-01',
+    ),
+  );
+});
+
+test('definition body boundaries prevent another requirement from supplying an earlier mapping', async t => {
+  const records = {
+    ...BASELINE,
+    'prd.md':
+      '# Product\n\n## Requirements\n\n### PRD-DEMO-02: Unmapped\n\n### PRD-DEMO-01: Mapped\n\nTraceability: `SRS-DEMO-01`\n',
+  };
+  const result = await auditPlanning(await fixture(t, records));
+  assert.ok(
+    result.diagnostics.some(
+      diagnostic => diagnostic.id === 'PRD-DEMO-02' && diagnostic.code === 'traceability-outgoing',
+    ),
+  );
+  assert.ok(!result.diagnostics.some(diagnostic => diagnostic.id === 'PRD-DEMO-01'));
+});
+
+test('CLI emits deterministic JSON, exits nonzero on gaps and never writes planning files', async t => {
+  const directory = await fixture(t, { 'README.md': '# Bounded\n\nATP-MISSING-01\n' });
+  const before = await snapshot(directory);
+  const args = [CLI, directory, '--lightweight', '--format', 'json'];
+  const first = spawnSync(process.execPath, args, { encoding: 'utf8' });
+  const second = spawnSync(process.execPath, args, { encoding: 'utf8' });
+  assert.equal(first.status, 1);
+  assert.equal(first.stdout, second.stdout);
+  const result = JSON.parse(first.stdout);
+  assert.equal(result.diagnostics[0].id, 'ATP-MISSING-01');
+  assert.deepEqual(await snapshot(directory), before);
+  const invalid = spawnSync(process.execPath, [CLI, '--fix'], { encoding: 'utf8' });
+  assert.equal(invalid.status, 1);
+  assert.match(invalid.stderr, /Unknown argument/);
+});

package/repo-agent-governance/tools/spec-audit/audit.mjs

@@ -0,0 +1,427 @@
+import { access, readFile, readdir } from 'node:fs/promises';
+import { dirname, extname, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  findIdentifiers,
+  markdownLines,
+  parseDefinitions,
+  parseProgress,
+  parseWbs,
+} from '../spec-charts/spec-parser.mjs';
+
+const OWNERS = new Map([
+  ['PRD-', 'prd.md'],
+  ['SRS-', 'srs.md'],
+  ['WBS-', 'pdp-wbs.md'],
+  ['ATP-', 'test-plan.md'],
+]);
+const CORE = ['README.md', ...OWNERS.values(), 'progress.md'];
+const LIMITS =
+  'Static structure only; approval, semantic sufficiency, implementation, and evidence authenticity require human review.';
+
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function planningFiles(directory, prefix = '') {
+  const result = [];
+  for (const entry of await readdir(resolve(directory, prefix), { withFileTypes: true })) {
+    if (entry.name === 'evidence' || entry.name.startsWith('.')) continue;
+    const path = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) result.push(...(await planningFiles(directory, path)));
+    else if (entry.isFile() && entry.name.endsWith('.md')) result.push(path);
+  }
+  return result.sort();
+}
+
+function cells(line) {
+  if (!line.trim().startsWith('|')) return null;
+  return line
+    .trim()
+    .replace(/^\||\|$/g, '')
+    .split(/(?<!\\)\|/)
+    .map(value => value.trim());
+}
+
+function exactIds(value, prefix) {
+  // Aggregations are summaries, not exact traceability. Do not count their endpoints.
+  if (/[*–—]|\b(?:through|to)\b|`\s*-\s*`|\d\s+-\s+(?:`|PRD-|SRS-|WBS-|ATP-)/.test(value))
+    return [];
+  return findIdentifiers(value, prefix);
+}
+
+function mappingGroups(text) {
+  return Array.from(OWNERS.keys(), prefix => exactIds(text, prefix));
+}
+
+function addMapping(groups, edges, definitions) {
+  for (let index = 0; index < groups.length - 1; index++) {
+    for (const from of groups[index]) {
+      if (!definitions.has(from)) continue;
+      for (const to of groups[index + 1]) {
+        if (definitions.has(to)) edges.get(from).add(to);
+      }
+    }
+  }
+}
+
+function collectMappings(records, definitions) {
+  const edges = new Map(Array.from(definitions.keys(), id => [id, new Set()]));
+  for (const definition of definitions.values()) {
+    for (const { text, line } of markdownLines(definition.body ?? '')) {
+      const field =
+        definition.kind === 'bullet' && line === 1
+          ? text.slice(text.search(/\bTraceability\s*:/i))
+          : text.trim();
+      const match = field.match(/^(?:-\s*)?(?:\*\*)?Traceability(?:\*\*)?\s*:(.*)$/i);
+      if (!match) continue;
+      const groups = mappingGroups(match[1]);
+      const index = [...OWNERS.keys()].findIndex(prefix => definition.id.startsWith(prefix));
+      groups[index].push(definition.id);
+      addMapping(groups, edges, definitions);
+    }
+  }
+  for (const markdown of records.values()) {
+    let columns = null;
+    for (const { text } of markdownLines(markdown)) {
+      const row = cells(text);
+      if (!row) {
+        columns = null;
+        continue;
+      }
+      if (row.every(value => /^:?-+:?$/.test(value))) continue;
+      const header = Array.from(OWNERS.keys(), prefix =>
+        row.findIndex(value =>
+          new RegExp(
+            `^${prefix.slice(0, -1)}(?:\\s+(?:IDs?|requirements?|contracts?|tasks?|scenarios?))?$`,
+            'i',
+          ).test(value.replace(/[`*]/g, '').trim()),
+        ),
+      );
+      if (header.every(index => index >= 0)) {
+        columns = header;
+        continue;
+      }
+      if (columns) {
+        addMapping(
+          columns.map((index, kind) => exactIds(row[index] ?? '', [...OWNERS.keys()][kind])),
+          edges,
+          definitions,
+        );
+      }
+    }
+  }
+  return edges;
+}
+
+function headingIds(markdown) {
+  const slugs = new Set();
+  const counts = new Map();
+  for (const { heading } of markdownLines(markdown)) {
+    if (!heading) continue;
+    const explicit = heading.text.match(/\{#([^}]+)\}\s*$/);
+    if (explicit) {
+      slugs.add(explicit[1]);
+      continue;
+    }
+    const slug = heading.text
+      .toLowerCase()
+      .replace(/<[^>]*>/g, '')
+      .replace(/[^\p{L}\p{N}_\-\s]/gu, '')
+      .replace(/\s/g, '-');
+    const count = counts.get(slug) ?? 0;
+    slugs.add(count ? `${slug}-${count}` : slug);
+    counts.set(slug, count + 1);
+  }
+  return slugs;
+}
+
+function markdownLinks(markdown) {
+  const lines = markdownLines(markdown);
+  const references = new Map();
+  const links = [];
+  for (const { text, line } of lines) {
+    const declaration = text.match(/^\s*\[([^\]]+)\]:\s*(<[^>]+>|\S+)/);
+    if (declaration)
+      references.set(declaration[1].trim().toLowerCase(), declaration[2].replace(/^<|>$/g, ''));
+    const inline = /!?\[[^\]]*\]\(\s*(<[^>]+>|[^\s)]+)(?:\s+["'][^\n]*["'])?\s*\)/g;
+    for (const match of text.matchAll(inline))
+      links.push({ destination: match[1].replace(/^<|>$/g, ''), line });
+    const referenced = /!?\[([^\]]+)\]\[([^\]]*)\]/g;
+    for (const match of text.matchAll(referenced))
+      links.push({ reference: (match[2] || match[1]).trim().toLowerCase(), line });
+  }
+  return links.map(link =>
+    link.reference ? { ...link, destination: references.get(link.reference) } : link,
+  );
+}
+
+async function checkLinks(directory, records, root, report) {
+  const targets = new Map();
+  for (const [file, markdown] of records) {
+    for (const link of markdownLinks(markdown)) {
+      if (link.reference && !link.destination) {
+        report(
+          'link-reference',
+          file,
+          link.line,
+          `Undefined Markdown link reference: ${link.reference}.`,
+        );
+        continue;
+      }
+      const destination = link.destination;
+      if (!destination || /^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(destination)) continue;
+      let path;
+      let fragment;
+      try {
+        const hash = destination.indexOf('#');
+        path = decodeURIComponent(
+          (hash < 0 ? destination : destination.slice(0, hash)).split('?')[0],
+        );
+        fragment = hash < 0 ? '' : decodeURIComponent(destination.slice(hash + 1));
+      } catch {
+        report('link-format', file, link.line, `Invalid encoded local link: ${destination}.`);
+        continue;
+      }
+      const target = path
+        ? resolve(
+            path.startsWith('/') ? root : dirname(resolve(directory, file)),
+            path.replace(/^\//, ''),
+          )
+        : resolve(directory, file);
+      if (!(await exists(target))) {
+        report('link-target', file, link.line, `Missing local link target: ${destination}.`);
+        continue;
+      }
+      if (!fragment || extname(target) !== '.md') continue;
+      if (!targets.has(target)) targets.set(target, headingIds(await readFile(target, 'utf8')));
+      if (!targets.get(target).has(fragment)) {
+        report(
+          'link-fragment',
+          file,
+          link.line,
+          `Missing Markdown heading fragment: ${destination}.`,
+        );
+      }
+    }
+  }
+}
+
+export async function auditPlanning(
+  directory,
+  { lightweight = false, root = resolve(directory, '../..') } = {},
+) {
+  directory = resolve(directory);
+  const diagnostics = [];
+  const report = (code, file, line, message, id) =>
+    diagnostics.push({ code, file, line, ...(id ? { id } : {}), message });
+  const records = new Map();
+  for (const file of await planningFiles(directory))
+    records.set(file, await readFile(resolve(directory, file), 'utf8'));
+  if (!lightweight) {
+    for (const file of CORE) {
+      if (!records.has(file))
+        report('missing-record', file, 1, 'Required complete-baseline record is missing.');
+    }
+    if (![...records.keys()].some(file => /^decisions\/[^/]+\.md$/.test(file)))
+      report('missing-adr', 'decisions/', 1, 'A complete baseline requires a suite boundary ADR.');
+  }
+  const definitions = new Map();
+  let wbs;
+  for (const [prefix, file] of OWNERS) {
+    if (!records.has(file)) continue;
+    try {
+      let declared;
+      if (prefix === 'WBS-') {
+        wbs = parseWbs(records.get(file), { file });
+        declared = new Map(wbs.tasks.map(task => [task.id, { ...task, file, kind: 'WBS' }]));
+      } else {
+        declared = parseDefinitions(records.get(file), prefix, { file });
+      }
+      for (const [id, definition] of declared) definitions.set(id, { ...definition, file });
+      if (!lightweight && !declared.size) {
+        report(
+          'missing-definition',
+          file,
+          1,
+          `No formal ${prefix.slice(0, -1)} definitions found.`,
+        );
+      }
+    } catch (error) {
+      report('declaration', file, 1, error.message);
+    }
+  }
+  for (const [file, markdown] of records) {
+    for (const { text, line } of markdownLines(markdown)) {
+      for (const prefix of OWNERS.keys()) {
+        for (const id of findIdentifiers(text, prefix)) {
+          if (!definitions.has(id)) {
+            report(
+              'undefined-reference',
+              file,
+              line,
+              `No unique formal definition in ${OWNERS.get(prefix)}.`,
+              id,
+            );
+          }
+        }
+      }
+    }
+  }
+  if (wbs) {
+    const progress = records.get('progress.md');
+    if (progress !== undefined) {
+      try {
+        const { rows, locations } = parseProgress(progress, { file: 'progress.md' });
+        for (const task of wbs.tasks) {
+          if (!rows.has(task.id)) {
+            report('missing-progress', 'progress.md', 1, 'WBS task has no progress row.', task.id);
+          } else if (
+            (task.status || task.deferred) &&
+            rows.get(task.id) !== (task.status ?? 'deferred')
+          ) {
+            report(
+              'status-conflict',
+              'progress.md',
+              locations?.get(task.id)?.line ?? 1,
+              `Progress contradicts explicit WBS status ${task.status ?? 'deferred'}.`,
+              task.id,
+            );
+          }
+          if (['implementation-complete', 'verified'].includes(rows.get(task.id))) {
+            for (const dependency of task.dependencyIds) {
+              if (
+                ['not-started', 'in-progress', 'blocked', 'deferred'].includes(rows.get(dependency))
+              ) {
+                report(
+                  'dependency-state',
+                  'progress.md',
+                  locations?.get(task.id)?.line ?? 1,
+                  `Completed task still has an unfinished recorded prerequisite: ${dependency}.`,
+                  task.id,
+                );
+              }
+            }
+          }
+        }
+        for (const id of rows.keys()) {
+          if (!definitions.has(id)) {
+            report(
+              'unknown-progress',
+              'progress.md',
+              locations?.get(id)?.line ?? 1,
+              'Progress row has no WBS definition.',
+              id,
+            );
+          }
+        }
+      } catch (error) {
+        report('progress', 'progress.md', 1, error.message);
+      }
+    }
+  } else if (records.has('progress.md') && !records.has('pdp-wbs.md')) {
+    report('missing-owner', 'progress.md', 1, 'A progress register requires pdp-wbs.md.');
+  }
+  if (!lightweight) {
+    const edges = collectMappings(records, definitions);
+    const incoming = new Set([...edges.values()].flatMap(values => [...values]));
+    for (const [id, definition] of definitions) {
+      if (definition.status === 'deferred' || definition.deferred) continue;
+      if (!id.startsWith('PRD-') && !incoming.has(id)) {
+        report(
+          'traceability-incoming',
+          definition.file,
+          definition.line,
+          'No explicit exact-ID mapping from the preceding authority kind.',
+          id,
+        );
+      }
+      if (!id.startsWith('ATP-') && !edges.get(id).size) {
+        report(
+          'traceability-outgoing',
+          definition.file,
+          definition.line,
+          'No explicit exact-ID mapping to the next authority kind.',
+          id,
+        );
+      }
+    }
+  }
+  await checkLinks(directory, records, resolve(root), report);
+  diagnostics.sort(
+    (a, b) =>
+      a.file.localeCompare(b.file, 'en') ||
+      a.line - b.line ||
+      a.code.localeCompare(b.code, 'en') ||
+      (a.id ?? '').localeCompare(b.id ?? '', 'en'),
+  );
+  return {
+    mode: lightweight ? 'lightweight' : 'complete',
+    ok: diagnostics.length === 0,
+    files: records.size,
+    definitions: definitions.size,
+    coverage: lightweight
+      ? 'Present owners, exact references, progress, and local links; full-chain coverage not checked.'
+      : 'Complete-baseline structure and explicit exact-ID chain.',
+    omittedRecords: CORE.filter(file => !records.has(file)),
+    diagnostics,
+    limitations: LIMITS,
+  };
+}
+
+async function main(args) {
+  let target;
+  let lightweight = false;
+  let format = 'text';
+  for (let index = 0; index < args.length; index++) {
+    const value = args[index];
+    if (value === '--lightweight') {
+      lightweight = true;
+    } else if (value === '--format' && ['text', 'json'].includes(args[index + 1])) {
+      format = args[++index];
+    } else if (!value.startsWith('-') && !target) {
+      target = value;
+    } else {
+      throw new Error(
+        `Unknown argument: ${value}. Usage: spec:check <suite-or-directory> [--lightweight] [--format text|json]`,
+      );
+    }
+  }
+  if (!target)
+    throw new Error('Usage: spec:check <suite-or-directory> [--lightweight] [--format text|json]');
+  const root = process.cwd();
+  const directory = (await exists(resolve(root, target)))
+    ? resolve(root, target)
+    : resolve(root, 'repo-specs', target);
+  const result = await auditPlanning(directory, { lightweight, root });
+  if (format === 'json') {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    process.stdout.write(
+      `${relative(root, directory)}: ${result.mode} planning structure ${result.ok ? 'passed' : 'failed'} (${result.definitions} definitions).\n`,
+    );
+    for (const diagnostic of result.diagnostics) {
+      process.stdout.write(
+        `${diagnostic.file}:${diagnostic.line} [${diagnostic.code}]${diagnostic.id ? ` ${diagnostic.id}` : ''} ${diagnostic.message}\n`,
+      );
+    }
+    process.stdout.write(`${result.coverage}\n`);
+    if (result.omittedRecords.length)
+      process.stdout.write(`Absent core records: ${result.omittedRecords.join(', ')}.\n`);
+    process.stdout.write(`${result.limitations}\n`);
+  }
+  if (!result.ok) process.exitCode = 1;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main(process.argv.slice(2)).catch(error => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  });
+}