# Refinement - DDD Effect Rust Providers CLI

## Rastreabilidade
- Orquestração: DDD Effect Rust Providers CLI
- Slug: ddd-effect-rust-providers-cli
- Stage: refinement
- Estado atual: draft
- Origem: Tech Spec aprovada em `03-techspec.md` e backlog em `04-tasks.md`.
- Motivo: Refinement obrigatório por risco `high`.
- Decisão pendente: aprovar, pedir ajustes ou rejeitar antes de Execution.

## Resumo
O MVP deve ser menor que a visão completa: entregar DDD incremental, redaction, provider config/registry offline e introspecção de providers antes de qualquer integração remota real. A memória incremental entra depois que a base de redaction e config estiver segura. A bridge Node+Effect.ts deve ficar como spike final, não como dependência do MVP.

## Solução proposta
- MVP 1: segurança e fundação.
  - SDD-DDD-006: melhorar risk classifier para tokens/providers.
  - SDD-DDD-001: modularização interna mínima.
  - SDD-DDD-002: `SddError`, redaction e `Secret<T>`.
- MVP 2: provider registry offline.
  - SDD-DDD-003: schema/parser de provider config.
  - SDD-DDD-004: `sdd providers list/doctor`.
  - SDD-DDD-005: flags `--provider`, `--model`, `--offline` sem chamada remota.
  - SDD-DDD-008: preservar config em `sdd update`.
- MVP 3: aprendizado auditável e docs.
  - SDD-DDD-007: memory index derivado.
  - SDD-DDD-009: documentação e exemplos.
- Post-MVP/spike:
  - SDD-DDD-010: bridge Node+Effect.ts, com ADR antes de implementação ampla.

## Pontos de observação
- Não implementar chamadas reais a OpenAI/Claude/Gemini/opencode antes de `providers doctor` e redaction estarem cobertos.
- Evitar workspace multi-crate no primeiro ciclo; mover para módulos internos reduz risco.
- `codex` deve ser documentado como perfil OpenAI-compatible inicialmente, até existir contrato específico de Codex CLI/API.
- Config YAML sem parser estruturado é risco; se não houver crate YAML hoje, a execução deve decidir entre adicionar `serde_yaml` ou implementar parser restrito com testes. Recomendação: adicionar `serde` + `serde_yaml` quando a task SDD-DDD-003 começar.
- Node bridge não deve entrar no caminho crítico; nenhum comando offline pode depender de `node` ou `pnpm`.
- O worktree atual já está sujo fora desta orquestração; execução deve isolar diffs e não reverter mudanças alheias.

## Checklist
- [ ] Confirmar que Tech Spec está aprovada no traceability map.
- [ ] Executar SDD-DDD-006 primeiro para calibrar risco.
- [ ] Manter cada task em diff pequeno, com teste dedicado.
- [ ] Rodar `cargo fmt --check`, `cargo clippy -- -D warnings`, `cargo test` após cada bloco relevante.
- [ ] Testar redaction com valores reais sintéticos em env.
- [ ] Atualizar docs apenas depois do contrato CLI/config estabilizar.
- [ ] Criar ADR após execução quando provider architecture/redaction/runtime forem confirmados.

## Subtasks
| Task | Entrega | Estimativa | Dono sugerido | Bloqueia |
|---|---|---:|---|---|
| SDD-DDD-006 | Risk classifier atualizado | 3 SP | execution | MVP 1 |
| SDD-DDD-001 | Módulos internos e tipos puros | 5 SP | execution | MVP 1 |
| SDD-DDD-002 | Runtime/error/redaction base | 5 SP | execution + security review | MVP 1 |
| SDD-DDD-003 | Provider config/schema | 8 SP | execution + data contract review | MVP 2 |
| SDD-DDD-004 | Providers list/doctor | 5 SP | execution | MVP 2 |
| SDD-DDD-005 | Flags provider/model/offline | 8 SP | execution + test review | MVP 2 |
| SDD-DDD-008 | Update preserva config nova | 5 SP | execution | MVP 2 |
| SDD-DDD-007 | Memory index derivado | 8 SP | execution + data contract review | MVP 3 |
| SDD-DDD-009 | Docs/presets/examples | 3 SP | execution | MVP 3 |
| SDD-DDD-010 | Spike Node+Effect.ts | 3 SP | architecture review | Post-MVP |

## Definition of Done
- PRD, Tech Spec, Tasks e Refinement salvos em `docs/ddd-effect-rust-providers-cli/`.
- Cada task implementada tem teste ou justificativa explícita aprovada em review.
- Nenhum segredo aparece em outputs de teste, artifacts, logs ou JSON.
- Comandos existentes continuam compatíveis.
- `sdd providers doctor --json` é estável e seguro antes de qualquer provider remoto real.
- `sdd update` preserva config local nova.
- ADR pós-execução criada para decisões de DDD/runtime/provider/redaction.

## Flags e configurações
- `providers.default`: provider lógico padrão.
- `providers.offline_default`: modo determinístico local.
- `providers.profiles.<id>.enabled`: habilita provider sem exigir chamada remota.
- `providers.profiles.<id>.auth_env`: nome da variável de ambiente; valor nunca persistido.
- `runtime.node_effect_bridge.enabled`: default `false`.
- `memory.learning_enabled`: default `true`, mas sempre redigido e derivado.
- `SDD_PROVIDER`: override por env.
- `SDD_MODEL`: override por env.
- `SDD_OFFLINE`: força modo sem rede.
