ultra-builder-pro-cli 0.15.0 → 0.17.0

package/spec/schemas/delivery-report.v1.schema.json

@@ -5,7 +5,7 @@
   "type": "object",
   "required": [
     "$schema", "change_id", "archive_status", "baseline_id", "baseline_status",
-    "git_commit", "worktree_digest", "context_digest", "checks", "release", "rollback", "timestamp"
+    "git_commit", "worktree_digest", "context_digest", "checks", "rollback", "timestamp"
   ],
   "additionalProperties": false,
   "properties": {
@@ -41,51 +41,6 @@
         ]
       }
     },
-    "release": {
-      "type": "object",
-      "required": ["authorized", "performed", "evidence"],
-      "additionalProperties": false,
-      "properties": {
-        "authorized": { "type": "boolean" },
-        "performed": { "type": "boolean" },
-        "evidence": {
-          "type": "array",
-          "items": {
-            "type": "object",
-            "required": ["kind", "reference", "status", "evidence"],
-            "additionalProperties": false,
-            "properties": {
-              "kind": { "enum": ["commit", "push", "tag", "registry", "deploy", "release", "other"] },
-              "reference": { "type": "string", "minLength": 1 },
-              "status": { "const": "pass" },
-              "evidence": { "type": "string", "minLength": 1 }
-            }
-          }
-        },
-        "version": { "type": "string" },
-        "tag": { "type": "string" },
-        "commit": { "type": "string" },
-        "registry": { "type": "string" },
-        "remote": { "type": "string" }
-      },
-      "allOf": [
-        {
-          "if": { "properties": { "authorized": { "const": true } } },
-          "then": {
-            "properties": {
-              "performed": { "const": true },
-              "evidence": { "minItems": 1 }
-            }
-          },
-          "else": {
-            "properties": {
-              "performed": { "const": false },
-              "evidence": { "maxItems": 0 }
-            }
-          }
-        }
-      ]
-    },
     "rollback": { "type": ["string", "null"] },
     "timestamp": { "type": ["string", "null"], "format": "date-time" }
   },

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

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

package/spec/schemas/state-db.sql

