ultra-builder-pro-cli 0.19.1 → 0.21.1

package/adapters/_shared/runtime-assets.cjs

@@ -8,7 +8,6 @@
  */
 
 const CORE_PUBLIC_SKILLS = Object.freeze([
-  'learn',
   'ultra-init',
   'ultra-research',
   'ultra-plan',
@@ -22,6 +21,34 @@ const CORE_PUBLIC_SKILLS = Object.freeze([
   'ultra-doctor',
 ]);
 
+const PUBLIC_CAPABILITY_MODES = Object.freeze({
+  'ultra-init': 'setup',
+  'ultra-research': 'workflow',
+  'ultra-plan': 'workflow',
+  'ultra-dev': 'workflow',
+  'ultra-test': 'workflow',
+  'ultra-review': 'workflow',
+  'ultra-deliver': 'workflow',
+  'ultra-status': 'read_only',
+  'ultra-think': 'reasoning',
+  'ultra-change': 'workflow',
+  'ultra-doctor': 'diagnostic',
+});
+
+const PUBLIC_CAPABILITY_GRAPH = Object.freeze(Object.fromEntries(
+  CORE_PUBLIC_SKILLS.map((name) => [
+    name,
+    Object.freeze({
+      mode: PUBLIC_CAPABILITY_MODES[name],
+      activation: 'explicit_only',
+      next_capability_source: 'mcp_allowed_transitions',
+      recommendation_owner: 'host_model',
+      selection_owner: 'user',
+      automatic_invocation: false,
+    }),
+  ]),
+));
+
 const INTERNAL_AGENT_SKILLS = Object.freeze([
   'code-review-expert',
   'security-rules',
@@ -56,12 +83,22 @@ const WORKFLOW_HOOK_FILES = Object.freeze([
   'context_spine.py',
   'health_check.py',
   'pre_stop_check.py',
+  'runtime_paths.py',
   'subagent_tracker.py',
   'workflow_checkpoint.py',
   'workflow_context.py',
   'workflow_resume.py',
 ]);
 
+const RUNTIME_WORKER_FILES = Object.freeze([
+  'session-close-journal-worker.cjs',
+  'doctor-backup-worker.cjs',
+]);
+
+const RUNTIME_SUPPORT_FILES = Object.freeze([
+  'archive-mutation-worker.py',
+]);
+
 function skillsForRuntime(runtime) {
   const collab = COLLAB_SKILLS_BY_RUNTIME[runtime];
   if (!collab) throw new Error(`unsupported Ultra runtime: ${runtime}`);
@@ -84,11 +121,14 @@ function skillPolicy(name) {
 
 module.exports = {
   CORE_PUBLIC_SKILLS,
+  PUBLIC_CAPABILITY_GRAPH,
   INTERNAL_AGENT_SKILLS,
   SUPPORTED_RUNTIMES,
   COLLAB_SKILLS_BY_RUNTIME,
   MCP_DEPENDENT_SKILLS,
+  RUNTIME_SUPPORT_FILES,
   WORKFLOW_HOOK_FILES,
+  RUNTIME_WORKER_FILES,
   isSupportedRuntime,
   skillPolicy,
   skillsForRuntime,

package/adapters/claude.js

@@ -16,6 +16,7 @@ const {
 } = require('./_shared/file-ops.cjs');
 const { buildMcpRuntime } = require('./_shared/codex-assets.cjs');
 const { parse: parseFrontmatter, serialize: serializeFrontmatter } = require('./_shared/frontmatter.cjs');
+const { adaptInteractionGuidance } = require('./_shared/interaction-contract.cjs');
 const provenance = require('./_shared/provenance.cjs');
 const {
   CORE_PUBLIC_SKILLS,
@@ -55,13 +56,14 @@ function copySkills(repoRoot, target, names) {
     if (!fs.existsSync(source)) throw new Error(`missing allowlisted Claude skill: ${name}`);
     const files = copyTree(source, path.join(target, 'skills', name), {
       transform(buf, rel) {
-        if (rel !== 'SKILL.md') return buf;
+        if (rel !== 'SKILL.md') {
+          return rel.endsWith('.md')
+            ? Buffer.from(adaptInteractionGuidance(buf.toString('utf8'), 'claude'))
+            : buf;
+        }
         const { fm, body } = parseFrontmatter(buf.toString('utf8'));
         if (!fm) throw new Error(`missing frontmatter in Claude skill: ${name}`);
-        let adaptedBody = body;
-        if (name === 'learn') {
-          adaptedBody = adaptedBody.replaceAll("current host's user skill directory", '`~/.claude/skills`');
-        }
+        let adaptedBody = adaptInteractionGuidance(body, 'claude');
         if (name === 'ultra-review') {
           adaptedBody = adaptedBody.replace(
             /the current host's native bounded-worker\s+mechanism/g,

package/adapters/codex.js

@@ -8,7 +8,7 @@
  *   skills/**           -> ~/plugins/ultra-builder-pro/skills/**
  *   agents/*.md         -> ~/.codex/agents/*.toml
  *   hooks/*.py          -> plugin hooks with a Codex wire adapter
- *   mcp-server          -> plugin .mcp.json (project cwd owns .ultra/state.db)
+ *   mcp-server          -> plugin .mcp.json (project cwd owns .ultra/.runtime/state.db)
  *   plugin marketplace  -> ~/.agents/plugins/marketplace.json
  *
  * Deprecated ~/.codex/prompts and ~/.codex/skills projection is intentionally

package/adapters/kimi.js

@@ -16,6 +16,7 @@ const {
 } = require('./_shared/file-ops.cjs');
 const { buildMcpRuntime } = require('./_shared/codex-assets.cjs');
 const { parse: parseFm, serialize: serializeFm } = require('./_shared/frontmatter.cjs');
+const { adaptInteractionGuidance } = require('./_shared/interaction-contract.cjs');
 const provenance = require('./_shared/provenance.cjs');
 const {
   CORE_PUBLIC_SKILLS,
@@ -66,7 +67,7 @@ function loadRegistry(file) {
 }
 
 function kimiTextTransform(input, assetName = '') {
-  let text = String(input);
+  let text = adaptInteractionGuidance(input, 'kimi');
   text = text.replaceAll('$CLAUDE_PLUGIN_ROOT', '$KIMI_PLUGIN_ROOT');
   text = text.replaceAll('~/.claude/skills', '~/.kimi-code/skills');
   text = text.replaceAll('~/.claude/hooks', '~/.kimi-code/hooks');
@@ -99,17 +100,10 @@ function kimiTextTransform(input, assetName = '') {
       'Kimi `AgentSwarm` for parallel reviewers or one foreground Kimi `Agent` for a single reviewer, using the worker prompt files under `$KIMI_PLUGIN_ROOT/agents/`',
     );
   }
-  if (assetName === 'learn') {
-    text = text.replaceAll("current host's user skill directory", '`~/.kimi-code/skills`');
-  }
   text = text.replace(
     /(^|[\s`("'])\/ultra-(?!builder-pro:)([a-z][a-z0-9-]*)/gm,
     '$1/ultra-builder-pro:ultra-$2',
   );
-  text = text.replace(
-    /(^|[\s`("'])\/learn(?=$|[\s`),.;:])/gm,
-    '$1/ultra-builder-pro:learn',
-  );
   text = text.replace(
     /(^|[\s`("'])\/clear(?=$|[\s`),.;:])/gm,
     '$1/new',

package/adapters/opencode.js

@@ -15,6 +15,7 @@ const {
   writeAtomic,
 } = require('./_shared/file-ops.cjs');
 const { buildMcpRuntime } = require('./_shared/codex-assets.cjs');
+const { adaptInteractionGuidance } = require('./_shared/interaction-contract.cjs');
 const provenance = require('./_shared/provenance.cjs');
 const {
   CORE_PUBLIC_SKILLS,
@@ -67,7 +68,7 @@ function lowercaseFrontmatterTransform(buf, relPath) {
 }
 
 function openCodeTextTransform(input, assetName = '') {
-  let text = String(input);
+  let text = adaptInteractionGuidance(input, 'opencode');
   text = text.replaceAll('$CLAUDE_PLUGIN_ROOT/skills', '~/.config/opencode/skills');
   text = text.replaceAll('~/.claude/skills', '~/.config/opencode/skills');
   text = text.replaceAll('~/.claude/hooks', '~/.config/opencode/.ultra-builder-pro/hooks');
@@ -96,9 +97,6 @@ function openCodeTextTransform(input, assetName = '') {
       'the OpenCode `task` tool using the installed bounded review agents',
     );
   }
-  if (assetName === 'learn') {
-    text = text.replaceAll("current host's user skill directory", '`~/.config/opencode/skills`');
-  }
   return text;
 }
 
@@ -335,7 +333,6 @@ function preflightAssets(repoRoot, target) {
 
 function pluginSource() {
   return `// Managed by Ultra Builder Pro. Rebuild through the adapter; do not edit in place.
-import fs from "node:fs";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
@@ -347,36 +344,29 @@ const BREADCRUMB_CLI = path.resolve(
   PLUGIN_DIR, "..", ${JSON.stringify(BUNDLE_DIR)}, "runtime", "breadcrumb.cjs",
 );
 
-function findUltraRoot(directory) {
-  let current = path.resolve(directory);
-  while (true) {
-    const stateDb = path.join(current, ".ultra", "state.db");
-    if (fs.existsSync(stateDb) && fs.statSync(stateDb).isFile()) return current;
-    const parent = path.dirname(current);
-    if (parent === current) return null;
-    current = parent;
-  }
-}
-
 function readUltraContext(directory) {
-  const root = findUltraRoot(directory);
-  if (!root) return null;
   try {
-    const raw = execFileSync(NODE_BINARY, [BREADCRUMB_CLI, root], {
-      cwd: root,
+    const raw = execFileSync(NODE_BINARY, [BREADCRUMB_CLI, "--discover", directory], {
+      cwd: directory,
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
       timeout: 5000,
     });
     const value = JSON.parse(raw);
+    const root = value?.root;
+    if (typeof root !== "string" || !root) return null;
     // A canonical breadcrumb is injectable only while DB authority proves an active workflow.
     if (!value?.breadcrumb || !value.breadcrumb.workflow
         || typeof value.text !== "string" || !value.text) {
       return { root, breadcrumb: null, text: null };
     }
     return { root, breadcrumb: value.breadcrumb, text: value.text };
-  } catch {
-    return { root, breadcrumb: null, text: null };
+  } catch (error) {
+    const detail = String(error?.stderr || error?.message || error);
+    if (/RUNTIME_(?:STATE_CONFLICT|PATH_UNSAFE|ORPHAN_SIDECAR|ROOT_INVALID|AUTHORITY_MISMATCH)|both legacy .*runtime.*state\\.db/i.test(detail)) {
+      throw new Error(detail.trim());
+    }
+    return null;
   }
 }
 
@@ -392,11 +382,22 @@ function targetPaths(tool, args) {
   return [...new Set(paths)];
 }
 
-function isTasksProjection(active, candidate) {
+function projectionRootForTarget(baseRoot, candidate) {
   const target = path.isAbsolute(candidate)
     ? path.resolve(candidate)
-    : path.resolve(active.root, candidate);
-  return target === path.resolve(active.root, TASKS_PROJECTION);
+    : path.resolve(baseRoot, candidate);
+  if (path.basename(target) !== "tasks.json"
+      || path.basename(path.dirname(target)) !== "tasks"
+      || path.basename(path.dirname(path.dirname(target))) !== ".ultra") {
+    return null;
+  }
+  return path.dirname(path.dirname(path.dirname(target)));
+}
+
+function protectsTasksProjection(baseRoot, candidate) {
+  const targetRoot = projectionRootForTarget(baseRoot, candidate);
+  if (!targetRoot) return false;
+  return Boolean(readUltraContext(targetRoot));
 }
 
 export const UltraBuilderProPlugin = async ({ directory, worktree }) => {
@@ -417,13 +418,14 @@ export const UltraBuilderProPlugin = async ({ directory, worktree }) => {
     },
     "tool.execute.before": async (input, output) => {
       refresh();
-      if (!active) return;
       const tool = String(input?.tool ?? "").toLowerCase();
       if (!["write", "edit", "apply_patch"].includes(tool)) return;
-      if (targetPaths(tool, output?.args).some((candidate) => isTasksProjection(active, candidate))) {
+      if (targetPaths(tool, output?.args).some(
+        (candidate) => protectsTasksProjection(root, candidate),
+      )) {
         throw new Error(
           "Ultra Builder Pro refused a direct write to .ultra/tasks/tasks.json. " +
-          ".ultra/state.db is authoritative; use MCP task tools and run ultra-doctor when state or projection health is degraded."
+          ".ultra/.runtime/state.db is authoritative; use MCP task tools and run ultra-doctor when state or projection health is degraded."
         );
       }
     },

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/commands/ultra-research.md

@@ -1,5 +1,5 @@
 ---
-description: Build evidence with model-selected semantic coverage and adaptive user alignment
+description: Build evidence with recommended, owner-selected semantic coverage and adaptive alignment
 argument-hint: "[scope-or-question]"
 workflow-ref: "@skills/ultra-research/SKILL.md"
 ---