ultra-builder-pro-cli 0.15.0 → 0.17.0

package/orchestrator/session-runner.cjs

@@ -1,11 +1,12 @@
 'use strict';
 
-// Phase 4.5.1 — Session 标准单元 runner.
-// Session = new process + independent git worktree + state.db sessions-table
-// lease/heartbeat (D20 + D32 — no .ultra/sessions/<sid>/lease.json file).
+// Phase 4.5.1 — standard session unit runner.
+// Session = one task/runtime lease + independent git worktree + state.db
+// lease/heartbeat. A caller may attach a worker process or let the active host
+// operate directly in the returned worktree.
 //
-// This module is the execution layer. MCP session.* tools record state,
-// orchestrator runs the actual git worktree + child_process work.
+// This module is the single session/worktree execution layer shared by MCP
+// session.* tools and the optional orchestrator child-process path.
 // Callers share a single open state-db connection (WAL supports multi-writer).
 
 const fs = require('node:fs');
@@ -14,8 +15,18 @@ const { spawn, execFileSync } = require('node:child_process');
 const { randomUUID } = require('node:crypto');
 
 const ops = require('../mcp-server/lib/state-ops.cjs');
+const workflows = require('../mcp-server/lib/workflow-state.cjs');
 const skillMiner = require('./skill-miner.cjs');
 
