gsd-lite 0.3.2 → 0.3.5

package/references/execution-loop.md

@@ -0,0 +1,162 @@
+# Execution Loop -- Canonical Specification
+
+本文件是执行循环的唯一 source of truth。所有 command 文件 (start.md, prd.md, resume.md) 引用此文件。
+
+---
+
+### 11.1 — 加载 phase 计划
+
+```
+for each pending phase:
+  加载 phase 计划 + todo DAG
+```
+
+### 11.2 — 选择 runnable task
+
+选择条件:
+- `lifecycle` 属于 `{pending, needs_revalidation}`
+- `requires` 中每个依赖都满足对应 gate
+- 不被 unresolved blocker 阻塞
+- 未超过 retry 上限
+
+如果 0 个 runnable task 且 phase 未完成:
+```
+├── 全部 blocked → workflow_mode = awaiting_user，展示所有 blocker
+└── 全部等待 review → 触发 batch review (L1) 或等待 L2 review 完成
+```
+
+### 11.3 — 构建 executor 上下文 + 串行派发
+
+executor 上下文传递协议 (orchestrator → executor):
+```
+├── task_spec:           从 phases/*.md 提取当前 task 的规格段落
+├── research_decisions:  从 research_basis 引用的 decision 摘要
+├── predecessor_outputs: 前置依赖 task 的 files_changed + checkpoint_commit
+├── project_conventions: CLAUDE.md 路径 (executor 自行读取)
+├── workflows:           需加载的工作流文件路径 (如 tdd-cycle.md)
+└── constraints:         retry_count / level / review_required
+```
+
+派发 `executor` 子代理执行单个 task。
+
+### 11.4 — 处理 executor 结果
+
+严格按 agent result contract 处理:
+```
+├── checkpointed → 写入 checkpoint commit + evidence refs → 进入审查 (11.5)
+├── blocked      → 写入 blocked_reason / unblock_condition
+│                  → 编排器检查 decisions 数组，能自动回答则重新派发
+│                  → 不能回答 → workflow_mode = awaiting_user，向用户转达
+├── failed       → retry_count + 1
+│                  → 未超限 → 重新派发 executor
+│                  → 超限 (3次) 或返回 [FAILED] 且错误指纹重复
+│                    或修复尝试未收敛 → 触发 debugger (见下方)
+```
+
+**Debugger 触发流程:**
+1. 编排器派发 `debugger` 子代理，传入: 错误信息 + executor 修复尝试记录 + 相关代码路径
+2. debugger 返回: 根因分析 + 修复方向建议
+3. 编排器决定:
+   - 带修复方向重新派发 executor
+   - 标记 task failed
+   - 标记 phase failed
+
+**Decisions 累积:**
+- executor 返回 `[DECISION]` → 编排器追加到 `state.json` 的 `decisions` 数组
+- 每条 decision 记录: `id` / `task` / `summary` / `phase`
+- decisions 跨 task、跨 phase、跨 `/clear` + `/gsd:resume` 持久保留
+- 编排器收到 `[BLOCKED]` 时，先查 `decisions` 数组尝试自动回答
+
+### 11.5 — 分层审查
+
+```
+├── L0: checkpoint commit 后可直接 accepted (无需 reviewer)
+├── L1: phase 结束后批量 reviewer 审查
+│       → 派发 reviewer 子代理，scope = phase
+└── L2: checkpoint commit 后立即独立审查
+        → 派发 reviewer 子代理，scope = task
+        → 未 accepted 前不释放其下游依赖
+```
+
+**审查级别运行时重分类:**
+- executor 报告 `contract_changed: true` + 涉及 auth/payment/public API → 自动升级为 L2
+- executor 标注 `[LEVEL-UP]` → 编排器采纳
+- 不主动降级 (安全优先)
+
+### 11.6 — 处理 reviewer 结果
+
+```
+├── 无 Critical → 更新 accepted 状态 + evidence refs
+└── 有 Critical → 标记返工 task + 失效传播 → 重新审查 (最多 3 轮)
+```
+
+**返工失效传播规则:**
+- 返工修改了 contract / schema / shared behavior:
+  → 所有直接和间接依赖 task → `needs_revalidation`
+  → 清空其旧 `evidence_refs`
+  → 已 accepted 则退回到 `checkpointed` 或 `pending_review`
+- 返工只影响局部实现、外部契约未变:
+  → 下游 task 保持现状
+  → 但受影响验证范围必须重跑并刷新 evidence
+- 触发判定: `contract_changed` (executor 运行时报告) 是主触发源
+  `invalidate_downstream_on_change` (planner 静态标记) 是预判辅助
+  → executor 报告 `contract_changed: true` → 一定传播
+  → planner 标记但 executor 报告 false → 不传播 (以运行时实际为准)
+
+### 11.7 — Phase handoff gate
+
+<HARD-GATE id="phase-handoff">
+所有条件必须满足才能进入下一 phase:
+- [ ] 所有 required task = `accepted`
+- [ ] required review = `passed`
+- [ ] critical issues = 0
+- [ ] tests/lint/typecheck 满足计划验证条件
+- [ ] 方向校验: 当前阶段产出是否仍与 plan.md 中的项目目标一致？
+
+→ 全部满足 → 自动进入下一阶段
+→ 任一不满足 → 标注问题，尝试修复，3 次失败停止
+→ 方向漂移 → workflow_mode = awaiting_user，展示偏差让用户决定
+</HARD-GATE>
+
+### 11.8 — 批量更新 state.json
+
+阶段完成后，编排器批量更新 state.json:
+- 更新 phase lifecycle → `accepted`
+- 更新 phase_handoff 信息
+- 归档旧 phase 的 evidence (只保留当前 phase 和上一 phase)
+- 推进 `current_phase` 到下一个 pending phase
+
+**规则:** 只有编排器写 state.json，避免并发竞态。
+
+### 11.9 — 上下文检查
+
+每次派发子代理前和阶段切换时检查上下文健康度:
+
+```
+remaining < 35%:
+  1. 保存完整状态到 state.json
+  2. workflow_mode = awaiting_clear
+  3. 输出: "上下文剩余 <35%，已保存进度。请执行 /clear 然后 /gsd:resume 继续"
+  4. 停止执行
+
+remaining < 25%:
+  1. 紧急保存状态到 state.json
+  2. workflow_mode = awaiting_clear
+  3. 输出: "上下文即将耗尽，已保存进度。请立即执行 /clear 然后 /gsd:resume"
+  4. 立即停止
+```
+
+---
+
+## 依赖门槛语义 (Gate-aware dependencies)
+
+```json
+{ "kind": "task",  "id": "2.2", "gate": "checkpoint" }     // 低风险内部串接
+{ "kind": "task",  "id": "2.3", "gate": "accepted" }        // 默认安全门槛
+{ "kind": "phase", "id": 2,     "gate": "phase_complete" }  // 跨 phase 依赖
+```
+
+- `checkpoint` — 允许依赖未独立验收的实现检查点；只适合低风险内部串接
+- `accepted` — 默认安全门槛；适合共享行为、公共接口、L2 风险任务
+- `phase_complete` — 跨 phase 依赖；只有 phase handoff 完成后才释放
+- 默认值: 如果 planner 没显式放宽，则依赖按 `accepted` 处理

