specops 0.2.4 → 0.3.0

package/.opencode/workflows/update.md

@@ -0,0 +1,219 @@
+<purpose>
+通过 npm 检查 SpecOps 更新，显示已安装版本和最新版本之间的变更日志，获取用户确认，并执行清除缓存的全新安装。
+</purpose>
+
+<required_reading>
+在开始之前，阅读调用提示的 execution_context 中引用的所有文件。
+</required_reading>
+
+<process>
+
+<step name="get_installed_version">
+通过检查本地和全局两个位置来检测 SpecOps 的安装方式，并验证安装完整性：
+
+```bash
+# 优先检查本地（仅在有效时优先）
+# 路径在安装时模板化以确保运行时兼容性
+LOCAL_VERSION_FILE="./.claude/specops/VERSION"
+LOCAL_MARKER_FILE="./.claude/specops/workflows/update.md"
+GLOBAL_VERSION_FILE="$HOME/.claude/specops/VERSION"
+GLOBAL_MARKER_FILE="$HOME/.claude/specops/workflows/update.md"
+
+if [ -f "$LOCAL_VERSION_FILE" ] && [ -f "$LOCAL_MARKER_FILE" ] && grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+' "$LOCAL_VERSION_FILE"; then
+  cat "$LOCAL_VERSION_FILE"
+  echo "LOCAL"
+elif [ -f "$GLOBAL_VERSION_FILE" ] && [ -f "$GLOBAL_MARKER_FILE" ] && grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+' "$GLOBAL_VERSION_FILE"; then
+  cat "$GLOBAL_VERSION_FILE"
+  echo "GLOBAL"
+else
+  echo "UNKNOWN"
+fi
+```
+
+解析输出：
+- 如果最后一行是"LOCAL"：本地安装有效；已安装版本为第一行；使用 `--local`
+- 如果最后一行是"GLOBAL"：本地缺失/无效，全局安装有效；已安装版本为第一行；使用 `--global`
+- 如果是"UNKNOWN"：继续到安装步骤（视为版本 0.0.0）
+
+**如果 VERSION 文件缺失：**
+```
+## SpecOps 更新
+
+**已安装版本：** 未知
+
+你的安装不包含版本追踪。
+
+正在执行全新安装……
+```
+
+继续到安装步骤（比较时视为版本 0.0.0）。
+</step>
+
+<step name="check_latest_version">
+从 npm 检查最新版本：
+
+```bash
+npm view specops-cc version 2>/dev/null
+```
+
+**如果 npm 检查失败：**
+```
+无法检查更新（离线或 npm 不可用）。
+
+手动更新：`npx specops-cc --global`
+```
+
+退出。
+</step>
+
+<step name="compare_versions">
+比较已安装版本和最新版本：
+
+**如果已安装 == 最新：**
+```
+## SpecOps 更新
+
+**已安装：** X.Y.Z
+**最新：** X.Y.Z
+
+你已经是最新版本。
+```
+
+退出。
+
+**如果已安装 > 最新：**
+```
+## SpecOps 更新
+
+**已安装：** X.Y.Z
+**最新：** A.B.C
+
+你的版本超前于最新发布版（开发版本？）。
+```
+
+退出。
+</step>
+
+<step name="show_changes_and_confirm">
+**如果有可用更新**，在更新前获取并显示新内容：
+
+1. 从 GitHub raw URL 获取变更日志
+2. 提取已安装版本和最新版本之间的条目
+3. 显示预览并请求确认：
+
+```
+## SpecOps 有可用更新
+
+**已安装：** 1.5.10
+**最新：** 1.5.15
+
+### 更新内容
+────────────────────────────────────────────────────────────
+
+## [1.5.15] - 2026-01-20
+
+### 新增
+- 功能 X
+
+## [1.5.14] - 2026-01-18
+
+### 修复
+- Bug 修复 Y
+
+────────────────────────────────────────────────────────────
+
+⚠️  **注意：** 安装程序将对 SpecOps 文件夹执行全新安装：
+- `commands/specops/` 将被清除并替换
+- `specops/` 将被清除并替换
+- `agents/specops-*` 文件将被替换
+
+（路径相对于你的安装位置：全局为 `.opencode/`，本地为 `./.claude/`）
+
+你在其他位置的自定义文件将被保留：
+- 不在 `commands/specops/` 中的自定义命令 ✓
+- 不以 `specops-` 为前缀的自定义 Agent ✓
+- 自定义钩子 ✓
+- 你的 CLAUDE.md 文件 ✓
+
+如果你直接修改了任何 SpecOps 文件，它们将被自动备份到 `specops-local-patches/`，更新后可以使用 `/specops:reapply-patches` 重新应用。
+```
+
+使用 AskUserQuestion：
+- 问题："是否继续更新？"
+- 选项：
+  - "是，立即更新"
+  - "否，取消"
+
+**如果用户取消：** 退出。
+</step>
+
+<step name="run_update">
+使用步骤 1 中检测到的安装类型运行更新：
+
+**如果是本地安装：**
+```bash
+npx -y specops-cc@latest --local
+```
+
+**如果是全局安装（或未知）：**
+```bash
+npx -y specops-cc@latest --global
+```
+
+捕获输出。如果安装失败，显示错误并退出。
+
+清除更新缓存，使状态栏指示器消失：
+
+**如果是本地安装：**
+```bash
+rm -f ./.claude/cache/specops-update-check.json
+```
+
+**如果是全局安装：**
+```bash
+rm -f .opencode/cache/specops-update-check.json
+```
+（路径在安装时模板化以确保运行时兼容性）
+</step>
+
+<step name="display_result">
+格式化完成消息（变更日志已在确认步骤中显示）：
+
+```
+╔═══════════════════════════════════════════════════════════╗
+║  SpecOps 已更新：v1.5.10 → v1.5.15                       ║
+╚═══════════════════════════════════════════════════════════╝
+
+⚠️  请重启 Claude Code 以加载新命令。
+
+[查看完整变更日志](https://github.com/glittercowboy/specops/blob/main/CHANGELOG.md)
+```
+</step>
+
+
+<step name="check_local_patches">
+更新完成后，检查安装程序是否检测到并备份了本地修改的文件：
+
+检查配置目录中的 specops-local-patches/backup-meta.json。
+
+**如果发现补丁：**
+
+```
+更新前已备份本地补丁。
+运行 /specops:reapply-patches 将你的修改合并到新版本中。
+```
+
+**如果没有补丁：** 正常继续。
+</step>
+</process>
+
+<success_criteria>
+- [ ] 已正确读取已安装版本
+- [ ] 已通过 npm 检查最新版本
+- [ ] 如果已是最新则跳过更新
+- [ ] 在更新前获取并显示了变更日志
+- [ ] 显示了全新安装警告
+- [ ] 已获取用户确认
+- [ ] 更新执行成功
+- [ ] 显示了重启提醒
+</success_criteria>

