ultra-builder-pro-cli 0.6.0 → 0.7.0

package/commands/ultra-change.md

@@ -0,0 +1,47 @@
+---
+description: Start or resume a continuous post-delivery change with bounded context, documentation impact, and linked authoritative tasks
+argument-hint: "[change-id or title] [quick|standard|major|incident]"
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion
+model: opus
+workflow-ref: "@skills/ultra-change/SKILL.md"
+mcp_tools_required:
+  - change.create
+  - change.update
+  - change.get
+  - change.list
+  - change.context
+  - task.create
+  - task.list
+---
+
+# /ultra-change
+
+## 目标
+
+把初始交付后的日常修复、功能、重构或事故变成一个持续可追踪的 change，避免
+代码、spec、测试证据和项目上下文逐步漂移。
+
+## Workflow
+
+完整流程见 `@skills/ultra-change/SKILL.md`：
+
+1. 先查 active/blocked change，匹配则恢复，避免重复创建。
+2. 按 `quick / standard / major / incident` 分类并声明 docs impact。
+3. 调 `change.create`，为 change 创建至少一个带 `change_id` 的 task。
+4. standard/major 写 delta + plan；调 `change.context` 编译最小上下文。
+5. 路由到 `/ultra-dev`、`/ultra-test`、`/ultra-review`、`/ultra-deliver`。
+
+Memory 与代码图谱只允许以外部 provider 元数据引用出现；本命令不保存 provider
+正文，也不自动刷新外部 provider。
+
+## 用法
+
+```bash
+/ultra-change auth-timeout quick
+/ultra-change billing-redesign major
+/ultra-change incident-2026-07-17 incident
+```
+
+## 下一步
+
+输出会给出 change id、artifact root、linked task 与准确的下一个 Ultra workflow。

package/commands/ultra-deliver.md

@@ -1,18 +1,24 @@
 ---
-description: Release preparation — docs + build + version bump + tag + push, gated by /ultra-test pass
+description: Converge and deliver a verified baseline or continuous change — reconcile specs, archive evidence, version, tag, and push
 argument-hint: "[version-type]"
 allowed-tools: Task, Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion
 model: opus
 workflow-ref: "@skills/ultra-deliver/SKILL.md"
 cli_fallback: "direct user interaction"
+mcp_tools_required:
+  - change.list
+  - change.get
+  - change.context
+  - change.converge
+  - change.archive
 ---
 
 # /ultra-deliver
 
 ## 目标
 
-`/ultra-test` 绿灯后做发布准备：更新 CHANGELOG + technical-debt + README →
-production build → 版本号 + git tag + push。写 `.ultra/delivery-report.json`。
+`/ultra-test` 绿灯后，把 active delta 合并回 baseline，重跑发布证据，调用
+`change.converge` 与 `change.archive`，再完成版本号、tag、push 和 delivery report。
 
 ## 参数
 
