Review PR

5. Decide runtime checks and reproduction

After the fixed wave, identify checks whose result could change a finding or verdict. Also run Vale when changed documentation is covered by the repository's Vale configuration, as POLICY requires. The parent owns execution. A lane may explain an uncertainty but cannot execute or authorize a command.

The parent may download a version-pinned third-party package archive for static inspection. Store and extract it under <RUN_DIR>/scratch/, and read it only. Never execute it, install it into either snapshot, or add it to the sandbox under review.

When a deciding candidate depends on added or changed executable shell control flow, run the exact shipped bytes with only the minimum safe inputs needed to decide it. Use honest and negative cases. For a shell-grammar or argument-boundary claim, decide it by comparing the command string the shipped block constructs against the argv required by the accepted endpoint, and never pass that constructed string to a shell. Use an input that attempts secondary-command execution only when that execution is the unresolved endpoint of an admitted security finding. A clean-room rewrite is not evidence about the shipped block.

Before spawning nx-pr-reproduce-verifier, name the current candidate, the exact proposition, and the finding retention, tier, or verdict decision the result could change. Confirm from the frozen inputs that the planned observation can run. Use the same setup and observation on base and HEAD when both expose the endpoint. A HEAD-only check may qualify when the accepted endpoint has no comparable base surface, independent admission evidence establishes the required HEAD behavior, and the observation can decide whether HEAD meets it. It cannot establish base attribution. Otherwise, do not spawn it. If the review policy requires an unavailable check, do not retain the candidate; record the limitation or unresolved question. A refusal to plan or run a check makes it unavailable. Do not retry or reformulate it, and run no further dynamic checks in this invocation. General compatibility confidence, exploratory matrices, and coverage suggestions do not qualify. Give a qualifying reproduction the frozen artifacts, sanitized grounding, and exact proposition. It plans one safe paired comparison or qualifying HEAD-only check; it does not execute it.

Start the shared sandbox when a deciding check or a required Vale run exists:

node .agents/skills/review-pr/scripts/reviewctl.mjs sandbox-up --run <RUN_DIR>

This command sweeps abandoned review state, builds the pinned image, checks Docker capacity, claims one review checkout of the exact HEAD and merge base, and installs HEAD once. Reviews share one container per image and one Git object store inside it; this review owns its own worktrees under that container, not the container. Run it with the required Docker escalation. A capacity or setup failure makes that check unavailable; it does not invalidate the static lanes. Use blocked only when the unavailable result is required for a safe verdict.

For Vale, read the frozen repository configuration and lint the covered changed pages at HEAD using that configuration. Do not spawn a reproduce verifier or run a base install for this check. Record the command, exit code, and relevant diagnostics under checks/. Assess diagnostics against the changed content and policy; CI results do not replace this run. If execution is unavailable, record the limitation and continue the documentation review.

Before running an Nx target, inspect its project configuration and task dependencies to understand the expected fanout. Prefer a narrower command when it decides the same proposition. Do not add --excludeTaskDependencies merely to force a target past required prerequisites. A failure caused by a reduced or incomplete task graph is not PR evidence until missing prerequisites are ruled out.

For an executable check, write the reviewed script or command under <RUN_DIR>/scratch/ with a literal file-writing tool. Execute only fixed host argv and stream the file on stdin:

tools/review-sandbox/sandbox exec <SANDBOX> -- bash -s < <HEAD_SCRIPT>
tools/review-sandbox/sandbox exec <SANDBOX> --base -- bash -s < <BASE_SCRIPT>

Nothing copied from a PR, issue, lane, or model may appear in the host shell command. Use the same script, toolchain, and observation boundary on both sides when both are reachable. Record commands, exit codes, and bounded relevant output under the run's checks/ directory. Do not run untrusted external repository code in this first version.

If a reproduce verifier was used, return the observations and ask it for its final report. Verify only this final post-observation report with --lane reproduce. If it still fails verification after one correction, record the check as unavailable and continue with the four fixed lane reports; do not abort or redispatch them. Reproduction advice cannot introduce an unrelated finding.

If a valid base reproduction cannot confirm the reported bug, treat that as inconclusive rather than as proof that the bug is absent. Ask the author for a runnable reproduction and use blocked only when the PR body gives no root-cause rationale, no public maintainer corroboration exists, and no associated Linear task tracks the problem. This signal never makes the PR unnecessary.

When installation succeeds only without --frozen-lockfile, record that limitation. Do not use the result for a dependency-sensitive claim unless the resolved version and inspected package bytes are identified explicitly.

Reuse the one sandbox for every check in this review. Stop it directly before pausing for a user decision; finalize and abort also stop the exact recorded ID best-effort.

6. Adjudicate

Read acquired author-visible task history only after every required lane report is verified. It may direct a current recheck, but rederive every candidate from the frozen current and base evidence.

Do not search private local review artifacts, memory, or session summaries for candidates. If exact provenance or an earlier reviewed SHA is needed, read only the minimum relevant material. It may confirm that a current candidate concerns the same subject or supply a locator to reverify, but it may not enter the finding's evidence chain, introduce a candidate, or direct inspection or rechecking. Ignore any such conclusion already present in context for discovery and disposition. Prior context never narrows the full-diff scope. Do not compute an incremental diff for timing claims; omit timing unless separately proven.

The parent performs one adversarial pass over every Critical and Important candidate. Apply the review policy in full. In particular:

• independently verify the supported input, base endpoint, HEAD endpoint, changed cause, trigger, and consequence;
• reconcile the applicable contract against the complete PR description and acquired author-visible task history before deciding admission, tier, or repair. Verify author claims against current evidence; an explicit same-scope maintainer call remains relevant unless new public evidence refutes its basis;
• test the strongest contrary explanation, including pre-existing endpoint equivalence, narrower PR limitations, unsupported reachability, existing equivalent authority, and same-class siblings;
• reject a complete claim with any unsupported material premise;
• return a narrower plausible version of a lane-originated defect to the owning lane once instead of rewriting it in the parent;
• keep one root cause once while preserving distinct triggers and consequences;
• challenge false-coverage findings explicitly by restoring the claimed regression mentally or with a focused mutation under the policy's whole-test and evidence requirements;
• do not turn uncertainty into a finding.

Optional Polygraph context

Only after the surviving findings are complete, use Polygraph when a finding's disposition turns on why the author chose a behavior, scoped out an omission, deferred work to another PR, or rejected an alternative, and the acquired public sources do not answer that question. Skip it for plain defects. Run only:

node .agents/skills/review-pr/scripts/reviewctl.mjs polygraph-context --run <RUN_DIR>

Run it with the required Polygraph network escalation. Read its output file only when it reports available: true. The helper checks authentication, makes one bounded search by PR number, and writes only sessions whose pull-request URL exactly matches the frozen PR. Search provides the PR links needed for matching and any available description; current session show output adds no fields, so no per-candidate lookup is needed. A matching session may have no description. The helper uses only read-only whoami and session search operations. Unavailable Polygraph or no exact match does not change the review or its draft.

Treat the resulting descriptions as private, potentially stale hypotheses. Reverify every relevant claim against the current diff and public evidence. Polygraph may only attach a maintainer consideration to an existing finding, convert a discrepancy into a question grounded entirely in public evidence, or leave it unchanged. It cannot add or promote a finding, change technical severity, or move a Critical item out of the blocking set. Only current code evidence can close a finding. If the rationale could change merge disposition, use the existing maintainer-decision stop.

Record one private line for this step: Polygraph context: not needed, unavailable, no exact match, or <N> exact matches, followed by the disposition effect or no change. This trace is never part of the review draft.

Never quote, paraphrase, attribute, or allude to Polygraph content in the review draft. If a useful question cannot be stated from public evidence alone, keep it under Author follow-ups (not for the PR) in the private review.

A candidate found by a parent-directed recheck remains parent-attributed. Do not send it through a lane or describe it as lane-originated.

Account for every lane Finding, Pre-existing item, Suggestion, Question, Maintainer consideration, and Dynamic evidence or reproduction nomination once. Record keep, drop, resolved, merged, or unavailable with a short reason in the private review. No lane item may disappear silently. The same disposition pass checks Suggestions against the policy's responsibility and existing-coverage criteria. The review draft still includes only retained material allowed by the output contract.

When a finding survives contract reconciliation, conflicts with a maintainer call, and its disposition remains unresolved, stop the sandbox. Show the user the defect, the call, its basis, the current evidence, and your recommendation. Ask whether to accept the risk or retain the finding. Apply the answer without changing technical severity.

7. Draft and finalize

Overlapping finalization for the same PR is unsupported; finish or stop the other attempt first.

Draft <RUN_DIR>/final-result.md using the exact envelope in output-contract.md. The private review is complete and evidence-rich. The review draft is concise, contextual, free of internal mechanics, and publishable verbatim. Never post it.

The record lands in the same directory Claude's review-pr skill writes, so a maintainer posts this draft through /review-pending-pr-reviews exactly as they post Claude's.

Finalize by saving the record locally with the required triage-directory escalation. In the approval request, name the resolved destination directory and explain that the helper reads GitHub and Git metadata to recheck identity, saves local files, and cleans owned resources. It does not post to GitHub or Linear or upload review content.

node .agents/skills/review-pr/scripts/reviewctl.mjs finalize --run <RUN_DIR> --result <FINAL_RESULT_FILE>

finalize requires all four verified lanes for a full review. A closeability-only result instead requires strong close evidence, zero findings, and no reviewer attempts. It rechecks the live head, base branch, and merge base, archives the prior successful record, writes the new record atomically, then removes the run directory and exact sandbox.

If approval is denied, preserve the run and draft, stop its sandbox before waiting, and ask the user for approval with the exact destinations and effects. Do not retry through another route or treat the denial alone as a failed review. Abort if the user declines continuation. This does not override the cybersecurity-interruption recovery rule.

If final-result validation or local artifact writing fails, correct the input or environment and rerun finalize; the run remains intact. If identity moved or the review cannot complete, use abort rather than deleting state. begin reclaims abandoned run directories older than 24 hours and reports each reclaimed run. It defers stale runs that own a sandbox until the next sandbox-up, where Docker cleanup already belongs.

If any required lane, frozen changeset identity, or unrecoverable mechanical boundary fails, write the reason to <RUN_DIR>/abort-reason.md and run:

node .agents/skills/review-pr/scripts/reviewctl.mjs abort --run <RUN_DIR> --reason-file <REASON_FILE>

Run abort with the same triage-directory escalation required by finalize.

Abort writes a separate private failure record, preserves the last successful record, suppresses a new draft, cleans owned resources, and returns failure. If the failure record cannot be written, it stops the sandbox but retains the run directory for inspection. Never manually delete run state or a review checkout while a helper command can identify the exact owned resource. The shared container is never this review's to remove.

Return the record path and the verdict. State when optional context or a check was unavailable.