# Compatibility and protocol evolution A project's historical records do not have to be rewritten whenever AIE evolves. Completed Works retain their original files, approvals, evidence and completion provenance. Continued readability is a reader responsibility, not a reason to reopen delivered work or to add current refinement content to old Works. ## Public inspection Run `aie project compatibility --format json` using the installed executable. It reports: - `cliVersion`: the executable release, separately from data compatibility. - `currentProtocolVersion` and `readableProtocolVersions`: supported contract revisions. - `formats`: supported read versions and the current write version for each format family. - `findings`: observed versions, missing defaulted fields and diagnostics by file. - `state`, `readable`, `migrationRequired` and public guidance. The scan covers configuration, discovery manifest, Work counter, all Works (including archived and completed), canonical record documents, artifact manifests, AIE-generated completion receipts and record revision files. It does not treat local backups, ignored runs or ordinary artifact payloads as protocol records. It checks missing references to current records. It does not validate revision links, evidence integrity, semantic acceptance criteria or delivery readiness; run `project validate` and `work check` for their respective contracts. No repository commands, adapters, locks or writes occur during compatibility reads. | State | Meaning | CLI exit | |---|---|---| | `CURRENT` | Observed representations match current supported formats | 0 | | `LEGACY_COMPATIBLE` | Supported older representations or omitted defaulted Work fields | 0 | | `UNSUPPORTED` | A declared version has no supported reader | 4 | | `INVALID` | Malformed metadata, unknown fields, missing records or invalid typed content | 4 | The report is an inspection, not a conversion plan. No required migrations are registered, so `migrationRequired` is false, including for unsupported versions: an unknown version is not evidence that an older CLI can convert it. Unsupported records require a CLI with the appropriate reader; invalid data needs deliberate repair. Basic command/path errors retain the usual exit codes. ## Three independent version dimensions `protocol.json.schemaVersion` describes the manifest's structure. Its new optional `protocolVersion` identifies the engineering contract. The initial explicit contract revision is 1; absent `protocolVersion` means the pre-versioned baseline contract 1 and is reported as legacy compatible. The CLI release number is not a substitute for either. Unsupported declared manifest/contract versions prevent ordinary CLI operations and onboarding from overwriting a newer contract. Compatibility inspection remains available to explain the mismatch. Contract 2 advertises deterministic DF open-agenda import. The CLI reads contracts 1, 2 and 3, and existing contract-1 projects remain legacy compatible without any Work migration. An import-enabled manifest requires contract 2 and the `discussion-import` capability. This makes old contract-1 CLIs refuse the new manifest before onboarding could overwrite its feature declaration. `onboard` refreshes the entry files with backups; completed Works and history are unchanged. Contract 3 adds human Work guidance and optional Plan experiments; it advertises `work-guidance`, `human-decision-request` and `plan-experiments`. New Works ask for mode and require DEC approval by default. Existing Works without guidance retain their historical semantics until explicit adoption. Guidance is omitted when absent and empty experiment collections are omitted, preserving completion digests. See [Work conduct and OODA](work-guidance.md) for the behavior and commands. The format catalog is deliberately small: | Format | Current writer | Supported readers | |---|---|---| | Manifest schema | 1 | 1 | | Canonical record schema (including configuration and Work) | 1 | 1 | | Narrative document | 2 | 1, 2 | | Metadata-only document (Work) | 1 | 1 | | Work sequence | 2 | 1, 2 | `schemaVersion` and `documentVersion` describe different layers of one file. A discussion may have record schema 1 in document version 2. An omitted document version means 1. Work operational/refinement/EPIC fields absent from earlier schema 1 records retain their documented empty/false defaults. Existing sequence readers interpret legacy decimal reservations without changing identifier spelling; only an explicit creation of a new Work advances and writes the sequence. The installed manifest declares the expected contract, not a certificate that every record has been converted. The scanner reads actual versions in current records and history; mixed supported versions are normal. Capabilities are discovery labels, not independent migration versions or evidence that a feature has been configured. ## Updating instructions and future migrations `aie onboard` is idempotent and backs up changed entry files. It refreshes the README, agent instructions and manifest, preserving project rules outside the managed block. It does not convert Works, decisions, history, evidence or the Work counter, and does not manufacture topics, answers, decisions or approval. A historical Work remains legacy compatible after onboarding, which is expected. Use only the installed CLI and public documentation for consumer operations; report gaps rather than reading the implementation to infer a procedure. When introducing an incompatible format or contract, add an explicit supported reader/adaptation path and retained fixtures. Unknown schemas and fields must not be silently ignored to simulate compatibility. Increasing a writer version must not remove an existing reader or alter the meaning of historical approval/provenance. A future required conversion must declare its source and target versions and expose a public command that previews exact scope before applying changes, backs up original bytes, resumes safely and is idempotent. The report may only claim a required migration when a known route actually exists. Completed historical Works must retain a read path; they must not be selected for blanket normalization. There is no placeholder migration command and no automatic project-wide rewrite in this release. ## Historical regression fixture `CompatibilityTest` loads a frozen project produced by the prior 0.1.0 native executable, with a pre-versioned manifest, legacy sequence, omitted Work fields, YAML-only discussion and decision revision, accepted decision, evidence and completed Work. The tests compare all stored bytes before/after reads, and all Work files before/after onboarding. They also check interpreted approval/completion provenance, the original scope digest, mixed versions and unsupported/corrupt formats.