gsd-pi 2.79.0 → 2.80.0-dev.4ea7d80e7

package/src/resources/extensions/gsd/db-gate-rows.ts

@@ -0,0 +1,19 @@
+// Project/App: GSD-2
+// File Purpose: Quality gate row mapper for the GSD database facade.
+
+import type { GateId, GateRow, GateScope, GateStatus, GateVerdict } from "./types.js";
+
+export function rowToGate(row: Record<string, unknown>): GateRow {
+  return {
+    milestone_id: row["milestone_id"] as string,
+    slice_id: row["slice_id"] as string,
+    gate_id: row["gate_id"] as GateId,
+    scope: row["scope"] as GateScope,
+    task_id: (row["task_id"] as string) ?? "",
+    status: row["status"] as GateStatus,
+    verdict: row["status"] === "pending" ? null : (row["verdict"] as GateVerdict),
+    rationale: (row["rationale"] as string) || "",
+    findings: (row["findings"] as string) || "",
+    evaluated_at: (row["evaluated_at"] as string) ?? null,
+  };
+}

package/src/resources/extensions/gsd/db-lightweight-query-rows.ts

@@ -0,0 +1,50 @@
+// Project/App: GSD-2
+// File Purpose: Lightweight DB query row mappers for hot-path status reads.
+
+type DbRow = Record<string, unknown>;
+
+export interface IdStatusSummary {
+  id: string;
+  status: string;
+}
+
+export interface ActiveTaskSummary extends IdStatusSummary {
+  title: string;
+}
+
+export interface TaskStatusCounts {
+  total: number;
+  done: number;
+  pending: number;
+}
+
+export function rowToIdStatusSummary(row: DbRow): IdStatusSummary {
+  return {
+    id: row["id"] as string,
+    status: row["status"] as string,
+  };
+}
+
+export function rowToActiveTaskSummary(row: DbRow): ActiveTaskSummary {
+  return {
+    ...rowToIdStatusSummary(row),
+    title: row["title"] as string,
+  };
+}
+
+export function rowToTaskStatusCounts(row: DbRow | undefined): TaskStatusCounts {
+  if (!row) return emptyTaskStatusCounts();
+  return {
+    total: (row["total"] as number) ?? 0,
+    done: (row["done"] as number) ?? 0,
+    pending: (row["pending"] as number) ?? 0,
+  };
+}
+
+export function emptyTaskStatusCounts(): TaskStatusCounts {
+  return { total: 0, done: 0, pending: 0 };
+}
+
+export function rowsToStringColumn(rows: DbRow[], column: string): string[] {
+  return rows.map((row) => row[column] as string);
+}

package/src/resources/extensions/gsd/db-memory-fts-schema.ts

@@ -0,0 +1,66 @@
+// Project/App: GSD-2
+// File Purpose: Memory FTS5 SQLite schema helpers for the GSD database facade.
+
+import type { DbAdapter } from "./db-adapter.js";
+
+export interface MemoryFtsSchemaOptions {
+  onUnavailable?: (message: string) => void;
+}
+
+function formatFtsUnavailableError(err: unknown): string {
+  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
+ * SQLite builds — callers should treat failure as non-fatal and fall back
+ * to LIKE-based scans in `memory-store.queryMemoriesRanked`.
+ */
+export function tryCreateMemoriesFtsSchema(
+  db: DbAdapter,
+  options: MemoryFtsSchemaOptions = {},
+): boolean {
+  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) {
+    options.onUnavailable?.(`FTS5 unavailable — memory queries will use LIKE fallback: ${formatFtsUnavailableError(err)}`);
+    return false;
+  }
+}
+
+export function isMemoriesFtsAvailableSchema(db: DbAdapter): boolean {
+  try {
+    const row = db
+      .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='memories_fts'")
+      .get();
+    return !!row;
+  } catch {
+    return false;
+  }
+}

package/src/resources/extensions/gsd/db-migration-backup.ts

@@ -0,0 +1,34 @@
+// Project/App: GSD-2
+// File Purpose: Pre-migration backup helper for GSD database schema upgrades.
+
+import type { DbAdapter } from "./db-adapter.js";
+
+export interface MigrationBackupDeps {
+  existsSync(path: string): boolean;
+  copyFileSync(src: string, dest: string): void;
+  logWarning(scope: string, message: string): void;
+}
+
+export function backupDatabaseBeforeMigration(
+  db: DbAdapter,
+  dbPath: string | null,
+  currentVersion: number,
+  deps: MigrationBackupDeps,
+): void {
+  if (!dbPath || dbPath === ":memory:" || !deps.existsSync(dbPath)) return;
+
+  try {
+    const backupPath = `${dbPath}.backup-v${currentVersion}`;
+    if (deps.existsSync(backupPath)) return;
+
+    try {
+      db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+    } catch {
+      // Checkpoint is best effort; copying the base file is still better than no backup.
+    }
+    deps.copyFileSync(dbPath, backupPath);
+  } catch (backupErr) {
+    const message = backupErr instanceof Error ? backupErr.message : String(backupErr);
+    deps.logWarning("db", `Pre-migration backup failed: ${message}`);
+  }
+}

package/src/resources/extensions/gsd/db-migration-steps.ts

