ultra-builder-pro-cli 0.5.0

package/spec/schemas/context-file.v4.5.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ultra-builder-pro.dev/spec/context-file.v4.5.schema.json",
+  "title": "context-file projection (v4.5)",
+  "description": "Schema for the parsed representation of .ultra/tasks/contexts/task-*.md. The header is regenerated by the projector from state.db (D32). Body sections are author-owned; status MUST NOT appear in body. Trace: PLAN §7.1, D17, D21.",
+  "type": "object",
+  "required": ["header", "body"],
+  "additionalProperties": false,
+  "properties": {
+    "header": {
+      "type": "object",
+      "required": ["task_id", "title", "status", "schema_version"],
+      "additionalProperties": false,
+      "properties": {
+        "task_id":        { "type": "string" },
+        "title":          { "type": "string" },
+        "status": {
+          "type": "string",
+          "enum": ["pending", "in_progress", "completed", "blocked", "expanded"],
+          "x-derived": true,
+          "description": "DERIVED from state.db tasks.status; written by projector, not by humans"
+        },
+        "priority":       { "type": "string", "enum": ["P0", "P1", "P2", "P3"] },
+        "type":           { "type": "string", "enum": ["architecture", "feature", "bugfix"] },
+        "session_id":     { "type": "string", "x-derived": true },
+        "schema_version": { "const": "4.5" },
+        "generated_at":   { "type": "string", "format": "date-time" }
+      }
+    },
+    "body": {
+      "type": "object",
+      "required": ["sections"],
+      "additionalProperties": false,
+      "properties": {
+        "sections": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["heading", "content"],
+            "additionalProperties": false,
+            "properties": {
+              "heading": {
+                "type": "string",
+                "not": { "pattern": "^[Ss]tatus" },
+                "description": "body sections cannot be 'Status' — that lives only in header (D17)"
+              },
+              "content": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/spec/schemas/mcp-tools.schema.json

@@ -0,0 +1,136 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ultra-builder-pro.dev/spec/mcp-tools.schema.json",
+  "title": "MCP tools manifest",
+  "description": "Meta-schema describing the shape of spec/mcp-tools.yaml. The manifest itself is the single source for MCP tool contracts (PLAN R19).",
+  "type": "object",
+  "required": ["version", "info", "tools"],
+  "additionalProperties": false,
+  "properties": {
+    "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+(\\.[0-9]+)?$" },
+    "info": {
+      "type": "object",
+      "required": ["title", "phase", "trace_to"],
+      "additionalProperties": false,
+      "properties": {
+        "title": { "type": "string" },
+        "phase": { "type": "string" },
+        "trace_to": { "type": "string" },
+        "notes": { "type": "string" }
+      }
+    },
+    "families": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "description"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string", "pattern": "^[a-z]+$" },
+          "description": { "type": "string", "minLength": 10 },
+          "phase": { "type": "string" }
+        }
+      }
+    },
+    "tools": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/tool" }
+    }
+  },
+  "$defs": {
+    "tool": {
+      "type": "object",
+      "required": [
+        "name",
+        "family",
+        "description",
+        "phase",
+        "input_schema",
+        "output_schema",
+        "errors",
+        "cli_subcommand"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z_]*\\.[a-z][a-z_]*$",
+          "description": "family.verb naming convention (PLAN §7.3)"
+        },
+        "family": {
+          "type": "string",
+          "enum": ["task", "memory", "review", "impact", "skill", "session", "ask", "plan"]
+        },
+        "description": { "type": "string", "minLength": 10 },
+        "phase": {
+          "type": "string",
+          "pattern": "^[0-9]+(\\.[0-9]+)?[ab]?$",
+          "description": "earliest phase that implements this tool (e.g. 2, 4.5, 4.6a, 8a)"
+        },
+        "readonly": { "type": "boolean", "default": false },
+        "writer_role": {
+          "type": "string",
+          "enum": ["mcp", "cli", "orchestrator", "any"],
+          "default": "mcp",
+          "description": "which process is allowed to invoke (R25 access policy)"
+        },
+        "input_schema": { "$ref": "#/$defs/jsonSchemaFragment" },
+        "output_schema": { "$ref": "#/$defs/jsonSchemaFragment" },
+        "errors": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["code", "description"],
+            "additionalProperties": false,
+            "properties": {
+              "code": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$" },
+              "description": { "type": "string", "minLength": 5 },
+              "retriable": { "type": "boolean", "default": false }
+            }
+          }
+        },
+        "cli_subcommand": {
+          "type": "string",
+          "pattern": "^[a-z][a-z\\- ]*$",
+          "description": "ultra-tools subcommand path (e.g. 'task create', 'session spawn')"
+        },
+        "emits_events": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "events.type values appended to state.db on success"
+        },
+        "trace_to": {
+          "type": "string",
+          "description": "PLAN section/decision id (e.g. §7.3, D33)"
+        }
+      }
+    },
+    "jsonSchemaFragment": {
+      "type": "object",
+      "description": "embedded JSON Schema (Draft 2020-12 subset). validate-mcp-tools.cjs compiles each fragment to ensure it is a usable schema.",
+      "required": ["type"],
+      "properties": {
+        "type": {},
+        "properties": {},
+        "required": {},
+        "additionalProperties": {},
+        "items": {},
+        "enum": {},
+        "oneOf": {},
+        "anyOf": {},
+        "allOf": {},
+        "$ref": {},
+        "format": {},
+        "pattern": {},
+        "minimum": {},
+        "maximum": {},
+        "minLength": {},
+        "maxLength": {},
+        "minItems": {},
+        "description": {}
+      }
+    }
+  }
+}

