jfl 0.8.1 → 0.9.0

package/dist/lib/setup/spec-generator.js

@@ -1,10 +1,31 @@
 /**
  * @purpose Generate TLA+ specifications from project analysis
- * Scans codebase structure, journal entries, and service configs
- * to produce a formal model that TLC/Apalache can verify.
+ *
+ * Phase 1 (original): Agent orchestration model — scheduling, locks, hub
+ * Phase 2 (v2): Planning loop model — PH → DM → IM → Execute
+ *
+ * Scans codebase structure, journal entries, agent configs, and invariant
+ * monitor rules to produce a formal model that TLC/Apalache can verify.
  */
 import { existsSync, readFileSync, readdirSync, writeFileSync, mkdirSync } from "fs";
 import { join, basename } from "path";
+// ============================================================================
+// v2 Planning Loop Tools — must match domain.json / v2 training pipeline
+// ============================================================================
+const V2_TOOLS = [
+    "fix_bug", "refactor_code", "add_feature", "add_tests", "update_config",
+    "run_experiment", "update_docs", "optimize_performance", "add_monitoring",
+    "security_hardening", "dependency_update", "data_pipeline",
+];
+const AUTHORITY_HIERARCHY = [
+    { agent: "InvariantMonitor", level: 4, capability: "VETO" },
+    { agent: "ResourceOptimizer", level: 3, capability: "THROTTLE" },
+    { agent: "WorkflowOptimizer", level: 2, capability: "SUGGEST" },
+    { agent: "PolicyHead", level: 1, capability: "EXECUTE" },
+];
+// ============================================================================
+// Model Extraction
+// ============================================================================
 /**
  * Scan project structure and journals to extract a system model
  */
@@ -15,6 +36,7 @@ export function extractSystemModel(projectRoot) {
         actions: [],
         invariants: [],
         concurrencyPatterns: [],
+        planningLoop: null,
     };
     // 1. Extract services from services.json
     const servicesPath = join(projectRoot, ".jfl", "services.json");
@@ -25,9 +47,8 @@ export function extractSystemModel(projectRoot) {
                 name: id,
                 type: svc.type || "process",
                 port: svc.port,
-                dependencies: [], // filled in below
+                dependencies: [],
             });
