ffd5370464
* fix(#2903): use the command form that actually works in reader-facing docs Docs told readers to type the colon form, which no runtime registers -- 18 of 19 runtimes use slash-hyphen and the 19th uses shell-var -- so anyone copying an example got an unrecognized command. Swept 178 occurrences across 53 files, locale mirrors included so they do not re-diverge from English. The colon form is a source-authoring token, not a user-facing one: install-time converters key on it to produce the hyphen form runtimes actually register. So the sweep is scoped, and three things are deliberately left alone: - ADRs, which are a historical record; editing their prose falsifies what was written at the time. - The legacy release-notes archive, pending a maintainer decision on whether it follows the same historical carve-out. Excluding it keeps a later reversal additive rather than a revert. - Source artifacts under commands, workflows and agents, where the colon form is load-bearing. Rewriting those would break the installed-skill guarantee across every runtime -- the single largest hazard here. The plugin namespace form is a real, separate token and survives untouched. Adds a lint enforcing exactly that boundary, since the correct form genuinely differs by directory and nothing previously caught the drift. Also fixes a hardcoded colon form in the capability-matrix generator. The sweep alone would have left the generated matrix disagreeing with the template that produces it, so the fix is at the source and the output regenerated. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#2903): stop the sweep misquoting source frontmatter Adversarial review caught three lines where the sweep rewrote a citation of the literal YAML name: key from a source command file. That key genuinely is the colon form -- this change's own carve-out logic says source-authoring tokens keep it -- so the docs ended up misquoting the real files. One of the three is an acceptance-checklist assertion, which the sweep turned into a false statement. Restored the three citations to match their sources verbatim, surgically: where a line carried both a name: citation and a real reader-facing slash command, only the citation reverted and the command stayed corrected. The guard needed the same distinction, or it would have flagged the restoration and reddened the build: a gsd:<cmd> token preceded by name: is a citation of a source token and is now permitted. The exemption is deliberately narrow -- a bare gsd:<cmd> anywhere else still fails -- with a test pinning that narrowness. Also makes the detection case-insensitive. Review found /GSD:next slipped through silently; no such casing exists in the tree today, so this closes a latent gap rather than fixing a live one. Swept the whole tree for further corrupted citations: none beyond the three. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(#2903): retire the stale-next invariant and sweep next like every other command Maintainer decision on a genuine conflict between two contracts. Invariant #3054 banned the literal /gsd-next from user-facing docs because it named a retired workflow-advance command. But commands/gsd/next.md is a live command -- the state-aware smart-entry launcher -- and this issue requires docs to use the hyphen form every runtime actually registers. Both could not hold for this one command, so docs had been sidestepping the ban by keeping the colon form, which is exactly the defect this issue exists to remove. FEATURES.md already recorded the reassignment: the hyphen form "is not the retired workflow-advance command; it is reserved for the state-aware smart-entry launcher. Workflow advancement remains under /gsd-progress --next." With that reassignment the invariant's premise is obsolete and the guard now contradicts the documented command form, so it is retired with a comment recording why rather than deleted silently. next is now swept like every other command, and the earlier exemption added to the new guard is removed so nothing is special-cased. Four citations of the literal name: frontmatter key stay in colon form, because the source file really does carry name: gsd:next and a doc quoting it must reproduce it verbatim. Two of those lines were reworded to say which side is the frontmatter key and which is the slash command, since they previously conflated the two. Verified the retired scan would now genuinely fail against this tree -- the conflict was real and resolved, not dodged. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * chore(#2903): backfill changeset pr number Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
149 lines
6.4 KiB
Markdown
149 lines
6.4 KiB
Markdown
# CONTEXT.md 结构参考
|
||
|
||
每个阶段的 `CONTEXT.md` 是 GSD Core 用于保存 `/gsd-discuss-phase` 阶段所收集的实现决策的载体。它是研究代理和规划代理的主要上游输入。本页面记录其结构。参见[文档索引](../README.md)。
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
每个经过讨论工作流处理的阶段，均会在以下路径生成一份 `CONTEXT.md`：
|
||
|
||
```
|
||
.planning/phases/<NN>-<slug>/<NN>-CONTEXT.md
|
||
```
|
||
|
||
示例：`.planning/phases/03-post-feed/03-CONTEXT.md`。
|
||
|
||
该文件由 `gsd-core/workflows/discuss-phase.md` 中的 `write_context` 步骤生成（或通过 PRD/ADR 摄入快速路径生成）。在正常操作中，该文件不会被手动编辑——讨论阶段工作流负责写入，下游代理将其作为封闭的可信来源读取。
|
||
|
||
---
|
||
|
||
## 前言（Frontmatter）
|
||
|
||
`CONTEXT.md` 不包含 YAML 前言。元数据以内联形式写在正文顶部：
|
||
|
||
```markdown
|
||
# Phase [X]: [Name] - Context
|
||
|
||
**Gathered:** [ISO date]
|
||
**Status:** Ready for planning
|
||
```
|
||
|
||
`Status` 字段在文件首次写入时始终为 `Ready for planning`，创建后不再更新。
|
||
|
||
---
|
||
|
||
## 块结构
|
||
|
||
正文由若干具名 XML 风格的块组成，以固定顺序出现。下游代理通过块名而非行号来读取各块内容。
|
||
|
||
| 块名 | 用途 | 由谁填充 | 由谁消费 |
|
||
|---|---|---|---|
|
||
| `<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` |
|
||
| `<deferred>` | 讨论中出现但属于其他阶段的想法，予以保留以免遗失。当待办事项经过审查但未纳入范围时，包含 `Reviewed Todos` 子节。 | `discuss-phase`（范围蔓延重定向） | 不被自动化代理消费；仅供人工参考 |
|
||
|
||
---
|
||
|
||
## 决策标识符格式
|
||
|
||
`<decisions>` 中的每条决策均带有顺序编号的 `D-NN` 标识符：
|
||
|
||
```markdown
|
||
### Layout style
|
||
- **D-01:** Card-based layout, not timeline or list
|
||
- **D-02:** Each card shows: author avatar, name, timestamp, full post content, reaction counts
|
||
```
|
||
|
||
标识符的作用域限定在阶段内。第 3 阶段中的 `D-01` 与第 7 阶段中的 `D-01` 无关。计划检查器（维度 7）会验证每个 `D-NN` 是否在生成计划中至少有一个任务动作加以覆盖。
|
||
|
||
---
|
||
|
||
## 规范引用
|
||
|
||
`<canonical_refs>` 块为**必填项**。如果代理发现其缺失，会将该 CONTEXT.md 视为不完整并发出警告。条目按主题分组，包含完整相对路径以及对文件所决定或定义内容的简要说明：
|
||
|
||
```markdown
|
||
<canonical_refs>
|
||
## Canonical References
|
||
|
||
**Downstream agents MUST read these before planning or implementing.**
|
||
|
||
### Feed display
|
||
- `docs/features/social-feed.md` — Feed requirements, post card fields, engagement display rules
|
||
- `docs/decisions/adr-012-infinite-scroll.md` — Scroll strategy decision, virtualisation requirements
|
||
|
||
### Empty states
|
||
- `docs/design/empty-states.md` — Empty state patterns, illustration guidelines
|
||
|
||
</canonical_refs>
|
||
```
|
||
|
||
当项目没有外部规格文档时，该节应明确说明：
|
||
|
||
```
|
||
No external specs — requirements fully captured in decisions above
|
||
```
|
||
|
||
在 `<decisions>` 中散落的内联提及（如"参见 ADR-019"）是不够的；代理需要在专用节中获取完整路径。
|
||
|
||
---
|
||
|
||
## 决策覆盖关卡关系
|
||
|
||
计划检查器的**维度 7：上下文合规性**在规划完成后执行覆盖关卡检查：
|
||
|
||
1. `<decisions>` 中的每个 `D-NN` 标识符必须出现在至少一个计划任务的 `<action>` 或说明中。
|
||
2. 任何任务均不得实现 `<deferred>` 中列出的内容（即范围蔓延）。
|
||
3. `Claude's Discretion` 领域免于此检查——规划者可自由选择。
|
||
|
||
决策被成功纳入计划的 CONTEXT.md 被视为合规。决策被悄然丢弃或部分交付的 CONTEXT.md 会触发**维度 7b：范围缩减检测**，这始终是一个**阻断项**。
|
||
|
||
---
|
||
|
||
## SPEC.md 集成
|
||
|
||
当 `/gsd-spec-phase` 在讨论阶段之前运行时，`check_spec` 步骤会找到 `*-SPEC.md` 文件并激活 `<spec_lock>`：
|
||
|
||
```markdown
|
||
<spec_lock>
|
||
## Requirements (locked via SPEC.md)
|
||
|
||
**12 requirements are locked.** See `03-SPEC.md` for full requirements, boundaries, and acceptance criteria.
|
||
|
||
Downstream agents MUST read `03-SPEC.md` before planning or implementing. Requirements are not duplicated here.
|
||
|
||
**In scope (from SPEC.md):** [copied from SPEC.md Boundaries]
|
||
**Out of scope (from SPEC.md):** [copied from SPEC.md Boundaries]
|
||
|
||
</spec_lock>
|
||
```
|
||
|
||
当 `<spec_lock>` 存在时，`<decisions>` 中仅包含来自讨论的实现决策——即"如何做"，而非"做什么"。需求不会在两个文件之间重复。
|
||
|
||
---
|
||
|
||
## 页脚
|
||
|
||
每份 CONTEXT.md 以身份页脚结尾：
|
||
|
||
```markdown
|
||
---
|
||
|
||
*Phase: XX-name*
|
||
*Context gathered: [date]*
|
||
```
|
||
|
||
---
|
||
|
||
## 相关内容
|
||
|
||
- [PLAN.md 结构](plan-md.md)
|
||
- [规划产物](planning-artifacts.md)
|
||
- [讨论模式](../workflow-discuss-mode.md)
|
||
- [文档索引](../README.md)
|