ultra-builder-pro-cli 0.16.0 → 0.17.1

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,11 +10,11 @@
 > Kimi Code 采用各自 native plugin 呈现，其他旧 runtime adapter 已退役。下文所有与此冲突的
 > memory/hindsight 章节仅作为历史实施记录，不再是当前需求或运行时契约。
 
-**当前状态**：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、
+**当前状态**：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 或发布状态的事实来源。
@@ -31,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 条）
 
 ---
@@ -347,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 | 规则层可不依赖执行层独立跑；半自动 → 全自动平滑升级 |
@@ -1646,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 阻塞和新意图复用旧证据等机械化断点 |
 
 ---
 
@@ -1664,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/RUNTIME-COMPAT-MATRIX.md

@@ -126,9 +126,9 @@ records. Uninstall refuses an unmanaged or conflicting root.
 
 | Capability | Contract |
 |---|---|
-| Current state schema | `16.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, typed research semantics and verified reconciliation in 15.0, then resumable owner-agent decision threads, artifact checkpoints, and workflow alignment gates in 16.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/WORKFLOW-LIFECYCLE.md

@@ -9,9 +9,9 @@ host and project owner. It is the operational companion to
 
 | Surface | Owns | Must not own |
 |---|---|---|
-| Active host and owner | Product judgment, research content, implementation, review findings, release authorization | Durable workflow status or fabricated evidence digests |
+| Active host and owner | Product judgment, research content, implementation, review findings, and authorization for destructive or external effects | Durable workflow status or fabricated evidence digests |
 | Skill | One reusable procedure and its evidence requirements | Project state, static product doctrine, host-specific tool fiction |
-| MCP | IDs, transitions, task contracts, evidence references, output hashes, gate verdicts, next action | Research prose, code generation, memory, or model calls |
+| MCP | IDs, valid transitions, hard recovery requirements, task contracts, evidence references, output hashes, and gate verdicts | Semantic route selection, research prose, code generation, memory, or model calls |
 | `.ultra/state.db` | Baseline, change, decision, task, workflow, session, event, incident, projection, and evidence authority | Prompts, transcripts, external memory, or code-graph payloads |
 | Generated JSON and Markdown | Read-only projections and durable artifacts | Independent lifecycle authority |
 | Hook | Compact DB-derived lifecycle observation, minimal event metadata, and projection protection | Generic engineering judgment, prompt/transcript capture, parallel lifecycle logs, or arbitrary edit blocking |
@@ -20,7 +20,8 @@ Prompt input can supply facts, content paths, reasons, owner decisions, and
 evidence references. MCP reads the current repository and DB, validates those
 inputs, hashes outputs, and derives status. Prompt input cannot override a task's
 public seam, verification command, context references, workflow summary, gate
-verdict, output digest, or next action.
+verdict, output digest, or transition validity. A host recommendation is never stored
+as MCP authority.
 
 Load-bearing owner choices are normalized through `decision.*`; Prompt prose is not
 durable authority. The host acquires observable facts autonomously, exposes one
@@ -34,10 +35,12 @@ authority, and no new stage may start on an archived or cancelled change. Doctor
 recovers a legacy change without this link into an explicitly blocked workflow;
 it does not fabricate the missing provenance.
 
-Ultra does not select an MVP. Product scope and delivery posture are owner
-decisions. A reduced research mode is valid only for an explicitly bounded active
-change with a recorded selection reason; initial greenfield and brownfield
-baselines always use all seventeen research steps.
+Ultra does not select an MVP. Product scope and material delivery posture are owner
+decisions. The seventeen research areas are a coverage catalog, not a forced
+questionnaire. Initial greenfield and brownfield research must disposition every area
+as `execute`, `verify_existing`, `reuse`, `not_applicable`, or accepted `deferred`;
+only selected necessary work executes. Bounded change research records the same
+selection rationale over its smaller scope.
 
 ## 2. How `ultra-init` classifies a repository
 
@@ -65,9 +68,22 @@ worktree digests and accepted dirty files are restricted to that scope.
 
 Classification and readiness are separate. Initialization immediately creates
 or resumes `.ultra/state.db`, installs only the required scaffold, records the
-classification, opens an `init` workflow, and opens `full` research for
-greenfield or `adoption` research for brownfield. Empty templates are not an
-approved baseline.
+classification, and completes an `init` workflow after read-back verification. It
+does not create a research run. A later explicit `ultra-research` invocation selects
+`full` for greenfield or `adoption` for brownfield, records coverage dispositions, and
+works toward baseline readiness. Empty templates are not an approved baseline.
+
+With `git_mode: auto`, initialization preserves an existing repository and HEAD.
+When Git is absent it initializes `main` and adds the symlink-safe `.ultra` rule to
+`.gitignore`; an existing repository keeps its tracked ignore file unchanged. Init
+does not create a commit, remote, tag, or push. The resulting `unborn` worktree state
+is durable authority, not equivalent to a non-Git workspace. Full/adoption research
+must obtain explicit approval for one local checkpoint commit before
+`baseline.record`; until then `BASELINE_GIT_HEAD_REQUIRED` blocks convergence.
+
+Init completion means only that local authority, Git state, scaffold, and
+classification are usable. Baseline readiness is a separate research and convergence
+outcome; failure there never reopens or blocks the completed init workflow.
 
 ## 3. Durable status machines
 
@@ -124,6 +140,40 @@ traceability, slice kind, public seam, exact verification command, acceptance
 checks, context references, resolved documentation impact, owner, and valid
 dependencies.
 
+A semantic Change update marks all derived tasks stale. Clearing that marker requires
+one complete execution-contract rebind through `task.update`; a marker-only clear is
+rejected. MCP validates the resulting contract and appends
+`task_contract_reconciled` with the current Change authority digest before a new plan
+may converge.
+
+A session process and a task have different status machines. Process exit zero closes
+the execution transport but leaves the task `in_progress` until development,
+integration, test, and review gates converge. Process failure marks the task `blocked`
+and records failure/circuit evidence. `session.close` preserves the worktree by
+default. Explicit removal succeeds only after Git proves it is clean and its commit is
+integrated into the current checkout.
+
+Dependency-wave automation advances only when every task in the current wave is
+`completed` or `expanded` in the DB. A successful worker exit with open gates emits
+`wave_paused` and `plan_paused`; it cannot start dependent work. Re-running the plan
+resumes the first unfinished wave. Explicit auto-merge is additionally gated by task
+completion, an exact completion commit, a ready dev workflow, a current task review,
+clean committed work, and successful integration; otherwise the worktree remains
+recoverable. Legacy tasks without change ownership retain their compatibility path,
+but cannot satisfy the current change workflow contract.
+
+Every session worktree resolves its ignored `.ultra` entry to the project authority
+directory. Automated workers receive the central DB path and the isolated checkout
+root separately; their supplied environment cannot override those bindings. If a
+legacy `.ultra/` rule does not ignore the link itself, Ultra adds a repository-local
+`info/exclude` entry without changing tracked files. A missing, tracked, still
+unignored, or conflicting authority entry fails before the session row or worker is
+created and the provisional worktree is removed. A process that already has
+`UBP_SESSION_ID` must reuse that lease and worktree; nested spawn and worker-side close
+are rejected, so the supervising parent alone settles the lease from the real process
+exit. Authority drift detected after wave selection pauses the plan without recording
+execution failure.
+
 ### Workflow run and step
 
 ```text
