loopforge 1.3.1 → 1.8.0

package/dist/verification-gate.js

@@ -0,0 +1,232 @@
+/** Verification Gate — Layer 1 cross-round consistency checks.
+ *
+ * Pure-function module. Validates an agent's SelfEvaluation against the
+ * loop's own lineage before it enters the compiler.
+ *
+ * Verdict semantics:
+ * - trusted:      all checks passed; flags are informational only.
+ * - suspect:      one or more warn-level flags; flags become warnings in
+ *                 the next prompt so the agent can clarify.
+ * - contradicted: one or more error-level flags; the quality score for
+ *                 this round is excluded from the quality trend (NOT
+ *                 modified). Flags become hard constraints — the agent
+ *                 must respond in the next round.
+ */
+import { makeVerificationFlag, makeVerificationResult } from "./protocol.js";
+// ═══════════════════════════════════════════════════════════════════════════
+// Helpers
+// ═══════════════════════════════════════════════════════════════════════════
+/** Extract the round number from a vault entry's loop_lineage.
+ *  Returns 0 if the entry has no lineage or no round field.
+ *  In practice, persistLoopLineage always writes round ≥ 1, so 0
+ *  unambiguously means "not a valid round entry" in this context. */
+function entryRound(entry) {
+    const lineage = (entry.loop_lineage ?? {});
+    return lineage.round ?? 0;
+}
+/** Read constraint_violations from a vault entry (entry-level, stored from
+ *  the previous round's last_round_result at persist time). */
+function entryViolations(entry) {
+    const viols = entry.constraint_violations;
+    if (Array.isArray(viols))
+        return viols.filter((v) => typeof v === "string");
+    return [];
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Individual checks — each returns a VerificationFlag or null
+// ═══════════════════════════════════════════════════════════════════════════
+function checkProgressRegression(selfEval, prevSelfEval) {
+    if (!prevSelfEval?.execution_evidence)
+        return null;
+    if (!selfEval.execution_evidence)
+        return null;
+    const prevProgress = prevSelfEval.execution_evidence.progress_estimate;
+    const currProgress = selfEval.execution_evidence.progress_estimate;
+    if (typeof prevProgress !== "number" || typeof currProgress !== "number")
+        return null;
+    // Use delta with epsilon to avoid IEEE 754 rounding issues (0.8 - 0.2 > 0.6 in float)
+    if (prevProgress - currProgress <= 0.2 + 1e-10)
+        return null;
+    return makeVerificationFlag({
+        severity: "warn",
+        field: "progress_estimate",
+        check: "progress_regression",
+        detail: `Progress dropped from ${prevProgress.toFixed(2)} to ` +
+            `${currProgress.toFixed(2)} (delta: ${(currProgress - prevProgress).toFixed(2)})`,
+    });
+}
+function checkEmptyChangeWithPassing(selfEval) {
+    const ev = selfEval.execution_evidence;
+    if (!ev)
+        return null;
+    const filesEmpty = ev.files_changed.length === 0;
+    const testsAllPass = ev.test_results !== null &&
+        ev.test_results.failed === 0 &&
+        ev.test_results.passed > 0;
+    if (!filesEmpty || !testsAllPass || !selfEval.success)
+        return null;
+    return makeVerificationFlag({
+        severity: "warn",
+        field: "execution_evidence",
+        check: "empty_change_with_passing",
+        detail: "Agent claims success with no files changed and all tests passing — " +
+            "verify that work was actually performed",
+    });
+}
+function checkSuccessWithRemainingCriteria(selfEval) {
+    if (!selfEval.success)
+        return null;
+    const remaining = selfEval.execution_evidence?.success_criteria_remaining;
+    if (!remaining || remaining.length === 0)
+        return null;
+    return makeVerificationFlag({
+        severity: "error",
+        field: "success",
+        check: "success_with_remaining_criteria",
+        detail: `Agent claims success but ${remaining.length} criteria remain unmet: ` +
+            remaining.slice(0, 3).join("; "),
+    });
+}
+function checkDuplicateConstraintDiscovery(selfEval, prevSelfEval, olderViolations) {
+    const discovered = selfEval.discovered_constraints;
+    if (!discovered || discovered.length === 0)
+        return null;
+    // Collect all previously-known constraints
+    const known = new Set();
+    for (const v of olderViolations)
+        known.add(v.toLowerCase().trim());
+    if (prevSelfEval) {
+        for (const d of prevSelfEval.discovered_constraints ?? []) {
+            known.add(d.toLowerCase().trim());
+        }
+        // Also treat previous violations as implicitly discovered
+        for (const v of prevSelfEval.constraint_violations) {
+            known.add(v.toLowerCase().trim());
+        }
+    }
+    for (const d of discovered) {
+        if (known.has(d.toLowerCase().trim())) {
+            return makeVerificationFlag({
+                severity: "warn",
+                field: "discovered_constraints",
+                check: "duplicate_constraint_discovery",
+                detail: `Constraint "${d}" was already known from a previous round`,
+            });
+        }
+    }
+    return null;
+}
+function checkRecurringViolation(selfEval, prevSelfEval, vaultEntries, currentRound) {
+    const currViols = selfEval.constraint_violations;
+    if (!currViols || currViols.length === 0)
+        return null;
+    // Build the violation history: [round N-2, round N-1, round N]
+    const violationsByRound = [];
+    // Round N-2 violations come from the vault entry for round N-1
+    // (persistLoopLineage stores the PREVIOUS round's violations on each entry)
+    if (currentRound >= 3) {
+        const entryNMinus1 = vaultEntries.find((e) => entryRound(e) === currentRound - 1);
+        if (entryNMinus1) {
+            const viols = entryViolations(entryNMinus1);
+            if (viols.length)
+                violationsByRound.push(viols.map((v) => v.toLowerCase().trim()));
+        }
+    }
+    // Round N-1 violations from prevSelfEval
+    if (prevSelfEval) {
+        const prevViols = prevSelfEval.constraint_violations;
+        violationsByRound.push(prevViols.map((v) => v.toLowerCase().trim()));
+    }
+    // Round N violations from current selfEval
+    violationsByRound.push(currViols.map((v) => v.toLowerCase().trim()));
+    // Need at least 3 rounds of data
+    if (violationsByRound.length < 3)
+        return null;
+    // Check each current violation against the previous 2 rounds
+    const [rNMinus2, rNMinus1, rN] = violationsByRound.slice(-3);
+    for (const v of rN) {
+        if (rNMinus1.includes(v) && rNMinus2.includes(v)) {
+            return makeVerificationFlag({
+                severity: "error",
+                field: "constraint_violations",
+                check: "recurring_violation",
+                detail: `Constraint violation "${v}" has appeared in 3 consecutive rounds ` +
+                    `(rounds ${currentRound - 2}–${currentRound}) without resolution`,
+            });
+        }
+    }
+    return null;
+}
+function checkRetractFreshConstraint(selfEval, prevSelfEval, currentRound) {
+    const retracted = selfEval.retracted_constraints;
+    if (!retracted || retracted.length === 0)
+        return null;
+    if (!prevSelfEval)
+        return null;
+    const lastRoundDiscoveries = new Set();
+    for (const d of prevSelfEval.discovered_constraints ?? []) {
+        lastRoundDiscoveries.add(d.toLowerCase().trim());
+    }
+    for (const r of retracted) {
+        if (lastRoundDiscoveries.has(r.toLowerCase().trim())) {
+            return makeVerificationFlag({
+                severity: "warn",
+                field: "retracted_constraints",
+                check: "retract_fresh_constraint",
+                detail: `Retracting constraint "${r}" that was just discovered in round ` +
+                    `${currentRound - 1} — may indicate rapid flip-flopping`,
+            });
+        }
+    }
+    return null;
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// Main entry point
+// ═══════════════════════════════════════════════════════════════════════════
+/** Verify a SelfEvaluation against the loop's cross-round lineage.
+ *
+ * @param selfEval      The agent's self-evaluation for the current round.
+ * @param currentRound  The current round number (1-based).
+ * @param vaultEntries  Vault entries for this loop (non-feedback only).
+ * @param prevSelfEval  The agent's self-evaluation from the previous round
+ *                      (null for round 1).
+ */
+export function verifySelfEvaluation(selfEval, currentRound, vaultEntries, prevSelfEval = null) {
+    const flags = [];
+    // Collect violations from all previous vault entries for duplicate-discovery
+    // and other checks that need deeper history.
+    const olderViolations = [];
+    for (const entry of vaultEntries) {
+        for (const v of entryViolations(entry))
+            olderViolations.push(v);
+    }
+    // Run all checks
+    const checks = [
+        () => checkProgressRegression(selfEval, prevSelfEval),
+        () => checkEmptyChangeWithPassing(selfEval),
+        () => checkSuccessWithRemainingCriteria(selfEval),
+        () => checkDuplicateConstraintDiscovery(selfEval, prevSelfEval, olderViolations),
+        () => checkRecurringViolation(selfEval, prevSelfEval, vaultEntries, currentRound),
+        () => checkRetractFreshConstraint(selfEval, prevSelfEval, currentRound),
+    ];
+    for (const run of checks) {
+        const flag = run();
+        if (flag)
+            flags.push(flag);
+    }
+    // Determine verdict from the most severe flag present
+    const hasError = flags.some((f) => f.severity === "error");
+    const hasWarn = flags.some((f) => f.severity === "warn");
+    let verdict;
+    if (hasError) {
+        verdict = "contradicted";
+    }
+    else if (hasWarn) {
+        verdict = "suspect";
+    }
+    else {
+        verdict = "trusted";
+    }
+    return makeVerificationResult({ verdict, flags });
+}
+//# sourceMappingURL=verification-gate.js.map

package/dist/verification-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification-gate.js","sourceRoot":"","sources":["../src/verification-gate.ts"],"names":[],"mappings":"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"}

package/loop_policy.json

@@ -47,5 +47,36 @@
   "backend": {
     "vault_path": ".promptcraft/prompt_vault.json",
     "global_vault_path": "~/.promptcraft/global_vault.json"
+  },
+  "evolution": {
+    "max_discovered_constraints_per_round": 5,
+    "max_active_constraints": 15,
+    "max_objective_versions": 10,
+    "progress_stall_threshold": 0.05,
+    "progress_stall_rounds": 2,
+    "progress_mismatch_threshold": 0.3
+  },
+  "memory_injection": {
+    "enabled": true,
+    "min_rounds_between_injections": 1,
+    "phase_thresholds": {
+      "phase1": { "trigger": "round_1" },
+      "phase2": { "trigger": "progress", "threshold": 0.40 },
+      "phase3": { "trigger": "progress", "threshold": 0.70 }
+    },
+    "round_tiers": [
+      { "max_rounds": 10, "allowed_phases": [1] },
+      { "max_rounds": 20, "allowed_phases": [1, 3] },
+      { "max_rounds": 30, "allowed_phases": [1, 2, 3] }
+    ],
+    "dedup_threshold": 0.6,
+    "max_context_length": 2000,
+    "section_title": "### Background Context (Long-Term Memory)"
+  },
+  "memory_writeback": {
+    "enabled": true,
+    "max_feedback_entries": 5,
+    "max_discoveries_in_project": 3,
+    "write_on_outcomes": ["completed", "circuit_breaker", "max_rounds"]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopforge",
-  "version": "1.3.1",
+  "version": "1.8.0",
   "description": "Loop-Time Intelligence Layer for AI coding agents — per-iteration prompt compiler with structured memory, constraint inheritance, and drift correction.",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,7 +24,6 @@
     }
   },
   "bin": {
-    "loopforge": "./dist/cli.js",
     "loopforge-mcp": "./dist/mcp-server.js"
   },
   "files": [

package/skills/perception/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: perception
-description: Multi-round autonomous loop driver powered by LoopForge MCP. Compiles context-aware prompts per iteration, tracks quality, inherits constraints, and stops when work is done — not when rounds run out.
+description: Multi-round autonomous loop driver powered by LoopForge MCP. Compiles context-aware prompts per iteration, tracks quality, inherits constraints, and stops when work is done — not when rounds run out. Supports single-agent and multi-agent (AgentTool / Coordinator) scenarios.
 ---
 
 # Perception — Loop-Time Intelligence Skill
@@ -13,10 +13,15 @@ detection — maintaining cognitive stability across long-horizon loops.
 Works with Claude Code, Codex, and any MCP-capable host. Zero configuration
 beyond having `loopforge-mcp` registered as an MCP server.
 
+**Multi-Agent:** When you spawn sub-agents (AgentTool) or orchestrate Workers
+(Coordinator mode), LoopForge tracks delegation history, inherits constraints
+across Workers, and injects structured summaries into subsequent prompts.
+No separate mode required — LoopForge treats all agents the same.
+
 ## When to Activate
 
 Activate when the user says any of:
-- `/loop <task>` — start an autonomous multi-round loop
+- `/perception <task>` — start an autonomous multi-round loop
 - "do this in a loop", "keep going until done", "iterate on this"
 - Any task that clearly needs 3+ rounds (audit, refactor, migrate, review-and-fix cycles)
 
@@ -26,20 +31,20 @@ round (e.g. "audit the entire codebase and fix every issue").
 ## Core Workflow
 
 ```
-┌─────────────────────────────────────────────────────┐
-│  1. loopforge_start(task, constraints, maxRounds)    │
-│     → sessionId + Round 1 prompt                     │
-│                                                      │
-│  2. Execute the prompt (read, write, test, fix)      │
-│     MUST include ---loopforge-eval block in output   │
-│                                                      │
-│  3. loopforge_next(sessionId, output)                │
-│     → if prompt: go to step 2                        │
-│     → if prompt=null: loop ended, read stopReason    │
-│                                                      │
-│  After restart: loopforge_resume(loopId)             │
-│     → picks up from last saved round                 │
-└─────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────┐
+│  1. loopforge_start(task, constraints, maxRounds)         │
+│     → sessionId + Round 1 prompt                          │
+│                                                           │
+│  2. Execute the prompt (read, write, test, fix)           │
+│     Prepare a structured self-evaluation                  │
+│                                                           │
+│  3. loopforge_next(sessionId, evaluation, output?)        │
+│     → if prompt: go to step 2                             │
+│     → if prompt=null: loop ended, read stopReason         │
+│                                                           │
+│  After restart: loopforge_resume(loopId)                  │
+│     → picks up from last saved round                      │
+└──────────────────────────────────────────────────────────┘
 ```
 
 ### Step-by-step
@@ -60,18 +65,38 @@ Execute the compiled prompt exactly as you would any user task. Read files,
 write code, run tests, fix bugs. The prompt already contains the task scope,
 constraints, and quality expectations for this specific round.
 
-**CRITICAL: Every round's output MUST end with a self-evaluation block:**
-```
----loopforge-eval
+After executing, prepare a structured self-evaluation. Pass it as the
+`evaluation` parameter to `loopforge_next` — do NOT embed it as a text block
+in the output. The `evaluation` parameter is a typed object with the fields
+described below.
+
+**New (v1.7+): Pass evaluation as a structured tool parameter.**
+```json
 {
   "success": true,
   "output_summary": "Fixed 3 reentrancy bugs in withdraw() and deposit(). All 12 tests pass.",
   "constraint_violations": [],
-  "should_continue": true
+  "should_continue": true,
+  "discovered_constraints": [],
+  "objective_refinement": "",
+  "emerged_subtasks": [],
+  "execution_evidence": {
+    "files_changed": ["contracts/Token.sol", "test/Token.test.ts"],
+    "test_results": {"passed": 24, "failed": 0, "skipped": 0},
+    "success_criteria_met": ["No reentrancy vectors remain"],
+    "success_criteria_remaining": ["Access control verified", "Overflow checks complete"],
+    "progress_estimate": 0.4
+  },
+  "retracted_constraints": [],
+  "revised_success_criteria": [],
+  "wrong_assumptions": []
 }
----end-loopforge-eval
 ```
 
+**Legacy (still supported):** Embed a `---loopforge-eval` block in output text
+when the agent cannot pass structured tool parameters. The new parameter form
+is preferred — it's validated by the MCP client before reaching the server.
+
 **Field rules:**
 
 | Field | Type | Rule |
@@ -80,24 +105,37 @@ constraints, and quality expectations for this specific round.
 | `output_summary` | string | Specific, actionable. What was DONE this round — not what was attempted |
 | `constraint_violations` | string[] | Constraints the agent actually violated this round. Be honest — hiding violations corrupts the quality signal and defeats the circuit breaker |
 | `should_continue` | boolean | `false` ONLY when the ENTIRE task is complete. Partial progress = `true` |
-
-**Why this matters:** Without a valid `---loopforge-eval` block, extraction
-fails and the loop stops with `stopReason: stalled`. The circuit breaker
-uses `success` + `violations` to compute quality scores — lying here defeats
-the only mechanism that prevents infinite loops.
+| `discovered_constraints` | string[] | **P0 (optional)** — New constraints discovered this round. They become active guardrails for future rounds. Example: `["All external calls must use SafeERC20"]`. Empty `[]` if none. |
+| `objective_refinement` | string | **P1 (optional)** — If this round deepened your understanding of what the task is really about, describe the refinement. APPENDED to (never replaces) the original objective. Empty `""` if unchanged. |
+| `emerged_subtasks` | string[] | **P2 (optional)** — Sub-problems that surfaced during execution and need separate attention. Feed into next-round task suggestions. Example: `["Audit upgrade proxy", "Verify timelock"]`. Empty `[]` if none. |
+| `execution_evidence` | object | **P4 (recommended)** — Structured record of what actually happened. `files_changed` (string[]), `test_results` ({passed, failed, skipped} | null), `success_criteria_met` (string[]), `success_criteria_remaining` (string[]), `progress_estimate` (0.0–1.0). Use this to give LoopForge real visibility into your progress. |
+| `retracted_constraints` | string[] | **P5 (optional)** — Constraints you now believe are wrong. Removed from active guardrails. Only retract with evidence. Empty `[]` if none. |
+| `revised_success_criteria` | object[] | **P5 (optional)** — Success criteria that need reformulation. Array of `{old: string, new: string}`. Applied to Loop Objective. Empty `[]` if none. |
+| `wrong_assumptions` | string[] | **P5 (optional)** — Assumptions from earlier rounds that turned out to be incorrect. Recorded as key lessons. Empty `[]` if none. |
+| `worker_results` | object[] | **Multi-Agent (optional)** — Results of sub-agent / Worker delegations this round. Each entry: `{ agentId, subAgentType, subTask, resultSummary, success, discoveredConstraints? }`. Engine auto-records to delegation journal. Empty `[]` if no delegations. |
+
+**Why this matters:** The evaluation is validated by the MCP client before
+reaching the server — a missing or malformed evaluation causes an immediate
+error, not a silent stall. The circuit breaker uses `success` + `violations`
+to compute quality scores — lying here defeats the only mechanism that
+prevents infinite loops. The optional fields (P0–P5) enable cognitive
+evolution: discovering constraints, deepening understanding, surfacing
+sub-problems, tracking real progress, and correcting wrong assumptions as
+the loop executes.
 
 **Step 3 — Advance to next round:**
 ```
 Call loopforge_next with:
-  sessionId: from loopforge_start
-  output:    your FULL output from this round (including the eval block)
+  sessionId:  from loopforge_start
+  evaluation: REQUIRED — structured self-evaluation object (see field table below)
+  output:     OPTIONAL — raw output text for audit trail (can be omitted)
 ```
 
 If the result has `prompt: null`, the loop has ended. Read `stopReason`:
 - `task_complete` — you reported should_continue=false. Work is done.
 - `circuit_breaker` — quality flat or declining for 3+ rounds. Review your approach.
 - `max_rounds` — hit the round limit. Decide whether to extend or accept.
-- `stalled` — no valid self-eval block found. Check your output format.
+- `stalled` — no valid self-evaluation provided. Check your evaluation parameter.
 
 If the result has a non-null `prompt`, execute it and repeat from Step 2.
 
@@ -114,6 +152,51 @@ If the result has a non-null `prompt`, execute it and repeat from Step 2.
 | `loopforge_resume` | Resume a loop after process restart | `loopId` | next `prompt` or `null` + `stopReason` |
 | `loopforge_health` | Check loop health mid-run | `loopId` | goal alignment, constraint integrity, drift, strategy |
 
+## Delegation Helpers (AgentTool Mode)
+
+When you spawn sub-agents via `AgentTool` (Explore, General-purpose, Plan)
+during a loop round, use these helpers to improve delegation quality:
+
+**Before delegating:**
+1. **Filter constraints** — not all active constraints apply to every sub-agent.
+   An Explore agent searching for deprecated APIs doesn't need "all files must
+   have a license header." Use `filterConstraintsForSubTask(allConstraints, subTask)`
+   to get only the relevant subset.
+2. **Format the prompt** — use `formatDelegationPrompt(subTask, subAgentType,
+   relevantConstraints, options?)` to produce a self-contained prompt. This is
+   critical: sub-agents cannot see your conversation. Every prompt must stand
+   alone — no "based on above," no "continue from previous."
+
+**After delegating (in your self-evaluation):**
+Include `worker_results` in your evaluation to record what you delegated.
+The engine auto-detects this field and writes delegation journals to the vault:
+
+```json
+{
+  "worker_results": [
+    {
+      "agentId": "abc123",
+      "subAgentType": "explore",
+      "subTask": "Search for deprecated API usage in src/",
+      "resultSummary": "Found 12 deprecated calls across 8 files",
+      "success": true,
+      "discoveredConstraints": ["All API calls must be versioned"]
+    }
+  ]
+}
+```
+
+This feeds into the delegation history table displayed in future rounds.
+Constraints discovered by sub-agents flow into the active constraint set
+automatically — they appear in future prompts alongside main-agent constraints.
+Delegation recording is lightweight — it's the main agent's memory,
+not sub-agent memory.
+
+**Important:** These helpers are optional. If your sub-task is trivial (e.g.
+"read file X and report line 42"), a raw prompt is fine. Use the helpers when
+sub-tasks involve constraints, specific output formats, or results worth
+remembering across rounds.
+
 ## Quality Signals (Read the Room)
 
 The prompt changes between rounds based on your trajectory. Pay attention to:
@@ -138,7 +221,8 @@ The prompt changes between rounds based on your trajectory. Pay attention to:
 
 ## Rules
 
-1. **Never skip the eval block.** No exceptions. If you forget, the loop stalls.
+1. **Always pass the evaluation parameter.** `loopforge_next` requires it.
+   If you omit it, the MCP client will reject the call with a schema error.
 2. **Be honest in self-evaluation.** Lying about success or hiding violations
    produces a false quality signal. The circuit breaker exists to stop bad
    loops — if you fake quality=5 every round, it fires anyway.
@@ -154,7 +238,7 @@ The prompt changes between rounds based on your trajectory. Pay attention to:
 ## Example
 
 ```
-User: /loop "Audit the ERC20 token in contracts/Token.sol for security issues"
+User: /perception "Audit the ERC20 token in contracts/Token.sol for security issues"
 
 Agent:
   → loopforge_start({ task: "Audit ERC20 token in contracts/Token.sol for security issues",
@@ -162,33 +246,41 @@ Agent:
                        constraints: ["must not break existing tests", "follow check-effects-interactions"] })
   ← { sessionId: "abc-123", round: 1, prompt: "## LoopForge Loop Compile — Round 1\n...", level: "l2" }
 
-  [Executes prompt: reads Token.sol, identifies 4 issues, writes audit notes]
-
-  Output ends with:
-  ---loopforge-eval
-  {"success":false,"output_summary":"Found 4 potential issues: 2 reentrancy, 1 overflow, 1 access control. Not yet fixed.","constraint_violations":[],"should_continue":true}
-  ---end-loopforge-eval
+  [Executes prompt: reads Token.sol, identifies 4 issues, discovers a new constraint]
 
-  → loopforge_next({ sessionId: "abc-123", output: <full output> })
+  → loopforge_next({ sessionId: "abc-123",
+      evaluation: {
+        success: false,
+        output_summary: "Found 4 potential issues: 2 reentrancy, 1 overflow, 1 access control. Not yet fixed.",
+        constraint_violations: [],
+        should_continue: true,
+        discovered_constraints: ["All _mint() calls must emit Transfer event per ERC20 spec"]
+      } })
   ← { sessionId: "abc-123", round: 2, prompt: "## LoopForge Loop Compile — Round 2\n...", level: "l1" }
 
-  [Executes prompt: fixes 3 issues, 1 needs more investigation]
-
-  ---loopforge-eval
-  {"success":false,"output_summary":"Fixed reentrancy in withdraw() and overflow in calcReward(). Access control issue in setOwner() needs design discussion.","constraint_violations":[],"should_continue":true}
-  ---end-loopforge-eval
-
-  → loopforge_next({ sessionId: "abc-123", output: <full output> })
-  ← { sessionId: "abc-123", round: 3, prompt: "## LoopForge Loop Compile — Round 3\n...", level: "l0" }
-
-  [Executes prompt: documents access control issue for user decision, all fixes pass tests]
-
-  ---loopforge-eval
-  {"success":true,"output_summary":"All fixable issues resolved. 1 access control design question flagged for user. 24/24 tests pass.","constraint_violations":[],"should_continue":false}
-  ---end-loopforge-eval
-
-  → loopforge_next({ sessionId: "abc-123", output: <full output> })
+  [Executes prompt: fixes 3 issues, deepens understanding of access control problem]
+
+  → loopforge_next({ sessionId: "abc-123",
+      evaluation: {
+        success: false,
+        output_summary: "Fixed reentrancy in withdraw() and overflow in calcReward(). Access control in setOwner() needs design discussion — discovered it's part of a larger upgradeability concern.",
+        constraint_violations: [],
+        should_continue: true,
+        objective_refinement: "Access control audit scope expanded: setOwner() is unprotected because the contract follows an upgradeable proxy pattern where owner is set via initializer — need to verify the initializer guard and proxy admin separately",
+        emerged_subtasks: ["Audit upgrade proxy initialization flow", "Verify proxy admin is not renounced without recovery path"]
+      } })
+  ← { sessionId: "abc-123", round: 3, prompt: "## LoopForge Loop Compile — Round 3\n  Suggested Next Task: Audit upgrade proxy initialization flow; Verify proxy admin is not renounced without recovery path\n...", level: "l0" }
+
+  [Executes prompt: audits proxy pattern, documents findings, all fixes pass tests]
+
+  → loopforge_next({ sessionId: "abc-123",
+      evaluation: {
+        success: true,
+        output_summary: "All fixable issues resolved. Proxy initialization verified — initializer modifier prevents double-init. Proxy admin held by multisig — low risk. 24/24 tests pass.",
+        constraint_violations: [],
+        should_continue: false
+      } })
   ← { sessionId: "abc-123", round: 3, prompt: null, stopReason: "task_complete", quality: 5 }
 
-  Reports to user: "Audit complete in 3 rounds. 3 issues fixed, 1 design question flagged."
+  Reports to user: "Audit complete in 3 rounds. 3 issues fixed, 1 design question flagged. Discovered 1 new constraint during audit. Objective deepened to include proxy pattern verification."
 ```

package/dist/adapter.d.ts

@@ -1,17 +0,0 @@
-/** LoopForge-loop_compile — Sub-agent adapter (unified entry point).
- *
- * This is the single entry point when LoopForge is invoked as a sub-agent.
- * It wraps the Engine, routes by mode, and always prepends a compact health line.
- *
- * Three modes (v1.0):
- *     loop_compile — Per-iteration prompt compiler (primary entry point)
- *     feedback     — Record execution results → quality scoring → vault persistence
- *     review       — Audit prompt quality (structural checks + constraint compliance)
- *
- * build is an internal path (loop_compile L2 delegation) — not an exposed mode.
- */
-import { type LoopForgeRequest } from "./protocol.js";
-import { LoopForgeEngine } from "./engine.js";
-export declare function handle(requestInput: string | Record<string, unknown> | LoopForgeRequest, engine?: LoopForgeEngine): string;
-export declare function main(): void;
-//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAKL,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,eAAe,EAGhB,MAAM,aAAa,CAAC;AAiBrB,wBAAgB,MAAM,CACpB,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,gBAAgB,EACjE,MAAM,CAAC,EAAE,eAAe,GACvB,MAAM,CAwER;AAsJD,wBAAgB,IAAI,IAAI,IAAI,CA8B3B"}