@tea-agent/loop-agent 0.36.1 → 0.36.3-beta.0

package/CHANGELOG.md

@@ -1,6 +1,13 @@
 # 更新日志
 
-## [Unreleased]
+## [0.36.3-beta.0] - 2026-08-16
+
+> 前端 DAG Mock 治理收紧（beta，发布到 `beta` dist-tag）。
+
+### 改进
+
+- 前端 DAG 的 Mock 策略约束注入设计评审链：`mockContextBlock`（含冻结 allowlist 的「HARD CONSTRAINT」与修复路径）现在也注入 `frontend-design-review-pi` / `frontend-plan-revision-pi` / `frontend-final-design-review-pi`，消除「design-review 按项目规范要求 native、但生成期 allowlist 冻结为 not-needed、prewrite 硬阻断」的策略断环——评审链会明确提示这是生成期契约缺口（需声明 `frontendMock.verifyCommands` 或 `policy: "required"` 后重新生成 DAG）
+- 前端任务生成期 Mock 预警：新增 `DagSpec.advisories`，任务源提到接口/API/Mock 但 auto 模式把策略收窄为 `not-needed` 时，`task advance` 的 `warnings` 会给出可操作提示（声明 `frontendMock.verifyCommands` 或 `policy: required` 后重新生成 DAG），把契约缺口提前到生成期暴露
 
 ## [0.36.1] - 2026-08-16
 
@@ -13,6 +20,27 @@
 - move interrupt eligibility to observability to honor kernel import boundary
 - retry semantic intake across Pi tiers with 300s timeout
 
+## [0.36.1-beta.0] - 2026-08-16
+
+> 标准 DAG planner 输出超长紧凑重试（beta，发布到 `beta` dist-tag）。
+
+### 改进
+
+- 标准 DAG 的 planner 节点（`contract-pi` / `plan-pi`）输出超长（`output-too-large`）时自动紧凑重试：新增 `PLANNER_OUTPUT_LIMIT_RETRY_POLICY`（默认重试集合 + `output-too-large`），紧凑重试指令按节点类型区分——结构化契约节点只返回单个紧凑 JSON，普通计划节点返回最小计划（有序步骤、writeSet 边界、验证命令），并丢弃上游原文引用与长证据摘录
+
+## [0.35.4-beta.0] - 2026-08-15
+
+> frontend prewrite 阻断误路由修正 + Mock 契约文档落地（beta，发布到 `beta` dist-tag）。
+
+### 改进
+
+- prewrite 阻断导致的 writer `SKIPPED`（`skippedReason=frontend-prewrite-not-authorized`）失败路由从 `DependencyFailure`/`unblock dependency` 修正为 `ContractMismatch`/`fix-frontend-task-contract-and-regenerate-dag`；`dag report` / `dag doctor` 透传 `skippedReason`，对「Mock 策略契约缺陷需改 task.json + 重新生成 DAG」这类场景给出可操作建议，而非误导性的「解除依赖」
+
+### 文档
+
+- `docs/templates/frontend-task-constraints.md` 的 Mock 约束从 TODO 改为可落地契约：要求从项目**探索**实际存在的确定性 Mock 验证命令（不硬编码命令名）并声明到 `task.json.frontendMock.verifyCommands`，说明生成期 `allowedMockStrategies` 来源、`mock-strategy-outside-allowed` 是生成期契约问题（修复 = 补契约 + 重新生成 DAG，plan-revision 无法修复）
+- `docs/runtime/frontend-implementation-workflow.md` 的 task.json 输入标准补充 Mock 契约声明、命令探索与失败恢复指引
+
 ## [0.36.0] - 2026-08-15
 
 ### 新增

package/dist/build-stamp.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "version": "0.36.1",
-  "gitSha": "e023c82feae11ad8a6f5f9e50e8553cc38512f5e",
-  "builtAt": "2026-08-16T09:24:03.417Z"
+  "version": "0.36.3-beta.0",
+  "gitSha": "5baa4176d2b96e68c61f759934c6582911b4a42a",
+  "builtAt": "2026-08-16T11:51:43.878Z"
 }

package/dist/workflows/dag/failure-routing.js

@@ -44,7 +44,9 @@ function routeToProductLine(input) {
         case "decision-envelope":
             return "NeedsHuman";
         case "skipped":
-            return "DependencyFailure";
+            return input.skippedReason === "frontend-prewrite-not-authorized"
+                ? "ContractMismatch"
+                : "DependencyFailure";
         case "shell-command":
             if (/\b(ENOENT|PATH|command not found|No such file|not found in PATH|bash: .*: No such file)\b/i.test(raw)) {
                 return "EnvFailure";
@@ -90,9 +92,12 @@ export function routeDagFailure(input) {
     if (!productLineFailureCategory)
         return {};
     const recommendedFollowUp = productLineFailureCategory === "ContractMismatch" &&
-        isFrontendDesignGateNode(input.nodeId ?? "")
-        ? "frontend-plan-revision-and-rerun"
-        : FOLLOW_UP_BY_PRODUCT_LINE[productLineFailureCategory];
+        input.skippedReason === "frontend-prewrite-not-authorized"
+        ? "fix-frontend-task-contract-and-regenerate-dag"
+        : productLineFailureCategory === "ContractMismatch" &&
+            isFrontendDesignGateNode(input.nodeId ?? "")
+            ? "frontend-plan-revision-and-rerun"
+            : FOLLOW_UP_BY_PRODUCT_LINE[productLineFailureCategory];
     return {
         productLineFailureCategory,
         recommendedFollowUp,

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

@@ -9,7 +9,7 @@ import { planMavenVerification, } from "../../verification/maven/index.js";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
 import { BASELINE_FORBIDDEN_PATHS } from "./governance-constants.js";
 import { buildDecisionEnvelopePromptContract } from "./decision-envelope.js";
-import { DEFAULT_READ_ONLY_PI_RETRY_POLICY, PROTOCOL_AWARE_PI_RETRY_POLICY, STRUCTURED_REQUIRED_PI_RETRY_POLICY, BACKEND_TEST_WRITER_COMPLETENESS_RETRY_POLICY, WRITER_TRANSPORT_RETRY_POLICY, isSafeReadOnlyPiRetryCandidate, isWriterTransportRetryCandidate, } from "./retry-policy.js";
+import { DEFAULT_READ_ONLY_PI_RETRY_POLICY, PLANNER_OUTPUT_LIMIT_RETRY_POLICY, PROTOCOL_AWARE_PI_RETRY_POLICY, STRUCTURED_REQUIRED_PI_RETRY_POLICY, BACKEND_TEST_WRITER_COMPLETENESS_RETRY_POLICY, WRITER_TRANSPORT_RETRY_POLICY, isSafeReadOnlyPiRetryCandidate, isWriterTransportRetryCandidate, } from "./retry-policy.js";
 import { REVIEW_JSON_VERDICT_OUTPUT_PROTOCOL, REVIEW_VERDICT_OUTPUT_PROTOCOL, } from "./output-protocol.js";
 import { resolveAdapter } from "../../adapters/index.js";
 import { loadHarnessManifest } from "../../governance/harness.js";
@@ -558,6 +558,39 @@ export function hasApiDependency(sources) {
         .some((clause) => !negationPatterns.some((pattern) => pattern.test(clause)) &&
         dependencyPatterns.some((pattern) => pattern.test(clause)));
 }
+/**
+ * Generation-time heuristic: does the task source mention interface/API/Mock
+ * needs anywhere (requirement or constraints)?
+ *
+ * Mirrors hasApiDependency's clause-level negation filtering so explicit
+ * "not involved / not implementing" clauses and out-of-scope sections do not
+ * become positive evidence. Used to emit a machine-visible advisory when auto
+ * mode narrows Mock to not-needed despite the source mentioning such needs.
+ */
+export function frontendSourceMentionsMock(sources) {
+    const text = [sources.requirementMarkdown, sources.constraintMarkdown]
+        .filter((entry) => typeof entry === "string" && entry.trim().length > 0)
+        .map((entry) => normalizeTaskRequirementText(entry).replace(/`[^`\n]*`/g, " "))
+        .join("\n");
+    const signalPatterns = [
+        /mock/i,
+        /模拟服务/,
+        /接口桩/,
+        /\bmsw\b/i,
+        /(?<![A-Za-z0-9_])API(?![A-Za-z0-9_])/i,
+        /接口/,
+    ];
+    const negationPatterns = [
+        /(?:不涉及|无需|不需要|不依赖|不调用|不请求|不实现|没有|禁止|不得).{0,16}(?:接口|后端|服务端|远程数据|异步数据|API|mock|模拟|桩)/i,
+        /\b(?:no|without|does\s+not|do\s+not|must\s+not)\b.{0,24}\b(?:api|endpoint|request|backend|server|mock)\b/i,
+    ];
+    return text
+        .split(/[。！？!?；;，,\r\n]+/)
+        .map((clause) => clause.trim())
+        .filter(Boolean)
+        .some((clause) => !negationPatterns.some((pattern) => pattern.test(clause)) &&
+        signalPatterns.some((pattern) => pattern.test(clause)));
+}
 /**
  * Resolve frontend Mock mode from capability seed, task config, and interface dependency analysis.
  *
@@ -2111,6 +2144,7 @@ function resolveFrontendMockContextBlock(sources) {
         parts.push("Generation-time evidence does not require Mock. The assessment must still use contract/scout evidence: select not-needed when Mock is intentionally skipped, or select a safe Mock strategy if project evidence supports one.");
         if (frontendMockStrategyMustBeNotNeeded(sources)) {
             parts.push('Auto mode has no confirmed project Mock capability or no deterministic Mock verification command. The structured contract must set mockApi.strategy to "not-needed". Do not add Mock files or dependencies; keep the real request path as default and record any unproved backend behavior as Real Integration Gap.');
+            parts.push('HARD CONSTRAINT (frozen at generation time): this DAG allows only mockApi.strategy "not-needed"; the prewrite gate rejects any other strategy. If project governance (openspec / ai_workspace / decision records, e.g. a DEC rule requiring native) demands Mock-backed verification, that is a generation-time contract gap, not a plan-revision defect: declare frontendMock.verifyCommands (or policy: "required") in task.json and regenerate the DAG. Do not emit any mockApi.strategy outside the allowlist and do not add Mock files or dependencies within this run.');
         }
     }
     if (mode === "blocked") {
@@ -2509,6 +2543,11 @@ async function buildFrontendHybridDagFromTask(sources) {
         `- Behavior command source: ${behaviorVerifyEvidence.commandSource}`,
         ...behaviorVerifyEvidence.commandLabels.map((command) => `  - ${JSON.stringify(command)}`),
     ].join("\n");
+    const advisories = [];
+    if (frontendSourceMentionsMock(frontendSources) &&
+        frontendMockStrategyMustBeNotNeeded(frontendSources)) {
+        advisories.push("auto 模式已将 Mock 策略收窄为 not-needed：任务源提到接口/API/Mock 需求，但仓库无确认 Mock 能力或无确定性 Mock 验证命令。若项目规范要求 Mock，请声明 frontendMock.verifyCommands 或 policy:required 后重新生成 DAG。");
+    }
     const spec = {
         version: 3,
         title: `Frontend implementation DAG: ${taskConfig.title}`,
@@ -2523,6 +2562,7 @@ async function buildFrontendHybridDagFromTask(sources) {
         skillsByRole: FRONTEND_SKILLS_BY_ROLE,
         executorModels: sources.executorModelMatrix ?? DEFAULT_DAG_EXECUTOR_MODELS,
         verifyStrategy: resolveDagVerifyStrategy(taskConfig),
+        advisories: advisories.length > 0 ? advisories : undefined,
         tasks: [
             {
                 id: "frontend-contract-pi",
@@ -2617,6 +2657,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                     "Read-only: do not modify repository files.",
                     fixedVerificationContext,
                     sourceContext,
+                    mockContextBlock,
                 ].join("\n\n"),
             },
             {
@@ -2651,6 +2692,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                     fixedVerificationContext,
                     sourceContext,
                     frontendContractSchemaBlock,
+                    mockContextBlock,
                 ].join("\n\n"),
             },
             {
@@ -2681,6 +2723,7 @@ async function buildFrontendHybridDagFromTask(sources) {
                     "Read-only: do not modify repository files.",
                     fixedVerificationContext,
                     sourceContext,
+                    mockContextBlock,
                 ].join("\n\n"),
             },
             {
@@ -5783,7 +5826,9 @@ function applyDefaultReadOnlyRetryPolicy(spec) {
         if (isSafeReadOnlyPiRetryCandidate(task)) {
             task.retryPolicy = task.outputProtocol
                 ? PROTOCOL_AWARE_PI_RETRY_POLICY
-                : DEFAULT_READ_ONLY_PI_RETRY_POLICY;
+                : task.role === "planner"
+                    ? PLANNER_OUTPUT_LIMIT_RETRY_POLICY
+                    : DEFAULT_READ_ONLY_PI_RETRY_POLICY;
             continue;
         }
         if (isWriterTransportRetryCandidate(task)) {

package/dist/workflows/dag/lifecycle.js

@@ -743,6 +743,7 @@ function findDoctorFailureNode(state) {
             nodeId: state.pausedByNodeId,
             status: node?.status,
             rawFailureCategory: node?.failureCategory,
+            skippedReason: node?.skippedReason,
         };
     }
     const errorEntry = Object.entries(state.nodes).find(([, node]) => node.status === "ERROR");
@@ -758,6 +759,7 @@ function findDoctorFailureNode(state) {
         nodeId: selected[0],
         status: selected[1].status,
         rawFailureCategory: selected[1].failureCategory,
+        skippedReason: selected[1].skippedReason,
     };
 }
 async function readRunOwnedBackendTestClassification(runDir) {
@@ -786,6 +788,7 @@ async function resolveDoctorFailureRouting(input) {
             normalizedFailureCategory: "unknown",
             nodeId: input.nodeId,
             productLineFailureCategory: classifiedCategory,
+            skippedReason: input.skippedReason,
         });
     }
     return routeDagFailure(input);
@@ -807,6 +810,7 @@ async function formatDagDoctorMarkdown(repoRoot, runId) {
         rawFailureCategory,
         normalizedFailureCategory: normalizedCategory,
         nodeId: failure.nodeId,
+        skippedReason: failure.skippedReason,
     });
     const evidence = failure.nodeId
         ? path.join(located.runDir, failure.nodeId, "result.summary.md")

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

@@ -216,18 +216,28 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
             "</retry_instruction>",
         ].join("\n");
     }
-    if (task.outputMode !== "structured-required" ||
-        previousFailureCategory !== "output-too-large") {
+    if (previousFailureCategory !== "output-too-large") {
         return basePrompt;
     }
+    if (task.outputMode === "structured-required") {
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "Previous attempt exceeded the structured output size limit.",
+            "Return only the compact structured artifact required by this node's output contract.",
+            "Do not include explanatory prose, duplicated upstream context, long evidence excerpts, or additional markdown sections.",
+            "If a fenced JSON object is required, output exactly one fenced json block and nothing else.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
     return [
         basePrompt,
         "",
         "<retry_instruction>",
-        "Previous attempt exceeded the structured output size limit.",
-        "Return only the compact structured artifact required by this node's output contract.",
-        "Do not include explanatory prose, duplicated upstream context, long evidence excerpts, or additional markdown sections.",
-        "If a fenced JSON object is required, output exactly one fenced json block and nothing else.",
+        "Previous attempt exceeded the output size limit.",
+        "Return a minimal plan: ordered steps, narrow writeSet boundaries, and verification commands.",
+        "Drop verbatim upstream quotes, long evidence excerpts, and repeated context.",
         "</retry_instruction>",
     ].join("\n");
 }

package/dist/workflows/dag/report.js

@@ -441,6 +441,7 @@ export async function buildDagRunReportEntry(input) {
                 normalizedFailureCategory,
                 nodeId,
                 executor: node.executor,
+                skippedReason: node.skippedReason,
             });
             const followUp = node.status === "ERROR" || node.status === "SKIPPED"
                 ? recommendFollowUpForFailureCategory(node.failureCategory)
@@ -505,6 +506,7 @@ export async function buildDagRunReportEntry(input) {
             normalizedFailureCategory: normalizeDagFailureCategory(pausedNode.failureCategory, pausedNode.status),
             failureCategory: pausedNode.failureCategory,
             nodeId: input.state.pausedByNodeId,
+            skippedReason: pausedNode.skippedReason,
         }
         : firstActionableNode
             ? {
@@ -513,6 +515,7 @@ export async function buildDagRunReportEntry(input) {
                     normalizeDagFailureCategory(firstActionableNode.failureCategory, firstActionableNode.status),
                 failureCategory: firstActionableNode.failureCategory,
                 nodeId: firstActionableNode.nodeId,
+                skippedReason: input.state.nodes[firstActionableNode.nodeId]?.skippedReason,
             }
             : {
                 status: input.state.status,
@@ -529,6 +532,9 @@ export async function buildDagRunReportEntry(input) {
         rawFailureCategory: runRecoverySource.failureCategory,
         normalizedFailureCategory: runRecoverySource.normalizedFailureCategory,
         nodeId: "nodeId" in runRecoverySource ? runRecoverySource.nodeId : undefined,
+        skippedReason: "skippedReason" in runRecoverySource
+            ? runRecoverySource.skippedReason
+            : undefined,
     });
     const runFollowUp = input.state.status === "failed" ||
         input.state.status === "partial_failed"

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

@@ -118,6 +118,17 @@ export const STRUCTURED_REQUIRED_PI_RETRY_POLICY = {
     ...DEFAULT_READ_ONLY_PI_RETRY_POLICY,
     retryCategories: [...STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES],
 };
+/**
+ * Planner read-only nodes (standard DAG contract-pi / plan-pi) may retry with
+ * a compact-output instruction when the model produced an oversized assistant
+ * response. Only `output-too-large` is added on top of the default set;
+ * report/review and other read-only roles keep the default set so they do not
+ * silently learn new output semantics.
+ */
+export const PLANNER_OUTPUT_LIMIT_RETRY_POLICY = {
+    ...DEFAULT_READ_ONLY_PI_RETRY_POLICY,
+    retryCategories: [...DEFAULT_DAG_RETRY_CATEGORIES, STRUCTURED_OUTPUT_RETRY_CATEGORY],
+};
 /**
  * Default retry for reviewer / recovery nodes that declare outputProtocol.
  * Includes protocol-invalid so missing VERDICT lines are corrected in-node.

package/dist/workflows/dag/types.js

@@ -822,6 +822,8 @@ export const dagSpecSchema = z
     defaults: dagDefaultsSchema,
     skillsByRole: z.record(z.string(), z.array(z.string())).optional(),
     executorModels: dagExecutorModelsSchema.optional(),
+    /** Generation-time advisories surfaced as machine-visible warnings. */
+    advisories: z.array(z.string()).optional(),
     tasks: z.array(dagTaskSchema).min(1),
 })
     .superRefine((spec, ctx) => {

package/dist/workflows/dag/validate.js

@@ -14,6 +14,7 @@ const GOVERNANCE_WARNING_TYPES = new Set([
     "shell-verdict-gate-multi-command-state",
     "shell-verdict-gate-handwritten-inline",
     "orphan-writer-source-binding",
+    "advisory",
 ]);
 const ROOT_ARTIFACT_PATH_PROBES = [
     "artifacts/修改记录.md",
@@ -32,10 +33,11 @@ export function collectGovernanceWarnings(issues) {
     return issues.filter(isGovernanceWarning);
 }
 function collectBlockingIssues(issues, options = {}) {
+    const nonAdvisory = issues.filter((issue) => issue.type !== "advisory");
     if (options.strictGovernance) {
-        return [...issues];
+        return nonAdvisory;
     }
-    return issues.filter((issue) => !isGovernanceWarning(issue));
+    return nonAdvisory.filter((issue) => !isGovernanceWarning(issue));
 }
 function normalizePath(value) {
     return value.replace(/\\/g, "/").replace(/^\.\//, "");
@@ -956,6 +958,9 @@ export function validateDagSpec(spec) {
     validateSameRankWriteSetConflicts(spec, ranks, issues);
     validateSameRankAgentAttributionRisks(spec, ranks, issues);
     validateWriterSourceBinding(spec, issues);
+    for (const advisory of spec.advisories ?? []) {
+        issues.push({ type: "advisory", message: advisory });
+    }
     return issues;
 }
 function validateProjectGovernanceTaskConfig(task, spec, issues) {

package/docs/templates/frontend-task-constraints.md

@@ -18,13 +18,19 @@ TODO
 
 ## Mock 约束（数据型任务）
 
-- Mock/API/schema 规范路径：TODO
-- 既有 Mock service root、handler/fixture/bootstrap：TODO
-- 既有 browser/e2e interception 或 request adapter/DI seam：TODO
-- 启动、健康检查和专项验证命令：TODO
-- production 禁用边界：TODO
-- 真实请求默认路径与 Mock 显式启用方式：TODO
-- `task.json.frontendMock.policy`：`auto | required | disabled`
+本段决定生成期 `allowedMockStrategies` 与冻结的 Mock 验证命令。只有当生成期**能证明任务确实包含 Mock 且有确定性验证命令**时，DAG 才会放行 `native` / `browser-intercept` / `request-adapter`；否则自动收敛为 `not-needed`，design review 若按项目规范改选 `native`，会在 prewrite 被 `mock-strategy-outside-allowed` 拦截、`implement` 被跳过。
+
+- **何时必须填**：项目规范（`openspec/project-specs/**`、`ai_workspace/**`、mock 规则或类似 DEC-* 决策）要求/建议 Mock；或需求涉及远端接口且后端未就绪。规范要求 Mock 时，优先 `task.json.frontendMock.policy: "required"`。
+- **命令要探索、不要硬编码**：到项目 `package.json` scripts 里找实际存在的 Mock 相关脚本（如 `mock`、`mock:*`、`dev:mock`，或名字含 mock 的脚本），结合既有 service root 的 handler/fixture/bootstrap 启动方式，确定一条**真实存在、确定、可自终止**（启动→断言→退出 0）的验证命令。常驻 dev server 必须包装成自终止脚本（start→assert→stop），否则 verify shell 会超时 fail-closed。
+- **写入 task.json**：把探索到的命令原样写进 `frontendMock.verifyCommands`（`label` 唯一、`command` 与项目脚本一致）。`label` 会进入冻结命令集，implementation contract 的 `verificationTarget.commandLabel` 必须逐字引用它。
+- **命令来源白名单**：只允许项目 `package.json` 已有脚本、Mock capability seed、或本段声明的 `verifyCommands`；plan/design 阶段不能发明 shell 命令。
+- **Mock/API/schema 规范路径**：TODO
+- **既有 Mock service root、handler/fixture/bootstrap**：TODO
+- **既有 browser/e2e interception 或 request adapter/DI seam**：TODO
+- **production 禁用边界**：TODO
+- **真实请求默认路径与 Mock 显式启用方式**：TODO
+- **`task.json.frontendMock.policy`**：`auto | required | disabled`（规范强制 Mock 用 `required`）
+- **被拦截时怎么修**：`mock-strategy-outside-allowed` / `no authorized Mock verification commands` 是**生成期契约问题，不是 plan 问题**——补 `frontendMock.verifyCommands`（或 `policy: "required"` + 命令）后**重新生成 DAG** 再跑，plan-revision 无法修复它。
 
 ## allowedPaths
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.36.1",
+  "version": "0.36.3-beta.0",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",