@opengsd/gsd-pi 1.3.0 → 1.4.0

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

@@ -28,6 +28,7 @@ import {
 import { rowToGate } from "../db-gate-rows.js";
 import { rowToArtifact, rowToMilestone, type ArtifactRow, type MilestoneRow } from "../db-milestone-artifact-rows.js";
 import { rowToSlice, rowToTask, type SliceRow, type TaskRow } from "../db-task-slice-rows.js";
+import { TERMINAL_STATUS_SQL } from "./sql-constants.js";
 
 
 function parseStringArrayColumn(raw: unknown): string[] {
@@ -49,6 +50,59 @@ function normalizeRepoPath(file: string): string {
   return file.trim().replace(/\\/g, "/").replace(/^\.\/+/, "");
 }
 
+export interface HierarchyCompletionCounts {
+  milestones: number;
+  milestonesTotal: number;
+  slices: number;
+  slicesTotal: number;
+  tasks: number;
+  tasksTotal: number;
+}
+
+function numberColumn(row: Record<string, unknown> | undefined, column: string): number {
+  const value = row?.[column];
+  if (typeof value === "number") return value;
+  if (typeof value === "bigint") return Number(value);
+  if (typeof value === "string") {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+  }
+  return 0;
+}
+
+function getCompletionCount(table: "milestones" | "slices" | "tasks"): { completed: number; total: number } {
+  const row = getDbOrNull()!.prepare(
+    `SELECT
+       COUNT(*) AS total,
+       COALESCE(SUM(CASE WHEN status IN (${TERMINAL_STATUS_SQL}) THEN 1 ELSE 0 END), 0) AS completed
+     FROM ${table}`,
+  ).get();
+
+  return {
+    completed: numberColumn(row, "completed"),
+    total: numberColumn(row, "total"),
+  };
+}
+
+export function getHierarchyCompletionCounts(): HierarchyCompletionCounts {
+  if (!getDbOrNull()!) {
+    return { milestones: 0, milestonesTotal: 0, slices: 0, slicesTotal: 0, tasks: 0, tasksTotal: 0 };
+  }
+
+  const milestones = getCompletionCount("milestones");
+  const slices = getCompletionCount("slices");
+  const tasks = getCompletionCount("tasks");
+
+  return {
+    milestones: milestones.completed,
+    milestonesTotal: milestones.total,
+    slices: slices.completed,
+    slicesTotal: slices.total,
+    tasks: tasks.completed,
+    tasksTotal: tasks.total,
+  };
+}
+
 export function getDecisionById(id: string): Decision | null {
   if (!getDbOrNull()!) return null;
   const row = getDbOrNull()!.prepare("SELECT * FROM decisions WHERE id = ?").get(id);
@@ -270,6 +324,66 @@ export function getMilestoneSlices(milestoneId: string): SliceRow[] {
   return rows.map(rowToSlice);
 }
 
+export interface ParallelMonitorSliceProgress {
+  id: string;
+  status: string;
+  total: number;
+  done: number;
+}
+
+export function getParallelMonitorSliceProgress(milestoneId: string): ParallelMonitorSliceProgress[] {
+  const db = getDbOrNull();
+  if (!db) return [];
+  const rows = db.prepare(
+    `SELECT
+       s.id AS id,
+       s.status AS status,
+       COUNT(t.id) AS total,
+       COALESCE(SUM(CASE WHEN t.status='complete' THEN 1 ELSE 0 END), 0) AS done
+     FROM slices s
+     LEFT JOIN tasks t ON s.milestone_id=t.milestone_id AND s.id=t.slice_id
+     WHERE s.milestone_id=:mid
+     GROUP BY s.id
+     ORDER BY s.id`,
+  ).all({ ":mid": milestoneId });
+  return rows.map((row) => ({
+    id: String(row["id"] ?? ""),
+    status: String(row["status"] ?? ""),
+    total: Number(row["total"] ?? 0),
+    done: Number(row["done"] ?? 0),
+  }));
+}
+
+export interface ParallelMonitorCompletion {
+  taskId: string;
+  sliceId: string;
+  oneLiner: string;
+}
+
+export function getParallelMonitorRecentCompletions(
+  milestoneId: string,
+  limit: number = 5,
+): ParallelMonitorCompletion[] {
+  const db = getDbOrNull();
+  if (!db) return [];
+  const numericLimit = Number.isFinite(limit) ? Math.floor(limit) : 5;
+  const safeLimit = Math.max(1, Math.min(50, numericLimit));
+  const rows = db.prepare(
+    `SELECT id, slice_id, one_liner
+     FROM tasks
+     WHERE milestone_id=:mid
+       AND status='complete'
+       AND completed_at IS NOT NULL
+     ORDER BY completed_at DESC
+     LIMIT ${safeLimit}`,
+  ).all({ ":mid": milestoneId });
+  return rows.map((row) => ({
+    taskId: String(row["id"] ?? ""),
+    sliceId: String(row["slice_id"] ?? ""),
+    oneLiner: String(row["one_liner"] ?? ""),
+  }));
+}
+
 /**
  * Load slices for many milestones in a single query. Returns a Map keyed by
  * milestone_id, preserving `ORDER BY sequence, id` within each bucket.
@@ -342,6 +456,24 @@ export function getArtifact(path: string): ArtifactRow | null {
   return rowToArtifact(row);
 }
 
+/** Milestone-level artifacts (CONTEXT, RESEARCH, VALIDATION, etc.) from the artifacts table. */
+export function getMilestoneScopedArtifacts(milestoneId: string): ArtifactRow[] {
+  if (!getDbOrNull()!) return [];
+  const rows = getDbOrNull()!.prepare(
+    "SELECT * FROM artifacts WHERE milestone_id = :mid AND slice_id IS NULL AND task_id IS NULL ORDER BY path",
+  ).all({ ":mid": milestoneId });
+  return rows.map(rowToArtifact);
+}
+
+/** Slice-level artifacts (CONTEXT, RESEARCH, CONTINUE, etc.) from the artifacts table. */
+export function getSliceScopedArtifacts(milestoneId: string, sliceId: string): ArtifactRow[] {
+  if (!getDbOrNull()!) return [];
+  const rows = getDbOrNull()!.prepare(
+    "SELECT * FROM artifacts WHERE milestone_id = :mid AND slice_id = :sid AND task_id IS NULL ORDER BY path",
+  ).all({ ":mid": milestoneId, ":sid": sliceId });
+  return rows.map(rowToArtifact);
+}
+
 /** Fast milestone status check — avoids deserializing JSON planning fields. */
 export function getActiveMilestoneIdFromDb(): IdStatusSummary | null {
   if (!getDbOrNull()!) return null;
@@ -412,6 +544,31 @@ export function getAssessment(path: string): Record<string, unknown> | null {
   return row ?? null;
 }
 
+/**
+ * Look up a slice's `run-uat` assessment by (milestoneId, sliceId) identity,
+ * independent of the artifact `path`. Used as a DB fallback by the UAT
+ * closeout gate when a path migration orphans the ASSESSMENT markdown from its
+ * canonical expected path (ADR-017: DB-authoritative UAT sign-off).
+ *
+ * `status` holds the normalized verdict (`pass`/`fail`/…) written by
+ * `executeUatResultSave`; `fullContent` carries the ASSESSMENT body so callers
+ * can derive `uatType` without re-reading a file that may not exist.
+ */
+export function getSliceRunUatAssessment(
+  milestoneId: string,
+  sliceId: string,
+): { status: string; fullContent: string } | null {
+  if (!getDbOrNull()!) return null;
+  const row = getDbOrNull()!.prepare(
+    `SELECT status, full_content AS fullContent FROM assessments
+      WHERE milestone_id = :mid AND slice_id = :sid AND scope = 'run-uat'
+      ORDER BY created_at DESC, ROWID DESC
+      LIMIT 1`,
+  ).get({ ":mid": milestoneId, ":sid": sliceId });
+  if (!row) return null;
+  return { status: String(row["status"] ?? ""), fullContent: String(row["fullContent"] ?? "") };
+}
+
 export function getLatestAssessmentByScope(
   milestoneId: string,
   scope: string,

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

@@ -520,9 +520,33 @@ export function getRecentUnitKeysForWorker(
 export function getRecentUnitKeysForProjectRoot(
   projectRootRealpath: string,
   limit = 20,
+  traceId?: string,
 ): Array<{ key: string }> {
   if (!isDbAvailable()) return [];
   const db = _getAdapter()!;
+  // When a trace_id is provided, scope the window to the current session so
+  // stale finalize-retry entries from PREVIOUS sessions don't fire detectStuck
+  // Rule 1 on the first iteration of a new session — killing auto-mode before
+  // any new dispatch runs. Without this, a project that had two consecutive
+  // finalize-retry failures in a prior session is permanently stuck: every
+  // fresh session loads those stale errors and immediately declares stuck.
+  if (traceId) {
+    const rows = db.prepare(
+      `SELECT ud.unit_type, ud.unit_id
+       FROM unit_dispatches ud
+       INNER JOIN workers w ON w.worker_id = ud.worker_id
+       WHERE w.project_root_realpath = :project_root_realpath
+         AND w.status != 'crashed'
+         AND ud.trace_id = :trace_id
+       ORDER BY ud.started_at DESC, ud.id DESC
+       LIMIT :limit`,
+    ).all({
+      ":project_root_realpath": projectRootRealpath,
+      ":trace_id": traceId,
+      ":limit": limit,
+    }) as Array<{ unit_type: string; unit_id: string }>;
+    return rows.reverse().map((r) => ({ key: `${r.unit_type}/${r.unit_id}` }));
+  }
   const rows = db.prepare(
     `SELECT ud.unit_type, ud.unit_id
      FROM unit_dispatches ud

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

@@ -2,11 +2,18 @@
 // File Purpose: Memory FTS5 SQLite schema helpers for the GSD database facade.
 
 import type { DbAdapter } from "./db-adapter.js";
+import { createRuntimeKvTableV25 } from "./db-runtime-kv-schema.js";
+
+export const MEMORIES_FTS_REBUILT_KEY = "memories_fts_rebuilt_at";
 
 export interface MemoryFtsSchemaOptions {
   onUnavailable?: (message: string) => void;
 }
 
+export interface MemoryFtsRebuildOptions {
+  onRebuildFailed?: (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: ");
@@ -64,3 +71,41 @@ export function isMemoriesFtsAvailableSchema(db: DbAdapter): boolean {
     return false;
   }
 }
+
+export function rebuildMemoriesFtsSchemaOnce(
+  db: DbAdapter,
+  options: MemoryFtsRebuildOptions = {},
+): void {
+  if (!isMemoriesFtsAvailableSchema(db)) return;
+
+  createRuntimeKvTableV25(db);
+  const marker = db.prepare(
+    "SELECT 1 as present FROM runtime_kv WHERE scope = 'global' AND scope_id = '' AND key = :key",
+  ).get({ ":key": MEMORIES_FTS_REBUILT_KEY });
+  if (marker) return;
+
+  const now = new Date().toISOString();
+  try {
+    db.exec("BEGIN");
+    db.exec("INSERT INTO memories_fts(memories_fts) VALUES('rebuild')");
+    db.prepare(
+      `INSERT INTO runtime_kv (scope, scope_id, key, value_json, updated_at)
+       VALUES ('global', '', :key, :value_json, :updated_at)
+       ON CONFLICT (scope, scope_id, key) DO UPDATE SET
+         value_json = excluded.value_json,
+         updated_at = excluded.updated_at`,
+    ).run({
+      ":key": MEMORIES_FTS_REBUILT_KEY,
+      ":value_json": JSON.stringify(now),
+      ":updated_at": now,
+    });
+    db.exec("COMMIT");
+  } catch (err) {
+    try {
+      db.exec("ROLLBACK");
+    } catch {
+      // Best effort: leave startup alive and retry the rebuild on next open.
+    }
+    options.onRebuildFailed?.(`FTS5 rebuild failed: ${(err as Error).message}`);
+  }
+}

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

@@ -2,9 +2,10 @@
 // File Purpose: Workspace-facing Interface for opening and maintaining the workflow database.
 
 import { existsSync } from "node:fs";
-import { dirname } from "node:path";
+import { dirname, join } from "node:path";
 
 import type { GsdWorkspace, MilestoneScope } from "./workspace.js";
+import type { DbAdapter } from "./db-adapter.js";
 import {
   backupDatabaseSnapshot,
   checkpointDatabase,
@@ -18,12 +19,13 @@ import {
   openDatabase,
   openDatabaseByScope,
   openDatabaseByWorkspace,
+  openIsolatedDatabase,
   refreshOpenDatabaseFromDisk,
   vacuumDatabase,
   wasDbOpenAttempted,
 } from "./gsd-db.js";
-import { resolveGsdPathContract } from "./paths.js";
-import { setLogBasePath } from "./workflow-logger.js";
+import { resolveGsdPathContract, gsdRoot } from "./paths.js";
+import { logWarning, setLogBasePath } from "./workflow-logger.js";
 
 export interface WorkflowDatabaseLocation {
   projectRoot: string;
@@ -54,6 +56,20 @@ export type WorkflowDatabaseOpenResult =
 export type WorkflowDatabaseStatus = ReturnType<typeof getDbStatus>;
 export type WorkflowDatabaseProvider = ReturnType<typeof getDbProvider>;
 
+/**
+ * Global SQLite handle invariants:
+ *
+ * - `openWorkflowDatabase` / `openDatabase` switch the process-global handle consumed by
+ *   deriveState, dispatch, reconciliation repairs, and domain writers. Only one active
+ *   project database should own the global handle at a time.
+ * - `openWorkflowDatabaseIsolated` opens a caller-owned connection that does not clobber
+ *   the global handle. Use for read-only observers (parallel monitor) and other background
+ *   probes that must not disturb the active workflow session.
+ * - Reconciliation repairs that write markdown/DB state must use `ensureWorkflowDbForBase`
+ *   so repairs target the correct project; those paths intentionally re-open the global handle.
+ * - Pair ad-hoc project switches with `closeWorkflowDatabase()` or restore via
+ *   `ensureWorkflowDbForBase(..., { refresh: true })` before returning to derive/dispatch.
+ */
 export function resolveWorkflowDatabaseLocation(basePath: string): WorkflowDatabaseLocation {
   const contract = resolveGsdPathContract(basePath);
   return {
@@ -113,6 +129,19 @@ export function openWorkflowDatabasePath(path: string): boolean {
   return openDatabase(path);
 }
 
+/**
+ * Open an isolated database connection for read-only observation without
+ * displacing the active workflow session's global DB handle. The caller is
+ * responsible for calling `adapter.close()` when done.
+ *
+ * Use this for background observers (e.g. the parallel monitor overlay) that
+ * need to query a database on a 5s tick without interfering with the primary
+ * connection. Returns null if the connection cannot be opened.
+ */
+export function openWorkflowDatabaseIsolated(path: string): DbAdapter | null {
+  return openIsolatedDatabase(path);
+}
+
 export function openWorkflowDatabaseByWorkspace(workspace: GsdWorkspace): boolean {
   return openDatabaseByWorkspace(workspace);
 }
@@ -157,6 +186,50 @@ export function refreshWorkflowDatabaseFromDisk(): boolean {
   return refreshOpenDatabaseFromDisk();
 }
 
+export function expectedWorkflowDbPathForBase(basePath: string): string {
+  return join(gsdRoot(basePath), "gsd.db");
+}
+
+export interface EnsureWorkflowDbOptions {
+  /** When true, refresh from disk before reopening if already open on the correct path. */
+  refresh?: boolean;
+}
+
+export function ensureWorkflowDbAtPath(dbPath: string | null): boolean {
+  if (!dbPath || dbPath === ":memory:") return isDbAvailable();
+  if (isDbAvailable() && getWorkflowDatabasePath() === dbPath) return true;
+  if (!existsSync(dbPath)) return false;
+  try {
+    return openWorkflowDatabasePath(dbPath);
+  } catch (err) {
+    logWarning("reconcile", `ensureWorkflowDbAtPath could not reopen DB: ${(err as Error).message}`);
+    return false;
+  }
+}
+
+export function ensureWorkflowDbForBase(
+  basePath: string,
+  options: EnsureWorkflowDbOptions = {},
+): boolean {
+  const dbPath = expectedWorkflowDbPathForBase(basePath);
+  if (!existsSync(dbPath)) return false;
+
+  try {
+    if (options.refresh) {
+      if (isDbAvailable() && getWorkflowDatabasePath() === dbPath && refreshWorkflowDatabaseFromDisk()) {
+        return true;
+      }
+      return openWorkflowDatabasePath(dbPath);
+    }
+
+    if (isDbAvailable() && getWorkflowDatabasePath() === dbPath) return true;
+    return openWorkflowDatabasePath(dbPath);
+  } catch (err) {
+    logWarning("reconcile", `ensureWorkflowDbForBase could not reopen DB: ${(err as Error).message}`);
+    return false;
+  }
+}
+
 export function checkpointWorkflowDatabase(): void {
   checkpointDatabase();
 }

package/src/resources/extensions/gsd/delegation-policy.ts

@@ -121,7 +121,7 @@ const POLICY: Record<string, DelegationPolicyEntry> = {
     toolName: "gsd_plan_task",
     verdict: "no",
     rationale:
-      "plan-slice prompt explicitly forbids calling gsd_plan_task separately; per-task granularity multiplies manifest writes and projection re-renders with no payoff.",
+      "Incremental task planning mutates the active slice plan and re-renders projections; keep it ordered in the foreground plan-slice unit.",
   },
 };
 

package/src/resources/extensions/gsd/discussion-handoff.ts

@@ -11,7 +11,7 @@ import {
   assessMilestoneHandoffReadiness,
   formatAcceptedDiscussHandoffMessage,
 } from "./milestone-readiness.js";
-import { gsdRoot, resolveGsdRootFile, resolveMilestoneFile } from "./paths.js";
+import { clearPathCache, gsdRoot, resolveGsdRootFile, resolveMilestoneFile } from "./paths.js";
 import { _getPendingAutoStart, deletePendingAutoStart, type PendingAutoStartEntry } from "./pending-auto-start.js";
 import { logWarning } from "./workflow-logger.js";
 import { readManifest } from "./workflow-manifest.js";
@@ -241,14 +241,18 @@ function cleanupAcceptedHandoffArtifacts(entry: PendingAutoStartEntry): void {
 
 /** Called from agent_end to check if auto-mode should start after discuss. */
 export function checkAutoStartAfterDiscuss(lookupBasePath?: string): boolean {
+  // Clear the path cache so layout-aware resolution sees fresh directory
+  // listings — the cache may have been primed before discuss wrote its
+  // artifacts (e.g. CONTEXT.md), causing resolveMilestoneFile to miss them.
+  clearPathCache();
   const entry = _getPendingAutoStart(lookupBasePath);
   if (!entry) return false;
 
   const { ctx, pi, basePath, milestoneId, step } = entry;
-  const contextFilePath = entry.scope.contextFile();
-  const roadmapFilePath = entry.scope.roadmapFile();
-  const contextFile = existsSync(contextFilePath) ? contextFilePath : null;
-  const roadmapFile = existsSync(roadmapFilePath) ? roadmapFilePath : null;
+  // Use layout-aware resolution so flat-phase projects (phases/NN-slug/)
+  // are found as well as legacy projects (milestones/MID/).
+  const contextFile = resolveMilestoneFile(basePath, milestoneId, "CONTEXT");
+  const roadmapFile = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
   if (!contextFile && !roadmapFile) return false;
 
   if (hasBlockingDepthGate(entry)) return false;

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -273,10 +273,10 @@ This config sets a parent workspace with two child repositories. The implicit `p
   - `audit_unified.enabled`: boolean — dual-write unified audit envelope events. Default: `true`.
   - `plan_v2.enabled`: boolean — enable bounded clarify/research/draft/compile planning flow. Default: `true`.
 
-- `context_management`: configures context hygiene for auto-mode sessions. Keys:
+- `context_management`: configures context hygiene for auto-mode sessions. In step mode, the configurable threshold is a soft warning; automatic session re-rooting happens only at the fixed 90% hard context boundary. Keys:
   - `observation_masking`: boolean — mask old tool results to reduce context bloat. Default: `true`.
   - `observation_mask_turns`: number — keep this many recent turns verbatim (1-50). Default: `8`.
-  - `compaction_threshold_percent`: number — trigger compaction at this % of context window (0.5-0.95). Lower values fire compaction earlier, reducing drift. Default: `0.60`.
+  - `compaction_threshold_percent`: number — show a soft context warning at this fraction of the context window (0.5-0.95). Lower values warn earlier so operators can compact manually before drift accumulates. Default: `0.60`.
   - `tool_result_max_chars`: number — max chars per tool result in GSD sessions (200-10000). Default: `800`.
 
 - `auto_visualize`: boolean — show a visualizer hint after each milestone completion in auto-mode. Default: `false`.