HG Adversarial Resolve

Use scripts/adversarial_resolve.py as the durable state and budget controller. Act as the builder and evidence referee; the external reviewer is an adversary, not an authority.

Establish the run contract

1. Start from a fresh origin/main worktree and preserve unrelated changes.
2. Translate the objective into observable success criteria. Infer safe criteria rather than making John or Victoria specify every test.
3. Require an explicit total external-review budget. Also set per-round, final-review reserve, Anthropic, and monthly ceilings. Leave max_rounds unset unless the user explicitly requests a round cap.
4. Require explicit authorization before sending the scoped diff, synthetic fixtures, screenshots, or test output to external providers. One authorization may cover every round of the named run.
5. Record whether normal repository merge rules apply or the run must stop before merge.
6. Never place secrets, customer data, personal travel documents, credentials, or private business data in the objective, fixtures, or review packet.

Create a version-1 JSON spec using the schema in docs/adversarial-resolve.md. Keep temporary specs outside the repo; the controller copies the normalized contract into its ignored run directory.

Initialize:

python3 scripts/adversarial_resolve.py init --spec /private/tmp/hg-resolve-objective.json

If authorization was granted after initialization, record it only after the user grants it:

python3 scripts/adversarial_resolve.py authorize --run <run-dir> --external-review

Build the acceptance surface

• Add deterministic tests before or with the fix whenever the failure can recur.
• For factual benchmarks, store the expected result, primary source, verification date, and freshness/expiration rule. Model recollection is not an oracle.
• Keep known regression fixtures and fresh held-out cases distinct. Promote every confirmed held-out failure into the permanent suite after repair.
• For visual work, include faithful 1440px, device-emulated 390px, and required 320px checks. Do not hide visual uncertainty behind a code-only verdict.
• Put free deterministic commands in acceptance_commands. Do not hide separately paid hg-verify or UX-review calls there; give those tools their own explicit caps and report their spend separately.

Run and resolve rounds

Run one round:

python3 scripts/adversarial_resolve.py round --run <run-dir>

The controller runs acceptance commands, creates a fresh code_verify.py packet, invokes hg-code-review with the remaining exploratory allowance, assigns stable finding IDs, records provider costs, and evaluates stop conditions. It will not spend the protected final-review reserve during an exploratory round.

For NEEDS_FIX:

1. Inspect round-NN/findings.json and the supporting review packet.
2. Reproduce each finding or verify it against primary evidence. A finding blocks by default only when it is blocker/high, confirmed, concrete, and within the frozen release contract.
3. Record the disposition:

python3 scripts/adversarial_resolve.py triage \
  --run <run-dir> \
  --finding <finding-id> \
  --status confirmed \
  --evidence "Reproduced by the new regression test ..."

1. Fix confirmed issues and add a regression test. Mark them resolved with evidence once the deterministic test passes.
2. Mark false findings invalid only with concrete evidence. Do not implement a reviewer suggestion merely to make the model agree.
3. Defer only non-critical findings when the run contract permits it. Never defer blockers or highs.
4. Rerun the full round. The controller refuses to pay when both a previously failed diff and its evidence-triage record are unchanged.

Do not weaken tests, remove a valid benchmark, broaden tolerances, or rewrite success criteria to manufacture a pass. Cluster lexical variants under their root cause, and do not chase invented synonyms outside the documented parser contract. If the requirement genuinely changes, create a new run contract or obtain explicit user direction.

When exploratory work is ready, or the controller returns AWAITING_FINAL_REVIEW, run:

python3 scripts/adversarial_resolve.py round --run <run-dir> --final

Stop and ship correctly

Treat only controller status resolved as adversarial resolution. It requires green deterministic checks, an accepted complete final reviewer verdict, and no unresolved configured blocking findings.

• stopped_budget: report spend and remaining findings; never imply resolution.
• stopped_round_limit: applies only when the spec explicitly configured max_rounds; report the best current state and unresolved evidence.
• stopped_no_progress: applies only when the spec explicitly enabled stop_on_repeated_findings; stop changing code blindly and request the missing evidence or decision.
• stopped_tool_error: preserve artifacts and diagnose the provider/tool failure without widening scope.
• authority or repository stop condition: stop even if the resolver is green.

After resolved, run any additional repository gates that the controller did not own, then follow the repository’s PR and merge policy. Report objective, rounds, total and provider spend, tests added, findings fixed or disproved, final verdict, PR/deployment state, and any separately metered review costs.

Budget semantics

The run budget covers hg-code-review API calls launched by this controller. Codex application usage is not expressed as API dollars. Exploratory rounds cannot consume the protected final-review reserve. The reviewer launches its required providers sequentially with stage reservations, and the controller records provider-reported spend before permitting another round. The monthly verifier ledger remains an independent runaway-spend guard.