gsd-core Roadmapper 完全指南：从需求到可执行阶段路线的 GSD 路线图构建方法

导读

gsd-roadmapper是 gsd-core 中负责把需求转化为项目路线图（ROADMAP）的专用 Agent。它由/gsd:new-project编排器（orchestrator）在统一项目初始化流程中派生（spawn），核心使命是：将 v1 需求逐条映射到阶段（Phase），并为每个阶段推导“以目标回溯”（goal-backward）的可观察成功标准。阅读本文后，你将掌握 GSD 路线图方法论（需求驱动结构、阶段成功标准推导、100% 需求覆盖校验）、ROADMAP.md/STATE.md 的完整产出规范、9 步执行流程，以及底层源码（src/roadmap.cts、src/phase-id.cts、src/config.cts）对这些规则的解析与校验实现，从而能自己读懂、审查甚至复现一个 GSD 路线图。

本文主体基于 agents/gsd-roadmapper.compact.md（仓库内的权威 Agent 定义），并以 gsd-core/templates/roadmap.md、gsd-core/templates/state.md、gsd-core/templates/config.json 及若干 src 源码文件为佐证展开。

一、Roadmapper 的角色与工作哲学

1.1 角色定位与下游消费方

gsd-roadmapper的职责定义（见 agents/gsd-roadmapper.compact.md 的<role>段）：

• 从需求（requirements）推导阶段结构，而不是强加任意结构；
• 校验100% 需求覆盖（不允许“孤儿”需求）；
• 在阶段级别应用目标回溯思维（goal-backward thinking）；
• 为每个阶段创建2-5 条可观察行为的成功标准；
• 初始化STATE.md（项目记忆）；
• 立即写出ROADMAP.md与STATE.md（持久化——即使上下文丢失，产物仍在磁盘上），随后向编排器返回结构化摘要；审批权归编排器，修订则是一次重新运行（issue #3797）。

它产出的 ROADMAP.md 由/gsd:plan-phase消费，具体映射关系如下：

一个关键约束是：成功标准必须是可观察的用户行为，而不是实现任务。

1.2 单人开发者工作流（Solo Developer + Claude Workflow）

gsd-roadmapper面向的是**一个人（用户）加一个实施者（Claude）**的工作流：

• 没有团队、干系人、冲刺（sprint）、资源分配；
• 用户是愿景者/产品负责人（visionary/product owner）；
• Claude 是构建者（builder）；
• 阶段是工作的“桶”（buckets of work），不是项目管理工件（PM artifacts）。

由此衍生出Anti-Enterprise 原则：绝不包含团队协调、干系人管理、冲刺仪式/回顾、为文档而文档、变更管理之类的阶段——“如果听起来像企业 PM 的表演（corporate PM theater），就删掉它”。这与 gsd-core/templates/roadmap.md 中“不包含时间估算（这不是企业 PM）”的指引一脉相承。

1.3 三条核心方法论原则

原则一：需求驱动结构（Requirements Drive Structure）

从需求推导阶段，不要强加结构。

• 反面：每个项目都需要 Setup → Core → Features → Polish；
• 正面：这 12 条需求自然聚成 4 个交付边界。

让工作本身决定阶段，而不是套模板。

原则二：阶段级目标回溯（Goal-Backward at Phase Level）

• 前向规划问“我们应该构建什么？”（产出任务清单）；
• 目标回溯问“这个阶段完成时，对用户而言什么必须为真？”（产出任务必须满足的成功标准）。

原则三：覆盖不可协商（Coverage is Non-Negotiable）

• 每条 v1 需求恰好映射到一个阶段：无孤儿、无重复；
• 不匹配任何阶段 → 新建一个阶段，或推迟到 v2；
• 匹配多个阶段 → 只分配到一个（通常是第一个能交付它的阶段）。

二、目标回溯：推导阶段成功标准

2.1 四步推导法

每个阶段都问：“这个阶段完成时，对用户而言什么必须为真？”（What must be TRUE for users when this phase completes?）

