ultra-builder-pro-cli 0.11.0 → 0.13.0

package/mcp-server/lib/context-spine.cjs

@@ -4,6 +4,7 @@ const crypto = require('node:crypto');
 const fs = require('node:fs');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
+const baselines = require('./baseline-workflow.cjs');
 
 const ROLES = new Set(['plan', 'implement', 'check', 'review']);
 const GATES = new Set([
@@ -12,6 +13,12 @@ const GATES = new Set([
 const CONTEXT_KINDS = new Set(['spec', 'source', 'test', 'docs', 'external']);
 const SLICE_KINDS = new Set(['tracer_bullet', 'expand_contract', 'integration_checkpoint']);
 const DEFAULT_BUDGET = Object.freeze({ max_tokens: 12_000, max_files: 12 });
+const ADVISORY_CONTEXT_CODES = new Set([
+  'CONTEXT_FILE_BUDGET_EXCEEDED',
+  'CONTEXT_TOKEN_BUDGET_EXCEEDED',
+  'EXECUTION_CONTEXT_BUDGET_EXCEEDED',
+  'EXECUTION_CONTEXT_BUDGET_ADVISORY',
+]);
 
 class ContextSpineError extends Error {
   constructor(code, message) {
@@ -149,8 +156,13 @@ function defaultGate(role) {
   }[role];
 }
 
-function deriveNextAction({ change, tasks, task, role, readiness, explicit }) {
-  if (readiness === 'blocked') return 'Resolve the context readiness blockers, then recompile change.context.';
+function deriveNextAction({ change, tasks, task, role, readiness, blockers = [], explicit }) {
+  if (readiness === 'blocked') {
+    if (blockers.some((blocker) => blocker.startsWith('BASELINE_'))) {
+      return 'Complete or refresh the Ultra project baseline, then recompile change.context.';
+    }
+    return 'Resolve the context readiness blockers, then recompile change.context.';
+  }
   if (explicit && String(explicit).trim()) return String(explicit).trim();
   if (change.status === 'ready') return `Run ultra-deliver for change ${change.id}.`;
   if (change.status === 'blocked') return `Resolve the blockers for change ${change.id}, then recompile context.`;
@@ -199,12 +211,19 @@ function compileRoleContext(db, { input, change, tasks, rootDir }) {
     input, inherited.execution_contract, { taskId: input.task_id },
   );
   const blockers = [];
+  const warnings = [];
+  const baselineHealth = baselines.inspectBaseline(db, { rootDir });
+  // An active change must remain executable even when adoption is incomplete or
+  // the repository has moved. Approved adoption is required at convergence and
+  // full revision/spec health is required at archive; here both are recovery
+  // guidance, not a refusal.
+  warnings.push(...baselineHealth.blockers, ...baselineHealth.warnings);
   for (const item of items) {
     if (item.required && item.status === 'missing') blockers.push(`CONTEXT_REQUIRED_REF_MISSING:${item.ref}`);
     if (item.required && item.status === 'stale') blockers.push(`CONTEXT_REQUIRED_REF_STALE:${item.ref}`);
   }
-  if (fileCount > budget.max_files) blockers.push('CONTEXT_FILE_BUDGET_EXCEEDED');
-  if (tokenEstimate > budget.max_tokens) blockers.push('CONTEXT_TOKEN_BUDGET_EXCEEDED');
+  if (fileCount > budget.max_files) warnings.push('CONTEXT_FILE_BUDGET_EXCEEDED');
+  if (tokenEstimate > budget.max_tokens) warnings.push('CONTEXT_TOKEN_BUDGET_EXCEEDED');
   if (input.task_id) {
     if (!executionContract) blockers.push('EXECUTION_CONTRACT_MISSING');
     else {
@@ -212,21 +231,29 @@ function compileRoleContext(db, { input, change, tasks, rootDir }) {
       if (!executionContract.verification_command) blockers.push('EXECUTION_VERIFICATION_COMMAND_MISSING');
       if (executionContract.slice_kind !== 'expand_contract'
         && executionContract.context_budget_percent > 40) {
-        blockers.push('EXECUTION_CONTEXT_BUDGET_EXCEEDED');
+        warnings.push('EXECUTION_CONTEXT_BUDGET_ADVISORY');
       }
     }
   }
   const readiness = blockers.length === 0 ? 'ready' : 'blocked';
   const nextAction = deriveNextAction({
-    change, tasks, task, role, readiness, explicit: input.next_action,
+    change, tasks, task, role, readiness, blockers, explicit: input.next_action,
   });
   return {
     role,
     gate,
     next_action: nextAction,
-    readiness: { status: readiness, blockers },
+    readiness: { status: readiness, blockers, warnings: [...new Set(warnings)] },
     context: { items, budget, token_estimate: tokenEstimate, file_count: fileCount },
     execution_contract: executionContract,
+    baseline: baselineHealth.baseline ? {
+      id: baselineHealth.baseline.id,
+      mode: baselineHealth.baseline.mode,
+      status: baselineHealth.baseline.status,
+      repository_revision: baselineHealth.baseline.repository_revision,
+      health: baselineHealth.status,
+      warnings: [...new Set([...baselineHealth.blockers, ...baselineHealth.warnings])],
+    } : null,
     selected_task: task,
     resume: {
       change_id: change.id,
@@ -250,6 +277,7 @@ function recommendedWorkflow(change, task, tasks, readiness) {
 }
 
 function readBreadcrumb(db, { id } = {}, { rootDir = process.cwd() } = {}) {
+  const baselineHealth = baselines.inspectBaseline(db, { rootDir });
   const change = id
     ? db.prepare('SELECT * FROM changes WHERE id = ?').get(id)
     : db.prepare(
@@ -259,10 +287,32 @@ function readBreadcrumb(db, { id } = {}, { rootDir = process.cwd() } = {}) {
     throw new ContextSpineError('CHANGE_NOT_FOUND', `change ${id} not found`);
   }
   if (!change) {
+    const baseline = baselineHealth.baseline;
+    if (baselineHealth.status !== 'pass') {
+      const nextAction = baseline
+        ? `Complete ${baseline.mode} baseline adoption ${baseline.id} through ultra-init.`
+        : 'Initialize the project and start baseline adoption with ultra-init.';
+      return {
+        change_id: null, task_id: null, role: 'plan', gate: 'alignment', readiness: 'blocked',
+        blockers: baselineHealth.blockers, warnings: baselineHealth.warnings, next_action: nextAction,
+        recommended_workflow: 'ultra-init', context_manifest_path: null,
+        context_manifest_hash: null, git_head: currentHead(rootDir),
+        baseline: baseline ? {
+          id: baseline.id, mode: baseline.mode, status: baseline.status,
+          repository_revision: baseline.repository_revision,
+        } : null,
+      };
+    }
     return {
       change_id: null, task_id: null, role: 'plan', gate: 'alignment', readiness: 'ready',
       next_action: 'Start daily work with ultra-change.', recommended_workflow: 'ultra-change',
       context_manifest_path: null, context_manifest_hash: null, git_head: currentHead(rootDir),
+      blockers: [], warnings: baselineHealth.warnings,
+      baseline: {
+        id: baselineHealth.baseline.id, mode: baselineHealth.baseline.mode,
+        status: baselineHealth.baseline.status,
+        repository_revision: baselineHealth.baseline.repository_revision,
+      },
     };
   }
   const tasks = db.prepare('SELECT * FROM tasks WHERE change_id = ? ORDER BY created_at ASC').all(change.id);
@@ -275,18 +325,26 @@ function readBreadcrumb(db, { id } = {}, { rootDir = process.cwd() } = {}) {
   const task = tasks.find((row) => row.id === taskId) || null;
   const head = currentHead(rootDir);
   const snapshotMissing = !snapshot;
-  const legacyContext = Boolean(snapshot && (!context.resume || !context.context || !context.readiness));
+  const legacyContext = Boolean(
+    snapshot && (!context.resume || !context.context || !context.readiness || !('baseline' in context)),
+  );
   const headStale = Boolean(snapshot?.git_head && head && snapshot.git_head !== head);
   const stateChanged = context.resume?.task_status !== undefined
     && context.resume.task_status !== (task?.status || null);
   const blockers = [];
+  const warnings = [...baselineHealth.blockers, ...baselineHealth.warnings];
   if (snapshotMissing) blockers.push('CONTEXT_NOT_COMPILED');
   else {
     if (legacyContext) blockers.push('CONTEXT_SNAPSHOT_UPGRADE_REQUIRED');
     if (headStale) blockers.push('CONTEXT_HEAD_STALE');
     if (stateChanged) blockers.push('CONTEXT_TASK_STATE_STALE');
     for (const blocker of parseJson(snapshot.blockers_json, [])) {
-      if (!blockers.includes(blocker)) blockers.push(blocker);
+      if (ADVISORY_CONTEXT_CODES.has(blocker) || blocker.startsWith('BASELINE_')) {
+        if (!warnings.includes(blocker)) warnings.push(blocker);
+      } else if (!blockers.includes(blocker)) blockers.push(blocker);
+    }
+    for (const warning of context.readiness?.warnings || []) {
+      if (!warnings.includes(warning)) warnings.push(warning);
     }
   }
   const readiness = blockers.length > 0 ? 'blocked' : snapshot.readiness;
@@ -302,6 +360,7 @@ function readBreadcrumb(db, { id } = {}, { rootDir = process.cwd() } = {}) {
   } else {
     nextAction = deriveNextAction({
       change, tasks, task, role: snapshot?.role || 'plan', readiness,
+      blockers,
       explicit: snapshot?.next_action,
     });
   }
@@ -315,11 +374,17 @@ function readBreadcrumb(db, { id } = {}, { rootDir = process.cwd() } = {}) {
     gate: snapshot?.gate || 'alignment',
     readiness,
     blockers,
+    warnings: [...new Set(warnings)],
     next_action: nextAction,
     recommended_workflow: recommendedWorkflow(change, task, tasks, readiness),
     context_manifest_path: snapshot?.manifest_path || null,
     context_manifest_hash: snapshot?.manifest_hash || null,
     git_head: head,
+    baseline: baselineHealth.baseline ? {
+      id: baselineHealth.baseline.id, mode: baselineHealth.baseline.mode,
+      status: baselineHealth.baseline.status,
+      repository_revision: baselineHealth.baseline.repository_revision,
+    } : null,
   };
 }
 

package/mcp-server/lib/context-spine.test.cjs

@@ -11,6 +11,21 @@ const { initStateDb } = require('./state-db.cjs');
 const { createChange } = require('./change-workflow.cjs');
 const { createTask } = require('./state-ops.cjs');
 
+test('breadcrumb routes a project without a converged baseline back to adoption', () => {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-spine-baseline-'));
+  const { db } = initStateDb(path.join(rootDir, '.ultra', 'state.db'));
+  try {
+    const breadcrumb = readBreadcrumb(db, {}, { rootDir });
+    assert.equal(breadcrumb.readiness, 'blocked');
+    assert.ok(breadcrumb.blockers.includes('BASELINE_MISSING'));
+    assert.equal(breadcrumb.recommended_workflow, 'ultra-init');
+    assert.match(breadcrumb.next_action, /baseline|adoption/i);
+  } finally {
+    db.close();
+    fs.rmSync(rootDir, { recursive: true, force: true });
+  }
+});
+
 test('deriveNextAction gives one state-specific action instead of a workflow dump', () => {
   const change = { id: 'context-spine', status: 'active' };
   const task = { id: 'task-1', status: 'in_progress' };
@@ -37,6 +52,11 @@ test('a task is not plan-ready before its execution contract is compiled', () =>
   const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-spine-plan-'));
   const { db } = initStateDb(path.join(rootDir, '.ultra', 'state.db'));
   try {
+    db.prepare(
+      `INSERT INTO baselines
+       (id, project_name, mode, status, approved_by, approval_note, converged_at)
+       VALUES ('test-baseline', 'fixture', 'greenfield', 'ready', 'test', 'accepted fixture', ?)`,
+    ).run(new Date().toISOString());
     const { change } = createChange(db, {
       id: 'planning-contract', title: 'Planning contract', kind: 'standard',
       intent: 'Require an executable fresh-context slice before implementation.',

package/mcp-server/lib/doctor.cjs

@@ -8,6 +8,9 @@ const ops = require('./state-ops.cjs');
 const runtime = require('./runtime-state.cjs');
 const projector = require('./projector.cjs');
 const recovery = require('../../orchestrator/recovery.cjs');
+const baselines = require('./baseline-workflow.cjs');
+const changes = require('./change-workflow.cjs');
+const archiveJournal = require('./archive-journal.cjs');
 
 const SPEC_CONSUMER = 'spec-staleness';
 
@@ -48,8 +51,14 @@ function inspectSystem(db, { rootDir = process.cwd() } = {}) {
          WHERE status IN ('active', 'blocked', 'ready') AND artifact_root IS NOT NULL`,
       ).all().filter((row) => row.artifact_root && !fs.existsSync(path.resolve(rootDir, row.artifact_root))).length
     : 0;
+  const archiveIntents = missing.length === 0 ? archiveJournal.listArchiveIntents(rootDir) : [];
+  const corruptArchiveIntents = archiveIntents.filter((item) => item.error).length;
+  const baseline = missing.length === 0
+    ? baselines.inspectBaseline(db, { rootDir })
+    : { status: 'fail', blockers: ['BASELINE_STATE_UNAVAILABLE'], warnings: [], baseline: null };
   const degraded = integrity !== 'ok' || missing.length > 0 || incidents.length > 0
     || pending.length > 0 || running.length > 0 || failed.length > 0 || orphanSessions > 0 || activeMissing > 0
+    || archiveIntents.length > 0
     || eventCursor > projectedCursor;
   return {
     status: degraded ? 'degraded' : 'healthy',
@@ -63,6 +72,23 @@ function inspectSystem(db, { rootDir = process.cwd() } = {}) {
       },
       sessions: { status: orphanSessions === 0 ? 'pass' : 'fail', orphan: orphanSessions },
       change_artifacts: { status: activeMissing === 0 ? 'pass' : 'fail', missing: activeMissing },
+      archive_recovery: {
+        status: archiveIntents.length === 0 ? 'pass' : 'fail',
+        pending: archiveIntents.length, corrupt: corruptArchiveIntents,
+      },
+      baseline: {
+        status: baseline.status === 'pass' ? 'pass' : 'warning',
+        readiness: baseline.status,
+        mode: baseline.baseline?.mode || null,
+        baseline_status: baseline.baseline?.status || null,
+        id: baseline.baseline?.id || null,
+        repository_revision: baseline.baseline?.repository_revision || null,
+        repository_branch: baseline.baseline?.repository_branch || null,
+        worktree_state: baseline.baseline?.worktree_state || 'unavailable',
+        gaps: baseline.baseline ? baselines.summarizeGaps(baseline.baseline.gaps) : null,
+        blockers: baseline.blockers,
+        warnings: baseline.warnings,
+      },
       external_providers: {
         status: 'pass', ownership: 'external',
         note: 'Ultra stores provider metadata references only and never owns memory or code-graph content.',
@@ -86,6 +112,7 @@ async function runDoctor(db, {
 } = {}) {
   if (!repair) return { ...inspectSystem(db, { rootDir }), repair_performed: false };
   const backupPath = await backupDatabase(db, rootDir);
+  const archives = changes.recoverInterruptedArchives(db, { rootDir });
   const recovered = recovery.recoverOnBoot(db);
   const cursor = runtime.readConsumerCursor(db, SPEC_CONSUMER);
   const consumed = ops.consumeSpecChangedEvents(db, { since_id: cursor, limit: 500 });
@@ -100,7 +127,7 @@ async function runDoctor(db, {
     ...inspectSystem(db, { rootDir }),
     repair_performed: true,
     backup_path: backupPath,
-    repair: { recovered, consumed, interrupted, requeued, ensured, projections },
+    repair: { archives, recovered, consumed, interrupted, requeued, ensured, projections },
   };
 }
 

package/mcp-server/lib/doctor.test.cjs

@@ -10,10 +10,20 @@ const { initStateDb, closeStateDb } = require('./state-db.cjs');
 const ops = require('./state-ops.cjs');
 const runtime = require('./runtime-state.cjs');
 const doctor = require('./doctor.cjs');
+const baselines = require('./baseline-workflow.cjs');
+const changes = require('./change-workflow.cjs');
+const archiveJournal = require('./archive-journal.cjs');
 
-function fixture() {
+function fixture({ baseline = true } = {}) {
   const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-doctor-'));
   const { db } = initStateDb(path.join(rootDir, '.ultra', 'state.db'));
+  if (baseline) {
+    db.prepare(
+      `INSERT INTO baselines
+       (id, project_name, mode, status, approved_by, approval_note, converged_at)
+       VALUES ('test-baseline', 'fixture', 'greenfield', 'ready', 'test', 'accepted fixture', ?)`,
+    ).run(new Date().toISOString());
+  }
   return { rootDir, db };
 }
 
@@ -35,6 +45,25 @@ test('doctor reports structured health for an initialized Ultra project', async
   }
 });
 
+test('doctor reports incomplete brownfield adoption as advisory rather than authority failure', async () => {
+  const fx = fixture({ baseline: false });
+  try {
+    baselines.startBaseline(fx.db, {
+      id: 'adoption', project_name: 'legacy', mode: 'brownfield', scope: ['.'],
+    }, { rootDir: fx.rootDir, emitEvent: false });
+    const report = await doctor.runDoctor(fx.db, { rootDir: fx.rootDir });
+    assert.equal(report.status, 'healthy');
+    assert.equal(report.checks.baseline.status, 'warning');
+    assert.equal(report.checks.baseline.mode, 'brownfield');
+    assert.deepEqual(report.checks.baseline.gaps, {
+      total: 0, open: 0, blocking: 0, by_category: {},
+    });
+    assert.ok(report.checks.baseline.blockers.includes('BASELINE_NOT_READY:adopting'));
+  } finally {
+    cleanup(fx);
+  }
+});
+
 test('doctor repair is backup-first and drains projection/spec-event recovery work', async () => {
   const fx = fixture();
   try {
@@ -84,3 +113,36 @@ test('doctor reports running projection work and repairs only stale interrupted
     cleanup(fx);
   }
 });
+
+test('doctor repair resumes an archive journal left after a process crash', async () => {
+  const fx = fixture();
+  try {
+    const activeRoot = path.join(fx.rootDir, '.ultra', 'changes', 'active', 'doctor-archive');
+    fs.mkdirSync(activeRoot, { recursive: true });
+    fs.writeFileSync(path.join(activeRoot, 'intent.md'), '# Authorized archive\n');
+    fx.db.prepare(
+      `INSERT INTO changes
+       (id, title, kind, status, intent, docs_impact_json, provider_refs_json, artifact_root)
+       VALUES ('doctor-archive', 'Recover archive', 'quick', 'ready', 'Recover it',
+               '{"status":"none","files":[],"rationale":"recovery"}', '{}',
+               '.ultra/changes/active/doctor-archive')`,
+    ).run();
+    const prepared = archiveJournal.prepareArchiveMove({
+      rootDir: fx.rootDir, change: changes.readChange(fx.db, 'doctor-archive'),
+      summary: 'Resume the authorized archive.', baselineUpdates: [],
+      noBaselineChangeReason: 'No baseline content changed.',
+    });
+    assert.equal(fs.existsSync(prepared.source), false);
+    const before = doctor.inspectSystem(fx.db, { rootDir: fx.rootDir });
+    assert.equal(before.status, 'degraded');
+    assert.equal(before.checks.archive_recovery.pending, 1);
+
+    const after = await doctor.runDoctor(fx.db, { rootDir: fx.rootDir, repair: true });
+    assert.equal(after.repair.archives.resumed, 1);
+    assert.equal(changes.readChange(fx.db, 'doctor-archive').status, 'archived');
+    assert.equal(after.checks.archive_recovery.pending, 0);
+    assert.equal(fs.existsSync(path.join(prepared.destination, archiveJournal.INTENT_FILE)), false);
+  } finally {
+    cleanup(fx);
+  }
+});