Auth and role issues have their own list on Auth and roles.

​
Checks and GitHub

First: wait 2 minutes — the cron sweep runs every minute and evaluation is asynchronous by design. Then: tail the worker (cd apps/mcp && npx wrangler tail) and re-trigger by closing/reopening the PR. If you see webhook for unclaimed installation <id> … ignored, the installation isn’t linked to an org: check codex.github_installations for that installation_id. Fix by connecting GitHub from Settings → Integrations while signed into the org that should own it. One installation can only be claimed by one org (DB-unique); the connect flow refuses to steal an installation another org holds, with a clear error.
Historical failure (pre 2026-08-11): an in_progress check run orphaned when a deploy evicted the isolate. Current code creates check runs already-completed, so a spinner today means GitHub is showing a queued check the ruleset requires but the App hasn’t reported — same diagnosis path as “no check appears”.
  1. Confirm the statement is enforced (approved = advisory, does not block).
  2. Check the org’s model: Settings → LLM. Weak models miss real findings — openai/gpt-4.1 is the validated reference; Anthropic-via-OpenRouter breaks the JSON response format entirely.
  3. Replay the exact input: gh pr diff <n> piped to /v1/check (see Smoke tests) — statements_considered tells you which org’s corpus the key saw; a surprising number means the wrong key.
  4. Remember diff-only limits: a diff cannot prove a missing OpenAPI entry; repo-tree evidence helps, full scans close the rest.
The check only blocks if a ruleset/branch protection requires it. On GitHub’s free plan, required checks need a public repo (private repos 403 with “Upgrade to Pro”). Verify the repo has a ruleset requiring PolicyCodex pinned to integration 4542396.
Per-repo cooldown. Wait a few minutes, or (internal estates only) delete the org’s pending_scans row to clear the cooldown.
Confirm the file types are scannable (code + markdown extensions, 400-file/55k-char caps) and that the scan-mode prompt is in effect — a regression to the diff-framed prompt makes scans blind. Probe with the known-bad file contents via /v1/check and compare against the eval suite.

​
Authoring and extraction

The current revision’s body_md is missing its YAML frontmatter block — body_md must hold the full composed document. Happens when content was seeded/imported wrongly. Fix: paste the frontmatter block back into the editor and save (creates a complete new revision); fix the seeding source too.
Approval survives extraction failure by design. Common causes: free-plan org without llm_extraction (HTTP 402 from the function) → upgrade or expect manual statements; LLM output rejected by schema (rare since synonym normalization — check the function logs in the Supabase dashboard). Re-approving the RFC re-runs extraction.
The importer converts and validates but never auto-approves; Zod errors are shown verbatim. Most common: non-ISO created dates and RFC 2119 synonym levels in hand-written JSON.

​
Platform

Almost always a deploy-matrix miss: the artifact that owns the behaviour wasn’t redeployed — especially packages/core changes, which require redeploying every consumer, and Edge Functions, which deploy one-by-one. Check the deploy matrix. For the worker, verify secrets survived: npx wrangler secret list must show 8; the GitHub trio has vanished after dashboard changes before, and a missing MODEL silently degrades /v1/check.
Pages custom domains can lag a few seconds after a deployment reports Active. Confirm with the asset-hash probe in Environments before escalating.