# 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.
