Before asking, read User Questions.

Challenge and Resolve¶

Task-size routing follows Proportional Execution; this skill's specialized lifecycle and acceptance checks remain authoritative.

Read, apply ../../shared/adversarial-loop.md before dispatch or edits. That shared procedure owns the algorithm; this entrypoint owns Codex artifacts, the closing gate. Read evidence-contract.md before source capture or reviewer dispatch. Also read Authorized Workflow Execution for authority; Acceptance and recovery and Evidence Rules for evidence limits; Bounded Dispatch Wave, Read-only work and executable probes, Portable Role Routing and Retry And Checkpoint Policy for reviewer admission. Recurrence follows the stop rules in ../../shared/adversarial-loop.md.

Input Schema¶

{
  "goal": "required review-and-fix objective",
  "scope_files": ["bounded source paths relevant to the task; discover them when initially unknown"],
  "specification": "required behavior or acceptance criteria",
  "symptom": "reported problem, feature objective, or preventive review",
  "caller_run": "optional existing workflow run to resume",
  "done_when": "independent final review is clean and normal checks pass"
}

Begin with independent baseline W_0, then continue only while the unchanged-scope nonnegative integer total score strictly decreases; no arbitrary three-review cap applies. Stricter caller reviewer and retry budgets remain binding. For a problem or feature without named files, inspect the repository to identify and bound the relevant source before freezing a review; a pre-existing implementation can have an empty diff. In-scope feasible fixes are authorized by a review-and-fix request; a structural finding does not authorize scope expansion, public API changes, commits, installs, network access or publication. A caller's stricter scope or admission still applies. The retained request proves delivery of the parent's declared criteria to the challenger; report any uncertainty about interpreting the user's scope instead of claiming machine authentication of natural language.

Review each frozen scope with a fresh independent challenger process. Give it source, diff, criteria, and original finding counterexamples needed for verification; never give it resolver handoffs, explanations of changes, or parent closure claims. The main process owns old/new identity, severity, the weighted ledger, resolver assignments, and stop decisions. New challenge results use the same strict artifact checks under candidate and canonical filenames; archived JSON remains readable as data but cannot certify current completion.

Workflow¶

01: Establish scope and evidence ownership¶

Read ../../shared/helper-cli-contract.md; create a run with create_run.py --skill challenge-resolve. Record caller_run when supplied, without overwriting its artifacts. Retain baseline source and acceptance evidence. Write loop-report.md with Scope, Rounds, Findings, Remediation, and Verification sections. Identify implementation author and allowed reviewer route before dispatch.

Before freezing a Python review scope, follow ../../shared/codemap-contract.md to settle unresolved caller, dependency and test-impact facts. Reuse still-current caller evidence that covers the same source and question; otherwise run PLUGIN_ROOT/bin/python PLUGIN_ROOT/shared/codemap_adapter.py context --category implementation --query-kind <skip|central|callers|blast|dependencies|test-impact|coupling|standard> --root <verified-source-root> --out <run-directory>/codemap-context.json, adding --target <resolved-qname> when required. Select the smallest sufficient route; an explicit structural request overrides skip. The parent prepares the index serially through the provider's ordinary query, then includes the retained evidence and its limitations in reviewer context. Missing provider or incomplete static coverage requires bounded source inspection, not fabricated graph evidence; never mechanically invoke scan-codebase or substitute a different checkout's index.

Before any remediation, list every requested path, relevant unchanged consumer, and known interaction in loop-report.md under Scope; assign each to the first challenger scope or mark it unreviewed with a reason. Finish the first challenge over every admitted part before treating the gathered findings as the discovery baseline. A complete-file chunk plan proves byte delivery only; the parent must inspect each reviewer's stated coverage and keep an uninspected path or interaction visible. If full initial coverage is unavailable, stop an overall clean claim rather than spending repeated fix rounds on a partial baseline.

For each workflow branch in scope, record one source route before dispatch: entrypoint, producer, next ordinary consumer, distinct sibling path where one exists, and the acceptance test that exercises them. Include unchanged files on that route in supporting source; ask the challenger to state which routes it assessed. Missing route source or a reviewer-declared unassessed route blocks a complete discovery baseline. If a later challenger finds a defect already present in an earlier frozen source, mark the earlier route coverage gap, add the missed producer or consumer, and reassess that route before another fix round. A test that manually upgrades a producer's output cannot prove the ordinary producer-to-consumer path.

