ultra-builder-pro-cli 0.19.1 → 0.20.0

package/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

package/README.md

@@ -73,8 +73,8 @@ The responsibility split is deliberate:
 
 | Owner | Responsibility |
 |---|---|
-| **User** | Product intent, material scope and trade-offs, destructive actions, publishing and deployment authorization |
-| **Host model** | Fact-finding, synthesis, research coverage, route recommendation, reversible implementation decisions |
+| **User** | Product intent, semantic route selection, material scope and trade-offs, risk acceptance, destructive actions, publishing and deployment authorization |
+| **Host model** | Fact-finding, synthesis, research-coverage and route recommendations, reversible implementation decisions |
 | **Ultra MCP** | Durable state, evidence references, digests, freshness, locks, valid transitions and hard recovery |
 | **Host adapter** | Native Skill discovery, user questions, tool invocation, installation, and runtime wiring |
 | **Hooks** | Fast lifecycle observation, current breadcrumb injection, and protection of generated projections |
@@ -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

package/adapters/_shared/interaction-contract.cjs

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

package/commands/ultra-research.md

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

package/docs/AGENT-CONTEXT.md

@@ -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
 

package/docs/ARCHITECTURE.md

@@ -51,7 +51,7 @@ the supported hosts share.
 | Layer        | Role                                         | Form                                                  |
 |--------------|----------------------------------------------|-------------------------------------------------------|
 | **skill**    | knowledge carrier; tells the runtime *what to do* | `skills/<name>/SKILL.md` discovered natively by all supported runtimes |
-| **MCP**      | authoritative workflow-state, decision, and Context Spine API | stdio MCP server exposing 50 live tools across task/session/baseline/change/decision/workflow/system/plan families in [`spec/mcp-tools.yaml`](../spec/mcp-tools.yaml) |
+| **MCP**      | authoritative workflow-state, decision, and Context Spine API | stdio MCP server exposing 51 live tools across task/session/baseline/change/decision/workflow/system/plan families in [`spec/mcp-tools.yaml`](../spec/mcp-tools.yaml) |
 | **CLI**      | explicit initialization, recovery, diagnostics, and orchestration | `ultra-tools` / `ubp-orchestrator`; only commands listed by `--help` are executable (see [`spec/cli-protocol.md`](../spec/cli-protocol.md)) |
 
 Why three: skills give us behavior portability across runtimes; MCP gives
@@ -91,7 +91,7 @@ covers twenty-one tables:
 | `event_consumers` | durable monotonic consumer cursors                   | 8C    |
 | `workflow_runs`   | init/research/plan/change/dev/test/review/deliver run authority, position, blockers, approval, and derived summary | 13 |
 | `workflow_steps`  | ordered step state, evidence, decisions, immutable output paths, and recorded SHA-256 digests | 13 |
-| `decision_threads` | baseline/change/workflow-bound owner-agent alignment, interaction mode, normalized summary, and checkpoint authority | 16 |
+| `decision_threads` | baseline/change/workflow-bound owner-agent alignment, interaction mode, normalized completion, and optional checkpoint authority | 16/19 |
 | `decision_items` | one-at-a-time owner choices, evidence, recommendations, durable effects, resolutions, delegation, deferral, and supersession history | 16 |
 
 Two rules make this work:
@@ -141,9 +141,13 @@ same authoritative state shape without rewriting application code.
 
 Initialization completes after local authority, classification, Git/scaffold setup,
 and read-back verification. It does not start or complete research. An explicit
-`ultra-research` invocation then records the model-selected semantic coverage and
-executes, verifies, or reuses only the evidence needed to converge the baseline.
-Omitted catalog areas create no workflow row.
+`ultra-research` invocation lets the model inspect evidence and recommend a semantic
+route. The owner selects, modifies, delegates, or defers through the host-native
+question surface unless current intent already resolves the route. The normalized
+accepted coverage is then recorded, and research executes, verifies, or reuses only
+the evidence needed to converge the baseline. Omitted catalog areas create no
+workflow row. MCP validates the stored state and evidence, not the preceding user
+interaction.
 
 Auto initialization preserves an existing Git repository and HEAD. When Git is absent,
 it initializes `main`, adds the symlink-safe `.ultra` rule to `.gitignore`, and persists
@@ -193,12 +197,13 @@ alternatives, evidence refs, and durable effects; a partial unique index guarant
 current question per thread. The host ends that turn and waits.
 
 The next response becomes a normalized owner decision, explicit reversible delegation,
-or consequence-bearing deferral. Prompts and transcripts are never persisted. A coherent
-cluster moves through prepare/confirm checkpointing, which binds an owner-approved
-decision digest to the current specification, Change Contract, alignment, or plan artifact.
-Matching workflow steps and completion fail closed until the checkpoint is confirmed.
-Supersession preserves prior history and reopens alignment instead of silently editing an
-old decision. The shared procedure lives in
+or consequence-bearing deferral. Prompts and transcripts are never persisted. Routine
+settled state closes through `decision.complete`, which is lifecycle completion rather
+than another approval. Only a coherent cluster that needs an artifact-bound recovery
+boundary moves through prepare/confirm checkpointing. Matching workflow steps fail
+closed while a blocking question, blocking deferral, prepared checkpoint, or stale
+checkpoint artifact remains. Supersession preserves prior history and reopens alignment
+instead of silently editing an old decision. The shared procedure lives in
 `skills/ultra-think/references/decision-dialogue.md`; status, breadcrumb, and doctor expose
 only the current recovery surface.
 

package/docs/DECISIONS.md

@@ -9,8 +9,8 @@ release-version authority.
 
 | Layer | Owns | Must not own |
 |---|---|---|
-| User intent | Goals, acceptance, non-goals, material product trade-offs, risk acceptance, and authorization for irreversible or external effects | Facts that the current checkout or runtime can establish directly |
-| Host model | Classification, investigation, research coverage, solution design, task decomposition, context, test and review strategy, documentation impact, and next-action recommendations | Fabricated evidence, bypassed authorization, or durable lifecycle state |
+| User intent | Goals, acceptance, non-goals, semantic route selection, material product trade-offs, risk acceptance, and authorization for irreversible or external effects | Facts that the current checkout or runtime can establish directly |
+| Host model | Classification and route recommendations, investigation, solution design, task decomposition, context, test and review strategy, documentation impact, intent normalization, and next-action recommendations | Fabricated evidence, bypassed authorization, or durable lifecycle state |
 | Ultra MCP | IDs, state, digests, provenance, freshness, locks, leases, transactions, recovery, and legal state transitions | Product direction, a fixed research route, technology selection, or business decisions |
 | Host adapter | Native Skill discovery, user-question surfaces, tool invocation, installation, and runtime wiring | A second project-state authority |
 | Hook | Lifecycle observation, compact DB-derived context, recovery hints, and generated-projection protection | Ordinary development blocking or semantic route selection |
@@ -22,15 +22,19 @@ external memory, and code-graph payloads are not Ultra authority.
 ## Research coverage
 
 The research references form an optional semantic catalog. The host model
-selects only the areas justified by the current goal and evidence, records an
-evidence-based selection reason, and always includes synthesis. Omitted catalog
-areas create no workflow rows. An explicit `not_applicable` or accepted
-`deferred` entry is recorded only when preserving that exclusion is useful.
+inspects current evidence and recommends the smallest sufficient route. The
+owner selects, modifies, delegates, or defers that route through the current
+host's native question surface unless current intent already resolves it. The
+host then normalizes and records the accepted coverage with an evidence-based
+rationale and synthesis. Omitted catalog areas create no workflow rows. An
+explicit `not_applicable` or accepted `deferred` entry is recorded only when
+preserving that exclusion is useful.
 
 MCP validates generic invariants: selected identifiers must exist, dispositions
 must be legal, reused or excluded evidence must be referenced, synthesis must be
 active, and at least one non-synthesis area must be applicable. MCP does not
