ultra-builder-pro-cli 0.6.0 → 0.8.1

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

@@ -0,0 +1,346 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const { initStateDb, closeStateDb } = require('./state-db.cjs');
+const ops = require('./state-ops.cjs');
+const changes = require('./change-workflow.cjs');
+
+function fixture() {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-change-'));
+  execFileSync('git', ['init', '-q'], { cwd: rootDir });
+  execFileSync('git', ['config', 'user.email', 'test@ubp.dev'], { cwd: rootDir });
+  execFileSync('git', ['config', 'user.name', 'ubp-test'], { cwd: rootDir });
+  fs.writeFileSync(path.join(rootDir, 'README.md'), '# Fixture\n');
+  execFileSync('git', ['add', 'README.md'], { cwd: rootDir });
+  execFileSync('git', ['commit', '-q', '-m', 'seed'], { cwd: rootDir });
+  const { db } = initStateDb(path.join(rootDir, '.ultra', 'state.db'));
+  return { rootDir, db };
+}
+
+function cleanup({ rootDir, db }) {
+  closeStateDb(db);
+  fs.rmSync(rootDir, { recursive: true, force: true });
+}
+
+function standardEvidence() {
+  return [
+    { category: 'diff', status: 'pass', evidence: 'git diff reviewed' },
+    { category: 'tests', status: 'pass', evidence: 'node --test passed' },
+    { category: 'spec', status: 'pass', evidence: 'delta reconciled' },
+    { category: 'docs', status: 'pass', evidence: 'docs/feature.md updated' },
+    { category: 'review', status: 'pass', evidence: 'review findings resolved' },
+  ];
+}
+
+function incidentEvidence() {
+  return [
+    { category: 'diagnosis', status: 'pass', evidence: 'Structured diagnosis artifact reviewed.' },
+    { category: 'diff', status: 'pass', evidence: 'Root-cause fix diff reviewed.' },
+    { category: 'tests', status: 'pass', evidence: 'Regression test reproduces then verifies the fix.' },
+  ];
+}
+
+test('createChange persists a change and an inspectable external-provider context manifest', () => {
+  const fx = fixture();
+  try {
+    const created = changes.createChange(fx.db, {
+      id: 'chg-context',
+      title: 'Keep context current',
+      kind: 'standard',
+      intent: 'Add a continuous change lane after project delivery.',
+      provider_refs: {
+        memory: { provider: 'cloud-mem', reference: 'cmem://project/fixture', status: 'available' },
+        code_graph: {
+          provider: 'codebase-memory-mcp', project: 'fixture', revision: 'graph-7',
+          indexed_head: execFileSync('git', ['rev-parse', 'HEAD'], { cwd: fx.rootDir, encoding: 'utf8' }).trim(),
+          status: 'fresh',
+        },
+      },
+    }, { rootDir: fx.rootDir });
+
+    assert.equal(created.change.status, 'active');
+    assert.equal(created.change.kind, 'standard');
+    assert.ok(fs.existsSync(created.intent_path));
+    assert.ok(fs.existsSync(created.context_manifest_path));
+
+    const manifest = JSON.parse(fs.readFileSync(created.context_manifest_path, 'utf8'));
+    assert.equal(manifest.change.id, 'chg-context');
+    assert.equal(manifest.providers.memory.provider, 'cloud-mem');
+    assert.equal(manifest.providers.code_graph.provider, 'codebase-memory-mcp');
+    assert.equal(manifest.providers.code_graph.status, 'fresh');
+    assert.equal(JSON.stringify(manifest).includes('prompt'), false);
+    assert.equal(JSON.stringify(manifest).includes('transcript'), false);
+  } finally {
+    cleanup(fx);
+  }
+});
+
+test('convergeChange blocks incomplete work and marks a fully evidenced standard change ready', () => {
+  const fx = fixture();
+  try {
+    changes.createChange(fx.db, {
+      id: 'chg-converge', title: 'Converge artifacts', kind: 'standard',
+      intent: 'Require code, specs, tests, docs, and review evidence to agree.',
+    }, { rootDir: fx.rootDir });
+
+    const blocked = changes.convergeChange(fx.db, {
+      id: 'chg-converge', evidence: standardEvidence(),
+    }, { rootDir: fx.rootDir });
+    assert.equal(blocked.ready, false);
+    assert.ok(blocked.blockers.includes('NO_TASKS'));
+    assert.ok(blocked.blockers.includes('DOCS_IMPACT_UNKNOWN'));
+    assert.ok(blocked.blockers.includes('SPEC_DELTA_MISSING'));
+    const blockedEvent = fx.db.prepare(
+      "SELECT type, change_id FROM events WHERE change_id = ? ORDER BY id DESC LIMIT 1",
+    ).get('chg-converge');
+    assert.deepEqual(blockedEvent, { type: 'change_blocked', change_id: 'chg-converge' });
+
+    fs.mkdirSync(path.join(fx.rootDir, 'docs'), { recursive: true });
+    fs.writeFileSync(path.join(fx.rootDir, 'docs', 'feature.md'), '# Continuous changes\n');
+    const deltaDir = path.join(fx.rootDir, '.ultra', 'changes', 'active', 'chg-converge', 'delta');
+    fs.mkdirSync(deltaDir, { recursive: true });
+    fs.writeFileSync(path.join(deltaDir, 'product.md'), '# Delta\n\nDaily changes remain traceable.\n');
+    fs.writeFileSync(
+      path.join(fx.rootDir, '.ultra', 'changes', 'active', 'chg-converge', 'plan.md'),
+      '# Plan\n\nImplement and verify the continuous change contract.\n',
+    );
+
+    changes.updateChange(fx.db, 'chg-converge', {
+      docs_impact: { status: 'required', files: ['docs/feature.md'], rationale: 'User-facing workflow changed.' },
+    });
+    ops.createTask(fx.db, {
+      id: 'change-task', title: 'Implement change lifecycle', type: 'feature', priority: 'P0',
+      change_id: 'chg-converge',
+    });
+    ops.updateTaskStatus(fx.db, 'change-task', 'in_progress');
+    ops.updateTaskStatus(fx.db, 'change-task', 'completed');
+    changes.compileContext(fx.db, { id: 'chg-converge' }, { rootDir: fx.rootDir });
+
+    const ready = changes.convergeChange(fx.db, {
+      id: 'chg-converge', evidence: standardEvidence(),
+    }, { rootDir: fx.rootDir });
+    assert.equal(ready.ready, true);
+    assert.equal(ready.status, 'ready');
+    assert.deepEqual(ready.blockers, []);
+    assert.ok(fs.existsSync(ready.verification_path));
+  } finally {
+    cleanup(fx);
+  }
+});
+
+test('archiveChange moves a ready change into immutable history and records baseline reconciliation', () => {
+  const fx = fixture();
+  try {
+    changes.createChange(fx.db, {
+      id: 'chg-archive', title: 'Archive verified change', kind: 'quick',
+      intent: 'Preserve the completed change as project history.',
+      docs_impact: { status: 'none', files: [], rationale: 'Internal test-only behavior.' },
+    }, { rootDir: fx.rootDir });
+    ops.createTask(fx.db, {
+      id: 'archive-task', title: 'Complete archive path', type: 'bugfix', priority: 'P1',
+      change_id: 'chg-archive',
+    });
+    ops.updateTaskStatus(fx.db, 'archive-task', 'in_progress');
+    ops.updateTaskStatus(fx.db, 'archive-task', 'completed');
+    changes.compileContext(fx.db, { id: 'chg-archive' }, { rootDir: fx.rootDir });
+    const converged = changes.convergeChange(fx.db, {
+      id: 'chg-archive',
+      evidence: [
+        { category: 'diff', status: 'pass', evidence: 'diff reviewed' },
+        { category: 'tests', status: 'pass', evidence: 'tests passed' },
+        { category: 'spec', status: 'not_applicable', evidence: 'No behavior contract changed.' },
+      ],
+    }, { rootDir: fx.rootDir });
+    assert.equal(converged.ready, true);
+
+    const archived = changes.archiveChange(fx.db, {
+      id: 'chg-archive', summary: 'Verified quick fix archived.',
+      no_baseline_change_reason: 'No canonical spec changed.',
+    }, { rootDir: fx.rootDir });
+    assert.equal(archived.change.status, 'archived');
+    assert.ok(fs.existsSync(archived.archive_path));
+    assert.equal(fs.existsSync(path.join(fx.rootDir, '.ultra', 'changes', 'active', 'chg-archive')), false);
+    const artifacts = fx.db.prepare(
+      'SELECT kind, path, status FROM artifacts WHERE change_id = ? ORDER BY kind',
+    ).all('chg-archive');
+    assert.ok(artifacts.some((artifact) => artifact.kind === 'archive_summary'));
+    for (const artifact of artifacts) {
+      assert.equal(artifact.status, 'archived');
+      assert.doesNotMatch(artifact.path, /changes\/active/);
+      assert.ok(fs.existsSync(path.join(fx.rootDir, artifact.path)), artifact.path);
+    }
+  } finally {
+    cleanup(fx);
+  }
+});
+
+test('provider references reject embedded memory or graph payloads', () => {
+  const fx = fixture();
+  try {
+    assert.throws(
+      () => changes.createChange(fx.db, {
+        id: 'chg-provider-content', title: 'Reject provider payload', kind: 'quick',
+        intent: 'Keep external provider content outside Ultra state.',
+        provider_refs: {
+          memory: { provider: 'cloud-mem', status: 'available', content: 'captured transcript' },
+        },
+      }, { rootDir: fx.rootDir }),
+      (error) => error.code === 'PROVIDER_CONTENT_FORBIDDEN',
+    );
+  } finally {
+    cleanup(fx);
+  }
+});
+
+test('createChange rejects whitespace-only title and intent outside the MCP boundary', () => {
+  const fx = fixture();
+  try {
+    assert.throws(
+      () => changes.createChange(fx.db, {
+        id: 'chg-empty-title', title: '   ', kind: 'quick', intent: 'Valid intent.',
+      }, { rootDir: fx.rootDir }),
+      (error) => error.code === 'VALIDATION_ERROR',
+    );
+    assert.throws(
+      () => changes.createChange(fx.db, {
+        id: 'chg-empty-intent', title: 'Valid title', kind: 'quick', intent: '\t',
+      }, { rootDir: fx.rootDir }),
+      (error) => error.code === 'VALIDATION_ERROR',
+    );
+  } finally {
+    cleanup(fx);
+  }
+});
+
+test('updateChange keeps intent.md synchronized with authoritative change metadata', () => {
+  const fx = fixture();
+  try {
+    const created = changes.createChange(fx.db, {
+      id: 'chg-update-intent', title: 'Original title', kind: 'quick',
+      intent: 'Original intent.',
+      docs_impact: { status: 'none', files: [], rationale: 'Internal-only change.' },
+    }, { rootDir: fx.rootDir });
+
+    changes.updateChange(fx.db, 'chg-update-intent', {
+      title: 'Updated title',
+      intent: 'Updated intent with current acceptance behavior.',
+      docs_impact: { status: 'required', files: ['README.md'], rationale: 'Usage changed.' },
+    }, { rootDir: fx.rootDir });
+
+    const text = fs.readFileSync(created.intent_path, 'utf8');
+    assert.match(text, /^# Updated title/m);
+    assert.match(text, /Updated intent with current acceptance behavior\./);
+    assert.match(text, /Documentation impact: `required`/);
+    const artifact = fx.db.prepare(
+      "SELECT content_hash FROM artifacts WHERE change_id = ? AND kind = 'intent'",
+    ).get('chg-update-intent');
+    assert.match(artifact.content_hash, /^[0-9a-f]{64}$/);
+  } finally {
+    cleanup(fx);
+  }
+});
+
+test('updateChange rejects whitespace-only title or intent outside the MCP boundary', () => {
+  const fx = fixture();
+  try {
+    changes.createChange(fx.db, {
+      id: 'chg-update-validation', title: 'Valid title', kind: 'quick',
+      intent: 'Valid intent.',
+    }, { rootDir: fx.rootDir });
+    assert.throws(
+      () => changes.updateChange(fx.db, 'chg-update-validation', { title: '   ' }, { rootDir: fx.rootDir }),
+      (error) => error.code === 'VALIDATION_ERROR',
+    );
+    assert.throws(
+      () => changes.updateChange(fx.db, 'chg-update-validation', { intent: '\t' }, { rootDir: fx.rootDir }),
+      (error) => error.code === 'VALIDATION_ERROR',
+    );
+  } finally {
+    cleanup(fx);
+  }
+});
+
+test('incident changes create a durable structured diagnosis artifact', () => {
+  const fx = fixture();
+  try {
+    const created = changes.createChange(fx.db, {
+      id: 'chg-incident-diagnosis', title: 'Diagnose runtime failure', kind: 'incident',
+      intent: 'Reproduce and fix the runtime failure at its root cause.',
+      docs_impact: { status: 'none', files: [], rationale: 'Internal runtime repair.' },
+    }, { rootDir: fx.rootDir });
+
+    const diagnosisPath = path.join(path.dirname(created.intent_path), 'diagnosis.md');
+    assert.ok(fs.existsSync(diagnosisPath));
+    const text = fs.readFileSync(diagnosisPath, 'utf8');
+    for (const heading of ['Reproduction', 'Hypotheses', 'Root cause', 'Regression test', 'Recovery']) {
+      assert.match(text, new RegExp(`^## ${heading}$`, 'm'));
+    }
+    const artifact = fx.db.prepare(
+      "SELECT kind, path, content_hash FROM artifacts WHERE change_id = ? AND kind = 'diagnosis'",
+    ).get('chg-incident-diagnosis');
+    assert.equal(artifact.kind, 'diagnosis');
+    assert.match(artifact.content_hash, /^[0-9a-f]{64}$/);
+    assert.equal(path.join(fx.rootDir, artifact.path), diagnosisPath);
+  } finally {
+    cleanup(fx);
+  }
+});
+
+test('incident convergence requires every structured diagnosis section and refreshes its artifact hash', () => {
+  const fx = fixture();
+  try {
+    const created = changes.createChange(fx.db, {
+      id: 'chg-incident-converge', title: 'Converge runtime diagnosis', kind: 'incident',
+      intent: 'Require inspectable debugging evidence before incident closure.',
+      docs_impact: { status: 'none', files: [], rationale: 'Internal runtime repair.' },
+    }, { rootDir: fx.rootDir });
+    ops.createTask(fx.db, {
+      id: 'incident-task', title: 'Fix diagnosed failure', type: 'bugfix', priority: 'P0',
+      change_id: 'chg-incident-converge',
+    });
+    ops.updateTaskStatus(fx.db, 'incident-task', 'in_progress');
+    ops.updateTaskStatus(fx.db, 'incident-task', 'completed');
+    changes.compileContext(fx.db, { id: 'chg-incident-converge' }, { rootDir: fx.rootDir });
+
+    const blocked = changes.convergeChange(fx.db, {
+      id: 'chg-incident-converge', evidence: incidentEvidence(),
+    }, { rootDir: fx.rootDir });
+    assert.equal(blocked.ready, false);
+    assert.ok(blocked.blockers.includes('DIAGNOSIS_SECTION_MISSING:reproduction'));
+    assert.ok(blocked.blockers.includes('DIAGNOSIS_SECTION_MISSING:root-cause'));
+
+    const diagnosisPath = path.join(path.dirname(created.intent_path), 'diagnosis.md');
+    const beforeHash = fx.db.prepare(
+      "SELECT content_hash FROM artifacts WHERE change_id = ? AND kind = 'diagnosis'",
+    ).get('chg-incident-converge').content_hash;
+    fs.writeFileSync(diagnosisPath, [
+      '# Incident diagnosis: Converge runtime diagnosis', '',
+      '## Reproduction', '', 'The projection worker fails after an interrupted claim.', '',
+      '## Hypotheses', '', 'A stale running job is never returned to the pending queue.', '',
+      '## Root cause', '', 'Boot recovery did not consume interrupted projection state.', '',
+      '## Regression test', '', 'The test seeds a stale running job and verifies requeue.', '',
+      '## Recovery', '', 'Requeue the job after the stale cutoff and replay projection.', '',
+    ].join('\n'));
+
+    const ready = changes.convergeChange(fx.db, {
+      id: 'chg-incident-converge', evidence: incidentEvidence(),
+    }, { rootDir: fx.rootDir });
+    assert.equal(ready.ready, true);
+    const afterHash = fx.db.prepare(
+      "SELECT content_hash FROM artifacts WHERE change_id = ? AND kind = 'diagnosis'",
+    ).get('chg-incident-converge').content_hash;
+    assert.notEqual(afterHash, beforeHash);
+    assert.equal(
+      afterHash,
+      require('node:crypto').createHash('sha256').update(fs.readFileSync(diagnosisPath)).digest('hex'),
+    );
+  } finally {
+    cleanup(fx);
+  }
+});

package/mcp-server/lib/doctor.cjs

@@ -0,0 +1,112 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { REQUIRED_TABLES, tableNames } = require('./state-db.cjs');
+const ops = require('./state-ops.cjs');
+const runtime = require('./runtime-state.cjs');
+const projector = require('./projector.cjs');
+const recovery = require('../../orchestrator/recovery.cjs');
+
+const SPEC_CONSUMER = 'spec-staleness';
+
+class DoctorError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'DoctorError';
+    this.code = code;
+  }
+}
+
+function timestamp() {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+function inspectSystem(db, { rootDir = process.cwd() } = {}) {
+  const tables = new Set(tableNames(db));
+  const missing = REQUIRED_TABLES.filter((name) => !tables.has(name));
+  const integrity = db.pragma('quick_check', { simple: true });
+  const incidents = missing.length === 0 ? runtime.listIncidents(db, { status: 'open' }) : [];
+  const pending = missing.length === 0 ? runtime.listProjectionJobs(db, { status: 'pending' }) : [];
+  const running = missing.length === 0 ? runtime.listProjectionJobs(db, { status: 'running' }) : [];
+  const failed = missing.length === 0 ? runtime.listProjectionJobs(db, { status: 'failed' }) : [];
+  const orphanSessions = missing.length === 0
+    ? db.prepare("SELECT COUNT(*) AS count FROM sessions WHERE status = 'orphan'").get().count
+    : 0;
+  const eventCursor = missing.length === 0
+    ? Number(db.prepare('SELECT COALESCE(MAX(id), 0) AS id FROM events').get().id)
+    : 0;
+  const projectedCursor = missing.length === 0
+    ? Number(db.prepare(
+        "SELECT COALESCE(MAX(event_cursor), 0) AS id FROM projection_jobs WHERE status = 'completed'",
+      ).get().id)
+    : 0;
+  const activeMissing = missing.length === 0
+    ? db.prepare(
+        `SELECT artifact_root FROM changes
+         WHERE status IN ('active', 'blocked', 'ready') AND artifact_root IS NOT NULL`,
+      ).all().filter((row) => row.artifact_root && !fs.existsSync(path.resolve(rootDir, row.artifact_root))).length
+    : 0;
+  const degraded = integrity !== 'ok' || missing.length > 0 || incidents.length > 0
+    || pending.length > 0 || running.length > 0 || failed.length > 0 || orphanSessions > 0 || activeMissing > 0
+    || eventCursor > projectedCursor;
+  return {
+    status: degraded ? 'degraded' : 'healthy',
+    checks: {
+      state_db: { status: integrity === 'ok' && missing.length === 0 ? 'pass' : 'fail', integrity, missing_tables: missing },
+      incidents: { status: incidents.length === 0 ? 'pass' : 'fail', open: incidents.length, items: incidents },
+      projections: {
+        status: pending.length === 0 && running.length === 0 && failed.length === 0 && eventCursor <= projectedCursor ? 'pass' : 'fail',
+        pending: pending.length, running: running.length, failed: failed.length,
+        event_cursor: eventCursor, projected_cursor: projectedCursor,
+      },
+      sessions: { status: orphanSessions === 0 ? 'pass' : 'fail', orphan: orphanSessions },
+      change_artifacts: { status: activeMissing === 0 ? 'pass' : 'fail', missing: activeMissing },
+      external_providers: {
+        status: 'pass', ownership: 'external',
+        note: 'Ultra stores provider metadata references only and never owns memory or code-graph content.',
+      },
+    },
+  };
+}
+
+async function backupDatabase(db, rootDir) {
+  const backupDir = path.join(rootDir, '.ultra', 'backups');
+  fs.mkdirSync(backupDir, { recursive: true });
+  const backupPath = path.join(backupDir, `state-${timestamp()}.db`);
+  try { await db.backup(backupPath); }
+  catch (error) { throw new DoctorError('BACKUP_FAILED', `state.db backup failed: ${error.message}`); }
+  return backupPath;
+}
+
+async function runDoctor(db, {
+  rootDir = process.cwd(), repair = false, project = projector.projectAll,
+  projectionStaleAfterMs = 5 * 60 * 1000,
+} = {}) {
+  if (!repair) return { ...inspectSystem(db, { rootDir }), repair_performed: false };
+  const backupPath = await backupDatabase(db, rootDir);
+  const recovered = recovery.recoverOnBoot(db);
+  const cursor = runtime.readConsumerCursor(db, SPEC_CONSUMER);
+  const consumed = ops.consumeSpecChangedEvents(db, { since_id: cursor, limit: 500 });
+  runtime.writeConsumerCursor(db, SPEC_CONSUMER, consumed.next_since_id);
+  const interrupted = runtime.requeueInterruptedProjections(db, {
+    staleBefore: new Date(Date.now() - Math.max(0, projectionStaleAfterMs)).toISOString(),
+  });
+  const requeued = runtime.requeueFailedProjections(db);
+  const ensured = runtime.ensureProjectionJob(db, { tool_name: 'system.doctor' });
+  const projections = runtime.processProjectionJobs(db, { rootDir, project, limit: 500 });
+  return {
+    ...inspectSystem(db, { rootDir }),
+    repair_performed: true,
+    backup_path: backupPath,
+    repair: { recovered, consumed, interrupted, requeued, ensured, projections },
+  };
+}
+
+module.exports = {
+  DoctorError,
+  SPEC_CONSUMER,
+  inspectSystem,
+  runDoctor,
+};

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

@@ -0,0 +1,86 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { initStateDb, closeStateDb } = require('./state-db.cjs');
+const ops = require('./state-ops.cjs');
+const runtime = require('./runtime-state.cjs');
+const doctor = require('./doctor.cjs');
+
+function fixture() {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-doctor-'));
+  const { db } = initStateDb(path.join(rootDir, '.ultra', 'state.db'));
+  return { rootDir, db };
+}
+
+function cleanup({ rootDir, db }) {
+  closeStateDb(db);
+  fs.rmSync(rootDir, { recursive: true, force: true });
+}
+
+test('doctor reports structured health for an initialized Ultra project', async () => {
+  const fx = fixture();
+  try {
+    const report = await doctor.runDoctor(fx.db, { rootDir: fx.rootDir });
+    assert.equal(report.status, 'healthy');
+    assert.equal(report.repair_performed, false);
+    assert.equal(report.checks.state_db.status, 'pass');
+    assert.equal(report.checks.external_providers.ownership, 'external');
+  } finally {
+    cleanup(fx);
+  }
+});
+
+test('doctor repair is backup-first and drains projection/spec-event recovery work', async () => {
+  const fx = fixture();
+  try {
+    ops.createTask(fx.db, {
+      id: 'stale-target', title: 'Refresh context', type: 'feature', priority: 'P1',
+      trace_to: '.ultra/specs/product.md#continuous-change',
+    });
+    ops.appendEvent(fx.db, {
+      type: 'spec_changed',
+      payload: { sections: ['.ultra/specs/product.md#continuous-change'] },
+    });
+    runtime.enqueueProjection(fx.db, { tool_name: 'task.append_event', event_cursor: 2 });
+
+    const report = await doctor.runDoctor(fx.db, { rootDir: fx.rootDir, repair: true });
+    assert.equal(report.repair_performed, true);
+    assert.ok(fs.existsSync(report.backup_path));
+    assert.equal(ops.readTask(fx.db, 'stale-target').stale, true);
+    assert.equal(runtime.readConsumerCursor(fx.db, 'spec-staleness'), 2);
+    assert.equal(runtime.listProjectionJobs(fx.db, { status: 'pending' }).length, 0);
+    assert.equal(report.status, 'healthy');
+  } finally {
+    cleanup(fx);
+  }
+});
+
+test('doctor reports running projection work and repairs only stale interrupted jobs', async () => {
+  const fx = fixture();
+  try {
+    ops.appendEvent(fx.db, { type: 'spec_changed', payload: { sections: [] } });
+    const job = runtime.enqueueProjection(fx.db, { tool_name: 'task.append_event', event_cursor: 1 });
+    fx.db.prepare("UPDATE projection_jobs SET status = 'running', updated_at = ? WHERE id = ?")
+      .run('2000-01-01T00:00:00.000Z', job.id);
+
+    const before = await doctor.runDoctor(fx.db, { rootDir: fx.rootDir });
+    assert.equal(before.status, 'degraded');
+    assert.equal(before.checks.projections.running, 1);
+
+    const after = await doctor.runDoctor(fx.db, {
+      rootDir: fx.rootDir,
+      repair: true,
+      projectionStaleAfterMs: 0,
+    });
+    assert.equal(after.repair.interrupted.requeued, 1);
+    assert.equal(after.checks.projections.running, 0);
+    assert.equal(after.status, 'healthy');
+  } finally {
+    cleanup(fx);
+  }
+});

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

@@ -14,6 +14,8 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
+const { initStateDb } = require('./state-db.cjs');
+
 const REPO_ROOT = process.env.UBP_RUNTIME_ROOT
   ? path.resolve(process.env.UBP_RUNTIME_ROOT)
   : path.resolve(__dirname, '..', '..');
@@ -109,6 +111,20 @@ function injectTasksJson(ultraDir, { project_name, project_type, stack }) {
   fs.writeFileSync(tasksFile, JSON.stringify(data, null, 2) + '\n');
 }
 
+function rollbackInitialization(ultraDir, backupPath) {
+  const errors = [];
+  try {
+    if (fs.existsSync(ultraDir)) fs.rmSync(ultraDir, { recursive: true, force: true });
+  } catch (error) {
+    errors.push(`partial cleanup failed: ${error.message}`);
+  }
+  if (backupPath) {
+    try { fs.renameSync(backupPath, ultraDir); }
+    catch (error) { errors.push(`backup restore failed: ${error.message}`); }
+  }
+  return errors;
+}
+
 function initProject({
   target_dir,
   project_name,
@@ -138,20 +154,30 @@ function initProject({
     status = 'overwritten';
   }
 
-  try { fs.mkdirSync(ultraDir, { recursive: true }); }
-  catch (err) { throw new InitProjectError('IO_ERROR', `cannot create .ultra/: ${err.message}`, { retriable: true, cause: err }); }
-
   let copiedFiles;
   try {
+    fs.mkdirSync(ultraDir, { recursive: true });
     copiedFiles = copyTemplate(source, ultraDir);
+    injectTasksJson(ultraDir, { project_name, project_type, stack });
+    const stateDbPath = path.join(ultraDir, 'state.db');
+    const { db } = initStateDb(stateDbPath);
+    db.close();
   } catch (err) {
-    throw new InitProjectError('IO_ERROR', `template copy failed: ${err.message}`, { retriable: true, cause: err });
+    const rollbackErrors = rollbackInitialization(ultraDir, backupPath);
+    const rollbackNote = rollbackErrors.length > 0
+      ? `; rollback incomplete: ${rollbackErrors.join('; ')}`
+      : '; prior state restored';
+    throw new InitProjectError(
+      'IO_ERROR',
+      `project initialization failed: ${err.message}${rollbackNote}`,
+      { retriable: true, cause: err },
+    );
   }
 
-  injectTasksJson(ultraDir, { project_name, project_type, stack });
-
+  const stateDbPath = path.join(ultraDir, 'state.db');
   const result = {
     created_path: ultraDir,
+    state_db_path: stateDbPath,
     status,
     copied_files: copiedFiles,
   };