🛠️ Codex Rig — Development and Technical Reference

Audience: contributors, maintainers, and agents that need the technical contracts behind Codex Rig. User-facing install, usage and limits live in the README.

This file holds detail moved out of the README so the README stays readable. The normative sources remain the skill files (skills/<name>/SKILL.md), the shared contracts in shared/, and the tests. Where a statement here and a skill disagree, the skill and its tests win.

Where things live

Area	Location
Workflow instructions	skills/<name>/SKILL.md
Role cards	roles/
Shared executable contracts	shared/
Scripts (package, role, shim lifecycle)	scripts/README.md
Calibration	runtime/calibration/
Hooks	hooks/hooks.json
Tests	tests/
Package manifest	package-manifest.json

Regenerate the manifest with build_package.py --update after any shipped-file edit, including README or this file.

Acceptance, calibration and confidence contracts

• 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.
• Agents attempt feasible authorized confidence recovery before deferring material gaps: complete eligible reviewer receipt recovery, run pinned autofixing checks on disposable source copies during read-only review, and investigate accessible CI evidence alongside local checks.
• Recovery retains retry limits and authentic provenance; local passes never clear remote CI status, and parent inspection never supplies independent coverage.
• Each confidence score names the delivered result or claim and assesses its correctness within the stated scope, including how it was produced and checked and limitations that could make it wrong.
• Completion and gate status remain separate.
• A gate-driving score assesses the process or judgment that gate protects, not an unrelated status fact or speculation about future success.
• For costly, nondeterministic, or external workflow validation, Codex first checks realistic controlled cases with independently specified outcomes, relevant failure and recovery cases, and negative controls.
• Bounded real or live validation follows only after those cases pass; synthetic receipts do not establish live or independent behavior.
• Actual incident diagnosis and representative real-case acceptance remain required where applicable.
• 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.

Review execution and recovery details

