ultra-builder-pro-cli 0.13.0 → 0.14.0

package/hooks/workflow_checkpoint.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Write a minimal, mechanical compaction checkpoint for an active workflow."""
+"""Write a recovery projection of the canonical DB breadcrumb before compaction."""
 
 import json
 import os
@@ -8,18 +8,12 @@ import tempfile
 from datetime import datetime, timezone
 from pathlib import Path
 
-TERMINAL = {"committed", "completed", "done", "cancelled"}
-
-
-def valid_workflow(state: object) -> bool:
-    return (
-        isinstance(state, dict)
-        and isinstance(state.get("command"), str)
-        and bool(state["command"].strip())
-        and state.get("step") is not None
-        and isinstance(state.get("status"), str)
-        and bool(state["status"].strip())
-    )
+from context_spine import (
+    ContextSpineError,
+    find_root,
+    read_breadcrumb,
+    render_breadcrumb,
+)
 
 
 def main() -> None:
@@ -29,41 +23,39 @@ def main() -> None:
     except json.JSONDecodeError as exc:
         print(f"[workflow_checkpoint] invalid hook input: {exc}", file=sys.stderr)
         data = {}
-    start = Path(data.get("cwd") or Path.cwd()).resolve()
-    for root in (start, *start.parents):
-        state_file = root / ".ultra" / "workflow-state.json"
-        if not state_file.is_file():
-            continue
-        try:
-            state = json.loads(state_file.read_text(encoding="utf-8"))
-        except (OSError, json.JSONDecodeError) as exc:
-            print(f"[workflow_checkpoint] cannot read {state_file}: {exc}", file=sys.stderr)
-            break
-        if not valid_workflow(state):
-            print(f"[workflow_checkpoint] invalid workflow state in {state_file}", file=sys.stderr)
-            break
-        if state.get("status") in TERMINAL:
-            break
-        runtime_dir = root / ".ultra" / "runtime"
-        runtime_dir.mkdir(parents=True, exist_ok=True)
-        checkpoint = {
-            "schema": 1,
-            "captured_at": datetime.now(timezone.utc).isoformat(),
-            "session_id": data.get("session_id", ""),
-            "workflow": state,
-        }
-        fd, temp_name = tempfile.mkstemp(prefix="checkpoint.", suffix=".json", dir=runtime_dir)
-        try:
-            with os.fdopen(fd, "w", encoding="utf-8") as handle:
-                json.dump(checkpoint, handle, ensure_ascii=False, indent=2)
-                handle.write("\n")
-            os.replace(temp_name, runtime_dir / "checkpoint.json")
-        finally:
-            if os.path.exists(temp_name):
-                os.unlink(temp_name)
-        print(json.dumps({"systemMessage": "Ultra workflow checkpoint saved."}))
+    root = find_root(Path(data.get("cwd") or Path.cwd()).resolve())
+    if root is None:
+        print(json.dumps({}))
+        return
+    try:
+        breadcrumb = read_breadcrumb(root)
+    except ContextSpineError as exc:
+        print(f"[workflow_checkpoint] cannot inspect Context Spine: {exc}", file=sys.stderr)
+        print(json.dumps({}))
         return
-    print(json.dumps({}))
+    if not breadcrumb or not breadcrumb.get("change_id"):
+        print(json.dumps({}))
+        return
+
+    runtime_dir = root / ".ultra" / "runtime"
+    runtime_dir.mkdir(parents=True, exist_ok=True)
+    checkpoint = {
+        "schema": 2,
+        "captured_at": datetime.now(timezone.utc).isoformat(),
+        "session_id": data.get("session_id", ""),
+        "breadcrumb": dict(breadcrumb),
+        "rendered": render_breadcrumb(root, breadcrumb),
+    }
+    fd, temp_name = tempfile.mkstemp(prefix="checkpoint.", suffix=".json", dir=runtime_dir)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(checkpoint, handle, ensure_ascii=False, indent=2)
+            handle.write("\n")
+        os.replace(temp_name, runtime_dir / "checkpoint.json")
+    finally:
+        if os.path.exists(temp_name):
+            os.unlink(temp_name)
+    print(json.dumps({"systemMessage": "Ultra workflow checkpoint saved."}))
 
 
 if __name__ == "__main__":

package/hooks/workflow_context.py

@@ -2,11 +2,10 @@
 """Inject one compact Ultra state position without persistent memory."""
 
 import json
-import sqlite3
 import sys
 from pathlib import Path
 
-from context_spine import find_root, read_breadcrumb, render_breadcrumb
+from context_spine import ContextSpineError, find_root, read_breadcrumb, render_breadcrumb
 
 
 def payload() -> dict:
@@ -26,18 +25,14 @@ def main() -> None:
         return
     try:
         breadcrumb = read_breadcrumb(root)
-    except (sqlite3.Error, OSError) as exc:
+    except ContextSpineError 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({}))
+        return
     print(json.dumps({"hookSpecificOutput": {
         "hookEventName": "SessionStart",
         "additionalContext": context,

package/hooks/workflow_resume.py

@@ -1,84 +1,53 @@
 #!/usr/bin/env python3
-"""Restore only the current Ultra workflow boundary after compaction."""
+"""Re-inject live DB authority after compaction; checkpoints are advisory only."""
 
 import json
-import os
-import sqlite3
 import sys
-import tempfile
-from datetime import datetime, timezone
+from datetime import datetime
 from pathlib import Path
 
-from context_spine import find_root, read_breadcrumb, render_breadcrumb
+from context_spine import (
+    ContextSpineError,
+    find_root,
+    read_breadcrumb,
+    render_breadcrumb,
+)
 
-TERMINAL = {"committed", "completed", "done", "cancelled"}
 
+def _hook_output(event: str, text: str) -> dict:
+    if event == "SessionStart":
+        return {"hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": text,
+        }}
+    return {"additionalContext": text}
 
-def valid_workflow(state: object) -> bool:
-    return (
-        isinstance(state, dict)
-        and isinstance(state.get("command"), str)
-        and bool(state["command"].strip())
-        and state.get("step") is not None
-        and isinstance(state.get("status"), str)
-        and bool(state["status"].strip())
-    )
 
-
-def read_json(file: Path, label: str):
+def _checkpoint_advisory(root: Path):
+    file = root / ".ultra" / "runtime" / "checkpoint.json"
     if not file.is_file():
         return None
     try:
-        return json.loads(file.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
-        print(f"[workflow_resume] cannot read {label} {file}: {exc}", file=sys.stderr)
-        return None
-
-
-def parse_time(value: object):
-    if not isinstance(value, str) or not value.strip():
-        return None
-    try:
-        return datetime.fromisoformat(value.replace("Z", "+00:00")).astimezone(timezone.utc)
-    except ValueError:
-        return None
-
-
-def newest_time(file: Path, *values: object) -> datetime:
-    candidates = [parsed for value in values if (parsed := parse_time(value)) is not None]
-    try:
-        candidates.append(datetime.fromtimestamp(file.stat().st_mtime, tz=timezone.utc))
-    except OSError:
-        pass
-    return max(candidates, default=datetime.min.replace(tzinfo=timezone.utc))
-
-
-def load_checkpoint(file: Path):
-    checkpoint = read_json(file, "checkpoint")
-    if checkpoint is None:
+        value = json.loads(file.read_text(encoding="utf-8"))
+        datetime.fromisoformat(str(value.get("captured_at", "")).replace("Z", "+00:00"))
+    except (OSError, json.JSONDecodeError, ValueError, AttributeError) as exc:
+        print(f"[workflow_resume] cannot read checkpoint {file}: {exc}", file=sys.stderr)
         return None
-    if not isinstance(checkpoint, dict):
+    if (
+        not isinstance(value, dict)
+        or value.get("schema") != 2
+        or not isinstance(value.get("breadcrumb"), dict)
+        or not isinstance(value.get("rendered"), str)
+        or not value["rendered"].strip()
+    ):
         print(f"[workflow_resume] invalid checkpoint schema in {file}", file=sys.stderr)
         return None
-    captured_at = checkpoint.get("captured_at")
-    workflow = checkpoint.get("workflow")
-    if checkpoint.get("schema") != 1 or parse_time(captured_at) is None or not valid_workflow(workflow):
-        print(f"[workflow_resume] invalid checkpoint schema in {file}", file=sys.stderr)
-        return None
-    return checkpoint
-
-
-def restore_state(file: Path, state: dict) -> None:
-    file.parent.mkdir(parents=True, exist_ok=True)
-    fd, temp_name = tempfile.mkstemp(prefix="workflow-state.", suffix=".json", dir=file.parent)
-    try:
-        with os.fdopen(fd, "w", encoding="utf-8") as handle:
-            json.dump(state, handle, ensure_ascii=False, indent=2)
-            handle.write("\n")
-        os.replace(temp_name, file)
-    finally:
-        if os.path.exists(temp_name):
-            os.unlink(temp_name)
+    return "\n".join([
+        "[Ultra checkpoint advisory]",
+        "Live .ultra/state.db could not be read; this checkpoint is not authority.",
+        value["rendered"],
+        "Run ultra-doctor before mutation.",
+    ])
 
 
 def main() -> None:
@@ -88,72 +57,23 @@ def main() -> None:
     except json.JSONDecodeError as exc:
         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
+    root = find_root(Path(data.get("cwd") or Path.cwd()).resolve())
+    if root is None:
+        print(json.dumps({}))
+        return
+    text = None
+    try:
+        breadcrumb = read_breadcrumb(root)
         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"
-        if not state_file.is_file() and not checkpoint_file.is_file():
-            continue
-        live = read_json(state_file, "workflow state")
-        if live is not None and not valid_workflow(live):
-            print(f"[workflow_resume] invalid workflow state in {state_file}", file=sys.stderr)
-            live = None
-        if live is not None and live.get("status") in TERMINAL:
-            break
-        checkpoint = load_checkpoint(checkpoint_file)
-        checkpoint_state = checkpoint["workflow"] if checkpoint is not None else None
-        if checkpoint_state is not None and checkpoint_state.get("status") in TERMINAL:
-            checkpoint_state = None
-
-        source = ".ultra/workflow-state.json"
-        state = live
-        if checkpoint_state is not None:
-            checkpoint_time = newest_time(
-                checkpoint_file, checkpoint_state.get("ts"), checkpoint.get("captured_at")
-            )
-            live_time = newest_time(state_file, live.get("ts")) if live is not None else None
-            if live_time is None or checkpoint_time >= live_time:
-                state = checkpoint_state
-                source = ".ultra/runtime/checkpoint.json"
-                restore_state(state_file, state)
-        if state is None:
-            break
-        text = (
-            "[Ultra workflow resumed] "
-            f"command={state.get('command', 'unknown')}; "
-            f"task={state.get('task_id', state.get('task', 'unknown'))}; "
-            f"step={state.get('step', 'unknown')}; status={state.get('status', 'active')}. "
-            f"source={source}. Continue from the recovered workflow boundary and verify "
-            "task/session/change state through .ultra/state.db."
-        )
-        event = data.get("hook_event_name", "SessionStart")
-        if event == "SessionStart":
-            print(json.dumps({"hookSpecificOutput": {
-                "hookEventName": "SessionStart",
-                "additionalContext": text,
-            }}))
-        else:
-            print(json.dumps({"additionalContext": text}))
+    except ContextSpineError as exc:
+        print(f"[workflow_resume] cannot inspect Context Spine: {exc}", file=sys.stderr)
+        text = _checkpoint_advisory(root)
+    if not text:
+        print(json.dumps({}))
         return
-    print(json.dumps({}))
+    event = data.get("hook_event_name", "SessionStart")
+    print(json.dumps(_hook_output(event, text)))
 
 
 if __name__ == "__main__":

package/mcp-server/breadcrumb.cjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const runtime = fs.existsSync(path.join(__dirname, 'index.cjs'))
+  ? require('./index.cjs')
+  : require('./server.cjs');
+
+function main() {
+  const rootDir = path.resolve(process.argv[2] || process.cwd());
+  const breadcrumb = runtime.readProjectBreadcrumb(rootDir);
+  process.stdout.write(`${JSON.stringify({
+    breadcrumb,
+    text: breadcrumb ? runtime.renderProjectBreadcrumb(rootDir, breadcrumb) : null,
+  })}\n`);
+}
+
+if (require.main === module) main();
+
+module.exports = { main };

package/mcp-server/lib/prd-parser.cjs

@@ -1,17 +1,11 @@
 'use strict';
 
-// Phase 8A.1 — PRD → task[] parser. Delegates LLM call to an injected
-// llmClient (see lib/llm-client.cjs). The parser itself is pure logic:
-// prompt assembly → schema validation → id normalization. Keeping the
-// llmClient as a parameter makes unit tests a Test Double exercise without
-// mocking network I/O.
+// Validate and normalize a task graph derived from a PRD by the current host.
+// The MCP runtime is deliberately deterministic: model judgment stays with
+// the host that already owns the user interaction, while this module owns the
+// machine contract before state.db is mutated.
 
 const Ajv = require('ajv/dist/2020');
-const {
-  buildSystemPrompt,
-  buildUserPrompt,
-} = require('../../orchestrator/planner/prd-prompt.cjs');
-
 const TASK_LIST_SCHEMA = Object.freeze({
   type: 'object',
   required: ['tasks'],
@@ -48,39 +42,22 @@ class PrdParseError extends Error {
   }
 }
 
-async function parsePrd(prdText, { llmClient, tag } = {}) {
-  if (!prdText || typeof prdText !== 'string' || !prdText.trim()) {
-    throw new PrdParseError('NO_INPUT', 'prd text is empty');
-  }
-  if (!llmClient || typeof llmClient.completeJson !== 'function') {
-    throw new PrdParseError('NO_LLM_CLIENT', 'llmClient.completeJson is required');
+function parsePrd(tasks, { tag, changeId } = {}) {
+  if (!Array.isArray(tasks) || tasks.length === 0) {
+    throw new PrdParseError('NO_INPUT', 'at least one host-derived task is required');
   }
-
-  const system = buildSystemPrompt();
-  const user = buildUserPrompt(prdText);
-
-  let reply;
-  try {
-    reply = await llmClient.completeJson({ system, user });
-  } catch (err) {
-    throw new PrdParseError(
-      'PARSE_FAILED',
-      `LLM call failed: ${err.message}`,
-      err,
-    );
-  }
-
-  if (!validateTaskList(reply.json)) {
+  const input = { tasks };
+  if (!validateTaskList(input)) {
     throw new PrdParseError(
       'PARSE_FAILED',
-      `LLM output failed schema: ${ajv.errorsText(validateTaskList.errors)}`,
+      `task graph failed schema: ${ajv.errorsText(validateTaskList.errors)}`,
     );
   }
 
   const ids = new Set();
-  const tasks = reply.json.tasks.map((t) => {
+  const normalized = tasks.map((t) => {
     if (ids.has(t.id)) {
-      throw new PrdParseError('PARSE_FAILED', `duplicate task id "${t.id}" in LLM output`);
+      throw new PrdParseError('PARSE_FAILED', `duplicate task id "${t.id}" in task graph`);
     }
     ids.add(t.id);
     return {
@@ -92,15 +69,11 @@ async function parsePrd(prdText, { llmClient, tag } = {}) {
       deps: Array.isArray(t.deps) ? t.deps : [],
       files_modified: Array.isArray(t.files_modified) ? t.files_modified : [],
       tag: tag || null,
+      change_id: changeId || null,
     };
   });
 
-  return {
-    tasks,
-    usage: reply.usage || {},
-    model: reply.model,
-    provider: reply.provider,
-  };
+  return { tasks: normalized };
 }
 
 module.exports = {