package/references/review-classification.md

@@ -0,0 +1,84 @@
+# 审查级别分类参考
+
+## 静态分类 (计划时)
+
+| 级别 | 适用场景 | 审查方式 |
+|------|---------|---------|
+| L0 | 无运行时语义变化 (docs/config/style) | checkpoint 后直接 accepted |
+| L1 | 普通编码任务 (默认) | phase 结束后批量审查 |
+| L2 | 高风险 (auth/payment/public API/DB migration) | checkpoint 后立即独立审查 |
+
+## 运行时重分类
+
+触发条件 (L1 -> L2 升级):
+1. executor 报告 `contract_changed: true` 且 task name 匹配敏感关键词
+2. executor decisions 中包含 `[LEVEL-UP]` 标注 (字符串或 `decision.summary` 中包含)
+
+敏感关键词正则 (`SENSITIVE_KEYWORDS`):
+
+```
+/\b(auth|payment|security|public.?api|login|token|credential|session|oauth)\b/i
+```
+
+规则: 只升不降 (安全优先)。当前级别为 L2 或 L3 时直接保持不变。
+
+## 决策树
+
+```
+task.level 当前值?
+├── L2 或 L3 -> 保持不变 (不降级)
+└── L0 或 L1
+    ├── executor decisions 含 [LEVEL-UP]? -> 升级为 L2
+    ├── contract_changed: true + task.name 匹配敏感关键词? -> 升级为 L2
+    └── 否 -> 保持当前级别
+```
+
+来源: `reclassifyReviewLevel()` in `src/tools/state.js`
+
+## 审查流程
+
+### L0 流程
+
+```
+executor checkpointed
+  -> handleExecutorResult 检测 reviewLevel === 'L0'
+  -> auto_accepted = true
+  -> 编排器直接 accepted (persist lifecycle: 'accepted', done +1)
+  -> 释放下游依赖
+```
+
+不派发 reviewer。`review_required: false` 的 task 同样走此路径。
+
+### L1 流程
+
+```
+executor checkpointed
+  -> workflow_mode 保持 'executing_task'
+  -> 继续执行其他 task
+  -> phase 内所有 runnable task 完成后
+  -> selectRunnableTask 返回 { mode: 'trigger_review' }
+  -> 编排器设置 workflow_mode = 'reviewing_phase'
+  -> 派发 reviewer (scope='phase', review_level='L1-batch')
+  -> 批量审查所有 checkpointed task (排除 L0)
+```
+
+### L2 流程
+
+```
+executor checkpointed
+  -> handleExecutorResult 检测 reviewLevel === 'L2' && review_required !== false
+  -> 设置 current_review = { scope: 'task', scope_id: task.id, stage: 'spec' }
+  -> workflow_mode = 'reviewing_task'
+  -> 派发 reviewer (scope='task', review_level='L2')
+  -> 审查通过后才释放下游依赖
+```
+
+## Reviewer 结果处理
+
+| 审查结果 | 编排器行为 |
+|----------|-----------|
+| 无 critical issues | accepted_tasks 标记为 `accepted`; phase_review.status = `accepted` |
+| 有 critical issues | rework_tasks 标记为 `needs_revalidation`; phase_review.status = `rework_required` |
+| critical + `invalidates_downstream` | 触发 `propagateInvalidation`: 所有下游依赖 task -> `needs_revalidation` + 清空 evidence_refs |
+
+来源: `handleReviewerResult()` in `src/tools/orchestrator.js`, `reviewer.md` in `agents/`

