@tea-agent/loop-agent 0.41.1-beta.0 → 0.42.0-next.1

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

@@ -2,17 +2,21 @@ import { createHash } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
-import { OPENSPEC_SPEC_EXT_RE, isOpenspecSpecFilePath } from "../../shared/openspec-spec.js";
+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 { 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 { 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. */
+export const FRONTEND_CONTRACT_MAX_BYTES = 65536;
 /**
  * Machine-readable failure classification for blocked/retryable-invalid
  * prewrite outcomes. Kept alongside the human-readable failureReason so
@@ -33,12 +37,13 @@ export const frontendPrewriteFailureCodeSchema = z.enum([
     "verification-target-outside-write-set",
     "openspec-not-read",
     "candidate-missing-drift",
-    "candidate-content-drift",
-    "openspec-selection-invalid",
+    "openspec-citation-block-unparseable",
+    "openspec-not-cited",
+    "openspec-citation-not-read",
     "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",
@@ -135,7 +140,7 @@ export const frontendPrewriteResultV1Schema = z
 export const frontendWriterAdmissionSchema = z
     .object({
     schemaVersion: z.literal(1),
-    writerNodeId: z.enum(["frontend-implement-pi"]),
+    writerNodeId: z.enum(["frontend-implement-pi", "frontend-repair-pi"]),
     decision: z.enum(["authorized", "denied"]),
     sourceArtifact: z.string().min(1),
     artifactHash: z.string().regex(/^[a-f0-9]{64}$/),
@@ -269,7 +274,6 @@ 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");
@@ -304,7 +308,7 @@ async function collectOpenspecReadPaths(input) {
                         : null;
                     if (relativePath &&
                         !isFailedToolResult(event) &&
-                        (candidateSet ? candidateSet.has(relativePath) : OPENSPEC_SPEC_EXT_RE.test(relativePath))) {
+                        isOpenspecSpecFilePath(relativePath)) {
                         matched.add(relativePath);
                     }
                     startedReads.delete(event.toolCallId);
@@ -319,6 +323,21 @@ 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("#");
@@ -333,132 +352,57 @@ function normalizeCitationPath(rawPath, repoRoot) {
     }
     return candidate;
 }
-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)}`);
+/**
+ * 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);
             }
-            if (!input.candidatePaths.includes(row.path)) {
-                throw new Error(`invalid selection ${row.path}: not a candidate path`);
+            catch {
+                unparseable = true;
+                continue;
             }
-            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");
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                unparseable = true;
+                continue;
+            }
+            const rawPath = parsed.path;
+            if (typeof rawPath !== "string" || !rawPath.trim()) {
+                unparseable = true;
+                continue;
+            }
+            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 });
         }
-        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
@@ -509,7 +453,162 @@ async function finalizePrewrite(input, pending) {
         openspecPolicy: pending.openspecPolicy,
     };
 }
-export { checkFrontendSourceFidelityLedger } from "./frontend-source-fidelity-ledger.js";
+/**
+ * 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
@@ -558,6 +657,9 @@ 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);
@@ -681,6 +783,21 @@ 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
@@ -752,31 +869,14 @@ 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 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 candidatePaths = input.config.openspecCandidatePaths ?? [];
     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 (frozenCandidatePaths.length > 0) {
-        for (const candidate of frozenCandidatePaths) {
+    if (candidatePaths.length > 0) {
+        for (const candidate of candidatePaths) {
             try {
                 await stat(path.join(candidateRoot, candidate));
             }
@@ -799,78 +899,99 @@ export async function runFrontendPrewriteGate(input) {
             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,
-            });
+    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,
+                });
+            }
         }
+        // cited with empty candidates: no read enforcement. The generation step
+        // emits an advisory instead of failing the gate.
     }
-    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,
-            });
+    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,
+                });
+            }
         }
     }
     // Component selection spec conformance (ADR 0016). Deterministic cross-check
@@ -892,17 +1013,13 @@ 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 必须给 OpenSpec specReference.path/section/line，new 必须给任务源 PRD specReference.path/section/line。",
+            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 声明偏差。",
             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
@@ -910,37 +1027,11 @@ 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 ||
-                !(candidatePaths.length > 0
-                    ? candidatePaths.includes(ref.normalized)
-                    : isOpenspecSpecFilePath(ref.normalized)))
+                !isOpenspecSpecFilePath(ref.normalized))
                 .map((ref) => ref.raw)),
         ];
         if (invalidRefs.length > 0) {
@@ -958,10 +1049,13 @@ 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)),
             ];
@@ -973,7 +1067,7 @@ export async function runFrontendPrewriteGate(input) {
                     normalizationActions: [],
                     mockStrategy,
                     classification: "retryable-invalid",
-                    failureReason: `frontend prewrite gate: these uiComponentChoices specReference paths are missing a ledger specReference or lack a successful read event: ${uncorroborated.join(", ")}`,
+                    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(", ")}`,
                     failureCode: "component-spec-not-cited",
                     openspecReadPaths,
                     openspecCandidatePaths: candidatePaths,