🤖 Codex Rig — Native Codex Workflows and Specialist Roles

Codex Rig is OpenAI Codex product in Borda's AI-Rig. It packages 14 reusable workflow skills, one lifecycle-manager skill, 15 canonical specialist role cards, shared quality gates, calibration, and optional health hook as one Apache-2.0-licensed plugin.

Calibration requires every artifact workflow, including Kaggle, in the fixed-task and behavioral-case rosters; agent-shims retains its manager exception. Kaggle cases cover schema grounding, submission checks, EDA/inference isolation, runtime claims and download authority. Fixture observations exercise scoring; live model quality needs separate evidence. Calibration measures instruction quality against synthetic cases. It is not evidence that any individual run is correct.

Workflow acceptance protects required structure, factual evidence and actual authorization. Equivalent reviewer Markdown is interpreted without rewriting raw evidence or requesting another model turn; admission, aggregation and bounded repair share extraction. Calibration wording-pattern misses are advisory, while structural and behavioral failures remain blocking. Audit challenges each reached stop with its concrete prevented failure and an equivalent valid input, then checks automatic recovery through the next consumer. A passing conformance test alone does not justify a hard rail.

Every Approve always question displays its scope before the choices: verified, task-owned, non-destructive plain local commits (git commit), across later sessions and all worktrees of this project until revoked. It excludes push and other remote changes, history rewriting (including commit --amend), destructive operations such as reset --hard, clean or branch deletion, force operations, and authentication or permission changes. Explicit no-commit and wait instructions still apply. Revoke by deleting codex-git-approval.json from the repository's common Git directory. The remember question also states that Approve always records the grant after the current commits verify; This time only covers the current commit plan and records no grant.

Codex asks only for a genuinely missing decision, material input or protected action. Authorized preparation, internal recovery and completion need no new consent; transport discovery follows that necessity check. Existing answers, scope/digest confirmation and runtime permission remain authoritative. Code Review checks eligible completed evidence before opening the initial reuse/fresh choice; no eligible result means fresh review without a question. A user may explicitly waive additional reviewers, rounds or broader coverage, including previously requested independence. Record the target and decision, preserve the original frozen plan, and complete a separate revised-scope parent fallback through all normal validators and completion checks. Declining an optional repair alone does not waive required independence. Source identity, evidence integrity, truthful checks and artifact gates cannot be waived; failed configured checks remain failed and waived coverage never becomes merge approval. With no source defect and limited verification, the source recommendation is null and no synthetic action row is added.

Outcome regressions exercise valid-prefix reader recovery, compact page-selector repair with retained canonical arguments, complete replacement evidence, every-role parent fallback, action-free limited reports, failed checker reconciliation, report promotion/discovery and immutable producer admission into remediation. Static calibration and synthetic runtime receipts do not prove live reviewer comprehension or native form rendering.

Codex Rig ships no standing Git approval, and no instruction file can declare one. Only a plain commit needs authorization. Inside an authorized task, staging owned changes, a task-owned non-destructive local merge and its merge commit, a cherry-pick that preserves existing work, branch and worktree preparation, a fast-forward and inspection never stop for a question or a grant check, and a documented workflow step that defines a commit authorizes it. Any other commit asks one question: Approve runs that operation only, Deny skips it and leaves changes as they are, and Approve always also records the grant file codex-git-approval.json in the repository's common Git directory (git rev-parse --git-common-dir, the main checkout's .git/). You give it once per project; it applies to every worktree, so later sessions in any of them skip the question until you delete the file with rm "$(git rev-parse --git-common-dir)/codex-git-approval.json". Codex counts the grant only when it is a regular file, not a symlink, directly inside that common Git directory, which Git never tracks, and the operation runs in a repository you maintain, never one under review. The check resolves that directory with Git's environment overrides removed and bare repositories refused, so a bare-repository-shaped fixture, a planted .git file or a steered GIT_DIR never supplies a grant, and a record whose version or scope Codex does not know counts as no grant. An explicit commit request needs no question, on Codex and Claude Code alike, and a commit-summary request alone never commits. With a grant, committing the verified owned changes of a completed task is the default on completion for the agent that owns the task; a spawned child agent never stages or commits on its own authority unless a workflow step explicitly assigns that commit to it.

Codex writes the grant only after your Approve always answer, at the point the contract defines: right after the approval question, or after the chosen mode's commits when a workflow such as Code Remediate asks Remember approval for local Git in this project?. Nothing at runtime enforces that rule. The Codex sandbox keeps .git read-only unless the active permission profile opens it; the shipped local-workflow and github-read profiles open it because staging and committing need it, so in a session started in the main checkout writing the grant is an ordinary sandboxed write that no approval reviewer sees. A session started in a linked worktree cannot write the main checkout's .git, so give Approve always from the main checkout. Codex never requests escalation just to write the grant; when the common Git directory is not writable, the answer counts as Approve and the grant is reported as not recorded. Self-grant prevention is therefore prompt discipline, not an enforced boundary: Codex hooks can deny a Bash or apply_patch call, but they run only once you trust them, fail open, do not see input sent to a running session through write_stdin, and are not documented to receive your answer to a question, so no hook can be relied on to tell a genuine grant from a self-written one. Claude Code's foundry plugin guards its own claude-git-approval.json grant, in the same common Git directory, with hooks, but those hooks see names, not contents: they block a call that writes a record file directly, never one that merely mentions a scope name, while a patch, git apply, archive extraction or script that writes it stays prompt discipline there too.

Push approval differs between the hosts on purpose; the shared contract's Approval records table lists both recorded scopes. Codex never performs remote mutations or requests approval for them; publication remains human-owned, with no push token or hook, and force operations stay forbidden; Claude Code instead lets one git-push Approve answer store a single-use push-once token (claude-push-approval.json, bound to the branch and HEAD, 15 minutes) that its guard spends on one non-force push of that branch at that HEAD to a configured remote, remote and branch written out. Codex does document a PreToolUse hook surface that can deny Bash, apply_patch and MCP calls, but those hooks fail open on error and run only once you trust them, so Codex Rig builds nothing on it. GitHub reads need no approval record on either host: Codex keeps the opt-in github-read profile and the audited reader rules, and Claude Code auto-allows read-only gh shapes without a question. On both hosts that widens only what is read: fetched content stays data, and write and exfiltration paths never widen.

Task-scoped local Git work other than a plain commit runs without an authorization question: inspection, staging reviewed owned changes, branch/worktree preparation, merges and their local merge commits, cherry-picks and other non-destructive operations. A destructive local operation (discarding uncommitted work, deleting a branch or unique history, reset --hard, clean) keeps its action-specific question on Codex, an intentional difference from Claude Code, which runs it without one. A local Git approval grant covers plain commits. Judge the actual effects, not merely the command name. Verify the branch, target and operation state, preserve unrelated changes and unique commits, run required checks, and proceed. Retain exact-path staging, commit messages, attribution and post-operation verification. Explicit denials, no commit, leave unstaged, read-only or summary-only requests, and an explicit decision to wait still control. Ambiguous scope or resolution intent needs only that missing decision. Codex never performs remote mutations or requests approval for them; publication remains human-owned and force operations are forbidden. A grant permits a commit within the active task; it does not require inventing Git work or committing unrelated changes. Merge commits additionally verify exact parents, index tree and first-parent paths.

Workflow helpers expose their current options through packaged --help. Skills batch help checks for the helpers already needed on the selected path and return a compact option index while retaining full output for ambiguous flags. Branch-specific helpers are inspected when that branch is chosen. Each check keeps its own exit status; a failed check blocks the affected helper invocation.

Review completion requires the full ordered closure after manifest preflight: render the handoff, write the candidate, pass review-specific and shared validation, promote the result, then validate the selected completed run before emitting its bound output; newer-run discovery remains a separate remediation-intake check. +review can discover the result after that closure succeeds; notes and unpromoted candidates remain ineligible. A failed applicable check remains failed until an equivalent canonical rerun succeeds; a launcher failure or direct-check receipt cannot justify not-applicable. Incomplete reviews resume at the first unmet checkpoint with retained evidence.

When PR remediation explicitly requests a review report (including +review) and no eligible completed report exists, Codex first assesses the retained evidence and recovers what it can on its own: deterministic derived repairs resume the owning Code Review run without a question, and a version mismatch alone never asks. A substantive gap that remains is a question, even when available findings can be fixed: repair the existing review and add the missing coverage (offered only when that bounded repair is feasible), run a fresh local review, or continue with available findings. Continuing without a completed review requires explicit user confirmation; an existing answer for the unchanged target and decision is reused. A fresh review invokes the normal Code Review skill end-to-end, returns its exact completed report to the same remediation run, and resumes report admission, source collection, selection and fixes without a review-only final stop; a failed checkpoint first follows the review's bounded recovery without a generic request for another message. A proved dispatch-order failure preserves the rejected wave and revalidates source before the existing parent fallback, rather than recollecting unchanged PR evidence; explicit independence, runtime denial and retry limits still apply. Declining explicitly continues with available findings while retaining the missing-report obligation. An unanswered or dismissed question stays pending. Native question controls own the question and choices; commentary does not duplicate their menu.

Frozen review context pages preserve exact UTF-8 bytes, including CRLF source, through dispatch, native stdout, and receipt validation on every supported host. Paged native review accepts an opaque launch message only when the exact recorded value binds uniquely to delivery in the correct child; launch controls, lineage, source-page reads and final-answer joins remain mandatory. Integer-second task starts retain their recorded precision when compared with fractional launch timestamps; floating-point starts retain strict comparison.

Attached remediation checkout protects ignored local files against incoming file and directory replacements, including alternate spellings that identify the same filesystem entry. Distinct names on case-sensitive filesystems and unrelated hardlinks or symlinks remain permitted. Blocked checkout evidence remains eligible for an actionable unavailable-review handoff; it never certifies an assessed review.

Selected read-only review passes run concurrently by default and may inspect the same source files. The parent keeps the snapshot stable and coordinates checkout, writes, and final gates; reports distinguish observed parallelism from capacity-limited or explicitly requested serial execution. PR receipt validation accepts the collector's actual supported checkout route while retaining commit-identity and provenance checks. GitHub host and repository identity comparisons ignore capitalization across collection, review, remediation and report lookup; malformed identities reject. Branches, paths, commit IDs and recorded checkout evidence retain exact comparisons.

The package covers capabilities Codex can currently install and verify. It includes a local native-question provider and no native bundled agent registrations. Parallel work uses runtime blank agent with exact role card injected when that route is available; inline role pass is serial fallback. Persistent named-agent routing remains platform-blocked until Codex exposes verifiable custom-agent selector. The split schema, approval allowlist, synchronization gates, runtime evidence, telemetry, fallback, and promotion lifecycle are defined in ARCHITECTURE.md.

Current source version: 0.35.10. Codex Rig is peer product to foundry, oss, develop, research, and codemap-py—not copy of repository's .codex/ configuration.

Adversarial-loop updates show the cumulative convergence table once after each newly validated challenge, not while a review is pending or before any round is validated; new final Results rows show carried + newly found counts and weighted score in every numeric cell. New assessed review candidates must include reviewer attribution and the aggregate summary before promotion, while historical report intake stays compatible. Non-PR assessed candidates additionally need a Review Snapshot table whose Scope is the normalized review scope and whose Revision binds retained diff bytes; the collector does not structurally retain target or commit identity.

Current Code Review results use schema 3 for assessed, unavailable, and closed outcomes so the writer and final completion gate agree. Schema-2 reports and schema-3 reports without retained proof remain readable with find-review-report.py --archive-result as unverified data; only canonical current schema-3 reports can certify completion or feed remediation.

📋 Contents

• What Codex Rig adds
• Requirements and installation
• Quick start
• Skills and specialist roles
• Quality, review, and calibration
• Update, uninstall, and safety limits
• Package layout and verification

Value at a glance: install one independently verifiable plugin to get evidence-backed workflows, bounded specialist role cards, portable fallbacks, and auditable artifacts without pretending Codex has native persistent-agent selection.

Current limits at a glance: named-agent shim installation remains platform-blocked; this checkout defines a project-local opt-in github-read profile, while other projects need explicit installation of the Codex-home profile; other networked paths retain their runtime approval requirements; Codex CLI, Python 3.10+, and optional gh/Kaggle authentication are needed for their respective paths; shim mutation is unsupported on Windows and network/distributed filesystems.

Scope questions choose their delivery route before printing context: a native control owns the question, or one final plain-text response owns both context and question. Structured question controls are the first choice. When plain text is required, the question and complete answer options or accepted input syntax are the very last terminal block, after context, reports, confidence and limitations; no trailing summary or status hides the pending decision. Required closure checks and fresh independent review inherit the selected remediation scope; an intake flag does not create a new consent hold. Source tests validate these contracts, not installed question rendering.

Authorized Git work includes local operations and remote reads such as clone, ls-remote, fetch, remote update, and guarded pull --ff-only under effective grants. Push and other remote service mutations remain prohibited; destructive local actions and PR-specific checkout protections retain their existing scope checks.

Remediation validates exact report-obligation occurrences before scope selection and frozen bucket contracts before edits. Small dependent multi-role plans can run sequentially with concrete fallback evidence. Final status counts derive from item rows; failed quality gates remain visible in a valid failed result.

Review report recovery assesses retained evidence before treating a version mismatch as a blocker. Supported selection presentations 2–5 pass the same structural preflight. Deterministic derived artifacts are repaired automatically by their owning workflow, preserving original evidence; substantive gaps offer bounded report repair with missing coverage or a fresh review. Archives remain unverified until authentic evidence passes producer completion and consumer admission.

Configured pre-commit failures trigger root-cause investigation and repair within existing scope, then the same hook, affected gates and required review rerun before the original authorized commit resumes. PR diagnosis compares per-hook results on exact PR and target revisions with equivalent configuration, environment and selection; a target failure never waives a PR failure. Read-only review gains comparison only. The recovery contract preserves unrelated staged content, real denials, recurrence stops and install boundaries.

🎯 What Codex Rig adds

• A complete development loop: investigate, assess, implement, review, remediate, optimize, release, and audit with measurable gates.
• Specialist depth without permanent agent install: exact packaged role cards can guide independent blank agents or inline passes.
• Bounded context: each specialist receives narrow context pack instead of whole parent thread.
• Evidence-backed completion: workflows use .reports/codex/<skill>/<canonical-safe-identity>/run-<NNN>/ only for bounded validated non-sensitive identity and otherwise use .reports/codex/<skill>/<timestamp>/; raw arguments are never serialized into paths. PR reviews and PR-targeted remediation use identity pr-<number>. Every workflow validates digest-bound final response after gates and discloses failed gates and confidence limits.
• Auditable commit handoffs: every proposed or created commit records all meaningful changes, concrete impacts, executed verification, and residual limits in commit body.
• Cold PR review and remediation: $code-review #123 and $code-remediate #123 +review preserve current PR evidence and local merge context.
• No stale dismissal: remediation reassesses review concerns against current code after conflict-resolution line changes; stale is not a triage or resolution status. Other evidence-backed dispositions are unchanged.
• Scoped network access: shell networking stays blocked by default outside an active profile. This checkout defines a project-local opt-in github-read profile; explicit setup or sync installs the Codex-home profile for other projects without selecting it. Both route GitHub-domain requests through the proxy when selected; host restrictions still apply and HTTP methods are not policy-enforced. Kaggle, marketplace refresh, and paid live calibration retain their runtime approval paths.
• Calibration: fixed and behavioral checks measure recall, precision, confidence accuracy, routing leaks, stale assumptions, fixture misuse, unjustified local imports, and incomplete abstractions.
• Embedded review findings: review and remediation enumerate suggestions inside collapsed bot comments individually, retain parent evidence and per-finding identities, reconcile advertised counts before grouping, and track each disposition. Shared locations alone never justify merging distinct obligations.
• Safe legacy cleanup: authenticated, exact-plan removal exists for thin shims created during pre-release development.
• Optional codemap-py structural context: the implement, investigate, and optimize workflows select task-neutral route and probe public codemap-py CLI once per run for only required structural fact, or record zero-query decision for localized edit; they persist one artifact and fall back to bounded file inspection when Codemap is absent. code-review, code-remediate, and implement must run that probe whenever their changed or target files include Python, so every such run records why structural evidence was present or absent; Code Review rejects a fresh Python-diff candidate without it. Specialists may add at most three targeted follow-up queries each.

✅ Requirements

• Codex CLI with plugin support
• Python 3.10+
• On Python 3.10, tomli in the same interpreter used for profile setup or sync_codex.py; Python 3.11+ uses tomllib
• GitHub CLI (gh) installed and authenticated for complete PR review, checkout, and private evidence; public metadata fallback remains limited
• Kaggle CLI installed and authenticated for grounded Kaggle workflows; when it is missing, Codex Rig only explains user-owned setup and never installs it
• Public GitHub access for Git marketplace install or refresh
• Windows, macOS, or Linux for workflows, package verification, sync, and read-only diagnostics
• A POSIX local filesystem only for authenticated legacy agent-shim cleanup

No official marketplace is assumed. Local, unpushed changes are not installable from GitHub.

