# ADR — Project Intelligence Layer determinística
## Rastreabilidade
- Orquestração: Project Intelligence Layer
- Slug: project-intelligence-layer
- Origem: docs/project-intelligence-layer/06-execution.md
- PRD aprovado: docs/project-intelligence-layer/02-prd.md
- Tech Spec aprovada: docs/project-intelligence-layer/03-techspec.md
- Refinement aprovado: docs/project-intelligence-layer/05-refinement.md
- Fonte canônica local: docs/project-intelligence-layer/traceability-map.yaml
## Status
Aceita e registrada após execução.
## Contexto
O SDD já persistia artefatos em `docs/<slug-da-orquestracao>/`, mantinha `traceability-map.yaml` como mapa local e oferecia `sdd memory learn` como índice derivado. A nova necessidade era garantir que toda etapa futura considerasse contexto relevante de forma auditável, sem depender de memória de conversa, provider específico ou infraestrutura externa.
## Problema
Sem uma camada explícita de inteligência, cada nova etapa podia ignorar decisões, riscos, ADRs, reviews, padrões e memórias já registrados. Ao mesmo tempo, transformar índices derivados em fonte de verdade criaria conflito com o artifact store canônico.
## Decisão
Implementar a Project Intelligence Layer como uma camada local, determinística e reconstruível:
- `docs/<slug-da-orquestracao>/` e `traceability-map.yaml` continuam sendo fonte canônica.
- `.sdd/memory/learnings.jsonl` e `.sdd/intelligence/*.jsonl` são caches derivados.
- `sdd intelligence learn` cria learnings enriquecidos com `source_artifact`, `source_hash`, `status` e `derived`.
- `sdd intelligence status` recalcula hashes e persiste `status: stale` quando a fonte muda.
- `sdd intelligence health` expõe sinais objetivos de saúde.
- `sdd context build` gera Context Packs por stage com manifesto auditável.
- `sdd context build` valida stages canônicos antes de montar caminhos de escrita.
- `--dry-run` não persiste mudanças em índices derivados.
- Conflitos de decisão são detectados por chave em seções de decisão e resolvidos por precedência canônica.
- O MVP não depende de embeddings, vector DB, MCP, browser, subagents ou provider específico.
## Alternativas consideradas
- **Usar apenas `sdd memory learn`:** menor escopo, mas insuficiente para Context Packs, health e stale detection explícita.
- **Adicionar vector DB/embeddings no MVP:** melhora busca semântica, mas cria dependência operacional e risco de segunda fonte de verdade.
- **Criar dashboard/TUI primeiro:** útil no futuro, mas prematuro antes do contrato local e testável.
- **Persistir tudo em docs canônicos:** auditável, mas misturaria cache derivado com artefatos aprovados e aumentaria ruído.
## Consequências
Positivas:
- Cada etapa pode receber um pacote de contexto rastreável.
- Learnings derivados ficam idempotentes e reconstruíveis.
- Stale detection reduz risco de usar contexto obsoleto.
- Stage validation reduz risco de escrita fora do diretório esperado.
- Dry-run compute-only preserva a semântica de simulação.
- Conflitos explícitos entre ADR e Memory/índice aparecem no manifesto em vez de serem resolvidos silenciosamente.
- Health torna lacunas visíveis sem bloquear projetos incompletos.
- A solução funciona em modo local/offline.
Custos:
- `src/main.rs` ganhou mais responsabilidades no primeiro corte.
- Há mais arquivos derivados em `.sdd/intelligence/`.
- A documentação precisa reforçar constantemente que índices não são fonte canônica.
## Impactos e riscos
- **Risco de acoplamento:** mitigar com extração futura para `src/domain/intelligence.rs` se a camada crescer.
- **Risco de duplicação de fonte:** mitigado por `derived: true`, documentação e precedência canônica.
- **Risco de vazamento em índices:** mitigado por `runtime::redaction::redact_text`.
- **Risco de escopo amplo:** mitigado ao excluir busca semântica, dashboard e integrações externas do MVP.
## Plano de adoção
1. Usar `sdd intelligence learn --name "<orquestracao>"` após materializar artefatos relevantes.
2. Usar `sdd context build --name "<orquestracao>" --stage <stage> --write` antes de etapas críticas.
3. Usar `sdd intelligence status --json` para verificar obsolescência.
4. Usar `sdd intelligence health --json` para acompanhar lacunas objetivas.
5. Promover padrões recorrentes para docs/rules/skills somente com checkpoint humano.
## Plano de reversão
- Remover ou ignorar `.sdd/intelligence/`; os índices são derivados.
- Continuar usando `docs/<slug>/`, `traceability-map.yaml` e `sdd memory learn`.
- Reverter os comandos `intelligence` e `context build` sem perda da fonte canônica.
## Evidências
- `cargo test`: 270 testes passaram.
- `cargo clippy -- -D warnings`: sem issues.
- `sdd intelligence learn/status/health`: comandos executados com sucesso.
- `sdd context build --stage execution --write`: Context Pack gerado.
- `sdd memory learn/status`: compatibilidade preservada.
- `sdd validate-artifact tasks/refinement`: artefatos válidos.
- Testes pós-review cobrem stage inválido, dry-run sem mutação, health stale sem status, memory indexada e conflito ADR vs Memory com precedência.
## Histórico de revisão
- 2026-06-08: ADR registrada após execução da Project Intelligence Layer.