ultra-builder-pro-cli 0.15.0 → 0.17.0

package/bin/orchestrator.js

@@ -4,6 +4,7 @@
  * ubp-orchestrator — Phase 5.4 daemon CLI.
  *
  * Subcommands:
+ *   execute-plan  resume the current plan through the first unfinished dependency wave.
  *   run     foreground daemon (debug / test).
  *   start   detached background daemon, writes .ultra/orchestrator.pid.
  *   stop    reads pidfile, SIGTERM the process, deletes pidfile.
@@ -12,9 +13,8 @@
  * Opt-in gate: `start` and `run` require settings.json
  * `orchestrator.auto_dispatch: true` — default off per PLAN Phase 5.4 AC.
  *
- * The daemon never launches real runtime children in this phase — session
- * rows + git worktrees are created, external adapters (Phase 4) attach to
- * the worktree out-of-band. command/args can be passed via env for testing.
+ * Dispatch requires both explicit opt-in and an explicit executable command.
+ * A daemon may never reserve a session/worktree without a real worker process.
  */
 
 'use strict';
@@ -56,6 +56,124 @@ function parseRuntimes() {
   return runtimes;
 }
 
+function commandConfigError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function resolveDispatchCommand(settings, env = process.env) {
+  const configured = settings?.orchestrator || {};
+  const fromEnvironment = typeof env.UBP_ORCH_COMMAND === 'string'
+    && env.UBP_ORCH_COMMAND.trim() !== '';
+  const command = fromEnvironment
+    ? env.UBP_ORCH_COMMAND.trim()
+    : (typeof configured.command === 'string' ? configured.command.trim() : '');
+  if (!command) {
+    throw commandConfigError(
+      'ORCHESTRATOR_COMMAND_REQUIRED',
+      'orchestrator dispatch requires orchestrator.command or UBP_ORCH_COMMAND',
+    );
+  }
+  if (/\s/.test(command) && !fs.existsSync(command)) {
+    throw commandConfigError(
+      'ORCHESTRATOR_COMMAND_INVALID',
+      'orchestrator.command must contain only the executable; put arguments in command_args',
+    );
+  }
+
+  let commandArgs;
+  if (fromEnvironment && env.UBP_ORCH_ARGS_JSON !== undefined) {
+    try {
+      commandArgs = JSON.parse(env.UBP_ORCH_ARGS_JSON);
+    } catch (error) {
+      throw commandConfigError(
+        'ORCHESTRATOR_COMMAND_INVALID',
+        `UBP_ORCH_ARGS_JSON must be a JSON array: ${error.message}`,
+      );
+    }
+  } else {
+    commandArgs = configured.command_args === undefined ? [] : configured.command_args;
+  }
+  if (!Array.isArray(commandArgs) || commandArgs.some((arg) => typeof arg !== 'string')) {
+    throw commandConfigError(
+      'ORCHESTRATOR_COMMAND_INVALID',
+      'orchestrator command arguments must be an array of strings',
+    );
+  }
+  return {
+    command,
+    commandArgs: commandArgs.slice(),
+    source: fromEnvironment ? 'environment' : 'settings',
+  };
+}
+
+function parseExecutePlanArgs(argv = []) {
+  const options = {
+    planPath: null,
+    autoMerge: false,
+    mergeBaseBranch: 'main',
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--auto-merge') {
+      options.autoMerge = true;
+      continue;
+    }
+    if (arg === '--plan' || arg === '--base-branch') {
+      const value = argv[index + 1];
+      if (!value || value.startsWith('--')) {
+        throw commandConfigError(
+          'ORCHESTRATOR_ARGUMENT_INVALID',
+          `${arg} requires a value`,
+        );
+      }
+      if (arg === '--plan') options.planPath = value;
+      else options.mergeBaseBranch = value;
+      index += 1;
+      continue;
+    }
+    throw commandConfigError(
+      'ORCHESTRATOR_ARGUMENT_INVALID',
+      `unknown execute-plan option: ${arg}`,
+    );
+  }
+  return options;
+}
+
+async function cmdExecutePlan(argv = []) {
+  const settings = readSettings();
+  const dispatch = resolveDispatchCommand(settings);
+  const options = parseExecutePlanArgs(argv);
+  const { initStateDb, closeStateDb } = require('../mcp-server/lib/state-db.cjs');
+  const parallelOrchestrator = require('../orchestrator/parallel-orchestrator.cjs');
+  const { db } = initStateDb(path.join(REPO_ROOT, '.ultra', 'state.db'));
+  try {
+    const result = await parallelOrchestrator.runPlan({
+      db,
+      repoRoot: REPO_ROOT,
+      planPath: options.planPath ? path.resolve(REPO_ROOT, options.planPath) : undefined,
+      runtimes: parseRuntimes(),
+      command: dispatch.command,
+      commandArgs: dispatch.commandArgs,
+      autoMerge: options.autoMerge,
+      mergeBaseBranch: options.mergeBaseBranch,
+      onError: (error) => process.stderr.write(`orchestrator error: ${error.message}\n`),
+    });
+    process.stdout.write(`${JSON.stringify({
+      ok: true,
+      data: {
+        ...result,
+        auto_merge: options.autoMerge,
+        merge_base_branch: options.mergeBaseBranch,
+      },
+    })}\n`);
+    return result;
+  } finally {
+    closeStateDb(db);
+  }
+}
+
 function cmdRun(opts = {}) {
   const settings = readSettings();
   if (!opts.skipOptIn && !optInAllowed(settings)) {
@@ -68,11 +186,14 @@ function cmdRun(opts = {}) {
   const { initStateDb } = require('../mcp-server/lib/state-db.cjs');
   const { runDaemon } = require('../orchestrator/daemon.cjs');
   const runtimes = parseRuntimes();
+  const dispatch = resolveDispatchCommand(settings);
   const { db } = initStateDb(path.join(REPO_ROOT, '.ultra', 'state.db'));
   const handle = runDaemon({
     db,
     repoRoot: REPO_ROOT,
     runtimes,
+    command: dispatch.command,
+    commandArgs: dispatch.commandArgs,
     pollMs: Number(process.env.UBP_ORCH_POLL_MS || 1000),
     onError: (err) => process.stderr.write(`orchestrator error: ${err.message}\n`),
   });
@@ -85,7 +206,10 @@ function cmdRun(opts = {}) {
   };
   process.on('SIGTERM', () => shutdown('SIGTERM'));
   process.on('SIGINT', () => shutdown('SIGINT'));
-  process.stderr.write(`orchestrator running (pollMs=${Number(process.env.UBP_ORCH_POLL_MS || 1000)}, runtimes=${runtimes.join(',')})\n`);
+  process.stderr.write(
+    `orchestrator running (pollMs=${Number(process.env.UBP_ORCH_POLL_MS || 1000)}, ` +
+    `runtimes=${runtimes.join(',')}, worker=${dispatch.command}, source=${dispatch.source})\n`,
+  );
   // Keep process alive while the setInterval is unref'd.
   setInterval(() => {}, 60000);
 }
@@ -96,6 +220,7 @@ function cmdStart() {
     process.stderr.write('orchestrator.auto_dispatch is not enabled; refusing to start.\n');
     process.exit(2);
   }
+  resolveDispatchCommand(settings);
   if (fs.existsSync(PIDFILE)) {
     const existing = Number(fs.readFileSync(PIDFILE, 'utf8'));
     try { process.kill(existing, 0); }
@@ -170,8 +295,9 @@ function cmdStatus() {
 
 function usage() {
   process.stderr.write(
-    'usage: ubp-orchestrator <run|start|stop|status>\n' +
+    'usage: ubp-orchestrator <execute-plan|run|start|stop|status>\n' +
     '\n' +
+    '  execute-plan  resume the first unfinished dependency wave [--plan <path>] [--auto-merge] [--base-branch <name>]\n' +
     '  run     foreground daemon (requires opt-in)\n' +
     '  start   detached background daemon (requires opt-in)\n' +
     '  stop    terminate running daemon\n' +
@@ -179,18 +305,48 @@ function usage() {
   );
 }
 
-const argv = process.argv.slice(2);
-const subcommand = argv[0];
-switch (subcommand) {
-  case 'run':    cmdRun();        break;
-  case 'start':  cmdStart();      break;
-  case 'stop':   cmdStop();       break;
-  case 'status': cmdStatus();     break;
-  case '-h':
-  case '--help':
-  case 'help':
-    usage(); process.exit(0);
-    break;
-  default:
-    usage(); process.exit(1);
+async function main(argv = process.argv.slice(2)) {
+  const subcommand = argv[0];
+  try {
+    switch (subcommand) {
+      case 'execute-plan': await cmdExecutePlan(argv.slice(1)); break;
+      case 'run':    cmdRun();        break;
+      case 'start':  cmdStart();      break;
+      case 'stop':   cmdStop();       break;
+      case 'status': cmdStatus();     break;
+      case '-h':
+      case '--help':
+      case 'help':
+        usage(); process.exit(0);
+        break;
+      default:
+        usage(); process.exit(1);
+    }
+  } catch (error) {
+    process.stderr.write(
+      `orchestrator configuration error${error.code ? ` [${error.code}]` : ''}: ${error.message}\n`,
+    );
+    process.exit(2);
+  }
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    process.stderr.write(`orchestrator fatal error: ${error.message}\n`);
+    process.exit(2);
+  });
 }
+
+module.exports = {
+  readSettings,
+  optInAllowed,
+  parseRuntimes,
+  parseExecutePlanArgs,
+  resolveDispatchCommand,
+  cmdExecutePlan,
+  cmdRun,
+  cmdStart,
+  cmdStop,
+  cmdStatus,
+  main,
+};

package/commands/ultra-change.md

@@ -1,5 +1,5 @@
 ---
-description: Open or resume a bounded continuous change with linked authoritative tasks and context
+description: Capture or revise one bounded Change Contract without starting downstream workflows
 argument-hint: "[change-id-or-title] [quick|standard|major|incident]"
 workflow-ref: "@skills/ultra-change/SKILL.md"
 ---

package/commands/ultra-deliver.md

@@ -1,10 +1,10 @@
 ---
-description: Converge current evidence and specification learning into an archived or released baseline
-argument-hint: "[version-type]"
+description: Converge current evidence and archive local Ultra authority without external release effects
+argument-hint: "[change-id]"
 workflow-ref: "@skills/ultra-deliver/SKILL.md"
 ---
 
 # Converge and deliver
 
-Read and follow `@skills/ultra-deliver/SKILL.md`, using `$ARGUMENTS` only for an explicitly requested version policy.
+Read and follow `@skills/ultra-deliver/SKILL.md`, using `$ARGUMENTS` only to select the change.
 Treat the referenced skill as the only workflow definition.

package/commands/ultra-init.md

@@ -1,5 +1,5 @@
 ---
-description: Initialize a new project or adopt an existing repository into authoritative Ultra baseline state
+description: Create or recover Ultra project authority without implicitly starting research
 argument-hint: "[name] [type] [stack] [auto|greenfield|brownfield] [--scope <path>]"
 workflow-ref: "@skills/ultra-init/SKILL.md"
 ---

package/commands/ultra-plan.md

@@ -1,5 +1,5 @@
 ---
-description: Convert validated requirements into dependency-valid Ultra tasks with bounded context and exact verification
+description: Persist dependency-valid vertical task contracts from an accepted Change Contract
 argument-hint: "[scope]"
 workflow-ref: "@skills/ultra-plan/SKILL.md"
 ---

package/commands/ultra-research.md

@@ -1,10 +1,10 @@
 ---
-description: Research unresolved product or architecture decisions and update the authoritative baseline specifications
+description: Build evidence with model-selected semantic coverage and adaptive user alignment
 argument-hint: "[scope-or-question]"
 workflow-ref: "@skills/ultra-research/SKILL.md"
 ---
 
-# Research a baseline
+# Research one bounded question or baseline
 
 Read and follow `@skills/ultra-research/SKILL.md`, using `$ARGUMENTS` to bound the research scope.
 Treat the referenced skill as the only workflow definition.

package/commands/ultra-review.md

@@ -0,0 +1,10 @@
+---
+description: Review one plan, task diff, or aggregate change on independent specification and engineering axes
+argument-hint: "[plan|task|change] [id]"
+workflow-ref: "@skills/ultra-review/SKILL.md"
+---
+
+# Review one bounded Ultra scope
+
+Read and follow `@skills/ultra-review/SKILL.md`, using `$ARGUMENTS` to select the review mode and authority.
+Treat the referenced skill as the only workflow definition.

package/commands/ultra-status.md

@@ -1,5 +1,5 @@
 ---
-description: Report authoritative Ultra health, readiness, evidence freshness, and one next action
+description: Report authoritative Ultra health, evidence freshness, and valid capability transitions
 argument-hint: "[task-or-change-id]"
 workflow-ref: "@skills/ultra-status/SKILL.md"
 ---

package/commands/ultra-test.md

@@ -1,5 +1,5 @@
 ---
-description: Run the independent pre-delivery verification gate and record current acceptance evidence
+description: Run independent, risk-selected verification and record current acceptance evidence
 argument-hint: "[scope]"
 workflow-ref: "@skills/ultra-test/SKILL.md"
 ---

package/commands/ultra-think.md

@@ -1,10 +1,10 @@
 ---
-description: Analyze a consequential question with evidence, uncertainty, and proportionate stress testing
+description: Resolve a consequential question through evidence or one-decision-at-a-time alignment
 argument-hint: "[question]"
 workflow-ref: "@skills/ultra-think/SKILL.md"
 ---
 
-# Analyze a consequential question
+# Align on a consequential question
 
 Read and follow `@skills/ultra-think/SKILL.md`, treating `$ARGUMENTS` as the question to resolve.
 Treat the referenced skill as the only workflow definition.

package/docs/AGENT-CONTEXT.md

@@ -37,15 +37,15 @@ native command or skill -> MCP workflow-state operation -> .ultra/state.db
 | MCP | `mcp-server/server.cjs` | Authoritative typed operations over `.ultra/state.db` |
 | CLI | `ultra-tools`, `ubp-orchestrator` | Selected initialization, backup-first recovery, automation, and diagnostics; not a change-state mirror |
 
-`.ultra/state.db` is the only durable Ultra authority for baselines, changes, tasks,
+`.ultra/state.db` is the only durable Ultra authority for baselines, changes, decisions, tasks,
 workflow runs/steps, sessions, events, incidents, projection jobs/cursors, telemetry, review evidence,
 and circuit-breaker state. `tasks.json`, context Markdown, execution plans, and
 reports are projections or workflow artifacts.
 
 ## 3. Live MCP and declared contracts
 
-`spec/mcp-tools.yaml` declares and the bundled server registers 41 tools across
-seven families:
+`spec/mcp-tools.yaml` declares and the bundled server registers 50 tools across
+eight families:
 
 | Family | Live tools |
 |---|---|
@@ -53,13 +53,15 @@ seven families:
 | `task.*` | create, update, list, get, switch_tag, delete, init_project, expand, parse_prd, dependency_topo, append_event, subscribe_events |
 | `session.*` | spawn, close, get, list, admission_check, heartbeat, subscribe_events |
 | `change.*` | create, update, get, list, context, breadcrumb, learning_propose, learning_resolve, converge, archive |
+| `decision.*` | thread_start, get, list, open, resolve, delegate, defer, supersede, checkpoint |
 | `workflow.*` | start, get, list, step, complete |
 | `system.*` | doctor |
 | `plan.*` | export, get |
 
-Review, repository impact discovery, skill loading, and user interaction remain
-host-native capabilities rather than fake MCP contracts. The generated Codex
-capability map documents those replacements.
+Review, repository impact discovery, skill loading, and decision presentation remain
+host-native capabilities rather than fake MCP contracts. MCP stores only normalized
+decision authority and checkpoints; it never generates questions or retains prompts
+and transcripts. The generated Codex capability map documents host replacements.
 
 The complete write, transition, invalidation, and recovery contract lives in
 [`WORKFLOW-LIFECYCLE.md`](./WORKFLOW-LIFECYCLE.md).
@@ -67,19 +69,37 @@ The complete write, transition, invalidation, and recovery contract lives in
 Any new MCP contract starts in `spec/mcp-tools.yaml` with valid and invalid
 fixtures. Do not add an ad-hoc server handler first.
 
-## 4. Context Spine contract
+## 4. Human-agent alignment contract
 
-Context Manifest v2 is an immutable DB-backed role handoff, not a static codebase summary.
+`skills/ultra-think/references/decision-dialogue.md` is the single reusable prompt
+contract for load-bearing owner choices. Research, change, and plan read it at their
+decision boundaries. They inspect evidence first, expose only the earliest unresolved
+choice, include a recommendation and durable effects, and stop the turn. Dev, test,
+review, and deliver route back to the same thread instead of deciding for the owner.
+
+One partial unique index permits only one open item per thread. `decision.resolve`,
+`decision.delegate`, and `decision.defer` preserve the source of authority;
+`decision.supersede` preserves history when evidence or intent changes. Prepare and
+confirm checkpointing bind a material accepted cluster to current artifact digests
+when interruption recovery needs that boundary. Status and breadcrumb return only the
+current question plus allowed and mechanically required transitions, so recovery does
+not require replaying conversation history.
+
+## 5. Context Spine contract
+
+Context Manifest v3 is an immutable DB-backed role handoff, not a static codebase summary.
 `change.context` compiles required references, digests, readiness, context budget,
-public seam, exact verification command, and one next action for `plan`,
-`implement`, `check`, or `review`. The default 12-file, about 12k-token, and 40%
+public seam, exact verification command, Change/task authority digests, and valid
+transitions for `plan`, `implement`, `check`, or `review`. The default 12-file,
+about 12k-token, and 40%
 fresh-context values are attention guidance. Overflow produces warnings; it does
 not block work or require raising a threshold. Prefer direct reads, bounded
 excerpts, or a smaller slice when they preserve correctness, and retain all
 necessary context when they do not.
 
 `change.breadcrumb` is the only compact router. Hooks may inject its change/task,
-role, gate, readiness, blockers, and one next action. They must not inject intent
+role, gate, readiness, blockers, `allowed_transitions`, and `required_transition`.
+They must not inject intent
 bodies, transcripts, external memory, or graph payloads. Missing references,
 digest drift, HEAD drift, or a missing execution seam blocks readiness. Context
 size and baseline drift are advisory for a change that is already active. New ordinary
@@ -92,7 +112,7 @@ through approve/reject/apply transitions in `change.learning_resolve`. Unresolve
 learning blocks convergence. Review contributes two independent axes,
 `spec_fidelity` and `engineering_standards`; neither can replace the other.
 
-## 5. Native host presentation
+## 6. Native host presentation
 
 | Host | Plugin form | Workflow entry | Hook form | Collaboration companions |
 |---|---|---|---|---|
@@ -105,7 +125,7 @@ The current host remains primary. Collaboration skills call another runtime
 only when explicitly requested, use it as a read-only advisor, and return the
 evidence to the primary host for final verification.
 
-## 6. Hook boundary
+## 7. Hook boundary
 
 The canonical Python hook bundle contains seven executable workflow hooks plus
 the shared read-only `context_spine.py` breadcrumb helper:
@@ -133,7 +153,7 @@ reject an edit, stop, or tool call.
 Generic command blocking, post-edit governance, and unrelated user hooks are not
 copied into Ultra Builder Pro.
 
-## 7. Memory boundary
+## 8. Memory boundary
 
 Ultra Builder Pro has no memory MCP family, recall skill, prompt capture,
 transcript capture, observation journal, or session-summary hook. Persistent
@@ -151,7 +171,7 @@ ultra-tools legacy-memory prune --confirm DELETE_ULTRA_LEGACY_MEMORY
 
 Archive before prune; the confirmation token is intentionally required.
 
-## 8. Project state layout
+## 9. Project state layout
 
 ```text
 .ultra/
@@ -159,7 +179,7 @@ Archive before prune; the confirmation token is intentionally required.
 ├── runtime/
 │   └── checkpoint.json      # advisory breadcrumb recovery projection
 ├── changes/
-│   ├── active/<id>/         # intent, delta, plan, context v2, learning, verification
+│   ├── active/<id>/         # intent, delta, plan, context v3, learning, verification
 │   └── archive/             # converged packets after baseline reconciliation
 ├── tasks/                   # projections and task contexts
 ├── specs/                   # research/product/architecture artifacts
@@ -171,7 +191,7 @@ Archive before prune; the confirmation token is intentionally required.
     └── delivery/<workflow-id>.json
 ```
 
-## 9. User handbook integration
+## 10. User handbook integration
 
 General engineering doctrine remains user-owned in `CLAUDE.md` or `AGENTS.md`.
 Ultra Builder Pro contributes one managed section only. Preview or apply it with:
@@ -186,7 +206,7 @@ timestamped backup, replaces only the marked block, and can migrate the old
 Codex `## Ultra Builder Pro Runtime Contract` section without touching the next
 user section. Plugin adapters themselves do not silently overwrite handbooks.
 
-## 10. Verification
+## 11. Verification
 
 Run `npm run test:all`, `python3 -m pytest hooks/tests -q`, and `npm audit`.
 Adapter tests assert the allowlisted assets, native manifests, hook boundary,