@jaimevalasek/aioson 1.8.0 → 1.9.0

package/docs/pt/{feature-archive.md → 5-referencia/feature-archive.md}

@@ -1,191 +1,199 @@
-# Feature Archive — Limpeza automática do contexto
-
-O `feature:archive` move os artefatos de uma feature concluída para `.aioson/context/done/{slug}/` e mantém um manifest que permite aos agentes consultarem o histórico sem carregar os arquivos arquivados.
-
-O objetivo é manter o root de `.aioson/context/` enxuto automaticamente — o usuário não precisa fazer nada.
-
----
-
-## Como funciona
-
-Quando o `@qa` aprova uma feature e roda `aioson feature:close --verdict=PASS`, o arquivamento acontece no mesmo ato:
-
-```
-@qa aprova → aioson feature:close --feature={slug} --verdict=PASS
-                ├── atualiza spec-{slug}.md (QA sign-off)
-                ├── atualiza features.md → done
-                ├── limpa project-pulse.md
-                └── chama feature:archive automaticamente
-                        ├── move *-{slug}.{md,yaml,yml,json} → done/{slug}/
-                        └── atualiza done/MANIFEST.md
-```
-
-Não existe etapa manual. O contexto fica limpo sem que o desenvolvedor precise lembrar de nada.
-
----
-
-## Arquivos que são movidos
-
-O comando identifica os artefatos da feature pelo padrão de nome: qualquer arquivo no **root** de `.aioson/context/` que contenha o slug da feature no nome. Exemplos para `--feature=checkout`:
-
-```
-prd-checkout.md
-spec-checkout.md
-requirements-checkout.md
-architecture-checkout.md
-implementation-plan-checkout.md
-sheldon-enrichment-checkout.md
-qa-report-checkout.md
-qa-report-checkout-hardening.md   ← sufixo extra: também capturado
-conformance-checkout.yaml
-security-findings-checkout.json
-```
-
-**O que nunca é movido:**
-
-- Arquivos globais do projeto: `project.context.md`, `project-pulse.md`, `features.md`, `discovery.md`, `design-doc.md`, `prd.md`, `architecture.md`, `scan-*.md`, `test-plan.md`, `test-inventory.md`, `module-src.md`, `context-pack.md`, `memory-index.md`, `handoff-*.json`, etc.
-- Subdiretórios: `bootstrap/`, `forensics/`, `parallel/`, `seeds/`, `done/`
-- Arquivos de outra feature (proteção contra colisão de slugs similares)
-
----
-
-## O manifest
-
-Após cada arquivamento, `.aioson/context/done/MANIFEST.md` é atualizado com uma linha por feature:
-
-```markdown
-| slug | completed | files | summary |
-|------|-----------|-------|---------|
-| checkout | 2026-04-24 | 7 | Fluxo completo de checkout com Stripe e endereço. |
-| user-auth | 2026-03-10 | 5 | Autenticação JWT com refresh token e 2FA opcional. |
-```
-
-O summary é extraído automaticamente da seção `## Vision` do PRD da feature.
-
-Agentes que precisam de contexto histórico (`@cypher`, `@neo`, `@discover`, `@sheldon`) leem o manifest em vez de varrer os arquivos arquivados — custo de tokens mínimo.
-
----
-
-## Comandos disponíveis
-
-### Arquivamento (chamado automaticamente pelo feature:close)
-
-```bash
-# Já acontece automaticamente via feature:close --verdict=PASS
-aioson feature:close . --feature=checkout --verdict=PASS
-
-# Mas você pode rodar diretamente se precisar
-aioson feature:archive . --feature=checkout
-
-# Ver o que seria movido sem mover nada
-aioson feature:archive . --feature=checkout --dry-run
-
-# Desabilitar o archive automático em um feature:close específico
-aioson feature:close . --feature=checkout --verdict=PASS --no-archive
-```
-
-### Restauração (para reabrir uma feature arquivada)
-
-```bash
-# Ver o que seria restaurado
-aioson feature:archive . --feature=checkout --restore --dry-run
-
-# Restaurar os arquivos de volta ao root
-aioson feature:archive . --feature=checkout --restore
-```
-
-Após restaurar, atualize `features.md` manualmente se quiser mudar o status da feature de `done` para `in_progress`.
-
-### Arquivamento retroativo
-
-Para features que já estão como `done` em `features.md` mas ainda têm arquivos no root (projetos que fizeram upgrade do AIOSON):
-
-```bash
-aioson feature:archive . --feature=cypher-agent
-aioson feature:archive . --feature=harness-driven-aioson
-# etc.
-```
-
-O comando é idempotente — rodar duas vezes na mesma feature é no-op seguro.
-
-### Opção --force
-
-```bash
-# Arquivar mesmo que o slug não esteja registrado em features.md
-aioson feature:archive . --feature=minha-feature --force
-```
-
-Use apenas em emergências ou migrações manuais.
-
-### Saída JSON
-
-```bash
-aioson feature:archive . --feature=checkout --json
-```
-
-```json
-{
-  "ok": true,
-  "slug": "checkout",
-  "completed": "2026-04-24",
-  "archiveDir": ".aioson/context/done/checkout",
-  "moved": ["prd-checkout.md", "spec-checkout.md"],
-  "skipped": [],
-  "totalArchived": 7,
-  "manifestEntry": {
-    "slug": "checkout",
-    "completed": "2026-04-24",
-    "files": "7",
-    "summary": "Fluxo completo de checkout com Stripe e endereço."
-  }
-}
-```
-
----
-
-## Estrutura após o arquivamento
-
-```
-.aioson/context/
-├── project.context.md       ← global, nunca arquivado
-├── project-pulse.md         ← global
-├── features.md              ← registro de todas as features
-├── prd-nova-feature.md      ← feature ativa (ainda no root)
-├── done/
-│   ├── MANIFEST.md          ← resumo de todas as features concluídas
-│   ├── checkout/
-│   │   ├── prd-checkout.md
-│   │   ├── spec-checkout.md
-│   │   └── ...
-│   └── user-auth/
-│       ├── prd-user-auth.md
-│       └── ...
-└── bootstrap/               ← cache semântico (separado)
-```
-
----
-
-## Impacto nos agentes
-
-| Agente | Comportamento |
-|--------|--------------|
-| `@qa` | Roda `aioson feature:close --verdict=PASS` ao fechar — o archive cascateia automaticamente |
-| `@dev`, `@analyst`, `@architect`, `@tester`, `@pm`, `@ux-ui` | Sem mudança — já operavam apenas na feature ativa |
-| `@product` | Sem mudança — vê apenas `prd.md` e `prd-{slug}.md` ativos |
-| `@cypher` | Lê `done/MANIFEST.md` para evitar duplicar briefings de features já entregues |
-| `@neo` | Lê `done/MANIFEST.md` para contexto geral do projeto |
-| `@discover` | Lê `done/MANIFEST.md` ao montar `bootstrap/what-it-does.md` |
-| `@sheldon` | Lê `done/MANIFEST.md` — features arquivadas não aparecem no menu de enrichment |
-
----
-
-## Safety guards
-
-| Situação | Comportamento |
-|----------|--------------|
-| Feature com status `in_progress` em `features.md` | Aborta com erro (use `--force` para forçar) |
-| Feature não registrada em `features.md` | Aborta com erro (use `--force` para forçar) |
-| Arquivo já presente no destino | Skip silencioso (idempotente) |
-| `--restore` com conflito no root | Aborta e lista os conflitos — resolve manualmente |
-| `--verdict=FAIL` no feature:close | Sem arquivamento (feature permanece no root para correção) |
-| Subdiretórios em `.aioson/context/` | Nunca afetados — o glob é somente sobre arquivos no root |
+# Feature Archive — Limpeza automática do contexto
+
+O `feature:archive` move os artefatos de uma feature concluída para `.aioson/context/done/{slug}/` e mantém um manifest que permite aos agentes consultarem o histórico sem carregar os arquivos arquivados.
+
+O objetivo é manter o root de `.aioson/context/` enxuto automaticamente — o usuário não precisa fazer nada.
+
+---
+
+## Como funciona
+
+Quando o `@qa` aprova uma feature e roda `aioson feature:close --verdict=PASS`, o arquivamento acontece no mesmo ato:
+
+```
+@qa aprova → aioson feature:close --feature={slug} --verdict=PASS
+                ├── atualiza spec-{slug}.md (QA sign-off)
+                ├── atualiza features.md → done
+                ├── limpa project-pulse.md
+                └── chama feature:archive automaticamente
+                        ├── move *-{slug}.{md,yaml,yml,json} → done/{slug}/
+                        └── atualiza done/MANIFEST.md
+```
+
+Não existe etapa manual. O contexto fica limpo sem que o desenvolvedor precise lembrar de nada.
+
+---
+
+## Arquivos que são movidos
+
+O comando identifica os artefatos da feature pelo padrão de nome: qualquer arquivo no **root** de `.aioson/context/` que contenha o slug da feature no nome. Exemplos para `--feature=checkout`:
+
+```
+prd-checkout.md
+spec-checkout.md
+requirements-checkout.md
+architecture-checkout.md
+implementation-plan-checkout.md
+sheldon-enrichment-checkout.md
+qa-report-checkout.md
+qa-report-checkout-hardening.md   ← sufixo extra: também capturado
+conformance-checkout.yaml
+security-findings-checkout.json
+```
+
+**O que nunca é movido:**
+
+- Arquivos globais do projeto: `project.context.md`, `project-pulse.md`, `features.md`, `discovery.md`, `design-doc.md`, `prd.md`, `architecture.md`, `scan-*.md`, `test-plan.md`, `test-inventory.md`, `module-src.md`, `context-pack.md`, `memory-index.md`, `handoff-*.json`, etc.
+- Subdiretórios: `bootstrap/`, `forensics/`, `parallel/`, `seeds/`, `done/`
+- Arquivos de outra feature (proteção contra colisão de slugs similares)
+
+---
+
+## O manifest
+
+Após cada arquivamento, `.aioson/context/done/MANIFEST.md` é atualizado com uma linha por feature:
+
+```markdown
+| slug | completed | files | summary |
+|------|-----------|-------|---------|
+| checkout | 2026-04-24 | 7 | Fluxo completo de checkout com Stripe e endereço. |
+| user-auth | 2026-03-10 | 5 | Autenticação JWT com refresh token e 2FA opcional. |
+```
+
+O summary é extraído automaticamente da seção `## Vision` do PRD da feature.
+
+Agentes que precisam de contexto histórico (`@briefing`, `@neo`, `@discover`, `@sheldon`) leem o manifest em vez de varrer os arquivos arquivados — custo de tokens mínimo.
+
+---
+
+## Comandos disponíveis
+
+### Arquivamento (chamado automaticamente pelo feature:close)
+
+```bash
+# Já acontece automaticamente via feature:close --verdict=PASS
+aioson feature:close . --feature=checkout --verdict=PASS
+
+# Mas você pode rodar diretamente se precisar
+aioson feature:archive . --feature=checkout
+
+# Ver o que seria movido sem mover nada
+aioson feature:archive . --feature=checkout --dry-run
+
+# Desabilitar o archive automático em um feature:close específico
+aioson feature:close . --feature=checkout --verdict=PASS --no-archive
+```
+
+### Restauração (para reabrir uma feature arquivada)
+
+```bash
+# Ver o que seria restaurado
+aioson feature:archive . --feature=checkout --restore --dry-run
+
+# Restaurar os arquivos de volta ao root
+aioson feature:archive . --feature=checkout --restore
+```
+
+Após restaurar, atualize `features.md` manualmente se quiser mudar o status da feature de `done` para `in_progress`.
+
+### Arquivamento retroativo
+
+Para features que já estão como `done` em `features.md` mas ainda têm arquivos no root (projetos que fizeram upgrade do AIOSON):
+
+```bash
+aioson feature:archive . --feature=briefing-agent
+aioson feature:archive . --feature=harness-driven-aioson
+# etc.
+```
+
+O comando é idempotente — rodar duas vezes na mesma feature é no-op seguro.
+
+### Opção --force
+
+```bash
+# Arquivar mesmo que o slug não esteja registrado em features.md
+aioson feature:archive . --feature=minha-feature --force
+```
+
+Use apenas em emergências ou migrações manuais.
+
+### Saída JSON
+
+```bash
+aioson feature:archive . --feature=checkout --json
+```
+
+```json
+{
+  "ok": true,
+  "slug": "checkout",
+  "completed": "2026-04-24",
+  "archiveDir": ".aioson/context/done/checkout",
+  "moved": ["prd-checkout.md", "spec-checkout.md"],
+  "skipped": [],
+  "totalArchived": 7,
+  "manifestEntry": {
+    "slug": "checkout",
+    "completed": "2026-04-24",
+    "files": "7",
+    "summary": "Fluxo completo de checkout com Stripe e endereço."
+  }
+}
+```
+
+---
+
+## Estrutura após o arquivamento
+
+```
+.aioson/context/
+├── project.context.md       ← global, nunca arquivado
+├── project-pulse.md         ← global
+├── features.md              ← registro de todas as features
+├── prd-nova-feature.md      ← feature ativa (ainda no root)
+├── done/
+│   ├── MANIFEST.md          ← resumo de todas as features concluídas
+│   ├── checkout/
+│   │   ├── prd-checkout.md
+│   │   ├── spec-checkout.md
+│   │   └── ...
+│   └── user-auth/
+│       ├── prd-user-auth.md
+│       └── ...
+└── bootstrap/               ← cache semântico (separado)
+```
+
+---
+
+## Impacto nos agentes
+
+| Agente | Comportamento |
+|--------|--------------|
+| `@qa` | Roda `aioson feature:close --verdict=PASS` ao fechar — o archive cascateia automaticamente |
+| `@dev`, `@analyst`, `@architect`, `@tester`, `@pm`, `@ux-ui` | Sem mudança — já operavam apenas na feature ativa |
+| `@product` | Sem mudança — vê apenas `prd.md` e `prd-{slug}.md` ativos |
+| `@briefing` | Lê `done/MANIFEST.md` para evitar duplicar briefings de features já entregues |
+| `@neo` | Lê `done/MANIFEST.md` para contexto geral do projeto |
+| `@discover` | Lê `done/MANIFEST.md` ao montar `bootstrap/what-it-does.md` |
+| `@sheldon` | Lê `done/MANIFEST.md` — features arquivadas não aparecem no menu de enrichment |
+
+---
+
+## Safety guards
+
+| Situação | Comportamento |
+|----------|--------------|
+| Feature com status `in_progress` em `features.md` | Aborta com erro (use `--force` para forçar) |
+| Feature não registrada em `features.md` | Aborta com erro (use `--force` para forçar) |
+| Arquivo já presente no destino | Skip silencioso (idempotente) |
+| `--restore` com conflito no root | Aborta e lista os conflitos — resolve manualmente |
+| `--verdict=FAIL` no feature:close | Sem arquivamento (feature permanece no root para correção) |
+| Subdiretórios em `.aioson/context/` | Nunca afetados — o glob é somente sobre arquivos no root |
+
+---
+
+## Veja também
+
+- [Feature Dossier](./feature-dossier.md) — o que o dossier carrega *antes* de arquivar a feature
+- [Continuidade entre sessões](../3-receitas/continuidade-entre-sessoes.md) — retomar feature interrompida com dossier + dev-resume
+- [Fluxo de artefatos](./fluxo-artefatos.md) — mapa de quem cria o quê e quem consome