@@ -29,7 +29,7 @@ CREATE TABLE IF NOT EXISTS baselines (
   repository_revision TEXT,
   repository_branch   TEXT,
   worktree_state      TEXT NOT NULL DEFAULT 'unavailable'
-                        CHECK (worktree_state IN ('clean', 'dirty', 'unavailable')),
+                        CHECK (worktree_state IN ('clean', 'dirty', 'unborn', 'unavailable')),
   worktree_digest     TEXT,
   worktree_files_json TEXT NOT NULL DEFAULT '[]',
   worktree_accepted   INTEGER NOT NULL DEFAULT 0 CHECK (worktree_accepted IN (0, 1)),
@@ -67,6 +67,7 @@ CREATE TABLE IF NOT EXISTS changes (
   contract_json     TEXT NOT NULL DEFAULT '{}',
   classification_json TEXT NOT NULL DEFAULT '{}',
   research_disposition_json TEXT NOT NULL DEFAULT '{}',
+  alignment_thread_id TEXT REFERENCES decision_threads(id) ON DELETE SET NULL,
   base_commit       TEXT,
   artifact_root     TEXT NOT NULL,
   created_at        TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
@@ -251,7 +252,9 @@ CREATE TABLE IF NOT EXISTS context_snapshots (
                        CHECK (role IN ('plan', 'implement', 'check', 'review')),
   gate               TEXT NOT NULL DEFAULT 'alignment'
                        CHECK (gate IN ('alignment', 'planning', 'implementation', 'verification', 'review', 'convergence', 'recovery')),
-  next_action        TEXT NOT NULL DEFAULT 'Resolve the next Ultra workflow action.',
+  next_action        TEXT NOT NULL DEFAULT '',
+  allowed_transitions_json TEXT NOT NULL DEFAULT '[]',
+  required_transition TEXT,
   readiness          TEXT NOT NULL DEFAULT 'ready'
                        CHECK (readiness IN ('ready', 'blocked')),
   blockers_json      TEXT NOT NULL DEFAULT '[]',
@@ -403,6 +406,61 @@ CREATE UNIQUE INDEX IF NOT EXISTS workflow_steps_position
 CREATE INDEX IF NOT EXISTS workflow_steps_status
   ON workflow_steps(run_id, status, position);
 
+-- ──────────────────────────── decision dialogue ─────────────────────────
+-- The host owns reasoning and normalized decision content. MCP owns one-at-a-
+-- time presentation, durable authority, checkpoints, and recovery. Raw prompts
+-- and transcripts never belong in these tables.
+CREATE TABLE IF NOT EXISTS decision_threads (
+  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', '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')),
+  confirmed_at       TEXT,
+  CHECK (baseline_id IS NOT NULL OR change_id IS NOT NULL OR workflow_run_id IS NOT NULL)
+);
+
+CREATE INDEX IF NOT EXISTS decision_threads_status
+  ON decision_threads(status, updated_at);
+CREATE INDEX IF NOT EXISTS decision_threads_authority
+  ON decision_threads(baseline_id, change_id, workflow_run_id, status);
+
+CREATE TABLE IF NOT EXISTS decision_items (
+  id                 TEXT PRIMARY KEY,
+  thread_id          TEXT NOT NULL REFERENCES decision_threads(id) ON DELETE CASCADE,
+  sequence           INTEGER NOT NULL CHECK (sequence > 0),
+  phase              TEXT NOT NULL,
+  question           TEXT NOT NULL,
+  why_now            TEXT NOT NULL,
+  recommendation     TEXT NOT NULL,
+  options_json       TEXT NOT NULL DEFAULT '[]',
+  evidence_refs_json TEXT NOT NULL DEFAULT '[]',
+  dependency_ids_json TEXT NOT NULL DEFAULT '[]',
+  effects_json       TEXT NOT NULL DEFAULT '{}',
+  blocking           INTEGER NOT NULL DEFAULT 1 CHECK (blocking IN (0, 1)),
+  status             TEXT NOT NULL DEFAULT 'open'
+                       CHECK (status IN ('open', 'answered', 'delegated', 'deferred', 'superseded')),
+  resolution_json    TEXT NOT NULL DEFAULT '{}',
+  supersedes_id      TEXT REFERENCES decision_items(id) ON DELETE SET NULL,
+  created_at         TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  updated_at         TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  resolved_at        TEXT,
+  UNIQUE (thread_id, sequence)
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS decision_items_one_open
+  ON decision_items(thread_id) WHERE status = 'open';
+CREATE INDEX IF NOT EXISTS decision_items_status
+  ON decision_items(thread_id, status, sequence);
+
 -- ──────────────────────────── seed: schema_version ────────────────────────
 INSERT OR IGNORE INTO schema_version (version, description)
 VALUES ('4.5', 'Phase 2 initial — tasks/events/sessions/schema_version/migration_history/telemetry/specs_refs');
@@ -428,3 +486,9 @@ INSERT OR IGNORE INTO schema_version (version, description)
 VALUES ('14.0', 'Continuously revalidated baseline authority and persisted known-red acceptance');
 INSERT OR IGNORE INTO schema_version (version, description)
 VALUES ('15.0', 'Typed research semantics, complete change contracts, verified learning application, and reconciliation provenance');
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES ('16.0', 'Durable one-question decision dialogue, owner checkpoints, and workflow alignment gates');
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES ('17.0', 'Explicit unborn Git authority and owner-authorized baseline checkpoints');
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES ('18.0', 'Adaptive capability transitions, independent initialization, and recoverable workflow migration');

package/spec/schemas/test-report.v1.schema.json

@@ -6,7 +6,7 @@
   "required": [
     "$schema", "change_id", "task_ids", "git_commit", "worktree_digest",
     "context_digest", "acceptance", "commands", "public_seams", "failures",
-    "recovery", "verification_dimensions", "regression_signal", "passed", "run_count",
+    "recovery", "verification_profile", "verification_dimensions", "regression_signal", "passed", "run_count",
     "timestamp", "blocking_issues"
   ],
   "additionalProperties": false,
@@ -93,12 +93,36 @@
         }
       }
     },
+    "verification_profile": {
+      "type": "object",
+      "required": ["rationale", "selected_dimensions", "excluded_dimensions"],
+      "additionalProperties": false,
+      "properties": {
+        "rationale": { "type": "string", "minLength": 3 },
+        "selected_dimensions": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "contains": { "const": "acceptance" },
+          "items": { "$ref": "#/$defs/verificationDimensionName" }
+        },
+        "excluded_dimensions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["dimension", "rationale"],
+            "additionalProperties": false,
+            "properties": {
+              "dimension": { "$ref": "#/$defs/verificationDimensionName" },
+              "rationale": { "type": "string", "minLength": 3 }
+            }
+          }
+        }
+      }
+    },
     "verification_dimensions": {
       "type": "object",
-      "required": [
-        "acceptance", "regression", "integration", "static_analysis",
-        "build", "performance", "security", "recovery"
-      ],
+      "required": ["acceptance"],
       "additionalProperties": false,
       "properties": {
         "acceptance": { "$ref": "#/$defs/verificationDimension" },
@@ -131,12 +155,19 @@
     "blocking_issues": { "type": "array", "items": { "type": "string" } }
   },
   "$defs": {
+    "verificationDimensionName": {
+      "type": "string",
+      "enum": [
+        "acceptance", "regression", "integration", "static_analysis",
+        "build", "performance", "security", "recovery"
+      ]
+    },
     "verificationDimension": {
       "type": "object",
       "required": ["status", "evidence", "rationale"],
       "additionalProperties": false,
       "properties": {
-        "status": { "enum": ["pass", "fail", "not_run", "not_applicable"] },
+        "status": { "enum": ["pass", "fail", "not_run"] },
         "evidence": {
           "type": "array",
           "items": { "type": "string", "minLength": 1 }
@@ -174,14 +205,14 @@
           "recovery": { "items": { "properties": { "status": { "const": "pass" } } } },
           "verification_dimensions": {
             "properties": {
-              "acceptance": { "properties": { "status": { "enum": ["pass", "not_applicable"] } } },
-              "regression": { "properties": { "status": { "enum": ["pass", "not_applicable"] } } },
-              "integration": { "properties": { "status": { "enum": ["pass", "not_applicable"] } } },
-              "static_analysis": { "properties": { "status": { "enum": ["pass", "not_applicable"] } } },
-              "build": { "properties": { "status": { "enum": ["pass", "not_applicable"] } } },
-              "performance": { "properties": { "status": { "enum": ["pass", "not_applicable"] } } },
-              "security": { "properties": { "status": { "enum": ["pass", "not_applicable"] } } },
-              "recovery": { "properties": { "status": { "enum": ["pass", "not_applicable"] } } }
+              "acceptance": { "properties": { "status": { "const": "pass" } } },
+              "regression": { "properties": { "status": { "const": "pass" } } },
+              "integration": { "properties": { "status": { "const": "pass" } } },
+              "static_analysis": { "properties": { "status": { "const": "pass" } } },
+              "build": { "properties": { "status": { "const": "pass" } } },
+              "performance": { "properties": { "status": { "const": "pass" } } },
+              "security": { "properties": { "status": { "const": "pass" } } },
+              "recovery": { "properties": { "status": { "const": "pass" } } }
             }
           },
           "run_count": { "minimum": 1 },

package/ultra-tools/cli.cjs

@@ -38,7 +38,7 @@ SUBCOMMANDS:
   system    doctor [--repair] | restore | rebaseline
   status    [--cost] [--since <duration>] [--json]
   db        init | checkpoint | vacuum | integrity | backup (Phase 2)
-  migrate   --from=<4.4|4.5> --to=<4.5|15.0> [--dry|--rollback]
+  migrate   --from=<4.4|4.5> --to=<4.5|18.0> [--dry|--rollback]
   legacy-memory inspect | archive | prune --confirm DELETE_ULTRA_LEGACY_MEMORY
 
   --help / -h      show this message

package/ultra-tools/commands/session.cjs

@@ -9,6 +9,7 @@
 const path = require('node:path');
 const { initStateDb, closeStateDb } = require('../../mcp-server/lib/state-db.cjs');
 const ops = require('../../mcp-server/lib/state-ops.cjs');
+const sessionRunner = require('../../orchestrator/session-runner.cjs');
 
 const DEFAULT_DB_PATH = path.join('.ultra', 'state.db');
 
@@ -20,11 +21,12 @@ VERBS:
   reap        [--grace-seconds <n>]                      orphan sweeper (Phase 4.5.6)
   get         --sid <sid>
   heartbeat   --sid <sid>
-  close       --sid <sid> --status completed|crashed|orphan
+  close       --sid <sid> --status completed|crashed|orphan [--remove-worktree]
   subscribe   --since-id <n> [--sid <sid>] [--limit <n>]
 
 GLOBAL FLAGS:
   --db <path>  path to state.db (default: .ultra/state.db)
+  --repo-root <path> repository root for verified worktree cleanup (default: cwd)
   -h, --help   show this message
 `;
 
@@ -44,6 +46,8 @@ function parseFlags(args) {
       case '--limit':           flags.limit = Number(args[++i]); break;
       case '--since-id':        flags.since_id = Number(args[++i]); break;
       case '--grace-seconds':   flags.grace_seconds = Number(args[++i]); break;
+      case '--repo-root':       flags.repo_root = args[++i]; break;
+      case '--remove-worktree': flags.remove_worktree = true; break;
       case '-h': case '--help': flags.help = true; break;
       default:                  flags._.push(a);
     }
@@ -127,8 +131,11 @@ function cmdClose(flags) {
   if (!flags.sid || !flags.status) { emit({ ok: false, error: { code: 'VALIDATION_ERROR', message: 'missing --sid or --status' } }); return 1; }
   return withDb(flags, (db) => {
     try {
-      ops.updateSession(db, flags.sid, { status: flags.status });
-      emit({ ok: true, data: { sid: flags.sid, status: flags.status } });
+      const result = sessionRunner.closeSession(
+        { db, repoRoot: path.resolve(flags.repo_root || process.cwd()), sid: flags.sid },
+        { status: flags.status, remove_worktree: flags.remove_worktree === true },
+      );
+      emit({ ok: true, data: result });
       return 0;
     } catch (err) {
       emit({ ok: false, error: { code: err.code || 'STATE_DB_ERROR', message: err.message } });

package/ultra-tools/commands/status.cjs

@@ -12,11 +12,12 @@ const path = require('node:path');
 const ops = require('../../mcp-server/lib/state-ops.cjs');
 const baselines = require('../../mcp-server/lib/baseline-workflow.cjs');
 const workflowState = require('../../mcp-server/lib/workflow-state.cjs');
+const decisionDialogue = require('../../mcp-server/lib/decision-dialogue.cjs');
 const { readBreadcrumb } = require('../../mcp-server/lib/context-spine.cjs');
 
 const USAGE = `ultra-tools status [flags]
 
-Reads .ultra/state.db and prints baseline, workflow, task, session, route, and
+Reads .ultra/state.db and prints baseline, workflow, task, session, valid transitions, and
 cost-observability status.
 
 FLAGS:
@@ -167,20 +168,25 @@ function buildStatusPanel(db, { since = null, limit = 3, rootDir = process.cwd()
     };
   }
   if (!Array.isArray(workflows.current)) workflows.current = [];
-  let next;
+  const decisions = tables.has('decision_threads') && tables.has('decision_items')
+    ? decisionDialogue.inspectDecisionHealth(db, { rootDir })
+    : {
+      status: 'unavailable', active: 0, awaiting_owner: 0, checkpoint_ready: 0,
+      deferred_blocking: 0, stale_artifacts: [], current: null, current_thread_id: null,
+    };
+  let transitions;
   let breadcrumb = null;
   try {
     if (!tables.has('baselines')) {
-      next = {
-        action: 'Resume project initialization to migrate and establish baseline authority.',
-        recommended_workflow: 'ultra-init', readiness: 'blocked',
+      transitions = {
+        allowed: ['ultra-init', 'ultra-status'], required: 'ultra-init', readiness: 'blocked',
         blockers: ['BASELINE_SCHEMA_MIGRATION_REQUIRED'], warnings: [],
       };
     } else {
     breadcrumb = readBreadcrumb(db, {}, { rootDir });
-    next = {
-      action: breadcrumb.next_action,
-      recommended_workflow: breadcrumb.recommended_workflow,
+    transitions = {
+      allowed: breadcrumb.allowed_transitions,
+      required: breadcrumb.required_transition,
       readiness: breadcrumb.readiness,
       blockers: breadcrumb.blockers,
       warnings: breadcrumb.warnings,
@@ -190,9 +196,8 @@ function buildStatusPanel(db, { since = null, limit = 3, rootDir = process.cwd()
     };
     }
   } catch (error) {
-    next = {
-      action: 'Run ultra-doctor to inspect authoritative state.',
-      recommended_workflow: 'ultra-doctor', readiness: 'blocked',
+    transitions = {
+      allowed: ['ultra-doctor', 'ultra-status'], required: 'ultra-doctor', readiness: 'blocked',
       blockers: [`STATUS_AUTHORITY_UNAVAILABLE:${error.code || 'unknown'}`], warnings: [],
     };
   }
@@ -242,13 +247,14 @@ function buildStatusPanel(db, { since = null, limit = 3, rootDir = process.cwd()
     period: { since: since || 'all-time' },
     baseline,
     workflows,
+    decisions,
     current_change: currentChange,
     current_task: currentTask,
     evidence,
     changes,
     tasks: taskCounts,
     sessions,
-    next,
+    transitions,
     by_runtime,
     top_tasks,
     total_cost_usd,
@@ -287,6 +293,13 @@ function renderHuman(panel) {
       `Workflow: ${current.id} (${current.kind}/${current.status}) · step=${current.current_step || 'finalize'} · outputs=${current.output_health}`,
     );
   }
+  if (panel.decisions.current) {
+    lines.push(
+      `Decision: ${panel.decisions.current.id} (${panel.decisions.current.phase}) — ${panel.decisions.current.question}`,
+    );
+  } else if (panel.decisions.checkpoint_ready > 0) {
+    lines.push(`Decision checkpoint: ${panel.decisions.current_thread_id} awaits confirmation`);
+  }
   lines.push(
     `Changes: active=${panel.changes.active} blocked=${panel.changes.blocked} ready=${panel.changes.ready} archived=${panel.changes.archived}`,
   );
@@ -300,7 +313,8 @@ function renderHuman(panel) {
   lines.push(
     `Sessions: running=${panel.sessions.running} crashed=${panel.sessions.crashed} orphan=${panel.sessions.orphan}`,
   );
-  lines.push(`Next: ${panel.next.action} (${panel.next.recommended_workflow})`);
+  lines.push(`Allowed transitions: ${panel.transitions.allowed.join(', ') || 'none'}`);
+  if (panel.transitions.required) lines.push(`Required transition: ${panel.transitions.required}`);
   lines.push(
     `Evidence: test=${panel.evidence.test.status} review=${panel.evidence.review.status} delivery=${panel.evidence.delivery.status}`,
   );
@@ -345,6 +359,11 @@ function resolveDbPath() {
   return path.resolve('.ultra', 'state.db');
 }
 
+function resolveRootDir(dbPath) {
+  if (process.env.UBP_ROOT_DIR) return path.resolve(process.env.UBP_ROOT_DIR);
+  return path.dirname(path.dirname(dbPath));
+}
+
 function dispatch(args) {
   let flags;
   try { flags = parseFlags(args); } catch (err) { return fail('USAGE_ERROR', err.message); }
@@ -362,7 +381,7 @@ function dispatch(args) {
   const Database = require('better-sqlite3');
   const db = new Database(dbPath, { readonly: true });
   try {
-    const rootDir = path.dirname(path.dirname(dbPath));
+    const rootDir = resolveRootDir(dbPath);
     const panel = buildStatusPanel(db, { since, limit: flags.limit, rootDir });
     if (flags.json) {
       emit({ ok: true, data: panel });
@@ -383,4 +402,5 @@ module.exports = {
   renderHuman,
   parseSince,
   parseFlags,
+  resolveRootDir,
 };

package/ultra-tools/commands/system.cjs

@@ -213,7 +213,7 @@ async function dispatchRestore(args) {
         quarantined_state_path: path.join(recoveryDir, 'state.db'),
         schema_version: initialized.schema_version,
         schema_migration_backup_path: initialized.backup_path || null,
-        next_action: 'Run ultra-tools system doctor, then ultra-init to inspect baseline readiness.',
+        recovery_guidance: 'Run ultra-tools system doctor, then ultra-init to inspect baseline readiness.',
       },
     });
     return 0;
@@ -284,7 +284,7 @@ async function dispatchRebaseline(args) {
           : null,
         baseline: initialized.baseline,
         copied_files: initialized.copied_files,
-        next_action: 'Inspect the preserved evidence, record the brownfield baseline, and obtain owner approval before convergence.',
+        recovery_guidance: 'Inspect the preserved evidence, run explicit adoption research, record the brownfield baseline, and obtain owner approval before convergence.',
       },
     });
     return 0;

package/ultra-tools/commands/task.cjs

@@ -17,6 +17,7 @@ FLAGS (init-project):
   --project-type <type>     web | api | cli | fullstack | other
   --stack <stack>           tech stack descriptor (comma-separated ok)
   --mode <mode>             auto | greenfield | brownfield (default: auto)
+  --git-mode <mode>         auto | initialize | skip (default: auto)
   --scope <path>            baseline scope; repeat for multiple paths (default: .)
   --resume                  preserve existing .ultra/ and install only missing assets
   --overwrite               replace existing .ultra/ (backup created)
@@ -38,6 +39,7 @@ function parseInitFlags(args) {
       case '--project-type':     flags.project_type     = args[++i]; break;
       case '--stack':            flags.stack            = args[++i]; break;
       case '--mode':             flags.mode             = args[++i]; break;
+      case '--git-mode':         flags.git_mode         = args[++i]; break;
       case '--scope':            flags.scope.push(args[++i]); break;
       case '--resume':           flags.resume            = true; break;
       case '--source-template':  flags.source_template  = args[++i]; break;
@@ -66,6 +68,7 @@ function dispatchInitProject(rawArgs) {
     project_type: flags.project_type,
     stack: flags.stack,
     mode: flags.mode || 'auto',
+    git_mode: flags.git_mode || 'auto',
     scope: flags.scope.length > 0 ? flags.scope : undefined,
     resume: !!flags.resume,
     overwrite: !!flags.overwrite,