Persist explicit human discussion choices, DEC requests and approval policies. Add optional evidence-backed Plan experiments and align context, adapters and next actions under protocol contract 3. Include WRK-000B decisions, plan history and verification evidence: 167 JVM tests, 25 focused checks, Jenkins fixtures and native smoke coverage.
6.7 KiB
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.currentProtocolVersionandreadableProtocolVersions: 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,migrationRequiredand 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 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.