@devcxl/opencode-cabbage 1.2.0 → 1.3.0

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

@@ -0,0 +1,110 @@
+---
+name: flow-review
+description: 双轴审查（规范 + 规格）→ 发布审查结果 → 合并
+---
+
+# flow-review
+
+沿两条轴线审查 PR 代码：规范（是否符合编码标准）和规格（是否实现了原始需求）。
+reviewer 只读；写操作（review/merge）由 primary 编排器执行。
+
+## 核心流程
+
+1. **发布审查结果**（primary 执行）
+   ```bash
+   gh pr review <pr-number> --approve
+   gh pr review <pr-number> --request-changes --body "<原因>"
+   ```
+2. **合并**（CI + 审查通过后，primary 执行）
+   ```bash
+   HEAD_SHA=$(gh pr view <pr-number> --json headRefOid --jq .headRefOid)
+   gh pr merge <pr-number> --squash --delete-branch --match-head-commit "$HEAD_SHA"
+   ```
+3. 合并后清理 worktree：`git worktree remove ".worktree/<task-slug>"`（脏时提示用户手动处理）
+
+reviewer 只读：不直接执行 `gh pr review` / `gh pr merge`（写操作由 primary 编排器执行）。
+
+## 双轴审查
+
+两条轴线独立审查、分别报告；不把发现项混排，也不允许一条轴线的通过掩盖另一条轴线的失败。
+
+### 规格轴（Specification）
+
+回答“是否实现了正确的行为”：
+
+- 对照 PRD、Task `Builds`、`Acceptance Criteria` 与技术方案检查遗漏或不完整需求。
+- 检查 diff 是否增加规格未要求的行为或抽象，识别 scope creep。
+- 检查看似已实现但边界、错误或状态转换不符合规格的行为。
+- 逐条核查 Acceptance Criteria 是否由 Design `Testing Decisions` 约定的 Test Seam 上的行为测试或验证命令证明。
+- 测试存在不等于规格通过；实现与测试共同误解需求时仍应报告。
+
+### 规范轴（Convention / Code Quality）
+
+回答“实现是否写得正确”：
+
+- 检查仓库文档化规范、AGENTS.md 与相关 ADR；仓库规则优先。
+- 参考 `references/smell-baseline.md`，代码气味属于判断性问题，不冒充硬性规范。
+- 检查 KISS、YAGNI、SRP，以及是否存在浅 Module、透传层或只有一个假设 Adapter 的 Seam。
+- 检查测试是否描述行为、使用公共 Test Seam，并避免私有方法、内部调用次数/顺序、侧信道和循环论证。
+- 跳过 formatter、lint、typecheck 等工具已经强制执行且没有实际风险的机械问题。
+
+**明确不检查 commit order**：RED→GREEN 顺序是编码过程约束，reviewer 不审查 commit 历史。
+
+### 审查结论
+
+- 任一轴存在阻断问题 → `CHANGES_REQUESTED`。
+- 两轴都没有阻断问题 → `APPROVED`。
+- 报告必须分别给出每条轴线的发现数量和最高严重度，不跨轴线重新排序。
+
+## 审查材料获取
+
+代码审查必须在本地分支/worktree 中进行，禁止通过 WebFetch 或浏览器访问远程 PR 页面获取代码。
+
+## Output
+- 结构化审查报告（APPROVED / CHANGES_REQUESTED）
+- PR 已合并（条件满足时）
+- Worktree 已清理
+
+## 后续
+- **/release** — 发布（如所有 PR 已合并）
+
+## Contract
+
+### Trigger
+由 `/review` 命令或 `@agent-dev-lifecycle` Phase 3 审查步骤触发。
+
+### Inputs
+- PR 编号、Task 文件与 Task Record（来源：`/code` 产出）
+- PRD 与技术方案（包含 Testing Decisions）
+
+### Preconditions
+- `/code` 已完成 → PR 已创建
+- Design 已包含本 Task 相关行为的 Testing Decisions；存量 Design 缺失时先返回 Design Gap，不提前给出审查结论
+
+### Procedure
+1. 在本地 worktree/分支获取 PR diff 与元数据
+2. 独立执行规格轴审查，核对行为、范围与 Acceptance Criteria 证据
+3. 独立执行规范轴审查，核对仓库规范、实现质量与测试质量
+4. 分轴输出结构化审查报告，不合并或重排发现
+5. primary 用 `gh pr review` 发布结果
+6. CI 通过后 primary 用 `gh pr merge` 合并并清理 worktree
+
+### Outputs
+- 结构化审查报告（APPROVED / CHANGES_REQUESTED）
+- PR 已合并（条件满足时）
+- Worktree 已清理
+
+### Failure
+- Critical/High → request-changes
+- Testing Decisions 缺失或与仓库现实冲突 → 返回 Design Gap，由 primary 在当前 stage 完成 amendment 后重新审查
+- Worktree 清理失败 → 记录警告，不阻塞
+
+### Idempotency
+- 已合并的 PR → 跳过
+- 已审查的 PR → 更新结论
+
+### Prohibited Actions
+- **禁止使用 WebFetch 或任何 Web 工具获取远程 PR 代码** — 审查代码时必须本地读取源码文件
+- reviewer 不直接执行 `gh pr review` / `gh pr merge`（由 primary 编排器执行）
+- 不把规格轴与规范轴合并成单一问题列表或用一条轴线抵消另一条轴线
+- 不使用默认 --force 清理

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

