ultra-builder-pro-cli 0.11.0 → 0.13.0

package/hooks/context_spine.py

@@ -2,6 +2,7 @@
 """Read and render the compact DB-derived Ultra Context Spine breadcrumb."""
 
 import json
+import hashlib
 import sqlite3
 import subprocess
 from pathlib import Path
@@ -13,6 +14,12 @@ CONTEXT_COLUMNS = {
     "role", "gate", "next_action", "readiness", "blockers_json",
     "context_json", "manifest_path", "manifest_hash", "git_head", "task_id",
 }
+ADVISORY_CONTEXT_CODES = {
+    "CONTEXT_FILE_BUDGET_EXCEEDED",
+    "CONTEXT_TOKEN_BUDGET_EXCEEDED",
+    "EXECUTION_CONTEXT_BUDGET_EXCEEDED",
+    "EXECUTION_CONTEXT_BUDGET_ADVISORY",
+}
 
 
 def find_root(start: Path):
@@ -49,8 +56,90 @@ def git_head(root: Path):
     return result.stdout.strip() if result.returncode == 0 else None
 
 
-def _next_action(change, task, tasks, role, readiness, stored, state_changed):
+def git_branch(root: Path):
+    result = subprocess.run(
+        ["git", "branch", "--show-current"],
+        cwd=root,
+        text=True,
+        capture_output=True,
+        check=False,
+        timeout=2,
+    )
+    return (result.stdout.strip() or None) if result.returncode == 0 else None
+
+
+def baseline_health(conn, root: Path):
+    columns = {row[1] for row in conn.execute("PRAGMA table_info(baselines)")}
+    optional = [
+        name for name in (
+            "repository_branch", "worktree_state", "worktree_accepted", "gaps_json"
+        ) if name in columns
+    ]
+    row = conn.execute(
+        f"""SELECT id, mode, status, repository_revision, spec_refs_json{''.join(f', {name}' for name in optional)}
+            FROM baselines WHERE status != 'superseded'
+            ORDER BY updated_at DESC, rowid DESC LIMIT 1"""
+    ).fetchone()
+    if row is None:
+        return {"status": "fail", "blockers": ["BASELINE_MISSING"], "warnings": [], "baseline": None}
+    baseline = dict(row)
+    blockers = []
+    warnings = []
+    if baseline["status"] != "ready":
+        blockers.append(f"BASELINE_NOT_READY:{baseline['status']}")
+    elif baseline["mode"] == "migrated":
+        blockers.append("BASELINE_MIGRATION_REVIEW_REQUIRED")
+    else:
+        if "gaps_json" not in columns:
+            blockers.append("BASELINE_SCHEMA_MIGRATION_REQUIRED")
+        for gap in safe_json(baseline.get("gaps_json"), []):
+            if (
+                isinstance(gap, dict)
+                and gap.get("status") == "open"
+                and gap.get("blocking") is True
+            ):
+                blockers.append(f"BASELINE_GAP_BLOCKING:{gap.get('id', 'unknown')}")
+        if baseline.get("worktree_state") == "dirty" and not baseline.get("worktree_accepted"):
+            blockers.append("BASELINE_DIRTY_WORKTREE_NOT_ACCEPTED")
+        branch = git_branch(root)
+        if baseline.get("repository_branch") and branch and baseline["repository_branch"] != branch:
+            blockers.append("BASELINE_BRANCH_STALE")
+        for spec in safe_json(baseline.get("spec_refs_json"), []):
+            ref = spec.get("path") if isinstance(spec, dict) else None
+            expected = spec.get("digest") if isinstance(spec, dict) else None
+            if not isinstance(ref, str) or not ref or Path(ref).is_absolute():
+                blockers.append(f"BASELINE_SPEC_INVALID:{ref}")
+                continue
+            candidate = (root / ref).resolve()
+            try:
+                candidate.relative_to(root.resolve())
+            except ValueError:
+                blockers.append(f"BASELINE_SPEC_INVALID:{ref}")
+                continue
+            if not candidate.is_file():
+                blockers.append(f"BASELINE_SPEC_MISSING:{ref}")
+                continue
+            digest = hashlib.sha256(candidate.read_bytes()).hexdigest()
+            if not expected or digest != expected:
+                blockers.append(f"BASELINE_SPEC_STALE:{ref}")
+        head = git_head(root)
+        revision = baseline.get("repository_revision")
+        if head and revision and not str(revision).startswith("workspace:") and head != revision:
+            blockers.append("BASELINE_HEAD_STALE")
+    baseline.pop("spec_refs_json", None)
+    baseline.pop("gaps_json", None)
+    return {
+        "status": "fail" if blockers else "pass",
+        "blockers": blockers,
+        "warnings": warnings,
+        "baseline": baseline,
+    }
+
+
+def _next_action(change, task, tasks, role, readiness, stored, state_changed, blockers=None):
     if readiness != "ready":
