ultra-builder-pro-cli 0.8.1 → 0.10.0

package/bin/install.js

@@ -4,14 +4,14 @@
  * 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
@@ -58,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'));
@@ -71,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:')}
@@ -95,6 +96,9 @@ 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
 `);
@@ -120,6 +124,7 @@ 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;
@@ -199,7 +204,7 @@ async function main() {
   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);

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/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.
 
@@ -43,14 +44,14 @@ reports are projections or workflow artifacts.
 
 ## 3. Live MCP and declared contracts
 
-`spec/mcp-tools.yaml` declares and the bundled server registers 29 tools across
+`spec/mcp-tools.yaml` declares and the bundled server registers 32 tools across
 five families:
 
 | Family | Live tools |
 |---|---|
 | `task.*` | create, update, list, get, switch_tag, delete, init_project, expand, parse_prd, dependency_topo, append_event, subscribe_events |
 | `session.*` | spawn, close, get, list, admission_check, heartbeat, subscribe_events |
-| `change.*` | create, update, get, list, context, converge, archive |
+| `change.*` | create, update, get, list, context, breadcrumb, learning_propose, learning_resolve, converge, archive |
 | `system.*` | doctor |
 | `plan.*` | export, get |
 
@@ -61,21 +62,42 @@ capability map documents those replacements.
 Any new MCP contract starts in `spec/mcp-tools.yaml` with valid and invalid
 fixtures. Do not add an ad-hoc server handler first.
 
-## 4. Native host presentation
+## 4. Context Spine contract
+
+Context Manifest v2 is a DB-backed role handoff, not a static codebase summary.
+`change.context` compiles required references, digests, readiness, context budget,
+public seam, exact verification command, and one next action for `plan`,
+`implement`, `check`, or `review`. The default fresh-context contract is at most
+12 files, about 12k tokens, and 40% of the host context; wider work must use an
+explicit `expand_contract`.
+
+`change.breadcrumb` is the only compact router. Hooks may inject its change/task,
+role, gate, readiness, blockers, and one next action. They must not inject intent
+bodies, transcripts, external memory, or graph payloads. Missing references,
+digest drift, HEAD drift, or budget overflow blocks readiness.
+
+Stable discoveries use `change.learning_propose`; they reach the baseline only
+through approve/reject/apply transitions in `change.learning_resolve`. Unresolved
+learning blocks convergence. Review contributes two independent axes,
+`spec_fidelity` and `engineering_standards`; neither can replace the other.
+
+## 5. Native host presentation
 
 | Host | Plugin form | Workflow entry | Hook form | Collaboration companions |
 |---|---|---|---|---|
 | 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
 evidence to the primary host for final verification.
 
-## 5. Hook boundary
+## 6. Hook boundary
 
-The canonical Python hook allowlist contains seven workflow-only adapters:
+The canonical Python hook bundle contains seven executable workflow hooks plus
+the shared read-only `context_spine.py` breadcrumb helper:
 
 - `health_check.py` and `workflow_context.py` on session start;
 - `active_task_context.py` before an edit;
@@ -84,7 +106,9 @@ The canonical Python hook allowlist contains seven workflow-only adapters:
 - `pre_stop_check.py` at stop;
 - `subagent_tracker.py` for bounded worker lifecycle evidence.
 
-`health_check.py` and `workflow_context.py` may inspect any initialized project;
+`workflow_context.py`, `active_task_context.py`, and `workflow_resume.py` read the
+same DB-derived breadcrumb through `context_spine.py`. `health_check.py` and
+`workflow_context.py` may inspect any initialized project;
 `active_task_context.py` always protects the task projection but limits ordinary
 edit guidance to an active workflow. Compact/stop/subagent hooks remain
 active-workflow scoped. OpenCode natively injects baseline/change context and
@@ -93,7 +117,7 @@ protects the projection; full health inspection is available through
 Generic command blocking, post-edit governance, and unrelated user hooks are not
 copied into Ultra Builder Pro.
 
-## 6. Memory boundary
+## 7. Memory boundary
 
 Ultra Builder Pro has no memory MCP family, recall skill, prompt capture,
 transcript capture, observation journal, or session-summary hook. Persistent
@@ -111,14 +135,14 @@ ultra-tools legacy-memory prune --confirm DELETE_ULTRA_LEGACY_MEMORY
 
 Archive before prune; the confirmation token is intentionally required.
 
-## 7. Project state layout
+## 8. Project state layout
 
 ```text
 .ultra/
 ├── state.db                 # authoritative SQLite store
 ├── workflow-state.json      # active workflow/recovery checkpoint
 ├── changes/