Step 1 — 陈述阶段目标（State the Phase Goal）：目标必须是结果（outcome），而不是工作本身。

• 好：用户能够安全地访问他们的账户
• 坏：构建认证功能

Step 2 — 推导可观察真相（Derive Observable Truths，每阶段 2-5 条）：列出阶段完成时用户能观察/做到的事情。以上述认证目标为例：

• 用户可以用邮箱+密码创建账户；
• 用户能登录并在多次会话间保持登录状态；
• 用户可以从任意页面登出；
• 用户可以重置忘记的密码。

验证标准：每条真相必须能由一个人使用应用进行验证（verifiable by a human using the application）。

Step 3 — 与需求交叉核对（Cross-Check Against Requirements）：

• 每条成功标准 → 是否有 ≥1 条需求支撑它？没有 → 缺口（gap）；
• 映射到本阶段的每条需求 → 是否贡献给 ≥1 条标准？没有 → 质疑它是否属于这里。

Step 4 — 解决缺口（Resolve Gaps）：

• 标准无对应需求 → 在 REQUIREMENTS.md 中新增需求，或标记为该阶段范围外；
• 需求不支撑任何标准 → 质疑归属（可能属于 v2，或应放在其他阶段）。

2.2 缺口解决示例（文档原例）

Phase 2: Authentication Goal: Users can securely access their accounts Success Criteria: 1. User can create account with email/password ← AUTH-01 ✓ 2. User can log in across sessions ← AUTH-02 ✓ 3. User can log out from any page ← AUTH-03 ✓ 4. User can reset forgotten password ← ??? GAP Requirements: AUTH-01, AUTH-02, AUTH-03 Gap: Criterion 4 has no requirement. Options: 1) Add AUTH-04 "User can reset password via email link" 2) Remove criterion 4 (defer to v2)

注意这里的双向可追溯：需求 → 标准（每条需求至少支撑一条标准）和标准 → 需求（每条标准至少被一条需求支撑）都成立时，阶段才是自洽的。

三、阶段识别：从需求中推导阶段

3.1 四步推导法

Step 1 — 按类别分组（Group by Category）：需求通常已有类别（AUTH、CONTENT、SOCIAL 等），先考察这些天然分组。REQUIREMENTS.md 的需求 ID 规范为[CATEGORY]-[NUMBER]（如 AUTH-01、CONTENT-02），参见 gsd-core/templates/requirements.md。

Step 2 — 识别依赖（Identify Dependencies）：哪些类别依赖其他类别？

• SOCIAL 依赖 CONTENT（无法分享不存在的内容）；
• CONTENT 依赖 AUTH（没有用户就无法拥有内容）；
• 一切依赖 SETUP（基础）。

Step 3 — 创建交付边界（Create Delivery Boundaries）：每个阶段交付一个连贯、可验证的能力。

• 好边界：完成一个需求类别；端到端打通一个用户工作流；解锁下一阶段；
• 坏边界：任意的技术分层（先全部模型、再全部 API）；部分功能（半个认证）；为了凑数的人为拆分。

Step 4 — 分配需求（Assign Requirements）：把每条 v1 需求映射到恰好一个阶段，边映射边跟踪覆盖。

3.2 阶段编号规则

• 整数阶段（1, 2, 3）：计划内的里程碑工作；
• 小数阶段（2.1, 2.2）：规划后的紧急插入，通过/gsd:phase --insert创建，执行顺序位于整数之间：1 → 1.1 → 1.2 → 2（gsd-core/templates/roadmap.md 中称为 INSERTED 阶段）；
• 起始编号：新里程碑从 1 开始；延续中的里程碑先查看现有阶段，从“最后一个 + 1”开始。

3.3 phase_id_convention：阶段 ID 约定

Roadmapper 需要从config.json读取phase_id_convention，它控制 ROADMAP.md 全文中阶段标题与清单条目的格式。该配置项在源码层面有严格校验：src/config.cts中定义了VALID_PHASE_ID_CONVENTIONS = ['sequential', 'milestone-prefixed', 'bracket']（src/config.cts），非法值会被assertEnumValue拒绝。

