loopforge 2.7.0 → 3.0.0

package/skills/perception/SKILL.md

@@ -1,118 +1,228 @@
 ---
 name: perception
-description: Drive a recoverable multi-round coding task through LoopForge MCP while the Agent remains the execution owner.
+description: Drive a recoverable multi-round task through the LoopForge MCP runtime while the Agent remains the execution owner.
 ---
 
 # Perception
 
-Use LoopForge when a coding task needs several rounds, must survive context
-compression or process restart, or benefits from an auditable record of goals,
-constraints, evidence, and decisions.
+Use LoopForge for work that spans multiple context windows, needs an auditable
+record, or must survive a process restart. LoopForge stores canonical facts and
+compiles prompts; you remain responsible for inspecting the repository,
+editing files, running tools, and making technical decisions.
 
-LoopForge maintains cognitive state. You remain the Agent that reads files,
-edits code, runs commands, delegates work, and decides how to reason.
+There is one public execution path. Do not create a second plan scheduler,
+background Agent, MCP Task, or local shadow state machine.
 
-## Start
+## 1. Start one loop
 
 Call `loopforge_start` with:
 
-- `task`: the complete user objective.
-- `constraints`: hard boundaries that must survive every round.
-- `maxRounds`: optional safety limit. The default is 20.
-- `domain`: optional context label.
+- `task`: the complete user objective, not a short reminder;
+- `constraints`: hard boundaries that must survive every round;
+- `successCriteria`: explicit verifiable completion criteria when the task has
+  more than the default objective-level criterion;
+- `maxRounds`: an explicit safety limit when the default (100) is unsuitable;
+- `domain`: an optional technology or repository hint;
+- `planSource`: an optional path to a user-provided plan (reference only).
 
-Keep the returned `sessionId`, `roundId`, prompt, and level.
+Keep the returned `sessionId`, `loopId`, `roundId`, prompt, and hashes. Execute
+the returned prompt in the bound workspace before submitting a report.
 
-## Execute a round
+## 2. Submit `RoundReport`
 
-1. Execute the returned prompt. Do real repository work.
-2. Use the available tools and reasoning approach that best fit the task.
-3. Check actual evidence before claiming success.
-4. Call `loopforge_next` with `sessionId` and a structured `evaluation`.
-
-Minimal evaluation:
+Call `loopforge_next` after an accepted round. Call `loopforge_retry` only when
+the previous logical round was rejected. Both calls require `sessionId` and a
+canonical report; free-form text and the old `status` report are invalid.
 
 ```json
 {
-  "success": false,
-  "output_summary": "Implemented the parser and added 8 passing tests.",
-  "constraint_violations": [],
-  "should_continue": true
+  "format": "loopforge.round-report",
+  "outcome": "partial",
+  "continuation": "continue",
+  "summary": "Implemented the parser and ran focused tests.",
+  "violations": [],
+  "evidence": {
+    "files": ["src/parser.ts", "test/parser.test.ts"],
+    "checks": [{"name": "npm test -- parser", "status": "passed", "counts": {"passed": 8, "failed": 0, "skipped": 0}}],
+    "claims": [{"id": "claim-0123456789ab", "targetId": "cr-abcdef12", "evidenceRefs": ["command:npm test -- parser"]}],
+    "provenance": {}
+  },
+  "agentIntent": "Add parser regression coverage next"
 }
 ```
 
-Important fields:
+### Outcome versus continuation
+
+- `outcome` is only this round's result: `success`, `partial`, `failed`, or
+  `blocked`.
+- `continuation` is only the request to start another round: `continue` or
+  `stop`.
+- `success` does not prove the total objective is complete. Completion requires
+  runtime-verified claims for every remaining criterion, no contradictory
+  checks, and no unresolved User Gate.
+- `blocked` requires a `blocker` object. Use `continuation: "stop"` for a
+  user decision, external dependency, or side effect that must not be guessed.
+  An Agent-resolvable blocker may use `continue`, but state the required
+  evidence and resolution.
+
+### Report fields
 
-| Field | Rule |
+| Field | How to use it |
 | --- | --- |
