loopforge 3.0.0 → 3.6.0

package/README.md

@@ -1,13 +1,81 @@
-# LoopForge package
+# LoopForge
 
-LoopForge is a cognitive state runtime for AI coding agents. It keeps a long
-task's objective, constraints, evidence, decisions and recovery state stable
-across many Agent-driven rounds.
+**A context window is not memory. Memory needs a runtime.**
 
-The Agent remains the executor: it reads code, edits files, runs tools and
-decides how to reason. LoopForge is the external round boundary that checks
-claims, commits canonical facts and rebuilds the next prompt. It is not a model,
-scheduler, unattended worker or second planning system.
+> **v3.6.0** — `npm install -g loopforge`. Node.js ≥ 18. Zero runtime dependencies.
+> [中文文档](../README.zh-CN.md)
+
+---
+
+## The real problems with long-horizon tasks
+
+Any AI coding agent, given a long enough task, hits three walls. Not because the model isn't smart enough. Not because the context window isn't large enough. These are **architectural** problems.
+
+### Problem 1: The summary cascade
+
+Context fills up → compress. Fills up again → compress again. The third compression is a summary of a summary of a summary. Every cycle evaporates information — critical constraints get silently deleted because the summarizer judged them "no longer relevant." Researchers found that after 3–4 summary cycles, constraint violation rates spike from 0% to 59%. The agent doesn't know what it forgot, because the forgetting itself was compressed away.
+
+### Problem 2: Self-correction doesn't work
+
+Models cannot reliably improve themselves through introspection — they talk themselves out of correct answers. Effective recovery requires an **external verifier** — an independent observer that doesn't share the agent's context, doesn't participate in its reasoning, and only looks at inputs and outputs.
+
+### Problem 3: Compound error (p^N)
+
+If each step succeeds with probability p, N sequential steps succeed with probability p^N. Frontier agents nail nearly 100% of tasks under 4 minutes but crater to under 10% on tasks over 4 hours. Small errors at each step become the correct input for the next step.
+
+**These three problems amplify each other. The summary cascade loses information → lost information becomes errors → the agent can't self-correct because those errors look reasonable within its own context.**
+
+---
+
+## What LoopForge does about it
+
+LoopForge runs outside the agent and owns the boundary between rounds. Its
+design has two explicit sources:
+
+- **One factual source:** committed typed round documents in the Vault.
+- **One cognitive source:** Canonical State compiled from those facts.
+
+`loopforge_next` accepts a structured evaluation. The core fields `success`,
+`output_summary`, `constraint_violations`, and `should_continue` are strict;
+optional fields are normalized. Invalid input returns `evaluation_invalid` and
+can be corrected with the same `roundId` without saving session state, writing
+a round, entering either gate, or changing metrics.
+
+Valid submissions pass through evidence collection, 27 verification checks,
+and 14 enforcement rules. Only an allowed round joins committed history. The
+shared internal `CommittedRoundView` gives Replay, Audit, Metrics, contracts,
+the compiler, and gate history one decoder and one filtering policy. It does
+not create another storage format.
+
+The compiler evolves Canonical State from committed history, then derives
+focus, todo, phase, delegation, and handoff for prompts and status views. The
+next prompt therefore comes from typed cognitive state, not from a summary of
+the previous prompt.
+
+```text
+Traditional: prompt -> summary -> next prompt -> another summary
+LoopForge:    committed rounds -> Canonical State -> next prompt
+```
+
+The verification gate compares claims with Git snapshots, test output, and
+configured command evidence. The enforcement gate can accept, reject,
+backtrack, or terminate. A rejected submission commits nothing. R4 and R5 can
+restore the last clean round, inject a diagnosis, and verify workspace
+restoration before work continues.
+
+---
+
+## What LoopForge is not
+
+- **Not a memory database.** The optional state file is derived. Committed
+  rounds hold facts, and Canonical State supplies runtime cognition.
+- **Not a context compressor.** It recompiles prompts from typed state instead
+  of compressing the prior prompt.
+- **Not a constraint tracker.** Constraints are one input to external judgment.
+- **Not an agent or unattended executor.** The external agent owns planning,
+  code changes, and tool use. LoopForge governs round transitions.
+
+---
 
 ## Install
 
