gsd-lite 0.1.0

package/commands/gsd-prd.md

@@ -0,0 +1,154 @@
+---
+name: gsd-prd
+description: Start project from requirements document or description text
+arguments:
+  path_or_description: File path to requirements doc, or inline description text
+---
+
+<role>
+你是 GSD-Lite 编排器。从需求文档或描述文本启动项目，快速进入计划阶段。
+用用户输入的语言进行所有后续输出。
+</role>
+
+<usage>
+```
+/gsd:prd docs/requirements.md          # 从需求文件启动
+/gsd:prd "实现用户认证，支持 JWT"       # 从描述文本启动
+```
+</usage>
+
+<process>
+
+## STEP 1: 解析输入
+
+判断 `$ARGUMENTS` 的类型:
+
+**如果是文件路径** (包含 `/` 或 `.` 且文件存在):
+- 使用 Read 工具读取文件内容
+- 如果文件不存在 → 告知用户并停止
+
+**如果是文本描述**:
+- 直接作为需求描述使用
+
+## STEP 2: 分析代码库
+
+- 使用 Glob/Grep/Read 分析代码库中与需求相关的部分
+- 识别: 已有代码结构、技术栈、现有约定
+- 目的: 让后续计划能与现有代码库无缝衔接
+
+## STEP 3: 提取关键需求点
+
+- 从输入内容中提取所有关键需求点
+- 整理为结构化列表
+- 向用户确认理解是否正确:
+  - "以下是我从需求中提取的关键点，请确认:"
+  - 逐条列出，标注优先级
+
+## STEP 4: 提出补充问题
+
+- 基于需求分析，识别模糊点和缺失信息
+- 提出补充问题，每个问题提供选项:
+  - 标识推荐选项
+  - 允许用户自定义回答
+- 使用 references/questioning.md 的提问技巧 (如可用)
+- 用户回答后，可适当追问直到需求清晰
+
+<!-- 以下 STEP 5-12 同 gsd-start.md -->
+
+## STEP 5: 智能判断是否需要研究
+
+- 新项目 / 涉及新技术栈 → 必须研究
+- 简单 bug 修复 / 已有研究且未过期 → 跳过
+- 用户明确要求 → 研究
+- 需要时 → 派发 gsd-researcher 子代理 → 展示关键发现
+- 不需要 → 跳过，进入下一步
+
+## STEP 6: 深度思考
+
+- 如有 sequential-thinking MCP → 调用深入思考
+- 无则跳过，不影响流程
+
+## STEP 7: 生成分阶段计划
+
+- phase 负责管理与验收，task 负责执行
+- 每阶段控制在 5-8 个 task (便于 phase-level 收口)
+- 每个 task = 原子化 todo (含文件、操作、验证条件)
+- 每个 task 补充元数据: `requires` / `review_required` / `research_basis`
+- 审查级别按影响面判定: L0(无运行时语义变化) / L1(普通) / L2(高风险)
+- 标注可并行任务组 [PARALLEL] (当前仅作未来升级标记)
+
+## STEP 8: 计划自审
+
+轻量替代 plan-checker:
+- 检查: 是否有遗漏的需求点？
+- 检查: 阶段划分是否合理？(phase 过大则拆分)
+- 检查: 任务依赖关系是否正确？
+- 检查: 验证条件是否可执行？
+- 如属高风险项目 → 升级为增强计划审查:
+
+<enhanced_plan_review>
+触发条件: 涉及 auth / payment / security / public API / DB migration / 核心架构变更
+
+审查维度:
+1. 需求覆盖: 原始需求的每个要点是否都映射到了至少一个 task？
+2. 风险排序: 高风险 task 是否排在前面？(fail-fast 原则)
+3. 依赖安全: L2 task 的下游是否都用了 gate:accepted？
+4. 验证充分: 涉及 auth/payment 的 task 是否都有明确的安全验证条件？
+5. 陷阱规避: research/PITFALLS.md 中的每个陷阱是否都有对应的防御 task 或验证条件？
+
+输出: pass / revise (附具体修正建议)
+轮次: 最多 2 轮自审修正；2 轮后仍有问题 → 标注风险展示给用户
+</enhanced_plan_review>
+
+→ 自审修正后再展示给用户
+
+## STEP 9: 展示计划，等待用户确认
+
+- 展示完整分阶段计划
+- 用户指出问题 → 调整 → 再展示
+- 用户确认 → 继续
+
+## STEP 10: 生成文档
+
+- 创建 .gsd/ 目录
+- 写入 state.json + plan.md + phases/*.md
+- 初始化 `workflow_mode` / `current_task` / `current_review` / phase 状态与 handoff 信息
+- 如有研究: 写入 .gsd/research/
+
+<HARD-GATE id="docs-written">
+□ state.json 已写入且包含所有 canonical fields
+□ plan.md 已写入
+□ phases/*.md 已写入 (每个 phase 一个文件)
+□ 所有 task 都有 lifecycle / level / requires / review_required
+→ 全部满足才可继续
+</HARD-GATE>
+
+## STEP 11: 进入自动执行主路径
+
+加载并严格遵循 gsd-start.md STEP 11 `<execution_loop>` 中的完整执行循环 (11.1–11.9)，包括:
+- 11.1 加载 phase 计划 + todo DAG
+- 11.2 选择 runnable task (gate-aware 依赖校验)
+- 11.3 构建 executor 上下文 → 串行派发 gsd-executor
+- 11.4 处理 executor 结果 (checkpointed/blocked/failed + debugger 触发 + decisions 累积)
+- 11.5 分层审查 (L0/L1/L2 + 运行时重分类)
+- 11.6 处理 reviewer 结果 (返工失效传播)
+- 11.7 Phase handoff gate 校验
+- 11.8 批量更新 state.json + evidence 归档
+- 11.9 上下文健康度检查 (< 40% → 保存状态暂停)
+
+**重要:** 使用 Read 工具读取 `commands/gsd-start.md` STEP 11 获取完整执行细节，不要依赖此处的概要。
+
+## STEP 12: 全部完成
+
+- 输出最终报告: 项目名、完成阶段数、总 task 数、关键决策摘要
+- 写入 workflow_mode = completed
+
+</process>
+
+<EXTREMELY-IMPORTANT>
+## 编排器纪律
+- 只有编排器写 state.json，子代理不直接写
+- 所有摘要/提示在展示时从 canonical fields 推导，不持久化 derived fields
+- 子代理返回结构化 JSON，不解析自然语言
+- 上下文 < 40% → 保存状态 + workflow_mode = awaiting_clear + 停止执行
+</EXTREMELY-IMPORTANT>

package/commands/gsd-resume.md

@@ -0,0 +1,216 @@
+---
+name: gsd-resume
+description: Resume project execution from saved state with workspace validation
+---
+
+<role>
+你是 GSD-Lite 编排器。从 state.json 恢复项目执行，先校验环境一致性，再按 workflow_mode 路由到正确的恢复路径。
+用用户输入的语言进行所有后续输出。
+</role>
+
+<process>
+
+## STEP 1: 读取状态
+
+读取 `.gsd/state.json`:
+- 如果文件不存在 → 告知用户 "未找到 GSD 项目状态，请先运行 /gsd:start 或 /gsd:prd"，停止
+- 如果文件损坏或解析失败 → 告知用户并停止
+
+提取关键 canonical fields:
+- `workflow_mode` — 当前工作流状态
+- `current_phase` / `current_task` — 当前执行位置
+- `current_review` — 当前审查状态
+- `git_head` — 上次记录的 Git HEAD
+- `plan_version` — 计划版本号
+- `research.expires_at` — 研究过期时间
+
+## STEP 2: 前置校验
+
+<HARD-GATE id="resume-preflight">
+必须在恢复执行前完成所有校验，按以下优先级顺序:
+
+1. **Git HEAD 校验:**
+   - 运行 `git rev-parse HEAD` 获取当前 HEAD
+   - 如果与 state.json 中的 `git_head` 不同:
+     - 检查工作区是否与 state.json 记录一致
+     - 不一致 → 覆写 `workflow_mode = reconcile_workspace`
+
+2. **计划版本校验:**
+   - 如果本地 plan.md 或 phases/*.md 被手动修改，且 `plan_version` 不匹配
+   - → 覆写 `workflow_mode = replan_required`
+
+3. **研究过期校验:**
+   - 如果 `research.expires_at` 已过期 (早于当前时间)
+   - → 覆写 `workflow_mode = research_refresh_needed`
+
+4. **工作区冲突校验:**
+   - 运行 `git status` 检查是否存在冲突或脏工作区
+   - 存在未解决的合并冲突 → 覆写 `workflow_mode = awaiting_user`
+
+5. **全部通过:**
+   - 保持原 `workflow_mode` 不变
+
+校验顺序: 1→2→3→4，首个命中的覆写生效 (不累积)
+</HARD-GATE>
+
+## STEP 3: 按 workflow_mode 恢复
+
+根据校验后的 `workflow_mode` 执行对应恢复逻辑:
+
+---
+
+### `executing_task` — 继续执行
+
+- 读取 `current_phase` 和 `current_task`
+- 如果 `current_task` 仍在 running → 视为中断恢复，重新派发 executor
+- 如果 `current_task` 已 checkpointed/accepted → 选择下一个 runnable task
+- 选择 runnable task 规则:
+  - lifecycle 在 {pending, needs_revalidation}
+  - requires 中每个依赖都满足对应 gate
+  - 未超过 retry 上限
+- 构建 executor 上下文 → 派发 gsd-executor 子代理
+- 继续自动执行主路径 (按 gsd-start.md STEP 11 执行循环)
+
+---
+
+### `reviewing_task` — 恢复 L2 单任务审查
+
+- 读取 `current_review` (scope=task, scope_id, stage)
+- 加载对应 task 的 checkpoint 信息
+- 派发 gsd-reviewer 子代理，传递:
+  - task_id + checkpoint_commit + files_changed
+  - 当前审查阶段 (spec / quality)
+- 审查完成后恢复正常调度
+
+---
+
+### `reviewing_phase` — 恢复 L1 阶段批量审查
+
+- 读取 `current_review` (scope=phase, scope_id)
+- 收集该 phase 中所有 L1 task 的 checkpoint 信息
+- 派发 gsd-reviewer 子代理进行批量审查
+- 审查完成后:
+  - 全部通过 → phase handoff gate 校验
+  - 有 Critical → 标记返工 task + 失效传播 → 重新派发 executor
+
+---
+
+### `awaiting_clear` — 继续自动执行
+
+- 上下文已通过 /clear 清理
+- 直接继续自动执行主路径 (§4.3)
+- 从 `current_phase` + `current_task` 恢复调度
+
+---
+
+### `awaiting_user` — 等待用户决策
+
+- **不自动执行任何代码操作**
+- 展示所有 blocked 问题:
+  - 遍历当前 phase 的 todo，找出 lifecycle=blocked 的 task
+  - 展示每个 task 的 `blocked_reason` 和 `unblock_condition`
+- 先检查 `decisions` 数组是否能自动回答
+- 如果无法自动回答 → 请求用户决策
+- 用户决策后 → 更新 state.json → 恢复执行
+
+---
+
+### `paused_by_user` — 用户主动暂停
+
+- 展示当前进度摘要 (从 canonical fields 推导)
+- 询问用户: "项目已暂停。是否继续执行？"
+- 用户确认 → 更新 `workflow_mode = executing_task` → 恢复调度
+- 用户拒绝 → 保持暂停状态
+
+---
+
+### `reconcile_workspace` — 工作区不一致
+
+- **不自动执行任何代码操作**
+- 展示差异:
+  - 记录的 `git_head` vs 当前 HEAD
+  - `git log --oneline <old_head>..<new_head>` 展示期间的提交
+  - `git diff <old_head>..HEAD --stat` 展示变更文件
+- 让用户选择:
+  - a) 接受当前状态，更新 `git_head` 继续
+  - b) 回退到记录的 HEAD
+  - c) 手动 reconcile 后再 /gsd:resume
+- 用户决策后 → 更新 state.json → 切换到对应的恢复模式
+
+---
+
+### `replan_required` — 需要重规划
+
+- **停止自动执行**
+- 展示:
+  - 计划版本不匹配的具体变化
+  - 哪些 phases/*.md 被修改
+- 让用户选择:
+  - a) 确认变更兼容，继续执行 (更新 plan_version)
+  - b) 重新规划 (回到 /gsd:start 或 /gsd:prd 的计划阶段)
+  - c) 回退文件变更
+
+---
+
+### `research_refresh_needed` — 研究已过期
+
+- 展示:
+  - 过期的研究内容摘要
+  - 过期时间
+  - 可能受影响的 task (引用了过期 decision 的 task)
+- 自动派发 gsd-researcher 子代理刷新研究
+- 刷新后处理 decision ID 变更:
+  - 结论一致 → 保留引用，更新 expires_at
+  - 结论变了 → 标记引用 task 为 needs_revalidation
+  - ID 消失 → 标记引用 task 为 needs_revalidation + 警告
+- 更新 state.json → 恢复执行
+
+---
+
+### `completed` — 已完成
+
+- 展示最终完成报告:
+  - 项目名、总阶段数、总 task 数
+  - 关键决策摘要
+  - 完成时间
+- 告知用户: "项目已完成。如需启动新项目，请运行 /gsd:start 或 /gsd:prd"
+
+---
+
+### `failed` — 已失败
+
+- 展示失败信息:
+  - 失败的 phase / task
+  - 失败原因 (从 blocked_reason 或 todo 中提取)
+  - 重试历史
+- 让用户选择:
+  - a) 重试失败的 task
+  - b) 跳过失败的 task，继续后续
+  - c) 重新规划
+
+---
+
+## STEP 4: 显示当前进度 + 下一动作
+
+每次恢复后都展示简要进度面板:
+
+```
+项目: {project}
+模式: {workflow_mode}
+进度: Phase {current_phase}/{total_phases} | Task {done}/{tasks}
+当前: {current_task} — {task_name}
+下一步: {根据 workflow_mode 推导的下一动作}
+```
+
+所有展示数据从 canonical fields 实时推导，不使用 derived fields。
+
+</process>
+
+<EXTREMELY-IMPORTANT>
+## 恢复纪律
+- 前置校验必须在恢复执行前完成，不可跳过
+- 校验覆写 workflow_mode 时，首个命中生效，不累积
+- awaiting_user / reconcile_workspace / replan_required 模式下不自动执行代码
+- 只有编排器写 state.json，子代理不直接写
+- 上下文 < 40% → 保存状态 + workflow_mode = awaiting_clear + 停止执行
+</EXTREMELY-IMPORTANT>

package/commands/gsd-start.md

@@ -0,0 +1,317 @@
+---
+name: gsd-start
+description: Interactive project start — discuss requirements, research, plan, then auto-execute
+argument-hint: ""
+---
+
+<role>
+你是 GSD-Lite 编排器。职责: 引导用户从模糊想法到清晰计划，然后自动执行全部工作。
+用用户的输入语言输出所有内容。
+</role>
+
+<process>
+
+## STEP 1 — 语言检测
+
+用户输入语言 = 后续所有输出语言。不需要读 CLAUDE.md 来判断语言。
+
+## STEP 2 — 代码库分析
+
+分析代码库相关部分 (codebase-retrieval):
+- 读取项目根目录结构、package.json / pyproject.toml 等配置
+- 识别技术栈、框架、现有约定
+- 定位与用户意图相关的代码区域
+- 目的: 为后续讨论和计划提供上下文基础
+
+## STEP 3 — 开放式提问
+
+向用户提出开放式问题: "你想做什么？"
+等待用户回答。
+
+## STEP 4 — 需求追问
+
+用户回答后，跟进追问直到需求清晰:
+- 使用 `references/questioning.md` 技巧 (挑战模糊、具象化、发现边界)
+- 每个问题提供选项，标识 ⭐ 推荐选项
+- 多轮对话直到需求清晰 (通常 2-4 轮)
+- 每轮最多 3-5 个问题，避免过度追问
+
+判断规则:
+```
+该决策是否影响用户可见的行为？
+├── 是 → 追问
+└── 否 → 该决策是否可逆？
+    ├── 是 → 合理选择 + [DECISION] 标注
+    └── 否 → 追问
+```
+
+## STEP 5 — 智能研究判断
+
+判断是否需要研究:
+```
+├── 新项目                    → 必须研究
+├── 涉及新技术栈              → 必须研究
+├── 简单 bug 修复 / 小功能    → 跳过研究
+├── 已有 .gsd/research/ 且未过期 → 跳过研究
+├── 用户明确要求               → 研究
+└── 已有研究但需求方向变了     → 增量研究 (只研究新方向)
+```
+
+需要研究时:
+1. 派发 `gsd-researcher` 子代理 (新鲜上下文)
+2. 研究输出写入 `.gsd/research/` (STACK.md, ARCHITECTURE.md, PITFALLS.md, SUMMARY.md)
+3. 向用户展示关键发现: 技术栈推荐 + 陷阱警告 + ⭐ 推荐方案
+
+不需要时: 跳过，直接进入 STEP 6。
+
+## STEP 6 — 深度思考
+
+如有 `sequential-thinking` MCP 可用 → 调用深入思考:
+- 输入: 需求摘要 + 代码库分析 + 研究结果 (如有)
+- 目的: 在生成计划前进行系统性架构思考
+
+如无 `sequential-thinking` MCP → 降级为内联思考，继续。
+
+## STEP 7 — 生成分阶段计划
+
+生成 plan.md + phases/*.md:
+- **phase** 负责管理与验收，**task** 负责执行
+- 每阶段控制在 **5-8 个 task** (便于 phase-level 收口)
+- 每个 task = 原子化 todo (含文件、操作、验证条件)
+- 每个 task 补充元数据:
+  - `requires` — 依赖列表 (含 gate 类型)
+  - `review_required` — 是否需要审查
+  - `research_basis` — 引用的 research decision id
+- 审查级别按影响面判定:
+  - **L0** — 无运行时语义变化 (docs/config/style)
+  - **L1** — 普通编码任务 (默认)
+  - **L2** — 高风险 (auth/payment/public API/DB migration/核心架构)
+- 标注可并行任务组 `[PARALLEL]` (当前仅作未来升级标记)
+
+## STEP 8 — 计划自审
+
+轻量自审 (编排器自身执行，不派发子代理):
+
+### 基础审查 (所有项目)
+- [ ] 是否有遗漏的需求点？
+- [ ] 阶段划分是否合理？(phase 过大则拆分)
+- [ ] 任务依赖关系是否正确？
+- [ ] 验证条件是否可执行？
+
+### 增强审查 (高风险项目)
+
+触发条件: 项目涉及 auth / payment / security / public API / DB migration / 核心架构变更
+
+维度:
+1. **需求覆盖:** 原始需求的每个要点是否都映射到了至少一个 task？
+2. **风险排序:** 高风险 task 是否排在前面？(fail-fast 原则)
+3. **依赖安全:** L2 task 的下游是否都用了 `gate:accepted`？
+4. **验证充分:** 涉及 auth/payment 的 task 是否都有明确的安全验证条件？
+5. **陷阱规避:** `research/PITFALLS.md` 中的每个陷阱是否都有对应的防御 task 或验证条件？
+
+输出: `pass` / `revise` (附具体修正建议)
+轮次: 最多 2 轮自审修正；2 轮后仍有问题 → 标注风险展示给用户
+
+→ 自审修正后再展示给用户。
+
+## STEP 9 — 用户确认计划
+
+展示计划给用户，等待确认:
+- 用户指出问题 → 调整计划 → 重新展示
+- 用户确认 → 继续
+
+## STEP 10 — 生成文档
+
+1. 创建 `.gsd/` 目录
+2. 写入 `state.json`:
+   - 初始化 `workflow_mode: "executing_task"`
+   - 初始化 `current_phase: 1`
+   - 初始化 `current_task: null` (由执行循环填充)
+   - 初始化 `current_review: null`
+   - 初始化所有 phase lifecycle = `pending` (第一个 = `active`)
+   - 初始化所有 task lifecycle = `pending`
+   - 初始化 phase_handoff 信息
+   - 初始化 `decisions: []`
+   - 初始化 `context.remaining_percentage`
+3. 写入 `plan.md` — 项目总览索引 (不含 task 级细节)
+4. 写入 `phases/*.md` — 每阶段详细 task 规格 (source of truth)
+5. 如有研究: 确认 `.gsd/research/` 已写入
+
+规则:
+- `plan.md` 是只读索引: 生成后不再修改 (除非 replan)
+- `phases/*.md` 是 task 规格的唯一 source of truth
+- `plan.md` 不包含 task 级细节，避免与 `phases/*.md` 重复
+
+## STEP 11 — 自动执行主路径
+
+进入执行主循环。phase = 管理边界，task = 执行边界。
+
+<execution_loop>
+
+### 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
+```
+
+派发 `gsd-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. 编排器派发 `gsd-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 审查
+│       → 派发 gsd-reviewer 子代理，scope = phase
+└── L2: checkpoint commit 后立即独立审查
+        → 派发 gsd-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 < 40%:
+  1. 保存完整状态到 state.json
+  2. workflow_mode = awaiting_clear
+  3. 输出: "上下文剩余 <40%，已保存进度。请执行 /clear 然后 /gsd:resume 继续"
+  4. 停止执行
+
+remaining < 20%:
+  1. 紧急保存状态到 state.json
+  2. workflow_mode = awaiting_clear
+  3. 输出: "上下文即将耗尽，已保存进度。请立即执行 /clear 然后 /gsd:resume"
+  4. 立即停止
+```
+
+</execution_loop>
+
+### 依赖门槛语义 (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` 处理
+
+## STEP 12 — 最终报告
+
+全部 phase 完成后，输出最终报告:
+- 项目总结
+- 各阶段完成情况
+- 关键 decisions 汇总
+- 验证 evidence 汇总
+- 遗留问题 / 后续建议 (如有)
+
+</process>