@devcxl/opencode-cabbage 0.3.1 → 1.0.0

package/assets/skills/flow-review/SKILL.md

@@ -1,130 +1,44 @@
 ---
 name: flow-review
-description: 双轴审查（规范 + 规格）→ 自动合并
+description: 双轴审查（规范 + 规格）→ task_control submit-review / merge-task
 ---
 
 # flow-review
 
 沿两条轴线审查 PR 代码：规范（是否符合编码标准）和规格（是否实现了原始需求）。
+审查结果由 primary 通过 `task_control` 提交与合并，reviewer 本身只读。
 
-## Prerequisites
-- PR 已创建
-- 可选的 `/test` 已完成
+## 核心：调用 task_control
 
-## Workflow
+1. `task_control{op:"submit-review", pr_number, verdict:"approve"|"request-changes", ...}` — 发布审查结果
+2. `task_control{op:"merge-task", pr_number, ...}` — 合并（CI + 分支保护 + 风险分级 + 高风险人类 approval）
+3. `task_control{op:"status-task", task_id}` — 查看 Task/PR 状态
 
-### 1. 获取审查材料
-```bash
-gh pr diff <pr-number>
-gh pr view <pr-number> --json title,body,files
-```
+reviewer 只读：不直接 `gh pr review` / `gh pr merge`（写操作由 primary 经 task_control 执行）。
 
-### 2. 阅读约束来源
-- 检查相关 ADR（`docs/adr/`）— 确认代码是否遵循架构决策
-- 确认规格来源：commit 消息中的 Issue 引用或 `docs/prd/` / `docs/dev/specs/`
-
-### 3. 文档同步确认
-确认 PR 中是否包含文档同步：
-- 检查 PR body 是否列出已同步的文档
-- 检查 `docs/guides/` 和 `docs/dev/guides/` 是否有相应变更
-- 如涉及配置/API 变更但文档未同步 → 标记为阻断性问题
-
-### 4. 双轴审查
-并行检查两个维度：
+## 双轴审查
 
 **规范轴（Normative）** — 代码是否符合文档化的编码标准？
 参考 `references/smell-baseline.md` 中的代码气味基线。
 
 **规格轴（Specification）** — 代码是否忠实实现了需求？
 对照 PRD（`docs/prd/`）和设计方案（`docs/dev/specs/`）验证。
-- 如发现实现与设计偏差 → 追加到 `docs/dev/changelog/<YYYY-MM-DD-NNN-slug>.md`
+- 如发现实现与设计偏差 → 追加到 changelog
 
 **TDD Criterion Coverage** — 检查 Task 的 `acceptance_criteria` 是否被 PR 覆盖：
 - 对照 Task frontmatter 中的 `acceptance` 数组，逐条核查
 - 检查 PR 是否包含每条 criterion 对应的测试或验证
 - 检查 `tdd` 配置块中的 `mode` 和 `min_cycles` 是否被遵循
