ultra-builder-pro-cli 0.12.1 → 0.14.0

package/spec/mcp-tools.yaml

@@ -3,11 +3,11 @@
 # Validated by spec/schemas/mcp-tools.schema.json (run `npm run test:spec`).
 # Trace: PLAN §7.3, decisions D12 / D29 / D31-D34.
 
-version: '1.1'
+version: '1.2'
 
 info:
   title: Ultra Builder Pro MCP tool contracts
-  phase: '1.1'
+  phase: '1.2'
   trace_to: 'PLAN docs/PLAN.zh-CN.md §7.3'
   notes: |
     This published contract contains only tools registered by the MCP server.
@@ -32,7 +32,7 @@ tools:
   # ─────────────────────────── task family ────────────────────────────────
   - name: task.create
     family: task
-    description: Create a new task in state.db. Emits task_created event. If `id` is omitted the server mints a uuid.
+    description: Create a new task in state.db. Emits task_created event. If `id` is omitted the server mints a uuid. Child tasks inherit the parent's change ownership; conflicting ownership is rejected.
     phase: '2'
     writer_role: mcp
     input_schema:
@@ -48,10 +48,10 @@ tools:
         estimated_days: { type: number, exclusiveMinimum: 0, description: 'estimated implementation effort in days' }
         deps:           { type: array, items: { type: string } }
         files_modified: { type: array, items: { type: string }, description: 'Phase 8A conflict detection' }
-        parent_id:      { type: string, description: 'Phase 8A.3 parent reference for task.expand children' }
+        parent_id:      { type: string, description: 'Phase 8A.3 parent reference; the child inherits this task change ownership' }
         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' }
+        change_id:      { type: string, pattern: '^[a-zA-Z0-9_\-]+$', description: 'active or blocked continuous change unit owning this task; inherited from parent_id when omitted' }
     output_schema:
       type: object
       required: [id, status, created_at]
@@ -63,6 +63,11 @@ tools:
     errors:
       - { code: VALIDATION_ERROR, description: 'input failed schema validation' }
       - { code: DUPLICATE_TASK_ID, description: 'task id already exists' }
+      - { code: TASK_NOT_FOUND, description: 'parent task does not exist' }
+      - { code: CHANGE_NOT_FOUND, description: 'assigned change does not exist' }
+      - { code: CHANGE_NOT_MUTABLE, description: 'assigned change no longer accepts tasks' }
+      - { code: TASK_CHANGE_OWNERSHIP_MISMATCH, description: 'child ownership conflicts with its parent change' }
+      - { code: BASELINE_NOT_READY, description: 'ordinary task creation requires a ready baseline or an already-authorized active change' }
       - { code: LEGACY_STATE_MIGRATION_REQUIRED, description: 'non-empty v4.4 projection must be migrated before state-backed tools can run' }
       - { code: STATE_DB_LOCKED, description: 'database is locked', retriable: true }
     cli_subcommand: task create
@@ -106,6 +111,9 @@ tools:
       - { code: TASK_NOT_FOUND, description: 'no task with given id' }
       - { code: ILLEGAL_STATUS_TRANSITION, description: 'transition rejected by state machine' }
       - { code: VALIDATION_ERROR, description: 'patch failed schema validation' }
+      - { code: CHANGE_NOT_FOUND, description: 'assigned change does not exist' }
+      - { code: CHANGE_NOT_MUTABLE, description: 'assigned change no longer accepts task updates' }
+      - { code: TASK_CHANGE_OWNERSHIP_MISMATCH, description: 'task ownership conflicts with its parent or children' }
       - { code: LEGACY_STATE_MIGRATION_REQUIRED, description: 'non-empty v4.4 projection must be migrated before state-backed tools can run' }
     cli_subcommand: task update
     emits_events: [task_started, task_completed, task_blocked, task_stale_marked]
@@ -246,6 +254,17 @@ tools:
           enum: [auto, greenfield, brownfield]
           default: auto
           description: auto detects whether meaningful project content already exists
+        resume:
+          type: boolean
+          default: false
+          description: preserve an existing `.ultra/`, upgrade its schema, and install only missing current scaffold files
+        scope:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items: { type: string, minLength: 1 }
+          default: ['.']
+          description: project-relative repository roots governed by the initial baseline
         overwrite:
           type: boolean
           default: false
@@ -255,7 +274,7 @@ tools:
           description: override path to the template root (defaults to bundled templates/.ultra/)
     output_schema:
       type: object
-      required: [created_path, state_db_path, status, mode, baseline, copied_files]
+      required: [created_path, state_db_path, status, mode, baseline, copied_files, repository_profile]
       additionalProperties: false
       properties:
         created_path:
@@ -266,43 +285,66 @@ tools:
           description: absolute path to the initialized authoritative SQLite database
         status:
           type: string
-          enum: [created, overwritten]
+          enum: [created, overwritten, resumed]
         mode:
           type: string
           enum: [greenfield, brownfield]
         baseline:
           type: object
-          required: [id, mode, status]
+          required: [id, mode, status, scope]
           additionalProperties: true
         copied_files:
           type: array
           items: { type: string }
           description: paths relative to created_path
+        repository_profile:
+          type: object
+          description: bounded classification evidence used to route greenfield or brownfield adoption
         backup_path:
           type: string
           description: set only when status=overwritten
+        migration_backup_path:
+          type: string
+          description: pre-migration database backup created while resuming an older schema
     errors:
       - { code: ULTRA_DIR_EXISTS,  description: '.ultra/ already exists and overwrite=false' }
       - { code: TEMPLATE_MISSING,  description: 'source_template path does not exist' }
       - { code: TARGET_NOT_DIR,    description: 'target_dir is not a directory' }
+      - { code: BASELINE_SCOPE_MISSING, description: 'a selected baseline scope does not exist' }
+      - { code: LEGACY_STATE_MIGRATION_REQUIRED, description: 'projection-only tasks must be imported before resume' }
+      - { code: STATE_AUTHORITY_CONFLICT, description: 'projection tasks and authoritative state cannot be reconciled automatically' }
+      - { code: STATE_PROJECTION_INVALID, description: 'the existing task projection is malformed' }
       - { code: IO_ERROR,          description: 'filesystem write failed', retriable: true }
     cli_subcommand: task init-project
-    emits_events: [project_initialized]
+    emits_events: [project_initialized, project_resumed]
     trace_to: 'PLAN §6 Phase 3.1'
 
   - name: task.expand
     family: task
-    description: Expand a parent task into N child sub-tasks (Phase 8A).
+    description: Validate and atomically persist child tasks derived by the current host from one parent task.
     phase: '8a'
     writer_role: mcp
     input_schema:
       type: object
-      required: [id]
+      required: [id, children]
       additionalProperties: false
       properties:
-        id:        { type: string }
-        sub_count: { type: integer, minimum: 1, maximum: 16 }
-        strategy:  { type: string, enum: [llm], default: llm }
+        id: { type: string }
+        children:
+          type: array
+          minItems: 1
+          items:
+            type: object
+            required: [id, title, type, priority]
+            additionalProperties: false
+            properties:
+              id: { type: string, pattern: '^[a-zA-Z0-9_\-]+$' }
+              title: { type: string, minLength: 3, maxLength: 200 }
+              type: { type: string, enum: [architecture, feature, bugfix] }
+              priority: { type: string, enum: [P0, P1, P2, P3] }
+              complexity: { type: integer, minimum: 1, maximum: 10 }
+              deps: { type: array, items: { type: string } }
+              files_modified: { type: array, items: { type: string } }
     output_schema:
       type: object
       required: [parent_id, children]
@@ -313,22 +355,41 @@ tools:
     errors:
       - { code: TASK_NOT_FOUND, description: 'parent id missing' }
       - { code: ALREADY_EXPANDED, description: 'task is already expanded' }
+      - { code: CHANGE_NOT_FOUND, description: 'the parent task change does not exist' }
+      - { code: CHANGE_NOT_MUTABLE, description: 'the parent task change no longer accepts children' }
+      - { code: BASELINE_NOT_READY, description: 'child creation requires a ready baseline or the parent task to belong to an already-authorized active change' }
+      - { code: INVALID_OUTPUT, description: 'the host-derived child task graph is invalid' }
     cli_subcommand: task expand
     emits_events: [task_expanded]
     trace_to: '§7.3, D34'
 
   - name: task.parse_prd
     family: task
