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,90 @@
# Engenharia de contexto
> Por que o GSD Core existe e qual problema ele foi projetado para resolver.
---
## O problema: degradação de contexto
Toda sessão de programação com IA começa do zero. O modelo lê sua pergunta, raciocina sobre ela e responde. Mas raramente uma sessão é composta de uma única troca. Você faz perguntas de acompanhamento, cola mensagens de erro, itera sobre o código, redireciona o modelo quando ele se desvia. Cada turno adiciona tokens à janela de contexto — o buffer finito de texto que o modelo consegue "enxergar" de uma só vez.
À medida que essa janela vai se preenchendo, algo sutil acontece. O modelo não falha de forma escancarada. Ele continua respondendo. Mas a qualidade das suas respostas vai se degradando silenciosamente. As instruções iniciais são empurradas para as bordas do que ele consegue atentar. A nuance das primeiras trocas — as restrições que você estabeleceu, a arquitetura que você acordou, os casos extremos que você sinalizou — compete por atenção com tudo o que veio depois. Pesquisadores chamam isso de **degradação de contexto** (*context rot*).
A degradação de contexto se manifesta de várias formas:
- O modelo começa a contradizer decisões anteriores que havia reconhecido.
- O estilo do código se distancia das convenções estabelecidas no início da sessão.
- Os planos passam a ignorar requisitos que foram claramente declarados, mas que agora estão soterrados no histórico.
- O modelo alucina nomes de arquivos ou assinaturas de funções que tinha corretos vinte mensagens atrás.
Nada disso é um bug do modelo. É uma propriedade fundamental de como a atenção de transformers funciona sobre sequências longas. O modelo não está esquecendo — ele nunca "lembrou" no sentido humano. Ele está ponderando a relevância ao longo de uma janela finita e, à medida que essa janela se preenche com ruído acumulado, a relação sinal-ruído se degrada.
A resposta ingênua é usar `/clear` e recomeçar. Mas isso perde a continuidade. Você precisa reexplicar o contexto, recolar os arquivos relevantes, reafirmar as restrições. A sessão essencialmente volta à estaca zero.
---
## A resposta do GSD Core: subagentes com contexto limpo
O insight central do GSD Core é que *a maior parte* do trabalho em uma sessão de programação não precisa acontecer no contexto principal. Pesquisa, planejamento, escrita de código e verificação são tarefas discretas e delimitadas. Cada uma pode ser entregue a um subagente especializado que começa com uma janela de contexto limpa e cuidadosamente delimitada — e reporta seu resultado de volta a um orquestrador enxuto que permanece leve.
Isso não é um contorno para a degradação de contexto. É uma solução estrutural.
O orquestrador — sua sessão principal — nunca toca os arquivos-fonte. Ele spawna agentes, coleta seus resultados, atualiza o estado compartilhado e encaminha para o próximo passo. Como ele faz muito pouco por conta própria, sua janela de contexto cresce de forma lenta e previsível. O trabalho pesado acontece em agentes que cada um começa do zero, recebe exatamente o contexto necessário para sua tarefa e termina quando concluído.
Considere o que isso significa na prática. Quando você executa `/gsd-plan-phase`, o orquestrador:
1. Carrega um payload de contexto JSON compacto (resumo do projeto, objetivo da fase, configuração relevante).
2. Spawna um agente pesquisador com uma janela limpa de 200k tokens.
3. Spawna um agente planejador com a saída da pesquisa e os requisitos da fase.
4. Spawna um agente verificador de plano para validar o plano antes da execução.
Cada agente opera com capacidade total, sem o peso do histórico acumulado da sua sessão. Quando o planejador escreve seus arquivos `PLAN.md` em `.planning/phases/`, essa saída se torna um artefato durável — não uma memória frágil em uma janela de contexto compartilhada.
---
## Desenvolvimento orientado a especificações e meta-prompting
A engenharia de contexto por si só não é suficiente. Se um agente começa do zero mas recebe instruções vagas, ele vai produzir saídas vagas. O GSD Core combina subagentes com contexto limpo com duas disciplinas complementares:
**Desenvolvimento orientado a especificações** significa que toda fase produz artefatos estruturados antes de a execução começar. Um `CONTEXT.md` captura as decisões de implementação da etapa Discuss. Um `RESEARCH.md` registra o que o pesquisador encontrou. Um `PLAN.md` divide o trabalho em tarefas discretas, ordenadas por dependência, com critérios de aceite explícitos. Quando um agente executor toca um arquivo, ele tem uma especificação precisa para seguir — não uma reinterpretação de uma conversa longa.
**Meta-prompting** significa que as próprias definições de agentes são prompts cuidadosamente engenheirados, não instruções ad-hoc. Os arquivos em `get-shit-done/workflows/` e `agents/` codificam conhecimento conquistado a duras penas sobre como delimitar tarefas, o que verificar e quando escalar para um checkpoint humano. O usuário não precisa reexplicar esse conhecimento a cada sessão; ele está integrado aos próprios prompts do sistema.
A combinação é deliberada. O contexto limpo garante que cada agente raciocine com clareza. Os artefatos orientados a especificações garantem que cada agente raciocine sobre a *coisa certa*. O meta-prompting garante que cada agente saiba *como* raciocinar bem sobre ela.
---
## O papel do `.planning/`
A engenharia de contexto exige que o conhecimento sobreviva a reinicializações de contexto. O GSD Core usa o sistema de arquivos para isso. Toda saída significativa é escrita em `.planning/` como Markdown ou JSON legível por humanos. Isso significa que:
- Reiniciar sua sessão (ou uma falha do modelo) não faz você perder trabalho.
- Qualquer agente subsequente pode ler artefatos anteriores diretamente, sem depender de um histórico de conversa compartilhado.
- Você pode inspecionar, editar ou commitar artefatos de planejamento no git — são texto simples, não estado opaco em um banco de dados.
`STATE.md` é a espinha dorsal desse sistema. Ele registra a posição atual do projeto (qual milestone, qual fase, quais planos estão completos), decisões ativas e bloqueadores, e métricas de progresso. Quando qualquer workflow começa, ele lê o `STATE.md` para se orientar. Quando qualquer workflow conclui uma etapa significativa, ele escreve de volta no `STATE.md`. Os agentes não dependem de memória; dependem do arquivo.
---
## Concessões e limitações
É importante ser honesto sobre as concessões envolvidas.
**Sobrecarga.** O ciclo de fases introduz atrito real. Executar `/gsd-discuss-phase`, `/gsd-plan-phase` e `/gsd-execute-phase` como etapas separadas leva mais tempo que digitar "escreva esse recurso" em uma sessão simples. Para uma mudança pequena e bem compreendida, essa sobrecarga não se justifica.
**Latência.** Spawnar múltiplos subagentes com contexto limpo é mais lento do que uma única edição no contexto. Pesquisa, planejamento e execução incorrem cada um em custos de ida e volta.
**Cerimônia para tarefas simples.** Se você precisa renomear uma variável, corrigir um erro de digitação ou adicionar um import ausente, o ciclo de fases é exagero. O GSD Core fornece `/gsd-quick` e `/gsd-fast` para trabalho ad-hoc que não justifica uma fase completa. Veja [Lidar com tarefas rápidas](../how-to/handle-quick-and-fast-tasks.md).
O ciclo de fases se paga quando o trabalho é suficientemente complexo para que a degradação de contexto seja um risco real — recursos com múltiplos arquivos, refatorações transversais, trabalho que se estende por horas ou sessões. Para todo o resto, recorra ao primitivo mais leve.
Uma regra de bolso útil: se a tarefa pudesse ser totalmente especificada em um prompt único e curto e concluída em um turno de agente sem mais esclarecimentos, pule o ciclo de fases. Se a tarefa requer pesquisa, envolve arquivos que você não leu recentemente, ou depende de decisões que ainda não estão definidas, o ciclo de fases te protege.
---
## Relacionados
- [O ciclo de fases](the-phase-loop.md) — como o ciclo Discuss → Plan → Execute → Verify → Ship coloca a engenharia de contexto em prática
- [Orquestração multi-agente](multi-agent-orchestration.md) — como subagentes são spawnados, delimitados e coordenados
- [Arquitetura](../ARCHITECTURE.md) — arquitetura do sistema, modelo de agentes e fluxo de dados
- [Índice de documentação](../README.md)

