AUR-455 — Um desenvolvedor novo roda as tres features em um minuto

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 onboarding de 2026-08-14 (.board/cards/ready/AUR-455.md, seção "Achados medidos") mediu quatro problemas concretos: README.md tinha zero ocorrências da palavra "review" (a feature principal era invisível); o comando de build que o README mandava rodar (go build ./...) falha; o único exemplo executável de aurumcode review vivia em docs/specs/AUR-430.md (um spec de card, não um doc de usuário) e estava quebrado como escrito; e .github/workflows/examples/ nunca era linkado de lugar nenhum. Este card entrega:

demo.sh na raiz — builda ./cmd/regenerate-docs e ./cmd/aurumcode uma vez cada e roda as três features contra fixtures determinísticas comitadas, offline, sem chave de LLM: (a) geração de documentação (result=ok), (b) aurumcode review --base HEAD~1 --seguranca sem nenhuma configuração, (c) o mesmo review com uma resposta de modelo fixada por AURUMCODE_LLM_FIXTURE, e (d) a linha de publicação Jekyll que o passo (a) já imprime.
README.md: uma seção "Try it now" no topo apontando para bash demo.sh, uma seção "Features" com as três features e o comando real de cada uma, a correção do comando de build (go build ./cmd/... ./internal/... ./pkg/..., com a razão), e o link para .github/workflows/examples/.
docs/getting-started.md: corrige a linha que mandava compilar o gerador de documentação com o nome aurumcode, que colide com o CLI de review real.

O caminho relativo corrigido (achado desta construção)

docs/specs/AUR-430.md's próprio exemplo executável (fora dos paths e read_paths deste card, portanto nunca relido pelo aceite) tem:

$ cd tests/fixtures/repos/git-demo/repo.git
$ AURUMCODE_LLM_FIXTURE=../../review/known-problem-response.json \
    go run ../../../../../cmd/aurumcode review --base HEAD~1

O caminho do fixture, ../../review/known-problem-response.json, sobe apenas dois níveis a partir de tests/fixtures/repos/git-demo/repo.git (chegando a tests/fixtures/repos/) e nunca resolve — tests/fixtures/review/known-problem-response.json está três níveis acima, não dois. Executar o comando como escrito falha com open ../../review/known-problem-response.json: no such file or directory, que aurumcode review reporta como "no LLM provider configured" (o arquivo apontado nunca é aberto). O caminho correto, confirmado por execução direta durante a construção deste card:

$ cd tests/fixtures/repos/git-demo/repo.git
$ AURUMCODE_LLM_FIXTURE=../../../review/known-problem-response.json \
    go run ../../../../../cmd/aurumcode review --base HEAD~1
config/demo-tokens.txt:4: [error] A credential-shaped value was committed in plain text (DEMO_API_TOKEN). (rule security/hardcoded-secret: Hardcoded Secrets)

demo.sh evita a fragilidade de contar níveis de ../ inteiramente: ele resolve seu próprio diretório (script_dir) uma vez e passa caminhos absolutos para o binário e para AURUMCODE_LLM_FIXTURE, então cd para dentro do repositório-fixture apenas para que --base resolva contra o cwd correto. Esta correção vive apenas nos artefatos deste card (demo.sh, este spec); docs/specs/AUR-430.md não está em paths e permanece intocado — corrigi-lo pertence ao card que o possui.

Por que (b) e (c) rodam contra a fixture git-demo, não contra o histórico deste repositório

.board/bin/oci-run materializa apenas arquivos rastreados sob paths e read_paths (git ls-files --cached) e recusa qualquer sobreposição com forbidden_paths (que inclui .git, ver oci-run linhas 592-599). O .git real deste repositório nunca chega ao sandbox bootstrap-readonly-v1 — nem por acidente, porque a checagem de sobreposição impede até uma declaração deliberada. Isso significa que aurumcode review --base HEAD~1 rodando contra o próprio checkout deste repositório dentro do aceite falharia com "not a git repository": não há .git para encontrar.