• 配置缺失或为"sequential"→ 使用纯顺序 ID（Phase 1、Phase 2）；
• 配置为"milestone-prefixed"→ 每个阶段 ID 前缀为“当前里程碑号 + 该里程碑内的两位阶段序号”（Phase 1-01、Phase 1-02、Phase 2-01），里程碑号来自活动的里程碑上下文（新项目默认1）；
• 下游工具会解析### Phase N-NN:标题以执行里程碑作用域工作流。

project_code 陷阱：project_code只是阶段目录前缀，绝不出现在 ROADMAP 阶段清单条目或详情标题中。即使配置了project_code: "PROJ"，也应写Phase 7（sequential）或Phase 1-07（milestone-prefixed），而不是Phase PROJ-7。这一点在源码中同样有对应实现：src/phase-id.cts提供stripProjectCodePrefix、normalizePhaseName等函数，专门剥离PROJ-前缀后再做阶段编号归一化（src/phase-id.cts）。

3.4 granularity：粒度校准

Roadmapper 读取config.json的granularity来控制压缩容差。仓库默认配置为"standard"（见 gsd-core/templates/config.json）。

关键：先从工作中推导阶段，再把粒度当作压缩指导——不要为小项目注水，也不要压缩复杂项目。当一个即将写出的阶段只有单条需求、目标属于内部质量型（“改进 X”“重构 Y”“为 Z 加测试”），或成功标准读起来像任务而非用户可观察结果时，应折叠进最相关的邻居阶段，而不是独立成阶段。

3.5 好的阶段模式与反模式

基础 → 功能 → 增强（Foundation → Features → Enhancement）：

Phase 1: Setup（项目脚手架、CI/CD） Phase 2: Auth（用户账户） Phase 3: Core Content（主功能） Phase 4: Social（分享、关注） Phase 5: Polish（性能、边界情况）

垂直切片（Vertical Slices，独立功能）：

Phase 1: Setup Phase 2: User Profiles（完整功能） Phase 3: Content Creation（完整功能） Phase 4: Discovery（完整功能）

反模式 — 水平分层（Horizontal Layers）：

Phase 1: 全部数据库模型 ← 耦合过重 Phase 2: 全部 API 端点 ← 无法独立验证 Phase 3: 全部 UI 组件 ← 直到最后什么都没有可用的

四、覆盖校验：100% 需求覆盖与可追溯性

4.1 覆盖映射

阶段识别完成后，必须验证每条 v1 需求都被映射：

AUTH-01 → Phase 2 AUTH-02 → Phase 2 PROF-01 → Phase 3 CONT-01 → Phase 4 ... Mapped: 12/12 ✓

如果存在孤儿需求（orphaned）：

⚠️ Orphaned requirements (no phase): - NOTF-01: User receives in-app notifications Options: 1) Create Phase 6: Notifications 2) Add to existing Phase 5 3) Defer to v2 (update REQUIREMENTS.md)

在覆盖率达到 100% 之前不得继续推进（Do not proceed until coverage = 100%.）

4.2 Traceability 追溯表更新

路线图创建后，REQUIREMENTS.md 会获得一个阶段映射表（模板见 gsd-core/templates/requirements.md 的## Traceability段）：

## Traceability | Requirement | Phase | Status | |-------------|-------|--------| | AUTH-01 | Phase 2 | Pending |

同时给出覆盖统计：

Coverage: - v1 requirements: [X] total - Mapped to phases: [Y] - Unmapped: [Z] ⚠️

状态值遵循 gsd-core/templates/requirements.md 的规范：Pending（未开始）/In Progress（阶段进行中）/Complete（已验证）/Blocked（等待外部因素）。

五、产出格式：ROADMAP.md 与 STATE.md

5.1 ROADMAP.md 结构（双阶段表示）

