@tea-agent/loop-agent 0.39.0-beta.1 → 0.39.0-beta.11

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

@@ -1,16 +1,20 @@
+import { createHash } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
-import { isOpenspecSpecFilePath } from "../../shared/openspec-spec.js";
+import { OPENSPEC_SPEC_EXT_RE, 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 { checkFrontendSourceFidelityLedger, } from "./frontend-source-fidelity-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. */
+export const FRONTEND_CONTRACT_MAX_BYTES = 65536;
 /**
  * Machine-readable failure classification for blocked/retryable-invalid
  * prewrite outcomes. Kept alongside the human-readable failureReason so
@@ -31,13 +35,22 @@ export const frontendPrewriteFailureCodeSchema = z.enum([
     "verification-target-outside-write-set",
     "openspec-not-read",
     "candidate-missing-drift",
-    "openspec-citation-block-unparseable",
-    "openspec-not-cited",
-    "openspec-citation-not-read",
+    "candidate-content-drift",
+    "openspec-selection-invalid",
     "component-spec-reference-invalid",
     "component-spec-not-cited",
+    "component-spec-choice-unbound",
     "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({
@@ -125,7 +138,7 @@ export const frontendPrewriteResultV1Schema = z
 export const frontendWriterAdmissionSchema = z
     .object({
     schemaVersion: z.literal(1),
-    writerNodeId: z.enum(["frontend-implement-pi", "frontend-repair-pi"]),
+    writerNodeId: z.enum(["frontend-implement-pi"]),
     decision: z.enum(["authorized", "denied"]),
     sourceArtifact: z.string().min(1),
     artifactHash: z.string().regex(/^[a-f0-9]{64}$/),
@@ -154,136 +167,68 @@ 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)})`);
     }
-    // Pi execution mirrors a successful structured-contract normalization into
-    // both assistantText and stdout. Treat node output the same way as the DAG
-    // runtime's canonicalNodeOutput(): assistantText is authoritative and stdout
-    // is only a fallback. Concatenating the two duplicate fields makes a single
-    // canonical plan appear as two complete JSON contracts to the prewrite gate.
+    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 ?? "";
-}
-function resolveRunOwnedArtifact(runDir, candidate, label) {
-    const root = path.resolve(runDir);
-    const resolved = path.resolve(candidate);
-    const relative = path.relative(root, resolved);
-    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
-        throw new Error(`frontend prewrite gate ${label} must be contained by the current run directory`);
+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}`);
     }
-    return resolved;
-}
-async function readHashBoundArtifact(input) {
-    const resolved = resolveRunOwnedArtifact(input.runDir, input.artifactPath, input.label);
-    const text = await readFile(resolved, "utf8");
-    const actual = sha256Hex(text);
-    if (actual !== input.expectedSha256) {
-        throw new Error(`frontend prewrite gate ${input.label} SHA-256 mismatch (expected ${input.expectedSha256}, got ${actual})`);
+    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}`);
     }
-    return text;
-}
-async function readFrontendPlanNodeInput(runDir, nodeId) {
-    const record = JSON.parse(await readFile(path.join(runDir, `${nodeId}.json`), "utf8"));
-    if (record.status !== "FINISHED") {
-        throw new Error(`frontend prewrite gate requires FINISHED node ${nodeId} (got ${String(record.status)})`);
+    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}`);
     }
-    const frontend = record.frontendPlanOutput;
-    if (!frontend) {
-        const payloadText = record.assistantText?.trim() || record.stdout?.trim() || "";
-        if (!payloadText)
-            throw new Error(`frontend prewrite gate empty output from ${nodeId}`);
-        return {
-            artifactFirst: false,
-            payloadText,
-            citationsText: payloadText,
-            rawCandidateSha256: sha256Hex(record.assistantText ?? record.stdout ?? ""),
-            payloadKind: "canonical-contract",
-        };
+    if (record.structuredArtifactSchemaId &&
+        record.structuredArtifactSchemaId !== FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID) {
+        throw new Error(`frontend prewrite gate structured artifact schema mismatch for ${nodeId}: ${record.structuredArtifactSchemaId}`);
     }
-    if (frontend.schemaVersion !== 1 ||
-        !record.structuredArtifactPath ||
-        !record.structuredArtifactSha256 ||
-        !record.structuredArtifactSchemaId) {
-        throw new Error(`frontend prewrite gate ${nodeId} has incomplete artifact-first metadata`);
-    }
-    const expectedSchema = frontend.payloadKind === "canonical-contract"
-        ? "frontend-implementation-contract-v1"
-        : "frontend-implementation-contract-revision-patch-v1";
-    if (record.structuredArtifactSchemaId !== expectedSchema) {
-        throw new Error(`frontend prewrite gate ${nodeId} artifact schema ${record.structuredArtifactSchemaId} does not match ${frontend.payloadKind}`);
+    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;
+        }
     }
-    const [payloadText, citationsText] = await Promise.all([
-        readHashBoundArtifact({
-            runDir,
-            artifactPath: record.structuredArtifactPath,
-            expectedSha256: record.structuredArtifactSha256,
-            label: `${nodeId} primary payload`,
-        }),
-        readHashBoundArtifact({
-            runDir,
-            artifactPath: frontend.citationsArtifactPath,
-            expectedSha256: frontend.citationsArtifactSha256,
-            label: `${nodeId} citations`,
-        }),
-        readHashBoundArtifact({
-            runDir,
-            artifactPath: frontend.rawCandidatePath,
-            expectedSha256: frontend.rawCandidateSha256,
-            label: `${nodeId} raw candidate`,
-        }).then(() => undefined),
-    ]);
-    return {
-        artifactFirst: true,
-        payloadText,
-        citationsText,
-        rawCandidateSha256: frontend.rawCandidateSha256,
-        payloadKind: frontend.payloadKind,
-    };
-}
-/**
- * Same shape predicate as the internal `isContract` inside
- * `extractFrontendImplementationJson` (frontend-implementation-contract.ts):
- * schemaVersion 1 + a plain `targets` object + `requirements` and
- * `verificationTargets` arrays. A merge-patch delta does not carry these
- * fields, so this is the deterministic boundary between a full contract and a
- * patch. Keep the two predicates in sync.
- */
-function isFullContractShape(value) {
-    if (value === null || typeof value !== "object" || Array.isArray(value)) {
-        return false;
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
     }
-    const record = value;
-    const targets = record.targets;
-    return (record.schemaVersion === 1 &&
-        targets !== null &&
-        typeof targets === "object" &&
-        !Array.isArray(targets) &&
-        Array.isArray(record.requirements) &&
-        Array.isArray(record.verificationTargets));
-}
-/**
- * Shared merge pipeline for revisionPatch mode and content-driven
- * compatibility: read the original contract node, extract the original
- * contract and the effective node's patch, apply the RFC 7386 merge-patch, and
- * serialize deterministically. Throws on any failure; callers map the error to
- * their own classification (retryable-invalid for explicit revisionPatch mode,
- * blocked for content-driven fallback).
- */
-async function mergeRevisionPatch(runDir, planText, originalNodeId) {
-    const originalText = await readNodeText(runDir, originalNodeId);
-    const originalValue = extractFrontendImplementationJson(originalText);
-    const patchValue = extractFrontendImplementationJson(planText);
-    const merged = applyFrontendImplementationContractPatch(originalValue, patchValue);
-    return serializeDeterministicJson(merged);
+    return { contractText, citationsText, rawSha256: digest };
 }
 function firstNonEmptyVerdictLine(text) {
     const lines = text
@@ -327,6 +272,7 @@ function isFailedToolResult(event) {
 }
 async function collectOpenspecReadPaths(input) {
     const { runDir, planNodeId, reviewNodeId, repoRoot } = input;
+    const candidateSet = input.candidatePaths ? new Set(input.candidatePaths) : undefined;
     const matched = new Set();
     for (const nodeId of [planNodeId, reviewNodeId]) {
         const eventsPath = path.join(runDir, nodeId, "session-events.jsonl");
@@ -361,7 +307,7 @@ async function collectOpenspecReadPaths(input) {
                         : null;
                     if (relativePath &&
                         !isFailedToolResult(event) &&
-                        isOpenspecSpecFilePath(relativePath)) {
+                        (candidateSet ? candidateSet.has(relativePath) : OPENSPEC_SPEC_EXT_RE.test(relativePath))) {
                         matched.add(relativePath);
                     }
                     startedReads.delete(event.toolCallId);
@@ -376,21 +322,6 @@ async function collectOpenspecReadPaths(input) {
     }
     return [...matched];
 }
-async function checkOpenspecReadEvidence(input) {
-    const { runDir, candidatePaths, planNodeId, reviewNodeId, repoRoot } = input;
-    if (candidatePaths.length === 0)
-        return [];
-    const allReadPaths = await collectOpenspecReadPaths({
-        runDir,
-        planNodeId,
-        reviewNodeId,
-        repoRoot,
-    });
-    const normalizedCandidates = new Set(candidatePaths
-        .map((candidate) => toRepoRelativePath(candidate, repoRoot))
-        .filter((candidate) => Boolean(candidate && isOpenspecSpecFilePath(candidate))));
-    return allReadPaths.filter((readPath) => normalizedCandidates.has(readPath));
-}
 function normalizeCitationPath(rawPath, repoRoot) {
     let candidate = rawPath.trim();
     const hashIndex = candidate.indexOf("#");
@@ -405,57 +336,132 @@ function normalizeCitationPath(rawPath, repoRoot) {
     }
     return candidate;
 }
-/**
- * Parses the deterministic openspec-citations fence from the effective plan
- * output. Each non-empty line must be one JSON object {"path","section","line"}.
- * Rows whose normalized path is not a supported openspec spec file are ignored
- * (out of scope); rows that are invalid JSON or lack a string path mark the
- * block unparseable (fail-closed when candidates are non-empty).
- */
-export function parseOpenspecCitations(planText, repoRoot) {
-    const citations = [];
-    let blockPresent = false;
-    let unparseable = false;
-    const fenceRe = /```openspec-citations[ \t]*\r?\n([\s\S]*?)\r?\n```/g;
-    let match;
-    while ((match = fenceRe.exec(planText)) !== null) {
-        blockPresent = true;
-        const body = match[1] ?? "";
-        for (const rawLine of body.split(/\r?\n/)) {
-            const line = rawLine.trim();
-            if (!line)
-                continue;
-            let parsed;
-            try {
-                parsed = JSON.parse(line);
-            }
-            catch {
-                unparseable = true;
-                continue;
-            }
-            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-                unparseable = true;
-                continue;
+async function resolveRequiredOpenspecPaths(input) {
+    if (input.policy === "scan-strict")
+        return { ok: true, paths: input.candidatePaths };
+    // Legacy cited DAGs had no selector: preserve their full candidate must-read
+    // semantics instead of silently weakening an existing run.
+    if (!input.selectionNodeId)
+        return { ok: true, paths: input.candidatePaths };
+    // OpenSpec classifications arrive as individual typed `openspec-selection`
+    // facts (one path per record_openspec_selection call) so a large candidate
+    // set never exceeds a single model output budget. Only positive
+    // classifications (required | relevant) are legal facts; candidates that
+    // were never mentioned default to irrelevant. Explicit task declarations /
+    // source citations (`mandatoryPaths`) are never downgraded: they are
+    // always required and always must-read, whether or not the model declared
+    // them. Fall back to the legacy single fenced JSON for older runs (which
+    // may still carry explicit irrelevant rows).
+    let selections;
+    let allowIrrelevant = false;
+    const selectionNodeId = input.selectionNodeId; // guarded above: no selector -> full candidate semantics
+    try {
+        const facts = await readCommittedContractFacts(input.runDir, selectionNodeId);
+        selections = facts
+            .filter((fact) => fact.kind === "openspec-selection")
+            .map((fact) => ({
+            path: String(fact.path ?? ""),
+            disposition: String(fact.disposition ?? ""),
+            rationale: String(fact.rationale ?? ""),
+        }));
+    }
+    catch {
+        selections = [];
+    }
+    if (selections.length === 0) {
+        const legacy = await readLegacyOpenspecSelection({
+            runDir: input.runDir,
+            selectionNodeId,
+            candidatePaths: input.candidatePaths,
+            mandatoryPaths: input.mandatoryPaths,
+        });
+        if (!legacy.ok)
+            return legacy;
+        selections = legacy.selections;
+        allowIrrelevant = true;
+    }
+    try {
+        const byPath = new Map();
+        for (const row of selections) {
+            const legalDispositions = allowIrrelevant
+                ? ["required", "relevant", "irrelevant"]
+                : ["required", "relevant"];
+            if (typeof row.path !== "string" ||
+                !legalDispositions.includes(row.disposition) ||
+                typeof row.rationale !== "string" ||
+                !row.rationale.trim()) {
+                throw new Error(`invalid selection row (path+${legalDispositions.join("|")}+non-empty rationale expected): ${JSON.stringify(row)}`);
             }
-            const rawPath = parsed.path;
-            if (typeof rawPath !== "string" || !rawPath.trim()) {
-                unparseable = true;
-                continue;
+            if (!input.candidatePaths.includes(row.path)) {
+                throw new Error(`invalid selection ${row.path}: not a candidate path`);
             }
-            const normalized = normalizeCitationPath(rawPath, repoRoot);
-            if (!normalized || !isOpenspecSpecFilePath(normalized))
-                continue;
-            const section = typeof parsed.section === "string"
-                ? parsed.section
-                : "";
-            const lineValue = parsed.line;
-            const citationLine = typeof lineValue === "number" && Number.isInteger(lineValue)
-                ? lineValue
-                : null;
-            citations.push({ path: normalized, section, line: citationLine });
+            if (byPath.has(row.path))
+                throw new Error(`duplicate selection ${row.path}`);
+            byPath.set(row.path, row.disposition);
+        }
+        // Only explicitly required/relevant candidates must be read; everything
+        // unmentioned defaults to irrelevant. mandatoryPaths are intrinsic:
+        // they must be read even if the model omitted them, and they can never
+        // be downgraded by a declaration.
+        const mustRead = [
+            ...input.mandatoryPaths,
+            ...input.candidatePaths.filter((candidate) => byPath.get(candidate) === "required"),
+        ];
+        return { ok: true, paths: [...new Set(mustRead)].sort() };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `openspec selector invalid: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+async function readCommittedContractFacts(runDir, nodeId) {
+    const { readTypedEventStoreFromJsonl } = await import("./frontend-typed-event-store.js");
+    const records = await readTypedEventStoreFromJsonl(path.join(runDir, nodeId, "contract-typed-facts.jsonl"));
+    return records
+        .filter((record) => record.phase === "committed")
+        .map((record) => record.fact)
+        .filter((fact) => Boolean(fact));
+}
+async function readLegacyOpenspecSelection(input) {
+    let text;
+    try {
+        text = await readNodeText(input.runDir, input.selectionNodeId);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `openspec selector output unreadable: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    const fenced = /```json\s*\n([\s\S]*?)\n```/.exec(text);
+    if (!fenced) {
+        return {
+            ok: false,
+            reason: "openspec selector emitted neither typed openspec-selection facts nor a legacy fenced JSON selection object",
+        };
+    }
+    try {
+        const parsed = JSON.parse(fenced[1] ?? "");
+        if (parsed.schemaVersion !== 1 ||
+            parsed.schemaId !== "frontend-openspec-selection-v1" ||
+            !Array.isArray(parsed.selections)) {
+            throw new Error("schemaVersion/schemaId/selections invalid");
         }
+        const rows = parsed.selections.map((row) => ({
+            path: String(row.path ?? ""),
+            disposition: String(row.disposition ?? ""),
+            rationale: String(row.rationale ?? ""),
+        }));
+        return { ok: true, selections: rows };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `openspec selector invalid: ${error instanceof Error ? error.message : String(error)}`,
+        };
     }
-    return { blockPresent, unparseable, citations };
 }
 async function finalizePrewrite(input, pending) {
     const sourceBindingSha256 = input.sourceBinding
@@ -506,13 +512,37 @@ async function finalizePrewrite(input, pending) {
         openspecPolicy: pending.openspecPolicy,
     };
 }
+export { checkFrontendSourceFidelityLedger } from "./frontend-source-fidelity-ledger.js";
 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,
@@ -531,21 +561,6 @@ export async function runFrontendPrewriteGate(input) {
         openspecCandidatePaths: input.config.openspecCandidatePaths ?? [],
         openspecPolicy,
     };
-    let planInput;
-    try {
-        planInput = await readFrontendPlanNodeInput(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 = planInput.payloadText;
-    const citationsText = planInput.citationsText;
-    basePending.candidateRawSha256 = planInput.rawCandidateSha256;
     let reviewText;
     try {
         reviewText = await readNodeText(input.runDir, reviewNodeId);
@@ -568,90 +583,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];
-        try {
-            const originalInput = await readFrontendPlanNodeInput(input.runDir, originalNodeId);
-            if (planInput.artifactFirst && !originalInput.artifactFirst) {
-                throw new Error(`artifact-first revision ${planNodeId} requires artifact-first original contract ${originalNodeId}`);
-            }
-            if (planInput.artifactFirst) {
-                if (planInput.payloadKind !== "merge-patch" ||
-                    originalInput.payloadKind !== "canonical-contract") {
-                    throw new Error("artifact-first revision/original payload kinds are invalid");
-                }
-                effectiveContractText = serializeDeterministicJson(applyFrontendImplementationContractPatch(JSON.parse(originalInput.payloadText), JSON.parse(planInput.payloadText)));
-            }
-            else {
-                effectiveContractText = await mergeRevisionPatch(input.runDir, planText, 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",
-            });
-        }
-    }
-    else {
-        // Content-driven compatibility (Bug 1): legacy DAGs without
-        // revisionPatch can still receive a merge-patch delta from the revision
-        // node. Detect the output shape instead of trusting the DAG flag alone.
-        // - Full contract shape → keep legacy full-contract semantics unchanged.
-        // - Patch shape with a usable original contract node → auto-merge and
-        //   run the existing analysis/materialization pipeline.
-        // - Patch shape but unmergeable → blocked + revision-patch-unmergeable
-        //   (no retryable loop).
-        let planJsonValue = null;
-        try {
-            planJsonValue = extractFrontendImplementationJson(planText);
-        }
-        catch {
-            // Not machine-readable JSON: fall back to the legacy full-contract
-            // path where analyzeFrontendImplementationContract surfaces the
-            // original diagnostic (fail-closed without a new failure mode).
-        }
-        if (planJsonValue !== null && !isFullContractShape(planJsonValue)) {
-            const originalNodeId = input.config.planFallbackFromNodeIds[0];
-            if (!originalNodeId || originalNodeId === planNodeId) {
-                return finalizePrewrite(input, {
-                    ...basePending,
-                    verdict,
-                    classification: "blocked",
-                    failureReason: "frontend prewrite gate: the effective plan output is a merge-patch delta but no distinct original contract node is available. Check the DAG revisionPatch/planFallbackFromNodeIds configuration or regenerate the DAG.",
-                    failureCode: "revision-patch-unmergeable",
-                });
-            }
-            try {
-                const originalText = await readNodeText(input.runDir, originalNodeId);
-                const originalValue = extractFrontendImplementationJson(originalText);
-                if (!isFullContractShape(originalValue)) {
-                    throw new Error(`original contract node ${originalNodeId} is not a full frontend implementation contract`);
-                }
-                effectiveContractText = await mergeRevisionPatch(input.runDir, planText, originalNodeId);
-            }
-            catch (error) {
-                return finalizePrewrite(input, {
-                    ...basePending,
-                    verdict,
-                    classification: "blocked",
-                    failureReason: `frontend prewrite gate: the effective plan output is a merge-patch delta but it cannot be merged onto the original contract node ${originalNodeId}: ${error instanceof Error ? error.message : String(error)}. Check the DAG revisionPatch/planFallbackFromNodeIds configuration or regenerate the DAG.`,
-                    failureCode: "revision-patch-unmergeable",
-                });
-            }
-        }
-    }
-    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, {
@@ -699,17 +631,13 @@ export async function runFrontendPrewriteGate(input) {
                 workspaceRoot,
             });
     }
-    // Candidate -> canonical conversion. Artifact-first inputs must keep using
-    // the already hash-verified payload: re-reading the selected node record
-    // here would silently fall back to its prose and defeat the integrity gate.
-    // Historical records intentionally retain their node-text compatibility path.
+    // Candidate -> canonical conversion. The gate consumes the producing node's
+    // hash-bound canonical artifact and never re-merges plan/revision stdout.
     let analysis;
     try {
-        const rawContractText = effectiveContractText ?? (planInput.artifactFirst ? planText : undefined);
         analysis = await analyzeFrontendImplementationContract({
             runDir: input.runDir,
-            fromNodeId: rawContractText ? undefined : planNodeId,
-            rawContractText,
+            rawContractText: planArtifact.contractText,
             sourceBinding: input.sourceBinding,
         });
     }
@@ -729,6 +657,48 @@ 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");
+    if (contractSizeBytes > FRONTEND_CONTRACT_MAX_BYTES) {
+        return finalizePrewrite(input, {
+            ...basePending,
+            verdict,
+            candidateJsonSha256: analysis.candidateJsonSha256,
+            normalizationActions: [],
+            mockStrategy: analysis.canonical.mockApi.strategy,
+            classification: "retryable-invalid",
+            failureReason: `frontend prewrite gate: canonical contract serialization is ${contractSizeBytes} bytes, exceeding the ${FRONTEND_CONTRACT_MAX_BYTES}-byte limit. 压缩契约（移除冗余 prose、重复目标或过长描述）后重试。`,
+            failureCode: "contract-too-large",
+        });
+    }
     const mockStrategy = analysis.canonical.mockApi.strategy;
     if (!input.config.allowedMockStrategies.includes(mockStrategy)) {
         const quotedAllowed = input.config.allowedMockStrategies
@@ -800,14 +770,31 @@ export async function runFrontendPrewriteGate(input) {
     // Effective plan/review must actually read the candidate openspec paths when
     // any exist. This fail-closes BEFORE the canonical contract is materialized
     // so a writer is never authorized on top of unread normative evidence.
-    const candidatePaths = input.config.openspecCandidatePaths ?? [];
+    const frozenCandidatePaths = input.config.openspecCandidatePaths ?? [];
+    const selection = await resolveRequiredOpenspecPaths({
+        runDir: input.runDir,
+        selectionNodeId: input.config.openspecSelectionNodeId,
+        candidatePaths: frozenCandidatePaths,
+        mandatoryPaths: input.config.openspecMandatoryPaths ?? [],
+        policy: openspecPolicy,
+    });
+    if (!selection.ok) {
+        return finalizePrewrite(input, {
+            ...basePending, verdict, candidateJsonSha256: analysis.candidateJsonSha256,
+            normalizationActions: [], mockStrategy, classification: "retryable-invalid",
+            failureReason: `frontend prewrite gate: ${selection.reason}`,
+            failureCode: "openspec-selection-invalid",
+            openspecCandidatePaths: frozenCandidatePaths,
+        });
+    }
+    const candidatePaths = selection.paths;
     const candidateRoot = workspaceRoot ?? process.cwd();
     // Drift precheck: candidates are frozen at generation time. A candidate that
     // no longer exists on disk was deleted/renamed after generation and is a
     // generation-contract defect, not an "unread" failure.
     const missingCandidates = [];
-    if (candidatePaths.length > 0) {
-        for (const candidate of candidatePaths) {
+    if (frozenCandidatePaths.length > 0) {
+        for (const candidate of frozenCandidatePaths) {
             try {
                 await stat(path.join(candidateRoot, candidate));
             }
@@ -830,99 +817,78 @@ export async function runFrontendPrewriteGate(input) {
             openspecCandidatePaths: candidatePaths,
         });
     }
-    let openspecReadPaths;
-    if (openspecPolicy === "cited") {
-        openspecReadPaths = await collectOpenspecReadPaths({
-            runDir: input.runDir,
-            planNodeId,
-            reviewNodeId,
-            repoRoot: candidateRoot,
-        });
-        if (candidatePaths.length > 0) {
-            const parsed = parseOpenspecCitations(citationsText, candidateRoot);
-            if (!parsed.blockPresent || parsed.unparseable) {
-                return finalizePrewrite(input, {
-                    ...basePending,
-                    verdict,
-                    candidateJsonSha256: analysis.candidateJsonSha256,
-                    normalizationActions: [],
-                    mockStrategy,
-                    classification: "retryable-invalid",
-                    failureReason: `frontend prewrite gate: the effective plan output must end with a parseable \`\`\`openspec-citations fenced block (one JSON {"path","section","line"} per line). ${parsed.blockPresent
-                        ? "The block is present but contains unparseable lines."
-                        : "No openspec-citations block was found."}`,
-                    failureCode: "openspec-citation-block-unparseable",
-                    openspecReadPaths,
-                    openspecCandidatePaths: candidatePaths,
-                });
-            }
-            const citedPaths = new Set(parsed.citations.map((citation) => citation.path));
-            const notCited = candidatePaths.filter((candidate) => !citedPaths.has(candidate));
-            if (notCited.length > 0) {
-                return finalizePrewrite(input, {
-                    ...basePending,
-                    verdict,
-                    candidateJsonSha256: analysis.candidateJsonSha256,
-                    normalizationActions: [],
-                    mockStrategy,
-                    classification: "retryable-invalid",
-                    failureReason: `frontend prewrite gate: these openspec candidate paths were not cited in the plan openspec-citations block: ${notCited.join(", ")}`,
-                    failureCode: "openspec-not-cited",
-                    openspecReadPaths,
-                    openspecCandidatePaths: candidatePaths,
-                });
-            }
-            const readSet = new Set(openspecReadPaths);
-            const uncorroborated = [
-                ...new Set(parsed.citations
-                    .filter((citation) => !readSet.has(citation.path))
-                    .map((citation) => citation.path)),
-            ];
-            if (uncorroborated.length > 0) {
-                return finalizePrewrite(input, {
-                    ...basePending,
-                    verdict,
-                    candidateJsonSha256: analysis.candidateJsonSha256,
-                    normalizationActions: [],
-                    mockStrategy,
-                    classification: "retryable-invalid",
-                    failureReason: `frontend prewrite gate: these openspec paths were cited in the plan but have no successful read event in the effective plan/review: ${uncorroborated.join(", ")}`,
-                    failureCode: "openspec-citation-not-read",
-                    openspecReadPaths,
-                    openspecCandidatePaths: candidatePaths,
-                });
-            }
+    const frozenSnapshots = input.config.openspecCandidateSnapshots;
+    if (frozenSnapshots) {
+        const snapshotByPath = new Map(frozenSnapshots.map((snapshot) => [snapshot.path, snapshot.sha256]));
+        const incompleteSnapshots = frozenCandidatePaths.filter((candidate) => !snapshotByPath.has(candidate));
+        const unexpectedSnapshots = frozenSnapshots
+            .map((snapshot) => snapshot.path)
+            .filter((candidate) => !frozenCandidatePaths.includes(candidate));
+        const changedCandidates = [];
+        for (const candidate of frozenCandidatePaths) {
+            const expected = snapshotByPath.get(candidate);
+            if (!expected)
+                continue;
+            const actual = createHash("sha256")
+                .update(await readFile(path.join(candidateRoot, candidate)))
+                .digest("hex");
+            if (actual !== expected)
+                changedCandidates.push(candidate);
+        }
+        if (incompleteSnapshots.length > 0 ||
+            unexpectedSnapshots.length > 0 ||
+            changedCandidates.length > 0) {
+            const details = [
+                ...(incompleteSnapshots.length > 0
+                    ? [`missing snapshots: ${incompleteSnapshots.join(", ")}`]
+                    : []),
+                ...(unexpectedSnapshots.length > 0
+                    ? [`unexpected snapshots: ${unexpectedSnapshots.join(", ")}`]
+                    : []),
+                ...(changedCandidates.length > 0
+                    ? [`content changed: ${changedCandidates.join(", ")}`]
+                    : []),
+            ].join("; ");
+            return finalizePrewrite(input, {
+                ...basePending,
+                verdict,
+                candidateJsonSha256: analysis.candidateJsonSha256,
+                normalizationActions: [],
+                mockStrategy,
+                classification: "blocked",
+                failureReason: `frontend prewrite gate blocked: the generation-frozen OpenSpec content snapshot no longer matches the workspace (${details}). Re-read the changed specification and regenerate the DAG.`,
+                failureCode: "candidate-content-drift",
+                openspecReadPaths: [],
+                openspecCandidatePaths: candidatePaths,
+            });
         }
-        // cited with empty candidates: no read enforcement. The generation step
-        // emits an advisory instead of failing the gate.
     }
-    else {
-        openspecReadPaths = await checkOpenspecReadEvidence({
-            runDir: input.runDir,
-            candidatePaths,
-            planNodeId,
-            reviewNodeId,
-            repoRoot: candidateRoot,
-        });
-        if (candidatePaths.length > 0) {
-            const readSet = new Set(openspecReadPaths);
-            const unread = candidatePaths.filter((candidate) => !readSet.has(candidate));
-            if (unread.length > 0) {
-                const governanceRoot = await resolveOpenspecGovernanceRoot(candidateRoot);
-                const excludedGovernanceCount = await countExcludedGovernanceSpecFiles(candidateRoot, governanceRoot);
-                return finalizePrewrite(input, {
-                    ...basePending,
-                    verdict,
-                    candidateJsonSha256: analysis.candidateJsonSha256,
-                    normalizationActions: [],
-                    mockStrategy,
-                    classification: "retryable-invalid",
-                    failureReason: `frontend prewrite gate: effective plan/review did not read these openspec candidate paths: ${unread.join(", ")}. Read each candidate and report applicable rules plus hit path/section/line number, conflicts, and missing specifications, then rerun. 实际成功读取: ${openspecReadPaths.length > 0 ? openspecReadPaths.join(", ") : "(none)"}; 候选总数: ${candidatePaths.length}; 排除治理目录 ${governanceRoot} 下 ${excludedGovernanceCount} 个文件（运行期诊断口径）; 候选集在生成期冻结，若候选与本任务无关属于生成期契约配置问题，应修正后重新生成 DAG。`,
-                    failureCode: "openspec-not-read",
-                    openspecReadPaths,
-                    openspecCandidatePaths: candidatePaths,
-                });
-            }
+    let openspecReadPaths;
+    openspecReadPaths = await collectOpenspecReadPaths({
+        runDir: input.runDir,
+        planNodeId,
+        reviewNodeId,
+        repoRoot: candidateRoot,
+        ...(candidatePaths.length > 0 ? { candidatePaths } : {}),
+    });
+    if (candidatePaths.length > 0) {
+        const readSet = new Set(openspecReadPaths);
+        const unread = candidatePaths.filter((candidate) => !readSet.has(candidate));
+        if (unread.length > 0) {
+            const governanceRoot = await resolveOpenspecGovernanceRoot(candidateRoot);
+            const excludedGovernanceCount = await countExcludedGovernanceSpecFiles(candidateRoot, governanceRoot);
+            return finalizePrewrite(input, {
+                ...basePending,
+                verdict,
+                candidateJsonSha256: analysis.candidateJsonSha256,
+                normalizationActions: [],
+                mockStrategy,
+                classification: "retryable-invalid",
+                failureReason: `frontend prewrite gate: effective plan/review did not read these openspec candidate paths: ${unread.join(", ")}. Read each candidate and report applicable rules plus hit path/section/line number, conflicts, and missing specifications, then rerun. 实际成功读取: ${openspecReadPaths.length > 0 ? openspecReadPaths.join(", ") : "(none)"}; 候选总数: ${candidatePaths.length}; 排除治理目录 ${governanceRoot} 下 ${excludedGovernanceCount} 个文件（运行期诊断口径）; 候选集在生成期冻结，若候选与本任务无关属于生成期契约配置问题，应修正后重新生成 DAG。`,
+                failureCode: "openspec-not-read",
+                openspecReadPaths,
+                openspecCandidatePaths: candidatePaths,
+            });
         }
     }
     // Component selection spec conformance (ADR 0016). Deterministic cross-check
@@ -944,13 +910,17 @@ export async function runFrontendPrewriteGate(input) {
             normalizationActions: [],
             mockStrategy,
             classification: "retryable-invalid",
-            failureReason: "frontend prewrite gate: the canonical contract has UI-visible work but uiComponentChoices is missing or empty while the generation-frozen component/theme specification bucket is non-empty. 为每个 UI 用途声明组件选型（decision: specified | reuse-existing | new），specified 必须给 specReference.path/section/line，new 必须给 rationale 声明偏差。",
+            failureReason: "frontend prewrite gate: the canonical contract has UI-visible work but uiComponentChoices is missing or empty while the generation-frozen component/theme specification bucket is non-empty. 为每个 UI 用途声明组件选型（decision: specified | reuse-existing | new）；specified 必须给 OpenSpec specReference.path/section/line，new 必须给任务源 PRD specReference.path/section/line。",
             failureCode: "component-choices-missing",
             openspecReadPaths,
             openspecCandidatePaths: candidatePaths,
         });
     }
+    // Only `specified` choices cite the frozen OpenSpec candidate bucket. A
+    // `new` choice instead cites its task-source/PRD declaration and must not be
+    // rejected merely because that source is outside the OpenSpec roots.
     const componentSpecReferences = componentChoices
+        .filter((choice) => choice.decision === "specified")
         .map((choice) => ({
         raw: choice.specReference?.path ?? "",
         normalized: choice.specReference?.path
@@ -958,11 +928,37 @@ export async function runFrontendPrewriteGate(input) {
             : null,
     }))
         .filter((ref) => ref.raw.length > 0);
+    if (componentSpecCandidates.length > 0 && hasUiVisibleWork) {
+        const componentCandidateSet = new Set(componentSpecCandidates);
+        const hasBoundSpecifiedChoice = componentChoices.some((choice) => {
+            if (choice.decision !== "specified" || !choice.specReference?.path) {
+                return false;
+            }
+            const normalized = normalizeCitationPath(choice.specReference.path, candidateRoot);
+            return Boolean(normalized && componentCandidateSet.has(normalized));
+        });
+        if (!hasBoundSpecifiedChoice) {
+            return finalizePrewrite(input, {
+                ...basePending,
+                verdict,
+                candidateJsonSha256: analysis.candidateJsonSha256,
+                normalizationActions: [],
+                mockStrategy,
+                classification: "retryable-invalid",
+                failureReason: "frontend prewrite gate: UI-visible work has a generation-frozen component/theme specification bucket, but no uiComponentChoices decision=specified is bound to a path in that bucket. At least one declared UI purpose must use and cite the applicable component/theme specification; reuse-existing/new alone cannot bypass the bucket.",
+                failureCode: "component-spec-choice-unbound",
+                openspecReadPaths,
+                openspecCandidatePaths: candidatePaths,
+            });
+        }
+    }
     if (componentSpecReferences.length > 0) {
         const invalidRefs = [
             ...new Set(componentSpecReferences
                 .filter((ref) => !ref.normalized ||
-                !isOpenspecSpecFilePath(ref.normalized))
+                !(candidatePaths.length > 0
+                    ? candidatePaths.includes(ref.normalized)
+                    : isOpenspecSpecFilePath(ref.normalized)))
                 .map((ref) => ref.raw)),
         ];
         if (invalidRefs.length > 0) {
@@ -980,13 +976,10 @@ export async function runFrontendPrewriteGate(input) {
             });
         }
         if (openspecPolicy === "cited") {
-            const parsedCitations = parseOpenspecCitations(citationsText, candidateRoot);
-            const citedPaths = new Set(parsedCitations.citations.map((citation) => citation.path));
             const readSet = new Set(openspecReadPaths);
             const uncorroborated = [
                 ...new Set(componentSpecReferences
                     .filter((ref) => !ref.normalized ||
-                    !citedPaths.has(ref.normalized) ||
                     !readSet.has(ref.normalized))
                     .map((ref) => ref.raw)),
             ];
@@ -998,7 +991,7 @@ export async function runFrontendPrewriteGate(input) {
                     normalizationActions: [],
                     mockStrategy,
                     classification: "retryable-invalid",
-                    failureReason: `frontend prewrite gate: these uiComponentChoices specReference paths were not cited in the plan openspec-citations block or lack a successful read event: ${uncorroborated.join(", ")}`,
+                    failureReason: `frontend prewrite gate: these uiComponentChoices specReference paths are missing a ledger specReference or lack a successful read event: ${uncorroborated.join(", ")}`,
                     failureCode: "component-spec-not-cited",
                     openspecReadPaths,
                     openspecCandidatePaths: candidatePaths,
@@ -1072,6 +1065,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) {