# PRD — Project Intelligence Layer

## Rastreabilidade
- Orquestração: Project Intelligence Layer
- Slug: project-intelligence-layer
- Origem: docs/project-intelligence-layer/01-idea.md
- Estado atual: approved
- Decisão humana anterior: direção aprovada em 2026-06-08.
- Próximo checkpoint: aprovação deste PRD antes da Tech Spec.
- Fonte canônica local: docs/project-intelligence-layer/traceability-map.yaml

## Resumo

Construir uma camada de inteligência evolutiva para o SDD que garanta que toda ideia, planejamento, execução e review considere o contexto máximo disponível do projeto sem transformar memória derivada em fonte de verdade.

A solução introduz três capacidades principais:

- **Ingestão rastreável:** extrair aprendizados de artefatos canônicos, ADRs, reviews, memórias e sinais `.sdd`.
- **Context Pack obrigatório:** montar contexto curto, auditável e específico antes de cada etapa SDD.
- **Saúde evolutiva:** revelar padrões recorrentes, riscos, conflitos, lacunas de rastreabilidade e oportunidades de promover conhecimento para docs, rules ou skills.

O núcleo deve funcionar com Markdown, YAML, JSONL, CLI `sdd` e validação local. Busca semântica, embeddings, vector DB, MCP e integrações externas são aceleradores opcionais, não dependências do contrato.

## Objetivos

- Garantir que cada etapa SDD comece com contexto relevante, rastreável e atualizado.
- Unificar a leitura de artefatos históricos sem duplicar conteúdo entre sistemas.
- Preservar `docs/<slug-da-orquestracao>/` como fonte canônica quando não houver sistema externo confiável.
- Tratar `.sdd/memory/learnings.jsonl` e futuros índices como cache derivado e reconstruível.
- Reduzir redescoberta de decisões, padrões e riscos já documentados.
- Detectar conflitos entre artefatos antes de etapas de alto impacto.
- Criar base para melhoria contínua da saúde do projeto.
- Manter compatibilidade com qualquer provider/modelo/client que consiga operar com Markdown, arquivos e comandos `sdd`.

## Não objetivos

- Não criar uma base paralela que substitua PRD, Tech Spec, ADR, Review ou Memory.
- Não depender de vector DB, embeddings ou API externa para o MVP.
- Não exigir MCP, browser, subagents ou ferramenta visual para o comportamento essencial.
- Não copiar documentos inteiros para índices derivados.
- Não promover automaticamente aprendizados para rules, skills ou AGENTS sem checkpoint humano.
- Não implementar dashboard visual no primeiro corte.
- Não resolver integrações Jira, Confluence, GitHub, GitLab ou Bitbucket além de guardar ponteiros canônicos quando existirem.

## Usuários

- **Lead humano do SDD:** precisa aprovar decisões com evidência e ver se o projeto está ficando mais saudável.
- **Agente de planejamento:** precisa criar Idea, PRD, Tech Spec e Tasks com base no histórico real.
- **Agente executor:** precisa saber decisões, limites, comandos e riscos antes de alterar código.
- **Agente reviewer:** precisa relacionar diffs a critérios de aceite, ADRs, riscos e padrões já existentes.
- **Mantenedor da camada SDD:** precisa evoluir comandos, schemas e skills sem quebrar provider-compatibility.
- **Projeto instalado:** precisa operar com fallback local quando integrações externas estiverem ausentes ou parciais.

## Requisitos

### RF-01 — Inventário de fontes canônicas

O SDD deve conseguir inventariar fontes relevantes do projeto:

- `AGENTS.md`, `CLAUDE.md` e rules instaladas;
- `sdd.config.yaml`;
- `docs/<slug-da-orquestracao>/traceability-map.yaml`;
- artefatos SDD por etapa;
- ADRs;
- reviews;
- memórias finais;
- diretórios `docs/_project-intelligence/`, quando existirem;
- eventos locais `.sdd/*.jsonl`, quando seguros e úteis;
- manifests e comandos conhecidos do projeto, quando o stage exigir contexto operacional.

### RF-02 — Índices derivados reconstruíveis

O SDD deve armazenar learnings em JSONL derivado, com no mínimo:

- tipo do aprendizado;
- resumo curto;
- origem da orquestração;
- estágio de origem;
- `source_artifact`;
- `source_hash`;
- tags;
- confiança;
- estado (`active`, `stale`, `superseded`, `conflict`);
- timestamp de aprendizado;
- marcação `derived: true`.

### RF-03 — Context Pack por etapa

Antes de gerar ou executar uma etapa principal, o SDD deve produzir um Context Pack específico para o stage:

- `/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 do código e riscos técnicos;
- `/tasks`: plano técnico aprovado, dependências, DoD, prompts agent 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.

### RF-04 — Manifesto de contexto

Todo Context Pack deve incluir um manifesto auditável com:

- fontes consideradas;
- fontes incluídas;
- fontes excluídas e motivo;
- fontes obsoletas por hash;
- conflitos detectados;
- limite de tamanho aplicado;
- comandos ou validações recomendadas.

### RF-05 — Precedência de verdade

Quando houver conflito, a camada deve aplicar precedência 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.

Quando a precedência não resolver, o Context Pack deve marcar conflito e exigir checkpoint antes da próxima etapa crítica.

### RF-06 — Redação de segredos

Todo índice, Context Pack, evento e relatório deve passar pelo redactor central antes de persistir conteúdo derivado.

### RF-07 — Health signals

O SDD deve calcular sinais mínimos de saúde:

- orquestrações sem memória final;
- artefatos obrigatórios ausentes;
- PRDs ou Tech Specs sem validação;
- ADRs ausentes após decisões arquiteturais;
- riscos recorrentes sem mitigação;
- reviews com achados repetidos;
- comandos de validação recorrentes;
- padrões úteis ainda não promovidos;
- fontes derivadas `stale` por mudança de hash.

### RF-08 — Promoção com checkpoint

Learnings recorrentes podem sugerir atualizações em:

- `docs/_project-intelligence/project-profile.md`;
- `docs/_project-intelligence/architecture-map.md`;
- `docs/_project-intelligence/decision-index.md`;
- `docs/_project-intelligence/patterns-and-conventions.md`;
- `docs/_project-intelligence/risk-register.md`;
- `docs/_project-intelligence/quality-health.md`;
- `.agents/skills/*`;
- rules de clients.

Nenhuma promoção deve ser aplicada sem checkpoint humano explícito.

### RF-09 — Provider compatibility

O MVP deve funcionar com:

- Markdown;
- YAML;
- JSONL;
- comandos `sdd`;
- validação local;
- artifact store local.

Busca semântica, embeddings, vector DB, MCP, browser, subagents e screenshots devem ser opcionais.

### RF-10 — Comandos propostos

O MVP deve introduzir ou evoluir comandos determinísticos:

```bash
sdd context build --name "<orquestracao>" --stage <stage>
sdd intelligence learn --name "<orquestracao>"
sdd intelligence status --json
sdd intelligence health --json
```

Se for melhor para compatibilidade inicial, `sdd memory learn` pode ser preservado como alias ou base do `sdd intelligence learn`.

## Critérios de aceite

```gherkin
Funcionalidade: Context Pack obrigatório
  Cenário: Gerar contexto para Tech Spec
    Dado que existe uma orquestração com Idea e PRD salvos em docs/project-intelligence-layer
    Quando eu executar sdd context build --name "Project Intelligence Layer" --stage techspec
    Então o SDD deve gerar um Context Pack com origem, fontes incluídas, decisões relevantes, riscos e próximo artefato esperado
    E o pacote deve citar os caminhos dos artefatos usados
```

```gherkin
Funcionalidade: Índice derivado reconstruível
  Cenário: Aprender a partir dos artefatos locais
    Dado que existem artefatos em docs/project-intelligence-layer
    Quando eu executar sdd intelligence learn --name "Project Intelligence Layer"
    Então o SDD deve escrever registros JSONL derivados com source_artifact e source_hash
    E nenhum registro deve ser tratado como fonte canônica
```

```gherkin
Funcionalidade: Detecção de obsolescência
  Cenário: Artefato muda depois de indexado
    Dado que um aprendizado possui source_hash calculado
    Quando o arquivo de origem for alterado
    Então o status do aprendizado deve ser marcado como stale ou reprocessado
    E o Context Pack deve evitar usar esse aprendizado como verdade confirmada
```

```gherkin
Funcionalidade: Precedência entre fontes
  Cenário: Memory contradiz ADR aprovada
    Dado que uma Memory final contradiz uma ADR aprovada
    Quando eu gerar um Context Pack para execução
    Então a ADR deve ter precedência
    E o conflito deve aparecer no manifesto de contexto
```

```gherkin
Funcionalidade: Operação provider-neutral
  Cenário: Rodar sem vector DB ou MCP
    Dado que o projeto está em modo local/offline
    Quando eu executar intelligence learn e context build
    Então o fluxo deve funcionar usando apenas arquivos locais, JSONL, YAML, Markdown e o CLI sdd
```

## Métricas

- Percentual de etapas com Context Pack gerado antes da produção do artefato.
- Número de fontes canônicas consideradas por Context Pack.
- Número de conflitos detectados antes de Tech Spec, Execution ou Review.
- Número de aprendizados marcados como `stale` e reprocessados.
- Redução de achados repetidos em reviews.
- Percentual de orquestrações com `08-memory.md` salvo.
- Número de padrões promovidos para docs/rules/skills após checkpoint humano.
- Tempo médio para um agente localizar comandos, decisões e riscos relevantes.

## Riscos

- **Escopo amplo demais:** tentar entregar busca semântica, health, promoção de rules e contexto perfeito no primeiro corte. Mitigação: começar com inventário, JSONL e Context Pack determinístico.
- **Segunda fonte de verdade:** índices derivados podem ser confundidos com documentação canônica. Mitigação: campo `derived: true`, precedência explícita e documentação clara.
- **Contexto excessivo:** pacotes grandes podem piorar a resposta do modelo. Mitigação: ranking por stage, manifesto de exclusões e limite de tamanho.
- **Conflitos silenciosos:** artefatos antigos podem contradizer decisões recentes. Mitigação: hashes, status `stale` e precedência.
- **Vazamento de segredo:** eventos e logs podem conter tokens. Mitigação: redactor central obrigatório antes de persistir derivados.
- **Dependência de provider específico:** recursos avançados podem quebrar portabilidade. Mitigação: núcleo baseado em arquivos e CLI.

## Diagramas

```mermaid
flowchart TD
  A["Artefatos canônicos em docs/<slug>/"] --> B["Ingestão intelligence learn"]
  C["Traceability map"] --> B
  D["ADRs, reviews e memory"] --> B
  E["Eventos .sdd seguros"] --> B
  B --> F["Índices derivados JSONL"]
  F --> G["Context build por stage"]
  A --> G
  C --> G
  G --> H["Context Pack auditável"]
  H --> I["Agente SDD gera ou executa etapa"]
  I --> J["Novo artefato salvo"]
  J --> A
```

```mermaid
flowchart LR
  ADR["ADR aprovada"] --> P["Precedência"]
  TS["Tech Spec aprovada"] --> P
  PRD["PRD aprovado"] --> P
  MEM["Memory final"] --> P
  IDX["Índice derivado"] --> P
  P --> OK["Fonte escolhida"]
  P --> C["Conflito para checkpoint"]
```
