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

| Stage | Foco do Context Pack |
|---|---|
| `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.

## 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 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 `08-memory.md` no artifact store local e reexecute `sdd intelligence learn` para atualizar os derivados.