package/references/state-diagram.md

@@ -0,0 +1,218 @@
+# 状态机图参考
+
+## 1. Task 生命周期
+
+### 状态转换表
+
+| 当前状态 | 允许的目标状态 |
+|----------|---------------|
+| `pending` | `running`, `blocked` |
+| `running` | `checkpointed`, `blocked`, `failed` |
+| `checkpointed` | `accepted`, `needs_revalidation` |
+| `accepted` | `needs_revalidation` |
+| `blocked` | `pending` |
+| `failed` | `pending` |
+| `needs_revalidation` | `pending` |
+
+### Mermaid 图
+
+```mermaid
+stateDiagram-v2
+    [*] --> pending
+
+    pending --> running : 编排器选中执行
+    pending --> blocked : executor 报告阻塞
+
+    running --> checkpointed : executor 完成 checkpoint
+    running --> blocked : executor 运行时阻塞
+    running --> failed : executor 执行失败
+
+    checkpointed --> accepted : reviewer 审查通过 / L0 自动接受
+    checkpointed --> needs_revalidation : 上游返工触发失效传播
+
+    accepted --> needs_revalidation : 上游 contract 变更触发失效传播
+
+    blocked --> pending : 阻塞解除 (用户干预/自动匹配 decision)
+
+    failed --> pending : 重置后重试 (debugger 建议/用户干预)
+
+    needs_revalidation --> pending : 重新排入执行队列
+```
+
+### 关键路径说明
+
+- **正常路径**: `pending -> running -> checkpointed -> accepted`
+- **阻塞路径**: `pending -> blocked -> pending -> running` (解除阻塞后重入)
+- **失败-重试路径**: `running -> failed -> pending -> running` (retry_count 递增)
+- **返工路径**: `accepted -> needs_revalidation -> pending -> running` (contract 变更触发)
+- **审查返工**: `checkpointed -> needs_revalidation -> pending -> running` (reviewer 要求返工)
+
+来源: `TASK_LIFECYCLE` in `src/schema.js`
+
+---
+
+## 2. Phase 生命周期
+
+### 状态转换表
+
+| 当前状态 | 允许的目标状态 |
+|----------|---------------|
+| `pending` | `active` |
+| `active` | `reviewing`, `blocked`, `failed` |
+| `reviewing` | `accepted`, `active` |
+| `accepted` | *(终态，无后续转换)* |
+| `blocked` | `active` |
+| `failed` | *(终态，无后续转换)* |
+
+### Mermaid 图
+
+```mermaid
+stateDiagram-v2
+    [*] --> pending
+
+    pending --> active : 前置 phase 完成 / 首个 phase 自动激活
+
+    active --> reviewing : 所有 task 完成，触发 phase review
+    active --> blocked : 外部依赖阻塞
+    active --> failed : 不可恢复失败 (debugger 报告架构问题)
+
+    reviewing --> accepted : reviewer 审查通过 + handoff gate 满足
+    reviewing --> active : reviewer 发现 critical issues，需要返工
+
+    blocked --> active : 阻塞解除
+
+    accepted --> [*]
+    failed --> [*]
+```
+
+### 关键路径说明
+
+- **正常路径**: `pending -> active -> reviewing -> accepted`
+- **返工路径**: `active -> reviewing -> active -> reviewing -> accepted` (最多循环)
+- **失败路径**: `active -> failed` (终态，不可恢复)
+- **Phase 推进**: 当前 phase `accepted` 后，下一个 `pending` phase 自动转为 `active`
+
+来源: `PHASE_LIFECYCLE` in `src/schema.js`
+
+---
+
+## 3. Phase 审查状态
+
+### 允许的状态值
+
+```
+pending -> reviewing -> accepted
+                    \-> rework_required
+```
+
+| 状态 | 含义 |
+|------|------|
+| `pending` | 初始状态，尚未开始审查 |
+| `reviewing` | 审查进行中 |
+| `accepted` | 审查通过 |
+| `rework_required` | 审查发现 critical issues，需要返工 |
+
+### Mermaid 图
+
+```mermaid
+stateDiagram-v2
+    [*] --> pending
+
+    pending --> reviewing : 触发 phase review
+
+    reviewing --> accepted : 无 critical issues
+    reviewing --> rework_required : 有 critical issues
+
+    rework_required --> reviewing : 返工完成后重新审查
+```
+
+### 与 Phase Lifecycle 的关系
+
+- `phase_review.status` 是 phase 对象内的子状态
+- `phase_review.retry_count` 记录审查返工次数: 无 critical 时重置为 0，有 critical 时递增
+- `handleReviewerResult` 中: 有 critical -> `rework_required`; 无 critical -> `accepted`
+- 审查 accepted 且 scope 为 phase 时，同时设置 `phase_handoff.required_reviews_passed = true`
+
+来源: `PHASE_REVIEW_STATUS` in `src/schema.js`, `handleReviewerResult()` in `src/tools/orchestrator.js`
+
+---
+
+## 4. Workflow Mode 状态机
+
+### 所有模式
+
+| 模式 | 含义 |
+|------|------|
+| `planning` | 计划阶段 |
+| `executing_task` | 正在执行 task |
+| `reviewing_task` | L2 task 即时审查中 |
+| `reviewing_phase` | L1 phase 批量审查中 |
+| `awaiting_clear` | 上下文不足，等待 /clear |
+| `awaiting_user` | 等待用户干预 (阻塞/方向漂移) |
+| `paused_by_user` | 用户主动暂停 |
+| `reconcile_workspace` | git HEAD 不匹配，需要工作区协调 |
+| `replan_required` | 计划文件被外部修改，需要重新规划 |
+| `research_refresh_needed` | 研究缓存过期，需刷新 |
+| `completed` | 所有 phase 完成 (终态) |
+| `failed` | 工作流失败 (终态) |
+
+### Mermaid 图 (主要转换)
+
+```mermaid
+stateDiagram-v2
+    [*] --> planning
+
+    planning --> executing_task : init 完成
+
+    executing_task --> reviewing_task : L2 task checkpointed
+    executing_task --> reviewing_phase : phase 内所有 task 完成
+    executing_task --> awaiting_user : task blocked / 方向漂移
+    executing_task --> awaiting_clear : 上下文 < 35%
+    executing_task --> failed : debugger 报告架构问题
+
+    reviewing_task --> executing_task : 审查完成 (通过或返工)
+    reviewing_phase --> executing_task : 审查返工 (有 critical)
+    reviewing_phase --> completed : 最终 phase 审查通过
+
+    awaiting_clear --> executing_task : /clear + /resume 后恢复
+    awaiting_user --> executing_task : 用户解除阻塞 / 自动匹配 decision
+
+    state preflight_overrides <<choice>>
+    executing_task --> preflight_overrides : resume 时 preflight 检测
+    preflight_overrides --> reconcile_workspace : git HEAD 不匹配
+    preflight_overrides --> replan_required : 计划文件被修改
+    preflight_overrides --> research_refresh_needed : 研究缓存过期
+    preflight_overrides --> awaiting_user : 方向漂移检测
+
+    research_refresh_needed --> executing_task : 研究刷新完成
+    research_refresh_needed --> reviewing_task : 刷新后恢复审查状态
+    research_refresh_needed --> reviewing_phase : 刷新后恢复审查状态
+
+    paused_by_user --> executing_task : 用户恢复
+
+    completed --> [*]
+    failed --> [*]
+```
+
+### 关键转换说明
+
+**执行主路径**:
+`planning -> executing_task -> reviewing_phase -> executing_task (next phase) -> ... -> completed`
+
+**L2 审查分支**:
+`executing_task -> reviewing_task -> executing_task`
+
+**上下文耗尽路径**:
+`executing_task -> awaiting_clear -> executing_task` (需要 /clear + /resume)
+
+**Preflight 覆盖 (resume 时检测)**:
+`resumeWorkflow()` 执行 `evaluatePreflight()` 检测以下条件 (按优先级):
+1. git HEAD 不匹配 -> `reconcile_workspace`
+2. 计划文件被外部修改 -> `replan_required`
+3. 方向漂移 -> `awaiting_user`
+4. 研究缓存过期 -> `research_refresh_needed`
+
+**Research 刷新后恢复**:
+`storeResearch()` 中: 如果 `workflow_mode === 'research_refresh_needed'`，调用 `inferWorkflowModeAfterResearch()` 根据 `current_review` 状态推断恢复到 `reviewing_phase` / `reviewing_task` / `executing_task`。
+
+来源: `WORKFLOW_MODES` in `src/schema.js`, `resumeWorkflow()`, `evaluatePreflight()` in `src/tools/orchestrator.js`, `storeResearch()` in `src/tools/state.js`