package/spec/schemas/skill-manifest.schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ultra-builder-pro.dev/spec/skill-manifest.schema.json",
+  "title": "Skill manifest (frontmatter)",
+  "description": "YAML frontmatter contract for skills/*/SKILL.md. Strict additionalProperties=false: any new field must be added here AND propagated through validate-skills.cjs (PLAN R19 single-source rule).",
+  "type": "object",
+  "required": ["name", "description"],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9\\-]*$",
+      "description": "kebab-case slug; matches the directory name"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 10,
+      "description": "human-readable trigger sentence consumed by the runtime's skill router"
+    },
+    "runtime": {
+      "oneOf": [
+        { "type": "string", "enum": ["claude", "opencode", "codex", "gemini", "all"] },
+        {
+          "type": "array",
+          "items": { "type": "string", "enum": ["claude", "opencode", "codex", "gemini"] },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      ],
+      "description": "v4.5 — which runtime(s) this skill targets. Defaults to 'all' when absent (Phase 4 adapter installs everywhere)."
+    },
+    "mcp_tools_required": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^[a-z]+\\.[a-z_]+$" },
+      "uniqueItems": true,
+      "description": "v4.5 — MCP tool names this skill calls; Phase 3+ generators verify availability"
+    },
+    "cli_fallback": {
+      "type": "string",
+      "description": "v4.5 — ultra-tools subcommand to fall back to when MCP unreachable"
+    },
+    "complexity_hint": {
+      "type": "string",
+      "enum": ["haiku", "sonnet", "opus"],
+      "description": "v4.5 — model routing hint (Phase 7+)"
+    },
+    "argument-hint": {
+      "type": "string",
+      "description": "Claude Code convention: hint shown after slash-command name"
+    },
+    "allowed-tools": {
+      "type": "string",
+      "description": "Claude Code convention: comma-separated tool allowlist"
+    },
+    "user-invocable": {
+      "type": "boolean",
+      "description": "Claude Code convention: can the user call this via slash command"
+    },
+    "disable-model-invocation": {
+      "type": "boolean",
+      "description": "Claude Code convention: skill is not auto-invoked by the model"
+    },
+    "context": {
+      "type": "string",
+      "enum": ["fork", "main"],
+      "description": "Claude Code convention: 'fork' isolates skill output from main conversation"
+    },
+    "license": {
+      "type": "string",
+      "description": "third-party skill license (e.g. MIT)"
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "author":  { "type": "string" },
+        "version": { "type": "string" }
+      },
+      "description": "third-party metadata block (vercel skills, etc.)"
+    }
+  },
+  "allOf": [
+    {
+      "if": { "required": ["user-invocable"], "properties": { "user-invocable": { "const": true } } },
+      "then": {
+        "not": {
+          "required": ["disable-model-invocation"],
+          "properties": { "disable-model-invocation": { "const": true } }
+        },
+        "errorMessage": "user-invocable=true cannot coexist with disable-model-invocation=true"
+      }
+    }
+  ]
+}

