ci(docs-truth): fail fast when the org read token is missing or unscoped

[mindburnlabs]

Why

A reusable workflow's secrets: required: true only validates that the caller declared the key — not that a value arrived, nor that it can read anything. So every token problem surfaces two layers downstream, inside actions/checkout, wearing the wrong error message:

Actual cause	What the log says
Secret deleted / not visible to the repo	Input required and not supplied: token
Token present but under-scoped	remote: Write access to repository not granted. → 403

Both read as checkout bugs. That ambiguity is most of what made HELM-311 expensive:

• 2026-07-16 — an org-wide sweep deleted MINDBURN_ORG_READ_TOKEN. Docs Truth went red on main for five days, and the error pointed at actions/checkout rather than at a missing secret. The gate also never produced a report, so the orphan-ledger comment step logged "nothing to comment on" — the gate looked broken rather than unconfigured.
• 2026-07-21 — the secret was restored with a value lacking repo access. The error changed to a bare 403, still inside checkout, and still not naming the token.

What this does

Probes the token once, before the first checkout, and names the real cause — distinguishing empty, 401 (invalid/expired), 403 (valid but insufficient scope), and 404 (no access to that repo).

Roughly 15 lines, no new dependencies, no new permissions. The subject repo goes in via env: rather than being interpolated into the run: block.

Rollout

Callers pin this workflow by SHA, so nothing changes for them until each repin — the guard lands inert and arrives per caller. Note main here is already ahead of the f609d37a most callers pin; four different pinned versions are live across the nine callers, which is worth collapsing separately.

Verification

The failure it catches is live right now: six callers (mindburn-infra, docs_for_team, homebrew-tap, gitops-platform, helm-ai-enterprise, helm-agent-integrations) still reference the broken MINDBURN_ORG_READ_TOKEN. Repinning any one of them to this commit should surface a named token error instead of a checkout error.

Refs HELM-311, HELM-41.

🤖 Generated with Claude Code

[strix-security]

Strix is installed on this repository, but we couldn't run this PR security review because this workspace's trial has ended. Add a card to resume code reviews here.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[github-actions]

Docs Truth: missing_ledger_row — 1 file(s) need ledger rows

Tracked markdown in .github has no matching row in the org ledger
(Mindburn-Labs/docs/audit/markdown-estate-ledger.csv). This gate will stay
red on main after merge until the rows are added there.

Files that need ledger rows

• docs/adr/2026-07-18-phase1-ci-authority.md

Fix — open a small PR against Mindburn-Labs/docs

Append these rows to audit/markdown-estate-ledger.csv (schema: repo,path,status,owner,truth_kind,source_refs,truth_gate,public_surface,superseded_by,notes):

".github","docs/adr/2026-07-18-phase1-ci-authority.md","active",".github","repo_docs",".github:Makefile;.github:catalog-info.yaml;.github:agent.yaml;.github-repo:repo-manifest.yaml","","false","","initial docs-truth inventory row generated from tracked markdown; source_refs name owning repo evidence or gates"

Adjust source_refs if .github does not have all four of Makefile, catalog-info.yaml, agent.yaml, and the .github-repo:repo-manifest.yaml entry — grep neighboring .github, rows in the CSV to see the canonical set for this repo. Keep the new rows alphabetically ordered inside the .github, block.

Once the ledger PR merges, re-run this job (gh run rerun 29812506750 --repo Mindburn-Labs/.github --failed) to turn this gate green.

_{Auto-generated by Mindburn-Labs/.github/.github/workflows/docs-truth-public.yml. Longer-term refactor of the two-repo ledger flow is tracked in HELM-41.}