# Tasks - 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: tasks
- Estado atual: recorded
- Artefato anterior: `03-techspec.md` aprovado
- Origem de produto: `02-prd.md` aprovado
- Context Pack: `sdd context build --name "a-jogada-mais-limpa-sdd-continua-runtime-agnostic-o-core-segue-dono-do-contrato-sdl-8ee3bafff01a" --stage tasks`
- Decisões relacionadas: ADR `Runtime adapters rmcp e Rig`, ADR `Project Intelligence Layer determinística`

## Backlog
| ID | Título | Objetivo verificável | Arquivos prováveis | Estado |
|---|---|---|---|---|
| T-01 | Consolidar contrato runtime-agnostic nas superfícies canônicas | Documentação e skills declaram que core SDD governa o SDLC e runtimes são adapters opcionais com fallback | `templates/capability-catalog.yaml`, `clients/README.md`, `.agents/skills/orchestration/SKILL.md`, `.claude/skills/orchestration/SKILL.md`, `.cursor/skills/orchestration/SKILL.md`, surfaces geradas | ready |
| T-02 | Normalizar registry de runtime adapters | `RuntimeAdapterDefinition` cobre campos mínimos de diagnóstico sem quebrar default build | `src/runtime/mcp.rs`, `src/main.rs`, `tests/cli.rs`, `Cargo.toml` | ready |
| T-03 | Fortalecer observabilidade MCP de adapters | `sdd_runtime_adapters` e `sdd://runtime/adapters` têm testes de tool/resource e mantêm MCP read-only | `src/runtime/mcp.rs`, `src/main.rs`, `tests/cli.rs` | ready |
| T-04 | Expandir guardrails de compatibilidade | `clients doctor --strict` e `capabilities doctor --targets all` detectam drift de docs/adapters/fallbacks | `templates/capability-catalog.yaml`, `src/main.rs`, `tests/cli.rs`, client surfaces | ready |
| T-05 | Registrar ADR pós-execução quando houver mudança de contrato | Decisão técnica da execução fica rastreável em `06-adr.md` se contrato/registry/comportamento mudar | `docs/<slug>/06-execution.md`, `docs/<slug>/06-adr.md`, `traceability-map.yaml` | conditional |

## Dependências
```mermaid
flowchart TD
    T01["T-01 contrato nas superfícies"] --> T02["T-02 registry runtime adapters"]
    T02 --> T03["T-03 observabilidade MCP"]
    T01 --> T04["T-04 guardrails de compatibilidade"]
    T03 --> T04
    T04 --> T05{"T-05 ADR se houver decisão nova"}
```

- T-01 deve vir primeiro para travar linguagem de domínio e fallback.
- T-02 e T-03 podem ser executadas em sequência curta; T-03 depende do contrato de registry.
- T-04 fecha a fatia com validações de drift.
- T-05 só é executada após evidência de Execution se houver alteração arquitetural ou contrato público novo.

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

  Cenário: Superfícies canônicas declaram adapters opcionais
    Dado que `.agents` é a fonte canônica de skills e regras
    Quando as superfícies de client são revisadas
    Então nenhuma delas deve exigir Rig, Flue, LangGraph, Agno, MCP ou tool calling para o comportamento essencial
    E cada capability opcional deve mencionar fallback local ou CLI

  Cenário: Registry de runtime adapters funciona sem features
    Dado que o binário é compilado com `default = []`
    Quando `runtime_adapters()` é consultado
    Então adapters opcionais devem aparecer com `enabled=false`
    E o caminho default não deve falhar nem ativar rede

  Cenário: MCP expõe adapters como observabilidade derivada
    Dado que o servidor MCP SDD está disponível
    Quando um client chama `sdd_runtime_adapters` ou lê `sdd://runtime/adapters`
    Então a resposta deve listar adapters, capabilities e fallback
    E não deve gravar artifact, alterar stage state ou aprovar checkpoint

  Cenário: Guardrails detectam drift
    Dado que capability catalog e client surfaces foram alterados
    Quando `sdd clients doctor --strict` e `sdd capabilities doctor --targets all` são executados
    Então ambos devem passar
    E falhas devem apontar qual surface, capability ou fallback divergiu
