Pular para conteúdo

AUR-612 — Documentação de integração e arquitetura sem promessa que o código não cumpre

Medido

Revisores de arquitetura e de ferramentas externas (2026-10-09) acharam texto que promete o que o código não faz ou omite o passo que faz o produto funcionar. Este card corrige só documentação. Cada achado abaixo foi conferido no código desta árvore antes de ser escrito; a linha citada é a prova.

Achados, correção e prova

1. Padrões de engenharia centrais não são nativos

Página: docs/gate-corporativo.md, subseção "Padrões de engenharia centrais (hoje)", no fim da seção 1.

  • O workflow tem um único input de política, policy_repository (.github/workflows/review.yml:56); não há segundo repositório nem sincronização de skills.
  • As skills do repositório vêm da branch base da PR, no próprio repositório revisado: p.contextRef = p.env().baseSHA (cmd/aurumcode/review_pr_model.go:61), catálogo remoto nesse ref (:78) e seções citáveis nesse ref (:99).
  • .aurumcode/profiles.yml vem do mesmo ref (cmd/aurumcode/review_pr_profiles.go:53-60).
  • A política não governa review.profiles: ele está em reviewRepositoryFields (internal/config/governance.go:56).
  • O que a política carrega de skills, e por isso o caminho (a): o catálogo <política>/.aurumcode/skills/ (cmd/aurumcode/skill_catalog.go:96-101, chamado em review_pr_model.go:76) e os arquivos listados em review.context.skills da política (review_pr_model.go:97), como regras de origem política (gateOriginPolicy). Uma pasta como skills/padroes/ só é lida quando listada em review.context.skills; a página diz isso.
  • CODEOWNERS só obriga a aprovação quando a proteção da branch exige revisão de code owners: comportamento do GitHub, dito como condição, sem prometer nada do AurumCode.

2. Tabela de precedência

Página: docs/tutorials/politica-central.md, caso 3 (tabela, frase de abertura do caso e objetivo).

  • gate: governGate faz effective.Gate = central.Gate sempre, declarado ou não (internal/config/governance.go:100-109). Foi para a linha "sempre a política" com rules (:68-80), ignore (:82-89) e exceptions (:111-124).
  • quality_gates.scanners: engine por engine; entrada required: true da política vence, sem required vale a do repositório com aviso (internal/config/scanners_policy.go:11-54).
  • quality_gates.sast: o alias vira entrada semgrep com Required: true (internal/config/scanners.go:82), por isso a política vence.
  • ssor_dtrack e supply_chain: decididos pela política só quando ela os declara (internal/config/governance.go:129-145).
  • analysis_data (governance.go:150-159), deliberation (internal/config/deliberation.go:88-100), batches (internal/config/batches.go:39-51), changelog_check (internal/config/changelog_check.go:113-122) e dependencies (internal/config/dependencies.go:258-267): se a política declara, decide sozinha.
  • review.language/review.publication: da política quando declarados (governance.go:44-50, :91-98).
  • review.profiles, verification, memory, inline_comments, presentation, changelog, version: sempre do repositório (governance.go:56).
  • review.context: o do repositório continua (governance.go:56) e o da política entra como camada própria (cmd/aurumcode/review_pr_model.go:70-72, :97). A tabela diz "os dois", e não "sempre do repositório", porque o caso 1 do mesmo tutorial usa as skills da política.

3. "Cada seção de quality_gates do repositório é ignorada"

Página: docs/gate-corporativo.md, seção 1. A frase estava mais forte que o código: governQualityGates resolve cada subseção à parte, e uma seção que a política não declara continua do repositório (governance.go:126-145; scanners em scanners_policy.go:11-54). O texto novo diz isso e aponta a tabela do tutorial.

4. Versão do AurumCode, Dependabot, tag e SHA, ruleset

