docs(identity): GITHUB_TOKEN vs GH_TOKEN precedence (H-13) + test nit cleanup

[sabbour]

Summary

Documents H-13 from the identity hardening roadmap: the precedence between GITHUB_TOKEN and GH_TOKEN environment variables in Squad agents and CI/CD workflows.

Changes

• New file: docs/identity/token-precedence.md (~300 lines)

  • Explains what each variable is used for
  • Documents how Squad SDK picks between them in different contexts
  • Includes decision tables and troubleshooting
  • Real-world scenarios (Actions + Squad, stored credentials, etc.)

• Test nit fix: Remove unused withRetry import from test/identity/retry.test.ts (flagged in PR feat(identity): retry resilience + PR22 nits (H-03) #23 review)

• Changeset: docs-only patch (no code changes)

Testing

• npx vitest run test/identity/retry.test.ts ✅ all 12 tests pass
• npm run build ✅ both SDK and CLI compile cleanly

Related

• Closes H-13 from docs/proposals/identity-hardening-roadmap-2026-04-20.md
• PR feat(identity): retry resilience + PR22 nits (H-03) #23 review nit (unused import)

[sabbour]

🔄 Request Changes — Flight (Lead)

1 blocker, 2 nits. Full review: docs/reviews/pr-24-token-precedence-review-2026-04-21.md

Blocker: B-1 — Scenario 3 precedence list is factually wrong

The doc's Scenario 3 claims gh CLI precedence is:

1. GH_TOKEN (if non-empty)
2. Stored gh auth credentials  ← WRONG position
3. GITHUB_TOKEN (if set)       ← WRONG position

Per official gh docs, the real order is:

1. GH_TOKEN (if non-empty)
2. GITHUB_TOKEN (if set)       ← both env vars beat stored auth
3. Stored gh auth credentials

The rest of the doc (Actions Context §2.3, decision table) already has this right — only Scenario 3's explicit list is inverted. Swap items 2 and 3 to fix.

Nits (non-blocking)

• N-1: "Cannot be explicitly set by users in Actions" is imprecise — users can override GITHUB_TOKEN via workflow permissions: or step env:.
• N-2: Summary table lists "Stored gh auth" as primary for local dev — add "(when no env vars set)" qualifier.

Everything else ✅

Code verification (spawn.ts, exec.ts, tokens.ts) matches doc claims. Changeset name correct (@bradygaster/squad-cli: patch). withRetry import removal confirmed. squad identity explain reference verified. Decision table accurate. Great doc overall — fix the one list and ship it.

[sabbour]

FIDO — Review fixes applied (commit abd897d4)

B-1 (blocker) ✅ Fixed: Scenario 3's precedence list was inverted. Corrected to match official gh CLI docs and the rest of the document:

1. GH_TOKEN env var (if non-empty)   ← wins
2. GITHUB_TOKEN env var (if set)     ← was incorrectly listed 3rd
3. Stored gh auth credentials        ← was incorrectly listed 2nd

N-1 ✅ Addressed: Softened the GITHUB_TOKEN bullet — now reads: "Automatically injected by Actions runners; can be overridden via the permissions: key or a step-level env: variable, but rarely needs to be."

N-2 ✅ Addressed: Summary table "Local development" primary token now reads "Stored gh auth (when no env vars set)" to be accurate for power users.

Only docs/identity/token-precedence.md was modified. Ready for Flight's re-review.

[sabbour]

✅ Re-review: APPROVE (Flight)

All three fixes from abd897d verified:

Item	Status	Detail
B-1	✅ Fixed	Scenario 3 precedence corrected → GH_TOKEN > GITHUB_TOKEN > stored gh auth (matches official gh CLI docs)
N-1	✅ Fixed	GITHUB_TOKEN wording softened — now acknowledges permissions:/env: overrides
N-2	✅ Fixed	Summary table Local dev row clarified with '(when no env vars set)'

Scope check: Commit touches only docs/identity/token-precedence.md (4+/4−). No other files modified.

Ship it. 🚀

— Flight