-| `success` | Use `true` only when the whole objective and every hard constraint are satisfied. |
-| `output_summary` | State what changed and what was verified. |
-| `constraint_violations` | Report real violations. Do not hide them to force progress. |
-| `should_continue` | Use `false` only when the entire task is complete. |
-| `execution_evidence` | Report changed files, test counts, met and remaining criteria, and progress when known. |
-| `discovered_constraints` | Add newly discovered guardrails. |
-| `objective_refinement` | Refine the objective when repository evidence changes its meaning. |
-| `wrong_assumptions` | Record assumptions disproved this round. |
-| `worker_results` | Record delegated subtask results and discoveries. |
+| `summary` | Describe concrete work and observations from this round. |
+| `violations` | List every actual hard-constraint violation; do not hide one to obtain acceptance. Prefer `c-XXXXXXXX` IDs. |
+| `evidence` | Report files, checks, claims and references. Agent provenance is only a claim until a runtime provider observes it. |
+| `discoveries` | Record wrong assumptions, emerged work, durable facts and newly discovered constraints. |
+| `subGoalEvents` | Report completed, blocked or canceled existing sub-goals. Do not invent a second sub-goal lifecycle. Prefer `sg-XXXXXXXX` IDs. |
+| `constraintEvents` | Retire a constraint only when repository evidence shows it is no longer valid. |
+| `criterionRevisions` | Propose an old-to-new criterion change; never silently replace the user's objective. |
+| `objectiveRefinement` | Add a safe clarification when evidence changes the interpretation; it is validated by the runtime. |
+| `phaseBoundaryProposal` | Suggest a phase label and reason. The runtime decides whether the boundary is real. |
+| `contextRequest` | Per-round emphasis, expansion or confusion requests. It is consumed once and is not durable state. |
+| `agentIntent` | Optional Agent suggestion used only for audit and drift comparison. Runtime-derived Focus, Todo and Suggested Next Action take precedence. |
+| `driftClarification` | When drift is detected, provide a concrete explanation and a criterion/constraint ID or observed file path. Runtime validates it; do not submit a waiver boolean. |
+
+Do not submit derived `currentFocus`, `todoProjection`, `handoff`,
+`progress`, `failedPatterns`, `nextAction`, or `verifiedFacts` as alternate
+facts. These are internal or derived views. A progress estimate, if present in
+the evidence supplied to an embedding, is never authoritative.
+
+## 3. Evidence discipline
+
+Use stable IDs shown in the prompt:
+
+- constraints: `[c-a3f2b1c0]`;
+- criteria: `[cr-b5a6c7d8]`;
+- sub-goals: `[sg-f1e2d3c4]`.
+
+Claims should reference a concrete file, check, or provider observation. Do not
+mark your own provenance `verified` to force progress. Runtime providers may
+replace claimed evidence with `verified`, `contradicted`, or `unavailable`.
+Missing provider output is unavailable, not a pass. A rejected attempt and its
+claims are not canonical facts.
+
+## 4. Retry, backtrack and continuation
+
+Read the returned `decision` and `enforcementAction`:
+
+- `accepted`: execute the returned prompt for the next round;
+- `rejected`: correct the evidence or work and call `loopforge_retry`; keep the
+  same logical `roundId` and do not call `next` to bypass rejection;
+- `backtracked`: use the returned restore round and requirements, then continue
+  from the new prompt;
+- `stopped` or `terminated`: do not submit another report unless a new loop is
+  explicitly started.
+
+Backtrack is advisory and bounded. It never changes workspace files. Follow the
+exact paths and checks returned by LoopForge, inspect the resulting workspace,
+and report the restoration evidence. Never improvise an unbounded destructive
+command such as `git clean -fd` or `git reset --hard`; ask for a User Gate when
+the required action is destructive or authorization is unclear.
+
+## 5. User Gate and Agent Gate
+
+For a risky action, call `loopforge_gate_check` with:
 
-Do not embed an evaluation marker in ordinary output when the MCP client accepts
-the structured `evaluation` argument.
+```json
+{
+  "description": "Apply the production database migration",
+  "scope": ["db/migrations/2026-01.sql"],
+  "effects": ["data_migration", "production"],
+  "reversibility": "recoverable",
+  "authorization": "user_required"
+}
+```
 
