ultra-builder-pro-cli 0.9.0 → 0.11.0

package/hooks/active_task_context.py

@@ -2,9 +2,12 @@
 """Protect Ultra projections and restate an active task boundary before edits."""
 
 import json
+import sqlite3
 import sys
 from pathlib import Path
 
+from context_spine import read_breadcrumb, render_breadcrumb
+
 TERMINAL = {"committed", "completed", "done", "cancelled"}
 TASKS_PROJECTION = Path(".ultra/tasks/tasks.json")
 
@@ -53,6 +56,17 @@ def main() -> None:
                 ),
             }}))
             return
+        try:
+            breadcrumb = read_breadcrumb(root)
+        except (sqlite3.Error, OSError) as exc:
+            print(f"[active_task_context] cannot inspect Context Spine: {exc}", file=sys.stderr)
+            breadcrumb = None
+        if breadcrumb and breadcrumb.get("task_id"):
+            print(json.dumps({"hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "additionalContext": render_breadcrumb(root, breadcrumb),
+            }}))
+            return
         if not state_file.is_file():
             break
         try:

package/hooks/context_spine.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+"""Read and render the compact DB-derived Ultra Context Spine breadcrumb."""
+
+import json
+import sqlite3
+import subprocess
+from pathlib import Path
+
+
+ACTIVE_CHANGE_STATUSES = ("active", "blocked", "ready")
+TERMINAL_TASK_STATUSES = ("completed", "expanded")
+CONTEXT_COLUMNS = {
+    "role", "gate", "next_action", "readiness", "blockers_json",
+    "context_json", "manifest_path", "manifest_hash", "git_head", "task_id",
+}
+
+
+def find_root(start: Path):
+    for root in (start, *start.parents):
+        ultra = root / ".ultra"
+        if (
+            (ultra / "state.db").is_file()
+            or (ultra / "workflow-state.json").is_file()
+            or (ultra / "changes" / "active").is_dir()
+        ):
+            return root
+    return None
+
+
+def safe_json(raw, fallback):
+    if not isinstance(raw, str) or not raw.strip():
+        return fallback
+    try:
+        value = json.loads(raw)
+        return value
+    except json.JSONDecodeError:
+        return fallback
+
+
+def git_head(root: Path):
+    result = subprocess.run(
+        ["git", "rev-parse", "HEAD"],
+        cwd=root,
+        text=True,
+        capture_output=True,
+        check=False,
+        timeout=2,
+    )
+    return result.stdout.strip() if result.returncode == 0 else None
+
+
+def _next_action(change, task, tasks, role, readiness, stored, state_changed):
+    if readiness != "ready":
+        return "Resolve the context readiness blockers, then recompile change.context."
+    if not state_changed and isinstance(stored, str) and stored.strip():
+        return stored.strip()
+    if change["status"] == "ready":
+        return f"Run ultra-deliver for change {change['id']}."
+    if change["status"] == "blocked":
+        return f"Resolve the blockers for change {change['id']}, then recompile context."
+    if task and task["status"] == "pending":
+        return f"Start task {task['id']} through ultra-dev."
+    if task and task["status"] == "in_progress":
+        if role == "check":
+            return f"Run the exact verification command for task {task['id']}."
+        if role == "review":
+            return (
+                "Complete independent spec-fidelity and engineering-standards "
+                f"review for task {task['id']}."
+            )
+        return f"Continue the approved vertical slice for task {task['id']}."
+    if tasks and all(row["status"] in TERMINAL_TASK_STATUSES for row in tasks):
+        return f"Run ultra-test for change {change['id']}."
+    pending = next((row for row in tasks if row["status"] == "pending"), None)
+    if pending:
+        return f"Compile implement context for task {pending['id']}."
+    return f"Create the first fresh-context tracer-bullet task for change {change['id']}."
+
+
+def _route(change, task, tasks, readiness):
+    if readiness != "ready" or change["status"] == "blocked":
+        return "ultra-change"
+    if change["status"] == "ready":
+        return "ultra-deliver"
+    if task and task["status"] in ("pending", "in_progress"):
+        return "ultra-dev"
+    if tasks and all(row["status"] in TERMINAL_TASK_STATUSES for row in tasks):
+        return "ultra-test"
+    return "ultra-change"
+
+
+def read_breadcrumb(root: Path):
+    db_path = root / ".ultra" / "state.db"
+    if not db_path.is_file():
+        return None
+    with sqlite3.connect(f"file:{db_path}?mode=ro", uri=True, timeout=1) as conn:
+        conn.row_factory = sqlite3.Row
+        tables = {
+            row[0]
+            for row in conn.execute("SELECT name FROM sqlite_master WHERE type='table'")
+        }
+        if not {"changes", "tasks", "context_snapshots"}.issubset(tables):
+            return None
+        change = conn.execute(
+            """SELECT id, status FROM changes
+               WHERE status IN ('active', 'blocked', 'ready')
+               ORDER BY updated_at DESC LIMIT 1"""
+        ).fetchone()
+        if change is None:
+            return None
+        tasks = list(conn.execute(
+            "SELECT id, status, session_id FROM tasks WHERE change_id = ? ORDER BY created_at ASC",
+            (change["id"],),
+        ))
+        columns = {
+            row[1] for row in conn.execute("PRAGMA table_info(context_snapshots)")
+        }
+        snapshot = None
+        if CONTEXT_COLUMNS.issubset(columns):
+            snapshot = conn.execute(
+                """SELECT task_id, git_head, manifest_path, manifest_hash, role, gate,
+                          next_action, readiness, blockers_json, context_json
+                   FROM context_snapshots WHERE change_id = ?
+                   ORDER BY created_at DESC, rowid DESC LIMIT 1""",
+                (change["id"],),
+            ).fetchone()
+
+    task_id = snapshot["task_id"] if snapshot else None
+    if not task_id:
+        active = next((row for row in tasks if row["status"] == "in_progress"), None)
+        pending = next((row for row in tasks if row["status"] == "pending"), None)
+        task_id = (active or pending)["id"] if (active or pending) else None
+    task = next((row for row in tasks if row["id"] == task_id), None)
+    context = safe_json(snapshot["context_json"], {}) if snapshot else {}
+    role = snapshot["role"] if snapshot else "plan"
+    gate = snapshot["gate"] if snapshot else "alignment"
+    current_head = git_head(root)
+    head_stale = bool(
+        snapshot and snapshot["git_head"] and current_head
+        and snapshot["git_head"] != current_head
+    )
+    snapshot_missing = snapshot is None
+    legacy_context = bool(
+        snapshot and (
+            not isinstance(context.get("resume"), dict)
+            or not isinstance(context.get("context"), dict)
+            or not isinstance(context.get("readiness"), dict)
+        )
+    )
+    stored_status = context.get("resume", {}).get("task_status")
+    current_status = task["status"] if task else None
+    state_changed = stored_status is not None and stored_status != current_status
+    stored_action = snapshot["next_action"] if snapshot else None
+    blockers = []
+    if snapshot_missing:
+        blockers.append("CONTEXT_NOT_COMPILED")
+    else:
+        if legacy_context:
+            blockers.append("CONTEXT_SNAPSHOT_UPGRADE_REQUIRED")
+        if head_stale:
+            blockers.append("CONTEXT_HEAD_STALE")
+        if state_changed:
+            blockers.append("CONTEXT_TASK_STATE_STALE")
+        for blocker in safe_json(snapshot["blockers_json"], []):
+            if blocker not in blockers:
+                blockers.append(blocker)
+    readiness = "blocked" if blockers else snapshot["readiness"]
+    if snapshot_missing:
+        next_action = f"Compile change.context for change {change['id']} before continuing."
+    elif legacy_context:
+        next_action = "Recompile change.context to upgrade this legacy context snapshot."
+    elif head_stale:
+        next_action = "Git HEAD changed after context compilation; recompile change.context."
+    elif state_changed:
+        next_action = "Task state changed after context compilation; recompile change.context."
+    else:
+        next_action = _next_action(change, task, tasks, role, readiness, stored_action, False)
+    return {
+        "change_id": change["id"],
+        "change_status": change["status"],
+        "task_id": task["id"] if task else None,
+        "task_status": task["status"] if task else None,
+        "session_id": task["session_id"] if task else None,
+        "role": role,
+        "gate": gate,
+        "readiness": readiness,
+        "blockers": blockers,
+        "next_action": next_action,
+        "recommended_workflow": _route(change, task, tasks, readiness),
+        "context_manifest_path": snapshot["manifest_path"] if snapshot else None,
+        "context_manifest_hash": snapshot["manifest_hash"] if snapshot else None,
+        "git_head": current_head,
+    }
+
+
+def render_breadcrumb(root: Path, breadcrumb: dict) -> str:
+    task = breadcrumb.get("task_id") or "none"
+    task_status = breadcrumb.get("task_status") or "none"
+    lines = [
+        "[Ultra context spine]",
+        f"Project: {root}",
+        f"Change: {breadcrumb['change_id']} ({breadcrumb.get('change_status', 'active')})",
+        f"Task: {task} ({task_status})",
+        f"Role: {breadcrumb.get('role', 'plan')}",
+        f"Gate: {breadcrumb.get('gate', 'alignment')}",
+        f"Readiness: {breadcrumb.get('readiness', 'ready')}",
+    ]
+    if breadcrumb.get("blockers"):
+        lines.append("Blockers: " + ", ".join(breadcrumb["blockers"]))
+    lines.extend([
+        f"Next: {breadcrumb.get('next_action', 'Inspect Ultra status.')}",
+        f"Route: {breadcrumb.get('recommended_workflow', 'ultra-change')}",
+    ])
+    if breadcrumb.get("context_manifest_path"):
+        digest = breadcrumb.get("context_manifest_hash") or "unknown"
+        lines.append(f"Context: {breadcrumb['context_manifest_path']} sha256={digest}")
+    lines.append("Authority: .ultra/state.db; JSON/Markdown remain projections or evidence artifacts.")
+    return "\n".join(lines)

