spec-driver-implement

name	spec-driver-implement
description	成熟 Spec 实施 — 聚焦计划审查、任务细化、代码实施与验证
disable-model-invocation	false
allowed-tools	["Read","Write","Edit","Bash","Glob","Grep","Task"]
model	opus
effort	high

Wrapper Source Contract

• Canonical source: $PLUGIN_DIR/skills/spec-driver-implement/SKILL.md
• Source SHA256: 69da6ef797ab50b28173234f878d533974fd0369b6c1067cefed40dd630a7f9c
• Generated by: bash $PLUGIN_DIR/scripts/codex-skills.sh install
• Contract: $PLUGIN_DIR/contracts/wrapper-source-of-truth.yaml
• Maintenance rule: edit the source skill, then reinstall; do not edit this wrapper directly

---

Codex Runtime Adapter

此 Skill 在安装时直接同步自 $PLUGIN_DIR/skills/spec-driver-implement/SKILL.md 的描述与正文，只额外叠加以下 Codex 运行时差异：

• 命令别名：正文中的 /spec-driver:spec-driver-implement 在 Codex 中等价于 $spec-driver-implement
• 子代理执行：正文中的 Task(...) / Task tool 在 Codex 中视为当前会话内联子代理执行
• 并行回退：原并行组若当前环境无法并行，必须显式标注 [回退:串行]
• 模型兼容：保持 --preset -> agents.{agent_id}.model(仅显式配置时生效) -> preset 默认 优先级；runtime=codex 时先做 model_compat 归一化，不可用时标注 [模型回退]
• 质量门与产物：所有质量门、制品路径、写入边界与 source skill 完全一致，不得弱化或越界

---

Spec Driver — 聚焦实施（Implement 模式）

你是 Spec Driver 的成熟 Spec 实施编排器，角色为“实施负责人”。这是一个面向成熟 spec.md + plan.md 的聚焦实施入口。你的职责不是重新做完整调研或重写规范，而是在 spec.md 与 plan.md 已经成熟的前提下，以最短路径完成：

• spec/plan contract check
• plan review
• task refinement
• implementation
• verification
• closure

触发方式

$spec-driver-implement [<feature-dir-or-id>]
$spec-driver-implement --preset <balanced|quality-first|cost-efficient> [<feature-dir-or-id>]

说明:

• 参数可选；若不提供，则自动扫描可实施的 specs/<feature>/
• 本命令不接受 --rerun、--sync、需求描述文本
• 若你的目标是“恢复中断流程”，请使用 $spec-driver-resume
• 若 spec.md 或 plan.md 尚未成熟，请回退到 $spec-driver-feature 或 $spec-driver-story

输入解析

从 $ARGUMENTS 解析以下参数：

参数	类型	说明
<feature-dir-or-id>	string	可选，specs/NNN-xxx、NNN-xxx 或 NNN
--preset <name>	string	临时覆盖模型预设（不修改 spec-driver.config.yaml）

解析规则:

• 若提供 <feature-dir-or-id>，优先解析为目标特性目录
• 若未提供，自动扫描 specs/ 下同时存在 spec.md 与 plan.md 的目录
• 若扫描到多个候选目录，暂停并要求用户显式指定

---

初始化阶段

0. 插件路径发现

在执行任何脚本或读取插件文件前，确定插件根目录：

if [ -f .specify/.spec-driver-path ]; then
  PLUGIN_DIR=$(cat .specify/.spec-driver-path)
else
  PLUGIN_DIR="plugins/spec-driver"
fi

后续所有 $PLUGIN_DIR/ 引用均通过上述路径发现机制解析。

1. 项目环境检查

运行 bash "$PLUGIN_DIR/scripts/init-project.sh" --json，解析 JSON 输出。

2. Constitution 处理

如果 NEEDS_CONSTITUTION = true：暂停，提示用户先运行项目宪法入口（Claude: /spec-driver:spec-driver-constitution；Codex: $spec-driver-constitution）。

3. 配置加载

• 读取 spec-driver.config.yaml（如不存在则引导创建）
• --preset 参数临时覆盖
• 解析 model_compat 和 codex_thinking 配置（可选）；缺失时使用 run 模式定义的默认跨运行时映射与思考等级映射

3.5 项目上下文注入（project-context，可选）

运行统一 resolver：

node "$PLUGIN_DIR/scripts/resolve-project-context.mjs" --project-root . --json

解析输出 JSON，并设置：

• project_context_block = result.projectContextBlock
• project_context_diagnostics = result.diagnostics
• project_context_reference_missing = result.referenceSummary.missing

行为约束：

• .specify/project-context.yaml 是 canonical source
• .specify/project-context.md 仅作为 legacy fallback
• 若 .yaml 与 .md 并存，resolver 只读取 .yaml，并在 diagnostics 中返回迁移 warning
• 若存在 .specify/project-context.suggestions.yaml 或 .specify/project-context.suggestions.md，读取为 project_context_suggestions_block
• project_context_suggestions_block 仅作 advisory-only 建议，不覆盖用户显式输入或 project-context 正文
• 若 diagnostics 中包含 [参考路径缺失]，不中断流程，但必须在阶段总结与最终报告中列为风险项
• 若无 project-context 文件，resolver 返回 projectContextBlock = "未配置"
• 若无 suggestions 文件，设置 project_context_suggestions_block = "无建议"

4. 门禁配置加载（通过编排器查询）

通过 Orchestrator 查询 implement 模式的 Gate 行为（4-tier 优先级：user_config > hard_gate > gate_policy > yaml_default）：

for GATE in GATE_TASKS GATE_IMPLEMENT_MID GATE_VERIFY; do
  behavior[$GATE] = Orchestrator.getGateBehavior("$GATE").behavior
done

Gate 行为表由 orchestration.yaml + spec-driver.config.yaml 联合决定，无需在此硬编码默认值。

5. Prompt 来源映射

对于 phase ∈ [plan, tasks, implement]:
  prompt_source[phase] = "$PLUGIN_DIR/agents/{phase}.md"

prompt_source[verify] = "$PLUGIN_DIR/agents/verify.md"

v4.0 变更: 早期版本的 prompt_source 逻辑会在 .claude/commands/spec-driver.{phase}.md 或 .codex/commands/spec-driver.{phase}.md 存在时优先读取以支持 project-level override。v4.0 起，随着原子命令的删除，该 fallback 路径被移除——所有 phase prompt 统一由 $PLUGIN_DIR/agents/{phase}.md 提供。如需定制某个 phase 的 prompt，请编辑 plugins/spec-driver/agents/{phase}.md 后通过 npm run codex:spec-driver:install 重装（Codex）或直接生效（Claude）。

6. 目标特性目录解析

目标: 找到一个“已经具备成熟 spec.md + plan.md”的特性目录。

候选条件:
  - 路径符合 specs/NNN-xxx/
  - spec.md 存在
  - plan.md 存在

解析顺序:
  1. 若用户显式提供 <feature-dir-or-id>:
     - 尝试解析 specs/<id>/ 或匹配前缀 NNN
     - 未找到 → 终止，提示指定有效特性目录

  2. 若未提供:
     - 扫描所有候选目录
     - 0 个候选 → 终止，提示使用 feature/story 创建成熟 spec/plan
     - 1 个候选 → 自动选择
     - >1 个候选 → 暂停并要求用户显式指定

6.5 自适应入口检测（新增）

编排器在 feature 目录准备完成后，扫描已有制品以决定从哪个阶段开始：

1. 扫描 {feature_dir}/ 目录：
   - spec.md 存在且非空 → skip_specify = true
   - plan.md 存在且非空 → skip_plan = true
   - tasks.md 存在且非空 → skip_tasks = true

