ultra-builder-pro-cli 0.16.0 → 0.17.1

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: Align, open, and route one bounded continuous change through research, plan, and delivery
+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: Interactively review and persist dependency-valid 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: Build complete research evidence while presenting only one load-bearing owner decision at a time
+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/docs/AGENT-CONTEXT.md

@@ -80,23 +80,26 @@ review, and deliver route back to the same thread instead of deciding for the ow
 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 the accepted cluster to current artifact digests before a
-matching workflow may advance. Status and breadcrumb return only the current question
-and one route, so recovery does not require replaying conversation history.
+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 v2 is an immutable DB-backed role handoff, not a static codebase summary.
+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
@@ -176,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

package/docs/ARCHITECTURE.md

@@ -74,7 +74,7 @@ covers twenty-one tables:
 
 | Table              | Holds                                             | Phase |
 |--------------------|---------------------------------------------------|-------|
-| `baselines`        | repository classification, greenfield/brownfield adoption, worktree snapshot, specs, evidence, verification, gap ledger, persisted known-red acceptance, and approval | 12→14 |
+| `baselines`        | repository classification, greenfield/brownfield adoption, explicit unborn/clean/dirty Git snapshot, specs, evidence, verification, gap ledger, persisted known-red acceptance, and approval | 12→17 |
 | `tasks`            | task rows — id, status, deps, files_modified, …   | 2     |
 | `events`           | append-only event stream; `id` is subscription cursor (D31) | 2 |
 | `sessions`         | execution sessions, **including lease + heartbeat fields** (D32) | 4.5 |
@@ -141,6 +141,19 @@ scripts, and monorepo markers. It detects `greenfield` or `brownfield`, records
 bounded classification evidence and selected repository scope, and creates the
 same authoritative state shape without rewriting application code.
 
+Initialization completes after local authority, classification, Git/scaffold setup,
+and read-back verification. It does not start or complete research. An explicit
+`ultra-research` invocation then records a disposition for each of the seventeen
+coverage areas and executes, verifies, or reuses only the evidence needed to converge
+the baseline.
+
+Auto initialization preserves an existing Git repository and HEAD. When Git is absent,
+it initializes `main`, adds the symlink-safe `.ultra` rule to `.gitignore`, and persists
+the resulting `unborn` snapshot. Existing repositories keep their tracked ignore file
+unchanged. It never creates a commit, remote, tag, or push. An initialized
+repository cannot use a non-Git workspace hash: research must obtain approval for a
+local checkpoint commit before `baseline.record`.
+
 Projection-only v4.4 and v4.5 projects use `ultra-tools migrate` to preserve the
 entire `.ultra` tree, import tasks and events, and create a `migrated/adopting`
 compatibility row. Schema upgrades use `ultra-tools system doctor --repair` and
@@ -212,7 +225,7 @@ impact, and no open incident. Memory and graph payloads never enter Ultra;
 
 ### Context Spine
 
-Context Manifest v2 is the immutable handoff contract between planning,
+Context Manifest v3 is the immutable handoff contract between planning,
 implementation, checking, review, convergence, and recovery. Each snapshot records:
 
 - one role (`plan`, `implement`, `check`, or `review`) and lifecycle gate;
@@ -221,19 +234,24 @@ implementation, checking, review, convergence, and recovery. Each snapshot recor
   execution contract;
 - advisory attention budgets (12 files / about 12k tokens / 40% by default);
 - a DB-derived execution contract (`slice_kind`, public seam, exact verification command);
-- one deterministic next action.
+- mechanically valid `allowed_transitions` and a `required_transition` only when a
+  hard invariant leaves one recovery route;
+- a digest of the accepted Change authority so semantic updates invalidate the
+  snapshot.
 
 Prompt input may identify the intended role/gate, add bounded reference candidates,
 and lower advisory budgets. It cannot supply or override the task seam, verification
 command, task context references, evidence digest, gate verdict, workflow summary, or