-    description: Parse a PRD document into a task graph (Phase 8A). When dry_run=true the tasks are returned without writing to state.db (supports ultra-plan human gate workflow).
+    description: Validate a host-derived PRD task graph and optionally persist it after the Ultra planning approval gate.
     phase: '8a'
     writer_role: mcp
     input_schema:
       type: object
+      required: [tasks]
       additionalProperties: false
       properties:
-        prd_path: { type: string }
-        prd_text: { type: string }
+        tasks:
+          type: array
+          minItems: 1
+          items:
+            type: object
+            required: [id, title, type, priority]
+            additionalProperties: false
+            properties:
+              id: { type: string, pattern: '^[a-zA-Z0-9_\-]+$' }
+              title: { type: string, minLength: 3, maxLength: 200 }
+              type: { type: string, enum: [architecture, feature, bugfix] }
+              priority: { type: string, enum: [P0, P1, P2, P3] }
+              complexity: { type: integer, minimum: 1, maximum: 10 }
+              deps: { type: array, items: { type: string } }
+              files_modified: { type: array, items: { type: string } }
         tag:      { type: string }
+        change_id: { type: string, pattern: '^[a-zA-Z0-9_\-]+$', description: 'continuous change unit that will own every persisted parsed task' }
         dry_run:  { type: boolean, default: false, description: 'when true, do not persist to state.db — used by ultra-plan gate to preview before approve' }
     output_schema:
       type: object
@@ -338,8 +399,11 @@ tools:
         tasks: { type: array, items: { type: object } }
         topo:  { type: array, items: { type: array, items: { type: string } } }
     errors:
-      - { code: NO_INPUT, description: 'one of prd_path or prd_text required' }
-      - { code: PARSE_FAILED, description: 'PRD could not be parsed into tasks' }
+      - { code: PARSE_FAILED, description: 'the host-derived PRD task graph is invalid' }
+      - { code: CYCLE_DETECTED, description: 'the proposed task graph contains a dependency cycle' }
+      - { code: CHANGE_NOT_FOUND, description: 'assigned change does not exist' }
+      - { code: CHANGE_NOT_MUTABLE, description: 'assigned change no longer accepts tasks' }
+      - { code: BASELINE_NOT_READY, description: 'persisting parsed tasks requires a ready baseline or an already-authorized active change' }
     cli_subcommand: task parse-prd
     emits_events: [task_created]
     trace_to: '§7.3, D34'
@@ -652,6 +716,15 @@ tools:
       type: object
       required: [project_name, mode]
       additionalProperties: false
+      allOf:
+        - if:
+            required: [replace_ready]
+            properties: { replace_ready: { const: true } }
+          then: { required: [replacement_authorization] }
+        - if: { required: [replacement_authorization] }
+          then:
+            required: [replace_ready]
+            properties: { replace_ready: { const: true } }
       properties:
         id: { type: string, pattern: '^[a-zA-Z0-9_\-]+$', default: project-baseline }
         project_name: { type: string, minLength: 1 }
@@ -661,6 +734,15 @@ tools:
         scope: { type: array, minItems: 1, items: { type: string, minLength: 1 }, default: ['.'] }
         repository_revision: { type: string, minLength: 1 }
         replace_ready: { type: boolean, default: false }
+        replacement_authorization:
+          type: object
+          required: [approved_by, reason]
+          additionalProperties: false
+          properties:
+            approved_by: { type: string, minLength: 1 }
+            reason: { type: string, minLength: 3 }
+        replace_migrated: { type: boolean, default: false, description: explicitly supersede a compatibility-only migrated baseline and start evidence-backed adoption }
+        classification: { type: object, description: bounded repository classification evidence; content is limited to 32 KiB }
         provider_refs:
           type: object
           additionalProperties: false
@@ -696,6 +778,9 @@ tools:
     errors:
       - { code: BASELINE_EXISTS, description: 'a ready baseline requires explicit replacement' }
       - { code: BASELINE_IN_PROGRESS, description: 'another adoption is already active' }
