@tea-agent/loop-agent 0.1.0-fe-test.0

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

@@ -0,0 +1,1011 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+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 { 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
+ * downstream routing (repair prompting, dashboards, retry policies) can act on
+ * a stable code instead of parsing prose.
+ */
+export const frontendPrewriteFailureCodeSchema = z.enum([
+    "plan-text-unreadable",
+    "review-text-unreadable",
+    "verdict-not-pass",
+    "missing-requirement-ids",
+    "source-binding-not-fresh",
+    "contract-invalid",
+    "contract-blocked",
+    "mock-strategy-outside-allowed",
+    "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({
+    schemaVersion: z.literal(1),
+    schemaId: z.literal(FRONTEND_PREWRITE_RESULT_SCHEMA_ID),
+    classification: z.enum([
+        "accepted",
+        "accepted-normalized",
+        "retryable-invalid",
+        "blocked",
+    ]),
+    failureCode: frontendPrewriteFailureCodeSchema.nullable(),
+    normalizationActions: z.array(frontendNormalizationActionSchema),
+    candidateRawSha256: z.string().regex(/^[a-f0-9]{64}$/),
+    candidateJsonSha256: z.string().regex(/^[a-f0-9]{64}$/).nullable(),
+    canonicalSha256: z.string().regex(/^[a-f0-9]{64}$/).nullable(),
+    selectedPlanNodeId: z.string().regex(/^[a-z][a-z0-9-]*$/),
+    sourceBindingSha256: z.string().regex(/^[a-f0-9]{64}$/).nullable(),
+    writeSetDigest: z.string().regex(/^[a-f0-9]{64}$/).nullable(),
+    retryCount: z.number().int().min(0).max(1),
+    maxRetryCount: z.literal(1),
+    failureReason: z.string().nullable(),
+    digestAlgorithm: z.literal("sha256"),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const acceptedLike = value.classification === "accepted" ||
+        value.classification === "accepted-normalized";
+    const failed = value.classification === "retryable-invalid" ||
+        value.classification === "blocked";
+    if (acceptedLike) {
+        if (value.failureReason !== null)
+            ctx.addIssue({
+                code: "custom",
+                message: "failureReason must be null for accepted/accepted-normalized",
+                path: ["failureReason"],
+            });
+        if (value.failureCode !== null)
+            ctx.addIssue({
+                code: "custom",
+                message: "failureCode must be null for accepted/accepted-normalized",
+                path: ["failureCode"],
+            });
+        if (!value.candidateJsonSha256 || !value.canonicalSha256)
+            ctx.addIssue({
+                code: "custom",
+                message: "candidateJsonSha256 and canonicalSha256 are required for accepted/accepted-normalized",
+                path: ["candidateJsonSha256"],
+            });
+    }
+    if (value.classification === "accepted" && value.normalizationActions.length !== 0)
+        ctx.addIssue({
+            code: "custom",
+            message: "accepted must have empty normalizationActions",
+            path: ["normalizationActions"],
+        });
+    if (value.classification === "accepted-normalized" &&
+        value.normalizationActions.length === 0)
+        ctx.addIssue({
+            code: "custom",
+            message: "accepted-normalized must have non-empty normalizationActions",
+            path: ["normalizationActions"],
+        });
+    if (failed) {
+        if (value.normalizationActions.length !== 0)
+            ctx.addIssue({
+                code: "custom",
+                message: "retryable-invalid/blocked must have empty normalizationActions",
+                path: ["normalizationActions"],
+            });
+        if (!value.failureReason)
+            ctx.addIssue({
+                code: "custom",
+                message: "failureReason must be non-empty for retryable-invalid/blocked",
+                path: ["failureReason"],
+            });
+        if (value.failureCode === null)
+            ctx.addIssue({
+                code: "custom",
+                message: "failureCode must be non-null for retryable-invalid/blocked",
+                path: ["failureCode"],
+            });
+    }
+});
+export const frontendWriterAdmissionSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    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}$/),
+    checkedAt: z.string().min(1),
+    reason: z.string().nullable(),
+})
+    .strict();
+async function selectNode(runDir, primary, fallbacks) {
+    const candidates = [primary, ...fallbacks.filter((id) => id !== primary)];
+    const rejections = [];
+    for (const nodeId of candidates) {
+        try {
+            const raw = await readFile(path.join(runDir, `${nodeId}.json`), "utf8");
+            const record = JSON.parse(raw);
+            if (record.status === "FINISHED")
+                return nodeId;
+            rejections.push(`${nodeId}: status=${String(record.status)}`);
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                rejections.push(`${nodeId}: file missing`);
+                continue;
+            }
+            throw error;
+        }
+    }
+    throw new Error(`frontend prewrite gate no FINISHED candidate: ${rejections.join("; ")}`);
+}
+async function readNodeText(runDir, nodeId) {
+    const record = JSON.parse(await readFile(path.join(runDir, `${nodeId}.json`), "utf8"));
+    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");
+    if (!text)
+        throw new Error(`frontend prewrite gate empty output from ${nodeId}`);
+    return text;
+}
+async function readNodeRawText(runDir, nodeId) {
+    const record = JSON.parse(await readFile(path.join(runDir, `${nodeId}.json`), "utf8"));
+    return record.assistantText ?? record.stdout ?? "";
+}
+/**
+ * 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);
+    // 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
+    // prompt while making the deterministic gate resilient to that drift.
+    const verdictLine = normalizedLines.find((line) => /^VERDICT:/.test(line)) ?? first;
+    if (/^VERDICT:\s*pass(?:\s*[.!?。！？]|\s+|$)/i.test(verdictLine))
+        return "VERDICT: pass";
+    if (/^VERDICT:\s*request-revision(?:\s*[.!?。！？]|\s+|$)/i.test(verdictLine))
+        return "VERDICT: request-revision";
+    return verdictLine;
+}
+function eventArgs(event) {
+    return event.args ?? event.toolInput ?? event.input ?? {};
+}
+function toRepoRelativePath(filePath, repoRoot) {
+    const resolved = path.resolve(repoRoot, filePath);
+    const relative = path.relative(repoRoot, resolved);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+        return null;
+    }
+    return relative.replaceAll(path.sep, "/");
+}
+function isFailedToolResult(event) {
+    return (event.isError === true ||
+        event.toolResult?.error != null ||
+        event.toolResult?.ok === false ||
+        event.result?.error != null ||
+        event.result?.ok === false);
+}
+async function collectOpenspecReadPaths(input) {
+    const { runDir, planNodeId, reviewNodeId, repoRoot } = input;
+    const matched = new Set();
+    for (const nodeId of [planNodeId, reviewNodeId]) {
+        const eventsPath = path.join(runDir, nodeId, "session-events.jsonl");
+        try {
+            const raw = await readFile(eventsPath, "utf8");
+            const startedReads = new Map();
+            for (const line of raw.split(/\r?\n/)) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                let event;
+                try {
+                    event = JSON.parse(trimmed);
+                }
+                catch {
+                    continue;
+                }
+                if (event.type === "tool_execution_start" &&
+                    event.toolName === "read" &&
+                    event.toolCallId) {
+                    const readPath = eventArgs(event).path;
+                    if (typeof readPath === "string") {
+                        startedReads.set(event.toolCallId, readPath);
+                    }
+                }
+                else if (event.type === "tool_execution_end" &&
+                    event.toolName === "read" &&
+                    event.toolCallId !== undefined) {
+                    const readPath = startedReads.get(event.toolCallId);
+                    const relativePath = readPath
+                        ? toRepoRelativePath(readPath, repoRoot)
+                        : null;
+                    if (relativePath &&
+                        !isFailedToolResult(event) &&
+                        isOpenspecSpecFilePath(relativePath)) {
+                        matched.add(relativePath);
+                    }
+                    startedReads.delete(event.toolCallId);
+                }
+            }
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+            throw error;
+        }
+    }
+    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)
+        : null;
+    const writeSetDigest = input.config.implementationWriteSet
+        ? deterministicSha256([...new Set(input.config.implementationWriteSet)].sort())
+        : null;
+    const prewriteResult = frontendPrewriteResultV1Schema.parse({
+        schemaVersion: 1,
+        schemaId: FRONTEND_PREWRITE_RESULT_SCHEMA_ID,
+        classification: pending.classification,
+        normalizationActions: pending.normalizationActions,
+        candidateRawSha256: pending.candidateRawSha256,
+        candidateJsonSha256: pending.candidateJsonSha256,
+        canonicalSha256: pending.canonicalSha256,
+        selectedPlanNodeId: pending.planNodeId,
+        sourceBindingSha256,
+        writeSetDigest,
+        retryCount: 0,
+        maxRetryCount: 1,
+        failureReason: pending.failureReason,
+        failureCode: pending.failureCode,
+        digestAlgorithm: "sha256",
+    });
+    const written = await writeDeterministicJsonArtifact(input.runDir, path.posix.join(input.config.outputDir, FRONTEND_PREWRITE_RESULT_ARTIFACT_NAME), prewriteResult);
+    return {
+        ok: true,
+        classification: pending.classification,
+        planNodeId: pending.planNodeId,
+        reviewNodeId: pending.reviewNodeId,
+        verdict: pending.verdict,
+        mockStrategy: pending.mockStrategy,
+        artifact: pending.artifact,
+        prewriteResult: {
+            path: written.path,
+            sha256: written.sha256,
+            schemaId: FRONTEND_PREWRITE_RESULT_SCHEMA_ID,
+        },
+        failureReason: pending.failureReason,
+        failureCode: pending.failureCode,
+        normalizationActions: pending.normalizationActions,
+        candidateRawSha256: pending.candidateRawSha256,
+        candidateJsonSha256: pending.candidateJsonSha256,
+        canonicalSha256: pending.canonicalSha256,
+        openspecReadPaths: pending.openspecReadPaths,
+        openspecCandidatePaths: pending.openspecCandidatePaths,
+        openspecPolicy: pending.openspecPolicy,
+    };
+}
+export async function runFrontendPrewriteGate(input) {
+    const workspaceRoot = input.workspaceRoot ?? input.repoRoot;
+    // selectNode throws for a scheduling defect (no FINISHED plan/review). That
+    // remains an ERROR and is intentionally not classified into prewrite-result.
+    const planNodeId = await selectNode(input.runDir, input.config.planFromNodeId, input.config.planFallbackFromNodeIds);
+    const reviewNodeId = await selectNode(input.runDir, input.config.reviewFromNodeId, input.config.reviewFallbackFromNodeIds);
+    const candidateRawSha256 = sha256Hex(await readNodeRawText(input.runDir, planNodeId));
+    const openspecPolicy = input.config.openspecPolicy ?? "scan-strict";
+    const basePending = {
+        planNodeId,
+        reviewNodeId,
+        verdict: "",
+        candidateRawSha256,
+        candidateJsonSha256: null,
+        canonicalSha256: null,
+        normalizationActions: [],
+        mockStrategy: undefined,
+        artifact: undefined,
+        failureReason: null,
+        failureCode: null,
+        classification: "accepted",
+        openspecReadPaths: [],
+        openspecCandidatePaths: input.config.openspecCandidatePaths ?? [],
+        openspecPolicy,
+    };
+    let planText;
+    try {
+        planText = await readNodeText(input.runDir, planNodeId);
+    }
+    catch (error) {
+        return finalizePrewrite(input, {
+            ...basePending,
+            classification: "retryable-invalid",
+            failureReason: error instanceof Error ? error.message : String(error),
+            failureCode: "plan-text-unreadable",
+        });
+    }
+    let reviewText;
+    try {
+        reviewText = await readNodeText(input.runDir, reviewNodeId);
+    }
+    catch (error) {
+        return finalizePrewrite(input, {
+            ...basePending,
+            classification: "blocked",
+            failureReason: `frontend prewrite gate blocked by ${reviewNodeId}: ${error instanceof Error ? error.message : String(error)}`,
+            failureCode: "review-text-unreadable",
+        });
+    }
+    const verdict = firstNonEmptyVerdictLine(reviewText);
+    if (verdict !== "VERDICT: pass") {
+        return finalizePrewrite(input, {
+            ...basePending,
+            verdict,
+            classification: "blocked",
+            failureReason: `frontend prewrite gate blocked by ${reviewNodeId}: ${verdict || "missing VERDICT"}`,
+            failureCode: "verdict-not-pass",
+        });
+    }
+    // revisionPatch mode: the effective plan node emits an RFC 7386 merge-patch
+    // delta against the original contract node (planFallbackFromNodeIds[0]).
+    // Legacy DAGs without revisionPatch (undefined) keep full-contract semantics.
+    const revisionPatchMode = input.config.revisionPatch === true &&
+        planNodeId === input.config.planFromNodeId &&
+        input.config.planFallbackFromNodeIds.length > 0;
+    let effectiveContractText = null;
+    if (revisionPatchMode) {
+        const originalNodeId = input.config.planFallbackFromNodeIds[0];
+        try {
+            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,
+            verdict,
+            classification: "blocked",
+            failureReason: `frontend prewrite gate missing requirement ids: ${missingIds.join(", ")}`,
+            failureCode: "missing-requirement-ids",
+        });
+    }
+    if (workspaceRoot) {
+        if (input.config.requireSourceFreshness) {
+            if (!input.sourceBinding) {
+                throw new Error("frontend prewrite gate requires sourceBinding for freshness check");
+            }
+            try {
+                await assertFrontendSourceBindingFresh({
+                    workspaceRoot,
+                    binding: input.sourceBinding,
+                });
+            }
+            catch (error) {
+                return finalizePrewrite(input, {
+                    ...basePending,
+                    verdict,
+                    classification: "blocked",
+                    failureReason: error instanceof Error ? error.message : String(error),
+                    failureCode: "source-binding-not-fresh",
+                });
+            }
+        }
+        let hasGitMetadata = true;
+        try {
+            await stat(path.join(workspaceRoot, ".git"));
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes("ENOENT"))
+                hasGitMetadata = false;
+            else
+                throw error;
+        }
+        if (hasGitMetadata)
+            await captureFrontendWorktreeBaseline({
+                runDir: input.runDir,
+                workspaceRoot,
+            });
+    }
+    // Candidate -> canonical conversion. The gate consumes the selected
+    // plan/revision assistant output directly and is the only conversion point.
+    let analysis;
+    try {
+        analysis = await analyzeFrontendImplementationContract({
+            runDir: input.runDir,
+            fromNodeId: effectiveContractText ? undefined : planNodeId,
+            rawContractText: effectiveContractText ?? undefined,
+            sourceBinding: input.sourceBinding,
+        });
+    }
+    catch (error) {
+        if (error instanceof FrontendContractFailure) {
+            return finalizePrewrite(input, {
+                ...basePending,
+                verdict,
+                classification: error.kind,
+                failureReason: error.message,
+                failureCode: error.kind === "retryable-invalid"
+                    ? "contract-invalid"
+                    : "contract-blocked",
+                candidateJsonSha256: error.candidateJsonSha256,
+                normalizationActions: [],
+            });
+        }
+        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
+            .map((strategy) => JSON.stringify(strategy))
+            .join(", ");
+        const forcedNotNeeded = input.config.allowedMockStrategies.length === 1 &&
+            input.config.allowedMockStrategies[0] === "not-needed";
+        const reason = forcedNotNeeded
+            ? "the task is auto/not-required or lacks authorized deterministic Mock verification commands"
+            : `allowed strategies are [${quotedAllowed}]`;
+        return finalizePrewrite(input, {
+            ...basePending,
+            verdict,
+            candidateJsonSha256: analysis.candidateJsonSha256,
+            normalizationActions: [],
+            mockStrategy,
+            classification: "blocked",
+            failureReason: `frontend contract mock strategy "${mockStrategy}" is incompatible with the generated allowed strategies [${quotedAllowed}]; ${reason}. Regenerate the DAG or set frontendMock.policy=required with authorized Mock verification commands.`,
+            failureCode: "mock-strategy-outside-allowed",
+        });
+    }
+    // Mock command binding (main): a non-not-needed strategy can only be proven
+    // by the DAG's frozen Mock verification commands. Block before any write is
+    // authorized when none were materialized at generation time.
+    if (mockStrategy !== "not-needed" &&
+        (input.config.mockCommandLabels?.length ?? 0) === 0) {
+        return finalizePrewrite(input, {
+            ...basePending,
+            verdict,
+            candidateJsonSha256: analysis.candidateJsonSha256,
+            normalizationActions: [],
+            mockStrategy,
+            classification: "blocked",
+            failureReason: `frontend prewrite gate blocked: contract selected Mock strategy ${mockStrategy} but the DAG has no authorized Mock verification commands; add frontendMock.verifyCommands or a project mock script, or select not-needed`,
+            failureCode: "mock-strategy-no-verification-commands",
+        });
+    }
+    if (input.config.implementationWriteSet) {
+        const writeSet = new Set(input.config.implementationWriteSet);
+        const contractTargets = new Set(analysis.canonical.targets.files);
+        const uncoveredTargets = [...contractTargets].filter((target) => ![...writeSet].some((pattern) => pathMatchesPattern(target, pattern) || target === pattern));
+        if (uncoveredTargets.length > 0) {
+            return finalizePrewrite(input, {
+                ...basePending,
+                verdict,
+                candidateJsonSha256: analysis.candidateJsonSha256,
+                normalizationActions: [],
+                mockStrategy,
+                classification: "blocked",
+                failureReason: `frontend prewrite gate contract target is outside implementation writeSet: ${uncoveredTargets.join(", ")}`,
+                failureCode: "target-outside-write-set",
+            });
+        }
+        const nonStaticVTs = analysis.canonical.verificationTargets.filter((vt) => vt.type !== "static");
+        const uncoveredVTs = nonStaticVTs.filter((vt) => ![...writeSet].some((pattern) => pathMatchesPattern(vt.file, pattern) || vt.file === pattern));
+        if (uncoveredVTs.length > 0) {
+            return finalizePrewrite(input, {
+                ...basePending,
+                verdict,
+                candidateJsonSha256: analysis.candidateJsonSha256,
+                normalizationActions: [],
+                mockStrategy,
+                classification: "blocked",
+                failureReason: `frontend prewrite gate verification target is outside implementation writeSet: ${uncoveredVTs.map((vt) => vt.file).join(", ")}`,
+                failureCode: "verification-target-outside-write-set",
+            });
+        }
+    }
+    // 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,
+        outputDir: input.config.outputDir,
+        artifactName: input.config.artifactName,
+        canonical: analysis.canonical,
+    });
+    // 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,
+        verdict,
+        classification,
+        failureReason: null,
+        candidateJsonSha256: analysis.candidateJsonSha256,
+        canonicalSha256: artifact.sha256,
+        normalizationActions: analysis.normalizationActions,
+        mockStrategy,
+        artifact,
+        openspecReadPaths,
+        openspecCandidatePaths: candidatePaths,
+    });
+}
+export function formatFrontendPrewriteGateStdout(result) {
+    const lines = [];
+    if (result.classification === "accepted" ||
+        result.classification === "accepted-normalized") {
+        lines.push("Frontend prewrite gate: pass");
+    }
+    else if (result.classification === "blocked") {
+        lines.push("Frontend prewrite gate: blocked");
+    }
+    else {
+        lines.push("Frontend prewrite gate: retryable-invalid");
+    }
+    lines.push(`Classification: ${result.classification}`);
+    lines.push(`Plan: ${result.planNodeId}`);
+    lines.push(`Review: ${result.reviewNodeId}`);
+    if (result.mockStrategy)
+        lines.push(`Mock strategy: ${result.mockStrategy}`);
+    if (result.artifact) {
+        lines.push(`Structured artifact: ${result.artifact.path}`);
+        lines.push(`Schema: ${result.artifact.schemaId}`);
+        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(", ")}`);
+    }
+    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");
+}