-- **明确不检查 commit order** — TDD cycle 的 RED→GREEN 顺序是编码过程约束，
-  reviewer 不审查 commit 历史是否呈现 RED-first 模式
-
-### 5. 合并前检查
-在合并前确认以下项：
-- 文档同步已完成（`docs/guides/` 已更新或无需更新）
-- changelog 已记录偏差（如有）
-- CI 已通过
-
-### 6. 发表审查意见
-发现阻断性问题：
-```bash
-gh pr review <pr-number> --request-changes --body "..."
-```
-无问题或非阻断性建议：
-```bash
-gh pr review <pr-number> --approve --body "..."
-```
-
-### 7. 等待 CI + 自动合并
-```bash
-gh pr checks <pr-number> --watch
-gh pr merge <pr-number> --squash --delete-branch
-```
-
-### 8. 关闭关联 Sub Issue
-如果 PR body 未包含 `Closes #<num>`（或 PR 合并后 GitHub 未自动关闭），手动关闭：
-```bash
-gh issue close <issue-num> --comment "已完成，已合并至 main"
-```
-
-### 9. 清理 Worktree
-PR 合并后，安全清理对应的 worktree 和分支：
-
-```bash
-WORKTREE=".worktree/<task-slug>"
-BRANCH="feat/<task-slug>"
-
-# Preflight 检查
-echo "=== Worktree 清理 Preflight ==="
-
-# 1. 确认 PR 已合并
-PR_NUM=<pr-number>
-if ! gh pr view "$PR_NUM" --json merged --jq '.merged' 2>/dev/null | grep -q true; then
-  echo "ERROR: PR #$PR_NUM 未合并，跳过清理"
-  exit 1
-fi
-
-# 2. 确认分支已推送到远程
-if git ls-remote --exit-code origin "$BRANCH" >/dev/null 2>&1; then
-  echo "分支 $BRANCH 已推送到远程"
-else
-  echo "WARNING: 分支 $BRANCH 未推送到远程，但 PR 已合并，继续清理"
-fi
-
-# 3. 检查 worktree 是否干净
-if [ -d "$WORKTREE" ]; then
-  DIRTY=$(git -C "$WORKTREE" status --porcelain)
-  if [ -n "$DIRTY" ]; then
-    echo "WARNING: Worktree 有未提交变更："
-    echo "$DIRTY"
-    echo "暂停。如需强制清理请手动执行 --force"
-    exit 1
-  fi
-
-  # 4. 全部通过 → 清理
-  git worktree remove "$WORKTREE"
-  git branch -D "$BRANCH" 2>/dev/null || true
-  echo "Worktree 已清理：$WORKTREE"
-else
-  echo "Worktree 不存在，跳过清理"
-fi
-```
-
-> 清理前必须验证 PR 已合并、worktree 干净。只有在所有 preflight 检查通过后才删除。
-> 如果 PR 已合并但 worktree 仍有未提交变更，暂停并通知用户，不自动 --force。
+- **明确不检查 commit order** — RED→GREEN 顺序是编码过程约束，reviewer 不审查 commit 历史
+
+## 审查材料获取
+
+代码审查必须在本地分支/worktree 中进行，禁止通过 WebFetch 或浏览器访问远程 PR 页面获取代码。
 
 ## Output
-- PR 已审查
-- PR 已合并（条件满足时）
-- 关联 Sub Issue 已关闭
-- changelog 已记录偏差（如有）
+- 结构化审查报告（APPROVED / CHANGES_REQUESTED）
+- PR 已合并（task_control merge-task，条件满足时）
+- Worktree 已清理（task_control merge-task 后 preflight 销毁）
 
 ## 后续
 - **/release** — 发布（如所有 PR 已合并）
@@ -135,26 +49,25 @@ fi
 由 `/review` 命令或 `@dev-lifecycle` Phase 3 审查步骤触发。
 
 ### Inputs
-- PR 编号（来源：`/code` 产出）
+- PR 编号与 Task Record（来源：`/code` 产出）
 
 ### Preconditions
 - `/code` 已完成 → PR 已创建
 
 ### Procedure
-1. 获取 PR diff 和元数据
-2. 双轴审查（规范轴 + 规格轴）
+1. 在本地 worktree/分支获取 PR diff 与元数据
+2. 双轴审查（规范轴 + 规格轴）+ TDD criterion coverage
 3. 输出结构化审查报告
-4. 编排器发布审查结果
-5. 等待 CI 通过后合并
-6. 关闭关联 Sub Issue
-7. 安全清理 Worktree（Preflight）
+4. primary 调用 `task_control{op:"submit-review"}` 发布结果
+5. CI 通过后 `task_control{op:"merge-task"}` 合并（工具执行清理）
 
 ### Outputs
 - 结构化审查报告（APPROVED / CHANGES_REQUESTED）
 - PR 已合并（条件满足时）
+- Worktree 已清理
 
 ### Failure
-- Critical/High → Request Changes
+- Critical/High → request-changes
 - Worktree 清理失败 → 记录警告，不阻塞
 
 ### Idempotency
@@ -162,5 +75,6 @@ fi
 - 已审查的 PR → 更新结论
 
 ### Prohibited Actions
+- **禁止使用 WebFetch 或任何 Web 工具获取远程 PR 代码** — 审查代码时必须本地读取源码文件
+- reviewer 不直接执行 `gh pr review` / `gh pr merge`（由 task_control 完成）
 - 不使用默认 --force 清理
-- 不直接执行 gh pr merge（Orchestrator 执行）

package/assets/skills/flow-setup/SKILL.md

@@ -1,46 +1,42 @@
 ---
 name: flow-setup