+const EXPECTED_EXECUTION_GATE_CODES = new Set([
+  'TASK_EXECUTION_CONTRACT_INCOMPLETE',
+  'WORKFLOW_TASK_NOT_EXECUTABLE',
+  'TASK_DEPENDENCIES_INCOMPLETE',
+  'WORKFLOW_PLAN_NOT_COMPLETED',
+  'WORKFLOW_PLAN_TASK_SET_STALE',
+  'WORKFLOW_PLAN_TASK_CONTRACT_STALE',
+]);
+
 class SessionRunnerError extends Error {
   constructor(code, message, { cause } = {}) {
     super(message);
@@ -25,6 +36,10 @@ class SessionRunnerError extends Error {
   }
 }
 
+function isExpectedExecutionGate(error) {
+  return Boolean(error && EXPECTED_EXECUTION_GATE_CODES.has(error.code));
+}
+
 function gitWorktreeAdd(repoRoot, worktreePath, ref = 'HEAD') {
   fs.mkdirSync(path.dirname(worktreePath), { recursive: true });
   try {
@@ -49,10 +64,240 @@ function gitWorktreeRemove(repoRoot, worktreePath) {
   }
 }
 
+function authorityLinkIsIgnored(worktreePath) {
+  try {
+    execFileSync(
+      'git',
+      ['check-ignore', '--quiet', '--no-index', '--', '.ultra'],
+      { cwd: worktreePath, stdio: 'ignore' },
+    );
+    return true;
+  } catch (error) {
+    if (error.status === 1) return false;
+    throw new SessionRunnerError(
+      'WORKTREE_AUTHORITY_LINK_FAILED',
+      `cannot verify the worktree Ultra ignore rule: ${error.message}`,
+      { cause: error },
+    );
+  }
+}
+
+function ensureAuthorityLinkIgnored(worktreePath) {
+  if (authorityLinkIsIgnored(worktreePath)) return { changed: false, path: null };
+  let output;
+  try {
+    output = execFileSync('git', ['rev-parse', '--git-path', 'info/exclude'], {
+      cwd: worktreePath,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+  } catch (error) {
+    throw new SessionRunnerError(
+      'WORKTREE_AUTHORITY_LINK_FAILED',
+      `cannot locate the repository-local exclude file: ${error.message}`,
+      { cause: error },
+    );
+  }
+  const excludePath = path.isAbsolute(output)
+    ? output
+    : path.resolve(worktreePath, output);
+  let stat = null;
+  try { stat = fs.lstatSync(excludePath); }
+  catch (error) {
+    if (error.code !== 'ENOENT') {
+      throw new SessionRunnerError(
+        'WORKTREE_AUTHORITY_LINK_FAILED',
+        `cannot inspect ${excludePath}: ${error.message}`,
+        { cause: error },
+      );
+    }
+  }
+  if (stat && (stat.isSymbolicLink() || !stat.isFile())) {
+    throw new SessionRunnerError(
+      'WORKTREE_AUTHORITY_NOT_IGNORED',
+      `refusing to update unsafe Git exclude path: ${excludePath}`,
+    );
+  }
+  const before = stat ? fs.readFileSync(excludePath, 'utf8') : '';
+  const prefix = before && !before.endsWith('\n') ? `${before}\n` : before;
+  const separator = prefix && !prefix.endsWith('\n\n') ? '\n' : '';
+  try {
+    fs.mkdirSync(path.dirname(excludePath), { recursive: true });
+    fs.writeFileSync(
+      excludePath,
+      `${prefix}${separator}# Ultra Builder Pro session authority\n.ultra\n`,
+    );
+    if (!authorityLinkIsIgnored(worktreePath)) {
+      throw new Error('Git still does not ignore the session authority link');
+    }
+  } catch (error) {
+    try {
+      if (stat) fs.writeFileSync(excludePath, before);
+      else fs.rmSync(excludePath, { force: true });
+    } catch { /* best effort */ }
+    throw new SessionRunnerError(
+      'WORKTREE_AUTHORITY_NOT_IGNORED',
+      `cannot establish a safe local ignore rule for .ultra: ${error.message}`,
+      { cause: error },
+    );
+  }
+  return { changed: true, path: excludePath };
+}
+
+function linkAuthorityIntoWorktree(repoRoot, worktreePath) {
+  const authorityDir = path.resolve(repoRoot, '.ultra');
+  const stateDbPath = path.join(authorityDir, 'state.db');
+  const linkPath = path.join(worktreePath, '.ultra');
+  if (!fs.existsSync(stateDbPath)) {
+    throw new SessionRunnerError(
+      'WORKTREE_AUTHORITY_MISSING',
+      `central Ultra authority is missing at ${stateDbPath}`,
+    );
+  }
+  ensureAuthorityLinkIgnored(worktreePath);
+  try {
+    if (fs.existsSync(linkPath) || fs.lstatSync(linkPath, { throwIfNoEntry: false })) {
+      throw new SessionRunnerError(
+        'WORKTREE_AUTHORITY_CONFLICT',
+        `worktree already contains an .ultra entry at ${linkPath}`,
+      );
+    }
+    fs.symlinkSync(
+      process.platform === 'win32' ? authorityDir : path.relative(worktreePath, authorityDir),
+      linkPath,
+      process.platform === 'win32' ? 'junction' : 'dir',
+    );
+    if (fs.realpathSync(path.join(linkPath, 'state.db')) !== fs.realpathSync(stateDbPath)) {
+      throw new Error('linked state.db does not resolve to the central authority');
+    }
+    return { authorityDir, stateDbPath, linkPath };
+  } catch (error) {
+    throw error instanceof SessionRunnerError ? error : new SessionRunnerError(
+      'WORKTREE_AUTHORITY_LINK_FAILED',
+      `cannot link the worktree to central Ultra authority: ${error.message}`,
+      { cause: error },
+    );
+  }
+}
+
+function worktreeRemovalBlocker(repoRoot, worktreePath) {
+  if (!fs.existsSync(worktreePath)) return null;
+  try {
+    const status = execFileSync('git', ['status', '--porcelain=v1'], {
+      cwd: worktreePath, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+    if (status) return 'worktree contains uncommitted changes';
+    const sessionHead = execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: worktreePath, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+    const repositoryHead = execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+    execFileSync(
+      'git', ['merge-base', '--is-ancestor', sessionHead, repositoryHead],
+      { cwd: repoRoot, stdio: ['ignore', 'ignore', 'ignore'] },
+    );
+    return null;
+  } catch (error) {
+    if (error.status === 1) return 'worktree commit has not been integrated into the current checkout';
+    return `worktree integration could not be verified: ${error.message}`;
+  }
+}
+
+function changeTaskIntegrationBlocker(db, task, worktreePath) {
+  if (!task?.change_id) return null;
+  let worktreeHead;
+  try {
+    worktreeHead = execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: worktreePath,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+  } catch (error) {
+    return {
+      code: 'WORKTREE_HEAD_UNAVAILABLE',
+      message: `cannot verify task worktree HEAD: ${error.message}`,
+    };
+  }
+  if (!task.completion_commit || task.completion_commit !== worktreeHead) {
+    return {
+      code: 'TASK_COMPLETION_COMMIT_STALE',
+      message: `task ${task.id} completion commit does not match worktree HEAD`,
+    };
+  }
+  const dev = workflows.listWorkflows(
+    db,
+    {
+      kind: 'dev',
+      status: 'ready',
+      change_id: task.change_id,
+      task_id: task.id,
+      limit: 1,
+    },
+    { rootDir: worktreePath },
+  )[0];
+  if (!dev || dev.artifact_health.status !== 'pass') {
+    return {
+      code: 'DEV_WORKFLOW_NOT_READY',
+      message: `task ${task.id} has no current ready dev workflow`,
+    };
+  }
+  try {
+    workflows.assertApprovedReview(db, task.change_id, task.id, worktreePath);
+  } catch (error) {
+    return {
+      code: error.code || 'TASK_REVIEW_NOT_CURRENT',
+      message: error.message,
+    };
+  }
+  return null;
+}
+
+function resolveWorktreeBase(repoRoot, requestedBase) {
+  const managedBase = path.resolve(repoRoot, '.ultra', 'worktrees');
+  const resolved = requestedBase
+    ? path.resolve(repoRoot, requestedBase)
+    : managedBase;
+  if (resolved !== managedBase && !resolved.startsWith(`${managedBase}${path.sep}`)) {
+    throw new SessionRunnerError(
+      'WORKTREE_SCOPE_INVALID',
+      `worktree_base must stay inside ${managedBase}`,
+    );
+  }
+  return resolved;
+}
+
 function mintSessionId() {
   return `sess-${randomUUID().slice(0, 8)}`;
 }
 
+function assertSessionTaskReady(db, repoRoot, taskId) {
+  const task = ops.readTask(db, taskId);
+  if (!task) return null; // admissionCheck reports the canonical TASK_NOT_FOUND error.
+  // Unbound rows remain readable for legacy recovery, but every current
+  // change-owned task must pass the same plan gate as a dev workflow.
+  if (!task.change_id) return task;
+  ops.assertTaskExecutionContract(task);
+  if (!['pending', 'in_progress', 'blocked'].includes(task.status) || task.stale) {
+    throw new workflows.WorkflowStateError(
+      'WORKFLOW_TASK_NOT_EXECUTABLE',
+      `task ${task.id} is not executable from status ${task.status}${task.stale ? ' (stale)' : ''}`,
+    );
+  }
+  const incompleteDependencies = (task.deps || []).filter((id) => {
+    const dependency = ops.readTask(db, id);
+    return !dependency || !['completed', 'expanded'].includes(dependency.status);
+  });
+  if (incompleteDependencies.length > 0) {
+    throw new workflows.WorkflowStateError(
+      'TASK_DEPENDENCIES_INCOMPLETE',
+      `task ${task.id} has incomplete dependencies: ${incompleteDependencies.join(', ')}`,
+    );
+  }
+  workflows.assertCurrentPlan(db, task.change_id, repoRoot);
+  return task;
+}
+
 function spawnSession({
   db,
   repoRoot,
@@ -64,12 +309,14 @@ function spawnSession({
   env = {},
   stdio = 'ignore',
   worktreeRef = 'HEAD',
+  worktree_base = null,
   lease_seconds = 1800,
 }) {
   if (!db) throw new SessionRunnerError('VALIDATION_ERROR', 'db handle required');
   if (!repoRoot) throw new SessionRunnerError('VALIDATION_ERROR', 'repoRoot required');
   if (!task_id) throw new SessionRunnerError('VALIDATION_ERROR', 'task_id required');
   if (!runtime) throw new SessionRunnerError('VALIDATION_ERROR', 'runtime required');
+  const worktreeBase = resolveWorktreeBase(repoRoot, worktree_base);
 
   // 1. Admission check
   const verdict = ops.admissionCheck(db, task_id);
@@ -82,6 +329,9 @@ function spawnSession({
     err.verdict = verdict;
     throw err;
   }
+  // Validate workflow authority before takeover can terminate the prior worker
+  // or any filesystem mutation creates a new worktree.
+  assertSessionTaskReady(db, repoRoot, task_id);
   if (!verdict.can_spawn && !takeover) {
     const err = new SessionRunnerError(
       'ADMISSION_DENIED',
@@ -91,31 +341,53 @@ function spawnSession({
     throw err;
   }
   if (!verdict.can_spawn && takeover && verdict.conflict) {
+    const priorSession = ops.readSession(db, verdict.conflict.sid);
+    if (priorSession?.pid) {
+      try { process.kill(priorSession.pid, 'SIGTERM'); }
+      catch (error) {
+        if (error.code !== 'ESRCH') {
+          throw new SessionRunnerError(
+            'TAKEOVER_FAILED',
+            `cannot terminate prior session ${verdict.conflict.sid}: ${error.message}`,
+          );
+        }
+      }
+    }
     ops.updateSession(db, verdict.conflict.sid, { status: 'crashed' });
   }
 
   // 2. Mint sid + paths
   const sid = mintSessionId();
-  const worktree_path = path.join(repoRoot, '.ultra', 'worktrees', sid);
+  const worktree_path = path.join(worktreeBase, sid);
   const artifact_dir = path.join(repoRoot, '.ultra', 'sessions', sid);
 
   // 3. Git worktree (throws WORKTREE_FAILED on failure)
   gitWorktreeAdd(repoRoot, worktree_path, worktreeRef);
-  fs.mkdirSync(artifact_dir, { recursive: true });
+  let authority;
+  try {
+    authority = linkAuthorityIntoWorktree(repoRoot, worktree_path);
+    fs.mkdirSync(artifact_dir, { recursive: true });
+  } catch (error) {
+    gitWorktreeRemove(repoRoot, worktree_path);
+    throw error;
+  }
 
-  // 4. Spawn child process (optional — caller may want a record-only session)
+  // 4. Spawn child process (optional — the active host may consume the worktree)
   let proc = null;
   if (command) {
     proc = spawn(command, args, {
       cwd: worktree_path,
       env: {
         ...process.env,
+        ...env,
         UBP_SESSION_ID: sid,
         UBP_TASK_ID: task_id,
         UBP_RUNTIME: runtime,
         UBP_WORKTREE: worktree_path,
         UBP_ARTIFACT_DIR: artifact_dir,
-        ...env,
+        UBP_DB_PATH: authority.stateDbPath,
+        UBP_ROOT_DIR: worktree_path,
+        UBP_AUTHORITY_ROOT: repoRoot,
       },
       stdio,
       detached: false,
@@ -138,6 +410,7 @@ function spawnSession({
     // state.db insert failed — roll back worktree + child
     if (proc && !proc.killed) { try { proc.kill('SIGTERM'); } catch (_) { /* ignore */ } }
     gitWorktreeRemove(repoRoot, worktree_path);
+    try { fs.rmSync(artifact_dir, { recursive: true, force: true }); } catch (_) { /* ignore */ }
     throw err;
   }
 
@@ -145,6 +418,7 @@ function spawnSession({
     sid,
     worktree_path,
     artifact_dir,
+    authority_db_path: authority.stateDbPath,
     lease_expires_at: session.lease_expires_at,
     pid: proc ? proc.pid : null,
     process: proc,
@@ -157,7 +431,7 @@ function closeSession({
   sid,
 }, {
   status = 'completed',
-  remove_worktree = true,
+  remove_worktree = false,
   kill_signal = 'SIGTERM',
   mineSkill = false,
   skillsRoot = null,
@@ -169,13 +443,21 @@ function closeSession({
   if (!session) {
     throw new SessionRunnerError('SESSION_NOT_FOUND', `session ${sid} not found`);
   }
+  if (remove_worktree && !autoMerge) {
+    const blocker = worktreeRemovalBlocker(repoRoot, session.worktree_path);
+    if (blocker) {
+      throw new SessionRunnerError(
+        'WORKTREE_NOT_INTEGRATED',
+        `refusing to remove ${session.worktree_path}: ${blocker}`,
+      );
+    }
+  }
   if (session.pid) {
     try { process.kill(session.pid, kill_signal); }
     catch (_) { /* already dead */ }
   }
-  ops.updateSession(db, sid, { status });
-  // Phase 7.3 — opt-in skill mining (same lifecycle moment; runs after
-  // status flip so task_completed events are visible).
+  // Phase 7.3 — opt-in skill mining reads durable task/session events. It
+  // cannot advance task or workflow state.
   if (mineSkill && skillsRoot) {
     try { skillMiner.mineSession(db, { sid, skillsRoot }); }
     catch (err) { process.stderr.write(`skill-miner error: ${err.message}\n`); }
@@ -185,21 +467,55 @@ function closeSession({
   let mergeResult;
   let effectiveRemove = remove_worktree;
   if (autoMerge && status === 'completed' && repoRoot && session.worktree_path) {
-    const autoMergeMod = require('./auto-merge.cjs');
-    mergeResult = autoMergeMod.autoMerge({
-      repoRoot,
-      worktreePath: session.worktree_path,
-      baseBranch: mergeBaseBranch,
-      sid,
-      task_id: session.task_id,
-      db,
-    });
-    if (mergeResult.reason === 'conflict') effectiveRemove = false;
+    const task = session.task_id ? ops.readTask(db, session.task_id) : null;
+    if (!task || task.status !== 'completed') {
+      mergeResult = {
+        merged: false,
+        reason: 'task_not_completed',
+        task_status: task?.status || null,
+      };
+      effectiveRemove = false;
+    } else {
+      const integrationBlocker = changeTaskIntegrationBlocker(
+        db,
+        task,
+        session.worktree_path,
+      );
+      if (integrationBlocker) {
+        mergeResult = {
+          merged: false,
+          reason: 'workflow_gates_open',
+          blocker: integrationBlocker.code,
+          message: integrationBlocker.message,
+        };
+        effectiveRemove = false;
+      } else {
+        const autoMergeMod = require('./auto-merge.cjs');
+        mergeResult = autoMergeMod.autoMerge({
+          repoRoot,
+          worktreePath: session.worktree_path,
+          baseBranch: mergeBaseBranch,
+          sid,
+          task_id: session.task_id,
+          db,
+        });
+        effectiveRemove = Boolean(
+          mergeResult.merged || mergeResult.reason === 'no_changes',
+        );
+      }
+    }
   }
+  ops.updateSession(db, sid, { status });
   if (effectiveRemove && repoRoot && session.worktree_path) {
     gitWorktreeRemove(repoRoot, session.worktree_path);
   }
-  const out = { sid, status };
+  const out = {
+    sid,
+    status,
+    worktree_preserved: Boolean(
+      session.worktree_path && fs.existsSync(session.worktree_path),
+    ),
+  };
   if (mergeResult) out.merge = mergeResult;
   return out;
 }
@@ -216,9 +532,22 @@ function attachHeartbeat(db, sid, { intervalMs = 30000 } = {}) {
 
 module.exports = {
   SessionRunnerError,
+  EXPECTED_EXECUTION_GATE_CODES,
+  isExpectedExecutionGate,
   spawnSession,
   closeSession,
   attachHeartbeat,
+  assertSessionTaskReady,
   // exposed for tests
-  _internal: { gitWorktreeAdd, gitWorktreeRemove, mintSessionId },
+  _internal: {
+    gitWorktreeAdd,
+    gitWorktreeRemove,
+    mintSessionId,
+    authorityLinkIsIgnored,
+    ensureAuthorityLinkIgnored,
+    linkAuthorityIntoWorktree,
+    worktreeRemovalBlocker,
+    changeTaskIntegrationBlocker,
+    resolveWorktreeBase,
+  },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.15.0",
+  "version": "0.17.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",
@@ -50,6 +50,7 @@
     "docs/ROADMAP.md",
     "docs/ARCHITECTURE.md",
     "docs/WORKFLOW-LIFECYCLE.md",
+    "docs/LEGACY-CLI-CROSSWALK.md",
     "docs/AGENT-CONTEXT.md",
     "docs/SKILL-AUTHORING.md",
     "docs/COMMIT-HASH-BACKFILL.md",

package/skills/ultra-change/SKILL.md

@@ -1,69 +1,73 @@
 ---
 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.
+description: Capture or revise one bounded feature, fix, redesign, or incident contract against a ready Ultra baseline. Use when post-baseline work needs accepted intent before research, planning, or implementation.
 ---
 
-# Maintain one continuous change
-
-Use Ultra MCP for lifecycle writes. Keep external memory and code-graph content in
-their providers; Ultra stores references only.
-
-## Bind or create
-
-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
-   requires an explicit `baseline_bypass` reason and approver. Never infer approval
-   from urgency.
-4. Read `references/change-contract.md`. Persist the complete 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.
-   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`.
-
-## Record the change workflow
-
-Use `workflow.step` as evidence becomes durable:
-
-- `bind-baseline`: current baseline id, revision, branch, and worktree evidence;
-- `classify-change`: kind and rationale;
-- `record-intent`: intent artifact, acceptance, scope, and resolved docs impact;
-- `plan-change`: completed plan workflow and authoritative task ids;
-- `compile-context`: current task-bound `change.context` manifest and digest;
-- `verify-readiness`: ready breadcrumb with one executable next action.
-
-Standard and major changes keep deltas under
-`.ultra/changes/active/<id>/delta/` and an evidence-linked `plan.md`. Deltas describe
-differences from the baseline; they are not a second baseline. Incidents maintain the
-structured diagnosis artifact and recovery evidence.
-
-When `research_disposition.status` is `bounded` or `required`, run `ultra-research`
-with the exact recorded mode and selected steps before planning. Planning is blocked
-until that change-bound research run is complete, current, and selection-equivalent.
-Use `none` only when the Change Contract already has sufficient evidence.
-
-Use `ultra-plan` to create complete DB-backed task contracts. Recompile
-`change.context` after any task, HEAD, specification, or decision change. The task's DB
-contract is authoritative; Prompt input may not override its seam or verification.
-Required missing or stale refs block. Budget warnings guide narrower context but never
-justify dropping necessary evidence or refusing legitimate work.
-
-An ordinary active change remains executable only while its durable `bind-baseline`
-evidence still names the current approved-ready baseline. HEAD, worktree, specification,
-or source-evidence drift created after that binding is advisory until delivery
-reconciliation. Adoption/migration state, missing approval or evidence, blocking gaps,
-and any other structural baseline failure block tasks, context, and later stages. Only
-the recorded incident break-glass authority can bypass that gate.
-
-Call `workflow.complete` only after all change workflow steps are current. Return the
-change id, kind, task set, context digest, blockers or warnings, workflow state, and the
-breadcrumb's one route.
-
-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`.
+# Capture accepted change intent
+
+Change is the durable unit that connects later research, plan, implementation,
+verification, review, and baseline reconciliation. Capturing a change does not start
+those workflows or compile execution context.
+
+Read `../ultra-think/references/decision-dialogue.md` before asking a material question.
+
+## Inspect and align
+
+1. Read `system.doctor`, `baseline.get`, active changes, decisions, and
+   `change.breadcrumb`.
+2. Resume an existing change that matches the request. Do not duplicate authority.
+3. Ordinary work requires a healthy ready baseline. An incident may use only an
+   explicit `baseline_bypass` reason and approver; urgency is not approval.
+4. Inspect the checkout and accepted baseline before asking the user. Resolve code and
+   runtime facts yourself.
+5. Convert the request into a Change Contract:
+   - observable outcome and executable acceptance;
+   - non-goals and public seams;
+   - recovery strategy and verification;
+   - unresolved material decisions;
+   - documentation impact;
+   - 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.
+
+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.
+
+## Persist the contract
+
+When a durable alignment checkpoint is necessary, bind it to a compact artifact and
+pass its id as `alignment_thread_id`. Do not require a checkpoint for a complete,
+unambiguous request that already provides current authority.
+
+Call `change.create`. It records and completes exactly:
+
+1. `bind-baseline`
+2. `classify-change`
+3. `record-intent`
+
+The returned change workflow must be `completed`; research, plan, context, dev, test,
+review, and deliver remain independent capabilities. Standard and major changes may
+store delta artifacts under `.ultra/changes/active/<id>/delta/`. Incidents maintain
+the structured diagnosis artifact.
+
+Use `change.update` when accepted intent or evidence changes. Update the Change
+Contract, classification, research disposition, and docs impact together when their
+meaning is coupled. Downstream task, context, test, or review evidence affected by that
+change must become stale and be regenerated; never keep old evidence green by prompt
+assertion.
+
+If research is required, invoke `ultra-research` with the recorded disposition. If the
+contract is sufficiently evidenced, the host may recommend `ultra-plan`. `change.context`
+is compiled only for an actual plan, implementation, test, or review consumer.
+
+Stable implementation discoveries use the approval-gated specification-learning
+transitions. External memory and graph providers retain their own content; Ultra stores
+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.