@tea-agent/loop-agent 0.39.0-next.4 → 0.39.0-next.5

package/CHANGELOG.md

@@ -4,6 +4,12 @@
 
 ### 新增
 
+- 前端 plan 唯一机器契约化（JSON-only）：`frontend-plan-pi` / `frontend-plan-revision-pi` 输出收敛为「一行导语 + 唯一 fenced `json` 契约 + 唯一 `openspec-citations` 引用块」，彻底移除「可选 Markdown 说明」；plan.md（`contracts/frontend-plan.md`）改由 prewrite gate 用纯函数 `renderFrontendPlanMarkdown` 确定性渲染（不新增 DAG 节点/不新增 Pi 调用）
+- 契约 schema 新增 5 个可选字段（`implementationSteps` / `stylingStrategy` / `dependencyPolicy` / `residualRisks` / `realIntegrationGap`），`schemaVersion` 保持 1；`docs/templates/frontend-implementation-contract.schema.json` 同步
+- revision 输出改为 RFC 7386 merge-patch delta + 引用块：gate 配置新增 `revisionPatch`，生效时在 `planFallbackFromNodeIds[0]` 原始契约上应用 `applyFrontendImplementationContractPatch` 后进入既有分析/规范化/物化管线；旧 DAG 缺字段按整契约处理
+- canonical contract 序列化（UTF-8）超过 64KB → `retryable-invalid` + 新增 `contract-too-large` failureCode（体积守卫兜底）
+- `design-review` / `final-design-review` 提示改为消费契约 JSON（注入契约字段摘要），不再要求读取 plan prose
+
 - `frontend-prewrite-gate` 的 OpenSpec 读取校验支持 `task.json.frontendOpenspec` 配置：`policy` 缺省 `cited`（候选 = `requiredReadPaths` ∪ 任务源显式引用的 openspec 路径），`scan-strict` 保留止血任务后的全量必读语义；`requiredReadPaths` 中非 openspec 支持路径在生成期确定性失败
 - 确定性引用块协议：生效 plan 输出在 fenced `json` 契约块后追加 `openspec-citations` fenced 块（每行一个 JSON `{"path","section","line"}`）；gate 解析并与生效 plan/review 节点的成功 read 事件核验，新增 `openspec-citation-block-unparseable` / `openspec-not-cited` / `openspec-citation-not-read` 三个 retryable-invalid failureCode（防捏造、防遗漏）
 - `src/shared/openspec-spec.ts` 新增 `extractTaskSourceOpenspecPaths` 纯函数（反引号内联、markdown 链接目标、裸路径 token → 归一化 → spec 过滤 → 治理子树排除 → 去重排序）
@@ -11,6 +17,7 @@
 
 ### 文档
 
+- 新增 `docs/decisions/0015-frontend-plan-json-only-contract.md`，并同步 `docs/runtime/frontend-implementation-workflow.md`、`docs/templates/frontend-implementation-contract.schema.json`、`skills/frontend-implementation/references/node-contracts.md`
 - 新增 `docs/decisions/0014-openspec-gate-claim-verification.md`，并同步 `docs/runtime/frontend-implementation-workflow.md`、`docs/templates/frontend-task-constraints.md`、`docs/templates/frontend-design-contract.md`、`skills/frontend-implementation/references/node-contracts.md`
 
 ## [0.36.4-beta.0] - 2026-08-16

package/dist/build-stamp.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
   "version": "0.37.0",
-  "gitSha": "2151d87d0e2ad4aaab0dd6a894945df8cf59d940",
-  "builtAt": "2026-08-17T11:03:51.721Z"
+  "gitSha": "5c445d9697e1ff1974fbea8999634ecc668fecc9",
+  "builtAt": "2026-08-17T11:38:52.355Z"
 }

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

@@ -316,6 +316,11 @@ export const frontendImplementationContractSchema = z
     })
         .strict()).min(1),
     evidenceGaps: z.array(gap),
