ultra-builder-pro-cli 0.20.0 → 0.22.0

package/bin/orchestrator.js

@@ -6,7 +6,7 @@
  * 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.
+ *   start   detached background daemon, writes .ultra/.runtime/orchestrator.pid.
  *   stop    reads pidfile, SIGTERM the process, deletes pidfile.
  *   status  prints pidfile + running session summary.
  *
@@ -23,10 +23,12 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { spawn } = require('node:child_process');
 const { isSupportedRuntime } = require('../adapters/_shared/runtime-assets.cjs');
+const runtimePaths = require('../mcp-server/lib/runtime-paths.cjs');
 
 const REPO_ROOT = process.env.UBP_REPO_ROOT || process.cwd();
-const PIDFILE = path.join(REPO_ROOT, '.ultra', 'orchestrator.pid');
-const LOGFILE = path.join(REPO_ROOT, '.ultra', 'orchestrator.log');
+const RUNTIME_PATHS = runtimePaths.pathsFor(REPO_ROOT);
+const PIDFILE = RUNTIME_PATHS.orchestratorPidPath;
+const LOGFILE = RUNTIME_PATHS.orchestratorLogPath;
 const SETTINGS_FILES = [
   path.join(REPO_ROOT, 'settings.json'),
   path.join(REPO_ROOT, '.claude', 'settings.json'),
@@ -111,6 +113,7 @@ function resolveDispatchCommand(settings, env = process.env) {
 function parseExecutePlanArgs(argv = []) {
   const options = {
     planPath: null,
+    changeId: null,
     autoMerge: false,
     mergeBaseBranch: 'main',
   };
@@ -120,7 +123,7 @@ function parseExecutePlanArgs(argv = []) {
       options.autoMerge = true;
       continue;
     }
-    if (arg === '--plan' || arg === '--base-branch') {
+    if (arg === '--plan' || arg === '--change' || arg === '--base-branch') {
       const value = argv[index + 1];
       if (!value || value.startsWith('--')) {
         throw commandConfigError(
@@ -129,6 +132,7 @@ function parseExecutePlanArgs(argv = []) {
         );
       }
       if (arg === '--plan') options.planPath = value;
+      else if (arg === '--change') options.changeId = value;
       else options.mergeBaseBranch = value;
       index += 1;
       continue;
@@ -138,21 +142,43 @@ function parseExecutePlanArgs(argv = []) {
       `unknown execute-plan option: ${arg}`,
     );
   }
+  if (options.planPath && options.changeId) {
+    throw commandConfigError(
+      'ORCHESTRATOR_ARGUMENT_INVALID',
+      '--plan is explicit legacy compatibility and cannot be combined with --change',
+    );
+  }
   return options;
 }
 
+function validateOrchestratorRuntime(rootDir = REPO_ROOT, {
+  forMutation = false,
+} = {}) {
+  return runtimePaths.validateProjectLayout(rootDir, {
+    env: {},
+    forMutation,
+    validateRuntimeTree: true,
+  });
+}
+
+function openNoFollow(file, flags) {
+  const noFollow = fs.constants.O_NOFOLLOW || 0;
+  return fs.openSync(file, flags | noFollow, 0o600);
+}
+
 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'));
+  const { db } = initStateDb(runtimePaths.ensureRuntimeState(REPO_ROOT).stateDbPath);
   try {
     const result = await parallelOrchestrator.runPlan({
       db,
       repoRoot: REPO_ROOT,
       planPath: options.planPath ? path.resolve(REPO_ROOT, options.planPath) : undefined,
+      changeId: options.changeId,
       runtimes: parseRuntimes(),
       command: dispatch.command,
       commandArgs: dispatch.commandArgs,
@@ -187,7 +213,7 @@ function cmdRun(opts = {}) {
   const { runDaemon } = require('../orchestrator/daemon.cjs');
   const runtimes = parseRuntimes();
   const dispatch = resolveDispatchCommand(settings);
-  const { db } = initStateDb(path.join(REPO_ROOT, '.ultra', 'state.db'));
+  const { db } = initStateDb(runtimePaths.ensureRuntimeState(REPO_ROOT).stateDbPath);
   const handle = runDaemon({
     db,
     repoRoot: REPO_ROOT,
@@ -221,39 +247,51 @@ function cmdStart() {
     process.exit(2);
   }
   resolveDispatchCommand(settings);
-  if (fs.existsSync(PIDFILE)) {
-    const existing = Number(fs.readFileSync(PIDFILE, 'utf8'));
+  const layout = validateOrchestratorRuntime(REPO_ROOT, { forMutation: true });
+  const pidfile = layout.orchestratorPidPath;
+  const logfile = layout.orchestratorLogPath;
+  if (fs.existsSync(pidfile)) {
+    const existing = Number(fs.readFileSync(pidfile, 'utf8'));
     try { process.kill(existing, 0); }
-    catch (_) { fs.unlinkSync(PIDFILE); }
-    if (fs.existsSync(PIDFILE)) {
+    catch (_) { fs.unlinkSync(pidfile); }
+    if (fs.existsSync(pidfile)) {
       process.stderr.write(`orchestrator already running (pid=${existing}).\n`);
       process.exit(1);
     }
   }
-  fs.mkdirSync(path.dirname(PIDFILE), { recursive: true });
-  const out = fs.openSync(LOGFILE, 'a');
-  const err = fs.openSync(LOGFILE, 'a');
+  fs.mkdirSync(layout.orchestratorDir, { recursive: true });
+  const appendFlags = fs.constants.O_APPEND | fs.constants.O_CREAT | fs.constants.O_WRONLY;
+  const out = openNoFollow(logfile, appendFlags);
+  const err = openNoFollow(logfile, appendFlags);
   const child = spawn(process.execPath, [__filename, 'run'], {
     detached: true,
     stdio: ['ignore', out, err],
     env: { ...process.env, UBP_REPO_ROOT: REPO_ROOT },
   });
   child.unref();
-  fs.writeFileSync(PIDFILE, String(child.pid));
-  process.stdout.write(`orchestrator started (pid=${child.pid}, log=${LOGFILE})\n`);
+  const pidFd = openNoFollow(
+    pidfile,
+    fs.constants.O_CREAT | fs.constants.O_TRUNC | fs.constants.O_WRONLY,
+  );
+  try { fs.writeFileSync(pidFd, String(child.pid)); }
+  finally { fs.closeSync(pidFd); }
+  process.stdout.write(`orchestrator started (pid=${child.pid}, log=${logfile})\n`);
 }
 
 function cmdStop() {
-  if (!fs.existsSync(PIDFILE)) {
+  const { orchestratorPidPath: pidfile } = validateOrchestratorRuntime(REPO_ROOT, {
+    forMutation: true,
+  });
+  if (!fs.existsSync(pidfile)) {
     process.stderr.write('no pidfile found; orchestrator not running.\n');
     process.exit(1);
   }
-  const pid = Number(fs.readFileSync(PIDFILE, 'utf8'));
+  const pid = Number(fs.readFileSync(pidfile, 'utf8'));
   try { process.kill(pid, 'SIGTERM'); }
   catch (err) {
     if (err.code === 'ESRCH') {
       process.stderr.write(`pid ${pid} already dead; cleaning pidfile.\n`);
-      fs.unlinkSync(PIDFILE);
+      fs.unlinkSync(pidfile);
       return;
     }
     throw err;
@@ -262,22 +300,23 @@ function cmdStop() {
   setTimeout(() => {
     try { process.kill(pid, 0); }
     catch (_) { /* dead; good */ }
-    if (fs.existsSync(PIDFILE)) fs.unlinkSync(PIDFILE);
+    if (fs.existsSync(pidfile)) fs.unlinkSync(pidfile);
     process.stdout.write(`orchestrator stopped (pid=${pid})\n`);
   }, 200);
 }
 
 function cmdStatus() {
-  const out = { pidfile: PIDFILE, running: false };
-  if (fs.existsSync(PIDFILE)) {
-    const pid = Number(fs.readFileSync(PIDFILE, 'utf8'));
+  const { orchestratorPidPath: pidfile } = validateOrchestratorRuntime(REPO_ROOT);
+  const out = { pidfile, running: false };
+  if (fs.existsSync(pidfile)) {
+    const pid = Number(fs.readFileSync(pidfile, 'utf8'));
     try { process.kill(pid, 0); out.pid = pid; out.running = true; }
     catch (_) { out.pid = pid; out.running = false; out.note = 'pidfile stale'; }
   }
   // Session summary.
   try {
     const Database = require('better-sqlite3');
-    const dbPath = path.join(REPO_ROOT, '.ultra', 'state.db');
+    const dbPath = runtimePaths.locateStateDb(REPO_ROOT);
     if (fs.existsSync(dbPath)) {
       const db = new Database(dbPath, { readonly: true });
       const counts = db.prepare(
@@ -297,7 +336,7 @@ function usage() {
   process.stderr.write(
     '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' +
+    '  execute-plan  resume the first unfinished dependency wave [--change <id>] [--plan <legacy-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' +
@@ -343,6 +382,7 @@ module.exports = {
   parseRuntimes,
   parseExecutePlanArgs,
   resolveDispatchCommand,
+  validateOrchestratorRuntime,
   cmdExecutePlan,
   cmdRun,
   cmdStart,

package/docs/AGENT-CONTEXT.md

@@ -7,9 +7,9 @@ and Kimi Code plugins.
 
 Ultra Builder Pro owns only:
 
-- twelve public workflows: `learn`, `ultra-init`, `ultra-research`, `ultra-plan`,
-  `ultra-dev`, `ultra-test`, `ultra-review`, `ultra-deliver`, `ultra-status`, and
-  `ultra-think`, plus the daily `ultra-change` and diagnostic `ultra-doctor`;
+- eleven public capabilities: `ultra-init`, `ultra-research`, `ultra-plan`,
+  `ultra-dev`, `ultra-test`, `ultra-review`, `ultra-deliver`, `ultra-status`,
+  `ultra-think`, `ultra-change`, and `ultra-doctor`;
 - four internal agent-only rule skills: `code-review-expert`, `security-rules`,
   `integration-rules`, and `testing-rules`;
 - the host-specific collaboration companions, `ultra-verify`, and host-native
@@ -25,36 +25,46 @@ not put it in a plugin until that allowlist classifies it.
 ## 2. Three-layer architecture
 
 ```text
-native command or skill -> MCP workflow-state operation -> .ultra/state.db
+native command or skill -> MCP workflow-state operation -> .ultra/.runtime/state.db
+                                      | \
+                                      |  -> .ultra/tasks/tasks.json (Git checkpoint)
+                                      |  -> .ultra/.runtime/projections/ (local views)
                                       ^
-                                      |
               selected CLI init / doctor / diagnostics / orchestration
 ```
 
 | Layer | Artifact | Contract |
 |---|---|---|
 | Skill/command | `skills/*/SKILL.md`, `commands/*.md` | Model-facing workflow and host-native entry point |
-| MCP | `mcp-server/server.cjs` | Authoritative typed operations over `.ultra/state.db` |
+| MCP | `mcp-server/server.cjs` | Authoritative typed operations over `.ultra/.runtime/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, 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.
+`.ultra/` is project-local cross-session workflow memory for normalized intent,
+progress, tasks, bounded context, specifications, evidence, provenance, and recovery.
+`.ultra/.runtime/state.db` is checkout-local lifecycle, index, transition, freshness,
+and coordination authority for baselines, changes, decisions, tasks, workflow
+runs/steps, sessions, events, incidents, projection jobs/cursors, telemetry, review
+evidence, and circuit-breaker state. Registered digest-bound specifications and
+reports carry semantic or evidence bodies. `.ultra/tasks/tasks.json` is the
+MCP-published portable baseline/Change/task checkpoint; it is not live lease or session
+authority. Generated task views, runtime checkpoints, and collaboration scratch are
+not independent authority. See
+[`ARTIFACT-AUTHORITY.md`](./ARTIFACT-AUTHORITY.md).
 
 ## 3. Live MCP and declared contracts
 
-`spec/mcp-tools.yaml` declares and the bundled server registers 51 tools across
-eight families:
+`spec/mcp-tools.yaml` declares and the bundled server registers 60 tools across
+nine families:
 
 | Family | Live tools |
 |---|---|
 | `baseline.*` | start, record, get, converge |
-| `task.*` | create, update, list, get, switch_tag, delete, init_project, expand, parse_prd, dependency_topo, append_event, subscribe_events |
+| `task.*` | create, update, list, get, switch_tag, delete, init_project, expand, parse_prd, dependency_topo, append_event, subscribe_events, ledger_get, ledger_publish, ledger_import |
 | `session.*` | spawn, close, get, list, admission_check, heartbeat, subscribe_events |
-| `change.*` | create, update, get, list, context, breadcrumb, learning_propose, learning_resolve, converge, archive |
+| `change.*` | create, update, delta, documentation_reconcile, get, list, context, breadcrumb, learning_propose, learning_resolve, converge, archive |
 | `decision.*` | thread_start, get, list, open, resolve, delegate, defer, supersede, complete, checkpoint |
-| `workflow.*` | start, get, list, step, complete |
+| `workflow.*` | start, get, list, step, revise, supersede, complete |
+| `artifact.*` | record, get |
 | `system.*` | doctor |
 | `plan.*` | export, get |
 
@@ -81,35 +91,55 @@ 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.
-`decision.complete` closes settled normalized state without manufacturing an approval
-receipt. Prepare and confirm checkpointing remain optional and bind only 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.
+After normalization, the host applies accepted intent through the owning MCP operation
+or digest-bound artifact, reads it back, and records typed `applied_refs` when another
+authority changed. Row-backed references require the exact field and canonical value;
+specification and artifact references require the exact file digest. Active proposals
+are never recalled as accepted intent. `decision.complete` then closes settled state without manufacturing
+an approval receipt. Prepare and confirm checkpointing remain optional and bind only a
+material accepted cluster to current artifact digests when interruption recovery needs
+that boundary. Status and breadcrumb return the current unresolved question, accepted
+intent relevant to the active authority, and allowed or 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, Change/task authority digests, and valid
-transitions for `plan`, `implement`, `check`, or `review`. The default 12-file,
-about 12k-token, and 40%
+transitions for `plan`, `implement`, `check`, or `review`. Compilation never updates
+Change or provider authority; provider metadata changes through `change.update`.
+Snapshots are selected exactly by `change_id`, nullable `task_id`, `role`, and `gate`,
+so a review packet cannot satisfy implementation or planning evidence.
+
+Implementation packets inline only the selected task, direct dependency/integration
+neighborhood, and the restored task-context contract. Referenced file bodies remain
+lazy. The token estimate includes inline Change/task authority plus referenced-file
+estimates. Context refs preserve `expected_digest`, `anchor`, `scope`, and one of
+`digest`, `existence`, or `advisory` freshness. Current consumers revalidate these
+policies instead of trusting an old manifest.
+
+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, `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
+role, gate, readiness, blockers, bounded normalized accepted intent,
+`allowed_transitions`, and `required_transition`. They must not inject raw prompts,
+interaction transcripts, external-memory payloads, or graph payloads. Missing references,
+required 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
 work requires a healthy baseline. Only an explicitly approved incident break-glass may
 start without it; incident archive records a blocking reconciliation gap. Revision and
 tracked-spec integrity are reconciled and rechecked atomically for ordinary archive.
 
+The plan workflow records a `plan/planning` manifest before design and exports only
+`<artifact_root>/plan.json` plus deterministic `plan.md`. Both bind the planning
+snapshot digest. The global `.ultra/execution-plan.json` is legacy read-only
+compatibility and must not receive new plan writes.
+
 Stable discoveries use `change.learning_propose`; they reach the baseline only
 through approve/reject/apply transitions in `change.learning_resolve`. Unresolved
 learning blocks convergence. Review contributes two independent axes,
@@ -119,10 +149,14 @@ learning blocks convergence. Review contributes two independent axes,
 
 | Host | Plugin form | Workflow entry | Hook form | Collaboration companions |
 |---|---|---|---|---|
-| Claude Code | `.claude-plugin/plugin.json`, native commands/skills/agents, `.mcp.json` | `/ultra-*`, `/learn` | native `hooks/hooks.json` | `codex-collab`, `ultra-verify` |
-| Codex | personal plugin with `.codex-plugin/plugin.json`, namespaced skills, TOML agents, `.mcp.json` | `$ultra-builder-pro:ultra-*`, `$ultra-builder-pro:learn` | native `hooks/hooks.json` through the Codex wire adapter | `cc-collab`, `ultra-verify` |
-| OpenCode | config bundle plus native JavaScript plugin | `/ultra-*`, `/learn` | `event`, system transform, compaction, and tool lifecycle handlers | `cc-collab`, `codex-collab`, `ultra-verify` |
-| Kimi Code 0.26+ | managed `kimi.plugin.json` plugin with commands, skills, hooks, and MCP | `/ultra-builder-pro:ultra-*`, `/ultra-builder-pro:learn` | native hooks through the Kimi wire adapter | `cc-collab`, `codex-collab`, `ultra-verify` |
+| Claude Code | `.claude-plugin/plugin.json`, native commands/skills/agents, `.mcp.json` | `/ultra-builder-pro:ultra-*` | native `hooks/hooks.json` | `codex-collab`, `ultra-verify` |
+| Codex | personal plugin with `.codex-plugin/plugin.json`, namespaced skills, TOML agents, `.mcp.json` | `$ultra-builder-pro:ultra-*` | native `hooks/hooks.json` through the Codex wire adapter | `cc-collab`, `ultra-verify` |
+| OpenCode | config bundle plus native JavaScript plugin | `/ultra-*` | `event`, system transform, compaction, and tool lifecycle handlers | `cc-collab`, `codex-collab`, `ultra-verify` |
+| Kimi Code 0.26+ | managed `kimi.plugin.json` plugin with commands, skills, hooks, and MCP | `/ultra-builder-pro:ultra-*` | native hooks through the Kimi wire adapter | `cc-collab`, `codex-collab`, `ultra-verify` |
+
+`spec/interaction-contract.json` carries the same exact public-capability graph for
+every host. Adapters translate the question and invocation surfaces; they never own
+semantic selection or durable state.
 
 The current host remains primary. Collaboration skills call another runtime
 only when explicitly requested, use it as a read-only advisor, and return the
@@ -146,22 +180,24 @@ OpenCode plugin invoke the same bundled JavaScript `change.breadcrumb` reader
 through the thin `context_spine.py` bridge. No hook reimplements the state query.
 `health_check.py` and
 `workflow_context.py` may inspect any initialized project;
-`active_task_context.py` always protects the task projection but limits ordinary
+`active_task_context.py` protects both the MCP-owned Git checkpoint and local task
+projection but limits ordinary
 edit guidance to an active workflow. Compact/stop/subagent hooks remain
 active-workflow scoped. OpenCode natively injects baseline/change context and
-protects the projection; full health inspection is available through
+protects both managed task paths; full health inspection is available through
 `system.doctor` rather than a session-start health hook.
 Advisory baseline or context-budget warnings are presentation only and never
 reject an edit, stop, or tool call.
 Generic command blocking, post-edit governance, and unrelated user hooks are not
 copied into Ultra Builder Pro.
 
-## 8. Memory boundary
+## 8. Workflow-memory boundary
 
-Ultra Builder Pro has no memory MCP family, recall skill, prompt capture,
-transcript capture, observation journal, or session-summary hook. Persistent
-cross-session memory belongs to a separately installed provider such as
-cloud-mem/claude-mem. Code graph content is equally external. A change context
+Ultra Builder Pro has no general memory MCP family, general recall skill, prompt
+capture, transcript capture, observation journal, or session-summary hook. It does
+retain its own project-local cross-session workflow memory under `.ultra/`.
+General conversational or episodic memory belongs to a separately installed provider
+such as cloud-mem/claude-mem. Code-graph content is equally external. A change context
 may contain only provider metadata references, never provider payload content.
 
 Old Ultra data is never deleted during install. The explicit migration path is:
@@ -173,25 +209,29 @@ ultra-tools legacy-memory prune --confirm DELETE_ULTRA_LEGACY_MEMORY
 ```
 
 Archive before prune; the confirmation token is intentionally required.
+This CLI is an operator-invoked migration cleanup surface only. Hooks, MCP, and
+sessions never call it, and it cannot collect, recall, or reflect memory.
 
 ## 9. Project state layout
 
 ```text
 .ultra/
-├── state.db                 # authoritative SQLite store
-├── runtime/
-│   └── checkpoint.json      # advisory breadcrumb recovery projection
+├── .runtime/
+│   ├── state.db             # authoritative SQLite lifecycle/index store
+│   ├── checkpoint.json      # advisory breadcrumb recovery projection
+│   └── projections/         # generated checkout-local task views
 ├── changes/
-│   ├── active/<id>/         # intent, delta, plan, context v3, learning, verification
+│   ├── active/<id>/         # all Change semantics and evidence
+│   │   ├── intent.md, findings.md, progress.md
+│   │   ├── research/, delta/, documentation/, plan.json, plan.md
+│   │   └── contexts/, test/, review/, delivery/
 │   └── archive/             # converged packets after baseline reconciliation
-├── tasks/                   # projections and task contexts
+├── tasks/
+│   └── tasks.json           # MCP-published Git team checkpoint
+├── templates/
+│   └── task-context.md      # authored task-context template
 ├── specs/                   # research/product/architecture artifacts
-├── sessions/                # bounded runtime artifacts
-├── reviews/                 # immutable review evidence by session id
-└── reports/
-    ├── templates/           # blank report schemas; never evidence
-    ├── tests/<workflow-id>.json
-    └── delivery/<workflow-id>.json
+└── reports/templates/      # blank report schemas; never evidence
 ```
 
 ## 10. Plugin and user-instruction isolation