-## Interpret the result
+User Gate is required for production, credentials, data migration, publishing,
+payment, external communication, public API changes, irreversible or unknown
+actions, and unknown authorization. Limit the blocked scope and continue only
+with allowed read-only investigation or dry runs. Agent Gate is for bounded,
+reversible, explicitly `agent_allowed` workspace work or ordinary technical
+blockers. Resolve a User Gate with `loopforge_gate_resolve` using the exact same
+descriptor; its `actionHash` invalidates an approval if the action changes.
 
-If `prompt` is non-null, execute it and submit the next evaluation.
+## 6. Status, history and audit
 
-If `enforcementAction` is `reject`, redo the same logical round. The round ID
-stays stable and the attempt number increases. Follow the retry requirements;
-the rejected attempt has not been committed.
+Use only the current twelve tools:
 
-If `prompt` is null, inspect `stopReason`:
+```text
+loopforge_start       loopforge_next        loopforge_retry
+loopforge_backtrack   loopforge_resume      loopforge_pause
+loopforge_stop        loopforge_status      loopforge_history
+loopforge_gate_check  loopforge_gate_resolve loopforge_audit
+```
 
-| Reason | Meaning |
-| --- | --- |
-| `task_complete` | The complete objective was reported finished. |
-| `circuit_breaker` | Repeated failed rounds require a different approach or user input. |
-| `max_rounds` | The safety limit was reached. Summarize remaining work. |
-| `stalled` | Evaluation or execution did not produce a usable next state. |
-| `enforcement_terminated` | Repeated invalid claims or stalled progress terminated the loop. |
-| `paused` | The durable session remains available for resume. |
-
-## Prompt levels
-
-- L0 is a same-round retry with the rejection reason and changed evidence.
-- L1 is the normal compact continuation view.
-- L2 is a full rehydration for the first round, a checkpoint, or a goal change.
-
-These levels control state density only. LoopForge does not choose a reasoning
-technique for you.
-
-## Recovery and control
-
-- Use `loopforge_status` to inspect the live round and trajectory.
-- Use `loopforge_pause` before an intentional interruption.
-- Use `loopforge_resume` with the loop ID to reconstruct a durable session.
-- Use `loopforge_list` after a client restart to find recoverable sessions.
-- Use `loopforge_replay` for the committed timeline.
-- Use `loopforge_health` to inspect goal alignment and drift.
-- Use `loopforge_stop` only for an intentional terminal stop.
-
-The optional `.loopforge/state/<loopId>-state.md` file is a readable derived
-view. The typed JSON session and round documents are the recovery truth. If the
-state file exists, it can help you review the full state, but do not assume it is
-enabled.
-
-## Delegation
-
-Delegation does not create a separate LoopForge mode. Give each worker a
-self-contained subtask and relevant hard constraints. Add the returned result to
-`worker_results` so discoveries can enter the next canonical state.
-
-## Rules
-
-1. Execute the prompt instead of generating another prompt.
-2. Submit one honest structured evaluation after each attempt.
-3. Treat required command evidence and verification errors as authoritative.
-4. Keep one loop focused on one user objective.
-5. Do not advance a paused or stopped session through another process.
-6. Continue within the same Agent task when possible; LoopForge preserves state,
-   but it does not create a background Agent.
+- `loopforge_status({scope: "session", sessionId})` shows the live round. Add
+  `detail: "full"` for cognition projections, prompt diagnostics, metrics and
+  audit data.
+- `loopforge_status({scope: "loop", loopId})` reads loop-level health and
+  audit. `scope: "all"` lists persisted loop summaries (including stopped
+  loops for audit/recovery inspection) and accepts no ID.
+- `loopforge_history({loopId, view: "round", round})` reads one persisted
+  round. `view: "timeline"` reads events in `event_sequence` order; use
+  `fromSequence`, `toSequence` and `limit` (1-200) for pagination.
+- `loopforge_audit({loopId})` is read-only and reports criteria coverage,
+  contradictions, evidence availability, unresolved User Gates, regression
+  obligations and `sequenceComplete`.
+
+The old names `loopforge_list`, `loopforge_health`, `loopforge_inspect`, and
+`loopforge_replay` are not public tools.
+
+## 7. Pause and resume
+
+Call `loopforge_pause` before an intentional interruption. After a client or
+process restart, call `loopforge_resume` with the saved `loopId`; do not start a
+new loop just because the in-memory session disappeared. Compare the returned
+`stateHash` and `promptHash`, then execute the rebuilt prompt. A loop can be
+resumed only from its persisted vault state.
+
+## 8. Prompt levels and projections
+
+- **L0**: compact same-round retry with the rejection gap.
+- **L1**: normal continuation with current focus and required evidence.
+- **L2**: full rehydration after the first round, a phase boundary, goal or
+  constraint change, stale or contradictory evidence, drift, recovery, or
+  repeated low-information rounds.
+
+L0/L1/L2 control state density, not reasoning strategy. The prompt compiler
+reads canonical Goal, RoundEvent, EvidenceEnvelope, Constraint, SubGoal and
+GateDecision facts, then derives Phase, Focus, Todo, Handoff, progress and
+diagnostics. Mandatory objective, focus, gate, hard constraints and required
+fixes remain present under a prompt budget.
+
+## 9. Workspace and command safety
+
+When LoopForge requests verification, run commands in the bound workspace only.
+Use executable plus argument arrays, `shell: false`, timeouts, output limits and
+path-boundary checks. Do not concatenate user-controlled strings into shell
+commands. This is LoopForge's evidence boundary; it does not grant or revoke
+the Agent's ordinary tool permissions.
+
+## 10. Long-horizon habits
+
+Keep one loop focused on one user objective. Submit one honest report per
+round, preserve criterion and constraint IDs, and include a concrete next
+verification when continuing. Inspect the full state on L2 rounds. Use pause
+before handoff and audit before claiming final completion. LoopForge supports
+long runs through explicit rounds and durable replay, but it does not execute
+rounds in the background for you.
+
+## 11. Reliability rules
+
+An invalid report is an input error, not a round fact. The runtime leaves the
+current `roundId`, attempt, state and vault unchanged and returns
+`invalid_round_report`; submit a corrected report instead of starting a new
+loop. A persistence error is not recoverable by pretending success: stop and
+retry the operation after the storage boundary is healthy.
+
+Evidence capture and recovery are asynchronous. `maxRounds` must be a positive
+integer no greater than the configured policy limit. Corrupt JSON, an invalid
+event format, or a sequence gap returns `storage_corruption`; the runtime never
+sorts, fills, or rewrites damaged history. Terminal enforcement rules track
+their escalation retry independently; the same rule terminates only after its
+guided retry has already been used.
+
+When intent drift is reported, use `driftClarification` with a concrete
+explanation and an anchor that exists in the current criteria, constraints or
+observed workspace evidence. Do not send `clarification_accepted: true`.
+Runtime verification owns the clarification streak and any escalation.

