gsd-pi 2.80.0 → 2.81.0-dev.3cddbbba2

package/dist/resources/extensions/gsd/gsd-db.js

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: GSD database facade, schema, migrations, and single-writer write API.
 // GSD Database Abstraction Layer
 // Provides a SQLite database with provider fallback chain:
 //   node:sqlite (built-in) → better-sqlite3 (npm) → null (unavailable)
@@ -20,269 +22,38 @@
 // intentionally independent store for cross-worktree claim races and is
 // excluded from this invariant.
 import { createRequire } from "node:module";
+import { createHash } from "node:crypto";
 import { existsSync, copyFileSync, mkdirSync, realpathSync } from "node:fs";
 import { dirname } from "node:path";
 import { GSDError, GSD_STALE_STATE } from "./errors.js";
 import { getGateIdsForTurn } from "./gate-registry.js";
 import { logError, logWarning } from "./workflow-logger.js";
+import { createDbAdapter } from "./db-adapter.js";
+import { createBaseSchemaObjects } from "./db-base-schema.js";
+import { createCoordinationTablesV24 } from "./db-coordination-schema.js";
+import { createDbConnectionCache } from "./db-connection-cache.js";
+import { emptyTaskStatusCounts, rowToActiveTaskSummary, rowToIdStatusSummary, rowToTaskStatusCounts, rowsToStringColumn, } from "./db-lightweight-query-rows.js";
+import { rowToActiveDecision, rowToActiveRequirement, rowToDecision, rowToRequirement, rowsToRequirementCounts, } from "./db-decision-requirement-rows.js";
+import { rowToGate } from "./db-gate-rows.js";
+import { rowToArtifact, rowToMilestone } from "./db-milestone-artifact-rows.js";
+import { backupDatabaseBeforeMigration } from "./db-migration-backup.js";
+import { applyMigrationV2Artifacts, applyMigrationV3Memories, applyMigrationV4DecisionMadeBy, applyMigrationV5HierarchyTables, applyMigrationV6SliceSummaries, applyMigrationV7Dependencies, applyMigrationV8PlanningFields, applyMigrationV9Ordering, applyMigrationV10ReplanTrigger, applyMigrationV11TaskPlanning, applyMigrationV12QualityGates, applyMigrationV13HotPathIndexes, applyMigrationV14SliceDependencies, applyMigrationV15AuditTables, applyMigrationV16EscalationSource, applyMigrationV17TaskEscalation, applyMigrationV18MemorySources, applyMigrationV19MemoryFts, applyMigrationV20MemoryRelations, applyMigrationV21StructuredMemories, applyMigrationV22QualityGateRepair, applyMigrationV23MilestoneQueue, applyMigrationV26MilestoneCommitAttributions, applyMigrationV27ArtifactHash, applyMigrationV28MemoryLastHitAt, } from "./db-migration-steps.js";
+import { isMemoriesFtsAvailableSchema, tryCreateMemoriesFtsSchema } from "./db-memory-fts-schema.js";
+import { createDbOpenState } from "./db-open-state.js";
+import { createRuntimeKvTableV25 } from "./db-runtime-kv-schema.js";
+import { getCurrentSchemaVersion, recordSchemaVersion } from "./db-schema-metadata.js";
+import { rowToSlice, rowToTask } from "./db-task-slice-rows.js";
+import { createDbTransactionRunner } from "./db-transaction.js";
+import { ensureVerificationEvidenceDedupIndex } from "./db-verification-evidence-schema.js";
+import { createSqliteProviderLoader, suppressSqliteWarning } from "./db-provider.js";
 const _require = createRequire(import.meta.url);