• Detached PR review accepts the collector's native Windows command paths as well as serialized forward-slash coordinates, while checking the exact worktree and revision range. Stop diagnostics recognize literal single- and double-quoted PowerShell helper paths.
• Code Review completes its routed source and specialist work before the final test gate. If declared dependencies are missing, it preserves the failed attempt and can run the full source-bound gate with a vetted wheel overlay inside the sandbox; focused overlay checks remain claim evidence. Missing packages do not by themselves cancel independent review or artifact closure.
• 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.
• Native parent transcripts distinguish their own execution from inherited ancestor history; specialist identity and independence checks remain required.
• Static calibration and synthetic runtime receipts do not prove live reviewer comprehension or native form rendering.
• Code Review preserves healthy page reads when only an unexecuted future frame is suspected; generated recipes stay verbatim.
• One bounded interrupted-dispatch recovery requires authenticated spawn/delivery, a matching running-status parent interrupt receipt and genuine child abort after an exact nonempty successful reader prefix, before source-informed assessment or other activity.
• Explicit opening commentary may precede the first reader call when event order and timestamps prove that boundary; all host representations remain intact.
• Missing phase, final output and assistant text after source reading begins still reject recovery.
• Preserve siblings and dispatch pending original roles before recovery; one replacement reads every page within the existing two-attempt ceiling.
• Interrupted originals retain their real evidence without invented final answers or outputs, and unrecoverable coverage remains incomplete.
• Challenge Resolve and historical routes retain their existing recovery limits.
• Gate deadlines cover inherited output pipes and terminate the owned process group even when its leader exits first; captured stdout and stderr are drained with a 1 MiB per-stream limit and a truncation marker.
• A source guard failure preserves the command exit while remaining valid failed-gate evidence.
• Fully inspected reviewer assessments cannot be relabeled as transient failures.
• A genuine source-incomplete task can use the existing one-replacement retry before promotion, preserving original evidence and reusing other completed roles; final acceptance requires full assigned source inspection.
• Generic retry labels without authenticated host failure receipts are rejected; evidence-bound interruption recovery and disclosed parent fallback remain available.
• Review preparation checks declared test extras and can propagate a verified source path to child processes when the failure proves it is needed.
• Completed review reuse validates the original producer identity across sessions.
• A recommendation that the change needs revision does not mean the review is unfinished.
• Native Challenge Resolve retains complete scoped source beyond the historical ordinary paged-review ceiling and accepts supported native tool namespaces while preserving page and provenance checks.
• A challenger may truthfully list additional inspected evidence; acceptance still requires every frozen source path and its original bindings.
• Challenge validation also accepts complete source-rated local reviewer assessments while preserving the original evidence and rejecting incomplete assessments.
• Host-supplied developer tool inventories do not count as reviewer tool calls; actual calls and audited page receipts remain validated. CI-only backend dependencies are not mislabeled as newly introduced by a PR, and a borrowed test environment’s plugin failure remains a failed check rather than stopping feasible review completion.
• Low-risk reviews can use complete parent-only coverage when independence was not requested, disclosing the missing independent specialists and retaining all required source and checks.
• 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.
• An ineligible reviewer repair continues through the permitted parent fallback when source is verified and independence is not required; merely collecting another run does not finish that fallback.
• Nested review completes and admits its report before continuing the original remediation, without requiring a new user invocation.
• PR remediation accepts the collector's canonical diff command and retained legacy receipt forms through exact comparison; altered revisions, transforms and path filters remain rejected.
• Routine missing-dependency recovery prepares the complete declared environment for the selected test lane without another bootstrap-consent question.
• Standalone review can use a disposable environment when bootstrap, declarations, lock and routing are unchanged; source and invoking environments stay untouched.
• Retries preserve required runtime capabilities, while actual denials and sandboxed build/test boundaries remain controlling.
• For code-remediate +review, the remediation parent owns preparation even before finding selection and resumes the joined workflow after review validation.
• Resuming an older review keeps valid evidence and reruns missing, stale or unverifiable work through the current workflow. Old execution plans remain preserved history; recovery does not require repairing their protocol or restarting usable work.
• Unstarted review work is not itself a blocker: the agent continues it in the current turn. Interrupted checks and missed ordering first use Continue or Skip in the retained review, with missing proof disclosed. For other recovery decisions, the native question offers New review, Resume last one, or Stop, explains the blocker and retained evidence, and waits for the answer. Stop ends a waiting joined remediation too.
• Small TRIVIAL or LOCAL reviews may select the existing parent-inspection route before preparing specialists when independence is not explicitly required; all required inspection axes and closing gates remain.
• Independent dispatches preserve every generated argument, including the digest-bound task name.
• A missing expected direct child is reported separately from duplicate sessions, and permitted parent recovery runs through completion rather than ending with a fallback announcement.
• Review preparation uses its packaged skill-local helper path and recovers incorrect invocations before asking for a decision. Recovery questions discover the packaged native form before considering async; an accepted async question receives no trailing final or status message.
• When PR remediation requests existing report evidence (+report, report aliases or an explicit path) 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.
• An interrupted check or missed ordering uses Continue or Skip, preserving the incomplete proof. Other substantive gaps that remain are a question, even when available findings can be fixed: New review, Resume last one, or Stop, with the feasibility and consequences of each route explained.
• 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.
• Stop preserves artifacts and changes without continuing remediation; only a separate explicit instruction authorizes continuing with available findings.
• An unanswered or dismissed question stays pending.
• Native question controls own the question and choices; commentary does not duplicate their menu.
• Native review input can admit an exact inert fixture occurrence after parent verification and explicit user approval, bound to its complete input context and matched span.
• Changed contexts, new occurrences and overlaps require separate approval.
• Real credentials remain refused, and outputs, logs, failure and retry explanations, portable and isolated contexts remain strictly scanned.
• Version-3 direct plans bind fixture admissions to a complete source snapshot record or Git diff section, with all original bytes scanned and cross-component matches refused; unrelated files do not enlarge that input’s verification requirement.
• Historical direct plans retain their original aggregate bindings.
• No fixture is admitted automatically.
• 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.
• 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.

Question delivery, waivers and scope

