# Eva-CLI V1.5 Compatibility Policy (Historical)

> Language: English
>
> Published default: `docs/en/release/v1.5-compatibility-policy.md`
>
> Translation: [Simplified Chinese](../../zh-CN/release/V1.5兼容性策略.md)

Updated: 2026-07-14

Status: historical source-release policy associated with `v1.5.0`; not a complete compatibility guarantee for current `main`.

## Scope

V1.5 documented which source-checkout CLI contracts were intended to remain compatible while release commands were added. This record separates a policy promise from code structure and automated verification strength.

Current compatibility and production gaps are tracked in the [V1.x incomplete feature inventory](../planning/v1.x-incomplete-feature-inventory.md) and current contract fixtures.

![Eva-CLI release history boundary](../../../assets/release-history-boundary.svg)

## Version Context

| Signal | Meaning |
| --- | --- |
| V1.0 | Internal milestone commit `437087c`; no `v1.0` tag exists |
| V1.4 | Internal lifecycle milestone commit `909ab07`; no `v1.4` tag exists |
| V1.5.0 | Annotated tag `v1.5.0`, resolving to commit `74d85e7da58ac40ef5d30b38e2844dee503a44c0` |
| Current `main` | Cargo and CLI report `1.11.5-alpha`; later V1.12-V1.17 strings are legacy evidence IDs, not release tags |

## Policy, Code, And Test Strength

| Contract | V1.5 policy | Code evidence | Automated verification strength |
| --- | --- | --- | --- |
| JSON envelope | Success keeps `ok`, `command`, `exit_code`, `data`, and `trace`; error keeps `ok`, `command`, `exit_code`, `error`, and `trace` | Shared success/error writers construct those top-level fields | CLI unit tests cover representative success and error paths; current golden fixtures cover selected successful commands, not every command/error permutation |
| Exit codes | `0`, `1`, `2`, `3`, `4`, `5`, and `64` keep their documented meanings | Central constants and error-kind mapping define the values | Unit tests exercise representative usage, config, policy, runtime, and external failures; no historical binary-to-binary diff is run |
| Command surface | Existing V1.0-V1.4 command families remain available while `release` is added | V1.5 parser/help contained both old and new families | Presence tests and command tests exist; `release migration` does not compare command surfaces |
| Sample configuration | Checked-in sample project and manifests remain loadable without migration | Typed loaders parse the samples | Loader tests verify the current checkout; they do not compare a V1.4 release because no `v1.4` tag exists |
| Plan-first operations | Hardware bind, restore, and upgrade stay non-destructive at the V1.5 tag | The tag exposes logical bind, restore plan, and upgrade check only | Command tests cover those tag-era boundaries; current `main` has separate policy-gated apply paths |
| Deprecation window | A breaking CLI or manifest change requires at least one documented release window | Stored as policy text in `CompatibilityPolicy::v15()` | Governance rule only; no code automatically enforces the passage of a release window |

## V1.5 Public Surface

The compatibility declaration covered these V1.5-era command families:

- version, doctor, configuration validation, inspection, basic run, and local task diagnostics;
- Adapter, MCP, Skill, discovery, memory, and hardware diagnostics;
- backup, snapshot, restore plan, and upgrade check;
- release check, security, performance, and migration reports.

This is a historical V1.5 surface, not a list of every current command. Current `main` also exposes daemon, agent, capability, emit, observability, restore apply/rollback, upgrade apply, and other additive alpha paths.

## Current Contract Checks

Current `main` retains the shared envelope and exit-code implementation. It also provides `scripts/validate-cli-json-contracts.ps1` for checking selected golden subset fixtures:

- required fields and required nested values must remain present;
- removed or renamed fixture fields fail validation;
- additive fields are allowed;
- commands without fixtures and unrepresented error variants are outside that suite's proof.

`release migration` returns the compatibility policy as structured data, but it does not execute these golden checks or inspect Git history. A `compatible` result is therefore a declaration, not a generated compatibility verdict.

## Compatibility Limits

The V1.5 policy applied to the source checkout, documented command families, JSON envelope, exit-code meanings, and checked-in sample configuration. It did not promise:

- installer or package-manager compatibility;
- signed artifact layout or supply-chain identity;
- production performance numbers;
- durable storage schema stability;
- automatic migration of operator data;
- compatibility of capabilities added after the `v1.5.0` tag.

## Related References

- [V1.5 migration declaration](v1.5-migration-guide.md)
- [V1.5 release hardening evidence model](v1.5-release-hardening.md#evidence-model)
- [V1.5.0 release acceptance record](v1.5-release-acceptance.md)
- [Current V1.x incomplete feature inventory](../planning/v1.x-incomplete-feature-inventory.md)
- [Current project configuration boundary](../operations/project-configuration.md)
- [Version management](version-management-plan.md)