package/hooks/health_check.py

@@ -10,7 +10,7 @@ from pathlib import Path
 REQUIRED_TABLES = {
     "tasks", "events", "sessions", "schema_version", "migration_history",
     "telemetry", "specs_refs", "circuit_breaker", "changes", "artifacts",
-    "context_snapshots", "trace_links", "incidents", "projection_jobs",
+    "context_snapshots", "spec_learning_candidates", "trace_links", "incidents", "projection_jobs",
     "event_consumers",
 }
 

package/hooks/workflow_context.py

@@ -1,16 +1,12 @@
 #!/usr/bin/env python3
-"""Inject current Ultra workflow/change context without persistent memory."""
+"""Inject one compact Ultra state position without persistent memory."""
 
 import json
 import sqlite3
 import sys
 from pathlib import Path
 
-
-TERMINAL_WORKFLOW = {"committed", "completed", "done", "cancelled"}
-PROVIDER_FIELDS = {
-    "provider", "project", "reference", "revision", "indexed_head", "status",
-}
+from context_spine import find_root, read_breadcrumb, render_breadcrumb
 
 
 def payload() -> dict:
@@ -22,132 +18,29 @@ def payload() -> dict:
         return {}
 
 
-def find_root(start: Path):
-    for root in (start, *start.parents):
-        ultra = root / ".ultra"
-        if (
-            (ultra / "state.db").is_file()
-            or (ultra / "workflow-state.json").is_file()
-            or (ultra / "changes" / "active").is_dir()
-        ):
-            return root
-    return None
-
-
-def read_workflow(root: Path):
-    state_file = root / ".ultra" / "workflow-state.json"
-    if not state_file.is_file():
-        return None
-    try:
-        state = json.loads(state_file.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
-        print(f"[workflow_context] cannot read {state_file}: {exc}", file=sys.stderr)
-        return None
-    if isinstance(state, dict) and state.get("status") not in TERMINAL_WORKFLOW:
-        return state
-    return None
-
-
-def safe_json(raw, fallback):
-    try:
-        value = json.loads(raw)
-        return value
-    except (TypeError, json.JSONDecodeError):
-        return fallback
-
-
-def provider_metadata(raw) -> dict:
-    refs = safe_json(raw, {})
-    if not isinstance(refs, dict):
-        return {}
-    clean = {}
-    for kind, ref in refs.items():
-        if kind not in {"memory", "code_graph"} or not isinstance(ref, dict):
-            continue
-        clean[kind] = {key: ref[key] for key in PROVIDER_FIELDS if key in ref}
-    return clean
-
-
-def read_changes(root: Path):
-    db_path = root / ".ultra" / "state.db"
-    if not db_path.is_file():
-        return []
-    try:
-        with sqlite3.connect(f"file:{db_path}?mode=ro", uri=True, timeout=1) as conn:
-            exists = conn.execute(
-                "SELECT 1 FROM sqlite_master WHERE type='table' AND name='changes'"
-            ).fetchone()
-            if not exists:
-                return []
-            rows = conn.execute(
-                """SELECT id, title, kind, status, intent, docs_impact_json,
-                          provider_refs_json, artifact_root
-                   FROM changes WHERE status IN ('active', 'blocked', 'ready')
-                   ORDER BY updated_at DESC"""
-            ).fetchall()
-    except sqlite3.Error as exc:
-        print(f"[workflow_context] cannot inspect {db_path}: {exc}", file=sys.stderr)
-        return []
-    return [
-        {
-            "id": row[0], "title": row[1], "kind": row[2], "status": row[3],
-            "intent": row[4], "docs_impact": safe_json(row[5], {}),
-            "providers": provider_metadata(row[6]), "artifact_root": row[7],
-        }
-        for row in rows
-    ]
-
-
-def context_text(root: Path, workflow, changes) -> str:
-    lines = []
-    if workflow:
-        lines.extend([
-            "[Ultra active workflow]",
-            f"Project: {root}",
-            f"Command: {workflow.get('command', 'unknown')}",
-            f"Task: {workflow.get('task_id', workflow.get('task', 'unknown'))}",
-            f"Step: {workflow.get('step', 'unknown')}",
-            f"Status: {workflow.get('status', 'active')}",
-        ])
-    if changes:
-        change = changes[0]
-        lines.extend([
-            "[Ultra continuous change]",
-            f"Project: {root}",
-            f"Change: {change['id']} ({change['kind']}, {change['status']})",
-            f"Title: {change['title']}",
-            f"Intent: {change['intent']}",
-            "Docs impact: " + json.dumps(change["docs_impact"], ensure_ascii=False, sort_keys=True),
-            f"Context manifest: {change['artifact_root']}/context-manifest.json",
-            "External providers (metadata references only): "
-            + json.dumps(change["providers"], ensure_ascii=False, sort_keys=True),
-        ])
-        if len(changes) > 1:
-            lines.append(f"Active change count: {len(changes)}; resolve scope with change.list before mutation.")
-    if not workflow and not changes:
-        lines.extend([
-            "[Ultra baseline]",
-            f"Project: {root}",
-            "No active continuous change. Start daily work with the ultra-change workflow.",
-        ])
-    lines.append("Authority: .ultra/state.db; generated JSON/Markdown are projections or artifacts.")
-    return "\n".join(lines)
-
-
 def main() -> None:
     data = payload()
     root = find_root(Path(data.get("cwd") or Path.cwd()).resolve())
     if root is None:
         print(json.dumps({}))
         return
-    workflow = read_workflow(root)
-    changes = read_changes(root)
-    context = context_text(root, workflow, changes)
+    try:
+        breadcrumb = read_breadcrumb(root)
+    except (sqlite3.Error, OSError) as exc:
+        print(f"[workflow_context] cannot inspect Context Spine: {exc}", file=sys.stderr)
+        breadcrumb = None
+    if breadcrumb:
+        context = render_breadcrumb(root, breadcrumb)
+    else:
+        context = "\n".join([
+            "[Ultra baseline]",
+            f"Project: {root}",
+            "No active continuous change. Start daily work with the ultra-change workflow.",
+            "Authority: .ultra/state.db; JSON/Markdown remain projections or evidence artifacts.",
+        ])
     print(json.dumps({"hookSpecificOutput": {
         "hookEventName": "SessionStart",
         "additionalContext": context,
     }}))
-
-
 if __name__ == "__main__":
     main()

package/hooks/workflow_resume.py

@@ -3,11 +3,14 @@
 
 import json
 import os
+import sqlite3
 import sys
 import tempfile
 from datetime import datetime, timezone
 from pathlib import Path
 
+from context_spine import find_root, read_breadcrumb, render_breadcrumb
+
 TERMINAL = {"committed", "completed", "done", "cancelled"}
 
 
@@ -86,6 +89,24 @@ def main() -> None:
         print(f"[workflow_resume] invalid hook input: {exc}", file=sys.stderr)
         data = {}
     start = Path(data.get("cwd") or Path.cwd()).resolve()
+    root = find_root(start)
+    if root is not None:
+        try:
+            breadcrumb = read_breadcrumb(root)
+        except (sqlite3.Error, OSError) as exc:
+            print(f"[workflow_resume] cannot inspect Context Spine: {exc}", file=sys.stderr)
+            breadcrumb = None
+        if breadcrumb:
+            text = render_breadcrumb(root, breadcrumb)
+            event = data.get("hook_event_name", "SessionStart")
+            if event == "SessionStart":
+                print(json.dumps({"hookSpecificOutput": {
+                    "hookEventName": "SessionStart",
+                    "additionalContext": text,
+                }}))
+            else:
+                print(json.dumps({"additionalContext": text}))
+            return
     for root in (start, *start.parents):
         state_file = root / ".ultra" / "workflow-state.json"
         checkpoint_file = root / ".ultra" / "runtime" / "checkpoint.json"

package/mcp-server/lib/change-workflow.cjs

@@ -6,6 +6,8 @@ const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 
 const ops = require('./state-ops.cjs');
+const contextSpine = require('./context-spine.cjs');
+const specLearning = require('./spec-learning.cjs');
 
 const CHANGE_ID = /^[a-zA-Z0-9_-]+$/;
 const PROVIDER_KINDS = new Set(['memory', 'code_graph']);
@@ -227,13 +229,16 @@ function compileContext(db, input, { rootDir = process.cwd() } = {}) {
     ? change.provider_refs
     : normalizeProviderRefs(input.provider_refs);
   const tasks = db.prepare(
-    'SELECT id, title, status, priority, stale, trace_to, context_file FROM tasks WHERE change_id = ? ORDER BY created_at ASC',
+    `SELECT id, title, type, status, priority, complexity, stale, trace_to,
+            context_file, files_modified, session_id, created_at, updated_at
+     FROM tasks WHERE change_id = ? ORDER BY created_at ASC`,
   ).all(change.id).map((task) => ({ ...task, stale: Boolean(task.stale) }));
   const specs = Array.isArray(input.spec_refs) ? input.spec_refs : [];
   const allowedPaths = Array.isArray(input.allowed_paths) ? input.allowed_paths : [];
   const head = gitHead(rootDir);
+  const spine = contextSpine.compileRoleContext(db, { input, change, tasks, rootDir });
   const manifest = {
-    schema_version: '1.0',
+    schema_version: '2.0',
     generated_at: nowIso(),
     change: {
       id: change.id, title: change.title, kind: change.kind, status: change.status,
@@ -241,7 +246,15 @@ function compileContext(db, input, { rootDir = process.cwd() } = {}) {
     },
     git: { head },
     tasks,
+    selected_task: spine.selected_task,
     specs,
+    role: spine.role,
+    gate: spine.gate,
+    next_action: spine.next_action,
+    readiness: spine.readiness,
+    context: spine.context,
+    execution_contract: spine.execution_contract,
+    resume: spine.resume,
     providers,
     provider_boundary: 'metadata references only; memory and code graph content remain external',
     tool_policy: { allowed_paths: allowedPaths },
@@ -257,15 +270,24 @@ function compileContext(db, input, { rootDir = process.cwd() } = {}) {
   ops.tx(db, () => {
     db.prepare(
       `INSERT INTO context_snapshots
-       (id, change_id, task_id, git_head, provider_refs_json, manifest_path, manifest_hash)
-       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+       (id, change_id, task_id, git_head, provider_refs_json, manifest_path, manifest_hash,
+        role, gate, next_action, readiness, blockers_json, context_json,
+        token_estimate, token_budget)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
     ).run(
       `ctx-${crypto.randomUUID().slice(0, 12)}`, change.id, input.task_id || null,
       head, JSON.stringify(providers), relative, hash,
+      spine.role, spine.gate, spine.next_action, spine.readiness.status,
+      JSON.stringify(spine.readiness.blockers), JSON.stringify(spine),
+      spine.context.token_estimate, spine.context.budget.max_tokens,
     );
     upsertArtifact(db, {
       change_id: change.id, task_id: input.task_id || null, kind: 'context_manifest',
-      artifactPath: relative, contentHash: hash, metadata: { git_head: head },
+      artifactPath: relative, contentHash: hash,
+      metadata: {
+        git_head: head, role: spine.role, gate: spine.gate,
+        readiness: spine.readiness.status, token_estimate: spine.context.token_estimate,
+      },
     });
     for (const task of tasks) {
       if (!task.trace_to) continue;
@@ -278,7 +300,11 @@ function compileContext(db, input, { rootDir = process.cwd() } = {}) {
       .run(JSON.stringify(providers), nowIso(), change.id);
     ops.appendEventInTx(db, {
       type: 'context_updated', change_id: change.id, task_id: input.task_id || null,
-      payload: { manifest_path: relative, manifest_hash: hash, git_head: head },
+      payload: {
+        manifest_path: relative, manifest_hash: hash, git_head: head,
+        role: spine.role, gate: spine.gate, readiness: spine.readiness.status,
+        next_action: spine.next_action,
+      },
     });
   });
   return { manifest, context_manifest_path: manifestPath, manifest_hash: hash };
@@ -438,16 +464,43 @@ function filesUnder(dir) {
   return out;
 }
 
-function evidenceBlockers(change, evidence) {
+function evidenceBlockers(change, evidence, tasks) {
   const blockers = [];
   const rows = Array.isArray(evidence) ? evidence : [];
   const byCategory = new Map(rows.map((row) => [row.category, row]));
-  for (const category of REQUIRED_EVIDENCE[change.kind]) {
+  for (const category of REQUIRED_EVIDENCE[change.kind].filter((value) => value !== 'review')) {
     const row = byCategory.get(category);
     if (!row) blockers.push(`EVIDENCE_MISSING:${category}`);
     else if (!['pass', 'not_applicable'].includes(row.status)) blockers.push(`EVIDENCE_FAILED:${category}`);
     else if (!row.evidence || String(row.evidence).trim().length < 3) blockers.push(`EVIDENCE_EMPTY:${category}`);
   }
+  if (['standard', 'major'].includes(change.kind)) {
+    const reviews = rows.filter((row) => row.category === 'review');
+    for (const axis of ['spec_fidelity', 'engineering_standards']) {
+      const row = reviews.find((candidate) => candidate.axis === axis);
+      if (!row) blockers.push(`REVIEW_AXIS_MISSING:${axis}`);
+      else if (row.status !== 'pass') blockers.push(`REVIEW_AXIS_FAILED:${axis}`);
+      else if (!row.evidence || String(row.evidence).trim().length < 3) {
+        blockers.push(`REVIEW_AXIS_EMPTY:${axis}`);
+      }
+    }
+  }
+  const tests = byCategory.get('tests');
+  if (tests && ['standard', 'major', 'incident'].includes(change.kind)
+    && (!tests.seam || String(tests.seam).trim().length < 3)) {
+    blockers.push('TEST_SEAM_MISSING');
+  }
+  if (tests && (change.kind === 'incident' || tasks.some((task) => task.type === 'bugfix'))) {
+    const signal = tests.signal;
+    if (!signal) blockers.push('TEST_RED_SIGNAL_MISSING');
+    else {
+      if (!signal.command || String(signal.command).trim().length < 3) blockers.push('TEST_SIGNAL_COMMAND_MISSING');
+      if (!signal.expected_red || String(signal.expected_red).trim().length < 3) blockers.push('TEST_EXPECTED_RED_MISSING');
+      if (signal.observed_red !== true) blockers.push('TEST_RED_NOT_OBSERVED');
+      if (signal.observed_green !== true) blockers.push('TEST_GREEN_NOT_OBSERVED');
+      if (signal.deterministic !== true) blockers.push('TEST_SIGNAL_NOT_DETERMINISTIC');
+    }
+  }
   return blockers;
 }
 
@@ -457,11 +510,31 @@ function convergeChange(db, input, { rootDir = process.cwd() } = {}) {
   if (!['active', 'blocked'].includes(change.status)) {
     throw new ChangeWorkflowError('CHANGE_NOT_CONVERGEABLE', `change ${input.id} is ${change.status}`);
   }
-  const blockers = new Set(evidenceBlockers(change, input.evidence));
-  const tasks = db.prepare('SELECT id, status, stale FROM tasks WHERE change_id = ? ORDER BY id').all(change.id);
+  const tasks = db.prepare('SELECT id, type, status, stale FROM tasks WHERE change_id = ? ORDER BY id').all(change.id);
+  const blockers = new Set(evidenceBlockers(change, input.evidence, tasks));
   if (tasks.length === 0) blockers.add('NO_TASKS');
   if (tasks.some((task) => !['completed', 'expanded'].includes(task.status))) blockers.add('TASKS_INCOMPLETE');
   if (tasks.some((task) => Boolean(task.stale))) blockers.add('TASK_CONTEXT_STALE');
+  for (const task of tasks) {
+    const snapshot = db.prepare(
+      `SELECT readiness, context_json FROM context_snapshots
+       WHERE change_id = ? AND task_id = ?
+       ORDER BY created_at DESC, rowid DESC LIMIT 1`,
+    ).get(change.id, task.id);
+    if (!snapshot) {
+      blockers.add(`TASK_CONTEXT_MISSING:${task.id}`);
+      continue;
+    }
+    const context = parseJson(snapshot.context_json, 'context_snapshots.context_json');
+    if (snapshot.readiness !== 'ready') blockers.add(`TASK_CONTEXT_NOT_READY:${task.id}`);
+    if (!context.execution_contract?.public_seam) blockers.add(`TASK_SEAM_MISSING:${task.id}`);
+    if (!context.execution_contract?.verification_command) blockers.add(`TASK_VERIFICATION_MISSING:${task.id}`);
+  }
+
+  for (const candidate of specLearning.listSpecLearning(db, change.id)) {
+    if (candidate.status === 'proposed') blockers.add(`SPEC_LEARNING_UNRESOLVED:${candidate.id}`);
+    if (candidate.status === 'approved') blockers.add(`SPEC_LEARNING_NOT_APPLIED:${candidate.id}`);
+  }
 
   if (change.docs_impact.status === 'unknown') blockers.add('DOCS_IMPACT_UNKNOWN');
   if (change.docs_impact.status === 'none' && (!change.docs_impact.rationale || change.docs_impact.rationale.length < 3)) {
@@ -513,7 +586,8 @@ function convergeChange(db, input, { rootDir = process.cwd() } = {}) {
   const lines = [
     `# Verification: ${change.title}`, '',
     ...input.evidence.flatMap((row) => [
-      `## ${row.category}`, '', `Status: **${row.status}**`, '', String(row.evidence).trim(), '',
+      `## ${row.category}${row.axis ? `:${row.axis}` : ''}`, '',
+      `Status: **${row.status}**`, '', String(row.evidence).trim(), '',
     ]),
   ];
   fs.writeFileSync(verificationPath, `${lines.join('\n')}\n`);
@@ -618,6 +692,10 @@ module.exports = {
   listChanges,
   updateChange,
   compileContext,
+  readBreadcrumb: contextSpine.readBreadcrumb,
+  proposeSpecLearning: specLearning.proposeSpecLearning,
+  resolveSpecLearning: specLearning.resolveSpecLearning,
+  listSpecLearning: specLearning.listSpecLearning,
   convergeChange,
   archiveChange,
   normalizeDocsImpact,