+      - { code: BASELINE_REPLACEMENT_AUTHORIZATION_REQUIRED, description: 'ready-baseline replacement lacks durable owner approval and rationale' }
+      - { code: BASELINE_REPLACEMENT_INVALID, description: 'replacement flags do not match the current baseline lifecycle or authorization payload' }
+      - { code: BASELINE_SCOPE_MISSING, description: 'a selected baseline scope does not exist' }
       - { code: PROVIDER_CONTENT_FORBIDDEN, description: 'provider payload content must remain external' }
     cli_subcommand: baseline start
     emits_events: [baseline_started]
@@ -754,6 +839,22 @@ tools:
               summary: { type: string, minLength: 1 }
               blocking: { type: boolean }
               owner: { type: string, minLength: 1 }
+        gaps:
+          type: array
+          items:
+            type: object
+            required: [id, category, summary]
+            additionalProperties: false
+            properties:
+              id: { type: string, pattern: '^[a-zA-Z0-9_\-]+$' }
+              category: { type: string, enum: [baseline_blocker, documentation_drift, known_defect, technical_debt, unknown, future_change] }
+              status: { type: string, enum: [open, accepted, resolved, deferred], default: open }
+              blocking: { type: boolean, default: false }
+              summary: { type: string, minLength: 1 }
+              evidence_refs: { type: array, uniqueItems: true, items: { type: string, minLength: 1 }, default: [] }
+              owner: { type: ['string', 'null'], minLength: 1 }
+              resolution: { type: string, minLength: 1 }
+        classification: { type: object, description: bounded repository classification evidence; content is limited to 32 KiB }
         provider_refs:
           type: object
           additionalProperties: false
@@ -790,6 +891,7 @@ tools:
       - { code: BASELINE_NOT_FOUND, description: 'baseline id does not exist' }
       - { code: BASELINE_NOT_MUTABLE, description: 'ready and superseded baselines are immutable' }
       - { code: BASELINE_SPEC_MISSING, description: 'a declared specification file does not exist' }
+      - { code: BASELINE_SCOPE_MISSING, description: 'a selected baseline scope does not exist' }
       - { code: PROVIDER_CONTENT_FORBIDDEN, description: 'provider payload content must remain external' }
     cli_subcommand: baseline record
     emits_events: [baseline_recorded]
@@ -831,6 +933,7 @@ tools:
         approved_by: { type: string, minLength: 1 }
         approval_note: { type: string, minLength: 3 }
         accept_known_red: { type: boolean, default: false }
+        accept_dirty_worktree: { type: boolean, default: false, description: explicitly freeze the exact recorded dirty-worktree digest into the baseline }
     output_schema:
       type: object
       required: [ready, status, blockers, baseline]
@@ -843,6 +946,7 @@ tools:
     errors:
       - { code: BASELINE_NOT_FOUND, description: 'baseline id does not exist' }
       - { code: BASELINE_NOT_CONVERGEABLE, description: 'baseline lifecycle does not allow convergence' }
+      - { code: BASELINE_NOT_READY, description: 'baseline evidence, gaps, revision, branch, worktree, or verification still blocks convergence' }
     cli_subcommand: baseline converge
     emits_events: [baseline_blocked, baseline_converged]
 
@@ -862,6 +966,14 @@ tools:
         kind: { type: string, enum: [quick, standard, major, incident] }
         intent: { type: string, minLength: 3 }
         base_commit: { type: string, pattern: '^[0-9a-f]{7,40}$' }
+        baseline_bypass:
+          type: object
+          required: [reason, approved_by]
+          additionalProperties: false
+          properties:
+            reason: { type: string, minLength: 3 }
+            approved_by: { type: string, minLength: 1 }
+          description: incident-only break-glass approval when the project baseline is unhealthy
         docs_impact:
           type: object
           additionalProperties: false
