feat: add protocol compatibility diagnostics and historical readers
This commit is contained in:
@@ -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,
|
||||
|
||||
Reference in New Issue
Block a user