package/spec/schemas/state-db.sql

@@ -0,0 +1,154 @@
+-- Ultra Builder Pro — authoritative state schema
+-- Phase 2 builds .ultra/state.db from this file. Source of truth for all
+-- task / session / event / telemetry data. tasks.json and context md status
+-- header are projections (PLAN §7.1, D18, D32).
+--
+-- Trace: docs/PLAN.zh-CN.md §7.1; decisions D18/D30/D31/D32/D37.
+--
+-- PRAGMAs are applied by mcp-server/lib/state-db.ts on connection open;
+-- they cannot be persisted in CREATE statements but are documented here.
+--   PRAGMA journal_mode=WAL;        -- multi-reader / single-writer (R21)
+--   PRAGMA synchronous=NORMAL;      -- WAL durability vs perf
+--   PRAGMA busy_timeout=5000;       -- block up to 5s on lock (R25)
+--   PRAGMA foreign_keys=ON;         -- enforce FK constraints
+
+-- ──────────────────────────── tasks ───────────────────────────────────────
+-- Authoritative task row. tasks.json is generated from this table by the
+-- projector (Phase 2.6). Manual edits to tasks.json are overwritten.
+CREATE TABLE IF NOT EXISTS tasks (
+  id                TEXT PRIMARY KEY,
+  title             TEXT NOT NULL,
+  type              TEXT NOT NULL CHECK (type IN ('architecture', 'feature', 'bugfix')),
+  priority          TEXT NOT NULL CHECK (priority IN ('P0', 'P1', 'P2', 'P3')),
+  complexity        INTEGER CHECK (complexity BETWEEN 1 AND 10),
+  status            TEXT NOT NULL DEFAULT 'pending'
+                      CHECK (status IN ('pending', 'in_progress', 'completed', 'blocked', 'expanded')),
+  deps              TEXT,                -- JSON array of task ids
+  files_modified    TEXT,                -- JSON array of paths (Phase 8B conflict detection)
+  session_id        TEXT,                -- current owning session (Phase 4.5)
+  stale             INTEGER NOT NULL DEFAULT 0 CHECK (stale IN (0, 1)),
+  complexity_hint   TEXT CHECK (complexity_hint IN ('haiku', 'sonnet', 'opus')),
+  tag               TEXT,                -- git branch tag (Phase 7.2)
+  trace_to          TEXT,                -- spec anchor reference
+  context_file      TEXT,                -- projection target path
+  completion_commit TEXT,                -- backfilled hash (Phase 2.8)
+  parent_id         TEXT REFERENCES tasks(id) ON DELETE SET NULL,  -- Phase 8A.1: task.expand subtask→parent
+  created_at        TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  updated_at        TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);
+
+CREATE INDEX IF NOT EXISTS tasks_status      ON tasks(status);
+CREATE INDEX IF NOT EXISTS tasks_tag         ON tasks(tag);
+CREATE INDEX IF NOT EXISTS tasks_session     ON tasks(session_id) WHERE session_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS tasks_stale       ON tasks(stale) WHERE stale = 1;
+CREATE INDEX IF NOT EXISTS tasks_parent      ON tasks(parent_id) WHERE parent_id IS NOT NULL;
+
+-- ──────────────────────────── events ──────────────────────────────────────
+-- Append-only event stream. id is the subscription cursor (D31, R26):
+-- subscribers pull `id > since_id` to avoid same-ms event loss that
+-- max(ts) would suffer.
+CREATE TABLE IF NOT EXISTS events (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts            TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  type          TEXT    NOT NULL,
+  task_id       TEXT,
+  session_id    TEXT,
+  runtime       TEXT CHECK (runtime IS NULL OR runtime IN ('claude', 'opencode', 'codex', 'gemini')),
+  payload_json  TEXT
+);
+
+CREATE INDEX IF NOT EXISTS events_ts_type ON events(ts, type);
+CREATE INDEX IF NOT EXISTS events_task    ON events(task_id, id);
+CREATE INDEX IF NOT EXISTS events_session ON events(session_id, id);
+
+-- ──────────────────────────── sessions ────────────────────────────────────
+-- Authoritative session row. lease_expires_at + heartbeat_at live ONLY here
+-- (D32, R29) — no lease.json file. Worktree + artifact_dir are filesystem
+-- paths owned by the session.
+CREATE TABLE IF NOT EXISTS sessions (
+  sid               TEXT PRIMARY KEY,
+  task_id           TEXT NOT NULL REFERENCES tasks(id),
+  runtime           TEXT NOT NULL CHECK (runtime IN ('claude', 'opencode', 'codex', 'gemini')),
+  pid               INTEGER,
+  worktree_path     TEXT NOT NULL,
+  artifact_dir      TEXT NOT NULL,
+  status            TEXT NOT NULL DEFAULT 'running'
+                      CHECK (status IN ('running', 'completed', 'crashed', 'orphan')),
+  lease_expires_at  TEXT NOT NULL,
+  heartbeat_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  started_at        TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);
+
+CREATE INDEX IF NOT EXISTS sessions_active ON sessions(status, task_id);
+CREATE INDEX IF NOT EXISTS sessions_lease  ON sessions(lease_expires_at) WHERE status = 'running';
+
+-- ──────────────────────────── schema_version ──────────────────────────────
+-- Cross-version misread guard (D30, R27). Single row per applied version.
+CREATE TABLE IF NOT EXISTS schema_version (
+  version     TEXT PRIMARY KEY,
+  applied_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  description TEXT
+);
+
+-- ──────────────────────────── migration_history ───────────────────────────
+-- Audit trail for every migration attempt (D30, R27).
+CREATE TABLE IF NOT EXISTS migration_history (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  from_version  TEXT NOT NULL,
+  to_version    TEXT NOT NULL,
+  direction     TEXT NOT NULL CHECK (direction IN ('forward', 'rollback')),
+  ts            TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  status        TEXT NOT NULL CHECK (status IN ('success', 'failed', 'dry_run')),
+  notes         TEXT
+);
+
+CREATE INDEX IF NOT EXISTS migration_history_ts ON migration_history(ts);
+
+-- ──────────────────────────── telemetry ───────────────────────────────────
+-- Token / cost / tool-call counters per session.
+CREATE TABLE IF NOT EXISTS telemetry (
+  id             INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id     TEXT REFERENCES sessions(sid),
+  event_type     TEXT NOT NULL CHECK (event_type IN ('tool_call', 'token_usage', 'cost')),
+  tokens_input   INTEGER,
+  tokens_output  INTEGER,
+  tool_name      TEXT,
+  cost_usd       REAL,
+  ts             TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);
+
+CREATE INDEX IF NOT EXISTS telemetry_session ON telemetry(session_id, ts);
+CREATE INDEX IF NOT EXISTS telemetry_type    ON telemetry(event_type, ts);
+
+-- ──────────────────────────── specs_refs ──────────────────────────────────
+-- Spec change tracking. Phase 5.3 staleness propagation reads this.
+CREATE TABLE IF NOT EXISTS specs_refs (
+  spec_file        TEXT NOT NULL,
+  section          TEXT NOT NULL,
+  anchor           TEXT,
+  last_modified_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  PRIMARY KEY (spec_file, section)
+);
+
+-- ──────────────────────────── circuit_breaker ─────────────────────────────
+-- Per-task failure accumulator (Phase 5.2). When failure_count crosses the
+-- threshold, tripped_at is stamped and `task_circuit_broken` fires. Admission
+-- control refuses new spawns for tripped tasks until manually reset.
+CREATE TABLE IF NOT EXISTS circuit_breaker (
+  task_id             TEXT PRIMARY KEY REFERENCES tasks(id) ON DELETE CASCADE,
+  failure_count       INTEGER NOT NULL DEFAULT 0,
+  tripped_at          TEXT,
+  last_failure_at     TEXT,
+  last_failure_reason TEXT
+);
+
+CREATE INDEX IF NOT EXISTS circuit_breaker_tripped ON circuit_breaker(tripped_at)
+  WHERE tripped_at IS NOT NULL;
+
+-- ──────────────────────────── seed: schema_version ────────────────────────
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES ('4.5', 'Phase 2 initial — tasks/events/sessions/schema_version/migration_history/telemetry/specs_refs');
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES ('5.2', 'Phase 5.2 — circuit_breaker table for per-task trip tracking');
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES ('8A.1', 'Phase 8A.1 — tasks.parent_id for task.expand parent→children');

