ultra-builder-pro-cli 0.15.0 → 0.16.0

package/mcp-server/lib/doctor.cjs

@@ -12,6 +12,7 @@ const baselines = require('./baseline-workflow.cjs');
 const changes = require('./change-workflow.cjs');
 const archiveJournal = require('./archive-journal.cjs');
 const workflows = require('./workflow-state.cjs');
+const decisions = require('./decision-dialogue.cjs');
 
 const SPEC_CONSUMER = 'spec-staleness';
 
@@ -63,6 +64,12 @@ function inspectSystem(db, { rootDir = process.cwd() } = {}) {
       status: 'fail', active: 0, blocked: 0, ready: 0, stale_outputs: [],
       historical_stale_outputs: [], terminal_authority_runs: [], untracked_active_changes: [],
     };
+  const decisionHealth = missing.length === 0
+    ? decisions.inspectDecisionHealth(db, { rootDir })
+    : {
+      status: 'fail', active: 0, awaiting_owner: 0, checkpoint_ready: 0,
+      deferred_blocking: 0, stale_artifacts: [], current: null, current_thread_id: null,
+    };
   const baselineCheckStatus = baseline.status === 'pass'
     ? 'pass'
     : (baseline.baseline?.status === 'ready' ? 'fail' : 'warning');
