@tea-agent/loop-agent 0.38.0 → 0.38.1

package/dist/workflows/dag/frontend-plan-render.js

@@ -0,0 +1,90 @@
+/**
+ * Deterministic Markdown renderer for a canonical frontend implementation
+ * contract. The prewrite gate materializes this as `contracts/frontend-plan.md`
+ * next to the contract JSON, so plan prose is never produced by the model — it
+ * is derived from the single machine contract at materialization time.
+ *
+ * The function is pure: the same contract always renders byte-identical
+ * Markdown, and absent optional fields render as placeholders without throwing.
+ */
+function bulletList(items) {
+    if (!items || items.length === 0)
+        return "";
+    return items.map((item) => `- ${item}`).join("\n");
+}
+function requirementsCoverage(contract) {
+    const lines = contract.requirements.map((requirement) => `- ${requirement.id}: ${requirement.expectedOutcome}`);
+    return lines.length > 0 ? lines.join("\n") : "_(no requirements)_";
+}
+function uiStateHandling(contract) {
+    const lines = contract.uiStates.map((state) => {
+        if (state.applicable) {
+            return `- ${state.name}: ${state.expectedBehavior ?? ""}`;
+        }
+        return `- ${state.name}: not applicable — ${state.notApplicableReason ?? ""}`;
+    });
+    return lines.length > 0 ? lines.join("\n") : "_(none)_";
+}
+function interactionNotes(contract) {
+    const lines = contract.interactions.map((interaction) => `- ${interaction.name}: ${interaction.trigger} → ${interaction.expectedBehavior}`);
+    return lines.length > 0 ? lines.join("\n") : "_(none)_";
+}
+function verificationPlan(contract) {
+    const lines = contract.verificationTargets.map((target) => `- ${target.id}: ${target.commandLabel} (${target.file})`);
+    return lines.length > 0 ? lines.join("\n") : "_(none)_";
+}
+function componentSelection(contract) {
+    const choices = contract.uiComponentChoices ?? [];
+    if (choices.length === 0)
+        return "_(not specified)_";
+    return choices
+        .map((choice) => {
+        const specReference = choice.specReference;
+        const refText = specReference
+            ? ` ${specReference.path}${specReference.section ? `#${specReference.section}` : ""}${specReference.line != null ? `:${specReference.line}` : ""}`
+            : "";
+        return `- ${choice.purpose} → ${choice.component} (${choice.decision})${refText ? `:${refText}` : ""} — ${choice.rationale}`;
+    })
+        .join("\n");
+}
+export function renderFrontendPlanMarkdown(contract) {
+    return [
+        "# Frontend Implementation Plan",
+        "",
+        "## Requirement Coverage",
+        requirementsCoverage(contract),
+        "",
+        "## Implementation Steps",
+        bulletList(contract.implementationSteps) || "_(not specified)_",
+        "",
+        "## Target Files",
+        bulletList(contract.targets.files) || "_(none)_",
+        "",
+        "## UI State Handling",
+        uiStateHandling(contract),
+        "",
+        "## Styling & Component Strategy",
+        contract.stylingStrategy || "_(not specified)_",
+        "",
+        "## Component Selection (spec conformance)",
+        componentSelection(contract),
+        "",
+        "## Interaction Notes",
+        interactionNotes(contract),
+        "",
+        "## Mock & API Strategy",
+        contract.mockApi.strategy,
+        "",
+        "## Dependency Policy",
+        contract.dependencyPolicy || "_(not specified)_",
+        "",
+        "## Verification Plan",
+        verificationPlan(contract),
+        "",
+        "## Real Integration Gap",
+        contract.realIntegrationGap || "_(not specified)_",
+        "",
+        "## Residual Risks",
+        bulletList(contract.residualRisks) || "_(none)_",
+    ].join("\n") + "\n";
+}

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

@@ -2,11 +2,16 @@ 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";
 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 +30,15 @@ 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",
 ]);
 export const frontendPrewriteResultV1Schema = z
     .object({
@@ -196,14 +210,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 +246,7 @@ async function checkOpenspecReadEvidence(input) {
                         : null;
                     if (relativePath &&
                         !isFailedToolResult(event) &&
-                        normalizedCandidates.has(relativePath)) {
+                        isOpenspecSpecFilePath(relativePath)) {
                         matched.add(relativePath);
                     }
                     startedReads.delete(event.toolCallId);
@@ -252,6 +261,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 +388,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 +398,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 +414,7 @@ export async function runFrontendPrewriteGate(input) {
         classification: "accepted",
         openspecReadPaths: [],
         openspecCandidatePaths: input.config.openspecCandidatePaths ?? [],
+        openspecPolicy,
     };
     let planText;
     try {
@@ -357,7 +450,60 @@ 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];
+        let originalText;
+        try {
+            originalText = await readNodeText(input.runDir, originalNodeId);
+        }
+        catch (error) {
+            return finalizePrewrite(input, {
+                ...basePending,
+                verdict,
+                classification: "retryable-invalid",
+                failureReason: `frontend prewrite gate revisionPatch mode requires original contract node ${originalNodeId}: ${error instanceof Error ? error.message : String(error)}`,
+                failureCode: "contract-invalid",
+            });
+        }
+        let originalValue;
+        let patchValue;
+        try {
+            originalValue = extractFrontendImplementationJson(originalText);
+            patchValue = extractFrontendImplementationJson(planText);
+        }
+        catch (error) {
+            return finalizePrewrite(input, {
+                ...basePending,
+                verdict,
+                classification: "retryable-invalid",
+                failureReason: `frontend prewrite gate revisionPatch mode failed to parse contract/patch: ${error instanceof Error ? error.message : String(error)}`,
+                failureCode: "contract-invalid",
+            });
+        }
+        let merged;
+        try {
+            merged = applyFrontendImplementationContractPatch(originalValue, patchValue);
+        }
+        catch (error) {
+            return finalizePrewrite(input, {
+                ...basePending,
+                verdict,
+                classification: "retryable-invalid",
+                failureReason: `frontend prewrite gate revisionPatch apply failed: ${error instanceof Error ? error.message : String(error)}`,
+                failureCode: "contract-invalid",
+            });
+        }
+        effectiveContractText = serializeDeterministicJson(merged);
+    }
+    const requirementIdSearchText = effectiveContractText ?? planText;
+    const missingIds = input.config.requiredRequirementIds.filter((id) => !requirementIdSearchText.includes(id));
     if (missingIds.length > 0) {
         return finalizePrewrite(input, {
             ...basePending,
@@ -410,7 +556,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 +577,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 +660,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 +894,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 +934,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");