@@ -22,14 +28,15 @@ production build → 版本号 + git tag + push。写 `.ultra/delivery-report.js
 
 ## Workflow
 
-完整 5 步见 `@skills/ultra-deliver/SKILL.md`（validations → 文档 → build → 版本发布 → 产物报告）。
+完整流程见 `@skills/ultra-deliver/SKILL.md`（绑定 change → baseline reconciliation →
+build/test → release commit → context/convergence/archive → tag/push → report）。
 
 **命令入口做的事**：
 1. 读 `.ultra/test-report.json` 验 `passed=true` + `git_commit === HEAD`
 2. `git status` 清洁检查；不干净 → 通过 Host 原生提问界面选处理方式
-3. 驱动 skill 跑文档 + build + 版本 + tag + push
-4. 写 `.ultra/delivery-report.json`
-5. 输出 release summary
+3. 有 active change 时合并 delta、刷新 context，并通过确定性 convergence gate
+4. archive 完成后才允许 tag/push
+5. 写带 change id、archive path、baseline updates 的 delivery report
 
 ## 用法
 

package/commands/ultra-dev.md

@@ -8,6 +8,8 @@ mcp_tools_required:
   - task.update
   - task.get
   - task.list
+  - change.get
+  - change.context
 ---
 
 # /ultra-dev
@@ -34,9 +36,10 @@ v4.4→v4.5 迁移，绝不从 `tasks.json` 回退或直接改投影。
 **命令入口做的事**：
 1. 读 `.ultra/workflow-state.json` 决定新跑 vs resume
 2. 首跑通过 Host 原生提问触发 Design Approval Gate
-3. 驱动 skill 走 TDD + review 循环；状态仅通过 MCP `task.update`（双写消除）
-4. Step 4.5 review 通过 `/ultra-review` 和 Host 原生 subagent 执行
-5. Step 4.4 pre-review checkpoint 写入 workflow-state.json，不依赖 `/compact`
+3. 驱动 skill 走 TDD + review 循环；状态仅通过 MCP `task.update`
+4. task 有 `change_id` 时把需求变化写进 active delta，并用 `change.context` 刷新上下文
+5. Step 4.5 review 通过 `/ultra-review` 和 Host 原生 subagent 执行
+6. Step 4.4 pre-review checkpoint 写入 workflow-state.json，不依赖 `/compact`
 
 ## 用法
 

package/commands/ultra-doctor.md

@@ -0,0 +1,36 @@
+---
+description: Inspect Ultra runtime health and optionally run explicit backup-first mechanical recovery
+argument-hint: "[--repair]"
+allowed-tools: Read, Bash
+model: opus
+workflow-ref: "@skills/ultra-doctor/SKILL.md"
+mcp_tools_required:
+  - system.doctor
+cli_fallback: "system doctor"
+---
+
+# /ultra-doctor
+
+## 目标
+
+诊断 state.db、projection、incident、session 和 active change artifact 的健康状态。
+默认只读；只有显式传入 `--repair` 才允许备份后执行机械恢复。
+
+## Workflow
+
+完整契约见 `@skills/ultra-doctor/SKILL.md`。
+
+1. 默认调用 `system.doctor {"repair": false}`。
+2. 只报告失败检查、incident、游标落后和归属边界。
+3. `--repair` 时必须先生成 state.db 备份，再恢复 orphan、消费 staleness event、
+   重排超时中断或失败的 projection 并重新投影。
+4. 修复后重新读取报告；仍 degraded 就明确剩余阻塞，不宣称完成。
+
+## 用法
+
+```bash
+/ultra-doctor
+/ultra-doctor --repair
+```
+
+Memory 和代码图谱属于外部 provider，本命令既不收集也不修复它们。

package/commands/ultra-init.md

@@ -1,5 +1,5 @@
 ---
-description: Initialize Ultra Builder Pro project — scaffold .ultra/, seed tasks.json, optional git
+description: Initialize Ultra Builder Pro project — scaffold .ultra/, initialize state.db and continuous-change directories, optional git
 argument-hint: <name> <type> <stack> [git]
 allowed-tools: Read, Write, Bash, Grep, Glob, AskUserQuestion
 model: opus
@@ -13,8 +13,9 @@ cli_fallback: "task init-project"
 
 ## 目标
 
-搭 `.ultra/` 骨架（specs + tasks + docs + reports）；写入带元数据的 `tasks.json`；
-按需初始化 git。4 个 runtime 行为一致，不依赖 Claude 独占工具。
+搭 `.ultra/` 骨架（specs + tasks + changes + docs + reports），初始化权威
+`state.db`，写入带元数据的初始 `tasks.json`，并按需初始化 git。Claude Code、
+OpenCode、Codex 三个 runtime 行为一致。
 
 ## 参数
 

package/commands/ultra-status.md

@@ -7,6 +7,8 @@ workflow-ref: "@skills/ultra-status/SKILL.md"
 mcp_tools_required:
   - task.list
   - task.get
+  - change.list
+  - system.doctor
 ---
 
 # /ultra-status
@@ -14,7 +16,7 @@ mcp_tools_required:
 ## 目标
 
 一次调用拿整个项目近况：任务进度（来自 state.db `task.list`）+ 测试状态（`test-report.json`）+
-发布状态（`delivery-report.json`）+ 风险检测 + 下一步命令路由。只读。
+发布状态（`delivery-report.json`）+ active change + runtime health + 下一步命令路由。只读。
 任务状态只接受 MCP `task.list`/`task.get`；失败时原样报告并停止，绝不读取
 `tasks.json` 冒充权威数据。旧 v4.4 数据必须先执行正式迁移。
 
@@ -30,9 +32,9 @@ mcp_tools_required:
 
 **命令入口做的事**：
 1. 环境检查（state.db 可达 + 有 task）
-2. `task.list` 拿全量；读 test-report / delivery-report
-3. 算进度 + 风险（blocked / stalled / overdue / complexity spike / test stale）
-4. 按当前 artifact 组合路由到下一个命令（/ultra-init → /ultra-research → /ultra-plan → /ultra-dev → /ultra-test → /ultra-deliver）
+2. `task.list` + `change.list` + read-only `system.doctor`；读 test/delivery report
+3. 算进度 + 风险（含 projection、incident、context/docs drift）
+4. 初始交付后不再显示终局 Done；健康 baseline 的下一项日常工作路由到 `/ultra-change`
 
 ## 用法
 
@@ -44,4 +46,4 @@ mcp_tools_required:
 ## 下一步
 
 看输出的 `▶ Next Up` 块。常见场景：有 pending → `/ultra-dev`；全绿 → `/ultra-test`；
-test passed → `/ultra-deliver`。
+test passed → `/ultra-deliver`；已归档且 baseline 健康 → `/ultra-change`。

package/commands/ultra-test.md

@@ -6,6 +6,7 @@ model: opus
 workflow-ref: "@skills/ultra-test/SKILL.md"
 mcp_tools_required:
   - task.list
+  - change.list
 ---
 
 # /ultra-test
@@ -33,7 +34,7 @@ completed-task 前置检查必须来自 MCP `task.list`；失败时停止，绝
 **命令入口做的事**：
 1. 探测项目类型 + `task.list` 确认 ≥1 completed
 2. 按 scope 跑 gates；失败进 auto-fix（最多 5 轮）
-3. 写 `.ultra/test-report.json`（`passed` + gate-level 明细 + blocking_issues）
+3. 写 `.ultra/test-report.json`（change_id + exact commands + gate 明细 + blocking_issues）
 4. 通过 → 提示 `/ultra-deliver`
 
 ## 用法

package/docs/AGENT-CONTEXT.md

@@ -7,9 +7,9 @@ plugins.
 
 Ultra Builder Pro owns only:
 
-- ten public workflows: `learn`, `ultra-init`, `ultra-research`, `ultra-plan`,
+- twelve public workflows: `learn`, `ultra-init`, `ultra-research`, `ultra-plan`,
   `ultra-dev`, `ultra-test`, `ultra-review`, `ultra-deliver`, `ultra-status`, and
-  `ultra-think`;
+  `ultra-think`, plus the daily `ultra-change` and diagnostic `ultra-doctor`;
 - four internal agent-only rule skills: `code-review-expert`, `security-rules`,
   `integration-rules`, and `testing-rules`;
 - the host-specific collaboration companions and `ultra-verify`;
@@ -24,39 +24,39 @@ not put it in a plugin until that allowlist classifies it.
 ## 2. Three-layer architecture
 
 ```text
