git:20261012.8e6b67e to git:20261016.002ddc5

# AI-Rig — Project-Only Agent Instructions

<!-- Scope: maintaining this repository only; never shipped. Policy meant for every project or install goes into the plugin that ships it, never here. -->

<!-- policy-sibling-sync: CLAUDE.md, AGENTS.md, plugins/AGENTS.md, plugins/CLAUDE.md -->

- Any policy change in one listed instruction file must trigger a relevance review of every other listed file before completion.

- Synchronize applicable shared policy in either direction; preserve intentional agent-specific differences and record when no counterpart change is needed.

## Instruction Layering

- Repository-wide policy belongs in this top-level file.

- Lower-scope instruction files inherit it and must add only narrower rules or explicit exceptions, never repeat the same policy; when a top-level policy changes, review lower layers for conflicts or obsolete duplication rather than copying the new text into them.

- **This file is for maintaining this repository only and is never shipped** — plugin users never see it. Anything general, meant for every project or every install, must be distributed in the plugin that ships it (the Codex Rig global template [plugins/codex-rig/assets/AGENTS.md](plugins/codex-rig/assets/AGENTS.md) or `plugins/codex-rig/shared/`; foundry rules for Claude), never added here. This file holds only this repository's own conventions and restates none of the shipped baseline.

## Shipped Global Baseline

These generic rules ship in the global template (section names as in that file) and are not restated here: core principles and focused delegation (§Execution Discipline, §Subagent Spawn Rules, §Code Quality), internal record types (packaged `shared/global-baseline-details.md` §"Code standard details", **Internal records**), docstring opening line (§Docstring Style Resolution), Multi-OS Executables, Markdown Authoring, the lossless instruction compression gate (§Scope And Layering), pytest parametrization, marker discipline and xdist isolation (§Testing), pre-commit hooks over bare lint tools (§Code Quality, **Project hygiene**), benchmark isolation (§Testing), plan isolation (§Work Handover) and Notebook Authoring. Sections below add only this repository's specifics. This repository supports Linux, macOS, and native Windows, so the conditional Multi-OS Executables rule always applies here.

## Edit Scope

- All edits stay inside this project directory. Never edit `$CODEX_HOME` or `~/.claude/` directly — both are install targets populated from this checkout, and a hand-edit there is overwritten on the next sync.

- Permitted roots: `.codex/` (Codex config, skills, session policy), `.claude/settings.json` and `.claude/settings.local.json`, `plugins/*/{agents,skills,rules,hooks,bin}/`.

- The Makefile installs from the pushed GitHub remote, not the local working tree: commit and push first, then `make sync-claude` or `make sync-codex`. Running it against uncommitted work silently installs the previous state.

- Never initiate propagation mid-task; it is a deliberate human-triggered step.

## Version Continuity

This repository's own convention, not shipped policy: other projects commonly decide SemVer at release time rather than per commit.

- Before changing any shipped version or serialized artifact schema, identify its version family and read that family's value from the last committed `HEAD`; do not use an earlier uncommitted edit or an unrelated nested version as the baseline.

- A changed integer schema advances exactly one step from its committed current value. A new version family starts at 1. Keep older versions only as explicitly labeled historical readers; several revisions before the next commit still produce one bump from `HEAD`.

- Check the proposed value against `HEAD` before handoff and record the comparison with the affected verification. Reject skipped or downgraded versions. Plugin release versions also follow the separate SemVer pre-bump gate in [plugins/AGENTS.md](plugins/AGENTS.md).

## Interpreter Commands — Fix the Launcher, Not the Call Site

Claude recipe commands retain `python` identities used by allow rules and blueprint digests. Codex does not add plugin `bin/` to shell PATH: its packaged helper recipes explicitly use the plugin's portable launcher, a narrow exception to the fixed-command rule.

- Preserve explicit project interpreters, managed-environment commands, and recorded command identities. Never add per-call interpreter selection or repeat interpreter-selection instructions across skills.

- Portable launchers validate the runtime before executing the workload, preserve arguments and exit status, and never retry a failed workload with another interpreter.