Before choosing how to deliver a large scope, estimate the source and diff size, supporting context, expected page reads, and any chunk and interaction workload from available local evidence. Use the estimate to plan a practical admission check, not as proof of model capacity or route failure. First assess the default Code Review native instruction-bounded route; the optional isolated Codex review route's 2 MiB transport limit is not a native-route limit. A size estimate alone cannot establish independence-unavailable: freeze the full source and diff, inspect actual native admission, then use the chunk path below if the full input cannot be admitted or meaningfully reviewed. Preserve the route's actual rejection evidence; never send truncated source or infer model capacity from a byte count.

Bounded chunk path¶

Only when the full source and diff cannot be admitted or meaningfully reviewed, or when resuming, stopping or reporting a chunked coordinator, read chunk-path.md before planning chunks; single-scope runs do not load it. The reference preserves the planner and checker commands, independently dispatched child runs, pair and group interaction reviews, chunks/results.json shapes, stopped-coordinator summaries, cross-run history and prior-finding continuation obligations.

02: Run the shared bounded procedure¶

Use one serial challenger loop per scoped run, including each chunk or reviewed interaction. Separate independent chunk baselines may run concurrently against the same frozen snapshot when the chunk path and runtime permit; rounds within each run, source changes and acceptance remain serial:

Before the baseline dispatch of a diff this run's author wrote (not a continuation of a prior ledger), write the attestation to a randomly named file in the system temp directory, outside the workspace and never recorded in the run directory, per the shared loop rule's pre-baseline attestation and close its gaps within scope; never show it to the challenger or hand over the run directory. Freeze complete current source and diff. Start one fresh independent challenger subprocess with that scope, the specification, and every prior finding signature plus its original counterexample and evidence when this is a repeat round. Include the implementation, next consumer, validating helper, and relevant tests needed to judge each earlier finding; if they cannot fit or are unavailable, record that finding unassessed and stop its closure claim before dispatch. Ask the challenger for structured current findings and evidence on each original counterexample, without any resolver handoff or account of what changed. Keep its original structured response and reviewer provenance.
Before any fix, score, or next challenge, triage each returned finding on separate axes: compare the failed invariant and proof with every signature in all earlier validated rounds and parent/child runs to mark new, carried, or reopened; classify its demonstrated impact as security, critical, high, medium, low, or nit; and for first-reported findings, classify the failing source as present earlier, introduced by remediation, scope-added, or undated with cited snapshot/coverage evidence, recorded under the signature in loop-report.md and never in ledger evidence, which must equal the reviewer's report (the append step then warns origin-missing, expected here). A changed title or file location is not a new defect, and severity does not determine identity. Retain the old signature for the same failed invariant; if its severity conflicts with the prior tier, stop ledger promotion until the conflict has evidence and is resolved under the stable-tier contract. If the reviewer lacked source needed to assess a prior signature, record unassessed in cross-run history and seek complete coverage rather than treating absence as closure or the old signature as a fresh finding. Record one schema-2 loop-evidence.rounds[].triage mapping per raw reviewer finding, with a reason and evidence for any corrected identity or severity. Keep the raw response intact; validate source and reviewer evidence, stage the mapped round in <run-directory>/loop-rounds.jsonl.rec and run adversarial_loop.py --ledger <run-directory>/loop-ledger.json --append --progress per the append-only round rule below, and show its weighted old/new table. One reviewer avoids same-round classification conflicts; an invalid response or missing provenance stops the affected run with the returned findings still visible.
Triage every finding against source. Record a refutation only with evidence; put every open signature and parent action in loop-actions.json, then validate it. Before fix dispatch, write a short per-signature closure plan under loop-report.md Remediation: the failed invariant, original counterexample, next ordinary consumer, all known sibling routes or write sites, and the source paths whose actual changes must be inspected. Delegate feasible fixes by disjoint finding domain, with one owner per file set; a child chunk run returns its actions to the coordinator parent instead of dispatching solvers. Give each solver this plan and a focused acceptance check that fails on the reviewed source. An action labeled fix is an assignment, never proof of completion. Parent owns integration, gates, and any shared-file conflict.
Wait for every fix agent under Agent Waits, then inspect the actual source diff and verify each attempted repair against its original counterexample and at least one distinct sibling route when one exists, through the next consumer. Record the failing-before and passing-after checks, or the exact missing capability and remaining finding, in loop-report.md under the signature. A passing unit test of only the producer, a child-reported changed-file list, or a solver summary cannot close a consumer-path finding. Freeze corrected source and the supporting modules used by those checks before another review; a solver's handoff and local tests leave fixes fixed-pending-verification until a fresh independent challenger checks the current source. Keep the solver report in the parent record, never in the next challenger input. If the invariant still fails, keep the finding open, investigate the incomplete fix, and do not dispatch a repeat challenge merely to rediscover it. After every wait, including an empty return, report completed/expected counts, pending roles and elapsed time before any next tool call; include the last observed event or no new progress evidence, deadline and next action. Never infer child liveness from an empty return or wait without an outstanding accepted dispatch.
Repeat from step 1 while the unchanged-scope integer total score strictly decreases and authority, recurrence, evidence and stricter caller-budget rules permit. For each same-scope repeat review, report the prior round's open weighted score and the current open weight of all previously reported signatures, including reopened ones. Report newly discovered weight separately from carried-open residue. Apply the canonical total-score rule: any decrease converges, equal weight is plateau, and increased weight is non-converging. New discoveries cannot conceal unresolved prior findings or reset their signatures, recurrence history, or a stricter caller budget. A different-scope child has no comparable ratio: retain the parent stop, show its prior finding status, and wait for complete current-source coverage before claiming reduction. Never infer closure from an omitted signature alone.
At clean, plateau, cap, stale-source, conflicting evidence, or unavailable-review stop, report only validated round scores and all remaining findings. For unexpected blockers, stop the affected route and give one recommended remediation action plus meaningful alternatives. Reuse explicit user decisions and existing authorization; perform a permitted bounded recovery and resume the first unmet checkpoint when the owning retry and stop rules allow it. Ask only for a specific missing decision or authority, never repeat a decision the user already made. Keep unrelated authorized work separate.

Read adversarial_loop.py --help before using it. Record each validated round append-only: write it as one JSON object to <run-directory>/loop-rounds.jsonl.rec with the filesystem tool, then run adversarial_loop.py --ledger <run-directory>/loop-ledger.json --append --progress --append-metrics, after staging the round's cost record in <run-directory>/loop-metrics.jsonl.rec (schema_version 1, kind round, round, route (parent, or agent:/bridge:/codex:/other: plus a label), brief (always full: the frozen context shape is fixed here), brief_bytes, duration_s (seconds, a number), tokens_in, tokens_out, attested_gaps (integers); null for any unknown, attested_gaps null after round 1 and when no attestation was written, an integer (0 included) otherwise; a rejected cost record only warns and never blocks the round); rewrite only the loop-ledger.json header's current_snapshot, never an earlier round line. Retain loop-ledger.json with its loop-rounds.jsonl round log, loop-actions.json, round-<index>.diff, current snapshot current.diff, and each independent report. When asked for loop status/history, show every completed review or aggregate checkpoint immediately in the fixed history layout, with admission explicit; do not substitute the five-stage source-rating legend or the final no-round placeholder. Aggregate checkpoints identify their constituent reviewers in the retained report. This descriptive status view does not append canonical rounds or certify closure. During normal execution, show the progress table exactly once after each newly validated round, with Iteration | Security | Critical | High | Medium | Low | Nits | Weighted score and literal old + new cells; never show a placeholder or repeat it in unrelated status updates. Keep the final Results table separate, with ranked severity counts per challenge. A completed reviewer response without a validated ledger is review completed, canonical round blocked, not an unqualified not-run; preserve its original findings and score each response descriptively while naming the missing gate. No paid retry follows from an older wave approval.

Collect scoped source snapshots with the existing collect_diff.py snapshot mode, retain loop-evidence.json per evidence-contract.md. Use existing Code Review routing, frozen contexts, specialist manifests for reviewer provenance; never manufacture a second runtime evidence format. Every participating reviewer receives the exact snapshot contents, diff, response contract, returns one structured response containing every finding, with only the route-required provenance header outside it. Preserve original reports and runtime evidence.

