ultra-builder-pro-cli 0.12.1 → 0.13.0

package/.ultra-template/docs/research/README.md

@@ -1,53 +1,30 @@
-# Research Reports
+# Research Evidence
 
-This directory contains research reports generated by `/ultra-research` step-file architecture.
+Store durable research evidence here only when it is too detailed for the baseline
+specification. Baseline decisions and accepted behavior remain in `.ultra/specs/`.
 
-## Structure
+## When to create a report
 
-Each round generates a report with quality metadata:
+Create a report for external facts, repository investigations, experiments, runtime
+observations, or decision evidence that must remain inspectable. Use a descriptive
+file name and include the observation date when freshness matters.
 
-| Steps | Round | Report File |
-|-------|-------|-------------|
-| 00-05 | R0: Product Discovery | `product-discovery-{date}.md` |
-| 10-11 | R1: User & Scenario | `user-scenario-{date}.md` |
-| 20-22 | R2: Feature Definition | `feature-definition-{date}.md` |
-| 30-32 | R3: Architecture Design | `architecture-design-{date}.md` |
-| 40-41 | R4: Quality & Deployment | `quality-deployment-{date}.md` |
+## Report contract
 
-## Report Format
+Record:
 
-Each report includes quality tracking in header:
+- scope and the decision the evidence informs;
+- observed facts with source references and dates;
+- verification commands or runtime evidence;
+- accepted decisions and their owner;
+- unresolved unknowns and whether they block the baseline;
+- links to the product or architecture sections updated from the evidence.
 
-```markdown
-# Round {N}: {Round Name}
+Keep inference distinct from observation. Link to external provider content instead of
+copying memory, code-graph payloads, or large source material into Ultra.
 
-> **Confidence**: 92%
-> **Steps completed**: {list}
-> **Completed**: {date}
+## Completion
 
-## Key Findings
-[3-5 bullet points]
-
-## Decisions Made
-[Choices and rationale]
-
-## Open Questions
-[What remains uncertain]
-```
-
-## Quality Gate
-
-- Each step uses [C] Continue user gate — user confirms before proceeding
-- Per-step SUCCESS METRICS and FAILURE MODES enforce output quality
-- Step 99 (Synthesis) validates field-level completeness of all spec files
-
-## Research Distillate
-
-After all steps complete, `step-99-synthesis` generates:
-- `.ultra/specs/research-distillate.md` — Token-efficient summary (<2000 tokens) for `/ultra-plan` consumption
-
-## Integration
-
-- Reports are referenced in `specs/` for technology decisions
-- Research distillate is the primary input for `/ultra-plan`
-- Quality summary displayed at end of `/ultra-research`
+Update the affected baseline specification, include the report in `baseline.record`
+evidence when material, and record unresolved work in the authoritative gap ledger.
+Do not create a condensed duplicate of the baseline.

package/.ultra-template/specs/discovery.md

@@ -36,6 +36,16 @@ Separate blocking unknowns from questions that are outside the accepted scope.
 |---|---|---|---|
 | | | | |
 
+## Baseline Gaps
+
+Reference the authoritative gap ids recorded in `.ultra/state.db`. Use one of
+`baseline_blocker`, `documentation_drift`, `known_defect`, `technical_debt`,
+`unknown`, or `future_change`.
+
+| Gap id | Category | Status | Evidence reference | Owner |
+|---|---|---|---|---|
+| | | | | |
+
 ## Current Behavior Notes
 
 For an existing project, describe only behavior confirmed from source, tests, runtime,

package/CHANGELOG.md

