ultra-builder-pro-cli 0.13.0 → 0.15.0

package/mcp-server/lib/projector.cjs

@@ -16,8 +16,11 @@ const SCHEMA_VERSION = '4.5';
 const SOURCE_TAG = '.ultra/state.db';
 
 // Frozen SELECTs — values bind through @placeholders.
-const LIST_TASKS_FOR_PROJECTION_SQL = "SELECT id, title, type, priority, complexity, estimated_days, status, deps, files_modified, session_id, stale, complexity_hint, tag, trace_to, context_file, completion_commit, created_at, updated_at FROM tasks ORDER BY created_at ASC";
-const READ_TASK_FOR_PROJECTION_SQL = "SELECT id, title, type, priority, complexity, estimated_days, status, deps, files_modified, session_id, stale, complexity_hint, tag, trace_to, context_file, completion_commit, created_at, updated_at FROM tasks WHERE id = @id";
+const TASK_PROJECTION_COLUMNS = 'id, title, type, priority, complexity, estimated_days, status, deps, files_modified, session_id, stale, tag, trace_to, outcome, slice_kind, public_seam, verification_command, acceptance_json, context_refs_json, docs_impact_json, ownership_json, context_file, completion_commit, created_at, updated_at';
+const LIST_TASKS_FOR_PROJECTION_SQL = `SELECT ${TASK_PROJECTION_COLUMNS} FROM tasks ORDER BY created_at ASC`;
+const READ_TASK_FOR_PROJECTION_SQL = `SELECT ${TASK_PROJECTION_COLUMNS} FROM tasks WHERE id = @id`;
+const CONTRACT_START = '<!-- ultra:task-contract:start -->';
+const CONTRACT_END = '<!-- ultra:task-contract:end -->';
 
 function rowToProjection(row) {
   if (!row) return null;
@@ -28,6 +31,17 @@ function rowToProjection(row) {
     }
     if (out[k] === null || out[k] === undefined) delete out[k];
   }
