Pular para conteúdo

AUR-561: tutoriais executáveis de revisão, skills de convenção e política central

O que entrega

  • demo/tutoriais/_lib/tutorial.sh: framework comum (fases, out/<caso>.log, --check por grep -F de cada linha de expected/<caso>.txt, imagem do produto por Dockerfile, provedor falso AURUMCODE_LLM_FIXTURE, --network none, repositórios descartáveis em .estado/). Como criar um tutorial novo: demo/tutoriais/README.md (para os cards 562 a 564).
  • Três tutoriais em docs/tutorials/ (pt-BR), com índice em docs/tutorials/README.md, e as demonstrações em demo/tutoriais/<tutorial>/ (run.sh com uma fase por caso, expected/, out/ da última execução real).
  • tests/acceptance/AUR-561.sh: all, AC-001..AC-004, AC-002-MUT-001; seletor desconhecido sai 64.

Decisões

  • O produto, não um simulacro. Cada caso roda /app/aurumcode da imagem construída do Dockerfile da raiz, sem rede, com o provedor falso. A fase de PR é conferência do workflow, não revisão de PR (ver "Limites").
  • Blocos literais. O texto marca <!-- arquivo: PATH --> antes do bloco; o aceite compara byte a byte. Saídas esperadas marcam <!-- saida: caso -->; cada linha do bloco tem de existir em out/<caso>.log (AC-002).
  • Saída copiada, não escrita. expected/ guarda só linhas que provam o caso; o texto só mostra linhas presentes no out/.
  • .gitignore. O .gitignore da raiz ignora *.log; demo/tutoriais/.gitignore reabre out/ para os tutoriais (o out/ é evidência versionada).
  • Texto de rede omitido, declaradamente. Só em politica-central/analysis-data, o detalhe do erro de rede (varia por ambiente) é trocado por <detalhe de rede omitido do registro> por TUT_SED, documentado no run.sh.

