ultra-builder-pro-cli 0.5.0

package/adapters/_shared/codex-ultra-tools-entry.cjs

@@ -0,0 +1,11 @@
+'use strict';
+
+const path = require('node:path');
+
+// ncc emits this entrypoint into <plugin>/runtime/ultra-tools.cjs. Set the
+// runtime asset root before loading modules that read schemas or templates.
+process.env.UBP_RUNTIME_ROOT = path.resolve(__dirname, '..');
+
+const { main } = require('../../ultra-tools/cli.cjs');
+
+main(process.argv);

package/adapters/_shared/file-ops.cjs

@@ -0,0 +1,115 @@
+'use strict';
+
+// File-system primitives shared by every runtime adapter.
+// Pure filesystem — no runtime coupling. Kept small; each adapter layers
+// its own runtime-specific behavior on top.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const DEFAULT_EXCLUDES = new Set(['.DS_Store', 'Thumbs.db']);
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function writeAtomic(file, content) {
+  ensureDir(path.dirname(file));
+  // randomUUID defeats predictable tmp-name attacks and PID+ms collisions
+  // when two writers hit the same path inside one millisecond.
+  const tmp = `${file}.tmp-${crypto.randomUUID()}`;
+  fs.writeFileSync(tmp, content);
+  fs.renameSync(tmp, file);
+}
+
+function listRelative(root, { exclude = DEFAULT_EXCLUDES } = {}) {
+  const out = [];
+  (function walk(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (exclude.has(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile()) out.push(path.relative(root, full));
+    }
+  })(root);
+  return out.sort();
+}
+
+function copyTree(src, dst, { exclude = DEFAULT_EXCLUDES, transform } = {}) {
+  const files = listRelative(src, { exclude });
+  for (const rel of files) {
+    const from = path.join(src, rel);
+    const to = path.join(dst, rel);
+    ensureDir(path.dirname(to));
+    if (transform) {
+      const original = fs.readFileSync(from);
+      const rewritten = transform(original, rel);
+      writeAtomic(to, rewritten);
+    } else {
+      fs.copyFileSync(from, to);
+    }
+  }
+  return files;
+}
+
+function removeTree(target, { allowRoot = false } = {}) {
+  const abs = path.resolve(target);
+  if (!allowRoot && (abs === '/' || abs === path.parse(abs).root)) {
+    throw new Error(`refusing to remove filesystem root: ${abs}`);
+  }
+  // Guard against a target that is itself a symlink: unlink the link,
+  // don't rmSync through it (which would delete the target's contents).
+  try {
+    const lst = fs.lstatSync(abs);
+    if (lst.isSymbolicLink()) {
+      fs.unlinkSync(abs);
+      return;
+    }
+  } catch (err) {
+    if (err.code === 'ENOENT') return;
+    throw err;
+  }
+  fs.rmSync(abs, { recursive: true, force: true });
+}
+
+const UBP_SENTINEL_FILE = '.ubp-managed';
+
+// Write a sentinel file into a managed directory so uninstall can verify
+// ownership before deleting (P1 #3).
+function markManaged(dir, meta = {}) {
+  ensureDir(dir);
+  writeAtomic(path.join(dir, UBP_SENTINEL_FILE), JSON.stringify({
+    source: 'ubp',
+    installed_at: new Date().toISOString(),
+    ...meta,
+  }, null, 2) + '\n');
+}
+
+function isManaged(dir) {
+  return fs.existsSync(path.join(dir, UBP_SENTINEL_FILE));
+}
+
+function copyFlatByExt(srcDir, dstDir, ext) {
+  if (!fs.existsSync(srcDir)) return [];
+  const files = fs.readdirSync(srcDir).filter((f) => f.endsWith(ext));
+  if (files.length === 0) return [];
+  ensureDir(dstDir);
+  for (const f of files) {
+    fs.copyFileSync(path.join(srcDir, f), path.join(dstDir, f));
+  }
+  return files;
+}
+
+module.exports = {
+  DEFAULT_EXCLUDES,
+  UBP_SENTINEL_FILE,
+  ensureDir,
+  writeAtomic,
+  listRelative,
+  copyTree,
+  removeTree,
+  markManaged,
+  isManaged,
+  copyFlatByExt,
+};