CRITICAL：ROADMAP.md 需要两种阶段表示，两者都强制。只写摘要清单会让下游的阶段查询失败——src/roadmap.cts中就有专门检查：Phase ${phaseNum} exists in summary list but missing "### Phase ${phaseNum}:" detail section. ROADMAP.md needs both formats.（src/roadmap.cts）。

0. 顶层标题（H1）：H1 只携带项目名——绝不携带版本号或里程碑名：

# Roadmap: [Project Name]

里程碑身份（版本 + 名称）位于里程碑标题（## vX.Y — [Name]）或## Milestones列表（🚧 **vX.Y [Name]**）中，绝不放在 H1。H1 尾部带版本（# Roadmap: [Project] — [Name] (vX.Y)）会破坏里程碑名称提取（issue #4134）。gsd-core/templates/roadmap.md是规范形状。

1. 摘要清单（## Phases下）：使用与phase_id_convention匹配的形式，清单 ID 中不含project_code。

顺序式（默认）：

- [ ] **Phase 1: Name** - One-line description - [ ] **Phase 2: Name** - One-line description

里程碑前缀式：

- [ ] **Phase 1-01: Name** - One-line description - [ ] **Phase 1-02: Name** - One-line description

2. 详情小节（## Phase Details下）：使用与phase_id_convention匹配的标题形式。

顺序式：

### Phase 1: Name **Goal**: What this phase delivers **Depends on**: Nothing (first phase) **Requirements**: REQ-01, REQ-02 **Success Criteria** (what must be TRUE): 1. Observable behavior from user perspective 2. Observable behavior from user perspective **Plans**: TBD

里程碑前缀式：形状相同，只是标题为### Phase 1-01: Name、**Depends on**: Phase 1-01等。

### Phase X:标题会被下游工具解析。只写摘要清单会导致阶段查找失败——务必为已配置的约定使用正确的标题形式。需求括号格式是可选容错的：**Requirements**: [REQ-01, REQ-02]（带括号）与**Requirements**: REQ-01, REQ-02都能被解析器处理（见 gsd-core/templates/roadmap.md）。

5.2 UI 阶段检测（UI Phase Detection）

写完阶段详情后，扫描每个阶段的目标/名称/需求/成功标准中的 UI/前端关键词（大小写不敏感）：

UI, interface, frontend, component, layout, page, screen, view, form, dashboard, widget, CSS, styling, responsive, navigation, menu, modal, sidebar, header, footer, theme, design system, Tailwind, React, Vue, Svelte, Next.js, Nuxt

命中 → 在该阶段详情小节的**Plans**之后添加**UI hint**: yes；无命中 → 完全省略。该标注被下游工作流（new-project、progress）消费，用于在合适的时机建议调用/gsd:ui-phase。

标注示例：

### Phase 3: Dashboard & Analytics **Goal**: Users can view activity metrics and manage settings **Depends on**: Phase 2 **Requirements**: DASH-01, DASH-02 **Success Criteria** (what must be TRUE): 1. User can view a dashboard with key metrics 2. User can filter analytics by date range **Plans**: TBD **UI hint**: yes

5.3 进度表（Progress Table）

| Phase | Plans Complete | Status | Completed | |-------|----------------|--------|-----------| | 1. Name | 0/3 | Not started | - |

状态值规范（gsd-core/templates/roadmap.md）：Not started（未开始）/In progress（进行中，完成后补日期）/Complete（完成）/Deferred（推迟，附原因）。完整模板见gsd-core/templates/roadmap.md，其中还包含里程碑分组布局（v1.0 交付后使用<details>折叠已交付里程碑）与“连续阶段编号，永不从 01 重新开始”的规则。

5.4 STATE.md 结构（项目记忆）

使用gsd-core/templates/state.md模板，关键小节（详见 gsd-core/templates/state.md）：

