specops 0.2.4 → 0.3.0

package/.opencode/workflows/audit-milestone.md

@@ -0,0 +1,297 @@
+<purpose>
+通过汇总阶段验证、检查跨阶段集成和评估需求覆盖率来验证里程碑是否达成其完成定义。读取现有的 VERIFICATION.md 文件（阶段在 execute-phase 期间已验证），汇总技术债务和推迟的缺口，然后生成集成检查器进行跨阶段接线检查。
+</purpose>
+
+<required_reading>
+在开始之前，阅读调用提示的 execution_context 中引用的所有文件。
+</required_reading>
+
+<process>
+
+## 0. 初始化里程碑上下文
+
+```bash
+INIT=$(node .opencode/bin/specops-tools.cjs init milestone-op)
+```
+
+从初始化 JSON 中提取：`milestone_version`、`milestone_name`、`phase_count`、`completed_phases`、`commit_docs`。
+
+解析集成检查器模型：
+```bash
+CHECKER_MODEL=$(node .opencode/bin/specops-tools.cjs resolve-model specops-integration-checker --raw)
+```
+
+## 1. 确定里程碑范围
+
+```bash
+# 获取里程碑中的阶段（按数字排序，处理小数）
+node .opencode/bin/specops-tools.cjs phases list
+```
+
+- 从参数解析版本或从 ROADMAP.md 检测当前版本
+- 识别范围内的所有阶段目录
+- 从 ROADMAP.md 提取里程碑完成定义
+- 从 REQUIREMENTS.md 提取映射到此里程碑的需求
+
+## 2. 读取所有阶段验证
+
+对于每个阶段目录，读取 VERIFICATION.md：
+
+```bash
+# 对于每个阶段，使用 find-phase 解析目录（处理已归档的阶段）
+PHASE_INFO=$(node .opencode/bin/specops-tools.cjs find-phase 01 --raw)
+# 从 JSON 中提取目录，然后从该目录读取 VERIFICATION.md
+# 对 ROADMAP.md 中的每个阶段编号重复此操作
+```
+
+从每个 VERIFICATION.md 中提取：
+- **状态：** passed | gaps_found
+- **关键缺口：**（如有——这些是阻塞项）
+- **非关键缺口：** 技术债务、推迟项、警告
+- **发现的反模式：** TODO、桩代码、占位符
+- **需求覆盖：** 哪些需求已满足/被阻塞
+
+如果某个阶段缺少 VERIFICATION.md，将其标记为"未验证阶段"——这是阻塞项。
+
+## 3. 生成集成检查器
+
+收集阶段上下文后：
+
+从 REQUIREMENTS.md 追溯表中提取 `MILESTONE_REQ_IDS`——分配给此里程碑各阶段的所有 REQ-ID。
+
+```
+Task(
+  prompt="Check cross-phase integration and E2E flows.
+
+Phases: {phase_dirs}
+Phase exports: {from SUMMARYs}
+API routes: {routes created}
+
+Milestone Requirements:
+{MILESTONE_REQ_IDS — list each REQ-ID with description and assigned phase}
+
+MUST map each integration finding to affected requirement IDs where applicable.
+
+Verify cross-phase wiring and E2E user flows.",
+  subagent_type="specops-integration-checker",
+  model="{integration_checker_model}"
+)
+```
+
+## 4. 收集结果
+
+合并：
+- 阶段级缺口和技术债务（来自步骤 2）
+- 集成检查器的报告（接线缺口、中断的流程）
+
+## 5. 检查需求覆盖（3 源交叉引用）
+
+必须对每个需求交叉引用三个独立来源：
+
+### 5a. 解析 REQUIREMENTS.md 追溯表
+
+从追溯表中提取映射到里程碑阶段的所有 REQ-ID：
+- 需求 ID、描述、分配阶段、当前状态、勾选状态（`[x]` vs `[ ]`）
+
+### 5b. 解析阶段 VERIFICATION.md 需求表
+
+对于每个阶段的 VERIFICATION.md，提取展开的需求表：
+- 需求 | 来源计划 | 描述 | 状态 | 证据
+- 将每个条目映射回其 REQ-ID
+
+### 5c. 提取 SUMMARY.md Frontmatter 交叉检查
+
+对于每个阶段的 SUMMARY.md，从 YAML frontmatter 中提取 `requirements-completed`：
+```bash
+for summary in .planning/phases/*-*/*-SUMMARY.md; do
+  node .opencode/bin/specops-tools.cjs summary-extract "$summary" --fields requirements_completed | jq -r '.requirements_completed'
+done
+```
+
+### 5d. 状态判定矩阵
+
+对于每个 REQ-ID，使用所有三个来源确定状态：
+
+| VERIFICATION.md 状态 | SUMMARY Frontmatter | REQUIREMENTS.md | → 最终状态 |
+|---------------------|---------------------|-----------------|-----------|
+| passed              | 已列出              | `[x]`           | **已满足** |
+| passed              | 已列出              | `[ ]`           | **已满足**（更新复选框）|
+| passed              | 缺失                | 任意            | **部分**（手动验证）|
+| gaps_found          | 任意                | 任意            | **未满足** |
+| 缺失                | 已列出              | 任意            | **部分**（验证缺口）|
+| 缺失                | 缺失                | 任意            | **未满足** |
+
+### 5e. 失败门控和孤立检测
+
+**必需：** 任何 `未满足` 的需求必须强制里程碑审计状态为 `gaps_found`。
+
+**孤立检测：** 存在于 REQUIREMENTS.md 追溯表中但在所有阶段 VERIFICATION.md 文件中都不存在的需求必须标记为孤立。孤立需求视为 `未满足`——它们被分配了但从未被任何阶段验证。
+
+## 6. 汇总到 v{version}-MILESTONE-AUDIT.md
+
+创建 `.planning/v{version}-v{version}-MILESTONE-AUDIT.md`：
+
+```yaml
+---
+milestone: {version}
+audited: {timestamp}
+status: passed | gaps_found | tech_debt
+scores:
+  requirements: N/M
+  phases: N/M
+  integration: N/M
+  flows: N/M
+gaps:  # 关键阻塞项
+  requirements:
+    - id: "{REQ-ID}"
+      status: "unsatisfied | partial | orphaned"
+      phase: "{assigned phase}"
+      claimed_by_plans: ["{引用此需求的计划文件}"]
+      completed_by_plans: ["{SUMMARY 标记为完成的计划文件}"]
+      verification_status: "passed | gaps_found | missing | orphaned"
+      evidence: "{具体证据或缺乏证据}"
+  integration: [...]
+  flows: [...]
+tech_debt:  # 非关键，已推迟
+  - phase: 01-auth
+    items:
+      - "TODO: add rate limiting"
+      - "Warning: no password strength validation"
+  - phase: 03-dashboard
+    items:
+      - "Deferred: mobile responsive layout"
+---
+```
+
+加上完整的 markdown 报告，包含需求、阶段、集成、技术债务的表格。
+
+**状态值：**
+- `passed` — 所有需求已满足，无关键缺口，技术债务最少
+- `gaps_found` — 存在关键阻塞项
+- `tech_debt` — 无阻塞项但有累积的推迟项需要审查
+
+## 7. 展示结果
+
+根据状态路由（参见 `<offer_next>`）。
+
+</process>
+
+<offer_next>
+直接输出此 markdown（不作为代码块）。根据状态路由：
+
+---
+
+**如果 passed：**
+
+## ✓ 里程碑 {version} — 审计通过
+
+**评分：** {N}/{M} 需求已满足
+**报告：** .planning/v{version}-MILESTONE-AUDIT.md
+
+所有需求已覆盖。跨阶段集成已验证。端到端流程完整。
+
+───────────────────────────────────────────────────────────────
+
+## ▶ 下一步
+
+**完成里程碑** — 归档并打标签
+
+/specops:complete-milestone {version}
+
+<sub>先 /clear → 全新上下文窗口</sub>
+
+───────────────────────────────────────────────────────────────
+
+---
+
+**如果 gaps_found：**
+
+## ⚠ 里程碑 {version} — 发现缺口
+
+**评分：** {N}/{M} 需求已满足
+**报告：** .planning/v{version}-MILESTONE-AUDIT.md
+
+### 未满足的需求
+
+{对于每个未满足的需求：}
+- **{REQ-ID}：{描述}**（阶段 {X}）
+  - {原因}
+
+### 跨阶段问题
+
+{对于每个集成缺口：}
+- **{from} → {to}：** {问题}
+
+### 中断的流程
+
+{对于每个流程缺口：}
+- **{流程名称}：** 在 {步骤} 处中断
+
+───────────────────────────────────────────────────────────────
+
+## ▶ 下一步
+
+**规划缺口修复** — 创建阶段以完成里程碑
+
+/specops:plan-milestone-gaps
+
+<sub>先 /clear → 全新上下文窗口</sub>
+
+───────────────────────────────────────────────────────────────
+
+**其他可用操作：**
+- cat .planning/v{version}-MILESTONE-AUDIT.md — 查看完整报告
+- /specops:complete-milestone {version} — 仍然继续（接受技术债务）
+
+───────────────────────────────────────────────────────────────
+
+---
+
+**如果 tech_debt（无阻塞项但有累积债务）：**
+
+## ⚡ 里程碑 {version} — 技术债务审查
+
+**评分：** {N}/{M} 需求已满足
+**报告：** .planning/v{version}-MILESTONE-AUDIT.md
+
+所有需求已满足。无关键阻塞项。累积的技术债务需要审查。
+
+### 按阶段的技术债务
+
+{对于每个有债务的阶段：}
+**阶段 {X}：{名称}**
+- {项目 1}
+- {项目 2}
+
+### 总计：{N} 项，跨 {M} 个阶段
+
+───────────────────────────────────────────────────────────────
+
+## ▶ 选项
+
+**A. 完成里程碑** — 接受债务，记入待办
+
+/specops:complete-milestone {version}
+
+**B. 规划清理阶段** — 在完成前处理债务
+
+/specops:plan-milestone-gaps
+
+<sub>先 /clear → 全新上下文窗口</sub>
+
+───────────────────────────────────────────────────────────────
+</offer_next>
+
+<success_criteria>
+- [ ] 已识别里程碑范围
+- [ ] 已读取所有阶段 VERIFICATION.md 文件
+- [ ] 已提取每个阶段 SUMMARY.md 的 `requirements-completed` frontmatter
+- [ ] 已解析 REQUIREMENTS.md 追溯表中所有里程碑 REQ-ID
+- [ ] 已完成 3 源交叉引用（VERIFICATION + SUMMARY + 追溯表）
+- [ ] 已检测孤立需求（在追溯表中但在所有 VERIFICATION 中都不存在）
+- [ ] 已汇总技术债务和推迟的缺口
+- [ ] 已生成带里程碑需求 ID 的集成检查器
+- [ ] 已创建包含结构化需求缺口对象的 v{version}-MILESTONE-AUDIT.md
+- [ ] 已执行失败门控——任何未满足的需求强制 gaps_found 状态
+- [ ] 已展示带可操作后续步骤的结果
+</success_criteria>

