phase-b-developer

name	phase-b-developer
description	十步循环 Phase B - 开发阶段执行器，编排 B.1-B.3 步骤。 使用场景："执行开发阶段"、"Phase B"、"创建分支并运行测试"
argument-hint	[--skip-tests]
disable-model-invocation	false
user-invocable	true
allowed-tools	Bash, Read, Write, Glob, Grep, Task, Skill

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。

字段	默认值	说明
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

---

执行流程

输入

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"

步骤执行

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 "<本 cycle carry-id/Spec id>" --phase B --mode advisory \
        [--linked-issue "<repo>#<n>"] --repo-path "<repo root>"
    - goal 直驱 / 绕过 state-scanner 进入的 session 也适用 (B-entry 手动补 claim)
  skip_if:
    # 可判定谓词 (review I5 — 注意: "无 coordination 基础设施"不是有效 skip 条件,
    # write_claim auto_bootstrap 会自动建 ref 并 push 到项目 origin):
    - 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 审计检查点 (新增)

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, 条件触发)

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)

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"

输出

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 机读 runtime-truth:

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 —— 占用 ≥ 阈值(默认 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 再喂其输出:

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 不变。

跳过逻辑

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: 完整开发阶段

输入:
  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: 跳过分支创建

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

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

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

示例 3: 测试降级

输入:
  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 生成测试"

---

错误处理

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

测试失败处理

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 分支管理增强

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 开发执行增强

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 完成流程增强

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: 否

集成执行流程

完整 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

配置参数

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 - B.1 分支管理 (v2.0.0 自动模式决策)
• subagent-driver - B.2 开发执行 (Fresh Subagent)
• branch-finisher - B.3 完成流程 (测试验证+清理)

辅助技能

• test-verifier - 测试验证 (被 branch-finisher 调用)
• arch-update - 架构同步
• tdd-enforcer - TDD 强制执行

Phase 关联

• phase-a-planner - 上一阶段
• phase-c-integrator - 下一阶段

---

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

---

Git Worktree 集成

新增于 v1.1.0

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

Worktree 模式

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 路径切换

切换到 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 扩展支持两阶段评审：规范合规性 → 代码质量。

评审流程

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	❌ (警告)
安全扫描	无高危漏洞	❌ (警告)

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

评审报告

评审报告格式:
  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 添加测试用例"

阻塞机制

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

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

评审配置

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 配合使用

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

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

---

相关文档 (更新)

• branch-manager - B.1 分支管理 + Worktree 支持
• test-verifier - B.2 测试验证
• arch-update - B.3 架构同步
• tdd-enforcer - TDD 强制执行
• subagent-driver - B.2 Fresh Subagent 执行
• branch-finisher - B.3 完成流程
• phase-a-planner - 上一阶段
• phase-c-integrator - 下一阶段
• Aria Workflow Enhancement - 增强提案

---

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 保护

作用对象: 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 保护

作用对象: 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"]

执行流程

完整 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

配置优先级

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

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

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

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

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

禁用 TDD

# 方式 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