loopforge 3.9.4 → 4.0.7

package/dist/workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAiC5E;AAED;;;;;;;0CAO0C;AAC1C,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO7D"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAiC5E"}

package/dist/workspace.js

@@ -58,21 +58,4 @@ export function containInWorkspace(workspace, target) {
     }
     return projected;
 }
-/** v3.8.1: the Contract scope-entry check, in the module that owns workspace
- *  containment.
- *
- *  It lives here rather than in the MCP transport because it is a filesystem
- *  fact about the running process, not a property of the payload: the strict
- *  contract boundary injects it so a declared scope entry that escapes the
- *  workspace is rejected pre-advance. Returns the reason when the entry
- *  escapes, null when it is contained. */
-export function scopeEntryDetail(entry) {
-    try {
-        containInWorkspace(process.cwd(), entry);
-        return null;
-    }
-    catch (error) {
-        return error instanceof Error ? error.message : "leaves the workspace";
-    }
-}
 //# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAE/D;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAiB,EAAE,MAAc;IAClE,MAAM,aAAa,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,OAAO,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;IAC/C,MAAM,eAAe,GAAG,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IACzD,IACE,eAAe,KAAK,IAAI,IAAI,eAAe,CAAC,UAAU,CAAC,KAAK,GAAG,EAAE,CAAC;QAClE,UAAU,CAAC,eAAe,CAAC,EAC3B,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC/C,CAAC;IACD,qEAAqE;IACrE,yEAAyE;IACzE,qEAAqE;IACrE,yDAAyD;IACzD,IAAI,QAAQ,GAAG,OAAO,CAAC;IACvB,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACvC,IAAI,MAAM,KAAK,QAAQ;YAAE,MAAM;QAC/B,QAAQ,GAAG,MAAM,CAAC;IACpB,CAAC;IACD,IAAI,QAAQ,KAAK,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACjD,oEAAoE;QACpE,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;IAC/E,MAAM,YAAY,GAAG,QAAQ,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;IACxD,IACE,YAAY,KAAK,IAAI,IAAI,YAAY,CAAC,UAAU,CAAC,KAAK,GAAG,EAAE,CAAC;QAC5D,UAAU,CAAC,YAAY,CAAC,EACxB,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;0CAO0C;AAC1C,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,IAAI,CAAC;QACH,kBAAkB,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,KAAK,CAAC,CAAC;QACzC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,sBAAsB,CAAC;IACzE,CAAC;AACH,CAAC"}
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAE/D;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAiB,EAAE,MAAc;IAClE,MAAM,aAAa,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,OAAO,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;IAC/C,MAAM,eAAe,GAAG,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IACzD,IACE,eAAe,KAAK,IAAI,IAAI,eAAe,CAAC,UAAU,CAAC,KAAK,GAAG,EAAE,CAAC;QAClE,UAAU,CAAC,eAAe,CAAC,EAC3B,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC/C,CAAC;IACD,qEAAqE;IACrE,yEAAyE;IACzE,qEAAqE;IACrE,yDAAyD;IACzD,IAAI,QAAQ,GAAG,OAAO,CAAC;IACvB,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACvC,IAAI,MAAM,KAAK,QAAQ;YAAE,MAAM;QAC/B,QAAQ,GAAG,MAAM,CAAC;IACpB,CAAC;IACD,IAAI,QAAQ,KAAK,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACjD,oEAAoE;QACpE,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;IAC/E,MAAM,YAAY,GAAG,QAAQ,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;IACxD,IACE,YAAY,KAAK,IAAI,IAAI,YAAY,CAAC,UAAU,CAAC,KAAK,GAAG,EAAE,CAAC;QAC5D,UAAU,CAAC,YAAY,CAAC,EACxB,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/loop_policy.json

