# Phase B Developer

> 十步循环 Phase B - 开发阶段执行器，编排 B.1-B.3 步骤。 使用场景："执行开发阶段"、"Phase B"、"创建分支并运行测试"

- Skill: `10cg/phase-b-developer` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add 10cg/phase-b-developer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/10cg/phase-b-developer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: 10cg (https://skillmd.com/u/10cg)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/10cg/phase-b-developer

---


# Phase B - 开发阶段 (Developer)

> **版本**: 1.4.0 | **十步循环**: B.1-B.3
> **更新**: 2026-03-27 - 升级审计触发从 agent-team-audit 改为 audit-engine

## 快速开始

### 我应该使用这个 Skill 吗？

**使用场景**:
- 需要创建功能分支
- 需要运行测试验证
- 需要同步架构文档
- 代码开发完成后的验证阶段

**不使用场景**:
- 已在功能分支 → 跳过 B.1
- 无测试文件 → B.2 降级模式
- 无架构变更 → 跳过 B.3

---

## 配置 (config-loader)

执行前读取 `.aria/config.json`，缺失则使用默认值。参见 [config-loader](../config-loader/SKILL.md)。

| 字段 | 默认值 | 说明 |
|------|--------|------|
| `audit.enabled` | `false` | 启用 audit-engine 审计 (新) |
| `audit.checkpoints.post_implementation` | `"off"` | post_implementation 检查点模式 |
| `experiments.agent_team_audit` | `false` | 旧配置 (向后兼容，自动映射到 audit.*) |
| `experiments.agent_team_audit_points` | `["pre_merge"]` | 旧配置 (向后兼容) |
| `phase_b_developer.framework_build_check.enabled` | `false` | B.2.5 框架 build 验证开关 (Aria #95) |
| `phase_b_developer.framework_build_check.command` | `null` | build 命令 (如 `"npm run build"`); null=no-op |
| `phase_b_developer.framework_build_check.mode` | `"advisory"` | `advisory`=警告不阻塞 / `blocking`=失败阻塞进 Phase C |

当 `audit.enabled=true` 且 `audit.checkpoints.post_implementation != "off"` 时，B.3 完成后触发 audit-engine (post_implementation 检查点)。
旧配置 `experiments.agent_team_audit=true` 且 `"post_implementation" in agent_team_audit_points` 自动映射到新配置。

---

## 核心功能

| 步骤 | Skill | 职责 | 输出 |
|------|-------|------|------|
| B.1 | branch-manager | 分支创建 | branch_name |
| B.2 | test-verifier | 测试验证 | test_passed, coverage |
| B.3 | arch-update | 架构同步 | arch_updated |

---

## 执行流程

### 输入

```yaml
context:
  phase_cycle: "Phase4-Cycle9"
  module: "mobile"
  changed_files: ["lib/auth.dart", "test/auth_test.dart"]
  spec_id: "add-auth-feature"      # 来自 Phase A
  task_list: [TASK-001, ...]       # 来自 Phase A

config:
  skip_steps: []
  params:
    coverage_threshold: 80
    branch_prefix: "feature"
```

### 步骤执行

```yaml
B.0 - REQUIRE claim (coordination-claim-lifecycle-and-overlap Part A1, MUST):
  precondition: 进入 B.1 前, 本 (container) 必须已有一条本 session 的 active claim
  check: phase1_gate telemetry / 编排层记忆 (本 session 是否已跑 phase1_gate)
  if_missing:
    - MUST 先跑 (不可跳过, advisory 强制 — 步骤级 MUST, 非 hook 硬锁):
      python3 "${CLAUDE_PLUGIN_ROOT:-aria}/skills/state-scanner/scripts/phase1_gate.py" \
        --raw-track-id "<A.1 认领时派生的那一串>" --phase B --mode advisory \
        [--linked-issue "<repo>#<n>"] --repo-path "<repo root>"
    - goal 直驱 / 绕过 state-scanner 进入的 session 也适用 (B-entry 手动补 claim)
    - carry-id 取值 = **A.1 认领时派生的那一串** (逐字, 不重新拼); 未走 A.1 的
      session 沿用 Spec id —— 两端不同串会各认领一条, 收尾时 release 只命中一条
  skip_if:
    # 可判定谓词 (review I5 — 注意: "无 coordination 基础设施"不是有效 skip 条件,
    # write_claim auto_bootstrap 会自动建 ref, 缺 ref 不构成 skip 理由):
    #   ⚠️ 勘正: bootstrap 走的是 push=False (coordination_ref.py:800), **它不推**。
    #   真正的推送点是 phase1_gate.py 的 Step 9 resilient_push (:880) 与 7a
    #   self-resume push (:597) —— 把「建 ref」当成「已同步远端」会高估协调面。
    #   另: --no-push / ARIA_COORDINATION_NO_PUSH 只抑制推送, **不是 skip 条件** ——
    #   claim 照写本地, 跳过的只是同步那一步。
    - coordination.enabled 显式 false (opt-out; 默认 true — config-loader SOT)
    - 非 git repo / 无 origin remote (gate 自身 fail-soft ABORT, 不阻断)
  third_party_note: 默认 true 意味着装了 aria-plugin 的项目走 Phase B 会向其
    origin 推 refs/aria/coordination (仅协调元数据, 不碰代码分支)。单人单终端
    项目若不想要该 ref, 显式设 state_scanner.coordination.enabled=false。
  rationale: defect a — 2026-07-11 双子星撞车实证"认领非强制→从不认领";
             advisory mode 放行一切, 成本只是一次 claim 写入, 收益是 reconcile 有据可依
  诚实边界: 本步骤管不到绕过 state-scanner/phase-b 的自主 bot (Layer 2 orchestrator
             维度另开 aria-orchestrator issue 跟踪)

B.1 - 分支管理:
  skill: branch-manager
  action: create
  skip_if:
    - already_on_feature_branch: true
  action:
    - 检查当前分支
    - 创建功能分支
  output:
    branch_name: "feature/mobile/TASK-001-add-auth"

B.2 - 测试验证:
  skill: test-verifier
  params:
    coverage_threshold: 80
  degrade_if:
    - no_test_files: true           # 降级模式，不阻塞
  action:
    - 检测变更文件类型
    - 运行对应测试
    - 检查覆盖率
  output:
    test_passed: true
    coverage: 87.5
    tests_run: 15

B.2.5 - 框架 build 验证 (Aria #95, 可选 / advisory):
  config: phase_b_developer.framework_build_check
  enabled_if: framework_build_check.enabled == true AND command != null
  skip_if:
    - 无 build 命令配置 (no-op, 如 Aria 自身等无 build 项目)
      → 输出 framework_build_passed: not_configured (tri-state: skip ≠ pass,
        避免下游把"未跑"误读为"已验证"; 镜像 #141 coordination_ref_present 三态)
  action:
    - test-verifier 通过后、进入 Phase C 前, 跑配置的 framework build 命令
      (e.g. `npm run build` / `next build` / `astro build`)
    - 目的: framework convention bug (route handler export 限制 / routing /
      client-server 误用 / metadata 白名单) tsc/lint/单测**不抓**, 仅 build 期暴露
  on_fail:
    - mode=advisory (默认): 警告 + 记录, 不阻塞 (让 owner 决定)
    - mode=blocking: 阻塞进入 Phase C
  rationale: 本地 build 1-3min << CI fail + redeploy ~14min/iteration
             (实战 SilkNode US-096 Next.js route named export 2 次 hotfix)
  output:
    framework_build_passed: true | false | not_configured   # tri-state (skip ≠ pass)
    build_command: "npm run build"

B.3 - 架构同步:
  skill: arch-update
  skip_if:
    - no_architecture_changes: true
  action:
    - 检测架构相关变更
    - 更新 ARCHITECTURE.md
  output:
    arch_updated: true
    files_modified: ["docs/ARCHITECTURE.md"]
```

### Mid-Implementation 审计检查点 (新增)

```yaml
B.mid - 审计引擎 (条件触发):
  checkpoint: mid_implementation
  trigger: B.2 任务执行循环中，每个任务完成后检查进度阈值
  condition: audit.enabled == true
             AND audit.checkpoints.mid_implementation != "off"
             AND tasks_completed_count >= total_tasks * (audit.mid_implementation.threshold / 100)

  注意: 每次 Phase B 生命周期内仅触发一次 (触发后置标记，后续任务不再检查)
        默认 threshold=50 (已完成任务数 >= 总任务数 × 50%)，来自 config.audit.mid_implementation

  步骤:
    1. 每个任务完成后更新 tasks_completed_count
    2. 检查触发条件 (audit.enabled + checkpoint enabled + progress >= threshold)
    3. 如已触发过 (mid_audit_fired=true) → 跳过
    4. 如条件满足: 调用 audit-engine
       - checkpoint: "mid_implementation"
       - mode: 来自配置 (convergence / challenge / adaptive)
       - context: 已完成任务的变更文件路径列表 (diff)
    5. 处理 verdict:
       - PASS / PASS_WITH_WARNINGS → 继续执行剩余任务
       - FAIL → 阻塞，呈现审计报告，等待用户决策后再继续
    6. 标记 mid_audit_fired=true

  on_fail: 阻塞继续执行任务, 输出审计报告
  on_skip: 继续任务执行循环
  output:
    mid_audit_verdict: "PASS"             # PASS | PASS_WITH_WARNINGS | FAIL (如触发)
    mid_audit_report: ".aria/audit-reports/mid_implementation-{timestamp}.md"
```

### Mid-Post-Spec spec 漂移检查点 (Aria #79, 条件触发)

```yaml
B.drift - 审计引擎 spec 漂移校验 (条件触发):
  checkpoint: mid_post_spec
  trigger: B.2 任务执行期, SMOKE / 集成测试暴露 spec 陈述与运行实际不符
  condition: audit.enabled == true
             AND audit.checkpoints.mid_post_spec != "off"
             AND spec_drift_detected
  drift 信号 (任一):
    - 机械: 测试/SMOKE 报告含 verdict_invalidated_assumptions 字段且非空
    - 概念: AI 识别运行实际 (test 行为 / 集成结果) 与 spec 原陈述矛盾
  注意: 与 mid_implementation 正交 (后者按进度阈值, 本者按漂移事件);
        可在一次 Phase B 内多次触发 (每个独立漂移点一次)

  步骤:
    1. 检测到 drift 信号 → 暂停当前 Phase B 任务执行
    2. 调用 audit-engine:
       - checkpoint: "mid_post_spec"
       - mode: 来自 adaptive_rules (L1 off / L2 convergence / L3 challenge)
       - max_rounds: 1 (恒单轮, 快速校验)
       - scope: 仅漂移涉及的 spec 陈述 (非全量)
    3. audit 产出 append-only spec amendment 建议 (类 DEC Amendment: 日期 +
       原陈述 + 修正 + 触发证据)
    4. 采纳 amendment (append 到 proposal.md, 不改原文; **同时**在原失效断言处加
       inline 指向标记防 amended-and-ignored, 见 audit-points.md neutralize 要求)
       → resume Phase B (后续实施基于修正后假设, 避免带 stale 假设继续)

  on_drift: 暂停 → mini-audit → amendment → resume (blocking=false, advisory)
  on_skip: 继续任务执行循环 (未检测到漂移 / checkpoint off)
  output:
    mid_post_spec_triggered: false        # true 如触发
    spec_amendments: []                   # append-only amendment block 列表 (如触发)
```

### Post-Implementation 审计 (audit-engine)

```yaml
B.post - 审计引擎 (可选):
  checkpoint: post_implementation
  trigger: B.3 完成后 (实现验证通过后)
  condition: 读取 .aria/config.json (via config-loader)
             audit.enabled == true
             AND checkpoints.post_implementation != "off"

  步骤:
    1. 通过 config-loader 读取 .aria/config.json audit 块
    2. 检查 audit.enabled — false 则跳过，保持现有行为不变
    3. 检查 audit.checkpoints.post_implementation — "off" 则跳过
    4. 如启用: 调用 audit-engine
       - checkpoint: "post_implementation"
       - mode: 来自配置 (convergence / challenge / adaptive)
       - context: 当前变更文件列表 (changed_files)
    5. 处理 verdict:
       - PASS / PASS_WITH_WARNINGS → 继续进入 Phase C
       - FAIL → 阻塞，输出审计报告，不进入 Phase C

  backward_compat:
    audit.enabled=false: 完全跳过，Phase B 行为与之前完全相同
    旧配置 experiments.agent_team_audit: 由 audit-engine 内部映射处理
    旧字段 experiments.agent_team_audit_points: 兼容映射，"post_implementation" 检查保留

  fallback_description: |
    audit-engine 内部通过 agent-team-audit 单轮引擎执行审计。
    直接调用 agent-team-audit 已由 audit-engine 编排层取代。

  on_fail: 阻塞进入 Phase C, 输出审计报告
  on_skip: 继续到 Phase C (审计未启用)
  output:
    audit_verdict: "PASS"                 # PASS | PASS_WITH_WARNINGS | FAIL (如启用)
    audit_report: ".aria/audit-reports/post_implementation-{timestamp}.md"
```

### 输出

```yaml
success: true
steps_executed: [B.1, B.2, B.3]
steps_skipped: []
results:
  B.1:
    branch_name: "feature/mobile/TASK-001-add-auth"
  B.2:
    test_passed: true
    coverage: 87.5
  B.3:
    arch_updated: true

context_for_next:
  branch_name: "feature/mobile/TASK-001-add-auth"
  test_results:
    passed: true
    coverage: 87.5
  arch_sync_status: "updated"
```

---

## Context 占用感知 (暂停 vs 继续, #104)

Phase B 多任务实施期, "当前会话继续 vs 暂停 (形成自然 commit boundary)" 是关键决策点。
**不要凭感觉估** context 余量 (实证 #104: 凭感觉 +22% 偏差导致不必要暂停)。调用 [aria-context-monitor](../aria-context-monitor/SKILL.md) 机读 runtime-truth:

```bash
python3 "${CLAUDE_PLUGIN_ROOT:-aria}/skills/aria-token-telemetry/scripts/token_telemetry.py" --project-root .
```

- `source=relay_cache` (confidence=high): 读 `used_percentage` — runtime 真值, 0 偏差
- `source=transcript_fallback` (estimate): 读 `used_percentage_proxy` — window 可能低估, 放宽解读

**决策阈值** (advisory): `<70%` 继续 / `70-85%` 找 commit boundary / `>85%` 建议在当前任务收尾后暂停 + commit。
本 skill **只提供数据, 不自动中断** — 暂停决策由 AI 判断。relay 未装时引导 `setup_relay.sh`。

**会话收尾触发** (session-closer TASK-007): 读完 occupancy 后调 [session-closer 的 closeout_trigger](../session-closer/scripts/closeout_trigger.py) —— 占用 ≥ 阈值(默认 85%)**且**有未交接成果(未提交变更 / `upm.followups` / 新 memory 未入 §8)时 **advise** 现在 `/session-closer` 写交接(advisory, **不自动执行**)。

**契约 (I-1)**: `closeout_trigger` 消费 **`token_telemetry.py` 的输出 schema** (含 `source` 字段), **不是** relay cache 原始文件 (无 `source` → 落 unavailable → 恒不 nudge)。须先跑 token_telemetry 再喂其输出:

```bash
TEL=$(mktemp)
python3 "${CLAUDE_PLUGIN_ROOT:-aria}/skills/aria-token-telemetry/scripts/token_telemetry.py" --project-root . > "$TEL"
python3 "${CLAUDE_PLUGIN_ROOT:-aria}/skills/session-closer/scripts/closeout_trigger.py" \
  --project-root . --telemetry-json "$TEL"; rm -f "$TEL"
```
`should_nudge=true` → 向 owner surface nudge; 否则静默继续。

---

## 跳过规则

| 条件 | 跳过步骤 | 检测方法 |
|------|---------|----------|
| 已在功能分支 | B.1 | 当前分支不是 main/develop |
| 无测试文件 | B.2 (降级) | 变更文件无对应 *_test.* |
| 无架构变更 | B.3 | 无 ARCHITECTURE.md 变更 |
| **emergency hotfix 单测替代** | B.2 单测 (manual prod validation 替代) | `hotfix/*` 分支 + `Prod-Validated:` trailer (见下) |

### emergency hotfix: B.2 单测替代 + Prod-Validated trailer gate (#58, v1.35.0)

prod 紧急修复 (emergency_hotfix lane, `hotfix/*` 分支) 中, ops/config 改动 (无业务逻辑可单测) 可用 **manual prod validation 替代 B.2 单测** —— 但需 **机械 gate**:

```
若 (hotfix/* 分支 AND 拟跳单测):
    grep commit message for "^Prod-Validated:" trailer
    ├── 存在 → 允许 manual prod validation 替代单测 (lighter lane 继续)
    └── 缺失 → BLOCK, 回标准 lane (必须写单测 或 补 Prod-Validated trailer + 根因块)
```

- **机检 = trailer 存在性** (防"忘记留验证证据"); **内容真实性**靠 owner PR review + audit trail 事后追溯 (不事前防伪)。
- trailer 格式 + 根因块见 `standards/conventions/git-commit.md §6.4`。
- 非 hotfix 分支 / 非跳单测 → 此 gate 不触发, 标准 B.2 不变。

### 跳过逻辑

```yaml
skip_evaluation:
  B.1:
    - check: git branch --show-current
      skip_if: not in [main, master, develop]
      reason: "已在功能分支"

  B.2:
    - check: test file mapping
      degrade_if: no corresponding test files
      action: 运行但不阻塞，输出警告

  B.3:
    - check: changed_files
      skip_if: no files match *ARCHITECTURE*.md
      reason: "无架构文档变更"
```

---

## 输出格式

```
╔══════════════════════════════════════════════════════════════╗
║              PHASE B - DEVELOPMENT                           ║
╚══════════════════════════════════════════════════════════════╝

📋 执行计划
───────────────────────────────────────────────────────────────
  B.1 branch-manager    → 创建分支
  B.2 test-verifier     → 测试验证
  B.3 arch-update       → 架构同步 (跳过 - 无架构变更)

🚀 执行中...
───────────────────────────────────────────────────────────────
  ✅ B.1 完成 → 分支: feature/mobile/TASK-001-add-auth
  ✅ B.2 完成 → 测试: 15/15 通过, 覆盖率: 87.5%
  ○  B.3 跳过 → 理由: 无架构文档变更

📤 上下文输出
───────────────────────────────────────────────────────────────
  branch: feature/mobile/TASK-001-add-auth
  tests: passed (87.5% coverage)
  ready_for: Phase C
```

---

## 使用示例

### 示例 1: 完整开发阶段

```yaml
输入:
  context:
    module: "mobile"
    changed_files: ["lib/auth.dart", "test/auth_test.dart"]

执行:
  B.1: 创建分支 → feature/mobile/TASK-001-add-auth
  B.2: 运行测试 → 15/15 通过
  B.3: 更新架构 → ARCHITECTURE.md 已更新

输出:
  context_for_next:
    branch_name: "feature/mobile/TASK-001-add-auth"
    test_passed: true
```

### 示例 2: 跳过分支创建

```yaml
输入:
  current_branch: "feature/add-auth"  # 已在功能分支

执行:
  B.1: 跳过 (已在功能分支)
  B.2: 运行测试
  B.3: 检查架构

输出:
  steps_skipped: [B.1]
  branch_name: "feature/add-auth"  # 使用现有分支
```

### 示例 3: 测试降级

```yaml
输入:
  changed_files: ["lib/new_feature.dart"]  # 无对应测试

执行:
  B.1: 创建分支
  B.2: 降级模式 (警告无测试)
  B.3: 检查架构

输出:
  B.2:
    mode: "degraded"
    warning: "lib/new_feature.dart 没有对应测试"
    suggestion: "使用 flutter-test-generator 生成测试"
```

---

## 错误处理

| 错误 | 原因 | 处理 |
|------|------|------|
| 分支创建失败 | 分支已存在 | 切换到现有分支 |
| 测试失败 | 代码问题 | 停止执行，报告失败 |
| 架构更新失败 | 文档格式错误 | 输出警告，继续执行 |

### 测试失败处理

```yaml
on_test_failure:
  action: stop
  report:
    - 失败的测试列表
    - 错误信息
    - 修复建议
  next_step: "修复测试后重新运行 Phase B"
```

---

## 与其他 Phase 的关系

```
phase-a-planner
    │
    │ context:
    │   - spec_id
    │   - task_list
    ▼
phase-b-developer (本 Skill)
    │
    │ context_for_next:
    │   - branch_name
    │   - test_results
    │   - arch_sync_status
    ▼
phase-c-integrator
```

---

## 新技能集成 (v1.2.0)

> **新增于 v1.2.0** - 集成 enforcement-mechanism-redesign 新技能

### 技能依赖图

```
phase-b-developer
    │
    ├──> branch-manager v2.0.0
    │    └── 自动模式决策 (Branch/Worktree)
    │
    ├──> subagent-driver v1.0.0
    │    └── Fresh Subagent 执行
    │
    └──> branch-finisher v1.0.0
         └── 完成流程 + 测试验证
```

### B.1 分支管理增强

```yaml
B.1 - 分支管理 (增强版):
  skill: branch-manager v2.0.0
  features:
    - 自动模式决策 (5因子评分)
    - Branch 模式 (简单任务)
    - Worktree 模式 (复杂/并行任务)

  mode_decision:
    factors:
      - file_count: 变更文件数
      - cross_directory: 跨目录变更
      - task_count: 任务数量
      - risk_level: 风险等级
      - parallel_needed: 并行需求
    threshold: 3  # >= 3 使用 Worktree

  output:
    mode: "branch" | "worktree"
    branch_name: "feature/mobile/TASK-001-xxx"
    worktree_path: ".git/worktrees/TASK-001-xxx"  # 仅 worktree 模式
```

### B.2 开发执行增强

```yaml
B.2 - 开发执行 (增强版):
  skill: subagent-driver v1.0.0
  features:
    - Fresh Subagent 模式
    - 任务间代码审查
    - 4选项完成流程
    - TDD 强制执行 (方案 A)

  execution_pattern:
    for_each_task:
      1. 启动 Fresh Subagent (隔离上下文)
      2. 应用 TDD 约束 (RED-GREEN-REFACTOR)
      3. 执行任务
      4. 任务间代码审查
      5. 更新状态

    tdd_enforcement:
      enabled: true              # 自动启用 TDD
      mode: "enforce"             # enforce | monitor | off
      rules:
        - test_before_code: true  # 必须先写测试
        - fail_first: true        # 测试必须先失败
        - minimal_implementation: true  # 最小实现原则

    inter_task_review:
      severity_levels:
        - Critical: 阻塞，必须修复
        - Major: 警告，建议修复
        - Minor: 提示，可忽略

  output:
    tasks_completed: [TASK-001, TASK-002, ...]
    review_issues: [...]
    tdd_compliance: "passed"      # TDD 合规状态
    context_for_finisher: {...}
```

### B.3 完成流程增强

```yaml
B.3 - 完成流程 (增强版):
  skill: branch-finisher v1.0.0
  features:
    - 测试前置验证
    - 4选项完成流程
    - Worktree 智能清理

  pre_validation:
    blocking:
      - unit_tests: 单元测试必须通过
      - type_check: 类型检查必须通过
      - build: 构建必须成功
    warning:
      - lint: Lint 检查 (可警告通过)
      - coverage: 覆盖率检查 (可警告通过)

  completion_options:
    "[1] 提交并创建 PR":
      action: commit + PR
      worktree_cleanup: 询问用户
    "[2] 继续修改":
      action: 返回开发
      worktree_cleanup: 否
    "[3] 放弃变更":
      action: 回滚
      worktree_cleanup: 强制清理
    "[4] 暂停保存":
      action: 保存状态
      worktree_cleanup: 否
```

### 集成执行流程

```yaml
完整 Phase B 执行流程 (v1.2.0):

  1. 接收 Phase A 输出
     ├── spec_id
     ├── task_list
     └── complexity_score

  2. B.1 分支管理 (branch-manager)
     ├── 评估复杂度
     ├── 决策模式 (Branch/Worktree)
     └── 创建分支/Worktree

  3. B.2 开发执行 (subagent-driver)
     ├── 加载任务列表
     ├── 逐任务执行 (Fresh Subagent)
     ├── 任务间审查
     └── 汇总结果

  4. B.3 完成流程 (branch-finisher)
     ├── 测试前置验证
     ├── 4选项完成流程
     └── Worktree 清理决策

  5. 输出到 Phase C
     ├── branch_name
     ├── test_results
     ├── completion_option
     └── ready_for_integration
```

### 配置参数

```yaml
phase_b_config:
  # branch-manager 配置
  branch_manager:
    mode_threshold: 3
    worktree_base: ".git/worktrees"
    branch_prefix: "feature"

  # subagent-driver 配置
  subagent_driver:
    isolation_level: "L2"  # L1/L2/L3
    enable_inter_task_review: true
    critical_blocks: true

  # branch-finisher 配置
  branch_finisher:
    run_tests: true
    run_lint: true
    run_build: true
    coverage_threshold: 85
    auto_cleanup: false

  # TDD 双保险配置 (v1.3.0 新增)
  tdd:
    # 方案 A: Fresh Subagent TDD 保护
    subagent_level:
      enabled: true
      mode: "enforce"           # enforce | monitor | off
      rules:
        test_before_code: true
        fail_first: true
        minimal_implementation: true

    # 方案 B: 主会话 TDD 保护 (由 workflow-runner 启用)
    session_level:
      enabled: true             # 由 workflow-runner pre-hook 控制
      strict_mode: false        # 首次使用建议 false
      skip_patterns:
        - "**/*.md"
        - "**/*.json"
        - "**/config/**"
```

---

## 相关文档

### 核心技能 (v1.2.0 新增)

- [branch-manager](../branch-manager/SKILL.md) - B.1 分支管理 (v2.0.0 自动模式决策)
- [subagent-driver](../subagent-driver/SKILL.md) - B.2 开发执行 (Fresh Subagent)
- [branch-finisher](../branch-finisher/SKILL.md) - B.3 完成流程 (测试验证+清理)

### 辅助技能

- [test-verifier](../test-verifier/SKILL.md) - 测试验证 (被 branch-finisher 调用)
- [arch-update](../arch-update/SKILL.md) - 架构同步
- [tdd-enforcer](../tdd-enforcer/SKILL.md) - TDD 强制执行

### Phase 关联

- [phase-a-planner](../phase-a-planner/SKILL.md) - 上一阶段
- [phase-c-integrator](../phase-c-integrator/SKILL.md) - 下一阶段

---

**最后更新**: 2026-01-21
**Skill版本**: 1.2.0

---

## Git Worktree 集成

> **新增于 v1.1.0**

Phase B 支持使用 Git Worktrees 创建隔离的开发环境。

### Worktree 模式

```yaml
use_worktree: true  # 启用 worktree 模式

B.1 - 分支创建 (Worktree 模式):
  action:
    - 使用 branch-manager 的 worktree 创建
    - 工作目录: .git/worktrees/{task-name}/
  output:
    worktree_path: ".git/worktrees/TASK-001-user-auth"
    branch_name: "feature/backend/TASK-001-user-auth"
```

### Worktree 路径切换

```yaml
切换到 worktree:
  command: cd .git/worktrees/{task-name}/

返回主分支:
  command: cd ../..

清理 worktree:
  command: git worktree remove .git/worktrees/{task-name}/
```

### Worktree 配置参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `use_worktree` | `false` | 是否启用 worktree 模式 |
| `worktree_base` | `.git/worktrees` | worktree 基础路径 |

---

## 两阶段评审机制

> **新增于 v1.1.0**

Phase B 扩展支持两阶段评审：**规范合规性** → **代码质量**。

### 评审流程

```yaml
B.Review - 两阶段评审:

  Phase 1 - 规范合规性检查:
    enabled: true
    blocking: true
    checks:
      - OpenSpec 格式验证
      - UPM 状态同步检查
      - 架构文档同步检查
    output:
      spec_compliance: pass/fail
      issues: [...]

  Phase 2 - 代码质量检查:
    enabled: true
    blocking: false  # 警告但不阻塞
    checks:
      - 测试覆盖率检查 (>= 85%)
      - 代码复杂度分析
      - 安全漏洞扫描
    output:
      code_quality_score: 0-100
      recommendations: [...]
```

### Phase 1: 规范合规性

| 检查项 | 说明 | 阻塞 |
|--------|------|------|
| OpenSpec 格式 | proposal.md/tasks.md 格式正确 | ✅ |
| UPM 状态 | 进度状态与实际一致 | ✅ |
| 架构文档 | 代码变更与文档同步 | ✅ |

**失败处理**: 关键问题必须修复后方可继续

### Phase 2: 代码质量

| 检查项 | 阈值 | 阻塞 |
|--------|------|------|
| 测试覆盖率 | >= 85% | ❌ (警告) |
| 代码复杂度 | <= 10 | ❌ (警告) |
| 安全扫描 | 无高危漏洞 | ❌ (警告) |

**失败处理**: 记录警告，生成改进建议

### 评审报告

```yaml
评审报告格式:
  summary:
    phase1_status: "pass"
    phase2_status: "warning"
    overall_score: 85

  phase1_issues:
    - severity: "critical"
      description: "UPM 状态未更新"
      fix_required: true

  phase2_recommendations:
    - type: "coverage"
      current: 82
      target: 85
      suggestion: "为 AuthManager 添加测试用例"
```

### 阻塞机制

```yaml
阻塞条件:
  - Phase 1 有 critical 级别问题
  - OpenSpec 格式验证失败

绕过选项:
  - 用户显式确认 "force_continue"
  - 标记为 "technical_debt" (技术债务)
```

### 评审配置

```yaml
review_config:
  enabled: true
  phase1:
    enabled: true
    blocking: true
    checks:
      openspec_format: true
      upm_sync: true
      arch_doc_sync: true
  phase2:
    enabled: true
    blocking: false
    checks:
      test_coverage:
        threshold: 85
      code_complexity:
        threshold: 10
      security_scan:
        level: "high"
```

---

## 两阶段评审与 Worktree 配合使用

```yaml
完整流程 (Worktree + 两阶段评审):

  B.1 - 创建 Worktree 分支
  ↓
  B.2 - 开发 + 测试验证
  ↓
  B.Review - Phase 1: 规范合规性
  ↓ (通过)
  B.Review - Phase 2: 代码质量
  ↓ (警告/通过)
  B.3 - 架构同步
```

---

## 相关文档 (更新)

- [branch-manager](../branch-manager/SKILL.md) - B.1 分支管理 + Worktree 支持
- [test-verifier](../test-verifier/SKILL.md) - B.2 测试验证
- [arch-update](../arch-update/SKILL.md) - B.3 架构同步
- [tdd-enforcer](../tdd-enforcer/SKILL.md) - TDD 强制执行
- [subagent-driver](../subagent-driver/SKILL.md) - B.2 Fresh Subagent 执行
- [branch-finisher](../branch-finisher/SKILL.md) - B.3 完成流程
- [phase-a-planner](../phase-a-planner/SKILL.md) - 上一阶段
- [phase-c-integrator](../phase-c-integrator/SKILL.md) - 下一阶段
- [Aria Workflow Enhancement](../../../standards/openspec/changes/aria-workflow-enhancement/proposal.md) - 增强提案

---

## TDD 双保险机制 (v1.3.0 新增)

> **设计目标**: 确保无论通过何种方式执行代码编写，TDD 规则都会被强制执行

### 为什么需要双保险？

```
┌─────────────────────────────────────────────────────────────────────────┐
│                        TDD 保护缺口分析                                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  单一保护点的问题:                                                       │
│  ┌────────────────┐      ┌────────────────┐                            │
│  │ workflow-runner│──┬──▶│ phase-b-dev    │                            │
│  │  (主会话 Hook) │  │   │                │                            │
│  └────────────────┘  │   └────────┬───────┘                            │
│                      │            │                                    │
│                      │            ├──▶ subagent-driver                   │
│                      │            │        │                            │
│                      │            │        ▼                            │
│                      │            │  ┌─────────────┐                    │
│                      │            │  │Fresh Subagent│ ← 新会话，无 Hook │
│                      │            │  └─────────────┘                    │
│                      │            │        ❌ TDD 保护失效              │
│                      │            │                                    │
│  用户直接编辑代码 ───┴────────────┴── ❌ 绕过 phase-b                  │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│                        双保险保护方案                                    │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌────────────────┐                                                    │
│  │ workflow-runner│                                                    │
│  │  Pre-Hook B    │ ──▶ 方案 B: 启用主会话 TDD Hook                     │
│  └────────┬───────┘           ↓                                        │
│           │              ┌─────────┐                                   │
│           ▼              │主会话 TDD│ ← 保护用户直接编辑               │
│  ┌────────────────┐      └─────────┘                                   │
│  │ phase-b-dev    │                                                     │
│  │                │ ──▶ 方案 A: 传递 TDD 配置给 Subagent               │
│  └────────┬───────┘           ↓                                        │
│           │              ┌─────────────┐                               │
│           └─────────────▶│Subagent TDD │ ← 保护 Fresh Subagent        │
│                          └─────────────┘                               │
│                                                                         │
│  ✅ 完整闭环：主会话 + 子会话全覆盖                                     │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
```

### 方案 A: Fresh Subagent TDD 保护

```yaml
作用对象: subagent-driver 启动的 Fresh Subagent
触发时机: B.2 阶段调用 subagent-driver 时
传递方式: 通过 context 传递 TDD 配置
保护范围: 子会话内的所有代码编写操作

配置:
  phase_b_config.tdd.subagent_level:
    enabled: true
    mode: "enforce"
    rules:
      test_before_code: true
      fail_first: true
      minimal_implementation: true
```

### 方案 B: 主会话 TDD 保护

```yaml
作用对象: workflow-runner 主会话
触发时机: 进入 Phase B 之前的 pre-hook
启用方式: workflow-runner 自动调用 tdd-enforcer
保护范围: 主会话内的所有代码编写操作

配置:
  phase_b_config.tdd.session_level:
    enabled: true
    strict_mode: false
    skip_patterns: ["**/*.md", "**/*.json"]
```

### 执行流程

```yaml
完整 Phase B 执行 (TDD 双保险):

  1. workflow-runner pre-hook (方案 B)
     ├── 检测即将进入 Phase B
     ├── 调用 tdd-enforcer 启用主会话 TDD
     └── 返回 tdd_session_id

  2. phase-b-developer 执行
     ├── B.1: 创建分支
     ├── B.2: subagent-driver (方案 A)
     │   ├── 传递 TDD 配置到 Fresh Subagent
     │   ├── Fresh Subagent 启用时加载 TDD 约束
     │   └── 每个任务执行时强制 TDD
     └── B.3: branch-finisher
         ├── 运行所有测试 (质量门禁)
         └── 4 选项完成流程

  3. workflow-runner post-hook
     ├── 检测 Phase B 完成
     └── 可选: 保持或关闭 TDD Hook
```

### 配置优先级

```yaml
TDD 配置优先级 (从高到低):

  1. 项目配置 (.claude/tdd-config.json)
     └── 项目级开关，最高优先级

  2. 环境变量 (ARIA_TDD_ENABLED)
     └── 环境级覆盖

  3. phase_b_config.tdd
     └── Phase B 级别配置

  4. 默认值 (enabled: false)
     └── 兜底默认值
```

### 禁用 TDD

```yaml
# 方式 1: 项目级配置 (.claude/tdd-config.json)
{
  "enabled": false
}

# 方式 2: Phase 配置
phase_b_config:
  tdd:
    subagent_level:
      enabled: false
    session_level:
      enabled: false

# 方式 3: 临时跳过 (特定文件)
# tdd-enforcer 会根据 skip_patterns 自动跳过
```

---

**最后更新**: 2026-06-19 (Aria #95: B.2.5 可选 framework build 验证步骤 + config framework_build_check)
**Skill版本**: 1.5.0