package/.opencode/workflows/check-todos.md

@@ -0,0 +1,176 @@
+<purpose>
+列出所有待处理的待办事项，允许选择，加载所选待办事项的完整上下文，并路由到适当的操作。
+</purpose>
+
+<required_reading>
+在开始之前，阅读调用提示的 execution_context 中引用的所有文件。
+</required_reading>
+
+<process>
+
+<step name="init_context">
+加载待办事项上下文：
+
+```bash
+INIT=$(node .opencode/bin/specops-tools.cjs init todos)
+```
+
+从 init JSON 中提取：`todo_count`、`todos`、`pending_dir`。
+
+如果 `todo_count` 为 0：
+```
+No pending todos.
+
+Todos are captured during work sessions with /specops:add-todo.
+
+---
+
+Would you like to:
+
+1. Continue with current phase (/specops:progress)
+2. Add a todo now (/specops:add-todo)
+```
+
+退出。
+</step>
+
+<step name="parse_filter">
+检查参数中的领域过滤器：
+- `/specops:check-todos` → 显示全部
+- `/specops:check-todos api` → 仅过滤 area:api
+</step>
+
+<step name="list_todos">
+使用 init 上下文中的 `todos` 数组（如果指定了领域则已过滤）。
+
+解析并显示为编号列表：
+
+```
+Pending Todos:
+
+1. Add auth token refresh (api, 2d ago)
+2. Fix modal z-index issue (ui, 1d ago)
+3. Refactor database connection pool (database, 5h ago)
+
+---
+
+Reply with a number to view details, or:
+- `/specops:check-todos [area]` to filter by area
+- `q` to exit
+```
+
+将创建时间戳格式化为相对时间。
+</step>
+
+<step name="handle_selection">
+等待用户回复编号。
+
+如果有效：加载所选待办事项，继续。
+如果无效："Invalid selection. Reply with a number (1-[N]) or `q` to exit."
+</step>
+
+<step name="load_context">
+完整读取待办事项文件。显示：
+
+```
+## [title]
+
+**Area:** [area]
+**Created:** [date] ([relative time] ago)
+**Files:** [list or "None"]
+
+### Problem
+[problem section content]
+
+### Solution
+[solution section content]
+```
+
+如果 `files` 字段有条目，读取并简要总结每个文件。
+</step>
+
+<step name="check_roadmap">
+检查路线图（可使用 init progress 或直接检查文件是否存在）：
+
+如果 `.planning/ROADMAP.md` 存在：
+1. 检查待办事项的领域是否匹配即将到来的阶段
+2. 检查待办事项的文件是否与某个阶段的范围重叠
+3. 记录任何匹配以用于操作选项
+</step>
+
+<step name="offer_actions">
+**如果待办事项映射到路线图阶段：**
+
+使用 AskUserQuestion：
+- header："Action"
+- question："此待办事项与 Phase [N]: [name] 相关。你想怎么做？"
+- options：
+  - "Work on it now" — 移至已完成，开始工作
+  - "Add to phase plan" — 在规划 Phase [N] 时包含
+  - "Brainstorm approach" — 在决定前先思考方案
+  - "Put it back" — 返回列表
+
+**如果没有路线图匹配：**
+
+使用 AskUserQuestion：
+- header："Action"
+- question："你想对这个待办事项做什么？"
+- options：
+  - "Work on it now" — 移至已完成，开始工作
+  - "Create a phase" — 使用此范围执行 /specops:add-phase
+  - "Brainstorm approach" — 在决定前先思考方案
+  - "Put it back" — 返回列表
+</step>
+
+<step name="execute_action">
+**Work on it now：**
+```bash
+mv ".planning/todos/pending/[filename]" ".planning/todos/done/"
+```
+更新 STATE.md 待办事项计数。展示问题/解决方案上下文。开始工作或询问如何继续。
+
+**Add to phase plan：**
+在阶段规划备注中记录待办事项引用。保持在 pending 中。返回列表或退出。
+
+**Create a phase：**
+显示：`/specops:add-phase [description from todo]`
+保持在 pending 中。用户在新的上下文中运行命令。
+
+**Brainstorm approach：**
+保持在 pending 中。开始讨论问题和方案。
+
+**Put it back：**
+返回 list_todos 步骤。
+</step>
+
+<step name="update_state">
+在任何改变待办事项计数的操作之后：
+
+重新运行 `init todos` 获取更新后的计数，然后更新 STATE.md 中的 "### Pending Todos" 部分（如果存在）。
+</step>
+
+<step name="git_commit">
+如果待办事项被移至 done/，提交更改：
+
+```bash
+git rm --cached .planning/todos/pending/[filename] 2>/dev/null || true
+node .opencode/bin/specops-tools.cjs commit "docs: start work on todo - [title]" --files .planning/todos/done/[filename] .planning/STATE.md
+```
+
+工具会自动遵循 `commit_docs` 配置和 gitignore。
+
+确认："Committed: docs: start work on todo - [title]"
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] 所有待处理的待办事项已列出，包含标题、领域、时间
+- [ ] 已应用领域过滤器（如果指定）
+- [ ] 所选待办事项的完整上下文已加载
+- [ ] 已检查路线图上下文以匹配阶段
+- [ ] 已提供适当的操作选项
+- [ ] 所选操作已执行
+- [ ] STATE.md 已更新（如果待办事项计数变化）
+- [ ] 更改已提交到 git（如果待办事项移至 done/）
+</success_criteria>