-description: 初始化项目文档结构，验证开发环境
+description: 初始化 — 探测环境 → 生成 workflow → 确认 Profile
 ---
 
 # flow-setup
 
-初始化项目文档结构，验证开发环境。
+初始化阶段：探测开发环境、生成缺失的 CI/release workflow、确认 AGENTS.md Project Profile。
+所有探测与写入由内核工具 `setup_control` 完成，本 skill 只定义流程，不复制工具实现。
 
-## Workflow
+## 核心：调用 setup_control
 
-### 1. 创建文档目录
-确保以下目录结构存在：
-```
-docs/
-├── prd/              # 产品需求文档
-├── adr/              # 架构决策记录
-└── dev/
-    ├── specs/        # 技术方案
-    ├── tasks/        # DAG 任务定义
-    ├── api/          # API 设计文档
-    ├── db/           # 数据库设计
-    ├── guides/       # 开发指南
-    └── handoff/      # 上下文交接
-```
+调用 `setup_control` 完成三个阶段：
 
-### 2. 验证环境
-```bash
-gh auth status
-git remote get-url origin
-```
-确保 gh CLI 已认证、项目已关联 GitHub 远程。
+1. `setup_control{op:"probe"}` — 探测 git/gh/CI/Profile，输出 readiness 报告
+2. `setup_control{op:"generate-workflows"}` — 缺失时生成 CI/release workflow 草案 + Setup PR（人工合入）
+3. `setup_control{op:"confirm-profile"}` — 用户确认后将 Profile 区块写入根 AGENTS.md
 
-### 3. 完成标记
-```bash
-mkdir -p .opencode/opencode-cabbage
-echo "setup-complete" > .opencode/opencode-cabbage/setup-complete
+Profile 区块格式（内核解析白名单，§9.1）：
+
+```markdown
+## Project Profile
+
+- test command: `npm test -- run`
+- test file patterns: `test/**/*.test.ts`
+- implementation file patterns: `src/**/*.ts`
+- tdd default mode: `strict`
+- version bump rule: `breaking→major, feature→minor, fix→patch`
+- version file: `package.json`
+- tag format: `v{version}`
+- release workflow: `.github/workflows/release.yml`
 ```
 
+未确认 Profile 时 `flow_control{op:"create-flow"}` 会阻断并提示先执行 `/setup`。
+
 ## Output
-- `docs/` 目录已就绪
-- 开发环境已验证
-- 可开始 `/requirements`
+- readiness 报告（development-ready / release-ready 逐项布尔）
+- `.github/workflows/` 草案（缺失时，经 Setup PR 人工合入）
+- 根 AGENTS.md `## Project Profile` 区块
 
 ## Contract
 
@@ -48,28 +44,29 @@ echo "setup-complete" > .opencode/opencode-cabbage/setup-complete
 由 `/setup` 命令触发。首次使用插件或切换新项目时执行。
 
 ### Inputs
-无外部输入。从当前工作目录检测项目状态。
+- 用户对 readiness 报告 / Profile 覆盖项的确认
 
 ### Preconditions
-无。不要求任何前置阶段。
+- gh CLI 已认证（宿主 `gh auth`）
 
 ### Procedure
-1. 创建 docs 目录结构
-2. 验证 gh CLI 和 GitHub 远程
-3. 写入完成标记
+1. 调用 `setup_control{op:"probe"}` 读取 readiness 报告
+2. 缺失 workflow 时调用 `setup_control{op:"generate-workflows"}` 生成草案
+3. 用户确认后调用 `setup_control{op:"confirm-profile"}` 写入 Profile
 
 ### Outputs
-- `docs/` 目录树（prd, adr, dev/specs, dev/tasks, dev/api, dev/db, dev/guides, dev/handoff）
-- `.opencode/opencode-cabbage/setup-complete` 标记文件
+- readiness 报告
+- workflow 草案（可选）
+- 根 AGENTS.md Profile 区块
 
 ### Failure
-- 目录创建失败 → 报告错误并退出
-- gh auth 失败 → 提示用户执行 `gh auth login`
+- gh auth 失败 → 提示用户执行 `gh auth login` 后重试
+- workflow 生成失败 → 报告错误并停止
 
 ### Idempotency
-- 已存在的目录跳过
-- 已存在 `setup-complete` 标记则跳过全部步骤
+- Profile 已确认 → 重复 confirm 覆盖写入（工具内读后写）
+- workflow 已存在 → 跳过生成
 
 ### Prohibited Actions
-- 不删除已有目录或文件
-- 不修改项目代码
+- 不手工编辑 AGENTS.md Profile 区块（由 setup_control 写回）
+- 不直接 push 或创建 Setup PR（工具内部执行）

package/assets/skills/flow-tasks/SKILL.md

@@ -1,151 +1,43 @@
 ---
 name: flow-tasks
-description: DAG 任务拆解 → Sub Issues 创建
+description: DAG 任务拆解 → Task Record（task_control）
 ---
 
 # flow-tasks
 
-将设计方案拆解为 DAG（有向无环图）任务，创建 GitHub Sub Issues。
+将设计方案拆解为 DAG（有向无环图）任务，并用 `task_control{op:"create-task"}` 创建 Task Record（GitHub Sub Issue）。
 
-## Prerequisites
-- `/design` 已完成 → `docs/dev/specs/<title>.md` 存在
-- Parent GitHub Issue 存在
+## 核心：调用 task_control
 
-## Workflow
+`task_control{op:"create-task", title:"<英文功能标题>", acceptance_criteria:"<JSON>", ...}` 创建 Sub Issue。
+内核负责 slug 派生与校验、标题规范（R3）、关联 Parent Issue——创建动作全部收敛到工具内。
 
-### 1. DAG 拆解
-将设计拆解为最小可执行单元，识别并行/串行关系。
+## DAG 拆解
 
-拆解原则：
-- 每个任务应在 1-2 小时内完成实现
-- 无依赖的任务标记为可并行
-- 任务粒度以"一个人可独立完成"为标准
+#### 拆解前自检
 
-DAG 使用 Mermaid 语法绘制，示例：
+1. **能否用一个任务完成？** — 如果功能足够内聚，不强拆多个任务
+2. **拆开后能否独立验证？** — 每个任务必须有独立的验收标准
+3. **拆开后耦合是否最低？** — 两个任务共享大量数据结构/模块 → 合并
 
-```mermaid
-graph TD
-  A["Task A（无依赖）"] --> B["Task B（依赖 A）"]
-  A --> C["Task C（依赖 A）"]
-  D["Task D（无依赖）"]
-```
+#### 反模式
 
-保存为 `docs/dev/tasks/<YYYY-MM-DD-NNN-slug>/DAG.md`。
+| 反模式 | 示例 | 正确做法 |
+|--------|------|----------|
+| 技术分层拆分 | "建表任务" → "DAO 任务" → "Service 任务" | 垂直切片：一个任务包含完整链路 |
+| 过度拆分 | 一个 CRUD 拆成四个任务 | 一个 CRUD 就是一个任务 |
+| 预留式拆分 | "先搭框架，后面任务再填内容" | 不要有空壳任务 |
 
-### 2. 创建任务文件
-每个任务 `docs/dev/tasks/<task-name>.md`：
+DAG 使用 Mermaid 语法绘制，保存为 `docs/dev/tasks/<YYYY-MM-DD-NNN-slug>/DAG.md`。
 