package/spec/schemas/tasks.v4.5.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ultra-builder-pro.dev/spec/tasks.v4.5.schema.json",
+  "title": "tasks.json projection (v4.5)",
+  "description": "Read-only projection of the tasks table. Generated by the projector (Phase 2.6) — manual edits are overwritten. Status and dependencies are derived from state.db; do not write them through this file. Trace: PLAN §7.1, D21, D32.",
+  "type": "object",
+  "required": ["schema_version", "generated_at", "tasks"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": { "const": "4.5" },
+    "generated_at":   { "type": "string", "format": "date-time" },
+    "source":         { "const": ".ultra/state.db", "description": "authoritative source (D32)" },
+    "tasks": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/task" }
+    }
+  },
+  "$defs": {
+    "task": {
+      "type": "object",
+      "required": ["id", "title", "type", "priority", "status", "created_at", "updated_at"],
+      "additionalProperties": false,
+      "properties": {
+        "id":         { "type": "string", "pattern": "^[a-zA-Z0-9_\\-]+$" },
+        "title":      { "type": "string", "minLength": 3 },
+        "type":       { "type": "string", "enum": ["architecture", "feature", "bugfix"] },
+        "priority":   { "type": "string", "enum": ["P0", "P1", "P2", "P3"] },
+        "complexity": { "type": "integer", "minimum": 1, "maximum": 10 },
+        "status": {
+          "type": "string",
+          "enum": ["pending", "in_progress", "completed", "blocked", "expanded"],
+          "x-derived": true,
+          "description": "DERIVED from state.db tasks.status; never write through this projection"
+        },
+        "deps": {
+          "type": "array",
+          "items": { "type": "string" },
+          "x-derived": true,
+          "description": "DERIVED from state.db tasks.deps JSON"
+        },
+        "files_modified": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Phase 8B conflict surface; new in v4.5"
+        },
+        "session_id": {
+          "type": "string",
+          "x-derived": true,
+          "description": "DERIVED from state.db tasks.session_id (current owning session)"
+        },
+        "stale": {
+          "type": "boolean",
+          "x-derived": true,
+          "description": "DERIVED from staleness propagation (Phase 5.3)"
+        },
+        "complexity_hint": { "type": "string", "enum": ["haiku", "sonnet", "opus"] },
+        "tag":              { "type": "string" },
+        "trace_to":         { "type": "string" },
+        "context_file":     { "type": "string" },
+        "completion_commit": { "type": "string", "pattern": "^[0-9a-f]{7,40}$" },
+        "created_at":       { "type": "string", "format": "date-time" },
+        "updated_at":       { "type": "string", "format": "date-time" }
+      }
+    }
+  }
+}