@@ -17,154 +85,69 @@ loopforge init --client claude
 claude mcp add loopforge -- npx loopforge mcp
 ```
 
-For Codex use `loopforge init --client codex` and register the same MCP command.
-The generic initializer prints an MCP configuration fragment. The package
-requires Node.js 18 or newer and has zero runtime dependencies.
-
-## How a loop works
-
-1. The Agent calls `loopforge_start` with one objective and its hard constraints.
-2. LoopForge compiles a prompt from canonical state.
-3. The Agent executes that prompt and submits a structured `RoundReport`.
-4. Runtime evidence is checked, the round boundary is enforced, and the result is accepted, rejected, backtracked or stopped.
-5. If work remains, the next prompt is compiled again from committed facts.
-
-The report deliberately separates `outcome` (`success`, `partial`, `failed` or
-`blocked`) from `continuation` (`continue` or `stop`). This prevents a local
-round result from being mistaken for completion of the whole objective. The old
-`status` report and free-form evaluation text are not accepted at the public
-boundary.
-
-```json
-{
-  "format": "loopforge.round-report",
-  "outcome": "partial",
-  "continuation": "continue",
-  "summary": "Implemented the parser and ran focused tests.",
-  "violations": [],
-  "agentIntent": "Add parser regression coverage next",
-  "evidence": {"files": ["src/parser.ts"], "checks": [], "claims": [], "provenance": {}},
-  "discoveries": {"wrongAssumptions": [], "emergedWork": [], "facts": [], "newConstraints": []},
-  "subGoalEvents": {"completed": [], "blocked": [], "canceled": []}
-}
-```
+Works with Claude Code, Codex CLI, or any MCP-compatible client.
 
-`blocked` reports include a blocker. User decisions and external side effects
-must stop at a User Gate; an Agent-resolvable technical blocker may continue
-only with concrete evidence requirements.
-
-## State model and prompt artifact
-
-The package follows a single-source rule: Goal, RoundEvent, EvidenceEnvelope,
-Constraint, SubGoal and GateDecision are durable facts; phase history, Current
-Focus, Todo, Handoff, progress, failed patterns and prompt diagnostics are
-rebuildable projections, never a competing plan or persistence layer. Compiler
-responses keep those derived views in one `projection` object. The full model,
-the L0/L1/L2 prompt levels and the immutable prompt artifact are described in
-the [project README](https://github.com/kyrielrving11/LoopForge/blob/main/README.md)
-under “Canonical cognitive state” and “One prompt artifact per attempt”.
-
-The default store is `.loopforge`. Events are written through the canonical
-writer and receive a monotonic `event_sequence` within each loop. Prompt and
-state hashes make a restart or replay auditable. Markdown state is only a
-replaceable view, not the recovery truth.
-
-Evidence collection and recovery are asynchronous. A malformed report is an
-input error; corrupt JSON, an invalid event format, or a sequence gap is a
-`storage_corruption` error and is never auto-repaired. The configured
-`maxRounds` must be a positive integer no greater than the policy limit.
-
-## Verification, enforcement and gates
-
-Git evidence is enabled by default. Explicit command providers run with an
-executable and argument array (`shell: false`), bounded output, a timeout and a
-workspace path check; required command failures contradict an unsupported
-success claim. Agent claims remain `claimed` until a provider observes them —
-provenance is owned by the runtime, and criteria coverage comes from verified
-claims, never from a progress estimate. A successful report that requests a
-stop is accepted as completion only when a live evidence provider produced
-verifiable evidence; with no provider, completion stays unresolved.
-
-Gate checks use `GateActionDescriptor` to make risk explicit: production,
-credentials, data migration, publishing, payment, external communication,
-public API changes, irreversible actions and unknown authorization are User
-Gates; bounded, reversible, explicitly agent-allowed workspace work is an
-Agent Gate. Decisions bind to an `actionHash`, so changing an action
-invalidates an earlier approval.
-
-For the full decision semantics — what the gate detects, how enforcement
-decides accept, reject, backtrack and stop — see the corresponding sections in
-the [project README](https://github.com/kyrielrving11/LoopForge/blob/main/README.md).
-
-## Recovery semantics
-
-A rejected attempt is zero-commit: its report does not enter canonical state.
-`loopforge_retry` keeps the same logical round ID and increments the attempt;
-`loopforge_next` cannot bypass a rejection. `loopforge_backtrack` returns a
-bounded restore point and verification requirements but never changes workspace
-files. Pause and resume preserve the transaction across client or process
-boundaries. Stop records termination without deleting the vault.
-
-`agentIntent` is an optional, non-authoritative suggestion retained inside the
-report for audit and drift comparison. It never overwrites Current Focus, Todo,
-runtime progress, completion, or the compiler's Suggested Next Action.
-
-Terminal enforcement escalation is tracked per rule. A rule can issue one
-guided retry before a repeated hit terminates it; accepting progress or
-backtracking clears the active rejection episode.
-
-## MCP surface
-
-The server exposes exactly twelve Agent-driven tools:
+The MCP server path (`loopforge mcp`) is the primary integration. It provides
+the full cognitive infrastructure: verification gate, enforcement gate,
+backtrack, evidence collection, and crash recovery. The engine is also
+available as a library for custom integrations.
+
+---
+
+## Architecture
 
 ```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
