codefa: Instructions file for Codex

AGENTIC DIRECTIVE

Keep AGENTS.md and CLAUDE.md identical.

CODING ENVIRONMENT

• Install astral uv using "curl -LsSf https://astral.sh/uv/install.sh | sh" if not already installed and if already installed then update it to the latest version
• Install Python 3.14.0 stable using uv python install 3.14.0 if not already installed (requires uv >=0.9; see [tool.uv] required-version in pyproject.toml)
• Always use uv run to run files instead of the global python command.
• Current uv ruff formatter is set to py314 which has supports multiple exception types without paranthesis (except TypeError, ValueError:)
• Read .env.example for environment variables.
• All CI checks must pass; failing checks block merge.
• Add tests for new changes (including edge cases).
• Before pushing, prefer ./scripts/ci.sh (macOS/Linux) or .\scripts\ci.ps1 (Windows) to run the local CI sequence; requires uv on PATH. The local scripts run Ruff in repair mode (ruff format, then ruff check --fix) before type checking and tests.
• Use --only / --skip (PowerShell: -Only / -Skip) to run a subset when iterating; use --dry-run to print commands without running them.
• GitHub CI remains check-only for Ruff (ruff format --check, ruff check) so branch protection verifies committed code.
• Fall back to individual repair commands when debugging local failures: uv run ruff format, uv run ruff check --fix, uv run ty check, uv run pytest -v --tb=short. Use GitHub-style checks only when verifying enforcement locally: uv run ruff format --check, uv run ruff check.
• Do not add # type: ignore or # ty: ignore; fix the underlying type issue.
• Do not add from __future__ import annotations; Python 3.14 native lazy annotations are the project standard.
• All 5 check IDs are represented in scripts/ci.sh / scripts/ci.ps1 and enforced in tests.yml on push/merge (parallel jobs: suppression grep, ruff-format, ruff-check, ty, pytest).
• GitHub CI runs on push, pull_request, and merge_group so required checks validate merge queue candidates before they land.
• Repository protection should use rulesets: a non-bypassable main integrity ruleset requires pull requests, merge queue, required checks, and blocks direct/force pushes to main; a separate review ruleset may allow Foshati/admins to bypass review only.
• Required status checks: set required status checks to all of those statuses (e.g. Ban suppressions and legacy annotations, ruff-format, ruff-check, ty, pytest—use the exact labels GitHub shows, which may be prefixed with CI /). Remove ci from required checks if it was previously added for the old gate job.