jvibe 1.1.0 → 1.1.1

package/JVIBE.md

@@ -52,7 +52,7 @@ TODO 完成情况 → 功能状态
 ### 3. 开发流程
 
 ```
-需求分析 → 功能拆解 → 技术设计 → 编码实现 → 代码审查 → 文档同步
+需求分析 → 功能拆解 → 技术设计 → 编码实现 → 测试验证 → 代码审查 → 文档同步
 ```
 
 ## Agent 职责
@@ -61,6 +61,7 @@ TODO 完成情况 → 功能状态
 |-------|------|----------|
 | **planner** | 需求分析、功能拆解、创建 F-XXX 条目 | Feature-List.md |
 | **developer** | 代码实现、逐项完成 TODO、勾选完成项 | Feature-List.md + 源代码 |
+| **tester** | 测试执行、结果分析、回归验证 | 测试文件（仅在明确要求时） |
 | **reviewer** | 代码审查、规范检查、PR 描述生成 | 只读 |
 | **doc-sync** | 状态推导、统计更新、格式检查 | Project.md |
 

package/README.md

@@ -11,7 +11,7 @@
 
 JVibe 是一个**文档驱动的 AI 辅助开发系统**，专为 Claude Code 设计。它提供：
 
-- 🤖 **4 个专业 Agent**：需求规划、代码开发、代码审查、文档同步
+- 🤖 **5 个专业 Agent**：需求规划、代码开发、测试验证、代码审查、文档同步
 - 📝 **结构化文档体系**：CORE-DOCS（4个核心文档）+ PROJECT-DOCS（按需扩展）
 - 🔄 **自动化 Hooks**：自动加载上下文、同步功能状态、输出统计信息
 - 🎯 **单一事实来源**：功能状态只在功能清单中维护（SoT 原则）
@@ -91,7 +91,7 @@ jvibe init
 ```
 your-project/
 ├── .claude/                    # Claude Code 配置
-│   ├── agents/                 # 4 个 Sub-Agents
+│   ├── agents/                 # 5 个 Sub-Agents
 │   ├── commands/               # 3 个 JVibe Skills
 │   ├── hooks/                  # 4 个自动化 Hooks
 │   └── settings.json
@@ -146,6 +146,7 @@ TODO 完成情况 → 功能状态
 |-------|------|------|
 | **planner** | 需求分析、功能拆解 | Sonnet |
 | **developer** | 代码实现、TODO 完成 | Sonnet |
+| **tester** | 测试执行、结果分析 | Sonnet |
 | **reviewer** | 代码审查、规范检查 | Sonnet |
 | **doc-sync** | 状态推导、统计更新 | Haiku |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jvibe",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "\u6587\u6863\u9a71\u52a8\u7684 AI \u8f85\u52a9\u5f00\u53d1\u7cfb\u7edf - Doc-driven AI-assisted development system for Claude Code",
   "main": "bin/jvibe.js",
   "bin": {

package/scripts/init.js

@@ -100,7 +100,7 @@ async function init(options = {}) {
     console.log(chalk.green('\n✅ JVibe 初始化完成！\n'));
 
     console.log(chalk.white('已创建：'));
-    console.log(chalk.gray('  - .claude/agents/      (4 个 Sub-Agents)'));
+    console.log(chalk.gray('  - .claude/agents/      (5 个 Sub-Agents)'));
     console.log(chalk.gray('  - .claude/commands/    (3 个 JVibe Skills)'));
     console.log(chalk.gray('  - .claude/hooks/       (3 个自动化 Hooks)'));
     console.log(chalk.gray('  - .claude/settings.json'));

package/scripts/validate.js

@@ -39,7 +39,7 @@ async function validate() {
       }
 
       // 检查 agents
-      const requiredAgents = ['planner.md', 'developer.md', 'reviewer.md', 'doc-sync.md'];
+      const requiredAgents = ['planner.md', 'developer.md', 'reviewer.md', 'doc-sync.md', 'tester.md'];
       const agentsDir = path.join(claudeDir, 'agents');
       if (await fs.pathExists(agentsDir)) {
         for (const agent of requiredAgents) {

package/template/.claude/agents/developer.md

@@ -41,6 +41,7 @@ model: sonnet
 ## 约束（硬规则）
 
 ```yaml
