ultra-builder-pro-cli 0.12.1 → 0.14.0

package/docs/AGENT-CONTEXT.md

@@ -78,9 +78,10 @@ necessary context when they do not.
 role, gate, readiness, blockers, and one next action. They must not inject intent
 bodies, transcripts, external memory, or graph payloads. Missing references,
 digest drift, HEAD drift, or a missing execution seam blocks readiness. Context
-size and an incomplete baseline are advisory during an active bounded change;
-baseline adoption becomes a hard gate at convergence; revision and tracked-spec
-integrity are reconciled and rechecked atomically at archive.
+size and baseline drift are advisory for a change that is already active. New ordinary
+work requires a healthy baseline. Only an explicitly approved incident break-glass may
+start without it; incident archive records a blocking reconciliation gap. Revision and
+tracked-spec integrity are reconciled and rechecked atomically for ordinary archive.
 
 Stable discoveries use `change.learning_propose`; they reach the baseline only
 through approve/reject/apply transitions in `change.learning_resolve`. Unresolved
@@ -112,8 +113,10 @@ the shared read-only `context_spine.py` breadcrumb helper:
 - `pre_stop_check.py` reports unfinished workflow position at stop without denial;
 - `subagent_tracker.py` for bounded worker lifecycle evidence.
 
-`workflow_context.py`, `active_task_context.py`, and `workflow_resume.py` read the
-same DB-derived breadcrumb through `context_spine.py`. `health_check.py` and
+`workflow_context.py`, `active_task_context.py`, `workflow_resume.py`, and the
+OpenCode plugin invoke the same bundled JavaScript `change.breadcrumb` reader
+through the thin `context_spine.py` bridge. No hook reimplements the state query.
+`health_check.py` and
 `workflow_context.py` may inspect any initialized project;
 `active_task_context.py` always protects the task projection but limits ordinary
 edit guidance to an active workflow. Compact/stop/subagent hooks remain
@@ -148,7 +151,8 @@ Archive before prune; the confirmation token is intentionally required.
 ```text
 .ultra/
 ├── state.db                 # authoritative SQLite store
-├── workflow-state.json      # active workflow/recovery checkpoint
+├── runtime/
+│   └── checkpoint.json      # advisory breadcrumb recovery projection
 ├── changes/
 │   ├── active/<id>/         # intent, delta, plan, context v2, learning, verification
 │   └── archive/             # converged packets after baseline reconciliation

package/docs/ARCHITECTURE.md

@@ -74,7 +74,7 @@ covers seventeen tables:
 
 | Table              | Holds                                             | Phase |
 |--------------------|---------------------------------------------------|-------|
-| `baselines`        | greenfield/brownfield adoption, specs, verification, unknowns, and approval | 11 |
+| `baselines`        | repository classification, greenfield/brownfield adoption, worktree snapshot, specs, evidence, verification, gap ledger, and approval | 12 |
 | `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           | 8C    |
+| `changes`          | continuous feature/fix/incident lifecycle and incident baseline bypass | 12 |
 | `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 |
@@ -128,23 +128,34 @@ archive/prune command for data created by older releases.
 
 ### Project baseline adoption
 
-`task.init_project` detects an empty repository as `greenfield` and an existing
-codebase as `brownfield` unless the caller supplies an explicit mode. It creates
-the same authoritative state shape without rewriting application code.
+`task.init_project` classifies source, tests, deployment, persistence, package
+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.
+
+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
+produce a pre-migration backup. Compatibility state never grants baseline approval;
+`baseline.start` with `replace_migrated: true` opens the actual brownfield adoption.
 
 `baseline.start` opens adoption, `baseline.record` captures server-hashed spec
 references, bounded repository/runtime evidence, actual verification results,
-known unknowns, and metadata-only external provider references, and
+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.
-
-With no active change, a missing, incomplete, or stale baseline routes to
-`ultra-init`. During an already active bounded fix or incident it is an advisory
-warning so recovery work remains possible. `change.converge` requires that adoption
-has produced a `ready` baseline, but does not reject the HEAD or tracked-spec drift
-created by the change itself. `change.archive` declares baseline updates, refreshes
-the revision and digests, rechecks full baseline health inside the same transaction,
-and rolls back both state and artifacts if reconciliation remains incomplete.
+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
+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.
 
 ## 4. Continuous changes — the daily unit of convergence
 
@@ -179,10 +190,17 @@ checking, review, convergence, and recovery. Each snapshot records:
 - one deterministic next action.
 
 `change.breadcrumb` derives the compact current position from state.db. Session,
-edit, and resume hooks inject only this breadcrumb, never the intent body,
+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`.
 