-```markdown
----
-name: "<task-name>"
-depends_on: ["<前置任务>"]
-labels: ["backend"]
-worktree_root: ".worktree/<task-name>/"
-test_commands:
-  - "npm test -- <test-file>"
-  - "npm run typecheck"
-verify_commands:
-  - "npm run lint"
-tdd:
-  mode: strict
-  min_cycles: 1
-acceptance:
-  - criteria: "<验收标准描述>"
-    verification_type: test | manual | lint
-    test_command: "<关联的测试命令>"
-  - criteria: "<另一条验收标准>"
-    verification_type: test
-    test_command: "npm test -- <other-test>"
----
-```
-
-Task frontmatter 新增字段说明：
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `test_commands` | `string[]` | TDD cycle 中运行的测试命令列表 |
-| `verify_commands` | `string[]` | final-verification 阶段运行的验证命令 |
-| `tdd.mode` | `"strict" \| "advisory"` | TDD 模式，默认 `strict` |
-| `tdd.min_cycles` | `number` | 最少 RED→GREEN cycle 数量，默认 `1` |
-| `acceptance` | `object[]` | 结构化验收标准列表 |
-| `acceptance[].criteria` | `string` | 验收标准描述 |
-| `acceptance[].verification_type` | `"test" \| "manual" \| "lint"` | 验证方式 |
-| `acceptance[].test_command` | `string` | 关联的测试命令（verification_type 为 test 时必填） |
-
-`tdd` 配置块为 `flow-tdd` skill 提供运行时参数。模式默认 `strict`，
-表示 Agent 必须遵循 RED→GREEN→final-regression→final-verification 完整流程。
-
-## 目标
-
-## 实现要点
-
-## 验收标准
-
-验收标准以结构化 `acceptance` 数组形式定义在 frontmatter 中（见上方模板）。
-每条标准包含 `criteria`（描述）、`verification_type`（验证方式）和 `test_command`（关联命令）。
-`flow-tdd` skill 在 final-verification 阶段逐条核验这些标准。
-
-## TDD 集成
-
-本 skill 生成的 `test_commands`、`verify_commands`、`tdd` 配置块和 `acceptance_criteria`
-是 `flow-tdd` skill 的输入。`flow-tdd` 根据这些字段执行 RED→GREEN cycle、
-final-regression 和 final-verification。
-
-## Worktree
-- 路径: `.worktree/<task-name>/`
-- 分支: `feat/<task-name>`
-- 创建时机: `/code` 阶段首次执行时自动创建
-- 清理时机: PR 合并后自动删除
-```
-
-### 3. 创建 Sub Issues
-
-```bash
-mkdir -p docs/dev/handoff
-cat > docs/dev/handoff/task-issue-body.md << 'EOF'
-## 依赖
-前置任务: <列表>
-
-## Worktree
-- 路径: `.worktree/<task-name>/`
-- 分支: `feat/<task-name>`
-
-## 描述
-...
-EOF
-gh issue create \
-  --title "<task-name>" \
-  --label "task" \
-  --parent <parent-number> \
-  --body-file docs/dev/handoff/task-issue-body.md
-```
-
-### 4. 提交任务文件
-任务定义文件通过 Planning PR 合入默认分支：
-
-```bash
-# 探测默认分支
-BASE=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' 2>/dev/null || echo "main")
-
-git checkout -b chore/plan-tasks-<slug> $BASE
-git add docs/dev/tasks/<YYYY-MM-DD-NNN-slug>/
-git commit -m "docs: <title> — 任务定义"
-git push origin chore/plan-tasks-<slug>
-gh pr create --title "docs: <title> — 任务定义" --base $BASE
-```
+## 任务定义文件
+
+每个任务一个文件 `docs/dev/tasks/<task-name>.md`，frontmatter 含 `test_commands` / `verify_commands` / `tdd` 配置块 / `acceptance` 结构化验收标准。
+这些字段是 `flow-tdd` skill 的输入（RED→GREEN cycle、final-regression、final-verification）。
 
 ## Output
 - `docs/dev/tasks/*.md` — 独立任务文件
-- GitHub Sub Issues 已创建（依赖关系在 body 中声明）
-- 任务文件通过 Planning PR 合入默认分支
-
-## Sub Issue 关闭时机
-Sub Issue 不在 `/tasks` 阶段关闭，而是在对应 PR 合并后自动关闭：
-
-| 阶段 | 动作 |
-|------|------|
-| `/code` | PR body 含 `Closes #<issue-num>`，合并后 GitHub 自动关闭 |
-| `/review` | 如 PR 未自动关闭 Sub Issue，reviewer 手动 `gh issue close <num>` |
+- GitHub Sub Issues（由 task_control 创建，依赖关系在 body 中声明）
 
 ## 后续
 - **/code** — 认领 Sub Issue 开始编码
@@ -157,20 +49,18 @@ Sub Issue 不在 `/tasks` 阶段关闭，而是在对应 PR 合并后自动关
 
 ### Inputs
 - `docs/dev/specs/<title>.md` — 技术方案
-- Parent Issue 编号
+- Flow Record 编号
 
 ### Preconditions
-- `/design` 已完成 → 技术方案和 ADR 存在
+- `/design` 已完成 → 技术方案和 ADR 存在（Planning Baseline 已合入）
 
 ### Procedure
