ultra-builder-pro-cli 0.9.0 → 0.11.0

package/commands/ultra-research.md

@@ -1,59 +1,10 @@
 ---
-description: Think-Driven Interactive Discovery — 17-step research with per-step web search and spec-file output
-argument-hint: [topic]
-allowed-tools: Task, Read, Write, WebSearch, WebFetch, Grep, Glob, AskUserQuestion
-model: opus
+description: Research unresolved product or architecture decisions and update the authoritative baseline specifications
+argument-hint: "[scope-or-question]"
 workflow-ref: "@skills/ultra-research/SKILL.md"
 ---
 
-# Ultra Research v2
+# Research a baseline
 
-**Step-file architecture**: Each research step is a self-contained instruction file loaded just-in-time for maximum LLM attention density.
-
-## How This Works
-
-1. Read the main skill file: `skills/ultra-research/SKILL.md`
-2. Follow the activation sequence (pre-checks → project type detection → step routing)
-3. For each step: Read `skills/ultra-research/steps/step-{NN}-{name}.md` and follow ALL instructions
-4. Each step writes output immediately to spec files, then presents [C] Continue gate
-5. Only proceed to next step after user confirms [C]
-
-## Step Sequence
-
-| Step | File | Focus |
-|------|------|-------|
-| **R0: Product Discovery** | | |
-| 00 | `step-00-problem-validation.md` | Validate the problem is real |
-| 01 | `step-01-opportunity-discovery.md` | Map opportunity space (OST) |
-| 02 | `step-02-market-assessment.md` | TAM/SAM/SOM sizing |
-| 03 | `step-03-competitive-landscape.md` | Competitor analysis |
-| 04 | `step-04-product-strategy.md` | Vision, segments, trade-offs |
-| 05 | `step-05-assumptions-validation.md` | Risk assumptions + experiments |
-| **R1: User & Scenario** | | |
-| 10 | `step-10-user-personas.md` | 2-3 personas |
-| 11 | `step-11-user-scenarios.md` | 3-5 user scenarios |
-| **R2: Feature Definition** | | |
-| 20 | `step-20-user-stories.md` | Stories + acceptance criteria |
-| 21 | `step-21-features-scope.md` | MVP scope + exclusions |
-| 22 | `step-22-success-metrics.md` | KPIs + targets |
-| **R3: Architecture** | | |
-| 30 | `step-30-architecture-context.md` | Quality goals, constraints |
-| 31 | `step-31-solution-strategy.md` | Tech stack decisions |
-| 32 | `step-32-building-blocks.md` | Modules + runtime scenarios |
-| **R4: Quality & Deploy** | | |
-| 40 | `step-40-deployment.md` | Infrastructure + CI/CD |
-| 41 | `step-41-quality-risks.md` | Quality scenarios + risks |
-| **Synthesis** | | |
-| 99 | `step-99-synthesis.md` | Distillate + validation |
-
-## Critical Rules
-
-- **Read SKILL.md first** — it has activation logic and project type detection
-- **One step at a time** — never load multiple step files simultaneously
-- **Write immediately** — every step writes to spec file before presenting to user
-- **Web search mandatory** — factual claims need sources, no exceptions
-- **User gate** — halt at [C] Continue, do not auto-proceed
-
-## Begin
-
-Read `skills/ultra-research/SKILL.md` now and follow the activation sequence.
+Read and follow `@skills/ultra-research/SKILL.md`, using `$ARGUMENTS` to bound the research scope.
+Treat the referenced skill as the only workflow definition.

package/commands/ultra-status.md

@@ -1,49 +1,10 @@
 ---
-description: Real-time project status — progress + risks + workflow routing, via MCP task.list
-argument-hint: "[task-id]"
-allowed-tools: Read, Bash(git status), Bash(git log *), Grep, Glob, Task
-model: opus
+description: Report authoritative Ultra health, readiness, evidence freshness, and one next action
+argument-hint: "[task-or-change-id]"
 workflow-ref: "@skills/ultra-status/SKILL.md"
