Files
ai-engineering/docs/protocol.md
T

8.1 KiB

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, refinement and Plan consolidation 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:

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:

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 documents those file formats. Storage migration 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.