ultra-builder-pro-cli 0.10.0 → 0.12.1

package/commands/ultra-test.md

@@ -1,50 +1,10 @@
 ---
-description: Pre-delivery quality audit — Anti-Pattern + Coverage Gap + Wiring + E2E + Perf + Security
-argument-hint: [scope]
-allowed-tools: Bash, Read, Write, Edit, Task, Grep, Glob, AskUserQuestion
-model: opus
+description: Run the independent pre-delivery verification gate and record current acceptance evidence
+argument-hint: "[scope]"
 workflow-ref: "@skills/ultra-test/SKILL.md"
-mcp_tools_required:
-  - task.list
-  - change.list
 ---
 
-# /ultra-test
+# Verify delivery readiness
 
-## 目标
-
-`/ultra-deliver` 前的项目级质量审计：6 类 gate（Anti-Pattern / Coverage Gap /
-Wiring / E2E / Performance / Security）× auto-fix loop。**只读** state.db，
-写 `.ultra/test-report.json` 作为 `/ultra-deliver` 的准入凭证。
-completed-task 前置检查必须来自 MCP `task.list`；失败时停止，绝不回退到
-`tasks.json`。`LEGACY_STATE_MIGRATION_REQUIRED` 必须先完成 v4.4→v4.5 迁移。
-
-**注意**：这不是跑单测（那是 `/ultra-dev`）。这是交付前的体检。
-
-## 参数
-
-| 位 | 含义 | 缺省 |
-|----|------|------|
-| `$1` | 审计范围（`all`/`anti-pattern`/`coverage`/`e2e`/`perf`/`security`） | `all` |
-
-## Workflow
-
-完整 8 步见 `@skills/ultra-test/SKILL.md`（pre-check → 6 gates → auto-fix → persist → report）。
-
-**命令入口做的事**：
-1. 探测项目类型 + `task.list` 确认 ≥1 completed
-2. 按 scope 跑 gates；失败进 auto-fix（最多 5 轮）
-3. 写 `.ultra/test-report.json`（change_id + exact commands + gate 明细 + blocking_issues）
-4. 通过 → 提示 `/ultra-deliver`
-
-## 用法
-
-```bash
-/ultra-test                # 全量审计
-/ultra-test security       # 只跑安全审计
-/ultra-test coverage       # 只找覆盖缺口
-```
-
-## 下一步
-
-`passed=true` → `/ultra-deliver`；`passed=false` → 修或跟进 `blocking_issues`。
+Read and follow `@skills/ultra-test/SKILL.md`, using `$ARGUMENTS` to bound the verification scope.
+Treat the referenced skill as the only workflow definition.

package/commands/ultra-think.md

@@ -1,45 +1,10 @@
 ---
-description: Deep analysis with adversarial reasoning — Evidence-First + Multi-Perspective + Stress-Test + Confidence-Quantified recommendation
-argument-hint: "[problem or decision to analyze]"
-allowed-tools: Read, Grep, Glob, Bash, Write, Task, WebSearch, WebFetch, AskUserQuestion, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, mcp__context7__resolve-library-id, mcp__context7__query-docs
-model: opus
+description: Analyze a consequential question with evidence, uncertainty, and proportionate stress testing
+argument-hint: "[question]"
 workflow-ref: "@skills/ultra-think/SKILL.md"
-cli_fallback: "direct user interaction"
 ---
 
-# /ultra-think
+# Analyze a consequential question
 
-## 目标
-
-结构化深度分析复杂问题/决策/诊断。Evidence-First 标注（Fact/Inference/Speculation）+
-多视角 + 对抗压测（Steel-Man / Pre-Mortem / Sensitivity / Second-Order）→
-量化置信度的推荐 + 验证计划。
-
-## 参数
-
-<problem>
-$ARGUMENTS
-</problem>
-
-## Workflow
-
-完整 5 步见 `@skills/ultra-think/SKILL.md`（Scope → Evidence → Multi-Perspective →
-Adversarial → Synthesis）。
-
-**命令入口做的事**：
-1. 读 `$ARGUMENTS` 判定问题范围 — 模糊 → 用 Host 原生提问界面最多澄清 3 个问题
-2. 简单问题 → 直接答；复杂 → 跑完整框架
-3. 输出 Markdown 报告（Problem / Analysis / Options / Adversarial / Recommendation /
-   Verification / Next Steps）
-
-## 用法
-
-```bash
-/ultra-think "should we switch from REST to gRPC for the internal API?"
-/ultra-think "why is the deploy pipeline flaky every 3rd run?"
-```
-
-## 下一步
-
-方案进入 spec → `/ultra-research` 补证据或 `/ultra-plan` 直接排任务；
-纯诊断 → 跟着 Verification Plan 走，取证后再定。
+Read and follow `@skills/ultra-think/SKILL.md`, treating `$ARGUMENTS` as the question to resolve.
+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,19 @@ 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 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.
 
 Stable discoveries use `change.learning_propose`; they reach the baseline only
 through approve/reject/apply transitions in `change.learning_resolve`. Unresolved
@@ -103,7 +109,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 +120,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`        | greenfield/brownfield adoption, specs, verification, unknowns, and approval | 11 |
 | `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 |