• 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.
• 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 already-authorized workplan verifiers inherit the selected remediation scope.
• An additional post-fix review requires its own bound decision; intake +review alone does not authorize that extra pass.
• 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 source recovery locates a relocated PR branch and attempts a fast-forward-only pull in its verified clean checkout before requiring fresh GitHub metadata. A failed or denied pull escalates with its cause; a successful pull still requires current PR identity and revision verification before fixes resume.
• 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.

Local Git approval details

• 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 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.

Commit handoff and approval prompts

• 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.
• 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 only for multiple selected actionable items; one selected item uses all at once without a grouping question, and any missing final authorization offers only all at once or leave unstaged; 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.
• 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.

GitHub reads, network and reader details

• 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.
• GitHub reads resolve profile-or-approval before the first request, including PR state preflight: sufficient active github-read or equivalent grants run directly; missing capability uses runtime approval for the complete reader or collector.
• A generic reader permission error does not prove a host denial.
• Available permission recovery precedes a blocked report, and successful approval resumes the same workflow.
• Actual denial, server authorization rejection, or continued failure after approval remains a diagnostic stop; the workflow never enables a profile or repairs credentials automatically.
• For Actions job logs, use the same reader with gh api /repos/OWNER/REPO/actions/jobs/JOB_ID/logs.
• If GitHub CLI refuses terminal escape sequences, the reader retries that GET once with --allow-escape-sequences, captures the response, removes ANSI formatting, normalizes CRLF and escapes remaining terminal controls before saving UTF-8 text.
• This compatibility flag is restricted to job-log GETs; it grants no additional network or repository permissions.
• Other responses retain their original bytes, including workflow-run log ZIP archives.
• Reader failures retain the stable error code followed by safe JSON metadata, including the subprocess exit code and classified reason when available.
• classic-token-forbidden identifies an organization policy rejecting classic personal access tokens: the user must configure an organization-permitted credential before retrying.
• Runtime approval cannot override that policy, and the reader does not switch to public access after the refusal.
• Raw CLI output and credential values remain undisclosed.
• 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.

Isolated local reviewer wave

• 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-3 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 and schema-2 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.
• 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.
• 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.

Codemap integration details

• 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.
• 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.
• challenge-resolve, 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 verified reviewed source checkout, including an isolated PR worktree.
• Review-category CLI calls with --out place default provider cache and telemetry files in the run directory outside the verified checkout, retaining the selected index’s shared coordination domain, preserving source receipts, explicit overrides and frozen index selection.
• The parent runs the initial query serially there; a supporting provider automatically prepares its own canonical index from working-tree bytes, including unstaged edits, additions and deletions.
• Frozen queries preserve their opt-out; an older provider failure remains explicit and never selects the invoking checkout instead.
• 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 opens with its search or, for a protocol method, its do-not-delete instruction, so the 300-character bound keeps it.
• 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.

Audit, installer and global instructions

• 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.
• Use $codex-rig:audit with axis=consolidate and a target to discover overlapping instruction intent.
• This advisory branch supports configuration, skills and roles, takes precedence over mode, and bypasses ordinary mutating checks.
• It recommends keep, local sharpen or scope-preserving merge-prune; independently loaded skills and roles never merge.
• A read-only validator binds source and citation bytes, checks ranges, coverage and obligation records, and derives proposal states from independent digest-bound reviews.
• Missing or stale review and unsupported Markdown structure remain unvalidated.
• No sources are edited, no fix-selection gate opens, and byte deltas are not accepted cost savings.
• See Advisory Consolidation for the bounded inventory, schema and separate application requirements.
• 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.
• 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.

Skill detail: challenge-resolve

• 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-3 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 | Security | Critical | High | Medium | Low | Nits | Weighted score; each numeric cell is old + new, security and critical have separate columns, 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.
• Adding --append-metrics to the append call records the round's cost (route, brief wording and bytes, duration, tokens, attested gaps; unknown values stay null) in an advisory loop-metrics.jsonl that never affects scoring, the progress table or clean acceptance, and a rejected cost record only warns.
• --plateau-kind names why a plateau or non-converging stop happened, and --brief-arm assigns the reviewer-brief wording for the lean/full pilot.
• Before the baseline review of a diff it authored, the parent writes an attestation (invariant, sibling routes, consumer, failing-before/passing-after check) outside the workspace, fixes the gaps it exposes, and never shows it to the reviewer.
• 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 detail: profile

