# Tech Spec - SDD Runtime-Agnostic Engines e Adapters

## Rastreabilidade
- Orquestração: a-jogada-mais-limpa-sdd-continua-runtime-agnostic-o-core-segue-dono-do-contrato-sdl-8ee3bafff01a
- Slug: a-jogada-mais-limpa-sdd-continua-runtime-agnostic-o-core-segue-dono-do-contrato-sdl-8ee3bafff01a
- Stage: techspec
- Estado atual: approved
- Origem: PRD aprovado em `02-prd.md`, Idea em `01-idea.md`, Discovery em `00-project-discovery.md`, Risk em `00-risk-classification.md`
- Evidência de contexto: `sdd context build --name "a-jogada-mais-limpa-sdd-continua-runtime-agnostic-o-core-segue-dono-do-contrato-sdl-8ee3bafff01a" --stage techspec`
- Code intelligence: CodeGraph consultado para `runtime_adapters`, `SddMcpBackend`, `CapabilityCatalog`, provider registry, trace e engine
- Decisões relacionadas: `docs/implementar-no-projeto-o-rig-rmcp-rmcp-para-fortalecer-o-mcp-rust-nativo-rig-como-provider-tool-adapter-opcional/06-adr.md`, `docs/project-intelligence-layer/06-adr.md`

## Visão técnica
O `sdd-layer` deve manter o core como harness determinístico do contrato SDLC, sem transferir regras de stage, checkpoint, artifact store ou traceability para engines externas. Runtimes como Rig, Flue, LangGraph, Agno e futuros frameworks entram como adapters opcionais: podem fornecer roteamento, execução, tools, composição ou metadata, mas nunca substituem o contrato canônico.

O estado atual já tem as bases certas:
- `src/main.rs` centraliza CLI, artifact store, validação de artefatos, `resolve-input`, `context build`, `clients doctor`, `capabilities doctor` e o backend MCP.
- `src/runtime/mcp.rs` expõe `RuntimeAdapterDefinition`, `runtime_adapters()` e o transporte MCP stdio manual.
- `Cargo.toml` mantém `rmcp` e `rig-core` como dependências opcionais por feature (`mcp-rmcp`, `rig-adapter`) com `default = []`.
- `templates/capability-catalog.yaml` já modela capabilities portáveis, adapters por client, fallback e validação.
- `src/domain/providers.rs` mantém provider registry determinístico, offline-friendly, com config versionada.
- `.agents` segue como contrato canônico de skills; `.codex`, `.claude`, `.cursor`, `.opencode`, `.devin`, `.trae` e Antigravity são superfícies geradas/sincronizadas.

A implementação deve ser incremental: primeiro consolidar contratos e validações; depois materializar adapters específicos. Flue, LangGraph e Agno devem entrar inicialmente como metadata/capability docs ou adapters planejados, não como dependências obrigatórias, até que uma task de execução verifique pacote, API, licença, runtime e fallback.

## Arquitetura
### Boundaries
| Camada | Dono | Responsabilidades | Não pode fazer |
|---|---|---|---|
| Core SDD | `src/main.rs`, `contract`, artifact store | Stages, schemas, checkpoints, traceability, `resolve-input`, `artifact save`, validations | Depender de runtime externo no caminho padrão |
| Runtime/MCP | `src/runtime/mcp.rs`, `src/runtime/trace.rs` | Expor observabilidade, adapters disponíveis, recursos e tools read-only | Virar fonte canônica de estado |
| Provider registry | `src/domain/providers.rs`, `sdd.config.yaml` | Resolver provider/modelo/offline/login/capabilities | Confundir framework runtime com provider obrigatório |
| Capability catalog | `templates/capability-catalog.yaml` | Declarar capability, adapter, fallback e validação | Duplicar lógica de execução do core |
| Client surfaces | `.codex`, `.claude`, `.cursor`, `.opencode`, `.devin`, `.trae`, `.agents` | Distribuir o mesmo contrato para cada harness | Introduzir requisito exclusivo de provider/client |
| Runtime adapters | Rig, Flue, LangGraph, Agno, futuros | Enriquecer execução, roteamento, tools ou orquestração externa | Possuir stages, checkpoints ou artifact store |

### Componentes técnicos
- `RuntimeAdapterDefinition`: contrato mínimo para qualquer adapter runtime (`id`, `kind`, `crate_name`, `feature`, `enabled`, `role`, `fallback`, `capabilities`).
- `runtime_adapters()`: registry local dos adapters compilados/conhecidos. Hoje cobre `rmcp` e `rig`; deve ser estendido sem alterar defaults.
- `SddMcpBackend::call_tool("sdd_runtime_adapters")`: superfície MCP para clients descobrirem adapters e fallbacks.
- `SddMcpBackend::read_resource("sdd://runtime/adapters")`: recurso MCP equivalente, derivado do mesmo registry.
- `capabilities doctor --targets all`: guarda semântico para capability coverage e drift entre fontes canônicas e surfaces.
- `clients doctor --strict`: guarda de distribuição para `.agents` e client surfaces.