Before dispatch through the isolated Codex reviewer route, run validate_evidence.py --preflight-plan <frozen-plan.json> --request-evidence <run>/loop-evidence.json --supporting-source <frozen-supporting.json> when supporting paths exist; omit the last option otherwise. This no-model gate checks canonical current source and supporting bytes, evidence-declared source copies, the current scoped tracked patch, plan digests, and exact line-start source, diff, request, and supporting labels in the frozen challenger context. Then run the route's separate no-model host check. Stop paid dispatch on either failure and preserve the frozen plan. Diagnose and perform any bounded recovery under existing authorization, then rerun the applicable checks when the owning retry and denial rules permit. Ask only for a missing decision or new authority; never request again an explicit user decision already given.

This explicitly requested loop uses the shared orchestration policy's bounded serial-review exception; disjoint fix agents may work after the parent has validated and scored the round and assigned one owner per file set. Request a 1,500-output-token reviewer target per the shared budget rule: apply a runtime per-reviewer limit only when it reports an overrun instead of cutting the structured response, otherwise record the target as advisory. Never truncate findings; report an overrun as a capacity gap. Re-plan and request a decision only when the next round needs new scope, authority, or a caller-specific approval. There is no fake independence fallback: parent-serial inspection stays labeled non-independent and cannot satisfy this skill's clean outcome.

03: Verify closure and run normal gates¶

Use schema-2 loop-evidence.json with origin for current single runs and copy its origin to result metadata. For a continuation, bind the caller ledger digest, include its canonical final-round findings in the frozen request, and require a current reviewer verdict on every earlier signature. Require the reviewer to state inspected primary and supporting paths plus limits in the structured assessment. This stated coverage is a reviewer claim, not proof of line-level inspection; an incomplete declaration blocks clean closure.

Require independent final current-source coverage before reporting clean. Run adversarial_loop.py --ledger <run-directory>/loop-ledger.json for the computed stop decision, then this skill's validate_evidence.py for existing reviewer provenance, returned findings, dispatched source contents, freshly recaptured current source. Derive the runtime log root and active CODEX_THREAD_ID from the observed host configuration, never from review input or the ledger. A declared identity or saved hash alone is insufficient. Never turn rejected evidence into accepted coverage.

Failing-before and passing-after pytest checks in the fix loop follow Sandboxed Test Runs; the canonical gate below keeps the project's configured test command.

Use run_gates.py for actual project lint, format, types, tests, review, with explicit reasons for genuinely inapplicable checks. Include adversarial_loop.py --ledger <run-directory>/loop-ledger.json --require-clean in the review gate, along with checks of independent coverage, current source, request conformance. The flag exits nonzero for a valid but non-clean loop, so a stopped ledger cannot masquerade as a passing review gate. Report status=fail with the concrete reason when the loop is not clean. For a supplied caller, resume its first unmet checkpoint, complete its ordinary gates and artifact contract too; neither result substitutes for the other.

04: Validate and hand off¶

Store the checker's exact JSON summary in ADVERSARIAL_LOOP_METADATA.adversarial_loop, and keep action_contract_version: 3 in result metadata with a schema-3 loop-actions.json. New candidates set challenge_scope to {"mode":"single"} for one scoped run, or the exact chunked declaration in chunk-path.md for a coordinator; a visible chunks/ directory cannot be labeled single. Follow the shared helper lifecycle: render bound handoff, write candidate with write-result.py, validate as challenge-resolve, promote only validated artifacts. Include confidence evidence, gaps, remediation actions, and residual limits. Default validation requires the action contract for candidate and final results; older artifacts lacking it can be read as data but cannot be validated under the current contract. Shared validation reruns action and evidence validation as well as binding the computed decision and visible output. Existing native or local reviewer wave evidence retains its actual trust level; neither becomes cryptographic proof of source correctness. The host has no table-delivery receipt: report the once-per-round chat timing as an instruction-level limit, not a machine-verified guarantee.

Fail-Fast Rules¶

Missing scope, specification, source, or required independent route prevents clean completion.
Shared hard stops take precedence over improvement and passing tests; a structural fix needs explicit authority only when it expands scope or crosses another approval boundary.
A non-converging score stops the affected loop under the shared ratio rule; report only validated rounds and obtain the next scoped decision before another attempt.
A malformed ledger, missing report, snapshot mismatch, or unverified closure blocks acceptance. Preserve the failed evidence and give the specific remediation action, not a bare unresolved status.
A clean loop does not waive caller completion checks, authorization, or recurrence rules.

Quality Gates¶

Use ../../shared/quality-gates.md. Required review evidence includes the validated ledger, original independent reports, current snapshot binding, finding dispositions, caller completion when applicable. No finding disappears merely because it was not selected or a check became green.

