specops 0.2.5 → 0.3.2

package/.opencode/workflows/execute-plan.md

@@ -0,0 +1,447 @@
+<purpose>
+执行阶段提示（PLAN.md）并创建结果摘要（SUMMARY.md）。
+</purpose>
+
+<required_reading>
+在任何操作之前先读取 STATE.md 以加载项目上下文。
+读取 config.json 了解规划行为设置。
+
+@.opencode/references/git-integration.md
+</required_reading>
+
+<process>
+
+<step name="init_context" priority="first">
+加载执行上下文（仅传路径以最小化编排器上下文）：
+
+```bash
+INIT=$(node .opencode/bin/specops-tools.cjs init execute-phase "${PHASE}")
+```
+
+从 init JSON 中提取：`executor_model`、`commit_docs`、`phase_dir`、`phase_number`、`plans`、`summaries`、`incomplete_plans`、`state_path`、`config_path`。
+
+如果 `.planning/` 缺失：报错。
+</step>
+
+<step name="identify_plan">
+```bash
+# Use plans/summaries from INIT JSON, or list files
+ls .planning/phases/XX-name/*-PLAN.md 2>/dev/null | sort
+ls .planning/phases/XX-name/*-SUMMARY.md 2>/dev/null | sort
+```
+
+找到第一个没有对应 SUMMARY 的 PLAN。支持小数阶段（`01.1-hotfix/`）：
+
+```bash
+PHASE=$(echo "$PLAN_PATH" | grep -oE '[0-9]+(\.[0-9]+)?-[0-9]+')
+# config settings can be fetched via specops-tools config-get if needed
+```
+
+<if mode="yolo">
+自动批准：`⚡ Execute {phase}-{plan}-PLAN.md [Plan X of Y for Phase Z]` → parse_segments。
+</if>
+
+<if mode="interactive" OR="custom with gates.execute_next_plan true">
+展示计划识别结果，等待确认。
+</if>
+</step>
+
+<step name="record_start_time">
+```bash
+PLAN_START_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+PLAN_START_EPOCH=$(date +%s)
+```
+</step>
+
+<step name="parse_segments">
+```bash
+grep -n "type=\"checkpoint" .planning/phases/XX-name/{phase}-{plan}-PLAN.md
+```
+
+**按检查点类型路由：**
+
+| 检查点 | 模式 | 执行方式 |
+|--------|------|----------|
+| 无 | A（自主） | 单个子代理：完整计划 + SUMMARY + 提交 |
+| 仅验证类 | B（分段） | 检查点之间的分段。无/human-verify 后 → 子代理。decision/human-action 后 → 主进程 |
+| 决策类 | C（主进程） | 完全在主进程上下文中执行 |
+
+**模式 A：** init_agent_tracking → 生成 Task(subagent_type="specops-executor", model=executor_model)，提示包含：在 [path] 执行计划，自主模式，所有任务 + SUMMARY + 提交，遵循偏差/认证规则，报告：计划名称、任务、SUMMARY 路径、提交哈希 → 跟踪 agent_id → 等待 → 更新跟踪 → 报告。
+
+**模式 B：** 逐段执行。自主段：为指定任务生成子代理（不含 SUMMARY/提交）。检查点：主进程上下文。所有段完成后：聚合、创建 SUMMARY、提交。参见 segment_execution。
+
+**模式 C：** 使用标准流程在主进程中执行（step name="execute"）。
+
+每个子代理的新鲜上下文保持最高质量。主进程上下文保持精简。
+</step>
+
+<step name="init_agent_tracking">
+```bash
+if [ ! -f .planning/agent-history.json ]; then
+  echo '{"version":"1.0","max_entries":50,"entries":[]}' > .planning/agent-history.json
+fi
+rm -f .planning/current-agent-id.txt
+if [ -f .planning/current-agent-id.txt ]; then
+  INTERRUPTED_ID=$(cat .planning/current-agent-id.txt)
+  echo "Found interrupted agent: $INTERRUPTED_ID"
+fi
+```
+
+如果中断：询问用户是恢复（Task `resume` 参数）还是重新开始。
+
+**跟踪协议：** 生成时：将 agent_id 写入 `current-agent-id.txt`，追加到 agent-history.json：`{"agent_id":"[id]","task_description":"[desc]","phase":"[phase]","plan":"[plan]","segment":[num|null],"timestamp":"[ISO]","status":"spawned","completion_timestamp":null}`。完成时：status → "completed"，设置 completion_timestamp，删除 current-agent-id.txt。清理：如果 entries > max_entries，移除最旧的 "completed"（绝不移除 "spawned"）。
+
+模式 A/B 在生成前运行。模式 C：跳过。
+</step>
+
+<step name="segment_execution">
+仅模式 B（仅验证类检查点）。模式 A/C 跳过。
+
+1. 解析分段映射：检查点位置和类型
+2. 每个分段：
+   - 子代理路由：为指定任务生成 specops-executor。提示：任务范围、计划路径、读取完整计划获取上下文、执行指定任务、跟踪偏差、不含 SUMMARY/提交。通过代理协议跟踪。
+   - 主进程路由：使用标准流程执行任务（step name="execute"）
+3. 所有分段完成后：聚合文件/偏差/决策 → 创建 SUMMARY.md → 提交 → 自检：
+   - 用 `[ -f ]` 验证 key-files.created 在磁盘上存在
+   - 检查 `git log --oneline --all --grep="{phase}-{plan}"` 返回 ≥1 个提交
+   - 在 SUMMARY 末尾追加 `## Self-Check: PASSED` 或 `## Self-Check: FAILED`
+
+   **已知 Claude Code bug（classifyHandoffIfNeeded）：** 如果任何段代理报告「失败」且包含 `classifyHandoffIfNeeded is not defined`，这是 Claude Code 运行时 bug——不是真正的失败。运行抽查；如果通过，视为成功。
+
+
+
+</step>
+
+<step name="load_prompt">
+```bash
+cat .planning/phases/XX-name/{phase}-{plan}-PLAN.md
+```
+这就是执行指令。严格按照执行。如果计划引用了 CONTEXT.md：在整个过程中尊重用户的愿景。
+
+**如果计划包含 `<interfaces>` 块：** 这些是预提取的类型定义和合约。直接使用它们——不要重新读取源文件来发现类型。规划器已经提取了你需要的内容。
+</step>
+
+<step name="previous_phase_check">
+```bash
+node .opencode/bin/specops-tools.cjs phases list --type summaries --raw
+# Extract the second-to-last summary from the JSON result
+```
+如果前一个 SUMMARY 有未解决的「遇到的问题」或「下一阶段就绪性」阻塞项：AskUserQuestion(header="Previous Issues", options: "Proceed anyway" | "Address first" | "Review previous")。
+</step>
+
+<step name="execute">
+偏差是正常的——按下面的规则处理。
+
+1. 从提示读取 @context 文件
+2. 每个任务：
+   - `type="auto"`：如果 `tdd="true"` → TDD 执行。使用偏差规则 + 认证门控实现。验证完成标准。提交（参见 task_commit）。记录哈希到 Summary。
+   - `type="checkpoint:*"`：停止 → checkpoint_protocol → 等待用户 → 确认后才继续。
+3. 运行 `<verification>` 检查
+4. 确认 `<success_criteria>` 已满足
+5. 在 Summary 中记录偏差
+</step>
+
+<authentication_gates>
+
+## 认证门控
+
+执行过程中的认证错误不是失败——它们是预期的交互点。
+
+**标识符：** "Not authenticated"、"Unauthorized"、401/403、"Please run {tool} login"、"Set {ENV_VAR}"
+
+**协议：**
+1. 识别认证门控（不是 bug）
+2. 停止任务执行
+3. 创建动态 checkpoint:human-action，包含确切的认证步骤
+4. 等待用户完成认证
+5. 验证凭据有效
+6. 重试原始任务
+7. 正常继续
+
+**示例：** `vercel --yes` → "Not authenticated" → 检查点要求用户 `vercel login` → 用 `vercel whoami` 验证 → 重试部署 → 继续
+
+**在 Summary 中：** 记录为正常流程，放在「## Authentication Gates」下，不记为偏差。
+
+</authentication_gates>
+
+<deviation_rules>
+
+## 偏差规则
+
+你会发现计划外的工作。自动应用，全部记录到 Summary。
+
+| 规则 | 触发条件 | 操作 | 权限 |
+|------|----------|------|------|
+| **1：Bug** | 行为异常、错误、查询错误、类型错误、安全漏洞、竞态条件、泄漏 | 修复 → 测试 → 验证 → 记录 `[Rule 1 - Bug]` | 自动 |
+| **2：缺失关键项** | 缺少必要项：错误处理、验证、认证、CSRF/CORS、限流、索引、日志 | 添加 → 测试 → 验证 → 记录 `[Rule 2 - Missing Critical]` | 自动 |
+| **3：阻塞项** | 阻止完成：缺少依赖、类型错误、导入失败、缺少环境变量/配置/文件、循环依赖 | 修复阻塞 → 验证可继续 → 记录 `[Rule 3 - Blocking]` | 自动 |
+| **4：架构变更** | 结构性变更：新数据库表、schema 变更、新服务、切换库、破坏性 API、新基础设施 | 停止 → 展示决策（如下）→ 记录 `[Rule 4 - Architectural]` | 询问用户 |
+
+**规则 4 格式：**
+```
+⚠️ Architectural Decision Needed
+
+Current task: [task name]
+Discovery: [what prompted this]
+Proposed change: [modification]
+Why needed: [rationale]
+Impact: [what this affects]
+Alternatives: [other approaches]
+
+Proceed with proposed change? (yes / different approach / defer)
+```
+
+**优先级：** 规则 4（停止）> 规则 1-3（自动）> 不确定 → 规则 4
+**边界情况：** 缺少验证 → R2 | 空引用崩溃 → R1 | 新表 → R4 | 新列 → R1/2
+**启发式：** 影响正确性/安全性/完成度？→ R1-3。可能？→ R4。
+
+</deviation_rules>
+
+<deviation_documentation>
+
+## 记录偏差
+
+Summary 必须包含偏差部分。没有偏差？→ `## Deviations from Plan\n\nNone - plan executed exactly as written.`
+
+每个偏差：**[Rule N - Category] Title** — 发现于：任务 X | 问题 | 修复 | 修改的文件 | 验证 | 提交哈希
+
+结尾：**偏差总计：** N 个自动修复（细分）。**影响：** 评估。
+
+</deviation_documentation>
+
+<tdd_plan_execution>
+## TDD 执行
+
+对于 `type: tdd` 计划——红-绿-重构：
+
+1. **基础设施**（仅第一个 TDD 计划）：检测项目、安装框架、配置、验证空测试套件
+2. **红：** 读取 `<behavior>` → 失败测试 → 运行（必须失败）→ 提交：`test({phase}-{plan}): add failing test for [feature]`
+3. **绿：** 读取 `<implementation>` → 最少代码 → 运行（必须通过）→ 提交：`feat({phase}-{plan}): implement [feature]`
+4. **重构：** 清理 → 测试必须通过 → 提交：`refactor({phase}-{plan}): clean up [feature]`
+
+错误处理：红阶段不失败 → 调查测试/已有功能。绿阶段不通过 → 调试、迭代。重构导致失败 → 撤销。
+
+详见 `.opencode/references/tdd.md`。
+</tdd_plan_execution>
+
+<task_commit>
+## 任务提交协议
+
+每个任务完成后（验证通过、完成标准满足），立即提交。
+
+**1. 检查：** `git status --short`
+
+**2. 逐个暂存**（绝不使用 `git add .` 或 `git add -A`）：
+```bash
+git add src/api/auth.ts
+git add src/types/user.ts
+```
+
+**3. 提交类型：**
+
+| 类型 | 使用场景 | 示例 |
+|------|----------|------|
+| `feat` | 新功能 | feat(08-02): create user registration endpoint |
+| `fix` | Bug 修复 | fix(08-02): correct email validation regex |
+| `test` | 仅测试（TDD 红阶段） | test(08-02): add failing test for password hashing |
+| `refactor` | 无行为变更（TDD 重构阶段） | refactor(08-02): extract validation to helper |
+| `perf` | 性能优化 | perf(08-02): add database index |
+| `docs` | 文档 | docs(08-02): add API docs |
+| `style` | 格式化 | style(08-02): format auth module |
+| `chore` | 配置/依赖 | chore(08-02): add bcrypt dependency |
+
+**4. 格式：** `{type}({phase}-{plan}): {description}`，用要点列出关键变更。
+
+**5. 记录哈希：**
+```bash
+TASK_COMMIT=$(git rev-parse --short HEAD)
+TASK_COMMITS+=("Task ${TASK_NUM}: ${TASK_COMMIT}")
+```
+
+</task_commit>
+
+<step name="checkpoint_protocol">
+遇到 `type="checkpoint:*"` 时：先自动化一切可自动化的。检查点仅用于验证/决策。
+
+显示：`CHECKPOINT: [Type]` 框 → 进度 {X}/{Y} → 任务名称 → 类型相关内容 → `YOUR ACTION: [signal]`
+
+| 类型 | 内容 | 恢复信号 |
+|------|------|----------|
+| human-verify（90%） | 构建了什么 + 验证步骤（命令/URL） | "approved" 或描述问题 |
+| decision（9%） | 需要的决策 + 上下文 + 含优劣的选项 | "Select: option-id" |
+| human-action（1%） | 已自动化的内容 + 一个手动步骤 + 验证计划 | "done" |
+
+响应后：如指定则验证。通过 → 继续。失败 → 告知，等待。等待用户——不要虚构完成。
+
+详见 .opencode/references/checkpoints.md。
+</step>
+
+<step name="checkpoint_return_for_orchestrator">
+通过 Task 生成且遇到检查点时：返回结构化状态（无法直接与用户交互）。
+
+**必需返回：** 1）已完成任务表（哈希 + 文件） 2）当前任务（什么在阻塞） 3）检查点详情（面向用户的内容） 4）等待内容（需要用户提供什么）
+
+编排器解析 → 向用户展示 → 用你的已完成任务状态生成新的延续代理。你不会被恢复。在主进程上下文中：使用上面的 checkpoint_protocol。
+</step>
+
+<step name="verification_failure_gate">
+如果验证失败：停止。展示："任务 [X] 验证失败：[name]。预期：[criteria]。实际：[result]。" 选项：重试 | 跳过（标记为未完成）| 停止（调查）。如果跳过 → SUMMARY「遇到的问题」。
+</step>
+
+<step name="record_completion_time">
+```bash
+PLAN_END_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+PLAN_END_EPOCH=$(date +%s)
+
+DURATION_SEC=$(( PLAN_END_EPOCH - PLAN_START_EPOCH ))
+DURATION_MIN=$(( DURATION_SEC / 60 ))
+
+if [[ $DURATION_MIN -ge 60 ]]; then
+  HRS=$(( DURATION_MIN / 60 ))
+  MIN=$(( DURATION_MIN % 60 ))
+  DURATION="${HRS}h ${MIN}m"
+else
+  DURATION="${DURATION_MIN} min"
+fi
+```
+</step>
+
+<step name="generate_user_setup">
+```bash
+grep -A 50 "^user_setup:" .planning/phases/XX-name/{phase}-{plan}-PLAN.md | head -50
+```
+
+如果 user_setup 存在：使用模板 `.opencode/templates/user-setup.md` 创建 `{phase}-USER-SETUP.md`。每个服务包含：环境变量表、账户设置清单、仪表盘配置、本地开发说明、验证命令。状态为「Incomplete」。设置 `USER_SETUP_CREATED=true`。如果为空/缺失：跳过。
+</step>
+
+<step name="create_summary">
+在 `.planning/phases/XX-name/` 创建 `{phase}-{plan}-SUMMARY.md`。使用 `.opencode/templates/summary.md`。
+
+**Frontmatter：** phase、plan、subsystem、tags | requires/provides/affects | tech-stack.added/patterns | key-files.created/modified | key-decisions | requirements-completed（**必须**原样复制 PLAN.md frontmatter 中的 `requirements` 数组）| duration ($DURATION)、completed ($PLAN_END_TIME date)。
+
+标题：`# Phase [X] Plan [Y]: [Name] Summary`
+
+一句话摘要要实质性：「使用 jose 库的 JWT 认证，含刷新令牌轮换」而不是「认证已实现」
+
+包含：时长、开始/结束时间、任务数、文件数。
+
+下一步：还有更多计划 → 「准备好执行 {next-plan}」| 最后一个 → 「阶段完成，准备转换」。
+</step>
+
+<step name="update_current_position">
+使用 specops-tools 更新 STATE.md：
+
+```bash
+# Advance plan counter (handles last-plan edge case)
+node .opencode/bin/specops-tools.cjs state advance-plan
+
+# Recalculate progress bar from disk state
+node .opencode/bin/specops-tools.cjs state update-progress
+
+# Record execution metrics
+node .opencode/bin/specops-tools.cjs state record-metric \
+  --phase "${PHASE}" --plan "${PLAN}" --duration "${DURATION}" \
+  --tasks "${TASK_COUNT}" --files "${FILE_COUNT}"
+```
+</step>
+
+<step name="extract_decisions_and_issues">
+从 SUMMARY 提取决策并添加到 STATE.md：
+
+```bash
+# Add each decision from SUMMARY key-decisions
+# Prefer file inputs for shell-safe text (preserves `$`, `*`, etc. exactly)
+node .opencode/bin/specops-tools.cjs state add-decision \
+  --phase "${PHASE}" --summary-file "${DECISION_TEXT_FILE}" --rationale-file "${RATIONALE_FILE}"
+
+# Add blockers if any found
+node .opencode/bin/specops-tools.cjs state add-blocker --text-file "${BLOCKER_TEXT_FILE}"
+```
+</step>
+
+<step name="update_session_continuity">
+使用 specops-tools 更新会话信息：
+
+```bash
+node .opencode/bin/specops-tools.cjs state record-session \
+  --stopped-at "Completed ${PHASE}-${PLAN}-PLAN.md" \
+  --resume-file "None"
+```
+
+保持 STATE.md 在 150 行以内。
+</step>
+
+<step name="issues_review_gate">
+如果 SUMMARY「遇到的问题」≠ "None"：yolo → 记录并继续。Interactive → 展示问题，等待确认。
+</step>
+
+<step name="update_roadmap">
+```bash
+node .opencode/bin/specops-tools.cjs roadmap update-plan-progress "${PHASE}"
+```
+统计磁盘上的 PLAN 和 SUMMARY 文件数。更新进度表行，含正确的计数和状态（`In Progress` 或 `Complete` 加日期）。
+</step>
+
+<step name="update_requirements">
+从 PLAN.md frontmatter 的 `requirements:` 字段标记已完成的需求：
+
+```bash
+node .opencode/bin/specops-tools.cjs requirements mark-complete ${REQ_IDS}
+```
+
+从计划的 frontmatter 提取需求 ID（如 `requirements: [AUTH-01, AUTH-02]`）。如果没有 requirements 字段，跳过。
+</step>
+
+<step name="git_commit_metadata">
+任务代码已按任务提交。提交计划元数据：
+
+```bash
+node .opencode/bin/specops-tools.cjs commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md .planning/REQUIREMENTS.md
+```
+</step>
+
+<step name="update_codebase_map">
+如果 .planning/codebase/ 不存在：跳过。
+
+```bash
+FIRST_TASK=$(git log --oneline --grep="feat({phase}-{plan}):" --grep="fix({phase}-{plan}):" --grep="test({phase}-{plan}):" --reverse | head -1 | cut -d' ' -f1)
+git diff --name-only ${FIRST_TASK}^..HEAD 2>/dev/null
+```
+
+仅更新结构性变更：新 src/ 目录 → STRUCTURE.md | 依赖 → STACK.md | 文件模式 → CONVENTIONS.md | API 客户端 → INTEGRATIONS.md | 配置 → STACK.md | 重命名 → 更新路径。跳过纯代码/bugfix/内容变更。
+
+```bash
+node .opencode/bin/specops-tools.cjs commit "" --files .planning/codebase/*.md --amend
+```
+</step>
+
+<step name="offer_next">
+如果 `USER_SETUP_CREATED=true`：在顶部显示 `⚠️ USER SETUP REQUIRED`，含路径 + 环境变量/配置任务。
+
+```bash
+ls -1 .planning/phases/[current-phase-dir]/*-PLAN.md 2>/dev/null | wc -l
+ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null | wc -l
+```
+
+| 条件 | 路由 | 操作 |
+|------|------|------|
+| summaries < plans | **A：更多计划** | 找到下一个没有 SUMMARY 的 PLAN。Yolo：自动继续。Interactive：显示下一个计划，建议 `/specops:execute-phase {phase}` + `/specops:verify-work`。到此停止。 |
+| summaries = plans，当前 < 最高阶段 | **B：阶段完成** | 显示完成信息，建议 `/specops:plan-phase {Z+1}` + `/specops:verify-work {Z}` + `/specops:discuss-phase {Z+1}` |
+| summaries = plans，当前 = 最高阶段 | **C：里程碑完成** | 显示横幅，建议 `/specops:complete-milestone` + `/specops:verify-work` + `/specops:add-phase` |
+
+所有路由：先 `/clear` 获取全新上下文。
+</step>
+
+</process>
+
+<success_criteria>
+
+- 所有 PLAN.md 中的任务已完成
+- 所有验证通过
+- 如果 frontmatter 中有 user_setup 则已生成 USER-SETUP.md
+- 已创建含实质性内容的 SUMMARY.md
+- STATE.md 已更新（位置、决策、问题、会话）
+- ROADMAP.md 已更新
+- 如果代码库映射存在：映射已随执行变更更新（或无重大变更时跳过）
+- 如果创建了 USER-SETUP.md：在完成输出中醒目展示
+</success_criteria>

