ultra-builder-pro-cli 0.7.0 → 0.9.0

package/bin/install.js

@@ -4,18 +4,20 @@
  * ultra-builder-pro-cli — multi-runtime installer.
  *
  * Distributes Ultra Builder Pro assets — commands, agents, skills, hooks,
- * MCP server — to Claude Code, OpenCode, and Codex CLI via
+ * MCP server — to Claude Code, OpenCode, Codex CLI, and Kimi Code via
  * runtime-specific adapters under adapters/. Install is idempotent and
  * uses atomic writes; uninstall reverses via sentinel/manifest blocks.
  *
  * Usage:
  *   npx ultra-builder-pro-cli [options]
  *
- *   --claude / --opencode / --codex              select runtime(s)
+ *   --claude / --opencode / --codex / --kimi     select runtime(s)
  *   --all                                         install to all supported runtimes
  *   -g, --global                                  install to runtime's global config dir
  *   -l, --local                                   install into current working directory
  *   -u, --uninstall                               remove installed assets
+ *   -d, --doctor                                  inspect installation provenance without mutation
+ *   --json                                        emit machine-readable doctor output
  *   -c, --config-dir <path>                       override config directory
  *   -h, --help                                    show help
  */
@@ -56,7 +58,7 @@ function printBanner() {
     paint('cyan', '   ╚═════╝ ╚═════╝ ╚═╝         ╚═════╝╚══════╝╚═╝'),
     '',
     `  ${paint('bold', 'Ultra Builder Pro CLI')} ${paint('dim', 'v' + pkg.version)}`,
-    `  ${paint('dim', 'Multi-runtime installer for Claude Code, OpenCode, and Codex')}`,
+    `  ${paint('dim', 'Multi-runtime installer for Claude Code, OpenCode, Codex, and Kimi Code')}`,
     '',
   ];
   console.log(banner.join('\n'));
