ultra-builder-pro-cli 0.15.0 → 0.17.0

package/.ultra-template/specs/research-distillate.md

@@ -8,7 +8,7 @@ specifications' prose.
 - Baseline or change id:
 - Research workflow id and mode:
 - Repository revision:
-- Completed step set:
+- Coverage dispositions and selected evidence work:
 
 ## Observed
 
@@ -24,7 +24,7 @@ specifications' prose.
 
 ## Unknowns
 
-| Unknown or gap id | Blocking | Owner or next action |
+| Unknown or gap id | Blocking | Owner and revisit condition |
 |---|---|---|
 | | | |
 
@@ -45,4 +45,5 @@ specifications' prose.
 - Accepted scope and posture:
 - Required references:
 - Blocking gaps:
-- Exact next route:
+- Allowed transitions:
+- Host recommendation and rationale:

package/CHANGELOG.md

@@ -7,6 +7,124 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.0] — 2026-07-24
+
+### Added
+
+- Added deterministic Git bootstrap for initialization and resume, including
+  explicit `auto`, `initialize`, and `skip` modes, persisted unborn-HEAD state,
+  and an owner-authorized first-checkpoint gate.
+- Added a source-backed compatibility crosswalk against the original
+  `rocky2431/ultra-builder-pro` workflow and a shell-free `execute-plan`
+  consumer for current completed-plan dependency waves.
+- Added schema 18 adaptive transition state, migration of active legacy
+  init/change/plan/deliver runs, Context Manifest v3 Change-authority digests,
+  and one host-specific interaction contract for every supported runtime.
+- Added research coverage dispositions (`execute`, `verify_existing`, `reuse`,
+  `not_applicable`, and accepted `deferred`) and risk-selected verification
+  profiles with rationale for every excluded dimension.
+
+### Changed
+
+- Changed plan execution into a resumable wave state machine. A wave pauses
+  until its DB tasks converge, later dependencies remain pending, and reruns
+  skip completed work.
+- Changed MCP session spawning to create the single authoritative Git worktree
+  and session record. Session close now preserves work by default, and
+  change-owned auto-merge requires current dev and review evidence.
+- Changed session worktrees to bind their ignored `.ultra` entry to the central
+  authority and pass non-overridable DB, checkout, and authority-root paths to
+  explicit workers.
+- Changed initialization to complete after classification, local Git/scaffold
+  setup, and read-back verification. It never starts research implicitly;
+  baseline research begins only through an explicit invocation.
+- Changed the workflow from a canonical next-action pipeline to an adaptive
+  capability graph. MCP exposes valid alternatives and unique hard-recovery
+  transitions; the active host owns semantic recommendations and native user
+  interaction.
+- Changed change capture to end after the accepted intent contract, made plan
+  approval conditional on a material owner decision, selected test/review work
+  by risk, and limited Ultra delivery to local convergence and archive.
+
+### Fixed
+
+- Fixed process exit zero, worker spawn errors, and daemon failures bypassing
+  task gates or losing session-linked failure and circuit-breaker evidence.
+- Fixed daemon dispatch of stale tasks, unresolved dependencies, or overlapping
+  declared files, and made explicit takeover terminate the prior worker before
+  replacing its lease.
+- Fixed initialization resume leaving corrected metadata or projections behind
+  after a late failure; DB state, generated projections, and newly bootstrapped
+  Git now roll back together.
+- Fixed cleanup paths that could remove uncommitted or unintegrated worktrees,
+  and fixed dependency waves that could start before prior task convergence.
+- Fixed change-owned auto-merge trusting task status alone; integration now
+  requires the exact completion commit, ready dev evidence, and current task review.
+- Fixed `execute-plan` accepting empty, cyclic, duplicate-task, stale, or
+  incomplete change plans. Change-owned execution now requires the exact healthy
+  completed plan workflow and current DB task graph.
+- Fixed direct MCP and daemon session creation bypassing the plan workflow.
+  Admission and spawn now share the same current task-contract, dependency, and
+  staleness gate before takeover or worktree mutation.
+- Fixed plan-authority drift between wave selection and spawn being counted as a
+  worker failure, and fixed isolated workers creating a second project DB.
+- Fixed an isolated worker recursively spawning, taking over, or prematurely
+  closing its parent-owned session; the supervising process now remains the only
+  transport-settlement authority.
+- Fixed late resume failure after a schema upgrade restoring the migrated
+  intermediate DB instead of the exact pre-migration backup.
+- Fixed the directory-only `.ultra/` Git ignore form failing to protect an
+  authority symlink from `git add -A`; fresh initialization uses the symlink-safe
+  `.ultra` rule, while legacy repositories receive a repository-local
+  `info/exclude` rule without changing their tracked baseline.
+- Fixed semantic `change.update` operations leaving derived tasks and compiled
+  contexts apparently current. A changed intent contract now marks tasks stale,
+  invalidates Context v3, and records the exact invalidation evidence.
+- Fixed stale tasks remaining usable through plan completion, dev startup,
+  verification, delivery, or orchestrator admission after semantic invalidation.
+- Fixed marker-only task reconciliation bypassing semantic invalidation. Clearing
+  `stale` now requires a complete execution-contract rebind and records the current
+  Change authority digest.
+- Fixed review convergence accepting incomplete or fabricated worker provenance;
+  every specialist is now selected or skipped with rationale, and completed workers
+  must exactly match persisted specialist artifacts.
+- Fixed MCP workflow contracts omitting public freshness, recovery, review, testing,
+  and delivery failure codes needed by host adapters.
+- Fixed runtime specification templates and workflow prompts retaining rigid-route
+  wording or omitting durable step and decision-tool handoffs.
+
+## [0.16.0] — 2026-07-23
+
+### Added
+
+- Added schema 16 durable decision threads and items with exactly one current
+  question, normalized owner answers, explicit reversible delegation, consequence-
+  bearing deferral, supersession history, and artifact-bound checkpoints.
+- Added nine `decision.*` MCP contracts, CLI mappings, events, valid/invalid contract
+  fixtures, status/breadcrumb recovery, doctor health checks, and workflow gates.
+- Added one canonical progressive-disclosure decision protocol shared by init,
+  research, thinking, change, and planning without copying questionnaires into each
+  Skill.
+
+### Changed
+
+- Changed research to preserve all seventeen semantic steps as an internal coverage
+  contract while exposing only the current owner decision or compact checkpoint.
+- Changed change and plan formation to inspect facts autonomously, present one
+  evidence-backed choice at a time, stop for the owner, and reuse one approved
+  checkpoint instead of requesting equivalent confirmations.
+- Changed dev, test, review, deliver, status, doctor, user handbooks, and lifecycle
+  documentation to recover through the same decision authority and exact next route.
+
+### Fixed
+
+- Prevented a decision thread for one change from blocking unrelated changes on the
+  same baseline while preserving baseline-only and matching workflow gates.
+- Prevented workflow steps or completion from advancing on an open, blocking-deferred,
+  checkpoint-ready, stale, or superseded owner decision.
+- Prevented prompt transcripts, static question queues, large research dumps, and
+  repeated owner approvals from becoming project authority.
+
 ## [0.15.0] — 2026-07-22
 
 ### Added
@@ -624,7 +742,8 @@ 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.15.0...HEAD
+[Unreleased]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.16.0...HEAD
+[0.16.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.15.0...v0.16.0
 [0.15.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.14.0...v0.15.0
 [0.14.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.13.0...v0.14.0
 [0.13.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.12.1...v0.13.0

package/README.md

@@ -3,12 +3,12 @@
 Multi-runtime plugin suite + autonomous coding factory for the Ultra Builder Pro
 agent engineering system. It ships native plugins for **Claude Code · OpenCode ·
 Codex · Kimi Code** and orchestrates PRD →
-dependency graph → parallel session execution → auto-merge with a single
-authoritative `.ultra/state.db`.
+dependency graph → resumable dependency-wave execution → convergence-gated
+integration with a single authoritative `.ultra/state.db`.
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/version-0.15.0-blue)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.16.0-blue)](./CHANGELOG.md)
 [![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](#verification)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![Node](https://img.shields.io/badge/node-%E2%89%A522-informational)](./package.json)
@@ -25,20 +25,31 @@ authoritative `.ultra/state.db`.
   Install and uninstall are symmetric on every supported host; `ubp --doctor`
   verifies the installed asset hashes and host entry points without mutation.
 - **Shares state across runtimes.** `.ultra/state.db` (SQLite + WAL) is the
-  authoritative source for baselines, changes, tasks, sessions, events, incidents,
-  projection jobs, and telemetry. `tasks.json` and context markdown are
+  authoritative source for baselines, changes, decision threads, workflows, tasks,
+  sessions, events, incidents, projection jobs, and telemetry. `tasks.json` and context markdown are
   generated projections, not handwritten.
+- **Aligns the owner and agent without questionnaire overload.** The host resolves
+  observable facts first, then presents exactly one load-bearing decision with
+  evidence, a recommendation, credible alternatives, and the durable effect. The
+  normalized answer and owner-approved artifact checkpoint live in the DB; prompts
+  and transcripts do not. Matching workflows stop until that authority is current.
 - **Keeps memory ownership explicit.** Ultra Builder Pro does not collect
   prompts, transcripts, observations, summaries, or cross-session memory.
   Install cloud-mem/claude-mem separately if persistent memory is wanted.
-- **Runs real PRDs end-to-end without a second model credential.** The current
-  host derives task objects; `task.parse_prd` validates them → `lib/topo.cjs` waves →
-  `.ultra/execution-plan.json` → parallel worktree sessions → auto-merge back.
+- **Runs current plans without a second model credential.** The current host
+  derives task objects; `task.parse_prd` validates them → `lib/topo.cjs` waves →
+  `.ultra/execution-plan.json` → parallel worktree sessions. Execution pauses at
+  the first wave whose tasks have not converged through Ultra gates. An explicit
+  auto-merge is accepted only for a change task with a matching completion commit,
+  ready dev evidence, and a current task review; transport success alone preserves
+  the worktree.
 - **Keeps daily work convergent.** `/ultra-change` creates a bounded delta and
   complete Change Contract, classifies risk, records whether bounded research is
-  required, and creates immutable Context Manifest v2 snapshots; the Context Spine assigns a role/gate, verifies required
-  references, reports fresh-context budget pressure as advisory warnings, exposes one DB-derived breadcrumb, and
-  routes a single next action. Research stores typed, source-digested semantic records;
+  required, and leaves planning and context compilation to their actual consumers.
+  Context Manifest v3 assigns a role/gate, verifies required references, reports
+  fresh-context budget pressure as advisory warnings, and exposes mechanically valid
+  transitions without choosing the semantic route. Research stores typed,
+  source-digested semantic records;
   planning proves Change acceptance coverage; `/ultra-deliver` requires applied specification
   learning plus docs/test/mode-bound two-axis review evidence and a schema-validated
   baseline reconciliation manifest before archive. `/ultra-doctor` reports incidents,
@@ -94,9 +105,16 @@ based on delivered-system evidence: application source, tests, deployment, or
 persisted-state/schema signals make a repository brownfield; a Git repository,
 manifest, README, or starter documentation alone remains greenfield. An empty project
 opens a `draft` greenfield baseline and an existing system opens an `adopting`
-brownfield baseline. Both execute all seventeen research steps before
-`baseline.record` and explicit `baseline.converge`; initialization never treats blank
-templates as a trusted baseline and never selects an MVP. Existing active work may
+brownfield baseline. Initialization completes after classification, local Git setup,
+scaffold creation, and read-back verification; it never starts research implicitly.
+When `ultra-research` is explicitly invoked, the host dispositions each of seventeen
+coverage areas as `execute`, `verify_existing`, `reuse`, `not_applicable`, or accepted
+`deferred`. It performs only the necessary work before `baseline.record` and explicit
+`baseline.converge`; initialization never treats blank templates as a trusted baseline
+and never selects an MVP. Auto mode preserves existing
+Git or initializes `main` and adds a symlink-safe `.ultra` ignore rule; an unborn
+repository requires an owner-approved local checkpoint commit before the baseline can
+be recorded. It never creates a remote, tag, or push. Existing active work may
 continue only when its durable change workflow was bound to a healthy ready baseline;
 the expected HEAD, worktree, spec, and source-evidence drift created by that change is
 advisory until delivery reconciliation. Loss of approved-ready status or structural
@@ -105,6 +123,8 @@ approver and leaves a blocking reconciliation gap at archive; new ordinary work
 requires a healthy ready baseline. See
 [`docs/WORKFLOW-LIFECYCLE.md`](./docs/WORKFLOW-LIFECYCLE.md) for exact write,
 transition, invalidation, and recovery semantics.
+The semantic crosswalk to the original Claude Code harness is
+[`docs/LEGACY-CLI-CROSSWALK.md`](./docs/LEGACY-CLI-CROSSWALK.md).
 
 ## Three-layer architecture
 
@@ -112,15 +132,16 @@ transition, invalidation, and recovery semantics.
 |-------|---------|----------------|
 | **skill** (`skills/ultra-*/`) | Knowledge — prompts, workflows, prose | Runtime's native skill/prompt loader picks them up after install |
 | **MCP** (`mcp-server/`) | Authoritative state — reads/writes `.ultra/state.db` via stdio JSON-RPC | Primary path for task / session / event / plan operations |
-| **CLI** (`ultra-tools`, `bin/*`) | Selected initialization, recovery, diagnostics, and orchestration surfaces | `ultra-tools task init-project`, `ultra-tools system doctor`, `ubp-orchestrator run` |
+| **CLI** (`ultra-tools`, `bin/*`) | Selected initialization, recovery, diagnostics, and orchestration surfaces | `ultra-tools task init-project`, `ultra-tools system doctor`, `ubp-orchestrator execute-plan` |
 
 The layers share one `.ultra/state.db`, but the CLI is not a mirror of every MCP
 tool: continuous change mutations are MCP-only and fail closed. See
 [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) for the full contract and
-[`spec/cli-protocol.md`](./spec/cli-protocol.md) for the 41 live contracts.
-Review, impact discovery, skill resolution, and user interaction stay on each
-Host's native surfaces; the generated Codex capability map documents those
-replacements without advertising non-existent MCP tools.
+[`spec/cli-protocol.md`](./spec/cli-protocol.md) for the 50 live contracts.
+Review, impact discovery, skill resolution, and decision presentation stay on each
+host's native surfaces; MCP stores normalized decision authority but never generates
+questions. The generated Codex capability map documents those replacements without
+advertising non-existent MCP tools.
 
 The package boundary is deliberate: twelve public Ultra workflow skills, four
 internal review-rule skills, host-specific collaboration companions, and the
@@ -137,7 +158,7 @@ and framework guidance belong to their original plugins.
 | Workflow hooks               | ✅ (native plugin) | ✅ (native JS plugin) | ✅ (native plugin) | ✅ with documented compact limitation |
 | Sub-agents                   | ✅          | ✅       | ✅ (9 native TOML agents) | ✅ via `Agent` / `AgentSwarm` prompt templates |
 | Session worktree isolation   | ✅ (driven by `orchestrator/session-runner.cjs`) | ✅ | ✅ | ✅ |
-| Parallel dispatch + auto-merge | ✅ (`ubp-orchestrator run`) | ✅ | ✅ | ✅ |
+| Dependency-wave dispatch + optional verified auto-merge | ✅ (`ubp-orchestrator execute-plan`) | ✅ | ✅ | ✅ |
 
 Full details in [`docs/RUNTIME-COMPAT-MATRIX.md`](./docs/RUNTIME-COMPAT-MATRIX.md)
 (10 sections, with per-runtime deviations called out).
@@ -145,19 +166,29 @@ Full details in [`docs/RUNTIME-COMPAT-MATRIX.md`](./docs/RUNTIME-COMPAT-MATRIX.m
 ## Typical workflow
 
 ```bash
-# 1. Bootstrap project state (the ultra-init skill completes adoption and approval)
+# 1. Bootstrap deterministic authority. This completes init but not research/baseline.
 ultra-tools task init-project --project-name myapp --mode auto
 
 # Projection-only projects from prior releases use one backup-first import:
 ultra-tools migrate --from=4.4 --to=4.5 --source-dir .
-ultra-tools migrate --from=4.5 --to=15.0 --source-dir .
-
-# 2. Complete all 17 research steps, record current evidence, and obtain explicit
-#    baseline approval. Then open an initial change and persist its task contracts
-#    (normally driven by ultra-research/change/plan).
-
-# 3. Run the plan — parallel sessions, auto-merge back to main on success
-ubp-orchestrator run
+ultra-tools migrate --from=4.5 --to=18.0 --source-dir .
+
+# 2. Invoke ultra-research explicitly. The host dispositions each coverage area,
+#    executes/verifies/reuses only what is necessary, and asks one material decision at
+#    a time through the host-native question surface. Record evidence and obtain
+#    baseline approval only after the selected coverage converges.
+
+# 3. Optional worker automation. Configure a real shell-free worker first:
+# {"orchestrator":{"command":"/absolute/path/to/ultra-worker","command_args":[]}}
+# Then resume current dependency waves until the first non-converged wave.
+# A paused result is expected while dev/test/review evidence is still open.
+# Worktrees are preserved by default. Empty, cyclic, stale, duplicate-task,
+# cross-change, and stale or unverified plans fail before a session is created.
+# Each worker checkout resolves `.ultra` to the one central authority; reserved
+# UBP_DB_PATH / UBP_ROOT_DIR / UBP_AUTHORITY_ROOT bindings cannot be overridden.
+ubp-orchestrator execute-plan
+# Add --auto-merge only when the worker records the exact completion commit,
+# ready dev steps, and a current task review before it exits.
 
 # 4. Monitor cost, progress, and runtime health
 ultra-tools status
@@ -177,12 +208,18 @@ Kimi uses the corresponding
 `/ultra-builder-pro:ultra-*` namespace. Other runtimes retain their native
 command form.
 
+The arrows above show a common capability path, not a mandatory pipeline. After
+initialization the user or host explicitly selects research. During daily work,
+`ultra-change` may hand off to bounded research, planning, an already-current task,
+thinking, or status according to intent and evidence. MCP exposes allowed transitions
+and hard recovery requirements; the active host recommends the semantic route.
+
 ## CLI surface
 
 | Binary | Purpose |
 |--------|---------|
 | `ultra-builder-pro-cli` / `ubp` | Installer — `--claude / --opencode / --codex / --kimi / --all`, `--local / --global`, `--uninstall`; read-only install checks via `--doctor [--json]` |
-| `ubp-orchestrator` | Session dispatch daemon — `run`, `start`, `stop`, `status` |
+| `ubp-orchestrator` | Current completed-plan runner (`execute-plan`) and optional explicit-worker daemon (`run`, `start`, `stop`, `status`) |
 | `ultra-tools` | State-layer CLI — `task`, `session`, `status`, `db`, `migrate`; explicit `legacy-memory` archive/prune migration |
 | `ubp-handbook` | Preview/apply the managed Ultra contract in `CLAUDE.md` / `AGENTS.md`, with backup |
 

package/adapters/_shared/codex-assets.cjs

@@ -21,6 +21,7 @@ const {
   removeTree,
   writeAtomic,
 } = require('./file-ops.cjs');
+const { interactionContract } = require('./interaction-contract.cjs');
 
 const PLUGIN_NAME = 'ultra-builder-pro';
 const MANAGED_MARKER = 'Managed by Ultra Builder Pro Codex adapter.';
@@ -54,12 +55,12 @@ const CODEX_NATIVE_MCP_REPLACEMENTS = Object.freeze({
     replacement: 'the installed plugin skill SKILL.md and agents/openai.yaml contract',
   },
   'ask.question': {
-    surface: 'direct_user_interaction',
-    replacement: 'ask the user directly, or request_user_input when that Codex surface is available',
+    surface: 'request_user_input',
+    replacement: 'use request_user_input when available, otherwise ask one concise direct question',
   },
   'ask.menu': {
-    surface: 'direct_user_interaction',
-    replacement: 'present a concise choice directly, or request_user_input when that Codex surface is available',
+    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'));
@@ -420,6 +421,10 @@ main().catch((error) => {
   const specRoot = path.join(pluginRoot, 'spec');
   ensureDir(specRoot);
   writeAtomic(path.join(specRoot, 'mcp-tools.yaml'), yaml.dump(liveManifest, { lineWidth: -1, noRefs: true }));
+  writeAtomic(
+    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({
@@ -519,7 +524,7 @@ function buildPlugin({ repoRoot, pluginRoot }) {
       defaultPrompt: [
         'Initialize this project with the Ultra Builder Pro workflow.',
         'Run the Ultra review pipeline on my current changes.',
-        'Show the current Ultra project status and next action.',
+        'Show the current Ultra project status, valid transitions, and host recommendation.',
       ],
       brandColor: '#111827',
     },

package/adapters/_shared/handbook.cjs

@@ -59,9 +59,10 @@ function renderHandbook(runtime) {
     `- Workflow entry points: ${value.invocation}.`,
     `- Collaboration boundary: ${value.collaboration}. The current host remains primary and owns final verification.`,
     `- Coordination boundary: ${value.coordination}.`,
-    '- Authority: `.ultra/state.db` is the only durable Ultra authority for baselines, changes, tasks, sessions, events, incidents, projection state, telemetry, and review evidence. Generated JSON and Markdown are projections or workflow artifacts.',
+    '- Authority: `.ultra/state.db` is the only durable Ultra authority for baselines, changes, decision threads, tasks, sessions, events, incidents, projection state, telemetry, and review evidence. Generated JSON and Markdown are projections or workflow artifacts.',
     '- Baseline boundary: `task.init_project` classifies greenfield or brownfield work and records repository scope. Projection-only prior state uses the exact supported backup-first import returned by the authority check; migrated compatibility rows require explicit brownfield re-adoption. `baseline.record` owns evidence, verification, repository snapshot, and the gap ledger; `baseline.converge` requires explicit owner approval. New ordinary changes require a healthy ready baseline. Existing active work may continue with warnings, but baseline readiness blocks change convergence; normal drift reconciliation is health-checked atomically at archive. Only an explicitly approved incident break-glass may start without baseline readiness, and its archive creates a blocking reconciliation gap.',
-    '- Context Spine boundary: `change.context` compiles role/gate readiness, required references, a fresh-context budget, public seam, verification command, and one next action. File, token, and context-share budgets are advisory attention signals, not refusal gates. Hooks inject only the DB-derived `change.breadcrumb`; missing required evidence or stale execution context must be recompiled.',
+    '- Decision boundary: project-bound owner choices use one resumable DB-backed decision thread. The host resolves observable facts autonomously, presents only the earliest unresolved decision with evidence and a recommendation, waits for the owner, and records the normalized decision rather than prompts or transcripts. A linked workflow cannot advance until blocking decisions are resolved and its owner-approved checkpoint is current.',
+    '- Context Spine boundary: `change.context` compiles role/gate readiness, required references, a fresh-context budget, public seam, verification command, Change/task authority digests, allowed transitions, and any unique hard-recovery transition. File, token, and context-share budgets are advisory attention signals, not refusal gates. The host owns semantic recommendations. Hooks inject only the DB-derived `change.breadcrumb`; missing required evidence or stale execution context must be recompiled.',
     '- Specification learning boundary: stable implementation discoveries use approval-gated propose/approve-or-reject/apply transitions. Unresolved learning blocks convergence; review requires independent specification-fidelity and engineering-standards evidence.',
     '- Memory and graph boundary: Ultra Builder Pro does not capture prompts, transcripts, observations, summaries, cross-session memory, or code-graph content. Separately installed providers own that data; Ultra may store only their metadata references in a change context manifest.',
     '- Hook boundary: Ultra hooks observe workflow/change lifecycle only. Health/context may run when `.ultra/state.db` exists; advisory warnings never reject work, and an incomplete workflow never traps session stop. Direct projection protection remains authoritative; compact and subagent recovery stays active-workflow scoped. Generic command blocking and post-edit policy stay in user or repository governance.',

package/adapters/_shared/interaction-contract.cjs

@@ -0,0 +1,61 @@
+'use strict';
+
+const SURFACES = Object.freeze({
+  claude: Object.freeze({
+    primary: 'AskUserQuestion',
+    fallback: 'direct_user_interaction',
+  }),
+  codex: Object.freeze({
+    primary: 'request_user_input',
+    fallback: 'direct_user_interaction',
+  }),
+  opencode: Object.freeze({
+    primary: 'question',
+    fallback: 'direct_user_interaction',
+  }),
+  kimi: Object.freeze({
+    primary: 'native_question_surface',
+    fallback: 'direct_user_interaction',
+  }),
+});
+
+function interactionContract(runtime) {
+  const question = SURFACES[runtime];
+  if (!question) throw new Error(`unsupported interaction runtime: ${runtime}`);
+  return {
+    schema_version: '1.0',
+    runtime,
+    authority: {
+      user: [
+        'product_intent',
+        'material_scope_and_tradeoffs',
+        'destructive_or_external_effect_authorization',
+      ],
+      host_model: [
+        'fact_finding_and_synthesis',
+        'reversible_implementation_judgment',
+        'coverage_risk_and_route_recommendation',
+      ],
+      ultra_mcp: [
+        'durable_state_and_evidence_refs',
+        'digests_freshness_locks_and_recovery',
+        'allowed_and_required_transitions',
+      ],
+    },
+    interaction: {
+      question_surface: question,
+      dependent_decisions: 'one_at_a_time',
+      independent_low_load_questions: { maximum: 3 },
+      explicit_current_intent: 'normalize_without_reconfirmation',
+      unavailable_native_surface: 'use_direct_interaction',
+    },
+    routing: {
+      semantic_recommendation_owner: 'host_model',
+      durable_recommendation_authority: false,
+      hard_invariant_field: 'required_transition',
+      valid_capabilities_field: 'allowed_transitions',
+    },
+  };
+}
+
+module.exports = { SURFACES, interactionContract };

package/adapters/claude.js

@@ -28,7 +28,7 @@ const PLUGIN_NAME = 'ultra-builder-pro';
 const MCP_SERVER_NAME = PLUGIN_NAME;
 const SOURCE_TAG = 'ubp';
 const SENTINEL_KEY = '_ubp_manifest';
-const COMMAND_NAMES = CORE_PUBLIC_SKILLS.filter((name) => name !== 'ultra-review');
+const COMMAND_NAMES = CORE_PUBLIC_SKILLS;
 const PROVENANCE_FILE = 'provenance.json';
 
 function resolveTarget(ctx = {}) {

package/adapters/opencode.js

@@ -36,7 +36,7 @@ const BUNDLE_DIR = '.ultra-builder-pro';
 const MANAGED_TEXT_MARKER = '<!-- ultra-builder-pro:managed -->';
 const PLUGIN_MARKER = '// Managed by Ultra Builder Pro.';
 const PROVENANCE_FILE = 'provenance.json';
-const COMMAND_NAMES = CORE_PUBLIC_SKILLS.filter((name) => name !== 'ultra-review');
+const COMMAND_NAMES = CORE_PUBLIC_SKILLS;
 
 function resolveTarget(ctx = {}) {
   if (ctx.configDir) return ctx.configDir;