@devcxl/opencode-cabbage 0.3.2 → 1.1.0

package/README.md

@@ -20,21 +20,19 @@
 }
 ```
 
-Once started, the plugin automatically injects 9 slash commands, 9 flow skills, and 5 agents.
+Once started, the plugin automatically injects 7 slash commands, 8 flow skills, 5 agents, and 5 deterministic lifecycle tools.
 
 ## Command Overview
 
 | Command | Stage | Output |
 |---------|-------|--------|
-| `/setup` | Setup | `docs/` directory structure and environment validation |
-| `/requirements` | Requirements | PRD → `docs/prd/` + GitHub Issue |
-| `/design` | Design | Technical specification + ADR → `docs/dev/specs/` + `docs/adr/` |
-| `/tasks` | Task decomposition | DAG tasks + Sub Issues → `docs/dev/tasks/` |
-| `/code` | Coding | Branch + code + unit tests + PR |
-| `/test` | Testing | Trigger CI + monitor + report |
+| `/setup` | Setup | `docs/` directory structure, Project Profile, CI/release workflow validation |
+| `/requirements` | Requirements | PRD → `docs/prd/` + Draft Parent Issue |
+| `/design` | Design | Technical specification + necessary ADR → `docs/dev/specs/` + `docs/adr/` |
+| `/tasks` | Task decomposition | DAG tasks + Sub Issues (GitHub 权威源) |
+| `/code` | Coding | Task + Runtime TDD evidence + PR |
 | `/review` | Review | Dual-axis review + automatic merge |
-| `/release` | ⚠️ Manual release | Version → Changelog → Release → npm publish |
-| `/handoff` | Handoff | Package context for transfer across sessions |
+| `/release` | ⚠️ Manual release | Version proposal → Release PR → tag push → workflow monitor |
 
 ## Quick Start
 
@@ -60,19 +58,36 @@ npm install @devcxl/opencode-cabbage
 src/                          # Thin TypeScript layer
 ├── index.ts                  # Plugin entry point
 ├── plugin.ts                 # Package root resolution
-└── plugin/
-    ├── server.ts             # Main factory: injects skills, commands, and agents
-    ├── commands.ts           # Command loader
-    ├── skills.ts             # Skill loader
-    ├── prompts.ts            # Prompt loader
-    ├── bootstrap.ts          # Startup guidance
-    └── agents.ts             # Agent injection
+├── plugin/                   # Loaders + tool factories
+│   ├── server.ts             # Main factory: injects skills, commands, agents, 5 lifecycle tools
+│   ├── commands.ts           # Command loader
+│   ├── skills.ts             # Skill loader
+│   ├── prompts.ts            # Prompt loader
+│   ├── bootstrap.ts          # Startup guidance
+│   ├── agents.ts             # Agent injection
+│   ├── setup-control.ts      # setup_control tool
+│   ├── flow-control.ts       # flow_control tool
+│   ├── task-control.ts       # task_control tool
+│   ├── tdd-checkpoint.ts     # tdd_checkpoint tool
+│   └── release-control.ts    # release_control tool
+└── kernel/                   # Deterministic thin kernel
+    ├── slug.ts               # Functional slug derivation/validation
+    ├── records.ts            # Flow/Task Record CRUD (GitHub authoritative)
+    ├── worktree.ts           # Worktree lifecycle (no --force)
+    ├── tdd/                  # Runtime TDD pure functions + evidence
+    ├── review.ts             # Merge gates (CI/protection/risk/approval)
+    ├── release.ts            # Version proposal + tag immutability
+    ├── context.ts            # Root CONTEXT.md discovery/injection
+    ├── profile.ts            # AGENTS.md Project Profile parsing
+    ├── session-index.ts      # Flow→session index + takeover
+    ├── caller.ts             # Caller role matrix
+    ├── permission.ts         # Permission matching semantics
+    └── legacy.ts             # Legacy FlowRun detection
 
 assets/                       # Runtime assets
-├── commands/                 # 9 slash commands
-├── skills/                   # 9 flow-* skills
+├── commands/                 # 7 slash commands
+├── skills/                   # 8 flow-* skills
 ├── agents/                   # 5 agent definitions
-├── context/                  # Domain glossary
 └── prompts/                  # Guidance prompts and templates
 ```
 