-choose the coverage set.
+choose the coverage set or prove how the owner answered. Once normalized intent
+is written, `.ultra/state.db` treats it as current cross-session authority.
 
 ## Lifecycle boundaries
 

package/docs/LEGACY-CLI-CROSSWALK.md

@@ -24,14 +24,14 @@ contract and adds stronger authority, recovery, or portability.
 | Original capability | Current implementation | Compatibility result |
 |---|---|---|
 | Init gathers project facts, creates Ultra files, and establishes Git | `task.init_project` performs deterministic classification, scaffold, schema, Git bootstrap, read-back verification, and then stops | Preserved and strengthened. Init has its own completion boundary and never starts research implicitly. |
-| Complete product and architecture research | `ultra-research` retains the semantic reference catalog while the model selects only applicable areas and records execute/verify/reuse/not-applicable/deferred dispositions as needed | Preserved without questionnaire overload. Necessary reports, typed semantic records, source digests, and material decision checkpoints add durable evidence. |
+| Complete product and architecture research | `ultra-research` retains the semantic reference catalog while the model recommends evidence-relevant coverage and the owner selects, modifies, delegates, or defers the route | Preserved without questionnaire overload. Accepted dispositions, necessary reports, typed semantic records, source digests, and optional material decision checkpoints add durable evidence. |
 | Planning converts accepted research into executable work with dependencies | `ultra-plan` persists complete change-owned task contracts and an exact dependency graph | Preserved and strengthened with topology, acceptance coverage, public seams, verification commands, and plan digests. |
 | Development uses isolated Git work, TDD, verification, review, commit, and integration | `ultra-dev`, `session.*`, and the session runner create real worktrees and retain task/review/commit evidence | Preserved and strengthened. Process exit cannot complete a task; uncommitted or unintegrated worktrees cannot be deleted. |
 | Test checks wiring, acceptance, regression, build, performance, security, and failures | `ultra-test` emits a change-bound immutable report covering each applicable dimension | Preserved and strengthened with HEAD, context, task-set, and report-digest validation. |
 | Review challenges specification fidelity and engineering quality | `ultra-review` is a first-class stage with independent specification and engineering axes | Strengthened. A coordinated summary cannot replace either complete axis. |
 | Delivery verifies clean readiness, documentation, build, and evidence | `ultra-deliver` requires current tasks, test, review, learning resolution, reconciliation, a local archive, and an immutable report | Preserved and strengthened. Publish, deploy, push, and other external effects remain separate explicitly authorized operations. |
 | Status restores the current workflow position | `ultra-status` reads DB authority, Git, sessions, artifacts, decisions, allowed transitions, and any hard recovery requirement | Strengthened. The host recommends the semantic route; projections and Prompt prose cannot override state. |
-| Thinking synchronizes owner and Agent intent | `ultra-think` plus `decision.*` persists one-question dialogue and artifact checkpoints | Strengthened. Observable facts are resolved first; only load-bearing owner choices block. |
+| Thinking synchronizes owner and Agent intent | `ultra-think` plus `decision.*` persists one-question dialogue, non-ceremonial completion, and optional artifact checkpoints | Strengthened. Observable facts are resolved first; only load-bearing owner choices block. |
 
 ## CLI-original capabilities
 
@@ -73,8 +73,9 @@ metadata references.
 ## Reference capability paths and gates
 
 These paths show common capability order and hard prerequisites. They are not a
-single mandatory pipeline: the host selects among MCP-reported allowed transitions,
-while MCP requires one route only for a unique mechanical recovery invariant.
+single mandatory pipeline: the model recommends among MCP-reported allowed
+transitions, while the owner selects or delegates the semantic route. MCP requires one
+route only for a unique mechanical recovery invariant.
 
 ### New repository
 
@@ -83,7 +84,7 @@ task.init_project
   -> greenfield classification
   -> Git bootstrap when absent
   -> init read-back and completion
-  -> explicit full research with model-selected coverage
+  -> explicit full research with a model-recommended, owner-selected route
   -> selected execute/verify/reuse work and synthesis
   -> owner-authorized local checkpoint commit when Git is unborn
   -> baseline.record
@@ -99,7 +100,7 @@ task.init_project
   -> brownfield classification and selected scope
   -> preserve current Git HEAD and dirty-state evidence
   -> init read-back and completion
-  -> explicit adoption research with model-selected coverage
+  -> explicit adoption research with a model-recommended, owner-selected route
   -> characterization verification + known-red/gap ledger
   -> baseline.record + owner approval
   -> baseline.converge
@@ -122,7 +123,8 @@ doctor/migrate with backup
 status
   -> change intent capture
   -> material alignment only when unresolved
-  -> host-selected bounded research, plan, current dev work, think, or status
+  -> model-recommended, owner-selected or delegated bounded research, plan,
+     current dev work, think, or status
   -> session.spawn creates the real task worktree
   -> red/green/verify/review
   -> local task commit and verified integration

package/docs/ROADMAP.md

@@ -49,25 +49,26 @@ sharing one authoritative workflow store.
 | 12    | Repository evidence snapshots + gap ledger + migration re-adoption + incident governance | ✅ done |
 | 13    | Durable init-to-delivery workflows + task execution contracts + immutable stage evidence | ✅ done |
 | 16    | Resumable one-question owner-agent decisions + artifact checkpoints + workflow gates | ✅ done |