+PRD decomposition and complex-task subdivision use the active host model. The
+MCP accepts the resulting structured tasks, validates schema, topology,
+baseline/change ownership, and transaction boundaries, then persists them. It
+does not call Anthropic, OpenAI, or another model provider and needs no separate
+model API credential.
+
 File count, token estimate, and context-share overflow produce warnings, never a
 refusal. The agent may narrow reads, load files lazily, or split a slice when that
 preserves correctness; it must not raise a threshold merely to clear a gate or
@@ -204,8 +222,13 @@ evidence, and final convergence decision.
 
 Mutating MCP calls enqueue durable `projection_jobs`. Success is exposed in MCP
 response metadata; failure becomes a retryable structured incident instead of a
-swallowed warning. `system.doctor` is read-only by default and performs only
-backup-first mechanical recovery when explicitly requested.
+swallowed warning. `system.doctor` is read-only by default. Explicit repair performs
+backup-first schema upgrade, archive-journal recovery, session and projection
+recovery, and regenerated projections. It cannot approve a baseline or replace a
+corrupt SQLite file silently. `system restore` accepts only a verified SQLite backup
+inside `.ultra/backups`, quarantines the corrupt authority, and rolls back on failure.
+When no valid backup exists, confirmed `system rebaseline` preserves both corrupt
+authority and the legacy task projection before creating a new brownfield adoption.
 
 ## 5. Sessions — the execution unit
 

package/docs/PLAN.zh-CN.md

@@ -1,6 +1,6 @@
 # ultra-builder-pro-cli — 历史执行计划与决策日志
 
-> **2026-07-18 当前生效边界（D50-D54，覆盖下文旧 Phase 6/7 的内置图谱、memory 与 runtime 设计）**：
+> **2026-07-18 当前生效边界（D50-D55，覆盖下文旧 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,8 +10,8 @@
 > Kimi Code 采用各自 native plugin 呈现，其他旧 runtime adapter 已退役。下文所有与此冲突的
 > memory/hindsight 章节仅作为历史实施记录，不再是当前需求或运行时契约。
 
-**当前状态**：v0.12.1；四宿主 native plugin、36 个 live MCP tool、
-schema 11.0（17 表）、portable Skill authoring contract、双轴 review、
+**当前状态**：v0.13.0；四宿主 native plugin、36 个 live MCP tool、
+schema 12.0（17 表）、portable Skill authoring contract、双轴 review、
 Context Spine v2 / breadcrumb / spec-learning、持续 change/context/convergence/doctor、incident debug lane、
 checkpoint 恢复消费与跨宿主安装 provenance/doctor 已落地；npm 发布由
 `v*.*.*` tag 触发。以下 Phase 0-9 正文保留为 2026-04 的实施历史，不再作为
@@ -29,7 +29,7 @@ checkpoint 恢复消费与跨宿主安装 provenance/doctor 已落地；npm 发
 - **Phase 4.6 拆 a/b**（R6 + D35）：v0.1 只跑 smoke flow，full conformance 推 v0.2
 - **Codex 第二轮结论**："小改后开工"（tl;dr）；本版已完成小改
 
-**总决策数**：D1-D53（当前边界以 D50-D53 为准）
+**总决策数**：D1-D55（当前边界以 D50-D55 为准）
 **总风险数**：R1-R32（v0.3.1 新增 R25-R32 共 8 条）
 
 ---
@@ -1643,6 +1643,7 @@ Week 18      buffer（ship 中任何 Phase 的 25% 滑动吃掉）
 | **D52** | **2026-07-17** | **初始交付后进入持续变更闭环**：新增 `ultra-change` / `ultra-doctor`、change/context/artifact/trace/incident/projection/consumer 状态、delta-first spec、确定性 convergence 与 baseline reconciliation；删除内置 code-graph watcher 和通用命令代理，Memory/图谱只保留外部 provider 元数据引用 | 用户确认采用最佳组合落地；解决日常小改导致 spec/context 漂移、投影失败静默和异常无恢复证据的问题 |
 | **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 决策边界 |
 
 ---
 

package/docs/ROADMAP.md

@@ -70,7 +70,7 @@ ultra-tools/                ← CLI fallback, migration, and diagnostics
 ├── cli.cjs
 └── commands/
     ├── db.cjs              (init/checkpoint/vacuum/integrity/backup)
