ultra-builder-pro-cli 0.6.0 → 0.8.1

package/agents/debugger.md

@@ -115,6 +115,18 @@ If **3 consecutive fix attempts fail**, and each reveals new problems in differe
 {test output proving fix resolves the issue, no regressions}
 ```
 
+When the parent assigns an Ultra `incident` change, also map the verified report
+into the exact durable `diagnosis.md` contract:
+
+- `Reproduction`: the smallest repeatable symptom and exact trigger;
+- `Hypotheses`: falsifiable hypotheses and the evidence that accepted/rejected each;
+- `Root cause`: the earliest incorrect state and why it occurred;
+- `Regression test`: the failing-first test and its final passing command;
+- `Recovery`: rollback, retry, repair, or operator action when applicable.
+
+Return this content to the primary agent. Do not write `.ultra/state.db` or claim
+incident convergence; the primary agent owns the change artifact and verification.
+
 ## Rules
 
 - Never guess. Every claim must have evidence from code or output.

package/bin/install.js

@@ -16,8 +16,9 @@
  *   -g, --global                                  install to runtime's global config dir
  *   -l, --local                                   install into current working directory
  *   -u, --uninstall                               remove installed assets
+ *   -d, --doctor                                  inspect installation provenance without mutation
+ *   --json                                        emit machine-readable doctor output
  *   -c, --config-dir <path>                       override config directory
- *       --skip-rtk                                do not detect / install RTK hook
  *   -h, --help                                    show help
  */
 
@@ -78,8 +79,9 @@ function printHelp() {
 
   ${paint('yellow', 'Other:')}
     ${paint('cyan', '-u, --uninstall')}    remove installed assets
+    ${paint('cyan', '-d, --doctor')}       verify installed version, provenance, managed assets, and live entry points
+    ${paint('cyan', '--json')}             emit machine-readable doctor output (doctor only)
     ${paint('cyan', '-c, --config-dir')}   override runtime's config directory (string path)
-    ${paint('cyan', '--skip-rtk')}        skip RTK hook registration (RTK is a soft dependency)
     ${paint('cyan', '-h, --help')}         show this help
     ${paint('cyan', '-v, --version')}      show CLI version
 
@@ -92,6 +94,9 @@ function printHelp() {
 
     ${paint('dim', '# Uninstall from OpenCode')}
     npx ultra-builder-pro-cli --opencode --global --uninstall
+
+    ${paint('dim', '# Verify all host installations without changing them')}
+    npx ultra-builder-pro-cli --all --global --doctor
 `);
 }
 
