# Learned-test contract

A promoted learned test must be portable into a normal CARBON plan and auditable back to its learning session.

Require:

- stable test ID, title, priority, type, adapter, and estimated duration;
- surface and environment identity;
- supported claim and confidence;
- exact probe or canonical steps;
- product oracle and evidence to capture;
- observation and hypothesis IDs as provenance;
- required role, synthetic data, setup, dependencies, cleanup, and stop conditions;
- side-effect flags;
- staleness anchors: route/operation, relevant contract fingerprint or revision, and one behavior to re-observe.

`scripts/carbon_learn.py promote` writes promoted cases to `learned-tests.json` in normal CARBON plan shape. Merge only relevant promoted cases into a new plan; deduplicate them against library-derived and code-derived cases.

Promotion means “good test candidate supported by learning.” It does not mean the product passed that test, and it does not make a target-specific behavior a universal CARBON convention.

When Learn Mode discovers a flow, `generate-flow` also writes automatically generated inputs and cases to the learning model and plan fragment. These cases carry `learningStatus: candidate`; their oracles are hypotheses until execution supports them. Read [learn-flow-generation.md](learn-flow-generation.md) for the flow schema, generation coverage, and evidence boundary.

Resolve conflicting observations by narrowing environment, role, state, version, data, or timing. If conflict remains, keep separate hypotheses or mark the oracle unknown.
