ultra-builder-pro-cli 0.15.0 → 0.17.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 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,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 nineteen tables:
+covers twenty-one tables:
 
 | Table              | Holds                                             | Phase |
 |--------------------|---------------------------------------------------|-------|
-| `baselines`        | repository classification, greenfield/brownfield adoption, worktree snapshot, specs, evidence, verification, gap ledger, persisted known-red acceptance, and approval | 12→14 |
+| `baselines`        | repository classification, greenfield/brownfield adoption, explicit unborn/clean/dirty Git snapshot, specs, evidence, verification, gap ledger, persisted known-red acceptance, and approval | 12→17 |
 | `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 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
@@ -139,6 +141,19 @@ scripts, and monorepo markers. It detects `greenfield` or `brownfield`, records
 bounded classification evidence and selected repository scope, and creates the
 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 a disposition for each of the seventeen
+coverage areas and executes, verifies, or reuses only the evidence needed to converge
+the baseline.
+
+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
+the resulting `unborn` snapshot. Existing repositories keep their tracked ignore file
+unchanged. It never creates a commit, remote, tag, or push. An initialized
+repository cannot use a non-Git workspace hash: research must obtain approval for a
+local checkpoint commit before `baseline.record`.
+
 Projection-only v4.4 and v4.5 projects use `ultra-tools migrate` to preserve the
 entire `.ultra` tree, import tasks and events, and create a `migrated/adopting`
 compatibility row. Schema upgrades use `ultra-tools system doctor --repair` and
@@ -171,6 +186,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
@@ -192,7 +225,7 @@ impact, and no open incident. Memory and graph payloads never enter Ultra;
 
 ### Context Spine
 
-Context Manifest v2 is the immutable handoff contract between planning,
+Context Manifest v3 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;
@@ -201,19 +234,24 @@ implementation, checking, review, convergence, and recovery. Each snapshot recor
   execution contract;
 - advisory attention budgets (12 files / about 12k tokens / 40% by default);
 - a DB-derived execution contract (`slice_kind`, public seam, exact verification command);
-- one deterministic next action.
+- mechanically valid `allowed_transitions` and a `required_transition` only when a
+  hard invariant leaves one recovery route;
+- a digest of the accepted Change authority so semantic updates invalidate the
+  snapshot.
 
 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
+machine transitions. A host may attach a clearly non-authoritative recommendation.
+Critical 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,
-provider content, or a conversation summary. A changed git HEAD marks the
-snapshot stale and routes back to `change.context`.
+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`.
 
 PRD decomposition and complex-task subdivision use the active host model. The
 MCP accepts the resulting structured tasks, validates schema, topology,
@@ -255,10 +293,13 @@ authority and the legacy task projection before creating a new brownfield adopti
 A **session** is the standard unit of execution across all four runtimes
 (D20). One session =
 
-- a fresh OS process for the runtime,
-- an isolated `git worktree`,
+- one authoritative task/runtime lease;
+- an isolated `git worktree` created by `session.spawn`,
+- an ignored `.ultra` link from that checkout to the one central authority,
 - a lease + heartbeat row in `sessions` (D32),
-- an `artifact_dir` under `.ultra/sessions/<sid>/` for logs and scratch.
+- an `artifact_dir` under `.ultra/sessions/<sid>/` for logs and scratch;
+- either the active host operating in that exact worktree or an explicitly configured
+  worker process.
 
 Spawning a new session for a task is gated by `session.admission_check`
 (D33). If another session already owns an active lease on the same task,
@@ -272,6 +313,43 @@ This admission gate is the smallest piece that prevents two agents from
 silently double-writing the same task — it is part of the v0.1 minimum
 execution layer, not deferred to Phase 5.
 
