Milestone v{VERSION} — Project Summary

Generated: {date} Purpose: Team onboarding and project review

---

1. Project Overview

{From PROJECT.md: "What This Is", core value proposition, target users} {If mid-milestone: note which phases are complete vs in-progress}

2. Architecture & Technical Decisions

{From CONTEXT.md files across phases: key technical choices} {From SUMMARY.md decisions: patterns, libraries, frameworks chosen} {From PROJECT.md: tech stack if documented} Present as a bulleted list of decisions with brief rationale:

• Decision: {what was chosen}
  • Why: {rationale from CONTEXT.md}
  • Phase: {which phase made this decision}

3. Phases Delivered

Phase	Name	Status	One-Liner
{For each phase: number, name, status (complete/in-progress/planned), one_liner from SUMMARY.md}

4. Requirements Coverage

{From REQUIREMENTS.md: list each requirement with status}

• ✅ {Requirement met}
• ⚠️ {Requirement partially met — note gap}
• ❌ {Requirement not met — note reason} {If MILESTONE-AUDIT.md exists: include audit verdict}

5. Key Decisions Log

{Aggregate from all CONTEXT.md sections} {Each decision with: ID, description, phase, rationale}

6. Tech Debt & Deferred Items

{From VERIFICATION.md files: gaps found, anti-patterns noted} {From RETROSPECTIVE.md: lessons learned, what to improve} {From CONTEXT.md sections: ideas parked for later}

7. Getting Started

{Entry points for new contributors:}

• Run the project: {from PROJECT.md or SUMMARY.md}
• Key directories: {from codebase structure}
• Tests: {test command from PROJECT.md or CLAUDE.md}
• Where to look first: {main entry points, core modules}

---

Stats

• Timeline: {start} → {end} ({duration})
• Phases: {count complete} / {count total}
• Commits: {count}
• Files changed: {count} (+{insertions} / -{deletions})
• Contributors: {list}