• Use $codex-rig:profile for a retained report over selected native session JSONL, or let it identify the current session when the host supplies an exact thread identity.
• Native /status answers quick session-token questions, /usage shows account usage, and existing OTel supplies instrumentation.
• Profile adds no collector: it reports latest cumulative tokens and inclusive completed-tool time, keeps agent inputs separate, and excludes private conversation content.
• Optional local rate sheets supply explicit model prices and source/date; estimates are hypothetical rather than subscription billing.
• Missing agent logs, unsupported paginated history, mixed-model pricing and unknown attribution stay unavailable.
• Counter subsets cannot exceed their totals; malformed or excessively nested JSON fails with bounded diagnostics.
• Retained profile results require the current result schema and bound final handoff.
• See profile workflow and the reader's --help for supported inputs.

Execution model details

• 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.
• 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 lightweight path: the parent defines a concise plan, performs a brief self-challenge (not independent), accepts the challenged plan within existing authority, assigns useful bounded owners or retains indivisible parent execution, then implements and consolidates actual source/handoffs with one bounded independent result challenge and relevant verification.
• Approval asks the user only for actual missing authority or protected decisions.
• Establish core acceptance before optional expansion; expand only for demonstrated current need, reuse valid evidence, and stop or re-scope waste.
• If independent coverage is unavailable, continue permitted work and disclose the gap without claiming an independent clean review.
• Tests and documentation for the same change do not require separate specialist assignments, standalone execution-plan artifacts, 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, Confidence, Artifact, Recommendations / next steps—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.
• Every skill and workflow keeps a table as a human reading anchor, including single clean results and blocked work.
• New presentation-12 terminal reviews render a compact status table without inventing assessed findings; unvalidated process pauses retain an explicitly preliminary checkpoint table and numbered recovery steps.
• 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/.
• Validate a coherent bounded outcome or split it into smaller outcomes, then complete the active branch depth-first using a compact task map and context limited to the active piece, dependencies, and interfaces.
• Complete required leaf challenge and verification before dependent work; dependency-ready siblings with agreed stable interfaces and disjoint owners may proceed.
• Unknown causes or design choices first become bounded investigation or decision prerequisites; parent consolidation retains required gates.
• This replaces broadly open workstreams and far-ahead detail to reduce context, coordination, and rework; that benefit is expected, not measured.
• Medium/large or unexpectedly nontrivial implementation follows the proportional execution sequence:
• Define and independently challenge one scoped plan.
• Seek bounded advice if a material decision remains uncertain.
• Approve the challenged plan within existing authority.
• Delegate useful bounded disjoint execution or retain indivisible parent execution.
• Implement, then consolidate the integrated result, independent result challenge and verification against every accepted criterion.
• 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 preparation, hooks and isolation

• An oversized invoking-worktree context scan is informational for isolated PR review: collection records source-worktree-context.json as unavailable and continues to verify the separate worktree's repository, exact PR commit, detached branch and clean state. Attached remediation checkout still requires complete local preservation checks; an oversized scan there stops collection before checkout.
• The bundled Stop hook requests at most one diagnostic continuation when current-turn host receipts show review or remediation started without its completion check.
• A nested review's completion does not finish its waiting remediation; remediation closes through its existing validated finalizer.
• It reads no review source and runs no commands; recorded stops, questions, interruptions, unknown lifecycle formats and an already-continued turn preserve stopping.
• For long transcripts it reads the session identity and a bounded recent suffix; if the complete current turn is unavailable or the transcript is changing, it preserves stopping.
• It recognizes the host's reasoning-effort-only update.
• This is an advisory guard, not permission enforcement or guaranteed workflow completion.
• It recognizes direct packaged helper calls and their promotion chain; unsupported command wrappers, intake abandoned before run creation, and resumed runs without a current-turn creation receipt are not covered.
• After installing the update, review and trust the changed hook through Codex /hooks; installation alone does not enable untrusted hooks.
• A plugin contents changed; hook approval required message means this diagnostic did not run.
• Ordinary workflow execution does not depend on hook trust: joined +review intake directly resumes the owning review and returns to remediation, while a genuinely missing decision uses its native question.
• Phase references are loaded only as needed, with truncated reads completed before use.
• See the Codex hooks reference.
• New ordinary Code Review runs use skills/code-review/review_prepare.py to freeze the source identity, role cards, focused review-briefs.json and path assignments, then prepare one direct task per routed specialist.
• Reviewers inspect assigned source with ordinary read-only tools; their source coverage is reported by the reviewer, and instruction-bounded review does not prove enforced isolation.
• After joining each required reviewer, the parent records unchanged confidence and nonnegative integer blocking_findings counts in specialist-assessments.json, assembles the review, reconciles findings and runs source-bound checks.
• Missing source coverage remains incomplete, and a failed operation alone never selects a terminal handoff: permitted recovery and independent work run first.
• Explicit --paged or --batches, resumed historical runs, and the documented parent-only fallback retain their applicable historical dispatch and recovery contracts, including bounded contexts and audited page reads where required.
• For those routes, review_prepare.py owns generated specialists/<role>-context.md files, and review_batches.py prepares batch inputs.
• 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.

Parallel execution internals

• 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; current generic runtime promotion requires schema-v3 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-v3 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 schema-3 runtime plan freezes dispatch_choices by node, with exact role and explicit or inherited model and effort; null means omit the spawn argument and inherit the observed parent turn.
• 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-v3 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.
• 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 routing and fallback 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.
• Fresh ordinary native preparation uses direct source-pointer tasks without paging or size-driven batching.
• Explicit paged compatibility 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.
• 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.
• 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.

Cost control and stall guardrail

• Role cards preserve their assigned reasoning effort and execution boundaries without pinning a model.
• Select a concrete model only for an actual subagent dispatch, respecting explicit user choice and the task evidence.
• Architecture and security roles remain explicit-selection, read-only advisory passes.
• Parent owns integration and executable acceptance; required specialist evidence remains mandatory.
• 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.
• The obligations command exposes coverage-required finding details without manual copying and identifies partial or ambiguous records that still need inspection.
• 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 specialist-owned. Narrow work stays in parent when handoff cost would exceed its value.

Artifact layout and remediation intake

• 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.
• The remediation entrypoint follows four phases: admit evidence, collect and select findings, implement and verify, then finalize and deliver.
• Each phase loads its detailed rules when needed.
• An authorized missing review runs before finding selection and returns its exact validated result to the waiting remediation; incomplete reporting never substitutes for an available authorized next step.
• Bare PR remediation validates older online claims against current source without a review-choice question caused only by their age; additional review still requires authorization.
• 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:
• 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.

PR review-to-remediation reference

