# 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` registra PASS e o usuário autoriza `aioson feature:close --verdict=PASS`, o arquivamento acontece no mesmo ato:

```
@qa registra PASS → usuário autoriza 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
                ├── extrai os aprendizados (lê a evidência bruta)
                ├── apaga de done/{slug}/ tudo que não é documentação
                └── roda feature:sweep para arrumar o que outros fechamentos deixaram para trás
```

Não existe etapa manual. O contexto fica limpo sem que o desenvolvedor precise lembrar de nada.

### O arquivo morto guarda só documentação

Depois que a feature fecha, os arquivos que os agentes geraram para testar e analisar o sistema já cumpriram o papel. O `feature:archive` os apaga e mantém só a documentação:

| Fica | Sai |
|---|---|
| `*.md`, `*.yaml`, `*.yml` (PRD, spec, requisitos, planos, relatório de QA, dossiê, briefing) | capturas de tela, logs, `*.txt`, scripts de teste (`*.mjs`, `*.cjs`) |
| `prototype*.html` (protótipo aprovado) | `review.html`, `walkthrough.json`, JSON de execução, validação e evidência visual |
| `security-findings-{slug}.json`, `closure-review.json`, `force-bypass-findings.json` | as pastas `browser/`, `visual-screenshots/`, `evidence/`, `validator-runs/`, `reviews/`, `jev/`, `qa/`, `scouts/`, `reports/` inteiras |

`--keep-evidence` guarda tudo (no `feature:archive`, `feature:sweep` e `feature:close`). Dentro do `feature:close` a limpeza só acontece depois da extração de aprendizados, que ainda lê a evidência bruta.

### Features abandonadas

Uma feature `abandoned` sai do contexto vivo do mesmo jeito: vai para `.aioson/context/abandoned/{slug}/`, com o próprio `abandoned/MANIFEST.md`. O `feature:register --status=abandoned` já arquiva na hora (`--no-archive` deixa os arquivos onde estão). Features `paused` continuam no contexto vivo.

---

## 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 (`feature:sweep`)

Fechamentos que não passaram pelo `feature:close` deixam arquivos perdidos no contexto vivo: linha marcada `done` à mão em `features.md`, feature abandonada, ou um arquivo que um agente escreveu depois que a feature já tinha sido arquivada. O `feature:sweep` arruma tudo de uma vez:

```bash
# Ver o que seria arquivado e quanta evidência sairia dos arquivos mortos
aioson feature:sweep . --dry-run

# Arquivar e limpar
aioson feature:sweep .
```

Ele arquiva toda feature `done` ou `abandoned` que ainda tem arquivo no contexto vivo (inclusive sobras de uma já arquivada) e reduz cada pasta de `done/` e `abandoned/` a só documentação.

Os planos simples (`simple-plans/{slug}.md`) não têm comando de fechamento: o plano só muda para `status: done`. O sweep leva cada plano terminado (`done`, `abandoned` ou `dismissed`) para `done/simple-plans/`. Vão junto os arquivos companheiros (`{slug}.qa-report.md`, `{slug}.ui-spec.md`) e a pasta `features/{slug}/` com a evidência do plano, que é limpa como qualquer arquivo morto. Ficam onde estão:

- planos ainda abertos;
- planos de pendência (`source_feature`), que o `feature:closure` lê;
- planos cujo slug está registrado em `features.md`;
- planos atualizados nos últimos 2 dias, porque a sessão que acabou de terminar um pode ainda estar commitando. Uma sobra com o mesmo nome e o mesmo conteúdo da cópia arquivada é apagada; com conteúdo diferente, vira erro para conciliar à mão, nunca sobrescrita. O `feature:close` roda essa varredura sozinho ao fechar.

O comando é idempotente — rodar duas vezes é 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` | Registra PASS e recomenda o fechamento; o usuário autoriza `feature:close`, cujo archive cascateia automaticamente |
| `@dev`, `@planner`, `@tester` | 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 Export](./feature-export.md) — **copiar** (não mover) os artefatos para um local limpo, sem mexer na origem
- [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