-mcp_tools_required:
-  - task.list
-  - task.get
-  - change.list
-  - system.doctor
 ---
 
-# /ultra-status
+# Report Ultra status
 
-## 目标
-
-一次调用拿整个项目近况：任务进度（来自 state.db `task.list`）+ 测试状态（`test-report.json`）+
-发布状态（`delivery-report.json`）+ active change + runtime health + 下一步命令路由。只读。
-任务状态只接受 MCP `task.list`/`task.get`；失败时原样报告并停止，绝不读取
-`tasks.json` 冒充权威数据。旧 v4.4 数据必须先执行正式迁移。
-
-## 参数
-
-| 位 | 含义 | 缺省 |
-|----|------|------|
-| `$1` | 单 task id（只看这个 task） | 不填 → 全局报告 |
-
-## Workflow
-
-完整 5 阶段见 `@skills/ultra-status/SKILL.md`（validation → load → progress → risk → routing）。
-
-**命令入口做的事**：
-1. 环境检查（state.db 可达 + 有 task）
-2. `task.list` + `change.list` + read-only `system.doctor`；读 test/delivery report
-3. 算进度 + 风险（含 projection、incident、context/docs drift）
-4. 初始交付后不再显示终局 Done；健康 baseline 的下一项日常工作路由到 `/ultra-change`
-
-## 用法
-
-```bash
-/ultra-status            # 项目全局报告
-/ultra-status 3          # 只看 task 3
-```
-
-## 下一步
-
-看输出的 `▶ Next Up` 块。常见场景：有 pending → `/ultra-dev`；全绿 → `/ultra-test`；
-test passed → `/ultra-deliver`；已归档且 baseline 健康 → `/ultra-change`。
+Read and follow `@skills/ultra-status/SKILL.md`, using `$ARGUMENTS` to select a specific task or change.
+Treat the referenced skill as the only workflow definition.

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

@@ -44,14 +44,14 @@ reports are projections or workflow artifacts.
 
 ## 3. Live MCP and declared contracts
 
-`spec/mcp-tools.yaml` declares and the bundled server registers 29 tools across
+`spec/mcp-tools.yaml` declares and the bundled server registers 32 tools across
 five families:
 
 | Family | Live tools |
 |---|---|
 | `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, converge, archive |
+| `change.*` | create, update, get, list, context, breadcrumb, learning_propose, learning_resolve, converge, archive |
 | `system.*` | doctor |
 | `plan.*` | export, get |
 
@@ -62,7 +62,26 @@ capability map documents those replacements.
 Any new MCP contract starts in `spec/mcp-tools.yaml` with valid and invalid
 fixtures. Do not add an ad-hoc server handler first.
 
-## 4. Native host presentation
+## 4. Context Spine contract
+
+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`.
+
+`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.
+
+Stable discoveries use `change.learning_propose`; they reach the baseline only
+through approve/reject/apply transitions in `change.learning_resolve`. Unresolved
+learning blocks convergence. Review contributes two independent axes,
+`spec_fidelity` and `engineering_standards`; neither can replace the other.
+
+## 5. Native host presentation
 
 | Host | Plugin form | Workflow entry | Hook form | Collaboration companions |
 |---|---|---|---|---|
@@ -75,9 +94,10 @@ The current host remains primary. Collaboration skills call another runtime
 only when explicitly requested, use it as a read-only advisor, and return the
 evidence to the primary host for final verification.
 
-## 5. Hook boundary
+## 6. Hook boundary
 
-The canonical Python hook allowlist contains seven workflow-only adapters:
+The canonical Python hook bundle contains seven executable workflow hooks plus
+the shared read-only `context_spine.py` breadcrumb helper:
 
 - `health_check.py` and `workflow_context.py` on session start;
 - `active_task_context.py` before an edit;
@@ -86,7 +106,9 @@ The canonical Python hook allowlist contains seven workflow-only adapters:
 - `pre_stop_check.py` at stop;
 - `subagent_tracker.py` for bounded worker lifecycle evidence.
 
-`health_check.py` and `workflow_context.py` may inspect any initialized project;
+`workflow_context.py`, `active_task_context.py`, and `workflow_resume.py` read the
+same DB-derived breadcrumb through `context_spine.py`. `health_check.py` and
+`workflow_context.py` may inspect any initialized project;
 `active_task_context.py` always protects the task projection but limits ordinary
 edit guidance to an active workflow. Compact/stop/subagent hooks remain
 active-workflow scoped. OpenCode natively injects baseline/change context and
@@ -95,7 +117,7 @@ protects the projection; full health inspection is available through
 Generic command blocking, post-edit governance, and unrelated user hooks are not
 copied into Ultra Builder Pro.
 
-## 6. Memory boundary
+## 7. Memory boundary
 
 Ultra Builder Pro has no memory MCP family, recall skill, prompt capture,
 transcript capture, observation journal, or session-summary hook. Persistent
@@ -113,14 +135,14 @@ ultra-tools legacy-memory prune --confirm DELETE_ULTRA_LEGACY_MEMORY
 
 Archive before prune; the confirmation token is intentionally required.
 
-## 7. Project state layout
+## 8. Project state layout
 
 ```text
 .ultra/
 ├── state.db                 # authoritative SQLite store
 ├── workflow-state.json      # active workflow/recovery checkpoint
 ├── changes/
