Files
ai-engineering/docs/protocol.md
T

149 lines
8.1 KiB
Markdown

# Local engineering memory protocol
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.
## Starting and continuing
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.
`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.
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
```
Obtain `evaluatedHash` before running the procedure externally. Attach required
small evidence with `artifact add`. Then record the actual result:
```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
```
`--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.