-const BETTER_SQLITE3_PACKAGE = ["better", "sqlite3"].join("-");
-let providerName = null;
-let providerModule = null;
-let loadAttempted = false;
-function suppressSqliteWarning() {
-    const origEmit = process.emit;
-    // Override via loose cast: Node's overloaded emit signature is not directly assignable.
-    process.emit = function (event, ...args) {
-        if (event === "warning" &&
-            args[0] &&
-            typeof args[0] === "object" &&
-            "name" in args[0] &&
-            args[0].name === "ExperimentalWarning" &&
-            "message" in args[0] &&
-            typeof args[0].message === "string" &&
-            args[0].message.includes("SQLite")) {
-            return false;
-        }
-        return origEmit.apply(process, [event, ...args]);
-    };
-}
-function loadProvider() {
-    if (loadAttempted)
-        return;
-    loadAttempted = true;
-    try {
-        suppressSqliteWarning();
-        const mod = _require("node:sqlite");
-        if (mod.DatabaseSync) {
-            providerModule = mod;
-            providerName = "node:sqlite";
-            return;
-        }
-    }
-    catch {
-        // unavailable
-    }
-    try {
-        const mod = _require(BETTER_SQLITE3_PACKAGE);
-        if (typeof mod === "function" || (mod && mod.default)) {
-            providerModule = mod.default || mod;
-            providerName = "better-sqlite3";
-            return;
-        }
-    }
-    catch {
-        // unavailable
-    }
-    const nodeMajor = parseInt(process.versions.node.split(".")[0], 10);
-    const versionHint = nodeMajor < 22
-        ? ` GSD requires Node >= 22.0.0 (current: v${process.versions.node}). Upgrade Node to fix this.`
-        : "";
-    process.stderr.write(`gsd-db: No SQLite provider available (tried node:sqlite, better-sqlite3).${versionHint}\n`);
-}
-function normalizeRow(row) {
-    if (row == null)
-        return undefined;
-    if (Object.getPrototypeOf(row) === null) {
-        return { ...row };
-    }
-    return row;
-}
-function normalizeRows(rows) {
-    return rows.map((r) => normalizeRow(r));
-}
-function createAdapter(rawDb) {
-    const db = rawDb;
-    const stmtCache = new Map();
-    function wrapStmt(raw) {
-        return {
-            run(...params) {
-                return raw.run(...params);
-            },
-            get(...params) {
-                return normalizeRow(raw.get(...params));
-            },
-            all(...params) {
-                return normalizeRows(raw.all(...params));
-            },
-        };
-    }
-    return {
-        exec(sql) {
-            db.exec(sql);
-        },
-        prepare(sql) {
-            let cached = stmtCache.get(sql);
-            if (cached)
-                return cached;
-            cached = wrapStmt(db.prepare(sql));
-            stmtCache.set(sql, cached);
-            return cached;
-        },
-        close() {
-            stmtCache.clear();
-            db.close();
-        },
-    };
-}
-function openRawDb(path) {
-    loadProvider();
-    if (!providerModule || !providerName)
-        return null;
-    if (providerName === "node:sqlite") {
-        const { DatabaseSync } = providerModule;
-        return new DatabaseSync(path);
-    }
-    const Database = providerModule;
-    return new Database(path);
-}
-export const SCHEMA_VERSION = 25;
-function indexExists(db, name) {
-    return !!db.prepare("SELECT 1 as present FROM sqlite_master WHERE type = 'index' AND name = ?").get(name);
-}
-/**
- * Create the v24 coordination tables (workers, milestone_leases,
- * unit_dispatches, cancellation_requests, command_queue) and their indexes.
- *
- * Idempotent — uses IF NOT EXISTS throughout. Called from both the
- * fresh-install path and the v24 migration block in migrateSchema().
- *
- * Single-host invariant: these tables coordinate concurrent auto-mode
- * workers via shared SQLite WAL on local disk only. NFS / network
- * filesystems break the coordination semantics — multi-host execution
- * needs a real coordinator (etcd, Postgres) and is out of scope.
- */
-function createCoordinationTablesV24(db) {
-    const ddl = [
-        `CREATE TABLE IF NOT EXISTS workers (
-      worker_id TEXT PRIMARY KEY,
-      host TEXT NOT NULL,
-      pid INTEGER NOT NULL,
-      started_at TEXT NOT NULL,
-      version TEXT NOT NULL,
-      last_heartbeat_at TEXT NOT NULL,
-      status TEXT NOT NULL,
-      project_root_realpath TEXT NOT NULL
-    )`,
-        `CREATE TABLE IF NOT EXISTS milestone_leases (
-      milestone_id TEXT PRIMARY KEY,
-      worker_id TEXT NOT NULL,
-      fencing_token INTEGER NOT NULL,
-      acquired_at TEXT NOT NULL,
-      expires_at TEXT NOT NULL,
-      status TEXT NOT NULL,
-      FOREIGN KEY (worker_id) REFERENCES workers(worker_id),
-      FOREIGN KEY (milestone_id) REFERENCES milestones(id)
-    )`,
-        `CREATE TABLE IF NOT EXISTS unit_dispatches (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      trace_id TEXT NOT NULL,
-      turn_id TEXT,
-      worker_id TEXT NOT NULL,
-      milestone_lease_token INTEGER NOT NULL,
-      milestone_id TEXT NOT NULL,
-      slice_id TEXT,
-      task_id TEXT,
-      unit_type TEXT NOT NULL,
-      unit_id TEXT NOT NULL,
-      status TEXT NOT NULL,
-      attempt_n INTEGER NOT NULL DEFAULT 1,
-      started_at TEXT NOT NULL,
-      ended_at TEXT,
-      exit_reason TEXT,
-      error_summary TEXT,
-      verification_evidence_id INTEGER,
-      next_run_at TEXT,
-      retry_after_ms INTEGER,
-      max_attempts INTEGER NOT NULL DEFAULT 3,
-      last_error_code TEXT,
-      last_error_at TEXT,
-      FOREIGN KEY (worker_id) REFERENCES workers(worker_id),
-      FOREIGN KEY (verification_evidence_id) REFERENCES verification_evidence(id)
-    )`,
-        `CREATE TABLE IF NOT EXISTS cancellation_requests (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      requested_at TEXT NOT NULL,
-      requested_by TEXT NOT NULL,
-      scope TEXT NOT NULL,
-      scope_id TEXT NOT NULL,
-      dispatch_id INTEGER,
-      reason TEXT NOT NULL,
-      status TEXT NOT NULL,
-      acked_at TEXT,
-      acked_worker_id TEXT,
-      FOREIGN KEY (dispatch_id) REFERENCES unit_dispatches(id),
-      FOREIGN KEY (acked_worker_id) REFERENCES workers(worker_id)
-    )`,
-        `CREATE TABLE IF NOT EXISTS command_queue (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      target_worker TEXT,
-      command TEXT NOT NULL,
-      args_json TEXT NOT NULL DEFAULT '{}',
-      enqueued_at TEXT NOT NULL,
-      claimed_at TEXT,
-      claimed_by TEXT,
-      completed_at TEXT,
-      result_json TEXT
-    )`,
-    ];
-    for (const stmt of ddl)
-        db.exec(stmt);
-    // Indexes — created here so both fresh-install and v24-migration paths
-    // produce identical structure.
-    db.exec("CREATE INDEX IF NOT EXISTS idx_unit_dispatches_active ON unit_dispatches(milestone_id, status)");
-    db.exec("CREATE INDEX IF NOT EXISTS idx_unit_dispatches_trace ON unit_dispatches(trace_id, turn_id)");
-    // Partial unique index — prevents two workers from claiming the same
-    // unit concurrently. Codex review MEDIUM B2: enforces double-claim guard
-    // at the DB level.
-    db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_unit_dispatches_active_per_unit "
-        + "ON unit_dispatches(unit_id) WHERE status IN ('claimed','running')");
-    // command_queue index — SQLite indexes NULLs in B-trees, so this single
-    // index serves both targeted (target_worker = ?) and broadcast
-    // (target_worker IS NULL) queries. Codex review LOW B4 documented.
-    db.exec("CREATE INDEX IF NOT EXISTS idx_command_queue_pending ON command_queue(target_worker, claimed_at)");
-}
-/**
- * Create the v25 runtime_kv table. Idempotent — uses IF NOT EXISTS.
- *
- * STRICT INVARIANT: runtime_kv is NON-CORRECTNESS-CRITICAL. UI cursors,
- * dashboard caches, last-seen-version markers, resume cursors, and other
- * "soft" state are OK. Anything that drives auto-mode control flow gets
- * typed columns in unit_dispatches / workers / milestone_leases — never
- * a bag of JSON in runtime_kv.
- *
- * Scope partitioning: ('global', '', key) for project-wide values;
- * ('worker', worker_id, key) for per-worker state (resume cursors);
- * ('milestone', milestone_id, key) for per-milestone soft state.
- */
-function createRuntimeKvTableV25(db) {
-    db.exec(`
-    CREATE TABLE IF NOT EXISTS runtime_kv (
-      scope TEXT NOT NULL,
-      scope_id TEXT NOT NULL DEFAULT '',
-      key TEXT NOT NULL,
-      value_json TEXT NOT NULL,
-      updated_at TEXT NOT NULL,
-      PRIMARY KEY (scope, scope_id, key)
-    )
-  `);
-}
-function dedupeVerificationEvidenceRows(db) {
-    db.exec(`
-    DELETE FROM verification_evidence
-    WHERE rowid NOT IN (
-      SELECT MIN(rowid)
-      FROM verification_evidence
-      GROUP BY task_id, slice_id, milestone_id, command, verdict
-    )
-  `);
-}
-function ensureVerificationEvidenceDedupIndex(db) {
-    if (indexExists(db, "idx_verification_evidence_dedup"))
-        return;
-    dedupeVerificationEvidenceRows(db);
-    db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_verification_evidence_dedup ON verification_evidence(task_id, slice_id, milestone_id, command, verdict)");
-}
+const providerLoader = createSqliteProviderLoader({
+    requireModule: (id) => _require(id),
+    suppressSqliteWarning,
+    nodeVersion: process.versions.node,
+    writeStderr: (message) => process.stderr.write(message),
+});
+export const SCHEMA_VERSION = 28;
 function initSchema(db, fileBacked) {
     if (fileBacked)
         db.exec("PRAGMA journal_mode=WAL");
@@ -300,344 +71,10 @@ function initSchema(db, fileBacked) {
     db.exec("PRAGMA foreign_keys = ON");
     db.exec("BEGIN");
     try {
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS schema_version (
-        version INTEGER NOT NULL,
-        applied_at TEXT NOT NULL
-      )
-    `);
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS decisions (
-        seq INTEGER PRIMARY KEY AUTOINCREMENT,
-        id TEXT NOT NULL UNIQUE,
-        when_context TEXT NOT NULL DEFAULT '',
-        scope TEXT NOT NULL DEFAULT '',
-        decision TEXT NOT NULL DEFAULT '',
-        choice TEXT NOT NULL DEFAULT '',
-        rationale TEXT NOT NULL DEFAULT '',
-        revisable TEXT NOT NULL DEFAULT '',
-        made_by TEXT NOT NULL DEFAULT 'agent',
-        source TEXT NOT NULL DEFAULT 'discussion', -- ADR-011 P2: 'discussion' | 'planning' | 'escalation'
-        superseded_by TEXT DEFAULT NULL
-      )
-    `);
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS requirements (
-        id TEXT PRIMARY KEY,
-        class TEXT NOT NULL DEFAULT '',
-        status TEXT NOT NULL DEFAULT '',
-        description TEXT NOT NULL DEFAULT '',
-        why TEXT NOT NULL DEFAULT '',
-        source TEXT NOT NULL DEFAULT '',
-        primary_owner TEXT NOT NULL DEFAULT '',
-        supporting_slices TEXT NOT NULL DEFAULT '',
-        validation TEXT NOT NULL DEFAULT '',
-        notes TEXT NOT NULL DEFAULT '',
-        full_content TEXT NOT NULL DEFAULT '',
-        superseded_by TEXT DEFAULT NULL
-      )
-    `);
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS artifacts (
-        path TEXT PRIMARY KEY,
-        artifact_type TEXT NOT NULL DEFAULT '',
-        milestone_id TEXT DEFAULT NULL,
-        slice_id TEXT DEFAULT NULL,
-        task_id TEXT DEFAULT NULL,
-        full_content TEXT NOT NULL DEFAULT '',
-        imported_at TEXT NOT NULL DEFAULT ''
-      )
-    `);
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS memories (
-        seq INTEGER PRIMARY KEY AUTOINCREMENT,
-        id TEXT NOT NULL UNIQUE,
-        category TEXT NOT NULL,
-        content TEXT NOT NULL,
-        confidence REAL NOT NULL DEFAULT 0.8,
-        source_unit_type TEXT,
-        source_unit_id TEXT,
-        created_at TEXT NOT NULL,
-        updated_at TEXT NOT NULL,
-        superseded_by TEXT DEFAULT NULL,
-        hit_count INTEGER NOT NULL DEFAULT 0,
-        scope TEXT NOT NULL DEFAULT 'project',
-        tags TEXT NOT NULL DEFAULT '[]',
-        structured_fields TEXT DEFAULT NULL
-      )
-    `);
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS memory_processed_units (
-        unit_key TEXT PRIMARY KEY,
-        activity_file TEXT,
-        processed_at TEXT NOT NULL
-      )
-    `);
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS memory_sources (
-        id TEXT PRIMARY KEY,
-        kind TEXT NOT NULL,
-        uri TEXT,
-        title TEXT,
-        content TEXT NOT NULL,
-        content_hash TEXT NOT NULL UNIQUE,
-        imported_at TEXT NOT NULL,
-        scope TEXT NOT NULL DEFAULT 'project',
-        tags TEXT NOT NULL DEFAULT '[]'
-      )
-    `);
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS memory_embeddings (
-        memory_id TEXT PRIMARY KEY,
-        model TEXT NOT NULL,
-        dim INTEGER NOT NULL,
-        vector BLOB NOT NULL,
-        updated_at TEXT NOT NULL
-      )
-    `);
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS memory_relations (
-        from_id TEXT NOT NULL,
-        to_id TEXT NOT NULL,
-        rel TEXT NOT NULL,
-        confidence REAL NOT NULL DEFAULT 0.8,
-        created_at TEXT NOT NULL,
-        PRIMARY KEY (from_id, to_id, rel)
-      )
-    `);
-        // FTS5 virtual table mirroring memories.content for fast keyword search.
-        // Optional — if the SQLite build lacks FTS5, we fall back to LIKE scans.
-        tryCreateMemoriesFts(db);
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS milestones (
-        id TEXT PRIMARY KEY,
-        title TEXT NOT NULL DEFAULT '',
-        status TEXT NOT NULL DEFAULT 'active',
-        depends_on TEXT NOT NULL DEFAULT '[]',
-        created_at TEXT NOT NULL DEFAULT '',
-        completed_at TEXT DEFAULT NULL,
-        vision TEXT NOT NULL DEFAULT '',
-        success_criteria TEXT NOT NULL DEFAULT '[]',
-        key_risks TEXT NOT NULL DEFAULT '[]',
-        proof_strategy TEXT NOT NULL DEFAULT '[]',
-        verification_contract TEXT NOT NULL DEFAULT '',
-        verification_integration TEXT NOT NULL DEFAULT '',
-        verification_operational TEXT NOT NULL DEFAULT '',
-        verification_uat TEXT NOT NULL DEFAULT '',
-        definition_of_done TEXT NOT NULL DEFAULT '[]',
-        requirement_coverage TEXT NOT NULL DEFAULT '',
-        boundary_map_markdown TEXT NOT NULL DEFAULT '',
-        sequence INTEGER DEFAULT 0
-      )
-    `);
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS slices (
-        milestone_id TEXT NOT NULL,
-        id TEXT NOT NULL,
-        title TEXT NOT NULL DEFAULT '',
-        status TEXT NOT NULL DEFAULT 'pending',
-        risk TEXT NOT NULL DEFAULT 'medium',
-        depends TEXT NOT NULL DEFAULT '[]',
-        demo TEXT NOT NULL DEFAULT '',
-        created_at TEXT NOT NULL DEFAULT '',
-        completed_at TEXT DEFAULT NULL,
-        full_summary_md TEXT NOT NULL DEFAULT '',
-        full_uat_md TEXT NOT NULL DEFAULT '',
-        goal TEXT NOT NULL DEFAULT '',
-        success_criteria TEXT NOT NULL DEFAULT '',
-        proof_level TEXT NOT NULL DEFAULT '',
-        integration_closure TEXT NOT NULL DEFAULT '',
-        observability_impact TEXT NOT NULL DEFAULT '',
-        sequence INTEGER DEFAULT 0, -- Ordering hint: tools may set this to control execution order
-        replan_triggered_at TEXT DEFAULT NULL,
-        is_sketch INTEGER NOT NULL DEFAULT 0, -- ADR-011: 1 = slice is a sketch awaiting refinement
-        sketch_scope TEXT NOT NULL DEFAULT '', -- ADR-011: 2-3 sentence rough scope from plan-milestone
-        PRIMARY KEY (milestone_id, id),
-        FOREIGN KEY (milestone_id) REFERENCES milestones(id)
-      )
-    `);
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS tasks (
-        milestone_id TEXT NOT NULL,
-        slice_id TEXT NOT NULL,
-        id TEXT NOT NULL,
-        title TEXT NOT NULL DEFAULT '',
-        status TEXT NOT NULL DEFAULT 'pending',
-        one_liner TEXT NOT NULL DEFAULT '',
-        narrative TEXT NOT NULL DEFAULT '',
-        verification_result TEXT NOT NULL DEFAULT '',
-        duration TEXT NOT NULL DEFAULT '',
-        completed_at TEXT DEFAULT NULL,
-        blocker_discovered INTEGER DEFAULT 0,
-        blocker_source TEXT NOT NULL DEFAULT '', -- ADR-011 P2: provenance for blocker_discovered (e.g. 'reject-escalation')
-        escalation_pending INTEGER NOT NULL DEFAULT 0, -- ADR-011 P2: pause-on-escalation flag
-        escalation_awaiting_review INTEGER NOT NULL DEFAULT 0, -- ADR-011 P2: artifact exists but continueWithDefault=true (no pause)
-        escalation_artifact_path TEXT DEFAULT NULL, -- ADR-011 P2: path to T##-ESCALATION.json
-        escalation_override_applied_at TEXT DEFAULT NULL, -- ADR-011 P2: DB claim lock for idempotent override injection
-        deviations TEXT NOT NULL DEFAULT '',
-        known_issues TEXT NOT NULL DEFAULT '',
-        key_files TEXT NOT NULL DEFAULT '[]',
-        key_decisions TEXT NOT NULL DEFAULT '[]',
-        full_summary_md TEXT NOT NULL DEFAULT '',
-        description TEXT NOT NULL DEFAULT '',
-        estimate TEXT NOT NULL DEFAULT '',
-        files TEXT NOT NULL DEFAULT '[]',
-        verify TEXT NOT NULL DEFAULT '',
-        inputs TEXT NOT NULL DEFAULT '[]',
-        expected_output TEXT NOT NULL DEFAULT '[]',
-        observability_impact TEXT NOT NULL DEFAULT '',
-        full_plan_md TEXT NOT NULL DEFAULT '',
-        sequence INTEGER DEFAULT 0, -- Ordering hint: tools may set this to control execution order
-        PRIMARY KEY (milestone_id, slice_id, id),
-        FOREIGN KEY (milestone_id, slice_id) REFERENCES slices(milestone_id, id)
-      )
-    `);
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS verification_evidence (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        task_id TEXT NOT NULL DEFAULT '',
-        slice_id TEXT NOT NULL DEFAULT '',
-        milestone_id TEXT NOT NULL DEFAULT '',
-        command TEXT NOT NULL DEFAULT '',
-        exit_code INTEGER DEFAULT 0,
-        verdict TEXT NOT NULL DEFAULT '',
-        duration_ms INTEGER DEFAULT 0,
-        created_at TEXT NOT NULL DEFAULT '',
-        FOREIGN KEY (milestone_id, slice_id, task_id) REFERENCES tasks(milestone_id, slice_id, id)
-      )
-    `);
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS replan_history (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        milestone_id TEXT NOT NULL DEFAULT '',
-        slice_id TEXT DEFAULT NULL,
-        task_id TEXT DEFAULT NULL,
-        summary TEXT NOT NULL DEFAULT '',
-        previous_artifact_path TEXT DEFAULT NULL,
-        replacement_artifact_path TEXT DEFAULT NULL,
-        created_at TEXT NOT NULL DEFAULT '',
-        FOREIGN KEY (milestone_id) REFERENCES milestones(id)
-      )
-    `);
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS assessments (
-        path TEXT PRIMARY KEY,
-        milestone_id TEXT NOT NULL DEFAULT '',
-        slice_id TEXT DEFAULT NULL,
-        task_id TEXT DEFAULT NULL,
-        status TEXT NOT NULL DEFAULT '',
-        scope TEXT NOT NULL DEFAULT '',
-        full_content TEXT NOT NULL DEFAULT '',
-        created_at TEXT NOT NULL DEFAULT '',
-        FOREIGN KEY (milestone_id) REFERENCES milestones(id)
-      )
-    `);
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS quality_gates (
-        milestone_id TEXT NOT NULL,
-        slice_id TEXT NOT NULL,
-        gate_id TEXT NOT NULL,
-        scope TEXT NOT NULL DEFAULT 'slice',
-        task_id TEXT NOT NULL DEFAULT '',
-        status TEXT NOT NULL DEFAULT 'pending',
-        verdict TEXT NOT NULL DEFAULT '',
-        rationale TEXT NOT NULL DEFAULT '',
-        findings TEXT NOT NULL DEFAULT '',
-        evaluated_at TEXT DEFAULT NULL,
-        PRIMARY KEY (milestone_id, slice_id, gate_id, task_id),
-        FOREIGN KEY (milestone_id, slice_id) REFERENCES slices(milestone_id, id)
-      )
-    `);
-        // Slice dependency junction table (v14)
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS slice_dependencies (
-        milestone_id TEXT NOT NULL,
-        slice_id TEXT NOT NULL,
-        depends_on_slice_id TEXT NOT NULL,
-        PRIMARY KEY (milestone_id, slice_id, depends_on_slice_id),
-        FOREIGN KEY (milestone_id, slice_id) REFERENCES slices(milestone_id, id),
-        FOREIGN KEY (milestone_id, depends_on_slice_id) REFERENCES slices(milestone_id, id)
-      )
-    `);
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS gate_runs (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        trace_id TEXT NOT NULL,
-        turn_id TEXT NOT NULL,
-        gate_id TEXT NOT NULL,
-        gate_type TEXT NOT NULL DEFAULT '',
-        unit_type TEXT DEFAULT NULL,
-        unit_id TEXT DEFAULT NULL,
-        milestone_id TEXT DEFAULT NULL,
-        slice_id TEXT DEFAULT NULL,
-        task_id TEXT DEFAULT NULL,
-        outcome TEXT NOT NULL DEFAULT 'pass',
-        failure_class TEXT NOT NULL DEFAULT 'none',
-        rationale TEXT NOT NULL DEFAULT '',
-        findings TEXT NOT NULL DEFAULT '',
-        attempt INTEGER NOT NULL DEFAULT 1,
-        max_attempts INTEGER NOT NULL DEFAULT 1,
-        retryable INTEGER NOT NULL DEFAULT 0,
-        evaluated_at TEXT NOT NULL DEFAULT ''
-      )
-    `);
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS turn_git_transactions (
-        trace_id TEXT NOT NULL,
-        turn_id TEXT NOT NULL,
-        unit_type TEXT DEFAULT NULL,
-        unit_id TEXT DEFAULT NULL,
-        stage TEXT NOT NULL DEFAULT 'turn-start',
-        action TEXT NOT NULL DEFAULT 'status-only',
-        push INTEGER NOT NULL DEFAULT 0,
-        status TEXT NOT NULL DEFAULT 'ok',
-        error TEXT DEFAULT NULL,
-        metadata_json TEXT NOT NULL DEFAULT '{}',
-        updated_at TEXT NOT NULL DEFAULT '',
-        PRIMARY KEY (trace_id, turn_id, stage)
-      )
-    `);
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS audit_events (
-        event_id TEXT PRIMARY KEY,
-        trace_id TEXT NOT NULL,
-        turn_id TEXT DEFAULT NULL,
-        caused_by TEXT DEFAULT NULL,
-        category TEXT NOT NULL,
-        type TEXT NOT NULL,
-        ts TEXT NOT NULL,
-        payload_json TEXT NOT NULL DEFAULT '{}'
-      )
-    `);
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS audit_turn_index (
-        trace_id TEXT NOT NULL,
-        turn_id TEXT NOT NULL,
-        first_ts TEXT NOT NULL,
-        last_ts TEXT NOT NULL,
-        event_count INTEGER NOT NULL DEFAULT 0,
-        PRIMARY KEY (trace_id, turn_id)
-      )
-    `);
-        db.exec("CREATE INDEX IF NOT EXISTS idx_memories_active ON memories(superseded_by)");
-        db.exec("CREATE INDEX IF NOT EXISTS idx_replan_history_milestone ON replan_history(milestone_id, created_at)");
-        // v13 indexes — hot-path dispatch queries
-        db.exec("CREATE INDEX IF NOT EXISTS idx_tasks_active ON tasks(milestone_id, slice_id, status)");
-        db.exec("CREATE INDEX IF NOT EXISTS idx_slices_active ON slices(milestone_id, status)");
-        db.exec("CREATE INDEX IF NOT EXISTS idx_milestones_status ON milestones(status)");
-        db.exec("CREATE INDEX IF NOT EXISTS idx_quality_gates_pending ON quality_gates(milestone_id, slice_id, status)");
-        db.exec("CREATE INDEX IF NOT EXISTS idx_verification_evidence_task ON verification_evidence(milestone_id, slice_id, task_id)");
-        ensureVerificationEvidenceDedupIndex(db);
-        // v14 index — slice dependency lookups
-        db.exec("CREATE INDEX IF NOT EXISTS idx_slice_deps_target ON slice_dependencies(milestone_id, depends_on_slice_id)");
-        db.exec("CREATE INDEX IF NOT EXISTS idx_gate_runs_turn ON gate_runs(trace_id, turn_id)");
-        db.exec("CREATE INDEX IF NOT EXISTS idx_gate_runs_lookup ON gate_runs(milestone_id, slice_id, task_id, gate_id)");
-        db.exec("CREATE INDEX IF NOT EXISTS idx_turn_git_tx_turn ON turn_git_transactions(trace_id, turn_id)");
-        db.exec("CREATE INDEX IF NOT EXISTS idx_audit_events_trace ON audit_events(trace_id, ts)");
-        db.exec("CREATE INDEX IF NOT EXISTS idx_audit_events_turn ON audit_events(trace_id, turn_id, ts)");
-        db.exec(`CREATE VIEW IF NOT EXISTS active_decisions AS SELECT * FROM decisions WHERE superseded_by IS NULL`);
-        db.exec(`CREATE VIEW IF NOT EXISTS active_requirements AS SELECT * FROM requirements WHERE superseded_by IS NULL`);
-        db.exec(`CREATE VIEW IF NOT EXISTS active_memories AS SELECT * FROM memories WHERE superseded_by IS NULL`);
+        createBaseSchemaObjects(db, {
+            tryCreateMemoriesFts,
+            ensureVerificationEvidenceDedupIndex,
+        });
         const existing = db.prepare("SELECT count(*) as cnt FROM schema_version").get();
         if (existing && existing["cnt"] === 0) {
             createCoordinationTablesV24(db);
@@ -652,10 +89,7 @@ function initSchema(db, fileBacked) {
             db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_scope ON memory_sources(scope)");
             db.exec("CREATE INDEX IF NOT EXISTS idx_memory_relations_from ON memory_relations(from_id)");
             db.exec("CREATE INDEX IF NOT EXISTS idx_memory_relations_to ON memory_relations(to_id)");
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": SCHEMA_VERSION,
-                ":applied_at": new Date().toISOString(),
-            });
+            recordSchemaVersion(db, SCHEMA_VERSION);
         }
         db.exec("COMMIT");
     }
@@ -665,14 +99,6 @@ function initSchema(db, fileBacked) {
     }
     migrateSchema(db);
 }
-function columnExists(db, table, column) {
-    const rows = db.prepare(`PRAGMA table_info(${table})`).all();
-    return rows.some((row) => row["name"] === column);
-}
-function formatFtsUnavailableError(err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return message.replace(/\bmoduel\s*:\s*/gi, "module: ");
-}
 /**
  * Create the FTS5 virtual table for memories plus the triggers that keep it
  * in sync with the base table. FTS5 may be unavailable on stripped-down
@@ -680,304 +106,74 @@ function formatFtsUnavailableError(err) {
  * to LIKE-based scans in `memory-store.queryMemoriesRanked`.
  */
 export function tryCreateMemoriesFts(db) {
-    try {
-        db.exec(`
-      CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts
-      USING fts5(content, content='memories', content_rowid='seq', tokenize='porter unicode61')
-    `);
-        // Triggers mirror inserts / updates / deletes on the base memories table.
-        db.exec(`
-      CREATE TRIGGER IF NOT EXISTS memories_ai
-      AFTER INSERT ON memories BEGIN
-        INSERT INTO memories_fts(rowid, content) VALUES (new.seq, new.content);
-      END
-    `);
-        db.exec(`
-      CREATE TRIGGER IF NOT EXISTS memories_ad
-      AFTER DELETE ON memories BEGIN
-        INSERT INTO memories_fts(memories_fts, rowid, content) VALUES ('delete', old.seq, old.content);
-      END
-    `);
-        db.exec(`
-      CREATE TRIGGER IF NOT EXISTS memories_au
-      AFTER UPDATE OF content ON memories BEGIN
-        INSERT INTO memories_fts(memories_fts, rowid, content) VALUES ('delete', old.seq, old.content);
-        INSERT INTO memories_fts(rowid, content) VALUES (new.seq, new.content);
-      END
-    `);
-        return true;
-    }
-    catch (err) {
-        logWarning("db", `FTS5 unavailable — memory queries will use LIKE fallback: ${formatFtsUnavailableError(err)}`);
-        return false;
-    }
+    return tryCreateMemoriesFtsSchema(db, {
+        onUnavailable: (message) => logWarning("db", message),
+    });
 }
 export function isMemoriesFtsAvailable(db) {
-    try {
-        const row = db
-            .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='memories_fts'")
-            .get();
-        return !!row;
-    }
-    catch {
-        return false;
-    }
+    return isMemoriesFtsAvailableSchema(db);
+}
+function backfillMemoriesFts(db) {
+    db.exec(`INSERT INTO memories_fts(rowid, content) SELECT seq, content FROM memories`);
 }
-function ensureColumn(db, table, column, ddl) {
-    if (!columnExists(db, table, column))
-        db.exec(ddl);
+function copyQualityGateRowsToRepairedTable(db) {
+    db.exec(`
+    INSERT OR IGNORE INTO quality_gates_new
+      (milestone_id, slice_id, gate_id, scope, task_id, status, verdict, rationale, findings, evaluated_at)
+    SELECT milestone_id, slice_id, gate_id, scope, COALESCE(task_id, ''), status, verdict, rationale, findings, evaluated_at
+    FROM quality_gates
+  `);
 }
 function migrateSchema(db) {
-    const row = db.prepare("SELECT MAX(version) as v FROM schema_version").get();
-    const currentVersion = row ? row["v"] : 0;
+    const currentVersion = getCurrentSchemaVersion(db);
     if (currentVersion >= SCHEMA_VERSION)
         return;
-    // Backup database before migration so a mid-migration crash doesn't
-    // leave a partially-migrated DB with no recovery path.
-    // WAL-safe: checkpoint first to flush WAL into the main DB file, then copy.
-    if (currentPath && currentPath !== ":memory:" && existsSync(currentPath)) {
-        try {
-            const backupPath = `${currentPath}.backup-v${currentVersion}`;
-            if (!existsSync(backupPath)) {
-                // Flush WAL to main DB file before copying — without this, the backup
-                // may be missing committed data that only exists in the -wal file.
-                try {
-                    db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
-                }
-                catch { /* checkpoint is best-effort */ }
-                copyFileSync(currentPath, backupPath);
-            }
-        }
-        catch (backupErr) {
-            // Log but proceed — blocking migration leaves the DB stuck at an old
-            // schema version permanently on read-only or full filesystems.
-            logWarning("db", `Pre-migration backup failed: ${backupErr instanceof Error ? backupErr.message : String(backupErr)}`);
-        }
-    }
+    backupDatabaseBeforeMigration(db, currentPath, currentVersion, {
+        existsSync,
+        copyFileSync,
+        logWarning,
+    });
     db.exec("BEGIN");
     try {
         if (currentVersion < 2) {
-            db.exec(`
-        CREATE TABLE IF NOT EXISTS artifacts (
-          path TEXT PRIMARY KEY,
-          artifact_type TEXT NOT NULL DEFAULT '',
-          milestone_id TEXT DEFAULT NULL,
-          slice_id TEXT DEFAULT NULL,
-          task_id TEXT DEFAULT NULL,
-          full_content TEXT NOT NULL DEFAULT '',
-          imported_at TEXT NOT NULL DEFAULT ''
-        )
-      `);
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": 2,
-                ":applied_at": new Date().toISOString(),
-            });
+            applyMigrationV2Artifacts(db);
+            recordSchemaVersion(db, 2);
         }
         if (currentVersion < 3) {
-            db.exec(`
-        CREATE TABLE IF NOT EXISTS memories (
-          seq INTEGER PRIMARY KEY AUTOINCREMENT,
-          id TEXT NOT NULL UNIQUE,
-          category TEXT NOT NULL,
-          content TEXT NOT NULL,
-          confidence REAL NOT NULL DEFAULT 0.8,
-          source_unit_type TEXT,
-          source_unit_id TEXT,
-          created_at TEXT NOT NULL,
-          updated_at TEXT NOT NULL,
-          superseded_by TEXT DEFAULT NULL,
-          hit_count INTEGER NOT NULL DEFAULT 0
-        )
-      `);
-            db.exec(`
-        CREATE TABLE IF NOT EXISTS memory_processed_units (
-          unit_key TEXT PRIMARY KEY,
-          activity_file TEXT,
-          processed_at TEXT NOT NULL
-        )
-      `);
-            db.exec("CREATE INDEX IF NOT EXISTS idx_memories_active ON memories(superseded_by)");
-            db.exec("DROP VIEW IF EXISTS active_memories");
-            db.exec("CREATE VIEW active_memories AS SELECT * FROM memories WHERE superseded_by IS NULL");
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": 3,
-                ":applied_at": new Date().toISOString(),
-            });
+            applyMigrationV3Memories(db);
+            recordSchemaVersion(db, 3);
         }
         if (currentVersion < 4) {
-            ensureColumn(db, "decisions", "made_by", `ALTER TABLE decisions ADD COLUMN made_by TEXT NOT NULL DEFAULT 'agent'`);
-            db.exec("DROP VIEW IF EXISTS active_decisions");
-            db.exec("CREATE VIEW active_decisions AS SELECT * FROM decisions WHERE superseded_by IS NULL");
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": 4,
-                ":applied_at": new Date().toISOString(),
-            });
+            applyMigrationV4DecisionMadeBy(db);
+            recordSchemaVersion(db, 4);
         }
         if (currentVersion < 5) {
-            db.exec(`
-        CREATE TABLE IF NOT EXISTS milestones (
-          id TEXT PRIMARY KEY,
-          title TEXT NOT NULL DEFAULT '',
-          status TEXT NOT NULL DEFAULT 'active',
-          created_at TEXT NOT NULL,
-          completed_at TEXT DEFAULT NULL
-        )
-      `);
-            db.exec(`
-        CREATE TABLE IF NOT EXISTS slices (
-          milestone_id TEXT NOT NULL,
-          id TEXT NOT NULL,
-          title TEXT NOT NULL DEFAULT '',
-          status TEXT NOT NULL DEFAULT 'pending',
-          risk TEXT NOT NULL DEFAULT 'medium',
-          created_at TEXT NOT NULL DEFAULT '',
-          completed_at TEXT DEFAULT NULL,
-          PRIMARY KEY (milestone_id, id),
-          FOREIGN KEY (milestone_id) REFERENCES milestones(id)
-        )
-      `);
-            db.exec(`
-        CREATE TABLE IF NOT EXISTS tasks (
-          milestone_id TEXT NOT NULL,
-          slice_id TEXT NOT NULL,
-          id TEXT NOT NULL,
-          title TEXT NOT NULL DEFAULT '',
-          status TEXT NOT NULL DEFAULT 'pending',
-          one_liner TEXT NOT NULL DEFAULT '',
-          narrative TEXT NOT NULL DEFAULT '',
-          verification_result TEXT NOT NULL DEFAULT '',
-          duration TEXT NOT NULL DEFAULT '',
-          completed_at TEXT DEFAULT NULL,
-          blocker_discovered INTEGER DEFAULT 0,
-          deviations TEXT NOT NULL DEFAULT '',
-          known_issues TEXT NOT NULL DEFAULT '',
-          key_files TEXT NOT NULL DEFAULT '[]',
-          key_decisions TEXT NOT NULL DEFAULT '[]',
-          full_summary_md TEXT NOT NULL DEFAULT '',
-          PRIMARY KEY (milestone_id, slice_id, id),
-          FOREIGN KEY (milestone_id, slice_id) REFERENCES slices(milestone_id, id)
-        )
-      `);
-            db.exec(`
-        CREATE TABLE IF NOT EXISTS verification_evidence (
-          id INTEGER PRIMARY KEY AUTOINCREMENT,
-          task_id TEXT NOT NULL DEFAULT '',
-          slice_id TEXT NOT NULL DEFAULT '',
-          milestone_id TEXT NOT NULL DEFAULT '',
-          command TEXT NOT NULL DEFAULT '',
-          exit_code INTEGER DEFAULT 0,
-          verdict TEXT NOT NULL DEFAULT '',
-          duration_ms INTEGER DEFAULT 0,
-          created_at TEXT NOT NULL DEFAULT '',
-          FOREIGN KEY (milestone_id, slice_id, task_id) REFERENCES tasks(milestone_id, slice_id, id)
-        )
-      `);
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": 5,
-                ":applied_at": new Date().toISOString(),
-            });
+            applyMigrationV5HierarchyTables(db);
+            recordSchemaVersion(db, 5);
         }
         if (currentVersion < 6) {
-            ensureColumn(db, "slices", "full_summary_md", `ALTER TABLE slices ADD COLUMN full_summary_md TEXT NOT NULL DEFAULT ''`);
-            ensureColumn(db, "slices", "full_uat_md", `ALTER TABLE slices ADD COLUMN full_uat_md TEXT NOT NULL DEFAULT ''`);
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": 6,
-                ":applied_at": new Date().toISOString(),
-            });
+            applyMigrationV6SliceSummaries(db);
+            recordSchemaVersion(db, 6);
         }
         if (currentVersion < 7) {
-            ensureColumn(db, "slices", "depends", `ALTER TABLE slices ADD COLUMN depends TEXT NOT NULL DEFAULT '[]'`);
-            ensureColumn(db, "slices", "demo", `ALTER TABLE slices ADD COLUMN demo TEXT NOT NULL DEFAULT ''`);
-            ensureColumn(db, "milestones", "depends_on", `ALTER TABLE milestones ADD COLUMN depends_on TEXT NOT NULL DEFAULT '[]'`);
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": 7,
-                ":applied_at": new Date().toISOString(),
-            });
+            applyMigrationV7Dependencies(db);
+            recordSchemaVersion(db, 7);
         }
         if (currentVersion < 8) {
-            ensureColumn(db, "milestones", "vision", `ALTER TABLE milestones ADD COLUMN vision TEXT NOT NULL DEFAULT ''`);
-            ensureColumn(db, "milestones", "success_criteria", `ALTER TABLE milestones ADD COLUMN success_criteria TEXT NOT NULL DEFAULT '[]'`);
-            ensureColumn(db, "milestones", "key_risks", `ALTER TABLE milestones ADD COLUMN key_risks TEXT NOT NULL DEFAULT '[]'`);
-            ensureColumn(db, "milestones", "proof_strategy", `ALTER TABLE milestones ADD COLUMN proof_strategy TEXT NOT NULL DEFAULT '[]'`);
-            ensureColumn(db, "milestones", "verification_contract", `ALTER TABLE milestones ADD COLUMN verification_contract TEXT NOT NULL DEFAULT ''`);
-            ensureColumn(db, "milestones", "verification_integration", `ALTER TABLE milestones ADD COLUMN verification_integration TEXT NOT NULL DEFAULT ''`);
-            ensureColumn(db, "milestones", "verification_operational", `ALTER TABLE milestones ADD COLUMN verification_operational TEXT NOT NULL DEFAULT ''`);
-            ensureColumn(db, "milestones", "verification_uat", `ALTER TABLE milestones ADD COLUMN verification_uat TEXT NOT NULL DEFAULT ''`);
-            ensureColumn(db, "milestones", "definition_of_done", `ALTER TABLE milestones ADD COLUMN definition_of_done TEXT NOT NULL DEFAULT '[]'`);
-            ensureColumn(db, "milestones", "requirement_coverage", `ALTER TABLE milestones ADD COLUMN requirement_coverage TEXT NOT NULL DEFAULT ''`);
-            ensureColumn(db, "milestones", "boundary_map_markdown", `ALTER TABLE milestones ADD COLUMN boundary_map_markdown TEXT NOT NULL DEFAULT ''`);
-            ensureColumn(db, "slices", "goal", `ALTER TABLE slices ADD COLUMN goal TEXT NOT NULL DEFAULT ''`);
-            ensureColumn(db, "slices", "success_criteria", `ALTER TABLE slices ADD COLUMN success_criteria TEXT NOT NULL DEFAULT ''`);
-            ensureColumn(db, "slices", "proof_level", `ALTER TABLE slices ADD COLUMN proof_level TEXT NOT NULL DEFAULT ''`);
-            ensureColumn(db, "slices", "integration_closure", `ALTER TABLE slices ADD COLUMN integration_closure TEXT NOT NULL DEFAULT ''`);
-            ensureColumn(db, "slices", "observability_impact", `ALTER TABLE slices ADD COLUMN observability_impact TEXT NOT NULL DEFAULT ''`);
-            ensureColumn(db, "tasks", "description", `ALTER TABLE tasks ADD COLUMN description TEXT NOT NULL DEFAULT ''`);
-            ensureColumn(db, "tasks", "estimate", `ALTER TABLE tasks ADD COLUMN estimate TEXT NOT NULL DEFAULT ''`);
-            ensureColumn(db, "tasks", "files", `ALTER TABLE tasks ADD COLUMN files TEXT NOT NULL DEFAULT '[]'`);
-            ensureColumn(db, "tasks", "verify", `ALTER TABLE tasks ADD COLUMN verify TEXT NOT NULL DEFAULT ''`);
-            ensureColumn(db, "tasks", "inputs", `ALTER TABLE tasks ADD COLUMN inputs TEXT NOT NULL DEFAULT '[]'`);
-            ensureColumn(db, "tasks", "expected_output", `ALTER TABLE tasks ADD COLUMN expected_output TEXT NOT NULL DEFAULT '[]'`);
-            ensureColumn(db, "tasks", "observability_impact", `ALTER TABLE tasks ADD COLUMN observability_impact TEXT NOT NULL DEFAULT ''`);
-            db.exec(`
-        CREATE TABLE IF NOT EXISTS replan_history (
-          id INTEGER PRIMARY KEY AUTOINCREMENT,
-          milestone_id TEXT NOT NULL DEFAULT '',
-          slice_id TEXT DEFAULT NULL,
-          task_id TEXT DEFAULT NULL,
-          summary TEXT NOT NULL DEFAULT '',
-          previous_artifact_path TEXT DEFAULT NULL,
-          replacement_artifact_path TEXT DEFAULT NULL,
-          created_at TEXT NOT NULL DEFAULT '',
-          FOREIGN KEY (milestone_id) REFERENCES milestones(id)
-        )
-      `);
-            db.exec(`
-        CREATE TABLE IF NOT EXISTS assessments (
-          path TEXT PRIMARY KEY,
-          milestone_id TEXT NOT NULL DEFAULT '',
-          slice_id TEXT DEFAULT NULL,
-          task_id TEXT DEFAULT NULL,
-          status TEXT NOT NULL DEFAULT '',
-          scope TEXT NOT NULL DEFAULT '',
-          full_content TEXT NOT NULL DEFAULT '',
-          created_at TEXT NOT NULL DEFAULT '',
-          FOREIGN KEY (milestone_id) REFERENCES milestones(id)
-        )
-      `);
-            db.exec("CREATE INDEX IF NOT EXISTS idx_replan_history_milestone ON replan_history(milestone_id, created_at)");
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": 8,
-                ":applied_at": new Date().toISOString(),
-            });
+            applyMigrationV8PlanningFields(db);
+            recordSchemaVersion(db, 8);
         }
         if (currentVersion < 9) {
-            ensureColumn(db, "slices", "sequence", `ALTER TABLE slices ADD COLUMN sequence INTEGER DEFAULT 0`);
-            ensureColumn(db, "tasks", "sequence", `ALTER TABLE tasks ADD COLUMN sequence INTEGER DEFAULT 0`);
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": 9,
-                ":applied_at": new Date().toISOString(),
-            });
+            applyMigrationV9Ordering(db);
+            recordSchemaVersion(db, 9);
         }
         if (currentVersion < 10) {
-            ensureColumn(db, "slices", "replan_triggered_at", `ALTER TABLE slices ADD COLUMN replan_triggered_at TEXT DEFAULT NULL`);
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": 10,
-                ":applied_at": new Date().toISOString(),
-            });
+            applyMigrationV10ReplanTrigger(db);
+            recordSchemaVersion(db, 10);
         }
         if (currentVersion < 11) {
-            ensureColumn(db, "tasks", "full_plan_md", `ALTER TABLE tasks ADD COLUMN full_plan_md TEXT NOT NULL DEFAULT ''`);
-            // Add unique constraint to replan_history for idempotency:
-            // one replan record per blocker task per slice per milestone.
-            db.exec(`
-        CREATE UNIQUE INDEX IF NOT EXISTS idx_replan_history_unique
-        ON replan_history(milestone_id, slice_id, task_id)
-        WHERE slice_id IS NOT NULL AND task_id IS NOT NULL
-      `);
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": 11,
-                ":applied_at": new Date().toISOString(),
-            });
+            applyMigrationV11TaskPlanning(db);
+            recordSchemaVersion(db, 11);
         }
         if (currentVersion < 12) {
             // NOTE: The original DDL used COALESCE(task_id, '') in the PRIMARY KEY
@@ -985,295 +181,57 @@ function migrateSchema(db) {
             // DBs that migrate through v12. The corrected DDL uses
             // task_id TEXT NOT NULL DEFAULT '' with a plain column list PK. DBs that
             // were created with the broken DDL are repaired by the v22 migration below.
-            db.exec(`
-        CREATE TABLE IF NOT EXISTS quality_gates (
-          milestone_id TEXT NOT NULL,
-          slice_id TEXT NOT NULL,
-          gate_id TEXT NOT NULL,
-          scope TEXT NOT NULL DEFAULT 'slice',
-          task_id TEXT NOT NULL DEFAULT '',
-          status TEXT NOT NULL DEFAULT 'pending',
-          verdict TEXT NOT NULL DEFAULT '',
-          rationale TEXT NOT NULL DEFAULT '',
-          findings TEXT NOT NULL DEFAULT '',
-          evaluated_at TEXT DEFAULT NULL,
-          PRIMARY KEY (milestone_id, slice_id, gate_id, task_id),
-          FOREIGN KEY (milestone_id, slice_id) REFERENCES slices(milestone_id, id)
-        )
-      `);
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": 12,
-                ":applied_at": new Date().toISOString(),
-            });
+            applyMigrationV12QualityGates(db);
+            recordSchemaVersion(db, 12);
         }
         if (currentVersion < 13) {
-            // Hot-path indexes for auto-loop dispatch queries
-            db.exec("CREATE INDEX IF NOT EXISTS idx_tasks_active ON tasks(milestone_id, slice_id, status)");
-            db.exec("CREATE INDEX IF NOT EXISTS idx_slices_active ON slices(milestone_id, status)");
-            db.exec("CREATE INDEX IF NOT EXISTS idx_milestones_status ON milestones(status)");
-            db.exec("CREATE INDEX IF NOT EXISTS idx_quality_gates_pending ON quality_gates(milestone_id, slice_id, status)");
-            db.exec("CREATE INDEX IF NOT EXISTS idx_verification_evidence_task ON verification_evidence(milestone_id, slice_id, task_id)");
-            ensureVerificationEvidenceDedupIndex(db);
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": 13,
-                ":applied_at": new Date().toISOString(),
-            });
+            applyMigrationV13HotPathIndexes(db, ensureVerificationEvidenceDedupIndex);
+            recordSchemaVersion(db, 13);
         }
         if (currentVersion < 14) {
-            db.exec(`
-        CREATE TABLE IF NOT EXISTS slice_dependencies (
-          milestone_id TEXT NOT NULL,
-          slice_id TEXT NOT NULL,
-          depends_on_slice_id TEXT NOT NULL,
-          PRIMARY KEY (milestone_id, slice_id, depends_on_slice_id),
-          FOREIGN KEY (milestone_id, slice_id) REFERENCES slices(milestone_id, id),
-          FOREIGN KEY (milestone_id, depends_on_slice_id) REFERENCES slices(milestone_id, id)
-        )
-      `);
-            db.exec("CREATE INDEX IF NOT EXISTS idx_slice_deps_target ON slice_dependencies(milestone_id, depends_on_slice_id)");
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": 14,
-                ":applied_at": new Date().toISOString(),
-            });
+            applyMigrationV14SliceDependencies(db);
+            recordSchemaVersion(db, 14);
         }
         if (currentVersion < 15) {
-            db.exec(`
-        CREATE TABLE IF NOT EXISTS gate_runs (
-          id INTEGER PRIMARY KEY AUTOINCREMENT,
-          trace_id TEXT NOT NULL,
-          turn_id TEXT NOT NULL,
-          gate_id TEXT NOT NULL,
-          gate_type TEXT NOT NULL DEFAULT '',
-          unit_type TEXT DEFAULT NULL,
-          unit_id TEXT DEFAULT NULL,
-          milestone_id TEXT DEFAULT NULL,
-          slice_id TEXT DEFAULT NULL,
-          task_id TEXT DEFAULT NULL,
-          outcome TEXT NOT NULL DEFAULT 'pass',
-          failure_class TEXT NOT NULL DEFAULT 'none',
-          rationale TEXT NOT NULL DEFAULT '',
-          findings TEXT NOT NULL DEFAULT '',
-          attempt INTEGER NOT NULL DEFAULT 1,
-          max_attempts INTEGER NOT NULL DEFAULT 1,
-          retryable INTEGER NOT NULL DEFAULT 0,
-          evaluated_at TEXT NOT NULL DEFAULT ''
-        )
-      `);
-            db.exec(`
-        CREATE TABLE IF NOT EXISTS turn_git_transactions (
-          trace_id TEXT NOT NULL,
-          turn_id TEXT NOT NULL,
-          unit_type TEXT DEFAULT NULL,
-          unit_id TEXT DEFAULT NULL,
-          stage TEXT NOT NULL DEFAULT 'turn-start',
-          action TEXT NOT NULL DEFAULT 'status-only',
-          push INTEGER NOT NULL DEFAULT 0,
-          status TEXT NOT NULL DEFAULT 'ok',
-          error TEXT DEFAULT NULL,
-          metadata_json TEXT NOT NULL DEFAULT '{}',
-          updated_at TEXT NOT NULL DEFAULT '',
-          PRIMARY KEY (trace_id, turn_id, stage)
-        )
-      `);
-            db.exec(`
-        CREATE TABLE IF NOT EXISTS audit_events (
-          event_id TEXT PRIMARY KEY,
-          trace_id TEXT NOT NULL,
-          turn_id TEXT DEFAULT NULL,
-          caused_by TEXT DEFAULT NULL,
-          category TEXT NOT NULL,
-          type TEXT NOT NULL,
-          ts TEXT NOT NULL,
-          payload_json TEXT NOT NULL DEFAULT '{}'
-        )
-      `);
-            db.exec(`
-        CREATE TABLE IF NOT EXISTS audit_turn_index (
-          trace_id TEXT NOT NULL,
-          turn_id TEXT NOT NULL,
-          first_ts TEXT NOT NULL,
-          last_ts TEXT NOT NULL,
-          event_count INTEGER NOT NULL DEFAULT 0,
-          PRIMARY KEY (trace_id, turn_id)
-        )
-      `);
-            db.exec("CREATE INDEX IF NOT EXISTS idx_gate_runs_turn ON gate_runs(trace_id, turn_id)");
-            db.exec("CREATE INDEX IF NOT EXISTS idx_gate_runs_lookup ON gate_runs(milestone_id, slice_id, task_id, gate_id)");
-            db.exec("CREATE INDEX IF NOT EXISTS idx_turn_git_tx_turn ON turn_git_transactions(trace_id, turn_id)");
-            db.exec("CREATE INDEX IF NOT EXISTS idx_audit_events_trace ON audit_events(trace_id, ts)");
-            db.exec("CREATE INDEX IF NOT EXISTS idx_audit_events_turn ON audit_events(trace_id, turn_id, ts)");
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": 15,
-                ":applied_at": new Date().toISOString(),
-            });
+            applyMigrationV15AuditTables(db);
+            recordSchemaVersion(db, 15);
         }
         if (currentVersion < 16) {
-            // ADR-011 Phase 1: sketch-then-refine progressive planning — sketch columns on slices.
-            ensureColumn(db, "slices", "is_sketch", `ALTER TABLE slices ADD COLUMN is_sketch INTEGER NOT NULL DEFAULT 0`);
-            ensureColumn(db, "slices", "sketch_scope", `ALTER TABLE slices ADD COLUMN sketch_scope TEXT NOT NULL DEFAULT ''`);
-            // ADR-011 Phase 2: decisions can now be sourced from escalation resolutions.
-            ensureColumn(db, "decisions", "source", `ALTER TABLE decisions ADD COLUMN source TEXT NOT NULL DEFAULT 'discussion'`);
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": 16,
-                ":applied_at": new Date().toISOString(),
-            });
+            applyMigrationV16EscalationSource(db);
+            recordSchemaVersion(db, 16);
         }
         if (currentVersion < 17) {
-            // ADR-011 Phase 2: mid-execution escalation — columns on the tasks table.
-            ensureColumn(db, "tasks", "blocker_source", `ALTER TABLE tasks ADD COLUMN blocker_source TEXT NOT NULL DEFAULT ''`);
-            ensureColumn(db, "tasks", "escalation_pending", `ALTER TABLE tasks ADD COLUMN escalation_pending INTEGER NOT NULL DEFAULT 0`);
-            ensureColumn(db, "tasks", "escalation_awaiting_review", `ALTER TABLE tasks ADD COLUMN escalation_awaiting_review INTEGER NOT NULL DEFAULT 0`);
-            ensureColumn(db, "tasks", "escalation_artifact_path", `ALTER TABLE tasks ADD COLUMN escalation_artifact_path TEXT DEFAULT NULL`);
-            ensureColumn(db, "tasks", "escalation_override_applied_at", `ALTER TABLE tasks ADD COLUMN escalation_override_applied_at TEXT DEFAULT NULL`);
-            db.exec("CREATE INDEX IF NOT EXISTS idx_tasks_escalation_pending ON tasks(milestone_id, slice_id, escalation_pending)");
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": 17,
-                ":applied_at": new Date().toISOString(),
-            });
+            applyMigrationV17TaskEscalation(db);
+            recordSchemaVersion(db, 17);
         }
         if (currentVersion < 18) {
-            // Memory system Phase 2: scope + tags on memories, plus memory_sources
-            // table for raw ingested content (notes, files, URLs, artifacts).
-            ensureColumn(db, "memories", "scope", `ALTER TABLE memories ADD COLUMN scope TEXT NOT NULL DEFAULT 'project'`);
-            ensureColumn(db, "memories", "tags", `ALTER TABLE memories ADD COLUMN tags TEXT NOT NULL DEFAULT '[]'`);
-            db.exec(`
-        CREATE TABLE IF NOT EXISTS memory_sources (
-          id TEXT PRIMARY KEY,
-          kind TEXT NOT NULL,
-          uri TEXT,
-          title TEXT,
-          content TEXT NOT NULL,
-          content_hash TEXT NOT NULL UNIQUE,
-          imported_at TEXT NOT NULL,
-          scope TEXT NOT NULL DEFAULT 'project',
-          tags TEXT NOT NULL DEFAULT '[]'
-        )
-      `);
-            // If memory_sources already existed before v18 (created by an earlier
-            // version of initSchema that lacked scope/tags), add the missing columns.
-            ensureColumn(db, "memory_sources", "scope", `ALTER TABLE memory_sources ADD COLUMN scope TEXT NOT NULL DEFAULT 'project'`);
-            ensureColumn(db, "memory_sources", "tags", `ALTER TABLE memory_sources ADD COLUMN tags TEXT NOT NULL DEFAULT '[]'`);
-            db.exec("CREATE INDEX IF NOT EXISTS idx_memories_scope ON memories(scope)");
-            db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_kind ON memory_sources(kind)");
-            db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_scope ON memory_sources(scope)");
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": 18,
-                ":applied_at": new Date().toISOString(),
-            });
+            applyMigrationV18MemorySources(db);
+            recordSchemaVersion(db, 18);
         }
         if (currentVersion < 19) {
-            // Memory system Phase 3: embeddings + FTS5 for hybrid retrieval.
-            db.exec(`
-        CREATE TABLE IF NOT EXISTS memory_embeddings (
-          memory_id TEXT PRIMARY KEY,
-          model TEXT NOT NULL,
-          dim INTEGER NOT NULL,
-          vector BLOB NOT NULL,
-          updated_at TEXT NOT NULL
-        )
-      `);
-            tryCreateMemoriesFts(db);
-            // Backfill FTS5 with any existing memories (triggers only cover future writes).
-            if (isMemoriesFtsAvailable(db)) {
-                try {
-                    db.exec(`INSERT INTO memories_fts(rowid, content) SELECT seq, content FROM memories`);
-                }
-                catch (err) {
-                    logWarning("db", `FTS5 backfill failed: ${err.message}`);
-                }
-            }
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": 19,
-                ":applied_at": new Date().toISOString(),
+            applyMigrationV19MemoryFts(db, {
+                tryCreateMemoriesFts,
+                isMemoriesFtsAvailable,
+                backfillMemoriesFts,
+                logWarning,
             });
+            recordSchemaVersion(db, 19);
         }
         if (currentVersion < 20) {
-            // Memory system Phase 4: knowledge-graph relations between memories.
-            db.exec(`
-        CREATE TABLE IF NOT EXISTS memory_relations (
-          from_id TEXT NOT NULL,
-          to_id TEXT NOT NULL,
-          rel TEXT NOT NULL,
-          confidence REAL NOT NULL DEFAULT 0.8,
-          created_at TEXT NOT NULL,
-          PRIMARY KEY (from_id, to_id, rel)
-        )
-      `);
-            db.exec("CREATE INDEX IF NOT EXISTS idx_memory_relations_from ON memory_relations(from_id)");
-            db.exec("CREATE INDEX IF NOT EXISTS idx_memory_relations_to ON memory_relations(to_id)");
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": 20,
-                ":applied_at": new Date().toISOString(),
-            });
+            applyMigrationV20MemoryRelations(db);
+            recordSchemaVersion(db, 20);
         }
         if (currentVersion < 21) {
-            // ADR-013 Step 2: preserve structured fields (gsd_save_decision's
-            // scope/decision/choice/rationale/made_by/revisable) on memories rows so
-            // the eventual decisions->memories cutover does not lose schema fidelity.
-            // Nullable JSON column — existing rows stay NULL until backfilled in Step 5.
-            // Use ensureColumn for race-safety (matches v15-v18 pattern; bare ALTER
-            // throws "duplicate column" on the loser of a concurrent open race even
-            // though the transaction wrapper protects the schema_version row).
-            ensureColumn(db, "memories", "structured_fields", "ALTER TABLE memories ADD COLUMN structured_fields TEXT DEFAULT NULL");
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": 21,
-                ":applied_at": new Date().toISOString(),
-            });
+            applyMigrationV21StructuredMemories(db);
+            recordSchemaVersion(db, 21);
         }
         if (currentVersion < 22) {
-            // v22: Repair quality_gates tables that were created by the broken v12
-            // migration (which used COALESCE(task_id, '') as a PK expression — invalid
-            // SQLite DDL). Those DBs have task_id nullable (dflt_value NULL, notnull 0).
-            // Rebuild the table with the correct schema, migrating existing rows via
-            // COALESCE so no data is lost.
-            const qgInfo = db.prepare("PRAGMA table_info(quality_gates)").all();
-            const taskIdCol = qgInfo.find((r) => r["name"] === "task_id");
-            const needsRepair = taskIdCol && (taskIdCol["notnull"] === 0 || taskIdCol["notnull"] === "0");
-            if (needsRepair) {
-                db.exec(`
-          CREATE TABLE quality_gates_new (
-            milestone_id TEXT NOT NULL,
-            slice_id TEXT NOT NULL,
-            gate_id TEXT NOT NULL,
-            scope TEXT NOT NULL DEFAULT 'slice',
-            task_id TEXT NOT NULL DEFAULT '',
-            status TEXT NOT NULL DEFAULT 'pending',
-            verdict TEXT NOT NULL DEFAULT '',
-            rationale TEXT NOT NULL DEFAULT '',
-            findings TEXT NOT NULL DEFAULT '',
-            evaluated_at TEXT DEFAULT NULL,
-            PRIMARY KEY (milestone_id, slice_id, gate_id, task_id),
-            FOREIGN KEY (milestone_id, slice_id) REFERENCES slices(milestone_id, id)
-          )
-        `);
-                db.exec(`
-          INSERT OR IGNORE INTO quality_gates_new
-            (milestone_id, slice_id, gate_id, scope, task_id, status, verdict, rationale, findings, evaluated_at)
-          SELECT milestone_id, slice_id, gate_id, scope, COALESCE(task_id, ''), status, verdict, rationale, findings, evaluated_at
-          FROM quality_gates
-        `);
-                db.exec("DROP TABLE quality_gates");
-                db.exec("ALTER TABLE quality_gates_new RENAME TO quality_gates");
-                db.exec("CREATE INDEX IF NOT EXISTS idx_quality_gates_pending ON quality_gates(milestone_id, slice_id, status)");
-            }
-            // Ensure scope column exists on quality_gates and assessments (guard
-            // against DBs that somehow lack it after a partial migration).
-            ensureColumn(db, "quality_gates", "scope", "ALTER TABLE quality_gates ADD COLUMN scope TEXT NOT NULL DEFAULT 'slice'");
-            ensureColumn(db, "assessments", "scope", "ALTER TABLE assessments ADD COLUMN scope TEXT NOT NULL DEFAULT ''");
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": 22,
-                ":applied_at": new Date().toISOString(),
-            });
+            applyMigrationV22QualityGateRepair(db, { copyQualityGateRowsToRepairedTable });
+            recordSchemaVersion(db, 22);
         }
         if (currentVersion < 23) {
-            // v23: milestone queue ordering moves into the canonical DB. The
-            // historical QUEUE-ORDER.json file remains a projection, but runtime
-            // derivation must not read it as authoritative state.
-            ensureColumn(db, "milestones", "sequence", "ALTER TABLE milestones ADD COLUMN sequence INTEGER DEFAULT 0");
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": 23,
-                ":applied_at": new Date().toISOString(),
-            });
+            applyMigrationV23MilestoneQueue(db);
+            recordSchemaVersion(db, 23);
         }
         if (currentVersion < 24) {
             // v24: auto-mode coordination tables. See createCoordinationTablesV24
@@ -1281,19 +239,25 @@ function migrateSchema(db) {
             // helper runs in the fresh-install path); for upgraded DBs this is
             // the only place these tables get created.
             createCoordinationTablesV24(db);
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": 24,
-                ":applied_at": new Date().toISOString(),
-            });
+            recordSchemaVersion(db, 24);
         }
         if (currentVersion < 25) {
             // v25: runtime_kv non-correctness-critical key-value storage. See
             // createRuntimeKvTableV25 for the full schema + invariants.
             createRuntimeKvTableV25(db);
-            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
-                ":version": 25,
-                ":applied_at": new Date().toISOString(),
-            });
+            recordSchemaVersion(db, 25);
+        }
+        if (currentVersion < 26) {
+            applyMigrationV26MilestoneCommitAttributions(db);
+            recordSchemaVersion(db, 26);
+        }
+        if (currentVersion < 27) {
+            applyMigrationV27ArtifactHash(db);
+            recordSchemaVersion(db, 27);
+        }
+        if (currentVersion < 28) {
+            applyMigrationV28MemoryLastHitAt(db);
+            recordSchemaVersion(db, 28);
         }
         db.exec("COMMIT");
     }
@@ -1306,9 +270,7 @@ let currentDb = null;
 let currentPath = null;
 let currentPid = 0;
 let _exitHandlerRegistered = false;
-let _dbOpenAttempted = false;
-let _lastDbError = null;
-let _lastDbPhase = null;
+const _dbOpenState = createDbOpenState();
 /**
  * Identity key of the workspace whose connection is currently active
  * (currentDb). Set by openDatabaseByWorkspace(); null when the active
@@ -1328,10 +290,33 @@ let _currentIdentityKey = null;
  * The cache allows fast re-activation of a previously opened connection when
  * callers switch between known workspaces via openDatabaseByWorkspace().
  */
-const _dbCache = new Map();
+const _dbCache = createDbConnectionCache();
 /** Test helper: expose the internal cache for inspection. Not for production use. */
 export function _getDbCache() {
-    return _dbCache;
+    return _dbCache.asReadonlyMap();
+}
+function closeCachedConnection(entry, source) {
+    try {
+        entry.db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+    }
+    catch (e) {
+        if (source === "workspace")
+            logWarning("db", `WAL checkpoint (byWorkspace) failed: ${e.message}`);
+    }
+    try {
+        entry.db.exec("PRAGMA incremental_vacuum(64)");
+    }
+    catch (e) {
+        if (source === "workspace")
+            logWarning("db", `incremental vacuum (byWorkspace) failed: ${e.message}`);
+    }
+    try {
+        entry.db.close();
+    }
+    catch (e) {
+        if (source === "workspace")
+            logWarning("db", `database close (byWorkspace) failed: ${e.message}`);
+    }
 }
 /**
  * Close and evict every entry in the workspace connection cache, then call
@@ -1343,23 +328,7 @@ export function _getDbCache() {
  */
 export function closeAllDatabases() {
     // Close all non-active cached connections first.
-    for (const [key, entry] of _dbCache) {
-        if (entry.db === currentDb)
-            continue; // handled by closeDatabase() below
-        _dbCache.delete(key);
-        try {
-            entry.db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
-        }
-        catch { /* best-effort */ }
-        try {
-            entry.db.exec("PRAGMA incremental_vacuum(64)");
-        }
-        catch { /* best-effort */ }
-        try {
-            entry.db.close();
-        }
-        catch { /* best-effort */ }
-    }
+    _dbCache.closeNonActive(currentDb, (entry) => closeCachedConnection(entry, "all"));
     closeDatabase();
 }
 /**
@@ -1387,7 +356,7 @@ export function openDatabaseByWorkspace(workspace) {
         currentDb = cached.db;
         currentPath = cached.dbPath;
         currentPid = process.pid;
-        _dbOpenAttempted = true;
+        _dbOpenState.markAttempted();
         _currentIdentityKey = key;
         return true;
     }
@@ -1476,29 +445,12 @@ export function closeDatabaseByWorkspace(workspace) {
     }
     else {
         // Connection was displaced by a later open; close the adapter directly.
-        try {
-            cached.db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
-        }
-        catch (e) {
-            logWarning("db", `WAL checkpoint (byWorkspace) failed: ${e.message}`);
-        }
-        try {
-            cached.db.exec("PRAGMA incremental_vacuum(64)");
-        }
-        catch (e) {
-            logWarning("db", `incremental vacuum (byWorkspace) failed: ${e.message}`);
-        }
-        try {
-            cached.db.close();
-        }
-        catch (e) {
-            logWarning("db", `database close (byWorkspace) failed: ${e.message}`);
-        }
+        closeCachedConnection(cached, "workspace");
     }
 }
 export function getDbProvider() {
-    loadProvider();
-    return providerName;
+    providerLoader.load();
+    return providerLoader.getProviderName();
 }
 export function isDbAvailable() {
     return currentDb !== null;
@@ -1510,59 +462,46 @@ export function isDbAvailable() {
  * trigger a false degraded-mode warning.
  */
 export function wasDbOpenAttempted() {
-    return _dbOpenAttempted;
+    return _dbOpenState.snapshot().attempted;
 }
 export function getDbStatus() {
-    loadProvider();
+    providerLoader.load();
+    const openState = _dbOpenState.snapshot();
     return {
         available: currentDb !== null,
-        provider: providerName,
-        attempted: _dbOpenAttempted,
-        lastError: _lastDbError,
-        lastPhase: _lastDbPhase,
+        provider: providerLoader.getProviderName(),
+        attempted: openState.attempted,
+        lastError: openState.lastError,
+        lastPhase: openState.lastPhase,
     };
 }
 export function openDatabase(path) {
-    _dbOpenAttempted = true;
+    _dbOpenState.markAttempted();
     if (currentDb && currentPath !== path)
         closeDatabase();
     if (currentDb && currentPath === path)
         return true;
     // Reset error state only when a new open attempt is actually going to run.
-    _lastDbError = null;
-    _lastDbPhase = null;
+    _dbOpenState.clearError();
     let rawDb;
-    let fallbackProvider = null;
-    let fallbackModule = null;
+    let fallbackOpen = null;
     try {
-        rawDb = openRawDb(path);
+        rawDb = providerLoader.openRaw(path);
     }
     catch (primaryErr) {
-        _lastDbPhase = "open";
-        _lastDbError = primaryErr instanceof Error ? primaryErr : new Error(String(primaryErr));
+        _dbOpenState.recordError("open", primaryErr);
         // node:sqlite loaded but failed to open this file — try better-sqlite3 as fallback.
-        if (providerName === "node:sqlite") {
-            try {
-                const mod = _require(BETTER_SQLITE3_PACKAGE);
-                const Db = (mod && mod.default) ? mod.default : mod;
-                if (typeof Db === "function") {
-                    rawDb = new Db(path);
-                    fallbackProvider = "better-sqlite3";
-                    fallbackModule = Db;
-                    _lastDbError = null;
-                    _lastDbPhase = null;
-                }
-            }
-            catch {
-                // fallback unavailable; surface original error
-            }
+        fallbackOpen = providerLoader.tryOpenBetterSqliteFallback(path);
+        if (fallbackOpen) {
+            rawDb = fallbackOpen.rawDb;
+            _dbOpenState.clearError();
         }
         if (!rawDb)
             throw primaryErr;
     }
     if (!rawDb)
         return false;
-    const adapter = createAdapter(rawDb);
+    const adapter = createDbAdapter(rawDb);
     const fileBacked = path !== ":memory:";
     try {
         initSchema(adapter, fileBacked);
@@ -1577,8 +516,7 @@ export function openDatabase(path) {
                 process.stderr.write("gsd-db: recovered corrupt database via VACUUM\n");
             }
             catch (retryErr) {
-                _lastDbPhase = "vacuum-recovery";
-                _lastDbError = retryErr instanceof Error ? retryErr : new Error(String(retryErr));
+                _dbOpenState.recordError("vacuum-recovery", retryErr);
                 try {
                     adapter.close();
                 }
@@ -1589,8 +527,7 @@ export function openDatabase(path) {
             }
         }
         else {
-            _lastDbPhase = "initSchema";
-            _lastDbError = err instanceof Error ? err : new Error(String(err));
+            _dbOpenState.recordError("initSchema", err);
             try {
                 adapter.close();
             }
@@ -1601,10 +538,8 @@ export function openDatabase(path) {
         }
     }
     // Commit fallback provider switch only after open + schema both succeeded.
-    if (fallbackProvider) {
-        providerName = fallbackProvider;
-        providerModule = fallbackModule;
-    }
+    if (fallbackOpen)
+        providerLoader.commitFallback(fallbackOpen);
     currentDb = adapter;
     currentPath = path;
     currentPid = process.pid;
@@ -1653,9 +588,7 @@ export function closeDatabase() {
     }
     // Reset session-scoped state unconditionally so stale error info from a
     // failed open doesn't persist into the next open attempt or status check.
-    _dbOpenAttempted = false;
-    _lastDbError = null;
-    _lastDbPhase = null;
+    _dbOpenState.reset();
 }
 /**
  * Re-open the active database connection from disk.
@@ -1708,7 +641,15 @@ export function checkpointDatabase() {
         logWarning("db", `WAL checkpoint failed: ${e.message}`);
     }
 }
-let _txDepth = 0;
+const _transactionRunner = createDbTransactionRunner();
+function createTransactionControls(db) {
+    return {
+        begin: () => db.exec("BEGIN"),
+        beginRead: () => db.exec("BEGIN DEFERRED"),
+        commit: () => db.exec("COMMIT"),
+        rollback: () => db.exec("ROLLBACK"),
+    };
+}
 /**
  * Whether the current call is running inside an active SQLite transaction.
  * Statement-time recovery paths (e.g. VACUUM retry on a malformed memory
@@ -1716,36 +657,12 @@ let _txDepth = 0;
  * and would mask the original error with a secondary "cannot VACUUM" throw.
  */
 export function isInTransaction() {
-    return _txDepth > 0;
+    return _transactionRunner.isInTransaction();
 }
 export function transaction(fn) {
     if (!currentDb)
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
-    // Re-entrant: if already inside a transaction, just run fn() without
-    // starting a new one. SQLite does not support nested BEGIN/COMMIT.
-    if (_txDepth > 0) {
-        _txDepth++;
-        try {
-            return fn();
-        }
-        finally {
-            _txDepth--;
-        }
-    }
-    currentDb.exec("BEGIN");
-    _txDepth++;
-    try {
-        const result = fn();
-        currentDb.exec("COMMIT");
-        return result;
-    }
-    catch (err) {
-        currentDb.exec("ROLLBACK");
-        throw err;
-    }
-    finally {
-        _txDepth--;
-    }
+    return _transactionRunner.transaction(createTransactionControls(currentDb), fn);
 }
 /**
  * Wrap a block of reads in a DEFERRED transaction so that all SELECTs observe
@@ -1757,39 +674,14 @@ export function transaction(fn) {
 export function readTransaction(fn) {
     if (!currentDb)
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
-    if (_txDepth > 0) {
-        _txDepth++;
-        try {
-            return fn();
-        }
-        finally {
-            _txDepth--;
-        }
-    }
-    currentDb.exec("BEGIN DEFERRED");
-    _txDepth++;
-    try {
-        const result = fn();
-        currentDb.exec("COMMIT");
-        return result;
-    }
-    catch (err) {
-        try {
-            currentDb.exec("ROLLBACK");
-        }
-        catch (rollbackErr) {
-            // A failed ROLLBACK after a failed read is a split-brain signal —
-            // the transaction is in an indeterminate state. Surface it via the
-            // logger instead of swallowing it.
-            logError("db", "snapshotState ROLLBACK failed", {
-                error: rollbackErr.message,
-            });
-        }
-        throw err;
-    }
-    finally {
-        _txDepth--;
-    }
+    return _transactionRunner.readTransaction(createTransactionControls(currentDb), fn, (rollbackErr) => {
+        // A failed ROLLBACK after a failed read is a split-brain signal —
+        // the transaction is in an indeterminate state. Surface it via the
+        // logger instead of swallowing it.
+        logError("db", "snapshotState ROLLBACK failed", {
+            error: rollbackErr.message,
+        });
+    });
 }
 export function insertDecision(d) {
     if (!currentDb)
@@ -1814,37 +706,13 @@ export function getDecisionById(id) {
     const row = currentDb.prepare("SELECT * FROM decisions WHERE id = ?").get(id);
     if (!row)
         return null;
-    return {
-        seq: row["seq"],
-        id: row["id"],
-        when_context: row["when_context"],
-        scope: row["scope"],
-        decision: row["decision"],
-        choice: row["choice"],
-        rationale: row["rationale"],
-        revisable: row["revisable"],
-        made_by: row["made_by"] ?? "agent",
-        source: row["source"] ?? "discussion",
-        superseded_by: row["superseded_by"] ?? null,
-    };
+    return rowToDecision(row);
 }
 export function getActiveDecisions() {
     if (!currentDb)
         return [];
     const rows = currentDb.prepare("SELECT * FROM active_decisions").all();
-    return rows.map((row) => ({
-        seq: row["seq"],
-        id: row["id"],
-        when_context: row["when_context"],
-        scope: row["scope"],
-        decision: row["decision"],
-        choice: row["choice"],
-        rationale: row["rationale"],
-        revisable: row["revisable"],
-        made_by: row["made_by"] ?? "agent",
-        source: row["source"] ?? "discussion",
-        superseded_by: null,
-    }));
+    return rows.map(rowToActiveDecision);
 }
 export function insertRequirement(r) {
     if (!currentDb)
@@ -1871,39 +739,13 @@ export function getRequirementById(id) {
     const row = currentDb.prepare("SELECT * FROM requirements WHERE id = ?").get(id);
     if (!row)
         return null;
-    return {
-        id: row["id"],
-        class: row["class"],
-        status: row["status"],
-        description: row["description"],
-        why: row["why"],
-        source: row["source"],
-        primary_owner: row["primary_owner"],
-        supporting_slices: row["supporting_slices"],
-        validation: row["validation"],
-        notes: row["notes"],
-        full_content: row["full_content"],
-        superseded_by: row["superseded_by"] ?? null,
-    };
+    return rowToRequirement(row);
 }
 export function getActiveRequirements() {
     if (!currentDb)
         return [];
     const rows = currentDb.prepare("SELECT * FROM active_requirements").all();
-    return rows.map((row) => ({
-        id: row["id"],
-        class: row["class"],
-        status: row["status"],
-        description: row["description"],
-        why: row["why"],
-        source: row["source"],
-        primary_owner: row["primary_owner"],
-        supporting_slices: row["supporting_slices"],
-        validation: row["validation"],
-        notes: row["notes"],
-        full_content: row["full_content"],
-        superseded_by: null,
-    }));
+    return rows.map(rowToActiveRequirement);
 }
 export function getRequirementCounts() {
     if (!currentDb) {
@@ -1912,23 +754,7 @@ export function getRequirementCounts() {
     const rows = currentDb
         .prepare("SELECT lower(status) as status, COUNT(*) as count FROM requirements GROUP BY lower(status)")
         .all();
-    const counts = { active: 0, validated: 0, deferred: 0, outOfScope: 0, blocked: 0, total: 0 };
-    for (const row of rows) {
-        const status = String(row["status"] ?? "");
-        const count = Number(row["count"] ?? 0);
-        counts.total += count;
-        if (status === "active")
-            counts.active += count;
-        else if (status === "validated")
-            counts.validated += count;
-        else if (status === "deferred")
-            counts.deferred += count;
-        else if (status === "out-of-scope" || status === "out_of_scope")
-            counts.outOfScope += count;
-        else if (status === "blocked")
-            counts.blocked += count;
-    }
-    return counts;
+    return rowsToRequirementCounts(rows);
 }
 export function getDbOwnerPid() {
     return currentPid;
@@ -1940,9 +766,7 @@ export function _getAdapter() {
     return currentDb;
 }
 export function _resetProvider() {
-    loadAttempted = false;
-    providerModule = null;
-    providerName = null;
+    providerLoader.reset();
 }
 export function upsertDecision(d) {
     if (!currentDb)
@@ -2006,8 +830,9 @@ export function clearArtifacts() {
 export function insertArtifact(a) {
     if (!currentDb)
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
-    currentDb.prepare(`INSERT OR REPLACE INTO artifacts (path, artifact_type, milestone_id, slice_id, task_id, full_content, imported_at)
-     VALUES (:path, :artifact_type, :milestone_id, :slice_id, :task_id, :full_content, :imported_at)`).run({
+    const contentHash = createHash("sha256").update(a.full_content).digest("hex");
+    currentDb.prepare(`INSERT OR REPLACE INTO artifacts (path, artifact_type, milestone_id, slice_id, task_id, full_content, imported_at, content_hash)
+     VALUES (:path, :artifact_type, :milestone_id, :slice_id, :task_id, :full_content, :imported_at, :content_hash)`).run({
         ":path": a.path,
         ":artifact_type": a.artifact_type,
         ":milestone_id": a.milestone_id,
@@ -2015,6 +840,7 @@ export function insertArtifact(a) {
         ":task_id": a.task_id,
         ":full_content": a.full_content,
         ":imported_at": new Date().toISOString(),
+        ":content_hash": contentHash,
     });
 }
 export function insertMilestone(m) {
@@ -2304,30 +1130,6 @@ export function upsertTaskPlanning(milestoneId, sliceId, taskId, planning) {
         ":full_plan_md": planning.fullPlanMd ?? null,
     });
 }
-function rowToSlice(row) {
-    return {
-        milestone_id: row["milestone_id"],
-        id: row["id"],
-        title: row["title"],
-        status: row["status"],
-        risk: row["risk"],
-        depends: JSON.parse(row["depends"] || "[]"),
-        demo: row["demo"] ?? "",
-        created_at: row["created_at"],
-        completed_at: row["completed_at"] ?? null,
-        full_summary_md: row["full_summary_md"] ?? "",
-        full_uat_md: row["full_uat_md"] ?? "",
-        goal: row["goal"] ?? "",
-        success_criteria: row["success_criteria"] ?? "",
-        proof_level: row["proof_level"] ?? "",
-        integration_closure: row["integration_closure"] ?? "",
-        observability_impact: row["observability_impact"] ?? "",
-        sequence: row["sequence"] ?? 0,
-        replan_triggered_at: row["replan_triggered_at"] ?? null,
-        is_sketch: row["is_sketch"] ?? 0,
-        sketch_scope: row["sketch_scope"] ?? "",
-    };
-}
 export function getSlice(milestoneId, sliceId) {
     if (!currentDb)
         return null;
@@ -2357,82 +1159,6 @@ export function setSliceSummaryMd(milestoneId, sliceId, summaryMd, uatMd) {
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
     currentDb.prepare(`UPDATE slices SET full_summary_md = :summary_md, full_uat_md = :uat_md WHERE milestone_id = :mid AND id = :sid`).run({ ":mid": milestoneId, ":sid": sliceId, ":summary_md": summaryMd, ":uat_md": uatMd });
 }
-function parseTaskArrayColumn(raw) {
-    if (typeof raw !== "string" || raw.trim() === "")
-        return [];
-    try {
-        const parsed = JSON.parse(raw);
-        if (Array.isArray(parsed))
-            return parsed.map((value) => String(value));
-        if (parsed === null || parsed === undefined || parsed === "")
-            return [];
-        return [String(parsed)];
-    }
-    catch {
-        // Older/corrupt rows may contain comma-separated strings instead of JSON.
-        return raw
-            .split(",")
-            .map((value) => value.trim())
-            .filter(Boolean);
-    }
-}
-function rowToTask(row) {
-    const parseTaskArray = (value) => {
-        if (Array.isArray(value)) {
-            return value.filter((entry) => typeof entry === "string");
-        }
-        if (typeof value !== "string")
-            return [];
-        const trimmed = value.trim();
-        if (!trimmed)
-            return [];
-        try {
-            const parsed = JSON.parse(trimmed);
-            if (Array.isArray(parsed)) {
-                return parsed.filter((entry) => typeof entry === "string");
-            }
-            if (typeof parsed === "string" && parsed.trim()) {
-                return [parsed.trim()];
-            }
-        }
-        catch {
-            // Older/corrupt DB rows may contain raw comma-separated paths instead of JSON arrays.
-        }
-        return trimmed.split(",").map((entry) => entry.trim()).filter(Boolean);
-    };
-    return {
-        milestone_id: row["milestone_id"],
-        slice_id: row["slice_id"],
-        id: row["id"],
-        title: row["title"],
-        status: row["status"],
-        one_liner: row["one_liner"],
-        narrative: row["narrative"],
-        verification_result: row["verification_result"],
-        duration: row["duration"],
-        completed_at: row["completed_at"] ?? null,
-        blocker_discovered: row["blocker_discovered"] === 1,
-        deviations: row["deviations"],
-        known_issues: row["known_issues"],
-        key_files: parseTaskArrayColumn(row["key_files"]),
-        key_decisions: parseTaskArrayColumn(row["key_decisions"]),
-        full_summary_md: row["full_summary_md"],
-        description: row["description"] ?? "",
-        estimate: row["estimate"] ?? "",
-        files: parseTaskArray(row["files"]),
-        verify: row["verify"] ?? "",
-        inputs: parseTaskArray(row["inputs"]),
-        expected_output: parseTaskArray(row["expected_output"]),
-        observability_impact: row["observability_impact"] ?? "",
-        full_plan_md: row["full_plan_md"] ?? "",
-        sequence: row["sequence"] ?? 0,
-        blocker_source: row["blocker_source"] ?? "",
-        escalation_pending: row["escalation_pending"] ?? 0,
-        escalation_awaiting_review: row["escalation_awaiting_review"] ?? 0,
-        escalation_artifact_path: row["escalation_artifact_path"] ?? null,
-        escalation_override_applied_at: row["escalation_override_applied_at"] ?? null,
-    };
-}
 export function getTask(milestoneId, sliceId, taskId) {
     if (!currentDb)
         return null;
@@ -2447,6 +1173,47 @@ export function getSliceTasks(milestoneId, sliceId) {
     const rows = currentDb.prepare("SELECT * FROM tasks WHERE milestone_id = :mid AND slice_id = :sid ORDER BY sequence, id").all({ ":mid": milestoneId, ":sid": sliceId });
     return rows.map(rowToTask);
 }
+export function getCompletedMilestoneTaskFileHints(milestoneId) {
+    if (!currentDb)
+        return [];
+    const rows = currentDb.prepare(`SELECT files, key_files
+     FROM tasks
+     WHERE milestone_id = :mid AND status IN ('complete', 'done')`).all({ ":mid": milestoneId });
+    const hints = new Set();
+    for (const row of rows) {
+        for (const raw of [row["files"], row["key_files"]]) {
+            for (const file of parseStringArrayColumn(raw)) {
+                const normalized = normalizeRepoPath(file);
+                if (normalized)
+                    hints.add(normalized);
+            }
+        }
+    }
+    return [...hints];
+}
+function parseStringArrayColumn(raw) {
+    if (Array.isArray(raw))
+        return raw.filter((entry) => typeof entry === "string");
+    if (typeof raw !== "string")
+        return [];
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return [];
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (Array.isArray(parsed))
+            return parsed.filter((entry) => typeof entry === "string");
+        if (typeof parsed === "string")
+            return [parsed];
+    }
+    catch {
+        return trimmed.split(",");
+    }
+    return [];
+}
+function normalizeRepoPath(file) {
+    return file.trim().replace(/\\/g, "/").replace(/^\.\/+/, "");
+}
 // ─── ADR-011 Phase 2 escalation helpers ──────────────────────────────────
 /** Set pause-on-escalation state on a completed task. Mutually exclusive with awaiting_review. */
 export function setTaskEscalationPending(milestoneId, sliceId, taskId, artifactPath) {
@@ -2557,39 +1324,6 @@ export function getVerificationEvidence(milestoneId, sliceId, taskId) {
     const rows = currentDb.prepare("SELECT * FROM verification_evidence WHERE milestone_id = :mid AND slice_id = :sid AND task_id = :tid ORDER BY id").all({ ":mid": milestoneId, ":sid": sliceId, ":tid": taskId });
     return rows;
 }
-function rowToMilestone(row) {
-    return {
-        id: row["id"],
-        title: row["title"],
-        status: row["status"],
-        depends_on: JSON.parse(row["depends_on"] || "[]"),
-        created_at: row["created_at"],
-        completed_at: row["completed_at"] ?? null,
-        vision: row["vision"] ?? "",
-        success_criteria: JSON.parse(row["success_criteria"] || "[]"),
-        key_risks: JSON.parse(row["key_risks"] || "[]"),
-        proof_strategy: JSON.parse(row["proof_strategy"] || "[]"),
-        verification_contract: row["verification_contract"] ?? "",
-        verification_integration: row["verification_integration"] ?? "",
-        verification_operational: row["verification_operational"] ?? "",
-        verification_uat: row["verification_uat"] ?? "",
-        definition_of_done: JSON.parse(row["definition_of_done"] || "[]"),
-        requirement_coverage: row["requirement_coverage"] ?? "",
-        boundary_map_markdown: row["boundary_map_markdown"] ?? "",
-        sequence: Number(row["sequence"] ?? 0),
-    };
-}
-function rowToArtifact(row) {
-    return {
-        path: row["path"],
-        artifact_type: row["artifact_type"],
-        milestone_id: row["milestone_id"] ?? null,
-        slice_id: row["slice_id"] ?? null,
-        task_id: row["task_id"] ?? null,
-        full_content: row["full_content"],
-        imported_at: row["imported_at"],
-    };
-}
 export function getAllMilestones() {
     if (!currentDb)
         return [];
@@ -2689,13 +1423,13 @@ export function getActiveMilestoneIdFromDb() {
     const row = currentDb.prepare("SELECT id, status FROM milestones WHERE status NOT IN ('complete', 'parked') ORDER BY id LIMIT 1").get();
     if (!row)
         return null;
-    return { id: row["id"], status: row["status"] };
+    return rowToIdStatusSummary(row);
 }
 /** Fast slice status check — avoids deserializing JSON depends/planning fields. */
 export function getSliceStatusSummary(milestoneId) {
     if (!currentDb)
         return [];
-    return currentDb.prepare("SELECT id, status FROM slices WHERE milestone_id = :mid ORDER BY sequence, id").all({ ":mid": milestoneId }).map((r) => ({ id: r["id"], status: r["status"] }));
+    return currentDb.prepare("SELECT id, status FROM slices WHERE milestone_id = :mid ORDER BY sequence, id").all({ ":mid": milestoneId }).map(rowToIdStatusSummary);
 }
 /** Fast task status check — avoids deserializing JSON arrays and large text fields. */
 export function getActiveTaskIdFromDb(milestoneId, sliceId) {
@@ -2704,20 +1438,18 @@ export function getActiveTaskIdFromDb(milestoneId, sliceId) {
     const row = currentDb.prepare("SELECT id, status, title FROM tasks WHERE milestone_id = :mid AND slice_id = :sid AND status NOT IN ('complete', 'done') ORDER BY sequence, id LIMIT 1").get({ ":mid": milestoneId, ":sid": sliceId });
     if (!row)
         return null;
-    return { id: row["id"], status: row["status"], title: row["title"] };
+    return rowToActiveTaskSummary(row);
 }
 /** Count tasks by status for a slice — useful for progress reporting without full row load. */
 export function getSliceTaskCounts(milestoneId, sliceId) {
     if (!currentDb)
-        return { total: 0, done: 0, pending: 0 };
+        return emptyTaskStatusCounts();
     const row = currentDb.prepare(`SELECT
        COUNT(*) as total,
        SUM(CASE WHEN status IN ('complete', 'done') THEN 1 ELSE 0 END) as done,
        SUM(CASE WHEN status NOT IN ('complete', 'done') THEN 1 ELSE 0 END) as pending
      FROM tasks WHERE milestone_id = :mid AND slice_id = :sid`).get({ ":mid": milestoneId, ":sid": sliceId });
-    if (!row)
-        return { total: 0, done: 0, pending: 0 };
-    return { total: row["total"] ?? 0, done: row["done"] ?? 0, pending: row["pending"] ?? 0 };
+    return rowToTaskStatusCounts(row);
 }
 // ─── Slice Dependencies (junction table) ─────────────────────────────────
 /** Sync the slice_dependencies junction table from a slice's JSON depends array. */
@@ -2733,7 +1465,8 @@ export function syncSliceDependencies(milestoneId, sliceId, depends) {
 export function getDependentSlices(milestoneId, sliceId) {
     if (!currentDb)
         return [];
-    return currentDb.prepare("SELECT slice_id FROM slice_dependencies WHERE milestone_id = :mid AND depends_on_slice_id = :sid").all({ ":mid": milestoneId, ":sid": sliceId }).map((r) => r["slice_id"]);
+    const rows = currentDb.prepare("SELECT slice_id FROM slice_dependencies WHERE milestone_id = :mid AND depends_on_slice_id = :sid").all({ ":mid": milestoneId, ":sid": sliceId });
+    return rowsToStringColumn(rows, "slice_id");
 }
 // ─── Worktree DB Helpers ──────────────────────────────────────────────────
 export function copyWorktreeDb(srcDbPath, destDbPath) {
@@ -2799,6 +1532,13 @@ export function reconcileWorktreeDb(mainDbPath, worktreeDbPath) {
             const hasEscalationAwaiting = wtTaskInfo.some((col) => col["name"] === "escalation_awaiting_review");
             const hasEscalationArtifact = wtTaskInfo.some((col) => col["name"] === "escalation_artifact_path");
             const hasEscalationOverride = wtTaskInfo.some((col) => col["name"] === "escalation_override_applied_at");
+            const wtArtifactInfo = adapter.prepare("PRAGMA wt.table_info('artifacts')").all();
+            const hasArtifactContentHash = wtArtifactInfo.some((col) => col["name"] === "content_hash");
+            const wtMemoryInfo = adapter.prepare("PRAGMA wt.table_info('memories')").all();
+            const hasMemoryScope = wtMemoryInfo.some((col) => col["name"] === "scope");
+            const hasMemoryTags = wtMemoryInfo.some((col) => col["name"] === "tags");
+            const hasMemoryStructuredFields = wtMemoryInfo.some((col) => col["name"] === "structured_fields");
+            const hasMemoryLastHitAt = wtMemoryInfo.some((col) => col["name"] === "last_hit_at");
             const decConf = adapter.prepare(`SELECT m.id FROM decisions m INNER JOIN wt.decisions w ON m.id = w.id WHERE m.decision != w.decision OR m.choice != w.choice OR m.rationale != w.rationale OR ${hasMadeBy ? "m.made_by != w.made_by" : "'agent' != 'agent'"} OR m.superseded_by IS NOT w.superseded_by`).all();
             for (const row of decConf)
                 conflicts.push(`decision ${row["id"]}: modified in both`);
@@ -2831,12 +1571,17 @@ export function reconcileWorktreeDb(mainDbPath, worktreeDbPath) {
                  supporting_slices, validation, notes, full_content, superseded_by
           FROM wt.requirements
         `).run());
+                // V27: preserve content_hash. If the worktree predates V27 (no column),
+                // fall back to the main DB's existing hash so reconcile doesn't null
+                // out integrity fingerprints on artifacts that were unchanged in wt.
                 merged.artifacts = countChanges(adapter.prepare(`
           INSERT OR REPLACE INTO artifacts (
-            path, artifact_type, milestone_id, slice_id, task_id, full_content, imported_at
+            path, artifact_type, milestone_id, slice_id, task_id, full_content, imported_at, content_hash
           )
-          SELECT path, artifact_type, milestone_id, slice_id, task_id, full_content, imported_at
-          FROM wt.artifacts
+          SELECT w.path, w.artifact_type, w.milestone_id, w.slice_id, w.task_id, w.full_content, w.imported_at,
+                 ${hasArtifactContentHash ? "w.content_hash" : "m.content_hash"}
+          FROM wt.artifacts w
+          LEFT JOIN artifacts m ON m.path = w.path
         `).run());
                 // Merge milestones — worktree may have updated status/planning fields.
                 // Never downgrade status: complete > active > pre-planning (#4372).
@@ -2934,15 +1679,25 @@ export function reconcileWorktreeDb(mainDbPath, worktreeDbPath) {
           FROM wt.tasks w
           LEFT JOIN tasks m ON m.milestone_id = w.milestone_id AND m.slice_id = w.slice_id AND m.id = w.id
         `).run());
-                // Merge memories — keep worktree-learned insights
+                // Merge memories — keep worktree-learned insights.
+                // V18 (scope, tags), V21 (structured_fields), V28 (last_hit_at): for each
+                // column the wt may not yet have (older worktree DB), fall back to the
+                // main DB's existing value via LEFT JOIN so reconcile never silently
+                // resets these fields to defaults on rows that already had them.
                 merged.memories = countChanges(adapter.prepare(`
           INSERT OR REPLACE INTO memories (
             seq, id, category, content, confidence, source_unit_type, source_unit_id,
-            created_at, updated_at, superseded_by, hit_count
+            created_at, updated_at, superseded_by, hit_count,
+            scope, tags, structured_fields, last_hit_at
           )
-          SELECT seq, id, category, content, confidence, source_unit_type, source_unit_id,
-                 created_at, updated_at, superseded_by, hit_count
-          FROM wt.memories
+          SELECT w.seq, w.id, w.category, w.content, w.confidence, w.source_unit_type, w.source_unit_id,
+                 w.created_at, w.updated_at, w.superseded_by, w.hit_count,
+                 ${hasMemoryScope ? "w.scope" : "COALESCE(m.scope, 'project')"},
+                 ${hasMemoryTags ? "w.tags" : "COALESCE(m.tags, '[]')"},
+                 ${hasMemoryStructuredFields ? "w.structured_fields" : "m.structured_fields"},
+                 ${hasMemoryLastHitAt ? "w.last_hit_at" : "m.last_hit_at"}
+          FROM wt.memories w
+          LEFT JOIN memories m ON m.id = w.id
         `).run());
                 // Merge verification evidence — append-only, use INSERT OR IGNORE to avoid duplicates
                 merged.verification_evidence = countChanges(adapter.prepare(`
@@ -3058,6 +1813,7 @@ export function deleteMilestone(milestoneId) {
         currentDb.prepare(`DELETE FROM replan_history WHERE milestone_id = :mid`).run({ ":mid": milestoneId });
         currentDb.prepare(`DELETE FROM assessments WHERE milestone_id = :mid`).run({ ":mid": milestoneId });
         currentDb.prepare(`DELETE FROM artifacts WHERE milestone_id = :mid`).run({ ":mid": milestoneId });
+        currentDb.prepare(`DELETE FROM milestone_commit_attributions WHERE milestone_id = :mid`).run({ ":mid": milestoneId });
         currentDb.prepare(`DELETE FROM milestone_leases WHERE milestone_id = :mid`).run({ ":mid": milestoneId });
         currentDb.prepare(`DELETE FROM milestones WHERE id = :mid`).run({ ":mid": milestoneId });
     });
