# PRD - 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: prd
- Estado atual: approved
- Artefato anterior: `01-idea.md`
- Artefatos de base: `00-project-discovery.md`, `00-risk-classification.md`
- 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`

## Resumo
O SDD deve preservar uma fronteira clara entre contrato SDLC e engines de execução. O contrato vive no core: skills Markdown, comandos CLI, artifact store, schemas, traceability, checkpoints, provider registry, capability catalog e observabilidade local. Engines como Rig, Flue, LangGraph e Agno entram como adapters opcionais para roteamento, execução, tools ou composição, sem tomar posse das regras de negócio do pipeline.

Essa abordagem mantém a camada compatível com qualquer provider/modelo e qualquer client/harness. Quando um runtime estiver disponível, ele pode enriquecer execução e integração. Quando não estiver, o fluxo continua operante por Markdown, CLI, arquivos locais e validações determinísticas.

## Objetivos
- Declarar explicitamente que o `sdd-layer` é runtime-agnostic.
- Definir que o core SDD é dono do contrato SDLC e das regras de rastreabilidade.
- Padronizar Rig, Flue, LangGraph, Agno e runtimes futuros como engines/adapters opcionais.
- Garantir que adapters sejam descobertos por capability catalog e expostos por MCP/trace quando disponível.
- Preservar `.agents` como contrato canônico e clients específicos como superfícies geradas.
- Exigir fallback provider-neutral para qualquer capability opcional.

## Não objetivos
- Reescrever o core em Rig, Flue, LangGraph, Agno ou qualquer runtime externo.
- Tornar MCP obrigatório para execução do fluxo.
- Mover estado canônico de `docs/<slug>/`, `traceability-map.yaml` ou `.sdd/*.jsonl` para runtime externo.
- Exigir tool calling, browser, subagents, visão ou contexto longo para que uma etapa SDD funcione.
- Implementar todos os adapters nesta etapa de planejamento.

## Usuários
- Mantenedor do `sdd-layer`.
- Autores de skills e comandos SDD.
- Implementadores de adapters runtime.
- Clients consumidores do contrato SDD: Codex, Claude Code, Cursor, opencode, Devin, Trae, Antigravity e futuros harnesses.
- Projetos instalados que precisam de execução offline, local ou com capacidades limitadas.

## Requisitos
- O core DEVE continuar responsável por estágios, transições, checkpoints, artifact store, validação de artefatos, provider registry, traceability map e comandos `sdd`.
- `.agents` DEVE permanecer a fonte canônica para skills, regras e contrato portável.
- Superfícies `.codex`, `.claude`, `.cursor`, `.opencode`, `.devin`, `.trae` e equivalentes DEVEM ser tratadas como adapters/client surfaces gerados ou sincronizados.
- Rig, Flue, LangGraph, Agno e runtimes similares DEVEM ser modelados como engines/adapters opcionais com capability declarada.
- Cada adapter DEVE declarar capacidades, fallback, limites, comandos de diagnóstico e evidência persistida.
- MCP/trace DEVE ser observabilidade e integração derivada; não pode substituir o artifact store local como fonte de verdade.
- O fluxo DEVE funcionar em modo mínimo com Markdown, texto estruturado, CLI `sdd` quando disponível e persistência local.
- Prompts agent e tasks futuras NÃO DEVEM exigir provider, model, MCP, browser, subagent ou runtime específico como requisito essencial.
- Artefatos humanos em PT-BR DEVEM preservar UTF-8, acentos e diacríticos; slugs, paths e identificadores técnicos DEVEM permanecer ASCII-safe.

## Critérios de aceite
```gherkin
Funcionalidade: Manter o SDD runtime-agnostic

  Cenário: Core permanece dono do contrato SDLC
    Dado que uma etapa SDD precisa consultar regras de estágio, schemas, checkpoints e traceability
    Quando um adapter runtime estiver configurado
    Então o adapter deve delegar essas regras ao core SDD
    E não deve definir estados canônicos próprios para substituir `traceability-map.yaml`

  Cenário: Adapter opcional indisponível
    Dado que Rig, Flue, LangGraph ou Agno não estão instalados no ambiente
    Quando o usuário executa uma orquestração SDD
    Então o fluxo deve continuar operante pelo CLI, Markdown e artifact store local
    E a ausência do adapter deve aparecer como fallback documentado, não como erro fatal

  Cenário: Client surface é gerada a partir do contrato canônico
    Dado que `.agents` contém a skill ou regra canônica
    Quando uma superfície de client é sincronizada
    Então `.codex`, `.claude`, `.cursor`, `.opencode`, `.devin`, `.trae` ou equivalente devem refletir o contrato comum
    E não devem introduzir requisito exclusivo de provider para o comportamento essencial

  Cenário: Observabilidade não vira fonte de verdade
    Dado que MCP expõe traces, artifacts, context packs ou adapters runtime
    Quando um agente consulta esses recursos
    Então a resposta deve apontar para `docs/<slug>/`, `traceability-map.yaml` ou `.sdd/*.jsonl` como fonte canônica
    E MCP deve permanecer uma superfície derivada de leitura ou integração
```

## Métricas
- `sdd capabilities doctor --targets all` passa sem drift de capability.
- `sdd clients doctor --strict` passa após sincronização de client surfaces.
- `sdd providers doctor` não exige runtime específico para validar configuração mínima.
- Novos adapters possuem capability, fallback e comandos de diagnóstico documentados.
- Testes de CLI cobrem ausência de adapter opcional e preservação do caminho local determinístico.

## Riscos
- Um adapter capturar regras de etapa e criar um segundo contrato concorrente.
- Dependências opcionais vazarem para o build padrão e quebrarem modo offline.
- MCP ser tratado por clients como estado canônico, criando divergência com `docs/<slug>/`.
- Prompts agent mencionarem runtimes específicos como obrigação, reduzindo compatibilidade.
- O nome "engine" sugerir posse do fluxo; documentação precisa reforçar que engines executam, mas o core governa.

## Compatibilidade de provider
- Provider/modelo exigido: nenhum.
- Capacidades opcionais usadas: MCP, runtime adapters, tool calling e subagents somente quando disponíveis.
- Fallback quando ausente: CLI `sdd`, Markdown, artifact store local e comandos de validação.
- Evidência persistida: artefatos em `docs/a-jogada-mais-limpa-sdd-continua-runtime-agnostic-o-core-segue-dono-do-contrato-sdl-8ee3bafff01a/` e traceability map local.
- Risco residual: adapters futuros podem introduzir acoplamento se não forem validados por capability doctor e revisão de provider compatibility.

## Diagramas
```mermaid
flowchart TD
    core["Core SDD\nContrato SDLC, stages, schemas, checkpoints"]
    agents[".agents\nSkills e regras canônicas"]
    store["Artifact store local\ndocs/<slug>/ + traceability-map.yaml"]
    trace["Trace/MCP\nObservabilidade derivada"]
    clients["Client surfaces geradas\nCodex, Claude, Cursor, opencode, Devin, Trae"]
    adapters["Engines/adapters opcionais\nRig, Flue, LangGraph, Agno"]
    providers["Providers/modelos\nOpenAI-compatible, Anthropic, Google, local, offline"]

    agents --> core
    core --> store
    core --> trace
    core --> clients
    adapters --> core
    adapters --> providers
    clients --> core
    trace --> store
```

Leitura do diagrama: adapters podem enriquecer execução e roteamento, mas sempre atravessam o core SDD. O artifact store e os traces locais seguem como base auditável; MCP apenas expõe ou integra essa base.