-│   ├── active/<id>/         # intent, delta, plan, compiled context, verification
+│   ├── active/<id>/         # intent, delta, plan, context v2, learning, verification
 │   └── archive/             # converged packets after baseline reconciliation
 ├── tasks/                   # projections and task contexts
 ├── specs/                   # research/product/architecture artifacts
@@ -128,7 +152,7 @@ Archive before prune; the confirmation token is intentionally required.
 └── delivery-report.json
 ```
 
-## 8. User handbook integration
+## 9. User handbook integration
 
 General engineering doctrine remains user-owned in `CLAUDE.md` or `AGENTS.md`.
 Ultra Builder Pro contributes one managed section only. Preview or apply it with:
@@ -138,12 +162,12 @@ ubp-handbook preview --runtime codex
 ubp-handbook apply --runtime codex
 ```
 
-Supported runtime names are `claude`, `codex`, and `opencode`. Apply creates a
+Supported runtime names are `claude`, `codex`, `opencode`, and `kimi`. Apply creates a
 timestamped backup, replaces only the marked block, and can migrate the old
 Codex `## Ultra Builder Pro Runtime Contract` section without touching the next
 user section. Plugin adapters themselves do not silently overwrite handbooks.
 
-## 9. Verification
+## 10. Verification
 
 Run `npm run test:all`, `python3 -m pytest hooks/tests -q`, and `npm audit`.
 Adapter tests assert the allowlisted assets, native manifests, hook boundary,

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)          │
                        └────────────┬─────────────┘
                                     │
                 ┌───────────────────┼────────────────────┐
@@ -53,7 +53,7 @@ the supported hosts share.
 | Layer        | Role                                         | Form                                                  |
 |--------------|----------------------------------------------|-------------------------------------------------------|
 | **skill**    | knowledge carrier; tells the runtime *what to do* | `skills/<name>/SKILL.md` discovered natively by all supported runtimes |
-| **MCP**      | authoritative workflow-state API             | stdio MCP server exposing 29 live tools across task/session/change/system/plan families in [`spec/mcp-tools.yaml`](../spec/mcp-tools.yaml) |
+| **MCP**      | authoritative workflow-state and Context Spine API | stdio MCP server exposing 32 live tools across task/session/change/system/plan families in [`spec/mcp-tools.yaml`](../spec/mcp-tools.yaml) |
 | **CLI**      | explicit initialization, recovery, diagnostics, and orchestration | `ultra-tools` / `ubp-orchestrator`; only commands listed by `--help` are executable (see [`spec/cli-protocol.md`](../spec/cli-protocol.md)) |
 
 Why three: skills give us behavior portability across runtimes; MCP gives
@@ -70,7 +70,7 @@ RPC, and host-native loaders own resolution and invocation.
 
 All durable Ultra workflow state lives in one SQLite file with WAL enabled. Schema is
 fixed in [`spec/schemas/state-db.sql`](../spec/schemas/state-db.sql) and
-covers fifteen tables:
+covers sixteen tables:
 
 | Table              | Holds                                             | Phase |
 |--------------------|---------------------------------------------------|-------|
@@ -84,7 +84,8 @@ covers fifteen tables:
 | `circuit_breaker`  | bounded retry and halt state for failed tasks       | 5     |
 | `changes`          | continuous feature/fix/incident lifecycle           | 8C    |
 | `artifacts`        | intent/context/verification artifact registry       | 8C    |
