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>
7.3 KiB
Referência do esquema CONTEXT.md
Um CONTEXT.md por fase é o mecanismo do GSD Core para capturar decisões de implementação durante /gsd-discuss-phase. É a principal entrada upstream para os agentes de pesquisa e planejamento. Esta página documenta sua estrutura. Consulte o índice de documentação.
Visão geral
Toda fase que passou pelo fluxo de trabalho de discussão produz um CONTEXT.md em:
.planning/phases/<NN>-<slug>/<NN>-CONTEXT.md
Por exemplo: .planning/phases/03-post-feed/03-CONTEXT.md.
O arquivo é produzido por write_context em gsd-core/workflows/discuss-phase.md (ou seus caminhos expressos de ingestão de PRD / ADR). Ele nunca é editado manualmente durante a operação normal — o fluxo de trabalho discuss-phase o escreve e os agentes downstream o leem como uma fonte de verdade selada.
Frontmatter
CONTEXT.md não possui frontmatter YAML. Os metadados ficam inline no topo do corpo:
# Phase [X]: [Name] - Context
**Gathered:** [ISO date]
**Status:** Ready for planning
O campo Status é sempre Ready for planning quando o arquivo é escrito pela primeira vez. Ele não é atualizado após a criação.
Estrutura de blocos
O corpo é dividido em blocos nomeados no estilo XML. Os blocos aparecem em uma ordem fixa e são lidos pelos agentes downstream pelo nome do bloco, não pelo número de linha.
| Bloco | Finalidade | Preenchido por | Consumido por |
|---|---|---|---|
<domain> |
Define o limite da fase — o que esta fase entrega e o que está explicitamente fora do escopo. Ancora a barreira de escopo ao longo do planejamento e execução. | discuss-phase (do objetivo da fase em ROADMAP.md) |
gsd-planner, gsd-plan-checker (conformidade de escopo) |
<spec_lock> |
Presente apenas quando um *-SPEC.md foi encontrado pela etapa check_spec. Lista contagens de requisitos bloqueados e limites de escopo; os agentes são orientados a ler SPEC.md diretamente para requisitos completos. |
discuss-phase (condicional) |
gsd-planner (lê SPEC.md em vez de reler os requisitos aqui) |
<decisions> |
Decisões de implementação capturadas durante a discussão, identificadas com identificadores D-NN. As categorias emergem do que foi realmente discutido, em vez de uma taxonomia fixa. Inclui uma subseção Claude's Discretion para áreas que o usuário delegou. |
discuss-phase (discussão interativa) |
gsd-planner (decisões bloqueadas devem ser implementadas), gsd-plan-checker (conformidade com a Dimensão 7) |
<canonical_refs> |
Caminhos relativos completos para cada spec, ADR, documento de funcionalidade ou documento de design relevante para esta fase. Obrigatório — todo CONTEXT.md deve ter esta seção. Os agentes devem ler os arquivos listados antes de planejar ou implementar. | discuss-phase (acumulado de refs do ROADMAP.md + referências do usuário durante a discussão + exploração do código) |
gsd-phase-researcher, gsd-planner |
<code_context> |
Ativos reutilizáveis, padrões estabelecidos e pontos de integração descobertos durante a etapa scout_codebase. Orienta os agentes em direção ao código existente em vez de reimplementar. |
discuss-phase (exploração do código) |
gsd-planner, gsd-phase-researcher |
<specifics> |
Referências concretas do tipo "quero assim", comparações de produtos ou exemplos específicos capturados verbatim durante a discussão. | discuss-phase (entrada livre do usuário) |
gsd-planner |
<deferred> |
Ideias que surgiram na discussão mas pertencem a outras fases. Preservadas para não serem perdidas. Inclui uma subseção Reviewed Todos quando os todos foram revisados mas não incorporados ao escopo. |
discuss-phase (redirecionamento de escopo expandido) |
Não consumido por agentes automatizados; somente referência humana |
Formato do identificador de decisão
Cada decisão em <decisions> carrega um identificador sequencial D-NN:
### 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
Os identificadores têm escopo por fase. D-01 na Fase 3 não tem relação com D-01 na Fase 7. O verificador de planos (Dimensão 7) verifica se cada D-NN é atendido por pelo menos uma ação de tarefa nos planos gerados.
Referências canônicas
O bloco <canonical_refs> é obrigatório. Agentes que o encontram ausente tratam o CONTEXT.md como incompleto e exibem um aviso. As entradas são agrupadas por tópico e contêm um caminho relativo completo mais uma breve declaração do que o arquivo decide ou define:
<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>
Quando um projeto não tem specs externas, a seção declara isso explicitamente:
No external specs — requirements fully captured in decisions above
Menções inline como "ver ADR-019" espalhadas em <decisions> são insuficientes; os agentes precisam do caminho completo na seção dedicada.
Relação com o portão de cobertura de decisões
A Dimensão 7: Conformidade com o Contexto do verificador de planos impõe um portão de cobertura após o planejamento:
- Todo identificador
D-NNem<decisions>deve aparecer em pelo menos um<action>ou justificativa de tarefa do plano. - Nenhuma tarefa pode implementar algo listado em
<deferred>(expansão de escopo). - Áreas de
Claude's Discretionsão isentas desta verificação — o planejador pode escolher livremente.
Um CONTEXT.md cujas decisões sobrevivem aos planos é considerado conforme. Um CONTEXT.md cujas decisões são silenciosamente descartadas ou parcialmente entregues aciona a Dimensão 7b: Detecção de Redução de Escopo, que é sempre um BLOQUEADOR.
Integração com SPEC.md
Quando /gsd-spec-phase foi executado antes de discutir uma fase, a etapa check_spec encontra o arquivo *-SPEC.md e ativa o <spec_lock>:
<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>
Quando <spec_lock> está presente, <decisions> contém apenas decisões de implementação da discussão — o "como", não o "o quê". Os requisitos não são duplicados entre os dois arquivos.
Rodapé
Todo CONTEXT.md termina com um rodapé de identidade:
---
*Phase: XX-name*
*Context gathered: [date]*