ultra-builder-pro-cli 0.14.0 → 0.15.0

package/mcp-server/server.cjs

@@ -2,7 +2,7 @@
 
 // MCP server (stdio JSON-RPC) exposing task.* + session.* tools backed by
 // .ultra/state.db. Uses the low-level Server API from
-// @modelcontextprotocol/sdk so we can pass raw JSON Schema (Draft 2020-12)
+// @modelcontextprotocol/server so we can pass raw JSON Schema (Draft 2020-12)
 // straight from spec/mcp-tools.yaml without translating to zod.
 
 const fs = require('node:fs');
@@ -12,12 +12,13 @@ const yaml = require('js-yaml');
 const Ajv = require('ajv/dist/2020');
 const addFormats = require('ajv-formats');
 
-const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
-const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
-const { ListToolsRequestSchema, CallToolRequestSchema } = require('@modelcontextprotocol/sdk/types.js');
+const { Server } = require('@modelcontextprotocol/server');
+const { StdioServerTransport } = require('@modelcontextprotocol/server/stdio');
 const { version: PACKAGE_VERSION } = require('../package.json');
 
-const { initStateDb, closeStateDb } = require('./lib/state-db.cjs');
+const {
+  initStateDb, closeStateDb, openStateDb, ensureSchemaVersion,
+} = require('./lib/state-db.cjs');
 const { assertStateAuthority } = require('./lib/state-authority.cjs');
 const ops = require('./lib/state-ops.cjs');
 const projector = require('./lib/projector.cjs');
@@ -30,6 +31,7 @@ const { initProject } = require('./lib/init-project.cjs');
 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 doctor = require('./lib/doctor.cjs');
 const {
   readProjectBreadcrumb,
@@ -91,12 +93,21 @@ const CHANGE_TOOLS = Object.freeze([
   'change.archive',
 ]);
 
+const WORKFLOW_TOOLS = Object.freeze([
+  'workflow.start',
+  'workflow.get',
+  'workflow.list',
+  'workflow.step',
+  'workflow.complete',
+]);
+
 const SYSTEM_TOOLS = Object.freeze([
   'system.doctor',
 ]);
 
 const REGISTERED_TOOLS = Object.freeze([
   ...TASK_TOOLS, ...SESSION_TOOLS, ...PLAN_TOOLS, ...BASELINE_TOOLS, ...CHANGE_TOOLS,
+  ...WORKFLOW_TOOLS,
   ...SYSTEM_TOOLS,
 ]);
 
@@ -112,6 +123,7 @@ 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',
+  'workflow.start', 'workflow.step', 'workflow.complete',
 ]);
 
 function loadRegisteredTools() {
@@ -252,10 +264,33 @@ async function dispatchTool(name, input, db, ctx = {}) {
       return ops.switchTaskTag(db, input.id, input.tag);
     }
     case 'task.dependency_topo': {
-      const requested = Array.isArray(input && input.task_ids) ? input.task_ids : null;
-      const rows = requested
-        ? requested.map((id) => ops.readTask(db, id)).filter(Boolean)
-        : ops.listTasks(db, {});
+      const hasTaskIds = Array.isArray(input && input.task_ids);
+      const hasChangeId = typeof input?.change_id === 'string' && input.change_id.trim() !== '';
+      if (hasTaskIds === hasChangeId) {
+        const err = new Error('provide exactly one of task_ids or change_id');
+        err.code = 'VALIDATION_ERROR';
+        throw err;
+      }
+      let rows;
+      if (hasTaskIds) {
+        rows = input.task_ids.map((id) => {
+          const task = ops.readTask(db, id);
+          if (!task) {
+            const err = new Error(`task ${id} not found`);
+            err.code = 'TASK_NOT_FOUND';
+            throw err;
+          }
+          return task;
+        });
+      } else {
+        const change = changes.readChange(db, input.change_id);
+        if (!change) {
+          const err = new Error(`change ${input.change_id} not found`);
+          err.code = 'CHANGE_NOT_FOUND';
+          throw err;
+        }
+        rows = ops.listTasks(db, { change_id: change.id });
+      }
       const graph = rows.map((t) => ({
         id: t.id,
         deps: Array.isArray(t.deps) ? t.deps : [],
@@ -272,6 +307,11 @@ async function dispatchTool(name, input, db, ctx = {}) {
     case 'task.parse_prd': {
       const dryRun = input.dry_run === true;
       const rootDir = ctx.rootDir || process.cwd();
+      if (!dryRun && !String(input.change_id || '').trim()) {
+        const err = new Error('persisting a parsed task graph requires change_id');
+        err.code = 'CHANGE_REQUIRED';
+        throw err;
+      }
       const creationAuthority = { change_id: input.change_id };
       if (!dryRun) changes.assertTaskCreationAllowed(db, creationAuthority, { rootDir });
       const parsed = parser.parsePrd(input.tasks, {
@@ -330,20 +370,34 @@ async function dispatchTool(name, input, db, ctx = {}) {
     }
     case 'plan.export': {
       const rootDir = ctx.rootDir || process.cwd();
+      const change = changes.readChange(db, input.change_id);
+      if (!change) {
+        const err = new Error(`change ${input.change_id} not found`);
+        err.code = 'CHANGE_NOT_FOUND';
+        throw err;
+      }
+      if (!['active', 'blocked'].includes(change.status)) {
+        const err = new Error(`change ${change.id} is ${change.status}`);
+        err.code = 'CHANGE_NOT_MUTABLE';
+        throw err;
+      }
       const abs = path.isAbsolute(input.out_path)
         ? input.out_path
         : path.join(rootDir, input.out_path);
-      const tasks = ops.listTasks(db, { tag: input.tag });
+      const tasks = ops.listTasks(db, { tag: input.tag, change_id: change.id });
       if (tasks.length === 0) {
         const err = new Error('no tasks to plan');
         err.code = 'NO_TASKS';
         throw err;
       }
-      const plan = planStore.buildPlan(tasks, {});
+      const plan = planStore.buildPlan(tasks, { changeId: change.id });
       const { plan_path } = planStore.savePlanArtifact(plan, abs, input.format || 'json');
       ops.appendEvent(db, {
-        type: 'plan_approved',
-        payload: { plan_path, wave_count: plan.waves.length, tag: input.tag || null },
+        type: 'plan_exported',
+        change_id: change.id,
+        payload: {
+          change_id: change.id, plan_path, wave_count: plan.waves.length, tag: input.tag || null,
+        },
       });
       return { plan_path, wave_count: plan.waves.length };
     }
@@ -355,6 +409,13 @@ async function dispatchTool(name, input, db, ctx = {}) {
         err.code = 'NO_PLAN';
         throw err;
       }
+      if (loaded.change_id !== input.change_id) {
+        const err = new Error(
+          `execution plan belongs to ${loaded.change_id || '(unbound)'}, not ${input.change_id}`,
+        );
+        err.code = 'PLAN_CHANGE_MISMATCH';
+        throw err;
+      }
       return { plan: planStore.selectSection(loaded, input.section) };
     }
     case 'baseline.start': {
@@ -456,6 +517,44 @@ async function dispatchTool(name, input, db, ctx = {}) {
     case 'change.archive': {
       return changes.archiveChange(db, input, { rootDir: ctx.rootDir || process.cwd() });
     }
+    case 'workflow.start': {
+      return {
+        workflow: workflows.startWorkflow(
+          db, input, { rootDir: ctx.rootDir || process.cwd() },
+        ),
+      };
+    }
+    case 'workflow.get': {
+      const workflow = workflows.readWorkflow(
+        db, input.id, { rootDir: ctx.rootDir || process.cwd() },
+      );
+      if (!workflow) {
+        const error = new Error(`workflow ${input.id} not found`);
+        error.code = 'WORKFLOW_NOT_FOUND';
+        throw error;
+      }
+      return { workflow };
+    }
+    case 'workflow.list': {
+      const rows = workflows.listWorkflows(
+        db, input || {}, { rootDir: ctx.rootDir || process.cwd() },
+      );
+      return { workflows: rows, count: rows.length };
+    }
+    case 'workflow.step': {
+      return {
+        workflow: workflows.recordWorkflowStep(
+          db, input, { rootDir: ctx.rootDir || process.cwd() },
+        ),
+      };
+    }
+    case 'workflow.complete': {
+      return {
+        workflow: workflows.completeWorkflow(
+          db, input, { rootDir: ctx.rootDir || process.cwd() },
+        ),
+      };
+    }
     case 'system.doctor': {
       return doctor.runDoctor(db, {
         rootDir: ctx.rootDir || process.cwd(),
@@ -501,7 +600,7 @@ function startServer({ dbPath, rootDir, projectOnWrite = true, project = project
     { capabilities: { tools: {} } },
   );
 
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  server.setRequestHandler('tools/list', async () => ({
     tools: tools.map((t) => ({
       name: t.name,
       description: t.description,
@@ -509,7 +608,7 @@ function startServer({ dbPath, rootDir, projectOnWrite = true, project = project
     })),
   }));
 
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  server.setRequestHandler('tools/call', async (request) => {
     const { name, arguments: args = {} } = request.params;
     const toolStart = Date.now();
     let toolError = null;
@@ -623,6 +722,51 @@ async function main() {
   process.on('SIGINT', cleanup);
 }
 
+function hookMetadata(value, fallback = 'unknown', maxLength = 256) {
+  const normalized = typeof value === 'string' ? value.trim() : '';
+  return (normalized || fallback).slice(0, maxLength);
+}
+
+function appendHookLifecycleEvent({ rootDir, action, hookInput = {} } = {}) {
+  if (!['start', 'stop'].includes(action)) {
+    const error = new Error('hook lifecycle action must be start or stop');
+    error.code = 'VALIDATION_ERROR';
+    throw error;
+  }
+  const root = path.resolve(rootDir || process.cwd());
+  const dbPath = path.join(root, '.ultra', 'state.db');
+  if (!fs.existsSync(dbPath)) return { recorded: false, reason: 'STATE_DB_MISSING' };
+
+  const db = openStateDb(dbPath);
+  try {
+    ensureSchemaVersion(db);
+    const change = db.prepare(
+      `SELECT id FROM changes WHERE status IN ('active', 'blocked', 'ready')
+       ORDER BY updated_at DESC, rowid DESC LIMIT 1`,
+    ).get();
+    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 payload = {
+      agent_id: hookMetadata(hookInput.agent_id),
+      agent_type: hookMetadata(hookInput.agent_type),
+      host_session_id: hookMetadata(hookInput.session_id, '', 256),
+    };
+    ops.appendEvent(db, {
+      type: action === 'start' ? 'subagent_started' : 'subagent_stopped',
+      change_id: change.id,
+      task_id: task?.id || null,
+      payload,
+    });
+    return { recorded: true, change_id: change.id, task_id: task?.id || null };
+  } finally {
+    closeStateDb(db);
+  }
+}
+
 if (require.main === module) {
   main().catch((err) => {
     process.stderr.write(`mcp-server fatal: ${err.message}\n`);
@@ -639,10 +783,12 @@ module.exports = {
   PLAN_TOOLS,
   BASELINE_TOOLS,
   CHANGE_TOOLS,
+  WORKFLOW_TOOLS,
   SYSTEM_TOOLS,
   REGISTERED_TOOLS,
   STATELESS_TOOLS,
   MUTATING_TOOLS,
+  appendHookLifecycleEvent,
   readProjectBreadcrumb,
   renderProjectBreadcrumb,
 };

package/orchestrator/daemon.cjs

@@ -16,7 +16,7 @@ const runtimeState = require('../mcp-server/lib/runtime-state.cjs');
 const projector = require('../mcp-server/lib/projector.cjs');
 const runner = require('./session-runner.cjs');
 const recovery = require('./recovery.cjs');
-const { evaluate, DEFAULT_RULES, ROUTE_PREFERENCES } = require('./dispatch-rules.cjs');
+const { evaluate, DEFAULT_RULES } = require('./dispatch-rules.cjs');
 
 // Phase 8B.1 — routeTask is now a thin wrapper over evaluate() so Phase 5.4
 // callers see identical behavior while the parallel orchestrator (8B.2) can
@@ -146,6 +146,5 @@ function runDaemon({
 module.exports = {
   runDaemon,
   routeTask,
-  ROUTE_PREFERENCES,
   maintainState,
 };

package/orchestrator/dispatch-rules.cjs

@@ -8,28 +8,13 @@
 //   • defer       — leave task pending, revisit next tick (deps/wave wait)
 //   • block       — terminal: don't spawn (breaker, no runtimes, etc.)
 //
-// Phase 5.4 ROUTE_PREFERENCES lives here now. daemon.cjs's `routeTask` is a
-// thin wrapper around evaluate() so Phase 5.4 tests stay green while the
-// parallel orchestrator (8B.2) gets a richer decision surface: wave state,
-// deps readiness, and custom rule injection.
+// Runtime order is caller-owned. The orchestrator does not infer model quality,
+// price, or capability from a host name because every host can be configured
+// with different models. The parallel orchestrator supplies richer dimensions:
+// wave state, dependency readiness, and explicit custom rules.
 
 const { isSupportedRuntime } = require('../adapters/_shared/runtime-assets.cjs');
 
-const ROUTE_PREFERENCES = Object.freeze({
-  haiku:  ['opencode', 'claude', 'codex'],
-  sonnet: ['claude', 'codex', 'opencode'],
-  opus:   ['claude', 'codex'],
-});
-
-function resolveByPreference(ctx) {
-  const hint = ctx.task && ctx.task.complexity_hint;
-  const pref = hint ? ROUTE_PREFERENCES[hint] : null;
-  if (pref) {
-    for (const r of pref) if (ctx.available_runtimes.includes(r)) return r;
-  }
-  return ctx.available_runtimes[0];
-}
-
 const DEFAULT_RULES = Object.freeze([
   {
     id: 'breaker-blocked',
@@ -56,17 +41,7 @@ const DEFAULT_RULES = Object.freeze([
     action: 'defer',
   },
   {
-    id: 'by-preference',
-    priority: 10,
-    when: (ctx) => {
-      const hint = ctx.task && ctx.task.complexity_hint;
-      return !!(hint && ROUTE_PREFERENCES[hint]);
-    },
-    action: 'spawn_agent',
-    resolve: resolveByPreference,
-  },
-  {
-    id: 'fallback-first-available',
+    id: 'first-authorized-runtime',
     priority: 0,
     when: () => true,
     action: 'spawn_agent',
@@ -100,5 +75,4 @@ function evaluate(ctx, rules = DEFAULT_RULES) {
 module.exports = {
   evaluate,
   DEFAULT_RULES,
-  ROUTE_PREFERENCES,
 };

package/orchestrator/planner/plan-builder.cjs

@@ -15,18 +15,22 @@ const DEFAULT_COMPLEXITY = 3;
 const TOKENS_PER_COMPLEXITY = Object.freeze({ input: 5000, output: 2000 });
 const DURATION_MIN_PER_COMPLEXITY = 5;
 
-function buildPlan(tasks, { runtime = 'claude', model = null } = {}) {
+function buildPlan(tasks, { runtime = null, model = null, changeId = null } = {}) {
   if (!Array.isArray(tasks)) {
     throw new TypeError('buildPlan: tasks must be an array');
   }
 
-  const graph = tasks.map((t) => ({
+  // Plan artifacts are durable and compared by digest. Keep their ordering
+  // independent from SQLite insertion order or caller enumeration order.
+  const orderedTasks = [...tasks].sort((left, right) => String(left.id).localeCompare(String(right.id)));
+
+  const graph = orderedTasks.map((t) => ({
     id: t.id,
     deps: Array.isArray(t.deps) ? t.deps : [],
   }));
   const { waves, cycles } = computeWaves(graph);
 
-  const byId = new Map(tasks.map((t) => [t.id, t]));
+  const byId = new Map(orderedTasks.map((t) => [t.id, t]));
 
   const conflict_surface = [];
   const wavePayload = waves.map((waveTasks, idx) => {
@@ -52,18 +56,21 @@ function buildPlan(tasks, { runtime = 'claude', model = null } = {}) {
   });
 
   const ownership_forecast = {};
-  for (const t of tasks) {
+  for (const t of orderedTasks) {
     ownership_forecast[t.id] = Array.isArray(t.files_modified) ? t.files_modified : [];
   }
 
-  const estimated_cost_usd = round4(
-    tasks.reduce((sum, t) => {
-      const complexity = Number(t.complexity || DEFAULT_COMPLEXITY);
-      const ti = complexity * TOKENS_PER_COMPLEXITY.input;
-      const to = complexity * TOKENS_PER_COMPLEXITY.output;
-      return sum + (computeCost(runtime, model, ti, to) || 0);
-    }, 0),
-  );
+  const taskCosts = orderedTasks.map((t) => {
+    const complexity = Number(t.complexity || DEFAULT_COMPLEXITY);
+    const ti = complexity * TOKENS_PER_COMPLEXITY.input;
+    const to = complexity * TOKENS_PER_COMPLEXITY.output;
+    return computeCost(runtime, model, ti, to);
+  });
+  const estimated_cost_usd = orderedTasks.length === 0
+    ? 0
+    : (taskCosts.some((cost) => cost === null)
+      ? null
+      : round4(taskCosts.reduce((sum, cost) => sum + cost, 0)));
 
   const estimated_duration_min = wavePayload.reduce((acc, wv) => {
     const complexities = wv.tasks.map(
@@ -76,6 +83,8 @@ function buildPlan(tasks, { runtime = 'claude', model = null } = {}) {
   }, 0);
 
   return {
+    schema_version: '1.0',
+    change_id: changeId,
     waves: wavePayload,
     ownership_forecast,
     conflict_surface,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.14.0",
+  "version": "0.15.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",
@@ -49,13 +49,20 @@
     ".ultra-template",
     "docs/ROADMAP.md",
     "docs/ARCHITECTURE.md",
+    "docs/WORKFLOW-LIFECYCLE.md",
     "docs/AGENT-CONTEXT.md",
     "docs/SKILL-AUTHORING.md",
     "docs/COMMIT-HASH-BACKFILL.md",
     "docs/PLAN.zh-CN.md",
     "docs/STATE-DB-ACCESS-POLICY.md",
     "docs/USER-HANDBOOK-CONTRACT.md",
-    "docs/RUNTIME-COMPAT-MATRIX.md"
+    "docs/RUNTIME-COMPAT-MATRIX.md",
+    "!**/__pycache__/**",
+    "!**/*.pyc",
+    "!**/*.pyo",
+    "!**/*.test.cjs",
+    "!**/tests/**",
+    "!mcp-server/test-support/**"
   ],
   "keywords": [
     "claude-code",
@@ -98,11 +105,14 @@
     "install:all": "node bin/install.js --all --local"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/server": "2.0.0-beta.5",
     "@vercel/ncc": "0.38.4",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "better-sqlite3": "^11.5.0",
     "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.0.0-beta.5"
   }
 }

package/skills/ultra-change/SKILL.md

@@ -1,84 +1,69 @@
 ---
 name: ultra-change
-description: Open or resume a bounded continuous change and connect its intent, delta, decisions, context, and executable tasks. Use when maintaining or extending an Ultra project after its baseline exists.
+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.
 ---
 
-# Open or resume a continuous change
+# Maintain one continuous change
 
-Keep post-delivery work aligned through a delta, implementation, learning, and
-convergence loop.
+Use Ultra MCP for lifecycle writes. Keep external memory and code-graph content in
+their providers; Ultra stores references only.
 
-## Authority boundary
+## Bind or create
 
-Use Ultra MCP tools for change and task lifecycle writes. Do not write raw SQLite or
-mutate generated task and context projections. External memory or code-graph systems
-own their payloads; Ultra stores only provider references supplied by the user or host.
+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`.
 
-## Workflow
+## Record the change workflow
 
-1. Call `baseline.get`. State integrity failure routes to `ultra-doctor`.
-   - Create ordinary work only when the baseline is healthy and `ready`.
-   - Resume a change that was already active when baseline drift appears; record the
-     condition as a warning and restore baseline readiness before ordinary convergence.
-   - Create an `incident` on an unhealthy baseline only with an explicit
-     `baseline_bypass` containing the reason and approver.
-   - Route every other missing, migrated, incomplete, or stale baseline to `ultra-init`.
-2. Call `change.list` and `change.breadcrumb`.
-   - Resume the single change that matches the requested outcome.
-   - Require an explicit id when several changes could match.
-   - Create a new change only when no existing packet represents the same outcome.
-3. Capture the observable outcome, acceptance, non-goals, affected public seam,
-   documentation impact, and unresolved decisions.
-4. Classify the change as `quick`, `standard`, `major`, or `incident`. Ask only for a
-   material product, risk, or recovery decision that repository evidence cannot answer.
-5. Call `change.create` with a stable kebab-case id, or `change.update` when resuming.
-   For incident break-glass, persist the approved reason in `baseline_bypass`; never
-   infer approval from urgency.
-6. Write the minimum artifact set required by the classification:
+Use `workflow.step` as evidence becomes durable:
 
-   ```text
-   .ultra/changes/active/<change-id>/
-     intent.md
-     delta/                 # standard and major
-     plan.md                # standard and major
-     diagnosis.md           # incident
-     context-manifest.json  # generated projection
-     spec-learning.json     # generated projection
-     verification.md        # generated projection
-   ```
+- `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.
 
-   Delta files describe differences from the baseline, not a second copy of it.
-   Incident diagnosis records the symptom, earliest bad state, falsifiable
-   hypotheses, evidence, root cause, and recovery boundary.
-7. Create the smallest executable vertical slice with `task.create`. Each task needs
-   one outcome, bounded ownership, dependencies, a live public seam, an exact
-   verification command, and documentation impact.
-8. Compile `change.context` for the next role and gate. Include only required
-   references and the task execution contract. Missing required references, digest or
-   HEAD drift, an absent public seam or verification command, and unknown
-   documentation impact are blockers. File count, token estimate, and context-share
-   thresholds are advisory warnings: narrow reads or split the slice when useful, but
-   never raise a threshold merely to make the warning disappear or refuse necessary
-   incident context.
-9. Call `change.breadcrumb` and return its single 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.
 
-## Specification learning
+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.
 
-When implementation uncovers a stable requirement, invariant, or public behavior
-missing from the baseline, call `change.learning_propose` with evidence and a target
-document. The proposal does not edit the baseline. It must be approved or rejected,
-and an approved item is marked applied only after the target document is updated and
-verified.
+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.
 
-## Completion gate
+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.
 
-Do not claim alignment while a material decision is unresolved, documentation impact
-is unknown, context is stale, or the next task is not executable. Ordinary change
-convergence requires a non-migrated `ready` baseline. Normal HEAD or tracked-spec drift
-caused by the active change is reconciled at archive.
+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.
 
-An approved break-glass incident may converge and archive while baseline adoption is
-incomplete. Its archive must add an open `baseline_blocker` reconciliation gap owned by
-the recorded approver. Report the incident as closed and the project baseline as not
-ready until that gap is resolved. Every archive declares baseline updates or an exact
-no-change reason; failed ordinary reconciliation rolls back state and artifacts.
+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`.

package/skills/ultra-change/references/change-contract.md

@@ -0,0 +1,36 @@
+# Change Contract and profile
+
+Create one contract before planning. Keep every field specific enough to verify and
+stable enough to survive a fresh session.
+
+## Contract
+
+- `outcome`: one externally observable result.
+- `acceptance`: stable ids with a criterion and exact verification for each accepted
+  behavior.
+- `non_goals`: explicit boundaries that prevent accidental scope growth.
+- `public_seams`: entry points or outputs through which acceptance is observed.
+- `recovery`: a bounded reversal or recovery strategy and its verification.
+- `unresolved_decisions`: stable ids, summary, blocking state, and owner when known.
+
+Resolve every blocking decision before planning. Keep non-blocking uncertainty visible
+in the task and verification contracts.
+
+## Profile
+
+- `quick`: one low-risk task, no material risk flags, and no research dependency.
+- `standard`: a bounded change with multiple tasks or ordinary integration risk.
+- `major`: a broad or consequential change with material contract, migration,
+  authorization, security, multi-module, external-integration, or release impact.
+- `incident`: urgent diagnosis and recovery with a reproducible symptom. Baseline
+  break-glass still requires a recorded approver and recovery contract.
+
+Record a profile rationale and every applicable risk flag. Select the smallest profile
+whose guarantees cover the real blast radius; never use profile labels as estimates.
+
+## Research disposition
+
+Use `none` with a rationale when accepted evidence is sufficient. Use `bounded` or
+`required` with a supported mode and the exact selected semantic steps when product,
+behavior, architecture, deployment, or risk facts remain load-bearing. The recorded
+selection is the planning gate.