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

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

Browse Source 
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
Download Patch File Download Diff File Expand all files Collapse all files

18
docs/pt-BR/reference/context-md.md
View File

@@ -1,6 +1,6 @@
# 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).
Um `CONTEXT.md` por fase é o mecanismo do MSD Core para capturar decisões de implementação durante `/msd-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).
---
@@ -14,7 +14,7 @@ Toda fase que passou pelo fluxo de trabalho de discussão produz um `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.
O arquivo é produzido por `write_context` em `msd-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.
---
@@ -39,12 +39,12 @@ O corpo é dividido em blocos nomeados no estilo XML. Os blocos aparecem em uma
| 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` |
| `<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) | `msd-planner`, `msd-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) | `msd-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) | `msd-planner` (decisões bloqueadas devem ser implementadas), `msd-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) | `msd-phase-researcher`, `msd-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) | `msd-planner`, `msd-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) | `msd-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 |
---
@@ -107,7 +107,7 @@ Um CONTEXT.md cujas decisões sobrevivem aos planos é considerado conforme. Um
## 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>`:
Quando `/msd-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>

14
docs/pt-BR/reference/plan-md.md
View File

@@ -1,6 +1,6 @@
# 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).
Um `PLAN.md` por plano é a unidade executável de trabalho do MSD 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).
---
@@ -14,7 +14,7 @@ Os planos ficam dentro de diretórios de fase em:
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.
Os planos são produzidos pelo agente `msd-planner` (disparado por `/msd-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.
---
@@ -66,7 +66,7 @@ must_haves:
| `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`. |
| `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 `msd-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. |
@@ -78,7 +78,7 @@ must_haves:
## 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`.
`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 `msd-verifier`.
### Sub-campos
@@ -122,8 +122,8 @@ Lista os arquivos de workflow que o executor lê antes de começar. Sempre inclu
```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 @@ Planos que contêm qualquer tarefa de checkpoint devem definir `autonomous: fals
## 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):
O agente `msd-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 `msd-planner` para revisão (até 3 iterações):
| Dimensão | O que verifica |
|---|---|

72
docs/pt-BR/reference/planning-artifacts.md
View File