-native command or skill -> MCP workflow-state operation -> CLI fallback
-                                  |
-                                  v
-                         .ultra/state.db
+native command or skill -> MCP workflow-state operation -> .ultra/state.db
+                                      ^
+                                      |
+              selected CLI init / doctor / diagnostics / orchestration
 ```
 
 | Layer | Artifact | Contract |
 |---|---|---|
 | Skill/command | `skills/*/SKILL.md`, `commands/*.md` | Model-facing workflow and host-native entry point |
 | MCP | `mcp-server/server.cjs` | Authoritative typed operations over `.ultra/state.db` |
-| CLI | `ultra-tools`, `ubp-orchestrator` | Portable fallback, automation, and diagnostics |
+| 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 tasks, sessions,
-events, telemetry, review evidence, and circuit-breaker state. `tasks.json`,
-context Markdown, execution plans, and reports are projections or workflow
-artifacts; never treat them as a second writable authority.
+`.ultra/state.db` is the only durable Ultra authority for 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 30 contracts across seven families. The bundled
-server registers 21 tools:
+`spec/mcp-tools.yaml` declares and the bundled server registers 29 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 |
+| `system.*` | doctor |
 | `plan.*` | export, get |
 
-The nine declared `review.*`, `impact.*`, `skill.*`, and `ask.*` contracts are
-not advertised by the live server. A generated Codex plugin records their
-native replacements in `spec/codex-capability-map.json`; other hosts use their
-own native review agents, repository discovery, skill loader, and user
-interaction surfaces.
+Review, repository impact discovery, skill loading, and user interaction remain
+host-native capabilities rather than fake MCP contracts. The generated Codex
+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.
@@ -84,17 +84,22 @@ The canonical Python hook allowlist contains seven workflow-only adapters:
 - `pre_stop_check.py` at stop;
 - `subagent_tracker.py` for bounded worker lifecycle evidence.
 
-Every hook is a no-op unless `.ultra/workflow-state.json` describes an active,
-non-terminal workflow. OpenCode expresses the same boundary in its native
-JavaScript plugin. Generic command blocking, post-edit governance, and unrelated
-user hooks are not copied into Ultra Builder Pro.
+`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
+protects the projection; full health inspection is available through
+`system.doctor` rather than a session-start health hook.
+Generic command blocking, post-edit governance, and unrelated user hooks are not
+copied into Ultra Builder Pro.
 
 ## 6. Memory boundary
 
 Ultra Builder Pro has no memory MCP family, recall skill, prompt capture,
 transcript capture, observation journal, or session-summary hook. Persistent
 cross-session memory belongs to a separately installed provider such as
-cloud-mem/claude-mem.
+cloud-mem/claude-mem. Code graph content is equally external. A change context
+may contain only provider metadata references, never provider payload content.
 
 Old Ultra data is never deleted during install. The explicit migration path is:
 
@@ -112,6 +117,9 @@ Archive before prune; the confirmation token is intentionally required.
 .ultra/
 ├── state.db                 # authoritative SQLite store
 ├── workflow-state.json      # active workflow/recovery checkpoint
+├── changes/
+│   ├── active/<id>/         # intent, delta, plan, compiled context, verification
+│   └── archive/             # converged packets after baseline reconciliation
 ├── tasks/                   # projections and task contexts
 ├── specs/                   # research/product/architecture artifacts
 ├── sessions/                # bounded runtime artifacts

package/docs/ARCHITECTURE.md

@@ -35,8 +35,8 @@ the supported hosts share.
         ║              ║   ║                ║   ║    fallback) ║
         ╚══════╤═══════╝   ╚════════╤═══════╝   ╚══════╤═══════╝
                │                    │                  │
-               │ resolve / read     │ task.* etc.      │ same tools
-               │  (D29 read-only)   │                  │ via stdio
+               │ resolve / read     │ task.* etc.      │ selected init /
+               │  (D29 read-only)   │                  │ recovery / ops
                └────────────┬───────┴──────────────────┘
                             ▼
                   ┌─────────────────────┐
@@ -53,25 +53,24 @@ 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 seven declared tool families in [`spec/mcp-tools.yaml`](../spec/mcp-tools.yaml); 21 tools are live and nine scheduled contracts map to host-native surfaces |
-| **CLI**      | the lowest common denominator hooks can call  | `ultra-tools <family> <verb>` — same contract, last-line JSON envelope (see [`spec/cli-protocol.md`](../spec/cli-protocol.md)) |
+| **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) |
+| **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
 us a strongly-typed contract so we can refactor implementations without
-rewriting prompts; CLI gives us a Python-hook-callable fallback when a
-runtime's MCP transport is unavailable. None of the three could carry the
-load alone (D12).
+rewriting prompts; the CLI supplies bounded maintenance and recovery paths when
+the MCP cannot start. It is deliberately not a second change-state API:
+continuous change mutations remain MCP-only and fail closed (D12).
 
-The skill layer is **read-only by design** (D29). We keep `skill.resolve`
-and `skill.manifest` to let the runtime locate a SKILL.md and parse its
-frontmatter; we deliberately removed `skill.invoke` and `skill.list`
-because skills are documentation, not RPC.
+The skill layer is **read-only by design** (D29) and is discovered directly by
+each host. Ultra exposes no `skill.*` MCP family: skills are documentation, not
+RPC, and host-native loaders own resolution and invocation.
 
 ## 3. Authoritative state — `.ultra/state.db`
 
 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 eight tables:
+covers fifteen tables:
 
 | Table              | Holds                                             | Phase |
 |--------------------|---------------------------------------------------|-------|
@@ -83,6 +82,13 @@ covers eight 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    |
+| `artifacts`        | intent/context/verification artifact registry       | 8C    |
+| `context_snapshots`| compiled context hashes, git head, provider refs    | 8C    |
+| `trace_links`      | task/spec/change traceability                        | 8C    |
+| `incidents`        | structured runtime failures and resolutions         | 8C    |
+| `projection_jobs` | durable projection outbox/retry state                | 8C    |
+| `event_consumers` | durable monotonic consumer cursors                   | 8C    |
 
 Two rules make this work:
 
@@ -117,9 +123,32 @@ 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.
 
-## 4. Sessions — the execution unit
+## 4. Continuous changes — the daily unit of convergence
 
-A **session** is the standard unit of execution across all four runtimes
+After the initial baseline delivery, every fix, feature, redesign, or incident
+is represented by a `changes` row and an inspectable packet:
+
+```text
+active -> blocked -> active -> ready -> archived
+   |                              |
+   ├─ intent + delta + plan       └─ verification + baseline reconciliation
+   ├─ linked tasks
+   └─ context-manifest (current HEAD + provider metadata references)
+```
+
+`quick`, `standard`, `major`, and `incident` kinds require different evidence,
+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.
+
+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.
+
+## 5. Sessions — the execution unit
+
+A **session** is the standard unit of execution across all three runtimes
 (D20). One session =
 
 - a fresh OS process for the runtime,
@@ -139,7 +168,7 @@ This admission gate is the smallest piece that prevents two agents from
 silently double-writing the same task — it is part of the v0.1 minimum
 execution layer, not deferred to Phase 5.
 
-## 5. Two timelines — rule layer vs execution layer
+## 6. Two timelines — rule layer vs execution layer
 
 The roadmap separates two concerns that compete for the same surface
 area (D13):
@@ -167,7 +196,7 @@ value from "skills + tasks survive across sessions" long before they get
 value from "ten agents in parallel." Each milestone is independently
 shippable; downstream slip never blocks an earlier release.
 
-## 6. Where to look next
+## 7. Where to look next
 
 | Question                                           | File                                                |
 |----------------------------------------------------|-----------------------------------------------------|
@@ -177,7 +206,7 @@ shippable; downstream slip never blocks an earlier release.
 | What does a tasks.json look like after projection? | [`spec/fixtures/valid/tasks.v4.5.json`](../spec/fixtures/valid/tasks.v4.5.json) |
 | Phase-by-phase work breakdown + decision log       | [`docs/PLAN.zh-CN.md`](./PLAN.zh-CN.md)             |
 
-## 7. Verifying the architecture
+## 8. Verifying the architecture
 
 Every contract on this page is enforced by `npm run test:spec`: