@nforma.ai/nforma 0.2.1

package/bin/probe-quorum-slots.cjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * probe-quorum-slots.cjs — parallel reachability probe for quorum slots
+ *
+ * Usage:
+ *   node probe-quorum-slots.cjs --slots slot1,slot2,slot3 [--timeout 8000] [--cwd <dir>]
+ *
+ * Spawns each slot's CLI with a minimal "OK" prompt and a short timeout.
+ * All slots are probed in parallel (Promise.all).
+ *
+ * Output (stdout): JSON array of { slot, healthy, latencyMs, error }
+ *   healthy: true  → CLI responded within timeout (any exit code)
+ *   healthy: false → CLI timed out or failed to spawn
+ *
+ * Only probes type=subprocess slots. HTTP slots are skipped (marked healthy=true by default).
+ * Exit code: always 0 — caller interprets the JSON to decide what to skip.
+ */
+
+const { spawn } = require('child_process');
+const fs         = require('fs');
+const path       = require('path');
+const os         = require('os');
+
+// ─── Find providers.json (mirrors call-quorum-slot.cjs logic) ────────────────
+function findProviders() {
+  const searchPaths = [
+    path.join(__dirname, 'providers.json'),
+    path.join(os.homedir(), '.claude', 'qgsd-bin', 'providers.json'),
+  ];
+  try {
+    const claudeJson = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.claude.json'), 'utf8'));
+    const u1args = claudeJson?.mcpServers?.['unified-1']?.args ?? [];
+    const serverScript = u1args.find(a => typeof a === 'string' && a.endsWith('unified-mcp-server.mjs'));
+    if (serverScript) searchPaths.unshift(path.join(path.dirname(serverScript), 'providers.json'));
+  } catch (_) {}
+  for (const p of searchPaths) {
+    try { if (fs.existsSync(p)) return JSON.parse(fs.readFileSync(p, 'utf8')).providers; } catch (_) {}
+  }
+  return null;
+}
+
+// ─── Kill entire process group (mirrors call-quorum-slot.cjs killGroup) ──────
+function makeKillGroup(child) {
+  return () => {
+    try { process.kill(-child.pid, 'SIGTERM'); } catch (_) { try { child.kill('SIGTERM'); } catch (_) {} }
+    setTimeout(() => {
+      try { process.kill(-child.pid, 'SIGKILL'); } catch (_) { try { child.kill('SIGKILL'); } catch (_) {} }
+      try { child.stdout.destroy(); } catch (_) {}
+      try { child.stderr.destroy(); } catch (_) {}
+    }, 1000);
+  };
+}
+
+// ─── Probe a single subprocess slot ──────────────────────────────────────────
+function probeSlot(provider, timeoutMs, spawnCwd) {
+  return new Promise((resolve) => {
+    const start = Date.now();
+
+    // Replace {prompt} with the minimal probe string
+    const args = provider.args_template.map(a => (a === '{prompt}' ? 'OK' : a));
+    const env  = { ...process.env, ...(provider.env ?? {}) };
+
+    let child;
+    try {
+      child = spawn(provider.cli, args, {
+        env,
+        cwd:      spawnCwd,
+        stdio:    ['pipe', 'pipe', 'pipe'],
+        detached: true,
+      });
+    } catch (err) {
+      resolve({ slot: provider.name, healthy: false, latencyMs: Date.now() - start, error: `spawn: ${err.message}` });
+      return;
+    }
+
+    child.stdin.end(); // non-interactive
+
+    let stdout   = '';
+    let stderr   = '';
+    let timedOut = false;
+
+    const killGroup = makeKillGroup(child);
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killGroup();
+    }, timeoutMs);
+
+    child.stdout.on('data', d => { stdout += d.toString().slice(0, 1024); });
+    child.stderr.on('data', d => { stderr += d.toString().slice(0,  512); });
+
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      const latencyMs = Date.now() - start;
+      if (timedOut) {
+        resolve({ slot: provider.name, healthy: false, latencyMs, error: `TIMEOUT after ${timeoutMs}ms` });
+      } else {
+        // Any response (even exit code ≠ 0) counts as "reachable" — the CLI started and ran.
+        // Only a timeout means the slot is truly unreachable.
+        resolve({ slot: provider.name, healthy: true, latencyMs, error: code !== 0 ? `exit ${code}` : null });
+      }
+    });
+
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      resolve({ slot: provider.name, healthy: false, latencyMs: Date.now() - start, error: `spawn: ${err.message}` });
+    });
+  });
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+async function main() {
+  const argv   = process.argv.slice(2);
+  const getArg = (f) => { const i = argv.indexOf(f); return i !== -1 && argv[i + 1] ? argv[i + 1] : null; };
+
+  const slotsArg  = getArg('--slots');
+  const timeoutMs = Math.max(1000, parseInt(getArg('--timeout') || '8000', 10));
+  const spawnCwd  = getArg('--cwd') ?? process.cwd();
+
+  if (!slotsArg) {
+    process.stderr.write('Usage: node probe-quorum-slots.cjs --slots slot1,slot2 [--timeout 8000] [--cwd <dir>]\n');
+    process.exit(1);
+  }
+
+  const providers = findProviders();
+  if (!providers) {
+    process.stderr.write('[probe-quorum-slots] Could not find providers.json — skipping probe\n');
+    // Fail-open: emit empty array so caller treats all slots as healthy
+    process.stdout.write('[]\n');
+    process.exit(0);
+  }
+
+  if (providers.length === 0) {
+    process.stderr.write('[probe-quorum-slots] No providers configured in providers.json — skipping probe\n');
+    process.stdout.write('[]\n');
+    process.exit(0);
+  }
+
+  const slotNames = slotsArg.split(',').map(s => s.trim()).filter(Boolean);
+
+  const results = await Promise.all(
+    slotNames.map(name => {
+      const provider = providers.find(p => p.name === name);
+      if (!provider) {
+        // Unknown slot — treat as healthy (fail-open)
+        return Promise.resolve({ slot: name, healthy: true, latencyMs: 0, error: 'unknown slot — skipped' });
+      }
+      if (provider.type !== 'subprocess') {
+        // HTTP slots are not probed — treat as healthy
+        return Promise.resolve({ slot: name, healthy: true, latencyMs: 0, error: null });
+      }
+      return probeSlot(provider, timeoutMs, spawnCwd);
+    })
+  );
+
+  process.stdout.write(JSON.stringify(results, null, 2) + '\n');
+  process.exit(0);
+}
+
+main().catch(err => {
+  process.stderr.write(`[probe-quorum-slots] Fatal: ${err.message}\n`);
+  // Fail-open on unexpected errors
+  process.stdout.write('[]\n');
+  process.exit(0);
+});

