@nforma.ai/nforma 0.2.1

package/bin/generate-proposed-changes.cjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+'use strict';
+// bin/generate-proposed-changes.cjs
+// PLAN-01: Reads must_haves: truths: from a single PLAN.md file and generates
+// a proposed-changes.tla scratch spec with INVARIANT/PROPERTY stubs in {phaseDir}/.formal/.
+// Also generates MCProposedChanges.cfg for TLC invocation.
+//
+// Reuses parsePlanFrontmatter and classifyTruth from generate-phase-spec.cjs.
+//
+// Usage:
+//   node bin/generate-proposed-changes.cjs <path-to-PLAN.md> [--dry-run]
+//
+// Output: {phaseDir}/.formal/proposed-changes.tla + MCProposedChanges.cfg
+
+const fs   = require('fs');
+const path = require('path');
+
+const { parsePlanFrontmatter, classifyTruth } = require('./generate-phase-spec.cjs');
+
+/**
+ * Generate a TLA+ proposed-changes spec from a single PLAN.md file.
+ *
+ * @param {string} planFilePath - Absolute path to a PLAN.md file
+ * @returns {{ generated: boolean, reason?: string, specPath?: string, truthCount?: number, classifications?: Array<{truth: string, kind: string, propName: string}> }}
+ */
+function generateProposedChanges(planFilePath) {
+  const content = fs.readFileSync(planFilePath, 'utf8');
+  const fm = parsePlanFrontmatter(content);
+  const phase = fm.phase || 'unknown';
+  const truths = fm.truths || [];
+
+  if (truths.length === 0) {
+    return { generated: false, reason: 'no truths' };
+  }
+
+  const classifications = [];
+  const timestamp = new Date().toISOString();
+
+  // Build TLA+ module
+  let spec = `---- MODULE ProposedChanges ----
+\\* Source: must_haves: truths: from PLAN.md YAML frontmatter
+\\* Generated by bin/generate-proposed-changes.cjs -- PLAN-01
+\\* Phase: ${phase}
+\\* Source file: ${planFilePath}
+\\* Generated: ${timestamp}
+
+EXTENDS Naturals, FiniteSets, TLC
+
+`;
+
+  // ReqNN-to-Truth index mapping block
+  spec += `\\* === ReqNN-to-Truth Mapping ===\n`;
+  truths.forEach((truth, idx) => {
+    const propName = `Req${String(idx + 1).padStart(2, '0')}`;
+    spec += `\\* ${propName} -> Truth[${idx}]: "${truth}"\n`;
+  });
+  spec += `\\* ================================\n\n`;
+
+  // Minimal state machine
+  spec += `VARIABLES state
+
+Init == state = "INIT"
+
+Next == state' = state
+
+Spec == Init /\\ [][Next]_<<state>>
+
+`;
+
+  // Generate stubs for each truth
+  truths.forEach((truth, idx) => {
+    const kind = classifyTruth(truth);
+    const propName = `Req${String(idx + 1).padStart(2, '0')}`;
+    classifications.push({ truth, kind, propName });
+
+    // Escape for TLA+ comment
+    const label = truth.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    spec += `${propName} == TRUE \\* "${label}"\n\n`;
+  });
+
+  spec += `====`;
+
+  // Determine output directory: phaseDir/.formal/
+  const phaseDir = path.dirname(planFilePath);
+  const formalDir = path.join(phaseDir, '.formal');
+  fs.mkdirSync(formalDir, { recursive: true });
+
+  const specPath = path.join(formalDir, 'ProposedChanges.tla');
+  fs.writeFileSync(specPath, spec, 'utf8');
+
+  return {
+    generated: true,
+    specPath,
+    truthCount: truths.length,
+    classifications,
+  };
+}
+
+/**
+ * Generate MCProposedChanges.cfg from a proposed-changes.tla file.
+ *
+ * @param {string} specPath - Absolute path to proposed-changes.tla
+ * @returns {{ cfgPath: string }}
+ */
+function generateTlaCfg(specPath) {
+  const specContent = fs.readFileSync(specPath, 'utf8');
+  const lines = specContent.split('\n');
+
+  let cfg = 'SPECIFICATION Spec\n';
+
+  // Parse each ReqNN line to determine if it was classified as INVARIANT or PROPERTY
+  // We read the classifications from the mapping block comments
+  const mappingRegex = /^\\?\*\s+(Req\d{2})\s+->\s+Truth\[(\d+)\]:\s+"(.+)"/;
+  const propNames = [];
+
+  for (const line of lines) {
+    const match = line.match(mappingRegex);
+    if (match) {
+      propNames.push({ propName: match[1], truth: match[3] });
+    }
+  }
+
+  // Classify each truth to determine INVARIANT vs PROPERTY for the .cfg
+  for (const { propName, truth } of propNames) {
+    const kind = classifyTruth(truth);
+    if (kind === 'INVARIANT') {
+      cfg += `INVARIANT ${propName}\n`;
+    } else {
+      cfg += `PROPERTY ${propName}\n`;
+    }
+  }
+
+  const cfgPath = path.join(path.dirname(specPath), 'MCProposedChanges.cfg');
+  fs.writeFileSync(cfgPath, cfg, 'utf8');
+
+  return { cfgPath };
+}
+
+// ── CLI entrypoint ────────────────────────────────────────────────────────────
+if (require.main === module) {
+  const args    = process.argv.slice(2).filter(a => !a.startsWith('--'));
+  const flags   = process.argv.slice(2).filter(a => a.startsWith('--'));
+  const isDryRun = flags.includes('--dry-run');
+
+  if (args.length === 0) {
+    process.stderr.write('[generate-proposed-changes] Usage: node bin/generate-proposed-changes.cjs <path-to-PLAN.md> [--dry-run]\n');
+    process.stderr.write('[generate-proposed-changes] Generates proposed-changes.tla + MCProposedChanges.cfg in {phaseDir}/.formal/\n');
+    process.exit(1);
+  }
+
+  const planFilePath = path.resolve(args[0]);
+  if (!fs.existsSync(planFilePath)) {
+    process.stderr.write('[generate-proposed-changes] Error: file not found: ' + planFilePath + '\n');
+    process.exit(1);
+  }
+
+  if (isDryRun) {
+    // Read and parse without writing
+    const content = fs.readFileSync(planFilePath, 'utf8');
+    const fm = parsePlanFrontmatter(content);
+    const truths = fm.truths || [];
+
+    if (truths.length === 0) {
+      process.stderr.write('[generate-proposed-changes] No truths found in ' + planFilePath + '\n');
+      process.exit(0);
+    }
+
+    process.stdout.write('[generate-proposed-changes] DRY-RUN\n');
+    process.stdout.write('[generate-proposed-changes] Plan: ' + planFilePath + '\n');
+    process.stdout.write('[generate-proposed-changes] Truths: ' + truths.length + '\n');
+    truths.forEach((t, i) => {
+      const kind = classifyTruth(t);
+      process.stdout.write('  Req' + String(i + 1).padStart(2, '0') + ' [' + kind + ']: ' + t + '\n');
+    });
+  } else {
+    const result = generateProposedChanges(planFilePath);
+
+    if (!result.generated) {
+      process.stderr.write('[generate-proposed-changes] ' + result.reason + ' in ' + planFilePath + '\n');
+      process.exit(0);
+    }
+
+    const { cfgPath } = generateTlaCfg(result.specPath);
+
+    process.stdout.write('[generate-proposed-changes] Spec: ' + result.specPath + '\n');
+    process.stdout.write('[generate-proposed-changes] Config: ' + cfgPath + '\n');
+    process.stdout.write('[generate-proposed-changes] Truths: ' + result.truthCount + '\n');
+    result.classifications.forEach(c => {
+      process.stdout.write('  ' + c.propName + ' [' + c.kind + ']: ' + c.truth + '\n');
+    });
+  }
+}
+
+module.exports = { generateProposedChanges, generateTlaCfg };