package/dist/backends/interface.d.ts

@@ -1,39 +0,0 @@
-/** @deprecated Use LoopStore from loop-store.js directly.
- *
- *  Kept for backward compatibility with modules that still reference
- *  VaultBackend as a parameter type. New code should depend on LoopStore. */
-export interface VaultEntry {
-    id?: string;
-    task_id?: string;
-    version_tag?: string;
-    is_active?: boolean;
-    timestamp?: string;
-    user_intent?: string;
-    task_type?: string;
-    /** @deprecated Use `success` field instead. Kept for reading old vault data. */
-    quality_score?: number;
-    success?: boolean;
-    skill_used?: string;
-    loop_id?: string;
-    loop_lineage?: Record<string, unknown>;
-    loop_objective?: Record<string, unknown> | null;
-    execution_feedback?: string;
-    task?: string;
-    output_summary?: string;
-    constraint_violations?: string[];
-    tags?: string[];
-    full_prompt?: string;
-    [key: string]: unknown;
-}
-export interface VaultBackend {
-    /** Optional atomic critical section used by storage adapters. */
-    withLock?<T>(fn: () => T): T;
-    queryEntries(opts?: {
-        prefix?: string;
-        taskIdPattern?: string;
-        feedbackOnly?: boolean;
-    }): VaultEntry[];
-    appendEntry(entry: VaultEntry): void;
-    appendEntries(entries: VaultEntry[]): number;
-}
-//# sourceMappingURL=interface.d.ts.map

package/dist/backends/interface.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../../src/backends/interface.ts"],"names":[],"mappings":"AAAA;;;6EAG6E;AAE7E,MAAM,WAAW,UAAU;IACzB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAChD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAG7B,YAAY,CAAC,IAAI,CAAC,EAAE;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,YAAY,CAAC,EAAE,OAAO,CAAC;KACxB,GAAG,UAAU,EAAE,CAAC;IAEjB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACrC,aAAa,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CAAC;CAE9C"}

