ultra-builder-pro-cli 0.25.1 → 0.26.1

package/mcp-server/lib/task-ledger.cjs

@@ -1,1964 +0,0 @@
-'use strict';
-
-const crypto = require('node:crypto');
-const fs = require('node:fs');
-const path = require('node:path');
-const util = require('node:util');
-const Ajv = require('ajv/dist/2020');
-const addFormats = require('ajv-formats');
-
-const canonical = require('./canonical-json.cjs');
-const decisionRecords = require('./decision-records.cjs');
-const {
-  restoreManagedFile,
-  snapshotManagedFile,
-  writeManagedFile,
-} = require('./managed-file-write.cjs');
-const ops = require('./state-ops.cjs');
-const { readStableProjectFile } = require('./safe-project-file.cjs');
-const stageCheckpoints = require('./stage-checkpoints.cjs');
-const taskContract = require('./task-contract.cjs');
-const taskLedgerSchema = require('../../spec/schemas/task-ledger.v2.schema.json');
-
-const taskLedgerAjv = new Ajv({ allErrors: true, strict: false });
-addFormats(taskLedgerAjv);
-const validateTaskLedgerSchema = taskLedgerAjv.compile(taskLedgerSchema);
-
-const LEDGER_KIND = 'ultra-team-task-ledger';
-const LEDGER_SCHEMA_VERSION = '2.0';
-const LEGACY_LEDGER_SCHEMA_VERSION = '1.0';
-const LEDGER_RELATIVE_PATH = '.ultra/tasks/tasks.json';
-const HASH_PATTERN = /^[0-9a-f]{64}$/;
-const MAX_ANCESTORS = 64;
-const PUBLICATION_ROLLBACK = Symbol('task-ledger-publication-rollback');
-const DURABLE_BASELINE_FIELDS = Object.freeze([
-  'id',
-  'project_name',
-  'project_type',
-  'stack',
-  'mode',
-  'status',
-  'scope',
-  'repository_revision',
-  'repository_branch',
-  'worktree_state',
-  'worktree_digest',
-  'worktree_accepted',
-  'known_red_accepted',
-  'spec_refs',
-  'evidence',
-  'verification',
-  'unknowns',
-  'gaps',
-  'classification',
-  'provider_refs',
-  'research_checkpoint_id',
-  'approved_by',
-  'approval_note',
-  'converged_at',
-]);
-const LEGACY_DURABLE_BASELINE_FIELDS = Object.freeze(
-  DURABLE_BASELINE_FIELDS.map((field) => (
-    field === 'research_checkpoint_id' ? 'research_run_id' : field
-  )),
-);
-const DURABLE_TASK_FIELDS = taskContract.DURABLE_TASK_FIELDS;
-const DURABLE_CHANGE_FIELDS = Object.freeze([
-  'id',
-  'title',
-  'kind',
-  'status',
-  'intent',
-  'docs_impact',
-  'provider_refs',
-  'baseline_bypass',
-  'contract',
-  'classification',
-  'research_disposition',
-  'base_commit',
-  'supersedes_id',
-  'artifact_root',
-  'closed_at',
-]);
-const DURABLE_DECISION_FIELDS = Object.freeze([
-  'id',
-  'scope_type',
-  'scope_id',
-  'selection',
-  'effects',
-  'status',
-  'artifact_path',
-  'artifact_digest',
-  'supersedes_id',
-]);
-const DURABLE_CHECKPOINT_FIELDS = Object.freeze([
-  'stage',
-  'scope_type',
-  'scope_id',
-  'revision',
-  'payload',
-  'evidence',
-  'diagnostics',
-  'status',
-]);
-
-class TaskLedgerError extends Error {
-  constructor(code, message, details) {
-    super(message);
-    this.name = 'TaskLedgerError';
-    this.code = code;
-    if (details) this.details = details;
-  }
-}
-
-function ledgerPath(rootDir) {
-  return path.join(path.resolve(rootDir || '.'), ...LEDGER_RELATIVE_PATH.split('/'));
-}
-
-function safeDirectoryChain(rootDir, components, { create = false } = {}) {
-  const root = path.resolve(rootDir || '.');
-  const rootStat = fs.lstatSync(root, { throwIfNoEntry: false });
-  if (!rootStat || rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
-    throw new TaskLedgerError('TASK_LEDGER_UNSAFE', `project root is unsafe: ${root}`);
-  }
-  const physicalRoot = fs.realpathSync.native(root);
-  let current = root;
-  for (const component of components) {
-    current = path.join(current, component);
-    let stat = fs.lstatSync(current, { throwIfNoEntry: false });
-    if (!stat && create) {
-      fs.mkdirSync(current);
-      stat = fs.lstatSync(current);
-    }
-    if (!stat) return null;
-    if (stat.isSymbolicLink() || !stat.isDirectory()) {
-      throw new TaskLedgerError(
-        'TASK_LEDGER_UNSAFE',
-        `task ledger directory is unsafe: ${current}`,
-      );
-    }
-    const physical = fs.realpathSync.native(current);
-    if (physical !== physicalRoot && !physical.startsWith(`${physicalRoot}${path.sep}`)) {
-      throw new TaskLedgerError(
-        'TASK_LEDGER_UNSAFE',
-        `task ledger directory escapes the project: ${current}`,
-      );
-    }
-  }
-  return current;
-}
-
-function sha256(value) {
-  return crypto.createHash('sha256').update(
-    typeof value === 'string' ? value : JSON.stringify(value),
-  ).digest('hex');
-}
-
-function parseJson(value, fallback) {
-  if (value == null || value === '') return fallback;
-  try { return JSON.parse(value); }
-  catch { return fallback; }
-}
-
-function compactObject(entries) {
-  return Object.fromEntries(entries.filter(([, value]) => value !== null && value !== undefined));
-}
-
-function portableBaseline(row) {
-  if (!row) return null;
-  return compactObject([
-    ['id', row.id],
-    ['project_name', row.project_name],
-    ['project_type', row.project_type],
-    ['stack', row.stack],
-    ['mode', row.mode],
-    ['status', row.status],
-    ['scope', Array.isArray(row.scope) ? row.scope : parseJson(row.scope_json, ['.'])],
-    ['repository_revision', row.repository_revision],
-    ['repository_branch', row.repository_branch],
-    ['worktree_state', row.worktree_state],
-    ['worktree_digest', row.worktree_digest],
-    ['worktree_accepted', Boolean(row.worktree_accepted)],
-    ['known_red_accepted', Boolean(row.known_red_accepted)],
-    ['spec_refs', Array.isArray(row.spec_refs) ? row.spec_refs : parseJson(row.spec_refs_json, [])],
-    ['evidence', Array.isArray(row.evidence) ? row.evidence : parseJson(row.evidence_json, [])],
-    ['verification', Array.isArray(row.verification)
-      ? row.verification : parseJson(row.verification_json, [])],
-    ['unknowns', Array.isArray(row.unknowns) ? row.unknowns : parseJson(row.unknowns_json, [])],
-    ['gaps', Array.isArray(row.gaps) ? row.gaps : parseJson(row.gaps_json, [])],
-    ['classification', row.classification && typeof row.classification === 'object'
-      ? row.classification : parseJson(row.classification_json, {})],
-    ['provider_refs', row.provider_refs && typeof row.provider_refs === 'object'
-      ? row.provider_refs : parseJson(row.provider_refs_json, {})],
-    ['research_checkpoint_id', row.research_checkpoint_id || row.research_run_id],
-    ['approved_by', row.approved_by],
-    ['approval_note', row.approval_note],
-    ['converged_at', row.converged_at],
-  ]);
-}
-
-function durableBaseline(row, previous = null) {
-  if (!row) return null;
-  const value = portableBaseline(row);
-  const digest = sha256(value);
-  if (previous?.digest === digest) return previous;
-  return {
-    ...value,
-    revision: previous ? Number(previous.revision || 0) + 1 : 1,
-    parent_digest: previous?.digest || null,
-    digest,
-  };
-}
-
-function readBaselineForLedger(db, previous = null) {
-  const row = db.prepare(
-    `SELECT * FROM baselines
-     WHERE status <> 'superseded'
-     ORDER BY CASE status WHEN 'ready' THEN 0 ELSE 1 END, updated_at DESC, rowid DESC
-     LIMIT 1`,
-  ).get();
-  return durableBaseline(row, previous);
-}
-
-function portableChange(row) {
-  return compactObject([
-    ['id', row.id],
-    ['title', row.title],
-    ['kind', row.kind],
-    ['status', ['blocked', 'ready'].includes(row.status) ? 'active' : row.status],
-    ['intent', row.intent],
-    ['docs_impact', parseJson(row.docs_impact_json, {})],
-    ['provider_refs', parseJson(row.provider_refs_json, {})],
-    ['baseline_bypass', parseJson(row.baseline_bypass_json, null)],
-    ['contract', parseJson(row.contract_json, {})],
-    ['classification', parseJson(row.classification_json, {})],
-    ['research_disposition', parseJson(row.research_disposition_json, {})],
-    ['base_commit', row.base_commit],
-    ['supersedes_id', row.supersedes_id],
-    ['artifact_root', row.artifact_root],
-    ['closed_at', row.closed_at],
-  ]);
-}
-
-function durableChange(row, previous = null) {
-  const value = portableChange(row);
-  const digest = sha256(value);
-  if (previous?.digest === digest) return previous;
-  return {
-    ...value,
-    revision: previous ? Number(previous.revision || 0) + 1 : 1,
-    parent_digest: previous?.digest || null,
-    digest,
-  };
-}
-
-function readChangesForLedger(db, taskRows, previousChanges = new Map()) {
-  const rows = db.prepare('SELECT * FROM changes ORDER BY id').all();
-  const byId = new Map(rows.map((row) => [row.id, row]));
-  for (const task of taskRows) {
-    if (!task.change_id) continue;
-    const row = byId.get(task.change_id);
-    if (!row) {
-      throw new TaskLedgerError(
-        'TASK_LEDGER_CHANGE_MISSING',
-        `task ledger cannot publish missing owning change ${task.change_id}`,
-      );
-    }
-  }
-  return rows.map((row) => durableChange(row, previousChanges.get(row.id)));
-}
-
-function durableDecision(row) {
-  const value = compactObject([
-    ['id', row.id],
-    ['scope_type', row.scope_type],
-    ['scope_id', row.scope_id],
-    ['selection', row.selection],
-    ['effects', parseJson(row.effects_json, {})],
-    ['status', row.status],
-    ['artifact_path', row.artifact_path],
-    ['artifact_digest', row.digest],
-    ['supersedes_id', row.supersedes_id],
-  ]);
-  return {
-    ...value,
-    digest: sha256(value),
-  };
-}
-
-function readDecisionsForLedger(db) {
-  return db.prepare(
-    `SELECT * FROM decision_records
-     WHERE status IN ('accepted', 'superseded')
-     ORDER BY scope_type, scope_id, created_at, id`,
-  ).all().map(durableDecision);
-}
-
-function durableCheckpoint(row) {
-  const value = compactObject([
-    ['stage', row.stage],
-    ['scope_type', row.scope_type],
-    ['scope_id', row.scope_id],
-    ['revision', row.revision],
-    ['payload', parseJson(row.payload_json, {})],
-    ['evidence', parseJson(row.evidence_json, [])],
-    ['diagnostics', parseJson(row.diagnostics_json, [])],
-    ['status', row.status],
-  ]);
-  return {
-    ...value,
-    digest: sha256(value),
-  };
-}
-
-function readCheckpointsForLedger(db) {
-  return db.prepare(
-    `SELECT * FROM stage_checkpoints
-     WHERE status = 'accepted'
-     ORDER BY stage, scope_type, scope_id, revision`,
-  ).all().map(durableCheckpoint);
-}
-
-function durableStatus(task, previous) {
-  if (task.status !== 'in_progress') return task.status;
-  if (previous && previous.status !== 'in_progress') return previous.status;
-  return 'pending';
-}
-
-function assertValidTaskContract(entry) {
-  try {
-    taskContract.validateDurableTask(entry, { metadata: false });
-  } catch (error) {
-    if (!(error instanceof taskContract.TaskContractError)) throw error;
-    throw new TaskLedgerError(
-      'TASK_LEDGER_INVALID',
-      `task ledger entry ${entry?.id || '(unknown)'} violates the Task Contract: ${error.message}`,
-      error.details,
-    );
-  }
-  return entry;
-}
-
-function durableTask(task, previous = null) {
-  const value = compactObject([
-    ['id', task.id],
-    ['title', task.title],
-    ['type', task.type],
-    ['priority', task.priority],
-    ['complexity', task.complexity],
-    ['estimated_days', task.estimated_days],
-    ['status', durableStatus(task, previous)],
-    ['deps', task.deps == null ? [] : task.deps],
-    ['files_modified', task.files_modified == null ? [] : task.files_modified],
-    ['stale', task.stale == null ? false : task.stale],
-    ['trace_to', task.trace_to],
-    ['outcome', task.outcome],
-    ['slice_kind', task.slice_kind],
-    ['public_seam', task.public_seam],
-    ['verification_command', task.verification_command],
-    ['acceptance', task.acceptance == null ? [] : task.acceptance],
-    ['context_refs', task.context_refs == null ? [] : task.context_refs],
-    ['docs_impact', task.docs_impact == null
-      ? { status: 'unknown', files: [], rationale: null }
-      : task.docs_impact],
-    ['ownership', task.ownership == null ? {} : task.ownership],
-    ['change_id', task.change_id],
-    ['parent_id', task.parent_id],
-  ]);
-  const digest = sha256(value);
-  const entry = {
-    ...value,
-    revision: previous ? Number(previous.revision || 0) + 1 : 1,
-    parent_digest: previous?.digest || null,
-    digest,
-  };
-  assertValidTaskContract(entry);
-  if (previous && previous.digest === digest) return previous;
-  return entry;
-}
-
-function statePayload({
-  baseline,
-  changes,
-  decisions,
-  checkpoints,
-  tasks,
-}) {
-  return {
-    baseline: baseline || null,
-    changes: Array.isArray(changes) ? changes : [],
-    decisions: Array.isArray(decisions) ? decisions : [],
-    checkpoints: Array.isArray(checkpoints) ? checkpoints : [],
-    tasks: Array.isArray(tasks) ? tasks : [],
-  };
-}
-
-function validateTask(entry) {
-  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
-    throw new TaskLedgerError('TASK_LEDGER_INVALID', 'every task ledger entry must be an object');
-  }
-  for (const field of [
-    'id', 'title', 'type', 'priority', 'status', 'revision', 'digest',
-  ]) {
-    if (entry[field] === undefined || entry[field] === null || entry[field] === '') {
-      throw new TaskLedgerError(
-        'TASK_LEDGER_INVALID',
-        `task ledger entry ${entry.id || '(unknown)'} is missing ${field}`,
-      );
-    }
-  }
-  if (!Object.prototype.hasOwnProperty.call(entry, 'parent_digest')) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_INVALID',
-      `task ledger entry ${entry.id || '(unknown)'} is missing parent_digest`,
-    );
-  }
-  assertValidTaskContract(entry);
-  if (!Number.isInteger(entry.revision) || entry.revision < 1) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_INVALID',
-      `task ledger entry ${entry.id} has an invalid revision`,
-    );
-  }
-  if (!HASH_PATTERN.test(entry.digest) || entry.digest !== sha256(
-    Object.fromEntries(DURABLE_TASK_FIELDS
-      .filter((field) => entry[field] !== undefined)
-      .map((field) => [field, entry[field]])),
-  )) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_DIGEST_MISMATCH',
-      `task ledger entry ${entry.id} does not match its digest`,
-    );
-  }
-  if (entry.parent_digest != null && !HASH_PATTERN.test(entry.parent_digest)) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_INVALID',
-      `task ledger entry ${entry.id} has an invalid parent_digest`,
-    );
-  }
-}
-
-function validateLegacyTask(entry) {
-  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
-    throw new TaskLedgerError('TASK_LEDGER_INVALID', 'every legacy task entry must be an object');
-  }
-  for (const field of ['id', 'title', 'type', 'priority', 'status', 'revision', 'digest']) {
-    if (entry[field] === undefined || entry[field] === null || entry[field] === '') {
-      throw new TaskLedgerError(
-        'TASK_LEDGER_INVALID',
-        `legacy task entry ${entry.id || '(unknown)'} is missing ${field}`,
-      );
-    }
-  }
-  const value = Object.fromEntries(DURABLE_TASK_FIELDS
-    .filter((field) => entry[field] !== undefined)
-    .map((field) => [field, entry[field]]));
-  if (!HASH_PATTERN.test(entry.digest) || entry.digest !== sha256(value)) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_DIGEST_MISMATCH',
-      `legacy task entry ${entry.id} does not match its digest`,
-    );
-  }
-  if (entry.parent_digest != null && !HASH_PATTERN.test(entry.parent_digest)) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_INVALID',
-      `legacy task entry ${entry.id} has an invalid parent_digest`,
-    );
-  }
-}
-
-function validateBaseline(entry) {
-  if (entry == null) return;
-  if (typeof entry !== 'object' || Array.isArray(entry)) {
-    throw new TaskLedgerError('TASK_LEDGER_INVALID', 'baseline ledger entry must be an object');
-  }
-  for (const field of [
-    'id', 'project_name', 'mode', 'status', 'scope', 'revision', 'digest',
-  ]) {
-    if (entry[field] === undefined || entry[field] === null || entry[field] === '') {
-      throw new TaskLedgerError(
-        'TASK_LEDGER_INVALID',
-        `baseline ledger entry ${entry.id || '(unknown)'} is missing ${field}`,
-      );
-    }
-  }
-  const value = Object.fromEntries(DURABLE_BASELINE_FIELDS
-    .filter((field) => entry[field] !== undefined)
-    .map((field) => [field, entry[field]]));
-  if (!HASH_PATTERN.test(entry.digest) || entry.digest !== sha256(value)) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_DIGEST_MISMATCH',
-      `baseline ledger entry ${entry.id} does not match its digest`,
-    );
-  }
-  if (entry.parent_digest != null && !HASH_PATTERN.test(entry.parent_digest)) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_INVALID',
-      `baseline ledger entry ${entry.id} has an invalid parent_digest`,
-    );
-  }
-}
-
-function validateLegacyBaseline(entry) {
-  if (entry == null) return;
-  if (typeof entry !== 'object' || Array.isArray(entry)) {
-    throw new TaskLedgerError('TASK_LEDGER_INVALID', 'baseline ledger entry must be an object');
-  }
-  for (const field of [
-    'id', 'project_name', 'mode', 'status', 'scope', 'revision', 'digest',
-  ]) {
-    if (entry[field] === undefined || entry[field] === null || entry[field] === '') {
-      throw new TaskLedgerError(
-        'TASK_LEDGER_INVALID',
-        `baseline ledger entry ${entry.id || '(unknown)'} is missing ${field}`,
-      );
-    }
-  }
-  const value = Object.fromEntries(LEGACY_DURABLE_BASELINE_FIELDS
-    .filter((field) => entry[field] !== undefined)
-    .map((field) => [field, entry[field]]));
-  if (!HASH_PATTERN.test(entry.digest) || entry.digest !== sha256(value)) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_DIGEST_MISMATCH',
-      `baseline ledger entry ${entry.id} does not match its v1 digest`,
-    );
-  }
-  if (entry.parent_digest != null && !HASH_PATTERN.test(entry.parent_digest)) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_INVALID',
-      `baseline ledger entry ${entry.id} has an invalid parent_digest`,
-    );
-  }
-}
-
-function validateChange(entry) {
-  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
-    throw new TaskLedgerError('TASK_LEDGER_INVALID', 'every Change ledger entry must be an object');
-  }
-  for (const field of [
-    'id', 'title', 'kind', 'status', 'intent', 'artifact_root', 'revision', 'digest',
-  ]) {
-    if (entry[field] === undefined || entry[field] === null || entry[field] === '') {
-      throw new TaskLedgerError(
-        'TASK_LEDGER_INVALID',
-        `Change ledger entry ${entry.id || '(unknown)'} is missing ${field}`,
-      );
-    }
-  }
-  const value = Object.fromEntries(DURABLE_CHANGE_FIELDS
-    .filter((field) => entry[field] !== undefined)
-    .map((field) => [field, entry[field]]));
-  if (!HASH_PATTERN.test(entry.digest) || entry.digest !== sha256(value)) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_DIGEST_MISMATCH',
-      `Change ledger entry ${entry.id} does not match its digest`,
-    );
-  }
-  if (entry.parent_digest != null && !HASH_PATTERN.test(entry.parent_digest)) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_INVALID',
-      `Change ledger entry ${entry.id} has an invalid parent_digest`,
-    );
-  }
-}
-
-function validateDecision(entry) {
-  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
-    throw new TaskLedgerError('TASK_LEDGER_INVALID', 'every decision entry must be an object');
-  }
-  for (const field of [
-    'id', 'scope_type', 'scope_id', 'selection', 'status',
-    'artifact_path', 'artifact_digest', 'digest',
-  ]) {
-    if (entry[field] === undefined || entry[field] === null || entry[field] === '') {
-      throw new TaskLedgerError(
-        'TASK_LEDGER_INVALID',
-        `decision entry ${entry.id || '(unknown)'} is missing ${field}`,
-      );
-    }
-  }
-  const value = Object.fromEntries(DURABLE_DECISION_FIELDS
-    .filter((field) => entry[field] !== undefined)
-    .map((field) => [field, entry[field]]));
-  if (!HASH_PATTERN.test(entry.artifact_digest)
-      || !HASH_PATTERN.test(entry.digest)
-      || entry.digest !== sha256(value)) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_DIGEST_MISMATCH',
-      `decision entry ${entry.id} does not match its digest`,
-    );
-  }
-}
-
-function validateCheckpoint(entry) {
-  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
-    throw new TaskLedgerError('TASK_LEDGER_INVALID', 'every checkpoint entry must be an object');
-  }
-  for (const field of [
-    'stage', 'scope_type', 'scope_id', 'revision', 'payload',
-    'evidence', 'diagnostics', 'status', 'digest',
-  ]) {
-    if (entry[field] === undefined || entry[field] === null) {
-      throw new TaskLedgerError(
-        'TASK_LEDGER_INVALID',
-        `checkpoint entry ${entry.stage || '(unknown)'} is missing ${field}`,
-      );
-    }
-  }
-  const value = Object.fromEntries(DURABLE_CHECKPOINT_FIELDS
-    .filter((field) => entry[field] !== undefined)
-    .map((field) => [field, entry[field]]));
-  if (entry.status !== 'accepted'
-      || !HASH_PATTERN.test(entry.digest)
-      || entry.digest !== sha256(value)) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_DIGEST_MISMATCH',
-      `checkpoint ${entry.stage}:${entry.scope_type}:${entry.scope_id} is invalid`,
-    );
-  }
-}
-
-function validateLegacyLedger(document, file) {
-  if (!document || document.kind !== LEDGER_KIND
-      || document.schema_version !== LEGACY_LEDGER_SCHEMA_VERSION
-      || !Array.isArray(document.tasks)
-      || !Array.isArray(document.changes)
-      || !Array.isArray(document.ancestors)) {
-    return false;
-  }
-  validateLegacyBaseline(document.baseline);
-  document.tasks.forEach(validateLegacyTask);
-  document.changes.forEach(validateChange);
-  const expected = sha256({
-    baseline: document.baseline || null,
-    changes: document.changes,
-    tasks: document.tasks,
-  });
-  if (!HASH_PATTERN.test(document.state_digest || '')
-      || document.state_digest !== expected) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_DIGEST_MISMATCH',
-      `${file} legacy state_digest does not match its durable payload`,
-    );
-  }
-  return true;
-}
-
-function validateLedger(document, file = '(memory)') {
-  if (document?.schema_version === LEGACY_LEDGER_SCHEMA_VERSION
-      && validateLegacyLedger(document, file)) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_SCHEMA_MIGRATION_REQUIRED',
-      `${file} is a valid v${LEGACY_LEDGER_SCHEMA_VERSION} ledger and must migrate to v${LEDGER_SCHEMA_VERSION}`,
-      {
-        from: LEGACY_LEDGER_SCHEMA_VERSION,
-        to: LEDGER_SCHEMA_VERSION,
-      },
-    );
-  }
-  if (!document || typeof document !== 'object' || Array.isArray(document)
-      || document.kind !== LEDGER_KIND
-      || document.schema_version !== LEDGER_SCHEMA_VERSION
-      || !Number.isInteger(document.generation)
-      || document.generation < 0
-      || !Array.isArray(document.ancestors)
-      || !Array.isArray(document.tasks)
-      || !Array.isArray(document.changes)
-      || !Array.isArray(document.decisions)
-      || !Array.isArray(document.checkpoints)) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_INVALID',
-      `${file} is not an Ultra team task ledger v${LEDGER_SCHEMA_VERSION}`,
-    );
-  }
-  if (!validateTaskLedgerSchema(document)) {
-    const first = validateTaskLedgerSchema.errors?.[0];
-    const location = first?.instancePath || '(root)';
-    throw new TaskLedgerError(
-      'TASK_LEDGER_INVALID',
-      `${file} violates the exact v${LEDGER_SCHEMA_VERSION} schema at ${location}: `
-      + `${first?.message || 'schema validation failed'}`,
-      { errors: validateTaskLedgerSchema.errors || [] },
-    );
-  }
-  if (document.ancestors.length > MAX_ANCESTORS
-      || document.ancestors.some((digest) => !HASH_PATTERN.test(digest))) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_INVALID',
-      `${file} contains an invalid checkpoint ancestry chain`,
-    );
-  }
-  validateBaseline(document.baseline);
-  const seen = new Set();
-  for (const task of document.tasks) {
-    validateTask(task);
-    if (seen.has(task.id)) {
-      throw new TaskLedgerError('TASK_LEDGER_INVALID', `${file} contains duplicate task ${task.id}`);
-    }
-    seen.add(task.id);
-  }
-  const seenChanges = new Set();
-  for (const change of document.changes) {
-    validateChange(change);
-    if (seenChanges.has(change.id)) {
-      throw new TaskLedgerError(
-        'TASK_LEDGER_INVALID',
-        `${file} contains duplicate Change ${change.id}`,
-      );
-    }
-    seenChanges.add(change.id);
-  }
-  const seenDecisions = new Set();
-  for (const decision of document.decisions) {
-    validateDecision(decision);
-    if (seenDecisions.has(decision.id)) {
-      throw new TaskLedgerError(
-        'TASK_LEDGER_INVALID',
-        `${file} contains duplicate decision ${decision.id}`,
-      );
-    }
-    seenDecisions.add(decision.id);
-  }
-  const seenCheckpoints = new Set();
-  for (const checkpoint of document.checkpoints) {
-    validateCheckpoint(checkpoint);
-    const key = `${checkpoint.stage}:${checkpoint.scope_type}:${checkpoint.scope_id}`;
-    if (seenCheckpoints.has(key)) {
-      throw new TaskLedgerError(
-        'TASK_LEDGER_INVALID',
-        `${file} contains multiple accepted checkpoints for ${key}`,
-      );
-    }
-    seenCheckpoints.add(key);
-  }
-  const expected = sha256(statePayload(document));
-  if (!HASH_PATTERN.test(document.state_digest || '') || document.state_digest !== expected) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_DIGEST_MISMATCH',
-      `${file} state_digest does not match its durable payload`,
-    );
-  }
-  if (document.parent_digest != null && !HASH_PATTERN.test(document.parent_digest)) {
-    throw new TaskLedgerError('TASK_LEDGER_INVALID', `${file} has an invalid parent_digest`);
-  }
-  return document;
-}
-
-function readTaskLedger(rootDir, { optional = true } = {}) {
-  const file = ledgerPath(rootDir);
-  const directory = safeDirectoryChain(rootDir, ['.ultra', 'tasks']);
-  if (!directory) {
-    if (optional) return null;
-    throw new TaskLedgerError('TASK_LEDGER_INVALID', `task ledger is missing: ${file}`);
-  }
-  let stat;
-  try { stat = fs.lstatSync(file); }
-  catch (error) {
-    if (error.code === 'ENOENT' && optional) return null;
-    throw error;
-  }
-  if (stat.isSymbolicLink() || !stat.isFile()) {
-    throw new TaskLedgerError('TASK_LEDGER_UNSAFE', `task ledger must be a regular file: ${file}`);
-  }
-  let parsed;
-  try { parsed = JSON.parse(fs.readFileSync(file, 'utf8')); }
-  catch (error) {
-    throw new TaskLedgerError('TASK_LEDGER_INVALID', `cannot read ${file}: ${error.message}`);
-  }
-  return validateLedger(parsed, file);
-}
-
-function writeLedgerAtomic(rootDir, document) {
-  writeManagedFile(
-    rootDir,
-    LEDGER_RELATIVE_PATH,
-    `${JSON.stringify(document, null, 2)}\n`,
-  );
-  return ledgerPath(rootDir);
-}
-
-function migrateLegacyProjection(db, rootDir, originalError) {
-  const file = ledgerPath(rootDir);
-  let bytes;
-  let document;
-  try {
-    bytes = fs.readFileSync(file);
-    document = JSON.parse(bytes.toString('utf8'));
-  } catch {
-    throw originalError;
-  }
-  if (document?.kind === LEDGER_KIND
-      || !document || !Array.isArray(document.tasks)
-      || !['4.4', '4.5'].includes(String(document.version || document.schema_version))) {
-    throw originalError;
-  }
-  const legacyIds = document.tasks.map((task) => String(task?.id || '')).sort();
-  if (legacyIds.some((id) => !id) || new Set(legacyIds).size !== legacyIds.length) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_LEGACY_CONFLICT',
-      'legacy tasks projection has missing or duplicate task ids',
-    );
-  }
-  const currentIds = ops.listTasks(db, { status: 'any', limit: 1000 })
-    .map((task) => task.id)
-    .sort();
-  if (JSON.stringify(legacyIds) !== JSON.stringify(currentIds)) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_LEGACY_CONFLICT',
-      'legacy tasks projection does not match current SQLite task authority',
-      { legacy_task_ids: legacyIds, current_task_ids: currentIds },
-    );
-  }
-  const currentById = new Map(
-    ops.listTasks(db, { status: 'any', limit: 1000 }).map((task) => [task.id, task]),
-  );
-  for (const legacyTask of document.tasks) {
-    const current = currentById.get(legacyTask.id);
-    for (const field of DURABLE_TASK_FIELDS) {
-      if (legacyTask[field] === undefined) continue;
-      if (!util.isDeepStrictEqual(legacyTask[field], current[field])) {
-        throw new TaskLedgerError(
-          'TASK_LEDGER_LEGACY_CONFLICT',
-          `legacy task ${legacyTask.id} field ${field} does not match SQLite authority`,
-          {
-            task_id: legacyTask.id,
-            field,
-            legacy_value: legacyTask[field],
-            current_value: current[field],
-          },
-        );
-      }
-    }
-  }
-  const digest = sha256(bytes);
-  const backupDir = safeDirectoryChain(
-    rootDir,
-    ['.ultra', '.runtime', 'backups', 'task-ledger'],
-    { create: true },
-  );
-  const backup = path.join(backupDir, `legacy-tasks-${digest.slice(0, 16)}.json`);
-  if (fs.existsSync(backup)) {
-    const stat = fs.lstatSync(backup);
-    if (stat.isSymbolicLink() || !stat.isFile()
-        || !fs.readFileSync(backup).equals(bytes)) {
-      throw new TaskLedgerError(
-        'TASK_LEDGER_UNSAFE',
-        `legacy task ledger backup is unsafe or conflicting: ${backup}`,
-      );
-    }
-  } else {
-    fs.writeFileSync(backup, bytes, { flag: 'wx' });
-  }
-  return { previous: null, migrated: true, backup };
-}
-
-function migrateLegacyTeamLedger(rootDir, originalError) {
-  const file = ledgerPath(rootDir);
-  let bytes;
-  let document;
-  try {
-    bytes = fs.readFileSync(file);
-    document = JSON.parse(bytes.toString('utf8'));
-    if (!validateLegacyLedger(document, file)) throw originalError;
-  } catch (error) {
-    if (error instanceof TaskLedgerError) throw error;
-    throw originalError;
-  }
-  const digest = sha256(bytes);
-  const backupDir = safeDirectoryChain(
-    rootDir,
-    ['.ultra', '.runtime', 'backups', 'task-ledger'],
-    { create: true },
-  );
-  const backup = path.join(backupDir, `team-ledger-v1-${digest.slice(0, 16)}.json`);
-  if (fs.existsSync(backup)) {
-    const stat = fs.lstatSync(backup);
-    if (stat.isSymbolicLink() || !stat.isFile()
-        || !fs.readFileSync(backup).equals(bytes)) {
-      throw new TaskLedgerError(
-        'TASK_LEDGER_UNSAFE',
-        `legacy team ledger backup is unsafe or conflicting: ${backup}`,
-      );
-    }
-  } else {
-    fs.writeFileSync(backup, bytes, { flag: 'wx' });
-  }
-  return {
-    previous: {
-      ...document,
-      decisions: [],
-      checkpoints: [],
-    },
-    migrated: true,
-    backup,
-    migration_kind: 'team-ledger-v1',
-  };
-}
-
-function priorLedgerForPublish(db, rootDir) {
-  try {
-    return { previous: readTaskLedger(rootDir), migrated: false, backup: null };
-  } catch (error) {
-    if (error.code === 'TASK_LEDGER_SCHEMA_MIGRATION_REQUIRED') {
-      return migrateLegacyTeamLedger(rootDir, error);
-    }
-    if (!['TASK_LEDGER_INVALID', 'TASK_LEDGER_DIGEST_MISMATCH'].includes(error.code)) {
-      throw error;
-    }
-    return migrateLegacyProjection(db, rootDir, error);
-  }
-}
-
-function syncTaskLedger(db, { rootDir = '.' } = {}) {
-  let document;
-  try {
-    document = readTaskLedger(rootDir);
-  } catch (error) {
-    if (error.code === 'TASK_LEDGER_SCHEMA_MIGRATION_REQUIRED') {
-      return { status: 'legacy', imported: 0, already_current: false };
-    }
-    if (!['TASK_LEDGER_INVALID', 'TASK_LEDGER_DIGEST_MISMATCH'].includes(error.code)) {
-      throw error;
-    }
-    try {
-      const raw = JSON.parse(fs.readFileSync(ledgerPath(rootDir), 'utf8'));
-      if (raw && Array.isArray(raw.tasks)
-          && ['4.4', '4.5'].includes(String(raw.version || raw.schema_version))) {
-        return { status: 'legacy', imported: 0, already_current: false };
-      }
-    } catch {
-      // Preserve the typed ledger error from the validated read.
-    }
-    throw error;
-  }
-  if (!document) {
-    return { status: 'missing', imported: 0, already_current: false };
-  }
-  const checkpoint = latestImportedCheckpoint(db);
-  if (checkpoint.state_digest === document.state_digest) {
-    return {
-      status: 'current',
-      imported: 0,
-      preserved: document.tasks.length,
-      deleted: 0,
-      imported_changes: 0,
-      preserved_changes: document.changes.length,
-      imported_decisions: 0,
-      preserved_decisions: document.decisions.length,
-      imported_checkpoints: 0,
-      preserved_checkpoints: document.checkpoints.length,
-      imported_baseline: false,
-      preserved_baseline: Boolean(document.baseline),
-      generation: document.generation,
-      state_digest: document.state_digest,
-      requires_plan_revalidation: false,
-      requires_baseline_revalidation: false,
-      already_current: true,
-    };
-  }
-  return {
-    status: 'imported',
-    ...importTaskLedger(db, { rootDir }),
-  };
-}
-
-function taskDigestMap(tasks) {
-  return Object.fromEntries(tasks.map((task) => [task.id, task.digest]));
-}
-
-function checkpointDigestMap(checkpoints) {
-  return Object.fromEntries(checkpoints.map((checkpoint) => [
-    `${checkpoint.stage}:${checkpoint.scope_type}:${checkpoint.scope_id}`,
-    checkpoint.digest,
-  ]));
-}
-
-function recordLedgerEvent(db, type, ledger, extra = {}) {
-  ops.appendEvent(db, {
-    type,
-    payload: {
-      generation: ledger.generation,
-      state_digest: ledger.state_digest,
-      baseline_digest: ledger.baseline?.digest || null,
-      baseline_checkpoint: ledger.baseline || null,
-      task_digests: taskDigestMap(ledger.tasks),
-      change_digests: taskDigestMap(ledger.changes),
-      decision_digests: taskDigestMap(ledger.decisions || []),
-      checkpoint_digests: checkpointDigestMap(ledger.checkpoints || []),
-      ...extra,
-    },
-  });
-}
-
-function publishTaskLedger(db, {
-  rootDir = '.',
-  reason = 'manual_checkpoint',
-} = {}) {
-  let prior = priorLedgerForPublish(db, rootDir);
-  if (prior.previous && !prior.migrated) {
-    syncTaskLedger(db, { rootDir });
-    prior = {
-      previous: readTaskLedger(rootDir),
-      migrated: false,
-      backup: null,
-    };
-  }
-  const previous = prior.previous;
-  const priorTasks = new Map((previous?.tasks || []).map((task) => [task.id, task]));
-  const priorChanges = new Map((previous?.changes || []).map((change) => [change.id, change]));
-  const rows = ops.listTasks(db, { status: 'any', limit: 1000 })
-    .sort((left, right) => left.id.localeCompare(right.id));
-  const tasks = rows.map((task) => durableTask(task, priorTasks.get(task.id)));
-  const baseline = readBaselineForLedger(db, previous?.baseline || null);
-  if (baseline?.gaps?.some((gap) => (
-    gap.id === 'team-ledger-revalidation-required' && gap.status === 'open'
-  ))) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_REVALIDATION_REQUIRED',
-      'the imported team baseline must converge in this checkout before publication',
-      { baseline_id: baseline.id, ledger_path: LEDGER_RELATIVE_PATH },
-    );
-  }
-  const changes = readChangesForLedger(db, rows, priorChanges);
-  const decisions = readDecisionsForLedger(db);
-  const checkpoints = readCheckpointsForLedger(db);
-  const digest = sha256(statePayload({
-    baseline,
-    changes,
-    decisions,
-    checkpoints,
-    tasks,
-  }));
-  if (previous?.state_digest === digest) {
-    return {
-      changed: false,
-      path: ledgerPath(rootDir),
-      ledger: previous,
-    };
-  }
-  const document = {
-    kind: LEDGER_KIND,
-    schema_version: LEDGER_SCHEMA_VERSION,
-    generation: Number(previous?.generation || 0) + 1,
-    parent_digest: previous?.state_digest || null,
-    ancestors: previous
-      ? [previous.state_digest, ...(previous.ancestors || [])].slice(0, MAX_ANCESTORS)
-      : [],
-    state_digest: digest,
-    published_at: new Date().toISOString(),
-    reason,
-    baseline,
-    changes,
-    decisions,
-    checkpoints,
-    tasks,
-  };
-  validateLedger(document);
-  const snapshot = snapshotManagedFile(rootDir, LEDGER_RELATIVE_PATH);
-  let file;
-  try {
-    file = writeLedgerAtomic(rootDir, document);
-    recordLedgerEvent(db, 'task_ledger_published', document, {
-      reason,
-      migrated_legacy_projection: prior.migrated,
-      legacy_backup_path: prior.backup,
-    });
-  } catch (error) {
-    try {
-      restoreManagedFile(rootDir, snapshot);
-    } catch (rollbackError) {
-      throw new TaskLedgerError(
-        'STATE_CORRUPT',
-        'task ledger publication failed and the previous ledger bytes could not be restored',
-        {
-          cause: error.code || error.message,
-          rollback: rollbackError.code || rollbackError.message,
-          path: LEDGER_RELATIVE_PATH,
-        },
-      );
-    }
-    throw error;
-  }
-  const result = {
-    changed: true,
-    path: file,
-    ledger: document,
-    migrated_legacy_projection: prior.migrated,
-    legacy_backup_path: prior.backup,
-  };
-  Object.defineProperty(result, PUBLICATION_ROLLBACK, {
-    configurable: false,
-    enumerable: false,
-    writable: false,
-    value: { rootDir: path.resolve(rootDir), snapshot },
-  });
-  return result;
-}
-
-function rollbackTaskLedgerPublication(publication) {
-  const rollback = publication?.[PUBLICATION_ROLLBACK];
-  if (!rollback) return { restored: false, reason: 'NO_PUBLICATION_ROLLBACK' };
-  restoreManagedFile(rollback.rootDir, rollback.snapshot);
-  return {
-    restored: true,
-    path: rollback.snapshot.path,
-    previous_existed: rollback.snapshot.existed,
-  };
-}
-
-function latestImportedCheckpoint(db) {
-  const row = db.prepare(
-    `SELECT payload_json FROM events
-     WHERE type IN ('task_ledger_imported', 'task_ledger_published')
-     ORDER BY id DESC LIMIT 1`,
-  ).get();
-  const payload = parseJson(row?.payload_json, {});
-  return {
-    generation: Number.isInteger(payload.generation) ? payload.generation : null,
-    state_digest: HASH_PATTERN.test(payload.state_digest || '') ? payload.state_digest : null,
-    task_digests: payload.task_digests && typeof payload.task_digests === 'object'
-      ? payload.task_digests
-      : {},
-    change_digests: payload.change_digests && typeof payload.change_digests === 'object'
-      ? payload.change_digests
-      : {},
-    decision_digests: payload.decision_digests && typeof payload.decision_digests === 'object'
-      ? payload.decision_digests
-      : {},
-    checkpoint_digests: payload.checkpoint_digests
-      && typeof payload.checkpoint_digests === 'object'
-      ? payload.checkpoint_digests
-      : {},
-    baseline_digest: HASH_PATTERN.test(payload.baseline_digest || '')
-      ? payload.baseline_digest
-      : null,
-    baseline_checkpoint: payload.baseline_checkpoint
-      && typeof payload.baseline_checkpoint === 'object'
-      ? payload.baseline_checkpoint
-      : null,
-  };
-}
-
-function baselineForLocalCheckout(baseline) {
-  const value = portableBaseline(baseline);
-  const requiresRevalidation = baseline.status === 'ready';
-  if (!requiresRevalidation) return { value, requiresRevalidation: false };
-  const gaps = [...(value.gaps || [])];
-  if (requiresRevalidation && !gaps.some((gap) => gap.id === 'team-ledger-revalidation-required')) {
-    gaps.push({
-      id: 'team-ledger-revalidation-required',
-      category: 'baseline_blocker',
-      status: 'open',
-      blocking: true,
-      summary: 'The imported team checkpoint must be revalidated against this checkout.',
-      evidence_refs: [LEDGER_RELATIVE_PATH],
-      owner: 'project-owner',
-    });
-  }
-  return {
-    value: compactObject(Object.entries({
-      ...value,
-      status: value.mode === 'greenfield' ? 'draft' : 'adopting',
-      worktree_accepted: false,
-      known_red_accepted: false,
-      gaps,
-      research_checkpoint_id: undefined,
-      approved_by: undefined,
-      approval_note: undefined,
-      converged_at: undefined,
-    })),
-    requiresRevalidation: true,
-  };
-}
-
-function writeBaseline(db, baseline, { update = false } = {}) {
-  const local = baselineForLocalCheckout(baseline);
-  const value = local.value;
-  if (update) {
-    db.prepare(
-      `UPDATE baselines SET
-         project_name = ?, project_type = ?, stack = ?, mode = ?, status = ?,
-         scope_json = ?, repository_revision = ?, repository_branch = ?,
-         worktree_state = ?, worktree_digest = ?, worktree_accepted = ?,
-         known_red_accepted = ?, spec_refs_json = ?, evidence_json = ?,
-         verification_json = ?, unknowns_json = ?, gaps_json = ?,
-         classification_json = ?, provider_refs_json = ?,
-         research_checkpoint_id = ?, research_run_id = NULL,
-         approved_by = ?, approval_note = ?, converged_at = ?, updated_at = ?
-       WHERE id = ?`,
-    ).run(
-      value.project_name,
-      value.project_type || null,
-      value.stack || null,
-      value.mode,
-      value.status,
-      JSON.stringify(value.scope || ['.']),
-      value.repository_revision || null,
-      value.repository_branch || null,
-      value.worktree_state || 'unavailable',
-      value.worktree_digest || null,
-      value.worktree_accepted ? 1 : 0,
-      value.known_red_accepted ? 1 : 0,
-      JSON.stringify(value.spec_refs || []),
-      JSON.stringify(value.evidence || []),
-      JSON.stringify(value.verification || []),
-      JSON.stringify(value.unknowns || []),
-      JSON.stringify(value.gaps || []),
-      JSON.stringify(value.classification || {}),
-      JSON.stringify(value.provider_refs || {}),
-      value.research_checkpoint_id || null,
-      value.approved_by || null,
-      value.approval_note || null,
-      value.converged_at || null,
-      new Date().toISOString(),
-      value.id,
-    );
-    return local;
-  }
-  db.prepare(
-    `INSERT INTO baselines
-     (id, project_name, project_type, stack, mode, status, repository_root, scope_json,
-      repository_revision, repository_branch, worktree_state, worktree_digest,
-      worktree_accepted, known_red_accepted, spec_refs_json, evidence_json,
-      verification_json, unknowns_json, gaps_json, classification_json,
-      provider_refs_json, research_checkpoint_id, research_run_id,
-      approved_by, approval_note, converged_at)
-     VALUES (?, ?, ?, ?, ?, ?, '.', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, ?, ?)`,
-  ).run(
-    value.id,
-    value.project_name,
-    value.project_type || null,
-    value.stack || null,
-    value.mode,
-    value.status,
-    JSON.stringify(value.scope || ['.']),
-    value.repository_revision || null,
-    value.repository_branch || null,
-    value.worktree_state || 'unavailable',
-    value.worktree_digest || null,
-    value.worktree_accepted ? 1 : 0,
-    value.known_red_accepted ? 1 : 0,
-    JSON.stringify(value.spec_refs || []),
-    JSON.stringify(value.evidence || []),
-    JSON.stringify(value.verification || []),
-    JSON.stringify(value.unknowns || []),
-    JSON.stringify(value.gaps || []),
-    JSON.stringify(value.classification || {}),
-    JSON.stringify(value.provider_refs || {}),
-    value.research_checkpoint_id || null,
-    value.approved_by || null,
-    value.approval_note || null,
-    value.converged_at || null,
-  );
-  return local;
-}
-
-function localBaselineMatchesRevalidation(row, checkpointBaseline) {
-  if (!row || !checkpointBaseline || row.id !== checkpointBaseline.id
-      || checkpointBaseline.status !== 'ready') return false;
-  const expected = baselineForLocalCheckout(checkpointBaseline).value;
-  return util.isDeepStrictEqual(portableBaseline(row), expected);
-}
-
-function mergeBaseline(db, incoming, checkpoint) {
-  if (!incoming) {
-    return { imported: false, preserved: false, requiresRevalidation: false };
-  }
-  const active = db.prepare(
-    `SELECT * FROM baselines
-     WHERE status <> 'superseded'
-     ORDER BY CASE status WHEN 'ready' THEN 0 ELSE 1 END, updated_at DESC, rowid DESC
-     LIMIT 1`,
-  ).get();
-  if (!active) {
-    const written = writeBaseline(db, incoming);
-    return {
-      imported: true,
-      preserved: false,
-      requiresRevalidation: written.requiresRevalidation,
-    };
-  }
-
-  const current = durableBaseline(active, null);
-  const lastDigest = checkpoint.baseline_digest;
-  const effectiveCurrentDigest = localBaselineMatchesRevalidation(
-    active,
-    checkpoint.baseline_checkpoint,
-  ) ? lastDigest : current.digest;
-  if (active.id === incoming.id && current.digest === incoming.digest) {
-    return { imported: false, preserved: true, requiresRevalidation: false };
-  }
-  if (!lastDigest) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_BASELINE_CONFLICT',
-      `baseline ${active.id} exists locally without a common team checkpoint`,
-      {
-        local_baseline_id: active.id,
-        incoming_baseline_id: incoming.id,
-        local_digest: current.digest,
-        incoming_digest: incoming.digest,
-      },
-    );
-  }
-  if (effectiveCurrentDigest !== lastDigest && incoming.digest === lastDigest) {
-    return { imported: false, preserved: true, requiresRevalidation: false };
-  }
-  if (effectiveCurrentDigest !== lastDigest && incoming.digest !== lastDigest) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_BASELINE_CONFLICT',
-      'baseline changed both locally and in the Git ledger',
-      {
-        local_baseline_id: active.id,
-        incoming_baseline_id: incoming.id,
-        last_digest: lastDigest,
-        local_digest: current.digest,
-        incoming_digest: incoming.digest,
-      },
-    );
-  }
-  if (active.id !== incoming.id) {
-    db.prepare(
-      "UPDATE baselines SET status = 'superseded', updated_at = ? WHERE id = ?",
-    ).run(new Date().toISOString(), active.id);
-    const written = writeBaseline(db, incoming);
-    return {
-      imported: true,
-      preserved: false,
-      requiresRevalidation: written.requiresRevalidation,
-    };
-  }
-  const written = writeBaseline(db, incoming, { update: true });
-  return {
-    imported: true,
-    preserved: false,
-    requiresRevalidation: written.requiresRevalidation,
-  };
-}
-
-function insertChange(db, change) {
-  db.prepare(
-    `INSERT INTO changes
-     (id, title, kind, status, intent, docs_impact_json, provider_refs_json,
-      baseline_bypass_json, contract_json, classification_json,
-      research_disposition_json, base_commit, supersedes_id, artifact_root, closed_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-  ).run(
-    change.id,
-    change.title,
-    change.kind,
-    change.status,
-    change.intent,
-    JSON.stringify(change.docs_impact || {}),
-    JSON.stringify(change.provider_refs || {}),
-    change.baseline_bypass ? JSON.stringify(change.baseline_bypass) : null,
-    JSON.stringify(change.contract || {}),
-    JSON.stringify(change.classification || {}),
-    JSON.stringify(change.research_disposition || {}),
-    change.base_commit || null,
-    change.supersedes_id || null,
-    change.artifact_root,
-    change.closed_at || null,
-  );
-}
-
-function updateChangeFromLedger(db, change) {
-  db.prepare(
-    `UPDATE changes SET
-       title = ?, kind = ?, status = ?, intent = ?, docs_impact_json = ?,
-       provider_refs_json = ?, baseline_bypass_json = ?, contract_json = ?,
-       classification_json = ?, research_disposition_json = ?, base_commit = ?,
-       supersedes_id = ?, artifact_root = ?, closed_at = ?, updated_at = ?
-     WHERE id = ?`,
-  ).run(
-    change.title,
-    change.kind,
-    change.status,
-    change.intent,
-    JSON.stringify(change.docs_impact || {}),
-    JSON.stringify(change.provider_refs || {}),
-    change.baseline_bypass ? JSON.stringify(change.baseline_bypass) : null,
-    JSON.stringify(change.contract || {}),
-    JSON.stringify(change.classification || {}),
-    JSON.stringify(change.research_disposition || {}),
-    change.base_commit || null,
-    change.supersedes_id || null,
-    change.artifact_root,
-    change.closed_at || null,
-    new Date().toISOString(),
-    change.id,
-  );
-}
-
-function insertTaskFromLedger(db, task) {
-  const created = ops.createTask(db, {
-    id: task.id,
-    title: task.title,
-    type: task.type,
-    priority: task.priority,
-    complexity: task.complexity,
-    estimated_days: task.estimated_days,
-    deps: task.deps || [],
-    files_modified: task.files_modified || [],
-    stale: Boolean(task.stale),
-    trace_to: task.trace_to,
-    outcome: task.outcome,
-    slice_kind: task.slice_kind,
-    public_seam: task.public_seam,
-    verification_command: task.verification_command,
-    acceptance: task.acceptance || [],
-    context_refs: task.context_refs || [],
-    docs_impact: task.docs_impact || { status: 'unknown', files: [], rationale: null },
-    ownership: task.ownership || {},
-    change_id: task.change_id || null,
-    parent_id: null,
-  });
-  if (task.status !== created.status || Boolean(task.stale) !== created.stale) {
-    updateTaskFromLedger(db, task);
-  }
-  return ops.readTask(db, task.id);
-}
-
-function updateTaskFromLedger(db, task) {
-  db.prepare(
-    `UPDATE tasks SET
-       title = ?, type = ?, priority = ?, complexity = ?, estimated_days = ?,
-       status = ?, deps = ?, files_modified = ?, session_id = NULL, stale = ?,
-       trace_to = ?, outcome = ?, slice_kind = ?, public_seam = ?,
-       verification_command = ?, acceptance_json = ?, context_refs_json = ?,
-       docs_impact_json = ?, ownership_json = ?, change_id = ?, updated_at = ?
-     WHERE id = ?`,
-  ).run(
-    task.title,
-    task.type,
-    task.priority,
-    task.complexity ?? null,
-    task.estimated_days ?? null,
-    task.status,
-    JSON.stringify(task.deps || []),
-    JSON.stringify(task.files_modified || []),
-    task.stale ? 1 : 0,
-    task.trace_to || null,
-    task.outcome || null,
-    task.slice_kind || null,
-    task.public_seam || null,
-    task.verification_command || null,
-    JSON.stringify(task.acceptance || []),
-    JSON.stringify(task.context_refs || []),
-    JSON.stringify(task.docs_impact || { status: 'unknown', files: [], rationale: null }),
-    JSON.stringify(task.ownership || {}),
-    task.change_id || null,
-    new Date().toISOString(),
-    task.id,
-  );
-}
-
-function decisionDocument(rootDir, entry) {
-  const read = readStableProjectFile(rootDir, entry.artifact_path, { encoding: 'utf8' });
-  let document;
-  try { document = JSON.parse(read.text); }
-  catch (error) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_DECISION_INVALID',
-      `decision artifact ${entry.artifact_path} is invalid JSON: ${error.message}`,
-    );
-  }
-  const { digest, ...value } = document;
-  if (digest !== entry.artifact_digest || canonical.digest(value) !== digest) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_DECISION_CONFLICT',
-      `decision artifact ${entry.artifact_path} does not match the team ledger`,
-      {
-        decision_id: entry.id,
-        ledger_digest: entry.artifact_digest,
-        artifact_digest: digest || null,
-      },
-    );
-  }
-  return document;
-}
-
-function importDecisionEntry(db, rootDir, entry) {
-  const existing = decisionRecords.readDecision(db, entry.id);
-  if (existing) {
-    if (existing.digest !== entry.artifact_digest) {
-      throw new TaskLedgerError(
-        'TASK_LEDGER_DECISION_CONFLICT',
-        `decision ${entry.id} changed both locally and in the team ledger`,
-      );
-    }
-    return false;
-  }
-  const document = decisionDocument(rootDir, entry);
-  const accepted = decisionRecords.acceptDecision(db, {
-    id: document.id,
-    scope: document.scope.type === 'baseline'
-      ? { baseline_id: document.scope.id }
-      : { change_id: document.scope.id },
-    question: document.question,
-    recommendation: document.recommendation,
-    selection: document.selection,
-    effects: document.effects,
-    non_goals: document.non_goals,
-    owner: document.owner,
-    source: document.source,
-    provenance: document.provenance,
-    applied_refs: document.applied_refs,
-    supersedes_id: document.supersedes_id || undefined,
-  }, { rootDir });
-  if (accepted.digest !== entry.artifact_digest) {
-    throw new TaskLedgerError(
-      'TASK_LEDGER_DECISION_CONFLICT',
-      `decision ${entry.id} changed while it was imported`,
-    );
-  }
-  return true;
-}
-
-function mergeTeamDecisions(db, rootDir, entries) {
-  const pending = new Map(entries.map((entry) => [entry.id, entry]));
-  let imported = 0;
-  while (pending.size > 0) {
-    let progressed = false;
-    for (const [id, entry] of pending) {
-      if (entry.supersedes_id
-          && pending.has(entry.supersedes_id)
-          && !decisionRecords.readDecision(db, entry.supersedes_id)) {
-        continue;
-      }
-      if (importDecisionEntry(db, rootDir, entry)) imported += 1;
-      pending.delete(id);
-      progressed = true;
-    }
-    if (!progressed) {
-      throw new TaskLedgerError(
-        'TASK_LEDGER_DECISION_CONFLICT',
-        'decision supersession graph cannot be imported deterministically',
-        { decision_ids: [...pending.keys()].sort() },
-      );
-    }
-  }
-  return imported;
-}
-
-function checkpointKey(entry) {
-  return `${entry.stage}:${entry.scope_type}:${entry.scope_id}`;
-}
-
-function mergeTeamCheckpoints(db, entries, lastDigests = {}) {
-  let imported = 0;
-  for (const entry of entries) {
-    const current = db.prepare(
-      `SELECT * FROM stage_checkpoints
-       WHERE stage = ? AND scope_type = ? AND scope_id = ? AND status = 'accepted'
-       ORDER BY revision DESC LIMIT 1`,
-    ).get(entry.stage, entry.scope_type, entry.scope_id);
-    const currentDurable = current ? durableCheckpoint(current) : null;
-    if (currentDurable?.digest === entry.digest) continue;
-    const key = checkpointKey(entry);
-    const last = lastDigests[key] || null;
-    if (currentDurable && (!last || currentDurable.digest !== last)) {
-      throw new TaskLedgerError(
-        'TASK_LEDGER_CHECKPOINT_CONFLICT',
-        `checkpoint ${key} changed both locally and in the team ledger`,
-        {
-          checkpoint: key,
-          local_digest: currentDurable.digest,
-          incoming_digest: entry.digest,
-          last_digest: last,
-        },
-      );
-    }
-    if (current) {
-      db.prepare(
-        `UPDATE stage_checkpoints SET status = 'superseded',
-         updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
-         WHERE id = ?`,
-      ).run(current.id);
-    }
-    const importedId = `checkpoint-team-${entry.digest.slice(0, 24)}`;
-    const importedDigest = stageCheckpoints.checkpointDigest({
-      stage: entry.stage,
-      scope_type: entry.scope_type,
-      scope_id: entry.scope_id,
-      revision: entry.revision,
-      payload: entry.payload,
-      evidence: entry.evidence,
-      diagnostics: entry.diagnostics,
-      context_envelope_id: null,
-      supersedes_id: current?.id || null,
-    });
-    db.prepare(
-      `INSERT INTO stage_checkpoints
-       (id, stage, scope_type, scope_id, revision, status, payload_json,
-        evidence_json, diagnostics_json, context_envelope_id, digest,
-        supersedes_id, idempotency_key, accepted_at)
-       VALUES (?, ?, ?, ?, ?, 'accepted', ?, ?, ?, NULL, ?, ?, ?,
-               strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`,
-    ).run(
-      importedId,
-      entry.stage,
-      entry.scope_type,
-      entry.scope_id,
-      entry.revision,
-      JSON.stringify(entry.payload),
-      JSON.stringify(entry.evidence),
-      JSON.stringify(entry.diagnostics),
-      importedDigest,
-      current?.id || null,
-      `team-import:${entry.digest}`,
-    );
-    imported += 1;
-  }
-  return imported;
-}
-
-function importTaskLedger(db, {
-  rootDir = '.',
-} = {}) {
-  const document = readTaskLedger(rootDir, { optional: false });
-  const checkpoint = latestImportedCheckpoint(db);
-  const lastDigests = checkpoint.task_digests;
-  const lastChangeDigests = checkpoint.change_digests;
-  if (checkpoint.state_digest && checkpoint.state_digest !== document.state_digest) {
-    if (document.generation < checkpoint.generation) {
-      throw new TaskLedgerError(
-        'TASK_LEDGER_STALE',
-        `task ledger generation ${document.generation} is older than local generation ${checkpoint.generation}`,
-        {
-          incoming_generation: document.generation,
-          local_generation: checkpoint.generation,
-        },
-      );
-    }
-    if (document.generation === checkpoint.generation
-        || !document.ancestors.includes(checkpoint.state_digest)) {
-      throw new TaskLedgerError(
-        'TASK_LEDGER_HISTORY_CONFLICT',
-        'task ledger does not descend from the last local team checkpoint',
-        {
-          incoming_generation: document.generation,
-          local_generation: checkpoint.generation,
-          incoming_parent_digest: document.parent_digest,
-          local_state_digest: checkpoint.state_digest,
-        },
-      );
-    }
-  }
-  if (checkpoint.state_digest === document.state_digest) {
-    return {
-      imported: 0,
-      preserved: document.tasks.length,
-      deleted: 0,
-      imported_changes: 0,
-      preserved_changes: document.changes.length,
-      imported_decisions: 0,
-      preserved_decisions: document.decisions.length,
-      imported_checkpoints: 0,
-      preserved_checkpoints: document.checkpoints.length,
-      imported_baseline: false,
-      preserved_baseline: Boolean(document.baseline),
-      generation: document.generation,
-      state_digest: document.state_digest,
-      requires_plan_revalidation: false,
-      requires_baseline_revalidation: false,
-      already_current: true,
-      ledger: document,
-    };
-  }
-  const parentUpdates = [];
-  let imported = 0;
-  let preserved = 0;
-  let deleted = 0;
-  let importedChanges = 0;
-  let preservedChanges = 0;
-  let importedDecisions = 0;
-  let importedCheckpoints = 0;
-  let baselineImport = {
-    imported: false,
-    preserved: false,
-    requiresRevalidation: false,
-  };
-  const changesById = new Set((document.changes || []).map((change) => change.id));
-  for (const task of document.tasks) {
-    if (task.change_id && !changesById.has(task.change_id)
-        && !db.prepare('SELECT 1 FROM changes WHERE id = ?').get(task.change_id)) {
-      throw new TaskLedgerError(
-        'TASK_LEDGER_CHANGE_MISSING',
-        `task ${task.id} references missing change ${task.change_id}`,
-      );
-    }
-  }
-
-  ops.tx(db, () => {
-    baselineImport = mergeBaseline(db, document.baseline, checkpoint);
-    for (const incoming of document.changes) {
-      const row = db.prepare('SELECT * FROM changes WHERE id = ?').get(incoming.id);
-      if (!row) {
-        insertChange(db, incoming);
-        importedChanges += 1;
-        continue;
-      }
-      const current = durableChange(row, null);
-      const last = lastChangeDigests[incoming.id] || null;
-      if (current.digest === incoming.digest) {
-        preservedChanges += 1;
-        continue;
-      }
-      if (!last) {
-        throw new TaskLedgerError(
-          'TASK_LEDGER_CHANGE_CONFLICT',
-          `Change ${incoming.id} exists locally without a common team checkpoint`,
-          {
-            change_id: incoming.id,
-            local_digest: current.digest,
-            incoming_digest: incoming.digest,
-          },
-        );
-      }
-      if (current.digest !== last && incoming.digest === last) {
-        preservedChanges += 1;
-        continue;
-      }
-      if (current.digest !== last && incoming.digest !== last) {
-        throw new TaskLedgerError(
-          'TASK_LEDGER_CHANGE_CONFLICT',
-          `Change ${incoming.id} changed both locally and in the Git ledger`,
-          {
-            change_id: incoming.id,
-            last_digest: last,
-            local_digest: current.digest,
-            incoming_digest: incoming.digest,
-          },
-        );
-      }
-      updateChangeFromLedger(db, incoming);
-      importedChanges += 1;
-    }
-    for (const incoming of document.tasks) {
-      const current = ops.readTask(db, incoming.id);
-      const last = lastDigests[incoming.id] || null;
-      if (!current) {
-        insertTaskFromLedger(db, incoming);
-        parentUpdates.push([incoming.id, incoming.parent_id || null]);
-        imported += 1;
-        continue;
-      }
-      const currentDurable = durableTask(current, null);
-      if (currentDurable.digest === incoming.digest) {
-        preserved += 1;
-        parentUpdates.push([incoming.id, incoming.parent_id || null]);
-        continue;
-      }
-      const runningSession = db.prepare(
-        "SELECT sid FROM sessions WHERE task_id = ? AND status = 'running' LIMIT 1",
-      ).get(incoming.id);
-      if (current.session_id || runningSession) {
-        throw new TaskLedgerError(
-          'TASK_LEDGER_ACTIVE_TASK_CONFLICT',
-          `task ${incoming.id} changed in Git while a local session still owns it`,
-          {
-            task_id: incoming.id,
-            local_status: current.status,
-            task_session_id: current.session_id || null,
-            running_session_id: runningSession?.sid || null,
-          },
-        );
-      }
-      if (current.status === 'in_progress' && last && incoming.digest !== last) {
-        throw new TaskLedgerError(
-          'TASK_LEDGER_ACTIVE_TASK_CONFLICT',
-          `task ${incoming.id} changed in Git while a local session is in progress`,
-          { task_id: incoming.id, local_status: current.status },
-        );
-      }
-      if (last && currentDurable.digest !== last && incoming.digest === last) {
-        preserved += 1;
-        continue;
-      }
-      if (last && currentDurable.digest !== last && incoming.digest !== last) {
-        throw new TaskLedgerError(
-          'TASK_LEDGER_CONFLICT',
-          `task ${incoming.id} changed both locally and in the Git ledger`,
-          {
-            task_id: incoming.id,
-            last_digest: last,
-            local_digest: currentDurable.digest,
-            incoming_digest: incoming.digest,
-          },
-        );
-      }
-      updateTaskFromLedger(db, incoming);
-      parentUpdates.push([incoming.id, incoming.parent_id || null]);
-      imported += 1;
-    }
-    const incomingIds = new Set(document.tasks.map((task) => task.id));
-    for (const [id, last] of Object.entries(lastDigests)) {
-      if (incomingIds.has(id)) continue;
-      const current = ops.readTask(db, id);
-      if (!current) continue;
-      const activeSession = db.prepare(
-        "SELECT sid FROM sessions WHERE task_id = ? AND status = 'running' LIMIT 1",
-      ).get(id);
-      if (current.status === 'in_progress' || current.session_id || activeSession) {
-        throw new TaskLedgerError(
-          'TASK_LEDGER_ACTIVE_TASK_CONFLICT',
-          `task ${id} was removed from Git while local work is in progress`,
-          { task_id: id, local_status: current.status },
-        );
-      }
-      const currentDurable = durableTask(current, null);
-      if (currentDurable.digest !== last) {
-        throw new TaskLedgerError(
-          'TASK_LEDGER_CONFLICT',
-          `task ${id} was removed from Git after it changed locally`,
-          {
-            task_id: id,
-            last_digest: last,
-            local_digest: currentDurable.digest,
-            incoming_digest: null,
-          },
-        );
-      }
-      const sessionCount = db.prepare(
-        'SELECT COUNT(*) AS count FROM sessions WHERE task_id = ?',
-      ).get(id).count;
-      if (sessionCount > 0) {
-        throw new TaskLedgerError(
-          'TASK_LEDGER_CONFLICT',
-          `task ${id} cannot be removed because local session history still references it`,
-          { task_id: id, session_count: sessionCount },
-        );
-      }
-      ops.deleteTask(db, id, { rootDir });
-      deleted += 1;
-    }
-    for (const [id, parentId] of parentUpdates) {
-      if (parentId && !db.prepare('SELECT 1 FROM tasks WHERE id = ?').get(parentId)) {
-        throw new TaskLedgerError(
-          'TASK_LEDGER_PARENT_MISSING',
-          `task ${id} references missing parent ${parentId}`,
-        );
-      }
-      db.prepare('UPDATE tasks SET parent_id = ? WHERE id = ?').run(parentId, id);
-    }
-    importedDecisions = mergeTeamDecisions(db, rootDir, document.decisions);
-    importedCheckpoints = mergeTeamCheckpoints(
-      db,
-      document.checkpoints,
-      checkpoint.checkpoint_digests,
-    );
-    recordLedgerEvent(db, 'task_ledger_imported', document, {
-      imported,
-      preserved,
-      deleted,
-      imported_changes: importedChanges,
-      preserved_changes: preservedChanges,
-      imported_decisions: importedDecisions,
-      imported_checkpoints: importedCheckpoints,
-    });
-  });
-  return {
-    imported,
-    preserved,
-    deleted,
-    imported_changes: importedChanges,
-    preserved_changes: preservedChanges,
-    imported_decisions: importedDecisions,
-    preserved_decisions: document.decisions.length - importedDecisions,
-    imported_checkpoints: importedCheckpoints,
-    preserved_checkpoints: document.checkpoints.length - importedCheckpoints,
-    imported_baseline: baselineImport.imported,
-    preserved_baseline: baselineImport.preserved,
-    generation: document.generation,
-    state_digest: document.state_digest,
-    requires_plan_revalidation: imported > 0
-      || deleted > 0
-      || importedChanges > 0
-      || baselineImport.imported,
-    requires_baseline_revalidation: baselineImport.requiresRevalidation,
-    already_current: false,
-    ledger: document,
-  };
-}
-
-function inspectTaskLedger(db, { rootDir = '.' } = {}) {
-  const document = readTaskLedger(rootDir);
-  if (!document) {
-    return {
-      status: 'missing',
-      path: ledgerPath(rootDir),
-      generation: null,
-      state_digest: null,
-    };
-  }
-  const localTasks = ops.listTasks(db, { status: 'any', limit: 1000 });
-  const previous = new Map(document.tasks.map((task) => [task.id, task]));
-  const local = localTasks.map((task) => durableTask(task, previous.get(task.id)))
-    .sort((left, right) => left.id.localeCompare(right.id));
-  const localChanges = readChangesForLedger(
-    db,
-    localTasks,
-    new Map(document.changes.map((change) => [change.id, change])),
-  );
-  const localDecisions = readDecisionsForLedger(db);
-  const localCheckpoints = readCheckpointsForLedger(db);
-  const localBaseline = readBaselineForLedger(db, document.baseline || null);
-  const localDigest = sha256(statePayload({
-    baseline: localBaseline,
-    changes: localChanges,
-    decisions: localDecisions,
-    checkpoints: localCheckpoints,
-    tasks: local,
-  }));
-  const baselineRequiresRevalidation = Array.isArray(localBaseline?.gaps)
-    && localBaseline.gaps.some((gap) => (
-      gap.id === 'team-ledger-revalidation-required' && gap.status === 'open'
-    ));
-  const importedPayloadDigest = baselineRequiresRevalidation
-    ? sha256(statePayload({
-      baseline: document.baseline,
-      changes: localChanges,
-      decisions: localDecisions,
-      checkpoints: localCheckpoints,
-      tasks: local,
-    }))
-    : null;
-  const status = localDigest === document.state_digest
-    ? 'current'
-    : (importedPayloadDigest === document.state_digest
-      ? 'revalidation_required'
-      : 'drifted');
-  return {
-    status,
-    path: ledgerPath(rootDir),
-    generation: document.generation,
-    state_digest: document.state_digest,
-    local_state_digest: localDigest,
-    baseline_revalidation_required: baselineRequiresRevalidation,
-  };
-}
-
-module.exports = {
-  DURABLE_BASELINE_FIELDS,
-  DURABLE_CHANGE_FIELDS,
-  DURABLE_CHECKPOINT_FIELDS,
-  DURABLE_DECISION_FIELDS,
-  DURABLE_TASK_FIELDS,
-  LEDGER_KIND,
-  LEDGER_RELATIVE_PATH,
-  LEDGER_SCHEMA_VERSION,
-  TaskLedgerError,
-  durableChange,
-  durableCheckpoint,
-  durableDecision,
-  durableBaseline,
-  durableTask,
-  importTaskLedger,
-  inspectTaskLedger,
-  ledgerPath,
-  publishTaskLedger,
-  readTaskLedger,
-  rollbackTaskLedgerPublication,
-  syncTaskLedger,
-  validateLedger,
-};