feat: bootstrap portable engineering protocol CLI

Implement milestones 0 and 1 with project and repository configuration, Work persistence, discussions, draft decisions, evidence integrity, and deterministic context exports.

Add Java 25, Spring Boot and Modulith, native distributions, CI workflows, protocol documentation, and the pinned SDKMAN GraalVM CE toolchain.

Validated with 20 passing tests and the macOS ARM64 native multi-repository continuity smoke.
This commit is contained in:
Nilton Constantino
2026-11-11 16:14:22 +00:00
commit f0e0dd061a
49 changed files with 2367 additions and 0 deletions
@@ -0,0 +1,6 @@
package net.intrepid.aiengineering;
import org.junit.jupiter.api.Test;
import org.springframework.modulith.core.ApplicationModules;
class ArchitectureTest {
@Test void moduleBoundariesAreValid() { ApplicationModules.of(AiEngineeringApplication.class).verify(); }
}
@@ -0,0 +1,74 @@
package net.intrepid.aiengineering;
import net.intrepid.aiengineering.cli.EngineeringCli;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import java.nio.file.*;
import java.io.*;
import static org.assertj.core.api.Assertions.*;
class IntegrityTest {
@TempDir Path root;
private String lastOutput;
private int cli(String... args) {
var out = new StringWriter(); var err = new StringWriter();
int code = new EngineeringCli(root).execute(new PrintWriter(out), new PrintWriter(err), args);
lastOutput = out + err.toString(); return code;
}
private void ok(String... args) { assertThat(cli(args)).as(lastOutput).isZero(); }
private Path work() { return root.resolve(".ai-engineering/works/WRK-0001-one"); }
private void initWork() { ok("init", "--name", "Test"); ok("work", "create", "One"); }
@Test void missingPayloadAndTamperedEvidenceAreDetected() throws Exception {
initWork(); Path source = Files.writeString(root.resolve("source.txt"), "abc");
ok("artifact", "add", "WRK-0001", "--file", source.toString(), "--purpose", "Test integrity");
Path payload = work().resolve("artifacts/evidence/ART-0001/payload");
Files.writeString(payload, "xyz");
assertThat(cli("work", "validate", "WRK-0001")).isEqualTo(4); assertThat(lastOutput).contains("SHA-256");
Files.delete(payload);
assertThat(cli("work", "validate", "WRK-0001")).isEqualTo(4); assertThat(lastOutput).contains("Missing artifact payload");
assertThat(cli("work", "context", "WRK-0001")).isEqualTo(4);
}
@Test void registeredRepositoryMissingAfterRegistrationIsDetected() throws Exception {
initWork(); Path repo = Files.createDirectory(root.resolve("runtime"));
var git = new ProcessBuilder("git", "init", repo.toString()).redirectErrorStream(true).start();
git.getInputStream().readAllBytes(); assertThat(git.waitFor()).isZero();
ok("repo", "add", "runtime", "--path", "runtime");
Files.move(repo, root.resolve("moved"));
assertThat(cli("project", "validate")).isEqualTo(4); assertThat(lastOutput).contains("Missing repository");
}
@Test void discussionRepliesKeepHistoryAndResolveOnlyExplicitQuestions() {
initWork();
ok("discussion", "add", "WRK-0001", "--text", "Which renderer?", "--kind", "QUESTION");
ok("discussion", "add", "WRK-0001", "--text", "Canvas", "--kind", "RESPONSE", "--responds-to", "DSC-0001");
ok("work", "context", "WRK-0001", "--format", "json");
assertThat(lastOutput).contains("Which renderer?", "Canvas", "\"outstandingQuestions\" : [ ]");
assertThat(cli("discussion", "add", "WRK-0001", "--text", "Wrong", "--responds-to", "DSC-9999")).isEqualTo(2);
}
@Test @org.junit.jupiter.api.condition.DisabledOnOs(org.junit.jupiter.api.condition.OS.WINDOWS)
void protocolAndWorkSymlinksAreRejected() throws Exception {
initWork(); Path outside = Files.createTempDirectory("aie-link-");
Files.createSymbolicLink(work().resolve("decisions/DEC-0001.md"), outside.resolve("decision.md"));
assertThat(cli("decision", "draft", "WRK-0001", "--title", "Do not escape")).isEqualTo(2);
assertThat(cli("work", "validate", "WRK-0001")).isEqualTo(4);
}
@Test void unknownSchemaFieldsDuplicateKeysAndMalformedYamlFail() throws Exception {
initWork(); Path config = root.resolve(".ai-engineering/ai-engineering.yaml"); String original = Files.readString(config);
for (String corrupt : new String[]{original + "unknownPolicy: true\n", original + "schemaVersion: 2\n", "project: [broken\n"}) {
Files.writeString(config, corrupt); assertThat(cli("project", "validate")).isEqualTo(4);
}
}
@Test void lifecycleIsReversibleAndArtifactsAreWorkLocal() throws Exception {
initWork(); ok("work", "create", "Two");
ok("work", "status", "WRK-0001", "COMPLETED"); ok("work", "status", "WRK-0001", "ACTIVE");
Path source = Files.writeString(root.resolve("result.txt"), "Only first Work\n");
ok("artifact", "add", "WRK-0001", "--file", source.toString(), "--purpose", "First only");
ok("work", "context", "WRK-0002"); assertThat(lastOutput).doesNotContain("First only", "ART-0001");
ok("work", "show", "WRK-0001"); assertThat(lastOutput).contains("ACTIVE");
}
@Test void orphanFilesAndMissingWorkDirectoriesAreDiagnosed() throws Exception {
initWork(); Files.writeString(work().resolve("discussions/orphan.md"), "unreferenced");
Files.delete(work().resolve("runs"));
assertThat(cli("work", "validate", "WRK-0001")).isEqualTo(4);
assertThat(lastOutput).contains("Unreferenced protocol file", "Missing Work directory");
}
}
@@ -0,0 +1,66 @@
package net.intrepid.aiengineering;
import net.intrepid.aiengineering.filesystem.*;
import net.intrepid.aiengineering.project.*;
import net.intrepid.aiengineering.work.*;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import java.nio.file.*;
import java.util.*;
import static org.assertj.core.api.Assertions.*;
class PersistenceTest {
@TempDir Path root;
@Test void atomicCreateNeverOverwritesAndReplacementLeavesNoTemporaryFile() throws Exception {
Path target = root.resolve("state.yaml");
Filespace.write(target, "first", false);
assertThatThrownBy(() -> Filespace.write(target, "second", false)).isInstanceOf(ProtocolException.class);
assertThat(Files.readString(target)).isEqualTo("first");
Filespace.write(target, "replacement", true);
assertThat(Files.readString(target)).isEqualTo("replacement");
try (var files = Files.list(root)) { assertThat(files.map(p -> p.getFileName().toString())).containsExactly("state.yaml"); }
}
@Test void workIdentityReservationSurvivesRemovalAndModelsAreImmutable() throws Exception {
var projects = new ProjectService(); projects.initialize(root, "Test"); var works = new WorkService();
var constraints = new ArrayList<>(List.of("Original"));
var one = works.create(root, "One", "", "Goal", "", constraints, List.of(), List.of(), "human");
constraints.add("Changed"); assertThat(one.constraints()).containsExactly("Original");
assertThatThrownBy(() -> one.constraints().add("Mutate")).isInstanceOf(UnsupportedOperationException.class);
Path removed = root.resolve("removed-work"); Files.move(works.folder(root, one.id()), removed);
var two = works.create(root, "Two", "", "Goal", "", List.of(), List.of(), List.of(), "human");
assertThat(two.id()).isEqualTo("WRK-0002");
}
@Test void omittedAccessIsReadOnlyAndInvalidPolicyIsRejected() {
var config = Documents.parse("""
schemaVersion: 1
project: {id: test, name: Test}
repositories:
- {id: runtime, path: runtime, type: linked-git}
""", ProjectConfig.class);
assertThat(config.repositories().getFirst().access()).isEqualTo(new ProjectConfig.Access(true, false));
assertThatThrownBy(() -> new ProjectConfig.Access(false, true)).isInstanceOf(ProtocolException.class);
}
@Test void numericLifecycleValuesAreRejected() {
var projects = new ProjectService(); projects.initialize(root, "Test"); var works = new WorkService();
var work = works.create(root, "One", "", "Goal", "", List.of(), List.of(), List.of(), "human");
String invalid = Documents.yaml(work).replaceAll("(?m)^status:.*$", "status: 0");
assertThatThrownBy(() -> Documents.parse(invalid, Work.class)).isInstanceOf(ProtocolException.class);
}
@Test void realGitSubmoduleCanBeRegisteredWithoutReconfiguration() throws Exception {
var projects = new ProjectService(); projects.initialize(root, "Test");
Path upstream = Files.createTempDirectory("aie-upstream-");
git("init", upstream.toString());
git("-C", upstream.toString(), "-c", "user.name=Fixture", "-c", "user.email=fixture@example.invalid", "commit", "--allow-empty", "-m", "fixture");
git("init", root.toString());
git("-C", root.toString(), "-c", "protocol.file.allow=always", "submodule", "add", upstream.toString(), "runtime");
Path modules = root.resolve(".gitmodules"); byte[] before = Files.readAllBytes(modules);
projects.addRepository(root, new ProjectConfig.Repository("runtime", "runtime", "git-submodule", "rust", null, null));
projects.validate(root);
assertThat(Files.readAllBytes(modules)).isEqualTo(before);
}
private static void git(String... args) throws Exception {
var command = new ArrayList<>(List.of("git")); command.addAll(List.of(args));
var process = new ProcessBuilder(command).redirectErrorStream(true).start();
String out = new String(process.getInputStream().readAllBytes()); assertThat(process.waitFor()).as(out).isZero();
}
}
@@ -0,0 +1,47 @@
package net.intrepid.aiengineering;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import java.nio.file.*;
import java.util.*;
import java.util.concurrent.TimeUnit;
import static org.assertj.core.api.Assertions.*;
/** Separate operating-system processes prove there is no hidden in-memory continuity. */
class ProcessContinuityTest {
@TempDir Path root;
private String cli(String... args) throws Exception {
var command = new ArrayList<>(List.of(Path.of(System.getProperty("java.home"), "bin", "java").toString(),
"-jar", System.getProperty("cli.jar")));
command.addAll(List.of(args));
Path log = Files.createTempFile("aie-process-", ".log");
try {
var process = new ProcessBuilder(command).directory(root.toFile()).redirectErrorStream(true).redirectOutput(log.toFile()).start();
boolean exited = process.waitFor(30, TimeUnit.SECONDS);
if (!exited) process.destroyForcibly();
assertThat(exited).as("CLI must terminate without a server").isTrue();
String result = Files.readString(log); assertThat(process.exitValue()).as(result).isZero(); return result;
} finally { Files.deleteIfExists(log); }
}
@Test void independentJvmProcessesReconstructMultiRepositoryWork() throws Exception {
cli("init", "--name", "Continuity Experiment");
for (String repo : List.of("runtime", "studio")) {
Path path = Files.createDirectory(root.resolve(repo));
var git = new ProcessBuilder("git", "init", path.toString()).redirectErrorStream(true).start();
git.getInputStream().readAllBytes(); assertThat(git.waitFor()).isZero();
var commit = new ProcessBuilder("git", "-C", path.toString(), "-c", "user.name=Fixture", "-c",
"user.email=fixture@example.invalid", "commit", "--allow-empty", "-m", "fixture").redirectErrorStream(true).start();
commit.getInputStream().readAllBytes(); assertThat(commit.waitFor()).isZero();
cli("repo", "add", repo, "--path", repo);
}
cli("work", "create", "Improve scene editor", "--repo", "runtime", "--repo", "studio", "--goal", "Continue across agents");
cli("discussion", "add", "WRK-0001", "--text", "Evaluate Canvas rendering", "--author", "agent-a");
cli("decision", "draft", "WRK-0001", "--title", "Use layered Canvas");
Path evidence = Files.writeString(root.resolve("result.txt"), "Observed rendering result\n");
cli("artifact", "add", "WRK-0001", "--file", evidence.toString(), "--purpose", "Rendering experiment");
String first = cli("work", "context", "WRK-0001", "--format", "json");
assertThat(cli("work", "context", "WRK-0001", "--format", "json")).isEqualTo(first)
.contains("agent-a", "runtime", "studio", "sha256", "DRAFT", "Continue across agents");
assertThat(cli("project", "validate", "--format", "json")).contains("\"valid\" : true");
}
}
@@ -0,0 +1,92 @@
package net.intrepid.aiengineering;
import net.intrepid.aiengineering.cli.EngineeringCli;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import java.nio.file.*;
import java.io.*;
import static org.assertj.core.api.Assertions.*;
class ProtocolIntegrationTest {
@TempDir Path root;
record Result(int code, String out, String err) {}
Result run(Path cwd, String... args) {
var out = new StringWriter(); var err = new StringWriter();
int code = new EngineeringCli(cwd).execute(new PrintWriter(out), new PrintWriter(err), args);
return new Result(code, out.toString(), err.toString());
}
Result ok(String... args) {
var r = run(root, args);
assertThat(r.code()).as(r.err()).isZero(); return r;
}
void init() { ok("init", "--name", "Test Project"); }
void repository(String name) throws Exception {
Path path = Files.createDirectory(root.resolve(name));
var process = new ProcessBuilder("git", "init", path.toString()).redirectErrorStream(true).start();
process.getInputStream().readAllBytes(); assertThat(process.waitFor()).isZero();
ok("repo", "add", name, "--path", name);
}
@Test void portableMultiRepositoryContinuity() throws Exception {
init(); repository("runtime"); repository("studio");
ok("work", "create", "Improve scene editor", "--goal", "Portable rendering", "--repo", "runtime", "--repo", "studio",
"--constraint", "No web server", "--acceptance", "Context reloads");
ok("discussion", "add", "WRK-0001", "--kind", "QUESTION", "--text", "Evaluate Canvas rendering?");
ok("discussion", "add", "WRK-0001", "--kind", "CONCLUSION", "--text", "Evaluate layered Canvas first");
ok("decision", "draft", "WRK-0001", "--title", "Use layered Canvas");
Path evidence = Files.writeString(root.resolve("evidence.txt"), "Rendering experiment: 60 fps\n");
ok("artifact", "add", "WRK-0001", "--file", evidence.toString(), "--purpose", "Rendering evidence");
String before = ok("work", "context", "WRK-0001").out();
Path nested = Files.createDirectories(root.resolve("studio/src/editor"));
var fresh = run(nested, "work", "context", "WRK-0001");
assertThat(fresh.code()).as(fresh.err()).isZero();
assertThat(fresh.out()).isEqualTo(before).contains("Portable rendering", "No web server", "Context reloads",
"Evaluate Canvas rendering?", "Use layered Canvas", "DRAFT", "Rendering evidence", "runtime", "studio", "OPEN");
assertThat(ok("work", "context", "WRK-0001", "--format", "json").out()).contains("\"schemaVersion\"", "sha256");
ok("project", "validate"); ok("work", "validate", "WRK-0001");
assertThat(Files.exists(root.resolve(".git"))).isFalse();
}
@Test void independentWorksAndDeterministicExports() {
init(); ok("work", "create", "One"); ok("work", "create", "Two");
ok("discussion", "add", "WRK-0001", "--text", "Only one");
assertThat(ok("work", "list", "--format", "json").out()).contains("WRK-0001", "WRK-0002");
assertThat(ok("work", "context", "WRK-0002").out()).doesNotContain("Only one");
assertThat(ok("work", "context", "WRK-0001").out()).isEqualTo(ok("work", "context", "WRK-0001").out());
}
@Test void invalidIdentifiersMissingResourcesAndNoOverwrite() throws Exception {
init();
assertThat(run(root, "init", "--name", "Again").code()).isEqualTo(2);
assertThat(run(root, "work", "show", "../../escape").code()).isEqualTo(2);
assertThat(run(root, "work", "show", "WRK-9999").code()).isEqualTo(3);
assertThat(run(root, "repo", "add", "missing", "--path", "missing").code()).isEqualTo(3);
assertThat(run(root, "repo", "add", "escape", "--path", "../escape").code()).isEqualTo(2);
org.junit.jupiter.api.Assumptions.assumeFalse(System.getProperty("os.name").startsWith("Windows"), "Symlink fixtures need OS support");
Path outside = Files.createTempDirectory("aie-outside-");
Files.createSymbolicLink(root.resolve("escape"), outside);
assertThat(run(root, "repo", "add", "escape", "--path", "escape").code()).isEqualTo(2);
}
@Test void validationDetectsMissingDecisionArtifactAndDuplicateWork() throws Exception {
init(); ok("work", "create", "One");
ok("decision", "draft", "WRK-0001", "--title", "Draft");
Path work = root.resolve(".ai-engineering/works/WRK-0001-one");
Files.delete(work.resolve("decisions/DEC-0001.md"));
assertThat(run(root, "work", "validate", "WRK-0001").code()).isEqualTo(4);
Files.createDirectory(root.resolve(".ai-engineering/works/WRK-0001-copy"));
Files.copy(work.resolve("work.md"), root.resolve(".ai-engineering/works/WRK-0001-copy/work.md"));
assertThat(run(root, "project", "validate").code()).isEqualTo(4);
}
@Test void invalidConfigurationIsDiagnosed() throws Exception {
init(); Files.writeString(root.resolve(".ai-engineering/ai-engineering.yaml"), "schemaVersion: 999\n");
assertThat(run(root, "project", "validate").code()).isEqualTo(4);
}
@Test void cliSmokeAndHelpForEveryCommand() {
assertThat(ok("--version").out()).isEqualTo("ai-engineering 0.1.0\n");
for (String command : new String[]{"", "init", "project", "project show", "project validate", "repo", "repo add", "repo list",
"work", "work create", "work list", "work show", "work validate", "work context", "discussion", "discussion add",
"decision", "decision draft", "artifact", "artifact add"}) {
var args = new java.util.ArrayList<String>();
if (!command.isEmpty()) args.addAll(java.util.List.of(command.split(" ")));
args.add("--help"); assertThat(ok(args.toArray(String[]::new)).out()).contains("Usage:");
}
assertThat(run(root, "--unknown").code()).isEqualTo(2);
}
}