ultra-builder-pro-cli 0.6.0 → 0.7.0

package/mcp-server/tests/init-project.test.cjs

@@ -5,6 +5,7 @@ const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const Database = require('better-sqlite3');
 
 const { initProject, InitProjectError, DEFAULT_TEMPLATE } = require('../lib/init-project.cjs');
 
@@ -29,6 +30,18 @@ test('initProject copies bundled template into .ultra/', () => {
     assert.equal(r.created_path, path.join(target, '.ultra'));
     assert.ok(r.copied_files.includes('tasks/tasks.json'));
     assert.ok(r.copied_files.includes('specs/product.md'));
+    assert.ok(r.copied_files.includes('changes/active/.gitkeep'));
+    assert.ok(r.copied_files.includes('changes/archive/.gitkeep'));
+    assert.equal(r.state_db_path, path.join(target, '.ultra', 'state.db'));
+    assert.ok(fs.existsSync(r.state_db_path));
+    const db = new Database(r.state_db_path, { readonly: true });
+    try {
+      const version = db.prepare("SELECT version FROM schema_version WHERE version = '9.0'").get();
+      assert.equal(version.version, '9.0');
+      assert.ok(db.prepare("SELECT name FROM sqlite_master WHERE name = 'changes'").get());
+    } finally {
+      db.close();
+    }
     assert.ok(!r.copied_files.some((f) => f.endsWith('.DS_Store')));
   } finally { cleanup(target); }
 });
@@ -81,6 +94,38 @@ test('initProject with overwrite=true backs up existing .ultra/', () => {
   } finally { cleanup(target); }
 });
 