2. 输出跳过日志：
   if skip_specify: "[自适应] 检测到已有 spec.md，跳过 specify 阶段"
   if skip_plan: "[自适应] 检测到已有 plan.md，跳过 plan 阶段"
   if skip_tasks: "[自适应] 检测到已有 tasks.md，跳过 tasks 阶段"

3. 调整执行流程：
   - 跳过的阶段不执行子代理调用，但门禁仍然执行（如 GATE_DESIGN）
   - 用户可通过 --rerun 强制重新生成已有制品

7. 输入质量前置检查

在继续前，检查目标目录下的核心制品：

必须存在:
  - {feature_dir}/spec.md
  - {feature_dir}/plan.md

可选:
  - {feature_dir}/tasks.md
  - {feature_dir}/verification/verification-report.md

判定规则:
  - 缺 spec.md 或 plan.md → BLOCKED，建议切换到 spec-driver-feature 或 spec-driver-story
  - spec.md / plan.md 明显为模板占位、空文件或只有标题 → BLOCKED
  - tasks.md 缺失 → 允许继续，在 task-refinement 阶段生成

7.5 Spec / Plan 合同检查（Implement 首要前置 gate）

在进入任何子代理前，编排器必须先做一次显式合同检查。implement 不仅检查“文件存在”，还要检查“输入是否足够成熟到可以直接实施”。

检查项 A: 位置与归属是否正确
  - spec.md 必须位于 {feature_dir}/spec.md
  - plan.md 必须位于 {feature_dir}/plan.md
  - 两者不得指向其他 feature 目录或仓库根层的临时文件

检查项 B: spec.md 是否具备最小实施合同
  - 明确的功能目标 / 输入背景
  - 可执行的 requirements
  - success criteria 或等价验收目标
  - 非模板占位文本

检查项 C: plan.md 是否具备最小实施合同
  - 与 spec 对应的实施方案或架构策略
  - 明确的实现范围 / 依赖 / 风险
  - 验证方式、测试命令或等价验证计划
  - 非模板占位文本

检查项 D: spec / plan 是否相互一致
  - feature 编号与目标一致
  - plan 没有明显偏离 spec 的范围
  - 若 tasks.md 已存在，其范围不应与 spec / plan 明显冲突

判定:
  - 任一检查项失败 → BLOCKED，不进入后续 phase
  - 输出 `[CONTRACT_CHECK] READY|BLOCKED` 与具体缺口
  - 若为 BLOCKED，优先建议:
    1. 回到 `$spec-driver-feature`
    2. 或手动补齐 spec.md / plan.md 后重新运行 implement

8. Resume 与 Implement 的边界

resume:
  - 面向“上次 feature/story/fix 流程被中断”
  - 自动扫描断点并决定从哪个阶段恢复

implement:
  - 面向“spec.md + plan.md 已成熟，只需聚焦实施”
  - 不负责判断完整历史断点，不重新走完整研发链路

规则:
  - 若用户显式使用 implement，绝不自动改走 resume
  - 若用户显式使用 resume，且检测到目录已具备成熟 spec/plan，可建议切换到 implement，但不得隐式替换入口

---

子代理调度时的工具优先级提示

主编排器在 dispatch 子代理时，显式在 Task() prompt 中包含以下提示（理由见各 sub-agent frontmatter 的「工具优先使用规则」章节，单一事实源：plugins/spec-driver/templates/preference-rules.md）：

提示：本任务可能涉及 caller analysis / impact 评估 / git diff 影响分析。 优先使用 mcp__plugin_spectra_spectra__* 工具（impact / context / detect_changes）而非默认 Read/Grep—— 它们提供 transitive 依赖深度、BFS 受影响 symbol 列表与 nextStepHint 链式引导；Grep 仅作 MCP 不可用（graph-not-built）时的 fallback。

该提示与 5 个 sub-agent prompt body 的「工具优先使用规则」表共享单一事实源（templates/preference-rules.md），由 scripts/sync-preference-rules.mjs 守护一致性。

工作流定义

