@tea-agent/loop-agent 0.41.0-next.3 → 0.41.1-beta.0

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

@@ -2,21 +2,17 @@ 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 { 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 { 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 { checkFrontendSourceFidelityLedger, } from "./frontend-source-fidelity-ledger.js";
+import { analyzeFrontendImplementationContract, writeFrontendImplementationContractArtifact, writeDeterministicJsonArtifact, assertFrontendSourceBindingFresh, deterministicSha256, sha256Hex, 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
@@ -37,13 +33,12 @@ 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",
@@ -140,7 +135,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}$/),
@@ -274,6 +269,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");
@@ -308,7 +304,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);
@@ -323,21 +319,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("#");
@@ -352,57 +333,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
@@ -453,162 +509,7 @@ 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 { 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
@@ -657,9 +558,6 @@ export async function runFrontendPrewriteGate(input) {
         openspecCandidatePaths: input.config.openspecCandidatePaths ?? [],
         openspecPolicy,
     };
-    const planText = [planArtifact.contractText, planArtifact.citationsText]
-        .filter(Boolean)
-        .join("\n");
     let reviewText;
     try {
         reviewText = await readNodeText(input.runDir, reviewNodeId);
@@ -783,21 +681,6 @@ export async function runFrontendPrewriteGate(input) {
             });
         }
     }
-    // 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
@@ -869,14 +752,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));
             }
@@ -899,99 +799,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(planText, 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
@@ -1013,13 +892,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
@@ -1027,11 +910,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) {
@@ -1049,13 +958,10 @@ export async function runFrontendPrewriteGate(input) {
             });
         }
         if (openspecPolicy === "cited") {
-            const parsedCitations = parseOpenspecCitations(planText, 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)),
             ];
@@ -1067,7 +973,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,