@nforma.ai/nforma 0.2.1 → 0.29.0

package/bin/gate-c-validation.cjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * gate-c-validation.cjs — Gate C L3-to-test-recipe coverage verification.
+ *
+ * Verifies every L3 failure mode maps to at least one test recipe.
+ * Reports gate_c_score and gap list for uncovered failure modes.
+ *
+ * Requirements: GATE-03
+ *
+ * Usage:
+ *   node bin/gate-c-validation.cjs            # print summary to stdout
+ *   node bin/gate-c-validation.cjs --json     # print full results JSON to stdout
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const ROOT = process.env.PROJECT_ROOT
+  || (process.argv.find(a => a.startsWith('--project-root=')) || '').replace('--project-root=', '')
+  || path.join(__dirname, '..');
+const FORMAL = path.join(ROOT, '.planning', 'formal');
+const REASONING_DIR = path.join(FORMAL, 'reasoning');
+const RECIPES_DIR = path.join(FORMAL, 'test-recipes');
+const GATES_DIR = path.join(FORMAL, 'gates');
+const OUT_FILE = path.join(GATES_DIR, 'gate-c-validation.json');
+
+const JSON_FLAG = process.argv.includes('--json');
+
+// ── Gate C computation ───────────────────────────────────────────────────
+
+function computeGateC(failureModes, recipes) {
+  if (failureModes.length === 0) {
+    return {
+      schema_version: '1',
+      generated: new Date().toISOString(),
+      gate_c_score: 0,
+      total_entries: 0,
+      validated_entries: 0,
+      unvalidated_entries: 0,
+      gaps: [],
+      target: 0.8,
+      target_met: false,
+    };
+  }
+
+  // Build lookup: failure_mode_id -> recipe[]
+  const recipeMap = new Map();
+  for (const r of recipes) {
+    const fmId = r.failure_mode_id;
+    if (!recipeMap.has(fmId)) recipeMap.set(fmId, []);
+    recipeMap.get(fmId).push(r);
+  }
+
+  let validated = 0;
+  const gaps = [];
+
+  for (const fm of failureModes) {
+    if (recipeMap.has(fm.id) && recipeMap.get(fm.id).length > 0) {
+      validated++;
+    } else {
+      gaps.push({
+        failure_mode_id: fm.id,
+        state: fm.state,
+        event: fm.event,
+        failure_mode: fm.failure_mode,
+        severity_class: fm.severity_class,
+      });
+    }
+  }
+
+  const score = validated / failureModes.length;
+
+  return {
+    schema_version: '1',
+    generated: new Date().toISOString(),
+    gate_c_score: Math.round(score * 10000) / 10000,
+    total_entries: failureModes.length,
+    validated_entries: validated,
+    unvalidated_entries: gaps.length,
+    gaps,
+    target: 0.8,
+    target_met: score >= 0.8,
+  };
+}
+
+// ── Entry point ──────────────────────────────────────────────────────────
+
+function main() {
+  const startMs = Date.now();
+
+  // Load failure-mode-catalog
+  const fmPath = path.join(REASONING_DIR, 'failure-mode-catalog.json');
+  if (!fs.existsSync(fmPath)) {
+    console.error('ERROR: failure-mode-catalog.json not found at', fmPath);
+    process.exit(1);
+  }
+  const fmData = JSON.parse(fs.readFileSync(fmPath, 'utf8'));
+  const failureModes = fmData.failure_modes || [];
+
+  // Load test-recipes
+  const trPath = path.join(RECIPES_DIR, 'test-recipes.json');
+  if (!fs.existsSync(trPath)) {
+    console.error('ERROR: test-recipes.json not found at', trPath);
+    console.error('Run bin/test-recipe-gen.cjs first to generate recipes.');
+    process.exit(1);
+  }
+  const trData = JSON.parse(fs.readFileSync(trPath, 'utf8'));
+  const recipes = trData.recipes || [];
+
+  const result = computeGateC(failureModes, recipes);
+  const runtimeMs = Date.now() - startMs;
+
+  // Write output
+  fs.mkdirSync(GATES_DIR, { recursive: true });
+  fs.writeFileSync(OUT_FILE, JSON.stringify(result, null, 2) + '\n');
+
+  // Emit check result
+  try {
+    const { writeCheckResult } = require(path.join(__dirname, 'write-check-result.cjs'));
+    writeCheckResult({
+      tool: 'gate-c-validation',
+      formalism: 'trace',
+      result: result.target_met ? 'pass' : 'fail',
+      check_id: 'gate-c:recipe-coverage',
+      surface: 'trace',
+      property: `Gate C test recipe coverage: ${(result.gate_c_score * 100).toFixed(1)}% (target: 80%)`,
+      runtime_ms: runtimeMs,
+      summary: `${result.target_met ? 'pass' : 'fail'}: coverage ${(result.gate_c_score * 100).toFixed(1)}%, ${result.validated_entries}/${result.total_entries} validated`,
+      requirement_ids: ['GATE-03'],
+      metadata: {
+        gate_c_score: result.gate_c_score,
+        target: result.target,
+        target_met: result.target_met,
+        gaps_count: result.unvalidated_entries,
+      },
+    });
+  } catch (e) {
+    // write-check-result.cjs not available; skip
+  }
+
+  if (JSON_FLAG) {
+    process.stdout.write(JSON.stringify(result));
+  } else {
+    console.log('Gate C: L3-to-Test-Recipe Coverage');
+    console.log(`  Score: ${(result.gate_c_score * 100).toFixed(1)}%`);
+    console.log(`  Total entries: ${result.total_entries}`);
+    console.log(`  Validated: ${result.validated_entries}`);
+    console.log(`  Unvalidated: ${result.unvalidated_entries}`);
+    console.log(`  Target met: ${result.target_met}`);
+    if (result.gaps.length > 0) {
+      console.log('  Gaps:');
+      for (const g of result.gaps) {
+        console.log(`    - ${g.failure_mode_id} (${g.failure_mode}/${g.severity_class})`);
+      }
+    }
+    console.log(`  Output: ${OUT_FILE}`);
+  }
+
+  process.exit(result.target_met ? 0 : 1);
+}
+
+if (require.main === module) main();
+
+module.exports = { computeGateC, main };

