ultra-builder-pro-cli 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.20.0] — 2026-07-28
+
+### Added
+
+- Added schema 19 and `decision.complete` so settled normalized intent reaches a
+  terminal lifecycle state without fabricating a second user approval or an
+  artifact checkpoint. Existing settled schema-18 threads migrate safely.
+
+### Changed
+
+- Unified semantic selection across Claude Code, Codex, OpenCode, and Kimi Code
+  as `inspect -> suggest -> ask if unresolved -> normalize -> persist`, using
+  each host's native structured question surface with a direct-question
+  fallback.
+- Made research coverage and planning posture owner-selected after model
+  recommendation while preserving autonomous fact finding, synthesis,
+  decomposition, and reversible implementation judgment.
+- Stopped requiring a ceremonial decision checkpoint after every normalized
+  answer. Artifact checkpoints remain explicit digest-bound freshness gates.
+- Made unanswered non-blocking follow-ups advisory instead of global workflow
+  gates; unanswered blocking choices and blocking deferrals still fail closed.
+
+## [0.19.1] — 2026-07-26
+
+### Fixed
+
+- Made the four-host handbook-isolation release test hermetic so a clean CI
+  runner does not require the Codex CLI merely to prove that installation and
+  uninstallation preserve user-owned instruction files byte for byte.
+
+## [0.19.0] — 2026-07-26
+
+### Changed
+
+- Made every public Ultra workflow explicitly activated. Claude Code and Kimi
+  Code disable model invocation, Codex keeps implicit invocation disabled, and
+  OpenCode commands load private plugin workflow assets instead of exposing
+  public workflows through its model skill catalog.
+- Limited lifecycle context, health, checkpoint, stop, and subagent hooks to
+  DB-authoritative active workflows. Initialized idle projects retain only
+  generated-projection protection.
+- Changed workflow handoff to return allowed transitions and a host-owned
+  recommendation without launching another public workflow.
+
+### Removed
+
+- Removed `ubp-handbook`, the shared handbook renderer, Kimi session bootstrap,
+  and every package path capable of creating or rewriting user-level
+  `CLAUDE.md` or `AGENTS.md` files.
+
 ## [0.18.0] — 2026-07-25
 
 ### Added
@@ -789,7 +839,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   skill manifest, CLI protocol + mapping table; 5 spec validators.
 - **Phase 0 — skeleton**: multi-runtime installer scaffolding.
 