package/ultra-tools/cli.cjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+/**
+ * ultra-tools — runtime-agnostic state engine for Ultra Builder Pro.
+ *
+ * Shell fallback for Ultra task/session state, status, database maintenance,
+ * migration, and explicit legacy-memory cleanup. User interaction, skill
+ * discovery, and subagent delegation stay on each host's native surfaces.
+ *
+ * Usage:
+ *   ultra-tools <subcommand> [...]
+ *   ultra-tools --help
+ *   ultra-tools --version
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const VERSION = (() => {
+  try {
+    const pkg = require(path.join(__dirname, '..', 'package.json'));
+    return pkg.version;
+  } catch (_err) {
+    return '0.1.0';
+  }
+})();
+
+const USAGE = `ultra-tools v${VERSION}
+
+USAGE:
+  ultra-tools <subcommand> [args]
+
+SUBCOMMANDS:
+  task      create | update | list | get | delete
+  session   spawn | close | get | list | admission | heartbeat | subscribe
+  status    [--cost] [--since <duration>] [--json]
+  db        init | checkpoint | vacuum | integrity | backup (Phase 2)
+  migrate   --from=4.4 --to=4.5 [--dry|--rollback]          (Phase 2)
+  legacy-memory inspect | archive | prune --confirm DELETE_ULTRA_LEGACY_MEMORY
+
+  --help / -h      show this message
+  --version / -v   show version
+
+All state lives under .ultra/ in the project root.
+`;
+
+function readJsonIfExists(p) {
+  if (!fs.existsSync(p)) return null;
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
+  catch (err) {
+    fail(`malformed JSON at ${p}: ${err.message}`);
+  }
+}
+
+function fail(msg, code) {
+  process.stderr.write(`ultra-tools: ${msg}\n`);
+  process.exit(code || 1);
+}
+
+const dbCommand = require('./commands/db.cjs');
+const migrateCommand = require('./commands/migrate.cjs');
+const taskCommand = require('./commands/task.cjs');
+const sessionCommand = require('./commands/session.cjs');
+const statusCommand = require('./commands/status.cjs');
+const legacyMemoryCommand = require('./commands/legacy-memory.cjs');
+
+// Phase 6.2 — CLI telemetry: best-effort, never blocks the subcommand.
+function emitCliTelemetry(sub, rest) {
+  try {
+    const dbPath = path.resolve('.ultra', 'state.db');
+    if (!fs.existsSync(dbPath)) return;
+    const Database = require('better-sqlite3');
+    const db = new Database(dbPath);
+    try {
+      const telemetry = require('../mcp-server/lib/telemetry.cjs');
+      telemetry.appendTelemetry(db, {
+        event_type: 'tool_call',
+        tool_name: `cli.${sub}`,
+        session_id: process.env.UBP_SESSION_ID || null,
+        rootDir: process.cwd(),
+        payload: { args: Array.isArray(rest) ? rest.slice(0, 4) : [] },
+      });
+    } finally { db.close(); }
+  } catch (_) { /* telemetry is opt-in side channel; never crash the CLI */ }
+}
+
+const SUBCOMMANDS = {
+  task: (args) => process.exit(taskCommand.dispatch(args)),
+  session: (args) => process.exit(sessionCommand.dispatch(args)),
+  status: (args) => process.exit(statusCommand.dispatch(args)),
+  db: (args) => process.exit(dbCommand.dispatch(args)),
+  migrate: (args) => process.exit(migrateCommand.dispatch(args)),
+  'legacy-memory': (args) => process.exit(legacyMemoryCommand.dispatch(args)),
+};
+
+function main(argv) {
+  const args = argv.slice(2);
+  if (args.length === 0 || args[0] === '-h' || args[0] === '--help') {
+    process.stdout.write(USAGE);
+    return;
+  }
+  if (args[0] === '-v' || args[0] === '--version') {
+    process.stdout.write(`${VERSION}\n`);
+    return;
+  }
+
+  const [sub, ...rest] = args;
+  const handler = SUBCOMMANDS[sub];
+  if (!handler) fail(`unknown subcommand: ${sub}\n\n${USAGE}`);
+  emitCliTelemetry(sub, rest);
+  handler(rest);
+}
+
+// exports kept for unit tests (Phase 1+)
+module.exports = { USAGE, SUBCOMMANDS, readJsonIfExists, VERSION, main };
+
+if (require.main === module) {
+  main(process.argv);
+}