# Implementações recentes
> Atualizado em 2026-07-18 (janela de consolidação `0.20.x`).
## Atualização documental e operacional até 0.20.x
- Documento principal de mudanças em `CHANGELOG.md` agora concentra o bloco mais recente com resumo das novas skills de execução, design-extraction e reforços de qualidade/geração para a trilha `0.20.x`.
- `docs-site/content/docs/resources/cli.md` e artefatos de release já apontam para o gate único `sdd ci --strict-release`, com orientação de `--name <slug>` e preparação de MCP local para validação de clientes em CI.
- As orientações de release de documentação (`docs-site/content/docs/operacao/release-docs.mdx`) foram mantidas como checklist operacional complementar para publicação segura de conteúdo.
## Release readiness, bot GitHub e supply chain
Este ciclo adiciona a camada de release/readiness que faltava para publicar o `sdd-layer` com evidência única:
- `sdd ci --strict-release` executa fmt, clippy all-targets/all-features, testes Rust locked/all-features, `sdd health --strict`, workflow validate, clients/capabilities/skills doctors, bot build/test, docs generate/links/build e advisory checks.
- `sdd ci --strict-release --json --dry-run` expõe a matriz de comandos sem executar checks caros.
- `sdd maintenance report` gera leitura rápida por área (`core-rust`, `docs`, `clients`, `bot`, `providers`, `intelligence`, `workflows`, `release`, `diagrams`, `advisory`) sem fingir que builds caros foram executados; áreas apenas detectadas aparecem como `skipped`.
- `.github/workflows/sdd-layer.yml` instala dependências de bot/docs, gera configs MCP locais ignoradas pelo Git e roda o gate release a partir do binário release.
- O bot ganhou provider GitHub para Issues/Projects/PRs, receiver de webhook com assinatura HMAC e migração de storage para provider de card.
- Jira/GitHub no bot usam helper HTTP comum com timeout, retry seguro para leituras, classificação de status e redaction de tokens.
- O advisory `npm audit` do bot foi limpo removendo dependências locais não usadas (`diff`, `@types/diff`, `pm2`) e atualizando transitive seguro via `npm audit fix`; PM2 continua ferramenta global de operação, não dependência runtime local.
Comandos de evidência recomendados:
```bash
cargo build --release
target/release/sdd mcp config --targets all --force
target/release/sdd ci --strict-release --name melhorias-modularizar-src-main-rs-por-dominio-commands-clients-commands-workflow-co-3557c07ccfa4
cd bot && npm audit --audit-level=high
cd docs-site && npm run docs:generate -- --check && npm run docs:links && npm run build
cargo publish --dry-run
```
## Rastreabilidade
- Origem: revisão do commit local `feat: add SDD diagram companions and client surfaces`.
- Escopo revisado: `sdd diagram`, `sdd acp`, MCP read-only, agente `sdd-orchestrator`, client surfaces, skill `diagram-design`, validações de artefato e avaliação.
- Fonte canônica: CLI `sdd`, artifact store `docs/<slug>/`, `traceability-map.yaml`, eventos `.sdd/*.jsonl` e checkpoints humanos.
## Visão geral
Este pacote amplia o SDD Layer em três direções:
1. **Companions visuais para artefatos SDD**: PRD e Tech Spec passam a exigir `## Diagramas`; Mermaid/Excalidraw continuam sendo o contrato versionável, e HTML/SVG gerado por `diagram-design` entra como companion derivado em `docs/<slug>/assets/diagrams/`.
2. **Superfícies agentic por cliente**: Codex/Antigravity, Claude Code, Cursor, Devin, opencode e Trae recebem comandos, agents, workflows ou skills para iniciar o loop `agentic-sdd-loop`, anexar diagramas e preservar o contrato portável.
3. **Observabilidade e agentes via MCP/ACP**: MCP expõe tools, prompts e resources read-only para artifacts, traces, capabilities, handoffs e manifesto do agente; ACP expõe o agente `sdd-orchestrator` como sessão de editor sem substituir o artifact store.
## Comandos novos ou reforçados
```bash
sdd workflow run agentic-sdd-loop --input "<demanda>" --max-iterations 3 --json
sdd diagram doctor --name "<ciclo>"
sdd acp doctor --root . --json
sdd acp config --targets zed --dry-run
sdd mcp serve --root .
sdd clients doctor --strict
sdd capabilities doctor --targets all
sdd eval stage --name "<ciclo>" --stage prd --json
sdd quality report --name "<ciclo>" --json
```
## Diagramas e companions
`sdd diagram attach` copia um arquivo `.html`, `.svg` ou `.excalidraw` para `docs/<slug>/assets/diagrams/` e injeta um bloco gerenciado na seção `## Diagramas` do artefato de `idea`, `prd` ou `techspec`.
Contrato operacional:
- `diagram-design` gera apenas companions editoriais HTML/SVG.
- Mermaid/Excalidraw permanece no Markdown como contrato versionável quando aplicável.
- PRD e Tech Spec precisam ter `## Diagramas` com Mermaid, `.excalidraw`, companion `assets/diagrams/*.html|*.svg` ou `Não aplicável` com justificativa curta.
- IDEA pode usar `## Diagramas` quando o visual melhorar entendimento, mas a seção não é obrigatória no schema.
- `sdd diagram doctor` verifica artifact store, skill `diagram-design`, assets e style guide.
## Agentic SDD Loop
`agentic-sdd-loop` é o recipe durável de entrada para agents. Ele resolve a demanda, roda planejamento até o primeiro gate, registra estado em `.sdd/workflows/*.json` e deixa execução, review e memory como etapas supervisionadas.
Superfícies gerenciadas:
- `.agents/agents/sdd-orchestrator/AGENT.md`
- `.codex/commands/agentic-sdd-loop.md`
- `.claude/commands/agentic-sdd-loop.md`
- `.devin/skills/agentic-sdd-loop/SKILL.md`
- `.opencode/commands/agentic-sdd-loop.md`
- `.trae/commands/agentic-sdd-loop.md`
- `templates/workflows/agentic-sdd-loop.yaml`
Regra de segurança: o loop não aprova checkpoints humanos automaticamente e não troca o artifact store por estado de chat.
## MCP read-only
O backend MCP agora expõe:
- tools: `sdd_trace_list`, `sdd_trace_show`, `sdd_trace_summary`, `sdd_artifact_status`, `sdd_context_build`, `sdd_context_bundle`, `sdd_clients_doctor`, `sdd_project_status`, `sdd_search`, `sdd_runtime_adapters`, `sdd_optimize_status`, `sdd_context_handoff`, `sdd_readiness_summary`, `sdd_capabilities_status`, `sdd_agents_manifest`;
- resources: `sdd://artifact/{orchestration}/{artifact}`, `sdd://trace/{run_id}`, `sdd://context/{orchestration}/{stage}`, `sdd://context-bundle/{orchestration}/{stage}`, `sdd://handoff/{orchestration}/{stage}`, `sdd://optimization/status`, `sdd://capabilities/catalog`, `sdd://agents/{agent_id}`, `sdd://runtime/adapters`, `sdd://auto/status`, `sdd://workflow/{id}/status`, `sdd://quality/{slug}`;
- prompts: `sdd_orchestration`, `sdd_stage_handoff`, `sdd_trace_review`.
Todas as tools MCP são read-only e derivadas de fontes locais. O contrato `2025-11-25` adiciona lifecycle, schemas de entrada/saída, `structuredContent`, paginação e perfis `compact`/`standard`/`full`. `sdd_context_bundle` é a leitura principal; `sdd_readiness_summary` entrega apenas o cockpit resumido e links para detalhes. MCP não aprova checkpoints, não grava artefatos e não substitui `traceability-map.yaml`.
## ACP
`sdd acp serve --root .` expõe uma superfície Agent Client Protocol v1 para o agente `sdd-orchestrator`.
Contrato operacional:
- sessões ACP ficam em `.sdd/acp/sessions/<session_id>/meta.json` e `events.jsonl`;
- `mcpServers` e prompts persistidos passam por redaction antes de gravação;
- cada sessão nova recebe ID único mesmo quando várias sessões são criadas rapidamente no mesmo processo;
- o turno ACP transmite plano, mensagem, uso e tool calls, com permissão explícita antes de mutações;
- ACP é cache de sessão, não fonte canônica de requisito, aprovação ou memória.
## Achados da revisão
**Veredito:** aprovado com correções aplicadas.
- Correção aplicada: `src/domain/evaluation.rs` aceitava apenas Mermaid, `.excalidraw` ou `Não aplicável`, enquanto `validate-artifact` e a documentação já aceitavam companion `assets/diagrams/*.html|*.svg`. O contrato foi alinhado e coberto por teste de `eval stage`.
- Correção aplicada: `src/runtime/acp.rs` gerava `sessionId` com timestamp em segundos, PID e cwd; duas sessões criadas rapidamente no mesmo processo poderiam colidir. O seed agora inclui contador monotônico e teste dedicado.
## Evidências recomendadas
```bash
cargo fmt --check
cargo test -q
cargo test -q --features mcp-rmcp
cargo test -q --features acp-agent
cargo run -q -- diagram doctor --name "<ciclo>"
cargo run -q -- acp doctor --root . --json
cargo run -q -- mcp serve --root .
```
## Limitações conhecidas
- `diagram-design` é companion editorial; não deve ser tratado como contrato único de arquitetura ou produto.
- ACP v1 expõe apenas o agente principal `sdd-orchestrator`; subagents seguem como papéis internos do fluxo SDD.
- Runtime adapters `rmcp`, `rig-core` e `agent-client-protocol` continuam opcionais por feature flag.
- Execution real que edita workspace continua dependente de adapter autorizado; os adapters diretos cobrem Codex, Claude Code, opencode, Cursor Agent, Devin, Trae e Antigravity.