# Implementações recentes

## 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 diagram attach --name "<ciclo>" --stage idea|prd|techspec --file <arquivo.html|svg|excalidraw> --title "<título>" --source "<origem>"
sdd acp serve --root .
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/workflows/agentic-sdd-loop.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. `sdd_context_bundle` é a leitura principal para agentes MCP porque combina Context Pack, handoff, traces, capabilities, runtime adapters, busca e recomendações CodeGraph em uma resposta. `sdd_readiness_summary` entrega o cockpit operacional com veredito `ready | warn | blocked` e próximos comandos recomendados. 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>.json`;
- `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;
- a resposta ACP orienta o caminho seguro via `sdd init` e `sdd workflow run agentic-sdd-loop`;
- 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.
