ultra-builder-pro-cli 0.5.3 → 0.7.0

package/orchestrator/daemon.cjs

@@ -12,7 +12,10 @@
 // calling runDaemon — the runtime layer itself has no opt-in concept.
 
 const ops = require('../mcp-server/lib/state-ops.cjs');
+const runtimeState = require('../mcp-server/lib/runtime-state.cjs');
+const projector = require('../mcp-server/lib/projector.cjs');
 const runner = require('./session-runner.cjs');
+const recovery = require('./recovery.cjs');
 const { evaluate, DEFAULT_RULES, ROUTE_PREFERENCES } = require('./dispatch-rules.cjs');
 
 // Phase 8B.1 — routeTask is now a thin wrapper over evaluate() so Phase 5.4
@@ -29,6 +32,19 @@ function routeTask(task, availableRuntimes) {
   return d.action === 'spawn_agent' ? d.runtime : null;
 }
 
+function maintainState({ db, repoRoot, project = projector.projectAll } = {}) {
+  if (!db) throw new Error('maintainState: db required');
+  if (!repoRoot) throw new Error('maintainState: repoRoot required');
+  const cursor = runtimeState.readConsumerCursor(db, 'spec-staleness');
+  const staleness = ops.consumeSpecChangedEvents(db, { since_id: cursor, limit: 500 });
+  runtimeState.writeConsumerCursor(db, 'spec-staleness', staleness.next_since_id);
+  const ensured = runtimeState.ensureProjectionJob(db, { tool_name: 'orchestrator.maintenance' });
+  const projections = runtimeState.processProjectionJobs(db, {
+    rootDir: repoRoot, project, limit: 500,
+  });
+  return { staleness, ensured, projections };
+}
+
 function runDaemon({
   db,
   repoRoot,
@@ -47,9 +63,30 @@ function runDaemon({
 
   let stopped = false;
   const children = [];
+  let bootRecovery;
+  try {
+    bootRecovery = recovery.recoverOnBoot(db);
+  } catch (error) {
+    runtimeState.recordIncident(db, {
+      code: 'BOOT_RECOVERY_FAILED', severity: 'critical', retryable: true,
+      message: error.message, source_kind: 'orchestrator', source_id: 'boot',
+    });
+    if (onError) onError(error); else throw error;
+    bootRecovery = { recovered: [], count: 0, error: error.message };
+  }
 
   function tick() {
     if (stopped) return;
+    try {
+      maintainState({ db, repoRoot });
+    } catch (error) {
+      runtimeState.recordIncident(db, {
+        code: 'RUNTIME_MAINTENANCE_FAILED', severity: 'error', retryable: true,
+        message: error.message, source_kind: 'orchestrator', source_id: 'maintenance',
+      });
+      if (onError) onError(error); else throw error;
+      return;
+    }
     let pending;
     try {
       const filter = { status: 'pending' };
@@ -102,6 +139,7 @@ function runDaemon({
     },
     get running() { return !stopped; },
     get children() { return children.slice(); },
+    get bootRecovery() { return bootRecovery; },
   };
 }
 
@@ -109,4 +147,5 @@ module.exports = {
   runDaemon,
   routeTask,
   ROUTE_PREFERENCES,
+  maintainState,
 };

package/orchestrator/dispatch-rules.cjs

@@ -13,9 +13,11 @@
 // parallel orchestrator (8B.2) gets a richer decision surface: wave state,
 // deps readiness, and custom rule injection.
 
+const { isSupportedRuntime } = require('../adapters/_shared/runtime-assets.cjs');
+
 const ROUTE_PREFERENCES = Object.freeze({
-  haiku:  ['opencode', 'gemini', 'claude', 'codex'],
-  sonnet: ['claude', 'codex', 'opencode', 'gemini'],
+  haiku:  ['opencode', 'claude', 'codex'],
+  sonnet: ['claude', 'codex', 'opencode'],
   opus:   ['claude', 'codex'],
 });
 
@@ -73,12 +75,21 @@ const DEFAULT_RULES = Object.freeze([
 ]);
 
 function evaluate(ctx, rules = DEFAULT_RULES) {
+  const normalizedCtx = {
+    ...ctx,
+    available_runtimes: Array.isArray(ctx && ctx.available_runtimes)
+      ? [...new Set(ctx.available_runtimes.filter(isSupportedRuntime))]
+      : [],
+  };
   const sorted = [...rules].sort((a, b) => (b.priority || 0) - (a.priority || 0));
   for (const rule of sorted) {
-    if (rule.when(ctx)) {
+    if (rule.when(normalizedCtx)) {
       let runtime = null;
       if (rule.action === 'spawn_agent') {
-        runtime = rule.resolve ? rule.resolve(ctx) : (rule.runtime || null);
+        runtime = rule.resolve ? rule.resolve(normalizedCtx) : (rule.runtime || null);
+        if (!isSupportedRuntime(runtime)) {
+          return { rule_id: rule.id, action: 'block', runtime: null };
+        }
       }
       return { rule_id: rule.id, action: rule.action, runtime };
     }

package/orchestrator/tests/daemon.test.cjs

@@ -15,6 +15,7 @@ const { execFileSync } = require('node:child_process');
 const { initStateDb, closeStateDb } = require('../../mcp-server/lib/state-db.cjs');
 const ops = require('../../mcp-server/lib/state-ops.cjs');
 const daemon = require('../daemon.cjs');
+const RETIRED_RUNTIME = ['gem', 'ini'].join('');
 
 const LONG_SLEEP_CMD = process.execPath;
 const LONG_SLEEP_ARGS = ['-e', 'setInterval(() => {}, 60000);'];
@@ -55,15 +56,15 @@ function cleanup(repoRoot, db, handle) {
 test('routeTask: haiku hint prefers cheap runtimes', () => {
   const runtime = daemon.routeTask(
     { id: 't', complexity_hint: 'haiku' },
-    ['claude', 'opencode', 'codex', 'gemini'],
+    ['claude', 'opencode', 'codex'],
   );
-  assert.ok(['opencode', 'gemini'].includes(runtime), `got ${runtime}`);
+  assert.equal(runtime, 'opencode');
 });
 
 test('routeTask: opus hint prefers strong runtimes', () => {
   const runtime = daemon.routeTask(
     { id: 't', complexity_hint: 'opus' },
-    ['claude', 'opencode', 'codex', 'gemini'],
+    ['claude', 'opencode', 'codex'],
   );
   assert.ok(['claude', 'codex'].includes(runtime), `got ${runtime}`);
 });
@@ -71,23 +72,23 @@ test('routeTask: opus hint prefers strong runtimes', () => {
 test('routeTask: sonnet hint middle-ground', () => {
   const runtime = daemon.routeTask(
     { id: 't', complexity_hint: 'sonnet' },
-    ['claude', 'opencode', 'codex', 'gemini'],
+    ['claude', 'opencode', 'codex'],
   );
-  assert.ok(['claude', 'codex', 'opencode', 'gemini'].includes(runtime));
+  assert.ok(['claude', 'codex', 'opencode'].includes(runtime));
 });
 
 test('routeTask: respects availability constraint', () => {
   const runtime = daemon.routeTask(
     { id: 't', complexity_hint: 'opus' },
-    ['opencode', 'gemini'],
+    ['opencode'],
   );
   // Prefers claude/codex but those aren't available → fall back to any.
-  assert.ok(['opencode', 'gemini'].includes(runtime));
+  assert.equal(runtime, 'opencode');
 });
 
-test('routeTask: no hint → first available', () => {
-  const runtime = daemon.routeTask({ id: 't' }, ['gemini', 'claude']);
-  assert.ok(['gemini', 'claude'].includes(runtime));
+test('routeTask: no hint skips unsupported runtimes', () => {
+  const runtime = daemon.routeTask({ id: 't' }, [RETIRED_RUNTIME, 'claude']);
+  assert.equal(runtime, 'claude');
 });
 
 test('routeTask: no runtimes available → null', () => {
@@ -244,7 +245,7 @@ test('runDaemon applies complexity_hint route', async () => {
     });
     handle = daemon.runDaemon({
       db, repoRoot,
-      runtimes: ['claude', 'opencode', 'gemini'],
+      runtimes: ['claude', 'opencode'],
       pollMs: 50,
       command: LONG_SLEEP_CMD,
       commandArgs: LONG_SLEEP_ARGS,
@@ -252,9 +253,59 @@ test('runDaemon applies complexity_hint route', async () => {
     await new Promise((r) => setTimeout(r, 300));
     const sessions = db.prepare("SELECT * FROM sessions WHERE task_id = 'd-opus'").all();
     assert.equal(sessions.length, 1);
-    // opus should prefer claude over opencode/gemini.
+    // opus should prefer claude over opencode.
     assert.equal(sessions[0].runtime, 'claude');
   } finally {
     cleanup(repoRoot, db, handle);
   }
 });
+
+test('maintainState consumes spec changes with a durable cursor', () => {
+  const repoRoot = mkRepo();
+  const db = mkDb(repoRoot);
+  try {
+    ops.createTask(db, {
+      id: 'maintain-stale', title: 'stale target', type: 'feature', priority: 'P1',
+      trace_to: '.ultra/specs/product.md#daily-change',
+    });
+    ops.appendEvent(db, {
+      type: 'spec_changed', payload: { sections: ['.ultra/specs/product.md#daily-change'] },
+    });
+    const first = daemon.maintainState({ db, repoRoot });
+    assert.equal(first.staleness.processed, 1);
+    assert.equal(ops.readTask(db, 'maintain-stale').stale, true);
+    const second = daemon.maintainState({ db, repoRoot });
+    assert.equal(second.staleness.processed, 0);
+  } finally {
+    cleanup(repoRoot, db);
+  }
+});
+
+test('runDaemon performs crash recovery before dispatch polling', async () => {
+  const repoRoot = mkRepo();
+  const db = mkDb(repoRoot);
+  let handle;
+  try {
+    ops.createTask(db, { id: 'recover-boot', title: 'recover boot', type: 'bugfix', priority: 'P0' });
+    ops.updateTaskStatus(db, 'recover-boot', 'in_progress');
+    ops.createSession(db, {
+      sid: 'dead-session', task_id: 'recover-boot', runtime: 'claude', pid: 999999,
+      worktree_path: '/tmp/dead-worktree', artifact_dir: '/tmp/dead-artifact', lease_seconds: 1,
+    });
+    db.prepare(
+      "UPDATE sessions SET heartbeat_at = '2000-01-01T00:00:00.000Z', lease_expires_at = '2000-01-01T00:00:00.000Z' WHERE sid = 'dead-session'",
+    ).run();
+
+    handle = daemon.runDaemon({
+      db, repoRoot, runtimes: ['claude'], pollMs: 50,
+      command: LONG_SLEEP_CMD, commandArgs: LONG_SLEEP_ARGS,
+    });
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    const session = ops.readSession(db, 'dead-session');
+    assert.equal(session.status, 'crashed');
+    const failure = db.prepare("SELECT * FROM circuit_breaker WHERE task_id = 'recover-boot'").get();
+    assert.equal(failure.failure_count, 1);
+  } finally {
+    cleanup(repoRoot, db, handle);
+  }
+});

package/orchestrator/tests/dispatch-rules.test.cjs

@@ -11,12 +11,13 @@ const { test } = require('node:test');
 const assert = require('node:assert/strict');
 
 const { evaluate, DEFAULT_RULES, ROUTE_PREFERENCES } = require('../dispatch-rules.cjs');
+const RETIRED_RUNTIME = ['gem', 'ini'].join('');
 
 function baseCtx(overrides = {}) {
   return {
     task: { id: 't1' },
     deps_ready: true,
-    available_runtimes: ['claude', 'opencode', 'codex', 'gemini'],
+    available_runtimes: ['claude', 'opencode', 'codex'],
     breaker_state: 'ok',
     wave: null,
     ...overrides,
@@ -42,7 +43,7 @@ test('evaluate: opus hint + only codex available → codex', () => {
 test('evaluate: opus hint + preference exhausted → first available fallback', () => {
   const d = evaluate(baseCtx({
     task: { id: 't', complexity_hint: 'opus' },
-    available_runtimes: ['opencode', 'gemini'],
+    available_runtimes: ['opencode'],
   }));
   assert.equal(d.action, 'spawn_agent');
   assert.equal(d.runtime, 'opencode');
@@ -58,13 +59,13 @@ test('evaluate: sonnet hint + all available → claude', () => {
   assert.equal(d.runtime, 'claude');
 });
 
-test('evaluate: no hint → first available fallback', () => {
+test('evaluate: retired runtimes are discarded before fallback routing', () => {
   const d = evaluate(baseCtx({
     task: { id: 't' },
-    available_runtimes: ['gemini', 'claude'],
+    available_runtimes: [RETIRED_RUNTIME, 'claude'],
   }));
   assert.equal(d.action, 'spawn_agent');
-  assert.equal(d.runtime, 'gemini');
+  assert.equal(d.runtime, 'claude');
 });
 
 // ─── block / defer paths (new in 8B.1) ────────────────────────────────────
@@ -97,20 +98,21 @@ test('evaluate: serial wave already has running task → defer', () => {
 
 // ─── composability: custom rules override defaults ────────────────────────
 
-test('evaluate: custom high-priority rule overrides defaults', () => {
+test('evaluate: custom rules cannot select an unsupported runtime', () => {
   const customRules = [
     ...DEFAULT_RULES,
     {
-      id: 'force-gemini',
+      id: 'force-retired-runtime',
       priority: 999,
       when: () => true,
       action: 'spawn_agent',
-      resolve: () => 'gemini',
+      resolve: () => RETIRED_RUNTIME,
     },
   ];
   const d = evaluate(baseCtx({ task: { id: 't', complexity_hint: 'opus' } }), customRules);
-  assert.equal(d.runtime, 'gemini');
-  assert.equal(d.rule_id, 'force-gemini');
+  assert.equal(d.action, 'block');
+  assert.equal(d.runtime, null);
+  assert.equal(d.rule_id, 'force-retired-runtime');
 });
 
 // ─── ROUTE_PREFERENCES shape guard (regression: don't drift from Phase 5.4) ─

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.5.3",
-  "description": "Multi-runtime installer for the Ultra Builder Pro agent engineering system — deploys commands, agents, skills, hooks, and MCP server to Claude Code, OpenCode, Codex CLI, and Gemini CLI.",
+  "version": "0.7.0",
+  "description": "Multi-runtime installer for the Ultra Builder Pro agent engineering system — deploys commands, agents, skills, hooks, and MCP server to Claude Code, OpenCode, and Codex CLI.",
   "bin": {
     "ultra-builder-pro-cli": "bin/install.js",
     "ubp": "bin/install.js",
@@ -27,13 +27,14 @@
     "skills/ultra-deliver",
     "skills/ultra-status",
     "skills/ultra-think",
+    "skills/ultra-change",
+    "skills/ultra-doctor",
     "skills/code-review-expert",
     "skills/security-rules",
     "skills/integration-rules",
     "skills/testing-rules",
     "skills/cc-collab",
     "skills/codex-collab",
-    "skills/gemini-collab",
     "skills/ultra-verify",
     "hooks/*.py",
     "hooks/adapters/*.py",
@@ -50,7 +51,6 @@
     "docs/ARCHITECTURE.md",
     "docs/AGENT-CONTEXT.md",
     "docs/COMMIT-HASH-BACKFILL.md",
-    "docs/LEGACY-HERMES.md",
     "docs/PLAN.zh-CN.md",
     "docs/STATE-DB-ACCESS-POLICY.md",
     "docs/USER-HANDBOOK-CONTRACT.md",
@@ -60,7 +60,6 @@
     "claude-code",
     "opencode",
     "codex",
-    "gemini",
     "agent",
     "cli",
     "multi-runtime",
@@ -87,7 +86,7 @@
     "test:state": "node --test 'mcp-server/**/*.test.cjs'",
     "test:orch": "node --test 'orchestrator/**/*.test.cjs'",
     "test:spec": "node spec/scripts/test-all.cjs",
-    "test:rest": "node --test adapters/_shared/tests/*.test.cjs adapters/tests/*.test.cjs ultra-tools/*.test.cjs tests/conformance/**/*.test.cjs tests/install.test.cjs tests/package-smoke.test.cjs",
+    "test:rest": "node --test adapters/_shared/tests/*.test.cjs adapters/tests/*.test.cjs ultra-tools/*.test.cjs tests/conformance/**/*.test.cjs tests/install.test.cjs tests/package-smoke.test.cjs tests/retired-runtime.test.cjs",
     "test:all": "npm run test:state && npm run test:orch && npm run test:spec && npm run test:rest",
     "test:hooks": "pytest hooks/tests -q",
     "verify:release": "npm run test:all && npm run test:hooks && npm audit --omit=dev --audit-level=high",
@@ -102,7 +101,6 @@
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "better-sqlite3": "^11.5.0",
-    "chokidar": "^3.6.0",
     "js-yaml": "^4.1.0",
     "openai": "^6.34.0"
   }

package/settings.json

@@ -2,7 +2,6 @@
   "_comment": "Ultra Builder Pro runtime settings. Host hooks and plugin permissions live in each native plugin manifest.",
   "cleanupPeriodDays": 30,
   "orchestrator": {
-    "auto_dispatch": false,
-    "graph_watcher": false
+    "auto_dispatch": false
   }
 }

package/skills/ultra-change/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: ultra-change
+description: "Start or resume a continuous post-delivery change, compile bounded context, declare documentation impact, and route the change through implementation and convergence."
+runtime: all
+mcp_tools_required:
+  - change.create
+  - change.update
+  - change.get
+  - change.list
+  - change.context
+  - task.create
+  - task.list
+---
+
+# ultra-change — Continuous Change Entry
+
+Use this workflow for daily fixes, small features, redesigns, and incidents after
+the initial `init → research → plan → dev → test → deliver` baseline exists.
+Each piece of work becomes one durable change unit instead of an informal edit
+that drifts away from specifications and verification evidence.
+
+## Authority and provider boundary
+
+- `.ultra/state.db` is authoritative for the change, its tasks, events, incidents,
+  context snapshots, and projection status.
+- `.ultra/changes/active/<change-id>/` contains inspectable artifacts, not a
+  second state authority.
+- Memory and code graph are external providers. Pass only metadata references:
+  `provider`, `project`, `reference`, `revision`, `indexed_head`, and `status`.
+- Never paste recalled memories, graph nodes, embeddings, summaries, or provider
+  payloads into `provider_refs`. If provider data is unavailable, record
+  `status: unavailable` and continue with current-checkout evidence.
+- If any required change/task MCP operation is unavailable, stop. Do not edit
+  `state.db`, `tasks.json`, or context projections directly.
+
+## Arguments
+
+- `$1`: existing change id, or a short title for a new change.
+- Optional flags/concepts: `quick`, `standard`, `major`, `incident` and an
+  explicit documentation impact.
+
+## 1. Resume before creating
+
+Call `change.list` for `active` and `blocked` changes. If `$1` matches an
+existing id, call `change.get` and resume it. If the request clearly belongs to
+an active change, show the match and continue there rather than creating a
+duplicate.
+
+Do not resume `ready`, `archived`, or `cancelled` work as a new mutation. Create
+a follow-up change that links to the prior archive in its intent.
+
+## 2. Classify the change
+
+Choose the smallest honest kind:
+
+| Kind | Use when | Required convergence evidence |
+|---|---|---|
+| `quick` | localized fix or tiny behavior change | diff, tests, spec |
+| `standard` | normal feature or cross-file change | diff, tests, spec, docs, review |
+| `major` | architecture, public contract, migration, or broad redesign | diff, tests, spec, docs, review |
+| `incident` | production/runtime failure requiring diagnosis | diagnosis, diff, tests |
+
+When uncertain between two kinds, choose the higher-risk kind. Classification
+changes the proof required; it must not be used to bypass evidence.
+
+## 3. Declare intent and documentation impact
+
+Before implementation, write a concise intent with:
+
+- observed problem or requested outcome;
+- acceptance behavior and non-goals;
+- affected contract/surface;
+- recovery or rollback concern when material.
+
+Documentation impact is mandatory:
+
+- `required`: list every baseline document expected to change;
+- `none`: provide a concrete rationale;
+- `unknown`: allowed only while investigating and blocks convergence.
+
+Create the change with `change.create`. Use a stable kebab-case id. External
+provider references are optional and metadata-only.
+
+## 4. Build the delta packet
+
+The change directory is the bounded execution packet:
+
+```text
+.ultra/changes/active/<change-id>/
+  intent.md
+  context-manifest.json
+  delta/                  # required for standard and major
+  plan.md                 # required for standard and major
+  verification.md         # generated by convergence
+```
+
+For `standard` and `major`, write delta documents under `delta/` describing
+what changes relative to the current baseline. Do not copy the whole baseline.
+Write `plan.md` with live entry points, files/contracts, tests, documentation,
+and rollback. For `quick` and `incident`, add only artifacts needed to make the
+decision and evidence inspectable.
+
+Create at least one task through `task.create` with `change_id` set. Split only
+when ownership, dependencies, or independent verification justify it. All task
+status changes remain MCP-authoritative.
+
+## 5. Compile task context
+
+Call `change.context` before implementation and again whenever any of these
+changes: git HEAD, task set, relevant specs, allowed paths, or provider revision.
+Supply only the minimum task/spec/path references needed for the current slice.
+
+Inspect `context-manifest.json` before handing work to an agent. A stale git head
+or task set is a hard signal to recompile. Provider `status: stale` is visible
+context, not permission to silently refresh or mutate the external provider.
+
+## 6. Route execution
+
+- Implement one linked task with `/ultra-dev <task-id>`.
+- Run `/ultra-test` for project-level evidence.
+- Run `/ultra-review` when the change kind requires review.
+- Update baseline docs declared in `docs_impact` during the change, not after
+  memory has gone cold.
+- Finish with `/ultra-deliver`; it runs deterministic change convergence and
+  archive reconciliation before release actions.
+
+If work exposes a new requirement, update the change intent/delta and recompile
+context before continuing. Never let code become the only record of the change.
+
+## 7. Report
+
+Return the change id, kind, artifact root, linked tasks, documentation impact,
+context freshness, provider-reference status, and exact next workflow. Separate
+provider unavailability from an Ultra runtime incident.
+
+## What this skill does not do
+
+- It does not implement, test, review, release, or repair runtime state.
+- It does not own or synchronize Memory/code-graph content.
+- It does not bypass user approval for destructive or external release actions.