# Refinement — Project Intelligence Layer
## Rastreabilidade
- Orquestração: Project Intelligence Layer
- Slug: project-intelligence-layer
- Origem: docs/project-intelligence-layer/04-tasks.md
- Estado atual: approved
- PRD aprovado: docs/project-intelligence-layer/02-prd.md
- Tech Spec aprovada: docs/project-intelligence-layer/03-techspec.md
- Backlog registrado: docs/project-intelligence-layer/04-tasks.md
- Fonte canônica local: docs/project-intelligence-layer/traceability-map.yaml
## Resumo
O backlog deve ser executado em três ondas para reduzir risco no CLI central:
1. **Fundação compatível:** comandos, config, inventário e learnings enriquecidos sem quebrar `memory learn`.
2. **Contexto utilizável:** stale detection, precedência e `context build` com manifesto auditável.
3. **Saúde e distribuição:** status, health, docs, skills e regressão completa.
Refinement é obrigatório neste ciclo porque a entrega altera interface CLI, configuração, índices locais, documentação e superfícies espelhadas.
## Solução proposta
### Onda 1 — Fundação compatível
Executar T-01, T-02 e T-03 juntas como primeira fatia de execução, mas com commits/diffs lógicos separados quando possível.
Critério para encerrar a onda:
- `sdd intelligence --help` existe.
- `sdd context recommend` continua funcionando.
- `sdd memory learn` continua gerando `.sdd/memory/learnings.jsonl`.
- `sdd intelligence learn` gera `.sdd/intelligence/learnings.jsonl`.
- Nenhum índice derivado é documentado como fonte canônica.
### Onda 2 — Contexto utilizável
Executar T-04 e T-05.
Critério para encerrar a onda:
- Alterar um artefato após learn marca fonte derivada como `stale`.
- `sdd context build --name "Project Intelligence Layer" --stage techspec --write` gera Context Pack com manifesto.
- Context Pack cita artefatos incluídos e excluídos.
- Conflitos detectados aparecem como risco, não são resolvidos silenciosamente.
### Onda 3 — Saúde e distribuição
Executar T-06, T-07, T-08 e T-09.
Critério para encerrar a onda:
- `sdd intelligence status --json` retorna contadores estáveis.
- `sdd intelligence health --json` retorna sinais objetivos.
- Docs e skills citam Context Pack e intelligence sem contradizer artifact store.
- `cargo test` e `cargo clippy -- -D warnings` são executados ou pendências são registradas com motivo.
## Pontos de observação
- **Compatibilidade:** `sdd memory learn` não pode mudar comportamento público de forma incompatível.
- **Escopo:** o MVP não inclui embeddings, vector DB, MCP, dashboard visual ou busca semântica.
- **Fonte de verdade:** `docs/<slug>/` e `traceability-map.yaml` continuam canônicos.
- **Redaction:** qualquer summary persistido em JSONL deve passar por `runtime::redaction::redact_text`.
- **Worktree sujo:** preservar alterações locais existentes e tocar somente arquivos necessários.
- **Superfícies espelhadas:** atualizar `.agents`, `.claude`, `.trae`, `.opencode` e clients apenas quando necessário para manter pacote consistente.
- **Testes:** preferir testes CLI pequenos e determinísticos antes de rodar a suíte completa.
## Checklist
- [ ] T-01 implementada e ajuda CLI verificada.
- [ ] T-02 inventaria fontes e hashes com exclusões seguras.
- [ ] T-03 preserva `memory learn` e adiciona `intelligence learn`.
- [ ] T-04 marca learnings obsoletos como `stale`.
- [ ] T-05 gera Context Pack com manifesto.
- [ ] T-06 expõe status humano e JSON.
- [ ] T-07 expõe health objetivo.
- [ ] T-08 atualiza docs e skills sem duplicar fonte de verdade.
- [ ] T-09 registra evidência de execução e validações.
- [ ] `04-tasks.md` e este Refinement continuam válidos por schema.
## Subtasks
### R-01 — Preparar contratos antes da lógica
- Implementar T-01.
- Adicionar testes mínimos de help.
- Não iniciar scanner ou learnings antes de o contrato CLI estar estável.
### R-02 — Consolidar ingestão local
- Implementar T-02 e T-03.
- Usar dados reais em `docs/project-intelligence-layer/`.
- Validar que `.sdd/memory/learnings.jsonl` continua reconstruível.
### R-03 — Tornar contexto confiável
- Implementar T-04 e T-05.
- Criar pelo menos um teste de stale detection.
- Criar pelo menos um teste de Context Pack com manifesto.
### R-04 — Fechar operação e distribuição
- Implementar T-06, T-07 e T-08.
- Rodar busca textual por comandos novos nas docs/superfícies.
- Ajustar superfícies geradas somente quando o pacote exigir.
### R-05 — Evidenciar execução
- Implementar T-09.
- Registrar `06-execution.md` com comandos executados, arquivos alterados, decisões e pendências.
## Definition of Done
- O comando `sdd intelligence learn --name "Project Intelligence Layer"` funciona em projeto local.
- O comando `sdd context build --name "Project Intelligence Layer" --stage techspec --write` gera Context Pack auditável.
- `sdd memory learn --name "Project Intelligence Layer"` permanece funcional.
- `sdd intelligence status --json` funciona com e sem índices existentes.
- `sdd intelligence health --json` reporta sinais objetivos sem falhar em orquestração incompleta.
- Índices derivados têm `source_artifact`, `source_hash`, `status` e `derived`.
- Conteúdo derivado passa por redaction.
- Docs e skills deixam claro que índices são cache reconstruível.
- Testes focados e validação completa são registrados em Execution.
## Flags e configurações
Não há feature flag runtime obrigatória para o MVP.
Configuração proposta com defaults seguros:
```yaml
intelligence:
enabled: true
index_dir: .sdd/intelligence
context_pack_dir: .sdd/intelligence/context-packs
max_context_chars: 24000
redact_secrets: true
```
Regras de compatibilidade:
- Se o bloco `intelligence` estiver ausente, usar defaults.
- Se `memory.learning_enabled` for `false`, `memory learn` deve respeitar o valor existente.
- `intelligence status` e `intelligence health` podem operar mesmo quando não há índices.
- `context build` deve falhar com mensagem clara quando `--name` aponta para orquestração inexistente.