GSD 里程碑审计（audit-milestone）：基于三源交叉验证与集成检查的完成度验收工作流

GSD 里程碑审计（audit-milestone）：基于三源交叉验证与集成检查的完成度验收工作流

【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done

导读

audit-milestone是 get-shit-done（GSD）体系中负责"里程碑归档前最后一道质量闸门"的工作流：它在阶段级验证（execute-phase期间的VERIFICATION.md）之上，聚合技术债与延期缺口，派生集成检查子代理校验跨阶段接线（cross-phase wiring）与端到端流程，并通过 REQUIREMENTS.md 追踪表、阶段 VERIFICATION.md、SUMMARY.md 前置元数据三方交叉验证，判定里程碑是否真正达成其"完成定义（definition of done）"。读完本文，你将掌握该工作流的完整执行步骤、三源状态判定矩阵、FAIL 门禁与孤儿需求检测规则、Nyquist 合规发现机制，以及 passed / gaps_found / tech_debt 三种结果的后续路由与修复闭环。

一、工作流定位：审计发生在哪个环节

在 GSD 的阶段链中，audit-milestone通常紧跟在阶段执行与验证之后、归档（complete-milestone）之前。其输入是每个阶段执行完毕后生成的VERIFICATION.md（阶段验证报告），核心职责有三：

1. 聚合各阶段的验证结论（通过/有缺口）与技术债、延期项；
2. 检查跨阶段集成与端到端（E2E）流程，确认"组件之间真的接上了"，而不只是"每个阶段各自看起来完整"；
3. 评估需求覆盖率，确认里程碑的 definition of done 是否达成。

该工作流的命令入口定义在 commands/gsd/audit-milestone.md，其执行上下文直接引用本工作流文件；命令元数据声明requires: [execute-phase]，即只有先完成阶段执行才允许运行审计，同时允许[version]可选参数（缺省时自动检测当前里程碑）。命令级目标（objective）原文强调："This command IS the orchestrator"——审计是编排者，自身读取已有验证产物，并把跨阶段接线检查委托给gsd-integration-checker子代理。

二、步骤 0～1：初始化里程碑上下文与范围界定

2.1 初始化上下文

工作流第一步通过gsd-sdk查询初始化数据，获取当前里程碑的全局上下文：

INIT=$(gsd-sdk query init.milestone-op) if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi AGENT_SKILLS_CHECKER=$(gsd-sdk query agent-skills gsd-integration-checker)

从初始化 JSON 中提取：milestone_version（里程碑版本）、milestone_name（名称）、phase_count（阶段数）、completed_phases（已完成阶段）、commit_docs（提交文档开关）。init.milestone-op是 SDK 查询注册表中的正式查询名——在 sdk/src/query/command-family-handlers.ts 中可以看到phases.list与init.milestone-op等查询被统一注册到命令族分发器。

随后解析集成检查子代理的模型配置：

integration_checker_model=$(gsd-sdk query resolve-model gsd-integration-checker --raw)

resolve-model会依据当前配置的模型目录（model catalog）解析出该子代理应使用的模型名，保证审计派生的子代理与项目配置保持一致。

2.2 界定里程碑范围

# Get phases in milestone (sorted numerically, handles decimals) gsd-sdk query phases.list

范围界定四要素：

• 从命令行参数解析版本号，或从ROADMAP.md检测当前版本；
• 识别范围内所有阶段目录；
• 从ROADMAP.md提取里程碑的 definition of done；
• 从REQUIREMENTS.md提取映射到本里程碑的需求。

phases.list按数值排序并支持小数阶段号（如2.1），这是 GSD 计划体系的常见形态：阶段可插拔（/gsd:phase --insert插入缺口关闭阶段），因此审计必须能处理非连续、含小数的阶段编号序列。

三、步骤 2：读取全部阶段验证报告（VERIFICATION.md）

