sdd-layer 0.20.1

# Tech Spec — Project Intelligence Layer

## Rastreabilidade
- Orquestração: Project Intelligence Layer
- Slug: project-intelligence-layer
- Origem: docs/project-intelligence-layer/02-prd.md
- Estado atual: approved
- PRD aprovado em: docs/project-intelligence-layer/traceability-map.yaml
- Próximo artefato: docs/project-intelligence-layer/04-tasks.md
- Fonte canônica local: docs/project-intelligence-layer/traceability-map.yaml

## Visão técnica

Implementar a Project Intelligence Layer como uma evolução determinística do CLI `sdd`, preservando o contrato atual de artifact store, memória derivada e compatibilidade de provider.

O MVP adiciona:

- `sdd context build --name "<orquestracao>" --stage <stage>` para gerar Context Packs auditáveis;
- `sdd intelligence learn --name "<orquestracao>"` para indexar aprendizados derivados;
- `sdd intelligence status --json` para inspecionar fontes, aprendizados e obsolescência;
- `sdd intelligence health --json` para expor sinais mínimos de saúde;
- reuso de `sdd memory learn` como caminho compatível ou alias para a ingestão inicial.

O núcleo continua local e reconstruível:

- fonte canônica: `docs/<slug-da-orquestracao>/` e `traceability-map.yaml`;
- cache derivado: `.sdd/memory/learnings.jsonl` e `.sdd/intelligence/*.jsonl`;
- Context Packs: `.sdd/intelligence/context-packs/<slug>/<stage>.md`;
- saída estruturada opcional: JSON em stdout quando `--json` for usado.

## Arquitetura

### Componentes

| Componente | Arquivo inicial | Papel |
|---|---|---|
| CLI commands | `src/main.rs` | Registrar subcomandos `context build` e `intelligence` |
| Artifact scanner | `src/main.rs` ou módulo futuro `src/domain/intelligence.rs` | Inventariar fontes canônicas e calcular hashes |
| Learning extractor | `src/main.rs` ou módulo futuro `src/domain/intelligence.rs` | Criar registros derivados a partir de artefatos |
| Context builder | `src/main.rs` ou módulo futuro `src/domain/intelligence.rs` | Selecionar fontes por stage e renderizar Context Pack |
| Health analyzer | `src/main.rs` ou módulo futuro `src/domain/intelligence.rs` | Calcular sinais mínimos de saúde |
| Config | `src/domain/providers.rs` | Adicionar defaults de caminhos sem quebrar `sdd.config.yaml` existente |
| Redaction | `src/runtime/redaction.rs` | Reusar `redact_text` antes de persistir conteúdo derivado |
| Testes CLI | `tests/cli.rs` | Cobrir learn, context build, stale e health |

O primeiro corte pode ficar em `src/main.rs` para seguir o padrão atual do CLI. Se a implementação crescer, mover os tipos e funções puras para `src/domain/intelligence.rs` reduz acoplamento sem mudar a interface pública.

### Novos comandos

```text
sdd context build --name "<orquestracao>" --stage <stage> [--json] [--write] [--dry-run]
sdd intelligence learn --name "<orquestracao>" [--json] [--dry-run]
sdd intelligence status [--json]
sdd intelligence health [--json]
```

Compatibilidade:

- `sdd context recommend` permanece como está.
- `sdd memory learn --name "<orquestracao>"` permanece aceito.
- `sdd intelligence learn` pode chamar a mesma rotina de ingestão enriquecida usada por `memory learn`.

### Fluxo de contexto por stage

1. Resolver root e config.
2. Resolver orquestração e artifact dir.
3. Ler `traceability-map.yaml`.
4. Inventariar artefatos da orquestração via `STAGE_FILES`.
5. Inventariar fontes globais relevantes.
6. Carregar índices derivados existentes.
7. Recalcular hash das fontes e marcar derivados obsoletos.
8. Aplicar ranking determinístico por stage.
9. Renderizar Context Pack Markdown com manifesto.
10. Persistir em `.sdd/intelligence/context-packs/<slug>/<stage>.md` quando `--write`.

### Ranking determinístico do MVP

Sem embeddings no MVP. A seleção usa pesos simples:

| Fonte | Peso base |
|---|---:|
| Artefatos anteriores da mesma orquestração | 100 |
| `traceability-map.yaml` da mesma orquestração | 95 |
| ADRs aprovadas relacionadas | 90 |
| Tech Spec/PRD aprovados | 85 |
| Reviews e memórias finais | 75 |
| `docs/_project-intelligence/*` | 70 |
| Learnings derivados ativos | 60 |
| `AGENTS.md`, rules e config | 55 |
| Eventos `.sdd/*.jsonl` seguros | 35 |

Modificadores:

- `+20` quando a fonte pertence ao stage imediatamente anterior;
- `+15` quando a fonte contém o slug atual;
- `-50` quando o registro derivado está `stale`;
- excluir quando o conteúdo viola redaction ou não é texto legível.

## Contratos

### LearningRecord JSONL

```json
{
  "kind": "decision",
  "summary": "Context Packs devem ser gerados antes de cada etapa principal.",
  "orchestration": "Project Intelligence Layer",
  "orchestration_slug": "project-intelligence-layer",
  "source_stage": "prd",
  "source_artifact": "docs/project-intelligence-layer/02-prd.md",
  "source_hash": "sha256...",
  "tags": ["context-pack", "provider-neutral"],
  "confidence": "high",
  "status": "active",
  "learned_at": "2026-06-08T00:00:00Z",
  "derived": true
}
```

Campos obrigatórios:

- `kind`: `decision`, `pattern`, `risk`, `command`, `quality_signal`, `artifact_summary`;
- `summary`: uma frase curta, redigida;
- `orchestration_slug`;
- `source_stage`;
- `source_artifact`;
- `source_hash`;
- `status`: `active`, `stale`, `superseded`, `conflict`;
- `derived: true`.

### SourceRecord JSONL

```json
{
  "path": "docs/project-intelligence-layer/02-prd.md",
  "kind": "artifact",
  "stage": "prd",
  "hash": "sha256...",
  "last_seen_at": "2026-06-08T00:00:00Z",
  "status": "active"
}
```

### ContextPack Markdown

```md
# Context Pack — <stage> — <orquestracao>

## Rastreabilidade
- Orquestração:
- Stage:
- Gerado em:
- Fonte canônica:

## Contexto essencial

## Artefatos obrigatórios

## Decisões relevantes

## Padrões úteis

## Riscos e conflitos

## Comandos e validações sugeridas

## Manifesto de contexto
- Fontes consideradas:
- Fontes incluídas:
- Fontes excluídas:
- Fontes obsoletas:
- Limite aplicado:
```

## Dados

### Caminhos

```text
.sdd/memory/learnings.jsonl
.sdd/intelligence/sources.index.jsonl
.sdd/intelligence/learnings.jsonl
.sdd/intelligence/health.json
.sdd/intelligence/context-packs/<slug>/<stage>.md
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
```

### Config

Adicionar defaults compatíveis, sem exigir atualização imediata do `sdd.config.yaml`:

```yaml
memory:
  learning_enabled: true
  index_path: .sdd/memory/learnings.jsonl
  redact_secrets: true

intelligence:
  enabled: true
  index_dir: .sdd/intelligence
  context_pack_dir: .sdd/intelligence/context-packs
  max_context_chars: 24000
  redact_secrets: true
```

Se a primeira implementação preferir menor superfície, `intelligence` pode ser um bloco novo com `Default`, mantendo `memory` intacto.

## Segurança

- Nunca persistir valores de secrets, tokens, passwords, credentials ou bearer tokens.
- Reusar `runtime::redaction::redact_text` em summaries, manifests, erros persistidos e trechos derivados.
- Não indexar arquivos binários.
- Não indexar diretórios sensíveis como `.git`, `target`, `node_modules`, `.next`, `dist`, `build`, arquivos `.env` e outputs volumosos.
- Eventos `.sdd/*.jsonl` só entram no MVP por allowlist e com redaction.
- Índices derivados não podem ser fonte de verdade para decisões que contradizem ADR ou artefato aprovado.

## Performance

- Usar leitura local sequencial no MVP.
- Limitar tamanho por fonte antes de renderizar Context Pack.
- Calcular hash por arquivo com SHA-256, padrão já usado no CLI.
- Evitar varredura ampla de todo o repositório; priorizar `docs/`, config, rules, artifact store e índices `.sdd`.
- O Context Pack deve caber em `max_context_chars`, com exclusões registradas no manifesto.

## Observabilidade

- `sdd intelligence status --json` deve expor:
  - `index_dir`;
  - `learnings`;
  - `sources_indexed`;
  - `stale_sources`;
  - `conflicts`;
  - `last_error`.
- `sdd intelligence health --json` deve expor sinais por severidade.
- `sdd context build --json` deve imprimir caminho do Context Pack, fontes incluídas e conflitos.
- Erros devem ser redigidos antes de stdout/stderr persistível.

## Testes

### Testes unitários

- Parsing e renderização de `ContextPack`.
- Hash e stale detection.
- Ranking por stage.
- Redaction em summaries e manifesto.
- Precedência entre ADR, Tech Spec, PRD, Memory e índice derivado.

### Testes CLI

Adicionar em `tests/cli.rs`:

- `intelligence_learn_indexes_artifacts_with_hash_and_status`.
- `context_build_writes_stage_pack_with_manifest`.
- `context_build_marks_changed_learning_as_stale`.
- `intelligence_health_reports_missing_memory_and_artifacts`.
- `memory_learn_remains_compatible_with_intelligence_indexing`.

### Comandos de validação

```bash
cargo test
cargo clippy -- -D warnings
./target/debug/sdd validate-artifact techspec docs/project-intelligence-layer/03-techspec.md
```

## Riscos

- **Acoplamento excessivo em `src/main.rs`:** aceitável no MVP, mas mover para `src/domain/intelligence.rs` se a implementação ultrapassar funções pequenas e testáveis.
- **Context Pack grande demais:** mitigar com `max_context_chars`, ranking e manifesto de exclusão.
- **Confundir índice com verdade:** mitigar com `derived: true`, precedência e documentação.
- **Mudança de CLI ampla:** manter `context recommend` e `memory learn` compatíveis.
- **Redaction incompleta:** cobrir com testes para tokens conhecidos e eventos `.sdd`.
- **Health subjetivo:** começar com sinais objetivos e contáveis.

## Plano de implementação

1. Adicionar tipos de argumentos CLI para `ContextCommand::Build` e `Command::Intelligence`.
2. Adicionar config `IntelligenceConfig` com defaults em `src/domain/providers.rs`.
3. Extrair funções compartilhadas para inventário de fontes e hash.
4. Evoluir `memory_learn` para produzir registros enriquecidos sem quebrar formato atual.
5. Implementar `intelligence learn` usando a rotina enriquecida.
6. Implementar `context build` com ranking determinístico e Context Pack Markdown.
7. Implementar `intelligence status`.
8. Implementar `intelligence health` com sinais mínimos.
9. Atualizar docs, skills e superfícies geradas que citam memory/context.
10. Cobrir regressões em `tests/cli.rs`.

## Diagramas

```mermaid
flowchart TD
  CLI["sdd context build"] --> Resolver["Resolver root, config e orquestração"]
  Resolver --> Trace["Ler traceability-map.yaml"]
  Resolver --> Artifacts["Inventariar STAGE_FILES em docs/<slug>/"]
  Resolver --> Global["Ler AGENTS, rules, config e docs/_project-intelligence"]
  Resolver --> Index["Carregar índices derivados"]
  Artifacts --> Rank["Rankear fontes por stage"]
  Trace --> Rank
  Global --> Rank
  Index --> Stale["Validar source_hash e stale"]
  Stale --> Rank
  Rank --> Pack["Renderizar Context Pack"]
  Pack --> Persist["Persistir .sdd/intelligence/context-packs/<slug>/<stage>.md"]
```

```mermaid
sequenceDiagram
  participant H as Humano
  participant S as sdd CLI
  participant D as docs/<slug>
  participant I as .sdd/intelligence
  participant A as Agente SDD

  H->>S: sdd context build --name X --stage techspec
  S->>D: lê traceability e artefatos aprovados
  S->>I: lê learnings e fontes indexadas
  S->>S: aplica precedência, stale detection e ranking
  S->>I: grava Context Pack
  S-->>A: entrega contexto auditável
  A->>D: produz próximo artefato
```

```mermaid
flowchart LR
  ADR["ADR aprovada"] --> Prec["Precedência"]
  TS["Tech Spec aprovada"] --> Prec
  PRD["PRD aprovado"] --> Prec
  MEM["Memory final"] --> Prec
  IDX["Índice derivado"] --> Prec
  Prec --> Chosen["Fonte usada"]
  Prec --> Conflict["Conflito exige checkpoint"]
```