Codex Rig never enables persistent unrestricted workspace network access. This checkout defines github-read in project .codex/config.toml without selecting it; explicit setup or sync separately installs the managed Codex-home profile for other projects preserving explicit defaults and adding default_permissions = "local-workflow" when no default exists. The local-workflow profile grants workspace .git writes with network disabled and is selected by this checkout. Direct plugin installation alone does not install that managed profile. Start a fresh opted-in session with codex -c 'default_permissions="github-read"' when needed. Both extend :workspace with .git write access under workspace roots for every command in the selected session; only github-read enables GitHub-domain traffic through the network proxy; stricter host restrictions remain in force, and neither enforces HTTP methods or executable identity. Audited GitHub helper calls use current runtime network and filesystem grants. With network enabled and required paths writable, omit sandbox_permissions and justification, even if the runtime omits the profile name. A stored default_permissions = ":workspace" or failed profile lookup does not negate current grants. Check report, .git, and checkout paths separately; preserve explicit denied destinations. Only unavailable required capability uses the owning-command approval boundary when runtime policy permits it. Other networked operations also reuse effective grants; only missing capability requires owning-command approval. Approving only gh, kaggle, or another nested executable is insufficient when a Python helper owns its subprocesses and HTTPS traffic.

Approval and denial behavior: brief names operation's purpose, capability and effects, target, owning command, and denial outcome. If approval is denied, current tool call stops and assistant turn may end; external command is not run, and Codex Rig does not issue equivalent reprompt or silently broaden fallback. To continue, send new message. Audited GitHub reads and the collector's safe local PR checkout use current network and path grants without a separate runtime request; unavailable required capability needs owning-command approval when runtime policy permits it. Destructive checkout and lifecycle mutation require separate authorization.

Codex questions prefer permitted synchronous input, then this plugin's packaged native terminal form (ask_user). The local form waits for the answer, binds it to the decision ID and frozen scope digest, and does not emit a second assistant question message. Closed choices use a selectable list; open-ended indexes, ranges, severity combinations and exact-token confirmations use native text input with the complete grammar. It performs no commands, repository writes, credential reads, network access or permission changes. Async questions are used only where current host evidence establishes usable controls; tool acceptance alone is insufficient. Explicit Approve/Deny replies bind to one unchanged, unambiguous conversational decision without demanding its displayed key again. Ambiguity, supersession, exact-token/digest and runtime-permission rules remain enforced. No answer, cancellation or unsupported input grants consent. Each plugin ships its own provider; no sibling installation or user-settings change is required. Headless hosts retain an explicit unresolved-input fallback. Before fallback, discover deferred native question tools through the current catalog or tool search, including functions.exec ALL_TOOLS when exposed, and record route eligibility. Unknown async usability is unsuitable. A text-delivered async question stays pending without a second control or repeated menu.

The native provider receives decision_id, scope_digest, question and optional closed-choice options. Consume only a matching answered receipt through the existing workflow's canonical mapping; a cached receipt never authorizes executing a completed action again. A declined or cancelled form leaves missing consent unresolved. Legacy async calls must follow their actual schema, and never receive a duplicate prose menu or an empty final after idle submission.

Rejected question calls resume at the pending decision without replaying delivered report context. A synchronous mode error does not establish async unavailability; explicit higher-priority host requirements for plain text remain binding and are reported as policy restrictions, not missing tools.

Local reviewer wave evidence requires every supplied turn identity to agree, lifecycle items to be objects, and review events to belong to a still-active reviewer. Contradictory identities, malformed items, and late events fail with a specific reason while preserving any already completed reviewer output. Final evidence validation failures also record failed status and the validation reason after cleanup, rather than leaving a completed result; failure recording still requires a writable output directory.

Every new local reviewer turn uses outputSchema to constrain raw JSON findings and bind exact source/diff digests. The runner validates returned JSON and finding fields before success; malformed output or unsupported schema fails without repair, unconstrained fallback or automatic paid retry. The loop reader also preserves historical fenced-report compatibility. This enforces response structure, not semantic correctness; it does not change native reviewer output or claim live provider certification.

Complete Local reviewer wave contexts may contain up to 2 MiB of UTF-8 source; metadata and role cards remain capped at 256 KiB, final responses at 128 KiB. JSON escaping and aggregate buffering stay bounded. An optional plan-bound model_context_window requests per-thread capacity without changing global settings; current model evidence and instruction/output headroom are required before paid execution. Transport admission and host-control checks do not prove model capacity. Exact source/diff inclusion and drift rejection remain mandatory; no source truncation or automatic paid retry.

New Local reviewer wave dispatch and Code Review acceptance require schema-2 plans containing source/diff paths and digests, with their complete exact bytes in every context. Each reviewer also needs a digest-bound operator capacity record and instruction/output reserves. The helper recomputes utf8-byte-upper-bound from exact context bytes and rejects unknown measurement methods or mismatched counts. Admission uses the requested window or evidenced default, capped by evidenced support and effective-window percentage; all reviewers' capacity records are rechecked before any paid turn. This dependency-free text bound is conservative: smaller scoped contexts may be required even when an exact tokenizer would fit. Reserves and operator capacity evidence are not hosted-model attestation. Historical schema-1 evidence remains directly inspectable but cannot authorize new dispatch or current Code Review acceptance.

Above the CLI's 1,048,576-character aggregate turn-input ceiling, the adapter loads the full context into the same ephemeral thread's history before a short trigger turn. All required preloads must acknowledge before any reviewer turn starts; --check-host tests this without model work. Large-context evidence binds the acknowledged delivery to the immutable context digest. RPC failures retain only static categories and recognized standard codes, never raw error payloads. History loading and local mock-provider tests are not independent-review completion.

Internal reviewer state uses a same-module slotted dataclass so misspelled state attributes fail instead of silently creating dictionary entries. State remains mutable during review; external JSON validation and serialized evidence formats remain explicit and unchanged.

📦 Install from GitHub

codex plugin marketplace add Borda/AI-Rig
# Optional reproducible release pin:
# codex plugin marketplace add Borda/AI-Rig --ref codex-rig-v0.4.0
codex plugin add codex-rig@borda-ai-rig

The primary command follows GitHub repository's default branch. The commented form pins immutable release bytes.

Start fresh Codex session. Codex discovers plugin's skills/ and default hooks/hooks.json; plugin hooks run only after their current definition is reviewed and trusted.

Verify install in fresh session:

$codex-rig:agent-shims doctor
$codex-rig:audit

doctor verifies active package, manifest, helpers, role cards, and legacy shim state without writing. The audit workflow checks consuming repository and reports concrete gaps. Workflow audits trace producer/consumer guarantees through the next ordinary user action, challenge accepted assumptions with counterexamples, and distinguish tested transitions from missing evidence in workflow-exploration.md. Skill/all audits also emit prompt-efficiency evidence: matched instruction cost, loaded-reference cost, obligation preservation, behavioral/calibration guards, and adversarial review. axis=value-per-token accepts candidate only with matched native/tokenizer evidence, no hard-guard regression, and declared material cost reduction; length or byte count alone cannot establish quality.

The global-instruction installer supports a read-only --check for managed/unmanaged overlap, stale blocks, and two verified legacy skill signatures. Ordinary installation refuses overlapping policy; a separately reviewed --migrate-legacy-prefix-sha256 removes only the exact digest-selected old prefix, saves a full backup, and preserves custom suffix bytes. It never deletes user skills automatically. Installation writes the absolute installed Codex Rig root into the block's PLUGIN_ROOT line (default: the package containing --source; sync passes the installed cache root through --plugin-root), so every packaged shared/<file> pointer resolves from sessions in any project. Source edits do not update active installations. Repository-specific setup and synchronization are documented in the managed global instructions guide.

⚡ Quick start

Skills can be invoked explicitly with $codex-rig:<skill> or selected implicitly when request matches their description.

$codex-rig:investigate find the root cause of this Windows-only CI failure
$codex-rig:implement apply the verified fix and run relevant gates
$codex-rig:code-review review the current diff with no prior assumptions
$codex-rig:code-remediate close the high-severity findings
$codex-rig:release assess release readiness for the current package

For PR work:

$codex-rig:code-review #123
$codex-rig:code-remediate #123
$codex-rig:code-remediate #123 +review

A bare PR number, #number, PR URL, or natural-language PR target refreshes current online PR items and verified local checkout directly, so it does not require assessed review artifact. Add +review (or another report alias or explicit report path) when remediation should combine matching assessed review report with refreshed online PR evidence.

To remediate latest assessed review created in current session without refreshing PR evidence or online comments:

$codex-rig:code-remediate review

When same invocations are passed from shell, quote them so $ is not expanded:

codex '$codex-rig:code-review #123'
codex '$codex-rig:code-remediate #123'
codex '$codex-rig:code-remediate #123 +review'
codex '$codex-rig:code-remediate review'

🔧 Skills

Skill frontmatter uses compact routing descriptions to conserve Codex skills catalog; each SKILL.md body remains complete workflow contract.

Codex Rig installs 15 skills: 14 workflows plus legacy shim manager.

Use $codex-rig:challenge-resolve with a bounded task, selected source, and acceptance criteria. Before fixes, inventory requested paths, material consumers and interactions, and complete an initial challenge across admitted parts; unreviewed parts remain explicit coverage gaps. For each current-source round, a fresh independent challenger returns structured findings; before scoring, the parent checks each failed invariant against every earlier validated signature, assigns severity separately, and dates first-reported findings as preexisting, introduced by remediation, scope-added, or unknown from frozen source evidence. The parent records stable signatures in loop-ledger.json, shows the validated weighted table before fixes, and records schema-2 actions in loop-actions.json with invariant, original case, consumer, sibling route, and source-path evidence. Each feasible solver receives that closure plan. The parent inspects actual changed source and checks the original and sibling behavior through the consumer, then asks a fresh challenger with the prior findings and complete required source to assess every signature. A solver's report remains pending until that independent assessment. On a repeated scope, report carried-open weight and newly discovered weight separately. Any decrease in total open weight converges; equal weight is plateau and increased weight is non-converging. New discoveries remain visible and cannot reset prior signatures, score history or recurrence. A changed-scope chunk retains the parent stop and marks prior findings unassessed when their validating source is missing; its local baseline cannot reset parent history or prove resolution. The same cycle applies to each large-scope chunk and material interaction: after its independent baseline, continue only while the unchanged-scope nonnegative integer total score strictly decreases. There is no arbitrary three-review cap; recurrence, authority, evidence and stricter caller reviewer/retry budgets remain binding. Missing provenance, a stale snapshot, a failed ledger/action gate, or an unexpected reviewer response stops the affected route with findings visible, one recommended remediation action, alternatives, and a user decision before another affected dispatch. The fresh challenger receives frozen source, criteria, and original counterexamples, never resolver handoffs or implementation explanations. Current challenge results use the same strict artifact checks under both filenames; historical reviewer outputs can be scored as archives but cannot become current challenge rounds by relabeling. Existing review, remediation and implementation workflows retain their own completion gates.

Before the first challenge, the parent maps each workflow branch from entrypoint through producer and ordinary consumer, with a sibling path and acceptance test. Unchanged dependencies join supporting source. A reviewer-declared unassessed route blocks the discovery baseline; a later finding present in older frozen source triggers a coverage-map correction before another fix round. Tests must exercise the real producer output instead of manually rewriting it for the consumer.

Current single-run challenge evidence uses schema 2 with an origin binding. A declared continuation pins its caller ledger and puts every earlier final-round signature, tier, structural flag, and counterexample into the frozen reviewer request; the current reviewer must assess each one. A clean reviewer response declares inspected and uninspected source paths and its limits in structured form. The validator checks that declaration against the frozen source inventory; the declaration cannot prove line-by-line inspection or detect an undeclared earlier run.

After each newly completed validated challenge, the skill stages that round in loop-rounds.jsonl.rec, invokes shared/adversarial_loop.py --append --progress, and shows its cumulative stderr table before any next fix, review or stop. Its columns are Iteration | Critical | High | Medium | Low | Nits | Weighted score; each numeric cell is old + new, security and critical combine only for display, and score weights remain 20/10/6/4/2/1. Pending or empty rounds print no progress table; unrelated updates do not repeat it. New final Results rows keep security and critical separate while showing old + new for each severity and weighted score; 0 + 0 remains visible. Old means a currently open signature seen in any earlier completed round. Unreviewed runs show N/A rather than zero; historical result formats remain readable. Table delivery timing is an agent instruction, not a machine-verified chat count. Reviewer responses target at most 1,500 output tokens; this is a hard cap only when the runtime exposes and applies one, never a reason to drop findings.

Frozen source and diff evidence preserve original line endings, including Windows CRLF. Reviewer context must contain that exact text; newline-normalized substitutes do not satisfy the binding.

Before a paid isolated Codex challenger turn, skills/challenge-resolve/validate_evidence.py --preflight-plan checks the frozen context against current canonical source, diff, declared request, and complete supporting source. Current schema-2 single-run evidence also check declared continuation origin and prior findings before dispatch. Every material section must end exactly at its next label or the context end; evidence-declared supporting paths each need a captured record. Clean final validation checks the retained scoped patch against current Git for both current reviewer routes. Source snapshots and complete-file chunk inventories retain staged deletions as missing records. This no-model check and the separate host check must pass before dispatch; a failed response remains advisory and its frozen evidence stays unchanged. Exact material comparisons avoid compiling full source and diff payloads as regular expressions, keeping large-context validation memory bounded while preserving section-boundary rejection.

The loop reuses Code Review's native inspection or isolated Codex reviewer evidence validation, binds the implementation owner to the active host session, and requires every returned finding inside one structured reviewer response. For current native challenges, use review_prepare.py prepare --challenge-only and assemble --challenge-only: one challenger receives the canonical role card and exact frozen challenge brief through audited context-page reads. Schema-eight assembly retains raw terminal output and its normalized report separately; challenge validation binds the ledger to either exact retained report and revalidates the original runtime provenance. No copied hash header is required. Historical schema-five inline and schema-six reader evidence keep their original strict contracts; isolated Codex reviewer manifests use schema four. Ordinary Code Review keeps its multi-axis routing and report format. The loop binds responses to supplied source contents and recaptures actual scoped source before acceptance. A changed file, staged state, or newly added source invalidates stale clean evidence; a stopped loop must fail its review gate. Older unsupported or substituted reviewer evidence cannot certify independent coverage. These checks preserve each route's provenance limits; they do not prove that a review found every defect.

For a large requested source scope, challenge-resolve first checks native instruction-bounded review instead of applying the optional isolated Codex reviewer route's 2 MiB limit to every route. skills/challenge-resolve/chunk_diff.py can split any requested changed or existing source scope into stable whole-file chunks using measured source JSON plus patch bytes and the coordinator's exact goal, specification, and done_when. New schema-1 plans declare first-run or continuation origin; continuation requires --caller-run, its exact loop-ledger.json, and prior coverage. Continuation planning takes the previously authenticated ledger and a source/reviewer assignment for every prior signature, pins the ledger bytes, and appends each original signature, tier, structural flag, and evidence to the reviewer request. The clean checker requires each assigned current run to receive its declared source and independently mark that exact signature with its original tier and structural flag verified-fixed or rejected; a new chunk baseline cannot hide old debt. Stopped summaries list unresolved prior signatures; unsupported chunk-plan versions cannot validate clean or stopped results. The parent runs normal validated challenge-resolve loops sequentially per chunk, replans after edits, and checks that every changed file has one current clean child result with matching criteria. Every chunk pair, including a proposed no-interaction decision, receives an independent review of the complete current files in both chunks; declared material relationships among three or more chunks receive a review of the complete member chunks too. A run may assess multiple decisions when its source contains their exact union and its bound request preserves the coordinator criteria plus every assigned rationale. New chunked coordinators store the checker's child-backed summary, and the validated final handoff lists each child's result path, score series, and decision beneath the chunk-only Results row. Complete checked child and interaction coverage lets the coordinator pass its review gate with zero findings, without an aggregate score or whole-scope reviewer receipt; partial coverage stops with a failed review gate. Candidate and promoted results rerun the coverage check and bind metadata.challenge_origin to the schema-1 manifest declaration. Current candidate and canonical coordinator completion requires schema 1; a falsely declared first run or undeclared caller history cannot be proven from local artifacts. The parent examines possible undeclared groups and the stated review scope before claiming overall clean. Oversized individual files, absent authenticated prior evidence, incomplete declared dependencies, and plausible unassessed interactions remain explicit stops; chunking does not turn partial review into full-scope evidence.

When chunks follow earlier validated reviews, the coordinator retains a chronological finding-history table across the original and child runs. Each row names its run and local round; old/new cells compare assessable underlying defects with earlier validated rows, while the child's own progress table keeps its local numbering. Prior findings whose complete validating source was omitted remain unassessed in coordinator history rather than reclassified as open or new. Different scopes do not form one convergence series or a combined score.

A stopped coordinator with validated partial child work uses a separate partial-results check that preserves each completed child's score and names pending chunks and interactions. The ordinary complete-results check still requires clean child and interaction coverage; neither partial route yields an overall clean verdict.

Replies and handoffs now name the topic or question they answer before giving the outcome, so responses remain understandable after topic switches without repeating the conversation.

