ultra-builder-pro-cli 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.16.0] — 2026-07-23
+
+### Added
+
+- Added schema 16 durable decision threads and items with exactly one current
+  question, normalized owner answers, explicit reversible delegation, consequence-
+  bearing deferral, supersession history, and artifact-bound checkpoints.
+- Added nine `decision.*` MCP contracts, CLI mappings, events, valid/invalid contract
+  fixtures, status/breadcrumb recovery, doctor health checks, and workflow gates.
+- Added one canonical progressive-disclosure decision protocol shared by init,
+  research, thinking, change, and planning without copying questionnaires into each
+  Skill.
+
+### Changed
+
+- Changed research to preserve all seventeen semantic steps as an internal coverage
+  contract while exposing only the current owner decision or compact checkpoint.
+- Changed change and plan formation to inspect facts autonomously, present one
+  evidence-backed choice at a time, stop for the owner, and reuse one approved
+  checkpoint instead of requesting equivalent confirmations.
+- Changed dev, test, review, deliver, status, doctor, user handbooks, and lifecycle
+  documentation to recover through the same decision authority and exact next route.
+
+### Fixed
+
+- Prevented a decision thread for one change from blocking unrelated changes on the
+  same baseline while preserving baseline-only and matching workflow gates.
+- Prevented workflow steps or completion from advancing on an open, blocking-deferred,
+  checkpoint-ready, stale, or superseded owner decision.
+- Prevented prompt transcripts, static question queues, large research dumps, and
+  repeated owner approvals from becoming project authority.
+
 ## [0.15.0] — 2026-07-22
 
 ### Added
@@ -624,7 +656,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   skill manifest, CLI protocol + mapping table; 5 spec validators.
 - **Phase 0 — skeleton**: multi-runtime installer scaffolding.
 
