149 lines
8.1 KiB
Markdown
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.
|