feat: adopt local SQLite engineering memory and quality gates

This commit is contained in:
2026-11-22 14:39:00 +00:00
parent f5d5db73c2
commit 218c060b94
228 changed files with 28728 additions and 1161 deletions
+25 -13
View File
@@ -1,7 +1,7 @@
# 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
Completed Works retain useful memory, approvals, validated evidence results 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.
@@ -32,13 +32,24 @@ No repository commands, adapters, locks or writes occur during compatibility rea
| `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:
The report is an inspection, not a conversion plan. Legacy reading does not require conversion, 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
Contract 4 adds `sqlite-storage`, `local-memory`, `quality-gates`,
`temporary-artifacts` and the explicit storage migration route. New projects select
SQLite and ignore state by default. Legacy projects can remain readable on their
original backend. SQLite requires contract 4; a database without the matching
bootstrap is refused rather than treated as empty memory.
The SQLite report inspects typed records/revisions in the database. Bootstrap,
database schema and original legacy document versions remain separate dimensions.
Project validation checks foreign keys, revision chains and evidence/retirement facts.
A retired attachment is valid historical evidence only with its persisted validation;
new checks still require available inputs.
## Independent version dimensions
`protocol.json.schemaVersion` describes the manifest's structure. Its new optional
`protocolVersion` identifies the engineering contract. The initial explicit contract
@@ -49,7 +60,7 @@ operations and onboarding from overwriting a newer contract. Compatibility inspe
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
1, 2, 3 and 4, 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`
@@ -70,7 +81,8 @@ The format catalog is deliberately small:
| 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 |
| Work sequence (legacy files) | 2 | 1, 2 |
| SQLite schema/application | 1 / AIE1 | 1 / AIE1 |
`schemaVersion` and `documentVersion` describe different layers of one file. A
discussion may have record schema 1 in document version 2. An omitted document
@@ -84,7 +96,7 @@ record has been converted. The scanner reads actual versions in current records
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
## Updating instructions and storage
`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.
@@ -99,12 +111,12 @@ reader/adaptation path and retained fixtures. Unknown schemas and fields must no
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.
The public SQLite route is `storage migrate` (read-only preview), then
`--apply --expect HASH`. `--recover` and `--rollback` require the operation's same
fingerprint. It is optional for supported legacy reading and never runs implicitly.
Read [the migration procedure](storage-migration.md) before conversion. Unknown
schemas still need an appropriate reader; this route converts supported legacy
records, not arbitrary unsupported versions.
## Historical regression fixture