package/adapters/_shared/frontmatter.cjs

@@ -0,0 +1,52 @@
+'use strict';
+
+// YAML frontmatter parsing / serialization for markdown assets.
+// Every runtime adapter consumes this — OpenCode lowercases keys,
+// Gemini extracts description for toml, Claude preserves verbatim.
+
+const yaml = require('js-yaml');
+
+const DELIMITER = '---';
+
+function parse(text) {
+  if (typeof text !== 'string') throw new TypeError('parse() expects string');
+  if (!text.startsWith(DELIMITER)) {
+    return { fm: null, body: text, bodyStart: 0 };
+  }
+  const end = text.indexOf(`\n${DELIMITER}`, DELIMITER.length);
+  if (end === -1) {
+    return { fm: null, body: text, bodyStart: 0 };
+  }
+  const raw = text.slice(DELIMITER.length, end).trim();
+  const fm = yaml.load(raw) || null;
+  // end points at "\n---"; skip "\n---" (4 chars) to land on whatever follows the closing delimiter
+  const bodyStart = end + DELIMITER.length + 1;
+  let body = text.slice(bodyStart);
+  // Strip leading blank line(s) separating frontmatter from body (Markdown convention)
+  body = body.replace(/^\n+/, '');
+  return { fm, body, bodyStart };
+}
+
+function serialize(fm, body = '') {
+  if (fm == null) return body;
+  const yamlBody = yaml.dump(fm, { lineWidth: -1, noRefs: true }).trimEnd();
+  return `${DELIMITER}\n${yamlBody}\n${DELIMITER}\n${body}`;
+}
+
+function lowercaseKeys(obj) {
+  if (Array.isArray(obj)) return obj.map(lowercaseKeys);
+  if (obj === null || typeof obj !== 'object') return obj;
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    out[k.toLowerCase()] = lowercaseKeys(v);
+  }
+  return out;
+}
+
+function patch(text, patchFn) {
+  const { fm, body } = parse(text);
+  const nextFm = patchFn(fm ? { ...fm } : {});
+  return serialize(nextFm, body);
+}
+
+module.exports = { parse, serialize, lowercaseKeys, patch };

package/adapters/_shared/handbook.cjs