### Estratégia de evolução
1. Manter o caminho default sem feature opcional e sem dependência de rede.
2. Tratar cada runtime como feature/adaptação isolada, com fallback textual e CLI.
3. Expor disponibilidade por MCP e CLI, mas persistir decisões em Markdown/traceability.
4. Validar cada adapter por testes de ausência e presença da feature.
5. Só promover adapter para execução direta depois de ADR ou Tech Spec específica.

## Contratos
### Contrato do core
- Entrada unificada: `sdd resolve-input "$ARGUMENTS"` define `--name`, slug e próxima etapa.
- Persistência canônica: `docs/<slug>/traceability-map.yaml` e artefatos por stage.
- Estados canônicos: `pending`, `draft`, `recorded`, `approved`, `optional` conforme artifact store.
- Validação: `sdd validate-artifact <tipo> <arquivo.md>`.
- Checkpoints: PRD, Tech Spec, Merge e Deploy quando aplicável; Refinement obrigatório apenas quando risco/escopo exigir.

### Contrato de adapter runtime
Todo adapter deve declarar:
- `id`: ASCII-safe e estável.
- `kind`: categoria operacional (`mcp-sdk`, `provider-tool-adapter`, `graph-orchestrator`, `workflow-engine` ou equivalente).
- `feature` ou `availability`: como detectar presença sem falhar no default.
- `role`: o que o adapter acrescenta.
- `fallback`: caminho provider-neutral quando ausente.
- `capabilities`: lista curta de capacidades observáveis.
- `diagnostics`: comando esperado (`providers doctor`, `capabilities doctor`, `mcp_runtime_adapters` ou específico).

### Contrato MCP
- MCP expõe artifacts, traces, context packs, clients doctor e runtime adapters.
- MCP não grava stage state nem aprova checkpoints.
- `sdd://runtime/adapters` é derivado de `runtime_adapters()`; se uma feature não estiver compilada, `enabled=false` deve ser suficiente para diagnóstico.

### Contrato provider-neutral
- Prompts e tasks devem funcionar sem MCP, sem tool calling, sem browser, sem subagents, sem visão e sem runtime específico.
- Capacidades avançadas entram como "se disponível"; a saída mínima é Markdown validável e persistido.
- Conteúdo humano em PT-BR preserva acentos; paths, slugs, features e IDs permanecem ASCII-safe.

## Dados
### Fontes canônicas
- `docs/<slug>/traceability-map.yaml`
- `docs/<slug>/<stage>.md`
- `.agents/skills/**/SKILL.md` e regras `.agents`
- `templates/capability-catalog.yaml`
- `sdd.config.yaml` e `sdd.config.example.yaml`

### Dados derivados
- `.sdd/events.jsonl`, `.sdd/subagents.jsonl`, `.sdd/task-gates.jsonl`, `.sdd/runs.jsonl`
- `.sdd/intelligence/**`
- Recursos MCP `sdd://artifact/*`, `sdd://trace/*`, `sdd://context/*`, `sdd://runtime/adapters`

### Compatibilidade e migração
- Slugs de artifact store devem ser path-safe e limitados para evitar erro de filesystem.
- Adapters futuros não devem exigir migração de artifact store.
- Metadata de adapters pode crescer de forma compatível adicionando campos opcionais; campos mínimos devem permanecer estáveis.

## Segurança
- Features opcionais não devem ativar rede ou execução remota por padrão.
- Provider credentials continuam resolvidas por `auth_env`, comandos de login/check e redaction; adapters não devem copiar tokens para artifact ou MCP.
- `runtime::redaction` deve continuar aplicado em traces e erros.
- MCP deve permanecer read-only para artifacts/context/traces nesta fatia.
- Entrada de runtime externo deve ser tratada como não confiável; qualquer execução direta futura precisa de ADR, allowlist e testes de redaction.

## Performance
- O caminho default deve continuar compilando sem `rmcp`, `rig-core` ou outros runtime SDKs.
- `runtime_adapters()` deve ser O(n) em lista pequena e sem IO.
- `clients doctor --strict` e `capabilities doctor --targets all` continuam sendo guards de CI/local, não operações por request.
- `context build` pode usar índices derivados, mas não deve bloquear execução se MCP ou CodeGraph não existirem.

## Observabilidade
- `sdd trace list|show|summary|doctor` continua a superfície CLI de observabilidade local.
- MCP expõe `sdd_trace_list`, `sdd_trace_show`, `sdd_trace_summary`, `sdd_artifact_status`, `sdd_context_build`, `sdd_clients_doctor` e `sdd_runtime_adapters`.
- Runtime adapters devem aparecer em `sdd_runtime_adapters` e `sdd://runtime/adapters`, com `enabled` e `fallback`.
- Eventos de decisão arquitetural devem virar ADR após execução quando a task alterar comportamento de runtime/provider.