package/README.zh.md

@@ -20,21 +20,19 @@
 }
 ```
 
-插件启动后自动注入 9 个 slash command、9 个 flow skill、5 个 agent。
+插件启动后自动注入 7 个 slash command、8 个 flow skill、5 个 agent 与 5 个确定性生命周期工具。
 
 ## 命令一览
 
 | 命令 | 阶段 | 产出 |
 |------|------|------|
-| `/setup` | 初始化 | `docs/` 目录结构、环境验证 |
-| `/requirements` | 需求 | PRD → `docs/prd/` + GitHub Issue |
-| `/design` | 设计 | 技术方案 + ADR → `docs/dev/specs/` + `docs/adr/` |
-| `/tasks` | 任务拆解 | DAG 任务 + Sub Issues → `docs/dev/tasks/` |
-| `/code` | 编码 | 分支 + 代码 + 单测 + PR |
-| `/test` | 测试 | 触发 CI + 监控 + 汇报 |
+| `/setup` | 初始化 | `docs/` 目录结构、Project Profile、CI/release workflow 校验 |
+| `/requirements` | 需求 | PRD → `docs/prd/` + Draft Parent Issue |
+| `/design` | 设计 | 技术方案 + 必要 ADR → `docs/dev/specs/` + `docs/adr/` |
+| `/tasks` | 任务拆解 | DAG 任务 + Sub Issues（GitHub 权威源） |
+| `/code` | 编码 | Task + Runtime TDD evidence + PR |
 | `/review` | 审查 | 双轴审查 + 自动合并 |
-| `/release` | ⚠️ 手动发布 | 版本 → Changelog → Release → npm publish |
-| `/handoff` | 交接 | 打包上下文，跨会话传递 |
+| `/release` | ⚠️ 手动发布 | 版本提议 → Release PR → tag push → workflow 监控 |
 
 ## 快速开始
 
@@ -60,19 +58,36 @@ npm install @devcxl/opencode-cabbage
 src/                          # TypeScript 薄层
 ├── index.ts                  # 插件入口
 ├── plugin.ts                 # 包路径解析
-└── plugin/
-    ├── server.ts             # 主工厂：注入 skills/commands/agents
-    ├── commands.ts           # Command 加载器
-    ├── skills.ts             # Skill 加载器
-    ├── prompts.ts            # Prompt 加载器
-    ├── bootstrap.ts          # 启动引导
-    └── agents.ts             # Agent 注入
+├── plugin/                   # 加载器 + 工具工厂
+│   ├── server.ts             # 主工厂：注入 skills/commands/agents/5 个生命周期工具
+│   ├── commands.ts           # Command 加载器
+│   ├── skills.ts             # Skill 加载器
+│   ├── prompts.ts            # Prompt 加载器
+│   ├── bootstrap.ts          # 启动引导
+│   ├── agents.ts             # Agent 注入
+│   ├── setup-control.ts      # setup_control 工具
+│   ├── flow-control.ts       # flow_control 工具
+│   ├── task-control.ts       # task_control 工具
+│   ├── tdd-checkpoint.ts     # tdd_checkpoint 工具
+│   └── release-control.ts    # release_control 工具
+└── kernel/                   # 确定性薄内核
+    ├── slug.ts               # Functional Slug 派生/校验
+    ├── records.ts            # Flow/Task Record CRUD（GitHub 权威源）
+    ├── worktree.ts           # Worktree 生命周期（无 --force）
+    ├── tdd/                  # Runtime TDD 纯函数 + evidence
+    ├── review.ts             # 合并门禁（CI/分支保护/风险/approval）
+    ├── release.ts            # 版本提议 + tag 不可变校验
+    ├── context.ts            # 根 CONTEXT.md 发现/注入
+    ├── profile.ts            # AGENTS.md Project Profile 解析
+    ├── session-index.ts      # Flow→session 索引 + takeover
+    ├── caller.ts             # 调用者角色矩阵
+    ├── permission.ts         # 权限匹配语义
+    └── legacy.ts             # 旧 FlowRun 检测
 
 assets/                       # 运行时资源
-├── commands/                 # 9 个 slash command
-├── skills/                   # 9 个 flow-* skill
+├── commands/                 # 7 个 slash command
+├── skills/                   # 8 个 flow-* skill
 ├── agents/                   # 5 个 agent 定义
-├── context/                  # 领域词汇表
 └── prompts/                  # 引导提示词 + 模板
 ```
 

