# ADR - Core SDD runtime-agnostic e runtime adapters opcionais

## Rastreabilidade
- Orquestração: `a-jogada-mais-limpa-sdd-continua-runtime-agnostic-o-core-segue-dono-do-contrato-sdl-8ee3bafff01a`
- Stage: `adr`
- Origem principal: `06-execution.md`
- Artefatos relacionados: `02-prd.md`, `03-techspec.md`, `04-tasks.md`
- Decisões relacionadas: ADR `Runtime adapters rmcp e Rig`

## Status
- Estado: Aceito
- Data da decisão: 2026-06-17
- Dono técnico: mantenedor do `sdd-layer`
- Escopo: contrato SDLC canônico, client surfaces, runtime engines/adapters e observabilidade MCP/trace.

## Contexto
O `sdd-layer` já seguia uma direção portátil: `.agents` como contrato canônico, artifact store local em `docs/<slug>/`, traceability map por orquestração, CLI determinístico e MCP/trace como leitura/observabilidade. A evolução com Rig, `rmcp` e futuros runtimes como Flue, LangGraph e Agno trouxe a necessidade de explicitar a fronteira entre contrato SDD e engines/adapters.

## Problema
Se um runtime externo for tratado como dono do fluxo, o SDD passa a depender de SDK, tool calling, MCP, subagents ou provider específico para executar etapas essenciais. Isso quebraria a portabilidade entre clients e confundiria fonte de verdade, observabilidade e execução.

## Decisão
Manter o core SDD como dono do contrato SDLC:

- etapas, checkpoints, artifact store, validação, rastreabilidade, provider registry e comportamento determinístico do CLI pertencem ao core SDD;
- `.agents` continua sendo contrato canônico de skills e regras portáveis;
- `docs/<slug>/traceability-map.yaml` continua sendo a fonte local de verdade do estado da orquestração;
- MCP e trace continuam sendo observabilidade derivada/read-only;
- Rig, Flue, LangGraph, Agno e runtimes futuros são engines/adapters opcionais para execução, roteamento, tools ou composição;
- quando um runtime adapter estiver ausente, o fluxo deve continuar com Markdown, comandos `sdd`, artifact store local e validações determinísticas.

## Alternativas consideradas
- **Promover Rig ou outro runtime a harness principal:** rejeitado porque acopla o contrato SDD a uma runtime específica.
- **Tratar MCP como fonte de verdade:** rejeitado porque MCP deve consultar e apresentar estado, não aprovar checkpoints nem gravar artefatos canônicos.
- **Manter a decisão apenas implícita em PRD/Tech Spec:** rejeitado porque client surfaces e plugin mirrors precisam carregar a regra de fallback.
- **Criar adapters somente via documentação, sem checks:** rejeitado porque drift entre generator, clients e capabilities ficaria invisível.

## Consequências
- O fluxo essencial continua operando offline/localmente.
- Client adapters podem ser gerados sem assumir tool calling, browser, MCP ou runtime específico.
- Runtimes externos podem evoluir como plugins/adapters sem substituir `.agents`.
- Doctors e testes passam a ser a evidência de que as superfícies seguem o contrato.
- Futuras integrações precisam declarar fallback explícito e não podem mover aprovação de checkpoint para MCP/trace.

## Impactos e riscos
- Impacto positivo: reduz acoplamento entre core SDD, providers, clients e runtimes.
- Impacto positivo: preserva a direção de capabilities portáveis e client adapters gerados.
- Risco residual: próximas fatias ainda precisam fortalecer registry e observabilidade MCP de runtime adapters.
- Risco residual: a repetição do contrato em várias superfícies exige checks de drift contínuos.

## Plano de adoção
1. Manter a linguagem runtime-agnostic em `templates/client-skills/orchestration.md`, skills por client, commands/workflows e docs de clients.
2. Usar `sdd clients doctor --strict` e `sdd capabilities doctor --targets all` antes de release.
3. Ao adicionar runtime novo, registrar como adapter opcional com fallback local/CLI.
4. Ao tocar MCP/trace, validar que a superfície permanece read-only e derivada.

## Plano de reversão
- Remover a seção runtime-agnostic das superfícies e templates caso o projeto decida eleger um runtime específico como harness principal.
- Reverter os patches em `src/main.rs` relacionados aos templates gerados.
- Manter `docs/<slug>/` e `traceability-map.yaml` intactos; a reversão de linguagem não exige migração de artifact store.

## Evidências
- `rtk cargo test`: `402 passed`.
- `rtk cargo run --quiet -- clients doctor --strict`: `SDD clients doctor PASS` e `SDD capabilities doctor PASS`.
- `rtk cargo run --quiet -- capabilities doctor --targets all`: `SDD capabilities doctor PASS`.
- `rtk cargo run --quiet -- validate-artifact execution docs/a-jogada-mais-limpa-sdd-continua-runtime-agnostic-o-core-segue-dono-do-contrato-sdl-8ee3bafff01a/06-execution.md`: artefato válido.
- `rtk git diff --check`: sem saída.

## Histórico de revisão
- 2026-06-17: ADR registrado após execução de T-01 e validação local.