@@ -1,16 +1,10 @@
 {
-  "version": "6",
-  "constraints": {
-    "retire_window": 3
-  },
-  "summary": {
-    "window": 5,
-    "milestone_interval": 20
-  },
+  "version": "10",
   "engine": {
     "stall_lookback_rounds": 3,
     "max_rounds": 200,
     "enforcement_escalation_enabled": true,
+    "agent_recovery_enabled": true,
     "backtrack_enabled": true,
     "backtrack_max_depth": 3,
     "backtrack_preserve_discoveries": true,
@@ -18,12 +12,8 @@
   },
   "prompt": {
     "l0_max_chars": 5000,
-    "l1_max_chars": 10000,
-    "l2_max_chars": 18000,
-    "l2_pointer_enabled": true,
-    "max_emphasize_l2": 5,
-    "max_emphasize_l1": 3,
-    "max_confusion_points": 3
+    "l1_max_chars": 50000,
+    "l2_max_chars": 100000
   },
   "backend": {
     "root_dir": ".loopforge"
@@ -31,12 +21,8 @@
   "evolution": {
     "max_discovered_constraints_per_round": 5,
     "max_start_criteria": 12,
-    "max_objective_versions": 10,
     "max_active_subgoals": 12
   },
-  "checkpoint": {
-    "outcome_max_chars": 200
-  },
   "state_file": {
     "enabled": true,
     "directory": ".loopforge/state"

package/package.json

@@ -1,68 +1,68 @@
-{
-  "name": "loopforge",
-  "version": "3.9.4",
-  "description": "External cognitive infrastructure for AI coding agents — breaks the summary cascade, provides independent verification, and enables model-directed prompt prioritization for 100+ round agent loops.",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    },
-    "./compiler": {
-      "import": "./dist/loop-compiler.js",
-      "types": "./dist/loop-compiler.d.ts"
-    },
-    "./replay": {
-      "import": "./dist/replay.js",
-      "types": "./dist/replay.d.ts"
-    },
-    "./mcp": {
-      "import": "./dist/mcp/server.js",
-      "types": "./dist/mcp/server.d.ts"
-    }
-  },
-  "bin": {
-    "loopforge": "dist/cli.js"
-  },
-  "files": [
-    "dist/",
-    "!dist/tests/",
-    "skills",
-    "loop_policy.json",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "node scripts/sync-version.mjs && tsc && node scripts/trim-dist.mjs && node dist/generate-schema.js && node scripts/trim-dist.mjs",
-    "generate-schema": "node scripts/sync-version.mjs && tsc && node scripts/trim-dist.mjs && node dist/generate-schema.js && node scripts/trim-dist.mjs",
-    "test": "node scripts/sync-version.mjs && tsc && node scripts/trim-dist.mjs && node dist/generate-schema.js && node scripts/trim-dist.mjs && node --test --test-concurrency=1 dist/tests/*.test.js",
-    "test:watch": "node scripts/sync-version.mjs && tsc && node scripts/trim-dist.mjs && node --test --watch dist/tests/*.test.js",
-    "check": "node scripts/sync-version.mjs && tsc --noEmit",
-    "verify:artifacts": "node scripts/verify-artifacts.mjs",
-    "measure:boundary": "node scripts/measure-boundary.mjs",
-    "prepack": "npm run verify:artifacts && npm run build"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/kyrielrving11/LoopForge.git"
-  },
-  "keywords": [
-    "cognitive-state",
-    "ai-agent",
-    "durable-agent",
-    "claude-code",
-    "llm",
-    "cognitive-stability",
-    "constraint-management",
-    "mcp"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "license": "MIT",
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.4.0"
-  }
-}
+{
+  "name": "loopforge",
+  "version": "4.0.7",
+  "description": "Durable round runtime for coding agents with committed history, machine evidence, and agent-directed recovery.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./compiler": {
+      "import": "./dist/loop-compiler.js",
+      "types": "./dist/loop-compiler.d.ts"
+    },
+    "./replay": {
+      "import": "./dist/replay.js",
+      "types": "./dist/replay.d.ts"
+    },
+    "./mcp": {
+      "import": "./dist/mcp/server.js",
+      "types": "./dist/mcp/server.d.ts"
+    }
+  },
+  "bin": {
+    "loopforge": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "!dist/tests/",
+    "skills",
+    "loop_policy.json",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/sync-version.mjs && tsc && node scripts/trim-dist.mjs && node dist/generate-schema.js && node scripts/trim-dist.mjs",
+    "generate-schema": "node scripts/sync-version.mjs && tsc && node scripts/trim-dist.mjs && node dist/generate-schema.js && node scripts/trim-dist.mjs",
+    "test": "node scripts/sync-version.mjs && tsc && node scripts/trim-dist.mjs && node dist/generate-schema.js && node scripts/trim-dist.mjs && node --test --test-concurrency=1 dist/tests/*.test.js",
+    "test:watch": "node scripts/sync-version.mjs && tsc && node scripts/trim-dist.mjs && node --test --watch dist/tests/*.test.js",
+    "check": "node scripts/sync-version.mjs && tsc --noEmit",
+    "verify:artifacts": "node scripts/verify-artifacts.mjs",
+    "measure:boundary": "node scripts/measure-boundary.mjs",
+    "prepack": "npm run verify:artifacts && npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kyrielrving11/LoopForge.git"
+  },
+  "keywords": [
+    "cognitive-state",
+    "ai-agent",
+    "durable-agent",
+    "claude-code",
+    "llm",
+    "cognitive-stability",
+    "constraint-management",
+    "mcp"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  }
+}

