ultra-builder-pro-cli 0.11.0 → 0.13.0

package/adapters/tests/kimi-hook.test.cjs

@@ -97,7 +97,7 @@ test('Kimi subagent fields are normalized for the existing lifecycle tracker', (
   });
 });
 
-test('Kimi stop blocks and recovery context use the exact structured-output schema', () => {
+test('Kimi adapter preserves an explicit Stop deny and recovery context schema', () => {
   const script = [
     'import importlib.util, json, pathlib',
     `p = pathlib.Path(${JSON.stringify(ADAPTER)})`,

package/adapters/tests/opencode.test.cjs

@@ -206,11 +206,14 @@ test('OpenCode context covers active changes and projection writes are blocked f
     fs.mkdirSync(changeRoot, { recursive: true });
     fs.writeFileSync(path.join(changeRoot, 'context-manifest.json'), JSON.stringify({
       schema_version: '2.0',
+      baseline: { id: 'project-baseline', mode: 'brownfield', status: 'ready', repository_revision: compiledHead },
       change: { id: 'daily-fix', title: 'Daily fix', kind: 'quick', status: 'active', intent: 'Fix drift' },
       role: 'implement',
       gate: 'implementation',
       next_action: 'Run the exact regression test.',
-      readiness: { status: 'ready', blockers: [] },
+      readiness: {
+        status: 'ready', blockers: [], warnings: ['CONTEXT_FILE_BUDGET_EXCEEDED'],
+      },
       git: { head: compiledHead },
       selected_task: { id: 'daily-task', status: 'in_progress' },
       context: { token_estimate: 1200, budget: { max_tokens: 8000, max_files: 8 } },
@@ -225,6 +228,7 @@ test('OpenCode context covers active changes and projection writes are blocked f
     assert.match(output.system.join('\n'), /Role: implement/);
     assert.match(output.system.join('\n'), /Gate: implementation/);
     assert.match(output.system.join('\n'), /Readiness: ready/);
+    assert.match(output.system.join('\n'), /Warnings: CONTEXT_FILE_BUDGET_EXCEEDED/);
     assert.match(output.system.join('\n'), /Run the exact regression test/);
     assert.doesNotMatch(output.system.join('\n'), /Fix drift|cloud-mem/);
 
@@ -238,6 +242,16 @@ test('OpenCode context covers active changes and projection writes are blocked f
     legacyManifest.schema_version = '2.0';
     fs.writeFileSync(manifestFile, JSON.stringify(legacyManifest));
 
+    delete legacyManifest.baseline;
+    fs.writeFileSync(manifestFile, JSON.stringify(legacyManifest));
+    const missingBaselineOutput = { system: [] };
+    await plugin['experimental.chat.system.transform']({}, missingBaselineOutput);
+    assert.match(missingBaselineOutput.system.join('\n'), /CONTEXT_SNAPSHOT_UPGRADE_REQUIRED/);
+    legacyManifest.baseline = {
+      id: 'project-baseline', mode: 'brownfield', status: 'ready', repository_revision: compiledHead,
+    };
+    fs.writeFileSync(manifestFile, JSON.stringify(legacyManifest));
+
     fs.writeFileSync(path.join(project, 'app.txt'), 'changed\n');
     execFileSync('git', ['add', 'app.txt'], { cwd: project, stdio: 'ignore' });
     execFileSync('git', ['-c', 'user.name=Ultra Tests', '-c', 'user.email=ultra@example.invalid', 'commit', '-m', 'change'], {
@@ -262,6 +276,27 @@ test('OpenCode context covers active changes and projection writes are blocked f
   }
 });
 
+test('OpenCode does not assume a project baseline is ready when no active change manifest exists', async () => {
+  const target = mkTarget();
+  const project = mkTarget();
+  try {
+    opencode.install({ configDir: target, repoRoot: REPO_ROOT });
+    fs.mkdirSync(path.join(project, '.ultra'), { recursive: true });
+    fs.writeFileSync(path.join(project, '.ultra', 'state.db'), 'owned-by-ultra');
+    const module = await import(`${pathToFileURL(path.join(target, 'plugins', 'ultra-builder-pro.js')).href}?baseline`);
+    const plugin = await module.UltraBuilderProPlugin({ directory: project });
+    const output = { system: [] };
+    await plugin['experimental.chat.system.transform']({}, output);
+    const text = output.system.join('\n');
+    assert.match(text, /ultra-status/);
+    assert.match(text, /ultra-init/);
+    assert.doesNotMatch(text, /Start daily work with the ultra-change workflow/);
+  } finally {
+    fs.rmSync(target, { recursive: true, force: true });
+    fs.rmSync(project, { recursive: true, force: true });
+  }
+});
+
 test('install preserves user mcp entries; uninstall removes only owned Ultra assets', () => {
   const target = mkTarget();
   const configFile = path.join(target, 'opencode.json');

package/commands/ultra-init.md

@@ -1,10 +1,10 @@
 ---
-description: Initialize an Ultra project with authoritative state and baseline specification files
-argument-hint: "[name] [type] [stack] [git]"
+description: Initialize a new project or adopt an existing repository into authoritative Ultra baseline state
+argument-hint: "[name] [type] [stack] [auto|greenfield|brownfield] [--scope <path>]"
 workflow-ref: "@skills/ultra-init/SKILL.md"
 ---
 
-# Initialize an Ultra project
+# Initialize or adopt an Ultra project
 
 Read and follow `@skills/ultra-init/SKILL.md`, using `$ARGUMENTS` as optional project metadata.
 Treat the referenced skill as the only workflow definition.

package/docs/AGENT-CONTEXT.md

@@ -37,18 +37,19 @@ native command or skill -> MCP workflow-state operation -> .ultra/state.db
 | MCP | `mcp-server/server.cjs` | Authoritative typed operations over `.ultra/state.db` |
 | CLI | `ultra-tools`, `ubp-orchestrator` | Selected initialization, backup-first recovery, automation, and diagnostics; not a change-state mirror |
 
-`.ultra/state.db` is the only durable Ultra authority for changes, tasks,
+`.ultra/state.db` is the only durable Ultra authority for baselines, changes, tasks,
 sessions, events, incidents, projection jobs/cursors, telemetry, review evidence,
 and circuit-breaker state. `tasks.json`, context Markdown, execution plans, and
 reports are projections or workflow artifacts.
 
 ## 3. Live MCP and declared contracts
 
-`spec/mcp-tools.yaml` declares and the bundled server registers 32 tools across
-five families:
+`spec/mcp-tools.yaml` declares and the bundled server registers 36 tools across
+six families:
 
 | Family | Live tools |
 |---|---|
+| `baseline.*` | start, record, get, converge |
 | `task.*` | create, update, list, get, switch_tag, delete, init_project, expand, parse_prd, dependency_topo, append_event, subscribe_events |
 | `session.*` | spawn, close, get, list, admission_check, heartbeat, subscribe_events |
 | `change.*` | create, update, get, list, context, breadcrumb, learning_propose, learning_resolve, converge, archive |
@@ -67,14 +68,20 @@ fixtures. Do not add an ad-hoc server handler first.
 Context Manifest v2 is a DB-backed role handoff, not a static codebase summary.
 `change.context` compiles required references, digests, readiness, context budget,
 public seam, exact verification command, and one next action for `plan`,
-`implement`, `check`, or `review`. The default fresh-context contract is at most
-12 files, about 12k tokens, and 40% of the host context; wider work must use an
-explicit `expand_contract`.
+`implement`, `check`, or `review`. The default 12-file, about 12k-token, and 40%
+fresh-context values are attention guidance. Overflow produces warnings; it does
+not block work or require raising a threshold. Prefer direct reads, bounded
+excerpts, or a smaller slice when they preserve correctness, and retain all
+necessary context when they do not.
 
 `change.breadcrumb` is the only compact router. Hooks may inject its change/task,
 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 budget overflow blocks readiness.
+digest drift, HEAD drift, or a missing execution seam blocks readiness. Context
+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
@@ -103,7 +110,7 @@ the shared read-only `context_spine.py` breadcrumb helper:
 - `active_task_context.py` before an edit;
 - `workflow_checkpoint.py` before compaction;
 - `workflow_resume.py` after compaction/resume;
-- `pre_stop_check.py` at stop;
+- `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
@@ -114,6 +121,8 @@ edit guidance to an active workflow. Compact/stop/subagent hooks remain
 active-workflow scoped. OpenCode natively injects baseline/change context and
 protects the projection; full health inspection is available through
 `system.doctor` rather than a session-start health hook.
+Advisory baseline or context-budget warnings are presentation only and never
+reject an edit, stop, or tool call.
 Generic command blocking, post-edit governance, and unrelated user hooks are not
 copied into Ultra Builder Pro.
 

package/docs/ARCHITECTURE.md

@@ -53,7 +53,7 @@ the supported hosts share.
 | Layer        | Role                                         | Form                                                  |
 |--------------|----------------------------------------------|-------------------------------------------------------|
 | **skill**    | knowledge carrier; tells the runtime *what to do* | `skills/<name>/SKILL.md` discovered natively by all supported runtimes |
-| **MCP**      | authoritative workflow-state and Context Spine API | stdio MCP server exposing 32 live tools across task/session/change/system/plan families in [`spec/mcp-tools.yaml`](../spec/mcp-tools.yaml) |
+| **MCP**      | authoritative workflow-state and Context Spine API | stdio MCP server exposing 36 live tools across baseline/task/session/change/system/plan families in [`spec/mcp-tools.yaml`](../spec/mcp-tools.yaml) |
 | **CLI**      | explicit initialization, recovery, diagnostics, and orchestration | `ultra-tools` / `ubp-orchestrator`; only commands listed by `--help` are executable (see [`spec/cli-protocol.md`](../spec/cli-protocol.md)) |
 
 Why three: skills give us behavior portability across runtimes; MCP gives
@@ -70,10 +70,11 @@ RPC, and host-native loaders own resolution and invocation.
 
 All durable Ultra workflow state lives in one SQLite file with WAL enabled. Schema is
 fixed in [`spec/schemas/state-db.sql`](../spec/schemas/state-db.sql) and
-covers sixteen tables:
+covers seventeen tables:
 
 | Table              | Holds                                             | Phase |
 |--------------------|---------------------------------------------------|-------|
+| `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 |
@@ -82,7 +83,7 @@ covers sixteen 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 |
@@ -101,7 +102,7 @@ Two rules make this work:
 
 2. **Single writer for mutable tables, multi-writer for `events`.**
    `.ultra/state.db` opens in WAL with `busy_timeout=5000`. The MCP
-   server holds the single writer connection for `tasks`, `sessions`,
+   server holds the single writer connection for `baselines`, `tasks`, `sessions`,
    `changes`, `context_snapshots`, `spec_learning_candidates`, `telemetry`,
    `specs_refs`, and `migration_history`; the CLI calls
    those tools over stdio rather than opening its own writer. The
@@ -125,6 +126,37 @@ such as cloud-mem/claude-mem owns persistent memory and its own lifecycle. The
 only related migration surface is the explicit `ultra-tools legacy-memory`
 archive/prune command for data created by older releases.
 
+### Project baseline adoption
+
+`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, 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.
+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
 
 After the initial baseline delivery, every fix, feature, redesign, or incident
@@ -151,8 +183,9 @@ checking, review, convergence, and recovery. Each snapshot records:
 
 - one role (`plan`, `implement`, `check`, or `review`) and lifecycle gate;
 - required context references with local digests and reasons;
-- readiness blockers for missing/stale references or budget overflow;
-- a fresh-context budget (12 files / about 12k tokens / 40% by default);
+- readiness blockers for missing/stale required references or an incomplete
+  execution contract;
+- advisory attention budgets (12 files / about 12k tokens / 40% by default);
 - an execution contract (`slice_kind`, public seam, exact verification command);
 - one deterministic next action.
 
@@ -161,6 +194,11 @@ edit, and resume hooks 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`.
 
+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
+drop required incident evidence.
+
 `change.learning_propose` records a durable implementation discovery without
 silently rewriting the baseline. `change.learning_resolve` enforces approval,
 rejection, and applied transitions. Proposed or merely approved candidates block
@@ -177,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-17 当前生效边界（D50-D53，覆盖下文旧 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.11.0；四宿主 native plugin、32 个 live MCP tool、
-schema 10.0（16 表）、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 条）
 
 ---
@@ -1642,6 +1642,8 @@ Week 18      buffer（ship 中任何 Phase 的 25% 滑动吃掉）
 | **D51** | **2026-07-17** | **runtime 收敛为 Claude Code、OpenCode、Codex**：删除第四 runtime 的 adapter、安装参数、collab skill、prompt、schema、pricing、调度与测试面；`ultra-verify` 改为当前宿主主责加单一只读外部顾问 | 用户确认不再需要第四 runtime；0.6.0 退役契约阻止其重新进入活跃源码或发布包 |
 | **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 决策边界 |
 
 ---
 
@@ -1666,8 +1668,9 @@ Week 18      buffer（ship 中任何 Phase 的 25% 滑动吃掉）
 - **Session**：GSD-2 模式升级版（D20）：新进程 + 独立 worktree + lease/
   heartbeat（存 sessions 表） + artifact dir；Phase 4.5 实装。
 - **state.db**：`.ultra/state.db` SQLite + WAL 数据库，所有 Ultra workflow
-  状态的权威源；当前 15 表，新增 changes/artifacts/context_snapshots/
-  trace_links/incidents/projection_jobs/event_consumers；Phase 2 建立，D52 扩展。
+  状态的权威源；当前 17 表，包含 baselines、changes、artifacts、
+  context_snapshots、spec_learning_candidates、trace_links、incidents、
+  projection_jobs 与 event_consumers；Phase 2 建立，D52-D54 扩展。
 - **三层架构**：§4.1；skill（知识，只读发现）+ MCP（状态操作主路径）+
   CLI（兜底）。
 - **staleness**：task 的 spec 被改后，未开工的 pending task 自动标记

package/docs/ROADMAP.md

@@ -44,23 +44,25 @@ sharing one authoritative workflow store.
 | 8B    | Execution automation (dispatch / parallel worktree / merge) | ✅ done (D48, `8224159`) — **v0.3 ready** |
 | 8C    | Continuous change packets + context compiler + convergence + doctor | ✅ done (D52) |
 | 10    | Context Spine v2 + breadcrumb + fresh-context budget + spec learning + two-axis review | ✅ done |
+| 11    | Greenfield/brownfield baseline adoption + advisory context budgets + convergence gate | ✅ done |
 | 9     | Release pipeline                               | npm tag publishing live; Homebrew / pip not implemented |
 
 ## What is in the repo today
 
 ```
 spec/                       ← Phase 1 single source of truth
-├── mcp-tools.yaml          (32 live tools across 5 families)
+├── mcp-tools.yaml          (36 live tools across 6 families)
 ├── cli-protocol.md         (CLI ↔ MCP mapping table)
 ├── schemas/                (state-db.sql + 4 JSON schemas)
 ├── fixtures/{valid,invalid}/  (+ v4.4-project for migration)
 └── scripts/test-all.cjs    (npm run test:spec — 7 validation stages)
 
 mcp-server/                 ← Phase 2 authoritative state layer
-├── server.cjs              (stdio MCP server, 32 task/session/change/system/plan tools)
+├── server.cjs              (stdio MCP server, 36 baseline/task/session/change/system/plan tools)
 ├── lib/
 │   ├── state-db.cjs        (SQLite + WAL + pragmas)
 │   ├── state-ops.cjs       (full write API, status state machine)
+│   ├── baseline-workflow.cjs (project adoption + approval + reconciliation)
 │   └── projector.cjs       (state.db → tasks.json + context md)
 └── tests/                  (npm run test:state)
 
@@ -68,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/RUNTIME-COMPAT-MATRIX.md

@@ -50,7 +50,7 @@ not presented as nonexistent custom agents.
 | 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 |
-| Incomplete-stop gate | FULL, native blocking `Stop` | DEGRADED, no equivalent blocking stop hook | FULL, native blocking `Stop` | FULL, native structured deny |
+| Stop lifecycle advisory | FULL, native non-blocking `Stop` | N/A, no equivalent stop event needed | FULL, native non-blocking `Stop` | FULL, native non-blocking `Stop` |
 | Subagent lifecycle evidence | FULL | DEGRADED, no equivalent packaged event | FULL | FULL, native `SubagentStart` / `SubagentStop` |
 
 Kimi's session bootstrap therefore also instructs recovery to inspect
@@ -63,20 +63,23 @@ applies at baseline, while compact/stop/subagent enforcement remains
 active-workflow scoped. No host receives prompt capture, transcript capture,
 observation journaling, session-summary memory, generic command blocking, or
 generic post-edit policy.
+Baseline-adoption and context-budget warnings are injected as advisory context;
+they do not deny edits or stop active incident work.
 
 ## 4. MCP and state
 
 | Capability | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
 |---|---|---|---|---|
 | stdio MCP registration | plugin `.mcp.json` | `opencode.json` local MCP entry | plugin `.mcp.json` | plugin `mcpServers` entry |
-| Live/declared contracts | 32 | 32 | 32 | 32 |
+| 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 |
 | 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` |
 | Ultra memory API | N/A | N/A | N/A | N/A |
 
-All 32 `task.*`, `session.*`, `change.*`, `system.*`, and `plan.*` operations
+All 36 `baseline.*`, `task.*`, `session.*`, `change.*`, `system.*`, and `plan.*` operations
 registered by `mcp-server/server.cjs` are live. Review, impact discovery, skill
 loading, and user interaction remain host-native surfaces.
 
@@ -123,9 +126,9 @@ records. Uninstall refuses an unmanaged or conflicting root.
 
 | Capability | Contract |
 |---|---|
-| Current state schema | `10.0` |
+| Current state schema | `11.0` |
 | Runtime values | `claude`, `opencode`, `codex`, `kimi` |
-| Upgrade from earlier schema | preserves Kimi runtime rows, adds Context Spine columns and `spec_learning_candidates` transactionally |
+| Upgrade from earlier schema | preserves runtime rows, adds Context Spine state through 10.0, then adds authoritative baseline adoption state transactionally in 11.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

@@ -3,28 +3,30 @@
 > Phase 2.2 contract. Trace: PLAN §6 Phase 2.2, decisions D18 / D32 / D37,
 > risks R21 / R25.
 
-`.ultra/state.db` is the only authoritative state store for tasks,
-events, sessions, telemetry, and spec references (D18). Every process
+`.ultra/state.db` is the only authoritative state store for baselines, changes,
+tasks, events, sessions, incidents, projections, telemetry, and spec references
+(D18, D52, D54). Every process
 that touches it must follow the rules below; deviations are bugs.
 
 ## 1. Three-role write matrix
 
-| Role                       | tasks | events | sessions | telemetry | specs_refs | migration_history |
-|----------------------------|:-----:|:------:|:--------:|:---------:|:----------:|:-----------------:|
-| **MCP server** (single writer for mutables) | RW | RW | RW | RW | RW | RW |
-| **CLI** (`ultra-tools …`)   | R     | RW (append-only) | R | R | R | R |
-| **Orchestrator daemon** (Phase 5+) | R | RW | RW | RW | RW | R |
+| Role | tasks | baselines | change/artifact state | events | sessions | telemetry | specs_refs | migration_history |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| **MCP server** (single writer for mutables) | RW | RW | RW | RW | RW | RW | RW | RW |
+| **CLI** (`ultra-tools …`) | R | RW (init only) | R | RW (append-only) | R | R | R | RW (migration only) |
+| **Orchestrator daemon** | R | R | R | RW | RW | RW | RW | R |
 
 - **R** = read-only;
 - **RW** = read + write;
 - A `(append-only)` qualifier means the role may execute `INSERT INTO`
   but never `UPDATE` / `DELETE`.
 
-The CLI may indirectly mutate any table by spawning the MCP server over
+The CLI may indirectly mutate ordinary workflow tables by spawning the MCP server over
 stdio and calling `task.update`, `session.spawn`, etc. — but the actual
-SQLite write is performed by the MCP server's writer connection. The CLI
-never opens a writer connection on `tasks`, `sessions`, `telemetry`,
-`specs_refs`, or `migration_history`.
+SQLite write is performed by the MCP server's writer connection. The documented
+exceptions are initial schema/baseline creation, migration, and explicitly
+authorized backup-first doctor recovery. The CLI never provides a parallel raw
+write API for normal task, change, session, or baseline lifecycle updates.
 
 The append-only carve-out for `events` exists because `events.id INTEGER
 PRIMARY KEY AUTOINCREMENT` makes concurrent inserts collision-free under
@@ -68,13 +70,17 @@ 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 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 |
+| `incidents`, `projection_jobs`, `event_consumers`, `circuit_breaker` | MCP server; backup-first doctor recovery may perform only documented mechanical transitions |
 | `events`           | MCP server **and** any process via append-only INSERT  |
 | `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

@@ -7,7 +7,7 @@ only one small managed section describing its runtime boundary.
 ## Source and render targets
 
 `adapters/_shared/handbook.cjs` is the canonical source. It renders the common
-authority, Context Spine, specification-learning, memory, hook, agent, and
+authority, baseline adoption, Context Spine, specification-learning, memory, hook, agent, and
 package boundaries with host-native command syntax:
 
 | Runtime | Default target | Main invocation form |
@@ -22,10 +22,14 @@ 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; 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.
+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.
 
 ## Managed-block contract
 

package/hooks/README.md

@@ -1,8 +1,9 @@
 # Ultra Builder Pro workflow hooks
 
 These hooks observe only Ultra-owned state. Session health/context recognizes an initialized
-`.ultra/state.db` and active continuous changes; edit/compact/stop/subagent enforcement remains
-bounded to the relevant Ultra projection or a non-terminal workflow.
+`.ultra/state.db` and active continuous changes. Direct projection writes remain blocked;
+context, compact, stop, and subagent lifecycle behavior is recovery-oriented and does not turn
+advisory workflow conditions into refusal gates.
 
 | Lifecycle | Hook | Purpose |
 |---|---|---|
@@ -12,7 +13,7 @@ bounded to the relevant Ultra projection or a non-terminal workflow.
 | Before edit | `active_task_context.py` | Protect `tasks.json` and restate the same DB-derived task breadcrumb |
 | Before compact | `workflow_checkpoint.py` | Validate and atomically save a minimal workflow checkpoint |
 | After compact/resume | `workflow_resume.py` | Prefer the DB breadcrumb; restore the minimal file checkpoint only when no active change owns recovery |
-| Stop | `pre_stop_check.py` | Block once when the Ultra workflow is incomplete |
+| Stop | `pre_stop_check.py` | Report an incomplete workflow boundary and allow stop |
 | Subagent lifecycle | `subagent_tracker.py` | Append lifecycle evidence under `.ultra/runtime/` |
 
 The plugin deliberately does not capture prompts, tool observations, transcripts, summaries, or

package/hooks/adapters/codex.py

@@ -175,7 +175,7 @@ def adapt_output(output: dict[str, Any], event: str) -> dict[str, Any]:
     if event == "Stop":
         if output.get("decision") == "block":
             result["decision"] = "block"
-            result["reason"] = str(output.get("reason") or "Ultra completion gate blocked stop")
+            result["reason"] = str(output.get("reason") or "Ultra hook blocked stop")
         return result
 
     if event in {"PreCompact", "PostCompact", "SubagentStop"}:

package/hooks/adapters/kimi.py

@@ -3,7 +3,7 @@
 
 Kimi 0.26 uses snake_case JSON input compatible with the workflow hooks, but
 its output contract accepts only ``message`` plus an optional structured deny.
-This adapter preserves real projection/stop blocks, converts foreign context
+This adapter preserves explicit projection denials and optional Stop decisions, converts foreign context
 fields into Kimi messages, and fails open with diagnostic evidence.
 """