@tea-agent/loop-agent 0.39.0-next.9 → 0.39.1

package/dist/workflows/dag/frontend-prewrite-gate.js

@@ -1,13 +1,18 @@
+import { createHash } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
+import { isDagSourceBindingV2 } from "./types.js";
 import { isOpenspecSpecFilePath } from "../../shared/openspec-spec.js";
 import { writeTextArtifactFile } from "../../infrastructure/harness/artifact-store.js";
 import { countExcludedGovernanceSpecFiles, resolveOpenspecGovernanceRoot, } from "../../task/frontend-project-capability.js";
-import { analyzeFrontendImplementationContract, writeFrontendImplementationContractArtifact, writeDeterministicJsonArtifact, assertFrontendSourceBindingFresh, deterministicSha256, sha256Hex, serializeDeterministicJson, applyFrontendImplementationContractPatch, extractFrontendImplementationJson, FrontendContractFailure, frontendNormalizationActionSchema, } from "./frontend-implementation-contract.js";
+import { resolveDagTaskSourcePath } from "../../task/dag-source-paths.js";
+import { parseLedgerJson, validateRequirementLedger, } from "../../task/source-prepare/ledger.js";
+import { analyzeFrontendImplementationContract, writeFrontendImplementationContractArtifact, writeDeterministicJsonArtifact, assertFrontendSourceBindingFresh, deterministicSha256, sha256Hex, serializeDeterministicJson, FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID, FrontendContractFailure, frontendNormalizationActionSchema, } from "./frontend-implementation-contract.js";
 import { renderFrontendPlanMarkdown } from "./frontend-plan-render.js";
 import { captureFrontendWorktreeBaseline } from "./frontend-worktree-diff.js";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
+import { normalizeVerdictCandidateLine } from "./dynamic-runtime/shared.js";
 export const FRONTEND_PREWRITE_RESULT_SCHEMA_ID = "frontend-prewrite-result-v1";
 export const FRONTEND_PREWRITE_RESULT_ARTIFACT_NAME = "frontend-prewrite-result.json";
 /** Canonical contract serialization must stay at or below this byte size. */
