@tea-agent/loop-agent 0.39.0-next.18 → 0.39.0-next.19

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### 变更
+
+- npm `next` 渠道发布改为提交数节流：main push 仅当距上次 next 发布的 source commit ≥ 5 个 commit 时才自动发布（新增 `scripts/next-publish-gate.mjs`，读已发布 tarball build-stamp 对比 HEAD）；不足阈值时 workflow 绿色跳过，手动 `workflow_dispatch` 不受限（切 release 线前强制出包 / 紧急补发）。发布文档真源 §4.1/§5.1/§7/§12 同步。
+
 ### 新增
 
 - backend-test 适配 A–D：可配置 `backendTest` 布局（`testRoot`/`markdownRel`/`scriptRel`）、用户公共前置文档引用与模块顶部 `user_shared_setup`（不写 conftest）、查询轴 Scenario Partitions 确定性展开与 fail-closed 门禁、`mode=gap-fill` 13 节点增量 DAG。Slot ID 以声明的 Partition ID 为真源（`TP-<Partition ID>-...`）。
@@ -24,6 +28,7 @@
 
 ### 改进
 
+- `frontend-plan-pi` 改为 runtime skeleton + editable RFC 7386 patch：`schemaVersion`、source binding、risk、writer target files 与生产 Mock 安全位由 DAG 冻结且不可被 plan/revision 覆盖；节点 validator 将补丁编译为 canonical 完整契约后再交给 review/prewrite，并在 `contracts/candidates/<nodeId>/` 保存每次 raw/extracted/normalized/validation 证据。任务提示与三类结构化重试（invalid-output / provider length 截断 / output-too-large）同步收敛为单一 patch + 唯一 `openspec-citations`；无法在声明文件中解析的可选 verification symbol 会被确定性移除并留下 normalization action，避免格式冲突、完整契约重复输出和说明性 symbol 延迟到 trace 才失败。
 - Operator Chat 恢复工具对齐真实能力：系统提示改用 `dagReport` / `dagRerunPlan` / `dagRerun` / `standaloneTaskRerun` / `workerTaskRetry` 真名，不再写 `operator_*` 或把 `dagResume` 当成模型可执行项；`dagDoctor` / `dagStatus` / `workerPoolDoctor` 改为 typed `runId`/`taskId`，不再让模型猜 CLI `args[]`。ADR 0013 自定义 base prompt 上限由 1900 统一调整为 2500（2026-08-18，废止 0.8×2498 比例），预算用于写清节点续跑 / 整单重生 / Worker 重排队分流，以及多轮迭代恢复纪律（先一句话总结上一轮错误、修根因不修症状、禁止原样重交、同错两轮后停下报告）。
 
 - Operator Chat 对齐 pi-web：建会话不再传封闭 `tools` 白名单（避免 SDK 把扩展 MCP 工具滤出 registry），创建后 `bindExtensions` 发 `session_start`，再钉激活集。扩展注册的 MCP 工具可被模型调用；`apply_patch` / `full-tools` / `shell` / `coding-chat` 仍排除。
@@ -59,6 +64,7 @@
 - 强化 backend-test correspondence、scenario-param、Markdown/pytest writer、collection repair、日志审计和 Windows pytest argfile 执行链，稳定区分 controller TestBug、generated TestBug 与真实 API ProductBug
 
 ### 改进