@@ -0,0 +1,75 @@
+---
+name: flow-setup
+description: 初始化 — 探测环境 → 确认 Profile
+---
+
+# flow-setup
+
+初始化阶段：探测开发环境、确认 AGENTS.md Project Profile。
+纯 Prompt 流程：直接使用 git/gh 命令探测，Profile 由用户确认后写入根 AGENTS.md。
+
+## 核心流程
+
+1. **探测环境**
+   ```bash
+   gh auth status                        # gh CLI 认证
+   gh repo view --json nameWithOwner,defaultBranchRef  # 仓库与默认分支
+   ls .github/workflows/                 # 现有 CI/release workflow
+   ```
+
+2. **确认 Project Profile**：向用户逐项确认以下配置（技术栈无关）：
+   - test command：测试命令（如 `npm test`）
+   - regression command：全量回归命令
+   - test file patterns：测试文件匹配（如 `test/**/*.test.ts`）
+   - implementation file patterns：实现文件匹配（如 `src/**/*.ts`）
+   - version bump rule、version file、tag format、release workflow
+
+3. **写入根 AGENTS.md**：用户确认后，将 Profile 区块追加/替换到根 `AGENTS.md`：
+
+```markdown
+## Project Profile
+
+- test command: `npm test`
+- regression command: `npm test`
+- test file patterns: `test/**/*.test.ts`
+- implementation file patterns: `src/**/*.ts`
+- version bump rule: `breaking→major, feature→minor, fix→patch`
+- version file: `package.json`
+- tag format: `v{version}`
+- release workflow: `.github/workflows/release.yml`
+```
+
+## Output
+- readiness 报告（git/gh 可用性、CI/release workflow 存在性）
+- 根 AGENTS.md `## Project Profile` 区块
+
+## Contract
+
+### Trigger
+由 `/setup` 命令触发。首次使用插件或切换新项目时执行。
+
+### Inputs
+- 用户对 readiness 报告 / Profile 覆盖项的确认
+
+### Preconditions
+- gh CLI 已认证（宿主 `gh auth`）
+
+### Procedure
+1. 用 gh/git 命令探测环境，输出 readiness 报告
+2. 缺失 CI/release workflow 时提示用户（可手工创建）
+3. 向用户逐项确认 Profile 配置
+4. 用户确认后写入根 AGENTS.md Profile 区块
+
+### Outputs
+- readiness 报告
+- 根 AGENTS.md Profile 区块
+
+### Failure
+- gh auth 失败 → 提示用户执行 `gh auth login` 后重试
+
+### Idempotency
+- Profile 已存在 → 覆盖为最新确认值
+
+### Prohibited Actions
+- 不写入未获用户确认的 Profile 项
+- 不假设测试命令为 npm（按用户确认的技术栈）

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

