# PRD - DDD Effect Rust Providers CLI

## Rastreabilidade
- Orquestração: DDD Effect Rust Providers CLI
- Slug: ddd-effect-rust-providers-cli
- Stage: prd
- Estado atual: approved
- Origem: `00-project-discovery.md`, `00-risk-classification.md`, `01-idea.md`.
- Decisão: aprovado pelo humano em 2026-06-06; prosseguir para Tech Spec.

## Resumo
Evoluir o `sdd-layer` de um CLI Rust monolítico para uma plataforma de orquestração SDD modular. A solução deve organizar o core por DDD, introduzir uma camada Effect-like em Rust para dependências/falhas/recursos/observabilidade, permitir uma bridge opcional Node+TypeScript com Effect.ts, adicionar provider selection no CLI e criar uma memória incremental que aprende com documentação e uso do SDD.

## Objetivos
- Definir bounded contexts do produto: `cli`, `orchestration`, `artifact_store`, `risk`, `providers`, `memory`, `clients`, `install_update`, `hooks`.
- Permitir escolher provider via CLI/config/env: `codex`/OpenAI-compatible, `claude`, `gemini`, `opencode` e `custom`.
- Suportar modelo, endpoint/base URL, auth source, budget, timeout, retry e capabilities por provider.
- Criar abstração Rust inspirada em Effect.ts para compor services/layers, erros tipados, contexto de execução, resource scope e telemetria.
- Usar Node+TypeScript com Effect.ts apenas como runtime opcional para adapters/orquestrações que dependam melhor do ecossistema JS.
- Fazer o CLI aprender com `docs/<slug>/`, `traceability-map.yaml`, ADRs, reviews e memories, gerando recomendações futuras sem substituir o artifact store.
- Manter compatibilidade com comandos existentes e com projetos já instalados.

## Não objetivos
- Reescrever todo o `src/main.rs` em uma única entrega.
- Criar um clone completo de Effect.ts em Rust.
- Armazenar ou sincronizar tokens/secrets em Markdown, Git ou memory.
- Tornar Node obrigatório para usar o CLI.
- Substituir Codex, Claude Code, opencode ou Cursor; o `sdd` continua como harness determinístico.
- Implementar billing, compra de tokens ou gestão de contas de providers.
- Criar um banco remoto de memória nesta fase.

## Usuários
- Mantenedor do `sdd-layer`.
- Usuário de CLI que quer rodar `sdd orchestration` com provider/modelo específico.
- Agente/editor que delega fluxo SDD ao CLI.
- Integrador que quer plugar um provider compatível por API.
- Revisor de segurança que precisa comprovar que tokens não vazam.

## Requisitos
- R1: O CLI deve aceitar provider e modelo em comandos de orquestração e stages, por exemplo `sdd orchestration --provider claude --model <id> "<ideia>"`.
- R2: A precedência de configuração deve ser explícita: flags CLI > env vars > `sdd.config.yaml` > default seguro.
- R3: O projeto deve ter um schema versionado para providers, incluindo `id`, `kind`, `base_url`, `auth_env`, `model`, `capabilities`, `timeouts`, `retries`, `token_budget` e `enabled`.
- R4: O provider registry deve aceitar providers conhecidos e `custom` OpenAI-compatible sem alterar o fluxo SDD.
- R5: O CLI nunca deve imprimir, salvar ou copiar API keys/tokens para docs, traceability map, logs, review ou memory.
- R6: O core Rust deve ser reorganizado incrementalmente em módulos/crates com linguagem de domínio, mantendo `src/main.rs` como composition root fino.
- R7: A camada Effect-like Rust deve padronizar context/services, erros tipados, composição de dependências, resource cleanup, retries/timeouts e observabilidade.
- R8: A bridge Node+TypeScript deve ser opcional, isolada, detectável por config e chamada como adapter; falha na bridge não pode quebrar fluxos offline que não dependem dela.
- R9: A memória incremental deve indexar somente artefatos SDD aprovados/registrados e produzir recomendações auditáveis com ponteiros para fonte.
- R10: O aprendizado deve respeitar modo offline e poder ser desabilitado por config.
- R11: `sdd doctor` e `sdd clients doctor` devem diagnosticar provider config, ausência de secrets obrigatórios, bridge Node opcional e compatibilidade de surfaces.
- R12: `sdd update` deve preservar configs locais, providers customizados, memória local e artefatos existentes.
- R13: O CLI deve expor comandos de introspecção como `sdd providers list`, `sdd providers doctor` e possivelmente `sdd memory status`.
- R14: Toda mudança de contrato público deve atualizar README, docs, schemas, presets e testes.