@@ -1,6 +1,6 @@
# 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).
O diretório `.planning/` é a memória compartilhada do MSD 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).
---
@@ -50,32 +50,32 @@ O diretório `.planning/` é a memória compartilhada do GSD Core para um projet
| | |
|---|---|
| **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, incluindo handoff do `/gsd-onboard`); 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). |
| **Produzido por** | `/msd-new-project` (criação inicial, incluindo handoff do `/msd-onboard`); atualizado por `/msd-complete-milestone` à medida que as decisões são validadas. |
| **Consumido por** | Todos os fluxos de trabalho de planejamento; `msd-phase-researcher`, `msd-planner` (contexto); `discuss-phase` (decisões anteriores); `msd-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, incluindo handoff do `/gsd-onboard`); 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`. |
| **Produzido por** | `/msd-new-project` (criação inicial, incluindo handoff do `/msd-onboard`); atualizado por `/msd-phase --insert` e `/msd-complete-milestone`. |
| **Consumido por** | `/msd-discuss-phase`, `/msd-plan-phase`, `/msd-execute-phase`; todos os comandos de orquestração que precisam de informações de fase; `msd-planner`, `msd-plan-checker`, `msd-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, incluindo handoff do `/gsd-onboard`); 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). |
| **Produzido por** | `/msd-new-project` (criação inicial, incluindo handoff do `/msd-onboard`); requisitos marcados como concluídos por `execute-phase`. |
| **Consumido por** | `msd-planner` (os planos devem contemplar todos os IDs de requisitos da fase); `msd-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, incluindo handoff do `/gsd-onboard`); 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). |
| **Produzido por** | `/msd-new-project` (criação inicial, incluindo handoff do `/msd-onboard`); atualizado continuamente por todos os fluxos de fase, `/msd-pause-work`, `/msd-resume-work`. |
| **Consumido por** | Todos os fluxos de orquestração; `/msd-progress`; execução de tarefas avulsas via `/msd-quick`; `msd-planner` e `msd-phase-researcher` (decisões do projeto). |
Consulte o [esquema de STATE.md](state-md.md) para a referência completa de campos.
@@ -84,8 +84,8 @@ Consulte o [esquema de STATE.md](state-md.md) para a referência completa de cam
| | |
|---|---|
| **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`. |
| **Produzido por** | `/msd-new-project` (criação inicial); `/msd-settings` (edição interativa). |
| **Consumido por** | Todos os fluxos de trabalho e subagentes — lido no momento de inicialização via `msd-tools query config-get`. |
Consulte [CONFIGURATION](../CONFIGURATION.md) para o esquema completo.
@@ -93,17 +93,17 @@ Consulte [CONFIGURATION](../CONFIGURATION.md) para o esquema completo.
| | |
|---|---|
| **Finalidade** | Índice de onboarding brownfield que registra status dos artefatos, se o mapeamento do código-base está completo e o próximo comando GSD recomendado após a configuração inicial. |
| **Produzido por** | `/gsd-onboard` depois que `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md` e `STATE.md` existem. |
| **Consumido por** | Humanos revisando a configuração inicial; futuras execuções de `/gsd-onboard` ao confirmar o estado de onboarding existente. |
| **Finalidade** | Índice de onboarding brownfield que registra status dos artefatos, se o mapeamento do código-base está completo e o próximo comando MSD recomendado após a configuração inicial. |
| **Produzido por** | `/msd-onboard` depois que `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md` e `STATE.md` existem. |
| **Consumido por** | Humanos revisando a configuração inicial; futuras execuções de `/msd-onboard` ao confirmar o estado de onboarding existente. |
### `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. |
| **Produzido por** | `/msd-complete-milestone`. |
| **Consumido por** | `/msd-audit-milestone`; revisão humana. |
### `DECISIONS-INDEX.md` (opcional)
@@ -118,8 +118,8 @@ Consulte [CONFIGURATION](../CONFIGURATION.md) para o esquema completo.
| | |
|---|---|
| **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`. |
| **Produzido por** | `/msd-pause-work`. |
| **Consumido por** | `/msd-resume-work`. |
---
@@ -132,8 +132,8 @@ Todos os arquivos por fase ficam em `.planning/phases/<NN>-<slug>/`, onde `NN`
| | |
|---|---|
| **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). |
| **Produzido por** | `/msd-discuss-phase` (discussão interativa ou caminhos expressos PRD/ADR). |
| **Consumido por** | `msd-phase-researcher` (o que investigar); `msd-planner` (decisões bloqueadas); `msd-plan-checker` Dimensão 7 (conformidade de contexto). |
Consulte o [esquema de CONTEXT.md](context-md.md) para a referência completa de campos.
@@ -142,7 +142,7 @@ Consulte o [esquema de CONTEXT.md](context-md.md) para a referência completa de
| | |
|---|---|
| **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`). |
| **Produzido por** | `/msd-discuss-phase` (etapa `git_commit`). |
| **Consumido por** | Revisão humana; retrospectivas. |
### `<NN>-RESEARCH.md`
@@ -150,32 +150,32 @@ Consulte o [esquema de CONTEXT.md](context-md.md) para a referência completa de
| | |
|---|---|
| **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). |
| **Produzido por** | `/msd-plan-phase` via agente `msd-phase-researcher`. |
| **Consumido por** | `msd-planner` (entradas de planejamento); `msd-plan-checker` Dimensão 7c (conformidade de camada), Dimensão 8 (Nyquist), Dimensão 11 (resolução de pesquisa); `msd-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`. |
| **Produzido por** | `/msd-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** | `msd-plan-checker` Dimensão 8 (gate Check 8e — deve existir antes de os checks Nyquist prosseguirem); `msd-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). |
| **Finalidade** | Mapa de análogos do código-base produzido pelo `msd-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** | `/msd-plan-phase` via agente `msd-pattern-mapper` (opcional; ignorado se `workflow.pattern_mapper: false`). |
| **Consumido por** | `msd-planner` (orientação de padrões); `msd-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). |
| **Produzido por** | `/msd-plan-phase` via agente `msd-planner`. Um arquivo por plano — ex.: `03-02-PLAN.md` é Fase 3, Plano 2. |
| **Consumido por** | `/msd-execute-phase` (agente executor lê o plano e executa as tarefas); `msd-plan-checker` (revisão de qualidade pré-execução); `msd-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.
@@ -185,30 +185,30 @@ Consulte o [esquema de PLAN.md](plan-md.md) para a referência completa de campo
|---|---|
| **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`. |
| **Consumido por** | `/msd-progress` (status da fase); `msd-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. |
| **Produzido por** | `/msd-verify-work` (ou a etapa de verificação dentro de `/msd-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`); `/msd-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). |
| **Produzido por** | `/msd-audit-uat` (sessão UAT interativa). |
| **Consumido por** | `/msd-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`. |
| **Produzido por** | `/msd-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. |
---

42
docs/pt-BR/reference/state-md.md
View File

@@ -1,14 +1,14 @@
# 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).
`STATE.md` é o arquivo de memória viva do projeto do MSD 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:
Todo projeto gerenciado pelo MSD 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`.
- **Frontmatter YAML** — campos legíveis por máquina consumidos pelo hook de linha de status (`parseStateMd`) e pelos comandos `msd-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.
@@ -17,13 +17,13 @@ O arquivo é intencionalmente pequeno (meta: menos de 100 linhas). Ele é um res
## 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.
O frontmatter aparece entre delimitadores `---` no início do arquivo. Todos os campos, exceto `msd_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'
msd_state_version: '1.0'
milestone: v2.0
milestone_name: Code Quality
status: executing
@@ -56,7 +56,7 @@ paused_at: null
| Campo | Tipo | Quando populado | Finalidade |
|---|---|---|---|
| `gsd_state_version` | string (`'1.0'`) | Sempre | Versão do esquema; escrito na primeira chamada `state.*` por `syncStateFrontmatter`. |
| `msd_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). |
@@ -83,7 +83,7 @@ paused_at: null
| Campo | Cardinalidade |
|---|---|
| `gsd_state_version` | one |
| `msd_state_version` | one |
| `milestone` | optional |
| `milestone_name` | optional |
| `current_phase` | optional |
@@ -105,7 +105,7 @@ paused_at: null
### Valores de status
`normalizeStateStatus()` em `gsd-core/bin/lib/state-document.cjs` mapeia o texto bruto do corpo para estes valores canônicos:
`normalizeStateStatus()` em `msd-core/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) |
|---|---|
@@ -121,10 +121,10 @@ Quando um comando do orquestrador está em andamento, a convenção (issue #2833
| Comando | `status` durante a execução |
|---|---|
| `/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 -->
### Ciclo de vida do status (ADR-2207)
@@ -145,7 +145,7 @@ Phase-completion verbs never write `Milestone complete` (the overloaded bare val
## 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.
`formatMsdState()` em `hooks/msd-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 |
|---|---|---|
@@ -154,7 +154,7 @@ Phase-completion verbs never write `Milestone complete` (the overloaded bare val
| **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/gsd-statusline.test.cjs`.
**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 `formatMsdState()` e coberta pelo conjunto `"scene priority"` em `tests/msd-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.
@@ -162,7 +162,7 @@ A barra de progresso (`[██░░░░░░░░] 20%`) é anexada ao segm
## 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/gsd-statusline.test.cjs`.
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/msd-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.
@@ -176,7 +176,7 @@ Se uma mudança futura substituir o analisador de regex por uma biblioteca YAML
## Seções do corpo Markdown
O corpo (tudo após o `---` de fechamento) segue o template em `gsd-core/templates/state.md`. As seções padrão são:
O corpo (tudo após o `---` de fechamento) segue o template em `msd-core/templates/state.md`. As seções padrão são:
### Referência do Projeto
@@ -200,7 +200,7 @@ Onde o projeto está agora:
O *histórico* de progresso não pertence aqui. Ele se acumula em [`### Performance Metrics`](#métricas-de-desempenho) logo abaixo, que é a seção projetada para crescer.
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 `gsd-core/bin/lib/state-document.cjs`.
Os campos `Status:` e `Last activity:` nesta seção são atualizados pelos handlers do MSD 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 `msd-core/bin/lib/state-document.cjs`.
### Métricas de Desempenho
@@ -213,11 +213,11 @@ 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`.
**Decisões** — um resumo das decisões recentes que afetam o trabalho atual (o log completo vive em `PROJECT.md`). Adicionado via `msd-tools state add-decision`.
**Todos Pendentes** — contagem e referência a `.planning/todos/pending/`. Capturado via `/gsd-capture`.
**Todos Pendentes** — contagem e referência a `.planning/todos/pending/`. Capturado via `/msd-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`.
**Bloqueadores/Preocupações** — problemas que afetam trabalhos futuros, prefixados com a fase de origem. Adicionado via `msd-tools state add-blocker`; resolvido via `msd-tools state resolve-blocker`.
### Continuidade de Sessão
@@ -236,7 +236,7 @@ Os campos de ciclo de vida de fase (`active_phase`, `next_action`, `next_phases`
- 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/gsd-statusline.test.cjs` garante essa promessa; qualquer mudança que quebre a renderização legada do `STATE.md` fará o conjunto falhar.
O conjunto de testes `formatMsdState #2833 backward compatibility` em `tests/msd-statusline.test.cjs` garante essa promessa; qualquer mudança que quebre a renderização legada do `STATE.md` fará o conjunto falhar.
---