@nforma.ai/nforma 0.2.1 → 0.28.0

package/bin/manage-agents-core.cjs

@@ -4,7 +4,7 @@
  * Pure functions and shared helpers for manage-agents CLI and blessed TUI.
  * No interactive dependencies (inquirer, blessed). This module provides:
  * - File I/O helpers: readClaudeJson, writeClaudeJson, readProvidersJson, writeProvidersJson
- * - Configuration parsing: readQgsdJson, readCcrConfigSafe, getGlobalMcpServers
+ * - Configuration parsing: readNfJson, readCcrConfigSafe, getGlobalMcpServers
  * - Provider management: fetchProviderModels, probeProviderUrl, probeAllSlots, liveDashboard
  * - Pure transformation functions exported in _pure namespace
  *
@@ -23,9 +23,9 @@ const { updateAgents, getUpdateStatuses } = require('./update-agents.cjs');
 // File paths
 const CLAUDE_JSON_PATH = path.join(os.homedir(), '.claude.json');
 const CLAUDE_JSON_TMP = CLAUDE_JSON_PATH + '.tmp';
-const QGSD_JSON_PATH = path.join(os.homedir(), '.claude', 'qgsd.json');
+const NF_JSON_PATH = path.join(os.homedir(), '.claude', 'nf.json');
 const CCR_CONFIG_PATH = path.join(os.homedir(), '.claude-code-router', 'config.json');
-const UPDATE_LOG_PATH = path.join(os.homedir(), '.claude', 'qgsd-update.log');
+const UPDATE_LOG_PATH = path.join(os.homedir(), '.claude', 'nf-update.log');
 const PROVIDERS_JSON_PATH = path.join(__dirname, 'providers.json');
 const PROVIDERS_JSON_TMP = PROVIDERS_JSON_PATH + '.tmp';
 
@@ -145,7 +145,7 @@ function probeProviderUrl(baseUrl, apiKey) {
         headers: {
           'Authorization': apiKey ? `Bearer ${apiKey}` : '',
           'Accept': 'application/json',
-          'User-Agent': 'qgsd-manage-agents/1.0',
+          'User-Agent': 'nf-manage-agents/1.0',
         },
         timeout: 7000,
       },
