ultra-builder-pro-cli 0.23.0 → 0.24.1

package/hooks/workflow_resume.py

@@ -1,16 +1,16 @@
 #!/usr/bin/env python3
-"""Re-inject live DB authority after compaction; checkpoints are advisory only."""
+"""Re-inject the live Context Envelope after compaction; checkpoints are advisory."""
 
 import json
 import sys
 from datetime import datetime
 from pathlib import Path
 
-from context_spine import (
-    ContextSpineError,
+from context_envelope import (
+    ContextEnvelopeError,
     find_root_for_hook,
-    read_breadcrumb,
-    render_breadcrumb,
+    read_context_envelope,
+    render_context_envelope,
 )
 
 
@@ -35,10 +35,11 @@ def _checkpoint_advisory(root: Path):
         return None
     if (
         not isinstance(value, dict)
-        or value.get("schema") != 2
-        or not isinstance(value.get("breadcrumb"), dict)
+        or value.get("schema") != 3
+        or not isinstance(value.get("context"), dict)
         or not isinstance(value.get("rendered"), str)
         or not value["rendered"].strip()
+        or value.get("context_digest") != value["context"].get("digest")
     ):
         print(f"[workflow_resume] invalid checkpoint schema in {file}", file=sys.stderr)
         return None
@@ -46,7 +47,7 @@ def _checkpoint_advisory(root: Path):
         "[Ultra checkpoint advisory]",
         "Live .ultra/.runtime/state.db could not be read; this checkpoint is not authority.",
         value["rendered"],
-        "Run ultra-doctor before mutation.",
+        "Run ultra.doctor before mutation.",
     ])
 
 
@@ -66,11 +67,11 @@ def main() -> None:
         return
     text = None
     try:
-        breadcrumb = read_breadcrumb(root)
-        if breadcrumb and breadcrumb.get("workflow"):
-            text = render_breadcrumb(root, breadcrumb)
-    except ContextSpineError as exc:
-        print(f"[workflow_resume] cannot inspect Context Spine: {exc}", file=sys.stderr)
+        envelope = read_context_envelope(root)
+        if envelope:
+            text = render_context_envelope(root, envelope)
+    except ContextEnvelopeError as exc:
+        print(f"[workflow_resume] cannot inspect Context Envelope: {exc}", file=sys.stderr)
         text = _checkpoint_advisory(root)
     if not text:
         print(json.dumps({}))

package/mcp-server/{breadcrumb.cjs → hook-context.cjs}

@@ -13,18 +13,16 @@ function main() {
   const requested = path.resolve(process.argv[discover ? 3 : 2] || process.cwd());
   const rootDir = discover ? runtime.findProjectRoot(requested) : requested;
   if (!rootDir) {
-    process.stdout.write(`${JSON.stringify({
-      root: null,
-      breadcrumb: null,
-      text: null,
-    })}\n`);
+    process.stdout.write(`${JSON.stringify({ root: null, context: null, text: null })}\n`);
     return;
   }
-  const breadcrumb = runtime.readProjectBreadcrumb(rootDir);
+  const context = runtime.readProjectContextEnvelope(rootDir, {
+    runtime: process.env.UBP_HOOK_RUNTIME || 'hook',
+  });
   process.stdout.write(`${JSON.stringify({
     root: rootDir,
-    breadcrumb,
-    text: breadcrumb ? runtime.renderProjectBreadcrumb(rootDir, breadcrumb) : null,
+    context,
+    text: context ? runtime.renderProjectContextEnvelope(rootDir, context) : null,
   })}\n`);
 }
 
@@ -32,7 +30,7 @@ if (require.main === module) {
   try {
     main();
   } catch (error) {
-    process.stderr.write(`${error.code || 'BREADCRUMB_FAILED'}: ${error.message}\n`);
+    process.stderr.write(`${error.code || 'CONTEXT_ENVELOPE_FAILED'}: ${error.message}\n`);
     process.exitCode = 2;
   }
 }

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

@@ -7,7 +7,7 @@ const { spawnSync } = require('node:child_process');
 
 const ops = require('./state-ops.cjs');
 const providerRefs = require('./provider-refs.cjs');
-const workflows = require('./workflow-state.cjs');
+const checkpoints = require('./stage-checkpoints.cjs');
 
 const BASELINE_ID = /^[a-zA-Z0-9_-]+$/;
 const MODES = new Set(['greenfield', 'brownfield']);
