feat: add the Ultra Context Spine

Daily maintenance could drift away from the original specification because role context, task freshness, verification seams, and implementation discoveries were not one durable contract. Hooks also injected broad workflow prose while projection-only hosts could accept stale manifests.

This release adds Context Manifest v2, schema 10.0, deterministic breadcrumbs, approval-gated specification learning, and 32 live MCP contracts. It gives every linked task a bounded role/gate packet, required references and digests, a public seam, an exact verification command, and fail-closed readiness. Convergence now requires current task contexts, documentation/spec evidence, exact test seams, and independent spec-fidelity and engineering-standards review.

The seven daily execution workflows are compressed from 1,922 to 758 lines and all twelve public workflows are host-invocable. Claude Code, Codex, OpenCode, and Kimi Code receive native Context Spine rendering; OpenCode rejects legacy or HEAD-stale projections. A shared read-only hook helper replaces duplicated broad context injection.

Compatibility remains additive: the 9.1 to 10.0 migration preserves durable rows and foreign keys; external providers continue to own memory and code graphs; Gemini and RTK remain absent from active runtime, prompt, installer, and documentation surfaces. Rollback is package reinstall to 0.9.0; databases retain additive columns/table and should be backed up before any manual downgrade.

Verification: npm run verify:release (144 Node tests, 21 hook tests, npm audit with 0 vulnerabilities); npm pack --dry-run --json (222 files, all new runtime assets present); git diff --cached --check; MCP system.doctor reports healthy with SQLite integrity ok, zero projection lag, zero open incidents, and external provider ownership.

Author: rocky2431

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

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.
 

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');

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.',

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',

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, '\\$&')));

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',

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');

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");
 }
 

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 {