ultra-builder-pro-cli 0.14.0 → 0.16.0

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 36 live tools across baseline/task/session/change/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,11 +70,11 @@ 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 seventeen tables:
+covers twenty-one tables:
 
 | Table              | Holds                                             | Phase |
 |--------------------|---------------------------------------------------|-------|
-| `baselines`        | repository classification, greenfield/brownfield adoption, worktree snapshot, specs, evidence, verification, gap ledger, and approval | 12 |
+| `baselines`        | repository classification, greenfield/brownfield adoption, worktree snapshot, specs, evidence, verification, gap ledger, persisted known-red acceptance, and approval | 12→14 |
 | `tasks`            | task rows — id, status, deps, files_modified, …   | 2     |
 | `events`           | append-only event stream; `id` is subscription cursor (D31) | 2 |
 | `sessions`         | execution sessions, **including lease + heartbeat fields** (D32) | 4.5 |
@@ -83,7 +83,7 @@ covers seventeen 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 |
@@ -91,6 +91,10 @@ covers seventeen tables:
 | `incidents`        | structured runtime failures and resolutions         | 8C    |
 | `projection_jobs` | durable projection outbox/retry state                | 8C    |
 | `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:
 
@@ -103,12 +107,16 @@ 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`, `context_snapshots`, `spec_learning_candidates`, `telemetry`,
+   `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
    `events` table is append-only and explicitly multi-writer — CLI and
    orchestrator processes append directly to it under the same WAL +
    `busy_timeout` discipline, since independent INSERTs do not conflict.
+   External writers and public `task.append_event` may append observations only;
+   lifecycle event names are emitted by the mutation that owns the corresponding
+   DB transition and no event row can substitute for that transition.
    In `spec/mcp-tools.yaml` this split is captured by `writer_role: mcp`
    (must go through the MCP server) versus `writer_role: any` (any
    process may execute). Full policy lives in
@@ -143,20 +151,46 @@ produce a pre-migration backup. Compatibility state never grants baseline approv
 references, bounded repository/runtime evidence, actual verification results,
 known unknowns, repository branch and worktree snapshot, the categorized gap ledger,
 and metadata-only external provider references, and
-`baseline.converge` records explicit owner approval. A ready baseline is replaced
-only by an explicit re-adoption, preserving the superseded row for recovery.
+`baseline.converge` records explicit owner approval, including a durable
+`known_red_accepted` decision when applicable. Read paths continuously revalidate
+ready authority: scope, three specifications, source/runtime evidence, verification,
+known-red rationale and acceptance, research provenance and output digests, repository
+revision/worktree state, blocking gaps and unknowns, approver, and convergence time.
+A row cannot become trusted merely because its stored status says `ready`. A ready
+baseline is replaced only by an explicit re-adoption, preserving the superseded row
+for recovery.
 For a selected monorepo scope, the worktree digest and dirty-file list include only
 that scope; out-of-scope changes remain visible repository context but cannot be
 accepted implicitly by `accept_dirty_worktree`.
 
-New ordinary changes require a healthy `ready` baseline. A change that was already
-active may continue with baseline drift surfaced as a warning. A new incident can
+New ordinary changes require a healthy `ready` baseline. An active ordinary change may
+continue through only the expected HEAD/worktree/spec/source drift created after its
+durable `bind-baseline` step; loss of ready approval, missing evidence, blocking gaps,
+or any other structural defect stops task/context/stage progression. A new incident can
 start on an unhealthy baseline only with an explicit reason and approver stored in
 `baseline_bypass_json`. Ordinary convergence and archive reconcile HEAD, worktree,
 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
@@ -167,7 +201,7 @@ active -> blocked -> active -> ready -> archived
    |                              |
    ├─ intent + delta + plan       └─ verification + baseline reconciliation
    ├─ linked tasks
-   ├─ context-manifest v2 (role + gate + readiness + execution seam)
+   ├─ immutable context snapshots (role + gate + readiness + execution seam)
    └─ spec-learning candidates (proposed -> approved/rejected -> applied)
 ```
 
@@ -178,17 +212,23 @@ impact, and no open incident. Memory and graph payloads never enter Ultra;
 
 ### Context Spine
 
-Context Manifest v2 is the handoff contract between planning, implementation,
-checking, review, convergence, and recovery. Each snapshot records:
+Context Manifest v2 is the immutable handoff contract between planning,
+implementation, checking, review, convergence, and recovery. Each snapshot records:
 
 - one role (`plan`, `implement`, `check`, or `review`) and lifecycle gate;
 - required context references with local digests and reasons;
 - readiness blockers for missing/stale required references or an incomplete
   execution contract;
 - advisory attention budgets (12 files / about 12k tokens / 40% by default);
-- an execution contract (`slice_kind`, public seam, exact verification command);
+- a DB-derived execution contract (`slice_kind`, public seam, exact verification command);
 - one deterministic next action.
 
+Prompt input may identify the intended role/gate, add bounded reference candidates,
+and lower advisory budgets. It cannot supply or override the task seam, verification
+command, task context references, evidence digest, gate verdict, workflow summary, or
+next action. Critical change/dev/test/review/deliver workflow steps record the matching
+snapshot as an output; test, review, and delivery reports carry its digest forward.
+
 `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,
@@ -315,6 +355,7 @@ shippable; downstream slip never blocks an earlier release.
 | Exact SQLite schema?                               | [`spec/schemas/state-db.sql`](../spec/schemas/state-db.sql) |
 | What does a tasks.json look like after projection? | [`spec/fixtures/valid/tasks.v4.5.json`](../spec/fixtures/valid/tasks.v4.5.json) |
 | Phase-by-phase work breakdown + decision log       | [`docs/PLAN.zh-CN.md`](./PLAN.zh-CN.md)             |
+| When does each workflow write, invalidate, and converge state? | [`docs/WORKFLOW-LIFECYCLE.md`](./WORKFLOW-LIFECYCLE.md) |
 
 ## 10. Verifying the architecture
 

package/docs/PLAN.zh-CN.md

@@ -10,8 +10,10 @@
 > Kimi Code 采用各自 native plugin 呈现，其他旧 runtime adapter 已退役。下文所有与此冲突的
 > memory/hindsight 章节仅作为历史实施记录，不再是当前需求或运行时契约。
 
-**当前状态**：v0.13.0；四宿主 native plugin、36 个 live MCP tool、
-schema 12.0（17 表）、portable Skill authoring contract、双轴 review、
+**当前状态**：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 发布由
 `v*.*.*` tag 触发。以下 Phase 0-9 正文保留为 2026-04 的实施历史，不再作为

package/docs/ROADMAP.md

@@ -13,7 +13,7 @@ sharing one authoritative workflow store.
 
 **Distribution channels (v1.0)**: npm · Homebrew · pip.
 
-**Release line**: `0.11.x`; every release is gated by `npm run verify:release`.
+**Release line**: `0.16.x`; every release is gated by `npm run verify:release`.
 
 ---
 
@@ -45,24 +45,29 @@ sharing one authoritative workflow store.
 | 8C    | Continuous change packets + context compiler + convergence + doctor | ✅ done (D52) |
 | 10    | Context Spine v2 + breadcrumb + fresh-context budget + spec learning + two-axis review | ✅ done |
 | 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          (36 live tools across 6 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, 36 baseline/task/session/change/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)
 
@@ -70,7 +75,7 @@ ultra-tools/                ← CLI fallback, migration, and diagnostics
 ├── cli.cjs
 └── commands/
     ├── db.cjs              (init/checkpoint/vacuum/integrity/backup)
-    ├── migrate.cjs         (v4.4 projection → v4.5 authority; v4.5 projection → schema 12; dry/rollback)
+    ├── migrate.cjs         (v4.4 projection → v4.5 authority; v4.5 projection → current schema; dry/rollback)
     └── legacy-memory.cjs   (explicit inspect/archive/confirmed prune)
 
 bin/install.js              ← multi-runtime installer
@@ -81,6 +86,7 @@ hooks/                      ← 7 executable workflow hooks + shared Context Spi
 docs/
 ├── PLAN.zh-CN.md                historical phase plan + decision log
 ├── 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    managed CLAUDE.md / AGENTS.md boundary
 ├── RUNTIME-COMPAT-MATRIX.md     Phase 4 runtime capability matrix

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 | 36 | 36 | 36 | 36 |
+| 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 36 `baseline.*`, `task.*`, `session.*`, `change.*`, `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 | `12.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, then runtime constraint compatibility in 12.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, 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/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;
@@ -31,7 +32,11 @@ write API for normal task, change, session, or baseline lifecycle updates.
 The append-only carve-out for `events` exists because `events.id INTEGER
 PRIMARY KEY AUTOINCREMENT` makes concurrent inserts collision-free under
 WAL + `busy_timeout`. This lets hooks and short-lived CLI invocations
-record audit events without paying the cost of a full MCP round trip.
+record audit observations without paying the cost of a full MCP round trip.
+It does not grant lifecycle authority: external writers and public
+`task.append_event` use the published observation allowlist, while lifecycle event
+names are emitted only inside the mutation that owns the corresponding state change.
+Consumers must verify mutable rows rather than infer success from an event name.
 
 ## 2. Connection discipline
 
@@ -40,31 +45,27 @@ Every process **must**:
 1. Open the database with WAL + `busy_timeout=5000` + `foreign_keys=ON`.
    Use `mcp-server/lib/state-db.cjs` `openStateDb` so the pragmas are
    applied uniformly.
-2. Wrap every write in `BEGIN IMMEDIATE` (use the helper `withWrite(db,
-   fn)` once Phase 2.3 lands; until then call `db.transaction(fn)()` and
-   know that better-sqlite3 promotes to IMMEDIATE on the first write).
-3. Retry up to **3 times** on `SQLITE_BUSY`, with exponential backoff
-   starting at 25 ms. Each retry must re-issue the full transaction —
-   never partially commit.
+2. Wrap every mutable state operation with `state-ops.cjs` `tx(db, fn)`. The
+   helper calls better-sqlite3's immediate transaction variant, so the writer
+   lock is acquired before user code runs and the whole operation rolls back on
+   failure.
+3. Retry the complete transaction up to **10 attempts** on `SQLITE_BUSY`, using
+   decorrelated jitter from a 50 ms base with a 2 s cap. Never retry only a
+   suffix of a failed transaction or preserve partial state.
 4. Close the connection in a `finally` block. WAL files (`-wal`,
    `-shm`) are reclaimed on the last writer's close.
 
 Reads never need explicit transactions; better-sqlite3 reads observe a
 consistent snapshot under WAL.
 
-## 3. WAL fallback
+## 3. WAL requirement
 
-WAL is **unsafe on NFS / SMB / certain Docker bind mounts** (R21). When
-`.ultra/state.db` resides on such a filesystem the orchestrator must
-either:
-
-- refuse to start (preferred — surfaces the deployment problem early), or
-- downgrade to `PRAGMA journal_mode = DELETE` and warn loudly. Concurrent
-  writers fall back to short-burst contention; throughput drops but
-  correctness holds.
-
-Detection happens at boot: `statvfs` of `.ultra/state.db`'s mount;
-`f_type` ∈ `{NFS_SUPER_MAGIC, SMB_SUPER_MAGIC}` ⇒ refuse / downgrade.
+WAL is part of the authority contract, not an optional performance setting.
+`openStateDb` asks SQLite to enable WAL and checks the actual returned mode. If
+the storage layer returns anything else, startup fails with
+`STATE_DB_WAL_UNAVAILABLE`. Ultra does not silently downgrade to a different
+concurrency model. Move `.ultra/state.db` to storage that supports SQLite WAL or
+resolve the mount/runtime constraint before retrying.
 
 ## 4. Where each table is owned
 
@@ -73,9 +74,11 @@ Detection happens at boot: `statvfs` of `.ultra/state.db`'s mount;
 | `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 |
-| `events`           | MCP server **and** any process via append-only INSERT  |
+| `events`           | MCP server for lifecycle events; approved processes and `task.append_event` for allowlisted append-only observations |
 | `sessions`         | MCP server (`session.spawn` / `session.close` / `session.heartbeat`); orchestrator may write status transitions |
 | `telemetry`        | MCP server (collected from tool-call wrappers); orchestrator may dump bulk samples |
 | `specs_refs`       | MCP server (rebuilt on `spec_changed` event); orchestrator may rebuild |
@@ -110,6 +113,7 @@ The contract on this page is enforced by:
   appending to `events` simultaneously; asserts no `SQLITE_BUSY` escapes
   the retry loop and the resulting `events.id` sequence has no gaps and
   no duplicates.
-- Phase 2.3 will add `concurrency-update.test.cjs` — 20 worker threads
-  driving `task.update` against disjoint task ids, verifying serialized
-  writes through the MCP server.
+- `mcp-server/tests/state-ops.test.cjs` — immediate transactions, rollback,
+  status transitions, task contracts, and event coupling.
+- `mcp-server/lib/workflow-state.test.cjs` — ordered workflow transitions,
+  evidence/output requirements, blocking/resume, and cross-stage gates.

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: