ultra-builder-pro-cli 0.10.0 → 0.12.1

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

@@ -8,12 +8,10 @@ const { spawnSync } = require('node:child_process');
 const ops = require('./state-ops.cjs');
 const contextSpine = require('./context-spine.cjs');
 const specLearning = require('./spec-learning.cjs');
+const providerRefs = require('./provider-refs.cjs');
+const baselines = require('./baseline-workflow.cjs');
 
 const CHANGE_ID = /^[a-zA-Z0-9_-]+$/;
-const PROVIDER_KINDS = new Set(['memory', 'code_graph']);
-const PROVIDER_FIELDS = new Set([
-  'provider', 'project', 'reference', 'revision', 'indexed_head', 'status',
-]);
 const CHANGE_PATCH_FIELDS = new Set(['title', 'intent', 'status', 'docs_impact', 'provider_refs']);
 const CHANGE_TRANSITIONS = Object.freeze({
   active: new Set(['active', 'blocked', 'cancelled']),
@@ -83,29 +81,7 @@ function normalizeDocsImpact(value) {
 }
 
 function normalizeProviderRefs(value) {
-  if (value == null) return {};
-  if (typeof value !== 'object' || Array.isArray(value)) {
-    throw new ChangeWorkflowError('VALIDATION_ERROR', 'provider_refs must be an object');
-  }
-  const out = {};
-  for (const [kind, ref] of Object.entries(value)) {
-    if (!PROVIDER_KINDS.has(kind) || !ref || typeof ref !== 'object' || Array.isArray(ref)) {
-      throw new ChangeWorkflowError('VALIDATION_ERROR', `invalid external provider reference: ${kind}`);
-    }
-    for (const key of Object.keys(ref)) {
-      if (!PROVIDER_FIELDS.has(key)) {
-        throw new ChangeWorkflowError(
-          'PROVIDER_CONTENT_FORBIDDEN',
-          `provider_refs.${kind}.${key} is not metadata; provider content remains external`,
-        );
-      }
-    }
-    if (typeof ref.provider !== 'string' || !ref.provider.trim()) {
-      throw new ChangeWorkflowError('VALIDATION_ERROR', `provider_refs.${kind}.provider required`);
-    }
-    out[kind] = { ...ref };
-  }
-  return out;
+  return providerRefs.normalizeProviderRefs(value, ChangeWorkflowError);
 }
 
 function gitHead(rootDir) {
@@ -254,6 +230,7 @@ function compileContext(db, input, { rootDir = process.cwd() } = {}) {
     readiness: spine.readiness,
     context: spine.context,
     execution_contract: spine.execution_contract,
+    baseline: spine.baseline,
     resume: spine.resume,
     providers,
     provider_boundary: 'metadata references only; memory and code graph content remain external',
@@ -504,6 +481,13 @@ function evidenceBlockers(change, evidence, tasks) {
   return blockers;
 }
 
+function baselineConvergenceBlockers(db) {
+  const baseline = baselines.readBaseline(db);
+  if (!baseline) return ['BASELINE_MISSING'];
+  if (baseline.status !== 'ready') return [`BASELINE_NOT_READY:${baseline.status}`];
+  return [];
+}
+
 function convergeChange(db, input, { rootDir = process.cwd() } = {}) {
   const change = readChange(db, input.id);
   if (!change) throw new ChangeWorkflowError('CHANGE_NOT_FOUND', `change ${input.id} not found`);
@@ -512,6 +496,7 @@ function convergeChange(db, input, { rootDir = process.cwd() } = {}) {
   }
   const tasks = db.prepare('SELECT id, type, status, stale FROM tasks WHERE change_id = ? ORDER BY id').all(change.id);
   const blockers = new Set(evidenceBlockers(change, input.evidence, tasks));
+  for (const blocker of baselineConvergenceBlockers(db)) blockers.add(blocker);
   if (tasks.length === 0) blockers.add('NO_TASKS');
   if (tasks.some((task) => !['completed', 'expanded'].includes(task.status))) blockers.add('TASKS_INCOMPLETE');
   if (tasks.some((task) => Boolean(task.stale))) blockers.add('TASK_CONTEXT_STALE');
@@ -671,6 +656,18 @@ function archiveChange(db, input, { rootDir = process.cwd() } = {}) {
       });
       db.prepare("UPDATE artifacts SET status = 'archived', updated_at = ? WHERE change_id = ?")
         .run(nowIso(), change.id);
+      baselines.reconcileBaseline(db, {
+        baseline_updates: updates,
+        change_id: change.id,
+      }, { rootDir });
+      const baselineHealth = baselines.inspectBaseline(db, { rootDir });
+      if (baselineHealth.blockers.length > 0) {
+        throw new ChangeWorkflowError(
+          'BASELINE_RECONCILIATION_INCOMPLETE',
+          `baseline reconciliation remains incomplete: ${baselineHealth.blockers.join(', ')}`,
+          { blockers: baselineHealth.blockers },
+        );
+      }
       ops.appendEventInTx(db, {
         type: 'change_archived', change_id: change.id,
         payload: { archive_path: relative, baseline_updates: updates, no_baseline_change_reason: noChangeReason || null },

package/mcp-server/lib/change-workflow.test.cjs

@@ -10,6 +10,7 @@ const { execFileSync } = require('node:child_process');
 const { initStateDb, closeStateDb } = require('./state-db.cjs');
 const ops = require('./state-ops.cjs');
 const changes = require('./change-workflow.cjs');
+const baselines = require('./baseline-workflow.cjs');
 
 function fixture() {
   const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-change-'));
@@ -20,6 +21,11 @@ function fixture() {
   execFileSync('git', ['add', 'README.md'], { cwd: rootDir });
   execFileSync('git', ['commit', '-q', '-m', 'seed'], { cwd: rootDir });
   const { db } = initStateDb(path.join(rootDir, '.ultra', 'state.db'));
+  db.prepare(
+    `INSERT INTO baselines
+     (id, project_name, mode, status, approved_by, approval_note, converged_at)
+     VALUES ('test-baseline', 'fixture', 'migrated', 'ready', 'test', 'legacy fixture', ?)`,
+  ).run(new Date().toISOString());
   return { rootDir, db };
 }
 
@@ -179,14 +185,82 @@ test('convergeChange blocks incomplete work and marks a fully evidenced standard
   }
 });
 
+test('convergeChange requires an approved baseline after active work has remained executable', () => {
+  const fx = fixture();
+  try {
+    changes.createChange(fx.db, {
+      id: 'chg-baseline-gate', title: 'Keep runtime work moving', kind: 'quick',
+      intent: 'Defer baseline closure to convergence without losing implementation progress.',
+      docs_impact: { status: 'none', files: [], rationale: 'Internal workflow behavior only.' },
+    }, { rootDir: fx.rootDir });
+    ops.createTask(fx.db, {
+      id: 'baseline-gate-task', title: 'Exercise convergence boundary', type: 'feature', priority: 'P0',
+      change_id: 'chg-baseline-gate',
+    });
+    ops.updateTaskStatus(fx.db, 'baseline-gate-task', 'in_progress');
+    ops.updateTaskStatus(fx.db, 'baseline-gate-task', 'completed');
+    changes.compileContext(fx.db, {
+      id: 'chg-baseline-gate', ...executionContext('baseline-gate-task'),
+    }, { rootDir: fx.rootDir });
+    fx.db.prepare('DELETE FROM baselines').run();
+
+    const result = changes.convergeChange(fx.db, {
+      id: 'chg-baseline-gate',
+      evidence: [
+        { category: 'diff', status: 'pass', evidence: 'diff reviewed' },
+        { category: 'tests', status: 'pass', evidence: 'workflow regression passed', seam: 'convergence gate' },
+        { category: 'spec', status: 'pass', evidence: 'change remains aligned' },
+      ],
+    }, { rootDir: fx.rootDir });
+
+    assert.equal(result.ready, false);
+    assert.ok(result.blockers.includes('BASELINE_MISSING'));
+  } finally {
+    cleanup(fx);
+  }
+});
+
 test('archiveChange moves a ready change into immutable history and records baseline reconciliation', () => {
   const fx = fixture();
   try {
+    fs.mkdirSync(path.join(fx.rootDir, '.ultra', 'specs'), { recursive: true });
+    fs.writeFileSync(path.join(fx.rootDir, '.ultra', 'specs', 'product.md'), '# Product\n\nCurrent behavior.\n');
+    fs.writeFileSync(path.join(fx.rootDir, '.ultra', 'specs', 'architecture.md'), '# Architecture\n\nCurrent boundary.\n');
+    const fileDigest = (file) => require('node:crypto').createHash('sha256')
+      .update(fs.readFileSync(file)).digest('hex');
+    fx.db.prepare(
+      `UPDATE baselines SET mode = 'brownfield', repository_revision = ?, spec_refs_json = ?
+       WHERE id = 'test-baseline'`,
+    ).run(
+      execFileSync('git', ['rev-parse', 'HEAD'], { cwd: fx.rootDir, encoding: 'utf8' }).trim(),
+      JSON.stringify([
+        {
+          kind: 'product', path: '.ultra/specs/product.md',
+          digest: fileDigest(path.join(fx.rootDir, '.ultra', 'specs', 'product.md')),
+        },
+        {
+          kind: 'architecture', path: '.ultra/specs/architecture.md',
+          digest: fileDigest(path.join(fx.rootDir, '.ultra', 'specs', 'architecture.md')),
+        },
+      ]),
+    );
     changes.createChange(fx.db, {
       id: 'chg-archive', title: 'Archive verified change', kind: 'quick',
       intent: 'Preserve the completed change as project history.',
       docs_impact: { status: 'none', files: [], rationale: 'Internal test-only behavior.' },
     }, { rootDir: fx.rootDir });
+    fs.appendFileSync(
+      path.join(fx.rootDir, '.ultra', 'specs', 'product.md'),
+      '\nBehavior learned and approved by this change.\n',
+    );
+    execFileSync('git', ['add', '.ultra/specs/product.md'], { cwd: fx.rootDir });
+    execFileSync('git', ['commit', '-q', '-m', 'update baseline behavior'], { cwd: fx.rootDir });
+    const changedHead = execFileSync(
+      'git', ['rev-parse', 'HEAD'], { cwd: fx.rootDir, encoding: 'utf8' },
+    ).trim();
+    const drift = baselines.inspectBaseline(fx.db, { rootDir: fx.rootDir });
+    assert.ok(drift.blockers.includes('BASELINE_HEAD_STALE'));
+    assert.ok(drift.blockers.includes('BASELINE_SPEC_STALE:.ultra/specs/product.md'));
     ops.createTask(fx.db, {
       id: 'archive-task', title: 'Complete archive path', type: 'bugfix', priority: 'P1',
       change_id: 'chg-archive',
@@ -214,7 +288,7 @@ test('archiveChange moves a ready change into immutable history and records base
 
     const archived = changes.archiveChange(fx.db, {
       id: 'chg-archive', summary: 'Verified quick fix archived.',
-      no_baseline_change_reason: 'No canonical spec changed.',
+      baseline_updates: ['.ultra/specs/product.md'],
     }, { rootDir: fx.rootDir });
     assert.equal(archived.change.status, 'archived');
     assert.ok(fs.existsSync(archived.archive_path));
@@ -228,6 +302,84 @@ test('archiveChange moves a ready change into immutable history and records base
       assert.doesNotMatch(artifact.path, /changes\/active/);
       assert.ok(fs.existsSync(path.join(fx.rootDir, artifact.path)), artifact.path);
     }
+    const reconciliation = fx.db.prepare(
+      "SELECT type, payload_json FROM events WHERE type = 'baseline_reconciled' ORDER BY id DESC LIMIT 1",
+    ).get();
+    assert.equal(reconciliation.type, 'baseline_reconciled');
+    assert.deepEqual(JSON.parse(reconciliation.payload_json).baseline_updates, ['.ultra/specs/product.md']);
+    const reconciled = baselines.inspectBaseline(fx.db, { rootDir: fx.rootDir });
+    assert.equal(reconciled.status, 'pass');
+    assert.equal(reconciled.baseline.repository_revision, changedHead);
+  } finally {
+    cleanup(fx);
+  }
+});
+
+test('archiveChange rolls back when declared reconciliation leaves a tracked specification stale', () => {
+  const fx = fixture();
+  try {
+    const specPath = path.join(fx.rootDir, '.ultra', 'specs', 'product.md');
+    fs.mkdirSync(path.dirname(specPath), { recursive: true });
+    fs.writeFileSync(specPath, '# Product\n\nOriginal behavior.\n');
+    const originalHead = execFileSync(
+      'git', ['rev-parse', 'HEAD'], { cwd: fx.rootDir, encoding: 'utf8' },
+    ).trim();
+    const originalDigest = require('node:crypto').createHash('sha256')
+      .update(fs.readFileSync(specPath)).digest('hex');
+    fx.db.prepare(
+      `UPDATE baselines SET mode = 'brownfield', repository_revision = ?, spec_refs_json = ?
+       WHERE id = 'test-baseline'`,
+    ).run(originalHead, JSON.stringify([
+      { kind: 'product', path: '.ultra/specs/product.md', digest: originalDigest },
+    ]));
+    changes.createChange(fx.db, {
+      id: 'chg-reconcile-rollback', title: 'Reject incomplete reconciliation', kind: 'quick',
+      intent: 'Keep the active change recoverable until every tracked specification is reconciled.',
+      docs_impact: { status: 'none', files: [], rationale: 'Workflow integrity only.' },
+    }, { rootDir: fx.rootDir });
+    fs.appendFileSync(specPath, '\nChanged behavior that must be declared.\n');
+    execFileSync('git', ['add', '.ultra/specs/product.md'], { cwd: fx.rootDir });
+    execFileSync('git', ['commit', '-q', '-m', 'change tracked product spec'], { cwd: fx.rootDir });
+    ops.createTask(fx.db, {
+      id: 'reconcile-rollback-task', title: 'Exercise archive rollback', type: 'feature', priority: 'P0',
+      change_id: 'chg-reconcile-rollback',
+    });
+    ops.updateTaskStatus(fx.db, 'reconcile-rollback-task', 'in_progress');
+    ops.updateTaskStatus(fx.db, 'reconcile-rollback-task', 'completed');
+    changes.compileContext(fx.db, {
+      id: 'chg-reconcile-rollback', ...executionContext('reconcile-rollback-task'),
+    }, { rootDir: fx.rootDir });
+    const converged = changes.convergeChange(fx.db, {
+      id: 'chg-reconcile-rollback',
+      evidence: [
+        { category: 'diff', status: 'pass', evidence: 'archive diff reviewed' },
+        {
+          category: 'tests', status: 'pass', evidence: 'archive rollback regression passed',
+          seam: 'archive reconciliation boundary',
+        },
+        { category: 'spec', status: 'pass', evidence: 'tracked specification change identified' },
+      ],
+    }, { rootDir: fx.rootDir });
+    assert.equal(converged.ready, true);
+
+    assert.throws(
+      () => changes.archiveChange(fx.db, {
+        id: 'chg-reconcile-rollback', summary: 'Attempt an incomplete archive.',
+        no_baseline_change_reason: 'No baseline update declared.',
+      }, { rootDir: fx.rootDir }),
+      (error) => error.code === 'BASELINE_RECONCILIATION_INCOMPLETE'
+        && error.details.blockers.includes('BASELINE_SPEC_STALE:.ultra/specs/product.md'),
+    );
+
+    const active = changes.readChange(fx.db, 'chg-reconcile-rollback');
+    assert.equal(active.status, 'ready');
+    assert.ok(fs.existsSync(path.join(fx.rootDir, active.artifact_root)));
+    assert.equal(fs.existsSync(path.join(fx.rootDir, active.artifact_root, 'archive-summary.md')), false);
+    assert.equal(baselines.readBaseline(fx.db).repository_revision, originalHead);
+    const reconciliationEvents = fx.db.prepare(
+      "SELECT COUNT(*) AS count FROM events WHERE type = 'baseline_reconciled' AND change_id = ?",
+    ).get('chg-reconcile-rollback');
+    assert.equal(reconciliationEvents.count, 0);
   } finally {
     cleanup(fx);
   }
@@ -447,12 +599,12 @@ test('compileContext v2 persists role-scoped context, budget, execution contract
   }
 });
 
-test('compileContext blocks a required missing ref or an over-budget role packet', () => {
+test('compileContext blocks a required missing ref', () => {
   const fx = fixture();
   try {
     changes.createChange(fx.db, {
       id: 'chg-context-budget', title: 'Bound context packet', kind: 'quick',
-      intent: 'Fail closed when required context is missing or too large.',
+      intent: 'Fail closed when required context is missing while reporting size pressure.',
     }, { rootDir: fx.rootDir });
     ops.createTask(fx.db, {
       id: 'budget-task', title: 'Compile bounded packet', type: 'bugfix', priority: 'P0',
@@ -466,14 +618,58 @@ test('compileContext blocks a required missing ref or an over-budget role packet
           { ref: 'missing-contract.md', kind: 'spec', reason: 'Required contract', required: true },
           { ref: 'README.md', kind: 'source', reason: 'Current implementation', required: true },
         ],
-        budget: { max_tokens: 1, max_files: 1 },
+        budget: { max_tokens: 2_000, max_files: 4 },
       }),
     }, { rootDir: fx.rootDir });
 
     assert.equal(compiled.manifest.readiness.status, 'blocked');
     assert.ok(compiled.manifest.readiness.blockers.includes('CONTEXT_REQUIRED_REF_MISSING:missing-contract.md'));
-    assert.ok(compiled.manifest.readiness.blockers.includes('CONTEXT_FILE_BUDGET_EXCEEDED'));
-    assert.ok(compiled.manifest.readiness.blockers.includes('CONTEXT_TOKEN_BUDGET_EXCEEDED'));
+  } finally {
+    cleanup(fx);
+  }
+});
+
+test('an incident can proceed with four necessary large files while context budgets remain advisory', () => {
+  const fx = fixture();
+  try {
+    const refs = [];
+    for (let index = 1; index <= 4; index += 1) {
+      const ref = `incident-runtime-${index}.cjs`;
+      fs.writeFileSync(path.join(fx.rootDir, ref), 'x'.repeat(8_000));
+      refs.push({
+        ref, kind: 'source', reason: `Required incident runtime boundary ${index}`, required: true,
+      });
+    }
+    changes.createChange(fx.db, {
+      id: 'chg-incident-context', title: 'Recover IM runtime', kind: 'incident',
+      intent: 'Keep an urgent root-cause fix executable when its required files exceed guidance.',
+    }, { rootDir: fx.rootDir });
+    ops.createTask(fx.db, {
+      id: 'incident-context-task', title: 'Repair IM terminal transition', type: 'bugfix', priority: 'P0',
+      change_id: 'chg-incident-context',
+    });
+
+    const compiled = changes.compileContext(fx.db, {
+      id: 'chg-incident-context',
+      ...executionContext('incident-context-task', {
+        context_refs: refs,
+        budget: { max_tokens: 100, max_files: 2 },
+        execution_contract: {
+          slice_kind: 'tracer_bullet',
+          public_seam: 'IM terminal transition',
+          verification_command: 'node --test im-terminal.test.cjs',
+          context_budget_percent: 80,
+        },
+      }),
+    }, { rootDir: fx.rootDir });
+
+    assert.equal(compiled.manifest.readiness.status, 'ready');
+    assert.deepEqual(compiled.manifest.readiness.blockers, []);
+    assert.ok(compiled.manifest.readiness.warnings.includes('CONTEXT_FILE_BUDGET_EXCEEDED'));
+    assert.ok(compiled.manifest.readiness.warnings.includes('CONTEXT_TOKEN_BUDGET_EXCEEDED'));
+    assert.ok(compiled.manifest.readiness.warnings.includes('EXECUTION_CONTEXT_BUDGET_ADVISORY'));
+    assert.equal(compiled.manifest.context.file_count, 4);
+    assert.ok(compiled.manifest.context.token_estimate > 100);
   } finally {
     cleanup(fx);
   }

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' };

package/mcp-server/lib/doctor.cjs

@@ -8,6 +8,7 @@ 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 SPEC_CONSUMER = 'spec-staleness';
 
@@ -48,6 +49,9 @@ 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 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
     || eventCursor > projectedCursor;
@@ -63,6 +67,16 @@ function inspectSystem(db, { rootDir = process.cwd() } = {}) {
       },
       sessions: { status: orphanSessions === 0 ? 'pass' : 'fail', orphan: orphanSessions },
       change_artifacts: { status: activeMissing === 0 ? 'pass' : 'fail', missing: activeMissing },
+      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,
+        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.',

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

@@ -10,10 +10,18 @@ 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');
 
-function fixture() {
+function fixture({ migratedBaseline = true } = {}) {
   const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-doctor-'));
   const { db } = initStateDb(path.join(rootDir, '.ultra', 'state.db'));
+  if (migratedBaseline) {
+    db.prepare(
+      `INSERT INTO baselines
+       (id, project_name, mode, status, approved_by, approval_note, converged_at)
+       VALUES ('test-baseline', 'fixture', 'migrated', 'ready', 'test', 'legacy fixture', ?)`,
+    ).run(new Date().toISOString());
+  }
   return { rootDir, db };
 }
 
@@ -35,6 +43,22 @@ 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({ migratedBaseline: 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.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 {