@nforma.ai/nforma 0.2.1

package/bin/attribute-trace-divergence.cjs

@@ -0,0 +1,150 @@
+'use strict';
+// bin/attribute-trace-divergence.cjs
+// Root-cause attribution tool for XState conformance divergences.
+// Reads TTrace records from .planning/formal/.divergences.json (produced by validate-traces.cjs).
+// Classifies each divergence as spec-bug or impl-bug with confidence scores.
+// DIAG-02: outputs "fix XState guard X" or "fix hook implementation Y at line Z".
+//
+// CLI usage:
+//   node bin/attribute-trace-divergence.cjs [--input <path>] [--batch-size <N>] [--output-json]
+//
+// --input       path to TTrace JSON file (default: .planning/formal/.divergences.json)
+// --batch-size  analyze first N divergences (default: 10)
+// --output-json emit structured JSON to stdout in addition to plain text summary
+
+const fs   = require('fs');
+const path = require('path');
+
+// ── Attribution heuristics ────────────────────────────────────────────────────
+
+// classifyDivergence: given a TTrace record, classify the root cause.
+// Returns { specBugConfidence, implBugConfidence, failingGuard, recommendation, evidence }.
+function classifyDivergence(ttrace) {
+  const { event, actualState, expectedState, guardEvaluations, divergenceType } = ttrace;
+  let specBugConfidence = 50;  // start at 50/50
+  let implBugConfidence = 50;
+  let failingGuard = null;
+  const evidence = [];
+
+  // Evidence 1: Are there guard evaluations where a guard failed?
+  const failedGuards = (guardEvaluations || []).filter(g => !g.passed);
+  if (failedGuards.length > 0) {
+    failingGuard = failedGuards[0].guardName;
+    evidence.push(`Guard "${failingGuard}" evaluated to false`);
+    // Guard failure → could be spec-bug (wrong guard logic) or impl-bug (context not set)
+    // Check if context values look uninitialized (null, 0, undefined for numeric fields)
+    const ctx = failedGuards[0].context || {};
+    const suspiciousFields = Object.entries(ctx)
+      .filter(([k, v]) => (v === null || v === undefined || v === 0) &&
+        (k.includes('Count') || k.includes('Available') || k.includes('Polled')))
+      .map(([k]) => k);
+    if (suspiciousFields.length > 0) {
+      implBugConfidence += 30;
+      specBugConfidence -= 30;
+      evidence.push(`Context fields may not be initialized: ${suspiciousFields.join(', ')}`);
+    } else {
+      // Guard failed but context looks populated → more likely spec-bug
+      specBugConfidence += 20;
+      implBugConfidence -= 20;
+      evidence.push(`Context appears populated — guard logic may be incorrect`);
+    }
+  }
+
+  // Evidence 2: unmappable_action — always impl-bug (hook sent wrong event type)
+  if (divergenceType === 'unmappable_action') {
+    implBugConfidence = 90;
+    specBugConfidence = 10;
+    evidence.push('Action type has no XState mapping — hook emitted unknown event');
+  }
+
+  // Evidence 3: state stayed same when it should have changed (machine ignored event)
+  if (actualState === expectedState) {
+    // Validation passed — not a divergence; shouldn't be in TTrace
+    implBugConfidence = 0;
+    specBugConfidence = 0;
+  }
+
+  // Clamp 0-100
+  specBugConfidence = Math.max(0, Math.min(100, specBugConfidence));
+  implBugConfidence = Math.max(0, Math.min(100, implBugConfidence));
+
+  const recommendation = implBugConfidence >= specBugConfidence
+    ? `impl-bug: check hook implementation — context field initialization or event payload mapping`
+    : `spec-bug: review XState guard "${failingGuard || 'unknown'}" in qgsd-workflow.machine.ts`;
+
+  return { specBugConfidence, implBugConfidence, failingGuard, recommendation, evidence };
+}
+
+// analyzeTrace: full attribution for one TTrace record.
+// Returns structured analysis object.
+function analyzeTrace(ttrace, machine, walker) {
+  const { event, actualState, expectedState, divergenceType } = ttrace;
+  const classification = classifyDivergence(ttrace);
+  return {
+    event_action:         event?.action || 'unknown',
+    actual_state:         actualState,
+    expected_state:       expectedState,
+    divergence_type:      divergenceType,
+    failing_guard:        classification.failingGuard,
+    spec_bug_confidence:  classification.specBugConfidence,
+    impl_bug_confidence:  classification.implBugConfidence,
+    recommendation:       classification.recommendation,
+    evidence:             classification.evidence,
+  };
+}
+
+module.exports = { classifyDivergence, analyzeTrace };
+
+if (require.main === module) {
+  // Parse args
+  const args       = process.argv.slice(2);
+  const inputIdx   = args.indexOf('--input');
+  const batchIdx   = args.indexOf('--batch-size');
+  const outputJson = args.includes('--output-json');
+  const inputPath  = inputIdx >= 0
+    ? args[inputIdx + 1]
+    : path.join(process.cwd(), '.planning', 'formal', '.divergences.json');
+  const batchSize  = batchIdx >= 0 ? (parseInt(args[batchIdx + 1], 10) || 10) : 10;
+
+  if (!fs.existsSync(inputPath)) {
+    process.stderr.write('[attribute-trace-divergence] No divergences file at: ' + inputPath + '\n');
+    process.stderr.write('  Run: node bin/validate-traces.cjs to generate .planning/formal/.divergences.json\n');
+    process.exit(0);
+  }
+
+  let ttraces;
+  try {
+    ttraces = JSON.parse(fs.readFileSync(inputPath, 'utf8'));
+  } catch (e) {
+    process.stderr.write('[attribute-trace-divergence] Failed to parse: ' + inputPath + ' — ' + e.message + '\n');
+    process.exit(1);
+  }
+
+  if (!Array.isArray(ttraces) || ttraces.length === 0) {
+    process.stdout.write('[attribute-trace-divergence] No divergences to analyze\n');
+    process.exit(0);
+  }
+
+  const batch   = ttraces.slice(0, batchSize);
+  const results = batch.map(t => analyzeTrace(t, null, null));
+
+  // Plain text summary
+  process.stdout.write('[attribute-trace-divergence] Analyzed ' + results.length + ' of ' + ttraces.length + ' divergences\n\n');
+  for (const r of results) {
+    process.stdout.write('Action: ' + r.event_action + ' | ' + r.actual_state + ' → expected ' + r.expected_state + '\n');
+    process.stdout.write('  Guard:       ' + (r.failing_guard || 'n/a') + '\n');
+    process.stdout.write('  Spec-bug:    ' + r.spec_bug_confidence + '%  |  Impl-bug: ' + r.impl_bug_confidence + '%\n');
+    process.stdout.write('  Recommend:   ' + r.recommendation + '\n');
+    if (r.evidence.length > 0) {
+      process.stdout.write('  Evidence:    ' + r.evidence.join('; ') + '\n');
+    }
+    process.stdout.write('\n');
+  }
+
+  if (outputJson) {
+    process.stdout.write(JSON.stringify(results, null, 2) + '\n');
+  }
+
+  // Fail-open exit: non-zero only if attribution itself errored, not just because divergences exist
+  process.exit(0);
+}