@@ -0,0 +1,451 @@
+// Project/App: GSD-2
+// File Purpose: Schema migration DDL steps for the GSD database facade.
+
+import type { DbAdapter } from "./db-adapter.js";
+import { ensureColumn } from "./db-schema-metadata.js";
+
+export function applyMigrationV2Artifacts(db: DbAdapter): void {
+  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 ''
+    )
+  `);
+}
+
+export function applyMigrationV3Memories(db: DbAdapter): void {
+  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");
+}
+
+export function applyMigrationV4DecisionMadeBy(db: DbAdapter): void {
+  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");
+}
+
+export function applyMigrationV5HierarchyTables(db: DbAdapter): void {
+  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)
+    )
+  `);
+}
+
+export function applyMigrationV6SliceSummaries(db: DbAdapter): void {
+  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 ''");
+}
+
+export function applyMigrationV7Dependencies(db: DbAdapter): void {
+  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 '[]'");
+}
+
+export function applyMigrationV8PlanningFields(db: DbAdapter): void {
+  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)");
+}
+
+export function applyMigrationV9Ordering(db: DbAdapter): void {
+  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");
+}
+
+export function applyMigrationV10ReplanTrigger(db: DbAdapter): void {
+  ensureColumn(db, "slices", "replan_triggered_at", "ALTER TABLE slices ADD COLUMN replan_triggered_at TEXT DEFAULT NULL");
+}
+
+export function applyMigrationV11TaskPlanning(db: DbAdapter): void {
+  ensureColumn(db, "tasks", "full_plan_md", "ALTER TABLE tasks ADD COLUMN full_plan_md TEXT NOT NULL DEFAULT ''");
+  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
+  `);
+}
+
+export function applyMigrationV12QualityGates(db: DbAdapter): void {
+  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)
+    )
+  `);
+}
+
+export function applyMigrationV13HotPathIndexes(
+  db: DbAdapter,
+  ensureVerificationEvidenceDedupIndex: (db: DbAdapter) => void,
+): void {
+  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);
+}
+
+export function applyMigrationV14SliceDependencies(db: DbAdapter): void {
+  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)");
+}
+
+export function applyMigrationV15AuditTables(db: DbAdapter): void {
+  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)");
+}
+
+export function applyMigrationV16EscalationSource(db: DbAdapter): void {
+  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 ''");
+  ensureColumn(db, "decisions", "source", "ALTER TABLE decisions ADD COLUMN source TEXT NOT NULL DEFAULT 'discussion'");
+}
+
+export function applyMigrationV17TaskEscalation(db: DbAdapter): void {
+  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)");
+}
+
+export function applyMigrationV18MemorySources(db: DbAdapter): void {
+  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 '[]'
+    )
+  `);
+  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)");
+}
+
+export interface MigrationV19Hooks {
+  tryCreateMemoriesFts(db: DbAdapter): boolean;
+  isMemoriesFtsAvailable(db: DbAdapter): boolean;
+  backfillMemoriesFts(db: DbAdapter): void;
+  logWarning(scope: string, message: string): void;
+}
+
+export function applyMigrationV19MemoryFts(db: DbAdapter, hooks: MigrationV19Hooks): void {
+  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
+    )
+  `);
+  hooks.tryCreateMemoriesFts(db);
+  if (hooks.isMemoriesFtsAvailable(db)) {
+    try {
+      hooks.backfillMemoriesFts(db);
+    } catch (err) {
+      hooks.logWarning("db", `FTS5 backfill failed: ${(err as Error).message}`);
+    }
+  }
+}
+
+export function applyMigrationV20MemoryRelations(db: DbAdapter): void {
+  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)");
+}
+
+export function applyMigrationV21StructuredMemories(db: DbAdapter): void {
+  ensureColumn(db, "memories", "structured_fields", "ALTER TABLE memories ADD COLUMN structured_fields TEXT DEFAULT NULL");
+}
+
+export function applyMigrationV23MilestoneQueue(db: DbAdapter): void {
+  ensureColumn(db, "milestones", "sequence", "ALTER TABLE milestones ADD COLUMN sequence INTEGER DEFAULT 0");
+}
+
+export function applyMigrationV26MilestoneCommitAttributions(db: DbAdapter): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS milestone_commit_attributions (
+      commit_sha TEXT NOT NULL,
+      milestone_id TEXT NOT NULL,
+      slice_id TEXT DEFAULT NULL,
+      task_id TEXT DEFAULT NULL,
+      source TEXT NOT NULL DEFAULT 'recorded',
+      confidence REAL NOT NULL DEFAULT 1.0,
+      files_json TEXT NOT NULL DEFAULT '[]',
+      created_at TEXT NOT NULL DEFAULT '',
+      PRIMARY KEY (commit_sha, milestone_id)
+    )
+  `);
+  db.exec("CREATE INDEX IF NOT EXISTS idx_milestone_commit_attr_milestone ON milestone_commit_attributions(milestone_id)");
+}
+
+export interface MigrationV22Hooks {
+  copyQualityGateRowsToRepairedTable(db: DbAdapter): void;
+}
+
+export function applyMigrationV22QualityGateRepair(db: DbAdapter, hooks: MigrationV22Hooks): void {
+  const qgInfo = db.prepare("PRAGMA table_info(quality_gates)").all() as Array<Record<string, unknown>>;
+  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)
+      )
+    `);
+    hooks.copyQualityGateRowsToRepairedTable(db);
+    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)");
+  }
+  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 ''");
+}