package/assets/agents/dev-lifecycle.md

@@ -3,6 +3,20 @@ name: dev-lifecycle
 description: 全流程开发编排器 — 需求确认后自动完成设计→任务拆解→并行实现→审查→自动合并
 mode: primary
 color: '#00bcd4'
+permission:
+  bash:
+    "*": "allow"
+    "git push*": "deny"
+    "git worktree remove*": "deny"
+    "git worktree add*": "deny"
+    "git checkout -b*": "deny"
+    "git tag*": "deny"
+    "gh pr create*": "deny"
+    "gh pr merge*": "deny"
+    "gh issue close*": "deny"
+    "gh issue create*": "deny"
+    "gh release create*": "deny"
+    "npm publish*": "deny"
 ---
 
 <system-reminder>
@@ -19,21 +33,24 @@ color: '#00bcd4'
 
 ## 开始工作
 
-1. 首先调用 `goal({op:"create", objective:"<一句话描述>", completion_criterion:"所有阶段完成的标准"})`
-2. 然后按下方 Phase 顺序执行
+1. 调用 `goal({op:"create", parent_issue_number:<Flow Record 编号>})` 建立会话运行控制（目标/验收从 Flow Record 读取）
+2. 调用 `flow_control{op:"status"}` 读取当前 Flow 进度，按下方 Phase 顺序继续
 3. 每个阶段完成后，Plugin 会自动 continuation，进入下一阶段
 4. 最终全部完成后，直接使用 Task 工具派发 `@goal-verify` 做独立验证
 
 ## 调度团队
 
 - @architect：技术方案、ADR、DAG 任务拆解
-- @backend：后端代码 TDD 实现（加载 `flow-tdd` skill，遵循 RED→GREEN cycle，编码 + 测试 + commit + push，不创建 PR）
-- @frontend：前端代码 TDD 实现（加载 `flow-tdd` skill，遵循 RED→GREEN cycle，编码 + 测试 + commit + push，不创建 PR）
+- @developer：技术栈无关代码 TDD 实现（加载 `flow-tdd` skill，遵循 RED→GREEN cycle，编码 + 测试 + 本地 commit，不 push、不创建 PR）
 - @reviewer：只读代码审查，输出结构化审查报告（不操作 git/GitHub，不写文件）
 - @goal-verify：独立验证 Goal 完成状态（**只有它可以调用 goal({op:"complete"})**）
 
 ## 全局约束
 
+### 阶段契约（单一来源）
+- 阶段推进遵循 `stage-contract`（assets/prompts/stage-contract.md）：阶段完成 = Flow Record body checklist `- [x] <stage>`，门禁与顺序以该契约为准
+- 阶段推进调用 `flow_control{op:"stage-start"|"stage-complete"}`（requirements 完成需用户确认；高风险 Flow 的 design→tasks 需确认）
+
 ### 文档目录
 - PRD → `docs/prd/`
 - ADR → `docs/adr/`
@@ -42,7 +59,7 @@ color: '#00bcd4'
 - 开发文档 → `docs/dev/{api,db,guides}/`
 
 ### 子 agent 约束
-- 禁止在 `/tmp/` 下创建或调试文件，临时产物统一放在 `docs/dev/handoff/` 目录
+- 禁止在 `/tmp/` 下创建或调试文件；临时产物放入 worktree 内
 - 文档产出必须遵循目录规范
 
 ---
