loopforge 3.7.1 → 3.8.1

package/README.md

@@ -1,169 +1,171 @@
-# LoopForge
-
-**A context window is not memory. Memory needs a runtime.**
-
-> **Version per `package.json`** — `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, a verification gate
-organized into four domains (evaluation consistency, evidence integrity, plan
-& contract, progress & recovery), and an enforcement gate driven by one
-ordered strategy table across four action classes (evidence contradiction,
-contract & scope, plan drift, progress recovery). 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. A stalled-
-progress evaluator 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
-
-```bash
-npm install -g loopforge
-loopforge init --client claude
-claude mcp add loopforge -- npx loopforge mcp
-```
-
-Works with Claude Code, Codex CLI, or any MCP-compatible client.
-
-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
-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
-```
-
----
-
-## 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. A backtrack carries a derived
-  Recovery Brief — trigger rule, restore point, redo round ID, failed
-  approaches, and falsified assumptions — sourced from committed rounds plus
-  the in-flight attempt (never rejected payloads); the redo reuses the round
-  ID and its commit retires the brief.
-- L0, L1, and L2 prompt density, five-state sub-goals with explicit
-  `subgoal_updates` transitions (active `sg-` IDs only; done/canceled are
-  terminal), constraint lifecycle, milestones, and agent-requested emphasis or
-  confusion points. Prompts and the state file render active sub-goals only,
-  capped by policy; the state file is grouped into Current / Recent /
-  Historical Summary tiers with derived metadata (round, attempt, state hash)
-  and is byte-identical when regenerated from the Vault.
-- 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`. The two gate tools are opt-in
-  (`policy.gate.enabled`, default false): hidden from `tools/list`, structured
-  preflight via `gate_check`, round-blocking on unapproved `gate_ids`
-  citations.
-- Zero runtime dependencies. Policy controls thresholds, budgets, and intervals.
-
----
-
-## Development
-
-```bash
-npm run check
-npm test
-npm pack --dry-run --json
-```
-
-The protocol schema in `../loopforge-protocol.json` is generated from `src/protocol.ts`. Do not edit it by hand.
-
----
-
-## License
-
-MIT
+# LoopForge
+
+**A context window is not memory. Memory needs a runtime.**
+
+> **Version per `package.json`** — `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, a verification gate
+organized into four domains (evaluation consistency, evidence integrity, plan
+& contract, progress & recovery), and an enforcement gate driven by one
+ordered strategy table — the row order is the priority, and each row names
+the check it reacts to plus its escalation ladder. 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. A stalled-
+progress evaluator 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
+
+```bash
+npm install -g loopforge
+loopforge init --client claude
+claude mcp add loopforge -- npx loopforge mcp
+```
+
+Works with Claude Code, Codex CLI, or any MCP-compatible client.
+
+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
+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
+```
+
+---
+
+## 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. A backtrack carries a derived
+  Recovery Brief — trigger rule, restore point, redo round ID, failed
+  approaches, and falsified assumptions — sourced from committed rounds plus
+  the in-flight attempt (never rejected payloads); the redo reuses the round
+  ID and its commit retires the brief.
+- L0, L1, and L2 prompt density, five-state sub-goals with explicit
+  `subgoal_updates` transitions (active `sg-` IDs only; done/canceled are
+  terminal), constraint lifecycle, milestones, and agent-requested emphasis
+  (by stable id or exact text) or confusion points. Prompts and the state file
+  render active sub-goals only, capped by policy; the state file is grouped
+  into Current / Recent / Historical Summary tiers with derived metadata
+  (round, attempt, state hash) and is byte-identical when regenerated from the
+  Vault — its content depends on committed facts, not on which prompt level
+  compiled.
+- 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`. The two gate tools are opt-in
+  (`policy.gate.enabled`, default false): hidden from `tools/list`, structured
+  preflight via `gate_check`, round-blocking on unapproved `gate_ids`
+  citations.
+- Zero runtime dependencies. Policy controls thresholds, budgets, and intervals.
+
+---
+
+## Development
+
+```bash
+npm run check
+npm test
+npm pack --dry-run --json
+```
+
+The protocol schema in `../loopforge-protocol.json` is generated from `src/protocol.ts`. Do not edit it by hand.
+
+---
+
+## License
+
+MIT

package/dist/audit.d.ts

@@ -4,21 +4,39 @@
  *  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.
+ *
+ *  v3.8: the CONTRACT ITEM axis is the primary completion basis. The criterion
+ *  claims stay as an advisory second view — a criterion claim is an agent
+ *  statement whose machine backing is mediated by the contract items, so it
+ *  cannot be the completion signal. Both axes read the same committed-round
+ *  model and the same item reducer the coordinator and explain use.
  */
 import type { LoopStore } from "./loop-store.js";
 import type { VaultEntry } from "./loop-store.js";
+import type { ContractItemStatus } from "./protocol.js";
 export interface AuditRound {
     round: number;
     outcome: string;
     claims: Array<{
         text: string;
-        status: "verified" | "unverified" | "no_evidence";
+        status: "verified" | "unverified";
     }>;
     checks: Array<{
         check: string;
         severity: string;
         verdict: "failed" | "warn" | "info";
     }>;
+    /** v3.8: the contract this round EXECUTED under and each item's status as of
+     *  this round — the same derivation `explain` renders. */
+    contract: {
+        id: string;
+        declared_at_round: number;
+        closure: string;
+        items: Array<{
+            itemId: string;
+            status: ContractItemStatus;
+        }>;
+    } | null;
 }
 export interface AuditGate {
     gateId: string;
@@ -28,12 +46,42 @@ export interface AuditGate {
     decidedAt: string;
     round: number;
 }
+/** v3.8: One contract's outcome over the loaned loop, keyed by its content-
+ *  addressed id. Re-declaring the same contract later extends the same entry —
+ *  the identity says it IS the same contract. */
+export interface AuditContract {
+    contract_id: string;
+    declared_at_round: number;
+    first_active_round: number;
+    last_active_round: number;
+    closure: "open" | "verified" | "blocked";
+    closed_at_round: number | null;
+    /** Item statuses as of the last round the contract was execution-relevant. */
+    items: Array<{
+        itemId: string;
+        description: string;
+        status: ContractItemStatus;
+    }>;
+}
+export interface AuditContractSummary {
+    contracts: AuditContract[];
+    /** Contracts whose final closure is still `open`. */
+    open: number;
+    verifiedItems: number;
+    insufficientItems: number;
+    contradictedItems: number;
+    pendingItems: number;
+}
 export interface AuditResult {
     loopId: string;
     verdict: "passed" | "incomplete" | "contradicted";
     rounds: AuditRound[];
     gates: AuditGate[];
     unresolvedUserGates: string[];
+    /** v3.8: the verification skeleton — the primary completion basis. */
+    contracts: AuditContractSummary;
+    /** Advisory second axis: criterion claims, not the completion signal.
+     *  `declared` and `evidenced` are both DISTINCT-id counts, so they compare. */
     criteria: {
         declared: number;
         evidenced: number;
@@ -42,6 +90,10 @@ export interface AuditResult {
     sequenceComplete: boolean;
     /** False when no LoopStore was provided (sequence/provenance degraded). */
     provenanceAvailable: boolean;
+    /** v3.8: rounds whose persisted transaction carries a legacy schema
+     *  version. They are NOT part of history (the version break is hard) — this
+     *  list makes the loss visible instead of letting the loop look complete. */
+    legacyRounds: number[];
 }
 /** Build the audit from committed vault entries. Pure, read-only.
  *  @param store Optional LoopStore — when provided, sequence integrity is

package/dist/audit.d.ts.map

@@ -1 +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;AAED;;oDAEoD;AACpD,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,UAAU,EAAE,EACrB,KAAK,CAAC,EAAE,SAAS,GAChB,WAAW,CA8Gb"}
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"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"}

package/dist/audit.js

@@ -4,36 +4,63 @@
  *  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.
+ *
+ *  v3.8: the CONTRACT ITEM axis is the primary completion basis. The criterion
+ *  claims stay as an advisory second view — a criterion claim is an agent
+ *  statement whose machine backing is mediated by the contract items, so it
+ *  cannot be the completion signal. Both axes read the same committed-round
+ *  model and the same item reducer the coordinator and explain use.
  */
 import { eventSequence, StorageCorruptionError } from "./loop-store.js";
 import { auditOrder, deriveGate } from "./cognitive-governance.js";
 import { rederiveClaimViewWithFlags, listVerifiedClaims } from "./evidence-claims.js";
 import { isRecord, entryRound } from "./token-utils.js";
-import { decodeCommittedRound, machineEvidenceForRound } from "./committed-round.js";
+import { legacyTransactionRounds, machineEvidenceForRound, readOnlyRounds, } from "./committed-round.js";
+import { deriveRoundContractView } from "./round-contract.js";
+import { getPolicy } from "./policy.js";
 /** 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);
+    // v3.8: the shared committed-round read model — ordering, dedup and rollback
+    // exclusion come from it, not from a private rule. v3.8.1: the READ-ONLY
+    // window, which additionally applies the session frontier while a committed
+    // rollback directive is in effect, so a backtracked branch is not audited as
+    // this branch's history.
+    const views = readOnlyRounds(entries).filter((view) => view.loopId === loopId);
+    const commands = getPolicy().evidence.commands ?? [];
+    // The executed contract per round, through the ONE derivation explain and
+    // the live coordinator also call. Re-derived per round rather than walked
+    // incrementally on purpose: a private incremental walker would be a second
+    // history interpretation, which is exactly what this project forbids.
+    const contractByRound = new Map();
+    for (const view of views) {
+        contractByRound.set(view.round, deriveRoundContractView({
+            rounds: views,
+            round: view.round,
+            report: view.executionReport,
+            observations: view.observationDelta,
+            outcome: view.outcome,
+            commands,
+        }));
+    }
     // ── Rounds: per-round claims + checks from committed snapshots ─────────
+    //
+    // v3.8.1: the list is built from the SAME window the contract axis below
+    // reads. Scanning the raw entries here applied a second, weaker history
+    // rule — no replacement of a round by a later record of the same logical
+    // round — so a superseded record was listed twice and could still flip the
+    // verdict to `contradicted`, while explain (which reads only the window)
+    // reported a different loop. Rollback exclusion comes from the window too.
     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, machineEvidenceForRound(committed), committed.verificationFlags)
+    for (const view of views) {
+        const round = view.round;
+        const outcome = view.outcome ?? "unknown";
+        const claimView = view.evaluation
+            ? rederiveClaimViewWithFlags(view.evaluation, machineEvidenceForRound(view), view.verificationFlags)
             : null;
+        const executed = contractByRound.get(round);
         rounds.push({
             round,
             outcome,
@@ -43,13 +70,57 @@ export function buildAudit(loopId, entries, store) {
                     status: claim.status === "verified" ? "verified" : "unverified",
                 }))
                 : [],
-            checks: committed.verificationFlags.map((flag) => ({
+            checks: view.verificationFlags.map((flag) => ({
                 check: flag.check,
                 severity: flag.severity,
                 verdict: flag.severity === "error" ? "failed" : flag.severity,
             })),
+            contract: executed?.contract && executed.statuses.contractId
+                ? {
+                    id: executed.statuses.contractId,
+                    declared_at_round: executed.contract.declared_at_round,
+                    closure: executed.statuses.closure,
+                    items: executed.statuses.items.map((item) => ({
+                        itemId: item.itemId,
+                        status: item.status,
+                    })),
+                }
+                : null,
         });
     }
+    // ── Contract item axis — the verification skeleton ─────────────────────
+    const contractsById = new Map();
+    for (const view of views) {
+        const executed = contractByRound.get(view.round);
+        if (!executed?.contract || !executed.statuses.contractId)
+            continue;
+        const id = executed.statuses.contractId;
+        const existing = contractsById.get(id);
+        contractsById.set(id, {
+            contract_id: id,
+            declared_at_round: existing?.declared_at_round ?? executed.contract.declared_at_round,
+            first_active_round: existing?.first_active_round ?? view.round,
+            last_active_round: view.round,
+            closure: executed.statuses.closure,
+            closed_at_round: executed.statuses.closed_at_round,
+            items: executed.statuses.items.map((item) => ({
+                itemId: item.itemId,
+                description: item.description,
+                status: item.status,
+            })),
+        });
+    }
+    const contracts = [...contractsById.values()]
+        .sort((a, b) => a.first_active_round - b.first_active_round || a.contract_id.localeCompare(b.contract_id));
+    const flatItems = contracts.flatMap((contract) => contract.items);
+    const contractsSummary = {
+        contracts,
+        open: contracts.filter((contract) => contract.closure === "open").length,
+        verifiedItems: flatItems.filter((item) => item.status === "verified").length,
+        insufficientItems: flatItems.filter((item) => item.status === "insufficient").length,
+        contradictedItems: flatItems.filter((item) => item.status === "contradicted").length,
+        pendingItems: flatItems.filter((item) => item.status === "pending").length,
+    };
     // ── Gates: latest decision wins; opened-without-decision stays open ────
     const decisionsByGate = new Map();
     const openedGates = new Map();
@@ -101,15 +172,26 @@ export function buildAudit(loopId, entries, store) {
                 throw error;
         }
     }
-    // ── Criteria accounting + verdict ──────────────────────────────────────
+    // ── Criteria accounting (advisory second axis) + verdict ───────────────
+    //
+    // v3.8 fix: `declared` used to be a PER-ROUND SUM while `evidenced` was a
+    // DEDUPLICATED count — a criterion claimed in three rounds read as three
+    // declared against one evidenced, so `missing` was fiction. Both sides are
+    // now distinct-id counts over the same history and compare directly.
     const verified = listVerifiedClaims(entries, loopId);
-    const declared = rounds.reduce((sum, round) => sum + round.claims.length, 0);
+    const declaredIds = new Set(rounds.flatMap((round) => round.claims.map((claim) => claim.text)));
+    const declared = declaredIds.size;
     const evidenced = verified.length;
+    // v3.8: the contract item axis decides completion. A contradicted item is a
+    // machine denial; an open contract is unfinished verification; the claim
+    // axis only speaks when no contract item exists to speak for it.
     let verdict = "passed";
-    if (rounds.some((round) => round.checks.some((check) => check.verdict === "failed"))) {
+    if (rounds.some((round) => round.checks.some((check) => check.verdict === "failed")) ||
+        contractsSummary.contradictedItems > 0) {
         verdict = "contradicted";
     }
-    else if (unresolvedUserGates.length > 0 || (declared > 0 && evidenced === 0)) {
+    else if (unresolvedUserGates.length > 0 || contractsSummary.open > 0 ||
+        (declared > 0 && evidenced === 0)) {
         verdict = "incomplete";
     }
     return {
@@ -118,9 +200,11 @@ export function buildAudit(loopId, entries, store) {
         rounds,
         gates,
         unresolvedUserGates,
+        contracts: contractsSummary,
         criteria: { declared, evidenced, missing: Math.max(0, declared - evidenced) },
         sequenceComplete,
         provenanceAvailable,
+        legacyRounds: legacyTransactionRounds(entries).map((item) => item.round),
     };
 }
 //# sourceMappingURL=audit.js.map