ultra-builder-pro-cli 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] — 2026-07-18
+
+### Added
+
+- Added Context Manifest v2 and a DB-derived Context Spine across planning,
+  implementation, checking, review, convergence, and recovery. Context snapshots
+  now carry role, gate, readiness blockers, bounded references and digests,
+  fresh-context budgets, a public seam, an exact verification command, and one
+  deterministic next action.
+- Added `change.breadcrumb`, `change.learning_propose`, and
+  `change.learning_resolve`, advancing the live MCP contract to 32 tools and
+  `.ultra/state.db` to schema 10.0 with 16 tables.
+- Added approval-gated specification-learning candidates. Proposed or approved
+  discoveries block convergence until rejected or applied to a declared baseline
+  target, and `change.get` exposes their authoritative state.
+- Added independent `spec_fidelity` and `engineering_standards` review evidence,
+  plus public-seam and exact red/green signal fields for convergence.
+
+### Changed
+
+- Rebuilt the daily harness around one status router, one highest-value alignment
+  question, fresh-context tracer bullets, explicit expand contracts, independent
+  check/review contexts, and convergence before release.
+- Reduced the seven core execution workflow prompts from 1,922 to 758 lines and
+  added a 220-line ceiling for every public Ultra skill so host prompts cannot
+  silently accumulate duplicated procedure. All twelve public workflows are now
+  explicitly user-invocable; four rule skills remain agent-only.
+- Session-start, pre-edit, and recovery hooks now share one read-only
+  `context_spine.py` helper and inject only the compact DB breadcrumb. Intent,
+  transcript, memory-provider, and graph-provider payloads never enter hook context.
+- OpenCode now consumes the DB-generated Context Manifest v2 projection, strips
+  provider/intent content, and fails context readiness when its compiled HEAD
+  differs from the current repository.
+- Updated Claude Code, Codex, OpenCode, and Kimi Code native renderings, managed
+  handbook blocks, MCP mapping, architecture, and compatibility documentation.
+
+### Fixed
+
+- Prevented plan-role task context from becoming ready without an execution
+  contract, public seam, and verification command.
+- Prevented breadcrumbs from reusing a snapshot after task state or git HEAD
+  changed, and made an explicitly missing change id fail closed.
+- Added auditable 9.1 → 10.0 migration history while preserving existing runtime
+  rows, references, projections, and foreign-key integrity.
+- Corrected hook conformance to package `context_spine.py` as an imported helper
+  without registering it as a duplicate lifecycle hook.
+
 ## [0.9.0] — 2026-07-17
 
 ### Added

package/README.md

@@ -8,7 +8,7 @@ authoritative `.ultra/state.db`.
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/version-0.9.0-blue)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.10.0-blue)](./CHANGELOG.md)
 [![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](#verification)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![Node](https://img.shields.io/badge/node-%E2%89%A522-informational)](./package.json)
@@ -36,8 +36,10 @@ authoritative `.ultra/state.db`.
 - **Runs real PRDs end-to-end.** `task.parse_prd` → `lib/topo.cjs` waves →
   `.ultra/execution-plan.json` → parallel worktree sessions → auto-merge back.
 - **Keeps daily work convergent.** `/ultra-change` creates a bounded delta and
-  context manifest; `/ultra-deliver` requires docs/test/review evidence and
-  baseline reconciliation before archive. `/ultra-doctor` reports incidents,
+  Context Manifest v2; the Context Spine assigns a role/gate, verifies required
+  references and fresh-context budget, exposes one DB-derived breadcrumb, and
+  routes a single next action. `/ultra-deliver` requires applied specification
+  learning plus docs/test/two-axis review evidence before archive. `/ultra-doctor` reports incidents,
   projection lag, orphan sessions, and backup-first mechanical recovery.
   Incident changes additionally require a five-section `diagnosis.md` covering
   reproduction, hypotheses, root cause, regression test, and recovery.
@@ -91,7 +93,7 @@ for per-runtime capabilities.
 The layers share one `.ultra/state.db`, but the CLI is not a mirror of every MCP
 tool: continuous change mutations are MCP-only and fail closed. See
 [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) for the full contract and
-[`spec/cli-protocol.md`](./spec/cli-protocol.md) for the 29 live contracts.
+[`spec/cli-protocol.md`](./spec/cli-protocol.md) for the 32 live contracts.
 Review, impact discovery, skill resolution, and user interaction stay on each
 Host's native surfaces; the generated Codex capability map documents those
 replacements without advertising non-existent MCP tools.
@@ -137,8 +139,11 @@ ultra-tools system doctor
 
 Or let the skills drive it. In Codex, invoke
 `$ultra-builder-pro:ultra-plan` → `$ultra-builder-pro:ultra-dev` →
-`$ultra-builder-pro:ultra-status`; after the baseline is delivered, daily work
-starts with `$ultra-builder-pro:ultra-change`. Kimi uses the corresponding
+`$ultra-builder-pro:ultra-test` → `$ultra-builder-pro:ultra-review` →
+`$ultra-builder-pro:ultra-deliver`; after the baseline is delivered, daily work
+starts with `$ultra-builder-pro:ultra-change`, while
+`$ultra-builder-pro:ultra-status` reads the compact authoritative breadcrumb.
+Kimi uses the corresponding
 `/ultra-builder-pro:ultra-*` namespace. Other runtimes retain their native
 command form.
 

package/adapters/_shared/codex-assets.cjs

@@ -467,6 +467,16 @@ and does not require an interactive MCP or legacy CLI menu.
   }
 
   if (skillName === 'ultra-review') {
+    text = text.replace(
+      '# $ultra-builder-pro:ultra-review - Ultra Review System',
+      `# $ultra-builder-pro:ultra-review - Ultra Review System
+
+## Codex native worker contract
+
+Use the installed native Codex custom agents as bounded review workers. Dispatch independent
+workers concurrently, keep the current Codex task primary, and treat their JSON artifacts—not
+their conversational transcripts—as review evidence.`,
+    );
     text = text.replaceAll('### Phase 3: Background Execution', '### Phase 3: Parallel Native Agent Execution');
     text = text.replaceAll('**Step 4b: Launch coordinator in background:**', '**Step 4b: Delegate coordination:**');
     text = text.replaceAll('in **background mode** (`native parallel execution`)', 'concurrently with native Codex subagent orchestration');

package/adapters/_shared/handbook.cjs

@@ -60,6 +60,8 @@ function renderHandbook(runtime) {
     `- Collaboration boundary: ${value.collaboration}. The current host remains primary and owns final verification.`,
     `- Coordination boundary: ${value.coordination}.`,
     '- Authority: `.ultra/state.db` is the only durable Ultra authority for changes, tasks, sessions, events, incidents, projection state, telemetry, and review evidence. Generated JSON and Markdown are projections or workflow artifacts.',
+    '- Context Spine boundary: `change.context` compiles role/gate readiness, bounded references, fresh-context budget, public seam, verification command, and one next action. Hooks inject only the DB-derived `change.breadcrumb`; stale or blocked context must be recompiled.',
+    '- Specification learning boundary: stable implementation discoveries use approval-gated propose/approve-or-reject/apply transitions. Unresolved learning blocks convergence; review requires independent specification-fidelity and engineering-standards evidence.',
     '- Memory and graph boundary: Ultra Builder Pro does not capture prompts, transcripts, observations, summaries, cross-session memory, or code-graph content. Separately installed providers own that data; Ultra may store only their metadata references in a change context manifest.',
     '- Hook boundary: Ultra hooks observe workflow/change lifecycle only. Health/context may run when `.ultra/state.db` exists; projection protection is always authoritative, while edit/compact/stop/subagent enforcement remains active-workflow scoped. Generic command blocking and post-edit policy stay in user or repository governance.',
     '- Installation boundary: `ubp --doctor` is the read-only authority for installed asset provenance, content hashes, and host entry-point wiring; `system.doctor` remains scoped to project state and workflow recovery.',

package/adapters/_shared/runtime-assets.cjs

@@ -50,6 +50,7 @@ const RETIRED_SKILLS = Object.freeze([
 
 const WORKFLOW_HOOK_FILES = Object.freeze([
   'active_task_context.py',
+  'context_spine.py',
   'health_check.py',
   'pre_stop_check.py',
   'subagent_tracker.py',

package/adapters/_shared/tests/handbook.test.cjs

@@ -33,6 +33,9 @@ test('renders one common contract with host-native invocation syntax', () => {
     assert.match(rendered, /ultra-change/);
     assert.match(rendered, /ultra-doctor/);
     assert.match(rendered, /metadata references/);
+    assert.match(rendered, /Context Spine boundary/);
+    assert.match(rendered, /change\.breadcrumb/);
+    assert.match(rendered, /Specification learning boundary/);
     assert.doesNotMatch(rendered, /\.ultra\/memory|memory\.retain|memory\.recall/);
     assert.match(rendered, new RegExp(BEGIN_MARKER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
     assert.match(rendered, new RegExp(END_MARKER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));

package/adapters/_shared/tests/runtime-assets.test.cjs

@@ -83,6 +83,7 @@ test('code-review-expert and rule skills are internal, never implicitly exposed'
 test('workflow hook allowlist contains no memory, prompt capture, or generic policy hook', () => {
   assert.deepEqual(WORKFLOW_HOOK_FILES, [
     'active_task_context.py',
+    'context_spine.py',
     'health_check.py',
     'pre_stop_check.py',
     'subagent_tracker.py',

package/adapters/kimi.js

@@ -219,8 +219,8 @@ bundled files are bounded prompt templates, not separately registered host agent
       'Read `SUMMARY.json` only after this validation succeeds.',
     ].join('\n');
     text = text.replace(
-      /### Phase 3:[\s\S]*?### Phase 5: Report to User/,
-      `${executionContract}\n\n### Phase 5: Report to User`,
+      /#{2,3} Phase 3:[\s\S]*?#{2,3} Phase 5: Report to User/,
+      `${executionContract}\n\n## Phase 5: Report to User`,
     );
     text = text.replaceAll('Background Execution', 'Reviewer Execution');
     text = text.replaceAll('Wait & Coordinate', 'Validate & Coordinate');

package/adapters/opencode.js

@@ -336,25 +336,26 @@ function pluginSource() {
   return `// Managed by Ultra Builder Pro. Rebuild through the adapter; do not edit in place.
 import fs from "node:fs";
 import path from "node:path";
+import { execFileSync } from "node:child_process";
 
 const TERMINAL = new Set(["committed", "completed", "done", "cancelled"]);
 const TASKS_PROJECTION = ".ultra/tasks/tasks.json";
-const PROVIDER_FIELDS = new Set(["provider", "project", "reference", "revision", "indexed_head", "status"]);
-
-function providerMetadata(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
-  const clean = {};
-  for (const [kind, ref] of Object.entries(value)) {
-    if (!["memory", "code_graph"].includes(kind) || !ref || typeof ref !== "object" || Array.isArray(ref)) continue;
-    clean[kind] = Object.fromEntries(Object.entries(ref).filter(([key]) => PROVIDER_FIELDS.has(key)));
+
+function gitHead(root) {
+  try {
+    return execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
   }
-  return clean;
 }
 
 function findUltraContext(directory) {
   let current = path.resolve(directory);
   while (true) {
     const ultra = path.join(current, ".ultra");
+    const currentHead = gitHead(current);
     const workflowFile = path.join(ultra, "workflow-state.json");
     const statePresent = fs.existsSync(path.join(ultra, "state.db"));
     let workflow = null;
@@ -375,11 +376,36 @@ function findUltraContext(directory) {
         if (!fs.existsSync(manifestPath)) continue;
         try {
           const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
-          if (manifest?.change) changes.push({
-            ...manifest.change,
-            providers: providerMetadata(manifest.providers),
+          if (manifest?.change) {
+            const compiledHead = manifest.git?.head ?? null;
+            const legacyContext = manifest.schema_version !== "2.0";
+            const headStale = Boolean(compiledHead && currentHead && compiledHead !== currentHead);
+            const blockers = Array.isArray(manifest.readiness?.blockers)
+              ? [...manifest.readiness.blockers]
+              : [];
+            if (headStale && !blockers.includes("CONTEXT_HEAD_STALE")) blockers.push("CONTEXT_HEAD_STALE");
+            if (legacyContext && !blockers.includes("CONTEXT_SNAPSHOT_UPGRADE_REQUIRED")) {
+              blockers.unshift("CONTEXT_SNAPSHOT_UPGRADE_REQUIRED");
+            }
+            changes.push({
+            id: manifest.change.id,
+            kind: manifest.change.kind,
+            status: manifest.change.status,
+            role: manifest.role ?? "plan",
+            gate: manifest.gate ?? "alignment",
+            nextAction: legacyContext
+              ? "Recompile change.context to upgrade this legacy context snapshot."
+              : headStale
+              ? "Git HEAD changed after context compilation; recompile change.context."
+              : (manifest.next_action ?? "Inspect Ultra status."),
+            readiness: legacyContext || headStale ? "blocked" : (manifest.readiness?.status ?? "ready"),
+            blockers,
+            taskId: manifest.selected_task?.id ?? manifest.resume?.task_id ?? null,
+            taskStatus: manifest.selected_task?.status ?? manifest.resume?.task_status ?? null,
+            tokenEstimate: manifest.context?.token_estimate ?? 0,
             manifestPath: path.relative(current, manifestPath),
           });
+          }
         } catch (error) {
           process.stderr.write(\`[ultra-builder-pro] cannot read \${manifestPath}: \${error.message}\\n\`);
         }
@@ -410,13 +436,16 @@ function contextText(active) {
   if (active.changes.length > 0) {
     const change = active.changes[0];
     lines.push(
-      "[Ultra continuous change]",
+      "[Ultra context spine]",
       \`Project: \${active.root}\`,
       \`Change: \${change.id} (\${change.kind ?? "unknown"}, \${change.status ?? "active"})\`,
-      \`Title: \${change.title ?? "unknown"}\`,
-      \`Intent: \${change.intent ?? "unknown"}\`,
+      \`Task: \${change.taskId ?? "none"} (\${change.taskStatus ?? "none"})\`,
+      \`Role: \${change.role}\`,
+      \`Gate: \${change.gate}\`,
+      \`Readiness: \${change.readiness}\`,
+      ...(change.blockers.length > 0 ? [\`Blockers: \${change.blockers.join(", ")}\`] : []),
+      \`Next: \${change.nextAction}\`,
       \`Context manifest: \${change.manifestPath}\`,
-      \`External providers (metadata references only): \${JSON.stringify(change.providers)}\`,
     );
     if (active.changes.length > 1) lines.push(
       \`Active change count: \${active.changes.length}; resolve scope with change.list before mutation.\`,
@@ -429,7 +458,7 @@ function contextText(active) {
       "No active continuous change. Start daily work with the ultra-change workflow.",
     );
   }
-  lines.push("Authority: .ultra/state.db; generated JSON/Markdown are projections or artifacts.");
+  lines.push("Authority: .ultra/state.db; JSON/Markdown remain projections or evidence artifacts.");
   return lines.join("\\n");
 }
 

package/adapters/tests/claude.test.cjs

@@ -36,7 +36,10 @@ test('install builds the Claude-native plugin from the explicit Ultra allowlist'
 
     const hooks = JSON.parse(fs.readFileSync(path.join(target, 'hooks', 'hooks.json'), 'utf8'));
     const serialized = JSON.stringify(hooks);
-    for (const name of WORKFLOW_HOOK_FILES) assert.match(serialized, new RegExp(name.replace('.', '\\.')));
+    for (const name of WORKFLOW_HOOK_FILES.filter((value) => value !== 'context_spine.py')) {
+      assert.match(serialized, new RegExp(name.replace('.', '\\.')));
+    }
+    assert.ok(fs.existsSync(path.join(target, 'hooks', 'context_spine.py')));
     assert.doesNotMatch(serialized, /memory|recall|journal|observation_capture|user_prompt_capture|block_dangerous|post_edit_guard/);
     assert.match(serialized, /\$\{CLAUDE_PLUGIN_ROOT\}/);
   } finally {

package/adapters/tests/codex.test.cjs

@@ -198,9 +198,10 @@ test('plugin declares current Codex hooks and a project-local Ultra MCP server',
       'SubagentStart', 'SubagentStop',
     ].sort());
     const serializedHooks = JSON.stringify(hooks);
-    for (const feature of WORKFLOW_HOOK_FILES) {
+    for (const feature of WORKFLOW_HOOK_FILES.filter((value) => value !== 'context_spine.py')) {
       assert.match(serializedHooks, new RegExp(feature.replace('.', '\\.')));
     }
+    assert.ok(fs.existsSync(path.join(layout.pluginRoot, 'hooks', 'context_spine.py')));
     assert.doesNotMatch(serializedHooks, /memory|recall|journal|observation_capture|user_prompt_capture|block_dangerous|post_edit_guard/);
     assert.match(serializedHooks, /\$PLUGIN_ROOT\/hooks\/adapters\/codex\.py/);
     assert.match(serializedHooks, /apply_patch/);
@@ -231,8 +232,8 @@ test('plugin declares current Codex hooks and a project-local Ultra MCP server',
     const liveSpec = yaml.load(fs.readFileSync(path.join(layout.pluginRoot, 'spec', 'mcp-tools.yaml'), 'utf8'));
     const upstreamSpec = yaml.load(fs.readFileSync(path.join(layout.pluginRoot, 'spec', 'upstream-mcp-tools.yaml'), 'utf8'));
     const capabilityMap = JSON.parse(fs.readFileSync(path.join(layout.pluginRoot, 'spec', 'codex-capability-map.json'), 'utf8'));
-    assert.equal(liveSpec.tools.length, 29);
-    assert.equal(upstreamSpec.tools.length, 29);
+    assert.equal(liveSpec.tools.length, 32);
+    assert.equal(upstreamSpec.tools.length, 32);
     assert.deepEqual(upstreamSpec.tools.map((tool) => tool.name).sort(), liveSpec.tools.map((tool) => tool.name).sort());
     assert.deepEqual(capabilityMap.live_mcp_tools.sort(), liveSpec.tools.map((tool) => tool.name).sort());
     assert.equal(Object.keys(capabilityMap.codex_native_replacements).length, 9);

package/adapters/tests/kimi.test.cjs

@@ -85,7 +85,10 @@ test('Kimi manifest exposes native skills, commands, hooks, session bootstrap, a
 
     const hookText = JSON.stringify(manifest.hooks);
     assert.match(hookText, /hooks\/adapters\/kimi\.py/);
-    for (const hook of WORKFLOW_HOOK_FILES) assert.match(hookText, new RegExp(hook.replace('.', '\\.')));
+    for (const hook of WORKFLOW_HOOK_FILES.filter((value) => value !== 'context_spine.py')) {
+      assert.match(hookText, new RegExp(hook.replace('.', '\\.')));
+    }
+    assert.ok(fs.existsSync(path.join(pluginRoot, 'hooks', 'context_spine.py')));
     assert.doesNotMatch(hookText, /memory|recall|journal|prompt[_ -]?capture|block_dangerous|post_edit_guard/i);
 
     const commands = fs.readdirSync(path.join(pluginRoot, 'commands')).sort();
@@ -120,7 +123,8 @@ test('Kimi assets are allowlisted and adapted to native tools and paths', () =>
     );
     assert.match(learn, /~\/.kimi-code\/skills\/learned-<pattern-slug>-unverified\/SKILL\.md/);
     assert.match(review, /Kimi `AgentSwarm`/);
-    assert.match(review, /5 specialized reviewers/);
+    assert.match(review, /Five engineering specialists/);
+    assert.match(review, /axes\.spec_fidelity/);
     assert.doesNotMatch(review, /6 specialized|ALL 6/);
     assert.match(review, /\$KIMI_PLUGIN_ROOT\/agents\/review-code\.md/);
     assert.match(review, /`prompt_template` containing\s+`\{\{item\}\}`/);

package/adapters/tests/opencode.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 { execFileSync } = require('node:child_process');
 const { pathToFileURL } = require('node:url');
 
 const opencode = require('../opencode.js');
@@ -172,7 +173,8 @@ test('install writes a schema-safe opencode.json and keeps ownership outside hos
     assert.match(plugin, /throw new Error/);
     assert.match(plugin, /session\.compacted/);
     assert.doesNotMatch(plugin, /memory\.(?:retain|recall|reflect)|journal|observation|prompt[_ -]?capture/);
-    assert.match(plugin, /metadata references only/);
+    assert.match(plugin, /Ultra context spine/);
+    assert.doesNotMatch(plugin, /providerMetadata|External providers/);
   } finally {
     fs.rmSync(target, { recursive: true, force: true });
   }
@@ -189,18 +191,59 @@ test('OpenCode context covers active changes and projection writes are blocked f
 
     fs.mkdirSync(path.join(project, '.ultra'), { recursive: true });
     fs.writeFileSync(path.join(project, '.ultra', 'state.db'), 'owned-by-ultra');
+    execFileSync('git', ['init'], { cwd: project, stdio: 'ignore' });
+    fs.writeFileSync(path.join(project, 'app.txt'), 'initial\n');
+    execFileSync('git', ['add', 'app.txt'], { cwd: project, stdio: 'ignore' });
+    execFileSync('git', ['-c', 'user.name=Ultra Tests', '-c', 'user.email=ultra@example.invalid', 'commit', '-m', 'initial'], {
+      cwd: project, stdio: 'ignore',
+    });
+    const compiledHead = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: project, encoding: 'utf8' }).trim();
     const changeRoot = path.join(project, '.ultra', 'changes', 'active', 'daily-fix');
     fs.mkdirSync(changeRoot, { recursive: true });
     fs.writeFileSync(path.join(changeRoot, 'context-manifest.json'), JSON.stringify({
+      schema_version: '2.0',
       change: { id: 'daily-fix', title: 'Daily fix', kind: 'quick', status: 'active', intent: 'Fix drift' },
+      role: 'implement',
+      gate: 'implementation',
+      next_action: 'Run the exact regression test.',
+      readiness: { status: 'ready', blockers: [] },
+      git: { head: compiledHead },
+      selected_task: { id: 'daily-task', status: 'in_progress' },
+      context: { token_estimate: 1200, budget: { max_tokens: 8000, max_files: 8 } },
       providers: { memory: { provider: 'cloud-mem', status: 'available' } },
     }));
 
     const output = { system: [] };
     await plugin['experimental.chat.system.transform']({}, output);
-    assert.match(output.system.join('\n'), /Ultra continuous change/);
+    assert.match(output.system.join('\n'), /Ultra context spine/);
     assert.match(output.system.join('\n'), /daily-fix/);
-    assert.match(output.system.join('\n'), /metadata references only/);
+    assert.match(output.system.join('\n'), /daily-task/);
+    assert.match(output.system.join('\n'), /Role: implement/);
+    assert.match(output.system.join('\n'), /Gate: implementation/);
+    assert.match(output.system.join('\n'), /Readiness: ready/);
+    assert.match(output.system.join('\n'), /Run the exact regression test/);
+    assert.doesNotMatch(output.system.join('\n'), /Fix drift|cloud-mem/);
+
+    const manifestFile = path.join(changeRoot, 'context-manifest.json');
+    const legacyManifest = JSON.parse(fs.readFileSync(manifestFile, 'utf8'));
+    legacyManifest.schema_version = '1.0';
+    fs.writeFileSync(manifestFile, JSON.stringify(legacyManifest));
+    const legacyOutput = { system: [] };
+    await plugin['experimental.chat.system.transform']({}, legacyOutput);
+    assert.match(legacyOutput.system.join('\n'), /CONTEXT_SNAPSHOT_UPGRADE_REQUIRED/);
+    legacyManifest.schema_version = '2.0';
+    fs.writeFileSync(manifestFile, JSON.stringify(legacyManifest));
+
+    fs.writeFileSync(path.join(project, 'app.txt'), 'changed\n');
+    execFileSync('git', ['add', 'app.txt'], { cwd: project, stdio: 'ignore' });
+    execFileSync('git', ['-c', 'user.name=Ultra Tests', '-c', 'user.email=ultra@example.invalid', 'commit', '-m', 'change'], {
+      cwd: project, stdio: 'ignore',
+    });
+    const staleOutput = { system: [] };
+    await plugin['experimental.chat.system.transform']({}, staleOutput);
+    assert.match(staleOutput.system.join('\n'), /Readiness: blocked/);
+    assert.match(staleOutput.system.join('\n'), /CONTEXT_HEAD_STALE/);
+    assert.match(staleOutput.system.join('\n'), /recompile change\.context/);
 
     await assert.rejects(
       plugin['tool.execute.before'](

package/docs/AGENT-CONTEXT.md

@@ -44,14 +44,14 @@ reports are projections or workflow artifacts.
 
 ## 3. Live MCP and declared contracts
 
-`spec/mcp-tools.yaml` declares and the bundled server registers 29 tools across
+`spec/mcp-tools.yaml` declares and the bundled server registers 32 tools across
 five families:
 
 | Family | Live tools |
 |---|---|
 | `task.*` | create, update, list, get, switch_tag, delete, init_project, expand, parse_prd, dependency_topo, append_event, subscribe_events |
 | `session.*` | spawn, close, get, list, admission_check, heartbeat, subscribe_events |
-| `change.*` | create, update, get, list, context, converge, archive |
+| `change.*` | create, update, get, list, context, breadcrumb, learning_propose, learning_resolve, converge, archive |
 | `system.*` | doctor |
 | `plan.*` | export, get |
 
@@ -62,7 +62,26 @@ capability map documents those replacements.
 Any new MCP contract starts in `spec/mcp-tools.yaml` with valid and invalid
 fixtures. Do not add an ad-hoc server handler first.
 
-## 4. Native host presentation
+## 4. Context Spine contract
+
+Context Manifest v2 is a DB-backed role handoff, not a static codebase summary.
+`change.context` compiles required references, digests, readiness, context budget,
+public seam, exact verification command, and one next action for `plan`,
+`implement`, `check`, or `review`. The default fresh-context contract is at most
+12 files, about 12k tokens, and 40% of the host context; wider work must use an
+explicit `expand_contract`.
+
+`change.breadcrumb` is the only compact router. Hooks may inject its change/task,
+role, gate, readiness, blockers, and one next action. They must not inject intent
+bodies, transcripts, external memory, or graph payloads. Missing references,
+digest drift, HEAD drift, or budget overflow blocks readiness.
+
+Stable discoveries use `change.learning_propose`; they reach the baseline only
+through approve/reject/apply transitions in `change.learning_resolve`. Unresolved
+learning blocks convergence. Review contributes two independent axes,
+`spec_fidelity` and `engineering_standards`; neither can replace the other.
+
+## 5. Native host presentation
 
 | Host | Plugin form | Workflow entry | Hook form | Collaboration companions |
 |---|---|---|---|---|
@@ -75,9 +94,10 @@ The current host remains primary. Collaboration skills call another runtime
 only when explicitly requested, use it as a read-only advisor, and return the
 evidence to the primary host for final verification.
 
-## 5. Hook boundary
+## 6. Hook boundary
 
-The canonical Python hook allowlist contains seven workflow-only adapters:
+The canonical Python hook bundle contains seven executable workflow hooks plus
+the shared read-only `context_spine.py` breadcrumb helper:
 
 - `health_check.py` and `workflow_context.py` on session start;
 - `active_task_context.py` before an edit;
@@ -86,7 +106,9 @@ The canonical Python hook allowlist contains seven workflow-only adapters:
 - `pre_stop_check.py` at stop;
 - `subagent_tracker.py` for bounded worker lifecycle evidence.
 
-`health_check.py` and `workflow_context.py` may inspect any initialized project;
+`workflow_context.py`, `active_task_context.py`, and `workflow_resume.py` read the
+same DB-derived breadcrumb through `context_spine.py`. `health_check.py` and
+`workflow_context.py` may inspect any initialized project;
 `active_task_context.py` always protects the task projection but limits ordinary
 edit guidance to an active workflow. Compact/stop/subagent hooks remain
 active-workflow scoped. OpenCode natively injects baseline/change context and
@@ -95,7 +117,7 @@ protects the projection; full health inspection is available through
 Generic command blocking, post-edit governance, and unrelated user hooks are not
 copied into Ultra Builder Pro.
 
-## 6. Memory boundary
+## 7. Memory boundary
 
 Ultra Builder Pro has no memory MCP family, recall skill, prompt capture,
 transcript capture, observation journal, or session-summary hook. Persistent
@@ -113,14 +135,14 @@ ultra-tools legacy-memory prune --confirm DELETE_ULTRA_LEGACY_MEMORY
 
 Archive before prune; the confirmation token is intentionally required.
 
-## 7. Project state layout
+## 8. Project state layout
 
 ```text
 .ultra/
 ├── state.db                 # authoritative SQLite store
 ├── workflow-state.json      # active workflow/recovery checkpoint
 ├── changes/
-│   ├── active/<id>/         # intent, delta, plan, compiled context, verification
+│   ├── active/<id>/         # intent, delta, plan, context v2, learning, verification
 │   └── archive/             # converged packets after baseline reconciliation
 ├── tasks/                   # projections and task contexts
 ├── specs/                   # research/product/architecture artifacts
@@ -130,7 +152,7 @@ Archive before prune; the confirmation token is intentionally required.
 └── delivery-report.json
 ```
 
-## 8. User handbook integration
+## 9. User handbook integration
 
 General engineering doctrine remains user-owned in `CLAUDE.md` or `AGENTS.md`.
 Ultra Builder Pro contributes one managed section only. Preview or apply it with:
@@ -140,12 +162,12 @@ ubp-handbook preview --runtime codex
 ubp-handbook apply --runtime codex
 ```
 
-Supported runtime names are `claude`, `codex`, and `opencode`. Apply creates a
+Supported runtime names are `claude`, `codex`, `opencode`, and `kimi`. Apply creates a
 timestamped backup, replaces only the marked block, and can migrate the old
 Codex `## Ultra Builder Pro Runtime Contract` section without touching the next
 user section. Plugin adapters themselves do not silently overwrite handbooks.
 
-## 9. Verification
+## 10. Verification
 
 Run `npm run test:all`, `python3 -m pytest hooks/tests -q`, and `npm audit`.
 Adapter tests assert the allowlisted assets, native manifests, hook boundary,

package/docs/ARCHITECTURE.md

@@ -53,7 +53,7 @@ the supported hosts share.
 | Layer        | Role                                         | Form                                                  |
 |--------------|----------------------------------------------|-------------------------------------------------------|
 | **skill**    | knowledge carrier; tells the runtime *what to do* | `skills/<name>/SKILL.md` discovered natively by all supported runtimes |
-| **MCP**      | authoritative workflow-state API             | stdio MCP server exposing 29 live tools across task/session/change/system/plan families in [`spec/mcp-tools.yaml`](../spec/mcp-tools.yaml) |
+| **MCP**      | authoritative workflow-state and Context Spine API | stdio MCP server exposing 32 live tools across task/session/change/system/plan families in [`spec/mcp-tools.yaml`](../spec/mcp-tools.yaml) |
 | **CLI**      | explicit initialization, recovery, diagnostics, and orchestration | `ultra-tools` / `ubp-orchestrator`; only commands listed by `--help` are executable (see [`spec/cli-protocol.md`](../spec/cli-protocol.md)) |
 
 Why three: skills give us behavior portability across runtimes; MCP gives
@@ -70,7 +70,7 @@ RPC, and host-native loaders own resolution and invocation.
 
 All durable Ultra workflow state lives in one SQLite file with WAL enabled. Schema is
 fixed in [`spec/schemas/state-db.sql`](../spec/schemas/state-db.sql) and
-covers fifteen tables:
+covers sixteen tables:
 
 | Table              | Holds                                             | Phase |
 |--------------------|---------------------------------------------------|-------|
@@ -84,7 +84,8 @@ covers fifteen tables:
 | `circuit_breaker`  | bounded retry and halt state for failed tasks       | 5     |
 | `changes`          | continuous feature/fix/incident lifecycle           | 8C    |
 | `artifacts`        | intent/context/verification artifact registry       | 8C    |
-| `context_snapshots`| compiled context hashes, git head, provider refs    | 8C    |
+| `context_snapshots`| role/gate context, readiness, budget, execution seam, hashes, git head, provider refs | 10 |
+| `spec_learning_candidates` | approval-gated implementation discoveries for baseline convergence | 10 |
 | `trace_links`      | task/spec/change traceability                        | 8C    |
 | `incidents`        | structured runtime failures and resolutions         | 8C    |
 | `projection_jobs` | durable projection outbox/retry state                | 8C    |
@@ -101,7 +102,8 @@ Two rules make this work:
 2. **Single writer for mutable tables, multi-writer for `events`.**
    `.ultra/state.db` opens in WAL with `busy_timeout=5000`. The MCP
    server holds the single writer connection for `tasks`, `sessions`,
-   `telemetry`, `specs_refs`, and `migration_history`; the CLI calls
+   `changes`, `context_snapshots`, `spec_learning_candidates`, `telemetry`,
+   `specs_refs`, and `migration_history`; the CLI calls
    those tools over stdio rather than opening its own writer. The
    `events` table is append-only and explicitly multi-writer — CLI and
    orchestrator processes append directly to it under the same WAL +
@@ -133,7 +135,8 @@ active -> blocked -> active -> ready -> archived
    |                              |
    ├─ intent + delta + plan       └─ verification + baseline reconciliation
    ├─ linked tasks
-   └─ context-manifest (current HEAD + provider metadata references)
+   ├─ context-manifest v2 (role + gate + readiness + execution seam)
+   └─ spec-learning candidates (proposed -> approved/rejected -> applied)
 ```
 
 `quick`, `standard`, `major`, and `incident` kinds require different evidence,
@@ -141,6 +144,29 @@ but all require completed linked tasks, current context, declared documentation
 impact, and no open incident. Memory and graph payloads never enter Ultra;
 `context_snapshots.provider_refs_json` stores metadata references only.
 
+### Context Spine
+
+Context Manifest v2 is the handoff contract between planning, implementation,
+checking, review, convergence, and recovery. Each snapshot records:
+
+- one role (`plan`, `implement`, `check`, or `review`) and lifecycle gate;
+- required context references with local digests and reasons;
+- readiness blockers for missing/stale references or budget overflow;
+- a fresh-context budget (12 files / about 12k tokens / 40% by default);
+- an execution contract (`slice_kind`, public seam, exact verification command);
+- one deterministic next action.
+
+`change.breadcrumb` derives the compact current position from state.db. Session,
+edit, and resume hooks inject only this breadcrumb, never the intent body,
+provider content, or a conversation summary. A changed git HEAD marks the
+snapshot stale and routes back to `change.context`.
+
+`change.learning_propose` records a durable implementation discovery without
+silently rewriting the baseline. `change.learning_resolve` enforces approval,
+rejection, and applied transitions. Proposed or merely approved candidates block
+convergence, so daily work cannot leave accepted behavior stranded in chat or a
+delta packet.
+
 `incident` is the canonical debug lane. Creating one also registers a durable
 `diagnosis.md` artifact with five mandatory sections: reproduction, hypotheses,
 root cause, regression test, and recovery. Convergence validates the artifact

package/docs/PLAN.zh-CN.md

@@ -10,8 +10,9 @@
 > Kimi Code 采用各自 native plugin 呈现，其他旧 runtime adapter 已退役。下文所有与此冲突的
 > memory/hindsight 章节仅作为历史实施记录，不再是当前需求或运行时契约。
 
-**当前状态**：v0.9.0；四宿主 native plugin、29 个 live MCP tool、
-schema 9.1（15 表）、持续 change/context/convergence/doctor、incident debug lane、
+**当前状态**：v0.10.0；四宿主 native plugin、32 个 live MCP tool、
+schema 10.0（16 表）、Context Spine v2 / breadcrumb / spec-learning、持续
+change/context/convergence/doctor、incident debug lane、
 checkpoint 恢复消费与跨宿主安装 provenance/doctor 已落地；npm 发布由
 `v*.*.*` tag 触发。以下 Phase 0-9 正文保留为 2026-04 的实施历史，不再作为
 当前 runtime 或发布状态的事实来源。