> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bugspray.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Read PR validation with confidence

> Separate proposed coverage, deterministic replay and actual CI evidence.

A PR report combines several kinds of evidence. Read each against its exact candidate and environment; a green result in one section does not fill a gap in another.

| Evidence | What it answers | What it does not establish |
| - | - | - |
| Candidate inventory | Which suites were declared at this commit? | Tests exist, ran or passed |
| Suite plan | Which registered suites were proposed, and why? | Execution approval or safe skipping |
| Finding replay | Does a known repro recur against this candidate? | All expected workflows pass |
| Advisory exploration | What else did a browser agent observe? | Deterministic suite success |
| CI receipt | What did an authenticated run report for an exact request? | Current validity after candidate/environment changes |

## Follow a change to saved views

**1. Establish the exact candidate**

Import the candidate's committed manifest through authenticated discovery. Retain head/base commits, inventory digest and the exact saved workflow definitions. A stale head, missing manifest or unresolved catalog reference is a visible gap.

**2. Prepare and inspect a plan**

An authorized sampling-capable MCP host can call `plan_pr_suites` with repository, PR number and full candidate SHA. Trusted deployment policy defines smoke, dependencies and fallback. PR text and model output are evidence/proposals, never policy or executable commands.

`plan_and_save_pr_suites` explicitly asks the server to recollect current inputs and persist a matching immutable plan. Saving does not authorize CI. Missing sampling or rejected output retains conservative fallback. Required smoke and dependency selections cannot be removed by the model.

**3. Establish independent execution authority**

The CI bridge requires a trusted adapter, current plan/input/catalog identity, a verified environment and independent authorization. A generic new installation has no default CI adapter. Do not copy a pilot's identity or approval to bypass this boundary.

**4. Read the result and its limits**

Open the relevant PR run (`/pr-runs/:id`). Review selection reasons, smoke/fallback, catalog gaps, exact definitions, immutable identities, CI attempts and artifact links. Compare current projected validity with historical runner-reported status. Missing evidence is not a pass.

## What is supported today?

The merged code provides candidate discovery, bounded planning, immutable plan storage, CI delivery/receipt contracts and a consolidated suite report. A fixed, narrowly scoped Records pilot adapter supports independently approved dispatch and authenticated artifact collection. Three pilot tests have passed unattended on a real verified preview with normal authentication, a real API, isolated records and cleanup.

That result proves those tests under those conditions. Generic automatic **label → plan → CI → report** operation is not established. Signed broker webhook ingress is implemented with a bounded installation-to-tenant service-binding route; operators must still configure and verify actual delivery. Provider App setup and successful manual CI do not prove that unattended webhook orchestration works.

Plans retain `executionEvidence: not_run`, `canSkip: false` and `canAutoMerge: false`. The pilot runs its entire three-suite inventory while observing the selected proposal. A label or authorized comment can trigger the existing configured replay/advisory gate; it is not a general suite-dispatch switch.

## Recognize stale and unavailable results

A changed head/base, manifest, catalog definition or trusted policy can supersede a plan. A same-SHA deployment rebuild can change environment identity. Expired authorization, missing artifacts, ambiguous delivery, provider failure or changed runner state can block current evidence while preserving historical receipts.

The report keeps request attempt separate from GitHub run attempt. V1 receipts do not carry provider cancellation outcomes; a missing receipt is not inferred cancellation. Detailed CI logs and older attempts remain in CI. A report API failure should leave existing replay/advisory sections usable and mark suite evidence unavailable.

## Integrate beyond the pilot

Treat a new CI adapter as developer work: independently bind trusted runner commands, scope, approvals, exact candidate/environment and authenticated bounded receipts. Run the full established suite inventory during observation, compare proposed selections on the same candidate and evaluate missed regressions before considering any future selection policy.

Use the source contracts for [planning](https://github.com/SynclyUS/bugspray/blob/main/docs/suite-planning.md), [plan/CI bridge](https://github.com/SynclyUS/bugspray/blob/main/docs/suite-plan-ci-bridge.md), [delivery](https://github.com/SynclyUS/bugspray/blob/main/docs/suite-ci-delivery.md) and [reporting](https://github.com/SynclyUS/bugspray/blob/main/docs/pr-suite-reporting.md). Some older increment notes describe their pre-integration state; current executable code and the connected bridge take precedence. No test skipping, auto-merge or general runner deployment is authorized by these docs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.