ultra-builder-pro-cli 0.9.0 → 0.11.0

package/mcp-server/lib/spec-learning.cjs

@@ -0,0 +1,191 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ops = require('./state-ops.cjs');
+
+const CANDIDATE_ID = /^[a-zA-Z0-9_-]+$/;
+const TRANSITIONS = Object.freeze({
+  proposed: new Set(['approved', 'rejected']),
+  approved: new Set(['applied', 'rejected']),
+  rejected: new Set(),
+  applied: new Set(),
+});
+
+class SpecLearningError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'SpecLearningError';
+    this.code = code;
+  }
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function rowToCandidate(row) {
+  if (!row) return null;
+  let evidence;
+  try { evidence = JSON.parse(row.evidence_json); }
+  catch (error) {
+    throw new SpecLearningError('STATE_CORRUPT', `invalid spec-learning evidence: ${error.message}`);
+  }
+  const candidate = { ...row, evidence };
+  delete candidate.evidence_json;
+  return candidate;
+}
+
+function listSpecLearning(db, changeId) {
+  return db.prepare(
+    'SELECT * FROM spec_learning_candidates WHERE change_id = ? ORDER BY proposed_at ASC, id ASC',
+  ).all(changeId).map(rowToCandidate);
+}
+
+function writeAtomic(file, contents) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.tmp-${process.pid}-${Date.now()}`;
+  fs.writeFileSync(temporary, contents);
+  fs.renameSync(temporary, file);
+}
+
+function upsertProjectionArtifact(db, change, rootDir, candidates) {
+  const file = path.resolve(rootDir, change.artifact_root, 'spec-learning.json');
+  const generatedAt = candidates.reduce((latest, candidate) => (
+    [candidate.applied_at, candidate.resolved_at, candidate.proposed_at]
+      .filter(Boolean)
+      .reduce((value, timestamp) => (timestamp > value ? timestamp : value), latest)
+  ), '1970-01-01T00:00:00.000Z');
+  const payload = {
+    schema_version: '1.0',
+    source: '.ultra/state.db',
+    change_id: change.id,
+    generated_at: generatedAt,
+    candidates,
+  };
+  const serialized = `${JSON.stringify(payload, null, 2)}\n`;
+  writeAtomic(file, serialized);
+  const relative = path.relative(rootDir, file);
+  const hash = crypto.createHash('sha256').update(serialized).digest('hex');
+  db.prepare(
+    `INSERT INTO artifacts (id, change_id, kind, path, content_hash, metadata_json)
+     VALUES (?, ?, 'spec_learning', ?, ?, ?)
+     ON CONFLICT(change_id, kind, path) DO UPDATE SET
+       content_hash = excluded.content_hash,
+       metadata_json = excluded.metadata_json,
+       updated_at = excluded.updated_at`,
+  ).run(
+    `art-${crypto.randomUUID().slice(0, 12)}`, change.id, relative, hash,
+    JSON.stringify({ candidates: candidates.length }),
+  );
+  return { path: file, hash };
+}
+
+function mutableChange(db, changeId) {
+  const change = db.prepare('SELECT * FROM changes WHERE id = ?').get(changeId);
+  if (!change) throw new SpecLearningError('CHANGE_NOT_FOUND', `change ${changeId} not found`);
+  if (!['active', 'blocked'].includes(change.status)) {
+    throw new SpecLearningError(
+      'CHANGE_NOT_MUTABLE', `change ${changeId} is ${change.status}; learning must resolve before convergence`,
+    );
+  }
+  return change;
+}
+
+function normalizeEvidence(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string' || !entry.trim())) {
+    throw new SpecLearningError('VALIDATION_ERROR', 'spec-learning evidence must be non-empty strings');
+  }
+  return [...new Set(value.map((entry) => entry.trim()))];
+}
+
+function proposeSpecLearning(db, input, { rootDir = process.cwd() } = {}) {
+  const change = mutableChange(db, input.change_id);
+  const id = String(input.id || `learning-${crypto.randomUUID().slice(0, 12)}`).trim();
+  if (!CANDIDATE_ID.test(id)) {
+    throw new SpecLearningError('VALIDATION_ERROR', `invalid spec-learning candidate id: ${id}`);
+  }
+  const targetRef = typeof input.target_ref === 'string' ? input.target_ref.trim() : '';
+  const summary = typeof input.summary === 'string' ? input.summary.trim() : '';
+  if (!targetRef || !summary) {
+    throw new SpecLearningError('VALIDATION_ERROR', 'target_ref and summary are required');
+  }
+  if (input.task_id) {
+    const task = db.prepare('SELECT change_id FROM tasks WHERE id = ?').get(input.task_id);
+    if (!task || task.change_id !== change.id) {
+      throw new SpecLearningError('TASK_NOT_FOUND', `task ${input.task_id} is not linked to change ${change.id}`);
+    }
+  }
+  const evidence = normalizeEvidence(input.evidence);
+  const proposedAt = nowIso();
+  return ops.tx(db, () => {
+    try {
+      db.prepare(
+        `INSERT INTO spec_learning_candidates
+         (id, change_id, task_id, target_ref, summary, evidence_json, proposed_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      ).run(id, change.id, input.task_id || null, targetRef, summary, JSON.stringify(evidence), proposedAt);
+    } catch (error) {
+      if (String(error.message).includes('UNIQUE')) {
+        throw new SpecLearningError('DUPLICATE_LEARNING_ID', `spec-learning candidate ${id} exists`);
+      }
+      throw error;
+    }
+    ops.appendEventInTx(db, {
+      type: 'spec_learning_proposed', change_id: change.id, task_id: input.task_id || null,
+      payload: { candidate_id: id, target_ref: targetRef },
+    });
+    const candidates = listSpecLearning(db, change.id);
+    upsertProjectionArtifact(db, change, rootDir, candidates);
+    return candidates.find((candidate) => candidate.id === id);
+  });
+}
+
+function resolveSpecLearning(db, input, { rootDir = process.cwd() } = {}) {
+  const change = mutableChange(db, input.change_id);
+  const current = rowToCandidate(db.prepare(
+    'SELECT * FROM spec_learning_candidates WHERE id = ? AND change_id = ?',
+  ).get(input.candidate_id, change.id));
+  if (!current) {
+    throw new SpecLearningError('LEARNING_NOT_FOUND', `candidate ${input.candidate_id} not found`);
+  }
+  const status = { approve: 'approved', reject: 'rejected', apply: 'applied' }[input.decision];
+  if (!status) throw new SpecLearningError('VALIDATION_ERROR', `invalid learning decision: ${input.decision}`);
+  if (!TRANSITIONS[current.status].has(status)) {
+    throw new SpecLearningError(
+      'ILLEGAL_LEARNING_TRANSITION', `cannot move candidate ${current.id} from ${current.status} to ${status}`,
+    );
+  }
+  const resolution = typeof input.resolution === 'string' ? input.resolution.trim() : '';
+  if (['rejected', 'applied'].includes(status) && !resolution) {
+    throw new SpecLearningError('VALIDATION_ERROR', `${input.decision} requires a resolution`);
+  }
+  const timestamp = nowIso();
+  return ops.tx(db, () => {
+    db.prepare(
+      `UPDATE spec_learning_candidates
+       SET status = ?, resolution = ?, resolved_at = ?, applied_at = ?
+       WHERE id = ? AND change_id = ?`,
+    ).run(
+      status, resolution || null, timestamp, status === 'applied' ? timestamp : null,
+      current.id, change.id,
+    );
+    ops.appendEventInTx(db, {
+      type: 'spec_learning_resolved', change_id: change.id, task_id: current.task_id,
+      payload: { candidate_id: current.id, decision: input.decision, status },
+    });
+    const candidates = listSpecLearning(db, change.id);
+    upsertProjectionArtifact(db, change, rootDir, candidates);
+    return candidates.find((candidate) => candidate.id === current.id);
+  });
+}
+
+module.exports = {
+  SpecLearningError,
+  listSpecLearning,
+  proposeSpecLearning,
+  resolveSpecLearning,
+};

package/mcp-server/lib/spec-learning.test.cjs

@@ -0,0 +1,62 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const { initStateDb, closeStateDb } = require('./state-db.cjs');
+const changes = require('./change-workflow.cjs');
+const learning = require('./spec-learning.cjs');
+
+function fixture() {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-learning-'));
+  execFileSync('git', ['init', '-q'], { cwd: rootDir });
+  execFileSync('git', ['config', 'user.email', 'test@ubp.dev'], { cwd: rootDir });
+  execFileSync('git', ['config', 'user.name', 'ubp-test'], { cwd: rootDir });
+  fs.writeFileSync(path.join(rootDir, 'README.md'), '# Fixture\n');
+  execFileSync('git', ['add', 'README.md'], { cwd: rootDir });
+  execFileSync('git', ['commit', '-q', '-m', 'seed'], { cwd: rootDir });
+  const { db } = initStateDb(path.join(rootDir, '.ultra', 'state.db'));
+  changes.createChange(db, {
+    id: 'learning-change', title: 'Learning change', kind: 'quick',
+    intent: 'Exercise guarded specification-learning transitions.',
+  }, { rootDir });
+  return { rootDir, db };
+}
+
+test('spec learning cannot skip approval or mutate after apply', () => {
+  const fx = fixture();
+  try {
+    learning.proposeSpecLearning(fx.db, {
+      id: 'candidate-1', change_id: 'learning-change', target_ref: 'README.md',
+      summary: 'A stable public contract was discovered.',
+    }, { rootDir: fx.rootDir });
+    assert.throws(
+      () => learning.resolveSpecLearning(fx.db, {
+        change_id: 'learning-change', candidate_id: 'candidate-1', decision: 'apply',
+        resolution: 'Applied.',
+      }, { rootDir: fx.rootDir }),
+      (error) => error.code === 'ILLEGAL_LEARNING_TRANSITION',
+    );
+    learning.resolveSpecLearning(fx.db, {
+      change_id: 'learning-change', candidate_id: 'candidate-1', decision: 'approve',
+    }, { rootDir: fx.rootDir });
+    learning.resolveSpecLearning(fx.db, {
+      change_id: 'learning-change', candidate_id: 'candidate-1', decision: 'apply',
+      resolution: 'Applied to README.md.',
+    }, { rootDir: fx.rootDir });
+    assert.throws(
+      () => learning.resolveSpecLearning(fx.db, {
+        change_id: 'learning-change', candidate_id: 'candidate-1', decision: 'reject',
+        resolution: 'Too late.',
+      }, { rootDir: fx.rootDir }),
+      (error) => error.code === 'ILLEGAL_LEARNING_TRANSITION',
+    );
+  } finally {
+    closeStateDb(fx.db);
+    fs.rmSync(fx.rootDir, { recursive: true, force: true });
+  }
+});

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.11.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/AGENT-CONTEXT.md",
+    "docs/SKILL-AUTHORING.md",
     "docs/COMMIT-HASH-BACKFILL.md",
     "docs/PLAN.zh-CN.md",
     "docs/STATE-DB-ACCESS-POLICY.md",
@@ -87,7 +88,7 @@
     "test:state": "node --test 'mcp-server/**/*.test.cjs'",
     "test:orch": "node --test 'orchestrator/**/*.test.cjs'",
     "test:spec": "node spec/scripts/test-all.cjs",
-    "test:rest": "node --test adapters/_shared/tests/*.test.cjs adapters/tests/*.test.cjs ultra-tools/*.test.cjs tests/conformance/**/*.test.cjs tests/install.test.cjs tests/package-smoke.test.cjs tests/retired-runtime.test.cjs",
+    "test:rest": "node --test adapters/_shared/tests/*.test.cjs adapters/tests/*.test.cjs ultra-tools/*.test.cjs tests/conformance/**/*.test.cjs tests/*.test.cjs",
     "test:all": "npm run test:state && npm run test:orch && npm run test:spec && npm run test:rest",
     "test:hooks": "pytest hooks/tests -q",
     "verify:release": "npm run test:all && npm run test:hooks && npm audit --omit=dev --audit-level=high",