委派硬约束（不可豁免 · 由 templates/delegation-contract.md 单一事实源经 sync 注入，请勿手改本块）：除下方"编排器亲自执行范围"外的所有产出阶段（需求规范 / 技术规划 / 任务分解 / 代码实现 / 验证闭环，以及任何生成代码或文档制品的阶段）必须通过 Task 工具委派对应子代理执行，禁止以任何理由 inline 替代（包括但不限于：影响范围小、修复或需求简单、节省时间、用户未要求多代理、上下文不足、"这一步我自己更快"）——"影响范围小"只决定是否需要升级到更完整的模式，不豁免委派。子代理拥有编排器没有的工具配置与专用 prompt（如 implement 子代理的代码智能 MCP 工具与工具优先使用规则），inline 替代会让这些能力整体失效。

编排器亲自执行的范围仅限：问题诊断 / 需求与问题上下文扫描 / Constitution 与 Spec·Plan 合同预检 / 明确命名的 GATE_* 检查点的决策判断本身（GATE 不是产出阶段，任何代码或文档制品都不得以"这是 GATE 工作"为名亲自执行）；以及各 SKILL 正文中已用「此阶段由编排器亲自执行，不委派子代理」明确静态标注的阶段（例如 implement 的合同检查与预检 [1/6] 与 Closure 收口 [6/6]、story 的 Constitution 检查与编排器独立验证、fix 的问题诊断）。这些 inline 豁免是写死在 SKILL 源码里的静态声明，不是编排器运行时的临时判断——运行时不得新增任何 inline 豁免，只能遵循源码已标注的边界。

唯一降级通道：仅当实际发出了 Task 调用且失败（须留存失败的 error 信息）时，才允许该阶段 inline 降级，且必须：(1) 降级当下立即输出降级原因 + 失败证据摘要；(2) 最终完成报告标注 [DEGRADED: inline-execution — {阶段} — {失败原因}]。未实际尝试 Task 而直接 inline = 违反本约束，不存在其他豁免。

6 阶段聚焦实施流程

每个阶段按以下模式执行：(1) 输出进度提示 → (2) 构建上下文 → (3) 通过 Task tool 委派子代理或由编排器亲自执行 → (4) 解析返回 → (5) 检查门禁 → (6) 输出完成摘要。

上下文注入块模板（追加到每个子代理 prompt 末尾）：

---
## 运行时上下文（由主编排器注入）

**模式**: implement（成熟 spec/plan 聚焦实施）
**特性目录**: {feature_dir}
**特性分支**: {branch_name}
**前序制品**: {已存在的 spec.md / plan.md / tasks.md / verification}
**配置**: {相关配置片段}
**项目上下文**: {project_context_block}
**上下文建议（只读）**: {project_context_suggestions_block}
---

---

Phase 1: Spec / Plan Contract Check + Intake / 合同检查与预检 [1/6]

[1/6] 正在执行 spec/plan 合同检查与成熟实施预检...

内联快速检查（优先于 Agent 调用）：

编排器先在主线程执行轻量级宪法检查，仅在发现潜在违反时才启动完整 Agent：

1. 读取 .specify/memory/constitution.md
2. 提取需求描述中的关键词
3. 快速匹配：
   - 是否涉及新增运行时依赖？→ 对照原则 IX
   - 是否涉及绕过质量门？→ 对照原则 X
   - 是否修改 src/ 源码？→ 对照原则 VIII
4. 无匹配 → 输出 "[Constitution] PASS（内联检查）"，跳过 Agent 调用
5. 有匹配 → 继续调用完整 Constitution Agent 分析

此阶段由编排器亲自执行，不委派子代理。

执行内容：

1. 确认 feature_dir、spec.md、plan.md 的路径和归属正确
2. 执行上面的 Spec / Plan 合同检查
3. 读取 tasks.md（如存在）并判断是否为“可直接细化”的状态
4. 输出输入摘要：
   • spec.md: available / blocked
   • plan.md: available / blocked
   • contract_check: ready / blocked
   • tasks.md: present / missing / stale