@@ -185,17 +185,17 @@ function classifyProbeResult(probeResult) {
 }
 
 /**
- * Write key validity status to qgsd.json under agent_config[slotName].key_status.
+ * Write key validity status to nf.json under agent_config[slotName].key_status.
  */
 function writeKeyStatus(slotName, status, filePath) {
-  const qgsd = readQgsdJson(filePath);
-  if (!qgsd.agent_config) qgsd.agent_config = {};
-  if (!qgsd.agent_config[slotName]) qgsd.agent_config[slotName] = {};
-  qgsd.agent_config[slotName].key_status = {
+  const nfCfg = readNfJson(filePath);
+  if (!nf.agent_config) nf.agent_config = {};
+  if (!nf.agent_config[slotName]) nf.agent_config[slotName] = {};
+  nf.agent_config[slotName].key_status = {
     status,
     checkedAt: new Date().toISOString(),
   };
-  writeQgsdJson(qgsd, filePath);
+  writeNfJson(nfCfg, filePath);
 }
 
 /**
@@ -214,7 +214,7 @@ function formatTimestamp(ts) {
  */
 function buildDashboardLines(slots, mcpServers, healthMap, lastUpdated) {
   const lines = [];
-  lines.push('  QGSD Live Health Dashboard');
+  lines.push('  nForma Live Health Dashboard');
   lines.push('  ' + '\u2500'.repeat(60));
   lines.push('');
 
@@ -324,11 +324,11 @@ function writeProvidersJson(data) {
 }
 
 // ---------------------------------------------------------------------------
-// QGSD JSON helpers
+// nForma JSON helpers
 // ---------------------------------------------------------------------------
 
-function readQgsdJson(filePath) {
-  const p = filePath || QGSD_JSON_PATH;
+function readNfJson(filePath) {
+  const p = filePath || NF_JSON_PATH;
   if (!fs.existsSync(p)) return {};
   try {
     return JSON.parse(fs.readFileSync(p, 'utf8'));
@@ -337,19 +337,19 @@ function readQgsdJson(filePath) {
   }
 }
 
-function writeQgsdJson(data, filePath) {
-  const p = filePath || QGSD_JSON_PATH;
+function writeNfJson(data, filePath) {
+  const p = filePath || NF_JSON_PATH;
   const tmp = p + '.tmp';
   fs.writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf8');
   fs.renameSync(tmp, p);
 }
 
 function writeUpdatePolicy(slotName, policy, filePath) {
-  const qgsd = readQgsdJson(filePath);
-  if (!qgsd.agent_config) qgsd.agent_config = {};
-  if (!qgsd.agent_config[slotName]) qgsd.agent_config[slotName] = {};
-  qgsd.agent_config[slotName].update_policy = policy;
-  writeQgsdJson(qgsd, filePath);
+  const nfCfg = readNfJson(filePath);
+  if (!nf.agent_config) nf.agent_config = {};
+  if (!nf.agent_config[slotName]) nf.agent_config[slotName] = {};
+  nf.agent_config[slotName].update_policy = policy;
+  writeNfJson(nfCfg, filePath);
 }
 
 // ---------------------------------------------------------------------------
@@ -392,11 +392,11 @@ function applyKeyUpdate(updates, keytarAccount, newEnv, secretsLib) {
   if (!('apiKey' in updates)) return newEnv;
   if (updates.apiKey === '__REMOVE__') {
     delete newEnv.ANTHROPIC_API_KEY;
-    if (secretsLib) secretsLib.delete('qgsd', keytarAccount);
+    if (secretsLib) secretsLib.delete('nforma', keytarAccount);
   } else {
     delete newEnv.ANTHROPIC_API_KEY;
     if (secretsLib) {
-      secretsLib.set('qgsd', keytarAccount, updates.apiKey);
+      secretsLib.set('nforma', keytarAccount, updates.apiKey);
     } else {
       newEnv.ANTHROPIC_API_KEY = updates.apiKey;
     }
@@ -406,11 +406,11 @@ function applyKeyUpdate(updates, keytarAccount, newEnv, secretsLib) {
 
 async function applyCcrProviderUpdate(subAction, selectedKey, keyValue, secretsLib) {
   if (subAction === 'set') {
-    await secretsLib.set('qgsd', selectedKey, keyValue);
+    await secretsLib.set('nforma', selectedKey, keyValue);
     return { action: 'set', key: selectedKey };
   }
   if (subAction === 'remove') {
-    await secretsLib.delete('qgsd', selectedKey);
+    await secretsLib.delete('nforma', selectedKey);
     return { action: 'remove', key: selectedKey };
   }
   return null;
@@ -611,7 +611,7 @@ function validateImportSchema(parsed) {
 // ---------------------------------------------------------------------------
 
 /**
- * Probe a single slot and persist key_status to qgsd.json if the provider responded.
+ * Probe a single slot and persist key_status to nf.json if the provider responded.
  * Does NOT persist for timeout/network errors (statusCode is null) -- this is
  * a provider/network issue, not a key validity issue.
  * @param {string} slotName - MCP server slot name (e.g. 'claude-1')
@@ -642,7 +642,7 @@ async function probeAllSlots(mcpServers, slots, secretsLib) {
     let apiKey = env.ANTHROPIC_API_KEY || '';
     if (secretsLib) {
       try {
-        const k = await secretsLib.get('qgsd', account);
+        const k = await secretsLib.get('nforma', account);
         if (k) apiKey = k;
       } catch (_) {}
     }
@@ -654,9 +654,9 @@ async function probeAllSlots(mcpServers, slots, secretsLib) {
 
 async function runAutoUpdateCheck(getStatusesFn = getUpdateStatuses) {
   const check = async () => {
-    let qgsd;
-    try { qgsd = readQgsdJson(); } catch { return; }
-    const agentConfig = qgsd.agent_config || {};
+    let nfCfg;
+    try { nfCfg = readNfJson(); } catch { return; }
+    const agentConfig = nf.agent_config || {};
     const autoSlots = Object.keys(agentConfig).filter(
       (s) => agentConfig[s] && agentConfig[s].update_policy === 'auto'
     );
@@ -777,8 +777,8 @@ module.exports._pure = {
   buildAgentChoiceLabel,
   applyKeyUpdate,
   applyCcrProviderUpdate,
-  readQgsdJson,
-  writeQgsdJson,
+  readNfJson,
+  writeNfJson,
   slotToFamily,
   getWlDisplay,
   readCcrConfigSafe,

package/bin/migrate-to-slots.cjs

@@ -62,8 +62,8 @@ function migrateClaudeJson(claudeJsonPath, dryRun = false) {
   return { changed, renamed };
 }
 
-// tool_prefix migration map for qgsd.json
-const QGSD_PREFIX_MAP = {
+// tool_prefix migration map for nf.json
+const NF_PREFIX_MAP = {
   'mcp__codex-cli__':   'mcp__codex-cli-1__',
   'mcp__gemini-cli__':  'mcp__gemini-cli-1__',
   'mcp__opencode__':    'mcp__opencode-1__',
@@ -71,21 +71,21 @@ const QGSD_PREFIX_MAP = {
 };
 
 /**
- * Migrate ~/.claude/qgsd.json required_models tool_prefix values to slot-based prefixes.
- * @param {string} qgsdJsonPath - Absolute path to ~/.claude/qgsd.json
+ * Migrate ~/.claude/nf.json required_models tool_prefix values to slot-based prefixes.
+ * @param {string} nfJsonPath - Absolute path to ~/.claude/nf.json
  * @param {boolean} dryRun - If true, do not write changes
  * @returns {{ changed: number, patched: Array<{key: string, from: string, to: string}> }}
  */
-function migrateQgsdJson(qgsdJsonPath, dryRun = false) {
-  if (!fs.existsSync(qgsdJsonPath)) {
+function migrateNfJson(nfJsonPath, dryRun = false) {
+  if (!fs.existsSync(nfJsonPath)) {
     return { changed: 0, patched: [] };
   }
 
   let raw;
   try {
-    raw = JSON.parse(fs.readFileSync(qgsdJsonPath, 'utf8'));
+    raw = JSON.parse(fs.readFileSync(nfJsonPath, 'utf8'));
   } catch (e) {
-    throw new Error(`Failed to read ${qgsdJsonPath}: ${e.message}`);
+    throw new Error(`Failed to read ${nfJsonPath}: ${e.message}`);
   }
 
   const requiredModels = raw.required_models;
@@ -98,7 +98,7 @@ function migrateQgsdJson(qgsdJsonPath, dryRun = false) {
 
   for (const [modelKey, modelDef] of Object.entries(requiredModels)) {
     if (modelDef && typeof modelDef.tool_prefix === 'string') {
-      const newPrefix = QGSD_PREFIX_MAP[modelDef.tool_prefix];
+      const newPrefix = NF_PREFIX_MAP[modelDef.tool_prefix];
       if (newPrefix) {
         patched.push({ key: modelKey, from: modelDef.tool_prefix, to: newPrefix });
         modelDef.tool_prefix = newPrefix;
@@ -108,21 +108,21 @@ function migrateQgsdJson(qgsdJsonPath, dryRun = false) {
   }
 
   if (changed > 0 && !dryRun) {
-    fs.writeFileSync(qgsdJsonPath, JSON.stringify(raw, null, 2) + '\n', 'utf8');
+    fs.writeFileSync(nfJsonPath, JSON.stringify(raw, null, 2) + '\n', 'utf8');
   }
 
   return { changed, patched };
 }
 
 /**
- * Populate quorum_active in ~/.claude/qgsd.json from current mcpServers in ~/.claude.json.
+ * Populate quorum_active in ~/.claude/nf.json from current mcpServers in ~/.claude.json.
  * Idempotent: skips if quorum_active already present and non-empty.
- * @param {string} qgsdJsonPath - Absolute path to ~/.claude/qgsd.json
+ * @param {string} nfJsonPath - Absolute path to ~/.claude/nf.json
  * @param {string} claudeJsonPath - Absolute path to ~/.claude.json
  * @param {boolean} dryRun - If true, do not write changes
  * @returns {{ skipped: boolean, slots: string[] }}
  */
-function populateActiveSlots(qgsdJsonPath, claudeJsonPath, dryRun = false) {
+function populateActiveSlots(nfJsonPath, claudeJsonPath, dryRun = false) {
   // Read current slot names from ~/.claude.json
   let slotNames = [];
   try {
@@ -134,25 +134,25 @@ function populateActiveSlots(qgsdJsonPath, claudeJsonPath, dryRun = false) {
     return { skipped: true, slots: [] };
   }
 
-  // Read or create qgsd.json
-  let qgsdConfig = {};
+  // Read or create nf.json
+  let nfConfig = {};
   try {
-    qgsdConfig = JSON.parse(fs.readFileSync(qgsdJsonPath, 'utf8'));
+    nfConfig = JSON.parse(fs.readFileSync(nfJsonPath, 'utf8'));
   } catch (e) {
-    if (e.code !== 'ENOENT') throw new Error(`Failed to read ${qgsdJsonPath}: ${e.message}`);
-    // qgsd.json absent — create minimal object
+    if (e.code !== 'ENOENT') throw new Error(`Failed to read ${nfJsonPath}: ${e.message}`);
+    // nf.json absent — create minimal object
   }
 
   // Idempotent: skip if already set and non-empty
-  if (Array.isArray(qgsdConfig.quorum_active) && qgsdConfig.quorum_active.length > 0) {
-    return { skipped: true, slots: qgsdConfig.quorum_active };
+  if (Array.isArray(nfConfig.quorum_active) && nfConfig.quorum_active.length > 0) {
+    return { skipped: true, slots: nfConfig.quorum_active };
   }
 
   // Populate and write
-  qgsdConfig.quorum_active = slotNames;
+  nfConfig.quorum_active = slotNames;
   if (!dryRun) {
-    fs.mkdirSync(path.dirname(qgsdJsonPath), { recursive: true });
-    fs.writeFileSync(qgsdJsonPath, JSON.stringify(qgsdConfig, null, 2) + '\n', 'utf8');
+    fs.mkdirSync(path.dirname(nfJsonPath), { recursive: true });
+    fs.writeFileSync(nfJsonPath, JSON.stringify(nfConfig, null, 2) + '\n', 'utf8');
   }
   return { skipped: false, slots: slotNames };
 }
@@ -161,7 +161,7 @@ function populateActiveSlots(qgsdJsonPath, claudeJsonPath, dryRun = false) {
 if (require.main === module) {
   const dryRun = process.argv.includes('--dry-run');
   const claudeJsonPath = path.join(os.homedir(), '.claude.json');
-  const qgsdJsonPath = path.join(os.homedir(), '.claude', 'qgsd.json');
+  const nfJsonPath = path.join(os.homedir(), '.claude', 'nf.json');
 
   let r1, r2;
   try {
@@ -172,15 +172,15 @@ if (require.main === module) {
   }
 
   try {
-    r2 = migrateQgsdJson(qgsdJsonPath, dryRun);
+    r2 = migrateNfJson(nfJsonPath, dryRun);
   } catch (e) {
-    console.error(`Error migrating ~/.claude/qgsd.json: ${e.message}`);
+    console.error(`Error migrating ~/.claude/nf.json: ${e.message}`);
     process.exit(1);
   }
 
   let r3;
   try {
-    r3 = populateActiveSlots(qgsdJsonPath, claudeJsonPath, dryRun);
+    r3 = populateActiveSlots(nfJsonPath, claudeJsonPath, dryRun);
     if (!r3.skipped) {
       console.log(`[migrate-to-slots] quorum_active populated: ${r3.slots.join(', ')}`);
     } else {
@@ -200,7 +200,7 @@ if (require.main === module) {
       console.log(`  mcpServers: ${from} → ${to}`);
     }
     for (const { key, from, to } of r2.patched) {
-      console.log(`  qgsd.json required_models.${key}.tool_prefix: ${from} → ${to}`);
+      console.log(`  nf.json required_models.${key}.tool_prefix: ${from} → ${to}`);
     }
   } else {
     if (r1.changed > 0) {
@@ -210,7 +210,7 @@ if (require.main === module) {
       }
     }
     if (r2.changed > 0) {
-      console.log(`Patched ${r2.changed} qgsd.json tool_prefix values`);
+      console.log(`Patched ${r2.changed} nf.json tool_prefix values`);
       for (const { key, from, to } of r2.patched) {
         console.log(`  required_models.${key}.tool_prefix: ${from} → ${to}`);
       }
@@ -221,24 +221,24 @@ if (require.main === module) {
 }
 
 /**
- * Append a single slot name to quorum_active in qgsd.json if not already present.
+ * Append a single slot name to quorum_active in nf.json if not already present.
  * Idempotent: no-op if slot is already in the array.
  * @param {string} slotName - e.g. "copilot-2"
- * @param {string} qgsdJsonPath - path to ~/.claude/qgsd.json
+ * @param {string} nfJsonPath - path to ~/.claude/nf.json
  * @param {boolean} dryRun - if true, report but do not write
  * @returns {{ added: boolean, slot: string, skipped: boolean }}
  */
-function addSlotToQuorumActive(slotName, qgsdJsonPath, dryRun = false) {
-  let qgsdConfig = {};
+function addSlotToQuorumActive(slotName, nfJsonPath, dryRun = false) {
+  let nfConfig = {};
   try {
-    if (fs.existsSync(qgsdJsonPath)) {
-      qgsdConfig = JSON.parse(fs.readFileSync(qgsdJsonPath, 'utf8'));
+    if (fs.existsSync(nfJsonPath)) {
+      nfConfig = JSON.parse(fs.readFileSync(nfJsonPath, 'utf8'));
     }
   } catch (e) {
     return { added: false, slot: slotName, skipped: true, error: e.message };
   }
 
-  const active = Array.isArray(qgsdConfig.quorum_active) ? qgsdConfig.quorum_active : [];
+  const active = Array.isArray(nfConfig.quorum_active) ? nfConfig.quorum_active : [];
   if (active.includes(slotName)) {
     return { added: false, slot: slotName, skipped: true, reason: 'already present' };
   }
@@ -247,9 +247,9 @@ function addSlotToQuorumActive(slotName, qgsdJsonPath, dryRun = false) {
     return { added: true, slot: slotName, skipped: false, dryRun: true };
   }
 
-  qgsdConfig.quorum_active = [...active, slotName];
-  fs.writeFileSync(qgsdJsonPath, JSON.stringify(qgsdConfig, null, 2) + '\n');
+  nfConfig.quorum_active = [...active, slotName];
+  fs.writeFileSync(nfJsonPath, JSON.stringify(nfConfig, null, 2) + '\n');
   return { added: true, slot: slotName, skipped: false };
 }
 
-module.exports = { migrateClaudeJson, migrateQgsdJson, populateActiveSlots, addSlotToQuorumActive, SLOT_MIGRATION_MAP };
+module.exports = { migrateClaudeJson, migrateNfJson, populateActiveSlots, addSlotToQuorumActive, SLOT_MIGRATION_MAP };

package/bin/mismatch-register.cjs

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+'use strict';
+// bin/mismatch-register.cjs
+// Builds a JSONL mismatch register tracking L2-model vs L1-trace disagreements.
+// Each line is a standalone JSON object with resolution tracking.
+// Requirements: SEM-02
+
+const fs   = require('fs');
+const path = require('path');
+
+const PROJECT_ROOT = path.resolve(__dirname, '..');
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Classify a conformance event as a methodology skip.
+ * H1 methodology: mid-session events (phase !== 'IDLE' AND action !== 'quorum_start')
+ * cannot be validated with a fresh actor from IDLE, so they are methodology skips,
+ * NOT mismatches. Fresh actors always start in IDLE, so mid-session events would
+ * produce false mismatches without this compensation.
+ */
+function isMethodologySkip(event) {
+  if (!event) return false;
+  // quorum_start always starts from IDLE -- valid for fresh-actor replay
+  if (event.action === 'quorum_start') return false;
+  // Events with non-IDLE phase are mid-session
+  if (event.phase && event.phase !== 'IDLE') return true;
+  return false;
+}
+
+/**
+ * Generate a mismatch entry from a conformance event comparison.
+ */
+function buildMismatchEntry(id, event, eventIndex, expectedState, actualState, divergenceType, resolution, notes, classification) {
+  return {
+    id: 'MISMATCH-' + String(id).padStart(3, '0'),
+    timestamp: event.ts || new Date().toISOString(),
+    l2_source: 'nf-workflow.machine.ts',
+    l1_trace_ref: {
+      event_index: eventIndex,
+      session: event.session_id || event.round_id || 'standalone',
+    },
+    expected_state: expectedState,
+    actual_state: actualState,
+    divergence_type: divergenceType,
+    resolution: resolution || 'open',
+    resolution_notes: notes || null,
+    classification: classification || null,
+  };
+}
+
+/**
+ * Process conformance events and build mismatch entries.
+ * Returns { entries, summary }.
+ */
+function buildMismatchRegister(conformanceEvents, vocabulary, divergences) {
+  // Lazy-load validate-traces for mapToXStateEvent
+  const { mapToXStateEvent } = require(path.join(__dirname, 'validate-traces.cjs'));
+
+  // Machine path resolution (same pattern as 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);
+
+  const entries = [];
+  let mismatchCounter = 0;
+  const stats = { total_events: 0, mapped: 0, unmapped: 0, methodology_skip: 0, state_mismatch: 0 };
+
+  // Process conformance events
+  for (let i = 0; i < conformanceEvents.length; i++) {
+    const event = conformanceEvents[i];
+    stats.total_events++;
+
+    // Map to XState event
+    const xstateEvent = mapToXStateEvent(event);
+    if (!xstateEvent) {
+      stats.unmapped++;
+      continue; // instrumentation gap, not a mismatch
+    }
+    stats.mapped++;
+
+    // H1 methodology skip: mid-session events cannot be validated with fresh actor
+    if (isMethodologySkip(event)) {
+      stats.methodology_skip++;
+      continue;
+    }
+
+    // Fresh actor per event for isolation
+    const actor = createActor(nfWorkflowMachine);
+    actor.start();
+    actor.send(xstateEvent);
+    const snapshot = actor.getSnapshot();
+    actor.stop();
+
+    // Determine expected state based on event type
+    let expectedState = null;
+    if (event.action === 'quorum_start') expectedState = 'COLLECTING_VOTES';
+    else if (event.action === 'circuit_break') expectedState = 'IDLE';
+    else if (event.action === 'deliberation_round') expectedState = 'DELIBERATING';
+    else if (event.outcome === 'APPROVE' || event.outcome === 'BLOCK') expectedState = 'DECIDED';
+
+    if (expectedState === null) continue; // cannot determine -- skip
+
+    // Get actual state as string
+    const actualStateValue = typeof snapshot.value === 'string'
+      ? snapshot.value
+      : JSON.stringify(snapshot.value);
+
+    // Compare states
+    if (!snapshot.matches(expectedState)) {
+      mismatchCounter++;
+      stats.state_mismatch++;
+      entries.push(buildMismatchEntry(
+        mismatchCounter, event, i,
+        expectedState, actualStateValue,
+        'state_mismatch', 'open', null, null
+      ));
+    }
+  }
+
+  // Incorporate existing .divergences.json entries
+  if (Array.isArray(divergences)) {
+    for (const div of divergences) {
+      mismatchCounter++;
+      const divEvent = div.event || {};
+
+      // Check if this divergence matches the H1 methodology skip pattern
+      const isH1 = isMethodologySkip(divEvent);
+      const resolution = isH1 ? 'explained' : 'open';
+      const notes = isH1 ? 'H1 methodology limitation: mid-session event evaluated with fresh actor from IDLE' : null;
+
+      entries.push(buildMismatchEntry(
+        mismatchCounter, divEvent, divEvent._lineIndex || 0,
+        div.expectedState || 'unknown',
+        typeof div.actualState === 'string' ? div.actualState : JSON.stringify(div.actualState || 'unknown'),
+        div.divergenceType || 'state_mismatch',
+        resolution, notes,
+        isH1 ? 'methodology_limitation' : null
+      ));
+    }
+  }
+
+  const byResolution = { open: 0, explained: 0, bug: 0 };
+  const byDivergenceType = {};
+  for (const e of entries) {
+    byResolution[e.resolution] = (byResolution[e.resolution] || 0) + 1;
+    byDivergenceType[e.divergence_type] = (byDivergenceType[e.divergence_type] || 0) + 1;
+  }
+
+  return {
+    entries,
+    summary: {
+      total_mismatches: entries.length,
+      by_resolution: byResolution,
+      by_divergence_type: byDivergenceType,
+      stats,
+    },
+  };
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+
+if (require.main === module) {
+  const jsonFlag = process.argv.includes('--json');
+
+  // Read conformance events
+  const pp = require(path.join(__dirname, 'planning-paths.cjs'));
+  const logPath = pp.resolveWithFallback(PROJECT_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 malformed lines */ }
+    }
+  }
+
+  // Read event vocabulary
+  const vocabPath = path.join(PROJECT_ROOT, '.planning', 'formal', 'evidence', 'event-vocabulary.json');
+  let vocabulary = {};
+  if (fs.existsSync(vocabPath)) {
+    try { vocabulary = JSON.parse(fs.readFileSync(vocabPath, 'utf8')); } catch (_) { /* fail-open */ }
+  }
+
+  // Read existing divergences
+  const divergencesPath = path.join(PROJECT_ROOT, '.planning', 'formal', '.divergences.json');
+  let divergences = [];
+  if (fs.existsSync(divergencesPath)) {
+    try { divergences = JSON.parse(fs.readFileSync(divergencesPath, 'utf8')); } catch (_) { /* fail-open */ }
+  }
+
+  const result = buildMismatchRegister(conformanceEvents, vocabulary, divergences);
+
+  // Write JSONL output (one JSON object per line)
+  const outputPath = path.join(PROJECT_ROOT, '.planning', 'formal', 'semantics', 'mismatch-register.jsonl');
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  const jsonlContent = result.entries.map(e => JSON.stringify(e)).join('\n');
+  fs.writeFileSync(outputPath, jsonlContent + (jsonlContent.length > 0 ? '\n' : ''), 'utf8');
+
+  // Output summary
+  if (jsonFlag) {
+    process.stdout.write(JSON.stringify(result.summary, null, 2) + '\n');
+  } else {
+    process.stdout.write('[mismatch-register] Total mismatches: ' + result.summary.total_mismatches + '\n');
+    process.stdout.write('[mismatch-register] By resolution: ' + JSON.stringify(result.summary.by_resolution) + '\n');
+    process.stdout.write('[mismatch-register] By type: ' + JSON.stringify(result.summary.by_divergence_type) + '\n');
+    process.stdout.write('[mismatch-register] Stats: ' + JSON.stringify(result.summary.stats) + '\n');
+    process.stdout.write('[mismatch-register] Output: ' + outputPath + '\n');
+  }
+
+  process.exit(0);
+}
+
+module.exports = { buildMismatchRegister, buildMismatchEntry, isMethodologySkip };