@@ -0,0 +1,144 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { writeAtomic } = require('./file-ops.cjs');
+
+const BEGIN_MARKER = '<!-- ultra-builder-pro:handbook:start -->';
+const END_MARKER = '<!-- ultra-builder-pro:handbook:end -->';
+const LEGACY_HEADING = '## Ultra Builder Pro Runtime Contract';
+
+const HOSTS = Object.freeze({
+  claude: Object.freeze({
+    name: 'Claude Code',
+    handbook: ['.claude', 'CLAUDE.md'],
+    invocation: '`/ultra-init`, `/ultra-research`, `/ultra-plan`, `/ultra-dev`, `/ultra-test`, `/ultra-review`, and `/ultra-deliver`; diagnostics use `/ultra-status` and `/ultra-think`',
+    collaboration: '`/codex-collab` and `/gemini-collab` are explicitly requested read-only advisors',
+    coordination: 'Claude Code task UI is host coordination; it does not replace Ultra task state',
+  }),
+  codex: Object.freeze({
+    name: 'Codex',
+    handbook: ['.codex', 'AGENTS.md'],
+    invocation: '`$ultra-builder-pro:ultra-init`, `$ultra-builder-pro:ultra-research`, `$ultra-builder-pro:ultra-plan`, `$ultra-builder-pro:ultra-dev`, `$ultra-builder-pro:ultra-test`, `$ultra-builder-pro:ultra-review`, and `$ultra-builder-pro:ultra-deliver`; diagnostics use `$ultra-builder-pro:ultra-status` and `$ultra-builder-pro:ultra-think`',
+    collaboration: '`$ultra-builder-pro:cc-collab` and `$ultra-builder-pro:gemini-collab` are explicitly requested read-only advisors',
+    coordination: 'The Codex plan is turn-facing coordination; it does not replace Ultra task state',
+  }),
+  opencode: Object.freeze({
+    name: 'OpenCode',
+    handbook: ['.config', 'opencode', 'AGENTS.md'],
+    invocation: '`/ultra-init`, `/ultra-research`, `/ultra-plan`, `/ultra-dev`, `/ultra-test`, `/ultra-review`, and `/ultra-deliver`; diagnostics use `/ultra-status` and `/ultra-think`',
+    collaboration: '`/cc-collab`, `/codex-collab`, and `/gemini-collab` are explicitly requested read-only advisors',
+    coordination: 'OpenCode session coordination does not replace Ultra task state',
+  }),
+});
+
+function host(runtime) {
+  const value = HOSTS[runtime];
+  if (!value) throw new Error(`unsupported handbook runtime: ${runtime}`);
+  return value;
+}
+
+function renderHandbook(runtime) {
+  const value = host(runtime);
+  return [
+    BEGIN_MARKER,
+    '## Ultra Builder Pro Runtime Contract',
+    '',
+    `Ultra Builder Pro is installed as a native ${value.name} plugin. Keep general engineering`,
+    'policy in this handbook and detailed Ultra procedures in the plugin skills.',
+    '',
+    `- Workflow entry points: ${value.invocation}.`,
+    `- Collaboration boundary: ${value.collaboration}. The current host remains primary and owns final verification.`,
+    `- Coordination boundary: ${value.coordination}.`,
+    '- Authority: `.ultra/state.db` is the only durable Ultra authority for tasks, sessions, events, telemetry, and review evidence. Generated JSON and Markdown are projections or workflow artifacts.',
+    '- Memory boundary: Ultra Builder Pro does not capture prompts, transcripts, observations, summaries, or cross-session memory. Persistent memory belongs to a separately installed provider such as cloud-mem or claude-mem.',
+    '- Hook boundary: Ultra hooks are workflow-only lifecycle adapters and are no-ops unless `.ultra/workflow-state.json` describes an active non-terminal workflow. Generic command blocking and post-edit policy stay in user or repository governance.',
+    '- Agent boundary: the bundled review and debugging agents are bounded workers. They use the current checkout and parent-supplied context, do not own private persistent state, and never replace the primary agent.',
+    '- Package boundary: only the ten Ultra workflows, four internal review-rule skills, and host-specific collaboration companions belong to this plugin. General browser, deployment, discovery, and framework skills must be installed from their owners.',
+    END_MARKER,
+  ].join('\n');
+}
+
+function markerCount(text, marker) {
+  return text.split(marker).length - 1;
+}
+
+function replaceManagedBlock(existing, block) {
+  const beginCount = markerCount(existing, BEGIN_MARKER);
+  const endCount = markerCount(existing, END_MARKER);
+  if (beginCount !== endCount || beginCount > 1) {
+    throw new Error('handbook contains malformed or duplicate Ultra managed markers');
+  }
+  if (beginCount === 0) return null;
+
+  const start = existing.indexOf(BEGIN_MARKER);
+  const end = existing.indexOf(END_MARKER, start) + END_MARKER.length;
+  return existing.slice(0, start) + block + existing.slice(end);
+}
+
+function replaceLegacyCodexSection(existing, block) {
+  const heading = new RegExp(`^${LEGACY_HEADING.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[^\\n]*$`, 'm');
+  const match = heading.exec(existing);
+  if (!match) return null;
+
+  const start = match.index;
+  const remainder = existing.slice(start + match[0].length);
+  const nextHeading = /^##\s+/m.exec(remainder);
+  const end = nextHeading ? start + match[0].length + nextHeading.index : existing.length;
+  const before = existing.slice(0, start).trimEnd();
+  const after = existing.slice(end).trimStart();
+  return `${before}${before ? '\n\n' : ''}${block}${after ? `\n\n${after}` : '\n'}`;
+}
+
+function mergeHandbook(existing, runtime) {
+  host(runtime);
+  const current = typeof existing === 'string' ? existing : '';
+  const block = renderHandbook(runtime);
+  const managed = replaceManagedBlock(current, block);
+  if (managed !== null) return managed;
+
+  if (runtime === 'codex') {
+    const migrated = replaceLegacyCodexSection(current, block);
+    if (migrated !== null) return migrated;
+  }
+
+  const before = current.trimEnd();
+  return `${before}${before ? '\n\n' : ''}${block}\n`;
+}
+
+function resolveHandbookFile(runtime, { homeDir = os.homedir() } = {}) {
+  return path.join(homeDir, ...host(runtime).handbook);
+}
+
+function timestamp() {
+  return new Date().toISOString().replace(/[-:.]/g, '').replace(/\.\d{3}Z$/, 'Z');
+}
+
+function applyHandbook({ runtime, file, homeDir, now = timestamp() }) {
+  const target = path.resolve(file || resolveHandbookFile(runtime, { homeDir }));
+  const exists = fs.existsSync(target);
+  const existing = exists ? fs.readFileSync(target, 'utf8') : '';
+  const merged = mergeHandbook(existing, runtime);
+  if (merged === existing) return { runtime, file: target, changed: false, backup: null };
+
+  let backup = null;
+  if (exists) {
+    backup = `${target}.ubp-backup-${now}`;
+    if (fs.existsSync(backup)) throw new Error(`handbook backup already exists: ${backup}`);
+    writeAtomic(backup, existing);
+  }
+  writeAtomic(target, merged);
+  return { runtime, file: target, changed: true, backup };
+}
+
+module.exports = {
+  BEGIN_MARKER,
+  END_MARKER,
+  HOSTS,
+  applyHandbook,
+  mergeHandbook,
+  renderHandbook,
+  resolveHandbookFile,
+};