Skill	Purpose
assess	Inspect issue, PR, module, or problem before implementation; emit ranked findings and gates.
challenge-resolve	Independently review and fix a bounded task through convergence rounds, retaining evidence and explicit stop reasons.
audit	Detect configuration, workflow, routing, documentation, prompt-efficiency, and quality-gate drift.
calibrate	Run fixed and behavioral checks across packaged skills and roles; score recall, precision, and confidence accuracy.
code-remediate	Triage review findings, select valid work, assign owners/verifiers, apply fixes, and prove closure.
code-review	Close PR at evidence-backed proposal gate or review its local diff across mandatory and risk-triggered axes; feature-shaped changes get a blind blueprint written before the diff is opened.
implement	Run proportionate plan-build-verify work with bounded native implementation owners after independent plan challenges, or the separate promoted read-only route.
investigate	Debug code and narrow unknown failures to evidence-backed root cause before implementation.
kaggle	Create or extend grounded Jupytext Kaggle notebooks per shared/notebook-style.md, grounding schema via authenticated kaggle CLI.
manage	Safely create, update, or remove Codex skills and agent configuration with optional disjoint read-only inventory support; mutations remain parent-serial.
optimize	Measure first, change one bounded variable, remeasure, and reject regressions.
release	Draft traced release notes, complete contributor credits, preserved changelogs, migration and summaries; report readiness in a check/evidence/action table.
research	Collect current primary evidence and map findings to concrete implementation choices.
sync	Inspect active plugin-cache drift or refresh public-GitHub Codex Rig installation without cache edits.
agent-shims	Diagnose and remove authenticated thin shims from pre-release development; new installation stays blocked.

Routine execution across all Codex skills follows Authorized Workflow Execution. Shipped helpers, local preparation, selected edits, and configured checks use current effective grants. State changes, wrappers, multiline text, and chained commands alone never require escalation. Missing prerequisites are reported as unavailable checks rather than code failures; recovered commands resume the first unmet checkpoint. These contracts neither bypass a runtime denial nor authorize arbitrary unsandboxed interpreters or gate runners.

Small understood reversible local implementation and management tasks use a parent-only path: relevant project checks and a concise verified outcome. Tests and documentation for the same change do not require separate specialists, execution plans, or result bundles. Broad work and requested structured reviews retain the detailed workflow. Every detailed workflow defines input contract, fail-fast rules, required gates, artifact shape, and confidence output. shared/quality-gates.md owns compact outcome-coupled final-chat frame—Outcome, Results, Verification, Remaining, Recommendations / next steps, Confidence, Artifact—while shared/final-handoff-contract.md makes that structure executable after gates: schema-v2 general results and schema-v3 current Code Review results bind validated final-handoff.json, rendered final.md, and digest record before promotion, and workflow emits final.md verbatim. Code Review producer completion accepts only bound schema-v3 results, including unavailable and closed dispositions; schema-2 results and schema-3 results without retained proof remain readable as unverified archives, outside completion and remediation intake. Rendered section and table labels use portable Markdown bold text instead of headings or terminal color escapes. Each skill keeps its exact outcome vocabulary, result table, and terminal exceptions; next steps reference result rows instead of repeating them, and artifacts supplement rather than replace readable result. Historical schema-v1 artifacts remain readable. agent-shims stays explicit exception because it has no canonical run/result artifact, and current host still has no post-send transcript hook to prove chat transport bytes. shared/native-skill-contract.md likewise owns generic shell-network approval and denial behavior while each networked skill retains its five concrete operation values and recovery exceptions. Workflow instructions live in skills/<name>/SKILL.md; shared executable contracts live in shared/.

Medium/large or unexpectedly nontrivial implementation follows the proportional execution sequence: freeze and independently challenge the top-level plan, detail and independently challenge implementation ownership, delegate only useful disjoint work, then verify against the accepted plan. Reuse current parent plans for scoped children. Native implementation writes require existing task authorization and observed tool controls; instruction bounds do not prove filesystem isolation. The separate portable parallel-read route retains its admission, digest approval, and parent-serial mutation rules. Manage mutations remain parent-serial, and read-only workflows retain their specialized evidence contracts without an invented implementation stage.

Review execution and source isolation

Code Review prepares all required specialist contexts and short dispatch arguments with skills/code-review/review_prepare.py. For new native runs, the parent writes focused evidence briefs referenced by review-briefs.json; review_prepare.py owns generated specialists/<role>-context.md files and delegates bounded batches to review_batches.py. The parent writes specialist context files directly only for legacy or non-producer routes. After joins, specialist-assessments.json records unchanged numeric confidence and a nonnegative integer blocking_findings count of canonical non-low findings; assembly derives each axis from frozen briefs. Lists are invalid blocker counts, and low reviewer confidence remains a completion limit. The complete frozen native roster launches in descending context-byte order with stable role-ID ties and at most four allocated child slots. A successful spawn holds its slot until actual task completion and the exact final-answer join. A smaller host pool keeps the remaining roles queued; at an observed parent scheduling opportunity, proven free slots refill before another wait. Explicit no-child full-pool refusals retain the queued role and resume only after actual capacity changes; unknown receipts stay incomplete. Manifests bind actual launch order, slot lifetime, parent wait/results, complete child evidence and joins. Dispatch supplies every exact page call; reviewers execute each complete generated block unchanged and in order, without constructing or editing command arguments. Current reader commands use absolute script and plan paths and omit a redundant working-directory coordinate; historical reader recipes retain their exact original coordinates. Each reviewer reads its frozen context through generated audited review_context.py calls in responses of at most 8,192 UTF-8 bytes, then returns text without further tools. Missing, altered, or truncated pages cannot establish complete coverage. This avoids copying source through the parent’s dispatch message and fixes the self-referential provenance hash; known historical reader identities retain their exact original dispatch recipes, while unknown or altered readers fail closed. Contexts stay within 65,536 UTF-8 bytes. Generated byte counts measure dispatch overhead, not a proven token or wall-time saving.

Review coverage and confidence gaps remain explicit limitations, not recursive review findings or automatic remediation tasks. Additional review beyond authorized scope needs one decision with a specific question, expected evidence and stop condition; a declined or dismissed request is omitted from final actions. Remediation retains exact report context separately from actionable source findings, with historical intake still readable.

PR reviews retain their exact detached worktree. Local working-tree/path reviews now create an isolated mirror of changed source, preserving the invoking branch/index/files, and recheck it before acceptance. Captured changed-file bytes are restored after Git patch application so LF/CRLF conversion cannot alter the review source. Worktrees separate caller edits but do not enforce immutability. The gate runner can reuse an explicitly selected existing project virtual environment for a verified clean review worktree; required checker/import-source checks remain. Referenced PR bodies come from the audited GitHub reader when material, rather than relying on browser cache. No automatic installs, permission changes, or remote mutations are added. Remediation can prepare already-collected online review evidence alongside parent-owned conflict analysis after PR/target identities and checkout are verified. It joins before finding fixes; actual merge resolution keeps its existing authorization and source-mutation barriers.

🔗 Optional codemap-py structural context

Bounded Codemap integration and fallback vocabulary

When an active installed Codemap skill is available but its launcher is outside PATH, pass its exact plugin root through the adapter’s --provider-root. Explicit CODEMAP_BIN retains precedence. Use an already available compatible CODEMAP_PYTHON; never scan versioned caches, install dependencies automatically, or treat provider presence as proof the index matches the review worktree.

implement, investigate, and optimize select route and probe the codemap-py plugin once at bounded decision point via shared/codemap_adapter.py, then persist result to run artifact — specialists consume that artifact first. An exact localized edit with no unresolved structural fact uses skip; one unresolved fact uses matching single route; broad or unknown scope uses legacy standard batch; explicit structural request overrides skip. The other workflows retain their existing category-specific standard behavior or recorded not-applicable status. The adapter reads only public codemap-py doctor --json/query CLI surface, never codemap-py's cache internals, source paths, or cross-plugin Python import.

Running the probe is required, not optional, when changed or target files include .py paths the provider can map: code-review checks the changed files its diff file contains (untracked-only and .pyi-only changes are outside that diff), code-remediate its target scope and normalized findings, and implement its target or planned files. Required means the adapter runs and persists codemap-context.json; it never means Codemap must be installed. An absent or incompatible artifact records its reason and the workflow continues with bounded inspection. Code Review's validator fails a fresh Python-diff candidate that has no artifact, a skipped one, or one whose status, reasons, query, or diff file disagree with what actually ran — it re-derives them with the adapter's own reduction — while promoted historical results stay readable. code-remediate and implement keep no changed-file listing a validator could classify, so their requirement is enforced by the skill instructions.

The review batch reads the reviewed change set from --diff-file and never diffs the working tree against HEAD, which in a detached review worktree compares the tree with itself and reports zero changed files. --root names the checkout whose Codemap index answers — the invoking checkout, not the nested review worktree — and the adapter runs Codemap from that root, because Codemap finds its index from its working directory; relative paths resolve against the caller's directory first. Artifact schema 4 keeps the provider's bounded answer for each query — for diff-impact, changed modules with risk, unmapped files, and test impact, lists capped with their original lengths recorded — plus its completeness_reason, root_mismatch, and note, and lists every gap cause in status_reasons. A root_mismatch, a change set whose Python files all map to no module, or a diff that deletes a Python module (which the provider never reads, leaving its importers unchecked) is degraded with its reason, never available; only a diff naming no Python file may map nothing and stay available. A changed method or constructor with caller_count: 0 keeps the provider's dispatch hint on its entry and in a top-level hint named in status_reasons, and the call graph's not_covered blind spots make that artifact degraded, since zero static callers there is unresolved, never unused; a changed test* method in a test module carries no hint, since the test runner calls it, so a test-only change keeps its status. A provider failure keeps the provider's own error text, and input the provider itself diagnoses and rejects degrades rather than marking it incompatible, while a bare argument-parser usage exit is a provider failure. A review restored by native-provenance recovery is never probed retroactively: it keeps its earlier artifact or records codemap_context: "not-required-historical".

When the persisted artifact leaves a structural fact open for one specialist, that specialist may receive at most three targeted follow-up queries — callers, dependencies, or test-impact, each with a resolved target — written as codemap-followups/<role>-<NN>.json and cited in that specialist's own evidence. Follow-ups never run after an absent, incompatible, or skipped probe, and each one's role must be a role the review's routing triggered. A target the provider refuses — not found, ambiguous, or not indexed — leaves that follow-up degraded with the provider's candidates kept in its answer, so the next follow-up can use one of them; a method with zero static callers keeps the provider's dispatch hint on callers and test-impact alike, each hint opening with its search or, for a protocol method, its do-not-delete instruction, so the 300-character bound keeps it, since instance calls, property reads, bound-method references, and implicit protocol (dunder) calls are never resolved statically. Code Review's validator re-derives each query's input_rejected flag from its exit code and recorded answer, so a provider failure cannot be recorded as a refused target to keep follow-ups open. Read-only reviewers never run commands, so the parent runs their follow-ups before preparing their context. A further open question is recorded as a coverage gap rather than a fourth query.

The adapter resolves validated launcher once per workflow and reuses it. Independent standalone read-only queries may run concurrently only against prepared stable index with self-heal disabled (SCAN_NO_AUTOBUILD=1); dependent queries wait, and refresh/self-heal/index writes are serial. A complete untruncated result settles its own graph fact, not sibling dimensions; there is no arbitrary total-call cap for workflow facts required to finish, while targeted correction retries stay bounded and stop when same failure recurs. Explicit independent AST/oracle work remains allowed.

The adapter reports one named status: available, absent, stale, incompatible, degraded, stale+degraded, or skipped. skipped means workflow deliberately selected zero Codemap subprocesses; it is not structural evidence. stale+degraded is vocabulary's only composed value and means both caveats hold at once, so neither masks other. A standard batch run without --target omits queries that require one instead of failing them, so targetless probe reports honest status of queries it actually ran. Each query also records index file that answered it, and any disagreement with path health probe resolved is listed under index_path_divergence as evidence — both paths retained, never reconciled, and never folded into status. Absence and incompatibility are non-fatal — workflow falls back to its normal bounded file inspection. manage, sync, agent-shims, calibrate, and kaggle stay not-applicable with recorded behavioral reason (no Python call-graph subject); see shared/codemap-contract.md for full protocol, adaptive route vocabulary, category-to-query map, per-skill route selection, and not-applicable rationale. Repository sync installs Codemap alongside Codex Rig, but Codex Rig retains zero runtime dependency on it: packaging, skill discovery, and startup still work when Codemap is absent or incompatible.

The active consumer contract is separate from provider integration metadata. Audit compares active source guidance with reachable installed skill references and reports consumer_query_guidance_missing, consumer_query_guidance_unreachable, or consumer_query_guidance_drift; static references establish reachability only, not semantic loading or current-session activation. The provider-managed codemap-py-integration.md block is metadata-only, and matching installed bytes or native listings cannot substitute for session evidence.

🤖 Specialist role cards

Roles are canonical behavioral profiles, not claims that Codex selected custom agent configuration. Each card includes trigger/skip boundaries, evidence ownership, execution constraints, handover fields, and confidence rules.

When several independent role passes are justified, Codex Rig fixes their routes and narrow context packs first, dispatches approved work in one wave when runtime supports it, and joins every handoff before parent acceptance. The installed shared/parallel_execution.py validator derives parallel only from overlapping substantive intervals recorded in one manifest wave; completed spawned passes without overlap are independent-spawned, while unsafe or unavailable fan-out is serial-fallback with equal gates. Schema-v1 manifests remain readable for historical structural checks only; generic runtime promotion requires schema-v2 and non-sensitive portable-read-restricted plan/manifest. That runtime evidence binds frozen parent plan, parent spawn/start, child lineage, persisted restricted controls and approval never, terminal interval, exact output, parent result-delivery event, and context/output common-secret scans to currently observed Codex rollout shape; filesystem credential isolation remains unverified. The summary does not claim global network, command, credential, or filesystem denial or that all command behavior was inspected. Generic portable parallel writes and the future host-isolated tier remain unavailable; Implement's bounded native write route is separate, and code-remediate-local has its own production lifecycle below. That shape and its timestamp units are internal rather than documented platform guarantee, so drift fails closed. It never starts second wave for same parent work item; new discoveries stay parent-serial or require user-visible re-plan. Scheduling never expands fan-out, overlaps ownership, bypasses approval, treats requested-only controls as enforced, or accepts unjoined output. Code Review has a separate schema-eight instruction-bounded native route: its predeclared full roster may exceed four roles, while allocated child slots stay at most four and dependent source waves retain all-role join barriers. New source-only batches do not add interaction or consolidation review waves; historical batch inventories without that topology retain those strict barriers. Refilling that roster adds no scope; strict portable schema-v2 still permits at most four total nodes.

The Implement and Manage execution selector uses --execution=serial|parallel-read|parallel-write|auto, which avoids ambiguity with positional task text. An explicit invocation value wins over CODEX_RIG_EXECUTION, which wins over the default auto. auto keeps narrow work on the lightweight parent path; medium/large or unexpectedly nontrivial Implement work uses bounded native delegation only when useful disjoint ownership and observed tool controls permit it, otherwise it stays parent-serial. Manage may use disjoint read-only support, while its mutations remain parent-serial. auto never selects the portable route. A resolved parallel-read selection—whether from the invocation or environment—selects the promoted read-only consumer route, which retains frozen-plan and exact digest-bound approval for planned parent mutations. parallel-write rejects before dispatch, serial remains parent-serial, and unknown values reject before dispatch. Authorized serial work needs no additional consent receipt. A launch-wide default can be selected with CODEX_RIG_EXECUTION=auto codex. See the canonical G0–G8 execution flow for forked dispatch and synchronization chart.

implement and manage have promoted portable read-only routes with freeze/join barriers, resource conflicts, serial parent decisions, equal-gate fallback, and stop rules. Each route is plan-bound to exact consumer_id, capability=portable-read-only, promotion_status=promoted, parent_mutations=serial, and canonical_gates=serial. Before dispatch, skill runs installed parallel_execution.py preflight for its fixed consumer; after every terminal join it runs validate-runtime with same consumer and repeats preflight before any parent mutation. A planned parent mutation on the selected portable route requires separate exact-digest approval; authorized serial parent work and serial fallback use existing task authorization. Supplied denial or stale approval still rejects. Unbound generic runtime evidence is promotion-ineligible. On this portable route, mutations and canonical gates remain parent-serial and generic portable writes remain disabled. Only Implement may select native bounded writes after its accepted plan. The canonical G0–G8 execution flow is shared gate reference.

shared/parallel_telemetry.py provides privacy-minimized timing and token accounting for rollout analysis. It retains HMAC identifiers, counters, declared outcomes, child timing, workload-key digests, and explicit dispatch-to-final-join duration; it does not retain raw prompts or responses, reasoning, tool data, paths, environments, credentials, or raw runtime IDs. Two matched live pairs measured speedups of 1.6091x and 1.0791x, with token multipliers of 1.0024x and 0.9976x. These are workload-specific observations, not guarantee. The current host has no provider-enforced per-child usage cap, so actual context may exceed pre-dispatch reservation; compact telemetry reports overrun. Child-duration maxima are diagnostic proxies only and never support savings claim.

Each parallel wave must freeze positive token-admission ceiling and positive per-node reservations before dispatch. Completed and active reservations must form stable prefix and remain charged; admission stops before first node that would exceed ceiling, active children finish to terminal evidence, and all unstarted nodes are serially re-planned with same gates. Schema-v2 runtime acceptance binds each wave and spawned node to token_budgets in exact hashed plan. Earlier schema-v2 evidence without token budgets can be read only with historical_unbudgeted=True; that result is acceptance-blocked and promotion-ineligible, while default path remains budget-required. This bounds admitted reservations, not actual provider usage: no provider-enforced child token cap exists on current host, so actual context may exceed reservation and compact telemetry reports any overrun. Retained wave proof uses HMAC identity, proof digest, and bounded status/counters. enforce_diagnostic_expiry appends path-free JSONL evidence to fixed expiry-audit.jsonl before eligible deletion and after each outcome; it deletes only exact HMAC diagnostic and retains unresolved diagnostics until resolution. Unknown or raw fields fail closed.

