feat: promote draft decisions when creating plans

Promote referenced drafts deterministically with system provenance, causal
Plan links, supersession history and recovery from publication failures.
Preserve direct human approval and historical records.

Add JVM and native regression coverage and update the portable protocol.
Record the WRK-0007 importer decision and six-step plan, and complete
WRK-0008 with verification evidence.
This commit is contained in:
Nilton Constantino
2026-11-16 12:35:06 +00:00
parent 95c28e2e79
commit 3d2abb487f
101 changed files with 5322 additions and 14 deletions
@@ -0,0 +1,175 @@
package net.intrepid.aiengineering;
import net.intrepid.aiengineering.cli.EngineeringCli;
import net.intrepid.aiengineering.decision.*;
import net.intrepid.aiengineering.filesystem.*;
import net.intrepid.aiengineering.planning.PlanService;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import java.io.*;
import java.nio.file.*;
import java.util.*;
import static org.assertj.core.api.Assertions.*;
class PlanDecisionPromotionTest {
@TempDir Path root;
private String output;
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);
output = out + err.toString(); return code;
}
private void ok(String... args) { assertThat(cli(args)).as(output).isZero(); }
private void init() { ok("init", "--name", "Promotion"); ok("work", "create", "One"); }
private void draft(String title) {
ok("decision", "draft", "WRK-0001", "--title", title, "--context", "Problem", "--approach", "Approach", "--rationale", "Reason");
}
private void accept(String id) {
ok("decision", "accept", "WRK-0001", id, "--by", "owner", "--reason", "Explicit approval", "--human-approved");
}
private Decision decision(String id) { return new DecisionService().get(root, "WRK-0001", id); }
private Path folder() { return root.resolve(".ai-engineering/works/WRK-0001-one"); }
private Map<String, String> snapshot() throws IOException {
var result = new TreeMap<String, String>();
try (var files = Files.walk(folder())) {
for (var path : files.filter(Files::isRegularFile).toList()) result.put(folder().relativize(path).toString(), Files.readString(path));
}
return result;
}
@Test void creationPromotesDraftWithoutHumanAttestationOrConfiguredModelAndRetainsHistory() {
init(); draft("Chosen approach");
ok("plan", "create", "WRK-0001", "--title", "Delivery", "--decision", "DEC-0001", "--author", "requester");
var promoted = decision("DEC-0001"); var approval = promoted.approvals().getLast();
assertThat(promoted.approvalStatus()).isEqualTo(Decision.Status.ACCEPTED);
assertThat(promoted.revision()).isEqualTo(2);
assertThat(approval.origin()).isEqualTo(Decision.ApprovalOrigin.SYSTEM_PLAN);
assertThat(approval.planId()).isEqualTo("PLN-0001");
assertThat(approval.by()).isEqualTo("system:planning");
assertThat(approval.reason()).contains("requester");
assertThat(approval.humanApproved()).isFalse();
assertThat(new DecisionService().history(root, "WRK-0001", "DEC-0001")).extracting(Decision::approvalStatus)
.containsExactly(Decision.Status.DRAFT, Decision.Status.ACCEPTED);
ok("work", "context", "WRK-0001", "--format", "json");
assertThat(output).contains("SYSTEM_PLAN", "PLN-0001", "system:planning", "\"humanApproved\" : false");
ok("project", "validate"); ok("project", "compatibility");
// Another Plan from the same decision does not duplicate its promotion.
ok("plan", "create", "WRK-0001", "--title", "More delivery", "--decision", "DEC-0001");
assertThat(decision("DEC-0001")).isEqualTo(promoted);
}
@Test void multipleDraftsPromoteTogetherAndAlreadyAcceptedDecisionsStayByteIdentical() throws Exception {
init(); draft("One"); accept("DEC-0001"); draft("Two"); draft("Three");
String accepted = Files.readString(folder().resolve("decisions/DEC-0001.md"));
ok("plan", "create", "WRK-0001", "--title", "Delivery", "--decision", "DEC-0001", "--decision", "DEC-0002", "--decision", "DEC-0003");
assertThat(Files.readString(folder().resolve("decisions/DEC-0001.md"))).isEqualTo(accepted);
for (String id : List.of("DEC-0002", "DEC-0003")) assertThat(decision(id).approvals().getLast().planId()).isEqualTo("PLN-0001");
ok("project", "validate");
}
@Test void invalidReferencesOrInputsNeverPromoteEarlierDrafts() throws Exception {
init(); draft("Eligible"); draft("Rejected");
ok("decision", "reject", "WRK-0001", "DEC-0002", "--by", "reviewer", "--reason", "Rejected");
var before = snapshot();
for (String id : List.of("DEC-9999", "DEC-0002")) {
assertThat(cli("plan", "create", "WRK-0001", "--title", "Delivery", "--decision", "DEC-0001", "--decision", id)).isNotZero();
assertThat(snapshot()).isEqualTo(before);
}
assertThat(cli("plan", "create", "WRK-0001", "--title", " ", "--decision", "DEC-0001")).isNotZero();
assertThat(snapshot()).isEqualTo(before);
assertThat(cli("plan", "create", "WRK-0001", "--title", "Delivery", "--author", " ", "--decision", "DEC-0001")).isNotZero();
assertThat(snapshot()).isEqualTo(before);
}
@Test void incompleteDraftAndConflictingHistoryLeaveNoPromotion() throws Exception {
init(); draft("Eligible"); ok("decision", "draft", "WRK-0001", "--title", "Incomplete");
var before = snapshot();
assertThat(cli("plan", "create", "WRK-0001", "--title", "Delivery", "--decision", "DEC-0001", "--decision", "DEC-0002")).isEqualTo(4);
assertThat(output).contains("context, approach and rationale"); assertThat(snapshot()).isEqualTo(before);
Path history = folder().resolve("decisions/.history/DEC-0001/r0001.md");
Files.createDirectories(history.getParent()); Files.writeString(history, "Conflicting history"); before = snapshot();
assertThat(cli("plan", "create", "WRK-0001", "--title", "Delivery", "--decision", "DEC-0001")).isEqualTo(4);
assertThat(output).contains("Conflicting revision history"); assertThat(snapshot()).isEqualTo(before);
}
@Test void ordinaryPublicationFailureRollsBackEarlierPromotions() throws Exception {
init(); draft("One"); draft("Two");
// Force the second revision publication to fail after the first draft was promoted.
Path blocked = folder().resolve("decisions/.history/DEC-0002");
Files.createDirectories(blocked.getParent()); Files.writeString(blocked, "Directory occupied by a file");
var before = snapshot();
assertThat(cli("plan", "create", "WRK-0001", "--title", "Delivery", "--decision", "DEC-0001", "--decision", "DEC-0002")).isNotZero();
assertThat(snapshot()).isEqualTo(before);
assertThat(decision("DEC-0001").approvalStatus()).isEqualTo(Decision.Status.DRAFT);
assertThat(new PlanService().list(root, "WRK-0001")).isEmpty();
}
@Test void revisedDraftSupersedesParentWithTheSamePlanProvenance() {
init(); draft("Original"); accept("DEC-0001");
ok("decision", "revise", "WRK-0001", "DEC-0001", "--by", "editor", "--reason", "New information");
ok("plan", "create", "WRK-0001", "--title", "Revised delivery", "--decision", "DEC-0002");
assertThat(decision("DEC-0001").approvalStatus()).isEqualTo(Decision.Status.SUPERSEDED);
assertThat(decision("DEC-0001").supersededBy()).isEqualTo("DEC-0002");
assertThat(decision("DEC-0001").approvals().getLast().origin()).isEqualTo(Decision.ApprovalOrigin.SYSTEM_PLAN);
assertThat(decision("DEC-0001").approvals().getLast().humanApproved()).isFalse();
assertThat(decision("DEC-0002").approvalStatus()).isEqualTo(Decision.Status.ACCEPTED);
ok("project", "validate");
// The causal link remains valid after the Plan's current references are changed.
ok("plan", "update", "WRK-0001", "PLN-0001", "--clear-decisions", "--by", "owner", "--reason", "Scope changed");
ok("project", "validate");
}
@Test void conflictingRevisionsAndSupersededReferencesAreRejectedWithoutChanges() throws Exception {
init(); draft("Original"); accept("DEC-0001");
ok("decision", "revise", "WRK-0001", "DEC-0001", "--by", "editor", "--reason", "Alternative one");
ok("decision", "revise", "WRK-0001", "DEC-0001", "--by", "editor", "--reason", "Alternative two");
var before = snapshot();
assertThat(cli("plan", "create", "WRK-0001", "--title", "Conflict", "--decision", "DEC-0002", "--decision", "DEC-0003")).isEqualTo(2);
assertThat(snapshot()).isEqualTo(before);
assertThat(cli("plan", "create", "WRK-0001", "--title", "Conflict", "--decision", "DEC-0001", "--decision", "DEC-0002")).isEqualTo(2);
assertThat(snapshot()).isEqualTo(before);
ok("plan", "create", "WRK-0001", "--title", "Chosen", "--decision", "DEC-0002"); before = snapshot();
assertThat(cli("plan", "create", "WRK-0001", "--title", "Stale", "--decision", "DEC-0001")).isEqualTo(2);
assertThat(snapshot()).isEqualTo(before);
assertThat(cli("plan", "create", "WRK-0001", "--title", "Stale revision", "--decision", "DEC-0003")).isEqualTo(2);
assertThat(snapshot()).isEqualTo(before);
}
@Test void directAcceptanceStillNeedsHumanApprovalAndBrokenPromotionLinksAreDiagnosed() throws Exception {
init(); draft("Chosen");
assertThat(cli("decision", "accept", "WRK-0001", "DEC-0001", "--by", "agent", "--reason", "Not attested")).isEqualTo(2);
ok("plan", "create", "WRK-0001", "--title", "Delivery", "--decision", "DEC-0001");
ok("plan", "create", "WRK-0001", "--title", "Unrelated");
ok("plan", "update", "WRK-0001", "PLN-0002", "--decision", "DEC-0001", "--by", "owner", "--reason", "Later reference is not creation provenance");
Path promoted = folder().resolve("decisions/DEC-0001.md"); String original = Files.readString(promoted);
assertThat(original).contains("planId: \"PLN-0001\"");
Files.writeString(promoted, original.replace("planId: \"PLN-0001\"", "planId: \"PLN-0002\""));
assertThat(cli("work", "validate", "WRK-0001")).isEqualTo(4);
assertThat(output).contains("Promoting Plan does not reference"); Files.writeString(promoted, original);
Path plan = folder().resolve("plans/PLN-0001.md"); Files.delete(plan);
assertThat(cli("work", "validate", "WRK-0001")).isEqualTo(4);
assertThat(output).contains("PLN-0001");
assertThatThrownBy(() -> new Decision.Approval(Decision.Status.ACCEPTED, "agent", "Forged", java.time.Instant.now().toString(), false))
.isInstanceOf(ProtocolException.class).hasMessageContaining("human approval");
assertThatThrownBy(() -> new Decision.Approval(Decision.Status.ACCEPTED, "system:planning", "Forged", java.time.Instant.now().toString(), true,
Decision.ApprovalOrigin.SYSTEM_PLAN, "PLN-0001")).isInstanceOf(ProtocolException.class).hasMessageContaining("provenance");
}
@Test void occupiedPlanOutputDoesNotPromoteItsDecision() throws Exception {
init(); draft("Chosen");
Path occupied = folder().resolve("plans/PLN-0001.md"); Files.writeString(occupied, "Existing unindexed Plan");
var before = snapshot();
assertThat(cli("plan", "create", "WRK-0001", "--title", "Delivery", "--decision", "DEC-0001")).isEqualTo(4);
assertThat(output).contains("Unreferenced protocol file", "PLN-0001"); assertThat(snapshot()).isEqualTo(before);
}
@Test void separateCliProcessesCreatePlansButPromoteSharedDraftOnlyOnce() throws Exception {
init(); draft("Shared");
var command = List.of(Path.of(System.getProperty("java.home"), "bin", "java").toString(), "-jar", System.getProperty("cli.jar"),
"--project", root.toString(), "plan", "create", "WRK-0001", "--title", "Concurrent delivery", "--decision", "DEC-0001");
var first = new ProcessBuilder(command).redirectErrorStream(true).start();
var second = new ProcessBuilder(command).redirectErrorStream(true).start();
try {
for (var process : List.of(first, second)) {
assertThat(process.waitFor(30, java.util.concurrent.TimeUnit.SECONDS)).isTrue();
assertThat(process.exitValue()).as(new String(process.getInputStream().readAllBytes(), java.nio.charset.StandardCharsets.UTF_8)).isZero();
}
} finally { first.destroyForcibly(); second.destroyForcibly(); }
var plans = new PlanService().list(root, "WRK-0001");
assertThat(plans).extracting(net.intrepid.aiengineering.planning.Plan::id).containsExactly("PLN-0001", "PLN-0002");
var promoted = decision("DEC-0001"); assertThat(promoted.revision()).isEqualTo(2);
assertThat(promoted.approvals()).hasSize(1);
assertThat(promoted.approvals().getFirst().planId()).isEqualTo("PLN-0001");
ok("project", "validate");
}
}