# CARBON AI-intent test contract

Use this reference when importing legacy tests, reviewing readiness, or deciding whether a prompt-defined test is ready to activate.

## Schema

The portable test-case shape originates with [OpenTest.ai](https://www.opentest.ai/),
`otai/testcase` v1. Its required field is `title`; its public fields are `title`,
`goal`, and structured `steps`. CARBON keeps those fields and identifies the
origin in `schemaOrigin`, then adds execution, safety, readiness, lifecycle, and
evidence fields. The CARBON library is a container around those testcase
extensions; it is not presented as a separate OpenTest.ai format.

The library uses `carbon.intent-library/v1`; each entry uses `carbon.intent-test/v1` and includes:

- `id`, `title`, `goal`, and the tester-authored `intentPrompt`;
- `schemaOrigin`, identifying OpenTest.ai `otai/testcase` v1 as the origin;
- `scope`, `setup`, `inputs`, and `oracles`;
- `evidenceRequirements`, `adapter`, `priority`, `tags`, and `safety`;
- `status`: `draft`, `active`, or `archived`;
- `lifecycle`: candidate until CARBON execution evidence qualifies it;
- `source`: prompt or legacy provenance, including path/framework/hash where available;
- `readiness`: score, high/medium/low band, and explicit missing information;
- `revision`, `createdAt`, and `updatedAt`.
- optional `bakeIn` state with observed attempt, repair, evidence, and run provenance.

`status` controls inclusion in automatic plans. `lifecycle` records evidence maturity. Activating a test does not make it a trusted regression.

## Good intent

A useful intent says what risk or product promise to validate while leaving the agent freedom to adapt to the current UI, API, or implementation. It includes enough constraints to avoid a vague “make sure it works” exercise.

Prefer:

> As a billing administrator, change a monthly subscription to annual using a synthetic account. Verify the quoted proration, one durable subscription transition, invoice/audit consistency, retry safety, and the confirmation shown to the user.

Avoid:

> Click `#plan-2`, wait 3 seconds, click the third blue button, and check that the div exists.

Keep exact selectors, wire formats, status codes, and timing when they are the contract rather than incidental implementation.

## Conversion bands

- **High:** clear title/intent, target scope, setup/data, objective oracle, and evidence expectation. Pilot locally.
- **Medium:** useful intent but one or two material setup/oracle/scope gaps. Refine before activation.
- **Low:** a procedural fragment, vague title, or missing pass criterion. Keep draft and ask focused questions.

Do not inflate readiness because a legacy test passes today. Readiness asks whether an AI coding agent can reproduce the intended validation safely and judge it objectively in a future build.

## Legacy conversion rules

1. Preserve the original source and hash; do not rewrite it during import.
2. Extract test names, actions, assertions, data, and setup as evidence of intent.
3. Separate business-relevant contracts from brittle mechanics.
4. Preserve negative, boundary, authorization, idempotency, recovery, performance, accessibility, and destructive intent.
5. Mark missing URLs, roles, fixtures, flags, credentials, callbacks, and expected evidence.
6. Deduplicate idempotently by source path, hash, and case location.
7. Review and pilot before activating a batch.

For TestRail and Xray exports, preserve external case/test keys, section or repository path, source format, and step-level expected outcomes. For spreadsheets or manual cases, map common title/name, steps/procedure, expected/oracle, setup/preconditions, and data/input columns. CARBON directly reads ordinary `.xlsx` sheet values and `.docx` text/tables locally; formulas, comments, macros, attachments, and hidden context are not execution evidence and must be reported as conversion gaps when material.

## Import bake contract

Every newly imported batch prepares a durable local bake unless the user chooses conversion only. The coding agent executes each queued intent through its local browser, API, evaluation, code, or manual adapter and records actual results plus evidence.

- `test-definition`: CARBON may revise only intent, scope, setup, inputs, oracles, evidence requirements, or adapter, then rerun up to the configured bounded limit.
- `infrastructure`: preserve runner, environment, authentication, data, or availability blockers without calling the product defective.
- `product-defect`: preserve the observed failure and evidence; product changes require a separate scoped request.
- `unknown`: preserve uncertainty and keep the test draft.

Only an observed pass with evidence activates an imported test and advances its lifecycle to `observed`. Bake-in does not promote a trusted regression. Paid, public, destructive, and high-volume cases remain blocked until the exact action is approved.
