@nforma.ai/nforma 0.2.1 → 0.29.0

package/bin/run-formal-verify.cjs

@@ -21,14 +21,15 @@
 //   Traceability (3) — generate-traceability-matrix.cjs (requirements <-> properties matrix)
 //                      check-coverage-guard.cjs (coverage regression guard vs baseline)
 //                      analyze-state-space.cjs (state-space risk classification per TLA+ model)
+//   Gates     (3)  — gate-a-grounding.cjs, gate-b-abstraction.cjs, gate-c-validation.cjs
 //   Registry  (N)  — custom check commands from model-registry.json
 //   ─────────────────────────────────────────────────────────────
-//   Total:    34+ steps (dynamic — registry can add more)
+//   Total:    37+ steps (dynamic — registry can add more)
 //
 // Usage:
 //   node bin/run-formal-verify.cjs                    # all 28 steps
 //   node bin/run-formal-verify.cjs --concurrent       # run tool groups in parallel (old behavior)
-//   QGSD_FORMAL_CONCURRENT=1 node bin/run-formal-verify.cjs  # same via env var
+//   NF_FORMAL_CONCURRENT=1 node bin/run-formal-verify.cjs  # same via env var
 //   node bin/run-formal-verify.cjs --only=generate    # source extraction only (2 steps)
 //   node bin/run-formal-verify.cjs --only=tla         # TLA+ only  (10 steps)
 //   node bin/run-formal-verify.cjs --only=alloy       # Alloy only (8 steps)
@@ -63,7 +64,7 @@ for (const arg of process.argv.slice(2)) {
 }
 
 // ── Runner picker maps ─────────────────────────────────────────────────────────
