@tea-agent/loop-agent 0.39.0-next.2 → 0.39.0-next.21

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

@@ -2,12 +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 { writeTextArtifactFile } from "../../infrastructure/harness/artifact-store.js";
 import { countExcludedGovernanceSpecFiles, resolveOpenspecGovernanceRoot, } from "../../task/frontend-project-capability.js";
-import { analyzeFrontendImplementationContract, writeFrontendImplementationContractArtifact, writeDeterministicJsonArtifact, assertFrontendSourceBindingFresh, deterministicSha256, sha256Hex, FrontendContractFailure, frontendNormalizationActionSchema, } from "./frontend-implementation-contract.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
@@ -31,6 +36,11 @@ export const frontendPrewriteFailureCodeSchema = z.enum([
     "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({
@@ -163,16 +173,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
@@ -442,7 +489,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,
@@ -495,7 +613,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,
         });
     }
@@ -515,6 +634,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
@@ -711,6 +845,105 @@ export async function runFrontendPrewriteGate(input) {
             }
         }
     }
+    // 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,
@@ -718,6 +951,8 @@ export async function runFrontendPrewriteGate(input) {
         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,