AUR-428 — Publicar as páginas copiando um workflow que funciona

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

O que este card entrega

O usuário copia .github/workflows/examples/documentation.yml para o repositório dele como .github/workflows/documentation.yml, sem editar nada, e a documentação sai publicada no GitHub Pages. Três artefatos tornam isso possível:

O workflow de exemplo referencia a action por tag semver publicável (Mpaape/AurumCode@v1), nunca por um SHA de commit local — um SHA do repositório de trabalho não é contrato publicado, e um branch mutável (@main) deixaria um push futuro trocar o que executa no CI do usuário.
LICENSE existe na raiz (MIT). O workflow copiado executa o código deste repositório dentro do CI do usuário; a tag só é publicável sobre conteúdo licenciado.
O manifesto de permissões declara o mínimo que o deploy do Pages exige: contents: read no nível do workflow e, somente no job que publica, pages: write + id-token: write, com environment: github-pages.

Comando

No repositório do usuário, depois de copiar o arquivo (e com Settings → Pages → Source = "GitHub Actions"):

mkdir -p .github/workflows
curl -fsSL https://raw.githubusercontent.com/Mpaape/AurumCode/v1/.github/workflows/examples/documentation.yml \
  -o .github/workflows/documentation.yml   # ou copie o arquivo manualmente
git add .github/workflows/documentation.yml && git commit -m "docs: AurumCode Pages workflow" && git push
gh workflow run documentation.yml          # dispara via workflow_dispatch

Nenhum segredo é necessário: o bloco de LLM é opcional e fica comentado no exemplo. gh workflow run documentation.yml funciona porque o exemplo declara workflow_dispatch e o nome do arquivo é preservado na cópia.

Opções (via workflow_dispatch input):

Input	Default	Efeito
`extra-toolchains`	`''`	Toolchains extras de extração (`javascript`, `python`, `csharp`, `cpp`); valor desconhecido derruba a execução em vez de pular linguagem silenciosamente.

Aceite hermético (o que o sandbox prova — e o que não prova)

O aceite roda em bootstrap-readonly-v1 (sem rede, rootfs read-only). Ele não pode publicar uma tag real no GitHub nem observar um deploy do Pages ao vivo — isso é o AUR-429, que usa um driver simulado pelo mesmo motivo. O aceite deste card é verificação estática do manifesto copiado, com parse YAML real (árvore de nós percorrida estruturalmente, nunca grep cego):

./.board/bin/oci-run --profile bootstrap-readonly-v1 --card AUR-428

O aceite (tests/acceptance/AUR-428.sh, seletor default AC-001) executa:

Lane	Seletor	O que afirma
Unit	`TestAUR428` (`tests/unit/AUR-428.go`)	O documento do workflow parseia; `workflow_dispatch` existe; `contents: read` no topo; o job de deploy declara `pages: write`, `id-token: write`, `environment: github-pages`; o `uses` tem forma `owner/repo@vN[.N[.N]]` (rejeita SHA de 40 hex e branch); `publish: 'pages'`.
Integration	`IntegrationAUR428` (`tests/integration/AUR-428.go`)	O `owner/repo` do `uses` é exatamente o que `go.mod` declara (`Mpaape/AurumCode`); toda chave em `with:` é input declarado em `action.yml`; `action.yml` é composite e declara `publish`; `LICENSE` existe com o grant MIT real.
E2E	`E2EAUR428` (`tests/e2e/AUR-428.sh`)	Copia o exemplo byte a byte para um repositório-usuário de rascunho, valida a cópia com parse real, roda duas vezes e exige saída byte-idêntica (cláusula de repetição do AC-001).
Spec	—	Este arquivo existe e nomeia a tag `v1`.

Contrato de rótulos e exit codes (todas as lanes):

Situação	Rótulo em stderr	Exit
Comportamento ausente (SHA local, LICENSE ausente, permissão faltando, `publish` errado)	`AUR-428/AC-001/behavior-missing`	1
Referência mutada/inexistente (repo errado, ref que não é tag semver, input que a action não declara)	`AUR-428/AC-001/MUT-001`	1 (validador E2E: 3 → mapeado para 1)
Infraestrutura ausente (sem `go`, sem module cache, build do validador)	`AUR-428/AC-001/infrastructure/*`	69
Seletor desconhecido	`AUR-428/AC-001/unknown-selector`	64
Nominal	JSON `{"result":"pass",...}` em stdout	0

MUT-001 (mutação cética)

Apontar o workflow para uma referência inexistente — outro repositório, um branch, uma ref que não é tag semver — faz o mesmo accept sair não-zero registrando AUR-428/AC-001/MUT-001 em stderr; restaurar o arquivo reproduz o GREEN exato. O RED original (pré-implementação) era o pin em SHA local + ausência de LICENSE, registrado como AUR-428/AC-001/behavior-missing.

Limite honesto da verificação estática

Uma ref com forma de tag semver que simplesmente não foi publicada (ex.: @v999) passa na verificação estática: existência de tag só é observável com rede. Esse resíduo é aceito pela "Restricao medida" do card e coberto ao vivo pelo fluxo do AUR-429.

Publicar a tag `v1` é ação humana

O aceite hermético não publica nada. Para o workflow copiado resolver, o mantenedor precisa — uma única vez, fora do CI, com a identidade humana já configurada — criar e publicar a tag:

git tag -a v1 -m "AurumCode action v1"
git push origin v1

Releases seguintes: mover a major tag (git tag -fa v1 <novo sha> + git push --force origin v1) ou publicar v1.N.N adicionais. Enquanto a tag não existir no GitHub, o run do usuário falha em uses: com "unable to resolve action" — isso é diagnóstico de tag não publicada, não defeito do workflow.

Diagnóstico de falha (lado do usuário)

Sintoma no run	Causa	Correção
`unable to resolve action Mpaape/AurumCode@v1`	Tag `v1` ainda não publicada	Ação humana acima.
Deploy recusado com erro de permissão/OIDC	Fork/cópia removeu `pages: write`/`id-token: write`	Restaurar o bloco `permissions` do job.
`Get Pages site failed` / 404 no deploy	Settings → Pages → Source não é "GitHub Actions"	Ajustar a fonte do Pages (ver PAGES_SETUP.md).
Site publica mas links quebram	`base-path` divergente do tipo de site	Ver a documentação do input `base-path` em `action.yml`.

Fora de escopo / notas

Execução ao vivo de gh workflow run e verificação do Pages publicado: AUR-429 (driver simulado; rede negada aqui).
README.md e ACTION_USAGE.md ainda dizem "No LICENSE file is present"; esses arquivos estão fora dos paths deste card e a atualização fica para um card próprio.
Dos demais exemplos em .github/workflows/examples/, qa-testing.yml e all-pipelines.yml continuam pinados por SHA (Mpaape/AurumCode@6f584b5987c12399bc7a85571dad4a81e28005c8); este card cobre apenas documentation.yml, o único citado pelo seu Outcome. code-review.yml não está mais nesse grupo: o AUR-440 o repinou para a tag v1 (ref: v1 no passo "Checkout the AurumCode release" de .github/workflows/examples/code-review.yml) — ver docs/specs/AUR-440.md.