ultra-builder-pro-cli 0.9.0 → 0.10.0

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

@@ -9,7 +9,8 @@ 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 = '9.1';
+const EXPECTED_VERSION = '10.0';
+const KIMI_SCHEMA_VERSION = '9.1';
 
 const REQUIRED_TABLES = Object.freeze([
   'tasks',
@@ -23,6 +24,7 @@ const REQUIRED_TABLES = Object.freeze([
   'changes',
   'artifacts',
   'context_snapshots',
+  'spec_learning_candidates',
   'trace_links',
   'incidents',
   'projection_jobs',
@@ -71,6 +73,13 @@ function columnNames(db, table) {
   return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((row) => row.name));
 }
 
+function latestSchemaVersion(db) {
+  if (!tableNames(db).includes('schema_version')) return null;
+  return db.prepare(
+    'SELECT version FROM schema_version ORDER BY applied_at DESC, rowid DESC LIMIT 1',
+  ).get()?.version || null;
+}
+
 function applyCompatibleColumns(db) {
   const tables = new Set(tableNames(db));
   if (!tables.has('tasks')) return;
@@ -87,6 +96,48 @@ function applyCompatibleColumns(db) {
   }
 }
 
+function applyContextSpineUpgrade(db) {
+  const tables = new Set(tableNames(db));
+  if (!tables.has('context_snapshots')) return false;
+  let changed = !tables.has('spec_learning_candidates');
+  const columns = columnNames(db, 'context_snapshots');
+  const additions = [
+    ['role', "TEXT NOT NULL DEFAULT 'plan' CHECK (role IN ('plan', 'implement', 'check', 'review'))"],
+    ['gate', "TEXT NOT NULL DEFAULT 'alignment' CHECK (gate IN ('alignment', 'planning', 'implementation', 'verification', 'review', 'convergence', 'recovery'))"],
+    ['next_action', "TEXT NOT NULL DEFAULT 'Resolve the next Ultra workflow action.'"],
+    ['readiness', "TEXT NOT NULL DEFAULT 'ready' CHECK (readiness IN ('ready', 'blocked'))"],
+    ['blockers_json', "TEXT NOT NULL DEFAULT '[]'"],
+    ['context_json', "TEXT NOT NULL DEFAULT '{}'"],
+    ['token_estimate', 'INTEGER NOT NULL DEFAULT 0 CHECK (token_estimate >= 0)'],
+    ['token_budget', 'INTEGER NOT NULL DEFAULT 12000 CHECK (token_budget > 0)'],
+  ];
+  for (const [name, definition] of additions) {
+    if (!columns.has(name)) {
+      db.exec(`ALTER TABLE context_snapshots ADD COLUMN ${name} ${definition}`);
+      changed = true;
+    }
+  }
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS spec_learning_candidates (
+      id            TEXT PRIMARY KEY,
+      change_id     TEXT NOT NULL REFERENCES changes(id) ON DELETE CASCADE,
+      task_id       TEXT REFERENCES tasks(id) ON DELETE SET NULL,
+      target_ref    TEXT NOT NULL,
+      summary       TEXT NOT NULL,
+      evidence_json TEXT NOT NULL DEFAULT '[]',
+      status        TEXT NOT NULL DEFAULT 'proposed'
+                      CHECK (status IN ('proposed', 'approved', 'rejected', 'applied')),
+      resolution    TEXT,
+      proposed_at   TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+      resolved_at   TEXT,
+      applied_at    TEXT
+    );
+    CREATE INDEX IF NOT EXISTS spec_learning_change
+      ON spec_learning_candidates(change_id, status, proposed_at);
+  `);
+  return changed;
+}
+
 function tableSupportsKimi(db, table) {
   const row = db.prepare(
     "SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?",
@@ -94,11 +145,9 @@ function tableSupportsKimi(db, table) {
   return typeof row?.sql === 'string' && row.sql.includes("'kimi'");
 }
 
-function upgradeRuntimeConstraints(db) {
+function upgradeRuntimeConstraints(db, fromVersion = latestSchemaVersion(db)) {
   if (tableSupportsKimi(db, 'events') && tableSupportsKimi(db, 'sessions')) return false;
-  const previousVersion = db.prepare(
-    'SELECT version FROM schema_version ORDER BY applied_at DESC LIMIT 1',
-  ).get()?.version || 'unknown';
+  const previousVersion = fromVersion || 'unknown';
   const foreignKeys = db.pragma('foreign_keys', { simple: true });
   db.pragma('foreign_keys = OFF');
   try {
@@ -155,7 +204,7 @@ function upgradeRuntimeConstraints(db) {
          VALUES (?, ?, 'forward', 'success', ?)`,
       ).run(
         previousVersion,
-        EXPECTED_VERSION,
+        KIMI_SCHEMA_VERSION,
         'Add Kimi to durable event and session runtime constraints',
       );
       const violations = db.pragma('foreign_key_check');
@@ -169,15 +218,27 @@ function upgradeRuntimeConstraints(db) {
   return true;
 }
 
-function applyCompatibleUpgrades(db) {
-  upgradeRuntimeConstraints(db);
+function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db)) {
+  const runtimeChanged = upgradeRuntimeConstraints(db, fromVersion);
   db.transaction(() => {
     applyCompatibleColumns(db);
+    const contextChanged = applyContextSpineUpgrade(db);
+    if (contextChanged || (fromVersion && fromVersion !== EXPECTED_VERSION)) {
+      db.prepare(
+        `INSERT INTO migration_history
+          (from_version, to_version, direction, status, notes)
+         VALUES (?, ?, 'forward', 'success', ?)`,
+      ).run(
+        runtimeChanged ? KIMI_SCHEMA_VERSION : (fromVersion || 'unknown'),
+        EXPECTED_VERSION,
+        'Add Context Spine role/gate readiness, execution contracts, breadcrumbs, and specification learning',
+      );
+    }
     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, 'Kimi runtime support with durable event and session state');
+    ).run(EXPECTED_VERSION, 'Role-scoped context snapshots, deterministic breadcrumbs, and approval-gated specification learning');
   })();
 }
 
