@tea-agent/loop-agent 0.36.4-beta.0 → 0.38.0-next.1

package/AGENTS.md

@@ -40,6 +40,7 @@
 6. 后端/接口/pytest → `taskKind: "backend-test"`（不是 `--profile`）；知识回写 `knowledge-sync`；图谱开荒 `knowledge-graph-bootstrap`。`--profile` 仅 `auto|minimal|standard|reviewed|supervised`。
 7. 看板/observe → `agent-worker console`（默认 repo=当前目录、port=8790；listen 成功后默认打开系统浏览器，`--no-open` 禁止）（`/inspect/` 只读）；`observe serve` 已下线（`OBSERVE_SERVE_REMOVED` + exit 2）；`observe snapshot` 仍可用。
 8. 分支合并 → 先读 `docs/operations/branch-merge-guideline.md`。
+9. 涉及版本发布、npm 渠道、release 分支、GitHub Actions 发布链或 dist-tag → 先读 `docs/operations/version-and-release-management.md`。
 
 ## 会话协议
 
@@ -62,6 +63,7 @@ DAG 执行期间，主 agent 不得修改 writeSet 外的任何工作区文件
 - `skills/`：源仓库/npm 内置 skills；目标项目只生成 `.agents/skills/`
 - `.harness/`：运行态（tasks/dag-runs/runs 等；init 会 gitignore 运行事实，保留 prompts 与占位）
 - `docs/`：治理；`website/`：用户文档站；`scripts/`：检查与 CI
+- 版本发布链（next / release-x.y / latest 手工 promote）：`docs/operations/version-and-release-management.md`
 
 ## 工作规则（增量约束）
 

package/CHANGELOG.md

@@ -1,32 +1,42 @@
 # 更新日志
 
-## [0.36.4-beta.0] - 2026-08-16
-
-> 前端 DAG 规范上下文确定性落地（beta，发布到 `beta` dist-tag）。
+## [Unreleased]
 
 ### 新增
 
-- `discoverFrontendProjectCapability` 产出 `designEvidence.classified` 语义归类：按通用目录约定（`openspec/schemas/**`、`openspec/project-specs/templates/**`、`openspec/project-specs/rules/**`、`openspec/project-specs/ui/**`、`ai_workspace/**`）把规范路径分入稳定键 `schemas` / `codeTemplate` / `rule.*` / `theme` / `component` / `uiOther` / `advisoryOther`，并进入 zod schema 校验（分区恒等式：归类值集合 == `normativePaths` 集合），重复探测稳定，不硬编码具体项目文件名
-- 前端 contract/scout/plan/design-review 节点的 `subtask_prompt` 注入归类后的规范路径（含角色语义）并明确要求报告适用规则、命中路径/章节/行号、冲突与缺失
+- 版本发布改为三渠道：main 自动发布 npm `next`（`x.y.0-next.N`）、release 分支自动发布正式 patch 到 `release-x.y`、`latest` 仅由人工 GitHub Actions promotion 移动（支持 dry-run 与 CAS 校验）
+- 新增 `next-release.yml` / `cut-release-line.yml` / `release-line-publish.yml` / `promote-npm-latest.yml`，删除旧每日自动 latest 发布入口
+- 发布策略改为 branch + version + channel 矩阵（`scripts/release-channel-policy.mjs`），fail closed
+- 双周 Release Train：可从选定 next 的精确 source SHA 创建版本化 release 分支，带幂等恢复与单 tarball SHA-256 绑定
 
-### 修复
+## [0.37.0] - 2026-08-16
 
-- `frontend-prewrite-gate` 在 `openspecCandidatePaths` 非空时强制生效 plan/review 节点实际读取候选路径：未读 → `retryable-invalid` + 新增 `openspec-not-read` failureCode，错误信息列出未读路径；空候选（greenfield）不阻断。此前读取证据仅记录不阻断（advisory），本次真正 fail-closed
+### 新增
 
-### 文档
+- markdown syntax highlight, math formulas and mermaid diagrams; operate entry lands on chat
+- label rerun titles with round number from -rN id suffix
+- enter-DAG action, artifact rail projection, zh changelog
+- surface compaction progress and timeline summary
+- floating auto-dismiss toasts replace in-flow error alerts
+- add running spinners to session titles and stop button
+- show context ratio, semantic cache icons, align process entry typography
+- show context usage and semantic cache labels in usage bar
+- stream live turn process in strict order
 