-│   ├── active/<id>/         # intent, delta, plan, compiled context, verification
+│   ├── active/<id>/         # intent, delta, plan, context v2, learning, verification
 │   └── archive/             # converged packets after baseline reconciliation
 ├── tasks/                   # projections and task contexts
 ├── specs/                   # research/product/architecture artifacts
@@ -130,7 +152,7 @@ Archive before prune; the confirmation token is intentionally required.
 └── delivery-report.json
 ```
 
-## 8. User handbook integration
+## 9. User handbook integration
 
 General engineering doctrine remains user-owned in `CLAUDE.md` or `AGENTS.md`.
 Ultra Builder Pro contributes one managed section only. Preview or apply it with:
@@ -140,12 +162,12 @@ ubp-handbook preview --runtime codex
 ubp-handbook apply --runtime codex
 ```
 
-Supported runtime names are `claude`, `codex`, and `opencode`. Apply creates a
+Supported runtime names are `claude`, `codex`, `opencode`, and `kimi`. Apply creates a
 timestamped backup, replaces only the marked block, and can migrate the old
 Codex `## Ultra Builder Pro Runtime Contract` section without touching the next
 user section. Plugin adapters themselves do not silently overwrite handbooks.
 
-## 9. Verification
+## 10. Verification
 
 Run `npm run test:all`, `python3 -m pytest hooks/tests -q`, and `npm audit`.
 Adapter tests assert the allowlisted assets, native manifests, hook boundary,

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 API             | stdio MCP server exposing 29 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 32 live tools across 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,7 +70,7 @@ 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 fifteen tables:
+covers sixteen tables:
 
 | Table              | Holds                                             | Phase |
 |--------------------|---------------------------------------------------|-------|
@@ -84,7 +84,8 @@ covers fifteen tables:
 | `circuit_breaker`  | bounded retry and halt state for failed tasks       | 5     |
 | `changes`          | continuous feature/fix/incident lifecycle           | 8C    |
 | `artifacts`        | intent/context/verification artifact registry       | 8C    |
-| `context_snapshots`| compiled context hashes, git head, provider refs    | 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 |
 | `trace_links`      | task/spec/change traceability                        | 8C    |
 | `incidents`        | structured runtime failures and resolutions         | 8C    |
 | `projection_jobs` | durable projection outbox/retry state                | 8C    |
