Context:
Identified during work on #11
PR: #12
Description:
The documentation gate added in #12 runs as TestRepositoryDocumentation, inside the existing go test -race -count=1 ./... step of both workflows. That is sufficient to fail the build, but it gives no step-level signal: a dead Markdown link and a genuine data race both surface as the same red "Test with race detector" step, so the collapsed checks list cannot distinguish them without opening the log.
Two workflow edits were prepared and reviewed in #12 but could not be pushed — the charles-fineman bot token carries gist, read:org, and repo scopes but not workflow, so GitHub rejects any push touching .github/workflows/:
! [remote rejected] issue-11 -> issue-11 (refusing to allow an OAuth App to
create or update workflow `.github/workflows/ci.yml` without `workflow` scope)
The two changes, ready to apply to both ci.yml and release.yml:
- A named step, placed before
Test with race detector so a documentation failure fails under its own name rather than aborting the run inside the race step:
- name: Check repository documentation
run: go test -run '^TestRepositoryDocumentation$' -v ./internal/docscheck/
- A comment above the
Self-check fixture documents step, because that step's exact shape is now load-bearing for a check that lives in a different file entirely — a maintainer converting run: | to run: >, or moving the block into a composite action, would break internal/docscheck with no local hint as to why:
# The exact shape of this step is load-bearing: internal/docscheck
# parses it as indented text to assert that AGENTS.md and both
# workflows run the same commands. Keep the "- name:" key, the
# "run: |" block, and one command per line.Rationale:
Deferred from #12 for a credential limitation, not a design disagreement. The gate is fully functional without either change; both are diagnosability improvements. The DevOps review of #12 rated the named step "important, nice-to-have, not blocking" and the comment "minor".
Note that AGENTS.md and CHANGELOG.md in #12 were corrected to describe the gate as running inside the race-detector step, so the prose is accurate as merged. Applying change 1 means updating both to mention the new step, or internal/docscheck will be describing CI incorrectly — exactly the drift class it exists to prevent.
Reference:
internal/docscheck/repository_test.go — TestRepositoryDocumentation.github/workflows/ci.yml, .github/workflows/release.yml — the Self-check fixture documents stepAGENTS.md — "Documentation checks" subsection
Acceptance Criteria:
Context:
Identified during work on #11
PR: #12
Description:
The documentation gate added in #12 runs as
TestRepositoryDocumentation, inside the existinggo test -race -count=1 ./...step of both workflows. That is sufficient to fail the build, but it gives no step-level signal: a dead Markdown link and a genuine data race both surface as the same red "Test with race detector" step, so the collapsed checks list cannot distinguish them without opening the log.Two workflow edits were prepared and reviewed in #12 but could not be pushed — the
charles-finemanbot token carriesgist,read:org, andreposcopes but notworkflow, so GitHub rejects any push touching.github/workflows/:The two changes, ready to apply to both
ci.ymlandrelease.yml:Test with race detectorso a documentation failure fails under its own name rather than aborting the run inside the race step:Self-check fixture documentsstep, because that step's exact shape is now load-bearing for a check that lives in a different file entirely — a maintainer convertingrun: |torun: >, or moving the block into a composite action, would breakinternal/docscheckwith no local hint as to why:Rationale:
Deferred from #12 for a credential limitation, not a design disagreement. The gate is fully functional without either change; both are diagnosability improvements. The DevOps review of #12 rated the named step "important, nice-to-have, not blocking" and the comment "minor".
Note that
AGENTS.mdandCHANGELOG.mdin #12 were corrected to describe the gate as running inside the race-detector step, so the prose is accurate as merged. Applying change 1 means updating both to mention the new step, orinternal/docscheckwill be describing CI incorrectly — exactly the drift class it exists to prevent.Reference:
internal/docscheck/repository_test.go—TestRepositoryDocumentation.github/workflows/ci.yml,.github/workflows/release.yml— theSelf-check fixture documentsstepAGENTS.md— "Documentation checks" subsectionAcceptance Criteria:
TestRepositoryDocumentationas a distinctly named step before the umbrella test stepSelf-check fixture documentsAGENTS.mdandCHANGELOG.mddescribe the new step accuratelygo test ./internal/docscheck/still passes, including the self-check command-list comparison