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
+57 -64
View File
@@ -4,10 +4,11 @@
AI Engineering (AIE) is a local CLI for keeping engineering work understandable
across people, AI agents, and sessions. It stores goals, discussions, decisions,
plans, and verification evidence as readable files alongside your project.
plans, and quality results in a local SQLite database for each project.
Use it in a single folder or across several source repositories. Git is optional.
The core workflow runs without a model API, database, or background service.
SQLite runs inside AIE; no database server, model API or background service is required.
State stays outside Git by default. Versioning it is the developer's choice.
## What you can do
@@ -53,71 +54,46 @@ ai-engineering() { java -jar "$AIE_JAR" "$@"; }
The JAR requires Java 25 at runtime. On Windows, use `gradlew.bat` in place of
`./gradlew`; you can invoke the JAR directly with `java -jar` and its full path.
### Build a native executable
### Prepare a native package
On Linux (x64/ARM64) and macOS (Apple Silicon), build and install for your user:
```sh
./scripts/install-native.sh
```
The script uses a compatible `GRAALVM_HOME` or `JAVA_HOME`, otherwise installs the
GraalVM version pinned in `.sdkmanrc` through [SDKMAN](https://sdkman.io/install/),
installing SDKMAN too when needed. It builds with the Gradle Wrapper, checks the
executable, copies it to `~/.local/bin/ai-engineering`, and creates the `aie`
shortcut. Run the same command again to update. The installed copy works independently
of this checkout. A failed build or executable check leaves the previous installation
in place. Downloads require internet access.
If `~/.local/bin` is not in your `PATH`, add this to your shell profile and current
session (the script prints the appropriate command for your destination):
```sh
export PATH="$HOME/.local/bin:$PATH"
aie --help
```
Use `./scripts/install-native.sh --bin-dir /path/to/bin` to select another destination.
The script can be invoked from any directory and does not modify shell profiles or
install system packages. It requires `curl`, `zip`, and `unzip` when installing GraalVM
through SDKMAN. Install [native build prerequisites](https://www.graalvm.org/jdk25/reference-manual/native-image/)
before running it:
- macOS: `xcode-select --install` (Apple Command Line Tools).
- Debian/Ubuntu: `sudo apt-get install build-essential zlib1g-dev`.
- Fedora/RHEL: `sudo dnf install gcc gcc-c++ glibc-devel zlib-devel libstdc++-static`.
The pinned GraalVM does not support macOS Intel; use the JVM instructions above.
For a manual native build:
The native executable runs without a JVM. Building it requires **GraalVM for
JDK 25**, Native Image, and a C/C++ toolchain for the target platform. Set both
`JAVA_HOME` and `GRAALVM_HOME` to your GraalVM installation.
If you use SDKMAN, the repository pins a compatible toolchain in [.sdkmanrc](.sdkmanrc):
On Linux (x64/ARM64) and macOS (Apple Silicon), use the GraalVM JDK 25 pinned in
[.sdkmanrc](.sdkmanrc), Native Image, a C/C++ toolchain and Python 3:
```sh
sdk env install
sdk env
export GRAALVM_HOME="$JAVA_HOME"
./gradlew nativeCompile
./build/native/nativeCompile/ai-engineering --help
```
Add the executable's directory to `PATH` to use `ai-engineering` from other folders.
On Windows the executable is named `ai-engineering.exe`. The shorter `aie` command
can be provided as a local alias or symlink.
To create distribution archives:
```sh
./gradlew nativePackage
python3 scripts/verify-native-package.py build/native/package
./gradlew nativeDistZip nativeDistTar
```
Archives are written to `build/distributions/` and include the README, documentation,
and MIT license. Build on the intended OS and architecture; the native CI matrix
is defined in [.github/workflows/build.yml](.github/workflows/build.yml).
These commands prepare build outputs. The complete package contains AIE, the
companion JDBC/native libraries and a pinned `sqlite3` diagnostic executable.
Keep those components together; copying the AIE executable alone is insufficient.
SQLite source is checksum-pinned in [sqlite-version.json](scripts/sqlite-version.json).
Distributions are written to `build/distributions/` with docs and licenses.
Build on the intended OS/architecture. macOS Intel uses the JVM distribution.
### Install when ready
Installation is a separate action. From a checkout:
```sh
./scripts/install-native.sh
```
The script prepares and verifies the complete package before activation. It uses a
compatible `GRAALVM_HOME`/`JAVA_HOME`, or obtains the pinned GraalVM through SDKMAN.
Defaults are `~/.local/lib/ai-engineering` for releases and `~/.local/bin` for
`ai-engineering`, `aie` and `aie-sqlite3` shortcuts. Project databases stay in their
projects. Failed checks preserve the prior installation; activation failures restore
the prior release/shortcuts. No project is migrated by installation.
Use `--lib-dir DIR --bin-dir DIR` for custom destinations. The script does not edit
shell profiles or install system packages. Add your bin directory to PATH yourself.
Native builds require platform C/C++ and zlib development tools; SDKMAN bootstrap
also needs curl, zip and unzip. Installer verification uses Python 3.
## Quick start
@@ -144,8 +120,9 @@ ai-engineering project validate
`init` creates `.ai-engineering/` and installs portable instructions for agents,
including a managed block in the project's `AGENTS.md`. Existing project rules
outside that block are preserved. Keep the canonical engineering files under
version control when you use Git; `.ai-engineering/.local/` contains local state.
outside that block are preserved. New state is SQLite and `/.ai-engineering/` is
added to .gitignore, even without Git installed. `init --version-state` leaves ignore
policy to you. Existing tracked files are never untracked automatically.
The exported context brings together the Work's scope, discussion, decisions,
plans, evidence references, and pending questions. `next-actions` suggests what to
@@ -226,7 +203,8 @@ model call. Direct human approval remains available through `decision accept`.
| Survey | Questions with suggested choices, free text, and answer history |
| Decision | A reviewed choice with explicit approval and revision history |
| Plan | Steps, dependencies, observed results, and evidence references |
| Artifact | Retained evidence with integrity metadata |
| Artifact | Temporary check input with integrity and retirement state |
| Quality gate | Required project/Work check and state-bound observed result |
Completed required plans can consolidate a Work automatically. The framework
checks recorded state and evidence integrity; it does not prove that arbitrary
@@ -236,6 +214,20 @@ and system completion retains its own provenance.
See the [protocol reference](docs/protocol.md) for commands, formats, lifecycle
rules, and recovery behavior.
## Quality and retention
Investigation/discussion and implementation remain connected through DEC and Plan.
OODA guides experiments and reconsideration. Required gates come from the project,
with additional gates per Work; pending, failed or stale checks block delivery.
Checks run externally. AIE records the actual observation against an evaluated
state and keeps a short result; human approval is separate.
Evidence attachments stay available while checks need them. After Work completion,
new temporary copies retire automatically; missing input before a check is an error.
Outputs requested by the user belong at their delivery destination outside AIE state.
Internal receipts are structured database facts. Legacy originals and migration safety
copies remain preserved. See [gates and retention](docs/protocol.md#quality-gates).
## AI agent integration
Agents can discover the protocol through `AGENTS.md` and `.ai-engineering/`.
@@ -266,9 +258,9 @@ ai-engineering project validate --format json
`CURRENT` and `LEGACY_COMPATIBLE` both indicate readable formats. Supported older
records remain readable without automatic normalization or reopening completed
Works. `onboard` refreshes entry instructions with backups while preserving Work
files. The [compatibility guide](docs/compatibility.md) explains contract versions,
storage formats, diagnostics, and future explicit migrations.
Works. `onboard` refreshes entry instructions without converting storage. To move a
legacy project to SQLite, review `aie storage migrate --format json`, then apply
with its fingerprint. See [migration and recovery](docs/storage-migration.md).
## Development and verification
@@ -294,6 +286,7 @@ Tests generate JUnit results and JaCoCo coverage. Open
|---|---|
| [Protocol reference](docs/protocol.md) | Commands, records, approval, persistence, and recovery |
| [Compatibility](docs/compatibility.md) | Supported formats and update procedures |
| [Storage migration](docs/storage-migration.md) | Preview, apply, recover and rollback |
| [Work conduct and OODA](docs/work-guidance.md) | Human discussion choices, DEC authority and optional Plan experiments |
| [Discussion and refinement](docs/discussion-slice.md) | Topics, surveys, and proposal handling |
| [Plan consolidation](docs/plan-consolidation.md) | Steps, results, and automatic completion |