@nforma.ai/nforma 0.2.1 → 0.28.0

package/bin/quorum-cache.cjs

@@ -0,0 +1,144 @@
+'use strict';
+
+/**
+ * quorum-cache.cjs — Cache infrastructure for quorum results.
+ *
+ * Provides deterministic cache key computation (SHA-256), file-based read/write
+ * with TTL validation, and invalidation logic based on git HEAD and quorum
+ * composition changes.
+ *
+ * Cache files are stored in .planning/.quorum-cache/ (gitignored).
+ * All operations fail-open: errors return null/undefined, never throw.
+ */
+
+const crypto = require('node:crypto');
+const fs     = require('node:fs');
+const path   = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+/**
+ * Compute a deterministic SHA-256 cache key from quorum inputs.
+ *
+ * @param {string} prompt - The user prompt string
+ * @param {string} context - Additional context string
+ * @param {Array<{slot: string}>} slots - Slot objects with .slot property
+ * @param {Array} configQuorumActive - quorum_active array from config
+ * @param {string} gitHead - Current git HEAD hash
+ * @returns {string} Full hex SHA-256 digest
+ */
+function computeCacheKey(prompt, context, slots, configQuorumActive, gitHead) {
+  const sortedSlotNames = (slots || [])
+    .map(s => s.slot)
+    .sort()
+    .join(',');
+
+  const configHash = crypto
+    .createHash('sha256')
+    .update(JSON.stringify(configQuorumActive || []))
+    .digest('hex')
+    .slice(0, 16);
+
+  const payload = [
+    String(prompt || ''),
+    String(context || ''),
+    sortedSlotNames,
+    configHash,
+    String(gitHead || ''),
+  ].join('\x00');
+
+  return crypto.createHash('sha256').update(payload).digest('hex');
+}
+
+/**
+ * Get current git HEAD hash.
+ * Runs `git rev-parse HEAD` with a 3s timeout. Fail-open.
+ *
+ * @returns {string} Trimmed HEAD hash or empty string on failure
+ */
+function getGitHead() {
+  try {
+    const result = spawnSync('git', ['rev-parse', 'HEAD'], {
+      timeout: 3000,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return (result.stdout || '').trim();
+  } catch (_) {
+    return '';
+  }
+}
+
+/**
+ * Read a cache entry from disk.
+ * Returns parsed entry if valid (version 1, not expired, has completed field).
+ * Fail-open: returns null on any error or invalid state.
+ *
+ * @param {string} cacheKey - The cache key (hex digest)
+ * @param {string} cacheDir - Directory containing cache files
+ * @returns {object|null} Parsed cache entry or null
+ */
+function readCache(cacheKey, cacheDir) {
+  try {
+    const filePath = path.join(cacheDir, `${cacheKey}.json`);
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const entry = JSON.parse(raw);
+
+    // Version check
+    if (entry.version !== 1) return null;
+
+    // Must have completed field (pending entries are cache misses)
+    if (!entry.completed) return null;
+
+    // TTL check
+    const age = Date.now() - new Date(entry.created).getTime();
+    if (age > entry.ttl_ms) return null;
+
+    return entry;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Write a cache entry to disk. Creates cacheDir if needed. Fail-open.
+ *
+ * @param {string} cacheKey - The cache key (hex digest)
+ * @param {object} entry - Cache entry object
+ * @param {string} cacheDir - Directory to write cache files
+ */
+function writeCache(cacheKey, entry, cacheDir) {
+  try {
+    fs.mkdirSync(cacheDir, { recursive: true });
+    const filePath = path.join(cacheDir, `${cacheKey}.json`);
+    fs.writeFileSync(filePath, JSON.stringify(entry, null, 2), 'utf8');
+  } catch (_) {
+    // Fail-open: swallow errors
+  }
+}
+
+/**
+ * Validate a cache entry against current state.
+ * Returns false if git HEAD changed, quorum composition changed, or TTL expired.
+ *
+ * @param {object} entry - Cache entry to validate
+ * @param {string} currentGitHead - Current git HEAD hash
+ * @param {Array} currentQuorumActive - Current quorum_active config
+ * @returns {boolean} True if cache entry is still valid
+ */
+function isCacheValid(entry, currentGitHead, currentQuorumActive) {
+  if (!entry) return false;
+
+  // Git HEAD must match
+  if (entry.git_head !== currentGitHead) return false;
+
+  // Quorum composition must match
+  if (JSON.stringify(entry.quorum_active) !== JSON.stringify(currentQuorumActive)) return false;
+
+  // TTL must not be expired
+  const age = Date.now() - new Date(entry.created).getTime();
+  if (age > entry.ttl_ms) return false;
+
+  return true;
+}
+
+module.exports = { computeCacheKey, readCache, writeCache, getGitHead, isCacheValid };

package/bin/quorum-consensus-gate.cjs

@@ -154,7 +154,7 @@ function readEarlyEscalationThreshold(configPaths) {
   const DEFAULT = 0.10;
   const paths = configPaths || [
     path.join(process.cwd(), '.planning', 'config.json'),
-    path.join(process.cwd(), '.planning', 'qgsd.json'),
+    path.join(process.cwd(), '.planning', 'nf.json'),
   ];
   for (const cfgPath of paths) {
     try {

package/bin/quorum-slot-dispatch.cjs

@@ -19,7 +19,7 @@
  *     [--cwd <dir>]
  *
  * Builds the Mode A or Mode B prompt from deterministic JS templates matching
- * agents/qgsd-quorum-slot-worker.md Step 2, pipes it to call-quorum-slot.cjs via
+ * agents/nf-quorum-slot-worker.md Step 2, pipes it to call-quorum-slot.cjs via
  * child_process.spawn, parses the output, and emits a structured YAML result block.
  *
  * Exported pure functions (testable without subprocess):
@@ -118,7 +118,7 @@ const PATH_CATEGORY_MAP = new Map([
  *
  * @param {Array} requirements — full requirements array
  * @param {string} question — the question text
- * @param {string|null} artifactPath — optional artifact path (e.g. "hooks/qgsd-stop.js")
+ * @param {string|null} artifactPath — optional artifact path (e.g. "hooks/nf-stop.js")
  * @returns {Array} — filtered requirements (max 20), sorted by score descending
  */
 function matchRequirementsByKeywords(requirements, question, artifactPath) {
@@ -279,7 +279,7 @@ function formatRequirementsSection(requirements) {
 /**
  * buildModeAPrompt — constructs the Mode A question prompt.
  *
- * Matches the EXACT template from agents/qgsd-quorum-slot-worker.md Step 2 Mode A.
+ * Matches the EXACT template from agents/nf-quorum-slot-worker.md Step 2 Mode A.
  *
  * @param {object} opts
  * @param {number}  opts.round
@@ -297,7 +297,7 @@ function buildModeAPrompt({ round, repoDir, question, artifactPath, artifactCont
   const lines = [];
 
   // Header
-  lines.push(`QGSD Quorum — Round ${round}`);
+  lines.push(`nForma Quorum — Round ${round}`);
   lines.push('');
 
   // Repository + question
@@ -422,7 +422,7 @@ function buildModeAPrompt({ round, repoDir, question, artifactPath, artifactCont
 /**
  * buildModeBPrompt — constructs the Mode B execution review prompt.
  *
- * Matches the EXACT template from agents/qgsd-quorum-slot-worker.md Step 2 Mode B.
+ * Matches the EXACT template from agents/nf-quorum-slot-worker.md Step 2 Mode B.
  *
  * @param {object} opts
  * @param {number}  opts.round
@@ -440,7 +440,7 @@ function buildModeBPrompt({ round, repoDir, question, traces, artifactPath, arti
   const lines = [];
 
   // Header
-  lines.push(`QGSD Quorum — Execution Review (Round ${round})`);
+  lines.push(`nForma Quorum — Execution Review (Round ${round})`);
   lines.push('');
 
   // Repository + question

package/bin/requirements-core.cjs

@@ -3,7 +3,7 @@
 /**
  * Pure data functions for requirements management.
  * No blessed dependency — all functions are testable in isolation.
- * Consumers: bin/qgsd.cjs (blessed TUI)
+ * Consumers: bin/nf.cjs (blessed TUI)
  *
  * Data sources (project-relative paths via process.cwd()):
  *   .planning/formal/requirements.json    — 210 requirements in frozen envelope

package/bin/review-mcp-logs.cjs

@@ -192,7 +192,7 @@ const fmtMs = (ms) => {
 };
 
 console.log(`\n${bold('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')}`);
-console.log(bold(' QGSD ► MCP LOG REVIEW'));
+console.log(bold(' nForma ► MCP LOG REVIEW'));
 console.log(bold('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
 console.log(dim(` Scanned: ${files.length} debug files | Last ${MAX_DAYS} days | ${DEBUG_DIR}`));
 console.log();

package/bin/risk-heatmap.cjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * risk-heatmap.cjs — Ranked risk transition list for Layer 3 (Reasoning).
+ *
+ * Combines FMEA RPN scores with L1/L2 coverage gap data to produce a
+ * prioritized list of highest-risk transitions. Transitions not modeled
+ * in XState receive a 50% risk penalty.
+ *
+ * Requirements: RSN-03
+ *
+ * Usage:
+ *   node bin/risk-heatmap.cjs            # print summary to stdout
+ *   node bin/risk-heatmap.cjs --json     # print full results JSON to stdout
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const ROOT = process.env.PROJECT_ROOT || path.join(__dirname, '..');
+const FORMAL = path.join(ROOT, '.planning', 'formal');
+const REASONING_DIR = path.join(FORMAL, 'reasoning');
+const OUT_FILE = path.join(REASONING_DIR, 'risk-heatmap.json');
+
+const JSON_FLAG = process.argv.includes('--json');
+
+// ── Risk tier classification ────────────────────────────────────────────────
+
+function classifyRiskTier(riskScore) {
+  if (riskScore >= 200) return 'critical';
+  if (riskScore >= 100) return 'high';
+  if (riskScore >= 40)  return 'medium';
+  return 'low';
+}
+
+// ── Core computation ────────────────────────────────────────────────────────
+
+/**
+ * Compute composite risk score for a transition.
+ * risk_score = RPN * (1 + coverage_gap_penalty)
+ * coverage_gap_penalty = 0.5 if transition is in missing_in_model, else 0.0
+ */
+function computeRiskScore(rpn, hasCoverageGap) {
+  const penalty = hasCoverageGap ? 0.5 : 0.0;
+  return rpn * (1 + penalty);
+}
+
+function generateRiskHeatmap(hazardModel, observedFsm) {
+  // Build set of missing_in_model transitions
+  const missingInModel = new Set(
+    (observedFsm.model_comparison?.missing_in_model || [])
+      .map(m => `${m.from}-${m.event}`)
+  );
+
+  const transitions = [];
+
+  for (const hazard of (hazardModel?.hazards || [])) {
+    const key = `${hazard.state}-${hazard.event}`;
+    const hasCoverageGap = missingInModel.has(key);
+    const coverageGapPenalty = hasCoverageGap ? 0.5 : 0.0;
+    const riskScore = computeRiskScore(hazard.rpn, hasCoverageGap);
+
+    transitions.push({
+      state: hazard.state,
+      event: hazard.event,
+      to_state: hazard.to_state,
+      rpn: hazard.rpn,
+      coverage_gap: hasCoverageGap,
+      coverage_gap_penalty: coverageGapPenalty,
+      risk_score: riskScore,
+      risk_tier: classifyRiskTier(riskScore),
+      derived_from: [
+        { layer: 'L3', artifact: 'reasoning/hazard-model.json', ref: `hazards[id=${hazard.id}]` },
+        { layer: 'L2', artifact: 'semantics/observed-fsm.json', ref: `observed_transitions.${hazard.state}.${hazard.event}` },
+      ],
+    });
+  }
+
+  // Sort by risk_score descending
+  transitions.sort((a, b) => b.risk_score - a.risk_score);
+
+  // Summary stats
+  const byRiskTier = { critical: 0, high: 0, medium: 0, low: 0 };
+  let coverageGapCount = 0;
+  for (const t of transitions) {
+    byRiskTier[t.risk_tier] = (byRiskTier[t.risk_tier] || 0) + 1;
+    if (t.coverage_gap) coverageGapCount++;
+  }
+
+  return {
+    schema_version: '1',
+    generated: new Date().toISOString(),
+    formula: 'risk_score = RPN * (1 + coverage_gap_penalty); coverage_gap_penalty = 0.5 if missing_in_model, else 0.0',
+    risk_tiers: {
+      critical: 'risk_score >= 200',
+      high: '100 <= risk_score < 200',
+      medium: '40 <= risk_score < 100',
+      low: 'risk_score < 40',
+    },
+    transitions,
+    summary: {
+      total: transitions.length,
+      by_risk_tier: byRiskTier,
+      coverage_gap_count: coverageGapCount,
+    },
+  };
+}
+
+// ── Entry point ─────────────────────────────────────────────────────────────
+
+function main() {
+  // Load L3 hazard model
+  const hazardPath = path.join(REASONING_DIR, 'hazard-model.json');
+  if (!fs.existsSync(hazardPath)) {
+    console.error('ERROR: hazard-model.json not found at', hazardPath);
+    console.error('Run bin/hazard-model.cjs first.');
+    process.exit(1);
+  }
+  const hazardModel = JSON.parse(fs.readFileSync(hazardPath, 'utf8'));
+
+  // Load L2 observed FSM
+  const fsmPath = path.join(FORMAL, 'semantics', 'observed-fsm.json');
+  if (!fs.existsSync(fsmPath)) {
+    console.error('ERROR: observed-fsm.json not found at', fsmPath);
+    process.exit(1);
+  }
+  const observedFsm = JSON.parse(fs.readFileSync(fsmPath, 'utf8'));
+
+  const output = generateRiskHeatmap(hazardModel, observedFsm);
+
+  // Write output
+  fs.mkdirSync(REASONING_DIR, { recursive: true });
+  fs.writeFileSync(OUT_FILE, JSON.stringify(output, null, 2) + '\n');
+
+  if (JSON_FLAG) {
+    process.stdout.write(JSON.stringify(output));
+  } else {
+    console.log(`Risk Heatmap`);
+    console.log(`  Total transitions: ${output.summary.total}`);
+    console.log(`  By risk tier: ${JSON.stringify(output.summary.by_risk_tier)}`);
+    console.log(`  Coverage gaps: ${output.summary.coverage_gap_count}`);
+    console.log(`  Output: ${OUT_FILE}`);
+  }
+
+  process.exit(0);
+}
+
+if (require.main === module) main();
+
+module.exports = { computeRiskScore, classifyRiskTier, generateRiskHeatmap, main };

package/bin/run-account-manager-tlc.cjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 'use strict';
 // bin/run-account-manager-tlc.cjs
-// Invokes TLC model checker for the QGSD account manager TLA+ specification.
-// Source spec: .planning/formal/tla/QGSDAccountManager.tla
+// Invokes TLC model checker for the nForma account manager TLA+ specification.
+// Source spec: .planning/formal/tla/NFAccountManager.tla
 // Source impl: bin/account-manager.cjs
 //
 // Checks:
@@ -23,7 +23,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');
@@ -125,7 +125,7 @@ if (!fs.existsSync(jarPath)) {
 }
 
 // ── 4. Invoke TLC ────────────────────────────────────────────────────────────
-const specPath = path.join(ROOT, '.planning', 'formal', 'tla', 'QGSDAccountManager.tla');
+const specPath = path.join(ROOT, '.planning', 'formal', 'tla', 'NFAccountManager.tla');
 const cfgPath  = path.join(ROOT, '.planning', 'formal', 'tla', configName + '.cfg');
 // Use workers=1 for liveness (IdleReachable) — avoids multi-worker liveness bugs in TLC
 const workers  = '1';

package/bin/run-account-pool-alloy.cjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 // bin/run-account-pool-alloy.cjs
-// Invokes Alloy 6 JAR headless for the QGSD account pool structure spec.
+// Invokes Alloy 6 JAR headless for the nForma account pool structure spec.
 // Requirements: ALY-AM-01
 //
 // Usage:
@@ -19,7 +19,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-alloy.cjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 // bin/run-alloy.cjs
-// Invokes Alloy 6 JAR headless for the QGSD vote-counting model.
+// Invokes Alloy 6 JAR headless for the nForma vote-counting model.
 // Requirements: ALY-02
 //
 // 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-audit-alloy.cjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 // bin/run-audit-alloy.cjs
-// Invokes Alloy 6 JAR headless for QGSD audit trail specs (GAP-3, GAP-9).
+// Invokes Alloy 6 JAR headless for nForma audit trail specs (GAP-3, GAP-9).
 // Requirements: GAP-3, GAP-9
 //
 // 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-breaker-tlc.cjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 // bin/run-breaker-tlc.cjs
-// Invokes TLC model checker for the QGSD circuit breaker TLA+ specification.
+// Invokes TLC model checker for the nForma circuit breaker TLA+ specification.
 // Requirements: QT-105
 //
 // 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');
@@ -117,7 +117,7 @@ if (!fs.existsSync(jarPath)) {
 }
 
 // ── 4. Invoke TLC ────────────────────────────────────────────────────────────
-const specPath = path.join(ROOT, '.planning', 'formal', 'tla', 'QGSDCircuitBreaker.tla');
+const specPath = path.join(ROOT, '.planning', 'formal', 'tla', 'NFCircuitBreaker.tla');
 const cfgPath  = path.join(ROOT, '.planning', 'formal', 'tla', configName + '.cfg');
 // Always use 'auto' workers — MCbreaker has a small state space and liveness
 // can safely run with multiple workers (no known multi-worker liveness bugs at this scale).

package/bin/run-formal-check.cjs

@@ -31,7 +31,7 @@ const MODULE_CHECKS = {
       cmd: [
         'java', '-cp', '.planning/formal/tla/tla2tools.jar', 'tlc2.TLC',
         '-config', '.planning/formal/tla/MCliveness.cfg',
-        '.planning/formal/tla/QGSDQuorum.tla',
+        '.planning/formal/tla/NFQuorum.tla',
         '-workers', '1'
       ]
     },
@@ -67,7 +67,7 @@ const MODULE_CHECKS = {
       cmd: [
         'java', '-cp', '.planning/formal/tla/tla2tools.jar', 'tlc2.TLC',
         '-config', '.planning/formal/tla/MCbreaker.cfg',
-        '.planning/formal/tla/QGSDCircuitBreaker.tla',
+        '.planning/formal/tla/NFCircuitBreaker.tla',
         '-workers', '1'
       ]
     }
@@ -78,7 +78,7 @@ const MODULE_CHECKS = {
       cmd: [
         'java', '-cp', '.planning/formal/tla/tla2tools.jar', 'tlc2.TLC',
         '-config', '.planning/formal/tla/MCdeliberation.cfg',
-        '.planning/formal/tla/QGSDDeliberation.tla',
+        '.planning/formal/tla/NFDeliberation.tla',
         '-workers', '1'
       ]
     }
@@ -89,7 +89,7 @@ const MODULE_CHECKS = {
       cmd: [
         'java', '-cp', '.planning/formal/tla/tla2tools.jar', 'tlc2.TLC',
         '-config', '.planning/formal/tla/MCoscillation.cfg',
-        '.planning/formal/tla/QGSDOscillation.tla',
+        '.planning/formal/tla/NFOscillation.tla',
         '-workers', '1'
       ]
     }
@@ -100,7 +100,7 @@ const MODULE_CHECKS = {
       cmd: [
         'java', '-cp', '.planning/formal/tla/tla2tools.jar', 'tlc2.TLC',
         '-config', '.planning/formal/tla/MCconvergence.cfg',
-        '.planning/formal/tla/QGSDConvergence.tla',
+        '.planning/formal/tla/NFConvergence.tla',
         '-workers', '1'
       ]
     }
@@ -111,7 +111,7 @@ const MODULE_CHECKS = {
       cmd: [
         'java', '-cp', '.planning/formal/tla/tla2tools.jar', 'tlc2.TLC',
         '-config', '.planning/formal/tla/MCprefilter.cfg',
-        '.planning/formal/tla/QGSDPreFilter.tla',
+        '.planning/formal/tla/NFPreFilter.tla',
         '-workers', '1'
       ]
     }
@@ -122,7 +122,7 @@ const MODULE_CHECKS = {
       cmd: [
         'java', '-cp', '.planning/formal/tla/tla2tools.jar', 'tlc2.TLC',
         '-config', '.planning/formal/tla/MCrecruiting-safety.cfg',
-        '.planning/formal/tla/QGSDRecruiting.tla',
+        '.planning/formal/tla/NFRecruiting.tla',
         '-workers', '1'
       ]
     }
@@ -133,7 +133,7 @@ const MODULE_CHECKS = {
       cmd: [
         'java', '-cp', '.planning/formal/tla/tla2tools.jar', 'tlc2.TLC',
         '-config', '.planning/formal/tla/MCaccount-manager.cfg',
-        '.planning/formal/tla/QGSDAccountManager.tla',
+        '.planning/formal/tla/NFAccountManager.tla',
         '-workers', '1'
       ]
     }
@@ -144,7 +144,7 @@ const MODULE_CHECKS = {
       cmd: [
         'java', '-cp', '.planning/formal/tla/tla2tools.jar', 'tlc2.TLC',
         '-config', '.planning/formal/tla/MCMCPEnv.cfg',
-        '.planning/formal/tla/QGSDMCPEnv.tla',
+        '.planning/formal/tla/NFMCPEnv.tla',
         '-workers', '1'
       ]
     }

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;