ultra-builder-pro-cli 0.18.0 → 0.20.0

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

package/docs/DECISIONS.md

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

package/docs/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/PLUGIN-ISOLATION-CONTRACT.md

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

package/docs/ROADMAP.md

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

package/docs/RUNTIME-COMPAT-MATRIX.md

@@ -15,10 +15,10 @@ not installed.
 |---|---|---|---|---|
 | Package form | `.claude-plugin` native plugin | native config bundle + JS plugin | personal `.codex-plugin` | managed `kimi.plugin.json` plugin |
 | Public entry | `/ultra-*`, `/learn` | `/ultra-*`, `/learn` | `$ultra-builder-pro:<skill>` | `/ultra-builder-pro:<command>` |
-| Public Ultra workflows | 12 | 12 | 12 | 12 |
+| Public Ultra workflows | 12, model invocation disabled | 12 commands backed by private workflow assets | 12, implicit invocation disabled | 12, model invocation disabled |
 | Internal agent-rule skills | 4, non-user-facing | 4, non-user-facing | 4 with implicit invocation disabled | 4, consumed by review workers |
 | Collaboration companions | `codex-collab`, `ultra-verify` | `cc-collab`, `codex-collab`, `ultra-verify` | `cc-collab`, `ultra-verify` | `cc-collab`, `codex-collab`, `ultra-verify` |
-| Host bootstrap | native plugin context | native plugin context | native plugin context | `using-ultra-builder-pro` session-start skill |
+| Automatic workflow bootstrap | N/A | N/A | N/A | N/A |
 | External browser/deploy/framework skills | N/A | N/A | N/A | N/A |
 
 Codex converts workflows into namespaced skills and records eleven legacy
@@ -46,21 +46,17 @@ not presented as nonexistent custom agents.
 
 | Lifecycle | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
 |---|---|---|---|---|
-| Session context/health | FULL, DB-derived Context Spine breadcrumb on native `SessionStart` | FULL, the native JS plugin invokes the same bundled DB breadcrumb reader; health via `system.doctor` | FULL, DB-derived breadcrumb on native `SessionStart` | FULL, DB-derived breadcrumb via session-start skill + hooks |
+| Session context/health | FULL, active-workflow breadcrumb on native `SessionStart` | FULL, native JS plugin injects only an active-workflow breadcrumb; health via `system.doctor` | FULL, active-workflow breadcrumb on native `SessionStart` | FULL, active-workflow breadcrumb via native hooks |
 | Active edit boundary | FULL, `PreToolUse Edit|Write` | FULL, `tool.execute.before` rejects projection writes | FULL, `PreToolUse Edit|Write|apply_patch` | FULL, native `PreToolUse Edit|Write` deny contract |
 | Pre-compact checkpoint | FULL | FULL | FULL | FULL, native `PreCompact` |
 | Post-compact context injection | FULL | FULL, native compacting context | FULL, native `PostCompact` restore | DEGRADED; checkpoint restoration runs, but Kimi 0.26/0.27 does not reinject fire-and-forget hook text |
 | Stop lifecycle advisory | FULL, native non-blocking `Stop` | N/A, no equivalent stop event needed | FULL, native non-blocking `Stop` | FULL, native non-blocking `Stop` |
 | Subagent lifecycle evidence | FULL | DEGRADED, no equivalent packaged event | FULL | FULL, native `SubagentStart` / `SubagentStop` |
 
-Kimi's session bootstrap therefore also instructs recovery to inspect
-`.ultra/runtime/checkpoint.json` and call Ultra status/doctor after compaction.
-This keeps durable recovery intact without claiming dynamic context injection
-that the host does not guarantee.
-
-Health/context hooks inspect initialized projects; projection protection also
-applies at baseline, while compact/stop/subagent enforcement remains
-active-workflow scoped. No host receives prompt capture, transcript capture,
+Health/context, compact, stop, and subagent hooks remain silent unless
+`.ultra/state.db` proves an active, blocked, or ready workflow. Projection
+protection applies to every initialized project because generated projections
+must never become a second authority. No host receives prompt capture, transcript capture,
 observation journaling, session-summary memory, generic command blocking, or
 generic post-edit policy.
 Baseline-adoption and context-budget warnings are injected as advisory context;
@@ -71,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 |
@@ -79,30 +76,34 @@ 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
 cannot be established. On POSIX it intentionally uses `env node` because Kimi
 0.26/0.27's embedded Node ABI differs from the ABI used to install `better-sqlite3`.
 
-## 5. User handbook presentation
+## 5. User instruction isolation
 
 | Capability | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
 |---|---|---|---|---|
 | Durable user file | `~/.claude/CLAUDE.md` | `~/.config/opencode/AGENTS.md` | `~/.codex/AGENTS.md` | `~/.kimi-code/AGENTS.md` |
 | Automatic overwrite by plugin install | no | no | no | no |
-| Explicit managed-block sync | `ubp-handbook apply --runtime claude` | `ubp-handbook apply --runtime opencode` | `ubp-handbook apply --runtime codex` | `ubp-handbook apply --runtime kimi` |
-| Explicit complete-handbook convergence | `--full --confirm TOKEN` | `--full --confirm TOKEN` | `--full --confirm TOKEN` | `--full --confirm TOKEN` |
-| Backup before change | FULL | FULL | FULL | FULL |
+| Writer shipped by Ultra | N/A | N/A | N/A | N/A |
+| Uninstall removes user instructions | no | no | no | no |
 
-The Kimi plugin installer does not edit `~/.kimi-code/config.toml`. Handbook
-sync remains a separate, previewable action so user policy and plugin mechanics
-do not become one irreversible mutation. Full mode is a semantic host rendering,
-not a product-name or path substitution.
+The Kimi plugin installer also does not edit `~/.kimi-code/config.toml`. Durable
+user preferences belong to each host and remain outside Ultra's ownership.
+Legacy Ultra handbook text is not proof of plugin ownership and is never
+silently rewritten or removed.
 
 ## 6. Install, update, and uninstall
 
@@ -134,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 |
 
@@ -151,8 +152,8 @@ records. Uninstall refuses an unmanaged or conflicting root.
   skills and generic/memory hooks from re-entering a package.
 - `tests/retired-runtime.test.cjs` prevents retired runtime code or prompt text
   from re-entering active product surfaces.
-- `adapters/_shared/tests/handbook.test.cjs` verifies bounded and full host
-  rendering, external-provider block preservation, backup, migration, and idempotency.
+- `adapters/_shared/tests/plugin-isolation.test.cjs` and `tests/install.test.cjs`
+  verify the absence of a handbook writer and byte-preservation of all user instruction files.
 - `adapters/_shared/tests/provenance.test.cjs` verifies normalized manifests,
   content hashes, source attribution, corruption handling, and contract drift.
 - `tests/install.test.cjs` verifies healthy four-host doctor output and

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

package/hooks/active_task_context.py

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

package/hooks/context_spine.py

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