ultra-builder-pro-cli 0.21.1 → 0.23.0

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

@@ -59,6 +59,49 @@ function gitBranch(rootDir) {
   return result.status === 0 ? (result.stdout.trim() || null) : null;
 }
 
+function gitCommitIsAncestor(rootDir, ancestor, descendant) {
+  if (!ancestor || !descendant) return false;
+  const result = spawnSync(
+    'git', ['merge-base', '--is-ancestor', ancestor, descendant],
+    { cwd: rootDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+  );
+  return result.status === 0;
+}
+
+function hashScopedWorkingTree(rootDir, relativePaths) {
+  const root = path.resolve(rootDir);
+  const digest = crypto.createHash('sha256');
+  for (const relative of [...new Set(relativePaths)].sort()) {
+    const file = path.resolve(root, relative);
+    if (file !== root && !file.startsWith(`${root}${path.sep}`)) {
+      throw new BaselineWorkflowError(
+        'BASELINE_SCOPE_INVALID',
+        `Git returned a path outside the repository: ${relative}`,
+      );
+    }
+    digest.update(relative).update('\0');
+    const stat = fs.lstatSync(file, { throwIfNoEntry: false });
+    if (!stat) {
+      digest.update('missing\0');
+    } else if (stat.isSymbolicLink()) {
+      digest.update('symlink\0').update(fs.readlinkSync(file)).update('\0');
+    } else if (stat.isFile()) {
+      digest.update(stat.mode & 0o111 ? 'file+x\0' : 'file\0');
+      digest.update(fs.readFileSync(file)).update('\0');
+    } else if (stat.isDirectory()) {
+      const submoduleHead = spawnSync('git', ['-C', file, 'rev-parse', 'HEAD'], {
+        cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      digest.update('directory\0');
+      if (submoduleHead.status === 0) digest.update(submoduleHead.stdout.trim());
+      digest.update('\0');
+    } else {
+      digest.update(`special:${stat.mode}\0`);
+    }
+  }
+  return digest.digest('hex');
+}
+
 function gitWorktreeSnapshot(rootDir, scope = ['.']) {
   const repositoryRoot = gitRepositoryRoot(rootDir);
   if (!repositoryRoot) {
@@ -76,40 +119,24 @@ function gitWorktreeSnapshot(rootDir, scope = ['.']) {
     'git', ['status', '--porcelain=v1', '-z', '--untracked-files=all', ...args],
     { cwd: rootDir, encoding: 'buffer', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 32 * 1024 * 1024 },
   );
-  const diff = head
-    ? spawnSync(
-      'git', ['diff', '--binary', '--no-ext-diff', 'HEAD', ...args],
-      { cwd: rootDir, encoding: 'buffer', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 32 * 1024 * 1024 },
-    )
-    : { status: 0, stdout: Buffer.alloc(0) };
-  const untracked = spawnSync(
-    'git', ['ls-files', '--others', '--exclude-standard', '-z', ...args],
+  const inventory = spawnSync(
+    'git', ['ls-files', '--cached', '--others', '--exclude-standard', '-z',
+      '--', ...pathspecs, ':(exclude).ultra', ':(exclude).ultra/**'],
     { cwd: rootDir, encoding: 'buffer', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 32 * 1024 * 1024 },
   );
-  if (status.status !== 0 || diff.status !== 0 || untracked.status !== 0) {
+  if (status.status !== 0 || inventory.status !== 0) {
     return {
       head, branch: gitBranch(rootDir), state: 'unavailable', digest: null, files: [],
     };
   }
   const statusText = status.stdout.toString('utf8');
   const files = statusText.split('\0').filter(Boolean);
-  const digest = crypto.createHash('sha256');
-  digest.update(head || 'unborn').update('\0').update(gitBranch(rootDir) || '').update('\0');
-  digest.update(status.stdout).update(diff.stdout);
-  for (const relative of untracked.stdout.toString('utf8').split('\0').filter(Boolean).sort()) {
-    digest.update(relative).update('\0');
-    const file = path.resolve(rootDir, relative);
-    if (file.startsWith(`${path.resolve(rootDir)}${path.sep}`)
-      && fs.existsSync(file) && fs.statSync(file).isFile()) {
-      digest.update(fs.readFileSync(file));
-    }
-    digest.update('\0');
-  }
+  const scopedFiles = inventory.stdout.toString('utf8').split('\0').filter(Boolean);
   return {
     head,
     branch: gitBranch(rootDir),
     state: head ? (files.length > 0 ? 'dirty' : 'clean') : 'unborn',
-    digest: digest.digest('hex'),
+    digest: hashScopedWorkingTree(rootDir, scopedFiles),
     files,
   };
 }
@@ -741,7 +768,12 @@ function convergenceBlockers(db, baseline, input, rootDir) {
   else if (baseline.repository_revision !== expected) blockers.add('BASELINE_REVISION_MISMATCH');
   const snapshot = gitWorktreeSnapshot(rootDir, baseline.scope);
   if (snapshot.state === 'unborn') blockers.add('BASELINE_GIT_HEAD_REQUIRED');
-  if (snapshot.head && expected && snapshot.head !== expected) blockers.add('BASELINE_HEAD_STALE');
+  if (snapshot.head && expected && snapshot.head !== expected
+      && (!gitCommitIsAncestor(rootDir, expected, snapshot.head)
+        || (baseline.worktree_digest && snapshot.digest
+          && baseline.worktree_digest !== snapshot.digest))) {
+    blockers.add('BASELINE_HEAD_STALE');
+  }
   if (baseline.repository_branch && snapshot.branch
     && baseline.repository_branch !== snapshot.branch) blockers.add('BASELINE_BRANCH_STALE');
   if (!Array.isArray(baseline.scope) || baseline.scope.length === 0) blockers.add('BASELINE_SCOPE_MISSING');
@@ -857,7 +889,11 @@ function inspectBaseline(db, { rootDir = process.cwd(), id } = {}) {
     blockers.push('BASELINE_GIT_HEAD_REQUIRED');
   }
   if (snapshot.head && baseline.repository_revision && snapshot.head !== baseline.repository_revision) {
-    blockers.push('BASELINE_HEAD_STALE');
+    if (!gitCommitIsAncestor(rootDir, baseline.repository_revision, snapshot.head)
+        || (baseline.worktree_digest && snapshot.digest
+          && baseline.worktree_digest !== snapshot.digest)) {
+      blockers.push('BASELINE_HEAD_STALE');
+    }
   } else if (!snapshot.head && baseline.repository_revision?.startsWith('workspace:')) {
     const revision = workspaceRevision({
       scope: baseline.scope, specs: baseline.spec_refs, evidence: baseline.evidence,

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

@@ -39,7 +39,7 @@ const SEMANTIC_AUTHORITY_FIELDS = new Set([
 const CHANGE_TRANSITIONS = Object.freeze({
   active: new Set(['active', 'blocked', 'cancelled']),
   blocked: new Set(['active', 'blocked', 'cancelled']),
-  ready: new Set(['ready']),
+  ready: new Set(['active', 'ready', 'cancelled']),
   archived: new Set(),
   cancelled: new Set(),
 });
@@ -702,11 +702,8 @@ function compileContext(db, input, { rootDir = process.cwd() } = {}) {
   const recommendation = spine.recommendation;
   const durableSpine = { ...spine };
   delete durableSpine.recommendation;
-  const snapshotId = `ctx-${crypto.randomUUID().slice(0, 12)}`;
-  const manifest = {
+  const semanticManifest = {
     schema_version: '3.0',
-    snapshot_id: snapshotId,
-    generated_at: nowIso(),
     change: {
       id: change.id, title: change.title, kind: change.kind, status: change.status,
       intent: change.intent, docs_impact: change.docs_impact, base_commit: change.base_commit,
@@ -734,6 +731,43 @@ function compileContext(db, input, { rootDir = process.cwd() } = {}) {
     providers,
     provider_boundary: 'metadata references only; memory and code graph content remain external',
   };
+  const identityHash = crypto.createHash('sha256')
+    .update(JSON.stringify(semanticManifest))
+    .digest('hex');
+  const snapshotId = `ctx-${identityHash.slice(0, 12)}`;
+  const existing = db.prepare(
+    `SELECT manifest_path, manifest_hash
+     FROM context_snapshots WHERE id = ?`,
+  ).get(snapshotId);
+  if (existing) {
+    const existingPath = path.resolve(rootDir, existing.manifest_path);
+    if (!fs.existsSync(existingPath)) {
+      throw new ChangeWorkflowError(
+        'CONTEXT_SNAPSHOT_CORRUPT',
+        `content-addressed Context snapshot is missing: ${existing.manifest_path}`,
+      );
+    }
+    const bytes = fs.readFileSync(existingPath);
+    const existingHash = crypto.createHash('sha256').update(bytes).digest('hex');
+    if (existingHash !== existing.manifest_hash) {
+      throw new ChangeWorkflowError(
+        'CONTEXT_SNAPSHOT_CORRUPT',
+        `content-addressed Context snapshot digest changed: ${existing.manifest_path}`,
+      );
+    }
+    return {
+      manifest: JSON.parse(bytes.toString('utf8')),
+      recommendation,
+      context_manifest_path: existingPath,
+      manifest_hash: existingHash,
+    };
+  }
+  const manifest = {
+    schema_version: semanticManifest.schema_version,
+    snapshot_id: snapshotId,
+    generated_at: nowIso(),
+    ...Object.fromEntries(Object.entries(semanticManifest).filter(([key]) => key !== 'schema_version')),
+  };
   const artifactDir = path.resolve(rootDir, change.artifact_root);
   fs.mkdirSync(artifactDir, { recursive: true });
   const manifestPath = path.join(artifactDir, 'contexts', `${snapshotId}.json`);
@@ -1005,7 +1039,7 @@ function assertTaskCreationAllowed(db, input = {}, { rootDir = process.cwd() } =
 function updateChange(db, id, patch = {}, { rootDir = process.cwd() } = {}) {
   const current = readChange(db, id);
   if (!current) throw new ChangeWorkflowError('CHANGE_NOT_FOUND', `change ${id} not found`);
-  if (['ready', 'archived', 'cancelled'].includes(current.status)) {
+  if (['archived', 'cancelled'].includes(current.status)) {
     throw new ChangeWorkflowError('CHANGE_NOT_MUTABLE', `change ${id} is ${current.status}`);
   }
   for (const field of Object.keys(patch)) {
@@ -1059,6 +1093,8 @@ function updateChange(db, id, patch = {}, { rootDir = process.cwd() } = {}) {
           );
         }
         sets.push('status = ?'); values.push(patch.status);
+      } else if (current.status === 'ready' && Object.keys(patch).length > 0) {
+        sets.push('status = ?'); values.push('active');
       }
       if (sets.length === 0) return current;
       sets.push('updated_at = ?'); values.push(nowIso(), id);

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

@@ -3,7 +3,8 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-const CONTEXT_ROOT_RELATIVE = '.ultra/tasks/contexts';
+const CONTEXT_ROOT_RELATIVE = '.ultra/.runtime/projections/contexts';
+const LEGACY_CONTEXT_ROOT_RELATIVE = '.ultra/tasks/contexts';
 const GENERATED_BY = 'ultra-projector';
 
 class ContextPathError extends Error {
@@ -77,9 +78,12 @@ function resolveContextPath(rootDir, value, {
   if (raw.split('/').includes('..')) invalid(original, 'parent traversal is not allowed');
 
   if (allowLegacyAliases && raw.startsWith('contexts/')) {
-    raw = `.ultra/tasks/${raw}`;
+    raw = `${LEGACY_CONTEXT_ROOT_RELATIVE}/${raw.slice('contexts/'.length)}`;
   } else if (allowLegacyAliases && !raw.includes('/')) {
-    raw = `${CONTEXT_ROOT_RELATIVE}/${raw}`;
+    raw = `${LEGACY_CONTEXT_ROOT_RELATIVE}/${raw}`;
+  }
+  if (raw.startsWith(`${LEGACY_CONTEXT_ROOT_RELATIVE}/`)) {
+    raw = `${CONTEXT_ROOT_RELATIVE}/${raw.slice(LEGACY_CONTEXT_ROOT_RELATIVE.length + 1)}`;
   }
 
   const relative = path.posix.normalize(raw);
@@ -98,14 +102,41 @@ function resolveContextPath(rootDir, value, {
   return { root, contextRoot, relative, file };
 }
 
+function resolveLegacyContextPath(rootDir, value, { taskId } = {}) {
+  const root = path.resolve(rootDir || '.');
+  const original = value || `${LEGACY_CONTEXT_ROOT_RELATIVE}/task-${taskId}.md`;
+  if (typeof original !== 'string' || original.trim() === '' || original.includes('\0')) {
+    invalid(original, 'a non-empty legacy path is required');
+  }
+  if (path.isAbsolute(original)) invalid(original, 'legacy paths must be project-relative');
+  const raw = original.trim().replaceAll('\\', '/').replace(/^\.\//, '');
+  if (raw.split('/').includes('..')) invalid(original, 'parent traversal is not allowed');
+  const relative = path.posix.normalize(raw);
+  if (!relative.startsWith(`${LEGACY_CONTEXT_ROOT_RELATIVE}/`)
+      || relative === `${LEGACY_CONTEXT_ROOT_RELATIVE}/`
+      || relative.endsWith('/')) {
+    invalid(original, `legacy path must be a file below ${LEGACY_CONTEXT_ROOT_RELATIVE}`);
+  }
+  const file = path.resolve(root, ...relative.split('/'));
+  const contextRoot = path.resolve(root, ...LEGACY_CONTEXT_ROOT_RELATIVE.split('/'));
+  if (!file.startsWith(`${contextRoot}${path.sep}`)) {
+    invalid(original, `legacy path escapes ${LEGACY_CONTEXT_ROOT_RELATIVE}`);
+  }
+  assertNoSymlinkAncestors(root, relative, original);
+  assertRealContainment(root, file, original);
+  return { root, contextRoot, relative, file };
+}
+
 function isGeneratedContextContents(contents) {
   return new RegExp(`^generated_by:\\s*${GENERATED_BY}\\s*$`, 'm').test(String(contents));
 }
 
 module.exports = {
   CONTEXT_ROOT_RELATIVE,
+  LEGACY_CONTEXT_ROOT_RELATIVE,
   GENERATED_BY,
   ContextPathError,
   isGeneratedContextContents,
   resolveContextPath,
+  resolveLegacyContextPath,
 };

package/mcp-server/lib/doctor.cjs

@@ -18,6 +18,7 @@ const decisions = require('./decision-dialogue.cjs');
 const runtimePaths = require('./runtime-paths.cjs');
 const artifactRegistry = require('./artifact-registry.cjs');
 const planStore = require('./plan-store.cjs');
+const taskLedger = require('./task-ledger.cjs');
 const closeJournal = require('../../orchestrator/session-close-journal.cjs');
 
 const SPEC_CONSUMER = 'spec-staleness';
@@ -84,6 +85,28 @@ function inspectSessionCloses(db, {
   };
 }
 
+function inspectTeamTaskLedger(db, rootDir) {
+  try {
+    const health = taskLedger.inspectTaskLedger(db, { rootDir });
+    const taskCount = db.prepare('SELECT COUNT(*) AS count FROM tasks').get().count;
+    let status = 'warning';
+    if (health.status === 'current') status = 'pass';
+    return {
+      ...health,
+      condition: health.status,
+      status,
+      task_count: taskCount,
+    };
+  } catch (error) {
+    return {
+      status: 'fail',
+      condition: 'invalid',
+      code: error.code || 'TASK_LEDGER_INVALID',
+      message: error.message,
+    };
+  }
+}
+
 function inspectSystem(db, { rootDir = process.cwd() } = {}) {
   const tables = new Set(tableNames(db));
   const missing = REQUIRED_TABLES.filter((name) => !tables.has(name));
@@ -137,6 +160,9 @@ function inspectSystem(db, { rootDir = process.cwd() } = {}) {
   const planPublications = missing.length === 0
     ? planStore.inspectPlanPublications(db, { rootDir })
     : { status: 'fail', pending: 0, transactions: [], issues: [] };
+  const taskLedgerHealth = missing.length === 0
+    ? inspectTeamTaskLedger(db, rootDir)
+    : { status: 'fail', condition: 'state_unavailable', code: 'STATE_DB_UNAVAILABLE' };
   const baselineCheckStatus = baseline.status === 'pass'
     ? 'pass'
     : (baseline.baseline?.status === 'ready' ? 'fail' : 'warning');
@@ -148,6 +174,7 @@ function inspectSystem(db, { rootDir = process.cwd() } = {}) {
     || decisionHealth.status === 'fail'
     || artifactHealth.status === 'fail'
     || planPublications.status === 'fail'
+    || taskLedgerHealth.status === 'fail'
     || baselineCheckStatus === 'fail';
   return {
     status: degraded ? 'degraded' : 'healthy',
@@ -167,6 +194,7 @@ function inspectSystem(db, { rootDir = process.cwd() } = {}) {
       },
       change_artifacts: { status: activeMissing === 0 ? 'pass' : 'fail', missing: activeMissing },
       artifacts: artifactHealth,
+      task_ledger: taskLedgerHealth,
       plan_publications: planPublications,
       archive_recovery: {
         status: archiveIntents.length === 0 ? 'pass' : 'fail',

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

@@ -62,7 +62,6 @@ const ULTRA_GIT_ARTIFACT_CLASSES = Object.freeze({
       '.ultra/tasks/tasks.json',
       '.ultra/tasks/plan.md',
       '.ultra/tasks/plan.json',
-      '.ultra/tasks/contexts/example.md',
     ]),
     research: Object.freeze([
       '.ultra/docs/research/README.md',

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

@@ -17,6 +17,7 @@ const Database = require('better-sqlite3');
 
 const { EXPECTED_VERSION, initStateDb } = require('./state-db.cjs');
 const { assertStateAuthority, inspectProjection } = require('./state-authority.cjs');
+const taskLedger = require('./task-ledger.cjs');
 const baselines = require('./baseline-workflow.cjs');
 const gitBootstrap = require('./git-bootstrap.cjs');
 const runtimePaths = require('./runtime-paths.cjs');
@@ -417,6 +418,8 @@ function createResumeSnapshot(ultraDir, stateDbPath) {
   const projectionTargets = [
     path.join('tasks', 'tasks.json'),
     path.join('tasks', 'contexts'),
+    path.join('.runtime', 'projections'),
+    path.join('.runtime', 'backups', 'task-ledger'),
   ];
   let db;
   try {
@@ -621,6 +624,7 @@ function resumeProject({
   let copiedFiles = [];
   let baselineResult;
   let workflowResult;
+  let teamCheckpoint;
   let resumeSnapshot;
   const completeResume = () => {
     try {
@@ -631,7 +635,11 @@ function resumeProject({
       }
       initialized = initStateDb(stateDbPath);
       const { db } = initialized;
-      if (projection && projection.taskCount > 0) assertStateAuthority(db, absTarget);
+      if (projection && (
+        projection.taskCount > 0 || projection.kind === taskLedger.LEDGER_KIND
+      )) {
+        teamCheckpoint = assertStateAuthority(db, absTarget, { importTeamLedger: true });
+      }
       copiedFiles = copyMissingTemplate(source, ultraDir);
       validateTasksTemplate(ultraDir);
       repositoryProfile.git = gitSetup.result;
@@ -653,6 +661,26 @@ function resumeProject({
         }, { rootDir: absTarget });
       }
       workflowResult = ensureInitializationWorkflows(db, baselineResult, { rootDir: absTarget });
+      if (projection?.kind === 'legacy-task-projection') {
+        const publication = taskLedger.publishTaskLedger(db, {
+          rootDir: absTarget,
+          reason: 'legacy_projection_upgraded',
+        });
+        teamCheckpoint = {
+          generation: publication.ledger.generation,
+          state_digest: publication.ledger.state_digest,
+          imported: 0,
+          deleted: 0,
+          imported_changes: 0,
+          imported_baseline: false,
+          requires_plan_revalidation: false,
+          requires_baseline_revalidation: false,
+          already_current: true,
+          published: publication.changed,
+          migrated_legacy_projection: Boolean(publication.migrated_legacy_projection),
+          legacy_backup_path: publication.legacy_backup_path || null,
+        };
+      }
       ops.appendEvent(db, {
         type: 'project_resumed',
         payload: {
@@ -687,7 +715,12 @@ function resumeProject({
         }
       }
       const rollbackErrors = [...stateRollbackErrors, ...gitRollbackErrors];
-      if (error.code && ['LEGACY_STATE_MIGRATION_REQUIRED', 'STATE_AUTHORITY_CONFLICT', 'STATE_PROJECTION_INVALID'].includes(error.code)) {
+      if (error instanceof taskLedger.TaskLedgerError
+          || (error.code && [
+            'LEGACY_STATE_MIGRATION_REQUIRED',
+            'STATE_AUTHORITY_CONFLICT',
+            'STATE_PROJECTION_INVALID',
+          ].includes(error.code))) {
         throw new InitProjectError(
           error.code,
           error.message,
@@ -751,6 +784,22 @@ function resumeProject({
     git: gitSetup.result,
     workflow: workflowResult,
   };
+  if (teamCheckpoint) {
+    result.team_checkpoint = {
+      generation: teamCheckpoint.generation,
+      state_digest: teamCheckpoint.state_digest,
+      imported_tasks: teamCheckpoint.imported,
+      deleted_tasks: teamCheckpoint.deleted,
+      imported_changes: teamCheckpoint.imported_changes,
+      imported_baseline: teamCheckpoint.imported_baseline,
+      requires_plan_revalidation: teamCheckpoint.requires_plan_revalidation,
+      requires_baseline_revalidation: teamCheckpoint.requires_baseline_revalidation,
+      already_current: teamCheckpoint.already_current,
+      published: Boolean(teamCheckpoint.published),
+      migrated_legacy_projection: Boolean(teamCheckpoint.migrated_legacy_projection),
+      legacy_backup_path: teamCheckpoint.legacy_backup_path || undefined,
+    };
+  }
   if (initialized.backup_path) result.migration_backup_path = initialized.backup_path;
   if (runtimeLayout.backupPath) {
     result.runtime_migration_backup_path = runtimeLayout.backupPath;
@@ -815,6 +864,7 @@ function initProject({
       );
     }
     if (projection && projection.taskCount > 0
+      && projection.kind !== taskLedger.LEDGER_KIND
       && !fs.existsSync(locatedStatePath)) {
       throw projectionMigrationError(projection);
     }

package/mcp-server/lib/projector.cjs

@@ -3,8 +3,8 @@
 // Projector: regenerates the read-only file views from .ultra/.runtime/state.db.
 //
 // state.db owns lifecycle and artifact bindings (D32); registered digest-bound
-// files own semantic/evidence bodies. tasks.json and contexts/task-*.md are
-// complete projections — humans may read them, never write them. The projector
+// files own semantic/evidence bodies. Live tasks.json and contexts/task-*.md are
+// checkout-local projections — humans may read them, never write them. The projector
 // is trigger-based: state-ops calls projectAll() after each successful
 // write transaction. Projection output passes the v4.5 schemas under
 // spec/schemas/ — see mcp-server/tests/projector.test.cjs for the
@@ -57,8 +57,8 @@ function rowToProjection(row) {
 
 function defaultPaths(rootDir) {
   return {
-    tasksJson: path.join(rootDir, '.ultra', 'tasks', 'tasks.json'),
-    contextsDir: path.join(rootDir, '.ultra', 'tasks', 'contexts'),
+    tasksJson: path.join(rootDir, '.ultra', '.runtime', 'projections', 'tasks.json'),
+    contextsDir: path.join(rootDir, '.ultra', '.runtime', 'projections', 'contexts'),
   };
 }
 
@@ -266,7 +266,27 @@ function projectContext(db, taskId, { contextsDir } = {}, opts = {}) {
     }
   }
   const target = contextPaths.resolveContextPath(rootDir, projection.context_file, { taskId });
-  const promoted = promoteAuthoredContext(db, taskId, target, rootDir);
+  const legacyValue = String(projection.context_file || '')
+    .replaceAll('\\', '/')
+    .replace(/^\.\//, '');
+  const legacyDefault = `${contextPaths.LEGACY_CONTEXT_ROOT_RELATIVE}/${
+    path.posix.basename(target.relative)
+  }`;
+  const legacyTarget = contextPaths.resolveLegacyContextPath(
+    rootDir,
+    legacyValue.startsWith(`${contextPaths.LEGACY_CONTEXT_ROOT_RELATIVE}/`)
+      ? legacyValue
+      : legacyDefault,
+    { taskId },
+  );
+  const legacyPromoted = promoteAuthoredContext(db, taskId, legacyTarget, rootDir);
+  if (fs.existsSync(legacyTarget.file)
+      && contextPaths.isGeneratedContextContents(fs.readFileSync(legacyTarget.file, 'utf8'))) {
+    fs.rmSync(legacyTarget.file, { force: true });
+  } else if (legacyPromoted) {
+    fs.rmSync(legacyTarget.file, { force: true });
+  }
+  const promoted = promoteAuthoredContext(db, taskId, target, rootDir) || legacyPromoted;
   const next = buildContextDoc(projection);
   writeAtomic(target.file, next);
   return { path: target.file, task_id: taskId, promoted };
@@ -284,8 +304,7 @@ function listContextFiles(directory) {
   return output;
 }
 
-function pruneGeneratedGhosts(db, rootDir, expected) {
-  const contextsDir = defaultPaths(rootDir).contextsDir;
+function pruneGeneratedGhostsIn(db, rootDir, contextsDir, expected) {
   const pruned = [];
   for (const file of listContextFiles(contextsDir)) {
     const relative = path.relative(rootDir, file).split(path.sep).join('/');
@@ -306,7 +325,23 @@ function pruneGeneratedGhosts(db, rootDir, expected) {
       throw error;
     }
   }
-  return pruned.sort();
+  return pruned;
+}
+
+function pruneGeneratedGhosts(db, rootDir, expected) {
+  const runtime = pruneGeneratedGhostsIn(
+    db,
+    rootDir,
+    defaultPaths(rootDir).contextsDir,
+    expected,
+  );
+  const legacy = pruneGeneratedGhostsIn(
+    db,
+    rootDir,
+    path.join(rootDir, ...contextPaths.LEGACY_CONTEXT_ROOT_RELATIVE.split('/')),
+    new Set(),
+  );
+  return [...runtime, ...legacy].sort();
 }
 
 function projectAll(db, { rootDir = '.', tasksJson, contextsDir } = {}) {

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

@@ -2,6 +2,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const taskLedger = require('./task-ledger.cjs');
 
 class StateAuthorityError extends Error {
   constructor(code, message, details) {
@@ -32,24 +33,39 @@ function inspectProjection(rootDir) {
       { projection_path: projectionPath },
     );
   }
+  if (projection.kind === taskLedger.LEDGER_KIND) {
+    const ledger = taskLedger.validateLedger(projection, projectionPath);
+    return {
+      path: projectionPath,
+      version: ledger.schema_version,
+      kind: ledger.kind,
+      taskCount: ledger.tasks.length,
+    };
+  }
   return {
     path: projectionPath,
     version: String(projection.version || projection.schema_version || 'unknown'),
+    kind: 'legacy-task-projection',
     taskCount: projection.tasks.length,
   };
 }
 
-function assertStateAuthority(db, rootDir) {
+function assertStateAuthority(db, rootDir, { importTeamLedger = false } = {}) {
   const authoritativeCount = db.prepare('SELECT COUNT(*) AS count FROM tasks').get().count;
-  if (authoritativeCount > 0) return;
   const projection = inspectProjection(rootDir);
-  if (!projection || projection.taskCount === 0) return;
+  if (projection?.kind === taskLedger.LEDGER_KIND) {
+    return importTeamLedger
+      ? taskLedger.syncTaskLedger(db, { rootDir })
+      : taskLedger.inspectTaskLedger(db, { rootDir });
+  }
+  if (authoritativeCount > 0 || !projection || projection.taskCount === 0) return null;
 
   const details = {
     authoritative_task_count: authoritativeCount,
     legacy_task_count: projection.taskCount,
     projection_path: projection.path,
     projection_version: projection.version,
+    projection_kind: projection.kind,
   };
   const migrationTargets = {
     '4.4': '4.5',

package/mcp-server/lib/state-ops.cjs

@@ -518,7 +518,12 @@ function patchTask(db, id, patch = {}) {
     }
     if (nextStatus !== null) {
       const allowed = STATUS_TRANSITIONS[current.status] || new Set();
-      if (!allowed.has(nextStatus) && nextStatus !== current.status) {
+      const recoveringUncommittedCompletion = current.status === 'completed'
+        && nextStatus === 'blocked'
+        && !current.completion_commit
+        && Boolean(current.session_id);
+      if (!allowed.has(nextStatus) && nextStatus !== current.status
+          && !recoveringUncommittedCompletion) {
         throw new StateOpsError(
           'ILLEGAL_STATUS_TRANSITION',
           `cannot transition task ${id} from ${current.status} to ${nextStatus}`,