package/bin/promote-model.cjs

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+'use strict';
+// bin/promote-model.cjs
+// Atomic promotion: merges PROPERTY definitions from proposed-changes.tla into
+// a canonical target spec. Both the spec and model-registry.json are written
+// atomically using tmp+rename to prevent partial writes.
+//
+// Usage:
+//   node bin/promote-model.cjs <proposed-changes.tla> <target-spec.tla> [--source-id <id>]
+//
+// Exit codes:
+//   0 — success (merged N properties, registry updated)
+//   1 — error (file not found, duplicate property names, etc.)
+
+const fs   = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+
+// ── Find .planning/formal/ root from target path ───────────────────────────────────────
+// Walks up from a given path until finding .planning/formal/, then
+// returns the grandparent of that directory as the project root.
+// Falls back to ROOT (the QGSD project root) if no .planning/formal/ ancestor is found.
+function findProjectRoot(startPath) {
+  let current = path.dirname(startPath);
+  while (true) {
+    if (path.basename(current) === 'formal' && path.basename(path.dirname(current)) === '.planning') {
+      return path.dirname(path.dirname(current));
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break; // filesystem root
+    current = parent;
+  }
+  return ROOT; // fallback
+}
+
+// ── Parse CLI arguments ───────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+
+let proposedPath = null;
+let targetPath   = null;
+let sourceId     = null;
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--source-id' && i + 1 < args.length) {
+    sourceId = args[++i];
+  } else if (!proposedPath) {
+    proposedPath = args[i];
+  } else if (!targetPath) {
+    targetPath = args[i];
+  }
+}
+
+if (!proposedPath || !targetPath) {
+  process.stderr.write('Usage: node bin/promote-model.cjs <proposed-changes.tla> <target-spec.tla> [--source-id <id>]\n');
+  process.exit(1);
+}
+
+// Resolve paths relative to cwd (or absolute)
+const resolvedProposed = path.resolve(proposedPath);
+const resolvedTarget   = path.resolve(targetPath);
+
+// ── Read proposed file ─────────────────────────────────────────────────────
+if (!fs.existsSync(resolvedProposed)) {
+  process.stderr.write('Error: proposed file not found: ' + resolvedProposed + '\n');
+  process.exit(1);
+}
+const proposedContent = fs.readFileSync(resolvedProposed, 'utf8');
+
+// ── Read target file ───────────────────────────────────────────────────────
+if (!fs.existsSync(resolvedTarget)) {
+  process.stderr.write('Error: target file not found: ' + resolvedTarget + '\n');
+  process.exit(1);
+}
+const targetContent = fs.readFileSync(resolvedTarget, 'utf8');
+
+// ── Extract PROPERTY names using canonical regex ───────────────────────────
+// Pattern: /^PROPERTY\s+(\w+)/gm — sufficient for all TLA+ PROPERTY declarations.
+// Each PROPERTY keyword appears at line start with its name on the same line.
+const PROPERTY_RE = /^PROPERTY\s+(\w+)/gm;
+
+function extractPropertyNames(content) {
+  return [...content.matchAll(PROPERTY_RE)].map(m => m[1]);
+}
+
+const proposedNames = extractPropertyNames(proposedContent);
+const targetNames   = extractPropertyNames(targetContent);
+
+if (proposedNames.length === 0) {
+  process.stderr.write('Warning: no PROPERTY definitions found in proposed file: ' + resolvedProposed + '\n');
+  // Not an error — allow no-op promotions
+}
+
+// ── Duplicate detection ────────────────────────────────────────────────────
+const targetNameSet = new Set(targetNames);
+const duplicates = proposedNames.filter(name => targetNameSet.has(name));
+
+if (duplicates.length > 0) {
+  process.stderr.write('Error: duplicate PROPERTY names: ' + duplicates.join(', ') + '\n');
+  process.stderr.write('These names already exist in target spec: ' + resolvedTarget + '\n');
+  process.exit(1);
+}
+
+// ── Extract PROPERTY blocks from proposed content ─────────────────────────
+// We extract all lines that are part of PROPERTY blocks.
+// A PROPERTY block starts at a line matching /^PROPERTY\s+\w+/ and continues
+// until the next PROPERTY, INVARIANT, ===, or EOF.
+function extractPropertyBlocks(content) {
+  const lines = content.split('\n');
+  const blocks = [];
+  let inBlock = false;
+  let currentBlock = [];
+
+  for (const line of lines) {
+    if (/^PROPERTY\s+\w+/.test(line)) {
+      if (inBlock && currentBlock.length > 0) {
+        // Trim trailing empty lines from previous block
+        while (currentBlock.length > 0 && currentBlock[currentBlock.length - 1].trim() === '') {
+          currentBlock.pop();
+        }
+        blocks.push(currentBlock.join('\n'));
+        currentBlock = [];
+      }
+      inBlock = true;
+      currentBlock.push(line);
+    } else if (inBlock) {
+      // Stop at module-level delimiters
+      if (/^====/.test(line) || /^INVARIANT\s+/.test(line)) {
+        if (currentBlock.length > 0) {
+          while (currentBlock.length > 0 && currentBlock[currentBlock.length - 1].trim() === '') {
+            currentBlock.pop();
+          }
+          blocks.push(currentBlock.join('\n'));
+          currentBlock = [];
+        }
+        inBlock = false;
+      } else {
+        currentBlock.push(line);
+      }
+    }
+  }
+
+  // Flush last block
+  if (inBlock && currentBlock.length > 0) {
+    while (currentBlock.length > 0 && currentBlock[currentBlock.length - 1].trim() === '') {
+      currentBlock.pop();
+    }
+    if (currentBlock.length > 0) {
+      blocks.push(currentBlock.join('\n'));
+    }
+  }
+
+  return blocks;
+}
+
+const propertyBlocks = extractPropertyBlocks(proposedContent);
+
+// ── Merge into target ──────────────────────────────────────────────────────
+// Insert before the closing ==== if present, otherwise append.
+let mergedContent;
+const endMarkerIndex = targetContent.lastIndexOf('\n====');
+
+if (endMarkerIndex !== -1) {
+  // Insert before the ==== end marker
+  const before = targetContent.slice(0, endMarkerIndex);
+  const after  = targetContent.slice(endMarkerIndex);
+  mergedContent = before + '\n\n' + propertyBlocks.join('\n\n') + '\n' + after;
+} else {
+  // Append at end
+  mergedContent = targetContent.trimEnd() + '\n\n' + propertyBlocks.join('\n\n') + '\n';
+}
+
+// ── Atomic write of target spec ────────────────────────────────────────────
+const tmpSpec = resolvedTarget + '.tmp.' + Date.now() + '.' + Math.random().toString(36).slice(2);
+fs.writeFileSync(tmpSpec, mergedContent, 'utf8');
+fs.renameSync(tmpSpec, resolvedTarget);
+
+// ── Update model-registry.json ─────────────────────────────────────────────
+// Find registry relative to the target file's .planning/formal/ ancestor
+const projectRoot  = findProjectRoot(resolvedTarget);
+const registryPath = path.join(projectRoot, '.planning', 'formal', 'model-registry.json');
+let newVersion = null;
+
+if (!fs.existsSync(registryPath)) {
+  process.stderr.write('[promote-model] Warning: .planning/formal/model-registry.json not found — skipping registry update\n');
+} else {
+  let registry;
+  try {
+    registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+  } catch (err) {
+    process.stderr.write('[promote-model] Warning: cannot parse registry — skipping update: ' + err.message + '\n');
+    registry = null;
+  }
+
+  if (registry) {
+    if (!registry.models) registry.models = {};
+    const key = path.relative(projectRoot, resolvedTarget).replace(/\\/g, '/');
+    const now = new Date().toISOString();
+    const existing = registry.models[key] || {};
+    newVersion = (existing.version || 0) + 1;
+
+    registry.models[key] = {
+      version: newVersion,
+      last_updated: now,
+      update_source: 'plan-promote',
+      source_id: sourceId || null,
+      session_id: null,
+      description: existing.description || ''
+    };
+    registry.last_sync = now;
+
+    // Atomic write of registry
+    const tmpReg = registryPath + '.tmp.' + Date.now() + '.' + Math.random().toString(36).slice(2);
+    fs.writeFileSync(tmpReg, JSON.stringify(registry, null, 2), 'utf8');
+    fs.renameSync(tmpReg, registryPath);
+  }
+}
+
+// ── Report success ─────────────────────────────────────────────────────────
+const versionStr = newVersion !== null ? '. Registry version: ' + newVersion : '';
+process.stdout.write(
+  '[promote-model] Merged ' + proposedNames.length + ' propert' +
+  (proposedNames.length === 1 ? 'y' : 'ies') +
+  ' into ' + path.relative(process.cwd(), resolvedTarget) + versionStr + '\n'
+);

