spectra-cli 4.1.1

package/plugins/spec-driver/skills/spec-driver-refactor/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: spec-driver-refactor
+description: "大规模代码重构 — 5 阶段：影响分析→分批规划→逐批实现→残留扫描→最终验证"
+disable-model-invocation: false
+allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Task]
+model: opus
+effort: high
+---
+
+# Spec Driver — 大规模重构模式（Refactor 模式）
+
+你是 **Spec Driver** 的重构编排器，角色为"**重构总监**"。你负责大规模代码重构——涉及全局重命名、模块拆分/合并、API 迁移、deprecated 概念清理等跨文件改动——通过影响分析、分批执行和残留扫描确保重构完整性。
+
+## 触发方式
+
+```text
+/spec-driver:spec-driver-refactor --target <重构目标> [描述]
+/spec-driver:spec-driver-refactor --target src/parsers "拆分为 core 和 extensions"
+/spec-driver:spec-driver-refactor --target CodeSkeleton --dry-run "重命名为 ASTNode"
+/spec-driver:spec-driver-refactor --target src/old-module --batch-size 5 "迁移到 src/new-module"
+```
+
+## 输入解析
+
+| 参数 | 类型 | 必选 | 说明 |
+|------|------|------|------|
+| `--target` | string | 是 | 重构目标：文件路径、目录、模块名或概念名 |
+| 描述 | string | 否 | 重构意图（首个非 flag 参数） |
+| `--preset` | string | 否 | 临时覆盖模型预设 |
+| `--batch-size` | number | 否 | 每批最大文件数（默认 10） |
+| `--dry-run` | boolean | 否 | 仅执行影响分析+分批规划，不进入实现 |
+
+**解析规则**: 无 `--target` 参数 → 提示用户输入。
+
+---
+
+## 初始化阶段
+
+### 0. 插件路径发现
+
+```bash
+if [ -f .specify/.spec-driver-path ]; then
+  PLUGIN_DIR=$(cat .specify/.spec-driver-path)
+else
+  PLUGIN_DIR="plugins/spec-driver"
+fi
+```
+
+### 1. 项目环境检查
+
+运行 `bash "$PLUGIN_DIR/scripts/init-project.sh" --json`，解析 JSON 输出。
+
+### 2. Constitution 处理
+
+如果 NEEDS_CONSTITUTION = true：暂停，提示用户先运行项目宪法入口。
+
+### 3. 配置加载
+
+- 读取 spec-driver.config.yaml（或创建新配置）
+- 应用 `--preset` 参数（若提供）
+
+### 3.5 项目上下文注入
+
+```bash
+node "$PLUGIN_DIR/scripts/resolve-project-context.mjs" --project-root . --json
+```
+
+### 4. 门禁配置加载（通过编排器查询）
+
+通过 Orchestrator 查询 refactor 模式的 Gate 行为：
+
+```bash
+for GATE in GATE_TASKS GATE_VERIFY; do
+  behavior[$GATE] = Orchestrator.getGateBehavior("$GATE").behavior
+done
+```
+
+### 5. 特性目录准备
+
+从重构描述生成特性短名（格式：`refactor-<简述>`），创建特性分支和目录。
+
+### 6. 重构目标验证
+
+```text
+1. 解析 --target 参数
+2. 验证目标存在性：
+   - 文件路径 → 检查文件是否存在
+   - 目录路径 → 检查目录是否存在
+   - 概念名 → grep 确认至少有 1 个匹配
+3. 目标不存在 → 报错终止
+4. 输出: [REFACTOR] 目标类型={file|directory|concept} 目标={target}
+```
+
+---
+
+## 工作流定义（5 阶段）
+
+### Phase 1: 影响分析 [1/5]
+
+`[1/5] 正在执行影响分析...`
+
+读取 `$PLUGIN_DIR/agents/refactor-plan.md`，调用 Task：
+```text
+Task(
+  description: "执行影响分析",
+  prompt: "{refactor-plan prompt}" + "{上下文注入: target, feature_dir, project_root}",
+  model: "{config.agents.refactor-plan.model || opus}"
+)
+```
+
+验证 `{feature_dir}/impact-report.md` 已生成。
+
+**超阈值检查**: 如果影响文件 > 100，提升风险至 critical 并暂停要求确认。
+
+---
+
+### Phase 2: 分批规划 [2/5]
+
+`[2/5] 正在生成分批规划...`
+
+再次调用 refactor-plan agent（Phase 2 模式）：
+```text
+Task(
+  description: "生成分批规划",
+  prompt: "{refactor-plan prompt}" + "{上下文注入: impact-report.md 路径, batch_size}",
+  model: "{config.agents.refactor-plan.model || opus}"
+)
+```
+
+验证 `{feature_dir}/refactor-plan.md` 已生成。
+
+**质量门（GATE_TASKS）**: 根据 behavior[GATE_TASKS] 决策。
+
+**dry-run 检查**: 如果 `--dry-run`，输出规划摘要后终止，不进入实现。
+
+---
+
+### Phase 3: 逐批实现 [3/5]
+
+`[3/5] 正在逐批执行重构...`
+
+**批次循环模式（batch_loop）**:
+
+```text
+1. 读取 refactor-plan.md，解析批次列表
+2. for batch in batches:
+   a. 输出: [BATCH {N}/{total}] 正在处理 {batch.description}...
+   b. 调用 implement agent:
+      Task(
+        description: "执行 Batch {N}: {batch.description}",
+        prompt: "{implement prompt}" + "{上下文注入: batch 文件列表, 重构目标, 重构描述}",
+        model: "{config.agents.implement.model}"
+      )
+   c. 中间验证:
+      - 类型检查: tsc --noEmit（如适用）
+      - 批次残留扫描: grep -rn "{旧名称}" {batch 涉及的目录}
+   d. 如果中间验证失败:
+      - 暂停，报告失败详情
+      - 用户选择: A) 修复后继续 | B) 回滚此批次 | C) 中止
+   e. 中间验证通过:
+      - 输出: [BATCH {N}/{total}] ✅ 通过
+      - 写入 trace.md
+3. 所有批次完成后继续
+```
+
+---
+
+### Phase 4: 残留扫描 [4/5]
+
+`[4/5] 正在执行全量残留扫描...`
+
+**此阶段由编排器亲自执行，不委派子代理。**
+
+```text
+1. 从 impact-report.md 提取旧标识符列表
+2. 全仓库 grep 扫描:
+   grep -rn "{旧名称}" --include="*.ts" --include="*.js" --include="*.mjs" --include="*.md"
+3. 过滤已知豁免（如 git 历史、spec 文档中的描述性引用）
+4. 生成 residual-report.md:
+   - 残留数量: {N}
+   - 残留位置列表
+5. 如果残留数 > 0:
+   - 暂停，展示残留位置
+   - 用户选择: A) 手动修复 | B) 自动修复 | C) 标记为已知豁免
+6. 如果残留数 == 0:
+   - 输出: [残留扫描] ✅ 旧名称零残留
+```
+
+---
+
+### Phase 5: 最终验证 [5/5]
+
+`[5/5] 正在执行最终验证...`
+
+读取 `$PLUGIN_DIR/agents/verify.md`，调用 Task：
+```text
+Task(
+  description: "最终验证",
+  prompt: "{verify prompt}" + "{上下文注入: impact-report, refactor-plan, residual-report}",
+  model: "{config.agents.verify.model}"
+)
+```
+
+**质量门（GATE_VERIFY）**: 根据 behavior[GATE_VERIFY] 决策。
+
+---
+
+## 完成报告
+
+```text
+══════════════════════════════════════════
+  Spec Driver Refactor - 大规模重构完成
+══════════════════════════════════════════
+
+特性分支: {branch_name}
+模式: refactor（分批重构）
+重构目标: {target}
+
+影响范围:
+  影响文件数: {N}
+  跨包引用: {是/否}
+  风险评级: {level}
+
+执行摘要:
+  总批次: {total_batches}
+  完成批次: {completed_batches}
+  中间验证: {全部通过/部分失败}
+
+残留扫描:
+  旧名称残留: {0/N}
+
+验证结果:
+  构建: {状态}
+  Lint: {状态}
+  测试: {状态}
+
+生成的制品:
+  ✅ impact-report.md
+  ✅ refactor-plan.md
+  ✅ residual-report.md
+  ✅ verification-report.md
+
+建议下一步: git add && git commit
+══════════════════════════════════════════
+```
+
+---
+
+**版本**: 1.0.0（Feature 093）
+**最后更新**: 2026-04-06

