ultra-builder-pro-cli 0.16.0 → 0.17.1

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

@@ -52,6 +52,10 @@ function parseJson(value, fallback = {}) {
   try { return JSON.parse(value); } catch { return fallback; }
 }
 
+function uniqueStrings(values) {
+  return [...new Set(values.filter((value) => typeof value === 'string' && value.length > 0))];
+}
+
 function hasIncidentBreakGlass(change) {
   const bypass = change?.baseline_bypass
     || parseJson(change?.baseline_bypass_json, null);
@@ -128,6 +132,22 @@ function taskStateDigest(task) {
   return crypto.createHash('sha256').update(JSON.stringify(payload)).digest('hex');
 }
 
+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');
+}
+
 function nonEmpty(value, field) {
   const text = typeof value === 'string' ? value.trim() : '';
   if (!text) throw new ContextSpineError('VALIDATION_ERROR', `${field} must be a non-empty string`);
@@ -291,27 +311,106 @@ function defaultGate(role) {
   }[role];
 }
 
-function deriveNextAction({ change, tasks, task, role, readiness, blockers = [] }) {
+function deriveTransitions({
+  change,
+  tasks = [],
+  task,
+  role,
+  readiness,
+  blockers = [],
+  activeWorkflow = null,
+  deliveryReady = false,
+}) {
+  const unique = (values) => [...new Set(values.filter(Boolean))];
+  const has = (prefix) => blockers.some((blocker) => blocker === prefix || blocker.startsWith(`${prefix}:`));
+  if (has('STATE_DB_UNREADABLE') || has('STATE_SCHEMA_INCOMPLETE') || has('STATE_AUTHORITY_CONFLICT')) {
+    return {
+      allowed_transitions: ['ultra-doctor', 'ultra-status'],
+      required_transition: 'ultra-doctor',
+    };
+  }
+  if (has('STATE_DB_MISSING') || has('BASELINE_MISSING')) {
+    return {
+      allowed_transitions: ['ultra-init', 'ultra-status'],
+      required_transition: 'ultra-init',
+    };
+  }
+  if (blockers.some((blocker) => blocker.startsWith('DECISION_'))) {
+    return {
+      allowed_transitions: ['ultra-think', 'ultra-status'],
+      required_transition: 'ultra-think',
+    };
+  }
+  if (blockers.some((blocker) => blocker.startsWith('BASELINE_SCHEMA_')
+    || blocker.startsWith('STATE_SCHEMA_MIGRATION_'))) {
+    return {
+      allowed_transitions: ['ultra-doctor', 'ultra-init', 'ultra-status'],
+      required_transition: 'ultra-doctor',
+    };
+  }
+
+  const transitions = [];
+  if (activeWorkflow) transitions.push(`ultra-${activeWorkflow.kind}`);
+  if (!change) {
+    transitions.push('ultra-research', 'ultra-change', 'ultra-think', 'ultra-status', 'ultra-doctor');
+    return { allowed_transitions: unique(transitions), required_transition: null };
+  }
   if (readiness === 'blocked') {
+    if (blockers.some((blocker) => blocker.startsWith('CONTEXT_')
+      || blocker.startsWith('EXECUTION_'))) {
+      transitions.push('change.context');
+    }
     if (blockers.some((blocker) => blocker.startsWith('BASELINE_'))) {
-      return 'Complete or refresh the Ultra project baseline, then recompile change.context.';
+      transitions.push('ultra-research', 'ultra-doctor');
     }
-    return 'Resolve the context readiness blockers, then recompile change.context.';
-  }
-  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.`;
-  if (!task && tasks.length === 0) return `Create the first fresh-context tracer-bullet task for change ${change.id}.`;
-  if (task?.status === 'pending') return `Start task ${task.id} through ultra-dev.`;
-  if (task?.status === 'in_progress') {
-    if (role === 'check') return `Run the exact verification command for task ${task.id}.`;
-    if (role === 'review') return `Complete independent spec-fidelity and engineering-standards review for task ${task.id}.`;
-    return `Continue the approved vertical slice for task ${task.id}.`;
-  }
-  if (tasks.length > 0 && tasks.every((row) => ['completed', 'expanded'].includes(row.status))) {
-    return `Run ultra-test for change ${change.id}.`;
-  }
-  const pending = tasks.find((row) => row.status === 'pending');
-  return pending ? `Compile implement context for task ${pending.id}.` : `Inspect blockers for change ${change.id}.`;
+    transitions.push('ultra-change', 'ultra-think', 'ultra-status');
+    return { allowed_transitions: unique(transitions), required_transition: null };
+  }
+  if (change.status === 'ready') {
+    transitions.push('ultra-deliver', 'ultra-review', 'ultra-test');
+  } else if (change.status === 'blocked') {
+    transitions.push('ultra-think', 'ultra-change');
+  } else if (!task && tasks.length === 0) {
+    transitions.push('ultra-plan', 'ultra-research', 'ultra-change');
+  } else if (task?.status === 'pending' || task?.status === 'in_progress') {
+    transitions.push('ultra-dev', 'ultra-plan');
+    if (role === 'review') transitions.push('ultra-review');
+  } else if (tasks.length > 0 && tasks.every((row) => ['completed', 'expanded'].includes(row.status))) {
+    transitions.push('ultra-test', 'ultra-review');
+    if (deliveryReady) transitions.push('ultra-deliver');
+  } else {
+    transitions.push('ultra-plan', 'ultra-change');
+  }
+  transitions.push('ultra-think', 'ultra-status');
+  return { allowed_transitions: unique(transitions), required_transition: null };
+}
+
+function normalizeRecommendation(value) {
+  if (value === undefined || value === null) return null;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new ContextSpineError('VALIDATION_ERROR', 'recommendation must be an object');
+  }
+  const workflow = String(value.workflow || '').trim();
+  const rationale = String(value.rationale || '').trim();
+  if (!workflow || rationale.length < 3) {
+    throw new ContextSpineError(
+      'VALIDATION_ERROR', 'recommendation requires workflow and rationale',
+    );
+  }
+  return { workflow, rationale, authoritative: false };
+}
+
+function deliveryCapabilityReady(db, change, tasks, rootDir) {
+  if (!change || !Array.isArray(tasks) || tasks.length === 0
+    || !tasks.every((row) => ['completed', 'expanded'].includes(row.status))) {
+    return false;
+  }
+  try {
+    workflows.validateDeliveryPrerequisites(db, { change_id: change.id }, rootDir);
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 function latestContext(db, changeId, taskId) {
@@ -328,8 +427,8 @@ function latestContext(db, changeId, taskId) {
 function compileRoleContext(db, { input, change, tasks, rootDir }) {
   if (input.next_action !== undefined) {
     throw new ContextSpineError(
-      'CONTEXT_NEXT_ACTION_AUTHORITY_VIOLATION',
-      'next_action is derived from authoritative workflow and task state',
+      'CONTEXT_LEGACY_NEXT_ACTION_UNSUPPORTED',
+      'next_action is not an authority field; provide a non-authoritative recommendation instead',
     );
   }
   const task = input.task_id ? tasks.find((row) => row.id === input.task_id) : null;
@@ -376,13 +475,20 @@ function compileRoleContext(db, { input, change, tasks, rootDir }) {
     }
   }
   const readiness = blockers.length === 0 ? 'ready' : 'blocked';
-  const nextAction = deriveNextAction({
-    change, tasks, task, role, readiness, blockers,
+  const control = deriveTransitions({
+    change,
+    tasks,
+    task,
+    role,
+    readiness,
+    blockers,
+    deliveryReady: deliveryCapabilityReady(db, change, tasks, rootDir),
   });
   return {
     role,
     gate,
-    next_action: nextAction,
+    control,
+    recommendation: normalizeRecommendation(input.recommendation),
     readiness: { status: readiness, blockers, warnings: [...new Set(warnings)] },
     context: { items, budget, token_estimate: tokenEstimate, file_count: fileCount },
     execution_contract: executionContract,
@@ -397,6 +503,7 @@ function compileRoleContext(db, { input, change, tasks, rootDir }) {
     selected_task: task,
     resume: {
       change_id: change.id,
+      change_state_digest: changeStateDigest(change),
       task_id: task?.id || null,
       task_status: task?.status || null,
       task_state_digest: taskStateDigest(task),
@@ -410,15 +517,6 @@ function compileRoleContext(db, { input, change, tasks, rootDir }) {
   };
 }
 
-function recommendedWorkflow(change, task, tasks, readiness) {
-  if (!change) return 'ultra-change';
-  if (readiness !== 'ready' || change.status === 'blocked') return 'ultra-change';
-  if (change.status === 'ready') return 'ultra-deliver';
-  if (task && ['pending', 'in_progress'].includes(task.status)) return 'ultra-dev';
-  if (tasks.length > 0 && tasks.every((row) => ['completed', 'expanded'].includes(row.status))) return 'ultra-test';
-  return 'ultra-change';
-}
-
 function actionableBaselineWorkflow(db, baselineId, rootDir) {
   if (!baselineId) return null;
   const candidates = workflows.listWorkflows(db, { baseline_id: baselineId, limit: 100 }, { rootDir })
@@ -443,16 +541,6 @@ function summarizeWorkflow(run) {
   };
 }
 
-function workflowNextAction(run) {
-  if (run.status === 'blocked') {
-    return `Resolve ${run.kind} workflow blockers at ${run.current_step}: ${run.blockers.join(', ')}.`;
-  }
-  if (run.status === 'ready') {
-    return `Finalize ${run.kind} workflow ${run.id} after verifying its recorded evidence and outputs.`;
-  }
-  return `Continue ${run.kind} workflow ${run.id} at ${run.current_step}.`;
-}
-
 function summarizeDecision(gate) {
   if (!gate?.thread) return null;
   const current = gate.current_decision;
@@ -472,19 +560,6 @@ function summarizeDecision(gate) {
   };
 }
 
-function decisionNextAction(gate) {
-  if (gate.blockers?.some((blocker) => blocker.startsWith('DECISION_CHECKPOINT_ARTIFACT_STALE:'))) {
-    return `Reprepare and confirm decision checkpoint ${gate.thread?.id || 'for the active alignment thread'} against the current artifact.`;
-  }
-  if (gate.current_decision) {
-    return `Answer decision ${gate.current_decision.id}: ${gate.current_decision.question}`;
-  }
-  if (gate.thread?.status === 'checkpoint_ready') {
-    return `Confirm decision checkpoint ${gate.thread.id} after reviewing its durable effects.`;
-  }
-  return `Prepare the confirmed decision checkpoint for ${gate.thread?.id || 'the active alignment thread'}.`;
-}
-
 function readBreadcrumb(db, { id } = {}, { rootDir = process.cwd() } = {}) {
   const baselineHealth = baselines.inspectBaseline(db, { rootDir });
   const change = id
@@ -505,7 +580,7 @@ function readBreadcrumb(db, { id } = {}, { rootDir = process.cwd() } = {}) {
         change_id: null, task_id: null, role: 'plan', gate: 'alignment', readiness: 'blocked',
         blockers: [...new Set([...baselineHealth.blockers, ...decisionGate.blockers])],
         warnings: baselineHealth.warnings,
-        next_action: decisionNextAction(decisionGate), recommended_workflow: 'ultra-think',
+        allowed_transitions: ['ultra-think', 'ultra-status'], required_transition: 'ultra-think',
         workflow: null, decision: summarizeDecision(decisionGate),
         context_manifest_path: null, context_manifest_hash: null, git_head: currentHead(rootDir),
         baseline: baseline ? {
@@ -516,15 +591,24 @@ function readBreadcrumb(db, { id } = {}, { rootDir = process.cwd() } = {}) {
     }
     if (baselineHealth.status !== 'pass') {
       const activeWorkflow = actionableBaselineWorkflow(db, baseline?.id, rootDir);
-      const nextAction = activeWorkflow
-        ? workflowNextAction(activeWorkflow)
-        : baseline
-        ? `Complete ${baseline.mode} baseline adoption ${baseline.id} through ultra-init.`
-        : 'Initialize the project and start baseline adoption with ultra-init.';
+      const control = baseline
+        ? {
+          allowed_transitions: uniqueStrings([
+            activeWorkflow ? `ultra-${activeWorkflow.kind}` : 'ultra-research',
+            'ultra-status',
+            'ultra-doctor',
+          ]),
+          required_transition: null,
+        }
+        : {
+          allowed_transitions: ['ultra-init', 'ultra-status'],
+          required_transition: '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: activeWorkflow ? `ultra-${activeWorkflow.kind}` : 'ultra-init',
+        blockers: baselineHealth.blockers, warnings: baselineHealth.warnings,
+        allowed_transitions: control.allowed_transitions,
+        required_transition: control.required_transition,
         workflow: summarizeWorkflow(activeWorkflow), decision: null, context_manifest_path: null,
         context_manifest_hash: null, git_head: currentHead(rootDir),
         baseline: baseline ? {
@@ -535,7 +619,8 @@ function readBreadcrumb(db, { id } = {}, { rootDir = process.cwd() } = {}) {
     }
     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',
+      allowed_transitions: ['ultra-change', 'ultra-research', 'ultra-think', 'ultra-status'],
+      required_transition: null,
       workflow: null,
       decision: null,
       context_manifest_path: null, context_manifest_hash: null, git_head: currentHead(rootDir),
@@ -564,6 +649,7 @@ function readBreadcrumb(db, { id } = {}, { rootDir = process.cwd() } = {}) {
       !context.resume || !context.context || !context.readiness || !('baseline' in context)
       || !Object.prototype.hasOwnProperty.call(context.resume, 'worktree_digest')
       || !Object.prototype.hasOwnProperty.call(context.resume, 'task_state_digest')
+      || !Object.prototype.hasOwnProperty.call(context.resume, 'change_state_digest')
     ),
   );
   const headStale = Boolean(snapshot?.git_head && head && snapshot.git_head !== head);
@@ -576,6 +662,9 @@ function readBreadcrumb(db, { id } = {}, { rootDir = process.cwd() } = {}) {
   const taskContractChanged = Boolean(
     context.resume && context.resume.task_state_digest !== taskStateDigest(task),
   );
+  const changeContractChanged = Boolean(
+    context.resume && context.resume.change_state_digest !== changeStateDigest(change),
+  );
   const blockers = [];
   const baselineGate = baselineGateForChange(db, change, baselineHealth);
   const decisionGate = decisions.decisionGate(db, {
@@ -586,13 +675,15 @@ function readBreadcrumb(db, { id } = {}, { rootDir = process.cwd() } = {}) {
   const warnings = [...baselineGate.warnings];
   blockers.push(...baselineGate.blockers);
   blockers.push(...decisionGate.blockers);
-  if (snapshotMissing) blockers.push('CONTEXT_NOT_COMPILED');
+  if (snapshotMissing && tasks.length > 0) blockers.push('CONTEXT_NOT_COMPILED');
+  else if (snapshotMissing) warnings.push('CONTEXT_NOT_COMPILED');
   else {
     if (legacyContext) blockers.push('CONTEXT_SNAPSHOT_UPGRADE_REQUIRED');
     if (headStale) blockers.push('CONTEXT_HEAD_STALE');
     if (worktreeStale) blockers.push('CONTEXT_WORKTREE_STALE');
     if (stateChanged) blockers.push('CONTEXT_TASK_STATE_STALE');
     if (taskContractChanged) blockers.push('CONTEXT_TASK_CONTRACT_STALE');
+    if (changeContractChanged) blockers.push('CONTEXT_CHANGE_CONTRACT_STALE');
     for (const blocker of parseJson(snapshot.blockers_json, [])) {
       if (ADVISORY_CONTEXT_CODES.has(blocker)
         || (blocker.startsWith('BASELINE_') && baselineGate.blockers.length === 0)) {
@@ -603,38 +694,18 @@ function readBreadcrumb(db, { id } = {}, { rootDir = process.cwd() } = {}) {
       if (!warnings.includes(warning)) warnings.push(warning);
     }
   }
-  const readiness = blockers.length > 0 ? 'blocked' : snapshot.readiness;
+  const readiness = blockers.length > 0 ? 'blocked' : (snapshot?.readiness || 'ready');
   const activeWorkflow = actionableChangeWorkflow(db, change.id, rootDir);
-  let nextAction;
-  if (baselineGate.blockers.length > 0) {
-    nextAction = deriveNextAction({
-      change, tasks, task, role: snapshot?.role || 'plan', readiness: 'blocked',
-      blockers: baselineGate.blockers,
-    });
-  } else if (!decisionGate.ready) {
-    nextAction = decisionNextAction(decisionGate);
-  } else if (activeWorkflow?.status === 'blocked') {
-    nextAction = workflowNextAction(activeWorkflow);
-  } else if (snapshotMissing) {
-    nextAction = `Compile change.context for change ${change.id} before continuing.`;
-  } else if (legacyContext) {
-    nextAction = 'Recompile change.context to upgrade this legacy context snapshot.';
-  } else if (headStale) {
-    nextAction = 'Git HEAD changed after context compilation; recompile change.context.';
-  } else if (worktreeStale) {
-    nextAction = 'The worktree changed after context compilation; recompile change.context.';
-  } else if (stateChanged) {
-    nextAction = 'Task state changed after context compilation; recompile change.context.';
-  } else if (taskContractChanged) {
-    nextAction = 'The task execution contract changed after context compilation; recompile change.context.';
-  } else if (activeWorkflow) {
-    nextAction = workflowNextAction(activeWorkflow);
-  } else {
-    nextAction = deriveNextAction({
-      change, tasks, task, role: snapshot?.role || 'plan', readiness,
-      blockers,
-    });
-  }
+  const control = deriveTransitions({
+    change,
+    tasks,
+    task,
+    role: snapshot?.role || 'plan',
+    readiness,
+    blockers,
+    activeWorkflow,
+    deliveryReady: deliveryCapabilityReady(db, change, tasks, rootDir),
+  });
   return {
     change_id: change.id,
     change_status: change.status,
@@ -646,14 +717,8 @@ function readBreadcrumb(db, { id } = {}, { rootDir = process.cwd() } = {}) {
     readiness,
     blockers,
     warnings: [...new Set(warnings)],
-    next_action: nextAction,
-    recommended_workflow: baselineGate.blockers.length > 0
-      ? (baselineHealth.baseline?.status === 'ready' ? 'ultra-doctor' : 'ultra-init')
-      : !decisionGate.ready
-        ? 'ultra-think'
-        : activeWorkflow
-        ? `ultra-${activeWorkflow.kind}`
-        : recommendedWorkflow(change, task, tasks, readiness),
+    allowed_transitions: control.allowed_transitions,
+    required_transition: control.required_transition,
     context_manifest_path: snapshot?.manifest_path || null,
     context_manifest_hash: snapshot?.manifest_hash || null,
     git_head: head,
@@ -670,7 +735,8 @@ function readBreadcrumb(db, { id } = {}, { rootDir = process.cwd() } = {}) {
 module.exports = {
   ContextSpineError,
   baselineGateForChange,
+  changeStateDigest,
   compileRoleContext,
-  deriveNextAction,
+  deriveTransitions,
   readBreadcrumb,
 };

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