ultra-builder-pro-cli 0.18.0 → 0.19.1

package/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +817,9 @@ 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.19.1...HEAD
+[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

@@ -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
 
@@ -366,7 +353,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 +412,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/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/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.
 
@@ -191,31 +191,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
 

package/docs/ARCHITECTURE.md

@@ -246,7 +246,8 @@ snapshot as an output; test, review, and delivery reports carry its digest forwa
 
 `change.breadcrumb` derives the compact current position from state.db. Session,
 edit, resume, and OpenCode lifecycle hooks invoke one bundled read-only reader
-and inject only this breadcrumb, never the intent body,
+and inject it only while state.db proves an active, blocked, or ready workflow,
+never the intent body,
 provider content, or a conversation summary. A changed Git HEAD, task contract, or
 Change semantic authority marks the snapshot stale and permits recompilation through
 `change.context`.
@@ -257,6 +258,14 @@ baseline/change ownership, and transaction boundaries, then persists them. It
 does not call Anthropic, OpenAI, or another model provider and needs no separate
 model API credential.
 
+Plugin installation does not activate a semantic workflow and never edits the
+user's `CLAUDE.md`, `AGENTS.md`, or equivalent durable instructions. Public
+workflows require explicit user invocation. A completed workflow returns
+mechanically allowed transitions and a host-owned recommendation, then stops;
+it never launches the next public workflow. OpenCode realizes this boundary
+with explicit commands backed by private plugin workflow assets, while Claude,
+Codex, and Kimi use their native implicit-invocation controls.
+
 File count, token estimate, and context-share overflow produce warnings, never a
 refusal. The agent may narrow reads, load files lazily, or split a slice when that
 preserves correctness; it must not raise a threshold merely to clear a gate or

package/docs/DECISIONS.md

@@ -70,6 +70,6 @@ release, deployment, or destructive effect.
 - Runtime architecture: [`ARCHITECTURE.md`](./ARCHITECTURE.md)
 - Workflow state and invalidation: [`WORKFLOW-LIFECYCLE.md`](./WORKFLOW-LIFECYCLE.md)
 - Host compatibility: [`RUNTIME-COMPAT-MATRIX.md`](./RUNTIME-COMPAT-MATRIX.md)
-- User handbook projection: [`USER-HANDBOOK-CONTRACT.md`](./USER-HANDBOOK-CONTRACT.md)
+- Plugin and user-instruction boundary: [`PLUGIN-ISOLATION-CONTRACT.md`](./PLUGIN-ISOLATION-CONTRACT.md)
 - MCP interface: [`../spec/mcp-tools.yaml`](../spec/mcp-tools.yaml)
 - Database contract: [`../spec/schemas/state-db.sql`](../spec/schemas/state-db.sql)

package/docs/PLUGIN-ISOLATION-CONTRACT.md

@@ -0,0 +1,54 @@
+# Plugin Isolation Contract
+
+Ultra Builder Pro is an explicitly invoked, removable workflow plugin. Installation
+must not change a user's durable engineering policy or initialize any repository.
+
+## Owned surfaces
+
+An adapter may write only:
+
+- the host's plugin-owned command, skill, worker, hook, and runtime directories;
+- the host registry or manifest entries required to load those assets;
+- the plugin's own provenance and managed-file markers.
+
+The first command allowed to create project authority is `ultra-init`. Once invoked,
+Ultra owns only the repository-local `.ultra/` authority and its generated projections.
+
+## Surfaces Ultra does not own
+
+Install, update, doctor, and uninstall must not create, rewrite, trim, merge, or delete:
+
+- user-level `CLAUDE.md`, `AGENTS.md`, or equivalent instruction files;
+- repository-level instruction files;
+- project source, Git history, remotes, or `.ultra/` data;
+- memory or code-graph provider data.
+
+Existing Ultra marker blocks in a user handbook are legacy user content after this
+contract takes effect. They are not silently removed because the plugin cannot prove
+ownership or preserve unrelated edits. The owner may review and remove them separately.
+
+## Activation
+
+Public Ultra workflows run only after an explicit user command or skill invocation.
+Completion of one workflow may return allowed transitions and a recommendation, but it
+must not start another public workflow.
+
+Host adapters prevent implicit model activation with the strongest native mechanism:
+
+- Claude Code and Kimi Code mark public workflow skills as model-disabled;
+- Codex marks workflow metadata as implicit-invocation-disabled;
+- OpenCode exposes public workflows through commands backed by private plugin assets,
+  not through the model-discoverable skill catalog.
+
+Internal review-rule skills remain available only to their bounded workers.
+
+## Idle behavior
+
+Outside a repository containing `.ultra/state.db`, all Ultra hooks are silent. Inside
+an initialized repository they remain silent unless a DB-authoritative workflow is
+active, blocked, or ready. The sole idle-time enforcement is protection against direct
+writes to generated Ultra projections; the DB remains authoritative.
+
+Installation tests preserve byte-for-byte snapshots of all supported user handbook
+paths. Runtime tests cover explicit activation, idle silence, active recovery, and
+projection protection.

package/docs/ROADMAP.md

@@ -80,7 +80,6 @@ ultra-tools/                ← CLI fallback, migration, and diagnostics
     └── legacy-memory.cjs   (explicit inspect/archive/confirmed prune)
 
 bin/install.js              ← multi-runtime installer
-bin/handbook.js             ← explicit bounded or full host-native handbook sync
 adapters/                   ← native Claude/OpenCode/Codex plugin builders
 skills/                     ← allowlisted Ultra workflows, internal rules, and collab companions
 hooks/                      ← 7 executable workflow hooks + shared Context Spine helper; OpenCode uses native JavaScript hooks
@@ -89,7 +88,7 @@ docs/
 ├── ARCHITECTURE.md              Phase 1 single-page entry point
 ├── WORKFLOW-LIFECYCLE.md        baseline classification + DB transition contract
 ├── AGENT-CONTEXT.md             Phase 3 canonical runtime context contract
-├── USER-HANDBOOK-CONTRACT.md    bounded/full CLAUDE.md / AGENTS.md contract
+├── PLUGIN-ISOLATION-CONTRACT.md install, activation, idle, and ownership contract
 ├── RUNTIME-COMPAT-MATRIX.md     Phase 4 runtime capability matrix
 ├── STATE-DB-ACCESS-POLICY.md    Phase 2 multi-process write contract
 ├── COMMIT-HASH-BACKFILL.md      Phase 2.8 two-commit completion flow

package/docs/RUNTIME-COMPAT-MATRIX.md

@@ -15,10 +15,10 @@ not installed.
 |---|---|---|---|---|
 | 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 |
+| Public Ultra workflows | 12, model invocation disabled | 12 commands backed by private workflow assets | 12, implicit invocation disabled | 12, model invocation disabled |
 | 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 |
+| Automatic workflow bootstrap | N/A | N/A | N/A | N/A |
 | External browser/deploy/framework skills | N/A | N/A | N/A | N/A |
 
 Codex converts workflows into namespaced skills and records eleven legacy
@@ -46,21 +46,17 @@ not presented as nonexistent custom agents.
 
 | Lifecycle | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
 |---|---|---|---|---|
-| Session context/health | FULL, DB-derived Context Spine breadcrumb on native `SessionStart` | FULL, the native JS plugin invokes the same bundled DB breadcrumb reader; health via `system.doctor` | FULL, DB-derived breadcrumb on native `SessionStart` | FULL, DB-derived breadcrumb via session-start skill + hooks |
+| Session context/health | FULL, active-workflow breadcrumb on native `SessionStart` | FULL, native JS plugin injects only an active-workflow breadcrumb; health via `system.doctor` | FULL, active-workflow breadcrumb on native `SessionStart` | FULL, active-workflow breadcrumb via native 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 |
 | Stop lifecycle advisory | FULL, native non-blocking `Stop` | N/A, no equivalent stop event needed | FULL, native non-blocking `Stop` | FULL, native non-blocking `Stop` |
 | 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,
+Health/context, compact, stop, and subagent hooks remain silent unless
+`.ultra/state.db` proves an active, blocked, or ready workflow. Projection
+protection applies to every initialized project because generated projections
+must never become a second authority. No host receives prompt capture, transcript capture,
 observation journaling, session-summary memory, generic command blocking, or
 generic post-edit policy.
 Baseline-adoption and context-budget warnings are injected as advisory context;
@@ -89,20 +85,19 @@ generated launcher recovers the project from the inherited `PWD`, sets
 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
+## 5. User instruction isolation
 
 | 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 apply --runtime claude` | `ubp-handbook apply --runtime opencode` | `ubp-handbook apply --runtime codex` | `ubp-handbook apply --runtime kimi` |
-| Explicit complete-handbook convergence | `--full --confirm TOKEN` | `--full --confirm TOKEN` | `--full --confirm TOKEN` | `--full --confirm TOKEN` |
-| Backup before change | FULL | FULL | FULL | FULL |
+| Writer shipped by Ultra | N/A | N/A | N/A | N/A |
+| Uninstall removes user instructions | no | no | no | no |
 
-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. Full mode is a semantic host rendering,
-not a product-name or path substitution.
+The Kimi plugin installer also does not edit `~/.kimi-code/config.toml`. Durable
+user preferences belong to each host and remain outside Ultra's ownership.
+Legacy Ultra handbook text is not proof of plugin ownership and is never
+silently rewritten or removed.
 
 ## 6. Install, update, and uninstall
 
@@ -151,8 +146,8 @@ records. Uninstall refuses an unmanaged or conflicting root.
   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 bounded and full host
-  rendering, external-provider block preservation, backup, migration, and idempotency.
+- `adapters/_shared/tests/plugin-isolation.test.cjs` and `tests/install.test.cjs`
+  verify the absence of a handbook writer and byte-preservation of all user instruction files.
 - `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

package/hooks/active_task_context.py

@@ -52,7 +52,7 @@ def main() -> None:
     except ContextSpineError as exc:
         print(f"[active_task_context] cannot inspect Context Spine: {exc}", file=sys.stderr)
         breadcrumb = None
-    if breadcrumb and breadcrumb.get("change_id"):
+    if breadcrumb and breadcrumb.get("workflow"):
         print(json.dumps({"hookSpecificOutput": {
             "hookEventName": "PreToolUse",
             "additionalContext": render_breadcrumb(root, breadcrumb),

package/hooks/context_spine.py

@@ -22,7 +22,7 @@ class Breadcrumb(dict):
 
 def find_root(start: Path):
     for root in (start, *start.parents):
-        if (root / ".ultra").is_dir():
+        if (root / ".ultra" / "state.db").is_file():
             return root
     return None
 

package/hooks/health_check.py

@@ -27,6 +27,22 @@ def hook_input() -> dict:
         return {}
 
 
+def has_active_workflow(db_path: Path) -> bool:
+    if not db_path.is_file():
+        return False
+    try:
+        uri = f"file:{db_path}?mode=ro"
+        with sqlite3.connect(uri, uri=True, timeout=1) as conn:
+            row = conn.execute(
+                """SELECT 1 FROM workflow_runs
+                   WHERE status IN ('active', 'blocked', 'ready')
+                   LIMIT 1"""
+            ).fetchone()
+            return row is not None
+    except sqlite3.Error:
+        return False
+
+
 def inspect(root: Path) -> dict:
     db_path = root / ".ultra" / "state.db"
     report = {"status": "healthy", "project": str(root), "checks": {}}
@@ -171,6 +187,9 @@ def main() -> None:
     if root is None:
         print(json.dumps({}))
         return
+    if not has_active_workflow(root / ".ultra" / "state.db"):
+        print(json.dumps({}))
+        return
     report = inspect(root)
     if report["status"] != "healthy":
         print("[Ultra health] " + json.dumps(report, ensure_ascii=False, sort_keys=True), file=sys.stderr)