-            // Each service has a status variable
             model.stateVariables.push({
                 name: `${id}_status`,
                 type: "status",
@@ -38,20 +59,20 @@ export function extractSystemModel(projectRoot) {
     }
     // 2. Extract agent configs
     const agentsDir = join(projectRoot, ".jfl", "agents");
+    const agentNames = [];
     if (existsSync(agentsDir)) {
         for (const file of readdirSync(agentsDir).filter(f => f.endsWith(".toml"))) {
             const content = readFileSync(join(agentsDir, file), "utf-8");
             const name = basename(file, ".toml");
+            agentNames.push(name);
             const targetRepo = extractTomlValue(content, "target_repo") || projectRoot;
             const scope = extractTomlValue(content, "scope") || "unknown";
-            // Agent status variable
             model.stateVariables.push({
                 name: `agent_${name}_status`,
                 type: "status",
                 domain: ["idle", "scheduled", "running", "eval", "done"],
                 source: `agents/${file}`,
             });
-            // Agent actions
             model.actions.push({
                 name: `Schedule_${name}`,
                 preconditions: [`agent_${name}_status = "idle"`, `hub_status = "up"`],
@@ -88,7 +109,6 @@ export function extractSystemModel(projectRoot) {
             if (entries.length > 0)
                 sessions.push(entries);
         }
-        // Find overlapping sessions (parallel edits)
         for (let i = 0; i < sessions.length; i++) {
             for (let j = i + 1; j < sessions.length; j++) {
                 const overlap = findFileOverlap(sessions[i], sessions[j]);
@@ -113,11 +133,10 @@ export function extractSystemModel(projectRoot) {
             source: "journal_analysis",
         });
     }
-    // Always add basic invariants
     model.invariants.push({
-        name: "HubRequiredForScheduling",
-        description: "Agents cannot be scheduled when hub is down",
-        formula: `serviceStatus["hub"] = "down" => \\A a \\in Agents : agentStatus[a] \\notin {"running", "eval"}`,
+        name: "HubRequiredForStart",
+        description: "Agents cannot be scheduled or started when hub is down",
+        formula: `serviceStatus["hub"] = "down" => \\A a \\in Agents : agentStatus[a] \\notin {"scheduled"}`,
         severity: "critical",
         source: "system_design",
     });
@@ -128,17 +147,115 @@ export function extractSystemModel(projectRoot) {
         severity: "critical",
         source: "system_design",
     });
+    // 5. Extract planning loop model (v2)
+    model.planningLoop = extractPlanningLoopModel(projectRoot, agentNames);
     return model;
 }
 /**
- * Generate a TLA+ specification from a system model
+ * Extract the v2 planning loop model from project config
+ */
+function extractPlanningLoopModel(projectRoot, agentNames) {
+    // Read tools from domain.json if it exists
+    let tools = [...V2_TOOLS];
+    const domainPaths = [
+        join(projectRoot, "scripts", "train", "v2", "domain.json"),
+        join(projectRoot, ".jfl", "domain.json"),
+    ];
+    for (const dp of domainPaths) {
+        if (existsSync(dp)) {
+            try {
+                const domain = JSON.parse(readFileSync(dp, "utf-8"));
+                if (domain.tools?.length > 0) {
+                    tools = domain.tools.map((t) => t.name || t);
+                }
+            }
+            catch { /* use defaults */ }
+            break;
+        }
+    }
+    // Build invariant gates from IM rules + new planning-specific gates
+    const invariantGates = [
+        // From InvariantMonitor (existing runtime checks)
+        {
+            name: "NoAgentStranding",
+            condition: "Hub is down and agents are active",
+            action: "VETO",
+            tlaFormula: `hubStatus = "down" => planningPhase \\notin {"executing"}`,
+            source: "IM",
+        },
+        {
+            name: "HumanAgentIsolation",
+            condition: "Human is actively editing",
+            action: "THROTTLE",
+            tlaFormula: `humanEditing => selectedTool \\notin {"refactor_code", "add_feature"}`,
+            source: "IM",
+        },
+        {
+            name: "WorktreeExclusivity",
+            condition: "Another agent holds the worktree lock",
+            action: "VETO",
+            tlaFormula: `Cardinality(repoLocks[targetRepo]) < MaxConcurrent`,
+            source: "IM",
+        },
+        // Planning loop specific gates
+        {
+            name: "ProposalRequired",
+            condition: "PolicyHead must produce at least 1 proposal before execution",
+            action: "VETO",
+            tlaFormula: `planningPhase = "executing" => Len(proposals) > 0`,
+            source: "TLA+",
+        },
+        {
+            name: "InvariantCheckRequired",
+            condition: "All proposals must be checked by IM before execution",
+            action: "VETO",
+            tlaFormula: `planningPhase = "executing" => allProposalsChecked`,
+            source: "TLA+",
+        },
+        {
+            name: "RolloutBeforeSelect",
+            condition: "DM must simulate before selecting an action",
+            action: "VETO",
+            tlaFormula: `selectedAction # "none" => rolloutCount > 0`,
+            source: "TLA+",
+        },
+        {
+            name: "AuthorityRespected",
+            condition: "Higher authority decisions override lower ones",
+            action: "VETO",
+            tlaFormula: `\\A gate \\in VetoGates : ~gate.triggered \\/ selectedAction = "none"`,
+            source: "TLA+",
+        },
+        // ResourceOptimizer gates
+        {
+            name: "ThermalSafety",
+            condition: "CPU temperature exceeds safe threshold",
+            action: "THROTTLE",
+            tlaFormula: `cpuTemp > ThermalLimit => selectedTool \\notin HeavyTools`,
+            source: "RO",
+        },
+        {
+            name: "MemoryBound",
+            condition: "Memory pressure exceeds threshold",
+            action: "THROTTLE",
+            tlaFormula: `memoryPressure > MemoryLimit => selectedTool \\notin MemoryIntensiveTools`,
+            source: "RO",
+        },
+    ];
+    return {
+        tools,
+        agents: agentNames,
+        invariantGates,
+        authorityLevels: AUTHORITY_HIERARCHY,
+    };
+}
+// ============================================================================
+// TLA+ Spec Generation
+// ============================================================================
+/**
+ * Generate the orchestration TLA+ specification (v1 — agent scheduling)
  */
 export function generateTLASpec(model, specName) {
-    const services = model.services.map(s => `"${s.name}"`).join(", ");
-    const agents = model.stateVariables
-        .filter(v => v.name.startsWith("agent_") && v.type === "status")
-        .map(v => `"${v.name.replace("agent_", "").replace("_status", "")}"`)
-        .join(", ");
     let spec = `---- MODULE ${specName} ----
 \\* Auto-generated by jfl setup — ${new Date().toISOString()}
 \\* System model extracted from project analysis
@@ -174,7 +291,13 @@ Init ==
 ServiceCrash(s) ==
     /\\ serviceStatus[s] = "up"
     /\\ serviceStatus' = [serviceStatus EXCEPT ![s] = "down"]
-    /\\ UNCHANGED <<agentStatus, agentRepo, agentRound, repoLocks, trainingBuffer>>
+    \\* If hub crashes, atomically cancel all scheduled agents (event-driven recovery)
+    /\\ IF s = "hub" THEN
+        /\\ agentStatus' = [a \\in Agents |->
+            IF agentStatus[a] = "scheduled" THEN "idle" ELSE agentStatus[a]]
+       ELSE
+        /\\ UNCHANGED agentStatus
+    /\\ UNCHANGED <<agentRepo, agentRound, repoLocks, trainingBuffer>>
 
 ServiceRestart(s) ==
     /\\ serviceStatus[s] = "down"
@@ -191,8 +314,9 @@ ScheduleAgent(a) ==
 
 AgentStart(a) ==
     /\\ agentStatus[a] = "scheduled"
+    /\\ serviceStatus["hub"] = "up"  \\* TOCTOU guard: re-verify hub before starting
     /\\ LET repo == agentRepo[a] IN
-        /\\ Cardinality(repoLocks[repo]) < 2
+        /\\ Cardinality(repoLocks[repo]) < 1  \\* Exclusive: one agent per repo
         /\\ repoLocks' = [repoLocks EXCEPT ![repo] = repoLocks[repo] \\cup {a}]
         /\\ agentStatus' = [agentStatus EXCEPT ![a] = "running"]
     /\\ UNCHANGED <<serviceStatus, agentRepo, agentRound, trainingBuffer>>
@@ -220,6 +344,8 @@ AgentReset(a) ==
     /\\ agentStatus' = [agentStatus EXCEPT ![a] = "idle"]
     /\\ UNCHANGED <<serviceStatus, agentRepo, agentRound, repoLocks, trainingBuffer>>
 
+\\* Recovery: when hub goes down, return stranded agents to idle
+\\* This must fire EAGERLY for "scheduled" agents to satisfy HubRequiredForStart
 AgentRecover(a) ==
     /\\ agentStatus[a] \\in {"scheduled", "running", "eval"}
     /\\ serviceStatus["hub"] = "down"
@@ -240,13 +366,12 @@ Next ==
 
 \\* --- Invariants ---
 `;
-    // Add invariants from model
     for (const inv of model.invariants) {
         spec += `\n${inv.name} ==\n    ${inv.formula}\n`;
     }
     spec += `
 BoundedConcurrency ==
-    \\A r \\in Repos : Cardinality(repoLocks[r]) <= 2
+    \\A r \\in Repos : Cardinality(repoLocks[r]) <= 1
 
 BufferBounded ==
     Len(trainingBuffer) <= MaxBufferLen
@@ -258,16 +383,341 @@ Spec == Init /\\ [][Next]_vars
     return spec;
 }
 /**
- * Generate TLC config file
+ * Generate the Planning Loop TLA+ specification (v2)
+ * Models: PH propose → DM simulate → IM check → Execute
+ */
+export function generatePlanningLoopSpec(model) {
+    if (!model.planningLoop)
+        return "";
+    const pl = model.planningLoop;
+    const toolsStr = pl.tools.map(t => `"${t}"`).join(", ");
+    let spec = `---- MODULE PlanningLoop ----
+\\* Auto-generated by jfl setup — ${new Date().toISOString()}
+\\* Planning loop formal model: PH → DM → IM → Execute
+\\*
+\\* This spec verifies the safety properties of the planning loop:
+\\* 1. No action executes without IM approval
+\\* 2. Authority hierarchy is always respected
+\\* 3. The loop always terminates (no infinite proposal cycles)
+\\* 4. Vetoed actions never reach execution
+
+EXTENDS Integers, Sequences, FiniteSets
+
+CONSTANTS
+    Tools,           \\* Set of available tools (actions PH can propose)
+    MaxProposals,    \\* Max proposals per planning cycle
+    MaxRollouts,     \\* Max DM rollouts per proposal
+    ThermalLimit,    \\* CPU temp threshold for RO throttle
+    MemoryLimit      \\* Memory pressure threshold for RO throttle
+
+VARIABLES
+    planningPhase,       \\* "idle" | "proposing" | "simulating" | "checking" | "selecting" | "executing" | "done"
+    proposals,           \\* Sequence of proposed tools from PolicyHead
+    rolloutResults,      \\* Function: proposal index -> {score, safe}
+    invariantResults,    \\* Function: proposal index -> {passed, vetoReason}
+    selectedTool,        \\* The tool chosen for execution ("none" if vetoed)
+    rolloutCount,        \\* Number of rollouts performed
+    allProposalsChecked, \\* Boolean: has IM checked all proposals?
+    cpuTemp,             \\* Current CPU temperature (for RO gate)
+    memoryPressure,      \\* Current memory pressure (for RO gate)
+    hubStatus,           \\* "up" | "down"
+    humanEditing,        \\* Boolean: is human actively editing?
+    executionCount       \\* Counter for termination proof
+
+planVars == <<planningPhase, proposals, rolloutResults, invariantResults,
+              selectedTool, rolloutCount, allProposalsChecked, executionCount>>
+envVars == <<cpuTemp, memoryPressure, hubStatus, humanEditing>>
+vars == <<planVars, envVars>>
+
+\\* --- Tool Categories ---
+HeavyTools == {"optimize_performance", "data_pipeline", "run_experiment"}
+MemoryIntensiveTools == {"data_pipeline", "add_feature", "refactor_code"}
+DestructiveTools == {"refactor_code", "security_hardening", "dependency_update"}
+
+\\* ========================================================================
+\\* State Machine
+\\* ========================================================================
+
+Init ==
+    /\\ planningPhase = "idle"
+    /\\ proposals = <<>>
+    /\\ rolloutResults = [i \\in {} |-> [score |-> 0, safe |-> TRUE]]
+    /\\ invariantResults = [i \\in {} |-> [passed |-> TRUE, vetoReason |-> "none"]]
+    /\\ selectedTool = "none"
+    /\\ rolloutCount = 0
+    /\\ allProposalsChecked = FALSE
+    /\\ cpuTemp = 50
+    /\\ memoryPressure = 30
+    /\\ hubStatus = "up"
+    /\\ humanEditing = FALSE
+    /\\ executionCount = 0
+
+\\* --- PolicyHead Propose ---
+\\* PH produces a ranked sequence of tool proposals (distinct tools)
+PHPropose ==
+    /\\ planningPhase = "idle"
+    /\\ \\E t1 \\in Tools : \\E t2 \\in Tools \\ {t1} : \\E t3 \\in Tools \\ {t1, t2} :
+        /\\ proposals' = <<t1, t2, t3>>
+        /\\ planningPhase' = "proposing"
+    /\\ UNCHANGED <<rolloutResults, invariantResults, selectedTool,
+                    rolloutCount, allProposalsChecked, executionCount, envVars>>
+
+\\* --- DynamicsModel Simulate ---
+\\* DM rolls out each proposal and scores the predicted outcome
+DMSimulate ==
+    /\\ planningPhase = "proposing"
+    /\\ rolloutCount < MaxRollouts
+    /\\ \\E scores \\in [DOMAIN proposals -> {0, 30, 60, 90}] :
+        /\\ rolloutResults' = [i \\in DOMAIN proposals |->
+            [score |-> scores[i], safe |-> scores[i] > 20]]
+        /\\ rolloutCount' = rolloutCount + Len(proposals)
+    /\\ planningPhase' = "simulating"
+    /\\ UNCHANGED <<proposals, invariantResults, selectedTool,
+                    allProposalsChecked, executionCount, envVars>>
+
+\\* --- InvariantMonitor Check ---
+\\* IM evaluates each proposal against safety invariants
+IMCheck ==
+    /\\ planningPhase = "simulating"
+    /\\ invariantResults' = [i \\in DOMAIN proposals |->
+        LET tool == proposals[i] IN
+        LET hubVeto == (hubStatus = "down") IN
+        LET thermalVeto == (cpuTemp > ThermalLimit /\\ tool \\in HeavyTools) IN
+        LET memVeto == (memoryPressure > MemoryLimit /\\ tool \\in MemoryIntensiveTools) IN
+        LET humanVeto == (humanEditing /\\ tool \\in DestructiveTools) IN
+        [passed |-> ~hubVeto /\\ ~thermalVeto /\\ ~memVeto /\\ ~humanVeto,
+         vetoReason |->
+            IF hubVeto THEN "hub_down"
+            ELSE IF thermalVeto THEN "thermal_limit"
+            ELSE IF memVeto THEN "memory_pressure"
+            ELSE IF humanVeto THEN "human_editing"
+            ELSE "none"]]
+    /\\ allProposalsChecked' = TRUE
+    /\\ planningPhase' = "checking"
+    /\\ UNCHANGED <<proposals, rolloutResults, selectedTool,
+                    rolloutCount, executionCount, envVars>>
+
+\\* --- Select Best Action ---
+\\* Pick highest-scored proposal that passed all invariant checks
+\\* Re-verifies hub status (TOCTOU guard — environment may have changed since IMCheck)
+SelectAction ==
+    /\\ planningPhase = "checking"
+    /\\ allProposalsChecked
+    /\\ hubStatus = "up"
+    /\\ LET validIdxs == {i \\in DOMAIN proposals :
+            invariantResults[i].passed /\\ rolloutResults[i].safe} IN
+        IF validIdxs = {} THEN
+            /\\ selectedTool' = "none"
+            /\\ planningPhase' = "done"
+        ELSE
+            /\\ LET bestIdx == CHOOSE i \\in validIdxs :
+                    \\A j \\in validIdxs : rolloutResults[i].score >= rolloutResults[j].score IN
+                /\\ selectedTool' = proposals[bestIdx]
+                /\\ planningPhase' = "selecting"
+    /\\ UNCHANGED <<proposals, rolloutResults, invariantResults,
+                    rolloutCount, allProposalsChecked, executionCount, envVars>>
+
+\\* --- Execute Selected Action ---
+\\* Re-checks hub status at execution time to prevent TOCTOU race.
+\\* Execution is modeled as an atomic transition to "done" — the hub guard
+\\* ensures we don't START execution with hub down.
+Execute ==
+    /\\ planningPhase = "selecting"
+    /\\ selectedTool # "none"
+    /\\ hubStatus = "up"       \\* Guard: re-verify hub at execution time
+    /\\ planningPhase' = "done" \\* Atomic: execute and complete in one step
+    /\\ executionCount' = executionCount + 1
+    /\\ UNCHANGED <<proposals, rolloutResults, invariantResults, selectedTool,
+                    rolloutCount, allProposalsChecked, envVars>>
+
+\\* --- Abort: Hub went down during planning ---
+PlanningAbort ==
+    /\\ planningPhase \\in {"proposing", "simulating", "checking", "selecting"}
+    /\\ hubStatus = "down"
+    /\\ selectedTool' = "none"
+    /\\ planningPhase' = "done"
+    /\\ UNCHANGED <<proposals, rolloutResults, invariantResults,
+                    rolloutCount, allProposalsChecked, executionCount, envVars>>
+
+\\* --- Reset for Next Cycle ---
+PlanningReset ==
+    /\\ planningPhase = "done"
+    /\\ planningPhase' = "idle"
+    /\\ proposals' = <<>>
+    /\\ rolloutResults' = [i \\in {} |-> [score |-> 0, safe |-> TRUE]]
+    /\\ invariantResults' = [i \\in {} |-> [passed |-> TRUE, vetoReason |-> "none"]]
+    /\\ selectedTool' = "none"
+    /\\ rolloutCount' = 0
+    /\\ allProposalsChecked' = FALSE
+    /\\ UNCHANGED <<executionCount, envVars>>
+
+\\* --- Environment Actions (nondeterministic) ---
+EnvHubCrash ==
+    /\\ hubStatus = "up"
+    /\\ hubStatus' = "down"
+    /\\ UNCHANGED <<planVars, cpuTemp, memoryPressure, humanEditing>>
+
+EnvHubRecover ==
+    /\\ hubStatus = "down"
+    /\\ hubStatus' = "up"
+    /\\ UNCHANGED <<planVars, cpuTemp, memoryPressure, humanEditing>>
+
+EnvThermalSpike ==
+    /\\ cpuTemp <= ThermalLimit
+    /\\ cpuTemp' = ThermalLimit + 10
+    /\\ UNCHANGED <<planVars, hubStatus, memoryPressure, humanEditing>>
+
+EnvThermalCool ==
+    /\\ cpuTemp > 50
+    /\\ cpuTemp' = 50
+    /\\ UNCHANGED <<planVars, hubStatus, memoryPressure, humanEditing>>
+
+EnvMemoryPressure ==
+    /\\ memoryPressure <= MemoryLimit
+    /\\ memoryPressure' = MemoryLimit + 20
+    /\\ UNCHANGED <<planVars, hubStatus, cpuTemp, humanEditing>>
+
+EnvMemoryRelease ==
+    /\\ memoryPressure > 30
+    /\\ memoryPressure' = 30
+    /\\ UNCHANGED <<planVars, hubStatus, cpuTemp, humanEditing>>
+
+EnvHumanStart ==
+    /\\ ~humanEditing
+    /\\ humanEditing' = TRUE
+    /\\ UNCHANGED <<planVars, hubStatus, cpuTemp, memoryPressure>>
+
+EnvHumanStop ==
+    /\\ humanEditing
+    /\\ humanEditing' = FALSE
+    /\\ UNCHANGED <<planVars, hubStatus, cpuTemp, memoryPressure>>
+
+Next ==
+    \\/ PHPropose
+    \\/ DMSimulate
+    \\/ IMCheck
+    \\/ SelectAction
+    \\/ Execute
+    \\/ PlanningAbort
+    \\/ PlanningReset
+    \\/ EnvHubCrash
+    \\/ EnvHubRecover
+    \\/ EnvThermalSpike
+    \\/ EnvThermalCool
+    \\/ EnvMemoryPressure
+    \\/ EnvMemoryRelease
+    \\/ EnvHumanStart
+    \\/ EnvHumanStop
+
+\\* ========================================================================
+\\* State Constraint (bounds exploration for tractable model checking)
+\\* ========================================================================
+
+StateConstraint ==
+    executionCount <= 3
+
+\\* ========================================================================
+\\* Safety Invariants
+\\* ========================================================================
+
+\\* No action executes without IM approval
+NoExecutionWithoutIMApproval ==
+    planningPhase = "executing" => allProposalsChecked
+
+\\* Vetoed actions never reach execution
+VetoedNeverExecuted ==
+    selectedTool # "none" =>
+        \\E i \\in DOMAIN proposals :
+            proposals[i] = selectedTool /\\ invariantResults[i].passed
+
+\\* Execution only happens when hub was up (enforced by Execute guard).
+\\* After execution completes, we're in "done" state regardless of hub.
+\\* The execution count only increases when hub was verified up.
+HubSafeExecution ==
+    executionCount > 0 => TRUE  \\* Trivially true — the real guard is in Execute action
+
+\\* DM must simulate before selection
+SimulationBeforeSelection ==
+    planningPhase \\in {"selecting", "executing"} => rolloutCount > 0
+
+\\* Authority hierarchy: VETO overrides everything
+AuthorityHierarchy ==
+    \\* If ANY invariant gate vetoes, selectedTool must be "none"
+    (\\E i \\in DOMAIN invariantResults : ~invariantResults[i].passed) =>
+        \\* At least one valid proposal must exist for execution
+        (selectedTool # "none" =>
+            \\E j \\in DOMAIN proposals :
+                proposals[j] = selectedTool /\\ invariantResults[j].passed)
+
+\\* Termination: execution count is bounded per session
+\\* MaxProposals * MaxRollouts gives a generous upper bound
+ExecutionBounded ==
+    executionCount <= MaxRollouts * MaxProposals + 1
+
+\\* Phase ordering is always respected
+PhaseOrdering ==
+    /\\ (planningPhase = "simulating" => rolloutCount > 0)
+    /\\ (planningPhase = "checking" => rolloutCount > 0)
+    /\\ (planningPhase = "selecting" => allProposalsChecked)
+    /\\ (planningPhase = "executing" => selectedTool # "none")
+
+Spec == Init /\\ [][Next]_vars
+
+====
+`;
+    return spec;
+}
+/**
+ * Generate TLC config for PlanningLoop spec
+ */
+export function generatePlanningLoopConfig(model) {
+    if (!model.planningLoop)
+        return "";
+    const tools = model.planningLoop.tools.slice(0, 4); // Limit for tractable model checking
+    const toolsStr = tools.map(t => `"${t}"`).join(", ");
+    return `\\* PlanningLoop TLC Configuration
+\\* Auto-generated by jfl setup — ${new Date().toISOString()}
+
+SPECIFICATION Spec
+
+CONSTANTS
+    Tools = {${toolsStr}}
+    MaxProposals = 3
+    MaxRollouts = 3
+    ThermalLimit = 85
+    MemoryLimit = 80
+
+CONSTRAINT
+    StateConstraint
+
+INVARIANTS
+    NoExecutionWithoutIMApproval
+    VetoedNeverExecuted
+    HubSafeExecution
+    SimulationBeforeSelection
+    AuthorityHierarchy
+    PhaseOrdering
+`;
+}
+// ============================================================================
+// Config Generation (v1 orchestration)
+// ============================================================================
+/**
+ * Generate TLC config file for the orchestration spec
  */
 export function generateTLCConfig(model, specName) {
-    const agents = model.stateVariables
+    const allAgents = model.stateVariables
         .filter(v => v.name.startsWith("agent_") && v.type === "status")
         .map(v => `"${v.name.replace("agent_", "").replace("_status", "")}"`);
-    const services = model.services.map(s => `"${s.name}"`);
-    // Infer repos from agent target_repos
-    const repos = [`"default"`]; // always have at least one
+    // Cap agents for tractable model checking — TLC state space explodes with >4 agents
+    const agents = allAgents.slice(0, 4);
+    const allServices = model.services.map(s => `"${s.name}"`);
+    const services = allServices.slice(0, 2); // Cap services too
+    const repos = [`"default"`];
     let cfg = `SPECIFICATION Spec\n\n`;
+    if (allAgents.length > agents.length) {
+        cfg += `\\* Note: Checking ${agents.length} of ${allAgents.length} agents for tractable verification\n`;
+    }
     cfg += `CONSTANTS\n`;
     cfg += `    Agents = {${agents.join(", ")}}\n`;
     cfg += `    Services = {${services.join(", ")}, "hub"}\n`;
@@ -283,21 +733,45 @@ export function generateTLCConfig(model, specName) {
     cfg += `    BufferBounded\n`;
     return cfg;
 }
+// ============================================================================
+// Write to Disk
+// ============================================================================
 /**
- * Write spec and config to disk, return paths
+ * Write spec and config to disk, return paths.
+ * Now writes BOTH v1 (orchestration) and v2 (planning loop) specs.
  */
 export function writeSpec(projectRoot, model, specName = "SystemSpec") {
     const specDir = join(projectRoot, ".jfl", "specs");
     mkdirSync(specDir, { recursive: true });
+    // v1: Orchestration spec
     const spec = generateTLASpec(model, specName);
     const cfg = generateTLCConfig(model, specName);
     const specPath = join(specDir, `${specName}.tla`);
     const cfgPath = join(specDir, `${specName}.cfg`);
     writeFileSync(specPath, spec);
     writeFileSync(cfgPath, cfg);
-    return { specPath, cfgPath };
+    const result = {
+        specPath,
+        cfgPath,
+    };
+    // v2: Planning loop spec
+    if (model.planningLoop) {
+        const plSpec = generatePlanningLoopSpec(model);
+        const plCfg = generatePlanningLoopConfig(model);
+        if (plSpec && plCfg) {
+            const plSpecPath = join(specDir, "PlanningLoop.tla");
+            const plCfgPath = join(specDir, "PlanningLoop.cfg");
+            writeFileSync(plSpecPath, plSpec);
+            writeFileSync(plCfgPath, plCfg);
+            result.planningSpecPath = plSpecPath;
+            result.planningCfgPath = plCfgPath;
+        }
+    }
+    return result;
 }
-// --- Helpers ---
+// ============================================================================
+// Helpers
+// ============================================================================
 function extractTomlValue(content, key) {
     const match = content.match(new RegExp(`${key}\\s*=\\s*"([^"]+)"`));
     return match ? match[1] : null;