Páginas: docs/gate-corporativo.md (seção 3) e docs/getting-started.md.

  • A política não fixa versão mínima: não há chave para isso em Config (internal/config/config.go:248-289); review.version é a versão de changelog do repositório (config.go:97-101). Busca por min_version, minimum_version, aurumcode_version em internal/config e cmd/aurumcode: nada.
  • A versão que roda é a do uses:: o workflow faz checkout de job.workflow_sha e constrói a imagem dele (.github/workflows/review.yml:156-165).
  • O Dependabot (package-ecosystem: github-actions) atualiza referências uses:; policy_ref é um input (review.yml:61-65), que ele não toca.
  • Reconciliação: tag basta para repositório avulso (getting-started.md); no workflow obrigatório da organização, SHA de 40 hex com a versão no comentário (gate-corporativo.md), porque uma tag pode ser movida.
  • Workflow obrigatório: ruleset da organização com Require workflows to pass before merging e Require status checks to pass before merging. Fontes:
  • "Available rules for rulesets", versão Enterprise Cloud (https://docs.github.com/en/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets): "Ruleset workflows can be configured at the organization or enterprise level to require workflows to pass before merging pull requests" e os eventos aceitos (pull_request, pull_request_target, merge_group; o exemplo usa pull_request). A versão padrão da mesma página (Free/Pro/Team) não traz essa regra, só Require status checks to pass before merging.
  • "Creating rulesets for repositories in your organization" (https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization): "For customers on GitHub Team or GitHub Enterprise plans you can create rulesets in your organization".
  • GitHub Changelog, 2023-10-11, "Requiring workflows with repository rules is generally available" (https://github.blog/changelog/2023-10-11-requiring-workflows-with-repository-rules-is-generally-available/). Por isso a página diz que o ruleset depende do plano da organização e dá a alternativa: cada repositório chama o workflow e exige aurumcode/policy-gate na proteção da branch.

5. O status só impede o merge com proteção de branch

Página: docs/getting-started.md, passo 6. O workflow só publica o status aurumcode/policy-gate (cmd/aurumcode/policygate.go:24); quem o torna obrigatório é a regra Require status checks to pass before merging da proteção da branch ou do ruleset (mesma fonte do GitHub acima). O passo vem depois do primeiro PR porque o GitHub só oferece na lista um check que já rodou.

O status só é publicado com o gate ativo: publishPolicyGateStatus não faz nenhuma chamada quando !gateResult.Active (cmd/aurumcode/policygate.go:166-168). O gate fica ativo com gate: declarado (internal/config/gate.go:124-126, internal/gate/policy.go:118-121) ou com uma fonte que o ativa sozinha: scanner (internal/gate/scanner.go:80), ssor_dtrack (internal/gate/dtrack.go:81), dependencies (internal/gate/dependencies.go:33) ou analysis_data (internal/gate/analysisdata.go:59,67). Por isso o passo 6 começa com a condição (gate: declarado, ver "Configuração mínima") e avisa que, sem gate, exigir o status deixaria toda PR pendente (achado do revisor independente).

6. PR do Dependabot só recebe Dependabot secrets

Página: docs/getting-started.md, "Saber quando há versão nova". Fonte: GitHub Docs, "Troubleshooting Dependabot on GitHub Actions", seção "Accessing secrets": "When a Dependabot event triggers a workflow, the only secrets available to the workflow are Dependabot secrets. GitHub Actions secrets are not available." (https://docs.github.com/en/code-security/dependabot/troubleshooting-dependabot/troubleshooting-dependabot-on-github-actions). Sem os secrets, o job para no primeiro passo, Check provider configuration (.github/workflows/review.yml:129-138), antes de qualquer revisão e sem publicar status. No guia corporativo (docs/gate-corporativo.md, seção 4) a mesma regra vale para toda PR do Dependabot sob o workflow obrigatório: sem AURUMCODE_POLICY_TOKEN o checkout cai no github.token (review.yml:213), que não lê política privada; sem DTRACK_*, com ssor_dtrack ligado, o gate fica inconclusivo (dtrack_secret_missing). O coordenador sugeriu "o gate reprova a PR"; a página diz o comportamento real (o job falha antes do gate).

7. Falha do AURUMCODE_POLICY_TOKEN

Página: docs/gate-corporativo.md, seção 4. O token vai direto ao actions/checkout (.github/workflows/review.yml:201-215, token: em :213); o passo vem antes de "Run and publish code review" (review.yml:354), o único que publica parecer e status. Sem token, vencido ou sem Contents: read, o job para nesse passo com o erro do próprio actions/checkout. A mensagem exata ("Repository not found") não foi reproduzida aqui e não foi escrita na página.

8. Reserva Bedrock/Azure no Actions; LLM_API_KEY para Ollama

Página: docs/provedores.md.

  • O contêiner da revisão recebe só LLM_* e as variáveis listadas em .github/workflows/review.yml:445-479 (-e LLM_API_KEY em :460 até -e DTRACK_PROJECT_ID em :475): nada de AWS_REGION nem AZURE_OPENAI_*.
  • A reserva lê esses {VAR} do ambiente como estão (internal/llm/provider/profiles/fallback.go:96,107); sem a URL da reserva, o perfil expande base_url com eles (internal/llm/provider/profiles/resolve.go:75-83) e falha com set AWS_REGION (resolve.go:127). Perfis em internal/llm/provider/profiles/profiles.yml:36-46 (azure-openai, com api-version padrão) e :63-70 (bedrock).
  • LLM_API_KEY vazio é recusado pelo workflow (.github/workflows/review.yml:135-137), mesmo para ollama, cujo perfil é auth: none (profiles.yml:95-102).
  • Identificadores reais de modelo nos exemplos (claude-sonnet-5-5, gpt-5, gpt-5.4-mini, bedrock/us.anthropic.claude-sonnet-5) viraram <id do modelo no provedor> ou ....

9. Versões fixadas das ferramentas

Página: docs/gate-corporativo.md, subseção "Versões fixadas das ferramentas".

Ferramenta Versão Prova
gitleaks v8.30.1 .board/bootstrap/locks/scanners.yml:6-7; Dockerfile:20,76; .github/workflows/review.yml:171-188
Semgrep 1.172.0 Dockerfile:73; scanners.yml:31
osv-scanner v2.0.0 Dockerfile:33,79
Trivy 0.73.0 scanners.yml:18-19 (imagem por digest); review.yml:281-285 recusa imagem sem digest
Cosign v3.1.3 review.yml:511-513 (instalador fixado por SHA)

O workflow confere a versão do gitleaks, mas do Trivy só o digest; a página diz "imagem por digest" para o Trivy. A demonstração de demo/gate-corporativo/ usa as mesmas imagens de Trivy e Semgrep (images.lock); a tabela cobre o workflow e a imagem do produto.

10. Verificador adversarial no fluxo da arquitetura

Página: docs/architecture.md, passo 4 do fluxo. runGate chama s.verifyModelFindings() antes do pipeline (cmd/aurumcode/review_gate.go:156), depois da fase do modelo; só achados sem origem de scanner são candidatos (internal/review/verify/verifier.go:41-43). Mesma descrição em docs/configuration.md ("Verificação adversarial dos achados do modelo"). Não é uma fase própria de session.Order; a página o põe dentro do passo gate.

11. O analista embutido seguranca

Página: demo/do-zero/README.md. O perfil seguranca (internal/reviewprofile/builtin.yml:11-15) é um perfil de analista, e um perfil "never changes severity, --fail-on, redaction, the cost cap or the deterministic security pass" (internal/config/config.go:102-106). "O parecer é editado" virou "o parecer é atualizado".

12. Índice por capacidade no topo

Página: docs/README.md: logo abaixo do guia interativo, links para index.md (visão geral por capacidade) e tutorials/README.md (índice de tutoriais).

Fora do card

  • CHANGELOG.md está em paths, mas a entrada do lote fica com o coordenador.
  • Capturas das páginas alteradas: regeneradas pelo coordenador (scripts/docs/capturas.sh).

Provas

tests/acceptance/AUR-612.sh (só bash; lê as páginas e .github/workflows/review.yml):

id prova última linha
AC-001 cada frase corrigida dos achados 1 a 12 está na página, cada frase errada saiu; a versão do Cosign confere com review.yml AUR-612/AC-001/pass
AC-002 bash scripts/docs/build.sh (MkDocs --strict na imagem fixada por digest) Documentation built sem aviso
MUT-001 cópia das páginas com "cada seção de quality_gates do repositório é ignorada" de volta: AC-001 falha, e a falha precisa ser AUR-612/AC-001/F03/ (outra falha reprova a mutação) AUR-612/MUT-001/rejected (...F03...)