ultra-builder-pro-cli 0.18.0 → 0.20.0

package/hooks/health_check.py

@@ -27,6 +27,22 @@ def hook_input() -> dict:
         return {}
 
 
+def has_active_workflow(db_path: Path) -> bool:
+    if not db_path.is_file():
+        return False
+    try:
+        uri = f"file:{db_path}?mode=ro"
+        with sqlite3.connect(uri, uri=True, timeout=1) as conn:
+            row = conn.execute(
+                """SELECT 1 FROM workflow_runs
+                   WHERE status IN ('active', 'blocked', 'ready')
+                   LIMIT 1"""
+            ).fetchone()
+            return row is not None
+    except sqlite3.Error:
+        return False
+
+
 def inspect(root: Path) -> dict:
     db_path = root / ".ultra" / "state.db"
     report = {"status": "healthy", "project": str(root), "checks": {}}
@@ -171,6 +187,9 @@ def main() -> None:
     if root is None:
         print(json.dumps({}))
         return
+    if not has_active_workflow(root / ".ultra" / "state.db"):
+        print(json.dumps({}))
+        return
     report = inspect(root)
     if report["status"] != "healthy":
         print("[Ultra health] " + json.dumps(report, ensure_ascii=False, sort_keys=True), file=sys.stderr)

package/hooks/pre_stop_check.py

@@ -34,7 +34,7 @@ def main() -> None:
         print(f"[pre_stop_check] cannot inspect Context Spine: {exc}", file=sys.stderr)
         allow_stop()
         return
-    if breadcrumb and breadcrumb.get("change_id"):
+    if breadcrumb and breadcrumb.get("workflow"):
         allowed = ", ".join(breadcrumb.get("allowed_transitions") or []) or "none"
         required = breadcrumb.get("required_transition") or "none"
         print(

package/hooks/workflow_checkpoint.py

@@ -33,7 +33,7 @@ def main() -> None:
         print(f"[workflow_checkpoint] cannot inspect Context Spine: {exc}", file=sys.stderr)
         print(json.dumps({}))
         return
-    if not breadcrumb or not breadcrumb.get("change_id"):
+    if not breadcrumb or not breadcrumb.get("workflow"):
         print(json.dumps({}))
         return
 

package/hooks/workflow_context.py

@@ -28,7 +28,7 @@ def main() -> None:
     except ContextSpineError as exc:
         print(f"[workflow_context] cannot inspect Context Spine: {exc}", file=sys.stderr)
         breadcrumb = None
-    if breadcrumb:
+    if breadcrumb and breadcrumb.get("workflow"):
         context = render_breadcrumb(root, breadcrumb)
     else:
         print(json.dumps({}))

package/hooks/workflow_resume.py

@@ -64,7 +64,7 @@ def main() -> None:
     text = None
     try:
         breadcrumb = read_breadcrumb(root)
-        if breadcrumb:
+        if breadcrumb and breadcrumb.get("workflow"):
             text = render_breadcrumb(root, breadcrumb)
     except ContextSpineError as exc:
         print(f"[workflow_resume] cannot inspect Context Spine: {exc}", file=sys.stderr)

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(
@@ -818,16 +822,28 @@ function appendHookLifecycleEvent({ rootDir, action, hookInput = {} } = {}) {
   const db = openStateDb(dbPath);
   try {
     ensureSchemaVersion(db);
-    const change = db.prepare(
-      `SELECT id FROM changes WHERE status IN ('active', 'blocked', 'ready')
+    const workflow = db.prepare(
+      `SELECT change_id, task_id FROM workflow_runs
+       WHERE status IN ('active', 'blocked', 'ready') AND change_id IS NOT NULL
        ORDER BY updated_at DESC, rowid DESC LIMIT 1`,
     ).get();
+    if (!workflow) return { recorded: false, reason: 'NO_ACTIVE_WORKFLOW' };
+    const change = db.prepare(
+      `SELECT id FROM changes
+       WHERE id = ? AND status IN ('active', 'blocked', 'ready')`,
+    ).get(workflow.change_id);
     if (!change) return { recorded: false, reason: 'NO_ACTIVE_CHANGE' };
-    const task = db.prepare(
-      `SELECT id FROM tasks WHERE change_id = ? AND status IN ('in_progress', 'pending', 'blocked')
-       ORDER BY CASE status WHEN 'in_progress' THEN 0 WHEN 'blocked' THEN 1 ELSE 2 END,
-                updated_at DESC, rowid DESC LIMIT 1`,
-    ).get(change.id);
+    const task = workflow.task_id
+      ? db.prepare(
+        `SELECT id FROM tasks
+         WHERE id = ? AND change_id = ?
+           AND status IN ('in_progress', 'pending', 'blocked')`,
+      ).get(workflow.task_id, change.id)
+      : db.prepare(
+        `SELECT id FROM tasks WHERE change_id = ? AND status IN ('in_progress', 'pending', 'blocked')
+         ORDER BY CASE status WHEN 'in_progress' THEN 0 WHEN 'blocked' THEN 1 ELSE 2 END,
+                  updated_at DESC, rowid DESC LIMIT 1`,
+      ).get(change.id);
     const payload = {
       agent_id: hookMetadata(hookInput.agent_id),
       agent_type: hookMetadata(hookInput.agent_type),

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.18.0",
-  "description": "Multi-runtime installer for the Ultra Builder Pro agent engineering system — deploys commands, agents, skills, hooks, and MCP server to Claude Code, OpenCode, Codex CLI, and Kimi Code.",
+  "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",
     "ubp": "bin/install.js",
-    "ubp-handbook": "bin/handbook.js",
     "ubp-orchestrator": "bin/orchestrator.js",
     "ultra-tools": "ultra-tools/cli.cjs"
   },
@@ -56,7 +55,7 @@
     "docs/COMMIT-HASH-BACKFILL.md",
     "docs/DECISIONS.md",
     "docs/STATE-DB-ACCESS-POLICY.md",
-    "docs/USER-HANDBOOK-CONTRACT.md",
+    "docs/PLUGIN-ISOLATION-CONTRACT.md",
     "docs/RUNTIME-COMPAT-MATRIX.md",
     "!**/__pycache__/**",
     "!**/*.pyc",