Operator rollback is deliberately procedural:

1. Disable the affected skill's parallel opt-in without changing the frozen plan or its digest.
2. Preserve completed outputs, terminal child evidence, parent joins, and the original quality gates.
3. Serially execute only unfinished work; never replay completed nodes.
4. Retain failed or conflicted worktrees and stop when cleanup or repository state is ambiguous.

shared/parallel_worktrees.py is bounded generated-fixture scaffold, not production write route. The active parent freezes exactly two disjoint work packages at one clean HEAD, creates separate detached worktrees, dispatches both subagents, and joins exactly two child reports containing node ID, completed status, concise summary, exact changed paths, and canonical Git patch SHA-256. A completed child obtains that fixed-shape report through create_completed_child_handover, which hashes raw Git subprocess bytes through lifecycle module rather than shell- or RTK-rendered diff output. The parent verifies both reports against actual worktrees before deriving patches, integrates them in stable order, and cleans successful worktrees without force only after durable evidence. It strips inherited GIT_* redirection overrides, rederives managed authority before every transition, fingerprints declared retained attempts, and rejects source drift, commits, staged/untracked/undeclared/delete/rename/mode/type changes, aliases, ownership ancestry, symlinks, partial joins, report mismatches, conflicts, and cleanup uncertainty.

The retained generated-fixture record is operational audit trail under parent authority, not cryptographic host attestation. It does not claim particular child tool, child authorship, edit-time overlap, native-Windows Git lifecycle coverage, or production eligibility. It keeps write_parallel_eligible=false and write_parallel_promoted=false; every generic production route remains disabled. Local reviewer wave readers, brokers, sidecars, signed receipts, and full-thread filtering are intentionally unnecessary.

Code-remediate-local has a separate production lifecycle, not generic resolver promotion. Its exact schema-v2 plan and dispatch record bind the authoritative source repository and exact HEAD/tree, two to four independent buckets with only exact shared-file overlap, actual context-pack paths and SHA-256 values, resource locks, fixed new state basename and output names under source-local run root, fixed code-remediate-shared-quality-gates reference, rollback policy, and non-force cleanup policy. Existing unrelated tracked, staged, or untracked changes may remain outside owned or operation paths. Detached worktrees use the supported sibling .codex-rig-worktrees/<run-id> location or a source-local Git-ignored .reports/codex/code-remediate-worktrees/<run-id> root, preferring source-local when available; roots that escape, traverse symlinks, or already exist are rejected. Plan, dispatch record, state, patch, reconciliation, rollback, and lifecycle artifacts stay in the authoritative repository’s normal .reports/codex/code-remediate/... run directory. Preparation and every authority transition re-hash each context pack and reject drift. The argparse sequence is prepare, create-handover, join, collect, integrate, optional reconcile, apply-source, and cleanup; it is not a scheduler, registry, or global promotion mechanism. The parent prepares worktrees; children edit only their declared paths, do not commit, and return canonical terminal status, summary, changed paths, and patch SHA-256. The parent re-derives patches, joins every terminal handover, integrates them in lexical bucket order, and reconciles any collision in the integration worktree against a run-local hash-bound record before source application. Integration records only Git-structural verification; it does not execute arbitrary plan-provided commands. After source application, existing shared quality gates and validated gates.json remain required for a passing remediation result. Eligible independent work runs in parallel by default. Indivisible, dependent, or capacity-limited work continues parent-owned or sequentially with its concrete reason recorded; that fallback does not require an approval prompt.

Source application rechecks exact raw integration postimages, captures raw source preimages, stores durable reverse patch, applies one parent-generated forward source bundle, and verifies expected Git content after authoritative worktree's clean filters. The lifecycle records raw source SHA-256 postimages for cleanup and evidence, while Git clean-filtered object identities allow LF and CRLF worktree bytes to represent same repository content across native platforms. Only known Git-content states may be restored after recomputing affected identities and confirming each path is at its recorded preimage or expected postimage; mismatch, filter failure, restore error, or failed recomputation records rollback-ambiguous, retains worktrees and evidence, and stops without automatic restore. Non-force cleanup occurs only after durable source application and exact recorded source postconditions, and failures retain evidence. The artifact validator independently re-hashes every child patch, forward source bundle, and rollback patch beneath exact run root, while source, worktree, evidence-root, state, output, and patch path components reject symlinks and path escapes. The schema-v2 lifecycle record and digest are bound into remediation result; schema-v1 plans are planning-only and cannot prove completed execution. Containment is parent-authoritative operational postcondition containment with capability_sandbox_verified=false, not per-child capability sandbox, hostile-child security boundary, globally atomic source transaction, or security isolation guarantee. Separately sandboxed processes remain future stronger alternative, not current prerequisite.

The code-remediate-local production route retains full lifecycle and rollback proof. Installed-package acceptance runs its lifecycle suite from manifest-declared payload, and the repository full-test matrix records that gate on Linux, macOS, and native Windows. Promotion is limited to this consumer-owned route. CI configuration, previous local proof, auto, environment value, or --execution=parallel-write never substitutes for a newly frozen consumer plan and exact-digest dispatch record. workflow-default authorizes the route without implying that a user approved that specific digest.

Role	Requested model	Primary axis
delegation-lead	Luna	Cost-aware workstream routing and consolidated handover.
sw-engineer	Sol	Primary production Python source reviewer; core implementation, APIs, types, and reproducible Python/ML code.
qa-specialist	Sol	Regression proof, edge cases, test design, and executable acceptance.
squeezer	Sol	Profile-first performance, throughput, memory, and synchronization analysis.
doc-scribe	Luna	User documentation, docstrings, examples, changelogs, and migration guidance.
security-auditor	Sol	Auth, permissions, secrets, deserialization, supply chain, and trust boundaries.
data-steward	Sol	Dataset integrity, leakage, splits, augmentation, and reproducibility.
cicd-steward	Luna	CI/CD, matrices, caching, publishing, and flaky-run diagnosis.
linting-expert	Luna	Ruff, mypy, pre-commit, suppressions, and static-analysis policy.
oss-shepherd	Luna	OSS triage, SemVer, deprecations, contributor workflow, and release readiness.
solution-architect	Sol	System design, public contracts, coupling, compatibility, and migrations.
web-explorer	Luna	Current external documentation, changelogs, and migration evidence.
curator	Luna	Configuration quality, duplication, drift, stale references, and weak gates.
challenger	Sol	Adversarial stress tests for plans, risky changes, and no-finding conclusions.
scientist	Sol	Papers, hypotheses, experimental methods, metrics, and ablations.

The model names are requested role settings. Blank-agent injection does not prove actual model, reasoning effort, sandbox, approval policy, or nesting profile. Workflows must record requested and observed controls and stop when unproved setting is mandatory for safety.

🔗 How portable role routing works

Role-card injection, fallback, and provenance details

The canonical policy is shared/specialist-orchestration.md.

Read-only specialists return findings or executable probe requests; parent saves responses and owns authorized scratch execution. Review and investigation do not grant source-edit authority. Implementation and remediation retain their separately authorized writer roles. Parent-run probes remain distinguishable from independent conclusions. Runtime validation rejects explicit filesystem write grants even under read-only sandbox label; absent contradictory grants still do not prove isolation. Missing child controls remain process limitation, not reason to broaden permissions or stop otherwise permitted serial investigation.

Every user-facing message starts with short plain-English explanation before technical details: progress updates, questions, approval requests, errors, blockers, handoffs, and final answers. When workflow pauses, its report names stopped action and scope, concrete cause/evidence, governing rule, safe work that continues, next step and responsible actor, and exact resume condition. Routine preparation and safe diagnosis stay agent-owned; generic "repair the environment" instruction is not diagnosis. Existing authorization is used first; denial and retry rules remain in force. Source inspection continues whenever source is accessible, while unavailable source identity, unsafe execution, credential exposure or unauthorized credential access, and unauthorized destructive or remote mutations remain hard stops; authorized credential-broker reads and local changes continue.

Recovery guidance explains why a check rejected the work, distinguishes unknown causes, and recommends a concrete next action. A necessary repair choice states what approval and decline each do: rejected reviewer evidence can permit fresh sequential review with disclosed missing independence; unavailable current PR source permits diagnosis or user-accepted discussion of an older assessed report, but no code edits. Existing merge conflicts receive a separate diagnosis; Code Remediate offers the applicable finish/abort/defer choices with preservation and authorization effects, while a review-only Code Review reports the conflict, never finishes or aborts it, and hands it to Code Remediate while its detached-worktree review continues. Once authorized recovery succeeds, Code Review and Code Remediate resume their first unmet checkpoint and normal completion gates without requiring another invocation; a remaining independent blocker gets its own explanation. Repairs to validators, credentials, or Git history are never inferred from a generic error code.

When native reviewer controls are unavailable, Code Review has explicitly approved isolated local reviewer wave. The parent launches bounded independent read-only threads, disables external tool capabilities for that invocation, saves unchanged responses, and validates schema-4 evidence before normal completion gates. Its saved evidence records execution observed by the parent; native child lineage, cryptographic attestation and credential isolation remain unverified. This experimental route requires compatible installed Codex CLI and separate paid-execution approval; it does not automatically promote other skills or enable parallel writes.

Native review preparation accepts up to 256 KiB of complete context per reviewer and sends it through ordered, provenance-checked pages of at most 6,000 context bytes. For new --batches source-only reviews, larger required scopes use the frozen source waves and per-role capacity parts; include material unchanged callers in that complete source coverage, and finish every scheduled wave before aggregation. This topology does not create interaction or final-consolidation review waves. Historical inventories without review_topology keep their strict interaction and consolidation requirements. Neither paging nor a larger transport limit proves the reviewer covered missing source.

Reviewer output must be new and contained beneath resolved plan directory. Setup failures return bounded errors; when output storage is unavailable, no diagnostic artifact is promised. Completed responses remain retained if later failure occurs.

The local reviewer wave accepts documented planning and warning events with bounded validation. Unknown events still stop that wave; rejection diagnostics classify a documented notification using a fixed public-schema label, or unrecognized, without retaining arbitrary method text or payloads. A repeated protocol failure stops retries of that launcher, not accessible source review. Use available instruction-bounded reviewer or disclosed parent-serial fallback without redundant approval; ask for decision only when explicitly required independence remains unavailable. Historical rejected events cannot be reconstructed from payload-free evidence.

Review continuation: verified source → available text-only reviewers → parent inspection if needed → findings with honest coverage. Failed launchers stay stopped; accepted evidence never includes rejected outputs.

Remediation reports separate new finding-specific changes from target integration and evidence-only closure. If no finding was implemented, the opening says so; green CI can close its CI obligation but does not prove a code fix or independent review. Concise outcomes state a disposition and reason, not bare unresolved; valid blocked work stays open with its owner and next action. Passing checks do not mean remediation is complete. Current native reviewers receive source, diff, and evidence through generated audited context-page reads before returning text. Historical inline reviewers retain their complete inline delivery; bare unreadable artifact paths never establish coverage. Missing coverage starts permitted evidence collection and focused reproduction; successful recovery resumes the selected finding, while unavailable capabilities receive a concrete recovery decision.

After authorized target integration, collection artifacts remain pre-merge source receipts and the merge-resolution record identifies the revision used for finding edits. Resuming does not replace that merge with the original PR head. Resolving files without a required merge commit is partial recovery: the workflow automatically completes and verifies the task-owned merge before finding edits, with no question and no grant check; it asks only when scope or resolution intent is genuinely missing, and a narrower no-commit instruction stops it. Terminal collection summaries link protected-path evidence without copying its path lists.

Situation	Review action	Human input needed
Public API changed; CI or CLA fails	Continue inspection; report compatibility or merge issues	None for reading
Child controls unproven; local reviewer wave fails repeatedly	Stop that launcher; use native text-only or parent review	None for available authorized route
A probe might execute unsafe code	Pause probe; continue inspection	Safe execution conditions and approval if required
Required source or identity unavailable	Pause dependent assessment	Supply verified source/evidence
Explicitly required independence unavailable	Finish available inspection; withhold full completion	Restore independent route or revise requirement
Requested action exceeds authorization	Pause that action; preserve unaffected work	Specific approval or human-owned action where delegation is prohibited

1. The parent determines whether work actually benefits from independent specialist.
2. It reads and hashes roles/<role-id>/ROLE.md.
3. It builds narrow context pack: objective, relevant evidence, exclusions, concrete questions, output contract, and stop rule.
4. It asks runtime-provided blank/default subagent to follow complete role card before context pack.
5. If no safe subagent route exists, it performs inline role pass and reports that independence is false.
6. The parent reconciles outputs, inspects executable evidence, and owns final acceptance.

Passing only role name or path is not role injection. A task name records provenance only; it does not select custom profile. General role fallback is permitted for route absence or rejection before substantive work. Code Review also permits its existing separate parent-sequential fallback after substantive specialist evidence is rejected: preserve that evidence as unaccepted and perform fresh parent inspection. Neither route permits fallback merely because a specialist disagreed or found a problem.

New native review manifests use schema eight, advancing the committed schema-seven family once. review_prepare.py prepare-repair supports one evidence-bound correction for an incorrect source reader command before any successful source page, or lossless conversion of closure_evidence lists to the required scalar string. It retains the original child, response and join, generates a distinct replacement, preserves findings and frozen source, and resumes the current wave. Historical schema-seven readers keep their original strict retry contract; substantive findings cannot be retried as protocol repairs.

For every routed pass, Codex Rig records role ID, card hash, attempted and selected routes, fallback reason, observable model/effort, requested and observed controls, independence, nesting depth, and material fidelity limits.

💰 Orchestration and cost control

Tier ownership and escalation guardrails

Use delegation only when two or more disjoint workstreams can proceed without duplicating same context. Typical high-value splits are implementation versus tests, architecture versus migration docs, or CI diagnosis versus static analysis.

• GPT-6 Luna owns bounded coordination, documentation, CI/CD, web evidence, OSS, linting, and curation support.
• GPT-6.1 Sol owns the normal parent, implementation, runtime behavior, tests, data/ML, performance, challenge, and executable verification. Routine parent/build/test/performance use medium; deeper review, data/research method, and challenge use high.
• GPT-6.1 Sol architecture and security roles remain explicit-selection, read-only advisory passes. GPT-6 Astra has no standing route.

Select smallest capable tier from current task evidence: escalate only for mandatory boundary or observed lower-tier insufficiency, de-escalate only after evidenced scope split leaves bounded support, and never change tiers on cost alone. The canonical policy is shared/specialist-orchestration.md.

Two consecutive primary work cycles without material progress, or three evidence-backed unsuccessful primary attempts since last evidence-backed material primary progress, trigger a persisted and validated stall ledger — a reasoning-progress.json header plus an append-only reasoning-cycles.jsonl cycle log, schema 3 — and one advisory escalation: supported higher reasoning effort first, then next permitted tier. The advisor supplies bounded recovery action and stop condition but makes no changes; its route is valid only when observed sandbox is read-only. If no safe route exists or that one action makes no evidence-backed material primary progress and still fails to close condition, Codex Rig stops and asks user with consolidated evidence, hypotheses, rejected alternatives, and recommended next step. This guardrail is distinct from, and never resets, repeated-obstacle policy.

The primary goal stays fixed through reviewer setup and artifact repair. Current schema-three progress ledgers retain primary_goal and classify each cycle as primary or auxiliary; auxiliary work names the acceptance criterion it serves and cannot count as primary material progress. Evidence-backed material primary progress resets the unsuccessful-attempt sequence; an open acceptance condition alone is not a stall. Auxiliary cycles do not reset that sequence. A replaced condition retains a distinct replacement id, source=user-direction|external-state, and nonempty evidence; a bare replacement label cannot bypass the bound. A known authorized fix gets its implementation and regression before another review-setup cycle. Agent-owned setup failures get one diagnosis and one bounded repair; a failed repair stops that route while safe primary work continues, with required coverage still blocking a clean completion claim.

Each native-wave or batched review admission validates its runtime evidence once per request. Later result, preflight, and report-consumer requests revalidate source and receipt evidence afresh; no validation state is cached between requests.

Native review preparation requires --source-root and focused source_paths in every role brief, binds source to local/PR checkout evidence or an expected detached commit HEAD, and supplies actual changed source plus relevant callers. Prose-only, stale, unrelated, or conflicting checkout evidence cannot produce a frozen dispatch. Full local patch/untracked inventory and collective reviewer source coverage are required; local path reviews declare --scope-path. Commit review binds both expected HEAD and comparison base. Verified committed/PR deletions retain missing-file evidence, renamed and Git-quoted paths remain reviewable, and local contexts may include preexisting unchanged callers from the verified mirror. Duplicate reviewer assessment sections are rejected. PR collection requires explicit thread/comment node arrays and marks partial GraphQL results or incomplete nested comment pages unavailable; import-bound pytest gates prove both imported modules and selected tests belong to the reviewed worktree. Parallel pytest retains import and selected-test provenance from each local xdist worker; missing worker coverage cannot certify a pass. Serial pytest and explicit -n 0 use the same source checks.

Release-draft templates use short square-bracket fields, with writing and verification guidance in separate notes. Finished release notes replace every field and omit template instructions.

Report-backed remediation reconciles the inventory with original canonical findings and evidence obligations in findings-input.txt. Confirmed selection determines resolved/unresolved totals, and blocked required work prevents status=pass even when no commit is requested. Explicit user deferral and historical presentation-two readers retain their separate contracts.

