refactor: hard-fork GSD -> MSD (Make Software Done)

Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD
across contents and paths, upstream package/repo coordinates -> @golem15/msd-core
and golem15com/msd-core. Deep links into upstream history, sibling upstream
packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is.

Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line,
package/plugin identity, regenerated lockfile, install-tree fixtures, derived
registries and benchmark baseline; migration checksum baseline re-locked
(MSD keeps its own install state, so no install had applied the old sums);
sort-order and regex-escaped expectations in tests adjusted.
This commit is contained in:
Jakub Zych
2026-10-06 01:47:40 +02:00
parent fe069b2a56
commit a9a7a328e6
2763 changed files with 78465 additions and 78434 deletions

View File

@@ -1,6 +1,6 @@
# CONTEXT.md 结构参考
每个阶段的 `CONTEXT.md` 是 GSD Core 用于保存 `/gsd-discuss-phase` 阶段所收集的实现决策的载体。它是研究代理和规划代理的主要上游输入。本页面记录其结构。参见[文档索引](../README.md)。
每个阶段的 `CONTEXT.md` 是 MSD Core 用于保存 `/msd-discuss-phase` 阶段所收集的实现决策的载体。它是研究代理和规划代理的主要上游输入。本页面记录其结构。参见[文档索引](../README.md)。
---
@@ -14,7 +14,7 @@
示例:`.planning/phases/03-post-feed/03-CONTEXT.md`。
该文件由 `gsd-core/workflows/discuss-phase.md` 中的 `write_context` 步骤生成(或通过 PRD/ADR 摄入快速路径生成)。在正常操作中,该文件不会被手动编辑——讨论阶段工作流负责写入,下游代理将其作为封闭的可信来源读取。
该文件由 `msd-core/workflows/discuss-phase.md` 中的 `write_context` 步骤生成(或通过 PRD/ADR 摄入快速路径生成)。在正常操作中,该文件不会被手动编辑——讨论阶段工作流负责写入,下游代理将其作为封闭的可信来源读取。
---
@@ -39,12 +39,12 @@
| 块名 | 用途 | 由谁填充 | 由谁消费 |
|---|---|---|---|
| `<domain>` | 声明阶段边界——本阶段交付内容及明确排除在范围之外的内容。在规划和执行过程中为范围护栏提供锚点。 | `discuss-phase`(来自 ROADMAP.md 阶段目标) | `gsd-planner`、`gsd-plan-checker`(范围合规性) |
| `<spec_lock>` | 仅在 `check_spec` 步骤发现 `*-SPEC.md` 时才存在。列出锁定的需求数量和范围边界;代理被指示直接读取 `SPEC.md` 以获取完整需求。 | `discuss-phase`(条件性) | `gsd-planner`(直接读取 SPEC.md,而非在此重读需求) |
| `<decisions>` | 从讨论中收集的实现决策,使用 `D-NN` 标识符标注。分类由实际讨论内容产生,而非固定分类体系。包含 `Claude's Discretion` 子节,用于用户委托代理自行决定的领域。 | `discuss-phase`(交互式讨论) | `gsd-planner`(锁定的决策必须实现)、`gsd-plan-checker`(维度 7 合规性) |
| `<canonical_refs>` | 与本阶段相关的所有规格文档、ADR、功能文档或设计文档的完整相对路径。必填——每份 CONTEXT.md 必须包含此节。代理在规划或实现之前必须读取列出的文件。 | `discuss-phase`(从 ROADMAP.md 引用 + 讨论中的用户引用 + 代码库侦查积累) | `gsd-phase-researcher`、`gsd-planner` |
| `<code_context>` | 在 `scout_codebase` 步骤中发现的可复用资产、已建立的模式和集成点。引导代理使用现有代码,而非重新实现。 | `discuss-phase`(代码库侦查) | `gsd-planner`、`gsd-phase-researcher` |
| `<specifics>` | 讨论期间逐字记录的具体"我希望它像 X 一样"的参考、产品对比或特定示例。 | `discuss-phase`(自由形式用户输入) | `gsd-planner` |
| `<domain>` | 声明阶段边界——本阶段交付内容及明确排除在范围之外的内容。在规划和执行过程中为范围护栏提供锚点。 | `discuss-phase`(来自 ROADMAP.md 阶段目标) | `msd-planner`、`msd-plan-checker`(范围合规性) |
| `<spec_lock>` | 仅在 `check_spec` 步骤发现 `*-SPEC.md` 时才存在。列出锁定的需求数量和范围边界;代理被指示直接读取 `SPEC.md` 以获取完整需求。 | `discuss-phase`(条件性) | `msd-planner`(直接读取 SPEC.md,而非在此重读需求) |
| `<decisions>` | 从讨论中收集的实现决策,使用 `D-NN` 标识符标注。分类由实际讨论内容产生,而非固定分类体系。包含 `Claude's Discretion` 子节,用于用户委托代理自行决定的领域。 | `discuss-phase`(交互式讨论) | `msd-planner`(锁定的决策必须实现)、`msd-plan-checker`(维度 7 合规性) |
| `<canonical_refs>` | 与本阶段相关的所有规格文档、ADR、功能文档或设计文档的完整相对路径。必填——每份 CONTEXT.md 必须包含此节。代理在规划或实现之前必须读取列出的文件。 | `discuss-phase`(从 ROADMAP.md 引用 + 讨论中的用户引用 + 代码库侦查积累) | `msd-phase-researcher`、`msd-planner` |
| `<code_context>` | 在 `scout_codebase` 步骤中发现的可复用资产、已建立的模式和集成点。引导代理使用现有代码,而非重新实现。 | `discuss-phase`(代码库侦查) | `msd-planner`、`msd-phase-researcher` |
| `<specifics>` | 讨论期间逐字记录的具体"我希望它像 X 一样"的参考、产品对比或特定示例。 | `discuss-phase`(自由形式用户输入) | `msd-planner` |
| `<deferred>` | 讨论中出现但属于其他阶段的想法,予以保留以免遗失。当待办事项经过审查但未纳入范围时,包含 `Reviewed Todos` 子节。 | `discuss-phase`(范围蔓延重定向) | 不被自动化代理消费;仅供人工参考 |
---
@@ -107,7 +107,7 @@ No external specs — requirements fully captured in decisions above
## SPEC.md 集成
当 `/gsd-spec-phase` 在讨论阶段之前运行时,`check_spec` 步骤会找到 `*-SPEC.md` 文件并激活 `<spec_lock>`:
当 `/msd-spec-phase` 在讨论阶段之前运行时,`check_spec` 步骤会找到 `*-SPEC.md` 文件并激活 `<spec_lock>`:
```markdown
<spec_lock>

View File

@@ -1,6 +1,6 @@
# PLAN.md 模式参考
每个计划的 `PLAN.md` 是 GSD Core 的可执行工作单元——一份结构化文档,精确告知执行器代理需要构建什么以及如何验证构建是否正确完成。本页记录其结构。参见[文档索引](../README.md)。
每个计划的 `PLAN.md` 是 MSD Core 的可执行工作单元——一份结构化文档,精确告知执行器代理需要构建什么以及如何验证构建是否正确完成。本页记录其结构。参见[文档索引](../README.md)。
---
@@ -14,7 +14,7 @@
例如:`.planning/phases/03-post-feed/03-02-PLAN.md`(第 3 阶段,第 2 计划)。
计划由 `gsd-planner` 代理生成(由 `/gsd-plan-phase` 触发),并由 `execute-phase` 消费。一个阶段通常包含一到四个计划;同一阶段内的计划被分配到执行波次,以便独立工作并行运行。
计划由 `msd-planner` 代理生成(由 `/msd-plan-phase` 触发),并由 `execute-phase` 消费。一个阶段通常包含一到四个计划;同一阶段内的计划被分配到执行波次,以便独立工作并行运行。
---
@@ -66,7 +66,7 @@ must_haves:
| `phase` | 是 | string | 阶段标识符,例如 `03-post-feed`。 |
| `plan` | 是 | string | 阶段内的计划编号,例如 `02`。 |
| `type` | 是 | `execute` 或 `tdd` | 标准计划使用 `execute`;测试驱动计划使用 `tdd`,测试在实现之前编写。 |
| `wave` | 是 | integer | 执行波次。波次 1 中的计划并行运行(无依赖关系)。波次 2 及以上的计划等待上一波次的所有计划完成后才开始。由 `gsd-planner` 在规划时预先计算。 |
| `wave` | 是 | integer | 执行波次。波次 1 中的计划并行运行(无依赖关系)。波次 2 及以上的计划等待上一波次的所有计划完成后才开始。由 `msd-planner` 在规划时预先计算。 |
| `depends_on` | 是 | array of plan IDs | 该计划必须等待的前置计划。空数组表示波次 1。示例:`["03-01"]` 表示该计划在第 3 阶段计划 01 完成后运行。 |
| `files_modified` | 是 | array of paths | 该计划创建或修改的所有文件。被计划检查器用于检测同波次文件冲突,也被 execute-phase 用于合并跟踪。 |
| `autonomous` | 是 | boolean | 当所有任务类型均为 `auto` 时为 `true`。当计划包含任何需要人工交互的 `checkpoint:*` 任务时为 `false`。 |
@@ -78,7 +78,7 @@ must_haves:
## `must_haves` 字段
`must_haves` 描述了阶段目标达成后必须可观测到的真实状态。该字段在规划阶段派生,并在执行后由 `gsd-verifier` 代理验证。
`must_haves` 描述了阶段目标达成后必须可观测到的真实状态。该字段在规划阶段派生,并在执行后由 `msd-verifier` 代理验证。
### 子字段
@@ -122,8 +122,8 @@ Output: PostFeed and PostCard components wired to /api/feed.
```xml
<execution_context>
@~/.claude/gsd-core/workflows/execute-plan.md
@~/.claude/gsd-core/templates/summary.md
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
```
@@ -194,7 +194,7 @@ Output: PostFeed and PostCard components wired to /api/feed.
## 计划质量维度
`gsd-plan-checker` 代理在执行开始前对每个 PLAN.md 进行 12 个维度的审查。任何未通过 BLOCKER 级别检查的计划将被退回给 `gsd-planner` 修订(最多 3 次迭代):
`msd-plan-checker` 代理在执行开始前对每个 PLAN.md 进行 12 个维度的审查。任何未通过 BLOCKER 级别检查的计划将被退回给 `msd-planner` 修订(最多 3 次迭代):
| 维度 | 检查内容 |
|---|---|

View File

@@ -1,6 +1,6 @@
# 规划产物参考
`.planning/` 目录是 GSD Core 项目的共享记忆。所有工作流都会读取和写入该目录,并留下可审计的决策记录。本页列出每个文件、其用途,以及哪些命令负责生成或消费它。参见[文档索引](../README.md)。
`.planning/` 目录是 MSD Core 项目的共享记忆。所有工作流都会读取和写入该目录,并留下可审计的决策记录。本页列出每个文件、其用途,以及哪些命令负责生成或消费它。参见[文档索引](../README.md)。
---
@@ -50,32 +50,32 @@
| | |
|---|---|
| **用途** | 规范的项目标识:项目内容、目标用户、核心价值、需求、约束和关键决策。随项目演进持续更新。 |
| **生成者** | `/gsd-new-project`(初始创建,包含 `/gsd-onboard` 交接);由 `/gsd-complete-milestone` 在决策验证后更新。 |
| **消费者** | 所有规划工作流;`gsd-phase-researcher`、`gsd-planner`(上下文);`discuss-phase`(历史决策);`gsd-plan-checker`(项目约束)。 |
| **生成者** | `/msd-new-project`(初始创建,包含 `/msd-onboard` 交接);由 `/msd-complete-milestone` 在决策验证后更新。 |
| **消费者** | 所有规划工作流;`msd-phase-researcher`、`msd-planner`(上下文);`discuss-phase`(历史决策);`msd-plan-checker`(项目约束)。 |
### `ROADMAP.md`
| | |
|---|---|
| **用途** | 里程碑与阶段列表,含目标、需求 ID、成功标准以及每个阶段的规范参考。是项目构建内容和顺序的唯一可信来源。 |
| **生成者** | `/gsd-new-project`(初始创建,包含 `/gsd-onboard` 交接);由 `/gsd-phase --insert` 和 `/gsd-complete-milestone` 更新。 |
| **消费者** | `/gsd-discuss-phase`、`/gsd-plan-phase`、`/gsd-execute-phase`;所有需要阶段信息的编排命令;`gsd-planner`、`gsd-plan-checker`、`gsd-phase-researcher`。 |
| **生成者** | `/msd-new-project`(初始创建,包含 `/msd-onboard` 交接);由 `/msd-phase --insert` 和 `/msd-complete-milestone` 更新。 |
| **消费者** | `/msd-discuss-phase`、`/msd-plan-phase`、`/msd-execute-phase`;所有需要阶段信息的编排命令;`msd-planner`、`msd-plan-checker`、`msd-phase-researcher`。 |
### `REQUIREMENTS.md`
| | |
|---|---|
| **用途** | 编号化、可勾选的项目验收标准。每条需求带有 ID(如 `AUTH-01`),映射到路线图阶段。随着阶段执行,逐步标记需求为已完成。 |
| **生成者** | `/gsd-new-project`(初始创建,包含 `/gsd-onboard` 交接);需求由 `execute-phase` 标记为已完成。 |
| **消费者** | `gsd-planner`(计划必须覆盖所有阶段需求 ID);`gsd-plan-checker` 维度 1(需求覆盖);`discuss-phase`(历史需求)。 |
| **生成者** | `/msd-new-project`(初始创建,包含 `/msd-onboard` 交接);需求由 `execute-phase` 标记为已完成。 |
| **消费者** | `msd-planner`(计划必须覆盖所有阶段需求 ID);`msd-plan-checker` 维度 1(需求覆盖);`discuss-phase`(历史需求)。 |
### `STATE.md`
| | |
|---|---|
| **用途** | 实时进度跟踪器——当前阶段与计划、进度指标、积累的决策、会话连续性说明。每次工作流运行时首先读取,每次重要操作后更新。 |
| **生成者** | `/gsd-new-project`(初始创建,包含 `/gsd-onboard` 交接);由所有阶段工作流、`/gsd-pause-work`、`/gsd-resume-work` 持续更新。 |
| **消费者** | 所有编排工作流;`/gsd-progress`;通过 `/gsd-quick` 执行的临时任务;`gsd-planner` 和 `gsd-phase-researcher`(项目决策)。 |
| **生成者** | `/msd-new-project`(初始创建,包含 `/msd-onboard` 交接);由所有阶段工作流、`/msd-pause-work`、`/msd-resume-work` 持续更新。 |
| **消费者** | 所有编排工作流;`/msd-progress`;通过 `/msd-quick` 执行的临时任务;`msd-planner` 和 `msd-phase-researcher`(项目决策)。 |
完整字段参考请参见 [STATE.md 模式](state-md.md)。
@@ -84,8 +84,8 @@
| | |
|---|---|
| **用途** | 工作流配置:模型配置文件、研究与计划检查器开关、Git 分支策略、Nyquist 验证、并行化设置,以及每个代理的模型覆盖。 |
| **生成者** | `/gsd-new-project`(初始创建);`/gsd-settings`(交互式编辑)。 |
| **消费者** | 每个工作流和子代理——在初始化时通过 `gsd-tools query config-get` 读取。 |
| **生成者** | `/msd-new-project`(初始创建);`/msd-settings`(交互式编辑)。 |
| **消费者** | 每个工作流和子代理——在初始化时通过 `msd-tools query config-get` 读取。 |
完整模式请参见 [CONFIGURATION](../CONFIGURATION.md)。
@@ -93,17 +93,17 @@
| | |
|---|---|
| **用途** | Brownfield onboarding 索引,记录产物状态、代码库映射是否完整,以及初次设置后的下一个推荐 GSD 命令。 |
| **生成者** | `/gsd-onboard`,在 `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md` 和 `STATE.md` 全部存在后生成。 |
| **消费者** | 审查初次设置的人;以后确认现有 onboarding 状态的 `/gsd-onboard` 运行。 |
| **用途** | Brownfield onboarding 索引,记录产物状态、代码库映射是否完整,以及初次设置后的下一个推荐 MSD 命令。 |
| **生成者** | `/msd-onboard`,在 `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md` 和 `STATE.md` 全部存在后生成。 |
| **消费者** | 审查初次设置的人;以后确认现有 onboarding 状态的 `/msd-onboard` 运行。 |
### `MILESTONES.md`(可选)
| | |
|---|---|
| **用途** | 已完成里程碑的历史记录。每个里程碑关闭时填充;提供已交付内容及时间的存档快照。 |
| **生成者** | `/gsd-complete-milestone`。 |
| **消费者** | `/gsd-audit-milestone`;人工审查。 |
| **生成者** | `/msd-complete-milestone`。 |
| **消费者** | `/msd-audit-milestone`;人工审查。 |
### `DECISIONS-INDEX.md`(可选)
@@ -118,8 +118,8 @@
| | |
|---|---|
| **用途** | 工作中断时写入的机器可读暂停状态。包含恢复点、进行中的上下文以及继续说明。恰好消费一次——在恢复时。 |
| **生成者** | `/gsd-pause-work`。 |
| **消费者** | `/gsd-resume-work`。 |
| **生成者** | `/msd-pause-work`。 |
| **消费者** | `/msd-resume-work`。 |
---
@@ -132,8 +132,8 @@
| | |
|---|---|
| **用途** | 规划开始前捕获的实现决策。包含阶段边界(`<domain>`)、带有 `D-NN` 标识符的锁定决策(`<decisions>`)、规范文档参考(`<canonical_refs>`)、现有代码洞察(`<code_context>`)、具体灵感(`<specifics>`)以及推迟的想法(`<deferred>`)。 |
| **生成者** | `/gsd-discuss-phase`(交互式讨论或 PRD/ADR 快速路径)。 |
| **消费者** | `gsd-phase-researcher`(待调查内容);`gsd-planner`(锁定决策);`gsd-plan-checker` 维度 7(上下文合规性)。 |
| **生成者** | `/msd-discuss-phase`(交互式讨论或 PRD/ADR 快速路径)。 |
| **消费者** | `msd-phase-researcher`(待调查内容);`msd-planner`(锁定决策);`msd-plan-checker` 维度 7(上下文合规性)。 |
完整字段参考请参见 [CONTEXT.md 模式](context-md.md)。
@@ -142,7 +142,7 @@
| | |
|---|---|
| **用途** | discuss-phase 会话的人类可读审计记录:讨论的领域、提出的选项、所做的选择、推迟的想法以及留给 Claude 自行决定的事项。不被自动化工作流消费。 |
| **生成者** | `/gsd-discuss-phase`(`git_commit` 步骤)。 |
| **生成者** | `/msd-discuss-phase`(`git_commit` 步骤)。 |
| **消费者** | 人工审查;回顾总结。 |
### `<NN>-RESEARCH.md`
@@ -150,32 +150,32 @@
| | |
|---|---|
| **用途** | 规划前产生的技术研究结果。回答"为了很好地规划此阶段,我需要了解什么?"——涵盖领域分析、模式、风险、架构职责映射以及验证架构部分(由 Nyquist 门控使用)。 |
| **生成者** | `/gsd-plan-phase` 通过 `gsd-phase-researcher` 代理。 |
| **消费者** | `gsd-planner`(规划输入);`gsd-plan-checker` 维度 7c(层级合规性)、维度 8(Nyquist)、维度 11(研究解决);`gsd-pattern-mapper`(文件列表来源)。 |
| **生成者** | `/msd-plan-phase` 通过 `msd-phase-researcher` 代理。 |
| **消费者** | `msd-planner`(规划输入);`msd-plan-checker` 维度 7c(层级合规性)、维度 8(Nyquist)、维度 11(研究解决);`msd-pattern-mapper`(文件列表来源)。 |
### `<NN>-VALIDATION.md`
| | |
|---|---|
| **用途** | 源自 RESEARCH.md 中 `## Validation Architecture` 部分的 Nyquist 启发式验证策略。指定计划必须遵守的自动化测试覆盖要求。 |
| **生成者** | `/gsd-plan-phase`(步骤 5.5,当 `workflow.nyquist_validation` 已启用且 RESEARCH.md 包含验证架构部分时)。 |
| **消费者** | `gsd-plan-checker` 维度 8(检查 8e 门控——Nyquist 检查进行前必须存在);`gsd-verifier`。 |
| **生成者** | `/msd-plan-phase`(步骤 5.5,当 `workflow.nyquist_validation` 已启用且 RESEARCH.md 包含验证架构部分时)。 |
| **消费者** | `msd-plan-checker` 维度 8(检查 8e 门控——Nyquist 检查进行前必须存在);`msd-verifier`。 |
### `<NN>-PATTERNS.md`
| | |
|---|---|
| **用途** | 由 `gsd-pattern-mapper` 生成的代码库类比映射。针对本阶段每个待创建或修改的文件,识别最近似的现有类比,对文件的角色和数据流进行分类,并提取具体代码摘录。引导规划者采用一致的模式。 |
| **生成者** | `/gsd-plan-phase` 通过 `gsd-pattern-mapper` 代理(可选;如果 `workflow.pattern_mapper: false` 则跳过)。 |
| **消费者** | `gsd-planner`(模式指导);`gsd-plan-checker` 维度 12(模式合规性)。 |
| **用途** | 由 `msd-pattern-mapper` 生成的代码库类比映射。针对本阶段每个待创建或修改的文件,识别最近似的现有类比,对文件的角色和数据流进行分类,并提取具体代码摘录。引导规划者采用一致的模式。 |
| **生成者** | `/msd-plan-phase` 通过 `msd-pattern-mapper` 代理(可选;如果 `workflow.pattern_mapper: false` 则跳过)。 |
| **消费者** | `msd-planner`(模式指导);`msd-plan-checker` 维度 12(模式合规性)。 |
### `<NN>-<PP>-PLAN.md`
| | |
|---|---|
| **用途** | 阶段内单个工作单元的可执行计划。包含 YAML 前置内容(wave、dependencies、files、requirements、`must_haves`)、目标、上下文参考、带有 `<read_first>`、`<action>`、`<verify>` 和 `<acceptance_criteria>` 字段的 XML 结构化任务,以及验证标准。 |
| **生成者** | `/gsd-plan-phase` 通过 `gsd-planner` 代理。每个计划一个文件——例如,`03-02-PLAN.md` 是第 3 阶段第 2 个计划。 |
| **消费者** | `/gsd-execute-phase`(执行器代理读取计划并运行任务);`gsd-plan-checker`(执行前质量审查);`gsd-verifier`(读取 `must_haves` 进行执行后验证)。 |
| **生成者** | `/msd-plan-phase` 通过 `msd-planner` 代理。每个计划一个文件——例如,`03-02-PLAN.md` 是第 3 阶段第 2 个计划。 |
| **消费者** | `/msd-execute-phase`(执行器代理读取计划并运行任务);`msd-plan-checker`(执行前质量审查);`msd-verifier`(读取 `must_haves` 进行执行后验证)。 |
完整字段参考请参见 [PLAN.md 模式](plan-md.md)。
@@ -185,30 +185,30 @@
|---|---|
| **用途** | 计划完成后写入的执行记录。记录已构建内容、与计划的偏差、对验收标准的自查,以及阶段的依赖关系图。 |
| **生成者** | `execute-phase` 执行器代理(在每个计划执行结束时写入)。 |
| **消费者** | `/gsd-progress`(阶段状态);`gsd-planner`(当后续计划对先前计划输出存在真实依赖时);`milestone-summary`。 |
| **消费者** | `/msd-progress`(阶段状态);`msd-planner`(当后续计划对先前计划输出存在真实依赖时);`milestone-summary`。 |
### `<NN>-VERIFICATION.md`
| | |
|---|---|
| **用途** | 阶段目标验证报告。在执行完成后,对照实际代码库检查所有计划中的 `must_haves.truths`、`must_haves.artifacts` 和 `must_haves.key_links`。记录 `status: passed | gaps_found | human_needed`。 |
| **生成者** | `/gsd-verify-work`(或 `/gsd-execute-phase` 内的验证步骤)。 |
| **消费者** | `plan-phase` 已关闭阶段门控(`status: passed` 的 VERIFICATION.md 将阶段标记为 `Complete`,并在没有 `--force` 的情况下阻止重新规划);`/gsd-progress`;人工审查。 |
| **生成者** | `/msd-verify-work`(或 `/msd-execute-phase` 内的验证步骤)。 |
| **消费者** | `plan-phase` 已关闭阶段门控(`status: passed` 的 VERIFICATION.md 将阶段标记为 `Complete`,并在没有 `--force` 的情况下阻止重新规划);`/msd-progress`;人工审查。 |
### `<NN>-UAT.md`
| | |
|---|---|
| **用途** | 持久化的 UAT 会话跟踪。在实时 UAT 会话中记录每个测试用例、预期的可观察行为、结果以及开发者响应。带有 YAML 前置内容(`status`、`phase`、`source`、时间戳)。 |
| **生成者** | `/gsd-audit-uat`(交互式 UAT 会话)。 |
| **消费者** | `/gsd-audit-uat`(恢复先前的 UAT 会话)。 |
| **生成者** | `/msd-audit-uat`(交互式 UAT 会话)。 |
| **消费者** | `/msd-audit-uat`(恢复先前的 UAT 会话)。 |
### `.continue-here.md`
| | |
|---|---|
| **用途** | 阶段工作暂停时写入的人类可读恢复说明。包含供恢复代理使用的上下文:关键反模式、阻塞问题、必读内容以及恢复的确切命令。 |
| **生成者** | `/gsd-pause-work`。 |
| **生成者** | `/msd-pause-work`。 |
| **消费者** | 任何在阶段上启动的工作流——`discuss-phase` 和 `plan-phase` 在入口处均检查此文件,并要求代理在继续之前证明其理解了所有 `blocking` 反模式。 |
---

