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

* 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

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)