-[Unreleased]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.18.0...HEAD
+[Unreleased]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.20.0...HEAD
+[0.20.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.19.1...v0.20.0
+[0.19.1]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.19.0...v0.19.1
+[0.19.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.18.0...v0.19.0
 [0.18.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.17.1...v0.18.0
 [0.17.1]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.17.0...v0.17.1
 [0.17.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.16.0...v0.17.0

package/README.md

@@ -73,8 +73,8 @@ The responsibility split is deliberate:
 
 | Owner | Responsibility |
 |---|---|
-| **User** | Product intent, material scope and trade-offs, destructive actions, publishing and deployment authorization |
-| **Host model** | Fact-finding, synthesis, research coverage, route recommendation, reversible implementation decisions |
+| **User** | Product intent, semantic route selection, material scope and trade-offs, risk acceptance, destructive actions, publishing and deployment authorization |
+| **Host model** | Fact-finding, synthesis, research-coverage and route recommendations, reversible implementation decisions |
 | **Ultra MCP** | Durable state, evidence references, digests, freshness, locks, valid transitions and hard recovery |
 | **Host adapter** | Native Skill discovery, user questions, tool invocation, installation, and runtime wiring |
 | **Hooks** | Fast lifecycle observation, current breadcrumb injection, and protection of generated projections |
@@ -155,24 +155,11 @@ npx --yes ultra-builder-pro-cli@latest --all --global --doctor --json
 After installing or upgrading, start a new Claude Code, OpenCode, or Codex
 session. In Kimi Code, run `/reload` or start a new session.
 
-Plugin installation does not mutate durable user instructions. To preview and
-explicitly converge a legacy handbook into the complete host-native engineering
-contract, use full mode:
-
-```bash
-npx --yes --package ultra-builder-pro-cli@latest \
-  ubp-handbook preview --runtime codex --full > /tmp/ubp-codex-handbook.md
-# Inspect the preview, then copy the confirmation token printed to the terminal.
-npx --yes --package ultra-builder-pro-cli@latest \
-  ubp-handbook apply --runtime codex --full \
-  --confirm "PASTE_64_CHARACTER_TOKEN_HERE"
-```
-
-Replace `codex` with `claude`, `opencode`, or `kimi` for the other hosts. The
-apply command rejects a missing or stale preview token, creates a timestamped
-backup, follows user-managed handbook symlinks, and preserves supported
-marker-delimited content owned by other providers. Without `--full`, only the
-small Ultra runtime block is merged.
+Plugin installation, update, doctor, and uninstall never mutate durable user
+instructions such as `CLAUDE.md` or `AGENTS.md`. Ultra policy stays in the plugin
+and becomes active only after an explicit workflow invocation. Existing legacy
+Ultra marker blocks in a user handbook are left untouched for the owner to review;
+the plugin neither claims nor silently deletes user-authored content.
 
 ### Host invocation
 
@@ -202,7 +189,7 @@ Initialization:
 - identifies the repository root and scope;
 - classifies the repository as greenfield, brownfield, or migrated;
 - initializes Git when needed;
-- creates `.ultra/` and schema 18 project authority;
+- creates `.ultra/` and schema 19 project authority;
 - verifies that the scaffold and database can be read back;
 - completes without silently starting research, creating a commit, adding a
   remote, or pushing anything.
@@ -244,9 +231,11 @@ product story. It builds a current-system baseline from:
 - APIs, data, permissions, integrations, deployment, and recovery seams;
 - known failures, documentation drift, technical debt, and unresolved unknowns.
 
-During `ultra-research`, the host model selects the smallest evidence-backed set
-of applicable catalog areas. Every included area receives one explicit
-disposition:
+During `ultra-research`, the host model inspects current evidence and recommends
+the smallest sufficient route. The owner selects, modifies, delegates, or
+defers it through the host-native question surface unless the current request
+already resolves the route. The normalized accepted coverage is then stored in
+`.ultra/state.db`. Every included area receives one explicit disposition:
 
 - `execute` — produce fresh evidence;
 - `verify_existing` — validate an existing artifact;
@@ -256,7 +245,8 @@ disposition:
 
 The catalog is not a mandatory document set or questionnaire. Omitted areas
 create no workflow rows; an explicit exclusion is recorded only when retaining
-that rationale is useful.
+that rationale is useful. MCP validates state, evidence, and transitions; it
+does not store or prove the preceding UI interaction.
 
 Older projection-only Ultra projects are preserved and routed through a
 backup-first migration or rebaseline. Use `ultra-doctor` when initialization
@@ -366,7 +356,6 @@ worker execution or verified auto-merge.
 | `ultra-builder-pro-cli` / `ubp` | Install, update, uninstall, and diagnose host plugins |
 | `ultra-tools` | Inspect and maintain project tasks, sessions, state, migration, and recovery |
 | `ubp-orchestrator` | Execute current dependency waves or supervise configured workers |
-| `ubp-handbook` | Preview or apply either the bounded Ultra block or the explicit full host-native handbook |
 
 Useful read-only checks:
 
@@ -426,7 +415,7 @@ and `test:rest`.
 | [Runtime Compatibility Matrix](./docs/RUNTIME-COMPAT-MATRIX.md) | Claude Code, OpenCode, Codex, and Kimi presentation details |
 | [Legacy CLI Crosswalk](./docs/LEGACY-CLI-CROSSWALK.md) | What was preserved, strengthened, or replaced from the original Ultra Builder Pro |
 | [Agent Context](./docs/AGENT-CONTEXT.md) | Context Manifest and host-agent execution contract |
-| [User Handbook Contract](./docs/USER-HANDBOOK-CONTRACT.md) | Shared user-level policy and managed host renderings |
+| [Plugin Isolation Contract](./docs/PLUGIN-ISOLATION-CONTRACT.md) | Plugin ownership, explicit activation, idle behavior, and user-instruction isolation |
 | [State DB Access Policy](./docs/STATE-DB-ACCESS-POLICY.md) | Multi-process authority and write rules |
 | [Roadmap](./docs/ROADMAP.md) | Current and historical delivery scope |
 | [Changelog](./CHANGELOG.md) | Release history |

package/adapters/_shared/interaction-contract.cjs

@@ -4,18 +4,22 @@ const SURFACES = Object.freeze({
   claude: Object.freeze({
     primary: 'AskUserQuestion',
     fallback: 'direct_user_interaction',
+    availability: 'interactive_session',
   }),
   codex: Object.freeze({
     primary: 'request_user_input',
     fallback: 'direct_user_interaction',
+    availability: 'current_mode_exposes_tool',
   }),
   opencode: Object.freeze({
     primary: 'question',
     fallback: 'direct_user_interaction',
+    availability: 'question_permission_not_denied',
   }),
   kimi: Object.freeze({
-    primary: 'native_question_surface',
+    primary: 'AskUserQuestion',
     fallback: 'direct_user_interaction',
+    availability: 'interactive_non_auto_mode',
   }),
 });
 
@@ -23,18 +27,21 @@ function interactionContract(runtime) {
   const question = SURFACES[runtime];
   if (!question) throw new Error(`unsupported interaction runtime: ${runtime}`);
   return {
-    schema_version: '1.0',
+    schema_version: '1.1',
     runtime,
     authority: {
       user: [
         'product_intent',
         'material_scope_and_tradeoffs',
+        'semantic_route_selection',
+        'risk_acceptance',
         'destructive_or_external_effect_authorization',
       ],
       host_model: [
         'fact_finding_and_synthesis',
         'reversible_implementation_judgment',
-        'coverage_risk_and_route_recommendation',
+        'semantic_route_recommendation',
+        'accepted_intent_normalization',
       ],
       ultra_mcp: [
         'durable_state_and_evidence_refs',
@@ -44,10 +51,25 @@ function interactionContract(runtime) {
     },
     interaction: {
       question_surface: question,
+      semantic_selection_flow: [
+        'inspect',
+        'suggest',
+        'ask_if_unresolved',
+        'normalize',
+        'persist',
+      ],
       dependent_decisions: 'one_at_a_time',
       independent_low_load_questions: { maximum: 3 },
       explicit_current_intent: 'normalize_without_reconfirmation',
-      unavailable_native_surface: 'use_direct_interaction',
+      dismissed_question: 'remain_unanswered',
+      unavailable_native_surface: 'use_direct_interaction_if_permitted',
+      host_forbids_interaction: 'remain_unanswered',
+    },
+    persistence: {
+      accepted_intent: 'trust_as_current_authority',
+      user_interaction_proof: 'not_required',
+      raw_prompt_or_transcript: 'never_store',
+      pending_question: 'store_only_when_recovery_requires_it',
     },
     routing: {
       semantic_recommendation_owner: 'host_model',

package/adapters/claude.js

@@ -68,10 +68,12 @@ function copySkills(repoRoot, target, names) {
             'Claude Code Task workers using the installed review agent definitions',
           );
         }
+        const policy = skillPolicy(name);
         return Buffer.from(serializeFrontmatter({
           name,
           description: fm.description,
-          'user-invocable': skillPolicy(name).userInvocable,
+          'user-invocable': policy.userInvocable,
+          ...(policy.userInvocable ? { 'disable-model-invocation': true } : {}),
         }, adaptedBody));
       },
     });

package/adapters/kimi.js

@@ -20,6 +20,7 @@ const provenance = require('./_shared/provenance.cjs');
 const {
   CORE_PUBLIC_SKILLS,
   WORKFLOW_HOOK_FILES,
+  skillPolicy,
   skillsForRuntime,
 } = require('./_shared/runtime-assets.cjs');
 
@@ -28,7 +29,6 @@ const MCP_SERVER_NAME = PLUGIN_ID;
 const PROVENANCE_FILE = 'provenance.json';
 const REGISTRY_RELATIVE = path.join('plugins', 'installed.json');
 const MANAGED_RELATIVE = path.join('plugins', 'managed', PLUGIN_ID);
-const BOOTSTRAP_SKILL = 'using-ultra-builder-pro';
 
 function resolveTarget(ctx = {}) {
   if (ctx.configDir) return path.resolve(ctx.configDir);
@@ -127,11 +127,13 @@ function transformSkill(buf, relPath, skillName) {
   if (!relPath.endsWith('.md')) return buf;
   const { fm, body } = parseFm(source);
   if (!fm) return Buffer.from(kimiTextTransform(source, skillName), 'utf8');
+  const policy = skillPolicy(skillName);
   const nativeFm = {
     name: String(fm.name || skillName),
     description: kimiTextTransform(fm.description || `${skillName} workflow`, skillName)
       .replace(/\s+/g, ' ')
       .trim(),
+    ...(policy.userInvocable ? { disableModelInvocation: true } : {}),
   };
   return Buffer.from(serializeFm(nativeFm, kimiTextTransform(body, skillName)), 'utf8');
 }
@@ -162,29 +164,6 @@ function copySkills(repoRoot, pluginRoot) {
     });
     installed.push(name);
   }
-  const bootstrapRoot = path.join(pluginRoot, 'skills', BOOTSTRAP_SKILL);
-  ensureDir(bootstrapRoot);
-  writeAtomic(path.join(bootstrapRoot, 'SKILL.md'), `---
-name: ${BOOTSTRAP_SKILL}
-description: Bootstrap the Kimi-native Ultra Builder Pro runtime contract at session start.
----
-
-# Ultra Builder Pro for Kimi Code
-
-Kimi Code is the primary host and owns all edits, evidence, and final verification. Use the
-namespaced \`/ultra-builder-pro:ultra-*\` commands or invoke the registered Ultra skills directly.
-
-- \`.ultra/state.db\` is the only durable Ultra authority. JSON and Markdown under \`.ultra/\` are
-  projections or workflow artifacts and must never replace MCP state writes.
-- Memory and code graph data belong to separately installed external providers. Ultra stores only
-  provider metadata references and never captures prompts, transcripts, or cross-session memory.
-- Use Kimi \`TodoList\` for session coordination and Kimi \`Agent\` / \`AgentSwarm\` for bounded
-  workers. Bundled files under \`$KIMI_PLUGIN_ROOT/agents/\` are worker prompt templates.
-- Before compaction, Ultra saves its workflow checkpoint. After compaction or recovery, inspect
-  \`.ultra/runtime/checkpoint.json\` and call the Ultra status/doctor MCP tools before continuing.
-- If no Ultra workflow is active, the lifecycle hooks remain advisory except projection protection.
-`);
-  installed.push(BOOTSTRAP_SKILL);
   return installed;
 }
 
@@ -280,7 +259,6 @@ function writeManifest(repoRoot, pluginRoot) {
     homepage: pkg.homepage,
     license: pkg.license || 'MIT',
     skills: ['./skills'],
-    sessionStart: { skill: BOOTSTRAP_SKILL },
     mcpServers: { [MCP_SERVER_NAME]: mcpManifest() },
     hooks: buildHooksManifest(),
     commands: ['./commands'],
@@ -351,9 +329,6 @@ function writePluginProvenance(repoRoot, target) {
       mcp_launcher: { root: 'plugin', path: path.join('runtime', 'launch.cjs') },
       hook_event_helper: { root: 'plugin', path: path.join('runtime', 'hook-event.cjs') },
       hook_adapter: { root: 'plugin', path: path.join('hooks', 'adapters', 'kimi.py') },
-      session_bootstrap: {
-        root: 'plugin', path: path.join('skills', BOOTSTRAP_SKILL, 'SKILL.md'),
-      },
     },
   });
   return { file, manifest };
@@ -444,7 +419,7 @@ function doctor(ctx = {}) {
       && manifest.skills.includes('./skills')
       && Array.isArray(manifest.commands)
       && manifest.commands.includes('./commands')
-      && manifest.sessionStart?.skill === BOOTSTRAP_SKILL;
+      && manifest.sessionStart === undefined;
     const mcp = manifest.mcpServers?.[MCP_SERVER_NAME];
     const expected = mcpManifest();
     mcpOk = !!mcp
@@ -508,7 +483,6 @@ module.exports = {
   name: 'kimi',
   PLUGIN_ID,
   MCP_SERVER_NAME,
-  BOOTSTRAP_SKILL,
   buildHooksManifest,
   kimiTextTransform,
   resolveTarget,

package/adapters/opencode.js

@@ -38,6 +38,11 @@ const PLUGIN_MARKER = '// Managed by Ultra Builder Pro.';
 const PROVENANCE_FILE = 'provenance.json';
 const COMMAND_NAMES = CORE_PUBLIC_SKILLS;
 
+function discoverableSkillNames() {
+  return skillsForRuntime('opencode')
+    .filter((name) => !CORE_PUBLIC_SKILLS.includes(name));
+}
+
 function resolveTarget(ctx = {}) {
   if (ctx.configDir) return ctx.configDir;
   if (ctx.scope === 'global') {
@@ -97,16 +102,26 @@ function openCodeTextTransform(input, assetName = '') {
   return text;
 }
 
-function openCodeCommandTransform(buf, relPath, commandName) {
+function openCodeCommandTransform(buf, relPath, commandName, workflowFile) {
   if (!relPath.endsWith('.md')) return buf;
-  const { fm, body } = parseFm(buf.toString('utf8'));
-  if (!fm) return Buffer.from(openCodeTextTransform(buf.toString('utf8'), commandName), 'utf8');
+  const { fm } = parseFm(buf.toString('utf8'));
+  if (!fm) throw new Error(`missing frontmatter in OpenCode command: ${commandName}`);
   const nativeFm = {
     description: openCodeTextTransform(fm.description || `${commandName} workflow`, commandName)
       .replace(/\s+/g, ' ')
       .trim(),
   };
-  return Buffer.from(serializeFm(nativeFm, openCodeTextTransform(body, commandName)), 'utf8');
+  const body = [
+    `# Run ${commandName}`,
+    '',
+    `Read and follow \`${workflowFile}\` as the only workflow definition.`,
+    'This explicit command is the activation boundary; do not substitute a model-discovered',
+    'public skill or start another public Ultra workflow automatically.',
+    '',
+    'Arguments: $ARGUMENTS',
+    '',
+  ].join('\n');
+  return Buffer.from(serializeFm(nativeFm, body), 'utf8');
 }
 
 function openCodeSkillAssetTransform(buf, relPath, skillName) {
@@ -229,7 +244,10 @@ function copyCommands(repoRoot, target) {
     const file = `${name}.md`;
     const source = path.join(repoRoot, 'commands', file);
     if (!fs.existsSync(source)) throw new Error(`missing allowlisted OpenCode command: ${file}`);
-    const transformed = withManagedMarker(openCodeCommandTransform(fs.readFileSync(source), file, name));
+    const workflowFile = path.join(target, BUNDLE_DIR, 'workflows', name, 'SKILL.md');
+    const transformed = withManagedMarker(
+      openCodeCommandTransform(fs.readFileSync(source), file, name, workflowFile),
+    );
     writeAtomic(path.join(output, file), transformed);
     copied.push(file);
   }
@@ -238,7 +256,7 @@ function copyCommands(repoRoot, target) {
 
 function copySkills(repoRoot, target) {
   const copied = [];
-  const names = skillsForRuntime('opencode');
+  const names = discoverableSkillNames();
   const skillsRoot = path.join(target, 'skills');
   ensureDir(skillsRoot);
   for (const entry of fs.readdirSync(skillsRoot, { withFileTypes: true })) {
@@ -262,6 +280,22 @@ function copySkills(repoRoot, target) {
   return copied;
 }
 
+function copyPrivateWorkflows(repoRoot, bundleRoot) {
+  const copied = [];
+  const workflowsRoot = path.join(bundleRoot, 'workflows');
+  for (const name of CORE_PUBLIC_SKILLS) {
+    const source = path.join(repoRoot, 'skills', name);
+    if (!fs.existsSync(path.join(source, 'SKILL.md'))) {
+      throw new Error(`missing allowlisted OpenCode workflow: ${name}`);
+    }
+    const files = copyTree(source, path.join(workflowsRoot, name), {
+      transform: (buf, relPath) => openCodeSkillAssetTransform(buf, relPath, name),
+    });
+    copied.push(...files.map((rel) => path.join('workflows', name, rel)));
+  }
+  return copied;
+}
+
 function copyAgents(repoRoot, target) {
   const sourceRoot = path.join(repoRoot, 'agents');
   const output = path.join(target, 'agents');
@@ -279,7 +313,7 @@ function preflightAssets(repoRoot, target) {
   for (const name of COMMAND_NAMES) {
     assertManagedTextTarget(path.join(target, 'commands', `${name}.md`), 'command');
   }
-  for (const name of skillsForRuntime('opencode')) {
+  for (const name of discoverableSkillNames()) {
     const destination = path.join(target, 'skills', name);
     if (fs.existsSync(destination) && !isManaged(destination)) {
       throw new Error(`refusing to replace unmanaged OpenCode skill: ${destination}`);
@@ -316,8 +350,8 @@ const BREADCRUMB_CLI = path.resolve(
 function findUltraRoot(directory) {
   let current = path.resolve(directory);
   while (true) {
-    const ultra = path.join(current, ".ultra");
-    if (fs.existsSync(ultra) && fs.statSync(ultra).isDirectory()) return current;
+    const stateDb = path.join(current, ".ultra", "state.db");
+    if (fs.existsSync(stateDb) && fs.statSync(stateDb).isFile()) return current;
     const parent = path.dirname(current);
     if (parent === current) return null;
     current = parent;
@@ -335,12 +369,13 @@ function readUltraContext(directory) {
       timeout: 5000,
     });
     const value = JSON.parse(raw);
-    if (!value?.breadcrumb || typeof value.text !== "string" || !value.text) {
-      throw new Error("canonical breadcrumb response is incomplete");
+    // A canonical breadcrumb is injectable only while DB authority proves an active workflow.
+    if (!value?.breadcrumb || !value.breadcrumb.workflow
+        || typeof value.text !== "string" || !value.text) {
+      return { root, breadcrumb: null, text: null };
     }
     return { root, breadcrumb: value.breadcrumb, text: value.text };
-  } catch (error) {
-    process.stderr.write(\`[ultra-builder-pro] cannot read canonical breadcrumb: \${error.message}\\n\`);
+  } catch {
     return { root, breadcrumb: null, text: null };
   }
 }
@@ -415,6 +450,7 @@ function install(ctx = {}) {
   const bundleRoot = path.join(target, BUNDLE_DIR);
   if (fs.existsSync(bundleRoot)) removeTree(bundleRoot);
   ensureDir(bundleRoot);
+  report.copied.workflows = copyPrivateWorkflows(repoRoot, bundleRoot);
   const runtime = buildMcpRuntime(repoRoot, bundleRoot, { runtime: 'opencode' });
   markManaged(bundleRoot, { adapter: 'opencode', asset: 'runtime-bundle' });
   const configFile = path.join(target, 'opencode.json');
@@ -433,7 +469,7 @@ function install(ctx = {}) {
   const bundleAssets = provenance.assetRefsForTree('config', bundleRoot, {
     exclude: [PROVENANCE_FILE],
   }).map((asset) => ({ ...asset, path: path.join(BUNDLE_DIR, asset.path) }));
-  const skillMarkers = skillsForRuntime('opencode').map((name) => ({
+  const skillMarkers = discoverableSkillNames().map((name) => ({
     root: 'config', path: path.join('skills', name, '.ubp-managed'),
   }));
   const provenanceFile = path.join(bundleRoot, PROVENANCE_FILE);

package/commands/ultra-research.md

@@ -1,5 +1,5 @@
 ---
-description: Build evidence with model-selected semantic coverage and adaptive user alignment
+description: Build evidence with recommended, owner-selected semantic coverage and adaptive alignment
 argument-hint: "[scope-or-question]"
 workflow-ref: "@skills/ultra-research/SKILL.md"
 ---

package/docs/AGENT-CONTEXT.md

@@ -12,8 +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, `ultra-verify`, and the minimal
-  Kimi session bootstrap required to establish the shared runtime boundary;
+- the host-specific collaboration companions, `ultra-verify`, and host-native
+  explicit command or skill entry points;
 - bounded review/debug agents, workflow-only hooks, MCP task state, and the
   portable CLI/orchestrator.
 
@@ -44,7 +44,7 @@ reports are projections or workflow artifacts.
 
 ## 3. Live MCP and declared contracts
 
-`spec/mcp-tools.yaml` declares and the bundled server registers 50 tools across
+`spec/mcp-tools.yaml` declares and the bundled server registers 51 tools across
 eight families:
 
 | Family | Live tools |
@@ -53,15 +53,16 @@ eight families:
 | `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, breadcrumb, learning_propose, learning_resolve, converge, archive |
-| `decision.*` | thread_start, get, list, open, resolve, delegate, defer, supersede, checkpoint |
+| `decision.*` | thread_start, get, list, open, resolve, delegate, defer, supersede, complete, checkpoint |
 | `workflow.*` | start, get, list, step, complete |
 | `system.*` | doctor |
 | `plan.*` | export, get |
 
 Review, repository impact discovery, skill loading, and decision presentation remain
 host-native capabilities rather than fake MCP contracts. MCP stores only normalized
-decision authority and checkpoints; it never generates questions or retains prompts
-and transcripts. The generated Codex capability map documents host replacements.
+decision authority, pending-question recovery state, lifecycle completion, and optional
+checkpoints; it never generates questions or retains prompts and transcripts. The
+generated Codex capability map documents host replacements.
 
 The complete write, transition, invalidation, and recovery contract lives in
 [`WORKFLOW-LIFECYCLE.md`](./WORKFLOW-LIFECYCLE.md).
@@ -79,11 +80,13 @@ review, and deliver route back to the same thread instead of deciding for the ow
 
 One partial unique index permits only one open item per thread. `decision.resolve`,
 `decision.delegate`, and `decision.defer` preserve the source of authority;
-`decision.supersede` preserves history when evidence or intent changes. Prepare and
-confirm checkpointing bind a material accepted cluster to current artifact digests
-when interruption recovery needs that boundary. Status and breadcrumb return only the
-current question plus allowed and mechanically required transitions, so recovery does
-not require replaying conversation history.
+`decision.supersede` preserves history when evidence or intent changes.
+`decision.complete` closes settled normalized state without manufacturing an approval
+receipt. Prepare and confirm checkpointing remain optional and bind only a material
+accepted cluster to current artifact digests when interruption recovery needs that
+boundary. Status and breadcrumb return only the current question plus allowed and
+mechanically required transitions, so recovery does not require replaying conversation
+history.
 
 ## 5. Context Spine contract
 
@@ -191,31 +194,17 @@ Archive before prune; the confirmation token is intentionally required.
     └── delivery/<workflow-id>.json
 ```
 
-## 10. User handbook integration
+## 10. Plugin and user-instruction isolation
 
-General engineering doctrine lives in the host's durable `CLAUDE.md` or `AGENTS.md`.
-Ultra Builder Pro supports two explicit operations. Default mode updates only the
-bounded runtime contract:
+General engineering doctrine and long-term personal preferences live in each
+host's durable `CLAUDE.md` or `AGENTS.md`. Ultra never writes those files. Its
+workflow doctrine remains in plugin-owned skills and is loaded only through an
+explicit public invocation.
 
-```bash
-ubp-handbook preview --runtime codex
-ubp-handbook apply --runtime codex
-```
-
-Full mode replaces legacy unmarked prompt content with one complete host-native
-engineering handbook:
-
-```bash
-ubp-handbook preview --runtime codex --full > /tmp/ubp-codex-handbook.md
-ubp-handbook apply --runtime codex --full \
-  --confirm "PASTE_64_CHARACTER_TOKEN_HERE"
-```
-
-Supported runtime names are `claude`, `codex`, `opencode`, and `kimi`. The full
-preview prints its content-bound confirmation token to stderr. Both apply modes
-create a timestamped backup. Full mode preserves supported marker-delimited blocks
-owned by other providers, follows handbook symlinks, and rejects missing or stale
-confirmation. Plugin adapters never overwrite handbooks implicitly.
+Installation and uninstall own only adapter-declared commands, skills, workers,
+hooks, runtime assets, provenance, and host registration. Project authority is
+created only by an explicit `ultra-init`, and uninstall never deletes `.ultra/`.
+See [`PLUGIN-ISOLATION-CONTRACT.md`](./PLUGIN-ISOLATION-CONTRACT.md).
 
 ## 11. Verification