@@ -70,6 +77,7 @@ function inspectSystem(db, { rootDir = process.cwd() } = {}) {
     || pending.length > 0 || running.length > 0 || failed.length > 0 || orphanSessions > 0 || activeMissing > 0
     || archiveIntents.length > 0
     || eventCursor > projectedCursor || workflowHealth.status === 'fail'
+    || decisionHealth.status === 'fail'
     || baselineCheckStatus === 'fail';
   return {
     status: degraded ? 'degraded' : 'healthy',
@@ -115,6 +123,7 @@ function inspectSystem(db, { rootDir = process.cwd() } = {}) {
         terminal_authority_runs: workflowHealth.terminal_authority_runs,
         untracked_active_changes: workflowHealth.untracked_active_changes,
       },
+      decisions: decisionHealth,
       external_providers: {
         status: 'pass', ownership: 'external',
         note: 'Ultra stores provider metadata references only and never owns memory or code-graph content.',

package/mcp-server/lib/project-breadcrumb.cjs

@@ -126,6 +126,15 @@ function renderProjectBreadcrumb(rootDir, breadcrumb) {
       `Step: ${breadcrumb.workflow.current_step || 'finalize'}`,
     );
   }
+  if (breadcrumb.decision) {
+    const current = breadcrumb.decision.current;
+    lines.push(
+      `Decision thread: ${breadcrumb.decision.thread_id} (${breadcrumb.decision.status}/${breadcrumb.decision.mode})`,
+      current
+        ? `Decision: ${current.id} — ${current.question}`
+        : 'Decision: checkpoint confirmation required',
+    );
+  }
   lines.push(
     `Next: ${breadcrumb.next_action || 'Inspect Ultra status.'}`,
     `Route: ${breadcrumb.recommended_workflow || 'ultra-doctor'}`,

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

@@ -9,13 +9,14 @@ 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 = '15.0';
+const EXPECTED_VERSION = '16.0';
 const KIMI_SCHEMA_VERSION = '9.1';
 const CONTEXT_SCHEMA_VERSION = '10.0';
 const BASELINE_SCHEMA_VERSION = '11.0';
 const ADOPTION_SCHEMA_VERSION = '12.0';
 const WORKFLOW_SCHEMA_VERSION = '13.0';
 const AUTHORITY_SCHEMA_VERSION = '14.0';
+const SEMANTIC_SCHEMA_VERSION = '15.0';
 
 const MIGRATED_GAPS = Object.freeze([{
   id: 'legacy-rebaseline-required',
@@ -47,6 +48,8 @@ const REQUIRED_TABLES = Object.freeze([
   'event_consumers',
   'workflow_runs',
   'workflow_steps',
+  'decision_threads',
+  'decision_items',
 ]);
 
 function applyBaselineUpgrade(db, { legacyState = false } = {}) {
@@ -143,6 +146,10 @@ function applyChangeColumns(db) {
   changed = addColumnIfMissing(
     db, 'changes', columns, 'research_disposition_json', "TEXT NOT NULL DEFAULT '{}'",
   ) || changed;
+  changed = addColumnIfMissing(
+    db, 'changes', columns, 'alignment_thread_id',
+    'TEXT REFERENCES decision_threads(id) ON DELETE SET NULL',
+  ) || changed;
   return changed;
 }
 
@@ -402,7 +409,7 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
     const needsContextMigration = Boolean(
       fromVersion && ![
         CONTEXT_SCHEMA_VERSION, BASELINE_SCHEMA_VERSION, ADOPTION_SCHEMA_VERSION,
-        WORKFLOW_SCHEMA_VERSION, AUTHORITY_SCHEMA_VERSION, EXPECTED_VERSION,
+        WORKFLOW_SCHEMA_VERSION, AUTHORITY_SCHEMA_VERSION, SEMANTIC_SCHEMA_VERSION, EXPECTED_VERSION,
       ].includes(fromVersion)
         && !contextMigration,
     );
@@ -426,7 +433,7 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
     ).get();
     if (fromVersion && ![
       BASELINE_SCHEMA_VERSION, ADOPTION_SCHEMA_VERSION, WORKFLOW_SCHEMA_VERSION,
-      AUTHORITY_SCHEMA_VERSION, EXPECTED_VERSION,
+      AUTHORITY_SCHEMA_VERSION, SEMANTIC_SCHEMA_VERSION, EXPECTED_VERSION,
     ].includes(fromVersion)
       && !baselineMigration) {
       db.prepare(
@@ -530,17 +537,31 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
          VALUES (?, ?, 'forward', 'success', ?)`,
       ).run(
         fromVersion === AUTHORITY_SCHEMA_VERSION ? fromVersion : AUTHORITY_SCHEMA_VERSION,
-        EXPECTED_VERSION,
+        SEMANTIC_SCHEMA_VERSION,
         'Add typed research semantics, complete change contracts, verified learning application, and reconciliation provenance',
       );
     }
+    const dialogueMigration = db.prepare(
+      "SELECT 1 FROM migration_history WHERE to_version = '16.0' AND status = 'success' LIMIT 1",
+    ).get();
+    if (fromVersion && fromVersion !== EXPECTED_VERSION && !dialogueMigration) {
+      db.prepare(
+        `INSERT INTO migration_history
+          (from_version, to_version, direction, status, notes)
+         VALUES (?, ?, 'forward', 'success', ?)`,
+      ).run(
+        fromVersion === SEMANTIC_SCHEMA_VERSION ? fromVersion : SEMANTIC_SCHEMA_VERSION,
+        EXPECTED_VERSION,
+        'Add durable one-question decision dialogue, owner checkpoints, and workflow alignment gates',
+      );
+    }
     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,
-      'Typed research semantics, complete change contracts, verified learning application, and reconciliation provenance',
+      'Durable one-question decision dialogue, owner checkpoints, and workflow alignment gates',
     );
   })();
 }
@@ -568,7 +589,9 @@ function initStateDb(dbPath) {
     const existing = new Set(tableNames(db));
     const fromVersion = latestSchemaVersion(db);
     const legacyState = existing.size > 0
-      && ![WORKFLOW_SCHEMA_VERSION, AUTHORITY_SCHEMA_VERSION, EXPECTED_VERSION].includes(fromVersion);
+      && ![
+        WORKFLOW_SCHEMA_VERSION, AUTHORITY_SCHEMA_VERSION, SEMANTIC_SCHEMA_VERSION, EXPECTED_VERSION,
+      ].includes(fromVersion);
     backupPath = migrationBackup(db, dbPath, fromVersion, existing);
     applyCompatibleColumns(db);
     const missing = REQUIRED_TABLES.filter((t) => !existing.has(t));

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

@@ -8,6 +8,7 @@ const Ajv = require('ajv/dist/2020');
 const addFormats = require('ajv-formats');
 
 const ops = require('./state-ops.cjs');
+const decisionDialogue = require('./decision-dialogue.cjs');
 const testReportSchema = require('../../spec/schemas/test-report.v1.schema.json');
 const deliveryReportSchema = require('../../spec/schemas/delivery-report.v1.schema.json');
 
@@ -947,6 +948,13 @@ function recordWorkflowStep(db, input = {}, { rootDir = process.cwd() } = {}) {
         `cannot transition ${id}/${stepId} from ${stepRow.status} to ${input.status}`,
       );
     }
+    if (input.status === 'completed') {
+      decisionDialogue.assertDecisionGate(db, {
+        workflow_run_id: runRow.id,
+        change_id: runRow.change_id,
+        baseline_id: runRow.baseline_id,
+      }, { rootDir });
+    }
     const firstOpen = db.prepare(
       `SELECT step_id FROM workflow_steps
        WHERE run_id = ? AND required = 1 AND status NOT IN ('completed', 'skipped')
@@ -1929,6 +1937,11 @@ function completeWorkflow(db, input = {}, { rootDir = process.cwd() } = {}) {
     if (run.status !== 'ready') {
       throw new WorkflowStateError('WORKFLOW_NOT_READY', `workflow ${id} is ${run.status}`);
     }
+    decisionDialogue.assertDecisionGate(db, {
+      workflow_run_id: run.id,
+      change_id: run.change_id,
+      baseline_id: run.baseline_id,
+    }, { rootDir });
     if (run.artifact_health.status !== 'pass') {
       throw new WorkflowStateError('WORKFLOW_OUTPUT_STALE', 'workflow outputs are missing or stale', run.artifact_health);
     }

package/mcp-server/server.cjs

@@ -32,6 +32,7 @@ const baselines = require('./lib/baseline-workflow.cjs');
 const changes = require('./lib/change-workflow.cjs');
 const runtimeState = require('./lib/runtime-state.cjs');
 const workflows = require('./lib/workflow-state.cjs');
+const decisions = require('./lib/decision-dialogue.cjs');
 const doctor = require('./lib/doctor.cjs');
 const {
   readProjectBreadcrumb,
@@ -101,12 +102,25 @@ const WORKFLOW_TOOLS = Object.freeze([
   'workflow.complete',
 ]);
 
+const DECISION_TOOLS = Object.freeze([
+  'decision.thread_start',
+  'decision.get',
+  'decision.list',
+  'decision.open',
+  'decision.resolve',
+  'decision.delegate',
+  'decision.defer',
+  'decision.supersede',
+  'decision.checkpoint',
+]);
+
 const SYSTEM_TOOLS = Object.freeze([
   'system.doctor',
 ]);
 
 const REGISTERED_TOOLS = Object.freeze([
   ...TASK_TOOLS, ...SESSION_TOOLS, ...PLAN_TOOLS, ...BASELINE_TOOLS, ...CHANGE_TOOLS,
+  ...DECISION_TOOLS,
   ...WORKFLOW_TOOLS,
   ...SYSTEM_TOOLS,
 ]);
@@ -123,6 +137,8 @@ const MUTATING_TOOLS = new Set([
   'baseline.start', 'baseline.record', 'baseline.converge',
   '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',
   'workflow.start', 'workflow.step', 'workflow.complete',
 ]);
 
@@ -517,6 +533,44 @@ async function dispatchTool(name, input, db, ctx = {}) {
     case 'change.archive': {
       return changes.archiveChange(db, input, { rootDir: ctx.rootDir || process.cwd() });
     }
+    case 'decision.thread_start': {
+      return { thread: decisions.startDecisionThread(db, input) };
+    }
+    case 'decision.get': {
+      const thread = decisions.readDecisionThread(db, input.id);
+      if (!thread) {
+        const error = new Error(`decision thread ${input.id} not found`);
+        error.code = 'DECISION_THREAD_NOT_FOUND';
+        throw error;
+      }
+      return { thread };
+    }
+    case 'decision.list': {
+      const threads = decisions.listDecisionThreads(db, input || {});
+      return { threads, count: threads.length };
+    }
+    case 'decision.open': {
+      return { thread: decisions.openDecision(db, input) };
+    }
+    case 'decision.resolve': {
+      return { thread: decisions.resolveDecision(db, input) };
+    }
+    case 'decision.delegate': {
+      return { thread: decisions.delegateDecision(db, input) };
+    }
+    case 'decision.defer': {
+      return { thread: decisions.deferDecision(db, input) };
+    }
+    case 'decision.supersede': {
+      return { thread: decisions.supersedeDecision(db, input) };
+    }
+    case 'decision.checkpoint': {
+      return {
+        thread: decisions.checkpointDecisionThread(
+          db, input, { rootDir: ctx.rootDir || process.cwd() },
+        ),
+      };
+    }
     case 'workflow.start': {
       return {
         workflow: workflows.startWorkflow(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.15.0",
+  "version": "0.16.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.",
   "bin": {
     "ultra-builder-pro-cli": "bin/install.js",

package/skills/ultra-change/SKILL.md

@@ -3,27 +3,43 @@ name: ultra-change
 description: Open or resume one bounded post-baseline change and connect its intent, delta, task plan, fresh context, and convergence evidence. Use when handling daily feature work, fixes, redesigns, or incidents after an Ultra baseline exists.
 ---
 
-# Maintain one continuous change
+# Align, route, and maintain one continuous change
 
 Use Ultra MCP for lifecycle writes. Keep external memory and code-graph content in
-their providers; Ultra stores references only.
+their providers; Ultra stores references only. Read
+`../ultra-think/references/decision-dialogue.md` before forming a Change Contract.
 
-## Bind or create
+## Capture and align the outcome
 
-1. Read `system.doctor`, `baseline.get`, `change.list`, and `change.breadcrumb`.
-2. Resume the change matching the requested outcome. Require an id when several could
-   match; do not create a duplicate packet.
-3. New ordinary work requires a ready baseline. An incident on unhealthy authority
+1. Read `system.doctor`, `baseline.get`, `change.list`, `change.breadcrumb`, and active
+   decision threads. Resume the matching change or alignment thread; do not duplicate
+   either authority.
+2. New ordinary work requires a ready baseline. An incident on unhealthy authority
    requires an explicit `baseline_bypass` reason and approver. Never infer approval
    from urgency.
-4. Read `references/change-contract.md`. Persist the complete outcome, executable
+3. Inspect the current checkout before questioning the owner. Convert the request into
+   a working outcome, constraints, accepted facts, unknowns, and likely risk profile.
+   Resolve repository facts yourself.
+4. Start a baseline-bound decision thread when the Change Contract contains a material
+   owner choice. Normalize explicit decisions already present in the user's request
+   without asking them to repeat themselves. Otherwise open one earliest decision,
+   present it with a recommendation and durable effect, and STOP.
+5. Read `references/change-contract.md`. After all blocking decisions are resolved,
+   prepare one compact Change Contract checkpoint containing the outcome, executable
    acceptance, non-goals, public seams, recovery contract, unresolved decisions,
    documentation impact, profile rationale, material risk flags, and research
-   disposition. Do not derive these fields from a title or free-form intent later.
-5. Select `quick`, `standard`, `major`, or `incident` from current scope and risk.
+   disposition. The owner approves the contract once; do not ask for a second equivalent
+   confirmation.
+6. Select `quick`, `standard`, `major`, or `incident` from current scope and risk.
    Escalate a proposed quick change when its contract carries material risk or research.
-   Then call `change.create` or `change.update` and read the normalized record back.
-6. Resume or start the linked `change` workflow with `workflow.list`/`workflow.start`.
+   Write the compact approved alignment projection to
+   `.ultra/docs/alignment/<thread-id>.md`, confirm the decision checkpoint with that
+   artifact digest, then call `change.create` with `alignment_thread_id`. The create
+   operation materializes the authoritative Change Contract projections. Read the
+   normalized change and linked workflow back.
+
+Do not create a decision thread for a fact the agent can inspect or a reversible
+implementation detail already delegated by the accepted contract.
 
 ## Record the change workflow
 
@@ -67,3 +83,16 @@ When implementation reveals a stable missing invariant, use
 `change.learning_propose` and the approval/reject/apply transition. Unresolved learning
 blocks delivery. An approved application must bind the declared target anchor, its
 before and after digests, and current evidence before the proposal becomes `applied`.
+
+## Automatic routing contract
+
+Automatic means route, inspect, and recover automatically; it never means silently
+choose an owner decision. The normal route is:
+
+`capture → align → Change Contract checkpoint → change authority → bounded research when
+needed → plan candidate → plan decision review → plan approval → ultra-dev → test →
+review → deliver → baseline reconciliation`.
+
+A quick change may omit research and use one task only when evidence proves the request
+has no material unresolved decision or risk. An incident routes through reproduction,
+hypothesis discrimination, recovery choice, fix, and verification before convergence.

package/skills/ultra-deliver/SKILL.md

@@ -11,8 +11,9 @@ output digests.
 
 ## Bind current evidence
 
-1. Read `system.doctor`, `baseline.get`, `change.get`, `change.breadcrumb`, linked
-   tasks, and current test/review workflows and artifacts.
+1. Read `system.doctor`, `baseline.get`, `change.get`, `change.breadcrumb`, active
+   decision state, linked tasks, and current test/review workflows and artifacts. An
+   open decision, blocking deferral, or unconfirmed checkpoint prevents delivery.
 2. Resume or start a `deliver` workflow linked to the change and baseline.
 3. Require completed tasks, current context, a passing test report at full HEAD with a
    verified public seam, and current independent `spec_fidelity` and
@@ -61,6 +62,9 @@ user's request, complete it with exactly one `release_authorization` decision co
 determine compatibility impact, update version and
 changelog, rerun invalidated checks, create a non-force commit/tag, push, publish, and
 verify remote commit, tag, release, and registry version independently.
+If release authority is not already explicit, present that authorization as one compact
+question and stop. Do not bundle release permission with unrelated delivery choices or
+ask again when the current user request already grants the exact scope.
 
 Write `.ultra/reports/delivery/<workflow-id>.json` atomically using
 `ultra-delivery-report-v1`, with change/archive state, baseline id/status, full HEAD,
@@ -74,4 +78,7 @@ remote evidence agree for every authorized action. MCP derives the delivery summ
 from this report rather than a Prompt claim.
 
 Return workflow id, archive and baseline state, evidence digests, commit/release facts,
-recovery notes, residual risks, and one next route.
+recovery notes, residual risks, and one next route. Successful delivery routes to
+`ultra-status` for the final authoritative view or `ultra-change` for the next accepted
+outcome. Stale gates return to their owning workflow; a new owner choice routes to
+`ultra-think`; broken authority routes to `ultra-doctor`.

package/skills/ultra-dev/SKILL.md

@@ -11,8 +11,10 @@ recovery.
 
 ## Start or resume
 
-1. Read `system.doctor`, `change.breadcrumb`, `task.get`, workflow state, dependencies,
-   active sessions, Git HEAD, and worktree scope.
+1. Read `system.doctor`, `change.breadcrumb`, active decision state, `task.get`, workflow
+   state, dependencies, active sessions, Git HEAD, and worktree scope. If the
+   breadcrumb names an open decision or unconfirmed checkpoint, return to
+   `ultra-think` and do not edit code.
 2. Resume an existing `dev` workflow or call `workflow.start` with `change_id` and
    `task_id`. Startup fails when the DB-backed task execution contract is incomplete or
    owned by another change.
@@ -34,6 +36,10 @@ recovery.
 3. Keep application judgment and edits in the host. Do not write projections, raw DB,
    workflow output digests, or evidence state by hand.
 4. Refactor only inside the accepted slice while the focused signal stays green.
+   When implementation exposes a product, compatibility, security, cost, or recovery
+   choice outside the accepted task contract, preserve the evidence, open one decision
+   through the shared dialogue protocol, and stop. Do not convert implementation
+   convenience into an owner decision.
 5. Record `implement-slice`, then run focused, adjacent, static/build, public-seam,
    error, and recovery checks proportional to risk. Record exact evidence under
    `verify-slice`.
@@ -55,4 +61,6 @@ completed steps remain durable. Any code or contract change invalidates affected
 review, or context evidence.
 
 Return the task outcome, public seam, changed paths, exact checks, review results,
-workflow id, session state, residual risks, and one next route.
+workflow id, session state, residual risks, and one next route. Route another ready
+task to `ultra-dev`; route a fully implemented change to aggregate `ultra-test`;
+route a new owner choice to `ultra-think`; route broken authority to `ultra-doctor`.

package/skills/ultra-doctor/SKILL.md

@@ -11,6 +11,8 @@ Default to read-only diagnosis. Call `system.doctor` with repair disabled and in
 - baseline classification/readiness, research provenance, spec/evidence digests, gaps,
   and revision/worktree drift;
 - active, blocked, and ready workflow runs, current steps, blockers, and output health;
+- active decision threads, the sole current question, blocking deferrals, checkpoint
+  state, and current checkpoint artifact digests;
 - event/projection cursor lag and failed or interrupted projection jobs;
 - sessions, incidents, circuit state, active-change artifacts, and archive journals;
 - external provider ownership boundaries.
@@ -19,6 +21,9 @@ An expected blocked workflow is a workflow warning, not DB corruption. A stale o
 missing recorded output is an authority failure for that run. Doctor cannot invent
 evidence, complete a step, accept a failure, approve a baseline, or change product
 scope.
+An awaiting owner decision is also a recoverable warning, not corruption. A missing or
+changed artifact bound to a current confirmed checkpoint is an authority failure;
+doctor may report it but cannot reconstruct the decision or approval.
 
 ## Route failures
 
@@ -29,6 +34,11 @@ scope.
 - Orphan session: reconcile the recorded lease; do not kill unrelated processes.
 - Missing change artifact: recover from version control, backup, or explicit owner
   decision rather than silently recreating it.
+- Open decision: resume its exact question through `ultra-think`; checkpoint-ready
+  state requires owner confirmation, not mechanical repair.
+- Stale decision artifact: restore or update the artifact from accepted authority,
+  then reprepare and reconfirm the same checkpoint through `ultra-think`; do not
+  rewrite the owner decision or mark the failure healthy mechanically.
 - Corrupt SQLite: preserve DB/WAL/SHM and obtain a restore-or-rebaseline decision.
 
 ## Explicit project repair

package/skills/ultra-init/SKILL.md

@@ -8,6 +8,8 @@ description: Initialize a new repository, adopt an existing codebase, or migrate
 Use host reasoning to inspect repository evidence and prepare baseline content. Use
 Ultra MCP for classification records, schema migration, workflow state, evidence
 digests, approval, and convergence. Never treat generated Markdown or JSON as state.
+Read `../ultra-think/references/decision-dialogue.md` before asking about repository
+scope, replacement authority, or another load-bearing owner choice.
 
 ## Classify without guessing product scope
 
@@ -29,6 +31,8 @@ ready. Classification never chooses an MVP, reduced scope, or delivery posture.
 Report the detected project type, technology signals, verification commands, and
 monorepo roots. Pass an explicit `project_type` or `stack` only when repository evidence
 or an owner decision supports the override; MCP preserves both detection and selection.
+Inspect first and ask only one unresolved scope or replacement decision at a time. Do
+not request a complete project questionnaire during initialization.
 
 ## Resume safely
 
@@ -74,7 +78,8 @@ Continue through `ultra-research`. Research completion records output digests; t
 specs, source and runtime evidence, actual verification, unknowns, gaps,
 classification, and external provider metadata references.
 
-Call `baseline.converge` only after explicit owner approval. The MCP rejects missing
+Call `baseline.converge` only after the compact research checkpoint receives explicit
+owner approval; do not ask for the same approval twice. The MCP rejects missing
 research, missing discovery/product/architecture refs, stale evidence, revision or
 worktree drift, unaccepted known failures, blocking unknowns, and blocking gaps. A
 successful convergence atomically marks the baseline ready and completes the init run.

package/skills/ultra-plan/SKILL.md

@@ -3,10 +3,12 @@ name: ultra-plan
 description: Convert a ready Ultra baseline or approved active-change delta into dependency-valid, DB-backed execution contracts and fresh-context vertical slices. Use when accepted requirements are ready for implementation planning or an existing plan must be resumed and verified.
 ---
 
-# Persist an executable plan
+# Review and persist an executable plan
 
 Use host reasoning for decomposition, tradeoffs, and approval. Use Ultra MCP for
-workflow position, task contracts, graph validation, projection, and recovery.
+workflow position, decision authority, task contracts, graph validation, projection,
+and recovery. Read `../ultra-think/references/decision-dialogue.md` before presenting a
+planning choice.
 
 ## Bind authority
 
@@ -21,7 +23,24 @@ workflow position, task contracts, graph validation, projection, and recovery.
 5. Resume the active `plan` workflow from `workflow.list`, or call `workflow.start`
    with its `baseline_id`, `change_id`, subject, and source refs.
 
-## Plan through the durable steps
+## Build a candidate before writing authority
+
+Inspect requirements, source, consumers, state, tests, deployment, and recovery before
+drafting slices. Build the candidate plan privately. Separate evidence-backed design
+detail from choices that change accepted scope, public behavior, compatibility, cost,
+risk, delivery semantics, or recovery.
+
+When a material planning decision remains, start or resume a decision thread bound to
+the plan workflow. Present exactly one decision with the recommendation, credible
+alternatives, and the tasks or contracts it changes, then STOP. The plan document is
+the result of this review; never use a large plan dump as a substitute for interaction.
+
+After all blocking choices are resolved, prepare one checkpoint. Present the compact
+topology, public seams, recovery, and material tradeoffs for approval. After approval,
+write the evidence-linked `plan.md`, confirm the checkpoint with its digest, and reuse
+that same approval for the durable `approve-plan` and workflow completion gates.
+
+## Record the durable steps
 
 Record each completed step with `workflow.step`:
 
@@ -37,11 +56,12 @@ Record each completed step with `workflow.step`:
    documentation, migration, observability, and recovery in the owning slice.
 6. `validate-dependencies`: validate ownership, missing dependencies, cycles, conflict
    surfaces, and meaningful integration checkpoints.
-7. `approve-plan`: persist owner approval when the plan makes a material decision.
+7. `approve-plan`: persist the already obtained checkpoint approval; do not ask again.
 
 ## Persist complete task contracts
 
-Call `task.create` for each approved task with:
+Only after the plan checkpoint is confirmed, call `task.create` for each approved task
+with:
 
 - one observable `outcome` and stable `trace_to`;
 - `slice_kind`, `public_seam`, and exact `verification_command`;

package/skills/ultra-research/SKILL.md

@@ -3,11 +3,12 @@ name: ultra-research
 description: Establish or extend an evidence-backed Ultra product and architecture baseline through the complete semantic research workflow, with resumable step state and traceable outputs. Use when initialization routes to research, baseline evidence is incomplete, or the owner explicitly requests bounded research for an active change.
 ---
 
-# Establish research authority
+# Establish research authority without overwhelming the owner
 
-Use host reasoning for evidence gathering, product judgment, questions, and artifact
-content. Use Ultra MCP for run selection, state transitions, output digests, blockers,
-and baseline convergence. Never ask MCP to generate research content.
+Use host reasoning to discover facts and synthesize artifacts. Use Ultra MCP for run
+position, decision authority, output digests, blockers, and convergence. Read
+`../ultra-think/references/decision-dialogue.md` before asking any owner question.
+Never ask MCP to generate research content.
 
 ## Bind the run
 
@@ -25,7 +26,7 @@ Never infer an MVP, reduced product posture, skipped step, or release phase. Ful
 adoption modes execute all seventeen semantic steps. A custom run records every
 excluded step and its selection reason in DB.
 
-## Execute one recoverable step at a time
+## Preserve complete semantic coverage
 
 Read only the reference matching `workflow.next_step.step_id`:
 
@@ -49,22 +50,32 @@ Read only the reference matching `workflow.next_step.step_id`:
 | `41-quality-risks` | `references/41-quality-risks.md` |
 | `99-synthesis` | `references/99-synthesis.md` |
 
-For each selected step:
+The seventeen steps are an internal completeness contract, not a questionnaire or the
+default user interface. For each selected step:
 
-1. Inspect current repository and specification evidence before asking the owner to
-   repeat known facts. Browse only for unstable or external claims, using primary
-   sources where possible.
-2. Separate `Observed`, `Verified`, `Decided`, and `Unknown`. Ask one concise question
-   only when the answer changes scope, product intent, security, cost, or another
-   load-bearing decision.
-3. Update the relevant baseline specification or active change research artifact.
-   Preserve citations, decisions, drift, and unresolved gaps without duplicating prose.
-4. Write one immutable step report at
+1. Read only its reference and inspect repository, specification, runtime, tests, and
+   current primary-source evidence. Do not ask the owner to repeat observable facts.
+2. Separate `Observed`, `Verified`, `Decided`, and `Unknown`. Resolve evidence-answerable
+   unknowns autonomously and record evidence-backed `not_applicable` results.
+3. If a load-bearing owner decision remains, start or resume one decision thread bound
+   to this research workflow. Open the earliest dependent decision, present only that
+   question, and STOP. Do not update specifications or complete the workflow step while
+   its checkpoint is unconfirmed.
+4. After a coherent decision cluster, prepare one checkpoint. Present the compact
+   shared understanding and affected specifications, obtain approval, and apply the
+   accepted decisions.
+5. Update only the relevant baseline specification or active-change research artifact.
+   Preserve evidence, decisions, drift, and unknowns without copying conversation text.
+   Write the accepted cluster to the stable
+   `.ultra/docs/decisions/<thread-id>.md` projection and confirm its checkpoint with
+   that digest. Do not bind an intermediate shared specification that later research
+   steps are expected to extend.
+6. Write one immutable step report at
    `.ultra/docs/research/<workflow-id>/<step-id>.md`. It must have a title and the
    sections `Evidence`, `Specification updates`, and `Decisions and unknowns`. Link
    specification anchors and external sources; do not copy transcripts or provider
    payloads.
-5. Call `workflow.step` with `completed`, bounded evidence references, that step report
+7. Call `workflow.step` with `completed`, bounded evidence references, that step report
    as `research-step-report`, material decisions, and one or more `semantic_records`.
    Each record has a stable `id`, the step-specific `kind` and `attributes` named in
    its reference, a status (`observed`, `verified`, `decided`, `accepted`, `unknown`,
@@ -72,11 +83,11 @@ For each selected step:
    project-relative `source_ref` using `path#anchor`. Use the immutable step report as
    the source when later edits could change a shared specification. MCP verifies the
    anchor and stores its digest; `not_applicable` requires an evidence-backed rationale.
-6. For `99-synthesis` in `full` or `adoption` mode, also bind the current
+8. For `99-synthesis` in `full` or `adoption` mode, also bind the current
    `discovery.md`, `product.md`, `architecture.md`, and `research-distillate.md` as
    outputs. This freezes the exact researched baseline without making the reports a
    second specification authority.
-7. If evidence or owner authority is missing, call `workflow.step` with `blocked` and
+9. If evidence or owner authority is missing, call `workflow.step` with `blocked` and
    specific blocker codes. Resume that same step after resolution; never skip a
    required step to obtain a ready state.
 
@@ -92,11 +103,15 @@ and results; unknowns; the complete gap ledger; classification; and external pro
 metadata references. Do not store prompts, transcripts, memory, or graph content.
 
 Present the recorded revision, worktree snapshot, known failures, blockers, and gaps.
-Only after explicit owner approval call `baseline.converge`. Accept known-red or a
+Only after explicit owner approval call `baseline.converge`. Reuse the final research
+checkpoint approval when it names this exact recorded revision, worktree snapshot,
+known failures, blockers, and gaps; do not ask for an equivalent approval again. If
+that snapshot changed, prepare one refreshed checkpoint instead. Accept known-red or a
 dirty worktree only when that exact snapshot was approved. Convergence must verify the
 completed full/adoption research run and current output digests.
 
-Return the workflow id, all seventeen step-report paths for full/adoption research,
-the four synthesis artifacts, baseline status, open gaps, approval state, and one exact
-next route. A ready initial baseline routes to `ultra-change`; bounded change research
-returns to its change breadcrumb and then `ultra-plan` when the research gate is ready.
+Return a compact checkpoint: workflow id, completed/selected semantic coverage,
+current decision or blocker, baseline state, open gaps, approval state, and one route.
+Do not print all seventeen report paths unless requested; they remain discoverable
+through workflow state. A ready initial baseline routes to `ultra-change`; bounded
+change research returns to its breadcrumb and then `ultra-plan` when ready.