@@ -3103,20 +1859,6 @@ export function getLatestAssessmentByScope(milestoneId, scope) {
     return row ?? null;
 }
 // ─── Quality Gates ───────────────────────────────────────────────────────
-function rowToGate(row) {
-    return {
-        milestone_id: row["milestone_id"],
-        slice_id: row["slice_id"],
-        gate_id: row["gate_id"],
-        scope: row["scope"],
-        task_id: row["task_id"] ?? "",
-        status: row["status"],
-        verdict: row["status"] === "pending" ? null : row["verdict"],
-        rationale: row["rationale"] || "",
-        findings: row["findings"] || "",
-        evaluated_at: row["evaluated_at"] ?? null,
-    };
-}
 export function insertGateRow(g) {
     if (!currentDb)
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
@@ -3299,6 +2041,59 @@ export function upsertTurnGitTransaction(entry) {
         ":updated_at": entry.updatedAt,
     });
 }
+export function getMilestoneCommitAttributionShas(milestoneId) {
+    if (!currentDb)
+        return [];
+    const rows = currentDb.prepare(`SELECT commit_sha
+     FROM milestone_commit_attributions
+     WHERE milestone_id = :mid
+     ORDER BY created_at, commit_sha`).all({ ":mid": milestoneId });
+    return rows
+        .map((row) => typeof row["commit_sha"] === "string" ? row["commit_sha"] : "")
+        .filter(Boolean);
+}
+export function recordMilestoneCommitAttribution(entry) {
+    if (!currentDb)
+        return;
+    transaction(() => {
+        currentDb.prepare(`INSERT OR REPLACE INTO milestone_commit_attributions (
+        commit_sha, milestone_id, slice_id, task_id, source, confidence, files_json, created_at
+      ) VALUES (
+        :commit_sha, :milestone_id, :slice_id, :task_id, :source, :confidence, :files_json, :created_at
+      )`).run({
+            ":commit_sha": entry.commitSha,
+            ":milestone_id": entry.milestoneId,
+            ":slice_id": entry.sliceId ?? null,
+            ":task_id": entry.taskId ?? null,
+            ":source": entry.source,
+            ":confidence": entry.confidence,
+            ":files_json": JSON.stringify(entry.files),
+            ":created_at": entry.createdAt,
+        });
+        currentDb.prepare(`INSERT OR IGNORE INTO audit_events (
+        event_id, trace_id, turn_id, caused_by, category, type, ts, payload_json
+      ) VALUES (
+        :event_id, :trace_id, :turn_id, :caused_by, :category, :type, :ts, :payload_json
+      )`).run({
+            ":event_id": `milestone-commit-attribution:${entry.milestoneId}:${entry.commitSha}`,
+            ":trace_id": "milestone-commit-attribution",
+            ":turn_id": null,
+            ":caused_by": null,
+            ":category": "git",
+            ":type": "milestone-commit-attribution-recorded",
+            ":ts": entry.createdAt,
+            ":payload_json": JSON.stringify({
+                commitSha: entry.commitSha,
+                milestoneId: entry.milestoneId,
+                sliceId: entry.sliceId ?? null,
+                taskId: entry.taskId ?? null,
+                source: entry.source,
+                confidence: entry.confidence,
+                files: entry.files,
+            }),
+        });
+    });
+}
 export function insertAuditEvent(entry) {
     if (!currentDb)
         return;
@@ -3385,6 +2180,7 @@ export function clearEngineHierarchy() {
         currentDb.exec("DELETE FROM slice_dependencies");
         currentDb.exec("DELETE FROM assessments");
         currentDb.exec("DELETE FROM replan_history");
+        currentDb.exec("DELETE FROM milestone_commit_attributions");
         currentDb.exec("DELETE FROM tasks");
         currentDb.exec("DELETE FROM slices");
         currentDb.exec("DELETE FROM milestone_leases");
@@ -3660,7 +2456,7 @@ export function updateMemoryContentRow(id, content, confidence, updatedAt) {
 export function incrementMemoryHitCount(id, updatedAt) {
     if (!currentDb)
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
-    currentDb.prepare("UPDATE memories SET hit_count = hit_count + 1, updated_at = :updated_at WHERE id = :id").run({ ":updated_at": updatedAt, ":id": id });
+    currentDb.prepare("UPDATE memories SET hit_count = hit_count + 1, updated_at = :updated_at, last_hit_at = :last_hit_at WHERE id = :id").run({ ":updated_at": updatedAt, ":last_hit_at": updatedAt, ":id": id });
 }
 export function supersedeMemoryRow(oldId, newId, updatedAt) {
     if (!currentDb)