+
 - backend-test correspondence 只分析目标请求实际绑定的 body/payload，忽略 `scenario` 元数据与 setup-only payload；对 `scenario["body"]` 保留字段 shape，并把 intentional invalid enum 交由 scenario-param 门禁判断；同时识别下划线前缀 pytest 参数集合与带说明的 `Payload Contract: none（…）`，避免零 eligible 的 payload/parameter 误阻断
 - backend-test correspondence 继续解析模块内 transport wrapper 的位置 payload 与 wrapper 构造 body，并清理 `Payload Enum` 值后的中文说明，避免 PUT/lifecycle 合法载荷误报；Markdown/pytest writer 同步禁止臆测响应 ID 类型，并在路径 ID 类型未声明时使用 create-delete 派生的合法 missing ID，避免把测试资产缺陷误分类为产品 400/404 缺陷
 - backend-test correspondence 可还原 `_apply_patch(_base_body(...), patch)` 等 transport-body 组合表达式，并把 setup wrapper payload 限定为有 body 契约时的 fallback；traceability 接受经递归脱敏和有界输出的结构化 request/response 日志，scenario-param 支持带显式例值的 string wrong-type；pytest writer/repair 同步禁止把 path/query/control `id` 混入 DTO patch
@@ -240,6 +246,7 @@
 
 - 修复「处理详情」思考折叠块背景引用未定义样式变量 --panel 的问题，改为确定性透明背景，消除 Console 样式变量完整性门禁对发布的拦截（视觉无变化）
 - 移除自指的 /help 命令项：输入 / 已弹出命令面板，不再单独提供重复的帮助入口
+
 ## [0.35.1] - 2026-08-15
 
 ### 重点更新
@@ -473,19 +480,23 @@
 ## [0.33.7-beta.2] - 2026-08-13
 
 ### Fixed
+
 - scenario-param 解析 `bound=LEN100`、解引用 `_STATUS_ACTIVE` 等 Python 字符串常量，识别 `"x" * _TITLE_MAX_LENGTH` 长度表达式
 - correspondence 忽略 pytest payload 中的 `expect`/`echo_*` 辅助键，避免假 PAYLOAD_SHAPE_MISMATCH
 
 ### Changed
+
 - my-webapp 五轮 backend-test 全流程 live campaign 归档（R1–R5 均 finished；R5 correspondence PASS）
 
 ## [0.33.7-beta.1] - 2026-08-12
 
 ### Fixed
+
 - scenario-param 识别 `_*_MAX_LENGTH` / `_*_OVER_LENGTH` 等长度 helper 名，明确 `custom-literal:trim` 不能是全空白，并把无 pytest.param 的 request-level/health nominal 记为 MATCH 以免污染 eligibility
 - backend-test writer 合同明确：`enum-invalid` 必须使用具体非法字面量且禁止 `_OMIT`/missing-key；`custom-literal:trim|ACTIVE|ARCHIVED` 必须使用真实 padded/enum 字面量；max/min/max+1 应用长度表达式/helper
 
 ### Changed
+
 - 归档 R108–R110 live campaign 证据与 residual 收紧结果
 
 ## [0.33.7-beta.0] - 2026-08-11

package/dist/build-stamp.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
   "version": "0.37.0",
-  "gitSha": "c311e93da8b34457472e44bd349ac0aa256a3c68",
-  "builtAt": "2026-08-19T09:55:58.554Z"
+  "gitSha": "3a13db908ffc98610e2d1c7ea17929a7ef87d8f3",
+  "builtAt": "2026-08-19T14:12:38.827Z"
 }

package/dist/workflows/dag/contract-validator-registrations.js

@@ -3,7 +3,8 @@
  * its schemaId in the contract output registry. Imported once by the node
  * executor; keeps per-contract imports out of the executor.
  */
-import { validateFrontendContractNodeOutput, validateFrontendRevisionPatchNodeOutput, } from "./frontend-implementation-contract.js";
+import { validateFrontendContractNodeOutput, validateFrontendPlanPatchNodeOutput, validateFrontendRevisionPatchNodeOutput, } from "./frontend-implementation-contract.js";
 import { registerStructuredContractValidator } from "./contract-output-registry.js";
 registerStructuredContractValidator("frontend-implementation-contract-v1", validateFrontendContractNodeOutput);