• 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 source: Before PR edits or integration, shared/remediation_branch.py prepare verifies source and writes the unchanged schema-2 receipt without altering branches or tracking.
• It binds the collector's attached branch, exact PR head, worktree and source repository.
• Head-branch tracking uses refs/heads/<headRefName> at the contributor repository; successful native fork checkout may instead track the exact refs/pull/<PR number>/head at the canonical base repository.
• That valid native state requires no fork setup, checkout retry or manual tracking repair.
• Native local aliases remain valid; same-repository fallback and recovered legacy receipts retain head-branch tracking.
• check revalidates source identity, branch, worktree, expected head and ancestry before continued edits/commits.
• Push configuration and live fork write access are not local-remediation prerequisites, and the receipt does not certify publication readiness.
• Remote updates remain human-owned and require independent destination verification.
• 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.
• Shared verification recovery: Any authorized workflow executing project code, including implementation, investigation, optimization and delegated test work, prepares missing declared dependencies through the parent before reporting blocked checks.
• Read-only reviewers retain their existing overlay boundary and request preparation from the parent.
• Degraded Codemap results stay unchanged; direct inspection of unmapped files and relevant dynamic references can close specific review facts without claiming an exhaustive graph or imposing an automatic confidence deduction.
• Reviewer transport recovery: A host-rejected wait with an extra target field and an immediate exact canonical retry no longer discards independently completed reviewers.
• The raw rejection remains preserved and supplies no scheduling opportunity.
• Isolated reviewers accept the documented, active-turn-bound moderation metadata notification without retaining its payload; malformed, mismatched, unknown or execution-related events remain rejected.
• Remediation closeout: missing declared Python dependencies trigger the project’s declared environment preparation before an environment-blocked outcome, including collection failures after all selected findings close.
• Install into the selected project virtual environment using its declared setup and constraints, request specific missing permissions when necessary, and rerun the source-bound canonical gate bundle at the recorded revision.
• Code Review retains its separate read-only overlay rules.
• 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.
• Ledger rendering and finalization derive the durable completeness totals and status counts from the final rows; authored summaries and intake explanations remain separate.
• 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.
• Review evidence and freshness: Joined +review authorizes the needed intake review step for the same target; reuse current evidence or update/create the review without asking for the same consent again, then resume remediation.
• Existing-only +report, report aliases and explicit report paths ask for a substantive missing-review decision after feasible automatic recovery.
• Saved reports and online comments use the same freshness rule: compare known reviewed revisions/outdated status with current source; fetching now does not make old findings current, and unknown freshness is disclosed.
• For stale evidence without existing review authorization, ask use existing findings, update existing review where feasible, or create a new review.
• Every finding is revalidated against current source.
• Updates preserve original evidence/provenance and run through Code Review; online evidence is reassessed locally without posting or editing GitHub comments.
• Unpromoted candidates remain inadmissible, missing independent proof stays explicit, and extra post-fix review rounds retain their separate authorization.
• Remediation questions: Ask scope first, complete any custom selection, then ask commit grouping through a suitable native control only for multiple selected actionable items.
• One selected item—including all, Custom or explicit scope resolving to one—defaults to one commit group without that question; existing authorization, deferral and denial still apply.
• Discover the packaged form before falling back to async or text; its single-field route opens one scope form then, when applicable, 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 its question and still uses the resolved selection count for grouping.
• 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 follows the missing-review checkpoint, reusing joined +review authorization or asking only for a genuinely missing 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.
• Conditional recovery detail: Code Review and Code Remediate load their packaged recovery references (references/validation-recovery.md, report-recovery.md, batched-review.md, historical-routes.md, collection-failure.md, existing-conflict.md, source-recovery.md, missing-review-decision.md) only when their trigger applies, and implement and manage load shared/portable-parallel-read.md only after parallel-read is selected.
• Ordinary runs skip them; each failure, historical or parallel path still loads every obligation before it acts.
• 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; an eligible interrupted original instead retains its abort/interrupt receipts and requires its complete replacement to join.
• Validated interrupted-dispatch recovery preserves siblings and pending-original order as described above.
• 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.

Handoff presentation and finalization

• 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=13; remediation with findings includes a compact per-item table—even for one item—with Finding, Selected, Outcome and How resolved, preserving each concrete resolution reason; an empty result states that there are no findings to remediate.
• Terminal review outcomes include a compact status table; remediation retains its resolution explanations, with compact tables and evidence paths in separate - Item: file-path lists; every workflow renders separate confidence bullets, coalescing only identical limit/gap labels while retaining closure details.
• Handoffs lead with a plain-English explanation, no empty Results section, one concise line for checks not run, and each recovery action shown once in an Owner / Issue / Action table; machine row IDs stay in JSON.
• 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.
• 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 5; final handoffs use version 12 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.

Optimize campaigns