@@ -660,27 +660,10 @@ function storedReadyInvariantBlockers(baseline) {
   if (!Array.isArray(baseline.scope) || baseline.scope.length === 0) {
     blockers.push('BASELINE_SCOPE_MISSING');
   }
-  if (Array.isArray(baseline.spec_refs)) {
-    for (const kind of ['discovery', 'product', 'architecture']) {
-      if (!baseline.spec_refs.some((item) => item?.kind === kind)) {
-        blockers.push(`BASELINE_SPEC_MISSING:${kind}`);
-      }
-    }
-  }
-  if (!Array.isArray(baseline.evidence) || baseline.evidence.length === 0) {
-    blockers.push('BASELINE_EVIDENCE_MISSING');
-  } else if (baseline.mode === 'brownfield'
-    && !baseline.evidence.some((item) => item?.kind === 'source')) {
-    blockers.push('BASELINE_SOURCE_EVIDENCE_MISSING');
-  }
-  if (!Array.isArray(baseline.verification) || baseline.verification.length === 0) {
-    blockers.push('BASELINE_VERIFICATION_MISSING');
-  } else {
+  if (Array.isArray(baseline.verification)) {
     for (const item of baseline.verification) {
       if (!item || typeof item !== 'object') {
         blockers.push('BASELINE_STATE_INVALID:verification');
-      } else if (item.status === 'not_run') {
-        blockers.push(`BASELINE_VERIFICATION_NOT_RUN:${item.name || 'unknown'}`);
       } else if (item.status === 'known_red') {
         if (!String(item.rationale || '').trim()) {
           blockers.push(`BASELINE_KNOWN_RED_RATIONALE_MISSING:${item.name || 'unknown'}`);
@@ -688,7 +671,7 @@ function storedReadyInvariantBlockers(baseline) {
         if (!baseline.known_red_accepted) {
           blockers.push(`BASELINE_KNOWN_RED_NOT_ACCEPTED:${item.name || 'unknown'}`);
         }
-      } else if (item.status !== 'pass') {
+      } else if (!['pass', 'not_run'].includes(item.status)) {
         blockers.push(`BASELINE_VERIFICATION_STATUS_INVALID:${item.name || 'unknown'}`);
       }
     }
@@ -697,68 +680,103 @@ function storedReadyInvariantBlockers(baseline) {
     blockers.push('BASELINE_REVISION_MISSING');
   }
   if (!String(baseline.approved_by || '').trim()) blockers.push('BASELINE_APPROVER_MISSING');
-  if (String(baseline.approval_note || '').trim().length < 3) {
+  if (!String(baseline.approval_note || '').trim()) {
     blockers.push('BASELINE_APPROVAL_NOTE_MISSING');
   }
   if (!baseline.converged_at || Number.isNaN(Date.parse(baseline.converged_at))) {
     blockers.push('BASELINE_CONVERGENCE_TIMESTAMP_MISSING');
   }
+  return [...new Set(blockers)];
+}
+
+function storedReadySemanticWarnings(baseline) {
+  const warnings = [];
+  if (Array.isArray(baseline.spec_refs)) {
+    for (const kind of ['discovery', 'product', 'architecture']) {
+      if (!baseline.spec_refs.some((item) => item?.kind === kind)) {
+        warnings.push(`BASELINE_SPEC_MISSING:${kind}`);
+      }
+    }
+  }
+  if (Array.isArray(baseline.evidence) && baseline.evidence.length === 0) {
+    warnings.push('BASELINE_EVIDENCE_MISSING');
+  }
+  if (baseline.mode === 'brownfield'
+    && Array.isArray(baseline.evidence)
+    && !baseline.evidence.some((item) => item?.kind === 'source')) {
+    warnings.push('BASELINE_SOURCE_EVIDENCE_MISSING');
+  }
+  if (Array.isArray(baseline.verification) && baseline.verification.length === 0) {
+    warnings.push('BASELINE_VERIFICATION_MISSING');
+  } else if (Array.isArray(baseline.verification)) {
+    for (const item of baseline.verification) {
+      if (item?.status === 'not_run') {
+        warnings.push(`BASELINE_VERIFICATION_NOT_RUN:${item.name || 'unknown'}`);
+      }
+    }
+  }
   if (Array.isArray(baseline.unknowns)) {
     for (const item of baseline.unknowns.filter((unknown) => unknown?.blocking === true)) {
-      blockers.push(`BASELINE_UNKNOWN_BLOCKING:${item.summary || 'unknown'}`);
+      warnings.push(`BASELINE_UNKNOWN_RECORDED:${item.summary || 'unknown'}`);
     }
   }
   if (Array.isArray(baseline.gaps)) {
     for (const gap of baseline.gaps.filter((item) => (
       item?.status === 'open' && item?.blocking === true
     ))) {
-      blockers.push(`BASELINE_GAP_BLOCKING:${gap.id || 'unknown'}`);
+      warnings.push(`BASELINE_GAP_RECORDED:${gap.id || 'unknown'}`);
     }
   }
-  return [...new Set(blockers)];
+  return [...new Set(warnings)];
 }
 
-function completedBaselineResearch(db, baseline, rootDir) {
-  const acceptedMode = baseline.mode === 'greenfield' ? 'full' : 'adoption';
-  const rows = db.prepare(
-    `SELECT id FROM workflow_runs
-     WHERE kind = 'research' AND baseline_id = ? AND mode = ? AND status = 'completed'
-     ORDER BY completed_at DESC, rowid DESC`,
-  ).all(baseline.id, acceptedMode);
-  const row = rows.find((candidate) => workflows.isConsumableWorkflowAuthority(
-    workflows.readWorkflow(db, candidate.id, { rootDir }),
-  ));
-  return row ? workflows.readWorkflow(db, row.id, { rootDir }) : null;
+function acceptedBaselineResearch(db, baseline) {
+  return checkpoints.currentCheckpoint(
+    db,
+    'research',
+    { baseline_id: baseline.id },
+    { includeDraft: false },
+  );
 }
 
-function convergenceResearchBlockers(db, baseline, rootDir) {
-  const run = completedBaselineResearch(db, baseline, rootDir);
-  if (!run) return ['BASELINE_RESEARCH_INCOMPLETE'];
-  return run.artifact_health.blockers.map((item) => `BASELINE_RESEARCH_${item}`);
+function convergenceResearchBlockers(db, baseline) {
+  const checkpoint = acceptedBaselineResearch(db, baseline);
+  if (!checkpoint) return ['BASELINE_RESEARCH_INCOMPLETE'];
+  return [];
 }
 
-function storedResearchHealth(db, baseline, rootDir) {
-  if (!baseline.research_run_id) {
-    return { blockers: ['BASELINE_RESEARCH_PROVENANCE_MISSING'], warnings: [] };
+function storedResearchHealth(db, baseline) {
+  const checkpointId = baseline.research_checkpoint_id || baseline.research_run_id;
+  if (!checkpointId) {
+    return { blockers: [], warnings: ['BASELINE_RESEARCH_PROVENANCE_MISSING'] };
+  }
+  let checkpoint;
+  try {
+    checkpoint = checkpoints.readCheckpoint(db, checkpointId);
+  } catch (error) {
+    if (error?.code === 'CHECKPOINT_DIGEST_MISMATCH') {
+      return { blockers: ['BASELINE_RESEARCH_RECORD_INVALID'], warnings: [] };
+    }
+    throw error;
   }
-  const run = workflows.readWorkflow(db, baseline.research_run_id, { rootDir });
-  if (!run || run.kind !== 'research' || run.status !== 'completed') {
+  if (!checkpoint
+      || checkpoint.stage !== 'research'
+      || checkpoint.scope_type !== 'baseline'
+      || checkpoint.scope_id !== baseline.id
+      || checkpoints.checkpointDigest(checkpoint) !== checkpoint.digest) {
     return { blockers: ['BASELINE_RESEARCH_RECORD_INVALID'], warnings: [] };
   }
-  const livingSpecifications = new Set(
-    (Array.isArray(baseline.spec_refs) ? baseline.spec_refs : [])
-      .map((item) => item?.path).filter(Boolean),
-  );
-  const blockers = run.artifact_health.blockers.filter((item) => {
-    const separator = item.indexOf(':');
-    if (separator < 0) return true;
-    const artifactPath = item.slice(separator + 1);
-    return !livingSpecifications.has(artifactPath);
-  });
-  return {
-    blockers: blockers.map((item) => `BASELINE_RESEARCH_${item}`),
-    warnings: [],
-  };
+  if (checkpoint.status !== 'accepted') {
+    return {
+      blockers: [],
+      warnings: [
+        checkpoint.status === 'superseded'
+          ? 'BASELINE_RESEARCH_SUPERSEDED'
+          : `BASELINE_RESEARCH_NOT_ACCEPTED:${checkpoint.status}`,
+      ],
+    };
+  }
+  return { blockers: [], warnings: checkpoint.diagnostics || [] };
 }
 
 function convergenceBlockers(db, baseline, input, rootDir) {
@@ -777,10 +795,6 @@ function convergenceBlockers(db, baseline, input, rootDir) {
   if (baseline.repository_branch && snapshot.branch
     && baseline.repository_branch !== snapshot.branch) blockers.add('BASELINE_BRANCH_STALE');
   if (!Array.isArray(baseline.scope) || baseline.scope.length === 0) blockers.add('BASELINE_SCOPE_MISSING');
-  for (const kind of ['discovery', 'product', 'architecture']) {
-    if (!baseline.spec_refs.some((ref) => ref.kind === kind)) blockers.add(`BASELINE_SPEC_MISSING:${kind}`);
-  }
-  for (const blocker of convergenceResearchBlockers(db, baseline, rootDir)) blockers.add(blocker);
   for (const blocker of storedSpecBlockers(baseline, rootDir)) blockers.add(blocker);
   for (const blocker of storedEvidenceBlockers(baseline, rootDir)) blockers.add(blocker);
   for (const blocker of storedScopeBlockers(baseline, rootDir)) blockers.add(blocker);
@@ -791,29 +805,23 @@ function convergenceBlockers(db, baseline, input, rootDir) {
   if (baseline.worktree_state === 'dirty' && input.accept_dirty_worktree !== true) {
     blockers.add('BASELINE_DIRTY_WORKTREE_NOT_ACCEPTED');
   }
-  if (baseline.evidence.length === 0) blockers.add('BASELINE_EVIDENCE_MISSING');
-  if (baseline.mode === 'brownfield' && !baseline.evidence.some((item) => item.kind === 'source')) {
-    blockers.add('BASELINE_SOURCE_EVIDENCE_MISSING');
-  }
-  if (baseline.verification.length === 0) blockers.add('BASELINE_VERIFICATION_MISSING');
   for (const item of baseline.verification) {
-    if (item.status === 'not_run') blockers.add(`BASELINE_VERIFICATION_NOT_RUN:${item.name}`);
     if (item.status === 'known_red') {
       if (input.accept_known_red !== true) blockers.add(`BASELINE_KNOWN_RED_NOT_ACCEPTED:${item.name}`);
       if (!item.rationale) blockers.add(`BASELINE_KNOWN_RED_RATIONALE_MISSING:${item.name}`);
     }
   }
-  for (const item of baseline.unknowns.filter((unknown) => unknown.blocking)) {
-    blockers.add(`BASELINE_UNKNOWN_BLOCKING:${item.summary}`);
-  }
-  for (const gap of baseline.gaps.filter((item) => item.status === 'open' && item.blocking)) {
-    blockers.add(`BASELINE_GAP_BLOCKING:${gap.id}`);
-  }
   if (!String(input.approved_by || '').trim()) blockers.add('BASELINE_APPROVER_REQUIRED');
-  if (String(input.approval_note || '').trim().length < 3) blockers.add('BASELINE_APPROVAL_NOTE_REQUIRED');
+  if (!String(input.approval_note || '').trim()) blockers.add('BASELINE_APPROVAL_NOTE_REQUIRED');
   return [...blockers].sort();
 }
 
+function convergenceWarnings(db, baseline) {
+  const warnings = new Set(storedReadySemanticWarnings(baseline));
+  for (const warning of convergenceResearchBlockers(db, baseline)) warnings.add(warning);
+  return [...warnings].sort();
+}
+
 function convergeBaseline(db, input = {}, { rootDir = process.cwd(), emitEvent = true } = {}) {
   const current = readBaseline(db, input.id);
   if (!current) throw new BaselineWorkflowError('BASELINE_NOT_FOUND', `baseline ${input.id} not found`);
@@ -821,6 +829,7 @@ function convergeBaseline(db, input = {}, { rootDir = process.cwd(), emitEvent =
     throw new BaselineWorkflowError('BASELINE_NOT_CONVERGEABLE', `baseline ${current.id} is ${current.status}`);
   }
   const blockers = convergenceBlockers(db, current, input, rootDir);
+  const warnings = convergenceWarnings(db, current);
   const ts = nowIso();
   if (blockers.length > 0) {
     ops.tx(db, () => {
@@ -832,18 +841,25 @@ function convergeBaseline(db, input = {}, { rootDir = process.cwd(), emitEvent =
         });
       }
     });
-    return { ready: false, status: 'blocked', blockers, baseline: readBaseline(db, current.id) };
+    return {
+      ready: false,
+      status: 'blocked',
+      blockers,
+      warnings,
+      baseline: readBaseline(db, current.id),
+    };
   }
-  const research = completedBaselineResearch(db, current, rootDir);
+  const research = acceptedBaselineResearch(db, current);
   ops.tx(db, () => {
     db.prepare(
       `UPDATE baselines SET status = 'ready', approved_by = ?, approval_note = ?,
-       worktree_accepted = ?, known_red_accepted = ?, research_run_id = ?,
+       worktree_accepted = ?, known_red_accepted = ?, research_checkpoint_id = ?,
+       research_run_id = NULL,
        converged_at = ?, updated_at = ? WHERE id = ?`,
     ).run(
       String(input.approved_by).trim(), String(input.approval_note).trim(),
       input.accept_dirty_worktree === true ? 1 : 0,
-      input.accept_known_red === true ? 1 : 0, research.id, ts, ts, current.id,
+      input.accept_known_red === true ? 1 : 0, research?.id || null, ts, ts, current.id,
     );
     if (emitEvent) {
       ops.appendEventInTx(db, {
@@ -851,7 +867,13 @@ function convergeBaseline(db, input = {}, { rootDir = process.cwd(), emitEvent =
       });
     }
   });
-  return { ready: true, status: 'ready', blockers: [], baseline: readBaseline(db, current.id) };
+  return {
+    ready: true,
+    status: 'ready',
+    blockers: [],
+    warnings,
+    baseline: readBaseline(db, current.id),
+  };
 }
 
 function inspectBaseline(db, { rootDir = process.cwd(), id } = {}) {
@@ -874,7 +896,7 @@ function inspectBaseline(db, { rootDir = process.cwd(), id } = {}) {
       status: 'fail', blockers: [`BASELINE_NOT_READY:${baseline.status}`], warnings: [], baseline,
     };
   }
-  const research = storedResearchHealth(db, baseline, rootDir);
+  const research = storedResearchHealth(db, baseline);
   const blockers = [
     ...storedReadyInvariantBlockers(baseline),
     ...(Array.isArray(baseline.scope) ? storedScopeBlockers(baseline, rootDir) : []),
@@ -882,6 +904,10 @@ function inspectBaseline(db, { rootDir = process.cwd(), id } = {}) {
     ...(Array.isArray(baseline.evidence) ? storedEvidenceBlockers(baseline, rootDir) : []),
     ...research.blockers,
   ];
+  const warnings = [
+    ...storedReadySemanticWarnings(baseline),
+    ...research.warnings,
+  ];
   const snapshot = gitWorktreeSnapshot(
     rootDir, Array.isArray(baseline.scope) && baseline.scope.length > 0 ? baseline.scope : ['.'],
   );
@@ -911,7 +937,7 @@ function inspectBaseline(db, { rootDir = process.cwd(), id } = {}) {
   }
   return {
     status: blockers.length === 0 ? 'pass' : 'fail', blockers: [...new Set(blockers)].sort(),
-    warnings: research.warnings, baseline,
+    warnings: [...new Set(warnings)], baseline,
   };
 }
 

package/mcp-server/lib/canonical-json.cjs

@@ -0,0 +1,19 @@
+'use strict';
+
+const crypto = require('node:crypto');
+
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map(
+      (key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`,
+    ).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function digest(value) {
+  return crypto.createHash('sha256').update(canonicalJson(value)).digest('hex');
+}
+
+module.exports = { canonicalJson, digest };

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

@@ -0,0 +1,26 @@
+'use strict';
+
+const crypto = require('node:crypto');
+
+function parseJson(value, fallback = {}) {
+  if (typeof value !== 'string' || !value.trim()) return fallback;
+  try { return JSON.parse(value); } catch { return fallback; }
+}
+
+function changeStateDigest(change) {
+  if (!change) return null;
+  const payload = {
+    id: change.id,
+    kind: change.kind,
+    intent: change.intent,
+    docs_impact: change.docs_impact || parseJson(change.docs_impact_json, {}),
+    provider_refs: change.provider_refs || parseJson(change.provider_refs_json, {}),
+    contract: change.contract || parseJson(change.contract_json, {}),
+    classification: change.classification || parseJson(change.classification_json, {}),
+    research_disposition: change.research_disposition
+      || parseJson(change.research_disposition_json, {}),
+  };
+  return crypto.createHash('sha256').update(JSON.stringify(payload)).digest('hex');
+}
+
+module.exports = { changeStateDigest };