-// Maps known QGSD model names to their specialized runners. Unknown models
+// Maps known nForma model names to their specialized runners. Unknown models
 // fall back to generic runners (run-tlc.cjs, run-alloy.cjs, run-prism.cjs).
 
 const TLA_RUNNER_MAP = {
@@ -328,9 +329,9 @@ const STATIC_STEPS = [
   // ─ Source extraction — must run first so generated specs are fresh ──────────
   {
     tool: 'generate', id: 'generate:tla-from-xstate',
-    label: 'Generate TLA+ spec (QGSDQuorum_xstate.tla) + TLC model config from XState machine (xstate-to-tla)',
+    label: 'Generate TLA+ spec (NFQuorum_xstate.tla) + TLC model config from XState machine (xstate-to-tla)',
     type: 'node', script: 'xstate-to-tla.cjs',
-    args: ['src/machines/qgsd-workflow.machine.ts', '--module=QGSDQuorum', '--config=.planning/formal/tla/guards/qgsd-workflow.json'],
+    args: ['src/machines/nf-workflow.machine.ts', '--module=NFQuorum', '--config=.planning/formal/tla/guards/nf-workflow.json'],
   },
   {
     tool: 'generate', id: 'generate:alloy-prism-specs',
@@ -394,6 +395,26 @@ const STATIC_STEPS = [
     type: 'node', script: 'analyze-state-space.cjs', args: [],
     nonCritical: true,
   },
+
+  // ─ Gates — cross-layer alignment checks ───────────────────────────────────
+  {
+    tool: 'gates', id: 'gates:gate-a',
+    label: 'Gate A -- L1-L2 grounding alignment score',
+    type: 'node', script: 'gate-a-grounding.cjs', args: [],
+    nonCritical: true,
+  },
+  {
+    tool: 'gates', id: 'gates:gate-b',
+    label: 'Gate B -- L2-L3 traceability alignment score',
+    type: 'node', script: 'gate-b-abstraction.cjs', args: [],
+    nonCritical: true,
+  },
+  {
+    tool: 'gates', id: 'gates:gate-c',
+    label: 'Gate C -- L3-TC validation alignment score',
+    type: 'node', script: 'gate-c-validation.cjs', args: [],
+    nonCritical: true,
+  },
 ];
 
 // Discover dynamic model steps from ROOT/.planning/formal/
@@ -412,7 +433,7 @@ process.stdout.write(TAG + ' Discovered models: ' + uniqueDynamicSteps.length +
 const argv    = process.argv.slice(2);
 const onlyArg = argv.find(a => a.startsWith('--only='));
 const only    = onlyArg ? onlyArg.split('=')[1] : null;
-const concurrent = argv.includes('--concurrent') || process.env.QGSD_FORMAL_CONCURRENT === '1';
+const concurrent = argv.includes('--concurrent') || process.env.NF_FORMAL_CONCURRENT === '1';
 
 const steps = only
   ? STEPS.filter(s => s.tool === only || s.id === only)
@@ -421,7 +442,7 @@ const steps = only
 if (only && steps.length === 0) {
   process.stderr.write(
     TAG + ' Unknown --only value: ' + only + '\n' +
-    TAG + ' Valid values: tla, alloy, prism, petri, generate, ci, uppaal, registry, or a step id\n'
+    TAG + ' Valid values: tla, alloy, prism, petri, generate, ci, uppaal, gates, registry, or a step id\n'
   );
   process.exit(1);
 }
@@ -550,7 +571,7 @@ async function runOnce() {
   fs.writeFileSync(ndjsonPath, '', 'utf8');
 
   process.stdout.write(TAG + ' ' + HR + '\n');
-  process.stdout.write(TAG + ' QGSD Formal Verification Suite\n');
+  process.stdout.write(TAG + ' nForma Formal Verification Suite\n');
   if (only) {
     process.stdout.write(TAG + ' Filter: --only=' + only + '\n');
   }
@@ -641,7 +662,7 @@ if (watchArg) {
   // by spawning with a custom cwd. __dirname-relative paths would always point
   // to the real repo's src/machines/ regardless of spawn cwd, breaking isolation.
   const machineDir  = path.join(process.cwd(), 'src', 'machines');
-  const machineName = 'qgsd-workflow.machine.ts';
+  const machineName = 'nf-workflow.machine.ts';
   let debounceTimer = null;
   let running       = false;  // concurrent-run guard
   let watcher       = null;

package/bin/run-installer-alloy.cjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 // bin/run-installer-alloy.cjs
-// Invokes Alloy 6 JAR headless for QGSD installer and taxonomy specs (GAP-7, GAP-8).
+// Invokes Alloy 6 JAR headless for nForma installer and taxonomy specs (GAP-7, GAP-8).
 // Requirements: GAP-7, GAP-8
 //
 // Usage:
@@ -16,7 +16,7 @@
 //   - .planning/formal/alloy/org.alloytools.alloy.dist.jar (see VERIFICATION_TOOLS.md for download)
 
 const { spawnSync } = require('child_process');
-const JAVA_HEAP_MAX = process.env.QGSD_JAVA_HEAP_MAX || '512m';
+const JAVA_HEAP_MAX = process.env.NF_JAVA_HEAP_MAX || '512m';
 const fs   = require('fs');
 const path = require('path');
 const { writeCheckResult } = require('./write-check-result.cjs');

package/bin/run-oscillation-tlc.cjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 // bin/run-oscillation-tlc.cjs
-// Invokes TLC model checker for QGSD oscillation and convergence TLA+ specifications.
+// Invokes TLC model checker for nForma oscillation and convergence TLA+ specifications.
 // Requirements: GAP-1, GAP-5
 //
 // Usage:
@@ -14,7 +14,7 @@
 //   - .planning/formal/tla/tla2tools.jar (see .planning/formal/tla/README.md for download command)
 
 const { spawnSync } = require('child_process');
-const JAVA_HEAP_MAX = process.env.QGSD_JAVA_HEAP_MAX || '512m';
+const JAVA_HEAP_MAX = process.env.NF_JAVA_HEAP_MAX || '512m';
 const fs   = require('fs');
 const path = require('path');
 const { writeCheckResult } = require('./write-check-result.cjs');
@@ -129,8 +129,8 @@ if (!fs.existsSync(jarPath)) {
 
 // ── 4. Resolve spec and config paths ─────────────────────────────────────────
 const specFileName = configName === 'MCoscillation'
-  ? 'QGSDOscillation.tla'
-  : 'QGSDConvergence.tla';
+  ? 'NFOscillation.tla'
+  : 'NFConvergence.tla';
 const specPath = path.join(ROOT, '.planning', 'formal', 'tla', specFileName);
 const cfgPath  = path.join(ROOT, '.planning', 'formal', 'tla', configName + '.cfg');
 

package/bin/run-phase-tlc.cjs

@@ -15,7 +15,7 @@
 // NOTE: Uses spawnSync (no shell) for safe subprocess invocation -- no exec().
 
 const { spawnSync } = require('child_process');
-const JAVA_HEAP_MAX = process.env.QGSD_JAVA_HEAP_MAX || '512m';
+const JAVA_HEAP_MAX = process.env.NF_JAVA_HEAP_MAX || '512m';
 const fs   = require('fs');
 const path = require('path');
 

package/bin/run-protocol-tlc.cjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 // bin/run-protocol-tlc.cjs
-// Invokes TLC model checker for QGSD protocol termination TLA+ specifications.
+// Invokes TLC model checker for nForma protocol termination TLA+ specifications.
 // Requirements: GAP-2, GAP-6
 //
 // Usage:
@@ -14,7 +14,7 @@
 //   - .planning/formal/tla/tla2tools.jar (see .planning/formal/tla/README.md for download command)
 
 const { spawnSync } = require('child_process');
-const JAVA_HEAP_MAX = process.env.QGSD_JAVA_HEAP_MAX || '512m';
+const JAVA_HEAP_MAX = process.env.NF_JAVA_HEAP_MAX || '512m';
 const fs   = require('fs');
 const path = require('path');
 const { writeCheckResult } = require('./write-check-result.cjs');
@@ -129,8 +129,8 @@ if (!fs.existsSync(jarPath)) {
 
 // ── 4. Resolve spec and config paths ─────────────────────────────────────────
 const specFileName = configName === 'MCdeliberation'
-  ? 'QGSDDeliberation.tla'
-  : 'QGSDPreFilter.tla';
+  ? 'NFDeliberation.tla'
+  : 'NFPreFilter.tla';
 const specPath = path.join(ROOT, '.planning', 'formal', 'tla', specFileName);
 const cfgPath  = path.join(ROOT, '.planning', 'formal', 'tla', configName + '.cfg');
 

package/bin/run-quorum-composition-alloy.cjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 // bin/run-quorum-composition-alloy.cjs
-// Invokes Alloy 6 JAR headless for the QGSD quorum composition model.
+// Invokes Alloy 6 JAR headless for the nForma quorum composition model.
 // Requirements: SPEC-03
 //
 // Usage:
@@ -12,7 +12,7 @@
 //   - .planning/formal/alloy/org.alloytools.alloy.dist.jar (see VERIFICATION_TOOLS.md for download)
 
 const { spawnSync } = require('child_process');
-const JAVA_HEAP_MAX = process.env.QGSD_JAVA_HEAP_MAX || '512m';
+const JAVA_HEAP_MAX = process.env.NF_JAVA_HEAP_MAX || '512m';
 const fs   = require('fs');
 const path = require('path');
 const { writeCheckResult } = require('./write-check-result.cjs');

package/bin/run-sensitivity-sweep.cjs

@@ -13,7 +13,7 @@
 // Always exits 0.
 
 const { spawnSync } = require('child_process');
-const JAVA_HEAP_MAX = process.env.QGSD_JAVA_HEAP_MAX || '512m';
+const JAVA_HEAP_MAX = process.env.NF_JAVA_HEAP_MAX || '512m';
 const fs   = require('fs');
 const path = require('path');
 const os   = require('os');
@@ -67,7 +67,7 @@ function runTLCSweep(maxSize) {
   const overrideCfg = baseCfg.replace(/MaxSize\s*=\s*\d+/, 'MaxSize = ' + maxSize);
   fs.writeFileSync(tmpCfg, overrideCfg, 'utf8');
 
-  const tlaFile = path.join(__dirname, '..', '.planning', 'formal', 'tla', 'QGSDQuorum.tla');
+  const tlaFile = path.join(__dirname, '..', '.planning', 'formal', 'tla', 'NFQuorum.tla');
   process.stderr.write('[heap] Xms=64m Xmx=' + JAVA_HEAP_MAX + '\n');
   const javaResult = spawnSync('java', [
     '-Xms64m', '-Xmx' + JAVA_HEAP_MAX,

package/bin/run-stop-hook-tlc.cjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 // bin/run-stop-hook-tlc.cjs
-// Invokes TLC model checker for the QGSD Stop hook TLA+ specification.
+// Invokes TLC model checker for the nForma Stop hook TLA+ specification.
 // Requirements: SPEC-01
 //
 // Usage:
@@ -13,7 +13,7 @@
 //   - .planning/formal/tla/tla2tools.jar (see .planning/formal/tla/README.md for download command)
 
 const { spawnSync } = require('child_process');
-const JAVA_HEAP_MAX = process.env.QGSD_JAVA_HEAP_MAX || '512m';
+const JAVA_HEAP_MAX = process.env.NF_JAVA_HEAP_MAX || '512m';
 const fs   = require('fs');
 const path = require('path');
 const { writeCheckResult } = require('./write-check-result.cjs');
@@ -118,7 +118,7 @@ if (!fs.existsSync(jarPath)) {
 }
 
 // ── 4. Resolve spec and config paths ─────────────────────────────────────────
-const specPath = path.join(ROOT, '.planning', 'formal', 'tla', 'QGSDStopHook.tla');
+const specPath = path.join(ROOT, '.planning', 'formal', 'tla', 'NFStopHook.tla');
 const cfgPath  = path.join(ROOT, '.planning', 'formal', 'tla', configName + '.cfg');
 
 // LivenessProperty1/2/3 requires -workers 1 (TLC multi-worker liveness bug in v1.8.0)

package/bin/run-tlc.cjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 // bin/run-tlc.cjs
-// Invokes TLC model checker for the QGSD formal TLA+ specification.
+// Invokes TLC model checker for the nForma formal TLA+ specification.
 // Requirements: TLA-04
 //
 // Usage:
@@ -14,7 +14,7 @@
 //   - .planning/formal/tla/tla2tools.jar (see .planning/formal/tla/README.md for download command)
 
 const { spawnSync } = require('child_process');
-const JAVA_HEAP_MAX = process.env.QGSD_JAVA_HEAP_MAX || '512m';
+const JAVA_HEAP_MAX = process.env.NF_JAVA_HEAP_MAX || '512m';
 const fs   = require('fs');
 const path = require('path');
 const { writeCheckResult } = require('./write-check-result.cjs');
@@ -298,52 +298,52 @@ if (require.main === module) {
   // Map config names to their corresponding spec files.
   // Static map for known exceptions; auto-discovery handles the rest.
   const SPEC_MAP = {
-    'MCMCPEnv':              'QGSDMCPEnv.tla',
-    'MCsafety':              'QGSDQuorum.tla',
-    'MCliveness':            'QGSDQuorum.tla',
-    'MCQGSDQuorum':          'QGSDQuorum_xstate.tla',
-    'MCrecruiting-liveness': 'QGSDRecruiting.tla',
-    'MCrecruiting-safety':   'QGSDRecruiting.tla',
+    'MCMCPEnv':              'NFMCPEnv.tla',
+    'MCsafety':              'NFQuorum.tla',
+    'MCliveness':            'NFQuorum.tla',
+    'MCNFQuorum':          'NFQuorum_xstate.tla',
+    'MCrecruiting-liveness': 'NFRecruiting.tla',
+    'MCrecruiting-safety':   'NFRecruiting.tla',
     'MCTUINavigation':       'TUINavigation.tla',
   };
 
-  // Auto-discover spec file: (1) check SPEC_MAP, (2) scan cfg header for QGSD*.tla ref,
-  // (3) try naming conventions, (4) fall back to QGSDQuorum.tla
+  // Auto-discover spec file: (1) check SPEC_MAP, (2) scan cfg header for nForma*.tla ref,
+  // (3) try naming conventions, (4) fall back to NFQuorum.tla
   function resolveSpecFile(cfgName) {
     if (SPEC_MAP[cfgName]) return SPEC_MAP[cfgName];
 
     const tlaDir = path.join(ROOT, '.planning', 'formal', 'tla');
 
-    // Strategy 1: read cfg header for QGSD*.tla reference (with or without .tla suffix)
+    // Strategy 1: read cfg header for nForma*.tla reference (with or without .tla suffix)
     try {
       const cfgContent = fs.readFileSync(path.join(tlaDir, cfgName + '.cfg'), 'utf8');
       const headerLines = cfgContent.split('\n').slice(0, 5).join('\n');
-      // Match QGSD*.tla or "for QGSD*." (without .tla extension)
-      const refMatch = headerLines.match(/QGSD\w+\.tla/) || headerLines.match(/QGSD\w+/);
+      // Match NF*.tla or "for nForma*." (without .tla extension)
+      const refMatch = headerLines.match(/NF\w+\.tla/) || headerLines.match(/NF\w+/);
       if (refMatch) {
         const candidate = refMatch[0].endsWith('.tla') ? refMatch[0] : refMatch[0] + '.tla';
         if (fs.existsSync(path.join(tlaDir, candidate))) return candidate;
       }
     } catch (_) { /* fall through */ }
 
-    // Strategy 2: naming convention — strip MC prefix, normalize hyphens, find matching QGSD*.tla
+    // Strategy 2: naming convention — strip MC prefix, normalize hyphens, find matching NF*.tla
     const stripped = cfgName.replace(/^MC/, '').toLowerCase().replace(/-/g, '');
     try {
       const allTla = fs.readdirSync(tlaDir).filter(f => f.endsWith('.tla') && !f.includes('TTrace'));
-      const qgsdFiles = allTla.filter(f => f.startsWith('QGSD'));
+      const nfFiles = allTla.filter(f => f.startsWith('NF'));
       const normalize = (s) => s.toLowerCase().replace(/-/g, '');
-      // Exact match against QGSD-prefixed files
-      const match = qgsdFiles.find(f => normalize(f.replace('QGSD', '').replace('.tla', '')) === stripped);
+      // Exact match against nForma-prefixed files
+      const match = nfFiles.find(f => normalize(f.replace('NF', '').replace('.tla', '')) === stripped);
       if (match) return match;
-      // Fuzzy substring match against QGSD-prefixed files
-      const fuzzy = qgsdFiles.find(f => normalize(f).includes(stripped));
+      // Fuzzy substring match against nForma-prefixed files
+      const fuzzy = nfFiles.find(f => normalize(f).includes(stripped));
       if (fuzzy) return fuzzy;
-      // Fallback: check non-QGSD-prefixed files (exact match on stripped name)
+      // Fallback: check non-nForma-prefixed files (exact match on stripped name)
       const nonPrefixed = allTla.find(f => normalize(f.replace('.tla', '')) === stripped);
       if (nonPrefixed) return nonPrefixed;
     } catch (_) { /* fall through */ }
 
-    return 'QGSDQuorum.tla';
+    return 'NFQuorum.tla';
   }
 
   const specFile = resolveSpecFile(configName);

package/bin/run-transcript-alloy.cjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 // bin/run-transcript-alloy.cjs
-// Invokes Alloy 6 JAR headless for QGSD transcript scanning spec (GAP-4).
+// Invokes Alloy 6 JAR headless for nForma transcript scanning spec (GAP-4).
 // Requirements: GAP-4
 //
 // Usage:
@@ -15,7 +15,7 @@
 //   - .planning/formal/alloy/org.alloytools.alloy.dist.jar (see VERIFICATION_TOOLS.md for download)
 
 const { spawnSync } = require('child_process');
-const JAVA_HEAP_MAX = process.env.QGSD_JAVA_HEAP_MAX || '512m';
+const JAVA_HEAP_MAX = process.env.NF_JAVA_HEAP_MAX || '512m';
 const fs   = require('fs');
 const path = require('path');
 const { writeCheckResult } = require('./write-check-result.cjs');

package/bin/secrets.cjs

@@ -2,9 +2,9 @@
 const os = require('os');
 const fs = require('fs');
 const path = require('path');
-const SERVICE = 'qgsd';
+const SERVICE = 'nforma';
 
-const INDEX_PATH = path.join(os.homedir(), '.claude', 'qgsd-key-index.json');
+const INDEX_PATH = path.join(os.homedir(), '.claude', 'nf-key-index.json');
 
 // Read the key index (no keychain access needed — just a JSON file)
 function readIndex() {
@@ -84,7 +84,7 @@ async function syncToClaudeJson(service) {
   try {
     credentials = await list(service);
   } catch (e) {
-    process.stderr.write('[qgsd-secrets] keytar unavailable: ' + e.message + '\n');
+    process.stderr.write('[nf-secrets] keytar unavailable: ' + e.message + '\n');
     return;
   }
 
@@ -100,7 +100,7 @@ async function syncToClaudeJson(service) {
   try {
     raw = fs.readFileSync(claudeJsonPath, 'utf8');
   } catch (e) {
-    process.stderr.write('[qgsd-secrets] ~/.claude.json not found, skipping sync\n');
+    process.stderr.write('[nf-secrets] ~/.claude.json not found, skipping sync\n');
     return;
   }
 
@@ -108,7 +108,7 @@ async function syncToClaudeJson(service) {
   try {
     claudeJson = JSON.parse(raw);
   } catch (e) {
-    process.stderr.write('[qgsd-secrets] ~/.claude.json is invalid JSON, skipping sync\n');
+    process.stderr.write('[nf-secrets] ~/.claude.json is invalid JSON, skipping sync\n');
     return;
   }
 

package/bin/security-sweep.cjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * bin/security-sweep.cjs — Standalone security scanner for nForma.
+ *
+ * Scans git-tracked files for hardcoded secrets, debug artifacts, and API keys.
+ * Produces structured findings with file:line references for VERIFICATION.md.
+ *
+ * Advisory only — exit code 0 always. Never blocks.
+ *
+ * Exports: SECRET_PATTERNS, scanFile, scanDirectory, formatReport
+ * CLI: node bin/security-sweep.cjs [--json] [--cwd /path]
+ */
+
+const fs = require('fs');
+const path = require('path');
+// spawnSync is used (not exec) to avoid shell injection — arguments are passed as an array
+const { spawnSync } = require('child_process');
+
+// ─── Secret Patterns ────────────────────────────────────────────────────────
+
+const SECRET_PATTERNS = [
+  { name: 'AWS Access Key', pattern: /AKIA[A-Z0-9]{16}/, severity: 'high' },
+  { name: 'GitHub Token', pattern: /gh[ps]_[A-Za-z0-9_]{36,}/, severity: 'high' },
+  { name: 'GitHub PAT', pattern: /github_pat_[A-Za-z0-9_]{22,}/, severity: 'high' },
+  { name: 'Stripe Live Key', pattern: /[sr]k_live_[A-Za-z0-9]{20,}/, severity: 'high' },
+  { name: 'OpenAI Key', pattern: /sk-[A-Za-z0-9]{32,}/, severity: 'high' },
+  { name: 'Generic API Key Assignment', pattern: /(?:api[_-]?key|apikey)\s*[:=]\s*['"][^'"]{10,}['"]/i, severity: 'medium' },
+  { name: 'Generic Secret Assignment', pattern: /(?:secret|password)\s*[:=]\s*['"][^'"]{8,}['"]/i, severity: 'medium' },
+  { name: 'Debugger Statement', pattern: /^\s*debugger\s*;?\s*$/, severity: 'low' },
+  { name: 'Sensitive Console.log', pattern: /console\.log\(.*(?:password|secret|token|key|api_key)/i, severity: 'low' },
+];
+
+// Words that indicate a line is a test fixture / not a real secret
+const TEST_INDICATOR_WORDS = ['test', 'mock', 'fake', 'example', 'dummy', 'fixture', 'placeholder', 'todo'];
+
+// File patterns to exclude from scanning
+const EXCLUDE_PATTERNS = [
+  /\.test\./,
+  /\.spec\./,
+  /security-sweep\.cjs$/,
+  /\.md$/,
+  /\.json$/,
+  /\.jsonl$/,
+  /node_modules\//,
+  /\.planning\/\.quorum-cache\//,
+  /package-lock\.json$/,
+];
+
+// ─── scanFile ────────────────────────────────────────────────────────────────
+
+/**
+ * Scan file content line-by-line against SECRET_PATTERNS.
+ * @param {string} filePath - Relative or absolute file path (for reporting).
+ * @param {string} content  - File content to scan.
+ * @returns {Array<{file:string, line:number, column:number, pattern_name:string, severity:string, match:string}>}
+ */
+function scanFile(filePath, content) {
+  if (!content || typeof content !== 'string') return [];
+
+  // Skip binary content (null bytes in first 512 chars)
+  if (content.slice(0, 512).includes('\0')) return [];
+
+  const findings = [];
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineLower = line.toLowerCase();
+
+    // Skip lines containing test indicator words
+    if (TEST_INDICATOR_WORDS.some(w => lineLower.includes(w))) continue;
+
+    for (const pat of SECRET_PATTERNS) {
+      const m = pat.pattern.exec(line);
+      if (m) {
+        findings.push({
+          file: filePath,
+          line: i + 1,
+          column: m.index + 1,
+          pattern_name: pat.name,
+          severity: pat.severity,
+          match: m[0].length > 40 ? m[0].slice(0, 37) + '...' : m[0],
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+// ─── scanDirectory ───────────────────────────────────────────────────────────
+
+/**
+ * Scan git-tracked files in a directory.
+ * @param {string} cwd - Working directory to scan.
+ * @param {Object} [options]
+ * @param {string[]} [options.excludePatterns] - Additional glob patterns to exclude.
+ * @param {number}   [options.maxFiles=500]    - Max files to scan.
+ * @returns {{findings: Array, files_scanned: number, duration_ms: number}}
+ */
+function scanDirectory(cwd, options = {}) {
+  const maxFiles = options.maxFiles || 500;
+  const startTime = Date.now();
+
+  // Get tracked files via git ls-files (spawnSync, not exec — no shell injection)
+  let files = [];
+  try {
+    const result = spawnSync('git', ['ls-files'], {
+      cwd,
+      encoding: 'utf8',
+      timeout: 5000,
+    });
+    if (result.status === 0 && result.stdout) {
+      files = result.stdout.split('\n').filter(f => f.trim());
+    }
+  } catch (_) {
+    return { findings: [], files_scanned: 0, duration_ms: Date.now() - startTime };
+  }
+
+  // Filter out excluded patterns
+  files = files.filter(f => !EXCLUDE_PATTERNS.some(rx => rx.test(f)));
+
+  // Apply additional exclude patterns from options
+  if (options.excludePatterns && Array.isArray(options.excludePatterns)) {
+    for (const pat of options.excludePatterns) {
+      try {
+        const rx = new RegExp(pat);
+        files = files.filter(f => !rx.test(f));
+      } catch (_) {}
+    }
+  }
+
+  // Cap file count
+  if (files.length > maxFiles) {
+    files = files.slice(0, maxFiles);
+  }
+
+  const allFindings = [];
+  let scanned = 0;
+
+  for (const relPath of files) {
+    const absPath = path.join(cwd, relPath);
+    try {
+      const content = fs.readFileSync(absPath, 'utf8');
+      // Skip binary files (null bytes in first 512 bytes)
+      if (content.slice(0, 512).includes('\0')) continue;
+      scanned++;
+      const findings = scanFile(relPath, content);
+      allFindings.push(...findings);
+    } catch (_) {
+      // Skip unreadable files silently
+    }
+  }
+
+  return {
+    findings: allFindings,
+    files_scanned: scanned,
+    duration_ms: Date.now() - startTime,
+  };
+}
+
+// ─── formatReport ────────────────────────────────────────────────────────────
+
+/**
+ * Format scan results as a markdown section for VERIFICATION.md.
+ * @param {{findings: Array, files_scanned: number, duration_ms: number}} scanResult
+ * @returns {string}
+ */
+function formatReport(scanResult) {
+  const { findings, files_scanned, duration_ms } = scanResult;
+  const lines = [];
+
+  lines.push('## Security Sweep');
+  lines.push('');
+  lines.push(`**Scanned:** ${files_scanned} files in ${duration_ms}ms`);
+
+  if (!findings || findings.length === 0) {
+    lines.push('**Findings:** 0');
+    lines.push('');
+    lines.push('No hardcoded secrets, debug artifacts, or API keys detected.');
+    return lines.join('\n');
+  }
+
+  const high = findings.filter(f => f.severity === 'high').length;
+  const medium = findings.filter(f => f.severity === 'medium').length;
+  const low = findings.filter(f => f.severity === 'low').length;
+
+  lines.push(`**Findings:** ${findings.length} (${high} high, ${medium} medium, ${low} low)`);
+  lines.push('');
+  lines.push('| Severity | File | Line | Pattern | Match |');
+  lines.push('|----------|------|------|---------|-------|');
+
+  for (const f of findings) {
+    lines.push(`| ${f.severity} | ${f.file} | ${f.line} | ${f.pattern_name} | ${f.match} |`);
+  }
+
+  lines.push('');
+  lines.push('_Advisory: Review findings and confirm whether they are genuine secrets or false positives._');
+
+  return lines.join('\n');
+}
+
+// ─── CLI ─────────────────────────────────────────────────────────────────────
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const jsonFlag = args.includes('--json');
+  const cwdIdx = args.indexOf('--cwd');
+  const cwd = cwdIdx >= 0 && args[cwdIdx + 1] ? args[cwdIdx + 1] : process.cwd();
+
+  const result = scanDirectory(cwd);
+
+  if (jsonFlag) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  } else {
+    process.stdout.write(formatReport(result) + '\n');
+  }
+
+  // Log conformance event (best-effort)
+  try {
+    const planningPaths = require('./planning-paths.cjs');
+    const conformancePath = planningPaths.resolveWithFallback(cwd, 'conformance-events');
+    const event = {
+      ts: new Date().toISOString(),
+      action: 'security_sweep',
+      files_scanned: result.files_scanned,
+      findings_count: result.findings.length,
+      duration_ms: result.duration_ms,
+    };
+    fs.appendFileSync(conformancePath, JSON.stringify(event) + '\n');
+  } catch (_) {}
+
+  process.exit(0);
+}
+
+module.exports = { SECRET_PATTERNS, scanFile, scanDirectory, formatReport };