ultra-builder-pro-cli 0.8.1 → 0.10.0

package/docs/USER-HANDBOOK-CONTRACT.md

@@ -7,18 +7,26 @@ only one small managed section describing its runtime boundary.
 ## Source and render targets
 
 `adapters/_shared/handbook.cjs` is the canonical source. It renders the common
-authority, memory, hook, agent, and package boundaries with host-native command
-syntax:
+authority, Context Spine, specification-learning, memory, hook, agent, and
+package boundaries with host-native command syntax:
 
 | Runtime | Default target | Main invocation form |
 |---|---|---|
 | Claude Code | `~/.claude/CLAUDE.md` | `/ultra-plan` |
 | Codex | `~/.codex/AGENTS.md` | `$ultra-builder-pro:ultra-plan` |
 | OpenCode | `~/.config/opencode/AGENTS.md` | `/ultra-plan` |
+| Kimi Code | `~/.kimi-code/AGENTS.md` | `/ultra-builder-pro:ultra-plan` |
 
-The renderer never copies Claude Code-only APIs into Codex or OpenCode. Each
+The renderer never copies Claude Code-only APIs into Codex, OpenCode, or Kimi. Each
 host receives only its native invocation and collaboration names.
 
+The managed block deliberately stays short. It says that `.ultra/state.db` is
+authoritative; `change.context` compiles role/gate readiness, bounded references,
+fresh-context budget, public seam, and exact verification; hooks inject only the
+DB-derived `change.breadcrumb`; and unresolved specification learning or either
+failed review axis blocks convergence. Detailed procedures remain in the plugin
+skills so user handbooks do not accumulate duplicated prompt sediment.
+
 ## Managed-block contract
 
 The owned content is bounded by:
@@ -42,6 +50,7 @@ Preview the full merged result before applying:
 ubp-handbook preview --runtime claude
 ubp-handbook preview --runtime codex
 ubp-handbook preview --runtime opencode
+ubp-handbook preview --runtime kimi
 ```
 
 Apply when the preview is correct:
@@ -50,6 +59,7 @@ Apply when the preview is correct:
 ubp-handbook apply --runtime claude
 ubp-handbook apply --runtime codex
 ubp-handbook apply --runtime opencode
+ubp-handbook apply --runtime kimi
 ```
 
 An existing target is copied to

package/hooks/README.md

@@ -7,10 +7,11 @@ bounded to the relevant Ultra projection or a non-terminal workflow.
 | Lifecycle | Hook | Purpose |
 |---|---|---|
 | Session start | `health_check.py` | Read-only integrity, incident, projection, session, and change-artifact checks |
-| Session start | `workflow_context.py` | Inject baseline/active workflow/change context and filtered provider metadata references |
-| Before edit | `active_task_context.py` | Protect `tasks.json` projection and restate an active task boundary |
+| Shared helper | `context_spine.py` | Read the latest role/gate/readiness snapshot from state.db and derive one compact breadcrumb |
+| Session start | `workflow_context.py` | Inject the DB-derived breadcrumb without intent or provider payloads |
+| Before edit | `active_task_context.py` | Protect `tasks.json` and restate the same DB-derived task breadcrumb |
 | Before compact | `workflow_checkpoint.py` | Validate and atomically save a minimal workflow checkpoint |
-| After compact/resume | `workflow_resume.py` | Select the newest valid live/checkpoint state, restore it atomically when needed, and re-inject the boundary |
+| After compact/resume | `workflow_resume.py` | Prefer the DB breadcrumb; restore the minimal file checkpoint only when no active change owns recovery |
 | Stop | `pre_stop_check.py` | Block once when the Ultra workflow is incomplete |
 | Subagent lifecycle | `subagent_tracker.py` | Append lifecycle evidence under `.ultra/runtime/` |
 
@@ -18,7 +19,8 @@ The plugin deliberately does not capture prompts, tool observations, transcripts
 cross-session memory or code-graph content. Generic command blocking and post-edit policy are
 user/repository governance. Persistent Memory/graph content belongs to separately installed providers.
 
