@nforma.ai/nforma 0.2.1 → 0.29.0

package/bin/sensitivity-report.cjs

@@ -22,7 +22,7 @@ const REPORT_MD_PATH = process.env.SENSITIVITY_MD_PATH ||
 
 const PARAM_ANNOTATIONS = {
   MaxSize: {
-    codePath: 'hooks/qgsd-prompt.js FAN_OUT_COUNT; .planning/formal/tla/MCsafety.cfg MaxSize',
+    codePath: 'hooks/nf-prompt.js FAN_OUT_COUNT; .planning/formal/tla/MCsafety.cfg MaxSize',
     testCases: [
       'Test quorum at N=2 boundary: set FAN_OUT_COUNT=2 in providers.json and run quorum round',
       'Test quorum at N=1 (no quorum): verify workflow rejects insufficient available slots',
@@ -44,7 +44,7 @@ const PARAM_ANNOTATIONS = {
     ],
   },
   MaxDeliberation: {
-    codePath: '.planning/formal/tla/MCsafety.cfg MaxDeliberation=7; src/machines/qgsd-workflow.machine.ts MaxDeliberation guard',
+    codePath: '.planning/formal/tla/MCsafety.cfg MaxDeliberation=7; src/machines/nf-workflow.machine.ts MaxDeliberation guard',
     testCases: [
       'Test quorum workflow with max deliberation rounds reached — verify DECIDED fallback',
       'Test rapid-fire slot responses (all within 1 deliberation round)',
@@ -89,7 +89,7 @@ function parseNDJSON(filePath) {
 function generateReport(records) {
   const now = new Date().toISOString();
   const lines = [
-    '# Sensitivity Report — QGSD v0.20',
+    '# Sensitivity Report — nForma v0.20',
     '',
     'Generated: ' + now,
     'Source: .planning/formal/sensitivity-report.ndjson (' + records.length + ' records)',

package/bin/set-secret.cjs

@@ -4,8 +4,8 @@
  * set-secret.cjs
  * Usage: node bin/set-secret.cjs <KEY_NAME> <value>
  *
- * Stores KEY_NAME=value in the OS keychain under service "qgsd",
- * then syncs all qgsd secrets into ~/.claude.json mcpServers env blocks.
+ * Stores KEY_NAME=value in the OS keychain under service "nforma",
+ * then syncs all nforma secrets into ~/.claude.json mcpServers env blocks.
  */
 const { set, syncToClaudeJson, SERVICE } = require('./secrets.cjs');
 
@@ -19,11 +19,11 @@ const value = valueParts.join(' ');
 (async () => {
   try {
     await set(SERVICE, keyName, value);
-    console.log(`[qgsd] Stored ${keyName} in keychain (service: ${SERVICE})`);
+    console.log(`[nf] Stored ${keyName} in keychain (service: ${SERVICE})`);
     await syncToClaudeJson(SERVICE);
-    console.log('[qgsd] Synced keychain secrets to ~/.claude.json');
+    console.log('[nf] Synced keychain secrets to ~/.claude.json');
   } catch (e) {
-    console.error('[qgsd] Error:', e.message);
+    console.error('[nf] Error:', e.message);
     process.exit(1);
   }
 })();

package/bin/setup-telemetry-cron.sh

@@ -26,11 +26,11 @@ if crontab -l 2>/dev/null | grep -q "telemetry-collector"; then
 fi
 
 # Install cron entry: top of every hour
-(crontab -l 2>/dev/null; echo "0 * * * * $CRON_CMD >> /tmp/qgsd-telemetry.log 2>&1") | crontab -
+(crontab -l 2>/dev/null; echo "0 * * * * $CRON_CMD >> /tmp/nf-telemetry.log 2>&1") | crontab -
 
 echo "Telemetry cron installed."
 
 # Windows: use Task Scheduler. Create a Basic Task that runs:
-#   node C:\path\to\qgsd\bin\telemetry-collector.cjs
-# followed by: node C:\path\to\qgsd\bin\issue-classifier.cjs
+#   node C:\path\to\nforma\bin\telemetry-collector.cjs
+# followed by: node C:\path\to\nforma\bin\issue-classifier.cjs
 # Trigger: Daily, repeat every 1 hour indefinitely.

package/bin/stall-detector.cjs

@@ -0,0 +1,126 @@
+'use strict';
+// bin/stall-detector.cjs
+// Stall detection for quorum slots — INFORMATIONAL ONLY, never blocks.
+// Uses only node:fs, node:path, node:child_process. No external dependencies.
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+/**
+ * Detect stalled quorum slots from quorum-failures.json.
+ * @param {string} cwd - Project working directory.
+ * @param {object} config - Config object (needs stall_detection section).
+ * @returns {Array} Array of { slot, consecutiveTimeouts, lastSeen }.
+ */
+function detectStalledSlots(cwd, config) {
+  try {
+    let failuresPath;
+    try {
+      const planningPaths = require(path.join(__dirname, 'planning-paths.cjs'));
+      failuresPath = planningPaths.resolveWithFallback(cwd, 'quorum-failures');
+    } catch {
+      failuresPath = path.join(cwd, '.planning', 'quorum', 'failures.json');
+    }
+
+    if (!fs.existsSync(failuresPath)) return [];
+
+    const data = JSON.parse(fs.readFileSync(failuresPath, 'utf8'));
+    if (!Array.isArray(data) || data.length === 0) return [];
+
+    // Group records by slot
+    const bySlot = {};
+    for (const record of data) {
+      const slot = record.slot || record.slot_name || 'unknown';
+      if (!bySlot[slot]) bySlot[slot] = [];
+      bySlot[slot].push(record);
+    }
+
+    const results = [];
+    for (const [slot, records] of Object.entries(bySlot)) {
+      // Count consecutive TIMEOUT entries from the end
+      let consecutive = 0;
+      let lastSeen = null;
+      for (let i = records.length - 1; i >= 0; i--) {
+        const r = records[i];
+        const reason = (r.reason || r.type || '').toUpperCase();
+        if (reason === 'TIMEOUT') {
+          consecutive++;
+          if (!lastSeen) lastSeen = r.ts || r.timestamp || null;
+        } else {
+          break;
+        }
+      }
+      if (consecutive >= 1) {
+        results.push({ slot, consecutiveTimeouts: consecutive, lastSeen });
+      }
+    }
+
+    return results;
+  } catch {
+    return []; // Fail-open
+  }
+}
+
+/**
+ * Determine if stall should be escalated to user.
+ * @param {Array} stalledSlots - Output from detectStalledSlots.
+ * @param {object} config - Config object.
+ * @param {string} cwd - Project working directory.
+ * @returns {object} Escalation result.
+ */
+function shouldEscalate(stalledSlots, config, cwd) {
+  const stallCfg = (config && config.stall_detection) || {};
+  const threshold = stallCfg.consecutive_threshold || 2;
+
+  const filtered = stalledSlots.filter(s => s.consecutiveTimeouts >= threshold);
+
+  if (filtered.length === 0) {
+    return { escalate: false, reason: 'below_threshold', stalledSlots: [] };
+  }
+
+  // Check for recent commit activity
+  if (stallCfg.check_commits !== false) {
+    try {
+      const result = spawnSync('git', ['rev-list', '--count', 'HEAD', '--since=10 minutes ago'], {
+        cwd: cwd || process.cwd(),
+        timeout: 3000,
+        encoding: 'utf8',
+      });
+      const count = parseInt(result.stdout.trim(), 10);
+      if (count > 0) {
+        return { escalate: false, reason: 'commits_active', stalledSlots: filtered };
+      }
+    } catch {
+      // Fail-open: if git fails, proceed with escalation check
+    }
+  }
+
+  return { escalate: true, stalledSlots: filtered };
+}
+
+/**
+ * Format a structured stall report for additionalContext injection.
+ * @param {object} escalationResult - Output from shouldEscalate.
+ * @returns {object|null} Stall report or null.
+ */
+function formatStallReport(escalationResult) {
+  if (!escalationResult || !escalationResult.escalate) return null;
+
+  const slotNames = escalationResult.stalledSlots.map(s => s.slot).join(', ');
+
+  return {
+    type: 'stall_report',
+    ts: new Date().toISOString(),
+    stalled_slots: escalationResult.stalledSlots.map(s => ({
+      slot: s.slot,
+      consecutive_timeouts: s.consecutiveTimeouts,
+      last_seen: s.lastSeen,
+      recommendation: 'Check provider health: node bin/check-mcp-health.cjs',
+    })),
+    recommendation: 'Stalled slots detected with no new commits. Consider checking provider status or adjusting quorum composition.',
+    message: `STALL DETECTED: ${escalationResult.stalledSlots.length} slot(s) stalled (${slotNames}). Run \`node bin/check-mcp-health.cjs\` to diagnose.`,
+  };
+}
+
+module.exports = { detectStalledSlots, shouldEscalate, formatStallReport };

package/bin/state-candidates.cjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+'use strict';
+// bin/state-candidates.cjs
+// Mines conformance traces for unmodeled state candidates.
+// Identifies unmapped actions and suggests missing state transitions.
+//
+// Requirement: EVID-04
+
+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, 'state-candidates.json');
+
+const JSON_FLAG = process.argv.includes('--json');
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+function main() {
+  if (!fs.existsSync(EVIDENCE_DIR)) {
+    fs.mkdirSync(EVIDENCE_DIR, { recursive: true });
+  }
+
+  // Import mapToXStateEvent from validate-traces.cjs
+  const { mapToXStateEvent } = require('./validate-traces.cjs');
+
+  // 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 (_) {}
+  }
+
+  // Load vocabulary
+  const vocab = JSON.parse(fs.readFileSync(VOCAB_PATH, 'utf8'));
+  const vocabActions = new Set(Object.keys(vocab.vocabulary));
+
+  // 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;
+  });
+
+  // Identify unmapped actions: action is "undefined", not in vocabulary, or has no action field
+  const unmappedClusters = {};
+  let totalUnmapped = 0;
+
+  for (let i = 0; i < events.length; i++) {
+    const event = events[i];
+    const action = event.action || event.type || 'undefined';
+
+    // Check if this action is unmapped
+    const isUnmapped = !vocabActions.has(action);
+
+    if (isUnmapped) {
+      totalUnmapped++;
+
+      if (!unmappedClusters[action]) {
+        unmappedClusters[action] = {
+          action,
+          count: 0,
+          timestamps: [],
+          context_before: {},
+          context_after: {},
+        };
+      }
+
+      const cluster = unmappedClusters[action];
+      cluster.count++;
+
+      // Sample timestamps (first 5)
+      if (cluster.timestamps.length < 5) {
+        cluster.timestamps.push(event.ts || event.timestamp);
+      }
+
+      // Context: what actions appear before/after
+      if (i > 0) {
+        const prevAction = events[i - 1].action || events[i - 1].type || 'undefined';
+        cluster.context_before[prevAction] = (cluster.context_before[prevAction] || 0) + 1;
+      }
+      if (i < events.length - 1) {
+        const nextAction = events[i + 1].action || events[i + 1].type || 'undefined';
+        cluster.context_after[nextAction] = (cluster.context_after[nextAction] || 0) + 1;
+      }
+    }
+  }
+
+  // Build deduplicated candidates
+  const candidates = Object.values(unmappedClusters).map(cluster => {
+    // Suggest state variable based on context
+    const topBefore = Object.entries(cluster.context_before)
+      .sort((a, b) => b[1] - a[1])[0];
+    const topAfter = Object.entries(cluster.context_after)
+      .sort((a, b) => b[1] - a[1])[0];
+
+    let suggestedState = 'unknown';
+    let confidence = 'low';
+
+    if (topBefore && topBefore[0] === 'quorum_start') {
+      suggestedState = 'quorum_sub_state';
+      confidence = 'medium';
+    } else if (topAfter && topAfter[0] === 'quorum_complete') {
+      suggestedState = 'quorum_pre_completion';
+      confidence = 'medium';
+    } else if (cluster.action === 'undefined' || cluster.action === 'quorum_fallback_t1_required') {
+      suggestedState = 'instrumentation_gap';
+      confidence = 'high';
+    }
+
+    const allTs = cluster.timestamps.map(t => new Date(t).getTime()).filter(t => !isNaN(t));
+
+    return {
+      action: cluster.action,
+      count: cluster.count,
+      first_seen: allTs.length > 0 ? new Date(Math.min(...allTs)).toISOString() : null,
+      last_seen: allTs.length > 0 ? new Date(Math.max(...allTs)).toISOString() : null,
+      sample_timestamps: cluster.timestamps.slice(0, 5),
+      context_before: cluster.context_before,
+      context_after: cluster.context_after,
+      suggested_state: suggestedState,
+      confidence,
+    };
+  });
+
+  // Sort by count descending
+  candidates.sort((a, b) => b.count - a.count);
+
+  // Identify missing transitions (sequences of known actions not in XState)
+  const transitionPairs = {};
+  for (let i = 0; i < events.length - 1; i++) {
+    const fromAction = events[i].action || 'undefined';
+    const toAction = events[i + 1].action || 'undefined';
+    if (vocabActions.has(fromAction) && vocabActions.has(toAction)) {
+      const key = `${fromAction}→${toAction}`;
+      transitionPairs[key] = (transitionPairs[key] || 0) + 1;
+    }
+  }
+
+  // Try mapping through XState to find unmodeled transitions
+  const missingTransitions = [];
+  for (const [key, count] of Object.entries(transitionPairs)) {
+    const [fromAction, toAction] = key.split('→');
+    // Check if XState maps both actions
+    try {
+      const fromEvent = mapToXStateEvent({ action: fromAction });
+      const toEvent = mapToXStateEvent({ action: toAction });
+      if (!fromEvent || !toEvent) {
+        missingTransitions.push({
+          from_action: fromAction,
+          to_action: toAction,
+          count,
+          note: `XState mapping missing: from=${fromEvent || 'null'}, to=${toEvent || 'null'}`,
+        });
+      }
+    } catch (_) {}
+  }
+
+  // Build result
+  const result = {
+    schema_version: '1',
+    generated: new Date().toISOString(),
+    total_unmapped_events: totalUnmapped,
+    candidates,
+    missing_transitions: missingTransitions,
+    summary: `${totalUnmapped} unmapped events found. ` +
+             `${candidates.length} candidate(s): ` +
+             candidates.slice(0, 3).map(c => `${c.action} (${c.count}x)`).join(', ') +
+             (candidates.length > 3 ? `, +${candidates.length - 3} more` : '') + '. ' +
+             `${missingTransitions.length} potentially missing 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('State Candidates Generated');
+    console.log(`  Unmapped events: ${totalUnmapped}`);
+    console.log(`  Candidates: ${candidates.length}`);
+    for (const c of candidates.slice(0, 5)) {
+      console.log(`    ${c.action}: ${c.count}x (suggested: ${c.suggested_state}, confidence: ${c.confidence})`);
+    }
+    console.log(`  Missing transitions: ${missingTransitions.length}`);
+  }
+}
+
+// Export for testing
+module.exports = { main };
+
+if (require.main === module) {
+  main();
+}

package/bin/sync-baseline-requirements.cjs

@@ -82,7 +82,7 @@ function _syncFromBaseline(baseline, projectRoot) {
           phase: 'baseline',
           status: 'Pending',
           provenance: {
-            source_file: 'qgsd-baseline',
+            source_file: 'nf-baseline',
             milestone: 'baseline',
           },
         };

package/bin/telemetry-collector.cjs

@@ -4,7 +4,7 @@
 /**
  * telemetry-collector.cjs
  *
- * Pure disk I/O telemetry collector for QGSD.
+ * Pure disk I/O telemetry collector for nForma.
  * Reads existing log sources, aggregates stats, writes .planning/telemetry/report.json.
  *
  * Sources:

package/bin/test-changed.cjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Run only tests affected by changed source files.
+ *
+ * Usage:
+ *   node bin/test-changed.cjs                   # changes vs HEAD (staged + unstaged)
+ *   node bin/test-changed.cjs --since=main       # changes vs main branch
+ *   node bin/test-changed.cjs --since=HEAD~3     # changes in last 3 commits
+ */
+
+const { execFileSync, spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const ROOT = path.resolve(__dirname, '..');
+
+// ── Parse args ──────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+const sinceFlag = args.find(a => a.startsWith('--since='));
+const since = sinceFlag ? sinceFlag.split('=')[1] : null;
+const dryRun = args.includes('--dry-run');
+const verbose = args.includes('--verbose');
+
+// ── 1. Get changed files ───────────────────────────────────────────────
+function getChangedFiles() {
+  const files = new Set();
+
+  if (since) {
+    const committed = execFileSync('git', ['diff', '--name-only', `${since}...HEAD`], { cwd: ROOT, encoding: 'utf8' });
+    committed.trim().split('\n').filter(Boolean).forEach(f => files.add(f));
+  }
+
+  // Always include unstaged + staged changes
+  const unstaged = execFileSync('git', ['diff', '--name-only'], { cwd: ROOT, encoding: 'utf8' });
+  const staged = execFileSync('git', ['diff', '--name-only', '--cached'], { cwd: ROOT, encoding: 'utf8' });
+
+  unstaged.trim().split('\n').filter(Boolean).forEach(f => files.add(f));
+  staged.trim().split('\n').filter(Boolean).forEach(f => files.add(f));
+
+  return [...files];
+}
+
+// ── 2. Map source files → test files ────────────────────────────────────
+function mapToTestFiles(changedFiles) {
+  const testFiles = new Set();
+
+  for (const file of changedFiles) {
+    // Skip non-JS files
+    if (!/\.(cjs|mjs|js)$/.test(file)) continue;
+
+    // If the file IS a test file, include it directly
+    if (/\.test\.(cjs|mjs|js)$/.test(file)) {
+      const abs = path.resolve(ROOT, file);
+      if (fs.existsSync(abs)) testFiles.add(abs);
+      continue;
+    }
+
+    // Map source → test: foo.cjs → foo.test.cjs
+    const ext = path.extname(file);
+    const base = file.slice(0, -ext.length);
+    const testPath = `${base}.test${ext}`;
+    const abs = path.resolve(ROOT, testPath);
+    if (fs.existsSync(abs)) {
+      testFiles.add(abs);
+    }
+
+    // Also check .test.cjs variant for .js sources
+    if (ext !== '.cjs') {
+      const altPath = `${base}.test.cjs`;
+      const altAbs = path.resolve(ROOT, altPath);
+      if (fs.existsSync(altAbs)) testFiles.add(altAbs);
+    }
+  }
+
+  return [...testFiles].sort();
+}
+
+// ── 3. Run ──────────────────────────────────────────────────────────────
+const changed = getChangedFiles();
+if (verbose) {
+  console.log(`Changed files (since ${since || 'working tree'}):`);
+  changed.forEach(f => console.log(`  ${f}`));
+  console.log();
+}
+
+const tests = mapToTestFiles(changed);
+
+if (tests.length === 0) {
+  console.log('No affected test files found.');
+  process.exit(0);
+}
+
+console.log(`Running ${tests.length} affected test(s):`);
+tests.forEach(t => console.log(`  ${path.relative(ROOT, t)}`));
+console.log();
+
+if (dryRun) {
+  console.log('(dry-run mode — skipping execution)');
+  process.exit(0);
+}
+
+const child = spawn('node', ['--test', ...tests], {
+  cwd: ROOT,
+  stdio: 'inherit',
+});
+
+child.on('close', (code) => {
+  process.exit(code ?? 1);
+});