package/.opencode/workflows/verify-phase.md

@@ -0,0 +1,242 @@
+<purpose>
+通过目标反推分析验证阶段目标的达成情况。检查代码库是否交付了阶段承诺的内容，而不仅仅是任务是否完成。
+
+由 execute-phase.md 生成的验证子 Agent 执行。
+</purpose>
+
+<core_principle>
+**任务完成 ≠ 目标达成**
+
+一个"创建聊天组件"的任务可以在组件只是占位符时就标记为完成。任务完成了——但"可用的聊天界面"这个目标并未达成。
+
+目标反推验证：
+1. 目标达成需要哪些事实为真？
+2. 这些事实成立需要哪些产物存在？
+3. 这些产物正常运作需要哪些连接就位？
+
+然后逐层对照实际代码库进行验证。
+</core_principle>
+
+<required_reading>
+@.opencode/references/verification-patterns.md
+@.opencode/templates/verification-report.md
+</required_reading>
+
+<process>
+
+<step name="load_context" priority="first">
+加载阶段操作上下文：
+
+```bash
+INIT=$(node .opencode/bin/specops-tools.cjs init phase-op "${PHASE_ARG}")
+```
+
+从初始化 JSON 中提取：`phase_dir`、`phase_number`、`phase_name`、`has_plans`、`plan_count`。
+
+然后加载阶段详情并列出计划/摘要：
+```bash
+node .opencode/bin/specops-tools.cjs roadmap get-phase "${phase_number}"
+grep -E "^| ${phase_number}" .planning/REQUIREMENTS.md 2>/dev/null
+ls "$phase_dir"/*-SUMMARY.md "$phase_dir"/*-PLAN.md 2>/dev/null
+```
+
+从 ROADMAP.md 提取**阶段目标**（要验证的成果，而非任务），以及从 REQUIREMENTS.md 提取**需求**（如果存在）。
+</step>
+
+<step name="establish_must_haves">
+**方案 A：PLAN frontmatter 中的必要项**
+
+使用 specops-tools 从每个 PLAN 中提取 must_haves：
+
+```bash
+for plan in "$PHASE_DIR"/*-PLAN.md; do
+  MUST_HAVES=$(node .opencode/bin/specops-tools.cjs frontmatter get "$plan" --field must_haves)
+  echo "=== $plan ===" && echo "$MUST_HAVES"
+done
+```
+
+返回 JSON：`{ truths: [...], artifacts: [...], key_links: [...] }`
+
+汇总所有计划的 must_haves 用于阶段级验证。
+
+**方案 B：使用 ROADMAP.md 中的成功标准**
+
+如果 frontmatter 中没有 must_haves（MUST_HAVES 返回错误或为空），检查成功标准：
+
+```bash
+PHASE_DATA=$(node .opencode/bin/specops-tools.cjs roadmap get-phase "${phase_number}" --raw)
+```
+
+从 JSON 输出中解析 `success_criteria` 数组。如果非空：
+1. 将每个成功标准直接用作**事实**（它们已经写成可观察、可测试的行为）
+2. 推导**产物**（每个事实对应的具体文件路径）
+3. 推导**关键连接**（桩代码容易隐藏的关键接线）
+4. 在继续之前记录必要项
+
+ROADMAP.md 中的成功标准是契约——当两者都存在时，它们优先于 PLAN 级别的 must_haves。
+
+**方案 C：从阶段目标推导（兜底方案）**
+
+如果 frontmatter 中没有 must_haves 且 ROADMAP 中没有成功标准：
+1. 陈述 ROADMAP.md 中的目标
+2. 推导**事实**（3-7 个可观察行为，每个可测试）
+3. 推导**产物**（每个事实对应的具体文件路径）
+4. 推导**关键连接**（桩代码容易隐藏的关键接线）
+5. 在继续之前记录推导出的必要项
+</step>
+
+<step name="verify_truths">
+对于每个可观察事实，判断代码库是否支持它。
+
+**状态：** ✓ 已验证（所有支撑产物通过）| ✗ 失败（产物缺失/桩代码/未连接）| ? 不确定（需要人工）
+
+对于每个事实：识别支撑产物 → 检查产物状态 → 检查连接 → 确定事实状态。
+
+**示例：** 事实"用户可以看到已有消息"依赖于 Chat.tsx（渲染）、/api/chat GET（提供数据）、Message 模型（schema）。如果 Chat.tsx 是桩代码或 API 返回硬编码的 [] → 失败。如果全部存在、有实质内容且已连接 → 已验证。
+</step>
+
+<step name="verify_artifacts">
+使用 specops-tools 对每个 PLAN 中的 must_haves 进行产物验证：
+
+```bash
+for plan in "$PHASE_DIR"/*-PLAN.md; do
+  ARTIFACT_RESULT=$(node .opencode/bin/specops-tools.cjs verify artifacts "$plan")
+  echo "=== $plan ===" && echo "$ARTIFACT_RESULT"
+done
+```
+
+解析 JSON 结果：`{ all_passed, passed, total, artifacts: [{path, exists, issues, passed}] }`
+
+**从结果判断产物状态：**
+- `exists=false` → 缺失
+- `issues` 非空 → 桩代码（检查 issues 中的"Only N lines"或"Missing pattern"）
+- `passed=true` → 已验证（第 1-2 级通过）
+
+**第 3 级 — 已连接（对通过第 1-2 级的产物进行手动检查）：**
+```bash
+grep -r "import.*$artifact_name" src/ --include="*.ts" --include="*.tsx"  # 已导入
+grep -r "$artifact_name" src/ --include="*.ts" --include="*.tsx" | grep -v "import"  # 已使用
+```
+已连接 = 已导入且已使用。孤立 = 存在但未导入/使用。
+
+| 存在 | 有实质内容 | 已连接 | 状态 |
+|------|-----------|--------|------|
+| ✓ | ✓ | ✓ | ✓ 已验证 |
+| ✓ | ✓ | ✗ | ⚠️ 孤立 |
+| ✓ | ✗ | - | ✗ 桩代码 |
+| ✗ | - | - | ✗ 缺失 |
+</step>
+
+<step name="verify_wiring">
+使用 specops-tools 对每个 PLAN 中的 must_haves 进行关键连接验证：
+
+```bash
+for plan in "$PHASE_DIR"/*-PLAN.md; do
+  LINKS_RESULT=$(node .opencode/bin/specops-tools.cjs verify key-links "$plan")
+  echo "=== $plan ===" && echo "$LINKS_RESULT"
+done
+```
+
+解析 JSON 结果：`{ all_verified, verified, total, links: [{from, to, via, verified, detail}] }`
+
+**从结果判断连接状态：**
+- `verified=true` → 已连接
+- `verified=false` 且 "not found" → 未连接
+- `verified=false` 且 "Pattern not found" → 部分连接
+
+**兜底模式（如果 must_haves 中没有 key_links）：**
+
+| 模式 | 检查 | 状态 |
+|------|------|------|
+| 组件 → API | fetch/axios 调用 API 路径，响应被使用（await/.then/setState） | 已连接 / 部分（调用但未使用响应）/ 未连接 |
+| API → 数据库 | Prisma/DB 查询模型，结果通过 res.json() 返回 | 已连接 / 部分（查询但未返回）/ 未连接 |
+| 表单 → 处理器 | onSubmit 有真实实现（fetch/axios/mutate/dispatch），不是 console.log/空函数 | 已连接 / 桩代码（仅 log/空）/ 未连接 |
+| 状态 → 渲染 | useState 变量出现在 JSX 中（`{stateVar}` 或 `{stateVar.property}`） | 已连接 / 未连接 |
+
+记录每个关键连接的状态和证据。
+</step>
+
+<step name="verify_requirements">
+如果 REQUIREMENTS.md 存在：
+```bash
+grep -E "Phase ${PHASE_NUM}" .planning/REQUIREMENTS.md 2>/dev/null
+```
+
+对于每个需求：解析描述 → 识别支撑事实/产物 → 状态：✓ 已满足 / ✗ 被阻塞 / ? 需要人工。
+</step>
+
+<step name="scan_antipatterns">
+从 SUMMARY.md 提取此阶段修改的文件，扫描每个文件：
+
+| 模式 | 搜索 | 严重程度 |
+|------|------|----------|
+| TODO/FIXME/XXX/HACK | `grep -n -E "TODO\|FIXME\|XXX\|HACK"` | ⚠️ 警告 |
+| 占位符内容 | `grep -n -iE "placeholder\|coming soon\|will be here"` | 🛑 阻塞 |
+| 空返回 | `grep -n -E "return null\|return \{\}\|return \[\]\|=> \{\}"` | ⚠️ 警告 |
+| 仅日志函数 | 只包含 console.log 的函数 | ⚠️ 警告 |
+
+分类：🛑 阻塞（阻碍目标）| ⚠️ 警告（不完整）| ℹ️ 信息（值得注意）。
+</step>
+
+<step name="identify_human_verification">
+**始终需要人工验证：** 视觉外观、用户流程完整性、实时行为（WebSocket/SSE）、外部服务集成、性能体验、错误消息清晰度。
+
+**不确定时需要人工：** grep 无法追踪的复杂连接、依赖动态状态的行为、边界情况。
+
+每项格式为：测试名称 → 操作步骤 → 预期结果 → 为什么无法程序化验证。
+</step>
+
+<step name="determine_status">
+**passed：** 所有事实已验证，所有产物通过第 1-3 级，所有关键连接已连接，无阻塞反模式。
+
+**gaps_found：** 任何事实失败、产物缺失/桩代码、关键连接未连接、或发现阻塞项。
+
+**human_needed：** 所有自动检查通过但仍有需要人工验证的项目。
+
+**评分：** `已验证事实数 / 总事实数`
+</step>
+
+<step name="generate_fix_plans">
+如果 gaps_found：
+
+1. **聚类相关缺口：** API 桩代码 + 组件未连接 → "连接前端到后端"。多个缺失 → "完成核心实现"。仅连接问题 → "连接现有组件"。
+
+2. **为每个聚类生成计划：** 目标、2-3 个任务（每个包含文件/操作/验证）、重新验证步骤。保持聚焦：每个计划单一关注点。
+
+3. **按依赖排序：** 修复缺失 → 修复桩代码 → 修复连接 → 验证。
+</step>
+
+<step name="create_report">
+```bash
+REPORT_PATH="$PHASE_DIR/${PHASE_NUM}-VERIFICATION.md"
+```
+
+填充模板各部分：frontmatter（阶段/时间戳/状态/评分）、目标达成情况、产物表格、连接表格、需求覆盖、反模式、人工验证项、缺口摘要、修复计划（如果 gaps_found）、元数据。
+
+参见 .opencode/templates/verification-report.md 获取完整模板。
+</step>
+
+<step name="return_to_orchestrator">
+返回状态（`passed` | `gaps_found` | `human_needed`）、评分（N/M 必要项）、报告路径。
+
+如果 gaps_found：列出缺口 + 推荐的修复计划名称。
+如果 human_needed：列出需要人工测试的项目。
+
+编排器路由：`passed` → 更新路线图 | `gaps_found` → 创建/执行修复，重新验证 | `human_needed` → 展示给用户。
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] 已建立必要项（来自 frontmatter 或推导）
+- [ ] 所有事实已验证并附带状态和证据
+- [ ] 所有产物已在三个级别全部检查
+- [ ] 所有关键连接已验证
+- [ ] 已评估需求覆盖（如适用）
+- [ ] 已扫描反模式并分类
+- [ ] 已识别需要人工验证的项目
+- [ ] 已确定总体状态
+- [ ] 已生成修复计划（如果 gaps_found）
+- [ ] 已创建包含完整报告的 VERIFICATION.md
+- [ ] 已将结果返回给编排器
+</success_criteria>