【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载本文围绕 gsd-core 的 ADR-612「bracket 阶段 ID 约定」显示面落地issue #3638 / PR 4111展开当一个项目通过phase_id_convention: bracket显式 opt-in 后progress、stats、manager init 以及两种 statusline 格式会以统一的规范形态[CODE.MM] NN渲染阶段标识而未 opt-in 的项目null、sequential、milestone-prefixed则保留原有输出形状字节级不变。同时config-set为该键新增了枚举校验只接受三个受支持值。读完本文你将掌握 bracket 约定的完整语法、各显示面的行为差异、底层规范解析/渲染对的实现原理以及如何安全地配置与验证这一约定。一、背景ADR-612 bracket 约定到底是什么gsd-core 的phase_id_convention配置键控制项目阶段 ID 的命名约定。在 docs/CONFIGURATION.md 中它被定义为取值sequential、milestone-prefixed、bracket或null的枚举默认值为nullnull/sequential沿用传统数字 IDPhase 1、Phase 2milestone-prefixed使用编码了所在 milestone 的全局唯一 IDPhase 1-01、Phase 1-02并且是当前发布线唯一的roadmap upgrade迁移目标bracket把 milestone 前置到阶段编号之前——标题写作### [GSD.02] 05: Name目录写作GSD.02-05-name。bracket是 opt-in 的仓库必须显式把phase_id_convention设为bracket显示面才会切换到新的标识形态。这一点在 gsd-core/references/phase-id-convention.md 开头直接写明The bracket convention is opt-in throughphase_id_convention: bracket.1.1 规范的 bracket 语法卡片该约定的紧凑语法卡片由 src/phase-id-card.cts 单一来源生成PHASE_ID_CARD常量渲染站点通过phaseIdCard()引入tests/phase-id-card.test.cjs 保证生成文档与其字节一致[GSD.02] 05.03-01 │ │ │ │ │ │ │ │ │ └── plan 01 │ │ │ └────── subphase 03 │ │ └───────── phase 05 │ └───────────── milestone 02 └───────────────── project GSD milestone bracket integer; dots phase-levels; one hyphen plan; no Phase word, no vX.Y两种等价形态显示形式[PROJECT.MM] PP[.SS][-LL]方括号承载 project 与 milestone点号连接阶段层级单一连字符引入可选的 plan目录形式PROJECT.MM-PP[.SS]-slug/同一身份不加方括号编码到目录名中末尾是 slug。面向人的 bracket 显示面同时省略了字面的Phase标签和传统vX.Ymilestone 标记参见 gsd-core/references/phase-id-convention.md。二、约定门控只有精确的bracket才改变显示#3638 的核心设计原则是精确门控exact gating显示面只在phase_id_convention精确等于bracket时才渲染规范的[CODE.MM] NN标识其他约定null、sequential、milestone-prefixed以及任何未识别值保留原有的模式与输出形状。这一点在 docs/CONFIGURATION.md 中有明确说明A project on any other value compiles the same heading patterns and retains the same output shape it did before.从源码看这一门控贯穿了所有相关模块。以 src/phase-id.cts 为例多个核心辅助函数都以可选参数convention作为 ADR-2121 的「增量形态」约定——不传参会字节级等价于旧行为phaseHeadingPrefixSrcForsrc/phase-id.ctsif (convention ! bracket) return base;——非 bracket 约定编译的是站点原有的基准标题前缀源码ANY_BRACKET或LABEL_ONLY而不是其超集getMilestoneFromPhaseIdsrc/phase-id.ctsbracket 分支从[PROJECT.MM]/{CODE}.{MM}-前缀读取 milestoneREADING-B非 bracket 路径保留传统前导整数规则READING-AextractPhaseTokensrc/phase-id.ctsbracket 目录{CODE}.{MM}-{PP}[.{SS}]-slug→ 阶段 tokenPP[.SS]同样被convention bracket门控。门控而非「检测」的原因是字符串层面的不可区分性ADR-2121bracket 目录{CODE}.{MM}-{PP}与 legacy#1324字母前缀小数族如P0.3-2、P0.12-34在 project code 以数字结尾时无法用纯字符串规则区分。自动检测会静默地把P0.3-2重新解释为2造成关键辅助函数上的字节级读取回归——所以必须显式约定信号。三、四个显示面的行为详解3.1progress/stats新增display_id字段在 bracket 项目上progress与stats的 JSON 输出在两个层面发生变化见 docs/CLI-TOOLS.md每个阶段保持裸的 join key 在phases[].number同时新增规范的人类可读标签phases[].display_id例如{number:05.03,display_id:[GSD.02] 05.03}milestone_version和表格标题使用[GSD.02]而不是 legacy 的v2.0标记。对应的表格渲染从| 05.03 | display slice |变为| [GSD.02] 05.03 | display slice |且不再出现v2.0。在非 bracket 项目上行为由 tests/adr-612-bracket-display.property.test.cjs 钉死number保持05.03并且不出现display_id字段Object.hasOwn(output.phases[0], display_id) false表格保持| 05.03 | ... |原样。3.2 manager initinit manager在 bracket 项目上读取无标签 bracket 标题如### [GSD.02] 05.03: Display Slice并输出规范的display_id。测试tests/adr-612-bracket-display.property.test.cjs断言其输出{ number: 05.03, display_id: [GSD.02] 05.03, name: Display Slice, disk_status: planned }3.3 两种 statusline 格式hooks/gsd-statusline.js在两种 statusline 格式full 与 compact上都实现了 bracket 门控。其配置解析入口hooks/gsd-statusline.js把phase_id_convention bracket解析为convention: bracket传入渲染函数渲染时hooks/gsd-statusline.js 与 hooks/gsd-statusline.js通过opts.convention bracket决定milestone 显示用[GSD.02]替代v2.0阶段显示用 bracket 阶段标签如[GSD.02] 05.03替代P05/12之类的 legacy 形态。测试tests/adr-612-bracket-display.property.test.cjs同时断言两种格式在 bracket 下匹配/\[GSD\.02\]/且不匹配/v2\.0/并在sequential下保留精确的 legacy 字符串见同文件 tests/adr-612-bracket-display.property.test.cjs。3.4 一个统一的语法决策milestone 标签 阶段显示前缀renderMilestoneId(id)返回[GSD.02]renderPhaseId(id)返回${renderMilestoneId(id)} 05.03-01——milestone 标签被钉死为所有 bracket 阶段显示共享的前缀见 tests/adr-612-bracket-display.property.test.cjs。显示适配层 src/phase-id-display.cts 中的renderBracketMilestoneDisplay(v2.0, GSD)能把 legacy 的v2.0元数据翻译成[GSD.02]。四、底层实现规范解析/渲染对与显示适配层4.1parsePhaseId/renderPhaseId/toDir单一可信的 round-trip 模型src/phase-id.cts 定义了唯一的可往返 bracket 模型ADR-612 Decision 4。PhaseId结构类型包含project、milestone零填充、phase零填充、可选subphase与可选plan仅文件名面。关键实现事实规范一致性由构造保证parsePhaseId在解析显示形式[PROJECT.MM] PP[.SS][-LL]或目录形式{PROJECT}.{MM}-{PP}[.{SS}][-{plan|slug}]后会重新渲染并逐字节比对输入拒绝非填充数字[GSD.5] 5、过度填充[GSD.005] 05与多空格[GSD.02] 05统一抛错而不是静默归一化render(parse(x)) x契约由属性测试钉死tests/adr-612-bracket-display.property.test.cjs 用 fast-check 对任意project, milestone, phase, subphase组合断言renderPhaseId(parsePhaseId(display)) display且toDir(parsePhaseId(display), display slice)精确命中手写目录toDir的写入侧校验project 必须匹配[A-Z][A-Z0-9_]*milestone/phase/subphase 必须匹配规范的数值宽度恰好 2 位或 3 位以上且无前导零——由BRACKET_CANONICAL_NUMERIC_SOURCE统一持有slug 必须清洗为非空、非全数字的 token防止路径穿越与磁盘↔身份双射破坏。4.2 显示适配层只做边界归一化src/phase-id-display.cts 的定位是「纯适配器」STATE.md和 milestone 元数据仍暴露 legacy 的vN.0标记显示面需要把它翻译成 bracket 身份但不重复实现另一套渲染器。renderBracketPhaseDisplay与renderBracketMilestoneDisplay只做数值边界归一化剥离v前缀、拆分v2.0、规范数值宽度随后委托给 src/phase-id.cts 的parsePhaseId/renderMilestoneId/renderPhaseId规范对元数据不完整或无效时返回null让装饰性调用方优雅降级而不是破坏命令/statusline 渲染。4.3 约定的一次性解析与线程化branch 文档 docs/adr/612-bracket-phase-id-convention.md 指出消费方遵循「解析一次、显式线程化」的纪律例如roadmap-command-router.cts在 src/roadmap-command-router.cts 中于消费方之前一次性解析phase_id_convention含从 ROADMAP frontmatter 回退读取再作为参数传入各消费方src/roadmap.cts 同样把resolvePhaseIdConvention的结果线程化到阶段目录扫描scopeToPhase、matchPhaseDirs等调用链而不是在每个站点重新读取配置。五、config-set的枚举校验三个受支持值#3638 的另一半是配置侧校验。此前phase_id_convention是一个未校验的魔法字面量现在config-set只接受精确的三个值。5.1 源码中的枚举定义src/config.cts 定义了// ADR-612 PR-5: configuration accepts every convention the runtime can read. // Keep this distinct from roadmap-upgrades supported target set: sequential // is valid project configuration but is not a migration destination. const VALID_PHASE_ID_CONVENTIONS: readonly string[] Object.freeze([ sequential, milestone-prefixed, bracket, ]);设置路径src/config.cts通过assertEnumValue(parsedValue, val, VALID_PHASE_ID_CONVENTIONS, phase_id_convention)校验null用于取消该键config-set phase_id_convention null会移除键本身且保留兄弟配置项见 tests/config.test.cjs。5.2 测试钉死的校验行为tests/config.test.cjs 覆盖了完整行为矩阵三个受支持值sequential、milestone-prefixed、bracket都能成功写入并被回读null取消键且不影响model_profile等兄弟配置不支持值free-form与大小写不匹配值Bracket都被拒绝错误信息包含Invalid phase_id_convention与支持集合sequential, milestone-prefixed, bracketsequential是合法项目配置但不是roadmap upgrade --convention的迁移目标迁移只接受milestone-prefixed。5.3 配置方式# 在项目根目录设置 bracket 约定 gsd-tools config-set phase_id_convention bracket # 取消约定键被移除回到 null 行为 gsd-tools config-set phase_id_convention null或直接在.planning/config.json中写入{phase_id_convention: bracket}测试夹具即以此方式构造 bracket 项目见 tests/adr-612-bracket-display.property.test.cjs。六、兼容性保证与边界行为6.1 非 bracket 项目结构等同而非「论证等价」这是本设计最值得注意的一点未 opt-in 的仓库编译的标题模式恰好是基线拼写本身BASE_ANY_BRACKET_HEADING_PREFIX_SRC/BASE_PHASE_LABEL_PREFIX_SRC而不是其超集。原因是早期实现曾不加门控地放宽读取并论证放宽后的形态「不可能出现在 legacy ROADMAP 中」——但### [RFC.2119] 5:、### [v1.0] 2024:、### [ADR.612] 3:都是合法 legacy 标题放宽会把它们当作阶段从而在没有 opt-in 的仓库上移动phase_count、total_phases与 W006。构造时选择construction-time selection从根上消除了这一论证负担见 src/phase-id.cts 的注释。6.2 malformed bracket 目录的恢复当目录名不规范时如小写gsd.02-05.03-recovered-display-nametests/adr-612-bracket-display.property.test.cjs 的夹具progress与stats仍能识别出阶段并输出number: 05.03但不产生display_idhasDisplayId: false——优雅降级不破坏命令输出。6.3 opt-in 的代价必须知晓的权衡文档在 docs/CONFIGURATION.md 中明确给出了 opt-in 的代价在 bracket 仓库上bracket 后直接跟数字的标题会被当作阶段标题因此在其他约定下合法的小节标题形态——### [RFC.2119] 5:、### [v1.0] 2024:、### [ADR.612] 3:——都会被认作阶段移动phase_count、total_phases与 W006。bracket 仓库放弃了这一标题形态这是 opt-in 换来的权衡也是放宽读取必须在构造时从该配置值选择、而不是全局应用的原因。6.4 范围限制目前bracket只影响读取与显示路径尚没有 bracket 迁移器和 bracket 写入emit。文档明确提示There is no bracket migrator and no bracket emit yet, so set it only on a project whose ROADMAP.md and phase directories already use that spelling.——只应在 ROADMAP.md 与阶段目录已使用该拼写的项目上开启。七、验证与测试地图围绕 #3638 的测试集中在两处测试文件覆盖点tests/adr-612-bracket-display.property.test.cjsprogress/stats 的display_id与milestone_versioninit manager 读取无标签 bracket 标题legacy 项目保留旧对象/表格形状malformed 目录恢复且无display_idrenderMilestoneId作为共享前缀statusline full/compact 的约定门控render(parse(x)) x与toDir的 fast-check 属性测试tests/config.test.cjsconfig-set phase_id_convention的枚举校验三值接受、null取消、不支持/大小写不匹配拒绝、sequential非迁移目标另有 tests/phase-id-card.test.cjs 钉死语法卡片字节与 src/phase-id-card.cts 一致以及同族测试 tests/adr-612-bracket-coherence.test.cjs、tests/adr-612-bracket-heading-selection.test.cjs 等覆盖读取侧一致性均在 tests 目录下。八、总结#3638PR 4111为 ADR-612 的 bracket 约定补齐了显示面与配置面的最后一块拼图其核心贡献可以概括为三点统一的规范形态progress、stats、manager init 与两种 statusline 在phase_id_convention: bracket下渲染同一套[CODE.MM] NN标识progress/stats同时暴露number与display_id双字段严格的约定门控非 bracket 项目编译与渲染与其基线字节级等同彻底消除「放宽读取被误用」的论证风险配置侧枚举校验config-set只接受sequential、milestone-prefixed、bracket三个精确值或null取消配合测试矩阵钉死行为。如果你想在已有 ROADMAP.md 与阶段目录均使用 bracket 拼写的项目上启用它只需gsd-tools config-set phase_id_convention bracket并在progress/stats/init manager/statusline 输出中确认[CODE.MM]形态出现、legacyvN.0消失即可若需深入语法细节gsd-core/references/phase-id-convention.md 是权威的紧凑语法卡src/phase-id.cts 与 src/phase-id-display.cts 则是规范的解析/渲染/适配实现。赞分享【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载相关推荐Wazuh Engine schemf 模块深度解析Schema 字段定义与两阶段校验系统Wazuh Engine schemf 模块深度解析Schema 字段定义与两阶段校验系统 本篇技术指南围绕 Wazuh Engine 的 schemf S网络安全IDS日志分析应用安全漏洞扫描Slang 仓库 LLM 生成文档的修复阶段_remediate.md 提示词契约与两阶段审校工作流解析Slang 仓库 LLM 生成文档的修复阶段 _remediate.md 提示词契约与两阶段审校工作流解析 本文档解析 Shader Slang 仓库中由 L编译器图形学编程语言get-shit-done 命令契约校验ADR-0002以双层校验与前端字段规范锁定 65 个 gsd 斜杠命令的质量基线get shit done 命令契约校验ADR 0002以双层校验与前端字段规范锁定 65 个 gsd 斜杠命令的质量基线 导读 本篇文章围绕 get s人工智能AI 应用提示工程开发工具工作流自动化AI Agent上一篇Backdrop CMS为非技术人员打造的全能内容管理系统下一篇Thelia开源电商平台的强大选择创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