@@ -907,6 +1019,8 @@ tools:
       - { 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' }
+      - { code: BASELINE_NOT_READY, description: 'ordinary work is blocked until the project baseline is healthy' }
+      - { code: BASELINE_BYPASS_REQUIRED, description: 'an incident on an unhealthy baseline requires explicit break-glass approval' }
     cli_subcommand: change create
     emits_events: [change_created, context_updated]
 

package/spec/schemas/state-db.sql

@@ -27,10 +27,18 @@ CREATE TABLE IF NOT EXISTS baselines (
   repository_root     TEXT NOT NULL DEFAULT '.',
   scope_json          TEXT NOT NULL DEFAULT '["."]',
   repository_revision TEXT,
+  repository_branch   TEXT,
+  worktree_state      TEXT NOT NULL DEFAULT 'unavailable'
+                        CHECK (worktree_state IN ('clean', 'dirty', 'unavailable')),
+  worktree_digest     TEXT,
+  worktree_files_json TEXT NOT NULL DEFAULT '[]',
+  worktree_accepted   INTEGER NOT NULL DEFAULT 0 CHECK (worktree_accepted IN (0, 1)),
   spec_refs_json      TEXT NOT NULL DEFAULT '[]',
   evidence_json       TEXT NOT NULL DEFAULT '[]',
   verification_json   TEXT NOT NULL DEFAULT '[]',
   unknowns_json       TEXT NOT NULL DEFAULT '[]',
+  gaps_json           TEXT NOT NULL DEFAULT '[]',
+  classification_json TEXT NOT NULL DEFAULT '{}',
   provider_refs_json  TEXT NOT NULL DEFAULT '{}',
   approved_by         TEXT,
   approval_note       TEXT,
@@ -53,6 +61,7 @@ CREATE TABLE IF NOT EXISTS changes (
   intent            TEXT NOT NULL,
   docs_impact_json  TEXT NOT NULL DEFAULT '{"status":"unknown","files":[],"rationale":null}',
   provider_refs_json TEXT NOT NULL DEFAULT '{}',
+  baseline_bypass_json TEXT,
   base_commit       TEXT,
   artifact_root     TEXT NOT NULL,
   created_at        TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
@@ -336,3 +345,5 @@ INSERT OR IGNORE INTO schema_version (version, description)
 VALUES ('10.0', 'Role-scoped context snapshots, deterministic breadcrumbs, and approval-gated specification learning');
 INSERT OR IGNORE INTO schema_version (version, description)
 VALUES ('11.0', 'Greenfield and brownfield baseline adoption, convergence, and drift authority');
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES ('12.0', 'Evidence-backed repository snapshots, gap ledger, safe re-adoption, and incident break-glass governance');

package/ultra-tools/cli.cjs

@@ -20,7 +20,7 @@ const path = require('node:path');
 
 const VERSION = (() => {
   try {
-    const pkg = require(path.join(__dirname, '..', 'package.json'));
+    const pkg = require('../package.json');
     return pkg.version;
   } catch (_err) {
     return '0.1.0';
@@ -35,10 +35,10 @@ USAGE:
 SUBCOMMANDS:
   task      init-project
   session   close | get | list | admission | heartbeat | subscribe | reap
-  system    doctor [--repair]
+  system    doctor [--repair] | restore | rebaseline
   status    [--cost] [--since <duration>] [--json]
   db        init | checkpoint | vacuum | integrity | backup (Phase 2)
-  migrate   --from=4.4 --to=4.5 [--dry|--rollback]          (Phase 2)
+  migrate   --from=<4.4|4.5> --to=<4.5|12.0> [--dry|--rollback]
   legacy-memory inspect | archive | prune --confirm DELETE_ULTRA_LEGACY_MEMORY
 
   --help / -h      show this message
@@ -68,7 +68,11 @@ 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.
+// Session commands run only against healthy authority and may emit best-effort
+// telemetry. Initialization, diagnosis, migration, and recovery commands must
+// never open state.db before their own evidence-preserving checks.
+const TELEMETRY_SUBCOMMANDS = new Set(['session']);
+
 function emitCliTelemetry(sub, rest) {
   try {
     const dbPath = path.resolve('.ultra', 'state.db');
@@ -112,7 +116,7 @@ function main(argv) {
   const [sub, ...rest] = args;
   const handler = SUBCOMMANDS[sub];
   if (!handler) fail(`unknown subcommand: ${sub}\n\n${USAGE}`);
-  emitCliTelemetry(sub, rest);
+  if (TELEMETRY_SUBCOMMANDS.has(sub)) emitCliTelemetry(sub, rest);
   handler(rest);
 }
 

package/ultra-tools/commands/migrate.cjs

@@ -3,12 +3,17 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-const { initStateDb, openStateDb, closeStateDb } = require('../../mcp-server/lib/state-db.cjs');
+const {
+  initStateDb, openStateDb, closeStateDb, MIGRATED_GAPS,
+} = require('../../mcp-server/lib/state-db.cjs');
 const ops = require('../../mcp-server/lib/state-ops.cjs');
 const projector = require('../../mcp-server/lib/projector.cjs');
 
-const SUPPORTED_FROM = '4.4';
-const SUPPORTED_TO = '4.5';
+const DEFAULT_FROM = '4.4';
+const SUPPORTED_TRANSITIONS = Object.freeze({
+  '4.4': '4.5',
+  '4.5': '12.0',
+});
 
 // Frozen SQL — values flow through parameter bindings.
 const RECORD_MIGRATION_SQL = "INSERT INTO migration_history (from_version, to_version, direction, status, notes) VALUES (@from, @to, @direction, @status, @notes)";
@@ -73,7 +78,7 @@ function copyDirSync(src, dst) {
     const s = path.join(src, entry.name);
     const d = path.join(dst, entry.name);
     if (entry.name === 'state.db' || entry.name === 'state.db-wal' || entry.name === 'state.db-shm') continue;
-    if (entry.name.startsWith('backup-v4.4-')) continue;
+    if (/^backup-v[^/]+-/.test(entry.name)) continue;
     if (entry.isDirectory()) copyDirSync(s, d);
     else fs.copyFileSync(s, d);
   }
@@ -148,15 +153,15 @@ function normalizeLegacyTask(task, tasksJson, contextHeaders, sourceDir) {
   };
 }
 
-function planForward(sourceDir) {
+function planForward(sourceDir, expectedFrom = DEFAULT_FROM) {
   const tasksPath = path.join(sourceDir, '.ultra', 'tasks', 'tasks.json');
   const tasksJson = readJsonOptional(tasksPath);
   if (!tasksJson || !Array.isArray(tasksJson.tasks)) {
     throw new Error(`migrate: tasks.json missing or malformed at ${tasksPath}`);
   }
   const version = String(tasksJson.version || tasksJson.schema_version || '');
-  if (version !== SUPPORTED_FROM) {
-    throw new Error(`migrate: expected v${SUPPORTED_FROM} tasks.json, found ${version || '(missing version)'}`);
+  if (version !== expectedFrom) {
+    throw new Error(`migrate: expected v${expectedFrom} tasks.json, found ${version || '(missing version)'}`);
   }
 
   const contextHeaders = {};
@@ -173,7 +178,7 @@ function planForward(sourceDir) {
         task_id: task.id,
         json_status: task.status,
         context_status: ctx.status,
-        resolution: 'tasks.json wins (v4.4 → v4.5 D21 rule)',
+        resolution: `tasks.json wins (v${expectedFrom} projection migration rule)`,
       });
     }
   }
@@ -190,6 +195,7 @@ function planForward(sourceDir) {
     events: eventList,
     contextHeaders,
     warnings,
+    projectName: tasksJson.project?.name || path.basename(sourceDir),
   };
 }
 
@@ -241,16 +247,17 @@ function recordMigration(db, { from, to, direction, status, notes }) {
   db.prepare(RECORD_MIGRATION_SQL).run({ from, to, direction, status, notes });
 }
 
-function ensureBackupName(sourceDir) {
+function ensureBackupName(sourceDir, fromVersion = DEFAULT_FROM) {
   const ts = new Date().toISOString().replace(/[:.]/g, '-');
-  return path.join(sourceDir, '.ultra', `backup-v4.4-${ts}`);
+  return path.join(sourceDir, '.ultra', `backup-v${fromVersion}-${ts}`);
 }
 
-function findLatestBackup(sourceDir) {
+function findLatestBackup(sourceDir, fromVersion = DEFAULT_FROM) {
   const ultra = path.join(sourceDir, '.ultra');
   if (!fs.existsSync(ultra)) return null;
+  const prefix = `backup-v${fromVersion}-`;
   const candidates = fs.readdirSync(ultra)
-    .filter((n) => n.startsWith('backup-v4.4-'))
+    .filter((n) => n.startsWith(prefix))
     .sort();
   return candidates.length === 0 ? null : path.join(ultra, candidates[candidates.length - 1]);
 }
@@ -258,9 +265,11 @@ function findLatestBackup(sourceDir) {
 function cmdForward(flags) {
   const sourceDir = path.resolve(flags.sourceDir || '.');
   const dbPath = path.resolve(flags.dbPath || path.join(sourceDir, '.ultra', 'state.db'));
+  const fromVersion = flags.from || DEFAULT_FROM;
+  const toVersion = flags.to || SUPPORTED_TRANSITIONS[fromVersion];
   let plan;
   try {
-    plan = planForward(sourceDir);
+    plan = planForward(sourceDir, fromVersion);
   } catch (err) {
     emit({ ok: false, error: { code: 'MIGRATE_FAILED', message: err.message, retriable: false } });
     return 2;
@@ -271,8 +280,8 @@ function cmdForward(flags) {
       ok: true,
       data: {
         mode: 'dry',
-        from: SUPPORTED_FROM,
-        to: SUPPORTED_TO,
+        from: fromVersion,
+        to: toVersion,
         source_dir: sourceDir,
         db_path: dbPath,
         tasks_to_insert: plan.tasks.length,
@@ -284,7 +293,7 @@ function cmdForward(flags) {
   }
 
   // Real run: backup the entire .ultra subtree first.
-  const backupDir = ensureBackupName(sourceDir);
+  const backupDir = ensureBackupName(sourceDir, fromVersion);
   const ultraSource = path.join(sourceDir, '.ultra');
   copyDirSync(ultraSource, backupDir);
 
@@ -297,9 +306,18 @@ function cmdForward(flags) {
         throw new Error(`migrate: refusing to merge into non-empty state.db (tasks=${existing})`);
       }
       const inserted = applyForward(db, plan);
+      db.prepare(
+        `INSERT INTO baselines
+         (id, project_name, mode, status, gaps_json, approval_note)
+         VALUES ('migrated-baseline', ?, 'migrated', 'adopting', ?, ?)`,
+      ).run(
+        plan.projectName,
+        JSON.stringify(MIGRATED_GAPS),
+        `Legacy v${fromVersion} projection imported; evidence-backed owner re-adoption is required`,
+      );
       recordMigration(db, {
-        from: SUPPORTED_FROM,
-        to: SUPPORTED_TO,
+        from: fromVersion,
+        to: toVersion,
         direction: 'forward',
         status: 'success',
         notes: `tasks=${inserted.taskInserted} events=${inserted.eventsInserted} warnings=${plan.warnings.length}`,
@@ -312,8 +330,8 @@ function cmdForward(flags) {
       ok: true,
       data: {
         mode: 'apply',
-        from: SUPPORTED_FROM,
-        to: SUPPORTED_TO,
+        from: fromVersion,
+        to: toVersion,
         source_dir: sourceDir,
         db_path: dbPath,
         backup_dir: backupDir,
@@ -328,8 +346,8 @@ function cmdForward(flags) {
     if (db) {
       try {
         recordMigration(db, {
-          from: SUPPORTED_FROM,
-          to: SUPPORTED_TO,
+          from: fromVersion,
+          to: toVersion,
           direction: 'forward',
           status: 'failed',
           notes: err.message,
@@ -346,9 +364,11 @@ function cmdForward(flags) {
 function cmdRollback(flags) {
   const sourceDir = path.resolve(flags.sourceDir || '.');
   const dbPath = path.resolve(flags.dbPath || path.join(sourceDir, '.ultra', 'state.db'));
-  const backupDir = findLatestBackup(sourceDir);
+  const fromVersion = flags.from || DEFAULT_FROM;
+  const toVersion = flags.to || SUPPORTED_TRANSITIONS[fromVersion];
+  const backupDir = findLatestBackup(sourceDir, fromVersion);
   if (!backupDir) {
-    emit({ ok: false, error: { code: 'NO_BACKUP', message: 'no backup-v4.4-* directory found' } });
+    emit({ ok: false, error: { code: 'NO_BACKUP', message: `no backup-v${fromVersion}-* directory found` } });
     return 2;
   }
 
@@ -358,8 +378,8 @@ function cmdRollback(flags) {
     if (fs.existsSync(dbPath)) {
       db = openStateDb(dbPath);
       recordMigration(db, {
-        from: SUPPORTED_TO,
-        to: SUPPORTED_FROM,
+        from: toVersion,
+        to: fromVersion,
         direction: 'rollback',
         status: 'success',
         notes: `restored from ${backupDir}`,
@@ -376,7 +396,7 @@ function cmdRollback(flags) {
     // Restore .ultra contents from backup, leaving the backup itself in place.
     const ultraDir = path.join(sourceDir, '.ultra');
     for (const entry of fs.readdirSync(ultraDir, { withFileTypes: true })) {
-      if (entry.name.startsWith('backup-v4.4-')) continue;
+      if (/^backup-v[^/]+-/.test(entry.name)) continue;
       const target = path.join(ultraDir, entry.name);
       fs.rmSync(target, { recursive: true, force: true });
     }
@@ -386,8 +406,8 @@ function cmdRollback(flags) {
       ok: true,
       data: {
         mode: 'rollback',
-        from: SUPPORTED_TO,
-        to: SUPPORTED_FROM,
+        from: toVersion,
+        to: fromVersion,
         backup_dir: backupDir,
         source_dir: sourceDir,
       },
@@ -406,29 +426,35 @@ function dispatch(args) {
     process.stdout.write(USAGE);
     return 0;
   }
-  if (flags.from && flags.from !== SUPPORTED_FROM) {
-    emit({ ok: false, error: { code: 'UNSUPPORTED_VERSION', message: `--from ${flags.from} unsupported (only ${SUPPORTED_FROM})` } });
+  const fromVersion = flags.from || DEFAULT_FROM;
+  const expectedTo = SUPPORTED_TRANSITIONS[fromVersion];
+  if (!expectedTo) {
+    emit({ ok: false, error: { code: 'UNSUPPORTED_VERSION', message: `--from ${fromVersion} unsupported (supported: ${Object.keys(SUPPORTED_TRANSITIONS).join(', ')})` } });
     return 1;
   }
-  if (flags.to && flags.to !== SUPPORTED_TO) {
-    emit({ ok: false, error: { code: 'UNSUPPORTED_VERSION', message: `--to ${flags.to} unsupported (only ${SUPPORTED_TO})` } });
+  if (flags.to && flags.to !== expectedTo) {
+    emit({ ok: false, error: { code: 'UNSUPPORTED_VERSION', message: `--to ${flags.to} unsupported for --from ${fromVersion} (expected ${expectedTo})` } });
     return 1;
   }
   return flags.rollback ? cmdRollback(flags) : cmdForward(flags);
 }
 
-const USAGE = `ultra-tools migrate --from=4.4 --to=4.5 [flags]
+const USAGE = `ultra-tools migrate --from=<version> --to=<version> [flags]
+
+Supported transitions:
+  4.4 -> 4.5   import the legacy task projection into authoritative state
+  4.5 -> 12.0  import a projection-only project into current authoritative state
 
 Flags:
   --source-dir <dir>   project root containing .ultra/ (default: .)
   --db-path <path>     state.db destination (default: <source-dir>/.ultra/state.db)
   --dry                print the migration plan without writing
-  --rollback           restore the most recent backup-v4.4-* and drop state.db
+  --rollback           restore the most recent matching backup-v<from>-* and drop state.db
 
 The forward flow: backup .ultra/ → init state.db → insert tasks from
 tasks.json → merge context md status (tasks.json wins on conflict, warnings
 recorded) → insert activity-log events → record migration_history.
-Rollback restores from the latest backup-v4.4-* directory and writes a
+Rollback restores from the latest matching backup-v<from>-* directory and writes a
 matching migration_history rollback row before dropping state.db.
 `;