package/bin/propose-debug-invariants.cjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+'use strict';
+// bin/propose-debug-invariants.cjs
+// LOOP-04 (v0.21-03): Mine debug session artifacts for TLA+ PROPERTY candidates.
+// Usage:
+//   node bin/propose-debug-invariants.cjs                  # Interactive: accept/reject each
+//   node bin/propose-debug-invariants.cjs --non-interactive # CI: print all, exit 0
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs   = require('fs');
+
+const NON_INTERACTIVE = process.argv.includes('--non-interactive');
+const DEBUG_ARTIFACT_PATH = path.join(process.cwd(), '.planning', 'quick', 'quorum-debug-latest.md');
+const ACCEPT_SCRIPT = path.join(__dirname, 'accept-debug-invariant.cjs');
+const DEFAULT_SPEC  = path.join(process.cwd(), '.planning', 'formal', 'tla', 'QGSDQuorum.tla');
+
+function sanitizeTlaName(str) {
+  return str.replace(/[^a-zA-Z0-9]+/g, '_').slice(0, 40).replace(/^_+|_+$/g, '') || 'Unknown';
+}
+
+function mineTransitions(lines) {
+  const candidates = [];
+  const seen = new Set();
+  const re = /(\w+)\s*[-\u2192]>\s*(\w+)/g;
+  for (let i = 0; i < lines.length; i++) {
+    let m;
+    re.lastIndex = 0;
+    while ((m = re.exec(lines[i])) !== null) {
+      const from = m[1], to = m[2];
+      const key = from + '_' + to;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const name = 'TransitionHint_' + from + '_to_' + to;
+      const body = '[][phase = "' + from + '" => phase\' \\in {"' + from + '", "' + to + '"}]_vars';
+      candidates.push({
+        name, body,
+        source: 'line ' + (i + 1) + ' "' + lines[i].trim().slice(0, 60) + '"',
+        formatted: 'PROPERTY ' + name + ' == ' + body,
+      });
+    }
+  }
+  return candidates;
+}
+
+function mineRootCauses(lines) {
+  const candidates = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/root_cause:\s*(.+)/i);
+    if (!m) continue;
+    const text = m[1].trim();
+    const sanitized = sanitizeTlaName(text);
+    const name = 'RootCauseHint_' + sanitized;
+    const body = 'TRUE  \\* Review: ' + text.slice(0, 80);
+    candidates.push({
+      name, body,
+      source: 'line ' + (i + 1) + ' "' + lines[i].trim().slice(0, 60) + '"',
+      formatted: 'INVARIANT ' + name + ' == ' + body,
+    });
+  }
+  return candidates;
+}
+
+function mineInvariantCandidates(lines) {
+  const candidates = [];
+  let n = 1;
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/[Ii]nvariant(?:\s+candidate)?:\s*(.+)/);
+    if (!m) continue;
+    const text = m[1].trim();
+    const name = 'InvariantCandidate_' + n++;
+    const body = 'TRUE  \\* TODO: Formalize: ' + text.slice(0, 80);
+    candidates.push({
+      name, body,
+      source: 'line ' + (i + 1) + ' "' + lines[i].trim().slice(0, 60) + '"',
+      formatted: 'PROPERTY ' + name + ' == ' + body,
+    });
+  }
+  return candidates;
+}
+
+if (!fs.existsSync(DEBUG_ARTIFACT_PATH)) {
+  process.stdout.write('No debug artifact found at ' + path.relative(process.cwd(), DEBUG_ARTIFACT_PATH) + ' — run a debug session first.\n');
+  process.exit(0);
+}
+
+let artifactText;
+try {
+  artifactText = fs.readFileSync(DEBUG_ARTIFACT_PATH, 'utf8');
+} catch (e) {
+  process.stdout.write('Warning: failed to read debug artifact: ' + e.message + '\n');
+  process.exit(0);
+}
+
+const lines = artifactText.split('\n');
+
+const candidates = [
+  ...mineTransitions(lines),
+  ...mineRootCauses(lines),
+  ...mineInvariantCandidates(lines),
+];
+
+if (candidates.length === 0) {
+  process.stdout.write('No invariant candidates detected in the debug artifact.\n');
+  process.exit(0);
+}
+
+if (NON_INTERACTIVE) {
+  process.stdout.write('=== propose-debug-invariants: ' + candidates.length + ' candidate(s) from quorum-debug-latest.md ===\n\n');
+  for (let i = 0; i < candidates.length; i++) {
+    const c = candidates[i];
+    process.stdout.write('[' + (i + 1) + '] ' + c.formatted + '\n');
+    process.stdout.write('    Source: ' + c.source + '\n\n');
+  }
+  process.stdout.write('Run without --non-interactive to accept/reject each individually.\n');
+  process.exit(0);
+}
+
+const readline = require('readline');
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+let accepted = 0, rejected = 0, skipped = 0;
+let idx = 0;
+
+function askNext() {
+  if (idx >= candidates.length) {
+    rl.close();
+    process.stdout.write('\nSummary: ' + accepted + ' accepted, ' + rejected + ' rejected, ' + skipped + ' skipped.\n');
+    process.exit(0);
+    return;
+  }
+
+  const c = candidates[idx];
+  process.stdout.write('\n[' + (idx + 1) + '/' + candidates.length + '] ' + c.formatted + '\n');
+  process.stdout.write('    Source: ' + c.source + '\n');
+  rl.question('Accept [a], Reject [r], or Skip [s]? ', (answer) => {
+    const choice = answer.trim().toLowerCase();
+    if (choice === 'a') {
+      const sessionId = 'debug-sess-' + Math.floor(Date.now() / 1000) + '-' + Math.random().toString(16).slice(2, 10);
+      const acceptResult = spawnSync(process.execPath, [
+        ACCEPT_SCRIPT, DEFAULT_SPEC,
+        '--property-name', c.name,
+        '--property-body', c.body,
+        '--session-id', sessionId,
+      ], { encoding: 'utf8', timeout: 15000 });
+
+      if (acceptResult.status === 0 && !acceptResult.error) {
+        process.stdout.write('Accepted: ' + c.name + ' -> written to spec.\n');
+        accepted++;
+      } else {
+        process.stdout.write('Warning: failed to write invariant: ' + (acceptResult.stderr || String(acceptResult.error || '')) + '\n');
+      }
+    } else if (choice === 'r') {
+      process.stdout.write('Rejected.\n');
+      rejected++;
+    } else {
+      process.stdout.write('Skipped.\n');
+      skipped++;
+    }
+    idx++;
+    askNext();
+  });
+}
+
+askNext();