ultra-builder-pro-cli 0.12.1 → 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/archive-journal.cjs

@@ -0,0 +1,192 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const INTENT_FILE = '.archive-intent.json';
+const INTENT_VERSION = '1.0';
+
+class ArchiveJournalError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'ArchiveJournalError';
+    this.code = code;
+  }
+}
+
+function resolveInside(rootDir, relative, field) {
+  if (typeof relative !== 'string' || !relative.trim() || path.isAbsolute(relative)) {
+    throw new ArchiveJournalError('ARCHIVE_INTENT_INVALID', `${field} must be project-relative`);
+  }
+  const root = path.resolve(rootDir);
+  const resolved = path.resolve(root, relative);
+  if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) {
+    throw new ArchiveJournalError('ARCHIVE_INTENT_INVALID', `${field} escapes project root`);
+  }
+  return resolved;
+}
+
+function assertIntent(intent, rootDir) {
+  if (!intent || typeof intent !== 'object' || Array.isArray(intent)
+    || intent.schema_version !== INTENT_VERSION
+    || typeof intent.change_id !== 'string' || !intent.change_id
+    || !Array.isArray(intent.baseline_updates)
+    || typeof intent.summary !== 'string' || intent.summary.trim().length < 3) {
+    throw new ArchiveJournalError('ARCHIVE_INTENT_INVALID', 'archive intent shape is invalid');
+  }
+  const source = resolveInside(rootDir, intent.source, 'source');
+  const destination = resolveInside(rootDir, intent.destination, 'destination');
+  const activeRoot = path.resolve(rootDir, '.ultra', 'changes', 'active');
+  const archiveRoot = path.resolve(rootDir, '.ultra', 'changes', 'archive');
+  if (path.dirname(source) !== activeRoot || path.basename(source) !== intent.change_id) {
+    throw new ArchiveJournalError('ARCHIVE_INTENT_INVALID', 'archive intent source is not the active change root');
+  }
+  if (path.dirname(destination) !== archiveRoot
+    || !path.basename(destination).endsWith(`-${intent.change_id}`)) {
+    throw new ArchiveJournalError('ARCHIVE_INTENT_INVALID', 'archive intent destination is not the change archive root');
+  }
+  for (const update of intent.baseline_updates) resolveInside(rootDir, update, 'baseline update');
+  if (intent.previous_summary !== null && typeof intent.previous_summary !== 'string') {
+    throw new ArchiveJournalError('ARCHIVE_INTENT_INVALID', 'previous_summary must be string or null');
+  }
+  return { intent, source, destination };
+}
+
+function readIntentFile(file, rootDir) {
+  let intent;
+  try { intent = JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (error) {
+    throw new ArchiveJournalError('ARCHIVE_INTENT_CORRUPT', `cannot read ${file}: ${error.message}`);
+  }
+  return assertIntent(intent, rootDir);
+}
+
+function writeJsonAtomic(file, value) {
+  const temp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx' });
+  fs.renameSync(temp, file);
+}
+
+function renderSummary(change, summary, baselineUpdates, noBaselineChangeReason) {
+  return [
+    `# Archived change: ${change.title}`, '', summary.trim(), '',
+    '## Baseline reconciliation', '',
+    ...(baselineUpdates.length > 0
+      ? baselineUpdates.map((file) => `- ${file}`)
+      : [noBaselineChangeReason]), '',
+  ].join('\n');
+}
+
+function sameOperation(intent, { change, summary, baselineUpdates, noBaselineChangeReason }) {
+  return intent.change_id === change.id
+    && intent.source === change.artifact_root
+    && intent.summary === summary.trim()
+    && JSON.stringify(intent.baseline_updates) === JSON.stringify(baselineUpdates)
+    && (intent.no_baseline_change_reason || null) === (noBaselineChangeReason || null);
+}
+
+function prepareArchiveMove({
+  rootDir, change, summary, baselineUpdates, noBaselineChangeReason, now = new Date(),
+}) {
+  const date = now.toISOString().slice(0, 10);
+  const source = resolveInside(rootDir, change.artifact_root, 'source');
+  const destinationRelative = path.join('.ultra', 'changes', 'archive', `${date}-${change.id}`);
+  const destination = resolveInside(rootDir, destinationRelative, 'destination');
+  const sourceIntentFile = path.join(source, INTENT_FILE);
+  const destinationIntentFile = path.join(destination, INTENT_FILE);
+
+  if (!fs.existsSync(source) && fs.existsSync(destinationIntentFile)) {
+    const resumed = readIntentFile(destinationIntentFile, rootDir);
+    if (!sameOperation(resumed.intent, {
+      change, summary, baselineUpdates, noBaselineChangeReason,
+    })) {
+      throw new ArchiveJournalError('ARCHIVE_INTENT_CONFLICT', 'existing archive intent differs from retry input');
+    }
+    return { ...resumed, resumed: true };
+  }
+  if (!fs.existsSync(source)) {
+    throw new ArchiveJournalError('ARCHIVE_SOURCE_MISSING', `active change root missing: ${change.artifact_root}`);
+  }
+  if (fs.existsSync(destination)) {
+    throw new ArchiveJournalError('ARCHIVE_EXISTS', `archive already exists: ${destination}`);
+  }
+
+  let prepared;
+  if (fs.existsSync(sourceIntentFile)) {
+    prepared = readIntentFile(sourceIntentFile, rootDir);
+    if (!sameOperation(prepared.intent, {
+      change, summary, baselineUpdates, noBaselineChangeReason,
+    })) {
+      throw new ArchiveJournalError('ARCHIVE_INTENT_CONFLICT', 'prepared archive intent differs from retry input');
+    }
+  } else {
+    const summaryPath = path.join(source, 'archive-summary.md');
+    const previousSummary = fs.existsSync(summaryPath) ? fs.readFileSync(summaryPath, 'utf8') : null;
+    const intent = {
+      schema_version: INTENT_VERSION,
+      change_id: change.id,
+      source: change.artifact_root,
+      destination: destinationRelative,
+      summary: summary.trim(),
+      baseline_updates: baselineUpdates,
+      no_baseline_change_reason: noBaselineChangeReason || null,
+      previous_summary: previousSummary,
+      created_at: now.toISOString(),
+    };
+    writeJsonAtomic(sourceIntentFile, intent);
+    prepared = assertIntent(intent, rootDir);
+  }
+
+  fs.writeFileSync(
+    path.join(source, 'archive-summary.md'),
+    renderSummary(change, summary, baselineUpdates, noBaselineChangeReason),
+  );
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.renameSync(source, destination);
+  return { ...prepared, source, destination, resumed: false };
+}
+
+function listArchiveIntents(rootDir) {
+  const roots = [
+    path.join(rootDir, '.ultra', 'changes', 'active'),
+    path.join(rootDir, '.ultra', 'changes', 'archive'),
+  ];
+  const found = [];
+  for (const parent of roots) {
+    if (!fs.existsSync(parent)) continue;
+    for (const entry of fs.readdirSync(parent, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const file = path.join(parent, entry.name, INTENT_FILE);
+      if (!fs.existsSync(file)) continue;
+      try { found.push({ ...readIntentFile(file, rootDir), file, error: null }); }
+      catch (error) { found.push({ file, error }); }
+    }
+  }
+  return found;
+}
+
+function completeArchiveIntent(rootDir, intent) {
+  const { destination } = assertIntent(intent, rootDir);
+  fs.rmSync(path.join(destination, INTENT_FILE), { force: true });
+}
+
+function rollbackArchiveIntent(rootDir, intent) {
+  const { source, destination } = assertIntent(intent, rootDir);
+  if (fs.existsSync(destination) && !fs.existsSync(source)) fs.renameSync(destination, source);
+  if (!fs.existsSync(source) || fs.existsSync(destination)) {
+    throw new ArchiveJournalError('ARCHIVE_ROLLBACK_FAILED', 'archive roots are not in a recoverable state');
+  }
+  const summaryPath = path.join(source, 'archive-summary.md');
+  if (intent.previous_summary === null) fs.rmSync(summaryPath, { force: true });
+  else fs.writeFileSync(summaryPath, intent.previous_summary);
+  fs.rmSync(path.join(source, INTENT_FILE), { force: true });
+}
+
+module.exports = {
+  ArchiveJournalError,
+  INTENT_FILE,
+  prepareArchiveMove,
+  listArchiveIntents,
+  completeArchiveIntent,
+  rollbackArchiveIntent,
+};

package/mcp-server/lib/archive-journal.test.cjs

@@ -0,0 +1,35 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const journal = require('./archive-journal.cjs');
+
+test('archive journal restores the exact active directory when finalization cannot run', () => {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-archive-journal-'));
+  const source = path.join(rootDir, '.ultra', 'changes', 'active', 'change-a');
+  fs.mkdirSync(source, { recursive: true });
+  fs.writeFileSync(path.join(source, 'intent.md'), '# Change A\n');
+  try {
+    const prepared = journal.prepareArchiveMove({
+      rootDir,
+      change: { id: 'change-a', title: 'Change A', artifact_root: '.ultra/changes/active/change-a' },
+      summary: 'Archive Change A.', baselineUpdates: [],
+      noBaselineChangeReason: 'No baseline content changed.',
+      now: new Date('2026-07-18T00:00:00.000Z'),
+    });
+    assert.equal(fs.existsSync(prepared.source), false);
+    assert.equal(journal.listArchiveIntents(rootDir).length, 1);
+
+    journal.rollbackArchiveIntent(rootDir, prepared.intent);
+    assert.equal(fs.existsSync(source), true);
+    assert.equal(fs.existsSync(path.join(source, 'intent.md')), true);
+    assert.equal(fs.existsSync(path.join(source, 'archive-summary.md')), false);
+    assert.equal(journal.listArchiveIntents(rootDir).length, 0);
+  } finally {
+    fs.rmSync(rootDir, { recursive: true, force: true });
+  }
+});