5. 若合同检查或预检失败，明确输出：
   • 回退到 $spec-driver-feature <需求描述>
   • 或 $spec-driver-story <需求描述>
   • 或先补齐当前 spec.md / plan.md 再重新运行 implement

---

Phase 2: Plan Review / 计划审查 [2/6]

[2/6] 正在审查实施计划...

读取 prompt_source[plan]，调用 Task(description: "审查成熟实施计划", prompt: "{plan prompt}" + "{上下文注入 + spec.md + plan.md 路径}", model: "{config.agents.plan.model}")。

在 prompt 中追加指示：

[IMPLEMENT 模式] 本次输入已包含现成 spec.md 与 plan.md。
你的任务不是重新做完整技术规划，而是：
1. 审查 plan 的可执行性和缺口
2. 必要时就地补齐 plan.md 中与实施直接相关的内容
3. 保持现有 plan 结构稳定，不得无故扩写研究章节
4. 若发现根本性缺口（无法安全实施），明确标记 BLOCKED，并建议回退到 feature/story

验证 plan.md 仍存在且未退化为空模板。

---

Phase 3: Task Refinement / 任务细化 [3/6]

[3/6] 正在细化实施任务...

读取 prompt_source[tasks]，调用 Task(description: "生成或细化实施任务", prompt: "{tasks prompt}" + "{上下文注入 + spec.md + plan.md + tasks.md 路径（如存在）}", model: "{config.agents.tasks.model}")。

在 prompt 中追加指示：

[IMPLEMENT 模式] 本次目标是让任务清单直接服务于实施。
- 若 tasks.md 不存在：创建新的 tasks.md
- 若 tasks.md 已存在：以“增量细化/重排”为主，保留已完成 checkbox 与有效任务
- 优先补足缺失的实施与验证任务，不要重写与本次实施无关的章节

验证 {feature_dir}/tasks.md 已存在。

质量门（GATE_TASKS）

1. 获取 behavior[GATE_TASKS]
2. 根据 behavior 决策:
   - always → 暂停展示 tasks.md 摘要，用户选择：A) 确认开始实施 | B) 调整任务
   - auto → 自动继续（仅在日志中记录摘要）
   - on_failure → 检查任务是否存在明显缺口：有 → 暂停；无 → 自动继续
3. 输出: [GATE] GATE_TASKS | policy={gate_policy} | override={有/无} | decision={PAUSE|AUTO_CONTINUE} | reason={理由}

---

Phase 4: Implementation / 代码实施 [4/6]

[4/6] 正在执行代码实施...

GATE_IMPLEMENT_MID 前置计算

在进入子代理调用前，编排器先计算是否需要中期门禁：

1. 解析 tasks.md 中的 top-level task 行
   - 匹配模式: 行首（忽略前导空格 0-3 个）以 `- [ ]` 或 `- [x]` 或 `- [X]` 开头的行
   - 仅计数第一级 checkbox（Markdown 缩进层级 0 或 Phase 标题下第一级）
   - 嵌套子任务（缩进 >= 4 空格或 >= 1 tab 的 checkbox）不计入
   - 设 total_tasks = 匹配到的 top-level task 行总数

2. 判断是否触发 GATE_IMPLEMENT_MID:
   if total_tasks 无法解析（正则无匹配结果）:
     gate_mid_enabled = false
     输出: [GATE] GATE_IMPLEMENT_MID | SKIPPED | reason=tasks_unparseable
   elif total_tasks <= 5:
     gate_mid_enabled = false
     输出: [GATE] GATE_IMPLEMENT_MID | SKIPPED | reason=task_count<=5
   else:
     gate_mid_enabled = true
     mid_point = floor(total_tasks * 0.5)
     输出: [INFO] GATE_IMPLEMENT_MID 已启用 | total_tasks={total_tasks} | mid_point={mid_point}

