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

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:
2026-11-16 17:33:24 +00:00
parent 3c75ce70f6
commit f5d5db73c2
104 changed files with 4432 additions and 106 deletions
@@ -39,7 +39,7 @@ public final class EngineeringCli implements Runnable {
.addSubcommand("project", new ProjectCommands()).addSubcommand("repo", new RepoCommands())
.addSubcommand("work", new WorkCommands()).addSubcommand("discussion", new DiscussionCommands())
.addSubcommand("decision", new DecisionCommands()).addSubcommand("artifact", new ArtifactCommands())
.addSubcommand("plan", new CommandLine(new PlanCommands()).addSubcommand("step", new StepCommands()))
.addSubcommand("plan", new CommandLine(new PlanCommands()).addSubcommand("step", new StepCommands()).addSubcommand("experiment", new ExperimentCommands()))
.addSubcommand("topic", new TopicCommands()).addSubcommand("survey", new SurveyCommands()).addSubcommand("agent", new AgentCommands())
.addSubcommand("epic", new EpicCommands());
commandLine.addSubcommand("import", new CommandLine(new ImportCommands()).addSubcommand("discussion", new DiscussionImportCommand()));
@@ -213,6 +213,27 @@ public final class EngineeringCli implements Runnable {
}
@Command(name = "work", mixinStandardHelpOptions = true, description = "Create, inspect, validate and export Works.")
public class WorkCommands {
@Command(name = "guidance", mixinStandardHelpOptions = true, description = "Show or record explicit human discussion mode and Work-wide DEC approval policy; choices are never inferred.")
int guidance(@Parameters(index = "0") String id,
@Option(names = "--mode") WorkGuidance.Mode mode,
@Option(names = "--approval") WorkGuidance.ApprovalPolicy policy,
@Option(names = "--by") String by, @Option(names = "--reason") String reason,
@Option(names = "--human-approved") boolean humanApproved,
@Option(names = "--format", defaultValue = "markdown") Format format) {
if (mode == null && policy == null) {
if (by != null || reason != null || humanApproved) throw ProtocolException.invalid("Specify --mode or --approval to record a human choice");
return emit(works.load(root(), id).guidance(), format);
}
return change(id, by, () -> works.guidance(root(), id, mode, policy, by, reason, humanApproved), format);
}
@Command(name = "request-decision", mixinStandardHelpOptions = true, description = "Record the human's request for the next DEC; exploratory discussion cannot end itself.")
int requestDecision(@Parameters(index = "0") String id,
@Option(names = "--decision", description = "Explicit existing DEC, for example when a direct discussion becomes exploratory; default is the next DEC.") String decision,
@Option(names = "--by", required = true) String by, @Option(names = "--reason", required = true) String reason,
@Option(names = "--human-approved", required = true) boolean humanApproved,
@Option(names = "--format", defaultValue = "markdown") Format format) {
return change(id, by, () -> works.requestDecision(root(), id, decision, by, reason, humanApproved), format);
}
@Command(name = "reconcile", mixinStandardHelpOptions = true, description = "Consolidate Plans and recover missed completion/EPIC propagation; no model is invoked.")
int reconcile(@Parameters(index = "0") String id,
@Option(names = "--requester", defaultValue = "human") String requester,
@@ -228,8 +249,14 @@ public final class EngineeringCli implements Runnable {
@Option(names = "--constraint") List<String> constraints,
@Option(names = "--acceptance") List<String> criteria,
@Option(names = "--repo") List<String> repositories,
@Option(names = "--author", defaultValue = "human") String author) {
return emit(works.create(root(), title, description, goal, motivation, safe(constraints), safe(criteria), safe(repositories), author), Format.markdown);
@Option(names = "--author", defaultValue = "human") String author,
@Option(names = "--mode", description = "Human choice of DIRECT or EXPLORATORY; no default is inferred.") WorkGuidance.Mode mode,
@Option(names = "--approval", description = "Human instruction: REQUIRED or WAIVED for this Work only.") WorkGuidance.ApprovalPolicy policy,
@Option(names = "--choice-reason") String choiceReason, @Option(names = "--human-approved") boolean humanApproved) {
WorkGuidance initial = null;
if (mode != null || policy != null) initial = WorkGuidance.pending().choose(mode, policy, author, choiceReason, humanApproved);
else if (choiceReason != null || humanApproved) throw ProtocolException.invalid("Specify --mode or --approval for a human choice");
return emit(works.create(root(), title, description, goal, motivation, safe(constraints), safe(criteria), safe(repositories), author, initial), Format.markdown);
}
@Command(name = "list", mixinStandardHelpOptions = true)
int list(@Option(names = "--open", description = "Only nonterminal, unarchived Works (OPEN, ACTIVE, BLOCKED).") boolean open,
@@ -394,9 +421,38 @@ public final class EngineeringCli implements Runnable {
return emit(new DecisionService().revise(root(), work, id, by, reason), Format.markdown);
}
}
@Command(name = "experiment", mixinStandardHelpOptions = true, description = "Optional experiments; criteria precede observations, and execution is external.")
public class ExperimentCommands {
@Command(name = "start", mixinStandardHelpOptions = true)
int start(@Parameters(index = "0") String work, @Parameters(index = "1") String plan,
@Option(names = "--step") String step, @Option(names = "--hypothesis", required = true) String hypothesis,
@Option(names = "--criterion", required = true) String criterion, @Option(names = "--invocation", required = true) String invocation,
@Option(names = "--retry-of") String retry, @Option(names = "--reconsideration") String reconsideration,
@Option(names = "--by", required = true) String by, @Option(names = "--reason", required = true) String reason) {
return change(work, by, () -> new PlanService().startExperiment(root(), work, plan, step, hypothesis, criterion,
invocation, retry, reconsideration, by, reason), Format.markdown);
}
@Command(name = "finish", mixinStandardHelpOptions = true)
int finish(@Parameters(index = "0") String work, @Parameters(index = "1") String plan, @Parameters(index = "2") String experiment,
@Option(names = "--outcome", required = true) Experiment.Outcome outcome,
@Option(names = "--observation", required = true) String observation,
@Option(names = "--interpretation", required = true) String interpretation,
@Option(names = "--next-action", required = true) String nextAction,
@Option(names = "--evidence", required = true) List<String> evidence,
@Option(names = "--questions-decision") String concern,
@Option(names = "--by", required = true) String by, @Option(names = "--reason", required = true) String reason) {
return change(work, by, () -> new PlanService().finishExperiment(root(), work, plan, experiment, outcome,
observation, interpretation, nextAction, evidence, concern, by, reason), Format.markdown);
}
@Command(name = "list", mixinStandardHelpOptions = true)
int list(@Parameters(index = "0") String work, @Parameters(index = "1") String plan,
@Option(names = "--format", defaultValue = "markdown") Format format) {
return emit(new PlanService().get(root(), work, plan).experiments(), format);
}
}
@Command(name = "plan", mixinStandardHelpOptions = true, description = "Maintain proportional implementation plans; execution remains external.")
public class PlanCommands {
@Command(name = "create", mixinStandardHelpOptions = true, description = "Create a Plan and automatically promote referenced draft decisions without a model call.")
@Command(name = "create", mixinStandardHelpOptions = true, description = "Create a Plan respecting Work authority; draft promotion requires an explicit Work-wide waiver in guided Works.")
int create(@Parameters(index = "0") String work, @Option(names = "--title", required = true) String title,
@Option(names = "--description", defaultValue = "") String description, @Option(names = "--decision") List<String> decisions,
@Option(names = "--author", defaultValue = "human") String author) {