ultra-builder-pro-cli 0.8.1 → 0.10.0

package/adapters/opencode.js

@@ -336,25 +336,26 @@ 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";
 
 const TERMINAL = new Set(["committed", "completed", "done", "cancelled"]);
 const TASKS_PROJECTION = ".ultra/tasks/tasks.json";
-const PROVIDER_FIELDS = new Set(["provider", "project", "reference", "revision", "indexed_head", "status"]);
-
-function providerMetadata(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
-  const clean = {};
-  for (const [kind, ref] of Object.entries(value)) {
-    if (!["memory", "code_graph"].includes(kind) || !ref || typeof ref !== "object" || Array.isArray(ref)) continue;
-    clean[kind] = Object.fromEntries(Object.entries(ref).filter(([key]) => PROVIDER_FIELDS.has(key)));
+
+function gitHead(root) {
+  try {
+    return execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
   }
-  return clean;
 }
 
 function findUltraContext(directory) {
   let current = path.resolve(directory);
   while (true) {
     const ultra = path.join(current, ".ultra");
+    const currentHead = gitHead(current);
     const workflowFile = path.join(ultra, "workflow-state.json");
     const statePresent = fs.existsSync(path.join(ultra, "state.db"));
     let workflow = null;
@@ -375,11 +376,36 @@ function findUltraContext(directory) {
         if (!fs.existsSync(manifestPath)) continue;
         try {
           const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
-          if (manifest?.change) changes.push({
-            ...manifest.change,
-            providers: providerMetadata(manifest.providers),
+          if (manifest?.change) {
+            const compiledHead = manifest.git?.head ?? null;
+            const legacyContext = manifest.schema_version !== "2.0";
+            const headStale = Boolean(compiledHead && currentHead && compiledHead !== currentHead);
+            const blockers = Array.isArray(manifest.readiness?.blockers)
+              ? [...manifest.readiness.blockers]
+              : [];
+            if (headStale && !blockers.includes("CONTEXT_HEAD_STALE")) blockers.push("CONTEXT_HEAD_STALE");
+            if (legacyContext && !blockers.includes("CONTEXT_SNAPSHOT_UPGRADE_REQUIRED")) {
+              blockers.unshift("CONTEXT_SNAPSHOT_UPGRADE_REQUIRED");
+            }
+            changes.push({
+            id: manifest.change.id,
+            kind: manifest.change.kind,
+            status: manifest.change.status,
+            role: manifest.role ?? "plan",
+            gate: manifest.gate ?? "alignment",
+            nextAction: legacyContext
+              ? "Recompile change.context to upgrade this legacy context snapshot."
+              : headStale
+              ? "Git HEAD changed after context compilation; recompile change.context."
+              : (manifest.next_action ?? "Inspect Ultra status."),
+            readiness: legacyContext || headStale ? "blocked" : (manifest.readiness?.status ?? "ready"),
+            blockers,
+            taskId: manifest.selected_task?.id ?? manifest.resume?.task_id ?? null,
+            taskStatus: manifest.selected_task?.status ?? manifest.resume?.task_status ?? null,
+            tokenEstimate: manifest.context?.token_estimate ?? 0,
             manifestPath: path.relative(current, manifestPath),
           });
+          }
         } catch (error) {
           process.stderr.write(\`[ultra-builder-pro] cannot read \${manifestPath}: \${error.message}\\n\`);
         }
@@ -410,13 +436,16 @@ function contextText(active) {
   if (active.changes.length > 0) {
     const change = active.changes[0];
     lines.push(
-      "[Ultra continuous change]",
+      "[Ultra context spine]",
       \`Project: \${active.root}\`,
       \`Change: \${change.id} (\${change.kind ?? "unknown"}, \${change.status ?? "active"})\`,
-      \`Title: \${change.title ?? "unknown"}\`,
-      \`Intent: \${change.intent ?? "unknown"}\`,
+      \`Task: \${change.taskId ?? "none"} (\${change.taskStatus ?? "none"})\`,
+      \`Role: \${change.role}\`,
+      \`Gate: \${change.gate}\`,
+      \`Readiness: \${change.readiness}\`,
+      ...(change.blockers.length > 0 ? [\`Blockers: \${change.blockers.join(", ")}\`] : []),
+      \`Next: \${change.nextAction}\`,
       \`Context manifest: \${change.manifestPath}\`,
-      \`External providers (metadata references only): \${JSON.stringify(change.providers)}\`,
     );
     if (active.changes.length > 1) lines.push(
       \`Active change count: \${active.changes.length}; resolve scope with change.list before mutation.\`,
@@ -429,7 +458,7 @@ function contextText(active) {
       "No active continuous change. Start daily work with the ultra-change workflow.",
     );
   }
-  lines.push("Authority: .ultra/state.db; generated JSON/Markdown are projections or artifacts.");
+  lines.push("Authority: .ultra/state.db; JSON/Markdown remain projections or evidence artifacts.");
   return lines.join("\\n");
 }
 

package/adapters/tests/claude.test.cjs

@@ -36,7 +36,10 @@ test('install builds the Claude-native plugin from the explicit Ultra allowlist'
 
     const hooks = JSON.parse(fs.readFileSync(path.join(target, 'hooks', 'hooks.json'), 'utf8'));
     const serialized = JSON.stringify(hooks);
-    for (const name of WORKFLOW_HOOK_FILES) assert.match(serialized, new RegExp(name.replace('.', '\\.')));
+    for (const name of WORKFLOW_HOOK_FILES.filter((value) => value !== 'context_spine.py')) {
+      assert.match(serialized, new RegExp(name.replace('.', '\\.')));
+    }
+    assert.ok(fs.existsSync(path.join(target, 'hooks', 'context_spine.py')));
     assert.doesNotMatch(serialized, /memory|recall|journal|observation_capture|user_prompt_capture|block_dangerous|post_edit_guard/);
     assert.match(serialized, /\$\{CLAUDE_PLUGIN_ROOT\}/);
   } finally {

package/adapters/tests/codex.test.cjs

@@ -198,9 +198,10 @@ test('plugin declares current Codex hooks and a project-local Ultra MCP server',
       'SubagentStart', 'SubagentStop',
     ].sort());
     const serializedHooks = JSON.stringify(hooks);
-    for (const feature of WORKFLOW_HOOK_FILES) {
+    for (const feature of WORKFLOW_HOOK_FILES.filter((value) => value !== 'context_spine.py')) {
       assert.match(serializedHooks, new RegExp(feature.replace('.', '\\.')));
     }
+    assert.ok(fs.existsSync(path.join(layout.pluginRoot, 'hooks', 'context_spine.py')));
     assert.doesNotMatch(serializedHooks, /memory|recall|journal|observation_capture|user_prompt_capture|block_dangerous|post_edit_guard/);
     assert.match(serializedHooks, /\$PLUGIN_ROOT\/hooks\/adapters\/codex\.py/);
     assert.match(serializedHooks, /apply_patch/);
@@ -231,8 +232,8 @@ test('plugin declares current Codex hooks and a project-local Ultra MCP server',
     const liveSpec = yaml.load(fs.readFileSync(path.join(layout.pluginRoot, 'spec', 'mcp-tools.yaml'), 'utf8'));
     const upstreamSpec = yaml.load(fs.readFileSync(path.join(layout.pluginRoot, 'spec', 'upstream-mcp-tools.yaml'), 'utf8'));
     const capabilityMap = JSON.parse(fs.readFileSync(path.join(layout.pluginRoot, 'spec', 'codex-capability-map.json'), 'utf8'));
-    assert.equal(liveSpec.tools.length, 29);
-    assert.equal(upstreamSpec.tools.length, 29);
+    assert.equal(liveSpec.tools.length, 32);
+    assert.equal(upstreamSpec.tools.length, 32);
     assert.deepEqual(upstreamSpec.tools.map((tool) => tool.name).sort(), liveSpec.tools.map((tool) => tool.name).sort());
     assert.deepEqual(capabilityMap.live_mcp_tools.sort(), liveSpec.tools.map((tool) => tool.name).sort());
     assert.equal(Object.keys(capabilityMap.codex_native_replacements).length, 9);

package/adapters/tests/kimi-hook.test.cjs

@@ -0,0 +1,122 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const ADAPTER = path.join(REPO_ROOT, 'hooks', 'adapters', 'kimi.py');
+
+function run(feature, payload, args = []) {
+  return spawnSync('python3', [ADAPTER, feature, ...args], {
+    cwd: REPO_ROOT,
+    input: JSON.stringify(payload),
+    encoding: 'utf8',
+  });
+}
+
+test('Kimi hook adapter rejects non-workflow policy hooks without blocking the host', () => {
+  const result = run('block_dangerous_commands.py', {
+    session_id: 'session-1',
+    cwd: REPO_ROOT,
+    hook_event_name: 'PreToolUse',
+    tool_name: 'Shell',
+    tool_input: { command: 'git reset --hard' },
+  });
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(JSON.parse(result.stdout).message, /refused unknown feature/);
+});
+
+test('Kimi hook adapter translates active edit context to the native message field', () => {
+  const project = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-kimi-hook-'));
+  try {
+    fs.mkdirSync(path.join(project, '.ultra'));
+    fs.writeFileSync(path.join(project, '.ultra', 'workflow-state.json'), JSON.stringify({
+      command: 'ultra-dev', task_id: 'task-7', step: '4.5', status: 'review_pending',
+    }));
+    const result = run('active_task_context.py', {
+      session_id: 'session-2',
+      cwd: project,
+      hook_event_name: 'PreToolUse',
+      tool_name: 'Edit',
+      tool_input: { file_path: 'src/a.py' },
+    });
+    assert.equal(result.status, 0, result.stderr);
+    const output = JSON.parse(result.stdout);
+    assert.match(output.message, /task-7/);
+    assert.equal(output.hookSpecificOutput, undefined);
+  } finally {
+    fs.rmSync(project, { recursive: true, force: true });
+  }
+});
+
+test('Kimi hook adapter emits the native deny contract for projection writes', () => {
+  const project = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-kimi-hook-deny-'));
+  try {
+    fs.mkdirSync(path.join(project, '.ultra'));
+    fs.writeFileSync(path.join(project, '.ultra', 'workflow-state.json'), JSON.stringify({
+      command: 'ultra-plan', task_id: 'plan', step: 'persist', status: 'active',
+    }));
+    const result = run('active_task_context.py', {
+      session_id: 'session-deny',
+      cwd: project,
+      hook_event_name: 'PreToolUse',
+      tool_name: 'Write',
+      tool_input: { file_path: '.ultra/tasks/tasks.json' },
+    });
+    assert.equal(result.status, 0, result.stderr);
+    const output = JSON.parse(result.stdout);
+    assert.equal(output.hookSpecificOutput.permissionDecision, 'deny');
+    assert.match(output.hookSpecificOutput.permissionDecisionReason, /\.ultra\/state\.db/);
+  } finally {
+    fs.rmSync(project, { recursive: true, force: true });
+  }
+});
+
+test('Kimi subagent fields are normalized for the existing lifecycle tracker', () => {
+  const script = [
+    'import importlib.util, json, pathlib',
+    `p = pathlib.Path(${JSON.stringify(ADAPTER)})`,
+    's = importlib.util.spec_from_file_location("kimi_hook_adapter", p)',
+    'm = importlib.util.module_from_spec(s)',
+    's.loader.exec_module(m)',
+    'payload = {"hook_event_name":"SubagentStart","agent_name":"review-code","session_id":"s"}',
+    'print(json.dumps(m.normalize_input(payload)))',
+  ].join('; ');
+  const result = spawnSync('python3', ['-c', script], { cwd: REPO_ROOT, encoding: 'utf8' });
+  assert.equal(result.status, 0, result.stderr);
+  assert.deepEqual(JSON.parse(result.stdout), {
+    hook_event_name: 'SubagentStart',
+    agent_name: 'review-code',
+    session_id: 's',
+    agent_id: 'review-code',
+    agent_type: 'review-code',
+  });
+});
+
+test('Kimi stop blocks and recovery context use the exact structured-output schema', () => {
+  const script = [
+    'import importlib.util, json, pathlib',
+    `p = pathlib.Path(${JSON.stringify(ADAPTER)})`,
+    's = importlib.util.spec_from_file_location("kimi_hook_adapter", p)',
+    'm = importlib.util.module_from_spec(s)',
+    's.loader.exec_module(m)',
+    'values = [m.adapt_output({"decision":"block","reason":"finish gates"}, "Stop"), m.adapt_output({"additionalContext":"restored"}, "PostCompact")]',
+    'print(json.dumps(values))',
+  ].join('; ');
+  const result = spawnSync('python3', ['-c', script], { cwd: REPO_ROOT, encoding: 'utf8' });
+  assert.equal(result.status, 0, result.stderr);
+  assert.deepEqual(JSON.parse(result.stdout), [
+    {
+      hookSpecificOutput: {
+        message: 'finish gates',
+        permissionDecision: 'deny',
+        permissionDecisionReason: 'finish gates',
+      },
+    },
+    { message: 'restored' },
+  ]);
+});

package/adapters/tests/kimi.test.cjs

@@ -0,0 +1,259 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const kimi = require('../kimi.js');
+const {
+  CORE_PUBLIC_SKILLS,
+  WORKFLOW_HOOK_FILES,
+  skillsForRuntime,
+} = require('../_shared/runtime-assets.cjs');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const PLUGIN_ID = 'ultra-builder-pro';
+
+function mkTarget() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-kimi-'));
+}
+
+function layout(home) {
+  return {
+    pluginRoot: path.join(home, 'plugins', 'managed', PLUGIN_ID),
+    registryFile: path.join(home, 'plugins', 'installed.json'),
+  };
+}
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+test('install builds and registers one Kimi-native plugin without changing config.toml', () => {
+  const home = mkTarget();
+  const { pluginRoot, registryFile } = layout(home);
+  const configFile = path.join(home, 'config.toml');
+  const userConfig = '[[hooks]]\nevent = "Stop"\ncommand = "/user/hook.sh"\n';
+  try {
+    fs.writeFileSync(configFile, userConfig);
+    const report = kimi.install({ configDir: home, repoRoot: REPO_ROOT });
+
+    assert.equal(report.target, pluginRoot);
+    assert.equal(fs.readFileSync(configFile, 'utf8'), userConfig);
+    assert.ok(fs.existsSync(path.join(pluginRoot, '.ubp-managed')));
+    assert.ok(fs.existsSync(path.join(pluginRoot, 'provenance.json')));
+
+    const registry = readJson(registryFile);
+    assert.equal(registry.version, 1);
+    assert.equal(registry.plugins.length, 1);
+    assert.deepEqual(registry.plugins[0], {
+      id: PLUGIN_ID,
+      root: pluginRoot,
+      source: 'local-path',
+      enabled: true,
+      installedAt: registry.plugins[0].installedAt,
+      updatedAt: registry.plugins[0].updatedAt,
+      originalSource: REPO_ROOT,
+    });
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('Kimi manifest exposes native skills, commands, hooks, session bootstrap, and MCP', () => {
+  const home = mkTarget();
+  const { pluginRoot } = layout(home);
+  try {
+    kimi.install({ configDir: home, repoRoot: REPO_ROOT });
+    const manifest = readJson(path.join(pluginRoot, 'kimi.plugin.json'));
+
+    assert.equal(manifest.name, PLUGIN_ID);
+    assert.deepEqual(manifest.skills, ['./skills']);
+    assert.deepEqual(manifest.commands, ['./commands']);
+    assert.deepEqual(manifest.sessionStart, { skill: 'using-ultra-builder-pro' });
+    assert.equal(manifest.agents, undefined, 'Kimi 0.26/0.27 has no custom-agent manifest field');
+    assert.deepEqual(manifest.mcpServers[PLUGIN_ID], {
+      transport: 'stdio',
+      command: process.platform === 'win32' ? 'node.exe' : 'env',
+      args: process.platform === 'win32'
+        ? ['./runtime/launch.cjs']
+        : ['node', './runtime/launch.cjs'],
+      enabled: true,
+    });
+
+    const hookText = JSON.stringify(manifest.hooks);
+    assert.match(hookText, /hooks\/adapters\/kimi\.py/);
+    for (const hook of WORKFLOW_HOOK_FILES.filter((value) => value !== 'context_spine.py')) {
+      assert.match(hookText, new RegExp(hook.replace('.', '\\.')));
+    }
+    assert.ok(fs.existsSync(path.join(pluginRoot, 'hooks', 'context_spine.py')));
+    assert.doesNotMatch(hookText, /memory|recall|journal|prompt[_ -]?capture|block_dangerous|post_edit_guard/i);
+
+    const commands = fs.readdirSync(path.join(pluginRoot, 'commands')).sort();
+    assert.deepEqual(commands, CORE_PUBLIC_SKILLS.map((name) => `${name}.md`).sort());
+    const commandText = fs.readFileSync(path.join(pluginRoot, 'commands', 'ultra-init.md'), 'utf8');
+    assert.match(commandText, /Use the registered `ultra-init` skill/);
+    assert.match(commandText, /\$ARGUMENTS/);
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('Kimi assets are allowlisted and adapted to native tools and paths', () => {
+  const home = mkTarget();
+  const { pluginRoot } = layout(home);
+  try {
+    kimi.install({ configDir: home, repoRoot: REPO_ROOT });
+
+    const skills = fs.readdirSync(path.join(pluginRoot, 'skills'), { withFileTypes: true })
+      .filter((entry) => entry.isDirectory()
+        && fs.existsSync(path.join(pluginRoot, 'skills', entry.name, 'SKILL.md')))
+      .map((entry) => entry.name)
+      .sort();
+    assert.deepEqual(skills, [...skillsForRuntime('kimi'), 'using-ultra-builder-pro'].sort());
+
+    const learn = fs.readFileSync(path.join(pluginRoot, 'skills', 'learn', 'SKILL.md'), 'utf8');
+    const review = fs.readFileSync(path.join(pluginRoot, 'skills', 'ultra-review', 'SKILL.md'), 'utf8');
+    const init = fs.readFileSync(path.join(pluginRoot, 'skills', 'ultra-init', 'SKILL.md'), 'utf8');
+    const bootstrap = fs.readFileSync(
+      path.join(pluginRoot, 'skills', 'using-ultra-builder-pro', 'SKILL.md'),
+      'utf8',
+    );
+    assert.match(learn, /~\/.kimi-code\/skills\/learned-<pattern-slug>-unverified\/SKILL\.md/);
+    assert.match(review, /Kimi `AgentSwarm`/);
+    assert.match(review, /Five engineering specialists/);
+    assert.match(review, /axes\.spec_fidelity/);
+    assert.doesNotMatch(review, /6 specialized|ALL 6/);
+    assert.match(review, /\$KIMI_PLUGIN_ROOT\/agents\/review-code\.md/);
+    assert.match(review, /`prompt_template` containing\s+`\{\{item\}\}`/);
+    assert.match(review, /selected reviewer names as the `items` array/);
+    assert.match(review, /Launch the coordinator with one foreground Kimi `Agent` call/);
+    assert.doesNotMatch(review, /background mode|Set Kimi `AgentSwarm` parallel execution|Launch review-coordinator with Kimi `AgentSwarm`/);
+    assert.match(init, /\| Kimi \| `\/ultra-builder-pro:ultra-init/);
+    assert.doesNotMatch(init, /codex exec "run \/ultra-init/);
+    assert.match(bootstrap, /\.ultra\/state\.db/);
+    assert.match(bootstrap, /external providers/);
+
+    const allPromptAssets = [];
+    for (const root of ['commands', 'skills', 'agents']) {
+      const pending = [path.join(pluginRoot, root)];
+      while (pending.length) {
+        const current = pending.pop();
+        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+          const file = path.join(current, entry.name);
+          if (entry.isDirectory()) pending.push(file);
+          else if (entry.isFile() && /\.(?:md|json)$/.test(entry.name)) allPromptAssets.push(file);
+        }
+      }
+    }
+    const foreign = /~\/.claude|~\/.codex|~\/.config\/opencode|CLAUDE\.md|TaskCreate|TaskUpdate|TaskList|AskUserQuestion|run_in_background:\s*true|\$CLAUDE_PLUGIN_ROOT|Kimi `Shell`/;
+    for (const file of allPromptAssets) {
+      const text = fs.readFileSync(file, 'utf8');
+      assert.doesNotMatch(text, foreign, file);
+      assert.doesNotMatch(text, /(^|[\s`("'])\/ultra-(?!builder-pro:)[a-z]/m, file);
+    }
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('reinstall preserves unrelated records and existing Kimi capability choices', () => {
+  const home = mkTarget();
+  const { registryFile } = layout(home);
+  try {
+    fs.mkdirSync(path.dirname(registryFile), { recursive: true });
+    fs.writeFileSync(registryFile, JSON.stringify({
+      version: 1,
+      plugins: [{
+        id: 'mine', root: '/tmp/mine', source: 'local-path', enabled: true,
+        installedAt: '2026-01-01T00:00:00.000Z', originalSource: '/tmp/mine',
+      }],
+    }, null, 2));
+
+    kimi.install({ configDir: home, repoRoot: REPO_ROOT });
+    const first = readJson(registryFile);
+    const ultra = first.plugins.find((entry) => entry.id === PLUGIN_ID);
+    ultra.enabled = false;
+    ultra.capabilities = { mcpServers: { [PLUGIN_ID]: { enabled: false } } };
+    fs.writeFileSync(registryFile, JSON.stringify(first, null, 2));
+
+    kimi.install({ configDir: home, repoRoot: REPO_ROOT });
+    const second = readJson(registryFile);
+    assert.deepEqual(second.plugins.map((entry) => entry.id).sort(), ['mine', PLUGIN_ID]);
+    const refreshed = second.plugins.find((entry) => entry.id === PLUGIN_ID);
+    assert.equal(refreshed.installedAt, ultra.installedAt);
+    assert.equal(refreshed.enabled, false);
+    assert.deepEqual(refreshed.capabilities, ultra.capabilities);
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('uninstall removes only the owned Kimi plugin record and managed root', () => {
+  const home = mkTarget();
+  const { pluginRoot, registryFile } = layout(home);
+  try {
+    kimi.install({ configDir: home, repoRoot: REPO_ROOT });
+    const registry = readJson(registryFile);
+    registry.plugins.unshift({
+      id: 'mine', root: '/tmp/mine', source: 'local-path', enabled: true,
+      installedAt: '2026-01-01T00:00:00.000Z', originalSource: '/tmp/mine',
+    });
+    fs.writeFileSync(registryFile, JSON.stringify(registry, null, 2));
+
+    kimi.uninstall({ configDir: home });
+    assert.equal(fs.existsSync(pluginRoot), false);
+    assert.deepEqual(readJson(registryFile).plugins.map((entry) => entry.id), ['mine']);
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('install and uninstall refuse to replace or remove an unmanaged Kimi root', () => {
+  const home = mkTarget();
+  const { pluginRoot, registryFile } = layout(home);
+  try {
+    fs.mkdirSync(pluginRoot, { recursive: true });
+    fs.writeFileSync(path.join(pluginRoot, 'user.txt'), 'keep');
+    assert.throws(
+      () => kimi.install({ configDir: home, repoRoot: REPO_ROOT }),
+      /unmanaged Kimi plugin/,
+    );
+
+    fs.mkdirSync(path.dirname(registryFile), { recursive: true });
+    fs.writeFileSync(registryFile, JSON.stringify({
+      version: 1,
+      plugins: [{
+        id: PLUGIN_ID, root: pluginRoot, source: 'local-path', enabled: true,
+        installedAt: '2026-01-01T00:00:00.000Z', originalSource: '/tmp/foreign',
+      }],
+    }));
+    assert.throws(() => kimi.uninstall({ configDir: home }), /unmanaged Kimi plugin/);
+    assert.equal(fs.readFileSync(path.join(pluginRoot, 'user.txt'), 'utf8'), 'keep');
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('doctor validates registration and provenance without mutating the Kimi home', () => {
+  const home = mkTarget();
+  const { registryFile } = layout(home);
+  try {
+    kimi.install({ configDir: home, repoRoot: REPO_ROOT });
+    const before = fs.readFileSync(registryFile);
+    const healthy = kimi.doctor({ configDir: home, repoRoot: REPO_ROOT });
+    assert.equal(healthy.status, 'healthy', JSON.stringify(healthy, null, 2));
+    assert.deepEqual(fs.readFileSync(registryFile), before);
+
+    const registry = readJson(registryFile);
+    registry.plugins[0].enabled = false;
+    fs.writeFileSync(registryFile, JSON.stringify(registry, null, 2));
+    const degraded = kimi.doctor({ configDir: home, repoRoot: REPO_ROOT });
+    assert.equal(degraded.status, 'degraded');
+    assert.ok(degraded.issues.some((issue) => issue.code === 'PLUGIN_REGISTRATION_INVALID'));
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});

package/adapters/tests/opencode.test.cjs

@@ -5,6 +5,7 @@ const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const { execFileSync } = require('node:child_process');
 const { pathToFileURL } = require('node:url');
 
 const opencode = require('../opencode.js');
@@ -172,7 +173,8 @@ test('install writes a schema-safe opencode.json and keeps ownership outside hos
     assert.match(plugin, /throw new Error/);
     assert.match(plugin, /session\.compacted/);
     assert.doesNotMatch(plugin, /memory\.(?:retain|recall|reflect)|journal|observation|prompt[_ -]?capture/);
-    assert.match(plugin, /metadata references only/);
+    assert.match(plugin, /Ultra context spine/);
+    assert.doesNotMatch(plugin, /providerMetadata|External providers/);
   } finally {
     fs.rmSync(target, { recursive: true, force: true });
   }
@@ -189,18 +191,59 @@ test('OpenCode context covers active changes and projection writes are blocked f
 
     fs.mkdirSync(path.join(project, '.ultra'), { recursive: true });
     fs.writeFileSync(path.join(project, '.ultra', 'state.db'), 'owned-by-ultra');
+    execFileSync('git', ['init'], { cwd: project, stdio: 'ignore' });
+    fs.writeFileSync(path.join(project, 'app.txt'), 'initial\n');
+    execFileSync('git', ['add', 'app.txt'], { cwd: project, stdio: 'ignore' });
+    execFileSync('git', ['-c', 'user.name=Ultra Tests', '-c', 'user.email=ultra@example.invalid', 'commit', '-m', 'initial'], {
+      cwd: project, stdio: 'ignore',
+    });
+    const compiledHead = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: project, encoding: 'utf8' }).trim();
     const changeRoot = path.join(project, '.ultra', 'changes', 'active', 'daily-fix');
     fs.mkdirSync(changeRoot, { recursive: true });
     fs.writeFileSync(path.join(changeRoot, 'context-manifest.json'), JSON.stringify({
+      schema_version: '2.0',
       change: { id: 'daily-fix', title: 'Daily fix', kind: 'quick', status: 'active', intent: 'Fix drift' },
+      role: 'implement',
+      gate: 'implementation',
+      next_action: 'Run the exact regression test.',
+      readiness: { status: 'ready', blockers: [] },
+      git: { head: compiledHead },
+      selected_task: { id: 'daily-task', status: 'in_progress' },
+      context: { token_estimate: 1200, budget: { max_tokens: 8000, max_files: 8 } },
       providers: { memory: { provider: 'cloud-mem', status: 'available' } },
     }));
 
     const output = { system: [] };
     await plugin['experimental.chat.system.transform']({}, output);
-    assert.match(output.system.join('\n'), /Ultra continuous change/);
+    assert.match(output.system.join('\n'), /Ultra context spine/);
     assert.match(output.system.join('\n'), /daily-fix/);
-    assert.match(output.system.join('\n'), /metadata references only/);
+    assert.match(output.system.join('\n'), /daily-task/);
+    assert.match(output.system.join('\n'), /Role: implement/);
+    assert.match(output.system.join('\n'), /Gate: implementation/);
+    assert.match(output.system.join('\n'), /Readiness: ready/);
+    assert.match(output.system.join('\n'), /Run the exact regression test/);
+    assert.doesNotMatch(output.system.join('\n'), /Fix drift|cloud-mem/);
+
+    const manifestFile = path.join(changeRoot, 'context-manifest.json');
+    const legacyManifest = JSON.parse(fs.readFileSync(manifestFile, 'utf8'));
+    legacyManifest.schema_version = '1.0';
+    fs.writeFileSync(manifestFile, JSON.stringify(legacyManifest));
+    const legacyOutput = { system: [] };
+    await plugin['experimental.chat.system.transform']({}, legacyOutput);
+    assert.match(legacyOutput.system.join('\n'), /CONTEXT_SNAPSHOT_UPGRADE_REQUIRED/);
+    legacyManifest.schema_version = '2.0';
+    fs.writeFileSync(manifestFile, JSON.stringify(legacyManifest));
+
+    fs.writeFileSync(path.join(project, 'app.txt'), 'changed\n');
+    execFileSync('git', ['add', 'app.txt'], { cwd: project, stdio: 'ignore' });
+    execFileSync('git', ['-c', 'user.name=Ultra Tests', '-c', 'user.email=ultra@example.invalid', 'commit', '-m', 'change'], {
+      cwd: project, stdio: 'ignore',
+    });
+    const staleOutput = { system: [] };
+    await plugin['experimental.chat.system.transform']({}, staleOutput);
+    assert.match(staleOutput.system.join('\n'), /Readiness: blocked/);
+    assert.match(staleOutput.system.join('\n'), /CONTEXT_HEAD_STALE/);
+    assert.match(staleOutput.system.join('\n'), /recompile change\.context/);
 
     await assert.rejects(
       plugin['tool.execute.before'](

package/bin/handbook.js

@@ -14,8 +14,8 @@ const {
 function usage() {
   return [
     'Usage:',
-    '  ubp-handbook preview --runtime <claude|codex|opencode> [--file <path>]',
-    '  ubp-handbook apply   --runtime <claude|codex|opencode> [--file <path>]',
+    '  ubp-handbook preview --runtime <claude|codex|opencode|kimi> [--file <path>]',
+    '  ubp-handbook apply   --runtime <claude|codex|opencode|kimi> [--file <path>]',
     '',
     'The apply command creates a timestamped backup before changing an existing file.',
   ].join('\n');