@@ -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,26 @@ 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` 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.
+
+`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
+`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.
+
 ## 4. Continuous changes — the daily unit of convergence
 
 After the initial baseline delivery, every fix, feature, redesign, or incident
@@ -151,8 +172,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 +183,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

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-D54，覆盖下文旧 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,9 +10,9 @@
 > Kimi Code 采用各自 native plugin 呈现，其他旧 runtime adapter 已退役。下文所有与此冲突的
 > memory/hindsight 章节仅作为历史实施记录，不再是当前需求或运行时契约。
 
-**当前状态**：v0.10.0；四宿主 native plugin、32 个 live MCP tool、
-schema 10.0（16 表）、Context Spine v2 / breadcrumb / spec-learning、持续
-change/context/convergence/doctor、incident debug lane、
+**当前状态**：v0.12.1；四宿主 native plugin、36 个 live MCP tool、
+schema 11.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 的实施历史，不再作为
 当前 runtime 或发布状态的事实来源。
@@ -1642,6 +1642,7 @@ 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 因四个大文件超预算而无法施工；限制只在损坏权威、缺少执行契约、证据陈旧和最终收敛边界阻断 |
 
 ---
 
@@ -1666,8 +1667,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

@@ -13,7 +13,7 @@ sharing one authoritative workflow store.
 
 **Distribution channels (v1.0)**: npm · Homebrew · pip.
 
-**Release line**: `0.10.x`; every release is gated by `npm run verify:release`.
+**Release line**: `0.11.x`; every release is gated by `npm run verify:release`.
 
 ---
 
@@ -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)
 

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/SKILL-AUTHORING.md

@@ -0,0 +1,75 @@
+# Skill authoring contract
+
+Ultra Builder Pro keeps one portable source workflow and adapts only runtime metadata
+or host invocation details. This contract follows OpenAI Skills guidance and the Agent
+Skills progressive-disclosure format:
+
+- <https://learn.chatgpt.com/docs/build-skills>
+- <https://learn.chatgpt.com/docs/customization/overview>
+- <https://agentskills.io/specification>
+- <https://agentskills.io/skill-creation/best-practices>
+
+## Surface ownership
+
+| Content | Owner |
+|---|---|
+| Repeatable task procedure and conditional references | `skills/<name>/SKILL.md` |
+| Codex display, invocation policy, and dependencies | `skills/<name>/agents/openai.yaml` after adaptation |
+| Host launcher | `commands/<name>.md` |
+| Durable repository or user engineering policy | `AGENTS.md` or the host equivalent |
+| Deterministic lifecycle enforcement | one hook implementation |
+| Live external data or actions | MCP server or connector |
+| Bounded delegated role | `agents/<name>.md` |
+
+Do not duplicate a rule across these surfaces.
+
+## Portable `SKILL.md`
+
+Source frontmatter contains only `name` and `description`. The description says what
+the Skill does and when it should activate. The body uses imperative, outcome-oriented
+steps and includes only information an agent cannot reliably infer from the task,
+repository, or host policy.
+
+Keep the main file compact. Move conditional domain detail to `references/`, reusable
+deterministic work to `scripts/`, and output material to `assets/`. Reference a file
+only from the main workflow or one directly relevant reference.
+
+## Language
+
+The standards do not prohibit Chinese. Ultra source prompts use English as a project
+policy because one source is transformed for Claude Code, Codex, OpenCode, and Kimi
+Code. The host or user instruction controls the response language; a workflow must not
+hard-code the user's output language unless language is itself part of the task.
+
+Maintainer documentation may use the language appropriate for its audience. English
+source prompts are a portability rule, not a claim that multilingual Skills are invalid.
+
+## Content that does not belong in a Skill prompt
+
+- release notes, migration history, old-version behavior, or implementation diary;
+- host tool inventories, model pins, package paths, and dependency metadata shared by
+  only one runtime;
+- generic engineering doctrine already owned by user or repository instructions;
+- one-off project facts, volatile external facts, or copied datasets;
+- duplicated command bodies, hook policy, MCP schemas, or private memory behavior;
+- arbitrary coverage, confidence, complexity, option-count, or severity thresholds;
+- pattern matching that turns TODOs, mocks, catch blocks, or line counts directly into
+  findings without a reachable impact;
+- tutorial-style old/new or good/bad comparisons that do not change the workflow;
+- menus of hypothetical alternatives when one repository default already satisfies the
+  contract.
+
+Comparison is appropriate only when the task requires a real decision or verification:
+compare credible alternatives against shared constraints, accepted specification
+against delivered behavior, or independent analyses against authoritative evidence.
+
+## Review checklist
+
+1. Does the description state a precise use condition?
+2. Is every instruction reusable for this Skill rather than copied global policy?
+3. Is host-specific metadata outside the portable prompt?
+4. Does each conditional reference earn its context cost?
+5. Are judgments evidence-based rather than threshold-based?
+6. Are commands thin and agents bounded?
+7. Do positive and negative trigger evals cover accidental activation?
+8. Do source, four generated runtimes, and package contents pass validation?

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,7 +70,11 @@ 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 |
 | `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 |

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,13 @@ 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 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
+`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.
 """