ultra-builder-pro-cli 0.21.1 → 0.22.0

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}`,