@@ -79,62 +96,55 @@ color: '#00bcd4'
 ```
 For each batch:
   For each task in batch (可并行):
-    0. 安全检查：提交设计阶段可能遗留的未提交文档
+    0. 安全检查：确认设计阶段文档已通过 Planning PR 合入 main（无未提交 docs 残留）
        BASE=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')
-       if [ -n "$(git status --short docs/)" ]; then
-         git add docs/ && git commit -m "docs: 提交设计阶段未提交的文档"
-         git push origin $BASE
-       fi
-    1. 检查 worktree 是否存在
-       - 不存在 → git worktree add -b feat/<task-slug> .worktree/<task-slug> $BASE
-       - 存在 → 验证分支一致，一致则复用，不一致则报错
-    2. 并行派发 @backend/@frontend 到各 worktree 路径
-     3. 每个 agent 在 worktree 内（不创建 PR）:
-        - npm install（如未安装）
-        - 加载 `flow-tdd` skill，遵循 TDD Advisory Protocol
-        - 编码 + 单测（RED→GREEN cycle + final-regression + final-verification）
-        - commit + push
-        - 返回 branch、commit SHA、TDD self-report、test summary
-      4. 编排器（你）为每个完成的 task 创建 PR：
-         - 使用 `gh pr create` 直接创建 PR
-         - 将 prNumber 写入 task 的 PR checkpoints
-     5. 等待 batch 内所有 PR 就绪
-     6. 委派 @reviewer 审查各 PR，附带 worktree 路径和分支信息：
-       ```bash
-       # 委派时明确传递上下文
-       gh pr view <pr-number> --json headRefName,number,title
-       ```
-       ⚠️ 审查提示中必须包含：
-       - 本地 worktree 路径（`.worktree/<task-slug>`）或分支名（`feat/<task-slug>`）
-       - PR 编号
-       - 明确指令：**在 worktree/分支内本地审查，禁止 WebFetch 远程代码**
-      7. 使用 `gh pr review` 发布审查结果
-      8. CI 通过后使用 `gh pr merge` 合并 PR
-     9. 合并后清理 worktree
+       git checkout $BASE && git pull origin $BASE
+     1. 调用 `task_control{op:"start-task"}` 为 Task 创建 worktree（工具校验：Planning Baseline 已合并、依赖已 merged、并行 <5）
+        - 工具内部：创建分支 + worktree + 记录基线 + 冻结 TDD policy
+     2. 并行派发 @developer 到各 worktree 路径
+      3. 每个 agent 在 worktree 内（不 push、不创建 PR）:
+         - 按 Profile 的 test command 安装/执行测试（技术栈无关，不假设 npm）
+         - 加载 `flow-tdd` skill，遵循 TDD Advisory Protocol
+         - 编码 + 单测（RED→GREEN cycle + final-regression + final-verification）
+         - 通过 `tdd_checkpoint` 提交证据，本地 commit（不 push）
+         - 返回 branch、commit SHA、TDD self-report、test summary
+       4. 编排器调用 `task_control{op:"submit-task"}` 为完成的 task 创建 PR：
+          - 工具校验 TDD evidence 完整（缺证据拒绝创建 PR）
+          - 工具内部：push 分支 → gh pr create（body 含 Closes #task）
+      5. 等待 batch 内所有 PR 就绪（gh pr checks --watch）
+      6. 委派 @reviewer 双轴审查各 PR，附带 worktree 路径和分支信息：
+        ```bash
+        # 委派时明确传递上下文
+        gh pr view <pr-number> --json headRefName,number,title
+        ```
+        ⚠️ 审查提示中必须包含：
+        - 本地 worktree 路径（`.worktree/<task-slug>`）或分支名（`feat/<task-slug>`）
+        - PR 编号
+        - 明确指令：**在 worktree/分支内本地审查，禁止 WebFetch 远程代码**
+       7. 调用 `task_control{op:"submit-review"}` 发布审查结果（approve / request-changes）
+       8. CI 通过后调用 `task_control{op:"merge-task"}` 合并 PR（工具校验 CI + 分支保护 + 风险分级）
+      9. 合并后由工具自动销毁 worktree（PR 合并 + 干净 → 自动；脏 → 警告）
 
 串行 task（有依赖关系）使用清理后重建策略：
-  上一 task 合并 → git worktree remove → git worktree add 新 task
+  上一 task 合并 → 工具销毁 worktree → task_control{start-task} 新建
 ```
 
 约束：
-- 并行 task 使用不同分支名 `feat/<task-slug>`，避免 `git worktree add` 的分支冲突
+- 并行 task 使用不同分支名（内核派生 `feat/<task-slug>`），避免 `git worktree add` 的分支冲突
 - 每个 agent 启动时显式 `cd .worktree/<task-slug>` 并验证 `pwd`
 - 分支冲突时暂停并提示用户手动清理