@@ -160,19 +210,19 @@ case. It never stores the conversation transcript.
 
 ## 4. Write and verification lifecycle
 
-| Stage | Authoritative writes | Completion verification | Next route |
+| Stage | Authoritative writes | Completion verification | Available continuation |
 |---|---|---|---|
-| `init` | Baseline classification/scope, init run, research run, initialization event, projection job | DB/schema opens, scaffold/projection succeeds; baseline convergence later completes init | `research`, re-adoption, or `change` for an already-ready baseline |
-| `research` | Ordered step evidence, decision threads/checkpoints, typed semantic records with source digests, one immutable report per selected step, output paths and SHA-256 digests | Every load-bearing owner decision is confirmed; every report has the required structure; semantic kinds/attributes/source anchors are valid and current; full/adoption synthesis binds the current three specifications and distillate; all digests remain current | `baseline.record`, then approval/convergence; bounded change research returns to its change |
+| `init` | Baseline classification/scope, Git bootstrap state, completed init run, initialization event, projection job | DB/schema opens, scaffold/projection and read-back succeed; existing Git is preserved or missing local Git is initialized | Explicitly chosen `research`, `status`, or `doctor`; an already-ready project may also enter `change` |
+| `research` | Coverage dispositions, selected step evidence, material decision checkpoints, typed semantic records with source digests, immutable reports, output paths and SHA-256 digests | Every coverage area is dispositioned; only executed/verified/reused areas require work evidence; synthesis binds current specifications and distillate; all material decisions and digests are current | Baseline record/convergence for initial research; bounded change research returns to its owning change |
 | baseline convergence | Spec/source/runtime refs, verification results, known failures, unknowns, gaps, branch/HEAD/worktree, approval | Full/adoption research complete; required discovery/product/architecture refs current; revision/worktree exact; blocking gaps resolved or explicitly accepted where allowed | `change` for every initial or daily outcome |
