ultra-builder-pro-cli 0.19.1 → 0.20.0

package/mcp-server/lib/decision-dialogue.cjs

@@ -120,6 +120,7 @@ function readDecisionThread(db, id) {
     items,
     started_at: row.started_at,
     updated_at: row.updated_at,
+    completed_at: row.completed_at,
     confirmed_at: row.confirmed_at,
   };
 }
@@ -384,6 +385,56 @@ function deferDecision(db, input = {}) {
   });
 }
 
+function completeDecisionThread(db, input = {}) {
+  const id = requiredText(input.id, 'id');
+  const summary = requiredText(input.summary, 'summary');
+  return ops.tx(db, () => {
+    const thread = readDecisionThread(db, id);
+    if (!thread) {
+      throw new DecisionDialogueError('DECISION_THREAD_NOT_FOUND', `decision thread ${id} not found`);
+    }
+    if (thread.status === 'checkpoint_ready') {
+      throw new DecisionDialogueError(
+        'DECISION_CHECKPOINT_PENDING', `confirm or revise checkpoint ${id} before completing the thread`,
+      );
+    }
+    if (thread.status !== 'active') {
+      throw new DecisionDialogueError(
+        'DECISION_THREAD_NOT_MUTABLE', `decision thread ${id} is ${thread.status}`,
+      );
+    }
+    const open = thread.items.find((item) => item.status === 'open');
+    const deferredBlocking = thread.items.filter((item) => item.blocking && item.status === 'deferred');
+    if (open || deferredBlocking.length > 0) {
+      const blockers = [
+        ...(open ? [`DECISION_AWAITING_OWNER:${open.id}`] : []),
+        ...deferredBlocking.map((item) => `DECISION_DEFERRED_BLOCKING:${item.id}`),
+      ];
+      throw new DecisionDialogueError(
+        'DECISION_ALIGNMENT_BLOCKING',
+        `decision thread ${id} still contains unresolved blocking state`,
+        { blockers },
+      );
+    }
+    const ts = nowIso();
+    db.prepare(
+      `UPDATE decision_threads
+       SET status = 'completed', summary_json = ?, completed_at = ?, updated_at = ?
+       WHERE id = ?`,
+    ).run(JSON.stringify({
+      text: summary,
+      completion_kind: 'normalized_state',
+      completed_at: ts,
+    }), ts, ts, id);
+    ops.appendEventInTx(db, {
+      type: 'decision_thread_completed',
+      change_id: thread.change_id,
+      payload: { thread_id: id, item_count: thread.items.length },
+    });
+    return readDecisionThread(db, id);
+  });
+}
+
 function supersedeDecision(db, input = {}) {
   return ops.tx(db, () => {
     const id = requiredText(input.id, 'id');
@@ -411,6 +462,15 @@ function supersedeDecision(db, input = {}) {
          checkpoint_json = json_set(checkpoint_json, '$.invalidated', json('true'),
            '$.invalidated_at', ?, '$.invalidation_reason', ?), updated_at = ? WHERE id = ?`,
       ).run(ts, reason, ts, thread.id);
+    } else if (thread.status === 'completed') {
+      db.prepare(
+        `UPDATE decision_threads
+         SET status = 'active', completed_at = NULL,
+             summary_json = json_set(summary_json, '$.invalidated', json('true'),
+               '$.invalidated_at', ?, '$.invalidation_reason', ?),
+             updated_at = ?
+         WHERE id = ?`,
+      ).run(ts, reason, ts, thread.id);
     }
     insertQuestionInTx(db, readDecisionThread(db, thread.id), replacement, id);
     return readDecisionThread(db, thread.id);
@@ -515,8 +575,10 @@ function checkpointDecisionThread(db, input = {}, { rootDir = process.cwd() } =
     if (!thread) {
       throw new DecisionDialogueError('DECISION_THREAD_NOT_FOUND', `decision thread ${id} not found`);
     }
-    if (thread.status === 'cancelled') {
-      throw new DecisionDialogueError('DECISION_THREAD_NOT_MUTABLE', `decision thread ${id} is cancelled`);
+    if (['completed', 'cancelled'].includes(thread.status)) {
+      throw new DecisionDialogueError(
+        'DECISION_THREAD_NOT_MUTABLE', `decision thread ${id} is ${thread.status}`,
+      );
     }
     const open = thread.items.find((item) => item.status === 'open');
     const deferredBlocking = thread.items.filter((item) => item.blocking && item.status === 'deferred');
@@ -612,6 +674,7 @@ function decisionGate(db, bindings = {}, { rootDir = process.cwd() } = {}) {
   ).all(params);
   const blockers = [];
   let selected = null;
+  let fallback = null;
   for (const row of rows) {
     const thread = readDecisionThread(db, row.id);
     if (thread.status === 'confirmed') {
@@ -622,23 +685,25 @@ function decisionGate(db, bindings = {}, { rootDir = process.cwd() } = {}) {
       }
       continue;
     }
-    selected ||= thread;
-    if (thread.current_decision) blockers.push(`DECISION_AWAITING_OWNER:${thread.current_decision.id}`);
+    fallback ||= thread;
+    const priorBlockerCount = blockers.length;
+    if (thread.current_decision?.blocking) {
+      blockers.push(`DECISION_AWAITING_OWNER:${thread.current_decision.id}`);
+    }
     for (const item of thread.items) {
       if (item.blocking && item.status === 'deferred') {
         blockers.push(`DECISION_DEFERRED_BLOCKING:${item.id}`);
       }
     }
     if (thread.status === 'checkpoint_ready') blockers.push(`DECISION_CHECKPOINT_CONFIRMATION_REQUIRED:${thread.id}`);
-    else if (!thread.current_decision && !thread.items.some((item) => item.blocking && item.status === 'deferred')) {
-      blockers.push(`DECISION_CHECKPOINT_REQUIRED:${thread.id}`);
-    }
+    if (blockers.length > priorBlockerCount) selected ||= thread;
   }
+  const reported = selected || fallback;
   return {
     ready: blockers.length === 0,
     blockers: [...new Set(blockers)],
-    thread: selected,
-    current_decision: selected?.current_decision || null,
+    thread: reported,
+    current_decision: reported?.current_decision || null,
   };
 }
 
@@ -656,8 +721,10 @@ function assertDecisionGate(db, bindings = {}, options = {}) {
 function inspectDecisionHealth(db, { rootDir = process.cwd() } = {}) {
   const threads = listDecisionThreads(db, { limit: 500 });
   const active = threads.filter((thread) => thread.status === 'active');
+  const completed = threads.filter((thread) => thread.status === 'completed');
   const checkpointReady = threads.filter((thread) => thread.status === 'checkpoint_ready');
   const awaiting = active.filter((thread) => thread.current_decision);
+  const awaitingBlocking = awaiting.filter((thread) => thread.current_decision.blocking);
   const deferredBlocking = threads.flatMap((thread) => thread.items.filter(
     (item) => item.blocking && item.status === 'deferred',
   ));
@@ -678,15 +745,20 @@ function inspectDecisionHealth(db, { rootDir = process.cwd() } = {}) {
       }
     }
   }
-  const currentThread = awaiting[0] || checkpointReady[0] || active[0] || null;
-  const currentThreadId = currentThread?.id || staleArtifacts[0]?.thread_id || null;
+  let currentThread = awaitingBlocking[0] || checkpointReady[0] || awaiting[0] || active[0] || null;
+  if (staleArtifacts.length > 0) {
+    currentThread = threads.find((thread) => thread.id === staleArtifacts[0].thread_id) || currentThread;
+  }
+  const currentThreadId = staleArtifacts[0]?.thread_id || currentThread?.id || null;
   const status = staleArtifacts.length > 0
     ? 'fail'
     : (active.length > 0 || checkpointReady.length > 0 || deferredBlocking.length > 0 ? 'warning' : 'pass');
   return {
     status,
     active: active.length,
+    completed: completed.length,
     awaiting_owner: awaiting.length,
+    awaiting_blocking: awaitingBlocking.length,
     checkpoint_ready: checkpointReady.length,
     deferred_blocking: deferredBlocking.length,
     stale_artifacts: staleArtifacts,
@@ -704,6 +776,7 @@ module.exports = {
   resolveDecision,
   delegateDecision,
   deferDecision,
+  completeDecisionThread,
   supersedeDecision,
   checkpointDecisionThread,
   decisionGate,

package/mcp-server/lib/doctor.cjs

@@ -67,7 +67,8 @@ function inspectSystem(db, { rootDir = process.cwd() } = {}) {
   const decisionHealth = missing.length === 0
     ? decisions.inspectDecisionHealth(db, { rootDir })
     : {
-      status: 'fail', active: 0, awaiting_owner: 0, checkpoint_ready: 0,
+      status: 'fail', active: 0, completed: 0, awaiting_owner: 0, awaiting_blocking: 0,
+      checkpoint_ready: 0,
       deferred_blocking: 0, stale_artifacts: [], current: null, current_thread_id: null,
     };
   const baselineCheckStatus = baseline.status === 'pass'

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

@@ -9,7 +9,7 @@ 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 = '18.0';
+const EXPECTED_VERSION = '19.0';
 const KIMI_SCHEMA_VERSION = '9.1';
 const CONTEXT_SCHEMA_VERSION = '10.0';
 const BASELINE_SCHEMA_VERSION = '11.0';
@@ -19,6 +19,8 @@ const AUTHORITY_SCHEMA_VERSION = '14.0';
 const SEMANTIC_SCHEMA_VERSION = '15.0';
 const DIALOGUE_SCHEMA_VERSION = '16.0';
 const GIT_AUTHORITY_SCHEMA_VERSION = '17.0';
+const ADAPTIVE_SCHEMA_VERSION = '18.0';
+const DECISION_COMPLETION_SCHEMA_VERSION = '19.0';
 
 const MIGRATED_GAPS = Object.freeze([{
   id: 'legacy-rebaseline-required',
@@ -328,7 +330,9 @@ function migrateAdaptiveWorkflowRuns(db, fromVersion = latestSchemaVersion(db))
   const existing = db.prepare(
     "SELECT 1 FROM migration_history WHERE to_version = '18.0' AND status = 'success' LIMIT 1",
   ).get();
-  if (fromVersion === EXPECTED_VERSION || existing) return false;
+  if ([ADAPTIVE_SCHEMA_VERSION, DECISION_COMPLETION_SCHEMA_VERSION].includes(fromVersion) || existing) {
+    return false;
+  }
 
   const obsoleteSteps = Object.freeze({
     init: ['establish-baseline'],
@@ -455,6 +459,95 @@ function baselineSupportsUnbornGit(db) {
   return typeof row?.sql === 'string' && row.sql.includes("'unborn'");
 }
 
+function decisionThreadsSupportCompletion(db) {
+  const row = db.prepare(
+    "SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'decision_threads'",
+  ).get();
+  if (typeof row?.sql !== 'string' || !row.sql.includes("'completed'")) return false;
+  return columnNames(db, 'decision_threads').has('completed_at');
+}
+
+function upgradeDecisionThreadLifecycle(db) {
+  if (!tableNames(db).includes('decision_threads') || decisionThreadsSupportCompletion(db)) {
+    return false;
+  }
+  const foreignKeys = db.pragma('foreign_keys', { simple: true });
+  db.pragma('foreign_keys = OFF');
+  try {
+    db.transaction(() => {
+      db.exec(`
+        DROP TABLE IF EXISTS decision_threads_completion_upgrade;
+        CREATE TABLE decision_threads_completion_upgrade (
+          id                 TEXT PRIMARY KEY,
+          purpose            TEXT NOT NULL,
+          mode               TEXT NOT NULL DEFAULT 'guided'
+                               CHECK (mode IN ('guided', 'fast', 'autonomous', 'diagnostic')),
+          status             TEXT NOT NULL DEFAULT 'active'
+                               CHECK (status IN ('active', 'checkpoint_ready', 'completed', 'confirmed', 'cancelled')),
+          baseline_id        TEXT REFERENCES baselines(id) ON DELETE SET NULL,
+          change_id          TEXT REFERENCES changes(id) ON DELETE CASCADE,
+          workflow_run_id    TEXT REFERENCES workflow_runs(id) ON DELETE CASCADE,
+          summary_json       TEXT NOT NULL DEFAULT '{}',
+          checkpoint_json    TEXT NOT NULL DEFAULT '{}',
+          started_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,
+          confirmed_at       TEXT,
+          CHECK (baseline_id IS NOT NULL OR change_id IS NOT NULL OR workflow_run_id IS NOT NULL)
+        );
+        INSERT INTO decision_threads_completion_upgrade (
+          id, purpose, mode, status, baseline_id, change_id, workflow_run_id,
+          summary_json, checkpoint_json, started_at, updated_at, completed_at, confirmed_at
+        )
+        SELECT
+          id, purpose, mode, status, baseline_id, change_id, workflow_run_id,
+          summary_json, checkpoint_json, started_at, updated_at, NULL, confirmed_at
+        FROM decision_threads;
+        DROP TABLE decision_threads;
+        ALTER TABLE decision_threads_completion_upgrade RENAME TO decision_threads;
+        CREATE INDEX decision_threads_status
+          ON decision_threads(status, updated_at);
+        CREATE INDEX decision_threads_authority
+          ON decision_threads(baseline_id, change_id, workflow_run_id, status);
+      `);
+      db.prepare(
+        `UPDATE decision_threads
+         SET status = 'completed',
+             summary_json = CASE
+               WHEN summary_json = '{}' THEN ?
+               ELSE json_set(summary_json, '$.completion_kind', 'migrated_settled_thread')
+             END,
+             completed_at = updated_at
+         WHERE status = 'active'
+           AND EXISTS (
+             SELECT 1 FROM decision_items WHERE decision_items.thread_id = decision_threads.id
+           )
+           AND NOT EXISTS (
+             SELECT 1 FROM decision_items
+             WHERE decision_items.thread_id = decision_threads.id AND status = 'open'
+           )
+           AND NOT EXISTS (
+             SELECT 1 FROM decision_items
+             WHERE decision_items.thread_id = decision_threads.id
+               AND blocking = 1 AND status = 'deferred'
+           )`,
+      ).run(JSON.stringify({
+        text: 'Existing normalized decision state was completed during schema migration.',
+        completion_kind: 'migrated_settled_thread',
+      }));
+      const violations = db.pragma('foreign_key_check');
+      if (violations.length > 0) {
+        throw new Error(
+          `decision completion migration produced ${violations.length} foreign key violation(s)`,
+        );
+      }
+    })();
+  } finally {
+    db.pragma(`foreign_keys = ${foreignKeys ? 'ON' : 'OFF'}`);
+  }
+  return true;
+}
+
 function upgradeBaselineWorktreeConstraint(db, fromVersion = latestSchemaVersion(db)) {
   if (!tableNames(db).includes('baselines') || baselineSupportsUnbornGit(db)) return false;
   const previousVersion = fromVersion || 'unknown';
@@ -611,6 +704,7 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
     })();
   }
   const gitStateChangedFrom = upgradeBaselineWorktreeConstraint(db, fromVersion);
+  const decisionCompletionChanged = upgradeDecisionThreadLifecycle(db);
   db.transaction(() => {
     applyCompatibleColumns(db);
     const contextChanged = applyContextSpineUpgrade(db);
@@ -621,7 +715,8 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
       fromVersion && ![
         CONTEXT_SCHEMA_VERSION, BASELINE_SCHEMA_VERSION, ADOPTION_SCHEMA_VERSION,
         WORKFLOW_SCHEMA_VERSION, AUTHORITY_SCHEMA_VERSION, SEMANTIC_SCHEMA_VERSION,
-        DIALOGUE_SCHEMA_VERSION, GIT_AUTHORITY_SCHEMA_VERSION, EXPECTED_VERSION,
+        DIALOGUE_SCHEMA_VERSION, GIT_AUTHORITY_SCHEMA_VERSION, ADAPTIVE_SCHEMA_VERSION,
+        DECISION_COMPLETION_SCHEMA_VERSION,
       ].includes(fromVersion)
         && !contextMigration,
     );
@@ -646,7 +741,8 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
     if (fromVersion && ![
       BASELINE_SCHEMA_VERSION, ADOPTION_SCHEMA_VERSION, WORKFLOW_SCHEMA_VERSION,
       AUTHORITY_SCHEMA_VERSION, SEMANTIC_SCHEMA_VERSION, DIALOGUE_SCHEMA_VERSION,
-      GIT_AUTHORITY_SCHEMA_VERSION, EXPECTED_VERSION,
+      GIT_AUTHORITY_SCHEMA_VERSION, ADAPTIVE_SCHEMA_VERSION,
+      DECISION_COMPLETION_SCHEMA_VERSION,
     ].includes(fromVersion)
       && !baselineMigration) {
       db.prepare(
@@ -715,7 +811,11 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
     const workflowMigration = db.prepare(
       "SELECT 1 FROM migration_history WHERE to_version = '13.0' AND status = 'success' LIMIT 1",
     ).get();
-    if (fromVersion && fromVersion !== EXPECTED_VERSION && !workflowMigration) {
+    if (fromVersion && ![
+      WORKFLOW_SCHEMA_VERSION, AUTHORITY_SCHEMA_VERSION, SEMANTIC_SCHEMA_VERSION,
+      DIALOGUE_SCHEMA_VERSION, GIT_AUTHORITY_SCHEMA_VERSION, ADAPTIVE_SCHEMA_VERSION,
+      DECISION_COMPLETION_SCHEMA_VERSION,
+    ].includes(fromVersion) && !workflowMigration) {
       db.prepare(
         `INSERT INTO migration_history
           (from_version, to_version, direction, status, notes)
@@ -729,7 +829,10 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
     const authorityMigration = db.prepare(
       "SELECT 1 FROM migration_history WHERE to_version = '14.0' AND status = 'success' LIMIT 1",
     ).get();
-    if (fromVersion && fromVersion !== EXPECTED_VERSION && !authorityMigration) {
+    if (fromVersion && ![
+      AUTHORITY_SCHEMA_VERSION, SEMANTIC_SCHEMA_VERSION, DIALOGUE_SCHEMA_VERSION,
+      GIT_AUTHORITY_SCHEMA_VERSION, ADAPTIVE_SCHEMA_VERSION, DECISION_COMPLETION_SCHEMA_VERSION,
+    ].includes(fromVersion) && !authorityMigration) {
       db.prepare(
         `INSERT INTO migration_history
           (from_version, to_version, direction, status, notes)
@@ -743,7 +846,10 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
     const semanticMigration = db.prepare(
       "SELECT 1 FROM migration_history WHERE to_version = '15.0' AND status = 'success' LIMIT 1",
     ).get();
-    if (fromVersion && fromVersion !== EXPECTED_VERSION && !semanticMigration) {
+    if (fromVersion && ![
+      SEMANTIC_SCHEMA_VERSION, DIALOGUE_SCHEMA_VERSION, GIT_AUTHORITY_SCHEMA_VERSION,
+      ADAPTIVE_SCHEMA_VERSION, DECISION_COMPLETION_SCHEMA_VERSION,
+    ].includes(fromVersion) && !semanticMigration) {
       db.prepare(
         `INSERT INTO migration_history
           (from_version, to_version, direction, status, notes)
@@ -757,7 +863,10 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
     const dialogueMigration = db.prepare(
       "SELECT 1 FROM migration_history WHERE to_version = '16.0' AND status = 'success' LIMIT 1",
     ).get();
-    if (fromVersion && ![DIALOGUE_SCHEMA_VERSION, EXPECTED_VERSION].includes(fromVersion)
+    if (fromVersion && ![
+      DIALOGUE_SCHEMA_VERSION, GIT_AUTHORITY_SCHEMA_VERSION, ADAPTIVE_SCHEMA_VERSION,
+      DECISION_COMPLETION_SCHEMA_VERSION,
+    ].includes(fromVersion)
       && !dialogueMigration) {
       db.prepare(
         `INSERT INTO migration_history
@@ -772,7 +881,9 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
     const gitStateMigration = db.prepare(
       "SELECT 1 FROM migration_history WHERE to_version = '17.0' AND status = 'success' LIMIT 1",
     ).get();
-    if (fromVersion && ![GIT_AUTHORITY_SCHEMA_VERSION, EXPECTED_VERSION].includes(fromVersion)
+    if (fromVersion && ![
+      GIT_AUTHORITY_SCHEMA_VERSION, ADAPTIVE_SCHEMA_VERSION, DECISION_COMPLETION_SCHEMA_VERSION,
+    ].includes(fromVersion)
       && !gitStateMigration) {
       db.prepare(
         `INSERT INTO migration_history
@@ -788,26 +899,44 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
     const adaptiveMigration = db.prepare(
       "SELECT 1 FROM migration_history WHERE to_version = '18.0' AND status = 'success' LIMIT 1",
     ).get();
-    if (fromVersion && fromVersion !== EXPECTED_VERSION && !adaptiveMigration) {
+    if (fromVersion && ![
+      ADAPTIVE_SCHEMA_VERSION, DECISION_COMPLETION_SCHEMA_VERSION,
+    ].includes(fromVersion) && !adaptiveMigration) {
       db.prepare(
         `INSERT INTO migration_history
           (from_version, to_version, direction, status, notes)
          VALUES (?, ?, 'forward', 'success', ?)`,
       ).run(
         fromVersion === GIT_AUTHORITY_SCHEMA_VERSION ? fromVersion : GIT_AUTHORITY_SCHEMA_VERSION,
-        EXPECTED_VERSION,
+        ADAPTIVE_SCHEMA_VERSION,
         adaptiveChanged
           ? 'Migrate active rigid workflows to adaptive capability transitions and independent initialization'
           : 'Add adaptive capability transitions and independent initialization authority',
       );
     }
+    const completionMigration = db.prepare(
+      "SELECT 1 FROM migration_history WHERE to_version = '19.0' AND status = 'success' LIMIT 1",
+    ).get();
+    if (fromVersion && fromVersion !== DECISION_COMPLETION_SCHEMA_VERSION && !completionMigration) {
+      db.prepare(
+        `INSERT INTO migration_history
+          (from_version, to_version, direction, status, notes)
+         VALUES (?, ?, 'forward', 'success', ?)`,
+      ).run(
+        ADAPTIVE_SCHEMA_VERSION,
+        DECISION_COMPLETION_SCHEMA_VERSION,
+        decisionCompletionChanged
+          ? 'Add non-ceremonial decision completion and migrate settled active threads'
+          : 'Add non-ceremonial decision completion authority',
+      );
+    }
     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,
-      'Adaptive capability transitions, independent initialization, and recoverable workflow migration',
+      'Non-ceremonial decision completion and host-neutral intent persistence',
     );
   })();
 }
@@ -837,7 +966,8 @@ function initStateDb(dbPath) {
     const legacyState = existing.size > 0
       && ![
         WORKFLOW_SCHEMA_VERSION, AUTHORITY_SCHEMA_VERSION, SEMANTIC_SCHEMA_VERSION,
-        DIALOGUE_SCHEMA_VERSION, GIT_AUTHORITY_SCHEMA_VERSION, EXPECTED_VERSION,
+        DIALOGUE_SCHEMA_VERSION, GIT_AUTHORITY_SCHEMA_VERSION, ADAPTIVE_SCHEMA_VERSION,
+        DECISION_COMPLETION_SCHEMA_VERSION,
       ].includes(fromVersion);
     backupPath = migrationBackup(db, dbPath, fromVersion, existing);
     applyCompatibleColumns(db);

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

@@ -647,7 +647,7 @@ function normalizeResearchCoverage(mode, coverage, selectedSteps, metadata = {})
     if (selectionReason.length < 3) {
       throw new WorkflowStateError(
         'WORKFLOW_SELECTION_REASON_REQUIRED',
-        `${mode} research requires the model's evidence-based coverage rationale`,
+        `${mode} research requires an evidence-based rationale for the accepted coverage`,
       );
     }
     const synthesis = normalized.find((item) => item.step_id === '99-synthesis');
@@ -679,7 +679,7 @@ function normalizeResearchCoverage(mode, coverage, selectedSteps, metadata = {})
     if (!Array.isArray(selectedSteps) || selectedSteps.length === 0) {
       throw new WorkflowStateError(
         'WORKFLOW_RESEARCH_COVERAGE_REQUIRED',
-        'custom research requires model-selected coverage or selected_steps',
+        'custom research requires accepted coverage or selected_steps',
       );
     }
     const invalid = selectedSteps.find((item) => !known.has(item));
@@ -688,7 +688,7 @@ function normalizeResearchCoverage(mode, coverage, selectedSteps, metadata = {})
     if (selectionReason.length < 3) {
       throw new WorkflowStateError(
         'WORKFLOW_SELECTION_REASON_REQUIRED',
-        'custom research requires the model\'s evidence-based coverage rationale',
+        'custom research requires an evidence-based rationale for the accepted coverage',
       );
     }
     const explicitCoverage = [...new Set([...selectedSteps, '99-synthesis'])].map((stepId) => ({
@@ -701,7 +701,7 @@ function normalizeResearchCoverage(mode, coverage, selectedSteps, metadata = {})
   }
   throw new WorkflowStateError(
     'WORKFLOW_RESEARCH_COVERAGE_REQUIRED',
-    `${mode} research requires model-selected coverage dispositions`,
+    `${mode} research requires accepted coverage dispositions`,
   );
 }
 

package/mcp-server/server.cjs

@@ -112,6 +112,7 @@ const DECISION_TOOLS = Object.freeze([
   'decision.delegate',
   'decision.defer',
   'decision.supersede',
+  'decision.complete',
   'decision.checkpoint',
 ]);
 
@@ -139,7 +140,7 @@ const MUTATING_TOOLS = new Set([
   'change.create', 'change.update', 'change.context', 'change.converge', 'change.archive',
   'change.learning_propose', 'change.learning_resolve',
   'decision.thread_start', 'decision.open', 'decision.resolve', 'decision.delegate',
-  'decision.defer', 'decision.supersede', 'decision.checkpoint',
+  'decision.defer', 'decision.supersede', 'decision.complete', 'decision.checkpoint',
   'workflow.start', 'workflow.step', 'workflow.complete',
 ]);
 
@@ -576,6 +577,9 @@ async function dispatchTool(name, input, db, ctx = {}) {
     case 'decision.supersede': {
       return { thread: decisions.supersedeDecision(db, input) };
     }
+    case 'decision.complete': {
+      return { thread: decisions.completeDecisionThread(db, input) };
+    }
     case 'decision.checkpoint': {
       return {
         thread: decisions.checkpointDecisionThread(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "Explicitly invoked Ultra Builder Pro workflows for Claude Code, OpenCode, Codex CLI, and Kimi Code, with project-local MCP authority and lifecycle recovery.",
   "bin": {
     "ultra-builder-pro-cli": "bin/install.js",

package/skills/ultra-change/SKILL.md

@@ -29,13 +29,18 @@ Read `../ultra-think/references/decision-dialogue.md` before asking a material q
    - change kind and evidence-backed risk flags;
    - research disposition.
 
-Select `quick`, `standard`, `major`, or `incident` from actual scope and risk. A quick
-change may have no material risk, research obligation, or more than one task.
+Recommend `quick`, `standard`, `major`, or `incident` from actual scope and risk,
+together with the research disposition. A quick change may have no material risk,
+research obligation, or more than one task. MCP may reject a profile that contradicts
+hard risk invariants; it does not choose a replacement.
 
 Ask only when a choice changes accepted product intent, scope, public behavior,
 compatibility, security, material cost, external effects, or recovery. Use the host's
 native question UI when available. Normalize clear choices already in the user's
-request. The model owns reversible implementation detail inside the accepted contract.
+request. When profile or research posture remains unresolved, present the recommended
+route and credible alternatives through that same UI, then stop. The user selects,
+modifies, delegates, or defers the semantic route. The model owns reversible
+implementation detail inside the accepted contract.
 
 ## Persist the contract
 
@@ -70,5 +75,7 @@ transitions. External memory and graph providers retain their own content; Ultra
 metadata references only.
 
 Return the normalized contract, change id and kind, research disposition, blockers,
-and `allowed_transitions`. The host selects a recommendation from those transitions;
-MCP does not encode a semantic next action.
+and `allowed_transitions`. Recommend a semantic next action from those transitions.
+If current intent does not already select it, present the recommendation and credible
+alternatives through the interaction protocol, then wait. MCP does not encode a
+semantic next action.

package/skills/ultra-plan/SKILL.md

@@ -15,17 +15,34 @@ accepted Change Contract without adding ceremonial approval.
    checkout.
 2. Require one mutable change with a healthy baseline or recorded incident bypass.
 3. Complete the exact change-bound research disposition before planning.
-4. Resume the matching plan run or start one bound to the change and baseline.
+4. Resume the matching plan run. Do not start a new run until planning posture is
+   accepted.
 
 Read `references/semantic-preflight.md` and inspect requirements, real consumers,
 state, tests, deployment, and recovery paths.
 
+## Align planning posture
+
+Use the interaction protocol in `../ultra-think/references/decision-dialogue.md`.
+Normalize a posture already explicit in current intent. Otherwise recommend one based
+on the Change Contract, explain its scope effect, and use the host's native question
+surface:
+
+- `EXPAND`: surface evidence-backed opportunities beyond accepted scope;
+- `SELECTIVE`: hold accepted scope and offer optional expansions individually;
+- `HOLD`: preserve scope and strengthen completeness, failure handling, and recovery;
+- `REDUCE`: propose the smallest outcome that still satisfies revised acceptance.
+
+The user may select, modify, delegate, or defer the posture. Stop on an unanswered
+choice. Start `workflow.start` only after alignment and store `planning_posture` plus
+its rationale in workflow metadata. This is a scope boundary, not approval of the
+eventual technical design.
+
 ## Design with model autonomy
 
 Build a candidate plan privately. Ask the user only if the plan would change accepted
 scope, public behavior, compatibility, security, material cost, external effects, or
-recovery. Use the host's native question UI when available and the interaction protocol
-in `../ultra-think/references/decision-dialogue.md`.
+recovery. Use the same host-native interaction protocol.
 
 When the candidate remains inside the accepted Change Contract, proceed without a
 second approval. A user may still request a plan review before persistence; that is an