@tea-agent/loop-agent 0.39.0-next.3 → 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": "944355b6e1204f12ebd4a7b0cc9c52fabff8ff97",
-  "builtAt": "2026-08-17T09:28:57.068Z"
+  "gitSha": "5c445d9697e1ff1974fbea8999634ecc668fecc9",
+  "builtAt": "2026-08-17T11:38:52.355Z"
 }

package/dist/executors/dag-pi-executor.js

@@ -1043,6 +1043,7 @@ export function mapPiResultToDagNodeResult(result, firstProtocolLine) {
         sdkAttempted: result.sdkAttempted,
         tokensUsed: result.tokensUsed,
         parsedEvents: result.parsedEvents,
+        stopReason: readWriterThinkingExhaustionEvidence(result).stopReason,
     };
 }
 function canonicalizeProtocolFirstLine(assistantText, firstProtocolLine) {

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

@@ -20,6 +20,7 @@ import { applySddEmbeddedEnhancements, probeRepoLocalSddSkills, } from "./sdd-em
 import { discoverProjectGovernancePresence } from "./project-governance-context.js";
 import { getTaskPaths, loadTaskConfig } from "../../task/runtime.js";
 import { materializeTaskReferenceDocs } from "../../task/source-references.js";
+import { REQUIREMENT_FACT_ROLES } from "../../task/source-prepare/artifact-meta.js";
 import { observeTaskContract } from "../../task/contract/observe.js";
 import { dagHasWriterExecution } from "./task-contract-binding.js";
 import { DEFAULT_VERIFY_TIMEOUT_MS, resolveVerifyPreset, } from "../../executors/shell-verification.js";
@@ -1499,11 +1500,27 @@ function buildSourceContextBlock(sources) {
             .relative(path.join(sources.taskDir, "source"), reference.path)
             .replaceAll(path.sep, "/");
         const referenceRef = toDagSourcePath(sources, reference.path);
-        const referenceExcerpt = excerptMarkdown(reference.markdown, {
-            sourceRef: referenceRef,
-        });
-        boundReadPaths.push(`- reference ${relativePath}: ${referenceRef}`);
-        parts.push(`## Task source reference: ${relativePath}`, `Bound readPath (use for Pi read-tool calls): ${referenceRef}`, referenceExcerpt.text);
+        // Fact-source roles (requirement/acceptance) carry the fields contracts
+        // depend on (AC/scope/columns). Inject them in full so a fixed excerpt
+        // cannot silently drop definitions; archival roles stay excerpted.
+        const isFactRole = reference.role !== undefined &&
+            REQUIREMENT_FACT_ROLES.has(reference.role);
+        const referenceExcerpt = isFactRole
+            ? {
+                text: reference.markdown.trim(),
+                truncated: false,
+                originalChars: reference.markdown.trim().length,
+                maxChars: Number.POSITIVE_INFINITY,
+            }
+            : excerptMarkdown(reference.markdown, {
+                sourceRef: referenceRef,
+            });
+        boundReadPaths.push(`- reference ${relativePath}${isFactRole ? " (full source)" : ""}: ${referenceRef}`);
+        parts.push(`## Task source reference: ${relativePath}`, `Bound readPath (use for Pi read-tool calls): ${referenceRef}`, ...(isFactRole
+            ? [
+                `Full source injected (role: ${reference.role}) — complete and authoritative; no excerpt truncation applied.`,
+            ]
+            : []), referenceExcerpt.text);
     }
     parts.push("## Bound source read paths", ...boundReadPaths, "Use these repository-readable paths for any Pi read-tool calls. Bound files under `.harness/tasks/<taskId>/source/**` are read-only inputs: reading them is allowed even though writing `.harness/**` is forbidden.", "Never resolve task-relative citations such as `source/需求.md` or `source/references/*` against the repository root, invent `source/<taskId>/...`, search for substitutes, or fall back to `docs/**` when a bound read fails.", "## Task config summary", `- taskId: ${sources.taskConfig.taskId}`, `- flow: ${sources.taskConfig.flow}`, `- complexity: ${sources.taskConfig.complexity}`, `- contextProfile: ${sources.taskConfig.contextProfile}`, `- allowedPaths: ${sources.taskConfig.allowedPaths.join(", ") || "(none — review before execute)"}`, `- forbiddenPaths: ${sources.taskConfig.forbiddenPaths.join(", ") || "(none)"}`, '- Pi DAG nodes are read-only unless toolProfile="write" is explicitly selected for a bounded writer node.', "- Agent DAG read-only nodes must not write root artifacts/**; root artifacts/ is not a per-node scratchpad.", `- Derived execution contract and immutable references live under the Bound source read paths above (not as repo-root \`source/...\`).`);
     if (sources.taskConfig.hardConstraints.length > 0) {
@@ -1541,10 +1558,49 @@ async function loadMaterializedSourceReferences(sourceDir) {
     }
     await collect(referenceDir);
     referencePaths.sort((left, right) => left.localeCompare(right));
-    return Promise.all(referencePaths.map(async (filePath) => ({
-        path: filePath,
-        markdown: await readFile(filePath, "utf-8"),
-    })));
+    const roleByPath = await loadReferenceRoles(sourceDir);
+    return Promise.all(referencePaths.map(async (filePath) => {
+        const relative = path
+            .relative(sourceDir, filePath)
+            .replaceAll(path.sep, "/");
+        const role = roleByPath.get(relative);
+        return {
+            path: filePath,
+            markdown: await readFile(filePath, "utf-8"),
+            ...(role !== undefined ? { role } : {}),
+        };
+    }));
+}
+/**
+ * Reads `source-manifest.json` into a materializedPath → role map so the DAG
+ * generator can tell fact-source references (requirement/acceptance) apart
+ * from archival ones (analysis/clarification/design). A missing or malformed
+ * manifest yields an empty map; such references keep the bounded-excerpt
+ * treatment instead of being injected in full.
+ */
+async function loadReferenceRoles(sourceDir) {
+    const roleByPath = new Map();
+    const manifestPath = path.join(sourceDir, "source-manifest.json");
+    let raw;
+    try {
+        raw = await readFile(manifestPath, "utf-8");
+    }
+    catch {
+        return roleByPath;
+    }
+    try {
+        const manifest = JSON.parse(raw);
+        for (const document of manifest.documents ?? []) {
+            if (typeof document.materializedPath === "string" &&
+                typeof document.role === "string") {
+                roleByPath.set(document.materializedPath.replaceAll(path.sep, "/"), document.role);
+            }
+        }
+    }
+    catch {
+        // A malformed manifest must never break reference injection.
+    }
+    return roleByPath;
 }
 export async function loadTaskHybridSources(repoRoot, taskId) {
     const paths = getTaskPaths(repoRoot, taskId);
@@ -2283,6 +2339,7 @@ function pruneFrontendTasksForRisk(tasks, risk) {
                             planFallbackFromNodeIds: [],
                             reviewFromNodeId: "frontend-design-review-pi",
                             reviewFallbackFromNodeIds: [],
+                            revisionPatch: false,
                         },
                     }
                     : task.shell,
@@ -2429,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,
@@ -2463,6 +2539,11 @@ async function buildFrontendHybridDagFromTask(sources) {
         `Non-static targets (type unit/component/integration/mock) MUST set file to a concrete code file inside the implementation writeSet (task allowedPaths); the prewrite gate rejects any non-static target whose file falls outside the writeSet.`,
         `Command-level checks that run project-wide (all tests, typecheck, build, governance) MUST use type "static" and must NOT be bound as non-static targets with file=package.json/tsconfig.json/vite.config.ts/scripts/*. Static targets are exempt from the writeSet containment check.`,
     ].join("\n");
+    const mandatorySourceReadInstruction = [
+        "## Mandatory full source read before contracting",
+        "Before producing this contract/plan, use the Pi read tool to read the FULL bound source files (需求.md, 执行约束.md, and every `references/*` Bound readPath listed above) — the inline copies above may be truncated excerpts, and requirement/acceptance references are authoritative only in their full form.",
+        "Do not drop scope fields, acceptance criteria, non-goals, UI states, or column/field definitions that exist in the full sources but are absent from the inline excerpts; if a field appears in the full source, it belongs in the contract.",
+    ].join("\n");
     const strategy = resolveDagVerifyStrategy(taskConfig);
     const readOnlyPaths = taskConfig.allowedPaths.length > 0 ? taskConfig.allowedPaths : ["**"];
     const behaviorPaths = deriveFrontendBehaviorPaths(taskConfig);
@@ -2648,6 +2729,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                     "Read task source and produce a concise frontend implementation contract.",
                     "Cover scope, non-goals, acceptance criteria, UI states, target runtime environment, risks, and verification expectations.",
                     "Read-only: do not modify code, docs, artifacts, or repository files.",
+                    mandatorySourceReadInstruction,
                     sourceContext,
                 ].join("\n\n"),
             },
