Complete large reviews in bounded batches

prepare --batches freezes the complete selected source and emits batch-inventory.json plus a serial source-wave schedule. Each native context stays within 65,536 UTF-8 bytes; source fragments retain exact file identities and byte intervals. New prepared batch inventories freeze review_topology=source-only: each triggered role owns one source-review responsibility, represented by one pass when it fits or by bounded source parts when actual context capacity requires splitting. These parts preserve exact source coverage and are not separate responsibilities or replacement attempts. A native wave retains its complete required role roster and holds at most four allocated child slots. Follow its generated largest-context-first order, preserve genuine capacity refusals and refill proven free slots at observed parent scheduling opportunities as in Prepare and dispatch the complete wave; queued roles stay in the same wave even when the host pool is smaller. Join every role, then use assemble-wave --out <contained-wave-directory> from the generated schedule. Finish assembly before dispatching the next dependent source wave; successful batches are separate evidence, never retry attempts.

For the new source-only topology, complete and assemble the scheduled source waves, then run assemble-batches; do not create interaction or final-consolidation review waves. The aggregate retains every source finding and its immutable origin mapping. A role's representative assessment comes from its highest-rated source part, with earliest-part ties; source_parts retain each raw assessment and the initial confidence is the lowest constituent score. A later clean part cannot erase an adverse rating, finding, or confidence gap. Schema-nine source-only aggregates use the normal result-validation and remediation evidence lookup. Historical inventories without review_topology retain their original strict interaction and final-consolidation requirements and remain readable under their admitted templates; do not infer source-only topology or relax historical admission from missing newer fields.

New batch inventories use generation schema two. Historical schema-one inventories retain their supported producer templates. For the historical topology, every generated interaction and final context includes the complete rating scale. When a historical interaction or fitting-final context was never issued, preparation uses the complete current rating legend and confidence instructions; that exact prefix is recognized on later reconstruction while the four proved issued templates remain supported. On resume, the aggregate reconstructs complete contexts from admitted source and outputs using an explicitly recognized historical template; an unknown or mixed template remains a compatibility failure. Never overwrite frozen contexts or accept their hashes alone to bypass a producer mismatch. Individual wave admission does not prove the later aggregate can consume those waves; verify ordinary aggregate reconstruction before claiming the full review complete.

The steps below that prepare interaction briefs, interaction waves and final consolidation apply to historical batch inventories without review_topology. New source-only inventories finish after complete source-wave assembly and the aggregate steps; do not add interaction or consolidation waves to them.

1. Finish every source wave with actual assessments, complete audited reads and native terminal receipts. Every batched response must follow the generated individual-finding profile below; retain complete raw output and provenance. A later clean answer cannot erase an earlier unresolved finding.
2. Freeze interaction-briefs.json for every triggered role. Include focused evidence and complete selected source intervals, including material unchanged callers. Declare bounded paired source ranges for producer/caller dependencies and dependencies spanning fragments. Every selected path needs its applicable pair coverage; record genuine exclusions rather than silently omitting an interaction.
3. Run prepare-interactions, then complete every generated serial interaction wave through its dispatch and assemble-wave. These contexts preserve source coverage, overlapping boundaries, declared pairs and lossless original reviewer evidence. A required pair exceeding the bounded context remains an explicit coverage failure; do not claim a completed interaction review.
4. Run prepare-consolidation. A fitting context produces the existing final native wave. When the mandatory evidence exceeds the context limit, complete every serial wave in generated consolidation-dispatch.json, using its exact dispatch and assemble-wave before starting the next wave. Bounded final packets preserve whole report occurrences and adjacent origin/source witnesses; deterministic group pairs provide comparison opportunities across packet boundaries. Every role must complete its full schedule. These are successful review parts, never replacement attempts. Do not claim that one child saw the complete evidence union. An indivisible report or origin/witness bundle exceeding the group budget remains an explicit capacity failure; do not truncate, summarize, raise the cap or split away relied-on evidence.
5. Run assemble-batches once, after all scheduled final parts are admitted. Assembly reconstructs the complete schedule and contexts from retained evidence, validates every constituent's native provenance and ordering, and retains findings from all parts. Fitting historical aggregates retain schema eight; multipart aggregates use schema nine with native parts remaining schema eight.
6. For multipart results, preserve the generated per-role part ledger: source_parts for new source-only topology, final_parts for historical multipart final consolidation. The role's representative assessment points to its actual highest-rating part, with the earliest part breaking ties; its confidence cannot hide a lower constituent confidence. Retain every part's scope, rating, rationale and confidence gaps. A later clean part cannot erase an earlier adverse assessment or unresolved obligation. Use the aggregate's derived values and normal result validation; never fabricate a combined reviewer response.
7. The lowest constituent confidence remains the immutable initial confidence, with every part's original score, scope, gaps, status, rationale and hash retained. It remains the final ceiling unless schema-nine global recovery accounting is complete. A higher aggregate confidence requires exact one-to-one accounting for every carried nonclosed qualified part gap and residual, admitted evidence for each claimed closure or evidence-backed reduction, explicit current deductions for unresolved or deferred gaps, and contributions that reconcile to the final score. The parent judges whether evidence closes a cause; validation checks references and accounting, not the truth of free-form rationale. Recovery never changes a constituent judgment, removes a gap or actionable finding, or treats review completion as proof that the underlying change is correct.
8. Copy the aggregate source_findings ledger into result metadata. Map every unresolved individual finding_id to exactly one canonical review_findings ID, or its parent candidate ID when review_validation is present, in source_finding_mapping. Preserve every original record and origin, including severity, title, summary, required change, closure evidence, author, manifest path and declared path:start_line-end_line references. Group obligations only by one of two paths: exact duplicates may share an action when their canonical payloads and source evidence are equal, with source_finding_duplicates mapping each later original ID to the first sorted original ID; or distinct variants may share one action only when parent source judgment establishes one canonical required change and closure obligation covers every origin. For reconciled variants, retain all origins in source_finding_reconciliation with nonempty invariant and rationale plus frozen-source witnesses for each original obligation, union every author and evidence reference, and set canonical severity to the strongest origin. The validator binds the full origin inventory, exact source witnesses and strongest severity; the parent and independent verification judge semantic equivalence. Exact canonical field equality remains required when no reconciliation is supplied. Counts come from explicit records, never assessment ratings. A low-severity finding remains actionable even when the pass has zero blockers. Normal gates, final handoff validation and report promotion still apply.