package/.opencode/workflows/cleanup.md

@@ -0,0 +1,152 @@
+<purpose>
+
+将已完成里程碑的阶段目录归档到 `.planning/milestones/v{X.Y}-phases/`。识别哪些阶段属于每个已完成的里程碑，显示预览摘要，确认后移动目录。
+
+</purpose>
+
+<required_reading>
+
+1. `.planning/MILESTONES.md`
+2. `.planning/milestones/` 目录列表
+3. `.planning/phases/` 目录列表
+
+</required_reading>
+
+<process>
+
+<step name="identify_completed_milestones">
+
+读取 `.planning/MILESTONES.md` 以识别已完成的里程碑及其版本。
+
+```bash
+cat .planning/MILESTONES.md
+```
+
+提取每个里程碑版本（例如 v1.0、v1.1、v2.0）。
+
+检查哪些里程碑归档目录已存在：
+
+```bash
+ls -d .planning/milestones/v*-phases 2>/dev/null
+```
+
+过滤出尚未拥有 `-phases` 归档目录的里程碑。
+
+如果所有里程碑都已有阶段归档：
+
+```
+所有已完成的里程碑都已归档阶段目录。无需清理。
+```
+
+在此停止。
+
+</step>
+
+<step name="determine_phase_membership">
+
+对于每个没有 `-phases` 归档的已完成里程碑，读取归档的 ROADMAP 快照以确定哪些阶段属于它：
+
+```bash
+cat .planning/milestones/v{X.Y}-ROADMAP.md
+```
+
+从归档路线图中提取阶段编号和名称（例如 Phase 1: Foundation, Phase 2: Auth）。
+
+检查这些阶段目录中哪些仍存在于 `.planning/phases/` 中：
+
+```bash
+ls -d .planning/phases/*/ 2>/dev/null
+```
+
+将阶段目录与里程碑归属进行匹配。仅包含仍存在于 `.planning/phases/` 中的目录。
+
+</step>
+
+<step name="show_dry_run">
+
+为每个里程碑展示预览摘要：
+
+```
+## 清理摘要
+
+### v{X.Y} — {Milestone Name}
+以下阶段目录将被归档：
+- 01-foundation/
+- 02-auth/
+- 03-core-features/
+
+目标位置：.planning/milestones/v{X.Y}-phases/
+
+### v{X.Z} — {Milestone Name}
+以下阶段目录将被归档：
+- 04-security/
+- 05-hardening/
+
+目标位置：.planning/milestones/v{X.Z}-phases/
+```
+
+如果没有剩余的阶段目录需要归档（全部已移动或删除）：
+
+```
+未找到需要归档的阶段目录。阶段可能已被移除或先前已归档。
+```
+
+在此停止。
+
+AskUserQuestion："是否继续归档？"选项："是 — 归档列出的阶段" | "取消"
+
+如果选择"取消"：停止。
+
+</step>
+
+<step name="archive_phases">
+
+对于每个里程碑，移动阶段目录：
+
+```bash
+mkdir -p .planning/milestones/v{X.Y}-phases
+```
+
+对于属于该里程碑的每个阶段目录：
+
+```bash
+mv .planning/phases/{dir} .planning/milestones/v{X.Y}-phases/
+```
+
+对清理集中的所有里程碑重复此操作。
+
+</step>
+
+<step name="commit">
+
+提交更改：
+
+```bash
+node .opencode/bin/specops-tools.cjs commit "chore: archive phase directories from completed milestones" --files .planning/milestones/ .planning/phases/
+```
+
+</step>
+
+<step name="report">
+
+```
+已归档：
+{对于每个里程碑}
+- v{X.Y}: {N} phase directories → .planning/milestones/v{X.Y}-phases/
+
+.planning/phases/ 已清理。
+```
+
+</step>
+
+</process>
+
+<success_criteria>
+
+- [ ] 已识别所有没有现有阶段归档的已完成里程碑
+- [ ] 已从归档的 ROADMAP 快照确定阶段归属
+- [ ] 已显示预览摘要并获得用户确认
+- [ ] 阶段目录已移动到 `.planning/milestones/v{X.Y}-phases/`
+- [ ] 更改已提交
+
+</success_criteria>