@nforma.ai/nforma 0.2.1

package/bin/generate-petri-net.cjs

@@ -0,0 +1,397 @@
+#!/usr/bin/env node
+'use strict';
+// bin/generate-petri-net.cjs
+// Generates a Graphviz DOT + SVG Petri Net for the QGSD quorum token-passing model.
+// Requirements: PET-01, PET-02, PET-03
+//
+// Usage:
+//   node bin/generate-petri-net.cjs
+//
+// Output:
+//   .planning/formal/petri/quorum-petri-net.dot  — Graphviz DOT source
+//   .planning/formal/petri/quorum-petri-net.svg  — Rendered SVG (via @hpcc-js/wasm-graphviz)
+//
+// No system Graphviz install required — uses @hpcc-js/wasm-graphviz WASM build.
+
+const fs   = require('fs');
+const path = require('path');
+
+// Quorum configuration
+const QUORUM_SLOTS    = ['gemini', 'opencode', 'copilot', 'codex', 'claude'];
+const MIN_QUORUM_SIZE = Math.ceil(QUORUM_SLOTS.length / 2);  // = 3
+
+// Optional --min-quorum=N override (makes PET-03 deadlock check exercisable at runtime)
+const minQuorumArg = process.argv.slice(2).find(a => a.startsWith('--min-quorum='));
+const effectiveMinQuorum = minQuorumArg
+  ? parseInt(minQuorumArg.split('=')[1], 10)
+  : MIN_QUORUM_SIZE;
+
+// PET-03: structural deadlock check (pure logic — before any rendering)
+// A structural deadlock occurs when the quorum transition can NEVER fire because
+// min_quorum_size > available_slots (more approvals needed than slots available)
+if (effectiveMinQuorum > QUORUM_SLOTS.length) {
+  process.stderr.write(
+    '[generate-petri-net] WARNING: Structural deadlock detected.\n' +
+    '[generate-petri-net] min_quorum_size (' + effectiveMinQuorum + ') > ' +
+    'available_slots (' + QUORUM_SLOTS.length + ').\n' +
+    '[generate-petri-net] Quorum transition can never fire.\n'
+  );
+  // Do NOT exit 1 — still emit the net for documentation purposes (per PET-03)
+}
+
+// buildDot: pure function — exported via _pure for unit testing
+function buildDot(slots, minQuorum) {
+  return [
+    'digraph quorum_petri_net {',
+    '  rankdir=LR;',
+    '  label="QGSD Quorum Petri Net (min_quorum=' + minQuorum + '/' + slots.length + ')";',
+    '  node [fontname="Helvetica"];',
+    '',
+    '  // Places (circles)',
+    '  node [shape=circle, fixedsize=true, width=1.2];',
+    '  idle         [label="idle"];',
+    '  collecting   [label="collecting\\nvotes"];',
+    '  deliberating [label="deliberating"];',
+    '  decided      [label="decided"];',
+    '',
+    '  // Transitions (filled rectangles)',
+    '  node [shape=rect, height=0.3, width=1.5, style=filled, fillcolor=black, fontcolor=white];',
+    '  t_start      [label="start quorum"];',
+    '  t_approve    [label="approve\\n(>=' + minQuorum + '/' + slots.length + ')"];',
+    '  t_deliberate [label="deliberate"];',
+    '  t_force      [label="force decide\\n(max rounds)"];',
+    '',
+    '  // Arcs (bipartite: place->transition or transition->place only)',
+    '  idle -> t_start;',
+    '  t_start -> collecting;',
+    '  collecting -> t_approve;',
+    '  collecting -> t_deliberate;',
+    '  t_approve -> decided;',
+    '  t_deliberate -> deliberating;',
+    '  deliberating -> t_approve;',
+    '  deliberating -> t_force;',
+    '  t_force -> decided;',
+    '}',
+  ].join('\n');
+}
+
+// ── Roadmap Petri Net (SIG-02) ───────────────────────────────────────────────
+
+/**
+ * parseRoadmapPhases(roadmapContent) — parses ROADMAP.md to extract phases and dependencies.
+ * @param {string} roadmapContent - Raw ROADMAP.md content
+ * @returns {Array<{ number: string, name: string, dependsOn: string[], completed: boolean }>}
+ */
+function parseRoadmapPhases(roadmapContent) {
+  const lines = roadmapContent.split('\n');
+  const phases = [];
+  let currentPhase = null;
+
+  const phaseHeaderRe = /^### Phase (v[\d.]+-\d+):\s*(.+)/;
+  const dependsOnRe = /^\*\*Depends on\*\*:\s*(.+)/;
+  const checkboxRe = /^- \[(x| )\].*(?:Phase )?(v[\d.]+-\d+)/;
+
+  const completedFromCheckboxes = new Set();
+
+  for (const line of lines) {
+    const headerMatch = phaseHeaderRe.exec(line);
+    if (headerMatch) {
+      if (currentPhase) phases.push(currentPhase);
+      currentPhase = {
+        number: headerMatch[1],
+        name: headerMatch[2].trim(),
+        dependsOn: [],
+        completed: false,
+      };
+      if (line.includes('completed')) currentPhase.completed = true;
+      continue;
+    }
+
+    if (currentPhase) {
+      const depsMatch = dependsOnRe.exec(line);
+      if (depsMatch) {
+        const depsStr = depsMatch[1];
+        const phaseRefs = depsStr.match(/v[\d.]+-\d+/g);
+        if (phaseRefs) {
+          currentPhase.dependsOn = phaseRefs;
+        }
+        continue;
+      }
+    }
+
+    const cbMatch = checkboxRe.exec(line);
+    if (cbMatch && cbMatch[1] === 'x') {
+      completedFromCheckboxes.add(cbMatch[2]);
+    }
+  }
+  if (currentPhase) phases.push(currentPhase);
+
+  // Mark completed from checkboxes and content patterns
+  for (const phase of phases) {
+    if (completedFromCheckboxes.has(phase.number)) {
+      phase.completed = true;
+    }
+  }
+
+  // Second pass: detect "(completed YYYY-MM-DD)" near phase headers
+  let currentPhaseIdx = -1;
+  for (const line of lines) {
+    const headerMatch = phaseHeaderRe.exec(line);
+    if (headerMatch) {
+      currentPhaseIdx = phases.findIndex(function(p) { return p.number === headerMatch[1]; });
+      continue;
+    }
+    if (currentPhaseIdx >= 0 && /completed\s+\d{4}-\d{2}-\d{2}/.test(line)) {
+      phases[currentPhaseIdx].completed = true;
+    }
+  }
+
+  return phases;
+}
+
+/**
+ * buildRoadmapDot(phases) — generates a Petri net DOT from parsed phases.
+ * @param {Array<{ number: string, name: string, dependsOn: string[], completed: boolean }>} phases
+ * @returns {string} DOT source
+ */
+function buildRoadmapDot(phases) {
+  const lines = [
+    'digraph roadmap_petri_net {',
+    '  rankdir=LR;',
+    '  label="QGSD Roadmap Petri Net (' + phases.length + ' phases)";',
+    '  node [fontname="Helvetica"];',
+    '',
+  ];
+
+  if (phases.length === 0) {
+    lines.push('}');
+    return lines.join('\n');
+  }
+
+  const phaseNumbers = new Set(phases.map(function(p) { return p.number; }));
+  const hasDependents = new Set();
+  for (const phase of phases) {
+    for (const dep of phase.dependsOn) {
+      if (phaseNumbers.has(dep)) hasDependents.add(dep);
+    }
+  }
+
+  lines.push('  // Places (circles)');
+  lines.push('  node [shape=circle, fixedsize=true, width=0.8];');
+
+  const sourcesExist = phases.some(function(p) { return p.dependsOn.length === 0; });
+  if (sourcesExist) {
+    lines.push('  p_start [label="start"];');
+  }
+
+  for (const phase of phases) {
+    for (const dep of phase.dependsOn) {
+      if (!phaseNumbers.has(dep)) continue;
+      const placeId = 'p_' + dep.replace(/[.-]/g, '_') + '__' + phase.number.replace(/[.-]/g, '_');
+      lines.push('  ' + placeId + ' [label=""];');
+    }
+  }
+
+  const sinksExist = phases.some(function(p) { return !hasDependents.has(p.number); });
+  if (sinksExist) {
+    lines.push('  p_done [label="done"];');
+  }
+
+  lines.push('');
+  lines.push('  // Transitions (rectangles) -- phases');
+  for (const phase of phases) {
+    const nodeId = 't_' + phase.number.replace(/[.-]/g, '_');
+    const label = phase.number + '\\n' + phase.name.substring(0, 30);
+    if (phase.completed) {
+      lines.push('  ' + nodeId + ' [shape=rect, height=0.5, width=2.0, style=filled, fillcolor="#4CAF50", fontcolor=white, label="' + label + '"];');
+    } else {
+      lines.push('  ' + nodeId + ' [shape=rect, height=0.5, width=2.0, style=filled, fillcolor=black, fontcolor=white, label="' + label + '"];');
+    }
+  }
+
+  lines.push('');
+  lines.push('  // Arcs');
+  for (const phase of phases) {
+    const nodeId = 't_' + phase.number.replace(/[.-]/g, '_');
+
+    if (phase.dependsOn.length === 0 && sourcesExist) {
+      lines.push('  p_start -> ' + nodeId + ';');
+    }
+
+    for (const dep of phase.dependsOn) {
+      if (!phaseNumbers.has(dep)) continue;
+      const placeId = 'p_' + dep.replace(/[.-]/g, '_') + '__' + phase.number.replace(/[.-]/g, '_');
+      lines.push('  ' + placeId + ' -> ' + nodeId + ';');
+    }
+
+    for (const downstream of phases) {
+      if (downstream.dependsOn.includes(phase.number)) {
+        const placeId = 'p_' + phase.number.replace(/[.-]/g, '_') + '__' + downstream.number.replace(/[.-]/g, '_');
+        lines.push('  ' + nodeId + ' -> ' + placeId + ';');
+      }
+    }
+
+    if (!hasDependents.has(phase.number) && sinksExist) {
+      lines.push('  ' + nodeId + ' -> p_done;');
+    }
+  }
+
+  lines.push('}');
+  return lines.join('\n');
+}
+
+/**
+ * computeCriticalPath(phases) — finds the longest path through the phase DAG.
+ * @param {Array<{ number: string, name: string, dependsOn: string[], completed: boolean }>} phases
+ * @returns {{ path: string[], length: number }}
+ */
+function computeCriticalPath(phases) {
+  if (phases.length === 0) return { path: [], length: 0 };
+
+  const phaseMap = new Map();
+  for (const p of phases) phaseMap.set(p.number, p);
+
+  // Kahn's algorithm for topological sort + longest path DP
+  const inDegree = new Map();
+  const adj = new Map();
+
+  for (const p of phases) {
+    if (!inDegree.has(p.number)) inDegree.set(p.number, 0);
+    if (!adj.has(p.number)) adj.set(p.number, []);
+  }
+
+  for (const p of phases) {
+    for (const dep of p.dependsOn) {
+      if (!phaseMap.has(dep)) continue;
+      if (!adj.has(dep)) adj.set(dep, []);
+      adj.get(dep).push(p.number);
+      inDegree.set(p.number, (inDegree.get(p.number) || 0) + 1);
+    }
+  }
+
+  const queue = [];
+  for (const [node, deg] of inDegree) {
+    if (deg === 0) queue.push(node);
+  }
+
+  const dist = new Map();
+  const pred = new Map();
+  for (const p of phases) {
+    dist.set(p.number, 1);
+    pred.set(p.number, null);
+  }
+
+  while (queue.length > 0) {
+    const node = queue.shift();
+    for (const next of (adj.get(node) || [])) {
+      if (dist.get(node) + 1 > dist.get(next)) {
+        dist.set(next, dist.get(node) + 1);
+        pred.set(next, node);
+      }
+      inDegree.set(next, inDegree.get(next) - 1);
+      if (inDegree.get(next) === 0) queue.push(next);
+    }
+  }
+
+  let maxDist = 0;
+  let endNode = null;
+  for (const [node, d] of dist) {
+    if (d > maxDist) {
+      maxDist = d;
+      endNode = node;
+    }
+  }
+
+  const criticalPath = [];
+  let current = endNode;
+  while (current !== null) {
+    criticalPath.unshift(current);
+    current = pred.get(current);
+  }
+
+  return { path: criticalPath, length: criticalPath.length };
+}
+
+// Export pure functions for unit testing
+module.exports._pure = { buildDot, buildRoadmapDot, computeCriticalPath, parseRoadmapPhases };
+
+// Guard against running main logic when required as a module (test imports)
+if (require.main === module) {
+  const isRoadmap = process.argv.includes('--roadmap');
+
+  if (isRoadmap) {
+    // ── Roadmap Petri Net mode ──────────────────────────────────────────────
+    const roadmapPath = path.join(process.cwd(), '.planning', 'ROADMAP.md');
+    if (!fs.existsSync(roadmapPath)) {
+      process.stderr.write('[generate-petri-net] ROADMAP.md not found at: ' + roadmapPath + '\n');
+      process.exit(1);
+    }
+
+    const content = fs.readFileSync(roadmapPath, 'utf8');
+    const phases = parseRoadmapPhases(content);
+    const dotContent = buildRoadmapDot(phases);
+    const criticalPath = computeCriticalPath(phases);
+
+    const outDir  = path.join(process.cwd(), '.planning', 'formal', 'petri');
+    const dotPath = path.join(outDir, 'roadmap-petri-net.dot');
+    const svgPath = path.join(outDir, 'roadmap-petri-net.svg');
+
+    fs.mkdirSync(outDir, { recursive: true });
+    fs.writeFileSync(dotPath, dotContent);
+    process.stdout.write('[generate-petri-net] Roadmap DOT written to: ' + dotPath + '\n');
+    process.stdout.write('[generate-petri-net] Phases: ' + phases.length + '\n');
+    process.stdout.write('[generate-petri-net] Critical path (' + criticalPath.length + '): ' + criticalPath.path.join(' -> ') + '\n');
+
+    // Render SVG
+    (async () => {
+      let Graphviz;
+      try {
+        ({ Graphviz } = await import('@hpcc-js/wasm-graphviz'));
+      } catch (_e) {
+        process.stderr.write('[generate-petri-net] @hpcc-js/wasm-graphviz not installed -- SVG skipped.\n');
+        process.exit(0);
+      }
+      try {
+        const graphviz = await Graphviz.load();
+        const svg      = graphviz.dot(dotContent);
+        fs.writeFileSync(svgPath, svg);
+        process.stdout.write('[generate-petri-net] Roadmap SVG written to: ' + svgPath + '\n');
+      } catch (renderErr) {
+        process.stderr.write('[generate-petri-net] SVG render failed: ' + renderErr.message + '\n');
+        process.exit(1);
+      }
+    })();
+  } else {
+    // ── Quorum Petri Net mode (existing) ────────────────────────────────────
+    const dotContent = buildDot(QUORUM_SLOTS, effectiveMinQuorum);
+    const outDir     = path.join(process.cwd(), '.planning', 'formal', 'petri');
+    const dotPath    = path.join(outDir, 'quorum-petri-net.dot');
+    const svgPath    = path.join(outDir, 'quorum-petri-net.svg');
+
+    fs.mkdirSync(outDir, { recursive: true });
+    fs.writeFileSync(dotPath, dotContent);
+    process.stdout.write('[generate-petri-net] DOT written to: ' + dotPath + '\n');
+
+    (async () => {
+      let Graphviz;
+      try {
+        ({ Graphviz } = await import('@hpcc-js/wasm-graphviz'));
+      } catch (importErr) {
+        process.stderr.write(
+          '[generate-petri-net] @hpcc-js/wasm-graphviz not installed.\n' +
+          '[generate-petri-net] Run: npm install --save-dev @hpcc-js/wasm-graphviz\n'
+        );
+        process.exit(1);
+      }
+      try {
+        const graphviz = await Graphviz.load();
+        const svg      = graphviz.dot(dotContent);
+        fs.writeFileSync(svgPath, svg);
+        process.stdout.write('[generate-petri-net] SVG written to: ' + svgPath + '\n');
+      } catch (renderErr) {
+        process.stderr.write('[generate-petri-net] SVG render failed: ' + renderErr.message + '\n');
+        process.exit(1);
+      }
+    })();
+  }
+}

