@nforma.ai/nforma 0.2.1 → 0.29.0

package/bin/test-recipe-gen.cjs

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * test-recipe-gen.cjs — Transform L3 failure modes into executable test recipe JSON.
+ *
+ * Reads failure-mode-catalog.json, hazard-model.json, and risk-heatmap.json
+ * to produce test recipes with setup, input_sequence, expected_outcome,
+ * oracle, risk_context, and derived_from for each failure mode.
+ *
+ * Requirements: RSN-04
+ *
+ * Usage:
+ *   node bin/test-recipe-gen.cjs            # print summary to stdout
+ *   node bin/test-recipe-gen.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 OUT_DIR = path.join(FORMAL, 'test-recipes');
+const OUT_FILE = path.join(OUT_DIR, 'test-recipes.json');
+
+const JSON_FLAG = process.argv.includes('--json');
+
+// ── Recipe builders ──────────────────────────────────────────────────────
+
+function buildSetup(fm) {
+  return {
+    initial_state: fm.state,
+    preconditions: [`Machine is in ${fm.state} state`],
+  };
+}
+
+function buildInputSequence(fm) {
+  return [
+    {
+      event: fm.event,
+      description: `Send ${fm.event} event to machine in ${fm.state} state`,
+    },
+  ];
+}
+
+function buildExpectedOutcome(fm) {
+  switch (fm.failure_mode) {
+    case 'omission':
+      return {
+        final_state: fm.to_state,
+        assertions: [`Machine transitions to ${fm.to_state}`],
+      };
+    case 'commission':
+      return {
+        rejection: true,
+        assertions: [`Machine remains in ${fm.state}; event ${fm.event} is rejected`],
+      };
+    case 'corruption':
+      return {
+        final_state: fm.to_state,
+        not_state: 'any_other',
+        assertions: [`Machine transitions to exactly ${fm.to_state}, not any other state`],
+      };
+    default:
+      return { final_state: fm.to_state, assertions: [] };
+  }
+}
+
+function buildOracle(fm) {
+  switch (fm.failure_mode) {
+    case 'omission':
+      return {
+        type: 'state_assertion',
+        check: `machine.state === '${fm.to_state}'`,
+        failure_indicates: 'Omission: transition did not fire',
+      };
+    case 'commission':
+      return {
+        type: 'guard_rejection',
+        check: `machine.state === '${fm.state}'`,
+        failure_indicates: 'Commission: unmodeled event was accepted',
+      };
+    case 'corruption':
+      return {
+        type: 'state_equality',
+        check: `machine.state === '${fm.to_state}'`,
+        failure_indicates: 'Corruption: wrong target state reached',
+      };
+    default:
+      return { type: 'unknown', check: '', failure_indicates: '' };
+  }
+}
+
+function buildRiskContext(fm, hazardMap, riskMap) {
+  const key = `${fm.state}-${fm.event}`;
+  const hazard = hazardMap.get(key);
+  const risk = riskMap.get(key);
+
+  return {
+    severity_class: fm.severity_class || null,
+    rpn: hazard ? hazard.rpn : null,
+    risk_tier: risk ? risk.risk_tier : null,
+  };
+}
+
+function buildDerivedFrom(fm) {
+  const refs = [
+    {
+      layer: 'L3',
+      artifact: 'reasoning/failure-mode-catalog.json',
+      ref: `failure_modes[id=${fm.id}]`,
+    },
+  ];
+
+  // Add hazard-model reference if the failure mode has one
+  if (fm.derived_from) {
+    const hazardLink = fm.derived_from.find(
+      d => d.artifact === 'reasoning/hazard-model.json'
+    );
+    if (hazardLink) {
+      refs.push({
+        layer: 'L3',
+        artifact: hazardLink.artifact,
+        ref: hazardLink.ref,
+      });
+    }
+  }
+
+  return refs;
+}
+
+function generateRecipe(fm, hazardMap, riskMap) {
+  return {
+    id: `TR-${fm.id}`,
+    failure_mode_id: fm.id,
+    title: `Test ${fm.failure_mode} of ${fm.state} --[${fm.event}]--> ${fm.to_state}`,
+    setup: buildSetup(fm),
+    input_sequence: buildInputSequence(fm),
+    expected_outcome: buildExpectedOutcome(fm),
+    oracle: buildOracle(fm),
+    risk_context: buildRiskContext(fm, hazardMap, riskMap),
+    derived_from: buildDerivedFrom(fm),
+  };
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────
+
+function generateAllRecipes(failureModes, hazards, riskTransitions) {
+  // Build lookup maps by state-event key
+  const hazardMap = new Map();
+  for (const h of hazards) {
+    hazardMap.set(`${h.state}-${h.event}`, h);
+  }
+
+  const riskMap = new Map();
+  for (const t of riskTransitions) {
+    riskMap.set(`${t.state}-${t.event}`, t);
+  }
+
+  const recipes = failureModes.map(fm => generateRecipe(fm, hazardMap, riskMap));
+
+  // Compute summary
+  const byFailureMode = {};
+  const byRiskTier = {};
+  for (const r of recipes) {
+    const fmType = r.oracle.type === 'state_assertion' ? 'omission'
+      : r.oracle.type === 'guard_rejection' ? 'commission'
+      : r.oracle.type === 'state_equality' ? 'corruption'
+      : 'unknown';
+    byFailureMode[fmType] = (byFailureMode[fmType] || 0) + 1;
+
+    const tier = r.risk_context.risk_tier || 'unclassified';
+    byRiskTier[tier] = (byRiskTier[tier] || 0) + 1;
+  }
+
+  return {
+    schema_version: '1',
+    generated: new Date().toISOString(),
+    source: {
+      failure_mode_catalog: 'reasoning/failure-mode-catalog.json',
+      hazard_model: 'reasoning/hazard-model.json',
+      risk_heatmap: 'reasoning/risk-heatmap.json',
+    },
+    recipes,
+    summary: {
+      total_recipes: recipes.length,
+      by_failure_mode: byFailureMode,
+      by_risk_tier: byRiskTier,
+    },
+  };
+}
+
+function main() {
+  // 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 hazard-model (optional)
+  let hazards = [];
+  const hmPath = path.join(REASONING_DIR, 'hazard-model.json');
+  if (fs.existsSync(hmPath)) {
+    const hmData = JSON.parse(fs.readFileSync(hmPath, 'utf8'));
+    hazards = hmData.hazards || [];
+  }
+
+  // Load risk-heatmap (optional)
+  let riskTransitions = [];
+  const rhPath = path.join(REASONING_DIR, 'risk-heatmap.json');
+  if (fs.existsSync(rhPath)) {
+    const rhData = JSON.parse(fs.readFileSync(rhPath, 'utf8'));
+    riskTransitions = rhData.transitions || [];
+  }
+
+  const result = generateAllRecipes(failureModes, hazards, riskTransitions);
+
+  // Write output
+  fs.mkdirSync(OUT_DIR, { recursive: true });
+  fs.writeFileSync(OUT_FILE, JSON.stringify(result, null, 2) + '\n');
+
+  if (JSON_FLAG) {
+    process.stdout.write(JSON.stringify(result));
+  } else {
+    console.log('Test Recipe Generator');
+    console.log(`  Total recipes: ${result.summary.total_recipes}`);
+    console.log(`  By failure mode: ${JSON.stringify(result.summary.by_failure_mode)}`);
+    console.log(`  By risk tier: ${JSON.stringify(result.summary.by_risk_tier)}`);
+    console.log(`  Output: ${OUT_FILE}`);
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  generateRecipe,
+  generateAllRecipes,
+  buildInputSequence,
+  buildExpectedOutcome,
+  buildOracle,
+  buildSetup,
+  buildRiskContext,
+  buildDerivedFrom,
+};

package/bin/trace-corpus-stats.cjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+'use strict';
+// bin/trace-corpus-stats.cjs
+// Indexes conformance events by session, action type, and state transition.
+// Infers sessions using timestamp gaps.
+//
+// Requirement: EVID-02
+
+const fs   = require('fs');
+const path = require('path');
+
+const ROOT = process.env.PROJECT_ROOT || path.join(__dirname, '..');
+const EVIDENCE_DIR = path.join(ROOT, '.planning', 'formal', 'evidence');
+const VOCAB_PATH = path.join(EVIDENCE_DIR, 'event-vocabulary.json');
+const OUTPUT_PATH = path.join(EVIDENCE_DIR, 'trace-corpus-stats.json');
+
+const JSON_FLAG = process.argv.includes('--json');
+
+// Parse --session-gap-ms from CLI
+const DEFAULT_SESSION_GAP_MS = 300000; // 5 minutes
+function parseSessionGapMs() {
+  const idx = process.argv.indexOf('--session-gap-ms');
+  if (idx >= 0 && process.argv[idx + 1]) {
+    const val = parseInt(process.argv[idx + 1], 10);
+    if (!isNaN(val) && val > 0) return val;
+  }
+  return DEFAULT_SESSION_GAP_MS;
+}
+
+// ── Session inference ───────────────────────────────────────────────────────
+
+/**
+ * Infer sessions from sorted events using timestamp gap analysis.
+ * A gap > sessionGapMs between consecutive events starts a new session.
+ */
+function inferSessions(events, sessionGapMs) {
+  if (events.length === 0) return [];
+
+  const sessions = [];
+  let currentSession = {
+    id: 'session-001',
+    events: [events[0]],
+  };
+
+  for (let i = 1; i < events.length; i++) {
+    const prevTs = new Date(events[i - 1].ts || events[i - 1].timestamp).getTime();
+    const currTs = new Date(events[i].ts || events[i].timestamp).getTime();
+    const gap = currTs - prevTs;
+
+    if (gap > sessionGapMs) {
+      sessions.push(currentSession);
+      const num = String(sessions.length + 1).padStart(3, '0');
+      currentSession = {
+        id: `session-${num}`,
+        events: [events[i]],
+      };
+    } else {
+      currentSession.events.push(events[i]);
+    }
+  }
+  sessions.push(currentSession);
+
+  return sessions;
+}
+
+/**
+ * Build session summary from raw session with events.
+ */
+function summarizeSession(session) {
+  const events = session.events;
+  const timestamps = events.map(e => new Date(e.ts || e.timestamp).getTime()).filter(t => !isNaN(t));
+  const start = timestamps.length > 0 ? new Date(Math.min(...timestamps)).toISOString() : null;
+  const end = timestamps.length > 0 ? new Date(Math.max(...timestamps)).toISOString() : null;
+
+  const actions = {};
+  for (const e of events) {
+    const action = e.action || 'undefined';
+    actions[action] = (actions[action] || 0) + 1;
+  }
+
+  return {
+    id: session.id,
+    start,
+    end,
+    event_count: events.length,
+    actions,
+  };
+}
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+function main() {
+  const sessionGapMs = parseSessionGapMs();
+
+  // Ensure output directory
+  if (!fs.existsSync(EVIDENCE_DIR)) {
+    fs.mkdirSync(EVIDENCE_DIR, { recursive: true });
+  }
+
+  // Read conformance events using planning-paths
+  const pp = require('./planning-paths.cjs');
+  const eventsPath = pp.resolve(process.cwd(), 'conformance-events');
+
+  if (!fs.existsSync(eventsPath)) {
+    console.error(`Conformance events file not found: ${eventsPath}`);
+    process.exit(1);
+  }
+
+  const raw = fs.readFileSync(eventsPath, 'utf8');
+  const lines = raw.split('\n').filter(l => l.trim());
+  const events = [];
+
+  for (const line of lines) {
+    try {
+      events.push(JSON.parse(line));
+    } catch (_) {
+      // Skip malformed lines
+    }
+  }
+
+  // Sort by timestamp
+  events.sort((a, b) => {
+    const tsA = new Date(a.ts || a.timestamp).getTime();
+    const tsB = new Date(b.ts || b.timestamp).getTime();
+    return tsA - tsB;
+  });
+
+  // Infer sessions
+  const rawSessions = inferSessions(events, sessionGapMs);
+  const sessions = rawSessions.map(summarizeSession);
+
+  // Build action index
+  const actionIndex = {};
+  for (const session of sessions) {
+    for (const [action, count] of Object.entries(session.actions)) {
+      if (!actionIndex[action]) {
+        actionIndex[action] = { total: 0, sessions: [] };
+      }
+      actionIndex[action].total += count;
+      actionIndex[action].sessions.push(session.id);
+    }
+  }
+
+  // Build transition index
+  const transitionCounts = {};
+  for (const event of events) {
+    if (event.from_state && event.to_state) {
+      const key = `${event.from_state}→${event.to_state}`;
+      transitionCounts[key] = (transitionCounts[key] || 0) + 1;
+    }
+  }
+  const transitionIndex = Object.entries(transitionCounts).map(([key, count]) => {
+    const [from, to] = key.split('→');
+    return { from, to, count };
+  });
+
+  // Date range
+  const timestamps = events.map(e => new Date(e.ts || e.timestamp).getTime()).filter(t => !isNaN(t));
+  const dateRange = timestamps.length > 0
+    ? { earliest: new Date(Math.min(...timestamps)).toISOString(), latest: new Date(Math.max(...timestamps)).toISOString() }
+    : { earliest: null, latest: null };
+
+  // Vocabulary validation
+  const vocab = JSON.parse(fs.readFileSync(VOCAB_PATH, 'utf8'));
+  const vocabActions = new Set(Object.keys(vocab.vocabulary));
+  const allActions = new Set(Object.keys(actionIndex));
+  const known = [...allActions].filter(a => vocabActions.has(a));
+  const unknown = [...allActions].filter(a => !vocabActions.has(a));
+
+  // Build result
+  const result = {
+    schema_version: '1',
+    generated: new Date().toISOString(),
+    session_gap_ms: sessionGapMs,
+    total_events: events.length,
+    date_range: dateRange,
+    sessions,
+    action_index: actionIndex,
+    transition_index: transitionIndex,
+    vocabulary_validation: {
+      known: known.length,
+      unknown: unknown.length,
+      unknown_actions: unknown,
+    },
+    summary: `${events.length} events across ${sessions.length} sessions ` +
+             `(${dateRange.earliest} to ${dateRange.latest}). ` +
+             `${known.length} known actions, ${unknown.length} unknown. ` +
+             `${transitionIndex.length} distinct transitions.`,
+  };
+
+  fs.writeFileSync(OUTPUT_PATH, JSON.stringify(result, null, 2) + '\n', 'utf8');
+
+  if (JSON_FLAG) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`Trace Corpus Stats Generated`);
+    console.log(`  Total events: ${events.length}`);
+    console.log(`  Sessions: ${sessions.length}`);
+    console.log(`  Date range: ${dateRange.earliest} to ${dateRange.latest}`);
+    console.log(`  Known actions: ${known.length}, Unknown: ${unknown.length}`);
+    console.log(`  Transitions: ${transitionIndex.length}`);
+  }
+}
+
+// Export for testing
+module.exports = { inferSessions, summarizeSession, parseSessionGapMs, DEFAULT_SESSION_GAP_MS };
+
+// Run if invoked directly
+if (require.main === module) {
+  main();
+}