tests/fixtures/repos/git-demo/repo.git é um repositório git bare, pequeno, comitado como arquivos comuns (não é um diretório .git), com objetos soltos apenas — exatamente o formato que o leitor Go-puro de internal/analyzer/gitrepo.go lê quando nenhum binário git está no PATH (o caso do bootstrap-readonly-v1, documentado em docs/specs/AUR-430.md, "Reading a repository"). Usar essa fixture para os passos (b) e (c) torna demo.sh idêntico byte-a-byte rodando num clone normal ou dentro do sandbox selado, e além disso produz um resultado mais interessante que rodar contra o histórico deste próprio repositório: o terceiro commit da fixture planta três segredos sintéticos (config/demo-tokens.txt), então --seguranca sem nenhuma configuração já encontra três achados reais, em vez de "No security findings." — a mesma demonstração que rodar aurumcode review --base HEAD~1 --seguranca faria contra qualquer repositório real: basta cd para dentro dele primeiro.

Ambiente de recursos (medido contra a imagem selada durante a construção)

O profile bootstrap-readonly-v1 limita memória a 256MB (.board/oci/profiles/bootstrap-readonly-v1.json). Buildar ./cmd/aurumcode (que importa internal/llm/provider/litellm, internal/review, gopkg.in/yaml.v3, etc.) com o paralelismo padrão do compilador Go é morto por OOM sob esse limite — confirmado rodando a imagem selada (aurum-bootstrap-go-bash, .board/locks/oci/bootstrap-readonly-v1.lock.json) com --memory=256m --user=65534:65534 --read-only --network=none diretamente durante a construção deste card. GOFLAGS='-mod=mod -p=1' mais GOMAXPROCS=1 resolvem: o mesmo build, com essas variáveis, completa em cerca de 20 segundos de parede (cache frio), bem dentro do timeout_seconds: 120 do profile. tests/acceptance/AUR-455.sh exporta essas variáveis para cada lane; demo.sh em si não as força, para não alterar o comportamento de um desenvolvedor rodando o script normalmente, fora do sandbox.

O cache de módulos (gorilla/mux, yaml.v3) já está populado dentro da imagem selada (go mod download roda no build da imagem, .board/oci/images/bootstrap-readonly-v1/Dockerfile), em GOPATH=/go, que é legível por qualquer usuário — inclusive 65534:65534. GOCACHE precisa apontar para o tmpfs gravável (/tmp, montado com exec); a raiz do sistema de arquivos é somente leitura.

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

Rust e C# não ganham nenhuma alegação nova neste card: apenas o caminho nativo, sem ferramenta externa, que o AUR-427/AUR-447 entregaram é citado onde citado; a superfície AURUMCODE_ALLOW_REPO_CODE_EXECUTION já existente no README não é reescrita por este card.
--seguranca cobre um subconjunto nomeado do catálogo de regras — o próprio binário informa a contagem (security pass applied 3 of 8 security rules, verificado por execução direta durante a construção deste card). A seção "Features" do README cita essa contagem em vez de implicar cobertura total.
A tag v1 que os workflows de exemplo referenciam (.github/workflows/examples/code-review.yml's ref: v1, .github/workflows/examples/documentation.yml's uses: Mpaape/AurumCode@v1) não existe ainda neste repositório (git tag -l não a lista, verificado durante a construção). O README declara explicitamente que publicar essa tag é uma ação do mantenedor, não algo que este card ou demo.sh fazem.

Comando (aceite executa demo.sh de verdade)

Ao contrário de um card puramente documental, o aceite deste card não é verificação estática apenas: a camada E2E builda os dois binários e roda demo.sh de fato, contra as fixtures comitadas.

# Dentro do profile pinado, cwd no worktree do candidato:
ulimit -v 8388608
export GOMEMLIMIT=2GiB GOFLAGS='-mod=mod -p=1'
bash tests/acceptance/AUR-455.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:

