@nforma.ai/nforma 0.2.1

package/bin/check-spec-sync.cjs

@@ -0,0 +1,360 @@
+#!/usr/bin/env node
+'use strict';
+// bin/check-spec-sync.cjs
+// Verifies that formal specs stay in sync with the XState machine.
+//
+// The XState machine (src/machines/qgsd-workflow.machine.ts) is the SOURCE OF TRUTH.
+// Formal specs must mirror it — not the other way around.
+//
+// Checks:
+//   1. State names in QGSDQuorum.tla TypeOK match the XState machine states
+//   2. MaxDeliberation in MCsafety.cfg and MCliveness.cfg matches the XState context default
+//   3. Initial state in QGSDQuorum.tla Init matches the XState initial state
+//   4. Alloy .als files do not reference state names or guard names not in XState machine
+//   5. Guard names in XState machine match keys in .planning/formal/tla/guards/qgsd-workflow.json (bidirectional)
+//
+// Exit 0 = in sync; Exit 1 = drift detected.
+// Usage: node bin/check-spec-sync.cjs [--tla-path=<path>] [--guards-path=<path>]
+//
+// CLI overrides (for fixture-based tests):
+//   --tla-path=<abs-path>    Override path to QGSDQuorum.tla (default: .planning/formal/tla/QGSDQuorum.tla)
+//   --guards-path=<abs-path> Override path to guards JSON (default: .planning/formal/tla/guards/qgsd-workflow.json)
+
+const { buildSync } = require('esbuild');
+const fs   = require('fs');
+const os   = require('os');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+
+// ── CLI overrides (for fixture-based drift injection tests) ───────────────────
+// These allow tests to substitute temp fixture files without modifying the repo.
+const tlaPathOverride   = process.argv.find(a => a.startsWith('--tla-path='));
+const guardsPathOverride = process.argv.find(a => a.startsWith('--guards-path='));
+
+// Resolved paths (absolute)
+const TLA_ABS_PATH = tlaPathOverride
+  ? tlaPathOverride.slice('--tla-path='.length)
+  : path.join(ROOT, '.planning', 'formal', 'tla', 'QGSDQuorum.tla');
+
+const GUARDS_ABS_PATH = guardsPathOverride
+  ? guardsPathOverride.slice('--guards-path='.length)
+  : path.join(ROOT, '.planning', 'formal', 'tla', 'guards', 'qgsd-workflow.json');
+
+// ── Load files ───────────────────────────────────────────────────────────────
+function load(rel) {
+  const abs = path.join(ROOT, rel);
+  if (!fs.existsSync(abs)) {
+    process.stderr.write('[check-spec-sync] File not found: ' + rel + '\n');
+    process.exit(1);
+  }
+  return fs.readFileSync(abs, 'utf8');
+}
+
+function loadAbs(abs) {
+  if (!fs.existsSync(abs)) {
+    process.stderr.write('[check-spec-sync] File not found: ' + abs + '\n');
+    process.exit(1);
+  }
+  return fs.readFileSync(abs, 'utf8');
+}
+
+const tlaSrc      = loadAbs(TLA_ABS_PATH);
+const safetyCfg   = load('.planning/formal/tla/MCsafety.cfg');
+const livenessCfg = load('.planning/formal/tla/MCliveness.cfg');
+
+// ── 1. Extract XState facts using esbuild+require() ────────────────────────────
+// Compile the TypeScript machine to a temporary CJS bundle, then require() it.
+// This gives us the live machine object — no regex parsing of raw source.
+
+const MACHINE_FILE = path.join(ROOT, 'src/machines/qgsd-workflow.machine.ts');
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'check-spec-sync-'));
+const tmpBundle = path.join(tmpDir, 'machine.cjs');
+
+let machineObj = null;
+let xstateExtractError = null;
+
+try {
+  buildSync({
+    entryPoints: [MACHINE_FILE],
+    bundle: true,
+    platform: 'node',
+    format: 'cjs',
+    outfile: tmpBundle,
+    logLevel: 'silent',
+  });
+  const m = require(tmpBundle);
+  // Find the exported machine — look for .config property (XState v5 machine)
+  machineObj = Object.values(m).find(v => v && typeof v === 'object' && v.config);
+} catch (err) {
+  xstateExtractError = err.message;
+}
+
+// Extract structural facts from the machine object
+let xstateStateNames = [];
+let xstateGuardNames = [];
+let xstateEventNames = [];
+let xstateMaxDelib = null;
+let xstateInitial = null;
+
+if (machineObj && machineObj.config) {
+  const cfg = machineObj.config;
+
+  // State names (all top-level states)
+  xstateStateNames = Object.keys(cfg.states || {});
+
+  // Initial state
+  xstateInitial = cfg.initial || null;
+
+  // Guard names from implementations.guards
+  const impls = machineObj.implementations || {};
+  xstateGuardNames = Object.keys(impls.guards || {});
+
+  // Event names from all transitions across all states
+  const eventSet = new Set();
+  for (const stateCfg of Object.values(cfg.states || {})) {
+    for (const evtName of Object.keys(stateCfg.on || {})) {
+      eventSet.add(evtName);
+    }
+  }
+  xstateEventNames = [...eventSet];
+
+  // maxDeliberation from context defaults
+  const ctxDefaults = cfg.context || {};
+  if (typeof ctxDefaults.maxDeliberation === 'number') {
+    xstateMaxDelib = ctxDefaults.maxDeliberation;
+  }
+} else if (xstateExtractError) {
+  // Fallback: use regex if esbuild fails (e.g., in environments without esbuild)
+  process.stderr.write('[check-spec-sync] esbuild extraction failed: ' + xstateExtractError + '\n');
+  process.stderr.write('[check-spec-sync] Falling back to regex extraction (limited)\n');
+  const machineSrc = load('src/machines/qgsd-workflow.machine.ts');
+  xstateStateNames = (machineSrc.match(/^    ([A-Z_]+):\s*\{/gm) || []).map(l => l.trim().split(':')[0]);
+  const md = machineSrc.match(/maxDeliberation:\s*(\d+)/);
+  xstateMaxDelib = md ? parseInt(md[1], 10) : null;
+  const im = machineSrc.match(/initial:\s*'([A-Z_]+)'/);
+  xstateInitial = im ? im[1] : null;
+}
+
+// ── 2. Extract TLA+ facts ────────────────────────────────────────────────────
+// Phase values in TypeOK: phase \in {"IDLE", "COLLECTING_VOTES", ...}
+const typeOkMatch = tlaSrc.match(/phase\s*\\in\s*\{([^}]+)\}/);
+const tlaPhaseValues = typeOkMatch
+  ? (typeOkMatch[1].match(/"([A-Z_]+)"/g) || []).map(s => s.replace(/"/g, ''))
+  : [];
+
+// Initial phase in Init block: find Init ==, then first phase = "..."
+const initBlockMatch = tlaSrc.match(/Init\s*==[\s\S]*?phase\s*=\s*"([A-Z_]+)"/);
+const tlaInitPhase = initBlockMatch ? initBlockMatch[1] : null;
+
+// ── 3. Extract MaxDeliberation from cfg files ─────────────────────────────────
+const safetyMaxDelibMatch   = safetyCfg.match(/MaxDeliberation\s*=\s*(\d+)/);
+const livenessMaxDelibMatch  = livenessCfg.match(/MaxDeliberation\s*=\s*(\d+)/);
+const safetyMaxDelib   = safetyMaxDelibMatch  ? parseInt(safetyMaxDelibMatch[1], 10)  : null;
+const livenessMaxDelib = livenessMaxDelibMatch ? parseInt(livenessMaxDelibMatch[1], 10) : null;
+
+// ── 4. Run checks ────────────────────────────────────────────────────────────
+const errors = [];
+const warnings = [];
+
+function fail(msg) { errors.push('  FAIL  ' + msg); }
+function warn(msg) { warnings.push('  WARN  ' + msg); }
+function ok(msg)   { process.stdout.write('  OK    ' + msg + '\n'); }
+
+process.stdout.write('\n[check-spec-sync] Source of truth: src/machines/qgsd-workflow.machine.ts\n\n');
+
+// Check 1: State names
+if (xstateStateNames.length === 0) {
+  fail('Could not extract state names from XState machine');
+} else {
+  ok('XState states: ' + xstateStateNames.join(', '));
+
+  if (tlaPhaseValues.length === 0) {
+    fail('Could not parse phase values from QGSDQuorum.tla TypeOK');
+  } else {
+    ok('TLA+ phases:  ' + tlaPhaseValues.join(', '));
+
+    const missing = xstateStateNames.filter(s => !tlaPhaseValues.includes(s));
+    const extra   = tlaPhaseValues.filter(s => !xstateStateNames.includes(s));
+
+    if (missing.length > 0) {
+      fail('XState states missing from TLA+ TypeOK: ' + missing.join(', '));
+    }
+    if (extra.length > 0) {
+      fail('TLA+ TypeOK has orphaned phases not in XState machine: ' + extra.join(', ') +
+        '\n         (These TLA+ phases have no corresponding XState state — update QGSDQuorum.tla)');
+    }
+    if (missing.length === 0 && extra.length === 0) {
+      ok('State names match exactly');
+    }
+  }
+}
+
+// Check 2: MaxDeliberation
+if (xstateMaxDelib === null) {
+  fail('Could not extract maxDeliberation from XState context defaults');
+} else {
+  ok('XState maxDeliberation: ' + xstateMaxDelib);
+
+  if (safetyMaxDelib === null) {
+    fail('Could not parse MaxDeliberation from MCsafety.cfg');
+  } else if (safetyMaxDelib !== xstateMaxDelib) {
+    fail(
+      'MCsafety.cfg MaxDeliberation=' + safetyMaxDelib +
+      ' does not match XState maxDeliberation=' + xstateMaxDelib
+    );
+  } else {
+    ok('MCsafety.cfg MaxDeliberation=' + safetyMaxDelib + ' matches');
+  }
+
+  if (livenessMaxDelib === null) {
+    fail('Could not parse MaxDeliberation from MCliveness.cfg');
+  } else if (livenessMaxDelib !== xstateMaxDelib) {
+    fail(
+      'MCliveness.cfg MaxDeliberation=' + livenessMaxDelib +
+      ' does not match XState maxDeliberation=' + xstateMaxDelib
+    );
+  } else {
+    ok('MCliveness.cfg MaxDeliberation=' + livenessMaxDelib + ' matches');
+  }
+}
+
+// Check 3: Initial state
+if (xstateInitial === null) {
+  fail('Could not extract initial state from XState machine');
+} else {
+  ok('XState initial state: ' + xstateInitial);
+
+  if (tlaInitPhase === null) {
+    fail('Could not parse Init phase from QGSDQuorum.tla');
+  } else if (tlaInitPhase !== xstateInitial) {
+    fail(
+      'TLA+ Init sets phase="' + tlaInitPhase +
+      '" but XState initial is "' + xstateInitial + '"'
+    );
+  } else {
+    ok('Initial state matches: "' + xstateInitial + '"');
+  }
+}
+
+// Check 4: Alloy orphan detection
+// Scan Alloy .als files for:
+//   (a) ALL_CAPS quoted string literals → cross-reference against xstateStateNames
+//   (b) camelCase guard name occurrences (verbatim word-boundary matches) → advisory cross-reference
+//
+// Note: Alloy orphan detection uses warn() not fail() because Alloy models are intentional
+// abstractions — they may use different predicate names (e.g., MajorityReached instead of
+// minQuorumMet). The authoritative guard mapping check is in Check 5 (guards/qgsd-workflow.json).
+const alloyDir = path.join(ROOT, '.planning', 'formal', 'alloy');
+if (fs.existsSync(alloyDir)) {
+  const alsFiles = fs.readdirSync(alloyDir).filter(f => f.endsWith('.als'));
+  for (const alsFile of alsFiles) {
+    const alsSrc = fs.readFileSync(path.join(alloyDir, alsFile), 'utf8');
+
+    // (a) State orphan scan: quoted ALL_CAPS string literals
+    const alloyStateRefs = (alsSrc.match(/"([A-Z_]{3,})"/g) || [])
+      .map(s => s.replace(/"/g, ''));
+    const orphanedStates = alloyStateRefs.filter(s => xstateStateNames.length > 0 && !xstateStateNames.includes(s));
+    if (orphanedStates.length > 0) {
+      warn('Alloy ' + alsFile + ' references states not in XState machine: ' + [...new Set(orphanedStates)].join(', '));
+    }
+
+    // (b) Guard name cross-reference: scan for verbatim camelCase XState guard names.
+    // Reports which XState guard names appear by exact name in the Alloy source (informational).
+    // Only flags Alloy files that reference XState guard names verbatim — PascalCase TLA+
+    // predicates (MinQuorumMet, DeliberationBounded) are NOT XState guard names and are not checked here.
+    if (xstateGuardNames.length > 0) {
+      const referencedGuards = xstateGuardNames.filter(g => {
+        const re = new RegExp('\\b' + g + '\\b');
+        return re.test(alsSrc);
+      });
+      if (referencedGuards.length > 0) {
+        ok('Alloy ' + alsFile + ' references XState guard names: ' + referencedGuards.join(', '));
+      }
+    }
+  }
+  ok('Alloy orphan scan complete');
+}
+
+// Check 5: Guard drift enforcement
+// Verify each XState guard name is documented in the TLA+ guard mapping file, and vice versa.
+//
+// Mapping context:
+//   XState uses camelCase guard names (minQuorumMet, noInfiniteDeliberation, phaseMonotonicallyAdvances).
+//   TLA+ uses PascalCase predicates (MinQuorumMet, DeliberationBounded) — different names, same semantics.
+//   The bridge is .planning/formal/tla/guards/qgsd-workflow.json, which maps XState guard names to TLA+ expressions.
+//
+//   If a guard is renamed in the XState machine, it must also be updated in guards/qgsd-workflow.json.
+//   If a mapping entry is removed from guards/qgsd-workflow.json without removing the guard from
+//   the machine (or vice versa), this check will detect the inconsistency.
+//
+// This check also corroborates by scanning QGSDQuorum.tla source text for camelCase guard name
+// occurrences (they appear in the header comment block as documentation of guard translations).
+if (xstateGuardNames.length > 0) {
+  if (!fs.existsSync(GUARDS_ABS_PATH)) {
+    fail('.planning/formal/tla/guards/qgsd-workflow.json not found — cannot verify guard name sync');
+  } else {
+    let guardsJson = null;
+    try {
+      guardsJson = JSON.parse(fs.readFileSync(GUARDS_ABS_PATH, 'utf8'));
+    } catch (e) {
+      fail('Could not parse guards JSON at ' + GUARDS_ABS_PATH + ': ' + e.message);
+    }
+    if (guardsJson) {
+      const mappedGuardNames = Object.keys(guardsJson.guards || {});
+      ok('XState guard names:           ' + xstateGuardNames.join(', '));
+      ok('Guards JSON mapped names:     ' + mappedGuardNames.join(', '));
+
+      // Forward check: XState guard → guards JSON (drift detection)
+      // If a guard is renamed in XState but guards/qgsd-workflow.json still has the old name, this fires.
+      const missingFromMapping = xstateGuardNames.filter(g => !mappedGuardNames.includes(g));
+      if (missingFromMapping.length > 0) {
+        fail(
+          'XState guards not found in guards/qgsd-workflow.json: ' + missingFromMapping.join(', ') +
+          '\n         (Update .planning/formal/tla/guards/qgsd-workflow.json to map these guard names to their TLA+ predicates)'
+        );
+      }
+
+      // Reverse check: guards JSON → XState (orphan detection)
+      // If a guard mapping entry exists in guards/qgsd-workflow.json but the guard was removed from
+      // the XState machine, this is an orphaned mapping.
+      const orphanedGuards = mappedGuardNames.filter(g => !xstateGuardNames.includes(g));
+      if (orphanedGuards.length > 0) {
+        fail(
+          'guards/qgsd-workflow.json references guards not in XState machine: ' + orphanedGuards.join(', ') +
+          '\n         (These guard mappings are orphaned — remove them or restore the XState guard)'
+        );
+      }
+
+      if (missingFromMapping.length === 0 && orphanedGuards.length === 0) {
+        ok('Guard names match exactly between XState machine and guards/qgsd-workflow.json');
+      }
+
+      // Corroboration: check TLA+ source mentions guard names in comment references
+      const tlaGuardRefs = xstateGuardNames.filter(g => tlaSrc.includes(g));
+      if (tlaGuardRefs.length > 0) {
+        ok('TLA+ source references guard names (comment docs): ' + tlaGuardRefs.join(', '));
+      }
+    }
+  }
+} else {
+  warn('No guard names extracted from XState machine — skipping guard drift check');
+}
+
+// ── 5. Report ────────────────────────────────────────────────────────────────
+if (warnings.length > 0) {
+  process.stdout.write('\nWarnings:\n');
+  warnings.forEach(w => process.stdout.write(w + '\n'));
+}
+
+if (errors.length > 0) {
+  process.stdout.write('\nSpec drift detected:\n');
+  errors.forEach(e => process.stderr.write(e + '\n'));
+  process.stdout.write(
+    '\nThe XState machine is the source of truth.\n' +
+    'Update the formal specs to match the code, then re-run this check.\n\n'
+  );
+  process.exit(1);
+}
+
+process.stdout.write('\nAll checks passed — formal specs are in sync with the XState machine.\n\n');

package/bin/check-trace-redaction.cjs

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+'use strict';
+// bin/check-trace-redaction.cjs
+// Validates trace event files against .planning/formal/trace/redaction.yaml policy.
+// Prevents secrets and PII from persisting in trace event artifacts.
+//
+// Exit code 0: no violations (or no trace directory/files)
+// Exit code 1: one or more violations found
+
+const fs   = require('fs');
+const path = require('path');
+const { writeCheckResult } = require('./write-check-result.cjs');
+const { getRequirementIds } = require('./requirement-map.cjs');
+
+const DEFAULT_POLICY_PATH = path.join(__dirname, '..', '.planning', 'formal', 'trace', 'redaction.yaml');
+
+/**
+ * Parse redaction.yaml using line-by-line regex (no external YAML parser).
+ * Handles two sections:
+ *   forbidden_keys:  - "key_name"
+ *   forbidden_patterns:  - name: "n"\n    regex: "r"
+ *
+ * @param {string} policyPath  Absolute path to redaction.yaml
+ * @returns {{ forbidden_keys: string[], forbidden_patterns: Array<{name: string, regex: string, compiled: RegExp}> }}
+ */
+function parseRedactionPolicy(policyPath) {
+  const yaml = fs.readFileSync(policyPath, 'utf8');
+  const lines = yaml.split('\n');
+
+  const forbidden_keys = [];
+  const forbidden_patterns = [];
+
+  let inKeys = false;
+  let inPatterns = false;
+  let currentPattern = null;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Section headers
+    if (trimmed === 'forbidden_keys:') {
+      inKeys = true;
+      inPatterns = false;
+      if (currentPattern) {
+        if (currentPattern.name && currentPattern.regex) {
+          forbidden_patterns.push({
+            name: currentPattern.name,
+            regex: currentPattern.regex,
+            compiled: new RegExp(currentPattern.regex),
+          });
+        }
+        currentPattern = null;
+      }
+      continue;
+    }
+    if (trimmed === 'forbidden_patterns:') {
+      inKeys = false;
+      inPatterns = true;
+      if (currentPattern) {
+        if (currentPattern.name && currentPattern.regex) {
+          forbidden_patterns.push({
+            name: currentPattern.name,
+            regex: currentPattern.regex,
+            compiled: new RegExp(currentPattern.regex),
+          });
+        }
+        currentPattern = null;
+      }
+      continue;
+    }
+
+    // Skip blank lines and top-level comments
+    if (trimmed === '' || (trimmed.startsWith('#') && !line.startsWith('  '))) {
+      continue;
+    }
+
+    if (inKeys) {
+      // Lines like:  - "api_key"  or  - api_key
+      const keyMatch = trimmed.match(/^-\s+"?([^"]+)"?$/);
+      if (keyMatch) {
+        forbidden_keys.push(keyMatch[1].trim());
+      }
+    }
+
+    if (inPatterns) {
+      // New pattern entry starts with "- name:"
+      const newEntryMatch = trimmed.match(/^-\s+name:\s+"?([^"]+)"?$/);
+      if (newEntryMatch) {
+        // Flush previous pattern
+        if (currentPattern && currentPattern.name && currentPattern.regex) {
+          forbidden_patterns.push({
+            name: currentPattern.name,
+            regex: currentPattern.regex,
+            compiled: new RegExp(currentPattern.regex),
+          });
+        }
+        currentPattern = { name: newEntryMatch[1].trim(), regex: null };
+        continue;
+      }
+      // Regex line within a pattern entry
+      const regexMatch = trimmed.match(/^regex:\s+"?(.+?)"?$/);
+      if (regexMatch && currentPattern) {
+        currentPattern.regex = regexMatch[1].trim();
+        continue;
+      }
+    }
+  }
+
+  // Flush last pattern
+  if (currentPattern && currentPattern.name && currentPattern.regex) {
+    forbidden_patterns.push({
+      name: currentPattern.name,
+      regex: currentPattern.regex,
+      compiled: new RegExp(currentPattern.regex),
+    });
+  }
+
+  return { forbidden_keys, forbidden_patterns };
+}
+
+/**
+ * Validate a single trace event object against the redaction policy.
+ * Returns an array of violation objects (empty if clean).
+ *
+ * @param {Object} event   Parsed trace event object
+ * @param {{ forbidden_keys: string[], forbidden_patterns: Array<{name: string, compiled: RegExp}> }} policy
+ * @returns {Array<{ key: string, value?: string, pattern_name?: string, violation_type: 'forbidden_key'|'forbidden_pattern' }>}
+ */
+function validateTraceEvent(event, policy) {
+  const violations = [];
+  if (!event || typeof event !== 'object') return violations;
+
+  for (const [key, value] of Object.entries(event)) {
+    // Check forbidden keys
+    if (policy.forbidden_keys.includes(key)) {
+      violations.push({ key, violation_type: 'forbidden_key' });
+    }
+
+    // Check forbidden patterns against string values
+    if (typeof value === 'string') {
+      for (const pattern of policy.forbidden_patterns) {
+        if (pattern.compiled.test(value)) {
+          violations.push({ key, value, pattern_name: pattern.name, violation_type: 'forbidden_pattern' });
+        }
+      }
+    }
+  }
+
+  return violations;
+}
+
+if (require.main === module) {
+  // Parse CLI args: optional --trace-dir <path>
+  let traceDir = path.join(process.cwd(), '.planning', 'formal', 'trace');
+  const args = process.argv.slice(2);
+  const traceDirIdx = args.indexOf('--trace-dir');
+  if (traceDirIdx !== -1 && args[traceDirIdx + 1]) {
+    traceDir = args[traceDirIdx + 1];
+  }
+
+  // Load policy
+  const policy = parseRedactionPolicy(DEFAULT_POLICY_PATH);
+
+  // Graceful: no trace directory
+  const _startMs = Date.now();
+  if (!fs.existsSync(traceDir)) {
+    try {
+      writeCheckResult({
+        tool: 'check-trace-redaction',
+        formalism: 'redaction',
+        result: 'pass',
+        check_id: 'ci:trace-redaction', surface: 'ci', property: 'Trace redaction — no forbidden keys or patterns in conformance event logs',
+        runtime_ms: Date.now() - _startMs, summary: 'pass: ci:trace-redaction in ' + (Date.now() - _startMs) + 'ms', triage_tags: [],
+        requirement_ids: getRequirementIds('ci:trace-redaction'),
+        metadata: { reason: 'no-trace-directory', directory: traceDir },
+      });
+    } catch (e) {
+      process.stderr.write('[check-trace-redaction] Warning: failed to write check result: ' + e.message + '\n');
+    }
+    process.exit(0);
+  }
+
+  // Find .json and .jsonl files (non-recursive)
+  const allFiles = fs.readdirSync(traceDir);
+  const traceFiles = allFiles.filter(f => f.endsWith('.json') || f.endsWith('.jsonl'));
+
+  if (traceFiles.length === 0) {
+    try {
+      writeCheckResult({
+        tool: 'check-trace-redaction',
+        formalism: 'redaction',
+        result: 'pass',
+        check_id: 'ci:trace-redaction', surface: 'ci', property: 'Trace redaction — no forbidden keys or patterns in conformance event logs',
+        runtime_ms: Date.now() - _startMs, summary: 'pass: ci:trace-redaction in ' + (Date.now() - _startMs) + 'ms', triage_tags: [],
+        requirement_ids: getRequirementIds('ci:trace-redaction'),
+        metadata: { reason: 'no-trace-events', directory: traceDir },
+      });
+    } catch (e) {
+      process.stderr.write('[check-trace-redaction] Warning: failed to write check result: ' + e.message + '\n');
+    }
+    process.exit(0);
+  }
+
+  // Scan all files — collect all violations (no fail-fast)
+  const allViolations = [];
+  let fileCount = 0;
+  let eventCount = 0;
+
+  for (const filename of traceFiles) {
+    const filePath = path.join(traceDir, filename);
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const fileLines = raw.split('\n').filter(l => l.trim().length > 0);
+    fileCount++;
+
+    for (const line of fileLines) {
+      let event;
+      try {
+        event = JSON.parse(line);
+      } catch (_) {
+        continue; // skip unparseable lines
+      }
+      eventCount++;
+      const violations = validateTraceEvent(event, policy);
+      for (const v of violations) {
+        allViolations.push({ file: filename, ...v });
+      }
+    }
+  }
+
+  const _runtimeMs = Date.now() - _startMs;
+  if (allViolations.length > 0) {
+    process.stdout.write('[check-trace-redaction] ' + allViolations.length + ' violation(s) found:\n');
+    for (const v of allViolations.slice(0, 10)) {
+      process.stdout.write('  ' + JSON.stringify(v) + '\n');
+    }
+    try {
+      writeCheckResult({
+        tool: 'check-trace-redaction',
+        formalism: 'redaction',
+        result: 'fail',
+        check_id: 'ci:trace-redaction', surface: 'ci', property: 'Trace redaction — no forbidden keys or patterns in conformance event logs',
+        runtime_ms: _runtimeMs, summary: 'fail: ci:trace-redaction in ' + _runtimeMs + 'ms', triage_tags: [],
+        requirement_ids: getRequirementIds('ci:trace-redaction'),
+        metadata: {
+          violations: allViolations.slice(0, 10),
+          total_violations: allViolations.length,
+        },
+      });
+    } catch (e) {
+      process.stderr.write('[check-trace-redaction] Warning: failed to write check result: ' + e.message + '\n');
+    }
+    process.exit(1);
+  }
+
+  try {
+    writeCheckResult({
+      tool: 'check-trace-redaction',
+      formalism: 'redaction',
+      result: 'pass',
+      check_id: 'ci:trace-redaction', surface: 'ci', property: 'Trace redaction — no forbidden keys or patterns in conformance event logs',
+      runtime_ms: _runtimeMs, summary: 'pass: ci:trace-redaction in ' + _runtimeMs + 'ms', triage_tags: [],
+      requirement_ids: getRequirementIds('ci:trace-redaction'),
+      metadata: { files_checked: fileCount, events_checked: eventCount },
+    });
+  } catch (e) {
+    process.stderr.write('[check-trace-redaction] Warning: failed to write check result: ' + e.message + '\n');
+  }
+  process.exit(0);
+}
+
+module.exports = { parseRedactionPolicy, validateTraceEvent };