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.
- Triage the returned findings before proceeding:
- a. 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).
- b. A changed title or file location is not a new defect, and severity does not determine identity.
- c. 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.
- d. 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.
- e. Record one schema-2
loop-evidence.rounds[].triage mapping per raw reviewer finding, with a reason and evidence for any corrected identity or severity.
- f. Keep the raw response intact; validate source and reviewer evidence, stage the mapped round in
<run-directory>/loop-rounds.jsonl.rec and run the full append invocation below (including --append-metrics) per the append-only round rule below, and show its weighted old/new table.
- g. 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. Complete useful parent work before waiting. Use timeout_ms: 60000, shortened for the active host's user-update cadence or nearest child deadline. Respect the active tool's timeout bounds and short-budget handling in shared/native-skill-contract.md §Agent Waits: report early for a cadence budget below the minimum; for a nearer child deadline use the minimum valid wait, disclose its timing granularity, keep the recorded deadline and assess expiry at the first return. Report on state changes or when the active host's user-update cadence is due; omit duplicate status for unchanged empty returns before that cadence. When reporting, include completed/expected counts, pending roles, elapsed time, last observed event or no new progress evidence, deadline and next action before any next tool call. Check child deadlines after every return and report a missed deadline at once. 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 known-invariant open weight. 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.
If native response intake reports review-challenge-disposition-invalid, automatically apply Code Review's bounded disposition correction before ledger admission. Reuse authenticated source inspection, preserve the original response, and allow only the single generated correction attempt; no parent relabeling or full-source reread solely for this mismatch. All source, provenance, finding and closing gates still apply.
- a. 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.
- b. 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.
- c. 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.
- d. Aggregate checkpoints identify their constituent reviewers in the retained report.
- e. This descriptive status view does not append canonical rounds or certify closure.
- f. 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.
- g. Keep the final
Results table separate, with ranked severity counts per challenge.
- h. 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.
- i. 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. For a scoped run, 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. A chunk coordinator has no own ledger; use the chunk gates below and the Output Contract instead. 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, except that section's documentation-only skip.
Use run_gates.py for actual project lint, format, types, tests, review, with explicit reasons for genuinely inapplicable checks. For a scoped run, 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. For a chunk coordinator, use chunk_diff.py check --manifest <coordinator-run>/chunks/chunks.json --results <coordinator-run>/chunks/results.json --summary for the clean review gate; use chunk_diff.py check-stopped --manifest <coordinator-run>/chunks/chunks.json --results <coordinator-run>/chunks/results.json --summary to validate a stopped coordinator and keep its review gate failed. Report status=fail with the concrete reason when the loop or coordinator 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.
The chunk coordinator omits its own loop ledger and adversarial_loop.py --require-clean check; the chunk clean/stopped checks above replace that ledger gate only for the coordinator. Each child and interaction run retains its ordinary loop ledger and review gate.
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=15 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 only the ledger helper's cumulative
--progress table, legend and reconciliation lines once after each newly completed validated round, before fixes or the next review; never hand-build the table or tabulate pre-ledger reviews. 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.
1---2name: challenge-resolve3description: Independently review and fix a bounded task through convergence rounds, with evidence-backed closure and explicit stop/remediation decisions. Use for an explicitly invoked adversarial review-and-fix loop over an existing implementation, feature, problem, or diff, including repeated review/fix requests or a second independent review of the same change; not for ordinary review (code-review) or single-pass finding remediation (code-remediate).4metadata:5 source: https://skillmd.com/skills/borda/challenge-resolve6---78> Before asking, read [User Questions](../../shared/codex-user-questions.md).910# Challenge and Resolve1112> Task-size routing follows [Proportional Execution](../../shared/native-skill-contract.md#proportional-execution); this skill's specialized lifecycle and acceptance checks remain authoritative.1314Read, 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](../../shared/native-skill-contract.md#authorized-workflow-execution) for authority; [Acceptance and recovery](../../shared/native-skill-contract.md#acceptance-and-recovery) and [Evidence Rules](../../shared/native-skill-contract.md#evidence-rules) for evidence limits; [Bounded Dispatch Wave](../../shared/specialist-orchestration.md#bounded-dispatch-wave), [Read-only work and executable probes](../../shared/specialist-orchestration.md#read-only-work-and-executable-probes), [Portable Role Routing](../../shared/specialist-orchestration.md#portable-role-routing) and [Retry And Checkpoint Policy](../../shared/specialist-orchestration.md#retry-and-checkpoint-policy) for reviewer admission. Recurrence follows the stop rules in `../../shared/adversarial-loop.md`.1516## Input Schema1718```json19{20 "goal": "required review-and-fix objective",21 "scope_files": ["bounded source paths relevant to the task; discover them when initially unknown"],22 "specification": "required behavior or acceptance criteria",23 "symptom": "reported problem, feature objective, or preventive review",24 "caller_run": "optional existing workflow run to resume",25 "done_when": "independent final review is clean and normal checks pass"26}27```2829Begin 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.3031> 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.3233## Workflow3435### 01: Establish scope and evidence ownership3637Read `../../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.3839Before 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.4041Before 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.4243For 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.4445Before 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.4647#### Bounded chunk path4849> 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](references/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.5051### 02: Run the shared bounded procedure5253Use 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:54551. 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.562. Triage the returned findings before proceeding:57 - a. 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).58 - b. A changed title or file location is not a new defect, and severity does not determine identity.59 - c. 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.60 - d. 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.61 - e. Record one schema-2 `loop-evidence.rounds[].triage` mapping per raw reviewer finding, with a reason and evidence for any corrected identity or severity.62 - f. Keep the raw response intact; validate source and reviewer evidence, stage the mapped round in `<run-directory>/loop-rounds.jsonl.rec` and run the full append invocation below (including `--append-metrics`) per the append-only round rule below, and show its weighted old/new table.63 - g. One reviewer avoids same-round classification conflicts; an invalid response or missing provenance stops the affected run with the returned findings still visible.643. 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.654. Wait for every fix agent under [Agent Waits](../../shared/native-skill-contract.md#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. Complete useful parent work before waiting. Use `timeout_ms: 60000`, shortened for the active host's user-update cadence or nearest child deadline. Respect the active tool's timeout bounds and short-budget handling in `shared/native-skill-contract.md` §Agent Waits: report early for a cadence budget below the minimum; for a nearer child deadline use the minimum valid wait, disclose its timing granularity, keep the recorded deadline and assess expiry at the first return. Report on state changes or when the active host's user-update cadence is due; omit duplicate status for unchanged empty returns before that cadence. When reporting, include completed/expected counts, pending roles, elapsed time, last observed event or `no new progress evidence`, deadline and next action before any next tool call. Check child deadlines after every return and report a missed deadline at once. Never infer child liveness from an empty return or wait without an outstanding accepted dispatch.665. 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 known-invariant open weight. 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.676. 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.6869Read `adversarial_loop.py --help` before using it.7071If native response intake reports `review-challenge-disposition-invalid`, automatically apply Code Review's [bounded disposition correction](../code-review/references/validation-recovery.md) before ledger admission. Reuse authenticated source inspection, preserve the original response, and allow only the single generated correction attempt; no parent relabeling or full-source reread solely for this mismatch. All source, provenance, finding and closing gates still apply.7273- a. 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.74- b. 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.75- c. 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.76- d. Aggregate checkpoints identify their constituent reviewers in the retained report.77- e. This descriptive status view does not append canonical rounds or certify closure.78- f. 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.79- g. Keep the final `Results` table separate, with ranked severity counts per challenge.80- h. 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.81- i. No paid retry follows from an older wave approval.8283Collect 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.8485Before 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.8687This 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.8889### 03: Verify closure and run normal gates9091Use 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.9293Require independent final current-source coverage before reporting clean. For a scoped run, 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. A chunk coordinator has no own ledger; use the chunk gates below and the Output Contract instead. 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.9495Failing-before and passing-after pytest checks in the fix loop follow [Sandboxed Test Runs](../../shared/native-skill-contract.md#sandboxed-test-runs); the canonical gate below keeps the project's configured test command, except that section's documentation-only skip.9697Use `run_gates.py` for actual project lint, format, types, tests, review, with explicit reasons for genuinely inapplicable checks. For a scoped run, 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. For a chunk coordinator, use `chunk_diff.py check --manifest <coordinator-run>/chunks/chunks.json --results <coordinator-run>/chunks/results.json --summary` for the clean review gate; use `chunk_diff.py check-stopped --manifest <coordinator-run>/chunks/chunks.json --results <coordinator-run>/chunks/results.json --summary` to validate a stopped coordinator and keep its review gate failed. Report `status=fail` with the concrete reason when the loop or coordinator 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.9899The chunk coordinator omits its own loop ledger and `adversarial_loop.py --require-clean` check; the chunk clean/stopped checks above replace that ledger gate only for the coordinator. Each child and interaction run retains its ordinary loop ledger and review gate.100101### 04: Validate and hand off102103Store 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](references/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.104105## Fail-Fast Rules106107- Missing scope, specification, source, or required independent route prevents clean completion.108- 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.109- 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.110- 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.111- A clean loop does not waive caller completion checks, authorization, or recurrence rules.112113## Quality Gates114115Use `../../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.116117## Calibration Hooks118119Cover 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.120121## Output Contract122123Follow `../../shared/final-handoff-contract.md`; after validation and promotion emit `final.md` verbatim. Use `result-template.json` for schema-v2 metadata.124125For a chunked coordinator:1261271. 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`.1282. Omit the coordinator's `loop-ledger.json`, `loop-rounds.jsonl`, and `metadata.adversarial_loop`: it has no own independent round.1293. 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.1304. Revalidate the coordinator candidate after source changes and before promotion; promoted results keep the same live coverage check.131132### Final chat133134- `Outcome`: identify the reviewed topic and `clean` or the specific stop reason.135- `Results`: exactly `Challenge | Security | Critical | High | Medium | Low | Nits | Weighted score | Decision | Evidence`.136 - Use one `layout: challenge-history` table: preserve the ordered validated rounds and include every completed unadmitted review/checkpoint in chronological position.137 - Each row declares `admission: validated | advisory | unavailable`; advisory rows also require a nonempty `admission_reason`.138 - 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`.139 - 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.140 - 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.141 - Set `challenge_table_contract_version: 2` in result metadata and `presentation_version=15` 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.142- During execution, show only the ledger helper's cumulative `--progress` table, legend and reconciliation lines once after each newly completed validated round, before fixes or the next review; never hand-build the table or tabulate pre-ledger reviews. This in-turn transcript is separate from the canonical final `Results` table.143- 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.144- 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.145- `Next steps`: recommended remediation action and relevant alternatives on stops; ask only for the missing decision.146- Confidence includes independence/provenance and execution limits, not just a number. Artifact: `.reports/codex/challenge-resolve/<timestamp>/result.json`.