对范围内每个阶段，使用find-phase解析其目录——该查询的关键能力是归档回退：当前阶段目录找不到时，会按版本倒序在.planning/milestones/v*-phases/归档目录中继续查找，这对审计已完成/已归档阶段至关重要：

PHASE_INFO=$(gsd-sdk query find-phase 01 --raw) # Extract directory from JSON, then read VERIFICATION.md from that directory # Repeat for each phase number from ROADMAP.md

从源码实现看，sdk/src/query/phase.ts 的findPhase处理器会先探测当前 phases 目录，再遍历v[\d.]+-phases归档目录（按版本号倒序），并在未命中时返回searched_directories列表用于诊断；同文件的getPhaseFileStats（sdk/src/query/phase.ts）会为每个阶段目录统计plans、summaries、has_verification（是否存在*-VERIFICATION.md或VERIFICATION.md）等属性，审计方可用这些字段快速预判哪些阶段缺少验证报告。

从每份VERIFICATION.md提取以下字段：

• Status（状态）：passed或gaps_found；
• Critical gaps（关键缺口）：若存在，即为阻塞项（blocker）；
• Non-critical gaps（非关键缺口）：技术债、延期项、警告；
• Anti-patterns（反模式）：TODOs、stub、占位实现；
• Requirements coverage（需求覆盖）：哪些需求已满足、哪些被阻塞。

硬性规则：若某个阶段缺少VERIFICATION.md，标记为 "unverified phase"，直接视为阻塞项（blocker）——没有验证报告的阶段不允许"蒙混过关"进入里程碑级结论。

VERIFICATION.md的生成格式由 get-shit-done/templates/verification-report.md 定义，其 frontmatter 形如：

--- phase: 03-chat verified: 2025-01-15T14:30:00Z status: passed | gaps_found | human_needed score: N/M must-haves verified ---

模板中的"关键链路验证（Key Link Verification）"表（From/To/Via/Status/Details）正是审计读取跨阶段接线证据的第一手来源，例如：Chat.tsx → /api/chat → fetch in useEffect → ✓ WIRED。

四、步骤 3：派生集成检查子代理（gsd-integration-checker）

在收集齐阶段上下文后，从REQUIREMENTS.md追踪表提取本里程碑所有阶段的 REQ-ID 集合MILESTONE_REQ_IDS，然后派生集成检查子代理：

