@dtlabs/ai-toolkit 0.17.5 → 0.19.0

package/src/claude/commands/assemble-docs.md

@@ -0,0 +1,16 @@
+---
+description: "Assemble Docs — renders the split Requirements/Tech-Spec/Work-Breakdown sources into single combined documents, on demand. Usage: /assemble-docs <feature-slug> [req|spec|wbs|all]"
+argument-hint: <feature-slug> [req|spec|wbs|all]
+allowed-tools: Bash, Glob, Read
+---
+
+Produce an on-demand, single-file view of one or more of this feature's split documents.
+
+Approach:
+1. Locate the feature folder under `docs/features/` (match by slug or FTR id) from the first argument.
+2. Extract the prefix from the folder name (`FTR-025-slug` → `FTR-025`).
+3. Determine `which` from the second argument (default `all`).
+4. Run: `node .claude/scripts/assemble-docs.js <feature-dir> <prefix> <which>`
+5. Report exactly what was written (the script's own JSON `written` array), or surface its error message verbatim if it failed — do not retry or guess an alternative path.
+
+This command is a read-only rendering action: it never affects Gate 1/Gate 2, approvals, or any digest. Running it is always safe, at any point in the pipeline.

package/src/claude/commands/feature-status.md

@@ -10,10 +10,15 @@ Steps:
 1. Locate the feature folder under `docs/features/`. Match by slug or FTR id (e.g. `FTR-001-user-login` matches both `001` and `user-login`).
 2. For each of the following artifacts, check presence and basic completeness:
    - `feature.md` — the source brief
-   - `{PREFIX}-Requirements.md` — functional requirements
-   - `{PREFIX}-Tech-Spec.md` — technical specification
-   - `{PREFIX}-Work-Breakdown.md` — user stories + tasks
-   - Implementation status: cross-check tasks in the work breakdown against the codebase. For each task, report `done` / `partial` / `not started` based on whether the referenced files/symbols exist.
+   - Requirements — ✅ if either `req/index.md` (split, default) or `{PREFIX}-Requirements.md`
+     (assembled, legacy or user-requested via `/assemble-docs`) exists; note which shape was found
+   - Tech-Spec — ✅ if either `spec/index.md` (split, default) or `{PREFIX}-Tech-Spec.md`
+     (assembled) exists; note which shape was found
+   - Work Breakdown — ✅ if either `wbs/index.json` (split, always the case since FTR-020) or
+     `{PREFIX}-Work-Breakdown.md` (rendered, only present if `/assemble-docs` was run) exists
+   - Implementation status: cross-check tasks in the work breakdown against the codebase (read
+     `wbs/` directly). For each task, report `done` / `partial` / `not started` based on whether
+     the referenced files/symbols exist.
 3. Output a single markdown table with columns: `Artifact | Status | Notes`. Status uses ✅ / ⚠️ / ❌. Keep notes under 80 chars.
 4. After the table, list the next 1–3 actionable items in priority order.
 

package/src/claude/scripts/ac-task-matrix.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+'use strict'
+
+// FTR-022: deterministic renderer producing {PREFIX}-AC-Task-Matrix.md — a table mapping every
+// Requirements Acceptance Criterion to the Work Breakdown task(s)/phase(s) that cover it. No new
+// data, no new validation: every fact here is already computed and enforced by wb-validate.js's
+// checks 19-21 (checkAcCoverage, wb-graph-checks.js). This script never re-validates; it assumes
+// its inputs already passed those checks and only renders what they already guarantee.
+
+const fs = require('fs')
+const path = require('path')
+const { loadWorkBreakdown } = require('./wbs-assembler')
+const { parseAcTable } = require('./wb-graph-checks')
+const { parseFileInventoryEntries } = require('./tech-spec-graph-checks')
+
+function computeCoverage(wb, acMap) {
+  // taskPhase mirrors checkAcCoverage's own seenTaskIds pattern — not read by this function's
+  // own return value, kept available for any future lookup that needs "which phase owns task X"
+  // directly instead of iterating coverage's per-AC sets.
+  const taskPhase = new Map()
+  for (const phase of wb.phases) for (const task of phase.tasks) taskPhase.set(task.id, phase.id)
+
+  const coverage = new Map([...acMap.keys()].map(acId => [acId, { taskIds: new Set(), phaseIds: new Set() }]))
+  for (const phase of wb.phases) {
+    for (const task of phase.tasks) {
+      for (const acId of (task.acceptanceCriteria || [])) {
+        if (!coverage.has(acId)) continue // AC_NOT_FOUND is wb-validate.js's job, not this script's
+        coverage.get(acId).taskIds.add(task.id)
+        coverage.get(acId).phaseIds.add(phase.id)
+      }
+    }
+  }
+  return coverage
+}
+
+// FTR-023: acId -> Set<filePath>, built from Tech-Spec §9 File Inventory "Addresses" cells.
+function computeTechSpecCoverage(entries, acMap) {
+  const coverage = new Map([...acMap.keys()].map(acId => [acId, new Set()]))
+  for (const entry of entries) {
+    for (const acId of entry.acIds) {
+      if (coverage.has(acId)) coverage.get(acId).add(entry.filePath)
+    }
+  }
+  return coverage
+}
+
+function renderMatrix(prefix, acMap, coverage, techSpecCoverage = new Map()) {
+  const mustEntries = [...acMap.entries()].filter(([, ac]) => ac.priority === 'Must')
+  const mustCovered = mustEntries.filter(([id]) => coverage.get(id).taskIds.size > 0).length
+  const summary = `**Must-AC coverage:** ${mustCovered}/${mustEntries.length} covered. ` +
+    'Machine-readable data: [index.json](index.json).'
+  const rows = [...acMap.entries()].map(([acId, ac]) => {
+    const relatedUc = ac.unscoped ? 'All UCs' : ac.relatedUCs.join(', ')
+    const cov = coverage.get(acId)
+    const taskIds = [...cov.taskIds].join(', ') || '—'
+    const phaseIds = [...cov.phaseIds].join(', ') || '—'
+    const techSpecFiles = [...(techSpecCoverage.get(acId) || [])].join(', ') || '—'
+    return `| ${acId} | ${ac.criterion} | ${ac.priority} | ${relatedUc} | ${techSpecFiles} | ${taskIds} | ${phaseIds} |`
+  })
+  return `# AC ↔ Task Traceability Matrix — ${prefix}\n\n${summary}\n\n` +
+    '| AC ID | Criterion | Priority | Related UC | Addressed by Tech-Spec File(s) | Covering Task(s) | Covering Phase(s) |\n' +
+    '|---|---|---|---|---|---|---|\n' +
+    rows.join('\n') + '\n\n' +
+    '> **Legend:** **AC ID** — unique identifier from the Requirements Acceptance Criteria ' +
+    'table. **Criterion** — the testable Given/When/Then statement, copied verbatim. ' +
+    '**Priority** — MoSCoW; every `Must` row is guaranteed non-empty in **Covering Task(s)** by ' +
+    'wb-validate.js check 21 before this file is ever generated. **Related UC** — which Use ' +
+    'Case(s) this AC belongs to, or `All UCs`. **Addressed by Tech-Spec File(s)** — every ' +
+    'Tech-Spec file whose `Addresses` column cites this AC, comma-separated, or `—` if none. ' +
+    '**Covering Task(s)** — every Work Breakdown task whose `acceptanceCriteria` cites this AC, ' +
+    'comma-separated, or `—` if none. **Covering Phase(s)** — the distinct phase(s) those tasks ' +
+    'belong to, comma-separated, or `—` if none.\n'
+}
+
+// FTR-026: serializes the same in-memory data renderMatrix() already consumes into a
+// machine-readable shape — one entry per Requirements AC, in table order. No new computation.
+function buildMatrixJson(prefix, acMap, coverage, techSpecCoverage = new Map()) {
+  const acceptanceCriteria = [...acMap.entries()].map(([acId, ac]) => {
+    const cov = coverage.get(acId)
+    return {
+      id: acId,
+      criterion: ac.criterion,
+      priority: ac.priority,
+      unscoped: !!ac.unscoped,
+      relatedUCs: ac.unscoped ? [] : ac.relatedUCs,
+      techSpecFiles: [...(techSpecCoverage.get(acId) || [])],
+      taskIds: [...cov.taskIds],
+      phaseIds: [...cov.phaseIds],
+    }
+  })
+  return { prefix, generatedAt: new Date().toISOString(), acceptanceCriteria }
+}
+
+if (require.main === module) {
+  // FTR-026: featureDir is REQUIRED (not optional) — confirmed by grep that pm-phase2.js and this
+  // script's own test suite are the only callers, so there is no backward-compatible no-arg case
+  // worth preserving. Output moves from one loose {prefix}-AC-Task-Matrix.md file (whose location
+  // used to be derived from path.dirname(requirementsPath) — a real bug: that would have silently
+  // moved once a caller passes a Requirements path living under req/) into a dedicated
+  // coverage-matrix/ subfolder under featureDir, as a JSON+MD pair.
+  const [wbsPath, requirementsPath, techSpecPath, prefix, featureDir] = process.argv.slice(2)
+  if (!wbsPath || !requirementsPath || !techSpecPath || !prefix || !featureDir) {
+    process.stderr.write(
+      'Usage: node ac-task-matrix.js <wbs-path> <requirements-path> <tech-spec-path> <prefix> <feature-dir>\n')
+    process.exit(1)
+  }
+  const wb = loadWorkBreakdown(path.resolve(wbsPath))
+  const acMap = parseAcTable(path.resolve(requirementsPath))
+  const coverage = computeCoverage(wb, acMap)
+  const techSpecEntries = parseFileInventoryEntries(fs.readFileSync(path.resolve(techSpecPath), 'utf8'))
+  const techSpecCoverage = computeTechSpecCoverage(techSpecEntries, acMap)
+  const outDir = path.join(path.resolve(featureDir), 'coverage-matrix')
+  fs.mkdirSync(outDir, { recursive: true })
+  const jsonPath = path.join(outDir, 'index.json')
+  const mdPath = path.join(outDir, 'index.md')
+  fs.writeFileSync(jsonPath, JSON.stringify(buildMatrixJson(prefix, acMap, coverage, techSpecCoverage), null, 2))
+  fs.writeFileSync(mdPath, renderMatrix(prefix, acMap, coverage, techSpecCoverage))
+  console.log(JSON.stringify({ jsonPath, mdPath }))
+}
+
+module.exports = { computeCoverage, renderMatrix, computeTechSpecCoverage, buildMatrixJson }

package/src/claude/scripts/assemble-docs.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+'use strict'
+
+// FTR-025: on-demand assembly of the split Requirements/Tech-Spec/Work-Breakdown sources into
+// single-file views. Runs as a plain Node CLI outside the sandboxed workflow runtime, so it can
+// `require()` req-assembler.js/tech-spec-assembler.js directly (no subprocess round-trip needed)
+// — it shells out only to wb-render.js, which is CLI-only (writes its own two output files and
+// exits, no exported function to call in-process). This script never runs automatically as part
+// of generation; it is the explicit, user-triggered alternative to that.
+
+const fs = require('fs')
+const path = require('path')
+const { execFileSync } = require('child_process')
+const { loadRequirements, AssemblyError: ReqAssemblyError } = require('./req-assembler')
+const { loadTechSpec, AssemblyError: SpecAssemblyError } = require('./tech-spec-assembler')
+
+// loadRequirements()/loadTechSpec() already throw a structured AssemblyError naming the exact
+// missing path when the directory doesn't exist (fs.statSync(inputPath, {throwIfNoEntry:false})
+// returning null) — no separate existence pre-check needed here, it would only duplicate what
+// the assembler already does correctly.
+function assembleReq(featureDir, prefix) {
+  const outPath = path.join(featureDir, `${prefix}-Requirements.md`)
+  fs.writeFileSync(outPath, loadRequirements(path.join(featureDir, 'req')))
+  return outPath
+}
+
+function assembleSpec(featureDir, prefix) {
+  const outPath = path.join(featureDir, `${prefix}-Tech-Spec.md`)
+  fs.writeFileSync(outPath, loadTechSpec(path.join(featureDir, 'spec')))
+  return outPath
+}
+
+function assembleWbs(featureDir, prefix) {
+  const wbsDir = path.join(featureDir, 'wbs')
+  if (!fs.existsSync(wbsDir)) throw new ReqAssemblyError(`wbs/ not found at ${wbsDir}`)
+  // wb-render.js is CLI-only (writes {prefix}-Work-Breakdown.md/.csv itself and exits) — shell
+  // out, same subprocess convention pm-phase2.js used for its own (now-removed) automatic call.
+  // No destination-dir argument needed: wb-render.js defaults it to the parent of its own
+  // <wbs-dir> argument, which is already featureDir.
+  execFileSync(process.execPath, [path.join(__dirname, 'wb-render.js'), wbsDir, prefix])
+  return [path.join(featureDir, `${prefix}-Work-Breakdown.md`), path.join(featureDir, `${prefix}-Work-Breakdown.csv`)]
+}
+
+const HANDLERS = { req: assembleReq, spec: assembleSpec, wbs: assembleWbs }
+
+if (require.main === module) {
+  const [featureDir, prefix, which = 'all'] = process.argv.slice(2)
+  if (!featureDir || !prefix) {
+    process.stderr.write('Usage: node assemble-docs.js <feature-dir> <prefix> [req|spec|wbs|all]\n')
+    process.exit(1)
+  }
+  const targets = which === 'all' ? Object.keys(HANDLERS) : [which]
+  if (!targets.every(t => HANDLERS[t])) {
+    process.stderr.write(`Unknown target "${which}" — expected req, spec, wbs, or all\n`)
+    process.exit(1)
+  }
+  try {
+    const written = targets.map(t => HANDLERS[t](path.resolve(featureDir), prefix)).flat()
+    process.stdout.write(JSON.stringify({ written }) + '\n')
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message}\n`)
+    process.exit((err instanceof ReqAssemblyError || err instanceof SpecAssemblyError) ? 2 : 1)
+  }
+}
+
+module.exports = { assembleReq, assembleSpec, assembleWbs }

package/src/claude/scripts/req-assembler.js

@@ -0,0 +1,127 @@
+'use strict'
+
+// FTR-021: loader/renderer for the split Requirements format (req/index.md +
+// req/use-cases/{UC-ID}.md). Unlike wbs-assembler.js (JSON -> Markdown rendering),
+// index.md is already Markdown narrative, so assembly here is textual reassembly:
+// splice each use case's already-rendered file into Section 2's slot, in index-table
+// order. Legacy input (a single monolithic file) is returned unchanged.
+
+const fs = require('fs')
+const path = require('path')
+
+class AssemblyError extends Error {}
+
+// Returns { start, end, lines }: `start` is the index of the "## N. " heading line for
+// `sectionNumber`, `end` is the index of the next "## M. " heading (M > sectionNumber),
+// or lines.length if none follows. Throws if the section is not found at all.
+function findSectionRange(content, sectionNumber) {
+  const lines = content.split('\n')
+  let start = -1
+  let end = lines.length
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^## (\d+)\.\s/)
+    if (!m) continue
+    const n = Number(m[1])
+    if (n === sectionNumber) start = i
+    else if (start !== -1 && n > sectionNumber) { end = i; break }
+  }
+  if (start === -1) throw new AssemblyError(`missing section ${sectionNumber}`)
+  return { start, end, lines }
+}
+
+// Parses the first Markdown table found inside [start, end) into rows, dropping the
+// header row and the "|---|---|" separator row. Returns an array of cell-arrays.
+function parseTableRows(lines, start, end) {
+  const tableLines = lines.slice(start, end).filter(l => l.trim().startsWith('|'))
+  if (tableLines.length < 2) return []
+  return tableLines.slice(2).map(line =>
+    line.split('|').map(c => c.trim()).filter((_, i, a) => i > 0 && i < a.length - 1))
+}
+
+// The "## 2. Use Cases" index table: UC ID | Title | Actor | Priority | File.
+// `File` is a Markdown link `[use-cases/UC-01.md](use-cases/UC-01.md)` — the link
+// TARGET (inside the parens) is authoritative, not the link text.
+function parseUseCaseIndexTable(indexContent) {
+  const { start, end, lines } = findSectionRange(indexContent, 2)
+  return parseTableRows(lines, start, end).map(cells => {
+    const [id, title, actor, priority, fileCol] = cells
+    const fileMatch = fileCol && fileCol.match(/\(([^)]+)\)/)
+    if (!fileMatch) throw new AssemblyError(`malformed File column for UC "${id}" in index.md`)
+    return { id, title, actor, priority, file: fileMatch[1] }
+  })
+}
+
+// The "## 7. Acceptance Criteria" table: ID | Criterion | Related UC | Priority.
+function parseAcTable(indexContent) {
+  const { start, end, lines } = findSectionRange(indexContent, 7)
+  return parseTableRows(lines, start, end).map(cells => {
+    const [id, criterion, relatedUc, priority] = cells
+    return { id, criterion, relatedUc, priority }
+  })
+}
+
+// The "## 3. Business Rules" table: ID | Rule | Applies to.
+function parseBusinessRulesTable(indexContent) {
+  const { start, end, lines } = findSectionRange(indexContent, 3)
+  return parseTableRows(lines, start, end).map(cells => {
+    const [id, rule, appliesTo] = cells
+    return { id, rule, appliesTo }
+  })
+}
+
+// Replaces Section 2's body (everything after its heading, up to but not including the
+// next "## 3." heading) with `section2Body`, keeping the heading line itself and every
+// other section untouched.
+function spliceSection2(indexContent, section2Body) {
+  const { start, end, lines } = findSectionRange(indexContent, 2)
+  const heading = lines[start]
+  const before = lines.slice(0, start).concat([heading]).join('\n')
+  const after = lines.slice(end).join('\n')
+  return `${before}\n\n${section2Body}\n\n${after}`
+}
+
+function loadRequirements(inputPath) {
+  const stat = fs.statSync(inputPath, { throwIfNoEntry: false })
+  if (!stat) throw new AssemblyError(`path does not exist: ${inputPath}`)
+  if (stat.isFile()) return fs.readFileSync(inputPath, 'utf8') // legacy path (AC-07)
+
+  const indexPath = path.join(inputPath, 'index.md')
+  if (!fs.existsSync(indexPath)) throw new AssemblyError(`missing req/index.md at ${indexPath}`)
+  const indexContent = fs.readFileSync(indexPath, 'utf8')
+
+  const ucTable = parseUseCaseIndexTable(indexContent)
+  if (ucTable.length === 0) throw new AssemblyError('req/index.md has no rows in its Use Cases index table')
+
+  const ucBlocks = ucTable.map(row => {
+    const ucPath = path.join(inputPath, row.file)
+    if (!fs.existsSync(ucPath)) throw new AssemblyError(`use case "${row.id}" has no detail file at ${ucPath}`)
+    return fs.readFileSync(ucPath, 'utf8').trimEnd()
+  })
+
+  return spliceSection2(indexContent, ucBlocks.join('\n\n'))
+}
+
+if (require.main === module) {
+  const inputPath = process.argv[2]
+  if (!inputPath) {
+    process.stderr.write('Usage: node req-assembler.js <path-to-req-dir-or-legacy-file>\n')
+    process.exit(1)
+  }
+  try {
+    process.stdout.write(loadRequirements(path.resolve(inputPath)))
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message}\n`)
+    process.exit(err instanceof AssemblyError ? 1 : 2)
+  }
+}
+
+module.exports = {
+  loadRequirements,
+  parseUseCaseIndexTable,
+  parseAcTable,
+  parseBusinessRulesTable,
+  spliceSection2,
+  findSectionRange,
+  parseTableRows,
+  AssemblyError,
+}

package/src/claude/scripts/req-graph-checks.js

@@ -0,0 +1,71 @@
+'use strict'
+
+// FTR-021: 4 pure self-consistency check functions for the split Requirements format
+// (req/index.md). Mirrors wb-graph-checks.js's convention: no file I/O, no process.exit,
+// just plain functions over an already-parsed plain object, returning an array of error
+// objects. The actual Markdown parsing lives in req-assembler.js / req-skeleton-check.js.
+
+const UC_ID_RE = /^UC-\d{2,}$/
+
+function checkUniqueUcIds({ ucIds }) {
+  const seen = new Set()
+  const duplicates = new Set()
+  for (const id of ucIds) {
+    if (seen.has(id)) duplicates.add(id)
+    else seen.add(id)
+  }
+  return [...duplicates].map(id => ({
+    category: 'DUPLICATE_UC_ID', severity: 'error', ucId: id,
+    message: `Duplicate UC ID "${id}" appears more than once in the use-case index table`,
+  }))
+}
+
+function checkUcIdFormat({ ucIds }) {
+  return ucIds.filter(id => !UC_ID_RE.test(id)).map(id => ({
+    category: 'INVALID_UC_ID_FORMAT', severity: 'error', ucId: id,
+    message: `UC ID "${id}" does not match the required UC-NN format`,
+  }))
+}
+
+// Orphan-file direction only: a use-cases/*.md file that no longer corresponds to any row
+// in the current table (e.g. left over after a UC was renamed/removed from a hand-edited
+// index.md). Deliberately NOT bidirectional — this check runs BEFORE per-use-case
+// dispatch, when every row is expected to have no file yet, so "table row without a file"
+// is the normal pre-dispatch state, not an error. That direction is enforced correctly,
+// after generation, by req-assembler.js's own missing-file error at assembly time.
+function checkUcTableFileParity({ ucIds }, existingUcFiles) {
+  const idSet = new Set(ucIds)
+  return existingUcFiles.filter(id => !idSet.has(id)).map(id => ({
+    category: 'UC_FILE_WITHOUT_TABLE_ROW', severity: 'error', ucId: id,
+    message: `use-cases/${id}.md exists but has no row in the use-case index table`,
+  }))
+}
+
+function checkCrossReferencesResolve({ ucIds, acTable, businessRules }) {
+  const idSet = new Set(ucIds)
+  const errors = []
+  const checkRefs = (rows, idField, refField, category) => {
+    for (const row of rows) {
+      const raw = row[refField]
+      if (raw == null || raw.trim() === 'All UCs') continue
+      for (const ref of raw.split(',').map(s => s.trim()).filter(Boolean)) {
+        if (!idSet.has(ref)) {
+          errors.push({
+            category, severity: 'error', id: row[idField], ucId: ref,
+            message: `${row[idField]}'s "${refField}" references unknown UC "${ref}"`,
+          })
+        }
+      }
+    }
+  }
+  checkRefs(acTable || [], 'id', 'relatedUc', 'DANGLING_AC_UC_REFERENCE')
+  checkRefs(businessRules || [], 'id', 'appliesTo', 'DANGLING_BR_UC_REFERENCE')
+  return errors
+}
+
+module.exports = {
+  checkUniqueUcIds,
+  checkUcIdFormat,
+  checkUcTableFileParity,
+  checkCrossReferencesResolve,
+}

package/src/claude/scripts/req-skeleton-check.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+'use strict'
+
+// FTR-021: deterministic structural pre-check for a Requirements skeleton (req/index.md),
+// run by pm-phase1.js before any per-use-case generation call is dispatched (UC-02).
+//
+// This is a separate script from req-assembler.js's CLI mode, not a reuse of it, because
+// pm-phase1.js's workflow-script runtime has no `require` (lib/workflow-runner.js) — this
+// is invoked as a real Node subprocess via `c.command(['run-asset',
+// 'scripts/req-skeleton-check.js', ...])`, the same pattern already used for
+// wb-skeleton-check.js/wb-validate.js/wb-render.js (FTR-020).
+
+const fs = require('fs')
+const path = require('path')
+const graphChecks = require('./req-graph-checks')
+const { parseUseCaseIndexTable, parseAcTable, parseBusinessRulesTable } = require('./req-assembler')
+
+function main() {
+  const indexPath = process.argv[2]
+  if (!indexPath) {
+    process.stderr.write('Usage: node req-skeleton-check.js <path-to-req-index.md>\n')
+    process.exit(2)
+  }
+
+  let indexContent
+  try {
+    indexContent = fs.readFileSync(indexPath, 'utf8')
+  } catch (e) {
+    console.log(JSON.stringify({ valid: false, errors: [{ message: `cannot read ${indexPath}: ${e.message}` }] }))
+    process.exit(2)
+  }
+
+  let ucTable, acTable, businessRules
+  try {
+    ucTable = parseUseCaseIndexTable(indexContent)
+    acTable = parseAcTable(indexContent)
+    businessRules = parseBusinessRulesTable(indexContent)
+  } catch (e) {
+    console.log(JSON.stringify({ valid: false, errors: [{ message: `parse failure: ${e.message}` }] }))
+    process.exit(2)
+  }
+
+  const ucIds = ucTable.map(r => r.id)
+  const useCasesDir = path.join(path.dirname(indexPath), 'use-cases')
+  const existingUcFiles = fs.existsSync(useCasesDir)
+    ? fs.readdirSync(useCasesDir).filter(f => f.endsWith('.md')).map(f => f.replace(/\.md$/, ''))
+    : []
+
+  const errors = [
+    ...graphChecks.checkUniqueUcIds({ ucIds }),
+    ...graphChecks.checkUcIdFormat({ ucIds }),
+    ...graphChecks.checkUcTableFileParity({ ucIds }, existingUcFiles),
+    ...graphChecks.checkCrossReferencesResolve({
+      ucIds,
+      acTable: acTable.map(a => ({ id: a.id, relatedUc: a.relatedUc })),
+      businessRules: businessRules.map(b => ({ id: b.id, appliesTo: b.appliesTo })),
+    }),
+  ]
+
+  console.log(JSON.stringify({ valid: errors.length === 0, errors }, null, 2))
+  process.exit(errors.length === 0 ? 0 : 1)
+}
+
+main()