gsd-pi 2.78.0 → 2.78.1-dev.2d3fd6e71

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

@@ -25,6 +25,7 @@ import { existsSync, copyFileSync, mkdirSync, realpathSync } from "node:fs";
 import { dirname } from "node:path";
 import type { Decision, Requirement, GateRow, GateId, GateScope, GateStatus, GateVerdict } from "./types.js";
 import { GSDError, GSD_STALE_STATE } from "./errors.js";
+import type { GsdWorkspace, MilestoneScope } from "./workspace.js";
 import { getGateIdsForTurn, type OwnerTurn } from "./gate-registry.js";
 import { logError, logWarning } from "./workflow-logger.js";
 // Type-only import to avoid a circular runtime dep. The runtime side of
@@ -33,6 +34,7 @@ import { logError, logWarning } from "./workflow-logger.js";
 import type { StateManifest } from "./workflow-manifest.js";
 
 const _require = createRequire(import.meta.url);
+const BETTER_SQLITE3_PACKAGE = ["better", "sqlite3"].join("-");
 
 interface DbStatement {
   run(...params: unknown[]): unknown;
@@ -89,7 +91,7 @@ function loadProvider(): void {
   }
 
   try {
-    const mod = _require("better-sqlite3");
+    const mod = _require(BETTER_SQLITE3_PACKAGE);
     if (typeof mod === "function" || (mod && mod.default)) {
       providerModule = mod.default || mod;
       providerName = "better-sqlite3";
@@ -180,7 +182,7 @@ function openRawDb(path: string): unknown {
   return new Database(path);
 }
 
-export const SCHEMA_VERSION = 22;
+export const SCHEMA_VERSION = 23;
 
 function indexExists(db: DbAdapter, name: string): boolean {
   return !!db.prepare(
@@ -353,7 +355,8 @@ function initSchema(db: DbAdapter, fileBacked: boolean): void {
         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 ''
+        boundary_map_markdown TEXT NOT NULL DEFAULT '',
+        sequence INTEGER DEFAULT 0
       )
     `);
 
@@ -1232,6 +1235,17 @@ function migrateSchema(db: DbAdapter): void {
       });
     }
 
+    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(),
+      });
+    }
+
     db.exec("COMMIT");
   } catch (err) {
     db.exec("ROLLBACK");
@@ -1246,6 +1260,182 @@ let _exitHandlerRegistered = false;
 let _dbOpenAttempted = false;
 let _lastDbError: Error | null = null;
 let _lastDbPhase: "open" | "initSchema" | "vacuum-recovery" | null = null;
+/**
+ * Identity key of the workspace whose connection is currently active
+ * (currentDb). Set by openDatabaseByWorkspace(); null when the active
+ * connection was opened via the legacy openDatabase(path) path.
+ */
+let _currentIdentityKey: string | null = null;
+
+/**
+ * Workspace-scoped connection cache.
+ * Key: GsdWorkspace.identityKey (realpath-normalized project root).
+ * Value: the DB path and open adapter for that workspace.
+ *
+ * Sibling worktrees of the same project share the same identityKey (set by
+ * createWorkspace) and therefore reuse the same cached connection, preserving
+ * shared-WAL semantics. Different projects get distinct cache entries.
+ *
+ * NOTE: Only one connection is "active" at a time (currentDb/currentPath).
+ * The cache allows fast re-activation of a previously opened connection when
+ * callers switch between known workspaces via openDatabaseByWorkspace().
+ */
+const _dbCache = new Map<string, { dbPath: string; db: DbAdapter }>();
+
+/** Test helper: expose the internal cache for inspection. Not for production use. */
+export function _getDbCache(): ReadonlyMap<string, { dbPath: string; db: DbAdapter }> {
+  return _dbCache;
+}
+
+/**
+ * Close and evict every entry in the workspace connection cache, then call
+ * closeDatabase() to close the active connection.
+ *
+ * Use this for test teardown or process-shutdown paths where every open
+ * connection must be flushed. Normal callers should use closeDatabase() or
+ * closeDatabaseByWorkspace() instead.
+ */
+export function closeAllDatabases(): void {
+  // 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 */ }
+  }
+  closeDatabase();
+}
+
+/**
+ * Open (or reuse) the database connection scoped to the given workspace.
+ *
+ * Uses workspace.identityKey as the cache key, so sibling worktrees of the
+ * same project resolve to the same connection. On a cache hit the existing
+ * adapter is reactivated as the current connection without re-opening the
+ * file. On a cache miss, delegates to openDatabase() for the full
+ * open + schema-init + migration flow, then caches the result.
+ *
+ * When switching to a different workspace, the previously active connection
+ * is preserved in the cache (not closed), so callers can switch back to it
+ * cheaply via a subsequent openDatabaseByWorkspace() call.
+ *
+ * @param workspace A GsdWorkspace created by createWorkspace().
+ * @returns true if the connection is open and ready, false otherwise.
+ */
+export function openDatabaseByWorkspace(workspace: GsdWorkspace): boolean {
+  const key = workspace.identityKey;
+  const dbPath = workspace.contract.projectDb;
+
+  const cached = _dbCache.get(key);
+  if (cached) {
+    // Reactivate the cached connection as the current singleton.
+    currentDb = cached.db;
+    currentPath = cached.dbPath;
+    currentPid = process.pid;
+    _dbOpenAttempted = true;
+    _currentIdentityKey = key;
+    return true;
+  }
+
+  // Cache miss — need to open a new connection.
+  //
+  // If there is a currently active workspace connection, stash it in the
+  // cache under its identity key before calling openDatabase(), because
+  // openDatabase() will call closeDatabase() when the path changes (which
+  // would destroy the existing adapter). By nulling out currentDb first,
+  // we prevent openDatabase() from closing the live adapter.
+  let oldDb: typeof currentDb = null;
+  let oldPath: typeof currentPath = null;
+  let oldPid: typeof currentPid = 0;
+  let oldKey: typeof _currentIdentityKey = null;
+
+  if (currentDb !== null && _currentIdentityKey !== null) {
+    // Snapshot the old globals so we can restore them on failure.
+    oldDb = currentDb;
+    oldPath = currentPath;
+    oldPid = currentPid;
+    oldKey = _currentIdentityKey;
+    // Save the current connection so it stays alive in the cache.
+    _dbCache.set(_currentIdentityKey, {
+      dbPath: currentPath!,
+      db: currentDb,
+    });
+    // Detach from globals so openDatabase() opens fresh without closing it.
+    currentDb = null;
+    currentPath = null;
+    currentPid = 0;
+    _currentIdentityKey = null;
+  }
+
+  // Run the full open/schema/migration flow for the new workspace.
+  // openDatabase() can throw on corrupt DB or permission error — catch so we
+  // can restore the previous connection rather than leaving globals null.
+  let opened: boolean;
+  try {
+    opened = openDatabase(dbPath);
+  } catch (err) {
+    // Failed to open the new DB. Restore the previous workspace connection so
+    // the caller's workspace remains active (it is still safe in _dbCache).
+    if (oldDb !== null) {
+      currentDb = oldDb;
+      currentPath = oldPath;
+      currentPid = oldPid;
+      _currentIdentityKey = oldKey;
+    }
+    throw err;
+  }
+  if (opened && currentDb) {
+    _dbCache.set(key, { dbPath, db: currentDb });
+    _currentIdentityKey = key;
+  } else if (!opened && oldDb !== null) {
+    // Restore the previous connection so the caller's workspace remains active.
+    // The failed attempt left no live adapter, so the globals stayed null.
+    currentDb = oldDb;
+    currentPath = oldPath;
+    currentPid = oldPid;
+    _currentIdentityKey = oldKey;
+  }
+  return opened;
+}
+
+/**
+ * Open (or reuse) the database connection scoped to the workspace in a
+ * MilestoneScope. Thin delegation to openDatabaseByWorkspace().
+ */
+export function openDatabaseByScope(scope: MilestoneScope): boolean {
+  return openDatabaseByWorkspace(scope.workspace);
+}
+
+/**
+ * Close the database connection for the given workspace and remove it from
+ * the cache. If the workspace's connection is currently active (currentDb),
+ * performs a full closeDatabase() including WAL checkpoint. Otherwise only
+ * removes the cache entry (the adapter was already replaced by a later open).
+ */
+export function closeDatabaseByWorkspace(workspace: GsdWorkspace): void {
+  const key = workspace.identityKey;
+  const cached = _dbCache.get(key);
+  if (!cached) return;
+
+  _dbCache.delete(key);
+
+  if (currentDb === cached.db) {
+    // This workspace's connection is the active one — full close.
+    closeDatabase();
+  } 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 as Error).message}`); }
+    try {
+      cached.db.exec("PRAGMA incremental_vacuum(64)");
+    } catch (e) { logWarning("db", `incremental vacuum (byWorkspace) failed: ${(e as Error).message}`); }
+    try {
+      cached.db.close();
+    } catch (e) { logWarning("db", `database close (byWorkspace) failed: ${(e as Error).message}`); }
+  }
+}
 
 export function getDbProvider(): ProviderName | null {
   loadProvider();
@@ -1303,7 +1493,7 @@ export function openDatabase(path: string): boolean {
     // node:sqlite loaded but failed to open this file — try better-sqlite3 as fallback.
     if (providerName === "node:sqlite") {
       try {
-        const mod = _require("better-sqlite3");
+        const mod = _require(BETTER_SQLITE3_PACKAGE);
         const Db = (mod && mod.default) ? mod.default : mod;
         if (typeof Db === "function") {
           rawDb = new Db(path);
@@ -1376,6 +1566,13 @@ export function closeDatabase(): void {
     try {
       currentDb.close();
     } catch (e) { logWarning("db", `database close failed: ${(e as Error).message}`); }
+    // If this connection was workspace-tracked, evict it from the cache so
+    // subsequent openDatabaseByWorkspace() calls re-open rather than reactivate
+    // a closed adapter.
+    if (_currentIdentityKey !== null) {
+      _dbCache.delete(_currentIdentityKey);
+      _currentIdentityKey = null;
+    }
     currentDb = null;
     currentPath = null;
     currentPid = 0;
@@ -1405,6 +1602,16 @@ export function checkpointDatabase(): void {
 
 let _txDepth = 0;
 
+/**
+ * Whether the current call is running inside an active SQLite transaction.
+ * Statement-time recovery paths (e.g. VACUUM retry on a malformed memory
+ * store) MUST gate on this — SQLite refuses VACUUM inside a transaction
+ * and would mask the original error with a secondary "cannot VACUUM" throw.
+ */
+export function isInTransaction(): boolean {
+  return _txDepth > 0;
+}
+
 export function transaction<T>(fn: () => T): T {
   if (!currentDb) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
 
@@ -1419,8 +1626,8 @@ export function transaction<T>(fn: () => T): T {
     }
   }
 
-  _txDepth++;
   currentDb.exec("BEGIN");
+  _txDepth++;
   try {
     const result = fn();
     currentDb.exec("COMMIT");
@@ -1452,8 +1659,8 @@ export function readTransaction<T>(fn: () => T): T {
     }
   }
 
-  _txDepth++;
   currentDb.exec("BEGIN DEFERRED");
+  _txDepth++;
   try {
     const result = fn();
     currentDb.exec("COMMIT");
@@ -1591,6 +1798,34 @@ export function getActiveRequirements(): Requirement[] {
   }));
 }
 
+export function getRequirementCounts(): {
+  active: number;
+  validated: number;
+  deferred: number;
+  outOfScope: number;
+  blocked: number;
+  total: number;
+} {
+  if (!currentDb) {
+    return { active: 0, validated: 0, deferred: 0, outOfScope: 0, blocked: 0, total: 0 };
+  }
+  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;
+}
+
 export function getDbOwnerPid(): number {
   return currentPid;
 }
@@ -2458,6 +2693,7 @@ export interface MilestoneRow {
   definition_of_done: string[];
   requirement_coverage: string;
   boundary_map_markdown: string;
+  sequence: number;
 }
 
 function rowToMilestone(row: Record<string, unknown>): MilestoneRow {
@@ -2479,6 +2715,7 @@ function rowToMilestone(row: Record<string, unknown>): MilestoneRow {
     definition_of_done: JSON.parse((row["definition_of_done"] as string) || "[]"),
     requirement_coverage: (row["requirement_coverage"] as string) ?? "",
     boundary_map_markdown: (row["boundary_map_markdown"] as string) ?? "",
+    sequence: Number(row["sequence"] ?? 0),
   };
 }
 
@@ -2506,7 +2743,9 @@ function rowToArtifact(row: Record<string, unknown>): ArtifactRow {
 
 export function getAllMilestones(): MilestoneRow[] {
   if (!currentDb) return [];
-  const rows = currentDb.prepare("SELECT * FROM milestones ORDER BY id").all();
+  const rows = currentDb.prepare(
+    "SELECT * FROM milestones ORDER BY CASE WHEN sequence > 0 THEN 0 ELSE 1 END, sequence, id",
+  ).all();
   return rows.map(rowToMilestone);
 }
 
@@ -2517,6 +2756,22 @@ export function getMilestone(id: string): MilestoneRow | null {
   return rowToMilestone(row);
 }
 
+export function setMilestoneQueueOrder(order: string[]): void {
+  if (!currentDb) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+  currentDb.exec("BEGIN IMMEDIATE");
+  try {
+    currentDb.prepare("UPDATE milestones SET sequence = 0").run();
+    const stmt = currentDb.prepare("UPDATE milestones SET sequence = :sequence WHERE id = :id");
+    order.forEach((id, index) => {
+      stmt.run({ ":id": id, ":sequence": index + 1 });
+    });
+    currentDb.exec("COMMIT");
+  } catch (err) {
+    currentDb.exec("ROLLBACK");
+    throw err;
+  }
+}
+
 /**
  * Update a milestone's status in the database.
  * Used by park/unpark to keep the DB in sync with the filesystem marker.
@@ -2712,6 +2967,8 @@ export function reconcileWorktreeDb(
       // fall through to the main DB's existing value (not a literal default)
       // so reconcile never silently clears state the main tree has recorded.
       const hasDecisionSource = wtInfo.some((col) => col["name"] === "source");
+      const wtMilestoneInfo = adapter.prepare("PRAGMA wt.table_info('milestones')").all();
+      const hasMilestoneSequence = wtMilestoneInfo.some((col) => col["name"] === "sequence");
       const wtSliceInfo = adapter.prepare("PRAGMA wt.table_info('slices')").all();
       const hasIsSketch = wtSliceInfo.some((col) => col["name"] === "is_sketch");
       const hasSketchScope = wtSliceInfo.some((col) => col["name"] === "sketch_scope");
@@ -2785,7 +3042,7 @@ export function reconcileWorktreeDb(
             id, title, status, depends_on, created_at, completed_at,
             vision, success_criteria, key_risks, proof_strategy,
             verification_contract, verification_integration, verification_operational, verification_uat,
-            definition_of_done, requirement_coverage, boundary_map_markdown
+            definition_of_done, requirement_coverage, boundary_map_markdown, sequence
           )
           SELECT w.id, w.title,
                  CASE
@@ -2803,7 +3060,8 @@ export function reconcileWorktreeDb(
                  END,
                  w.vision, w.success_criteria, w.key_risks, w.proof_strategy,
                  w.verification_contract, w.verification_integration, w.verification_operational, w.verification_uat,
-                 w.definition_of_done, w.requirement_coverage, w.boundary_map_markdown
+                 w.definition_of_done, w.requirement_coverage, w.boundary_map_markdown,
+                 ${hasMilestoneSequence ? "COALESCE(w.sequence, 0)" : "COALESCE(m.sequence, 0)"}
           FROM wt.milestones w
           LEFT JOIN milestones m ON m.id = w.id
         `).run());
@@ -3093,6 +3351,20 @@ export function getAssessment(path: string): Record<string, unknown> | null {
   return row ?? null;
 }
 
+export function getLatestAssessmentByScope(
+  milestoneId: string,
+  scope: string,
+): Record<string, unknown> | null {
+  if (!currentDb) return null;
+  const row = currentDb.prepare(
+    `SELECT * FROM assessments
+      WHERE milestone_id = :mid AND scope = :scope
+      ORDER BY created_at DESC
+      LIMIT 1`,
+  ).get({ ":mid": milestoneId, ":scope": scope });
+  return row ?? null;
+}
+
 // ─── Quality Gates ───────────────────────────────────────────────────────
 
 function rowToGate(row: Record<string, unknown>): GateRow {
@@ -3580,8 +3852,8 @@ export function restoreManifest(manifest: StateManifest): void {
       `INSERT INTO milestones (id, title, status, depends_on, created_at, completed_at,
         vision, success_criteria, key_risks, proof_strategy,
         verification_contract, verification_integration, verification_operational, verification_uat,
-        definition_of_done, requirement_coverage, boundary_map_markdown)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        definition_of_done, requirement_coverage, boundary_map_markdown, sequence)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
     );
     for (const m of manifest.milestones) {
       msStmt.run(
@@ -3590,7 +3862,7 @@ export function restoreManifest(manifest: StateManifest): void {
         m.vision, JSON.stringify(m.success_criteria), JSON.stringify(m.key_risks),
         JSON.stringify(m.proof_strategy),
         m.verification_contract, m.verification_integration, m.verification_operational, m.verification_uat,
-        JSON.stringify(m.definition_of_done), m.requirement_coverage, m.boundary_map_markdown,
+        JSON.stringify(m.definition_of_done), m.requirement_coverage, m.boundary_map_markdown, m.sequence ?? 0,
       );
     }
 

package/src/resources/extensions/gsd/gsd-home.ts

@@ -0,0 +1,30 @@
+/**
+ * GSD home directory resolution.
+ *
+ * Exports gsdHome() which returns the GSD configuration directory,
+ * defaulting to ~/.gsd with a GSD_HOME env var override.
+ *
+ * For the user's home directory, use os.homedir() directly — it handles
+ * platform-specific env lookup (USERPROFILE on Windows, HOME on POSIX)
+ * with appropriate fallbacks.
+ *
+ * @see https://github.com/gsd-build/gsd-2/issues/5015
+ */
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+/**
+ * Resolve the GSD home directory (typically ~/.gsd).
+ *
+ * `GSD_HOME` env var overrides the default location.
+ * Falls back to `homedir()/.gsd`.
+ *
+ * Always returns an absolute, normalized path — `resolve()` canonicalizes
+ * any relative or non-canonical `GSD_HOME` value so downstream comparison
+ * and redaction sites don't have to.
+ */
+export function gsdHome(): string {
+  return process.env.GSD_HOME
+    ? resolve(process.env.GSD_HOME)
+    : join(homedir(), ".gsd");
+}

package/src/resources/extensions/gsd/guided-flow-queue.ts

@@ -194,7 +194,7 @@ export async function showQueueAdd(
 
   // ── Dispatch the queue prompt ───────────────────────────────────────
   // Activate the queue phase so the write-gate applies to CONTEXT.md writes
-  setQueuePhaseActive(true);
+  setQueuePhaseActive(true, basePath);
 
   const queueInlinedTemplates = inlineTemplate("context", "Context");
   const prompt = loadPrompt("queue", {