Perform the repository's risk-tiered independent final review before implementation completion. Use only when explicitly invoked or when repository instructions require it after behavior-impacting implementation work; audit the complete task diff, supported contracts, lifecycle and security boundaries, complexity, and tests before final verification.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
The command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
File Explorer
10 files
Showing SKILL.md
SKILL.md
Source instructions · Read-only preview
name
implementation-final-review
description
Perform the repository's risk-tiered independent final review before implementation completion. Use only when explicitly invoked or when repository instructions require it after behavior-impacting implementation work; audit the complete task diff, supported contracts, lifecycle and security boundaries, complexity, and tests before final verification.
Implementation Final Review
Treat implementation and final review as separate phases. Reconstruct the change from the original requirement and the complete diff; do not defend the current design merely because it is implemented or tested.
Non-negotiable guarantees
Review the exact final task content, including committed, staged, unstaged, and task-owned untracked deliverables. The only exception is the narrowly verified final-gate base-advance closure in step 20, which preserves clean credit through explicit identity evidence and still requires the complete final verification stack on the resulting fingerprint.
Use the merge-base three-dot diff for patch ownership and the latest release tag separately for released compatibility.
Require independent review. A same-context self-review cannot satisfy the clean-review gate.
Freeze task-owned content while reviewers inspect a fingerprint.
Treat an exact normalized file path in the task and component manifests as authoritative even when ignore rules match that file. An existing exact file takes literal precedence over Git pathspec metacharacters; use explicit :(glob) magic when pattern semantics are intended. A directory or glob pathspec never promotes ignored operational files into the review.
Require the repository and every initialized submodule index to have no unresolved merge stages before fingerprinting.
Require every initialized submodule, including nested submodules, to be clean and checked out at the commit recorded by its parent index before freezing review state. Stage reviewable gitlink pointer changes in the parent repository; fail closed on dirty worktrees, hidden index flags, ignored nested changes, and untracked embedded repositories. Reject cyclic or aliased submodule worktree graphs before recursive inspection.
Require two consecutive identical observations of HEAD, status, diffs, task and repository workspace content, and component workspace content before accepting a review-state snapshot. Fail closed when repository state changes during capture.
Reject task-owned filesystem entries that Git cannot represent as finite blobs, including FIFOs, sockets, and devices.
Require packet, ledger, manifest, receipt, reviewer-output, and evidence paths to resolve to finite regular files. Canonicalize each path before opening. Verify the file type after opening and read content from that same descriptor; never authorize a path with stat and then reopen it. Reject evidence, receipt, and current-versus-prior ledger aliases by the opened descriptor's device and inode identity. Before accepting reviewer output or a reusable receipt, re-read the packet and current and prior ledgers and require their validated digests to remain unchanged; also re-read the indexed receipt before reporting it reusable. Materialize devices, FIFOs, sockets, or generated streams into regular files before validation.
Bind every canonical root-owned evidence ID and inventory ID in the ledger with contract_evidence_sha256 and inventory_sha256. Preserve those digest bindings across rounds so an existing ID cannot change content; inventory digests exclude only the ID itself so a renamed copy is not new semantic inventory.
Count evidence or inventory as new for a canonical root only when its digest is absent from that root's prior ownership. A new root proposal requires an evidence digest absent from every canonical root and every distinct root proposed in the same output; it cannot reuse canonical inventory before implementer promotion. Require every credited receipt to have a unique content digest and exact command.
Require unique keys and standard finite numbers in every JSON object. Duplicate keys, JavaScript-style NaN or infinity constants, and numeric exponents that overflow to infinity are invalid. Convert runtime numeric-size and nesting-limit failures into protocol errors instead of leaking parser exceptions.
Give the two reviewers distinct normalized primary and high-risk specialties, and require every preflight command to be unique before any receipt can claim it.
Encode manifests.dependency_map as an object that maps every component name to a nonempty array of exact pathspec and reason records. Reject prose-only claims, missing components, empty dependency sets, duplicate pathspecs, and extra record fields.
Treat verification receipts, reviewer outputs, findings, root-cause evidence, unchecked-inventory records, and sibling-scenario scans as exact schemas. Reject unknown fields instead of ignoring potentially conflicting evidence.
Repeat commit-hook inspection, every safe rewriting step, second-pass idempotence, and generated-provenance validation before every fingerprint freeze, including post-fix and delta-review rounds. Record the exact executable inspection and rewriting commands plus their results in packet preflight evidence; a prose label is not an executable command.
Start independent reviewers without inherited conversation history. Fresh judgment does not require repeatedly replaying the implementer's context.
Report only concrete, patch-scoped findings supported by requirements, released behavior, a durable boundary, explicit maintainer intent, user reliance, or a baseline regression.
Never weaken final repository verification. Component-aware review invalidation reduces repeated review, not required build or test gates.
Keep one task-global round ledger across pauses, compaction, handoff, renaming, resumed work, and post-completion feedback. Enforce a bounded budget for each active review cycle without discarding earlier history.
Trust the active implementation control plane to record actual reviewer dispatches, waits, outputs, and verification executions. The local protocol helper validates those records but does not replace platform-issued cryptographic execution attestation.
Post-completion feedback boundary
An implementation review cycle is complete only after its clean-review gate, mandatory verification, any requested local commit, and final user-facing handoff are complete. Seal that cycle at this boundary. A pause, compaction, context change, agent handoff before completion, or ordinary request to continue unfinished work does not create a new cycle or reset its budget.
A later user message containing concrete actionable review feedback starts a post-completion feedback cycle. The feedback message itself authorizes implementing that feedback and running the repository-mandated focused tests, delta review, verification, and local commit or amendment needed to return the task to a completed state. Do not ask for separate review-budget authorization merely because the sealed implementation cycle exhausted its budget.
Keep the same task identity and ledger, preserve its canonical root-cause history and clean credit for unchanged components, and append a default budget of two fingerprint rounds for the new feedback cycle. Ask the user again only when the feedback materially widens the requested contract, changes a released or durable compatibility boundary, requires authority beyond resolving the feedback, or exhausts the feedback-cycle budget.
Workflow
Persist the current combined content fingerprint as ledger.round_fingerprint and bind it to the packet fingerprint. A same-round retry is valid only when that value and the authorized budget history match the immutable prior ledger snapshot; a changed fingerprint or newly authorized budget advances the round.
Finish the initial implementation and focused tests. Apply formatting before review when formatting can rewrite the diff. Inspect the actual final commit-hook configuration and run the exact safe, non-committing equivalent of every hook step that can rewrite task-owned content before freezing the first review fingerprint. Run each rewriting step until a second execution is content-idempotent. Normalize generated files before computing embedded hashes or provenance so the hook cannot invalidate them later. Record any hook step that cannot safely run before review; if that step later changes task content, apply the normal invalidation rules without exception.
Re-read the original user request and the current implementation scope contract. If no contract exists, record the required behavior, compatibility requirements, intentionally unsupported cases and failure behavior, and supported alternative or none.
Resolve the intended target and merge base. If a supplied target or base is not an ancestor of HEAD, compute their common merge base and treat merge-base...HEAD as the task-owned diff. Use the latest release tag separately when released compatibility is the relevant boundary. Include committed, staged, unstaged, and untracked changes that belong to the task.
Read the complete task-owned three-dot diff from the resolved merge base. Never treat target-only commits between the merge base and an advanced or divergent target as deletions or regressions introduced by the patch. Check integration with the current target separately when relevant; report an actual conflict or semantic incompatibility, not mere absence of target-side changes. Do not limit review to the latest fix or files named in prior feedback. Record a complexity delta: runtime lines changed, new state fields, new synchronization or ownership mechanisms, affected subsystems, and test permutations.
Run the baseline-reset gate before accepting the current design:
Describe the required behavior without referring to branch-local helper types or state.
Identify the nearest released/base pipeline that already owns the behavior.
Compare patching the current diff with replacing task-owned branch-local machinery by a narrow change from the base implementation.
Treat unreleased implementation and tests as disposable. Preserve unrelated or user-owned changes.
Choose the narrower design unless concrete contract evidence requires the current machinery.
Select the relevant review dimensions below from the affected runtime boundaries and repository architecture references. Complete every selected dimension even after finding a blocker; the goal is a complete final review, not the first valid comment. Classify review risk before dispatch: normal when the change does not affect concurrency, cancellation, security, trust, persistence, durable state, released compatibility, package/runtime exports, protocol ownership, or cross-provider lifecycle; elevated when any of those boundaries changes or an earlier round produced P0/P1. Run the cheapest affected-boundary preflight broad enough to catch likely late fallout from a dependency, package surface, generated artifact, or cross-cutting runtime change. Prefer focused tests plus a narrowly targeted import, generated-surface, or static check. Run a targeted type check only when the change directly affects a typing boundary and the command is materially narrower than repository-wide . Do not run repository-wide lint, typecheck, builds, examples runners, integration suites, , or merely to enter or iterate through the review gate. Run the focused preflight once for a semantic state and rerun only affected checks after fixes.
Maintain one compact round ledger throughout all review cycles and persist it as a durable, task-global artifact:
Persist enough task identity, used and authorized round budgets, cycle boundaries, fingerprints, root-cause closure state, and clean credit to resume without reconstructing prior rounds. Update it only at a meaningful state transition: round start, accepted finding batch, complexity reset, clean result, verification result, sealed completion, or post-completion feedback-cycle start. Do not emit repeated waiting messages when neither reviewer state nor repository content changed.
Independent reviewer
An independent review uses a fresh no-history context that did not implement the fingerprinted content and is not given prior reviewer findings or implementer conclusions. Prefer a distinct agent and set fork_turns: "none" when the platform exposes that control. A same-context self-review or full-history fork is not independent and cannot satisfy the clean-review gate.
Give the reviewer the original requirement, implementation scope contract, base and head identifiers, canonical component manifest and fingerprints, raw repository state, and relevant architecture references.
Give the reviewer the precomputed contract-surface and await-boundary or authority/data-flow inventories. These are coverage maps, not conclusions; require the reviewer to validate every row against the raw diff and surrounding source.
Tell the reviewer which identifier is the intended target and require an explicit merge-base calculation. When target and head diverge, provide or request a three-dot diff; do not present a two-dot target-to-head diff as the patch.
Do not give the reviewer the implementer's conclusions, suspected bugs, intended fixes, or a list of expected findings.
Ask for exactly one read-only review round. The reviewer must not edit or stage files, run the autonomous review loop recursively, spawn another reviewer, or perform the final repository verification. The implementer owns finding validation, edits, loop control, and final verification.
Give every reviewer for a round the same review-state fingerprint and keep the diff frozen until all of them finish. Reject output produced from a different or changing state instead of merging partial observations across revisions.
Give every reviewer the compact self-contained control-plane brief, indexed evidence paths and digests, and one exact revalidation command. If any mandatory packet field is neither populated nor explicitly marked none or not applicable, the reviewer must report it and cannot return a creditable clean verdict. Tell reviewers not to inspect memory, rediscover workflow skills, rerun implementation strategy, search for the fingerprint helper, or rediscover the release tag unless supplied evidence is inconsistent or decision-relevant. Reopening source cannot replace missing packet contents. This preserves fresh judgment while avoiding repeated setup work.
Use fresh reviewers for every round when possible. Do not reveal findings or conclusions from prior rounds; provide only the updated requirement, scope contract, raw final diff, component manifest, and relevant references.
Use two concurrent fresh reviewers for every round. For the high-risk conditions in step 12, assign complementary high-risk specialties while requiring each reviewer to inspect the complete diff. Both reviewers of the same unchanged diff are one fingerprint round. Do not duplicate broad test execution.
Concurrent reviewers receive the same fingerprint and raw context but different primary specialties. They must not communicate during the round.
Give the reviewer existing verification commands and results as raw evidence. The reviewer should inspect code and tests, then run only focused probes needed to resolve a decision-relevant uncertainty. A probe must be demonstrably non-mutating or run in an isolated temporary checkout; any mutation of the reviewed worktree invalidates the round. Prefix repository Python probes with so importing helpers or running unittest cannot create inside the frozen worktree. Do not rerun the repository's broad test, typecheck, lint, build, or integration suites merely to reconfirm the implementer's evidence; the implementer runs the complete stack once after the clean-review gate.
When an independent reviewer is unavailable, rebuild context from the original request, scope contract, source, and complete diff before a best-effort self-review. Explicitly discard incremental-review assumptions, label the result non-independent, and do not count it toward the clean-review gate. Report the unavailable gate at handoff instead of silently weakening it.
Review dimensions
Choose dimensions based on the changed boundary; do not mechanically invent findings for every item.
Requirement and scope
Verify that the smallest required caller-visible behavior works.
Identify nearby constructible cases and confirm they are either intentionally supported or rejected before side effects.
Require contract evidence before treating repeated, concurrent, reentrant, malformed, wrapped, or cross-provider combinations as blockers. Reproduce the same supported scenario on the baseline when claiming a regression.
Check whether tests accidentally turn implementation permutations into public contract.
Map every new abstraction, state field, branch, dependency, and cross-module change to a requirement, supported contract, or verified risk.
Compatibility and identity
Compare released public signatures, field order, imports, names, serialized values, configuration, and wire behavior.
Preserve exact caller-visible identity or spelling unless transformation is required.
Distinguish unreleased branch-local machinery from released or durable compatibility boundaries.
For every new or modified public field, enumerate all construction, forwarding, and consumption branches. Verify that normal, specialized, default, missing-value, and error paths either honor the field or reject it according to one coherent contract; do not validate only the motivating branch.
Search public docs, examples, docstrings, configuration reference, and release metadata for claims made stale by the behavior change. Missing documentation can be an actionable omission even when no documentation file is in the diff. Apply the repository's Documentation Release Timing policy before classifying the omission: required docs/ content that would describe unreleased behavior is separately timed work, not a defect in the current task or pull request.
Lifecycle and failures
Trace ownership from acquisition through success, failure, cancellation, retry, replacement, and cleanup.
When shared lifecycle state changes, build a compact operation-state matrix before concluding. Cover each affected public mutating operation against never-started, partial-failure, active, cleanup-in-progress, and terminal states as applicable.
Trace repeated sequential calls and every relevant pair of overlapping public mutating operations. Identify the linearization point or manager-owned serialization mechanism; do not infer safety from per-resource deduplication alone.
Check repeated cancellation, partial initialization, cleanup failure, retry through every supported public entry point, and primary-exception preservation.
State the final survivor invariant: which tasks, workers, processes, sessions, listeners, files, or remote resources may remain.
Review ordering when several validations or cleanup actions can short-circuit one another.
Audit every check-await-side-effect sequence. State may change during the await; require revalidation or prove manager-owned serialization before cancellation, feedback, persistence, or cleanup.
Distinguish current state from historical evidence. If a stale-result guarantee depends on whether a newer operation ever started, an active pointer that later returns to undefined or null cannot prove absence; use or require monotonic evidence unless the operation is serialized.
Security, trust, persistence, and protocol
Trace caller-controlled data through logs, exceptions, causes, contexts, telemetry, model-visible output, and persisted state.
Treat serialized state as authority only when the supported trust boundary explicitly allows it.
Check fail-closed behavior for malformed or ambiguous sensitive inputs without returning or retaining the original value.
Verify protocol capability ownership, pagination termination, cache ownership, retry and replay safety, wire validation, and tool or call identity when affected.
Behavioral parity
Compare streaming and non-streaming, sync and async, initial and resumed, direct and wrapped, and provider-specific paths when the requirement crosses them.
Verify that one path does not silently ignore, reshape, or hard-fail data that another path supports.
Tests and generated public surfaces
Prefer public-boundary or caller-visible adversarial tests.
Exercise the highest stable caller boundary that reproduces the required behavior. A helper-only test is insufficient when a caller transforms the input, owns the lifecycle, or determines the observable result before or after invoking that helper.
Require expected values and failure signals to come from the contract, a worked example, a baseline, or another independent oracle. Do not accept an assertion that recomputes the expected result with the same logic as the implementation.
Use a narrower internal boundary when a lifecycle, concurrency, provider-wire, or malformed-stream scenario cannot be controlled reliably through a public entry point, and record why that boundary is necessary.
Add controlled interleavings for concurrency instead of relying only on sequential tests.
Test the required behavior, the nearest supported alternative, and one representative input per unsupported category.
Do not accept passing existing tests as proof when they encode the same assumptions as the implementation.
Import through intended consumer entry points and verify generated or distribution artifacts when public package behavior changes; runtime tests alone do not prove the published surface.
Complexity reset
Run a complexity reset when related findings keep expanding the same design, a narrow requirement requires recursive or cached classification, tests enumerate mechanics, representations are inferred in multiple places, or the diff spreads unexpectedly across subsystems.
Stop addressing findings one by one.
Group them by root cause and restate the original required behavior.
Compare the full diff with the merge base or release boundary.
Delete branch-local machinery that is not required.
Reuse the nearest existing source-of-truth pipeline.
Narrow unsupported behavior and reject it before side effects with a supported alternative when one exists.
Rebuild tests around caller-visible invariants and representative negative cases.
Compare the replacement's runtime and test complexity with both the previous round and the merge base. A reset that only renames or redistributes a growing state machine is not a reset.
Review-state workspace entries must use the exact key set emitted for their file, symlink, gitlink, directory, or missing kind; incomplete or unknown fields fail before dispatch.
For reusable verification credit, a receipt command must exactly match a structured command in verification.preflight_results; a different successful command cannot inherit verification credit.
Review output
Return exactly one JSON object using the schema in references/reviewer-brief.md. Put the verdict in verdict; put each actionable finding in findings with its priority, title, location, concrete failure scenario, user-visible consequence, support basis, baseline-versus-patch evidence when applicable, smallest safe correction, and stable root-cause ID. Account for every assigned inventory ID and keep unverified runtime uncertainty explicit. Do not claim implementation completion until both structured clean reviews and required verification apply to the exact final state.
pnpm -r build-check
pnpm test:review
pnpm test
Build the pre-dispatch evidence required by the changed boundary:
For every changed public symbol, configuration field, event, serialized field, wire value, or documented caller-visible behavior, create a contract-surface inventory: producers and constructors; every consumer, forwarding branch, and adapter; default, missing, and invalid-value behavior; package exports and generated public surfaces when applicable; adjacent docs and examples; and caller-visible tests. Search adjacent contract surfaces even when they are absent from the diff. A required example, export, adapter, or generated-surface update is a missing task deliverable, not out of scope merely because it is not yet in the manifest. A required docs/ update is also a missing task deliverable unless the repository's Documentation Release Timing policy intentionally defers it. When that policy applies, record the documentation need and timing as evidence of separately timed work; do not add it to the current task manifest, report it as a current-pull-request finding, or let it block clean review.
For concurrency, cancellation, reentrancy, shared lifecycle state, or a check followed by an await before a side effect, create an await-boundary matrix. For each relevant operation, record the state snapshot, blocking or await point, events and operations that may run while suspended, durable or monotonic evidence retained, revalidation before each side effect, and resulting cancel, feedback, persistence, or cleanup action. Include source completion, a newer operation active with known and unknown identity, a newer operation that starts and completes while suspended, and failure or cancellation of the awaited action when those states are supported. If correctness depends on whether something ever happened, current active state is insufficient unless serialization proves it cannot be lost; require monotonic identity, generation, tombstone, or equivalent durable evidence.
For protocol, persistence, or security changes, create the analogous authority/data-flow inventory from input through validation, storage, retry or replay, output, exceptions, logs, telemetry, and cleanup. Treat these as mechanical coverage artifacts, not implementation conclusions. The implementer must fill them from code and contract evidence before review; reviewers validate them independently against the complete diff and surrounding source.
Produce only concrete, patch-scoped findings that are reproducible from code, contract, documentation, or a focused probe. Do not report hypothetical extensibility or unrelated cleanup. Before concluding, account for every row in the contract-surface, await-boundary, and authority/data-flow inventories and every new or modified source of shared state. For a scenario outside the required behavior, run a differential check against the merge base or latest release and identify support evidence. Reachability through a public method, concurrent call, repeated call, host-language protocol, or third-party behavior is not by itself a supported contract.
Classify every finding before editing:
required-behavior defect;
released compatibility or durable-boundary defect;
missing failure-path or adversarial coverage;
unsupported neighboring case that should fail earlier;
unnecessary machinery or duplicated source of truth;
unrelated or unsupported suggestion to reject. Record the support basis for every actionable finding: original requirement, released documentation/example/typing/test, durable boundary, concrete maintainer intent or user reliance, or a regression where the same supported scenario succeeds at the baseline and fails in the patch. If none applies, do not fix or block on it; mark it unsupported/deferred.
Resume or create the task-global review ledger. Use the Codex task or thread ID as the stable task identity when available; otherwise generate one identity once. Persist that exact identity as ledger.task_id and require it to match the packet task identity. Store the ledger as an ignored operational file at a stable absolute path, include that path in every reviewer packet and handoff, and preserve the same file when work moves to another worktree. Never initialize a new counter merely because the task was paused, compacted, handed off, renamed, moved to another worktree, or resumed in another context. Start fingerprint round 1 only when the ledger has no prior round for this task; a same-fingerprint request for missing reviewer fields remains in the current round. The default autonomous budget for the initial implementation cycle is six fingerprint rounds. After that cycle has completed under the post-completion feedback boundary, concrete actionable review feedback starts a post-completion feedback cycle: treat the feedback message itself as authorization to append a default budget of two fingerprint rounds to the same ledger. Do not reset the round counter, canonical root-cause history, or clean credit for unchanged components. A continuation request without concrete new feedback remains in the existing cycle. Outside this post-completion feedback rule, only explicit user authorization may add another bounded budget, and the existing ledger and root-cause history must remain attached. The implementer assigns every root-cause ID once in the ledger using a stable canonical ID and includes the complete open and closed root set in every later packet. A reviewer must reuse one supplied canonical ID or propose exactly NEW:<slug> with content-new contract evidence; only the implementer may promote that proposal and assign canonical inventory in the ledger. Create one canonical manifest of every task-owned shipped path, including both sides of a rename and task-owned untracked files. Plans, review ledgers, packets, traces, temporary reports, and other workflow artifacts are operational-only by default even when repository policy requires creating them; include one only when the original requirement or repository policy explicitly makes that exact path a committed deliverable. Keep operational files outside the shipped manifest and account for them as repository exclusions. Keep the shipped manifest stable and update it only when task-owned deliverable paths actually change. Partition the manifest by the narrowest stable semantic boundaries that match the patch. In openai-agents-js, prefer components such as public-api, session-persistence, provider-adapters, sandbox-security, tests-examples, and release-metadata when present; do not create empty components or split tightly coupled files merely to preserve credit. Every changed deliverable must belong to exactly one component. For each component, record an exact semantic dependency-input pathspec set plus the reason each input can affect the component; do not use a coarse directory or prose-only none claim when build configuration, generated-surface owners, or shared runtime code are dependencies. When this skill's resources are available, prefer PYTHONDONTWRITEBYTECODE=1 python3 .agents/skills/implementation-final-review/scripts/review_state.py --repo <worktree> --base <merge-base> --pathspec-file task.paths --component-pathspec-file public-api=public-api.paths ... --complete-diff-output <complete.diff>; direct --pathspec and repeated --component NAME=PATHSPEC remain available for smaller diffs. Always generate the complete-diff artifact through --complete-diff-output; a standalone git diff omits ordinary untracked deliverables. Retain each component content_fingerprint, the combined content_fingerprint, and repository_fingerprint. Omit all pathspecs only when every repository change belongs to the task. Record the complexity delta and findings grouped by stable root-cause ID, severity, action, and whether each finding is new, repeated, or reintroduced.
Prepare one self-contained reviewer snapshot packet per round using references/reviewer-brief.md when available. Compute shared evidence once and reuse the same requirement, scope contract, target/base/head, manifests, fingerprint JSON, raw status, complete-diff command, preflight results, contract-surface inventory, state/data-flow inventories, and selected architecture excerpts for every reviewer. Assign stable IDs to every inventory row and evidence item. Populate every kind-specific inventory field documented by the reviewer brief; a summary-only inventory row is incomplete. Store the exact review_state.py JSON as the single artifact with role: "review-state", store the raw output produced by that command's --complete-diff-output as the single artifact with role: "complete-diff", store unfiltered git status --porcelain=v1 -z --untracked-files=all output as the single artifact with role: "repository-status", and mark other artifacts with role: "supporting". The packet's review_state.evidence_id points to the review-state artifact instead of copying fingerprint values, and repository.status_evidence_id points to the repository-status artifact. The repository fingerprint covers unfiltered status plus content identity for every changed path, including paths outside the task manifest. Assign every component and all three control artifacts to both reviewers. Packet preflight derives the combined and component fingerprints from the review-state artifact, requires the task and component manifests to match its pathspecs, requires complete_diff_paths to equal the task workspace exactly, requires the complete-diff digest to match its complete_diff_sha256, requires the status digest to match its unfiltered status fingerprint, and requires repository.exclusions to account exactly for every changed path outside the task manifest with a concrete reason. Every canonical ledger contract evidence ID must resolve to an indexed evidence artifact, and the ledger digest maps must bind the exact owned evidence and inventory content. Keep the task ID, task-global ledger path, and the immediately preceding round's immutable ledger snapshot plus SHA-256 digest in the active control plane outside the packet; never derive these authority arguments from the packet under validation, and never use the mutable current ledger as its own prior snapshot. Supply all four independently on every validator invocation after round 1. The validator requires packet, current-ledger, and prior-ledger identity to match those arguments, accepts only a same-round retry or an advance of exactly one round, reconciles the current round and remaining budget with the append-only authorized budget history, preserves the prior budget prefix, canonical root ownership, and owned-content digests, and assigns every inventory ID to exactly one canonical root. Keep the control-plane brief concise, with approximately 12 KB as a soft target; put larger raw diffs, logs, matrices, and reference excerpts in indexed evidence files and provide their exact paths plus SHA-256 digests. Exceed the target when compression would omit decision-relevant evidence, and record why. Populate every template field or mark it explicitly none or not applicable; do not dispatch an incomplete packet. Before dispatch, encode the packet index in the machine-readable schema documented by the reviewer brief and run PYTHONDONTWRITEBYTECODE=1 python3 .agents/skills/implementation-final-review/scripts/review_protocol.py packet --packet <packet.json> --task-id <task-id> --ledger <ledger.json> --prior-ledger <prior-ledger.json> --prior-ledger-sha256 <sha256> after round 1. Dispatch only when it exits successfully; use its emitted packet path, byte size, SHA-256 digest, exact combined fingerprint, component fingerprints, inventory IDs, and reviewer IDs as the launch record. Give each reviewer one ready-to-run fingerprint revalidation command and only the specialty assignment may differ. Do not ask reviewers to rediscover the workflow skill, implementation strategy, memory, release tag, manifest paths, helper location, or verification history. A reviewer may reopen primary source or released evidence when supplied evidence is inconsistent, appears wrong, or leaves a decision-relevant ambiguity, but reopening is not a substitute for missing mandatory packet contents and routine context reconstruction is implementer work.
Freeze task-owned content while reviewers for a round are running. Dispatch two independent reviewers concurrently on the same fingerprint. For normal risk, give them distinct primary dimensions that together cover the selected review surface. For elevated risk or a prior P0/P1, give them complementary high-risk specialties. Every reviewer sees the complete raw diff and may report blockers outside its specialty. When the platform supports context-fork control, dispatch every reviewer with fork_turns: "none"; never pass the implementer's accumulated conversation or use a full-history fork. Launch both reviewers before waiting. Wait for both reviewers in the round before editing so findings can be grouped and fixed as one batch. Use one event-driven wait of 240 seconds or the platform's multi-target first-completion wait. Do not poll with list_agents, separate short waits, progress questions, or no-op followup_task messages. If an event-driven wait times out while reviewers remain unfinished, issue another event-driven 240-second wait for the unfinished set; repeat without polling until a reviewer completes, needs attention, or no unfinished reviewers remain. After one reviewer completes, continue waiting only for the remaining reviewer with another event-driven 240-second wait, applying the same timeout rule. A reviewer process that fails before producing a protocol-valid output because of startup, service, content-filter, context, or tool infrastructure has produced neither a finding nor clean credit and does not advance ledger.current_round or consume another fingerprint round. Replace only that reviewer on the same frozen packet and assignment; a protocol-valid output already accepted from the other reviewer remains usable while the task fingerprint, packet, and assignment are unchanged. The original two-reviewer concurrent dispatch satisfies the round's concurrency requirement; the accepted peer output plus one independently launched replacement output on the identical packet and assignment form the required pair. If an independent replacement remains unavailable, report the gate as unavailable instead of counting an infrastructure failure as review evidence. Do not start any broad final repository gate while review is incomplete or finding-bearing. In openai-agents-js, defer pnpm i --frozen-lockfile, pnpm build, pnpm -r build-check, pnpm -r -F "@openai/*" dist:check, pnpm lint, pnpm test, pnpm format:check:changed, examples runners, and integration suites until step 19 establishes clean review. Use reviewer wait time for non-mutating evidence consolidation, finding classification preparation, host-capacity inspection, or other task work that cannot change the frozen fingerprint; otherwise continue the event-driven wait without progress polling. For repository Python probes, prefix interpreter commands with PYTHONDONTWRITEBYTECODE=1 unless they run in an isolated temporary checkout; an untracked __pycache__ or similar generated file mutates the repository fingerprint and invalidates the round. During an iterative review round, run only focused checks that target the changed boundary. Do not run pnpm test:review, pnpm test, or repository-wide pnpm -r build-check during an iterative review round. Use pnpm exec vitest run <path> for a focused test file or directory when the changed boundary needs it; do not use pnpm test <path> because the root script appends the path to the wrong command. Prefer an already successful same-fingerprint focused check over rerunning it, and never replay cumulative historical verification. Represent reusable focused success as a verification receipt containing the exact command, environment, exit status, non-mutation basis, and identical before/after combined, component, and repository fingerprints. Include its absolute path and SHA-256 digest in verification.credited_receipts; packet preflight validates every credited receipt. The focused check earns no final-gate credit; the exact clean-reviewed fingerprint must still pass the complete repository-required verification stack. Set verification.eligible_concurrent_gates to none and list every deferred broad gate in verification.deferred_gates. Keep $pr-draft-summary deferred until clean review and final-gate evidence apply to the final fingerprint. Do not introduce a repository lock, host-wide mutex, sentinel file, or user-triggered finalize step.
Verify the combined and component fingerprints before accepting reviewer output. If reviewed runtime or contract-bearing content changed, discard the affected review evidence unless the change later qualifies for the narrow final-gate base-advance closure in step 20. If only repository_fingerprint changed, accept the review only for unambiguous non-semantic bookkeeping such as staging, unstaging, or committing identical task-owned content. Preserve clean credit for a semantic component only when its fingerprint, requirement rows, assertions about runtime behavior, dependency inputs, and risk tier are all unchanged, except for a narrowly recorded step 20 closure. Require two concurrent independent delta reviews of every other changed or dependency-invalidated component plus its relevant boundaries with unchanged components. Any ambiguity invalidates the affected clean credit. Do not invalidate unrelated components solely because a neighboring file or coarse directory changed.
Apply a packet-and-output acceptance gate before counting findings or clean credit. Verify that every mandatory reviewer-brief field was populated or explicitly marked none or not applicable; missing packet evidence cannot be reconstructed by the reviewer and earns no clean credit. Require one structured JSON object with the documented schema: verdict, exact combined, component, and repository fingerprints, checked and unchecked inventory IDs, high-risk dimensions, focused probes, remaining uncertainty, findings, sibling-scenario scan, inspection call count, and inspection-budget reason when applicable. Every probe record must contain the exact executable command that ran, or the complete tool name and arguments for a non-shell probe. Reject prose-only labels, omitted arguments, and placeholders such as <focused probe> as incomplete evidence. Run PYTHONDONTWRITEBYTECODE=1 python3 .agents/skills/implementation-final-review/scripts/review_protocol.py reviewer-output --packet <packet.json> --reviewer <reviewer-id> --output <output.json> --task-id <task-id> --ledger <ledger.json> --prior-ledger <prior-ledger.json> --prior-ledger-sha256 <sha256> for each output after round 1 and accept no finding or clean credit when it fails. The validator rejects fingerprint drift, missing assignment coverage, malformed probes, unknown bare root IDs, root evidence IDs absent from the packet's indexed evidence or inventory, sibling scans that use a renamed root or unknown inventory, JSON booleans in integer fields, changed prior evidence or inventory bindings, reopening a closed canonical root without content-new evidence or semantic inventory, and distinct new roots that reuse one evidence digest. When a reviewer discovers new evidence after dispatch, add and digest it in the frozen packet and rerun packet preflight in the same fingerprint round before requesting corrected output. A bare clean, generic checklist, malformed object, or response that does not account for the assigned contract/state/data-flow artifacts is incomplete and earns no clean credit; request only the missing fields or coverage on the same frozen fingerprint rather than restarting the whole review. When two specialists are used, combine their declared ID coverage and reject the round if any assigned inventory row or selected high-risk dimension remains unreviewed. Use approximately 12 source-inspection tool calls per reviewer as a soft budget. A reviewer may exceed it when unresolved decision-relevant uncertainty requires more evidence, but must state the reason; never trade correctness for the budget.
Classify and validate all findings from the round before editing, then fix every actionable finding as one batch. Before choosing the fix, update the complete relevant inventory or matrix with the discovered transition or surface and solve the root cause across all populated rows; do not patch only the reported interleaving. The implementer owns $implementation-strategy and supplies its current scope contract in the packet. Reviewers inherit that contract and must not rerun the strategy workflow. Rerun it only in the implementer context when a fix changes supported behavior, compatibility, state, ownership, protocol paths, test permutations, or triggers a complexity reset; otherwise record scope contract unchanged and avoid reconstructing the same strategy. Add caller-visible regression coverage, not tests that only mirror helper structure. Run focused verification only for affected boundaries and dependency-invalidated checks.
Treat a second related finding in one root-cause group as a closure gate. Stop local patching, run the complexity reset once, scan the complete inventory for sibling scenarios, and record one root-level disposition: replace the design, narrow or reject unsupported behavior, or escalate a concrete unresolved contract decision. After the disposition is implemented and reviewed, mark the canonical root-cause ID closed. Do not reopen it for another local patch without content-new contract evidence or semantic inventory; reject aliases, renamed or copied content, and bare unknown IDs instead of treating them as new roots. If it cannot be closed coherently, escalate instead of consuming more rounds.
Increment the fingerprint round, repeat the full commit-hook parity gate from step 1, and review the complete post-fix diff with fresh context. Continue review -> validate all findings -> batch fixes -> focused verification -> hook parity -> review without waiting for another user prompt.
Apply the non-convergence guard before another local fix:
If the same root-cause group produces another P0/P1 after a complexity reset, return to the merge base and replace task-owned branch-local machinery with the narrowest coherent implementation.
If runtime diff size, state fields, ownership modes, or test permutations grow materially for two consecutive rounds, do not call that convergence merely because each finding is local. Re-run the baseline-reset gate.
If the same root-cause group produces actionable findings in three finding-bearing rounds, or the narrower reimplementation still produces the same root-cause P0/P1, escalate early rather than consuming the round budget.
If four rounds complete without a shrinking or stable diff and falling finding severity, escalate early.
Stop successfully only after the required clean-review condition is met on the exact reviewed content and every required reviewer output has passed the acceptance gate:
same-round infrastructure replacement: the original two-reviewer dispatch was concurrent, and the accepted pair consists of the unchanged protocol-valid peer output plus one independent replacement output accepted under step 12;
normal-risk change: two independent clean reviews of the same fingerprint, launched concurrently;
elevated-risk change or any loop that produced a P0/P1 finding: two independent clean reviews of the same fingerprint with complementary high-risk specialties, launched concurrently.
component-only post-review edit: clean credit for every unchanged component plus two concurrent clean independent delta reviews covering all changed components and their runtime boundary.
verified final-gate base-advance closure satisfying every condition in step 20: preserve the prior clean set without a new fingerprint round or reviewer dispatch, then run the complete final verification stack on the resulting fingerprint.
After the clean-review condition is met, confirm that the diff and component fingerprints remain stable, then check observable host capacity before starting final repository verification. Use available read-only task or process evidence; treat another repository-wide test, typecheck, build, examples runner, or integration command already active on the same host as concrete contention. When contention is visible, continue useful non-heavy work or an event-driven wait and check again later. Do not create or wait on a repository lock, host-wide mutex, or sentinel file, and do not require a user-triggered finalize message. If host telemetry is unavailable, do not block solely because capacity cannot be measured. Once capacity is available, complete $changeset-validation when package or changeset files changed and $code-change-verification for every eligible runtime, test, example, or build/test change in the repository-required order against the exact clean-reviewed fingerprint, or against the recorded resulting fingerprint of the verified base-advance closure below. Record combined, component, and repository fingerprints immediately before and after the final stack. Accept final verification only when every command succeeds, execution does not mutate reviewed content or create an ambiguous repository-state change, and all fingerprints still match. Classify any final-gate replay or edit before invalidating review evidence:
Verified base-advance closure: when the intended target advances after clean review, preserve the existing clean set without a new fingerprint round or reviewer dispatch only when every condition below holds. This exception grants no final-verification credit; rerun every mandatory final gate on the replayed fingerprint and regenerate the complete PR handoff.
The replay or rebase is conflict-free and requires no manual task-content edit. The old and new review_state.py artifacts have byte-identical task and component workspace arrays, and their tracked_diff_sha256 values are identical; compare these fields directly because content fingerprints intentionally include the resolved base.
Before the original review, each component recorded exact semantic dependency-input pathspecs and reasons. The complete upstream delta from old base to new base changes no task-manifest path, dependency-input path, selected architecture reference, generated-surface owner, or applicable build, test, lint, format, hook, lockfile, or package configuration input.
The original requirement, scope contract, inventory rows, assertions about runtime behavior, selected review dimensions, risk tier, and released compatibility boundary are unchanged. Focused checks affected by integration with the new base pass.
Record the old and new base, head, combined/component/repository fingerprints, exact upstream changed-path list and diff digest, dependency-input pathspecs, comparison commands, and results in the task-global ledger. This closure consumes no fingerprint round and creates no reviewer packet.
Any path overlap, changed configuration or dependency input, conflict, manual resolution, changed diff digest, missing prior dependency map, or uncertainty falls through to a fresh review round on the new base. A coarse directory-disjointness claim is insufficient.
Runtime, public API, behavior-impacting docs, runtime-behavior assertions, or scope-contract change: invalidate the applicable clean set, rerun pre-review validation, and restart review with fresh reviewers before rerunning every required final gate.
Tests or examples only: preserve clean runtime evidence only when the runtime fingerprint is identical and the delta does not change required behavior, compatibility, runtime-behavior assertions, or the scope contract. Run focused verification and a component delta review using the risk tier and clean-review conditions from step 19, covering test correctness, accidental contract expansion, and the runtime boundary, then rerun the required repository gates. Treat an example or expectation edit as behavior-impacting unless concrete evidence shows otherwise.
Release metadata only: preserve runtime and test evidence when their fingerprints are identical. Revalidate the metadata and independently review any changed behavioral claim, then rerun applicable final gates.
Operational artifact only: exclude it from deliverable manifests and do not invalidate review evidence. Completion requires the final combined fingerprint to be exactly composed of component fingerprints with applicable clean, delta-review, or verified base-advance-closure evidence and every mandatory repository gate to pass on that final content. Invoke $pr-draft-summary last, only after review and verification evidence apply to the final fingerprint.
Stop the autonomous loop when the active cycle reaches its current budget: six fingerprint rounds for the initial implementation cycle or two for a post-completion feedback cycle. This is an absolute cap for the active cycle, not a target, and it does not reset when execution pauses or context changes. Do not call the implementation complete. Summarize the remaining blockers, recurring root causes, complexity growth, attempted fixes and resets, current verification state, and the concrete decisions available to the user; then ask the user whether to narrow scope, split the change, accept a stated risk, redesign, or explicitly authorize another bounded budget. When concrete actionable feedback arrives after a successfully completed and sealed cycle, append the feedback cycle's default two-round budget to the same ledger without another authorization prompt. In every other case, append a user-authorized budget to the same ledger rather than replacing its history.
PYTHONDONTWRITEBYTECODE=1
__pycache__
Require the structured JSON output from the reviewer brief. clean alone is never sufficient: the reviewer must return the exact packet SHA-256 and fingerprints, checked and unchecked inventory IDs, high-risk dimensions checked, probes or none, unresolved uncertainty or none, findings, sibling-scenario scan, and inspection-budget accounting.
After fixes, review the exact final diff again. Preserve earlier clean credit only under the explicit component-delta rule; do not infer that a change is isolated merely from its file location.