• optimize keeps its existing single and campaign behavior, including pass/fail metrics.
• Request mode=campaign with checkpoint=true for a resumable numeric campaign; mode=resume with source_run verifies the retained configuration, source fingerprint and original total iteration budget before scheduling.
• Checkpoints detect pending attempts and reconcile an already-appended result without replaying it.
• The helper never executes measurement commands or rolls source back automatically.
• Managed checkpoints bind actual tracked bytes and executable modes independently of Git normalization, and reject assume-unchanged and skip-worktree entries that can hide tracked edits.
• Submodules, nonregular tracked source and symlink ancestors are unsupported.
• Artifact admission reconciles every structured Results row with the bound history or ablation receipts; campaign summaries follow the exact conventions in the mode instructions.
• Evidence roots may use filesystem aliases, while links inside retained evidence remain rejected.
• Use mode=ablation with a completed managed source_run and bounded component-removal variants.
• The workflow reconstructs the exact best source, including uncommitted changes, additions and deletions, in detached worktrees.
• It retains both Git patches and the complete raw tracked/scoped file inventory, restoring index membership, original bytes and executable modes after Git checkout conversion.
• It reruns the reference and each variant with the same metric/guard and ranks signed contribution loss only from valid retained measurements.
• Output hashes and source/configuration receipts are validated at promotion; actual execution provenance remains parent-verified.
• Component interactions need separate experiments.
• Use mode=retrospective with source_run for read-only campaign counts, deltas, repeated/rejected approaches and next-hypothesis suggestions.
• It reads retained history even after the live checkout moves.
• Adaptive iteration logs do not establish statistical significance.
• Historical runs without managed state are not silently migrated.
• See optimize inputs and dispatch, campaign checkpoints, ablation receipts, and retrospective limits.
• The deterministic campaign helper documents its inputs, outputs and failure behavior; invoke it through the plugin Python launcher and inspect --help.

Shim and hook lifecycle details

• 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.
• 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.
• 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.
• 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.

Design history details

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.
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. 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 maintenance 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.
• 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.
• 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:
• 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:

Gate, CI and live-probe notes

• 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.

Later additions and hardening notes

• 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.
• New Code Review runs use one direct native task per routed specialist.
• Reviewers read their assigned files in the verified isolated checkout with ordinary read-only tools.
• Preparation freezes the source identity, role cards, briefs and path assignments; assembly retains actual child outputs and verifies parent/child identity, completion and reported coverage.
• Source consumption is reviewer-reported, and read-only instructions are not a claim of enforced filesystem isolation.
• Source size does not create paged contexts or serial review waves.
• The parent joins every required reviewer, reconciles candidate findings and online discussion, runs source-bound project checks, and validates the final report before delivery.
• A failed check remains visible without preventing independent review work or an honest completed nonapproval.
• Pending reviewers resume from the same checkpoint with completed evidence retained.
• Parent checks can resolve a specialist’s pending verification while preserving the original assessment; missing source coverage and unresolved concerns still prevent complete readiness.
• The Code Review skill provides the main sequence and loads detailed result or recovery contracts only at their owning checkpoint.
• Historical paged and batched review artifacts retain their original validators and recovery contracts. Explicit historical preparation and Challenge Resolve keep their existing route; the new direct route does not reinterpret old evidence or claim transport-level proof of source consumption.
• 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. The paged and batched cases below apply to historical review runs and the explicit compatibility route:
• 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; controlled cases may use test doubles before real validation, but never justify weakening assertions or changing user-authorized behavior.
• Review artifact validation keeps direct child evidence and historical context-read, 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.
• A completed clean source inspection can retain a qualified source approval when a checker is unavailable, while the result remains failed and verification blocked.
• New Git review snapshots and full reports include the full reviewed commit SHA; commit reviews without native reviewer receipts use matching clean before/after gate observations, including failed checks whose source remained unchanged; working-tree/path reviews label it as the base and retain the reviewed diff digest.
• 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; new writers use presentation version 13, supported version-8/9/10/11/12 candidates remain admissible, and archived results retain their original rendering.
• Cosmetic handoff failures use automatic presentation recovery: regenerate owned display fields from retained evidence and rerun the affected check without another user decision.
• Reader defects are reproduced and fixed in authorized package source; genuine evidence, verification and authority failures retain their gates.
• Canonical PR remediation lifecycle roots accept the promoted PR/run layout while preserving legacy flat runs and rejecting malformed or foreign identities.

Original wording of paragraphs summarized in the README

• 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 parallel execution diagram.
• 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.
• 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.
• 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.
• 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.
• 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:
• 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.
• 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.