Files
ai-engineering/docs/experiments.md
T
Nilton Constantino e65f216926 feat: support simple projects and root Git repositories
Allow registering a single Git repository at the engineering project root with --path . while retaining path safety checks.

Document Git-optional projects first and cover plain folders, root repositories, and multiple repositories in process tests and native smoke scenarios.

Validated with 23 passing tests and macOS ARM64 native smoke checks for all three layouts.
2026-11-11 16:38:18 +00:00

175 lines
9.6 KiB
Markdown

# Initial experiments
Execution host: macOS ARM64, 2026-11-11. JVM: Amazon Corretto 25.0.4+7.
Native toolchain: Oracle GraalVM for JDK 25.0.4+7.1 and Apple C compiler.
Resolved Jackson YAML/Databind: 3.1.7 (Boot BOM). No Python, Node, model API,
database or external runtime service was used.
## H1 — One non-web modular application is enough
Observation: the packaged Spring Boot application prints Picocli help/version and
terminates. Automated process tests enforce a 30-second termination limit. There
are no web/server dependencies. Modulith verifies eight modules and their declared
dependency graph.
Result: verified by `ArchitectureTest`, CLI smoke tests and independent JVM processes.
Spring handles process lifecycle and AOT; the portable protocol stays plain Java.
## H2 — Files alone preserve meaningful engineering state
The main integration fixture initializes an engineering project with two independent
Git repositories (`runtime`, `studio`), creates a Work referencing both, supplies goal,
constraints and acceptance criteria, appends a question/conclusion, persists a draft
DEC and attaches evidence. A fresh CLI instance invoked from `studio/src/editor`
reconstructs exactly the same exported context.
`ProcessContinuityTest` repeats the scenario through separate `java -jar` processes.
Each source repository contains a real fixture commit. The fresh context includes
both revision snapshots, author, discussion, DRAFT status and evidence SHA-256. JSON
exports from independent processes compare byte-for-byte. Project validation succeeds.
Result: verified without shared application memory or conversation history. The native
smoke script reproduces the same scenario with a separate native process per command.
## H3 — Structural safety and integrity are testable without a model
Verified cases: multiple Works, separate artifact workspaces, missing repositories,
unknown configuration fields/schema, malformed YAML and duplicate YAML keys,
traversal and symlink attempts, malformed/missing/duplicate Work identifiers,
missing decision files and evidence payloads, orphan records, required directories,
SHA-256 corruption, explicit question replies, reversible status, default read-only
access, immutable models, atomic no-overwrite writes and persistent ID reservations.
A real submodule fixture additionally verifies registration without rewriting
`.gitmodules`. It initially exposed a path equality bug between macOS `/var` and
`/private/var`. Comparing both real paths fixed it. A numeric-enum negative fixture
initially failed to alter Jackson's quoted YAML; the corrected fixture now verifies
that ordinal lifecycle values are rejected.
Result: final clean build has **20 tests, 0 failures, 0 errors, 0 skipped**.
The first test-first run intentionally failed because implementation classes did not
exist. Intermediate compilation caught interruption handling and a Jackson 2 feature
constant moved to Jackson 3's `EnumFeature`; both were corrected. These failures are
resolved in the final tested source.
## Commands and evidence
```sh
./gradlew clean test bootJar --console=plain
./gradlew dependencies --configuration runtimeClasspath --console=plain
JAVA_HOME=<graalvm25-home> GRAALVM_HOME=<graalvm25-home> \
./gradlew nativeCompile nativeDistZip nativeDistTar \
-PtargetPlatform=macos-arm64 --console=plain
```
The clean test/JAR build passed. Generated test reports are under
`build/reports/tests/test`; raw JUnit XML is under `build/test-results/test`.
Runtime dependency inspection confirmed the pinned Spring pair and Jackson 3.1.7.
An initial Native Image compilation succeeded, but only the final rebuilt binary's
execution results count as native functionality verification.
Native result: **compiled and executed successfully on macOS ARM64**. The initial
verified Native Image build completed in approximately 1m 13s (Gradle invocation:
1m 23s). `ai-engineering` is a Mach-O ARM64 executable. ZIP and tar.gz archives were
generated with executable permissions and inspected.
The native continuity smoke passed with no JDK on the configured execution path:
```sh
JAVA_HOME=/nonexistent PATH=/usr/bin:/bin:/usr/sbin:/sbin AIE_KEEP_FIXTURE=1 \
bash scripts/native-smoke.sh "$PWD/build/native/nativeCompile/ai-engineering"
```
Observed output: `Native multi-repository continuity smoke passed.` Every CLI command
in the script starts a separate process. Help/version, exit code 2 for invalid input,
both repository registrations, Work creation, discussion, evidence, DEC draft,
nested discovery, JSON byte equality, Markdown export and final structural validation
all succeeded. The engineering fixture root had no `.git` directory.
The retained local demonstration fixture is at
`/var/folders/0t/tfsqc14j5wbgh9h4s4dytwb00000gq/T/ai-engineering-smoke.ziQUkw`.
Inspect `.ai-engineering/works/WRK-0001-improve-scene-editor/`, `before.json`,
`after.json`, `context.md` and `validation.json` there. The JSON validation report
contains `valid: true` and an empty issue list. Temporary fixtures are not required
for future use; the committed script can recreate the experiment.
Nonblocking Native Image build warnings: Picocli's generated proxy metadata uses a
deprecated configuration resource option; SLF4J reports no provider during image
analysis. Neither prevented compilation or the full native execution scenario.
An earlier exploratory native invocation was terminated with exit 137 during a clean
rebuild; it was not treated as a functional pass. The final rebuilt binary passed the
full smoke scenario above.
## H4 — SDKMAN GraalVM Community toolchain
The local project JDK is now pinned in `.sdkmanrc` to SDKMAN candidate
`25.5.5.0+3-graalce`. Direct inspection identifies GraalVM Community Edition
25.5.5.0.3+1.1, based on OpenJDK 25.0.5.0.3, with Native Image included. Gradle
9.3.1 recognizes it as both launcher and daemon JVM. A clean Java/AOT/JAR build
and all **20 tests** passed again using this installation. The language and bytecode
target remain Java 25. CI native builds select the Community 25.5 series; CI itself
has not been executed locally.
Native compilation with Native Build Tools 0.11.5 also succeeded (image generation
approximately 1m 8s; complete clean test/JAR/native invocation 1m 40s). The full native
continuity smoke passed with the CE-built executable, including project validation
and byte-identical context exports across processes. An isolated copy containing only
the executable passed the same scenario with both `JAVA_HOME` and `GRAALVM_HOME` set
to nonexistent paths and no JDK on the configured PATH. Native Image also emitted
optional desktop libraries beside the build output; the implemented CLI commands
were verified without those libraries present beside the isolated executable.
The compiler reports nonblocking deprecation warnings for `--no-fallback`,
`FallbackThreshold` and Picocli's proxy configuration. No application dependency or
native plugin upgrade was needed for the tested functionality.
Reproduction after `sdk env`:
```sh
export GRAALVM_HOME="$JAVA_HOME"
./gradlew clean test bootJar nativeCompile --console=plain
JAVA_HOME=/nonexistent GRAALVM_HOME=/nonexistent PATH=/usr/bin:/bin:/usr/sbin:/sbin \
bash scripts/native-smoke.sh "$PWD/build/native/nativeCompile/ai-engineering"
```
## H5 — Simple projects and a single root repository
A simple project can initialize `.ai-engineering` directly beside its existing source
files. Repository registration is optional; a project with no registered repositories
has a complete Work/discussion/decision/artifact workflow and no Git revision snapshots.
The separate-process test runs those commands with no Git on PATH, reconstructs the
same context, validates the project and confirms no `.git` or source changes appear.
For projects already using one Git repository, `repo add app --path .` now registers
the root repository. A test-first run reproduced the earlier root-path rejection;
removing that restriction preserves traversal, symlink and `.ai-engineering` exclusions.
Regression tests confirm read-only defaults, nested discovery, deterministic context,
duplicate-path rejection and unchanged Git configuration/source content. Existing
multi-repository and real-submodule fixtures still pass.
Result: **23 tests, 0 failures, 0 errors, 0 skipped** on the SDKMAN GraalVM CE toolchain.
The native smoke script now exercises all three layouts: no Git, a single root Git
repository, and multiple child Git repositories. The README starts with the simple
project workflow. These changes do not require a new configuration schema or project
mode.
Native compilation succeeded on macOS ARM64. With `JAVA_HOME` and `GRAALVM_HOME`
pointing to nonexistent paths, the expanded smoke passed both the simple-project
scenarios (including no Git on PATH) and the multi-repository scenario.
## Limits and next experiment
CI workflows are provided but have not been executed from this local workspace.
Linux x86_64 and Windows x86_64 binaries are not locally verified. GraalVM 25 removed
macOS x86_64 support, so that release target has no claimed native artifact.
Filesystem atomicity is per file/directory publication, not a transaction across the
child record and parent manifest. Orphans after interruption are detected, not
automatically repaired. Manual concurrent editors and adversarial path replacement
require external coordination/sandboxing. Artifact attachment is limited to small
files, and no full provenance/environment capture or agent intelligence is implemented.
Next recommended experiment: define a deterministic AgentAdapter test contract and
demonstrate two fake adapters continuing the same Work. Keep that work in Milestone 2;
no adapter implementation is included here.