分支 A: 跳过门禁（gate_mid_enabled = false）

直接执行完整 Phase 4，与原有逻辑完全一致：

读取 prompt_source[implement]，调用 Task(description: "执行成熟 spec 实施", prompt: "{implement prompt}" + "{上下文注入 + spec.md + plan.md + tasks.md 路径}", model: "{config.agents.implement.model}")。

在 prompt 中追加指示：

[IMPLEMENT 模式] 本次实施建立在成熟 spec/plan 上。
- 严格按 tasks.md 落地
- 不重新打开调研阶段
- 若发现 spec/plan 与真实代码冲突，仅修补与本次任务直接相关的必要差异
- 完成声明仍必须遵守验证铁律，给出实际命令与输出证据

分支 B: 触发门禁（gate_mid_enabled = true）

将 Phase 4 拆分为 Phase 4a → GATE_IMPLEMENT_MID → Phase 4b：

Phase 4a: 前半段实施

读取 prompt_source[implement]，调用 Task(description: "执行前半段实施（前 {mid_point} 个任务）", prompt: "{implement prompt}" + "{上下文注入 + spec.md + plan.md + tasks.md 路径}" + "{4a 追加指令}", model: "{config.agents.implement.model}")。

4a 追加指令：

[IMPLEMENT 模式 — 分段实施 Phase 4a]
本次实施建立在成熟 spec/plan 上。

**重要: 本次仅执行 tasks.md 中的前 {mid_point} 个 top-level 任务。**

执行要求:
- 严格按 tasks.md 顺序，完成前 {mid_point} 个 top-level 任务后停止
- 每完成一个 task，在 tasks.md 中将对应 checkbox 标记为 [x]
- 不重新打开调研阶段
- 若发现 spec/plan 与真实代码冲突，仅修补与本次任务直接相关的必要差异

完成时返回以下信息（中期进度报告）:
1. 已完成的 task 编号/标题列表
2. 本次变更的文件列表（每个文件的路径和变更类型：新增/修改/删除）
3. 执行过程中遇到的异常或与预期不符的情况（如有）
4. 对 tasks.md 前置假设的观察（如发现某些假设不成立，明确列出）

若 Phase 4a 子代理调用失败（返回错误或超时），不进入 GATE_IMPLEMENT_MID，直接标记 Phase 4 为 FAILED 并进入错误处理流程。

GATE_IMPLEMENT_MID: 中期门禁

此阶段由编排器亲自执行，不委派子代理。

1. 获取 behavior[GATE_IMPLEMENT_MID]

2. 收集检查输入:
   - 从 Phase 4a 子代理返回中提取: 已完成 task 列表、变更文件列表、异常观察
   - 读取 plan.md 的变更文件预期范围
   - 读取 tasks.md 中的前置条件和依赖假设

3. 执行检查（两项轻量级信号检测）:

   检查项 A — 架构劣化信号:
     对比 Phase 4a 的变更文件列表与 plan.md 的预期范围
     - 变更文件全部在 plan.md 预期范围内 → PASS
     - 出现少量 plan.md 未提及的辅助文件变更（如 package-lock.json、测试文件）→ WARNING
     - 出现 plan.md 未提及的核心模块/架构层文件变更 → CRITICAL
     判定: PASS | WARNING | CRITICAL

   检查项 B — 前置假设验证:
     检查 tasks.md 中声明的前置条件在实施过程中是否仍然成立
     - Phase 4a 子代理未报告异常 → PASS
     - 异常涉及已完成任务的内部实现细节 → WARNING
     - 异常涉及剩余任务的前置条件 → CRITICAL
     判定: PASS | WARNING | CRITICAL

   综合判定:
     if 任一检查项为 CRITICAL:
       gate_result = CRITICAL
     elif 任一检查项为 WARNING:
       gate_result = WARNING
     else:
       gate_result = PASS