@@ -69,6 +71,7 @@ function printHelp() {
     ${paint('cyan', '--claude')}           Claude Code
     ${paint('cyan', '--opencode')}         OpenCode
     ${paint('cyan', '--codex')}            Codex CLI (OpenAI)
+    ${paint('cyan', '--kimi')}             Kimi Code (Moonshot AI)
     ${paint('cyan', '--all')}              all supported runtimes
 
   ${paint('yellow', 'Scope:')}
@@ -77,6 +80,8 @@ function printHelp() {
 
   ${paint('yellow', 'Other:')}
     ${paint('cyan', '-u, --uninstall')}    remove installed assets
+    ${paint('cyan', '-d, --doctor')}       verify installed version, provenance, managed assets, and live entry points
+    ${paint('cyan', '--json')}             emit machine-readable doctor output (doctor only)
     ${paint('cyan', '-c, --config-dir')}   override runtime's config directory (string path)
     ${paint('cyan', '-h, --help')}         show this help
     ${paint('cyan', '-v, --version')}      show CLI version
@@ -90,6 +95,12 @@ function printHelp() {
 
     ${paint('dim', '# Uninstall from OpenCode')}
     npx ultra-builder-pro-cli --opencode --global --uninstall
+
+    ${paint('dim', '# Install to Kimi Code globally')}
+    npx ultra-builder-pro-cli --kimi --global
+
+    ${paint('dim', '# Verify all host installations without changing them')}
+    npx ultra-builder-pro-cli --all --global --doctor
 `);
 }
 
@@ -100,6 +111,8 @@ function parseArgs(argv) {
     global: false,
     local: false,
     uninstall: false,
+    doctor: false,
+    json: false,
     help: false,
     version: false,
     configDir: null,
@@ -111,12 +124,15 @@ function parseArgs(argv) {
       case '--claude': runtimes.add('claude'); break;
       case '--opencode': runtimes.add('opencode'); break;
       case '--codex': runtimes.add('codex'); break;
+      case '--kimi': runtimes.add('kimi'); break;
       case '--all':
         SUPPORTED_RUNTIMES.forEach(r => runtimes.add(r));
         break;
       case '-g': case '--global': flags.global = true; break;
       case '-l': case '--local': flags.local = true; break;
       case '-u': case '--uninstall': flags.uninstall = true; break;
+      case '-d': case '--doctor': flags.doctor = true; break;
+      case '--json': flags.json = true; break;
       case '-h': case '--help': flags.help = true; break;
       case '-v': case '--version': flags.version = true; break;
       case '-c': case '--config-dir':
@@ -178,30 +194,74 @@ async function main() {
     return;
   }
 
-  printBanner();
-
   if (flags.help) {
+    printBanner();
     printHelp();
     return;
   }
 
+  if (flags.doctor && flags.uninstall) bail('cannot combine --doctor and --uninstall');
+  if (flags.json && !flags.doctor) bail('--json is available only with --doctor');
+
   if (runtimes.length === 0) {
-    bail('no runtime selected; use --claude / --opencode / --codex / --all');
+    bail('no runtime selected; use --claude / --opencode / --codex / --kimi / --all');
   }
 
   const scope = resolveScope(flags);
   const repoRoot = path.resolve(__dirname, '..');
   const configDir = flags.configDir ? expandTilde(flags.configDir) : null;
 
-  const mode = flags.uninstall ? 'uninstall' : 'install';
-  console.log(`  ${paint('bold', 'Mode:')}     ${mode}`);
-  console.log(`  ${paint('bold', 'Scope:')}    ${scope}`);
-  console.log(`  ${paint('bold', 'Runtimes:')} ${runtimes.join(', ')}`);
-  if (configDir) console.log(`  ${paint('bold', 'ConfigDir:')} ${configDir}`);
-  console.log();
+  if (!flags.json) printBanner();
+
+  const mode = flags.doctor ? 'doctor' : flags.uninstall ? 'uninstall' : 'install';
+  if (!flags.json) {
+    console.log(`  ${paint('bold', 'Mode:')}     ${mode}`);
+    console.log(`  ${paint('bold', 'Scope:')}    ${scope}`);
+    console.log(`  ${paint('bold', 'Runtimes:')} ${runtimes.join(', ')}`);
+    if (configDir) console.log(`  ${paint('bold', 'ConfigDir:')} ${configDir}`);
+    console.log();
+  }
 
   const ctx = { repoRoot, scope, configDir, homeDir: os.homedir() };
 
+  if (flags.doctor) {
+    const reports = [];
+    for (const runtime of runtimes) {
+      const adapter = loadAdapter(runtime);
+      try {
+        if (typeof adapter.doctor !== 'function') throw new Error('adapter does not expose doctor()');
+        reports.push(await adapter.doctor(ctx));
+      } catch (error) {
+        reports.push({
+          adapter: runtime,
+          status: 'degraded',
+          manifest_path: null,
+          checks: {},
+          issues: [{ code: 'DOCTOR_FAILED', message: error.message }],
+        });
+      }
+    }
+    const output = {
+      status: reports.every((report) => report.status === 'healthy') ? 'healthy' : 'degraded',
+      reports,
+    };
+    if (flags.json) {
+      process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+    } else {
+      for (const report of reports) {
+        const color = report.status === 'healthy' ? 'green' : 'red';
+        console.log(`  ${paint(color, report.status === 'healthy' ? '✓' : '✗')} ${report.adapter}: ${report.status}`);
+        for (const finding of report.issues || []) {
+          const location = finding.path ? ` (${finding.path})` : '';
+          console.log(`      ${finding.code}${location}`);
+        }
+      }
+      console.log();
+    }
+    if (output.status !== 'healthy') process.exitCode = 2;
+    return;
+  }
+
   let failed = 0;
   for (const runtime of runtimes) {
     const adapter = loadAdapter(runtime);

package/bin/orchestrator.js

@@ -47,7 +47,7 @@ function optInAllowed(settings) {
 }
 
 function parseRuntimes() {
-  const raw = process.env.UBP_ORCH_RUNTIMES || 'claude,opencode,codex';
+  const raw = process.env.UBP_ORCH_RUNTIMES || 'claude,opencode,codex,kimi';
   const runtimes = [...new Set(raw.split(',').map((s) => s.trim()).filter(Boolean))];
   const invalid = runtimes.filter((runtime) => !isSupportedRuntime(runtime));
   if (invalid.length > 0) {

package/commands/ultra-change.md

@@ -28,8 +28,9 @@ mcp_tools_required:
 1. 先查 active/blocked change，匹配则恢复，避免重复创建。
 2. 按 `quick / standard / major / incident` 分类并声明 docs impact。
 3. 调 `change.create`，为 change 创建至少一个带 `change_id` 的 task。
-4. standard/major 写 delta + plan；调 `change.context` 编译最小上下文。
-5. 路由到 `/ultra-dev`、`/ultra-test`、`/ultra-review`、`/ultra-deliver`。
+4. standard/major 写 delta + plan；incident 完成结构化 `diagnosis.md`。
+5. 调 `change.context` 编译最小上下文；incident 先走 debugger 诊断切片。
+6. 路由到 `/ultra-dev`、`/ultra-test`、`/ultra-review`、`/ultra-deliver`。
 
 Memory 与代码图谱只允许以外部 provider 元数据引用出现；本命令不保存 provider
 正文，也不自动刷新外部 provider。

package/docs/AGENT-CONTEXT.md

@@ -1,7 +1,7 @@
 # Ultra Builder Pro — Agent Context
 
-Current shared runtime contract for the native Claude Code, OpenCode, and Codex
-plugins.
+Current shared runtime contract for the native Claude Code, OpenCode, Codex,
+and Kimi Code plugins.
 
 ## 1. Ownership boundary
 
@@ -12,7 +12,8 @@ Ultra Builder Pro owns only:
   `ultra-think`, plus the daily `ultra-change` and diagnostic `ultra-doctor`;
 - four internal agent-only rule skills: `code-review-expert`, `security-rules`,
   `integration-rules`, and `testing-rules`;
-- the host-specific collaboration companions and `ultra-verify`;
+- the host-specific collaboration companions, `ultra-verify`, and the minimal
+  Kimi session bootstrap required to establish the shared runtime boundary;
 - bounded review/debug agents, workflow-only hooks, MCP task state, and the
   portable CLI/orchestrator.
 
@@ -68,6 +69,7 @@ fixtures. Do not add an ad-hoc server handler first.
 | Claude Code | `.claude-plugin/plugin.json`, native commands/skills/agents, `.mcp.json` | `/ultra-*`, `/learn` | native `hooks/hooks.json` | `codex-collab`, `ultra-verify` |
 | Codex | personal plugin with `.codex-plugin/plugin.json`, namespaced skills, TOML agents, `.mcp.json` | `$ultra-builder-pro:ultra-*`, `$ultra-builder-pro:learn` | native `hooks/hooks.json` through the Codex wire adapter | `cc-collab`, `ultra-verify` |
 | OpenCode | config bundle plus native JavaScript plugin | `/ultra-*`, `/learn` | `event`, system transform, compaction, and tool lifecycle handlers | `cc-collab`, `codex-collab`, `ultra-verify` |
+| Kimi Code 0.26+ | managed `kimi.plugin.json` plugin with commands, skills, hooks, and MCP | `/ultra-builder-pro:ultra-*`, `/ultra-builder-pro:learn` | native hooks through the Kimi wire adapter | `cc-collab`, `codex-collab`, `ultra-verify` |
 
 The current host remains primary. Collaboration skills call another runtime
 only when explicitly requested, use it as a read-only advisor, and return the

package/docs/ARCHITECTURE.md

@@ -10,7 +10,7 @@
 
 `ultra-builder-pro-cli` is a multi-runtime plugin suite that **distributes** the
 Ultra Builder Pro engineering loop (skills + commands + workflow hooks) as
-native Claude Code, OpenCode, and Codex plugins, and
+native Claude Code, OpenCode, Codex, and Kimi Code plugins, and
 **runs** that loop with isolated sessions sharing one authoritative state
 store (`.ultra/state.db`).
 
@@ -23,7 +23,7 @@ the supported hosts share.
                        ┌──────────────────────────┐
                        │       runtime CLI        │
                        │  (claude / opencode /    │
-                       │   codex)                 │
+                       │   codex / kimi)          │
                        └────────────┬─────────────┘
                                     │
                 ┌───────────────────┼────────────────────┐
@@ -141,6 +141,14 @@ but all require completed linked tasks, current context, declared documentation
 impact, and no open incident. Memory and graph payloads never enter Ultra;
 `context_snapshots.provider_refs_json` stores metadata references only.
 
+`incident` is the canonical debug lane. Creating one also registers a durable
+`diagnosis.md` artifact with five mandatory sections: reproduction, hypotheses,
+root cause, regression test, and recovery. Convergence validates the artifact
+structure and refreshes its content hash, so a debugger result that exists only
+in chat cannot satisfy delivery. A host-native debugger may produce the bounded
+analysis, but the primary agent owns the artifact, linked task, regression
+evidence, and final convergence decision.
+
 Mutating MCP calls enqueue durable `projection_jobs`. Success is exposed in MCP
 response metadata; failure becomes a retryable structured incident instead of a
 swallowed warning. `system.doctor` is read-only by default and performs only
@@ -148,7 +156,7 @@ backup-first mechanical recovery when explicitly requested.
 
 ## 5. Sessions — the execution unit
 
-A **session** is the standard unit of execution across all three runtimes
+A **session** is the standard unit of execution across all four runtimes
 (D20). One session =
 
 - a fresh OS process for the runtime,
@@ -168,7 +176,33 @@ This admission gate is the smallest piece that prevents two agents from
 silently double-writing the same task — it is part of the v0.1 minimum
 execution layer, not deferred to Phase 5.
 
-## 6. Two timelines — rule layer vs execution layer
+## 6. Compaction recovery — checkpoint as a validated consumer
+
+`workflow_checkpoint.py` validates the current non-terminal workflow and writes
+a schema-versioned checkpoint atomically before compaction. On resume,
+`workflow_resume.py` reads both the live workflow and checkpoint defensively,
+rejects corrupt, non-object, schema-mismatched, or terminal candidates, and
+selects the newest valid state. A newer live state wins; a newer checkpoint can
+atomically restore a missing or older live state before context is re-injected.
+The checkpoint is therefore a recovery artifact and consumer, never a second
+durable authority alongside `.ultra/state.db`.
+
+## 7. Installation provenance — read-only cross-host diagnosis
+
+Every Claude Code, OpenCode, Codex, and Kimi Code adapter writes a normalized
+`provenance.json` for the assets it owns. The manifest records adapter/package
+identity, source metadata, per-file SHA-256 hashes, an aggregate digest, and the
+host-specific plugin, MCP, hook, launcher, and runtime contracts expected at
+that install scope. It never attributes a package to an enclosing consumer
+repository commit.
+
+`ubp --doctor [--json]` is read-only: it recomputes hashes and validates those
+entry points, returning a non-zero degraded result for missing/corrupt
+provenance, content drift, or broken host wiring. This is separate from
+`system.doctor`, which diagnoses project state, projection, incidents, sessions,
+and backup-first workflow recovery.
+
+## 8. Two timelines — rule layer vs execution layer
 
 The roadmap separates two concerns that compete for the same surface
 area (D13):
@@ -196,7 +230,7 @@ value from "skills + tasks survive across sessions" long before they get
 value from "ten agents in parallel." Each milestone is independently
 shippable; downstream slip never blocks an earlier release.
 
-## 7. Where to look next
+## 9. Where to look next
 
 | Question                                           | File                                                |
 |----------------------------------------------------|-----------------------------------------------------|
@@ -206,7 +240,7 @@ shippable; downstream slip never blocks an earlier release.
 | What does a tasks.json look like after projection? | [`spec/fixtures/valid/tasks.v4.5.json`](../spec/fixtures/valid/tasks.v4.5.json) |
 | Phase-by-phase work breakdown + decision log       | [`docs/PLAN.zh-CN.md`](./PLAN.zh-CN.md)             |
 
-## 8. Verifying the architecture
+## 10. Verifying the architecture
 
 Every contract on this page is enforced by `npm run test:spec`:
 

package/docs/PLAN.zh-CN.md

@@ -1,17 +1,18 @@
 # ultra-builder-pro-cli — 历史执行计划与决策日志
 
-> **2026-07-17 当前生效边界（D50-D52，覆盖下文旧 Phase 6/7 的内置图谱、memory 与 runtime 设计）**：
+> **2026-07-17 当前生效边界（D50-D53，覆盖下文旧 Phase 6/7 的内置图谱、memory 与 runtime 设计）**：
 > Ultra Builder Pro 不再拥有 `memory.*`、recall、prompt/transcript/observation/summary
 > 收集 hook 或私有 agent memory。跨会话记忆全部交给独立安装的 cloud-mem/claude-mem。
 > 插件只保留 12 个 Ultra 公共 workflow（新增 daily `ultra-change` 与诊断
 > `ultra-doctor`）、4 个 agent-only 规则 skill、宿主专属 collab companion、
 > workflow/change hook 与 `.ultra/state.db` 权威。Memory 和代码图谱内容全部由外部
-> provider 所有，Ultra 只保存 provider 元数据引用。Claude Code、Codex、OpenCode
-> 采用各自 native plugin 呈现，其他旧 runtime adapter 已退役。下文所有与此冲突的
+> provider 所有，Ultra 只保存 provider 元数据引用。Claude Code、Codex、OpenCode、
+> Kimi Code 采用各自 native plugin 呈现，其他旧 runtime adapter 已退役。下文所有与此冲突的
 > memory/hindsight 章节仅作为历史实施记录，不再是当前需求或运行时契约。
 
-**当前状态**：v0.7.0 发布候选；三宿主 native plugin、29 个 live MCP tool、
-schema 9.0（15 表）、持续 change/context/convergence/doctor 已落地；npm 发布由
+**当前状态**：v0.9.0；四宿主 native plugin、29 个 live MCP tool、
+schema 9.1（15 表）、持续 change/context/convergence/doctor、incident debug lane、
+checkpoint 恢复消费与跨宿主安装 provenance/doctor 已落地；npm 发布由
 `v*.*.*` tag 触发。以下 Phase 0-9 正文保留为 2026-04 的实施历史，不再作为
 当前 runtime 或发布状态的事实来源。
 **历史版本**：0.3.1-plan · 2026-04-17 Codex 第二轮评审收尾
@@ -27,7 +28,7 @@ schema 9.0（15 表）、持续 change/context/convergence/doctor 已落地；np
 - **Phase 4.6 拆 a/b**（R6 + D35）：v0.1 只跑 smoke flow，full conformance 推 v0.2
 - **Codex 第二轮结论**："小改后开工"（tl;dr）；本版已完成小改
 
-**总决策数**：D1-D52（当前边界以 D50-D52 为准）
+**总决策数**：D1-D53（当前边界以 D50-D53 为准）
 **总风险数**：R1-R32（v0.3.1 新增 R25-R32 共 8 条）
 
 ---
@@ -1639,6 +1640,7 @@ Week 18      buffer（ship 中任何 Phase 的 25% 滑动吃掉）
 | **D50** | **2026-07-15** | **重划插件与记忆边界**：Claude Code、Codex、OpenCode 改为各自 native plugin；只打包 10 个 Ultra 公共 workflow、4 个 agent-only 规则 skill 与宿主专属 collab companion；删除 6 个外部 skill、recall、Impeccable 残留、Ultra memory MCP/store/wrapper/capture hooks；持久记忆由独立 cloud-mem/claude-mem 负责；用户 handbook 通过可预览、可备份的 managed block 显式同步 | 用户确认最终方案；运行时 allowlist、conformance、hook 与 handbook 回归测试共同锁定边界 |
 | **D51** | **2026-07-17** | **runtime 收敛为 Claude Code、OpenCode、Codex**：删除第四 runtime 的 adapter、安装参数、collab skill、prompt、schema、pricing、调度与测试面；`ultra-verify` 改为当前宿主主责加单一只读外部顾问 | 用户确认不再需要第四 runtime；0.6.0 退役契约阻止其重新进入活跃源码或发布包 |
 | **D52** | **2026-07-17** | **初始交付后进入持续变更闭环**：新增 `ultra-change` / `ultra-doctor`、change/context/artifact/trace/incident/projection/consumer 状态、delta-first spec、确定性 convergence 与 baseline reconciliation；删除内置 code-graph watcher 和通用命令代理，Memory/图谱只保留外部 provider 元数据引用 | 用户确认采用最佳组合落地；解决日常小改导致 spec/context 漂移、投影失败静默和异常无恢复证据的问题 |
+| **D53** | **2026-07-17** | **Harness 缺口一次性闭环**：`incident` 成为带五段 `diagnosis.md` 结构门禁的 canonical debug lane；compact checkpoint 由 resume 消费、校验、择新并原子恢复；三宿主安装写 normalized provenance，`ubp --doctor` 只读校验 asset hash 与 plugin/hook/MCP/runtime contract | 将 GSD 的 debug/fresh context、GStack 的 checkpoint/readiness 与 ECC 的 doctor/provenance 思路收敛为 Ultra 自有契约；Memory 与图谱继续由外部 provider 所有，且不恢复任何已退役 surface |
 
 ---
 

package/docs/ROADMAP.md

@@ -6,14 +6,14 @@
 > when historical plan text differs.
 
 **Goal**: distribute the Ultra Builder Pro engineering loop as native Claude
-Code, OpenCode, and Codex plugins, and run it with isolated sessions sharing one
-authoritative workflow store.
+Code, OpenCode, Codex, and Kimi Code plugins, and run it with isolated sessions
+sharing one authoritative workflow store.
 
-**First-class runtimes**: Claude Code · OpenCode · Codex.
+**First-class runtimes**: Claude Code · OpenCode · Codex · Kimi Code.
 
 **Distribution channels (v1.0)**: npm · Homebrew · pip.
 
-**Release line**: `0.7.x`; every release is gated by `npm run verify:release`.
+**Release line**: `0.9.x`; every release is gated by `npm run verify:release`.
 
 ---
 

package/docs/RUNTIME-COMPAT-MATRIX.md

@@ -1,99 +1,150 @@
 # Runtime Compatibility Matrix
 
-Current presentation contract for Ultra Builder Pro. Claude Code, OpenCode, and
-Codex are the supported native plugin hosts. The canonical asset boundary lives
-in `adapters/_shared/runtime-assets.cjs`.
+Current presentation contract for Ultra Builder Pro. Claude Code, OpenCode,
+Codex, and Kimi Code 0.26+ are supported native plugin hosts. The canonical
+asset boundary lives in `adapters/_shared/runtime-assets.cjs`.
 
-Legend: **FULL** = native host surface, **DEGRADED** = supported but missing an
-equivalent lifecycle/control surface, **N/A** = intentionally not installed.
+Legend: **FULL** = native host surface, **FUNCTIONAL** = the complete outcome is
+available through a different native host primitive, **DEGRADED** = supported
+but missing an equivalent lifecycle/control surface, **N/A** = intentionally
+not installed.
 
 ## 1. Plugin and workflow surface
 
-| Capability | Claude Code | OpenCode | Codex |
-|---|---|---|---|
-| Package form | `.claude-plugin` native plugin | native config bundle + JS plugin | personal `.codex-plugin` |
-| Public entry | `/ultra-*`, `/learn` | `/ultra-*`, `/learn` | `$ultra-builder-pro:<skill>` |
-| Public Ultra workflows | 12 | 12 | 12 |
-| Internal agent-rule skills | 4, non-user-facing | 4, non-user-facing | 4 with implicit invocation disabled |
-| Collaboration companions | `codex-collab`, `ultra-verify` | `cc-collab`, `codex-collab`, `ultra-verify` | `cc-collab`, `ultra-verify` |
-| External browser/deploy/framework skills | N/A | N/A | N/A |
-
-Codex converts the workflows into namespaced skills and records eleven legacy
+| Capability | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
+|---|---|---|---|---|
+| Package form | `.claude-plugin` native plugin | native config bundle + JS plugin | personal `.codex-plugin` | managed `kimi.plugin.json` plugin |
+| Public entry | `/ultra-*`, `/learn` | `/ultra-*`, `/learn` | `$ultra-builder-pro:<skill>` | `/ultra-builder-pro:<command>` |
+| Public Ultra workflows | 12 | 12 | 12 | 12 |
+| Internal agent-rule skills | 4, non-user-facing | 4, non-user-facing | 4 with implicit invocation disabled | 4, consumed by review workers |
+| Collaboration companions | `codex-collab`, `ultra-verify` | `cc-collab`, `codex-collab`, `ultra-verify` | `cc-collab`, `ultra-verify` | `cc-collab`, `codex-collab`, `ultra-verify` |
+| Host bootstrap | native plugin context | native plugin context | native plugin context | `using-ultra-builder-pro` session-start skill |
+| External browser/deploy/framework skills | N/A | N/A | N/A | N/A |
+
+Codex converts workflows into namespaced skills and records eleven legacy
 command mappings in `command-map.json`; `ultra-review` remains directly
-invocable as a skill.
+invocable as a skill. Kimi registers all twelve commands through its native
+plugin command directory and exposes the allowlisted skills independently.
 
 ## 2. Agents and collaboration
 
-| Capability | Claude Code | OpenCode | Codex |
-|---|---|---|---|
-| Bundled review/debug agents | FULL, native Markdown agents | FULL, native agent frontmatter | FULL, nine managed TOML custom agents |
-| Native bounded delegation | native agent surface | native agent surface | native Codex subagents |
-| Cross-host advisor | explicit and read-only | explicit and read-only | explicit and read-only |
-| Primary-agent ownership | FULL | FULL | FULL |
+| Capability | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
+|---|---|---|---|---|
+| Bundled review/debug workers | FULL, native Markdown agents | FULL, native agent frontmatter | FULL, nine managed TOML agents | FUNCTIONAL, nine prompt templates consumed by `Agent` / `AgentSwarm` |
+| Plugin custom-agent registration | FULL | FULL | FULL | N/A; the 0.26 manifest has no custom-agent field |
+| Native bounded delegation | native agent surface | native agent surface | native Codex subagents | native `Agent` / `AgentSwarm` |
+| Cross-host advisor | explicit and read-only | explicit and read-only | explicit and read-only | explicit and read-only |
+| Primary-agent ownership | FULL | FULL | FULL | FULL |
 
-No bundled agent owns private persistent memory. It receives current-checkout
+No bundled worker owns private persistent memory. It receives current-checkout
 evidence and bounded context from the primary host, then returns a result for
-primary verification.
+primary verification. On Kimi, the review workflow reads the bundled worker
+template before creating the corresponding `AgentSwarm` item; the templates are
+not presented as nonexistent custom agents.
 
 ## 3. Workflow hooks
 
-| Lifecycle | Claude Code | OpenCode | Codex |
-|---|---|---|---|
-| Session context/health | FULL, native `SessionStart` | DEGRADED, native context; health via `system.doctor` | FULL, native `SessionStart` |
-| Active edit boundary | FULL, `PreToolUse Edit|Write` | FULL, `tool.execute.before` rejects projection writes | FULL, `PreToolUse Edit|Write|apply_patch` |
-| Compaction recovery | FULL, `PreCompact` + resume matcher | FULL, native compacting context | FULL, `PreCompact` + `PostCompact` |
-| Incomplete-stop gate | FULL, native blocking `Stop` | DEGRADED, no equivalent blocking stop hook | FULL, native blocking `Stop` |
-| Subagent lifecycle evidence | FULL | DEGRADED, no equivalent packaged event | FULL |
+| Lifecycle | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
+|---|---|---|---|---|
+| Session context/health | FULL, native `SessionStart` | DEGRADED, native context; health via `system.doctor` | FULL, native `SessionStart` | FULL, session-start skill + `SessionStart` hooks |
+| Active edit boundary | FULL, `PreToolUse Edit|Write` | FULL, `tool.execute.before` rejects projection writes | FULL, `PreToolUse Edit|Write|apply_patch` | FULL, native `PreToolUse Edit|Write` deny contract |
+| Pre-compact checkpoint | FULL | FULL | FULL | FULL, native `PreCompact` |
+| Post-compact context injection | FULL | FULL, native compacting context | FULL, native `PostCompact` restore | DEGRADED; checkpoint restoration runs, but Kimi 0.26/0.27 does not reinject fire-and-forget hook text |
+| Incomplete-stop gate | FULL, native blocking `Stop` | DEGRADED, no equivalent blocking stop hook | FULL, native blocking `Stop` | FULL, native structured deny |
+| Subagent lifecycle evidence | FULL | DEGRADED, no equivalent packaged event | FULL | FULL, native `SubagentStart` / `SubagentStop` |
+
+Kimi's session bootstrap therefore also instructs recovery to inspect
+`.ultra/runtime/checkpoint.json` and call Ultra status/doctor after compaction.
+This keeps durable recovery intact without claiming dynamic context injection
+that the host does not guarantee.
 
 Health/context hooks inspect initialized projects; projection protection also
-applies at baseline, while compact/stop/subagent enforcement remains active-workflow scoped.
-No host receives prompt capture, transcript
-capture, observation journaling, session-summary memory, generic command
-blocking, or generic post-edit policy.
+applies at baseline, while compact/stop/subagent enforcement remains
+active-workflow scoped. No host receives prompt capture, transcript capture,
+observation journaling, session-summary memory, generic command blocking, or
+generic post-edit policy.
 
 ## 4. MCP and state
 
-| Capability | Claude Code | OpenCode | Codex |
-|---|---|---|---|
-| stdio MCP registration | plugin `.mcp.json` | `opencode.json` local MCP entry | plugin `.mcp.json` |
-| Live/declared contracts | 29 | 29 | 29 |
-| Host-native review/discovery/ask | native | native | documented in `codex-capability-map.json` |
-| Durable authority | project `.ultra/state.db` | project `.ultra/state.db` | project `.ultra/state.db` |
-| Ultra memory API | N/A | N/A | N/A |
+| Capability | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
+|---|---|---|---|---|
+| stdio MCP registration | plugin `.mcp.json` | `opencode.json` local MCP entry | plugin `.mcp.json` | plugin `mcpServers` entry |
+| Live/declared contracts | 29 | 29 | 29 | 29 |
+| Host-native review/discovery/ask | native | native | documented in `codex-capability-map.json` | native Kimi tools and workers |
+| Durable authority | project `.ultra/state.db` | project `.ultra/state.db` | project `.ultra/state.db` | project `.ultra/state.db` |
+| Ultra memory API | N/A | N/A | N/A | N/A |
 
 All 29 `task.*`, `session.*`, `change.*`, `system.*`, and `plan.*` operations
 registered by `mcp-server/server.cjs` are live. Review, impact discovery, skill
 loading, and user interaction remain host-native surfaces.
 
+Kimi starts plugin MCP processes with the managed plugin root as `cwd`. The
+generated launcher recovers the project from the inherited `PWD`, sets
+`UBP_ROOT_DIR` and `UBP_DB_PATH`, and refuses to start if that project boundary
+cannot be established. On POSIX it intentionally uses `env node` because Kimi
+0.26/0.27's embedded Node ABI differs from the ABI used to install `better-sqlite3`.
+
 ## 5. User handbook presentation
 
-| Capability | Claude Code | OpenCode | Codex |
-|---|---|---|---|
-| Durable user file | `~/.claude/CLAUDE.md` | `~/.config/opencode/AGENTS.md` | `~/.codex/AGENTS.md` |
-| Automatic overwrite by plugin install | no | no | no |
-| Explicit managed-block sync | `ubp-handbook --runtime claude` | `ubp-handbook --runtime opencode` | `ubp-handbook --runtime codex` |
-| Backup before change | FULL | FULL | FULL |
+| Capability | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
+|---|---|---|---|---|
+| Durable user file | `~/.claude/CLAUDE.md` | `~/.config/opencode/AGENTS.md` | `~/.codex/AGENTS.md` | `~/.kimi-code/AGENTS.md` |
+| Automatic overwrite by plugin install | no | no | no | no |
+| Explicit managed-block sync | `ubp-handbook --runtime claude` | `ubp-handbook --runtime opencode` | `ubp-handbook --runtime codex` | `ubp-handbook --runtime kimi` |
+| Backup before change | FULL | FULL | FULL | FULL |
 
-## 6. Install, update, and uninstall
+The Kimi plugin installer does not edit `~/.kimi-code/config.toml`. Handbook
+sync remains a separate, previewable action so user policy and plugin mechanics
+do not become one irreversible mutation.
 
-| Capability | Claude Code | OpenCode | Codex |
-|---|---|---|---|
-| Adapter install | FULL | FULL | FULL |
-| Native update | next host session | host restart | cachebuster + `codex plugin add`, then new task |
-| Removes stale managed assets | FULL | FULL | FULL |
-| Preserves unrelated config | FULL | FULL | FULL |
-| Uninstall ownership guard | managed plugin root | sentinels + owned MCP entry | managed root/manifest/agent headers |
+## 6. Install, update, and uninstall
 
-## 7. Verification sources
+| Capability | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
+|---|---|---|---|---|
+| Adapter install | FULL | FULL | FULL | FULL |
+| Global install command | `ubp --claude --global` | `ubp --opencode --global` | `ubp --codex --global` | `ubp --kimi --global` |
+| Native update visibility | next host session | host restart | cachebuster + new task | `/reload` or new session |
+| Removes stale managed assets | FULL | FULL | FULL | FULL |
+| Preserves unrelated config | FULL | FULL | FULL | FULL, including `config.toml` and unrelated registry records |
+| Uninstall ownership guard | managed plugin root | sentinels + owned MCP entry | managed root/manifest/agent headers | managed root + exact registry record |
+| Normalized install provenance | FULL | FULL | FULL | FULL |
+| Read-only `ubp --doctor` | FULL | FULL | FULL | FULL |
+| Asset-content and host-contract drift detection | FULL | FULL | FULL | FULL |
+
+Kimi's global managed root is
+`~/.kimi-code/plugins/managed/ultra-builder-pro`; its only registry mutation is
+the owned `ultra-builder-pro` entry in `~/.kimi-code/plugins/installed.json`.
+Reinstall preserves the user's enabled/capability choices and unrelated plugin
+records. Uninstall refuses an unmanaged or conflicting root.
+
+## 7. Durable schema compatibility
+
+| Capability | Contract |
+|---|---|
+| Current state schema | `9.1` |
+| Runtime values | `claude`, `opencode`, `codex`, `kimi` |
+| Upgrade from pre-Kimi schema | transactionally rebuilds only constrained `events` and `sessions` tables |
+| Preservation gate | rows, IDs, indexes, foreign keys, telemetry, incidents, and migration history remain intact |
+| Failure behavior | rollback; no partially upgraded authority database |
+
+## 8. Verification sources
 
 - `adapters/tests/*.test.cjs` verifies each installer and native manifest.
 - `tests/conformance/<runtime>/*.test.cjs` verifies command/skill, hook, MCP,
-  idempotency, and smoke presentation.
+  idempotency, and smoke presentation for all four hosts.
+- `tests/conformance/kimi/smoke.test.cjs` reproduces Kimi's plugin-root MCP
+  `cwd` and proves that the first state write lands in the active project.
 - `adapters/_shared/tests/runtime-assets.test.cjs` prevents retired or external
   skills and generic/memory hooks from re-entering a package.
 - `tests/retired-runtime.test.cjs` prevents retired runtime code or prompt text
   from re-entering active product surfaces.
 - `adapters/_shared/tests/handbook.test.cjs` verifies host rendering, backup,
   migration, and idempotency.
+- `adapters/_shared/tests/provenance.test.cjs` verifies normalized manifests,
+  content hashes, source attribution, corruption handling, and contract drift.
+- `tests/install.test.cjs` verifies healthy four-host doctor output and
+  host-specific hook/MCP degradation after controlled tampering.
+- `tests/package-smoke.test.cjs` installs the packed tarball into a clean
+  consumer and executes a live MCP round trip through every generated launcher.
 
 Any capability claim elsewhere must match current adapter code and these tests.

package/docs/USER-HANDBOOK-CONTRACT.md

@@ -15,8 +15,9 @@ syntax:
 | Claude Code | `~/.claude/CLAUDE.md` | `/ultra-plan` |
 | Codex | `~/.codex/AGENTS.md` | `$ultra-builder-pro:ultra-plan` |
 | OpenCode | `~/.config/opencode/AGENTS.md` | `/ultra-plan` |
+| Kimi Code | `~/.kimi-code/AGENTS.md` | `/ultra-builder-pro:ultra-plan` |
 
-The renderer never copies Claude Code-only APIs into Codex or OpenCode. Each
+The renderer never copies Claude Code-only APIs into Codex, OpenCode, or Kimi. Each
 host receives only its native invocation and collaboration names.
 
 ## Managed-block contract
@@ -42,6 +43,7 @@ Preview the full merged result before applying:
 ubp-handbook preview --runtime claude
 ubp-handbook preview --runtime codex
 ubp-handbook preview --runtime opencode
+ubp-handbook preview --runtime kimi
 ```
 
 Apply when the preview is correct:
@@ -50,6 +52,7 @@ Apply when the preview is correct:
 ubp-handbook apply --runtime claude
 ubp-handbook apply --runtime codex
 ubp-handbook apply --runtime opencode
+ubp-handbook apply --runtime kimi
 ```
 
 An existing target is copied to

package/hooks/README.md

@@ -9,8 +9,8 @@ bounded to the relevant Ultra projection or a non-terminal workflow.
 | Session start | `health_check.py` | Read-only integrity, incident, projection, session, and change-artifact checks |
 | Session start | `workflow_context.py` | Inject baseline/active workflow/change context and filtered provider metadata references |
 | Before edit | `active_task_context.py` | Protect `tasks.json` projection and restate an active task boundary |
-| Before compact | `workflow_checkpoint.py` | Atomically save a minimal workflow checkpoint |
-| After compact/resume | `workflow_resume.py` | Re-inject the current workflow boundary |
+| Before compact | `workflow_checkpoint.py` | Validate and atomically save a minimal workflow checkpoint |
+| After compact/resume | `workflow_resume.py` | Select the newest valid live/checkpoint state, restore it atomically when needed, and re-inject the boundary |
 | Stop | `pre_stop_check.py` | Block once when the Ultra workflow is incomplete |
 | Subagent lifecycle | `subagent_tracker.py` | Append lifecycle evidence under `.ultra/runtime/` |
 
@@ -18,6 +18,10 @@ The plugin deliberately does not capture prompts, tool observations, transcripts
 cross-session memory or code-graph content. Generic command blocking and post-edit policy are
 user/repository governance. Persistent Memory/graph content belongs to separately installed providers.
 
+The checkpoint is a recovery artifact, not a second authority. A valid newer
+live workflow wins; a newer valid checkpoint may restore a missing or older
+live file; corrupt, non-object, or terminal checkpoints are ignored.
+
 Runtime wiring:
 
 - Claude Code: native `hooks/hooks.json` with `${CLAUDE_PLUGIN_ROOT}` paths.