golem15/msd-core
4
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rebrand to GSD Core and restructure docs with Diataxis (#605)

Browse Source 
* chore: wire docs/agents config into AGENTS.md Agent skills section

Add the `## Agent skills` discovery block pointing the engineering
skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md
files (issue tracker, triage label mapping, single-context domain docs).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: rebrand to GSD Core and restructure docs with Diataxis

Reorganise the root README and docs/ around the Diataxis framework
(tutorials, how-to guides, reference, explanation), add new how-to
guides and schema references (STATE.md / CONTEXT.md / PLAN.md /
planning artifacts), and cross-link the whole set. Update the lone
legacy gsd-build reference to open-gsd; keep internal get-shit-done/
filesystem paths unchanged (directory rename tracked separately in
open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN
localised trees to mirror the new structure.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: backfill changeset PR number (#605)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-06-02 08:13:09 -04:00
committed by GitHub
parent 8c47dcb1c1
commit 3bb2f8f1c5
200 changed files with 46813 additions and 8415 deletions
Download Patch File Download Diff File Expand all files Collapse all files

148
docs/pt-BR/reference/context-md.md Normal file
View File

@@ -0,0 +1,148 @@
# 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](../README.md).
---
## 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 `get-shit-done/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:
```markdown
# 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`:
```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
```
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:
```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>
```
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:
1. Todo identificador `D-NN` em `<decisions>` deve aparecer em pelo menos um `<action>` ou justificativa de tarefa do plano.
2. Nenhuma tarefa pode implementar algo listado em `<deferred>` (expansão de escopo).
3. Áreas de `Claude's Discretion` sã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>`:
```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>
```
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:
```markdown
---
*Phase: XX-name*
*Context gathered: [date]*
```
---
## Relacionados
- [Esquema PLAN.md](plan-md.md)
- [Artefatos de planejamento](planning-artifacts.md)
- [Modos de discussão](../workflow-discuss-mode.md)
- [Índice de documentação](../README.md)

249
docs/pt-BR/reference/plan-md.md Normal file
View File

@@ -0,0 +1,249 @@
# Referência do esquema PLAN.md
Um `PLAN.md` por plano é a unidade executável de trabalho do GSD Core — um documento estruturado que instrui exatamente um agente executor sobre o que construir e como verificar se foi construído corretamente. Esta página documenta sua estrutura. Veja o [índice da documentação](../README.md).
---
## Visão geral
Os planos ficam dentro de diretórios de fase em:
```
.planning/phases/<NN>-<slug>/<NN>-<PP>-PLAN.md
```
Por exemplo: `.planning/phases/03-post-feed/03-02-PLAN.md` (Fase 3, Plano 2).
Os planos são produzidos pelo agente `gsd-planner` (disparado por `/gsd:plan-phase`) e consumidos por `execute-phase`. Uma fase normalmente contém entre um e quatro planos; os planos dentro de uma fase são atribuídos a ondas de execução para que trabalhos independentes sejam executados em paralelo.
---
## Frontmatter YAML
Todo PLAN.md começa com um bloco de frontmatter YAML entre delimitadores `---`.
### Exemplo comentado
```yaml
---
phase: 03-post-feed
plan: 02
type: execute
wave: 2
depends_on: ["03-01"]
files_modified:
- src/components/PostFeed.tsx
- src/components/PostCard.tsx
- src/app/feed/page.tsx
autonomous: true
requirements: ["FEED-01", "FEED-03"]
user_setup: []
must_haves:
truths:
- "User can scroll through posts from followed accounts"
- "Each post shows author avatar, name, timestamp, and content"
- "Empty state appears when no posts exist"
artifacts:
- path: "src/components/PostFeed.tsx"
provides: "Scrollable post list"
min_lines: 40
- path: "src/components/PostCard.tsx"
provides: "Individual post card"
exports: ["PostCard"]
key_links:
- from: "src/components/PostFeed.tsx"
to: "/api/feed"
via: "fetch in useEffect"
pattern: "fetch.*api/feed"
---
```
### Referência dos campos de frontmatter
| Campo | Obrigatório | Tipo | Finalidade |
|---|---|---|---|
| `phase` | Sim | string | Identificador da fase, ex.: `03-post-feed`. |
| `plan` | Sim | string | Número do plano dentro da fase, ex.: `02`. |
| `type` | Sim | `execute` ou `tdd` | `execute` para planos padrão; `tdd` para planos orientados a testes, onde os testes são escritos antes da implementação. |
| `wave` | Sim | inteiro | Onda de execução. Planos na onda 1 são executados em paralelo (sem dependências). Planos na onda 2 ou superior aguardam a conclusão de todos os planos da onda anterior. Pré-calculado durante o planejamento pelo `gsd-planner`. |
| `depends_on` | Sim | array de IDs de planos | Planos dos quais este plano depende. Array vazio = onda 1. Exemplo: `["03-01"]` significa que este plano é executado após o Plano 01 da Fase 3. |
| `files_modified` | Sim | array de caminhos | Todos os arquivos que este plano cria ou modifica. Usado pelo verificador de planos para detectar conflitos de arquivos na mesma onda e pelo execute-phase para rastreamento de merge. |
| `autonomous` | Sim | booleano | `true` quando todas as tarefas são do tipo `auto`. `false` quando o plano contém alguma tarefa `checkpoint:*` que requer interação humana. |
| `requirements` | Sim | array de IDs | IDs de requisitos do ROADMAP.md que este plano atende. Todo ID de requisito de fase deve aparecer no campo `requirements` de pelo menos um plano. Arrays vazios são um BLOQUEADOR. |
| `user_setup` | Não | array de objetos | Etapas de configuração de serviços externos que o Claude não pode automatizar (criação de conta, recuperação de segredos, configuração de painel). Quando presente, o execute-phase gera um checklist `USER-SETUP.md` para o desenvolvedor. |
| `must_haves` | Sim | objeto | Critérios de verificação orientados ao objetivo final. Veja abaixo. |
---
## Campo `must_haves`
`must_haves` captura o que deve ser observavelmente verdadeiro para que o objetivo da fase seja alcançado. É derivado durante o planejamento e verificado após a execução pelo agente `gsd-verifier`.
### Sub-campos
| Sub-campo | Tipo | Finalidade |
|---|---|---|
| `truths` | array de strings | Comportamentos observáveis do ponto de vista do usuário. Cada um deve ser verificável. Exemplo: `"User can send a message"`, não `"WebSocket library installed"`. |
| `artifacts` | array de objetos | Arquivos que devem existir com implementação substantiva (não stubs). |
| `artifacts[].path` | string | Caminho do arquivo relativo à raiz do projeto. |
| `artifacts[].provides` | string | Qual capacidade este arquivo entrega. |
| `artifacts[].min_lines` | inteiro (opcional) | Contagem mínima de linhas para não ser considerado um stub. |
| `artifacts[].exports` | array de strings (opcional) | Exportações nomeadas esperadas para verificação. |
| `artifacts[].contains` | string (opcional) | Expressão regular ou padrão literal que deve aparecer no arquivo. |
| `key_links` | array de objetos | Conexões críticas entre artefatos — a ligação que faz o sistema funcionar de ponta a ponta. |
| `key_links[].from` | string | Arquivo ou componente de origem. |
| `key_links[].to` | string | Arquivo, endpoint ou módulo de destino. |
| `key_links[].via` | string | Descrição de como eles se conectam (ex.: `fetch in useEffect`, `Prisma query`, `import`). |
| `key_links[].pattern` | string (opcional) | Expressão regular para verificar se a conexão existe no código-fonte. |
---
## Estrutura do corpo
Após o frontmatter, o corpo do plano utiliza blocos no estilo XML lidos pelo agente executor.
### `<objective>`
Declara o que o plano entrega e por que isso importa para o projeto:
```xml
<objective>
Implement the post feed as a scrollable card list.
Purpose: Core display feature for the social feed phase.
Output: PostFeed and PostCard components wired to /api/feed.
</objective>
```
### `<execution_context>`
Lista os arquivos de workflow que o executor lê antes de começar. Sempre inclui o workflow execute-plan; adiciona a referência de checkpoints quando o plano contém tarefas de checkpoint:
```xml
<execution_context>
@~/.claude/get-shit-done/workflows/execute-plan.md
@~/.claude/get-shit-done/templates/summary.md
</execution_context>
```
### `<context>`
Referencia os arquivos-fonte que o executor precisa ler. Inclui documentos de planejamento no nível do projeto e quaisquer arquivos-fonte cujos padrões ou tipos o plano deve replicar. Arquivos `SUMMARY.md` de planos anteriores são incluídos apenas quando há uma dependência genuína (tipos importados, decisão compartilhada) — não de forma reflexiva:
```xml
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@src/components/UserCard.tsx
</context>
```
### `<tasks>`
Contém um ou mais elementos `<task>`. Todo elemento de tarefa deve ter `<name>`, `<files>`, `<read_first>`, `<action>`, `<verify>`, `<acceptance_criteria>` e `<done>` para tarefas do tipo `type="auto"`.
---
## Tipos de tarefa
| Tipo | Uso | Autonomia |
|---|---|---|
| `auto` | Tudo o que o executor pode fazer de forma independente. | Totalmente autônomo. |
| `checkpoint:human-verify` | Verificação visual ou funcional que requer que um humano observe uma UI ou serviço em execução. | Pausa a execução; apresenta ao desenvolvedor; retoma com aprovação. |
| `checkpoint:decision` | Escolhas de implementação que surgiram durante a execução e requerem a contribuição do desenvolvedor. | Pausa a execução; apresenta opções; retoma com a seleção. |
| `checkpoint:human-action` | Etapas manuais verdadeiramente inevitáveis (criação de conta, interação com hardware). Usadas com parcimônia. | Pausa a execução; retoma com confirmação. |
Planos que contêm qualquer tarefa de checkpoint devem definir `autonomous: false` no frontmatter.
---
## Estrutura de tarefa `auto`
```xml
<task type="auto">
<name>Task 1: Create PostCard component</name>
<files>src/components/PostCard.tsx</files>
<read_first>src/components/UserCard.tsx, src/types/post.ts</read_first>
<action>Create PostCard component accepting a Post prop (id, authorId, content, createdAt,
reactionCount). Render author avatar using UserAvatar from UserCard pattern. Show timestamp
using date-fns formatDistanceToNow. Export as named export PostCard.</action>
<verify>npx tsc --noEmit</verify>
<acceptance_criteria>
- src/components/PostCard.tsx exports named export PostCard
- PostCard.tsx contains "reactionCount" prop usage
- npx tsc --noEmit exits 0
</acceptance_criteria>
<done>PostCard renders post content with author and timestamp</done>
</task>
```
### Campos obrigatórios para tarefas `auto`
| Campo | Regra |
|---|---|
| `<files>` | Todo arquivo que a tarefa cria ou modifica. O executor escreve apenas nesses arquivos. |
| `<read_first>` | Arquivos que o executor deve ler antes de tocar em qualquer coisa — o arquivo sendo modificado, qualquer arquivo de padrão de referência, qualquer arquivo cujos tipos ou convenções devem ser replicados. |
| `<action>` | Instruções concretas com identificadores exatos, caminhos de arquivo, assinaturas de função e valores esperados. Nunca diz "alinhe X com Y" sem especificar o estado-alvo. Nunca contém blocos de código cercados ou implementações completas. |
| `<verify>` | Um comando ou verificação executável que comprova o sucesso da tarefa. Deve distinguir aprovação de falha — `echo "done"` não é válido. |
| `<acceptance_criteria>` | Condições verificáveis: strings verificáveis por grep, códigos de saída de comandos, comportamentos observáveis. Sem linguagem subjetiva ("parece correto", "configurado corretamente"). |
| `<done>` | Uma declaração curta e mensurável do resultado concluído. |
---
## Dimensões de qualidade do plano
O agente `gsd-plan-checker` avalia cada PLAN.md em 12 dimensões antes do início da execução. Um plano que falha em qualquer verificação de severidade BLOQUEADOR é devolvido ao `gsd-planner` para revisão (até 3 iterações):
| Dimensão | O que verifica |
|---|---|
| **1 — Cobertura de Requisitos** | Todo ID de requisito de fase do ROADMAP.md aparece no campo de frontmatter `requirements` de pelo menos um plano e possui tarefa(s) correspondente(s). |
| **2 — Completude das Tarefas** | Toda tarefa `auto` contém todos os campos obrigatórios (`<files>`, `<action>`, `<verify>`, `<acceptance_criteria>`, `<done>`). Nenhum campo vago ou vazio. |
| **3 — Correção de Dependências** | As referências de `depends_on` são válidas, acíclicas e consistentes com os números de onda. Um plano da Onda N depende apenas de planos em ondas < N. |
| **4 — Links Principais Planejados** | Artefatos em `must_haves.key_links` possuem tarefas correspondentes que implementam a ligação — não apenas a criação do artefato. |
| **5 — Sanidade do Escopo** | Os planos permanecem dentro do orçamento de contexto: 2–3 tarefas por plano (4 = aviso, 5+ = BLOQUEADOR), ≤ 8–10 arquivos por plano (15+ = BLOQUEADOR). |
| **6 — Derivação de Verificação** | `must_haves.truths` são comportamentos observáveis pelo usuário, não detalhes de implementação. Artefatos mapeiam para truths. Links principais cobrem a ligação crítica. |
| **7 — Conformidade de Contexto** | Toda decisão `D-NN` do CONTEXT.md é abordada por pelo menos uma tarefa. Nenhuma tarefa implementa nada de `<deferred>`. |
| **7b — Detecção de Redução de Escopo** | As ações das tarefas não reduzem silenciosamente uma decisão bloqueada para um "v1", "stub" ou "melhoria futura" sem entregar o escopo completo da decisão. Sempre é um BLOQUEADOR quando encontrado. |
| **7c — Conformidade de Nível Arquitetural** | As tarefas atribuem capacidades ao nível correto conforme o Mapa de Responsabilidade Arquitetural do RESEARCH.md (quando presente). Capacidades sensíveis à segurança no nível errado são BLOCKEADOREs. |
| **8 — Conformidade Nyquist** | Quando `workflow.nyquist_validation` está habilitado e RESEARCH.md existe, toda tarefa tem um comando de verificação `<automated>`, nenhuma janela consecutiva de 3 tarefas carece de cobertura, e VALIDATION.md está presente. |
| **9 — Contratos de Dados Entre Planos** | Quando planos compartilham pipelines de dados, suas transformações são compatíveis — nenhum plano remove dados que outro plano precisa em sua forma original. |
| **10 — Conformidade com CLAUDE.md** | Os planos respeitam convenções específicas do projeto, padrões proibidos, ferramentas obrigatórias e requisitos de segurança do `./CLAUDE.md`. |
| **11 — Resolução de Pesquisa** | Quando RESEARCH.md existe, sua seção `## Open Questions` está marcada como `(RESOLVED)` antes de o planejamento prosseguir. |
| **12 — Conformidade de Padrões** | Quando PATTERNS.md existe, as tarefas referenciam os padrões analógicos corretos para cada arquivo novo ou modificado. |
---
## Modelo de execução por ondas
Os números de onda são pré-calculados durante o planejamento. O execute-phase agrupa os planos por número de onda e executa os planos de cada onda em paralelo:
```
Wave 1: Plan 01, Plan 02, Plan 03 (all run simultaneously — no dependencies)
Wave 2: Plan 04 (waits for Wave 1 to complete)
Wave 3: Plan 05 (waits for Wave 2 to complete)
```
Planos dentro de uma mesma onda que modificam arquivos sobrepostos não devem estar na mesma onda — a Dimensão 3 do verificador de planos sinaliza isso como um BLOQUEADOR.
---
## Saída do plano
Após a execução bem-sucedida de um plano, o executor escreve um SUMMARY.md em:
```
.planning/phases/<NN>-<slug>/<NN>-<PP>-SUMMARY.md
```
O SUMMARY.md é o registro canônico do que foi construído. Planos subsequentes na mesma fase podem referenciá-lo quando há uma dependência genuína em seus tipos ou decisões.
---
## Relacionados
- [Esquema CONTEXT.md](context-md.md)
- [Artefatos de planejamento](planning-artifacts.md)
- [Funcionalidades](../FEATURES.md)
- [Índice da documentação](../README.md)

225
docs/pt-BR/reference/planning-artifacts.md Normal file
View File

@@ -0,0 +1,225 @@
# Referência de artefatos de planejamento
O diretório `.planning/` é a memória compartilhada do GSD Core para um projeto. Todos os fluxos de trabalho leem, gravam e deixam um rastro auditável de decisões. Esta página mapeia cada arquivo, sua finalidade e qual comando o produz ou consome. Consulte o [índice de documentação](../README.md).
---
## Estrutura de diretórios
```
.planning/
├── PROJECT.md # Identidade do projeto e valor central
├── ROADMAP.md # Listagem de marcos e fases com objetivos
├── REQUIREMENTS.md # Critérios de aceitação numerados
├── STATE.md # Rastreador de posição em andamento
├── config.json # Configuração de fluxo de trabalho e modelo
├── MILESTONES.md # Arquivo de marcos (opcional)
├── BACKLOG.md # Trabalho adiado e futuro (opcional)
├── LEARNINGS.md # Aprendizados acumulados entre fases (opcional)
├── DECISIONS-INDEX.md # Resumo contínuo de decisões anteriores (opcional)
├── METHODOLOGY.md # Frameworks interpretativos reutilizáveis (opcional)
├── HANDOFF.json # Estado de pausa legível por máquina (transitório)
├── codebase/ # Mapas do código-base (opcional)
│ ├── architecture.md
│ ├── stack.md
│ └── ...
├── intel/ # Índice de símbolos consultável (opcional, intel.enabled)
│ └── API-SURFACE.md
└── phases/
└── <NN>-<slug>/ # Um diretório por fase
├── <NN>-CONTEXT.md # Decisões de implementação (discuss-phase)
├── <NN>-DISCUSSION-LOG.md # Auditoria legível da discussão (discuss-phase)
├── <NN>-RESEARCH.md # Resultados de pesquisa técnica (plan-phase)
├── <NN>-VALIDATION.md # Estratégia de cobertura de testes Nyquist (plan-phase)
├── <NN>-PATTERNS.md # Mapa de análogos do código-base (plan-phase, opcional)
├── <NN>-<PP>-PLAN.md # Plano executável (plan-phase, um por plano)
├── <NN>-<PP>-SUMMARY.md # Registro de execução (execute-phase, um por plano)
├── <NN>-VERIFICATION.md # Relatório de verificação dos objetivos da fase (verify-phase)
├── <NN>-UAT.md # Estado persistente de sessão UAT (execute-phase)
└── .continue-here.md # Instruções de retomada após pausa (pause-work)
```
---
## Artefatos no nível raiz
### `PROJECT.md`
| | |
|---|---|
| **Finalidade** | Identidade canônica do projeto: o que é, para quem é, valor central, requisitos, restrições e decisões-chave. Atualizado ao longo do ciclo de vida do projeto conforme o produto evolui. |
| **Produzido por** | `/gsd-new-project` (criação inicial); atualizado por `/gsd-complete-milestone` à medida que as decisões são validadas. |
| **Consumido por** | Todos os fluxos de trabalho de planejamento; `gsd-phase-researcher`, `gsd-planner` (contexto); `discuss-phase` (decisões anteriores); `gsd-plan-checker` (restrições do projeto). |
### `ROADMAP.md`
| | |
|---|---|
| **Finalidade** | Listagem de marcos e fases com objetivos, IDs de requisitos, critérios de sucesso e referências canônicas por fase. A fonte única de verdade sobre o que o projeto está construindo e em que ordem. |
| **Produzido por** | `/gsd-new-project` (criação inicial); atualizado por `/gsd-phase --insert` e `/gsd-complete-milestone`. |
| **Consumido por** | `/gsd-discuss-phase`, `/gsd-plan-phase`, `/gsd-execute-phase`; todos os comandos de orquestração que precisam de informações de fase; `gsd-planner`, `gsd-plan-checker`, `gsd-phase-researcher`. |
### `REQUIREMENTS.md`
| | |
|---|---|
| **Finalidade** | Critérios de aceitação numerados e verificáveis para o projeto. Cada requisito possui um ID (ex.: `AUTH-01`) que mapeia para as fases do roadmap. Marca os requisitos como concluídos conforme as fases são executadas. |
| **Produzido por** | `/gsd-new-project` (criação inicial); requisitos marcados como concluídos por `execute-phase`. |
| **Consumido por** | `gsd-planner` (os planos devem contemplar todos os IDs de requisitos da fase); `gsd-plan-checker` Dimensão 1 (cobertura de requisitos); `discuss-phase` (requisitos anteriores). |
### `STATE.md`
| | |
|---|---|
| **Finalidade** | Rastreador de posição em andamento — fase e plano atuais, métricas de progresso, decisões acumuladas, notas de continuidade de sessão. Lido no início de toda execução de fluxo de trabalho. Atualizado após cada ação significativa. |
| **Produzido por** | `/gsd-new-project` (criação inicial); atualizado continuamente por todos os fluxos de fase, `/gsd-pause-work`, `/gsd-resume-work`. |
| **Consumido por** | Todos os fluxos de orquestração; `/gsd-progress`; execução de tarefas avulsas via `/gsd-quick`; `gsd-planner` e `gsd-phase-researcher` (decisões do projeto). |
Consulte o [esquema de STATE.md](state-md.md) para a referência completa de campos.
### `config.json`
| | |
|---|---|
| **Finalidade** | Configuração do fluxo de trabalho: perfis de modelo, alternâncias de pesquisa e verificador de plano, estratégia de ramificação git, validação Nyquist, configurações de paralelização e substituições de modelo por agente. |
| **Produzido por** | `/gsd-new-project` (criação inicial); `/gsd-settings` (edição interativa). |
| **Consumido por** | Todos os fluxos de trabalho e subagentes — lido no momento de inicialização via `gsd-tools query config-get`. |
Consulte [CONFIGURATION](../CONFIGURATION.md) para o esquema completo.
### `MILESTONES.md` (opcional)
| | |
|---|---|
| **Finalidade** | Registro histórico de marcos concluídos. Preenchido à medida que cada marco é encerrado; fornece um instantâneo de arquivo do que foi entregue e quando. |
| **Produzido por** | `/gsd-complete-milestone`. |
| **Consumido por** | `/gsd-audit-milestone`; revisão humana. |
### `DECISIONS-INDEX.md` (opcional)
| | |
|---|---|
| **Finalidade** | Resumo contínuo limitado de decisões capturadas em arquivos CONTEXT.md de fases anteriores. Quando presente, o `discuss-phase` lê este único arquivo em vez de ler até três arquivos CONTEXT.md anteriores individualmente, economizando orçamento de contexto. |
| **Produzido por** | Gerado quando o número de fases anteriores ultrapassa o limite de leitura contínua. |
| **Consumido por** | `discuss-phase` (etapa `load_prior_context`). |
### `HANDOFF.json` (transitório)
| | |
|---|---|
| **Finalidade** | Estado de pausa legível por máquina gravado quando o trabalho é interrompido. Contém o ponto de retomada, contexto em andamento e instruções de continuação. Consumido exatamente uma vez — na retomada. |
| **Produzido por** | `/gsd-pause-work`. |
| **Consumido por** | `/gsd-resume-work`. |
---
## Artefatos por fase
Todos os arquivos por fase ficam em `.planning/phases/<NN>-<slug>/`, onde `NN` é o número da fase com zero à esquerda e `slug` é o nome da fase com hifens.
### `<NN>-CONTEXT.md`
| | |
|---|---|
| **Finalidade** | Decisões de implementação capturadas antes do início do planejamento. Contém o limite da fase (`<domain>`), decisões bloqueadas com identificadores `D-NN` (`<decisions>`), referências canônicas de documentos (`<canonical_refs>`), insights de código existente (`<code_context>`), inspirações específicas (`<specifics>`) e ideias adiadas (`<deferred>`). |
| **Produzido por** | `/gsd-discuss-phase` (discussão interativa ou caminhos expressos PRD/ADR). |
| **Consumido por** | `gsd-phase-researcher` (o que investigar); `gsd-planner` (decisões bloqueadas); `gsd-plan-checker` Dimensão 7 (conformidade de contexto). |
Consulte o [esquema de CONTEXT.md](context-md.md) para a referência completa de campos.
### `<NN>-DISCUSSION-LOG.md`
| | |
|---|---|
| **Finalidade** | Rastro de auditoria legível da sessão de discuss-phase: áreas discutidas, opções apresentadas, seleções feitas, ideias adiadas e itens deixados ao critério do Claude. Não é consumido por fluxos de trabalho automatizados. |
| **Produzido por** | `/gsd-discuss-phase` (etapa `git_commit`). |
| **Consumido por** | Revisão humana; retrospectivas. |
### `<NN>-RESEARCH.md`
| | |
|---|---|
| **Finalidade** | Resultados de pesquisa técnica produzidos antes do planejamento. Responde à pergunta "O que preciso saber para planejar bem esta fase?" — abrange análise de domínio, padrões, riscos, um Mapa de Responsabilidade Arquitetural e uma seção de Arquitetura de Validação (usada pelo gate Nyquist). |
| **Produzido por** | `/gsd-plan-phase` via agente `gsd-phase-researcher`. |
| **Consumido por** | `gsd-planner` (entradas de planejamento); `gsd-plan-checker` Dimensão 7c (conformidade de camada), Dimensão 8 (Nyquist), Dimensão 11 (resolução de pesquisa); `gsd-pattern-mapper` (fonte de lista de arquivos). |
### `<NN>-VALIDATION.md`
| | |
|---|---|
| **Finalidade** | Estratégia de validação inspirada no Nyquist, derivada da seção `## Validation Architecture` do RESEARCH.md. Especifica requisitos de cobertura de testes automatizados que os planos devem respeitar. |
| **Produzido por** | `/gsd-plan-phase` (Etapa 5.5, quando `workflow.nyquist_validation` está habilitado e o RESEARCH.md contém uma seção de Arquitetura de Validação). |
| **Consumido por** | `gsd-plan-checker` Dimensão 8 (gate Check 8e — deve existir antes de os checks Nyquist prosseguirem); `gsd-verifier`. |
### `<NN>-PATTERNS.md`
| | |
|---|---|
| **Finalidade** | Mapa de análogos do código-base produzido pelo `gsd-pattern-mapper`. Para cada arquivo a ser criado ou modificado nesta fase, identifica o análogo existente mais próximo, classifica o papel e o fluxo de dados do arquivo e extrai trechos concretos de código. Orienta o planejador em direção a padrões consistentes. |
| **Produzido por** | `/gsd-plan-phase` via agente `gsd-pattern-mapper` (opcional; ignorado se `workflow.pattern_mapper: false`). |
| **Consumido por** | `gsd-planner` (orientação de padrões); `gsd-plan-checker` Dimensão 12 (conformidade de padrões). |
### `<NN>-<PP>-PLAN.md`
| | |
|---|---|
| **Finalidade** | Plano executável para uma única unidade de trabalho dentro da fase. Contém frontmatter YAML (onda, dependências, arquivos, requisitos, `must_haves`), um objetivo, referências de contexto, tarefas estruturadas em XML com campos `<read_first>`, `<action>`, `<verify>` e `<acceptance_criteria>`, e critérios de verificação. |
| **Produzido por** | `/gsd-plan-phase` via agente `gsd-planner`. Um arquivo por plano — ex.: `03-02-PLAN.md` é Fase 3, Plano 2. |
| **Consumido por** | `/gsd-execute-phase` (agente executor lê o plano e executa as tarefas); `gsd-plan-checker` (revisão de qualidade pré-execução); `gsd-verifier` (lê `must_haves` para verificação pós-execução). |
Consulte o [esquema de PLAN.md](plan-md.md) para a referência completa de campos.
### `<NN>-<PP>-SUMMARY.md`
| | |
|---|---|
| **Finalidade** | Registro de execução gravado após a conclusão de um plano. Documenta o que foi construído, desvios em relação ao plano, uma autoverificação em relação aos critérios de aceitação e o grafo de dependências da fase. |
| **Produzido por** | Agente executor de `execute-phase` (gravado ao final da execução de cada plano). |
| **Consumido por** | `/gsd-progress` (status da fase); `gsd-planner` (quando um plano subsequente tem dependência genuína da saída de um plano anterior); `milestone-summary`. |
### `<NN>-VERIFICATION.md`
| | |
|---|---|
| **Finalidade** | Relatório de verificação dos objetivos da fase. Verifica `must_haves.truths`, `must_haves.artifacts` e `must_haves.key_links` de todos os planos em relação ao código-base real após a execução. Registra `status: passed | gaps_found | human_needed`. |
| **Produzido por** | `/gsd-verify-work` (ou a etapa de verificação dentro de `/gsd-execute-phase`). |
| **Consumido por** | Gate de fase encerrada do `plan-phase` (um VERIFICATION.md com `status: passed` marca a fase como `Complete` e bloqueia replanejamento sem `--force`); `/gsd-progress`; revisão humana. |
### `<NN>-UAT.md`
| | |
|---|---|
| **Finalidade** | Rastreamento persistente de sessão UAT. Registra cada caso de teste, comportamento observável esperado, resultado e resposta do desenvolvedor ao longo de uma sessão UAT ativa. Carrega frontmatter YAML (`status`, `phase`, `source`, timestamps). |
| **Produzido por** | `/gsd-audit-uat` (sessão UAT interativa). |
| **Consumido por** | `/gsd-audit-uat` (retomada de uma sessão UAT anterior). |
### `.continue-here.md`
| | |
|---|---|
| **Finalidade** | Instruções de retomada legíveis gravadas quando o trabalho em uma fase é pausado. Contém contexto para agentes retomarem: antipadrões críticos, problemas bloqueantes, leitura obrigatória e o comando exato para retomar. |
| **Produzido por** | `/gsd-pause-work`. |
| **Consumido por** | Qualquer fluxo de trabalho que inicia em uma fase — tanto `discuss-phase` quanto `plan-phase` verificam a existência deste arquivo na entrada e exigem que o agente demonstre compreensão de quaisquer antipadrões `blocking` antes de prosseguir. |
---
## Convenções de nomenclatura
| Segmento | Formato | Exemplo |
|---|---|---|
| Diretório de fase | `<NN>-<slug>` | `03-post-feed` |
| Arquivo de nível de fase | `<NN>-<ARTIFACT>.md` | `03-CONTEXT.md` |
| Arquivo de nível de plano | `<NN>-<PP>-<ARTIFACT>.md` | `03-02-PLAN.md` |
| `NN` | Número da fase com zero à esquerda | `03` para Fase 3 |
| `PP` | Número do plano com zero à esquerda dentro da fase | `02` para Plano 2 |
Quando `project_code` está definido no `config.json`, os diretórios de fase usam o código do projeto como prefixo: `CK-03-post-feed` para o código de projeto `CK`, Fase 3.
---
## Relacionados
- [Esquema de STATE.md](state-md.md)
- [Esquema de CONTEXT.md](context-md.md)
- [Esquema de PLAN.md](plan-md.md)
- [Índice de documentação](../README.md)

201
docs/pt-BR/reference/state-md.md Normal file
View File

@@ -0,0 +1,201 @@
# Referência do esquema STATE.md
`STATE.md` é o arquivo de memória viva do projeto do GSD Core — um único documento Markdown que registra em que ponto o projeto se encontra, o que aconteceu por último e o que executar a seguir. Esta página documenta sua estrutura. Consulte o [índice da documentação](../README.md).
---
## Visão geral
Todo projeto gerenciado pelo GSD Core mantém um único `STATE.md` em `.planning/STATE.md`. Ele é lido no início de todo fluxo de trabalho e escrito após toda ação significativa. O arquivo combina:
- **Frontmatter YAML** — campos legíveis por máquina consumidos pelo hook de linha de status (`parseStateMd`) e pelos comandos `gsd-tools state`.
- **Corpo Markdown** — seções legíveis por humanos cobrindo a posição atual, contexto acumulado, continuidade de sessão e métricas de desempenho.
O arquivo é intencionalmente pequeno (meta: menos de 100 linhas). Ele é um resumo do estado do projeto, não um arquivo histórico.
---
## Frontmatter YAML
O frontmatter aparece entre delimitadores `---` no início do arquivo. Todos os campos, exceto `gsd_state_version` e `status`, são opcionais; os campos podem estar ausentes quando seus dados ainda não estão disponíveis.
### Exemplo comentado
```yaml
---
gsd_state_version: '1.0'
milestone: v2.0
milestone_name: Code Quality
status: executing
# Campos de ciclo de vida de fase — todos opcionais (adicionados na v1.40.0, issue #2833)
active_phase: "4.5"
next_action: execute-phase
next_phases: ["4.5"]
progress:
total_phases: 17
completed_phases: 10
total_plans: 84
completed_plans: 47
percent: 59
# Campos adicionais escritos por syncStateFrontmatter
current_phase: "4"
current_phase_name: Observability
current_plan: "3"
last_updated: "2026-06-01T12:34:56.789Z"
last_activity: "2026-06-01"
stopped_at: "Phase 4 P3 execution complete"
paused_at: null
---
```
### Referência de campos
| Campo | Tipo | Quando populado | Finalidade |
|---|---|---|---|
| `gsd_state_version` | string (`'1.0'`) | Sempre | Versão do esquema; escrito na primeira chamada `state.*` por `syncStateFrontmatter`. |
| `milestone` | string (ex.: `v2.0`) | Quando um milestone está configurado | Versão do milestone atual, lida da configuração do projeto. |
| `milestone_name` | string | Quando um milestone está configurado | Rótulo legível do milestone (ex.: `Code Quality`). |
| `status` | string | Sempre | Estágio atual do ciclo de vida. Normalizado por `normalizeStateStatus()` — veja [valores de status](#valores-de-status). |
| `active_phase` | string (ex.: `"4.5"`) | Um comando do orquestrador está em andamento nesta fase | O número da fase atualmente sendo processada. Definido como `null` entre fases. |
| `next_action` | string | Ocioso, com um comando recomendado | O slash command a executar a seguir: `discuss-phase`, `plan-phase`, `execute-phase` ou `verify-phase`. Definido como `null` quando um orquestrador está em andamento ou nenhuma recomendação está disponível. |
| `next_phases` | array YAML flow (ex.: `["4.5"]`) | Acompanha `next_action` | Os IDs de fase aos quais o `next_action` se aplica (tipicamente 1–2 entradas). Definido como `null` nas mesmas condições que `next_action`. |
| `progress.total_phases` | inteiro | Quando dados de fase estão disponíveis | Número total de fases no milestone atual, derivado do ROADMAP.md e do diretório de fases. |
| `progress.completed_phases` | inteiro | Quando dados de fase estão disponíveis | Número de fases que têm todos os resumos de planos em disco (ou seja, todos os planos concluídos). |
| `progress.total_plans` | inteiro | Quando arquivos de plano existem | Soma de todos os arquivos de plano nas fases do milestone atual. |
| `progress.completed_plans` | inteiro | Quando arquivos de resumo existem | Soma dos resumos de planos concluídos (um SUMMARY.md por plano executado). |
| `progress.percent` | inteiro 0–100 | Quando dados de progresso estão disponíveis | Progresso do milestone na **dimensão de fases** (`min(completed_plans/total_plans, completed_phases/total_phases)`). A barra de progresso da linha de status é renderizada somente quando este campo está presente — sua ausência suprime a barra. |
| `current_phase` | string | Quando uma fase está em execução | Número da fase extraído do campo `Current Phase:` do corpo. |
| `current_phase_name` | string | Quando uma fase tem nome | Nome da fase extraído do campo `Current Phase Name:` do corpo. |
| `current_plan` | string | Quando um plano está em andamento | Número do plano extraído do campo `Current Plan:` do corpo. |
| `last_updated` | timestamp ISO-8601 | Sempre (na escrita) | Timestamp da última chamada a `syncStateFrontmatter`; escrito por `realClock.nowIso()`. |
| `last_activity` | string | Quando definido no corpo | Data da última atividade, extraída do campo `Last Activity:` do corpo. |
| `stopped_at` | string | Quando um ponto de parada foi registrado | Descrição da última ação concluída; limitada à seção `## Session` do corpo para evitar correspondência com prosa de arquivo. |
| `paused_at` | string | Quando o projeto está pausado | Descrição de forma livre do ponto de pausa; ausente ou `null` quando não pausado. |
### Valores de status
`normalizeStateStatus()` em `get-shit-done/bin/lib/state-document.cjs` mapeia o texto bruto do corpo para estes valores canônicos:
| Valor canônico | Texto correspondente (sem diferenciação de maiúsculas/minúsculas) |
|---|---|
| `discussing` | contém `discussing` |
| `planning` | contém `planning` ou `ready to plan` |
| `executing` | contém `executing`, `in progress` ou `ready to execute` |
| `verifying` | contém `verif` |
| `completed` | contém `complete` ou `done` |
| `paused` | contém `paused` ou `stopped`, ou `paused_at` está presente |
| `unknown` | nenhuma das anteriores |
Quando um comando do orquestrador está em andamento, a convenção (issue #2833) é escrever o estágio do ciclo de vida diretamente em `status`:
| Comando | `status` durante a execução |
|---|---|
| `/gsd-discuss-phase` | `discussing` |
| `/gsd-plan-phase` | `planning` |
| `/gsd-execute-phase` | `executing` |
| `/gsd-verify-work` | `verifying` |
---
## Cenas de renderização da linha de status
`formatGsdState()` em `hooks/gsd-statusline.js` lê o frontmatter analisado e emite a **primeira cena correspondente**. Se nenhum campo novo do ciclo de vida se aplicar, a renderização cai para o formato original byte a byte, inalterado desde a v1.38.x.
| Cena | Gatilho | Exemplo de exibição |
|---|---|---|
| **1. Fase ativa** | `active_phase` está populado | `v2.0 [██░░░░░░░░] 20% · Phase 4.5 executing` |
| **2. Ocioso, próximo recomendado** | `active_phase` é null E tanto `next_action` quanto `next_phases` estão populados | `v2.0 [██░░░░░░░░] 20% · next execute-phase 4.5` |
| **3. Milestone completo** | `percent` é `100` OU `completed_phases == total_phases` | `v2.0 [██████████] 100% · milestone complete` |
| **4. Fallback padrão** | Nenhuma das anteriores corresponde | `v1.9 Code Quality · executing · ph 1/5` (formato existente) |
**Prioridade de cena:** quando `active_phase` e `next_action` estão populados, a Cena 1 prevalece — um orquestrador está em andamento, portanto uma "próxima recomendação" seria enganosa. Essa prioridade é imposta pela ordem de verificação em `formatGsdState()` e coberta pelo conjunto `"scene priority"` em `tests/enh-2833-phase-lifecycle-statusline.test.cjs`.
A barra de progresso (`[██░░░░░░░░] 20%`) é anexada ao segmento do milestone somente quando `progress.percent` está presente no frontmatter; ausente significa sem barra.
---
## Restrições de análise do frontmatter
O hook de linha de status usa análise baseada em regex (sem biblioteca YAML completa), portanto as seguintes restrições se aplicam. Elas são testadas em `tests/enh-2833-phase-lifecycle-statusline.test.cjs`.
1. **O frontmatter deve começar no primeiro caractere do arquivo.** Qualquer coisa — incluindo comentários — acima do `---` de abertura invalida a correspondência. A linha `---` de abertura deve ser exatamente isso, sem espaços no final.
2. **Comentários dentro de blocos aninhados não são suportados.** O analisador do bloco `progress:` requer que a próxima linha seja `[ \t]+\w+:`. Inserir um `# comment` entre `progress:` e sua primeira chave quebra a correspondência e a barra desaparece. Qualquer documentação pertence ao corpo do `STATE.md`, não dentro dos blocos do frontmatter.
3. **O formato primário de `next_phases` é flow de linha única.** O analisador tenta primeiro `next_phases: ["4.5", "4.6"]`. Sequências em bloco (`- 4.5\n- 4.6`) também são analisadas, mas são menos confiáveis para renderização da linha de status. Prefira flow de linha única para `next_phases` para manter o analisador baseado em regex previsível. Se muitas fases candidatas precisarem ser registradas para fins de documentação, armazene-as no corpo do `STATE.md`.
Se uma mudança futura substituir o analisador de regex por uma biblioteca YAML completa, essas restrições poderão ser relaxadas e os testes atualizados adequadamente.
---
## Seções do corpo Markdown
O corpo (tudo após o `---` de fechamento) segue o template em `get-shit-done/templates/state.md`. As seções padrão são:
### Referência do Projeto
Aponta para `.planning/PROJECT.md`. Contém:
- **Valor central** — a frase de uma linha da seção Core Value do `PROJECT.md`.
- **Foco atual** — qual fase está ativa.
### Posição Atual
Onde o projeto está agora:
| Campo | Formato |
|---|---|
| `Phase:` | `X of Y (Phase name)` |
| `Plan:` | `A of B in current phase` |
| `Status:` | Texto livre, ex.: `Ready to execute`, `Executing Phase 4`, `Phase complete — ready for verification` |
| `Last activity:` | Data ISO (`YYYY-MM-DD`) quando escrito por handler; prosa narrativa quando elaborado pelo executor |
| `Progress:` | Barra visual, ex.: `[████░░░░░░] 40%` |
Os campos `Status:` e `Last activity:` nesta seção são atualizados pelos handlers do GSD quando o valor existente é um padrão de template conhecido (invariante de Knuth: valores elaborados pelo executor são preservados). A lista completa de padrões de handler conhecidos está em `KNOWN_TEMPLATE_DEFAULTS` dentro de `get-shit-done/bin/lib/state-document.cjs`.
### Métricas de Desempenho
Rastreamento de velocidade de execução:
- Total de planos concluídos, duração média por plano.
- Tabela de detalhamento por fase (`Phase | Plans | Total | Avg/Plan`).
- Tendência recente: Improving / Stable / Degrading.
Atualizado após cada conclusão de plano.
### Contexto Acumulado
**Decisões** — um resumo das decisões recentes que afetam o trabalho atual (o log completo vive em `PROJECT.md`). Adicionado via `gsd-tools state add-decision`.
**Todos Pendentes** — contagem e referência a `.planning/todos/pending/`. Capturado via `/gsd-capture`.
**Bloqueadores/Preocupações** — problemas que afetam trabalhos futuros, prefixados com a fase de origem. Adicionado via `gsd-tools state add-blocker`; resolvido via `gsd-tools state resolve-blocker`.
### Continuidade de Sessão
Permite retomada instantânea de sessão:
- `Last session:` — timestamp ISO-8601 da última sessão.
- `Stopped at:` — descrição da última ação concluída.
- `Resume file:` — caminho para um arquivo `.continue-here*.md` se existir, caso contrário `None`.
---
## Compatibilidade retroativa
Os campos de ciclo de vida de fase (`active_phase`, `next_action`, `next_phases` e `progress.percent` para a barra) são **aditivos e opt-in por projeto**:
- Um `STATE.md` sem nenhum dos campos de ciclo de vida populados é renderizado **byte a byte de forma idêntica** à v1.38.x e anteriores.
- Adicionar qualquer campo de ciclo de vida é opt-in — o renderizador degrada graciosamente quando os campos estão ausentes.
- A barra de progresso é opt-in mesmo quando o bloco `progress` existe: somente `progress.percent` ativa a barra; `total_phases` e `completed_phases` sozinhos não ativam.
O conjunto de testes `formatGsdState #2833 backward compatibility` em `tests/enh-2833-phase-lifecycle-statusline.test.cjs` garante essa promessa; qualquer mudança que quebre a renderização legada do `STATE.md` fará o conjunto falhar.
---
## Relacionados
- [Artefatos de planejamento](planning-artifacts.md)
- [Configuração](../CONFIGURATION.md)
- [O ciclo de fases](../explanation/the-phase-loop.md)
- [índice da documentação](../README.md)