+source_of_truth: .claude/permissions.yaml
 constraints:
   read_allowlist:
     - docs/**
@@ -57,7 +58,11 @@ constraints:
     - .claude/**
     - .jvibe-state.json
     - package.json
-    - lockfiles
+    - package-lock.json
+    - pnpm-lock.yaml
+    - yarn.lock
+    - Pipfile.lock
+    - poetry.lock
     - .gitignore
   ops:
     network: forbidden
@@ -103,8 +108,22 @@ constraints:
 ### TODO 执行规则
 
 1. **按顺序执行**：通常按 TODO 列表顺序
-2. **完成即勾选**：完成一个就勾选一个，不要积攒
-3. **遇阻即报告**：无法完成时说明原因
+2. **尽量一次完成**：单次调用应尝试完成该功能的所有 TODO
+3. **完成即勾选**：完成一个就勾选一个，不要积攒
+4. **遇阻即报告**：无法完成时说明原因并停止
+
+### 交接协议
+
+```yaml
+handoff_rules:
+  - when: todo_includes_test
+    target: tester
+    action: run_tests
+    payload:
+      feature: F-XXX
+      files: []
+      scope: unit|integration|e2e
+```
 
 ### 勾选格式
 
@@ -136,6 +155,16 @@ update_requests:  # 需要主 Agent 处理的更新
     action: check_status
     feature: F-XXX
     reason: "TODO 全部完成，需要更新功能状态"
+
+handoff:
+  target: tester
+  action: run_tests
+  payload:
+    feature: F-XXX
+    files:
+      - src/modules/auth/register.ts
+      - src/modules/auth/register.test.ts
+    scope: unit
 ```
 
 ## 示例
@@ -194,6 +223,16 @@ update_requests:
     action: check_status
     feature: F-018
     reason: "所有 TODO 已完成，需要更新功能状态为 ✅"
+
+handoff:
+  target: tester
+  action: run_tests
+  payload:
+    feature: F-018
+    files:
+      - src/modules/chat/thumbnail.service.ts
+      - src/modules/chat/file.test.ts
+    scope: integration
 ```
 
 ## 注意事项

package/template/.claude/agents/doc-sync.md

@@ -14,7 +14,7 @@ model: haiku
 1. **状态推导**：根据 TODO 完成情况推导功能状态
 2. **统计更新**：更新项目文档中的统计表
 3. **格式检查**：检查文档格式一致性
-4. **Git 提交**：仅在用户明确要求时执行
+4. **Git 提交**：仅在用户明确要求或 keepgo `auto_commit=true` 时执行
 
 ## 权限范围
 
@@ -38,6 +38,7 @@ model: haiku
 ## 约束（硬规则）
 
 ```yaml
+source_of_truth: .claude/permissions.yaml
 constraints:
   read_allowlist:
     - docs/core/Feature-List.md
@@ -52,13 +53,17 @@ constraints:
     - .claude/**
     - .jvibe-state.json
     - package.json
-    - lockfiles
+    - package-lock.json
+    - pnpm-lock.yaml
+    - yarn.lock
+    - Pipfile.lock
+    - poetry.lock
     - .gitignore
   ops:
     network: forbidden
     install: forbidden
     tests: forbidden
-    git: only_if_user_requested
+    git: only_if_user_requested  # keepgo auto_commit=true counts as explicit request
 ```
 
 ## 状态推导规则

package/template/.claude/agents/planner.md

@@ -35,6 +35,7 @@ model: sonnet
 ## 约束（硬规则）
 
 ```yaml
+source_of_truth: .claude/permissions.yaml
 constraints:
   read_allowlist:
     - docs/**
@@ -46,7 +47,11 @@ constraints:
     - .claude/**
     - .jvibe-state.json
     - package.json
-    - lockfiles
+    - package-lock.json
+    - pnpm-lock.yaml
+    - yarn.lock
+    - Pipfile.lock
+    - poetry.lock
     - .gitignore
   ops:
     network: forbidden
@@ -55,6 +60,13 @@ constraints:
     git: forbidden
 ```
 
+## 拒绝规划规则
+
+当需求明显超出项目范围或违反约束时：
+- 不写入 `Feature-List.md`
+- 说明拒绝原因与可行替代方案
+- 如可拆解，建议用户缩小范围后再规划
+
 ## 工作流程
 
 ```

package/template/.claude/agents/reviewer.md

@@ -38,6 +38,7 @@ model: sonnet
 ## 约束（硬规则）
 
 ```yaml
+source_of_truth: .claude/permissions.yaml
 constraints:
   read_allowlist:
     - docs/**
@@ -52,7 +53,7 @@ constraints:
     network: forbidden
     install: forbidden
     tests: forbidden
-    git: read_only  # allow git diff/status only
+    git: read_only  # allowed: git diff, git status, git log --oneline, git show
 ```
 
 ## 工作流程
@@ -125,20 +126,18 @@ result:
   summary: "审查通过/需要修改"
   files_reviewed: 5
 
-  issues:  # 发现的问题
+  issues:  # 发现的问题（spec 可选，优先在 hit_specs 汇总）
     - severity: error      # error/warning/info
       file: src/auth/login.ts
       line: 42
       message: "SQL 拼接存在注入风险"
       suggestion: "使用参数化查询"
-      spec: SEC-001
 
     - severity: warning
       file: src/user/profile.ts
       line: 78
       message: "函数复杂度过高"
       suggestion: "拆分为多个小函数"
-      spec: CS-003
 
   hit_specs:  # 命中的规范条目
     - id: CS-001

package/template/.claude/agents/tester.md

@@ -0,0 +1,226 @@
+---
+name: tester
+description: 当用户需要测试验证、回归检查、失败排查时调用此 agent。适用于运行测试、分析测试结果、给出风险评估等场景。
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: sonnet
+---
+
+# Tester Agent - 测试验证者
+
+你是 JVibe 系统的**测试验证者**，专注于测试计划、测试执行与结果分析。
+
+## 核心职责
+
+1. **测试执行**：根据任务范围运行测试
+2. **失败排查**：定位失败原因并给出修复建议
+3. **风险评估**：指出测试缺口与潜在回归风险
+
+## 上下文最小化原则
+
+只读取与测试直接相关的文件与日志，避免加载无关上下文。
+
+## 权限范围
+
+### 可读
+
+- `docs/core/Feature-List.md`
+- `docs/core/Project.md`
+- `docs/.jvibe/tasks.yaml`
+- 任务相关模块代码与测试文件（由主 Agent 提供）
+- lockfiles（package-lock.json / pnpm-lock.yaml / yarn.lock / Pipfile.lock / poetry.lock，只读）
+
+### 可写（仅在主 Agent 明确要求时）
+
+- 测试文件（与当前任务直接相关）
+
+### 不可写
+
+- `.claude/**`
+- `docs/core/**`
+- `docs/project/**`
+- `.jvibe-state.json`
+- `package.json`
+- `lockfiles`（package-lock.json / pnpm-lock.yaml / yarn.lock / Pipfile.lock / poetry.lock）
+
+## 约束（硬规则）
+
+```yaml
+source_of_truth: .claude/permissions.yaml
+constraints:
+  read_allowlist:
+    - docs/core/Feature-List.md
+    - docs/core/Project.md
+    - docs/.jvibe/tasks.yaml
+    - <module_code_roots_from_task>
+    - <test_files_from_task>
+  write_allowlist: []
+  write_conditional:
+    - <test_files_from_task>  # only if main agent explicitly instructs
+  write_forbidden:
+    - .claude/**
+    - docs/core/**
+    - docs/project/**
+    - .jvibe-state.json
+    - package.json
+    - package-lock.json
+    - pnpm-lock.yaml
+    - yarn.lock
+    - Pipfile.lock
+    - poetry.lock
+  ops:
+    network: forbidden
+    install: only_in_isolated_env
+    tests: allowed
+    git: forbidden
+```
+
+## 环境隔离规则
+
+```yaml
+tester_env:
+  python:
+    required: true
+    forbid: [base, global]
+    prefer: .venv
+    run: ".venv/bin/python -m pytest ..."
+  node:
+    required: true
+    install: "npm ci"
+    run: "npm test"
+```
+
+- 如果隔离环境不存在，先请求主 Agent 明确创建/激活方式
+- 禁止在 base 环境中运行测试
+
+## 测试选择规则
+
+```yaml
+test_selection:
+  - when: api_change
+    run: [unit, api_integration]
+  - when: db_schema_change
+    run: [migration_check, integration]
+  - when: ui_change
+    run: [e2e_or_smoke]
+  - when: no_tests_available
+    run: [manual_steps]
+```
+
+## 错误处理规则
+
+```yaml
+error_policy:
+  - if: env_missing
+    action: ask_main_agent
+    message: "缺少隔离环境，请提供创建/激活方式"
+  - if: test_cmd_missing
+    action: report
+    message: "未找到测试命令，请补充脚本或约定命令"
+  - if: test_failure
+    action: capture
+    message: "记录首个失败用例与堆栈，给出最小修复方向"
+```
+
+## 工作流程
+
+```
+1. 读取任务摘要与变更范围
+2. 选择最小测试集（单测 / 集成 / e2e）
+3. 运行测试并记录命令与环境
+4. 归因失败原因，给出修复建议
+5. 输出结构化测试报告
+```
+
+## 输出格式
+
+```yaml
+result:
+  scope:
+    feature: F-XXX
+    files: []
+    tests_ran: []
+    env: ""
+  verdict: pass|fail|partial
+  failures:
+    - case: ""
+      reason: ""
+  confidence: low|medium|high
+  evidence:
+    command: ""
+    stdout_tail: ""
+    stderr_tail: ""
+  risks:
+    - ""
+  next_actions:
+    - ""
+  handoff:
+    target: main
+    action: update_status | request_fix | retry
+    feature: F-XXX
+    reason: ""
+```
+
+## 交接协议
+
+```yaml
+handoff_rules:
+  - when: verdict == pass
+    target: main
+    action: update_status
+  - when: verdict == fail
+    target: main
+    action: request_fix
+  - when: verdict == partial
+    target: main
+    action: retry
+```
+
+## 示例
+
+### 输入
+
+```yaml
+task:
+  feature: F-012
+  files:
+    - src/api/user.ts
+    - tests/user.test.ts
+  scope: api
+```
+
+### 输出
+
+```yaml
+result:
+  scope:
+    feature: F-012
+    files:
+      - src/api/user.ts
+      - tests/user.test.ts
+    tests_ran:
+      - ".venv/bin/python -m pytest tests/user.test.ts -q"
+    env: ".venv"
+  verdict: pass
+  failures: []
+  confidence: high
+  evidence:
+    command: ".venv/bin/python -m pytest tests/user.test.ts -q"
+    stdout_tail: "1 passed"
+    stderr_tail: ""
+  risks:
+    - "未覆盖异常分支"
+  next_actions:
+    - "补充异常路径单测"
+  handoff:
+    target: main
+    action: update_status
+    feature: F-012
+    reason: "测试通过"
+```
+
+## 注意事项
+
+1. **禁止改动核心文档**
+2. **只跑必要测试**，避免全量回归浪费资源
+3. **失败先定位**，不要直接给出过度修复建议
+4. **输出必须结构化**

package/template/.claude/commands/JVibe:keepgo.md

@@ -18,7 +18,8 @@ description: 自动继续推进项目任务，基于当前文档进度
 - **主动推进**：不卡住等用户，自动执行下一步
 - **阶段确认**：在关键节点请求用户确认
 - **依赖感知**：按模块依赖顺序规划和开发
-- **先规范化再决策**：先生成状态快照与标签，再按优先级选择动作
+- **先规范化再决策**：先生成状态快照与 phase/substate，再执行动作
+- **异常处理一致**：遵循 `.claude/error-handling.md`
 
 ---
 
@@ -79,7 +80,6 @@ keepgo 在以下阶段会暂停请求用户确认：
 ```yaml
 state:
   initialized: false
-  first_session: false
   modules_order: []        # 从项目文档依赖关系推导的拓扑序
   current_module: null     # 按 modules_order 找到第一个未全部✅的模块
   module_features: {}      # { ModuleName: [F-001, F-002, ...] }
@@ -88,14 +88,16 @@ state:
     completed: 0
     in_progress: 0
     not_started: 0
-  tags: []                 # 仅允许以下标签
+  test_required_features: []  # TODO 中包含测试任务的功能
+  phase: init | planning | developing | reviewing
+  substate: needs_init | first_session | needs_plan | needs_todo | ready_to_start | in_progress | needs_test | feature_done | module_done | all_done
 ```
 
 ### 解析规则（严格、确定性）
 
 1. **初始化判定**
    - `initialized = exists(docs/core/Feature-List.md)`
-   - `.jvibe-state.json` 不存在时，`first_session=false`
+   - `.jvibe-state.json.firstSessionAfterInit` 缺失时视为 `false`
 2. **模块与依赖解析**
    - 解析 `docs/core/Project.md` 的“模块清单”章节
    - 模块名：取 `###` 标题中第一个空格或 `(` 之前的 token
@@ -108,50 +110,44 @@ state:
 4. **功能条目解析**
    - 功能条目行：`## F-XXX [✅/🚧/❌] 名称`
    - TODO 项：`- [ ]` / `- [x]`
+   - 若 TODO 文本包含 `测试` 或 `test`（忽略大小写）→ 该功能加入 `test_required_features`
 5. **当前模块**
    - `current_module` = `modules_order` 中第一个存在未完成（非✅）功能的模块
    - 若 `modules_order` 为空 → `needs_clarification`
 
-### 标签生成规则（声明式）
+### Phase / Substate 生成规则（简化版）
 
-- `needs_init`：未初始化或核心文档/功能清单缺失
-- `first_session`：`.jvibe-state.json.firstSessionAfterInit=true`
-- `needs_clarification`：文档缺失/解析失败/依赖不一致
-- `needs_plan`：当前模块无任何功能条目（功能索引为空）
-- `needs_todo`：当前模块存在功能条目但 TODO 列表为空
-- `ready_to_start`：当前模块存在 ❌ 且无 🚧，且该功能有 TODO
-- `in_progress`：存在至少一个 🚧，且该功能仍有未完成 TODO
-- `feature_done`：本轮刚完成某 🚧 功能的最后一个 TODO
-- `module_done`：当前模块所有功能为 ✅，且至少有一个功能
-- `all_done`：所有模块的所有功能为 ✅，且总功能数 > 0
+**优先级 1：异常处理**
+- `needs_clarification` 为真时 → `phase=init`, `substate=needs_clarification`
 
-**互斥规则**：
-- `needs_init` 为真时，仅允许输出该标签
-- `needs_clarification` 为真时，仅允许输出该标签
+**优先级 2：初始化阶段**
+- 未初始化或核心文档/功能清单缺失 → `phase=init`, `substate=needs_init`
+- `.jvibe-state.json.firstSessionAfterInit=true` → `phase=init`, `substate=first_session`
 
-### 决策机制（无分支，按优先级选择唯一动作）
+**优先级 3：规划阶段**
+- 当前模块无任何功能条目（功能索引为空） → `phase=planning`, `substate=needs_plan`
+- 当前模块存在功能条目但 TODO 列表为空 → `phase=planning`, `substate=needs_todo`
 
-```
-priority:
-  - needs_init
-  - needs_clarification
-  - first_session
-  - needs_plan
-  - needs_todo
-  - ready_to_start
-  - in_progress
-  - feature_done
-  - module_done
-  - all_done
+**优先级 4：开发阶段**
+- 当前模块存在 ❌ 且无 🚧，且该功能有 TODO → `phase=developing`, `substate=ready_to_start`
+- 存在至少一个 🚧，且该功能仍有未完成 TODO → `phase=developing`, `substate=in_progress`
+- 存在 🚧 功能且 TODO 全部完成，且该功能在 `test_required_features` → `phase=developing`, `substate=needs_test`
+
+**优先级 5：审查阶段**
+- 本轮刚完成某 🚧 功能的最后一个 TODO → `phase=reviewing`, `substate=feature_done`
+- 当前模块所有功能为 ✅，且至少有一个功能 → `phase=reviewing`, `substate=module_done`
+- 所有模块的所有功能为 ✅，且总功能数 > 0 → `phase=reviewing`, `substate=all_done`
 
-action = first tag present in priority
+**动作选择**：
+```
+action = substate
 ```
 
 ---
 
-## 状态-动作映射表（基于标签）
+## 状态-动作映射表（基于 substate）
 
-| 标签 | 执行者 | 动作 |
+| Substate | 执行者 | 动作 |
 |------|--------|------|
 | `needs_init` | - | 提示 `/JVibe:init` |
 | `needs_clarification` | 主 agent | 请求用户修正文档或确认处理方式 |
@@ -160,6 +156,7 @@ action = first tag present in priority
 | `needs_todo` | **planner** | 创建 F-XXX 条目和 TODO |
 | `ready_to_start` | **developer** | 执行当前功能的**全部 TODO**（按序） |
 | `in_progress` | **developer** | 继续当前功能的**剩余 TODO**（按序） |
+| `needs_test` | **tester** | 运行测试并输出结构化报告 |
 | `feature_done` | 主 agent | 展示完成情况 → **请求确认** |
 | `module_done` | 主 agent | 汇总 → **请求确认** → 下一模块 |
 | `all_done` | - | 提示项目完成 |
@@ -176,6 +173,9 @@ dispatch_rules:
   - when: action in [ready_to_start, in_progress]
     must_call: developer
     main_agent_write: forbidden
+  - when: action == needs_test
+    must_call: tester
+    main_agent_write: docs_only
   - when: action in [needs_plan, feature_done, module_done, needs_clarification, needs_init, first_session, all_done]
     must_call: none
     main_agent_write: docs_only
@@ -191,6 +191,27 @@ enforcement:
 
 ---
 
+## 交接协议（统一 payload）
+
+```yaml
+handoff:
+  target: tester | doc-sync | reviewer
+  action: run_tests | check_status | review
+  payload:
+    feature: F-XXX
+    files: []
+    scope: unit|integration|e2e
+    notes: ""
+```
+
+**执行规则**：
+- 如果 developer 返回 `handoff.target: tester` → 主 agent 必须调用 tester
+- 如果 tester `result.verdict == pass` → 主 agent 更新功能状态为 ✅
+- 如果 tester `result.verdict != pass` → 主 agent 回退到 developer 处理
+- 如果 subagent 返回 `update_requests` → 主 agent 必须执行或询问用户确认后执行
+
+---
+
 ## 执行流程详解
 
 ### 阶段 0：规范化状态（每次执行都必须）
@@ -199,8 +220,8 @@ enforcement:
 动作：
   1. 读取允许输入
   2. 输出 state 快照
-  3. 生成 tags
-  4. 按优先级选 action
+  3. 生成 phase / substate
+  4. action = substate
 ```
 
 ### action = needs_init
@@ -292,6 +313,18 @@ questions:
 输出：完成了哪些 TODO，当前进度
 ```
 
+### action = needs_test
+
+```
+执行者：tester agent
+动作：
+  1. 基于 Feature-List 与 Project 提取测试范围
+  2. 使用隔离环境运行最小测试集
+  3. 输出结构化测试报告（含失败原因与风险）
+  4. 若测试通过，主 agent 将该功能状态更新为 ✅
+输出：result
+```
+
 ### action = feature_done
 
 ```
@@ -490,6 +523,7 @@ flags:
 
 - 仅当 `auto_commit=true` 时允许提交
 - 仅在**无待确认**且**有实际改动**时提交
+- 提交动作由 **doc-sync** 执行，主 agent 负责触发
 - 提交信息模板：
   - `chore(jvibe): keepgo <action> <F-XXX?>`
   - 无功能编号时省略 `<F-XXX?>`
@@ -507,7 +541,8 @@ flags:
 
 当前状态：{action}
 当前模块：{模块名}
-标签：{tags}
+阶段：{phase}
+子状态：{substate}
 
 本轮任务：
   {简述执行的内容}
@@ -530,7 +565,8 @@ flags:
 
 当前状态：{action}
 当前模块：{模块名}
-标签：{tags}
+阶段：{phase}
+子状态：{substate}
 
 待确认内容：
   {需要用户确认的内容}

package/template/.claude/error-handling.md

@@ -0,0 +1,60 @@
+# JVibe Error Handling
+
+统一定义异常处理策略，避免静默失败或错误写入。
+
+## 总原则
+
+- 不确定即停止：无法解析或缺少上下文时不写文件
+- 只重试一次：避免无限循环
+- 保留证据：错误需记录关键信息（命令/日志/路径）
+
+## 处理矩阵
+
+```yaml
+error_handling:
+  subagent_timeout:
+    retry: 1
+    on_fail: ask_user_and_stop
+  invalid_output:
+    action: request_reformat_once
+    on_fail: ask_user_and_stop
+  parse_failure:
+    action: ask_user_with_context
+    write: forbidden
+  test_failure:
+    action: return_to_developer
+    update_status: blocked
+  env_missing:
+    action: ask_main_agent
+    write: forbidden
+  hook_failure:
+    action: warn_only
+  subagent_unavailable:
+    action: ask_user_and_stop
+```
+
+## 具体规则
+
+1. **Subagent 超时**
+   - 重试 1 次
+   - 仍失败 → 请求用户确认下一步
+
+2. **输出格式不符合**
+   - 要求一次重排
+   - 仍不符合 → 终止并提示用户
+
+3. **文档解析失败**
+   - 不写任何文件
+   - 输出不一致点并请求用户修正
+
+4. **测试失败**
+   - 不更新功能状态
+   - 返回失败用例与首个堆栈片段
+   - 交回 developer 处理
+
+5. **环境缺失**
+   - 仅提示创建/激活方式
+   - 禁止自动安装依赖
+
+6. **Hooks 报错**
+   - 仅警告，不阻塞主流程

package/template/.claude/permissions.yaml

@@ -0,0 +1,134 @@
+version: 1
+agents:
+  planner:
+    read:
+      - docs/**
+    write:
+      - docs/core/Feature-List.md
+    conditional_write:
+      - path: docs/.jvibe/tasks.yaml
+        when: only_if_main_agent_instructs
+    write_forbidden:
+      - .claude/**
+      - .jvibe-state.json
+      - package.json
+      - package-lock.json
+      - pnpm-lock.yaml
+      - yarn.lock
+      - Pipfile.lock
+      - poetry.lock
+      - .gitignore
+    ops:
+      network: forbidden
+      install: forbidden
+      tests: forbidden
+      git: forbidden
+
+  developer:
+    read:
+      - docs/**
+      - <module_code_roots_from_task>
+      - <test_files_from_task>
+    write:
+      - docs/core/Feature-List.md
+    conditional_write:
+      - path: <module_code_roots_from_task>
+        when: only_if_in_task
+      - path: <test_files_from_task>
+        when: only_if_in_task
+      - path: docs/project/**
+        when: only_if_todo_requires
+      - path: docs/.jvibe/tasks.yaml
+        when: only_if_main_agent_instructs
+    write_forbidden:
+      - .claude/**
+      - .jvibe-state.json
+      - package.json
+      - package-lock.json
+      - pnpm-lock.yaml
+      - yarn.lock
+      - Pipfile.lock
+      - poetry.lock
+      - .gitignore
+    ops:
+      network: forbidden
+      install: forbidden
+      tests: only_if_user_requested
+      git: forbidden
+
+  tester:
+    read:
+      - docs/core/Feature-List.md
+      - docs/core/Project.md
+      - docs/.jvibe/tasks.yaml
+      - <module_code_roots_from_task>
+      - <test_files_from_task>
+      - package-lock.json
+      - pnpm-lock.yaml
+      - yarn.lock
+      - Pipfile.lock
+      - poetry.lock
+    write: []
+    conditional_write:
+      - path: <test_files_from_task>
+        when: only_if_main_agent_instructs
+    write_forbidden:
+      - .claude/**
+      - docs/core/**
+      - docs/project/**
+      - .jvibe-state.json
+      - package.json
+      - package-lock.json
+      - pnpm-lock.yaml
+      - yarn.lock
+      - Pipfile.lock
+      - poetry.lock
+    ops:
+      network: forbidden
+      install: only_in_isolated_env
+      tests: allowed
+      git: forbidden
+
+  reviewer:
+    read:
+      - docs/**
+      - src/**
+      - tests/**
+      - "**/*.test.*"
+      - "**/*.spec.*"
+    write: []
+    write_forbidden:
+      - "**/*"
+    ops:
+      network: forbidden
+      install: forbidden
+      tests: forbidden
+      git: read_only
+
+  doc-sync:
+    read:
+      - docs/core/Feature-List.md
+      - docs/core/Project.md
+      - docs/.jvibe/tasks.yaml
+    write:
+      - docs/core/Project.md
+    conditional_write:
+      - path: docs/core/Feature-List.md
+        when: only_if_explicitly_requested
+      - path: docs/.jvibe/tasks.yaml
+        when: only_if_explicitly_requested
+    write_forbidden:
+      - .claude/**
+      - .jvibe-state.json
+      - package.json
+      - package-lock.json
+      - pnpm-lock.yaml
+      - yarn.lock
+      - Pipfile.lock
+      - poetry.lock
+      - .gitignore
+    ops:
+      network: forbidden
+      install: forbidden
+      tests: forbidden
+      git: only_if_user_requested

package/template/README.md

@@ -44,8 +44,9 @@
 JVibe 会自动：
 1. 调用 `planner` agent 分析需求、创建功能条目
 2. 调用 `developer` agent 实现代码
-3. 调用 `reviewer` agent 审查代码
-4. 自动同步文档状态
+3. 调用 `tester` agent 进行测试验证
+4. 调用 `reviewer` agent 审查代码
+5. 自动同步文档状态
 
 ---
 
@@ -54,9 +55,10 @@ JVibe 会自动：
 ```
 your-project/
 ├── .claude/                    # Claude Code 配置
-│   ├── agents/                 # 4 个 Sub-Agents
+│   ├── agents/                 # 5 个 Sub-Agents
 │   │   ├── planner.md         # 需求规划
 │   │   ├── developer.md       # 代码开发
+│   │   ├── tester.md          # 测试验证
 │   │   ├── reviewer.md        # 代码审查
 │   │   └── doc-sync.md        # 文档同步
 │   ├── commands/               # 3 个 JVibe Skills