package/adapters/_shared/md-to-toml.cjs

@@ -0,0 +1,54 @@
+'use strict';
+
+// Convert a thin-shell command .md file to a Gemini custom-command TOML.
+// Gemini commands live in `~/.gemini/commands/<name>.toml` with shape:
+//
+//   description = "…"
+//   prompt = """
+//   <command body>
+//   """
+//
+// Only the description (from frontmatter) and the body text cross over.
+// Frontmatter keys like `workflow-ref` are inlined into the prompt so the
+// agent still sees the skill reference.
+
+const { parse: parseFrontmatter } = require('./frontmatter.cjs');
+
+function escapeTomlLiteral(str) {
+  // Gemini accepts """multi-line""" literals. Escape any triple-quote to be safe.
+  return String(str).replace(/"""/g, '\\"\\"\\"');
+}
+
+function buildPromptSection(fm, body) {
+  const lines = [];
+  if (fm && fm['workflow-ref']) {
+    lines.push(`[ultra-builder-pro] workflow reference: ${fm['workflow-ref']}`);
+  }
+  if (fm && Array.isArray(fm.mcp_tools_required) && fm.mcp_tools_required.length > 0) {
+    lines.push(`[ultra-builder-pro] MCP tools required: ${fm.mcp_tools_required.join(', ')}`);
+  }
+  if (fm && fm.cli_fallback) {
+    lines.push(`[ultra-builder-pro] CLI fallback: ultra-tools ${fm.cli_fallback}`);
+  }
+  if (lines.length > 0) lines.push('');
+  lines.push(body.trimEnd());
+  return lines.join('\n');
+}
+
+function mdCommandToToml(mdText) {
+  if (typeof mdText !== 'string') throw new TypeError('mdCommandToToml: expects string');
+  const { fm, body } = parseFrontmatter(mdText);
+  const description = (fm && fm.description) || 'Ultra Builder Pro command';
+  const prompt = buildPromptSection(fm, body);
+
+  const tomlLines = [
+    `description = ${JSON.stringify(description)}`,
+    'prompt = """',
+    escapeTomlLiteral(prompt),
+    '"""',
+    '',
+  ];
+  return tomlLines.join('\n');
+}
+
+module.exports = { mdCommandToToml };