+| 19    | Non-ceremonial decision completion + four-host semantic-selection contract | ✅ done |
 | 9     | Release pipeline                               | npm tag publishing live; Homebrew / pip not implemented |
 
 ## What is in the repo today
 
 ```
 spec/                       ← Phase 1 single source of truth
-├── mcp-tools.yaml          (50 live tools across 8 families)
+├── mcp-tools.yaml          (51 live tools across 8 families)
 ├── cli-protocol.md         (CLI ↔ MCP mapping table)
 ├── schemas/                (state-db.sql + 4 JSON schemas)
 ├── fixtures/{valid,invalid}/  (+ v4.4-project for migration)
 └── scripts/test-all.cjs    (npm run test:spec — 7 validation stages)
 
 mcp-server/                 ← Phase 2 authoritative state layer
-├── server.cjs              (stdio MCP server, 50 task/session/baseline/change/decision/workflow/system/plan tools)
+├── server.cjs              (stdio MCP server, 51 task/session/baseline/change/decision/workflow/system/plan tools)
 ├── lib/
 │   ├── state-db.cjs        (SQLite + WAL + pragmas)
 │   ├── state-ops.cjs       (full write API, status state machine)
 │   ├── baseline-workflow.cjs (project adoption + approval + reconciliation)
-│   ├── decision-dialogue.cjs (one-question authority + checkpoint gates)
+│   ├── decision-dialogue.cjs (one-question authority + completion/checkpoint gates)
 │   ├── workflow-state.cjs  (ordered stage runs, evidence, output digests, and gates)
 │   └── projector.cjs       (state.db → tasks.json + context md)
 └── tests/                  (npm run test:state)

package/docs/RUNTIME-COMPAT-MATRIX.md

@@ -67,7 +67,8 @@ they do not deny edits or stop active incident work.
 | Capability | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
 |---|---|---|---|---|
 | stdio MCP registration | plugin `.mcp.json` | `opencode.json` local MCP entry | plugin `.mcp.json` | plugin `mcpServers` entry |
-| Live/declared contracts | 50 | 50 | 50 | 50 |
+| Live/declared contracts | 51 | 51 | 51 | 51 |
+| Structured user alignment | `AskUserQuestion` in interactive sessions | `question` when permission is not denied | `request_user_input` when the current mode exposes it | `AskUserQuestion` outside auto mode |
 | Greenfield/brownfield baseline adoption | FULL | FULL | FULL | FULL |
 | Context Manifest v3 / breadcrumb | FULL | FULL, same bundled read-only DB reader as every hook | FULL | FULL |
 | Approval-gated spec learning | FULL | FULL | FULL | FULL |
@@ -75,10 +76,15 @@ they do not deny edits or stop active incident work.
 | Durable authority | project `.ultra/state.db` | project `.ultra/state.db` | project `.ultra/state.db` | project `.ultra/state.db` |
 | Ultra memory API | N/A | N/A | N/A | N/A |
 
-All 50 `task.*`, `session.*`, `baseline.*`, `change.*`, `decision.*`, `workflow.*`, `system.*`, and `plan.*` operations
+All 51 `task.*`, `session.*`, `baseline.*`, `change.*`, `decision.*`, `workflow.*`, `system.*`, and `plan.*` operations
 registered by `mcp-server/server.cjs` are live. Review, impact discovery, skill
 loading, and user interaction remain host-native surfaces.
 
+When a native structured question surface is unavailable, the shared interaction
+contract permits one concise direct question only if ordinary conversation is still
+available. A host mode that forbids interaction leaves the choice unanswered; Ultra
+does not infer consent or silently delegate the semantic route.
+
 Kimi starts plugin MCP processes with the managed plugin root as `cwd`. The
 generated launcher recovers the project from the inherited `PWD`, sets
 `UBP_ROOT_DIR` and `UBP_DB_PATH`, and refuses to start if that project boundary
@@ -129,9 +135,9 @@ records. Uninstall refuses an unmanaged or conflicting root.
 
 | Capability | Contract |
 |---|---|
-| Current state schema | `18.0` |
+| Current state schema | `19.0` |
 | Runtime values | `claude`, `opencode`, `codex`, `kimi` |
-| Upgrade from earlier schema | preserves runtime rows, adds Context Spine state through 10.0, authoritative baseline adoption in 11.0, repository evidence in 12.0, durable workflows in 13.0, continuous baseline revalidation in 14.0, typed research semantics and verified reconciliation in 15.0, resumable owner-agent decision threads and workflow alignment gates in 16.0, explicit unborn-Git authority in 17.0, then adaptive transitions and legacy workflow normalization in 18.0 |
+| Upgrade from earlier schema | preserves runtime rows, adds Context Spine state through 10.0, authoritative baseline adoption in 11.0, repository evidence in 12.0, durable workflows in 13.0, continuous baseline revalidation in 14.0, typed research semantics and verified reconciliation in 15.0, resumable owner-agent decision threads and workflow alignment gates in 16.0, explicit unborn-Git authority in 17.0, adaptive transitions and legacy workflow normalization in 18.0, then non-ceremonial decision completion in 19.0 |
 | Preservation gate | rows, IDs, indexes, foreign keys, telemetry, incidents, and migration history remain intact |
 | Failure behavior | rollback; no partially upgraded authority database |
 

package/docs/STATE-DB-ACCESS-POLICY.md

@@ -74,7 +74,7 @@ resolve the mount/runtime constraint before retrying.
 | `baselines`        | MCP server (`baseline.start` / `baseline.record` / `baseline.converge`); initialization and legacy-projection migration may create only the first draft or compatibility row |
 | `tasks`            | MCP server (`task.create` / `task.update` / `task.delete`) |
 | `changes`          | MCP server (`change.create` / `change.update` / `change.converge` / `change.archive`) |
-| `decision_threads`, `decision_items` | MCP server (`decision.thread_start` / `decision.open` / `decision.resolve` / `decision.delegate` / `decision.defer` / `decision.supersede` / `decision.checkpoint`); only normalized choices and checkpoints are stored, never prompts or transcripts |
+| `decision_threads`, `decision_items` | MCP server (`decision.thread_start` / `decision.open` / `decision.resolve` / `decision.delegate` / `decision.defer` / `decision.supersede` / `decision.complete` / `decision.checkpoint`); only pending questions needed for recovery, normalized choices, lifecycle completion, and optional artifact checkpoints are stored, never prompts or transcripts |
 | `workflow_runs`, `workflow_steps` | MCP server (`workflow.start` / `workflow.step` / `workflow.complete`); skills provide evidence inputs but never write rows directly |
 | `artifacts`, `context_snapshots`, `spec_learning_candidates`, `trace_links` | MCP server through change lifecycle tools |
 | `incidents`, `projection_jobs`, `event_consumers`, `circuit_breaker` | MCP server; backup-first doctor recovery may perform only documented mechanical transitions |

package/docs/WORKFLOW-LIFECYCLE.md

@@ -25,9 +25,10 @@ as MCP authority.
 
 Load-bearing owner choices are normalized through `decision.*`; Prompt prose is not
 durable authority. The host acquires observable facts autonomously, exposes one
-current question, and stops. A workflow cannot advance while a matching decision
-thread is active, waiting for checkpoint confirmation, or carrying a blocking
-deferral.
+current question, and stops. A workflow cannot advance while a matching decision has
+an unanswered blocking question, a blocking deferral, a prepared checkpoint awaiting
+confirmation, or a stale confirmed artifact. A normalized answer alone does not require
+a ceremonial checkpoint.
 
 Every change-bound research, plan, dev, test, review, and deliver run inherits
 the baseline id from the owning change workflow. A Prompt cannot switch that
@@ -37,11 +38,13 @@ it does not fabricate the missing provenance.
 
 Ultra does not select product scope or material delivery posture; those remain user
 decisions. Research references form an optional catalog, not a forced questionnaire.
-The host model selects only evidence-relevant areas and records one coverage rationale.
-MCP validates identifiers, dispositions, evidence requirements, synthesis, and at
-least one applicable semantic area. Omitted areas create no workflow step. An explicit
-`not_applicable` or accepted `deferred` row is retained only when its exclusion is
-material.
+The host model inspects evidence and recommends only relevant areas. The owner selects,
+modifies, delegates, or defers that route through the native question surface unless
+current intent already resolves it. The host records the normalized accepted coverage
+and rationale. MCP validates identifiers, dispositions, evidence requirements,
+synthesis, and at least one applicable semantic area; it does not prove the preceding
+interaction. Omitted areas create no workflow step. An explicit `not_applicable` or
+accepted `deferred` row is retained only when its exclusion is material.
 
 ## 2. How `ultra-init` classifies a repository
 
@@ -195,29 +198,33 @@ making it `completed`.
 ### Decision thread and item
 
 ```text