+Process status is not task status. Exit zero closes transport evidence but leaves the
+task `in_progress` until workflow gates pass; failure blocks the task and records
+circuit evidence. `session.close` preserves its worktree by default. Explicit cleanup
+is allowed only when the worktree is clean and its commit is an ancestor of the
+current checkout.
+
+The optional `ubp-orchestrator` daemon requires both `auto_dispatch: true` and an
+explicit executable plus argument array. It refuses to create a session when no real
+worker can consume it. Before launch, the runner verifies that Git ignores the
+symlink itself. When a legacy repository has only the directory-specific `.ultra/`
+rule, the runner adds `.ultra` to the repository-local `info/exclude` file without
+changing a tracked file. It then binds the checkout to the central `.ultra` and rolls
+the worktree back if the ignore rule or binding cannot be established safely. The
+executable is launched without a shell and receives
+the session, task, runtime, worktree, artifact, central DB, checkout root, and
+authority-root paths through reserved `UBP_*` environment variables that caller
+configuration cannot override.
+Pending tasks are skipped while stale, dependency-blocked, circuit-broken, leased, or
+overlapping the declared files of an active task.
+
+`execute-plan` is a resumable dispatcher, not a second workflow authority. It runs
+only the exact current DB task graph whose change-bound `plan` workflow is completed,
+healthy, and current. Empty, cyclic, duplicate-task, cross-change, stale, and merely
+exported plans fail before session creation. Owner approval is present only when a
+material planning choice required it. The dispatcher then runs only pending tasks whose
+dependencies are DB-terminal and re-reads task state. If a
+worker exits before the task converges, the current wave and plan become `paused`;
+later waves remain pending. Re-running the command skips completed waves and resumes
+the first unfinished one. `wave_completed` and `plan_completed` therefore describe
+Ultra task convergence, while `wave_paused` and `plan_paused` preserve unfinished
+gate state. Even with explicit auto-merge, integration is attempted only when the
+change task is `completed`, its completion commit matches the session HEAD, its dev
+workflow is ready, and its task review is current; process exit zero is insufficient.
+If task or plan authority changes after wave selection but before worktree creation,
+dispatch reports an authority pause without recording a worker failure or incrementing
+the circuit breaker.
+
 ## 6. Compaction recovery — checkpoint as a validated consumer
 
 `workflow_checkpoint.py` validates the current non-terminal workflow and writes

package/docs/LEGACY-CLI-CROSSWALK.md

