gswd 0.1.0

package/lib/audit.ts

@@ -0,0 +1,959 @@
+/**
+ * GSWD Audit Module — Coverage matrix, checks, report generation, auto-fix, workflow
+ *
+ * Mechanically checks spec artifacts for coverage gaps, cross-reference integrity,
+ * and heading compliance. Produces PASS or actionable FAIL checklist in AUDIT.md.
+ *
+ * Schema: GSWD_SPEC.md Section 8.4 (audit workflow), 6.1-6.3 (IDs and headings)
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {
+  extractIds,
+  validateHeadings,
+  extractHeadingContent,
+  normalizeId,
+  REQUIRED_HEADINGS,
+  type ExtractedId,
+} from './parse.js';
+import { readState, writeState, updateStageStatus, writeCheckpoint, safeWriteFile } from './state.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface Finding {
+  id: string;
+  issue: string;
+  fix: string;
+  severity: 'error' | 'warning';
+}
+
+export interface CheckResult {
+  check: string;
+  passed: boolean;
+  findings: Finding[];
+}
+
+export interface CoverageMatrix {
+  journeyToFRs: Map<string, Set<string>>;
+  frToJourneys: Map<string, Set<string>>;
+  journeyToTests: Map<string, string[]>;
+  journeyToIntegrations: Map<string, Set<string>>;
+  integrationStatus: Map<string, { status: string; hasFallback: boolean }>;
+  frScopes: Map<string, string>;
+  allJourneyIds: string[];
+  allFRIds: string[];
+  allNFRIds: string[];
+  allIntegrationIds: string[];
+}
+
+export interface AuditResult {
+  passed: boolean;
+  checks: CheckResult[];
+  matrix: CoverageMatrix;
+  summary: { total_checks: number; passed: number; failed: number; findings_count: number };
+}
+
+// ─── ID Extraction ──────────────────────────────────────────────────────────
+
+/**
+ * Extract all ID types from artifact content using parse.ts extractIds().
+ * Works on content strings (not file paths) for testability.
+ */
+export function extractArtifactIds(content: string): {
+  journeyIds: ExtractedId[];
+  frIds: ExtractedId[];
+  nfrIds: ExtractedId[];
+  integrationIds: ExtractedId[];
+} {
+  if (!content) {
+    return { journeyIds: [], frIds: [], nfrIds: [], integrationIds: [] };
+  }
+
+  return {
+    journeyIds: extractIds(content, 'J'),
+    frIds: extractIds(content, 'FR'),
+    nfrIds: extractIds(content, 'NFR'),
+    integrationIds: extractIds(content, 'I'),
+  };
+}
+
+// ─── Journey Section Parsing ────────────────────────────────────────────────
+
+/**
+ * Split JOURNEYS.md by ### J-NNN headings.
+ * Returns map of normalized journey ID -> section content.
+ */
+export function parseJourneySections(journeysContent: string): Map<string, string> {
+  const sections = new Map<string, string>();
+  if (!journeysContent) return sections;
+
+  const journeyRegex = /^### (J-\d{1,4})[:.]?\s/gm;
+  const positions: { id: string; start: number }[] = [];
+
+  let match: RegExpExecArray | null;
+  while ((match = journeyRegex.exec(journeysContent)) !== null) {
+    positions.push({ id: normalizeId(match[1]), start: match.index });
+  }
+
+  for (let i = 0; i < positions.length; i++) {
+    const start = positions[i].start;
+    const end = i + 1 < positions.length ? positions[i + 1].start : journeysContent.length;
+    sections.set(positions[i].id, journeysContent.slice(start, end).trim());
+  }
+
+  return sections;
+}
+
+// ─── FR Scope Parsing ───────────────────────────────────────────────────────
+
+/**
+ * Extract FR scope tags from SPEC.md content.
+ * Looks for patterns: **Scope:** v1, Scope: v2, etc.
+ * Defaults to "v1" if scope not found (conservative).
+ */
+export function parseFRScope(specContent: string): Map<string, string> {
+  const scopes = new Map<string, string>();
+  if (!specContent) return scopes;
+
+  // First, find all FR IDs in the content
+  const frIds = extractIds(specContent, 'FR');
+
+  // Split by FR headings to get per-FR sections
+  const frRegex = /^###?\s+(FR-\d{1,4})[:.]?\s/gm;
+  const positions: { id: string; start: number }[] = [];
+
+  let match: RegExpExecArray | null;
+  while ((match = frRegex.exec(specContent)) !== null) {
+    positions.push({ id: normalizeId(match[1]), start: match.index });
+  }
+
+  // Extract scope from each FR section
+  for (let i = 0; i < positions.length; i++) {
+    const start = positions[i].start;
+    const end = i + 1 < positions.length ? positions[i + 1].start : specContent.length;
+    const section = specContent.slice(start, end);
+
+    const scopeMatch = section.match(/\*{0,2}Scope:?\*{0,2}:?\s*(v1|v2|out)/i);
+    if (scopeMatch) {
+      scopes.set(positions[i].id, scopeMatch[1].toLowerCase());
+    } else {
+      scopes.set(positions[i].id, 'v1'); // Conservative default
+    }
+  }
+
+  // Also catch any FR IDs found by extractIds that weren't in heading positions
+  for (const fr of frIds) {
+    if (!scopes.has(fr.id)) {
+      scopes.set(fr.id, 'v1'); // Conservative default
+    }
+  }
+
+  return scopes;
+}
+
+// ─── Integration Status Parsing ─────────────────────────────────────────────
+
+/**
+ * Parse integration statuses from INTEGRATIONS.md.
+ * Looks for Status: and Fallback: fields per integration.
+ */
+export function parseIntegrationStatus(
+  integrationsContent: string
+): Map<string, { status: string; hasFallback: boolean }> {
+  const statuses = new Map<string, { status: string; hasFallback: boolean }>();
+  if (!integrationsContent) return statuses;
+
+  // Split by integration headings (### I-NNN)
+  const intRegex = /^###?\s+(I-\d{1,4})[:.]?\s/gm;
+  const positions: { id: string; start: number }[] = [];
+
+  let match: RegExpExecArray | null;
+  while ((match = intRegex.exec(integrationsContent)) !== null) {
+    positions.push({ id: normalizeId(match[1]), start: match.index });
+  }
+
+  for (let i = 0; i < positions.length; i++) {
+    const start = positions[i].start;
+    const end = i + 1 < positions.length ? positions[i + 1].start : integrationsContent.length;
+    const section = integrationsContent.slice(start, end);
+
+    const statusMatch = section.match(/\*{0,2}Status:?\*{0,2}:?\s*(\w+)/i);
+    const fallbackMatch = section.match(/^\*{0,2}Fallback:?\*{0,2}:?\s*(.+)/im);
+
+    const status = statusMatch ? statusMatch[1].toLowerCase() : 'unknown';
+    const hasFallback = fallbackMatch !== null && fallbackMatch[1].trim().length > 0;
+
+    statuses.set(positions[i].id, { status, hasFallback });
+  }
+
+  return statuses;
+}
+
+// ─── Acceptance Test Parsing ────────────────────────────────────────────────
+
+/**
+ * Parse acceptance tests from a journey section.
+ * Looks for "Acceptance Test" heading or bullet items after it.
+ */
+function parseAcceptanceTests(journeySection: string): string[] {
+  const tests: string[] = [];
+  if (!journeySection) return tests;
+
+  // Look for acceptance test section (various heading patterns)
+  const testSectionRegex = /(?:####?\s*Acceptance\s+Tests?|####?\s*Tests?)(?:\n|\r\n?)([\s\S]*?)(?=####?\s|\n##\s|$)/i;
+  const sectionMatch = journeySection.match(testSectionRegex);
+
+  if (sectionMatch) {
+    const testContent = sectionMatch[1];
+    // Extract bullet items
+    const bullets = testContent.match(/^[-*]\s+.+/gm);
+    if (bullets) {
+      for (const bullet of bullets) {
+        const text = bullet.replace(/^[-*]\s+/, '').trim();
+        if (text.length > 0) {
+          tests.push(text);
+        }
+      }
+    }
+    // Also check for checkbox items
+    const checkboxes = testContent.match(/^[-*]\s+\[[ x]\]\s+.+/gm);
+    if (checkboxes) {
+      for (const cb of checkboxes) {
+        const text = cb.replace(/^[-*]\s+\[[ x]\]\s+/, '').trim();
+        if (text.length > 0 && !tests.includes(text)) {
+          tests.push(text);
+        }
+      }
+    }
+  }
+
+  return tests;
+}
+
+// ─── Coverage Matrix Construction ───────────────────────────────────────────
+
+/**
+ * Build the full coverage matrix from spec artifact contents.
+ */
+export function buildCoverageMatrix(files: {
+  journeys?: string;
+  spec?: string;
+  nfr?: string;
+  integrations?: string;
+  architecture?: string;
+}): CoverageMatrix {
+  const journeyToFRs = new Map<string, Set<string>>();
+  const frToJourneys = new Map<string, Set<string>>();
+  const journeyToTests = new Map<string, string[]>();
+  const journeyToIntegrations = new Map<string, Set<string>>();
+
+  // Parse journey sections
+  const journeySections = parseJourneySections(files.journeys || '');
+
+  for (const [journeyId, section] of journeySections) {
+    // Extract FR references in this journey section
+    const frRefs = extractIds(section, 'FR');
+    const frSet = new Set(frRefs.map((f) => f.id));
+    journeyToFRs.set(journeyId, frSet);
+
+    // Build reverse map
+    for (const frId of frSet) {
+      if (!frToJourneys.has(frId)) {
+        frToJourneys.set(frId, new Set());
+      }
+      frToJourneys.get(frId)!.add(journeyId);
+    }
+
+    // Extract acceptance tests
+    const tests = parseAcceptanceTests(section);
+    journeyToTests.set(journeyId, tests);
+
+    // Extract integration references
+    const intRefs = extractIds(section, 'I');
+    const intSet = new Set(intRefs.map((i) => i.id));
+    journeyToIntegrations.set(journeyId, intSet);
+  }
+
+  // Parse FR scopes from SPEC.md
+  const frScopes = parseFRScope(files.spec || '');
+
+  // Parse integration statuses
+  const integrationStatus = parseIntegrationStatus(files.integrations || '');
+
+  // Collect all unique IDs
+  const allJourneyIds = Array.from(journeySections.keys()).sort();
+  const allFRIdSet = new Set<string>();
+  const allNFRIdSet = new Set<string>();
+  const allIntIdSet = new Set<string>();
+
+  // From all files
+  for (const content of Object.values(files)) {
+    if (!content) continue;
+    for (const id of extractIds(content, 'FR')) allFRIdSet.add(id.id);
+    for (const id of extractIds(content, 'NFR')) allNFRIdSet.add(id.id);
+    for (const id of extractIds(content, 'I')) allIntIdSet.add(id.id);
+  }
+
+  return {
+    journeyToFRs,
+    frToJourneys,
+    journeyToTests,
+    journeyToIntegrations,
+    integrationStatus,
+    frScopes,
+    allJourneyIds,
+    allFRIds: Array.from(allFRIdSet).sort(),
+    allNFRIds: Array.from(allNFRIdSet).sort(),
+    allIntegrationIds: Array.from(allIntIdSet).sort(),
+  };
+}
+
+// ─── Audit Checks ───────────────────────────────────────────────────────────
+
+/**
+ * Check: Every journey references >= 1 FR (AUDT-02 partial)
+ */
+export function checkJourneyFRCoverage(matrix: CoverageMatrix): CheckResult {
+  const findings: Finding[] = [];
+
+  for (const journeyId of matrix.allJourneyIds) {
+    const frSet = matrix.journeyToFRs.get(journeyId);
+    if (!frSet || frSet.size === 0) {
+      findings.push({
+        id: journeyId,
+        issue: 'Journey references no functional requirements',
+        fix: `Add FR-XXX references to journey ${journeyId} in JOURNEYS.md`,
+        severity: 'error',
+      });
+    }
+  }
+
+  return { check: 'journey_fr_coverage', passed: findings.length === 0, findings };
+}
+
+/**
+ * Check: Every journey has >= 1 acceptance test (AUDT-02 partial)
+ */
+export function checkJourneyTestCoverage(matrix: CoverageMatrix): CheckResult {
+  const findings: Finding[] = [];
+
+  for (const journeyId of matrix.allJourneyIds) {
+    const tests = matrix.journeyToTests.get(journeyId);
+    if (!tests || tests.length === 0) {
+      findings.push({
+        id: journeyId,
+        issue: 'Journey has no acceptance tests',
+        fix: `Add at least one acceptance test to journey ${journeyId} in JOURNEYS.md`,
+        severity: 'error',
+      });
+    }
+  }
+
+  return { check: 'journey_test_coverage', passed: findings.length === 0, findings };
+}
+
+/**
+ * Check: Every Scope:v1 FR is referenced by >= 1 journey (AUDT-03)
+ * Skips v2 and out-of-scope FRs.
+ */
+export function checkOrphanV1FRs(matrix: CoverageMatrix): CheckResult {
+  const findings: Finding[] = [];
+
+  for (const frId of matrix.allFRIds) {
+    const scope = matrix.frScopes.get(frId) || 'v1'; // Default to v1 (conservative)
+    if (scope !== 'v1') continue; // Only check v1 FRs
+
+    const journeys = matrix.frToJourneys.get(frId);
+    if (!journeys || journeys.size === 0) {
+      findings.push({
+        id: frId,
+        issue: 'v1 FR not referenced by any journey',
+        fix: `Add reference to ${frId} in a relevant journey in JOURNEYS.md, or change scope to v2 if not v1 priority`,
+        severity: 'error',
+      });
+    }
+  }
+
+  return { check: 'orphan_v1_frs', passed: findings.length === 0, findings };
+}
+
+/**
+ * Check: No unapproved integration referenced by v1 journey without fallback (AUDT-04)
+ */
+export function checkIntegrationApproval(matrix: CoverageMatrix): CheckResult {
+  const findings: Finding[] = [];
+  const reported = new Set<string>();
+
+  for (const [journeyId, intSet] of matrix.journeyToIntegrations) {
+    for (const intId of intSet) {
+      if (reported.has(intId)) continue;
+
+      const intStatus = matrix.integrationStatus.get(intId);
+      if (!intStatus) {
+        // Integration referenced but not found in INTEGRATIONS.md
+        findings.push({
+          id: intId,
+          issue: `Integration referenced by journey ${journeyId} but not defined in INTEGRATIONS.md`,
+          fix: `Add integration ${intId} section to INTEGRATIONS.md with Status and Fallback fields`,
+          severity: 'error',
+        });
+        reported.add(intId);
+        continue;
+      }
+
+      const isApproved = intStatus.status === 'approved';
+      const isDeferredWithFallback = intStatus.status === 'deferred' && intStatus.hasFallback;
+
+      if (!isApproved && !isDeferredWithFallback) {
+        findings.push({
+          id: intId,
+          issue: `Unapproved integration referenced by v1 journey ${journeyId} without fallback`,
+          fix: `Approve integration ${intId} in INTEGRATIONS.md, or add a fallback strategy (Status: deferred, Fallback: [description])`,
+          severity: 'error',
+        });
+        reported.add(intId);
+      }
+    }
+  }
+
+  return { check: 'integration_approval', passed: findings.length === 0, findings };
+}
+
+/**
+ * Check: All required headings exist in artifact files (AUDT-05)
+ */
+export function checkRequiredHeadings(files: Record<string, string>): CheckResult {
+  const findings: Finding[] = [];
+
+  for (const fileType of Object.keys(REQUIRED_HEADINGS)) {
+    const content = files[fileType];
+    // Only check files that were provided in the map
+    if (content === undefined) continue;
+    if (content === null || content === '') {
+      findings.push({
+        id: fileType,
+        issue: `Artifact file ${fileType} is missing or empty`,
+        fix: `Create ${fileType} with required headings`,
+        severity: 'error',
+      });
+      continue;
+    }
+
+    const validation = validateHeadings(content, fileType);
+    if (!validation.valid) {
+      for (const heading of validation.missing) {
+        findings.push({
+          id: fileType,
+          issue: `Missing required heading: ${heading}`,
+          fix: `Add '${heading}' section to ${fileType}`,
+          severity: 'error',
+        });
+      }
+    }
+  }
+
+  return { check: 'required_headings', passed: findings.length === 0, findings };
+}
+
+// ─── Audit Orchestrator ─────────────────────────────────────────────────────
+
+/**
+ * Run all audit checks and return structured result.
+ */
+export function runAudit(files: {
+  journeys?: string;
+  spec?: string;
+  nfr?: string;
+  integrations?: string;
+  architecture?: string;
+}): AuditResult {
+  // Build coverage matrix
+  const matrix = buildCoverageMatrix(files);
+
+  // Run all 5 checks
+  const checks: CheckResult[] = [
+    checkJourneyFRCoverage(matrix),
+    checkJourneyTestCoverage(matrix),
+    checkOrphanV1FRs(matrix),
+    checkIntegrationApproval(matrix),
+    checkRequiredHeadings({
+      'JOURNEYS.md': files.journeys || '',
+      'SPEC.md': files.spec || '',
+      'NFR.md': files.nfr || '',
+      'INTEGRATIONS.md': files.integrations || '',
+      // Only check ARCHITECTURE.md when it is present and non-empty (file is optional)
+      ...(files.architecture ? { 'ARCHITECTURE.md': files.architecture } : {}),
+    }),
+  ];
+
+  // Compute summary
+  const passedChecks = checks.filter((c) => c.passed).length;
+  const failedChecks = checks.filter((c) => !c.passed).length;
+  const totalFindings = checks.reduce((sum, c) => sum + c.findings.length, 0);
+
+  return {
+    passed: failedChecks === 0,
+    checks,
+    matrix,
+    summary: {
+      total_checks: checks.length,
+      passed: passedChecks,
+      failed: failedChecks,
+      findings_count: totalFindings,
+    },
+  };
+}
+
+// ─── Report Generation (Plan 04-02) ─────────────────────────────────────────
+
+/** Human-readable check name mapping */
+const CHECK_NAMES: Record<string, string> = {
+  journey_fr_coverage: 'Journey FR Coverage',
+  journey_test_coverage: 'Journey Test Coverage',
+  orphan_v1_frs: 'Orphan v1 FRs',
+  integration_approval: 'Integration Approval',
+  required_headings: 'Required Headings',
+};
+
+/**
+ * Format coverage matrix as a markdown table.
+ * Sorted by journey ID ascending.
+ */
+export function formatCoverageMatrixTable(matrix: CoverageMatrix): string {
+  const header = '| Journey | Linked FRs | Linked NFRs | Acceptance Tests | Integrations | Status |';
+  const separator = '|---------|------------|-------------|------------------|--------------|--------|';
+  const rows: string[] = [];
+
+  for (const journeyId of matrix.allJourneyIds) {
+    const frs = matrix.journeyToFRs.get(journeyId);
+    const tests = matrix.journeyToTests.get(journeyId) || [];
+    const integrations = matrix.journeyToIntegrations.get(journeyId);
+
+    // Collect NFRs referenced in this journey (from all content — approximate via allNFRIds for now)
+    const frList = frs && frs.size > 0 ? Array.from(frs).sort().join(', ') : '(none)';
+    const nfrList = '(none)'; // NFR cross-reference is not tracked per-journey in the matrix
+    const testCount = `${tests.length} test${tests.length !== 1 ? 's' : ''}`;
+    const intList = integrations && integrations.size > 0 ? Array.from(integrations).sort().join(', ') : '-';
+
+    // Status: PASS if has FRs and tests, FAIL with reason otherwise
+    const hasFRs = frs && frs.size > 0;
+    const hasTests = tests.length > 0;
+    let status: string;
+    if (hasFRs && hasTests) {
+      status = 'PASS';
+    } else if (!hasFRs && !hasTests) {
+      status = 'FAIL: no FRs, no tests';
+    } else if (!hasFRs) {
+      status = 'FAIL: no FRs';
+    } else {
+      status = 'FAIL: no tests';
+    }
+
+    rows.push(`| ${journeyId} | ${frList} | ${nfrList} | ${testCount} | ${intList} | ${status} |`);
+  }
+
+  return [header, separator, ...rows].join('\n');
+}
+
+/**
+ * Format a single check result as a markdown section.
+ */
+export function formatCheckSection(result: CheckResult): string {
+  const name = CHECK_NAMES[result.check] || result.check;
+  const lines: string[] = [];
+
+  lines.push(`### ${name}`);
+
+  if (result.passed) {
+    lines.push(`**Status:** PASS`);
+  } else {
+    lines.push(`**Status:** FAIL`);
+    lines.push('');
+    lines.push('**Issues:**');
+    for (const finding of result.findings) {
+      lines.push(`- [ ] **${finding.id}**: ${finding.issue}`);
+      lines.push(`  Fix: ${finding.fix}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate full AUDIT.md report content from audit result.
+ * Groups findings by check type. FAIL includes actionable checklist.
+ */
+export function generateAuditReport(result: AuditResult): string {
+  const lines: string[] = [];
+
+  // Header
+  lines.push('# Audit Report');
+  lines.push('');
+  lines.push(`**Date:** ${new Date().toISOString().split('T')[0]}`);
+  lines.push(`**Result:** ${result.passed ? 'PASS' : 'FAIL'}`);
+  lines.push(`**Summary:** ${result.summary.passed}/${result.summary.total_checks} checks passed, ${result.summary.findings_count} issue(s) found`);
+  lines.push('');
+
+  // Coverage Matrix
+  lines.push('## Coverage Matrix');
+  lines.push('');
+  lines.push(formatCoverageMatrixTable(result.matrix));
+  lines.push('');
+
+  // Coverage Statistics
+  lines.push('## Coverage Statistics');
+  lines.push('');
+  lines.push('| Metric | Count |');
+  lines.push('|--------|-------|');
+  lines.push(`| Journeys | ${result.matrix.allJourneyIds.length} |`);
+  lines.push(`| Functional Requirements | ${result.matrix.allFRIds.length} |`);
+  lines.push(`| Non-Functional Requirements | ${result.matrix.allNFRIds.length} |`);
+  lines.push(`| Integrations | ${result.matrix.allIntegrationIds.length} |`);
+  lines.push('');
+
+  // Check Results (grouped by check type)
+  lines.push('## Check Results');
+  lines.push('');
+  for (const check of result.checks) {
+    lines.push(formatCheckSection(check));
+    lines.push('');
+  }
+
+  // Actionable Checklist (only on FAIL)
+  if (!result.passed) {
+    lines.push('## Actionable Checklist');
+    lines.push('');
+    for (const check of result.checks) {
+      if (!check.passed) {
+        for (const finding of check.findings) {
+          lines.push(`- [ ] **${finding.id}**: ${finding.issue}`);
+          lines.push(`  Fix: ${finding.fix}`);
+        }
+      }
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+// ─── Auto-Fix (Plan 04-02) ──────────────────────────────────────────────────
+
+export interface AutoFixChange {
+  file: string;
+  change: string;
+  finding: Finding;
+}
+
+export interface AutoFixResult {
+  applied: AutoFixChange[];
+  skipped: Finding[];
+  updatedFiles: Map<string, string>;
+}
+
+/**
+ * Apply surgical auto-fixes to spec artifacts.
+ *
+ * CAN do:
+ *  - Add stub acceptance tests for journeys missing them
+ *  - Add fallback stubs for unapproved integrations
+ *
+ * CANNOT do:
+ *  - Invent new FRs, journeys, or integrations
+ *  - Approve paid integrations
+ *  - Change existing content (only append)
+ */
+export function applyAutoFix(
+  result: AuditResult,
+  files: Record<string, string>
+): AutoFixResult {
+  const applied: AutoFixChange[] = [];
+  const skipped: Finding[] = [];
+  const updatedFiles = new Map<string, string>();
+
+  // Initialize updatedFiles with copies of originals
+  for (const [name, content] of Object.entries(files)) {
+    updatedFiles.set(name, content);
+  }
+
+  for (const check of result.checks) {
+    if (check.passed) continue;
+
+    for (const finding of check.findings) {
+      switch (check.check) {
+        case 'journey_test_coverage': {
+          // Can fix: add stub acceptance test
+          const journeyId = finding.id;
+          let journeysContent = updatedFiles.get('JOURNEYS.md') || '';
+
+          // Find the journey section and append a stub test
+          const journeyHeadingRegex = new RegExp(
+            `(### ${journeyId.replace('-', '\\-')}[:\\.]?\\s[^\\n]*\\n)`,
+            'm'
+          );
+          const headingMatch = journeysContent.match(journeyHeadingRegex);
+
+          if (headingMatch) {
+            // Find where this journey section ends (next ### or end of file)
+            const headingIdx = journeysContent.indexOf(headingMatch[0]);
+            const nextHeadingIdx = journeysContent.indexOf('\n### ', headingIdx + headingMatch[0].length);
+            const insertPoint = nextHeadingIdx !== -1 ? nextHeadingIdx : journeysContent.length;
+
+            const stubTest = `\n#### Acceptance Tests\n- [ ] Verify that ${journeyId} completes successfully\n`;
+            journeysContent =
+              journeysContent.slice(0, insertPoint) + stubTest + journeysContent.slice(insertPoint);
+
+            updatedFiles.set('JOURNEYS.md', journeysContent);
+            applied.push({
+              file: 'JOURNEYS.md',
+              change: `Added stub acceptance test for ${journeyId}`,
+              finding,
+            });
+          } else {
+            skipped.push(finding);
+          }
+          break;
+        }
+
+        case 'integration_approval': {
+          // Can fix: add fallback stub (NOT approval)
+          const intId = finding.id;
+          let intContent = updatedFiles.get('INTEGRATIONS.md') || '';
+
+          // Find the integration section
+          const intHeadingRegex = new RegExp(
+            `(### ${intId.replace('-', '\\-')}[:\\.]?\\s[^\\n]*\\n)`,
+            'm'
+          );
+          const intMatch = intContent.match(intHeadingRegex);
+
+          if (intMatch) {
+            const intHeadingIdx = intContent.indexOf(intMatch[0]);
+            const nextIntHeading = intContent.indexOf('\n### ', intHeadingIdx + intMatch[0].length);
+            const insertPoint = nextIntHeading !== -1 ? nextIntHeading : intContent.length;
+
+            const fallbackStub = `\n**Fallback:** manual setup\n`;
+            intContent =
+              intContent.slice(0, insertPoint) + fallbackStub + intContent.slice(insertPoint);
+
+            updatedFiles.set('INTEGRATIONS.md', intContent);
+            applied.push({
+              file: 'INTEGRATIONS.md',
+              change: `Added fallback stub for unapproved integration ${intId}`,
+              finding,
+            });
+          } else {
+            skipped.push(finding);
+          }
+          break;
+        }
+
+        case 'orphan_v1_frs': {
+          // CANNOT fix: would require inventing journey references or new journeys
+          skipped.push(finding);
+          break;
+        }
+
+        case 'journey_fr_coverage': {
+          // CANNOT fix: would require inventing new FR references
+          skipped.push(finding);
+          break;
+        }
+
+        case 'required_headings': {
+          // CANNOT fix reliably: would require inventing content
+          skipped.push(finding);
+          break;
+        }
+
+        default: {
+          skipped.push(finding);
+          break;
+        }
+      }
+    }
+  }
+
+  return { applied, skipped, updatedFiles };
+}
+
+// ─── Hard Gate Enforcement (Plan 04-02) ──────────────────────────────────────
+
+/**
+ * Check audit gate: returns true ONLY when audit status is "pass".
+ * Fail-closed: returns false for any non-"pass" state, including read errors.
+ */
+export function checkAuditGate(statePath: string): boolean {
+  try {
+    const state = readState(statePath);
+    if (!state) return false;
+    return state.stage_status.audit === 'pass';
+  } catch {
+    return false; // Fail-closed
+  }
+}
+
+/**
+ * Update STATE.json with audit result.
+ * Sets stage_status.audit to "pass" or "fail".
+ * On pass: also updates stage to "audit".
+ */
+export function updateAuditState(statePath: string, passed: boolean): void {
+  updateStageStatus(statePath, 'audit', passed ? 'pass' : 'fail');
+
+  if (passed) {
+    const state = readState(statePath);
+    if (state) {
+      state.stage = 'audit';
+      writeState(statePath, state);
+    }
+  }
+}
+
+// ─── Workflow Orchestrator (Plan 04-03) ───────────────────────────────────────
+
+export interface AuditWorkflowResult {
+  passed: boolean;
+  auditResult: AuditResult;
+  reportPath: string;        // Path to written AUDIT.md
+  autoFixCycles: number;     // How many auto-fix cycles ran (0 if no auto-fix)
+  autoFixChanges: AutoFixChange[]; // All changes made across cycles
+}
+
+/**
+ * Read all spec artifact files from a planning directory.
+ * Returns a content map. Missing files get empty string (audit checks will flag them).
+ */
+export function readArtifactFiles(planningDir: string): Record<string, string> {
+  const fileMap: Array<[string, string]> = [
+    ['JOURNEYS.md', 'journeys'],
+    ['SPEC.md', 'spec'],
+    ['NFR.md', 'nfr'],
+    ['INTEGRATIONS.md', 'integrations'],
+    ['ARCHITECTURE.md', 'architecture'], // optional
+  ];
+
+  const result: Record<string, string> = {};
+  for (const [filename, key] of fileMap) {
+    try {
+      result[key] = fs.readFileSync(path.join(planningDir, filename), 'utf-8');
+    } catch {
+      result[key] = '';
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Write AUDIT.md atomically to the planning directory.
+ * Returns the written file path.
+ */
+export function writeAuditReport(planningDir: string, reportContent: string): string {
+  const reportPath = path.join(planningDir, 'AUDIT.md');
+  safeWriteFile(reportPath, reportContent);
+  return reportPath;
+}
+
+/**
+ * Returns the list of artifact file names that audit checks.
+ */
+export function getAuditableFileTypes(): string[] {
+  return ['JOURNEYS.md', 'SPEC.md', 'NFR.md', 'INTEGRATIONS.md'];
+}
+
+/**
+ * Full audit workflow orchestrator.
+ *
+ * Steps:
+ *   1. Update state -> in_progress
+ *   2. Read all artifact files
+ *   3. Run audit
+ *   4. If PASS -> generate report, write AUDIT.md, update state -> pass, write checkpoint, return
+ *   5. If FAIL and autoFix enabled:
+ *      - Run auto-fix cycles (max 2 by default per GSWD_SPEC Section 10.4)
+ *      - Write fixed files to disk after each cycle
+ *      - Re-read files and re-run audit
+ *   6. Generate report, write AUDIT.md, update state -> pass or fail, write checkpoint
+ */
+export function runAuditWorkflow(options: {
+  planningDir: string;
+  statePath: string;
+  autoFix?: boolean;
+  maxCycles?: number;
+}): AuditWorkflowResult {
+  const { planningDir, statePath, autoFix = false, maxCycles = 2 } = options;
+  const allAutoFixChanges: AutoFixChange[] = [];
+  let autoFixCycles = 0;
+
+  // Step 1: Update state -> in_progress
+  updateStageStatus(statePath, 'audit', 'in_progress');
+
+  // Step 2: Read all artifact files
+  let files = readArtifactFiles(planningDir);
+
+  // Build the file name map used for auto-fix (keyed by filename, not key)
+  const fileNameKeys: Record<string, string> = {
+    journeys: 'JOURNEYS.md',
+    spec: 'SPEC.md',
+    nfr: 'NFR.md',
+    integrations: 'INTEGRATIONS.md',
+    architecture: 'ARCHITECTURE.md',
+  };
+
+  // Step 3: Run audit
+  let auditResult = runAudit(files);
+
+  // Step 4: If PASS or no auto-fix, skip loop
+  if (!auditResult.passed && autoFix) {
+    // Step 5: Auto-fix loop
+    while (autoFixCycles < maxCycles && !auditResult.passed) {
+      // Build the named-file map for applyAutoFix (uses filename keys)
+      const namedFiles: Record<string, string> = {};
+      for (const [key, filename] of Object.entries(fileNameKeys)) {
+        if (files[key] !== undefined) {
+          namedFiles[filename] = files[key];
+        }
+      }
+
+      // Apply auto-fix
+      const fixResult = applyAutoFix(auditResult, namedFiles);
+      allAutoFixChanges.push(...fixResult.applied);
+
+      // Write fixed files to disk
+      for (const [filename, content] of fixResult.updatedFiles) {
+        const filePath = path.join(planningDir, filename);
+        safeWriteFile(filePath, content);
+      }
+
+      autoFixCycles++;
+
+      // Re-read files (they may have been modified)
+      files = readArtifactFiles(planningDir);
+
+      // Re-run audit
+      auditResult = runAudit(files);
+    }
+  }
+
+  // Generate report (with final result)
+  const reportContent = generateAuditReport(auditResult);
+
+  // Write AUDIT.md
+  const reportPath = writeAuditReport(planningDir, reportContent);
+
+  // Update state -> pass or fail
+  updateAuditState(statePath, auditResult.passed);
+
+  // Write checkpoint
+  writeCheckpoint(statePath, 'gswd/audit-spec', `audit-${auditResult.passed ? 'pass' : 'fail'}`);
+
+  return {
+    passed: auditResult.passed,
+    auditResult,
+    reportPath,
+    autoFixCycles,
+    autoFixChanges: allAutoFixChanges,
+  };
+}