+        if any(str(item).startswith("BASELINE_") for item in (blockers or [])):
+            return "Complete or refresh the Ultra project baseline through ultra-init."
         return "Resolve the context readiness blockers, then recompile change.context."
     if not state_changed and isinstance(stored, str) and stored.strip():
         return stored.strip()
@@ -77,7 +166,7 @@ def _next_action(change, task, tasks, role, readiness, stored, state_changed):
     return f"Create the first fresh-context tracer-bullet task for change {change['id']}."
 
 
-def _route(change, task, tasks, readiness):
+def _route(change, task, tasks, readiness, blockers=None):
     if readiness != "ready" or change["status"] == "blocked":
         return "ultra-change"
     if change["status"] == "ready":
@@ -99,15 +188,39 @@ def read_breadcrumb(root: Path):
             row[0]
             for row in conn.execute("SELECT name FROM sqlite_master WHERE type='table'")
         }
-        if not {"changes", "tasks", "context_snapshots"}.issubset(tables):
+        if not {"baselines", "changes", "tasks", "context_snapshots"}.issubset(tables):
             return None
+        baseline = baseline_health(conn, root)
         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
+            current = baseline["baseline"]
+            if baseline["status"] == "pass":
+                next_action = "Start daily work with ultra-change."
+                route = "ultra-change"
+                readiness = "ready"
+            else:
+                next_action = "Initialize or complete project baseline adoption through ultra-init."
+                route = "ultra-init"
+                readiness = "blocked"
+            return {
+                "change_id": None,
+                "task_id": None,
+                "role": "plan",
+                "gate": "alignment",
+                "readiness": readiness,
+                "blockers": baseline["blockers"],
+                "warnings": baseline["warnings"],
+                "next_action": next_action,
+                "recommended_workflow": route,
+                "context_manifest_path": None,
+                "context_manifest_hash": None,
+                "git_head": git_head(root),
+                "baseline": current,
+            }
         tasks = list(conn.execute(
             "SELECT id, status, session_id FROM tasks WHERE change_id = ? ORDER BY created_at ASC",
             (change["id"],),
@@ -145,6 +258,7 @@ def read_breadcrumb(root: Path):
             not isinstance(context.get("resume"), dict)
             or not isinstance(context.get("context"), dict)
             or not isinstance(context.get("readiness"), dict)
+            or "baseline" not in context
         )
     )
     stored_status = context.get("resume", {}).get("task_status")
@@ -152,6 +266,7 @@ def read_breadcrumb(root: Path):
     state_changed = stored_status is not None and stored_status != current_status
     stored_action = snapshot["next_action"] if snapshot else None
     blockers = []
+    warnings = list(dict.fromkeys([*baseline["blockers"], *baseline["warnings"]]))
     if snapshot_missing:
         blockers.append("CONTEXT_NOT_COMPILED")
     else:
@@ -162,8 +277,14 @@ def read_breadcrumb(root: Path):
         if state_changed:
             blockers.append("CONTEXT_TASK_STATE_STALE")
         for blocker in safe_json(snapshot["blockers_json"], []):
-            if blocker not in blockers:
+            if blocker in ADVISORY_CONTEXT_CODES or str(blocker).startswith("BASELINE_"):
+                if blocker not in warnings:
+                    warnings.append(blocker)
+            elif blocker not in blockers:
                 blockers.append(blocker)
+        for warning in context.get("readiness", {}).get("warnings", []):
+            if warning not in warnings:
+                warnings.append(warning)
     readiness = "blocked" if blockers else snapshot["readiness"]
     if snapshot_missing:
         next_action = f"Compile change.context for change {change['id']} before continuing."
@@ -174,7 +295,9 @@ def read_breadcrumb(root: Path):
     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)
