103 lines
5.8 KiB
Markdown
103 lines
5.8 KiB
Markdown
# 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.
|
|
|
|
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.
|