-thread: active -> checkpoint_ready -> confirmed
-           ^              |
-           |--------------+  revision/supersession
+thread: active -> completed
+           |
+           +----> checkpoint_ready -> confirmed
+           ^              |              |
+           |--------------+--------------+  revision/supersession
 
 item: open -> answered | delegated | deferred | superseded
 ```
 
 A thread is bound to baseline, change, or workflow authority. A partial unique index
 allows only one `open` item per thread. Resolved items remain immutable history;
-changed evidence or intent uses `decision.supersede` and reopens the checkpoint.
-`decision.checkpoint` first freezes a normalized decision digest, then binds explicit
-owner approval to current artifact digests or a justified standalone no-artifact
-case. It never stores the conversation transcript.
+changed evidence or intent uses `decision.supersede` and reopens alignment.
+`decision.complete` closes settled normalized state without adding an approval claim.
+When an artifact-bound recovery boundary is actually needed, `decision.checkpoint`
+instead freezes a normalized decision digest and binds explicit owner approval to
+current artifact digests or a justified standalone no-artifact case. Neither path
+stores the conversation transcript.
 
 ## 4. Write and verification lifecycle
 
 | Stage | Authoritative writes | Completion verification | Available continuation |
 |---|---|---|---|
 | `init` | Baseline classification/scope, Git bootstrap state, completed init run, initialization event, projection job | DB/schema opens, scaffold/projection and read-back succeed; existing Git is preserved or missing local Git is initialized | Explicitly chosen `research`, `status`, or `doctor`; an already-ready project may also enter `change` |
-| `research` | Coverage dispositions, selected step evidence, material decision checkpoints, typed semantic records with source digests, immutable reports, output paths and SHA-256 digests | Every coverage area is dispositioned; only executed/verified/reused areas require work evidence; synthesis binds current specifications and distillate; all material decisions and digests are current | Baseline record/convergence for initial research; bounded change research returns to its owning change |
+| `research` | Accepted coverage dispositions, selected step evidence, normalized material decisions, optional artifact checkpoints, typed semantic records with source digests, immutable reports, output paths and SHA-256 digests | Every included coverage area is dispositioned; only executed/verified/reused areas require work evidence; synthesis binds current specifications and distillate; all material decisions and digests are current | Baseline record/convergence for initial research; bounded change research returns to its owning change |
 | baseline convergence | Spec/source/runtime refs, verification results, known failures, unknowns, gaps, branch/HEAD/worktree, approval | Full/adoption research complete; required discovery/product/architecture refs current; revision/worktree exact; blocking gaps resolved or explicitly accepted where allowed | `change` for every initial or daily outcome |
-| `change` | Complete Change Contract, profile/risk rationale, research disposition, intent/delta artifacts, and a completed capture run; a decision thread only when material intent remains unresolved | Intent, acceptance, recovery, classification, and research disposition are complete and bound to the baseline | Host selects among bounded `research`, `plan`, current `dev`, `think`, or `status` using allowed transitions |
-| `plan` | Selected planning evidence, complete change-owned task rows, acceptance coverage matrix, and change-bound `.ultra/execution-plan.json`; approval only for a material owner decision | Every Change acceptance id is owned by a task; trace targets, ownership, dependencies, topology, task contracts, and exported digest match current authority | Any dependency-ready task may enter `dev` |
+| `change` | Complete Change Contract, profile/risk rationale, research disposition, intent/delta artifacts, and a completed capture run; a decision thread only when material intent remains unresolved | Intent, acceptance, recovery, classification, and research disposition are complete and bound to the baseline | Model recommends; owner selects or delegates bounded `research`, `plan`, current `dev`, `think`, or `status` from allowed transitions |
+| `plan` | Accepted planning posture, selected planning evidence, complete change-owned task rows, acceptance coverage matrix, and change-bound `.ultra/execution-plan.json`; approval only for a material owner decision | Every Change acceptance id is owned by a task; trace targets, ownership, dependencies, topology, task contracts, and exported digest match current authority | Any dependency-ready task may enter `dev` |
 | `dev` | Task/session transitions, real worktree, step evidence, immutable implementation context, completion/review references | Task completed; no live session; task contract unchanged; starting context and review artifacts valid; completion commits are integrated and remain ancestors of current HEAD | Next task, then aggregate `test` |
 | `test` | Immutable checking context, an explicit risk-selected verification profile, and `.ultra/reports/tests/<workflow-id>.json` | Selected dimensions and acceptance pass; every excluded dimension has a rationale; report change/task set, HEAD, worktree, context, commands, blockers, and digests agree | `review` when passing, otherwise resume `dev`/`test` |
 | `review` | Immutable review context, `task`/`change`/`plan` mode, risk-selected worker provenance, two mandatory specialist axes, and coordinated summary | Current diff/HEAD and context match; the complete worker roster is selected or skipped with rationale; completed workers match specialist artifacts; both axes complete; findings and axis verdicts derive the final verdict | `deliver` only from a passing `change` review, otherwise resume implementation or checking |
@@ -249,8 +256,19 @@ thread only for a new material decision cluster. Before asking, it must:
 6. normalize the owner response with `decision.resolve`, explicit reversible
    delegation with `decision.delegate`, or a consequence-bearing deferral with
    `decision.defer`;
-7. prepare a compact checkpoint only when a material decision cluster changes a
-   durable contract and interruption recovery needs an artifact-bound boundary.
+7. call `decision.complete` when normalized state is settled, or prepare a compact
+   checkpoint only when a material decision cluster changes a durable contract and
+   interruption recovery needs an artifact-bound boundary.
+
+The shared semantic flow is `inspect -> suggest -> ask if unresolved -> normalize ->
+persist`. Claude Code and Kimi Code use `AskUserQuestion`, Codex uses
+`request_user_input` when its current mode exposes it, and OpenCode uses `question`
+when permitted. Every host falls back to one concise direct question when normal
+conversation is still allowed. If the current host mode forbids interaction entirely,
+the choice remains unanswered and route-dependent writes stop. A dismissed question
+also remains unanswered. The DB trusts a normalized persisted result as current
+authority across sessions; it does not store or verify a UI receipt, raw prompt, or
+transcript.
 
 `ultra-think` owns this interaction protocol. `ultra-research`, `ultra-change`, and
 `ultra-plan` invoke it at their decision boundaries. `ultra-dev`, `ultra-test`,
@@ -326,7 +344,8 @@ current gate evidence do block.
 
 ```text
 ultra-init -> Git/scaffold/authority verification -> init completed