The delegation lead returns one handover. Executable acceptance, runtime/API changes, release-blocking decisions, and security/architecture conclusions remain parent- or appropriate Sol-owned. Narrow work stays in parent when handoff cost would exceed its value.

📊 Quality gates and artifacts

Artifact shape and confidence thresholds

Workflow artifacts commonly use this shape; exact files vary by workflow:

.reports/codex/<skill>/<timestamp>/
├── result.json
├── gates.json
├── gates.txt
├── failed.txt
├── gates.checks.jsonl
└── skill-specific evidence

Remediation PR decision questions include the PR number and a clickable canonical GitHub link inside the question, including missing-review and unavailable-PR prompts. A collection failure states that no source review ran; terminal diagnostic artifact closure does not imply a completed source review.

Remediation owns continuation after an approved nested review: review completion and a prepared branch receipt never mean fixes are complete. On source drift it verifies the PR destination, safely fast-forwards a clean behind branch or recovers the correct branch through the collector, preserves local fixes and original receipts, and resumes the first unmet checkpoint. A genuine blocker reports remediation incomplete, implemented count and next action; a no-change completion requires evidence for every finding’s disposition.

PR-targeted remediation reports follow .reports/codex/code-remediate/pr-<number>/run-<NNN>/, matching review report grouping. After collection, create_run.py --skill code-remediate --promote-pr-run <run-directory> derives the PR identity from pr/pr.json and allocates the next run. Local report-only runs and collection failures keep timestamp directories; resume preserves its existing run.

The exact files vary by workflow, but completion requires requested output, explainable gate results, unresolved risks, and validated result.json. Shared helpers provide diff collection, PR evidence collection, gate execution, artifact validation, severity mapping, and result writing. Local reviews retain timestamped shape above. A PR review starts there because current-branch input may not yet reveal PR number, then successful authoritative collection promotes whole run to .reports/codex/code-review/pr-<number>/run-<NNN>/; all later artifacts use that printed path. Failed pre-identity collection remains timestamped unavailable diagnostic, not assessed review. Existing flat review artifacts remain discoverable without migration.

Confidence is evidence-backed. Every reported gap/limit starts with (-0.NN) before its description (ASCII minus, two decimals); unique deductions total 1.00 - score, nonreducing limits carry (-0.00), repeated gaps count once, and unexplained shortfall is an explicit residual. This is transparent judgment accounting rather than an empirically calibrated probability; shared accounting rules govern prose and existing artifact strings. Confidence bands remain:

• <= 0.80: incomplete; continue recovery or report blocker.
• 0.80 < confidence < 0.85: very questionable; stronger evidence is required.
• 0.85 <= confidence < 0.90: cautious-low; objective recovery evidence and remaining limits must be explicit.
• >= 0.90: fair, not automatic; material residual limits still belong in result.

🗺️ PR review-to-remediation

Review completion is executable: shared/find-review-report.py --complete-run <run-directory> reruns both artifact validators against a promoted schema-v3 result, validates the explicitly named completed run independently of newer runs, and emits only digest-bound final text; latest-review admission for remediation remains strict. The optional isolated reviewer route revalidates retained JSON against its frozen source and diff when accepting current evidence, even if recorded output hashes match. A notes-only run is matching-review-incomplete, not missing evidence; newer incomplete or malformed reviews block older assessed fallback. A later collection failure cannot clear intervening incomplete or unpromoted review. For an incomplete requested review, explain the failed checkpoint, preserve preliminary evidence, and require the missing-review decision before continuing current-online/user findings or eligible preliminary hypotheses through normal selection and source validation with the requested report limitation disclosed; do not present “Review handoff blocked” as a terminal response for that work. Never treat notes as a completed review or select an older verdict. Other failures lead with a plain-English cause and continuation and never masquerade as completed review. Code Review first supports instruction-bounded native inspection route whose reviewers receive full role card first, then scope inventory and relevant source/diff/evidence as untrusted input, and return text only; prohibited tool use is detected and rejected, not prevented by sandbox claim. Schema-five inspection also accepts call-ID-bound task-path receipts when legacy activity events are absent, requiring unique runtime child lineage and creation within the recorded spawn interval; all context, model, tool-use and terminal-output checks remain mandatory. Missing or ambiguous session logs fail closed. Strict portable launcher admission and post-run validation remain required only for optional portable route and other consumers.

Evidence collection, review closure, and remediation boundaries

Assessed reviews of changed production Python require sw-engineer as the primary source reviewer; tests-only reviews do not. New presentation-7 review headers add a compact Reviewers row, such as Software engineer [3], QA specialist [2], Doc scribe [1]. Presentation-7 reviewer names and finding authors display roles only; execution provenance remains in machine evidence. Earlier presentation profiles retain their original labels and parenthesized scores for byte-exact archive validation. The current source-rating-family legend sits immediately below: 1 = Approve · 2 = Minor changes · 3 = Major revision · 4 = Insufficient, but a good initiative · 5 = Block. Stage 4 concerns promising but substantially incomplete implementation; stage 5 requires documented project-direction or binding-constraint conflict. Completed undecidable scope uses null with blocked readiness. Historical absent-family reports retain 4 = Insufficient evidence and 5 = Block / Reject. Each rating covers that participant's scope; skipped roles are omitted, and ratings are never averaged into the final verdict. Findings add an Author column preserving all contributing roles after deduplication. Aggregate prose summaries, existing header fields, verdicts, confidence and evidence remain; historical reports stay readable as unverified archives. Current schema-3 results retain exact reviewer-rating binding for completion and remediation.

GitHub reads use the github-read Codex permission profile when selected for a fresh session with codex -c 'default_permissions="github-read"'. This checkout defines a project-local profile; explicit setup or repository sync installs the separate managed Codex-home profile for other projects. Adding the plugin alone cannot install that managed profile. Neither profile selects itself by default. Both extend :workspace, route requests to GitHub domains through the network proxy, and permit .git writes under workspace roots for all commands in the selected session. Setup also installs the network-disabled local-workflow profile and selects it when a default is missing; schema-4 state migrates earlier plugin-generated defaults while preserving explicit user choices, and migrates a sole root sandbox_mode = "workspace-write" to default_permissions = ":workspace" with a backup; other root sandbox settings or sandbox_mode in a named [profiles.<name>] entry remain blocked because they can override the selected profile. It also refuses to newly enable the global proxy when an existing named permission profile has network.enabled = true. Removal retains an ordinary :workspace default when surviving user permission profiles need one, and refuses to turn that proxy off while any remaining named permission profile has network enabled. Other loaded configuration layers can still override the opt-in selection; setup validates only the selected Codex home's config. Host restrictions still apply and may block access. The profiles control network destinations, not HTTP methods or executable identity; workflow helpers retain their own operation checks and evidence requirements. Use the current effective grants described above even when profile identity is omitted; absence of a label is not disabled network access. Never use codex execpolicy list to discover the profile.

• Review intake: $codex-rig:code-review #123 collects contributor intent from PR title/body, comments/reviews, target-branch evidence, exact local PR head, and locally derived diff and complete changed-path inventory before producing structured review artifact. Collection starts in temporary timestamped run; after authoritative pr.json succeeds, run creator promotes it to next numeric .reports/codex/code-review/pr-<number>/run-<NNN>/ directory and that printed path owns every later artifact. Assessed PR handoffs begin with snapshot rebuilt from those run artifacts: PR number/link, author, GitHub check status, intent-based type, and review suggestion; validation rejects missing or replaced fields and suggestion that disagrees with structured decision.

• Terminal closure: After successful collection it may emit evidence-backed terminal close decision before detailed review for one of FALSE_GOAL, BREAKING_CONDUCT, WRONG_SCOPE, WRONG_PROVENANCE, DUPLICATE, UNADDRESSED_REVERT, SPAM, or ARCHITECTURE_VIOLATION; ambiguous evidence always continues to detailed review, and decision never closes, comments on, merges, or otherwise mutates GitHub.

• Review routing: It prefers independent QA/challenge passes for broad or high-risk diffs and conditionally triggers architecture, security, CI, docs, data, performance, research, or web evidence when detailed review proceeds. If launcher is unavailable, documented parent-serial substitute may continue review but is not independent; an unwaived expressly user-required independent pass remains unmet and withholds completion. An explicit waiver uses the separate revised-scope fallback and preserves every source, evidence and completion gate. Incomplete context or provenance is disclosed, and unsupported conclusions are withheld. Routing evidence and triggered-role reasons are always non-empty JSON string arrays, so validators can distinguish malformed output from assessed review. Fork PR checkout uses the same GitHub runtime approval route as the reader and collector. With existing grants it runs without another prompt. When capability is missing, recurring use requests the exact installed launcher-plus-helper prefix so the native host can offer Approve once or Approve always where supported. Remembered scope spans later targets and report destinations for that helper; it is not a per-PR or content-digest grant. A nested gh pr checkout rule does not cover the outer helper command. Force operations, unrelated changes and branch-conflict recovery retain their existing protections. See Reusable GitHub approval.

• GitHub transport: shared/github_read.py is sole GitHub data transport: it prefers authenticated gh but never reads credentials; permits only audited built-in view groups (gist, issue, pr, project, release, repo, ruleset, run, workflow), REST GET, and GraphQL query operations; and retains no CLI failure output.

• Permission recovery: Missing or unknown required runtime access requests approval for the complete reader or collector when allowed; approval resumes the workflow without requiring profile installation. A network error alone is not denial. Explicit denial or a non-overridable restriction stops recovery. Failed public fallback preserves safe CLI diagnostics when both transports have the same failure classification.

• Network boundary: The profile allows network access to GitHub domains through the proxy for the owning helper and its nested Git/GitHub requests. Destination access does not authorize remote mutations in workflow scope, and host restrictions remain controlling. The profile cannot enforce HTTP methods; helper-side validation and workflow rules govern which operations are used.

Release communication uses notes [base..head] [--changelog] [--summary] [--migration] [--append], prepare <version>, audit [version], or demo [range]; base->head is also accepted. Notes writes a structured draft; prepare writes draft, changelog excerpt, executive summary and migration guide in the established release directory while preserving canonical changelog history and technical detail. Audit is read-only; demo must execute before completion. Release-line ancestry, patch equivalence and final tree state determine which changes remain unreleased; subjects and default-branch PR lists are insufficient. Credits include human noreply authors, coauthors, and docs/test contributors. Incremental runs preserve hand edits, reconcile stale summaries/examples, and advance the checkpoint only after validation. Readiness appears as Check | Status | Evidence | Blocker / next action in both the report and final handoff. Local-only metadata limits remain explicit; publication and installation propagation remain human-owned.

Passing versioned releases also require a machine receipt for exact Git candidates, published-tree subtraction, claims, identity-bound credits, changelog preservation, and actual artifact destinations. Bot authors/coauthors and known PR bots remain in a separate classification-evidence inventory with one aggregate credit; they are neither silently dropped nor individually credited as humans. Summaries and migrations have explicit section contracts; a selected changelog must be the complete canonical target excerpt. The separate shared/release_evidence.py record-demo command records authorized local execution, script/output digests, failures and timeouts; validation never executes a demo implicitly. Published-patch checks conservatively reject changed same-file tree entries. Receipts do not prove prose truth, bot classification truth, remote PR discovery completeness, or hosted capacity; those limits stay visible in review.

