ultra-builder-pro-cli 0.23.0 → 0.24.0

package/.ultra-template/docs/research/README.md

@@ -49,7 +49,7 @@ copying memory, code-graph payloads, or large source material into Ultra.
 
 ## Completion
 
-Update the affected baseline specification, record the report through `workflow.step`,
-include it in `baseline.record` evidence when material, and record unresolved work in
-the authoritative gap ledger. The final synthesis also binds the three specifications
-and research distillate. Do not create a condensed duplicate of the baseline.
+Update the affected baseline specification, register the report through typed
+`ultra.record`, reference it from the Research Stage Checkpoint, and record unresolved
+work in the authoritative gap ledger. The final synthesis also binds the baseline
+specifications and research distillate. Do not create a condensed duplicate.

package/CHANGELOG.md

@@ -7,6 +7,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.24.0] — 2026-07-30
+
+### Added
+
+- Added normalized Decision Records, reversible Stage Checkpoints, bounded Context
+  Envelopes, and immutable Worker Packets as the shared evidence and handoff model
+  across Skills, Hooks, agents, SQLite, and tracked `.ultra` artifacts.
+- Added a native Grok Build plugin so Claude Code, Codex, OpenCode, Kimi Code, and
+  Grok Build share the same eleven explicit workflows and seven-tool MCP kernel.
+- Added schema 22 backup-first migration and real-history compatibility for v4.4,
+  v4.5, v0.22, and v0.23 state and team-ledger formats.
+- Added packaged `better-sqlite3` provenance, platform and Node ABI verification,
+  and durable Doctor and archive workers for every supported host.
+
+### Changed
+
+- Completed the MCP boundary reduction: Skills own adaptive semantic procedure;
+  MCP owns persistence, identity, transactions, leases, paths, recovery, and
+  irreversible safety; Hooks only observe or inject bounded context; agents consume
+  immutable Worker Packets without writing SQLite authority.
+- Folded Plan artifact publication into the accepted Plan checkpoint so a later
+  export cannot invalidate its own authority.
+- Replaced semantic supervisor failures with mutable diagnostics and repairable
+  drafts. Only corruption, unsafe paths, concurrency conflicts, permission failures,
+  and irreversible external effects remain hard blockers.
+- Made `ultra.context`, `ultra.sync`, and `ultra.doctor` own their inspection and
+  repair preflight so an older valid ledger cannot block the tools required to
+  migrate it.
+- Reduced packaged and documented MCP contracts to the exact seven public tools;
+  removed the retired fine-grained schemas, fixtures, and command bypasses.
+
+### Fixed
+
+- Fixed accepted or stale workflow runs becoming permanently self-locked after an
+  artifact changed, and made reversible stages reopenable without rewriting
+  immutable accepted history.
+- Fixed v0.23 team ledgers using `research_run_id` being rejected under the newer
+  `research_checkpoint_id` digest contract.
+- Fixed native SQLite drivers and Doctor workers being absent or unresolved in
+  installed plugins.
+- Fixed session acquisition, archive recovery, Context identity, and Worker Packet
+  cleanup paths leaving partial authority after failure.
+- Fixed installed interaction guidance failing to render each host's native question
+  surface while keeping canonical Skills host-neutral.
+
 ## [0.23.0] — 2026-07-30
 
 ### Added

package/README.md

@@ -2,8 +2,8 @@
 
 **An adaptive delivery harness for AI coding agents.**
 
-Ultra Builder Pro helps Claude Code, Codex, OpenCode, and Kimi Code carry a
-software project from an unclear request to a verified, recoverable delivery.
+Ultra Builder Pro helps Claude Code, Codex, OpenCode, Kimi Code, and Grok Build
+carry a software project from an unclear request to a verified, recoverable delivery.
 It keeps the user and the agent aligned, preserves project authority across
 sessions, and prevents specifications from quietly drifting away from the code.
 
