diff --git a/README.md b/README.md index 7e80370..62f0fbf 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,8 @@ # ai-engineering -An open, agent-agnostic engineering protocol and CLI. Works belong to an engineering -project spanning independent repositories. Canonical files preserve goals, discussion, +An open, agent-agnostic engineering protocol and CLI for simple projects and projects +spanning multiple repositories. Git is optional. Works belong to the engineering +project. Canonical files preserve goals, discussion, draft decisions and evidence so another person or agent can continue without chat history. Milestones 0 and 1 are implemented. The application runs locally in non-web mode; @@ -65,7 +66,38 @@ macOS x86_64 remains a target with an upstream toolchain availability limitation GraalVM 25 dropped that port; see [roadmap](docs/roadmap.md). Local verification results, including which native binaries were actually tested, are in [experiments](docs/experiments.md). -## Two-repository example +## Start in a simple project + +Run inside the folder you already use for your application, game or library: + +```sh +ai-engineering init --name "My Application" +ai-engineering work create "Improve the application" \ + --goal "Preserve enough context to continue in another session" +ai-engineering discussion add WRK-0001 --text "Record the current state and next questions." +ai-engineering decision draft WRK-0001 --title "Evaluate the proposed approach" +ai-engineering work context WRK-0001 --format markdown +ai-engineering project validate +``` + +This creates `.ai-engineering/` beside your existing source files. A project with +`repositories: []` is fully supported; the workflow above does not require Git to be +installed. Its Works have no Git revision snapshots. Git becomes relevant when you +choose to register repositories. + +If the project folder is itself an existing Git repository, you can register it: + +```sh +ai-engineering repo add app --path . +ai-engineering work create "Investigate a change" --repo app +``` + +Registration is optional and defaults to read-only. For example, a standalone +`zelda-1/` project can keep `.ai-engineering/` directly inside `zelda-1/`, without +registering the separate runtime or editor repositories. Each Work explicitly selects +any registered repositories it needs with `--repo`. + +## Multiple repositories in one project From an external project directory with existing `runtime/` and `studio/` Git repositories, run: diff --git a/docs/architecture.md b/docs/architecture.md index 3b36f2c..07e3e88 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -58,6 +58,12 @@ Context assembly belongs to Verification because it combines independently persi modules and refuses to export structurally inconsistent state. Work does not depend on Discussion, Decision or Artifact, avoiding cycles. It owns stable references only. +The engineering project is independent of repository count: a plain folder can use +the protocol with no Git dependency, a single Git repository can register the root +using `.`, and a larger workspace can register several child repositories. The same +configuration schema and services support each case; no separate project mode or +additional repository type is needed. + ## Persistence and native execution Writers take an OS file lock per project. Complete UTF-8 files are written to a sibling diff --git a/docs/experiments.md b/docs/experiments.md index 384c74d..1a14faa 100644 --- a/docs/experiments.md +++ b/docs/experiments.md @@ -132,6 +132,31 @@ JAVA_HOME=/nonexistent GRAALVM_HOME=/nonexistent PATH=/usr/bin:/bin:/usr/sbin:/s 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. diff --git a/docs/protocol.md b/docs/protocol.md index 5cb1d34..78870cf 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -6,6 +6,18 @@ The engineering root is the parent of `.ai-engineering`. Repository paths resolv against that root, independently of the CLI's current directory. Discovery searches upward or accepts an explicit `--project` root (or `.ai-engineering` directory). +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. + +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. + ```yaml schemaVersion: 1 project: @@ -30,8 +42,9 @@ never executable through this release. Unknown fields and schema versions fail v 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. Repositories cannot be the engineering root or live -inside `.ai-engineering`. Git inspection verifies an independent repository top-level; +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. diff --git a/docs/roadmap.md b/docs/roadmap.md index 6362df4..f22a5cc 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -16,6 +16,11 @@ discussion history, draft DECs, evidence integrity, structural validation and st Markdown/JSON context. Temporary-fixture tests cover continuity, independent Works, multiple repositories and malformed/missing/unsafe state. +Simple projects are supported directly: initialize in an existing source folder +without Git, or register a single existing Git repository using `repo add app --path .`. +No enclosing workspace or additional repositories are required. Regression coverage +includes fresh processes without Git on PATH and single-repository root discovery. + Acceptance demonstration: initialize a project with two independent Git repositories, create a Work referencing both, append discussion, persist a draft decision and evidence, export context, then reconstruct the same context in independent processes diff --git a/scripts/native-smoke.sh b/scripts/native-smoke.sh index 3484833..6cbda4a 100755 --- a/scripts/native-smoke.sh +++ b/scripts/native-smoke.sh @@ -17,6 +17,48 @@ else test "$?" -eq 2 fi +aie_without_git() { + PATH="$aie_fixture/no-installed-tools" "$aie_binary" "$@" +} + +# A source folder is a complete engineering project, even with no Git installed. +mkdir plain +cd plain +printf 'Existing source\n' > main.txt +aie_without_git init --name 'Simple Project' > init.yaml +aie_without_git work create 'Continue application' --goal 'Preserve local context' > work.yaml +aie_without_git discussion add WRK-0001 --text 'No repository is required' > discussion.yaml +aie_without_git artifact add WRK-0001 --file main.txt --purpose 'Initial source evidence' > artifact.yaml +aie_without_git decision draft WRK-0001 --title 'Pilot the protocol' --evidence ART-0001 > decision.yaml +aie_without_git work context WRK-0001 --format json > before.json +mkdir src +cd src +aie_without_git work context WRK-0001 --format json > ../after.json +cd .. +cmp before.json after.json +aie_without_git project validate --format json > validation.json +grep -q '"valid" : true' validation.json +test ! -e .git +cd "$aie_fixture" + +# A single Git repository can contain both the source and protocol workspace. +git init -q single +cd single +"$aie_binary" init --name 'Single Repository' > init.yaml +"$aie_binary" repo add app --path . > repo.yaml +"$aie_binary" work create 'Inspect application' --repo app > work.yaml +"$aie_binary" work context WRK-0001 --format json > before.json +mkdir src +cd src +"$aie_binary" work context WRK-0001 --format json > ../after.json +cd .. +cmp before.json after.json +grep -q '"repositoryId" : "app"' after.json +"$aie_binary" project validate --format json > validation.json +grep -q '"valid" : true' validation.json +cd "$aie_fixture" +echo 'Native simple-project continuity smoke passed (without Git and with one root repository).' + # Git initialization is fixture setup, never an implicit CLI operation. git init -q runtime git init -q studio diff --git a/src/main/java/net/intrepid/aiengineering/cli/EngineeringCli.java b/src/main/java/net/intrepid/aiengineering/cli/EngineeringCli.java index e218b3f..4724286 100644 --- a/src/main/java/net/intrepid/aiengineering/cli/EngineeringCli.java +++ b/src/main/java/net/intrepid/aiengineering/cli/EngineeringCli.java @@ -51,7 +51,7 @@ public final class EngineeringCli implements Runnable { } private int report(ValidationReport report, Format format) { emit(report, format); return report.valid() ? 0 : 4; } - @Command(name = "init", mixinStandardHelpOptions = true, description = "Initialize protocol files without modifying Git.") + @Command(name = "init", mixinStandardHelpOptions = true, description = "Initialize protocol files in this project folder; Git is optional.") int init(@Option(names = "--name", required = true) String name) { Path target = project == null ? cwd : resolve(project); return emit(projects.initialize(target, name), Format.markdown); @@ -66,7 +66,8 @@ public final class EngineeringCli implements Runnable { @Command(name = "repo", mixinStandardHelpOptions = true, description = "Register existing source repositories; default access is read-only.") public class RepoCommands { @Command(name = "add", mixinStandardHelpOptions = true) - int add(@Parameters(index = "0") String id, @Option(names = "--path", required = true) String path, + int add(@Parameters(index = "0") String id, + @Option(names = "--path", required = true, description = "Path relative to the project root; use . for the root repository.") String path, @Option(names = "--type", defaultValue = "linked-git") String type, @Option(names = "--language") String language, @Option(names = "--allow-edit") boolean edit, @Option(names = "--validation-command") List commands) { diff --git a/src/main/java/net/intrepid/aiengineering/project/ProjectService.java b/src/main/java/net/intrepid/aiengineering/project/ProjectService.java index 3365a51..556a74f 100644 --- a/src/main/java/net/intrepid/aiengineering/project/ProjectService.java +++ b/src/main/java/net/intrepid/aiengineering/project/ProjectService.java @@ -63,7 +63,7 @@ public final class ProjectService { } public Path repositoryPath(Path root, ProjectConfig.Repository repository) { Path path = Filespace.resolve(root, repository.path()); - if (path.equals(root) || path.startsWith(root.resolve(".ai-engineering"))) throw ProtocolException.invalid("Repository must be a source directory beneath project root"); + if (path.startsWith(root.resolve(".ai-engineering"))) throw ProtocolException.invalid("Repository must be outside .ai-engineering"); return path; } public void validate(Path root) { diff --git a/src/test/java/net/intrepid/aiengineering/ProcessContinuityTest.java b/src/test/java/net/intrepid/aiengineering/ProcessContinuityTest.java index 1a3c829..d518c90 100644 --- a/src/test/java/net/intrepid/aiengineering/ProcessContinuityTest.java +++ b/src/test/java/net/intrepid/aiengineering/ProcessContinuityTest.java @@ -11,18 +11,41 @@ import static org.assertj.core.api.Assertions.*; class ProcessContinuityTest { @TempDir Path root; private String cli(String... args) throws Exception { + return executeCli(false, args); + } + private String cliWithoutGit(String... args) throws Exception { + return executeCli(true, args); + } + private String executeCli(boolean withoutGit, 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(); + var builder = new ProcessBuilder(command).directory(root.toFile()).redirectErrorStream(true).redirectOutput(log.toFile()); + if (withoutGit) builder.environment().put("PATH", root.resolve("no-installed-tools").toString()); + var process = builder.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 simpleProjectWorksAcrossProcessesWithoutGitOnPath() throws Exception { + Path source = Files.writeString(root.resolve("main.txt"), "Existing project\n"); + cliWithoutGit("init", "--name", "Simple Project"); + assertThat(cliWithoutGit("repo", "list", "--format", "json").strip()).isEqualTo("[ ]"); + cliWithoutGit("work", "create", "Continue application", "--goal", "Preserve local context"); + cliWithoutGit("discussion", "add", "WRK-0001", "--text", "A simple folder is a complete engineering project"); + cliWithoutGit("artifact", "add", "WRK-0001", "--file", source.toString(), "--purpose", "Initial source evidence"); + cliWithoutGit("decision", "draft", "WRK-0001", "--title", "Pilot the protocol", "--evidence", "ART-0001"); + String context = cliWithoutGit("work", "context", "WRK-0001", "--format", "json"); + assertThat(cliWithoutGit("work", "context", "WRK-0001", "--format", "json")).isEqualTo(context) + .contains("Preserve local context", "\"repositories\" : [ ]", "Initial source evidence", "Pilot the protocol"); + assertThat(cliWithoutGit("project", "validate", "--format", "json")).contains("\"valid\" : true"); + assertThat(Files.exists(root.resolve(".git"))).isFalse(); + assertThat(Files.readString(source)).isEqualTo("Existing project\n"); + } @Test void independentJvmProcessesReconstructMultiRepositoryWork() throws Exception { cli("init", "--name", "Continuity Experiment"); for (String repo : List.of("runtime", "studio")) { diff --git a/src/test/java/net/intrepid/aiengineering/ProtocolIntegrationTest.java b/src/test/java/net/intrepid/aiengineering/ProtocolIntegrationTest.java index 36338ee..c0c9cfa 100644 --- a/src/test/java/net/intrepid/aiengineering/ProtocolIntegrationTest.java +++ b/src/test/java/net/intrepid/aiengineering/ProtocolIntegrationTest.java @@ -52,6 +52,28 @@ class ProtocolIntegrationTest { 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 singleGitRepositoryCanShareTheEngineeringProjectRoot() throws Exception { + var git = new ProcessBuilder("git", "init", root.toString()).redirectErrorStream(true).start(); + git.getInputStream().readAllBytes(); assertThat(git.waitFor()).isZero(); + Path source = Files.writeString(root.resolve("main.txt"), "Existing application source\n"); + byte[] gitConfig = Files.readAllBytes(root.resolve(".git/config")); + init(); ok("repo", "add", "app", "--path", "."); + assertThat(ok("repo", "list", "--format", "json").out()).contains("\"path\" : \".\"", "\"edit\" : false"); + ok("work", "create", "Improve application", "--repo", "app"); + String exported = ok("work", "context", "WRK-0001", "--format", "json").out(); + assertThat(exported).contains("\"repositoryId\" : \"app\"", "\"head\" : \"UNBORN\""); + Path nested = Files.createDirectories(root.resolve("src/feature")); + var fresh = run(nested, "work", "context", "WRK-0001", "--format", "json"); + assertThat(fresh.code()).as(fresh.err()).isZero(); assertThat(fresh.out()).isEqualTo(exported); + ok("project", "validate"); + assertThat(Files.readString(source)).isEqualTo("Existing application source\n"); + assertThat(Files.readAllBytes(root.resolve(".git/config"))).isEqualTo(gitConfig); + assertThat(run(root, "repo", "add", "duplicate", "--path", "./.").code()).isEqualTo(2); + } + @Test void protocolStorageCannotBeRegisteredAsASourceRepository() { + init(); + assertThat(run(root, "repo", "add", "protocol", "--path", ".ai-engineering").code()).isEqualTo(2); + } @Test void invalidIdentifiersMissingResourcesAndNoOverwrite() throws Exception { init(); assertThat(run(root, "init", "--name", "Again").code()).isEqualTo(2);