-| `change` | Baseline-bound alignment checkpoint, complete Change Contract, profile/risk rationale, research disposition, intent/delta artifacts, linked change run, initial context snapshot | The linked alignment thread is confirmed; selected change research is current; current plan task set matches DB; task-bound context is ready; one next action is derived | selected `research`, then `plan`, or `dev` for an already approved current plan |
-| `plan` | Plan decision checkpoint, plan-step evidence, complete change-owned task rows, acceptance coverage matrix, change-bound `.ultra/execution-plan.json`, explicit plan approval | Blocking planning choices are confirmed; every Change acceptance id is owned by a task; task trace targets resolve; quick has one task; ownership/dependencies valid; no cycles; exported topology and digest exactly match the current change task set | `dev` for the first dependency-ready task |
-| `dev` | Task/session transitions, step evidence, immutable implementation context, completion/review references | Task completed; no live session; task contract unchanged; starting context and review artifacts valid; completion commits remain ancestors of current HEAD | Next task, then aggregate `test` |
-| `test` | Immutable checking context and `.ultra/reports/tests/<workflow-id>.json` | Report change/task set, full HEAD, worktree digest, context digest, commands, public seam, blockers, and all acceptance/regression/integration/static/build/performance/security/recovery dimensions agree; every omission has a not-applicable rationale | `review` when passing, otherwise resume `dev`/`test` |
-| `review` | Immutable review context, `task`/`change`/`plan` mode, worker selection provenance, two specialist axes, coordinated summary | Current diff/HEAD and context match; selected/skipped workers match recorded rationale; both axes complete; P0/P1 and axis verdicts deterministically derive final verdict | `deliver` only from approved `change` mode, otherwise resume implementation |
-| `deliver` | Convergence context, verified learning resolutions, schema-validated semantic reconciliation manifest, change archive, durable release-authorization decision, immutable delivery report | Tasks/test/change-review current; every baseline update has an anchored before/after semantic record; `change.converge` derives evidence from DB and accepts no Prompt verdicts; archive and baseline transaction agree; external actions have evidence | Report completion or start the next `change` |
-| `status` | None | Reads doctor, baseline, workflows, breadcrumb, tasks, sessions, Git, and DB-referenced reports | One exact current route |
-| `doctor` | None by default; explicit repair writes only mechanical recovery state | Re-runs integrity, schema, workflow-output, projection, session, incident, archive, and install checks | Exact repair, restore/rebaseline decision, or workflow route |
+| `change` | Complete Change Contract, profile/risk rationale, research disposition, intent/delta artifacts, and a completed capture run; a decision thread only when material intent remains unresolved | Intent, acceptance, recovery, classification, and research disposition are complete and bound to the baseline | Host selects among bounded `research`, `plan`, current `dev`, `think`, or `status` using allowed transitions |
+| `plan` | Selected planning evidence, complete change-owned task rows, acceptance coverage matrix, and change-bound `.ultra/execution-plan.json`; approval only for a material owner decision | Every Change acceptance id is owned by a task; trace targets, ownership, dependencies, topology, task contracts, and exported digest match current authority | Any dependency-ready task may enter `dev` |
+| `dev` | Task/session transitions, real worktree, step evidence, immutable implementation context, completion/review references | Task completed; no live session; task contract unchanged; starting context and review artifacts valid; completion commits are integrated and remain ancestors of current HEAD | Next task, then aggregate `test` |
+| `test` | Immutable checking context, an explicit risk-selected verification profile, and `.ultra/reports/tests/<workflow-id>.json` | Selected dimensions and acceptance pass; every excluded dimension has a rationale; report change/task set, HEAD, worktree, context, commands, blockers, and digests agree | `review` when passing, otherwise resume `dev`/`test` |
+| `review` | Immutable review context, `task`/`change`/`plan` mode, risk-selected worker provenance, two mandatory specialist axes, and coordinated summary | Current diff/HEAD and context match; the complete worker roster is selected or skipped with rationale; completed workers match specialist artifacts; both axes complete; findings and axis verdicts derive the final verdict | `deliver` only from a passing `change` review, otherwise resume implementation or checking |
+| `deliver` | Convergence context, verified learning resolutions, semantic reconciliation manifest, local change archive, and immutable delivery report | Tasks/test/change-review are current; baseline semantic updates are anchored; archive and baseline transaction agree; the report contains no release action | Report local completion or start the next `change`; publish/deploy/push are separate explicitly authorized operations |
+| `status` | None | Reads doctor, baseline, workflows, breadcrumb, tasks, sessions, Git, and DB-referenced reports | Shows allowed transitions, any hard required transition, and a host-owned recommendation |
+| `doctor` | None by default; explicit repair writes only mechanical recovery state | Re-runs integrity, schema, workflow-output, projection, session, incident, archive, and install checks | Mechanically required recovery when unique; otherwise a set of safe recovery capabilities |
 
 Every mutating MCP operation appends an event and enqueues projection work when
 the corresponding read-only view can change. Projection failure is recorded as
