feat: align semantic decisions across Ultra hosts

Cause: host-specific question surfaces and checkpoint-only decision closure could blur user intent ownership and stall unrelated work.

Scope: add the four-host interaction contract, owner-selected research/change/plan routing, decision.complete, schema 19 migration, non-blocking decision gates, documentation, regression coverage, and the v0.20.0 release metadata.

Verification: npm run verify:release; npm pack --dry-run --ignore-scripts --json; Skill Creator validation for the five affected workflow skills; git diff --cached --check.

Residual risk: native structured-question availability remains host-version and mode dependent; the contract falls back to direct interaction when permitted and otherwise leaves intent unanswered.

Rollback: revert this commit for source behavior; schema upgrades are backup-first and existing project authority can be restored from the managed pre-migration backup.

Author: rocky2431

CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.20.0] — 2026-07-28
+
+### Added
+
+- Added schema 19 and `decision.complete` so settled normalized intent reaches a
+  terminal lifecycle state without fabricating a second user approval or an
+  artifact checkpoint. Existing settled schema-18 threads migrate safely.
+
+### Changed
+
+- Unified semantic selection across Claude Code, Codex, OpenCode, and Kimi Code
+  as `inspect -> suggest -> ask if unresolved -> normalize -> persist`, using
+  each host's native structured question surface with a direct-question
+  fallback.
+- Made research coverage and planning posture owner-selected after model
+  recommendation while preserving autonomous fact finding, synthesis,
+  decomposition, and reversible implementation judgment.
+- Stopped requiring a ceremonial decision checkpoint after every normalized
+  answer. Artifact checkpoints remain explicit digest-bound freshness gates.
+- Made unanswered non-blocking follow-ups advisory instead of global workflow
+  gates; unanswered blocking choices and blocking deferrals still fail closed.
+
 ## [0.19.1] — 2026-07-26
 
 ### Fixed
@@ -817,7 +839,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.19.1...HEAD
+[Unreleased]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.20.0...HEAD
+[0.20.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.19.1...v0.20.0
 [0.19.1]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.19.0...v0.19.1
 [0.19.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.18.0...v0.19.0
 [0.18.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.17.1...v0.18.0

README.md

@@ -73,8 +73,8 @@ The responsibility split is deliberate:
 
 | Owner | Responsibility |
 |---|---|
-| **User** | Product intent, material scope and trade-offs, destructive actions, publishing and deployment authorization |
-| **Host model** | Fact-finding, synthesis, research coverage, route recommendation, reversible implementation decisions |
+| **User** | Product intent, semantic route selection, material scope and trade-offs, risk acceptance, destructive actions, publishing and deployment authorization |
+| **Host model** | Fact-finding, synthesis, research-coverage and route recommendations, reversible implementation decisions |
 | **Ultra MCP** | Durable state, evidence references, digests, freshness, locks, valid transitions and hard recovery |
 | **Host adapter** | Native Skill discovery, user questions, tool invocation, installation, and runtime wiring |
 | **Hooks** | Fast lifecycle observation, current breadcrumb injection, and protection of generated projections |
@@ -189,7 +189,7 @@ Initialization:
 - identifies the repository root and scope;
 - classifies the repository as greenfield, brownfield, or migrated;
 - initializes Git when needed;
-- creates `.ultra/` and schema 18 project authority;
+- creates `.ultra/` and schema 19 project authority;
 - verifies that the scaffold and database can be read back;
 - completes without silently starting research, creating a commit, adding a
   remote, or pushing anything.
@@ -231,9 +231,11 @@ product story. It builds a current-system baseline from:
 - APIs, data, permissions, integrations, deployment, and recovery seams;
 - known failures, documentation drift, technical debt, and unresolved unknowns.
 
-During `ultra-research`, the host model selects the smallest evidence-backed set
-of applicable catalog areas. Every included area receives one explicit
-disposition:
+During `ultra-research`, the host model inspects current evidence and recommends
+the smallest sufficient route. The owner selects, modifies, delegates, or
+defers it through the host-native question surface unless the current request
+already resolves the route. The normalized accepted coverage is then stored in
+`.ultra/state.db`. Every included area receives one explicit disposition:
 
 - `execute` — produce fresh evidence;
 - `verify_existing` — validate an existing artifact;
@@ -243,7 +245,8 @@ disposition:
 
 The catalog is not a mandatory document set or questionnaire. Omitted areas
 create no workflow rows; an explicit exclusion is recorded only when retaining
-that rationale is useful.
+that rationale is useful. MCP validates state, evidence, and transitions; it
+does not store or prove the preceding UI interaction.
 
 Older projection-only Ultra projects are preserved and routed through a
 backup-first migration or rebaseline. Use `ultra-doctor` when initialization

adapters/_shared/interaction-contract.cjs

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

adapters/_shared/tests/interaction-contract.test.cjs

@@ -8,11 +8,40 @@ const {
 } = require('../interaction-contract.cjs');
 
 test('every supported host receives the same authority split with a native question surface', () => {
+  const expectedSurfaces = {
+    claude: 'AskUserQuestion',
+    codex: 'request_user_input',
+    opencode: 'question',
+    kimi: 'AskUserQuestion',
+  };
+  const expectedAvailability = {
+    claude: 'interactive_session',
+    codex: 'current_mode_exposes_tool',
+    opencode: 'question_permission_not_denied',
+    kimi: 'interactive_non_auto_mode',
+  };
   for (const runtime of ['claude', 'codex', 'opencode', 'kimi']) {
     const contract = interactionContract(runtime);
     assert.equal(contract.runtime, runtime);
+    assert.equal(contract.interaction.question_surface.primary, expectedSurfaces[runtime]);
     assert.equal(contract.interaction.question_surface.primary, SURFACES[runtime].primary);
     assert.equal(contract.interaction.question_surface.fallback, 'direct_user_interaction');
+    assert.equal(contract.interaction.question_surface.availability, expectedAvailability[runtime]);
+    assert.deepEqual(contract.interaction.semantic_selection_flow, [
+      'inspect', 'suggest', 'ask_if_unresolved', 'normalize', 'persist',
+    ]);
+    assert.equal(contract.interaction.dismissed_question, 'remain_unanswered');
+    assert.equal(
+      contract.interaction.unavailable_native_surface,
+      'use_direct_interaction_if_permitted',
+    );
+    assert.equal(contract.interaction.host_forbids_interaction, 'remain_unanswered');
+    assert.equal(contract.persistence.accepted_intent, 'trust_as_current_authority');
+    assert.equal(contract.persistence.user_interaction_proof, 'not_required');
+    assert.equal(contract.persistence.raw_prompt_or_transcript, 'never_store');
+    assert.ok(contract.authority.user.includes('semantic_route_selection'));
+    assert.ok(contract.authority.host_model.includes('semantic_route_recommendation'));
+    assert.ok(!contract.authority.host_model.includes('semantic_route_selection'));
     assert.equal(contract.routing.semantic_recommendation_owner, 'host_model');
     assert.equal(contract.routing.durable_recommendation_authority, false);
     assert.equal(contract.routing.hard_invariant_field, 'required_transition');

adapters/tests/claude.test.cjs

@@ -38,6 +38,12 @@ test('install builds the Claude-native plugin from the explicit Ultra allowlist'
     assert.ok(fs.existsSync(path.join(target, 'hooks', 'hooks.json')));
     assert.ok(fs.existsSync(path.join(target, '.mcp.json')));
     assert.ok(fs.existsSync(path.join(target, 'agents', 'code-reviewer.md')));
+    const interaction = JSON.parse(
+      fs.readFileSync(path.join(target, 'spec', 'interaction-contract.json'), 'utf8'),
+    );
+    assert.equal(interaction.interaction.question_surface.primary, 'AskUserQuestion');
+    assert.equal(interaction.interaction.question_surface.availability, 'interactive_session');
+    assert.equal(interaction.persistence.user_interaction_proof, 'not_required');
 
     const hooks = JSON.parse(fs.readFileSync(path.join(target, 'hooks', 'hooks.json'), 'utf8'));
     const serialized = JSON.stringify(hooks);

adapters/tests/codex.test.cjs

@@ -267,8 +267,8 @@ test('plugin declares current Codex hooks and a project-local Ultra MCP server',
     const upstreamSpec = yaml.load(fs.readFileSync(path.join(layout.pluginRoot, 'spec', 'upstream-mcp-tools.yaml'), 'utf8'));
     const capabilityMap = JSON.parse(fs.readFileSync(path.join(layout.pluginRoot, 'spec', 'codex-capability-map.json'), 'utf8'));
     const interaction = JSON.parse(fs.readFileSync(path.join(layout.pluginRoot, 'spec', 'interaction-contract.json'), 'utf8'));
-    assert.equal(liveSpec.tools.length, 50);
-    assert.equal(upstreamSpec.tools.length, 50);
+    assert.equal(liveSpec.tools.length, 51);
+    assert.equal(upstreamSpec.tools.length, 51);
     assert.deepEqual(upstreamSpec.tools.map((tool) => tool.name).sort(), liveSpec.tools.map((tool) => tool.name).sort());
     assert.deepEqual(capabilityMap.live_mcp_tools.sort(), liveSpec.tools.map((tool) => tool.name).sort());
     assert.equal(Object.keys(capabilityMap.codex_native_replacements).length, 9);

adapters/tests/kimi.test.cjs

@@ -92,6 +92,9 @@ test('Kimi manifest exposes explicit native skills, commands, hooks, and MCP wit
     }
     assert.ok(fs.existsSync(path.join(pluginRoot, 'hooks', 'context_spine.py')));
     assert.doesNotMatch(hookText, /memory|recall|journal|prompt[_ -]?capture|block_dangerous|post_edit_guard/i);
+    const interaction = readJson(path.join(pluginRoot, 'spec', 'interaction-contract.json'));
+    assert.equal(interaction.interaction.question_surface.primary, 'AskUserQuestion');
+    assert.equal(interaction.interaction.question_surface.availability, 'interactive_non_auto_mode');
 
     const commands = fs.readdirSync(path.join(pluginRoot, 'commands')).sort();
     assert.deepEqual(commands, CORE_PUBLIC_SKILLS.map((name) => `${name}.md`).sort());

adapters/tests/opencode.test.cjs

@@ -183,6 +183,16 @@ test('install writes a schema-safe opencode.json and keeps ownership outside hos
     assert.ok(Array.isArray(config.mcp[opencode.MCP_SERVER_NAME].command));
     assert.equal('_ubp_manifest' in config, false);
     assert.ok(fs.existsSync(path.join(target, opencode.BUNDLE_DIR, '.ubp-managed')));
+    const interaction = JSON.parse(fs.readFileSync(
+      path.join(target, opencode.BUNDLE_DIR, 'spec', 'interaction-contract.json'),
+      'utf8',
+    ));
+    assert.equal(interaction.interaction.question_surface.primary, 'question');
+    assert.equal(
+      interaction.interaction.question_surface.availability,
+      'question_permission_not_denied',
+    );
+    assert.equal(interaction.persistence.user_interaction_proof, 'not_required');
 
     const plugin = fs.readFileSync(path.join(target, 'plugins', 'ultra-builder-pro.js'), 'utf8');
     assert.match(plugin, /experimental\.chat\.system\.transform/);

commands/ultra-research.md

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

docs/AGENT-CONTEXT.md

@@ -44,7 +44,7 @@ reports are projections or workflow artifacts.
 
 ## 3. Live MCP and declared contracts
 
-`spec/mcp-tools.yaml` declares and the bundled server registers 50 tools across
+`spec/mcp-tools.yaml` declares and the bundled server registers 51 tools across
 eight families:
 
 | Family | Live tools |
@@ -53,15 +53,16 @@ eight families:
 | `task.*` | create, update, list, get, switch_tag, delete, init_project, expand, parse_prd, dependency_topo, append_event, subscribe_events |
 | `session.*` | spawn, close, get, list, admission_check, heartbeat, subscribe_events |
 | `change.*` | create, update, get, list, context, breadcrumb, learning_propose, learning_resolve, converge, archive |
-| `decision.*` | thread_start, get, list, open, resolve, delegate, defer, supersede, checkpoint |
+| `decision.*` | thread_start, get, list, open, resolve, delegate, defer, supersede, complete, checkpoint |
 | `workflow.*` | start, get, list, step, complete |
 | `system.*` | doctor |
 | `plan.*` | export, get |
 
 Review, repository impact discovery, skill loading, and decision presentation remain
 host-native capabilities rather than fake MCP contracts. MCP stores only normalized
-decision authority and checkpoints; it never generates questions or retains prompts
-and transcripts. The generated Codex capability map documents host replacements.
+decision authority, pending-question recovery state, lifecycle completion, and optional
+checkpoints; it never generates questions or retains prompts and transcripts. The
+generated Codex capability map documents host replacements.
 
 The complete write, transition, invalidation, and recovery contract lives in
 [`WORKFLOW-LIFECYCLE.md`](./WORKFLOW-LIFECYCLE.md).
@@ -79,11 +80,13 @@ review, and deliver route back to the same thread instead of deciding for the ow
 
 One partial unique index permits only one open item per thread. `decision.resolve`,
 `decision.delegate`, and `decision.defer` preserve the source of authority;
-`decision.supersede` preserves history when evidence or intent changes. Prepare and
-confirm checkpointing bind a material accepted cluster to current artifact digests
-when interruption recovery needs that boundary. Status and breadcrumb return only the
-current question plus allowed and mechanically required transitions, so recovery does
-not require replaying conversation history.
+`decision.supersede` preserves history when evidence or intent changes.
+`decision.complete` closes settled normalized state without manufacturing an approval
+receipt. Prepare and confirm checkpointing remain optional and bind only a material
+accepted cluster to current artifact digests when interruption recovery needs that
+boundary. Status and breadcrumb return only the current question plus allowed and
+mechanically required transitions, so recovery does not require replaying conversation
+history.
 
 ## 5. Context Spine contract