# Test-plan contract

Create the plan before execution and save it as durable JSON plus a clickable HTML report.

Start from [plan-template.json](plan-template.json). Its strings are examples to replace, not executable defaults.

## Required plan fields

At the run level:

- run title, mode, target, environment, scope, exclusions, assumptions, source revision, created time;
- detected flows/items and confidence;
- available execution adapters and setup dependencies;
- credential source names only—never secret values;
- estimated tests, duration, concurrency, stop conditions, and residual uncertainty.
- selected `breadth`, `depth`, or `balanced` test strategy plus its evidence-based rationale;
- generated product-user perspectives with stable IDs, roles, goals, risk lenses,
  and provenance from actual product context;
- breadth/depth exploratory charters with missions and stop conditions.

For every test:

- stable ID and concise title;
- priority `P0`–`P3`;
- test type and selected flow/item;
- reason/risk and affected user/business promise;
- provenance: change, source file/line or symbol, runtime evidence, requirement, bug, or CARBON reference;
- prerequisites and synthetic data;
- canonical steps or executable instruction;
- expected oracle, the authority behind it, and evidence to capture;
- source-predicted outcome (`pass`, `fail`, or `unknown`) and prediction basis
  when pre-execution evidence supports a prediction;
- estimated duration, dependencies, safe parallel group, and execution adapter;
- destructive/costly/privacy/payment/notification/security flags;
- initial status `planned`.

The oracle and predicted outcome answer different questions. The oracle states
what the product should do. The prediction states what this build is likely to
do. If source inspection predicts failure against a grounded oracle, preserve
both and label the case as deliberately bug-revealing. Execution failure then
confirms the suspected defect; it is not an oracle-authoring failure.

## Prioritization

Order by:

1. user/business impact and irreversible harm;
2. changed-code proximity and consumer blast radius;
3. explicit code/spec evidence and failure likelihood;
4. authentication, money, data integrity, privacy, security, recovery, and accessibility consequences;
5. setup/run time, reversibility, flakiness risk, and ability to produce decisive evidence.

Use:

- **P0:** cannot trust the build or core promise without it; severe integrity/security/recovery risk.
- **P1:** changed contract, primary flow, direct consumer, or likely high-impact regression.
- **P2:** representative edge, compatibility, accessibility, resilience, or safe security/privacy quality.
- **P3:** broad/rare/expensive exploration or low-impact polish.

Within equal risk, run the cheapest decisive test first. Place blockers and shared setup before dependents. Do not hide long setup or execution costs.

## Artifact

Use `scripts/carbon_run.py init` with the plan JSON. It writes:

- `run.json`: durable current state;
- `plan.json`: immutable input plan snapshot;
- `events.jsonl`: append-only progress/result events;
- `report.html`: clickable self-refreshing plan and result dashboard.
- `evidence/manifest.json`: page artifacts, strategy, persona feedback,
  exploratory observations, cross-artifact signals, and explicit gaps.

Open `report.html` for the user before execution.

Use `--state-root <writable-workspace>` when the target is a screenshot, URL, external checkout, or read-only tree. CARBON keeps the target path/URL in plan provenance while writing `.carbon/runs/` only beneath the explicit writable state root.

## Canonical adapter names

- `isolated-browser`: fresh browser/profile/context for UI behavior and screenshots;
- `direct-http`: isolated API requests with explicit base URL, headers by credential-source name, and cleanup;
- `cli`: documented local commands with captured exit status/output;
- `code-inspection`: static contracts and risks only, never a runtime pass;
- `computer-use`: isolated coding-agent computer-use session, not the user’s live browser;
- `manual`: user-performed or authorization-gated step with evidence requested.

An agent may add a qualified adapter such as `direct-http:openapi`, but the plan must explain how it executes and what state it can change.