Every batched native response uses individual-finding profile version one: ## Reviewer Findings, one fenced json array, optional ## Finding Dispositions, then ## Reviewer Confidence with one fenced JSON object, then ## Reviewer Assessment with Rating: <1-5> and one-line Rationale:. Each array record has exactly id, severity, title, summary, required_change, closure_evidence and evidence. IDs are unique within the response; severity is critical, high, medium or low; descriptive fields are nonempty. Evidence is an array of frozen source coordinates with exactly path, start_line and end_line. Declare [] explicitly when no findings exist. Put every finding in this inventory, with no additional prose findings outside it. Confidence has exactly score (0–1), scope (the inspected boundary) and gaps (an array of {gap,status,rationale} with closed, unresolved or deferred status and supporting evidence or rationale). Preserve every material evidence gap; completion claims require at least 0.90, and absent or malformed confidence fails admission. The producer validates coordinates, binds frozen source hashes and generates global origin identities; never transcribe hashes. This required profile applies only to generated batched waves; ordinary unbatched native responses and historical strict readers retain their existing format.

A source batch is a declared fragment, not the whole review. If a test, material unchanged caller, or other required source lies in a later frozen fragment, record the scoped limitation and complete the remaining scheduled source waves for source-only topology. For historical inventories without review_topology, also complete the required interaction review. Do not call the entire source unavailable or stop dispatch because the current excerpt ends before that source. Missing required source/caller coverage remains a blocker in either topology; interaction-pair coverage is additionally required only where the historical topology declares it. A scoped rating or confidence must not pretend later source was already inspected.

For the historical interaction/consolidation topology, a later independent role may explicitly dispose an earlier individual only when its frozen context contains the exact original record and cited frozen source bytes. Use Source disposition <generated-finding-id>: closed|rejected; Evidence: <path>:<start>-<end> - <source-backed explanation>. Generated examples may prefix the explanation with Existing behavior: or False positive:; those phrases and explanation length are not acceptance gates. The evidence must establish existing behavior, not a claimed unverified fix. Historical final consolidation includes bounded witnesses for source and intermediate findings when they fit. For source-only topology, individual response dispositions do not remove source findings: every original remains in the aggregate origin ledger and can be addressed only through the parent-owned reconciliation in step 5; a missing source witness or required caller coverage remains unresolved. A witness that exceeds the existing context ceiling is omitted with a diagnostic; the original remains unresolved and actionable. Do not block primary remediation merely to obtain an optional historical dismissal. A review with defects can complete with retained actions and a failed recommendation; missing required source/caller coverage cannot certify completion, and historical interaction coverage remains required where declared.

Each wave carries only the explicit advisory choices for roles present in that wave; the immutable global choice remains bound to the complete review. Never attach an absent advisory role to a shorter wave or drop its choice from a wave that uses it.

Each interaction brief contains axis, contained evidence_path, and source_paths entries with exactly path, start_line and end_line from the frozen source. Optional paired_ranges contains lists of at least two such ranges to inspect together, including nonadjacent ranges within one file. Small multi-file scopes can use the full-range default; large scopes require explicit bounded meaningful pairs. A single-file scope has no invented cross-file prerequisite. Freeze these obligations before dispatch.

Inspect the helper subcommand help for exact arguments and generated wave IDs. Use generated schedules and artifacts; never hand-copy hashes or convert multiple successful waves into one role's retry history. Context delivery establishes evidence availability, not proof of reviewer comprehension or complete discovery of semantic dependencies. Parent scope and finding reconciliation remain required.

For a historical schema-six run rejected only by a copied provenance header, inspect review_prepare.py recover-native-provenance --help. Supply the retained actual Codex home, original reader and original plan coordinates; recovery verifies original routing, role cards, complete native page receipts, output and join records before emitting a separate schema-eight candidate. Never run the Codemap adapter retroactively for such a run: keep its existing codemap-context.json, or, when it has none, set result metadata codemap_context to not-required-historical. Preserve the old artifacts and malformed response unchanged. Admit the candidate only through existing manifest and result validators. Missing runtime evidence remains a failure; never repair a digest by hand or certify unobserved source coverage.

Track dispatch.json context/dispatch byte counts, rejected dispatches, actual overlapping reviewer intervals, gate duration, and observed parent/child token usage when the host exposes it. Byte reduction is not a measured token or end-to-end latency improvement. Quality comparisons require the same scope, required roles, findings and gates; do not reduce coverage or inflate confidence to meet a timing target.