Pular para conteúdo

AUR-501 — Cada capacidade entregue tem tutorial e demonstração reproduzível

Medido antes (auditoria por leitura)

Capacidades de docs/configuration.md e de docs/index.md contra demo/tutoriais/*/run.sh (casos CASOS) e docs/tutorials/*.md:

Capacidade Tutorial antes
Revisão, prompts/skills, provedores, opções públicas, PR grande revisao, skills, provedores
Política central, gate, gate.sources, gate.triage, exceções, auditoria/SARIF politica-central, gate, excecoes, auditoria-sarif
SAST, segredos, SBOM/Dependency-Track, assinatura, xBOM, analysis_data sast, segredos, sbom-dependency-track, assinatura, xbom, dados-de-analise
Deliberação, qualquer linguagem, reaproveitamento, agente (MCP), extensão, benchmark, operação um tutorial cada
Changelog obrigatório (AUR-509) e sugestão de changelog nenhum
Realimentação da política (AUR-532) nenhum
Memória de revisão (review.memory) nenhum
Status do CI no parecer nenhum
Release oficial (AUR-510) capacidade não entregue

Invariante medida em todos os 21 tutoriais: o conjunto CASOS do run.sh é igual ao conjunto expected/<caso>.txt. A frase de RESULTADO: nem sempre é literal no run.sh (53 de 204 vêm de variáveis ou helpers), por isso a evidência rastreada é a linha do expected/.

Decisão

  • Tutorial novo changelog (pt-BR, padrão existente: run.sh com _lib/tutorial.sh, repo-exemplo/ com base e overlays, fixture-llm.json, expected/, docs/tutorials/changelog.md com blocos arquivo/saida, "Quando falha" e "Problemas comuns"). Casos: entrada-valida, consolidar-release, sugestao-separada, pr-desliga-o-modo, log-de-agente, falha-entrada-ausente. Não executado: o expected/ foi escrito pela leitura de internal/changelog e cmd/aurumcode/cmd_changelog.go; o fluxo final grava out/ e a seção "Como fica" (gerada por scripts/docs/capturas.sh).
  • Tutorial novo realimentacao (mesmo padrão), com GitHub falso próprio (demo/tutoriais/realimentacao/github-falso.py, subindo dentro do container por dentro.sh com rede none, estado do caso em .estado/) e o provedor falso (fixture-propostas.json). Casos: plano-sem-publicar, publica-uma-pr, rodada-sem-novidade, medir-melhora, medir-regressao, falha-sem-modelo. Os ids dos sinais no expected/ foram calculados pela regra de internal/feedback/signal.go (sha256 de tipo, repo e id da fonte).
  • Tutorial novo memoria (review.memory): a memória local guarda a observação (cache apontado por XDG_CACHE_HOME para dentro do repositório do caso), a segunda rodada a recebe no prompt (AURUMCODE_PROMPT_CAPTURE), off não grava, modo desconhecido é relatado e a revisão segue.
  • Mapa rastreado tests/fixtures/tutorials/mapa.tsv: uma linha por caso público (capacidade, tutorial, caso, comando, fixture, expected/, a linha RESULTADO: prometida, jornada do AC-003, estado). Capacidades sem tutorial aparecem como planejado com o card ou a pendência: release (AUR-510) e status do CI.
  • docs/index.md liga o tutorial; docs/tutorials/README.md e demo/tutoriais/README.md ganham a linha do tutorial.
  • docs/site/index.html (legado) não foi alterado: o site publicado é o MkDocs, que já injeta docs/tutorials/*.md no nav (scripts/docs/hooks.py).

Fora dos paths do card

demo/tutoriais/changelog/, demo/tutoriais/realimentacao/, demo/tutoriais/memoria/ e demo/tutoriais/README.md (pedido explícito do coordenador: os tutoriais seguem o padrão demo/tutoriais), docs/index.md (link do tutorial).

Como cada cenário é provado (tests/acceptance/AUR-501.sh, só bash)

  • AC-001: todo caso de todo run.sh está no mapa como entregue; cada linha entregue aponta para doc, run.sh, caso em CASOS, expected/ com a linha prometida e comando que existe no registro de subcomandos; planejado sem tutorial traz o motivo.
  • AC-002: cada caso entregue afirma exit_code= e RESULTADO:; o caso sem provedor (TUT_FIXTURE=none) existe e o texto explica a análise determinística; tutorial que roda review identifica a fixture do modelo.
  • AC-003: as jornadas review, contexto, memória, sugestão/fix, publicação, changelog e release estão no mapa; as entregues têm "Quando falha" ou "Problemas comuns".
  • AC-004: nenhuma forma de credencial em docs/tutorials e demo/tutoriais; nenhum go build/test/run em bloco bash dos tutoriais; o job de documentação roda em pull_request.
  • MUT-001: tirar revisao/fix do mapa → case-missing-from-map:revisao/fix; trocar a promessa de changelog/entrada-valida → promised-output-changed.

Limites

  • O expected/ do tutorial novo é uma previsão por leitura; o fluxo final roda run.sh all, grava out/ e corrige divergência, se houver.
  • Status do CI e release ficam como planejados no mapa: não há tutorial deles nesta entrega (release depende de uma versão publicada).