@@ -183,28 +233,30 @@ emitted by their owning DB mutation and never act as a substitute state transiti
 ## 5. Human-agent alignment lifecycle
 
 The host first reads `decision.list` and resumes matching authority. It starts a new
-thread only for a new decision cluster. For every current decision it must:
+thread only for a new material decision cluster. Before asking, it must:
 
 1. inspect repository, runtime, tests, specifications, and primary-source evidence;
 2. resolve evidence-answerable facts without asking the owner;
-3. call `decision.open` for the earliest unresolved owner choice with a recommendation,
-   no more than three credible alternatives, evidence refs, and durable effects;
-4. present that one choice and end the turn;
-5. normalize the next owner response with `decision.resolve`, explicit reversible
+3. normalize an unambiguous decision already present in the current user request
+   instead of asking for redundant confirmation;
+4. ask only when the remaining choice changes intent, public behavior, compatibility,
+   security, material cost, external effects, or recovery. Use the host-native
+   question surface declared by `spec/interaction-contract.json`;
+5. present the earliest dependent choice with a recommendation, credible alternatives,
+   evidence refs, and durable effects. Up to three independent low-load facts may be
+   grouped when that reduces inconsistency;
+6. normalize the owner response with `decision.resolve`, explicit reversible
    delegation with `decision.delegate`, or a consequence-bearing deferral with
    `decision.defer`;
-6. prepare one compact checkpoint, obtain one owner approval, update the affected
-   artifact, and confirm the checkpoint with its current digest. Workflow- and
-   change-bound threads must bind an artifact. If a shared specification will keep
-   evolving, bind a stable per-thread decision projection rather than the mutable
-   working draft.
+7. prepare a compact checkpoint only when a material decision cluster changes a
+   durable contract and interruption recovery needs an artifact-bound boundary.
 
 `ultra-think` owns this interaction protocol. `ultra-research`, `ultra-change`, and
 `ultra-plan` invoke it at their decision boundaries. `ultra-dev`, `ultra-test`,
 `ultra-review`, and `ultra-deliver` stop and route back to the same thread when new
 owner authority is required; they never answer on the owner's behalf. `ultra-status`
-shows only the current decision and exact route, while `ultra-doctor` diagnoses stale
-checkpoint artifacts and recovery state.
+shows only the current decision and transition set, while `ultra-doctor` diagnoses
+stale checkpoint artifacts and recovery state.
 
 When only a bound artifact changes, the same resolved thread is prepared and approved
 again against the current digest; this is checkpoint renewal, not a fabricated decision
@@ -213,7 +265,7 @@ opens one replacement.
 
 ## 6. Context and prompt follow-through
 