Agent( 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. ${AGENT_SKILLS_CHECKER}", subagent_type="gsd-integration-checker", model="{integration_checker_model}" )

ORCHESTRATOR RULE — CODEX RUNTIME：调用Agent()后立即停止当前任务的所有工作，在子代理运行期间不得再读取文件、编辑代码或运行相关测试，等待子代理返回结果。这是为了防止重复劳动、冲突编辑与上下文浪费；子代理返回后才继续。

被派生的gsd-integration-checker（定义见 agents/gsd-integration-checker.md）是一个持有"对抗性立场"的检查器，其核心信条是"Existence ≠ Integration"（存在不等于集成）：文件存在是阶段级事实，文件之间真正连接才是集成级事实。其检查维度包括：

• Exports → Imports：阶段 1 导出getCurrentUser，阶段 3 是否真的导入并调用；
• APIs → Consumers：/api/users路由存在，是否真的有消费方在 fetch；
• Forms → Handlers → DB → Display：完整数据链路逐环追踪，不只看第一跳；
• Auth protection：敏感页面是否真的做了鉴权校验与未登录重定向。

检查结果按BLOCKER（跨阶段连接缺失/断裂、E2E 流程无法完成）与WARNING（连接存在但脆弱、边界情况不完整）两级分类，并要求输出结构化报告（wiring summary、API coverage、auth protection、E2E flows、per-requirement 的 Requirements Integration Map）。审计方必须把每个集成发现映射到受影响的需求 ID——这是把"代码接线问题"翻译成"需求未达成证据"的关键。

五、步骤 4～5：三源交叉验证需求覆盖率

5.1 三源交叉引用（3-Source Cross-Reference）

对每个需求，审计方必须交叉核对三个独立来源：

5a. REQUIREMENTS.md 追踪表：提取映射到里程碑阶段的所有 REQ-ID——需求 ID、描述、指派阶段、当前状态、勾选状态（[x]vs[ ]）。

5b. 阶段 VERIFICATION.md 需求表：从每个阶段的验证报告中提取展开的需求表（Requirement | Source Plan | Description | Status | Evidence），并映射回 REQ-ID。如 get-shit-done/templates/verification-report.md 中所示格式：

5c. SUMMARY.md 前置元数据：用脚本提取每个阶段 SUMMARY 的requirements-completed字段：

for summary in .planning/phases/*-*/*-SUMMARY.md; do [ -e "$summary" ] || continue gsd-sdk query summary-extract "$summary" --fields requirements_completed --pick requirements_completed done

5.2 状态判定矩阵

5.3 FAIL 门禁与孤儿需求检测

• FAIL 门禁（REQUIRED）：任何unsatisfied需求必须强制里程碑审计状态为gaps_found；
• 孤儿检测（Orphan detection）：存在于 REQUIREMENTS.md 追踪表、但在所有阶段 VERIFICATION.md 中均未出现（即从未被任何阶段验证过）的需求，标记为 orphaned，并按unsatisfied处理——"被指派过但从未被验证"同样是失职。

5.4 步骤 5.5：Nyquist 合规发现（可选）

当workflow.nyquist_validation配置未显式设为false时（缺省即启用），审计还需扫描每个阶段的*-VALIDATION.md：

NYQUIST_CONFIG=$(gsd-sdk query config-get workflow.nyquist_validation --raw 2>/dev/null)

若为false则整节跳过。对每个阶段的*-VALIDATION.md解析 frontmatter（nyquist_compliant、wave_0_complete），并按条件归类：

归类结果写入审计 YAML：nyquist: { compliant_phases, partial_phases, missing_phases, overall }。注意：审计阶段只做"发现"，绝不自动调用/gsd:validate-phase——补验是后续路由中由用户决策的动作。

六、步骤 6：聚合生成 v{version}-MILESTONE-AUDIT.md

审计结论写入.planning/v{version}-MILESTONE-AUDIT.md（测试 tests/enh-2448-artifact-registry.test.cjs 将该命名确认为 canonical 规划文件，如v1.0-MILESTONE-AUDIT.md、v2.3.1-MILESTONE-AUDIT.md，且不会被 lint 误报为过期规划文件）。报告采用"YAML frontmatter + 完整 Markdown 正文"结构：

--- milestone: {version} audited: {timestamp} status: passed | gaps_found | tech_debt scores: requirements: N/M phases: N/M integration: N/M flows: N/M gaps: # Critical blockers requirements: - id: "{REQ-ID}" status: "unsatisfied | partial | orphaned" phase: "{assigned phase}" claimed_by_plans: ["{plan files that reference this requirement}"] completed_by_plans: ["{plan files whose SUMMARY marks it complete}"] verification_status: "passed | gaps_found | missing | orphaned" evidence: "{specific evidence or lack thereof}" integration: [...] flows: [...] tech_debt: # Non-critical, deferred - 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—— 无阻塞项，但累积的延期项需要审阅。

注意gaps.requirements中每个需求对象都包含claimed_by_plans与completed_by_plans两个证据数组：前者记录哪些计划文件声称覆盖了该需求，后者记录哪些计划的 SUMMARY 标记其已完成——这与三源交叉验证一一对应，使得"声称完成"与"实际完成"之间的落差一目了然。

七、步骤 7：结果呈现与后续路由（offer_next）

审计方按状态直接输出路由模板（Markdown，非代码块）。三种分支要点如下：

7.1 passed：通过并进入归档

## ✓ Milestone {version} — Audit Passed **Score:** {N}/{M} requirements satisfied **Report:** .planning/v{version}-MILESTONE-AUDIT.md All requirements covered. Cross-phase integration verified. E2E flows complete.

后续动作：/clear后运行/gsd:complete-milestone {version}归档并打 tag。

7.2 gaps_found：缺口关闭闭环

输出 Unsatisfied Requirements（按 REQ-ID 列出原因）、Cross-Phase Issues（{from} → {to}: {issue}）、Broken Flows（{flow name}: breaks at {step}）与 Nyquist Coverage 表。修复闭环是"先补验、后插阶段"：

• 对 Nyquist 覆盖缺口表中的阶段，优先运行/gsd:validate-phase {N}（若 SECURITY.md 被标记还需/gsd:secure-phase {N}）——补验可能"追溯性"关闭缺口而无需新阶段；
• 对仍存在的缺口，每个缺口（或相关缺口组）插入一个关闭阶段，走标准阶段链：

/clear then: /gsd:phase --insert <N> "Close gap: <REQ-ID> — <description>" /gsd:discuss-phase <N> /gsd:plan-phase <N> /gsd:execute-phase <N>

也可用cat .planning/v{version}-MILESTONE-AUDIT.md查看完整报告；/gsd:complete-milestone {version}则代表"接受技术债继续推进"的兜底选项。

7.3 tech_debt：技术债审阅双选项

无阻塞项但累积了延期债务时：

• 选项 A：/gsd:complete-milestone {version}—— 接受债务，记入 backlog 跟踪；
• 选项 B：插入清理阶段处理债务后再归档，同样走/gsd:phase --insert <N> "Address tech debt: <area>"→ discuss → plan → execute 标准链。

八、成功标准（success_criteria）与质量底线

工作流以可勾选的验收清单收尾，可作为审计质量的检查基准：

• 里程碑范围已识别
• 所有阶段 VERIFICATION.md 已读取
• 每个阶段的 SUMMARY.mdrequirements-completedfrontmatter 已提取
• REQUIREMENTS.md 追踪表已解析出全部里程碑 REQ-ID
• 三源交叉引用完成（VERIFICATION + SUMMARY + 追踪表）
• 孤儿需求已检测（在追踪表中但所有 VERIFICATION 中均缺失）
• 技术债与延期缺口已聚合
• 集成检查器已携带里程碑需求 ID 派生
• v{version}-MILESTONE-AUDIT.md已生成，含结构化需求缺口对象
• FAIL 门禁已强制——任何 unsatisfied 需求迫使状态为 gaps_found
• 所有里程碑阶段已扫描 Nyquist 合规（若启用）
• 缺失 VALIDATION.md 的阶段已标记 validate-phase 建议
• 结果已附带可执行的下一步呈现

九、设计要点总结

• 两级验证分层：阶段级验证（VERIFICATION.md，验证"组件存在且自洽"）与里程碑级审计（本工作流，验证"组件相互连接且需求达成"）互为补充；集成检查器明确警示："Individual phases can pass while the system fails"。
• 证据优先于声称：三源交叉验证与claimed_by_plans/completed_by_plans证据数组，让"计划声称"与"总结标记"之间的不一致显式暴露，而非静默放行。
• FAIL 快、放行慢：任何 unsatisfied 或 orphaned 需求都强制 gaps_found；而 tech_debt 与 passed 的边界在于是否存在阻塞项。
• 发现与修复分离：审计只产出现状（含 Nyquist 发现），修复动作（validate-phase、secure-phase、插入关闭阶段）全部交由结果路由中的明确命令闭环，避免审计代理越权改动代码。

该工作流与相邻工作流协同：阶段验证细节见 get-shit-done/workflows/validate-phase.md（Nyquist 补验流程），归档动作见 commands/gsd/complete-milestone.md，缺口规划见 get-shit-done/workflows/plan-milestone-gaps.md。理解审计工作流，是掌握 GSD"规划—执行—验证—审计—归档"完整闭环的最后一块拼图。

【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done