@nforma.ai/nforma 0.2.1

package/bin/read-policy.cjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+'use strict';
+// bin/read-policy.cjs
+// Reads and validates .planning/formal/policy.yaml using lightweight regex extraction.
+// No external YAML parser required — policy.yaml uses flat key: value structure.
+// Requirements: CALIB-01, CALIB-04
+
+const fs   = require('fs');
+const path = require('path');
+
+/**
+ * Read and validate .planning/formal/policy.yaml.
+ * Throws Error with descriptive message on missing file or missing required fields.
+ *
+ * @param {string} policyPath  Absolute path to policy.yaml
+ * @returns {{ cold_start: { min_ci_runs: number, min_quorum_rounds: number, min_days: number },
+ *             steady_state: { mode: string },
+ *             conservative_priors: { tp_rate: number, unavail: number } }}
+ */
+function readPolicy(policyPath) {
+  if (!fs.existsSync(policyPath)) {
+    throw new Error('[read-policy] Policy file not found: ' + policyPath);
+  }
+
+  const yaml = fs.readFileSync(policyPath, 'utf8');
+
+  // Extract flat key: value using regex (ignores YAML comments)
+  const extract = (key, asFloat) => {
+    const match = yaml.match(new RegExp('^\\s*' + key + ':\\s*([\\d.]+)', 'm'));
+    if (!match) {
+      throw new Error('[read-policy] Policy missing required key: ' + key);
+    }
+    return asFloat ? parseFloat(match[1]) : parseInt(match[1], 10);
+  };
+
+  const extractStr = (key) => {
+    const match = yaml.match(new RegExp('^\\s*' + key + ':\\s*["\']?([\\w]+)["\']?', 'm'));
+    if (!match) {
+      throw new Error('[read-policy] Policy missing required key: ' + key);
+    }
+    return match[1];
+  };
+
+  return {
+    cold_start: {
+      min_ci_runs:       extract('min_ci_runs', false),
+      min_quorum_rounds: extract('min_quorum_rounds', false),
+      min_days:          extract('min_days', true),
+    },
+    steady_state: {
+      mode: extractStr('mode'),
+    },
+    conservative_priors: {
+      tp_rate: extract('tp_rate', true),
+      unavail: extract('unavail', true),
+    },
+  };
+}
+
+module.exports = { readPolicy };

package/bin/requirement-map.cjs