package/adapters/_shared/path-rewrite.cjs

@@ -0,0 +1,79 @@
+'use strict';
+
+// Path-rewriting helpers for workflow-ref resolution per runtime.
+// The canonical form in commands/*.md is `@skills/<name>/SKILL.md`. Each
+// runtime stores skills under a different root — this module converts
+// the symbolic ref into a concrete path (or leaves it symbolic for
+// runtimes that understand the shorthand).
+
+const path = require('node:path');
+
+const SKILL_REF_RE = /^@skills\/([a-z][a-z0-9\-]*)\/SKILL\.md$/;
+
+const RUNTIME_SKILL_ROOT = {
+  claude: '.claude/skills',
+  opencode: '.config/opencode/skills',
+  codex: '.agents/skills',
+  gemini: '.gemini/extensions/ultra-builder-pro/skills',
+};
+
+function parseSkillRef(ref) {
+  if (typeof ref !== 'string') return null;
+  const m = ref.match(SKILL_REF_RE);
+  if (!m) return null;
+  return { name: m[1], filename: 'SKILL.md' };
+}
+
+function resolveSkillRef(ref, { runtime, homeDir }) {
+  const parsed = parseSkillRef(ref);
+  if (!parsed) throw new Error(`invalid skill ref: ${ref}`);
+  const root = RUNTIME_SKILL_ROOT[runtime];
+  if (!root) throw new Error(`unknown runtime: ${runtime}`);
+  return path.join(homeDir, root, parsed.name, parsed.filename);
+}
+
+function rewriteWorkflowRefInText(text, { runtime, homeDir }) {
+  return text.replace(/@skills\/([a-z][a-z0-9\-]*)\/SKILL\.md/g, (match) => {
+    const parsed = parseSkillRef(match);
+    if (!parsed) return match;
+    return resolveSkillRef(match, { runtime, homeDir });
+  });
+}
+
+function resolveAssetTarget(srcRel, { runtime, scope, homeDir, cwd }) {
+  const base = scope === 'global'
+    ? path.join(homeDir, runtimeRoot(runtime))
+    : path.join(cwd, localRoot(runtime));
+  return path.join(base, srcRel);
+}
+
+function runtimeRoot(runtime) {
+  switch (runtime) {
+    case 'claude': return '.claude';
+    case 'opencode': return '.config/opencode';
+    case 'codex': return '.agents';
+    case 'gemini': return '.gemini/extensions/ultra-builder-pro';
+    default: throw new Error(`unknown runtime: ${runtime}`);
+  }
+}
+
+function localRoot(runtime) {
+  switch (runtime) {
+    case 'claude': return '.claude';
+    case 'opencode': return '.opencode';
+    case 'codex': return '.agents';
+    case 'gemini': return '.gemini/extensions/ultra-builder-pro';
+    default: throw new Error(`unknown runtime: ${runtime}`);
+  }
+}
+
+module.exports = {
+  SKILL_REF_RE,
+  RUNTIME_SKILL_ROOT,
+  parseSkillRef,
+  resolveSkillRef,
+  rewriteWorkflowRefInText,
+  resolveAssetTarget,
+  runtimeRoot,
+  localRoot,
+};

package/adapters/_shared/rtk-detect.cjs

@@ -0,0 +1,86 @@
+'use strict';
+
+// Phase 6.1 — RTK soft dependency.
+//
+// RTK (Rust Token Killer) is an external CLI proxy the user installs
+// separately. We never hard-require it: installation continues even when
+// rtk is missing, we just print an install hint. This mirrors PLAN Phase
+// 6.1: "无 rtk → 提示安装 + 跳过（不硬依赖）".
+//
+// Tests inject a PATH override so we can exercise the happy/missing paths
+// without touching the real rtk binary on the machine.
+
+const { execFileSync } = require('node:child_process');
+
+const INSTALL_HINT =
+  'rtk not found. RTK is a token-saving proxy that rewrites Bash/git/npm\n' +
+  '  commands transparently. Install: https://github.com/rcrocky/rtk\n' +
+  '  (or run `cargo install rtk`). Continuing without RTK.';
+
+function envWithPath(pathOverride) {
+  if (!pathOverride) return process.env;
+  // Isolate rtk lookup to pathOverride + minimal system dirs (so shebangs
+  // like `/usr/bin/env bash` still resolve). Tests use this to cut off the
+  // real rtk binary on the developer's machine.
+  return { ...process.env, PATH: `${pathOverride}:/usr/bin:/bin` };
+}
+
+function detectRtk({ pathOverride = null, timeoutMs = 3000 } = {}) {
+  try {
+    const stdout = execFileSync('rtk', ['--version'], {
+      env: envWithPath(pathOverride),
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: timeoutMs,
+    });
+    return { available: true, version: stdout.toString().trim() };
+  } catch (err) {
+    return {
+      available: false,
+      reason: err && err.code === 'ENOENT' ? 'binary not on PATH' : (err && err.message) || 'unknown',
+    };
+  }
+}
+
+function initRtk({ pathOverride = null, scope = 'global', timeoutMs = 10000 } = {}) {
+  const args = ['init'];
+  if (scope === 'global') args.push('-g');
+  try {
+    const stdout = execFileSync('rtk', args, {
+      env: envWithPath(pathOverride),
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: timeoutMs,
+    });
+    return { ok: true, stdout: stdout.toString() };
+  } catch (err) {
+    return { ok: false, error: (err && err.message) || 'unknown' };
+  }
+}
+
+// High-level entry: detect + optionally init, never throws.
+// Caller passes {skip:true} to honor --skip-rtk flag.
+function installHook({ skip = false, pathOverride = null, scope = 'global' } = {}) {
+  if (skip) return { skipped: true };
+  const detection = detectRtk({ pathOverride });
+  if (!detection.available) {
+    return {
+      available: false,
+      initialized: false,
+      reason: detection.reason,
+      hint: INSTALL_HINT,
+    };
+  }
+  const initResult = initRtk({ pathOverride, scope });
+  return {
+    available: true,
+    initialized: initResult.ok,
+    version: detection.version,
+    init_error: initResult.ok ? undefined : initResult.error,
+  };
+}
+
+module.exports = {
+  detectRtk,
+  initRtk,
+  installHook,
+  INSTALL_HINT,
+};

package/adapters/_shared/runtime-assets.cjs