+    implementationSteps: z.array(z.string().min(1)).optional(),
+    stylingStrategy: z.string().min(1).optional(),
+    dependencyPolicy: z.string().min(1).optional(),
+    residualRisks: z.array(z.string().min(1)).optional(),
+    realIntegrationGap: z.string().min(1).optional(),
 })
     .strict()
     .superRefine((value, ctx) => {
@@ -426,6 +431,44 @@ export const frontendImplementationContractSchema = z
         });
     }
 }));
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Apply an RFC 7386 merge-patch on a target contract without mutating it.
+ * `null` removes the key; plain objects merge recursively when the target value
+ * is also a plain object; arrays and scalars replace the whole value. The
+ * result is re-validated by analyzeFrontendImplementationContract before it is
+ * ever materialized, so a patch that removes a required field still fails
+ * closed at the gate.
+ */
+export function applyFrontendImplementationContractPatch(target, patch) {
+    if (!isPlainObject(patch)) {
+        throw new Error("frontend revision patch must be a JSON object");
+    }
+    const merge = (base, delta) => {
+        if (delta === null)
+            return undefined;
+        if (!isPlainObject(delta))
+            return delta;
+        const result = isPlainObject(base)
+            ? { ...base }
+            : {};
+        for (const [key, value] of Object.entries(delta)) {
+            if (value === null) {
+                delete result[key];
+            }
+            else if (isPlainObject(value) && isPlainObject(result[key])) {
+                result[key] = merge(result[key], value);
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        return result;
+    };
+    return merge(target, patch);
+}
 export async function assertFrontendSourceBindingFresh(input) {
     for (const source of input.binding.sources) {
         const absolute = resolveDagTaskSourcePath({
@@ -1331,6 +1374,11 @@ export function coerceFrontendImplementationContractInput(value, canonicalBindin
         },
         verificationTargets,
         evidenceGaps,
+        implementationSteps: asStringArray(record.implementationSteps),
+        stylingStrategy: asString(record.stylingStrategy) || undefined,
+        dependencyPolicy: asString(record.dependencyPolicy) || undefined,
+        residualRisks: asStringArray(record.residualRisks),
+        realIntegrationGap: asString(record.realIntegrationGap) || undefined,
     };
 }
 /**

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

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

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

@@ -2,12 +2,16 @@ import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
 import { isOpenspecSpecFilePath } from "../../shared/openspec-spec.js";
+import { 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";
 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 +35,7 @@ export const frontendPrewriteFailureCodeSchema = z.enum([
     "openspec-citation-block-unparseable",
     "openspec-not-cited",
     "openspec-citation-not-read",
+    "contract-too-large",
 ]);
 export const frontendPrewriteResultV1Schema = z
     .object({
@@ -442,7 +447,60 @@ export async function runFrontendPrewriteGate(input) {
             failureCode: "verdict-not-pass",
         });
     }
-    const missingIds = input.config.requiredRequirementIds.filter((id) => !planText.includes(id));
+    // revisionPatch mode: the effective plan node emits an RFC 7386 merge-patch
+    // delta against the original contract node (planFallbackFromNodeIds[0]).
+    // Legacy DAGs without revisionPatch (undefined) keep full-contract semantics.
+    const revisionPatchMode = input.config.revisionPatch === true &&
+        planNodeId === input.config.planFromNodeId &&
+        input.config.planFallbackFromNodeIds.length > 0;
+    let effectiveContractText = null;
+    if (revisionPatchMode) {
+        const originalNodeId = input.config.planFallbackFromNodeIds[0];
+        let originalText;
+        try {
+            originalText = await readNodeText(input.runDir, originalNodeId);
+        }
+        catch (error) {
+            return finalizePrewrite(input, {
+                ...basePending,
+                verdict,
+                classification: "retryable-invalid",
+                failureReason: `frontend prewrite gate revisionPatch mode requires original contract node ${originalNodeId}: ${error instanceof Error ? error.message : String(error)}`,
+                failureCode: "contract-invalid",
+            });
+        }
+        let originalValue;
+        let patchValue;
+        try {
+            originalValue = extractFrontendImplementationJson(originalText);
+            patchValue = extractFrontendImplementationJson(planText);
+        }
+        catch (error) {
+            return finalizePrewrite(input, {
+                ...basePending,
+                verdict,
+                classification: "retryable-invalid",
+                failureReason: `frontend prewrite gate revisionPatch mode failed to parse contract/patch: ${error instanceof Error ? error.message : String(error)}`,
+                failureCode: "contract-invalid",
+            });
+        }
+        let merged;
+        try {
+            merged = applyFrontendImplementationContractPatch(originalValue, patchValue);
+        }
+        catch (error) {
+            return finalizePrewrite(input, {
+                ...basePending,
+                verdict,
+                classification: "retryable-invalid",
+                failureReason: `frontend prewrite gate revisionPatch apply failed: ${error instanceof Error ? error.message : String(error)}`,
+                failureCode: "contract-invalid",
+            });
+        }
+        effectiveContractText = serializeDeterministicJson(merged);
+    }
+    const requirementIdSearchText = effectiveContractText ?? planText;
+    const missingIds = input.config.requiredRequirementIds.filter((id) => !requirementIdSearchText.includes(id));
     if (missingIds.length > 0) {
         return finalizePrewrite(input, {
             ...basePending,
@@ -495,7 +553,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 +574,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 +785,24 @@ export async function runFrontendPrewriteGate(input) {
             }
         }
     }
+    // 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 +810,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,

package/dist/workflows/dag/init-hybrid.js

@@ -2339,6 +2339,7 @@ function pruneFrontendTasksForRisk(tasks, risk) {
                             planFallbackFromNodeIds: [],
                             reviewFromNodeId: "frontend-design-review-pi",
                             reviewFallbackFromNodeIds: [],
+                            revisionPatch: false,
                         },
                     }
                     : task.shell,
@@ -2485,8 +2486,27 @@ async function buildFrontendHybridDagFromTask(sources) {
             "",
             "### mockApi.endpoints - GOOD (strategy=native with complete endpoint):",
             '{"strategy":"native","productionDefaultOff":true,"activation":"VITE_ENABLE_MOCK=true","endpoints":[{"method":"GET","path":"/api/users","fixture":"mocks/fixtures/users.json","consumer":"src/api/users.ts"}]}',
+            "",
+            "### optional plan fields - GOOD (all optional; omit when absent):",
+            '{"implementationSteps":["confirm contract","sync tests"],"stylingStrategy":"reuse existing design tokens","dependencyPolicy":"no new runtime deps","residualRisks":["browser a11y not-run"],"realIntegrationGap":"FE-TEST owns live HTTP"}',
+            "",
+            "### optional plan fields - BAD (present-but-empty strings are rejected):",
+            '{"stylingStrategy":"","dependencyPolicy":""}  <-- REJECTED: optional string fields must be non-empty when present; omit them instead',
         ].join("\n");
     })();
+    const frontendContractFieldSummary = [
+        "## Contract field summary (authoritative JSON; no plan prose)",
+        "The plan/revision node emits only a fenced json contract — there is no Markdown plan explanation to read. Review these fields:",
+        "- requirements[]: id, expectedOutcome, implementationTargets, verificationTargetIds, evidenceGap",
+        "- uiStates[]: name, applicable, expectedBehavior, implementationTargets, verificationTargetIds, notApplicableReason",
+        "- interactions[]: name, trigger, expectedBehavior, implementationTargets, verificationTargetIds",
+        "- targets: files, routes, publicApiChanges",
+        "- mockApi: strategy, productionDefaultOff, activation, endpoints[]",
+        "- verificationTargets[]: id, type, commandLabel, file, symbol, requirementIds, uiStates",
+        "- designEvidence: source, paths, conflicts; evidenceGaps[]",
+        "- optional: implementationSteps[], stylingStrategy, dependencyPolicy, residualRisks[], realIntegrationGap",
+        "Do not require or read a separate plan prose section; the contract JSON is the only plan surface.",
+    ].join("\n");
     const sourceContext = [
         buildSourceContextBlock(sources),
         capabilityContextBlock,
@@ -2749,14 +2769,14 @@ async function buildFrontendHybridDagFromTask(sources) {
                 allowedPaths: readOnlyPaths,
                 forbiddenPaths,
                 skills: FRONTEND_IMPLEMENTATION_SKILLS,
-                outputContract: "One-line lead-in, then exactly ONE fenced json object (```json ... ```) conforming to frontend-implementation-contract-v1. This fenced block is the single authoritative implementation contract the prewrite gate materializes; it must appear exactly once. Immediately after it, append exactly one ```openspec-citations``` fenced citation block. After the citation block, an optional Markdown explanation may follow covering Requirement Coverage, Implementation Steps, Target Files, UI State Handling, Styling / Component Strategy, Interaction Notes, Mock / API Strategy, Dependency Policy, Verification Plan, Real Integration Gap, and Residual Risks; this explanation may be omitted and may be truncated, and must not be placed before the contract JSON. Apart from the contract JSON fenced block and the openspec-citations block, do not emit any other fenced block or raw JSON. No file writes.",
+                outputContract: "One-line lead-in, then exactly ONE fenced json object (```json ... ```) conforming to frontend-implementation-contract-v1. This fenced block is the single authoritative implementation contract the prewrite gate materializes; it must appear exactly once. Immediately after it, append exactly one ```openspec-citations``` fenced citation block. Do NOT emit a Markdown plan explanation or any prose after the contract JSON — the output is JSON-only (the gate renders plan.md deterministically). Apart from the contract JSON fenced block and the openspec-citations block, do not emit any other fenced block or raw JSON. No file writes.",
                 subtask_prompt: [
                     "Based on frontend-contract-pi, frontend-scout-pi, task sources, and the generation-time Mock capability evidence, return a minimal frontend implementation plan.",
                     "Select the Mock / API strategy inside the plan and structured contract. Carry endpoint/fixture mapping, explicit activation, production-default-off rule, verification commands, and Real Integration Gap into both outputs.",
-                    "Include ordered steps, target files, UI state handling, styling/component strategy, interaction notes, Mock/API strategy, dependency policy, deterministic verification entrypoints, and residual risks. Use only the fixed entrypoints below; implementation may add tests behind them but cannot replace them.",
+                    "Encode ordered steps (implementationSteps), target files, UI state handling, styling/component strategy (stylingStrategy), interaction notes, Mock/API strategy, dependency policy (dependencyPolicy), deterministic verification entrypoints, Real Integration Gap (realIntegrationGap), and residual risks (residualRisks) into the contract JSON fields. Use only the fixed entrypoints below; implementation may add tests behind them but cannot replace them.",
                     "Every target file and verification target must be selected from the current target workspace and task scope. Do not reuse paths or symbols from examples, prior tasks, or loop-agent itself; if the project uses app/, packages/, spec/, __tests__, or another layout, preserve that layout.",
                     "Consume the Scout TARGET_SURFACE evidence before selecting files. Preserve the discovered existing entrypoint and data source. If implementationPaths or testPaths are outside task allowedPaths, record a blocking scope conflict; do not substitute a new page or silently broaden the writeSet.",
-                    "Output in this exact order: (1) exactly one fenced json object conforming to frontend-implementation-contract-v1 — this fenced block is the single authoritative contract the prewrite gate materializes; (2) exactly one openspec-citations citation fenced block appended immediately after it; (3) optional Markdown explanation. The Markdown explanation may be omitted and may be truncated; never place evidence excerpts, duplicated upstream context, or long prose before the contract JSON. Do not emit any raw JSON or JSON objects in prose. Apart from the single contract JSON fenced block and the openspec-citations block, do not emit any other fenced block.",
+                    "Output in this exact order: (1) exactly one fenced json object conforming to frontend-implementation-contract-v1 — this fenced block is the single authoritative contract the prewrite gate materializes; (2) exactly one openspec-citations citation fenced block appended immediately after it. Do NOT emit a Markdown plan explanation or any prose after the contract JSON — the output is JSON-only. Do not emit any raw JSON or JSON objects in prose. Apart from the single contract JSON fenced block and the openspec-citations block, do not emit any other fenced block.",
                     "Each requirement must state its user-observable or logic-observable expectedOutcome. Each interaction must state its trigger and expectedBehavior. IDs plus file paths are not sufficient behavior semantics.",
                     requirementCoverageInstruction,
                     "verificationTargets[].commandLabel MUST be one of the frozen command labels listed above. Any other value will be rejected at contract materialization.",
@@ -2783,13 +2803,14 @@ async function buildFrontendHybridDagFromTask(sources) {
                 outputProtocol: REVIEW_VERDICT_OUTPUT_PROTOCOL,
                 outputContract: "Plain Markdown whose first non-empty line is VERDICT: pass or VERDICT: request-revision, followed by Findings, Required Plan Corrections, and Checked Items. No file writes.",
                 subtask_prompt: [
-                    "Audit the frontend plan before implementation.",
+                    "Audit the frontend plan before implementation. Consume the contract JSON (the single fenced json block from frontend-plan-pi); there is no separate plan prose.",
                     "First non-empty line must be exactly VERDICT: pass or VERDICT: request-revision.",
                     "Request revision when the Mock strategy is MOCK_STRATEGY: blocked, missing, unsupported by repository evidence, inconsistent with the API contract, outside authorized paths/dependencies, unable to prove production-default-off behavior with the fixed production/default-real-path static check, or missing deterministic behavior verification for a declared behavior target or selected Mock strategy. Mock strategies require Mock-backed evidence. A static-only contract is allowed only when every verification target is static and maps to a declared static entrypoint. not-needed otherwise requires applicable real/no-remote behavior evidence unless auto mode explicitly skipped Mock because no project Mock capability exists; in that case the plan must preserve the real request path and record the Real Integration Gap.",
                     "Also request revision for missing applicable UI states, unsupported dependency additions, design-system drift without reason, weak interaction coverage, broad scope, inline fake data, schema drift, or missing deterministic verification commands.",
                     "Read-only: do not modify repository files.",
                     fixedVerificationContext,
                     sourceContext,
+                    frontendContractFieldSummary,
                     mockContextBlock,
                 ].join("\n\n"),
             },
@@ -2810,16 +2831,16 @@ async function buildFrontendHybridDagFromTask(sources) {
                 allowedPaths: readOnlyPaths,
                 forbiddenPaths,
                 skills: FRONTEND_IMPLEMENTATION_SKILLS,
-                outputContract: "When the initial design review requests revision, return a one-line lead-in followed by exactly ONE fenced json object (```json ... ```) conforming to frontend-implementation-contract-v1. This fenced block is the single authoritative implementation contract the prewrite gate materializes; it must appear exactly once. Immediately after it, append exactly one ```openspec-citations``` fenced citation block. After the citation block, an optional Markdown revision plan explanation may follow covering Requirement Coverage, Implementation Steps, Target Files, UI State Handling, Styling / Component Strategy, Interaction Notes, Mock / API Strategy, Dependency Policy, Verification Plan, Real Integration Gap, and Residual Risks; this explanation may be omitted and may be truncated, and must not be placed before the contract JSON. Apart from the contract JSON fenced block and the openspec-citations block, do not emit any other fenced block or raw JSON. No file writes.",
+                outputContract: "When the initial design review requests revision, return a one-line lead-in followed by exactly ONE fenced json object (```json ... ```) containing an RFC 7386 merge-patch delta against the original frontend-implementation-contract-v1 (only the fields you change; null deletes a key; arrays and scalars replace; plain objects merge recursively). Immediately after it, append exactly one ```openspec-citations``` fenced citation block. Do NOT emit a full contract, Markdown explanation, or prose — the output is JSON-only; the gate applies the patch on the original contract and renders plan.md deterministically. Apart from the patch JSON fenced block and the openspec-citations block, do not emit any other fenced block or raw JSON. No file writes.",
                 subtask_prompt: [
-                    "Consume frontend-plan-pi (original plan) and frontend-design-review-pi (first design review findings).",
-                    "This node runs only when frontend-design-review-pi emitted VERDICT: request-revision. Produce a complete revised implementation plan that addresses every Required Plan Correction from the design findings.",
-                    "The revised plan must include Requirement Coverage, Implementation Steps, Target Files, UI State Handling, Styling / Component Strategy, Interaction Notes, Mock / API Strategy, Dependency Policy, Verification Plan, Real Integration Gap, and Residual Risks.",
+                    "Consume frontend-plan-pi (original contract JSON) and frontend-design-review-pi (first design review findings).",
+                    "This node runs only when frontend-design-review-pi emitted VERDICT: request-revision. Produce an RFC 7386 merge-patch delta against the original contract JSON that addresses every Required Plan Correction from the design findings.",
+                    "The patch delta may update any of these contract fields: requirements, implementationSteps, targets, uiStates, interactions, mockApi, dependencyPolicy, stylingStrategy, verificationTargets, evidenceGaps, residualRisks, realIntegrationGap. Only include fields you change; omit unchanged fields (the gate applies the patch on the original contract). null deletes a key; arrays and scalars replace; plain objects merge recursively.",
                     requirementCoverageInstruction,
                     "Do not turn MOCK_STRATEGY: blocked into an implementable strategy without new repository or contract evidence that resolves every blocker.",
                     "Read-only: do not modify code, docs, artifacts, or repository files. This node revises the plan only.",
-                    "Output in this exact order: (1) exactly one fenced json object conforming to frontend-implementation-contract-v1 — this fenced block is the single authoritative contract the prewrite gate materializes; (2) exactly one openspec-citations citation fenced block appended immediately after it; (3) optional Markdown explanation. The Markdown explanation may be omitted and may be truncated; never place evidence excerpts, duplicated upstream context, or long prose before the contract JSON. Bind the contract to the supplied task sources; map every requirement and applicable UI state to concrete implementation and verification targets or an explicit blocking evidence gap. Do not emit any raw JSON or JSON objects in prose. Apart from the single contract JSON fenced block and the openspec-citations block, do not emit any other fenced block. Do not include secrets or unsafe paths.",
-                    "Preserve each requirement expectedOutcome and each interaction trigger/expectedBehavior in the revised contract; do not reduce behavior semantics to IDs and paths.",
+                    "Output in this exact order: (1) exactly one fenced json object containing the merge-patch delta — this is the only plan output the prewrite gate applies on the original contract; (2) exactly one openspec-citations citation fenced block appended immediately after it. Do NOT emit a full contract, Markdown explanation, or prose — the output is JSON-only. Do not emit any raw JSON or JSON objects in prose. Apart from the patch JSON fenced block and the openspec-citations block, do not emit any other fenced block. Do not include secrets or unsafe paths.",
+                    "Preserve each requirement expectedOutcome and each interaction trigger/expectedBehavior in the effective (merged) contract; do not reduce behavior semantics to IDs and paths.",
                     "verificationTargets[].commandLabel MUST be one of the frozen command labels listed above. Any other value will be rejected at contract materialization.",
                     verificationTargetFileInstruction,
                     fixedVerificationContext,
@@ -2848,7 +2869,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                 outputProtocol: REVIEW_VERDICT_OUTPUT_PROTOCOL,
                 outputContract: "For the effective frontend plan, return plain Markdown whose first non-empty line is VERDICT: pass or VERDICT: request-revision, followed by Findings and Checked Items. No file writes.",
                 subtask_prompt: [
-                    "Audit the revised frontend plan before implementation. This node runs only after request-revision and consumes frontend-plan-revision-pi.",
+                    "Audit the revised frontend plan before implementation. This node runs only after request-revision and consumes the merge-patch delta from frontend-plan-revision-pi applied on the original frontend-plan-pi contract JSON — there is no separate plan prose.",
                     "First non-empty line must be exactly VERDICT: pass or VERDICT: request-revision.",
                     "Verify that every Required Plan Correction from the initial design review has been fully addressed.",
                     "Recheck the selected Mock / API strategy, contract-to-fixture mapping, authorized paths/dependencies, explicit activation, production-default-off behavior, behavior verification, and Real Integration Gap. MOCK_STRATEGY: blocked cannot receive VERDICT: pass.",
@@ -2857,6 +2878,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                     "Read-only: do not modify repository files.",
                     fixedVerificationContext,
                     sourceContext,
+                    frontendContractFieldSummary,
                     mockContextBlock,
                 ].join("\n\n"),
             },
@@ -2900,6 +2922,8 @@ async function buildFrontendHybridDagFromTask(sources) {
                                 ],
                         artifactName: "frontend-implementation-contract.json",
                         outputDir: "contracts",
+                        revisionPatch: true,
+                        planMdArtifactName: "frontend-plan.md",
                         requireSourceFreshness: true,
                         implementationWriteSet: implementPaths.writeSet,
                         openspecPolicy: openspecGate.openspecPolicy,

package/dist/workflows/dag/types.js

@@ -199,6 +199,22 @@ export const dagFrontendPrewriteGateSchema = z.object({
      * preserved. Generation always writes it explicitly for new DAGs.
      */
     openspecPolicy: z.enum(["cited", "scan-strict"]).optional(),
+    /**
+     * When true, the effective plan node (planFromNodeId when it is selected
+     * over the fallback) emits an RFC 7386 merge-patch delta instead of a full
+     * contract. The gate applies it on the original contract node
+     * (planFallbackFromNodeIds[0]) before analysis/materialization. Legacy DAGs
+     * without this field keep full-contract semantics.
+     */
+    revisionPatch: z.boolean().optional(),
+    /**
+     * Deterministically rendered plan.md artifact name (same outputDir as the
+     * contract). Defaults to frontend-plan.md at runtime.
+     */
+    planMdArtifactName: z
+        .string()
+        .regex(/^[a-z0-9][a-z0-9._-]*\.md$/)
+        .optional(),
     /**
      * Generation-frozen candidate source metadata (diagnostic). cited mode
      * candidates are declared ∪ taskSourceCited; scan-strict candidates are

package/docs/templates/frontend-implementation-contract.schema.json

@@ -16,7 +16,12 @@
     "mockApi": { "type": "object", "additionalProperties": false, "required": ["strategy", "productionDefaultOff", "activation", "endpoints"], "properties": { "strategy": { "enum": ["native", "browser-intercept", "request-adapter", "not-needed"] }, "productionDefaultOff": { "const": true }, "activation": { "type": ["string", "null"], "minLength": 1 }, "endpoints": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["method", "path"], "properties": { "method": { "enum": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"] }, "path": { "type": "string", "pattern": "^/" }, "fixture": { "anyOf": [{ "$ref": "#/$defs/path" }, { "type": "null" }] }, "consumer": { "anyOf": [{ "$ref": "#/$defs/path" }, { "type": "null" }] } } } } } },
     "designEvidence": { "type": "object", "additionalProperties": false, "required": ["source", "paths", "conflicts"], "properties": { "source": { "type": "string", "minLength": 1 }, "paths": { "type": "array", "items": { "$ref": "#/$defs/path" } }, "conflicts": { "type": "array", "items": { "type": "string", "minLength": 1 } } } },
     "verificationTargets": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "required": ["id", "type", "commandLabel", "file", "requirementIds", "uiStates"], "properties": { "id": { "type": "string", "minLength": 1 }, "type": { "enum": ["static", "unit", "component", "integration", "mock"] }, "commandLabel": { "type": "string", "minLength": 1 }, "file": { "$ref": "#/$defs/path" }, "symbol": { "anyOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] }, "requirementIds": { "type": "array", "items": { "$ref": "#/$defs/requirementId" } }, "uiStates": { "type": "array", "items": { "type": "string", "minLength": 1 } } } } },
-    "evidenceGaps": { "type": "array", "items": { "$ref": "#/$defs/gap" } }
+    "evidenceGaps": { "type": "array", "items": { "$ref": "#/$defs/gap" } },
+    "implementationSteps": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "stylingStrategy": { "type": "string", "minLength": 1 },
+    "dependencyPolicy": { "type": "string", "minLength": 1 },
+    "residualRisks": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "realIntegrationGap": { "type": "string", "minLength": 1 }
   },
   "allOf": [{ "if": { "properties": { "mockApi": { "properties": { "strategy": { "enum": ["native", "browser-intercept", "request-adapter"] } } } } }, "then": { "properties": { "mockApi": { "properties": { "endpoints": { "minItems": 1, "items": { "required": ["method", "path", "fixture", "consumer"] } } } } } } }],
   "$defs": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.39.0-next.4",
+  "version": "0.39.0-next.5",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",

package/skills/frontend-implementation/references/node-contracts.md

@@ -6,11 +6,12 @@ Pre-write nodes are read-only. Preserve IDs, labels, commands, language, require
 
 - **`frontend-contract-pi`**: `Scope`, `Non-goals`, `Acceptance Criteria`, `UI States`, `Target Runtime Environment`, `Risks`, `Verification Expectations`; no guessed requirements.
 - **`frontend-scout-pi`**: routes, components, tokens, data/API/Mock, scripts, tests, assets; fact vs inference vs gap. Search+read `openspec/schemas/`, `openspec/project-specs/`, `ai_workspace/` first. Output stack, routes, components, styling, conventions, state/data, test entry points, reuse, risks.
-- **`frontend-plan-pi` + conditional design loop**: AC → observable `expectedOutcome`; interactions → `trigger`+`expectedBehavior`; steps, in-bound files, applicable UI states, reuse, deps, Mock/API strategy, activation/rollback, frozen verify entrypoints, real-integration gap. Markdown plans only; each ends with **exactly one** fenced `json` block (authoritative `frontend-implementation-contract-v1`), then exactly one fenced `openspec-citations` block listing each read openspec file. No raw JSON, JSON in prose, or 2nd fenced block. `frontend-contract-json-pi`/`frontend-contract-json-validate-shell` don't exist; prewrite gate materializes the contract from effective plan. IDs+paths aren't sufficient behavior semantics. Use `uiStates: []` for logic-only changes; don't invent UI states. Applicable states need behavior/implementation/verification; non-applicable need a reason, no empty placeholders. Non-`not-needed` needs frozen Mock verify commands (`frontendMock.verifyCommands`/`package.json` mock script/capability seed); `auto` with absent/ambiguous capability or no command → `not-needed` (real requests default, gap recorded); `required` without a command → generation-time blocked (no writer). Initial pass uses original plan; only exact `request-revision` runs read-only revision + final review. Small-risk: one design review.
+- **`frontend-plan-pi` + conditional design loop**: AC → observable `expectedOutcome`; interactions → `trigger`+`expectedBehavior`; steps, in-bound files, applicable UI states, reuse, deps, Mock/API strategy, activation/rollback, frozen verify entrypoints, real-integration gap. **JSON-only**: one-line lead-in + **exactly one** fenced `json` block (`frontend-implementation-contract-v1`) + one `openspec-citations` block. No plan prose; plan.md is rendered by the prewrite gate. `frontend-contract-json-pi`/`frontend-contract-json-validate-shell` don't exist. IDs+paths aren't sufficient behavior semantics. Use `uiStates: []` for logic-only changes; don't invent UI states. Applicable states need behavior/implementation/verification; non-applicable need a reason. Non-`not-needed` needs frozen Mock verify commands (`frontendMock.verifyCommands`/`package.json` mock script/capability seed); `auto` with absent/ambiguous capability or no command → `not-needed`; `required` without a command → generation-time blocked. Initial pass uses original plan; only exact `request-revision` runs revision + final review. Small-risk: one design review.
 - **`frontend-prewrite-gate-shell`**: sole write authorization. Resolve effective plan (revised if revision ran, else original) + review; require exact pass; retain every REQ/BR/AC id; enforce Mock policy; validate schema/source binding+writeSet containment; materialize `contracts/frontend-implementation-contract.json` from the **single** fenced contract block (multiple candidates fail closed `invalid-output`). Fallback only when conditional primary absent; existing malformed primary fails closed. Generation-time blocked Mock yields one deterministic blocking shell node, no writer.
   - `verificationTarget.commandLabel` must be a **frozen command label** from `verifyEvidence.commandLabels`; others fail closed (`invalid-output`). Empty frozen set (no `run.json`) skips check.
   - `mockApi.strategy !== "not-needed"` fails closed when `mockCommandLabels` empty (`no authorized Mock verification commands`).
   - OpenSpec policy: `task.json.frontendOpenspec.policy` (default `cited`); candidates = `requiredReadPaths` ∪ task-source citations; effective plan must append one fenced `openspec-citations` block (one JSON `{"path","section","line"}` per line). Candidates non-empty but block missing/unparseable → `openspec-citation-block-unparseable`; candidate not cited → `openspec-not-cited`; cited path without successful read event in plan/review → `openspec-citation-not-read` (anti-fabrication). Empty candidates skip enforcement (generation-time advisory). `scan-strict` keeps auto-discovered full-read semantics (`openspec-not-read`); both modes keep `candidate-missing-drift`.
+  - revisionPatch mode: revision output is an RFC 7386 merge-patch delta applied on the original contract node (`planFallbackFromNodeIds[0]`); legacy DAGs keep full-contract semantics. Size guard: canonical serialization >64KB → `retryable-invalid` + `contract-too-large`.
 - **`frontend-implement-pi`**: sole regular exclusive writer; uses `frontend-bounded-implement` (not this skill). Stay in `writeSet`; real requests default-on. Atomic handler/intercept/adapter with consumer+tests. Stop on forbidden paths/guesses. First line `IMPLEMENTATION_OUTCOME: changed|already-satisfied|blocked`; runtime checks against attributed diff. Optional mock-verify when frozen; static+behavior always; behavior must prove page consumption. `not-needed` keeps real integration pending unless real backend has fresh evidence.
 
 ## Contract / trace / stages (M1–M2)