+  const jsonFields = {
+    acceptance_json: ['acceptance', []],
+    context_refs_json: ['context_refs', []],
+    docs_impact_json: ['docs_impact', { status: 'unknown', files: [], rationale: null }],
+    ownership_json: ['ownership', {}],
+  };
+  for (const [column, [field, fallback]] of Object.entries(jsonFields)) {
+    try { out[field] = typeof out[column] === 'string' ? JSON.parse(out[column]) : fallback; }
+    catch { out[field] = fallback; }
+    delete out[column];
+  }
   if (out.stale !== undefined && out.stale !== null) out.stale = Boolean(out.stale);
   for (const k of Object.keys(out)) {
     if (out[k] === null || out[k] === undefined) delete out[k];
@@ -94,17 +108,57 @@ function buildContextDoc(taskRow, existingBody) {
   body = body.replace(/^>\s*\*\*Status\*\*:.*(?:\r?\n|$)(?:\r?\n)?/mi, '');
   // Strip any previous STALE banner so re-projection after reset is clean.
   body = body.replace(/^> ⚠️\s*STALE[^\n]*\n(?:>[^\n]*\n)*\n?/m, '');
+  body = body.replace(
+    new RegExp(`${CONTRACT_START}[\\s\\S]*?${CONTRACT_END}\\n*`, 'm'),
+    '',
+  );
   if (taskRow.stale) {
     const banner = [
       `> ⚠️ STALE since ${taskRow.updated_at || new Date().toISOString()}`,
-      '> spec 改动可能让此 task 上下文失效；重新跑 spec 对齐后再继续。',
+      '> Specification evidence may have changed. Recompile the task context before continuing.',
       '',
     ].join('\n');
     body = banner + body;
   }
+  body = buildTaskContract(taskRow) + body;
   return headerLines.join('\n') + body;
 }
 
+function buildTaskContract(task) {
+  const acceptance = Array.isArray(task.acceptance) ? task.acceptance : [];
+  const refs = Array.isArray(task.context_refs) ? task.context_refs : [];
+  const docs = task.docs_impact || { status: 'unknown', files: [], rationale: null };
+  const ownership = task.ownership || {};
+  const lines = [
+    CONTRACT_START,
+    '## Execution Contract (generated from state.db)',
+    '',
+    `- Outcome: ${task.outcome || 'unresolved'}`,
+    `- Slice: ${task.slice_kind || 'unresolved'}`,
+    `- Public seam: ${task.public_seam || 'unresolved'}`,
+    `- Verification: ${task.verification_command || 'unresolved'}`,
+    `- Trace: ${task.trace_to || 'unresolved'}`,
+    `- Owner: ${ownership.owner || 'unresolved'}`,
+    `- Documentation: ${docs.status || 'unknown'}${docs.rationale ? ` — ${docs.rationale}` : ''}`,
+    '',
+    '### Acceptance',
+    '',
+    ...(acceptance.length > 0
+      ? acceptance.map((item) => `- ${item.id}: ${item.criterion} — verify with \`${item.verification}\``)
+      : ['- unresolved']),
+    '',
+    '### Context References',
+    '',
+    ...(refs.length > 0
+      ? refs.map((item) => `- \`${item.ref}\` — ${item.reason}`)
+      : ['- unresolved']),
+    '',
+    CONTRACT_END,
+    '',
+  ];
+  return lines.join('\n');
+}
+
 function escapeYaml(str) {
   if (str == null) return '';
   if (/[:#\[\]\{\}&\*!|>'"%@`]/.test(str) || /^\s|\s$/.test(str)) {

package/mcp-server/lib/spec-learning.cjs

@@ -33,8 +33,14 @@ function rowToCandidate(row) {
   catch (error) {
     throw new SpecLearningError('STATE_CORRUPT', `invalid spec-learning evidence: ${error.message}`);
   }
-  const candidate = { ...row, evidence };
+  let applyEvidence;
+  try { applyEvidence = JSON.parse(row.apply_evidence_json || '[]'); }
+  catch (error) {
+    throw new SpecLearningError('STATE_CORRUPT', `invalid spec-learning apply evidence: ${error.message}`);
+  }
+  const candidate = { ...row, evidence, apply_evidence: applyEvidence };
   delete candidate.evidence_json;
+  delete candidate.apply_evidence_json;
   return candidate;
 }
 
@@ -102,6 +108,66 @@ function normalizeEvidence(value) {
   return [...new Set(value.map((entry) => entry.trim()))];
 }
 
+function targetFile(rootDir, targetRef) {
+  const separator = String(targetRef || '').lastIndexOf('#');
+  if (separator <= 0 || separator === targetRef.length - 1) {
+    throw new SpecLearningError('VALIDATION_ERROR', 'target_ref must use project-relative path#anchor');
+  }
+  const relative = targetRef.slice(0, separator);
+  if (path.isAbsolute(relative)) {
+    throw new SpecLearningError('VALIDATION_ERROR', 'target_ref must be project-relative');
+  }
+  const root = path.resolve(rootDir);
+  const file = path.resolve(root, relative);
+  if (file !== root && !file.startsWith(`${root}${path.sep}`)) {
+    throw new SpecLearningError('VALIDATION_ERROR', 'target_ref escapes the project root');
+  }
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
+    throw new SpecLearningError('LEARNING_TARGET_MISSING', `target file does not exist: ${relative}`);
+  }
+  return { file, relative };
+}
+
+function digestFile(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+function verifyApplyEvidence(input, current, rootDir) {
+  const appliedRef = typeof input.applied_ref === 'string' ? input.applied_ref.trim() : '';
+  const beforeDigest = typeof input.before_digest === 'string' ? input.before_digest.trim() : '';
+  const afterDigest = typeof input.after_digest === 'string' ? input.after_digest.trim() : '';
+  const evidence = normalizeEvidence(input.apply_evidence);
+  if (appliedRef !== current.target_ref || !/^[0-9a-f]{64}$/.test(beforeDigest)
+    || !/^[0-9a-f]{64}$/.test(afterDigest) || beforeDigest === afterDigest
+    || evidence.length === 0) {
+    throw new SpecLearningError(
+      'LEARNING_APPLY_EVIDENCE_REQUIRED',
+      'apply requires the exact target ref, distinct before/after digests, and durable evidence refs',
+    );
+  }
+  if (current.before_digest && current.before_digest !== beforeDigest) {
+    throw new SpecLearningError(
+      'LEARNING_APPLY_EVIDENCE_MISMATCH', 'before_digest does not match the proposed target state',
+    );
+  }
+  const target = targetFile(rootDir, appliedRef);
+  if (digestFile(target.file) !== afterDigest) {
+    throw new SpecLearningError(
+      'LEARNING_APPLY_EVIDENCE_MISMATCH', 'after_digest does not match the current target file',
+    );
+  }
+  const workflows = require('./workflow-state.cjs');
+  try {
+    workflows.resolveProjectSourceRef(rootDir, appliedRef, 'applied_ref');
+    for (const ref of evidence) workflows.resolveProjectSourceRef(rootDir, ref, 'apply_evidence');
+  } catch (error) {
+    throw new SpecLearningError(
+      'LEARNING_APPLY_EVIDENCE_MISMATCH', `applied target or evidence anchor is invalid: ${error.message}`,
+    );
+  }
+  return { appliedRef, beforeDigest, afterDigest, evidence };
+}
+
 function proposeSpecLearning(db, input, { rootDir = process.cwd() } = {}) {
   const change = mutableChange(db, input.change_id);
   const id = String(input.id || `learning-${crypto.randomUUID().slice(0, 12)}`).trim();
@@ -120,6 +186,8 @@ function proposeSpecLearning(db, input, { rootDir = process.cwd() } = {}) {
     }
   }
   const evidence = normalizeEvidence(input.evidence);
+  const proposedTarget = targetFile(rootDir, targetRef);
+  const proposedDigest = digestFile(proposedTarget.file);
   const proposedAt = nowIso();
   return ops.tx(db, () => {
     try {
@@ -128,6 +196,9 @@ function proposeSpecLearning(db, input, { rootDir = process.cwd() } = {}) {
          (id, change_id, task_id, target_ref, summary, evidence_json, proposed_at)
          VALUES (?, ?, ?, ?, ?, ?, ?)`,
       ).run(id, change.id, input.task_id || null, targetRef, summary, JSON.stringify(evidence), proposedAt);
+      db.prepare(
+        'UPDATE spec_learning_candidates SET before_digest = ? WHERE id = ? AND change_id = ?',
+      ).run(proposedDigest, id, change.id);
     } catch (error) {
       if (String(error.message).includes('UNIQUE')) {
         throw new SpecLearningError('DUPLICATE_LEARNING_ID', `spec-learning candidate ${id} exists`);
@@ -164,13 +235,19 @@ function resolveSpecLearning(db, input, { rootDir = process.cwd() } = {}) {
     throw new SpecLearningError('VALIDATION_ERROR', `${input.decision} requires a resolution`);
   }
   const timestamp = nowIso();
+  const application = status === 'applied'
+    ? verifyApplyEvidence(input, current, rootDir)
+    : null;
   return ops.tx(db, () => {
     db.prepare(
       `UPDATE spec_learning_candidates
-       SET status = ?, resolution = ?, resolved_at = ?, applied_at = ?
+       SET status = ?, resolution = ?, resolved_at = ?, applied_at = ?, applied_ref = ?,
+       before_digest = COALESCE(?, before_digest), after_digest = ?, apply_evidence_json = ?
        WHERE id = ? AND change_id = ?`,
     ).run(
       status, resolution || null, timestamp, status === 'applied' ? timestamp : null,
+      application?.appliedRef || null, application?.beforeDigest || null,
+      application?.afterDigest || null, JSON.stringify(application?.evidence || []),
       current.id, change.id,
     );
     ops.appendEventInTx(db, {

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

@@ -9,10 +9,13 @@ const REPO_ROOT = process.env.UBP_RUNTIME_ROOT
   ? path.resolve(process.env.UBP_RUNTIME_ROOT)
   : path.resolve(__dirname, '..', '..');
 const SCHEMA_FILE = path.join(REPO_ROOT, 'spec', 'schemas', 'state-db.sql');
-const EXPECTED_VERSION = '12.0';
+const EXPECTED_VERSION = '15.0';
 const KIMI_SCHEMA_VERSION = '9.1';
 const CONTEXT_SCHEMA_VERSION = '10.0';
 const BASELINE_SCHEMA_VERSION = '11.0';
+const ADOPTION_SCHEMA_VERSION = '12.0';
+const WORKFLOW_SCHEMA_VERSION = '13.0';
+const AUTHORITY_SCHEMA_VERSION = '14.0';
 
 const MIGRATED_GAPS = Object.freeze([{
   id: 'legacy-rebaseline-required',
@@ -42,6 +45,8 @@ const REQUIRED_TABLES = Object.freeze([
   'incidents',
   'projection_jobs',
   'event_consumers',
+  'workflow_runs',
+  'workflow_steps',
 ]);
 
 function applyBaselineUpgrade(db, { legacyState = false } = {}) {
@@ -63,6 +68,7 @@ function applyBaselineUpgrade(db, { legacyState = false } = {}) {
       worktree_digest     TEXT,
       worktree_files_json TEXT NOT NULL DEFAULT '[]',
       worktree_accepted   INTEGER NOT NULL DEFAULT 0 CHECK (worktree_accepted IN (0, 1)),
+      known_red_accepted  INTEGER NOT NULL DEFAULT 0 CHECK (known_red_accepted IN (0, 1)),
       spec_refs_json      TEXT NOT NULL DEFAULT '[]',
       evidence_json       TEXT NOT NULL DEFAULT '[]',
       verification_json   TEXT NOT NULL DEFAULT '[]',
@@ -70,6 +76,7 @@ function applyBaselineUpgrade(db, { legacyState = false } = {}) {
       gaps_json           TEXT NOT NULL DEFAULT '[]',
       classification_json TEXT NOT NULL DEFAULT '{}',
       provider_refs_json  TEXT NOT NULL DEFAULT '{}',
+      research_run_id     TEXT,
       approved_by         TEXT,
       approval_note       TEXT,
       started_at          TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
@@ -114,17 +121,51 @@ function applyBaselineColumns(db) {
     db, 'baselines', columns, 'worktree_accepted',
     'INTEGER NOT NULL DEFAULT 0 CHECK (worktree_accepted IN (0, 1))',
   ) || changed;
+  changed = addColumnIfMissing(
+    db, 'baselines', columns, 'known_red_accepted',
+    'INTEGER NOT NULL DEFAULT 0 CHECK (known_red_accepted IN (0, 1))',
+  ) || changed;
   changed = addColumnIfMissing(db, 'baselines', columns, 'gaps_json', "TEXT NOT NULL DEFAULT '[]'") || changed;
   changed = addColumnIfMissing(
     db, 'baselines', columns, 'classification_json', "TEXT NOT NULL DEFAULT '{}'",
   ) || changed;
+  changed = addColumnIfMissing(db, 'baselines', columns, 'research_run_id', 'TEXT') || changed;
   return changed;
 }
 
 function applyChangeColumns(db) {
   if (!tableNames(db).includes('changes')) return false;
   const columns = columnNames(db, 'changes');
-  return addColumnIfMissing(db, 'changes', columns, 'baseline_bypass_json', 'TEXT');
+  let changed = false;
+  changed = addColumnIfMissing(db, 'changes', columns, 'baseline_bypass_json', 'TEXT') || changed;
+  changed = addColumnIfMissing(db, 'changes', columns, 'contract_json', "TEXT NOT NULL DEFAULT '{}'") || changed;
+  changed = addColumnIfMissing(db, 'changes', columns, 'classification_json', "TEXT NOT NULL DEFAULT '{}'") || changed;
+  changed = addColumnIfMissing(
+    db, 'changes', columns, 'research_disposition_json', "TEXT NOT NULL DEFAULT '{}'",
+  ) || changed;
+  return changed;
+}
+
+function applySemanticAuthorityColumns(db) {
+  let changed = false;
+  if (tableNames(db).includes('workflow_steps')) {
+    const columns = columnNames(db, 'workflow_steps');
+    changed = addColumnIfMissing(
+      db, 'workflow_steps', columns, 'semantic_records_json', "TEXT NOT NULL DEFAULT '[]'",
+    ) || changed;
+  }
+  if (tableNames(db).includes('spec_learning_candidates')) {
+    const columns = columnNames(db, 'spec_learning_candidates');
+    for (const [name, definition] of [
+      ['applied_ref', 'TEXT'],
+      ['before_digest', 'TEXT'],
+      ['after_digest', 'TEXT'],
+      ['apply_evidence_json', "TEXT NOT NULL DEFAULT '[]'"],
+    ]) {
+      changed = addColumnIfMissing(db, 'spec_learning_candidates', columns, name, definition) || changed;
+    }
+  }
+  return changed;
 }
 
 function quoteSqlString(value) {
@@ -151,7 +192,14 @@ function readSchemaSql() {
 }
 
 function applyPragmas(db) {
-  db.pragma('journal_mode = WAL');
+  const journalMode = db.pragma('journal_mode = WAL', { simple: true });
+  if (String(journalMode).toLowerCase() !== 'wal') {
+    const error = new Error(
+      `state.db requires SQLite WAL mode; storage returned ${String(journalMode || 'unknown')}`,
+    );
+    error.code = 'STATE_DB_WAL_UNAVAILABLE';
+    throw error;
+  }
   db.pragma('synchronous = NORMAL');
   db.pragma('busy_timeout = 5000');
   db.pragma('foreign_keys = ON');
@@ -202,6 +250,19 @@ function applyCompatibleColumns(db) {
   if (!taskColumns.has('change_id')) {
     db.exec('ALTER TABLE tasks ADD COLUMN change_id TEXT REFERENCES changes(id) ON DELETE SET NULL');
   }
+  const taskAdditions = [
+    ['outcome', 'TEXT'],
+    ['slice_kind', "TEXT CHECK (slice_kind IS NULL OR slice_kind IN ('tracer_bullet', 'expand_contract', 'integration_checkpoint'))"],
+    ['public_seam', 'TEXT'],
+    ['verification_command', 'TEXT'],
+    ['acceptance_json', "TEXT NOT NULL DEFAULT '[]'"],
+    ['context_refs_json', "TEXT NOT NULL DEFAULT '[]'"],
+    ['docs_impact_json', "TEXT NOT NULL DEFAULT '{\"status\":\"unknown\",\"files\":[],\"rationale\":null}'"],
+    ['ownership_json', "TEXT NOT NULL DEFAULT '{}'"],
+  ];
+  for (const [name, definition] of taskAdditions) {
+    if (!taskColumns.has(name)) db.exec(`ALTER TABLE tasks ADD COLUMN ${name} ${definition}`);
+  }
   if (tables.has('events')) {
     const eventColumns = columnNames(db, 'events');
     if (!eventColumns.has('change_id')) db.exec('ALTER TABLE events ADD COLUMN change_id TEXT');
@@ -339,7 +400,10 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
       "SELECT 1 FROM migration_history WHERE to_version = '10.0' AND status = 'success' LIMIT 1",
     ).get();
     const needsContextMigration = Boolean(
-      fromVersion && ![CONTEXT_SCHEMA_VERSION, BASELINE_SCHEMA_VERSION, EXPECTED_VERSION].includes(fromVersion)
+      fromVersion && ![
+        CONTEXT_SCHEMA_VERSION, BASELINE_SCHEMA_VERSION, ADOPTION_SCHEMA_VERSION,
+        WORKFLOW_SCHEMA_VERSION, AUTHORITY_SCHEMA_VERSION, EXPECTED_VERSION,
+      ].includes(fromVersion)
         && !contextMigration,
     );
     if (contextChanged || needsContextMigration) {
@@ -356,10 +420,14 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
     applyBaselineUpgrade(db, { legacyState });
     applyBaselineColumns(db);
     applyChangeColumns(db);
+    applySemanticAuthorityColumns(db);
     const baselineMigration = db.prepare(
       "SELECT 1 FROM migration_history WHERE to_version = '11.0' AND status = 'success' LIMIT 1",
     ).get();
-    if (fromVersion && ![BASELINE_SCHEMA_VERSION, EXPECTED_VERSION].includes(fromVersion)
+    if (fromVersion && ![
+      BASELINE_SCHEMA_VERSION, ADOPTION_SCHEMA_VERSION, WORKFLOW_SCHEMA_VERSION,
+      AUTHORITY_SCHEMA_VERSION, EXPECTED_VERSION,
+    ].includes(fromVersion)
       && !baselineMigration) {
       db.prepare(
         `INSERT INTO migration_history
@@ -372,6 +440,32 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
       );
     }
     if (legacyState) {
+      const legacyBaselines = db.prepare(
+        "SELECT id, mode, status, classification_json, gaps_json FROM baselines WHERE status != 'superseded'",
+      ).all();
+      for (const baseline of legacyBaselines) {
+        let classification = {};
+        let gaps = [];
+        try { classification = JSON.parse(baseline.classification_json || '{}'); } catch { classification = {}; }
+        try { gaps = JSON.parse(baseline.gaps_json || '[]'); } catch { gaps = []; }
+        if (!gaps.some((gap) => gap?.id === MIGRATED_GAPS[0].id)) gaps.push(MIGRATED_GAPS[0]);
+        classification.migration = {
+          previous_mode: baseline.mode,
+          previous_status: baseline.status,
+          from_schema: fromVersion || 'unknown',
+          requires_research_workflow: true,
+        };
+        db.prepare(
+          `UPDATE baselines SET mode = 'migrated', status = 'adopting',
+           classification_json = ?, gaps_json = ?, approved_by = NULL, approval_note = ?,
+           converged_at = NULL, research_run_id = NULL, updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+           WHERE id = ?`,
+        ).run(
+          JSON.stringify(classification), JSON.stringify(gaps),
+          'Legacy project preserved; evidence-backed brownfield re-adoption is required',
+          baseline.id,
+        );
+      }
       db.prepare(
         `UPDATE baselines SET status = 'adopting', approved_by = NULL, approval_note = ?,
          converged_at = NULL, worktree_state = 'unavailable', worktree_digest = NULL,
@@ -393,18 +487,60 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
            VALUES (?, ?, 'forward', 'success', ?)`,
         ).run(
           BASELINE_SCHEMA_VERSION,
-          EXPECTED_VERSION,
+          ADOPTION_SCHEMA_VERSION,
           'Add repository snapshots, authoritative gap ledger, incident governance, and required re-adoption',
         );
       }
     }
+    const workflowMigration = db.prepare(
+      "SELECT 1 FROM migration_history WHERE to_version = '13.0' AND status = 'success' LIMIT 1",
+    ).get();
+    if (fromVersion && fromVersion !== EXPECTED_VERSION && !workflowMigration) {
+      db.prepare(
+        `INSERT INTO migration_history
+          (from_version, to_version, direction, status, notes)
+         VALUES (?, ?, 'forward', 'success', ?)`,
+      ).run(
+        fromVersion === ADOPTION_SCHEMA_VERSION ? fromVersion : ADOPTION_SCHEMA_VERSION,
+        WORKFLOW_SCHEMA_VERSION,
+        'Add durable cross-stage workflow runs, step evidence, output digests, blockers, and recovery',
+      );
+    }
+    const authorityMigration = db.prepare(
+      "SELECT 1 FROM migration_history WHERE to_version = '14.0' AND status = 'success' LIMIT 1",
+    ).get();
+    if (fromVersion && fromVersion !== EXPECTED_VERSION && !authorityMigration) {
+      db.prepare(
+        `INSERT INTO migration_history
+          (from_version, to_version, direction, status, notes)
+         VALUES (?, ?, 'forward', 'success', ?)`,
+      ).run(
+        fromVersion === WORKFLOW_SCHEMA_VERSION ? fromVersion : WORKFLOW_SCHEMA_VERSION,
+        AUTHORITY_SCHEMA_VERSION,
+        'Persist known-red acceptance and continuously revalidate ready baseline authority',
+      );
+    }
+    const semanticMigration = db.prepare(
+      "SELECT 1 FROM migration_history WHERE to_version = '15.0' AND status = 'success' LIMIT 1",
+    ).get();
+    if (fromVersion && fromVersion !== EXPECTED_VERSION && !semanticMigration) {
+      db.prepare(
+        `INSERT INTO migration_history
+          (from_version, to_version, direction, status, notes)
+         VALUES (?, ?, 'forward', 'success', ?)`,
+      ).run(
+        fromVersion === AUTHORITY_SCHEMA_VERSION ? fromVersion : AUTHORITY_SCHEMA_VERSION,
+        EXPECTED_VERSION,
+        'Add typed research semantics, complete change contracts, verified learning application, and reconciliation provenance',
+      );
+    }
     db.exec('CREATE INDEX IF NOT EXISTS tasks_change ON tasks(change_id) WHERE change_id IS NOT NULL');
     db.exec('CREATE INDEX IF NOT EXISTS events_change ON events(change_id, id)');
     db.prepare(
       'INSERT OR IGNORE INTO schema_version (version, description) VALUES (?, ?)',
     ).run(
       EXPECTED_VERSION,
-      'Evidence-backed repository snapshots, gap ledger, safe re-adoption, and incident break-glass governance',
+      'Typed research semantics, complete change contracts, verified learning application, and reconciliation provenance',
     );
   })();
 }
@@ -431,7 +567,8 @@ function initStateDb(dbPath) {
     db = openStateDb(dbPath);
     const existing = new Set(tableNames(db));
     const fromVersion = latestSchemaVersion(db);
-    const legacyState = existing.size > 0 && fromVersion !== EXPECTED_VERSION;
+    const legacyState = existing.size > 0
+      && ![WORKFLOW_SCHEMA_VERSION, AUTHORITY_SCHEMA_VERSION, EXPECTED_VERSION].includes(fromVersion);
     backupPath = migrationBackup(db, dbPath, fromVersion, existing);
     applyCompatibleColumns(db);
     const missing = REQUIRED_TABLES.filter((t) => !existing.has(t));