mcp-accessibility-scanner: Skill for Codex

Pre-push review: catch Codex findings before they reach GitHub

This repo's PRs are reviewed by the OpenAI Codex bot. An analysis of all 179 inline findings it left across ~50 PRs shows the same defect classes recurring again and again. Almost every one of them was detectable from the diff alone — which means you can catch them locally.

Work through the checklist below against your actual diff — everything that differs from the default branch (git diff origin/main...HEAD, or git diff main...HEAD in a checkout with no origin remote; if neither ref exists, diff against the merge base of whatever ref tracks the default branch) plus any staged and unstaged changes. Don't treat it as a form to tick off: for each section, ask "does my change touch this territory?" — if yes, actively hunt for the failure mode described. Fix what you find, then run the final gate.

For concrete examples of every pattern (real findings with file/PR references), read references/codex-findings-catalog.md. Consult it whenever a section below feels abstract or you want to see what the failure looks like in practice.

1. Trace every option end-to-end — no silent no-ops

The single most common Codex finding (~20 occurrences): a flag, config field, or env var is accepted but silently ignored on some code path. --storage-state validated at startup but dropped by the VS Code/extension/CDP context factories; --mobile accepted with remoteEndpoint/cdpLaunch/--extension where context options are never applied; a configurable timeout that the SDK's own default overrides; a progress token forwarded but notifications never bridged through the proxy backend.

If your change adds or touches any option, setting, or env var:

• Enumerate every consumer path: launch modes (persistent, --isolated, remoteEndpoint, cdpEndpoint, cdpLaunch, --extension, --vscode), transports (stdio, HTTP), and the proxy backend. Grep for where the value is read.
• For each path, the option must be either applied or rejected with a clear error at startup. "Accepted but ignored" is never acceptable — the user believes they got the behavior (e.g. runs an "authenticated" audit that is actually anonymous).
• Validate against the merged config (CLI + config file + env), not just cliOptions — Codex caught mobile validation that only inspected the CLI flag while the config file smuggled in a CDP endpoint.
• Check the value is honored at runtime too: does a later runtime update (e.g. browser_default_timeout) actually reach the code that reads the config snapshot?
• Env var parsing: a present-but-blank value must not become 0/{} and change semantics (blank PING_TIMEOUT disabled the heartbeat entirely). Values containing commas/colons must survive parsing (comma-splitting broke comma-valued headers).
• Consistency between what you advertise and what you enforce: the server printed a 0.0.0.0 URL that its own Host-header allowlist then rejected with 403.