@@ -0,0 +1,70 @@
+'use strict';
+
+/**
+ * Canonical Ultra Builder Pro package boundary.
+ *
+ * Adapters must build from this allowlist. A new directory under skills/ or
+ * hooks/ is not packaged until it is deliberately classified here.
+ */
+
+const CORE_PUBLIC_SKILLS = Object.freeze([
+  'learn',
+  'ultra-init',
+  'ultra-research',
+  'ultra-plan',
+  'ultra-dev',
+  'ultra-test',
+  'ultra-review',
+  'ultra-deliver',
+  'ultra-status',
+  'ultra-think',
+]);
+
+const INTERNAL_AGENT_SKILLS = Object.freeze([
+  'code-review-expert',
+  'security-rules',
+  'integration-rules',
+  'testing-rules',
+]);
+
+const COLLAB_SKILLS_BY_RUNTIME = Object.freeze({
+  claude: Object.freeze(['codex-collab', 'gemini-collab', 'ultra-verify']),
+  codex: Object.freeze(['cc-collab', 'gemini-collab', 'ultra-verify']),
+  opencode: Object.freeze(['cc-collab', 'codex-collab', 'gemini-collab', 'ultra-verify']),
+  gemini: Object.freeze(['cc-collab', 'codex-collab', 'ultra-verify']),
+});
+
+const RETIRED_SKILLS = Object.freeze([
+  'agent-browser',
+  'find-skills',
+  'recall',
+  'use-railway',
+  'vercel-composition-patterns',
+  'vercel-react-best-practices',
+  'vercel-react-native-skills',
+]);
+
+const WORKFLOW_HOOK_FILES = Object.freeze([
+  'active_task_context.py',
+  'health_check.py',
+  'pre_stop_check.py',
+  'subagent_tracker.py',
+  'workflow_checkpoint.py',
+  'workflow_context.py',
+  'workflow_resume.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];
+}
+
+module.exports = {
+  CORE_PUBLIC_SKILLS,
+  INTERNAL_AGENT_SKILLS,
+  COLLAB_SKILLS_BY_RUNTIME,
+  RETIRED_SKILLS,
+  WORKFLOW_HOOK_FILES,
+  skillsForRuntime,
+};

package/adapters/_shared/settings-merge.cjs

@@ -0,0 +1,76 @@
+'use strict';
+
+// Sentinel-block merge/remove for JSON settings files (D7).
+// Protects user-authored settings by confining our writes to a single
+// well-known key (the sentinel). Install writes/updates the sentinel value;
+// uninstall deletes it. Everything else in the JSON is left untouched.
+
+const SENTINEL_VERSION = 1;
+
+function readJsonSafe(filepath, { fs = require('node:fs'), rescue = false } = {}) {
+  if (!fs.existsSync(filepath)) return {};
+  const raw = fs.readFileSync(filepath, 'utf8').trim();
+  if (!raw) return {};
+  try { return JSON.parse(raw); }
+  catch (err) {
+    // rescue mode: back up the corrupt file and treat as empty so install
+    // can proceed instead of exploding mid-setup (P2 #7 from Phase 4 review).
+    // Callers that need strict semantics leave rescue=false (default).
+    if (rescue) {
+      const backup = `${filepath}.bak-${Date.now()}`;
+      try {
+        fs.copyFileSync(filepath, backup);
+        process.stderr.write(`settings-merge: corrupt ${filepath}; backed up to ${backup}, continuing with empty object\n`);
+      } catch (_backupErr) { /* best-effort */ }
+      return {};
+    }
+    throw new Error(`settings-merge: cannot parse ${filepath}: ${err.message}`);
+  }
+}
+
+function withSentinelBlock(existing, sentinelKey, block) {
+  if (!sentinelKey || typeof sentinelKey !== 'string') {
+    throw new TypeError('withSentinelBlock: sentinelKey must be non-empty string');
+  }
+  const next = { ...existing };
+  next[sentinelKey] = {
+    __sentinel: SENTINEL_VERSION,
+    __generated_by: 'ultra-builder-pro-cli',
+    __generated_at: new Date().toISOString(),
+    ...block,
+  };
+  return next;
+}
+
+function removeSentinelBlock(existing, sentinelKey) {
+  if (!(sentinelKey in existing)) return existing;
+  const next = { ...existing };
+  delete next[sentinelKey];
+  return next;
+}
+
+function hasSentinelBlock(existing, sentinelKey) {
+  return Boolean(existing && existing[sentinelKey] && existing[sentinelKey].__sentinel);
+}
+
+function mergeArrayField(existing, key, items) {
+  const current = Array.isArray(existing[key]) ? existing[key] : [];
+  const seen = new Set(current.map((x) => JSON.stringify(x)));
+  const appended = [...current];
+  for (const item of items) {
+    const tag = JSON.stringify(item);
+    if (seen.has(tag)) continue;
+    appended.push(item);
+    seen.add(tag);
+  }
+  return { ...existing, [key]: appended };
+}
+
+module.exports = {
+  SENTINEL_VERSION,
+  readJsonSafe,
+  withSentinelBlock,
+  removeSentinelBlock,
+  hasSentinelBlock,
+  mergeArrayField,
+};