Test / Tests and coverage occurred while executing withChecks step.
Intrepid/AI Engineering/pipeline/head There was a failure building this commit
build / jvm (push) Canceled after 0s
build / native (macos-15, macos-arm64) (push) Canceled after 0s
build / native (ubuntu-24.04, linux-x86_64) (push) Canceled after 0s
build / native (windows-2025, windows-x86_64) (push) Canceled after 0s
Persist explicit human discussion choices, DEC requests and approval policies. Add optional evidence-backed Plan experiments and align context, adapters and next actions under protocol contract 3. Include WRK-000B decisions, plan history and verification evidence: 167 JVM tests, 25 focused checks, Jenkins fixtures and native smoke coverage.
175 lines
13 KiB
Java
175 lines
13 KiB
Java
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.Decision;
|
|
import net.intrepid.aiengineering.planning.Plan;
|
|
import net.intrepid.aiengineering.artifact.Artifact;
|
|
import net.intrepid.aiengineering.agent.AgentRun;
|
|
import tools.jackson.databind.node.ObjectNode;
|
|
import java.nio.file.*;
|
|
import java.util.*;
|
|
|
|
/** Format inspection only. Does not lock, write, migrate, reopen or reinterpret historical approvals. */
|
|
public final class CompatibilityService {
|
|
public enum State { CURRENT, LEGACY_COMPATIBLE, UNSUPPORTED, INVALID }
|
|
public record Summary(State state, boolean readable, boolean migrationRequired, String command) {}
|
|
public record Finding(String path, String recordType, State state, Map<String, String> versions,
|
|
List<String> missingFields, String message) {
|
|
public Finding { versions = Collections.unmodifiableMap(new LinkedHashMap<>(versions)); missingFields = List.copyOf(missingFields); }
|
|
}
|
|
public record Report(int schemaVersion, String cliVersion, int currentProtocolVersion,
|
|
List<Integer> readableProtocolVersions, List<FormatVersions.Format> formats, State state,
|
|
boolean readable, boolean migrationRequired, List<Finding> findings, List<String> guidance) {
|
|
public Report {
|
|
readableProtocolVersions = List.copyOf(readableProtocolVersions); formats = List.copyOf(formats);
|
|
findings = List.copyOf(findings); guidance = List.copyOf(guidance);
|
|
}
|
|
public Summary summary() { return new Summary(state, readable, migrationRequired, "aie project compatibility --format json"); }
|
|
}
|
|
private record RecordType(String area, Class<?> type, String bodyField) {}
|
|
private static final List<RecordType> RECORDS = List.of(
|
|
new RecordType("discussions", DiscussionEntry.class, "text"), new RecordType("decisions", Decision.class, "text"),
|
|
new RecordType("plans", Plan.class, "description"), new RecordType("topics", Topic.class, "description"),
|
|
new RecordType("surveys", Survey.class, "description"), new RecordType("dispositions", Disposition.class, "reason"),
|
|
new RecordType("agent-runs", AgentRun.class, "task"), new RecordType("epic", Epic.class, "reason"));
|
|
private static final List<String> WORK_DEFAULTS = List.of("plans", "completions", "events", "archived",
|
|
"topics", "surveys", "dispositions", "agentRuns", "epic", "guidance");
|
|
|
|
public Report inspect(Path root) {
|
|
var findings = new ArrayList<Finding>();
|
|
inspect(root, ".ai-engineering/ai-engineering.yaml", "project", ProjectConfig.class, null, false, findings);
|
|
Path manifest = Filespace.resolve(root, ".ai-engineering/protocol.json");
|
|
if (Files.exists(manifest)) inspect(root, ".ai-engineering/protocol.json", "manifest", ProtocolGuide.Manifest.class, null, false, findings);
|
|
else findings.add(new Finding(".ai-engineering/protocol.json", "manifest", State.LEGACY_COMPATIBLE, Map.of(), List.of(),
|
|
"No discovery manifest. Existing records are inspected independently; onboard can install the entry instructions."));
|
|
if (findings.stream().noneMatch(f -> f.recordType().equals("manifest") && (f.state() == State.UNSUPPORTED || f.state() == State.INVALID))) {
|
|
try { ProtocolGuide.validate(root); }
|
|
catch (RuntimeException e) { invalid(findings, ".ai-engineering/protocol.json", "entry-contract", e.getMessage()); }
|
|
}
|
|
Path workspace = Filespace.resolve(root, ".ai-engineering/works");
|
|
Path sequence = Filespace.resolve(root, ".ai-engineering/works/.sequence.yaml");
|
|
if (Files.exists(sequence)) inspect(root, root.relativize(sequence).toString(), "sequence", WorkService.Sequence.class, null, false, findings);
|
|
visit(root, workspace, findings, folder -> {
|
|
Path workFile = folder.resolve("work.md");
|
|
inspect(root, relative(root, workFile), "work", Work.class, null, true, findings);
|
|
if (!Files.exists(sequence)) invalid(findings, relative(root, sequence), "sequence", "Missing Work sequence");
|
|
for (var record : RECORDS) {
|
|
Path area = Filespace.resolve(root, relative(root, folder.resolve(record.area())));
|
|
if (!Files.exists(area)) continue;
|
|
visit(root, area, findings, file -> inspectRecord(root, file, record, findings));
|
|
Path history = Filespace.resolve(root, relative(root, area.resolve(".history")));
|
|
if (Files.exists(history)) visit(root, history, findings,
|
|
revisions -> visit(root, revisions, findings, file -> inspectRecord(root, file, record, findings)));
|
|
}
|
|
Path evidence = Filespace.resolve(root, relative(root, folder.resolve("artifacts/evidence")));
|
|
if (Files.exists(evidence)) visit(root, evidence, findings, artifact -> {
|
|
Path manifestPath = artifact.resolve("artifact.yaml");
|
|
inspect(root, relative(root, manifestPath), "artifact", Artifact.class, null, false, findings);
|
|
if (findings.getLast().state() == State.INVALID || findings.getLast().state() == State.UNSUPPORTED) return;
|
|
var record = Documents.read(manifestPath, Artifact.class);
|
|
Class<?> receipt = record.origin().startsWith(PlanCoordinator.RECEIPT_ORIGIN) ? PlanCoordinator.Receipt.class
|
|
: record.origin().startsWith(EpicCoordinator.RECEIPT_ORIGIN) ? EpicCoordinator.Receipt.class
|
|
: record.origin().startsWith(net.intrepid.aiengineering.legacyimport.DiscussionImport.RECEIPT_ORIGIN)
|
|
? net.intrepid.aiengineering.legacyimport.DiscussionImport.Receipt.class : null;
|
|
if (receipt != null) inspect(root, relative(root, Filespace.resolve(folder, record.path())),
|
|
receipt == net.intrepid.aiengineering.legacyimport.DiscussionImport.Receipt.class ? "discussion-import-receipt" : "completion-receipt", receipt, null, false, findings);
|
|
});
|
|
// Missing referenced records are not evidence of a readable historical format.
|
|
try {
|
|
Work work = Documents.readDocument(workFile, Work.class);
|
|
var references = new LinkedHashMap<String, List<String>>();
|
|
references.put("discussions", work.discussions()); references.put("decisions", work.decisions());
|
|
references.put("plans", work.plans()); references.put("topics", work.topics()); references.put("surveys", work.surveys());
|
|
references.put("dispositions", work.dispositions()); references.put("agent-runs", work.agentRuns());
|
|
references.put("epic", work.epic() ? List.of(work.id()) : List.of());
|
|
references.forEach((area, ids) -> ids.forEach(id -> {
|
|
String path = relative(root, folder.resolve(area).resolve(id + ".md"));
|
|
if (!Files.isRegularFile(Filespace.resolve(root, path))) invalid(findings, path, area, "Missing referenced record");
|
|
}));
|
|
for (String id : work.artifacts()) {
|
|
String path = relative(root, folder.resolve("artifacts/evidence/" + id + "/artifact.yaml"));
|
|
if (!Files.isRegularFile(Filespace.resolve(root, path))) invalid(findings, path, "artifact", "Missing referenced artifact manifest");
|
|
}
|
|
} catch (RuntimeException ignored) { /* The Work's parse diagnostic was already recorded above. */ }
|
|
});
|
|
// Presence/version inspection is independent from structural/evidence validation.
|
|
State state = findings.stream().map(Finding::state).max(Comparator.naturalOrder()).orElse(State.CURRENT);
|
|
boolean readable = state == State.CURRENT || state == State.LEGACY_COMPATIBLE;
|
|
var guidance = new ArrayList<String>();
|
|
if (readable) guidance.add("No migration is required. Keep readable historical and COMPLETED Works in their existing formats.");
|
|
else guidance.add("Unsupported versions require a compatible CLI; invalid files require deliberate repair. No migration route is inferred.");
|
|
guidance.add("onboard refreshes entry instructions only, with backups; it does not convert Works or their history.");
|
|
guidance.add("Compatibility describes storage readability, not completion readiness or evidence integrity. Run aie project validate separately.");
|
|
return new Report(1, ProtocolContract.CLI_VERSION, ProtocolContract.CURRENT, ProtocolContract.READABLE,
|
|
FormatVersions.supported(), state, readable, false, findings, guidance);
|
|
}
|
|
private void inspectRecord(Path root, Path path, RecordType type, List<Finding> findings) {
|
|
inspect(root, relative(root, path), type.area(), type.type(), type.bodyField(), true, findings);
|
|
}
|
|
private static String relative(Path root, Path path) { return root.relativize(path).toString(); }
|
|
private void visit(Path root, Path directory, List<Finding> findings, java.util.function.Consumer<Path> operation) {
|
|
try {
|
|
Path safe = Filespace.resolve(root, relative(root, directory));
|
|
for (Path child : Filespace.children(safe)) {
|
|
try { operation.accept(Filespace.resolve(root, relative(root, child))); }
|
|
catch (RuntimeException e) { invalid(findings, relative(root, child), "directory", e.getMessage()); }
|
|
}
|
|
} catch (RuntimeException e) { invalid(findings, relative(root, directory), "directory", e.getMessage()); }
|
|
}
|
|
private static void invalid(List<Finding> findings, String path, String type, String message) {
|
|
findings.add(new Finding(path, type, State.INVALID, Map.of(), List.of(), message == null ? "Cannot inspect record" : message));
|
|
}
|
|
private static final class UnsupportedFormat extends RuntimeException {
|
|
UnsupportedFormat(String message) { super(message); }
|
|
}
|
|
private boolean version(ObjectNode metadata, String field, Integer defaultVersion, FormatVersions.Format format, Map<String, String> versions) {
|
|
var value = metadata.get(field);
|
|
versions.put(field, value == null ? defaultVersion == null ? "missing" : "implicit " + defaultVersion : value.toString());
|
|
int actual;
|
|
if (value == null && defaultVersion != null) actual = defaultVersion;
|
|
else {
|
|
if (value == null || !value.isIntegralNumber() || value.bigIntegerValue().signum() <= 0)
|
|
throw ProtocolException.validation(field + " must be a positive integer");
|
|
if (!value.canConvertToInt()) throw new UnsupportedFormat("Unsupported " + field + ": " + value);
|
|
actual = value.intValue();
|
|
}
|
|
if (!format.supports(actual)) throw new UnsupportedFormat("Unsupported " + field + ": " + actual);
|
|
return actual != format.currentWriteVersion();
|
|
}
|
|
private void inspect(Path root, String relative, String name, Class<?> type, String bodyField, boolean markdown, List<Finding> findings) {
|
|
var versions = new LinkedHashMap<String, String>(); var missing = new ArrayList<String>();
|
|
try {
|
|
Path path = Filespace.resolve(root, relative);
|
|
boolean json = type == ProtocolGuide.Manifest.class || type == PlanCoordinator.Receipt.class || type == EpicCoordinator.Receipt.class
|
|
|| type == net.intrepid.aiengineering.legacyimport.DiscussionImport.Receipt.class;
|
|
ObjectNode metadata = markdown ? Documents.metadata(path) : json
|
|
? Documents.readJson(path, ObjectNode.class) : Documents.read(path, ObjectNode.class);
|
|
if (metadata == null) throw ProtocolException.validation("Expected record object");
|
|
var format = type == WorkService.Sequence.class ? FormatVersions.SEQUENCE
|
|
: type == ProtocolGuide.Manifest.class ? FormatVersions.MANIFEST : FormatVersions.SCHEMA;
|
|
boolean legacy = version(metadata, "schemaVersion", null, format, versions);
|
|
if (markdown) legacy |= version(metadata, "documentVersion", 1,
|
|
bodyField == null ? FormatVersions.METADATA : FormatVersions.DOCUMENT, versions);
|
|
if (type == ProtocolGuide.Manifest.class) {
|
|
legacy |= version(metadata, "protocolVersion", 1,
|
|
new FormatVersions.Format("protocol-contract", ProtocolContract.CURRENT, ProtocolContract.READABLE), versions);
|
|
if (!metadata.has("protocolVersion")) { legacy = true; missing.add("protocolVersion"); }
|
|
}
|
|
if (type == Work.class) for (String field : WORK_DEFAULTS) if (!metadata.has(field)) { missing.add(field); legacy = true; }
|
|
if (markdown) Documents.readMarkdownDocument(path, type, bodyField);
|
|
else if (json) Documents.readJson(path, type);
|
|
else Documents.read(path, type);
|
|
findings.add(new Finding(relative, name, legacy ? State.LEGACY_COMPATIBLE : State.CURRENT, versions, missing,
|
|
legacy ? "Readable legacy format; defaults are interpreted in memory. No migration required."
|
|
: "Readable current format."));
|
|
} catch (UnsupportedFormat e) {
|
|
findings.add(new Finding(relative, name, State.UNSUPPORTED, versions, missing, e.getMessage() + "; use a compatible CLI."));
|
|
} catch (RuntimeException e) {
|
|
findings.add(new Finding(relative, name, State.INVALID, versions, missing, e.getMessage() == null ? "Invalid record" : e.getMessage()));
|
|
}
|
|
}
|
|
}
|