package/bin/generate-formal-specs.cjs

@@ -3,11 +3,11 @@
 // bin/generate-formal-specs.cjs
 // Generates ALL formal verification artifacts from the XState machine.
 //
-// The XState machine (src/machines/qgsd-workflow.machine.ts) is the SINGLE SOURCE OF TRUTH.
+// The XState machine (src/machines/nf-workflow.machine.ts) is the SINGLE SOURCE OF TRUTH.
 // All formal specs are generated artifacts — do not edit them by hand.
 //
 // Generates:
-//   .planning/formal/tla/QGSDQuorum.tla   — TLA+ spec (states, transitions, invariants)
+//   .planning/formal/tla/NFQuorum.tla   — TLA+ spec (states, transitions, invariants)
 //   .planning/formal/tla/MCsafety.cfg     — TLC safety model config (N=5, symmetry)
 //   .planning/formal/tla/MCliveness.cfg   — TLC liveness model config (N=3)
 //   .planning/formal/alloy/quorum-votes.als — Alloy vote-counting model
@@ -68,7 +68,7 @@ function updateModelRegistry(absPath) {
 }
 
 // ── Parse XState machine ──────────────────────────────────────────────────────
-const machineFile = path.join(ROOT, 'src', 'machines', 'qgsd-workflow.machine.ts');
+const machineFile = path.join(ROOT, 'src', 'machines', 'nf-workflow.machine.ts');
 if (!fs.existsSync(machineFile)) {
   process.stderr.write('[generate-formal-specs] XState machine not found at ' + machineFile + ' — skipping (not required for external projects)\n');
   process.exit(0);
@@ -114,7 +114,7 @@ const ts = new Date().toISOString().split('T')[0];
 const GENERATED_HEADER = (comment, file) =>
   comment + ' ' + file + '\n' +
   comment + ' GENERATED — do not edit by hand.\n' +
-  comment + ' Source of truth: src/machines/qgsd-workflow.machine.ts\n' +
+  comment + ' Source of truth: src/machines/nf-workflow.machine.ts\n' +
   comment + ' Regenerate:      node bin/generate-formal-specs.cjs\n' +
   comment + ' Generated:       ' + ts + '\n';
 
@@ -148,17 +148,17 @@ const GUARD_REGISTRY = {
   },
 };
 