-next action. Critical change/dev/test/review/deliver workflow steps record the matching
+machine transitions. A host may attach a clearly non-authoritative recommendation.
+Critical dev/test/review/deliver workflow steps record the matching
 snapshot as an output; test, review, and delivery reports carry its digest forward.
 
 `change.breadcrumb` derives the compact current position from state.db. Session,
 edit, resume, and OpenCode lifecycle hooks invoke one bundled read-only reader
 and inject only this breadcrumb, never the intent body,
-provider content, or a conversation summary. A changed git HEAD marks the
-snapshot stale and routes back to `change.context`.
+provider content, or a conversation summary. A changed Git HEAD, task contract, or
+Change semantic authority marks the snapshot stale and permits recompilation through
+`change.context`.
 
 PRD decomposition and complex-task subdivision use the active host model. The
 MCP accepts the resulting structured tasks, validates schema, topology,
@@ -275,10 +293,13 @@ authority and the legacy task projection before creating a new brownfield adopti
 A **session** is the standard unit of execution across all four runtimes
 (D20). One session =
 
-- a fresh OS process for the runtime,
-- an isolated `git worktree`,
+- one authoritative task/runtime lease;
+- an isolated `git worktree` created by `session.spawn`,
+- an ignored `.ultra` link from that checkout to the one central authority,
 - a lease + heartbeat row in `sessions` (D32),
-- an `artifact_dir` under `.ultra/sessions/<sid>/` for logs and scratch.
+- an `artifact_dir` under `.ultra/sessions/<sid>/` for logs and scratch;
+- either the active host operating in that exact worktree or an explicitly configured
+  worker process.
 
 Spawning a new session for a task is gated by `session.admission_check`
 (D33). If another session already owns an active lease on the same task,
@@ -292,6 +313,43 @@ This admission gate is the smallest piece that prevents two agents from
 silently double-writing the same task — it is part of the v0.1 minimum
 execution layer, not deferred to Phase 5.
 
+Process status is not task status. Exit zero closes transport evidence but leaves the
+task `in_progress` until workflow gates pass; failure blocks the task and records
+circuit evidence. `session.close` preserves its worktree by default. Explicit cleanup
+is allowed only when the worktree is clean and its commit is an ancestor of the
+current checkout.
+
+The optional `ubp-orchestrator` daemon requires both `auto_dispatch: true` and an
+explicit executable plus argument array. It refuses to create a session when no real
+worker can consume it. Before launch, the runner verifies that Git ignores the
+symlink itself. When a legacy repository has only the directory-specific `.ultra/`
+rule, the runner adds `.ultra` to the repository-local `info/exclude` file without
+changing a tracked file. It then binds the checkout to the central `.ultra` and rolls
+the worktree back if the ignore rule or binding cannot be established safely. The
+executable is launched without a shell and receives
+the session, task, runtime, worktree, artifact, central DB, checkout root, and
+authority-root paths through reserved `UBP_*` environment variables that caller
+configuration cannot override.
+Pending tasks are skipped while stale, dependency-blocked, circuit-broken, leased, or
+overlapping the declared files of an active task.
+
+`execute-plan` is a resumable dispatcher, not a second workflow authority. It runs
+only the exact current DB task graph whose change-bound `plan` workflow is completed,
+healthy, and current. Empty, cyclic, duplicate-task, cross-change, stale, and merely
+exported plans fail before session creation. Owner approval is present only when a
+material planning choice required it. The dispatcher then runs only pending tasks whose
+dependencies are DB-terminal and re-reads task state. If a
+worker exits before the task converges, the current wave and plan become `paused`;
+later waves remain pending. Re-running the command skips completed waves and resumes
+the first unfinished one. `wave_completed` and `plan_completed` therefore describe
+Ultra task convergence, while `wave_paused` and `plan_paused` preserve unfinished
+gate state. Even with explicit auto-merge, integration is attempted only when the
+change task is `completed`, its completion commit matches the session HEAD, its dev
+workflow is ready, and its task review is current; process exit zero is insufficient.
+If task or plan authority changes after wave selection but before worktree creation,
+dispatch reports an authority pause without recording a worker failure or incrementing
+the circuit breaker.
+
 ## 6. Compaction recovery — checkpoint as a validated consumer
 
 `workflow_checkpoint.py` validates the current non-terminal workflow and writes