• Retry and denial: When the host blocks a required network operation, follow the host's approval and denial controls. Do not treat profile installation or a prior successful request as an override of a current host restriction; a denial stops the operation.
• Evidence tiers: collect_pr.py separates core source evidence from supplemental online evidence: PR identity/body, base-repository identity, target ancestry, exact PR-head checkout, and local diff are mandatory; GraphQL review-thread resolution status and derived statistics may degrade with explicit artifacts and confidence gaps.
• Checkout and ancestry: GitHub CLI remains primary for metadata. In review mode, the collector fetches and verifies the exact PR head, then creates a detached worktree at that immutable commit; it leaves the invoking branch, index, and tracked files untouched even when that worktree is dirty. Source inspection and project gates run from the recorded review worktree, with artifacts retained in the source repository; a failed or dirty generated worktree is retained for diagnosis rather than removed automatically. Remediation mode remains distinct: it always tries gh pr checkout <canonical PR URL>, even at matching HEAD, and requires an attached branch; after failure, only a verified same-repository direct checkout of the actual PR branch is allowed. Fork PRs may use the bounded adversarial recovery route only on explicit user request, then return to successful attached gh checkout; otherwise remediation reports the checkout blocker. No remediation exact-commit fallback, generated branch, or manual tracking repair is allowed. The collector fetches target and PR tips without persistent ref destinations on the normal path and captures verified commit IDs; the same-repository fallback may perform a guarded local update of an explicitly selected remote-tracking ref from the already fetched, verified PR head, preserving divergent or concurrently changed refs. Both tips must be fresh before conflict resolution; use captured immutable IDs, never a later FETCH_HEAD. Target advancement is integration context, not PR finding or merge blocker; genuine divergence remains collection failure.
• Remediation destination: Before PR edits or target integration, shared/remediation_branch.py prepare performs read-only verification and writes a schema-2 prepared receipt; it never manually creates, switches, or re-tracks a branch. The receipt binds the attached branch to the exact PR head, local branch name equal to the collector's recorded local_branch, branch.<name>.merge=refs/heads/<headRefName>, and an effective push destination identifying the original PR head repository through a named remote or fork URL. Missing/wrong repository identity, tracking, or custom push refspecs stop without changing local work. Successful gh fork checkouts may retain a local <fork-owner>/<headRefName> alias without branch renaming or a recovery loop; the remote merge ref remains refs/heads/<headRefName>. Same-repository direct fallback still requires the actual head branch name. This proves configured destination identity, not live write access or universal plain-push success; differing names require an explicit destination ref for any separately authorized publication. On resume, check repeats branch, worktree, name, head, ancestry, and destination checks. Show the observed branch and original PR destination; optional commits remain local and remote PR updates remain human-owned.
• Legacy remediation continuation: A schema-1 receipt can resume through shared/remediation_branch.py recover when the current branch already is the original PR branch. Recovery cross-checks the retained receipt and PR checkout metadata, last recorded authorized revision, ancestry and configured destination, then writes separate schema-2 evidence with the legacy receipt digest. It preserves the old receipt, local commits, index, worktree and tracking; no network or repeated checkout is needed. Subsequent checks use the recovered receipt, and an already authorized topic/all-at-once/per-finding choice continues without another mode question. A failed live check still stops; recovery cannot move work to a different branch or repair tracking.
• Working-tree identity: Matching HEAD is necessary but insufficient. Review source verification checks the newly created detached worktree for exact SHA and clean source state; dirtiness in the invoking worktree is preserved and cannot be confused with reviewed PR source. Remediation retains its before/after checkout overlap preflight. PR review passes the recorded checkout path as run_gates.py --worktree with --expected-head; the runner executes gates there and binds that path in before/after source receipts, so a different checkout at the same SHA cannot stand in for the reviewed worktree. For ordinary working-tree and path reviews, the local mirror may omit --expected-head only when the output already contains its matching collector receipt and source snapshot; the runner freezes current mirror bytes and binds source-dependent gates to them. Import-bound pytest accepts local added files only through exact snapshot membership and byte proof, while clean PR tests still require tracked origins. New PR review gates require the verified base...head range for git diff --check, not the clean worktree's empty diff. For Python tests, the import-bound pytest mode records actual post-test module origins from the selected interpreter; an editable environment still targeting the invoking checkout fails. Free-form or non-Python tests cannot claim source-bound tests:pass; unsupported import patterns remain inconclusive. Release checks keep their separate clean-commit gate contract.
• Historical and assessed results: Historical merged/closed PR evidence uses GitHub's pull ref, exact SHA verification, and an isolated detached review worktree, but merge decisions and code-remediate remain OPEN-only. Every assessed non-approval PR result includes findings/action table only for actual findings or review gates.
• Declared-package gaps: When a review claim's verification run is blocked because a Python package is absent or outside the reviewed head's declared specifier, Code Review unpacks the matching wheels into a run-local overlay directory and runs the selected tests over the existing project environment with that overlay first on PYTHONPATH, instead of recording a missing-tool gap. Only a package the review base already declares qualifies, with the reviewed head's specifier; a package the reviewed head newly adds becomes a new dependency finding, never an overlay. A wheel-only dry-run on the default index checks support first, sources are never built, the project environment stays unchanged, and the artifact records the evidence or the concrete reason the overlay could not run. The reviewed head's specifier must be a plain version range: a direct reference, URL or path becomes a non-index dependency reference finding, never a fetch. A name that the review base or the user routes to any other index — through [tool.uv.sources], a [[tool.uv.index]] entry not marked explicit, a requirements index option, a lock-file registry, or the user's index environment variables or uv/pip configuration — or whose routing cannot be determined is never fetched and keeps the gap non-default index dependency <name>, because a public project with the same name would otherwise be downloaded and executed. Any UV_* environment variable outside a short allowed set also keeps the gap rather than being cleared, so only the default index is read and a user's index setting is never silently replaced. The download is a separate, non-executing command; only it may receive a one-time network approval for the exact command. The test run that executes reviewed and downloaded code never shares that approval and never leaves the sandbox, so neither an escalation nor the reusable pytest approval covers it. Neither step counts as preapproved recipe or dependency-download work. Contract: shared/native-skill-contract.md §Ephemeral Dependency Evidence.
• Collection failure: If core collection fails before source review, report PR Review Availability: unavailable, specific reason, source findings not assessed, and merge decision not made. New unavailable results require all five PR checks explicitly not applicable; a print-only diagnostic is never passing PR verification. Keep actual recovery diagnostics separately. Safe Git cause categories distinguish ref-update rejection, missing ref, transport, explicit permission failure, unavailable repository, and unknown cause without retaining raw stderr. Repository absence does not prove authentication failure. For remediation, retain the failed gh attempt, fresh local identity/state, and classified cause; use only the verified same-repository original-branch route or, for forks, the shared bounded adversarial recovery loop only on explicit user request; otherwise report the recovery blocker. Never silently retry unchanged evidence or use detached/generated-branch/manual-tracking repair. Clear previous target identity before a new attempt, start the retry in a fresh artifact/run directory that retains the failed attempt and links recovery evidence, and after successful recollection consume that verified new attempt directory for prepare, diff, target, and every downstream check—never the failed pr/ artifacts or a silently cleared/reused path. Resume the original workflow only after authorized recovery verifies fresh attached source. Do not turn process failure into a PR finding or merge recommendation; authentication recovery remains private and user-owned.
• PR number default: Code Review, Code Remediate, and PR-mode Assess bind a bare PR number to valid GitHub origin even when fork remotes exist; without origin, they use the sole configured GitHub repository. An explicit canonical PR URL takes precedence and must match a configured remote. Missing or conflicting default identity requires a URL. Direct numeric collector calls remain fail-closed on ambiguous remotes; the skills pass the locally bound URL instead.
• Fallback eligibility: Public PR metadata fallback is limited to github-network, github-auth, github-rate-limit, or command-timeout failures and requires a canonical URL matching a configured GitHub remote, or a direct numeric collector target with one distinct configured GitHub repository identity. Ambiguous or unsafe direct numeric targets, permission, not-found, and unclassified failures fail closed. GitHub GraphQL object-resolution failures remain not-found errors instead of activating network fallback.
• Fallback evidence: The HTTPS client uses Python's default CA store and recovers an available system CA bundle only when that store is empty. The fallback normalizes limited metadata and may verify refs/pull/<number>/head in an isolated detached review worktree, derives local diff, and records unavailable evidence in online-review-summary.json; it cannot establish private PR evidence or alone satisfy remediation's attached-branch checkout contract. Same-repository remediation still needs its verified original-branch route and all degraded-evidence gates. Explicitly user-requested fork remediation recovery uses the shared adversarial procedure while retaining its stricter caller budget of at most three rounds including W_0; no new loop helper or hand-coded recovery framework is permitted.
• Fallback gaps and diagnostics: Review and remediation list sorted IDs github_provided_file_list, mergeability, review_decision, reviews, and top_level_comments in their online triage/action evidence, add exact gap Public HTTPS PR metadata fallback omitted evidence: <sorted IDs>., and cap final confidence at 0.89. Raw CLI stderr is never persisted; terminal diagnostics may include safe failure_reason enum.
• PR refresh: $codex-rig:code-remediate #123 collects current online PR items and verified local checkout directly; $codex-rig:code-remediate #123 +review additionally finds newest matching assessed review artifact, refreshes same core PR/body/checkout/local-diff evidence, records supplemental review-thread coverage gaps, evaluates merge-conflict risk, and presents resolution table before editing.
• Current-session reuse: $codex-rig:code-remediate review uses the latest assessed review result recorded in this session without starting another review or collecting PR comments. Missing completed evidence stops report admission; concrete user findings and eligible preliminary claims can still be checked against the current source and remediated after normal selection. The missing review evidence remains explicit. A newer closed result never supplies source findings or permits fallback to an older verdict.
• Remediation closeout: missing declared Python backends trigger the shared dependency-overlay procedure before an environment-blocked outcome. Statistical confidence disclaimers alone create no calibration prerequisite; explicit calibration checks and actual coverage gaps remain actionable. Capture ownership before edits; a late baseline can recover only from retained pre-edit evidence. remediation_finalize.py append --help documents accepted event fields and examples; after review closure, regenerate and validate the current handoff rather than citing stale results.
• Package-dependent review claims: Code Review owns dependency preparation before disposition, including favorable claims and refutations. Install eligible declared wheels in the run-local overlay and execute the affected checks with source-origin proof; retain a concrete preparation failure when unavailable. Package absence alone cannot exhaust feasible verification or become a confirmed behavior defect.
• Single-pass remediation: Code Remediate collects findings, resolves selected work, verifies, and reports. Normal checks and one bounded closure-verification pass remain required where applicable; new in-scope defects do not start another review wave or convergence-score stop. Generic plan-challenge and review-to-fix loop rules do not override this boundary. Challenge Resolve, including a fork checkout recovery loop, runs only on explicit user request; remediation does not solicit an optional loop. Code Review retains its separate opt-in rule. Unfinished selected work remains explicit in the final report.
• Optional review evidence: +review requests an existing matching review; it does not authorize a new review, reviewer dispatch, paid wave, or context redistribution. A newer unpromoted candidate is never admitted by remediation directly: it runs both validators read-only and records their exact codes. When the compatibility assessment proves a deterministic repair or unfinished finalization suffices, remediation resumes the owning Code Review workflow automatically, which alone may repair or promote the run. When substantive evidence is still missing, it asks one decision: repair the existing review and add the missing coverage, run a fresh code review, or continue with available findings. Selected source fixes continue without a completed report only after that explicit confirmation, disclosing the factual report limitation. Missing proof stays open, and stale findings never replace the newest incomplete run.
• Remediation questions: Ask scope first, complete any custom selection, then ask commit grouping through a suitable native control. Discover the packaged form before falling back to async or text; its single-field route opens one scope form then one commit form and omits the work-plan question. Keep one delivery owner per decision and never echo live menus in chat. An already supplied scope skips only its question.
• Artifact recovery: Review finalization derives canonical finding/blocker content into existing notes and handoff action rows, preserving authored status, source identities and runtime proof. Rejections retain structured errors, skipped checks and an owned next action. An incomplete requested PR review requires the missing-review decision before remediation continues. Only explicit confirmation permits available findings to proceed through normal selection and source gates with the requested report limitation disclosed. A selected fresh-review-first route gates edits until the completed report is admitted. Final actions cover actual remaining source work; declined extra review requests stay omitted. Successful completion can retain status=fail for failed quality gates: the review completed, while the change still needs work.
• Reviewer evidence and feedback: When an admitted finding no longer matches current source or is unclear, remediation reads that finding's reviewer evidence with shared/find-review-report.py --finding-evidence <result.json> --finding-id <id> before rejecting it or asking the user. After promotion it appends one {finding_id, verdict, sha, why} line per admitted finding to that review run's resolution.jsonl with shared/remediation_finalize.py resolutions; this is its only write into a review run. The next Code Review of the same PR reads the newest earlier ledger with --prior-resolutions <run-directory> and tells its reviewers to confirm prior fixes and not to re-report rejected findings without new evidence.
• Review/remediation parity: Reviews distinguish source fixes from missing verification. Remediation performs selected evidence work even with zero code edits: obtain fresh permitted independent coverage, retain unprovable historical isolation limits, and reuse CI/backend closures only for the source they prove.
• Blocked outcomes: Remediation headlines name the current blocker; the summary cites current-run evidence and the next owner/action needed to proceed. A bare Blocked label is insufficient.
• Prompt ownership: Show the indexed ledger and report path once, then use one permitted question route. Prefer an available synchronous question control, then the packaged native form tool. The scope menu offers All, Required (acceptance obligations), Suggestions (explicitly optional improvements), and custom selection. The packaged form uses a separate index/range/severity text question after Custom selection; built-in forms use their native custom-input field. Empty groups stay empty. Scope, commit, and work-plan decisions never share one answer field; all supplies scope only; standing Git approval is independent. The route owns the question and choices; do not repeat them in chat. Async requires current evidence of usable delivery and answer lifetime. Editing waits for a scope-bound answer; a clear conversational reply can resolve one unchanged, unambiguous pending decision. Exact-token and runtime-permission requirements remain separate. Parent-owned or sequential execution needs no fallback-choice question.
• Work buckets: Selected findings form coherent specialist/domain buckets of at most five items. Independent buckets run in isolated worktrees concurrently by default, including when their exact shared files need parent reconciliation after join. Indivisible or dependent work, and work without required runtime capacity, proceeds parent-owned or sequentially with the concrete reason and actual mode recorded, without an approval prompt. A workflow-default parent-only route records exactly one nonempty Ineligibility reason: <reason> line under ## Parallel Approval; the validator rejects common placeholders, while the parent checks the reason against evidence.
• Parallel child verification: Before plan hashing, preflight exact child commands against unchanged disposable baseline, separating expected failing regression assertions from launch/configuration errors and requiring zero ignored or untracked output. Freeze only byte-identical command text; changes require a new digest and dispatch record. After implementation, every approved child check must pass before handover or integration, with intended postimages unchanged and no generated output. Never delete verification output to manufacture clean handover; incompatible checks continue parent-owned or sequentially without an approval prompt. Authoritative coverage and full gates remain parent-owned after source application.
• Conditional lifecycle detail: Remediation loads its packaged references/parallel-lifecycle.md only when evaluating or executing parallel-specialist plan. Parent-owned and sequential routes retain common scope/approval/output checks without loading unused production lifecycle detail; parallel routes still load every containment, rollback, cleanup, and evidence obligation.
• Plan revision: Changed parallel plan bytes require a new digest and dispatch record; parent-only or sequential fallback records the actual route without a user-choice prompt.
• Validation: The validator rejects missing/duplicate item coverage, hidden source records, invalid owners or context packs, path aliases or ancestor overlap, excessive bucket size, artificial per-finding fan-out, and dispatch evidence not bound to current plan. Exact shared files require a verified integration result, with a parent reconciliation record when patches collide.
• Recap: The final recap is rendered from validated per-item machine ledger and repeats every ingested item in compact outcome table, including implemented, rejected, skipped/unselected, already-closed, and unresolved dispositions.
• Compact remediation tables: Initial selection and durable resolution tables show each contributing source as report [<report-file>:<line>], report [<report-json>#<finding-id>], online [<comment|thread|review-id>], or user [<local-finding-id>]; online references use stable IDs, not URLs, and grouped pointers use one plain space so terminal output never exposes HTML tags. A source cell is unique pointer, never prose or evidence. The final chat outcome table shows each finding and its resolution once; the linked action-items.md ledger retains complete sources, resolution explanations, evidence, and next actions. Exact duplicates retain every compact pointer in source order in the ledger and machine metadata. Resolution, evidence, owner/status, and unresolved next actions remain mandatory.
• Remote boundary: The workflow never pushes, comments, merges, or publishes remotely.
• Detailed review routing: The shipped skills/code-review/review_routing.py helper derives mechanical tier and exact file/line evidence from collected diff artifacts before specialist selection; public API compatibility is assessed normally and public-API touch alone is not automatic HIGH_RISK. The terminal validator imports same derivation, so reviewers never calculate or copy those fields manually.
• Parallel review: Assessed native schema-eight reviews retain a validated output for every required role, including rosters above four. Launch largest frozen contexts first with stable role-ID ties, keep at most four allocated child slots, and refill proven free slots at observed parent opportunities before another wait. All roles join before assembly or a dependent wave. Complete authentic independent coverage with uninterrupted free-capacity dispatch admits naturally fast children even when their substantive intervals do not overlap; retain truthful independent-spawned mode. Unrelated tool work or premature waits with pending roles and free capacity reject. Genuine validated no-child capacity refusal plus ordered queue/refill and complete all-role evidence can also admit a smaller pool, including one slot. This is not generic serial fallback, role substitution or omitted coverage. Terminal PR close and genuinely single-role review are exempt. Historical strict readers and portable schema-v2 retain their ceilings and overlap gates.
• Remediation intake: Assessed non-approval results retain validator-checked Review Findings and Merge Blocks table that becomes remediation intake contract.

Historical .reports/codex/review/ and .reports/codex/resolve/ artifacts remain readable fallback inputs. code-review and code-remediate are canonical names.

Use $codex-rig:assess (or $assess when the alias is available) for evidence-first analysis; it replaces change-analysis. New artifacts use .reports/codex/assess/. Existing change-analysis reports remain readable, but the old skill name is no longer registered. Refresh the installed plugin to discover the new name.

Audit starts with a map of material flows, dependencies and shared state, then alternates focused falsification with checks against consumers and sibling flows. New evidence or source drift reopens affected assumptions; final coverage distinguishes inspected, unresolved, excluded and inapplicable paths. This bounds conclusions without treating a completed audit as proof that every workflow is safe. The map and cycles live in the existing workflow-exploration.md; no additional report schema is required.

🎚️ Calibration

Offline and live calibration boundaries

The packaged runner supports plugin layout directly:

plugins/codex-rig/bin/python plugins/codex-rig/runtime/calibration/run.py --layout plugin --root .

It validates packaged skills, role cards, shared contracts, behavior fixtures, accepted routing evidence, confidence scoring, and known workflow leaks. Plugin-layout calibration checks that all fifteen roles have a distinct related task cue in their Trigger lines; this verifies declared routing, while live use requires live observations. In a source checkout, calibration compares the shipped behavioral case file's integer schema_version with its own HEAD version; a new version family starts at 1 and an uncommitted edit may advance only one step. An installed cache reports that version check as skipped because its packaged fixture is immutable; source layout reports a missing .codex fixture as skipped. The offline CI harness shadows network and LLM commands, uses isolated home, and writes compact failure artifacts without contacting LLM.

Paid live A/B calibration is separate, explicit, and never implied by offline result.

🧾 Approval prompts and commit handoffs

Collection prebriefs supply context, not standalone confirmation questions. For an action that requires separate workflow consent, obtain any missing consent through a permitted native control; existing preapproval skips reconfirmation, and runtime permission stays separate. Allowed GitHub reads need no separate workflow consent. Commit readiness requires a local commit-plan.md artifact and ordinary selected closure or the explicit local snapshot exception below.

Rule 43a governs automatic finding-fix commits, not the earlier checked target integration. An explicit user commit request can override report sequencing: finish the required verification and shared commit checks, record the request and pending report checkpoint, commit, then complete report validation. Standing approval or a grouping preference alone keeps the normal sequence; failed-check and ownership protections remain.

Every new remediation handoff records a commit disposition before final output: pending choice/execution, blocked, no eligible changes, explicitly declined, or committed. Ordinary readiness keeps passing checks and selected closure. An actual explicit local commit request or answered commit mode permits a local snapshot despite failed checks, timeouts, incomplete fixes or a known regression; the result and open findings remain failed/unresolved. The commit plan records the actual request, complete owned scope and remaining verification; the commit message discloses every limit. Standing approval/default grouping alone does not activate the exception, and runtime denial, hook failure, ownership/destination ambiguity or open security/critical findings still block the affected mutation. Earlier matching authorization is reused; pending native questions stay pending across resume. Rendering keeps commit disposition separate from quality, and candidate validation requires request/verification evidence for failed snapshots. Historical saved reports remain readable; no installation is propagated automatically.

Commit summaries name the local branch and absolute checkout path and distinguish local commits from publication and report promotion. Remediation finalization adds a clickable source-checkout link from the prepared branch receipt, preferring the recovered receipt when present. Git status claims identify the inspected checkout; a clean remediation worktree does not describe changes in the invoking folder. The link records location only and does not replace live branch or status verification.

Codex questions use a short shared guide, shipped locally by this plugin. The root uses a permitted question route with meaningful presets and built-in custom input; children hand decisions back to the root. Detailed approval/recovery rules load only when needed. Host restrictions still apply; this does not override a plain-text-only host.

Explicit local and PR review intake validates canonical result.json with both artifact validators before remediation consumes it. Metadata-only, draft, altered-evidence, and differently named files fail closed. Automatic discovery remains PR-only and validates its selected result before returning it. PR intake defaults to the recorded producer thread, not the consuming session; --parent-thread-id and --codex-home overrides never bypass provenance checks. Local completion retains current runtime defaults.

Same-directory gate reruns archive prior runner-owned evidence under gate-attempts/<NNN> before executing. A failed, timed-out, or missing-command check cannot become skipped; re-execute it through the canonical runner. Unreadable or incomplete prior evidence blocks overwrite and requires diagnosis.

Review and remediation check current PR state before report lookup, run allocation, checkout or specialist work, including resumed and +review requests. Closed or merged PRs are reported immediately and stop intake; local report-only work stays local. The early read validates repository identity and uses the existing GitHub reader permission boundary.

New final handoffs use presentation_version=8 with compact tables and evidence paths in separate - Item: file-path lists; assessed Code Review handoffs also retain separate confidence-limit and gap bullets. Handoffs lead with a plain-English explanation, no empty Results section, one concise line for checks not run, and each recovery action shown once with its row ID. Historical handoff versions retain their original bytes during validation. Unavailable review explanations bind actual collector failure to retained safe command and checkout evidence; missing cause details stay explicitly unknown. Machine records remain complete, historical rendered bytes stay unchanged, and explicitly requested exact caller output is preserved.

Every skill keeps its normal closing gate after user intervention, recovery, compaction, or repeated invocation. Resume at first unmet checkpoint using still-valid evidence; do not replay completed work or replace required final summary/tables with informal recap. Passing tests or completed notes do not replace validated results. Non-artifact skills retain their own final verification rather than inventing report artifacts.

Review/remediation reports keep one canonical record per finding, not one source per repeated summary/action/confidence mention. New review records add title, issue, required change, evidence and closure criterion under finding_records_version=2, and validator requires that marker on every new schema-v3 assessed candidate under both filenames — there is no bare-record fallback for new writes. Older schema-v1 ID/severity-only records and historical rendering remain readable. Real report/online references stay intact; related report mentions do not inflate source counts, and each comment has one owning item.

All-closed remediation records empty selected/deferred indexes without implying user confirmation. Grouped output keeps complete evidence in named detail blocks; only durable ledgers and historical symbol layouts require visible symbol definitions.

Selection preserves item types for report-gate count reconciliation and rejects output paths that overwrite its input or follow symlinks. Report identity is the review run: every view under one pr-<n>/run-<NNN>/ directory shares it, while separate runs or report roots may reuse finding IDs. Outside that layout, distinct report files can reuse finding IDs and verified cross-file views use explicit shared report_id. A shared test or closure criterion alone never merges findings. New local reviews with findings retain same canonical action table as PR reviews, including minor-change outcomes.

Before remediation selection, shared/final_handoff.py selection --input <run-directory>/selection.json --out-scope <run-directory>/resolution-scope.md validates inventory and derives counts; --check verifies existing bytes. shared/remediation_finalize.py removes hand-copied remediation bookkeeping: workplan writes the managed workplan sections from the frozen bucket plan and dispatch record, append adds a staged <ledger>.rec record to the append-only closure-log.md or validated resolution-events.jsonl, ledger rebuilds the action-items.md resolution table from those events and workplan renders bucket statuses from them instead of in-place edits, and finalize derives copied metadata and handoff fields, renders, writes, and validates the candidate in one call, returning every validator error with a repair hint; --promote renames only a passing candidate. shared/validate-artifacts.py --all-errors gives the same one-pass report for any skill; the default fail-fast output is unchanged. New remediation selections use presentation version 4; final handoffs use version 5 with a canonical Selected column. Both retain distinct user, report and online sources; historical versions keep their documented readers. Requested report admission records completed, preliminary or unavailable evidence. Noncompleted admission preserves exact source, diagnostic and selection bindings plus an open evidence obligation, and permits only a failed result that accurately reports completed fixes. It never starts another review automatically. Presentation version 3 uses # | Severity | Finding | Resolution proposal | Sources, with compact derived tags such as report ×1; online ×2. ID-only supporting groups retain context, acceptance checks and full evidence references once in saved reports. Terminal selection stops after the complete table, then shows the available PR Relevance Summary and Full report link; it omits all per-item detail blocks. Pending selection never implies user deferral. New final review/remediation tables use layout=concise: assessed review rows include short resolution proposals, with per-finding context, evidence and closure details retained in a derived full-report section that is validated before compact output can be emitted; the snapshot header links that report; remediation rows show ID | Severity | Finding | Selected | Outcome for every ingested finding, with Yes/No selection bound to confirmed scope. Detailed reasons stay in the linked Markdown ledger. Terminal reports prefer short sentences, labelled bullets, counts and evidence links; workflow completion, remediation closure, checks and next actions remain distinct. Exact machine cells and coverage remain validated. Finding names problem; Context explains it. Installed plugins must be deliberately refreshed to receive this behavior; historical reports are not rewritten.

Strict portable reads retain launcher-compatibility admission. For Implement and Manage, only explicit parallel-read enters that route, and missing controls stop dispatch; auto follows the shared proportional selector described above. Code Review keeps its own selector and route admission unchanged. Code Review's instruction-bounded native inspection route is exempt from that admission: current paged schema-seven/eight prompts require text-only findings without further tools and request no copied hash header. Runtime dispatch, complete reads, terminal output and joins establish provenance; historical schema-six checks remain strict. Only schema-eight native-wave batch admission with the current pinned reader and paged v7/v8 recipe accepts either no marker or one exact independently derived marker line at the start of decoded output, using existing text/newline handling. Raw output stays unchanged; schema-seven, standalone and representation-repair parsers remain strict. Historical schema-five runs supplied evidence inline with no child tools. Neither route authorizes repository execution, edits, installation, network, credentials, or escalation; validation detects rather than prevents violations. Review categories determine depth, not execution permission. An assessed review with two or more triggered roles needs validated specialist coverage. Current native schema-seven/eight paged inspection also admits naturally fast children after complete uninterrupted roster dispatch with free capacity; schema eight additionally admits verified actual capacity refusal and ordered queue/refill proof. These admission rules apply to conditional-role-only waves as well as core-role waves. Historical readers retain their overlap requirements. It reports independent-spawned when there is no overlap, never a generic serial fallback. Terminal PR closure and a single triggered role remain exceptions; historical overlap gates stay strict. A documented parent-serial substitute may continue inspection, with incomplete parallel coverage reported as a failed review. Requested role settings, inherited parent settings, supported launcher controls and observed effective controls remain distinct; no plan declaration proves sandbox isolation. A workspace-write launcher without verified child overrides remains unsupported for strict portable independent review. Diagnose this as process limitation, not source defect or failed launch; no live compatibility is claimed by offline tests.

Versioned result paths must resolve to run's canonical result.json, including while validating result.candidate.json before promotion. Confidence gaps are nonblank and unique, with exactly one declared closure each. Assessed handoffs bind Review Decision / Recommendation: <recommendation>. to structured recommendation; approval requires zero findings and minor-changes forbids critical/high findings. Both approving recommendations require passing result status and no failed checks. Historical assessed records used metadata.review_findings=[{"id":"CR-1","severity":"high"}] (or []); new records add canonical descriptive fields listed above, with exact per-severity totals and string severity values; malformed JSON types return stable validation error. Optional operational_blockers=[{"id":"G-1"}] declares non-finding actions separately. Notes and final action rows cover those stable, unique, disjoint IDs exactly; unknown, missing or duplicate identities fail. Source assessment must establish IDs before table construction. Historical schema-v1 and schema-v2 reports remain readable; new schema-v3 producers must supply identity lists rather than silently downgrading.

For every intentional approval request, Codex keeps detailed safety and effects pre-brief separate from runtime prompt. The prompt reason is short plain-English question about outcome or material effect; it never duplicates command syntax, arguments, flags, paths, multiline content, or full pre-brief. Reusable approval uses only justified short categorical safe prefix, while one-time or high-risk commands omit persistent prefix.

Targeted pytest runs in fix, challenge, reproduction, and acceptance loops add -p no:xdist when neither command nor pytest addopts requests parallelism, because plugins such as pytest-rerunfailures open a localhost socket whenever xdist is installed and the sandbox blocks it. When selected work still needs escalated pytest, Code Remediate requests one reusable approval right after scope selection, limited to the repository's exact pinned test-runner prefix and disclosing that approved runs, including repository conftest.py, execute unsandboxed for the rest of the session. Canonical run_gates.py test gate keeps the configured command; its escalation stays one-time without reusable prefix.

shared/test_targets.py picks the loop's tests from the change set: codemap-py test impact when a launcher is available, otherwise test-name and import heuristics, plus the sandbox-safe flag decision. Loops never run the full suite per finding or iteration; it runs once at the canonical gate. Code Review's source-bound test gate is its final gate and always runs the project's full selection; collected CI results supplement but never replace it. Child-agent waits use one blocking wait_agent with a 30-minute default per-agent deadline, never list_agents or sleep polling, and plan updates ride with real work. Each wait return requires a visible status before another call: completed/expected counts, pending roles and elapsed time, last observed event or no new progress evidence, deadlines and next action. Empty returns establish neither progress nor failure; waiting requires an outstanding accepted dispatch.

Codex-created commit handoffs identify every commit by hash and title, summarize behavior and affected surfaces, list exact verification evidence, disclose residual limits, and explain boundaries between multiple commits. For ordinary finding-fix commits, code remediation asks grouping after scope; approved task-owned merge commits do not enter that menu. Under a local Git approval grant the recommended/default grouping is all at once, including a dismissed or unanswered preference. An explicit decide after verification still defers the decision; leave unstaged still prevents committing. Without a grant, an unanswered preference keeps the later opt-in offer. Choosing a commit mode upfront (all at once, coherent finding topics, or each safely disjoint finding) or leave unstaged is an explicit opt-in that applies after verification only while paths, destination, grouping, and gates still match; otherwise Codex asks again then. It leaves changes unstaged when required authority is absent, ownership cannot be proved, or units overlap. A pre-edit worktree baseline, clean-index check, explicit-path staging, and exact committed-path comparison prevent unrelated or pre-existing user changes from entering remediation commit. Codex shows exact path list and complete message in chat, stages and commits in one owning command, rtk git add -- <paths> && rtk git commit --cleanup=verbatim -m <message>, using existing filesystem grants without escalation when Git metadata is writable, passes message literally as one argument, and verifies stored message and committed file set afterward. Argv-only tools and shells without && fall back to two calls. No agent-created message file, draft-file approval, or cleanup; full message can appear in runtime approval details and process arguments. Runtime permissions and hook approvals remain enforced; existing matching allowances are reused. POSIX command text uses shlex.join or equivalent literal escaping and a non-executing syntax check. A proven pre-execution parse error with unchanged HEAD, index, worktree and merge state permits one corrected attempt under existing authorization; verified staging-only progress resumes at the commit segment, and an already-created commit is verified without duplication. Actual denial, uncertain side effects, hook failure, concurrent changes, or message drift stops the affected mutation for diagnosis. Independent authorized checks continue, and successful recovery resumes the workflow without a new request to proceed.

Workflow command preapproval

Repository session-policy sync selects native approvals_reviewer = "auto_review" and adds the scoped workflow policy through [auto_review].extra_policy. It supplements the existing approval policy, including any user-owned [auto_review].policy; it never replaces it. The policy covers every user-invoked skill and flow in this project's codex-rig@borda-ai-rig, codemap-py@borda-ai-rig, and bridge@borda-ai-rig plugins, executable code blocks, inline helpers, verified path/argument substitutions, required dependency environments, configured gates, and already-authorized local commits. The reviewer checks the complete command and nested checks instead of granting a blanket interpreter or gate-runner prefix. Existing sandbox grants still run directly without review.

This provides automatic approval handling, not a deterministic guarantee that every command will execute. Managed restrictions, actual denials, protected data, out-of-scope operations, and missing action-specific authorization remain effective. If automatic review rejects a command, report its actual reason; do not call it missing user consent or route around it. Source policy tests do not establish live reviewer decisions or installed UI behavior. Direct plugin installation does not install repository session policy; root make sync-codex projects it, and a new session is required.

🩺 Optional SessionStart diagnostic

Read-only hook behavior

hooks/hooks.json defines read-only diagnostic for startup and resume. Codex discovers this default plugin hook path after install. The hook runs same shim doctor used by manager; it does not install, update, or remove shims. It also warns when the managed CODEX_HOME/AGENTS.md block names another Codex Rig root than the running plugin, or none (a block from a template before the PLUGIN_ROOT line), and names the re-render command below; it shows only the last root component and writes nothing.

Review hook command before trusting it. Declining hook trust leaves diagnostic inactive and does not disable skills.

⬆️ Update or reinstall

Use bundled $codex-rig:sync workflow for dry-run state report and approval-gated refresh, or run supported CLI commands directly:

codex plugin marketplace upgrade borda-ai-rig
codex plugin add codex-rig@borda-ai-rig
codex plugin add bridge@borda-ai-rig

A direct update installs a new versioned cache directory but leaves an existing managed global-instructions block naming the previous version's PLUGIN_ROOT, so its packaged shared/<file> pointers read the old package or a removed one. If you installed that block (repository sync or explicit setup), re-render it from the newly installed package; the root defaults to the package containing --source, so no --plugin-root is needed:

<installed-codex-rig-cache-root>/bin/python <installed-codex-rig-cache-root>/scripts/install_global_agents.py \
    --source <installed-codex-rig-cache-root>/assets/AGENTS.md --codex-home <CODEX_HOME>

<installed-codex-rig-cache-root> is <CODEX_HOME>/plugins/cache/borda-ai-rig/codex-rig/<version> for the version codex plugin list reports; on native Windows run bin\python.cmd. Pass --plugin-root <installed-codex-rig-cache-root> only when --source points elsewhere, such as a marketplace checkout. $codex-rig:sync refresh does this step itself.

Then start a fresh Codex session. Direct plugin installation does not install the managed Codex-home github-read profile; run explicit setup or repository sync for other projects. This checkout defines its own opt-in profile; select either profile only for a session that needs it. Use manager's authenticated remove action to clean prior development shims; new installation remains platform-blocked.

Repository sync never restores legacy .codex/ tree. When Codex scope is active, root make sync-codex installs or updates public Codex plugins, authenticated Codex Rig block, and the opt-in github-read permission profile, then projects repository model defaults, workflow approval policy, and personal policy as described above. The root Make target supplies no direct-script flags, so it always projects model, review_model, workflow approval policy, and personal-policy block together. The direct script's --no-codex-global-agents opt-out remains valid for leaving AGENTS.md unchanged; it does not skip profile installation. Start a fresh opted-in session after sync when GitHub access is needed.

Legacy project-to-home copies

Legacy copy cleanup warning

Older sync.sh versions — script has since been retired and its logic folded into root Makefile — copied AI-Rig files into ~/.codex/. The copied files had no durable per-file ownership marker, so Codex Rig does not delete them automatically. Before manual cleanup, back up home, distinguish AI-Rig copies from user-owned modifications, and remove only files whose ownership you can establish. An old home copy can otherwise expose duplicate unnamespaced skills or stale named-agent registrations beside plugin.

🧪 Experimental agent shims

Shim diagnostics and authenticated cleanup

The manager diagnoses prior development installations and safely removes authenticated standalone TOML files. New installation is platform-blocked because current collaboration tooling does not expose verifiable custom-agent selector. Do not infer selection from matching task name, child path, or file name.

Invoke exactly one action:

$codex-rig:agent-shims doctor
$codex-rig:agent-shims status
$codex-rig:agent-shims install
$codex-rig:agent-shims remove

• doctor: read-only runtime, active-package, manifest, helper, role-card, and filesystem checks.
• status: read-only installed-roster, lifecycle-state, target, and recovery summary.
• install: report platform block without creating or relinking files.
• remove: plan removal of intact, authenticated Codex Rig shims. No prefix-based cleanup.

doctor and status are read-only on Windows, macOS, and Linux. Windows verifies package hashes, active selection, executables, and inventory of exact codex-rig-*.toml names; it does not authenticate, adopt, or mutate those files. POSIX additionally validates lifecycle state and permissions. A blocked result names failed check and required invariant; it does not authorize repair. The optional SessionStart hook shows first bounded reason and confirms that no files changed. Do not apply recursive permission changes or delete/link-replace evidence from diagnostic alone. Existing POSIX $CODEX_HOME/agents directories are accepted when they are real current-user directories without group/world write or special permission bits; lifecycle state and recovery directories remain private mode 0700.

Prior lifecycle files use authenticated names such as codex-rig-linting-expert.toml. remove prints exact target root, operations, and SHA-256 approval digest. Review displayed plan. Type that exact digest only after explicit approval. Wrong or missing digest causes cancellation without authorized writes.

Interrupted recognized transactions use separate recovery digest. Approved recovery rolls back partial mutation or finalizes durable committed state. Repeat original action after recovery. Use remove to recover prior interrupted transactions; blocked install never enters recovery or mutation planning.

⬆️ Uninstall

Plugin removal and recovery procedure

Remove authenticated legacy shims while plugin manager still exists:

1. Run $codex-rig:agent-shims remove and approve exact plan when one exists.
2. While installed package is still available, run explicit sync_codex.py clear action to remove managed plugins, authenticated global-instruction block, and the owned github-read profile; it backs up changed configuration and preserves unrelated settings.
3. Run codex plugin remove codex-rig@borda-ai-rig.
4. Start fresh Codex session.

Removing plugin first deliberately leaves thin shim files behind. Those shims break because role cards and verifier live in removed plugin cache. They are not auto-deleted.

Recovery: reinstall codex-rig@borda-ai-rig, start fresh session, run doctor, then run approved remove. Compatible historical state can authenticate guarded cleanup. Verification failure remains blocked; no force cleanup is provided.

🧭 Lifecycle safety limits

Fail-closed mutation limits

• Foreign or marker-only codex-rig-*.toml files are never adopted, overwritten, or removed.
• Modified managed shims, concurrent drift, unsafe links/nodes, ambiguous package selection, or changed runtime binaries block mutation.
• Executable hashing is bounded consistently at 512 MiB across manager, generator, and verifier; larger files report selected path, observed size, and limit.
• Missing, malformed, oversized, aliased, or identity-inconsistent lifecycle state blocks cleanup. Manual evidence recovery is required.
• Only one exact recognized interrupted transaction can be recovered. Unknown, conflicting, or multiple residue remains blocked.
• The manager owns only its authenticated roster and state under current user's Codex home; it never cleans unrelated agents.
• Thin shims require active compatible plugin cache. Offline cached use may work; update, reinstall, and active-package validation depend on Codex CLI state.
• Hook trust, plugin install, shim install, and shim removal are separate lifecycle decisions.
• Plugin removal does not edit $CODEX_HOME/AGENTS.md or clear the sync-installed github-read profile; managed state remains until explicitly removed.
• The github-read profile extends :workspace and allows GitHub-domain network traffic through the proxy; it does not enforce HTTP methods. Host restrictions still apply.
• A successful shim transaction proves file ownership and link integrity, not runtime profile selection.
• Native Windows and network/distributed filesystems are unsupported for shim mutation. Windows workflows, package verification, sync, hooks, and read-only shim inventory remain supported.

🎯 What changed from the idealized design

Architecture evidence and remaining platform dependency

The initial design assumed plugin could bundle named agents with model, sandbox, approval, and nesting controls. Implementation evidence changed that architecture:

1. Agents became role cards. The behavioral instructions remain full-fidelity, versioned product assets, but they are no longer presented as directly installable native agents.
2. Selection became injection. Skills load exact role card and inject it into runtime blank agent. This preserves parallel specialist reasoning when available without inventing selector that Codex does not expose.
3. Inline execution became mandatory fallback. When safe blank-agent route is unavailable, parent applies card serially and reports lost independence.
4. Thin shims became cleanup-only. The transaction engine can authenticate and remove development shims, but install fails closed until runtime selection is observable and testable.
5. Project configuration left product. Models, MCP, and repository runtime defaults belong to user/project configuration. The plugin distributes reusable workflows, roles, hooks, helpers, evidence fixtures, and one inert global-instructions template. Repository sync installs it when Codex scope is active unless explicitly opted out; direct plugin installation alone leaves it inert.
6. Install identity became immutable. Released package bytes are tied to SemVer version and manifest hashes; README or code changes require new version rather than same-version cache drift.

This design delivers maintainable part of original goal today and records remaining platform dependency honestly. If Codex later exposes custom-agent selection, named shims can be reconsidered behind fresh runtime probes without changing skill or role-card semantics.

🏗️ Package layout

Installed package topology

codex-rig/
├── .codex-plugin/plugin.json
├── ARCHITECTURE.md        # parallel split, approvals, gates, evidence, telemetry
├── assets/AGENTS.md        # inert global-instructions template
├── skills/                 # 14 workflows + agent-shims lifecycle manager
├── roles/                  # 15 canonical role cards
├── shared/                 # gates, helpers, orchestration, artifact contracts
├── runtime/calibration/    # fixed, behavioral, and live calibration assets
├── hooks/                  # optional read-only SessionStart diagnostic
├── scripts/                # package, role, and shim lifecycle executables
├── tests/                  # package and cross-platform acceptance tests
└── package-manifest.json   # exact packaged file and role-card hashes

The installed cache is immutable input. Workflows never edit their own plugin root or manually patch Codex plugin configuration.

🧪 Development and verification

Pure helper docstrings include deterministic doctests for calibration, telemetry normalization, and review routing. Pytest collects these examples alongside workflow tests; regenerate package manifest after docstring edits because shipped Python bytes are hashed.

Maintainer verification commands and acceptance gate

From repository root:

plugins/codex-rig/bin/python plugins/codex-rig/scripts/build_package.py --update
plugins/codex-rig/bin/python plugins/codex-rig/scripts/build_package.py --check
plugins/codex-rig/bin/python plugins/codex-rig/scripts/validate_package.py
python3 -m pytest -q plugins/codex-rig
NO_MKDOCS_2_WARNING=1 python3 -m mkdocs build --strict

The test suite requires pytest 9 or newer: several tests use pytest's built-in subtests fixture so that each case of a shared, expensive setup still reports independently.

Packaged helper recipes use the explicit launcher described in Helper CLI Contract. On Windows, build_package.py --check, package validation, calibration, and tests are native. Authoritative manifest regeneration (--update) remains POSIX-only because released mode bits are part of package contract.

The repository's codex-rig-changelog-version pre-commit hook requires an exact ## <version> heading in CHANGELOG.md for the current .codex-plugin/plugin.json version. The heading may appear anywhere; the hook checks presence, not release-note content. This guard is pre-commit-only, not part of package validation or pytest.

The package is accepted only when generated manifest is current, every recorded file hash matches, plugin-only copied-tree tests pass, lifecycle safety tests pass, Windows collection and path behavior pass, offline calibration harness passes, and public documentation builds without warnings.

Hardening checks

The denial gate is deterministic and offline: it validates local JSON Lines transcript, requires one exact item/commandExecution/requestApproval callback followed by decline, matching resolution and declined completion, rejects output or fallback execution, and requires later local recovery item. Run its focused tests and inspect supported probe interface with:

python3 -m pytest -q plugins/codex-rig/tests/review/test_local_reviewer_denial_protocol.py
plugins/codex-rig/bin/python plugins/codex-rig/tests/local_reviewer_denial_probe.py --help

The installed-package-safe gate copies only manifest-declared payload into disposable cache and runs explicit package-safe test selection without checkout context (Makefile, .github, and .git). Run it with:

python3 -m pytest -q plugins/codex-rig/tests/packaging/test_installed_package_gate.py

CI matrix: The repository CI test matrix runs complete plugin test suite on Linux, macOS, and Windows with Python 3.10, 3.11, 3.12, and 3.13. The synthetic denial gate and installed-package-safe gate are included in that offline matrix.

Manual-only boundary: A live local reviewer wave candidate-binding probe is separately authorized and manual; it must not run in CI and does not establish equivalence with desktop approval UI.

Live manifest: Its --live-matrix form consumes one local three-entry manifest ordered text-control, skill-control, and denial; all entries must use same Codex binary, model, plugin version, timeout, and independently recorded SHA-256 digest of package-manifest.json, with operator-prepared isolated non-overlapping Codex homes, workdirs, evidence roots, and output paths.

Isolation and launch: The probe verifies full manifest and every declared payload before launch, rejects any candidate or cross-row digest mismatch, and mechanically enforces path isolation; whether Codex home had prior use remains operator precondition and is not inferred from directory contents. It stops at first failure, never accepts collector command, and never installs or retries.

Failure artifact: After each process cleanup attempt, live probe atomically records either passing evidence or bounded failing diagnostic containing only allowlisted event names/statuses, run-local identifier aliases, booleans, safe failure codes, sorted schema-owned error categories, first specific category, whether any retry occurred, and final retry state. The diagnostic omits commands, paths, prompts, model output, raw identifiers, error payloads, environment values, and credentials; failing artifact explains protocol shape but never counts as acceptance.

Interpretation limit: A passing skill control proves only that host completed turn carrying installed skill input, not semantic skill loading.

📄 License

Codex Rig is licensed under Apache-2.0. See LICENSE and NOTICE.

Audit optimization acceptance now validates retained schema-2 cost evidence, matched comparisons, paired per-task completion quality and tool/check failures, passed hard guards, and finite savings; an assessed audit needs an executed passing review. Final handoff instructions load one common contract plus only the matching Code Review, remediation, challenge, or release supplement. Static instruction savings do not establish live speed or quality improvements. Global-instruction installation warns when preserved unmanaged global policy overlaps its managed template; migration remains an explicit user-owned action. Windows startup, package, doctor, and denial-protocol assertions surface without unconditional retries; the documented timeout-only installed-package mitigation remains.

Review preparation requires an explicit complete nested boolean signals mapping and rejects malformed routing before rewriting it. Coverage failures report the exact missing diff and source paths so agent-owned input repairs can preserve the full requested scope. New large batches freeze a source-only topology: each role owns one source responsibility, divided into ordered capacity parts only when required; all source waves retain complete coverage and no new interaction or consolidation review waves are added. Schema-nine aggregates retain every raw source_parts assessment and immutable origin; the highest-rating part (earliest on a tie) represents its role, while the lowest part confidence remains the initial confidence. Historical batches without that topology retain strict interaction and final-consolidation requirements. Each context includes its role card and stays within 65,536 UTF-8 bytes. Batched native replies use explicit individual-finding profile version one, including an empty inventory when clean. Assembly validates receipt-bound records, binds declared source coordinates to frozen hashes and retains immutable source origins in source_findings; historical aggregates also retain their intermediate interaction and final findings. Each unresolved individual maps through source_finding_mapping to a canonical obligation with original role attribution and source references. Nonconfirmed parent candidates retain original severity, claim and closure, with the same duplicate or distinct-origin reconciliation checks as confirmed mappings. Pending and unverified remediation occurrences include every mapped immutable original and source evidence within one candidate obligation; closed dispositions remain archived without new edit requests. Current and historical records markers enforce the same review-notes action table. Exact duplicates may share an action only when their complete canonical finding payload—including source evidence—is equal, with every original recorded in duplicate accounting. Distinct variants may share one action only when parent source judgment is supported by complete frozen-source witnesses for every origin, every original required change and closure obligation is covered by the canonical action, authors and evidence are unioned, and canonical severity matches the strongest origin. The machine check binds the complete origin inventory and evidence; semantic equivalence remains the parent's judgment, with independent verification. A later clean assessment never removes a finding. Individual response dispositions do not remove source-only findings; address every original through the parent-owned reconciliation. Historical independent source-backed disposition witnesses are bounded; a witness that does not fit leaves its finding actionable. Ordinary unbatched native responses retain their existing format. Each wave binds the advisory choices for its actual roles while retaining the immutable global choice. Source intervals and constituent runtime provenance remain validated. Context capacity does not silently narrow the review or turn a remediation request into reviewer setup.

Historical final consolidation stays bounded as reports accumulate. Overflow uses a generated serial schedule of whole evidence groups and cross-group comparisons; each role reviews the complete scheduled union. Schema-nine aggregates validate every schema-eight native part and retain all findings, confidence gaps and ratings. The representative per-role assessment uses the actual highest-rating part, with earliest-part ties; a final clean part cannot overwrite adverse evidence. Historical fitting aggregates remain readable. An indivisible report or adjacent origin/source-witness bundle exceeding its group budget fails explicitly before dispatch.

New batch inventories identify generation schema two. Historical interaction and fitting-final contexts include the full rating legend. For historical schema-one runs, an interaction or fitting-final context that was never issued receives the complete current rating legend and confidence instructions; reconstruction recognizes that exact prefix alongside the proved issued templates. Historical runs still require complete source/output reconstruction. Frozen contexts and raw ratings remain unchanged; arbitrary captured prefixes or matching hashes cannot replace the normal aggregate coverage check.

For schema-nine multipart results, the lowest constituent confidence remains the immutable initial confidence, and all part scores, scopes, gaps, statuses, rationales and hashes remain retained. It remains the final ceiling without complete global recovery accounting. Higher aggregate confidence requires exact accounting for every carried nonclosed qualified part gap and residual, admitted evidence for each claimed closure or evidence-backed reduction, current deductions for unresolved or deferred gaps, and contributions that reconcile to the final score. The parent judges semantic closure; validation checks evidence references and accounting. Recovery never changes part judgments, removes gaps or actionable findings, or treats review completion as proof that the underlying change is correct.

The native question provider requires Python 3.10 or newer available as python on the executable search path inherited by Codex, matching its direct MCP command. Bundled shell and hook launchers do not change that search path. Codex Rig sync validates this prerequisite and does not install a global interpreter shim. If the host cannot start the provider, keep the required decision unresolved and use another permitted input route only when available.

Review and remediation recovery preserves real host evidence:

• Native reviewer dispatch omits an unavailable agent selector while historical explicit default selection remains readable. Opaque successful delivery retains exact parent/child binding; refused allocations require exact controls, no-child proof and a joined capacity release before retry.
• Collector preflight recognizes Git's trailing directory separator and retains collision protection. User-accepted report discussion stays before checkout and merge preparation, retaining open obligations without claiming remediation complete.
• The action-table recipe uses valid Markdown dividers and reports divider failures accurately.
• A proved duplicated-interpreter reader call can receive one complete independent replacement without accepting its partial assessment. Current paged reads retain one proved missing-plan failure only with an immediate canonical same-page retry and complete ordered source receipts. Omitting the optional outer output-budget comment does not alter the required command, inner budget or returned source bytes.
• Current paged reads also retain one host-proved malformed JSON comment rejected before execution, followed immediately by the exact canonical same-page read. The JavaScript body and all executed source receipts stay exact. This shares the single incidental-failure allowance with missing-plan recovery; repeated failures, unknown diagnostics and changed commands remain rejected.
• The same single-failure frame covers a mistyped nonexistent reader-file path with a matched Python cannot-open-file exit-2 receipt. Only that argument may differ; the launcher and remaining arguments stay exact. Immediate canonical retry and every ordered source page remain required, with no new reviewer attempt or raw-response rewrite. Reader, plan and outer-comment failures cannot be combined.
• Partial missing-reader recovery accepts the exact whole diagnostic on either sole output stream, matching the native host representation. Mixed or extra output remains invalid, and the replacement still must independently read every source page.
• Unissued native page reads use private paged-context-v8 frames: the first stores exact reader arguments, and later frames load them and add only the page selector. Validation checks exact frames plus the expanded executed commands and ordered complete receipts. Prompts request no copied provenance header; schema-eight native-wave batch admission permits zero or one exact derived marker line at decoded-output start for the current pinned reader with paged v7/v8. Raw output remains unchanged and standalone/repair parsers stay strict. Issued v6/v7 recipes remain unchanged. One complete known schema-eight/v7 execution may admit a single inert literal duplicate --plan before the final canonical plan when exact reader identity, command frame and every page receipt agree; this does not allow generalized argument equivalence or retries.
• Ordinary and main text assessments retain surrounding contract content when exactly one separate Rating/Rationale pair occupies its own blank-line-bounded paragraph with a nonempty one-line rationale. Ambiguous duplicate or malformed declarations, fenced declarations, continued rationale and adjacent prose remain rejected; raw response content is preserved.
• Batched assessment consumers accept the same unambiguous rating/rationale fields inline or on separate lines, preserving raw answers and scores; future prompts explicitly request separate lines. Ordinary, main, historical and structured formats stay strict, and a malformed duplicate field cannot hide behind a valid field.
• A batch assessment written as Rating: <1-5> — <explanation> remains invalid but can use one lossless representation correction. The helper derives the exact missing label and line break, retains the original response and source proof, and requires a distinct tool-free correction with unchanged rating, explanation, findings and confidence. Mixed errors or changed claims remain rejected.
• Batch prompts distinguish valid reviewer-local IDs from qualified source-origin witnesses. If one supplied qualified origin is copied into a local id, finding-id-namespace permits a single exact correction only when the admitted source ledger and frozen context uniquely prove its original local ID and unchanged finding content. Original raw evidence and provenance remain intact; collisions, ambiguous or unsupported origins, changed claims and extra corrections remain rejected. The normal two-attempt, source, scheduling and final reconciliation gates still apply.

Every standalone role card carries the shared confidence deduction rule, so injected cards and generated shims remain self-contained. Calibration rejects a card that loses that accounting contract. Its generated result also labels the contributions behind each fixed confidence score and names absent live-route evidence explicitly.

All Codex workflows inherit the shared evidence rules: factual, causal and completion claims cite inspected sources or recorded proof. TDD keeps a representative real case as its acceptance oracle; mocks are supplementary polishing after real validation, never a reason to weaken assertions or change user-authorized behavior.

Review artifact validation keeps execution receipts, context reads, scheduling, and recovery checks in skills/code-review/review_execution_validation.py; validate_artifacts.py retains the CLI, result checks, and existing helper imports. Preparation tests separate capacity, recovery, and reader-receipt contracts while retaining shared fixtures.

Code Review validates candidates at every severity before publishing confirmed findings. Versioned source judgments use Approve, Minor changes, Major revision, Insufficient but a good initiative, Block, or explicit no judgment; verification readiness remains separate. Unverified concerns retain their prerequisite, owner and next check through remediation intake, without becoming automatic defect edits. Historical five-value reviewer ratings retain their original meaning. New finding-record version 2 requires a compatible reader and completion validator.

Challenge–resolve history uses explicit validated/advisory admission: completed advisory reviews remain visible without satisfying canonical completion. Status/history requests show the complete recorded history; report resources appear as short table references with links underneath. Legacy report rendering stays unchanged.

Remediation results distinguish Selected: Yes (chosen actionable item), No (actionable item left unselected), and Closed (already resolved or informational at intake). Choosing All selects every actionable item. A recorded commit mode also authorizes committing completed fixes when only eligible external verification or review obligations remain; the report stays failed and the commit discloses those obligations.

Remediation uses the original invoking checkout as its default final destination. Temporary worktrees must be announced with their path and purpose; finished PR branches and owned changes return to that checkout with unrelated staged, unstaged and untracked content preserved. An explicit worktree-only request overrides return delivery. Unsafe handoffs remain incomplete with both locations and the exact blocker. Review-only work stays isolated and never switches the invoking checkout. The worktree lifecycle defines terminal transfer and report-only resume; its delivery proof complements the historical source receipt.

An explicit remediation commit this request or answered commit mode authorizes a local snapshot even when checks fail or a regression remains. Failures stay visible; the snapshot does not certify completed remediation. Standing approval alone keeps ordinary readiness. A selected commit must include all authorized owned content, including new files and incomplete fixes, with zero task-owned uncommitted residue before delivery and final output; unrelated pending work stays untouched.

Terminal handoffs use compact tables with evidence and file paths listed below as - Item: file-path. Machine records and historical reports retain their full evidence. Read-only audits rank findings without requiring remediation selection. Implementation style corrections recover automatically; release headings and contributor credit accept equivalent Markdown while preserving identity and content checks.

Ambiguous plain table cells containing paths and words or spaces, including unmarked slash expressions, move verbatim into item-labelled detail lists. Explicit Markdown links and quoted paths retain adjacent prose in the table. This automatic fallback preserves complete instructions and directory names without guessing path boundaries; current result candidates require presentation version 8 while archived canonical results retain their original rendering.