+test('initProject restores the prior .ultra when overwrite initialization fails', () => {
+  const target = mkTempDir();
+  const badTemplate = mkTempDir('ubp-bad-template-');
+  try {
+    initProject({ target_dir: target, project_name: 'first' });
+    fs.writeFileSync(path.join(target, '.ultra', 'sentinel.txt'), 'restore-me');
+    fs.cpSync(DEFAULT_TEMPLATE, badTemplate, { recursive: true });
+    fs.writeFileSync(path.join(badTemplate, 'tasks', 'tasks.json'), '{not-json\n');
+
+    assert.throws(
+      () => initProject({
+        target_dir: target,
+        project_name: 'broken-overwrite',
+        overwrite: true,
+        source_template: badTemplate,
+      }),
+      (error) => error instanceof InitProjectError && error.code === 'IO_ERROR',
+    );
+    assert.equal(
+      fs.readFileSync(path.join(target, '.ultra', 'sentinel.txt'), 'utf8'),
+      'restore-me',
+    );
+    assert.equal(
+      fs.readdirSync(target).some((name) => name.startsWith('.ultra.backup.')),
+      false,
+    );
+  } finally {
+    cleanup(target);
+    cleanup(badTemplate);
+  }
+});
+
 test('initProject rejects empty project_name', () => {
   const target = mkTempDir();
   try {

package/mcp-server/tests/server-contract.test.cjs

@@ -6,6 +6,7 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const yaml = require('js-yaml');
+const Database = require('better-sqlite3');
 
 const { Client } = require('@modelcontextprotocol/sdk/client/index.js');
 const { StdioClientTransport } = require('@modelcontextprotocol/sdk/client/stdio.js');
@@ -19,7 +20,7 @@ function tmpProject() {
   return { dir, dbPath: path.join(dir, '.ultra', 'state.db') };
 }
 
-async function withClient({ dir, dbPath }, fn) {
+async function withClient({ dir, dbPath }, fn, extraEnv = {}) {
   const transport = new StdioClientTransport({
     command: process.execPath,
     args: [SERVER],
@@ -27,6 +28,7 @@ async function withClient({ dir, dbPath }, fn) {
       ...process.env,
       UBP_DB_PATH: dbPath,
       UBP_ROOT_DIR: dir,
+      ...extraEnv,
     },
     stderr: 'pipe',
   });
@@ -72,6 +74,13 @@ test('listTools returns workflow tools and exposes no Ultra memory API', async (
       const list = await client.listTools();
       const names = list.tools.map((t) => t.name).sort();
       assert.deepEqual(names, [
+        'change.archive',
+        'change.context',
+        'change.converge',
+        'change.create',
+        'change.get',
+        'change.list',
+        'change.update',
         'plan.export',
         'plan.get',
         'session.admission_check',
@@ -81,6 +90,7 @@ test('listTools returns workflow tools and exposes no Ultra memory API', async (
         'session.list',
         'session.spawn',
         'session.subscribe_events',
+        'system.doctor',
         'task.append_event',
         'task.create',
         'task.delete',
@@ -105,6 +115,67 @@ test('listTools returns workflow tools and exposes no Ultra memory API', async (
   }
 });
 
+test('change.create + change.context expose a continuous change unit with external provider references', async () => {
+  const proj = tmpProject();
+  try {
+    fs.writeFileSync(path.join(proj.dir, 'README.md'), '# project\n');
+    await withClient(proj, async (client) => {
+      const created = await client.callTool({
+        name: 'change.create',
+        arguments: {
+          id: 'mcp-change', title: 'Continuous maintenance', kind: 'quick',
+          intent: 'Keep daily modifications synchronized after initial delivery.',
+          docs_impact: { status: 'none', files: [], rationale: 'Contract-only fixture.' },
+          provider_refs: {
+            memory: { provider: 'cloud-mem', status: 'available', reference: 'cmem://fixture' },
+            code_graph: { provider: 'codebase-memory-mcp', status: 'stale', project: 'fixture' },
+          },
+        },
+      });
+      const payload = readToolPayload(created);
+      assert.equal(payload.change.id, 'mcp-change');
+      assert.equal(payload.change.status, 'active');
+      assert.equal(created._meta.ultra.state_commit, 'committed');
+      assert.equal(created._meta.ultra.projection_status, 'completed');
+
+      const context = readToolPayload(await client.callTool({
+        name: 'change.context', arguments: { id: 'mcp-change' },
+      }));
+      assert.equal(context.manifest.change.id, 'mcp-change');
+      assert.equal(context.manifest.providers.memory.provider, 'cloud-mem');
+      assert.equal(context.manifest.provider_boundary.includes('content remain external'), true);
+
+      const listed = readToolPayload(await client.callTool({
+        name: 'change.list', arguments: { status: 'active' },
+      }));
+      assert.equal(listed.count, 1);
+      assert.equal(listed.changes[0].id, 'mcp-change');
+    });
+  } finally {
+    fs.rmSync(proj.dir, { recursive: true, force: true });
+  }
+});
+
+test('system.doctor returns structured provider ownership and projection health', async () => {
+  const proj = tmpProject();
+  try {
+    await withClient(proj, async (client) => {
+      await client.callTool({
+        name: 'task.create',
+        arguments: { id: 'doctor-seed', title: 'doctor seed', type: 'feature', priority: 'P1' },
+      });
+      const result = readToolPayload(await client.callTool({
+        name: 'system.doctor', arguments: { repair: false },
+      }));
+      assert.equal(result.status, 'healthy');
+      assert.equal(result.checks.external_providers.ownership, 'external');
+      assert.equal(result.repair_performed, false);
+    });
+  } finally {
+    fs.rmSync(proj.dir, { recursive: true, force: true });
+  }
+});
+
 test('MCP metadata matches the package and tools/list does not create project state', async () => {
   const proj = tmpProject();
   try {
@@ -309,6 +380,54 @@ test('mutating tools trigger the projector — tasks.json appears under .ultra/'
   }
 });
 
+test('output schema drift cannot strand a committed mutation without a projection job', async () => {
+  const proj = tmpProject();
+  try {
+    const runtimeRoot = path.join(proj.dir, 'runtime-contract');
+    fs.mkdirSync(path.join(runtimeRoot, 'spec', 'schemas'), { recursive: true });
+    fs.copyFileSync(path.join(REPO_ROOT, 'package.json'), path.join(runtimeRoot, 'package.json'));
+    fs.copyFileSync(
+      path.join(REPO_ROOT, 'spec', 'schemas', 'state-db.sql'),
+      path.join(runtimeRoot, 'spec', 'schemas', 'state-db.sql'),
+    );
+    const manifest = yaml.load(
+      fs.readFileSync(path.join(REPO_ROOT, 'spec', 'mcp-tools.yaml'), 'utf8'),
+    );
+    const createTool = manifest.tools.find((tool) => tool.name === 'task.create');
+    createTool.output_schema.required = ['impossible_output_field'];
+    createTool.output_schema.properties.impossible_output_field = { type: 'string' };
+    fs.writeFileSync(
+      path.join(runtimeRoot, 'spec', 'mcp-tools.yaml'),
+      yaml.dump(manifest, { noRefs: true, lineWidth: 120 }),
+    );
+
+    await withClient(proj, async (client) => {
+      const result = await client.callTool({
+        name: 'task.create',
+        arguments: { id: 'schema-drift', title: 'schema drift', type: 'feature', priority: 'P1' },
+      });
+      const error = expectError(result);
+      assert.equal(error.code, 'OUTPUT_SCHEMA_DRIFT');
+      assert.equal(error.details._ultra.state_commit, 'committed');
+      assert.equal(error.details._ultra.projection_status, 'completed');
+    }, { UBP_RUNTIME_ROOT: runtimeRoot });
+
+    const db = new Database(proj.dbPath, { readonly: true, fileMustExist: true });
+    try {
+      assert.equal(db.prepare('SELECT COUNT(*) AS count FROM tasks WHERE id = ?').get('schema-drift').count, 1);
+      const job = db.prepare(
+        "SELECT status FROM projection_jobs WHERE tool_name = 'task.create' ORDER BY id DESC LIMIT 1",
+      ).get();
+      assert.deepEqual(job, { status: 'completed' });
+    } finally {
+      db.close();
+    }
+    assert.ok(fs.existsSync(path.join(proj.dir, '.ultra', 'tasks', 'tasks.json')));
+  } finally {
+    fs.rmSync(proj.dir, { recursive: true, force: true });
+  }
+});
+
 test('task.init_project creates .ultra/ skeleton in a fresh target directory', async () => {
   const proj = tmpProject();
   const freshTarget = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-init-target-'));
@@ -321,6 +440,8 @@ test('task.init_project creates .ultra/ skeleton in a fresh target directory', a
       const payload = readToolPayload(res);
       assert.equal(payload.status, 'created');
       assert.equal(payload.created_path, path.join(freshTarget, '.ultra'));
+      assert.equal(payload.state_db_path, path.join(freshTarget, '.ultra', 'state.db'));
+      assert.ok(fs.existsSync(payload.state_db_path));
       assert.ok(payload.copied_files.includes('tasks/tasks.json'));
       const tasksJson = JSON.parse(fs.readFileSync(path.join(payload.created_path, 'tasks', 'tasks.json'), 'utf8'));
       assert.equal(tasksJson.project.name, 'mcp-init');
@@ -748,6 +869,7 @@ test('plan.export → plan.get round trip: artifact on disk + retrievable', asyn
       const expData = readToolPayload(exp);
       assert.equal(expData.wave_count, 2);
       assert.ok(fs.existsSync(expData.plan_path), 'artifact file must exist');
+      assert.equal(exp._meta.ultra.projection_status, 'completed');
 
       const got = await client.callTool({ name: 'plan.get', arguments: { section: 'topo' } });
       const gotData = readToolPayload(got);

package/mcp-server/tests/state-db.test.cjs

@@ -8,22 +8,59 @@ const path = require('node:path');
 
 const stateDb = require('../lib/state-db.cjs');
 
-test('initStateDb upgrades a v8A.1 database in place with estimated_days', () => {
+test('initStateDb upgrades a pre-9.0 database in place with task/event change linkage', () => {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-db-upgrade-'));
   const file = path.join(dir, 'state.db');
   try {
     const db = stateDb.openStateDb(file);
-    const oldSql = fs.readFileSync(stateDb.SCHEMA_FILE, 'utf8')
-      .replace(/^\s*estimated_days.*\n/m, '')
-      .replace(/^INSERT OR IGNORE INTO schema_version \(version, description\)\nVALUES \('8A\.2'.*\n/m, '');
-    db.exec(oldSql);
+    db.exec(`
+      CREATE TABLE tasks (
+        id TEXT PRIMARY KEY,
+        title TEXT NOT NULL,
+        type TEXT NOT NULL,
+        priority TEXT NOT NULL,
+        complexity INTEGER,
+        status TEXT NOT NULL DEFAULT 'pending',
+        deps TEXT,
+        files_modified TEXT,
+        session_id TEXT,
+        stale INTEGER NOT NULL DEFAULT 0,
+        complexity_hint TEXT,
+        tag TEXT,
+        trace_to TEXT,
+        context_file TEXT,
+        completion_commit TEXT,
+        parent_id TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+      CREATE TABLE events (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        ts TEXT NOT NULL,
+        type TEXT NOT NULL,
+        task_id TEXT,
+        session_id TEXT,
+        runtime TEXT,
+        payload_json TEXT
+      );
+      CREATE TABLE schema_version (
+        version TEXT PRIMARY KEY,
+        applied_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+        description TEXT
+      );
+      INSERT INTO schema_version (version, applied_at, description)
+      VALUES ('8A.1', '2026-01-01T00:00:00.000Z', 'legacy fixture');
+    `);
     stateDb.closeStateDb(db);
 
     const upgraded = stateDb.initStateDb(file);
     const columns = upgraded.db.prepare('PRAGMA table_info(tasks)').all().map((row) => row.name);
     assert.ok(columns.includes('estimated_days'));
-    assert.equal(upgraded.schema_version, '8A.2');
-    assert.ok(upgraded.db.prepare("SELECT 1 FROM schema_version WHERE version = '8A.2'").get());
+    assert.ok(columns.includes('change_id'));
+    const eventColumns = upgraded.db.prepare('PRAGMA table_info(events)').all().map((row) => row.name);
+    assert.ok(eventColumns.includes('change_id'));
+    assert.equal(upgraded.schema_version, '9.0');
+    assert.ok(upgraded.db.prepare("SELECT 1 FROM schema_version WHERE version = '9.0'").get());
     stateDb.closeStateDb(upgraded.db);
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });

package/mcp-server/tests/state-ops.test.cjs

@@ -112,6 +112,25 @@ test('patchTask updates JSON arrays + flags + status atomically', () => {
   }
 });
 
+test('patchTask status event follows the newly assigned continuous change', () => {
+  const { dir, db } = freshDb();
+  try {
+    db.prepare(
+      `INSERT INTO changes (id, title, kind, intent, artifact_root)
+       VALUES ('chg-link', 'Link task', 'quick', 'Link task to change.', '.ultra/changes/active/chg-link')`,
+    ).run();
+    ops.createTask(db, { id: 'link-task', title: 'link me', type: 'feature', priority: 'P1' });
+    ops.patchTask(db, 'link-task', { change_id: 'chg-link', status: 'in_progress' });
+    const event = db.prepare(
+      "SELECT change_id FROM events WHERE task_id = 'link-task' AND type = 'task_started'",
+    ).get();
+    assert.equal(event.change_id, 'chg-link');
+    closeStateDb(db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test('patchTask rejects unknown fields', () => {
   const { dir, db } = freshDb();
   try {

package/orchestrator/daemon.cjs

@@ -12,7 +12,10 @@
 // calling runDaemon — the runtime layer itself has no opt-in concept.
 
 const ops = require('../mcp-server/lib/state-ops.cjs');
+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');
 
 // Phase 8B.1 — routeTask is now a thin wrapper over evaluate() so Phase 5.4
@@ -29,6 +32,19 @@ function routeTask(task, availableRuntimes) {
   return d.action === 'spawn_agent' ? d.runtime : null;
 }
 
+function maintainState({ db, repoRoot, project = projector.projectAll } = {}) {
+  if (!db) throw new Error('maintainState: db required');
+  if (!repoRoot) throw new Error('maintainState: repoRoot required');
+  const cursor = runtimeState.readConsumerCursor(db, 'spec-staleness');
+  const staleness = ops.consumeSpecChangedEvents(db, { since_id: cursor, limit: 500 });
+  runtimeState.writeConsumerCursor(db, 'spec-staleness', staleness.next_since_id);
+  const ensured = runtimeState.ensureProjectionJob(db, { tool_name: 'orchestrator.maintenance' });
+  const projections = runtimeState.processProjectionJobs(db, {
+    rootDir: repoRoot, project, limit: 500,
+  });
+  return { staleness, ensured, projections };
+}
+
 function runDaemon({
   db,
   repoRoot,
@@ -47,9 +63,30 @@ function runDaemon({
 
   let stopped = false;
   const children = [];
+  let bootRecovery;
+  try {
+    bootRecovery = recovery.recoverOnBoot(db);
+  } catch (error) {
+    runtimeState.recordIncident(db, {
+      code: 'BOOT_RECOVERY_FAILED', severity: 'critical', retryable: true,
+      message: error.message, source_kind: 'orchestrator', source_id: 'boot',
+    });
+    if (onError) onError(error); else throw error;
+    bootRecovery = { recovered: [], count: 0, error: error.message };
+  }
 
   function tick() {
     if (stopped) return;
+    try {
+      maintainState({ db, repoRoot });
+    } catch (error) {
+      runtimeState.recordIncident(db, {
+        code: 'RUNTIME_MAINTENANCE_FAILED', severity: 'error', retryable: true,
+        message: error.message, source_kind: 'orchestrator', source_id: 'maintenance',
+      });
+      if (onError) onError(error); else throw error;
+      return;
+    }
     let pending;
     try {
       const filter = { status: 'pending' };
@@ -102,6 +139,7 @@ function runDaemon({
     },
     get running() { return !stopped; },
     get children() { return children.slice(); },
+    get bootRecovery() { return bootRecovery; },
   };
 }
 
@@ -109,4 +147,5 @@ module.exports = {
   runDaemon,
   routeTask,
   ROUTE_PREFERENCES,
+  maintainState,
 };

package/orchestrator/tests/daemon.test.cjs

@@ -259,3 +259,53 @@ test('runDaemon applies complexity_hint route', async () => {
     cleanup(repoRoot, db, handle);
   }
 });
+
+test('maintainState consumes spec changes with a durable cursor', () => {
+  const repoRoot = mkRepo();
+  const db = mkDb(repoRoot);
+  try {
+    ops.createTask(db, {
+      id: 'maintain-stale', title: 'stale target', type: 'feature', priority: 'P1',
+      trace_to: '.ultra/specs/product.md#daily-change',
+    });
+    ops.appendEvent(db, {
+      type: 'spec_changed', payload: { sections: ['.ultra/specs/product.md#daily-change'] },
+    });
+    const first = daemon.maintainState({ db, repoRoot });
+    assert.equal(first.staleness.processed, 1);
+    assert.equal(ops.readTask(db, 'maintain-stale').stale, true);
+    const second = daemon.maintainState({ db, repoRoot });
+    assert.equal(second.staleness.processed, 0);
+  } finally {
+    cleanup(repoRoot, db);
+  }
+});
+
+test('runDaemon performs crash recovery before dispatch polling', async () => {
+  const repoRoot = mkRepo();
+  const db = mkDb(repoRoot);
+  let handle;
+  try {
+    ops.createTask(db, { id: 'recover-boot', title: 'recover boot', type: 'bugfix', priority: 'P0' });
+    ops.updateTaskStatus(db, 'recover-boot', 'in_progress');
+    ops.createSession(db, {
+      sid: 'dead-session', task_id: 'recover-boot', runtime: 'claude', pid: 999999,
+      worktree_path: '/tmp/dead-worktree', artifact_dir: '/tmp/dead-artifact', lease_seconds: 1,
+    });
+    db.prepare(
+      "UPDATE sessions SET heartbeat_at = '2000-01-01T00:00:00.000Z', lease_expires_at = '2000-01-01T00:00:00.000Z' WHERE sid = 'dead-session'",
+    ).run();
+
+    handle = daemon.runDaemon({
+      db, repoRoot, runtimes: ['claude'], pollMs: 50,
+      command: LONG_SLEEP_CMD, commandArgs: LONG_SLEEP_ARGS,
+    });
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    const session = ops.readSession(db, 'dead-session');
+    assert.equal(session.status, 'crashed');
+    const failure = db.prepare("SELECT * FROM circuit_breaker WHERE task_id = 'recover-boot'").get();
+    assert.equal(failure.failure_count, 1);
+  } finally {
+    cleanup(repoRoot, db, handle);
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.6.0",
+  "version": "0.7.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, and Codex CLI.",
   "bin": {
     "ultra-builder-pro-cli": "bin/install.js",
@@ -27,6 +27,8 @@
     "skills/ultra-deliver",
     "skills/ultra-status",
     "skills/ultra-think",
+    "skills/ultra-change",
+    "skills/ultra-doctor",
     "skills/code-review-expert",
     "skills/security-rules",
     "skills/integration-rules",
@@ -49,7 +51,6 @@
     "docs/ARCHITECTURE.md",
     "docs/AGENT-CONTEXT.md",
     "docs/COMMIT-HASH-BACKFILL.md",
-    "docs/LEGACY-HERMES.md",
     "docs/PLAN.zh-CN.md",
     "docs/STATE-DB-ACCESS-POLICY.md",
     "docs/USER-HANDBOOK-CONTRACT.md",
@@ -100,7 +101,6 @@
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "better-sqlite3": "^11.5.0",
-    "chokidar": "^3.6.0",
     "js-yaml": "^4.1.0",
     "openai": "^6.34.0"
   }

package/settings.json

@@ -2,7 +2,6 @@
   "_comment": "Ultra Builder Pro runtime settings. Host hooks and plugin permissions live in each native plugin manifest.",
   "cleanupPeriodDays": 30,
   "orchestrator": {
-    "auto_dispatch": false,
-    "graph_watcher": false
+    "auto_dispatch": false
   }
 }

package/skills/ultra-change/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: ultra-change
+description: "Start or resume a continuous post-delivery change, compile bounded context, declare documentation impact, and route the change through implementation and convergence."
+runtime: all
+mcp_tools_required:
+  - change.create
+  - change.update
+  - change.get
+  - change.list
+  - change.context
+  - task.create
+  - task.list
+---
+
+# ultra-change — Continuous Change Entry
+
+Use this workflow for daily fixes, small features, redesigns, and incidents after
+the initial `init → research → plan → dev → test → deliver` baseline exists.
+Each piece of work becomes one durable change unit instead of an informal edit
+that drifts away from specifications and verification evidence.
+
+## Authority and provider boundary
+
+- `.ultra/state.db` is authoritative for the change, its tasks, events, incidents,
+  context snapshots, and projection status.
+- `.ultra/changes/active/<change-id>/` contains inspectable artifacts, not a
+  second state authority.
+- Memory and code graph are external providers. Pass only metadata references:
+  `provider`, `project`, `reference`, `revision`, `indexed_head`, and `status`.
+- Never paste recalled memories, graph nodes, embeddings, summaries, or provider
+  payloads into `provider_refs`. If provider data is unavailable, record
+  `status: unavailable` and continue with current-checkout evidence.
+- If any required change/task MCP operation is unavailable, stop. Do not edit
+  `state.db`, `tasks.json`, or context projections directly.
+
+## Arguments
+
+- `$1`: existing change id, or a short title for a new change.
+- Optional flags/concepts: `quick`, `standard`, `major`, `incident` and an
+  explicit documentation impact.
+
+## 1. Resume before creating
+
+Call `change.list` for `active` and `blocked` changes. If `$1` matches an
+existing id, call `change.get` and resume it. If the request clearly belongs to
+an active change, show the match and continue there rather than creating a
+duplicate.
+
+Do not resume `ready`, `archived`, or `cancelled` work as a new mutation. Create
+a follow-up change that links to the prior archive in its intent.
+
+## 2. Classify the change
+
+Choose the smallest honest kind:
+
+| Kind | Use when | Required convergence evidence |
+|---|---|---|
+| `quick` | localized fix or tiny behavior change | diff, tests, spec |
+| `standard` | normal feature or cross-file change | diff, tests, spec, docs, review |
+| `major` | architecture, public contract, migration, or broad redesign | diff, tests, spec, docs, review |
+| `incident` | production/runtime failure requiring diagnosis | diagnosis, diff, tests |
+
+When uncertain between two kinds, choose the higher-risk kind. Classification
+changes the proof required; it must not be used to bypass evidence.
+
+## 3. Declare intent and documentation impact
+
+Before implementation, write a concise intent with:
+
+- observed problem or requested outcome;
+- acceptance behavior and non-goals;
+- affected contract/surface;
+- recovery or rollback concern when material.
+
+Documentation impact is mandatory:
+
+- `required`: list every baseline document expected to change;
+- `none`: provide a concrete rationale;
+- `unknown`: allowed only while investigating and blocks convergence.
+
+Create the change with `change.create`. Use a stable kebab-case id. External
+provider references are optional and metadata-only.
+
+## 4. Build the delta packet
+
+The change directory is the bounded execution packet:
+
+```text
+.ultra/changes/active/<change-id>/
+  intent.md
+  context-manifest.json
+  delta/                  # required for standard and major
+  plan.md                 # required for standard and major
+  verification.md         # generated by convergence
+```
+
+For `standard` and `major`, write delta documents under `delta/` describing
+what changes relative to the current baseline. Do not copy the whole baseline.
+Write `plan.md` with live entry points, files/contracts, tests, documentation,
+and rollback. For `quick` and `incident`, add only artifacts needed to make the
+decision and evidence inspectable.
+
+Create at least one task through `task.create` with `change_id` set. Split only
+when ownership, dependencies, or independent verification justify it. All task
+status changes remain MCP-authoritative.
+
+## 5. Compile task context
+
+Call `change.context` before implementation and again whenever any of these
+changes: git HEAD, task set, relevant specs, allowed paths, or provider revision.
+Supply only the minimum task/spec/path references needed for the current slice.
+
+Inspect `context-manifest.json` before handing work to an agent. A stale git head
+or task set is a hard signal to recompile. Provider `status: stale` is visible
+context, not permission to silently refresh or mutate the external provider.
+
+## 6. Route execution
+
+- Implement one linked task with `/ultra-dev <task-id>`.
+- Run `/ultra-test` for project-level evidence.
+- Run `/ultra-review` when the change kind requires review.
+- Update baseline docs declared in `docs_impact` during the change, not after
+  memory has gone cold.
+- Finish with `/ultra-deliver`; it runs deterministic change convergence and
+  archive reconciliation before release actions.
+
+If work exposes a new requirement, update the change intent/delta and recompile
+context before continuing. Never let code become the only record of the change.
+
+## 7. Report
+
+Return the change id, kind, artifact root, linked tasks, documentation impact,
+context freshness, provider-reference status, and exact next workflow. Separate
+provider unavailability from an Ultra runtime incident.
+
+## What this skill does not do
+
+- It does not implement, test, review, release, or repair runtime state.
+- It does not own or synchronize Memory/code-graph content.
+- It does not bypass user approval for destructive or external release actions.