Harness Capability Projection
Versioned support contracts and truthful outcomes for AI harness projection
Historical (retired in CLI 6.0.0). This page describes the manifest-driven lifecycle. The Registry Baseline replaced it: see Scaffold Baseline and the CLI scaffolding runbook.
Harness projection converts one neutral ContextPlan into native Claude, Codex, Cursor, and OpenCode actions without pretending that the four harnesses have identical capabilities.
Capability Contract
Each adapter publishes a versioned capability matrix with exactly one row for each contribution family:
- Skills
- Scoped prompts
- Subagent templates
- Lifecycle hooks
- Tool configuration
Every row declares supported, degraded, or unsupported behavior. degraded is capability support metadata, not scaffold health. The matrix version and adapter version travel into the projection receipt, so output can be traced back to the contract that produced it.
The matrix describes harness capability. It does not modify the neutral plan and does not invent native concepts. For example, a real tool may remain a typed omission when a harness lacks a truthful project-level registration surface.
Projection Results
Adapters return actions, limitations, omissions, warnings, and failures as separate typed collections. Limitations and omissions are durable provenance. Warnings are reserved for genuine actionable nonfatal anomalies.
| Evidence | Meaning | Aggregate effect |
|---|---|---|
| Action | A supported native operation with canonical identity and source/target trace. | Applied independently when safe. |
| Limitation | An expected provider capability boundary with a stable reason and canonical trace. | Neutral provenance; health remains success. |
| Omission | A contribution was deliberately not projected or a project-owned prompt was preserved, with canonical trace. | Neutral provenance; health remains success. |
| Warning | A genuine actionable nonfatal anomaly occurred while independent supported output applied. | Produces partial when no failure exists. |
| Failure | Input validation, adapter logic, path containment, managed source resolution, or application behavior is broken. | Produces failure and a nonzero command exit. |
Known unsupported behavior and preserved project-owned prompts are neither faults nor degraded health. They remain visible in the receipt without producing warnings, scaffold issues, scaffoldDegradations, or partial. Invalid input, adapter defects, unsafe paths, missing managed canonical sources, and failed application are not downgraded to warnings. A failure can retain successful actions, limitations, and omissions beside it; the aggregate result must still be failure.
Shared and Harness-Specific Behavior
The pure shared projection core validates capability matrices, invokes the adapter contract, returns native actions or typed omissions, and computes the projection summary. A separate application boundary applies those actions independently and folds filesystem failures into the final aggregate result. Adapters only translate neutral contribution identities into truthful native actions or typed omissions.
Canonical shared prompt identity remains .agents/AGENTS.md. Harnesses may mirror it or use a native target, but that materialization choice never enters ContextPlan. Consumer-owned regular prompt files are preserved and recorded as neutral omissions rather than overwritten or falsely reported as applied.
All projected source, target, canonical, native, and file paths are contained within the repository root before mutation. Rejecting one unsafe action does not block unrelated safe actions, but it does make the overall result a failure.
Receipt Boundary
.devpunks/harness-projection-receipt.json records the context plan version, aggregate status, adapter and matrix versions, canonical traces, actions, limitations, omissions, warnings, and failures. A healthy run records success, and its scaffold manifest records projectionStatus: "success" with empty scaffoldDegradations, even when neutral limitation or preservation provenance exists. The receipt explains a projection run; it is not desired state and should not be hand-edited to direct the next run.
The original IP-317 artifacts preserve the historical contract and its test evidence. This page is the current health authority and supersedes their former rule that expected limitations or preservation omissions produce partial.
See Compile and Project Repository Context for the end-to-end flow and Shared Scaffold Model for schema ownership.