ultra-builder-pro-cli 0.12.1 → 0.14.0

package/mcp-server/lib/state-db.cjs

@@ -9,8 +9,20 @@ const REPO_ROOT = process.env.UBP_RUNTIME_ROOT
   ? path.resolve(process.env.UBP_RUNTIME_ROOT)
   : path.resolve(__dirname, '..', '..');
 const SCHEMA_FILE = path.join(REPO_ROOT, 'spec', 'schemas', 'state-db.sql');
-const EXPECTED_VERSION = '11.0';
+const EXPECTED_VERSION = '12.0';
 const KIMI_SCHEMA_VERSION = '9.1';
+const CONTEXT_SCHEMA_VERSION = '10.0';
+const BASELINE_SCHEMA_VERSION = '11.0';
+
+const MIGRATED_GAPS = Object.freeze([{
+  id: 'legacy-rebaseline-required',
+  category: 'baseline_blocker',
+  status: 'open',
+  blocking: true,
+  summary: 'Legacy Ultra state requires evidence-backed brownfield re-adoption.',
+  evidence_refs: [],
+  owner: null,
+}]);
 
 const REQUIRED_TABLES = Object.freeze([
   'baselines',
@@ -32,7 +44,7 @@ const REQUIRED_TABLES = Object.freeze([
   'event_consumers',
 ]);
 
-function applyBaselineUpgrade(db, fromVersion) {
+function applyBaselineUpgrade(db, { legacyState = false } = {}) {
   db.exec(`
     CREATE TABLE IF NOT EXISTS baselines (
       id                  TEXT PRIMARY KEY,
@@ -45,10 +57,18 @@ function applyBaselineUpgrade(db, fromVersion) {
       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,
@@ -58,15 +78,69 @@ function applyBaselineUpgrade(db, fromVersion) {
     );
     CREATE INDEX IF NOT EXISTS baselines_status ON baselines(status, updated_at);
   `);
-  if (fromVersion && fromVersion !== EXPECTED_VERSION) {
+  if (legacyState && db.prepare('SELECT COUNT(*) AS count FROM baselines').get().count === 0) {
     db.prepare(
       `INSERT OR IGNORE INTO baselines
-       (id, project_name, mode, status, approved_by, approval_note, converged_at)
-       VALUES ('migrated-baseline', 'Migrated Ultra project', 'migrated', 'ready',
-               'schema-migration', 'Legacy project preserved during schema 11.0 migration',
-               strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`,
-    ).run();
+       (id, project_name, mode, status, gaps_json, approval_note)
+       VALUES ('migrated-baseline', 'Migrated Ultra project', 'migrated', 'adopting', ?,
+               'Legacy project preserved; owner re-adoption is required')`,
+    ).run(JSON.stringify(MIGRATED_GAPS));
+  }
+}
+
+function addColumnIfMissing(db, table, columns, name, definition) {
+  if (!columns.has(name)) {
+    db.exec(`ALTER TABLE ${table} ADD COLUMN ${name} ${definition}`);
+    columns.add(name);
+    return true;
   }
+  return false;
+}
+
+function applyBaselineColumns(db) {
+  if (!tableNames(db).includes('baselines')) return false;
+  const columns = columnNames(db, 'baselines');
+  let changed = false;
+  changed = addColumnIfMissing(db, 'baselines', columns, 'repository_branch', 'TEXT') || changed;
+  changed = addColumnIfMissing(
+    db, 'baselines', columns, 'worktree_state',
+    "TEXT NOT NULL DEFAULT 'unavailable' CHECK (worktree_state IN ('clean', 'dirty', 'unavailable'))",
+  ) || changed;
+  changed = addColumnIfMissing(db, 'baselines', columns, 'worktree_digest', 'TEXT') || changed;
+  changed = addColumnIfMissing(
+    db, 'baselines', columns, 'worktree_files_json', "TEXT NOT NULL DEFAULT '[]'",
+  ) || changed;
+  changed = addColumnIfMissing(
+    db, 'baselines', columns, 'worktree_accepted',
+    'INTEGER NOT NULL DEFAULT 0 CHECK (worktree_accepted IN (0, 1))',
+  ) || changed;
+  changed = addColumnIfMissing(db, 'baselines', columns, 'gaps_json', "TEXT NOT NULL DEFAULT '[]'") || changed;
+  changed = addColumnIfMissing(
+    db, 'baselines', columns, 'classification_json', "TEXT NOT NULL DEFAULT '{}'",
+  ) || changed;
+  return changed;
+}
+
+function applyChangeColumns(db) {
+  if (!tableNames(db).includes('changes')) return false;
+  const columns = columnNames(db, 'changes');
+  return addColumnIfMissing(db, 'changes', columns, 'baseline_bypass_json', 'TEXT');
+}
+
+function quoteSqlString(value) {
+  return `'${String(value).replaceAll("'", "''")}'`;
+}
+
+function migrationBackup(db, dbPath, fromVersion, existingTables) {
+  if (existingTables.size === 0 || fromVersion === EXPECTED_VERSION) return null;
+  const parent = path.dirname(dbPath);
+  const backupDir = path.basename(parent) === '.ultra' ? path.join(parent, 'backups') : path.join(parent, 'backups');
+  fs.mkdirSync(backupDir, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const version = String(fromVersion || 'unknown').replace(/[^a-zA-Z0-9_.-]/g, '_');
+  const backupPath = path.join(backupDir, `state-pre-${version}-to-${EXPECTED_VERSION}-${stamp}.db`);
+  db.exec(`VACUUM INTO ${quoteSqlString(backupPath)}`);
+  return backupPath;
 }
 
 function readSchemaSql() {
@@ -256,7 +330,7 @@ function upgradeRuntimeConstraints(db, fromVersion = latestSchemaVersion(db)) {
   return true;
 }
 
-function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db)) {
+function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { legacyState = false } = {}) {
   const runtimeChanged = upgradeRuntimeConstraints(db, fromVersion);
   db.transaction(() => {
     applyCompatibleColumns(db);
@@ -265,7 +339,8 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db)) {
       "SELECT 1 FROM migration_history WHERE to_version = '10.0' AND status = 'success' LIMIT 1",
     ).get();
     const needsContextMigration = Boolean(
-      fromVersion && !['10.0', EXPECTED_VERSION].includes(fromVersion) && !contextMigration,
+      fromVersion && ![CONTEXT_SCHEMA_VERSION, BASELINE_SCHEMA_VERSION, EXPECTED_VERSION].includes(fromVersion)
+        && !contextMigration,
     );
     if (contextChanged || needsContextMigration) {
       db.prepare(
@@ -274,30 +349,63 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db)) {
          VALUES (?, ?, 'forward', 'success', ?)`,
       ).run(
         runtimeChanged ? KIMI_SCHEMA_VERSION : (fromVersion || 'unknown'),
-        '10.0',
+        CONTEXT_SCHEMA_VERSION,
         'Add Context Spine role/gate readiness, execution contracts, breadcrumbs, and specification learning',
       );
     }
-    applyBaselineUpgrade(db, fromVersion);
+    applyBaselineUpgrade(db, { legacyState });
+    applyBaselineColumns(db);
+    applyChangeColumns(db);
     const baselineMigration = db.prepare(
       "SELECT 1 FROM migration_history WHERE to_version = '11.0' AND status = 'success' LIMIT 1",
     ).get();
-    if (fromVersion && fromVersion !== EXPECTED_VERSION && !baselineMigration) {
+    if (fromVersion && ![BASELINE_SCHEMA_VERSION, EXPECTED_VERSION].includes(fromVersion)
+      && !baselineMigration) {
       db.prepare(
         `INSERT INTO migration_history
           (from_version, to_version, direction, status, notes)
          VALUES (?, ?, 'forward', 'success', ?)`,
       ).run(
-        fromVersion === '10.0' ? fromVersion : '10.0',
-        EXPECTED_VERSION,
+        fromVersion === CONTEXT_SCHEMA_VERSION ? fromVersion : CONTEXT_SCHEMA_VERSION,
+        BASELINE_SCHEMA_VERSION,
         'Add authoritative greenfield and brownfield baseline adoption, evidence, convergence, and drift state',
       );
     }
+    if (legacyState) {
+      db.prepare(
+        `UPDATE baselines SET status = 'adopting', approved_by = NULL, approval_note = ?,
+         converged_at = NULL, worktree_state = 'unavailable', worktree_digest = NULL,
+         worktree_files_json = '[]', worktree_accepted = 0,
+         gaps_json = CASE WHEN gaps_json IS NULL OR gaps_json = '[]' THEN ? ELSE gaps_json END,
+         updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+         WHERE mode = 'migrated' AND status != 'superseded'`,
+      ).run(
+        'Legacy project preserved; owner re-adoption is required',
+        JSON.stringify(MIGRATED_GAPS),
+      );
+      const adoptionMigration = db.prepare(
+        "SELECT 1 FROM migration_history WHERE to_version = '12.0' AND status = 'success' LIMIT 1",
+      ).get();
+      if (!adoptionMigration) {
+        db.prepare(
+          `INSERT INTO migration_history
+            (from_version, to_version, direction, status, notes)
+           VALUES (?, ?, 'forward', 'success', ?)`,
+        ).run(
+          BASELINE_SCHEMA_VERSION,
+          EXPECTED_VERSION,
+          'Add repository snapshots, authoritative gap ledger, incident governance, and required re-adoption',
+        );
+      }
+    }
     db.exec('CREATE INDEX IF NOT EXISTS tasks_change ON tasks(change_id) WHERE change_id IS NOT NULL');
     db.exec('CREATE INDEX IF NOT EXISTS events_change ON events(change_id, id)');
     db.prepare(
       'INSERT OR IGNORE INTO schema_version (version, description) VALUES (?, ?)',
-    ).run(EXPECTED_VERSION, 'Greenfield and brownfield baseline adoption, convergence, and drift authority');
+    ).run(
+      EXPECTED_VERSION,
+      'Evidence-backed repository snapshots, gap ledger, safe re-adoption, and incident break-glass governance',
+    );
   })();
 }
 
@@ -317,23 +425,36 @@ function ensureSchemaVersion(db) {
 }
 
 function initStateDb(dbPath) {
-  const db = openStateDb(dbPath);
-  const existing = new Set(tableNames(db));
-  const fromVersion = latestSchemaVersion(db);
-  applyCompatibleColumns(db);
-  const missing = REQUIRED_TABLES.filter((t) => !existing.has(t));
-  if (missing.length > 0) {
-    applySchema(db);
+  let db;
+  let backupPath = null;
+  try {
+    db = openStateDb(dbPath);
+    const existing = new Set(tableNames(db));
+    const fromVersion = latestSchemaVersion(db);
+    const legacyState = existing.size > 0 && fromVersion !== EXPECTED_VERSION;
+    backupPath = migrationBackup(db, dbPath, fromVersion, existing);
+    applyCompatibleColumns(db);
+    const missing = REQUIRED_TABLES.filter((t) => !existing.has(t));
+    if (missing.length > 0) {
+      applySchema(db);
+    }
+    applyCompatibleUpgrades(db, fromVersion, { legacyState });
+    const version = ensureSchemaVersion(db);
+    return {
+      db,
+      path: dbPath,
+      schema_version: version,
+      created: missing.length > 0,
+      backup_path: backupPath,
+      tables: tableNames(db).sort(),
+    };
+  } catch (error) {
+    if (backupPath && error && typeof error === 'object') {
+      error.migration_backup_path = backupPath;
+    }
+    closeStateDb(db);
+    throw error;
   }
-  applyCompatibleUpgrades(db, fromVersion);
-  const version = ensureSchemaVersion(db);
-  return {
-    db,
-    path: dbPath,
-    schema_version: version,
-    created: missing.length > 0,
-    tables: tableNames(db).sort(),
-  };
 }
 
 function closeStateDb(db) {
@@ -355,4 +476,5 @@ module.exports = {
   closeStateDb,
   tableNames,
   runScript,
+  MIGRATED_GAPS,
 };

package/mcp-server/lib/state-db.test.cjs

@@ -82,6 +82,135 @@ test('openStateDb on an empty file produces no tables until schema is applied',
   }
 });
 
+test('initStateDb upgrades an exact schema 11 project without replacing its approved baseline', () => {
+  const { dir, file } = tmpDbPath('ubp-schema-11-upgrade');
+  try {
+    const legacy = openStateDb(file);
+    legacy.exec(`
+      CREATE TABLE schema_version (
+        version TEXT PRIMARY KEY,
+        applied_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+        description TEXT
+      );
+      CREATE TABLE 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 TABLE baselines (
+        id TEXT PRIMARY KEY,
+        project_name TEXT NOT NULL,
+        project_type TEXT,
+        stack TEXT,
+        mode TEXT NOT NULL CHECK (mode IN ('greenfield', 'brownfield', 'migrated')),
+        status TEXT NOT NULL CHECK (status IN ('draft', 'adopting', 'blocked', 'ready', 'superseded')),
+        repository_root TEXT NOT NULL DEFAULT '.',
+        scope_json TEXT NOT NULL DEFAULT '["."]',
+        repository_revision TEXT,
+        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 '[]',
+        provider_refs_json TEXT NOT NULL DEFAULT '{}',
+        approved_by TEXT,
+        approval_note TEXT,
+        started_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+        converged_at TEXT,
+        updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+      );
+      CREATE TABLE 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 '{}',
+        provider_refs_json TEXT NOT NULL DEFAULT '{}',
+        base_commit TEXT,
+        artifact_root 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')),
+        closed_at TEXT
+      );
+      INSERT INTO schema_version (version, description) VALUES ('11.0', 'baseline authority');
+      INSERT INTO baselines
+        (id, project_name, mode, status, approved_by, approval_note, converged_at)
+      VALUES
+        ('approved-baseline', 'legacy-project', 'brownfield', 'ready', 'owner', 'approved',
+         '2026-07-01T00:00:00.000Z');
+    `);
+    closeStateDb(legacy);
+
+    let upgraded;
+    try {
+      upgraded = initStateDb(file);
+    } catch (error) {
+      assert.fail(`schema 11 upgrade failed: ${error.message}\n${error.stack || ''}`);
+    }
+    try {
+      assert.equal(upgraded.schema_version, '12.0');
+      assert.ok(fs.existsSync(upgraded.backup_path));
+      const baseline = upgraded.db.prepare(
+        'SELECT id, mode, status, worktree_state, gaps_json FROM baselines',
+      ).get();
+      assert.deepEqual(baseline, {
+        id: 'approved-baseline', mode: 'brownfield', status: 'ready',
+        worktree_state: 'unavailable', gaps_json: '[]',
+      });
+      assert.equal(
+        upgraded.db.prepare("SELECT COUNT(*) AS count FROM baselines WHERE mode = 'migrated'").get().count,
+        0,
+      );
+      const changeColumns = upgraded.db.prepare('PRAGMA table_info(changes)').all().map((row) => row.name);
+      assert.ok(changeColumns.includes('baseline_bypass_json'));
+    } finally { closeStateDb(upgraded.db); }
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('initStateDb exposes its pre-migration backup when an incompatible legacy schema fails', () => {
+  const { dir, file } = tmpDbPath('ubp-schema-upgrade-failure');
+  try {
+    const legacy = openStateDb(file);
+    legacy.exec(`
+      CREATE TABLE schema_version (
+        version TEXT PRIMARY KEY,
+        applied_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+        description TEXT
+      );
+      CREATE TABLE migration_history (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        from_version TEXT NOT NULL,
+        to_version TEXT NOT NULL,
+        direction TEXT NOT NULL,
+        applied_at TEXT NOT NULL,
+        status TEXT NOT NULL,
+        notes TEXT
+      );
+      INSERT INTO schema_version (version, description) VALUES ('11.0', 'incompatible fixture');
+    `);
+    closeStateDb(legacy);
+
+    let failure;
+    try {
+      initStateDb(file);
+    } catch (error) {
+      failure = error;
+    }
+    assert.ok(failure, 'the incompatible migration_history table must fail schema application');
+    assert.match(failure.message, /no such column: ts/);
+    assert.ok(failure.migration_backup_path, 'failure must retain the backup location for recovery');
+    assert.ok(fs.existsSync(failure.migration_backup_path));
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test('Phase 8A.1 schema: tasks.parent_id column + tasks_parent partial index + seed row', () => {
   const { dir, file } = tmpDbPath();
   try {
@@ -123,7 +252,7 @@ test('initStateDb migrates existing runtime constraints to Kimi without losing r
     const legacy = openStateDb(file);
     const legacySchema = fs.readFileSync(SCHEMA_FILE, 'utf8').replaceAll(", 'kimi'", '');
     legacy.exec(legacySchema);
-    legacy.prepare("DELETE FROM schema_version WHERE version IN ('9.1', '10.0', '11.0')").run();
+    legacy.prepare("DELETE FROM schema_version WHERE version IN ('9.1', '10.0', '11.0', '12.0')").run();
     legacy.prepare(
       "INSERT INTO tasks (id, title, type, priority) VALUES ('task-old', 'Old', 'feature', 'P1')",
     ).run();
@@ -146,20 +275,23 @@ test('initStateDb migrates existing runtime constraints to Kimi without losing r
     closeStateDb(legacy);
 
     const upgraded = initStateDb(file);
-    assert.equal(upgraded.schema_version, '11.0');
+    assert.equal(upgraded.schema_version, '12.0');
+    assert.ok(upgraded.backup_path);
+    assert.ok(fs.existsSync(upgraded.backup_path));
     assert.equal(upgraded.db.prepare("SELECT runtime FROM sessions WHERE sid = 'session-old'").get().runtime, 'codex');
     assert.equal(upgraded.db.prepare("SELECT COUNT(*) AS n FROM telemetry WHERE session_id = 'session-old'").get().n, 1);
     assert.equal(upgraded.db.prepare("SELECT COUNT(*) AS n FROM incidents WHERE session_id = 'session-old'").get().n, 1);
     assert.deepEqual(upgraded.db.pragma('foreign_key_check'), []);
     const migrations = upgraded.db.prepare(
-      "SELECT to_version, notes FROM migration_history WHERE to_version IN ('9.1', '10.0', '11.0') ORDER BY id",
+      "SELECT to_version, notes FROM migration_history WHERE to_version IN ('9.1', '10.0', '11.0', '12.0') ORDER BY id",
     ).all();
     assert.ok(migrations.some((row) => row.to_version === '9.1' && /Kimi/.test(row.notes)));
     assert.ok(migrations.some((row) => row.to_version === '10.0' && /Context Spine/.test(row.notes)));
     assert.ok(migrations.some((row) => row.to_version === '11.0' && /baseline adoption/i.test(row.notes)));
+    assert.ok(migrations.some((row) => row.to_version === '12.0' && /gap ledger|re-adoption/i.test(row.notes)));
     assert.deepEqual(
       upgraded.db.prepare("SELECT mode, status FROM baselines WHERE id = 'migrated-baseline'").get(),
-      { mode: 'migrated', status: 'ready' },
+      { mode: 'migrated', status: 'adopting' },
     );
 
     upgraded.db.prepare(

package/mcp-server/lib/state-ops.cjs

@@ -128,6 +128,60 @@ function listTasks(db, filter = {}) {
   }).map(rowToTask);
 }
 
+function assertChangeAcceptsTasks(db, changeId) {
+  if (changeId === null || changeId === undefined) return null;
+  const change = db.prepare('SELECT id, status FROM changes WHERE id = ?').get(changeId);
+  if (!change) throw new StateOpsError('CHANGE_NOT_FOUND', `change ${changeId} does not exist`);
+  if (!['active', 'blocked'].includes(change.status)) {
+    throw new StateOpsError('CHANGE_NOT_MUTABLE', `change ${changeId} is ${change.status}`);
+  }
+  return change;
+}
+
+function resolveTaskCreationChangeId(db, input = {}) {
+  const explicitlyAssigned = input.change_id !== undefined;
+  const requestedChangeId = explicitlyAssigned ? input.change_id : null;
+  if (!input.parent_id) {
+    assertChangeAcceptsTasks(db, requestedChangeId);
+    return requestedChangeId;
+  }
+  const parent = readTask(db, input.parent_id);
+  if (!parent) {
+    throw new StateOpsError('TASK_NOT_FOUND', `parent task ${input.parent_id} does not exist`);
+  }
+  if (explicitlyAssigned && requestedChangeId !== parent.change_id) {
+    throw new StateOpsError(
+      'TASK_CHANGE_OWNERSHIP_MISMATCH',
+      `child task change ${requestedChangeId || '(none)'} does not match parent ${parent.id} change ${parent.change_id || '(none)'}`,
+    );
+  }
+  assertChangeAcceptsTasks(db, parent.change_id);
+  return parent.change_id;
+}
+
+function assertTaskChangeAssignment(db, task, changeId) {
+  if (task.parent_id) {
+    const parent = readTask(db, task.parent_id);
+    if (!parent) throw new StateOpsError('TASK_NOT_FOUND', `parent task ${task.parent_id} does not exist`);
+    if (changeId !== parent.change_id) {
+      throw new StateOpsError(
+        'TASK_CHANGE_OWNERSHIP_MISMATCH',
+        `task ${task.id} must retain parent ${parent.id} change ${parent.change_id || '(none)'}`,
+      );
+    }
+  }
+  const mismatchedChild = db.prepare(
+    'SELECT id, change_id FROM tasks WHERE parent_id = ? AND change_id IS NOT ? LIMIT 1',
+  ).get(task.id, changeId);
+  if (mismatchedChild) {
+    throw new StateOpsError(
+      'TASK_CHANGE_OWNERSHIP_MISMATCH',
+      `task ${task.id} change must continue to match child ${mismatchedChild.id}`,
+    );
+  }
+  assertChangeAcceptsTasks(db, changeId);
+}
+
 function createTask(db, input) {
   if (!input || !input.id || !input.title || !input.type || !input.priority) {
     throw new StateOpsError('VALIDATION_ERROR', 'id, title, type, priority required');
@@ -160,9 +214,7 @@ function createTask(db, input) {
     updated_at: ts,
   };
   return tx(db, () => {
-    if (row.change_id && !db.prepare('SELECT id FROM changes WHERE id = ?').get(row.change_id)) {
-      throw new StateOpsError('CHANGE_NOT_FOUND', `change ${row.change_id} does not exist`);
-    }
+    row.change_id = resolveTaskCreationChangeId(db, input);
     try {
       db.prepare(
         `INSERT INTO tasks (${TASK_FIELDS.join(', ')})
@@ -188,6 +240,10 @@ function patchTask(db, id, patch = {}) {
   return tx(db, () => {
     const current = readTask(db, id);
     if (!current) throw new StateOpsError('TASK_NOT_FOUND', `no task ${id}`);
+    // A task owned by a change remains writable only while that change is an
+    // active execution authority. Ownership is durable once assigned: it may
+    // not be detached or moved to another change by a generic task patch.
+    assertChangeAcceptsTasks(db, current.change_id);
     const sets = [];
     const params = [];
     let nextStatus = null;
@@ -200,9 +256,14 @@ function patchTask(db, id, patch = {}) {
         throw new StateOpsError('VALIDATION_ERROR', `field ${key} is not patchable`);
       }
       let value = patch[key];
-      if (key === 'change_id' && value !== null
-        && !db.prepare('SELECT id FROM changes WHERE id = ?').get(value)) {
-        throw new StateOpsError('CHANGE_NOT_FOUND', `change ${value} does not exist`);
+      if (key === 'change_id') {
+        if (current.change_id !== null && value !== current.change_id) {
+          throw new StateOpsError(
+            'TASK_CHANGE_OWNERSHIP_MISMATCH',
+            `task ${current.id} already belongs to change ${current.change_id}`,
+          );
+        }
+        assertTaskChangeAssignment(db, current, value);
       }
       if (key === 'deps' || key === 'files_modified') {
         if (value !== null && !Array.isArray(value)) {
@@ -711,6 +772,7 @@ module.exports = {
   // tasks
   readTask,
   listTasks,
+  resolveTaskCreationChangeId,
   createTask,
   patchTask,
   updateTaskStatus,

package/mcp-server/lib/task-expander.cjs

@@ -1,20 +1,11 @@
 'use strict';
 
-// Phase 8A.3 — Expand a complex task into subtasks via injected llmClient.
-//
-// expandTask(db, { id, sub_count, strategy, llmClient }) reads the parent,
-// asks the LLM for children, and persists them atomically (children rows
-// with parent_id set, parent status → 'expanded'). The status transition
-// automatically emits task_expanded via state-ops' status→event map.
-// Strategy 'manual' is reserved for future CLI interactive flows.
+// Persist host-derived child tasks atomically. Model judgment stays with the
+// current host; this module validates ownership and the database contract.
 
 const Ajv = require('ajv/dist/2020');
 const ops = require('./state-ops.cjs');
-const {
-  buildExpandSystemPrompt,
-  buildExpandUserPrompt,
-} = require('../../orchestrator/planner/expand-prompt.cjs');
-
+const changes = require('./change-workflow.cjs');
 const CHILDREN_SHAPE = Object.freeze({
   type: 'object',
   required: ['children'],
@@ -51,7 +42,9 @@ class TaskExpandError extends Error {
   }
 }
 
-async function expandTask(db, { id, sub_count, strategy = 'llm', llmClient } = {}) {
+function expandTask(db, {
+  id, children, rootDir = process.cwd(),
+} = {}) {
   if (!id) throw new TaskExpandError('VALIDATION_ERROR', 'id required');
 
   const parent = ops.readTask(db, id);
@@ -59,34 +52,16 @@ async function expandTask(db, { id, sub_count, strategy = 'llm', llmClient } = {
   if (parent.status === 'expanded') {
     throw new TaskExpandError('ALREADY_EXPANDED', `task ${id} is already expanded`);
   }
-  if (strategy === 'manual') {
-    throw new TaskExpandError('NOT_IMPLEMENTED', 'strategy "manual" not implemented; use "llm"');
-  }
-  if (strategy !== 'llm') {
-    throw new TaskExpandError('VALIDATION_ERROR', `unknown strategy "${strategy}"`);
-  }
-  if (!llmClient || typeof llmClient.completeJson !== 'function') {
-    throw new TaskExpandError('NO_LLM_CLIENT', 'llmClient.completeJson is required');
-  }
-
-  const system = buildExpandSystemPrompt({ sub_count });
-  const user = buildExpandUserPrompt(parent);
-
-  let reply;
-  try {
-    reply = await llmClient.completeJson({ system, user });
-  } catch (err) {
-    throw new TaskExpandError('LLM_CALL_FAILED', `LLM call failed: ${err.message}`, err);
-  }
-  if (!validateChildren(reply.json)) {
+  changes.assertTaskCreationAllowed(db, { change_id: parent.change_id }, { rootDir });
+  if (!validateChildren({ children })) {
     throw new TaskExpandError(
       'INVALID_OUTPUT',
-      `LLM output failed schema: ${ajv.errorsText(validateChildren.errors)}`,
+      `child task graph failed schema: ${ajv.errorsText(validateChildren.errors)}`,
     );
   }
 
   const seen = new Set();
-  const children = reply.json.children.map((c) => {
+  const normalized = children.map((c) => {
     if (seen.has(c.id)) {
       throw new TaskExpandError('INVALID_OUTPUT', `duplicate child id "${c.id}"`);
     }
@@ -101,17 +76,19 @@ async function expandTask(db, { id, sub_count, strategy = 'llm', llmClient } = {
       files_modified: Array.isArray(c.files_modified) ? c.files_modified : [],
       parent_id: parent.id,
       tag: parent.tag,
+      change_id: parent.change_id,
     };
   });
 
   return ops.tx(db, () => {
-    for (const child of children) {
+    changes.assertTaskCreationAllowed(db, { change_id: parent.change_id }, { rootDir });
+    for (const child of normalized) {
       ops.createTask(db, child);
     }
     ops.patchTask(db, parent.id, { status: 'expanded' });
     return {
       parent_id: parent.id,
-      children,
+      children: normalized,
     };
   });
 }