-| `context_snapshots`| compiled context hashes, git head, provider refs    | 8C    |
+| `context_snapshots`| role/gate context, readiness, budget, execution seam, hashes, git head, provider refs | 10 |
+| `spec_learning_candidates` | approval-gated implementation discoveries for baseline convergence | 10 |
 | `trace_links`      | task/spec/change traceability                        | 8C    |
 | `incidents`        | structured runtime failures and resolutions         | 8C    |
 | `projection_jobs` | durable projection outbox/retry state                | 8C    |
@@ -101,7 +102,8 @@ Two rules make this work:
 2. **Single writer for mutable tables, multi-writer for `events`.**
    `.ultra/state.db` opens in WAL with `busy_timeout=5000`. The MCP
    server holds the single writer connection for `tasks`, `sessions`,
-   `telemetry`, `specs_refs`, and `migration_history`; the CLI calls
+   `changes`, `context_snapshots`, `spec_learning_candidates`, `telemetry`,
+   `specs_refs`, and `migration_history`; the CLI calls
    those tools over stdio rather than opening its own writer. The
    `events` table is append-only and explicitly multi-writer — CLI and
    orchestrator processes append directly to it under the same WAL +
@@ -133,7 +135,8 @@ active -> blocked -> active -> ready -> archived
    |                              |
    ├─ intent + delta + plan       └─ verification + baseline reconciliation
    ├─ linked tasks
-   └─ context-manifest (current HEAD + provider metadata references)
+   ├─ context-manifest v2 (role + gate + readiness + execution seam)
+   └─ spec-learning candidates (proposed -> approved/rejected -> applied)
 ```
 
 `quick`, `standard`, `major`, and `incident` kinds require different evidence,
@@ -141,6 +144,29 @@ 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.
 
+### Context Spine
+
+Context Manifest v2 is the handoff contract between planning, implementation,
+checking, review, convergence, and recovery. Each snapshot records:
+
+- one role (`plan`, `implement`, `check`, or `review`) and lifecycle gate;
+- required context references with local digests and reasons;
+- readiness blockers for missing/stale references or budget overflow;
+- a fresh-context budget (12 files / about 12k tokens / 40% by default);
+- an execution contract (`slice_kind`, public seam, exact verification command);
+- one deterministic next action.
+
+`change.breadcrumb` derives the compact current position from state.db. Session,
+edit, and resume hooks inject only this breadcrumb, never the intent body,
+provider content, or a conversation summary. A changed git HEAD marks the
+snapshot stale and routes back to `change.context`.
+
+`change.learning_propose` records a durable implementation discovery without
+silently rewriting the baseline. `change.learning_resolve` enforces approval,
+rejection, and applied transitions. Proposed or merely approved candidates block
+convergence, so daily work cannot leave accepted behavior stranded in chat or a
+delta packet.
+
 `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
@@ -156,7 +182,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,
@@ -189,7 +215,7 @@ durable authority alongside `.ultra/state.db`.
 
 ## 7. Installation provenance — read-only cross-host diagnosis
 
-Every Claude Code, OpenCode, and Codex adapter writes a normalized
+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

package/docs/PLAN.zh-CN.md

@@ -6,12 +6,13 @@
 > 插件只保留 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.8.1；三宿主 native plugin、29 个 live MCP tool、