@@ -199,12 +260,13 @@ function ensureSchemaVersion(db) {
 function initStateDb(dbPath) {
   const db = openStateDb(dbPath);
   const existing = new Set(tableNames(db));
+  const fromVersion = latestSchemaVersion(db);
   applyCompatibleColumns(db);
   const missing = REQUIRED_TABLES.filter((t) => !existing.has(t));
   if (missing.length > 0) {
     applySchema(db);
   }
-  applyCompatibleUpgrades(db);
+  applyCompatibleUpgrades(db, fromVersion);
   const version = ensureSchemaVersion(db);
   return {
     db,

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

@@ -123,7 +123,7 @@ test('initStateDb migrates existing runtime constraints to Kimi without losing r
     const legacy = openStateDb(file);
     const legacySchema = fs.readFileSync(SCHEMA_FILE, 'utf8').replaceAll(", 'kimi'", '');
     legacy.exec(legacySchema);
-    legacy.prepare("DELETE FROM schema_version WHERE version = '9.1'").run();
+    legacy.prepare("DELETE FROM schema_version WHERE version IN ('9.1', '10.0')").run();
     legacy.prepare(
       "INSERT INTO tasks (id, title, type, priority) VALUES ('task-old', 'Old', 'feature', 'P1')",
     ).run();
@@ -146,11 +146,16 @@ test('initStateDb migrates existing runtime constraints to Kimi without losing r
     closeStateDb(legacy);
 
     const upgraded = initStateDb(file);
-    assert.equal(upgraded.schema_version, '9.1');
+    assert.equal(upgraded.schema_version, '10.0');
     assert.equal(upgraded.db.prepare("SELECT runtime FROM sessions WHERE sid = 'session-old'").get().runtime, 'codex');
     assert.equal(upgraded.db.prepare("SELECT COUNT(*) AS n FROM telemetry WHERE session_id = 'session-old'").get().n, 1);
     assert.equal(upgraded.db.prepare("SELECT COUNT(*) AS n FROM incidents WHERE session_id = 'session-old'").get().n, 1);
     assert.deepEqual(upgraded.db.pragma('foreign_key_check'), []);
+    const migrations = upgraded.db.prepare(
+      "SELECT to_version, notes FROM migration_history WHERE to_version IN ('9.1', '10.0') ORDER BY id",
+    ).all();
+    assert.ok(migrations.some((row) => row.to_version === '9.1' && /Kimi/.test(row.notes)));
+    assert.ok(migrations.some((row) => row.to_version === '10.0' && /Context Spine/.test(row.notes)));
 
     upgraded.db.prepare(
       "INSERT INTO tasks (id, title, type, priority) VALUES ('task-kimi', 'Kimi', 'feature', 'P1')",

package/mcp-server/server.cjs

@@ -73,6 +73,9 @@ const CHANGE_TOOLS = Object.freeze([
   'change.get',
   'change.list',
   'change.context',
+  'change.breadcrumb',
+  'change.learning_propose',
+  'change.learning_resolve',
   'change.converge',
   'change.archive',
 ]);
@@ -95,6 +98,7 @@ const MUTATING_TOOLS = new Set([
   'session.spawn', 'session.close', 'session.heartbeat',
   'plan.export',
   'change.create', 'change.update', 'change.context', 'change.converge', 'change.archive',
+  'change.learning_propose', 'change.learning_resolve',
 ]);
 
 function loadRegisteredTools() {
@@ -368,7 +372,12 @@ async function dispatchTool(name, input, db, ctx = {}) {
         err.code = 'CHANGE_NOT_FOUND';
         throw err;
       }
-      return { change };
+      return {
+        change: {
+          ...change,
+          learning_candidates: changes.listSpecLearning(db, change.id),
+        },
+      };
     }
     case 'change.list': {
       const rows = changes.listChanges(db, input || {});
@@ -382,6 +391,27 @@ async function dispatchTool(name, input, db, ctx = {}) {
         manifest: out.manifest,
       };
     }
+    case 'change.breadcrumb': {
+      return {
+        breadcrumb: changes.readBreadcrumb(
+          db, input || {}, { rootDir: ctx.rootDir || process.cwd() },
+        ),
+      };
+    }
+    case 'change.learning_propose': {
+      return {
+        candidate: changes.proposeSpecLearning(
+          db, input, { rootDir: ctx.rootDir || process.cwd() },
+        ),
+      };
+    }
+    case 'change.learning_resolve': {
+      return {
+        candidate: changes.resolveSpecLearning(
+          db, input, { rootDir: ctx.rootDir || process.cwd() },
+        ),
+      };
+    }
     case 'change.converge': {
       return changes.convergeChange(db, input, { rootDir: ctx.rootDir || process.cwd() });
     }

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

@@ -11,7 +11,7 @@ const Database = require('better-sqlite3');
 
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
 const CLI = path.join(REPO_ROOT, 'ultra-tools', 'cli.cjs');
-const { initStateDb, closeStateDb } = require('../lib/state-db.cjs');
+const { EXPECTED_VERSION, initStateDb, closeStateDb } = require('../lib/state-db.cjs');
 const ops = require('../lib/state-ops.cjs');
 
 function tmpDir() {
@@ -97,8 +97,8 @@ test('db backup writes a file that opens independently with the same schema', ()
 
     // Independently open the backup with a fresh connection
     const snap = new Database(backupPath);
-    const v = snap.prepare("SELECT version FROM schema_version").get();
-    assert.equal(v.version, '4.5');
+    const v = snap.prepare('SELECT version FROM schema_version WHERE version = ?').get(EXPECTED_VERSION);
+    assert.equal(v.version, EXPECTED_VERSION);
     const t = snap.prepare("SELECT id FROM tasks WHERE id = 'b-1'").get();
     assert.equal(t.id, 'b-1');
     snap.close();

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

@@ -75,10 +75,13 @@ test('listTools returns workflow tools and exposes no Ultra memory API', async (
       const names = list.tools.map((t) => t.name).sort();
       assert.deepEqual(names, [
         'change.archive',
+        'change.breadcrumb',
         'change.context',
         'change.converge',
         'change.create',
         'change.get',
+        'change.learning_propose',
+        'change.learning_resolve',
         'change.list',
         'change.update',
         'plan.export',
@@ -142,9 +145,19 @@ test('change.create + change.context expose a continuous change unit with extern
         name: 'change.context', arguments: { id: 'mcp-change' },
       }));
       assert.equal(context.manifest.change.id, 'mcp-change');
+      assert.equal(context.manifest.schema_version, '2.0');
+      assert.equal(context.manifest.role, 'plan');
+      assert.equal(context.manifest.readiness.status, 'ready');
       assert.equal(context.manifest.providers.memory.provider, 'cloud-mem');
       assert.equal(context.manifest.provider_boundary.includes('content remain external'), true);
 
+      const breadcrumb = readToolPayload(await client.callTool({
+        name: 'change.breadcrumb', arguments: { id: 'mcp-change' },
+      }));
+      assert.equal(breadcrumb.breadcrumb.change_id, 'mcp-change');
+      assert.equal(breadcrumb.breadcrumb.recommended_workflow, 'ultra-change');
+      assert.match(breadcrumb.breadcrumb.context_manifest_hash, /^[0-9a-f]{64}$/);
+
       const listed = readToolPayload(await client.callTool({
         name: 'change.list', arguments: { status: 'active' },
       }));
@@ -156,6 +169,67 @@ test('change.create + change.context expose a continuous change unit with extern
   }
 });
 
+test('spec-learning MCP tools persist an approval-gated candidate and projection', async () => {
+  const proj = tmpProject();
+  try {
+    await withClient(proj, async (client) => {
+      await client.callTool({
+        name: 'change.create',
+        arguments: {
+          id: 'learning-change', title: 'Learn stable contract', kind: 'quick',
+          intent: 'Persist only approved specification discoveries.',
+          docs_impact: { status: 'none', files: [], rationale: 'Contract fixture.' },
+        },
+      });
+      await client.callTool({
+        name: 'task.create',
+        arguments: {
+          id: 'learning-task', title: 'Discover contract', type: 'feature', priority: 'P1',
+          change_id: 'learning-change',
+        },
+      });
+      const proposed = readToolPayload(await client.callTool({
+        name: 'change.learning_propose',
+        arguments: {
+          id: 'learning-contract', change_id: 'learning-change', task_id: 'learning-task',
+          target_ref: 'README.md#contract', summary: 'Context compilation fails closed on stale refs.',
+          evidence: ['node --test context-spine.test.cjs'],
+        },
+      }));
+      assert.equal(proposed.candidate.status, 'proposed');
+      const withLearning = readToolPayload(await client.callTool({
+        name: 'change.get', arguments: { id: 'learning-change' },
+      }));
+      assert.deepEqual(
+        withLearning.change.learning_candidates.map((candidate) => candidate.id),
+        ['learning-contract'],
+      );
+
+      const approved = readToolPayload(await client.callTool({
+        name: 'change.learning_resolve',
+        arguments: {
+          change_id: 'learning-change', candidate_id: 'learning-contract', decision: 'approve',
+          resolution: 'Stable behavior contract.',
+        },
+      }));
+      assert.equal(approved.candidate.status, 'approved');
+      const applied = readToolPayload(await client.callTool({
+        name: 'change.learning_resolve',
+        arguments: {
+          change_id: 'learning-change', candidate_id: 'learning-contract', decision: 'apply',
+          resolution: 'Applied to README.md#contract.',
+        },
+      }));
+      assert.equal(applied.candidate.status, 'applied');
+      assert.ok(fs.existsSync(path.join(
+        proj.dir, '.ultra', 'changes', 'active', 'learning-change', 'spec-learning.json',
+      )));
+    });
+  } finally {
+    fs.rmSync(proj.dir, { recursive: true, force: true });
+  }
+});
+
 test('system.doctor returns structured provider ownership and projection health', async () => {
   const proj = tmpProject();
   try {

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

@@ -8,7 +8,7 @@ const path = require('node:path');
 
 const stateDb = require('../lib/state-db.cjs');
 
-test('initStateDb upgrades a pre-9.1 database in place with task/event change linkage', () => {
+test('initStateDb upgrades a pre-10.0 database in place with Context Spine state', () => {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-db-upgrade-'));
   const file = path.join(dir, 'state.db');
   try {
@@ -59,8 +59,25 @@ test('initStateDb upgrades a pre-9.1 database in place with task/event change li
     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.1');
-    assert.ok(upgraded.db.prepare("SELECT 1 FROM schema_version WHERE version = '9.1'").get());
+    assert.equal(upgraded.schema_version, '10.0');
+    assert.ok(upgraded.db.prepare("SELECT 1 FROM schema_version WHERE version = '10.0'").get());
+    const contextColumns = upgraded.db.prepare('PRAGMA table_info(context_snapshots)').all()
+      .map((row) => row.name);
+    for (const column of ['role', 'gate', 'next_action', 'readiness', 'context_json', 'token_budget']) {
+      assert.ok(contextColumns.includes(column), column);
+    }
+    assert.ok(upgraded.db.prepare(
+      "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'spec_learning_candidates'",
+    ).get());
+    const contextMigration = upgraded.db.prepare(
+      "SELECT from_version, to_version, notes FROM migration_history WHERE to_version = '10.0' ORDER BY id DESC LIMIT 1",
+    ).get();
+    assert.equal(contextMigration.from_version, '9.1');
+    assert.equal(contextMigration.to_version, '10.0');
+    assert.match(contextMigration.notes, /Context Spine/);
+    assert.ok(upgraded.db.prepare(
+      "SELECT 1 FROM migration_history WHERE from_version = '8A.1' AND to_version = '9.1' AND notes LIKE '%Kimi%'",
+    ).get());
     stateDb.closeStateDb(upgraded.db);
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.9.0",
+  "version": "0.10.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/learn/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: learn
 description: "Extract one reusable pattern from the current session into a valid user skill, with explicit user approval before writing."
+user-invocable: true
 ---
 
 # learn — Phase 3.6

package/skills/ultra-change/SKILL.md

@@ -1,6 +1,7 @@
 ---
 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."
+description: "Open or resume a continuous change, capture its delta and decisions, compile bounded role context, and route one executable slice."
+user-invocable: true
 runtime: all
 mcp_tools_required:
   - change.create
@@ -8,142 +9,114 @@ mcp_tools_required:
   - change.get
   - change.list
   - change.context
+  - change.breadcrumb
+  - change.learning_propose
+  - change.learning_resolve
   - task.create
   - task.list
 ---
 
-# ultra-change — Continuous Change Entry
+# ultra-change — Delta Entry and Alignment Gate
 
-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.
+Use this after the first baseline delivery for fixes, small features, redesigns,
+incidents, and maintenance. It keeps specifications live through a delta → implement
+→ learn → converge loop.
 
-## Authority and provider boundary
+## Authority 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.
+All change and task lifecycle writes use the live MCP tools. Do not write raw SQLite
+or mutate generated task/context projections. Provider payloads stay in their owning
+memory or graph system; Ultra stores metadata references only.
 
-## Arguments
+## 1. Establish the change
 
-- `$1`: existing change id, or a short title for a new change.
-- Optional flags/concepts: `quick`, `standard`, `major`, `incident` and an
-  explicit documentation impact.
+Call `change.list` and `change.breadcrumb` first.
 
-## 1. Resume before creating
+- Resume the single matching active/blocked change.
+- If several may match, require an explicit id.
+- Otherwise auto-discover repository facts, then ask only the highest-value unresolved
+  question. Do not ask the user for branch, stack, paths, or behavior already visible.
 
-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.
+Capture:
 
-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.
+- observable problem or requested outcome;
+- acceptance and explicit non-goals;
+- affected public seam or integration boundary;
+- documentation impact: `required` paths, `none` with rationale, or blocking `unknown`;
+- kind: `quick`, `standard`, `major`, or `incident`;
+- decision inventory: accepted decisions, rejected alternatives, and unresolved choices.
 
-## 2. Classify the change
+Create with `change.create` using a stable kebab-case id. Update an existing packet
+with `change.update`; never create a parallel packet for the same outcome.
 
-Choose the smallest honest kind:
+## 2. Write only the delta
 
-| 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` | canonical debug lane for a production/runtime failure | diagnosis, diff, tests |
+The bounded packet is:
 
-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:
+```text
+.ultra/changes/active/<change-id>/
+  intent.md
+  delta/                 # standard and major
+  plan.md                # standard and major
+  diagnosis.md           # incident
+  context-manifest.json  # MCP projection
+  spec-learning.json     # MCP projection
+  verification.md        # convergence projection
+```
 
-- `required`: list every baseline document expected to change;
-- `none`: provide a concrete rationale;
-- `unknown`: allowed only while investigating and blocks convergence.
+`intent.md` records outcome, acceptance, non-goals, docs impact, and decisions.
+Delta files describe only differences from the baseline. An incident diagnosis must
+record symptom, earliest bad state, root-cause hypothesis, discriminating evidence,
+and recovery boundary.
+
+## 3. Create an executable slice
+
+Prefer the smallest vertical `tracer_bullet` that crosses a live public seam. Split
+only when ownership or verification is genuinely independent. Each task must declare:
+
+- one observable outcome and linked `change_id`;
+- bounded files/contracts and dependencies;
+- `public_seam` that proves reachability;
+- exact `verification_command`;
+- expected red signal for a bug/incident;
+- documentation impact.
+
+Persist tasks with `task.create`. Generated `tasks.json` is never an input authority.
+
+## 4. Compile Context Manifest v2
+
+Call `change.context` for the next task with:
+
+```json
+{
+  "id": "<change-id>",
+  "task_id": "<task-id>",
+  "role": "plan",
+  "gate": "planning",
+  "context_refs": [{"ref":"<path>","kind":"spec","reason":"defines acceptance","required":true}],
+  "budget": {"max_tokens":12000,"max_files":12},
+  "execution_contract": {
+    "slice_kind":"tracer_bullet",
+    "public_seam":"<reachable boundary>",
+    "verification_command":"<exact command>",
+    "context_budget_percent":40
+  }
+}
+```
 
-Create the change with `change.create`. Use a stable kebab-case id. External
-provider references are optional and metadata-only.
+Include only files needed for the current role and gate. Missing required references,
+digest drift, file-count overflow, or a fresh-context budget over 40% blocks readiness.
+Use `expand_contract` only for an explicitly approved wider slice.
 
-## 4. Build the delta packet
+## 5. Handle discoveries without silent spec drift
 
-The change directory is the bounded execution packet:
+When implementation reveals a stable requirement, invariant, or public behavior not
+in the baseline, call `change.learning_propose` with evidence and target document.
+It is a candidate, not an automatic edit. A human/primary-agent decision must approve
+or reject it; approved learning is marked applied only after the baseline was updated.
 
-```text
-.ultra/changes/active/<change-id>/
-  intent.md
-  context-manifest.json
-  delta/                  # required for standard and major
-  plan.md                 # required for standard and major
-  diagnosis.md            # created and structurally required for incident
-  verification.md         # generated by convergence
-```
+## Exit contract
 
-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`, add only artifacts needed to make the decision and
-evidence inspectable. For `incident`, complete the generated `diagnosis.md` with
-non-empty `Reproduction`, `Hypotheses`, `Root cause`, `Regression test`, and
-`Recovery` sections. Free-form convergence evidence never substitutes for this
-durable diagnosis artifact.
-
-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
-
-- For `incident`, diagnosis is the first execution slice. Route it to the bundled
-  `debugger` agent when the Host exposes native subagents; otherwise the primary
-  Host follows the same four-phase method. Supply only the compiled change/task
-  context. The primary Host owns the fix, updates `diagnosis.md`, and reruns the
-  discriminating regression test.
-- 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.
+Call `change.breadcrumb` and report the compiled task, readiness, blockers, and its
+single next action. Do not claim alignment while documentation impact is unknown,
+context is stale, or a material decision remains unresolved.