@@ -102,10 +107,11 @@ function parseArgs(argv) {
     global: false,
     local: false,
     uninstall: false,
+    doctor: false,
+    json: false,
     help: false,
     version: false,
     configDir: null,
-    skipRtk: false,
   };
 
   for (let i = 0; i < args.length; i++) {
@@ -120,9 +126,10 @@ function parseArgs(argv) {
       case '-g': case '--global': flags.global = true; break;
       case '-l': case '--local': flags.local = true; break;
       case '-u': case '--uninstall': flags.uninstall = true; break;
+      case '-d': case '--doctor': flags.doctor = true; break;
+      case '--json': flags.json = true; break;
       case '-h': case '--help': flags.help = true; break;
       case '-v': case '--version': flags.version = true; break;
-      case '--skip-rtk': flags.skipRtk = true; break;
       case '-c': case '--config-dir':
         flags.configDir = args[++i];
         if (!flags.configDir || flags.configDir.startsWith('-')) {
@@ -182,13 +189,15 @@ async function main() {
     return;
   }
 
-  printBanner();
-
   if (flags.help) {
+    printBanner();
     printHelp();
     return;
   }
 
+  if (flags.doctor && flags.uninstall) bail('cannot combine --doctor and --uninstall');
+  if (flags.json && !flags.doctor) bail('--json is available only with --doctor');
+
   if (runtimes.length === 0) {
     bail('no runtime selected; use --claude / --opencode / --codex / --all');
   }
@@ -197,15 +206,57 @@ async function main() {
   const repoRoot = path.resolve(__dirname, '..');
   const configDir = flags.configDir ? expandTilde(flags.configDir) : null;
 
-  const mode = flags.uninstall ? 'uninstall' : 'install';
-  console.log(`  ${paint('bold', 'Mode:')}     ${mode}`);
-  console.log(`  ${paint('bold', 'Scope:')}    ${scope}`);
-  console.log(`  ${paint('bold', 'Runtimes:')} ${runtimes.join(', ')}`);
-  if (configDir) console.log(`  ${paint('bold', 'ConfigDir:')} ${configDir}`);
-  console.log();
+  if (!flags.json) printBanner();
+
+  const mode = flags.doctor ? 'doctor' : flags.uninstall ? 'uninstall' : 'install';
+  if (!flags.json) {
+    console.log(`  ${paint('bold', 'Mode:')}     ${mode}`);
+    console.log(`  ${paint('bold', 'Scope:')}    ${scope}`);
+    console.log(`  ${paint('bold', 'Runtimes:')} ${runtimes.join(', ')}`);
+    if (configDir) console.log(`  ${paint('bold', 'ConfigDir:')} ${configDir}`);
+    console.log();
+  }
 
   const ctx = { repoRoot, scope, configDir, homeDir: os.homedir() };
 
+  if (flags.doctor) {
+    const reports = [];
+    for (const runtime of runtimes) {
+      const adapter = loadAdapter(runtime);
+      try {
+        if (typeof adapter.doctor !== 'function') throw new Error('adapter does not expose doctor()');
+        reports.push(await adapter.doctor(ctx));
+      } catch (error) {
+        reports.push({
+          adapter: runtime,
+          status: 'degraded',
+          manifest_path: null,
+          checks: {},
+          issues: [{ code: 'DOCTOR_FAILED', message: error.message }],
+        });
+      }
+    }
+    const output = {
+      status: reports.every((report) => report.status === 'healthy') ? 'healthy' : 'degraded',
+      reports,
+    };
+    if (flags.json) {
+      process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+    } else {
+      for (const report of reports) {
+        const color = report.status === 'healthy' ? 'green' : 'red';
+        console.log(`  ${paint(color, report.status === 'healthy' ? '✓' : '✗')} ${report.adapter}: ${report.status}`);
+        for (const finding of report.issues || []) {
+          const location = finding.path ? ` (${finding.path})` : '';
+          console.log(`      ${finding.code}${location}`);
+        }
+      }
+      console.log();
+    }
+    if (output.status !== 'healthy') process.exitCode = 2;
+    return;
+  }
+
   let failed = 0;
   for (const runtime of runtimes) {
     const adapter = loadAdapter(runtime);
@@ -226,21 +277,6 @@ async function main() {
     process.exit(1);
   }
 
-  // Phase 6.1 — RTK hook (soft dependency; install continues on absence).
-  if (mode === 'install') {
-    const rtk = require('../adapters/_shared/rtk-detect.cjs');
-    const result = rtk.installHook({ skip: flags.skipRtk, scope });
-    if (result.skipped) {
-      console.log(`  ${paint('dim', '⤼ rtk skipped (--skip-rtk)')}`);
-    } else if (result.available && result.initialized) {
-      console.log(`  ${paint('green', '✓')} rtk hook registered (${result.version})`);
-    } else if (result.available && !result.initialized) {
-      console.log(`  ${paint('yellow', '!')} rtk present but init failed: ${result.init_error}`);
-    } else {
-      console.log(`  ${paint('dim', '⤼ ' + result.hint.replace(/\n/g, '\n    '))}`);
-    }
-  }
-
   console.log(`  ${paint('green', 'Done.')}`);
 }
 

package/bin/orchestrator.js

@@ -77,33 +77,9 @@ function cmdRun(opts = {}) {
     onError: (err) => process.stderr.write(`orchestrator error: ${err.message}\n`),
   });
 
-  // Phase 6.4 — optional code-graph watcher (opt-in via settings or CLI).
-  const watcherEnabled =
-    opts.withGraphWatcher === true ||
-    !!(settings && settings.orchestrator && settings.orchestrator.graph_watcher === true);
-  let watcherHandle = null;
-  if (watcherEnabled) {
-    try {
-      const { startWatcher } = require('../orchestrator/code-graph-watcher.cjs');
-      const jsonlPath = path.join(REPO_ROOT, '.ultra', 'code-graph-events.jsonl');
-      fs.mkdirSync(path.dirname(jsonlPath), { recursive: true });
-      watcherHandle = startWatcher({
-        repoRoot: REPO_ROOT,
-        onBatch: (batch) => {
-          try { fs.appendFileSync(jsonlPath, JSON.stringify(batch) + '\n'); }
-          catch (err) { process.stderr.write(`graph-watcher write error: ${err.message}\n`); }
-        },
-      });
-      process.stderr.write(`orchestrator: graph-watcher enabled → ${jsonlPath}\n`);
-    } catch (err) {
-      process.stderr.write(`orchestrator: graph-watcher disabled (${err.message})\n`);
-    }
-  }
-
   const shutdown = (signal) => {
     process.stderr.write(`orchestrator received ${signal}, stopping\n`);
     handle.stop();
-    if (watcherHandle) watcherHandle.stop();
     try { db.close(); } catch (_) { /* ignore */ }
     process.exit(0);
   };
@@ -205,9 +181,8 @@ function usage() {
 
 const argv = process.argv.slice(2);
 const subcommand = argv[0];
-const runOpts = { withGraphWatcher: argv.includes('--with-graph-watcher') };
 switch (subcommand) {
-  case 'run':    cmdRun(runOpts); break;
+  case 'run':    cmdRun();        break;
   case 'start':  cmdStart();      break;
   case 'stop':   cmdStop();       break;
   case 'status': cmdStatus();     break;

package/commands/ultra-change.md

@@ -0,0 +1,48 @@
+---
+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；incident 完成结构化 `diagnosis.md`。
+5. 调 `change.context` 编译最小上下文；incident 先走 debugger 诊断切片。
+6. 路由到 `/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