-schema 9.0（15 表）、持续 change/context/convergence/doctor、incident debug lane、
+**当前状态**：v0.10.0；四宿主 native plugin、32 个 live MCP tool、
+schema 10.0（16 表）、Context Spine v2 / breadcrumb / spec-learning、持续
+change/context/convergence/doctor、incident debug lane、
 checkpoint 恢复消费与跨宿主安装 provenance/doctor 已落地；npm 发布由
 `v*.*.*` tag 触发。以下 Phase 0-9 正文保留为 2026-04 的实施历史，不再作为
 当前 runtime 或发布状态的事实来源。

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.10.x`; every release is gated by `npm run verify:release`.
 
 ---
 
@@ -43,20 +43,21 @@ authoritative workflow store.
 | 8A    | Plan automation (parse / topo / expand + artifact + human gate) | ✅ done (D47, `a932cb8`) → v0.3 |
 | 8B    | Execution automation (dispatch / parallel worktree / merge) | ✅ done (D48, `8224159`) — **v0.3 ready** |
 | 8C    | Continuous change packets + context compiler + convergence + doctor | ✅ done (D52) |
+| 10    | Context Spine v2 + breadcrumb + fresh-context budget + spec learning + two-axis review | ✅ done |
 | 9     | Release pipeline                               | npm tag publishing live; Homebrew / pip not implemented |
 
 ## What is in the repo today
 
 ```
 spec/                       ← Phase 1 single source of truth
-├── mcp-tools.yaml          (29 live tools across 5 families)
+├── mcp-tools.yaml          (32 live tools across 5 families)
 ├── cli-protocol.md         (CLI ↔ MCP mapping table)
 ├── schemas/                (state-db.sql + 4 JSON schemas)
 ├── fixtures/{valid,invalid}/  (+ v4.4-project for migration)
 └── scripts/test-all.cjs    (npm run test:spec — 7 validation stages)
 
 mcp-server/                 ← Phase 2 authoritative state layer
-├── server.cjs              (stdio MCP server, 29 task/session/change/system/plan tools)
+├── server.cjs              (stdio MCP server, 32 task/session/change/system/plan tools)
 ├── lib/
 │   ├── state-db.cjs        (SQLite + WAL + pragmas)
 │   ├── state-ops.cjs       (full write API, status state machine)
@@ -74,7 +75,7 @@ bin/install.js              ← multi-runtime installer
 bin/handbook.js             ← explicit managed user-handbook sync
 adapters/                   ← native Claude/OpenCode/Codex plugin builders
 skills/                     ← allowlisted Ultra workflows, internal rules, and collab companions
-hooks/                      ← 7 workflow-only Python hooks; OpenCode uses native JavaScript hooks
+hooks/                      ← 7 executable workflow hooks + shared Context Spine helper; OpenCode uses native JavaScript hooks
 docs/
 ├── PLAN.zh-CN.md                historical phase plan + decision log
 ├── ARCHITECTURE.md              Phase 1 single-page entry point

package/docs/RUNTIME-COMPAT-MATRIX.md

@@ -1,97 +1,141 @@
 # 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, validated checkpoint + resume/restore matcher | FULL, native compacting context | FULL, validated checkpoint + `PostCompact` restore |
-| 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, DB-derived Context Spine breadcrumb on native `SessionStart` | DEGRADED, projected v2 breadcrumb; health via `system.doctor` | FULL, DB-derived breadcrumb on native `SessionStart` | FULL, DB-derived breadcrumb via session-start skill + 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 |
-
-All 29 `task.*`, `session.*`, `change.*`, `system.*`, and `plan.*` operations
+| 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 | 32 | 32 | 32 | 32 |
+| Context Spine v2 / breadcrumb | FULL | FULL, DB-generated projection consumed by native JS | FULL | FULL |
+| Approval-gated spec learning | FULL | FULL | FULL | FULL |
+| 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 32 `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 |
-| Normalized install provenance | FULL | FULL | FULL |
-| Read-only `ubp --doctor` | FULL | FULL | FULL |
-| Asset-content and host-contract drift detection | FULL | FULL | FULL |
+## 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 | `10.0` |
+| Runtime values | `claude`, `opencode`, `codex`, `kimi` |
+| Upgrade from earlier schema | preserves Kimi runtime rows, adds Context Spine columns and `spec_learning_candidates` transactionally |
+| 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
@@ -100,7 +144,9 @@ loading, and user interaction remain host-native surfaces.
   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 three-host doctor output and
+- `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.