package/.opencode/workflows/health.md

@@ -0,0 +1,156 @@
+<purpose>
+验证 `.planning/` 目录的完整性并报告可操作的问题。检查缺失文件、无效配置、不一致状态和孤立计划。可选择自动修复可修复的问题。
+</purpose>
+
+<required_reading>
+在开始之前，阅读调用提示的 execution_context 中引用的所有文件。
+</required_reading>
+
+<process>
+
+<step name="parse_args">
+**解析参数：**
+
+检查命令参数中是否包含 `--repair` 标志。
+
+```
+REPAIR_FLAG=""
+if arguments contain "--repair"; then
+  REPAIR_FLAG="--repair"
+fi
+```
+</step>
+
+<step name="run_health_check">
+**运行健康检查：**
+
+```bash
+node .opencode/bin/specops-tools.cjs validate health $REPAIR_FLAG
+```
+
+解析 JSON 输出：
+- `status`："healthy" | "degraded" | "broken"
+- `errors[]`：严重问题（code、message、fix、repairable）
+- `warnings[]`：非严重问题
+- `info[]`：信息性备注
+- `repairable_count`：可自动修复的问题数量
+- `repairs_performed[]`：使用 --repair 时执行的操作
+</step>
+
+<step name="format_output">
+**格式化并显示结果：**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SpecOps Health Check
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Status: HEALTHY | DEGRADED | BROKEN
+Errors: N | Warnings: N | Info: N
+```
+
+**如果执行了修复：**
+```
+## Repairs Performed
+
+- ✓ config.json: Created with defaults
+- ✓ STATE.md: Regenerated from roadmap
+```
+
+**如果存在错误：**
+```
+## Errors
+
+- [E001] config.json: JSON parse error at line 5
+  Fix: Run /specops:health --repair to reset to defaults
+
+- [E002] PROJECT.md not found
+  Fix: Run /specops:new-project to create
+```
+
+**如果存在警告：**
+```
+## Warnings
+
+- [W001] STATE.md references phase 5, but only phases 1-3 exist
+  Fix: Run /specops:health --repair to regenerate
+
+- [W005] Phase directory "1-setup" doesn't follow NN-name format
+  Fix: Rename to match pattern (e.g., 01-setup)
+```
+
+**如果存在信息：**
+```
+## Info
+
+- [I001] 02-implementation/02-01-PLAN.md has no SUMMARY.md
+  Note: May be in progress
+```
+
+**页脚（如果存在可修复问题且未使用 --repair）：**
+```
+---
+N issues can be auto-repaired. Run: /specops:health --repair
+```
+</step>
+
+<step name="offer_repair">
+**如果存在可修复问题且未使用 --repair：**
+
+询问用户是否要运行修复：
+
+```
+Would you like to run /specops:health --repair to fix N issues automatically?
+```
+
+如果是，使用 --repair 标志重新运行并显示结果。
+</step>
+
+<step name="verify_repairs">
+**如果执行了修复：**
+
+不带 --repair 重新运行健康检查以确认问题已解决：
+
+```bash
+node .opencode/bin/specops-tools.cjs validate health
+```
+
+报告最终状态。
+</step>
+
+</process>
+
+<error_codes>
+
+| Code | Severity | Description | Repairable |
+|------|----------|-------------|------------|
+| E001 | error | 未找到 .planning/ 目录 | No |
+| E002 | error | 未找到 PROJECT.md | No |
+| E003 | error | 未找到 ROADMAP.md | No |
+| E004 | error | 未找到 STATE.md | Yes |
+| E005 | error | config.json 解析错误 | Yes |
+| W001 | warning | PROJECT.md 缺少必需部分 | No |
+| W002 | warning | STATE.md 引用了无效阶段 | Yes |
+| W003 | warning | 未找到 config.json | Yes |
+| W004 | warning | config.json 字段值无效 | No |
+| W005 | warning | 阶段目录命名不匹配 | No |
+| W006 | warning | ROADMAP 中有阶段但无目录 | No |
+| W007 | warning | 磁盘上有阶段但不在 ROADMAP 中 | No |
+| I001 | info | 计划无 SUMMARY（可能正在进行中） | No |
+
+</error_codes>
+
+<repair_actions>
+
+| Action | Effect | Risk |
+|--------|--------|------|
+| createConfig | 使用默认值创建 config.json | 无 |
+| resetConfig | 删除并重新创建 config.json | 丢失自定义设置 |
+| regenerateState | 从 ROADMAP 结构创建 STATE.md | 丢失会话历史 |
+
+**不可修复（风险太高）：**
+- PROJECT.md、ROADMAP.md 内容
+- 阶段目录重命名
+- 孤立计划清理
+
+</repair_actions>