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,101 @@
package net.intrepid.aiengineering.verification;
import net.intrepid.aiengineering.filesystem.*;
import net.intrepid.aiengineering.project.*;
import net.intrepid.aiengineering.work.*;
import net.intrepid.aiengineering.discussion.*;
import net.intrepid.aiengineering.decision.*;
import net.intrepid.aiengineering.artifact.*;
import java.nio.file.*;
import java.util.*;
public final class VerificationService {
private final ProjectService projects = new ProjectService();
private final WorkService works = new WorkService();
private final DiscussionService discussions = new DiscussionService();
private final DecisionService decisions = new DecisionService();
private final ArtifactService artifacts = new ArtifactService();
private void check(List<String> issues, Runnable operation) {
try { operation.run(); } catch (RuntimeException e) { issues.add(e.getMessage() == null ? e.getClass().getSimpleName() : e.getMessage()); }
}
public ValidationReport project(Path root) {
var issues = new ArrayList<String>();
check(issues, () -> projects.validate(root));
check(issues, () -> {
var all = works.list(root);
Path counter = Filespace.resolve(works.workspace(root), ".sequence.yaml");
if (!all.isEmpty()) {
var sequence = Documents.read(counter, WorkService.Sequence.class);
long max = all.stream().mapToLong(w -> Long.parseLong(w.id().substring(4))).max().orElse(0);
if (sequence.lastWork() < max) issues.add("Work sequence is below the highest reserved ID");
}
all.forEach(w -> issues.addAll(work(root, w.id()).issues()));
});
for (String directory : List.of("works", "contracts", ".local"))
check(issues, () -> { if (!Files.isDirectory(Filespace.resolve(root, ".ai-engineering/" + directory))) issues.add("Missing project directory: " + directory); });
return new ValidationReport(issues.isEmpty(), issues);
}
public ValidationReport work(Path root, String id) {
var issues = new ArrayList<String>();
check(issues, () -> {
Work work = works.load(root, id); Path folder = works.folder(root, id);
var registered = projects.load(root).repositories().stream().map(ProjectConfig.Repository::id).toList();
for (var revision : work.repositories()) {
if (!registered.contains(revision.repositoryId())) issues.add("Unknown Work repository: " + revision.repositoryId());
check(issues, () -> Filespace.resolve(root, revision.path()));
}
for (String directory : List.of("discussions", "decisions", "artifacts/references", "artifacts/experiments", "artifacts/evidence", "artifacts/outputs", "runs"))
check(issues, () -> { if (!Files.isDirectory(Filespace.resolve(folder, directory))) issues.add("Missing Work directory: " + directory); });
check(issues, () -> {
var entries = discussions.list(root, id);
var seen = new HashSet<String>();
for (var entry : entries) {
if (entry.respondsTo() != null && !seen.contains(entry.respondsTo())) issues.add("Discussion response must reference an earlier entry: " + entry.id());
seen.add(entry.id());
}
});
check(issues, () -> decisions.list(root, id).forEach(d -> {
if (!work.artifacts().containsAll(d.evidence())) issues.add("Missing decision evidence: " + d.id());
}));
check(issues, () -> artifacts.validate(root, id));
check(issues, () -> orphans(issues, folder, "discussions", work.discussions().stream().map(s -> s + ".md").toList()));
check(issues, () -> orphans(issues, folder, "decisions", work.decisions().stream().map(s -> s + ".md").toList()));
check(issues, () -> orphans(issues, folder, "artifacts/evidence", work.artifacts()));
});
return new ValidationReport(issues.isEmpty(), issues);
}
private void orphans(List<String> issues, Path folder, String directory, List<String> expected) {
for (Path entry : Filespace.children(Filespace.resolve(folder, directory))) {
Filespace.resolve(folder, folder.relativize(entry).toString());
if (!expected.contains(entry.getFileName().toString())) issues.add("Unreferenced protocol file: " + directory + "/" + entry.getFileName());
}
}
public record Context(int schemaVersion, Work work, List<DiscussionEntry> discussionHistory, List<DraftDecision> decisions,
List<String> outstandingQuestions, List<Artifact> artifacts) {}
public Context context(Path root, String id) {
var report = work(root, id);
if (!report.valid()) throw ProtocolException.validation(String.join("; ", report.issues()));
var history = discussions.list(root, id);
var answered = history.stream().filter(e -> e.kind() == DiscussionEntry.Kind.RESPONSE || e.kind() == DiscussionEntry.Kind.CONCLUSION)
.map(DiscussionEntry::respondsTo).filter(Objects::nonNull).toList();
var outstanding = history.stream().filter(e -> e.kind() == DiscussionEntry.Kind.QUESTION || e.kind() == DiscussionEntry.Kind.ISSUE)
.filter(e -> !answered.contains(e.id())).map(e -> e.id() + ": " + e.text()).toList();
return new Context(1, works.load(root, id), history, decisions.list(root, id), outstanding, artifacts.list(root, id));
}
public String markdown(Context context) {
var w = context.work();
var result = new StringBuilder("# " + w.id() + " — " + w.title() + "\n\nProtocol schema: 1\n\nStatus: " + w.status() + "\n");
section(result, "Goal", w.goal()); section(result, "Description", w.description()); section(result, "Motivation", w.motivation());
section(result, "Constraints", items(w.constraints())); section(result, "Acceptance criteria", items(w.acceptanceCriteria()));
section(result, "Repository revisions at Work creation", yaml(w.repositories()));
section(result, "Discussion history and conclusions", yaml(context.discussionHistory()));
section(result, "Decisions (approval status is explicit)", yaml(context.decisions()));
section(result, "Outstanding questions", items(context.outstandingQuestions()));
section(result, "Artifact references (paths relative to Work)", yaml(context.artifacts()));
section(result, "Metadata", "Created: " + w.createdAt() + "\n\nUpdated: " + w.updatedAt() + "\n\nAuthor: " + w.author());
return result.toString();
}
private static String items(List<String> values) { return values.isEmpty() ? "None recorded." : String.join("\n", values.stream().map(v -> "- " + v).toList()); }
private static String yaml(Object value) { return "```yaml\n" + Documents.yaml(value) + "```"; }
private static void section(StringBuilder out, String title, String body) { out.append("\n## ").append(title).append("\n\n").append(body.isBlank() ? "None recorded." : body).append('\n'); }
}