各章节信息源设计得非常有层次：Overview/Architecture 侧重 PROJECT.md 与跨 phase 的 CONTEXT 决策；Requirements Coverage 用三态（已达成/部分达成/未达成）符号清单映射需求满足度，并在存在审计文件时附上审计结论；Tech Debt 聚合自 VERIFICATION 的缺口与反模式、RETROSPECTIVE 的经验教训、CONTEXT 中被搁置的 `<deferred>` 想法——这套信息源划分与 [state.md 模板](https://gitcode.com/GitHub_Trending/getshi/get-shit-done/blob/dee2434b0ff956547f3741df7a81d2fa23b88f7a/get-shit-done/templates/state.md?utm_source=gitcode_repo_files) 中要求 STATE 反映 `Deferred Items` 的设计一脉相承（该要求本身由 issue #2158 引入，见测试注释）。

## 第六步：写入与提交（Write and Commit）

写入前必须先做**覆盖保护（overwrite guard）**：若 `.planning/reports/MILESTONE_SUMMARY-v${VERSION}.md` 已存在，须询问用户 *"A milestone summary for v{VERSION} already exists. Overwrite it, or view the existing one?"*——选择 "view" 则展示现有文件并跳到交互模式（第八步），选择 "overwrite" 才继续，避免静默覆盖历史报告。

随后创建报告目录并写入：

```bash
mkdir -p .planning/reports

提交时使用 GSD SDK 的 commit 查询接口，仅提交新增的报告文件：

gsd-sdk query commit "docs(v${VERSION}): generate milestone summary for onboarding" --files \
  ".planning/reports/MILESTONE_SUMMARY-v${VERSION}.md"

--files 精确限定提交范围，保证一次里程碑总结不会把其它工作区的改动卷进来。

第七步与第八步：内联呈现与交互式 Q&A

文档写完后要全文内联呈现（而不是只给路径）。随后进入可选交互模式，向用户发出邀请：

"Summary written to .planning/reports/MILESTONE_SUMMARY-v{VERSION}.md. I have full context from the build artifacts. Want to ask anything about the project? Architecture decisions, specific phases, requirements, tech debt — ask away."

交互模式的技术含量在于：模型在前几步已把 CONTEXT.md、SUMMARY.md、VERIFICATION.md 等产物全文读入上下文，因此 Q&A 的回答必须基于已加载产物回答、引用具体文件与决策、并"Stay grounded in what was actually built (not speculation)"——即禁止脱离产物凭空发挥。用户结束问答后，引导下一步操作：/gsd:new-milestone、/gsd:progress，或把总结分享给团队。这也是命令核心 Purpose 的外化：onboarding 不是一次生成，而是一次可追问的上下文交接。

第九步：更新 STATE.md

最后，通过 GSD SDK 的 state 系列查询记录本次会话，保持项目"活记忆"的同步：

gsd-sdk query state.record-session "" \
  "Milestone v${VERSION} summary generated" \
  ".planning/reports/MILESTONE_SUMMARY-v${VERSION}.md"

state.record-session 在仓库 SDK 层有完整实现与注册：见 command-family-handlers.ts 中 'state.record-session': stateRecordSession 的映射、command-manifest.state.ts 中 { family: 'state', canonical: 'state.record-session', aliases: ['state record-session'], mutation: true, outputMode: 'json' } 的契约声明，以及 command-aliases.generated.ts 为其生成的别名 state record-session；其底层行为由 state-mutation.ts 中 state.record-session handler 实现，并有 state-mutation.test.ts 覆盖（例如在 ROADMAP 当前里程碑不一致时保留 milestone 字段等场景）。工作流文档写作时保留了 CJS 与 gsd-sdk query 两种调用形态，测试亦同时接受二者（见 workflow updates STATE.md 断言）。

源码侧的契约验证：一份命令的完整闭环

commands/gsd/milestone-summary.md 并非孤立文档，它与 tests/milestone-summary.test.cjs 形成契约—测试闭环。测试从多个维度守护这条命令的稳定性，可作为实现事实的证据链：

• 命令结构：校验文件存在、name: gsd:milestone-summary、workflow 引用（workflows/milestone-summary.md）、可选 [version] 参数、type: prompt、<success_criteria> 节、context 含 RESEARCH.md；
• 工作流语义：必须引用 ROADMAP/REQUIREMENTS/PROJECT/SUMMARY/VERIFICATION/CONTEXT/RETROSPECTIVE 七类产物；必须写 .planning/reports/MILESTONE_SUMMARY；必须含交互式 Q&A；必须同时处理 archived 与 current 两种状态；必须覆盖全部 7 个章节名；必须通过 state.record-session 更新 STATE；必须有覆盖保护；空 phase 目录不得报错；归档审计文件需检查两处位置；
• 产物发现逻辑：测试以临时工程为夹具，构造 v1.0-ROADMAP/REQUIREMENTS/MILESTONE-AUDIT 归档、三个 phase 目录（产物完整度分别为 4/2/1 种）乃至完全空的 .planning/，验证发现逻辑与优雅降级；
• 输出命名：MILESTONE_SUMMARY-v{version}.md 必须匹配 ^MILESTONE_SUMMARY-v\d+\.\d+\.md$ 的命名模式；
• 审计模块联动（#2158）：同文件还验证了 auditOpenArtifacts/formatAuditReport（实现位于 get-shit-done/bin/lib/audit.cjs）、complete-milestone 的 pre_close_artifact_audit 门禁、verify-work 的 phase 产物检查等相邻能力。

在项目官方文档中，本命令同时被收录于 docs/COMMANDS.md（/gsd-milestone-summary，参数表注明 version 可选、产物路径为 .planning/reports/MILESTONE_SUMMARY-v{version}.md，给出无参与带版本两种调用示例）与 docs/FEATURES.md（Feature 50，需求编号 REQ-SUMMARY-01/02/03，分别约束"聚合 phase 计划/总结/验证结果"、"同时支持当前与归档里程碑"、"产出单一可导航文档"）。中/日/韩等语言文档目录（如 docs/ja-JP/COMMANDS.md、docs/zh-CN）也同步收录，便于国际化团队查阅。

常见用法速查与最佳实践

基本调用（在 GSD 项目根目录执行）：

/gsd-milestone-summary              # 总结当前/最新里程碑
/gsd-milestone-summary v1.0         # 总结指定版本里程碑