# Project Intelligence Layer
## Rastreabilidade
- Origem: `docs/project-intelligence-layer/02-prd.md`
- Tech Spec: `docs/project-intelligence-layer/03-techspec.md`
- Tasks: `docs/project-intelligence-layer/04-tasks.md`
- Refinement: `docs/project-intelligence-layer/05-refinement.md`
- Estado atual: documentação operacional da T-08
- Fonte canônica local: `docs/project-intelligence-layer/traceability-map.yaml`
## Visão operacional
A Project Intelligence Layer adiciona contexto operacional ao fluxo SDD sem criar uma segunda fonte de verdade. Ela lê artefatos aprovados, mapas de rastreabilidade, ADRs, reviews, memórias finais, regras e configurações do projeto para montar contexto curto, auditável e específico para cada etapa.
O contrato central é:
- `docs/<slug-da-orquestracao>/` e `traceability-map.yaml` continuam sendo a fonte canônica local quando não houver sistema externo confiável.
- `.sdd/intelligence/*.jsonl` e `.sdd/memory/learnings.jsonl` são índices derivados, reconstruíveis e auditáveis.
- Context Packs são pacotes de trabalho para agentes, não documentos de decisão.
- Learnings derivados podem sugerir promoções para docs, rules ou skills, mas nunca aplicam mudanças sem checkpoint humano.
## Comandos principais
### `sdd intelligence learn`
```bash
sdd intelligence learn --name "<orquestracao>"
sdd intelligence learn --all
```
Indexa aprendizados derivados a partir dos artefatos locais da orquestração. Os registros devem apontar para a origem com `source_artifact`, `source_hash`, estágio, status e `derived: true`.
Uso esperado:
- rode depois de salvar PRD, Tech Spec, Tasks, Review ou Memory relevantes;
- use `--all` para reconstruir o índice derivado de todos os diretórios `docs/*/` que tenham `traceability-map.yaml`;
- trate o resultado como cache reconstruível;
- reexecute quando artefatos canônicos mudarem;
- preserve `sdd memory learn --name "<orquestracao>"` como caminho compatível quando disponível.
### `sdd intelligence repair`
```bash
sdd intelligence repair --name "<orquestracao>" --json
sdd intelligence repair --all --json
```
Fecha os sinais operacionais `missing-memory` e `stale-learning` sem promover cache derivado a fonte primária. Quando uma orquestração tem `traceability-map.yaml` mas não possui `08-memory.md`, o comando gera uma memória operacional determinística a partir dos artefatos existentes, com seções para decisões, falhas recorrentes, comandos confiáveis e padrões por repo. Em seguida, reconstrói `.sdd/intelligence/learnings.jsonl` para atualizar hashes e remover stale causado por artefatos alterados.
Uso esperado:
- rode quando `sdd health --json` ou `sdd intelligence health --json` apontar `missing-memory` ou `stale-learning`;
- use `--dry-run` para ver arquivos e índices que seriam escritos;
- revise o `08-memory.md` gerado quando houver decisão humana relevante que não esteja clara nos artefatos de origem;
- trate `missing-artifact` informativo separadamente: ele continua visível, mas não impede o health de ficar `pass` quando não houver warning.
### `sdd intelligence status`
```bash
sdd intelligence status --json
```
Mostra o estado objetivo dos índices derivados: diretório de índice, quantidade de fontes, learnings, fontes obsoletas, conflitos e último erro conhecido.
Use para responder perguntas como:
- existem fontes indexadas?
- algum learning ficou `stale` porque o hash da origem mudou?
- há conflitos detectados que precisam aparecer no Context Pack?
- o índice está ausente, vazio ou reconstruível?
### `sdd intelligence health`
```bash
sdd intelligence health --json
sdd intelligence health --json --fail-on high
```
Calcula sinais mínimos de saúde do fluxo SDD, sempre com base em evidências locais. Exemplos: orquestrações sem `08-memory.md`, artefatos obrigatórios ausentes, índices obsoletos, reviews com achados recorrentes e riscos sem mitigação registrada.
O health report é diagnóstico. Ele não aprova merge, deploy, promoção de rules ou alteração de artefato canônico. Use `--fail-on <severity>` em CI/checkpoints para retornar erro quando houver sinais no nível indicado ou acima (`info`, `warning`, `high`, `critical`).
### `sdd context build`
```bash
sdd context build --name "<orquestracao>" --stage <stage>
sdd context build --name "<orquestracao>" --stage <stage> --write
```
Gera um Context Pack para uma etapa específica do fluxo. A coleta considera a orquestração atual, fontes globais e artefatos históricos encontrados em `docs/*/traceability-map.yaml`; o ranking prioriza a feature atual e depois ADRs, Tech Specs, memórias e rastreabilidade histórica. Com `--write`, o pacote é persistido em:
```text
.sdd/intelligence/context-packs/<slug>/<stage>.md
```
O Context Pack deve incluir:
- rastreabilidade da orquestração e do stage;
- contexto essencial para a etapa;
- artefatos obrigatórios e fontes incluídas;
- decisões relevantes;
- padrões úteis;
- riscos, conflitos e fontes obsoletas;
- comandos e validações sugeridas;
- manifesto de contexto com fontes consideradas, incluídas, excluídas e limite aplicado.
### Optimization Wrapper
```bash
sdd optimize status --json
sdd optimize compress --kind trace < trace.log
sdd optimize compress --kind handoff --file handoff.md
```
O Optimization Wrapper é uma camada operacional em cima de CodeGraph, RTK e Caveman. As três ferramentas são opcionais: quando ausentes ou sem índice, o SDD continua usando fallback local e registra a decisão no Context Pack.
Comportamento esperado:
- CodeGraph: preferir `context`, `query`, `files` e `affected` quando o índice existir; sem índice, usar `git diff/status`, manifests e `rg` delimitado.
- Init: `sdd init` tenta executar `codegraph init -i .` automaticamente quando `optimization.codegraph.auto_index` está ativo, CodeGraph existe no `PATH` e `.codegraph/` ainda não existe.
- RTK: executar comandos longos ou ruidosos com saída filtrada, preservando o comando bruto para diagnóstico quando houver falha.
- Caveman: compactar traces, handoffs e memória derivada, preservando paths, comandos, IDs, URLs, hashes e critérios. Artefatos formais continuam completos e validáveis.
- Bounds: ignorar `.git`, `.codegraph`, `.sdd`, `target`, `node_modules`, `dist`, `build`, `.next`, caches e saídas temporárias salvo justificativa explícita no plano.
- Loop produtivo: cada iteração precisa testar uma hipótese nova, ler uma fonte nova, reduzir escopo ou produzir evidência nova; repetir erro, diff, comando ou busca sem ganho deve parar com blocker/decisão registrado.
## Context Pack por etapa
Cada stage recebe contexto diferente:
| `idea` | contexto de produto, histórico de features similares, riscos e objetivos recorrentes |
| `prd` | decisões de produto, usuários, métricas e critérios já usados |
| `techspec` | ADRs, padrões de arquitetura, contratos, áreas de código e riscos técnicos |
| `tasks` | plano técnico aprovado, dependências, DoD, prompts de agente e comandos prováveis |
| `execution` | task atual, escopo permitido, arquivos prováveis, padrões, riscos e validação |
| `review` | critérios de aceite, diffs, evidências, riscos e padrões de review |
| `memory` | decisões finais, pendências, padrões úteis e ponteiros canônicos |
Antes de uma etapa crítica, gere o Context Pack e leia o manifesto. Se houver conflito sem precedência clara, pare em checkpoint humano antes de avançar.
## Fonte canônica e índices derivados
A precedência de verdade é explícita:
1. ADR aprovada.
2. Tech Spec aprovada.
3. PRD aprovado.
4. Tasks registradas.
5. Execution e Review.
6. Memory final.
7. Índice derivado.
Índices derivados ajudam a recuperar contexto, mas não decidem. Se `.sdd/intelligence/learnings.jsonl` contradizer uma ADR ou um artefato aprovado, o artefato aprovado prevalece e o conflito deve aparecer no manifesto.
Nunca copie documentos inteiros para o índice. Registre resumos curtos e ponteiros canônicos. Se o índice for apagado, o projeto deve conseguir reconstruí-lo a partir de `docs/<slug-da-orquestracao>/`, `traceability-map.yaml` e demais fontes permitidas.
## Redaction
Todo conteúdo persistido em índices, Context Packs, eventos e relatórios deve passar pelo redactor central antes de ser gravado ou exibido como evidência persistível.
Regras práticas:
- não indexar `.env`, credenciais, tokens, chaves privadas, dumps ou arquivos binários;
- não gravar bearer tokens, API keys, passwords ou secrets em summaries, manifests ou erros;
- aplicar redaction também em mensagens de erro e trechos de logs usados como fonte;
- preferir allowlist para eventos `.sdd/*.jsonl` em vez de varredura ampla.
Se uma fonte não puder ser redigida com segurança, exclua-a do Context Pack e registre o motivo no manifesto.
## Contexto via MCP
Quando o client tiver MCP disponível, use `sdd_context_bundle` como primeira leitura antes de gerar, executar ou revisar uma etapa:
```text
sdd_context_bundle({ "orchestration": "<orquestracao>", "stage": "execution", "task": "T-04" })
sdd://context-bundle/<slug>/execution
```
O bundle combina Project Intelligence, artifact store, Context Pack, Context Handoff, trace summary, busca local, capability catalog, runtime adapters e recomendações de chamadas CodeGraph. Ele é a superfície principal de leitura para agentes MCP porque reduz chamadas dispersas e entrega um pacote auditável parecido com um contexto estrutural, mas não muda a precedência de verdade: ADRs, Tech Spec, PRD, Tasks, Execution/Review, Memory e `traceability-map.yaml` continuam canônicos.
Fluxo recomendado em clients MCP:
1. Leia `sdd_context_bundle`.
2. Use as chamadas em `codegraph_companion.recommended_mcp_calls` para mapear símbolos, callers/callees e impacto quando houver código.
3. Execute ou gere somente dentro do stage e do escopo retornados pelo bundle.
4. Valide com `sdd validate-artifact`, `sdd eval stage` ou testes do projeto e registre evidências no artifact store local.
## Provider-neutralidade
O MVP deve funcionar sem vector DB, embeddings, MCP, browser ou API externa. O núcleo usa:
- arquivos Markdown;
- YAML;
- JSONL;
- comandos locais `sdd`;
- hashes de fonte;
- manifesto auditável;
- validação local.
Providers, modelos, subagents e integrações externas podem consumir o Context Pack, mas não fazem parte da fonte de verdade. O mesmo projeto deve continuar operável por Codex, Claude, Cursor, opencode, Antigravity, Devin ou modo Markdown-only quando eles respeitam os arquivos e comandos locais.
## Fluxo recomendado
```bash
sdd init "<nome-da-orquestracao>"
sdd artifact save "<nome-da-orquestracao>" prd --file prd.md --state approved
sdd artifact save "<nome-da-orquestracao>" techspec --file techspec.md --state approved
sdd intelligence learn --name "<nome-da-orquestracao>"
sdd intelligence learn --all
sdd intelligence repair --name "<nome-da-orquestracao>" --json
sdd intelligence status --json
sdd context build --name "<nome-da-orquestracao>" --stage execution --write
sdd intelligence health --json --fail-on high
```
Use o Context Pack gerado como entrada de trabalho para o agente da etapa. Ao final da feature, salve ou revise `08-memory.md` no artifact store local e reexecute `sdd intelligence learn` para atualizar os derivados; quando `health` apontar memória ausente ou stale, use `sdd intelligence repair` como reparo explícito.