+External agent
+  -> structured evaluation
+  -> evidence / verification / enforcement
+  -> accept, reject, backtrack, or terminate
+       reject / terminate: no round commit
+       accept / stop / backtrack: commit transaction decision
+  -> committed round documents        [factual source]
+  -> CommittedRoundView                [shared read model]
+       -> Replay                       [what happened]
+       -> Audit / Metrics              [evidence and diagnostics]
+       -> Canonical State              [cognitive source]
+            -> DerivedCognitiveFacts
+            -> prompt / state file / status
+            -> external agent, next round
 ```
 
-`status` combines session, loop and persisted-loop views. `history` combines
-single-round inspection and event-timeline replay with sequence pagination. The
-old `list`, `health`, `inspect` and `replay` MCP names are not aliases. MCP
-Tasks and background Agent execution are intentionally outside this package.
-
-## Long-horizon use
-
-LoopForge can support dozens or hundreds of explicit rounds, context
-compression, restart, rejection and backtrack because every prompt is compiled
-from durable facts rather than from a summary of the previous prompt. It does
-not keep an Agent running after the client task ends. Use one loop per clear
-objective; for a large roadmap, let the Agent carry explicit outcomes between
-independent loops instead of creating an endless session.
-
-## Reliability boundaries
-
-Malformed canonical reports are rejected without changing the current session,
-round or vault, so callers can retry the same logical round. Persistence
-failures are returned as errors and never become a successful or partial
-commit. Drift clarification requires an explanation and a runtime-verifiable
-anchor; agent waiver flags are not accepted. `loopforge doctor` diagnoses
-unknown, deprecated, type-invalid and removed policy keys. Automatic Git
-restore is intentionally not implemented. Persistence and evidence collection
-are asynchronous; corrupt JSON, invalid event formats and sequence gaps return
-`storage_corruption` instead of a partial status. `maxRounds` must be a positive
-integer within the configured policy limit.
+---
+
+## Key capabilities
+
+- Structured evaluation with strict core fields, lenient optional normalization,
+  and retryable `evaluation_invalid` responses.
+- One committed-round history for the compiler, contracts, gates, Replay,
+  Audit, and Metrics.
+- One Canonical State for prompts, the optional state file, and current-status
+  cognition.
+- Evidence-backed accept, reject, backtrack, and terminate decisions, including
+  Round Contract and workspace-restore checks.
+- L0, L1, and L2 prompt density, five-state sub-goals, constraint lifecycle,
+  milestones, and agent-requested emphasis or confusion points.
+- Separate Replay and Audit views. Replay answers what happened; Audit checks
+  evidence and completeness.
+- Durable sessions with atomic round documents, sequence checks, owned locks,
+  renewable leases, pause, resume, and idempotent recovery.
+- Nine MCP tools: `start`, `next`, `status`, `stop`, `pause`, `resume`, `replay`,
+  `gate_check`, and `gate_resolve`.
+- Zero runtime dependencies. Policy controls thresholds, budgets, and intervals.
+
+---
 
 ## Development
 
 ```bash
 npm run check
 npm test