package/bin/generate-tla-cfg.cjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+'use strict';
+// bin/generate-tla-cfg.cjs
+// Generates TLA+ model configuration files from the XState machine.
+//
+// The XState machine (src/machines/qgsd-workflow.machine.ts) is the SOURCE OF TRUTH.
+// MCsafety.cfg and MCliveness.cfg are generated artifacts — do not edit them by hand.
+// To change MaxDeliberation, update the XState machine context default instead.
+//
+// Usage:
+//   node bin/generate-tla-cfg.cjs        # writes MCsafety.cfg + MCliveness.cfg
+//   node bin/generate-tla-cfg.cjs --dry  # print output without writing
+//
+// Why agent counts are hardcoded here (not derived from code):
+//   SAFETY_AGENTS=5 and LIVENESS_AGENTS=3 are model-checking parameters, not
+//   runtime constants. 5 matches the quorum slot count; 3 keeps the liveness
+//   state space tractable (liveness + symmetry = incompatible in TLC).
+
+const fs   = require('fs');
+const path = require('path');
+
+const ROOT  = path.join(__dirname, '..');
+const DRY   = process.argv.includes('--dry');
+
+// ── Model-checking parameters (stable, not derived from code) ─────────────────
+const SAFETY_AGENTS   = 5;   // N for MCsafety — matches QGSD quorum slot count
+const LIVENESS_AGENTS = 3;   // N for MCliveness — smaller for tractable liveness
+
+// ── Extract MaxDeliberation from the XState machine ───────────────────────────
+const machineFile = path.join(ROOT, 'src', 'machines', 'qgsd-workflow.machine.ts');
+if (!fs.existsSync(machineFile)) {
+  process.stderr.write('[generate-tla-cfg] XState machine not found: ' + machineFile + '\n');
+  process.exit(1);
+}
+const machineSrc = fs.readFileSync(machineFile, 'utf8');
+
+const maxDelibMatch = machineSrc.match(/maxDeliberation:\s*(\d+)/);
+if (!maxDelibMatch) {
+  process.stderr.write(
+    '[generate-tla-cfg] Could not find maxDeliberation in XState context defaults.\n' +
+    '[generate-tla-cfg] Expected: maxDeliberation: <number>\n'
+  );
+  process.exit(1);
+}
+const maxDeliberation = parseInt(maxDelibMatch[1], 10);
+process.stdout.write('[generate-tla-cfg] Extracted maxDeliberation=' + maxDeliberation + ' from XState machine\n');
+
+// ── Generate agent declarations ───────────────────────────────────────────────
+function agentDecls(n) {
+  const lines = [];
+  for (let i = 1; i <= n; i++) {
+    lines.push('    a' + i + ' = a' + i);
+  }
+  return lines.join('\n');
+}
+
+function agentsSet(n) {
+  const names = [];
+  for (let i = 1; i <= n; i++) names.push('a' + i);
+  return '{' + names.join(', ') + '}';
+}
+
+// ── Build MCsafety.cfg ────────────────────────────────────────────────────────
+const safetyCfg = [
+  '\\* .planning/formal/tla/MCsafety.cfg',
+  '\\* GENERATED — do not edit by hand.',
+  '\\* Source of truth: src/machines/qgsd-workflow.machine.ts',
+  '\\* Regenerate: node bin/generate-tla-cfg.cjs',
+  '\\*',
+  '\\* TLC safety model: N=' + SAFETY_AGENTS + ' agents, symmetry reduction, no liveness check.',
+  '\\* Run: node bin/run-tlc.cjs MCsafety  (requires Java >=17 and tla2tools.jar)',
+  '\\* NOTE: SYMMETRY requires model values — agents declared as model values (a1=a1 etc.)',
+  'SPECIFICATION Spec',
+  'CONSTANTS',
+  agentDecls(SAFETY_AGENTS),
+  '    Agents = ' + agentsSet(SAFETY_AGENTS),
+  '    MaxDeliberation = ' + maxDeliberation,
+  'SYMMETRY AgentSymmetry',
+  'INVARIANT TypeOK',
+  'INVARIANT MinQuorumMet',
+  'PROPERTY NoInvalidTransition',
+  'CHECK_DEADLOCK FALSE',
+  '',
+].join('\n');
+
+// ── Build MCliveness.cfg ──────────────────────────────────────────────────────
+const livenessCfg = [
+  '\\* .planning/formal/tla/MCliveness.cfg',
+  '\\* GENERATED — do not edit by hand.',
+  '\\* Source of truth: src/machines/qgsd-workflow.machine.ts',
+  '\\* Regenerate: node bin/generate-tla-cfg.cjs',
+  '\\*',
+  '\\* TLC liveness model: N=' + LIVENESS_AGENTS + ' agents, NO symmetry (incompatible with liveness), PROPERTY only.',
+  '\\* Use -workers 1 for liveness (defensive against older TLC multi-worker liveness bugs).',
+  '\\* Run: node bin/run-tlc.cjs MCliveness  (requires Java >=17 and tla2tools.jar)',
+  '\\* NOTE: Agents set to ' + LIVENESS_AGENTS + ' model values for tractable liveness checking.',
+  'SPECIFICATION Spec',
+  'CONSTANTS',
+  agentDecls(LIVENESS_AGENTS),
+  '    Agents = ' + agentsSet(LIVENESS_AGENTS),
+  '    MaxDeliberation = ' + maxDeliberation,
+  'PROPERTY EventualConsensus',
+  'CHECK_DEADLOCK FALSE',
+  '',
+].join('\n');
+
+// ── Write or print ────────────────────────────────────────────────────────────
+const safetyPath   = path.join(ROOT, '.planning', 'formal', 'tla', 'MCsafety.cfg');
+const livenessPath = path.join(ROOT, '.planning', 'formal', 'tla', 'MCliveness.cfg');
+
+if (DRY) {
+  process.stdout.write('\n--- MCsafety.cfg ---\n' + safetyCfg);
+  process.stdout.write('\n--- MCliveness.cfg ---\n' + livenessCfg);
+} else {
+  fs.writeFileSync(safetyPath,   safetyCfg,   'utf8');
+  fs.writeFileSync(livenessPath, livenessCfg, 'utf8');
+  process.stdout.write('[generate-tla-cfg] Written: .planning/formal/tla/MCsafety.cfg\n');
+  process.stdout.write('[generate-tla-cfg] Written: .planning/formal/tla/MCliveness.cfg\n');
+}
+
+process.stdout.write('[generate-tla-cfg] MaxDeliberation=' + maxDeliberation +
+  '  SafetyAgents=' + SAFETY_AGENTS + '  LivenessAgents=' + LIVENESS_AGENTS + '\n');