@@ -44,7 +44,7 @@ Ultra Builder Pro addresses those gaps with four ideas:
    and asks the user only for material intent, scope, risk, or authorization
    decisions—normally one dependent decision at a time.
 3. **Durable project authority.** `.ultra/.runtime/state.db` records checkout-local
-   lifecycle, decisions, workflows, evidence digests, sessions, incidents, and
+   lifecycle facts, decisions, checkpoints, evidence digests, sessions, incidents, and
    recovery state across host sessions. Tracked semantic artifacts plus the
    MCP-published `.ultra/tasks/tasks.json` checkpoint carry reviewed project intent
    across Git checkouts without committing SQLite, leases, or telemetry.
@@ -65,13 +65,13 @@ flowchart TB
     U["User<br/>goals, acceptance, trade-offs, risk, and external authorization"]
 
     subgraph HOST["Supported coding host"]
-        UI["Host-native interaction<br/>Claude Code / Codex / OpenCode / Kimi Code"]
+        UI["Host-native interaction<br/>Claude Code / Codex / OpenCode / Kimi Code / Grok Build"]
         MODEL["Host agent<br/>inspect, recommend, implement, test, and review"]
         ADAPTER["Host adapter<br/>native questions, commands, tools, and lifecycle wiring"]
     end
 
     SKILLS["Eleven explicit Ultra Skills<br/>init / research / think / change / plan / dev<br/>test / review / deliver / status / doctor"]
-    MCP["Ultra MCP safety kernel<br/>7 public tools; 60 hidden compatibility operations"]
+    MCP["Ultra MCP safety kernel<br/>exactly 7 public tools"]
     DB[(".ultra/.runtime/state.db<br/>SQLite lifecycle and index authority")]
     LEDGER[".ultra/tasks/tasks.json<br/>Git team checkpoint for portable baseline, Change, and task state"]
     VIEWS[".ultra/.runtime/projections<br/>checkout-local generated views"]
@@ -103,7 +103,7 @@ The responsibility split is deliberate:
 |---|---|
 | **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 checkpoints, evidence references, digests, team sync, leases, archive transactions, and mechanical recovery |
+| **Ultra MCP** | Structure validation, durable checkpoints, evidence references, digests, team sync, leases, archive transactions, and mechanical recovery; never semantic route selection |
 | **Host adapter** | Native Skill discovery, user questions, tool invocation, installation, and runtime wiring |
 | **Hooks** | Fast lifecycle observation, current breadcrumb injection, and protection of MCP-owned checkpoint and generated projection paths |
 
@@ -126,10 +126,9 @@ The public model-facing surface is intentionally small:
 | `ultra.archive` | Converge and archive through the recoverable filesystem/DB boundary |
 | `ultra.doctor` | Inspect or repair mechanical health, backup first |
 
-The 0.22 fine-grained tools remain callable but undiscoverable for one compatibility
-release. Skills and new sessions use only the seven tools above. Workflow prose stays
-in Skills, model judgment stays with the host, and SQLite records what happened rather
-than deciding what the model is allowed to think next.
+Retired fine-grained operation names are neither discoverable nor callable. Workflow
+prose stays in Skills, model judgment stays with the host, and SQLite records what
+happened rather than deciding what the model is allowed to think next.
 
 The enforcement gradient is:
 
@@ -165,8 +164,9 @@ and effects—not chain-of-thought, raw prompts, transcripts, or UI receipts.
 
 ## What you get
 
-- Native plugins for **Claude Code**, **OpenCode**, **Codex**, and **Kimi Code**.
-- One workflow vocabulary across all four hosts.
+- Native plugins for **Claude Code**, **OpenCode**, **Codex**, **Kimi Code**, and
+  **Grok Build**.
+- One workflow vocabulary across all five hosts.
 - Deterministic initialization for new, existing, monorepo, and older Ultra
   projects.
 - Evidence-backed greenfield research and brownfield adoption.
@@ -218,6 +218,7 @@ npx --yes ultra-builder-pro-cli@latest --claude --global
 npx --yes ultra-builder-pro-cli@latest --opencode --global
 npx --yes ultra-builder-pro-cli@latest --codex --global
 npx --yes ultra-builder-pro-cli@latest --kimi --global
+npx --yes ultra-builder-pro-cli@latest --grok --global
 ```
 
 Use `--local` instead of `--global` to install into the current project's host
@@ -454,7 +455,7 @@ health without selecting product intent.
 ```text
 .ultra/
   .runtime/                # local mutable state; ignored by Git
-    state.db               # lifecycle, index, transition, and freshness authority
+    state.db               # facts, indexes, checkpoints, leases, CAS, and recovery
     checkpoint.json        # advisory recovery projection
     projections/           # generated local task and task-context views
     backups/               # verified migration and recovery snapshots
@@ -463,17 +464,18 @@ health without selecting product intent.
     worktrees/             # registered local Git worktrees
     telemetry/             # local operational telemetry
   specs/                   # digest-bound product and architecture baseline
+  decisions/baseline/      # normalized accepted baseline decisions
   changes/
     active/<id>/           # all current Change semantics and evidence
       intent.md            # accepted Change Contract
-      findings.md          # durable Change findings
+      decisions/           # normalized accepted Change decisions
       progress.md          # generated human-readable projection
       research/            # Change-only findings and research reports
       delta/               # typed baseline overlay and semantic payloads
       documentation/       # documentation overlay and reconciliation evidence
       plan.json            # machine-readable task topology
       plan.md              # deterministic human plan projection
-      contexts/            # immutable role/task context snapshots
+      contexts/            # immutable canonical Context Envelopes
       test/                # Change-scoped test reports
       review/              # Change-scoped review workers and summary
       delivery/            # Change-scoped delivery evidence
@@ -585,8 +587,9 @@ host's existing model session.
 - **A generated view disagrees with MCP:** trust `.ultra/.runtime/state.db`; never edit
   `.ultra/.runtime/projections/` by hand.
 - **A draft checkpoint is rejected:** use `ultra-status` to read the exact warnings
-  and blockers, fix the same mutable draft, and retry. Use `workflow.abandon` through
-  `ultra.record` only when intentionally cancelling the attempt.
+  and blockers, fix the same mutable draft, and retry. If the attempt is no longer
+  relevant, leave it as history and open a new draft revision; no hidden workflow
+  state must be cancelled first.
 - **Kimi reports a native-module ABI error:** ensure an external Node.js 22+
   executable is available on `PATH`; the generated Kimi MCP launcher uses
   `env node`.
@@ -616,7 +619,7 @@ and `test:rest`.
 |---|---|
 | [Architecture](./docs/ARCHITECTURE.md) | Components, authority boundaries, and live integration paths |
 | [Workflow Lifecycle](./docs/WORKFLOW-LIFECYCLE.md) | Command ownership, transitions, invalidation, recovery, and convergence |
-| [Runtime Compatibility Matrix](./docs/RUNTIME-COMPAT-MATRIX.md) | Claude Code, OpenCode, Codex, and Kimi presentation details |
+| [Runtime Compatibility Matrix](./docs/RUNTIME-COMPAT-MATRIX.md) | Claude Code, OpenCode, Codex, Kimi Code, and Grok Build 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 |
 | [Plugin Isolation Contract](./docs/PLUGIN-ISOLATION-CONTRACT.md) | Plugin ownership, explicit activation, idle behavior, and user-instruction isolation |

package/adapters/_shared/codex-assets.cjs