@@ -0,0 +1,220 @@
+---
+name: flow-tasks
+description: 将技术方案拆解为可独立实现的 tracer-bullet Task Plan 与 DAG
+---
+
+# flow-tasks
+
+将设计方案拆解为 Task Plan 与 DAG（有向无环图）。每个 Task 都是一条完整但狭窄的行为切片，可以交给一个 fresh-context developer agent 独立实现和验证。
+
+本 skill 只定义任务拆解与 Task Plan 产出。`@agent-architect` 不创建 GitHub Issue、不操作 GitHub lifecycle；调用方负责检查并发布 Task Plan。
+
+## Task 拆解规则
+
+每个 Task 必须：
+
+1. 交付一个可以观察或验证的新行为。
+2. 是垂直切片，而不是 Controller / Service / DAO 等技术分层。
+3. 可以交给一个 fresh-context developer agent 独立理解和实现。
+4. 完成以后仓库处于可工作的状态，而不是为下一个 Task 留空壳。
+5. `Blocked By` 只声明“前者未完成时，本 Task 无法开始”的真实阻塞关系。
+
+每个 Task 应适合一个 fresh-context developer agent：
+
+- 不需要读取整个 Flow 历史才能理解。
+- Task、Design 与 repository context 足够开始工作。
+- 正常情况下不需要再次进行架构设计。
+- 可以在一次独立开发循环中实现、测试、提交。
+
+## 何时拆分
+
+不要为了制造并行度而拆 Task。
+
+如果一个行为高度内聚、修改范围集中、一个 fresh context 可以完成，且没有独立可验证的中间行为，则保持为一个 Task。
+
+如果一个 Task 同时包含三个以上相互独立的“用户可以……”行为，应考虑按这些可独立验证的行为拆分。
+
+拆分前检查：
+
+1. **能否用一个 Task 完成？** — 足够内聚时不强拆。
+2. **拆开后能否独立验证？** — 每个 Task 都必须交付可观察行为。
+3. **是否真的阻塞？** — 只有无法开始的前置关系才进入 DAG。
+4. **拆开后耦合是否更低？** — 大量共享同一数据结构或模块时优先合并。
+
+## Behavior-preserving Pre-refactor
+
+行为 Task 的唯一例外是必要的 behavior-preserving pre-refactor：当现有结构使后续行为无法在一个可测试、可工作的垂直切片中安全实现时，可以先建立一个重构 Task。
+
+Pre-refactor 必须同时满足：
+
+- 不改变现有可观察行为，并用回归验证证明行为保持。
+- 自身完成后仓库保持可工作，不留下迁移一半的状态。
+- 只消除阻碍后续行为的具体结构问题，不搭通用框架、不预留未来扩展点。
+- 后续行为确实无法安全开始时，才将 pre-refactor 声明为 blocking edge。
+
+仅仅“这样更整洁”或“以后可能复用”不构成 pre-refactor。优先直接交付行为切片。
+
+Pre-refactor 的 `Builds` 应说明“保持哪个现有行为不变，并消除哪个阻碍后续行为的具体结构问题”，不能写成文件或类的修改清单。
+
+## 反模式
+
+| 反模式 | 示例 | 正确做法 |
+|--------|------|----------|
+| 技术分层拆分 | `create-session-table` → `implement-session-service` → `implement-session-api` | `create-and-restore-session` |
+| 测试单独成 Task | `add-session-tests` | 测试随行为切片一起交付 |
+| 过度拆分 | 一个内聚 CRUD 拆成多个 Task | 保持为一个可独立验证的 Task |
+| 预留式拆分 | 先搭框架，后续 Task 再填内容 | 每个 Task 完成后仓库都可工作 |
+| 虚假依赖 | 因修改相邻文件而声明依赖 | 仅声明不完成前者就无法开始的依赖 |
+
+## Task 定义
+
+每个 Task 保存为 `docs/dev/tasks/<task-name>.md`，是 developer 使用的 **Agent Implementation Contract**：
+
+`task-name` 使用简短的英文 kebab-case 行为短语，并作为后续 `feat/<task-name>` 分支名的基准。
+
+```markdown
+---
+issue: null
+test_commands:
+  - <targeted test command>
+verify_commands:
+  - <verification command>
+---
+
+# <task-slug>
+
+## Builds
+
+<这个 Task 完成后，哪个端到端行为真正可以工作？>
+
+## Acceptance Criteria
+
+- [ ] <可观察行为>
+- [ ] <边界或异常行为>
+- [ ] <回归要求>
+
+## Blocked By
+
+- <blocking-task-slug>
+- 或 None
+
+## Implementation Notes
+
+<只记录真正限制实现方式的重要设计决策；不要复制具体实现步骤。>
+```
+
+`Builds` 必须直接说明完成后的可工作行为。`Acceptance Criteria` 是 `flow-tdd` 使用的行为规格；`test_commands` 与 `verify_commands` 只放在 Task 文件中。
+
+Task 的行为测试必须沿用 Design `Testing Decisions` 中约定的 Test Seam。Task 不重新设计 Seam；如果既有 Seam 无法验证该行为，应返回 Design Gap，由调用方在当前 stage 完成 amendment。
+
+### Design Gap
+
+存量 Design 缺少 `Testing Decisions` 时，不回退 lifecycle stage，也不生成半成品 Task Plan。返回给调用方：
+
+```markdown
+## Design Gap
+
+- Current Stage: tasks
+- Design File: <docs/dev/specs/...>
+- Missing Behaviors:
+  - <缺少 Test Seam 或 Observable Result 的行为>
+- Existing Context: <已发现的公共 Interface 与测试惯例；没有则写 None>
+- Required Amendment: 为以上行为补充 Testing Decisions
+```
+
+调用方在当前 tasks 阶段完成 Design Amendment 后，重新执行 Task Planning。`@agent-architect` 不在 flow-tasks 内自行修改测试设计。
+
+规划阶段尚无 Issue 编号，`Blocked By` 使用 task slug。发布后由调用方将其更新为真实 `#<issue-number>`；无依赖时写 `None`。
+
+## DAG
+
+DAG 使用 Mermaid 语法，保存为 `docs/dev/tasks/<YYYY-MM-DD-NNN-slug>/DAG.md`。
+
+- 节点对应行为 Task，不对应技术层。
+- 边只表示真实 blocking edge。
+- 发布前必须检查环形依赖。
+- 发布后将 Task 节点与依赖更新为真实 Issue 编号。
+
+## GitHub 发布边界
+
+GitHub Sub Issue 是协作与生命周期记录，正文只提取 Task 中用户可读的内容：
+
+```markdown
+## Builds
+
+...
+
+## Acceptance Criteria
+
+- [ ] ...
+
+## Blocked By
+
+None
+```
+
+不得把 `issue`、`test_commands`、`verify_commands` 或内部实现说明复制到 GitHub Issue。
+
+发布由调用方执行：
+
+- 普通 Flow：`@agent-dev-lifecycle` 检查后自动发布。
+- 高风险 Flow：展示 Task Plan，用户确认后发布。
+- 用户主动 `/tasks`：展示 Task Plan，等待用户确认后发布。
+- `@agent-architect`：产出并返回 Task Plan 后停止，不执行发布。
+
+## Output
+
+- `docs/dev/tasks/*.md` — Agent Implementation Contracts
+- `docs/dev/tasks/<YYYY-MM-DD-NNN-slug>/DAG.md` — Task DAG
+- 返回给调用方的 Task Plan 摘要与拓扑顺序
+
+## 后续
+
+- `@agent-dev-lifecycle` 检查并发布 GitHub Sub Issues
+- **/code** — 按 Task DAG 进入编码阶段
+
+## Contract
+
+### Trigger
+由 `/tasks` 命令或 `@agent-dev-lifecycle` Phase 2 委派 `@agent-architect` 触发。
+
+### Inputs
+- `docs/dev/specs/<title>.md` — 技术方案
+- 相关 PRD 与 ADR
+- Parent Issue 编号
+
+### Preconditions
+- `/design` 已完成，技术方案和 ADR 存在
+
+### Procedure
+1. 读取设计基线与必要的 repository context。
+2. 读取 Design `Testing Decisions`，确认关键行为已有公共 Test Seam；缺失时返回 Design Gap 并停止，不生成或更新 Task 文件。
+3. 识别可独立验证的 tracer-bullet 行为切片；仅在必要时增加 behavior-preserving pre-refactor。
+4. 为每个 Task 定义 `Builds`、`Acceptance Criteria`、`Blocked By` 与必要的 `Implementation Notes`。
+5. 生成 Task 文件与 Mermaid DAG。
+6. 检查技术分层式拆分、空壳 Task、虚假依赖、臆测性 pre-refactor 与环形依赖。
+7. 返回 Task Plan、文件路径与拓扑顺序；不创建 GitHub Issue。
+
+### Outputs
+- Task 定义文件
+- Task DAG
+- 供调用方检查与发布的 Task Plan
+- 或结构化 Design Gap（存量 Design 缺少 Testing Decisions 时）
+
+### Failure
+- 无法从设计中确定可验证行为 → 暂停并指出缺失信息
+- Design Amendment 后仍缺少稳定 Test Seam → 报告未解决的 Design Gap，由调用方暂停当前阶段
+- DAG 存在环形依赖 → 阻止并报告
+- Task 无法由 fresh-context developer 独立理解 → 重新拆分或补足契约
+
+### Idempotency
+- Task 文件已存在 → 读取并更新，不创建重复定义
+- 已有 `issue` 编号 → 保留并交给调用方核验，不重复发布
+
+### Prohibited Actions
+- 不按技术层拆分 Task
+- 不为制造并行度而拆分 Task
+- 不创建完成后不可工作的空壳 Task
+- 不用 pre-refactor 包装搭框架、清理代码或预留扩展点
+- 不把非阻塞关系写入 `Blocked By`
+- `@agent-architect` 不执行 `gh issue create`、`git push`、PR、merge 或 worktree 操作

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

