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.
225 lines
17 KiB
Java
225 lines
17 KiB
Java
package net.intrepid.aiengineering.planning;
|
|
|
|
import net.intrepid.aiengineering.filesystem.*;
|
|
import net.intrepid.aiengineering.work.*;
|
|
import net.intrepid.aiengineering.decision.*;
|
|
import net.intrepid.aiengineering.artifact.ArtifactService;
|
|
import java.nio.file.*;
|
|
import java.time.Instant;
|
|
import java.util.*;
|
|
import java.util.function.Function;
|
|
|
|
public final class PlanService {
|
|
private final WorkService works = new WorkService();
|
|
private final DecisionService decisions = new DecisionService();
|
|
private Path path(Path root, String work, String id) { Work.identifier(id, "PLN"); return Filespace.resolve(works.folder(root, work), "plans/" + id + ".md"); }
|
|
private Plan read(Path path) { return Documents.readMarkdownDocument(path, Plan.class, "description"); }
|
|
public List<Plan> list(Path root, String work) {
|
|
return works.load(root, work).plans().stream().map(id -> {
|
|
var plan = read(path(root, work, id)); identity(plan, work, id); chain(root, plan); return plan;
|
|
}).toList();
|
|
}
|
|
private void identity(Plan plan, String work, String id) {
|
|
if (!plan.id().equals(id) || !plan.workId().equals(work)) throw ProtocolException.validation("Plan identity mismatch: " + id);
|
|
}
|
|
public Plan get(Path root, String work, String id) {
|
|
Work.identifier(id, "PLN"); return list(root, work).stream().filter(plan -> plan.id().equals(id)).findFirst()
|
|
.orElseThrow(() -> ProtocolException.missing("Plan not found: " + id));
|
|
}
|
|
private List<Plan> chain(Path root, Plan current) {
|
|
var history = new ArrayList<Plan>(); history.add(current); var next = current;
|
|
for (int revision = current.revision() - 1; revision >= 1; revision--) {
|
|
Path path = Revisions.history(works.folder(root, current.workId()), "plans", current.id(), revision); String original = Filespace.read(path);
|
|
Revisions.chain(next.revision(), next.previousHash(), revision + 1, original);
|
|
var prior = read(path); identity(prior, current.workId(), current.id());
|
|
if (prior.revision() != revision) throw ProtocolException.validation("Invalid plan history revision: " + path);
|
|
history.add(prior); next = prior;
|
|
}
|
|
Collections.reverse(history); return List.copyOf(history);
|
|
}
|
|
public List<Plan> history(Path root, String work, String id) { return chain(root, get(root, work, id)); }
|
|
private void accepted(Path root, String work, List<String> ids) {
|
|
authority(root, work, ids, false);
|
|
for (String id : ids) if (decisions.get(root, work, id).approvalStatus() != Decision.Status.ACCEPTED)
|
|
throw ProtocolException.invalid("Plan execution requires an accepted decision: " + id);
|
|
}
|
|
public void requireExecutionAuthority(Path root, String work, List<String> ids) { accepted(root, work, ids); }
|
|
private void authority(Path root, String work, List<String> ids, boolean creating) {
|
|
var guidance = works.load(root, work).guidance();
|
|
if (guidance == null) return; // Historical Work; adoption is explicit, never a migration on read.
|
|
guidance.requireMode();
|
|
if (ids.isEmpty() && (!guidance.waived() || guidance.mode() == WorkGuidance.Mode.EXPLORATORY))
|
|
throw ProtocolException.invalid("A DEC under applicable human authority is required before creating or executing this Plan");
|
|
for (String id : ids) {
|
|
var decision = decisions.get(root, work, id);
|
|
if (decision.approvalStatus() == Decision.Status.DRAFT && creating) {
|
|
guidance.requireDecisionRequest(id);
|
|
if (!guidance.waived()) throw ProtocolException.invalid("Human approval is required for " + id + "; creating a Plan cannot bypass it");
|
|
} else if (decision.approvalStatus() == Decision.Status.ACCEPTED && !guidance.waived()
|
|
&& !decision.approvals().getLast().humanApproved())
|
|
throw ProtocolException.invalid("Current Work policy requires human approval for " + id + "; system promotion is not human approval");
|
|
}
|
|
}
|
|
public Plan create(Path root, String workId, String title, String description, List<String> refs, String author) {
|
|
return Filespace.locked(root, () -> {
|
|
var work = works.editable(root, workId); String id = works.nextReference(work.plans(), "PLN"), now = Instant.now().toString();
|
|
authority(root, workId, refs, true);
|
|
if (work.guidance() != null && new net.intrepid.aiengineering.discussion.DiscussionService().hasPending(root, workId))
|
|
throw ProtocolException.invalid("Resolve pending discussion questions and surveys before creating a Plan");
|
|
var plan = new Plan(1, id, workId, title, description, refs, List.of(), Plan.Status.OPEN, author, now, 1, null, now, author, "Plan created");
|
|
Path path = path(root, workId, id), folder = works.folder(root, workId), workPath = Filespace.resolve(folder, "work.md");
|
|
if (Files.exists(path)) throw ProtocolException.invalid("Already exists: " + path);
|
|
String originalWork = Filespace.read(workPath), document = Documents.markdownDocument(plan, "description");
|
|
var promotions = decisions.preparePlanAcceptance(root, workId, refs, id, author);
|
|
Filespace.directory(path.getParent());
|
|
try {
|
|
promotions.publish(folder);
|
|
Filespace.write(path, document, false);
|
|
works.addReference(root, workId, "plans", id); return plan;
|
|
} catch (RuntimeException failure) {
|
|
try {
|
|
if (Files.exists(path)) {
|
|
if (!Filespace.read(path).equals(document)) throw ProtocolException.validation("Concurrent edit during Plan recovery: " + path);
|
|
Filespace.io(() -> { Files.delete(path); return null; });
|
|
}
|
|
promotions.rollback();
|
|
if (!Filespace.read(workPath).equals(originalWork)) Filespace.write(workPath, originalWork, true);
|
|
} catch (RuntimeException recovery) {
|
|
failure.addSuppressed(recovery);
|
|
throw new ProtocolException(4, "Plan creation interrupted; inspect " + workId + ": " + failure.getMessage() + "; recovery: " + recovery.getMessage());
|
|
}
|
|
throw failure;
|
|
}
|
|
});
|
|
}
|
|
private Plan mutate(Path root, String work, String id, String by, String reason, Function<Plan, Plan> mutation) {
|
|
return Filespace.locked(root, () -> {
|
|
works.editable(root, work); ProtocolException.text(by, "plan actor"); ProtocolException.text(reason, "plan change reason");
|
|
var old = get(root, work, id); String original = Filespace.read(path(root, work, id)); var candidate = mutation.apply(old);
|
|
if (candidate.equals(old)) return old;
|
|
var changed = candidate.snapshot(by, reason, Revisions.hash(original));
|
|
Revisions.replace(works.folder(root, work), "plans", id, old.revision(), original, Documents.markdownDocument(changed, "description"));
|
|
works.touched(root, work, changed.updatedAt()); return changed;
|
|
});
|
|
}
|
|
public Plan update(Path root, String work, String id, String title, String description, List<String> refs, String by, String reason) {
|
|
if (title == null && description == null && refs == null) throw ProtocolException.invalid("Specify a plan field to update");
|
|
return mutate(root, work, id, by, reason, old -> {
|
|
old.requireEditable(); if (refs != null) accepted(root, work, refs);
|
|
if (refs != null) for (var experiment : old.experiments()) {
|
|
String concern = experiment.questionsDecision();
|
|
if (concern != null && old.decisions().contains(concern) && !refs.contains(concern)
|
|
&& refs.stream().noneMatch(candidate -> replaces(root, work, candidate, concern)))
|
|
throw ProtocolException.invalid("Replace questioned DEC " + concern + " with its accepted revision; dropping the reference does not resolve evidence");
|
|
}
|
|
return old.content(title == null ? old.title() : title, description == null ? old.description() : description,
|
|
refs == null ? old.decisions() : refs, old.steps(), old.status());
|
|
});
|
|
}
|
|
private boolean replaces(Path root, String work, String candidate, String original) {
|
|
var seen = new HashSet<String>();
|
|
for (String current = candidate; current != null && seen.add(current); current = decisions.get(root, work, current).revises())
|
|
if (current.equals(original)) return true;
|
|
return false;
|
|
}
|
|
public Plan status(Path root, String work, String id, Plan.Status status, String by, String reason) {
|
|
ProtocolException.text(by, "plan actor"); ProtocolException.text(reason, "plan change reason");
|
|
var current = get(root, work, id);
|
|
if (current.status() == status) return current;
|
|
return mutate(root, work, id, by, reason, old -> {
|
|
// Reopening permits repairing stale references; starting steps still requires current authority.
|
|
if (status == Plan.Status.ACTIVE && !old.terminal()) accepted(root, work, old.decisions());
|
|
if (status == Plan.Status.COMPLETED) {
|
|
accepted(root, work, old.decisions());
|
|
if (!old.completionIssues().isEmpty()) throw ProtocolException.validation(String.join("; ", old.completionIssues()));
|
|
new ArtifactService().validate(root, work);
|
|
}
|
|
return old.content(old.title(), old.description(), old.decisions(), old.steps(), status);
|
|
});
|
|
}
|
|
/** Scope review retains the cancelled record and its revision chain. */
|
|
public Plan exclude(Path root, String work, String id, String step, String by, String reason) {
|
|
return mutate(root, work, id, by, reason, old -> old.exclude(step == null ? "PLAN" : step, by, reason));
|
|
}
|
|
/** Invoked by the coordination API; Planning never depends on Verification. */
|
|
public Plan consolidate(Path root, String work, String id) {
|
|
var plan = get(root, work, id);
|
|
if (plan.status() != Plan.Status.OPEN && plan.status() != Plan.Status.ACTIVE) return plan;
|
|
if (!plan.completionIssues().isEmpty()) return plan;
|
|
var history = history(root, work, id);
|
|
for (int i = history.size() - 1; i > 0; i--) {
|
|
if (history.get(i - 1).terminal() && history.get(i).status() == Plan.Status.ACTIVE) {
|
|
Instant reopened = Instant.parse(history.get(i).updatedAt());
|
|
if (plan.steps().stream().noneMatch(s -> Instant.parse(s.updatedAt()).isAfter(reopened))) return plan;
|
|
break;
|
|
}
|
|
}
|
|
return status(root, work, id, Plan.Status.COMPLETED, "system:plans", "All required steps completed; reviewed cancellations retained");
|
|
}
|
|
public Plan addStep(Path root, String work, String id, String title, String description, List<String> criteria, List<String> deps, String by, String reason) {
|
|
return mutate(root, work, id, by, reason, old -> {
|
|
old.requireEditable(); String stepId = works.nextReference(old.steps().stream().map(Plan.Step::id).toList(), "TSK");
|
|
var steps = new ArrayList<>(old.steps()); steps.add(new Plan.Step(stepId, title, description, criteria, deps, Plan.Status.OPEN, "", List.of(), Instant.now().toString()));
|
|
return old.content(old.title(), old.description(), old.decisions(), steps, old.status());
|
|
});
|
|
}
|
|
private Plan.Step step(Plan plan, String id) {
|
|
Work.identifier(id, "TSK"); return plan.steps().stream().filter(step -> step.id().equals(id)).findFirst()
|
|
.orElseThrow(() -> ProtocolException.missing("Plan step not found: " + id));
|
|
}
|
|
public Plan updateStep(Path root, String work, String id, String stepId, String title, String description, List<String> criteria, List<String> deps, String by, String reason) {
|
|
if (title == null && description == null && criteria == null && deps == null) throw ProtocolException.invalid("Specify a step field to update");
|
|
return mutate(root, work, id, by, reason, old -> {
|
|
old.requireEditable(); var previous = step(old, stepId);
|
|
if (previous.status() == Plan.Status.COMPLETED || previous.status() == Plan.Status.CANCELLED) throw ProtocolException.invalid("Reopen the step before editing its scope");
|
|
var changed = new Plan.Step(stepId, title == null ? previous.title() : title, description == null ? previous.description() : description,
|
|
criteria == null ? previous.acceptanceCriteria() : criteria, deps == null ? previous.dependsOn() : deps, previous.status(), previous.result(), previous.evidence(), Instant.now().toString());
|
|
var steps = old.steps().stream().map(step -> step.id().equals(stepId) ? changed : step).toList();
|
|
return old.content(old.title(), old.description(), old.decisions(), steps, old.status());
|
|
});
|
|
}
|
|
public Plan stepStatus(Path root, String work, String id, String stepId, Plan.Status target, String by, String reason, List<String> evidence) {
|
|
return mutate(root, work, id, by, reason, old -> {
|
|
old.requireEditable(); var previous = step(old, stepId);
|
|
if (target == Plan.Status.ACTIVE || target == Plan.Status.COMPLETED) {
|
|
accepted(root, work, old.decisions()); old.requireExperimentReady(stepId);
|
|
}
|
|
if (!works.load(root, work).artifacts().containsAll(evidence)) throw ProtocolException.invalid("Unknown step evidence");
|
|
if (target == Plan.Status.COMPLETED) new ArtifactService().validate(root, work);
|
|
var changed = new Plan.Step(stepId, previous.title(), previous.description(), previous.acceptanceCriteria(), previous.dependsOn(), target, reason, evidence, Instant.now().toString());
|
|
var steps = old.steps().stream().map(step -> step.id().equals(stepId) ? changed : step).toList();
|
|
var status = old.status() == Plan.Status.OPEN && (target == Plan.Status.ACTIVE || target == Plan.Status.COMPLETED) ? Plan.Status.ACTIVE : old.status();
|
|
return old.content(old.title(), old.description(), old.decisions(), steps, status);
|
|
});
|
|
}
|
|
public Plan startExperiment(Path root, String work, String id, String stepId, String hypothesis, String criterion,
|
|
String invocation, String retry, String reconsideration, String by, String reason) {
|
|
return mutate(root, work, id, by, reason, old -> {
|
|
old.requireEditable(); accepted(root, work, old.decisions());
|
|
ProtocolException.text(hypothesis, "experiment hypothesis");
|
|
if (works.load(root, work).guidance() == null) throw ProtocolException.invalid("Adopt Work guidance before recording Plan experiments");
|
|
if (stepId != null) step(old, stepId);
|
|
for (var prior : old.experiments()) if (prior.failed() && Experiment.normalized(prior.hypothesis()).equals(Experiment.normalized(hypothesis))
|
|
&& (retry == null || reconsideration == null || reconsideration.isBlank()))
|
|
throw ProtocolException.invalid("Reconsider the failed hypothesis with --retry-of and --reconsideration before repeating it");
|
|
var experiment = new Experiment(works.nextReference(old.experiments().stream().map(Experiment::id).toList(), "EXP"), stepId,
|
|
hypothesis, criterion, invocation, retry, reconsideration, by, Instant.now().toString(), Experiment.Outcome.OPEN,
|
|
null, null, null, List.of(), null, null, null);
|
|
var all = new ArrayList<>(old.experiments()); all.add(experiment); return old.withExperiments(all);
|
|
});
|
|
}
|
|
public Plan finishExperiment(Path root, String work, String id, String experimentId, Experiment.Outcome outcome,
|
|
String observation, String interpretation, String nextAction, List<String> evidence, String concern, String by, String reason) {
|
|
return mutate(root, work, id, by, reason, old -> {
|
|
old.requireEditable();
|
|
var experiment = old.experiments().stream().filter(e -> e.id().equals(experimentId)).findFirst()
|
|
.orElseThrow(() -> ProtocolException.missing("Experiment not found: " + experimentId));
|
|
if (!works.load(root, work).artifacts().containsAll(evidence)) throw ProtocolException.invalid("Unknown experiment evidence");
|
|
new ArtifactService().validate(root, work);
|
|
if (concern != null && !old.decisions().contains(concern)) throw ProtocolException.invalid("Questioned DEC must belong to the Plan");
|
|
var result = experiment.finish(outcome, observation, interpretation, nextAction, evidence, concern, by);
|
|
return old.withExperiments(old.experiments().stream().map(e -> e.id().equals(experimentId) ? result : e).toList());
|
|
});
|
|
}
|
|
}
|