package/bin/generate-phase-spec.cjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+'use strict';
+// bin/generate-phase-spec.cjs
+// SPEC-04: Reads must_haves: truths: from *-PLAN.md YAML frontmatter and translates
+// them into per-phase TLA+ scratch spec with INVARIANT/PROPERTY stubs.
+//
+// Data source: YAML frontmatter in *-PLAN.md files (NOT task-envelope.json — truths
+// are empty in task-envelope.json at planning time; plan frontmatter is the correct source).
+//
+// Usage:
+//   node bin/generate-phase-spec.cjs .planning/phases/v0.21-04-spec-completeness/
+//   node bin/generate-phase-spec.cjs .planning/phases/v0.21-04-spec-completeness/v0.21-04-01-PLAN.md
+//   node bin/generate-phase-spec.cjs <phase-dir-or-plan-file> --dry-run
+//
+// Output: .planning/formal/tla/scratch/<phase>-<timestamp>.tla
+
+const fs   = require('fs');
+const path = require('path');
+
+const ROOT       = path.join(__dirname, '..');
+const SCRATCH_DIR = path.join(ROOT, '.planning', 'formal', 'tla', 'scratch');
+
+/**
+ * Parse YAML frontmatter from a PLAN.md file.
+ * Returns the frontmatter object (parsed manually — no yaml dependency).
+ * Frontmatter is between the first two '---' lines.
+ *
+ * Extracts:
+ *   - phase: string
+ *   - truths: string[] from must_haves.truths
+ */
+function parsePlanFrontmatter(content) {
+  const lines = content.split('\n');
+  if (!lines[0] || lines[0].trim() !== '---') return { truths: [] };
+  const endIdx = lines.slice(1).findIndex(l => l.trim() === '---');
+  if (endIdx === -1) return { truths: [] };
+  const fmLines = lines.slice(1, endIdx + 1);
+
+  // Minimal YAML parser: extracts must_haves.truths array and phase field only.
+  // Looks for 'must_haves:' block, then 'truths:' key, then collects '- "..."' or "- '...'" entries.
+  const result = {};
+  let inMustHaves = false;
+  let inTruths = false;
+  const truths = [];
+
+  for (const line of fmLines) {
+    // Detect phase field at top-level
+    const phaseMatch = line.match(/^phase:\s*(.+)/);
+    if (phaseMatch) {
+      result.phase = phaseMatch[1].replace(/['"]/g, '').trim();
+      continue;
+    }
+
+    if (/^must_haves:/.test(line)) {
+      inMustHaves = true;
+      inTruths = false;
+      continue;
+    }
+
+    if (inMustHaves && /^\s{2}truths:/.test(line)) {
+      inTruths = true;
+      continue;
+    }
+
+    if (inMustHaves && inTruths) {
+      // Match list items: "    - "text"" or "    - 'text'" or "    - text"
+      const itemMatch = line.match(/^\s{4}-\s+"?'?(.+?)'?"?\s*$/);
+      if (itemMatch) {
+        // Clean up: strip surrounding quotes if present
+        let truth = itemMatch[1].trim();
+        // Remove leading/trailing quotes that may remain
+        truth = truth.replace(/^["']|["']$/g, '');
+        if (truth.length > 0) truths.push(truth);
+        continue;
+      }
+      // Stop collecting truths when indentation drops below 4 spaces (non-list, non-empty)
+      if (!/^\s{4}/.test(line) && line.trim() !== '') {
+        inTruths = false;
+      }
+    }
+
+    // Detect top-level key change inside must_haves (drops indentation)
+    if (inMustHaves && !inTruths && !/^\s{2,}/.test(line) && line.trim() !== '') {
+      inMustHaves = false;
+    }
+  }
+
+  result.truths = truths;
+  return result;
+}
+
+/**
+ * Collect all *-PLAN.md files from a directory or single file path.
+ * Returns sorted array of absolute paths.
+ */
+function collectPlanFiles(inputPath) {
+  const resolved = path.resolve(inputPath);
+  const stat = fs.statSync(resolved);
+  if (stat.isFile()) return [resolved];
+  // Directory: find *-PLAN.md files
+  return fs.readdirSync(resolved)
+    .filter(f => f.endsWith('-PLAN.md'))
+    .sort()
+    .map(f => path.join(resolved, f));
+}
+
+/**
+ * Classify a truth string as safety (INVARIANT) or liveness (PROPERTY).
+ *
+ * Liveness keywords: eventually, deadline, async, progress, future, after, until, leads-to
+ * Safety keywords: everything else (threshold, depth, count, max, min, never, always, etc.)
+ *
+ * @param {string} truth
+ * @returns {'PROPERTY' | 'INVARIANT'}
+ */
+function classifyTruth(truth) {
+  const lower = truth.toLowerCase();
+  const livenessKeywords = [
+    'eventually',
+    'deadline',
+    'async',
+    'progress',
+    'future',
+    'leads-to',
+    'after',
+    'until',
+  ];
+  const isLiveness = livenessKeywords.some(kw => lower.includes(kw));
+  return isLiveness ? 'PROPERTY' : 'INVARIANT';
+}
+
+/**
+ * Generate TLA+ module content from collected truths.
+ *
+ * @param {{ phase: string, truths: string[] }} options
+ * @returns {{ moduleName: string, spec: string, truthCount: number }}
+ */
+function generatePhaseSpec({ phase, truths }) {
+  const allTruths = truths || [];
+
+  // TLA+ module name: sanitize phase string (e.g. v0.21-04 → Phasev0_21_04Spec)
+  const moduleName = 'Phase' + (phase || 'unknown').replace(/[^a-zA-Z0-9]/g, '_') + 'Spec';
+  const timestamp = new Date().toISOString();
+
+  let spec = `---- MODULE ${moduleName} ----
+(* Source: must_haves: truths: from *-PLAN.md YAML frontmatter *)
+(* Generated by bin/generate-phase-spec.cjs — SPEC-04 *)
+(* Phase: ${phase || 'unknown'} *)
+(* Generated: ${timestamp} *)
+(* Purpose: Verify proposed state machine changes before quorum approval *)
+(* PLACEHOLDER properties — developer fills in formal logic before TLC run *)
+
+EXTENDS Naturals, FiniteSets, TLC
+
+VARIABLES state, counter
+
+TypeOK == state \\in {"INIT", "RUNNING", "DONE"}
+
+Init == state = "INIT" /\\ counter = 0
+
+Next ==
+    \\/ /\\ state = "INIT" /\\ state' = "RUNNING" /\\ counter' = counter + 1
+    \\/ /\\ state = "RUNNING" /\\ state' = "DONE" /\\ counter' = counter
+    \\/ /\\ state = "DONE" /\\ UNCHANGED <<state, counter>>
+
+Spec == Init /\\ [][Next]_<<state, counter>>
+
+\\* ── Requirements as Properties ──────────────────────────────────────────────
+
+`;
+
+  if (allTruths.length === 0) {
+    spec += `\\* No must_haves: truths: found in *-PLAN.md frontmatter
+\\* Add truths to see them translated to INVARIANT/PROPERTY stubs
+
+`;
+  }
+
+  allTruths.forEach((truth, idx) => {
+    const kind = classifyTruth(truth);
+    const propName = `Req${String(idx + 1).padStart(2, '0')}`;
+    // Escape backslashes and truncate label for TLA+ comment
+    const label = truth.substring(0, 100).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    spec += `${kind} ${propName} ==
+  \\* "${label}${truth.length > 100 ? '...' : ''}"
+  TRUE  \\* PLACEHOLDER: replace TRUE with formal TLA+ expression
+
+`;
+  });
+
+  spec += `====`;
+  return { moduleName, spec, truthCount: allTruths.length };
+}
+
+// ── 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-phase-spec] Usage: node bin/generate-phase-spec.cjs <phase-dir-or-PLAN.md> [--dry-run]\n');
+    process.stderr.write('[generate-phase-spec] Reads must_haves: truths: from *-PLAN.md YAML frontmatter (NOT task-envelope.json)\n');
+    process.exit(1);
+  }
+
+  const inputPath = path.resolve(args[0]);
+  if (!fs.existsSync(inputPath)) {
+    process.stderr.write('[generate-phase-spec] Error: path not found: ' + inputPath + '\n');
+    process.exit(1);
+  }
+
+  const planFiles = collectPlanFiles(inputPath);
+  if (planFiles.length === 0) {
+    process.stderr.write('[generate-phase-spec] Error: no *-PLAN.md files found in ' + inputPath + '\n');
+    process.exit(1);
+  }
+
+  // Collect truths from all plan files
+  let phase = 'unknown';
+  const allTruths = [];
+  for (const planFile of planFiles) {
+    const content = fs.readFileSync(planFile, 'utf8');
+    const fm = parsePlanFrontmatter(content);
+    if (fm.phase) phase = fm.phase;
+    if (fm.truths && fm.truths.length > 0) allTruths.push(...fm.truths);
+  }
+
+  const { moduleName, spec, truthCount } = generatePhaseSpec({ phase, truths: allTruths });
+  const ts      = Date.now();
+  const outName = phase.replace(/[^a-zA-Z0-9-]/g, '_') + '-' + ts + '.tla';
+  const outPath = path.join(SCRATCH_DIR, outName);
+
+  if (isDryRun) {
+    process.stdout.write('[generate-phase-spec] DRY-RUN: would write ' + outPath + '\n');
+    process.stdout.write('[generate-phase-spec] Plan files: ' + planFiles.join(', ') + '\n');
+    process.stdout.write('[generate-phase-spec] Truths collected: ' + truthCount + '\n');
+    process.stdout.write(spec + '\n');
+  } else {
+    fs.mkdirSync(SCRATCH_DIR, { recursive: true });
+    fs.writeFileSync(outPath, spec, 'utf8');
+    process.stdout.write(
+      '[generate-phase-spec] Written: ' + outPath +
+      ' (' + truthCount + ' truths from ' + planFiles.length + ' plan files → INVARIANT/PROPERTY stubs)\n'
+    );
+  }
+}
+
+module.exports = { generatePhaseSpec, classifyTruth, parsePlanFrontmatter };