feat: add protocol compatibility diagnostics and historical readers

This commit is contained in:
Nilton Constantino
2026-11-16 10:13:05 +00:00
parent bd2c9133da
commit 3dd04a730f
48 changed files with 1382 additions and 13 deletions
+34
View File
@@ -24,6 +24,40 @@ Use `ai-engineering` (or its installed alias `aie`). No server or model API is n
whole lists. Use DEC drafts for significant commitments; small work need not
invent a decision or plan merely to satisfy a ceremony.
## Compatibility and protocol updates
Run `aie project compatibility --format json` before considering an update. `status`
includes a compatibility summary and the diagnostic command. The diagnostic is
read-only: it inspects actual canonical files and record revisions, without locks,
backups, model calls or migrations. It includes AIE completion receipts, while ignored
runs, local backups and ordinary artifact payloads are excluded. Use `project validate`
for integrity.
`protocol.json` separates `schemaVersion` (the manifest shape) from `protocolVersion`
(the engineering contract revision). A missing `protocolVersion` denotes the legacy
baseline contract 1. The report exposes the installed CLI release, supported contract
versions, format catalog, observed versions and missing defaulted Work fields.
Storage `schemaVersion` and narrative `documentVersion` remain independent.
States are `CURRENT`, `LEGACY_COMPATIBLE`, `UNSUPPORTED` and `INVALID`. The first two
are readable, return exit 0 and do not require migration. Unsupported or invalid
records return exit 4 with file-specific diagnostics. A newer manifest does not prove
that old records were converted. A missing optional field is not by itself a defect.
Compatibility is separate from structural validation and completion readiness.
Keep historical and COMPLETED Works in their original formats. The CLI reads older
supported representations and applies documented defaults in memory, preserving
IDs, approvals, evidence, completion provenance and content hashes. Never reopen or
rewrite a completed Work merely to materialize current fields, topics or surveys.
`aie onboard` refreshes the entry instructions and manifest, with backups, while
leaving Works, evidence and revision history unchanged. A newer unsupported manifest
or contract is refused rather than overwritten; use a compatible CLI. No required
migration is registered in this release. Future conversions must have an explicit
public command, scope, preview, backups and repeatable execution. Do not invent a
migration or inspect AIE source code to discover consumer update procedures; report
public-interface gaps with evidence instead.
## Topics, surveys and refinement
Discussion remains the refinement space: receive ideas, organize topics, investigate,