Confirma estaticamente, por texto normalizado, que README.md e docs/getting-started.md carregam as âncoras que este card promete (Unit, tests/unit/AUR-455.go::TestAUR455).
Confirma, por leitura direta do código e das fixtures (não por outro grep sobre a documentação), que essas âncoras têm lastro: as flags citadas estão registradas em cmd/aurumcode/main.go; a fixture git-demo tem pelo menos dois commits; known-problem-response.json existe e tem ao menos um issue; os dois workflows de exemplo realmente referenciam a tag v1 (Integration, tests/integration/AUR-455.go::IntegrationAUR455).
Builda ./cmd/regenerate-docs e ./cmd/aurumcode e roda demo.sh de verdade, verificando que a saída capturada carrega os cinco marcadores dos quatro passos rotulados (E2E, tests/e2e/AUR-455.sh::E2EAUR455).

AC-001 sozinho NÃO reproduz o MUT-001: essa mutação é uma invocação separada, bash tests/acceptance/AUR-455.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/AUR-445). Essa invocação estagia uma cópia descartável SEPARADA em /tmp (nunca o demo.sh ou o cmd/aurumcode/main.go rastreados), renomeia apenas nessa cópia o registro da flag --seguranca em cmd/aurumcode/main.go (via sed), exporta AUR455_MUTATION=MUT-001 para que a camada E2E distinga a mutação deliberada de uma regressão real, builda e roda o demo.sh dessa mesma cópia mutada, e confirma que ele para de rodar (exit não-zero) com o rótulo AUR-455/AC-001/MUT-001. A cópia é descartada ao final; nada rastreado é tocado.

Exit codes

Código	Contexto	Significado
`0`	`AC-001`	As três camadas (Unit, Integration, E2E) passaram: a documentação promete o que o repositório faz, e `demo.sh` realmente roda e produz os quatro passos.
`0`	`MUT-001`	A mutação de ceticismo (quebrar a flag `--seguranca` só na cópia descartável) foi detectada corretamente pela camada E2E; o script de aceite reporta sucesso EM DETECTAR a mutação.
`1` (rotulado `AUR-455/AC-001/behavior-missing`)	`AC-001` sobre uma árvore não corrigida (RED)	`demo.sh` ausente, uma âncora de documentação ausente, ou `demo.sh` executado e sem um dos cinco marcadores esperados.
`1` (rotulado `AUR-455/AC-001/MUT-001`)	Dentro da invocação `MUT-001`	A camada E2E recusou a cópia mutada (a flag quebrada faz `demo.sh` sair não-zero), 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`, `mktemp` falhou), 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-455.sh AC-001
echo "exit: $?"

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

Diagnóstico de falha

AUR-455/AC-001/behavior-missing:entrypoint_missing:<caminho> — um arquivo ou diretório que demo.sh ou os lanes precisam não está presente no worktree materializado; confira paths/read_paths do card.
AUR-455/AC-001/behavior-missing:demo.sh output never contained the <label> marker — demo.sh rodou (exit 0) mas um dos quatro passos não produziu a saída documentada; um dos comandos reais mudou de comportamento sem a documentação acompanhar.
AUR-455/AC-001/behavior-missing:demo.sh exited <n> — demo.sh parou de rodar fora de uma mutação deliberada; normalmente um comando documentado quebrou de verdade.
AUR-455/AC-001/MUT-001 — esperado apenas durante a própria execução da mutação de ceticismo; fora dela, indica que a flag --seguranca (ou outro comando documentado) quebrou de verdade no candidato.
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 .board/cards/ready/AUR-455.md nomeia os seletores TestAUR445, IntegrationAUR445 e E2EAUR445 — resíduo do template copiado de AUR-445 (mesmo office, mesmo formato de card). Esses símbolos já existem em tests/unit/AUR-445.go e tests/integration/AUR-445.go, no mesmo pacote (unit, integration); declará-los de novo em tests/unit/AUR-455.go / tests/integration/AUR-455.go colidiria e quebraria qualquer go build/go test que compile os dois arquivos juntos. Este card usa os nomes correspondentes ao seu próprio ID — TestAUR455, IntegrationAUR455, E2EAUR455 — mantendo o mesmo padrão de nomenclatura que todo outro card do office já segue (docs/specs/AUR-445.md registra a mesma nota sobre seu próprio resíduo, herdado de AUR-428).