@nforma.ai/nforma 0.2.1 → 0.29.0

package/bin/observed-fsm.cjs

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * observed-fsm.cjs — Derives an observed-behavior FSM from traces using
+ * dual-mode replay (per-event isolation + per-session chains).
+ *
+ * Requirements: SEM-04
+ *
+ * Usage:
+ *   node bin/observed-fsm.cjs            # print summary to stdout
+ *   node bin/observed-fsm.cjs --json     # print full FSM 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 OUT_DIR = path.join(FORMAL, 'semantics');
+const OUT_FILE = path.join(OUT_DIR, 'observed-fsm.json');
+
+const JSON_FLAG = process.argv.includes('--json');
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function stateToString(value) {
+  if (typeof value === 'string') return value;
+  if (typeof value === 'object' && value !== null) return JSON.stringify(value);
+  return String(value);
+}
+
+// ── Model extraction ────────────────────────────────────────────────────────
+
+function extractModelTransitions() {
+  const machinePath = (() => {
+    const repoDist    = path.join(__dirname, '..', 'dist', 'machines', 'nf-workflow.machine.js');
+    const installDist = path.join(__dirname, 'dist', 'machines', 'nf-workflow.machine.js');
+    return fs.existsSync(repoDist) ? repoDist : installDist;
+  })();
+  const { nfWorkflowMachine } = require(machinePath);
+
+  const config = nfWorkflowMachine.config;
+  const transitions = [];
+
+  for (const [stateName, stateDef] of Object.entries(config.states)) {
+    const on = stateDef.on || {};
+    for (const [eventName, targets] of Object.entries(on)) {
+      if (Array.isArray(targets)) {
+        for (const t of targets) {
+          if (t.target) transitions.push({ from: stateName, event: eventName, to: t.target });
+        }
+      } else if (typeof targets === 'string') {
+        transitions.push({ from: stateName, event: eventName, to: targets });
+      } else if (targets && targets.target) {
+        transitions.push({ from: stateName, event: eventName, to: targets.target });
+      }
+    }
+  }
+
+  return { states: Object.keys(config.states), transitions };
+}
+
+// ── Mode A: Per-event isolation ─────────────────────────────────────────────
+
+function replayPerEvent(conformanceEvents, mapToXStateEvent, createActor, nfWorkflowMachine) {
+  const adjacency = {}; // { fromState: { eventType: { toState, count } } }
+  let totalMapped = 0;
+
+  for (const event of conformanceEvents) {
+    const xstateEvent = mapToXStateEvent(event);
+    if (!xstateEvent) continue;
+    totalMapped++;
+
+    const actor = createActor(nfWorkflowMachine);
+    actor.start();
+    const beforeState = stateToString(actor.getSnapshot().value);
+    actor.send(xstateEvent);
+    const afterState = stateToString(actor.getSnapshot().value);
+    actor.stop();
+
+    if (!adjacency[beforeState]) adjacency[beforeState] = {};
+    const key = xstateEvent.type;
+    if (!adjacency[beforeState][key]) {
+      adjacency[beforeState][key] = { to_state: afterState, count: 0 };
+    }
+    adjacency[beforeState][key].count++;
+  }
+
+  return { adjacency, totalMapped };
+}
+
+// ── Mode B: Per-session running actor ───────────────────────────────────────
+
+function replayPerSession(conformanceEvents, traceStats, mapToXStateEvent, createActor, nfWorkflowMachine) {
+  const adjacency = {};
+  let sessionsReplayed = 0;
+
+  const sessions = (traceStats && traceStats.sessions) || [];
+  for (const session of sessions) {
+    const sessionStart = new Date(session.start).getTime();
+    const sessionEnd = new Date(session.end).getTime();
+    const sessionEvents = conformanceEvents.filter(e => {
+      const t = new Date(e.ts).getTime();
+      return t >= sessionStart && t <= sessionEnd;
+    });
+
+    if (sessionEvents.length === 0) continue;
+
+    const actor = createActor(nfWorkflowMachine);
+    actor.start();
+    sessionsReplayed++;
+
+    for (const event of sessionEvents) {
+      const xstateEvent = mapToXStateEvent(event);
+      if (!xstateEvent) continue;
+
+      const beforeState = stateToString(actor.getSnapshot().value);
+      actor.send(xstateEvent);
+      const afterState = stateToString(actor.getSnapshot().value);
+
+      const key = xstateEvent.type;
+      if (!adjacency[beforeState]) adjacency[beforeState] = {};
+      if (!adjacency[beforeState][key]) {
+        adjacency[beforeState][key] = { to_state: afterState, count: 0 };
+      }
+      adjacency[beforeState][key].count++;
+    }
+
+    actor.stop();
+  }
+
+  return { adjacency, sessionsReplayed };
+}
+
+// ── Merge ───────────────────────────────────────────────────────────────────
+
+function mergeAdjacency(perEvent, perSession) {
+  const merged = {};
+
+  // Add per-event transitions
+  for (const [from, events] of Object.entries(perEvent)) {
+    if (!merged[from]) merged[from] = {};
+    for (const [event, data] of Object.entries(events)) {
+      merged[from][event] = { ...data, source: 'per_event' };
+    }
+  }
+
+  // Merge per-session transitions
+  for (const [from, events] of Object.entries(perSession)) {
+    if (!merged[from]) merged[from] = {};
+    for (const [event, data] of Object.entries(events)) {
+      if (merged[from][event]) {
+        // Both modes have this transition
+        merged[from][event].source = 'both';
+        // Keep per-event count as authoritative
+      } else {
+        merged[from][event] = { ...data, source: 'per_session' };
+      }
+    }
+  }
+
+  return merged;
+}
+
+// ── Model comparison ────────────────────────────────────────────────────────
+
+function compareWithModel(mergedAdjacency, modelTransitions) {
+  const observedSet = new Set();
+  for (const [from, events] of Object.entries(mergedAdjacency)) {
+    for (const [event, data] of Object.entries(events)) {
+      observedSet.add(`${from}::${event}::${data.to_state}`);
+    }
+  }
+
+  const modelSet = new Set();
+  for (const t of modelTransitions) {
+    modelSet.add(`${t.from}::${t.event}::${t.to}`);
+  }
+
+  const matching = [];
+  const missingInObserved = [];
+  const missingInModel = [];
+
+  for (const key of modelSet) {
+    const [from, event, to] = key.split('::');
+    if (observedSet.has(key)) {
+      matching.push({ from, event, to });
+    } else {
+      missingInObserved.push({ from, event, to });
+    }
+  }
+
+  for (const key of observedSet) {
+    if (!modelSet.has(key)) {
+      const [from, event, to] = key.split('::');
+      missingInModel.push({ from, event, to });
+    }
+  }
+
+  return { matching, missing_in_observed: missingInObserved, missing_in_model: missingInModel };
+}
+
+// ── Build FSM ───────────────────────────────────────────────────────────────
+
+function buildObservedFSM(conformanceEvents, traceStats) {
+  const { mapToXStateEvent } = require(path.join(__dirname, 'validate-traces.cjs'));
+  const machinePath = (() => {
+    const repoDist    = path.join(__dirname, '..', 'dist', 'machines', 'nf-workflow.machine.js');
+    const installDist = path.join(__dirname, 'dist', 'machines', 'nf-workflow.machine.js');
+    return fs.existsSync(repoDist) ? repoDist : installDist;
+  })();
+  const { createActor, nfWorkflowMachine } = require(machinePath);
+
+  // Mode A: Per-event isolation
+  const perEventResult = replayPerEvent(conformanceEvents, mapToXStateEvent, createActor, nfWorkflowMachine);
+
+  // Mode B: Per-session running actor
+  const perSessionResult = replayPerSession(conformanceEvents, traceStats, mapToXStateEvent, createActor, nfWorkflowMachine);
+
+  // Merge
+  const mergedAdjacency = mergeAdjacency(perEventResult.adjacency, perSessionResult.adjacency);
+
+  // Extract observed states
+  const statesObserved = new Set();
+  for (const [from, events] of Object.entries(mergedAdjacency)) {
+    statesObserved.add(from);
+    for (const data of Object.values(events)) {
+      statesObserved.add(data.to_state);
+    }
+  }
+
+  // Model comparison
+  const model = extractModelTransitions();
+  const comparison = compareWithModel(mergedAdjacency, model.transitions);
+
+  // Coverage metrics
+  const totalEvents = conformanceEvents.length;
+  const mappedEvents = perEventResult.totalMapped;
+  const unmappedEvents = totalEvents - mappedEvents;
+  const modelTransitionCount = model.transitions.length;
+  const exercisedCount = comparison.matching.length;
+
+  // Count per-event and per-session unique transitions
+  const perEventTransitions = new Set();
+  for (const [from, events] of Object.entries(perEventResult.adjacency)) {
+    for (const [event, data] of Object.entries(events)) {
+      perEventTransitions.add(`${from}::${event}::${data.to_state}`);
+    }
+  }
+  const perSessionTransitions = new Set();
+  for (const [from, events] of Object.entries(perSessionResult.adjacency)) {
+    for (const [event, data] of Object.entries(events)) {
+      perSessionTransitions.add(`${from}::${event}::${data.to_state}`);
+    }
+  }
+
+  return {
+    schema_version: '1',
+    generated: new Date().toISOString(),
+    observed_transitions: mergedAdjacency,
+    states_observed: [...statesObserved].sort(),
+    model_comparison: comparison,
+    coverage: {
+      model_coverage: modelTransitionCount > 0 ? exercisedCount / modelTransitionCount : 0,
+      vocabulary_coverage: totalEvents > 0 ? mappedEvents / totalEvents : 0,
+      total_events: totalEvents,
+      mapped_events: mappedEvents,
+      unmapped_events: unmappedEvents
+    },
+    replay_modes: {
+      per_event_transitions: perEventTransitions.size,
+      per_session_transitions: perSessionTransitions.size,
+      sessions_replayed: perSessionResult.sessionsReplayed
+    }
+  };
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────────────
+
+if (require.main === module) {
+  // Read conformance events
+  const pp = require(path.join(__dirname, 'planning-paths.cjs'));
+  const logPath = pp.resolveWithFallback(ROOT, 'conformance-events');
+  let conformanceEvents = [];
+  if (fs.existsSync(logPath)) {
+    const raw = fs.readFileSync(logPath, 'utf8');
+    const lines = raw.split('\n').filter(l => l.trim().length > 0);
+    for (const line of lines) {
+      try { conformanceEvents.push(JSON.parse(line)); } catch (_) { /* skip */ }
+    }
+  }
+
+  // Read trace stats
+  const statsPath = path.join(FORMAL, 'evidence', 'trace-corpus-stats.json');
+  let traceStats = null;
+  if (fs.existsSync(statsPath)) {
+    traceStats = JSON.parse(fs.readFileSync(statsPath, 'utf8'));
+  }
+
+  const fsm = buildObservedFSM(conformanceEvents, traceStats);
+
+  fs.mkdirSync(OUT_DIR, { recursive: true });
+  fs.writeFileSync(OUT_FILE, JSON.stringify(fsm, null, 2) + '\n');
+
+  if (JSON_FLAG) {
+    process.stdout.write(JSON.stringify(fsm, null, 2) + '\n');
+  } else {
+    console.log(`Observed FSM written to ${path.relative(ROOT, OUT_FILE)}`);
+    console.log(`  States observed: ${fsm.states_observed.length} (${fsm.states_observed.join(', ')})`);
+    console.log(`  Model coverage: ${(fsm.coverage.model_coverage * 100).toFixed(1)}%`);
+    console.log(`  Vocabulary coverage: ${(fsm.coverage.vocabulary_coverage * 100).toFixed(1)}%`);
+    console.log(`  Events: ${fsm.coverage.total_events} total, ${fsm.coverage.mapped_events} mapped, ${fsm.coverage.unmapped_events} unmapped`);
+    console.log(`  Replay modes: per_event=${fsm.replay_modes.per_event_transitions} per_session=${fsm.replay_modes.per_session_transitions} sessions=${fsm.replay_modes.sessions_replayed}`);
+    console.log(`  Model comparison: matching=${fsm.model_comparison.matching.length} missing_in_observed=${fsm.model_comparison.missing_in_observed.length} missing_in_model=${fsm.model_comparison.missing_in_model.length}`);
+  }
+
+  process.exit(0);
+}
+
+module.exports = {
+  buildObservedFSM, extractModelTransitions, replayPerEvent, replayPerSession,
+  mergeAdjacency, compareWithModel, stateToString
+};

package/bin/planning-paths.cjs

@@ -84,6 +84,12 @@ const TYPES = {
     legacy:    (root, p) => path.join(root, '.planning', `${p.version}-INTEGRATION-REPORT.md`),
   },
 
+  // Quorum cache
+  'quorum-cache': {
+    canonical: (root) => path.join(root, '.planning', '.quorum-cache'),
+    legacy:    (root) => path.join(root, '.planning', '.quorum-cache'),
+  },
+
   // State backups
   'state-backup': {
     canonical: (root, p) => path.join(root, '.planning', 'archive', 'state-backups', `STATE.md.bak-${p.timestamp}`),

package/bin/polyrepo.cjs

@@ -5,7 +5,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
-const TAG = '[qgsd-polyrepo]';
+const TAG = '[nf-polyrepo]';
 const POLYREPOS_DIR = path.join(os.homedir(), '.claude', 'polyrepos');
 const MARKER_FILE = 'polyrepo.json';
 

package/bin/probe-quorum-slots.cjs

@@ -27,7 +27,7 @@ const os         = require('os');
 function findProviders() {
   const searchPaths = [
     path.join(__dirname, 'providers.json'),
-    path.join(os.homedir(), '.claude', 'qgsd-bin', 'providers.json'),
+    path.join(os.homedir(), '.claude', 'nf-bin', 'providers.json'),
   ];
   try {
     const claudeJson = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.claude.json'), 'utf8'));

package/bin/promote-gate-maturity.cjs

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * promote-gate-maturity.cjs — Gate maturity level promotion CLI.
+ *
+ * Manages per-model gate enforcement levels: ADVISORY -> SOFT_GATE -> HARD_GATE.
+ *
+ * Requirements: GATE-04
+ *
+ * Usage:
+ *   node bin/promote-gate-maturity.cjs --model "alloy/quorum-votes.als" --level SOFT_GATE
+ *   node bin/promote-gate-maturity.cjs --check              # validate all models
+ *   node bin/promote-gate-maturity.cjs --check --fix         # demote violating models
+ *   node bin/promote-gate-maturity.cjs --json               # JSON output mode
+ */
+
+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 REGISTRY_PATH = path.join(FORMAL, 'model-registry.json');
+const CHECK_RESULTS_PATH = path.join(FORMAL, 'check-results.ndjson');
+
+const JSON_FLAG = process.argv.includes('--json');
+const CHECK_FLAG = process.argv.includes('--check');
+const FIX_FLAG = process.argv.includes('--fix');
+
+const LEVELS = ['ADVISORY', 'SOFT_GATE', 'HARD_GATE'];
+const LEVEL_RANK = { ADVISORY: 0, SOFT_GATE: 1, HARD_GATE: 2 };
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function getModelKeys(registry) {
+  return Object.keys(registry).filter(k => k.startsWith('.'));
+}
+
+function getModelLevel(model) {
+  return model.gate_maturity || 'ADVISORY';
+}
+
+/**
+ * Infer source_layer from the model path.
+ */
+function inferSourceLayer(modelPath) {
+  if (modelPath.includes('evidence/') || modelPath.includes('L1') || modelPath.includes('conformance')) return 'L1';
+  if (modelPath.includes('semantics/') || modelPath.includes('L2')) return 'L2';
+  if (modelPath.includes('reasoning/') || modelPath.includes('L3')) return 'L3';
+  // TLA+ and Alloy models are L2 by default (formal specs of the operational model)
+  if (modelPath.endsWith('.tla') || modelPath.endsWith('.als') || modelPath.endsWith('.props')) return 'L2';
+  return null;
+}
+
+// ── Validation criteria ─────────────────────────────────────────────────────
+
+/**
+ * Validate that a model meets its current (or target) gate_maturity criteria.
+ * Returns { valid: boolean, reason: string }
+ */
+function validateCriteria(modelPath, model, targetLevel, checkResults) {
+  const level = targetLevel || getModelLevel(model);
+
+  if (level === 'ADVISORY') {
+    return { valid: true, reason: 'ADVISORY: no criteria required' };
+  }
+
+  // SOFT_GATE: requires source_layer
+  const sourceLayer = model.source_layer || inferSourceLayer(modelPath);
+  if (level === 'SOFT_GATE' || level === 'HARD_GATE') {
+    if (!sourceLayer) {
+      return { valid: false, reason: 'SOFT_GATE requires source_layer assignment' };
+    }
+  }
+
+  // HARD_GATE: requires SOFT_GATE + passing check-result
+  if (level === 'HARD_GATE') {
+    const modelLower = modelPath.toLowerCase();
+    const hasPassingCheck = checkResults.some(cr => {
+      if (cr.result !== 'pass') return false;
+      const toolMatch = cr.tool && modelLower.includes(cr.tool.toLowerCase());
+      const checkIdPart = cr.check_id ? (cr.check_id.split(':')[1] || '') : '';
+      const checkIdMatch = checkIdPart && modelLower.includes(checkIdPart.toLowerCase());
+      return toolMatch || checkIdMatch;
+    });
+    if (!hasPassingCheck) {
+      return { valid: false, reason: 'HARD_GATE requires at least one passing check-result' };
+    }
+  }
+
+  return { valid: true, reason: `${level}: all criteria met` };
+}
+
+// ── Promote a single model ──────────────────────────────────────────────────
+
+function promoteModel(registry, modelPath, targetLevel, checkResults) {
+  const model = registry[modelPath];
+  if (!model) {
+    return { success: false, error: `Model not found: ${modelPath}` };
+  }
+
+  const currentLevel = getModelLevel(model);
+  const currentRank = LEVEL_RANK[currentLevel] ?? 0;
+  const targetRank = LEVEL_RANK[targetLevel];
+
+  if (targetRank === undefined) {
+    return { success: false, error: `Invalid level: ${targetLevel}. Must be one of: ${LEVELS.join(', ')}` };
+  }
+
+  if (targetRank <= currentRank) {
+    return { success: false, error: `Cannot promote: ${currentLevel} -> ${targetLevel} is not a promotion` };
+  }
+
+  // Validate target level criteria
+  const validation = validateCriteria(modelPath, model, targetLevel, checkResults);
+  if (!validation.valid) {
+    return { success: false, error: `Criteria not met for ${targetLevel}: ${validation.reason}` };
+  }
+
+  // Apply promotion
+  model.gate_maturity = targetLevel;
+  model.last_updated = new Date().toISOString();
+  if (!model.source_layer) {
+    model.source_layer = inferSourceLayer(modelPath);
+  }
+
+  return { success: true, from: currentLevel, to: targetLevel };
+}
+
+// ── Check all models ────────────────────────────────────────────────────────
+
+function checkAllModels(registry, checkResults, fix) {
+  const modelKeys = getModelKeys(registry);
+  const violations = [];
+  const demotions = [];
+
+  for (const modelPath of modelKeys) {
+    const model = registry[modelPath];
+    const level = getModelLevel(model);
+
+    if (level === 'ADVISORY') continue; // Always valid
+
+    const validation = validateCriteria(modelPath, model, level, checkResults);
+    if (!validation.valid) {
+      violations.push({
+        model: modelPath,
+        level,
+        reason: validation.reason,
+      });
+
+      if (fix) {
+        // Demote to highest valid level
+        if (level === 'HARD_GATE') {
+          const softCheck = validateCriteria(modelPath, model, 'SOFT_GATE', checkResults);
+          if (softCheck.valid) {
+            model.gate_maturity = 'SOFT_GATE';
+            model.last_updated = new Date().toISOString();
+            demotions.push({ model: modelPath, from: level, to: 'SOFT_GATE' });
+          } else {
+            model.gate_maturity = 'ADVISORY';
+            model.last_updated = new Date().toISOString();
+            demotions.push({ model: modelPath, from: level, to: 'ADVISORY' });
+          }
+        } else {
+          model.gate_maturity = 'ADVISORY';
+          model.last_updated = new Date().toISOString();
+          demotions.push({ model: modelPath, from: level, to: 'ADVISORY' });
+        }
+      }
+    }
+  }
+
+  return {
+    total: modelKeys.length,
+    checked: modelKeys.filter(k => getModelLevel(registry[k]) !== 'ADVISORY').length,
+    violations,
+    demotions,
+    by_level: {
+      ADVISORY: modelKeys.filter(k => getModelLevel(registry[k]) === 'ADVISORY').length,
+      SOFT_GATE: modelKeys.filter(k => getModelLevel(registry[k]) === 'SOFT_GATE').length,
+      HARD_GATE: modelKeys.filter(k => getModelLevel(registry[k]) === 'HARD_GATE').length,
+    },
+  };
+}
+
+// ── Load check results ──────────────────────────────────────────────────────
+
+function loadCheckResults() {
+  if (!fs.existsSync(CHECK_RESULTS_PATH)) return [];
+  return fs.readFileSync(CHECK_RESULTS_PATH, 'utf8')
+    .trim().split('\n').filter(Boolean)
+    .map(line => { try { return JSON.parse(line); } catch { return null; } })
+    .filter(Boolean);
+}
+
+// ── Entry point ─────────────────────────────────────────────────────────────
+
+function main() {
+  if (!fs.existsSync(REGISTRY_PATH)) {
+    console.error('ERROR: model-registry.json not found at', REGISTRY_PATH);
+    process.exit(1);
+  }
+
+  const registry = JSON.parse(fs.readFileSync(REGISTRY_PATH, 'utf8'));
+  const checkResults = loadCheckResults();
+
+  if (CHECK_FLAG) {
+    const result = checkAllModels(registry, checkResults, FIX_FLAG);
+
+    if (FIX_FLAG && result.demotions.length > 0) {
+      fs.writeFileSync(REGISTRY_PATH, JSON.stringify(registry, null, 2) + '\n');
+    }
+
+    if (JSON_FLAG) {
+      process.stdout.write(JSON.stringify(result));
+    } else {
+      console.log(`Gate Maturity Check`);
+      console.log(`  Total models: ${result.total}`);
+      console.log(`  By level: ${JSON.stringify(result.by_level)}`);
+      console.log(`  Violations: ${result.violations.length}`);
+      if (result.violations.length > 0) {
+        for (const v of result.violations) {
+          console.log(`    - ${v.model}: ${v.reason}`);
+        }
+      }
+      if (result.demotions.length > 0) {
+        console.log(`  Demotions applied:`);
+        for (const d of result.demotions) {
+          console.log(`    - ${d.model}: ${d.from} -> ${d.to}`);
+        }
+      }
+    }
+
+    process.exit(result.violations.length > 0 && !FIX_FLAG ? 1 : 0);
+  }
+
+  // Promotion mode
+  const modelIdx = process.argv.indexOf('--model');
+  const levelIdx = process.argv.indexOf('--level');
+
+  if (modelIdx === -1 || levelIdx === -1) {
+    console.error('Usage: --model <path> --level <ADVISORY|SOFT_GATE|HARD_GATE>');
+    console.error('  or:  --check [--fix] [--json]');
+    process.exit(1);
+  }
+
+  const modelPath = process.argv[modelIdx + 1];
+  const targetLevel = process.argv[levelIdx + 1];
+
+  const result = promoteModel(registry, modelPath, targetLevel, checkResults);
+
+  if (result.success) {
+    fs.writeFileSync(REGISTRY_PATH, JSON.stringify(registry, null, 2) + '\n');
+
+    if (JSON_FLAG) {
+      process.stdout.write(JSON.stringify(result));
+    } else {
+      console.log(`Promoted: ${modelPath}`);
+      console.log(`  ${result.from} -> ${result.to}`);
+    }
+    process.exit(0);
+  } else {
+    if (JSON_FLAG) {
+      process.stdout.write(JSON.stringify(result));
+    } else {
+      console.error(`Promotion failed: ${result.error}`);
+    }
+    process.exit(1);
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = { promoteModel, validateCriteria, checkAllModels, getModelKeys, inferSourceLayer, loadCheckResults };

package/bin/promote-model.cjs

@@ -20,7 +20,7 @@ const ROOT = path.join(__dirname, '..');
 // ── Find .planning/formal/ root from target path ───────────────────────────────────────
 // Walks up from a given path until finding .planning/formal/, then
 // returns the grandparent of that directory as the project root.
-// Falls back to ROOT (the QGSD project root) if no .planning/formal/ ancestor is found.
+// Falls back to ROOT (the nForma project root) if no .planning/formal/ ancestor is found.
 function findProjectRoot(startPath) {
   let current = path.dirname(startPath);
   while (true) {

package/bin/propose-debug-invariants.cjs

@@ -13,7 +13,7 @@ const fs   = require('fs');
 const NON_INTERACTIVE = process.argv.includes('--non-interactive');
 const DEBUG_ARTIFACT_PATH = path.join(process.cwd(), '.planning', 'quick', 'quorum-debug-latest.md');
 const ACCEPT_SCRIPT = path.join(__dirname, 'accept-debug-invariant.cjs');
-const DEFAULT_SPEC  = path.join(process.cwd(), '.planning', 'formal', 'tla', 'QGSDQuorum.tla');
+const DEFAULT_SPEC  = path.join(process.cwd(), '.planning', 'formal', 'tla', 'NFQuorum.tla');
 
 function sanitizeTlaName(str) {
   return str.replace(/[^a-zA-Z0-9]+/g, '_').slice(0, 40).replace(/^_+|_+$/g, '') || 'Unknown';