Calibration Hooks¶

Cover clean review, pending fixes, repeated signatures with improving score, feasible structural fixes, authority stops, score boundaries, decreasing runs beyond three reviews, stricter caller budgets, source changes after review, unavailable independent coverage, table timing, severe-finding escalation, reviewer budget fidelity and self-contained reply topic. Exercise both remediation and truthful failed handoffs; never weaken independent coverage to pass calibration.

Output Contract¶

Follow ../../shared/final-handoff-contract.md; after validation and promotion emit final.md verbatim. Use result-template.json for schema-v2 metadata.

For a chunked coordinator:

Run chunk_diff.py check --manifest <coordinator-run>/chunks/chunks.json --results <coordinator-run>/chunks/results.json --summary for complete clean coverage, or chunk_diff.py check-stopped --manifest <coordinator-run>/chunks/chunks.json --results <coordinator-run>/chunks/results.json --summary for the partial stopped map. Copy the exact JSON into metadata.chunked_review.
Omit the coordinator's loop-ledger.json, loop-rounds.jsonl, and metadata.adversarial_loop: it has no own independent round.
For complete clean checked coverage, set result and review gate to pass with zero findings. For a stopped summary, set result and review gate to fail, include review in checks_failed, and retain a remaining item and next step. Both states use one admission: unavailable / not-run | N/A ... | chunk-only | chunks/results.json Results row and copy chunked_review.runs into final-handoff.json as child_runs. The row records the absence of a coordinator round, not absence of checked child coverage; never synthesize a combined score or whole-scope reviewer receipt.
Revalidate the coordinator candidate after source changes and before promotion; promoted results keep the same live coverage check.

Final chat¶

Outcome: identify the reviewed topic and clean or the specific stop reason.
Results: exactly Challenge | Security | Critical | High | Medium | Low | Nits | Weighted score | Decision | Evidence.
Use one layout: challenge-history table: preserve the ordered validated rounds and include every completed unadmitted review/checkpoint in chronological position.
Each row declares admission: validated | advisory | unavailable; advisory rows also require a nonempty admission_reason.
A Checkpoint N row represents a parent aggregate, not one independent reviewer; its retained report identifies each constituent reviewer. A single returned unadmitted review uses Advisory N.
Use the one-based challenge index. Each ranked severity and weighted-score cell is literal old + new: old means an open signature seen in any earlier completed round (including a reopened one), new means an open signature first seen in this round. Include 0 + 0; count open and fixed-pending-verification, and bind all cells, decision, and retained report path to the checker. State this legend beside the table.
With no validated round but completed advisory history, show the advisory rows and the generated no-validation notice. Only when no completed history exists use admission: unavailable, not-run, N/A in all six severity cells and the score cell, the checker's stop reason, and loop-report.md. Never show zero counts for an unreviewed challenge. Advisory rows never satisfy completion, change canonical counts/scores, or remove a failed review gate.
Set challenge_table_contract_version: 2 in result metadata and presentation_version=13 for every new current handoff; use the new history layout for both single runs and chunk coordinators. Store exact run-relative report paths in machine Evidence cells. The renderer keeps paths out of every table cell and lists each as - <challenge>: <file-path> below the table; preserve non-path evidence prose, using the common handoff contract's lossless detail fallback for ambiguous plain cells. Reports must be nonempty retained files inside the run. Version 1 keeps its existing strict ledger validation and historical rendering; obsolete totals-only layouts remain rejected.
During execution, show the cumulative --progress table once after each newly completed validated round, before fixes or the next review. This in-turn transcript is separate from the canonical final Results table.
With no validated round, report the admission gap explicitly; descriptive advisory history is separate from the normal canonical progress table. Unsolicited updates do not repeat tables without a new round; an explicit status/history request receives the complete labelled history. Never invent a clean canonical row or omit a table due after an actual round.
Show the score series and each remaining finding's disposition, reason, owner, and next action. Report actual implemented fixes separately from evidence-only closure; no code fixes means say so. The common result counts fold security into critical and nit into low; the ledger retains all six tiers.
Next steps: recommended remediation action and relevant alternatives on stops; ask only for the missing decision.
Confidence includes independence/provenance and execution limits, not just a number. Artifact: .reports/codex/challenge-resolve/<timestamp>/result.json.