-- `docs/templates/frontend-task-constraints.md` 把裸 `TODO` 改写为「探索协议 + 结果 schema + 缺失/冲突 fail-closed」，不再出现具体业务组件名或项目专属路径/命令
-- `docs/templates/frontend-task-requirement.md` 与 `docs/templates/frontend-design-contract.md` 把裸 `TODO` 改写为「编写协议」三要素（要写什么 / DAG 如何消费 / 缺失/冲突时 fail-closed），并新增 `test/frontend-template-no-todo.test.ts` 扫描三个前端模板断言无裸 `TODO`
-- `docs/runtime/frontend-implementation-workflow.md` 的项目规范归类清单改为通用目录约定 + 归类规则，删除写死的示例项目文件名
+### 修复
 
-## [0.36.3-beta.0] - 2026-08-16
+- isolate interrupt kernel behind worker adapter
+- constrain session title width so hover tooltip engages
+- backfill operation link for semantic activity refs
+- fail fast on non-canonical newTask ids with suggested fix
+- accept projected references and normalize PRD headings
 
-> 前端 DAG Mock 治理收紧（beta，发布到 `beta` dist-tag）。
+## [0.36.2] - 2026-08-16
 
-### 改进
+### 修复
 
-- 前端 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），把契约缺口提前到生成期暴露
+- exempt changelog history from task-pool-root scan
+- exempt gitignore managed-block doc references in task-pool-root check
 
 ## [0.36.1] - 2026-08-16
 
@@ -39,73 +49,52 @@
 - 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
 
 ### 新增
 
-- add task journey activity rail
-- harden Operator Chat DAG recovery
-- confirm session deletion inline
-- supervise long-running DAG operations
-- polish slash command card grid
-- localize generated runtime state
+- 新增任务旅程活动栏，把任务创建、人工门禁、多次运行、失败和恢复记录聚合在同一张卡片中
+- 强化 Operator Chat 的 DAG 恢复能力，运行失败后可以直接查看原因、恢复路径和后续动作
+- 会话删除改为列表行内二次确认，减少误删，也不再被浏览器原生弹窗打断
+- Operator Chat 可以持续监督长时间运行的 DAG，直到任务结束、失败或确实需要人工处理
+- 优化斜杠命令面板的卡片布局和键盘操作，在较小窗口中也能完整浏览和选择命令
+- 运行状态、恢复提示和关键操作文案统一为自然中文，减少内部状态码和生硬英文直接暴露给用户
 
 ### 修复
 
-- harden task advance supervision
-- runner heartbeat logs no longer wake operationWait; writers must use edit tools for markdown
-- require writer to sync catalog index companions in writeSet
-- accept zh-CN acceptance heading variants in PRD parse
-- writer must materialize plan and not claim blocked for untouched forbidden paths
-- parse dag report runs[] envelope in rerun eligibility
-- tell writers diff is measured from git status, not response text
-- allow custom operator tools in SDK session allowlist
-- fit slash palette to available height
-- close operator chat command gaps
+- 任务推进期间的监督更加可靠，减少因短暂静默或状态更新延迟造成的误判
+- 运行器心跳不再提前唤醒 `operationWait`；Markdown 写入统一使用安全编辑工具，降低误覆盖风险
+- 写入目录文档时必须同步更新对应索引，避免内容已经生成却无法从目录入口找到
+- PRD 验收标准支持更多常见中文标题写法，不再因括号、破折号或措辞差异漏掉验收条件
+- 要求执行节点真正生成计划文件；没有触碰禁写路径时，不再错误声称任务受阻
+- 恢复重跑可以正确读取 `dag report` 返回的运行列表，不再因为响应结构差异误判为不可恢复
+- 变更范围统一以 Git 工作区的真实差异为准，不再根据模型回复文字推测是否修改过文件
+- Operator 自定义工具可以正常进入 Pi SDK 会话，不再被工具白名单意外过滤
+- 斜杠命令面板会根据实际可用高度自动调整，不再被窗口边缘裁切
+- 补齐 Operator Chat 的本地命令处理、动态命令降级和错误提示等交互缺口
 
 ## [0.35.3] - 2026-08-15
 
 ### 新增
 
