@tea-agent/loop-agent 0.39.0-beta.7 → 0.39.0-beta.9

package/dist/workflows/dag/frontend-review-context.js

@@ -5,6 +5,8 @@ import { writeDagRunJsonArtifact } from "../../infrastructure/harness/artifact-s
 import { formatFrontendWorktreeDiffStdout, runFrontendWorktreeDiffGate, } from "./frontend-worktree-diff.js";
 import { frontendLintAssessmentArtifactSchema } from "./frontend-lint-baseline.js";
 import { deterministicSha256, frontendImplementationContractSchema, } from "./frontend-implementation-contract.js";
+import { resolveDagTaskSourcePath } from "../../task/dag-source-paths.js";
+import { ledgerStatsLine, parseLedgerJson } from "../../task/source-prepare/ledger.js";
 export const FRONTEND_REVIEW_CONTEXT_SCHEMA_ID = "frontend-review-context-v1";
 /**
  * Deterministically assemble the cumulative diff from a task baseline and the
@@ -20,7 +22,8 @@ export function assembleCumulativeDiffContext(input) {
         ...currentByPath.keys(),
     ]);
     const sortedPaths = [...allPaths].sort();
-    const perPath = sortedPaths.map((p) => {
+    const perPath = sortedPaths
+        .map((p) => {
         const baselineSha256 = baselineByPath.get(p) ?? null;
         const hasCurrent = currentByPath.has(p);
         const currentSha256 = hasCurrent
@@ -34,10 +37,17 @@ export function assembleCumulativeDiffContext(input) {
             status = hasCurrent ? "deleted" : "unchanged";
         }
         else {
-            status = currentSha256 === baselineSha256 ? "unchanged" : "modified";
+            status =
+                currentSha256 === baselineSha256 ? "unchanged" : "modified";
         }
         return { path: p, status, baselineSha256, currentSha256 };
-    });
+    })
+        // Cumulative diff carries only actual changes. The worktree baseline is
+        // the full repository inventory (git ls-files -co), so an unfiltered
+        // perPath enumerates thousands of unchanged hashes (e.g. 3000+ entries
+        // ≈ 700KB), ballooning the review context and blowing the review node
+        // read budget on a single read. Unchanged entries add no diff evidence.
+        .filter((entry) => entry.status !== "unchanged");
     const baselineDigest = deterministicSha256([...input.baselineEntries].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
     const cumulativeDigest = deterministicSha256(perPath);
     return {
@@ -45,7 +55,7 @@ export function assembleCumulativeDiffContext(input) {
         baselineDigest,
         perPath,
         cumulativeDigest,
-        empty: perPath.every((entry) => entry.status === "unchanged"),
+        empty: perPath.length === 0,
     };
 }
 async function sha256File(filePath) {
@@ -154,12 +164,31 @@ export function compareTypedReviewToLegacyJsonVerdict(input) {
             : `typed review verdict ${typedVerdict} maps to ${expected} but legacy JSON verdict is ${legacyVerdict}`,
     };
 }
+/**
+ * review-context 稳定失败枚举（AC-011 / AC-HARD-005）：v2 drift / manifest 失败返回
+ * 结构化、可消费的 failure code（稳定枚举 + reason 的 envelope），既有调用方无需字符串
+ * 匹配裸 Error 文本。message 保持人类可读（shell stderr 兼容），code 供机械化路由。
+ */
+export const FRONTEND_REVIEW_CONTEXT_FAILURE_CODES = [
+    "review-context-invalid-contract",
+    "review-context-verification-unbound",
+    "review-context-ledger-drift",
+    "review-context-manifest-missing",
+];
+export class FrontendReviewContextFailure extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = "FrontendReviewContextFailure";
+        this.code = code;
+    }
+}
 async function readRequiredJson(runDir, relativePath) {
     try {
         return JSON.parse(await readFile(path.join(runDir, relativePath), "utf8"));
     }
-    catch {
-        throw new Error(`frontend review context missing or invalid ${relativePath}`);
+    catch (error) {
+        throw new FrontendReviewContextFailure("review-context-manifest-missing", `frontend review context missing or invalid ${relativePath}: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
 async function readOptionalLintAssessment(runDir) {
@@ -211,8 +240,9 @@ async function readOptionalVerifyFailure(runDir) {
 }
 function assertReviewEvidence(input) {
     const contract = frontendImplementationContractSchema.safeParse(input.contract);
-    if (!contract.success)
-        throw new Error("frontend review context invalid implementation contract");
+    if (!contract.success) {
+        throw new FrontendReviewContextFailure("review-context-invalid-contract", "frontend review context invalid implementation contract");
+    }
     const trace = input.verificationTrace;
     const expectedTargets = new Map(contract.data.verificationTargets.map((target) => [target.id, target]));
     const actualTargets = Array.isArray(trace?.targets) ? trace.targets : [];
@@ -248,17 +278,15 @@ function assertReviewEvidence(input) {
         actualIds.size !== expectedTargets.size ||
         !mockEvidenceBound ||
         trace.mockStrategy !== contract.data.mockApi.strategy) {
-        throw new Error("frontend review context verification trace is not bound to a passing contract");
+        throw new FrontendReviewContextFailure("review-context-verification-unbound", "frontend review context verification trace is not bound to a passing contract");
     }
-    // M8: no repair-assessment hard requirement. When the artifact exists it must
-    // be schema-valid; when absent the verify failure capsule (if any) is
-    // already surfaced through the payload as verifyFailure.
 }
 export async function runFrontendReviewContextGate(input) {
     const contract = await readRequiredJson(input.runDir, "contracts/frontend-implementation-contract.json");
     const parsedContract = frontendImplementationContractSchema.safeParse(contract);
-    if (!parsedContract.success)
-        throw new Error("frontend review context invalid implementation contract");
+    if (!parsedContract.success) {
+        throw new FrontendReviewContextFailure("review-context-invalid-contract", "frontend review context invalid implementation contract");
+    }
     const diff = await runFrontendWorktreeDiffGate({
         ...input,
         authorizedChangedPaths: parsedContract.data.targets.files,
@@ -267,12 +295,15 @@ export async function runFrontendReviewContextGate(input) {
     const repairAssessment = await readOptionalRepairAssessment(input.runDir);
     const verifyFailure = await readOptionalVerifyFailure(input.runDir);
     const lintAssessment = await readOptionalLintAssessment(input.runDir);
-    assertReviewEvidence({ contract, verificationTrace });
     const cumulativeDiff = await captureCumulativeDiffContext({
         runDir: input.runDir,
         workspaceRoot: input.workspaceRoot,
         diff,
     });
+    assertReviewEvidence({ contract, verificationTrace, repairAssessment });
+    // Source fidelity ledger 核对（AC-008 / AC-FIDELITY-008）：ledger 缺失/漂移即阻断；
+    // 同时把核对清单注入 review-context 供最终 reviewer 机械化核对。
+    const sourceFidelity = await buildReviewSourceFidelityChecklist(input, parsedContract.data);
     const payload = {
         schemaVersion: 1,
         schemaId: FRONTEND_REVIEW_CONTEXT_SCHEMA_ID,
@@ -281,10 +312,13 @@ export async function runFrontendReviewContextGate(input) {
         ...(repairAssessment ? { repairAssessment } : {}),
         ...(verifyFailure ? { verifyFailure } : {}),
         ...(lintAssessment ? { lintAssessment } : {}),
+        sourceFidelity,
         diff: {
             schemaId: diff.schemaId,
             patchPath: diff.patchPath,
             patchSha256: diff.patchSha256,
+            reviewSummaryPath: diff.reviewSummaryPath,
+            reviewIndexPath: diff.reviewIndexPath,
             changedFiles: diff.changedFiles,
             untrackedFiles: diff.untrackedFiles,
             empty: diff.empty,
@@ -294,6 +328,59 @@ export async function runFrontendReviewContextGate(input) {
     const artifactPath = await writeDagRunJsonArtifact(input.runDir, "contracts/frontend-review-context.json", payload);
     return { ok: true, artifactPath, diff };
 }
+/**
+ * 最终 review 核对清单（机械化）：ledger 缺失/漂移、canonical requirement 漏项、
+ * diff 越界、验证证据缺失均阻断 pass。清单以有界安全摘要注入提示词，不泄漏原文。
+ */
+async function buildReviewSourceFidelityChecklist(input, contract) {
+    const binding = contract.sourceBinding;
+    const checklist = [];
+    // 契约级 sourceBinding 的 v2 语义：四个 ledger 字段必须齐全（缺失即 v1 遗留绑定）。
+    const boundV2 = Boolean(binding.ledgerPath) &&
+        Boolean(binding.ledgerSha256) &&
+        Boolean(binding.inputDigest) &&
+        binding.requirementToFragments !== undefined;
+    if (!boundV2) {
+        return {
+            bound: false,
+            ledger: null,
+            checklist: [
+                "source fidelity ledger: not bound (v1 binding); 按现有语义评审",
+                "canonical contract 与实际 diff 逐项核对，验证证据齐全后 verdict 可为 pass",
+            ],
+        };
+    }
+    const absolute = resolveDagTaskSourcePath({
+        workspaceRoot: input.workspaceRoot,
+        taskId: contract.sourceBinding.taskId,
+        sourcePath: binding.ledgerPath,
+    });
+    let ledger = null;
+    try {
+        const raw = await readFile(absolute, "utf8");
+        const actualSha = createHash("sha256").update(raw).digest("hex");
+        if (actualSha !== binding.ledgerSha256) {
+            throw new Error(`ledger sha256 mismatch (bound ${binding.ledgerSha256}, observed ${actualSha})`);
+        }
+        ledger = parseLedgerJson(raw);
+    }
+    catch (error) {
+        // AC-011 / AC-HARD-005：v2 drift 返回结构化 failure code（稳定枚举 + reason），
+        // 不再裸 throw new Error；message 保持人类可读供 shell stderr。
+        throw new FrontendReviewContextFailure("review-context-ledger-drift", `frontend review context source fidelity ledger unavailable or drifted: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    checklist.push("ledger: 存在且绑定 sha256 一致（无缺失/漂移）", `ledger 覆盖统计: ${ledgerStatsLine(ledger)}`, "canonical contract requirements 必须覆盖 ledger 全部 canonical requirement IDs", "实际 diff 必须限制在契约 targets 内（越界即阻断 pass）", "验证证据必须绑定契约 verificationTargets（缺失即阻断 pass）", "仅满足派生摘要而遗漏 ledger requirement 时 verdict 不得为 pass");
+    return {
+        bound: true,
+        ledger: {
+            path: binding.ledgerPath,
+            sha256: binding.ledgerSha256,
+            inputDigest: binding.inputDigest,
+            stats: ledgerStatsLine(ledger),
+        },
+        checklist,
+    };
+}
 export function formatFrontendReviewContextStdout(result) {
     return [
         "Frontend review context: pass",

package/dist/workflows/dag/frontend-review-findings.js

@@ -10,10 +10,17 @@ import { readTypedEventStoreFromJsonl, } from "./frontend-typed-event-store.js";
  * rendered into a downstream-task PRD draft that a later DAG round can consume
  * instead of repeating the previous flow. Rendering is deterministic (pure);
  * only the JSONL read and PRD write are IO.
+ *
+ * The design-review analog (`request_design_changes`) reuses the same PRD
+ * rendering and typed-fact channel: a design rejection is a definite finding
+ * (not a protocol/environment error), so it auto-re-enters the next plan round
+ * with the committed design findings instead of terminating the run.
  */
 export const FRONTEND_REVIEW_FINDINGS_PRD_REL = "contracts/frontend-review-findings-prd.md";
 /** Review node id whose committed typed facts drive the findings PRD. */
 export const FRONTEND_REVIEW_NODE_ID = "frontend-review-pi";
+/** Design review node id whose committed typed facts drive the findings PRD. */
+export const FRONTEND_DESIGN_REVIEW_NODE_ID = "frontend-design-review-pi";
 /** Deterministic issueCategory → failure owner mapping (A+B AC-009 §4.10). */
 export function classifyReviewIssueCategoryFailureOwner(issueCategory) {
     switch (issueCategory) {
@@ -122,10 +129,34 @@ export function deriveFrontendReviewFixScope(fact) {
  * approve_review, missing store, or an unreadable store).
  */
 export async function readCommittedReviewRequestFact(input) {
+    const { runDir: reviewRunDir } = input;
     const reviewNodeId = input.reviewNodeId ?? FRONTEND_REVIEW_NODE_ID;
+    return readCommittedRequestFactByKind({
+        runDir: reviewRunDir,
+        nodeId: reviewNodeId,
+        factsFile: "review-typed-facts.jsonl",
+        kind: "request_review_changes",
+    });
+}
+/**
+ * Read the committed `request_design_changes` fact from the design review
+ * node's typed event store. Returns undefined when no committed request fact
+ * exists (e.g. approve_design, missing store, or an unreadable store).
+ */
+export async function readCommittedDesignRequestFact(input) {
+    const { runDir: designRunDir } = input;
+    const designNodeId = input.designNodeId ?? FRONTEND_DESIGN_REVIEW_NODE_ID;
+    return readCommittedRequestFactByKind({
+        runDir: designRunDir,
+        nodeId: designNodeId,
+        factsFile: "design-typed-facts.jsonl",
+        kind: "request_design_changes",
+    });
+}
+async function readCommittedRequestFactByKind(input) {
     let records;
     try {
-        records = await readTypedEventStoreFromJsonl(path.join(input.runDir, reviewNodeId, "review-typed-facts.jsonl"));
+        records = await readTypedEventStoreFromJsonl(path.join(input.runDir, input.nodeId, input.factsFile));
     }
     catch {
         return undefined;
@@ -133,9 +164,7 @@ export async function readCommittedReviewRequestFact(input) {
     const committed = records.filter((record) => record.phase === "committed");
     if (committed.length === 0)
         return undefined;
-    // A committed approve_review means the review passed; only a committed
-    // request_review_changes carries a "not passed" verdict.
-    const request = committed.find((record) => record.fact.kind === "request_review_changes");
+    const request = committed.find((record) => record.fact.kind === input.kind);
     if (!request)
         return undefined;
     const fact = request.fact;
@@ -166,25 +195,28 @@ function findingLines(findings) {
 }
 /**
  * Deterministically render a downstream-task PRD draft from a committed
- * `request_review_changes` fact. Same fact always renders byte-identical
- * output; the parent run id and review node id are the only context.
+ * `request_review_changes` / `request_design_changes` fact. Same fact always
+ * renders byte-identical output; the parent run id and review node id are the
+ * only context.
  */
 export function renderFrontendReviewFindingsPrd(input) {
     const { parentRunId, fact } = input;
-    const reviewNodeId = input.reviewNodeId ?? FRONTEND_REVIEW_NODE_ID;
+    const isDesign = fact.kind === "request_design_changes";
+    const reviewNodeId = input.reviewNodeId ??
+        (isDesign ? FRONTEND_DESIGN_REVIEW_NODE_ID : FRONTEND_REVIEW_NODE_ID);
     const restartPhase = classifyReviewIssueCategoryFailureOwner(fact.issueCategory);
     const scope = deriveFrontendReviewFixScope(fact);
     const targetSummary = scope.targetFiles.length > 0
         ? scope.targetFiles.join(", ")
         : fact.issueCategory;
     return [
-        `# 修复 review 发现（${scope.shape}）：${targetSummary}`,
+        `# 修复 ${isDesign ? "设计" : "review"} 发现（${scope.shape}）：${targetSummary}`,
         "",
         "## 背景",
         "",
         `- parentRunId: \`${parentRunId}\``,
         `- reviewNodeId: \`${reviewNodeId}\``,
-        `- typedVerdict: \`request_review_changes\``,
+        `- typedVerdict: \`${fact.kind}\``,
         `- issueCategory: \`${fact.issueCategory}\``,
         `- restartPhase/failureOwner: \`${restartPhase}\``,
         "",
@@ -216,7 +248,7 @@ export function renderFrontendReviewFindingsPrd(input) {
         "",
         `- 按 issueCategory 映射的重启阶段（${restartPhase}）定点修复，不复用上一轮未通过的实现。`,
         "- 逐条关闭上面「问题清单」中的 findings，并保留上一轮已通过的验证目标继续有效。",
-        "- 完成修复后重新走 frontend DAG 的 implement → verify → review 链，直到 review 提交 approve_review。",
+        `- 完成修复后重新走 frontend DAG 的 ${isDesign ? "plan → design" : "implement → verify → review"} 链，直到${isDesign ? " design-review 提交 approve_design" : " review 提交 approve_review"}。`,
         "",
     ].join("\n");
 }

package/dist/workflows/dag/frontend-shadow-dual-write.js

@@ -270,7 +270,7 @@ export function restorePlanPatchFromCommittedFacts(records) {
  * writeSet-external compile authority (`frontend-implementation-contract.ts`)
  * can still restore a plain `patch` object.
  */
-export function assemblePlanPatchFromCommittedFacts(records) {
+export function assemblePlanPatchFromCommittedFacts(records, contractRequirements) {
     const facts = records
         .filter((record) => record.phase === "committed")
         .map((record) => record.fact)
@@ -344,7 +344,41 @@ export function assemblePlanPatchFromCommittedFacts(records) {
             return { ...entry, expectedOutcome: `implied by contract: ${id}` };
         }
         return entry;
-    });
+    })
+        // Source fidelity ledger (AC-005/AC-006): the contract node declared the
+        // authoritative sourceFragmentIds/sourceRefs for each requirement from
+        // the ledger's requirement→fragment mapping. The plan inherits them by
+        // requirement id so the compiled canonical contract carries the same
+        // provenance evidence without the plan re-deriving (or fabricating) it.
+        .map((entry) => {
+        if (!contractRequirements)
+            return entry;
+        const id = asString(entry.id);
+        if (!id)
+            return entry;
+        const inherited = contractRequirements.get(id);
+        if (!inherited)
+            return entry;
+        const merged = { ...entry };
+        // Inherit the contract-declared provenance only when the plan did
+        // not already declare it (model override wins; missing inherits).
+        if (!Array.isArray(entry.sourceFragmentIds)) {
+            if (inherited.sourceFragmentIds) {
+                merged.sourceFragmentIds = inherited.sourceFragmentIds;
+            }
+        }
+        if (!Array.isArray(entry.sourceRefs)) {
+            if (inherited.sourceRefs) {
+                merged.sourceRefs = inherited.sourceRefs;
+            }
+        }
+        return merged;
+    })
+        // A requirement id is a canonical identity; drop duplicates so the
+        // compiled patch never carries the same requirement twice (the
+        // record_plan_requirement tool rejects re-records, this dedupes any
+        // legacy/edge duplicates at the compile authority).
+        .filter((entry, index, all) => all.findIndex((other) => asString(other.id) === asString(entry.id)) === index);
     if (requirements.length > 0)
         patch.requirements = requirements;
     const verificationTargets = facts

package/dist/workflows/dag/frontend-source-fidelity-ledger.js

@@ -0,0 +1,108 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { resolveDagTaskSourcePath } from "../../task/dag-source-paths.js";
+import { parseLedgerJson, validateRequirementLedger, } from "../../task/source-prepare/ledger.js";
+import { isDagSourceBindingV2 } from "./types.js";
+/**
+ * Validate the semantic source-fidelity ledger binding for a canonical frontend
+ * contract. This is deliberately shared: the compatibility prewrite gate may
+ * report a structured prewrite failure, while the generated production DAG
+ * must deny writer admission on exactly the same evidence.
+ */
+export async function checkFrontendSourceFidelityLedger(input) {
+    const { binding } = input;
+    if (!isDagSourceBindingV2(binding)) {
+        return { ok: true, failureCode: null, failureReason: null, ledger: null };
+    }
+    const absolute = resolveDagTaskSourcePath({
+        workspaceRoot: input.workspaceRoot,
+        taskId: binding.taskId,
+        sourcePath: binding.ledgerPath,
+    });
+    let raw;
+    try {
+        raw = await readFile(absolute, "utf8");
+    }
+    catch (error) {
+        return {
+            ok: false,
+            failureCode: "source-fidelity-ledger-missing",
+            failureReason: `frontend source fidelity ledger missing: ${binding.ledgerPath} (${error instanceof Error ? error.message : String(error)})`,
+            ledger: null,
+        };
+    }
+    const actualSha = createHash("sha256").update(raw).digest("hex");
+    if (actualSha !== binding.ledgerSha256) {
+        return {
+            ok: false,
+            failureCode: "source-fidelity-ledger-stale",
+            failureReason: `frontend source fidelity ledger stale or tampered: ${binding.ledgerPath} (bound ${binding.ledgerSha256}, observed ${actualSha})`,
+            ledger: null,
+        };
+    }
+    let ledger;
+    try {
+        ledger = parseLedgerJson(raw);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            failureCode: "source-fidelity-ledger-stale",
+            failureReason: `frontend source fidelity ledger is not a valid v1 ledger: ${error instanceof Error ? error.message : String(error)}`,
+            ledger: null,
+        };
+    }
+    if (ledger.inputDigest !== binding.inputDigest) {
+        return {
+            ok: false,
+            failureCode: "source-fidelity-ledger-stale",
+            failureReason: `frontend source fidelity ledger inputDigest mismatch: bound ${binding.inputDigest}, ledger ${ledger.inputDigest}`,
+            ledger,
+        };
+    }
+    const validation = validateRequirementLedger(ledger);
+    const firstError = (code) => validation.find((error) => error.code === code)?.message ?? null;
+    const invalid = (failureCode, failureReason) => ({ ok: false, failureCode, failureReason, ledger });
+    if (ledger.stats.unresolvedCount > 0 || validation.some((e) => e.code === "SOURCE_FIDELITY_UNRESOLVED")) {
+        return invalid("source-fidelity-unresolved", firstError("SOURCE_FIDELITY_UNRESOLVED") ?? `frontend source fidelity ledger has ${ledger.stats.unresolvedCount} unresolved fragment(s)`);
+    }
+    if (ledger.stats.conflictCount > 0 || validation.some((e) => e.code === "SOURCE_FIDELITY_CONFLICT")) {
+        return invalid("source-fidelity-conflict", firstError("SOURCE_FIDELITY_CONFLICT") ?? `frontend source fidelity ledger has ${ledger.stats.conflictCount} conflict(s)`);
+    }
+    if (ledger.stats.highRiskUncoveredCount > 0 || validation.some((e) => e.code === "SOURCE_FIDELITY_HIGH_RISK_UNCOVERED")) {
+        return invalid("source-fidelity-high-risk-uncovered", firstError("SOURCE_FIDELITY_HIGH_RISK_UNCOVERED") ?? `frontend source fidelity ledger has ${ledger.stats.highRiskUncoveredCount} high-risk uncovered fragment(s)`);
+    }
+    const notCoveredError = validation.find((e) => e.code === "SOURCE_FIDELITY_REQUIREMENT_NOT_COVERED");
+    if (notCoveredError) {
+        return invalid("source-fidelity-requirement-not-covered", notCoveredError.message);
+    }
+    const refInvalidError = validation.find((e) => e.code === "SOURCE_FIDELITY_SOURCE_REF_INVALID" || e.code === "SOURCE_FIDELITY_FRAGMENT_INVALID");
+    if (refInvalidError) {
+        return invalid("source-fidelity-source-ref-invalid", refInvalidError.message);
+    }
+    const ledgerIds = new Set(ledger.canonicalRequirements.map((requirement) => requirement.id));
+    const contractIds = new Set(input.contractRequirements.map((r) => r.id));
+    const uncoveredRequirements = [...ledgerIds].filter((id) => !contractIds.has(id));
+    if (uncoveredRequirements.length > 0) {
+        return invalid("source-fidelity-requirement-not-covered", `frontend contract requirements do not cover ledger canonical requirement ids: ${uncoveredRequirements.join(", ")}`);
+    }
+    const fragmentById = new Map(ledger.fragments.map((fragment) => [fragment.id, fragment]));
+    for (const requirement of input.contractRequirements) {
+        if (!ledgerIds.has(requirement.id))
+            continue;
+        const declared = requirement.sourceFragmentIds ?? [];
+        if (declared.length === 0) {
+            return invalid("source-fidelity-source-ref-invalid", `frontend contract requirement ${requirement.id} lacks sourceFragmentIds for the bound ledger`);
+        }
+        const boundFragments = new Set(ledger.canonicalRequirements.find((r) => r.id === requirement.id)?.sourceFragmentIds ?? []);
+        for (const fragmentId of declared) {
+            if (!fragmentById.has(fragmentId)) {
+                return invalid("source-fidelity-source-ref-invalid", `frontend contract requirement ${requirement.id} references unknown fragment ${fragmentId}`);
+            }
+            if (!boundFragments.has(fragmentId)) {
+                return invalid("source-fidelity-source-ref-invalid", `frontend contract requirement ${requirement.id} declares fabricated fragment reference ${fragmentId} (not bound in ledger)`);
+            }
+        }
+    }
+    return { ok: true, failureCode: null, failureReason: null, ledger };
+}

package/dist/workflows/dag/frontend-worktree-diff.js

@@ -5,6 +5,10 @@ import { runResilientGitCommand } from "../../shared/resilient-git.js";
 import { writeDagRunJsonArtifact } from "../../infrastructure/harness/artifact-store.js";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
 export const FRONTEND_WORKTREE_DIFF_SCHEMA_ID = "frontend-worktree-diff-v1";
+export const FRONTEND_REVIEW_DIFF_INDEX_SCHEMA_ID = "frontend-review-diff-index-v1";
+const MAX_REVIEW_DIFF_SUMMARY_ENTRIES = 48;
+/** Maximum diff payload per review artifact; metadata adds a small fixed header. */
+const MAX_REVIEW_DIFF_FRAGMENT_BYTES = 20 * 1024;
 export const FRONTEND_WORKTREE_BASELINE_SCHEMA_ID = "frontend-worktree-baseline-v1";
 async function runGit(cwd, args) {
     const result = await runResilientGitCommand({ cwd, args, readOnly: true });
@@ -56,6 +60,98 @@ function splitLines(text) {
         .map((line) => line.trim())
         .filter(Boolean);
 }
+function buildReviewDiffSummary(input) {
+    const files = [...input.hunks.reduce((grouped, hunk) => {
+            const existing = grouped.get(hunk.path);
+            if (existing) {
+                existing.bytes += hunk.bytes;
+                existing.lastPatchPath = hunk.patchPath;
+                return grouped;
+            }
+            grouped.set(hunk.path, {
+                path: hunk.path,
+                bytes: hunk.bytes,
+                parts: hunk.parts,
+                firstPatchPath: hunk.patchPath,
+                lastPatchPath: hunk.patchPath,
+            });
+            return grouped;
+        }, new Map()).values()];
+    const listedFiles = files.slice(0, MAX_REVIEW_DIFF_SUMMARY_ENTRIES);
+    const remainingFiles = files.length - listedFiles.length;
+    const listedUntracked = input.untrackedFiles.slice(0, MAX_REVIEW_DIFF_SUMMARY_ENTRIES);
+    const remainingUntracked = input.untrackedFiles.length - listedUntracked.length;
+    return [
+        "# Frontend review diff summary",
+        "",
+        "Read this bounded summary first. Do not read artifacts/diff_patch.patch in full; it is retained only as the canonical audit artifact.",
+        "For a semantic finding, read only the matching per-file diff fragment below and then the current source file when necessary. Read fragments in part order when a file has more than one.",
+        "",
+        `Canonical patch SHA-256: ${input.patchSha256}`,
+        `Canonical patch bytes: ${input.patchBytes}`,
+        `Tracked changed files: ${files.length}`,
+        `Review diff fragments: ${input.hunks.length}`,
+        `Untracked files (inventory only): ${input.untrackedFiles.length}`,
+        "",
+        "## Tracked file diff fragment references",
+        ...(listedFiles.length > 0
+            ? listedFiles.map((file) => file.parts === 1
+                ? `- ${file.path} — ${file.bytes} bytes — read ${file.firstPatchPath} only if this file needs review`
+                : `- ${file.path} — ${file.bytes} bytes across ${file.parts} ordered fragments — read ${file.firstPatchPath} through ${file.lastPatchPath} only if this file needs review`)
+            : ["- (none)"]),
+        ...(remainingFiles > 0
+            ? [`- … ${remainingFiles} additional tracked files are recorded in contracts/frontend-review-diff-index.json; do not bulk-read them.`]
+            : []),
+        "",
+        "## Untracked inventory",
+        ...(listedUntracked.length > 0
+            ? listedUntracked.map((file) => `- ${file}`)
+            : ["- (none)"]),
+        ...(remainingUntracked > 0
+            ? [`- … ${remainingUntracked} additional untracked files are recorded in contracts/frontend-review-diff-index.json.`]
+            : []),
+        "",
+    ].join("\n");
+}
+function splitReviewDiffFragments(text) {
+    const fragments = [];
+    let current = "";
+    for (const line of text.match(/[^\n]*\n|[^\n]+/g) ?? []) {
+        const lineBytes = Buffer.byteLength(line);
+        if (current.length > 0 &&
+            Buffer.byteLength(current) + lineBytes >
+                MAX_REVIEW_DIFF_FRAGMENT_BYTES) {
+            fragments.push(current);
+            current = "";
+        }
+        if (lineBytes <= MAX_REVIEW_DIFF_FRAGMENT_BYTES) {
+            current += line;
+            continue;
+        }
+        // Generated/minified files can produce a single diff line larger than the
+        // review budget. Split by Unicode code point so no fragment exceeds the
+        // byte limit while preserving the original patch bytes when concatenated.
+        let oversizedLineFragment = "";
+        let oversizedLineFragmentBytes = 0;
+        for (const codePoint of line) {
+            const codePointBytes = Buffer.byteLength(codePoint);
+            if (oversizedLineFragmentBytes > 0 &&
+                oversizedLineFragmentBytes + codePointBytes >
+                    MAX_REVIEW_DIFF_FRAGMENT_BYTES) {
+                fragments.push(oversizedLineFragment);
+                oversizedLineFragment = "";
+                oversizedLineFragmentBytes = 0;
+            }
+            oversizedLineFragment += codePoint;
+            oversizedLineFragmentBytes += codePointBytes;
+        }
+        if (oversizedLineFragment)
+            fragments.push(oversizedLineFragment);
+    }
+    if (current.length > 0)
+        fragments.push(current);
+    return fragments.length > 0 ? fragments : [""];
+}
 async function sha256File(filePath) {
     try {
         const bytes = await readFile(filePath);
@@ -206,11 +302,65 @@ export async function runFrontendWorktreeDiffGate(input) {
     const absolutePatch = path.join(input.runDir, ...relativePatch.split("/"));
     await mkdir(path.dirname(absolutePatch), { recursive: true });
     await writeFile(absolutePatch, patchText, "utf8");
+    // Keep the complete patch as immutable audit evidence, but create a bounded
+    // reviewer entrypoint plus one file-scoped artifact per tracked change. This
+    // prevents final review from loading a multi-thousand-line patch into a
+    // single Pi session merely to inspect one or two relevant files.
+    const reviewHunks = [];
+    const reviewHunksDir = path.join(input.runDir, "artifacts", "diff-hunks");
+    await mkdir(reviewHunksDir, { recursive: true });
+    for (const [index, file] of changedFiles.entries()) {
+        const filePatch = await run(root, ["diff", "--binary", "HEAD", "--", file]);
+        if (filePatch.code !== 0) {
+            throw new Error(`frontend worktree diff hunk failed for ${file}: ${filePatch.stderr.trim() || filePatch.stdout.trim()}`);
+        }
+        const text = filePatch.stdout.endsWith("\n") || filePatch.stdout.length === 0
+            ? filePatch.stdout
+            : `${filePatch.stdout}\n`;
+        const fragments = splitReviewDiffFragments(text);
+        for (const [partIndex, fragment] of fragments.entries()) {
+            const part = partIndex + 1;
+            const patchPath = `artifacts/diff-hunks/${String(index + 1).padStart(3, "0")}-${String(part).padStart(3, "0")}.patch`;
+            const artifact = [
+                "# Frontend review diff fragment",
+                `# path: ${file}`,
+                `# part: ${part}/${fragments.length}`,
+                "",
+                fragment,
+            ].join("\n");
+            await writeFile(path.join(input.runDir, ...patchPath.split("/")), artifact, "utf8");
+            reviewHunks.push({
+                path: file,
+                patchPath,
+                sha256: createHash("sha256").update(artifact).digest("hex"),
+                bytes: Buffer.byteLength(artifact),
+                part,
+                parts: fragments.length,
+            });
+        }
+    }
+    const reviewIndexPath = "contracts/frontend-review-diff-index.json";
+    await writeDagRunJsonArtifact(input.runDir, reviewIndexPath, {
+        schemaVersion: 1,
+        schemaId: FRONTEND_REVIEW_DIFF_INDEX_SCHEMA_ID,
+        patchSha256,
+        hunks: reviewHunks,
+        untrackedFiles,
+    });
+    const reviewSummaryPath = "artifacts/diff_summary.md";
+    await writeFile(path.join(input.runDir, ...reviewSummaryPath.split("/")), buildReviewDiffSummary({
+        patchSha256,
+        patchBytes: Buffer.byteLength(patchText),
+        hunks: reviewHunks,
+        untrackedFiles,
+    }), "utf8");
     const payload = {
         schemaVersion: 1,
         schemaId: FRONTEND_WORKTREE_DIFF_SCHEMA_ID,
         patchPath: relativePatch,
         patchSha256,
+        reviewSummaryPath,
+        reviewIndexPath,
         changedFiles,
         untrackedFiles,
         empty: changedFiles.length === 0 && untrackedFiles.length === 0,
@@ -223,6 +373,8 @@ export async function runFrontendWorktreeDiffGate(input) {
         patchPath: relativePatch,
         patchAbsolutePath: absolutePatch,
         patchSha256,
+        reviewSummaryPath,
+        reviewIndexPath,
         changedFiles,
         untrackedFiles,
         empty: payload.empty,
@@ -235,6 +387,8 @@ export function formatFrontendWorktreeDiffStdout(result) {
         `schemaId=${result.schemaId}`,
         `patchPath=${result.patchPath}`,
         `patchSha256=${result.patchSha256}`,
+        `reviewSummaryPath=${result.reviewSummaryPath}`,
+        `reviewIndexPath=${result.reviewIndexPath}`,
         `changedFiles=${result.changedFiles.length}`,
         `untrackedFiles=${result.untrackedFiles.length}`,
         `empty=${result.empty ? "true" : "false"}`,