## Critérios de aceite
```gherkin
Cenário: escolher provider por flag no CLI
  Dado um projeto SDD configurado
  Quando eu executo `sdd orchestration --provider claude --model <modelo> "minha feature"`
  Então o CLI resolve o provider `claude`
  E registra no artefato apenas o provider/modelo selecionado
  E não registra nenhum token ou segredo
```

```gherkin
Cenário: usar provider customizado compatível
  Dado um `sdd.config.yaml` com um provider `custom` habilitado
  E a variável de ambiente de autenticação definida
  Quando eu executo `sdd providers doctor`
  Então o CLI valida endpoint, auth source e capabilities declaradas
  E mostra um diagnóstico sem exibir o valor do segredo
```

```gherkin
Cenário: continuar funcionando offline
  Dado que nenhum provider remoto está configurado
  Quando eu executo `sdd init`, `sdd doctor`, `sdd artifact status` ou `sdd validate-artifact`
  Então os comandos determinísticos continuam funcionando sem rede e sem Node
```

```gherkin
Cenário: aprendizado incremental com fonte auditável
  Dado uma orquestração com PRD, Tech Spec, Review e Memory registrados
  Quando eu executo o comando de memória incremental
  Então o CLI gera recomendações futuras com links para os artefatos de origem
  E não cria uma segunda fonte de verdade fora do artifact store
```

```gherkin
Cenário: bridge Node opcional
  Dado que a bridge Node+TypeScript está desabilitada
  Quando eu executo o fluxo SDD padrão
  Então o CLI usa apenas o core Rust
  E nenhum comando falha por falta de `node`, `pnpm` ou Effect.ts
```

## Métricas
- 100% dos comandos existentes cobertos por testes atuais continuam passando.
- 0 ocorrências de secrets em arquivos gerados por testes de redaction.
- Tempo de `sdd doctor` sem provider remoto permanece local e rápido.
- Provider registry com pelo menos 4 adapters conhecidos e 1 adapter custom testado.
- Redução mensurável do composition root: `src/main.rs` deixa de concentrar domínios novos depois da primeira fase de refactor.
- Memory/recommendations sempre apontam para artefatos locais ou links externos, nunca para conteúdo sem origem.

## Riscos
- Refactor DDD amplo pode quebrar installer/update ou gerar churn em superfícies de agentes.
- Integrações de providers mudam rápido; adapters devem isolar contratos e documentar versões/capabilities.
- Tokens em logs/docs são risco crítico; secret redaction precisa ser requisito de teste, não convenção manual.
- Bridge Node pode aumentar complexidade de distribuição; manter opcional e atrás de config.
- "Aprender sozinho" pode virar comportamento opaco; memória deve ser auditável, reversível e derivada de artefatos aprovados.
- O classificador de risco atual subestimou a feature porque não reconheceu `tokens` plural/API provider; a própria feature deve melhorar esse tipo de calibração.

## Referências externas consultadas
- Effect.ts docs: https://effect.website/docs/getting-started/introduction/
- Effect Layers: https://effect.website/docs/requirements-management/layers/
- Tower Rust: https://docs.rs/tower/latest/tower/
- Tokio Rust: https://docs.rs/tokio/latest/tokio/
- Reqwest Rust: https://docs.rs/reqwest/latest/reqwest/
- Serde derive: https://serde.rs/derive.html
- OpenAI Responses API: https://platform.openai.com/docs/api-reference/responses/object
- Claude Agent SDK: https://code.claude.com/docs/en/agent-sdk/overview
- Gemini generateContent API: https://ai.google.dev/api/generate-content
- opencode providers: https://opencode.ai/docs/providers/