Achados sobre o produto (honestidade do tutorial)

  1. Seleção por linguagem e apelidos não estão ligados ao review. .aurumcode/skills/<nome>/SKILL.md com languages: [...] (internal/context/skills, AUR-468/AUR-559) é biblioteca: só testes (tests/unit/AUR-468.go, internal/context/skills/aur559_test.go) chamam skills.Providers. A CLI usa review.context.skills (lista explícita) e .aurumcode/instructions/*.md com applyTo (escopo por caminho). O tutorial de skills prova o negativo (selecao-por-linguagem) e usa o escopo por caminho como seletor funcional. O bloco ### Skill selection warnings (apelido desconhecido) só existe na biblioteca; teste que o cobre, rodado no go-shared nesta execução: TestAUR559AliasResolvesAndUnknownIsDeclared PASS.
  2. Skill ausente no repositório é aviso, não erro. continuing without that context, e achados que citam os ids dessa skill são descartados; o parecer pode sair Approve. Na política central é erro de carga (exit 1). O tutorial registra isso.
  3. fix imprime um patch sem contexto (@@ -6,1 +6,1 @@): git apply exige --unidiff-zero (o docs/getting-started.md mostra git apply sem a flag).
  4. Cobertura parcial sem gate sai 0 com veredito Comment; só com gate.inconclusive: block reprova (exit 1, partial_coverage).
  5. analysis_data declarado numa política faz o review consultar o GitHub: sem rede é inconclusivo (analysis_data_unavailable).

Limites

  • Não há runner do GitHub nem servidor GitHub reutilizável fora dos testes Go (os falsos de cmd/aurumcode/*_test.go são httptest em Go); então o caso "revisão de PR" prova só a coerência do workflow do chamador com .github/workflows/review.yml (inputs, secrets, permissões, policy_*). O review --pr não é executado.
  • AURUMCODE_PROMPT_CAPTURE (observação do prompt) é variável interna de observação, usada só para mostrar o que chegou ao modelo.
  • AURUMCODE_CACHE_DIR não é definido: o aviso gate verdict reuse unavailable aparece nos logs e é esperado.

Entradas de nav (o coordenador acrescenta ao mkdocs.yml do AUR-560)

mkdocs.yml não existia neste worktree; não foi criado. Entradas sob a seção Tutoriais:

nav:
  - Tutoriais:
      - Índice: tutorials/README.md
      - Revisão de código: tutorials/revisao.md
      - Skills de convenção: tutorials/skills.md
      - Política central: tutorials/politica-central.md

(docs/tutorials/revisao.md, docs/tutorials/skills.md, docs/tutorials/politica-central.md.) O AC-001 exige essas três entradas em mkdocs.yml quando ele existir.

Execução real

Execução real, em container, com a imagem aurum-tutoriais:local construída do Dockerfile do worktree (docker build -q -t aurum-tutoriais:local .), sem rede e com o provedor falso. Comandos: bash demo/tutoriais/<t>/run.sh all (os três terminaram com exit 0) e run.sh --check. A saída completa de cada caso é demo/tutoriais/<t>/out/<caso>.log (551 linhas no total).

revisao

  • revisao/primeira-revisao: exit_code(s) 0; primeira revisao concluida sem achados
  • revisao/sem-provedor: exit_code(s) 3; sem provedor, a analise deterministica achou o segredo e reprovou
  • revisao/com-provedor: exit_code(s) 3; achado do modelo citando security/hardcoded-secret reprovou
  • revisao/modelo-pondera (AUR-579): exit_code(s) 0; o relatorio mostra a origem ao lado da avaliacao do modelo (contestado e confirmado), sem gate nada muda de contagem
  • revisao/achado-refutado (AUR-603): exit_code(s) 0,3; refutado com citacao literal: o achado deixa de bloquear e fica marcado | citacao inexistente: a refutacao e descartada e o achado reprova
  • revisao/fix: exit_code(s) 0,1; fix imprimiu o patch (nada foi escrito no repositorio) | sugestao velha recusada, sem patch
  • revisao/pr-workflow: exit_code(s) n/a (conferencia, sem aurumcode)
  • revisao/falha-nao-revisado: exit_code(s) 0,1; sem gate, exit 0 mas o veredito nao e Approve | com gate.inconclusive: block, cobertura parcial reprova
caso primeira-revisao: ok
caso sem-provedor: ok
caso com-provedor: ok
caso fix: ok
caso pr-workflow: ok
caso falha-nao-revisado: ok
CHECK OK

skills

  • skills/skill-do-repo: exit_code(s) 0; o achado cita a secao da skill como regra; sem gate o exit e 0
  • skills/seletor-por-caminho: exit_code(s) 0; revisao feita
  • skills/selecao-por-linguagem: exit_code(s) 0; revisao feita
  • skills/repo-vs-politica: exit_code(s) 0,3; sob politica, a secao da skill do repo nao entra no gate | a secao da skill da politica reprova
  • skills/regra-citavel: exit_code(s) 3,3; o gate compara o MAIOR entre a severidade do modelo e a da secao | a secao nova ja e citavel e reprova
  • skills/falha-skill-inexistente: exit_code(s) 0,1; localmente a skill ausente e avisada e a revisao continua | politica com skill inexistente falha o comando
caso skill-do-repo: ok
caso seletor-por-caminho: ok
caso selecao-por-linguagem: ok
caso repo-vs-politica: ok
caso regra-citavel: ok
caso falha-skill-inexistente: ok
CHECK OK

politica-central

  • politica-central/politica-local: exit_code(s) 0,3; sem politica nao ha gate | a politica reprova o achado que cita a skill dela
  • politica-central/policy-repository: exit_code(s) n/a (conferencia, sem aurumcode)
  • politica-central/precedencia-por-secao: exit_code(s) 0; revisao feita sob politica
  • politica-central/analysis-data: exit_code(s) 0; analysis_data da politica indisponivel e inconclusivo (warn), nunca aprovado
  • politica-central/repo-afrouxa: exit_code(s) 0,3; o gate do proprio repositorio aceita o warning | o repositorio nao consegue afrouxar o gate da politica
  • politica-central/falha-politica-invalida: exit_code(s) 1; politica invalida falha antes de qualquer chamada ao modelo
caso politica-local: ok
caso policy-repository: ok
caso precedencia-por-secao: ok
caso analysis-data: ok
caso repo-afrouxa: ok
caso falha-politica-invalida: ok
CHECK OK

Aceite

bash tests/acceptance/AUR-561.sh all (offline; AC-003 usa .bin/aurumcode ou go build no sandbox). Selecionadores: AC-001..AC-004, AC-002-MUT-001. Selecionador desconhecido sai 64. Sealed: ./.board/bin/oci-run --profile go-unit-offline-v1 --card AUR-561.

Revisão de rigor (pós-aprovação)

  • Linhas RESULTADO:/prompt:/conferências de workflow estão marcadas no texto como conclusão do script, com a condição testada.
  • Novos casos executados: revisao/sem-provedor com --exigir-qualidade (exit 1) e a ordem política-primeiro em skills/repo-vs-politica (prompt capturado).
  • Afirmações sem lastro marcadas "não demonstrado aqui" (warn inconclusivo, 403, supply_chain mantido).
  • O container roda com --user "$(id -u):$(id -g)" (_lib/tutorial.sh); nada com dono root em out/. Os out/ dos três tutoriais foram regravados com execução real.

Site (AUR-560 integrado)

git merge --no-ff main trouxe o site; o hook injeta a aba Tutoriais a partir de docs/tutorials/README.md e docs/tutorials/*.md (o mkdocs.yml não foi editado). bash scripts/docs/build.sh, exit 0, strict, 0 warnings; páginas geradas: tutorials/, tutorials/revisao/, tutorials/skills/, tutorials/politica-central/.

INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /docs/site
INFO    -  Documentation built in 2.95 seconds