-The checkpoint is a recovery artifact, not a second authority. A valid newer
+`context_spine.py` is an imported library, not an eighth lifecycle registration.
+Registering it separately would duplicate hook execution. The checkpoint is a recovery artifact, not a second authority. A valid newer
 live workflow wins; a newer valid checkpoint may restore a missing or older
 live file; corrupt, non-object, or terminal checkpoints are ignored.
 

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/adapters/kimi.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""Kimi Code wire adapter for Ultra Builder Pro lifecycle hooks.
+
+Kimi 0.26 uses snake_case JSON input compatible with the workflow hooks, but
+its output contract accepts only ``message`` plus an optional structured deny.
+This adapter preserves real projection/stop blocks, converts foreign context
+fields into Kimi messages, and fails open with diagnostic evidence.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+
+HOOK_ROOT = Path(__file__).resolve().parent.parent
+ALLOWED_FEATURES = {
+    "active_task_context.py",
+    "health_check.py",
+    "pre_stop_check.py",
+    "subagent_tracker.py",
+    "workflow_checkpoint.py",
+    "workflow_context.py",
+    "workflow_resume.py",
+}
+
+
+def normalize_input(payload: dict[str, Any]) -> dict[str, Any]:
+    """Add only the legacy aliases required by the shared workflow hooks."""
+    normalized = copy.deepcopy(payload)
+    agent_name = normalized.get("agent_name")
+    if isinstance(agent_name, str) and agent_name:
+        normalized.setdefault("agent_id", agent_name)
+        normalized.setdefault("agent_type", agent_name)
+    if normalized.get("tool_response") is not None and normalized.get("tool_output") is None:
+        normalized["tool_output"] = normalized["tool_response"]
+    return normalized
+
+
+def _text(value: Any) -> str:
+    return str(value).strip() if value is not None else ""
+
+
+def adapt_output(output: dict[str, Any], event: str) -> dict[str, Any]:
+    """Convert one legacy hook result to Kimi's exact structured schema."""
+    if not isinstance(output, dict):
+        return {}
+    specific = output.get("hookSpecificOutput")
+    specific = specific if isinstance(specific, dict) else {}
+
+    decision = specific.get("permissionDecision")
+    blocked = output.get("decision") == "block" or decision == "deny"
+    reason = (
+        _text(specific.get("permissionDecisionReason"))
+        or _text(output.get("reason"))
+        or f"Ultra {event} gate blocked continuation"
+    )
+    if blocked:
+        return {
+            "hookSpecificOutput": {
+                "message": reason,
+                "permissionDecision": "deny",
+                "permissionDecisionReason": reason,
+            }
+        }
+
+    context = (
+        _text(specific.get("additionalContext"))
+        or _text(output.get("additionalContext"))
+        or _text(output.get("systemMessage"))
+        or _text(specific.get("message"))
+        or _text(output.get("message"))
+    )
+    advisory = _text(specific.get("permissionDecisionReason")) if decision == "ask" else ""
+    message = "\n\n".join(part for part in [advisory, context] if part)
+    return {"message": message} if message else {}
+
+
+def _parse_output(stdout: str) -> dict[str, Any]:
+    text = stdout.strip()
+    if not text:
+        return {}
+    try:
+        value = json.loads(text)
+    except json.JSONDecodeError:
+        return {"message": f"Ultra hook returned non-JSON output: {text[:500]}"}
+    return value if isinstance(value, dict) else {}
+
+
+def run_feature(feature: str, payload: dict[str, Any], feature_args: list[str]) -> dict[str, Any]:
+    if feature not in ALLOWED_FEATURES or Path(feature).name != feature:
+        return {"message": f"Ultra hook adapter refused unknown feature: {feature}"}
+    script = HOOK_ROOT / feature
+    if not script.is_file():
+        return {"message": f"Ultra hook feature is missing: {feature}"}
+
+    event = str(payload.get("hook_event_name") or "")
+    normalized = normalize_input(payload)
+    if feature == "workflow_resume.py" and event == "PostCompact":
+        normalized["hook_event_name"] = "SessionStart"
+        normalized["source"] = "compact"
+
+    env = os.environ.copy()
+    env["UBP_HOOK_RUNTIME"] = "kimi"
+    plugin_data = env.get("PLUGIN_DATA") or env.get("KIMI_PLUGIN_ROOT")
+    if plugin_data:
+        env["UBP_HOOK_DATA"] = plugin_data
+
+    cwd = normalized.get("cwd")
+    run_cwd = str(cwd) if isinstance(cwd, str) and Path(cwd).is_dir() else os.getcwd()
+    proc = subprocess.run(
+        [sys.executable, str(script), *feature_args],
+        input=json.dumps(normalized),
+        text=True,
+        capture_output=True,
+        cwd=run_cwd,
+        env=env,
+        timeout=30,
+        check=False,
+    )
+    if proc.stderr:
+        print(proc.stderr.rstrip(), file=sys.stderr)
+    if proc.returncode != 0:
+        return {
+            "message": (
+                f"Ultra hook {feature} failed with exit {proc.returncode}: "
+                f"{proc.stderr.strip()[:500]}"
+            )
+        }
+    return adapt_output(_parse_output(proc.stdout), event)
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print(json.dumps({"message": "Ultra Kimi hook adapter requires a feature name"}))
+        return 0
+    feature = sys.argv[1]
+    feature_args = sys.argv[2:]
+    try:
+        payload = json.loads(sys.stdin.read() or "{}")
+        if not isinstance(payload, dict):
+            payload = {}
+    except json.JSONDecodeError as exc:
+        print(json.dumps({"message": f"Ultra hook input parse error: {exc}"}))
+        return 0
+    try:
+        output = run_feature(feature, payload, feature_args)
+    except subprocess.TimeoutExpired:
+        output = {"message": f"Ultra hook {feature} timed out"}
+    except Exception as exc:  # Kimi hooks are fail-open at this adapter boundary.
+        output = {"message": f"Ultra hook adapter error in {feature}: {exc}"}
+    print(json.dumps(output, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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()