# CARBON automatic framework

Use this reference for broad requests such as “test this,” change-focused regression, CI setup, build comparison, or when CARBON needs durable product memory.

## Durable project model

CARBON stores inspectable project-local state under `.carbon/framework/`:

- `product-model.json`: UI and AI surfaces, APIs, flows, source provenance, links, tests, changed files, and discovery warnings.
- `coverage-map.json`: candidate and trusted regression coverage for each modeled entity, plus explicit gaps.
- `regression-suite.json`: generated or learned tests and their lifecycle, observations, outcomes, priority, and ownership evidence.
- `orchestration.json` and `orchestration-plan.json`: why the current request maps to a particular changed/adjacent scope, `carbon-browser/v1` capability requirements and selected adapters, approval gates, budget, and tests.
- `adaptive-plan.json`: original reproduction first, then the smallest related trusted regressions.
- `outcomes.jsonl`: confirmed, dismissed, false-positive, escaped, fixed, and flaky feedback.
- `confidence.json`, `confidence-history.jsonl`, and `report.html`: current/previous build evidence, lifecycle, coverage, uncertainty, repetitions, and release recommendation.
- `.carbon/runs/<run-id>/evidence/manifest.json` plus `evidence/pages/`: safe
  per-page screenshots and telemetry, channel gaps, artifact hashes,
  redactions, generated user-perspective feedback, breadth/depth exploratory
  charters and observations, and general cross-artifact issue signals rendered
  by the run report.
- `.carbon/browser/sessions/<session-id>/`: the selected browser adapter
  manifest, explicit capability negotiation, redacted operation envelopes,
  evidence handles, provenance, and a tamper-evident ledger digest.

This state is evidence, not authority. Discovery does not prove behavior. Generated tests begin as candidates. CARBON does not modify source, start paid/public execution, promote a regression, or release a build without the applicable scoped approval.

## Opinionated doctrine

Apply [the CARBON testing doctrine](testing-doctrine.md) to every plan and
recommendation. Its machine-readable `spices` preserve the useful case, failure
mode, and CARBON default for exploration, automation, human evaluation, unit
and end-to-end tests, mocks, coverage, test pyramids, shift-left, production
testing, fuzzing, snapshots, and AI-generated tests and judges.

In particular, rapid or session-based exploration is a discovery instrument,
not a complete confidence system. Use it for unfamiliar and ambiguous
behavior, preserve a bounded charter and evidence, and convert consequential
discoveries into repeatable candidates. Do not report an exploratory session
alone as trusted regression or release evidence.

## One-command routing

Run:

```bash
python3 scripts/carbon_framework.py prepare \
  --root <project> \
  --request "test this" \
  --target <url-or-api> \
  --size <quick|medium|large> \
  --strategy <auto|breadth|depth|balanced> \
  [--openapi <spec>] [--har <redacted-har>]
```

The router:

1. inventories source, tests, UI/AI surfaces, source-declared routes, OpenAPI operations, and authorized HAR traffic;
2. maps changed files to directly affected surfaces and linked APIs;
3. generates positive, negative, boundary, authorization, idempotency, and resilience API candidates;
4. declares required browser operations and evidence channels, negotiates them
   through `carbon-browser/v1`, selects an explicit local or managed adapter,
   and preserves approval gates without silent capability downgrade;
5. writes a `carbon_run.py` compatible plan;
6. selects breadth, depth, or balanced exploration from the change/risk model,
   generates product-grounded user perspectives, and writes explicit charters;
7. updates the candidate suite and coverage gaps.

CARBON owns the stable browser semantics and evidence envelopes. The coding
agent, Vibium/WebDriver BiDi, Playwright/CDP, Selenium/WebDriver, or testers.ai
managed devices may execute the selected browser operations as adapters. The
manager does not impersonate those engines; it negotiates capabilities,
dispatches through the available host integration, and records what really ran.
API clients, accessibility engines, load generators, and AI evaluators remain
separate explicit adapters.

During browser execution, each planned generated user perspective must produce
feedback tied to a captured page and screenshot, and each exploratory charter
must produce at least one observation or an explicit cut-line gap. Persona
opinion remains separate from deterministic test status. The run report shows
ratings, what worked, friction, recommendations, breadth/depth observations,
coverage, next probes, and supporting artifacts.

## Lifecycle and ownership

The trusted path is:

`candidate → observed → repeatable → regression`

- **candidate:** generated from code, contract, traffic, library, recording, or tester judgment.
- **observed:** one terminal passed or failed run has an actual result and an evidence handle.
- **repeatable:** passed with actual results and evidence in two distinct runs.
- **regression:** a person explicitly reviewed and promoted the repeatable case with `promote --confirm`.
- **needs-review:** dismissed or false-positive evidence invalidated the current oracle or implementation.

Record real outcomes with `outcome`. An escaped defect raises priority. Dismissed and false-positive cases lose trusted status pending review. Stale source or contract anchors should be rediscovered before execution, not silently treated as current.

## Adaptive execution and stopping

After a failure, `adapt` writes a plan that:

1. preserves and retries the original case first;
2. selects trusted tests sharing the surface, flow, or API operation;
3. stops expansion if the failure cannot be reproduced, a severe/shared blocker appears, authorization is missing, or more evidence no longer changes the decision.

Do not respond to instability with blind repetition. Compare the same defined population and case semantics across builds. CARBON’s 2×2 chi-square calculation is exploratory, warns when expected cells are too small, and warns that paired tests require paired analysis. Preserve the raw observations and state what result would change the decision.

## CI contract

`carbon_framework.py ci --root <project>` previews; `--apply` writes a vendored framework manager plus `.github/workflows/carbon.yml`. The workflow runs discovery/planning on pull requests and nightly, optionally invokes a repository-owned `CARBON_TEST_COMMAND`, analyzes recorded evidence, and uploads `.carbon/framework/`.

Planning without execution remains insufficient evidence. CI may recommend `insufficient-evidence`, `canary`, `hold`, or `ship`; a human remains the release authority.