## Testes
- Unitários para `runtime_adapters()` garantindo `default = []`, `enabled=false` sem feature e campos mínimos estáveis.
- Testes com feature para `mcp-rmcp` e `rig-adapter` quando disponíveis.
- Testes de CLI para `sdd mcp serve/config`, `sdd_runtime_adapters` e `sdd://runtime/adapters`.
- `cargo test`.
- `cargo check --features mcp-rmcp,rig-adapter`.
- `cargo run --quiet -- clients doctor --strict`.
- `cargo run --quiet -- capabilities doctor --targets all`.
- `cargo run --quiet -- validate-artifact techspec docs/<slug>/03-techspec.md`.

## Riscos
- **Acoplamento de runtime:** um adapter futuro pode capturar regras de stage. Mitigação: contrato de adapter + tests + ADR antes de execução direta.
- **Feature creep:** adicionar Flue/LangGraph/Agno como dependência antes de validar necessidade. Mitigação: começar por metadata e tasks separadas.
- **MCP como fonte de verdade:** clients podem tratar recursos MCP como estado canônico. Mitigação: docs e respostas MCP apontam para artifact store.
- **Divergência de surfaces:** client adapter pode driftar da `.agents`. Mitigação: `clients doctor --strict` e `capabilities doctor --targets all`.
- **Build default pesado:** SDKs opcionais podem vazar para default. Mitigação: `default = []` e checks sem features.

## Plano de implementação
1. **T-01 - Consolidar contrato runtime-agnostic**
   - Revisar `templates/capability-catalog.yaml`, `clients/README.md`, `.agents/skills/orchestration/SKILL.md` e surfaces geradas para declarar core/adapters/fallback.
   - Garantir que nenhum prompt exija Rig, Flue, LangGraph, Agno, MCP ou tool calling como requisito essencial.

2. **T-02 - Normalizar registry de runtime adapters**
   - Evoluir `RuntimeAdapterDefinition` se necessário com campos opcionais para `diagnostics`, `status_notes` e `docs`.
   - Manter `rmcp` e `rig` como adapters concretos atuais.
   - Adicionar Flue/LangGraph/Agno inicialmente como planned adapters somente se houver informação suficiente e fallback claro; não adicionar dependência obrigatória.

3. **T-03 - Fortalecer surfaces de observabilidade**
   - Cobrir `sdd_runtime_adapters` e `sdd://runtime/adapters` em testes.
   - Garantir que a resposta documente `enabled=false` sem falha.
   - Confirmar que MCP continua read-only para artifacts/context/traces.

4. **T-04 - Guardrails de compatibilidade**
   - Expandir testes de `capabilities doctor` e `clients doctor --strict` para detectar drift de runtime-adapter docs.
   - Validar `cargo test` e `cargo check --features mcp-rmcp,rig-adapter`.

5. **T-05 - ADR pós-execução**
   - Se a execução alterar contrato, registry ou behavior de runtime, criar/atualizar ADR registrando decisão, fallback e plano de reversão.

Refinement não é obrigatório pelo risco atual (`low`), mas deve ser usado se Tasks revelarem múltiplas dependências, mudança de schema pública ou adição real de SDK externo.

## Diagramas
**Pergunta respondida:** onde termina o core SDD e onde começam engines/adapters opcionais?
**Formato:** Mermaid versionado neste Markdown.
**Fonte:** PRD aprovado, CodeGraph, `src/runtime/mcp.rs`, `src/domain/providers.rs`, `templates/capability-catalog.yaml`, ADR de `rmcp`/Rig.
**Escopo:** arquitetura de contrato e observabilidade; não cobre API específica interna de Flue/LangGraph/Agno.
**Limitações:** Flue/LangGraph/Agno ficam como adapters planejáveis até validação específica em task.

```mermaid
flowchart TD
    Agents[".agents\nContrato canônico de skills e regras"] --> Core["Core SDD\nstages, checkpoints, schemas, artifact store"]
    Core --> Store["docs/<slug>/\ntraceability-map.yaml + artefatos"]
    Core --> Config["sdd.config.yaml\nprovider registry"]
    Core --> Catalog["capability-catalog v2\ncapabilities, adapters, fallbacks"]
    Core --> MCP["MCP/trace\nobservabilidade derivada"]

    Catalog --> Clients["Client surfaces geradas\nCodex, Claude, Cursor, opencode, Devin, Trae"]
    MCP --> RuntimeResource["sdd://runtime/adapters\nsdd_runtime_adapters"]

    subgraph Optional["Engines/adapters opcionais"]
      RMCP["rmcp\nmcp-rmcp"]
      Rig["Rig\nrig-adapter"]
      Flue["Flue\nplanned adapter"]
      LangGraph["LangGraph\nplanned adapter"]
      Agno["Agno\nplanned adapter"]
    end

    Optional --> RuntimeResource
    Optional --> Core
    Clients --> Core
    MCP -. "derivado de" .-> Store
```

**Leitura:** adapters podem executar, rotear ou enriquecer capabilities, mas retornam ao core para contrato SDLC. Observabilidade MCP é derivada; o artifact store continua canônico.