-    ├── migrate.cjs         (v4.4 → v4.5 + dry/rollback)
+    ├── migrate.cjs         (v4.4 projection → v4.5 authority; v4.5 projection → schema 12; dry/rollback)
     └── legacy-memory.cjs   (explicit inspect/archive/confirmed prune)
 
 bin/install.js              ← multi-runtime installer
@@ -101,5 +101,5 @@ npm audit
 ## Out of scope for v1.0 (deferred)
 
 PLAN §13 lists Copilot / Cursor / Windsurf / 7 more runtimes, web
-dashboard / TUI, LLM provider abstraction, team-collab server, plugin
+dashboard / TUI, team-collab server, plugin
 marketplace.

package/docs/RUNTIME-COMPAT-MATRIX.md

@@ -46,7 +46,7 @@ not presented as nonexistent custom agents.
 
 | Lifecycle | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
 |---|---|---|---|---|
-| Session context/health | FULL, DB-derived Context Spine breadcrumb on native `SessionStart` | DEGRADED, projected v2 breadcrumb; health via `system.doctor` | FULL, DB-derived breadcrumb on native `SessionStart` | FULL, DB-derived breadcrumb via session-start skill + hooks |
+| Session context/health | FULL, DB-derived Context Spine breadcrumb on native `SessionStart` | FULL, the native JS plugin invokes the same bundled DB breadcrumb reader; health via `system.doctor` | FULL, DB-derived breadcrumb on native `SessionStart` | FULL, DB-derived breadcrumb via session-start skill + hooks |
 | Active edit boundary | FULL, `PreToolUse Edit|Write` | FULL, `tool.execute.before` rejects projection writes | FULL, `PreToolUse Edit|Write|apply_patch` | FULL, native `PreToolUse Edit|Write` deny contract |
 | Pre-compact checkpoint | FULL | FULL | FULL | FULL, native `PreCompact` |
 | Post-compact context injection | FULL | FULL, native compacting context | FULL, native `PostCompact` restore | DEGRADED; checkpoint restoration runs, but Kimi 0.26/0.27 does not reinject fire-and-forget hook text |
@@ -73,7 +73,7 @@ they do not deny edits or stop active incident work.
 | stdio MCP registration | plugin `.mcp.json` | `opencode.json` local MCP entry | plugin `.mcp.json` | plugin `mcpServers` entry |
 | Live/declared contracts | 36 | 36 | 36 | 36 |
 | Greenfield/brownfield baseline adoption | FULL | FULL | FULL | FULL |
-| Context Spine v2 / breadcrumb | FULL | FULL, DB-generated projection consumed by native JS | 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 |
 | Host-native review/discovery/ask | native | native | documented in `codex-capability-map.json` | native Kimi tools and workers |
 | Durable authority | project `.ultra/state.db` | project `.ultra/state.db` | project `.ultra/state.db` | project `.ultra/state.db` |
@@ -126,9 +126,9 @@ records. Uninstall refuses an unmanaged or conflicting root.
 
 | Capability | Contract |
 |---|---|
-| Current state schema | `11.0` |
+| Current state schema | `12.0` |
 | Runtime values | `claude`, `opencode`, `codex`, `kimi` |
-| Upgrade from earlier schema | preserves runtime rows, adds Context Spine state through 10.0, then adds authoritative baseline adoption state transactionally in 11.0 |
+| 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 |
 | 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

@@ -70,7 +70,7 @@ Detection happens at boot: `statvfs` of `.ultra/state.db`'s mount;
 
 | Table              | Writer of record                                      |
 |--------------------|--------------------------------------------------------|
-| `baselines`        | MCP server (`baseline.start` / `baseline.record` / `baseline.converge`); initialization CLI may create the first row |
+| `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`) |
 | `artifacts`, `context_snapshots`, `spec_learning_candidates`, `trace_links` | MCP server through change lifecycle tools |