@@ -0,0 +1,235 @@
+---
+name: flow-tdd
+description: 公共 Test Seam 上的行为 TDD — RED→GREEN 状态机 + self-report 证据
+---
+
+# flow-tdd
+
+TDD（Test-Driven Development）Prompt 协议，为所有编码阶段提供统一的 TDD 流程约束。
+本 skill 是 TDD 协议的唯一来源，其他 skills 和 agents 通过引用本协议获得一致的 TDD 行为。
+
+## 核心原则
+
+测试是行为规格：通过 Design `Testing Decisions` 约定的公共 Test Seam 验证可观察行为，而不是验证内部实现。只要公共行为不变，重构 Module 内部实现不应导致测试失败。
+
+每个 TDD cycle 是一个最窄行为切片：
+
+```text
+确定 Test Seam 与一个行为
+        ↓
+写一个行为测试
+        ↓
+RED
+        ↓
+最小实现
+        ↓
+GREEN
+        ↓
+下一个行为
+```
+
+### 好测试
+
+- 名称描述调用者或用户可以完成什么，而不是调用了哪个内部方法。
+- 只通过约定的公共 Test Seam 触发并观察行为。
+- 期望值来自 Acceptance Criteria、已知正确示例或其他独立来源。
+- 实现重构但行为不变时仍然通过。
+
+### 反模式
+
+- **实现耦合** — 测试私有方法、内部协作对象、调用次数或调用顺序。
+- **侧信道验证** — 绕过公共 Seam 读取数据库或内部状态来证明行为。
+- **循环论证** — 用与实现相同的算法重新计算期望值。
+- **水平批量** — 先写完全部测试再实现；应按一个行为测试 → 一个最小实现逐次推进。
+- **为 mock 造抽象** — 仅允许在真实系统边界按既有 Interface 替换外部依赖，不为测试方便新增生产 Seam。
+
+## Advisory Procedure
+
+Agent 自行遵循 TDD 流程并 self-report 状态。测试质量由仓库 CI 把关，内核不强制证据。
+
+### Cycle 状态机
+
+```
+            ┌─────────────┐
+            │ cycle-start │ ← 开始新的 TDD 循环
+            └──────┬──────┘
+                   │
+                   ▼
+            ┌─────────────┐
+            │    red      │ ← 编写/更新测试，验证测试失败（RED）
+            └──────┬──────┘
+                   │
+                   ▼
+            ┌─────────────┐
+            │   green     │ ← 最小实现使测试通过（GREEN），仅做局部行为保持整理
+            └──────┬──────┘
+                   │
+        ┌──────────┼──────────┐
+        ▼          ▼          ▼
+   ┌─────────┐ ┌─────────┐ ┌──────────────┐
+   │ 下一个   │ │ abandon │ │ 所有 cycle   │
+   │ cycle   │ │ -cycle  │ │ 完成         │
+   └─────────┘ └─────────┘ └──────┬───────┘
+                                  │
+                                  ▼
+                          ┌──────────────────┐
+                          │ final-regression │ ← 运行全部测试，确认无回归
+                          └────────┬─────────┘
+                                   │
+                                   ▼
+                          ┌───────────────────┐
+                          │ final-verification│ ← 对照 Acceptance Criteria 逐条验证
+                          └───────────────────┘
+```
+
+### cycle-start
+
+开始一个新的 RED→GREEN 循环。Agent 在实现前从 Design `Testing Decisions` 读取 Test Seam，并声明本 cycle 的一个可观察行为。
+
+**self-report 格式：**
+```
+## TDD cycle-start
+- cycle: <序号>
+- behavior: <本 cycle 要交付的可观察行为>
+- test_seam: <约定的公共 Test Seam>
+- test: <通过该 Seam 验证行为的测试名称>
+```
+
+### red
+
+编写或更新测试用例，验证测试在当前实现下失败。
+
+**约束：**
+- 测试必须有明确的 fail/pass 边界
+- 测试名称描述行为，且只通过 cycle-start 声明的 Test Seam 触发和观察结果
+- RED 必须因目标行为尚未实现而失败，不能把环境、语法或夹具错误当作证据
+- 测试运行命令必须与 Task 的 `test_commands` 中定义的一致
+- 记录测试失败输出作为 RED evidence
+
+**self-report 格式：**
+```
+## TDD red
+- test: <测试名称>
+- command: <运行命令>
+- result: FAIL（预期）
+```
+
+### green
+
+编写最小实现使 RED 阶段的行为测试通过。可进行局部、行为保持的整理，但不得改变约定的 Test Seam 或扩展范围。
+
+**约束：**
+- 只写使当前测试通过的最少代码
+- 不新增与当前 test 无关的功能
+- 重构仅限于当前 cycle 涉及的代码
+- 不为通过测试而暴露内部状态、增加仅供测试使用的生产接口或改成实现细节断言
+
+**self-report 格式：**
+```
+## TDD green
+- test: <测试名称>
+- command: <运行命令>
+- result: PASS
+- changes: <涉及的文件列表>
+```
+
+### abandon-cycle
+
+当发现当前 cycle 的目标不合理、设计有缺陷或需要回退时，废弃当前 cycle 的所有修改。
+
+**触发条件：**
+- RED 阶段发现测试设计有误
+- GREEN 阶段发现需要根本性重新设计
+- 发现更简单的替代方案
+
+**流程：**
+1. 放弃当前 cycle 的修改（`git checkout -- <files>` 或 `git stash drop`）
+2. 记录 abandon 原因
+3. 重新从 cycle-start 开始
+
+**self-report 格式：**
+```
+## TDD abandon-cycle
+- cycle: <序号>
+- reason: <废弃原因>
+```
+
+### final-regression
+
+所有 cycle 完成后，运行项目全部测试套件，确认无回归。
+
+**约束：**
+- 必须运行 Task `test_commands` 中定义的全部命令
+- 所有测试必须通过
+- 如有失败 → 修复（不要求新 cycle，但需记录修复内容）
+
+**self-report 格式：**
+```
+## TDD final-regression
+- passed: <通过的测试数>
+- failed: <失败的测试数>
+- total: <测试总数>
+```
+
+### final-verification
+
+对照 Task 的 `Acceptance Criteria` 逐条验证，确认每项都由公共 Test Seam 上的行为测试或 `verify_commands` 证明。
+
+**self-report 格式：**
+```
+## TDD final-verification
+- criteria_total: <总数>
+- criteria_met: <已满足>
+- criteria_pending: <未满足>
+```
+
+## Contract
+
+### Trigger
+由编码阶段（`flow-code`）自动触发。Agent 在开始编码任务时加载 `flow-tdd` skill 获取 TDD 流程约束。
+
+### Inputs
+- Task 文件中的 `Builds` 与 `Acceptance Criteria`（来源：`flow-tasks`）
+- Task frontmatter 中的 `test_commands` 与 `verify_commands`
+- Design `Testing Decisions` 中约定的 Test Seam 与 Observable Result
+
+### Preconditions
+- Task 文件存在，包含 `Builds`、`Acceptance Criteria`、`test_commands`
+- Design 已为目标行为定义公共 Test Seam；存量 Design 缺失时先向 primary 返回 Design Gap，由兼容门在当前 stage 补齐
+- 测试运行环境就绪（worktree 内依赖已安装）
+
+### Procedure
+1. 读取 Task 的 `Builds`、`Acceptance Criteria`、`test_commands`、`verify_commands`。
+2. 读取 Design `Testing Decisions`，确认目标行为的 Test Seam 与 Observable Result。
+3. 选择一个尚未满足的行为，执行 `cycle-start` 声明 behavior、test_seam 与 test。
+4. 执行 `red` → 只写该行为测试，验证因行为缺失而失败，记录 self-report。
+5. 执行 `green` → 编写最小实现，验证通过，记录 self-report。
+6. 按一个行为切片一个 cycle 重复，直到所有 Acceptance Criteria 被覆盖。
+7. 执行 `final-regression` → 运行全部测试。
+8. 执行 `final-verification` → 通过 Test Seam 或 `verify_commands` 逐条验证 Acceptance Criteria。
+
+### Outputs
+- 每个 cycle 的 self-report
+- `final-regression` 报告（测试通过/失败统计）
+- `final-verification` 报告（criterion 覆盖情况）
+
+### Failure
+- RED 阶段测试意外通过 → 检查测试是否有意义，可能需要 abandon-cycle
+- RED 因环境、语法或夹具错误失败 → 修复测试基础设施，不能计为 RED evidence
+- 只能通过内部实现观察目标行为 → 停止编码并向 primary 返回 Design Gap，不自行修改 Design、不回退 lifecycle stage
+- GREEN 阶段测试持续失败 → 检查实现逻辑，记录失败原因
+- final-regression 失败 → 修复回归，不要求新 cycle
+- final-verification 未全部满足 → 返回未完成的 criterion，补充 cycle
+
+### Idempotency
+- 同一 cycle 重复执行 → 以最后一次结果为准
+- final-regression 重复执行 → 覆盖上次结果
+
+### Prohibited Actions
+- 不跳过 RED 阶段直接进入 GREEN
+- 不测试私有方法、内部调用次数、内部调用顺序或未约定的侧信道
+- 不一次批量编写多个行为测试后再统一实现
+- 不为了 mock 或测试方便新增生产抽象
+- 不跳过 final-regression 直接 commit
+- 不在 abandon-cycle 后保留修改
+- 不伪造测试结果（实际运行命令后再 self-report）

package/dist/hooks/session-start.d.ts

@@ -0,0 +1 @@
+export {};