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
+90 -263
View File
@@ -1,287 +1,114 @@
# Architecture
## Technology selection
AIE is a local engineering memory with two cycles: investigation/refinement and
implementation, connected by DEC and Plan. OODA is adaptive; gates constrain delivery.
The CLI records external observations and applies deterministic checks. It does not
execute repository commands, operate a server or provide distributed collaboration.
The project deliberately stays on a compatible maintenance pair: **Spring Boot
4.0.9 and Spring Modulith 2.0.9**. The published Modulith 2.0.9 POM declares
Boot autoconfigure 4.0.9. Java compilation and bytecode target are both **25**,
without preview features. Gradle **9.3.1** supports running on Java 25; its Wrapper
distribution is pinned with SHA-256 verification.
## Runtime and modules
The local development JDK is pinned through `.sdkmanrc` to SDKMAN candidate
`25.5.5.0+3-graalce` (GraalVM CE 25.5.5.0.3, OpenJDK 25.0.5.0.3). This
[GraalVM innovation release](https://www.graalvm.org/release-notes/25.5/) still uses
Java 25. It provides both JVM and Native Image tooling without changing compilation
target or application dependencies. Use `sdk env` for project-scoped activation;
the Gradle Wrapper remains responsible for the Gradle version.
Primary compatibility references checked during implementation:
- [Spring Boot 4.0 requirements](https://docs.spring.io/spring-boot/4.0/system-requirements.html): Java 25, Gradle 9 and GraalVM 25 are supported; Native Build Tools 0.11.5 is the documented version.
- [Published Modulith 2.0.9 dependencies](https://repo.maven.apache.org/maven2/org/springframework/modulith/spring-modulith-core/2.0.9/spring-modulith-core-2.0.9.pom): Boot 4.0.9 dependency.
- [Gradle Java compatibility](https://docs.gradle.org/9.3.1/userguide/compatibility.html): Java 25 support starts at Gradle 9.1.
- [Spring AOT Gradle integration](https://docs.spring.io/spring-boot/4.0/gradle-plugin/aot.html).
- [Picocli native configuration](https://picocli.info/#_graalvm_native_images): annotation-processor-generated reflection metadata.
- [GraalVM 25 release notes](https://www.graalvm.org/release-notes/JDK_25/): macOS x86_64 support was removed.
Picocli **4.7.7** handles argument validation, help and dispatch. Jackson 3 YAML/JSON
comes from Boot's BOM. JUnit is explicitly pinned to **5.13.4** because the requested
test baseline is JUnit 5; the Boot BOM otherwise selects a newer major generation.
AssertJ and Modulith/ArchUnit verify behavior and dependencies. There is no Spring AI,
Embabel, web starter, persistence server or workflow framework.
## Module boundaries
All packages below are under `net.intrepid.aiengineering`. A module's base package is
its explicit public API; implementation-only Git adapters live in `project.internal`.
`package-info.java` declares allowed dependencies. `ArchitectureTest` calls
`ApplicationModules.verify()` to enforce cycles, visibility and dependency rules.
Java 25, Gradle 9.3.1, Spring Boot 4.0.9, Modulith 2.0.9, Picocli 4.7.7 and Jackson 3
remain pinned by the build. JUnit 5.13.4, AssertJ and Modulith/ArchUnit verify behavior.
GraalVM CE 25.5.5.0+3 is pinned in .sdkmanrc. Spring supplies process lifecycle and AOT;
services are ordinary Java classes with explicit project paths and no retained Work
cache. Infrastructure stays outside immutable domain records.
| Module | Owns | May depend on |
|---|---|---|
| filesystem | Protocol codecs, safe paths, atomic file writes, locks, errors | none |
| project | Configuration, discovery, repository policy, read-only Git adapter | filesystem |
| work | Work identity/lifecycle, human guidance/history, repository snapshots, references and EPIC policy/graph | project, filesystem |
| discussion | Entries, topics, surveys, answer history and proposal dispositions | work, project, artifact, filesystem |
| decision | Draft, approval, revision and supersession records | work, filesystem |
| planning | Plans, dependencies, step results, experiments and revision history | work, decision, discussion, artifact, filesystem |
| legacyimport | DF preview, original agenda evidence, provenance and prepared Work publication | filesystem, project, work, discussion, artifact |
| artifact | Small evidence payloads and integrity metadata | work, filesystem |
| agent | Adapter contract, deterministic fixtures, routing and proposal application | project, work, discussion, decision, planning, artifact, filesystem |
| verification | Structural conformance, context, reviewed closure and deterministic EPIC coordination | all protocol modules |
| cli | Picocli commands, formats, exit codes | all APIs above |
| filesystem | Codecs, paths, SQLite sessions/typed storage, atomic external files and locks | none |
| project | Bootstrap, discovery, native/entry contracts and repository policy | filesystem |
| work | Work identity/guidance/lifecycle, source snapshots and EPIC graph/policy | project, filesystem |
| discussion | Entries, topics, surveys, answer history and dispositions | work, project, artifact, filesystem |
| decision | Drafts, approvals, revision and supersession | work, filesystem |
| planning | Plans, dependencies, results, experiments and scope exclusions | work, decision, discussion, artifact, filesystem |
| artifact | Temporary payloads, lifecycle, publication recovery and typed receipts | work, filesystem |
| agent | Proposal adapters, bounded local transport, validation and application | project, work, discussion, decision, planning, artifact, filesystem |
| legacyimport | Explicit DF preview/import, preserved originals and provenance | filesystem, project, work, discussion, artifact |
| verification | Integrity/readiness, gates, snapshots, coordination, migration and context | protocol modules |
| cli | Picocli commands and presentation | public module APIs |
Spring owns the process lifecycle and CLI bean, and supplies AOT processing. Protocol
services are ordinary Java classes with explicit path arguments and no retained Work
cache. This keeps direct tests and fresh instances simple. Infrastructure dependencies
remain inside services, outside immutable domain records. The small `GitAdapter` port
is internal to Project and can be replaced without changing Work contracts.
ArchitectureTest enforces these boundaries. Work does not import Decision, Artifact
or Verification. Verification coordinates across independently owned domains.
Context assembly, readiness and evidence-mapped closure belong to Verification because they combine independently persisted
modules and refuse to export structurally inconsistent state. Work does not depend
on Discussion, Decision or Artifact, avoiding cycles. It owns stable references only.
## Storage boundary
The engineering project is independent of repository count: a plain folder can use
the protocol with no Git dependency, a single Git repository can register the root
using `.`, and a larger workspace can register several child repositories. The same
configuration schema and services support each case; no separate project mode or
additional repository type is needed.
New projects use `.ai-engineering/aie.db`, selected explicitly in the bootstrap.
Small configuration and entry files remain outside the database. File existence alone
never selects SQLite. Contract 4 and the database application/schema versions are
validated before use. Legacy decoding remains explicit and never converts on read.
Work refinement uses an immutable update value that distinguishes omitted fields from
explicitly emptied lists. The domain preserves identity, lifecycle and references;
the filesystem service locks the project and replaces front matter while retaining
trailing notes. Discussion file input belongs to the CLI adapter: Picocli enforces
exclusive text sources and a bounded strict UTF-8 read supplies the existing domain
entry. Neither feature changes canonical record schemas or introduces new modules.
SQLite JDBC 3.54.1.0 provides the embedded engine. SqliteDatabase owns connection
lifecycle, foreign keys, WAL/FULL durability, IMMEDIATE writes, snapshot reads and
bounded busy waits. Nested services share a transaction; failed nested mutations
cannot be accidentally committed after an exception is caught. File-publication
callbacks run after commit or rollback, after the connection closes.
## Persistence and native execution
SqliteRecords maps trusted record components to typed scalar columns and ordered
child rows. Composite operational values have a domain codec, not serialized file
content. List presence preserves null versus empty, necessary for historical hashes.
Identity/current-revision/format/reference tables retain ownership and revisions;
EPIC links have a unique child-parent index and foreign keys. Selected Work reads
use direct keys. Global integrity checks still inspect the whole project.
Writers take an OS file lock per project. Nested service calls on the same thread reuse
the outer lock; other threads/processes cannot interleave the proposal application.
Complete UTF-8 files are written to a sibling
temporary file, forced to disk and published atomically. New files use a hard link
to avoid overwriting an existing destination. Existing files use atomic replacement;
unsupported filesystems fail instead of quietly falling back to partial writes.
New Works, projects and artifact payload bundles are staged before directory rename.
See the protocol document for crash limits and recovery.
A project publication lock fences storage migration/rollback from writers. SQLite
commands wait a bounded interval and reject a backend transition observed while
waiting. Ordinary related reads need no file lock and use one database snapshot.
Jackson parses explicit records, rejects unknown fields, duplicate YAML keys and
unsupported schema versions. Native hints register those records; Picocli's annotation
processor provides command reflection metadata. The Spring AOT tasks are wired by the
native build plugin. No application arguments are passed through Spring's property
parser. The entry point explicitly chooses non-web mode and closes its context.
## Quality and temporary files
Discussion document version 2 separates typed YAML metadata from an opaque Markdown
body. The filesystem codec maps that body to the domain record's existing `text`
field; it does not infer structure from prose headings. The reader accepts legacy
YAML-only text as well. Explicit discussion migration backs up originals, preserves
semantic state and skips converted files. New decision narrative (`text`) and plan
description use the same Markdown-body codec; legacy draft DECs remain readable.
Work front matter remains canonical, with additive operational fields. Markdown
context renders discussion/decision prose without YAML escaping.
QualityGates stores required project definitions and cumulative Work additions.
Observed results bind procedures, actual invocation, inputs, Work scope/guidance,
DEC revisions, outcome and a short summary. Missing, failed or stale gates block
manual, Plan and EPIC delivery. Delivery snapshots bind the exact passed results.
Human approval remains a different record and responsibility.
## Operational replacement baseline
Artifact bytes remain outside SQLite. Inputs stay available while the Work needs
checks. Completion atomically records validated retirement intent; after commit,
eligible payloads are unlinked and acknowledged. Pending retirement is repeatable
when deletion or acknowledgement was interrupted. New checks refuse retired inputs.
Structured Plan/EPIC receipts need no payload file. Legacy originals are preserved.
Requested outputs stay in their delivery destinations, outside the cleanup scope.
The user expanded the original bootstrap scope to replace the existing discussion
workflow before introducing intelligent adapters or a legacy importer. Planning is
a concrete ninth module, not a custom workflow engine. A plan records editable scope,
dependencies and externally executed results. Starting/completing steps checks their
dependencies and accepted decisions. No repository command is executed by Planning.
ArtifactPublication journals only owned publication intent. Rollback/recovery removes
its own orphan payload, never an unrelated file. Unknown residue is reported for
inspection. Local provider workspaces are bounded temporary directories; raw transport,
credentials, environment and complete logs do not become engineering memory.
Work owns optional human guidance and its choice/request history. New contract-3
Works begin without an inferred discussion mode and require human DEC approval.
Decision and Planning enforce that authority; explicit Work-wide waiver retains
system promotion provenance. Planning owns optional experiments inside its existing
revision chain and depends on Discussion to check unresolved planning commitments.
Verification and local CLI adapters expose the applicable conduct and OODA guidance.
Legacy absent fields are omitted to preserve historical digests.
## Authority, coordination and migration
Plan creation prepares eligible deterministic draft-decision promotions through Decision,
validates every reference before publication and records SYSTEM_PLAN provenance
with the causal Plan ID and no fabricated human attestation. Existing accepted
decisions are unchanged. Decision exposes prepared promotion/recovery operations;
Planning coordinates them under the existing project lock. Ordinary failures roll
back the attempted writes; crash interruption remains subject to per-file atomicity
and structural validation. Verification checks promotion links against Plan history.
No adapter is invoked, and the Decision module has no dependency on Planning.
Plans/steps can be reopened and revised when observations change.
Guidance preserves explicit human choices, DEC requests and approval policy.
Decision/Plan revisions enforce accepted authority, dependency completion, experiment
reconsideration and unresolved concerns. SQL promotion/supersession and related
references commit together. RUN failure rolls back its proposal and separately
records a short diagnostic without references to reverted records. Request replay
remains idempotent. No adapter can approve a DEC or answer on behalf of a human.
DEC approval is an explicit human-attestation command, with actor, reason and time.
Accepted records are immutable through the CLI; revision creates a new linked draft.
Acceptance supersedes the prior accepted DEC. Decision and plan changes preserve
the previous complete file under `.history`, linked by SHA-256. Hashes detect broken
chains; they are not signatures or protection against someone rewriting every file.
Cross-record supersession uses per-file atomic publication; validation diagnoses
incomplete links. There is no distributed transaction or automatic history repair.
PlanCoordinator and EpicCoordinator retain SYSTEM_PLANS/SYSTEM_EPIC provenance,
RESULTS/DECOMPOSITION policy and explicit scope-bound delegation. Related SQL
mutations/propagation are transactional. Historical legacy semantics and hashes
remain readable; only the legacy backend retains per-file recovery boundaries.
Verification separates structural validity, mechanical readiness and human judgment.
PlanCoordinator consolidates valid Plan results without invoking an adapter, records
SYSTEM_PLANS receipts and invokes existing EPIC propagation. Planning owns content-bound
scope reviews of cancellations; Verification coordinates public mutations/reconciliation
without a reverse dependency. Reads expose the same pending reasons without writes.
Explicit reopening leaves time to change Plans. Legacy optional fields are omitted
to preserve historical digests. See [the contract](plan-consolidation.md).
StorageMigration previews canonical hashes, retains safety originals, imports typed
records in a separate database, compares content/authority/history and validates
before activation. Exact legacy bytes stay external for revision-chain verification;
readers also compare them with typed rows. Contract 4 and a visible legacy-reader
marker prevent incompatible writers. Recovery is repeatable; rollback refuses to
lose engineering memory written after activation. Existing tracked originals are
not removed. Details: [migration](storage-migration.md).
For inspection-only Works without Plans, manual
readiness requires explicit criteria, resolved questions, reviewed DECs and terminal
plans. Completion records criterion-to-artifact mappings, a stable scope digest,
human approval, and canonical integration file digests or a reason no update is
needed. Canonical-file hashes are historical snapshots; later source evolution does
not invalidate an old delivery. Current completed Work records must still match
their frozen scope. Archive retains every file. Reopening preserves completion and
lifecycle history and permits new discussion/evidence.
## Native package
Project owns provider-neutral entry resources copied into `.ai-engineering` by
`init`/`onboard`, including a machine-readable manifest. A managed root `AGENTS.md`
block points to those resources while preserving surrounding rules. Changed
instructions are backed up; repeated onboarding is idempotent. Context includes the
guide. This supports agents that inspect the project; it cannot force discovery by
an arbitrary agent. `status` and `next-actions` derive diagnostics from persisted
state without executing work or inventing human approval.
`nativePackage` builds AIE and the pinned SQLite diagnostic CLI with companion native
libraries and a checksum manifest. Native hints cover operational records/resources.
The candidate verifier creates a disposable database with native AIE and reads it
with packaged sqlite3. Install preparation is distinct from activation: versioned
releases, a current symlink and shortcuts are switched only after verification.
Installer tests use fake tools and disposable destinations. This Work did not run
an actual installer or modify the active distribution or consumer projects.
## Discussion refinement and adapter boundary
Discussion still owns refinement; DEC and Plan remain its downstream commitments.
Topics and surveys are functional records in Discussion. Legacy threads are derived
as implicit topics; reads never migrate files. Answers append explicit supersession
links. Archive/restore dispositions retain proposals and require policy/evidence.
There is no separate Idea entity. See [record contracts](discussion-slice.md).
Agent is the tenth module. `AgentAdapter` accepts immutable context/task/executor
values and returns a typed `AgentProposal`; it receives no filesystem Path, persistence
service or execution tools. Only two deterministic adapters are registered. General
selects an activity when omitted and provides fallback for unspecialized activities;
an explicit activity selects its configured executor. Classification in fixtures uses
task markers, not natural-language model interpretation.
AgentService validates the entire proposal before applying it through domain APIs.
It rechecks the source fingerprint under the project lock to reject concurrent stale
application. A RUN preserves source digest, selected executor, requester, task,
proposal, applied references and terminal/error state. Completed request IDs provide
idempotent replay of identical input. An interrupted APPLYING run blocks new runs
pending inspection. Publication is atomic per file, not a rollback transaction;
FAILED records and validation expose partial application for deliberate repair.
Verification reads run provenance and computes staleness from canonical semantic
sources, excluding run bookkeeping. State checks never invoke an adapter. A summary
is a recorded result; fresh context does not implicitly rerun it. Adapter output
cannot provide human survey answers, approve DECs, complete Works or execute commands.
Typed records and nested proposal values have Native Image reflection hints.
The initial slice did not add provider integration; the local CLI slice below extends it.
## Local provider CLI transport
PLN-0003 implements the human-selected Codex/Claude CLI transport for Discussion and
synthesis. The agent module retains the same public adapter boundary. Its internal
LocalProcess uses fixed ProcessBuilder vectors, bounded streams, virtual threads,
timeout/descendant termination and private temporary workspaces. It receives no
engineering root. Provider tool/configuration controls constrain proposals, while
OS/provider policy remains separate. The full contract and verified CLI references
are in [cli-adapters.md](cli-adapters.md).
Versioned wire schemas normalize provider output into existing AgentProposal values;
the framework assigns identity and performs ownership/policy preflight. Classification
can request clarify surveys. An explicit activity skips that provider call. Immutable
previous RUNs travel in context, but derived run bookkeeping stays out of semantic
source fingerprints. Only validated results publish canonical RUNs. Earlier transport
failures return safe diagnostics without mutating Work state or storing raw stderr.
Optional invocation provenance captures observed version, configured role/model,
duration and output digest. Absent optional fields are omitted to preserve older
fingerprints/digests. Setup collects/validates all answers before initialization and
does not invoke providers. No Node SDK, HTTP client framework or external service is
required by tests. Deterministic JDK subprocess fixtures use the production transport.
## EPIC coordination
PLN-0002 implements DEC-0003 within the existing modules. Work owns the EPIC marker,
definition, forest topology, revision history and explicit policy authorization.
Verification coordinates lifecycle writes and checks affected ancestors, using
Artifact for owned aggregate receipts. No extra module, broker, workflow engine or
agent invocation is needed. Low-level storage callers must reconcile explicitly;
public CLI/Verification lifecycle entry points propagate within the project lock.
Policy authority binds parent/important-child scopes and links, excluding execution
status. Important child completions and local readiness control RESULTS completion;
DECOMPOSITION remains a reviewed human delivery. System completions record their
origin, policy delegation and receipt, with humanApproved=false. Historical direct
human completions keep their existing digest/approval semantics.
Frozen EPIC scope digests include current important delivery records; optional
execution can continue independently. Deterministic serialization uses ordered maps
and canonical records across JVM/native processes. Automatic receipts exclude prior
receipts from their input key, allowing reuse after interrupted publication.
Reconciliation derives state from files; no mutable in-memory index is authoritative.
Details and explicit reopening/reauthorization rules are in [epics.md](epics.md).
## Compatibility inspection
The project module owns the protocol contract revision independently of the CLI
release and manifest schema. Filesystem owns the supported storage-format catalog;
existing typed readers continue interpreting older representations in memory.
Verification's compatibility service inspects actual metadata and typed content,
including record revisions and system completion receipts. The CLI exposes a full
read-only report through `project compatibility` and a summary in `status`.
This adds no automatic conversion or blanket normalization. Onboarding refreshes
entry instructions with backups and refuses to overwrite an unsupported contract.
Frozen prior-release fixtures protect historical approvals, completion provenance,
scope hashes and bytes. See [compatibility](compatibility.md) for the public contract
and requirements before a future incompatible writer or migration is introduced.
## Earlier framework review and migration
Both implementations were inspected read-only:
- The user-identified Python repository at
`/Users/niltonconstantino/personal/workspace.personal/intrepid/discussion-framework`:
README, model/locking/index persistence and structural validation.
- The sibling Java `discussion-framework`: `DiscussionOrchestrator`,
`WorkflowValidator`, `WorkPacket`, `ArtifactDocumentParser` and
`FilesystemDiscussionRepository` concepts and implementations.
Reused concepts: deterministic context as the handoff surface, stable IDs, explicit
references, file locks, atomic replacement, duplicate/reference checks and separating
content from mechanical CLI state management. No Python code or dependency was copied.
The old generic Markdown inference was replaced by typed, versioned front matter;
semantic sections are explicit and cannot silently disappear from context parsing.
No legacy HTTP adapter, NDJSON global index, accepted-agenda gate, automatic housekeeping
deletion or Lesson model was retained. Work is the project-scoped aggregate; Discussion
is refinement within a Work. Source repositories were not changed.
The deterministic DF importer reads each independent source's NDJSON index and open
AGDs. It creates one Work per source+DSC, retaining agenda Markdown as refinement
NOTEs and original bytes as evidence. A versioned owned receipt links source IDs,
DSCs, AGDs, target descriptions and generated AIE references; existing Work schemas
and historical data remain unchanged. Receipt validation is available without the
source directory and compatibility inspection recognizes the receipt format.
Work, Discussion and Artifact expose prepared publication helpers using their normal
formats. The importer seeds a complete hidden Work folder before the normal atomic
directory publication and monotonic ID reservation. Revalidation under the destination
lock binds application to the preview fingerprint; immutable receipts make retry
recognize already published Works. A multi-Work batch is deliberately not a global
transaction. No legacy decision/Plan/Lesson is imported, source files are untouched
and no agent adapter is involved. See [the import contract](discussion-import.md).
Legacy Lessons remain candidates for manual integration into canonical docs.
Primary references: [SQLite JDBC native support](https://github.com/xerial/sqlite-jdbc#graalvm-native-image-support),
[SQLite transactions](https://sqlite.org/lang_transaction.html),
[foreign keys](https://sqlite.org/foreignkeys.html),
[official source releases/checksums](https://sqlite.org/download.html),
[Boot requirements](https://docs.spring.io/spring-boot/4.0/system-requirements.html),
[Gradle Java compatibility](https://docs.gradle.org/9.3.1/userguide/compatibility.html).
+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
+5
View File
@@ -92,3 +92,8 @@ Exit codes follow AIE: 0 for a valid preview/application, 2 for invalid command
arguments, 3 for a missing project/root, 4 for invalid/stale/review-required data,
and 1 for unexpected I/O failures. Diagnostics after partial publication retain
the normal failure code and identify the Work IDs already published.
SQLite application commits the batch and its references together. Failure rolls back
all Works in that transaction and recovers owned temporary payloads. The explicit
legacy backend keeps its per-Work publication/resume boundary. Imported originals
and import provenance remain preserved by the current retention policy.
+6 -5
View File
@@ -12,11 +12,12 @@ Existing free-form discussionId threads remain valid and appear as implicit topi
an empty Work presents implicit topic `main`. Formal topics can reference original
discussion entries without rewriting those entries.
Records reside in Work-local `topics/`, `surveys/`, `dispositions/` and `agent-runs/`.
Prose uses Markdown bodies with documentVersion 2 and schemaVersion 1 metadata.
Topic and survey revisions preserve complete prior files with SHA-256 links under
their `.history/` directories, following decision/plan conventions. New files are
published before Work references; interrupted cross-file writes are diagnosed.
SQLite stores these records and their revisions as typed data. Related publication
and Work references commit together. Legacy directories/Markdown and `.history`
remain supported on the explicit file backend; migration preserves original bytes.
SQLite RUN application rolls back the full proposal on failure, then records a short
failure diagnostic without reverted references. Legacy failed publication can retain
partial applied references for deliberate repair.
A survey owns immutable question definitions and append-only answers. QST and ANS
IDs are survey-local. Each question identifies a topic and nonempty options numbered
+6 -4
View File
@@ -1,7 +1,7 @@
# EPIC contract
An EPIC is a Work with `epic: true` and a versioned definition under
`epic/<Work ID>.md`. Ordinary schema-1 Works default to `epic: false`; reads never
An EPIC is a Work with `epic: true` and a versioned typed SQLite policy.
The legacy file backend uses `epic/<Work ID>.md`. Ordinary schema-1 Works default to `epic: false`; reads never
rewrite them. Definition revisions retain SHA-256-linked snapshots under
`epic/.history/<Work ID>/`. Links point to project-scoped Work IDs, not source repos.
@@ -50,9 +50,11 @@ editing links/scopes and reviewing authorization again.
`epic check` is read-only. `epic reconcile` deterministically repairs missed
propagation from canonical child state, including after interruption between child
and parent writes. Repeated notifications do not duplicate completion or receipts.
No server, message broker, database or agent invocation is used. Invalid histories,
SQLite is embedded; no server, message broker or agent invocation is used. Invalid histories,
missing links and unsafe paths are diagnosed; arbitrary corrupted files still need
deliberate repair. Publication remains atomic per file, not a global transaction.
deliberate repair. SQLite commits related propagation transactionally; only legacy
files retain per-file publication. Required gates also constrain parent delivery.
New aggregate receipts are structured database facts; old receipt files stay readable.
## CLI
+35
View File
@@ -0,0 +1,35 @@
# WRK-000C measurement handoff
SQLite adoption does not close the latency ticket. This scenario prepares comparable
local datasets; it makes no performance claim and was not run as a benchmark in
WRK-000D. Use the same final executable/package, machine and source revision for
both backends. Keep companion libraries beside the executable.
```sh
python3 scripts/latency-fixture.py --binary "$PWD/build/native/package/ai-engineering" \
--directory /tmp/aie-latency-sqlite --works 100 --entries 10 --storage sqlite
python3 scripts/latency-fixture.py --binary "$PWD/build/native/package/ai-engineering" \
--directory /tmp/aie-latency-legacy --works 100 --entries 10 --storage legacy
```
Directories must be new. The script creates only synthetic Works/notes, with no
approval, installation or migration. `latency-fixture.json` records version, binary
SHA-256, backend, environment, volume and selected Work. Creation time is distinct
from query latency. Record the source revision/build identifier as well; the release
label alone is insufficient to distinguish this checkout from older 0.1.0 builds.
Measure fresh processes separately from repeated queries. In each dataset, repeat
`work show WRK-0064 --format json`, `work context WRK-0064 --format json`,
`next-actions WRK-0064 --format json`, `work list --open --format table` and
`status --format json`. Capture wall time, exit status and whether the command gives
feedback while waiting; avoid including terminal rendering time accidentally.
Record each sample, then compare median and tail latency. Vary volume afterward
(1/10/100 Works), using identical note counts and commands across both backends.
Record OS/CPU, package/JVM mode, protocol/database schema and source access settings.
Use no registered Git repositories first, then measure their contribution separately.
Do not mix migration, integrity repair, network/provider calls or fixture generation
into query timing. The current physical native verification used macOS arm64 and
GraalVM CE 25.5.5.0+3 with SQLite JDBC 3.54.1.0 / sqlite3 3.54.1; other machines need
their own recorded environment. WRK-000C remains OPEN until actual measurements and
responsiveness criteria justify its decision and implementation.
+609
View File
@@ -0,0 +1,609 @@
# Legacy file backend reference
This reference applies to the explicit legacy backend. New projects use SQLite.
For current persistence, gates and retention, read [the protocol](protocol.md).
When recreating legacy examples, add `--storage legacy` to init.
Legacy source documents retained by migration are not a second writable authority.
# Portable engineering protocol — schema 1
## Project root and configuration
The engineering root is the parent of `.ai-engineering`. Repository paths resolve
against that root, independently of the CLI's current directory. Discovery searches
upward or accepts an explicit `--project` root (or `.ai-engineering` directory).
An engineering project may be a simple source folder without Git, one Git repository,
or a workspace containing several repositories. All three use the same Work protocol.
Initialize directly in the folder that represents the desired project scope. An empty
`repositories: []` is valid; Works need no repository references to persist discussions,
decisions, artifacts and context. Git is invoked only when inspecting registered
repositories. Without repository references, a Work has no Git revision snapshots.
For a single Git repository at the engineering root, register it with `path: "."`
and `type: linked-git`. Registration remains explicit; initialization does not create
or register a Git repository. For multiple repositories, register their relative
subdirectory paths as in the example below.
```yaml
schemaVersion: 1
project:
id: prometeu
name: Prometeu
repositories:
- id: runtime
path: runtime
type: linked-git
language: rust
access:
read: true
edit: false
validationCommands: []
```
IDs use lowercase ASCII letters, digits and hyphens, beginning with a letter.
Repository types are `linked-git` and `git-submodule`. Omitted `access` defaults to
`read: true, edit: false`. If `access` is supplied its booleans are explicit; edit
requires read. Language is optional. `validationCommands` is optional metadata,
never executable through this release. Unknown fields and schema versions fail validation.
Absolute repository paths, `..` components, backslashes and symlinks beneath the root
are rejected, including links that point inside the root. This stricter initial rule
avoids ambiguous link policies. A linked Git repository may be the engineering root;
repositories cannot live inside `.ai-engineering`. Git inspection verifies the registered
path is a repository top-level;
submodule registration additionally verifies its superproject. Paths must exist.
No submodules are automatically created, moved or updated.
Policy controls protocol intent, not OS security. Concurrent malicious filesystem
replacement is outside this CLI's sandbox guarantee; use OS isolation for untrusted
processes. The adapter clears inherited `GIT_*` variables and disables optional Git locks.
## Work and files
```text
.ai-engineering/
ai-engineering.yaml
README.md # portable agent entry point
AGENTS.md # provider-neutral instructions
protocol.json # discovery manifest and capabilities
.gitignore
.local/write.lock # ignored, no semantic state
contracts/ # reserved for project contracts
works/
.sequence.yaml # canonical high-water mark; commit this
WRK-0001-improve-scene-editor/
work.md
epic/WRK-0001.md # present when epic: true
epic/.history/WRK-0001/r0001.md
discussions/DSC-0001.md
topics/TOP-0001.md
topics/.history/TOP-0001/r0001.md
surveys/SVY-0001.md
surveys/.history/SVY-0001/r0001.md
dispositions/DSP-0001.md
agent-runs/RUN-0001.md # canonical provenance; version this
decisions/DEC-0001.md
decisions/.history/DEC-0001/r0001.md
plans/PLN-0001.md
plans/.history/PLN-0001/r0001.md
artifacts/
references/
experiments/
evidence/ART-0001/
artifact.yaml
payload
outputs/
runs/ # ignored temporary execution outputs
```
`work.md`, discussion and decision files contain YAML front matter, delimited by
`---`. Work fields remain in front matter; trailing Work notes are noncanonical.
New discussion/decision narrative and plan descriptions use version 2 Markdown
bodies, with typed metadata in front matter. Legacy YAML-only discussions and draft
DECs remain readable without rewriting. There is no Java object serialization and no
dependency on conversation state.
Work fields: `schemaVersion`, `id`, `title`, `description`, `goal`, `motivation`,
`constraints[]`, `acceptanceCriteria[]`, `status`, `createdAt`, `updatedAt`, `author`,
`repositories[]`, `discussions[]`, `decisions[]`, `artifacts[]`, `plans[]`,
`completions[]`, `events[]`, `archived`, `topics[]`, `surveys[]`, `dispositions[]`,
`agentRuns[]`, `epic`. Operational, refinement and EPIC fields default to empty/false
when absent in older schema 1 Works. Updated CLI versions write them explicitly;
older CLI binaries that reject unknown fields cannot read these extended records.
Each repository snapshot
records `repositoryId`, relative `path`, exact `head` commit and `dirty`. An empty
repository records `UNBORN`, not an invented commit. Snapshots are taken at Work
creation and remain stable; they are not claims about later experiments.
Work IDs are project-wide, monotonic `WRK-` identifiers with an uppercase hexadecimal
suffix of four to nine digits: `WRK-0001` through `WRK-FFFFFFFFF`. The sequence passes
from `WRK-0009` to `WRK-000A`, then `WRK-000F` to `WRK-0010`. Zero is not a Work ID;
lowercase, `0x` prefixes and non-hexadecimal characters are rejected. Listing uses
numeric hexadecimal order, including when the width grows beyond four digits.
A persisted sequence reserves identity before publishing a Work; crashes may leave
gaps. New `.sequence.yaml` files use their own schema version 2:
```yaml
schemaVersion: 2
lastWork: "000A"
```
`lastWork` is the highest reserved hexadecimal suffix, written as a quoted uppercase
string. `"0000"` represents no reservation. Work records and project configuration
continue to use protocol schema version 1; the sequence file has an independent format.
Legacy schema version 1 counters with a decimal numeric `lastWork` remain readable.
Existing Work IDs, directory names and references are not renamed. Their suffixes
are interpreted as hexadecimal from this version onward. To protect prior reservations,
the legacy high-water mark is converted by identifier spelling: decimal counter 16
reserved `WRK-0016`, so it becomes hexadecimal `"0016"` (0x16), even if that Work was
removed. The next identifier is `WRK-0017`. This deliberately leaves any gaps below
that reservation unused. Read/validation commands do not rewrite legacy counters;
the next creation atomically writes version 2 under the project lock. Use the updated
CLI for hexadecimal IDs and version 2 sequence files.
Do not remove or rewind the sequence. Discussion/decision/artifact/plan IDs remain decimal and are **Work-local**;
their full identity is `(project, Work ID, child ID)`. Work reference arrays determine
history order. Directory names are a convenience; ID stability does not depend on title.
Duplicate Work IDs and directory/record mismatches fail validation.
Statuses: OPEN, ACTIVE, BLOCKED, COMPLETED, CANCELLED. `work status` changes an open
Work's state but cannot set COMPLETED. `work complete` records the evidence mapping
and explicit approval described below. Terminal or archived Works reject mutation
until `work reopen --by NAME --reason TEXT` returns them to ACTIVE. Reopening preserves
all prior completion records and lifecycle events. Nothing is irreversibly closed.
Legacy COMPLETED Works without completion evidence remain readable, but validation
diagnoses the missing record; reopen and record reviewed evidence before archiving.
`work update <ID>` explicitly refines `title`, `description`, `goal`, `motivation`,
`constraints[]` and `acceptanceCriteria[]`. Omitted fields retain their current values.
Repeated `--constraint` and `--acceptance` values replace the entire respective list;
`--clear-constraints` and `--clear-acceptance` explicitly empty them. Supplying values
and the corresponding clear option is invalid. A command with no fields is invalid.
Title, goal and individual list entries must be nonblank; description and motivation
can be cleared with an empty string.
Updates hold the project lock and atomically replace only Work metadata. ID, folder,
status, creator, creation time, repository revision snapshots and all child references
are preserved. `updatedAt` changes only when field values actually change; repeated
identical updates retain the original bytes and timestamp. Trailing noncanonical Work
notes are retained during metadata, status and child-reference updates. Updating a
Work neither approves a DEC nor changes its lifecycle status. Existing discussion and
decision records remain the history of how the scope was refined.
## Discovery and agent entry
The directory `.ai-engineering` identifies the protocol workspace. `init` installs
its README, instructions and `protocol.json`. The manifest declares schema, relative
entrypoint/configuration/Works paths, executable, startup commands, capabilities and
explicit human-attestation semantics. `onboard` installs or refreshes those files in
existing projects, without rewriting Work data. It also maintains a root `AGENTS.md`
block between `<!-- ai-engineering:start -->` and `<!-- ai-engineering:end -->`.
Rules outside that block remain byte-identical; replaced files have `.local` backups.
Ambiguous, duplicated or unclosed markers cause refusal. Repeated onboarding is a no-op.
Legacy projects with none of the three entry files remain valid. Partial installation,
malformed/duplicate JSON fields, unknown manifest versions and unsupported paths are
validation failures. `onboard` refreshes the contract while backing up changed files.
`work list`, `status`, and `next-actions` support `--format table|csv|markdown|json`.
Their default Markdown output is a table; `table` aligns columns for terminals,
and CSV provides UTF-8 comma-separated records with stable headers and RFC 4180
quoting/CRLF record endings. CSV emits no project preamble and keeps original
multiline field values. Empty results still have headers. JSON retains its full
existing records (`Work[]`, `ProjectStatus`, and `Action[]`, respectively).
Work table/CSV/Markdown columns are `id`, `title`, `status`, `archived`, `steps`,
`pending_actions`, `validation`, and `next_action` (human formats use display
labels). Progress counts COMPLETED steps over all registered steps across Plans,
including cancelled steps in the denominator. No steps means `0/0`; unreadable
Plan data means `unavailable`, with invalid validation and a repair suggestion.
Pending actions count deterministic suggestions, including execution and
maintenance; they are not solely blockers or semantic progress. The next command
is the first existing suggestion, without a new prioritization algorithm.
Action columns are `work_id`, `code`, `message`, and `command`. A project-level
action has an empty `work_id`. Markdown escapes cell text; terminal tables flatten
line breaks/control characters without truncating field values.
`work list --open` filters every format to nonterminal, unarchived Works: OPEN,
ACTIVE, and BLOCKED. Unfiltered Work lists continue to include archived Works.
Tabular formats apply to these three read commands only; other commands retain
their existing format choices. No storage or protocol revision is required.
An agent begins with the guide, status, next-actions and selected Work context. These
are portable instructions, not an LLM plugin or enforcement mechanism. Without the
CLI, an agent can inspect the files directly. Agents must still inspect the entry
files and respect project/user rules. Quoted protocol data and evidence do not gain
instruction authority. `guide` also works outside a project. `status` hides archived
Works by default (`--all` includes them); `next-actions [WRK]` returns deterministic
suggestions and never executes a repository action.
## Discussion and decisions
Each discussion entry has `schemaVersion`, `id`, `workId`, `discussionId` (thread name),
`kind`, `author`, `createdAt`, optional `respondsTo`, and `text`. Multiple threads can
coexist. Kinds: NOTE, QUESTION, RESPONSE, SUGGESTION, ASSUMPTION, HYPOTHESIS,
INVESTIGATION, ALTERNATIVE, ISSUE, CONCLUSION. Entries are appended, not rewritten.
Text is supplied by a human, external agent or explicitly labeled fixture adapter.
`discussion add` requires exactly one text source: `--text` for an inline string or
`--text-file` for a regular UTF-8 file up to 1 MiB. A file path resolves relative to
the caller's working directory, independently of `--project`. The entire file is
read as prose, without trimming, newline normalization or front-matter interpretation.
Nonblank content is required. Missing files produce exit 3; nonregular, malformed UTF-8,
blank or oversized input produces exit 2, with no appended discussion. The source is
not changed or retained as an external dependency: later edits/removal cannot alter
the persisted entry. File input does not implicitly register an evidence artifact.
New discussion files have `documentVersion: 2` in front matter and omit the `text`
field there. The complete Markdown body supplies `text`, including its original
headings, lists, tables, code blocks and whitespace:
```markdown
---
schemaVersion: 1
id: DSC-0002
workId: WRK-0001
discussionId: main
kind: SUGGESTION
author: agent
createdAt: '2026-11-11T16:47:32Z'
respondsTo: DSC-0001
documentVersion: 2
---
## Proposed approach
Use the next small, testable slice.
- State the limits.
- Identify supporting evidence.
```
One blank line separates the closing delimiter from the body; that formatting line
is excluded from `text`. All subsequent whitespace belongs to the prose. LF and CRLF
front matter are accepted; the reader does not normalize the body's line endings.
`schemaVersion: 1` still describes the protocol record. `documentVersion: 2` describes
this file representation, not a change to JSON context fields. Unknown document
versions and simultaneous YAML `text` plus a version 2 body fail validation.
Legacy discussions omit `documentVersion` (or declare 1) and keep canonical `text`
in YAML; their trailing body remains noncanonical notes. The new reader accepts both
representations without automatic writes. The old CLI cannot read document version 2.
`discussion migrate <Work>` explicitly converts legacy entries. Every discussion is
preflighted before any file is replaced. Nonblank legacy trailing notes cause refusal;
incorporate those notes into canonical text first. Original UTF-8 files are backed up
under `.local/backups/discussions/<Work>/<operation-id>/` before atomic replacement.
Migration preserves all semantic fields, Work timestamps and context JSON/Markdown,
and skips already converted entries. It changes formatting, not discussion history.
Interrupted migrations can be resumed; completed files are skipped and existing backups
are retained. This is per-file publication, not an all-or-nothing multi-file transaction.
A response must refer to an earlier entry in the same Work. Outstanding questions
include QUESTION and ISSUE entries without an explicit RESPONSE or CONCLUSION pointing
to them. This mechanical definition does not infer agreement or approval from prose.
DEC fields: `schemaVersion`, `id`, `workId`, `title`, `context`, `approach`,
`alternatives[]`, `rationale`, `risks[]`, `acceptanceCriteria[]`, `approvalStatus`,
`author`, `createdAt`, `evidence[]`, narrative `text`, `revision`, `previousHash`,
`updatedAt`, `updatedBy`, `changeReason`, `approvals[]`, optional `revises` and
`supersededBy`. Legacy draft fields default to revision 1, no approvals/links and
empty narrative. Narrative uses document version 2; the JSON `text` field remains explicit.
Statuses: DRAFT, ACCEPTED, REJECTED, SUPERSEDED. `decision update` changes only drafts,
recording actor/reason and a snapshot. Lists replace entire lists; explicit `--clear-*`
options clear them. `--text`/`--text-file` supplies narrative. Direct acceptance requires
nonblank context/approach/rationale, actor/reason and `--human-approved`. This flag is
an attestation that approval occurred, not authenticated identity or OS permission.
An agent cannot infer approval from a proposal or a prior status. Rejection retains
the proposal. `decision revise` creates a new draft linked to an accepted/rejected
DEC. Accepting that draft supersedes the prior accepted DEC, preserving both records.
Operational choices during execution remain distinct from these formal commitments.
Creating a Plan from a draft DEC is a separate deterministic acceptance route.
The framework records `origin: SYSTEM_PLAN`, the causal `planId`, actor
`system:planning` and `humanApproved: false`; it does not invent a direct human
attestation. Context, approach and rationale must still be nonblank. Referenced
drafts are promoted and their accepted predecessors are superseded with the same
Plan provenance. Already accepted DECs stay byte-identical; rejected/superseded
DECs and conflicting replacements cannot be used to create the Plan. Optional
approval `origin`/`planId` fields are absent on historical direct approvals, whose
meaning and serialization remain unchanged. Readers predating this capability
cannot read new system-promotion records; use the updated CLI, without rewriting
historical approvals.
## Topics, surveys and adapter runs
[Discussion refinement contracts](discussion-slice.md) specify TOP/SVY/DSP/RUN records,
questions, answers, sources and commands. These IDs are decimal and Work-local;
QST/ANS IDs are survey-local. Topic and survey revisions use the same SHA-256 history
convention as decisions/plans. Existing discussionId threads are implicit topic views,
including `main` for an empty Work, without canonical file changes.
Questions have a topic, suggestions, optional recommendation, single/multiple selection
and discussion sources. Free-text answers are always available. A revised answer
supersedes the prior one without deletion; only the latest determines pending status.
Revision signals a review and does not change accepted decisions/plans. Guided console
answering and noninteractive commands use the same persisted contract.
Project configuration can optionally include:
```yaml
agents:
general:
adapter: fixture-general
profile: fixture
model: deterministic
activities:
analyze:
adapter: fixture-reviewer
profile: fixture
model: deterministic
archivePolicy: review-only
```
Without agents configuration ordinary commands still work. Agent execution requires
an explicitly configured general. Unknown activities fall back to general; configured
specializations win. Fixture adapters and local codex-cli/claude-cli are available. An explicit
`reversible` policy permits archive with owned ART evidence and a reason; restore
preserves the source and disposition history. Questions/responses cannot be hidden
through proposal archive. Policies are metadata, not OS enforcement.
RUN records preserve request ID, raw task, requested/chosen activity, requester,
executor, sourceHash, fixture proposal bundle, applied references, status, error and
timestamps. Proposals have typed source links; `@request` in a proposal resolves to a
persisted raw Discussion NOTE. Framework checks validate output before application.
Adapters cannot generate survey answers or human approvals. Fixture analyses are
synthetic observations, never claims about a real experiment or investigation.
Source fingerprints include semantic project/Work/discussion/survey/evidence/decision/
plan state, excluding run bookkeeping and Work modification time. Context derives
staleness without invoking an adapter. A proposal-changing run can already be stale
against its own resulting state; sourceHash identifies the input it actually saw.
Identical completed request IDs replay the recorded result even if context later
changes; use a new ID for a new computation. Changed request input with the same ID
is invalid. Interrupted APPLYING records block further runs pending inspection;
FAILED records retain applied references. This is diagnostic publication, not rollback.
## Local provider executors
Executor adds optional timeoutSeconds, bounded 1–600; omission means 120 seconds.
Old records remain readable without writing. Null timeout/provenance fields are
omitted from serialized values so legacy fixture digests remain stable. Local CLI
profile/model names are constrained tokens, not arbitrary flags; default model omits
the provider flag. Profile is an AIE role instruction. Provider configuration profiles,
private session state and credentials do not become portable AIE configuration.
The [CLI adapter contract](cli-adapters.md) defines bounded process invocation,
required controls, versioned schemas, failure semantics and setup. Wire output cannot
set adapter/fixture identity or human authority. The normal complete proposal bundle
must validate before publication. RUN adds optional provenance with classification
and/or proposal invocation: transport, observed CLI version, configured role/model,
durationMillis, timeoutSeconds, outputSha256 and outputBytes. No raw environment or
stderr is canonical. A pre-publication transport failure leaves the Work unchanged.
General can classify a request into configured/common activities. Explicit activity
skips classification. Clarify requires a survey with suggestions and leaves human
answers pending. Prior RUN outputs are supplied as derived interpretations; source
fingerprints still follow canonical semantic sources. State/conformance/EPIC checks
never invoke a provider. Setup/doctor similarly never sends a model request.
## Plans and execution records
Plans are optional, proportional Work-local records (`PLN-0001`). A plan contains
title, Markdown description, referenced decisions, steps, lifecycle status, creator,
timestamps and revision metadata. Each step (`TSK-0001`, decimal and plan-local)
records title/description, acceptance criteria, dependencies, status, result, evidence
and modification time. Statuses match Work's five values but describe external work.
`plan create --decision DEC` promotes eligible DRAFT decisions without an adapter
or LLM. Guided Works require an explicit Work-wide human waiver; otherwise the DEC
needs human approval before Plan creation. Legacy Works retain prior promotion
semantics until explicit guidance adoption. Input, decision and revision-history validation runs
before promotion, under the project lock. Ordinary publication failures roll back
the attempted Plan and promotions. Publication is atomic per file, not a crash-proof
multi-file transaction: interrupted writes or failed recovery remain inspectable
with `work validate`. Validation checks the causal Plan's first revision, so later
Plan reference edits retain the original promotion provenance and cannot invent it.
Creating another Plan from an already accepted DEC does not add an approval.
`plan update` does not promote drafts; review its references before changing them.
Step dependencies must exist in that plan and be acyclic. Starting or completing a
step requires completed dependencies and accepted referenced decisions. Completion
requires result text (`--reason`) and owned evidence. `plan status COMPLETED` requires
at least one completed step and all required steps completed; cancelled steps need
explicit scope review with `plan exclude --step`. Exclusions retain the cancelled
record and bind its content hash, actor and reason. Legacy Plans remain readable
without rewriting. Reopen a terminal plan with
`plan status ACTIVE` before editing; reopen terminal steps before changing scope.
Reopening a prerequisite first requires reopening/cancelling its dependent steps.
If a DEC is superseded, reconsider the plan and update its references before execution.
Plan/step changes retain previous plan snapshots. `decision history` and `plan history`
walk `.history/<ID>/rNNNN.md`; `previousHash` links each revision to the complete prior
UTF-8 file. Validation checks identity, numbering and hashes. Hashes are integrity
links, not signatures: manual rewriting of an entire chain is not prevented. New
records start at revision 1. A snapshot published before an interrupted current-file
replacement can be reused only when identical; conflicting history is never overwritten.
The CLI does not execute steps, tests or validation-command metadata. Humans/agents
run real commands externally and record observations, commands, source revisions and
results in evidence. Plans support explicit adaptation; no autonomous OODA engine or
fixed four-phase pipeline is implemented.
## Completion, integration and archive
Works with executable Plans derive completion from those Plans. Mutation commands
and `work reconcile WRK` consolidate the last completed step into its Plan and
recheck all associated Plans. Completed required Plans and no pending questions,
surveys, draft DECs or explicit blocking states produce SYSTEM_PLANS completion,
without a model call, repeated human delivery approval or manual Work-level criterion
mapping. Empty sets never auto-complete; reviewed cancellations retain history.
New Plans after delivery require reopening. Unchanged old Plans do not immediately
close an explicitly reopened Work/Plan. See [Plan consolidation](plan-consolidation.md)
for records, provenance and recovery. `work check` reports consolidation pending
reasons; status/context/next-actions remain read-only. Existing EPIC authority and
policy continue to govern EPIC completion.
For inspection-only Works without Plans, `work check` checks mechanical readiness: explicit acceptance criteria,
no unresolved questions/issues or draft DECs, and terminal plans. Noncancelled plans
must reference currently accepted decisions. Small Works can close without a DEC/plan.
The check cannot determine whether arbitrary prose/evidence proves the desired outcome.
`work complete` requires human attestation, actor, summary and one unique
`--criterion N=ART-0001[,ART-0002]` mapping per criterion (1-based). Artifacts must
belong to the Work and pass integrity checks. Completion captures criterion text,
evidence IDs, approval metadata and a deterministic SHA-256 digest of scope, source
snapshots, discussion, decisions, plans and artifact metadata. Current COMPLETED Work
data must still match that digest. Reopened Works retain earlier snapshots as history.
Supply updated canonical project files via `--integration PATH` or explicitly state
`--no-integration-needed REASON`. Integration paths are safe project-relative regular
files outside `.ai-engineering`; their hashes identify contents at closure. Those
files can evolve later without invalidating a historical completion. The CLI records
the attestation/snapshot; it does not prove that the file changed or infer its meaning.
Canonical code/spec/test/docs hold integrated knowledge; no Lesson entity is required.
`work archive --by NAME --reason TEXT` marks a verified completed or cancelled Work
archived. It retains all files and prior approvals/results. `work reopen` clears
archive, returns to ACTIVE and appends a reasoned event. There is no automatic deletion.
`import discussion` imports DF DSCs with open AGDs using a read-only preview and
an explicit `--apply --expect` fingerprint. Independent `--source ID=PATH` origins
share one AIE destination; targets are described in their Works. Only open agendas
are imported as complete refinement notes and original evidence. Owned versioned
receipts preserve source+DSC identity, source hashes and references without changing
the Work schema. Identical reimports are no-ops; changes are reported for review.
Work publication is atomic per prepared directory, while a batch may be resumed
after partial publication. Closed agendas, DECs, Plans and Lessons are not imported.
See [the import contract](discussion-import.md) for limits, diagnostics and recovery.
## EPIC policy and system completion
[The EPIC contract](epics.md) defines topology, authority and recovery. An EPIC remains
a project Work, marked `epic: true`, with one versioned definition in its `epic/`
directory. Links use Work IDs, with important=true by default. Definitions preserve
mode, links, explicit authorization, editor/reason, revision and previousHash.
History follows the DEC/Plan snapshot convention. Initial topology is a forest.
RESULTS tracks verified important deliveries; optional children are reported without
blocking. Important CANCELLED remains pending. DECOMPOSITION uses ordinary reviewed
closure for the parent's own output and does not wait for execution. Empty important
sets never auto-close. Policy edits require an open parent and invalidate automatic
authority; `epic authorize --human-approved` binds the parent/important-child scopes
and current policy. Authorization is delegation for the structured aggregate condition,
not an inferred human approval of a future delivery.
Completion records add optional `origin` and `delegation`. Old records default to
HUMAN with no delegation and retain their digest semantics. HUMAN requires direct
humanApproved=true. SYSTEM_EPIC requires humanApproved=false, actor system:epic,
an actual policy authorization/history hash and request correlation. Its criteria map
to a framework-owned aggregate ART receipt containing policy/input and important-child
completion digests. The human's policy delegation attests that this condition suffices
for the parent criteria; the framework performs no semantic inference about prose.
Frozen RESULTS scope includes important completion records; optional execution can
continue independently. Important reopening reopens ancestors and clears their archive,
retaining prior completions. Explicit reopening of an EPIC suspends its authority for
replanning. Child-caused reopening preserves unchanged-scope authority. BLOCKED and
CANCELLED parents require explicit resumption. Nested propagation runs from descendants
to ancestors under the project lock, without calling any AgentAdapter.
Public CLI/Verification lifecycle APIs return the changed Work plus affected EPIC
reports when linked; plain Work output remains compatible. `--requester` and
`--request-id` correlate results. IDs correlate notifications rather than acting as a
global transaction log. `epic reconcile [WRK]` derives missed updates from canonical
files and does not duplicate a satisfied completion. A matching published receipt is
reused after interrupted completion. Invalid histories, missing children and orphan
publication are diagnosed; arbitrary corruption still needs deliberate repair.
Low-level storage callers must explicitly reconcile after lifecycle writes.
## Evidence and integrity
`artifact add` copies one regular file up to 1 MiB. Its manifest records schema, ID,
Work ID, origin, purpose, Work-relative payload path, SHA-256, byte size, author and UTC
creation time. The origin defaults to the source basename; use `--origin` for a useful
portable provenance reference. Payload bytes are exact. The fixed `payload` filename
avoids filename ambiguity; origin preserves the supplied source identity.
Validation checks required directories, IDs, schemas, repository references, child
ownership, missing records, orphan records and payload integrity. Evidence paths stay
inside the Work. Large resources should remain in their canonical location and be
described in discussion/reference files, rather than copied into this workspace.
`artifacts/outputs` is versionable for deliberately retained outputs; use ignored `runs/`
for large temporary results. No command creates large output files by default.
## Compatibility and evolution
`project compatibility` inspects actual stored formats and revisions without writes.
`protocol.json.schemaVersion` versions the manifest, while optional `protocolVersion`
versions the engineering contract (absent means the supported legacy baseline 1).
The diagnostic exposes the supported read/write format catalog separately from the
executable release. Old compatible records remain valid and readable without
normalization, including COMPLETED Works. `onboard` updates only entry instructions
and the manifest; a newer unsupported contract is never silently overwritten.
See [compatibility and evolution](compatibility.md) for public states, update guidance
and requirements for future explicit conversions. No required migration exists today.
## Context and continuity
`work context --format markdown|json` loads only canonical project/Work files. It
includes all Work fields (metadata separately in Markdown), stored source revisions,
ordered discussion history/conclusions, explicit decisions and approvals, plans/results, unresolved questions
and complete artifact references with integrity metadata. JSON has top-level
`schemaVersion`, `work`, `discussionHistory`, `decisions`, `outstandingQuestions`,
`artifacts`, `plans`, `protocolGuide`, `topics`, `surveys`, `dispositions`, `agentRuns`,
`agents`, `epic`, `parentEpic`. Completion and lifecycle history are included
in `work`. It does not embed arbitrary evidence payloads or all revision snapshots;
use history commands when prior versions are relevant.
No export timestamp, current absolute path or live Git state is injected. Unchanged
files yield byte-identical output across new instances and processes. Export rejects
broken references or integrity failures. It requires neither a model nor live Git
inspection; `project validate` separately verifies live repositories.
Markdown context renders discussion and decision prose directly, with IDs, authors,
timestamps and reply/approval metadata. Empty sections use `None recorded.`. JSON
keeps the complete typed records, including discussion `text`, regardless of their
on-disk document version. Evidence remains referenced rather than embedded.
## Write guarantees and recovery
Protocol mutations hold `.local/write.lock`, an OS lock released automatically at
process exit. Individual files publish atomically; create operations reject overwrites.
New project/Work/artifact directories are staged and renamed. Work sequence reservation
precedes directory publication to avoid identity reuse after interruption.
A child file/bundle is published before its reference is atomically added to `work.md`.
The filesystem is not a multi-file transactional database: interruption in that window
can leave an orphan, which validation reports. Inspect its metadata and either add its
ID to the Work reference array or remove it after review. Hidden `.tmp` directories are
incomplete staging outputs, ignored by readers; inspect and clean them manually after
an interrupted write. Concurrent manual editors do not honor the CLI lock. Directory
entry durability under sudden power loss depends on the host filesystem.
## Work guidance and OODA
Contract 3 adds optional typed Work guidance and Plan experiments. New Works ask
for human discussion mode and require human DEC approval by default; explicit
Work-wide waivers and requests retain human provenance. Guided operations enforce
the selected authority. See [Work conduct and adaptive implementation](work-guidance.md)
for commands, experiment criteria/results, affected execution and legacy behavior.
This preserves the existing loops and does not add a repository executor.
## Future contracts (design only)
- Additional AgentAdapter transports and execution permissions: local proposal-only
Codex/Claude CLIs are implemented; direct provider APIs, repository execution and
vendor-native configuration profiles need separate contracts and authorization.
- OODA iteration: identify Work and prior observations, orientation, operational
choices and attempts. Phases can repeat or be skipped; no four-stage workflow gate.
- Attempt: stable identity, hypothesis, input references, exact repository revisions,
granted permissions, invocation/environment, observations, outputs, result and
evidence references. Evidence and interpretation remain distinguishable.
- Coordinated execution: independent per-repository worktrees and commit records,
integrated validation, explicit authority for destructive actions, pushes and merges.
No claim of atomic commits across repositories.
- Conformance: evaluate explicit criteria against evidence and canonical code/spec/test
updates. No required Lesson artifact. Later schema changes require explicit migration.
+5 -2
View File
@@ -34,8 +34,11 @@ Receipts use origin `ai-engineering:plans:<receipt-sha256>`. Their input hash om
framework receipts so a published receipt can be reused after interruption. Final
completion freezes the full scope including the receipt. Recovery validates
integrity/history, consolidates Plans, publishes/reuses a receipt, records completion
and invokes existing EPIC reconciliation. Publication is atomic per file; malformed
or orphan records require explicit repair rather than silent deletion.
and invokes existing EPIC reconciliation. SQLite commits these related changes
together; legacy publication remains per-file. New receipts are structured facts in
SQLite. Required project/Work gates must pass for the current evaluated state;
temporary step inputs retire only after all Work checks and completion commit.
Malformed or orphan records require explicit repair.
Existing completed Works and legacy serialized hashes remain unchanged. New
optional fields are omitted when absent. Manual completion remains available for
+138 -592
View File
@@ -1,602 +1,148 @@
# Portable engineering protocol — schema 1
# Local engineering memory protocol
## Project root and configuration
AIE is a local framework per project. `.ai-engineering/aie.db` owns operational
memory: Works, investigation, decisions, Plans, execution facts and gate results.
Small YAML/JSON and README/AGENTS files bootstrap discovery and configuration.
There is no database server or background process. Git and source repositories are
optional; synchronization, distributed IDs, Git LFS and Work/DEC export are outside
this version.
The engineering root is the parent of `.ai-engineering`. Repository paths resolve
against that root, independently of the CLI's current directory. Discovery searches
upward or accepts an explicit `--project` root (or `.ai-engineering` directory).
## Starting and continuing
An engineering project may be a simple source folder without Git, one Git repository,
or a workspace containing several repositories. All three use the same Work protocol.
Initialize directly in the folder that represents the desired project scope. An empty
`repositories: []` is valid; Works need no repository references to persist discussions,
decisions, artifacts and context. Git is invoked only when inspecting registered
repositories. Without repository references, a Work has no Git revision snapshots.
Run `aie status`, `aie next-actions`, then `aie work context WRK-0001`.
The closest enclosing `.ai-engineering` owns the project. `--project PATH` selects
one explicitly. A SQLite workspace requires a compatible CLI; unavailable or
unreadable memory must be reported, never treated as an empty project.
For a single Git repository at the engineering root, register it with `path: "."`
and `type: linked-git`. Registration remains explicit; initialization does not create
or register a Git repository. For multiple repositories, register their relative
subdirectory paths as in the example below.
`init --name TEXT` defaults to SQLite and adds `/.ai-engineering/` to .gitignore.
`--version-state` leaves ignore policy to the developer without removing existing
rules. Existing tracked files are not untracked. `--storage legacy` is an explicit
compatibility option. Neither reads, `onboard`, nor installation migrate storage.
```yaml
schemaVersion: 1
project:
id: prometeu
name: Prometeu
repositories:
- id: runtime
path: runtime
type: linked-git
language: rust
access:
read: true
edit: false
validationCommands: []
Work IDs are uppercase hexadecimal (`WRK-000A`); child IDs are decimal and local to
their Work (`DEC-0001`, `PLN-0001`, `TSK-0001`). The database transaction reserves
new identities and owned references together. Migration preserves reserved gaps.
## Investigation and implementation
Discussion/investigation and implementation remain separate cycles connected by
DEC and Plan. Work stores scope, criteria and useful refinement; topics, surveys,
answer supersession and explicit conclusions preserve continuity. OODA is adaptive:
observe results, reconsider assumptions, decide and act. It is not a four-step
ritual imposed on every edit.
Ask for DIRECT or EXPLORATORY when unspecified. Only the human chooses/changes the
mode or ends exploration. Record choices with `work guidance --human-approved`;
exploratory DEC emission needs `work request-decision`. Human DEC approval is the
default. Direct mode does not waive it. An explicit Work-wide waiver is recorded
separately. Never infer approval from an adapter proposal or status label.
Accepted DECs are immutable; revisions/supersession retain their authority and
history. Plans require applicable accepted decisions and resolved discussion.
Steps have dependencies, criteria and results. Relevant experiments record their
hypothesis/criterion before execution and observations/interpretation afterward.
Failed hypotheses require reconsideration before retry; DEC concerns block affected
execution until the accepted replacement is referenced.
See [Work guidance/OODA](work-guidance.md), [refinement](discussion-slice.md) and
[Plan consolidation](plan-consolidation.md) for command details.
## Quality gates
Required project gates and additional Work gates are cumulative. A Work cannot
replace a project gate by reusing its local name. Define the procedure and relevant
input files/directories before evaluating it:
```sh
aie gate configure tests --title "Project tests" --procedure "./gradlew check" \
--input src --input build.gradle.kts --require-evidence --by owner
aie gate configure review --work WRK-0001 --title "Work review" \
--procedure "Review the DEC criteria" --input src --by owner
aie gate status WRK-0001 --format json
```
IDs use lowercase ASCII letters, digits and hyphens, beginning with a letter.
Repository types are `linked-git` and `git-submodule`. Omitted `access` defaults to
`read: true, edit: false`. If `access` is supplied its booleans are explicit; edit
requires read. Language is optional. `validationCommands` is optional metadata,
never executable through this release. Unknown fields and schema versions fail validation.
Obtain `evaluatedHash` before running the procedure externally. Attach required
small evidence with `artifact add`. Then record the actual result:
Absolute repository paths, `..` components, backslashes and symlinks beneath the root
are rejected, including links that point inside the root. This stricter initial rule
avoids ambiguous link policies. A linked Git repository may be the engineering root;
repositories cannot live inside `.ai-engineering`. Git inspection verifies the registered
path is a repository top-level;
submodule registration additionally verifies its superproject. Paths must exist.
No submodules are automatically created, moved or updated.
Policy controls protocol intent, not OS security. Concurrent malicious filesystem
replacement is outside this CLI's sandbox guarantee; use OS isolation for untrusted
processes. The adapter clears inherited `GIT_*` variables and disables optional Git locks.
## Work and files
```text
.ai-engineering/
ai-engineering.yaml
README.md # portable agent entry point
AGENTS.md # provider-neutral instructions
protocol.json # discovery manifest and capabilities
.gitignore
.local/write.lock # ignored, no semantic state
contracts/ # reserved for project contracts
works/
.sequence.yaml # canonical high-water mark; commit this
WRK-0001-improve-scene-editor/
work.md
epic/WRK-0001.md # present when epic: true
epic/.history/WRK-0001/r0001.md
discussions/DSC-0001.md
topics/TOP-0001.md
topics/.history/TOP-0001/r0001.md
surveys/SVY-0001.md
surveys/.history/SVY-0001/r0001.md
dispositions/DSP-0001.md
agent-runs/RUN-0001.md # canonical provenance; version this
decisions/DEC-0001.md
decisions/.history/DEC-0001/r0001.md
plans/PLN-0001.md
plans/.history/PLN-0001/r0001.md
artifacts/
references/
experiments/
evidence/ART-0001/
artifact.yaml
payload
outputs/
runs/ # ignored temporary execution outputs
```sh
aie gate record WRK-0001 project/tests --expect <evaluatedHash> \
--invocation "./gradlew check" --outcome PASS --summary "Observed checks passed" \
--evidence ART-0001 --by observer --observed
```
`work.md`, discussion and decision files contain YAML front matter, delimited by
`---`. Work fields remain in front matter; trailing Work notes are noncanonical.
New discussion/decision narrative and plan descriptions use version 2 Markdown
bodies, with typed metadata in front matter. Legacy YAML-only discussions and draft
DECs remain readable without rewriting. There is no Java object serialization and no
dependency on conversation state.
Work fields: `schemaVersion`, `id`, `title`, `description`, `goal`, `motivation`,
`constraints[]`, `acceptanceCriteria[]`, `status`, `createdAt`, `updatedAt`, `author`,
`repositories[]`, `discussions[]`, `decisions[]`, `artifacts[]`, `plans[]`,
`completions[]`, `events[]`, `archived`, `topics[]`, `surveys[]`, `dispositions[]`,
`agentRuns[]`, `epic`. Operational, refinement and EPIC fields default to empty/false
when absent in older schema 1 Works. Updated CLI versions write them explicitly;
older CLI binaries that reject unknown fields cannot read these extended records.
Each repository snapshot
records `repositoryId`, relative `path`, exact `head` commit and `dirty`. An empty
repository records `UNBORN`, not an invented commit. Snapshots are taken at Work
creation and remain stable; they are not claims about later experiments.
Work IDs are project-wide, monotonic `WRK-` identifiers with an uppercase hexadecimal
suffix of four to nine digits: `WRK-0001` through `WRK-FFFFFFFFF`. The sequence passes
from `WRK-0009` to `WRK-000A`, then `WRK-000F` to `WRK-0010`. Zero is not a Work ID;
lowercase, `0x` prefixes and non-hexadecimal characters are rejected. Listing uses
numeric hexadecimal order, including when the width grows beyond four digits.
A persisted sequence reserves identity before publishing a Work; crashes may leave
gaps. New `.sequence.yaml` files use their own schema version 2:
```yaml
schemaVersion: 2
lastWork: "000A"
```
`lastWork` is the highest reserved hexadecimal suffix, written as a quoted uppercase
string. `"0000"` represents no reservation. Work records and project configuration
continue to use protocol schema version 1; the sequence file has an independent format.
Legacy schema version 1 counters with a decimal numeric `lastWork` remain readable.
Existing Work IDs, directory names and references are not renamed. Their suffixes
are interpreted as hexadecimal from this version onward. To protect prior reservations,
the legacy high-water mark is converted by identifier spelling: decimal counter 16
reserved `WRK-0016`, so it becomes hexadecimal `"0016"` (0x16), even if that Work was
removed. The next identifier is `WRK-0017`. This deliberately leaves any gaps below
that reservation unused. Read/validation commands do not rewrite legacy counters;
the next creation atomically writes version 2 under the project lock. Use the updated
CLI for hexadecimal IDs and version 2 sequence files.
Do not remove or rewind the sequence. Discussion/decision/artifact/plan IDs remain decimal and are **Work-local**;
their full identity is `(project, Work ID, child ID)`. Work reference arrays determine
history order. Directory names are a convenience; ID stability does not depend on title.
Duplicate Work IDs and directory/record mismatches fail validation.
Statuses: OPEN, ACTIVE, BLOCKED, COMPLETED, CANCELLED. `work status` changes an open
Work's state but cannot set COMPLETED. `work complete` records the evidence mapping
and explicit approval described below. Terminal or archived Works reject mutation
until `work reopen --by NAME --reason TEXT` returns them to ACTIVE. Reopening preserves
all prior completion records and lifecycle events. Nothing is irreversibly closed.
Legacy COMPLETED Works without completion evidence remain readable, but validation
diagnoses the missing record; reopen and record reviewed evidence before archiving.
`work update <ID>` explicitly refines `title`, `description`, `goal`, `motivation`,
`constraints[]` and `acceptanceCriteria[]`. Omitted fields retain their current values.
Repeated `--constraint` and `--acceptance` values replace the entire respective list;
`--clear-constraints` and `--clear-acceptance` explicitly empty them. Supplying values
and the corresponding clear option is invalid. A command with no fields is invalid.
Title, goal and individual list entries must be nonblank; description and motivation
can be cleared with an empty string.
Updates hold the project lock and atomically replace only Work metadata. ID, folder,
status, creator, creation time, repository revision snapshots and all child references
are preserved. `updatedAt` changes only when field values actually change; repeated
identical updates retain the original bytes and timestamp. Trailing noncanonical Work
notes are retained during metadata, status and child-reference updates. Updating a
Work neither approves a DEC nor changes its lifecycle status. Existing discussion and
decision records remain the history of how the scope was refined.
## Discovery and agent entry
The directory `.ai-engineering` identifies the protocol workspace. `init` installs
its README, instructions and `protocol.json`. The manifest declares schema, relative
entrypoint/configuration/Works paths, executable, startup commands, capabilities and
explicit human-attestation semantics. `onboard` installs or refreshes those files in
existing projects, without rewriting Work data. It also maintains a root `AGENTS.md`
block between `<!-- ai-engineering:start -->` and `<!-- ai-engineering:end -->`.
Rules outside that block remain byte-identical; replaced files have `.local` backups.
Ambiguous, duplicated or unclosed markers cause refusal. Repeated onboarding is a no-op.
Legacy projects with none of the three entry files remain valid. Partial installation,
malformed/duplicate JSON fields, unknown manifest versions and unsupported paths are
validation failures. `onboard` refreshes the contract while backing up changed files.
`work list`, `status`, and `next-actions` support `--format table|csv|markdown|json`.
Their default Markdown output is a table; `table` aligns columns for terminals,
and CSV provides UTF-8 comma-separated records with stable headers and RFC 4180
quoting/CRLF record endings. CSV emits no project preamble and keeps original
multiline field values. Empty results still have headers. JSON retains its full
existing records (`Work[]`, `ProjectStatus`, and `Action[]`, respectively).
Work table/CSV/Markdown columns are `id`, `title`, `status`, `archived`, `steps`,
`pending_actions`, `validation`, and `next_action` (human formats use display
labels). Progress counts COMPLETED steps over all registered steps across Plans,
including cancelled steps in the denominator. No steps means `0/0`; unreadable
Plan data means `unavailable`, with invalid validation and a repair suggestion.
Pending actions count deterministic suggestions, including execution and
maintenance; they are not solely blockers or semantic progress. The next command
is the first existing suggestion, without a new prioritization algorithm.
Action columns are `work_id`, `code`, `message`, and `command`. A project-level
action has an empty `work_id`. Markdown escapes cell text; terminal tables flatten
line breaks/control characters without truncating field values.
`work list --open` filters every format to nonterminal, unarchived Works: OPEN,
ACTIVE, and BLOCKED. Unfiltered Work lists continue to include archived Works.
Tabular formats apply to these three read commands only; other commands retain
their existing format choices. No storage or protocol revision is required.
An agent begins with the guide, status, next-actions and selected Work context. These
are portable instructions, not an LLM plugin or enforcement mechanism. Without the
CLI, an agent can inspect the files directly. Agents must still inspect the entry
files and respect project/user rules. Quoted protocol data and evidence do not gain
instruction authority. `guide` also works outside a project. `status` hides archived
Works by default (`--all` includes them); `next-actions [WRK]` returns deterministic
suggestions and never executes a repository action.
## Discussion and decisions
Each discussion entry has `schemaVersion`, `id`, `workId`, `discussionId` (thread name),
`kind`, `author`, `createdAt`, optional `respondsTo`, and `text`. Multiple threads can
coexist. Kinds: NOTE, QUESTION, RESPONSE, SUGGESTION, ASSUMPTION, HYPOTHESIS,
INVESTIGATION, ALTERNATIVE, ISSUE, CONCLUSION. Entries are appended, not rewritten.
Text is supplied by a human, external agent or explicitly labeled fixture adapter.
`discussion add` requires exactly one text source: `--text` for an inline string or
`--text-file` for a regular UTF-8 file up to 1 MiB. A file path resolves relative to
the caller's working directory, independently of `--project`. The entire file is
read as prose, without trimming, newline normalization or front-matter interpretation.
Nonblank content is required. Missing files produce exit 3; nonregular, malformed UTF-8,
blank or oversized input produces exit 2, with no appended discussion. The source is
not changed or retained as an external dependency: later edits/removal cannot alter
the persisted entry. File input does not implicitly register an evidence artifact.
New discussion files have `documentVersion: 2` in front matter and omit the `text`
field there. The complete Markdown body supplies `text`, including its original
headings, lists, tables, code blocks and whitespace:
```markdown
---
schemaVersion: 1
id: DSC-0002
workId: WRK-0001
discussionId: main
kind: SUGGESTION
author: agent
createdAt: '2026-11-11T16:47:32Z'
respondsTo: DSC-0001
documentVersion: 2
---
## Proposed approach
Use the next small, testable slice.
- State the limits.
- Identify supporting evidence.
```
One blank line separates the closing delimiter from the body; that formatting line
is excluded from `text`. All subsequent whitespace belongs to the prose. LF and CRLF
front matter are accepted; the reader does not normalize the body's line endings.
`schemaVersion: 1` still describes the protocol record. `documentVersion: 2` describes
this file representation, not a change to JSON context fields. Unknown document
versions and simultaneous YAML `text` plus a version 2 body fail validation.
Legacy discussions omit `documentVersion` (or declare 1) and keep canonical `text`
in YAML; their trailing body remains noncanonical notes. The new reader accepts both
representations without automatic writes. The old CLI cannot read document version 2.
`discussion migrate <Work>` explicitly converts legacy entries. Every discussion is
preflighted before any file is replaced. Nonblank legacy trailing notes cause refusal;
incorporate those notes into canonical text first. Original UTF-8 files are backed up
under `.local/backups/discussions/<Work>/<operation-id>/` before atomic replacement.
Migration preserves all semantic fields, Work timestamps and context JSON/Markdown,
and skips already converted entries. It changes formatting, not discussion history.
Interrupted migrations can be resumed; completed files are skipped and existing backups
are retained. This is per-file publication, not an all-or-nothing multi-file transaction.
A response must refer to an earlier entry in the same Work. Outstanding questions
include QUESTION and ISSUE entries without an explicit RESPONSE or CONCLUSION pointing
to them. This mechanical definition does not infer agreement or approval from prose.
DEC fields: `schemaVersion`, `id`, `workId`, `title`, `context`, `approach`,
`alternatives[]`, `rationale`, `risks[]`, `acceptanceCriteria[]`, `approvalStatus`,
`author`, `createdAt`, `evidence[]`, narrative `text`, `revision`, `previousHash`,
`updatedAt`, `updatedBy`, `changeReason`, `approvals[]`, optional `revises` and
`supersededBy`. Legacy draft fields default to revision 1, no approvals/links and
empty narrative. Narrative uses document version 2; the JSON `text` field remains explicit.
Statuses: DRAFT, ACCEPTED, REJECTED, SUPERSEDED. `decision update` changes only drafts,
recording actor/reason and a snapshot. Lists replace entire lists; explicit `--clear-*`
options clear them. `--text`/`--text-file` supplies narrative. Direct acceptance requires
nonblank context/approach/rationale, actor/reason and `--human-approved`. This flag is
an attestation that approval occurred, not authenticated identity or OS permission.
An agent cannot infer approval from a proposal or a prior status. Rejection retains
the proposal. `decision revise` creates a new draft linked to an accepted/rejected
DEC. Accepting that draft supersedes the prior accepted DEC, preserving both records.
Operational choices during execution remain distinct from these formal commitments.
Creating a Plan from a draft DEC is a separate deterministic acceptance route.
The framework records `origin: SYSTEM_PLAN`, the causal `planId`, actor
`system:planning` and `humanApproved: false`; it does not invent a direct human
attestation. Context, approach and rationale must still be nonblank. Referenced
drafts are promoted and their accepted predecessors are superseded with the same
Plan provenance. Already accepted DECs stay byte-identical; rejected/superseded
DECs and conflicting replacements cannot be used to create the Plan. Optional
approval `origin`/`planId` fields are absent on historical direct approvals, whose
meaning and serialization remain unchanged. Readers predating this capability
cannot read new system-promotion records; use the updated CLI, without rewriting
historical approvals.
## Topics, surveys and adapter runs
[Discussion refinement contracts](discussion-slice.md) specify TOP/SVY/DSP/RUN records,
questions, answers, sources and commands. These IDs are decimal and Work-local;
QST/ANS IDs are survey-local. Topic and survey revisions use the same SHA-256 history
convention as decisions/plans. Existing discussionId threads are implicit topic views,
including `main` for an empty Work, without canonical file changes.
Questions have a topic, suggestions, optional recommendation, single/multiple selection
and discussion sources. Free-text answers are always available. A revised answer
supersedes the prior one without deletion; only the latest determines pending status.
Revision signals a review and does not change accepted decisions/plans. Guided console
answering and noninteractive commands use the same persisted contract.
Project configuration can optionally include:
```yaml
agents:
general:
adapter: fixture-general
profile: fixture
model: deterministic
activities:
analyze:
adapter: fixture-reviewer
profile: fixture
model: deterministic
archivePolicy: review-only
```
Without agents configuration ordinary commands still work. Agent execution requires
an explicitly configured general. Unknown activities fall back to general; configured
specializations win. Fixture adapters and local codex-cli/claude-cli are available. An explicit
`reversible` policy permits archive with owned ART evidence and a reason; restore
preserves the source and disposition history. Questions/responses cannot be hidden
through proposal archive. Policies are metadata, not OS enforcement.
RUN records preserve request ID, raw task, requested/chosen activity, requester,
executor, sourceHash, fixture proposal bundle, applied references, status, error and
timestamps. Proposals have typed source links; `@request` in a proposal resolves to a
persisted raw Discussion NOTE. Framework checks validate output before application.
Adapters cannot generate survey answers or human approvals. Fixture analyses are
synthetic observations, never claims about a real experiment or investigation.
Source fingerprints include semantic project/Work/discussion/survey/evidence/decision/
plan state, excluding run bookkeeping and Work modification time. Context derives
staleness without invoking an adapter. A proposal-changing run can already be stale
against its own resulting state; sourceHash identifies the input it actually saw.
Identical completed request IDs replay the recorded result even if context later
changes; use a new ID for a new computation. Changed request input with the same ID
is invalid. Interrupted APPLYING records block further runs pending inspection;
FAILED records retain applied references. This is diagnostic publication, not rollback.
## Local provider executors
Executor adds optional timeoutSeconds, bounded 1–600; omission means 120 seconds.
Old records remain readable without writing. Null timeout/provenance fields are
omitted from serialized values so legacy fixture digests remain stable. Local CLI
profile/model names are constrained tokens, not arbitrary flags; default model omits
the provider flag. Profile is an AIE role instruction. Provider configuration profiles,
private session state and credentials do not become portable AIE configuration.
The [CLI adapter contract](cli-adapters.md) defines bounded process invocation,
required controls, versioned schemas, failure semantics and setup. Wire output cannot
set adapter/fixture identity or human authority. The normal complete proposal bundle
must validate before publication. RUN adds optional provenance with classification
and/or proposal invocation: transport, observed CLI version, configured role/model,
durationMillis, timeoutSeconds, outputSha256 and outputBytes. No raw environment or
stderr is canonical. A pre-publication transport failure leaves the Work unchanged.
General can classify a request into configured/common activities. Explicit activity
skips classification. Clarify requires a survey with suggestions and leaves human
answers pending. Prior RUN outputs are supplied as derived interpretations; source
fingerprints still follow canonical semantic sources. State/conformance/EPIC checks
never invoke a provider. Setup/doctor similarly never sends a model request.
## Plans and execution records
Plans are optional, proportional Work-local records (`PLN-0001`). A plan contains
title, Markdown description, referenced decisions, steps, lifecycle status, creator,
timestamps and revision metadata. Each step (`TSK-0001`, decimal and plan-local)
records title/description, acceptance criteria, dependencies, status, result, evidence
and modification time. Statuses match Work's five values but describe external work.
`plan create --decision DEC` promotes eligible DRAFT decisions without an adapter
or LLM. Guided Works require an explicit Work-wide human waiver; otherwise the DEC
needs human approval before Plan creation. Legacy Works retain prior promotion
semantics until explicit guidance adoption. Input, decision and revision-history validation runs
before promotion, under the project lock. Ordinary publication failures roll back
the attempted Plan and promotions. Publication is atomic per file, not a crash-proof
multi-file transaction: interrupted writes or failed recovery remain inspectable
with `work validate`. Validation checks the causal Plan's first revision, so later
Plan reference edits retain the original promotion provenance and cannot invent it.
Creating another Plan from an already accepted DEC does not add an approval.
`plan update` does not promote drafts; review its references before changing them.
Step dependencies must exist in that plan and be acyclic. Starting or completing a
step requires completed dependencies and accepted referenced decisions. Completion
requires result text (`--reason`) and owned evidence. `plan status COMPLETED` requires
at least one completed step and all required steps completed; cancelled steps need
explicit scope review with `plan exclude --step`. Exclusions retain the cancelled
record and bind its content hash, actor and reason. Legacy Plans remain readable
without rewriting. Reopen a terminal plan with
`plan status ACTIVE` before editing; reopen terminal steps before changing scope.
Reopening a prerequisite first requires reopening/cancelling its dependent steps.
If a DEC is superseded, reconsider the plan and update its references before execution.
Plan/step changes retain previous plan snapshots. `decision history` and `plan history`
walk `.history/<ID>/rNNNN.md`; `previousHash` links each revision to the complete prior
UTF-8 file. Validation checks identity, numbering and hashes. Hashes are integrity
links, not signatures: manual rewriting of an entire chain is not prevented. New
records start at revision 1. A snapshot published before an interrupted current-file
replacement can be reused only when identical; conflicting history is never overwritten.
The CLI does not execute steps, tests or validation-command metadata. Humans/agents
run real commands externally and record observations, commands, source revisions and
results in evidence. Plans support explicit adaptation; no autonomous OODA engine or
fixed four-phase pipeline is implemented.
## Completion, integration and archive
Works with executable Plans derive completion from those Plans. Mutation commands
and `work reconcile WRK` consolidate the last completed step into its Plan and
recheck all associated Plans. Completed required Plans and no pending questions,
surveys, draft DECs or explicit blocking states produce SYSTEM_PLANS completion,
without a model call, repeated human delivery approval or manual Work-level criterion
mapping. Empty sets never auto-complete; reviewed cancellations retain history.
New Plans after delivery require reopening. Unchanged old Plans do not immediately
close an explicitly reopened Work/Plan. See [Plan consolidation](plan-consolidation.md)
for records, provenance and recovery. `work check` reports consolidation pending
reasons; status/context/next-actions remain read-only. Existing EPIC authority and
policy continue to govern EPIC completion.
For inspection-only Works without Plans, `work check` checks mechanical readiness: explicit acceptance criteria,
no unresolved questions/issues or draft DECs, and terminal plans. Noncancelled plans
must reference currently accepted decisions. Small Works can close without a DEC/plan.
The check cannot determine whether arbitrary prose/evidence proves the desired outcome.
`work complete` requires human attestation, actor, summary and one unique
`--criterion N=ART-0001[,ART-0002]` mapping per criterion (1-based). Artifacts must
belong to the Work and pass integrity checks. Completion captures criterion text,
evidence IDs, approval metadata and a deterministic SHA-256 digest of scope, source
snapshots, discussion, decisions, plans and artifact metadata. Current COMPLETED Work
data must still match that digest. Reopened Works retain earlier snapshots as history.
Supply updated canonical project files via `--integration PATH` or explicitly state
`--no-integration-needed REASON`. Integration paths are safe project-relative regular
files outside `.ai-engineering`; their hashes identify contents at closure. Those
files can evolve later without invalidating a historical completion. The CLI records
the attestation/snapshot; it does not prove that the file changed or infer its meaning.
Canonical code/spec/test/docs hold integrated knowledge; no Lesson entity is required.
`work archive --by NAME --reason TEXT` marks a verified completed or cancelled Work
archived. It retains all files and prior approvals/results. `work reopen` clears
archive, returns to ACTIVE and appends a reasoned event. There is no automatic deletion.
`import discussion` imports DF DSCs with open AGDs using a read-only preview and
an explicit `--apply --expect` fingerprint. Independent `--source ID=PATH` origins
share one AIE destination; targets are described in their Works. Only open agendas
are imported as complete refinement notes and original evidence. Owned versioned
receipts preserve source+DSC identity, source hashes and references without changing
the Work schema. Identical reimports are no-ops; changes are reported for review.
Work publication is atomic per prepared directory, while a batch may be resumed
after partial publication. Closed agendas, DECs, Plans and Lessons are not imported.
See [the import contract](discussion-import.md) for limits, diagnostics and recovery.
## EPIC policy and system completion
[The EPIC contract](epics.md) defines topology, authority and recovery. An EPIC remains
a project Work, marked `epic: true`, with one versioned definition in its `epic/`
directory. Links use Work IDs, with important=true by default. Definitions preserve
mode, links, explicit authorization, editor/reason, revision and previousHash.
History follows the DEC/Plan snapshot convention. Initial topology is a forest.
RESULTS tracks verified important deliveries; optional children are reported without
blocking. Important CANCELLED remains pending. DECOMPOSITION uses ordinary reviewed
closure for the parent's own output and does not wait for execution. Empty important
sets never auto-close. Policy edits require an open parent and invalidate automatic
authority; `epic authorize --human-approved` binds the parent/important-child scopes
and current policy. Authorization is delegation for the structured aggregate condition,
not an inferred human approval of a future delivery.
Completion records add optional `origin` and `delegation`. Old records default to
HUMAN with no delegation and retain their digest semantics. HUMAN requires direct
humanApproved=true. SYSTEM_EPIC requires humanApproved=false, actor system:epic,
an actual policy authorization/history hash and request correlation. Its criteria map
to a framework-owned aggregate ART receipt containing policy/input and important-child
completion digests. The human's policy delegation attests that this condition suffices
for the parent criteria; the framework performs no semantic inference about prose.
Frozen RESULTS scope includes important completion records; optional execution can
continue independently. Important reopening reopens ancestors and clears their archive,
retaining prior completions. Explicit reopening of an EPIC suspends its authority for
replanning. Child-caused reopening preserves unchanged-scope authority. BLOCKED and
CANCELLED parents require explicit resumption. Nested propagation runs from descendants
to ancestors under the project lock, without calling any AgentAdapter.
Public CLI/Verification lifecycle APIs return the changed Work plus affected EPIC
reports when linked; plain Work output remains compatible. `--requester` and
`--request-id` correlate results. IDs correlate notifications rather than acting as a
global transaction log. `epic reconcile [WRK]` derives missed updates from canonical
files and does not duplicate a satisfied completion. A matching published receipt is
reused after interrupted completion. Invalid histories, missing children and orphan
publication are diagnosed; arbitrary corruption still needs deliberate repair.
Low-level storage callers must explicitly reconcile after lifecycle writes.
## Evidence and integrity
`artifact add` copies one regular file up to 1 MiB. Its manifest records schema, ID,
Work ID, origin, purpose, Work-relative payload path, SHA-256, byte size, author and UTC
creation time. The origin defaults to the source basename; use `--origin` for a useful
portable provenance reference. Payload bytes are exact. The fixed `payload` filename
avoids filename ambiguity; origin preserves the supplied source identity.
Validation checks required directories, IDs, schemas, repository references, child
ownership, missing records, orphan records and payload integrity. Evidence paths stay
inside the Work. Large resources should remain in their canonical location and be
described in discussion/reference files, rather than copied into this workspace.
`artifacts/outputs` is versionable for deliberately retained outputs; use ignored `runs/`
for large temporary results. No command creates large output files by default.
## Compatibility and evolution
`project compatibility` inspects actual stored formats and revisions without writes.
`protocol.json.schemaVersion` versions the manifest, while optional `protocolVersion`
versions the engineering contract (absent means the supported legacy baseline 1).
The diagnostic exposes the supported read/write format catalog separately from the
executable release. Old compatible records remain valid and readable without
normalization, including COMPLETED Works. `onboard` updates only entry instructions
and the manifest; a newer unsupported contract is never silently overwritten.
See [compatibility and evolution](compatibility.md) for public states, update guidance
and requirements for future explicit conversions. No required migration exists today.
## Context and continuity
`work context --format markdown|json` loads only canonical project/Work files. It
includes all Work fields (metadata separately in Markdown), stored source revisions,
ordered discussion history/conclusions, explicit decisions and approvals, plans/results, unresolved questions
and complete artifact references with integrity metadata. JSON has top-level
`schemaVersion`, `work`, `discussionHistory`, `decisions`, `outstandingQuestions`,
`artifacts`, `plans`, `protocolGuide`, `topics`, `surveys`, `dispositions`, `agentRuns`,
`agents`, `epic`, `parentEpic`. Completion and lifecycle history are included
in `work`. It does not embed arbitrary evidence payloads or all revision snapshots;
use history commands when prior versions are relevant.
No export timestamp, current absolute path or live Git state is injected. Unchanged
files yield byte-identical output across new instances and processes. Export rejects
broken references or integrity failures. It requires neither a model nor live Git
inspection; `project validate` separately verifies live repositories.
Markdown context renders discussion and decision prose directly, with IDs, authors,
timestamps and reply/approval metadata. Empty sections use `None recorded.`. JSON
keeps the complete typed records, including discussion `text`, regardless of their
on-disk document version. Evidence remains referenced rather than embedded.
## Write guarantees and recovery
Protocol mutations hold `.local/write.lock`, an OS lock released automatically at
process exit. Individual files publish atomically; create operations reject overwrites.
New project/Work/artifact directories are staged and renamed. Work sequence reservation
precedes directory publication to avoid identity reuse after interruption.
A child file/bundle is published before its reference is atomically added to `work.md`.
The filesystem is not a multi-file transactional database: interruption in that window
can leave an orphan, which validation reports. Inspect its metadata and either add its
ID to the Work reference array or remove it after review. Hidden `.tmp` directories are
incomplete staging outputs, ignored by readers; inspect and clean them manually after
an interrupted write. Concurrent manual editors do not honor the CLI lock. Directory
entry durability under sudden power loss depends on the host filesystem.
## Work guidance and OODA
Contract 3 adds optional typed Work guidance and Plan experiments. New Works ask
for human discussion mode and require human DEC approval by default; explicit
Work-wide waivers and requests retain human provenance. Guided operations enforce
the selected authority. See [Work conduct and adaptive implementation](work-guidance.md)
for commands, experiment criteria/results, affected execution and legacy behavior.
This preserves the existing loops and does not add a repository executor.
## Future contracts (design only)
- Additional AgentAdapter transports and execution permissions: local proposal-only
Codex/Claude CLIs are implemented; direct provider APIs, repository execution and
vendor-native configuration profiles need separate contracts and authorization.
- OODA iteration: identify Work and prior observations, orientation, operational
choices and attempts. Phases can repeat or be skipped; no four-stage workflow gate.
- Attempt: stable identity, hypothesis, input references, exact repository revisions,
granted permissions, invocation/environment, observations, outputs, result and
evidence references. Evidence and interpretation remain distinguishable.
- Coordinated execution: independent per-repository worktrees and commit records,
integrated validation, explicit authority for destructive actions, pushes and merges.
No claim of atomic commits across repositories.
- Conformance: evaluate explicit criteria against evidence and canonical code/spec/test
updates. No required Lesson artifact. Later schema changes require explicit migration.
`--observed` attests an actual external check; it is not human DEC approval.
AIE does not execute the procedure or establish the semantic truth of a claim.
Results retain definition, invocation, scope/input fingerprint, moment, observer,
outcome and short summary. `gate history` exposes prior observations. Changed
inputs, Work scope/guidance, DEC revisions or gate definitions require evaluation
again. Plan/status bookkeeping does not invalidate the check.
Pending, failed or stale gates prevent manual, Plan and EPIC delivery. Completion
freezes references/hashes of the actual gate results in the same transaction.
Later source/policy changes do not invent checks on old deliveries; reopened work
requires applicable current results. Imported deliveries keep their historical
contract, without fabricated retroactive gates.
## Temporary inputs and outputs
`artifact add WRK --file PATH --purpose TEXT` copies a small input to the filesystem
with owned integrity metadata; bytes never become BLOB, base64 or file-shaped TEXT
in SQLite. Inputs remain available during dependent checks. Finishing a partial
step or gate alone does not mean all future Work checks have consumed an input.
At Work completion, integrity and completion facts commit before eligible payloads
are removed. AVAILABLE, DISCARD_PENDING and DISCARDED distinguish usable input,
interrupted cleanup and legitimate retirement. Current evaluations require available
inputs; a retired artifact cannot be reused after reopening. Historical queries
use the validated result, and missing input before evaluation remains an error.
`artifact recover WRK` finishes interrupted publication/retirement. Reads only expose
recovery actions. Publication journals identify owned residue; unknown files require
inspection. Adapter process workspaces are temporary and cleaned at execution end.
New Plan/EPIC receipts are structured facts, without an extra JSON file. Imported
originals and migration safety copies remain preserved until explicit disposition.
Requested documents/images/other deliverables belong at their output destination,
outside `.ai-engineering`; code stays in the source repository. AIE does not require
a permanent duplicate solely for auditing. Cleanup targets owned temporary copies,
never the source/deliverable.
## Persistence, consistency and recovery
SQLite uses foreign keys, WAL, FULL durability, IMMEDIATE writes and bounded writer
waits. Nested domain mutations share the transaction; related reads use a snapshot.
An OS publication lock coordinates writers with storage activation/rollback, with
bounded waits for SQLite commands. Backend changes during a wait require a retry.
Typed columns and ordered child rows retain domain data. Nullable historical lists
remain distinct from empty lists. Revision hashes reconstruct the relevant typed
representation or verify retained original bytes. Migration also compares original
representations to typed records, detecting changed historical rows.
RUN application is transactional on SQLite. Failure rolls back the whole proposal;
a separate failure record has a short diagnostic and no rolled-back applied refs.
Request IDs retain idempotence. Adapters cannot answer for humans, approve DECs,
complete Works or execute repository commands through this framework.
Legacy storage retains its per-file publication/recovery behavior. Supported legacy
records remain readable; [the legacy reference](legacy-file-storage.md) documents
those file formats. [Storage migration](storage-migration.md) is explicit, staged,
verified and recoverable. No consumer or installed executable is automatically
converted by a new build.
## Verification and closure
`project validate` checks the project, identities, graph, references, history and
integrity. `work validate` scopes checks to selected memory and its dependencies.
`work check` reports mechanical readiness, not semantic proof of prose criteria.
`status`, `next-actions` and context are read-only projections.
Required completed Plans consolidate through SYSTEM_PLANS receipts; RESULTS EPICs
still need explicit current authorization, and DECOMPOSITION remains reviewed.
Empty sets, open questions/experiments, unresolved DEC concerns and unfinished scope
remain pending. Cancelled content needs explicit scope review. Reopening preserves
history and does not immediately reconclude unchanged old Plans. Archive preserves
memory, not an obligation to retain every temporary file.
Exit codes: 0 success, 1 I/O/runtime, 2 invalid input, 3 missing resource, 4 validation
or readiness failure. Use command `--help` for exact options.
+12 -2
View File
@@ -28,7 +28,7 @@ and long proposals can be authored as ordinary Markdown files before persistence
Acceptance demonstration: initialize a project with two independent Git repositories,
create a Work referencing both, append discussion, persist a draft decision and
evidence, export context, then reconstruct the same context in independent processes
using only files. No framework state or model history may be required.
using persisted local memory and a compatible CLI. No process-local model history may be required.
Platform release targets: Linux x86_64, macOS ARM64, macOS x86_64 and Windows x86_64.
The workflow builds the three available GraalVM 25 platforms. **macOS x86_64 is blocked
@@ -89,7 +89,7 @@ completion requires explicit policy delegation, local readiness and valid import
deliveries; receipts distinguish system results from human delivery approvals.
Lifecycle commands propagate outcomes/reopenings and return a deterministic report.
Reconciliation recovers missed propagation from files without an LLM. Acceptance
Reconciliation recovers missed propagation from persisted state without an LLM. Acceptance
covers independent processes, repeated notification, policy/scope changes, history,
important/optional/cancelled children and native standalone execution. Actual observed
results are recorded in [experiments](experiments.md).
@@ -150,3 +150,13 @@ checks against evidence; identify impacted canonical specs, tests,
code and documentation; expose conformance checks to agents and CI. Acceptance: a Work
can demonstrate its outcome and preserve actionable knowledge without a mandatory
Lesson model or redundant documentation trail.
## Local SQLite memory
Implemented in WRK-000D: typed per-project SQLite memory, transactional domain
mutations, cumulative project/Work gates, temporary attachments and structured
receipts, snapshot reads, explicit recoverable legacy migration and default Git
ignore policy. Native AIE/JDBC/sqlite3 packaging is prepared and verified; actual
installation and consumer migration remain deferred. The latency ticket WRK-000C
remains open for separate measurement. Work/DEC sharing, distributed sync,
Git LFS and backup/export are future discussions.
+421
View File
@@ -0,0 +1,421 @@
# SQLite persistence: legacy mapping and migration cases
This is the implementation map for WRK-000D / DEC-0001 / PLN-0001, starting with
TSK-0001. It describes the inspected file backend and the invariants the SQLite
implementation must preserve. The implementation sections below record the completed SQLite integration; the
source inventory also documents the supported legacy backend.
The active CLI and this repository's canonical `.ai-engineering` remain on the file
backend. Native installation, replacement of active binaries/libraries/shortcuts,
and migration of consumer projects are deferred by explicit human instruction.
Implementation and verification use fixtures, disposable copies and build outputs.
## Persistence boundary
One SQLite database, `.ai-engineering/aie.db`, will own a local project's Work
memory. Keep discovery/configuration/agent entry files small and explicit where
bootstrap needs them. A file named `aie.db` alone does not establish that migration
completed or that the installed CLI can read its schema.
Store domain fields and relationships, not files encoded as BLOB, base64 or a large
TEXT document. Ordered child data belongs to typed dependent rows; constrained
operational structures may use an explicit codec when they are not independently
queried. Do not put every aggregate into a serialized `work.md` column.
Generated contexts, readiness/evaluation reports, suggested actions and freshness
flags are projections, not additional authorities. Rebuild them from the applicable
records in a consistent read transaction. File payloads remain outside SQLite.
## Source-to-target inventory
Table names below identify logical groups for the schema step, not a final SQL
migration. Preserve ordered lists and nullable/omitted historical values where they
affect interpretation or digests. Do not change externally visible identities.
| Source and owner | Domain data to preserve | Target groups and invariants |
|---|---|---|
| `ai-engineering.yaml`; `ProjectService`, `ProjectConfig` | Project identity/name; repositories, paths/type/language/access/validation commands; general/activity adapters, profile/model/timeout and archive policy | Bootstrap configuration and typed configuration records; one authority per field. Empty repositories are valid. Repository access defaults to read-only. A source repository is optional. |
| `protocol.json`, entry README/AGENTS; `ProtocolGuide`, `ProtocolContract` | Contract/schema versions, capabilities, startup and managed instruction boundaries | Explicit storage/schema discovery and compatibility. Preserve external project rules. Unsupported contracts fail before writes. `onboard` is not data migration. |
| `works/.sequence.yaml`; `WorkService.Sequence` | Highest reserved Work number, including gaps | Transactional project-local allocation. Preserve legacy high-water interpretation; never recompute solely from surviving Works or rename decimal-looking historical IDs. |
| `work.md`; `Work` | ID, title, description, goal, motivation, ordered constraints/acceptance criteria, status, timestamps, author, repository revisions and all child references | `works`, ordered scope/revision rows and owned references. A Work ID is project-wide; `(work_id, child_id)` identifies a Work-local child. Preserve terminal/editability/archive/reopen semantics. |
| Work guidance; `WorkGuidance` | Mode, approval policy, explicit choice history and decision requests, with actor/reason/time/human attestation | Guidance/choice/request rows. Absence in a historical Work differs from newly UNSPECIFIED guidance. Only recorded human instructions change authority. |
| Work completion/events; `Work.Completion` | Criterion texts and evidence references; scope hash, integrations, summary, origin, delegation/aggregation, actor/time and lifecycle events | Completion/criterion/integration/event rows. Preserve HUMAN, SYSTEM_EPIC and SYSTEM_PLANS provenance, not just COMPLETED status. Do not invent approval during migration. |
| `discussions/DSC-*.md`; `DiscussionEntry` | Work/thread/topic, kind, author/time, exact narrative, optional earlier response target | Discussion entries and response edges in source order. QUESTION/ISSUE remains pending until an explicit linked RESPONSE/CONCLUSION. Preserve UTF-8, Markdown and whitespace. |
| `topics/TOP-*.md`, `.history`; `TopicService` | Title/description, ordered source discussion IDs, revision/hash/editor/reason/time | Topic/current revision/source rows. Legacy threads remain implicit topic views, without fabricated formal topic history. |
| `surveys/SVY-*.md`, `.history`; `SurveyService` | Questions/options/recommendation/multiple flag/topic/sources; every answer, selected choices, author/time and supersedes link | Survey/question/option/answer/choice rows and revision provenance. Recommendations are not answers. Superseded answers remain available; latest answer determines pending state. |
| `dispositions/DSP-*.md`; `DispositionService` | Target entry, ARCHIVE/RESTORE, reason/evidence, author/time | Owned disposition/evidence references. Archive remains subject to the configured policy; restore does not delete the original proposal. |
| `decisions/DEC-*.md`, `.history`; `DecisionService` | Narrative/context/approach/rationale, alternatives/risks/criteria/evidence, approval status/history, revisions and revises/supersededBy | Decision/revision/approval/list/reference rows. DIRECT and SYSTEM_PLAN approval provenance stay distinct; preserve causal Plan IDs and no-human-attestation semantics of permitted system promotion. |
| `plans/PLN-*.md`, `.history`; `PlanService` | Narrative, decisions, steps and ordered criteria/dependencies/results/evidence; status/revisions; scope exclusions; experiments | Plan/revision/step/dependency/exclusion/experiment rows. Excluding cancelled scope does not satisfy a dependency; completed steps still require results and applicable checks. |
| Plan experiments; `Experiment` | Hypothesis, criterion, invocation, step, author/time; observed outcome, interpretation/next action/evidence, retry/reconsideration, questioned DEC | Experiment/result/reference rows. Criteria precede results; failed retries require reconsideration. Open experiments and unresolved DEC concerns continue to block affected execution. |
| `epic/WRK-*.md`, `.history`; `EpicService` | RESULTS/DECOMPOSITION, ordered children/importance, revision/hash, explicit scope-bound authorization | EPIC policy/revision/link/authorization rows. Enforce existing forest topology, one parent, no cycles and no authorization inferred from status. |
| `agent-runs/RUN-*.md`; `AgentService`, `AgentRun` | Request identity/task/activity/requester/executor/source hash; APPLYING/COMPLETED/FAILED, typed proposal, applied references, diagnostic and invocation provenance | Run/proposal/applied-reference/invocation rows. Preserve idempotency and interrupted publication diagnostics; do not retain raw transport, environment or credentials. |
| `artifacts/evidence/ART-*/artifact.yaml`; `ArtifactService` | Work-local identity, origin/purpose/path, SHA-256, size, author/time | Artifact metadata and references. New temporary evidence needs explicit lifecycle state. Payload bytes are external; their absence is not success unless legitimate post-check disposal is recorded. |
| Plan/EPIC completion and DF-import receipt payloads | Typed receipt identity, inputs, referenced source revisions/hashes and producer provenance | Typed internal receipt/source rows. These are protocol state; parse only recognized owned receipts, not arbitrary user payloads. Preserve legacy payload/representation provenance when required. |
| `runs/`, `artifacts/outputs`, references and experiment files | Temporary execution files, requested deliverables and external references | Filesystem lifecycle/paths only when needed. A RUN record differs from the ignored `runs/` folder. Do not promote every generated file into permanent evidence. |
### Current gate boundary
`ProjectConfig.Repository.validationCommands` describes repository validation
commands. The legacy baseline did not expose a complete project-level and
per-Work gate-result catalog; QualityGates now supplies that contract in SQLite. Completion enforces mechanical protocol checks,
recorded results and owned evidence; it does not itself execute those commands.
TSK-0007 adds the project gate baseline and Work additions while preserving this
execution boundary. A historical COMPLETED label or an ART reference is not proof
that a newly introduced gate was executed. Imported approvals retain their original
meaning; new gate results must record actual observations of the applicable state.
## Hashes and historical representations
There are several distinct digests, with different source material:
1. **Revision chain:** `Revisions.chain` hashes the preceding file's exact UTF-8
content. Parsing and reserializing YAML can change bytes without changing the
domain object. Keep the original source representation/provenance available
for legacy chain checks; never replace a historical hash with a new one merely
to make import pass. Retained migration originals stay outside database TEXT.
2. **Work completion scope:** `VerificationService.scopeHash` hashes deterministic
JSON of selected domain fields and ordered child records. Optional legacy
fields are conditionally omitted. Do not normalize missing guidance to a new
choice, add optional empty collections to old digest inputs, or reorder lists.
3. **Plan/EPIC receipt sources:** source Plan revisions and child completions bind
to their semantic digests and producer/authority metadata. Importing a receipt
does not authorize re-completion, reevaluation or a new human approval.
4. **Artifact integrity:** SHA-256 is over exact payload bytes; retain size/path
ownership checks and the distinction between a user file and a protocol receipt.
5. **Adapter and import fingerprints:** preserve source fingerprints, request IDs
and import source identities. An identical retry is not a new Work or RUN;
changed input with the same identity requires existing rejection/review rules.
Storage schema, manifest schema, protocol contract and Markdown document versions
are separate. Existing record schema is 1, Work sequence reads versions 1/2,
narrative Markdown reads document versions 1/2 and protocol contracts read 1/2/3.
A new SQLite schema does not mean historical documents were rewritten.
## Unit-of-work and file lifecycle map
| Operation | Records that must publish coherently | External boundary |
|---|---|---|
| Create Work | Reserved high-water and initial identity/guidance | Bootstrap and legacy source discovery; no ID reuse on retry |
| Add discussion/answer | Entry or revised survey, source links and Work references/timestamp | No implicit evidence attachment or human answer |
| Accept/revise/supersede DEC | Approval and revision, replacement links and affected references | Preserve immutable accepted content and causal authority |
| Create/update Plan or finish step | Eligible decision promotion, Plan revision, step/result/evidence references | Evidence must be available and valid during dependent checks |
| Apply agent proposal | RUN state, typed proposals/applied references and resulting records | Provider call stays outside a write lock; recheck source state before application; preserve idempotent retry |
| Complete Plan/Work or coordinate EPIC | Source revisions, internal receipt, completion and applicable propagation | No automatic completion from an empty set; retain reopen/authorization rules |
| Retire temporary evidence | Completed dependent checks, minimal result and legitimate disposal state | File deletion follows committed result/disposal intent; interruption is recoverable; requested outputs are protected |
| Migrate file backend | Imported rows, mapping/provenance and activation state | Stable source snapshot, migration safety copy and staged database; never switch before verification |
Keep local write transactions short; provider calls and external quality commands
must not hold the database write lock. A read of related context uses one coherent
view. Waits have a duration limit and an actionable diagnostic.
File publication and removal are not SQLite transactions. Define interruption
cases explicitly: unreferenced staged file; committed reference with missing input;
committed checked result pending cleanup; process interrupted before completion.
Only the third case is eligible for post-check disposal. Removing one evidence
file must consider every dependent check, including other Plans or Work completion.
## Representative corpus and expected outcomes
Use the existing resource bytes and workflow builders. All mutations below are
against temporary copies/projects. Do not regenerate frozen resources with the new
writer to obtain expected values.
| Corpus/case | Existing source | Required result of future migration/SQLite checks |
|---|---|---|
| Frozen pre-contract delivered Work | `src/test/resources/compatibility/baseline-v1/.ai-engineering`; `CompatibilityTest` | Keep 9 original files unchanged, implicit contract 1 and sequence schema 1 readable, accepted DEC plus draft history, legacy defaults and exact frozen scope hash. SQLite import yields equivalent meaning without rewriting or reopening the source. |
| Missing optional refinement/guidance | `CompatibilityTest`, `RefinementSafetyTest`, `WorkGuidanceTest` | Interpret defaults in memory; no invented mode, waiver, answer or approval. New guided Works still require human choices. |
| Current refinement/history | `DiscussionRefinementTest`, `RefinementSafetyTest`, `DiscussionMarkdownTest` | Preserve UTF-8/body text, response links, implicit/formal topics, all survey answers and latest-answer semantics, reversible dispositions. |
| DEC and Plan authority | `WorkGuidanceTest`, `PlanDecisionPromotionTest`, `OperationalSafetyTest` | Preserve direct versus system approvals, exact causal links, accepted-content immutability, revised decision blocking and Plan authority. |
| Plan consolidation/recovery | `PlanConsolidationTest`, `PlanConsolidationSafetyTest` | Preserve actual completed Plan sources, exclusions, incomplete scopes, existing receipt reuse, reopen semantics and pending questions. Tampered evidence fails before the step write. |
| EPIC delegation/history | `EpicWorkflowTest`, `EpicSafetyTest` | Keep important/optional children, authorization invalidation, nested forest and historical hashes; reproduce recovery without duplicating completions. |
| Import receipts and colliding source-local IDs | `src/test/resources/discussion-import/alpha`, `beta`; `DiscussionImportTest`, `legacyimport/DiscussionImportRecoveryTest` | Preserve stable source identity and original evidence; distinguish sources that reused DSC IDs; identical reimport/recovery does not duplicate Works or overwrite changed inputs. |
| Fresh processes without Git | `ProcessContinuityTest`, `scripts/native-smoke.sh` | Reconstruct the same memory in a new process without Git installed; preserve source files and avoid a server dependency. |
| Evidence missing/tampered before check | `IntegrityTest`, `PlanConsolidationSafetyTest` | Reject size/hash/path/ownership failures and do not publish successful checks. |
| Explicitly retired temporary evidence | New scenario in TSK-0008/0009 | Check while present, persist minimal result, retire only after all consumers finish; historical queries remain valid; pending consumers prevent deletion. This behavior is not implemented in the current backend. |
| Unsupported versions/unknown fields | `CompatibilityTest`, `OperationalSafetyTest` | Reject malformed, future or inconsistent records before activation; a current manifest cannot hide unsupported history; preview does not modify source. |
| Traversal, symlink, foreign ownership | `IntegrityTest`, `RefinementSafetyTest`, `EpicSafetyTest` | Refuse unsafe paths/identities without reading a symlink target, leaking its contents or publishing partial records. Apply the same boundary to database and sidecar paths. |
| Interrupted conversion/retry | New scenario in TSK-0010; existing import recovery pattern | Fail before activation, retain usable legacy state, expose recovery state and retry without duplicate IDs/approvals/completions. Two usable writers must not become independent authorities. |
| Local concurrent writers/rollback | New scenario in TSK-0003 | Enforce ownership/foreign keys and whole-operation rollback; no duplicate allocated identity; bounded lock contention. Multi-machine reconciliation is out of scope. |
### Frozen anchors
The frozen baseline's expected completed Work scope hash is
`72d5803add0b8714d7dc4bf7e63ad55cc3259df910aa8b03790657eac4c2bd02`.
Its accepted DEC is revision 2; `previousHash` and the original draft's byte digest
are `545dc8e36da222fdeaf9458f77880bf2d1842738b82bac5296cddf62452a7e01`.
The ART-0001 payload digest is
`98545564d0747210b91b933bf8554c4b7e36ba878e6662cb48156b08ff74e1ee`.
These anchors were inspected from existing resources, not generated by SQLite.
## Mapping to implementation steps
- TSK-0002/0003 establish the driver, native loading, schema and unit of work.
- TSK-0004/0005 map investigation and implementation records while retaining authority.
- TSK-0006 maps RUNs, source fingerprints and deterministic coordination/receipts.
- TSK-0007/0008 add gate records and temporary evidence lifecycle.
- TSK-0009 builds projections without repeated unrelated reads.
- TSK-0010 exercises the corpus before any activation and implements public migration.
- TSK-0011 declares storage compatibility and initializes local ignored state.
- TSK-0012 prepares the distribution with disposable installer fixtures only.
- TSK-0013 updates public operational documentation once the commands exist.
- TSK-0014 verifies the integrated result and hands a reproducible workload to WRK-000C.
This mapping does not change DEC authority, weaken a gate or authorize installation.
Successful legacy tests characterize the source backend; they do not yet prove
equivalence of a SQLite importer. Future steps must exercise these same expectations
through the implemented database path.
## Driver and Native Image proof (TSK-0002)
The selected candidate is `org.xerial:sqlite-jdbc:3.54.1.0` (SQLite 3.54.1).
`src/sqliteProbe` is a build-only entry point, separate from the installed CLI and
project discovery. `sqliteProbe` exercises create/read/write/rollback/reopen in a
JVM; `nativeSqliteProbeCompile` builds the same entry point with its JNI library
exported beside the executable. The native binary explicitly selects a GraalVM
Java 25 toolchain; selecting the Gradle JVM alone did not select the correct
Native Image launcher in the first local build attempt.
Example disposable verification, using the repository's pinned GraalVM:
```sh
mkdir -p build/sqlite-probe/disposable
./gradlew sqliteProbe -PprobeDatabase=build/sqlite-probe/disposable/proof.db
./gradlew sqliteProbe -PprobeDatabase=build/sqlite-probe/disposable/proof.db
./gradlew nativeSqliteProbeCompile
bash scripts/sqlite-probe.sh /absolute/path/to/build/native/nativeSqliteProbeCompile/aie-sqlite-probe
```
The shell proof creates its own temporary database and starts separate native
processes, checks a UTF-8 value and rollback, disables temporary-library extraction
and verifies that an isolated executable fails when its companion library is absent.
These are build/driver checks; they do not install the native application, activate
the database backend or establish the end-to-end latency of the AIE CLI.
## Transaction foundation (TSK-0003)
`SqliteDatabase` now provides explicit initialization and command-scoped read/write
transactions. Opening a missing database does not create files. Its application ID,
`user_version` and schema metadata must agree before domain operations proceed.
Initialization uses WAL with FULL synchronization; connection foreign keys are
enabled explicitly, and writer transactions begin IMMEDIATE with a bounded busy
timeout (2 seconds by default).
Nested operations share their connection. A nested failure makes the enclosing
write rollback-only even if its caller catches the exception. Read transactions
use a read-only SQLite connection and cannot be upgraded implicitly to writes.
Related reads retain a stable snapshot while another local writer commits.
`sqlite/schema-v1.sql` establishes the ownership/revision/reference keys and local
identity high-water marks. Domain field tables will be integrated in TSK-0004
through TSK-0007; the foundation does not yet route the CLI's Works to SQLite.
References are deferred until commit so related revisions can publish together.
Missing target ownership aborts the transaction. Database and sidecar symlinks,
nonregular paths and orphan sidecars during initialization require inspection.
`SqliteDatabaseTest` covers initialization, path encoding, rollback, foreign keys,
nested failures, read-only access, snapshot consistency, writer contention,
unsupported schemas and filesystem boundaries. The build-only native probe also
creates and reopens the foundation schema, verifying its resource loading and
transaction entry points in Native Image without installing the application.
## Investigation record integration (TSK-0004)
`ProjectService.initializeSqlite` is the explicit backend entry point used by
disposable integration projects. The public `init` default is still the legacy
backend until the storage-contract/initialization step. Existing projects are not
converted by the presence of an arbitrary database file: the bootstrap configuration
must explicitly select SQLite.
`SqliteRecords` maps record scalar fields to typed columns in domain-specific
tables. Ordered fields use dependent tables and ordinals; structured operational
items (such as an answer or completion) have an explicit JSON representation per
item, not a serialized source document or entire Work. Work-owned references also
bind to the shared revision identity keys. Tables/columns come from trusted domain
record definitions, while identities and values use bound SQL parameters.
`RecordStorage` adapts the existing record codec and revision operations without
placing canonical Markdown files in SQLite projects. New revision hashes bind to
deterministic materializations of the typed record; migration can retain original
source paths/digests for legacy representations. `WorkService` loads a selected
Work by identity, allocates IDs transactionally and preserves its folder location
when the title changes. Discussions, topic revisions, survey/answer history and
dispositions use the same transaction as their Work references.
Integration checks cover rejected publication rollback, missing owned references,
concurrent local allocation, selecting one Work without parsing an unrelated broken
record, UTF-8 and explicit guidance/decision requests. A fresh JVM reconstructs
discussion/survey context, and the native probe creates and reopens a Work and its
discussion in separate processes using the application's AOT metadata. These checks
do not yet migrate DECs, Plans or the active workspace to the new backend.
## Decision and Plan integration (TSK-0005)
Decisions, approvals, supersession and Plan/experiment revisions now use the typed
record adapter. SQLite Plan creation publishes permitted draft promotions, the
Plan and its Work reference in one transaction. The legacy backend retains its
file-publication recovery path; SQL publication does not compensate by writing
Markdown files. A requested rollback of a prepared SQL promotion marks the whole
unit of work rollback-only.
The existing domain checks still enforce pending discussion, approval policy,
accepted decision references, step dependencies, experiment outcomes and required
owned evidence. Artifact metadata is mapped into SQLite as foundational support
for these checks; payloads remain files and are still retained at this step. The
temporary-artifact lifecycle and disposal policy belong to TSK-0008.
`SqliteImplementationTest` covers human acceptance and immutability, atomic system
promotion rollback/retry under an explicit fixture waiver, supersession and Plan
reconsideration, dependencies, owned evidence and the OODA experiment/retry loop.
Existing file-backend authority, promotion and experiment tests remain applicable.
### TSK-0006 — RUNs e coordenação
RUNs e políticas de EPIC usam registros tipados no SQLite. Idempotência e
fingerprints continuam derivados do contexto; a aplicação de propostas é uma
transação. Uma falha reverte todo o bundle e publica, em transação posterior,
somente o RUN falho com diagnóstico e referências aplicadas vazias. Não há
transporte bruto ou logs no banco. A coordenação conserva os recibos existentes
até a integração de seu ciclo de vida no TSK-0008.
Verificação: 30 cenários distintos de SqliteCoordinationTest, EpicWorkflowTest,
EpicSafetyTest, RefinementSafetyTest e ArchitectureTest passaram, incluindo
idempotência, falha intermediária via trigger SQL, RESULTS/DECOMPOSITION,
aprovação explícita, revisão de política, propagação e reabertura.
### TSK-0007 — gates obrigatórios
Definições de gates do projeto e adicionais por Work são cumulativas. Cada gate
declara procedimento e caminhos avaliados; não executa comandos. O registro exige
atestado de observação, fingerprint prévio, resultado, invocação e resumo curto.
Arquivos, escopo/guidance do Work e revisões das DECs compõem o fingerprint;
mudanças relevantes ou na definição exigem nova avaliação. Bookkeeping do Plan
não invalida um resultado. Anexos obrigatórios passam pela integridade existente.
Conclusões humanas, por Plans e por EPICs verificam os gates e congelam referências
e hashes dos resultados entregues na mesma transação. A consulta histórica não
reaplica regras configuradas depois da entrega. Testes focados de gates,
coordenação, infraestrutura e arquitetura: 23 cenários passaram. Instalação e
workspace canônico permanecem no formato legado.
### TSK-0008 — anexos temporários e recuperação
O Work aberto conserva seus anexos porque outros checks ainda podem precisar
deles. A conclusão valida os anexos e registra DISCARD_PENDING na transação;
somente após commit remove os payloads e reconhece DISCARDED. Interrupções entre
essas fases são repetíveis por `artifact recover WRK`. Ausência sem validação
prévia continua inválida. Novas avaliações exigem entradas disponíveis, inclusive
após reabrir um Work; o histórico usa o resultado mínimo persistido.
Recibos de Plans/EPICs novos são fatos tipados, sem arquivos JSON. As origens
legadas de importação permanecem preservadas, assim como futuras cópias de
migração. Publicações temporárias usam um pequeno journal operacional, removido
após commit/rollback; recuperação distingue órfão próprio de payload já publicado.
Rollback de preparação remove diretórios vazios próprios e preserva resíduos
desconhecidos. Outputs solicitados fora do estado AIE não são alvos da limpeza.
EXP-0002: 32 cenários distintos focados passaram em duas rodadas. Cobertura inclui
arquivo perdido antes de check, recusa de reuso após descarte, rollback da
conclusão, interrupção após commit e após unlink, publicação interrompida,
repetição, preservação de output e originais legados, recibos e coordenação.
### TSK-0009 — consultas e diagnóstico
Contexto, status, next-actions e validação usam snapshots SQLite para leituras
relacionadas. Parent/links de EPIC têm índice relacional com unicidade de pai e
FKs. Consultar um Work selecionado não carrega outros Works por conveniência:
um registro alheio inválido não bloqueia seu contexto. Validação global continua
inspecionando o projeto, contador, grafo, FK e integridade SQLite.
Compatibilidade inspeciona registros tipados e revisões no banco, sem procurar
Markdown inexistente nem converter arquivos. Contexto expõe gates e disponibilidade
dos anexos. Next-actions sinaliza descarte interrompido sem fazê-lo durante leitura.
15 testes focados passaram, incluindo contexto em JVM separado, snapshot com outro
escritor, isolamento de Work inválido, histórico com formato não suportado e leitura
sem limpeza. A regressão legada de compatibilidade também passou na rodada anterior.
### TSK-0010 — migração explícita
`storage migrate` apresenta prévia sem escrita; `--apply --expect HASH` prepara
uma base separada, importa registros tipados e compara DTOs, revisões, autoridade
e integridade antes de selecionar SQLite. `--recover` e `--rollback` usam o
fingerprint da operação. A cópia de segurança conserva originais e fontes exatas
dos hashes; o staging é removido após êxito. Os arquivos legados existentes
permanecem em seus destinos, sem alteração ou remoção de arquivos rastreados.
Contrato 4 e um marcador visível em `works/` impedem escrita por CLI antiga,
inclusive comandos que já aguardavam o lock. Escritores modernos compartilham
uma fronteira de publicação com espera limitada e recusam mudança de backend
durante a espera. Leituras não precisam desse lock. A recuperação recusa ativação
se o legado mudou; rollback preserva essas alterações e exige nova prévia. Depois
de novas gravações SQLite, rollback é recusado para não perder memória.
A prova encontrou e corrigiu a distinção entre lista nula e vazia (especialmente
exclusions de Plan). Essa presença é tipada no esquema e os hashes originais
continuam ancorados em bytes externos, com comparação contra o registro tipado.
EXP-0003: 34 testes na rodada final passaram, incluindo cinco pontos de falha,
corpus congelado, Plan/survey ativo, EPIC/RUN, IDs reservados e compatibilidade.
Nenhum consumidor nem este workspace foi migrado.
### TSK-0011 — inicialização local
`init` prepara SQLite e bootstrap antes de publicar o workspace. Acrescenta
`/.ai-engineering/` ao .gitignore sem exigir Git, preservando instruções externas
e regras anteriores. `--version-state` deixa essa política ao desenvolvedor;
`--storage legacy` é explícito para compatibilidade. Nenhum comando remove arquivos
rastreados ou converte projetos existentes durante onboard/leitura.
Bootstrap SQLite exige contrato 4 antes de acessar a base; esquemas/contratos
incompatíveis são diagnosticados. As instruções distribuídas exigem CLI compatível
para ler SQLite e proíbem interpretar memória ilegível como projeto vazio. Testes
de continuidade passaram em seis cenários JVM separados, inclusive sem Git no PATH.
A rodada consolidada de init, migração, compatibilidade, protocolo e arquitetura
também passou após explicitar o backend das fixtures legadas.
### TSK-0012 — pacote preparado, instalação adiada
`nativePackage` reúne AIE nativo, bibliotecas companheiras e CLI sqlite3 em
`build/native/package`; distribuições usam esse diretório completo. SQLite 3.54.1
é compilado de fonte oficial com SHA3-256 fixado em scripts/sqlite-version.json.
O verificador confere componentes/hashes/versões, inicializa um projeto descartável
com AIE nativo e lê sua base com o sqlite3 do pacote.
O instalador preparado aceita bin-dir/lib-dir, verifica uma release completa antes
de alternar current e publicar atalhos aie/ai-engineering/aie-sqlite3. Uma falha na
troca dos atalhos restaura a release e os atalhos anteriores. 17 testes com
ferramentas simuladas passaram, inclusive falha parcial de ativação. O pacote real
de build foi verificado em macOS arm64; Linux está coberto pelas fixtures de
instalação, sem prova nativa física nesta máquina.
Nenhuma instalação real foi executada: binários/bibliotecas/atalhos ativos e
projetos consumidores permanecem intactos.
### TSK-0013 — contrato documentado
README, arquitetura, protocolo, compatibilidade e recursos de entrada agora
descrevem memória local SQLite, gates e anexos temporários. O procedimento público
está em docs/storage-migration.md. A referência detalhada do backend de arquivos
foi mantida separadamente como legado explícito. Os dois ciclos, OODA e autoridade
humana permanecem; instalação/migração reais continuam adiadas. Links locais foram
verificados e os testes de init, compatibilidade e Work guidance passaram.
### TSK-0014 — regressão integrada e handoff
`./gradlew check` passou com 230 testes JVM, zero falhas/erros/skips, além dos 11
cenários do fixture Jenkins. O ajuste final do importador SQLite passou em rodada
focada de 17 testes (importação/recuperação e arquitetura). As 17 fixtures finais do
instalador passaram com ferramentas simuladas; nenhuma instalação real ocorreu.
O pacote final e arquivos ZIP/TAR foram gerados com GraalVM e tiveram componentes,
hashes, versões e permissões verificados. O smoke nativo completo passou, incluindo
legado, continuidade, guidance/OODA e os novos cenários SQLite de gate pendente,
conclusão, descarte, recusa de reuso e migração do corpus congelado. O diagnóstico de
processos do macOS exigiu execução fora do sandbox; a repetição autorizada passou.
Uma cópia isolada do pacote abriu SQLite com extração temporária sem escrita; uma
cópia sem a biblioteca JDBC foi corretamente recusada.
O gerador de latência foi verificado com um Work/uma nota sintéticos, sem medição.
docs/latency-scenario.md e scripts/latency-fixture.py foram encaminhados por Discussion
ao WRK-000C, que permanece OPEN. Adoção do banco não foi declarada prova de melhora.
A verificação física foi macOS arm64; Linux/Windows permanecem dependentes da matriz
CI para confirmação nativa. Instalação ativa, workspace canônico e consumidores
continuam no estado anterior, sem migração real.
+72
View File
@@ -0,0 +1,72 @@
# SQLite migration and recovery
Installation and migration are separate operations. Building/installing a CLI does
not convert a project. Keep the installed version used by ongoing projects until
choosing to activate a compatible release. This implementation was tested on
fixtures only; its canonical workspace and consumers were not migrated.
## Preview and apply
Use a CLI that advertises protocol contract 4. In the chosen legacy project:
```sh
aie project compatibility --format json
aie project validate --format json
aie storage migrate --format json
```
Preview reads supported canonical records, histories, evidence and bootstrap. It
returns validity, Work count and a fingerprint. It writes no lock, backup or database.
Repair invalid input first. Preserve original scope/authority; do not reopen completed
Works to normalize them. This route does not accept unknown future schemas.
After reviewing the preview:
```sh
aie storage migrate --apply --expect <fingerprint> --format json
```
Application takes the publication lock, verifies the current fingerprint, makes a
safety copy under `.ai-engineering/.local/sqlite-migration/<operation>/original`,
and imports into a separate staging database. It compares typed values/revisions,
references, approvals, reserved IDs, hashes and completion provenance. Original
file bytes remain external for historical chain verification; they are not BLOBs
or file-shaped TEXT in SQLite.
Only after validation does activation publish the protected contract, database and
storage selection. A visible `works/SQLITE-STORAGE` marker also stops legacy readers
that had already passed an old contract check. Existing Work documents stay
byte-identical as retained non-authoritative originals; future writes use SQLite.
No tracked file is automatically untracked or removed, and existing Git ignore policy
is preserved. New projects use `init` with state ignored by default.
Success reports APPLIED and the safety-copy path. Staging is removed. Repeating the
same application is idempotent. Keep the safety originals: historical revision hashes
may depend on them. They are not a general backup/export feature.
## Interrupted operation
Ordinary CLI access reports the pending migration rather than reading mixed storage.
Inspect its public preview/report, then choose:
```sh
aie storage migrate --recover --expect <operation-fingerprint>
# Or explicitly return to the recoverable legacy source:
aie storage migrate --rollback --expect <operation-fingerprint>
```
Recovery verifies source/safety/prepared data and resumes without duplicate records.
If a legacy writer changed input before activation, recovery refuses stale data;
rollback preserves those legacy edits, then a new preview captures them.
Rollback restores only bootstrap files changed by this operation and removes its
unchanged published database/guard. It retains the safety copy. Unrelated bootstrap
edits require deliberate review. Once SQLite has received new engineering writes,
rollback refuses to discard that memory; keep SQLite and inspect the diagnostic.
Never delete the database or journal to force a fresh-looking project.
A migration does not retroactively discard legacy evidence, add approvals or claim
new quality gates passed. New temporary inputs and gate results follow the current
[retention contract](protocol.md#temporary-inputs-and-outputs). Work/DEC sharing,
import/export, distributed reconciliation and backup as a product feature remain
outside this version.