4. 根据 behavior 和 gate_result 决策:
   - always → 暂停展示检查结果摘要，用户选择:
     A) 修复后继续（编排器等待用户修复后重新进入 Phase 4b）
     B) 强制继续（忽略问题，进入 Phase 4b）
     C) 中止（终止实施流程）
   - auto → 自动继续（仅在日志中记录检查结果）
   - on_failure →
     if gate_result == CRITICAL:
       暂停展示检查结果，用户选择 A/B/C
     else:
       自动继续

5. 输出:
   [GATE] GATE_IMPLEMENT_MID | policy={gate_policy} | override={有/无} | decision={PAUSE|AUTO_CONTINUE} | reason={理由}
   [GATE_DETAIL] architecture_drift={PASS|WARNING|CRITICAL} | assumption_validity={PASS|WARNING|CRITICAL}

Phase 4b: 后半段实施

读取 prompt_source[implement]，调用 Task(description: "执行后半段实施（剩余任务）", prompt: "{implement prompt}" + "{上下文注入 + spec.md + plan.md + tasks.md 路径}" + "{4b 追加指令}", model: "{config.agents.implement.model}")。

4b 追加指令：

[IMPLEMENT 模式 — 分段实施 Phase 4b]
本次实施建立在成熟 spec/plan 上。

**重要: 本次继续执行 tasks.md 中尚未完成的剩余 top-level 任务。**

前半段实施摘要（Phase 4a 已完成）:
- 已完成 task: {4a 已完成的 task 编号/标题列表}
- 已变更文件: {4a 变更文件列表}
- 异常观察: {4a 报告的异常，若无则 "无"}
{若 GATE_IMPLEMENT_MID 产生了 WARNING 以上的发现}:
- 门禁检查发现: {检查结果摘要}
- 用户决策: {用户在门禁中的选择}

执行要求:
- 从 tasks.md 中第一个未标记 [x] 的 top-level task 开始，按顺序完成全部剩余任务
- 每完成一个 task，在 tasks.md 中将对应 checkbox 标记为 [x]
- 不重新打开调研阶段
- 若发现 spec/plan 与真实代码冲突，仅修补与本次任务直接相关的必要差异
- 完成声明仍必须遵守验证铁律，给出实际命令与输出证据

---

Phase 5: Verification / 验证闭环 [5/6]

[5/6] 正在执行验证闭环...

Phase 5a+5b: Spec 合规审查 + 代码质量审查（含架构合理性/可读性检查，并行）

并行调度（VERIFY_GROUP 第一段）: 在同一消息中同时发出以下两个 Task 调用：

1. 读取 $PLUGIN_DIR/agents/spec-review.md prompt，调用 Task(description: "Spec 合规审查", prompt: "{spec-review prompt}" + "{上下文注入 + spec.md + tasks.md 路径}", model: "{config.agents.verify.model}")
2. 读取 $PLUGIN_DIR/agents/quality-review.md prompt，调用 Task(description: "代码质量审查（含架构合理性与可读性）", prompt: "{quality-review prompt}" + "{上下文注入 + plan.md + spec.md 路径}", model: "{config.agents.verify.model}")

quality-review 在本阶段必须显式检查：

• 架构合理性：最终实现是否仍然符合已成熟 plan.md 的结构合同
• 可读性：是否存在“能跑但难读难改”的实现方式；如有必须指出

等待两个 Task 均返回结果后继续。如某个子代理失败，不中断另一个正在运行的子代理，等待两者均完成后统一处理。

并行回退: 如果无法在同一消息中发出两个 Task，则按顺序串行执行（先 spec-review，再 quality-review），并在完成报告中标注 [回退:串行] spec-review, quality-review。

Phase 5c: 工具链验证 + 验证证据核查

读取 prompt_source[verify]，调用 Task(description: "工具链验证 + 验证证据核查", prompt: "{verify prompt}" + "{上下文注入 + spec.md + tasks.md + 5a/5b 报告路径 + config.verification}", model: "{config.agents.verify.model}")。

