loopforge 1.3.0 → 1.7.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,13 @@
   "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
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopforge",
-  "version": "1.3.0",
+  "version": "1.7.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

@@ -16,7 +16,7 @@ beyond having `loopforge-mcp` registered as an MCP server.
 ## 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,17 +26,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    │
-└─────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────┐
+│  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
@@ -57,18 +60,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 |
@@ -77,24 +100,36 @@ 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. |
+
+**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.
 
@@ -104,10 +139,12 @@ If the result has a non-null `prompt`, execute it and repeat from Step 2.
 |------|-------------|-----------|------------|
 | `loopforge_start` | Beginning of every loop | `task`, `maxRounds?`, `constraints?` | `sessionId`, round 1 `prompt` |
 | `loopforge_next` | After executing every round | `sessionId`, `output` (with eval block) | next `prompt` or `null` + `stopReason` |
-| `loopforge_status` | Mid-loop checkpoint, user asks "how's it going" | `sessionId` | `round`, `qualityTrajectory`, `status` |
+| `loopforge_status` | Mid-loop checkpoint, user asks "how's it going" | `sessionId` | `round`, `qualityTrajectory`, `status`, `technique` |
 | `loopforge_stop` | User wants to abort, fatal error | `sessionId` | `roundsCompleted`, final trajectory |
-| `loopforge_list` | User asks "what loops are running" | — | `sessions[]` |
+| `loopforge_list` | User asks "what loops are running" | — | `sessions[]` (includes vault-persisted) |
 | `loopforge_replay` | After loop ends, user asks "show me what happened" | `sessionId` | `timeline[]` with all rounds |
+| `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 |
 
 ## Quality Signals (Read the Room)
 
@@ -133,7 +170,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.
@@ -142,11 +180,14 @@ The prompt changes between rounds based on your trajectory. Pay attention to:
    narrow scope between rounds. Trust it — it sees the trajectory.
 5. **Call loopforge_next within the same turn.** Don't leave a round hanging
    across conversation turns. The MCP server is in-memory.
+6. **After process restart, use loopforge_resume.** The session state is saved
+   to vault every round. Call `loopforge_resume` with the original `loopId` to
+   pick up where you left off — no need to restart from round 1.
 
 ## 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",
@@ -154,33 +195,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/autonomous.d.ts

@@ -1,84 +0,0 @@
-/** LoopForge — Autonomous loop driver (v1.1).
- *
- *  Closes the feedback loop: compile → agent executes → extract self-eval →
- *  auto-feedback → compile next → ... until task complete or circuit breaker.
- *
- *  Zero API dependencies — LoopForge does NOT call AI APIs. The caller
- *  provides an execute callback or feeds agent output round by round.
- */
-import { type LoopHealth, type SelfEvaluation } from "./protocol.js";
-import { LoopForgeEngine } from "./engine.js";
-export interface AutonomousConfig {
-    /** The task description — becomes the loop objective. */
-    task: string;
-    /** Kebab-case loop identifier. */
-    loopId: string;
-    /** Optional explicit goal ID. Derived from task if omitted. */
-    goalId?: string;
-    /** Maximum rounds before forced stop. Default 20. */
-    maxRounds?: number;
-    /** Health check interval (rounds). Default 3. */
-    healthCheckInterval?: number;
-    /** Optional path to a plan/spec file for constraint extraction. */
-    planSource?: string;
-    /** Constraints extracted from the plan (provided by caller). */
-    constraintsFromPlan?: string[];
-    /** Domain hint for technique routing. */
-    domain?: string;
-}
-export interface RoundOutput {
-    round: number;
-    /** The compiled prompt — ready for agent execution. */
-    prompt: string;
-    /** L0 | L1 | L2 */
-    recompileLevel: string;
-    /** Selected prompting technique. */
-    techniqueUsed: string;
-    /** Cross-round health snapshot (null on round 1 if no prior data). */
-    health: LoopHealth | null;
-    /** Quality score from the PREVIOUS round (null on round 1). */
-    lastQualityScore: number | null;
-}
-export type StopReason = "task_complete" | "circuit_breaker" | "max_rounds" | "stalled" | "extraction_failed";
-export interface AutonomousResult {
-    /** Total rounds completed. */
-    roundsCompleted: number;
-    /** Why the loop stopped. */
-    stopReason: StopReason;
-    /** Health snapshot at stop. */
-    healthAtStop: LoopHealth | null;
-    /** Quality trajectory [round1_score, round2_score, ...]. */
-    qualityTrajectory: number[];
-    /** Whether the loop achieved its objective. */
-    success: boolean;
-}
-export interface RunOneRoundResult {
-    /** If stopNow is true, the loop should terminate. */
-    stopNow: boolean;
-    stopReason: StopReason | null;
-    /** The compiled prompt (null if stopping). */
-    roundOutput: RoundOutput | null;
-    /** Extracted self-evaluation (null on round 1 or if extraction failed). */
-    selfEval: SelfEvaluation | null;
-    /** Whether structured extraction succeeded. */
-    extractionSucceeded: boolean;
-}
-/** Run one round of the autonomous loop.
- *
- *  Round 1 (agentOutput = null): compile the first prompt (L2 full build).
- *  Round N (agentOutput = string): extract self-eval, record auto-feedback,
- *    compile next prompt (L0/L1/L2 decided by the 4-gate router).
- *
- *  Returns stopNow = true when the loop should terminate. */
-export declare function runOneRound(engine: LoopForgeEngine, config: AutonomousConfig, currentRound: number, agentOutput: string | null): RunOneRoundResult;
-/** Execute callback: takes a compiled prompt, returns the agent's output. */
-export type AgentExecutor = (prompt: string, round: number) => Promise<string>;
-/** Run a fully autonomous loop from start to finish.
- *
- *  The `execute` callback is called with each compiled prompt.
- *  LoopForge does NOT call any AI API — the caller provides execution.
- *
- *  Stops when: task complete, circuit breaker triggered, max rounds
- *  reached, or self-eval extraction fails. */
-export declare function runAutonomousLoop(engine: LoopForgeEngine, config: AutonomousConfig, execute: AgentExecutor): Promise<AutonomousResult>;
-//# sourceMappingURL=autonomous.d.ts.map

package/dist/autonomous.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"autonomous.d.ts","sourceRoot":"","sources":["../src/autonomous.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAKL,KAAK,UAAU,EACf,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,eAAe,EAIhB,MAAM,aAAa,CAAC;AAMrB,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAC1B,+DAA+D;IAC/D,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,MAAM,UAAU,GAClB,eAAe,GACf,iBAAiB,GACjB,YAAY,GACZ,SAAS,GACT,mBAAmB,CAAC;AAExB,MAAM,WAAW,gBAAgB;IAC/B,8BAA8B;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,4BAA4B;IAC5B,UAAU,EAAE,UAAU,CAAC;IACvB,+BAA+B;IAC/B,YAAY,EAAE,UAAU,GAAG,IAAI,CAAC;IAChC,4DAA4D;IAC5D,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;CAClB;AAMD,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,8CAA8C;IAC9C,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IAChC,2EAA2E;IAC3E,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAChC,+CAA+C;IAC/C,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;6DAM6D;AAC7D,wBAAgB,WAAW,CACzB,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,gBAAgB,EACxB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAAG,IAAI,GACzB,iBAAiB,CAwLnB;AAMD,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE/E;;;;;;8CAM8C;AAC9C,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,gBAAgB,CAAC,CAiE3B"}