@@ -7,6 +7,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.13.0] — 2026-07-18
+
+### Added
+
+- Added schema 12 repository snapshots, branch and dirty-worktree evidence,
+  classification metadata, and a categorized baseline gap ledger with explicit
+  blocker, ownership, acceptance, and resolution state.
+- Added safe `task.init_project` resume semantics, bounded monorepo scope
+  detection, projection-only import routing, explicit migrated-baseline
+  replacement, and backup-first recovery for old state databases.
+- Added explicit corrupt-state restore and rebaseline commands that quarantine
+  the original database, WAL, SHM, and task projection and restore every moved
+  artifact when recovery fails.
+- Added approved incident break-glass records and mandatory post-incident
+  baseline reconciliation gaps, plus durable archive-journal crash recovery.
+
+### Changed
+
+- Made `ultra-init` the single route for empty repositories, existing
+  codebases, healthy installations, incomplete adoptions, prior Ultra state,
+  and corrupt databases. Existing application and baseline files are preserved;
+  resume installs only missing current scaffold assets.
+- New ordinary changes now require a healthy ready baseline. Already-active
+  work remains executable with visible drift warnings, while convergence still
+  requires current approved authority.
+- Ready-baseline replacement now requires durable owner identity and rationale;
+  a bare `replace_ready` boolean is rejected and cannot erase provenance.
+- Reworked baseline templates and host-neutral Skills around
+  `Observed`/`Verified`/`Decided`/`Unknown` evidence, characterization results,
+  owner approval, and one deterministic next action.
+
+### Fixed
+
+- Prevented prior-version projects from being treated as approved after a
+  schema upgrade; compatibility baselines remain `migrated/adopting` until an
+  evidence-backed brownfield replacement is approved.
+- Made status and doctor report old or corrupt state as structured recovery
+  guidance, retain pre-migration backup paths on failure, and close failed
+  database handles safely.
+- Prevented maintenance CLI telemetry from opening corrupt authority before
+  evidence-preserving recovery checks, and made task creation enforce the same
+  baseline boundary as change creation.
+- Closed bulk-parse and task-expansion task-creation bypasses; persisted PRD
+  tasks now carry their active change id, and expanded children inherit the
+  parent task's authorized change ownership.
+- Rejected task writes against missing or terminal changes even when the
+  baseline is healthy, and enforced parent-child change ownership for generic
+  task creation and reassignment paths.
+- Fixed installed npm tarballs so direct `ultra-tools task init-project` calls
+  can locate the packaged scaffold outside a source checkout.
+
 ## [0.12.1] — 2026-07-18
 
 ### Fixed
@@ -490,7 +541,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   skill manifest, CLI protocol + mapping table; 5 spec validators.
 - **Phase 0 — skeleton**: multi-runtime installer scaffolding.
 
-[Unreleased]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.12.1...HEAD
+[Unreleased]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.13.0...HEAD
+[0.13.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.12.1...v0.13.0
 [0.12.1]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.12.0...v0.12.1
 [0.12.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/rocky2431/ultra-builder-pro-cli/compare/v0.10.0...v0.11.0

package/README.md

@@ -8,7 +8,7 @@ authoritative `.ultra/state.db`.
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/version-0.12.1-blue)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.13.0-blue)](./CHANGELOG.md)
 [![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](#verification)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![Node](https://img.shields.io/badge/node-%E2%89%A522-informational)](./package.json)
@@ -44,9 +44,10 @@ authoritative `.ultra/state.db`.
   Incident changes additionally require a five-section `diagnosis.md` covering
   reproduction, hypotheses, root cause, regression test, and recovery.
 - **Adopts existing repositories without pretending they are new.** `ultra-init`
-  auto-detects greenfield versus brownfield work. Brownfield adoption records
-  current specifications, repository/runtime evidence, known-red verification,
-  unknowns, and explicit approval without rewriting application code.
+  classifies greenfield, brownfield, and monorepo scope. Brownfield adoption records
+  current specifications, repository/runtime evidence, worktree snapshot, known-red
+  verification, categorized gaps, unknowns, and explicit approval without rewriting
+  application code. v4.4 and v4.5 projection-only projects have backup-first imports.
 - **Keeps external context external.** Memory and code-graph providers retain
   their own content; Ultra stores only provider/project/revision/status metadata
   references in a compiled change context.
@@ -89,10 +90,10 @@ for per-runtime capabilities.
 Start with `ultra-init` in both new and existing projects. An empty project opens
 a `draft` greenfield baseline. An existing codebase opens an `adopting`
 brownfield baseline; inspect current behavior, call `baseline.record`, then
-approve it through `baseline.converge` before normal planning or delivery. An
-urgent active fix may continue while adoption or context-size warnings are
-visible. `change.converge` requires approved adoption, while normal HEAD/spec drift
-from that change is declared and health-checked atomically by `change.archive`.
+approve it through `baseline.converge` before normal planning or delivery. Existing
+active work may continue while adoption drift is visible. A new incident requires an
+explicit break-glass approver and leaves a blocking reconciliation gap at archive;
+new ordinary work always requires a healthy ready baseline.
 
 ## Three-layer architecture
 
@@ -133,9 +134,13 @@ Full details in [`docs/RUNTIME-COMPAT-MATRIX.md`](./docs/RUNTIME-COMPAT-MATRIX.m
 ## Typical workflow
 
 ```bash
-# 1. Initialize a new project or adopt an existing repository automatically
+# 1. Bootstrap project state (the ultra-init skill completes adoption and approval)
 ultra-tools task init-project --project-name myapp --mode auto
 
+# Projection-only projects from prior releases use one backup-first import:
+ultra-tools migrate --from=4.4 --to=4.5 --source-dir .
+ultra-tools migrate --from=4.5 --to=12.0 --source-dir .
+
 # 2. Record and converge the greenfield/brownfield baseline, then turn accepted
 #    behavior into a task graph (normally driven by ultra-init/research/plan)
 
@@ -208,6 +213,17 @@ Individual suites: `test:state`, `test:orch`, `test:spec`, `test:rest`.
   the recorded install provenance with current asset hashes and validates the
   host-specific hook, MCP, plugin, and runtime-manifest entry points. Reinstall
   only after preserving the degraded report as evidence.
+- **Projection tasks exist but state.db has no tasks**: run the exact v4.4 or v4.5
+  `ultra-tools migrate` command returned by MCP, verify the backup and imported counts,
+  then run `ultra-init` to replace the compatibility row with a reviewed brownfield
+  baseline.
+- **Old or corrupt state.db**: `ultra-tools system doctor` is read-only;
+  `ultra-tools system doctor --repair` upgrades supported schemas with two backup
+  checkpoints. A corrupt database is never overwritten automatically. After explicit
+  owner approval, restore a verified managed copy with
+  `ultra-tools system restore --backup <path> --confirm REPLACE_CORRUPT_ULTRA_STATE`,
+  or preserve the corrupt DB and legacy projection before rebuilding authority with
+  `ultra-tools system rebaseline --project-name <name> --confirm REBASELINE_CORRUPT_ULTRA_STATE`.
 - **Legacy Ultra memory data remains on disk**: inspect first with
   `ultra-tools legacy-memory inspect`, archive with
   `ultra-tools legacy-memory archive`, then prune only with the explicit

package/adapters/_shared/handbook.cjs

@@ -60,12 +60,12 @@ function renderHandbook(runtime) {
     `- Collaboration boundary: ${value.collaboration}. The current host remains primary and owns final verification.`,
     `- Coordination boundary: ${value.coordination}.`,
     '- Authority: `.ultra/state.db` is the only durable Ultra authority for baselines, changes, tasks, sessions, events, incidents, projection state, telemetry, and review evidence. Generated JSON and Markdown are projections or workflow artifacts.',
-    '- Baseline boundary: `task.init_project` detects greenfield or brownfield work; `baseline.start`, `baseline.record`, and `baseline.converge` adopt the project without rewriting application code. An incomplete baseline is advisory during active work but blocks change convergence; normal HEAD or tracked-spec drift from that change is reconciled and health-checked atomically at archive.',
+    '- Baseline boundary: `task.init_project` classifies greenfield or brownfield work and records repository scope. Projection-only prior state uses the exact supported backup-first import returned by the authority check; migrated compatibility rows require explicit brownfield re-adoption. `baseline.record` owns evidence, verification, repository snapshot, and the gap ledger; `baseline.converge` requires explicit owner approval. New ordinary changes require a healthy ready baseline. Existing active work may continue with warnings, but baseline readiness blocks change convergence; normal drift reconciliation is health-checked atomically at archive. Only an explicitly approved incident break-glass may start without baseline readiness, and its archive creates a blocking reconciliation gap.',
     '- Context Spine boundary: `change.context` compiles role/gate readiness, required references, a fresh-context budget, public seam, verification command, and one next action. File, token, and context-share budgets are advisory attention signals, not refusal gates. Hooks inject only the DB-derived `change.breadcrumb`; missing required evidence or stale execution context must be recompiled.',
     '- Specification learning boundary: stable implementation discoveries use approval-gated propose/approve-or-reject/apply transitions. Unresolved learning blocks convergence; review requires independent specification-fidelity and engineering-standards evidence.',
     '- Memory and graph boundary: Ultra Builder Pro does not capture prompts, transcripts, observations, summaries, cross-session memory, or code-graph content. Separately installed providers own that data; Ultra may store only their metadata references in a change context manifest.',
     '- Hook boundary: Ultra hooks observe workflow/change lifecycle only. Health/context may run when `.ultra/state.db` exists; advisory warnings never reject work, and an incomplete workflow never traps session stop. Direct projection protection remains authoritative; compact and subagent recovery stays active-workflow scoped. Generic command blocking and post-edit policy stay in user or repository governance.',
-    '- Installation boundary: `ubp --doctor` is the read-only authority for installed asset provenance, content hashes, and host entry-point wiring; `system.doctor` remains scoped to project state and workflow recovery.',
+    '- Installation boundary: `ubp --doctor` is the read-only authority for installed asset provenance, content hashes, and host entry-point wiring. Project `system.doctor` diagnoses state and performs only authorized backup-first schema, projection, session, and archive-journal recovery; it never approves a baseline.',
     '- Agent boundary: the bundled review and debugging agents are bounded workers. They use the current checkout and parent-supplied context, do not own private persistent state, and never replace the primary agent.',
     '- Package boundary: only the twelve Ultra workflows, four internal review-rule skills, host-specific collaboration companions, and the minimal host bootstrap belong to this plugin. General browser, deployment, discovery, and framework skills must be installed from their owners.',
     END_MARKER,

package/adapters/tests/codex.test.cjs

@@ -9,6 +9,7 @@ const { spawnSync } = require('node:child_process');
 const yaml = require('js-yaml');
 const { Client } = require('@modelcontextprotocol/sdk/client/index.js');
 const { StdioClientTransport } = require('@modelcontextprotocol/sdk/client/stdio.js');
+const { initStateDb, closeStateDb } = require('../../mcp-server/lib/state-db.cjs');
 
 const codex = require('../codex.js');
 const { parse: parseFrontmatter } = require('../_shared/frontmatter.cjs');
@@ -263,6 +264,13 @@ test('bundled plugin MCP runs outside the source checkout and keeps state in the
   let client;
   try {
     install(layout);
+    const seededState = initStateDb(path.join(projectDir, '.ultra', 'state.db'));
+    seededState.db.prepare(
+      `INSERT INTO baselines
+       (id, project_name, mode, status, approved_by, approval_note, converged_at)
+       VALUES ('test-baseline', 'codex-bundle', 'greenfield', 'ready', 'test', 'smoke fixture', ?)`,
+    ).run(new Date().toISOString());
+    closeStateDb(seededState.db);
     const mcp = JSON.parse(fs.readFileSync(path.join(layout.pluginRoot, '.mcp.json'), 'utf8'));
     const server = mcp.mcpServers['ultra-builder-pro'];
     const env = { ...process.env };

package/commands/ultra-init.md

@@ -1,6 +1,6 @@
 ---
 description: Initialize a new project or adopt an existing repository into authoritative Ultra baseline state
-argument-hint: "[name] [type] [stack] [auto|greenfield|brownfield]"
+argument-hint: "[name] [type] [stack] [auto|greenfield|brownfield] [--scope <path>]"
 workflow-ref: "@skills/ultra-init/SKILL.md"
 ---
 

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

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
 
@@ -204,8 +215,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

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/context_spine.py

@@ -56,11 +56,29 @@ def git_head(root: Path):
     return result.stdout.strip() if result.returncode == 0 else None
 
 
+def git_branch(root: Path):
+    result = subprocess.run(
+        ["git", "branch", "--show-current"],
+        cwd=root,
+        text=True,
+        capture_output=True,
+        check=False,
+        timeout=2,
+    )
+    return (result.stdout.strip() or None) if result.returncode == 0 else None
+
+
 def baseline_health(conn, root: Path):
+    columns = {row[1] for row in conn.execute("PRAGMA table_info(baselines)")}
+    optional = [
+        name for name in (
+            "repository_branch", "worktree_state", "worktree_accepted", "gaps_json"
+        ) if name in columns
+    ]
     row = conn.execute(
-        """SELECT id, mode, status, repository_revision, spec_refs_json
-           FROM baselines WHERE status != 'superseded'
-           ORDER BY updated_at DESC, rowid DESC LIMIT 1"""
+        f"""SELECT id, mode, status, repository_revision, spec_refs_json{''.join(f', {name}' for name in optional)}
+            FROM baselines WHERE status != 'superseded'
+            ORDER BY updated_at DESC, rowid DESC LIMIT 1"""
     ).fetchone()
     if row is None:
         return {"status": "fail", "blockers": ["BASELINE_MISSING"], "warnings": [], "baseline": None}
@@ -70,8 +88,22 @@ def baseline_health(conn, root: Path):
     if baseline["status"] != "ready":
         blockers.append(f"BASELINE_NOT_READY:{baseline['status']}")
     elif baseline["mode"] == "migrated":
-        warnings.append("BASELINE_MIGRATION_REVIEW_RECOMMENDED")
+        blockers.append("BASELINE_MIGRATION_REVIEW_REQUIRED")
     else:
+        if "gaps_json" not in columns:
+            blockers.append("BASELINE_SCHEMA_MIGRATION_REQUIRED")
+        for gap in safe_json(baseline.get("gaps_json"), []):
+            if (
+                isinstance(gap, dict)
+                and gap.get("status") == "open"
+                and gap.get("blocking") is True
+            ):
+                blockers.append(f"BASELINE_GAP_BLOCKING:{gap.get('id', 'unknown')}")
+        if baseline.get("worktree_state") == "dirty" and not baseline.get("worktree_accepted"):
+            blockers.append("BASELINE_DIRTY_WORKTREE_NOT_ACCEPTED")
+        branch = git_branch(root)
+        if baseline.get("repository_branch") and branch and baseline["repository_branch"] != branch:
+            blockers.append("BASELINE_BRANCH_STALE")
         for spec in safe_json(baseline.get("spec_refs_json"), []):
             ref = spec.get("path") if isinstance(spec, dict) else None
             expected = spec.get("digest") if isinstance(spec, dict) else None
@@ -95,6 +127,7 @@ def baseline_health(conn, root: Path):
         if head and revision and not str(revision).startswith("workspace:") and head != revision:
             blockers.append("BASELINE_HEAD_STALE")
     baseline.pop("spec_refs_json", None)
+    baseline.pop("gaps_json", None)
     return {
         "status": "fail" if blockers else "pass",
         "blockers": blockers,