@@ -0,0 +1,163 @@
+# Original Ultra Builder Pro to CLI crosswalk
+
+This document is the compatibility contract between the original
+[`rocky2431/ultra-builder-pro`](https://github.com/rocky2431/ultra-builder-pro)
+Claude Code harness and this multi-runtime CLI/MCP implementation. Comparisons and
+migration rationale live here, not in runtime Skill prompts.
+
+## Provenance
+
+- Original baseline inspected at
+  [`a82a9d73efe14a2a94a6ac6aa1fd44ba905b2159`](https://github.com/rocky2431/ultra-builder-pro/tree/a82a9d73efe14a2a94a6ac6aa1fd44ba905b2159).
+- The CLI repository was bootstrapped from the original harness at `6deca47`.
+- The original delivery spine is six stages:
+  `init -> research -> plan -> dev -> test -> deliver`.
+- `status` and `think` support that spine. The original review Skill is a mandatory
+  development/release gate even though it was not a separate slash command.
+
+The compatibility target is semantic, not file-for-file. Host-specific Claude Code
+mechanics are replaced only when the replacement preserves the observable workflow
+contract and adds stronger authority, recovery, or portability.
+
+## What the CLI preserves and strengthens
+
+| 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 17 semantic areas as a coverage catalog with execute/verify/reuse/not-applicable/deferred dispositions | Preserved without questionnaire overload. Necessary reports, typed semantic records, source digests, and 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. |
+
+## CLI-original capabilities
+
+The following are deliberate extensions built on the original spine:
+
+1. `.ultra/state.db` as the only lifecycle authority; Markdown and JSON are artifacts
+   or projections.
+2. Typed MCP transitions for baseline, change, decision, workflow, task, session,
+   incident, projection, and evidence state.
+3. Greenfield, brownfield, monorepo-scope, migrated, restore, and rebaseline paths.
+4. `ultra-change` as the continuous post-baseline delta and convergence unit.
+5. `ultra-doctor` plus backup-first migration, projection repair, incident reporting,
+   orphan recovery, and installed-asset provenance.
+6. Context Manifest v3, Change/task authority digests, DB-derived breadcrumbs,
+   adaptive transitions, advisory context budgets, and fresh-context handoffs.
+7. Approval-gated specification learning and baseline reconciliation.
+8. Independent two-axis review and immutable test/review/delivery evidence.
+9. Native adapters for Claude Code, OpenCode, Codex, and Kimi Code.
+10. Explicit worktree admission, leases, heartbeats, crash evidence, circuit breaking,
+    dependency waves, and optional verified cleanup.
+
+## Intentionally retired original baggage
+
+These items are not compatibility losses:
+
+- embedded prompt, transcript, observation, summary, or cross-session memory;
+- an internal code graph or memory store;
+- retired model runtimes and their prompts;
+- retired command-proxy integrations;
+- imported browser, deployment, framework, discovery, or third-party Skills;
+- model-tier routing, confidence percentages, forced option counts, forced task
+  counts, automatic MVP selection, or silent scope reduction;
+- handwritten `tasks.json` authority or direct specification dual-write;
+- unsafe automatic push, release, merge, or worktree deletion.
+
+External memory and graph providers own their content. Ultra may store only bounded
+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.
+
+### New repository
+
+```text
+task.init_project
+  -> greenfield classification
+  -> Git bootstrap when absent
+  -> init read-back and completion
+  -> explicit full research with 17 coverage dispositions
+  -> selected execute/verify/reuse work and synthesis
+  -> owner-authorized local checkpoint commit when Git is unborn
+  -> baseline.record
+  -> baseline.converge
+  -> ultra-change
+  -> optional bounded research/plan -> dev tasks -> test -> review -> local deliver
+```
+
+### Existing repository
+
+```text
+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 17 coverage dispositions
+  -> characterization verification + known-red/gap ledger
+  -> baseline.record + owner approval
+  -> baseline.converge
+  -> first ultra-change
+```
+
+### Earlier Ultra authority
+
+```text
+doctor/migrate with backup
+  -> migrated compatibility row
+  -> explicit brownfield re-adoption
+  -> current research and evidence convergence
+  -> normal change loop
+```
+
+### Daily change
+
+```text
+status
+  -> change intent capture
+  -> material alignment only when unresolved
+  -> host-selected 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
+  -> safe session close
+  -> aggregate test -> review -> deliver
+  -> atomic baseline reconciliation
+```
+
+## Breakpoint closure
+
+| Prior breakpoint | Required invariant |
+|---|---|
+| Init was incorrectly held open until research and baseline convergence | Init completes only after classification, Git/scaffold setup, state creation, and read-back verification; research starts explicitly and owns baseline convergence. |
+| A fresh project had `.ultra` but no Git | Auto init creates `main`, adds the symlink-safe `.ultra` ignore rule, and exposes `initial_commit_required`. |
+| Initialized Git had no HEAD but baseline used a workspace hash | `unborn` is a persisted state; `baseline.record` fails with `BASELINE_GIT_HEAD_REQUIRED`. |
+| Resume preserved an incorrect project name/type/stack | In-progress resume refreshes corrected metadata and records the change. |
+| MCP session reservation and runner session were separate | `session.spawn` creates the actual worktree and the single authoritative session row. |
+| Process exit zero marked a task completed | Exit success leaves the task `in_progress` until dev/test/review evidence converges. |
+| Dependency waves advanced after transport exit | The plan pauses at the first non-terminal wave and resumes only after its DB tasks converge. |
+| A crafted or merely exported plan could bypass current plan authority | Change-owned dispatch requires a healthy completed plan workflow and the exact current DB graph; malformed, cyclic, stale, duplicate-task, or cross-change plans fail before session creation. |
+| Direct session or daemon spawn bypassed the current plan | Every change-owned admission and spawn revalidates current task-contract digests, task set, dependencies, and staleness before takeover or worktree creation. |
+| A worker launched inside a worktree could create a second `.ultra/state.db` | Every session checkout links its ignored `.ultra` entry to central authority and receives non-overridable DB/root bindings; legacy repositories get a local `info/exclude` rule without tracked drift, while unsafe ignore or link state rolls back before worker launch. |
+| Plan authority could drift between wave admission and actual spawn | The spawn-time gate converts this race into an authority pause without task-failure or circuit-breaker evidence. |
+| Explicit auto-merge could integrate before workflow gates | A change-owned auto-merge requires the exact completion commit, ready dev evidence, a current task review, and clean committed Git work; otherwise the worktree is preserved. |
+| Session close or auto-merge could delete uncommitted work | Close preserves by default; explicit cleanup verifies clean and integrated Git ancestry. |
+| Daemon could create a worktree with no worker | Dispatch refuses to start without an explicit executable command. |
+| Failure returned a task to pending without recovery evidence | Exit and spawn failures become `blocked` and record session-linked circuit-breaker evidence. |
+| A late resume failure could leave refreshed DB metadata behind | Resume snapshots DB authority and generated projections, then restores both together with Git rollback. |
+| A legacy schema migrated before a later resume failure | Resume restores the pre-migration backup, not the partially completed upgraded intermediate state. |
+
+## Advancement rule
+
+A stage advances only when its DB workflow definition reports every required step
+current and the stage-specific verifier accepts the referenced outputs. A Prompt,
+child-process exit, generated projection, or old document can never advance a stage.
+On interruption, resume the same non-terminal workflow and current step. On authority
+damage, route to doctor; on missing owner authority, route to think. Never open a
+parallel run to escape a blocker.

package/docs/PLAN.zh-CN.md

@@ -1,6 +1,6 @@
 # ultra-builder-pro-cli — 历史执行计划与决策日志
 
-> **2026-07-18 当前生效边界（D50-D55，覆盖下文旧 Phase 6/7 的内置图谱、memory 与 runtime 设计）**：
+> **2026-07-24 当前生效边界（D50-D60，覆盖下文旧 Phase 6/7 的内置图谱、memory 与 runtime 设计）**：
 > Ultra Builder Pro 不再拥有 `memory.*`、recall、prompt/transcript/observation/summary
 > 收集 hook 或私有 agent memory。跨会话记忆全部交给独立安装的 cloud-mem/claude-mem。
 > 插件只保留 12 个 Ultra 公共 workflow（新增 daily `ultra-change` 与诊断
@@ -10,10 +10,11 @@
 > 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、
-acceptance coverage、mode-bound 双轴 review、verified learning/reconciliation provenance、
-Context Spine v2 / breadcrumb / spec-learning、持续 change/context/convergence/doctor、incident debug lane、
+**当前状态**：v0.16.0 工作树；四宿主 native plugin、50 个 live MCP tool、
+schema 18.0（21 表）、host-native adaptive decision dialogue、material artifact checkpoint、
+adaptive capability graph、typed research coverage、complete Change Contract、
+acceptance coverage、risk-selected test/review、verified learning/reconciliation provenance、
+Context Spine v3 / transition breadcrumb / spec-learning、持续 change/context/convergence/doctor、incident debug lane、
 checkpoint 恢复消费与跨宿主安装 provenance/doctor 已落地；npm 发布由
 `v*.*.*` tag 触发。以下 Phase 0-9 正文保留为 2026-04 的实施历史，不再作为
 当前 runtime 或发布状态的事实来源。
@@ -30,7 +31,7 @@ checkpoint 恢复消费与跨宿主安装 provenance/doctor 已落地；npm 发
 - **Phase 4.6 拆 a/b**（R6 + D35）：v0.1 只跑 smoke flow，full conformance 推 v0.2
 - **Codex 第二轮结论**："小改后开工"（tl;dr）；本版已完成小改
 
-**总决策数**：D1-D55（当前边界以 D50-D55 为准）
+**总决策数**：D1-D60（当前边界以 D50-D60 为准）
 **总风险数**：R1-R32（v0.3.1 新增 R25-R32 共 8 条）
 
 ---
@@ -346,7 +347,7 @@ ultra-builder-pro-cli/
 | A2 | MCP server stdio 而非 HTTP | 4 runtime 全支持 stdio MCP；零端口、零防火墙问题 |
 | A3 | 单源 schema（spec/）驱动三层 | 避免 "skill 说的 tool" 与 "MCP 实际的 tool" 不一致 |
 | **A4** | **权威状态层 = SQLite + WAL**（`.ultra/state.db`）；tasks.json / context md / activity-log.json / workflow-state 全部降级为投影 | Codex Q1：多文件多主写入最易炸；SQLite 提供事务 + 并发读；D18 |
-| **A5** | **Session 标准单元 = 新进程 + 独立 worktree + lease/heartbeat + artifact dir**；`ctx.newSession()` 仅作 Claude/GSD-2 适配优化 | Codex Q7：跨 4 runtime 通用；systemd/launchd 过重；D20 |
+| **A5** | **Session 标准单元 = task/runtime lease + 真实独立 worktree + heartbeat + artifact dir**；由当前 host 或显式 worker 消费，process exit 不等于 task completion | D20 建立隔离单元，D56 修正空 worker 与退出即完成断点 |
 | A6 | 事件流 = state-db `events` 表（append-only）+ MCP subscribe | 取代 activity-log.json 文件；state-db 统一权威源（D18） |
 | A7 | Python hooks 沿用，Node shell out | 15 hook 重写 Node 要 2-3 周纯折腾；零价值 |
 | A8 | orchestrator 是可选的常驻 Node daemon | 规则层可不依赖执行层独立跑；半自动 → 全自动平滑升级 |
@@ -1645,6 +1646,11 @@ Week 18      buffer（ship 中任何 Phase 的 25% 滑动吃掉）
 | **D53** | **2026-07-17** | **Harness 缺口一次性闭环**：`incident` 成为带五段 `diagnosis.md` 结构门禁的 canonical debug lane；compact checkpoint 由 resume 消费、校验、择新并原子恢复；三宿主安装写 normalized provenance，`ubp --doctor` 只读校验 asset hash 与 plugin/hook/MCP/runtime contract | 将 GSD 的 debug/fresh context、GStack 的 checkpoint/readiness 与 ECC 的 doctor/provenance 思路收敛为 Ultra 自有契约；Memory 与图谱继续由外部 provider 所有，且不恢复任何已退役 surface |
 | **D54** | **2026-07-18** | **老项目接入与非阻断门禁闭环**：schema 11.0 新增 greenfield/brownfield baseline authority 与 `baseline.start/record/get/converge`；`task.init_project` 自动识别新旧仓库；上下文文件数、token 和占比改为 advisory warning，active change 的 baseline 问题同样只告警，`change.converge` / delivery 恢复硬门禁 | 避免 Ultra 把既有项目当新产品，也避免必要的 IM incident 因四个大文件超预算而无法施工；限制只在损坏权威、缺少执行契约、证据陈旧和最终收敛边界阻断 |
 | **D55** | **2026-07-18** | **新项目、老项目与旧版 Ultra 接入完成统一闭环**：schema 12.0 增加 repository branch/worktree digest、classification、gap ledger 与 incident bypass authority；`ultra-init` 自动分类、resume 只补缺失 scaffold、projection-only state 走支持的备份式 import、旧 DB 备份后升级、migrated baseline 必须显式 brownfield replacement；普通新 change 要求 ready baseline，已开工 change 保持可执行，紧急 incident 只允许有审批记录的 break-glass 并在 archive 写阻断 reconciliation gap | 老项目不再被重置或伪装成 greenfield/ready；历史任务、事件与文档可恢复迁移；健康项目可直接进入日常 change，损坏权威停在明确的 restore-or-rebaseline 决策边界 |
+| **D56** | **2026-07-24** | **以原始 `rocky2431/ultra-builder-pro` 为语义基线闭合 Git 与执行管线（覆盖 D48 的退出即完成语义）**：schema 17.0 增加 `unborn` Git authority；`task.init_project` 默认保留或建立 Git，resume 以 DB+projection snapshot 原子刷新进行中元数据；`session.spawn` 创建真实 worktree；进程成功不再越过 dev/test/review；spawn/exit 失败写 session-linked failure evidence；dependency wave 在首个未收敛任务处 pause，后续波次不启动；change-owned auto-merge 要求 exact completion commit、ready dev evidence 与 current task review；close 默认保留且仅在 clean+integrated 时删除；daemon 必须配置真实 worker | 原始 init/research/plan/dev/test/deliver 语义与 CLI 原创 DB/MCP/change/recovery 能力形成可恢复的单一管线；消除 scaffold 伪完成、无 HEAD baseline、双 session、空 worker、退出即完成、提前依赖推进、提前合并和 worktree 数据丢失 |
+| **D57** | **2026-07-24** | **当前宿主边界恢复为 Claude Code、OpenCode、Codex、Kimi Code（仅覆盖 D51 的宿主数量）**：四宿主均使用各自 native plugin/command/skill/MCP/hook 表示；Kimi 的 compact 动态注入限制保持显式 DEGRADED；已退役的模型 runtime、prompt 和模型路由保持删除 | 当前安装器、runtime assets、能力矩阵与 conformance tests 一致，不把 Kimi 支持误写成其他模型依赖，也不恢复任何已删除的外部 Skill、Memory 或命令代理 |
+| **D58** | **2026-07-24** | **所有 session 入口只能消费已批准且仍然 current 的 change plan**：`execute-plan` 校验 plan 结构、cycle、重复 task、change ownership、当前 DB task graph、已完成 plan workflow 及 artifact health；MCP admission/spawn 与 daemon 复用同一 task contract、dependency、staleness 和 plan-digest gate；所有检查都发生在 takeover 或 worktree mutation 之前 | 关闭 plan export、直接 MCP spawn 与 daemon 到实际执行之间的 authority 断点，保证 MCP/DB 的计划批准不能被手写 JSON、旧 artifact 或旁路入口绕过 |
+| **D59** | **2026-07-24** | **隔离 worktree 与中央 authority 分离但不分叉**：每个 session checkout 用 symlink-safe `.ultra` ignore 连接唯一中央 `.ultra`；旧仓库仅追加 repository-local `info/exclude`，不修改 tracked baseline；worker 获得不可覆盖的 DB/checkout/authority-root 环境；链接失败原子回滚；plan 在 wave admission 与 spawn 间漂移只 pause、不计 worker failure；旧 schema 的 late-resume 失败恢复迁移前备份 | 关闭自动 worker 在 worktree 中误建第二个 state.db、authority 链接被 Git 提交、竞态误触发 circuit breaker，以及旧版项目失败回滚停在半迁移状态的断点 |
+| **D60** | **2026-07-24** | **从硬管线升级为自适应能力图**：init 在分类、Git/scaffold 与 read-back 后独立完成且不隐式启动 research；17 项 research 改为 execute/verify/reuse/not-applicable/deferred coverage disposition；change 只捕获意图合同；plan approval 仅在 material decision 时需要；test/review 按风险选 profile；deliver 只做本地收敛归档，外部发布独立授权；MCP 只给 allowed/required transitions，宿主负责语义建议与 native question UI；Change 语义变更自动使任务与 Context v3 失效；schema 18 迁移旧 workflow state | 保留原始 Harness 的 research/plan/dev/test/review/deliver 能力与人机同步核心，同时消除 init/research 混合、固定 17 步执行、重复审批、唯一 next action、Hook 阻塞和新意图复用旧证据等机械化断点 |
 
 ---
 
@@ -1663,13 +1669,14 @@ Week 18      buffer（ship 中任何 Phase 的 25% 滑动吃掉）
   + event subscribe + 活跃会话可见；Phase 4.5 / D19。
 - **execution-plan.json**：8A 产出的可审计规划 artifact（waves + ownership
   + conflict），驱动 8B 分派；D34。
-- **Orchestrator**：Phase 5+ 引入的 Node daemon，负责 session 生命周期 +
-  事件循环 + 分派。
+- **Orchestrator**：Phase 5+ 引入的显式 worker 执行层；`execute-plan` 消费
+  dependency waves，daemon 仅在 opt-in 且配置真实 executable 时轮询分派。
 - **规则层 / 执行层**：§4.2；Phase 1-4 / Phase 4.5-8。
-- **Session**：GSD-2 模式升级版（D20）：新进程 + 独立 worktree + lease/
-  heartbeat（存 sessions 表） + artifact dir；Phase 4.5 实装。
+- **Session**：GSD-2 模式升级版（D20/D56）：真实独立 worktree + lease/
+  heartbeat（存 sessions 表） + artifact dir；由当前 host 或显式 worker
+  消费，进程退出不等于 task 完成。
 - **state.db**：`.ultra/state.db` SQLite + WAL 数据库，所有 Ultra workflow
-  状态的权威源；当前 17 表，包含 baselines、changes、artifacts、
+  状态的权威源；当前 21 表，包含 baselines、changes、artifacts、
   context_snapshots、spec_learning_candidates、trace_links、incidents、
   projection_jobs 与 event_consumers；Phase 2 建立，D52-D54 扩展。
 - **三层架构**：§4.1；skill（知识，只读发现）+ MCP（状态操作主路径）+

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 | `18.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, 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 |
 | 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: