feat: adopt local SQLite engineering memory and quality gates
This commit is contained in:
+138
-592
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user