@@ -2687,19 +2769,20 @@ async function buildFrontendHybridDagFromTask(sources) {
                 allowedPaths: readOnlyPaths,
                 forbiddenPaths,
                 skills: FRONTEND_IMPLEMENTATION_SKILLS,
-                outputContract: "Markdown implementation plan with 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, ending with 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 and must not contain or be followed by any raw JSON or extra fenced block. 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.",
-                    "End with exactly one fenced json object conforming to frontend-implementation-contract-v1. This node is the single contract JSON producer: the fenced block is the authoritative contract the prewrite gate materializes. Do not emit any raw JSON, JSON in prose, or a second fenced block anywhere in the response; the plan text must not contain other balanced JSON objects.",
+                    "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.",
                     verificationTargetFileInstruction,
                     "Read-only: do not modify code, docs, artifacts, or repository files.",
+                    mandatorySourceReadInstruction,
                     fixedVerificationContext,
                     sourceContext,
                     mockContextBlock,
@@ -2720,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"),
             },
@@ -2747,16 +2831,16 @@ async function buildFrontendHybridDagFromTask(sources) {
                 allowedPaths: readOnlyPaths,
                 forbiddenPaths,
                 skills: FRONTEND_IMPLEMENTATION_SKILLS,
-                outputContract: "When the initial design review requests revision, return a complete Markdown revision plan 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 and must not contain or be followed by any raw JSON or extra fenced block. Do NOT include multiple fenced JSON blocks; only the single authoritative contract JSON block is accepted. 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.",
-                    "End the response with exactly one fenced json object conforming to frontend-implementation-contract-v1. This node is the single contract JSON producer when the design review requests revision: the fenced block is the authoritative contract the prewrite gate materializes. Do not emit any raw JSON, JSON in prose, or a second fenced block anywhere in the response. Bind it 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 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,
@@ -2785,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.",
@@ -2794,6 +2878,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                     "Read-only: do not modify repository files.",
                     fixedVerificationContext,
                     sourceContext,
+                    frontendContractFieldSummary,
                     mockContextBlock,
                 ].join("\n\n"),
             },