@@ -101,7 +102,8 @@ 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`,
-   `telemetry`, `specs_refs`, and `migration_history`; the CLI calls
+   `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
    `events` table is append-only and explicitly multi-writer — CLI and
    orchestrator processes append directly to it under the same WAL +
@@ -133,7 +135,8 @@ active -> blocked -> active -> ready -> archived
    |                              |
    ├─ intent + delta + plan       └─ verification + baseline reconciliation
    ├─ linked tasks
-   └─ context-manifest (current HEAD + provider metadata references)
+   ├─ context-manifest v2 (role + gate + readiness + execution seam)
+   └─ spec-learning candidates (proposed -> approved/rejected -> applied)
 ```
 
 `quick`, `standard`, `major`, and `incident` kinds require different evidence,
@@ -141,6 +144,29 @@ but all require completed linked tasks, current context, declared documentation
 impact, and no open incident. Memory and graph payloads never enter Ultra;
 `context_snapshots.provider_refs_json` stores metadata references only.
 
+### Context Spine
+
+Context Manifest v2 is the handoff contract between planning, implementation,
+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);
+- an execution contract (`slice_kind`, public seam, exact verification command);
+- one deterministic next action.
+
+`change.breadcrumb` derives the compact current position from state.db. Session,
+edit, and resume hooks inject only this breadcrumb, never the intent body,
+provider content, or a conversation summary. A changed git HEAD marks the
+snapshot stale and routes back to `change.context`.
+
+`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
+convergence, so daily work cannot leave accepted behavior stranded in chat or a
+delta packet.
+
 `incident` is the canonical debug lane. Creating one also registers a durable
 `diagnosis.md` artifact with five mandatory sections: reproduction, hypotheses,
 root cause, regression test, and recovery. Convergence validates the artifact

package/docs/PLAN.zh-CN.md

@@ -10,8 +10,9 @@
 > Kimi Code 采用各自 native plugin 呈现，其他旧 runtime adapter 已退役。下文所有与此冲突的
 > memory/hindsight 章节仅作为历史实施记录，不再是当前需求或运行时契约。
 
-**当前状态**：v0.9.0；四宿主 native plugin、29 个 live MCP tool、
-schema 9.1（15 表）、持续 change/context/convergence/doctor、incident debug lane、
+**当前状态**：v0.11.0；四宿主 native plugin、32 个 live MCP tool、
+schema 10.0（16 表）、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 或发布状态的事实来源。

package/docs/ROADMAP.md

@@ -13,7 +13,7 @@ sharing one authoritative workflow store.
 
 **Distribution channels (v1.0)**: npm · Homebrew · pip.
 
-**Release line**: `0.9.x`; every release is gated by `npm run verify:release`.
+**Release line**: `0.11.x`; every release is gated by `npm run verify:release`.
 
 ---
 
@@ -43,20 +43,21 @@ sharing one authoritative workflow store.
 | 8A    | Plan automation (parse / topo / expand + artifact + human gate) | ✅ done (D47, `a932cb8`) → v0.3 |
 | 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 |
 | 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          (29 live tools across 5 families)
+├── mcp-tools.yaml          (32 live tools across 5 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, 29 task/session/change/system/plan tools)
+├── server.cjs              (stdio MCP server, 32 task/session/change/system/plan tools)
 ├── lib/
 │   ├── state-db.cjs        (SQLite + WAL + pragmas)
 │   ├── state-ops.cjs       (full write API, status state machine)
@@ -74,7 +75,7 @@ bin/install.js              ← multi-runtime installer
 bin/handbook.js             ← explicit managed user-handbook sync
 adapters/                   ← native Claude/OpenCode/Codex plugin builders
 skills/                     ← allowlisted Ultra workflows, internal rules, and collab companions
-hooks/                      ← 7 workflow-only Python hooks; OpenCode uses native JavaScript hooks
+hooks/                      ← 7 executable workflow hooks + shared Context Spine helper; OpenCode uses native JavaScript hooks
 docs/
 ├── PLAN.zh-CN.md                historical phase plan + decision log
 ├── ARCHITECTURE.md              Phase 1 single-page entry point

