ultra-builder-pro-cli 0.16.0 → 0.17.0

package/mcp-server/lib/git-bootstrap.cjs

@@ -0,0 +1,240 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const GIT_MODES = new Set(['auto', 'initialize', 'skip']);
+// No trailing slash: isolated session worktrees expose `.ultra` as a symlink
+// to the central authority, and Git's directory-only pattern does not ignore
+// that symlink reliably.
+const ULTRA_IGNORE_LINE = '.ultra';
+
+class GitBootstrapError extends Error {
+  constructor(code, message, { cause } = {}) {
+    super(message);
+    this.name = 'GitBootstrapError';
+    this.code = code;
+    if (cause) this.cause = cause;
+  }
+}
+
+function runGit(rootDir, args) {
+  return spawnSync('git', args, {
+    cwd: rootDir,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+function gitValue(rootDir, args) {
+  const result = runGit(rootDir, args);
+  return result.status === 0 ? result.stdout.trim() : null;
+}
+
+function inspectGitRepository(rootDir) {
+  const repositoryRoot = gitValue(rootDir, ['rev-parse', '--show-toplevel']);
+  if (!repositoryRoot) {
+    return {
+      present: false,
+      repository_root: null,
+      branch: null,
+      head: null,
+    };
+  }
+  return {
+    present: true,
+    repository_root: path.resolve(repositoryRoot),
+    branch: gitValue(rootDir, ['symbolic-ref', '--quiet', '--short', 'HEAD'])
+      || gitValue(rootDir, ['branch', '--show-current']),
+    head: gitValue(rootDir, ['rev-parse', '--verify', 'HEAD']),
+  };
+}
+
+function initializeRepository(rootDir) {
+  let result = runGit(rootDir, ['init', '-q', '-b', 'main']);
+  if (result.status !== 0) {
+    result = runGit(rootDir, ['init', '-q']);
+    if (result.status === 0) {
+      const branch = runGit(rootDir, ['symbolic-ref', 'HEAD', 'refs/heads/main']);
+      if (branch.status !== 0) result = branch;
+    }
+  }
+  if (result.status !== 0) {
+    throw new GitBootstrapError(
+      'GIT_INIT_FAILED',
+      `git init failed: ${(result.stderr || result.stdout || 'unknown error').trim()}`,
+    );
+  }
+}
+
+function containsUltraIgnore(contents, { requireSymlinkSafe = false } = {}) {
+  const accepted = requireSymlinkSafe
+    ? ['.ultra', '/.ultra']
+    : ['.ultra', '.ultra/', '/.ultra', '/.ultra/'];
+  return contents.split(/\r?\n/).some((line) => {
+    const value = line.trim();
+    return accepted.includes(value);
+  });
+}
+
+function effectiveUltraIgnore(rootDir) {
+  return runGit(rootDir, ['check-ignore', '--quiet', '--no-index', '--', '.ultra']).status === 0;
+}
+
+function ensureUltraIgnored(rootDir, { requireSymlinkSafe = false } = {}) {
+  const file = path.join(rootDir, '.gitignore');
+  let stat = null;
+  try { stat = fs.lstatSync(file); }
+  catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  const existed = stat !== null;
+  if (stat) {
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+      throw new GitBootstrapError(
+        'GITIGNORE_UNSAFE',
+        `refusing to update non-regular root .gitignore: ${file}`,
+      );
+    }
+  }
+  const before = existed ? fs.readFileSync(file, 'utf8') : null;
+  if (!requireSymlinkSafe && effectiveUltraIgnore(rootDir)) {
+    return {
+      changed: false,
+      path: file,
+      rollback: { existed, before },
+    };
+  }
+  if (before !== null && containsUltraIgnore(before, { requireSymlinkSafe })) {
+    return {
+      changed: false,
+      path: file,
+      rollback: { existed, before },
+    };
+  }
+  const prefix = before && !before.endsWith('\n') ? `${before}\n` : (before || '');
+  const separator = prefix && !prefix.endsWith('\n\n') ? '\n' : '';
+  const next = `${prefix}${separator}# Ultra Builder Pro local authority\n${ULTRA_IGNORE_LINE}\n`;
+  fs.writeFileSync(file, next);
+  return {
+    changed: true,
+    path: file,
+    rollback: { existed, before },
+  };
+}
+
+function assertUltraIgnored(rootDir) {
+  const result = runGit(rootDir, ['check-ignore', '--quiet', '--no-index', '--', '.ultra']);
+  if (result.status === 0) return;
+  const detail = result.status === 1
+    ? 'the effective Git rules re-include .ultra'
+    : (result.stderr || result.stdout || 'Git could not evaluate the rule').trim();
+  throw new GitBootstrapError(
+    'GITIGNORE_INEFFECTIVE',
+    `Ultra authority is not ignored by Git: ${detail}`,
+  );
+}
+
+function rollbackGitBootstrap(rootDir, internal) {
+  const errors = [];
+  if (!internal) return errors;
+  const gitignore = internal.gitignore;
+  if (gitignore?.changed) {
+    try {
+      if (gitignore.rollback.existed) {
+        fs.writeFileSync(gitignore.path, gitignore.rollback.before);
+      } else {
+        fs.rmSync(gitignore.path, { force: true });
+      }
+    } catch (error) {
+      errors.push(`gitignore restore failed: ${error.message}`);
+    }
+  }
+  if (internal.created_repository) {
+    try {
+      fs.rmSync(path.join(rootDir, '.git'), { recursive: true, force: true });
+    } catch (error) {
+      errors.push(`git repository rollback failed: ${error.message}`);
+    }
+  }
+  return errors;
+}
+
+function bootstrapGit(rootDir, { mode = 'auto' } = {}) {
+  if (!GIT_MODES.has(mode)) {
+    throw new GitBootstrapError(
+      'VALIDATION_ERROR',
+      `git_mode must be one of: ${[...GIT_MODES].join(', ')}`,
+    );
+  }
+  const before = inspectGitRepository(rootDir);
+  if (!before.present && mode === 'skip') {
+    return {
+      result: {
+        requested_mode: mode,
+        status: 'skipped',
+        repository_root: null,
+        branch: null,
+        head: null,
+        gitignore_path: null,
+        gitignore_changed: false,
+        initial_commit_required: false,
+      },
+      internal: null,
+    };
+  }
+
+  const internal = {
+    created_repository: false,
+    gitignore: null,
+  };
+  try {
+    if (!before.present) {
+      initializeRepository(rootDir);
+      internal.created_repository = true;
+    }
+    internal.gitignore = ensureUltraIgnored(rootDir, {
+      // A repository created in this call has no tracked baseline to preserve,
+      // so its ignore rule can be made safe for the session authority symlink.
+      requireSymlinkSafe: internal.created_repository,
+    });
+    assertUltraIgnored(rootDir);
+    const after = inspectGitRepository(rootDir);
+    if (!after.present) {
+      throw new GitBootstrapError(
+        'GIT_INIT_FAILED',
+        'git initialization completed without a discoverable repository',
+      );
+    }
+    return {
+      result: {
+        requested_mode: mode,
+        status: internal.created_repository ? 'initialized' : 'existing',
+        repository_root: after.repository_root,
+        branch: after.branch,
+        head: after.head,
+        gitignore_path: path.relative(rootDir, internal.gitignore.path) || '.gitignore',
+        gitignore_changed: internal.gitignore.changed,
+        initial_commit_required: after.head === null,
+      },
+      internal,
+    };
+  } catch (error) {
+    rollbackGitBootstrap(rootDir, internal);
+    if (error instanceof GitBootstrapError) throw error;
+    throw new GitBootstrapError(
+      'GIT_INIT_FAILED',
+      `Git bootstrap failed: ${error.message}`,
+      { cause: error },
+    );
+  }
+}
+
+module.exports = {
+  GitBootstrapError,
+  GIT_MODES,
+  bootstrapGit,
+  inspectGitRepository,
+  rollbackGitBootstrap,
+};

package/mcp-server/lib/init-project.cjs

@@ -17,6 +17,7 @@ const path = require('node:path');
 const { EXPECTED_VERSION, initStateDb } = require('./state-db.cjs');
 const { assertStateAuthority, inspectProjection } = require('./state-authority.cjs');
 const baselines = require('./baseline-workflow.cjs');
+const gitBootstrap = require('./git-bootstrap.cjs');
 const runtimeState = require('./runtime-state.cjs');
 const ops = require('./state-ops.cjs');
 const workflows = require('./workflow-state.cjs');
@@ -406,6 +407,80 @@ function rollbackInitialization(ultraDir, backupPath) {
   return errors;
 }
 
+function createResumeSnapshot(db, ultraDir, stateDbPath) {
+  const token = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  const statePath = path.join(ultraDir, `.resume-state-${token}.db`);
+  const projectionDir = path.join(ultraDir, `.resume-projections-${token}`);
+  const projectionTargets = [
+    path.join('tasks', 'tasks.json'),
+    path.join('tasks', 'contexts'),
+  ];
+  try {
+    db.prepare('VACUUM INTO ?').run(statePath);
+    const projections = projectionTargets.map((relative) => {
+      const source = path.join(ultraDir, relative);
+      const existed = fs.existsSync(source);
+      if (existed) {
+        const destination = path.join(projectionDir, relative);
+        fs.mkdirSync(path.dirname(destination), { recursive: true });
+        fs.cpSync(source, destination, { recursive: true });
+      }
+      return { relative, existed };
+    });
+    return { statePath, projectionDir, projections, stateDbPath, ultraDir };
+  } catch (error) {
+    for (const target of [statePath, projectionDir]) {
+      try { fs.rmSync(target, { recursive: true, force: true }); } catch { /* best effort */ }
+    }
+    throw error;
+  }
+}
+
+function discardResumeSnapshot(snapshot) {
+  if (!snapshot) return [];
+  const errors = [];
+  for (const target of [snapshot.statePath, snapshot.projectionDir]) {
+    try { fs.rmSync(target, { recursive: true, force: true }); }
+    catch (error) { errors.push(`resume snapshot cleanup failed for ${target}: ${error.message}`); }
+  }
+  return errors;
+}
+
+function restoreResumeSnapshot(snapshot, { stateSourcePath = null } = {}) {
+  if (!snapshot) return [];
+  const errors = [];
+  const source = stateSourcePath && fs.existsSync(stateSourcePath)
+    ? stateSourcePath
+    : snapshot.statePath;
+  try {
+    for (const suffix of ['', '-wal', '-shm']) {
+      fs.rmSync(`${snapshot.stateDbPath}${suffix}`, { force: true });
+    }
+    if (source === snapshot.statePath) {
+      fs.renameSync(source, snapshot.stateDbPath);
+    } else {
+      fs.copyFileSync(source, snapshot.stateDbPath);
+    }
+  } catch (error) {
+    errors.push(`state.db restore failed: ${error.message}`);
+  }
+  for (const item of snapshot.projections) {
+    const target = path.join(snapshot.ultraDir, item.relative);
+    try {
+      fs.rmSync(target, { recursive: true, force: true });
+      if (item.existed) {
+        const source = path.join(snapshot.projectionDir, item.relative);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.cpSync(source, target, { recursive: true });
+      }
+    } catch (error) {
+      errors.push(`projection restore failed for ${item.relative}: ${error.message}`);
+    }
+  }
+  errors.push(...discardResumeSnapshot(snapshot));
+  return errors;
+}
+
 function projectionMigrationError(projection) {
   const targets = { '4.4': '4.5', '4.5': EXPECTED_VERSION };
   const target = targets[projection.version];
@@ -428,32 +503,13 @@ function ensureInitializationWorkflows(db, baseline, { rootDir }) {
   let initRun = workflows.listWorkflows(
     db, { kind: 'init', baseline_id: baseline.id, limit: 1 }, { rootDir },
   )[0];
-  let researchRun = workflows.listWorkflows(
+  const researchRun = workflows.listWorkflows(
     db, { kind: 'research', baseline_id: baseline.id, limit: 1 }, { rootDir },
   )[0];
-  if (baseline.status === 'ready') {
-    const compatibilityOnly = baseline.mode === 'migrated';
-    const provenanceComplete = !compatibilityOnly
-      && initRun?.status === 'completed'
-      && researchRun?.status === 'completed'
-      && baseline.research_run_id === researchRun.id;
-    return {
-      init_id: initRun?.id || null,
-      init_status: initRun?.status || 'missing',
-      research_id: researchRun?.id || null,
-      research_mode: researchRun?.mode || null,
-      research_status: compatibilityOnly
-        ? 'not_required' : (researchRun?.status || 'missing'),
-      provenance_status: compatibilityOnly
-        ? 'compatibility_only' : (provenanceComplete ? 'complete' : 'incomplete'),
-      next_action: compatibilityOnly
-        ? 'ultra-init' : (provenanceComplete ? 'ultra-change' : 'ultra-doctor'),
-    };
-  }
   if (!initRun) {
     initRun = workflows.startWorkflow(db, {
       kind: 'init', baseline_id: baseline.id,
-      subject: `Establish the ${baseline.mode} baseline for ${baseline.project_name}.`,
+      subject: `Initialize Ultra authority for ${baseline.project_name}.`,
       metadata: { repository_revision: baseline.repository_revision, scope: baseline.scope },
     }, { rootDir });
     for (const stepId of ['inspect-authority', 'classify-repository', 'scaffold-authority']) {
@@ -461,33 +517,49 @@ function ensureInitializationWorkflows(db, baseline, { rootDir }) {
         id: initRun.id, step_id: stepId, status: 'completed',
       }, { rootDir });
     }
-  }
-
-  if (baseline.mode !== 'migrated') {
-    if (!researchRun) {
-      const researchMode = baseline.mode === 'brownfield' ? 'adoption' : 'full';
-      researchRun = workflows.startWorkflow(db, {
-        kind: 'research', mode: researchMode, baseline_id: baseline.id,
-        subject: baseline.mode === 'brownfield'
-          ? 'Adopt the existing system as an evidence-backed product and architecture baseline.'
-          : 'Validate the complete product and architecture baseline before planning.',
-      }, { rootDir });
-    }
-  }
+    initRun = workflows.recordWorkflowStep(db, {
+      id: initRun.id,
+      step_id: 'verify-initialization',
+      status: 'completed',
+      evidence: [{
+        kind: 'authority',
+        ref: '.ultra/state.db',
+        summary: 'State authority, scaffold, projection, and repository classification were verified.',
+      }],
+    }, { rootDir });
+    initRun = workflows.completeWorkflow(db, { id: initRun.id }, { rootDir });
+  }
+  const compatibilityOnly = baseline.mode === 'migrated';
+  const provenanceComplete = !compatibilityOnly
+    && baseline.status === 'ready'
+    && initRun.status === 'completed'
+    && researchRun?.status === 'completed'
+    && baseline.research_run_id === researchRun.id;
+  const readyWithoutProvenance = baseline.status === 'ready' && !provenanceComplete;
+  const allowedTransitions = provenanceComplete
+    ? ['ultra-change', 'ultra-research', 'ultra-status', 'ultra-doctor']
+    : (readyWithoutProvenance
+      ? ['ultra-doctor', 'ultra-research', 'ultra-status']
+      : ['ultra-research', 'ultra-status', 'ultra-doctor']);
   return {
     init_id: initRun.id,
     init_status: initRun.status,
     research_id: researchRun?.id || null,
     research_mode: researchRun?.mode || null,
     research_status: researchRun?.status || 'not_started',
-    provenance_status: 'in_progress',
-    next_action: baseline.mode === 'migrated' ? 'ultra-init' : 'ultra-research',
+    provenance_status: compatibilityOnly
+      ? 'compatibility_only'
+      : (provenanceComplete ? 'complete' : (readyWithoutProvenance ? 'incomplete' : 'pending_research')),
+    allowed_transitions: allowedTransitions,
+    required_transition: readyWithoutProvenance
+      ? 'ultra-doctor'
+      : (compatibilityOnly ? 'ultra-research' : null),
   };
 }
 
 function resumeProject({
   absTarget, ultraDir, source, project_name, project_type, stack, resolvedMode,
-  scope, repositoryProfile, projection,
+  scope, repositoryProfile, projection, git_mode,
 }) {
   const stateDbPath = path.join(ultraDir, 'state.db');
   const stateExisted = fs.existsSync(stateDbPath);
@@ -495,12 +567,19 @@ function resumeProject({
   let copiedFiles = [];
   let baselineResult;
   let workflowResult;
+  let gitSetup;
+  let resumeSnapshot;
   try {
     initialized = initStateDb(stateDbPath);
     const { db } = initialized;
+    if (stateExisted) {
+      resumeSnapshot = createResumeSnapshot(db, ultraDir, stateDbPath);
+    }
     if (projection && projection.taskCount > 0) assertStateAuthority(db, absTarget);
     copiedFiles = copyMissingTemplate(source, ultraDir);
     validateTasksTemplate(ultraDir);
+    gitSetup = gitBootstrap.bootstrapGit(absTarget, { mode: git_mode });
+    repositoryProfile.git = gitSetup.result;
     baselineResult = baselines.readBaseline(db);
     if (!baselineResult) {
       baselineResult = baselines.startBaseline(db, {
@@ -509,23 +588,42 @@ function resumeProject({
         scope: scope === undefined ? ['.'] : scope,
         classification: repositoryProfile,
       }, { rootDir: absTarget });
+    } else {
+      baselineResult = baselines.refreshInProgressBaseline(db, {
+        id: baselineResult.id,
+        project_name,
+        project_type,
+        stack,
+        classification: repositoryProfile,
+      }, { rootDir: absTarget });
     }
     workflowResult = ensureInitializationWorkflows(db, baselineResult, { rootDir: absTarget });
     ops.appendEvent(db, {
       type: 'project_resumed',
       payload: {
         project_name, mode: baselineResult.mode, baseline_id: baselineResult.id,
-        installed_missing_files: copiedFiles.length,
+        installed_missing_files: copiedFiles.length, git: gitSetup.result,
       },
     });
     const job = runtimeState.enqueueProjection(db, { tool_name: 'task.init_project' });
     const projectionResult = runtimeState.processProjectionJobs(db, { rootDir: absTarget, limit: 1 });
     const projected = projectionResult.jobs.find((item) => item.id === job.id);
     if (!projected || projected.status !== 'completed') {
-      throw new Error(projected?.error || 'resume projection did not complete');
+      throw new Error(
+        `resume projection did not complete: ${projected?.error || 'projection job missing'}`,
+      );
     }
   } catch (error) {
     if (initialized?.db?.open) initialized.db.close();
+    const stateRollbackErrors = stateExisted
+      ? restoreResumeSnapshot(resumeSnapshot, {
+        // initStateDb creates this durable snapshot before a schema migration.
+        // A later resume failure must return to the exact entry authority, not
+        // merely to the successfully migrated intermediate database.
+        stateSourcePath: initialized?.backup_path || null,
+      })
+      : [];
+    const gitRollbackErrors = gitBootstrap.rollbackGitBootstrap(absTarget, gitSetup?.internal);
     for (const rel of copiedFiles.reverse()) {
       try { fs.rmSync(path.join(ultraDir, rel), { force: true }); } catch { /* best effort */ }
     }
@@ -534,15 +632,27 @@ function resumeProject({
         try { fs.rmSync(`${stateDbPath}${suffix}`, { force: true }); } catch { /* best effort */ }
       }
     }
+    const rollbackErrors = [...stateRollbackErrors, ...gitRollbackErrors];
     if (error.code && ['LEGACY_STATE_MIGRATION_REQUIRED', 'STATE_AUTHORITY_CONFLICT', 'STATE_PROJECTION_INVALID'].includes(error.code)) {
       throw new InitProjectError(error.code, error.message, { cause: error, details: error.details });
     }
+    if (error instanceof gitBootstrap.GitBootstrapError) {
+      throw new InitProjectError(
+        error.code,
+        `${error.message}${rollbackErrors.length ? `; ${rollbackErrors.join('; ')}` : ''}`,
+        { cause: error },
+      );
+    }
     throw new InitProjectError(
-      'IO_ERROR', `project resume failed: ${error.message}; existing .ultra assets were preserved`,
+      'IO_ERROR',
+      `project resume failed: ${error.message}; `
+        + `${rollbackErrors.length ? 'resume rollback was incomplete' : 'existing authority and projections were restored'}`
+        + `${rollbackErrors.length ? `; ${rollbackErrors.join('; ')}` : ''}`,
       { retriable: true, cause: error },
     );
   }
   initialized.db.close();
+  discardResumeSnapshot(resumeSnapshot);
   const result = {
     created_path: ultraDir,
     state_db_path: stateDbPath,
@@ -552,13 +662,17 @@ function resumeProject({
       id: baselineResult.id,
       mode: baselineResult.mode,
       status: baselineResult.status,
+      project_name: baselineResult.project_name,
       project_type: baselineResult.project_type,
       stack: baselineResult.stack,
       repository_revision: baselineResult.repository_revision,
+      repository_branch: baselineResult.repository_branch,
+      worktree_state: baselineResult.worktree_state,
       scope: baselineResult.scope,
     },
     copied_files: copiedFiles,
     repository_profile: repositoryProfile,
+    git: gitSetup.result,
     workflow: workflowResult,
   };
   if (initialized.backup_path) result.migration_backup_path = initialized.backup_path;
@@ -574,6 +688,7 @@ function initProject({
   scope,
   resume = false,
   overwrite = false,
+  git_mode = 'auto',
   source_template,
 } = {}) {
   if (typeof project_name !== 'string' || project_name.length === 0) {
@@ -582,6 +697,12 @@ function initProject({
   if (resume && overwrite) {
     throw new InitProjectError('VALIDATION_ERROR', 'resume and overwrite are mutually exclusive');
   }
+  if (!gitBootstrap.GIT_MODES.has(git_mode)) {
+    throw new InitProjectError(
+      'VALIDATION_ERROR',
+      `git_mode must be one of: ${[...gitBootstrap.GIT_MODES].join(', ')}`,
+    );
+  }
 
   const absTarget = resolveTargetDir(target_dir);
   ensureTargetDir(absTarget);
@@ -611,7 +732,7 @@ function initProject({
     return resumeProject({
       absTarget, ultraDir, source, project_name, project_type: resolvedProjectType,
       stack: resolvedStack, resolvedMode,
-      scope, repositoryProfile, projection,
+      scope, repositoryProfile, projection, git_mode,
     });
   }
 
@@ -630,10 +751,13 @@ function initProject({
   let copiedFiles;
   let baselineResult;
   let workflowResult;
+  let gitSetup;
   try {
     fs.mkdirSync(ultraDir, { recursive: true });
     copiedFiles = copyTemplate(source, ultraDir);
     validateTasksTemplate(ultraDir);
+    gitSetup = gitBootstrap.bootstrapGit(absTarget, { mode: git_mode });
+    repositoryProfile.git = gitSetup.result;
     const stateDbPath = path.join(ultraDir, 'state.db');
     const { db } = initStateDb(stateDbPath);
     try {
@@ -649,6 +773,7 @@ function initProject({
         type: 'project_initialized',
         payload: {
           project_name, mode: resolvedMode, baseline_id: baselineResult.id,
+          git: gitSetup.result,
         },
       });
       const job = runtimeState.enqueueProjection(db, { tool_name: 'task.init_project' });
@@ -662,9 +787,17 @@ function initProject({
     }
   } catch (err) {
     const rollbackErrors = rollbackInitialization(ultraDir, backupPath);
+    rollbackErrors.push(...gitBootstrap.rollbackGitBootstrap(absTarget, gitSetup?.internal));
     const rollbackNote = rollbackErrors.length > 0
       ? `; rollback incomplete: ${rollbackErrors.join('; ')}`
       : '; prior state restored';
+    if (err instanceof gitBootstrap.GitBootstrapError) {
+      throw new InitProjectError(
+        err.code,
+        `project initialization failed: ${err.message}${rollbackNote}`,
+        { cause: err },
+      );
+    }
     throw new InitProjectError(
       'IO_ERROR',
       `project initialization failed: ${err.message}${rollbackNote}`,
@@ -682,13 +815,17 @@ function initProject({
       id: baselineResult.id,
       mode: baselineResult.mode,
       status: baselineResult.status,
+      project_name: baselineResult.project_name,
       project_type: baselineResult.project_type,
       stack: baselineResult.stack,
       repository_revision: baselineResult.repository_revision,
+      repository_branch: baselineResult.repository_branch,
+      worktree_state: baselineResult.worktree_state,
       scope: baselineResult.scope,
     },
     copied_files: copiedFiles,
     repository_profile: repositoryProfile,
+    git: gitSetup.result,
     workflow: workflowResult,
   };
   if (backupPath) result.backup_path = backupPath;

package/mcp-server/lib/project-breadcrumb.cjs

@@ -9,8 +9,8 @@ const { EXPECTED_VERSION, REQUIRED_TABLES } = require('./state-db.cjs');
 const { readBreadcrumb } = require('./context-spine.cjs');
 
 function blockedBreadcrumb(code, {
-  nextAction,
-  workflow,
+  allowedTransitions = [],
+  requiredTransition = null,
 } = {}) {
   return {
     change_id: null,
@@ -20,8 +20,8 @@ function blockedBreadcrumb(code, {
     readiness: 'blocked',
     blockers: [code],
     warnings: [],
-    next_action: nextAction,
-    recommended_workflow: workflow,
+    allowed_transitions: allowedTransitions,
+    required_transition: requiredTransition,
     context_manifest_path: null,
     context_manifest_hash: null,
     git_head: null,
@@ -31,15 +31,15 @@ function blockedBreadcrumb(code, {
 
 function migrationBreadcrumb(code) {
   return blockedBreadcrumb(code, {
-    nextAction: 'Resume project initialization to migrate and re-establish the Ultra baseline.',
-    workflow: 'ultra-init',
+    allowedTransitions: ['ultra-init', 'ultra-status'],
+    requiredTransition: 'ultra-init',
   });
 }
 
 function doctorBreadcrumb(code) {
   return blockedBreadcrumb(code, {
-    nextAction: 'Run ultra-doctor to inspect and recover the authoritative Ultra state database.',
-    workflow: 'ultra-doctor',
+    allowedTransitions: ['ultra-doctor', 'ultra-status'],
+    requiredTransition: 'ultra-doctor',
   });
 }
 
@@ -62,8 +62,8 @@ function readProjectBreadcrumb(rootDir) {
   const dbPath = path.join(ultraDir, 'state.db');
   if (!fs.existsSync(dbPath)) {
     return blockedBreadcrumb('STATE_DB_MISSING', {
-      nextAction: 'Initialize or resume this Ultra project through ultra-init.',
-      workflow: 'ultra-init',
+      allowedTransitions: ['ultra-init', 'ultra-status'],
+      requiredTransition: 'ultra-init',
     });
   }
 
@@ -135,10 +135,10 @@ function renderProjectBreadcrumb(rootDir, breadcrumb) {
         : 'Decision: checkpoint confirmation required',
     );
   }
-  lines.push(
-    `Next: ${breadcrumb.next_action || 'Inspect Ultra status.'}`,
-    `Route: ${breadcrumb.recommended_workflow || 'ultra-doctor'}`,
-  );
+  lines.push(`Allowed transitions: ${(breadcrumb.allowed_transitions || []).join(', ') || 'none'}`);
+  if (breadcrumb.required_transition) {
+    lines.push(`Required transition: ${breadcrumb.required_transition}`);
+  }
   if (breadcrumb.context_manifest_path) {
     lines.push(
       `Context: ${breadcrumb.context_manifest_path} sha256=${breadcrumb.context_manifest_hash || 'unknown'}`,