-// ── 1. QGSDQuorum.tla ─────────────────────────────────────────────────────────
+// ── 1. NFQuorum.tla ─────────────────────────────────────────────────────────
 // Intermediate states = all states except initial and final
 const collectingState   = 'COLLECTING_VOTES';
 const deliberatingState = 'DELIBERATING';
 const phaseSet = stateNames.map(s => '"' + s + '"').join(', ');
 
 const tlaSpec = [
-  '---- MODULE QGSDQuorum ----',
+  '---- MODULE NFQuorum ----',
   '(*',
-  GENERATED_HEADER(' *', '.planning/formal/tla/QGSDQuorum.tla'),
-  ' * Models the quorum workflow defined in src/machines/qgsd-workflow.machine.ts.',
+  GENERATED_HEADER(' *', '.planning/formal/tla/NFQuorum.tla'),
+  ' * Models the quorum workflow defined in src/machines/nf-workflow.machine.ts.',
   ' * Guard translations (from GUARD_REGISTRY in bin/generate-formal-specs.cjs):',
   ' *   unanimityMet (' + GUARD_REGISTRY.unanimityMet.ts + '):   ' + GUARD_REGISTRY.unanimityMet.tla,
   ' *   noInfiniteDeliberation (' + GUARD_REGISTRY.noInfiniteDeliberation.ts + '):  ' + GUARD_REGISTRY.noInfiniteDeliberation.tla,
@@ -335,7 +335,7 @@ function agentsSet(n) {
 const tlaCfgHeader = (file, desc) => [
   '\\* ' + file,
   '\\* GENERATED — do not edit by hand.',
-  '\\* Source of truth: src/machines/qgsd-workflow.machine.ts',
+  '\\* Source of truth: src/machines/nf-workflow.machine.ts',
   '\\* Regenerate:      node bin/generate-formal-specs.cjs',
   '\\* Generated:       ' + ts,
   '\\*',
@@ -379,10 +379,10 @@ const livenessCfg = tlaCfgHeader('.planning/formal/tla/MCliveness.cfg',
 // Alloy vote-counting model — derived from unanimityMet guard in XState machine
 const alloySpec = [
   GENERATED_HEADER('--', '.planning/formal/alloy/quorum-votes.als'),
-  '-- QGSD Quorum Vote-Counting Model (Alloy 6)',
+  '-- nForma Quorum Vote-Counting Model (Alloy 6)',
   '-- Requirements: ALY-01',
   '--',
-  '-- Models the unanimityMet guard from src/machines/qgsd-workflow.machine.ts:',
+  '-- Models the unanimityMet guard from src/machines/nf-workflow.machine.ts:',
   '--   ' + GUARD_REGISTRY.unanimityMet.ts,
   '--   ≡  ' + GUARD_REGISTRY.unanimityMet.alloy + '  (all polled agents approved)',
   '--',
@@ -390,11 +390,11 @@ const alloySpec = [
   '-- ' + GUARD_REGISTRY.unanimityMet.desc,
   '--',
   '-- Checks that no round reaches ' + finalState + ' without satisfying the unanimity predicate.',
-  '-- Scope: ' + SAFETY_AGENTS + ' agents (QGSD quorum slot count), 5 vote rounds.',
+  '-- Scope: ' + SAFETY_AGENTS + ' agents (nForma quorum slot count), 5 vote rounds.',
   '',
   'module quorum_votes',
   '',
-  '-- Fix agent count to ' + SAFETY_AGENTS + ' (QGSD quorum slot count).',
+  '-- Fix agent count to ' + SAFETY_AGENTS + ' (nForma quorum slot count).',
   '-- This makes the numeric threshold assertions below concrete and verifiable.',
   'fact AgentCount { #Agent = ' + SAFETY_AGENTS + ' }',
   '',
@@ -458,7 +458,7 @@ const alloySpec = [
 // State numbering: 0=collecting, 1=decided, 2=deliberating (absorbing at 1)
 const prismSpec = [
   GENERATED_HEADER('//', '.planning/formal/prism/quorum.pm'),
-  '// QGSD Quorum Convergence — DTMC Model',
+  '// nForma Quorum Convergence — DTMC Model',
   '// Requirements: PRM-01',
   '//',
   '// Discrete-Time Markov Chain modeling quorum state transitions.',
@@ -467,7 +467,7 @@ const prismSpec = [
   '//   s=1 : ' + finalState + '       (absorbing)',
   '//   s=2 : ' + deliberatingState + '     (retry)',
   '//',
-  '// Derived from src/machines/qgsd-workflow.machine.ts:',
+  '// Derived from src/machines/nf-workflow.machine.ts:',
   '//   ' + stateNames.join(', '),
   '//',
   '// Guard translations (from GUARD_REGISTRY):',
@@ -528,7 +528,7 @@ const prismSpec = [
 const prismProps = [
   '// .planning/formal/prism/quorum.props',
   '// GENERATED — do not edit by hand.',
-  '// Source of truth: src/machines/qgsd-workflow.machine.ts',
+  '// Source of truth: src/machines/nf-workflow.machine.ts',
   '// Regenerate:      node bin/generate-formal-specs.cjs',
   '// Generated:       ' + ts,
   '//',
@@ -558,7 +558,7 @@ const prismProps = [
 
 // ── Write or print ────────────────────────────────────────────────────────────
 const outputs = [
-  { rel: '.planning/formal/tla/QGSDQuorum.tla',              content: tlaSpec      },
+  { rel: '.planning/formal/tla/NFQuorum.tla',              content: tlaSpec      },
   { rel: '.planning/formal/tla/MCsafety.cfg',                content: safetyCfg    },
   { rel: '.planning/formal/tla/MCliveness.cfg',              content: livenessCfg  },
   { rel: '.planning/formal/alloy/quorum-votes.als',           content: alloySpec    },

package/bin/generate-petri-net.cjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 // bin/generate-petri-net.cjs
-// Generates a Graphviz DOT + SVG Petri Net for the QGSD quorum token-passing model.
+// Generates a Graphviz DOT + SVG Petri Net for the nForma quorum token-passing model.
 // Requirements: PET-01, PET-02, PET-03
 //
 // Usage:
@@ -44,7 +44,7 @@ function buildDot(slots, minQuorum) {
   return [
     'digraph quorum_petri_net {',
     '  rankdir=LR;',
-    '  label="QGSD Quorum Petri Net (min_quorum=' + minQuorum + '/' + slots.length + ')";',
+    '  label="nForma Quorum Petri Net (min_quorum=' + minQuorum + '/' + slots.length + ')";',
     '  node [fontname="Helvetica"];',
     '',
     '  // Places (circles)',
@@ -158,7 +158,7 @@ function buildRoadmapDot(phases) {
   const lines = [
     'digraph roadmap_petri_net {',
     '  rankdir=LR;',
-    '  label="QGSD Roadmap Petri Net (' + phases.length + ' phases)";',
+    '  label="nForma Roadmap Petri Net (' + phases.length + ' phases)";',
     '  node [fontname="Helvetica"];',
     '',
   ];

package/bin/generate-tla-cfg.cjs

@@ -3,7 +3,7 @@
 // bin/generate-tla-cfg.cjs
 // Generates TLA+ model configuration files from the XState machine.
 //
-// The XState machine (src/machines/qgsd-workflow.machine.ts) is the SOURCE OF TRUTH.
+// The XState machine (src/machines/nf-workflow.machine.ts) is the SOURCE OF TRUTH.
 // MCsafety.cfg and MCliveness.cfg are generated artifacts — do not edit them by hand.
 // To change MaxDeliberation, update the XState machine context default instead.
 //
@@ -23,11 +23,11 @@ const ROOT  = path.join(__dirname, '..');
 const DRY   = process.argv.includes('--dry');
 
 // ── Model-checking parameters (stable, not derived from code) ─────────────────
-const SAFETY_AGENTS   = 5;   // N for MCsafety — matches QGSD quorum slot count
+const SAFETY_AGENTS   = 5;   // N for MCsafety — matches nForma quorum slot count
 const LIVENESS_AGENTS = 3;   // N for MCliveness — smaller for tractable liveness
 
 // ── Extract MaxDeliberation from the XState machine ───────────────────────────
-const machineFile = path.join(ROOT, 'src', 'machines', 'qgsd-workflow.machine.ts');
+const machineFile = path.join(ROOT, 'src', 'machines', 'nf-workflow.machine.ts');
 if (!fs.existsSync(machineFile)) {
   process.stderr.write('[generate-tla-cfg] XState machine not found: ' + machineFile + '\n');
   process.exit(1);
@@ -64,7 +64,7 @@ function agentsSet(n) {
 const safetyCfg = [
   '\\* .planning/formal/tla/MCsafety.cfg',
   '\\* GENERATED — do not edit by hand.',
-  '\\* Source of truth: src/machines/qgsd-workflow.machine.ts',
+  '\\* Source of truth: src/machines/nf-workflow.machine.ts',
   '\\* Regenerate: node bin/generate-tla-cfg.cjs',
   '\\*',
   '\\* TLC safety model: N=' + SAFETY_AGENTS + ' agents, symmetry reduction, no liveness check.',
@@ -87,7 +87,7 @@ const safetyCfg = [
 const livenessCfg = [
   '\\* .planning/formal/tla/MCliveness.cfg',
   '\\* GENERATED — do not edit by hand.',
-  '\\* Source of truth: src/machines/qgsd-workflow.machine.ts',
+  '\\* Source of truth: src/machines/nf-workflow.machine.ts',
   '\\* Regenerate: node bin/generate-tla-cfg.cjs',
   '\\*',
   '\\* TLC liveness model: N=' + LIVENESS_AGENTS + ' agents, NO symmetry (incompatible with liveness), PROPERTY only.',