package/bin/unified-mcp-server.mjs

@@ -110,7 +110,7 @@ function buildSlotTools(provider) {
   // Universal: identity
   tools.push({
     name: 'identity',
-    description: 'Get server identity: name, version, active LLM model, and MCP server name. Used by QGSD to fingerprint the active quorum team.',
+    description: 'Get server identity: name, version, active LLM model, and MCP server name. Used by nForma to fingerprint the active quorum team.',
     inputSchema: NO_ARGS_SCHEMA,
   });
 
@@ -526,7 +526,7 @@ function buildIdentityResult(provider) {
     model,
     display_provider: provider.display_provider ?? null,
     provider: provider.description,
-    install_method: 'qgsd-monorepo',
+    install_method: 'nf-monorepo',
   });
 }
 
@@ -699,7 +699,7 @@ async function main() {
     const keytarAccount = 'ANTHROPIC_API_KEY_' + SLOT.toUpperCase().replace(/-/g, '_');
     try {
       const { default: keytar } = await import('keytar');
-      const secret = await keytar.getPassword('qgsd', keytarAccount);
+      const secret = await keytar.getPassword('nforma', keytarAccount);
       if (secret) {
         process.env.ANTHROPIC_API_KEY = secret;
         process.stderr.write(`[unified-mcp-server] Loaded API key for slot ${SLOT} from keychain\n`);

package/bin/update-scoreboard.cjs

@@ -555,7 +555,7 @@ async function initTeam(argv) {
   let mcps = [];
   let plugins = [];
   try {
-    const claudeJsonPath = process.env.QGSD_CLAUDE_JSON || path.join(os.homedir(), '.claude.json');
+    const claudeJsonPath = process.env.NF_CLAUDE_JSON || path.join(os.homedir(), '.claude.json');
     const claudeJson = JSON.parse(fs.readFileSync(claudeJsonPath, 'utf8'));
     mcps = Object.keys(claudeJson.mcpServers || {});
     plugins = claudeJson.plugins || [];

package/bin/validate-memory.cjs

@@ -4,7 +4,7 @@
 /**
  * validate-memory.cjs
  *
- * Memory staleness checker for QGSD auto-memory (MEMORY.md).
+ * Memory staleness checker for nForma auto-memory (MEMORY.md).
  *
  * Checks:
  *   1. Stale counts — numbers referencing requirements.json count vs actual
@@ -147,7 +147,7 @@ function checkDeadFileRefs(memoryContent, cwd) {
 
       // Skip URLs, patterns, and common non-path references
       if (ref.includes('://') || ref.includes('*') || ref.includes('{')) continue;
-      // Skip package names like qgsd@0.2.0
+      // Skip package names like nforma@0.2.0
       if (ref.includes('@')) continue;
       // Skip references that start with ~ (home dir)
       if (ref.startsWith('~')) {

package/bin/validate-traces.cjs

@@ -120,8 +120,8 @@ function buildTTrace(event, actualState, expectedStateName, divergenceType, scor
       const _path = require('path');
       const _fs   = require('fs');
       const _machinePath = (() => {
-        const repoDist    = _path.join(__dirname, '..', 'dist', 'machines', 'qgsd-workflow.machine.cjs');
-        const installDist = _path.join(__dirname, 'dist', 'machines', 'qgsd-workflow.machine.cjs');
+        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 } = require(_machinePath);
@@ -237,15 +237,15 @@ if (require.main === module) {
   const _startMs = Date.now();
   const { writeCheckResult } = require('./write-check-result.cjs');
   // Machine CJS path: in the repo, ../dist/machines/ (bin/ → dist/machines/)
-  // When installed at ~/.claude/qgsd-bin/, ./dist/machines/ (qgsd-bin/ → qgsd-bin/dist/machines/)
+  // When installed at ~/.claude/nf-bin/, ./dist/machines/ (nf-bin/ → nf-bin/dist/machines/)
   const machinePath = (function () {
-    const repoDist = path.join(__dirname, '..', 'dist', 'machines', 'qgsd-workflow.machine.cjs');
-    const installDist = path.join(__dirname, 'dist', 'machines', 'qgsd-workflow.machine.cjs');
+    const repoDist = path.join(__dirname, '..', 'dist', 'machines', 'nf-workflow.machine.js');
+    const installDist = path.join(__dirname, 'dist', 'machines', 'nf-workflow.machine.js');
     if (fs.existsSync(repoDist)) return repoDist;
     if (fs.existsSync(installDist)) return installDist;
-    throw new Error('[validate-traces] Cannot find qgsd-workflow.machine.cjs in ' + repoDist + ' or ' + installDist);
+    throw new Error('[validate-traces] Cannot find nf-workflow.machine.js in ' + repoDist + ' or ' + installDist);
   })();
-  const { createActor, qgsdWorkflowMachine } = require(machinePath);
+  const { createActor, nfWorkflowMachine } = require(machinePath);
 
   // Load walker for TTrace export (DIAG-01) — lazy-loaded here to avoid breaking module.exports usage
   let walker = null;
@@ -358,7 +358,7 @@ if (require.main === module) {
     }
 
     // Fresh actor per event — each conformance event is a single-step trace
-    const actor = createActor(qgsdWorkflowMachine);
+    const actor = createActor(nfWorkflowMachine);
     actor.start();
     actor.send(xstateEvent);
     const snapshot = actor.getSnapshot();
@@ -372,7 +372,7 @@ if (require.main === module) {
       const roundKey    = event.round_id || event.session_id || '__standalone__' + event._lineIndex;
       const roundEvents = roundGroups.get(roundKey) || [event];
       divergences.push(
-        buildTTrace(event, snapshot.value, expected, 'state_mismatch', scoreboardMeta, confidence, walker, qgsdWorkflowMachine, roundEvents)
+        buildTTrace(event, snapshot.value, expected, 'state_mismatch', scoreboardMeta, confidence, walker, nfWorkflowMachine, roundEvents)
       );
     }
   }
@@ -434,5 +434,5 @@ if (require.main === module) {
 }
 
 if (typeof module !== 'undefined') {
-  module.exports = { computeConfidenceTier, CONFIDENCE_THRESHOLDS, validateMCPMetadata, buildTTrace };
+  module.exports = { computeConfidenceTier, CONFIDENCE_THRESHOLDS, validateMCPMetadata, buildTTrace, mapToXStateEvent };
 }