package/docs/RUNTIME-COMPAT-MATRIX.md

@@ -46,7 +46,7 @@ not presented as nonexistent custom agents.
 
 | Lifecycle | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
 |---|---|---|---|---|
-| Session context/health | FULL, native `SessionStart` | DEGRADED, native context; health via `system.doctor` | FULL, native `SessionStart` | FULL, session-start skill + `SessionStart` hooks |
+| Session context/health | FULL, DB-derived Context Spine breadcrumb on native `SessionStart` | DEGRADED, projected v2 breadcrumb; health via `system.doctor` | FULL, DB-derived breadcrumb on native `SessionStart` | FULL, DB-derived breadcrumb via session-start skill + hooks |
 | 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 |
@@ -69,12 +69,14 @@ generic post-edit policy.
 | 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 | 29 | 29 | 29 | 29 |
+| Live/declared contracts | 32 | 32 | 32 | 32 |
+| 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 29 `task.*`, `session.*`, `change.*`, `system.*`, and `plan.*` operations
+All 32 `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.
 
@@ -121,9 +123,9 @@ records. Uninstall refuses an unmanaged or conflicting root.
 
 | Capability | Contract |
 |---|---|
-| Current state schema | `9.1` |
+| Current state schema | `10.0` |
 | Runtime values | `claude`, `opencode`, `codex`, `kimi` |
-| Upgrade from pre-Kimi schema | transactionally rebuilds only constrained `events` and `sessions` tables |
+| Upgrade from earlier schema | preserves Kimi runtime rows, adds Context Spine columns and `spec_learning_candidates` transactionally |
 | 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/USER-HANDBOOK-CONTRACT.md

@@ -7,8 +7,8 @@ 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, memory, hook, agent, and package boundaries with host-native command
-syntax:
+authority, Context Spine, specification-learning, memory, hook, agent, and
+package boundaries with host-native command syntax:
 
 | Runtime | Default target | Main invocation form |
 |---|---|---|
@@ -20,6 +20,13 @@ syntax:
 The renderer never copies Claude Code-only APIs into Codex, OpenCode, or Kimi. Each
 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.
+
 ## Managed-block contract
 
 The owned content is bounded by:

package/hooks/README.md

@@ -7,10 +7,11 @@ bounded to the relevant Ultra projection or a non-terminal workflow.
 | Lifecycle | Hook | Purpose |
 |---|---|---|
 | Session start | `health_check.py` | Read-only integrity, incident, projection, session, and change-artifact checks |
-| Session start | `workflow_context.py` | Inject baseline/active workflow/change context and filtered provider metadata references |
-| Before edit | `active_task_context.py` | Protect `tasks.json` projection and restate an active task boundary |
+| Shared helper | `context_spine.py` | Read the latest role/gate/readiness snapshot from state.db and derive one compact breadcrumb |
+| Session start | `workflow_context.py` | Inject the DB-derived breadcrumb without intent or provider payloads |
+| 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` | Select the newest valid live/checkpoint state, restore it atomically when needed, and re-inject the boundary |
+| 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 |
 | Subagent lifecycle | `subagent_tracker.py` | Append lifecycle evidence under `.ultra/runtime/` |
 
@@ -18,7 +19,8 @@ The plugin deliberately does not capture prompts, tool observations, transcripts
 cross-session memory or code-graph content. Generic command blocking and post-edit policy are
 user/repository governance. Persistent Memory/graph content belongs to separately installed providers.
 
-The checkpoint is a recovery artifact, not a second authority. A valid newer
+`context_spine.py` is an imported library, not an eighth lifecycle registration.
+Registering it separately would duplicate hook execution. The checkpoint is a recovery artifact, not a second authority. A valid newer
 live workflow wins; a newer valid checkpoint may restore a missing or older
 live file; corrupt, non-object, or terminal checkpoints are ignored.