```

Regras EARS:
- O sistema DEVE manter `docs/<slug>/traceability-map.yaml` como fonte canônica de estado.
- O sistema DEVE tratar MCP, `.sdd/intelligence` e traces como dados derivados.
- QUANDO um runtime externo for indisponível, o sistema DEVE continuar operando com Markdown, CLI e artifact store local.
- ENQUANTO uma feature opcional não estiver compilada, o adapter DEVE permanecer descobrível com `enabled=false` e fallback claro.

## Definition of Done
- Artefatos e docs preservam acentos em PT-BR e usam ASCII apenas para paths, slugs, features e IDs.
- Nenhuma task torna Rig, Flue, LangGraph, Agno, MCP, browser, subagents ou tool calling obrigatórios.
- `cargo test` passa.
- `cargo check --features mcp-rmcp,rig-adapter` passa quando a task tocar features opcionais.
- `cargo run --quiet -- clients doctor --strict` passa.
- `cargo run --quiet -- capabilities doctor --targets all` passa.
- `sdd validate-artifact tasks docs/a-jogada-mais-limpa-sdd-continua-runtime-agnostic-o-core-segue-dono-do-contrato-sdl-8ee3bafff01a/04-tasks.md` passa.
- Execution registra evidências e, se houver decisão arquitetural nova, ADR é criada ou atualizada.

## Estratégia de testes
- Testes unitários para contrato de `RuntimeAdapterDefinition` e `runtime_adapters()`.
- Testes de CLI/MCP para tool `sdd_runtime_adapters` e resource `sdd://runtime/adapters`.
- Testes de catálogo para garantir que capabilities possuem adapter/fallback/validation.
- Testes de doctor para `clients doctor --strict` e `capabilities doctor --targets all`.
- Testes de build default e build com features opcionais quando houver alteração em `Cargo.toml` ou registry.
- Validação manual curta de artefatos: `validate-artifact`, `resolve-input` e leitura do `traceability-map.yaml`.

## Ordem sugerida
1. T-01 - Consolidar contrato runtime-agnostic nas superfícies canônicas.
2. T-02 - Normalizar registry de runtime adapters.
3. T-03 - Fortalecer observabilidade MCP de adapters.
4. T-04 - Expandir guardrails de compatibilidade.
5. T-05 - Registrar ADR pós-execução quando houver mudança de contrato.

Refinement fica dispensado por ora porque a classificação de risco é `low`, as tasks têm dependência linear e não há migração de dados, UI, flags, remote config ou ativação obrigatória de SDK externo. Se T-02 decidir adicionar dependência nova real para Flue/LangGraph/Agno, Refinement deve ser retomado antes da execução dessa fatia.

## Prompts Agent
**Prompt T-01 - Consolidar contrato runtime-agnostic nas superfícies canônicas**
Você é um agente de código executando uma task SDD isolada.

Origem: PRD `docs/a-jogada-mais-limpa-sdd-continua-runtime-agnostic-o-core-segue-dono-do-contrato-sdl-8ee3bafff01a/02-prd.md`, Tech Spec `docs/a-jogada-mais-limpa-sdd-continua-runtime-agnostic-o-core-segue-dono-do-contrato-sdl-8ee3bafff01a/03-techspec.md`, Tasks `docs/a-jogada-mais-limpa-sdd-continua-runtime-agnostic-o-core-segue-dono-do-contrato-sdl-8ee3bafff01a/04-tasks.md`.

Objetivo verificável: atualizar as superfícies canônicas para declarar que o core SDD governa o contrato SDLC e que Rig, Flue, LangGraph, Agno e runtimes futuros são adapters opcionais com fallback.

Escopo: revisar e ajustar `templates/capability-catalog.yaml`, `clients/README.md`, `.agents/skills/orchestration/SKILL.md` e surfaces geradas relevantes. Fora de escopo: alterar execução direta de runtimes, adicionar SDKs novos, mudar stages ou checkpoints.

Contexto mínimo: `.agents` é a fonte canônica; client surfaces são geradas/sincronizadas; MCP/trace são observabilidade derivada; conteúdo humano em PT-BR preserva acentos; paths, slugs, features e IDs devem ser ASCII-safe.

Passos sugeridos: inspecione os arquivos prováveis, localize menções a runtime/provider/client, ajuste linguagem para provider-neutral, garanta fallback para capability opcional, rode validações.

Validação: descubra comandos reais no repo se necessário; execute `cargo test` quando tocar código gerador, `cargo run --quiet -- clients doctor --strict`, `cargo run --quiet -- capabilities doctor --targets all` e `git diff --check`.

Definition of Done: docs e skills não exigem runtime específico; fallbacks estão claros; validações passam; relatório final inclui arquivos alterados, comandos executados, evidências e riscos pendentes.

**Prompt T-02 - Normalizar registry de runtime adapters**
Você é um agente de código executando uma task SDD isolada.

Origem: PRD `docs/a-jogada-mais-limpa-sdd-continua-runtime-agnostic-o-core-segue-dono-do-contrato-sdl-8ee3bafff01a/02-prd.md`, Tech Spec `docs/a-jogada-mais-limpa-sdd-continua-runtime-agnostic-o-core-segue-dono-do-contrato-sdl-8ee3bafff01a/03-techspec.md`, Tasks `docs/a-jogada-mais-limpa-sdd-continua-runtime-agnostic-o-core-segue-dono-do-contrato-sdl-8ee3bafff01a/04-tasks.md`.

Objetivo verificável: garantir que `RuntimeAdapterDefinition` e `runtime_adapters()` tenham campos mínimos estáveis para diagnóstico e fallback sem quebrar o build default.

Escopo: `src/runtime/mcp.rs`, call sites em `src/main.rs`, testes em `tests/cli.rs` ou unitários próximos. Fora de escopo: implementar execução direta via Flue/LangGraph/Agno, substituir transporte MCP ou ativar rede.

Contexto mínimo: `rmcp` e `rig-core` já são opcionais por features; `default = []` deve continuar leve; adapters indisponíveis devem aparecer como `enabled=false` com fallback.

Passos sugeridos: inspecione `runtime_adapters()`, avalie se campos opcionais como diagnostics/docs/status_notes são necessários, implemente de forma compatível, atualize testes e fixtures.

Validação: `cargo test`, `cargo check --features mcp-rmcp,rig-adapter`, e checks focados de MCP se existirem. Se o harness não permitir executar comandos, registre comandos e resultado esperado.

Definition of Done: registry continua determinístico, default build não exige feature, adapters têm fallback claro, testes cobrem ausência/presença quando aplicável.

**Prompt T-03 - Fortalecer observabilidade MCP de adapters**
Você é um agente de código executando uma task SDD isolada.

Origem: PRD `docs/a-jogada-mais-limpa-sdd-continua-runtime-agnostic-o-core-segue-dono-do-contrato-sdl-8ee3bafff01a/02-prd.md`, Tech Spec `docs/a-jogada-mais-limpa-sdd-continua-runtime-agnostic-o-core-segue-dono-do-contrato-sdl-8ee3bafff01a/03-techspec.md`, Tasks `docs/a-jogada-mais-limpa-sdd-continua-runtime-agnostic-o-core-segue-dono-do-contrato-sdl-8ee3bafff01a/04-tasks.md`.

Objetivo verificável: cobrir a tool MCP `sdd_runtime_adapters` e o resource `sdd://runtime/adapters` com testes e garantir que permanecem read-only.

Escopo: `src/main.rs`, `src/runtime/mcp.rs`, testes CLI/MCP. Fora de escopo: adicionar write tools MCP, aprovar checkpoints via MCP ou mover fonte canônica para MCP.

Contexto mínimo: MCP é observabilidade derivada; fonte canônica fica em `docs/<slug>/` e `.sdd/*.jsonl`; respostas devem listar adapters, capabilities, `enabled` e fallback.

Passos sugeridos: localize testes MCP existentes, adicione cobertura para tool/resource, verifique que nenhuma chamada altera `traceability-map.yaml`, rode testes.

Validação: `cargo test`, teste focado MCP se existir, `cargo run --quiet -- clients doctor --strict`, `cargo run --quiet -- capabilities doctor --targets all`.

Definition of Done: tool/resource retornam metadata de adapters, não alteram estado, testes passam e relatório final cita evidência de read-only.

**Prompt T-04 - Expandir guardrails de compatibilidade**
Você é um agente de código executando uma task SDD isolada.

Origem: PRD `docs/a-jogada-mais-limpa-sdd-continua-runtime-agnostic-o-core-segue-dono-do-contrato-sdl-8ee3bafff01a/02-prd.md`, Tech Spec `docs/a-jogada-mais-limpa-sdd-continua-runtime-agnostic-o-core-segue-dono-do-contrato-sdl-8ee3bafff01a/03-techspec.md`, Tasks `docs/a-jogada-mais-limpa-sdd-continua-runtime-agnostic-o-core-segue-dono-do-contrato-sdl-8ee3bafff01a/04-tasks.md`.

Objetivo verificável: ampliar validações para detectar drift entre capability catalog, client surfaces e runtime-adapter docs/fallbacks.

Escopo: `templates/capability-catalog.yaml`, `src/main.rs`, `tests/cli.rs`, client surfaces afetadas. Fora de escopo: refatorar todo o gerador de clients ou mudar contrato de stages.

Contexto mínimo: `clients doctor --strict` valida distribuição; `capabilities doctor --targets all` valida paridade semântica; fallbacks são obrigatórios para capabilities opcionais.

Passos sugeridos: identifique validações existentes de capability catalog e clients doctor, adicione caso de teste que falhe quando fallback/adapters estiverem ausentes, atualize docs/surfaces mínimas.

Validação: `cargo test`, `cargo run --quiet -- clients doctor --strict`, `cargo run --quiet -- capabilities doctor --targets all`, `git diff --check`.

Definition of Done: drift de runtime adapters fica detectável por testes/doctor; comandos passam; relatório final aponta limitações residuais.

**Prompt T-05 - Registrar ADR pós-execução quando houver mudança de contrato**
Você é um agente de código executando uma task SDD isolada de registro arquitetural, executada somente se a implementação alterar contrato, registry, features opcionais ou comportamento MCP/provider.

Origem: `06-execution.md` da mesma orquestração, PRD `02-prd.md`, Tech Spec `03-techspec.md`, Tasks `04-tasks.md` e evidências de testes.

Objetivo verificável: criar ou atualizar `docs/a-jogada-mais-limpa-sdd-continua-runtime-agnostic-o-core-segue-dono-do-contrato-sdl-8ee3bafff01a/06-adr.md` com decisão, alternativas, consequências, riscos, adoção, reversão e evidências.

Escopo: artifact ADR e traceability map via `sdd artifact save`. Fora de escopo: implementar código novo.

Contexto mínimo: ADR é obrigatória após Execution quando decisão técnica ou arquitetural foi criada, confirmada ou alterada; use `recorded`, não `approved`, salvo instrução humana explícita.

Passos sugeridos: leia `06-execution.md`, compare com Tech Spec, registre decisão real e comandos executados, valide artifact.

Validação: `cargo run --quiet -- validate-artifact adr docs/a-jogada-mais-limpa-sdd-continua-runtime-agnostic-o-core-segue-dono-do-contrato-sdl-8ee3bafff01a/06-adr.md` e `sdd artifact save "<name>" adr --file <arquivo> --state recorded`.

Definition of Done: ADR existe quando necessária, aponta para Execution e evidências, e o mapa de rastreabilidade foi atualizado.