@@ -2837,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/node-execution.js

@@ -152,6 +152,20 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
             previousProtocolReason,
             "Return exactly one fenced json block conforming to the frontend-implementation-contract-v1 schema.",
             "Fix every reported field violation: do not emit null for optional fields, do not misspell field names, and match the required types exactly.",
+            "The Markdown explanation may be omitted; prioritize a complete contract.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
+    if (previousFailureCategory === "structured-output-truncated" &&
+        task.structuredContractOutput) {
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "Previous attempt was truncated by the provider (stopReason=length) before the JSON contract was completed.",
+            "This attempt: output ONLY the single fenced json contract block, immediately followed by exactly one openspec-citations block.",
+            "Do not emit any Markdown explanation, evidence excerpts, or duplicated upstream context.",
+            "The contract JSON must be complete; the trailing Markdown explanation may be omitted entirely.",
             "</retry_instruction>",
         ].join("\n");
     }
@@ -768,10 +782,16 @@ export async function executeDagNode(input) {
                     sourceBinding: spec.sourceBinding,
                 });
                 if (!contractCheck.ok) {
+                    // A provider stopReason=length means the response was cut before the
+                    // JSON contract could complete; separate it from an ordinary bad
+                    // contract so the retry switches to a JSON-only output strategy.
+                    const attemptStopReason = result.stopReason;
                     result = {
                         ...result,
                         ok: false,
-                        failureCategory: "invalid-output",
+                        failureCategory: attemptStopReason === "length"
+                            ? "structured-output-truncated"
+                            : "invalid-output",
                         stderr: [result.stderr, contractCheck.reason]
                             .filter(Boolean)
                             .join("\n"),

package/dist/workflows/dag/retry-policy.js

@@ -21,6 +21,8 @@ export const STRUCTURED_OUTPUT_RETRY_CATEGORY = "output-too-large";
 export const PROTOCOL_INVALID_RETRY_CATEGORY = "protocol-invalid";
 /** Recoverable model artifact/schema formatting failure on read-only structured nodes. */
 export const STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY = "invalid-output";
+/** Provider stopReason=length truncated the response before the JSON contract completed. */
+export const STRUCTURED_OUTPUT_TRUNCATED_RETRY_CATEGORY = "structured-output-truncated";
 /** Retry only a proven no-op from an explicitly opt-in bounded Pi writer. */
 export const WRITER_EMPTY_DIFF_RETRY_CATEGORY = "writer-empty-diff";
 /** Retry when a backend-test writer finished but Completeness Gate found missing/broken targets. */
@@ -36,6 +38,7 @@ export const STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES = [
     ...DEFAULT_DAG_RETRY_CATEGORIES,
     STRUCTURED_OUTPUT_RETRY_CATEGORY,
     STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY,
+    STRUCTURED_OUTPUT_TRUNCATED_RETRY_CATEGORY,
 ];
 /** Categories allowed on nodes that declare a machine-readable outputProtocol. */
 export const PROTOCOL_AWARE_DAG_RETRY_CATEGORIES = [
@@ -48,6 +51,7 @@ export const ALL_DAG_RETRY_CATEGORIES = [
     STRUCTURED_OUTPUT_RETRY_CATEGORY,
     PROTOCOL_INVALID_RETRY_CATEGORY,
     STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY,
+    STRUCTURED_OUTPUT_TRUNCATED_RETRY_CATEGORY,
     WRITER_EMPTY_DIFF_RETRY_CATEGORY,
     INCOMPLETE_WRITE_SET_RETRY_CATEGORY,
     WRITER_CLEAN_TIMEOUT_RETRY_CATEGORY,

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.3",
+  "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)