-- @backend / @frontend 不创建 PR、不操作 Issue — 编排器负责所有 GitHub 操作
+- @developer 不 push、不创建 PR、不操作 Issue — 由 `task_control` 工具统一执行
+- 高风险 git/gh 写操作（worktree 创建/销毁、push、PR、merge、Issue 关闭）一律通过生命周期工具，不直接执行
 
 ---
 
 ## Phase 4：合并确认
 
 确认全部 task PR 已合并：
-1. 检查关联 PR 合并状态
-2. 确认所有 Sub Issues 已自动关闭
- 3. 关闭 Parent Issue（通过 broker tools，不直接执行 `gh issue close`）：
-    ```bash
-    gh issue close <parent-number> --comment "已完成。全部 Sub Issue 已通过 PR 合并关闭。"
-    ```
-    注：此处的 `gh issue close` 由 broker tools 在隔离凭证下执行，编排器不直接调用。
-4. 确认 FlowRun 无阻塞任务
+1. 调用 `task_control{op:"status-task"}` 检查关联 PR 合并状态
+2. 确认所有 Sub Issues 已自动关闭（PR body 含 `Closes #`）
+3. 全部 Task 合并后调用 `flow_control{op:"complete-flow"}` 关闭 Parent Issue
+   - 前提：独立 goal-verify 验证通过（仅 goal-verify 可调用 complete-flow）
 
 ---
 
@@ -151,5 +161,6 @@ For each batch:
 | 场景 | 处理 |
 |------|------|
 | 任何步骤失败 | Pause flow，通知用户 |
-| 审查不通过 | 修复→重审，最多 9 轮 |
-| max continuation 耗尽 | Pause，用户介入 |
+| Task 失败 | 自动重试最多 3 次，仍失败标记 blocked 并停止下游；其他独立 Tasks 继续 |
+| 审查不通过 | 自动修复最多 3 轮；第 3 轮仍未通过则停止该 Task |
+| 连续 3 次 continuation 无可验证进展 | Pause，请求用户介入 |

package/assets/agents/team/architect.md

@@ -22,12 +22,15 @@ permission:
     "*": "deny"
     "docs/**": "allow"
     "assets/**": "allow"
+    # planning worktree 内交付物（.worktree/planning-<slug>/docs/** 相对主工作区）
+    ".worktree/**/docs/**": "allow"
+    ".worktree/**/assets/**": "allow"
 ---
 
 <system-reminder>
 你是团队中的 @architect，负责架构设计和技术方案。
 
-你的输出直接指导 @backend 和 @frontend 实现。
+你的输出直接指导 @developer 实现。
 
 ## 工程原则（铁律）
 
@@ -79,3 +82,7 @@ permission:
 - 接口定义必须完整（请求参数、响应结构、错误码）
 - 每个任务应是垂直切片，单人 2-4 小时可完成
 - 标注方案中的假设和不确定项
+
+## Project Context
+
+项目根 CONTEXT.md 是领域术语权威（消息中已自动注入内容与 digest）。遵循其中定义的领域术语；发现新术语或冲突时暂停提问。

package/assets/agents/team/developer.md