--> explicit ultra-research -> model-selected coverage -> selected evidence work
+-> explicit ultra-research -> suggested route -> owner-selected accepted coverage
+-> selected evidence work
 -> local checkpoint when Git is unborn -> baseline approval
 -> ultra-change -> optional bounded research/plan -> dev -> risk-selected test/review
 -> local deliver/archive
@@ -336,7 +355,7 @@ ultra-init -> Git/scaffold/authority verification -> init completed
 
 ```text
 ultra-init -> preserve Git/classify brownfield -> init completed
--> explicit adoption research -> model-selected coverage
+-> explicit adoption research -> suggested route -> owner-selected accepted coverage
 -> selected characterization/known-red evidence -> gap ledger -> owner approval
 -> first ultra-change -> optional bounded research/plan -> dev -> test/review -> deliver
 ```
@@ -358,7 +377,8 @@ Migration preserves prior files and rows but never carries old approval forward.
 
 ```text
 ultra-status -> ultra-change intent capture
--> host chooses bounded research, plan, current task, think, or status
+-> model recommends; owner selects or delegates bounded research, plan, current task,
+   think, or status
 -> dev -> risk-selected test -> review -> deliver -> reconciled baseline
 ```
 
@@ -374,13 +394,13 @@ evidence rather than bypassing them.
 | `ultra-init` | classification, scope, Git/scaffold bootstrap, and init verification | stops completed; exposes research/status/doctor and any already-valid change capability |
 | `ultra-research` | coverage disposition, selected evidence acquisition, synthesis, and material research decisions | baseline convergence or return to the owning change |
 | `ultra-think` | one material owner decision or read-only diagnosis | returns to the invoking capability after any needed checkpoint |