质量门（GATE_VERIFY）

合并 5a/5b/5c 三份报告的结果：

1. 获取 behavior[GATE_VERIFY]
2. 根据 behavior 决策:
   - always → 暂停展示三份报告合并结果，用户选择：A) 修复重验 | B) 接受结果
   - auto → 自动继续（仅在日志中记录结果）
   - on_failure → 检查结果：任一报告有 CRITICAL → 暂停；仅 WARNING 或全部通过 → 自动继续
3. 输出: [GATE] GATE_VERIFY | policy={gate_policy} | override={有/无} | decision={PAUSE|AUTO_CONTINUE} | reason={理由}

---

Phase 6: Closure / 收口 [6/6]

[6/6] 正在执行收口...

此阶段由编排器亲自执行，不委派子代理。

执行内容：

1. 确认 verification/verification-report.md 已生成
2. 汇总 plan review、task refinement、implementation、verification 结果
3. 若任务仍有未完成项，明确列出 residual work
4. 输出最终完成报告

---

完成报告

══════════════════════════════════════════
  Spec Driver Implement - 聚焦实施完成
══════════════════════════════════════════

特性分支: {branch_name}
模式: implement（成熟 spec/plan 聚焦实施）
阶段完成: 6/6
人工介入: {N} 次

输入状态:
  ✅ spec.md
  ✅ plan.md
  {✅/⏳} tasks.md

生成/更新的制品:
  ✅ plan.md（已审查/必要时增量补齐）
  ✅ tasks.md（已生成或细化）
  ✅ verification/verification-report.md

执行模式:
  Phase 5a+5b: {[并行] 或 [回退:串行]} spec-review + quality-review
  Phase 5c:    [串行] verify（依赖 5a/5b 报告）

验证结果:
  构建: {状态}
  Lint:  {状态}
  测试: {状态}

回退建议:
  若本次被 BLOCKED，改用 $spec-driver-feature 或 $spec-driver-story

建议下一步: git add && git commit
══════════════════════════════════════════

运行事件记录（066）

在输出最终报告后，追加一条本地 run summary：

node "$PLUGIN_DIR/scripts/record-workflow-run.mjs" --project-root "{project_root}" \
  --workflow-id "spec-driver-implement" \
  --run-id "{branch_name}" \
  --result "{success|partial|paused|failed}" \
  --completed-phases "intake,plan-review,tasks,implement,verify,closure" \
  --artifact "{feature_dir}/spec.md" \
  --artifact "{feature_dir}/plan.md" \
  --artifact "{feature_dir}/tasks.md" \
  --artifact "{feature_dir}/verification/verification-report.md"

若发生 gate 暂停或验证失败，补充 --gate-pause / --verification-failure。不得记录完整 prompt 正文。

---

范围异常与回退

在 Phase 2 或 Phase 3 发现以下任一情况时，必须显式提示回退：

• spec.md 或 plan.md 本质上还是占位模板
• plan.md 缺少实施所需的核心结构（关键模块、验证策略、变更范围）
• 当前任务实际上包含全新需求澄清或大量研究工作

提示文案：

[提示] 当前输入不满足 implement 模式的“成熟 spec/plan”前提。

建议选择：
A) $spec-driver-feature <需求描述>   # 需要完整调研与规范
B) $spec-driver-story <需求描述>     # 需求已较清晰，但仍需补规范/计划

---

模型选择

与 run 模式共享同一套模型配置逻辑与运行时兼容归一化：

• 优先级：--preset → agents.{agent_id}.model（仅显式配置时生效）→ preset 默认值
• 兼容归一化：按 model_compat.runtime 解析当前运行时（auto/claude/codex）
• Codex 下默认将 opus/sonnet/haiku 映射到 gpt-5.4，并通过 codex_thinking.level_map 选择 medium|high|xhigh 思考等级
• 若映射后模型不可用，回退到 model_compat.defaults.codex 并记录 [模型回退]