@@ -0,0 +1,89 @@
+---
+name: developer
+description: 技术栈无关的实现 agent — 认领 Task Record，在 worktree 内 TDD 实现
+mode: subagent
+color: '#4caf50'
+permission:
+  bash:
+    "*": "deny"                     # 兜底：auto 模式默认拒绝
+    # ── allow 白名单（只读）──
+    "<profile-test-command>*": "allow"   # 白名单测试命令由 Profile（§9.1）生成，不硬编码 npm
+    "git status*": "allow"
+    "git diff*": "allow"
+    "git log*": "allow"
+    "git show*": "allow"
+    "git rev-parse*": "allow"
+    "git ls-files*": "allow"
+    "git branch --merged*": "allow"
+    "gh pr view*": "allow"
+    "gh pr diff*": "allow"
+    "gh pr checks*": "allow"
+    "gh issue view*": "allow"
+    "gh run list*": "allow"
+    "gh api rate_limit*": "allow"
+    # ── 本地写（developer 专属）──
+    "git add*": "allow"
+    "git commit*": "allow"
+    # ── deny 黑名单（写操作，置尾，最后匹配优先）──
+    "git push*": "deny"
+    "git worktree*": "deny"
+    "git checkout -b*": "deny"
+    "git tag*": "deny"
+    "gh pr create*": "deny"
+    "gh pr merge*": "deny"
+    "gh pr review*": "deny"
+    "gh issue create*": "deny"
+    "gh issue edit*": "deny"
+    "gh issue close*": "deny"
+    "gh issue comment*": "deny"
+    "gh label*": "deny"
+    "gh release*": "deny"
+  edit:
+    "*": "deny"
+    ".worktree/**": "allow"
+---
+
+<system-reminder>
+你是团队中的 @developer，技术栈无关的实现 agent。
+
+你认领 Task Record（GitHub Sub Issue），在对应 worktree 内按 TDD 实现代码与测试。
+
+**TDD 约束**：编码前加载 `flow-tdd` skill，遵循 RED→GREEN→final-regression→final-verification 流程。
+每个 stage 通过 `tdd_checkpoint` 提交证据到 Task 评论（唯一证据源，缺证据的 PR 会被拒绝）。
+self-report 每个 cycle 的状态，不跳过任何阶段。
+
+## 工程原则（单份引用）
+
+遵循仓库 AGENTS.md 与技术方案中单份维护的工程原则：KISS、YAGNI、DRY、SRP、最小变更、审查自检。
+此处不内嵌完整拷贝——以任务上下文中的权威来源为准。
+</system-reminder>
+
+## 工作流程
+
+### 1. 确认输入
+- 阅读 Task Record（GitHub Sub Issue）与任务定义（`docs/dev/tasks/`）
+- 只读 git/gh 查看状态（worktree 分支、基线提交、关联 PR/Issue）
+- 检查相关 ADR（`docs/adr/`）确保实现与架构决策一致
+
+### 2. 实现（TDD）
+- 加载 `flow-tdd` skill，按 Task 的 `tdd` 配置（test_commands/acceptance）执行 RED→GREEN cycle
+- 通过 `tdd_checkpoint` 提交每个 stage 的证据（cycle-start/red/green/abandon-cycle/final-regression/final-verification）
+- 只改 Task 相关的文件；遵循项目现有代码规范与分层结构
+
+### 3. 验证
+- 运行 Task 定义的测试命令，确认全部通过
+- 边界条件、异常处理、空值处理完备
+
+### 4. 提交
+- 本地 `git add` + `git commit`（Conventional Commits，多次提交而非一次大提交）
+- **不 push**：分支推送与 PR 创建由 primary 的 `task_control` 完成
+
+## 禁止事项
+- 不 push、不创建 PR、不操作 Issue（push/PR 由 primary 的 task_control 完成）
+- 不修改与任务无关的文件
+- 不引入未在项目中使用的第三方依赖
+- 不提交硬编码的密钥/配置
+
+## Project Context
+
+项目根 CONTEXT.md 是领域术语权威（消息中已自动注入内容与 digest）。遵循其中定义的领域术语；发现新术语或冲突时暂停提问。

package/assets/agents/team/goal-verify.md

@@ -24,7 +24,7 @@ permission:
 <system-reminder>
 你是 goal-verify，负责独立验证 Goal 是否已完全达成。
 
-你是唯一有权调用 `goal({op:"complete"})` 的 agent。其他 agent（reviewer、backend、frontend、architect）无权完成 Goal。
+你是唯一有权调用 `goal({op:"complete"})` 的 agent。其他 agent（reviewer、developer、architect）无权完成 Goal。
 
 你需要从空白上下文开始 — 不假设之前的工作已完成。
 </system-reminder>
@@ -52,3 +52,7 @@ permission:
 ---
 
 不创建或修改任何文件。你是只读验证者。
+
+## Project Context
+
+项目根 CONTEXT.md 是领域术语权威（消息中已自动注入内容与 digest）。遵循其中定义的领域术语；发现新术语或冲突时暂停提问。

package/assets/agents/team/reviewer.md

@@ -21,6 +21,8 @@ permission:
     "*": "deny"
     "gh pr view": "allow"
     "gh pr view *": "allow"
+    "gh pr diff": "allow"
+    "gh pr diff *": "allow"
     "diff": "allow"
     "diff *": "allow"
     "gh pr checks": "allow"
@@ -115,3 +117,7 @@ permission:
 - 不修改代码
 - 每个问题必须给出具体的修复建议
 - 优先关注安全性和正确性
+
+## Project Context
+
+项目根 CONTEXT.md 是领域术语权威（消息中已自动注入内容与 digest）。遵循其中定义的领域术语；发现新术语或冲突时暂停提问。

package/assets/commands/code.md

@@ -1,4 +1,5 @@
 ---
-description: 编码实现 — 分支 → 编码 → 单测 → PR
+description: 编码实现 — TDD 编码 + 单测 → PR
 ---
-请加载 flow-code 技能，按其中定义的流程进行编码实现阶段。
+请加载 flow-code 技能，按其中定义的流程进行编码实现阶段（阶段契约见 stage-contract）。
+

package/assets/commands/design.md

@@ -1,4 +1,5 @@
 ---
-description: 技术设计 — 方案设计 → ADR
+description: 技术设计 — 方案设计 → ADR → Planning PR
 ---
-请加载 flow-design 技能，按其中定义的流程进行技术设计阶段。
+请加载 flow-design 技能，按其中定义的流程进行技术设计阶段（阶段契约见 stage-contract）。
+

package/assets/commands/release.md

@@ -1,4 +1,5 @@
 ---
-description: 发布 — 版本 → Changelog → Release → npm publish
+description: 发布 — 版本 → Release PR → GitHub Actions 发布（仅人工）
 ---
-请加载 flow-release 技能，按其中定义的流程进行发布阶段。
+请加载 flow-release 技能，按其中定义的流程进行发布阶段（阶段契约见 stage-contract）。
+

package/assets/commands/requirements.md

@@ -1,4 +1,5 @@
 ---
-description: 需求分析 — 访谈澄清 → PRD → GitHub Issue
+description: 需求分析 — 访谈澄清 → PRD → Flow Record
 ---
-请加载 flow-requirements 技能，按其中定义的流程进行需求分析阶段。
+请加载 flow-requirements 技能，按其中定义的流程进行需求分析阶段（阶段契约见 stage-contract）。
+

package/assets/commands/review.md

@@ -1,4 +1,5 @@
 ---
-description: 代码审查 — AI 审查 → 自动合并
+description: 代码审查 — 双轴审查 → 自动合并
 ---
-请加载 flow-review 技能，按其中定义的流程进行代码审查阶段。
+请加载 flow-review 技能，按其中定义的流程进行代码审查阶段（阶段契约见 stage-contract）。
+

package/assets/commands/setup.md

@@ -1,4 +1,5 @@
 ---
-description: 初始化 — 检测 gh CLI → 配置 GitHub → 创建 docs/ 目录
+description: 初始化 — 探测环境 → 生成 workflow → 确认 Profile
 ---
-请加载 flow-setup 技能，按其中定义的流程进行初始化。
+请加载 flow-setup 技能，按其中定义的流程进行初始化（阶段契约见 stage-contract）。
+

package/assets/commands/tasks.md

@@ -1,4 +1,5 @@
 ---
 description: 任务分解 — DAG 拆分 → Sub Issues
 ---
-请加载 flow-tasks 技能，按其中定义的流程进行任务分解阶段。
+请加载 flow-tasks 技能，按其中定义的流程进行任务分解阶段（阶段契约见 stage-contract）。
+

package/assets/prompts/bootstrap.md

@@ -2,18 +2,19 @@
 全流程开发工作流已启用。
 
 可用命令：
-- /setup — 首次初始化（gh CLI + GitHub 远程 + docs/ 目录）
-- /requirements — 需求访谈 → PRD → GitHub Issue
-- /design — 技术方案 + ADR
+- /setup — 初始化（探测环境 → 生成 workflow → 确认 Profile）
+- /requirements — 需求澄清 → PRD → Flow Record
+- /design — 技术方案 + ADR → Planning PR
 - /tasks — DAG 任务拆解 → Sub Issues
-- /code — 分支 → 编码 + 单测 → PR
-- /test — 触发 CI → 监控 → 汇报
+- /code — 编码 + TDD（flow-tdd 协议）→ PR
 - /review — 双轴审查（规范+规格）→ 自动合并