@@ -0,0 +1,63 @@
+'use strict';
+// bin/requirement-map.cjs
+// Centralized mapping from check_id (used by run-formal-verify.cjs steps) to requirement IDs.
+// Single source of truth for SCHEMA-03: runners import this to populate requirement_ids in NDJSON output.
+//
+// Maintenance: when adding a new formal check or requirement, update this map.
+// The check_id values match those in run-formal-verify.cjs STEPS array and individual runner CHECK_ID_MAP objects.
+
+const CHECK_ID_TO_REQUIREMENTS = {
+  // ── TLA+ checks ──────────────────────────────────────
+  'tla:quorum-safety':       ['QUORUM-01', 'QUORUM-02', 'QUORUM-03', 'SAFE-01', 'SAFE-02', 'SAFE-03', 'LOOP-01'],
+  'tla:quorum-liveness':     ['QUORUM-04', 'RECV-01'],
+  'tla:mcp-environment':     ['MCPENV-01', 'MCPENV-02', 'MCPENV-03'],
+  'tla:breaker':             ['DETECT-01', 'DETECT-02', 'DETECT-03'],
+  'tla:oscillation':         ['DETECT-04', 'DETECT-05', 'DETECT-06'],
+  'tla:convergence':         ['ORES-01', 'ORES-02', 'ORES-03', 'ORES-04', 'ORES-05'],
+  'tla:deliberation':        ['PLAN-01', 'PLAN-02', 'SAFE-03', 'IMPR-01', 'LOOP-02'],
+  'tla:prefilter':           ['PLAN-03', 'PLAN-04', 'PLAN-05', 'PLAN-06', 'LOOP-03'],
+  'tla:account-manager':     ['CRED-01', 'CRED-02', 'CRED-03', 'CRED-04', 'CRED-05', 'CRED-06'],
+  'tla:stop-hook':           ['STOP-01', 'STOP-02', 'STOP-03', 'STOP-04', 'STOP-05', 'STOP-06', 'STOP-07', 'SPEC-01'],
+  'tla:recruiting-safety':   ['SLOT-02', 'SLOT-03', 'SLOT-04'],
+  'tla:recruiting-liveness': ['SLOT-05'],
+  'tla:tui-navigation':      [],
+
+  // ── Alloy checks ─────────────────────────────────────
+  // check_id values match those emitted by individual runner scripts:
+  'alloy:quorum-votes':      ['QUORUM-02', 'SAFE-01', 'SAFE-04'],
+  'alloy:quorum-composition': ['SPEC-03', 'COMP-01'],
+  'alloy:scoreboard':        ['SCBD-01', 'SCBD-02', 'SCBD-03', 'SCBD-04'],
+  'alloy:availability':      ['CALIB-01', 'CALIB-02', 'CALIB-03'],
+  'alloy:transcript':        ['STOP-08', 'STOP-09', 'STOP-10', 'STOP-11'],
+  'alloy:install-scope':     ['INST-01', 'INST-02', 'INST-03', 'INST-04', 'INST-05'],
+  'alloy:taxonomy-safety':   ['SCBD-05', 'SCBD-06', 'SCBD-07'],
+  'alloy:account-pool':      ['CRED-07', 'CRED-08', 'CRED-09', 'CRED-10', 'CRED-11'],
+
+  // ── PRISM checks ─────────────────────────────────────
+  'prism:quorum':           ['PRM-01', 'QUORUM-04', 'LOOP-01'],
+  'prism:oauth-rotation':   ['PRM-AM-01', 'CRED-12'],
+  'prism:mcp-availability': ['MCPENV-04', 'FAIL-01'],
+
+  // ── UPPAAL checks ────────────────────────────────────
+  'uppaal:quorum-races':    ['UPPAAL-01', 'UPPAAL-02', 'UPPAAL-03'],
+
+  // ── CI enforcement checks ────────────────────────────
+  'ci:trace-redaction':         ['REDACT-01'],
+  'ci:trace-schema-drift':      ['DRIFT-01'],
+  'ci:liveness-fairness-lint':  ['LIVE-01', 'LIVE-02'],
+};
+
+/**
+ * Get requirement IDs for a given check_id.
+ * Returns empty array for unknown check_ids (fail-open).
+ *
+ * @param {string} checkId - The check_id (e.g., 'tla:quorum-safety')
+ * @returns {string[]} Array of requirement IDs
+ */
+function getRequirementIds(checkId) {
+  // Return a copy to prevent callers from mutating the shared source-of-truth array.
+  const found = CHECK_ID_TO_REQUIREMENTS[checkId];
+  return found ? found.slice() : [];
+}
+
+module.exports = { CHECK_ID_TO_REQUIREMENTS, getRequirementIds };

package/bin/requirements-core.cjs

