ultra-builder-pro-cli 0.25.1 → 0.26.0

package/adapters/_shared/delegate-profiles/kimi-read-only.md

@@ -0,0 +1,15 @@
+---
+name: ultra-delegate-read-only
+description: Execute one bounded Ultra delegation without file writes, shell commands, web access, MCP tools, or subagents.
+tools:
+  - Read
+  - Grep
+  - Glob
+subagents: []
+---
+
+${base_prompt}
+
+Follow the supplied immutable delegation instruction. Do not modify files, execute
+commands, access external services, dispatch subagents, or widen scope. Return the
+requested strict JSON object as the final response.

package/adapters/_shared/delegate-profiles/kimi-write.md

@@ -0,0 +1,17 @@
+---
+name: ultra-delegate-write
+description: Execute one bounded Ultra delegation with file tools only and without shell commands, web access, MCP tools, or subagents.
+tools:
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+subagents: []
+---
+
+${base_prompt}
+
+Follow the supplied immutable delegation instruction. Use file tools only inside the
+declared worktree roots. Do not execute commands, access external services, dispatch
+subagents, or widen scope. Return the requested strict JSON object as the final response.

package/adapters/_shared/file-ops.cjs

@@ -120,9 +120,18 @@ const UBP_SENTINEL_FILE = '.ubp-managed';
 // ownership before deleting (P1 #3).
 function markManaged(dir, meta = {}) {
   ensureDir(dir);
-  writeAtomic(path.join(dir, UBP_SENTINEL_FILE), JSON.stringify({
+  let previous = {};
+  const sentinel = path.join(dir, UBP_SENTINEL_FILE);
+  if (fs.existsSync(sentinel)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(sentinel, 'utf8'));
+      if (parsed?.source === 'ubp') previous = parsed;
+    } catch {}
+  }
+  writeAtomic(sentinel, JSON.stringify({
+    ...previous,
     source: 'ubp',
-    installed_at: new Date().toISOString(),
+    installed_at: previous.installed_at || new Date().toISOString(),
     ...meta,
   }, null, 2) + '\n');
 }
@@ -131,6 +140,68 @@ function isManaged(dir) {
   return fs.existsSync(path.join(dir, UBP_SENTINEL_FILE));
 }
 
+function managedMetadata(dir) {
+  const sentinel = path.join(dir, UBP_SENTINEL_FILE);
+  if (!fs.existsSync(sentinel)) return null;
+  const value = JSON.parse(fs.readFileSync(sentinel, 'utf8'));
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`invalid managed marker: ${sentinel}`);
+  }
+  if (value.source === undefined && Object.keys(value).length === 0) return {};
+  if (value.source !== 'ubp') throw new Error(`invalid managed marker: ${sentinel}`);
+  return value;
+}
+
+function normalizeOwnedRelative(value) {
+  if (value === '.') return '.';
+  if (typeof value !== 'string' || !value || path.isAbsolute(value)) {
+    throw new Error(`owned cleanup path must be relative: ${String(value)}`);
+  }
+  const normalized = path.normalize(value);
+  if (
+    normalized !== value
+    || normalized === '.'
+    || normalized === '..'
+    || normalized.startsWith(`..${path.sep}`)
+  ) {
+    throw new Error(`owned cleanup path escapes its root: ${value}`);
+  }
+  return normalized;
+}
+
+function captureAbsent(root, relatives) {
+  const absoluteRoot = path.resolve(root);
+  return [...new Set(relatives.map(normalizeOwnedRelative))]
+    .filter((relative) => !fs.existsSync(relative === '.' ? absoluteRoot : path.join(absoluteRoot, relative)));
+}
+
+function pruneCreatedEmpty(root, relatives) {
+  const absoluteRoot = path.resolve(root);
+  const ordered = [...new Set((relatives || []).map(normalizeOwnedRelative))]
+    .sort((a, b) => {
+      const depth = (value) => (value === '.' ? 0 : value.split(path.sep).length);
+      return depth(b) - depth(a);
+    });
+  const removed = [];
+  for (const relative of ordered) {
+    const target = relative === '.' ? absoluteRoot : path.resolve(absoluteRoot, relative);
+    if (target !== absoluteRoot && !target.startsWith(`${absoluteRoot}${path.sep}`)) {
+      throw new Error(`owned cleanup path escapes its root: ${relative}`);
+    }
+    if (!fs.existsSync(target)) continue;
+    const stat = fs.lstatSync(target);
+    if (stat.isSymbolicLink()) continue;
+    if (stat.isDirectory() && fs.readdirSync(target).length === 0) {
+      fs.rmdirSync(target);
+      removed.push(relative);
+    } else if (stat.isFile() && stat.size === 0) {
+      fs.unlinkSync(target);
+      removed.push(relative);
+    }
+  }
+  return removed;
+}
+
 function copyFlatByExt(srcDir, dstDir, ext) {
   if (!fs.existsSync(srcDir)) return [];
   const files = fs.readdirSync(srcDir).filter((f) => f.endsWith(ext));
@@ -152,5 +223,8 @@ module.exports = {
   removeTree,
   markManaged,
   isManaged,
+  managedMetadata,
+  captureAbsent,
+  pruneCreatedEmpty,
   copyFlatByExt,
 };

package/adapters/_shared/host-profile.cjs

@@ -0,0 +1,97 @@
+'use strict';
+
+const path = require('node:path');
+
+const KIMI_PROFILE_ROOT = path.join(__dirname, 'delegate-profiles');
+
+function opencodePermission(writableRoots) {
+  const edit = { '*': 'deny' };
+  for (const root of writableRoots) {
+    if (root === '.') edit['*'] = 'allow';
+    else edit[`${root}/**`] = 'allow';
+  }
+  return JSON.stringify({
+    share: 'disabled',
+    permission: {
+      '*': 'deny',
+      read: 'allow',
+      glob: 'allow',
+      grep: 'allow',
+      list: 'allow',
+      lsp: 'allow',
+      edit,
+      external_directory: 'deny',
+      bash: 'deny',
+      task: 'deny',
+      webfetch: 'deny',
+      websearch: 'deny',
+      question: 'deny',
+      skill: 'deny',
+    },
+  });
+}
+
+const PROFILES = Object.freeze({
+  claude: Object.freeze({
+    binary: 'claude',
+    delegateArgv: (prompt, _cwd, options) => [
+      '-p', prompt,
+      '--permission-mode', options.readOnly ? 'plan' : 'acceptEdits',
+      '--no-session-persistence',
+      '--output-format', 'json',
+      '--json-schema', options.schemaJson,
+      '--tools', options.readOnly ? 'Read,Grep,Glob' : 'Read,Write,Edit,Grep,Glob',
+    ],
+  }),
+  codex: Object.freeze({
+    binary: 'codex',
+    delegateArgv: (prompt, cwd, options) => [
+      'exec', '--ephemeral', '--ignore-user-config',
+      '--sandbox', options.readOnly ? 'read-only' : 'workspace-write',
+      '--cd', cwd,
+      '--config', 'sandbox_workspace_write.network_access=false',
+      '--output-schema', options.schemaFile,
+      '--output-last-message', options.hostOutput,
+      '--json', prompt,
+    ],
+  }),
+  opencode: Object.freeze({
+    binary: 'opencode',
+    delegateArgv: (prompt, cwd) => [
+      'run', '--dir', cwd, '--format', 'json', '--auto', prompt,
+    ],
+    delegateEnv: (options) => ({
+      OPENCODE_CONFIG_CONTENT: opencodePermission(options.writableRoots),
+    }),
+  }),
+  kimi: Object.freeze({
+    binary: 'kimi',
+    delegateArgv: (prompt, _cwd, options) => [
+      '-p', prompt,
+      '--output-format', 'stream-json',
+      '--agent-file', path.join(
+        KIMI_PROFILE_ROOT,
+        options.readOnly ? 'kimi-read-only.md' : 'kimi-write.md',
+      ),
+    ],
+  }),
+  grok: Object.freeze({
+    binary: 'grok',
+    delegateArgv: (prompt, cwd, options) => [
+      '--cwd', cwd, '--single', prompt,
+      '--permission-mode', options.readOnly ? 'plan' : 'acceptEdits',
+      '--sandbox', options.readOnly ? 'read-only' : 'workspace',
+      '--no-memory', '--no-subagents', '--disable-web-search',
+      '--json-schema', options.schemaJson,
+      '--output-format', 'json',
+    ],
+  }),
+});
+
+function hostProfile(runtime) {
+  const profile = PROFILES[runtime];
+  if (!profile) throw new Error(`unsupported delegate host: ${runtime}`);
+  return profile;
+}
+
+module.exports = { PROFILES, hostProfile, opencodePermission };

package/adapters/_shared/plugin-core.cjs

@@ -0,0 +1,204 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const {
+  copyTree,
+  ensureDir,
+  isManaged,
+  markManaged,
+  removeTree,
+  writeAtomic,
+} = require('./file-ops.cjs');
+const { parse, serialize } = require('./frontmatter.cjs');
+const provenance = require('./provenance.cjs');
+const {
+  MODEL_INVOKED_SKILLS,
+  WORKFLOW_HOOK_FILES,
+  skillPolicy,
+  skillsForRuntime,
+} = require('./runtime-assets.cjs');
+
+const PROVENANCE_FILE = 'provenance.json';
+
+function titleCase(name) {
+  return name.split('-').map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(' ');
+}
+
+function skillFrontmatter(runtime, name, fm) {
+  const base = { name, description: String(fm.description || '') };
+  const policy = skillPolicy(name);
+  if (runtime === 'claude' || runtime === 'grok') {
+    return {
+      ...base,
+      'user-invocable': policy.userInvocable,
+      ...(policy.userInvocable ? { 'disable-model-invocation': true } : {}),
+    };
+  }
+  if (runtime === 'kimi') {
+    return {
+      ...base,
+      ...(policy.userInvocable ? { disableModelInvocation: true } : {}),
+    };
+  }
+  return base;
+}
+
+function codexMetadata(name, description) {
+  const short = String(description).replace(/\s+/g, ' ').trim().slice(0, 64).replace(/[\s.,;:]+$/, '');
+  return [
+    'interface:',
+    `  display_name: ${JSON.stringify(titleCase(name))}`,
+    `  short_description: ${JSON.stringify(short || titleCase(name))}`,
+    `  default_prompt: ${JSON.stringify(`Use $ultra-builder-pro:${name} and follow its workflow.`)}`,
+    'policy:',
+    `  allow_implicit_invocation: ${MODEL_INVOKED_SKILLS.includes(name) ? 'true' : 'false'}`,
+    '',
+  ].join('\n');
+}
+
+function copySkills({ runtime, repoRoot, skillRoot }) {
+  const installed = [];
+  for (const name of skillsForRuntime(runtime)) {
+    const source = path.join(repoRoot, 'skills', name);
+    if (!fs.existsSync(path.join(source, 'SKILL.md'))) {
+      throw new Error(`missing allowlisted ${runtime} skill: ${name}`);
+    }
+    const target = path.join(skillRoot, name);
+    copyTree(source, target, {
+      transform(buffer, relative) {
+        if (relative !== 'SKILL.md') return buffer;
+        const { fm, body } = parse(buffer.toString('utf8'));
+        if (!fm) throw new Error(`missing frontmatter in ${name}`);
+        return Buffer.from(serialize(skillFrontmatter(runtime, name, fm), body));
+      },
+    });
+    if (name === 'ultra-init') {
+      const template = path.join(repoRoot, '.ultra-template');
+      if (!fs.existsSync(template)) throw new Error('missing canonical .ultra-template');
+      copyTree(template, path.join(target, 'assets', 'project-template'));
+    }
+    if (runtime === 'codex') {
+      const { fm } = parse(fs.readFileSync(path.join(source, 'SKILL.md'), 'utf8'));
+      writeAtomic(
+        path.join(target, 'agents', 'openai.yaml'),
+        codexMetadata(name, fm.description),
+      );
+    }
+    installed.push(name);
+  }
+  return installed;
+}
+
+function copyHooks({ runtime, repoRoot, hookRoot, hooksManifest }) {
+  ensureDir(hookRoot);
+  for (const name of [...WORKFLOW_HOOK_FILES, '_common.py']) {
+    const source = path.join(repoRoot, 'hooks', name);
+    if (!fs.existsSync(source)) throw new Error(`missing allowlisted hook: ${name}`);
+    fs.copyFileSync(source, path.join(hookRoot, name));
+  }
+  if (['codex', 'kimi', 'grok'].includes(runtime)) {
+    ensureDir(path.join(hookRoot, 'adapters'));
+    fs.copyFileSync(
+      path.join(repoRoot, 'hooks', 'adapters', `${runtime}.py`),
+      path.join(hookRoot, 'adapters', `${runtime}.py`),
+    );
+  }
+  writeAtomic(path.join(hookRoot, 'hooks.json'), `${JSON.stringify(hooksManifest, null, 2)}\n`);
+  return [...WORKFLOW_HOOK_FILES];
+}
+
+function writePluginProvenance({ adapter, repoRoot, stagingRoot, publishedRoot, contracts = {} }) {
+  const source = provenance.packageSource(repoRoot);
+  return provenance.writeProvenance({
+    file: path.join(stagingRoot, PROVENANCE_FILE),
+    adapter,
+    ...source,
+    roots: { plugin: publishedRoot },
+    assetRoots: { plugin: stagingRoot },
+    assets: provenance.assetRefsForTree('plugin', stagingRoot, {
+      exclude: ['.ubp-managed', PROVENANCE_FILE],
+    }),
+    contracts,
+  });
+}
+
+function publishManagedTrees(entries) {
+  const transaction = [];
+  for (const { source, target, label } of entries) {
+    if (fs.existsSync(target) && !isManaged(target)) {
+      throw new Error(`refusing to replace unmanaged ${label}: ${target}`);
+    }
+    ensureDir(path.dirname(target));
+  }
+  try {
+    for (const { source, target } of entries) {
+      const backup = `${target}.ubp-backup-${crypto.randomUUID()}`;
+      if (fs.existsSync(target)) fs.renameSync(target, backup);
+      fs.renameSync(source, target);
+      transaction.push({ target, backup });
+    }
+    for (const { backup } of transaction) {
+      if (fs.existsSync(backup)) removeTree(backup);
+    }
+  } catch (error) {
+    for (const { target, backup } of transaction.reverse()) {
+      if (fs.existsSync(target)) removeTree(target);
+      if (fs.existsSync(backup)) fs.renameSync(backup, target);
+    }
+    throw error;
+  }
+}
+
+function inspectPlugin({ adapter, repoRoot, pluginRoot, skillRoot, hookRoot, manifestFile }) {
+  const source = provenance.packageSource(repoRoot);
+  const report = provenance.inspectProvenance({
+    file: path.join(pluginRoot, PROVENANCE_FILE),
+    expectedAdapter: adapter,
+    expectedPackageVersion: source.packageInfo.version,
+  });
+  const issue = (code, details = {}) => report.issues.push({ code, ...details });
+  if (!fs.existsSync(manifestFile)) issue('PLUGIN_MANIFEST_MISSING', { path: manifestFile });
+  for (const name of skillsForRuntime(adapter)) {
+    if (!fs.existsSync(path.join(skillRoot, name, 'SKILL.md'))) {
+      issue('SKILL_MISSING', { skill: name });
+    }
+  }
+  for (const name of [...WORKFLOW_HOOK_FILES, '_common.py']) {
+    if (!fs.existsSync(path.join(hookRoot, name))) issue('HOOK_MISSING', { hook: name });
+  }
+  for (const retired of ['commands', 'agents', 'runtime', '.mcp.json']) {
+    if (fs.existsSync(path.join(pluginRoot, retired))) issue('RETIRED_ASSET_PRESENT', { path: retired });
+  }
+  report.checks.skill_inventory = {
+    status: report.issues.some((entry) => entry.code === 'SKILL_MISSING') ? 'fail' : 'pass',
+  };
+  report.checks.hook_inventory = {
+    status: report.issues.some((entry) => entry.code === 'HOOK_MISSING') ? 'fail' : 'pass',
+  };
+  report.checks.plugin_manifest = {
+    status: fs.existsSync(manifestFile) ? 'pass' : 'fail',
+  };
+  report.status = report.issues.length === 0 ? 'healthy' : 'degraded';
+  return report;
+}
+
+function removeManaged(target, label) {
+  if (!fs.existsSync(target)) return false;
+  if (!isManaged(target)) throw new Error(`refusing to remove unmanaged ${label}: ${target}`);
+  removeTree(target);
+  return true;
+}
+
+module.exports = {
+  PROVENANCE_FILE,
+  copySkills,
+  copyHooks,
+  inspectPlugin,
+  markManaged,
+  publishManagedTrees,
+  removeManaged,
+  writePluginProvenance,
+};

package/adapters/_shared/runtime-assets.cjs

@@ -1,109 +1,47 @@
 'use strict';
 
 /**
- * Canonical Ultra Builder Pro package boundary.
+ * Canonical v0.26 package boundary.
  *
- * Adapters must build from this allowlist. A new directory under skills/ or
- * hooks/ is not packaged until it is deliberately classified here.
+ * Skills carry semantic workflow. Hooks are optional acceleration and safety.
+ * There is no prompt projection, worker registry, MCP kernel, or runtime daemon.
  */
 
-const CORE_PUBLIC_SKILLS = Object.freeze([
+const USER_INVOKED_SKILLS = Object.freeze([
   'ultra-init',
   'ultra-research',
+  'ultra-change',
   'ultra-plan',
   'ultra-dev',
   'ultra-test',
-  'ultra-review',
   'ultra-deliver',
-  'ultra-status',
-  'ultra-think',
-  'ultra-change',
-  'ultra-doctor',
+  'ultra-delegate',
 ]);
 
-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: 'host_model_from_ultra_context',
-      recommendation_owner: 'host_model',
-      selection_owner: 'user',
-      automatic_invocation: false,
-    }),
-  ]),
-));
-
-const INTERNAL_AGENT_SKILLS = Object.freeze([
-  'code-review-expert',
-  'security-rules',
-  'integration-rules',
-  'testing-rules',
+const MODEL_INVOKED_SKILLS = Object.freeze([
+  'ultra-grilling',
+  'ultra-domain-modeling',
+  'ultra-tdd',
+  'ultra-review',
+  'ultra-think',
 ]);
 
+const ROUTER_SKILLS = Object.freeze(['ultra-status']);
 const SUPPORTED_RUNTIMES = Object.freeze(['claude', 'opencode', 'codex', 'kimi', 'grok']);
 
-const COLLAB_SKILLS_BY_RUNTIME = Object.freeze({
-  claude: Object.freeze(['codex-collab', 'ultra-verify']),
-  codex: Object.freeze(['cc-collab', 'ultra-verify']),
-  opencode: Object.freeze(['cc-collab', 'codex-collab', 'ultra-verify']),
-  kimi: Object.freeze(['cc-collab', 'codex-collab', 'ultra-verify']),
-  grok: Object.freeze(['cc-collab', 'codex-collab', 'ultra-verify']),
-});
-
-const MCP_DEPENDENT_SKILLS = Object.freeze([
-  'ultra-init',
-  'ultra-research',
-  'ultra-change',
-  'ultra-plan',
-  'ultra-dev',
-  'ultra-test',
-  'ultra-review',
-  'ultra-deliver',
-  'ultra-status',
-  'ultra-doctor',
-]);
-
 const WORKFLOW_HOOK_FILES = Object.freeze([
-  'active_task_context.py',
-  'context_envelope.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',
+  'session_context.py',
+  'mid_workflow_recall.py',
+  'compact_context.py',
+  'post_edit_guard.py',
+  'block_dangerous_commands.py',
 ]);
 
 function skillsForRuntime(runtime) {
-  const collab = COLLAB_SKILLS_BY_RUNTIME[runtime];
-  if (!collab) throw new Error(`unsupported Ultra runtime: ${runtime}`);
-  return [...CORE_PUBLIC_SKILLS, ...INTERNAL_AGENT_SKILLS, ...collab];
+  if (!SUPPORTED_RUNTIMES.includes(runtime)) {
+    throw new Error(`unsupported Ultra runtime: ${runtime}`);
+  }
+  return [...USER_INVOKED_SKILLS, ...MODEL_INVOKED_SKILLS, ...ROUTER_SKILLS];
 }
 
 function isSupportedRuntime(runtime) {
@@ -111,25 +49,22 @@ function isSupportedRuntime(runtime) {
 }
 
 function skillPolicy(name) {
-  const packaged = SUPPORTED_RUNTIMES.some((runtime) => skillsForRuntime(runtime).includes(name));
-  if (!packaged) throw new Error(`unknown packaged Ultra skill: ${name}`);
+  if (!skillsForRuntime(SUPPORTED_RUNTIMES[0]).includes(name)) {
+    throw new Error(`unknown packaged Ultra skill: ${name}`);
+  }
+  const modelInvoked = MODEL_INVOKED_SKILLS.includes(name);
   return {
-    userInvocable: !INTERNAL_AGENT_SKILLS.includes(name),
-    allowImplicitInvocation: false,
-    requiresUltraMcp: MCP_DEPENDENT_SKILLS.includes(name),
+    userInvocable: !modelInvoked,
+    allowImplicitInvocation: modelInvoked,
   };
 }
 
 module.exports = {
-  CORE_PUBLIC_SKILLS,
-  PUBLIC_CAPABILITY_GRAPH,
-  INTERNAL_AGENT_SKILLS,
+  USER_INVOKED_SKILLS,
+  MODEL_INVOKED_SKILLS,
+  ROUTER_SKILLS,
   SUPPORTED_RUNTIMES,
-  COLLAB_SKILLS_BY_RUNTIME,
-  MCP_DEPENDENT_SKILLS,
-  RUNTIME_SUPPORT_FILES,
   WORKFLOW_HOOK_FILES,
-  RUNTIME_WORKER_FILES,
   isSupportedRuntime,
   skillPolicy,
   skillsForRuntime,