-1. 基于技术方案拆解 DAG
-2. 创建 Task Manifest (`manifest.yaml`) 和任务文件
-3. 为每个任务创建 GitHub Sub Issue
-4. 通过 Planning PR 提交任务文件
+1. 基于技术方案拆解 DAG（Mermaid 图 + 任务文件）
+2. 为每个任务调用 `task_control{op:"create-task"}` 创建 Sub Issue
+3. 任务文件随 Planning PR 合入默认分支
 
 ### Outputs
-- `docs/dev/tasks/<feature-slug>/manifest.yaml` — 任务清单
-- `docs/dev/tasks/<feature-slug>/*.md` — 任务文件
+- `docs/dev/tasks/<feature-slug>/` — DAG 与任务文件
 - GitHub Sub Issues（含依赖声明）
 
 ### Failure
@@ -179,8 +69,9 @@ Sub Issue 不在 `/tasks` 阶段关闭，而是在对应 PR 合并后自动关
 
 ### Idempotency
 - 任务文件已存在 → 读取并更新
-- Sub Issue 已创建 → 更新而非重复创建
+- Sub Issue 已创建 → 内核检测同名冲突（未合并分支/worktree）并拒绝
 
 ### Prohibited Actions
 - 不跳过 DAG 依赖检查
+- 不绕过 task_control 手工创建 Sub Issue（由 create-task 完成）
 - 不直接 push 到默认分支

package/assets/skills/flow-tdd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: flow-tdd
-description: TDD Prompt 协议 — Phase A Advisory 层，定义 RED→GREEN self-reported 流程
+description: TDD Prompt 协议 — RED→GREEN 状态机 + tdd_checkpoint Runtime 证据
 ---
 
 # flow-tdd
@@ -10,7 +10,7 @@ TDD（Test-Driven Development）Prompt 协议，为所有编码阶段提供统
 
 ## Advisory Procedure
 
-Phase A Advisory 层协议：Agent 自行遵循 TDD 流程并 self-report 状态，无需工具拦截。
+Agent 自行遵循 TDD 流程并 self-report 状态。每个 stage 同时通过 `tdd_checkpoint` 提交证据。
 
 ### Cycle 状态机
 
@@ -64,7 +64,7 @@ Phase A Advisory 层协议：Agent 自行遵循 TDD 流程并 self-report 状态
 
 **约束：**
 - 测试必须有明确的 fail/pass 边界
-- 测试运行命令必须与 `test_commands` 中定义的一致
+- 测试运行命令必须与 Task 的 `test_commands` 中定义的一致
 - 记录测试失败输出作为 RED evidence
 
 **self-report 格式：**
@@ -119,7 +119,7 @@ Phase A Advisory 层协议：Agent 自行遵循 TDD 流程并 self-report 状态
 所有 cycle 完成后，运行项目全部测试套件，确认无回归。
 
 **约束：**
-- 必须运行 `test_commands` 中定义的全部命令
+- 必须运行 Task `test_commands` 中定义的全部命令
 - 所有测试必须通过
 - 如有失败 → 修复（不要求新 cycle，但需记录修复内容）
 
@@ -145,21 +145,19 @@ Phase A Advisory 层协议：Agent 自行遵循 TDD 流程并 self-report 状态
 
 ## Runtime Procedure
 
-> **Phase C 启用** — 以下为 Runtime Enforcement 协议占位，当前阶段不生效。
->
-> Phase C 将引入 `tdd_checkpoint` 工具在运行时拦截 RED/GREEN 状态切换，
-> 并将 evidence 写入 FlowRun 存储。Agent 不直接调用这些工具的时机和方式
-> 由 Phase C 的 `tdd_checkpoint` 工具实现决定。
-
-<!--
-Phase C 启用后的 Runtime Procedure:
-1. cycle-start → tdd_checkpoint({ stage: "cycle-start", task_id })
-2. red → tdd_checkpoint({ stage: "red", evidence: test_output, task_id })
-3. green → tdd_checkpoint({ stage: "green", evidence: test_output, task_id })
-4. abandon-cycle → tdd_checkpoint({ stage: "abandon-cycle", reason, task_id })
-5. final-regression → tdd_checkpoint({ stage: "final-regression", evidence: full_test_output, task_id })
-6. final-verification → tdd_checkpoint({ stage: "final-verification", evidence: criteria_checklist, task_id })
--->
+每个 stage 通过 `tdd_checkpoint` 提交证据到 Task Record 单个受控评论（marker 包裹，唯一证据源）。
+工具亲自执行测试，不接受内联 evidence；RED 有效性校验（失败分类 + 实现文件相对基线未变 + 输入未偷换）。
+
+| Stage | tdd_checkpoint op |
+|-------|-------------------|
+| cycle-start | `tdd_checkpoint{op:"cycle-start", task_id, criterion_id, test_paths, test_selector}` |
+| red | `tdd_checkpoint{op:"red", task_id, cycle_id, test_selector}` — 测试失败 + 实现文件未变 |
+| green | `tdd_checkpoint{op:"green", task_id, cycle_id, test_selector}` — 同 selector 通过 |
+| abandon-cycle | `tdd_checkpoint{op:"abandon-cycle", task_id, cycle_id, reason}` |
+| final-regression | `tdd_checkpoint{op:"final-regression", task_id}` — 全量测试通过 |
+| final-verification | `tdd_checkpoint{op:"final-verification", task_id}` — 每条 criterion 有 pass cycle |
+
+纯文档变更豁免：`tdd_checkpoint{op:"not-applicable"}`（仅 primary）；其他豁免须用户批准（`exempt-request`）。
 
 ## Contract
 
