【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载导读本文围绕 gsd-core 仓库中一次针对健康诊断规则 W019 的修复展开RETROSPECTIVE.md被正式写入CANONICAL_EXACT注册表位于 src/artifacts.cts使得gsd-health底层为validate health不再将其标记为「未识别的.planning/根文件」并抛出 W019 告警。读完本文你将理解 GSD 的 canonical artifact 注册机制、W019 规则的判定逻辑、RETROSPECTIVE.md作为/gsd-complete-milestone活文档的产生与消费链路以及如何用测试固化这类注册变更。1. 修复背景W019 的误报问题在.changeset/archived/3198-retrospective-canonical.md记录的变更中一行描述点名了两个核心事实gsd-health曾对RETROSPECTIVE.md抛出 W019「未识别文件」告警修复方式是把它注册进CANONICAL_EXACT与它作为/gsd-complete-milestone产出活文档living artifact的既有地位对齐。W019 属于健康诊断规则组「Milestone archive root hygiene」与 W018 同组定义在 src/health-diagnostic-rules/milestone-archive-hygiene.cts。该规则的职责是遍历.planning/根目录下的所有.md文件凡是不在 canonical 工件清单之内的一律发出 W019 告警并附带修复建议Unrecognized .planning/ file: {filename} — not a canonical GSD artifact建议「Move to .planning/milestones/ archive subdir or delete if stale. See templates/README.md for the canonical artifact list.」问题在于RETROSPECTIVE.md是/gsd-complete-milestone在每次里程碑收尾时正式产出并持续维护的文档但它此前并不在CANONICAL_EXACT集合里于是每次运行健康检查都会收到一条「请归档或删除」的错误建议——明明该文件是工作流主动创建的却被告知它不是规范工件属于典型的自产文件误报。2. 核心机制Canonical Artifact 注册表2.1CANONICAL_EXACT精确匹配清单修复落点位于 src/artifacts.cts 的CANONICAL_EXACT集合。该文件头部注释明确说明其定位Enumerates the file names that gsd workflows officially produce at the .planning/ root level. Used by gsd-health (W019) to flag unrecognized files so stale or misnamed artifacts dont silently mislead agents or reviewers. Add entries here whenever a new workflow produces a .planning/ root file.注册表分为两套匹配规则精确匹配CANONICAL_EXACT——目前包含 16 个条目文件名产出方 / 说明PROJECT.md/gsd:new-project项目身份与目标ROADMAP.md/gsd:new-milestone、/gsd:new-projectSTATE.md/gsd:new-project、gsd-health --repairREQUIREMENTS.md/gsd:new-milestoneMILESTONES.md/gsd:complete-milestoneBACKLOG.md/gsd-add-backlogLEARNINGS.md/gsd:extract-learnings等THREADS.md/gsd:threadconfig.json/gsd:new-projectCLAUDE.md/gsd-profile自动组装RETROSPECTIVE.md/gsd:complete-milestone本次修复新增语义WINDOWS.mdbroken-windows ledgersrc/broken-windows.cts#3224STATE-ARCHIVE.mdstate.cts的cmdStatePrunemilestone.locksrc/milestone-lock.cts#3311state.jsonsrc/state-contract.cts步骤边界发布#3227skill-manifest.jsoninit.cts的cmdSkillManifest --write#3964PATTERNS.md跨阶段模式沉淀#4282区别于阶段内NN-PATTERNS.md注意RETROSPECTIVE.md在源码中位于第 26 行紧邻CLAUDE.md与WINDOWS.md之间正是本次 changesetPR 3200所引入的登记。模式匹配CANONICAL_PATTERNS——针对带版本戳的文件名/^v\d\.\d(?:\.\d)?-MILESTONE-AUDIT\.md$/i, // gsd-complete-milestone (pre-archive) /^v\d\.\d(?:\.\d)?-.*\.md$/i, // other version-stamped planning docs2.2 判定函数isCanonicalPlanningFile注册表的唯一消费入口是isCanonicalPlanningFile(filename)src/artifacts.cts它按「先精确、后正则」的顺序判定export function isCanonicalPlanningFile(filename: string): boolean { if (CANONICAL_EXACT.has(filename)) return true; for (const pattern of CANONICAL_PATTERNS) { if (pattern.test(filename)) return true; } return false; }三个关键约束值得注意只接受 basename调用方传入的是不带路径的文件名路径处理在上层完成大小写敏感RETROSPECTIVE.md合法而retrospective.md或RETROSPECTIVE.MD均会被拒绝测试中有state.md判false的用例佐证空串与无关文件返回false保证 W019 对任何未登记文件照常触发。3. W019 规则的实现链路W019 的检查函数checkW019位于 src/health-diagnostic-rules/milestone-archive-hygiene.cts实现逻辑清晰function checkW019(snapshot: PlanningSnapshot): Diagnostic[] { const diagnostics: Diagnostic[] []; for (const filename of snapshot.planningRootFiles.value) { if (!filename.endsWith(.md)) continue; if (isCanonicalPlanningFile(filename)) continue; diagnostics.push({ code: W019, severity: SEVERITY.WARNING, message: Unrecognized .planning/ file: ${filename} — not a canonical GSD artifact, remedy: adviseRemedy( Move to .planning/milestones/ archive subdir or delete if stale. See templates/README.md for the canonical artifact list., ), }); } return diagnostics; }从实现可以提炼出几条明确的规则语义只检查.planning/根目录文件清单来自 planning snapshot 的planningRootFiles阶段子目录.planning/phases/NN-name/内的文件不在检查范围每个未识别文件产生一条独立告警与 W018 的聚合式报告不同W019 是「一文件一告警」测试中两个杂散文件会产生两条 W019 即为此意非自动修复repairable: false规则表同文件第 98-113 行中 W019 明确标注repairable: false健康检查的--repair不会自动移动或删除文件需要人工依据建议处理。该文件头部还注明了来源规则从cmdValidateHealth原src/verify.cts行为保持地移植而来并遵循 ADR-457「build-at-publish」策略——源码是src/health-diagnostic-rules/milestone-archive-hygiene.cts编译产物为 gitignored 的bin/lib/health-diagnostic-rules/milestone-archive-hygiene.cjs。4. RETROSPECTIVE.md 的生产与消费为什么它必须是 canonical要理解本次修复的必要性需要看清RETROSPECTIVE.md在完整里程碑收尾工作流中的角色。4.1 模板活文档的结构模板位于 gsd-core/templates/retrospective.md开篇即声明其定位A living document updated after each milestone. Lessons feed forward into future planning.模板包含两大板块单里程碑板块## Milestone: v{version} — {name}内含 Shipped/Phases/Plans/Sessions 元信息以及What Was Built、What Worked、What Was Inefficient、Patterns Established、Key Lessons、Cost Observations六个小节跨里程碑趋势板块## Cross-Milestone Trends用表格沉淀Process Evolution、Cumulative Quality与Top Lessons (Verified Across Milestones)。4.2 工作流每次收尾都会写入在 gsd-core/workflows/complete-milestone.md 的write_retrospective步骤中流程完整定义了该文件的维护方式探测ls .planning/RETROSPECTIVE.md 2/dev/null || true检查文件是否存在分支处理已存在则读取并在## Cross-Milestone Trends之前追加新里程碑板块不存在则从模板retrospective.md创建数据采集从SUMMARY.md提取交付物、从VERIFICATION.md提取验证分数与缺口、从UAT.md提取测试结果、从 git log 统计提交与时间线再结合里程碑过程反思提交gsd_run query commit docs: update retrospective for v${VERSION} --files .planning/RETROSPECTIVE.md将更新固化到 git 历史。同工作流的 checklist第 727 行也把RETROSPECTIVE.md updated with milestone section列为收尾必检项。这意味着只要完整执行过/gsd-complete-milestone.planning/RETROSPECTIVE.md就必然存在——它既不是临时草稿也不是残留杂物而是一个被工作流持续维护的规范产物。4.3 消费里程碑总结的输入源在 gsd-core/workflows/milestone-summary.md 中RETROSPECTIVE.md被列为「Always available」的三个路径之一与PROJECT.md、STATE.md并列其 lessons learned 是生成里程碑总结时「what to improve」部分的内容来源。此外 gsd-core/workflows/help/modes/full.md 在.planning/目录速览里也将其标注为 Living retrospective (updated per milestone)。至此结论闭环一个被工作流主动创建、每次收尾持续更新、被其他工作流当作权威输入读取的文档理应属于 canonical artifact 清单。此前它不在CANONICAL_EXACT中导致gsd-health给出「请归档或删除」的误导性建议——这正是本次 changeset 修复的实质。5. 修复的验证测试与文档联动5.1 注册表单元测试tests/artifacts.test.cjs 集中覆盖了注册表行为其中对同类误报修复的回归用例提供了先例参照如 #3227 的state.json、#3224 的WINDOWS.md、#4282 的PATTERNS.md其模式完全适用于RETROSPECTIVE.md断言CANONICAL_EXACT.has(RETROSPECTIVE.md)为真断言isCanonicalPlanningFile(RETROSPECTIVE.md)返回true断言isCanonicalPlanningFile(random-file.md)仍返回falseW019 的兜底能力不受影响。5.2 W019 集成测试同一文件的gsd-health W019 — unrecognized .planning/ root files分组第 187 行起通过临时项目夹具验证了完整行为矩阵.planning/MY-NOTES.md→ 触发一条 W019消息包含文件名repairable false仅标准BASE_FILES→ 无 W019版本戳文件v1.0-MILESTONE-AUDIT.md→ 无 W019命中CANONICAL_PATTERNS阶段子目录文件 → 无 W019根目录外不检查两个杂散文件 → 产生两条 W019一文件一告警。对应规则单测位于 tests/health-diagnostic-rules/milestone-archive-hygiene.test.cjs明确标注其来源为 Phase 11、#3309、ADR-3180 §8.2/§8.3/§8.5。5.3 权威清单文档同步gsd-core/templates/README.md 是该机制的权威索引开篇即声明if a.planning/root file is not listed here,gsd-healthwill flag it as W019 (unrecognized artifact).其根工件表格第 25 行已列出RETROSPECTIVE.md来源列标注为/gsd:complete-milestone用途为 Living milestone retrospective updated at each milestone close。由于 W019 的修复建议文本会指引用户「See templates/README.md for the canonical artifact list」文档、注册表、规则三者必须保持一致——本次变更正是这种一致性的又一次落地。同时第 45、66 行分别说明阶段子目录文件与归档到.planning/milestones/的文件永远不会被 W019 检查。6. 实践指引6.1 运行健康检查观察效果在项目根目录执行gsd-health修复前若.planning/根目录存在RETROSPECTIVE.md会收到W019 — Unrecognized .planning/ file: RETROSPECTIVE.md告警及「归档或删除」的建议。修复后该文件命中CANONICAL_EXACT不再产生任何告警而未登记的文件如MY-NOTES.md、scratch.md仍会被正常标记。6.2 新增根工件时的正确姿势参照src/artifacts.cts头部注释的指引任何新工作流若要在.planning/根目录产出文件应完成三件事注册将文件名加入CANONICAL_EXACT或符合语义时加入CANONICAL_PATTERNS文档化在 gsd-core/templates/README.md 的根工件表格中登记产出方与用途测试固化在 tests/artifacts.test.cjs 增加「注册表包含 判定为 canonical」的回归用例并视需要在 W019 集成测试中补充「不误报」用例。6.3 边界行为速查场景W019 行为.planning/RETROSPECTIVE.md本次修复不告警.planning/PROJECT.md等精确匹配项不告警.planning/v1.2.0-MILESTONE-AUDIT.md不告警正则匹配.planning/phases/01-foundation/01-01-PLAN.md不告警仅查根目录.planning/milestones/归档文件不告警归档目录豁免.planning/scratch.md等未登记文件告警且不可自动修复大小写变体如retrospective.md告警精确匹配区分大小写7. 小结本次 changesetPR 3200是一次典型而精准的「注册表遗漏」修复RETROSPECTIVE.md作为/gsd-complete-milestone持续维护的活文档其 canonical 地位此前只体现在工作流与文档层面却未同步到 src/artifacts.cts 的CANONICAL_EXACT导致gsd-health的 W019 规则对它误报。修复后注册表、W019 判定、模板 README 权威清单三者达成一致规则仍保留对真正杂散文件的告警能力。这一模式注册 → 文档化 → 测试固化为 gsd-core 中所有根级工件的管理提供了可复制的范本。赞分享【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载相关推荐gsd-core W002 误报修复详解/gsd:health 为何不再为已归档 Phase 报错gsd core W002 误报修复详解/gsd:health 为何不再为已归档 Phase 报错 本文围绕 gsd core 仓库中的一个变更集记录chagsd-core 里程碑归档目录解析修复getActiveMilestoneArchiveDir 的 null 语义与 W007 误报消除gsd core 里程碑归档目录解析修复getActiveMilestoneArchiveDir 的 null 语义与 W007 误报消除 本文聚焦 gsdVitest includeTaskLocation 配置详解为任务注入源码定位并启用按行号过滤测试Vitest includeTaskLocation 配置详解为任务注入源码定位并启用按行号过滤测试 includeTaskLocation 是 Vitest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考