package/bin/auth-drivers/gh-cli.cjs

@@ -0,0 +1,93 @@
+'use strict';
+
+/**
+ * auth-drivers/gh-cli.cjs — GitHub CLI keychain driver
+ *
+ * Accounts live in the macOS/system keychain managed by gh.
+ * There is no credential file to copy — all operations delegate to gh.
+ * This is the single source of truth for gh auth status parsing,
+ * replacing duplicated regex in qgsd.cjs and gh-account-rotate.cjs.
+ *
+ * Applies to: copilot-1
+ *
+ * Required providers.json fields:
+ *   auth.login  — add command (e.g. ["gh", "auth", "login"])
+ */
+
+const { spawnSync } = require('child_process');
+
+/**
+ * parseGhStatus() → { accounts: string[], active: string | null }
+ * Single authoritative parser for `gh auth status` output.
+ * gh writes to stderr; we merge both streams.
+ */
+function parseGhStatus() {
+  const r   = spawnSync('gh', ['auth', 'status'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  const out = (r.stdout || '') + (r.stderr || '');
+
+  const accounts = [];
+  let active = null;
+  let last   = null;
+
+  for (const line of out.split('\n')) {
+    const m = line.match(/account (\S+)/);
+    if (m) last = m[1];
+    if (/Logged in to github\.com account/.test(line) && last && !accounts.includes(last)) {
+      accounts.push(last);
+    }
+    if (/Active account:\s*true/.test(line) && last) {
+      active = last;
+    }
+  }
+
+  return { accounts, active };
+}
+
+/**
+ * list(provider) → [{ name, active }]
+ */
+function list(_provider) {
+  const { accounts, active } = parseGhStatus();
+  return accounts.map(name => ({ name, active: name === active }));
+}
+
+/**
+ * switch(provider, name) — calls gh auth switch (non-interactive, stays in TUI).
+ */
+function switchAccount(_provider, name) {
+  const r = spawnSync('gh', ['auth', 'switch', '--user', name, '--hostname', 'github.com'], {
+    encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (r.status !== 0) {
+    throw new Error((r.stderr || r.stdout || 'gh auth switch failed').trim());
+  }
+}
+
+/**
+ * addCredentialFile() → null
+ * gh stores credentials in the OS keychain — no file to poll.
+ * promptLoginExternal will wait for manual [Enter] confirmation.
+ */
+function addCredentialFile(_provider) {
+  return null;
+}
+
+/**
+ * extractAccountName() → null
+ * Cannot auto-detect from a file. TUI will not prompt for a name either —
+ * gh manages account identity internally; the new account will appear in
+ * the next `gh auth status` call.
+ */
+function extractAccountName(_provider) {
+  return null;
+}
+
+/**
+ * add() — no-op: gh auth login handles everything internally.
+ * The account appears automatically in parseGhStatus() after login.
+ */
+async function add(_provider, _name) {
+  // gh manages account storage; nothing to capture.
+}
+
+module.exports = { list, switch: switchAccount, addCredentialFile, extractAccountName, add, parseGhStatus };

package/bin/auth-drivers/index.cjs

@@ -0,0 +1,46 @@
+'use strict';
+
+/**
+ * auth-drivers/index.cjs — driver loader
+ *
+ * loadDriver(type) resolves an auth driver by name, validates the 4-method
+ * interface contract, and returns the driver module.
+ *
+ * Driver interface (all methods required):
+ *   list(provider)              → [{ name: string, active: boolean }]
+ *   switch(provider, name)      → void  (throws on error)
+ *   addCredentialFile(provider) → string | null  (file to poll for mtime, null = keychain)
+ *   extractAccountName(provider)→ string | null  (auto-detect after add, null = must prompt)
+ */
+
+const path = require('path');
+
+const DRIVER_DIR = __dirname;
+
+const REQUIRED_METHODS = ['list', 'switch', 'addCredentialFile', 'extractAccountName'];
+
+function loadDriver(type) {
+  if (!type) return null;
+
+  const driverPath = path.join(DRIVER_DIR, type + '.cjs');
+  let driver;
+  try {
+    driver = require(driverPath);
+  } catch (err) {
+    if (err.code === 'MODULE_NOT_FOUND') {
+      throw new Error(`Unknown auth driver "${type}" — expected ${driverPath}`);
+    }
+    throw err;
+  }
+
+  // Validate interface contract
+  for (const method of REQUIRED_METHODS) {
+    if (typeof driver[method] !== 'function') {
+      throw new Error(`Auth driver "${type}" missing required method: ${method}()`);
+    }
+  }
+
+  return driver;
+}
+
+module.exports = { loadDriver };

package/bin/auth-drivers/pool.cjs

@@ -0,0 +1,67 @@
+'use strict';
+
+/**
+ * auth-drivers/pool.cjs — file-copy credential pool driver
+ *
+ * For providers that store OAuth credentials as a JSON file that can be
+ * copied between a pool directory and an active location.
+ * Backed by account-manager.cjs (TLA+-formalized FSM).
+ *
+ * Applies to: gemini-1, gemini-2, codex-1, codex-2
+ *
+ * Required providers.json fields:
+ *   oauth_rotation.creds_dir    — pool directory (~/.gemini/accounts)
+ *   oauth_rotation.active_file  — live credential file (~/.gemini/oauth_creds.json)
+ *   auth.login                  — add command (e.g. ["gemini", "auth", "login"])
+ */
+
+const acm = require('../account-manager.cjs');
+
+/**
+ * list(provider) → [{ name, active }]
+ * Reads the pool directory and the .qgsd-active pointer — no subprocess.
+ */
+function list(provider) {
+  const credsDir = acm.getCredsDir(provider);
+  const pool     = acm.listPool(credsDir);
+  const active   = acm.readActivePtr(credsDir);
+  return pool.map(name => ({ name, active: name === active }));
+}
+
+/**
+ * switch(provider, name) — copies pool entry to active_file, updates pointer.
+ * Driven by the FSM; throws on invalid transition or I/O error.
+ */
+function switchAccount(provider, name) {
+  const fsm = new acm.AccountManagerFSM();
+  acm.cmdSwitch(fsm, provider, name);
+}
+
+/**
+ * addCredentialFile(provider) → string
+ * Returns the active_file path — promptLoginExternal polls its mtime to
+ * auto-detect when sign-in completes.
+ */
+function addCredentialFile(provider) {
+  return acm.getActiveFile(provider);
+}
+
+/**
+ * extractAccountName(provider) → string | null
+ * For Gemini: decodes the id_token JWT to get the Google email (no network).
+ * For Codex (no id_token): returns null → TUI prompts for a name.
+ */
+function extractAccountName(provider) {
+  return acm.extractEmailFromCreds(acm.getActiveFile(provider));
+}
+
+/**
+ * add(provider, name) — captures current active_file into pool under `name`.
+ * Called after promptLoginExternal resolves (credential file already written by CLI).
+ */
+async function add(provider, name) {
+  const fsm = new acm.AccountManagerFSM();
+  await acm.cmdAdd(fsm, provider, name, false);
+}
+
+module.exports = { list, switch: switchAccount, addCredentialFile, extractAccountName, add };

package/bin/auth-drivers/simple.cjs

@@ -0,0 +1,95 @@
+'use strict';
+
+/**
+ * auth-drivers/simple.cjs — login-only driver (no account pool)
+ *
+ * For providers where there is a single account / session and no concept
+ * of switching between multiple credentials. The only operation is "add"
+ * (i.e., log in), which opens a terminal window running auth.login.
+ *
+ * Applies to: codex-1/2, opencode-1, and any future CLIs before pool support is added.
+ *
+ * Required providers.json fields:
+ *   auth.login                     — login command (e.g. ["opencode", "auth"])
+ *   oauth_rotation.active_file     — optional; if present, JWT email is decoded from it
+ */
+
+const os = require('os');
+const fs = require('fs');
+
+/**
+ * list() → []
+ * No pool — there are no accounts to enumerate.
+ */
+function list(_provider) {
+  return [];
+}
+
+/**
+ * switch() — not supported; simple providers have no multi-account concept.
+ */
+function switchAccount(_provider, _name) {
+  throw new Error('Account switching is not supported for this provider.');
+}
+
+/**
+ * addCredentialFile() → null
+ * No known credential file to poll; promptLoginExternal waits for manual [Enter].
+ */
+function addCredentialFile(_provider) {
+  return null;
+}
+
+/**
+ * extractAccountName(provider) → string | null
+ *
+ * Two strategies, tried in order:
+ *
+ * 1. identity_detect (regex on a plain text/YAML/JSON file)
+ *    Configured via providers.json identity_detect.{file, pattern}.
+ *    Used for providers whose identity lives in a third-party config file,
+ *    e.g. OpenCode delegates to gh: file=~/.config/gh/hosts.yml.
+ *
+ * 2. JWT decode from oauth_rotation.active_file
+ *    Reads the credential JSON and decodes the id_token claim (or
+ *    tokens.id_token for Codex-style nesting) to extract the email.
+ *
+ * Returns null if no strategy succeeds or on any I/O / parse error.
+ */
+function extractAccountName(provider) {
+  // Strategy 1 — identity_detect (data-driven regex on a config file)
+  try {
+    const det = provider.identity_detect;
+    if (det?.file && det?.pattern) {
+      const filePath = det.file.replace(/^~/, os.homedir());
+      if (fs.existsSync(filePath)) {
+        const content = fs.readFileSync(filePath, 'utf8');
+        const m = content.match(new RegExp(det.pattern, 'm'));
+        if (m) return m[1];
+      }
+    }
+  } catch (_) {}
+
+  // Strategy 2 — JWT email from oauth_rotation.active_file
+  try {
+    const activeFile = provider.oauth_rotation?.active_file;
+    if (!activeFile) return null;
+    const filePath = activeFile.replace(/^~/, os.homedir());
+    if (!fs.existsSync(filePath)) return null;
+    const creds = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    // Gemini-style: { id_token: "..." }  |  Codex-style: { tokens: { id_token: "..." } }
+    const jwt = creds.id_token ?? creds.tokens?.id_token;
+    if (!jwt) return null;
+    const payload = Buffer.from(jwt.split('.')[1], 'base64url').toString('utf8');
+    return JSON.parse(payload).email ?? null;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * add() — no-op: the terminal already ran auth.login; nothing to capture.
+ */
+async function add(_provider, _name) {}
+
+module.exports = { list, switch: switchAccount, addCredentialFile, extractAccountName, add };

package/bin/autoClosePtoF.cjs

@@ -0,0 +1,110 @@
+/**
+ * P->F auto-close remediation dispatch
+ * Dispatches parameter updates via /qgsd:quick for drift entries,
+ * flags investigation for issue/invariant entries.
+ *
+ * Requirements: PF-04, PF-05
+ */
+
+'use strict';
+
+const { transitionDebtEntry } = require('./debt-state-machine.cjs');
+const { readDebtLedger, writeDebtLedger } = require('./debt-ledger.cjs');
+
+/**
+ * Auto-close P->F divergent entries with two-track dispatch
+ * @param {object} residual - The p_to_f residual from sweepPtoF
+ * @param {object} [options]
+ * @param {function} [options.spawnTool] - Mock spawn function for testing
+ * @param {function} [options.isNumericThreshold] - Mock isNumericThreshold for testing
+ * @param {function} [options.writeDebtLedger] - Mock write function for testing
+ * @param {string} [options.ledgerPath] - Path to debt.json
+ * @param {string} [options.specDir] - Path to spec directory
+ * @returns {{ actions_taken: string[], entries_processed: number }}
+ */
+function autoClosePtoF(residual, options = {}) {
+  if (!residual || residual.residual === 0) {
+    return { actions_taken: [], entries_processed: 0 };
+  }
+
+  const isNumericFn = options.isNumericThreshold || require('./isNumericThreshold.cjs').isNumericThreshold;
+  const writeLedgerFn = options.writeDebtLedger || writeDebtLedger;
+  const spawnFn = options.spawnTool || null;
+  const specDir = options.specDir;
+  const ledgerPath = options.ledgerPath;
+
+  const actions = [];
+  const divergent = residual.detail?.divergent_entries || [];
+
+  if (divergent.length === 0) {
+    return { actions_taken: [], entries_processed: 0 };
+  }
+
+  // Read full ledger to get actual entry objects for mutation
+  const ledger = ledgerPath ? readDebtLedger(ledgerPath) : { debt_entries: [] };
+
+  for (const div of divergent) {
+    // Find actual entry in ledger
+    const entryIdx = (ledger.debt_entries || []).findIndex(e => e.id === div.id);
+    if (entryIdx === -1) continue;
+
+    let entry = ledger.debt_entries[entryIdx];
+
+    // Freeze: transition acknowledged -> resolving
+    const freezeResult = transitionDebtEntry(entry, 'resolving');
+    if (!freezeResult.success) {
+      actions.push(`Cannot freeze entry ${entry.id}: ${freezeResult.error}`);
+      continue;
+    }
+    entry = freezeResult.entry;
+    ledger.debt_entries[entryIdx] = entry;
+
+    // Determine track: parameter update vs investigation
+    const isParameter = entry.issue_type === 'drift' && isNumericFn(entry.formal_ref, { specDir });
+
+    if (isParameter) {
+      // Parameter update track: dispatch /qgsd:quick
+      let dispatchOk = false;
+
+      if (spawnFn) {
+        const result = spawnFn('qgsd-quick.cjs', [
+          `Update formal parameter ${entry.formal_ref} to match production`,
+          `Production measurement: ${entry.meta?.measured_value}`,
+          `Current formal: ${div.expected}`,
+        ]);
+        dispatchOk = result && result.ok;
+      }
+
+      entry.meta = entry.meta || {};
+      entry.meta.remediation_log = `${new Date().toISOString()} - Dispatched parameter update: ${entry.formal_ref}`;
+
+      if (dispatchOk) {
+        const resolveResult = transitionDebtEntry(entry, 'resolved');
+        if (resolveResult.success) {
+          entry = resolveResult.entry;
+          ledger.debt_entries[entryIdx] = entry;
+        }
+        actions.push(`Dispatched parameter update for ${entry.id}`);
+      } else {
+        // Failed dispatch - entry stays in resolving (state machine does not allow resolving->acknowledged)
+        // It will need manual triage to resolve or a future mechanism to revert
+        actions.push(`Failed to dispatch parameter update for ${entry.id}`);
+      }
+    } else {
+      // Investigation track: flag only, do NOT auto-remediate
+      entry.meta = entry.meta || {};
+      entry.meta.investigation_notes = `${new Date().toISOString()} - Production diverged from ${entry.formal_ref || 'unknown'}. Requires manual review.`;
+      actions.push(`Flagged ${entry.id} for investigation`);
+      // Entry stays in 'resolving' status — investigation needed
+    }
+  }
+
+  // Persist updated ledger to disk
+  if (ledgerPath) {
+    writeLedgerFn(ledgerPath, ledger);
+  }
+
+  return { actions_taken: actions, entries_processed: divergent.length };
+}
+
+module.exports = { autoClosePtoF };