-[Unreleased]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.15.0...HEAD
+[Unreleased]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.16.0...HEAD
+[0.16.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.15.0...v0.16.0
 [0.15.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.14.0...v0.15.0
 [0.14.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.13.0...v0.14.0
 [0.13.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.12.1...v0.13.0

package/README.md

@@ -8,7 +8,7 @@ authoritative `.ultra/state.db`.
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/version-0.15.0-blue)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.16.0-blue)](./CHANGELOG.md)
 [![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](#verification)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![Node](https://img.shields.io/badge/node-%E2%89%A522-informational)](./package.json)
@@ -25,9 +25,14 @@ authoritative `.ultra/state.db`.
   Install and uninstall are symmetric on every supported host; `ubp --doctor`
   verifies the installed asset hashes and host entry points without mutation.
 - **Shares state across runtimes.** `.ultra/state.db` (SQLite + WAL) is the
-  authoritative source for baselines, changes, tasks, sessions, events, incidents,
-  projection jobs, and telemetry. `tasks.json` and context markdown are
+  authoritative source for baselines, changes, decision threads, workflows, tasks,
+  sessions, events, incidents, projection jobs, and telemetry. `tasks.json` and context markdown are
   generated projections, not handwritten.
+- **Aligns the owner and agent without questionnaire overload.** The host resolves
+  observable facts first, then presents exactly one load-bearing decision with
+  evidence, a recommendation, credible alternatives, and the durable effect. The
+  normalized answer and owner-approved artifact checkpoint live in the DB; prompts
+  and transcripts do not. Matching workflows stop until that authority is current.
 - **Keeps memory ownership explicit.** Ultra Builder Pro does not collect
   prompts, transcripts, observations, summaries, or cross-session memory.
   Install cloud-mem/claude-mem separately if persistent memory is wanted.
@@ -117,10 +122,11 @@ transition, invalidation, and recovery semantics.
 The layers share one `.ultra/state.db`, but the CLI is not a mirror of every MCP
 tool: continuous change mutations are MCP-only and fail closed. See
 [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) for the full contract and
-[`spec/cli-protocol.md`](./spec/cli-protocol.md) for the 41 live contracts.
-Review, impact discovery, skill resolution, and user interaction stay on each
-Host's native surfaces; the generated Codex capability map documents those
-replacements without advertising non-existent MCP tools.
+[`spec/cli-protocol.md`](./spec/cli-protocol.md) for the 50 live contracts.
+Review, impact discovery, skill resolution, and decision presentation stay on each
+host's native surfaces; MCP stores normalized decision authority but never generates
+questions. The generated Codex capability map documents those replacements without
+advertising non-existent MCP tools.
 
 The package boundary is deliberate: twelve public Ultra workflow skills, four
 internal review-rule skills, host-specific collaboration companions, and the
@@ -150,11 +156,12 @@ ultra-tools task init-project --project-name myapp --mode auto
 
 # Projection-only projects from prior releases use one backup-first import:
 ultra-tools migrate --from=4.4 --to=4.5 --source-dir .
-ultra-tools migrate --from=4.5 --to=15.0 --source-dir .
+ultra-tools migrate --from=4.5 --to=16.0 --source-dir .
 
-# 2. Complete all 17 research steps, record current evidence, and obtain explicit
-#    baseline approval. Then open an initial change and persist its task contracts
-#    (normally driven by ultra-research/change/plan).
+# 2. Complete all 17 research steps. When owner judgment is required, the host asks
+#    one evidence-backed decision at a time and checkpoints the accepted artifacts.
+#    Record current evidence, obtain explicit baseline approval, then open and align
+#    an initial change before persisting its task contracts.
 
 # 3. Run the plan — parallel sessions, auto-merge back to main on success
 ubp-orchestrator run

package/adapters/_shared/handbook.cjs

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

package/commands/ultra-change.md

@@ -1,5 +1,5 @@
 ---
-description: Open or resume a bounded continuous change with linked authoritative tasks and context
+description: Align, open, and route one bounded continuous change through research, plan, and delivery
 argument-hint: "[change-id-or-title] [quick|standard|major|incident]"
 workflow-ref: "@skills/ultra-change/SKILL.md"
 ---

package/commands/ultra-plan.md

@@ -1,5 +1,5 @@
 ---
-description: Convert validated requirements into dependency-valid Ultra tasks with bounded context and exact verification
+description: Interactively review and persist dependency-valid tasks with bounded context and exact verification
 argument-hint: "[scope]"
 workflow-ref: "@skills/ultra-plan/SKILL.md"
 ---

package/commands/ultra-research.md

@@ -1,5 +1,5 @@
 ---
-description: Research unresolved product or architecture decisions and update the authoritative baseline specifications
+description: Build complete research evidence while presenting only one load-bearing owner decision at a time
 argument-hint: "[scope-or-question]"
 workflow-ref: "@skills/ultra-research/SKILL.md"
 ---

package/commands/ultra-think.md

@@ -1,10 +1,10 @@
 ---
-description: Analyze a consequential question with evidence, uncertainty, and proportionate stress testing
+description: Resolve a consequential question through evidence or one-decision-at-a-time alignment
 argument-hint: "[question]"
 workflow-ref: "@skills/ultra-think/SKILL.md"
 ---
 
-# Analyze a consequential question
+# Align on a consequential question
 
 Read and follow `@skills/ultra-think/SKILL.md`, treating `$ARGUMENTS` as the question to resolve.
 Treat the referenced skill as the only workflow definition.

package/docs/AGENT-CONTEXT.md

@@ -37,15 +37,15 @@ native command or skill -> MCP workflow-state operation -> .ultra/state.db
 | MCP | `mcp-server/server.cjs` | Authoritative typed operations over `.ultra/state.db` |
 | CLI | `ultra-tools`, `ubp-orchestrator` | Selected initialization, backup-first recovery, automation, and diagnostics; not a change-state mirror |
 
-`.ultra/state.db` is the only durable Ultra authority for baselines, changes, tasks,
+`.ultra/state.db` is the only durable Ultra authority for baselines, changes, decisions, tasks,
 workflow runs/steps, sessions, events, incidents, projection jobs/cursors, telemetry, review evidence,
 and circuit-breaker state. `tasks.json`, context Markdown, execution plans, and
 reports are projections or workflow artifacts.
 
 ## 3. Live MCP and declared contracts
 
-`spec/mcp-tools.yaml` declares and the bundled server registers 41 tools across
-seven families:
+`spec/mcp-tools.yaml` declares and the bundled server registers 50 tools across
+eight families:
 
 | Family | Live tools |
 |---|---|
@@ -53,13 +53,15 @@ seven 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 |
 | `workflow.*` | start, get, list, step, complete |
 | `system.*` | doctor |
 | `plan.*` | export, get |
 
-Review, repository impact discovery, skill loading, and user interaction remain
-host-native capabilities rather than fake MCP contracts. The generated Codex
-capability map documents those replacements.
+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.
 
 The complete write, transition, invalidation, and recovery contract lives in
 [`WORKFLOW-LIFECYCLE.md`](./WORKFLOW-LIFECYCLE.md).
@@ -67,7 +69,22 @@ The complete write, transition, invalidation, and recovery contract lives in
 Any new MCP contract starts in `spec/mcp-tools.yaml` with valid and invalid
 fixtures. Do not add an ad-hoc server handler first.
 
-## 4. Context Spine contract
+## 4. Human-agent alignment contract
+
+`skills/ultra-think/references/decision-dialogue.md` is the single reusable prompt
+contract for load-bearing owner choices. Research, change, and plan read it at their
+decision boundaries. They inspect evidence first, expose only the earliest unresolved
+choice, include a recommendation and durable effects, and stop the turn. Dev, test,
+review, and deliver route back to the same thread instead of deciding for the owner.
+
+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 the accepted cluster to current artifact digests before a
+matching workflow may advance. Status and breadcrumb return only the current question
+and one route, so recovery does not require replaying conversation history.
+
+## 5. Context Spine contract
 
 Context Manifest v2 is an immutable DB-backed role handoff, not a static codebase summary.
 `change.context` compiles required references, digests, readiness, context budget,
@@ -92,7 +109,7 @@ through approve/reject/apply transitions in `change.learning_resolve`. Unresolve
 learning blocks convergence. Review contributes two independent axes,
 `spec_fidelity` and `engineering_standards`; neither can replace the other.
 
-## 5. Native host presentation
+## 6. Native host presentation
 
 | Host | Plugin form | Workflow entry | Hook form | Collaboration companions |
 |---|---|---|---|---|
@@ -105,7 +122,7 @@ The current host remains primary. Collaboration skills call another runtime
 only when explicitly requested, use it as a read-only advisor, and return the
 evidence to the primary host for final verification.
 
-## 6. Hook boundary
+## 7. Hook boundary
 
 The canonical Python hook bundle contains seven executable workflow hooks plus
 the shared read-only `context_spine.py` breadcrumb helper:
@@ -133,7 +150,7 @@ reject an edit, stop, or tool call.
 Generic command blocking, post-edit governance, and unrelated user hooks are not
 copied into Ultra Builder Pro.
 
-## 7. Memory boundary
+## 8. Memory boundary
 
 Ultra Builder Pro has no memory MCP family, recall skill, prompt capture,
 transcript capture, observation journal, or session-summary hook. Persistent
@@ -151,7 +168,7 @@ ultra-tools legacy-memory prune --confirm DELETE_ULTRA_LEGACY_MEMORY
 
 Archive before prune; the confirmation token is intentionally required.
 
-## 8. Project state layout
+## 9. Project state layout
 
 ```text
 .ultra/
@@ -171,7 +188,7 @@ Archive before prune; the confirmation token is intentionally required.
     └── delivery/<workflow-id>.json
 ```
 
-## 9. User handbook integration
+## 10. User handbook integration
 
 General engineering doctrine remains user-owned in `CLAUDE.md` or `AGENTS.md`.
 Ultra Builder Pro contributes one managed section only. Preview or apply it with:
@@ -186,7 +203,7 @@ timestamped backup, replaces only the marked block, and can migrate the old
 Codex `## Ultra Builder Pro Runtime Contract` section without touching the next
 user section. Plugin adapters themselves do not silently overwrite handbooks.
 
-## 10. Verification
+## 11. Verification
 
 Run `npm run test:all`, `python3 -m pytest hooks/tests -q`, and `npm audit`.
 Adapter tests assert the allowlisted assets, native manifests, hook boundary,

package/docs/ARCHITECTURE.md

@@ -53,7 +53,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 and Context Spine API | stdio MCP server exposing 41 live tools across task/session/baseline/change/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 50 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
@@ -70,7 +70,7 @@ RPC, and host-native loaders own resolution and invocation.
 
 All durable Ultra workflow state lives in one SQLite file with WAL enabled. Schema is
 fixed in [`spec/schemas/state-db.sql`](../spec/schemas/state-db.sql) and
-covers nineteen tables:
+covers twenty-one tables:
 
 | Table              | Holds                                             | Phase |
 |--------------------|---------------------------------------------------|-------|
@@ -83,7 +83,7 @@ covers nineteen tables:
 | `telemetry`        | per-session token / cost / tool-call counters     | 6     |
 | `specs_refs`       | spec change tracking → staleness propagation       | 5     |
 | `circuit_breaker`  | bounded retry and halt state for failed tasks       | 5     |
-| `changes`          | continuous feature/fix/incident lifecycle and incident baseline bypass | 12 |
+| `changes`          | continuous feature/fix/incident lifecycle, alignment-thread link, and incident baseline bypass | 12→16 |
 | `artifacts`        | intent/context/verification artifact registry       | 8C    |
 | `context_snapshots`| role/gate context, readiness, budget, execution seam, hashes, git head, provider refs | 10 |
 | `spec_learning_candidates` | approval-gated implementation discoveries for baseline convergence | 10 |
@@ -93,6 +93,8 @@ covers nineteen 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_items` | one-at-a-time owner choices, evidence, recommendations, durable effects, resolutions, delegation, deferral, and supersession history | 16 |
 
 Two rules make this work:
 
@@ -105,7 +107,7 @@ Two rules make this work:
 2. **Single writer for mutable tables, multi-writer for `events`.**
    `.ultra/state.db` opens in WAL with `busy_timeout=5000`. The MCP
    server holds the single writer connection for `baselines`, `tasks`, `sessions`,
-   `changes`, `workflow_runs`, `workflow_steps`, `artifacts`, `context_snapshots`,
+   `changes`, `decision_threads`, `decision_items`, `workflow_runs`, `workflow_steps`, `artifacts`, `context_snapshots`,
    `spec_learning_candidates`, `incidents`, `projection_jobs`, `telemetry`,
    `specs_refs`, and `migration_history`; the CLI calls
    those tools over stdio rather than opening its own writer. The
@@ -171,6 +173,24 @@ and tracked-spec drift atomically. Break-glass incident archive creates an open
 blocking reconciliation gap, so incident recovery can finish without falsely marking
 the project baseline healthy.
 
+### Human-agent decision authority
+
+Ultra separates autonomous evidence work from owner decision authority. The host reads
+the repository, runtime, tests, and primary sources first, then exposes only the earliest
+unresolved load-bearing choice. `decision.open` stores the recommendation, credible
+alternatives, evidence refs, and durable effects; a partial unique index guarantees one
+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
+`skills/ultra-think/references/decision-dialogue.md`; status, breadcrumb, and doctor expose
+only the current recovery surface.
+
 ## 4. Continuous changes — the daily unit of convergence
 
 After the initial baseline delivery, every fix, feature, redesign, or incident

package/docs/PLAN.zh-CN.md

@@ -10,8 +10,9 @@
 > Kimi Code 采用各自 native plugin 呈现，其他旧 runtime adapter 已退役。下文所有与此冲突的
 > memory/hindsight 章节仅作为历史实施记录，不再是当前需求或运行时契约。
 
-**当前状态**：v0.15.0；四宿主 native plugin、41 个 live MCP tool、
-schema 15.0（19 表）、typed research semantics、complete Change Contract、
+**当前状态**：v0.16.0；四宿主 native plugin、50 个 live MCP tool、
+schema 16.0（21 表）、one-question owner-agent decision dialogue、artifact checkpoint、
+workflow alignment gate、typed research semantics、complete Change Contract、
 acceptance coverage、mode-bound 双轴 review、verified learning/reconciliation provenance、
 Context Spine v2 / breadcrumb / spec-learning、持续 change/context/convergence/doctor、incident debug lane、
 checkpoint 恢复消费与跨宿主安装 provenance/doctor 已落地；npm 发布由

package/docs/ROADMAP.md

@@ -13,7 +13,7 @@ sharing one authoritative workflow store.
 
 **Distribution channels (v1.0)**: npm · Homebrew · pip.
 
-**Release line**: `0.14.x`; every release is gated by `npm run verify:release`.
+**Release line**: `0.16.x`; every release is gated by `npm run verify:release`.
 
 ---
 
@@ -47,24 +47,26 @@ sharing one authoritative workflow store.
 | 11    | Greenfield/brownfield baseline adoption + advisory context budgets + convergence gate | ✅ done |
 | 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 |
 | 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          (41 live tools across 7 families)
+├── mcp-tools.yaml          (50 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, 41 task/session/baseline/change/workflow/system/plan tools)
+├── server.cjs              (stdio MCP server, 50 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)
 │   ├── 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

@@ -71,7 +71,7 @@ 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 | 41 | 41 | 41 | 41 |
+| Live/declared contracts | 50 | 50 | 50 | 50 |
 | Greenfield/brownfield baseline adoption | FULL | FULL | FULL | FULL |
 | Context Spine v2 / breadcrumb | FULL | FULL, same bundled read-only DB reader as every hook | FULL | FULL |
 | Approval-gated spec learning | FULL | FULL | FULL | FULL |
@@ -79,7 +79,7 @@ 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 41 `task.*`, `session.*`, `baseline.*`, `change.*`, `workflow.*`, `system.*`, and `plan.*` operations
+All 50 `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.
 
@@ -126,9 +126,9 @@ records. Uninstall refuses an unmanaged or conflicting root.
 
 | Capability | Contract |
 |---|---|
-| Current state schema | `15.0` |
+| Current state schema | `16.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, then typed research semantics, complete Change Contracts, verified learning application, and reconciliation provenance in 15.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, then resumable owner-agent decision threads, artifact checkpoints, and workflow alignment gates in 16.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

@@ -4,17 +4,18 @@
 > risks R21 / R25.
 
 `.ultra/state.db` is the only authoritative state store for baselines, changes,
-tasks, workflow runs/steps, events, sessions, incidents, projections, telemetry, and spec references
+decision threads/items, tasks, workflow runs/steps, events, sessions, incidents,
+projections, telemetry, and spec references
 (D18, D52, D54). Every process
 that touches it must follow the rules below; deviations are bugs.
 
 ## 1. Three-role write matrix
 
-| Role | tasks | baselines | change/workflow/artifact state | events | sessions | telemetry | specs_refs | migration_history |
-|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
-| **MCP server** (single writer for mutables) | RW | RW | RW | RW | RW | RW | RW | RW |
-| **CLI** (`ultra-tools …`) | R | RW (init only) | R | RW (append-only) | R | R | R | RW (migration only) |
-| **Orchestrator daemon** | R | R | R | RW | RW | RW | RW | R |
+| Role | tasks | baselines | change/workflow/artifact state | decisions | events | sessions | telemetry | specs_refs | migration_history |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| **MCP server** (single writer for mutables) | RW | RW | RW | RW | RW | RW | RW | RW | RW |
+| **CLI** (`ultra-tools …`) | R | RW (init only) | R | R | RW (append-only) | R | R | R | RW (migration only) |
+| **Orchestrator daemon** | R | R | R | R | RW | RW | RW | RW | R |
 
 - **R** = read-only;
 - **RW** = read + write;
@@ -73,6 +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 |
 | `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/USER-HANDBOOK-CONTRACT.md

@@ -7,8 +7,8 @@ only one small managed section describing its runtime boundary.
 ## Source and render targets
 
 `adapters/_shared/handbook.cjs` is the canonical source. It renders the common
-authority, baseline adoption, Context Spine, specification-learning, memory, hook, agent, and
-package boundaries with host-native command syntax:
+authority, baseline adoption, decision dialogue, Context Spine, specification-learning,
+memory, hook, agent, and package boundaries with host-native command syntax:
 
 | Runtime | Default target | Main invocation form |
 |---|---|---|
@@ -31,6 +31,12 @@ a blocking reconciliation gap; hooks inject only the DB-derived
 axis blocks convergence. Detailed procedures remain in the plugin skills so user
 handbooks do not accumulate duplicated prompt sediment.
 
+The decision boundary is intentionally short but normative: project-bound owner
+choices use one resumable DB-backed thread; the host resolves observable facts first,
+presents only one current decision with evidence and a recommendation, and stores the
+normalized result rather than conversation text. Matching workflows remain gated until
+blocking choices are resolved and the owner-approved artifact checkpoint is current.
+
 ## Managed-block contract
 
 The owned content is bounded by: