ultra-builder-pro-cli 0.6.0 → 0.7.0

package/spec/mcp-tools.yaml

@@ -23,6 +23,8 @@ families:
   - { name: task,    description: 'authoritative task lifecycle on state.db', phase: '2' }
   - { name: session, description: 'execution-unit lifecycle with single-active-lease admission (D33)', phase: '4.5' }
   - { name: plan,    description: 'execution-plan artifact export and query (D34)', phase: '8a' }
+  - { name: change,  description: 'continuous post-delivery change lifecycle and convergence', phase: '9' }
+  - { name: system,  description: 'read-only diagnostics and explicit backup-first repair', phase: '9' }
 
 tools:
 
@@ -48,6 +50,7 @@ tools:
         parent_id:      { type: string, description: 'Phase 8A.3 parent reference for task.expand children' }
         tag:            { type: string, description: 'git branch tag (Phase 7.2)' }
         trace_to:       { type: string, description: 'spec anchor (e.g. spec/mcp-tools.yaml#task.create)' }
+        change_id:      { type: string, pattern: '^[a-zA-Z0-9_\-]+$', description: 'continuous change unit owning this task' }
     output_schema:
       type: object
       required: [id, status, created_at]
@@ -90,6 +93,7 @@ tools:
             stale:         { type: boolean }
             tag:           { type: string }
             completion_commit: { type: string, pattern: '^[0-9a-f]{7,40}$' }
+            change_id:    { type: ['string', 'null'], pattern: '^[a-zA-Z0-9_\-]+$' }
     output_schema:
       type: object
       required: [ok, task]
@@ -245,12 +249,15 @@ tools:
           description: override path to the template root (defaults to bundled templates/.ultra/)
     output_schema:
       type: object
-      required: [created_path, status, copied_files]
+      required: [created_path, state_db_path, status, copied_files]
       additionalProperties: false
       properties:
         created_path:
           type: string
           description: absolute path to the created `.ultra/` directory
+        state_db_path:
+          type: string
+          description: absolute path to the initialized authoritative SQLite database
         status:
           type: string
           enum: [created, overwritten]
@@ -358,6 +365,7 @@ tools:
       additionalProperties: false
       properties:
         task_id:    { type: string }
+        change_id:  { type: string }
         session_id: { type: string }
         runtime:    { type: string, enum: [claude, opencode, codex] }
         type:
@@ -385,6 +393,11 @@ tools:
             - cost_alert
             - token_alert
             - circuit_open
+            - change_created
+            - change_updated
+            - change_blocked
+            - change_converged
+            - change_archived
         payload: { type: object }
     output_schema:
       type: object
@@ -614,6 +627,329 @@ tools:
     emits_events: []
     trace_to: '§7.3, D31'
 
+  # ────────────────────────── change family ──────────────────────────────
+  - name: change.create
+    family: change
+    description: Create a continuous feature, fix, redesign, or incident change unit and its initial context manifest.
+    phase: '9'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [id, title, kind, intent]
+      additionalProperties: false
+      properties:
+        id: { type: string, pattern: '^[a-zA-Z0-9_\-]+$' }
+        title: { type: string, minLength: 3 }
+        kind: { type: string, enum: [quick, standard, major, incident] }
+        intent: { type: string, minLength: 3 }
+        base_commit: { type: string, pattern: '^[0-9a-f]{7,40}$' }
+        docs_impact:
+          type: object
+          additionalProperties: false
+          properties:
+            status: { type: string, enum: [unknown, required, none] }
+            files: { type: array, items: { type: string } }
+            rationale: { type: ['string', 'null'] }
+        provider_refs:
+          type: object
+          additionalProperties: false
+          properties:
+            memory:
+              type: object
+              required: [provider]
+              additionalProperties: false
+              properties:
+                provider: { type: string }
+                project: { type: string }
+                reference: { type: string }
+                revision: { type: string }
+                indexed_head: { type: string }
+                status: { type: string, enum: [available, unavailable, fresh, stale, unknown] }
+            code_graph:
+              type: object
+              required: [provider]
+              additionalProperties: false
+              properties:
+                provider: { type: string }
+                project: { type: string }
+                reference: { type: string }
+                revision: { type: string }
+                indexed_head: { type: string }
+                status: { type: string, enum: [available, unavailable, fresh, stale, unknown] }
+    output_schema:
+      type: object
+      required: [change, intent_path, context_manifest_path]
+      additionalProperties: false
+      properties:
+        change: { type: object }
+        intent_path: { type: string }
+        context_manifest_path: { type: string }
+    errors:
+      - { code: DUPLICATE_CHANGE_ID, description: 'change id already exists' }
+      - { code: PROVIDER_CONTENT_FORBIDDEN, description: 'provider payload content must remain external' }
+      - { code: VALIDATION_ERROR, description: 'change input failed validation' }
+    cli_subcommand: change create
+    emits_events: [change_created, context_updated]
+
+  - name: change.update
+    family: change
+    description: Update change intent, documentation impact, external provider metadata, or active status.
+    phase: '9'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [id, patch]
+      additionalProperties: false
+      properties:
+        id: { type: string }
+        patch:
+          type: object
+          additionalProperties: false
+          properties:
+            title: { type: string, minLength: 3 }
+            intent: { type: string, minLength: 3 }
+            status: { type: string, enum: [active, blocked, cancelled] }
+            docs_impact:
+              type: object
+              additionalProperties: false
+              properties:
+                status: { type: string, enum: [unknown, required, none] }
+                files: { type: array, items: { type: string } }
+                rationale: { type: ['string', 'null'] }
+            provider_refs:
+              type: object
+              additionalProperties: false
+              properties:
+                memory:
+                  type: object
+                  required: [provider]
+                  additionalProperties: false
+                  properties:
+                    provider: { type: string }
+                    project: { type: string }
+                    reference: { type: string }
+                    revision: { type: string }
+                    indexed_head: { type: string }
+                    status: { type: string, enum: [available, unavailable, fresh, stale, unknown] }
+                code_graph:
+                  type: object
+                  required: [provider]
+                  additionalProperties: false
+                  properties:
+                    provider: { type: string }
+                    project: { type: string }
+                    reference: { type: string }
+                    revision: { type: string }
+                    indexed_head: { type: string }
+                    status: { type: string, enum: [available, unavailable, fresh, stale, unknown] }
+    output_schema:
+      type: object
+      required: [ok, change]
+      additionalProperties: false
+      properties:
+        ok: { type: boolean }
+        change: { type: object }
+    errors:
+      - { code: CHANGE_NOT_FOUND, description: 'change id does not exist' }
+      - { code: CHANGE_NOT_MUTABLE, description: 'ready, archived, and cancelled changes are immutable' }
+      - { code: ILLEGAL_CHANGE_TRANSITION, description: 'change transition is not permitted' }
+      - { code: PROVIDER_CONTENT_FORBIDDEN, description: 'provider payload content must remain external' }
+    cli_subcommand: change update
+    emits_events: [change_updated]
+
+  - name: change.get
+    family: change
+    description: Read one continuous change unit from authoritative state.
+    phase: '9'
+    readonly: true
+    input_schema:
+      type: object
+      required: [id]
+      additionalProperties: false
+      properties:
+        id: { type: string }
+    output_schema:
+      type: object
+      required: [change]
+      additionalProperties: false
+      properties:
+        change: { type: object }
+    errors:
+      - { code: CHANGE_NOT_FOUND, description: 'change id does not exist' }
+    cli_subcommand: change get
+    emits_events: []
+
+  - name: change.list
+    family: change
+    description: List continuous changes by lifecycle status or change kind.
+    phase: '9'
+    readonly: true
+    input_schema:
+      type: object
+      additionalProperties: false
+      properties:
+        status: { type: string, enum: [active, blocked, ready, archived, cancelled] }
+        kind: { type: string, enum: [quick, standard, major, incident] }
+        limit: { type: integer, minimum: 1, maximum: 500 }
+    output_schema:
+      type: object
+      required: [changes, count]
+      additionalProperties: false
+      properties:
+        changes: { type: array, items: { type: object } }
+        count: { type: integer, minimum: 0 }
+    errors:
+      - { code: VALIDATION_ERROR, description: 'change filter failed validation' }
+    cli_subcommand: change list
+    emits_events: []
+
+  - name: change.context
+    family: change
+    description: Compile an inspectable task context manifest from Ultra state and external provider metadata references.
+    phase: '9'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [id]
+      additionalProperties: false
+      properties:
+        id: { type: string }
+        task_id: { type: string }
+        spec_refs: { type: array, items: { type: object } }
+        allowed_paths: { type: array, items: { type: string } }
+        provider_refs:
+          type: object
+          additionalProperties: false
+          properties:
+            memory:
+              type: object
+              required: [provider]
+              additionalProperties: false
+              properties:
+                provider: { type: string }
+                project: { type: string }
+                reference: { type: string }
+                revision: { type: string }
+                indexed_head: { type: string }
+                status: { type: string, enum: [available, unavailable, fresh, stale, unknown] }
+            code_graph:
+              type: object
+              required: [provider]
+              additionalProperties: false
+              properties:
+                provider: { type: string }
+                project: { type: string }
+                reference: { type: string }
+                revision: { type: string }
+                indexed_head: { type: string }
+                status: { type: string, enum: [available, unavailable, fresh, stale, unknown] }
+    output_schema:
+      type: object
+      required: [manifest_path, manifest_hash, manifest]
+      additionalProperties: false
+      properties:
+        manifest_path: { type: string }
+        manifest_hash: { type: string, pattern: '^[0-9a-f]{64}$' }
+        manifest: { type: object }
+    errors:
+      - { code: CHANGE_NOT_FOUND, description: 'change id does not exist' }
+      - { code: CHANGE_TERMINAL, description: 'terminal change cannot compile a new context' }
+      - { code: PROVIDER_CONTENT_FORBIDDEN, description: 'provider payload content must remain external' }
+    cli_subcommand: change context
+    emits_events: [context_updated]
+
+  - name: change.converge
+    family: change
+    description: Deterministically verify task, spec, test, documentation, review, and context evidence before closure.
+    phase: '9'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [id, evidence]
+      additionalProperties: false
+      properties:
+        id: { type: string }
+        evidence:
+          type: array
+          minItems: 1
+          items:
+            type: object
+            required: [category, status, evidence]
+            additionalProperties: false
+            properties:
+              category: { type: string, enum: [diagnosis, diff, tests, spec, docs, review] }
+              status: { type: string, enum: [pass, fail, not_applicable] }
+              evidence: { type: string, minLength: 3 }
+    output_schema:
+      type: object
+      required: [ready, status, blockers]
+      additionalProperties: false
+      properties:
+        ready: { type: boolean }
+        status: { type: string, enum: [blocked, ready] }
+        blockers: { type: array, items: { type: string } }
+        verification_path: { type: string }
+    errors:
+      - { code: CHANGE_NOT_FOUND, description: 'change id does not exist' }
+      - { code: CHANGE_NOT_CONVERGEABLE, description: 'change lifecycle does not allow convergence' }
+    cli_subcommand: change converge
+    emits_events: [change_blocked, change_converged]
+
+  - name: change.archive
+    family: change
+    description: Archive a converged change after explicit baseline-spec reconciliation.
+    phase: '9'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [id, summary]
+      additionalProperties: false
+      properties:
+        id: { type: string }
+        summary: { type: string, minLength: 3 }
+        baseline_updates: { type: array, items: { type: string } }
+        no_baseline_change_reason: { type: string, minLength: 3 }
+    output_schema:
+      type: object
+      required: [change, archive_path]
+      additionalProperties: false
+      properties:
+        change: { type: object }
+        archive_path: { type: string }
+    errors:
+      - { code: CHANGE_NOT_READY, description: 'change has not passed convergence' }
+      - { code: BASELINE_RECONCILIATION_REQUIRED, description: 'baseline update or explicit no-change reason required' }
+      - { code: ARCHIVE_EXISTS, description: 'archive target already exists' }
+    cli_subcommand: change archive
+    emits_events: [change_archived]
+
+  # ────────────────────────── system family ──────────────────────────────
+  - name: system.doctor
+    family: system
+    description: Inspect Ultra runtime health and optionally perform backup-first recovery and projection repair.
+    phase: '9'
+    writer_role: mcp
+    input_schema:
+      type: object
+      additionalProperties: false
+      properties:
+        repair: { type: boolean, default: false }
+    output_schema:
+      type: object
+      required: [status, checks, repair_performed]
+      additionalProperties: true
+      properties:
+        status: { type: string, enum: [healthy, degraded] }
+        checks: { type: object }
+        repair_performed: { type: boolean }
+        backup_path: { type: string }
+        repair: { type: object }
+    errors:
+      - { code: BACKUP_FAILED, description: 'state database backup failed before repair' }
+      - { code: STATE_DB_ERROR, description: 'runtime state could not be inspected' }
+    cli_subcommand: system doctor
+    emits_events: []
+
   # ────────────────────────── plan family (D34) ───────────────────────────
   - name: plan.export
     family: plan

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