@@ -39,6 +44,15 @@ export const frontendPrewriteFailureCodeSchema = z.enum([
     "component-spec-not-cited",
     "component-choices-missing",
     "contract-too-large",
+    "revision-patch-unmergeable",
+    // Source fidelity ledger 类目（SOURCE_FIDELITY_*/source-* 稳定错误码）。
+    "source-fidelity-ledger-missing",
+    "source-fidelity-ledger-stale",
+    "source-fidelity-unresolved",
+    "source-fidelity-conflict",
+    "source-fidelity-high-risk-uncovered",
+    "source-fidelity-requirement-not-covered",
+    "source-fidelity-source-ref-invalid",
 ]);
 export const frontendPrewriteResultV1Schema = z
     .object({
@@ -155,32 +169,80 @@ async function selectNode(runDir, primary, fallbacks) {
     }
     throw new Error(`frontend prewrite gate no FINISHED candidate: ${rejections.join("; ")}`);
 }
-async function readNodeText(runDir, nodeId) {
-    const record = JSON.parse(await readFile(path.join(runDir, `${nodeId}.json`), "utf8"));
+async function readFinishedNodeRecord(runDir, nodeId) {
+    let record;
+    try {
+        record = JSON.parse(await readFile(path.join(runDir, `${nodeId}.json`), "utf8"));
+    }
+    catch (error) {
+        throw new Error(`frontend prewrite gate cannot parse node record ${nodeId}: ${error instanceof Error ? error.message : String(error)}`);
+    }
     if (record.status !== "FINISHED") {
         throw new Error(`frontend prewrite gate requires FINISHED node ${nodeId} (got ${String(record.status)})`);
     }
-    const text = [record.assistantText, record.stdout]
-        .filter((value) => Boolean(value?.trim()))
-        .join("\n");
+    return record;
+}
+async function readNodeText(runDir, nodeId) {
+    const record = await readFinishedNodeRecord(runDir, nodeId);
+    const text = record.assistantText?.trim() || record.stdout?.trim() || "";
     if (!text)
         throw new Error(`frontend prewrite gate empty output from ${nodeId}`);
     return text;
 }
-async function readNodeRawText(runDir, nodeId) {
-    const record = JSON.parse(await readFile(path.join(runDir, `${nodeId}.json`), "utf8"));
-    return record.assistantText ?? record.stdout ?? "";
+async function readCanonicalContractFromNode(runDir, nodeId) {
+    const record = await readFinishedNodeRecord(runDir, nodeId);
+    if (!record.structuredArtifactPath) {
+        throw new Error(`frontend prewrite gate missing structured artifact for ${nodeId}`);
+    }
+    const artifactPath = path.isAbsolute(record.structuredArtifactPath)
+        ? record.structuredArtifactPath
+        : path.join(runDir, record.structuredArtifactPath);
+    const resolvedRun = path.resolve(runDir);
+    const resolvedArtifact = path.resolve(artifactPath);
+    const relative = path.relative(resolvedRun, resolvedArtifact);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error(`frontend prewrite gate structured artifact escapes runDir: ${record.structuredArtifactPath}`);
+    }
+    const bytes = await readFile(resolvedArtifact);
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (record.structuredArtifactSha256 &&
+        record.structuredArtifactSha256 !== digest) {
+        throw new Error(`frontend prewrite gate structured artifact hash mismatch for ${nodeId}`);
+    }
+    if (record.structuredArtifactSchemaId &&
+        record.structuredArtifactSchemaId !== FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID) {
+        throw new Error(`frontend prewrite gate structured artifact schema mismatch for ${nodeId}: ${record.structuredArtifactSchemaId}`);
+    }
+    const contractText = bytes.toString("utf8");
+    let citationsText = "";
+    try {
+        const citationsRaw = await readFile(path.join(path.dirname(resolvedArtifact), "openspec-citations.json"), "utf8");
+        try {
+            const parsed = JSON.parse(citationsRaw);
+            citationsText =
+                typeof parsed.block === "string" ? parsed.block : citationsRaw;
+        }
+        catch {
+            citationsText = citationsRaw;
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    return { contractText, citationsText, rawSha256: digest };
 }
 function firstNonEmptyVerdictLine(text) {
     const lines = text
         .split(/\r?\n/)
         .map((line) => line.trim())
         .filter(Boolean);
-    const normalize = (line) => {
-        const emphasized = line.match(/^(?:`{1,3}|\*{1,3})\s*(VERDICT:[^`*]+?)\s*(?:`{1,3}|\*{1,3})$/);
-        return (emphasized?.[1] ?? line).trim();
-    };
-    const normalizedLines = lines.map(normalize);
+    // Emphasis stripping (backtick + asterisk) is shared with the runIf
+    // selector and node-level output-protocol validation via
+    // normalizeVerdictCandidateLine. The gate keeps its own loose
+    // pass/request-revision normalization below (prefix match + trailing
+    // prose tolerance) for deterministic fail-closed behavior.
+    const normalizedLines = lines.map(normalizeVerdictCandidateLine);
     const first = normalizedLines[0] ?? "";
     // The prompt requires VERDICT to be the first non-empty line, but model
     // output can still prepend a summary. Keep the protocol strict in the
@@ -391,13 +453,192 @@ async function finalizePrewrite(input, pending) {
         openspecPolicy: pending.openspecPolicy,
     };
 }
+/**
+ * Source fidelity ledger 门禁检查（AC-FIDELITY-002/003/006）：绑定携带 ledger 指针时，
+ * 依次核验 ledger 存在、绑定 hash 一致、inputDigest 新鲜、无 unresolved/conflict/
+ * 高风险未覆盖、canonical requirement 全覆盖、来源引用有效且非伪造。任一失败 fail closed。
+ */
+export async function checkFrontendSourceFidelityLedger(input) {
+    const { binding } = input;
+    // v1 绑定不携带 ledger 指针：非 frontend task / 无可解析引用 → 无 v2 校验路径。
+    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;
+    if (ledger.stats.unresolvedCount > 0 || validation.some((e) => e.code === "SOURCE_FIDELITY_UNRESOLVED")) {
+        return {
+            ok: false,
+            failureCode: "source-fidelity-unresolved",
+            failureReason: firstError("SOURCE_FIDELITY_UNRESOLVED") ??
+                `frontend source fidelity ledger has ${ledger.stats.unresolvedCount} unresolved fragment(s)`,
+            ledger,
+        };
+    }
+    if (ledger.stats.conflictCount > 0 || validation.some((e) => e.code === "SOURCE_FIDELITY_CONFLICT")) {
+        return {
+            ok: false,
+            failureCode: "source-fidelity-conflict",
+            failureReason: firstError("SOURCE_FIDELITY_CONFLICT") ??
+                `frontend source fidelity ledger has ${ledger.stats.conflictCount} conflict(s)`,
+            ledger,
+        };
+    }
+    if (ledger.stats.highRiskUncoveredCount > 0 ||
+        validation.some((e) => e.code === "SOURCE_FIDELITY_HIGH_RISK_UNCOVERED")) {
+        return {
+            ok: false,
+            failureCode: "source-fidelity-high-risk-uncovered",
+            failureReason: firstError("SOURCE_FIDELITY_HIGH_RISK_UNCOVERED") ??
+                `frontend source fidelity ledger has ${ledger.stats.highRiskUncoveredCount} high-risk uncovered fragment(s)`,
+            ledger,
+        };
+    }
+    // AC-BLOCK-001：canonical requirement 缺少 fragment/sourceRef 证据（ledger 侧
+    // REQUIREMENT_NOT_COVERED）与来源引用/片段无效（SOURCE_REF_INVALID /
+    // FRAGMENT_INVALID）均为阻断性失败，结构化失败结果不得产生可继续执行的成功。
+    const notCoveredError = validation.find((e) => e.code === "SOURCE_FIDELITY_REQUIREMENT_NOT_COVERED");
+    if (notCoveredError) {
+        return {
+            ok: false,
+            failureCode: "source-fidelity-requirement-not-covered",
+            failureReason: notCoveredError.message,
+            ledger,
+        };
+    }
+    const refInvalidError = validation.find((e) => e.code === "SOURCE_FIDELITY_SOURCE_REF_INVALID" ||
+        e.code === "SOURCE_FIDELITY_FRAGMENT_INVALID");
+    if (refInvalidError) {
+        return {
+            ok: false,
+            failureCode: "source-fidelity-source-ref-invalid",
+            failureReason: refInvalidError.message,
+            ledger,
+        };
+    }
+    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 {
+            ok: false,
+            failureCode: "source-fidelity-requirement-not-covered",
+            failureReason: `frontend contract requirements do not cover ledger canonical requirement ids: ${uncoveredRequirements.join(", ")}`,
+            ledger,
+        };
+    }
+    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 {
+                ok: false,
+                failureCode: "source-fidelity-source-ref-invalid",
+                failureReason: `frontend contract requirement ${requirement.id} lacks sourceFragmentIds for the bound ledger`,
+                ledger,
+            };
+        }
+        const boundFragments = new Set(ledger.canonicalRequirements.find((r) => r.id === requirement.id)
+            ?.sourceFragmentIds ?? []);
+        for (const fragmentId of declared) {
+            if (!fragmentById.has(fragmentId)) {
+                return {
+                    ok: false,
+                    failureCode: "source-fidelity-source-ref-invalid",
+                    failureReason: `frontend contract requirement ${requirement.id} references unknown fragment ${fragmentId}`,
+                    ledger,
+                };
+            }
+            if (!boundFragments.has(fragmentId)) {
+                return {
+                    ok: false,
+                    failureCode: "source-fidelity-source-ref-invalid",
+                    failureReason: `frontend contract requirement ${requirement.id} declares fabricated fragment reference ${fragmentId} (not bound in ledger)`,
+                    ledger,
+                };
+            }
+        }
+    }
+    return { ok: true, failureCode: null, failureReason: null, ledger };
+}
 export async function runFrontendPrewriteGate(input) {
     const workspaceRoot = input.workspaceRoot ?? input.repoRoot;
     // selectNode throws for a scheduling defect (no FINISHED plan/review). That
     // remains an ERROR and is intentionally not classified into prewrite-result.
     const planNodeId = await selectNode(input.runDir, input.config.planFromNodeId, input.config.planFallbackFromNodeIds);
     const reviewNodeId = await selectNode(input.runDir, input.config.reviewFromNodeId, input.config.reviewFallbackFromNodeIds);
-    const candidateRawSha256 = sha256Hex(await readNodeRawText(input.runDir, planNodeId));
+    let planArtifact;
+    try {
+        planArtifact = await readCanonicalContractFromNode(input.runDir, planNodeId);
+    }
+    catch (error) {
+        return finalizePrewrite(input, {
+            planNodeId,
+            reviewNodeId,
+            verdict: "",
+            candidateRawSha256: sha256Hex(""),
+            candidateJsonSha256: null,
+            canonicalSha256: null,
+            normalizationActions: [],
+            mockStrategy: undefined,
+            artifact: undefined,
+            failureReason: error instanceof Error ? error.message : String(error),
+            failureCode: "plan-text-unreadable",
+            classification: "retryable-invalid",
+            openspecReadPaths: [],
+            openspecCandidatePaths: input.config.openspecCandidatePaths ?? [],
+            openspecPolicy: input.config.openspecPolicy ?? "scan-strict",
+        });
+    }
+    const candidateRawSha256 = planArtifact.rawSha256;
     const openspecPolicy = input.config.openspecPolicy ?? "scan-strict";
     const basePending = {
         planNodeId,
@@ -416,18 +657,9 @@ export async function runFrontendPrewriteGate(input) {
         openspecCandidatePaths: input.config.openspecCandidatePaths ?? [],
         openspecPolicy,
     };
-    let planText;
-    try {
-        planText = await readNodeText(input.runDir, planNodeId);
-    }
-    catch (error) {
-        return finalizePrewrite(input, {
-            ...basePending,
-            classification: "retryable-invalid",
-            failureReason: error instanceof Error ? error.message : String(error),
-            failureCode: "plan-text-unreadable",
-        });
-    }
+    const planText = [planArtifact.contractText, planArtifact.citationsText]
+        .filter(Boolean)
+        .join("\n");
     let reviewText;
     try {
         reviewText = await readNodeText(input.runDir, reviewNodeId);
@@ -450,59 +682,7 @@ export async function runFrontendPrewriteGate(input) {
             failureCode: "verdict-not-pass",
         });
     }
-    // revisionPatch mode: the effective plan node emits an RFC 7386 merge-patch
-    // delta against the original contract node (planFallbackFromNodeIds[0]).
-    // Legacy DAGs without revisionPatch (undefined) keep full-contract semantics.
-    const revisionPatchMode = input.config.revisionPatch === true &&
-        planNodeId === input.config.planFromNodeId &&
-        input.config.planFallbackFromNodeIds.length > 0;
-    let effectiveContractText = null;
-    if (revisionPatchMode) {
-        const originalNodeId = input.config.planFallbackFromNodeIds[0];
-        let originalText;
-        try {
-            originalText = await readNodeText(input.runDir, originalNodeId);
-        }
-        catch (error) {
-            return finalizePrewrite(input, {
-                ...basePending,
-                verdict,
-                classification: "retryable-invalid",
-                failureReason: `frontend prewrite gate revisionPatch mode requires original contract node ${originalNodeId}: ${error instanceof Error ? error.message : String(error)}`,
-                failureCode: "contract-invalid",
-            });
-        }
-        let originalValue;
-        let patchValue;
-        try {
-            originalValue = extractFrontendImplementationJson(originalText);
-            patchValue = extractFrontendImplementationJson(planText);
-        }
-        catch (error) {
-            return finalizePrewrite(input, {
-                ...basePending,
-                verdict,
-                classification: "retryable-invalid",
-                failureReason: `frontend prewrite gate revisionPatch mode failed to parse contract/patch: ${error instanceof Error ? error.message : String(error)}`,
-                failureCode: "contract-invalid",
-            });
-        }
-        let merged;
-        try {
-            merged = applyFrontendImplementationContractPatch(originalValue, patchValue);
-        }
-        catch (error) {
-            return finalizePrewrite(input, {
-                ...basePending,
-                verdict,
-                classification: "retryable-invalid",
-                failureReason: `frontend prewrite gate revisionPatch apply failed: ${error instanceof Error ? error.message : String(error)}`,
-                failureCode: "contract-invalid",
-            });
-        }
-        effectiveContractText = serializeDeterministicJson(merged);
-    }
-    const requirementIdSearchText = effectiveContractText ?? planText;
+    const requirementIdSearchText = planArtifact.contractText;
     const missingIds = input.config.requiredRequirementIds.filter((id) => !requirementIdSearchText.includes(id));
     if (missingIds.length > 0) {
         return finalizePrewrite(input, {
@@ -550,14 +730,13 @@ export async function runFrontendPrewriteGate(input) {
                 workspaceRoot,
             });
     }
-    // Candidate -> canonical conversion. The gate consumes the selected
-    // plan/revision assistant output directly and is the only conversion point.
+    // Candidate -> canonical conversion. The gate consumes the producing node's
+    // hash-bound canonical artifact and never re-merges plan/revision stdout.
     let analysis;
     try {
         analysis = await analyzeFrontendImplementationContract({
             runDir: input.runDir,
-            fromNodeId: effectiveContractText ? undefined : planNodeId,
-            rawContractText: effectiveContractText ?? undefined,
+            rawContractText: planArtifact.contractText,
             sourceBinding: input.sourceBinding,
         });
     }
@@ -577,6 +756,33 @@ export async function runFrontendPrewriteGate(input) {
         }
         throw error;
     }
+    // Source fidelity ledger gate (20260824-frontend-source-fidelity-ledger-v1):
+    // 在 verdict/missing-requirement-ids/source-binding-not-fresh 之后插入 ledger
+    // 检查。缺失即 fail closed 且 writer 不获授权；所有检查通过才继续物化契约。
+    if (input.sourceBinding) {
+        const ledgerCheck = await checkFrontendSourceFidelityLedger({
+            workspaceRoot: workspaceRoot ?? "",
+            binding: input.sourceBinding,
+            contractRequirements: analysis.canonical.requirements.map((requirement) => ({
+                id: requirement.id,
+                sourceFragmentIds: requirement.sourceFragmentIds,
+                sourceRefs: requirement.sourceRefs,
+            })),
+        });
+        if (!ledgerCheck.ok && ledgerCheck.failureCode) {
+            return finalizePrewrite(input, {
+                ...basePending,
+                verdict,
+                candidateJsonSha256: analysis.candidateJsonSha256,
+                normalizationActions: [],
+                mockStrategy: analysis.canonical.mockApi.strategy,
+                classification: "blocked",
+                failureReason: ledgerCheck.failureReason ??
+                    "frontend source fidelity ledger gate failed",
+                failureCode: ledgerCheck.failureCode,
+            });
+        }
+    }
     // Size guard: a canonical contract above 64KB is a retryable-invalid defect
     // (compress the contract) rather than a writer authorization failure.
     const contractSizeBytes = Buffer.byteLength(serializeDeterministicJson(analysis.canonical), "utf8");
@@ -935,6 +1141,9 @@ export function formatFrontendPrewriteGateStdout(result) {
     }
     lines.push(`Prewrite result: ${result.prewriteResult.path}`);
     lines.push(`Openspec policy: ${result.openspecPolicy}`);
+    if (result.failureCode?.startsWith("source-fidelity-")) {
+        lines.push(`Source fidelity ledger: blocked (${result.failureCode})`);
+    }
     if (result.failureReason)
         lines.push(`Failure reason: ${result.failureReason}`);
     if (result.openspecReadPaths.length > 0) {

package/dist/workflows/dag/frontend-repair.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { z } from "zod";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
 import { FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID, frontendImplementationContractSchema, } from "./frontend-implementation-contract.js";
+import { FRONTEND_NO_VERIFICATION_MARKER_TEXT, FRONTEND_VERIFICATION_UNAVAILABLE_MESSAGE, } from "./frontend-verification-trace.js";
 export const FRONTEND_REPAIR_ASSESSMENT_SCHEMA_ID = "frontend-repair-assessment-v1";
 export const frontendRepairFailureClassSchema = z.enum([
     "typecheck",
@@ -82,6 +83,12 @@ export function classifyFrontendFailure(input) {
     if (input.failureCategory === "write-guard") {
         return "path";
     }
+    if (`${input.stderr ?? ""}\n${input.stdout ?? ""}`.includes(FRONTEND_NO_VERIFICATION_MARKER_TEXT)) {
+        // Verification unavailability is a generation-time contract gap: no
+        // authorized verification command exists. Bounded repair cannot fix it;
+        // the operator must declare commands and regenerate the DAG.
+        return "contract";
+    }
     if (input.traceTarget || input.commandCategory === "trace") {
         return "trace";
     }
@@ -424,6 +431,13 @@ export async function runFrontendFailureAssessGate(input) {
             : !baseEligible
                 ? `non-repairable or ineligible: failureClass=${failureClass} attempt=${attempt}`
                 : `missing structured evidence for failureClass=${failureClass} on ${primary.nodeId}`;
+        if (!eligible &&
+            `${primary.record.stderr ?? ""}`.includes(FRONTEND_NO_VERIFICATION_MARKER_TEXT)) {
+            // Surface the actionable unavailable-verification reason in the
+            // assessment (and the non-repairable gate error) instead of a
+            // generic class label.
+            reason = FRONTEND_VERIFICATION_UNAVAILABLE_MESSAGE;
+        }
     }
     // fixScope and changedPaths must stay inside the implement writeSet.
     if (evidence.fixScope?.length) {

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

@@ -1,17 +1,39 @@
+import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { writeDagRunJsonArtifact } from "../../infrastructure/harness/artifact-store.js";
 import { formatFrontendWorktreeDiffStdout, runFrontendWorktreeDiffGate, } from "./frontend-worktree-diff.js";
 import { frontendLintAssessmentArtifactSchema } from "./frontend-lint-baseline.js";
-import { frontendImplementationContractSchema } from "./frontend-implementation-contract.js";
+import { frontendImplementationContractSchema, } from "./frontend-implementation-contract.js";
 import { frontendRepairAssessmentSchema } from "./frontend-repair.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";
+/**
+ * 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) {
@@ -32,8 +54,9 @@ async function readOptionalLintAssessment(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 : [];
@@ -69,17 +92,19 @@ 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");
     }
     const assessment = frontendRepairAssessmentSchema.safeParse(input.repairAssessment);
-    if (!assessment.success)
-        throw new Error("frontend review context invalid repair assessment");
+    if (!assessment.success) {
+        throw new FrontendReviewContextFailure("review-context-invalid-contract", "frontend review context invalid repair assessment");
+    }
 }
 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,
@@ -88,6 +113,9 @@ export async function runFrontendReviewContextGate(input) {
     const repairAssessment = await readRequiredJson(input.runDir, "contracts/frontend-repair-assessment.json");
     const lintAssessment = await readOptionalLintAssessment(input.runDir);
     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,
@@ -95,6 +123,7 @@ export async function runFrontendReviewContextGate(input) {
         verificationTrace,
         repairAssessment,
         ...(lintAssessment ? { lintAssessment } : {}),
+        sourceFidelity,
         diff: {
             schemaId: diff.schemaId,
             patchPath: diff.patchPath,
@@ -107,6 +136,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",