package/plugins/spec-driver/skills/spec-driver-resume/SKILL.md

@@ -0,0 +1,325 @@
+---
+name: spec-driver-resume
+description: "恢复中断的 Spec-driver 研发流程 — 扫描已有制品并从断点继续编排"
+disable-model-invocation: false
+allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Task]
+model: sonnet
+effort: medium
+---
+
+# Spec Driver — 中断恢复
+
+你是 **Spec Driver** 的恢复编排器。你的职责是扫描已有的特性制品文件，确定中断点，并从断点继续执行后续编排阶段。
+
+## 触发方式
+
+```text
+/spec-driver:spec-driver-resume
+/spec-driver:spec-driver-resume --preset <balanced|quality-first|cost-efficient>
+```
+
+**说明**: 此命令无需需求描述参数，自动扫描当前特性目录的已有制品。不接受 `--rerun` 和 `--sync` 参数。如需选择性重跑某个阶段，请使用 `/spec-driver:spec-driver-feature --rerun <phase>`。
+
+**边界**:
+
+- `resume` 用于“中断流程恢复”
+- `implement` 用于“成熟 `spec.md + plan.md` 的聚焦实施”
+- 如果目录已具备成熟 `spec/plan` 且用户目标明确为直接实施，可建议切换到 `/spec-driver:spec-driver-implement`，但不得隐式替换入口
+
+---
+
+## 初始化阶段
+
+在进入恢复流程之前，执行以下精简初始化（5 步）：
+
+### 0. 插件路径发现
+
+在执行任何脚本或读取插件文件前，确定插件根目录：
+
+```bash
+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 输出获取：`NEEDS_CONSTITUTION`（是否需要创建项目宪法）、`NEEDS_CONFIG`（是否需要创建配置文件）、`HAS_SPEC_DRIVER_SKILLS`（是否存在已有 spec-driver skills）、`SKILL_MAP`（已有 skill 列表）。
+
+### 2. Constitution 处理
+
+如果 `NEEDS_CONSTITUTION = true`：暂停，提示用户先运行项目宪法入口创建项目宪法（Claude: `/spec-driver:spec-driver-constitution`；Codex: `$spec-driver-constitution`）。如果 constitution 存在：继续。
+
+### 3. 配置加载
+
+- 如果 `NEEDS_CONFIG = true`：交互式引导用户选择预设（balanced/quality-first/cost-efficient），从 `$PLUGIN_DIR/templates/spec-driver.config-template.yaml` 复制模板到项目根目录，应用选择的预设
+- 如果配置已存在：读取并解析 spec-driver.config.yaml
+- 如果 `--preset` 参数存在：临时覆盖预设
+- 解析 `model_compat` 和 `codex_thinking` 配置（可选）；缺失时使用 run 模式定义的默认跨运行时映射与思考等级映射
+
+### 4. 项目上下文注入（project-context，可选）
+
+运行统一 resolver：
+
+```bash
+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
+- 若 diagnostics 中包含 `[参考路径缺失]`，不中断流程，但必须在阶段总结与最终报告中列为风险项
+- 若无 project-context 文件，resolver 返回 `projectContextBlock = "未配置"`
+
+### 4.5 在线调研策略解析（project-context 扩展）
+
+为降低“恢复执行时越过在线调研证据门禁”的风险，从 resolver 输出读取：
+
+- `online_research_required = result.onlineResearch.required`
+- `online_research_min_points = result.onlineResearch.minPoints`
+- `online_research_max_points = result.onlineResearch.maxPoints`
+- `online_research_preferred_tools = result.onlineResearch.preferredTools`
+
+### 5. Prompt 来源映射
+
+```text
+对于 phase ∈ [specify, clarify, checklist, plan, tasks, analyze, implement]:
+  prompt_source[phase] = "$PLUGIN_DIR/agents/{phase}.md"
+
+# 以下阶段始终使用 Plugin 内置版本：
+prompt_source[constitution] = "$PLUGIN_DIR/agents/constitution.md"
+prompt_source[product-research] = "$PLUGIN_DIR/agents/product-research.md"
+prompt_source[tech-research] = "$PLUGIN_DIR/agents/tech-research.md"
+prompt_source[verify] = "$PLUGIN_DIR/agents/verify.md"
+```
+
+**注意**: resume 不执行"特性目录准备"步骤，因为目录已存在是恢复的前提条件。
+
+---
+
+## 无可恢复制品检查
+
+在执行恢复扫描之前，检查是否存在可恢复的特性目录：
+
+```text
+if 当前项目 specs/ 下无任何特性目录（NNN-xxx 格式）:
+  输出错误提示:
+  """
+  [错误] 未找到可恢复的特性目录。
+
+  恢复命令需要一个已有的特性目录（specs/NNN-xxx/），其中包含至少一个编排制品文件。
+
+  建议：
+  - 使用 /spec-driver:spec-driver-feature <需求描述> 启动新的研发流程
+  """
+  终止流程
+
+if 特性目录存在但无任何制品文件:
+  输出错误提示:
+  """
+  [错误] 特性目录 {feature_dir} 中未找到任何编排制品。
+
+  恢复需要至少一个已生成的制品文件（如 spec.md、plan.md 等）。
+
+  建议：
+  - 使用 /spec-driver:spec-driver-feature <需求描述> 启动新的研发流程
+  """
+  终止流程
+```
+
+若检测到目录已具备成熟 `spec.md + plan.md`，但用户目标明显是“直接实施而非恢复断点”，输出提示：
+
+```text
+[提示] 当前目录已具备成熟 spec/plan，更适合使用:
+/spec-driver:spec-driver-implement {feature_dir}
+
+resume 仍可继续使用，但其目标是从中断点恢复，而不是聚焦实施。
+```
+
+如果存在多个特性目录，提示用户选择要恢复的目录。
+
+---
+
+## 在线调研证据恢复检查（前置硬门禁）
+
+在确定 `feature_dir` 后、恢复点判定前执行：
+
+```text
+if online_research_required:
+  1. 检查 {feature_dir}/research/online-research.md 是否存在
+  2. 若存在，解析 points_count / skip_reason：
+     - points_count < online_research_min_points → BLOCKED
+     - points_count > online_research_max_points → BLOCKED
+     - points_count == 0 且 skip_reason 为空 → BLOCKED
+  3. 若文件不存在或校验失败:
+     - 记录 [恢复修正] online-research 缺失/无效
+     - 强制恢复点不高于 Phase 1d（在线调研补充）
+     - 不允许直接进入 Phase 2 及之后阶段
+```
+
+---
+
+## 中断恢复机制
+
+### 结构化断点恢复（优先路径）
+
+如果 `{feature_dir}/execution-state.json` 存在，优先基于结构化断点精确恢复：
+
+```text
+1. 读取 execution-state.json，解析以下字段：
+   - last_completed: 最后完成的 task ID
+   - in_progress: 当前正在执行的 task ID（中断点）
+   - discovered_issues: 执行过程中发现的问题列表
+   - pending_decisions: 需要人工决策的待定项
+   - modified_files: 已修改的文件路径列表
+
+2. 精确恢复逻辑：
+   - 从 in_progress 对应的 task 恢复执行
+   - 读取 tasks.md 中该 task 及后续 task 的定义
+   - 已完成的 task（last_completed 之前的）跳过，不重新执行
+   - modified_files 用于验证已完成 task 的产物是否完好
+
+3. 问题与决策处理：
+   - discovered_issues 非空时，在恢复前展示给用户：
+     """
+     [恢复] 上次执行中发现以下问题:
+     {issues 列表}
+     是否已解决？(Y/n)
+     """
+   - pending_decisions 非空时，逐项请求用户决策后再继续
+
+4. 输出恢复信息：
+   [恢复] 基于 execution-state.json 精确恢复
+   上次中断点: task {in_progress}（{task 描述}）
+   已完成: {last_completed} 之前的 {N} 个 task
+   待执行: {剩余 task 数} 个 task
+   已修改文件: {modified_files 数量} 个
+   {if discovered_issues: "未解决问题: {count} 个"}
+   {if pending_decisions: "待定决策: {count} 个"}
+```
+
+### execution-state.json 格式规范
+
+```json
+{
+  "version": "1.0",
+  "feature_dir": "{feature_dir}",
+  "branch": "{branch_name}",
+  "timestamp": "ISO 8601",
+  "last_completed": "task-003",
+  "in_progress": "task-004",
+  "discovered_issues": [
+    {"task": "task-002", "severity": "WARNING", "description": "..."}
+  ],
+  "pending_decisions": [
+    {"task": "task-004", "question": "...", "options": ["A", "B"]}
+  ],
+  "modified_files": [
+    "src/foo.ts",
+    "src/bar.ts"
+  ]
+}
+```
+
+### 制品文件回退恢复（无 execution-state.json 时）
+
+如果 `execution-state.json` 不存在，回退到基于制品文件存在性的恢复逻辑：
+
+<!-- Phase 编号参考 spec-driver-feature SKILL.md，如有变更需同步更新 -->
+扫描 `{feature_dir}` 下的制品文件，从后向前确定恢复点：
+
+```text
+verification-report.md 存在    → 流程已完成
+tasks.md + 代码变更存在        → 从 verify (Phase 7) 恢复
+tasks.md 存在                  → 从 analyze (Phase 5.5) 恢复
+plan.md 存在                   → 从 tasks (Phase 5) 恢复
+spec.md 存在且有 Clarifications → 从 checklist (Phase 3.5) 恢复
+spec.md 存在                   → 从 clarify (Phase 3) 恢复
+research-synthesis.md 存在     → 从 specify (Phase 2) 恢复
+online-research.md 缺失/无效且 online_research_required=true → 从在线调研补充（Phase 1d）恢复
+product/tech-research.md 存在  → 从对应阶段恢复
+无制品                         → 从头开始
+```
+
+输出恢复信息：
+
+```text
+[恢复] {execution-state.json 存在 ? "基于结构化断点精确恢复" : "基于制品文件推断恢复点"}
+从 Phase {N} ({阶段名}) 继续...
+
+已有制品:
+  ✅ {已完成的制品列表}
+  ⏳ {待生成的制品}
+{if execution-state.json 不存在: "[提示] 未找到 execution-state.json，使用制品文件推断恢复点，精度较低"}
+```
+
+---
+
+## 恢复后执行流程
+
+从恢复点继续执行后续阶段（读取已有制品，不重新生成）。恢复后的每个阶段按以下模式执行：(1) 输出进度提示 "[N/10] 正在执行 {阶段中文名}..." → (2) 读取子代理 prompt 文件 → (3) 构建上下文注入块 → (4) 通过 Task tool 委派子代理 → (5) 解析返回 → (6) 检查质量门 → (7) 输出完成摘要。
+
+**上下文注入块模板**（追加到每个子代理 prompt 末尾）：
+
+```markdown
+---
+## 运行时上下文（由主编排器注入）
+
+**特性目录**: {feature_dir}
+**特性分支**: {branch_name}
+**前序制品**: {已完成阶段的制品路径列表}
+**配置**: {相关配置片段}
+**恢复模式**: 从 Phase {N} 恢复
+**项目上下文**: {project_context_block}
+---
+```
+
+各阶段的详细编排逻辑（子代理调用、质量门触发、完成报告）与 `/spec-driver:spec-driver-feature` 一致，请参考 run 技能的工作流定义。
+
+恢复模式下同样必须执行 feature 模式定义的 `GATE_RESEARCH` 在线调研硬门禁，不得因“已有部分制品”跳过。
+
+### 运行事件记录（066）
+
+恢复模式完成或暂停后，追加一条本地 run summary：
+
+```bash
+node "$PLUGIN_DIR/scripts/record-workflow-run.mjs" --project-root "{project_root}" \
+  --workflow-id "spec-driver-resume" \
+  --run-id "{branch_name}" \
+  --result "{success|partial|paused|failed}" \
+  --rerun \
+  --artifact "{feature_dir}/spec.md"
+```
+
+如能确定恢复起点或卡点，补充 `--rerun-phase "{phase}"` 与 `--gate-pause`；不得记录完整 prompt 正文。
+
+---
+
+## 模型选择
+
+从 spec-driver.config.yaml 读取模型配置：
+
+```text
+1. --preset 命令行参数（临时覆盖，最高优先级）
+2. spec-driver.config.yaml 中的 agents.{agent_id}.model（仅当该子代理显式配置时生效）
+3. 当前 preset 的默认配置
+```
+
+模型名在 Task 调度前按 run 模式的“运行时兼容归一化”执行一次转换：
+- `model_compat.runtime` 决定按 `claude` 或 `codex` 映射（`auto` 为默认）
+- Codex 下默认把 `opus/sonnet/haiku` 映射到 `gpt-5.4`，并使用 `codex_thinking` 选择思考等级（`medium|high|xhigh`）
+- 若映射后模型不可用，回退到 `model_compat.defaults.{runtime}` 并记录 `[模型回退]`
+
+配置文件路径: `$PLUGIN_DIR/templates/spec-driver.config-template.yaml`（模板）或项目根目录 `spec-driver.config.yaml`（用户配置）。