# Evidence and Handoff Contract

Use [Feature document management](../../../../docs/FEATURE_DOCUMENTATION.md) for concise main reports,
linked details, and Coordinator's document inventory. Include main and required detail paths in evidence.

Every stage returns one envelope:

| Field | Required content |
| --- | --- |
| `feature_id` | Stable feature identifier |
| `stage` | `requirements`, `research`, `formulation`, `numerical-review`, `io-definition`, `implementation-planning`, `implementation`, `correction`, `physics-evaluation`, or `release-readiness` |
| `outcome` | `pass`, `return-upstream`, `retry`, `blocked-environment`, or `needs-user-decision` |
| `next_owner` | Agent id, or YAML `null` |
| `evidence_paths` | Repository-relative artifacts used or produced |
| `evidence_digest` | Concise findings tied to requirement IDs |
| `failure_classification` | `configure`, `compile`, `link`, `test`, `reference-comparison`, `harness`, `environment`, `upstream-contract`, `physics`, `evidence`, or YAML `null` |
| `retry_key` | `<feature-id>\|<failing-gate>\|<classification>\|<contract-revision>`, or YAML `null` |
| `attempt` | Coordinator-managed nonnegative attempt count for the retry key |
| `escalation_class` | Critical-decision class, or YAML `null` |
| `blocker` | Actionable blocker, or YAML `null` |

Evidence records include, when applicable: source locator and access date; assumptions; command, exit code, duration, and relevant output; test identity and RED/GREEN result; artifact hash; comparison quantity, tolerance source, and decision; residual risk.

Use repository-relative paths and stable identifiers. Distinguish observed facts, calculations, inferences, and decisions. Never report a pass when a required command failed, evidence is stale, or a blocking acceptance item is unresolved.

Retry is bounded by the coordinator policy. A repeated normalized failure returns to its owning stage; it does not justify changing requirements, formulations, schemas, reference artifacts, or tolerances.