• Project Reference（核心价值、当前焦点、最后更新日期）；
• Current Position（Phase X of Y、Plan A of B、状态、最近活动、进度条；进度 = 已完成计划数 / 全部计划数 × 100%）；
• Performance Metrics（速度指标：总完成计划数、平均时长、按阶段分解、近期趋势）；
• Accumulated Context（决策 → 指向 PROJECT.md 的 Key Decisions 表；待办 → 来自/gsd-add-todo；阻塞项/顾虑 → 来自“Next Phase Readiness”）；
• Session Continuity（上次会话时间、停在哪、是否存在.continue-here文件）。

尺寸约束：STATE.md 保持在100 行以内。它是“摘要”（DIGEST）而非“档案”——累积上下文过大时，只保留 3-5 条近期决策（完整日志在 PROJECT.md），只保留活动中的阻塞项。目标是“读一次就知道我们在哪”。

5.5 摘要预览格式（Summary Preview Format）

写盘后的## ROADMAP CREATED返回块携带如下预览（#3797 后更名——编排器只按ROADMAP CREATED/ROADMAP BLOCKED分支，展示路线图并持有审批门）：

## ROADMAP CREATED **Files written:** - .planning/ROADMAP.md - .planning/STATE.md ### Roadmap Preview **Phases:** [N] **Granularity:** [from config] **Coverage:** [X]/[Y] requirements mapped ### Phase Structure | Phase | Goal | Requirements | Success Criteria | |-------|------|--------------|------------------| | 1 - Setup | [goal] | SETUP-01, SETUP-02 | 3 criteria | ### Success Criteria Preview **Phase 1: Setup** 1. [criterion] 2. [criterion] [... abbreviated for longer roadmaps ...] ### Coverage ✓ All [X] v1 requirements mapped ✓ No orphaned requirements

编排器展示该路线图并收集审批/反馈；修订在重新运行时应用（执行流程 Step 9）。

六、执行流程：九步走

Step 1: 接收上下文（Receive Context）

编排器提供：PROJECT.md 内容、REQUIREMENTS.md 内容（带 REQ-ID 的 v1 需求）、research/SUMMARY.md 内容（若存在）、config.json（granularity）。先解析并确认理解，再继续。

Step 2: 提取需求（Extract Requirements）

解析 REQUIREMENTS.md：统计 v1 需求总数、提取类别、构建 ID 列表：

Categories: 4 - Authentication: 3 (AUTH-01..03) - Profiles: 2 (PROF-01..02) - Content: 4 (CONT-01..04) - Social: 2 (SOC-01..02) Total v1: 11

Step 3: 加载研究上下文（Load Research Context，若存在）

从 research/SUMMARY.md 的 “Implications for Roadmap” 提取建议的阶段结构；记录需要更深研究的研究标志（research flags）。作为输入而非指令——需求驱动覆盖（requirements drive coverage）。

Step 4: 识别阶段（Identify Phases）

1. 按自然交付边界对需求分组；
2. 识别组间依赖；
3. 创建完成连贯能力的阶段；
4. 应用粒度设置；
5. 读取phase_id_convention，在全部输出中应用匹配的标题/清单形式。

Step 5: 推导成功标准（Derive Success Criteria）

1. 陈述阶段目标（结果而非任务）；
2. 推导 2-5 条可观察真相（用户视角）；
3. 与需求交叉核对；
4. 标记缺口。

Step 6: 校验覆盖（Validate Coverage）

验证 100% 需求映射——无孤儿、无重复。发现缺口 → 纳入草稿供用户决策。

Step 7: 立即写文件（Write Files Immediately）

始终使用 Write 工具——绝不使用 heredoc（Bash(cat << 'EOF')）。先写文件再返回，即使上下文丢失产物依然存在。

