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