+        next_action = _next_action(
+            change, task, tasks, role, readiness, stored_action, False, blockers
+        )
     return {
         "change_id": change["id"],
         "change_status": change["status"],
@@ -185,28 +308,42 @@ def read_breadcrumb(root: Path):
         "gate": gate,
         "readiness": readiness,
         "blockers": blockers,
+        "warnings": warnings,
         "next_action": next_action,
-        "recommended_workflow": _route(change, task, tasks, readiness),
+        "recommended_workflow": _route(change, task, tasks, readiness, blockers),
         "context_manifest_path": snapshot["manifest_path"] if snapshot else None,
         "context_manifest_hash": snapshot["manifest_hash"] if snapshot else None,
         "git_head": current_head,
+        "baseline": baseline["baseline"],
     }
 
 
 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')}",
-    ]
+    baseline = breadcrumb.get("baseline") or {}
+    if breadcrumb.get("change_id"):
+        lines = [
+            "[Ultra context spine]",
+            f"Project: {root}",
+            f"Baseline: {baseline.get('id', 'unknown')} ({baseline.get('mode', 'unknown')}/{baseline.get('status', 'unknown')})",
+            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')}",
+        ]
+    else:
+        lines = [
+            "[Ultra baseline]",
+            f"Project: {root}",
+            f"Baseline: {baseline.get('id', 'missing')} ({baseline.get('mode', 'unknown')}/{baseline.get('status', 'missing')})",
+            f"Readiness: {breadcrumb.get('readiness', 'blocked')}",
+        ]
     if breadcrumb.get("blockers"):
         lines.append("Blockers: " + ", ".join(breadcrumb["blockers"]))
+    if breadcrumb.get("warnings"):
+        lines.append("Warnings: " + ", ".join(breadcrumb["warnings"]))
     lines.extend([
         f"Next: {breadcrumb.get('next_action', 'Inspect Ultra status.')}",
         f"Route: {breadcrumb.get('recommended_workflow', 'ultra-change')}",

package/hooks/health_check.py

@@ -6,8 +6,11 @@ import sqlite3
 import sys
 from pathlib import Path
 
+from context_spine import baseline_health
+
 
 REQUIRED_TABLES = {
+    "baselines",
     "tasks", "events", "sessions", "schema_version", "migration_history",
     "telemetry", "specs_refs", "circuit_breaker", "changes", "artifacts",
     "context_snapshots", "spec_learning_candidates", "trace_links", "incidents", "projection_jobs",
@@ -48,6 +51,7 @@ def inspect(root: Path) -> dict:
     try:
         uri = f"file:{db_path}?mode=ro"
         with sqlite3.connect(uri, uri=True, timeout=1) as conn:
+            conn.row_factory = sqlite3.Row
             quick = conn.execute("PRAGMA quick_check").fetchone()[0]
             tables = {
                 row[0] for row in conn.execute(
@@ -66,6 +70,13 @@ def inspect(root: Path) -> dict:
                 report["status"] = "degraded"
                 return report
 
+            baseline = baseline_health(conn, root)
+            report["checks"]["baseline"] = {
+                **baseline,
+                "readiness": baseline["status"],
+                "status": "pass" if baseline["status"] == "pass" else "warning",
+            }
+
             incidents = [
                 {"id": row[0], "code": row[1], "severity": row[2], "retryable": bool(row[3])}
                 for row in conn.execute(

package/hooks/pre_stop_check.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Block stop only when the active Ultra workflow itself is incomplete."""
+"""Report unfinished Ultra workflow position without trapping session stop."""
 
 import sys
 import json
@@ -12,8 +12,9 @@ def allow_stop() -> None:
     print(json.dumps({}))
 
 
-def block_stop(reason: str) -> None:
-    print(json.dumps({"decision": "block", "reason": reason}))
+def advise_stop(reason: str) -> None:
+    print(f"[Ultra stop advisory] {reason}", file=sys.stderr)
+    allow_stop()
 
 
 def main():
@@ -41,12 +42,12 @@ def main():
         if not isinstance(state, dict) or state.get("status") in TERMINAL:
             allow_stop()
             return
-        block_stop(
+        advise_stop(
             "Active Ultra workflow is incomplete: "
             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')}. "
-            "Complete or explicitly cancel the Ultra workflow before stopping."
+            "Resume or explicitly cancel it in a later session; stop is allowed."
         )
         return
     allow_stop()

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