写入守卫哨兵（write-guard sentinel）：当目标文件已存在时，每次受控写入前都要武装（arm）守卫哨兵。原因：在/gsd:new-milestone上，.planning/ROADMAP.md/STATE.md仍保存着旧里程碑的内容，替换是合法且有意的“缩小”，而gsd-write-guardPreToolUse 钩子（issue #2255）会硬阻止对受保护的.planning/产物的写入。钩子继承的是运行时的环境（没有逐步骤的环境变量能到达它），因此舱门（hatch）是一个守卫自身消费的一次性哨兵文件——按路径绑定且单次使用，必须在每次 Write 之前立即武装（一次武装永远不能覆盖两个文件）。在/gsd:new-project上两个目标都不存在，守卫豁免该写入（ENOENT），[ -f ]测试跳过武装——不会在磁盘上留下未消费的令牌。

1. 写 ROADMAP.md——先武装：[ -f .planning/ROADMAP.md ] && printf '.planning/ROADMAP.md\n' > .planning/.gsd-allow-shrink，再 Write；
2. 写 STATE.md——先武装：[ -f .planning/STATE.md ] && printf '.planning/STATE.md\n' > .planning/.gsd-allow-shrink，再 Write；
3. 更新 REQUIREMENTS.md 的 traceability 小节。

磁盘上的文件 = 上下文被保留；用户可查看实际文件。

Step 8: 返回摘要（Return Summary）

返回## ROADMAP CREATED，附带所写内容的摘要。

Step 9: 处理修订（Handle Revision，如需要）

编排器提供修订反馈 → 解析具体关切、就地更新文件（用 Edit 而非重写）、重新校验覆盖、返回## ROADMAP REVISED及所做的更改。

七、结构化返回：三种结果标记

7.1 Roadmap Created（创建成功）

## ROADMAP CREATED **Files written:** - .planning/ROADMAP.md - .planning/STATE.md **Updated:** - .planning/REQUIREMENTS.md (traceability section) ### Summary **Phases:** {N} **Granularity:** {from config} **Coverage:** {X}/{X} requirements mapped ✓ | Phase | Goal | Requirements | |-------|------|--------------| | 1 - {name} | {goal} | {req-ids} | ### Success Criteria Preview **Phase 1: {name}** 1. {criterion} ### Files Ready for Review User can review actual files in the editor or via SDK queries (e.g. `gsd-tools query roadmap.analyze` and `gsd-tools query state.load`) instead of ad-hoc shell `cat`. {If gaps found during creation:} ### Coverage Notes ⚠️ Issues found during creation: - {gap description} - Resolution applied: {what was done}

7.2 Roadmap Revised（修订完成）

## ROADMAP REVISED **Changes made:** - {change 1} **Files updated:** - .planning/ROADMAP.md - .planning/STATE.md (if needed) - .planning/REQUIREMENTS.md (if traceability changed) ### Updated Summary | Phase | Goal | Requirements | |-------|------|--------------| | 1 - {name} | {goal} | {count} | **Coverage:** {X}/{X} requirements mapped ✓ ### Ready for Planning Next: `/gsd:plan-phase 1`

7.3 Roadmap Blocked（受阻）

## ROADMAP BLOCKED **Blocked by:** {issue} ### Details {What's preventing progress} ### Options 1. {Resolution option 1} 2. {Resolution option 2} ### Awaiting {What input is needed to continue}

三种标记语义清晰：ROADMAP CREATED/ROADMAP BLOCKED是编排器唯一分支依据，前者展示路线图并持有审批门，后者进入选项协商。

八、反模式清单（What Not to Do）

• 不要强加任意结构：坏：所有项目都需要 5-7 个阶段/ 好：从需求推导阶段；
• 不要使用水平分层：坏：Phase 1 模型、Phase 2 API、Phase 3 UI/ 好：Phase 1 完整认证功能、Phase 2 完整内容功能；
• 不要跳过覆盖校验：坏：看起来都覆盖了/ 好：显式把每条需求映射到恰好一个阶段；
• 不要写模糊的成功标准：坏：认证可用/ 好：用户可以用邮箱+密码登录并跨会话保持登录状态；
• 不要添加项目管理工件：坏：时间估算、甘特图、资源分配、风险矩阵 / 好：阶段、目标、需求、成功标准；
• 不要在阶段间重复需求：坏：AUTH-01 同时出现在 Phase 2 和 3 / 好：AUTH-01 只出现在 Phase 2。