-| `ultra-change` | outcome capture, Change Contract, risk/research routing | host selects research, plan, current dev work, think, or status |
+| `ultra-change` | outcome capture, Change Contract, risk/research routing | model recommends; owner selects or delegates research, plan, current dev work, think, or status |
 | `ultra-plan` | task contracts, dependencies, acceptance coverage, optional material approval | any dependency-ready task through `ultra-dev` |
 | `ultra-dev` | one task/session vertical slice and focused review | next `ultra-dev` task or aggregate `ultra-test` |
 | `ultra-test` | risk-selected change acceptance and verification profile | `ultra-review` on pass, `ultra-dev`/`ultra-test` on failure |
 | `ultra-review` | independent specification and engineering axes plus risk-selected workers | `ultra-deliver` on approval; otherwise implementation or checking |
 | `ultra-deliver` | convergence, reconciliation, local archive, and delivery evidence | `ultra-status` or the next `ultra-change`; external release is separate |
-| `ultra-status` | read-only authority and transition set | host recommendation among allowed transitions |
+| `ultra-status` | read-only authority and transition set | model recommendation; owner selection or delegation among allowed transitions |
 | `ultra-doctor` | read-only diagnosis and authorized mechanical recovery | required recovery only when unique; otherwise safe alternatives |
 
 Every row permits `ultra-think` when material owner authority is missing and permits