@tea-agent/loop-agent 0.38.0 → 0.38.1

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

@@ -144,14 +144,40 @@ 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,
-            "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.",
+            ...guidance,
+            "</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");
     }
@@ -216,18 +242,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");
 }
@@ -758,10 +794,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/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

@@ -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,
@@ -118,6 +122,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

@@ -171,6 +171,9 @@ export const dagJsonArtifactGateSchema = z.object({
 const dagFrontendNodeIdSchema = z
     .string()
     .regex(/^[a-z][a-z0-9-]*$/, "frontend node id must be kebab-case");
+const openspecCandidatePathSchema = z
+    .string()
+    .refine((candidate) => !candidate.includes("\\") && isOpenspecSpecFilePath(candidate), "openspec candidate must be a repo-relative supported file under openspec/schemas/, openspec/project-specs/, or ai_workspace/");
 export const dagFrontendPrewriteGateSchema = z.object({
     schemaVersion: z.literal(1),
     planFromNodeId: dagFrontendNodeIdSchema,
@@ -189,11 +192,51 @@ export const dagFrontendPrewriteGateSchema = z.object({
     outputDir: z.string().regex(/^[a-z0-9][a-z0-9._-]*$/),
     requireSourceFreshness: z.literal(true),
     implementationWriteSet: z.array(z.string().min(1)).min(1).optional(),
-    openspecCandidatePaths: z
-        .array(z
+    openspecCandidatePaths: z.array(openspecCandidatePathSchema).default([]),
+    /**
+     * Generation-frozen component/theme specification bucket. Derived from
+     * `designEvidence.classified.component ∪ theme ∪ rule.components` at DAG
+     * generation. When non-empty and the canonical contract has UI-visible
+     * work, the prewrite gate requires a non-empty `uiComponentChoices` and
+     * cross-checks each `specReference.path` against this set + the effective
+     * plan openspec-citations block. Legacy DAGs without this field keep the
+     * field-absent semantics (component-choices-missing is not enforced).
+     */
+    componentSpecCandidatePaths: z.array(openspecCandidatePathSchema).optional(),
+    /**
+     * OpenSpec gate policy. Omitted on legacy DAGs: the runtime treats
+     * undefined as scan-strict so pre-existing full-read semantics are
+     * 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()
-        .refine((candidate) => !candidate.includes("\\") && isOpenspecSpecFilePath(candidate), "openspec candidate must be a repo-relative supported file under openspec/schemas/ or openspec/project-specs/"))
-        .default([]),
+        .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
+     * scanStrict (auto-discovered designEvidence.normativePaths).
+     */
+    openspecCandidateSources: z
+        .object({
+        declared: z.array(openspecCandidatePathSchema).default([]),
+        taskSourceCited: z.array(openspecCandidatePathSchema).default([]),
+        scanStrict: z.array(openspecCandidatePathSchema).default([]),
+    })
+        .optional(),
 });
 export const dagFrontendLintBaselineSchema = z
     .object({
@@ -661,6 +704,7 @@ export const dagConvergenceSpecSchema = z
  */
 export const structuredContractOutputSchemaIds = [
     "frontend-implementation-contract-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"),
     depends_on: z.array(z.string()).default([]),
@@ -822,6 +866,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-design-contract.md

@@ -1,42 +1,68 @@
 # 前端设计契约模板
 
+本模板只承载**通用编写协议 + 三要素 + fail-closed 规则**，不包含任何具体业务组件名、项目专属路径或项目专属命令。设计契约在进入实现前由 `frontend-plan-pi` 落入结构化 implementation contract，`frontend-design-review-pi` 按本模板逐节审查；每一节都要给出「**要写什么** / **DAG 如何消费** / **缺失/冲突时 fail-closed**」三要素。
+
 ## 页面目标
 
-TODO
+- **要写什么**：写清每个目标页面的职责、用户到达该页面的目的与成功结果，逐页列出，与需求.md 的用户目标/目标页面一一对应。
+- **DAG 如何消费**：`frontend-plan-pi` 据它确定 `targets.routes` 与每页的实现步骤，`frontend-design-review-pi` 据它核对范围与需求一致性。
+- **缺失/冲突时 fail-closed**：页面目标与需求不一致、缺页或目标含糊（无成功结果）时阻塞，不得自行补页或改目标。
 
 ## 信息结构
 
-TODO
+- **要写什么**：写清每页展示的信息层级与数据来源（字段、分组、优先级、空/错误占位），接口数据与静态文案分开写。
+- **DAG 如何消费**：`frontend-plan-pi` 据它安排组件数据流与状态展示，`frontend-design-review-pi` 据它核对接口字段映射。
+- **缺失/冲突时 fail-closed**：信息层级缺失、数据来源不可追溯、与接口字段冲突时阻塞，不得臆造字段或层级。
 
 ## 组件拆分
 
-TODO
+- **要写什么**：把页面拆成组件树，逐组件写职责、复用边界、props/状态归属与可替换点；复用现有设计系统组件时引用其来源路径。
+- **DAG 如何消费**：`frontend-plan-pi` 据它确定 `targets.files` 与实现顺序，`frontend-design-review-pi` 据它审查拆分是否越界/重复。
+- **缺失/冲突时 fail-closed**：组件边界不清、同一职责被拆到多处、或与设计规范冲突时阻塞，不得按邻近代码自行决定复用。
 
 ## 交互规则
 
-TODO
+- **要写什么**：逐条写清每个交互的触发、预期行为、状态变化与可恢复性（对应需求.md 的交互要求）。
+- **DAG 如何消费**：`frontend-plan-pi` 据它填充 `interactions[]`（`trigger` + `expectedBehavior`），verify 用行为命令断言。
+- **缺失/冲突时 fail-closed**：交互无预期行为、与 UI 状态冲突、或不可自动化断言时阻塞。
 
 ## UI 状态
 
-TODO
+- **要写什么**：逐状态（loading/empty/error/success/disabled）写清触发条件、展示内容与转移；不适用状态写 `N/A` + 非空理由。
+- **DAG 如何消费**：进入 implementation contract 的 `uiStates[]`，verify 逐状态断言，`frontend-review-pi` 据它核对实现是否遗漏状态。
+- **缺失/冲突时 fail-closed**：适用状态缺失预期、N/A 无理由、或状态展示与交互/接口状态冲突时阻塞。
 
 ## Mock / API 策略
 
-- 接口文档或 schema：TODO
-- 策略：`native | browser-intercept | request-adapter | not-needed | blocked`
-- endpoint / fixture / UI 状态映射：TODO
-- 显式启用方式与 production 默认关闭边界：TODO
-- DAG 已固化的验证入口：TODO
-- Real Integration Gap 与后端就绪后的复验：TODO
+策略枚举固定为 `native | browser-intercept | request-adapter | not-needed | blocked`，与 runtime Mock 语义一致：`blocked` 永远不通过（缺少/冲突接口契约、路径或依赖未授权、无法证明生产默认关闭、固定验证入口无法覆盖、或唯一方案是注释真实请求时必须选它）；`not-needed` 必须有后端可用或任务不涉及远程接口的真实/无远程证据，且固定 behavior 入口能覆盖相应行为；显式 `policy=required` 不接受 `not-needed`。契约只接受当前 policy 允许的非 `blocked` 首行。
+
+- **接口文档或 schema — 要写什么**：引用接口文档/schema 路径与版本，作为 fixture 与字段映射的唯一来源。**DAG 如何消费**：`frontend-plan-pi` 据它冻结 endpoint/fixture 映射，prewrite gate 校验 fixture 可追溯。**缺失/冲突时 fail-closed**：无文档/schema、字段冲突时选 `blocked`，不得自行发明接口。
+- **策略**：只写枚举中的一个值：`native | browser-intercept | request-adapter | not-needed | blocked`。
+- **endpoint / fixture / UI 状态映射 — 要写什么**：逐 endpoint 列 method、path、fixture 路径与消费组件，并映射到 UI 状态。**DAG 如何消费**：写入 `mockApi.endpoints[]`（method/path/fixture/consumer），非 `not-needed` 策略要求每个 endpoint 都有 fixture 与 consumer。**缺失/冲突时 fail-closed**：非 `not-needed` 却缺 fixture/consumer、endpoint 与 UI 状态映射不一致时阻塞。
+- **显式启用方式与 production 默认关闭边界 — 要写什么**：写清真实请求为默认路径、Mock 仅通过显式开关（环境变量/构建开关）启用的具体边界。**DAG 如何消费**：`productionDefaultOff` 恒为 `true`，`frontend-review-pi` 检查是否注释真实请求或默认开启 Mock。**缺失/冲突时 fail-closed**：无法证明生产默认关闭、或 Mock 会进入生产入口时选 `blocked`。
+- **DAG 已固化的验证入口 — 要写什么**：引用 DAG 生成时已冻结的 static/behavior/Mock 命令 label，不发明新命令。**DAG 如何消费**：`verificationTarget.commandLabel` 必须逐字落在冻结命令集合内，否则 contract 物化 `invalid-output`。**缺失/冲突时 fail-closed**：策略需要 Mock 验证命令却没有冻结命令时生成期 fail-closed（`no authorized Mock verification commands`）。
+- **Real Integration Gap 与后端就绪后的复验 — 要写什么**：写清当前未联通的真实集成缺口，以及后端就绪后的复验路径。**DAG 如何消费**：进入 `evidenceGaps[]`，closeout 报告 `Real integration: pending`，复验任务 `<task-id>-real-api-integration-verify` 由操作者显式触发。**缺失/冲突时 fail-closed**：把 Mock 证据当真实联调证据时 review 拒绝。
 
 ## 样式与设计系统映射
 
-TODO
+- **要写什么**：写清页面用到的主题/Token、设计系统组件与样式来源（引用具体来源路径），自定义样式与复用样式的边界。
+- **DAG 如何消费**：`frontend-plan-pi` 据它安排样式实现，`frontend-design-review-pi` 据它核对是否与设计系统冲突。
+- **缺失/冲突时 fail-closed**：样式来源缺失、Token/组件冲突、或自定义样式会破坏设计系统时阻塞。
 
 ## 响应式范围
 
-TODO
+- **要写什么**：写清支持的视口范围（desktop/mobile/tablet）与断点、每个断点下的布局差异。
+- **DAG 如何消费**：进入 contract 的 target runtime environment，`frontend-plan-pi` 据它决定响应式策略。
+- **缺失/冲突时 fail-closed**：视口范围与需求运行环境不一致、或断点未覆盖声明环境时阻塞。
 
 ## 风险与非目标
 
-TODO
+- **要写什么**：写清设计上的已知风险、依赖缺口与明确不做/排除的设计范围。
+- **DAG 如何消费**：进入 `evidenceGaps[]` 与 Non-goals，`frontend-review-pi`/closeout 据它保留风险与后续项。
+- **缺失/冲突时 fail-closed**：范围与需求非目标冲突、或风险被隐藏时阻塞。
+
+## OpenSpec 引用块（openspec-citations）
+
+- **要写什么**：在 fenced `json` 契约块之后追加**恰好一个** fenced `openspec-citations` 块，每行一个 JSON `{"path","section","line"}`（`section` 可空串、`line` 为 int 或 null），逐条列出本计划实际读取并应用的每个 openspec 规范文件。
+- **DAG 如何消费**：`frontend-prewrite-gate-shell` 按 fence 语言标签解析该块，并与生效 plan/review 节点的成功 read 事件核验；`cited` 模式下候选未引用 → `openspec-not-cited`，引用无 read 背书 → `openspec-citation-not-read`，块缺失/不可解析 → `openspec-citation-block-unparseable`。
+- **缺失/冲突时 fail-closed**：候选非空而引用块缺失/不可解析、候选未引用、或引用未真实读取时，prewrite gate 以 `retryable-invalid` fail-closed；不要引用未读取的路径，也不要遗漏已读取的 openspec 文件。

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

@@ -16,13 +16,20 @@
     "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 },
+    "uiComponentChoices": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["purpose", "component", "decision", "rationale"], "properties": { "purpose": { "type": "string", "minLength": 1 }, "component": { "type": "string", "minLength": 1 }, "decision": { "enum": ["specified", "reuse-existing", "new"] }, "specReference": { "anyOf": [{ "$ref": "#/$defs/uiComponentSpecReference" }, { "type": "null" }] }, "rationale": { "type": "string", "minLength": 1 } }, "allOf": [ { "if": { "properties": { "decision": { "const": "specified" } }, "required": ["decision"] }, "then": { "required": ["specReference"], "properties": { "specReference": { "$ref": "#/$defs/uiComponentSpecReference" } } } }, { "if": { "properties": { "decision": { "const": "new" } }, "required": ["decision"] }, "then": { "properties": { "specReference": { "type": "null" } } } } ] } },
+    "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": {
     "path": { "type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\).+$" },
     "requirementId": { "type": "string", "pattern": "^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$" },
     "gap": { "type": "object", "additionalProperties": false, "required": ["description", "blocking"], "properties": { "requirementId": { "$ref": "#/$defs/requirementId" }, "description": { "type": "string", "minLength": 1 }, "blocking": { "type": "boolean" } } },
-    "sourceBinding": { "type": "object", "additionalProperties": false, "required": ["taskId", "requirementPath", "requirementSha256", "referencePaths", "requirementIds"], "properties": { "taskId": { "type": "string", "minLength": 1 }, "requirementPath": { "$ref": "#/$defs/path" }, "requirementSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "referencePaths": { "type": "array", "items": { "$ref": "#/$defs/path" } }, "requirementIds": { "type": "array", "items": { "$ref": "#/$defs/requirementId" } } } }
+    "sourceBinding": { "type": "object", "additionalProperties": false, "required": ["taskId", "requirementPath", "requirementSha256", "referencePaths", "requirementIds"], "properties": { "taskId": { "type": "string", "minLength": 1 }, "requirementPath": { "$ref": "#/$defs/path" }, "requirementSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "referencePaths": { "type": "array", "items": { "$ref": "#/$defs/path" } }, "requirementIds": { "type": "array", "items": { "$ref": "#/$defs/requirementId" } } } },
+    "uiComponentSpecReference": { "type": "object", "additionalProperties": false, "required": ["path", "section"], "properties": { "path": { "$ref": "#/$defs/path" }, "section": { "type": "string" }, "line": { "anyOf": [{ "type": "integer" }, { "type": "null" }] } } }
   }
 }

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

@@ -1,35 +1,62 @@
 # 前端任务执行约束模板
 
+本模板只承载**通用探索协议 + 结果 schema + 缺失/冲突时 fail-closed 规则**，不包含任何具体业务组件名、项目专属路径或项目专属命令。项目事实由生成期能力探测（`openspec/schemas/**`、`openspec/project-specs/**`、`ai_workspace/**`）产出并经语义归类注入任务契约。
+
 ## 技术约束
 
-TODO
+- **要探索什么**：项目 `package.json` 的直接依赖与 scripts、框架/路由/状态/数据获取/组件库/样式/测试/构建相关配置与引导文件，以及 `openspec/schemas/**` 与 `openspec/project-specs/rules/**` 中声明技术边界的规范。
+- **结果必须包含**：每一条适用技术规则的源路径、命中章节与行号；被排除依赖的明确理由；与既有技术栈一致的运行时要求（编译、构建、入口、环境变量）。
+- **缺失/冲突时如何 fail-closed**：无法找到技术规范来源时，显式标注 `source: unavailable` 并只采用任务源与现有代码的可验证事实；发现冲突规则时不臆造取舍，先记录冲突并返回 `request-revision`/blocked，而不是静默采用邻近代码惯例。
 
 ## 代码风格约束
 
-TODO
+- **要探索什么**：`openspec/project-specs/templates/**`（代码模板）与 `openspec/project-specs/rules/**` 中组件/钩子/工具等代码风格规则，以及现有组件、主题/Token、stories 与测试作为较弱 repository fallback。
+- **结果必须包含**：命中模板/规则的源路径、章节与行号；命名、目录、导出、类型、样式组织等可执行约定；冲突字段逐条列出。
+- **缺失/冲突时如何 fail-closed**：没有模板/规则命中时明确说明并记录 `repository fallback` 证据；冲突未解决时不得进入实现，必须返回阻塞信息。
 
 ## 设计约束
 
-TODO
+- **要探索什么**：`openspec/project-specs/ui/**`（主题/组件目录）与 `openspec/project-specs/rules/**` 中页面/组件拆分、交互、UI 状态与响应式相关规则。
+- **结果必须包含**：命中设计规范/组件目录的源路径、章节与行号；组件拆分与复用边界、样式与设计系统映射、UI 状态与响应式范围。
+- **缺失/冲突时如何 fail-closed**：设计规范缺失时明确记录来源为 `unavailable` 并保留为已知风险；组件/主题冲突时必须阻断，不能按邻近代码自行决定。
 
 ## 验证约束
 
-TODO
+- **要探索什么**：项目 `package.json` scripts 中真实存在的 lint/typecheck/build/test 命令，以及任务源 `需求.md`/`执行约束.md` 中声明的验证命令。
+- **结果必须包含**：命令的 label、原始命令文本与来源（scripts/任务源）；每条命令可自终止（启动→断言→退出）的说明。
+- **缺失/冲突时如何 fail-closed**：只在确定命令真实存在时写入冻结命令集；不发明 shell 命令。命令不可执行或漂移时 fail closed，不宣称验证通过。
 
 ## 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 规范路径**：到 `openspec/project-specs/**`（rules 中的 mock/api 规则、templates 中的接口模板）与 `ai_workspace/**` 检索；结果必须列出源路径、章节与行号。缺失或冲突时 fail closed，不自行发明接口契约。
+- **既有 Mock service root、handler/fixture/bootstrap**：检索项目现有 Mock 服务根目录、handler、fixture 与 bootstrap 启动方式；结果必须列出发现路径，未发现时明确记录 `unavailable`。
+- **既有 browser/e2e interception 或 request adapter/DI seam**：检索项目现有浏览器/e2e 拦截或请求适配层/依赖注入 seam；结果必须列出发现路径或明确记录缺失。
+- **production 禁用边界**：结果必须说明真实请求为默认路径、Mock 仅通过显式测试/开发开关启用的具体边界；无法证明生产默认关闭时返回 `blocked`。
+- **真实请求默认路径与 Mock 显式启用方式**：结果必须写出真实请求默认路径与 Mock 显式启用方式（如环境变量/构建开关），不得通过注释真实请求或在生产组件内硬编码假数据实现。
+- **`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
 
-TODO
+- **要探索什么**：任务源 `需求.md`/`执行约束.md`/`task.json` 中声明的写入边界，以及本次交付实际涉及的文件/目录。
+- **结果必须包含**：与 `task.json.allowedPaths` 一致且窄化的路径列表；任何越界路径都必须在 plan 中记为阻断性 scope conflict。
+- **缺失/冲突时如何 fail-closed**：缺失允许路径或发现计划目标在允许路径之外时，不得擅自扩大边界，返回 blocked。
 
 ## forbiddenPaths
 
-TODO
+- **要探索什么**：任务源与 `task.json` 中声明的禁止写入路径（运行时产物、依赖目录、构建输出、私有路径等）。
+- **结果必须包含**：禁止写入的路径清单，以及实现/验证步骤不触碰这些路径的确认。
+- **缺失/冲突时如何 fail-closed**：任何写入落入禁止路径立即阻断；禁止路径语义不变，不得新增读取权限字段或扩大写入边界。
+
+## OpenSpec 必读与引用核验（frontendOpenspec）
+
+- **要探索什么**：`task.json.frontendOpenspec.requiredReadPaths`（契约显式声明的必读 openspec 路径）与任务源 `需求.md`/`执行约束.md` 中显式引用的 openspec 路径。
+- **结果必须包含**：cited 模式候选集 = `requiredReadPaths` ∪ 任务源显式引用（去重排序）；每个候选在 plan 的 fenced `openspec-citations` 引用块中逐条出现（每行一个 JSON `{"path","section","line"}`），且每条引用都能在真实 read 事件中背书。
+- **缺失/冲突时如何 fail-closed**：候选非空而引用块缺失/不可解析 → `openspec-citation-block-unparseable`；候选未引用 → `openspec-not-cited`；引用存在但无成功 read 事件 → `openspec-citation-not-read`。三个 code 均为 `retryable-invalid`。候选为空时不强制并写 advisory（可声明 `requiredReadPaths` 增强）。`scan-strict` 模式保留全量必读语义与 `openspec-not-read`。
+- **`task.json.frontendOpenspec`**：`policy` 为 `cited | scan-strict`（缺省 `cited`）；`requiredReadPaths` 为 repo 相对路径数组，经 `isOpenspecSpecFilePath` 校验，非法路径生成期确定性失败。

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

@@ -1,70 +1,104 @@
 # 前端任务需求模板
 
+本模板只承载**通用编写协议 + 三要素 + fail-closed 规则**，不包含任何具体业务组件名、项目专属路径或项目专属命令。填写时每一节都要给出「**要写什么** / **DAG 如何消费** / **缺失/冲突时 fail-closed**」三要素；缺节、空占位或与验收标准冲突时必须阻塞，不得由模型猜测补写。
+
 ## 用户目标
 
-TODO
+- **要写什么**：以用户视角写清本次要交付的前端行为与用户价值——用户能完成什么、为什么需要它、成功后的可观察结果。必须可验证（可被界面状态或交互断言覆盖），不得只写技术动作或孤立关键词。
+- **DAG 如何消费**：`frontend-contract-pi` 把它映射为 Scope 与 `requirements[].expectedOutcome`，`frontend-plan-pi` 据它安排实现步骤并映射验收标准。
+- **缺失/冲突时 fail-closed**：缺失用户目标，或用户目标与验收标准互相矛盾时阻塞（`request-revision`/blocked），不得猜测补写或改写为技术实现描述。
 
 ## 目标页面/组件/路由
 
-TODO
+- **要写什么**：明确本次交付涉及的目标路由、页面入口与组件范围，逐条列出路径/名称与职责边界；相关但超出范围的页面写清「不做」。
+- **DAG 如何消费**：对齐 `docs/runtime/frontend-implementation-workflow.md` §「需求.md 应包含」的「目标路由/页面/组件」，`frontend-contract-pi` 据它确定 `targets.files` / `targets.routes`，`frontend-plan-pi` 据它划定 writeSet 与实现步骤。
+- **缺失/冲突时 fail-closed**：无法确定目标路由/页面/组件，或范围与验收标准不一致时阻塞；只写泛化名词（如「页面」「组件」）而不给具体范围视为缺失。
 
 ## 用户流程
 
-TODO
+- **要写什么**：写清端到端用户路径，从入口到结果，逐步列出触发动作、顺序与关键分支；涉及多页面/多状态时把每条路径分开写。
+- **DAG 如何消费**：`frontend-contract-pi` 据它抽取 `interactions[]`（每条带 `trigger` 与 `expectedBehavior`），`frontend-plan-pi` 据它安排组件/状态/交互实现步骤。
+- **缺失/冲突时 fail-closed**：缺少可执行的端到端路径、流程与验收标准冲突或关键分支未写时阻塞，不得只写「用户进入页面即可」。
 
 ## 必须状态
 
+每个适用状态必须写清该状态的触发条件与预期界面表现；不适用状态必须写 `N/A` 并给出非空理由（对齐 runtime 的 `uiStates` / N/A state 规则）。
+
 ### loading
 
-TODO
+- **要写什么**：loading 状态出现与结束的触发条件、展示内容（骨架/文案/禁用交互）与超时/失败转移。
+- **DAG 如何消费**：进入 implementation contract 的 `uiStates[]`（`name: "loading"`），`frontend-implement-pi` 按它实现，verify 用它的 `verificationTargetIds` 断言。
+- **缺失/冲突时 fail-closed**：适用但缺失预期行为时阻塞；不适用必须写 `N/A` 并给非空理由，只写 `N/A` 不带理由同样阻塞。
 
 ### empty
 
-TODO
+- **要写什么**：无数据/无结果状态的触发条件与展示（空态文案/引导动作/是否可刷新）。
+- **DAG 如何消费**：进入 `uiStates[]`（`name: "empty"`），verify 断言空态展示与引导。
+- **缺失/冲突时 fail-closed**：适用但缺失预期行为、或与 success/error 展示冲突时阻塞；不适用写 `N/A` + 非空理由。
 
 ### error
 
-TODO
+- **要写什么**：失败状态（请求失败/校验失败/权限失败）的触发条件、错误展示与可恢复动作。
+- **DAG 如何消费**：进入 `uiStates[]`（`name: "error"`），verify 断言错误展示与重试/回退行为。
+- **缺失/冲突时 fail-closed**：适用但缺失错误预期、或错误态会覆盖用户数据时阻塞；不适用写 `N/A` + 非空理由。
 
 ### success
 
-TODO
+- **要写什么**：成功状态的触发条件与展示（数据呈现/确认反馈/后续入口）。
+- **DAG 如何消费**：进入 `uiStates[]`（`name: "success"`），verify 断言成功展示与验收标准对应。
+- **缺失/冲突时 fail-closed**：成功态与验收标准不一致、或缺失成功结果时阻塞；不适用写 `N/A` + 非空理由。
 
 ### disabled
 
-TODO
+- **要写什么**：禁用/不可交互状态的触发条件（权限/前置未满足/进行中）与视觉/交互表现。
+- **DAG 如何消费**：进入 `uiStates[]`（`name: "disabled"`），verify 断言禁用态不会被误触。
+- **缺失/冲突时 fail-closed**：适用但缺失禁用条件、或禁用态与交互要求冲突时阻塞；不适用写 `N/A` + 非空理由。
 
 ## 目标运行环境
 
+每个环境必须声明适用性；不适用环境写 `N/A` 并给非空理由。
+
 ### desktop
 
-TODO
+- **要写什么**：desktop 视口下的适用性声明与关键布局/交互差异（断点、栅格、悬停等）。
+- **DAG 如何消费**：进入 contract 的 target runtime environment，`frontend-plan-pi` 据它决定响应式范围与样式策略。
+- **缺失/冲突时 fail-closed**：适用但缺失断点/布局说明，或与响应式要求冲突时阻塞；不适用写 `N/A` + 非空理由。
 
 ### mobile
 
-TODO
+- **要写什么**：mobile 视口下的适用性声明与触控/布局/安全区差异。
+- **DAG 如何消费**：进入 target runtime environment，`frontend-plan-pi` 据它决定响应式范围与组件策略。
+- **缺失/冲突时 fail-closed**：适用但缺失移动端表现，或与交互要求冲突时阻塞；不适用写 `N/A` + 非空理由。
 
 ### tablet
 
-TODO
+- **要写什么**：tablet 视口下的适用性声明与中间断点表现。
+- **DAG 如何消费**：进入 target runtime environment，`frontend-plan-pi` 据它决定响应式策略。
+- **缺失/冲突时 fail-closed**：适用但缺失 tablet 表现时阻塞；不适用写 `N/A` + 非空理由。
 
 ## 交互要求
 
-TODO
+- **要写什么**：逐条写清每个可交互元素的触发动作与预期行为（点击/输入/提交/滚动/键盘等），可被自动化断言覆盖。
+- **DAG 如何消费**：对齐 §「需求.md 应包含」的「交互要求」，`frontend-contract-pi` 抽取 `interactions[]`（`trigger` + `expectedBehavior`），verify 用行为命令断言。
+- **缺失/冲突时 fail-closed**：交互触发或预期行为缺失、与 UI 状态冲突、或不可自动化断言时阻塞，不得用「用户可正常操作」这类空话。
 
 ## 接口与 Mock 输入
 
-- 接口文档/schema：TODO
-- endpoint、method、关键请求/响应字段：TODO
-- 是否允许依赖真实后端：TODO
-- 是否要求离线或独立行为验证：TODO
-- success/empty/error/permission 状态：TODO
-- 后端当前就绪状态与 Real Integration Gap：TODO
+- **接口文档/schema — 要写什么**：引用接口文档或任务附件路径与版本，声明请求/响应 schema 来源。**DAG 如何消费**：`frontend-plan-pi` 据此选择 Mock 策略并冻结 endpoint/fixture 映射。**缺失/冲突时 fail-closed**：涉及接口但未引用文档或 schema 时阻塞，不得自行发明字段。
+- **endpoint、method、关键请求/响应字段 — 要写什么**：逐条列出 method、path 与关键字段及含义。**DAG 如何消费**：写入 `mockApi.endpoints[]`（method/path/fixture/consumer）。**缺失/冲突时 fail-closed**：字段缺失、与接口文档冲突或路径不合法时阻塞。
+- **是否允许依赖真实后端 — 要写什么**：明确声明真实后端当前是否可调用、是否允许生产/预览依赖真实请求。**DAG 如何消费**：决定 `mockApi.strategy` 是否可选 `not-needed`（需要真实/无远程证据）。**缺失/冲突时 fail-closed**：未声明后端就绪度却要求真实数据时阻塞，选 `not-needed` 却没有真实/无远程证据会被拦截。
+- **是否要求离线或独立行为验证 — 要写什么**：声明是否需要离线、本地预览或自动化行为验证（或两者都要）。**DAG 如何消费**：决定生成期 `frontendMock.verifyCommands` 与冻结命令集。**缺失/冲突时 fail-closed**：要求离线/自动化却未声明确定性验证命令时，生成期收敛为 `not-needed` 或直接 blocked，plan-revision 无法修复。
+- **success/empty/error/permission 状态 — 要写什么**：逐条声明接口各响应状态对应的 UI 表现。**DAG 如何消费**：与「必须状态」交叉校验，写入 `uiStates[]` 与 fixture 映射。**缺失/冲突时 fail-closed**：接口状态与 UI 状态不匹配或缺失 permission 分支时阻塞。
+- **后端当前就绪状态与 Real Integration Gap — 要写什么**：写清后端是否就绪、未就绪时保留的 Real Integration Gap 与后端就绪后的复验路径。**DAG 如何消费**：进入 `evidenceGaps[]` 与 closeout 的 `Real integration: pending`。**缺失/冲突时 fail-closed**：声称已联通真实接口却无真实证据时阻塞；未就绪却把 Mock 结果写成真实联调会被 review 拒绝。
 
 ## 验收标准
 
-TODO
+- **要写什么**：逐条编号（如 `AC-001`）写出可独立断言的前端验收标准，每条都能映射到需求与一个 verification target（可逐条追踪）。
+- **DAG 如何消费**：`frontend-contract-pi` 生成 `requirements[].verificationTargetIds` 映射，`frontend-plan-pi` 把每条 AC 落到有序步骤与验证命令，verify 逐条断言。
+- **缺失/冲突时 fail-closed**：无验收标准、AC 无法映射到需求/验证目标、或 AC 与其它节冲突时阻塞，不得把「看起来能用」当验收。
 
 ## 非目标
 
-TODO
+- **要写什么**：明确列出本次不做的前端范围/排除项（页面、组件、交互、浏览器/视觉/无障碍检查等）。
+- **DAG 如何消费**：`frontend-contract-pi` 记录为 Non-goals，`frontend-review-pi` 据它拒绝范围扩散。
+- **缺失/冲突时 fail-closed**：非目标与目标/验收标准冲突、或范围被悄悄扩大时阻塞；明确不做前端时也必须写入非目标。