@tea-agent/loop-agent 0.38.1 → 0.39.0-beta.0

package/dist/workflows/dag/convergence/controller.js

@@ -21,6 +21,17 @@ const REVIEW_VERDICT_NODE_ID = "review-verdict-recovery-pi";
 const INITIAL_REVIEW_NODE_ID = "initial-review-pi";
 const INITIAL_REVIEW_GATE_NODE_ID = "initial-review-gate-shell";
 const INITIAL_REVIEW_PASS_NODE_ID = "initial-review-pass-shell";
+/**
+ * Standard-dag governance verify chain ids. When the convergence chain
+ * observes the governance standard gate, a legitimate verify-pi
+ * `request-revision` re-enters a bounded implement-repair loop instead of
+ * terminating the run at the gate, mirroring the review-chain re-entry
+ * semantics (AC3/AC4). Protocol/provider/safety failures on verify-pi keep
+ * failing closed; only a safe `request-revision` drives code repair here.
+ */
+const GOVERNANCE_VERIFY_GATE_NODE_ID = "governance-standard-gate-shell";
+const GOVERNANCE_VERIFY_NODE_ID = "verify-pi";
+const GOVERNANCE_VERIFY_WRITER_NODE_ID = "implement-pi";
 // Automatic code repair is authorized only for an ordinary command/test
 // failure. Unknown, protocol, validation, provider, safety, governance, and
 // human-decision categories all fail closed instead of reaching a writer.
@@ -57,6 +68,15 @@ export async function runConvergencePassController(input) {
     }
     const chain = getConvergenceChain(input.spec);
     const observesReview = chain.includes(REVIEW_GATE_NODE_ID);
+    const observesGovernanceVerify = chain.includes(GOVERNANCE_VERIFY_GATE_NODE_ID);
+    // Standard-dag governance verify convergence: verify-pi drives a bounded
+    // implement-repair loop on `request-revision`. This shape has no
+    // hard-verify/review nodes; dispatch before the legacy hard-verify logic so
+    // the standard governance DAG never falls into `unsupported-dag-shape`/
+    // `non-retry-failure` dead ends.
+    if (observesGovernanceVerify && !observesReview) {
+        return handleGovernanceVerifyConvergence(input);
+    }
     if (input.tasksById.has(INITIAL_REVIEW_NODE_ID)) {
         const initialReview = input.state.nodes[INITIAL_REVIEW_NODE_ID];
         const initialGate = input.state.nodes[INITIAL_REVIEW_GATE_NODE_ID];
@@ -397,6 +417,127 @@ async function handleReviewRequestRevision(input, reviewGate) {
 function getConvergenceChain(spec) {
     return spec.convergence?.chainNodeIds ?? DEFAULT_CONVERGENCE_CHAIN_NODE_IDS;
 }
+/**
+ * Legitimate governance verify revision: verify-pi finished and emitted
+ * `request-revision`. No secondary verdict-recovery node exists on the
+ * standard dag, so the single verify-pi verdict plus a non-transport failure
+ * category is the legitimacy bar (protocol-invalid/invalid-output/timeout on
+ * verify-pi fail closed instead of driving repair).
+ */
+function isLegitimateGovernanceVerifyRevision(state) {
+    const verifyNode = state.nodes[GOVERNANCE_VERIFY_NODE_ID];
+    return (verifyNode?.status === "FINISHED" &&
+        parseProcessVerdict(verifyNode) === "request-revision");
+}
+function isLegitimateGovernanceVerifyPass(state) {
+    const verifyNode = state.nodes[GOVERNANCE_VERIFY_NODE_ID];
+    return (verifyNode?.status === "FINISHED" &&
+        parseProcessVerdict(verifyNode) === "pass");
+}
+/**
+ * Standard-dag governance verify convergence loop. Terminal pass when
+ * verify-pi passes; bounded re-entry (reset implement-pi + verify chain) when
+ * verify-pi legitimately requests revision. The reset lets the next
+ * implement-pi pass consume the prior verify findings through the structured
+ * convergence feedback block (node-execution injects it for implementer
+ * roles), so `already-satisfied` no-ops are explicitly contradicted by the
+ * preserved verify-pi evidence refs.
+ */
+async function handleGovernanceVerifyConvergence(input) {
+    const convergence = input.state.convergence;
+    const currentPass = convergence.currentPass || 1;
+    const verifyNode = input.state.nodes[GOVERNANCE_VERIFY_NODE_ID];
+    const verifyShell = input.state.nodes["verify-shell"];
+    // Hard verify commands failed: not a governance verdict issue. Without a
+    // supervised repair chain, this stays terminal so the failure-aware
+    // closeout reports it truthfully.
+    if (verifyShell?.status === "ERROR") {
+        const passRecord = await buildConvergencePassRecord({
+            pass: currentPass,
+            status: "terminal",
+            reason: "hard-verify-failed",
+            state: input.state,
+            runDir: input.runDir,
+            spec: input.spec,
+        });
+        convergence.passHistory.push(passRecord);
+        convergence.terminalReason = "hard-verify-failed";
+        await input.persistState();
+        return { retry: false };
+    }
+    if (isLegitimateGovernanceVerifyPass(input.state)) {
+        convergence.terminalReason = "hard-verify-pass";
+        await appendConvergenceKnowledgePattern({
+            cwd: input.cwd,
+            state: input.state,
+        });
+        return { retry: false };
+    }
+    const verifyFailureCategory = verifyNode?.failureCategory;
+    const legitimateRevision = isLegitimateGovernanceVerifyRevision(input.state);
+    if (!legitimateRevision ||
+        (verifyFailureCategory &&
+            REVIEW_SOURCE_NON_RETRY_FAILURES.has(verifyFailureCategory))) {
+        const passRecord = await buildConvergencePassRecord({
+            pass: currentPass,
+            status: "terminal",
+            reason: "non-retry-failure",
+            state: input.state,
+            runDir: input.runDir,
+            spec: input.spec,
+        });
+        convergence.passHistory.push(passRecord);
+        convergence.terminalReason = "non-retry-failure";
+        await input.persistState();
+        return { retry: false };
+    }
+    const passRecord = await buildConvergencePassRecord({
+        pass: currentPass,
+        status: "retrying",
+        reason: "verify-request-revision",
+        state: input.state,
+        runDir: input.runDir,
+        spec: input.spec,
+    });
+    if (currentPass >= convergence.maxPasses) {
+        passRecord.status = "terminal";
+        passRecord.reason = "max-passes";
+        convergence.passHistory.push(passRecord);
+        convergence.terminalReason = "max-passes";
+        await input.persistState();
+        return { retry: false };
+    }
+    convergence.passHistory.push(passRecord);
+    convergence.currentPass = currentPass + 1;
+    // Reset the writer plus the governance verify chain: the next implement-pi
+    // pass must consume the preserved verify-pi findings (injected as
+    // convergence feedback) instead of returning already-satisfied.
+    for (const id of collectGovernanceVerifyResetIds(input.spec)) {
+        const task = input.tasksById.get(id);
+        if (!task)
+            continue;
+        input.state.nodes[id] = freshNodeRecord(task);
+    }
+    await input.persistState();
+    return { retry: true };
+}
+/**
+ * Reset set for the governance verify loop: the exclusive writer and the
+ * verify chain closure (verify-shell, verify-pi, governance gate, and every
+ * transitive descendant so closeout re-adjudicates from fresh evidence).
+ */
+function collectGovernanceVerifyResetIds(spec) {
+    const resetIds = new Set([
+        GOVERNANCE_VERIFY_WRITER_NODE_ID,
+        "verify-shell",
+        GOVERNANCE_VERIFY_NODE_ID,
+        GOVERNANCE_VERIFY_GATE_NODE_ID,
+    ]);
+    for (const id of collectTransitiveDescendantTaskIds(spec, GOVERNANCE_VERIFY_GATE_NODE_ID)) {
+        resetIds.add(id);
+    }
+    return resetIds;
+}
 function hasConvergenceChain(tasksById, spec) {
     const chain = getConvergenceChain(spec);
     return chain.every((id) => tasksById.has(id));

package/dist/workflows/dag/dynamic-runtime/map.js

@@ -367,19 +367,26 @@ export async function executeDynamicMapExpansion(input) {
         }
     }
     const budgetBlockedIds = new Set(blockedChildren.map((entry) => entry.nodeId));
+    const failOnTokenBudgetExhaustion = input.expansion.failOnTokenBudgetExhaustion === true;
     const failedChildren = tolerateChildFailures
         ? []
         : childNodeIds.filter((nodeId) => {
             const record = input.state.nodes[nodeId];
             if (!record || record.status === "FINISHED")
                 return false;
-            if (budgetBlockedIds.has(nodeId) || isBudgetBlockedRecord(record))
-                return false;
+            if (budgetBlockedIds.has(nodeId) || isBudgetBlockedRecord(record)) {
+                return failOnTokenBudgetExhaustion;
+            }
             return true;
         });
+    const finishedItemCount = childNodeIds.filter((nodeId) => input.state.nodes[nodeId]?.status === "FINISHED").length;
+    const blockedItemCount = budgetBlockedIds.size;
     const aggregate = {
         workflowNodeId: input.expansion.workflowNodeId,
         itemCount: items.length,
+        expectedItemCount: items.length,
+        finishedItemCount,
+        blockedItemCount,
         children: childNodeIds.map((nodeId, index) => ({
             nodeId,
             item: items[index],
@@ -399,21 +406,30 @@ export async function executeDynamicMapExpansion(input) {
                 ?.reason,
         })),
         tokensUsed: totalTokensUsed,
+        maxTotalTokens: tokenBudget?.maxTotalTokens,
         caseOutcomeNotes: caseOutcomeNotes.length > 0 ? caseOutcomeNotes : undefined,
     };
+    const tokenBudgetFailure = failOnTokenBudgetExhaustion && blockedItemCount > 0;
     return {
-        // With tolerateChildFailures: barrier always succeeds; product outcomes live in
-        // case evidence + result materialization. Without it: real child failures fail-close.
-        ok: failedChildren.length === 0,
+        // With tolerateChildFailures: barrier succeeds and product outcomes live in
+        // case evidence. Backend-test opts into token-budget fail-closed because a
+        // partial generated module set is never a valid downstream input.
+        ok: failedChildren.length === 0 && !tokenBudgetFailure,
         stdout: JSON.stringify(aggregate),
         stderr: caseOutcomeNotes.length > 0
             ? `map children recorded as case outcomes: ${caseOutcomeNotes
                 .map((entry) => `${entry.nodeId}=${entry.status}:${entry.reason}`)
                 .join(", ")}`
+            : tokenBudgetFailure
+                ? `dynamic map token budget exhausted: expected=${items.length} finished=${finishedItemCount} blocked=${blockedItemCount} tokensUsed=${totalTokensUsed} maxTotalTokens=${tokenBudget?.maxTotalTokens ?? "unbounded"}`
+                : failedChildren.length > 0
+                    ? `dynamic map children failed: ${failedChildren.join(", ")}`
+                    : "",
+        failureCategory: tokenBudgetFailure
+            ? "dynamic-expansion-token-budget-exhausted"
             : failedChildren.length > 0
-                ? `dynamic map children failed: ${failedChildren.join(", ")}`
-                : "",
-        failureCategory: failedChildren.length > 0 ? "dynamic-expansion-child-failed" : "success",
+                ? "dynamic-expansion-child-failed"
+                : "success",
         durationMs: Date.now() - started,
     };
 }

package/dist/workflows/dag/dynamic-runtime/shared.js

@@ -30,7 +30,7 @@ export function getNodeOutputAsJson(state, nodeId) {
 /** Normalize a line the same way verdict gates do (strip whole-line Markdown emphasis). */
 export function normalizeVerdictCandidateLine(value) {
     const trimmed = String(value).trim();
-    const emphasized = trimmed.match(/^\*{1,3}\s*(VERDICT:[^*]+?)\s*\*{1,3}$/);
+    const emphasized = trimmed.match(/^(?:`{1,3}|\*{1,3})\s*(VERDICT:[^`*]+?)\s*(?:`{1,3}|\*{1,3})$/);
     const line = (emphasized ? emphasized[1] : trimmed).trim();
     // Canonicalize the colon separator and trailing sentence punctuation so
     // "VERDICT:pass", "VERDICT:  pass", or "VERDICT: pass." match the declared

package/dist/workflows/dag/frontend-implementation-contract.js

@@ -13,6 +13,7 @@ export const frontendNormalizationActionSchema = z.enum([
     "strip-comments",
     "canonicalize-requirement-ids",
     "canonicalize-verification-alias",
+    "drop-unresolved-verification-symbols",
     "inject-source-binding",
 ]);
 export function sha256Hex(input) {
@@ -40,6 +41,9 @@ export function serializeDeterministicJson(value) {
 export function deterministicSha256(value) {
     return sha256Hex(serializeDeterministicJson(value));
 }
+/** Provider-safe limits for the two planner outputs. Larger work must split. */
+export const FRONTEND_PLAN_RESPONSE_MAX_BYTES = 14 * 1024;
+export const FRONTEND_CANONICAL_CONTRACT_MAX_BYTES = 16 * 1024;
 /** A contract materialization failure carries its classification plus the
  * audit context collected up to the failure point, so the prewrite gate can
  * persist a complete frontend-prewrite-result-v1 even when the canonical
@@ -102,6 +106,21 @@ async function deriveFrozenCommandLabelsFromRun(runDir) {
     return [...labels];
 }
 export const FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID = "frontend-implementation-contract-v1";
+export const FRONTEND_IMPLEMENTATION_CONTRACT_PLAN_PATCH_SCHEMA_ID = "frontend-implementation-contract-plan-patch-v1";
+/**
+ * Build the deterministic, run-owned portion of the frontend contract. The
+ * planner is allowed to fill semantic fields with an RFC 7386 merge patch but
+ * cannot redefine task identity, risk, or the implementation write boundary.
+ */
+export function buildFrontendImplementationContractSkeleton(input) {
+    return {
+        schemaVersion: 1,
+        sourceBinding: canonicalFrontendContractSourceBinding(input.sourceBinding),
+        riskLevel: input.riskLevel,
+        targets: { files: [...input.targetFiles] },
+        mockApi: { productionDefaultOff: true },
+    };
+}
 /**
  * Load the canonical frontend-implementation-contract-v1 JSON Schema from the
  * installed loop-agent package docs/templates/ path. Package-root discovery
@@ -499,9 +518,9 @@ function isPlainObject(value) {
  * ever materialized, so a patch that removes a required field still fails
  * closed at the gate.
  */
-export function applyFrontendImplementationContractPatch(target, patch) {
+export function applyFrontendContractMergePatch(target, patch) {
     if (!isPlainObject(patch)) {
-        throw new Error("frontend revision patch must be a JSON object");
+        throw new Error("frontend contract patch must be a JSON object");
     }
     const merge = (base, delta) => {
         if (delta === null)
@@ -526,6 +545,9 @@ export function applyFrontendImplementationContractPatch(target, patch) {
     };
     return merge(target, patch);
 }
+export function applyFrontendImplementationContractPatch(target, patch) {
+    return applyFrontendContractMergePatch(target, patch);
+}
 export async function assertFrontendSourceBindingFresh(input) {
     for (const source of input.binding.sources) {
         const absolute = resolveDagTaskSourcePath({
@@ -1608,6 +1630,256 @@ export async function writeFrontendImplementationContractArtifact(input) {
         schemaId: FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID,
     };
 }
+const FRONTEND_PLAN_PATCH_PROTECTED_PATHS = [
+    "/schemaVersion",
+    "/sourceBinding",
+    "/riskLevel",
+    "/targets/files",
+    "/mockApi/productionDefaultOff",
+];
+function frontendPlanPatchProtectedPathViolations(patch) {
+    const record = asRecord(patch);
+    if (!record)
+        return ["/"];
+    const violations = [];
+    for (const key of ["schemaVersion", "sourceBinding", "riskLevel"]) {
+        if (Object.hasOwn(record, key))
+            violations.push(`/${key}`);
+    }
+    const targets = asRecord(record.targets);
+    if (targets && Object.hasOwn(targets, "files"))
+        violations.push("/targets/files");
+    const mockApi = asRecord(record.mockApi);
+    if (mockApi && Object.hasOwn(mockApi, "productionDefaultOff"))
+        violations.push("/mockApi/productionDefaultOff");
+    return violations;
+}
+function workspaceRootFromDagRunDir(runDir) {
+    const absolute = path.resolve(runDir);
+    const segments = absolute.split(path.sep);
+    const harnessIndex = segments.lastIndexOf(".harness");
+    if (harnessIndex < 0 ||
+        segments[harnessIndex + 1] !== "dag-runs" ||
+        harnessIndex + 3 >= segments.length) {
+        return null;
+    }
+    const joined = segments.slice(0, harnessIndex).join(path.sep);
+    return joined || path.parse(absolute).root;
+}
+function verificationSymbolMatchesFile(symbol, content) {
+    if (symbol.trim().toLowerCase() === "all describe blocks")
+        return content.includes("describe(");
+    const symbols = symbol.includes(" / ")
+        ? symbol
+            .split(/[（(]/, 1)[0]
+            .split("/")
+            .map((item) => item.trim())
+            .filter(Boolean)
+        : [symbol];
+    return symbols.every((item) => {
+        const describeTitle = item.match(/^describe\((?:['"])(.+?)(?:['"])/i)?.[1];
+        return [item, describeTitle, describeTitle ? "describe(" : undefined]
+            .filter((candidate) => Boolean(candidate))
+            .some((candidate) => content.includes(candidate));
+    });
+}
+async function dropUnresolvedVerificationSymbols(input) {
+    const workspaceRoot = workspaceRootFromDagRunDir(input.runDir);
+    const targets = asRecord(input.contract)?.verificationTargets;
+    if (!workspaceRoot || !Array.isArray(targets))
+        return false;
+    let changed = false;
+    for (const targetValue of targets) {
+        const target = asRecord(targetValue);
+        const file = asString(target?.file);
+        const symbol = asString(target?.symbol);
+        if (!target || !file || !symbol)
+            continue;
+        const absolute = path.resolve(workspaceRoot, file);
+        const relative = path.relative(workspaceRoot, absolute);
+        if (relative.startsWith("..") ||
+            path.isAbsolute(relative) ||
+            relative.includes("..")) {
+            continue;
+        }
+        let content;
+        try {
+            content = await readFile(absolute, "utf8");
+        }
+        catch {
+            // Missing files remain a trace-time hard failure; do not hide them by
+            // changing the optional symbol during candidate normalization.
+            continue;
+        }
+        if (verificationSymbolMatchesFile(symbol, content))
+            continue;
+        delete target.symbol;
+        changed = true;
+    }
+    return changed;
+}
+function extractSingleOpenspecCitationsBlock(text) {
+    const blocks = text.match(/```openspec-citations[ \t]*\r?\n[\s\S]*?\r?\n```/g) ?? [];
+    if (blocks.length !== 1) {
+        throw new Error(`frontend plan patch output must include exactly one fenced openspec-citations block (found ${blocks.length})`);
+    }
+    return blocks[0];
+}
+/**
+ * Frontend plan/revision output has two JSON-bearing regions: the primary
+ * payload and line-oriented OpenSpec citations. Keep their parsing domains
+ * separate so a citation row can never become a competing contract candidate.
+ * A bare JSON payload is retained only for historical node-output compatibility.
+ */
+export function extractFrontendPlanPayload(text) {
+    const citationsBlock = extractSingleOpenspecCitationsBlock(text);
+    return {
+        payload: extractFrontendPlanPrimaryPayload(text.replace(citationsBlock, "")),
+        citationsBlock,
+    };
+}
+function extractFrontendPlanPrimaryPayload(text) {
+    const fences = [...text.matchAll(/```json[ \t]*\r?\n([\s\S]*?)\r?\n```/gi)];
+    if (fences.length > 1) {
+        throw new Error(`frontend plan output must contain exactly one primary fenced json payload (found ${fences.length})`);
+    }
+    if (fences.length === 1) {
+        try {
+            return JSON.parse(fences[0][1]);
+        }
+        catch (error) {
+            throw new Error(`frontend plan primary json fence is invalid: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return extractFrontendImplementationJson(text);
+}
+async function writeFrontendPlanCandidateRaw(input) {
+    const relativePath = path.posix.join("contracts", "candidates", input.nodeId, `attempt-${input.attempt}.raw.md`);
+    await writeTextArtifactFile(path.join(input.runDir, relativePath), input.text);
+    return relativePath;
+}
+/**
+ * Compile the planner's editable RFC 7386 patch against the deterministic
+ * runtime skeleton. Every attempt is preserved under contracts/candidates so
+ * format/schema failures can be inspected and replayed without trusting model
+ * prose. A successful result returns canonical full-contract text for all
+ * downstream review and prewrite nodes.
+ */
+export async function validateFrontendPlanPatchNodeOutput(input) {
+    const nodeId = input.nodeId ?? "frontend-plan-pi";
+    const attempt = input.attempt ?? 1;
+    const candidateDir = path.posix.join("contracts", "candidates", nodeId);
+    const rawPath = await writeFrontendPlanCandidateRaw({
+        runDir: input.runDir,
+        nodeId,
+        attempt,
+        text: input.text,
+    });
+    const reportBase = {
+        schemaVersion: 1,
+        schemaId: FRONTEND_IMPLEMENTATION_CONTRACT_PLAN_PATCH_SCHEMA_ID,
+        nodeId,
+        attempt,
+        rawPath,
+        protectedPaths: [...FRONTEND_PLAN_PATCH_PROTECTED_PATHS],
+        candidateRawSha256: sha256Hex(input.text),
+    };
+    let extractedPatchPath;
+    let extractedPatchSha256;
+    const writeReport = async (value) => {
+        await writeDeterministicJsonArtifact(input.runDir, path.posix.join(candidateDir, `attempt-${attempt}.validation.json`), {
+            ...reportBase,
+            ...(extractedPatchPath
+                ? { extractedPatchPath, extractedPatchSha256 }
+                : {}),
+            ...value,
+        });
+    };
+    try {
+        if (Buffer.byteLength(input.text, "utf8") > FRONTEND_PLAN_RESPONSE_MAX_BYTES) {
+            throw new Error(`frontend plan response exceeds the ${FRONTEND_PLAN_RESPONSE_MAX_BYTES}-byte limit`);
+        }
+        if (!input.sourceBinding)
+            throw new Error("frontend plan patch validator requires DAG sourceBinding");
+        const skeleton = input.structuredContractOutput?.skeleton;
+        if (!skeleton)
+            throw new Error("frontend plan patch validator requires a deterministic runtime skeleton");
+        const patch = extractFrontendPlanPrimaryPayload(input.text);
+        if (!isPlainObject(patch))
+            throw new Error("frontend plan patch must extract to one JSON object");
+        extractedPatchPath = path.posix.join(candidateDir, `attempt-${attempt}.extracted.json`);
+        const extractedArtifact = await writeDeterministicJsonArtifact(input.runDir, extractedPatchPath, patch);
+        extractedPatchSha256 = extractedArtifact.sha256;
+        const citationsBlock = extractSingleOpenspecCitationsBlock(input.text);
+        const citationsArtifactPath = path.posix.join(candidateDir, `attempt-${attempt}.openspec-citations.md`);
+        await writeTextArtifactFile(path.join(input.runDir, citationsArtifactPath), `${citationsBlock}\n`);
+        const protectedViolations = frontendPlanPatchProtectedPathViolations(patch);
+        if (protectedViolations.length > 0)
+            throw new Error(`frontend plan patch must not modify runtime-protected paths: ${protectedViolations.join(", ")}`);
+        const merged = applyFrontendContractMergePatch(skeleton, patch);
+        const droppedUnresolvedSymbols = await dropUnresolvedVerificationSymbols({
+            runDir: input.runDir,
+            contract: merged,
+        });
+        const analysis = await analyzeFrontendImplementationContract({
+            runDir: input.runDir,
+            rawContractText: serializeDeterministicJson(merged),
+            sourceBinding: input.sourceBinding,
+        });
+        if (Buffer.byteLength(serializeDeterministicJson(analysis.canonical), "utf8") >
+            FRONTEND_CANONICAL_CONTRACT_MAX_BYTES) {
+            throw new Error(`frontend canonical contract exceeds the ${FRONTEND_CANONICAL_CONTRACT_MAX_BYTES}-byte limit; split the task`);
+        }
+        const normalizedArtifact = await writeDeterministicJsonArtifact(input.runDir, path.posix.join(candidateDir, `attempt-${attempt}.normalized.json`), analysis.canonical);
+        await writeReport({
+            classification: "accepted-normalized",
+            normalizedContractPath: path.posix.relative(input.runDir.replaceAll(path.sep, "/"), normalizedArtifact.path.replaceAll(path.sep, "/")),
+            normalizedContractSha256: normalizedArtifact.sha256,
+            normalizationActions: [
+                "apply-runtime-skeleton",
+                ...(droppedUnresolvedSymbols
+                    ? ["drop-unresolved-verification-symbols"]
+                    : []),
+                ...analysis.normalizationActions,
+            ],
+            errors: [],
+        });
+        return {
+            ok: true,
+            contract: analysis.canonical,
+            structuredArtifact: {
+                path: normalizedArtifact.path,
+                sha256: normalizedArtifact.sha256,
+                schemaId: FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID,
+            },
+            frontendPlanOutput: {
+                schemaVersion: 1,
+                payloadKind: "canonical-contract",
+                citationsArtifactPath: path.join(input.runDir, citationsArtifactPath),
+                citationsArtifactSha256: sha256Hex(`${citationsBlock}\n`),
+                rawCandidatePath: path.join(input.runDir, rawPath),
+                rawCandidateSha256: sha256Hex(input.text),
+            },
+            normalizedText: [
+                "Frontend implementation contract compiled from the runtime skeleton.",
+                "",
+                "```json",
+                serializeDeterministicJson(analysis.canonical),
+                "```",
+                citationsBlock,
+            ].join("\n"),
+        };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        await writeReport({
+            classification: "retryable-invalid",
+            normalizationActions: [],
+            errors: [{ path: "$", code: "invalid-output", message: reason }],
+        });
+        return { ok: false, reason };
+    }
+}
 /**
  * Node-output self-check for plan nodes that produce the implementation
  * contract. Mirrors the prewrite gate validation so schema/typo/null violations
@@ -1635,7 +1907,7 @@ export async function validateFrontendContractNodeOutput(input) {
 /**
  * Node-output self-check for the plan revision node, which emits an RFC 7386
  * merge-patch delta against the original contract instead of a full contract.
- * Deliberately loose and format-level: the output must contain at least one
+ * Deliberately loose and format-level: the output must contain exactly one
  * ```openspec-citations fenced block and must extract (after the citations
  * blocks are stripped) to exactly one JSON object. The delta carries no
  * schemaVersion/targets, so no full-contract schema/semantic checks run here;
@@ -1643,25 +1915,32 @@ export async function validateFrontendContractNodeOutput(input) {
  * the prewrite gate, which remains the only authority.
  */
 export async function validateFrontendRevisionPatchNodeOutput(input) {
-    // Mirror the prewrite gate's block-presence semantics (a fenced
-    // ```openspec-citations block with a newline-terminated body).
-    if (!/```openspec-citations[ \t]*\r?\n[\s\S]*?\r?\n```/.test(input.text)) {
+    const nodeId = input.nodeId ?? "frontend-plan-revision-pi";
+    const attempt = input.attempt ?? 1;
+    const candidateDir = path.posix.join("contracts", "candidates", nodeId);
+    const rawPath = await writeFrontendPlanCandidateRaw({
+        runDir: input.runDir,
+        nodeId,
+        attempt,
+        text: input.text,
+    });
+    if (Buffer.byteLength(input.text, "utf8") > FRONTEND_PLAN_RESPONSE_MAX_BYTES) {
         return {
             ok: false,
-            reason: "revision patch output must include at least one ```openspec-citations fenced block",
+            reason: `frontend revision response exceeds the ${FRONTEND_PLAN_RESPONSE_MAX_BYTES}-byte limit`,
         };
     }
-    // Strip the citation blocks before extraction: their per-row JSON objects
-    // would otherwise count as competing balanced objects in the extractor.
-    const textWithoutCitations = input.text.replace(/```openspec-citations[ \t]*\r?\n[\s\S]*?\r?\n```/g, "");
+    let citationsBlock;
     let patch;
     try {
-        patch = extractFrontendImplementationJson(textWithoutCitations);
+        const parsed = extractFrontendPlanPayload(input.text);
+        citationsBlock = parsed.citationsBlock;
+        patch = parsed.payload;
     }
     catch (error) {
         return {
             ok: false,
-            reason: `revision patch output must contain exactly one valid JSON object: ${error instanceof Error ? error.message : String(error)}`,
+            reason: error instanceof Error ? error.message : String(error),
         };
     }
     if (!patch || typeof patch !== "object" || Array.isArray(patch)) {
@@ -1670,7 +1949,34 @@ export async function validateFrontendRevisionPatchNodeOutput(input) {
             reason: "revision patch output must extract to exactly one JSON object (RFC 7386 merge-patch delta)",
         };
     }
-    return { ok: true, contract: patch };
+    const protectedViolations = frontendPlanPatchProtectedPathViolations(patch);
+    if (protectedViolations.length > 0) {
+        return {
+            ok: false,
+            reason: `frontend revision patch must not modify runtime-protected paths: ${protectedViolations.join(", ")}`,
+        };
+    }
+    const payloadPath = path.posix.join(candidateDir, `attempt-${attempt}.patch.json`);
+    const payloadArtifact = await writeDeterministicJsonArtifact(input.runDir, payloadPath, patch);
+    const citationsArtifactPath = path.posix.join(candidateDir, `attempt-${attempt}.openspec-citations.md`);
+    await writeTextArtifactFile(path.join(input.runDir, citationsArtifactPath), `${citationsBlock}\n`);
+    return {
+        ok: true,
+        contract: patch,
+        structuredArtifact: {
+            path: payloadArtifact.path,
+            sha256: payloadArtifact.sha256,
+            schemaId: "frontend-implementation-contract-revision-patch-v1",
+        },
+        frontendPlanOutput: {
+            schemaVersion: 1,
+            payloadKind: "merge-patch",
+            citationsArtifactPath: path.join(input.runDir, citationsArtifactPath),
+            citationsArtifactSha256: sha256Hex(`${citationsBlock}\n`),
+            rawCandidatePath: path.join(input.runDir, rawPath),
+            rawCandidateSha256: sha256Hex(input.text),
+        },
+    };
 }
 export async function materializeFrontendImplementationContract(input) {
     const analysis = await analyzeFrontendImplementationContract(input);