View File

@@ -1,14 +1,14 @@
# STATE.md 架构参考
`STATE.md` 是 GSD Core 的动态项目记忆文件——一个记录项目当前状态、最近发生的事情以及下一步操作的单一 Markdown 文档。本页面记录其结构。参见[文档索引](../README.md)。
`STATE.md` 是 MSD Core 的动态项目记忆文件——一个记录项目当前状态、最近发生的事情以及下一步操作的单一 Markdown 文档。本页面记录其结构。参见[文档索引](../README.md)。
---
## 概述
由 GSD Core 管理的每个项目在 `.planning/STATE.md` 处保存一个 `STATE.md`。该文件在每次工作流开始时被读取,并在每次重要操作后被写入。该文件包含:
由 MSD Core 管理的每个项目在 `.planning/STATE.md` 处保存一个 `STATE.md`。该文件在每次工作流开始时被读取,并在每次重要操作后被写入。该文件包含:
- **YAML 前置数据** — 机器可读字段,由状态行钩子(`parseStateMd`)和 `gsd-tools state` 命令使用。
- **YAML 前置数据** — 机器可读字段,由状态行钩子(`parseStateMd`)和 `msd-tools state` 命令使用。
- **Markdown 正文** — 人类可读的章节,涵盖当前位置、累积的上下文、会话连续性以及性能指标。
该文件有意保持较小(目标:不超过 100 行)。它是项目状态的摘要,而非存档。
@@ -17,13 +17,13 @@
## YAML 前置数据
前置数据出现在文件最开头的 `---` 分隔符之间。除 `gsd_state_version` 和 `status` 外,所有字段均为可选;当相关数据尚不可用时,字段可以缺失。
前置数据出现在文件最开头的 `---` 分隔符之间。除 `msd_state_version` 和 `status` 外,所有字段均为可选;当相关数据尚不可用时,字段可以缺失。
### 注释示例
```yaml
---
gsd_state_version: '1.0'
msd_state_version: '1.0'
milestone: v2.0
milestone_name: Code Quality
status: executing
@@ -56,7 +56,7 @@ paused_at: null
| 字段 | 类型 | 填充时机 | 用途 |
|---|---|---|---|
| `gsd_state_version` | 字符串(`'1.0'`) | 始终 | 架构版本;在第一次 `state.*` 调用时由 `syncStateFrontmatter` 写入。 |
| `msd_state_version` | 字符串(`'1.0'`) | 始终 | 架构版本;在第一次 `state.*` 调用时由 `syncStateFrontmatter` 写入。 |
| `milestone` | 字符串(如 `v2.0`) | 配置了里程碑时 | 当前里程碑版本,从项目配置中读取。 |
| `milestone_name` | 字符串 | 配置了里程碑时 | 里程碑的人类可读标签(如 `Code Quality`)。 |
| `status` | 字符串 | 始终 | 当前生命周期阶段。由 `normalizeStateStatus()` 规范化——参见[状态值](#状态值)。 |
@@ -83,7 +83,7 @@ paused_at: null
| 字段 | 基数 |
|---|---|
| `gsd_state_version` | one |
| `msd_state_version` | one |
| `milestone` | optional |
| `milestone_name` | optional |
| `current_phase` | optional |
@@ -105,7 +105,7 @@ paused_at: null
### 状态值
`gsd-core/bin/lib/state-document.cjs` 中的 `normalizeStateStatus()` 将原始正文文本映射到以下规范值:
`msd-core/bin/lib/state-document.cjs` 中的 `normalizeStateStatus()` 将原始正文文本映射到以下规范值:
| 规范值 | 匹配文本(不区分大小写) |
|---|---|
@@ -121,10 +121,10 @@ paused_at: null
| 命令 | 运行期间的 `status` |
|---|---|
| `/gsd-discuss-phase` | `discussing` |
| `/gsd-plan-phase` | `planning` |
| `/gsd-execute-phase` | `executing` |
| `/gsd-verify-work` | `verifying` |
| `/msd-discuss-phase` | `discussing` |
| `/msd-plan-phase` | `planning` |
| `/msd-execute-phase` | `executing` |
| `/msd-verify-work` | `verifying` |
<!-- STATE-MD-SCHEMA:START:status-lifecycle — generated by scripts/gen-state-md-docs.cjs from src/state-md-schema.cts; do not edit by hand -->
### 状态生命周期 (ADR-2207)
@@ -145,7 +145,7 @@ Phase-completion verbs never write `Milestone complete` (the overloaded bare val
## 状态行渲染场景
`hooks/gsd-statusline.js` 中的 `formatGsdState()` 读取已解析的前置数据并输出**第一个匹配的场景**。如果没有新的生命周期字段适用,渲染将回退到与 v1.38.x 完全一致的原始格式。
`hooks/msd-statusline.js` 中的 `formatMsdState()` 读取已解析的前置数据并输出**第一个匹配的场景**。如果没有新的生命周期字段适用,渲染将回退到与 v1.38.x 完全一致的原始格式。
| 场景 | 触发条件 | 显示示例 |
|---|---|---|
@@ -154,7 +154,7 @@ Phase-completion verbs never write `Milestone complete` (the overloaded bare val
| **3. 里程碑完成** | `percent` 为 `100` 或 `completed_phases == total_phases` | `v2.0 [██████████] 100% · milestone complete` |
| **4. 默认回退** | 以上均不匹配 | `v1.9 Code Quality · executing · ph 1/5`(现有格式) |
**场景优先级:** 当 `active_phase` 和 `next_action` 均已填充时,场景 1 优先——编排器正在运行,显示"下一步推荐"会造成误导。此优先级由 `formatGsdState()` 中的检查顺序强制执行,并由 `tests/gsd-statusline.test.cjs` 中的 `"scene priority"` 测试套件覆盖。
**场景优先级:** 当 `active_phase` 和 `next_action` 均已填充时,场景 1 优先——编排器正在运行,显示"下一步推荐"会造成误导。此优先级由 `formatMsdState()` 中的检查顺序强制执行,并由 `tests/msd-statusline.test.cjs` 中的 `"scene priority"` 测试套件覆盖。
进度条(`[██░░░░░░░░] 20%`)仅在前置数据中存在 `progress.percent` 时才追加到里程碑段;缺失则不显示进度条。
@@ -162,7 +162,7 @@ Phase-completion verbs never write `Milestone complete` (the overloaded bare val
## 前置数据解析约束
状态行钩子使用基于正则表达式的解析(无完整 YAML 库),因此以下约束适用。这些约束在 `tests/gsd-statusline.test.cjs` 中经过测试。
状态行钩子使用基于正则表达式的解析(无完整 YAML 库),因此以下约束适用。这些约束在 `tests/msd-statusline.test.cjs` 中经过测试。
1. **前置数据必须从文件的第一个字符开始。** 任何内容——包括注释——出现在开头 `---` 之前都会使匹配失效。开头的 `---` 行必须恰好如此,不能有尾随空格。
@@ -176,7 +176,7 @@ Phase-completion verbs never write `Milestone complete` (the overloaded bare val
## Markdown 正文章节
正文(结束 `---` 之后的所有内容)遵循 `gsd-core/templates/state.md` 中的模板。标准章节为:
正文(结束 `---` 之后的所有内容)遵循 `msd-core/templates/state.md` 中的模板。标准章节为:
### 项目参考
@@ -200,7 +200,7 @@ Phase-completion verbs never write `Milestone complete` (the overloaded bare val
进度*历史*不属于这里。它会累积到下方的 [`### Performance Metrics`](#性能指标) 中,那才是设计用于增长的部分。
当现有值为已知模板默认值时,该章节中的 `Status:` 和 `Last activity:` 字段由 GSD 处理器更新(Knuth 不变式:执行器编写的值被保留)。已知处理器默认值的完整列表位于 `gsd-core/bin/lib/state-document.cjs` 中的 `KNOWN_TEMPLATE_DEFAULTS`。
当现有值为已知模板默认值时,该章节中的 `Status:` 和 `Last activity:` 字段由 MSD 处理器更新(Knuth 不变式:执行器编写的值被保留)。已知处理器默认值的完整列表位于 `msd-core/bin/lib/state-document.cjs` 中的 `KNOWN_TEMPLATE_DEFAULTS`。
### 性能指标
@@ -213,11 +213,11 @@ Phase-completion verbs never write `Milestone complete` (the overloaded bare val
### 累积的上下文
**决策** — 影响当前工作的近期决策摘要(完整日志在 `PROJECT.md` 中)。通过 `gsd-tools state add-decision` 添加。
**决策** — 影响当前工作的近期决策摘要(完整日志在 `PROJECT.md` 中)。通过 `msd-tools state add-decision` 添加。
**待处理的待办事项** — 数量及对 `.planning/todos/pending/` 的引用。通过 `/gsd-capture` 捕获。
**待处理的待办事项** — 数量及对 `.planning/todos/pending/` 的引用。通过 `/msd-capture` 捕获。
**阻碍/关切** — 影响未来工作的问题,以发起阶段为前缀。通过 `gsd-tools state add-blocker` 添加;通过 `gsd-tools state resolve-blocker` 解决。
**阻碍/关切** — 影响未来工作的问题,以发起阶段为前缀。通过 `msd-tools state add-blocker` 添加;通过 `msd-tools state resolve-blocker` 解决。
### 会话连续性
@@ -236,7 +236,7 @@ Phase-completion verbs never write `Milestone complete` (the overloaded bare val
- 添加任何生命周期字段是可选的——当字段缺失时,渲染器会优雅降级。
- 即使 `progress` 块存在,进度条也是可选的:只有 `progress.percent` 触发进度条;单独的 `total_phases` 和 `completed_phases` 不会触发。
`tests/gsd-statusline.test.cjs` 中的 `formatGsdState #2833 backward compatibility` 测试套件锁定了此保证;任何破坏旧版 `STATE.md` 渲染的变更都将导致该套件失败。
`tests/msd-statusline.test.cjs` 中的 `formatMsdState #2833 backward compatibility` 测试套件锁定了此保证;任何破坏旧版 `STATE.md` 渲染的变更都将导致该套件失败。
---