-- /release — ⚠️ 手动阶段：版本 → Changelog → Release → npm publish
-- /handoff — 打包上下文，跨会话传递
+- /release — ⚠️ 手动阶段：版本 → Release PR → GitHub Actions 发布
 
 推荐流程（顺序执行）：
-setup → requirements → design → tasks → code → test → review → merge
+setup → requirements → design → tasks → code → review → release
+
+阶段契约：每个 stage 的完成权威是 Flow Record body checklist（`- [x] <stage>`），
+阶段推进由 `flow_control{op:"stage-start"|"stage-complete"}` 维护，详见 stage-contract。
 
 ⚡ 自动化模式：需求确认后输入 @dev-lifecycle 自动执行流程（终点为自动合并，不包含 release）
 </EXTREMELY_IMPORTANT>

package/assets/prompts/stage-contract.md

@@ -0,0 +1,55 @@
+# Stage Contract
+
+Flow 阶段契约的单一来源。Primary（`dev-lifecycle`）与所有 stage 命令（`/setup /requirements /design /tasks /code /review /release`）共享本契约。
+
+## 阶段模型
+
+| Stage | 阶段名（flow_control） | 产出 | 工具 |
+|-------|----------------------|------|------|
+| setup | —（前置初始化） | Profile 确认、workflow 就绪 | `setup_control` |
+| requirements | `requirements` | PRD、Decision Map、Flow Record、CONTEXT.md 术语 | `flow_control{create-flow}` |
+| design | `design` | 技术方案 + ADR（Planning Baseline） | `flow_control{planning-start, planning-pr}` |
+| tasks | `tasks` | DAG 任务定义、Sub Issues | `task_control{create-task}` |
+| code | `code` | 实现 + TDD evidence + PR | `task_control{start-task, submit-task}` |
+| review | `review` | 审查报告、合并 | `task_control{submit-review, merge-task}` |
+| release | —（手动） | 版本、Release PR、GitHub Actions 发布 | `release_control` |
+
+## 完成权威
+
+- **阶段完成 = Flow Record（Parent Issue）body checklist 中的 `- [x] <stage>`**
+- 阶段推进由 `flow_control{op:"stage-start"|"stage-complete"}` 维护：start 打 `cabbage:stage:<name>` label，complete 标记 checklist
+- 已完成阶段重复 start/complete → 幂等通过
+
+## 门禁规则
+
+| 场景 | 要求 |
+|------|------|
+| stage-start X | 前置阶段须已 completed（requirements 无前置） |
+| stage-complete X | 前置阶段须已 completed；**requirements 完成需用户确认一次** |
+| stage-start tasks（高风险 Flow，label `cabbage:risk:high`） | 需用户确认（`user_confirmed: true`） |
+| 依赖 Task 启动 | 前置依赖 Task 已 merged、并行数 < 5 |
+
+## 阶段顺序与基线
+
+```
+setup → requirements → design → tasks → code → review → (release 手动)
+```
+
+- **Planning Baseline**：CONTEXT.md + PRD + Design + ADR 经单个 Planning PR 合入后，才允许创建 Task Record
+- **requirements 基线**：需求阶段结束须用户确认一次
+- **goal 最小化**：`goal({op:"create", parent_issue_number:<Flow Record 编号>})`，目标/验收从 Flow Record 读取
+
+## 各阶段关键约束
+
+- **requirements**：渐进式澄清（Decision Map），一次只问一个问题；领域术语写入根 CONTEXT.md
+- **design**：architect 在 planning worktree 产出文档；方案遵循工程原则（KISS/YAGNI/DRY/SRP）
+- **tasks**：垂直切片、可独立验证、无循环依赖；标题用英文功能标题（内核派生 slug）
+- **code**：TDD 协议唯一来源是 `flow-tdd` skill；证据经 `tdd_checkpoint` 提交，缺证据 PR 被拒
+- **review**：双轴审查（规范 + 规格）+ TDD criterion coverage；reviewer 只读，写操作经 `task_control`
+- **release**：人工流程；按 Profile 版本规则 + 项目 GitHub Actions release workflow（技术栈无关）
+
+## Prohibited Actions
+
+- 不跳过前置门禁直接 stage-start/complete
+- 不手工修改 Flow Record 的 stage checklist（由 flow_control 维护）
+- 不绕过工具直接执行高风险 git/gh 写操作（push/PR/merge/worktree）