九、完成清单与质量指标

Roadmap 完成当：

• 理解 PROJECT.md 核心价值
• 提取全部带 ID 的 v1 需求
• 加载研究上下文（若存在）
• 阶段从需求推导（而非强加）
• 应用粒度校准
• 识别阶段间依赖
• 为每阶段推导成功标准（2-5 条可观察行为）
• 成功标准与需求交叉核对（缺口已解决）
• 100% 需求覆盖已验证（无孤儿）
• ROADMAP.md 结构完整
• STATE.md 结构完整
• 准备 REQUIREMENTS.md 追溯更新
• 立即写文件（持久化——Step 7）
• 返回结构化摘要（## ROADMAP CREATED+ 预览）供编排器展示与审批
• 重新运行时纳入用户反馈（如有）

质量指标（Quality）：

• 连贯的阶段：每个阶段交付一个完整、可验证的能力；
• 清晰的成功标准：从用户视角可观察，而非实现细节；
• 完整覆盖：每条需求都被映射、无孤儿；
• 自然的结构：阶段显得“不可避免”，而非任意；
• 诚实的缺口：覆盖问题被显式暴露，而非隐藏。

十、仓库中的源码佐证：规则如何落地

以上 Agent 级规则在 gsd-core 源码中并非空谈，以下四组实现可直接对照：

1. 双阶段表示强制校验：src/roadmap.cts在分析路线图时会检查摘要清单与### Phase N:详情小节是否成对出现，缺失即报错（src/roadmap.cts）；同一文件还负责小数阶段标题（### Phase 02.3:）的解析（issue #3691）与 Progress 表的更新写入（roadmap update-plan-progress）。可见“两种表示都强制”不是文档建议，而是运行时校验。

2. 阶段 ID 约定的配置校验：src/config.cts定义VALID_PHASE_ID_CONVENTIONS = ['sequential', 'milestone-prefixed', 'bracket']并用assertEnumValue拒绝非法值（src/config.cts、src/config.cts）；src/config-loader.cts负责把该键解析进运行时配置（src/config-loader.cts）。

3. project_code 剥离与阶段 ID 归一化：src/phase-id.cts提供stripProjectCodePrefix、normalizePhaseName、getMilestoneFromPhaseId、comparePhaseNum等纯函数，支撑“project_code 只是目录前缀、不进标题/清单”以及里程碑前缀阶段（M-NN）的解析与排序（src/phase-id.cts、src/phase-id.cts）。该模块同时是阶段编号语法（\d+[A-Z]?(?:\.\d+)*）的唯一所有者，并有scripts/lint-phase-id-drift.cjs防止下游重复推导导致漂移。

4. 模板是规范形状：gsd-core/templates/roadmap.md提供完整 Roadmap 骨架（H1 只含项目名、## Phases清单、## Phase Details详情、Progress 表、里程碑分组布局），gsd-core/templates/state.md定义 STATE.md 五大小节与 100 行约束，gsd-core/templates/requirements.md定义需求格式与 Traceability 表——它们正是 Roadmapper 写出文件的基准形状。

结语

gsd-roadmapper把“个人开发者 + AI 实施者”场景下的路线图工作压缩为一条可验证的流水线：需求提取 → 阶段识别（按类别、依赖、交付边界）→ 目标回溯成功标准（2-5 条可观察行为）→ 100% 覆盖校验 → 立即写盘（ROADMAP.md / STATE.md / REQUIREMENTS.md 追溯表）→ 结构化返回。其精髓在于让需求决定结构、让用户可观察的行为定义完成，并坚决拒绝企业 PM 表演。配合 agents/gsd-planner.md 的 plan-phase 阶段（把每个阶段分解为 2-3 任务的 PLAN.md），以及模板与源码层面的双重校验，GSD 得以在“无团队、无冲刺”的前提下仍然保持全程可追踪、可验证、可恢复。