package/dist/backends/interface.js

@@ -1,6 +0,0 @@
-/** @deprecated Use LoopStore from loop-store.js directly.
- *
- *  Kept for backward compatibility with modules that still reference
- *  VaultBackend as a parameter type. New code should depend on LoopStore. */
-export {};
-//# sourceMappingURL=interface.js.map

package/dist/backends/interface.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"interface.js","sourceRoot":"","sources":["../../src/backends/interface.ts"],"names":[],"mappings":"AAAA;;;6EAG6E"}

package/dist/enforcement-gate.d.ts

@@ -1,50 +0,0 @@
-/** Enforcement Gate — Layer 2 round-boundary runtime enforcement (v1.13).
- *
- * Pure-function module. Receives the verification gate's findings plus
- * round-level context and decides whether to accept the round, reject it
- * (force the agent to redo), or terminate the loop.
- *
- * This is the "runtime" that prompt-only constraint systems lack.
- * Verification gate detects WHAT is wrong; enforcement gate decides
- * what to DO about it.
- *
- * Decision semantics:
- * - accept:    round passes all checks; advance to next round as normal.
- * - reject:    agent's self-evaluation or round output is invalid; the
- *              agent receives a rejection prompt and must redo the SAME
- *              round. Round counter does NOT increment.
- * - terminate: loop has reached an unrecoverable state; stop immediately
- *              with stopReason "enforcement_terminated".
- */
-import type { VaultEntry } from "./backends/interface.js";
-import type { EnforcementResult, SelfEvaluation, VerificationFlag, VerificationResult } from "./protocol.js";
-/** Enforce round-boundary rules based on the verification gate's findings
- *  and the agent's self-evaluation integrity.
- *
- *  Rules run in priority order (R1 → R5). The first rule that fires wins.
- *
- * @param selfEval              The agent's self-evaluation for the current round.
- * @param verifyResult          The verification gate's output (from verifySelfEvaluation).
- * @param currentRound          Current round number (1-based, BEFORE increment).
- * @param vaultEntries          Vault entries for this loop (used for progress tracking).
- * @param consecutiveRejections How many consecutive rounds have already been rejected.
- *                              Starts at 0; increments on each reject; resets on accept.
- */
-export declare function enforceRound(selfEval: SelfEvaluation, verifyResult: VerificationResult, currentRound: number, vaultEntries: VaultEntry[], consecutiveRejections?: number, skipEvidenceRules?: boolean): EnforcementResult;
-/** Build a rejection prompt for the agent.
- *
- *  The prompt clearly states the round was rejected, why, what the agent
- *  must fix, and that the agent must redo the SAME round (not advance).
- *
- *  v2.7: Accepts verificationFlags to render a diagnostic "Evidence Gap"
- *  section. Each error/warn flag becomes a concrete claim-vs-evidence
- *  mismatch statement so the agent knows exactly what to correct rather
- *  than retrying blindly.
- *
- * @param currentRound      The round number that was rejected (NOT incremented).
- * @param task              The original loop task description.
- * @param enforceResult     The enforcement decision with reason and fix instructions.
- * @param verificationFlags The verification gate's findings for this round.
- *                          Used to build the Evidence Gap section. */
-export declare function buildRejectionPrompt(currentRound: number, task: string, enforceResult: EnforcementResult, verificationFlags?: VerificationFlag[]): string;
-//# sourceMappingURL=enforcement-gate.d.ts.map

package/dist/enforcement-gate.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"enforcement-gate.d.ts","sourceRoot":"","sources":["../src/enforcement-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,eAAe,CAAC;AAmevB;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,cAAc,EACxB,YAAY,EAAE,kBAAkB,EAChC,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,UAAU,EAAE,EAC1B,qBAAqB,GAAE,MAAU,EACjC,iBAAiB,UAAQ,GACxB,iBAAiB,CA0BnB;AAED;;;;;;;;;;;;;;sEAcsE;AACtE,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,iBAAiB,EAChC,iBAAiB,GAAE,gBAAgB,EAAO,GACzC,MAAM,CA6CR"}