-`change.context` compiles an immutable Context Manifest v2 snapshot. It combines:
+`change.context` compiles an immutable Context Manifest v3 snapshot. It combines:
 
 - the bound baseline/change/task identity;
 - a role and lifecycle gate;
@@ -221,13 +273,14 @@ opens one replacement.
 - local file hashes, current HEAD, branch, and worktree digest;
 - optional metadata-only external memory or graph references;
 - advisory file/token/context-share budgets;
-- readiness blockers and one DB-derived next action.
+- the current Change and task authority digests;
+- readiness blockers, `allowed_transitions`, and a `required_transition` only for a
+  unique hard-recovery path.
 
 Critical stage workflows bind a matching snapshot as a durable output:
 
 | Workflow | Required role | Required gate |
 |---|---|---|
-| `change` | `plan` or `implement` | `planning` or `implementation` |
 | `dev` | `implement` | `implementation` |
 | `test` | `check` | `verification` |
 | `review` | `review` | `review` |
@@ -236,13 +289,18 @@ Critical stage workflows bind a matching snapshot as a durable output:
 The snapshot path and digest are then carried into test, review, and delivery
 reports. This prevents a later Prompt from claiming evidence gathered under a
 different context. File and token budgets warn; they do not block legitimate
-work. Missing authority, required refs, task contracts, outputs, approval, or
+work. Missing authority, required refs, task contracts, outputs, required owner
+decisions, or
 current gate evidence do block.
 
 ## 7. Invalidation rules
 
 - Changing a task contract invalidates contexts and gates that depended on the
   former contract.
+- Changing accepted Change intent, contract, classification, research disposition,
+  provider evidence, or documentation impact marks all derived tasks stale and
+  invalidates compiled contexts. Planning or task reconciliation must explicitly
+  clear staleness before execution.
 - Changing required source/spec content invalidates the recorded output or
   context digest.
 - Changing a research semantic source invalidates that workflow even when its immutable
@@ -266,21 +324,25 @@ current gate evidence do block.
 ### New project
 
 ```text
-ultra-init -> full research (17 steps with one-decision checkpoints) -> baseline approval
--> initial change alignment -> plan checkpoint -> dev per task -> test -> review -> deliver
+ultra-init -> Git/scaffold/authority verification -> init completed
+-> explicit ultra-research -> disposition 17 coverage areas -> selected evidence work
+-> local checkpoint when Git is unborn -> baseline approval
+-> ultra-change -> optional bounded research/plan -> dev -> risk-selected test/review
+-> local deliver/archive
 ```
 
 ### Existing project
 
 ```text
-ultra-init -> brownfield adoption research (17 steps with one-decision checkpoints)
--> characterization and known-red evidence -> gap ledger -> owner approval
--> first selected change alignment -> plan checkpoint -> dev -> test -> review -> deliver
+ultra-init -> preserve Git/classify brownfield -> init completed
+-> explicit adoption research -> disposition 17 coverage areas
+-> selected characterization/known-red evidence -> gap ledger -> owner approval
+-> first ultra-change -> optional bounded research/plan -> dev -> test/review -> deliver
 ```
 
 Adoption records the system that exists. It does not force the owner to recreate
 market, persona, or roadmap claims that cannot be supported; those remain
-`Unknown` or explicit gaps while every semantic step is still processed.
+`Unknown`, `not_applicable`, accepted `deferred`, or explicit gaps with evidence.
 
 ### Earlier Ultra project
 
@@ -294,8 +356,9 @@ Migration preserves prior files and rows but never carries old approval forward.
 ### Daily maintenance
 
 ```text
-ultra-status -> ultra-change capture/alignment -> plan if task contracts are absent
--> dev -> test -> review -> deliver -> reconciled baseline
+ultra-status -> ultra-change intent capture
+-> host chooses bounded research, plan, current task, think, or status
+-> dev -> risk-selected test -> review -> deliver -> reconciled baseline
 ```
 
 Quick changes shorten the artifact burden only where the machine contract allows;
@@ -307,21 +370,22 @@ evidence rather than bypassing them.
 
 | Entry | Owns | Normal handoff |
 |---|---|---|
-| `ultra-init` | classification, scope, scaffold, baseline/run creation | `ultra-research`; an already-ready project routes to `ultra-change` |
-| `ultra-research` | evidence acquisition, seventeen-step semantic coverage, research decisions | baseline approval then `ultra-change`; bounded research returns to `ultra-plan` |
-| `ultra-think` | one current owner decision or read-only diagnosis | exact invoking workflow and step after checkpoint confirmation |
-| `ultra-change` | outcome capture, alignment, Change Contract, risk/research routing | selected `ultra-research`, then `ultra-plan`; approved existing plan may route to `ultra-dev` |
-| `ultra-plan` | plan decisions, task contracts, dependencies, approval | first ready task through `ultra-dev` |
+| `ultra-init` | classification, scope, Git/scaffold bootstrap, and init verification | stops completed; exposes research/status/doctor and any already-valid change capability |
+| `ultra-research` | coverage disposition, selected evidence acquisition, synthesis, and material research decisions | baseline convergence or return to the owning change |
+| `ultra-think` | one material owner decision or read-only diagnosis | returns to the invoking capability after any needed checkpoint |
+| `ultra-change` | outcome capture, Change Contract, risk/research routing | host selects research, plan, current dev work, think, or status |
+| `ultra-plan` | task contracts, dependencies, acceptance coverage, optional material approval | any dependency-ready task through `ultra-dev` |
 | `ultra-dev` | one task/session vertical slice and focused review | next `ultra-dev` task or aggregate `ultra-test` |
-| `ultra-test` | change-level acceptance and regression gate | `ultra-review` on pass, `ultra-dev` on implementation failure |
-| `ultra-review` | independent specification and engineering verdicts | `ultra-deliver` on approval; otherwise `ultra-dev` or `ultra-test` |
-| `ultra-deliver` | convergence, reconciliation, archive, authorized release evidence | `ultra-status` or the next `ultra-change` |
-| `ultra-status` | read-only authoritative position and one route | whichever exact workflow owns the current step |
-| `ultra-doctor` | read-only diagnosis and authorized mechanical recovery | exact recovered workflow, `ultra-init`, or `ultra-think` |
-
-Every row routes to `ultra-think` when owner authority is missing and to
-`ultra-doctor` when state or installed-runtime authority is unhealthy. Neither route
-creates a parallel workflow or substitutes a Prompt summary for the DB state.
+| `ultra-test` | risk-selected change acceptance and verification profile | `ultra-review` on pass, `ultra-dev`/`ultra-test` on failure |
+| `ultra-review` | independent specification and engineering axes plus risk-selected workers | `ultra-deliver` on approval; otherwise implementation or checking |
+| `ultra-deliver` | convergence, reconciliation, local archive, and delivery evidence | `ultra-status` or the next `ultra-change`; external release is separate |
+| `ultra-status` | read-only authority and transition set | host recommendation among allowed transitions |
+| `ultra-doctor` | read-only diagnosis and authorized mechanical recovery | required recovery only when unique; otherwise safe alternatives |
+
+Every row permits `ultra-think` when material owner authority is missing and permits
+`ultra-doctor` when state or installed-runtime authority is unhealthy. MCP makes one
+of them required only when no safe alternative exists. Neither capability creates a
+parallel workflow or substitutes a Prompt summary for DB state.
 
 ## 9. Recovery and diagnosis
 

package/hooks/pre_stop_check.py

@@ -35,13 +35,14 @@ def main() -> None:
         allow_stop()
         return
     if breadcrumb and breadcrumb.get("change_id"):
+        allowed = ", ".join(breadcrumb.get("allowed_transitions") or []) or "none"
+        required = breadcrumb.get("required_transition") or "none"
         print(
             "[Ultra stop advisory] Active Ultra change remains open: "
             f"change={breadcrumb['change_id']}, "
             f"task={breadcrumb.get('task_id') or 'none'}, "
             f"gate={breadcrumb.get('gate') or 'alignment'}, "
-            f"route={breadcrumb.get('recommended_workflow') or 'ultra-status'}. "
-            f"Next: {breadcrumb.get('next_action') or 'Inspect Ultra status.'} "
+            f"allowed_transitions={allowed}, required_transition={required}. "
             "Stop is allowed; resume or explicitly archive the change later.",
             file=sys.stderr,
         )