-- chat as default landing + analyze-skills-first new-task flow
-- guide plan verification targets to writeSet-internal files, command-level checks to static
-- console recovery display — surface frontend recovery lineage + outcome
-- frontend-implementation DAG phase 6 — recovery root manifest + statistics dedup
-- frontend-implementation DAG phase 5 — writer partial-write rollback + child recovery
-- frontend-implementation DAG phase 4 — writer transient rollback base
-- frontend-implementation DAG phase 3c — scheduler activation gate + recovery trigger
-- frontend-implementation DAG phase 3b — staged child-creation kernel
-- frontend-implementation DAG phase 3a — recovery state/result types + terminal recovery intent
-- producing-node contract self-check and run robustness hardening
-- frontend-implementation DAG phase 2 — unified writer helper + structured repair assessment
-- slim frontend-implementation DAG phase 1 — prewrite merge + writer admission gate
+- Console 默认进入「对话」页面；创建新任务时先分析需求和依赖，再进入正式任务流程
+- 计划中的文件验证会优先落到允许写入的范围内，命令级检查则使用稳定的静态验证入口
+- Recovery 页面新增恢复链路和最终结果展示，能够看清一次失败是如何被接管和收敛的
+- 前端实现 DAG 增加恢复根清单，并去除重复统计，恢复报告更清晰
+- 写入节点支持部分写入回滚和子任务恢复，局部失败不再轻易污染后续执行
+- 写入节点遇到短暂故障时可以回退到稳定基线，再决定重试或恢复
+- 调度器增加激活门禁和恢复触发条件，只有满足执行条件的子任务才会进入运行
+- 新增分阶段创建子任务的基础能力，为后续恢复和分批执行提供统一入口
+- 补齐恢复状态、恢复结果和终态恢复意图的数据结构，前后端对失败状态的理解保持一致
+- 产出节点新增契约自检，并强化长时间运行时的稳定性和异常收敛能力
+- 统一写入节点的公共辅助逻辑，修复判断改为结构化结果，不再依赖模糊文本
+- 精简前端实现 DAG 的第一阶段，在正式写入前完成结果合并和写入准入检查
 
 ### 修复
 
 - 规范证据面板不再单列 openspec，统一为「规范已读取/规范检索」
-- green full test suite — python3 fallback, build-stamp version normalization, DEP0205 suppression
-- update candidate-continuation fixtures for failureCode (rebase semantic fix)
+- 恢复全量测试稳定性：没有 `python3` 时自动使用可用 Python，统一构建版本格式，并处理 Node 弃用警告造成的干扰
+- 修正续跑候选测试数据，使 `failureCode` 与真实失败语义一致，避免变基后出现错误判断
 
 ## [0.35.2] - 2026-08-15
 

package/README.md

@@ -29,6 +29,18 @@ npm install -g @tea-agent/loop-agent@latest
 loop-agent --version
 ```
 
+渠道说明（普通用户默认 `latest`；开发/测试用 `next`；固定某条版本线用
+`release-x.y`；正式 dogfood 用精确版本）：
+
+```bash
+npm install -g @tea-agent/loop-agent                 # 推荐稳定版本
+npm install -g @tea-agent/loop-agent@next            # main 高频开发构建
+npm install -g @tea-agent/loop-agent@release-0.37    # 0.37 版本线最新 patch
+npm install -g @tea-agent/loop-agent@0.37.5          # 精确、可复现
+```
+
+完整发布治理见 `docs/operations/version-and-release-management.md`。
+
 ### 初始化当前项目
 
 ```bash

package/dist/build-stamp.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "version": "0.36.4-beta.0",
-  "gitSha": "b4d154e6c1e109f754c059c22588cfd0298d4764",
-  "builtAt": "2026-08-16T17:25:17.099Z"
+  "version": "0.37.0",
+  "gitSha": "7b0878dd8e02f0df25546a68db57ca0e4e6f58a1",
+  "builtAt": "2026-08-17T01:11:56.938Z"
 }

package/dist/infrastructure/harness/atomic-write.js

@@ -1,14 +1,13 @@
 import { copyFile, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { assertHarnessWriteAllowed, } from "./completed-facts-guard.js";
-let atomicWriteSequence = 0;
 async function writeAtomic(targetPath, content, options) {
     assertHarnessWriteAllowed(targetPath, options);
     const resolved = options?.repoRoot && !path.isAbsolute(targetPath)
         ? path.resolve(options.repoRoot, targetPath)
         : path.resolve(targetPath);
     await mkdir(path.dirname(resolved), { recursive: true });
-    const tempPath = `${resolved}.${process.pid}.${(atomicWriteSequence += 1)}.tmp`;
+    const tempPath = `${resolved}.${process.pid}.tmp`;
     try {
         await writeFile(tempPath, content, "utf-8");
         try {

package/dist/task/contract/project.js

@@ -46,6 +46,10 @@ export function projectRequirementMarkdown(draft) {
             lines.push(`- ${item}`);
         }
     }
+    // References / Source Resolutions remain projected into 需求.md (durable
+    // provenance for human readers); the managed read-back validator accepts
+    // the projector's own canonical forms instead of rejecting them
+    // (2026-08-16 L1: writer/reader round-trip invariant).
     if (draft.sourceResolutions && draft.sourceResolutions.length > 0) {
         lines.push("", "## Source Resolutions", "");
         for (const res of draft.sourceResolutions) {

package/dist/task/frontend-project-capability.js

@@ -5,73 +5,7 @@
  */
 import { readFile, readdir, stat } from "node:fs/promises";
 import path from "node:path";
-import { z } from "zod";
-import { OPENSPEC_SPEC_DIRS, OPENSPEC_SPEC_EXT_RE, isOpenspecSpecFilePath, } from "../shared/openspec-spec.js";
-const classifiedPathSchema = z
-    .string()
-    .refine((candidate) => isOpenspecSpecFilePath(candidate), "classified path must be a repo-relative supported spec file under openspec/schemas/, openspec/project-specs/, or ai_workspace/");
-/**
- * Stable semantic partition of `designEvidence.normativePaths`. Keys are a
- * generic directory convention (not project-specific file names); the same
- * repository therefore yields the same classification on repeated probes.
- */
-export const frontendDesignClassifiedSchema = z
-    .object({
-    schemas: z.array(classifiedPathSchema),
-    codeTemplate: z.array(classifiedPathSchema),
-    rule: z
-        .object({
-        api: z.array(classifiedPathSchema),
-        mock: z.array(classifiedPathSchema),
-        router: z.array(classifiedPathSchema),
-        hooks: z.array(classifiedPathSchema),
-        utils: z.array(classifiedPathSchema),
-        components: z.array(classifiedPathSchema),
-        other: z.array(classifiedPathSchema),
-    })
-        .strict(),
-    theme: z.array(classifiedPathSchema),
-    component: z.array(classifiedPathSchema),
-    uiOther: z.array(classifiedPathSchema),
-    advisoryOther: z.array(classifiedPathSchema),
-})
-    .strict();
-export const frontendDesignEvidenceSchema = z
-    .object({
-    normativePaths: z.array(z.string()),
-    advisoryPaths: z.array(z.string()),
-    conflicts: z.array(z.string()),
-    classified: frontendDesignClassifiedSchema,
-})
-    .strict()
-    .superRefine((evidence, ctx) => {
-    const classified = [
-        ...evidence.classified.schemas,
-        ...evidence.classified.codeTemplate,
-        ...evidence.classified.rule.api,
-        ...evidence.classified.rule.mock,
-        ...evidence.classified.rule.router,
-        ...evidence.classified.rule.hooks,
-        ...evidence.classified.rule.utils,
-        ...evidence.classified.rule.components,
-        ...evidence.classified.rule.other,
-        ...evidence.classified.theme,
-        ...evidence.classified.component,
-        ...evidence.classified.uiOther,
-        ...evidence.classified.advisoryOther,
-    ];
-    const classifiedSet = new Set(classified);
-    const normativeSet = new Set(evidence.normativePaths);
-    const onlyClassified = [...classifiedSet].filter((candidate) => !normativeSet.has(candidate));
-    const onlyNormative = [...normativeSet].filter((candidate) => !classifiedSet.has(candidate));
-    if (onlyClassified.length > 0 || onlyNormative.length > 0) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: `classified must partition normativePaths exactly; extra in classified: ${onlyClassified.join(", ") || "(none)"}; missing from classified: ${onlyNormative.join(", ") || "(none)"}`,
-            path: ["classified"],
-        });
-    }
-});
+import { OPENSPEC_SPEC_DIRS, OPENSPEC_SPEC_EXT_RE } from "../shared/openspec-spec.js";
 async function exists(filePath) {
     try {
         await stat(filePath);
@@ -107,14 +41,13 @@ async function listOpenspec(repoRoot) {
             continue;
         await walk(root, 0);
     }
-    out.sort();
     return out.slice(0, 40);
     async function walk(dir, depth) {
         if (depth > 4)
             return;
         let entries = [];
         try {
-            entries = (await readdir(dir)).sort();
+            entries = await readdir(dir);
         }
         catch {
             return;
@@ -135,97 +68,6 @@ async function listOpenspec(repoRoot) {
         }
     }
 }
-function emptyClassified() {
-    return {
-        schemas: [],
-        codeTemplate: [],
-        rule: { api: [], mock: [], router: [], hooks: [], utils: [], components: [], other: [] },
-        theme: [],
-        component: [],
-        uiOther: [],
-        advisoryOther: [],
-    };
-}
-/**
- * Classify discovered openspec paths by generic directory convention. Only
- * `isOpenspecSpecFilePath` paths enter a bucket; the classifier never invents
- * project-specific file names. Basename stems use word-boundary matching so
- * e.g. `*api*` (case-insensitive) maps to `rule.api` without hardcoding names.
- */
-function classifyOpenspecPaths(paths) {
-    const classified = emptyClassified();
-    const ruleStem = (basename) => {
-        const lower = basename.toLowerCase();
-        const stems = [
-            ["api", /\bapi\b/],
-            ["mock", /\bmock\b/],
-            ["router", /\brouter\b/],
-            ["hooks", /\bhooks?\b/],
-            ["utils", /\butils?\b/],
-            ["components", /\bcomponents?\b/],
-        ];
-        for (const [key, re] of stems) {
-            if (re.test(lower))
-                return key;
-        }
-        return "other";
-    };
-    for (const candidate of paths) {
-        if (!isOpenspecSpecFilePath(candidate))
-            continue;
-        const segments = candidate.split("/");
-        const basename = segments[segments.length - 1] ?? "";
-        if (candidate.startsWith("openspec/schemas/")) {
-            classified.schemas.push(candidate);
-        }
-        else if (candidate.startsWith("openspec/project-specs/templates/")) {
-            classified.codeTemplate.push(candidate);
-        }
-        else if (candidate.startsWith("openspec/project-specs/rules/")) {
-            classified.rule[ruleStem(basename)].push(candidate);
-        }
-        else if (candidate.startsWith("openspec/project-specs/ui/")) {
-            const lower = basename.toLowerCase();
-            if (/\btheme\b/.test(lower))
-                classified.theme.push(candidate);
-            else if (/\bcomponents?\b/.test(lower))
-                classified.component.push(candidate);
-            else
-                classified.uiOther.push(candidate);
-        }
-        else {
-            classified.advisoryOther.push(candidate);
-        }
-    }
-    const sortBucket = (bucket) => bucket.sort();
-    classified.schemas = sortBucket(classified.schemas);
-    classified.codeTemplate = sortBucket(classified.codeTemplate);
-    for (const key of [
-        "api",
-        "mock",
-        "router",
-        "hooks",
-        "utils",
-        "components",
-        "other",
-    ]) {
-        classified.rule[key] = sortBucket(classified.rule[key]);
-    }
-    classified.theme = sortBucket(classified.theme);
-    classified.component = sortBucket(classified.component);
-    classified.uiOther = sortBucket(classified.uiOther);
-    classified.advisoryOther = sortBucket(classified.advisoryOther);
-    return classified;
-}
-function buildDesignEvidence(openspec) {
-    const normativePaths = [...new Set(openspec)].sort();
-    return frontendDesignEvidenceSchema.parse({
-        normativePaths,
-        advisoryPaths: [],
-        conflicts: [],
-        classified: classifyOpenspecPaths(normativePaths),
-    });
-}
 export function buildAdapterGuidance(capability) {
     const lines = [
         "## Frontend project capability (generation-time)",
@@ -279,7 +121,11 @@ export async function discoverFrontendProjectCapability(repoRoot) {
             a11y: { status: "unknown", tools: [], evidencePaths: [] },
             evidencePaths: openspec.slice(0, 5),
             reasons: ["package.json missing or unreadable"],
-            designEvidence: buildDesignEvidence(openspec),
+            designEvidence: {
+                normativePaths: openspec,
+                advisoryPaths: [],
+                conflicts: [],
+            },
         };
         if (openspec.length) {
             base.reasons.push(`openspec spec files discovered: ${openspec.slice(0, 5).join(", ")}`);
@@ -438,7 +284,11 @@ export async function discoverFrontendProjectCapability(repoRoot) {
     if (hasDep(deps, "vue-router"))
         router = "vue-router";
     const openspec = await listOpenspec(repoRoot);
-    const designEvidence = buildDesignEvidence(openspec);
+    const designEvidence = {
+        normativePaths: openspec,
+        advisoryPaths: [],
+        conflicts: [],
+    };
     if (openspec.length)
         evidencePaths.push(...openspec.slice(0, 5));
     const base = {

package/dist/task/source-prepare/completeness.js

@@ -68,6 +68,15 @@ export function listPrepareGaps(input) {
             level: "blocking",
             field: "objective",
             message: "requirement.objective is required",
+            details: { headingAliases: ["目标", "objective", "业务目标", "需求概述"] },
+            selfHealing: {
+                action: "reimport-prd",
+                steps: [
+                    "检查 PRD 是否含「## 目标」或「## Objective」章节；中文括号后缀（如「目标（概述）」）已被识别",
+                    "若确实缺失：补全 PRD 后重新 importPrd（同 taskId），advance 会自动重投影",
+                    "不要手改 source/需求.md（会触发 DIRTY_SOURCE）；不要在 PRD 目录生成 sidecar draft JSON",
+                ],
+            },
         });
     }
     if (draft.requirement.acceptanceCriteria.length === 0) {
@@ -76,6 +85,25 @@ export function listPrepareGaps(input) {
             level: "blocking",
             field: "acceptanceCriteria",
             message: "at least one acceptance criterion is required",
+            details: {
+                recognizedHeadings: [
+                    "验收标准",
+                    "acceptance criteria",
+                    "完成标准",
+                    "完成定义",
+                    "验收",
+                    "dod",
+                ],
+                note: "标题含括号/破折号后缀会被自动归一；AC 需为列表项（- / 1.）或 AC-NNN 标题/行内格式",
+            },
+            selfHealing: {
+                action: "reimport-prd",
+                steps: [
+                    "检查 PRD 验收章节标题（如「完成标准（验收）」已可识别）与列表格式：需为「- 项目」或「AC-001: 文本」",
+                    "格式修正后重新 importPrd（同 taskId）；advance 内置 semantic intake 兜底，文档语义完整时会自动结构化",
+                    "若 advance 已返回 SEMANTIC_INTAKE_FAILED：补全 PRD 后重试，不要手改 source/ 需求.md",
+                ],
+            },
         });
     }
     if (input.acceptanceConflicts && input.acceptanceConflicts.length > 0) {
@@ -188,6 +216,14 @@ export function listPrepareGaps(input) {
             code: "DIRTY_SOURCE",
             level: "blocking",
             message: "existing non-empty or externally-modified source refuses --apply; use show/diff/adopt/recover or --force-overwrite-source",
+            selfHealing: {
+                action: "adopt-contract",
+                steps: [
+                    "task status --json 读取 contract.observedCanonicalHash 与当前 revision",
+                    "若变更确属预期：task contract adopt --task <id> --expected-revision <n> --expected-observed-hash <hash> --request-id <id> --request-payload-sha256 <sha>",
+                    "若变更不是预期的：改 PRD 后重新 importPrd 走完整重投影；禁止手改 lifecycle.json / .transactions/ 绕过",
+                ],
+            },
         });
         risks.push({
             code: "DIRTY_SOURCE",

package/dist/task/source-prepare/parse-intent.js

@@ -44,15 +44,6 @@ function stripFencedAndComments(text) {
         .replace(/~~~[\s\S]*?~~~/g, "\n")
         .replace(/<!--[\s\S]*?-->/g, "\n");
 }
-function normalizeHeadingText(raw) {
-    return raw
-        .trim()
-        // Strip leading section numbers: "2. 业务目标" / "3.1 已确认范围" / "3.2、非目标"
-        .replace(/^(?:\d+(?:\.\d+)*[.．、]?\s*)+/u, "")
-        .toLowerCase()
-        .replace(/[:：]\s*$/u, "")
-        .replace(/\s+/g, " ");
-}
 function normalizeAcceptanceId(raw) {
     return raw
         .trim()
@@ -69,12 +60,67 @@ function parseEmbeddedAcHeading(headingText) {
     const text = match[2]?.trim() || id;
     return { id, text };
 }
+function normalizeHeadingText(raw) {
+    return raw
+        .trim()
+        // Strip leading section numbers: "2. 业务目标" / "3.1 已确认范围" / "3.2、非目标"
+        .replace(/^(?:\d+(?:\.\d+)*[.．、]?\s*)+/u, "")
+        .toLowerCase()
+        .replace(/[:：]\s*$/u, "")
+        .replace(/\s+/g, " ");
+}
+/**
+ * Strip decorative suffixes that real PRD writers attach to section
+ * headings: "完成标准（验收）" → "完成标准", "Acceptance Criteria (DoD):" →
+ * "acceptance criteria", "验收标准 — 交付门槛" → "验收标准". Handles zh/en
+ * parens, dashes, colons and trailing separators before the suffix.
+ */
+function stripHeadingDecorations(normalized) {
+    return normalized
+        .replace(/[（(][^（()）]*[)）]\s*$/u, "")
+        .replace(/\s*[—–\-|]\s*[^—–\-|]+$/u, "")
+        .replace(/[:：]\s*$/u, "")
+        .trim();
+}
+const HEADING_PREFIX_HINTS = [
+    { key: "objective", hint: "目标" },
+    { key: "objective", hint: "objective" },
+    { key: "scope", hint: "范围" },
+    { key: "scope", hint: "scope" },
+    { key: "nonGoals", hint: "非目标" },
+    { key: "nonGoals", hint: "out of scope" },
+    { key: "acceptance", hint: "验收" },
+    { key: "acceptance", hint: "acceptance" },
+    { key: "acceptance", hint: "完成标准" },
+    { key: "acceptance", hint: "完成定义" },
+    { key: "acceptance", hint: "dod" },
+    { key: "constraints", hint: "约束" },
+    { key: "constraints", hint: "constraints" },
+    { key: "openQuestions", hint: "待决问题" },
+    { key: "openQuestions", hint: "open questions" },
+    { key: "assumptions", hint: "假设" },
+    { key: "assumptions", hint: "assumptions" },
+];
 function classifyHeading(text) {
     const normalized = normalizeHeadingText(text);
     for (const [key, aliases] of Object.entries(HEADING_ALIASES)) {
         if (aliases.has(normalized))
             return key;
     }
+    // Decoration-stripped exact match: "完成标准（验收）" → "完成标准".
+    const stripped = stripHeadingDecorations(normalized);
+    if (stripped && stripped !== normalized) {
+        for (const [key, aliases] of Object.entries(HEADING_ALIASES)) {
+            if (aliases.has(stripped))
+                return key;
+        }
+    }
+    // Prefix-contains fallback: "验收标准与测试" starts with "验收"; keep the
+    // hint list narrow (whole-word/leading-substring) to avoid false hits.
+    for (const { key, hint } of HEADING_PREFIX_HINTS) {
+        if (stripped === hint || stripped.startsWith(hint))
+            return key;
+    }
     return "other";
 }
 function isAtxHeading(line) {
@@ -408,10 +454,20 @@ export function fillMissingRequirementFacts(base, supplemental) {
 export function parseVerifyFlag(raw) {
     const idx = raw.indexOf(":");
     if (idx <= 0 || idx === raw.length - 1) {
-        throw new Error(`invalid --verify value "${raw}"; expected <label>:<command>`);
+        // Actionable error with concrete examples (2026-08-16 L3'-style):
+        // models were guessing flag names (--verify-label) and separator
+        // shapes; the example makes the contract self-evident.
+        const hint = !raw.includes(":")
+            ? `no label separator found; write it as <label>:<command>, e.g. --verify "typecheck:npm run typecheck"`
+            : `empty ${idx === 0 ? "label" : "command"}; write it as <label>:<command>, e.g. --verify "typecheck:npm run typecheck"`;
+        throw new Error(`invalid --verify value "${raw}"; expected <label>:<command> — ${hint}`);
+    }
+    const label = raw.slice(0, idx).trim();
+    if (!/^[a-z0-9][a-z0-9-]*$/i.test(label)) {
+        throw new Error(`invalid --verify label "${label}"; use short kebab-case letters/digits/hyphens (e.g. typecheck, unit-tests, build) — value was "${raw}"`);
     }
     return {
-        label: raw.slice(0, idx).trim(),
+        label,
         command: raw.slice(idx + 1).trim(),
     };
 }