@tea-agent/loop-agent 0.38.0 → 0.38.2

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

@@ -2,11 +2,17 @@ import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
 import { isOpenspecSpecFilePath } from "../../shared/openspec-spec.js";
-import { analyzeFrontendImplementationContract, writeFrontendImplementationContractArtifact, writeDeterministicJsonArtifact, assertFrontendSourceBindingFresh, deterministicSha256, sha256Hex, FrontendContractFailure, frontendNormalizationActionSchema, } from "./frontend-implementation-contract.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 { 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
@@ -25,6 +31,16 @@ export const frontendPrewriteFailureCodeSchema = z.enum([
     "mock-strategy-no-verification-commands",
     "target-outside-write-set",
     "verification-target-outside-write-set",
+    "openspec-not-read",
+    "candidate-missing-drift",
+    "openspec-citation-block-unparseable",
+    "openspec-not-cited",
+    "openspec-citation-not-read",
+    "component-spec-reference-invalid",
+    "component-spec-not-cited",
+    "component-choices-missing",
+    "contract-too-large",
+    "revision-patch-unmergeable",
 ]);
 export const frontendPrewriteResultV1Schema = z
     .object({
@@ -146,9 +162,12 @@ async function readNodeText(runDir, nodeId) {
     if (record.status !== "FINISHED") {
         throw new Error(`frontend prewrite gate requires FINISHED node ${nodeId} (got ${String(record.status)})`);
     }
-    const text = [record.assistantText, record.stdout]
-        .filter((value) => Boolean(value?.trim()))
-        .join("\n");
+    // 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.
+    const text = record.assistantText?.trim() || record.stdout?.trim() || "";
     if (!text)
         throw new Error(`frontend prewrite gate empty output from ${nodeId}`);
     return text;
@@ -157,16 +176,53 @@ async function readNodeRawText(runDir, nodeId) {
     const record = JSON.parse(await readFile(path.join(runDir, `${nodeId}.json`), "utf8"));
     return record.assistantText ?? record.stdout ?? "";
 }
+/**
+ * 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;
+    }
+    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);
+}
 function firstNonEmptyVerdictLine(text) {
     const lines = text
         .split(/\r?\n/)
         .map((line) => line.trim())
         .filter(Boolean);
-    const normalize = (line) => {
-        const emphasized = line.match(/^(?:`{1,3}|\*{1,3})\s*(VERDICT:[^`*]+?)\s*(?:`{1,3}|\*{1,3})$/);
-        return (emphasized?.[1] ?? line).trim();
-    };
-    const normalizedLines = lines.map(normalize);
+    // Emphasis stripping (backtick + asterisk) is shared with the runIf
+    // selector and node-level output-protocol validation via
+    // normalizeVerdictCandidateLine. The gate keeps its own loose
+    // pass/request-revision normalization below (prefix match + trailing
+    // prose tolerance) for deterministic fail-closed behavior.
+    const normalizedLines = lines.map(normalizeVerdictCandidateLine);
     const first = normalizedLines[0] ?? "";
     // The prompt requires VERDICT to be the first non-empty line, but model
     // output can still prepend a summary. Keep the protocol strict in the
@@ -196,14 +252,9 @@ function isFailedToolResult(event) {
         event.result?.error != null ||
         event.result?.ok === false);
 }
-async function checkOpenspecReadEvidence(input) {
-    const { runDir, candidatePaths, planNodeId, reviewNodeId, repoRoot } = input;
-    if (candidatePaths.length === 0)
-        return [];
+async function collectOpenspecReadPaths(input) {
+    const { runDir, planNodeId, reviewNodeId, repoRoot } = input;
     const matched = new Set();
-    const normalizedCandidates = new Set(candidatePaths
-        .map((candidate) => toRepoRelativePath(candidate, repoRoot))
-        .filter((candidate) => Boolean(candidate && isOpenspecSpecFilePath(candidate))));
     for (const nodeId of [planNodeId, reviewNodeId]) {
         const eventsPath = path.join(runDir, nodeId, "session-events.jsonl");
         try {
@@ -237,7 +288,7 @@ async function checkOpenspecReadEvidence(input) {
                         : null;
                     if (relativePath &&
                         !isFailedToolResult(event) &&
-                        normalizedCandidates.has(relativePath)) {
+                        isOpenspecSpecFilePath(relativePath)) {
                         matched.add(relativePath);
                     }
                     startedReads.delete(event.toolCallId);
@@ -252,6 +303,87 @@ async function checkOpenspecReadEvidence(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("#");
+    if (hashIndex >= 0)
+        candidate = candidate.slice(0, hashIndex);
+    candidate = candidate.replace(/\\/g, "/");
+    if (!candidate)
+        return null;
+    if (repoRoot) {
+        const relative = toRepoRelativePath(candidate, repoRoot);
+        return relative ? relative.replace(/\\/g, "/") : null;
+    }
+    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;
+            }
+            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 });
+        }
+    }
+    return { blockPresent, unparseable, citations };
+}
 async function finalizePrewrite(input, pending) {
     const sourceBindingSha256 = input.sourceBinding
         ? deterministicSha256(input.sourceBinding)
@@ -298,6 +430,7 @@ async function finalizePrewrite(input, pending) {
         canonicalSha256: pending.canonicalSha256,
         openspecReadPaths: pending.openspecReadPaths,
         openspecCandidatePaths: pending.openspecCandidatePaths,
+        openspecPolicy: pending.openspecPolicy,
     };
 }
 export async function runFrontendPrewriteGate(input) {
@@ -307,6 +440,7 @@ export async function runFrontendPrewriteGate(input) {
     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));
+    const openspecPolicy = input.config.openspecPolicy ?? "scan-strict";
     const basePending = {
         planNodeId,
         reviewNodeId,
@@ -322,6 +456,7 @@ export async function runFrontendPrewriteGate(input) {
         classification: "accepted",
         openspecReadPaths: [],
         openspecCandidatePaths: input.config.openspecCandidatePaths ?? [],
+        openspecPolicy,
     };
     let planText;
     try {
@@ -357,7 +492,78 @@ export async function runFrontendPrewriteGate(input) {
             failureCode: "verdict-not-pass",
         });
     }
-    const missingIds = input.config.requiredRequirementIds.filter((id) => !planText.includes(id));
+    // 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 {
+            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 missingIds = input.config.requiredRequirementIds.filter((id) => !requirementIdSearchText.includes(id));
     if (missingIds.length > 0) {
         return finalizePrewrite(input, {
             ...basePending,
@@ -410,7 +616,8 @@ export async function runFrontendPrewriteGate(input) {
     try {
         analysis = await analyzeFrontendImplementationContract({
             runDir: input.runDir,
-            fromNodeId: planNodeId,
+            fromNodeId: effectiveContractText ? undefined : planNodeId,
+            rawContractText: effectiveContractText ?? undefined,
             sourceBinding: input.sourceBinding,
         });
     }
@@ -430,6 +637,21 @@ export async function runFrontendPrewriteGate(input) {
         }
         throw error;
     }
+    // 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
@@ -498,6 +720,233 @@ 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 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) {
+            try {
+                await stat(path.join(candidateRoot, candidate));
+            }
+            catch {
+                missingCandidates.push(candidate);
+            }
+        }
+    }
+    if (missingCandidates.length > 0) {
+        return finalizePrewrite(input, {
+            ...basePending,
+            verdict,
+            candidateJsonSha256: analysis.candidateJsonSha256,
+            normalizationActions: [],
+            mockStrategy,
+            classification: "blocked",
+            failureReason: `frontend prewrite gate blocked: openspec candidate paths frozen at generation time no longer exist on disk: ${missingCandidates.join(", ")}. 候选集在生成期冻结，这些候选在生成后被删除/改名，请修正后重新生成 DAG。`,
+            failureCode: "candidate-missing-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.
+    }
+    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
+    // that declared component/token selections trace to the frontend spec
+    // (openspec/ai_workspace component + theme) instead of a model's ad-hoc
+    // "better" choice. Runs after the openspec read gate so citation + read
+    // evidence are already resolved.
+    const componentChoices = analysis.canonical.uiComponentChoices ?? [];
+    const componentSpecCandidates = input.config.componentSpecCandidatePaths ?? [];
+    const hasUiVisibleWork = analysis.canonical.uiStates.some((state) => state.applicable) ||
+        analysis.canonical.interactions.length > 0;
+    if (componentSpecCandidates.length > 0 &&
+        hasUiVisibleWork &&
+        componentChoices.length === 0) {
+        return finalizePrewrite(input, {
+            ...basePending,
+            verdict,
+            candidateJsonSha256: analysis.candidateJsonSha256,
+            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 声明偏差。",
+            failureCode: "component-choices-missing",
+            openspecReadPaths,
+            openspecCandidatePaths: candidatePaths,
+        });
+    }
+    const componentSpecReferences = componentChoices
+        .map((choice) => ({
+        raw: choice.specReference?.path ?? "",
+        normalized: choice.specReference?.path
+            ? normalizeCitationPath(choice.specReference.path, candidateRoot)
+            : null,
+    }))
+        .filter((ref) => ref.raw.length > 0);
+    if (componentSpecReferences.length > 0) {
+        const invalidRefs = [
+            ...new Set(componentSpecReferences
+                .filter((ref) => !ref.normalized ||
+                !isOpenspecSpecFilePath(ref.normalized))
+                .map((ref) => ref.raw)),
+        ];
+        if (invalidRefs.length > 0) {
+            return finalizePrewrite(input, {
+                ...basePending,
+                verdict,
+                candidateJsonSha256: analysis.candidateJsonSha256,
+                normalizationActions: [],
+                mockStrategy,
+                classification: "retryable-invalid",
+                failureReason: `frontend prewrite gate: these uiComponentChoices specReference paths are not supported openspec/ai_workspace spec files: ${invalidRefs.join(", ")}`,
+                failureCode: "component-spec-reference-invalid",
+                openspecReadPaths,
+                openspecCandidatePaths: candidatePaths,
+            });
+        }
+        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)),
+            ];
+            if (uncorroborated.length > 0) {
+                return finalizePrewrite(input, {
+                    ...basePending,
+                    verdict,
+                    candidateJsonSha256: analysis.candidateJsonSha256,
+                    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(", ")}`,
+                    failureCode: "component-spec-not-cited",
+                    openspecReadPaths,
+                    openspecCandidatePaths: candidatePaths,
+                });
+            }
+        }
+    }
+    // Render the deterministic plan.md from the canonical contract (fail-closed
+    // before any artifact is written: no contract, no writer authorization).
+    let planMarkdown;
+    try {
+        planMarkdown = renderFrontendPlanMarkdown(analysis.canonical);
+    }
+    catch (error) {
+        return finalizePrewrite(input, {
+            ...basePending,
+            verdict,
+            candidateJsonSha256: analysis.candidateJsonSha256,
+            normalizationActions: [],
+            mockStrategy,
+            classification: "retryable-invalid",
+            failureReason: `frontend prewrite gate: failed to render ${input.config.planMdArtifactName ?? "frontend-plan.md"}: ${error instanceof Error ? error.message : String(error)}`,
+            failureCode: "contract-invalid",
+        });
+    }
     // Materialize the canonical contract only after every governance check passed.
     const artifact = await writeFrontendImplementationContractArtifact({
         runDir: input.runDir,
@@ -505,14 +954,8 @@ export async function runFrontendPrewriteGate(input) {
         artifactName: input.config.artifactName,
         canonical: analysis.canonical,
     });
-    const candidatePaths = input.config.openspecCandidatePaths ?? [];
-    const openspecReadPaths = await checkOpenspecReadEvidence({
-        runDir: input.runDir,
-        candidatePaths,
-        planNodeId,
-        reviewNodeId,
-        repoRoot: workspaceRoot ?? process.cwd(),
-    });
+    // Materialize the rendered plan.md in the same outputDir as the contract.
+    await writeTextArtifactFile(path.join(input.runDir, path.posix.join(input.config.outputDir, input.config.planMdArtifactName ?? "frontend-plan.md")), planMarkdown);
     const classification = analysis.normalizationActions.length > 0 ? "accepted-normalized" : "accepted";
     return finalizePrewrite(input, {
         ...basePending,
@@ -551,12 +994,20 @@ export function formatFrontendPrewriteGateStdout(result) {
         lines.push(`SHA-256: ${result.artifact.sha256}`);
     }
     lines.push(`Prewrite result: ${result.prewriteResult.path}`);
+    lines.push(`Openspec policy: ${result.openspecPolicy}`);
     if (result.failureReason)
         lines.push(`Failure reason: ${result.failureReason}`);
     if (result.openspecReadPaths.length > 0) {
         lines.push(`openspec read: ${result.openspecReadPaths.join(", ")}`);
     }
-    else if (result.openspecCandidatePaths.length === 0) {
+    if (result.openspecCandidatePaths.length > 0) {
+        const readSet = new Set(result.openspecReadPaths);
+        const unread = result.openspecCandidatePaths.filter((candidate) => !readSet.has(candidate));
+        if (unread.length > 0) {
+            lines.push(`openspec unread: ${unread.join(", ")}`);
+        }
+    }
+    else {
         lines.push("openspec: unavailable");
     }
     return lines.join("\n");