@@ -60,7 +60,7 @@
         },
         "family": {
           "type": "string",
-          "enum": ["task", "memory", "review", "impact", "skill", "session", "ask", "plan"]
+          "enum": ["task", "memory", "review", "impact", "skill", "session", "ask", "plan", "change", "system"]
         },
         "description": { "type": "string", "minLength": 10 },
         "phase": {

package/spec/schemas/state-db.sql

@@ -12,6 +12,28 @@
 --   PRAGMA busy_timeout=5000;       -- block up to 5s on lock (R25)
 --   PRAGMA foreign_keys=ON;         -- enforce FK constraints
 
+-- ──────────────────────────── changes ─────────────────────────────────────
+-- A project baseline is continuous; each feature, fix, incident, or redesign
+-- is an independently converged change unit. Only changes become terminal.
+CREATE TABLE IF NOT EXISTS changes (
+  id                TEXT PRIMARY KEY,
+  title             TEXT NOT NULL,
+  kind              TEXT NOT NULL CHECK (kind IN ('quick', 'standard', 'major', 'incident')),
+  status            TEXT NOT NULL DEFAULT 'active'
+                      CHECK (status IN ('active', 'blocked', 'ready', 'archived', 'cancelled')),
+  intent            TEXT NOT NULL,
+  docs_impact_json  TEXT NOT NULL DEFAULT '{"status":"unknown","files":[],"rationale":null}',
+  provider_refs_json TEXT NOT NULL DEFAULT '{}',
+  base_commit       TEXT,
+  artifact_root     TEXT NOT NULL,
+  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')),
+  closed_at         TEXT
+);
+
+CREATE INDEX IF NOT EXISTS changes_status ON changes(status, created_at);
+CREATE INDEX IF NOT EXISTS changes_kind   ON changes(kind, created_at);
+
 -- ──────────────────────────── tasks ───────────────────────────────────────
 -- Authoritative task row. tasks.json is generated from this table by the
 -- projector (Phase 2.6). Manual edits to tasks.json are overwritten.
@@ -33,6 +55,7 @@ CREATE TABLE IF NOT EXISTS tasks (
   trace_to          TEXT,                -- spec anchor reference
   context_file      TEXT,                -- projection target path
   completion_commit TEXT,                -- backfilled hash (Phase 2.8)
+  change_id         TEXT REFERENCES changes(id) ON DELETE SET NULL,
   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'))
@@ -43,6 +66,7 @@ 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;
+CREATE INDEX IF NOT EXISTS tasks_change      ON tasks(change_id) WHERE change_id IS NOT NULL;
 
 -- ──────────────────────────── events ──────────────────────────────────────
 -- Append-only event stream. id is the subscription cursor (D31, R26):
@@ -53,6 +77,7 @@ CREATE TABLE IF NOT EXISTS events (
   ts            TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
   type          TEXT    NOT NULL,
   task_id       TEXT,
+  change_id     TEXT,
   session_id    TEXT,
   runtime       TEXT CHECK (runtime IS NULL OR runtime IN ('claude', 'opencode', 'codex')),
   payload_json  TEXT
@@ -61,6 +86,7 @@ CREATE TABLE IF NOT EXISTS events (
 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);
+CREATE INDEX IF NOT EXISTS events_change  ON events(change_id, id);
 
 -- ──────────────────────────── sessions ────────────────────────────────────
 -- Authoritative session row. lease_expires_at + heartbeat_at live ONLY here
@@ -146,6 +172,95 @@ CREATE TABLE IF NOT EXISTS circuit_breaker (
 CREATE INDEX IF NOT EXISTS circuit_breaker_tripped ON circuit_breaker(tripped_at)
   WHERE tripped_at IS NOT NULL;
 
+-- ──────────────────────────── change artifacts ────────────────────────────
+CREATE TABLE IF NOT EXISTS artifacts (
+  id            TEXT PRIMARY KEY,
+  change_id     TEXT NOT NULL REFERENCES changes(id) ON DELETE CASCADE,
+  task_id       TEXT REFERENCES tasks(id) ON DELETE SET NULL,
+  kind          TEXT NOT NULL,
+  path          TEXT NOT NULL,
+  content_hash  TEXT,
+  metadata_json TEXT,
+  status        TEXT NOT NULL DEFAULT 'current' CHECK (status IN ('current', 'archived')),
+  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')),
+  UNIQUE(change_id, kind, path)
+);
+
+CREATE INDEX IF NOT EXISTS artifacts_change ON artifacts(change_id, kind);
+
+CREATE TABLE IF NOT EXISTS context_snapshots (
+  id                 TEXT PRIMARY KEY,
+  change_id          TEXT NOT NULL REFERENCES changes(id) ON DELETE CASCADE,
+  task_id            TEXT REFERENCES tasks(id) ON DELETE SET NULL,
+  git_head           TEXT,
+  provider_refs_json TEXT NOT NULL DEFAULT '{}',
+  manifest_path      TEXT NOT NULL,
+  manifest_hash      TEXT NOT NULL,
+  created_at         TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);
+
+CREATE INDEX IF NOT EXISTS context_snapshots_change ON context_snapshots(change_id, created_at);
+
+CREATE TABLE IF NOT EXISTS trace_links (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  change_id   TEXT NOT NULL REFERENCES changes(id) ON DELETE CASCADE,
+  task_id     TEXT REFERENCES tasks(id) ON DELETE SET NULL,
+  source_ref  TEXT NOT NULL,
+  target_ref  TEXT NOT NULL,
+  relation    TEXT NOT NULL,
+  created_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  UNIQUE(change_id, source_ref, target_ref, relation)
+);
+
+CREATE INDEX IF NOT EXISTS trace_links_change ON trace_links(change_id, task_id);
+
+-- ──────────────────────────── runtime reliability ─────────────────────────
+CREATE TABLE IF NOT EXISTS incidents (
+  id               TEXT PRIMARY KEY,
+  code             TEXT NOT NULL,
+  severity         TEXT NOT NULL CHECK (severity IN ('warning', 'error', 'critical')),
+  status           TEXT NOT NULL DEFAULT 'open' CHECK (status IN ('open', 'resolved')),
+  retryable        INTEGER NOT NULL DEFAULT 0 CHECK (retryable IN (0, 1)),
+  message          TEXT NOT NULL,
+  change_id        TEXT REFERENCES changes(id) ON DELETE SET NULL,
+  task_id          TEXT REFERENCES tasks(id) ON DELETE SET NULL,
+  session_id       TEXT REFERENCES sessions(sid) ON DELETE SET NULL,
+  source_kind      TEXT,
+  source_id        TEXT,
+  evidence_json    TEXT,
+  occurrence_count INTEGER NOT NULL DEFAULT 1,
+  first_seen_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  last_seen_at     TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  resolved_at      TEXT,
+  resolution       TEXT
+);
+
+CREATE INDEX IF NOT EXISTS incidents_open ON incidents(status, severity, last_seen_at);
+CREATE INDEX IF NOT EXISTS incidents_change ON incidents(change_id, status);
+
+CREATE TABLE IF NOT EXISTS projection_jobs (
+  id             INTEGER PRIMARY KEY AUTOINCREMENT,
+  tool_name      TEXT NOT NULL,
+  event_cursor   INTEGER NOT NULL DEFAULT 0,
+  status         TEXT NOT NULL DEFAULT 'pending'
+                   CHECK (status IN ('pending', 'running', 'completed', 'failed')),
+  attempts       INTEGER NOT NULL DEFAULT 0,
+  max_attempts   INTEGER NOT NULL DEFAULT 3 CHECK (max_attempts > 0),
+  last_error     TEXT,
+  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')),
+  completed_at   TEXT
+);
+
+CREATE INDEX IF NOT EXISTS projection_jobs_status ON projection_jobs(status, id);
+
+CREATE TABLE IF NOT EXISTS event_consumers (
+  name       TEXT PRIMARY KEY,
+  cursor     INTEGER NOT NULL DEFAULT 0 CHECK (cursor >= 0),
+  updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);
+
 -- ──────────────────────────── 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');
@@ -155,3 +270,5 @@ INSERT OR IGNORE INTO schema_version (version, description)
 VALUES ('8A.1', 'Phase 8A.1 — tasks.parent_id for task.expand parent→children');
 INSERT OR IGNORE INTO schema_version (version, description)
 VALUES ('8A.2', 'Phase 8A.2 — tasks.estimated_days preserved across MCP and v4.4 migration');
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES ('9.0', 'Continuous change units, context snapshots, trace links, incidents, projection outbox, and durable consumers');

package/ultra-tools/cli.cjs

@@ -35,6 +35,7 @@ USAGE:
 SUBCOMMANDS:
   task      init-project
   session   close | get | list | admission | heartbeat | subscribe | reap
+  system    doctor [--repair]
   status    [--cost] [--since <duration>] [--json]
   db        init | checkpoint | vacuum | integrity | backup (Phase 2)
   migrate   --from=4.4 --to=4.5 [--dry|--rollback]          (Phase 2)
@@ -65,6 +66,7 @@ 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');
+const systemCommand = require('./commands/system.cjs');
 
 // Phase 6.2 — CLI telemetry: best-effort, never blocks the subcommand.
 function emitCliTelemetry(sub, rest) {
@@ -93,6 +95,7 @@ const SUBCOMMANDS = {
   db: (args) => process.exit(dbCommand.dispatch(args)),
   migrate: (args) => process.exit(migrateCommand.dispatch(args)),
   'legacy-memory': (args) => process.exit(legacyMemoryCommand.dispatch(args)),
+  system: (args) => systemCommand.dispatch(args).then((code) => process.exit(code)),
 };
 
 function main(argv) {

package/ultra-tools/commands/system.cjs

@@ -0,0 +1,57 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { openStateDb, closeStateDb } = require('../../mcp-server/lib/state-db.cjs');
+const doctor = require('../../mcp-server/lib/doctor.cjs');
+
+const USAGE = `ultra-tools system doctor [--repair]\n`;
+
+function emit(envelope) {
+  process.stdout.write(`${JSON.stringify(envelope)}\n`);
+}
+
+async function dispatchDoctor(args) {
+  const unknown = args.filter((arg) => !['--repair', '-h', '--help'].includes(arg));
+  if (args.includes('-h') || args.includes('--help')) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (unknown.length > 0) {
+    emit({ ok: false, error: { code: 'VALIDATION_ERROR', message: `unknown system doctor flag: ${unknown[0]}` } });
+    return 1;
+  }
+  const rootDir = process.cwd();
+  const dbPath = path.join(rootDir, '.ultra', 'state.db');
+  if (!fs.existsSync(dbPath)) {
+    emit({ ok: false, error: { code: 'STATE_DB_MISSING', message: `.ultra/state.db not found under ${rootDir}` } });
+    return 2;
+  }
+  const db = openStateDb(dbPath);
+  try {
+    const data = await doctor.runDoctor(db, { rootDir, repair: args.includes('--repair') });
+    emit({ ok: true, data });
+    return data.status === 'healthy' ? 0 : 2;
+  } catch (error) {
+    emit({ ok: false, error: { code: error.code || 'STATE_DB_ERROR', message: error.message } });
+    return 2;
+  } finally {
+    closeStateDb(db);
+  }
+}
+
+async function dispatch(args) {
+  const [verb, ...rest] = args;
+  if (!verb || verb === '-h' || verb === '--help') {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (verb !== 'doctor') {
+    emit({ ok: false, error: { code: 'UNKNOWN_VERB', message: `unknown system verb: ${verb}` } });
+    return 1;
+  }
+  return dispatchDoctor(rest);
+}
+
+module.exports = { USAGE, dispatch, dispatchDoctor };