package/skills/forge/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: forge
+description: "LoopForge user manual: drive multi-round coding tasks through LoopForge MCP so objectives, constraints, evidence, and decisions survive context loss and restarts. The external Agent remains responsible for planning, file changes, tools, and execution. Not for one-pass edits."
+when_to_use: "多轮任务, 长任务, 上下文压缩, 上下文丢失, 断点续跑, 会话恢复, 可审计过程, 机器验证, 漂移, 回滚, LoopForge, long-running coding task, multi-round, context loss, resume, machine-verified, auditable evidence, backtrack, drift"
+dispatch_intent: "Drive long-running coding work through LoopForge so it survives restarts and is machine-verified round by round"
+---
+
+# Forge
+
+Use this skill when work needs more than one verified boundary. It is the
+operating guide for LoopForge MCP; it does not replace the MCP server instructions,
+the prompt's `## Round Boundary`, or live `submission_guidance`.
+
+## When to use
+
+Use Forge when the task needs several meaningful slices, must survive a restart
+or context loss, carries constraints or acceptance criteria across rounds, or
+needs machine-backed observations and an auditable record of rejection,
+recovery, drift, or approval. Do not use it for a one-pass edit, a question, or
+a task that finishes in one verified pass.
+
+LoopForge has one factual source: committed typed round documents in the Vault.
+Canonical State is compiled from those documents and is the cognitive source.
+Prompts, receipts, state files, replay, audit, and explain are projections; do
+not treat them as a second ledger. The Agent still owns meaning, planning,
+tool use, edits, tests, and the choice to request recovery.
+
+## Round lifecycle
+
+Keep these boundaries separate:
+
+- A **logical round** is one coherent work slice with one before/after evidence
+  boundary.
+- An **attempt** is a submission for that round. An enforcement rejection
+  increases the attempt but does not create round history; an invalid payload
+  has no lifecycle side effects.
+- A **Round Contract** is an optional proposal for the next bounded,
+  machine-checkable slice. It is not a second plan ledger and does not decide
+  the current round boundary. With an enabled after-capable command, a
+  continuing round with a successor available must leave an active contract.
+- A **workspace checkpoint** is recovery material: an automatic before-image or
+  an explicit `loopforge_checkpoint` savepoint. It is not progress or history.
+
+```text
+prepared prompt -> Agent works -> loopforge_next(handle, evaluation | recovery)
+                                   |-- invalid payload: same handle, no state change
+                                   |-- reject: same round, new attempt and handle
+                                   |-- accept/continue: commit and prepare next round
+                                   |-- stop: commit the final round/evidence
+                                   |-- recovery/backtrack: restore and verify, then redo
+```
+
+LoopForge owns persistence, evidence collection, validation, and disposition.
+The Agent owns the work and the semantic decisions.
+
+## Context and continuity
+
+Every prompt that holds a round declares `contextMode`, `contextReason`, and a
+human-readable strategy label. Follow those values together:
+
+```text
+Context: clean context — next round (fresh_invocation; workspace continues)
+Context: clean context repair (fresh_invocation; rejection_escalation; same logical round; rejected posture is attempt-time only)
+Context: clean context repair + invocation recovery (fresh_invocation; invocation_recovery; same logical round; retry lessons carried)
+Context: in-context repair (same_round_retry; enforcement_retry; continue original invocation if alive; lessons injected)
+Context: clean context after restore (fresh_invocation; recovery_redo; lessons carried)
+```
+
+- `fresh_invocation` starts a new model conversation without the prior
+  transcript, tool outputs, or uncommitted reasoning. It does not restart the
+  host — it is not a host-runtime restart requirement — or reset the workspace:
+  the same loop/session identity and modified workspace continue. Continuity
+  comes from the prompt's committed projection and any explicitly carried retry
+  or recovery lessons.
+- `same_round_retry` is in-context repair below the repeated same-check
+  rejection threshold. Continue the original invocation if it exists; the
+  rejection notice and findings are already provided. If it is gone, call
+  `loopforge_resume(loopId, invocationLost: true)` and use the resulting
+  `fresh_invocation / invocation_recovery` prompt for the same round and
+  attempt.
+
+Rejection escalation, recovery redo, and invocation recovery use a new model
+conversation. Prompt density (`L0`, `L1`, `L2`) is independent of this
+boundary. Stable MCP material (`initialize` instructions, `tools/list` schemas,
+and installed skill files) may stay warm; LoopForge does not manage provider
+caches or implicit model habits. Read the prompt and
+`references/recovery-and-views.md` when the distinction matters.
+
+Working Memory is bounded, derived from committed branch history and rollback
+directives, and report-only. Machine Evidence is a separate protected
+projection. Neither is an independent history; Agent reports never become
+machine evidence.
+
+## Start or resume
+
+1. Call `loopforge_status` with `view: "all"`.
+2. If an existing loop covers the objective, resume it; do not start a second
+   loop for the same objective.
+3. Otherwise call `loopforge_start` with the complete `task`, initial
+   `criteria`, hard `constraints`, and any applicable `maxRounds`, `loopId`, or
+   `planSource`. The live tool schema is authoritative.
+
+Keep the returned identifiers:
+
+| ID | Lifetime | Use |
+| --- | --- | --- |
+| `loopId` | Durable Vault identity | `loopforge_resume`, durable status views, replay, explain |
+| `sessionId` | Live process session | stop, pause, and live session controls |
+| `submissionHandle` | Exact held round/attempt | `loopforge_next`, `loopforge_checkpoint`, `loopforge_gate_check` |
+
+Pass `submissionHandle` unchanged. A rejection returns a new handle; an invalid
+evaluation keeps the same one. A stale handle has no side effects. If only the
+handle is lost, re-anchor it with `loopforge_status`; if the prompt or live
+session is gone, use `loopforge_resume` with the durable `loopId`. A paused or
+stalled session must be resumed before submission.
+Stopped and legacy loops are read-only; status and replay do not reopen them.
+
+`currentUserInstruction` on `loopforge_next` or `loopforge_resume` is input for
+that invocation only. It never rewrites the task, objective, criteria,
+constraints, Round Contract, or goal identity. Never infer it from an older
+transcript.
+
+## Execute a round
+
+1. Execute the returned prompt and do the work in the workspace.
+2. Check actual workspace and configured command evidence before claiming
+   success.
+3. Submit exactly one evaluation or one Agent-requested recovery with the
+   current handle. They are mutually exclusive.
+
+The required evaluation fields are:
+
+| Field | Meaning |
+| --- | --- |
+| `outcome` | `success`, `partial`, `failed`, or `blocked`; `success` and `blocked` require `should_continue=false`, and `blocked` requires a non-empty `blocker`. |
+| `output_summary` | What changed and what was verified this round. |
+| `constraint_violations` | Real violations, preferably using rendered `c-*` ids. |
+| `should_continue` | Whether the Agent requests a successor round; false only when the objective is complete or the Agent must stop. |
+
+A completed slice does not necessarily complete the whole task.
+
+Optional fields are event-driven reports, not a checklist. Read the current
+`submission_guidance` for applicability, real ids, legal shapes, and usable
+commands. Omit fields for events that did not happen. In particular:
+
+- `execution_report.files_changed` is the net workspace change from round
+  preparation, including deletions; a commit alone is not a file change.
+- There is no Agent-reported test count. Configured command observations are
+  the test facts.
+- `execution_report.claims` is the single claims channel. Claims cite rendered
+  criterion or active contract-item ids, but a claim alone verifies nothing.
+- Never invent ids; use only ids rendered in the prompt or guidance. Unknown or
+  unavailable observations stay unknown, never a pass or an empty change set.
+- `no_change_reason` is allowed only when no verification command is configured;
+  it does not create evidence. Agent reports and receipts are not evidence.
+
+Use the evidence and contract reference before proposing or redirecting a Round
+Contract. Use the recovery reference before requesting recovery, interpreting
+backtrack, or relying on prompt-level details. A recovery request is an action,
+not an evaluation; LoopForge restores and verifies the target before issuing
+the redo prompt. Never restore the workspace yourself after backtrack.
+
+## Interpret results
+
+- A non-null `prompt` is the next held work slice; execute it and submit with
+  the returned handle.
+- `enforcementAction: "reject"` keeps the logical round and returns a new
+  handle. Follow its context strategy; never resubmit the old handle.
+- `enforcementAction: "backtrack"` or Agent `recovery` with a non-null `prompt`
+  means LoopForge restored and verified the workspace; continue only from the
+  new redo prompt. A failed restore returns no prompt, keeps the directive
+  pending, and is retried with `loopforge_resume`.
+- A stalled result with no prompt is handled with `loopforge_resume`; use
+  `loopforge_status` only to re-anchor a handle when the prompt is still live.
+- When `prompt` is null, read `stopReason`, `sessionStatus`, and the Agent's
+  stop facts. `completed` is a lifecycle result of the Agent's stop declaration
+  passing the configured gates; it is not machine-verified task success.
+
+Read `submission_receipt.verification.evidence_posture` for the persisted
+Machine Evidence and `machineBackedSuccess` for the verification gate's single
+machine-backed success fact. Keep it separate from `agentOutcome`,
+`agentSuccessClaim`, and `agentShouldContinue`.
+
+Errors are structured. Branch on `error.code`, not message prose. Correct
+retryable `evaluation_invalid`, `contract_invalid`, `policy_invalid`, or handle
+errors with the current handle. Do not blindly resubmit for
+`session_not_found`, `state_unavailable`, or `gate_disabled`.
+
+## Rules to keep
+
+- Keep one loop focused on one user objective; do not create a round for every
+  file, command, test, commit, or elapsed interval.
+- Use the handle returned for the current attempt and never edit or reconstruct
+  it.
+- Report only events that happened; do not fill optional fields for coverage.
+- Do not invent a contract when no configured command can verify it.
+- Do not treat a receipt, state file, or Agent report as committed evidence.
+- Restore the verified boundary before continuing after backtrack.
+- Do not continue after `prompt: null` without interpreting the stop facts.
+
+## References
+
+Read these only when the current slice needs the detail. The live
+`submission_guidance` remains authoritative for field applicability, legal
+shapes, real ids, and usable commands.
+
+- [`references/evidence-and-contracts.md`](references/evidence-and-contracts.md):
+  Round Contracts, item closure, evidence commands, ids, and Agent/operator
+  judgment boundaries.
+- [`references/recovery-and-views.md`](references/recovery-and-views.md):
+  recovery and backtrack, checkpoint authority, prompt levels, read-only views,
+  gates, delegation, and the derived state file.