- Fix each launch layer at its owning boundary:

| Launch layer | Mechanism |

| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |

| Claude Bash tool | Byte-identical plugin `bin/python` fallback, propagated by `propagate_shared.py`; real system `python` keeps its PATH precedence. |

| Claude hooks | Plugin-owned hook launchers; JavaScript hooks retain their existing Node probe and SessionStart diagnostic. |

| Codex helper recipes and hooks | Explicit plugin `bin/python` on POSIX or `bin/python.cmd` on native Windows; quote paths for the host shell. |

| Codex MCP servers | Fixed `python` executable prerequisite, checked during setup; no global shim installation or automatic PATH modification. |

- Guards: `tests/test_hook_interpreter_fallback.py` and `plugins/codex-rig/tests/packaging/test_sync_codex.py`. Extend them when adding a launch layer.

## Adversarial Convergence Loop

The loop ships in the global template. In this repository read the source-tree copy [plugins/codex-rig/shared/adversarial-loop.md](plugins/codex-rig/shared/adversarial-loop.md) directly before every independent review → authorized-fix cycle: the installed copy lags the working tree until it is published and synced.

## Lossless Instruction Compression Handover Gate

The gate ships in the global template (§Scope And Layering). Repository specifics: this repository's calibration gate (`plugins/codex-rig/runtime/calibration/run.py --layout plugin`) is mandatory; save the byte-exact backup under `.codex/caveman-compress/backups/`, and plugin-specific authoring, installability, cross-reference, versioning, and verification rules live in [plugins/AGENTS.md](plugins/AGENTS.md).

## Test Selection

Generic marker discipline ships in the global template (§Testing). This repository's vocabulary and commands:

- Use semantic markers: `integration` for real component interactions; `installed_plugin` for tests runnable without repository context; `packaging` for build/install/payload contracts; `live` for real external services or credentials.

- `installed_plugin` does not imply `packaging`. A `live` test also carries `integration` and retains explicit opt-in guards; selection never authorizes network or paid execution. Capability probes remain separate.

- From the repository root, use `.venv/bin/python -m pytest -m installed_plugin` or `.venv/bin/python -m pytest -m "packaging and not live"`; omit paths for project-wide discovery. On Windows use `.venv\Scripts\python.exe`.

## Project Workflow

- Python minimum: 3.10. The repository root is an environment anchor, not an installable package.

- Bootstrap test tooling with `uv sync --only-group test`; benchmark-only dependencies use `uv sync --only-group bench`.

- Run focused tests with `.venv/bin/python -m pytest <paths>` and broaden to the affected suite before completion.

- Broad local runs go parallel: `.venv/bin/python -m pytest -n 4 <paths>` (pytest-xdist, already in the test group). Measured on the full suite: 11556 tests in ~5 min at `-n 4`, several times faster than the same run serial. Use `-n 4` for any run wide enough to be worth waiting on; keep focused single-file runs serial, where worker startup costs more than it saves.

- Coverage tracing is opt-in: CI passes the `--cov=<plugin>/bin` list (see `.github/workflows/ci-tests.yml`), and a local run measures only when you add `--cov=<path>` with `--cov-report=term-missing`. Keep sources out of `[tool.coverage]`: it also configures tests that start their own coverage run. Untraced is the default because tracing slows every test, most on Windows.

- The generic xdist isolation rule ships in the global template (§Testing); in this repository the usual shared machine-global state is a `${TMPDIR}` sentinel without its `-${CSID}` suffix.

- Lint/format edits via the pinned pre-commit hooks (generic rule: global template §Code Quality, **Project hygiene**): `pre-commit run ruff-check --files <changed-python-paths>`, `pre-commit run ruff-format --files <changed-python-paths>`, and `pre-commit run mdformat --files <changed-markdown-paths>`; direct `ruff` or `mdformat` invocation drifts from the version/config pinned in `.pre-commit-config.yaml`. Use `pre-commit run --all-files` only when the task requires the repository-wide gate.

- Release and build entry points are plugin-specific; follow `plugins/AGENTS.md` and the owning plugin's scripts and README. Remote publication remains human-owned.