@tea-agent/loop-agent 0.36.4-beta.0 → 0.37.1-beta.0

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

@@ -1,126 +1,9 @@
 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 { frontendImplementationContractSchema, materializeFrontendImplementationContract, assertFrontendSourceBindingFresh, } from "./frontend-implementation-contract.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";
-/**
- * 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",
-]);
-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 = [];
@@ -154,10 +37,6 @@ async function readNodeText(runDir, nodeId) {
         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 ?? "";
-}
 function firstNonEmptyVerdictLine(text) {
     const lines = text
         .split(/\r?\n/)
@@ -253,141 +132,16 @@ async function checkOpenspecReadEvidence(input) {
     }
     return [...matched];
 }
-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,
-    };
-}
 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 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 ?? [],
-    };
-    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",
-        });
-    }
-    const missingIds = input.config.requiredRequirementIds.filter((id) => !planText.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) {
+            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",
-                });
-            }
+            await assertFrontendSourceBindingFresh({
+                workspaceRoot,
+                binding: input.sourceBinding,
+            });
         }
         let hasGitMetadata = true;
         try {
@@ -405,34 +159,31 @@ export async function runFrontendPrewriteGate(input) {
                 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: planNodeId,
-            sourceBinding: input.sourceBinding,
-        });
+    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 planText = await readNodeText(input.runDir, planNodeId);
+    const reviewText = await readNodeText(input.runDir, reviewNodeId);
+    const verdict = firstNonEmptyVerdictLine(reviewText);
+    if (verdict !== "VERDICT: pass") {
+        throw new Error(`frontend prewrite gate blocked by ${reviewNodeId}: ${verdict || "missing VERDICT"}`);
     }
-    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;
+    const missingIds = input.config.requiredRequirementIds.filter((id) => !planText.includes(id));
+    if (missingIds.length > 0) {
+        throw new Error(`frontend prewrite gate missing requirement ids: ${missingIds.join(", ")}`);
     }
-    const mockStrategy = analysis.canonical.mockApi.strategy;
-    if (!input.config.allowedMockStrategies.includes(mockStrategy)) {
+    // Always rematerialize from the selected plan node. Reusing a previous
+    // contracts/*.json would accept stale contracts when a higher-priority
+    // FINISHED primary is present but invalid (see composite-shell invalid-primary).
+    const artifact = await materializeFrontendImplementationContract({
+        runDir: input.runDir,
+        fromNodeId: planNodeId,
+        artifactName: input.config.artifactName,
+        outputDir: input.config.outputDir,
+        sourceBinding: input.sourceBinding,
+    });
+    const raw = JSON.parse(await readFile(artifact.path, "utf8"));
+    const contract = frontendImplementationContractSchema.parse(raw);
+    if (!input.config.allowedMockStrategies.includes(contract.mockApi.strategy)) {
         const quotedAllowed = input.config.allowedMockStrategies
             .map((strategy) => JSON.stringify(strategy))
             .join(", ");
@@ -441,67 +192,30 @@ export async function runFrontendPrewriteGate(input) {
         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",
-        });
+        throw new Error(`frontend contract mock strategy "${contract.mockApi.strategy}" is incompatible with the generated allowed strategies [${quotedAllowed}]; ${reason}. Regenerate the DAG or set frontendMock.policy=required with authorized Mock verification commands.`);
     }
-    // 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" &&
+    // Fail early instead of at the verification trace: a non-not-needed strategy
+    // can only be proven by executing the DAG's frozen Mock verification
+    // commands. If none were materialized at generation time the contract would
+    // fail "trace: selected Mock strategy requires successful Mock verification
+    // commands" after implementation, so block before any write is authorized.
+    if (contract.mockApi.strategy !== "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",
-        });
+        throw new Error(`frontend prewrite gate blocked: contract selected Mock strategy ${contract.mockApi.strategy} but the DAG has no authorized Mock verification commands; add frontendMock.verifyCommands or a project mock script, or select not-needed`);
     }
     if (input.config.implementationWriteSet) {
         const writeSet = new Set(input.config.implementationWriteSet);
-        const contractTargets = new Set(analysis.canonical.targets.files);
+        const contractTargets = new Set(contract.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",
-            });
+            throw new Error(`frontend prewrite gate contract target is outside implementation writeSet: ${uncoveredTargets.join(", ")}`);
         }
-        const nonStaticVTs = analysis.canonical.verificationTargets.filter((vt) => vt.type !== "static");
+        const nonStaticVTs = contract.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",
-            });
+            throw new Error(`frontend prewrite gate verification target is outside implementation writeSet: ${uncoveredVTs.map((vt) => vt.file).join(", ")}`);
         }
     }
-    // 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 openspecReadPaths = await checkOpenspecReadEvidence({
         runDir: input.runDir,
@@ -510,82 +224,36 @@ export async function runFrontendPrewriteGate(input) {
         reviewNodeId,
         repoRoot: workspaceRoot ?? process.cwd(),
     });
-    if (candidatePaths.length > 0) {
-        const readSet = new Set(openspecReadPaths);
-        const unread = candidatePaths.filter((candidate) => !readSet.has(candidate));
-        if (unread.length > 0) {
-            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.`,
-                failureCode: "openspec-not-read",
-                openspecReadPaths,
-                openspecCandidatePaths: candidatePaths,
-            });
-        }
-    }
-    // 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,
-    });
-    const classification = analysis.normalizationActions.length > 0 ? "accepted-normalized" : "accepted";
-    return finalizePrewrite(input, {
-        ...basePending,
+    // OpenSpec is advisory design evidence, not an authorization boundary.
+    // Model read behavior is nondeterministic, and a missed read must not block
+    // a contract/schema/write-set-authorized implementation. Preserve any
+    // successful evidence for review context, while allowing unavailable
+    // evidence to be reported downstream.
+    return {
+        ok: true,
+        planNodeId,
+        reviewNodeId,
         verdict,
-        classification,
-        failureReason: null,
-        candidateJsonSha256: analysis.candidateJsonSha256,
-        canonicalSha256: artifact.sha256,
-        normalizationActions: analysis.normalizationActions,
-        mockStrategy,
+        mockStrategy: contract.mockApi.strategy,
         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}`);
-    if (result.failureReason)
-        lines.push(`Failure reason: ${result.failureReason}`);
+    const lines = [
+        "Frontend prewrite gate: pass",
+        `Plan: ${result.planNodeId}`,
+        `Review: ${result.reviewNodeId}`,
+        `Mock strategy: ${result.mockStrategy}`,
+        `Structured artifact: ${result.artifact.path}`,
+        `Schema: ${result.artifact.schemaId}`,
+        `SHA-256: ${result.artifact.sha256}`,
+    ];
     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 {
+    else if (result.openspecCandidatePaths.length === 0) {
         lines.push("openspec: unavailable");
     }
     return lines.join("\n");