@@ -30,44 +30,6 @@ const {
 
 const PLUGIN_NAME = 'ultra-builder-pro';
 const MANAGED_MARKER = 'Managed by Ultra Builder Pro Codex adapter.';
-const CODEX_NATIVE_MCP_REPLACEMENTS = Object.freeze({
-  'review.run': {
-    surface: 'native_custom_agents',
-    replacement: '$ultra-builder-pro:ultra-review with the installed review-* agents',
-  },
-  'review.verdict': {
-    surface: 'native_custom_agents',
-    replacement: 'review-coordinator synthesis using the Ultra unified review artifact',
-  },
-  'impact.radius': {
-    surface: 'codex_code_discovery',
-    replacement: 'indexed code graph tools when current, otherwise targeted repository reads',
-  },
-  'impact.changes': {
-    surface: 'codex_code_discovery',
-    replacement: 'git diff plus indexed code graph tools when current',
-  },
-  'impact.dependents': {
-    surface: 'codex_code_discovery',
-    replacement: 'indexed caller/dependency tracing when current, otherwise targeted repository search',
-  },
-  'skill.resolve': {
-    surface: 'plugin_skill_discovery',
-    replacement: 'Codex plugin skill discovery with explicit $ultra-builder-pro:<skill> invocation',
-  },
-  'skill.manifest': {
-    surface: 'plugin_skill_discovery',
-    replacement: 'the installed plugin skill SKILL.md and agents/openai.yaml contract',
-  },
-  'ask.question': {
-    surface: 'request_user_input',
-    replacement: 'use request_user_input when available, otherwise ask one concise direct question',
-  },
-  'ask.menu': {
-    surface: 'request_user_input',
-    replacement: 'use request_user_input when available, otherwise present one concise direct choice',
-  },
-});
 const COMMAND_NAMES = Object.freeze(CORE_PUBLIC_SKILLS.filter((name) => name !== 'ultra-review'));
 const SKILL_REFERENCE_NAMES = Object.freeze([
   ...COMMAND_NAMES,
@@ -77,6 +39,11 @@ const SKILL_REFERENCE_NAMES = Object.freeze([
 ]);
 const CODEX_PRIMARY_SKILLS = new Set([...COMMAND_NAMES, 'ultra-review']);
 const TEXT_EXTENSIONS = new Set(['.md', '.json', '.py', '.sh', '.txt', '.yaml', '.yml']);
+const NATIVE_PACKAGES = Object.freeze([
+  'better-sqlite3',
+  'bindings',
+  'file-uri-to-path',
+]);
 
 function titleCase(name) {
   const special = { 'cc-collab': 'Claude Code Collaboration' };
@@ -273,7 +240,7 @@ function buildHooksManifest(pluginRoot) {
   };
 }
 
-function copyHooks(repoRoot, pluginRoot) {
+function copyHooks(repoRoot, pluginRoot, publishedRoot = pluginRoot) {
   const sourceRoot = path.join(repoRoot, 'hooks');
   const targetRoot = path.join(pluginRoot, 'hooks');
   ensureDir(targetRoot);
@@ -287,7 +254,7 @@ function copyHooks(repoRoot, pluginRoot) {
   );
   writeAtomic(
     path.join(targetRoot, 'hooks.json'),
-    JSON.stringify(buildHooksManifest(pluginRoot), null, 2) + '\n',
+    JSON.stringify(buildHooksManifest(publishedRoot), null, 2) + '\n',
   );
 }
 
@@ -322,6 +289,8 @@ function buildMcpRuntime(repoRoot, pluginRoot, { runtime = 'codex' } = {}) {
       buildRoot,
       '--no-cache',
       '--quiet',
+      '-e',
+      'better-sqlite3',
     ], {
       cwd: repoRoot,
       encoding: 'utf8',
@@ -347,6 +316,8 @@ function buildMcpRuntime(repoRoot, pluginRoot, { runtime = 'codex' } = {}) {
       cliBuildRoot,
       '--no-cache',
       '--quiet',
+      '-e',
+      'better-sqlite3',
     ], {
       cwd: repoRoot,
       encoding: 'utf8',
@@ -386,6 +357,8 @@ function buildMcpRuntime(repoRoot, pluginRoot, { runtime = 'codex' } = {}) {
         workerBuildRoot,
         '--no-cache',
         '--quiet',
+        '-e',
+        'better-sqlite3',
       ], {
         cwd: repoRoot,
         encoding: 'utf8',
@@ -416,6 +389,52 @@ function buildMcpRuntime(repoRoot, pluginRoot, { runtime = 'codex' } = {}) {
     fs.copyFileSync(sourceFile, path.join(runtimeRoot, supportFile));
   }
 
+  const nodeModulesRoot = path.join(runtimeRoot, 'node_modules');
+  for (const packageName of NATIVE_PACKAGES) {
+    let packageFile;
+    try {
+      packageFile = require.resolve(`${packageName}/package.json`, { paths: [repoRoot] });
+    } catch (error) {
+      throw new Error(`Ultra native runtime dependency ${packageName} is unavailable: ${error.message}`);
+    }
+    copyTree(
+      path.dirname(packageFile),
+      path.join(nodeModulesRoot, packageName),
+    );
+  }
+  const nativeRelative = path.join(
+    'node_modules',
+    'better-sqlite3',
+    'build',
+    'Release',
+    'better_sqlite3.node',
+  );
+  const nativeFile = path.join(runtimeRoot, nativeRelative);
+  if (!fs.existsSync(nativeFile) || !fs.statSync(nativeFile).isFile()) {
+    throw new Error(`Ultra native SQLite driver is missing after staging: ${nativeFile}`);
+  }
+  const betterSqlitePackage = JSON.parse(fs.readFileSync(
+    path.join(nodeModulesRoot, 'better-sqlite3', 'package.json'),
+    'utf8',
+  ));
+  writeAtomic(path.join(runtimeRoot, 'native-runtime.json'), JSON.stringify({
+    schema_version: 1,
+    platform: process.platform,
+    arch: process.arch,
+    modules: process.versions.modules,
+    node_version: process.versions.node,
+    package: {
+      name: 'better-sqlite3',
+      version: betterSqlitePackage.version,
+    },
+    native_module: nativeRelative.split(path.sep).join('/'),
+    native_sha256: crypto.createHash('sha256').update(fs.readFileSync(nativeFile)).digest('hex'),
+  }, null, 2) + '\n');
+  fs.copyFileSync(
+    path.join(repoRoot, 'adapters', '_shared', 'runtime-native.cjs'),
+    path.join(runtimeRoot, 'runtime-native.cjs'),
+  );
+
   const runtimeBootstrap = runtime === 'kimi' ? `
 const fs = require('node:fs');
 const pluginRoot = path.resolve(__dirname, '..');
@@ -443,10 +462,12 @@ if (!process.env.UBP_ROOT_DIR) {
   const launcher = `'use strict';
 
 const path = require('node:path');
+const { inspectRuntimeNative } = require('./runtime-native.cjs');
 
 process.env.UBP_RUNTIME_ROOT = path.resolve(__dirname, '..');
 ${runtimeBootstrap}
 
+inspectRuntimeNative(__dirname);
 const { main } = require('./index.cjs');
 
 main().catch((error) => {
@@ -456,8 +477,8 @@ main().catch((error) => {
 `;
   writeAtomic(path.join(runtimeRoot, 'launch.cjs'), launcher);
   fs.copyFileSync(
-    path.join(repoRoot, 'mcp-server', 'breadcrumb.cjs'),
-    path.join(runtimeRoot, 'breadcrumb.cjs'),
+    path.join(repoRoot, 'mcp-server', 'hook-context.cjs'),
+    path.join(runtimeRoot, 'hook-context.cjs'),
   );
   fs.copyFileSync(
     path.join(repoRoot, 'mcp-server', 'hook-event.cjs'),
@@ -470,11 +491,7 @@ main().catch((error) => {
 
   const sourceToolsFile = path.join(repoRoot, 'spec', 'mcp-tools.yaml');
   const upstreamManifest = yaml.load(fs.readFileSync(sourceToolsFile, 'utf8'));
-  const {
-    LEGACY_TOOLS,
-    PUBLIC_TOOLS,
-    REGISTERED_TOOLS,
-  } = require(path.join(repoRoot, 'mcp-server', 'server.cjs'));
+  const { REGISTERED_TOOLS } = require(path.join(repoRoot, 'mcp-server', 'server.cjs'));
   const registered = new Set(REGISTERED_TOOLS);
   const liveFamilies = new Set(
     upstreamManifest.tools.filter((tool) => registered.has(tool.name)).map((tool) => tool.family),
@@ -495,15 +512,6 @@ main().catch((error) => {
     path.join(specRoot, 'interaction-contract.json'),
     JSON.stringify(interactionContract(runtime), null, 2) + '\n',
   );
-  if (runtime === 'codex') {
-    fs.copyFileSync(sourceToolsFile, path.join(specRoot, 'upstream-mcp-tools.yaml'));
-    writeAtomic(path.join(specRoot, 'codex-capability-map.json'), JSON.stringify({
-      runtime: 'codex',
-      live_mcp_tools: PUBLIC_TOOLS,
-      compatibility_mcp_tools: LEGACY_TOOLS,
-      codex_native_replacements: CODEX_NATIVE_MCP_REPLACEMENTS,
-    }, null, 2) + '\n');
-  }
   const sourceSchema = path.join(repoRoot, 'spec', 'schemas', 'state-db.sql');
   const targetSchema = path.join(specRoot, 'schemas', 'state-db.sql');
   ensureDir(path.dirname(targetSchema));
@@ -521,9 +529,49 @@ main().catch((error) => {
     launcher: path.join(runtimeRoot, 'launch.cjs'),
     bundle: path.join(runtimeRoot, 'index.cjs'),
     ultraTools: path.join(runtimeRoot, 'ultra-tools.cjs'),
+    nativeManifest: path.join(runtimeRoot, 'native-runtime.json'),
   };
 }
 
+function mcpCommand(launcher) {
+  if (process.platform === 'win32') {
+    return { command: 'node.exe', args: [launcher] };
+  }
+  return { command: '/usr/bin/env', args: ['node', launcher] };
+}
+
+function inspectInstalledRuntime(runtimeRoot) {
+  const report = {
+    status: 'healthy',
+    checks: {},
+    issues: [],
+  };
+  try {
+    const detail = require(path.join(runtimeRoot, 'runtime-native.cjs'))
+      .inspectRuntimeNative(runtimeRoot);
+    report.checks.native_runtime = { status: 'pass', ...detail };
+  } catch (error) {
+    report.status = 'degraded';
+    report.checks.native_runtime = { status: 'fail' };
+    report.issues.push({
+      code: error.code || 'RUNTIME_NATIVE_MISSING',
+      message: error.message,
+      ...(error.details || {}),
+    });
+  }
+  return report;
+}
+
+function applyNativeDoctor(report, runtimeRoot) {
+  const native = inspectInstalledRuntime(runtimeRoot);
+  report.checks = { ...(report.checks || {}), ...native.checks };
+  report.issues = [...(report.issues || []), ...native.issues];
+  if (report.status !== 'missing') {
+    report.status = report.issues.length === 0 ? 'healthy' : 'degraded';
+  }
+  return report;
+}
+
 function pluginContentHash(pluginRoot, baseVersion) {
   const hash = crypto.createHash('sha256');
   hash.update(baseVersion);
@@ -535,13 +583,14 @@ function pluginContentHash(pluginRoot, baseVersion) {
   return hash.digest('hex').slice(0, 12);
 }
 
-function buildPlugin({ repoRoot, pluginRoot }) {
+function buildPlugin({ repoRoot, pluginRoot, publishedRoot = pluginRoot }) {
   if (fs.existsSync(pluginRoot)) {
     const marker = path.join(pluginRoot, '.ubp-managed');
-    if (!fs.existsSync(marker)) {
+    const entries = fs.readdirSync(pluginRoot);
+    if (entries.length > 0 && !fs.existsSync(marker)) {
       throw new Error(`refusing to replace unmanaged plugin directory: ${pluginRoot}`);
     }
-    removeTree(pluginRoot);
+    if (entries.length > 0) removeTree(pluginRoot);
   }
   ensureDir(pluginRoot);
 
@@ -555,14 +604,18 @@ function buildPlugin({ repoRoot, pluginRoot }) {
     installedSkills.push(name);
   }
 
-  copyHooks(repoRoot, pluginRoot);
+  copyHooks(repoRoot, pluginRoot, publishedRoot);
   const mcpRuntime = buildMcpRuntime(repoRoot, pluginRoot);
+  const command = mcpCommand(path.join(
+    publishedRoot,
+    path.relative(pluginRoot, mcpRuntime.launcher),
+  ));
   writeAtomic(path.join(pluginRoot, '.mcp.json'), JSON.stringify({
     mcpServers: {
       [PLUGIN_NAME]: {
         type: 'stdio',
-        command: process.execPath,
-        args: [mcpRuntime.launcher],
+        command: command.command,
+        args: command.args,
       },
     },
   }, null, 2) + '\n');
@@ -576,7 +629,7 @@ function buildPlugin({ repoRoot, pluginRoot }) {
   const manifest = {
     name: PLUGIN_NAME,
     version,
-    description: 'Codex-native Ultra Builder Pro workflows, agents, hooks, and MCP task state.',
+    description: 'Codex-native Ultra Builder Pro workflows with a persistent safety kernel.',
     author: { name: typeof pkg.author === 'string' ? pkg.author : 'Ultra Builder Pro contributors' },
     homepage: pkg.homepage,
     repository: 'https://github.com/rocky2431/ultra-builder-pro-cli',
@@ -587,7 +640,7 @@ function buildPlugin({ repoRoot, pluginRoot }) {
     interface: {
       displayName: 'Ultra Builder Pro',
       shortDescription: 'Codex-native engineering workflows and verification gates.',
-      longDescription: 'Complete Codex adaptation of Ultra Builder Pro skills, command workflows, custom agents, lifecycle hooks, and project-local MCP state.',
+      longDescription: 'Complete Codex adaptation of Ultra Builder Pro skills, command workflows, custom agents, lifecycle hooks, and a project-local persistence and safety kernel.',
       developerName: typeof pkg.author === 'string' ? pkg.author : 'Ultra Builder Pro contributors',
       category: 'Developer Tools',
       capabilities: ['Interactive', 'Write'],
@@ -602,7 +655,7 @@ function buildPlugin({ repoRoot, pluginRoot }) {
   };
   writeAtomic(path.join(pluginRoot, '.codex-plugin', 'plugin.json'), JSON.stringify(manifest, null, 2) + '\n');
   writeAtomic(path.join(pluginRoot, '.ubp-managed'), JSON.stringify({ source: 'ubp', adapter: 'codex', version }, null, 2) + '\n');
-  return { root: pluginRoot, version, skills: installedSkills.sort() };
+  return { root: publishedRoot, version, skills: installedSkills.sort() };
 }
 
 function tomlMultiline(value) {
@@ -663,6 +716,9 @@ module.exports = {
   buildCommandMap,
   buildHooksManifest,
   buildMcpRuntime,
+  inspectInstalledRuntime,
+  applyNativeDoctor,
+  mcpCommand,
   buildPlugin,
   buildAgentToml,
   installAgents,

package/adapters/_shared/interaction-contract.cjs

@@ -23,10 +23,15 @@ const SURFACES = Object.freeze({
     fallback: 'direct_user_interaction',
     availability: 'interactive_non_auto_mode',
   }),
+  grok: Object.freeze({
+    primary: 'AskUserQuestion',
+    fallback: 'direct_user_interaction',
+    availability: 'interactive_session',
+  }),
 });
 
 const GENERIC_QUESTION_GUIDANCE =
-  /Use the host-native structured question surface declared by the installed interaction\s+contract(?: when it exists)?\./g;
+  /Use the host-native (?:structured )?question surface declared by the installed interaction\s+contract(?: when it exists)?(?:;?\s+prefer its structured form when the host exposes one)?\./g;
 
 function interactionContract(runtime) {
   const question = SURFACES[runtime];
@@ -106,6 +111,7 @@ function interactionPrompt(runtime) {
     codex: 'Codex',
     opencode: 'OpenCode',
     kimi: 'Kimi Code',
+    grok: 'Grok Build',
   }[runtime];
   const primary = runtime === 'opencode' ? `\`${surface.primary}\`` : surface.primary;
   return `Use ${host} ${primary} when ${surface.availability.replaceAll('_', ' ')} permits it.`;

package/adapters/_shared/provenance.cjs

@@ -187,7 +187,8 @@ function assetRefsForTree(rootName, root, { exclude = [] } = {}) {
 function writeProvenance({
   file, adapter, packageInfo, repository, sourceCommit: commit = null,
   sourceDirty: dirty = null, sourceWorktreeDigest: worktreeDigest = null,
-  roots: inputRoots, assets: inputAssets, contracts: inputContracts = {},
+  roots: inputRoots, assetRoots: inputAssetRoots = inputRoots,
+  assets: inputAssets, contracts: inputContracts = {},
 }) {
   if (!file || !adapter || !packageInfo?.name || !packageInfo?.version || !repository) {
     throw new Error('provenance file, adapter, package, version, and repository are required');
@@ -199,9 +200,13 @@ function writeProvenance({
     throw new Error('provenance source worktree digest must be a SHA-256 digest or null');
   }
   const roots = normalizeRoots(inputRoots);
+  const assetRoots = normalizeRoots(inputAssetRoots);
+  for (const root of Object.keys(roots)) {
+    if (!assetRoots[root]) throw new Error(`missing provenance asset root: ${root}`);
+  }
   const refs = normalizeAssetRefs(inputAssets, roots);
   const assets = refs.map((ref) => {
-    const { target } = resolveRef(roots, ref);
+    const { target } = resolveRef(assetRoots, ref);
     const stat = fs.statSync(target);
     if (!stat.isFile()) throw new Error(`provenance asset is not a file: ${target}`);
     return { ...ref, size_bytes: stat.size, sha256: hashFile(target) };

package/adapters/_shared/runtime-assets.cjs

@@ -56,13 +56,14 @@ const INTERNAL_AGENT_SKILLS = Object.freeze([
   'testing-rules',
 ]);
 
-const SUPPORTED_RUNTIMES = Object.freeze(['claude', 'opencode', 'codex', 'kimi']);
+const SUPPORTED_RUNTIMES = Object.freeze(['claude', 'opencode', 'codex', 'kimi', 'grok']);
 
 const COLLAB_SKILLS_BY_RUNTIME = Object.freeze({
   claude: Object.freeze(['codex-collab', 'ultra-verify']),
   codex: Object.freeze(['cc-collab', 'ultra-verify']),
   opencode: Object.freeze(['cc-collab', 'codex-collab', 'ultra-verify']),
   kimi: Object.freeze(['cc-collab', 'codex-collab', 'ultra-verify']),
+  grok: Object.freeze(['cc-collab', 'codex-collab', 'ultra-verify']),
 });
 
 const MCP_DEPENDENT_SKILLS = Object.freeze([
@@ -80,7 +81,7 @@ const MCP_DEPENDENT_SKILLS = Object.freeze([
 
 const WORKFLOW_HOOK_FILES = Object.freeze([
   'active_task_context.py',
-  'context_spine.py',
+  'context_envelope.py',
   'health_check.py',
   'pre_stop_check.py',
   'runtime_paths.py',