@@ -167,27 +165,27 @@ Phase C 启用后的 Runtime Procedure:
 由编码阶段（`flow-code`）自动触发。Agent 在开始编码任务时加载 `flow-tdd` skill 获取 TDD 流程约束。
 
 ### Inputs
-- Task 定义中的 `acceptance_criteria`（来源：`flow-tasks` 产出）
-- Task 定义中的 `test_commands`（来源：`flow-tasks` 产出）
-- Task 定义中的 `verify_commands`（来源：`flow-tasks` 产出）
-- Task 定义中的 `tdd` 配置块 — `mode`（`strict`/`advisory`）、`min_cycles`（来源：`flow-tasks` 产出）
+- Task Record 中的 `acceptance_criteria`（来源：`flow-tasks` 产出）
+- Task Record 中的 `test_commands`（来源：`flow-tasks` 产出）
+- Task Record 中的 `verify_commands`（来源：`flow-tasks` 产出）
+- Task Record 中的 `tdd` 配置块 — `mode`（`strict`/`advisory`）、`min_cycles`（来源：`flow-tasks` 产出）
 
 ### Preconditions
-- Task 文件存在，包含 `acceptance_criteria`、`test_commands`、`tdd` 配置块
-- 测试运行环境就绪（`npm install` 已完成）
+- Task Record 存在，包含 `acceptance_criteria`、`test_commands`、`tdd` 配置块
+- 测试运行环境就绪（worktree 内依赖已安装）
 
 ### Procedure
 1. 读取 Task 的 `acceptance_criteria`、`test_commands`、`verify_commands`
-2. **Advisory Mode**：为每个验收标准识别对应的测试用例
-3. 执行 `cycle-start` → 声明当前 cycle 目标
-4. 执行 `red` → 编写测试，验证失败
-5. 执行 `green` → 最小实现，验证通过
+2. 为每个验收标准识别对应的测试用例
+3. 执行 `cycle-start` → 声明当前 cycle 目标并调用 tdd_checkpoint
+4. 执行 `red` → 编写测试，验证失败，提交 evidence
+5. 执行 `green` → 最小实现，验证通过，提交 evidence
 6. 重复 cycle 直到所有 criterion 覆盖
 7. 执行 `final-regression` → 运行全部测试
 8. 执行 `final-verification` → 逐条对照 acceptance_criteria
 
 ### Outputs
-- 每个 cycle 的 self-report（提交到 commit message 或 PR body）
+- 每个 cycle 的 self-report + tdd_checkpoint evidence（Task Record 评论）
 - `final-regression` 报告（测试通过/失败统计）
 - `final-verification` 报告（criterion 覆盖情况）
 
@@ -205,4 +203,5 @@ Phase C 启用后的 Runtime Procedure:
 - 不跳过 RED 阶段直接进入 GREEN
 - 不跳过 final-regression 直接 commit
 - 不在 abandon-cycle 后保留修改
-- 不修改 `tdd` 配置块中的 `mode` 和 `min_cycles` 值
+- 不修改 Task `tdd` 配置块中的 `mode` 和 `min_cycles` 值
+- 不伪造/内联 tdd_checkpoint evidence（工具亲自执行测试）