From 60669951b7808e4eef74695e86d0550879204c53 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Wed, 2 Sep 2026 10:37:58 -0700 Subject: [PATCH] refactor(review): improve specialist causal analysis Signed-off-by: Carlos Villela --- .../pr-review-advisor-local.test.ts | 17 +++++++++- .../pr-review-advisor-specialists.test.ts | 2 +- tools/pr-review-advisor/README.md | 2 +- tools/pr-review-advisor/investigate-turn.mts | 4 ++- .../local-review-implementation.mts | 17 +++++++--- .../specialists/architecture-standard-work.md | 27 +++++++--------- .../specialists/delivery-flow.md | 28 +++++++--------- .../documentation-standard-work.md | 28 +++++++--------- .../specialists/migration-completion.md | 32 +++++++++++++++++++ .../specialists/reduction-simplification.md | 32 +++++++++++++++++++ .../verification-mistake-proofing.md | 28 ++++------------ 11 files changed, 137 insertions(+), 80 deletions(-) create mode 100644 tools/pr-review-advisor/specialists/migration-completion.md create mode 100644 tools/pr-review-advisor/specialists/reduction-simplification.md diff --git a/test/automation/pull-requests/pr-review-advisor-local.test.ts b/test/automation/pull-requests/pr-review-advisor-local.test.ts index 120b6bb8dbc..11b1ff97b1c 100644 --- a/test/automation/pull-requests/pr-review-advisor-local.test.ts +++ b/test/automation/pull-requests/pr-review-advisor-local.test.ts @@ -127,6 +127,8 @@ function repository(): string { "ignored.txt\nartifacts/pr-review-advisor-local/\n", ); fs.writeFileSync(path.join(directory, "committed.txt"), "base\n"); + fs.symlinkSync("committed.txt", path.join(directory, "tracked-internal-link")); + fs.symlinkSync("/etc/passwd", path.join(directory, "tracked-retargeted-link")); fs.writeFileSync(path.join(directory, "staged.txt"), "base\n"); fs.writeFileSync(path.join(directory, "unstaged.txt"), "base\n"); fs.mkdirSync(path.join(directory, "tools", "pr-review-advisor"), { recursive: true }); @@ -144,6 +146,8 @@ function repository(): string { fs.writeFileSync(path.join(directory, "staged.txt"), "staged\n"); git(directory, ["add", "staged.txt"]); fs.writeFileSync(path.join(directory, "unstaged.txt"), "unstaged\n"); + fs.rmSync(path.join(directory, "tracked-retargeted-link")); + fs.symlinkSync("committed.txt", path.join(directory, "tracked-retargeted-link")); fs.writeFileSync(path.join(directory, "untracked.txt"), "untracked\n"); fs.symlinkSync("/etc/passwd", path.join(directory, "untracked-link")); fs.writeFileSync(path.join(directory, "ignored.txt"), "ignored\n"); @@ -406,12 +410,23 @@ describe("local PR review advisor", () => { expect( git(snapshot, ["diff", "--name-only", refs.baseRef + ".." + refs.headRef]).split("\n"), - ).toEqual(["committed.txt", "staged.txt", "unstaged.txt", "untracked-link", "untracked.txt"]); + ).toEqual([ + "committed.txt", + "staged.txt", + "tracked-retargeted-link", + "unstaged.txt", + "untracked-link", + "untracked.txt", + ]); expect(fs.readFileSync(path.join(snapshot, "committed.txt"), "utf8")).toBe("branch\n"); expect(fs.readFileSync(path.join(snapshot, "staged.txt"), "utf8")).toBe("staged\n"); expect(fs.readFileSync(path.join(snapshot, "unstaged.txt"), "utf8")).toBe("unstaged\n"); expect(fs.readFileSync(path.join(snapshot, "untracked.txt"), "utf8")).toBe("untracked\n"); expect(fs.existsSync(path.join(snapshot, "ignored.txt"))).toBe(false); + expect(fs.readlinkSync(path.join(snapshot, "tracked-internal-link"))).toBe("committed.txt"); + expect(fs.readlinkSync(path.join(snapshot, "tracked-retargeted-link"))).toBe("committed.txt"); + expect(git(snapshot, ["ls-tree", refs.headRef, "tracked-internal-link"])).toContain("120000 blob"); + expect(git(snapshot, ["ls-tree", refs.headRef, "tracked-retargeted-link"])).toContain("120000 blob"); expect(git(snapshot, ["ls-tree", refs.headRef, "untracked-link"])).toContain("120000 blob"); expect(fs.existsSync(path.join(snapshot, "untracked-link"))).toBe(false); expect(git(source, ["status", "--porcelain=v1", "-uall"])).toBe(before); diff --git a/test/automation/pull-requests/pr-review-advisor-specialists.test.ts b/test/automation/pull-requests/pr-review-advisor-specialists.test.ts index 80eee966692..d7bcdbbcbad 100644 --- a/test/automation/pull-requests/pr-review-advisor-specialists.test.ts +++ b/test/automation/pull-requests/pr-review-advisor-specialists.test.ts @@ -243,7 +243,7 @@ describe("PR review advisor specialist prompts", () => { const expected = fs.readFileSync(artifact, "utf8"); expect(path.basename(artifact)).toBe("pr-review-architecture-standard-work-summary.md"); - expect(expected).toContain("PR Review Advisor — Architecture and standard work specialist"); + expect(expected).toContain("PR Review Advisor — Architecture ownership specialist"); expect(expected).toContain("Complete specialist review for maintainers and review agents."); expect(expected).toContain("Concrete reduction."); }); diff --git a/tools/pr-review-advisor/README.md b/tools/pr-review-advisor/README.md index db066b7729b..1d4cd922cd3 100644 --- a/tools/pr-review-advisor/README.md +++ b/tools/pr-review-advisor/README.md @@ -8,7 +8,7 @@ model-backed analysis in OpenShell sandboxes from trusted GitHub Actions jobs an read-only data. It posts a sticky comment that links to the complete specialist reviews in the workflow run. -For each configured pull-request event, it runs every specialist prompt in `tools/pr-review-advisor/specialists`. Each prompt owns a distinct review concern and defines its purpose, method, scope, exclusions, review principles, and finding threshold. +For each configured pull-request event, it runs every specialist prompt in `tools/pr-review-advisor/specialists`. Each prompt owns a distinct review concern and defines its purpose, investigation method, evidence expectations, and finding threshold. Specialists inspect their assigned concern and recommend the smallest direct correction. They run independently and publish separate reports. The advisor does not select, aggregate, or summarize their findings. diff --git a/tools/pr-review-advisor/investigate-turn.mts b/tools/pr-review-advisor/investigate-turn.mts index 26f273cdc50..a171443bd05 100644 --- a/tools/pr-review-advisor/investigate-turn.mts +++ b/tools/pr-review-advisor/investigate-turn.mts @@ -103,6 +103,8 @@ Treat code growth as suspect and compare it with direct modification, reuse, con Assess checked-in regression evidence and choose only supported E2E selectors. Never claim a job ran or turn E2E guidance into a finding without a checked-in defect. -Return a concise specialist review with evidence-backed issues, exact citations, remedies, verification hints, positives, and limitations.`, +Before forming findings, enumerate the complete changed-file set and inspect the relevant changed hunks. For each candidate finding, compare the relevant parent state with the proposed state. Establish whether a changed line, changed omission, newly affected consumer, or changed contract introduces, worsens, exposes, expands, or materially relies on the problem. Repository-wide evidence can establish a call path or consequence, but its mere presence does not make an inherited condition attributable to this pull request. Verify production references through direct calls, qualified calls, imports, re-exports, wrappers, dependency injection, and selected immutable revisions where applicable. Distinguish a demonstrated behavior defect from missing evidence and from material uncertainty. + +Return a specialist review with evidence-backed issues, exact citations, remedies, verification hints, positives, and limitations.`, }; } diff --git a/tools/pr-review-advisor/local-review-implementation.mts b/tools/pr-review-advisor/local-review-implementation.mts index 78a5e9478f0..44137d5ce00 100755 --- a/tools/pr-review-advisor/local-review-implementation.mts +++ b/tools/pr-review-advisor/local-review-implementation.mts @@ -139,9 +139,17 @@ function git(cwd: string, args: readonly string[], input?: string): string { ); } const gitValue = (cwd: string, args: readonly string[]): string => git(cwd, args).trim(); -function removeSnapshotSymlinks(directory: string): void { - for (const entry of fs.readdirSync(directory, { recursive: true, withFileTypes: true })) - if (entry.isSymbolicLink()) fs.rmSync(path.join(entry.parentPath, entry.name), { force: true }); +function removeSnapshotSymlinksResolvingOutside(directory: string): void { + const root = fs.realpathSync(directory); + for (const entry of fs.readdirSync(directory, { recursive: true, withFileTypes: true })) { + if (!entry.isSymbolicLink()) continue; + const link = path.join(entry.parentPath, entry.name); + const target = path.resolve(entry.parentPath, fs.readlinkSync(link)); + const relative = path.relative(root, target); + const resolvesOutside = + relative === ".." || relative.startsWith(".." + path.sep) || path.isAbsolute(relative); + if (resolvesOutside) fs.rmSync(link, { force: true }); + } } export function createLocalReviewSnapshot( source: string, @@ -152,7 +160,6 @@ export function createLocalReviewSnapshot( const initialHead = gitValue(destination, ["rev-parse", "HEAD"]); git(destination, ["read-tree", initialHead]); git(destination, [...disabledFilters(source), "checkout-index", "--all", "--force"]); - removeSnapshotSymlinks(destination); const patch = git(source, ["diff", "--binary", "--no-ext-diff", "--no-textconv", "HEAD"]); if (patch) { git(destination, ["apply", "--cached", "--binary", "-"], patch); @@ -177,7 +184,7 @@ export function createLocalReviewSnapshot( "Local review snapshot", ]); git(destination, ["update-ref", "--no-deref", "HEAD", commit]); - removeSnapshotSymlinks(destination); + removeSnapshotSymlinksResolvingOutside(destination); git(destination, ["cat-file", "-e", baseRef + "^{commit}"]); return { baseRef, headRef: commit }; } diff --git a/tools/pr-review-advisor/specialists/architecture-standard-work.md b/tools/pr-review-advisor/specialists/architecture-standard-work.md index 37825d8fb01..05b30d6701d 100644 --- a/tools/pr-review-advisor/specialists/architecture-standard-work.md +++ b/tools/pr-review-advisor/specialists/architecture-standard-work.md @@ -3,33 +3,30 @@ SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All SPDX-License-Identifier: Apache-2.0 --> -# Architecture and standard work +# Architecture ownership ## Purpose -Determine whether one proportionate design owns the result through the simplest established path. +Determine whether the pull request leaves each responsibility, state transition, policy decision, and source of truth with one clear, proportionate owner in the resulting system. ## Review method -Inspect the complete source-and-test result. Compare each new owner, concept, state, branch, dependency, and compatibility path with direct change, reuse, consolidation, replacement, and deletion. +Investigate the complete change and its surrounding callers, callees, tests, configuration, workflows, and documentation. For every ownership concern, compare the parent revision with the proposed result before judging it. Establish what owned the behavior and state before the pull request, what the pull request changes, and whether the resulting ownership defect is introduced, worsened, or materially preserved by this change. A pre-existing condition is relevant when the pull request expands it, relies on it in a new way, or changes the same responsibility without resolving the ownership conflict. -## Own - -- Responsibility, state ownership, dependency direction, and one source of truth. -- Direct extension and use of repository, runtime, platform, or dependency capabilities. -- Unnecessary abstractions, wrappers, registries, parsers, caches, and integration code. -- Total structure across source, tests, fixtures, workflows, configuration, and documentation. -- Migration and replacement completion. -- Obsolete callers, tests, documents, and compatibility paths. +Trace behavior end to end. Follow reads, writes, derivations, synchronization, validation, error handling, and lifecycle boundaries. Check whether names and layers correspond to real responsibility boundaries, and whether dependency direction keeps policy with the component that has the necessary knowledge and authority. -## Do not own +## Own -Do not report a wrong product result, a security defect, test-oracle quality, operational recovery, or writing style unless duplicated ownership is the present defect. +- Responsibility boundaries and accountable owners. +- State ownership, mutation authority, derivation, synchronization, and sources of truth. +- Dependency direction and placement of policy decisions. +- Competing implementations or coordination paths that can disagree about the same result. +- New architecture that makes an existing ownership defect consequential to the pull request. ## Review principles -Remove overprocessing, duplicate ownership, unnecessary handoffs, and speculative machinery. Do not move complexity to another file or surface. +Prefer one authoritative path for each decision and state transition. Distinguish intentional layering from split authority. Judge the resulting system, not merely the size or novelty of the diff. Preserve required behavior, diagnostics, evidence, and trust boundaries when recommending a change. ## Report a finding when -The change creates or retains duplicate authority, an unnecessary owner or concept, a wrong dependency direction, an incomplete replacement, or custom machinery that an established capability can replace. Name the current cost and one coherent reduction. Preserve behavior, diagnostics, evidence, and trust boundaries. +The pull request introduces, worsens, or materially relies on unclear or duplicate authority, conflicting sources of truth, misplaced policy, an invalid dependency direction, or a responsibility boundary that permits components to disagree. Cite the changed lines that make the issue attributable to the pull request and the parent-state evidence needed to show the comparison. Explain the concrete failure mode or maintenance cost, identify the intended owner, and give a coherent remedy with a verification approach. diff --git a/tools/pr-review-advisor/specialists/delivery-flow.md b/tools/pr-review-advisor/specialists/delivery-flow.md index ba3d161ce1e..ccbe9d972e6 100644 --- a/tools/pr-review-advisor/specialists/delivery-flow.md +++ b/tools/pr-review-advisor/specialists/delivery-flow.md @@ -3,32 +3,26 @@ SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All SPDX-License-Identifier: Apache-2.0 --> -# Delivery flow +# Delivery and workflow causality ## Purpose -Determine whether the change moves evidence from commit to maintainer decision without avoidable delay or rework. +Determine how this pull request changes the path from a repository event or source change to trustworthy evidence and a maintainer decision. ## Review method -Follow changed CI, build, test, artifact, publication, and release work as a value stream. Identify each queue, dependency, batch, handoff, repeated operation, cancellation boundary, and feedback point. +Establish the parent-state workflow from parent versions of changed files and connected reusable workflows, actions, scripts, selectors, artifacts, and tests. Reconstruct the proposed state and compare the execution graphs. -## Own - -- CI and workflow dependencies, fan-out, concurrency, and cancellation. -- Duplicate builds, tests, downloads, and artifact production. -- Artifact handoffs, cache use, and publication flow. -- Failure localization, retained diagnostics, and feedback latency. -- Superseded work, unnecessary batching, waiting, transport, and work in progress. - -## Do not own +Trace each material change from trigger and changed-file classification through conditions, dependencies, fan-out, concurrency, cancellation, work, artifact transport, evidence retention, publication, and the consuming decision. Resolve what each expression, output, artifact, immutable action revision, or status actually controls. Classify behavior as introduced, worsened, removed, exposed, or unchanged. -Do not report deployment recovery, product runtime performance, security boundaries, generic workflow style, or hypothetical scale concerns. Do not report external CI status. - -## Review principles +## Own -Map the value stream. Remove waiting, batching, transport, repeated work, and excess work in progress. Prefer early deterministic feedback and direct evidence flow. +- Trigger, path-selection, matrix, conditional, dependency, fan-out, concurrency, cancellation, and supersession behavior. +- Relationships between production changes, selected verification, generated plans, and required evidence. +- Duplicate or displaced builds, tests, installation, downloads, packaging, uploads, and reconstruction. +- Artifact identity, provenance handoffs, availability, retention, and consumption. +- Failure localization, diagnostic preservation, feedback ordering, queues, waiting, and handoffs. ## Report a finding when -Checked-in workflow or tooling causes a present avoidable delay, repeated operation, unnecessary handoff, broad fan-out, stale work, or late failure signal. Name the affected evidence path, current waste, measurable or structurally certain effect, and smallest flow-preserving change. +A changed workflow, selector, action, script, configuration, or delivery contract causally introduces or worsens delay, repeated or stale work, an unnecessary handoff, incorrect dependency, missing or late evidence, loss of diagnostics, overly broad fan-out, or an artifact path that no longer reaches its decision. Cite the changed control point, parent behavior, proposed behavior, downstream effect, and flow-preserving correction. diff --git a/tools/pr-review-advisor/specialists/documentation-standard-work.md b/tools/pr-review-advisor/specialists/documentation-standard-work.md index ac7eb17872c..d61d01d096a 100644 --- a/tools/pr-review-advisor/specialists/documentation-standard-work.md +++ b/tools/pr-review-advisor/specialists/documentation-standard-work.md @@ -3,31 +3,25 @@ SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All SPDX-License-Identifier: Apache-2.0 --> -# Documentation and standard work +# Documentation drift ## Purpose -Determine whether the intended reader can perform the correct action from the changed text. +Determine whether this change causes repository guidance and explanatory text to diverge from behavior, interfaces, ownership, or operating procedure. ## Review method -Apply the trusted writing guide to changed explanatory text. Compare commands, examples, prerequisites, limits, failure guidance, links, support claims, messages, and test titles with current repository evidence. Trace changed terminology when its meaning matters. +Establish parent state, then compare proposed state. Trace changed behavior, commands, interfaces, configuration, workflows, messages, examples, tests, and terminology into owning documentation, including explanatory text outside the documentation tree. -## Own +Determine whether the change introduces an inaccurate statement, leaves existing guidance newly stale, leaves readers routed to a former owner, edits a claim that depends on retained drift, or merely encounters a parent-state defect not made newly relevant. A changed line alone does not establish causality; an unchanged document can become stale. Verify claims against source, tests, configuration, schemas, workflow behavior, and owning guidance. -- Reader procedures and standard work. -- Commands, examples, prerequisites, limits, and recovery instructions. -- Support claims, links, user-visible messages, and meaningful test titles. -- Writing-only findings and terminology consistency. +## Review scope -## Do not own +- Procedures, prerequisites, commands, examples, limits, expected results, failure handling, and recovery. +- Support, compatibility, security, lifecycle, release, and validation claims. +- Navigation, links, renamed concepts, sources of truth, and duplicated procedure ownership. +- Messages, prescriptive comments, configuration and schema descriptions, and meaningful test titles. -Do not report an implementation defect. Cite it only as evidence that the text directs the reader incorrectly. Do not turn missing evidence or personal style preference into a behavior claim. +## Findings -## Review principles - -Make normal and abnormal actions visible. Remove interpretation, repeated procedure ownership, unnecessary motion, and text that delays the reader's task. - -## Report a finding when - -Changed text can cause a wrong action, omit a required condition, conflict with the owning procedure, misstate support, hide the affected object or next action, or use a term with conflicting operational meaning. Group locations with one cause. Propose a shorter accurate rewrite. Treat writing-only defects as suggestions unless they change behavior, security, data safety, support, test meaning, release meaning, or required evidence. +For each documentation-drift issue caused, exposed, or materially worsened by the change, cite the changed behavior or ownership transition, parent comparison, affected reader-facing text or missing owning update, incorrect action or interpretation, and accurate remedy. Treat wording and terminology according to operational effect. diff --git a/tools/pr-review-advisor/specialists/migration-completion.md b/tools/pr-review-advisor/specialists/migration-completion.md new file mode 100644 index 00000000000..d99e271a942 --- /dev/null +++ b/tools/pr-review-advisor/specialists/migration-completion.md @@ -0,0 +1,32 @@ + + +# Migration completion + +## Purpose + +Determine whether the pull request completes each migration or replacement it undertakes and leaves one coherent supported path. + +## Review method + +Compare the parent revision with the proposed result. Identify each changed replacement, extraction, rename, version, state format, compatibility transition, or path relocation. Trace the pre-change and proposed owners, actual production callers and consumers, stored state, configuration, tests, fixtures, workflows, documentation, and compatibility commitments. + +Resolve what consumers execute rather than inferring activation from local source presence. For workflow actions and dependencies, inspect the exact immutable revision selected by each consumer. Trace upgrade, downgrade, restart, retry, partial-state, and mixed-version behavior where supported or reachable. Establish whether old paths remain authoritative and whether the pull request causes or newly depends on that coexistence. + +## Own + +- Completion of replacements and caller cutovers. +- Old and new state formats, conversion, reconciliation, and cleanup. +- Compatibility paths and their explicit lifecycle. +- Obsolete implementations, adapters, flags, configuration, tests, fixtures, workflows, and documentation. +- Split behavior caused by partial migration across repository surfaces. + +## Review principles + +A migration may be intentionally staged when the stages, compatibility contract, owner, and completion condition are established. Otherwise require one coherent authority model. Preserve required compatibility, diagnostics, rollback or recovery behavior, evidence, and trust boundaries. + +## Report a finding when + +The pull request introduces, worsens, or materially depends on an incomplete cutover, leaves reachable old and new paths that can diverge, strands callers or state, removes compatibility before its contract permits, retains obsolete authority without a defined lifecycle, or fails in a supported intermediate state. Cite changed lines and parent-state evidence. Explain the reachable consequence, remaining work, and verification of completion. diff --git a/tools/pr-review-advisor/specialists/reduction-simplification.md b/tools/pr-review-advisor/specialists/reduction-simplification.md new file mode 100644 index 00000000000..cf962ca3ba1 --- /dev/null +++ b/tools/pr-review-advisor/specialists/reduction-simplification.md @@ -0,0 +1,32 @@ + + +# Reduction and simplification + +## Purpose + +Determine whether the pull request achieves its required result through the smallest coherent total mechanism that fits established capabilities. + +## Review method + +Start with added and modified code and compare it with the parent. Inventory newly added or expanded predicates, filtered collections, sibling constants, registries, loops, emission blocks, wrappers, parsers, caches, adapters, handoffs, compatibility branches, configuration concepts, and test matrices. Compare sibling blocks for shared inputs, repeated membership tests, overlapping outputs, repeated normalization, and branches differing only by constant sets. + +Compare the full result with direct modification, reuse, consolidation, replacement, and deletion. Trace the whole path so a recommendation reduces total ownership rather than moving complexity elsewhere. Attribute a concern when the pull request adds unnecessary structure, expands or entrenches machinery, duplicates an established capability, or changes an area while leaving a directly removable step or concept in that changed path. + +## Own + +- Unnecessary mechanisms, concepts, layers, indirection, and handoffs. +- Duplicate classification, parsing, validation, transformation, state, configuration, emission, or integration paths. +- Custom implementations replaceable by a suitable established capability. +- Speculative generality and compatibility machinery without a current contract. +- Supporting tests, fixtures, workflows, configuration, and documentation that exist only for avoidable machinery. + +## Review principles + +Code growth is a signal to investigate, not a defect. A reduction is valid only when it preserves required behavior, ordering, clarity, diagnostics, regression evidence, safety, lifecycle guarantees, and trust boundaries. Prefer a concrete simpler end-to-end design over aesthetic objections. + +## Report a finding when + +The pull request introduces, worsens, expands, or entrenches avoidable machinery with a present cost, and a concrete alternative reduces the total mechanism. Cite changed lines and parent-state evidence. Describe the simpler design, what can be removed or consolidated, and how to verify equivalent behavior. diff --git a/tools/pr-review-advisor/specialists/verification-mistake-proofing.md b/tools/pr-review-advisor/specialists/verification-mistake-proofing.md index 58691844221..93ce5282ee1 100644 --- a/tools/pr-review-advisor/specialists/verification-mistake-proofing.md +++ b/tools/pr-review-advisor/specialists/verification-mistake-proofing.md @@ -3,34 +3,18 @@ SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All SPDX-License-Identifier: Apache-2.0 --> -# Verification and mistake-proofing +# Verification evidence ## Purpose -Determine whether checked-in evidence detects a plausible defect at the correct boundary. +Determine whether checked-in evidence independently proves changed behavior and detects plausible regressions at the correct boundary. ## Review method -For each changed invariant or test, identify the claimed behavior, trigger, action, observable result, independent oracle, and one plausible defect. Confirm that the evidence fails for that defect. +For every changed behavior, invariant, risk-plan obligation, selector, test, fixture, helper, workflow assertion, or claimed proof, identify trigger, action, observable result, oracle, side effects, and a plausible defect. Trace evidence to the production or automation path and determine whether that defect makes it fail. -## Own +Compare parent and proposed states. Distinguish newly added or weakened evidence from inherited gaps. Establish the changed decision or claim that creates the gap, broadens behavior without proof, weakens proof, or makes inherited evidence insufficient. Build a handoff evidence matrix for every changed capability, artifact, selector, SDK connection, and authority transfer: producer proof; forged or invalid rejection proof; direct valid consumer proof; side-effect oracle; never-settling or failure proof; and selection-to-execution proof. For each empty cell, determine whether the changed contract makes it a material regression gap. For each test claimed to fill a cell, cite the exact caller invocation, callee observation, and independent result assertion. For each changed handoff, separately inventory producer proof, rejection proof, and direct positive consumer proof. Do not treat proof that a capability or artifact is created, or that forged input is rejected, as proof that the real caller passes the valid value through the actual callee and produces the intended side effect. Investigate independent oracles, positive and negative boundaries, malformed input, stale state, partial failure, concurrency, idempotence, real caller/callee paths, mocks, selection-to-execution, package and installer boundaries, and the nearest stable test layer. -- Independent oracles and assertions on contract results and side effects. -- Positive, negative, absence, and non-mutation evidence. -- Stable public or component boundaries. -- The zero-budget source-shape test policy and base-branch exceptions. -- Readable tests, fixtures, helpers, hooks, and matrices. -- Duplicate, speculative, and obsolete coverage. -- Risk-plan invariants, test-layer choice, and E2E coverage guidance. +## Findings -## Do not own - -Do not report the production defect when the test correctly exposes it. Do not request tests for hypothetical behavior or report external test execution status. - -## Review principles - -Detect defects at the nearest stable boundary and provide fast feedback. Prefer the smallest proof that prevents escape. Remove repeated inspection that adds no distinct evidence. - -## Report a finding when - -A test can pass without exercising its claim, uses a self-derived oracle, asserts a non-contract detail, misses a required negative result, inspects shipped source shape without an existing exception, or duplicates evidence without protecting another risk. Name the plausible missed defect or harmless change, the faulty evidence, and the smallest replacement proof. +For each verification defect, identify the changed behavior or claim, parent state, plausible escaping regression, why evidence passes or does not execute, exact citations, and smallest stronger proof. Distinguish a demonstrated product defect from missing positive proof, missing negative proof, a weak oracle, and material uncertainty. Treat a test that correctly exposes a production defect as evidence rather than as the defect.