@@ -79,8 +79,8 @@ Detection happens at boot: `statvfs` of `.ultra/state.db`'s mount;
 | `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 |
-| `migration_history`| `ultra-tools migrate` CLI only                         |
-| `schema_version`   | `ultra-tools db init` and `ultra-tools migrate` only   |
+| `migration_history`| schema initializer and `ultra-tools migrate` or doctor repair |
+| `schema_version`   | schema initializer, `ultra-tools db init`, migration, and doctor repair |
 
 ## 5. Forbidden patterns
 

package/docs/USER-HANDBOOK-CONTRACT.md

@@ -22,10 +22,11 @@ host receives only its native invocation and collaboration names.
 
 The managed block deliberately stays short. It says that `.ultra/state.db` is
 authoritative; `change.context` compiles role/gate readiness, bounded references,
-fresh-context budget, public seam, and exact verification; size budgets and an
-incomplete baseline during active work are advisory, while an approved baseline is
-required for convergence and full baseline health is restored atomically at archive;
-hooks inject only the DB-derived
+fresh-context budget, public seam, and exact verification; size budgets are advisory,
+new ordinary work requires a healthy baseline, existing active work may continue with
+warnings, and only an approved incident break-glass may start without baseline
+readiness; ordinary archive restores baseline health while break-glass archive records
+a blocking reconciliation gap; hooks inject only the DB-derived
 `change.breadcrumb`; and unresolved specification learning or either failed review
 axis blocks convergence. Detailed procedures remain in the plugin skills so user
 handbooks do not accumulate duplicated prompt sediment.

package/hooks/active_task_context.py

@@ -2,13 +2,11 @@
 """Protect Ultra projections and restate an active task boundary before edits."""
 
 import json
-import sqlite3
 import sys
 from pathlib import Path
 
-from context_spine import read_breadcrumb, render_breadcrumb
+from context_spine import ContextSpineError, find_root, read_breadcrumb, render_breadcrumb
 
-TERMINAL = {"committed", "completed", "done", "cancelled"}
 TASKS_PROJECTION = Path(".ultra/tasks/tasks.json")
 
 
@@ -34,58 +32,32 @@ def main() -> None:
     except json.JSONDecodeError as exc:
         print(f"[active_task_context] invalid hook input: {exc}", file=sys.stderr)
         data = {}
-    start = Path(data.get("cwd") or Path.cwd()).resolve()
-    for root in (start, *start.parents):
-        ultra = root / ".ultra"
-        state_file = ultra / "workflow-state.json"
-        initialized = (
-            (ultra / "state.db").is_file()
-            or state_file.is_file()
-            or (ultra / "changes" / "active").is_dir()
-        )
-        if not initialized:
-            continue
-        if targets_tasks_projection(data, root):
-            print(json.dumps({"hookSpecificOutput": {
-                "hookEventName": "PreToolUse",
-                "permissionDecision": "deny",
-                "permissionDecisionReason": (
-                    "Refusing a direct write to the .ultra/tasks/tasks.json projection. "
-                    ".ultra/state.db is authoritative; use the Ultra MCP task tools and "
-                    "run ultra-doctor when state or projection health is degraded."
-                ),
-            }}))
-            return
-        try:
-            breadcrumb = read_breadcrumb(root)
-        except (sqlite3.Error, OSError) as exc:
-            print(f"[active_task_context] cannot inspect Context Spine: {exc}", file=sys.stderr)
-            breadcrumb = None
-        if breadcrumb and breadcrumb.get("task_id"):
-            print(json.dumps({"hookSpecificOutput": {
-                "hookEventName": "PreToolUse",
-                "additionalContext": render_breadcrumb(root, breadcrumb),
-            }}))
-            return
-        if not state_file.is_file():
-            break
-        try:
-            state = json.loads(state_file.read_text(encoding="utf-8"))
-        except (OSError, json.JSONDecodeError) as exc:
-            print(f"[active_task_context] cannot read {state_file}: {exc}", file=sys.stderr)
-            break
-        if not isinstance(state, dict) or state.get("status") in TERMINAL:
-            break
-        task = state.get("task_id", state.get("task", "unknown"))
-        step = state.get("step", "unknown")
+    root = find_root(Path(data.get("cwd") or Path.cwd()).resolve())
+    if root is None:
+        print(json.dumps({}))
+        return
+    if targets_tasks_projection(data, root):
         print(json.dumps({"hookSpecificOutput": {
             "hookEventName": "PreToolUse",
-            "additionalContext": (
-                f"Active Ultra task {task}, step {step}. Keep this edit inside the approved "
-                "task and preserve .ultra/state.db as workflow authority."
+            "permissionDecision": "deny",
+            "permissionDecisionReason": (
+                "Refusing a direct write to the .ultra/tasks/tasks.json projection. "
+                ".ultra/state.db is authoritative; use the Ultra MCP task tools and "
+                "run ultra-doctor when state or projection health is degraded."
             ),
         }}))
         return
+    try:
+        breadcrumb = read_breadcrumb(root)
+    except ContextSpineError as exc:
+        print(f"[active_task_context] cannot inspect Context Spine: {exc}", file=sys.stderr)
+        breadcrumb = None
+    if breadcrumb and breadcrumb.get("change_id"):
+        print(json.dumps({"hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "additionalContext": render_breadcrumb(root, breadcrumb),
+        }}))
+        return
     print(json.dumps({}))