Pular para conteúdo

AUR-445 — A documentação de raiz diz a verdade sobre o que a ferramenta faz

Documento histórico do board. Pode descrever componentes removidos; para uso atual, consulte o guia do produto.

O que este card entrega

A auditoria de 2026-08-13 (.board/cards/ready/AUR-445.md, seção "Achados medidos") encontrou cinco famílias de afirmação falsa espalhadas pela documentação de raiz. Este card corrige cada uma, ancorada no código real:

  1. LICENSE existe. README.md, ACTION_USAGE.md e CHANGELOG.md afirmavam "No LICENSE file is present" / "no LICENSE file is present". LICENSE (MIT, Copyright (c) 2026 Mateus Magnus Pimentel Paape) está na raiz do repositório desde o AUR-428. Os três arquivos agora apontam para [MIT](LICENSE).
  2. aurumcode review existe. CHANGELOG.md afirmava "No code-review or test-generation output". cmd/aurumcode é um segundo binário package main que implementa revisão de código local: aurumcode review --base <ref> [--fail-on <nível>] [--modelo <nome>] [--seguranca] [--limite <usd>] [--pr <n> --repo <owner/repo> --publicar --na-linha]. CHANGELOG.md agora documenta essa superfície sob "Present" e corrige "Not present" para nomear cmd/regenerate-docs explicitamente (é esse binário, não o repositório inteiro, que não faz revisão de código).
  3. As opções de aurumcode review são flags, não variáveis de ambiente. CHANGELOG.md:93 generalizava "Every knob is an environment variable" para o repositório inteiro. Isso continua verdadeiro para cmd/regenerate-docs (nenhum flag. no seu main.go; todas as chaves são os.Getenv/os.LookupEnv), mas é falso para cmd/aurumcode, cujas opções são exclusivamente flag.String/flag.Bool/flag.Int registradas em cmd/aurumcode/main.go. A correção separa os dois binários em vez de generalizar.
  4. Go não precisa de ferramenta externa. README.md:72,99, SETUP_GUIDE.md:86, ACTION_USAGE.md:49,56,265, docs/getting-started.md:53-54,75 e o texto correlato em RUN_DOCS_PIPELINE.md declaravam gomarkdoc obrigatório para Go. Desde o AUR-424, internal/documentation/extractors/go/extractor.go usa apenas go/parser + go/doc da biblioteca padrão — Validate() sempre retorna nil e nenhum arquivo do pacote importa os/exec ou referencia gomarkdoc. As outras 7 linguagens registradas (JavaScript/TypeScript, Python, C/C++, Bash, PowerShell, e — atrás de AURUMCODE_ALLOW_REPO_CODE_EXECUTION — Rust e C#) continuam dependendo de uma ferramenta externa; a correção é específica a Go, não uma generalização de "nenhuma linguagem precisa de ferramenta".
  5. Há dois comandos, não um. RUN_DOCS_PIPELINE.md:6-8 afirmava que cmd/regenerate-docs é "the only command in this repository". O repositório builda dois binários package main: cmd/regenerate-docs (gerador de documentação, tema deste arquivo) e cmd/aurumcode (aurumcode review, revisão de código). A correção nomeia o segundo e aponta para docs/specs/AUR-430.md sem transformar este arquivo em um tutorial de aurumcode review.

Escopo não expandido (Non-goals do card)

  • Rust e C# não são suportados por padrão hoje: ambos exigem AURUMCODE_ALLOW_REPO_CODE_EXECUTION porque seus toolchains (cargo doc, dotnet build) executam código do repositório documentado (internal/documentation/extractors/{rust,csharp}/extractor.go, constante ExecutesRepositoryCode). Nenhuma correção deste card afirma suporte pronto para uso a Rust ou C#.
  • --seguranca roda um subconjunto das regras do catálogo: internal/review/rules/security.yml declara 8 regras; apenas 2 carregam pattern (security/sql-injection, security/command-injection) e são de fato casadas contra as linhas adicionadas do diff. As outras 6 são metadado citável por um achado do modelo, não casadas pela passagem determinística. CHANGELOG.md agora declara esse escopo explicitamente em vez de deixar --seguranca implicar cobertura total. Essa contagem foi verificada por leitura direta do arquivo durante a construção deste card; internal/review/rules/security.yml está fora dos read_paths declarados no card, então o aceite sandboxed (tests/integration/AUR-445.go) deliberadamente NÃO relê esse arquivo em tempo de aceite — fazê-lo falharia com entrypoint_missing no perfil bootstrap-readonly-v1, que só materializa paths/read_paths, em vez de produzir um resultado de comportamento real.

Comando (verificação estática do aceite)

O aceite roda offline, sem executar aurumcode nem regenerate-docs, e sem rede — é leitura e correspondência de texto sobre os seis arquivos de documentação de raiz declarados em paths, mais checagem cruzada documentação-vs-código sobre os read_paths declarados no card.

# Dentro do profile pinado, cwd no worktree do candidato:
ulimit -v 8388608
export GOMEMLIMIT=2GiB GOFLAGS='-mod=mod -p=1'
bash tests/acceptance/AUR-445.sh AC-001

oci-run não passa seletor, então AC-001 (o default do script) é exatamente o que o aceite selado executa. O script, nesse caminho:

  1. Normaliza o texto de cada um dos seis arquivos (README.md, CHANGELOG.md, ACTION_USAGE.md, SETUP_GUIDE.md, RUN_DOCS_PIPELINE.md, docs/getting-started.md) — remove crase, normaliza para minúsculas, colapsa espaços em branco e quebras de linha — e confirma a ausência de cada uma das cinco famílias de frase falsa listadas acima (Unit, tests/unit/AUR-445.go::TestAUR445).
  2. Confirma, por leitura direta do código (não por outro grep sobre a documentação), que as afirmações verdadeiras têm lastro: LICENSE começa com "MIT License"; cmd/aurumcode/main.go e cmd/regenerate-docs/main.go são ambos package main; nenhum arquivo em internal/documentation/extractors/go/ referencia gomarkdoc ou importa os/exec; toda flag citada na documentação (base, fail-on, modelo, seguranca, limite, pr, repo, publicar, na-linha) está registrada em cmd/aurumcode/main.go (Integration, tests/integration/AUR-445.go::IntegrationAUR445).
  3. Roda a mesma verificação a partir do binário de shell (tests/e2e/AUR-445.sh::E2EAUR445), no mesmo processo do AC-001.

AC-001 sozinho NÃO reproduz o MUT-001: essa mutação é uma invocação separada, bash tests/acceptance/AUR-445.sh MUT-001, que este card provou manualmente durante a construção (nunca automática dentro de oci-run, mesma convenção de AUR-428/AUR-440). Essa invocação estagia uma cópia descartável SEPARADA em /tmp (nunca o README.md rastreado), reintroduz a frase banida só nessa cópia, exporta AUR445_MUTATION=MUT-001 para que o Unit e o E2E distingam a mutação deliberada do RED natural (que produz o mesmo texto banido, mas sem o marcador — ver a nota de normalização em tests/unit/AUR-445.go), e confirma que a saída capturada de cada camada carrega o rótulo AUR-445/AC-001/MUT-001 antes de aceitar a falha como a mutação detectada. A cópia é descartada ao final; o README.md rastreado nunca é tocado.

Exit codes

Código Contexto Significado
0 AC-001 Todas as cinco famílias de frase falsa estão ausentes dos seis arquivos e todas as afirmações verdadeiras têm lastro no código.
0 MUT-001 A mutação de ceticismo (reintroduzir "No LICENSE file is present" só na cópia descartável) foi detectada corretamente pelas camadas Unit e E2E; o script de aceite reporta sucesso EM DETECTAR a mutação.
1 (rotulado AUR-445/AC-001/behavior-missing) AC-001 sobre uma árvore não corrigida (RED), ou MUT-001 sem o marcador AUR445_MUTATION Uma frase falsa sobrevive, ou uma afirmação verdadeira não tem lastro.
1 (rotulado AUR-445/AC-001/MUT-001) Dentro da invocação MUT-001 A camada (Unit ou E2E) recusou a cópia mutada, como esperado; capturado e verificado pelo próprio script de aceite antes de reportar sucesso.
64 Seletor desconhecido (erro de uso do script).
69 Falha de infraestrutura (ex.: go ausente do PATH), nunca contada como aceite.

Exemplo executável, sem segredo

cd /caminho/para/AurumCode
ulimit -v 8388608
GOMEMLIMIT=2GiB GOFLAGS='-mod=mod -p=1' bash tests/acceptance/AUR-445.sh AC-001
echo "exit: $?"

Saída esperada em GREEN: uma linha JSON {"card":"AUR-445","scenario":"AC-001","result":"pass",...} e exit 0.

Diagnóstico de falha

  • AUR-445/AC-001/behavior-missing:<arquivo>:<família> — a família de frase falsa nomeada ainda aparece (após normalização) no arquivo nomeado; releia a seção correspondente deste spec e a auditoria original no card.
  • AUR-445/AC-001/behavior-missing:integration:<claim> — a checagem cruzada contra o código (LICENSE, package main, ausência de gomarkdoc/os/exec no extrator Go, ou uma flag citada mas não registrada) falhou; o código mudou sem a documentação acompanhar, ou vice-versa.
  • AUR-445/AC-001/MUT-001 — esperado apenas durante a própria execução da mutação de ceticismo; fora dela, indica que a frase banida voltou a aparecer em README.md, ACTION_USAGE.md ou CHANGELOG.md.
  • Exit 69 — infraestrutura (Go ausente, mktemp falhou); nunca conta como prova de comportamento.

Nota sobre os nomes dos seletores no card

A seção "TDD proof" do card nomeia os seletores TestAUR428, IntegrationAUR428 e E2EAUR428 — resíduo do template copiado de AUR-428 (mesmo office, mesmo formato de card). Esses símbolos já existem em tests/unit/AUR-428.go e tests/integration/AUR-428.go, no mesmo pacote (unit, integration); declará-los de novo em tests/unit/AUR-445.go / tests/integration/AUR-445.go colidiria e quebraria go build ./.... Este card usa os nomes correspondentes ao seu próprio ID — TestAUR445, IntegrationAUR445, E2EAUR445 — mantendo o mesmo padrão de nomenclatura (prefixo TestAUR<NNN>) que todo outro card do office já segue.