package/skills/forge/references/evidence-and-contracts.md

@@ -0,0 +1,204 @@
+# Evidence and Round Contracts
+
+This reference explains concepts and lifecycle rules. The live
+`submission_guidance` remains the only source for field applicability, legal
+shapes, real ids, and usable commands.
+
+## Optional evaluation field groups (conceptual)
+
+- **Reports:** `execution_report`, `discovered_constraints`,
+  `wrong_assumptions`, `open_questions`, and `worker_results` (the minimal audit
+  shape: `agentId`, `subTask`, `resultSummary`, `outcome`).
+- **State transitions:** `emerged_subtasks`, `subgoal_updates`,
+  `retracted_constraints` (Agent-discovered constraints only; operator
+  criteria/hard constraints are immutable).
+- **Claims and verification proposals:** one `execution_report.claims` channel
+  (`cr-` criterion claims are advisory, `rci-` active-contract item claims are
+  strict) and `round_contract` (with optional `supersedes`).
+- **Lifecycle controls:** `subtask_boundary` / `subtask_boundary_label`,
+  `outcome`, `blocker`, `objective_refinement`, `no_change_reason`, and
+  `gate_ids`. `outcome` is the ONE round conclusion; `success` must stop,
+  `blocked` must stop and carry a non-empty `blocker`.
+
+A field is included only when its event actually happened. The live guidance
+decides current applicability and the exact legal shape.
+
+`wrong_assumptions` and `open_questions` are strictly report-only. They feed
+bounded Working Memory, replay and explain, never the verification gate,
+success, contract closure or machine evidence. `open_questions` is a list of
+unresolved questions that still affect later slices (at most 3, 300 chars
+each), not a todo list and not a completion checklist.
+
+## What a Round Contract is
+
+A Round Contract is the Agent's proposal for a bounded, machine-checkable
+slice. It is not a round or a second plan ledger, and it is not unconditionally
+required. A proposal becomes active only after its declaring round commits,
+and it activates on the next round. With an enabled after-capable verification
+command, a continuing round that has a successor available must leave an active
+contract for that next round. An open active contract can continue without a
+new proposal; a closed contract needs a successor. A final configured round
+has no successor consumer.
+
+Declare a contract only when:
+
+- the next slice has one bounded deliverable;
+- each acceptance item can be checked by an available, enabled,
+  after-capable verification command;
+- the Agent can state what "done" means without asking the runtime to judge
+  semantics.
+
+If no configured command can verify the slice, do not invent a contract.
+Continue with Agent-directed work and report the evidence honestly.
+
+## Proposal shape and binding
+
+Use the current `submission_guidance` for the exact legal shape. Conceptually:
+
+- `work_item` is the bounded deliverable this slice produces — an outcome, not
+  an activity.
+- `items[]` are acceptance conditions inside that slice, not a task checklist.
+- Each item binds its own `verify_with` command ids. One condition may use
+  several commands; one command may back several conditions. The binding never
+  moves to the contract/work_item level.
+- `scope` is an optional, report-only declaration of intended files or
+  directories. It grants no permission, is never containment-checked, and
+  changes outside it are an info fact only.
+- `criterion_refs` is optional and must cite real `cr-*` ids from the active
+  criterion set the current prompt rendered. `scope` and `supersedes` are
+  report-only modifiers and never change `rc-*` identity.
+- Sub-goals remain an Agent plan report. Contract items do not link to them;
+  their closure depends only on the item, its bound commands and machine
+  evidence.
+
+Unknown fields, free text where an id is required, duplicate refs, duplicate
+normalized items, unconfigured/disabled/not-after commands, and a missing
+`work_item` are `contract_invalid`. Correct the payload and resubmit with the
+same `submissionHandle`.
+
+Contract and item ids are content-addressed (`rc-*`, `rci-*`) from `work_item`
+and the acceptance items only. Restating an unchanged proposal preserves
+identity; changing only `scope` or adding `supersedes` does not change it. While
+a contract is open, omitting `round_contract` continues it; you do not need to
+restate it.
+
+With an after-capable command, a continuing round with a successor available
+MUST leave an active contract for the next round. The final configured round
+has no successor consumer, so it does not require a proposal and LoopForge
+stops at the configured round limit. A closed contract with no successor is
+`contract_required`;
+a successor that repeats the closed acceptance items is
+`contract_successor_unchanged`. A different proposal while the active contract
+is open is rejected as `contract_premature` unless it explicitly supersedes the
+active contract.
+
+## Redirecting an active contract
+
+If investigation shows the active slice is the wrong route, do not report it as
+blocked and do not quietly propose another contract. Put the redirect modifier
+on the ONE contract channel in the same evaluation:
+
+```json
+{
+  "round_contract": {
+    "work_item": "<the successor deliverable>",
+    "items": [{
+      "description": "<a different acceptance condition>",
+      "criterion_refs": [],
+      "verify_with": ["verify"]
+    }],
+    "supersedes": {
+      "contract_id": "<the active rc-XXXXXXXX id rendered in this prompt>",
+      "reason": "why the active slice is no longer the right route"
+    }
+  }
+}
+```
+
+The successor is the same proposal, its acceptance items must differ from the
+active contract's, and `should_continue` must stay true. The old contract closes as
+`superseded` — not `verified`, not `blocked` — its item statuses stay in the
+audit record, the workspace is not restored, and the redirect round cannot be
+reported as `completed`. The successor activates next round.
+
+A stale or mismatched `contract_id`, unchanged acceptance items, a blocked
+outcome, or `should_continue=false` returns `contract_invalid`; fix the payload
+and resubmit the same handle. Stop and blocked rounds cannot leave any
+proposal (`contract_on_stop`).
+
+## Item status and closure
+
+Item status is machine-derived:
+
+- `pending`: not claimed as met;
+- `insufficient`: claimed as met but not backed by all required observations;
+- `contradicted`: a bound observation fails, or its entrypoint/configuration is
+  no longer trustworthy;
+- `verified`: the Agent claims `met`, every bound command passes in the closing
+  round's after phase, and the declaration binding remains intact.
+
+Closure priority is `blocked > superseded > verified > open`:
+
+- every item `verified` closes the contract as verified;
+- a round reporting `outcome: "blocked"` closes it as blocked;
+- an explicit `round_contract.supersedes` closes it as superseded;
+- otherwise it remains open.
+
+A superseded contract keeps every item status for audit and never restores the
+workspace. Its redirect round cannot be `completed`.
+
+A claimed-but-unbacked item is verification debt. Repeated claims escalate at
+`engine.unverified_claim_streak_limit` on the same check's streak. An honest
+supersede with no `met` claim retires the old debt finding; a supersede that
+still claims an old item `met` keeps it.
+
+## Evidence commands
+
+Contract items are backed by commands the **operator** configures in
+`loop_policy.json` under `evidence.commands`. The Agent never declares one and
+does not discover project scripts to invent one.
+
+Commands:
+
+- run with an explicit executable and argument list, without a shell;
+- are confined to the workspace;
+- run in the after phase (or both);
+- have their own timeout and output cap;
+- determine pass/fail from the configured success exit codes;
+- have a content-addressed configuration hash bound into the contract item.
+
+`loopforge doctor` statically checks every configured command and never
+executes one. When no command is available, no configured command can back a
+contract item; run without a contract rather than declaring items that cannot
+close.
+
+A command's **entrypoint** is the file it names plus `package.json` when a
+package manager runs it. It must already be part of the workspace when the
+round starts, and it must not change during the round that runs it. The runtime
+records those files at round start and compares them afterwards, whether or not
+git can see them. A changed entrypoint makes the observation untrustworthy:
+restore it to its round-start content. Do not author the verification script
+inside the round you expect it to verify.
+
+To keep a script that must survive a rollback, make it part of the committed
+workspace before the round that depends on it. Restoring to an earlier
+checkpoint discards work the target boundary did not already carry.
+
+## IDs and Agent judgment
+
+Prompts render stable IDs beside constraints (`c-*`), criteria (`cr-*`),
+sub-goals (`sg-*`), contracts (`rc-*`), and contract items (`rci-*`). Use those
+ids where a field asks for a reference. Never invent one; when an id is absent,
+omit the field rather than guessing.
+
+LoopForge validates structure, configured/enabled/after-capable command
+bindings, and references. It does not judge whether:
+
+- a `work_item` sounds like a deliverable;
+- an item semantically matches a command;
+- a command is the "right" acceptance test;
+- the declared `scope` is the right route.
+
+Those remain Agent and operator judgment. `round_scope_drift` is an info fact
+only; it never rejects, terminates, backtracks, stalls, or reaches the rejection
+counter.