package/docs/pt/5-referencia/feature-dossier.md

@@ -0,0 +1,121 @@
+# Feature Dossier
+
+> **Para quem é:** desenvolvedores que perdem contexto entre sessões ou que colaboram num projeto com outros.
+> **Tempo de leitura:** 7 min
+> **O que você vai sair sabendo:**
+> - O que é o dossier e qual problema ele resolve
+> - Como criar, consultar e enriquecer um dossier durante o desenvolvimento
+
+## Para que serve
+
+Você chega no projeto depois de dois dias, abre o Claude Code e percebe que não lembra mais em que ponto a feature estava: o `@dev` tinha terminado a autenticação ou ainda estava na validação? A especificação mudou ou não? Quais fontes de pesquisa foram consultadas?
+
+Esse é o problema do dossier. Ele é uma pasta viva por feature — criada automaticamente ou manualmente — que concentra num único lugar a spec, o plano, as decisões, as pesquisas e o estado atual. Qualquer agente que entrar na feature vai ali primeiro.
+
+O dossier não substitui a spec nem o PRD. Ele é a *pasta de trabalho* da feature: documenta o que foi decidido, por quê, com base em quê — e atualiza esse mapa à medida que o trabalho avança.
+
+## Quando usar
+
+- Toda vez que uma feature vai durar mais de uma sessão.
+- Quando mais de uma pessoa (ou agente) vai tocar no mesmo código.
+- Quando você precisa retomar um trabalho interrompido sem reler o histórico inteiro de chat.
+- Quando quer indexar pesquisas externas (links, PDFs, notas) e referenciá-las depois.
+
+## Como funciona (visão geral)
+
+```
+aioson dossier:init . --slug=checkout-stripe
+           │
+           ▼
+.aioson/context/dossier/checkout-stripe/
+├── dossier.json          ← schema v1.2 com metadados, status, classification
+├── research-index.json   ← índice de pesquisas adicionadas
+├── codemap.json          ← mapa de arquivos relevantes (bootstrap opcional)
+└── notes.md              ← notas livres da sessão atual
+           │
+           ▼
+Agentes leem dossier antes de qualquer ação:
+@dev → @qa → @validator → @committer
+```
+
+O dossier é **auto-inicializado** quando você roda `aioson feature:close` ou `aioson workflow:next` — se ainda não existir para a feature em andamento, o sistema cria. Você também pode criar manualmente para features novas.
+
+## Comandos
+
+```bash
+# Criar dossier para uma feature
+aioson dossier:init . --slug=<kebab-case>
+
+# Ver estado atual do dossier
+aioson dossier:show . --slug=<kebab-case>
+
+# Adicionar pesquisa ao índice (URL ou caminho local)
+aioson dossier:add-research . --slug=<kebab-case> --research-slug=<id-da-pesquisa>
+
+# Auditar consistência do dossier (detecta drift, artefatos faltando)
+aioson dossier:audit . --slug=<kebab-case>
+
+# Bootstrap do mapa de código (identifica arquivos relevantes para a feature)
+aioson dossier:codemap-bootstrap . --slug=<kebab-case>
+
+# Saída em JSON (para integração com CI ou scripts)
+aioson dossier:show . --slug=<kebab-case> --json
+```
+
+Flags comuns:
+- `--slug=<kebab-case>` — identificador da feature (obrigatório)
+- `--json` — saída estruturada em vez de texto
+- `--classification=MICRO|SMALL|MEDIUM` — sobrescreve a classificação detectada
+
+## Exemplo prático
+
+```
+# Sessão 1
+Você > aioson dossier:init . --slug=checkout-stripe
+> Dossier criado: .aioson/context/dossier/checkout-stripe/dossier.json
+> Classification detectada: SMALL
+> Próximo: adicione pesquisas ou comece com @product.
+
+Você > @dev
+@dev > Lendo dossier checkout-stripe... spec encontrada, plano de implementação OK.
+@dev > Implementando: src/payments/stripe-handler.js, src/routes/checkout.js
+@dev > dev-state.md atualizado. Sessão encerrada às 18h.
+
+# Sessão 2 (dia seguinte)
+Você > @neo
+@neo > Dossier checkout-stripe: @dev terminou stripe-handler, falta integrar com routes.
+      Próximo: continuar com @deyvin ou retomar @dev.
+
+Você > aioson dossier:show . --slug=checkout-stripe
+> Status: in_progress | Agente atual: @dev | Último checkpoint: stripe-handler done
+> Artefatos: spec.md ✓ | dev-state.md ✓ | codemap.json ✓
+> Pesquisas indexadas: 0
+
+Você > @deyvin
+@deyvin > Retomando checkout-stripe. Lendo dossier e dev-state...
+         Último ponto: stripe-handler implementado, rota de webhook pendente.
+```
+
+## Saídas em disco
+
+```
+.aioson/context/dossier/<slug>/
+├── dossier.json           ← metadados: status, classification, agent, timestamps
+├── research-index.json    ← entradas de pesquisa (schema v1.2)
+├── codemap.json           ← arquivos relevantes mapeados (após codemap-bootstrap)
+└── notes.md               ← notas livres (opcional)
+```
+
+O `dossier.json` referencia artefatos via `artifact_uris` — caminhos relativos para spec, PRD, architecture.md e outros.
+
+## Quando NÃO usar
+
+- Features de um único comando, sem continuidade esperada. Um MICRO de 30 minutos não precisa de dossier.
+- Você vai usar `@deyvin` para retomar e ele já lê `dev-state.md` diretamente. Para esses casos o dossier é opcional.
+- Quando o projeto usa o `runner-system` com fases automáticas — o runner gerencia o ciclo e cria os artefatos necessários.
+
+## Próximo passo
+
+- [Agent-chain continuity](./agent-chain-continuity.md) — como dossier, handoff-protocol e dev-resume trabalham juntos
+- [Feature Archive](./feature-archive.md) — o que acontece quando a feature é fechada
+- [Ficha do @deyvin](../4-agentes/deyvin.md) — agente de retomada que lê o dossier