Pular para o conteúdo principal

Status: Approved · v1 · SPEC-DELIVERY-SDD-DASHBOARD-001

Dashboard operacional do SDD e adapters de skill do Claude Code

Documento gerado por raizfc-reverse-engineer-branch a partir do branch feat/sdd-dashboard, registrando de forma descritiva um trabalho construído fora do fluxo CR/IS/EP. Escopo aprovado pelo owner em 2026-08-29 — ver human_approval em CR-SDD-DASHBOARD-001. Lockfile/testes/CI e a decisão sobre virar EP/IS formal seguem abertos em pending_decisions da mesma CR.

Cenário / objetivo​

O branch feat/sdd-dashboard não tinha CR, IS ou EP formal. O trabalho foi pedido diretamente pelo usuário, em sessão, com dois objetivos distintos que acabaram no mesmo branch:

  1. Dar visibilidade operacional ao estado do SDD (bloqueios, backlog, execuções, evidência, hierarquia CR/IS/EP/SPEC) sem exigir leitura manual de YAML/JSON ou comandos de CLI.
  2. Fechar uma lacuna descoberta durante a própria sessão: skills do fluxo RaizFC vivem em .agents/skills/, mas o Claude Code só descobre skills invocáveis por / em .claude/skills/. Três das quatro skills canônicas não tinham o adapter espelho e por isso não apareciam no autocomplete.

Contexto técnico​

  • App Streamlit somente leitura (tools/sdd-dashboard/app.py), lançado por pnpm sdd:board → scripts/sdd/board.mjs (porta 8501, com fallback automático de porta se ocupada).
  • Lê os artefatos canônicos diretamente do working tree e, quando possível, via git show <ref>:<path> usando master como ref de leitura (fallback para HEAD), para refletir o estado mesclado em vez do branch de feature local.
  • Não escreve em nenhum artefato do SDD; todas as operações são leitura (.sdd/state.yaml, .sdd/changes/, .sdd/evidence/, raizfc.manifest.yaml, docs/index.json, increments/index.yaml, .ai/execution/index.yaml, .agents/skills/).
  • Dependências Python novas no monorepo: streamlit, pandas, pyyaml (tools/sdd-dashboard/requirements.txt), sem lockfile.
  • Vive em tools/, não em apps/: apps/* é glob do workspace pnpm (pnpm-workspace.yaml) e scripts/check-workspace-boundaries.mjs exige package.json válido em todo diretório ali. O CI pegou isso na primeira versão da PR (INVALID_MANIFEST em apps/sdd-dashboard), e o diretório foi movido em vez de ganhar um package.json artificial.
  • Padrão de adapter de skill (já usado antes só por raizfc-review-validate-ep): o conteúdo canônico e completo mora em .agents/skills/<nome>/SKILL.md; .claude/skills/<nome>/SKILL.md é um stub curto com o mesmo name/description no frontmatter, que só aponta para o canônico e instrui a não replicar nem relaxar o protocolo.

Arquivos relevantes​

  • tools/sdd-dashboard/app.py, README.md, requirements.txt
  • scripts/sdd/board.mjs
  • package.json (script sdd:board)
  • .claude/launch.json (preview local do dashboard)
  • .claude/skills/raizfc-execute-ep/SKILL.md
  • .claude/skills/raizfc-list-enabled-eps/SKILL.md
  • .claude/skills/raizfc-reverse-engineer-branch/SKILL.md
  • .gitignore (artefatos Python/Streamlit — já commitado em 94e49bb)

Comportamento observado​

  • O dashboard abre em http://127.0.0.1:8501 e mostra: Overview (foco atual, métricas, distribuição por status, timeline de execução, backlog priorizado, bloqueios, snapshot de CRs, últimas execuções), Hierarchy, Entity Detail (EP/IS/CR), Execution Log (com detalhe rico por execução: comandos, findings, artefatos, metadados técnicos, command log), Prompt Snippets, Skills (lê .agents/skills/*/SKILL.md) e Docs.
  • Os três adapters novos em .claude/skills/ foram confirmados funcionando nesta mesma sessão: cada um apareceu no índice de skills do Claude Code assim que o arquivo foi criado, e /raizfc-reverse-engineer-branch foi invocado com sucesso para gerar este próprio documento.
  • O schema de findings em .sdd/evidence/*/metadata.yaml não é uniforme entre execuções (algumas usam area/resolution, outras id/disposition); o dashboard trata isso de forma defensiva, mas o schema em si não foi alterado por este trabalho.

Dependências e risco​

  • requirements.txt usa faixas de versão (>=, <) sem lockfile — risco de drift de versão entre máquinas.
  • Nenhum teste automatizado cobre tools/sdd-dashboard/app.py.
  • Não há verificação automática de que todo .agents/skills/<nome>/ tenha o adapter espelho em .claude/skills/<nome>/ — hoje é um passo manual; uma nova skill sem esse passo volta a ficar invisível no autocomplete, como aconteceu com as três skills fechadas por este trabalho.
  • O dashboard usa subprocess para git show, mas o ref só vem de master/HEAD resolvidos internamente, nunca de input externo — sem superfície de injeção conhecida.
  • Regra de manutenção (owner, 2026-08-29): qualquer mudança estrutural no SDD que afete o que o dashboard lê ou exibe deve vir acompanhada da atualização correspondente em tools/sdd-dashboard/app.py no mesmo trabalho. Não há checagem automática disso ainda — ver pending_decisions em CR-SDD-DASHBOARD-001.

Impacto de uso / arquitetura​

  • Ferramenta interna, uso local, sem autenticação, sem deploy remoto e sem qualquer mudança de produto/UX voltada ao usuário final do RaizFC.
  • Não altera o protocolo de nenhuma skill canônica; os adapters só redirecionam para o conteúdo já existente em .agents/skills/.

Itens não resolvidos ou assumidos​

  • Aprovação humana explícita do escopo recebida em 2026-08-29 — ver human_approval.status: approved em CR-SDD-DASHBOARD-001.yaml. Lockfile, testes/CI e a decisão de virar EP/IS formal seguem abertos em pending_decisions da mesma CR.
  • Este trabalho não foi decomposto em IS/EP formais: é tooling interno, não um incremento de produto, e forçar essa estrutura seria inventar status que o SDD não confirma.
  • Este documento entra em docs/index.json/docs/07_delivery/README.md via pnpm sdd:generate — não editei esses dois arquivos manualmente porque são catálogos gerados pelo próprio SDD.