View File

@@ -0,0 +1,234 @@
# Orquestração multi-agente no GSD Core
> **Explicação** — Este documento descreve *por que* o GSD Core foi projetado em torno da
> orquestração multi-agente e *como as partes se encaixam*. Não é um guia
> passo a passo. Para configuração, consulte
> [Configurar perfis de modelo](../how-to/configure-model-profiles.md) e a
> [Referência de configuração](../CONFIGURATION.md). Para o catálogo completo de agentes,
> consulte [Inventário](../INVENTORY.md).
---
## O problema que este design resolve
Agentes de codificação com IA degradam. Não porque o modelo piora, mas porque a
*janela de contexto fica cheia*. À medida que uma conversa cresce, decisões e código
anteriores são expulsos ou diluídos pelo ruído das etapas intermediárias. Quando um
agente escreve o quinto arquivo em uma tarefa complexa, pode já ter esquecido
a restrição declarada na primeira mensagem. Isso é às vezes chamado de *podridão
de contexto* (*context rot*).
O design multi-agente do GSD Core é uma resposta direta a esse problema. Em vez de
um único agente de longa duração carregando toda a sessão, um orquestrador enxuto gera
agentes especializados de curta duração, cada um com uma **janela de contexto fresca de 200 K tokens**
e *somente os artefatos de que precisa* para realizar seu trabalho específico. O orquestrador
nunca faz o trabalho pesado por conta própria; ele carrega o contexto, gera o agente
adequado, coleta o resultado e atualiza o estado compartilhado em `.planning/`.
---
## O padrão orquestrador → agente
Todos os workflows em `get-shit-done/workflows/` seguem a mesma estrutura:
```text
Orquestrador (arquivo .md de workflow)
│
├── Carregar contexto
│ gsd-tools.cjs init <workflow> <phase>
│ → JSON: informações do projeto, config, estado, detalhes da fase
│
├── Resolver modelo
│ gsd-tools.cjs resolve-model <agent-name>
│ → opus | sonnet | haiku | inherit
│
├── Gerar agente especializado (chamada Task/SubAgent)
│ ├── Definição do agente (agents/*.md)
│ ├── Payload de contexto (JSON de init)
│ ├── Atribuição de modelo
│ └── Permissões de ferramentas
│
├── Coletar resultado
│
└── Atualizar estado
gsd-tools.cjs state update / state patch / state advance-plan
```
O orquestrador é deliberadamente enxuto. Ele não raciocina sobre o domínio,
não escreve código e não interpreta resultados além de roteá-los para a
próxima etapa. Esse limite mantém a responsabilidade de cada camada clara e impede
que o contexto do orquestrador acumule ruído de domínio.
### O catálogo de agentes
Os agentes do GSD Core se enquadram em categorias funcionais que mapeiam o
pipeline pesquisa → planejamento → execução → verificação:
| Categoria | Agentes | Paralelismo típico |
|---|---|---|
| Pesquisadores | `gsd-project-researcher`, `gsd-phase-researcher`, `gsd-ui-researcher`, `gsd-advisor-researcher` | 4 em paralelo (stack, funcionalidades, arquitetura, armadilhas) |
| Sintetizadores | `gsd-research-synthesizer` | Sequencial, após a conclusão dos pesquisadores |
| Planejadores | `gsd-planner`, `gsd-roadmapper` | Sequencial |
| Verificadores | `gsd-plan-checker`, `gsd-integration-checker`, `gsd-ui-checker`, `gsd-nyquist-auditor` | Sequencial, até 3 iterações de revisão |
| Executores | `gsd-executor` | Paralelo dentro de uma onda, sequencial entre ondas |
| Validadores | `gsd-verifier` | Sequencial, após a conclusão de todos os executores |
| Mapeadores | `gsd-codebase-mapper` | 4 sub-sondas em paralelo |
| Auditores | `gsd-ui-auditor`, `gsd-security-auditor` | Sequencial |
Cada definição de agente (em `agents/*.md`) declara o acesso às ferramentas permitido,
a finalidade e a cor para saída no terminal. Um agente que só precisa ler arquivos
e escrever um único documento de saída recebe exatamente essas permissões — sem
execução de Bash, sem acesso a um estado mais amplo. Essa restrição é intencional: ela
mantém o raio de impacto pequeno caso um agente se comporte de forma inesperada.
Para o catálogo completo de 31 agentes, consulte [Inventário](../INVENTORY.md#agents-31-shipped).
---
## Execução paralela baseada em ondas
A expressão mais visível do design multi-agente é como o `/gsd-execute-phase`
lida com um conjunto de planos que podem depender uns dos outros.
Antes de gerar qualquer executor, o orquestrador realiza uma **análise de ondas**:
ele lê as declarações de dependência em cada arquivo `PLAN.md` e agrupa os planos
em ondas. Planos sem dependências declaradas formam a Onda 1 e executam em
paralelo. Planos que dependem da Onda 1 formam a Onda 2, e assim por diante.
```text
Plano 01 (sem deps) ─┐
Plano 02 (sem deps) ─┤─── Onda 1 (paralelo)
Plano 03 (depende de: 01) ─┤─── Onda 2 (aguarda Onda 1)
Plano 04 (depende de: 02) ─┘
Plano 05 (depende de: 03, 04) ─── Onda 3 (aguarda Onda 2)
```
Cada executor dentro de uma onda:
- recebe uma janela de contexto fresca (200 K tokens, ou até 1 M em modelos capazes)
- recebe o `PLAN.md` específico pelo qual é responsável
- recebe o contexto do projeto (`PROJECT.md`, `STATE.md`)
- recebe o contexto da fase (`CONTEXT.md`, `RESEARCH.md` se disponível)
- produz commits git atômicos ao concluir
- escreve um `SUMMARY.md` descrevendo o que foi construído
Após a conclusão de todos os executores em uma onda, o orquestrador executa o hook
de pré-commit uma vez para a onda como um todo. Os executores fazem commit com `--no-verify` para
evitar contenção de bloqueio de build (por exemplo, conflitos de lock do Cargo em projetos
Rust) quando múltiplos agentes fazem commit em paralelo. O hook, portanto, é executado
uma vez por onda em vez de uma vez por commit.
### Segurança de commits paralelos
Dois mecanismos previnem conflitos de escrita quando múltiplos executores executam
simultaneamente:
1. **Lock atômico em `STATE.md`** — Toda escrita em `STATE.md` usa um
arquivo de lock (`STATE.md.lock`) com criação atômica `O_EXCL`. Isso previne
a corrida de leitura-modificação-escrita onde dois agentes leem o arquivo, modificam
campos diferentes, e o escritor posterior sobrescreve as alterações do anterior.
Locks obsoletos (com mais de 10 segundos) são automaticamente removidos.
2. **Execução de hook por onda** — Em vez de cada executor executar hooks de pré-commit
de forma independente (o que pode causar contenção em nível de arquivo em artefatos
de build compartilhados), o orquestrador executa `git hook run pre-commit` uma vez após
a conclusão de cada onda.
---
## Enriquecimento adaptativo de contexto para modelos de janela grande
Janelas de contexto padrão de 200 K são suficientes para um executor implementar um
plano único e focado. Quando o `context_window` configurado é de 500 K tokens ou
maior (por exemplo, ao usar o Opus 4.6 ou Sonnet 4.6 no modo de 1 M), o orquestrador
automaticamente enriquece os prompts de subagentes com contexto adicional que não
caberia em uma janela padrão:
- **Agentes executores** recebem arquivos `SUMMARY.md` de ondas anteriores e o
`CONTEXT.md`/`RESEARCH.md` da fase, fornecendo a eles consciência entre planos
dentro da fase
- **Agentes validadores** recebem todos os arquivos `PLAN.md`, `SUMMARY.md` e `CONTEXT.md`
mais `REQUIREMENTS.md`, habilitando verificação com consciência histórica
Esse enriquecimento é condicional ao valor de `context_window` em
`config.json`. Em configurações de janela padrão, os prompts usam versões truncadas
com ordenação favorável ao cache para maximizar a eficiência de tokens.
---
## Por que este design — a conexão com a engenharia de contexto
O padrão orquestrador → agente só faz sentido como parte de uma abordagem mais ampla
de *engenharia de contexto*: a ideia de que o que um agente de IA recebe em sua
janela de contexto importa tanto quanto o nível do modelo ou a qualidade do prompt. Consulte
[Engenharia de contexto](context-engineering.md) para o tratamento completo.
A orquestração multi-agente operacionaliza a engenharia de contexto de duas formas:
**Isolamento de contexto.** Cada agente recebe apenas o que precisa. Um pesquisador
recebe a descrição do projeto e as questões de domínio; ele não recebe o histórico
completo de planejamento. Um validador recebe todos os planos e resumos; ele não recebe
a pesquisa bruta. O isolamento mantém o contexto de cada agente denso em sinal em vez
de diluído pelo ruído de outros estágios do pipeline.
**Higiene de contexto entre sessões.** Como todo o estado vive em
`.planning/` como Markdown e JSON legíveis por humanos (não na janela de contexto
de nenhum agente), os workflows do GSD sobrevivem a resets de contexto (`/clear`), trocas de
abas e intervalos de vários dias. O próximo agente sempre começa a partir de artefatos
persistidos e verificados, em vez de uma memória reconstruída de uma longa conversa.
---
## Compensações
A orquestração multi-agente não é gratuita.
**Sobrecarga de coordenação.** Cada geração de agente é uma ida e volta: o orquestrador
deve formatar um prompt, repassar o contexto, aguardar a conclusão do subagente
(tipicamente 1–5 minutos) e então analisar o resultado. Um único agente capaz
trabalhando em um contexto terminaria mais rápido para tarefas simples. O GSD mitiga
isso tornando o paralelismo o padrão sempre que as dependências permitirem — os
quatro pesquisadores em um `plan-phase` executam simultaneamente, não sequencialmente.
**Opacidade durante a execução.** Enquanto um subagente está em execução, seu trabalho é
invisível para a sessão pai. Não há fluxo de progresso ao vivo. Esta é uma
consequência deliberada do design de contexto fresco: o subagente está operando
em sua própria janela de contexto. O orquestrador exibe uma nota de atividade na
linha de geração ("executado em um subagente — sem saída até retornar") para definir
expectativas.
**Custo de costura de contexto.** Empacotar os artefatos certos para cada agente
requer que o orquestrador gaste tokens montando e transmitindo payloads de contexto.
Este é o custo do isolamento. O handler `gsd-tools.cjs init`
produz um payload JSON que equilibra completude com orçamento de tokens, aplicando
ordenação favorável ao cache para que as partes estáveis do payload (definição do projeto,
config) acertem o cache em invocações repetidas.
**Amplificação do custo do modelo.** Executar cinco agentes em paralelo no nível Opus
custa mais do que executar um. O sistema de perfis de modelo (`model_profiles.md`,
resolvido por agente pelo `model-profiles.cjs`) permite atribuir níveis mais baratos a
agentes menos críticos. O recurso `dynamic_routing` reduz ainda mais o custo ao
iniciar cada agente em um nível mais barato e escalar apenas em caso de falha suave.
Consulte [Configuração](../CONFIGURATION.md) para as opções completas.
Em troca desses custos, o design compra *qualidade consistente em fases grandes*.
Um executor escrevendo o décimo arquivo em um plano de 400 linhas não degrada porque
seu contexto está fresco. Um validador verificando vinte requisitos não esquece os
primeiros dez porque os recebeu todos como entrada estruturada em vez de histórico
de conversa.
---
## Relacionados
- [Engenharia de contexto](context-engineering.md) — o princípio upstream que
motiva este design
- [Configurar perfis de modelo](../how-to/configure-model-profiles.md) — como
atribuir níveis de modelo por agente
- [Referência de configuração](../CONFIGURATION.md) — schema completo de `config.json`
incluindo `models`, `model_overrides`, `dynamic_routing` e
`context_window`
- [Inventário](../INVENTORY.md) — catálogo autoritativo de agentes e lista de workflows
- [Arquitetura](../ARCHITECTURE.md#agent-model) — detalhes em nível de implementação
sobre o padrão orquestrador → agente e o modelo de execução por ondas
- [Índice de documentação](../README.md)

View File

@@ -0,0 +1,270 @@
# Modelo de segurança do GSD Core
> **Explicação** — Este documento descreve *por que* o GSD Core possui a
> postura de segurança que possui e *como as camadas se articulam*. Não é uma
> referência para todos os parâmetros de hook. Para o comando `/gsd-secure-phase`
> e suas opções, consulte [Comandos](../COMMANDS.md). Para a arquitetura de
> hooks em nível de implementação, consulte
> [Arquitetura § Sistema de Hooks](../ARCHITECTURE.md#hook-system).
> Para a linha de base de segurança organizacional (controles de scanner,
> checklists de incidentes, modelo de responsabilidade), consulte
> [SECURITY.md](../../../SECURITY.md).
---
## Por que o desenvolvimento orientado por IA precisa de uma postura de segurança dedicada
Um editor de código convencional não executa pacotes arbitrários em seu nome.
O GSD Core sim. O pipeline pesquisa → plano → execução automatiza o caminho
completo de "nomear um pacote" até "executar `npm install <package>`", de
"escrever um artefato de planejamento" até "usar esse artefato como prompt de
sistema de um LLM". Cada etapa de automação remove um humano do ciclo — e cada
remoção é uma superfície de ataque potencial.
O modelo de segurança do GSD Core é construído em torno de um princípio
organizador: **defesa em profundidade**. Nenhum controle isolado é assumido
como perfeito. Várias camadas sobrepostas reduzem, cada uma, uma classe distinta
de risco e, juntas, tornam a superfície de ataque substancialmente mais difícil
de explorar sem eliminá-la completamente. O resumo honesto ao final deste
documento explica o que o sistema não consegue proteger.
---
## Camada 1 — Proteção da cadeia de suprimentos: o Package Legitimacy Gate
### A ameaça
Modelos de IA alucinam nomes de pacotes. Este não é um modo de falha marginal:
pesquisas de 2025 documentam aproximadamente 20% das referências de pacotes
geradas por IA como nomes alucinados que não correspondem a pacotes legítimos.
Um subconjunto desses nomes alucinados — aproximadamente 43% na mesma pesquisa —
recorre consistentemente entre prompts, o que significa que um atacante pode
observar quais nomes as ferramentas de IA costumam produzir e pré-registrar
esses nomes no npm, PyPI ou crates.io com scripts de pós-instalação maliciosos.
A técnica é chamada de *slopsquatting*.
A qualidade insidiosa do slopsquatting é que um nome alucinado que passa no
`npm view` *parece legítimo*. A entrada no registro prova apenas que alguém
registrou o nome — não que o pacote faz o que a IA disse que faz, não que
possui usuários legítimos e não que seus scripts de instalação são seguros.
Sem uma barreira, um nome alucinado fluiria sem ser detectado pelo pipeline
pesquisador → planejador → executor do GSD e eventualmente seria executado como
`npm install <attacker-package>` na sua máquina.
### Como a barreira funciona
A barreira opera em três estágios do pipeline:
**Estágio de pesquisa.** Quando `gsd-phase-researcher` recomenda pacotes
externos, executa `slopcheck install <pkgs> --json` para cada um. Os resultados
são gravados em uma tabela `## Package Legitimacy Audit` no `RESEARCH.md`.
Pacotes marcados com `[SLOP]` (alucinação de alta confiança ou registrado por
atacante) são **removidos inteiramente do `RESEARCH.md`** antes de o arquivo
ser salvo. Eles nunca chegam ao planejador.
**Estágio de planejamento.** `gsd-planner` lê a tabela de auditoria. Para
qualquer pacote marcado com `[SUS]` (suspeito: recém-registrado, baixa contagem
de downloads, sem repositório de código-fonte ou padrão de nomenclatura próximo
a um pacote popular) ou `[ASSUMED]` (originado de WebSearch em vez de
verificação direta no registro), o planejador **insere uma tarefa
`checkpoint:human-verify`** antes da etapa de instalação. O checkpoint inclui
um link direto para a página do registro e aspectos específicos a verificar:
histórico do mantenedor, atividade no rastreador de problemas, ausência de
scripts de instalação suspeitos.
**Estágio de execução.** Se uma instalação falhar, `gsd-executor` **exibe um
checkpoint e para**. Ele não tenta silenciosamente um nome de pacote alternativo
— que poderia ser malicioso. Esta é uma regra explícita no comportamento do
executor (RULE 3 na definição do agente executor).
### Por que pacotes do WebSearch são sempre `[ASSUMED]`
Nomes de pacotes descobertos via WebSearch são marcados como `[ASSUMED]`
independentemente de o `npm view` ser bem-sucedido. Um pacote que existe no
registro não é o mesmo que um pacote seguro de instalar. `npm view` prova o
registro, não a legitimidade. A marcação `[ASSUMED]` aciona o mesmo checkpoint
de verificação humana que `[SUS]`, garantindo que qualquer recomendação
descoberta na web e não verificada sempre receba revisão humana antes da
instalação.
### Cobertura por ecossistema
O pesquisador usa comandos de verificação específicos de cada registro, em vez
de uma única verificação genérica:
- Node.js: `npm view`
- Python: `pip index versions`
- Rust: `cargo search`
Isso cobre alucinações entre ecossistemas, que ocorrem em aproximadamente 9%
dos casos de acordo com a pesquisa USENIX de 2025 — situações em que uma IA
recomenda um pacote que existe em um ecossistema, mas não no que está realmente
em uso.
### Degradação graciosa
Se `slopcheck` não estiver disponível (não instalado, ou se a instalação via
pip falhar no momento da pesquisa), o GSD aplica o fallback mais restrito
possível: **todo pacote recomendado é marcado como `[ASSUMED]`**, e o planejador
bloqueia cada instalação com uma tarefa `checkpoint:human-verify`. Pesquisa e
planejamento prosseguem normalmente — o sistema nunca falha irrecuperavelmente
por dependência de ferramenta ausente. Isso é intencionalmente mais restritivo
do que o fluxo normal: a indisponibilidade do slopcheck significa que toda
instalação de pacote recebe um checkpoint humano.
A ferramenta `slopcheck` é licenciada sob MIT e instalável via pip. Se for
descontinuada, o fallback de barreira `[ASSUMED]` garante que a cobertura por
checkpoint humano seja mantida independentemente.
---
## Camada 2 — Defesas contra injeção de prompt
### A ameaça
O GSD Core gera arquivos Markdown que se tornam prompts de sistema de LLMs. O
pipeline de pesquisa lê conteúdo externo da web; o pipeline de planejamento
incorpora texto fornecido pelo usuário (`--text-file`, `--prd`); o pipeline de
execução grava artefatos de planejamento que são relidos posteriormente como
contexto de agente. Qualquer texto controlado pelo usuário que flua para esses
artefatos é um vetor potencial de **injeção indireta de prompt** — uma string
controlada por um atacante que, uma vez dentro de um prompt de sistema, tenta
substituir as instruções do agente ou exfiltrar informações.
### Como as defesas funcionam
O GSD Core trata a injeção de prompt em três níveis.
**Validação de entrada (`security.cjs`).** O módulo
`get-shit-done/bin/lib/security.cjs` é o utilitário central de segurança.
Ele fornece:
- Prevenção de path traversal: caminhos de arquivo fornecidos pelo usuário
(`--text-file`, `--prd`) são validados para resolver dentro do diretório do
projeto, com resolução explícita do symlink `/var` → `/private/var` no macOS
- Detecção de injeção de prompt: padrões de injeção conhecidos (sobrescritas de
papel, desvios de instrução, injeções de tag de sistema) são escaneados em
texto fornecido pelo usuário antes de entrar em qualquer artefato de
planejamento
- Parsing seguro de JSON: um wrapper que previne ataques de poluição de
protótipo via payloads JSON manipulados
- Validação de argumentos de shell: argumentos passados a comandos de subshell
são validados antes do uso
**Hook de runtime: `gsd-prompt-guard.js`.** Este hook é acionado a cada
chamada de Write ou Edit que tem como alvo arquivos `.planning/`. Ele escaneia
o conteúdo sendo gravado em busca dos mesmos padrões de injeção que o
`security.cjs` (um subconjunto inlinado diretamente no hook para independência
— o hook não usa `require()` para carregar o módulo, portanto é executado mesmo
que o caminho do módulo mude). A detecção é **apenas consultiva**: o hook
registra a descoberta, mas não bloqueia a gravação. A justificativa é que um
bloqueio falso-positivo em uma gravação de planejamento legítima seria mais
disruptivo do que uma injeção não detectada em uma camada de varredura
secundária.
**Hook de runtime: `gsd-read-injection-scanner.js`.** Este hook é acionado na
saída de cada chamada da ferramenta Read. Ele escaneia o *conteúdo que acabou
de ser lido* em busca de instruções injetadas em conteúdo não confiável —
capturando casos em que um atacante incorporou instruções em um arquivo que o
GSD está prestes a incorporar ao contexto de um agente.
**Scanner de CI.** `prompt-injection-scan.test.cjs` escaneia todos os arquivos
de agente, workflow e comando em busca de vetores de injeção embutidos como
parte do conjunto de testes. Isso detecta tentativas de injeção no próprio
código-fonte do GSD — por exemplo, um ataque de cadeia de suprimentos que
modificou um arquivo de workflow para adicionar uma instrução de sobrescrita de
papel.
### Read Injection Scanner vs Prompt Guard
Os dois hooks cobrem superfícies complementares. `gsd-prompt-guard.js` monitora
*gravações em artefatos de planejamento* — ele detecta injeções sendo plantadas.
`gsd-read-injection-scanner.js` monitora *leituras de qualquer arquivo* — ele
detecta injeções sendo ingeridas a partir de conteúdo externo (o README de uma
dependência, um arquivo de configuração de terceiros, um documento fornecido
pelo usuário). Juntos, eles delimitam o ciclo de vida ingestão → armazenamento
→ releitura.
---
## Camada 3 — Integridade do repositório e das dependências
Acima do comportamento de runtime do GSD, a organização `open-gsd` aplica
controles nos níveis de repositório e pacote. Eles estão documentados
integralmente em [`docs/security/baseline.md`](../../security/baseline.md) e são
resumidos aqui para completude.
**Integridade das dependências.** Todas as dependências de terceiros são
fixadas via `package-lock.json` e verificadas em relação aos checksums
publicados antes da instalação. Uma barreira `scripts/check-npm-integrity.cjs`
detecta versões inválidas, pacotes ausentes e pacotes estranhos no momento do
CI. Isso mitiga ataques de confusão de dependências e typosquatting contra as
próprias dependências do GSD.
**Varredura de segredos.** Cada commit e PR é escaneado em busca de segredos
codificados no código. Fixtures de teste intencionais devem ser anotadas com a
gramática de exclusão padrão do projeto (consulte `SECURITY.md` para o formato
de anotação). Supressões não anotadas falham no CI.
**Varredura de texto com segurança de localidade.** Strings de saída e voltadas
ao usuário são escaneadas em busca de homóglifos Unicode, caracteres de
substituição bidirecional e Unicode invisível — a classe de ataques documentada
na CVE-2021-42574 ("Trojan Source") que pode ocultar conteúdo malicioso em
diffs.
---
## Concessões e limitações
O modelo de segurança descrito aqui reduz significativamente a superfície de
ataque para o desenvolvimento orientado por IA. Ele não elimina o risco da
cadeia de suprimentos.
**O que o Package Legitimacy Gate reduz:** A probabilidade de que um pacote
alucinado ou registrado por um atacante chegue ao `npm install` sem um
checkpoint humano. A barreira `[SLOP]` remove completamente pacotes ruins de
alta confiança; as barreiras `[SUS]` / `[ASSUMED]` exigem revisão humana antes
da execução. Isso eleva substancialmente o custo de um ataque de slopsquatting
bem-sucedido.
**O que o Package Legitimacy Gate não elimina:** Um pacote legítimo que é
comprometido posteriormente (tomada de conta, confusão de dependências em sua
própria árvore) não é detectado pelo slopcheck, que verifica sinais de registro
no momento da pesquisa. Lock files e `npm audit` na camada de integridade de
dependências são os controles para essa classe de ataque.
**O que as defesas contra injeção de prompt reduzem:** A probabilidade de que
texto controlado pelo usuário em artefatos de planejamento substitua com sucesso
as instruções do agente. A correspondência de padrões com formas de injeção
conhecidas detecta os casos comuns; jailbreaks novos ou injeções de baixo sinal
podem passar sem ser detectados. A postura apenas consultiva significa que a
detecção é registrada, mas não bloqueada — uma escolha deliberada que preserva
a continuidade do fluxo de trabalho ao custo de não interromper definitivamente
em uma detecção.
**O que as defesas contra injeção de prompt não eliminam:** Uma injeção
suficientemente criativa que não corresponde a padrões conhecidos, ou uma
injeção que chega por um canal que os hooks não cobrem (por exemplo, conteúdo
injetado no README publicado de uma dependência que é lido por um subagente
navegando em documentação). Defesa em profundidade significa que cada camada
torna o ataque mais difícil, não que qualquer camada isolada o torna impossível.
**Reportando vulnerabilidades.** Relate por meio de advisory de segurança
privado do GitHub em
`https://github.com/open-gsd/gsd-core/security/advisories/new`. Não abra
issues públicas. Consulte [SECURITY.md](../../../SECURITY.md) para o cronograma
de resposta e a política de divulgação.
---
## Relacionados
- [Comandos](../COMMANDS.md) — inclui `/gsd-secure-phase` e
`/gsd-code-review` com flags relevantes para segurança
- [Arquitetura § Sistema de Hooks](../ARCHITECTURE.md#hook-system) —
detalhes de implementação de cada hook, seu gatilho de evento e propriedades
de segurança
- [SECURITY.md](../../../SECURITY.md) — reporte de vulnerabilidades, linha de
base de segurança organizacional, governança de exclusão de varredura de
segredos e verificação de integridade de dependências
- [Índice de documentação](../README.md)

View File

@@ -0,0 +1,129 @@
# O loop de fases
> O modelo mental central de como o GSD Core organiza o trabalho.
---
## O que é o loop
O GSD Core estrutura todo o trabalho de desenvolvimento como um ciclo que se repete:
```text
Discuss → (UI design) → Plan → Execute → Verify → Ship
```
Cada unidade de trabalho — chamada de **fase** — percorre essas etapas em ordem. O loop não é uma formalidade. Cada etapa existe porque protege contra uma classe específica de falha que a etapa anterior, por si só, não consegue evitar.
Este documento explica *por que* o loop tem a forma que tem. Para instruções sobre como executar cada etapa, veja os guias práticos linkados ao final.
---
## Por que cada etapa existe
### Discuss
O planejamento não pode começar até que você saiba *como* construir a coisa, não apenas *o que* construir. O objetivo da fase em `ROADMAP.md` descreve o resultado. A etapa Discuss captura as decisões de implementação que moldam o caminho até esse resultado: quais bibliotecas, qual estratégia de tratamento de erros, se uma funcionalidade é por rota ou global, como os casos extremos devem se comportar.
Sem uma etapa Discuss, o planejador precisa tomar essas decisões por conta própria. Às vezes acerta. Muitas vezes acerta de forma plausível, mas errada — produzindo um plano coerente, porém desalinhado com suas preferências reais. Quando a execução termina e você percebe o erro, já está desfazendo um trabalho significativo.
A etapa Discuss é deliberadamente leve. É uma conversa, não um exercício de especificação. O resultado é um `CONTEXT.md` no diretório da fase: um registro estruturado de decisões que o planejador, executor e verificador podem ler. A conversa leva alguns minutos; pode economizar horas de retrabalho.
### UI design (opcional)
Para fases com componente visual, existe uma etapa opcional `/gsd-ui-phase` entre Discuss e Plan. Ela produz um `UI-SPEC.md` — um contrato de design que descreve layout, interação e comportamento visual antes de qualquer código ser escrito. Vale a pena executar essa etapa quando a interface é complexa o suficiente para que ambiguidades no design produzam escolhas de implementação divergentes. Um contrato de design claro é muito mais barato de escrever do que de reimplementar.
### Plan
A etapa Plan realiza a pesquisa, a decomposição e o raciocínio estrutural que a execução exige. Ela roda como uma sequência de subagentes com contexto zerado: um pesquisador que investiga o ecossistema e registra os achados em `RESEARCH.md`, um planejador que lê tanto a pesquisa quanto o `CONTEXT.md` para produzir os arquivos `PLAN.md`, e um verificador de planos que confere se os planos estão completos, consistentes e dentro do escopo.
O que um plano contém? Cada `PLAN.md` descreve uma unidade delimitada de trabalho: os arquivos a serem tocados, as mudanças específicas a serem feitas, os critérios de aceite que definem o que é "concluído". Os planos são ordenados em ondas de dependência para que a execução paralela seja segura — executores na mesma onda tocam preocupações que não se sobrepõem.
A etapa Plan é o momento em que a ambiguidade é mais cara. Um plano ambíguo produz um executor que faz suposições. Múltiplos executores paralelos fazendo suposições diferentes sobre a mesma preocupação produzem conflitos. O trabalho do verificador de planos é capturar isso antes de a execução começar, não depois.
### Execute
A execução roda os planos. Cada executor recebe uma janela de contexto zerada de 200k tokens carregada com exatamente o que precisa: o resumo do projeto, o contexto da fase, a pesquisa e o `PLAN.md` específico para sua tarefa. Nada mais.
Os executores escrevem código e fazem commits de forma atômica. Cada commit corresponde a uma tarefa concluída em um plano. Quando uma onda de executores paralelos termina, o orquestrador mescla o estado deles e inicia a próxima onda.
O contexto zerado do executor não é uma conveniência — é o mecanismo pelo qual a degradação de contexto é evitada. Um executor rodando com 180k tokens de histórico de sessão acumulado é um executor degradado. Um executor que começa do zero e lê apenas o que seu plano exige é um executor operando em plena capacidade.
### Verify
Após todos os executores terem concluído, um agente verificador lê o objetivo da fase, as decisões do `CONTEXT.md`, os planos e os resumos de execução — e verifica se o que foi construído corresponde ao que foi pretendido. Ele produz um `VERIFICATION.md` e, se houver discrepâncias, gera planos de correção direcionados.
A verificação não é apenas testes. Ela confere a cobertura de requisitos (todos os REQ-IDs foram endereçados?), a cobertura de decisões (as decisões capturadas no `CONTEXT.md` foram realmente implementadas?) e o alinhamento geral com o objetivo da fase. Uma fase não está concluída porque a execução terminou sem erros. Está concluída porque o que foi construído é o que foi planejado, e o que foi planejado é o que foi decidido.
### Ship
A etapa Ship cria o pull request e arquiva os artefatos da fase. O `STATE.md` é atualizado para marcar a fase como concluída. O loop então recomeça para a próxima fase.
---
## Marcos e fases
Um **marco** é um ciclo de versão — um incremento significativo e entregável do projeto. Tem um nome, um número de versão e um conjunto de requisitos que definem o que deve entregar. Um marco está completo quando todas as suas fases foram entregues e seus requisitos estão cobertos.
Uma **fase** é uma unidade de trabalho dentro de um marco. Uma fase tem um objetivo, um conjunto de requisitos que endereça e um conjunto de planos que a implementam.
A relação importa porque marcos e fases têm escopos de preocupação diferentes. Um marco pergunta: "O que esta versão do produto faz e o que ela não faz?" Uma fase pergunta: "Qual é a próxima coisa delimitada que podemos pesquisar, planejar, executar e verificar?"
Os limites dos marcos são traçados em fronteiras naturais do produto — uma API implantável, um fluxo de interface funcional, um modelo de dados completo. Os limites das fases são traçados nos limites do que pode ser executado com segurança em um loop sem que ele se torne incontrolável.
---
## O que define um bom escopo de fase
Vale a pena refletir sobre isso, pois é a fonte mais comum de atrito com o loop.
Uma fase muito grande torna-se um projeto de pesquisa em si mesma. O planejador tem dificuldade para decompô-la em planos independentes. Executores em ondas posteriores ficam bloqueados aguardando ondas anteriores. A verificação torna-se uma auditoria completa em vez de uma revisão direcionada. O ciclo de feedback se estende de horas para dias, e o risco de descobrir um erro de design fundamental tarde — após muito código ter sido escrito — aumenta drasticamente.
Uma fase muito pequena fragmenta trabalho que naturalmente pertence junto. Você acaba com arquivos de plano de meia dúzia de linhas, fases que completam em minutos e um custo de planejamento que supera em muito o custo de execução. O loop parece burocrático em vez de útil.
Um bom escopo de fase é aquele em que:
- O objetivo pode ser enunciado em uma única frase que não seja obviamente trivial nem suspeito de ser ampla demais.
- A pesquisa necessária para planejá-la é delimitada — as questões sobre o ecossistema têm respostas que não dependem de outras fases sendo concluídas primeiro.
- A execução pode ser paralelizada em um punhado de planos que não se sobrepõem, não dezenas.
- Existe uma definição clara e testável de "concluído" que um verificador pode checar sem ler todo o código-base.
Concretamente: "Adicionar middleware de validação de assinatura HMAC-SHA256" é um bom escopo de fase. "Construir o sistema de autenticação" geralmente não é — quase sempre contém múltiplas preocupações independentes que seriam melhor tratadas como fases separadas. "Corrigir o erro de digitação no README" está abaixo do limite onde o loop agrega valor; use `/gsd-quick` nesse caso.
Na dúvida, divida. Uma fase menor completa mais rápido, verifica com mais confiança e facilita a correção de curso se uma decisão de design se mostrar errada.
---
## Como `.planning/` transporta estado ao longo do loop
O loop não é uma sessão única. Pesquisa, planejamento e execução podem acontecer em múltiplas sessões, com reinicializações de contexto no meio. O diretório `.planning/` é o que torna isso possível.
Cada etapa do loop lê artefatos produzidos por etapas anteriores e escreve artefatos para etapas posteriores. O CONTEXT.md que a etapa Discuss produz ainda está disponível quando o Planejador roda — mesmo que isso ocorra em uma sessão diferente, horas depois. Os arquivos PLAN.md que o Planejador produz ainda estão disponíveis quando o Executor roda — mesmo após uma reinicialização. O VERIFICATION.md que o Verificador escreve ainda está disponível quando você revisa a fase.
`STATE.md` é a camada de navegação acima de tudo isso. Ele registra exatamente onde no loop o projeto está atualmente: qual marco está ativo, qual fase está em andamento, quais planos estão completos e quais estão pendentes. Qualquer agente ou fluxo de trabalho que precise se orientar lê o `STATE.md` primeiro.
Para a estrutura precisa desses arquivos, consulte [Artefatos de planejamento](../reference/planning-artifacts.md) e o [esquema do STATE.md](../reference/state-md.md).
---
## O loop é um ritmo, não uma restrição
É tentador ver o loop como burocracia — um conjunto de etapas obrigatórias que você tem que executar antes de ter permissão para escrever código. Essa visão está errada.
O loop existe porque cada etapa previne falhas que são genuinamente caras de corrigir depois. O Discuss previne o planejamento com base em suposições erradas. O Plan previne a execução de um design fundamentalmente quebrado. O Verify previne a entrega de trabalho que perdeu o escopo. Esses não são problemas inventados. São os modos de falha reais do desenvolvimento assistido por IA na escala de funcionalidades reais.
Quando o loop funciona bem, ele parece um ritmo: uma cadência de trabalho focado e delimitado em que cada etapa é clara porque a etapa anterior fez seu trabalho. O custo adicional é real, mas está concentrado no início — pago em minutos de planejamento em vez de horas de retrabalho.
Para trabalhos que ficam abaixo do limite em que o loop é justificado, o GSD Core oferece primitivas mais leves. O loop de fases é uma ferramenta, não a única ferramenta.
---
## Relacionados
- [Engenharia de contexto](context-engineering.md) — por que subagentes com contexto zerado evitam a degradação de qualidade que torna o loop necessário
- [Discutir uma fase](../how-to/discuss-a-phase.md)
- [Planejar uma fase](../how-to/plan-a-phase.md)
- [Executar uma fase](../how-to/execute-a-phase.md)
- [Verificar e entregar](../how-to/verify-and-ship.md)
- [Artefatos de planejamento](../reference/planning-artifacts.md)
- [Esquema do STATE.md](../reference/state-md.md)
- [índice de documentação](../README.md)