feat: add Work guidance and adaptive Plan experiments
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
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.
This commit is contained in:
@@ -39,12 +39,33 @@ public final class PlanService {
|
||||
}
|
||||
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);
|
||||
@@ -85,15 +106,29 @@ public final class PlanService {
|
||||
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()));
|
||||
@@ -146,7 +181,9 @@ public final class PlanService {
|
||||
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());
|
||||
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());
|
||||
@@ -155,4 +192,33 @@ public final class PlanService {
|
||||
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());
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user