-npm run build
-npm run verify:artifacts
-npm pack --dry-run --json --ignore-scripts
+npm pack --dry-run --json
 ```
 
-The schema in the repository's `loopforge-protocol.json` is generated from
-`src/protocol.ts`.
-Do not edit it by hand. `init` installs `skills/perception/SKILL.md` for the
-selected client and prints its MCP registration command.
+The protocol schema in `../loopforge-protocol.json` is generated from `src/protocol.ts`. Do not edit it by hand.
+
+---
 
 ## License
 

package/dist/audit.d.ts

@@ -0,0 +1,50 @@
+/** v2.12: Read-only, replayable end-of-loop audit — the verification view.
+ *
+ *  Positioning vs loopforge_replay: replay is the factual timeline (what
+ *  happened per round); audit is the assessment layer (which claims are
+ *  machine-verified, which gates were decided, is the sequence intact).
+ *  Everything is derived from committed vault entries — audit never writes.
+ */
+import type { LoopStore } from "./loop-store.js";
+import type { VaultEntry } from "./loop-store.js";
+export interface AuditRound {
+    round: number;
+    outcome: string;
+    claims: Array<{
+        text: string;
+        status: "verified" | "unverified" | "no_evidence";
+    }>;
+    checks: Array<{
+        check: string;
+        severity: string;
+        verdict: "failed" | "warn" | "info";
+    }>;
+}
+export interface AuditGate {
+    gateId: string;
+    kind: "user" | "agent";
+    actionHash: string;
+    approved: boolean;
+    decidedAt: string;
+    round: number;
+}
+export interface AuditResult {
+    loopId: string;
+    verdict: "passed" | "incomplete" | "contradicted";
+    rounds: AuditRound[];
+    gates: AuditGate[];
+    unresolvedUserGates: string[];
+    criteria: {
+        declared: number;
+        evidenced: number;
+        missing: number;
+    };
+    sequenceComplete: boolean;
+    /** False when no LoopStore was provided (sequence/provenance degraded). */
+    provenanceAvailable: boolean;
+}
+/** Build the audit from committed vault entries. Pure, read-only.
+ *  @param store Optional LoopStore — when provided, sequence integrity is
+ *  checked and provenanceAvailable becomes true. */
+export declare function buildAudit(loopId: string, entries: VaultEntry[], store?: LoopStore): AuditResult;
+//# sourceMappingURL=audit.d.ts.map

package/dist/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAIlD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,UAAU,GAAG,YAAY,GAAG,aAAa,CAAA;KAAE,CAAC,CAAC;IACnF,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC,CAAC;CACzF;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,QAAQ,GAAG,YAAY,GAAG,cAAc,CAAC;IAClD,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,QAAQ,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACnE,gBAAgB,EAAE,OAAO,CAAC;IAC1B,2EAA2E;IAC3E,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAMD;;oDAEoD;AACpD,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,UAAU,EAAE,EACrB,KAAK,CAAC,EAAE,SAAS,GAChB,WAAW,CAgHb"}

package/dist/audit.js

@@ -0,0 +1,131 @@
+/** v2.12: Read-only, replayable end-of-loop audit — the verification view.
+ *
+ *  Positioning vs loopforge_replay: replay is the factual timeline (what
+ *  happened per round); audit is the assessment layer (which claims are
+ *  machine-verified, which gates were decided, is the sequence intact).
+ *  Everything is derived from committed vault entries — audit never writes.
+ */
+import { eventSequence, StorageCorruptionError } from "./loop-store.js";
+import { auditOrder, deriveGate } from "./cognitive-governance.js";
+import { rederiveClaimViewWithFlags, listVerifiedClaims } from "./evidence-claims.js";
+import { isRecord, entryRound as sharedEntryRound } from "./token-utils.js";
+import { decodeCommittedRound } from "./committed-round.js";
+function entryRound(entry) {
+    return sharedEntryRound(entry);
+}
+/** Build the audit from committed vault entries. Pure, read-only.
+ *  @param store Optional LoopStore — when provided, sequence integrity is
+ *  checked and provenanceAvailable becomes true. */
+export function buildAudit(loopId, entries, store) {
+    const ordered = auditOrder(entries);
+    // ── Rounds: per-round claims + checks from committed snapshots ─────────
+    const rounds = [];
+    for (const entry of ordered) {
+        const taskId = String(entry.task_id ?? "");
+        if (!taskId.startsWith(`loop:${loopId}:r`) || !taskId.endsWith(":feedback"))
+            continue;
+        const committed = decodeCommittedRound(entry);
+        if (!committed)
+            continue;
+        // v2.14: rounds committed with action="backtrack" were rolled back —
+        // they are not part of the loop's final history. Counting them would
+        // inflate the round list and let their error flags flip the verdict.
+        if (committed.action === "backtrack")
+            continue;
+        const round = entryRound(entry);
+        const outcome = committed.outcome ?? "unknown";
+        const claimView = committed.evaluation
+            ? rederiveClaimViewWithFlags(committed.evaluation, (committed.afterEvidence.length > 0
+                ? committed.afterEvidence
+                : committed.roundEvidence), committed.verificationFlags)
+            : null;
+        rounds.push({
+            round,
+            outcome,
+            claims: claimView
+                ? claimView.claims.map((claim) => ({
+                    text: claim.targetId,
+                    status: claim.status === "verified" ? "verified" : "unverified",
+                }))
+                : [],
+            checks: committed.verificationFlags.map((flag) => ({
+                check: flag.check,
+                severity: flag.severity,
+                verdict: flag.severity === "error" ? "failed" : flag.severity,
+            })),
+        });
+    }
+    // ── Gates: latest decision wins; opened-without-decision stays open ────
+    const decisionsByGate = new Map();
+    const openedGates = new Map();
+    for (const entry of ordered) {
+        const gateId = String(entry.gate_id ?? "");
+        if (!gateId)
+            continue;
+        if (entry.task_type === "gate_decision" && isRecord(entry.gate_decision)) {
+            const decision = entry.gate_decision;
+            decisionsByGate.set(gateId, {
+                gateId,
+                kind: decision.kind === "agent" ? "agent" : "user",
+                actionHash: typeof decision.actionHash === "string" ? decision.actionHash : "",
+                approved: decision.approved === true,
+                decidedAt: typeof decision.decidedAt === "string" ? decision.decidedAt : "",
+                round: entryRound(entry),
+            });
+        }
+        else if (entry.task_type === "gate_opened") {
+            openedGates.set(gateId, {
+                description: typeof entry.gate_action === "string" ? entry.gate_action : gateId,
+                round: entryRound(entry),
+            });
+        }
+    }
+    const gates = [...decisionsByGate.values()];
+    const unresolvedUserGates = [];
+    for (const [gateId, opened] of openedGates) {
+        if (decisionsByGate.has(gateId))
+            continue;
+        // Re-derive the classification from the recorded action text.
+        const { gate } = deriveGate(opened.description);
+        if (gate.kind === "user") {
+            unresolvedUserGates.push(`${gateId} (round ${opened.round}): ${opened.description}`);
+        }
+    }
+    // ── Sequence integrity (P0) ────────────────────────────────────────────
+    let sequenceComplete = true;
+    let provenanceAvailable = store !== undefined;
+    if (store) {
+        try {
+            const sequences = eventSequence(store, loopId);
+            const max = sequences.length > 0 ? Math.max(...sequences) : 0;
+            sequenceComplete = sequences.length === max;
+        }
+        catch (error) {
+            sequenceComplete = false;
+            if (!(error instanceof StorageCorruptionError))
+                throw error;
+        }
+    }
+    // ── Criteria accounting + verdict ──────────────────────────────────────
+    const verified = listVerifiedClaims(entries, loopId);
+    const declared = rounds.reduce((sum, round) => sum + round.claims.length, 0);
+    const evidenced = verified.length;
+    let verdict = "passed";
+    if (rounds.some((round) => round.checks.some((check) => check.verdict === "failed"))) {
+        verdict = "contradicted";
+    }
+    else if (unresolvedUserGates.length > 0 || (declared > 0 && evidenced === 0)) {
+        verdict = "incomplete";
+    }
+    return {
+        loopId,
+        verdict,
+        rounds,
+        gates,
+        unresolvedUserGates,
+        criteria: { declared, evidenced, missing: Math.max(0, declared - evidenced) },
+        sequenceComplete,
+        provenanceAvailable,
+    };
+}
+//# sourceMappingURL=audit.js.map

package/dist/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAEtF,OAAO,EAAE,QAAQ,EAAE,UAAU,IAAI,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AA8B5D,SAAS,UAAU,CAAC,KAAiB;IACnC,OAAO,gBAAgB,CAAC,KAA2C,CAAC,CAAC;AACvE,CAAC;AAED;;oDAEoD;AACpD,MAAM,UAAU,UAAU,CACxB,MAAc,EACd,OAAqB,EACrB,KAAiB;IAEjB,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;IAEpC,0EAA0E;IAC1E,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,QAAQ,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC;YAAE,SAAS;QACtF,MAAM,SAAS,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;QAC9C,IAAI,CAAC,SAAS;YAAE,SAAS;QACzB,qEAAqE;QACrE,qEAAqE;QACrE,qEAAqE;QACrE,IAAI,SAAS,CAAC,MAAM,KAAK,WAAW;YAAE,SAAS;QAC/C,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;QAChC,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,IAAI,SAAS,CAAC;QAC/C,MAAM,SAAS,GAAG,SAAS,CAAC,UAAU;YACpC,CAAC,CAAC,0BAA0B,CACxB,SAAS,CAAC,UAAU,EACpB,CAAC,SAAS,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC;gBACjC,CAAC,CAAC,SAAS,CAAC,aAAa;gBACzB,CAAC,CAAC,SAAS,CAAC,aAAa,CAAY,EACvC,SAAS,CAAC,iBAAiB,CAC5B;YACH,CAAC,CAAC,IAAI,CAAC;QACT,MAAM,CAAC,IAAI,CAAC;YACV,KAAK;YACL,OAAO;YACP,MAAM,EAAE,SAAS;gBACf,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;oBAC/B,IAAI,EAAE,KAAK,CAAC,QAAQ;oBACpB,MAAM,EAAE,KAAK,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,UAAmB,CAAC,CAAC,CAAC,YAAqB;iBAClF,CAAC,CAAC;gBACL,CAAC,CAAC,EAAE;YACN,MAAM,EAAE,SAAS,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBACjD,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,OAAO,EAAE,IAAI,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,QAAiB,CAAC,CAAC,CAAC,IAAI,CAAC,QAA2B;aAC1F,CAAC,CAAC;SACJ,CAAC,CAAC;IACL,CAAC;IAED,0EAA0E;IAC1E,MAAM,eAAe,GAAG,IAAI,GAAG,EAAqB,CAAC;IACrD,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkD,CAAC;IAC9E,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM;YAAE,SAAS;QACtB,IAAI,KAAK,CAAC,SAAS,KAAK,eAAe,IAAI,QAAQ,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC;YACzE,MAAM,QAAQ,GAAG,KAAK,CAAC,aAAwC,CAAC;YAChE,eAAe,CAAC,GAAG,CAAC,MAAM,EAAE;gBAC1B,MAAM;gBACN,IAAI,EAAE,QAAQ,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM;gBAClD,UAAU,EAAE,OAAO,QAAQ,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE;gBAC9E,QAAQ,EAAE,QAAQ,CAAC,QAAQ,KAAK,IAAI;gBACpC,SAAS,EAAE,OAAO,QAAQ,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE;gBAC3E,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC;aACzB,CAAC,CAAC;QACL,CAAC;aAAM,IAAI,KAAK,CAAC,SAAS,KAAK,aAAa,EAAE,CAAC;YAC7C,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE;gBACtB,WAAW,EAAE,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM;gBAC/E,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC;aACzB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,MAAM,KAAK,GAAG,CAAC,GAAG,eAAe,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5C,MAAM,mBAAmB,GAAa,EAAE,CAAC;IACzC,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;QAC3C,IAAI,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,SAAS;QAC1C,8DAA8D;QAC9D,MAAM,EAAE,IAAI,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAChD,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACzB,mBAAmB,CAAC,IAAI,CAAC,GAAG,MAAM,WAAW,MAAM,CAAC,KAAK,MAAM,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;QACvF,CAAC;IACH,CAAC;IAED,0EAA0E;IAC1E,IAAI,gBAAgB,GAAG,IAAI,CAAC;IAC5B,IAAI,mBAAmB,GAAG,KAAK,KAAK,SAAS,CAAC;IAC9C,IAAI,KAAK,EAAE,CAAC;QACV,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAC/C,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC9D,gBAAgB,GAAG,SAAS,CAAC,MAAM,KAAK,GAAG,CAAC;QAC9C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,gBAAgB,GAAG,KAAK,CAAC;YACzB,IAAI,CAAC,CAAC,KAAK,YAAY,sBAAsB,CAAC;gBAAE,MAAM,KAAK,CAAC;QAC9D,CAAC;IACH,CAAC;IAED,0EAA0E;IAC1E,MAAM,QAAQ,GAAG,kBAAkB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACrD,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAC7E,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC;IAElC,IAAI,OAAO,GAA2B,QAAQ,CAAC;IAC/C,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,EAAE,CAAC;QACrF,OAAO,GAAG,cAAc,CAAC;IAC3B,CAAC;SAAM,IAAI,mBAAmB,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,IAAI,SAAS,KAAK,CAAC,CAAC,EAAE,CAAC;QAC/E,OAAO,GAAG,YAAY,CAAC;IACzB,CAAC;IAED,OAAO;QACL,MAAM;QACN,OAAO;QACP,MAAM;QACN,KAAK;QACL,mBAAmB;QACnB,QAAQ,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC,EAAE;QAC7E,gBAAgB;QAChB,mBAAmB;KACpB,CAAC;AACJ,CAAC"}

package/dist/canonical-state.d.ts

@@ -3,16 +3,52 @@
  * The canonical state is data, not Markdown. Prompt and state-file renderers
  * consume the same value so they cannot silently drift apart.
  */
-import type { ConstraintMeta, LoopCompileRequest, LoopCompileResponse, SubGoal, VerificationFlag, DerivedGate, HandoffProjection, PhaseHistoryEntry, TodoProjection } from "./protocol.js";
-export declare const CANONICAL_STATE_FORMAT: "loopforge.state";
+import type { ConstraintMeta, CriterionStatus, Lesson, LoopCompileRequest, LoopCompileResponse, MilestoneSummary, RoundContract, SubGoal, VerificationFlag } from "./protocol.js";
+export declare const CANONICAL_STATE_SCHEMA_VERSION: 1;
+/** v3.2: Durable snapshot of what an L1 prompt actually presented last round.
+ *  Used as the diff baseline for L1 collapse. Persisted inside the lineage
+ *  entry's loop_lineage (field extension — no new persistence format) and
+ *  carried on PromptArtifact for the compile-to-persist round-trip. */
+export interface PresentedStateSnapshot {
+    /** Round whose presentation this snapshot describes (the baseline round). */
+    round: number;
+    /** Stable IDs (c-XXXXXXXX) of constraints rendered in the L1 Active
+     *  Constraints section (post-emphasize, non-hard). */
+    constraintIds: string[];
+    /** [sub-goal id, status] pairs rendered in the L1 Active Sub-Goals section
+     *  (in_progress + pending only). Statuses enable transition detection. */
+    subGoals: Array<[string, string]>;
+    /** [start, end] round ranges of all milestones at presentation time. */
+    milestoneRanges: Array<[number, number]>;
+}
+/** v3.3: Per-round statistics for the display (files changed, rejected
+ *  attempts, self-reported progress delta). Compiler-derived from committed
+ *  entries — zero persistence. Optional: absent when no committed rounds. */
+export interface RoundStat {
+    round: number;
+    filesChangedCount: number | null;
+    rejectedAttempts: number | null;
+    progressDelta: number | null;
+}
+/** v3.3: Machine git-motion cross-check over the last committed rounds.
+ *  Display-only companion to the R4/R5 exculpatory signal. Optional:
+ *  absent when no committed rounds carry git snapshots — the object, when
+ *  present, always carries definite values (v3.6: the null arms were dead —
+ *  the derive path returns undefined wholesale instead of null fields). */
+export interface MachineStatus {
+    windowRounds: number;
+    gitMotion: boolean;
+    motionRounds: number;
+}
 export interface CanonicalLoopState {
-    format: "loopforge.state";
+    schemaVersion: typeof CANONICAL_STATE_SCHEMA_VERSION;
     loopId: string;
     round: number;
     maxRounds: number;
     goalId: string;
     objective: string;
     objectiveVersion: number;
+    currentTask: string;
     successCriteria: string[];
     hardConstraints: string[];
     activeConstraints: string[];
@@ -26,17 +62,23 @@ export interface CanonicalLoopState {
     blockers: string[];
     verificationFlags: VerificationFlag[];
     discoveries: string[];
+    nextAction: string;
     rollingOutcomes: string[];
     recurringIssues: string[];
     failedPatterns: string[];
-    /** v2.1: Single-paragraph loop-level synthesis (formulaic). */
-    loopSynthesis: string;
+    /** v2.1: Phase-boundary milestone summaries that survive window eviction. */
+    milestones: MilestoneSummary[];
     /** v2.2: Structured sub-goals with compiler-managed lifecycle. */
     subGoals: SubGoal[];
+    /** v3.2: Derived per-criterion status (goal → criteria → evidence view). */
+    criterionStatuses: CriterionStatus[];
+    /** v3.2: Deterministic lessons learned (repeated violations / failures). */
+    lessons: Lesson[];
     /** v2.5: Agent trust score [0, 1] from verification flags. */
     agentTrustScore: number | undefined;
     /** v2.5: Trust trend over last 10 rounds. */
     agentTrustTrend: number[];
+    suggestedNextTask: string;
     externalContext: string;
     stateFilePath: string;
     progress: {
@@ -50,29 +92,62 @@ export interface CanonicalLoopState {
             skipped: number;
         } | null;
     };
-    /** Derived obligations that must be rechecked after a change. */
-    regressionObligations: Array<{
-        id: string;
-        description: string;
-        sourceRound: number;
-        evidenceRefs: string[];
-        status: "open" | "satisfied" | "contradicted";
-    }>;
-    /** Derived views. They are rebuilt on every compile and are not a
-     * second transaction truth. */
-    phaseHistory: PhaseHistoryEntry[];
-    currentFocus: string;
-    todoProjection: TodoProjection | null;
-    suggestedNextAction: string;
-    activeGate: DerivedGate | null;
-    stateFreshness: "fresh" | "stale" | "missing";
-    handoff: HandoffProjection;
+    /** v3.3: Display-only round stats over the last committed rounds.
+     *  Conditional presence: absent when there are no committed rounds. */
+    roundStats?: RoundStat[];
+    /** v3.3: Machine git-motion cross-check for the progress dashboard.
+     *  Conditional presence: absent when no committed git snapshots exist. */
+    machineStatus?: MachineStatus;
+    /** v3.4: The ACTIVE Round Contract this round executes under —
+     *  compile-derived from committed rounds (never the submission's own
+     *  round_contract, which is a proposal for the NEXT round). Conditional
+     *  presence: absent without an active contract — keeps state hashes
+     *  byte-identical for contract-less rounds. */
+    roundContract?: RoundContract;
 }
 /** Deterministic JSON serialization used by state and prompt hashes. */
 export declare function stableStringify(value: unknown): string;
 export declare function hashCanonicalState(state: CanonicalLoopState): string;
 /** Human/Agent-readable materialized view. It is always reproducible from the
  * canonical state and is never consulted as transaction truth. */
+/** v3.3: Forward-looking "roadmap" view derived from existing state — loop
+ *  position, met/remaining criteria (with IDs), and sub-goal activity.
+ *
+ *  Deliberately label-free: milestone labels/ranges are collapsed content in
+ *  L1 (the diff-collapse invariant) and are rendered in full by Phase
+ *  History everywhere else — the roadmap only reports "N rounds since the
+ *  last milestone boundary", never the boundary's identity. Next action is
+ *  likewise excluded: every level renders its own Next Action section.
+ *  Shared by the state-file and prompt renderers so they cannot silently
+ *  drift apart (module contract above). Returns [] — renders nothing —
+ *  when the state carries none of these. Presentation only; never feeds
+ *  enforcement. */
+export declare function buildRoadmap(state: CanonicalLoopState): string[];
+/** v3.3/v3.4: Render the ACTIVE Round Contract as the Current Task section
+ *  body — the single formatting source shared by prompts and the state
+ *  file (module contract above). The original objective is NOT here: it
+ *  lives in the Objective section. Empty arrays render no line. */
+export declare function formatRoundContract(contract: RoundContract): string;
+/** The trust bar line ("██████░░░░ 60%"). The L2 Agent Trust section and the
+ *  detailed L1 renderer used to carry private copies of this formula — shared
+ *  here so a formatting change is made once (module contract: renderers must
+ *  not silently drift apart). */
+export declare function trustBarLine(score: number): string;
+/** Milestone heading line ("**🏁 Round 7** (Rounds 3–7, 60%)"). Shared by the
+ *  L2 Phase History and the detailed L1 renderer; the L1 copy previously
+ *  rendered the range as "R3–R7", a format only this heading used. */
+export declare function milestoneHeading(milestone: MilestoneSummary): string;
 export declare function renderCanonicalStateMarkdown(state: CanonicalLoopState): string;
-export declare function createCanonicalLoopState(request: LoopCompileRequest, response: LoopCompileResponse, stateFilePath: string): CanonicalLoopState;
+export declare function createCanonicalLoopState(request: LoopCompileRequest, response: LoopCompileResponse, stateFilePath: string, 
+/** v3.3: Display-only derived data (round stats, machine git-motion).
+ *  Optional 4th param — callers that predate v3.3 stay on 3-arg calls. */
+derived?: {
+    roundStats?: RoundStat[];
+    machineStatus?: MachineStatus;
+    /** v3.4: ACTIVE Round Contract for this round (compile-derived from the
+     *  committed evals of earlier rounds — see loop-compiler). Drives the
+     *  Current Task. Never the submission's own round_contract field, which
+     *  is a proposal for the NEXT round. */
+    roundContract?: RoundContract | null;
+}): CanonicalLoopState;
 //# sourceMappingURL=canonical-state.d.ts.map