+registerStructuredContractValidator("frontend-implementation-contract-plan-patch-v1", validateFrontendPlanPatchNodeOutput);
 registerStructuredContractValidator("frontend-implementation-contract-revision-patch-v1", validateFrontendRevisionPatchNodeOutput);

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

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

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

@@ -33,7 +33,7 @@ import { buildBackendTestIntakeContext } from "./backend-test-intake-context.js"
 import { buildFrontendTestOutcomeGateShellSnippet } from "./frontend-test-result-contract.js";
 import { classifyFrontendRisk, } from "./frontend-risk.js";
 import { discoverFrontendProjectCapability, } from "./frontend-project-capability.js";
-import { FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID, loadFrontendImplementationContractJsonSchema, } from "./frontend-implementation-contract.js";
+import { buildFrontendImplementationContractSkeleton, FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID, FRONTEND_IMPLEMENTATION_CONTRACT_PLAN_PATCH_SCHEMA_ID, loadFrontendImplementationContractJsonSchema, } from "./frontend-implementation-contract.js";
 import { serializeDagTaskSourcePath } from "../../task/dag-source-paths.js";
 const REQUIREMENT_FILE = "需求.md";
 const CONSTRAINT_FILE = "执行约束.md";
@@ -2418,33 +2418,21 @@ async function buildFrontendHybridDagFromTask(sources) {
             complexity: taskConfig.complexity,
         });
     const frontendSourceBinding = buildDagSourceBinding(sources);
+    const frontendContractSkeleton = buildFrontendImplementationContractSkeleton({
+        sourceBinding: frontendSourceBinding,
+        riskLevel: frontendRisk.selectedRisk,
+        targetFiles: implementPaths.writeSet,
+    });
     const frontendContractSchemaBlock = (() => {
         const schema = loadFrontendImplementationContractJsonSchema();
-        const requirement = frontendSourceBinding.sources.find((source) => source.kind === "requirement");
-        if (!requirement) {
-            throw new Error("frontend implementation contract context requires a bound requirement source");
-        }
-        const referencePaths = frontendSourceBinding.sources
-            .filter((s) => s.kind === "reference")
-            .map((s) => s.path);
-        const fixedFields = {
-            schemaVersion: 1,
-            sourceBinding: {
-                taskId: frontendSourceBinding.taskId,
-                requirementPath: requirement.path,
-                requirementSha256: requirement.sha256,
-                referencePaths,
-                requirementIds: frontendSourceBinding.requirementIds,
-            },
-            riskLevel: frontendRisk.selectedRisk,
-            targets: { files: implementPaths.writeSet },
-        };
         return [
-            `## ${FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID} JSON Schema (authoritative; do not guess fields)`,
+            `## Final ${FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID} JSON Schema (authoritative after runtime merge)`,
             schema,
             "",
-            "## Fixed contract fields (deterministic; copy exactly and do not modify)",
-            JSON.stringify(fixedFields),
+            "## Runtime contract skeleton (deterministic and protected)",
+            JSON.stringify(frontendContractSkeleton),
+            "",
+            "The initial planner emits an editable RFC 7386 patch against this skeleton. It MUST omit schemaVersion, sourceBinding, riskLevel, targets.files, and mockApi.productionDefaultOff. The runtime merges and validates the final contract, then replaces the planner output with canonical full-contract JSON for downstream review.",
             "",
             "## Forbidden fields (these are NOT in the schema; do not emit)",
             "- schemaId",
@@ -2796,20 +2784,22 @@ async function buildFrontendHybridDagFromTask(sources) {
                 outputMode: "structured-required",
                 retryPolicy: STRUCTURED_REQUIRED_PI_RETRY_POLICY,
                 structuredContractOutput: {
-                    schemaId: "frontend-implementation-contract-v1",
+                    schemaId: FRONTEND_IMPLEMENTATION_CONTRACT_PLAN_PATCH_SCHEMA_ID,
                     retryOnInvalid: true,
+                    skeleton: frontendContractSkeleton,
                 },
                 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. 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.",
+                outputContract: "JSON-only patch output: one-line lead-in, then exactly ONE fenced json object (```json ... ```) containing only the editable RFC 7386 plan patch for the runtime contract skeleton. Omit protected fields: schemaVersion, sourceBinding, riskLevel, targets.files, and mockApi.productionDefaultOff. Immediately after it, append exactly one ```openspec-citations``` fenced citation block. The runtime applies the patch, validates it, and promotes canonical full-contract JSON for downstream review. Do NOT emit a full contract, Markdown plan explanation, raw JSON, or any other fenced block. 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.",
+                    "Use frontend-contract-pi, frontend-scout-pi, task sources, and the generation-time Mock capability evidence to fill the runtime-owned frontend contract skeleton. Return JSON-only output containing only an editable RFC 7386 plan patch. The runtime already owns schemaVersion, sourceBinding, riskLevel, targets.files, and mockApi.productionDefaultOff; omit those protected paths even when their values look obvious.",
+                    "The patch fields become the complete implementation plan after deterministic merge. Do not produce a separate plan document, prose mirror, or full contract.",
+                    "Select the Mock / API strategy only in the patch. Encode endpoint/fixture mapping, explicit activation, verification commands, and Real Integration Gap in schema-defined editable fields; productionDefaultOff comes from the protected skeleton and there is no second plan output.",
                     "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. 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.",
+                    "Output in this exact order: (1) exactly one fenced json object containing the editable plan patch; (2) exactly one openspec-citations citation fenced block appended immediately after it. Do NOT emit protected skeleton fields, a full contract, Markdown plan explanation, raw JSON, or 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.",
@@ -2837,7 +2827,7 @@ 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. Consume the contract JSON (the single fenced json block from frontend-plan-pi); there is no separate plan prose.",
+                    "Audit the frontend plan before implementation. frontend-plan-pi is emitted to you as canonical full-contract JSON after the runtime applied and validated the planner's editable patch against its protected skeleton; 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.",
@@ -2870,7 +2860,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                 subtask_prompt: [
                     "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, uiComponentChoices, 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.",
+                    "The patch delta may update editable contract fields such as requirements, implementationSteps, targets.routes/publicApiChanges, uiStates, interactions, mockApi.strategy/activation/endpoints, dependencyPolicy, stylingStrategy, uiComponentChoices, verificationTargets, evidenceGaps, residualRisks, and realIntegrationGap. It must not modify protected schemaVersion, sourceBinding, riskLevel, targets.files, or mockApi.productionDefaultOff. 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.",

package/dist/workflows/dag/node-execution.js

@@ -129,6 +129,26 @@ export function buildNodePrompt(spec, task, upstream, options) {
         convergenceFeedback: options?.convergenceFeedback,
     });
 }
+function frontendStructuredArtifactRetryGuidance(schemaId) {
+    if (schemaId === "frontend-implementation-contract-plan-patch-v1") {
+        return [
+            "Return exactly this artifact and nothing else: one short lead-in line, then exactly one fenced json block containing only the editable RFC 7386 plan patch, immediately followed by exactly one fenced openspec-citations block.",
+            "The runtime applies your patch to its protected contract skeleton. Do not emit schemaVersion, sourceBinding, riskLevel, targets.files, or mockApi.productionDefaultOff; do not emit the full contract.",
+            "Do not emit Markdown headings, bullets, plan prose, explanations, raw JSON, or any other fenced block.",
+        ];
+    }
+    if (schemaId === "frontend-implementation-contract-revision-patch-v1") {
+        return [
+            "Return exactly this artifact and nothing else: one short lead-in line, then exactly one fenced json block containing the RFC 7386 merge-patch delta, immediately followed by exactly one fenced openspec-citations block.",
+            "The delta contains only the fields you change; null deletes a key, arrays and scalars replace, and plain objects merge recursively. Do not emit a full contract or a schemaVersion/targets section.",
+            "Do not emit Markdown headings, bullets, plan prose, explanations, raw JSON, or any other fenced block.",
+        ];
+    }
+    return [
+        "Return exactly this artifact and nothing else: one short lead-in line, then exactly one fenced json block conforming to frontend-implementation-contract-v1, immediately followed by exactly one fenced openspec-citations block.",
+        "The contract JSON fields are the complete implementation plan. Do not emit a separate plan document, Markdown headings, bullets, plan prose, explanations, raw JSON, or any other fenced block.",
+    ];
+}
 function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCategory, previousProtocolReason, recoveryTargetPaths, recoveryDiagnostics) {
     if (attemptNumber <= 1)
         return basePrompt;
@@ -144,27 +164,14 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
     if (previousFailureCategory === "invalid-output" &&
         task.structuredContractOutput &&
         previousProtocolReason) {
-        // Revision nodes emit an RFC 7386 merge-patch delta (no schemaVersion /
-        // targets), so the retry instruction must not push them toward a full
-        // contract rewrite; plan nodes keep the strict v1 guidance.
-        const guidance = task.structuredContractOutput.schemaId ===
-            "frontend-implementation-contract-revision-patch-v1"
-            ? [
-                "Return exactly one fenced json object containing the RFC 7386 merge-patch delta against the original contract (null deletes a key; arrays and scalars replace; plain objects merge recursively) + exactly one openspec-citations block.",
-                "The delta contains only the fields you change; do not emit a full contract or a schemaVersion/targets section.",
-            ]
-            : [
-                "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.",
-            ];
         return [
             basePrompt,
             "",
             "<retry_instruction>",
             "Previous attempt produced an invalid frontend implementation contract:",
             previousProtocolReason,
-            ...guidance,
+            ...frontendStructuredArtifactRetryGuidance(task.structuredContractOutput.schemaId),
+            "Fix every reported field violation: do not emit null for optional fields, do not misspell field names, and match the required types exactly.",
             "</retry_instruction>",
         ].join("\n");
     }
@@ -175,9 +182,8 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
             "",
             "<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.",
+            ...frontendStructuredArtifactRetryGuidance(task.structuredContractOutput.schemaId),
+            "The JSON artifact must be complete; omit evidence excerpts and duplicated upstream context.",
             "</retry_instruction>",
         ].join("\n");
     }
@@ -246,6 +252,17 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
         return basePrompt;
     }
     if (task.outputMode === "structured-required") {
+        if (task.structuredContractOutput) {
+            return [
+                basePrompt,
+                "",
+                "<retry_instruction>",
+                "Previous attempt exceeded the structured output size limit.",
+                ...frontendStructuredArtifactRetryGuidance(task.structuredContractOutput.schemaId),
+                "Keep every required field but make values concise; omit evidence excerpts and duplicated upstream context.",
+                "</retry_instruction>",
+            ].join("\n");
+        }
         return [
             basePrompt,
             "",
@@ -792,6 +809,9 @@ export async function executeDagNode(input) {
                     runDir,
                     text: contractText,
                     sourceBinding: spec.sourceBinding,
+                    nodeId,
+                    attempt: attemptNumber,
+                    structuredContractOutput: task.structuredContractOutput,
                 });
                 if (!contractCheck.ok) {
                     // A provider stopReason=length means the response was cut before the
@@ -811,6 +831,13 @@ export async function executeDagNode(input) {
                     previousProtocolReason = contractCheck.reason;
                 }
                 else {
+                    if (contractCheck.normalizedText) {
+                        result = {
+                            ...result,
+                            assistantText: contractCheck.normalizedText,
+                            stdout: contractCheck.normalizedText,
+                        };
+                    }
                     previousProtocolReason = undefined;
                 }
             }

package/dist/workflows/dag/types.js

@@ -713,6 +713,7 @@ export const dagConvergenceSpecSchema = z
  */
 export const structuredContractOutputSchemaIds = [
     "frontend-implementation-contract-v1",
+    "frontend-implementation-contract-plan-patch-v1",
     "frontend-implementation-contract-revision-patch-v1",
 ];
 export const dagTaskSchema = z.object({ id: z.string().regex(/^[a-z][a-z0-9-]*$/, "task id must be kebab-case"),
@@ -775,8 +776,25 @@ export const dagTaskSchema = z.object({ id: z.string().regex(/^[a-z][a-z0-9-]*$/
         .object({
         schemaId: z.enum(structuredContractOutputSchemaIds),
         retryOnInvalid: z.boolean().default(true),
+        /**
+         * Optional deterministic base object for patch-producing structured
+         * nodes. The frontend plan patch validator applies the model delta to
+         * this run-owned skeleton before strict contract validation.
+         */
+        skeleton: z.record(z.string(), z.unknown()).optional(),
     })
         .strict()
+        .superRefine((value, ctx) => {
+        if (value.schemaId ===
+            "frontend-implementation-contract-plan-patch-v1" &&
+            !value.skeleton) {
+            ctx.addIssue({
+                code: "custom",
+                message: "frontend plan patch output requires a runtime skeleton",
+                path: ["skeleton"],
+            });
+        }
+    })
         .optional(),
     /**
      * Fail-closed outcome/diff consistency contract for bounded Pi writers.

package/package.json

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

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

@@ -6,14 +6,14 @@ 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, 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, 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 gate. `frontend-contract-json-pi`/`frontend-contract-json-validate-shell` don't exist; IDs+paths ≠ behavior semantics. Use `uiStates: []` for logic-only changes; don't invent UI states. Applicable states need behavior/implementation/verification; non-applicable need reasons. 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 = original plan; only `request-revision` runs revision+final review; small-risk = one review.
+- **`frontend-plan-pi` + conditional design loop**: AC → observable `expectedOutcome`; interactions → `trigger`+`expectedBehavior`; include steps, in-bound files, UI states, reuse, deps, Mock/API, frozen verify entrypoints and integration gaps. DAG freezes a protected skeleton (`schemaVersion`, `sourceBinding`, `riskLevel`, `targets.files`, `mockApi.productionDefaultOff`). Model returns a **JSON-only** editable RFC 7386 patch (`frontend-implementation-contract-plan-patch-v1`) plus one `openspec-citations` block. Runtime compiles canonical `frontend-implementation-contract-v1` and archives raw/extracted/normalized/validation candidates; unresolved optional symbols are dropped and audited. No plan prose; gate renders plan.md. IDs+paths ≠ behavior semantics. Applicable UI states need behavior/implementation/verification; non-applicable states need reasons. Active Mock needs frozen commands; `auto` without confirmed capability/command → `not-needed`; `required` without command → generation-time blocked. Only `request-revision` runs revision+final review; small-risk gets one review.
   - `uiComponentChoices[]` (optional): `{purpose, component, decision, specReference, rationale}`; `specified` needs `specReference{path,section,line}`; `new` needs null ref+rationale.
 - **`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; malformed primary fails closed. Generation-time blocked Mock yields one 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 read event → `openspec-citation-not-read` (anti-fabrication). Empty candidates skip enforcement. `scan-strict` keeps full-read semantics (`openspec-not-read`); both modes keep `candidate-missing-drift`.
   - Component conformance: missing `uiComponentChoices` (frozen bucket non-empty + UI-visible work) → `component-choices-missing`; bad/uncited `specReference.path` → `component-spec-reference-invalid` / `component-spec-not-cited`.
-  - 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`.
+  - revisionPatch mode: revision output is an RFC 7386 merge-patch delta applied on the original canonical contract node (`planFallbackFromNodeIds[0]`); protected skeleton paths remain immutable. 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 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)