@@ -0,0 +1,247 @@
+'use strict';
+
+/**
+ * Pure data functions for requirements management.
+ * No blessed dependency — all functions are testable in isolation.
+ * Consumers: bin/qgsd.cjs (blessed TUI)
+ *
+ * Data sources (project-relative paths via process.cwd()):
+ *   .planning/formal/requirements.json    — 210 requirements in frozen envelope
+ *   .planning/formal/model-registry.json  — formal models with requirement links
+ *   .planning/formal/check-results.ndjson — check results (NDJSON)
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const { getRequirementIds } = require('./requirement-map.cjs');
+
+// ---------------------------------------------------------------------------
+// Data loaders
+// ---------------------------------------------------------------------------
+
+function readRequirementsJson(basePath) {
+  const p = path.join(basePath || process.cwd(), '.planning', 'formal', 'requirements.json');
+  if (!fs.existsSync(p)) return { envelope: null, requirements: [] };
+  try {
+    const raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+    const reqs = raw.requirements || [];
+    const envelope = {
+      aggregated_at: raw.aggregated_at || null,
+      content_hash:  raw.content_hash  || null,
+      frozen_at:     raw.frozen_at     || null,
+    };
+    return { envelope, requirements: reqs };
+  } catch (_) {
+    return { envelope: null, requirements: [] };
+  }
+}
+
+function readModelRegistry(basePath) {
+  const p = path.join(basePath || process.cwd(), '.planning', 'formal', 'model-registry.json');
+  if (!fs.existsSync(p)) return { version: null, last_sync: null, models: {} };
+  try {
+    const raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+    return {
+      version:   raw.version   || null,
+      last_sync: raw.last_sync || null,
+      models:    raw.models    || {},
+    };
+  } catch (_) {
+    return { version: null, last_sync: null, models: {} };
+  }
+}
+
+function readCheckResults(basePath) {
+  const p = path.join(basePath || process.cwd(), '.planning', 'formal', 'check-results.ndjson');
+  if (!fs.existsSync(p)) return [];
+  try {
+    return fs.readFileSync(p, 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .map(line => { try { return JSON.parse(line); } catch (_) { return null; } })
+      .filter(Boolean);
+  } catch (_) {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Computation
+// ---------------------------------------------------------------------------
+
+function computeCoverage(requirements, registry, checkResults) {
+  const total = requirements.length;
+
+  // By status
+  const byStatus = {};
+  for (const r of requirements) {
+    const s = r.status || 'Unknown';
+    byStatus[s] = (byStatus[s] || 0) + 1;
+  }
+
+  // By category
+  const byCategory = {};
+  for (const r of requirements) {
+    const c = r.category || 'Uncategorized';
+    if (!byCategory[c]) byCategory[c] = { total: 0, complete: 0 };
+    byCategory[c].total++;
+    if (r.status === 'Complete') byCategory[c].complete++;
+  }
+
+  // Formal model coverage: which requirements have at least one formal model?
+  const reqsWithModels = new Set();
+  const models = (registry && registry.models) || {};
+  for (const entry of Object.values(models)) {
+    for (const reqId of (entry.requirements || [])) {
+      reqsWithModels.add(reqId);
+    }
+  }
+  // Also include requirements with direct formal_models field (SCHEMA-04)
+  for (const r of requirements) {
+    if (Array.isArray(r.formal_models) && r.formal_models.length > 0) {
+      reqsWithModels.add(r.id);
+    }
+  }
+  const withFormalModels = requirements.filter(r => reqsWithModels.has(r.id)).length;
+  const totalModels = Object.keys(models).length;
+
+  // Check results summary
+  const checksByResult = {};
+  for (const cr of (checkResults || [])) {
+    const res = cr.result || 'unknown';
+    checksByResult[res] = (checksByResult[res] || 0) + 1;
+  }
+
+  // Requirements with at least one check result (via requirement_ids or requirement-map)
+  const reqsWithChecks = new Set();
+  for (const cr of (checkResults || [])) {
+    // Direct requirement_ids on the check result
+    if (Array.isArray(cr.requirement_ids)) {
+      for (const rid of cr.requirement_ids) reqsWithChecks.add(rid);
+    }
+    // Reverse lookup via requirement-map
+    if (cr.check_id) {
+      for (const rid of getRequirementIds(cr.check_id)) reqsWithChecks.add(rid);
+    }
+  }
+  const withCheckResults = requirements.filter(r => reqsWithChecks.has(r.id)).length;
+
+  return {
+    total,
+    byStatus,
+    byCategory,
+    withFormalModels,
+    withCheckResults,
+    totalModels,
+    checksByResult,
+  };
+}
+
+function buildTraceability(reqId, requirements, registry, checkResults) {
+  const requirement = requirements.find(r => r.id === reqId);
+  if (!requirement) return null;
+
+  // Forward: find formal models that list this requirement
+  const formalModels = [];
+  const models = (registry && registry.models) || {};
+  for (const [modelPath, entry] of Object.entries(models)) {
+    if ((entry.requirements || []).includes(reqId)) {
+      formalModels.push({
+        path:        modelPath,
+        description: entry.description || '',
+        version:     entry.version || null,
+      });
+    }
+  }
+  // Also include models listed in requirement's own formal_models field (SCHEMA-04)
+  if (Array.isArray(requirement.formal_models)) {
+    for (const modelPath of requirement.formal_models) {
+      // Deduplicate: skip if already found via registry
+      if (!formalModels.some(fm => fm.path === modelPath)) {
+        // Try to get description from registry if available
+        const registryEntry = models[modelPath];
+        formalModels.push({
+          path:        modelPath,
+          description: (registryEntry && registryEntry.description) || '',
+          version:     (registryEntry && registryEntry.version) || null,
+        });
+      }
+    }
+  }
+
+  // Reverse: find check results linked to this requirement
+  const matchingChecks = [];
+  const unmappedCheckIds = [];
+  for (const cr of (checkResults || [])) {
+    // Direct match via requirement_ids field
+    const directIds = Array.isArray(cr.requirement_ids) ? cr.requirement_ids : [];
+    // Reverse lookup via requirement-map
+    const mapIds = cr.check_id ? getRequirementIds(cr.check_id) : [];
+    const allIds = new Set([...directIds, ...mapIds]);
+
+    if (allIds.has(reqId)) {
+      matchingChecks.push(cr);
+    }
+  }
+
+  // Find check_ids from requirement-map that link to this req but have no results
+  const { CHECK_ID_TO_REQUIREMENTS } = require('./requirement-map.cjs');
+  for (const [checkId, reqIds] of Object.entries(CHECK_ID_TO_REQUIREMENTS)) {
+    if (reqIds.includes(reqId)) {
+      const hasResult = (checkResults || []).some(cr => cr.check_id === checkId);
+      if (!hasResult) unmappedCheckIds.push(checkId);
+    }
+  }
+
+  return {
+    requirement,
+    formalModels,
+    checkResults: matchingChecks,
+    unmappedCheckIds,
+  };
+}
+
+function filterRequirements(requirements, filters) {
+  filters = filters || {};
+  let result = requirements;
+
+  if (filters.category) {
+    result = result.filter(r => (r.category || 'Uncategorized') === filters.category);
+  }
+  if (filters.status) {
+    result = result.filter(r => (r.status || 'Unknown') === filters.status);
+  }
+  if (filters.search) {
+    const s = filters.search.toLowerCase();
+    result = result.filter(r =>
+      (r.id || '').toLowerCase().includes(s) ||
+      (r.text || '').toLowerCase().includes(s)
+    );
+  }
+
+  return result;
+}
+
+function getUniqueCategories(requirements) {
+  const cats = new Set();
+  for (const r of requirements) {
+    cats.add(r.category || 'Uncategorized');
+  }
+  return [...cats].sort();
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  readRequirementsJson,
+  readModelRegistry,
+  readCheckResults,
+  computeCoverage,
+  buildTraceability,
+  filterRequirements,
+  getUniqueCategories,
+};
+
+module.exports._pure = module.exports;

package/bin/resolve-cli.cjs

@@ -0,0 +1,101 @@
+'use strict';
+
+/**
+ * resolve-cli.cjs — CLI path resolution utility
+ *
+ * Resolves a bare CLI name to its full executable path using a priority-ordered search:
+ *   1. which <name>       — system PATH lookup
+ *   2. Homebrew prefixes  — /opt/homebrew/bin, /usr/local/bin
+ *   3. npm global bin     — derived from `npm root -g`
+ *   4. Common system paths — /usr/bin, /usr/local/bin
+ *   5. Bare fallback      — return name unchanged (let OS resolve at spawn time)
+ *
+ * Never throws. Always returns a non-empty string.
+ */
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Resolve a CLI name to its full executable path.
+ * @param {string} name - bare name like "codex", "gemini", "opencode"
+ * @returns {string} full path like "/opt/homebrew/bin/codex" or bare name if not found
+ */
+function resolveCli(name) {
+  if (!name || typeof name !== 'string') return name || '';
+
+  // 1. which <name>
+  try {
+    const result = spawnSync('which', [name], { encoding: 'utf8', timeout: 3000 });
+    if (result.status === 0 && result.stdout) {
+      const found = result.stdout.trim();
+      if (found && found.length > 0) {
+        return found;
+      }
+    }
+  } catch (_) {
+    // which failed — continue to next strategy
+  }
+
+  // 2. Known Homebrew prefixes
+  const homebrewPrefixes = ['/opt/homebrew/bin', '/usr/local/bin'];
+  for (const prefix of homebrewPrefixes) {
+    const candidate = path.join(prefix, name);
+    try {
+      if (fs.existsSync(candidate)) {
+        return candidate;
+      }
+    } catch (_) {
+      // fs error — continue
+    }
+  }
+
+  // 3. npm global bin: npm root -g -> ../bin/<name>
+  try {
+    const npmResult = spawnSync('npm', ['root', '-g'], { encoding: 'utf8', timeout: 5000 });
+    if (npmResult.status === 0 && npmResult.stdout) {
+      const npmRoot = npmResult.stdout.trim();
+      if (npmRoot) {
+        const candidate = path.join(npmRoot, '..', 'bin', name);
+        if (fs.existsSync(candidate)) {
+          return candidate;
+        }
+      }
+    }
+  } catch (_) {
+    // npm failed — continue
+  }
+
+  // 4. Common system paths (deduplicated — /usr/local/bin was checked in step 2)
+  const systemPaths = ['/usr/bin'];
+  for (const dir of systemPaths) {
+    const candidate = path.join(dir, name);
+    try {
+      if (fs.existsSync(candidate)) {
+        return candidate;
+      }
+    } catch (_) {
+      // continue
+    }
+  }
+
+  // 5. Fallback: return bare name (let OS resolve at spawn time)
+  return name;
+}
+
+module.exports = { resolveCli };
+
+// ---------------------------------------------------------------------------
+// Standalone CLI interface
+// ---------------------------------------------------------------------------
+
+if (require.main === module) {
+  const name = process.argv[2];
+  if (!name) {
+    console.error('Usage: node bin/resolve-cli.cjs <name>');
+    process.exit(1);
+  }
+  const resolved = resolveCli(name);
+  console.log(resolved);
+}