@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

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

@@ -47,7 +47,11 @@ import {
   applyMigrationV28MemoryLastHitAt,
   applyMigrationV29RepositoryTargets,
 } from "../db-migration-steps.js";
-import { isMemoriesFtsAvailableSchema, tryCreateMemoriesFtsSchema } from "../db-memory-fts-schema.js";
+import {
+  isMemoriesFtsAvailableSchema,
+  rebuildMemoriesFtsSchemaOnce,
+  tryCreateMemoriesFtsSchema,
+} from "../db-memory-fts-schema.js";
 import { createDbOpenState, type DbOpenPhase } from "../db-open-state.js";
 import { createRuntimeKvTableV25 } from "../db-runtime-kv-schema.js";
 import { getCurrentSchemaVersion, recordSchemaVersion } from "../db-schema-metadata.js";
@@ -134,6 +138,9 @@ function initSchema(db: DbAdapter, fileBacked: boolean, dbPath: string | null):
   }
 
   migrateSchema(db, dbPath);
+  rebuildMemoriesFtsSchemaOnce(db, {
+    onRebuildFailed: (message) => logWarning("db", message),
+  });
 }
 
 export function _isLikelyWslDrvFsPathForTest(dbPath: string | null): boolean {
@@ -671,6 +678,32 @@ export function closeDatabase(): void {
   _dbOpenState.reset();
 }
 
+/**
+ * Open an isolated database connection that does NOT touch the process-wide
+ * `currentDb` singleton. Intended for background observers (e.g. the parallel
+ * monitor overlay) that must read a database without displacing an active
+ * workflow session connection.
+ *
+ * The caller MUST call `adapter.close()` when done. Schema migrations are NOT
+ * run — the database must already exist and be fully migrated by the primary
+ * connection. Returns null if the connection cannot be opened.
+ */
+export function openIsolatedDatabase(path: string): DbAdapter | null {
+  try {
+    const rawDb = providerLoader.openRaw(path);
+    if (!rawDb) return null;
+    const adapter = createDbAdapter(rawDb);
+    // Minimal pragmas for a short-lived read-only observer connection.
+    // WAL mode is already set file-wide by the primary connection; repeating
+    // it here is a no-op on an existing WAL file and safe to issue.
+    adapter.exec("PRAGMA journal_mode=WAL");
+    adapter.exec("PRAGMA busy_timeout = 5000");
+    return adapter;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Re-open the active database connection from disk.
  *

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.
@@ -299,6 +413,46 @@ export function getSlicesByMilestoneIds(milestoneIds: readonly string[]): Map<st
   return byMilestone;
 }
 
+/**
+ * Load tasks for many (milestone, slice) pairs in batched queries. Returns a Map
+ * keyed by `${milestone_id}\0${slice_id}`, preserving `ORDER BY sequence, id`
+ * within each bucket. Mirrors getSlicesByMilestoneIds to avoid an N+1 over tasks
+ * during full projection rebuilds.
+ */
+export function getTasksBySliceIds(
+  slices: ReadonlyArray<{ milestoneId: string; sliceId: string }>,
+): Map<string, TaskRow[]> {
+  const bySlice = new Map<string, TaskRow[]>();
+  const db = getDbOrNull();
+  if (!db || slices.length === 0) return bySlice;
+  // SQLite caps bound params (~999); 2 per pair, so chunk well under the limit.
+  const CHUNK = 400;
+  for (let start = 0; start < slices.length; start += CHUNK) {
+    const chunk = slices.slice(start, start + CHUNK);
+    const clauses: string[] = [];
+    const params: Record<string, unknown> = {};
+    chunk.forEach((s, i) => {
+      clauses.push(`(milestone_id = :m${i} AND slice_id = :s${i})`);
+      params[`:m${i}`] = s.milestoneId;
+      params[`:s${i}`] = s.sliceId;
+    });
+    const rows = db
+      .prepare(`SELECT * FROM tasks WHERE ${clauses.join(" OR ")} ORDER BY milestone_id, slice_id, sequence, id`)
+      .all(params) as Record<string, unknown>[];
+    for (const row of rows) {
+      const task = rowToTask(row);
+      const key = `${task.milestone_id}\0${task.slice_id}`;
+      const bucket = bySlice.get(key);
+      if (bucket) {
+        bucket.push(task);
+      } else {
+        bySlice.set(key, [task]);
+      }
+    }
+  }
+  return bySlice;
+}
+
 /** Dispatch-eligibility shape consumed by decision-path callers (ADR-017). */
 export interface MilestoneSliceSummary {
   id: string;
@@ -342,6 +496,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 +584,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";
@@ -82,7 +82,13 @@ function ensureMilestoneRowForAcceptedHandoff(
   entry: PendingAutoStartEntry,
   contextFile: string | null,
 ): boolean {
-  if (!isDbAvailable()) return true;
+  if (!isDbAvailable()) {
+    logWarning(
+      "guided",
+      `R3b: milestone ${entry.milestoneId} DB-row recovery skipped because DB is unavailable`,
+    );
+    return false;
+  }
 
   const { basePath, milestoneId } = entry;
   const milestoneRow = getMilestone(milestoneId);
@@ -122,12 +128,14 @@ function ensureMilestoneRowForAcceptedHandoff(
     `(attempt ${entry.r3bRecoveryCount + 1}/${MAX_DB_ROW_RECOVERIES})`,
   );
 
+  let inserted = false;
   try {
-    insertMilestone({ id: milestoneId, title: milestoneId, status: "queued" });
+    inserted = insertMilestone({ id: milestoneId, title: milestoneId, status: "queued" });
   } catch (e) {
     logWarning("guided", `R3b: insertMilestone failed: ${(e as Error).message}`);
   }
 
+  if (inserted) return true;
   if (getMilestone(milestoneId)) return true;
 
   noteDbRowRecoveryMiss(entry);
@@ -241,14 +249,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

@@ -163,7 +163,7 @@ Diagnostics record the file path, scope (global/project), severity (error/warnin
   - **Deprecated:** `merge_to_main` — no longer valid; milestone-level merge is always used. Remove this setting.
 
 - `workspace`: configures multi-repository parent workspaces. Keys:
-  - `mode`: `"project"` (default single-repo behavior) or `"parent"` (one `.gsd` controlling child repos).
+  - `mode`: `"project"` (default single-repo behavior) or `"parent"` (one `.gsd` controlling child repos). In `"parent"` mode at least one child repository must be declared under `repositories`, otherwise the setting is rejected at validation time.
   - `repositories`: object map of repository IDs to config.
     - Repository ID format: `^[A-Za-z0-9][A-Za-z0-9._-]*$`.
     - Reserved ID: `project` is implicit and always maps to the project root; user-defined `workspace.repositories.project` is rejected.
@@ -171,6 +171,8 @@ Diagnostics record the file path, scope (global/project), severity (error/warnin
     - `role`: optional short description of what the repo owns.
     - `verification`: optional array of verification commands for that repo.
     - `commit_policy`: optional `"auto"` or `"skip"` to include or skip commit actions per repo.
+  - Planning tools consume repository IDs through `targetRepositories`: `gsd_plan_slice.targetRepositories` sets a slice-wide default, and `gsd_plan_task.targetRepositories` records the repositories an individual task touches. Values must be declared IDs or the implicit `project`; omit these fields in single-repo projects.
+  - In parent mode with declared child repositories, `/gsd codebase generate` and automatic `.gsd/CODEBASE.md` refreshes enumerate `project` plus each child repository, render repo-labeled sections, and store repository IDs in map metadata.
 
 ## Workspace Example
 
@@ -198,6 +200,8 @@ workspace:
 
 This config sets a parent workspace with two child repositories. The implicit `project` repository is always created for the project root and cannot be user-defined.
 
+In `"parent"` mode, slice/task `targetRepositories` default to the declared child repositories (here `frontend` and `backend`) rather than the root `project` repo. In `"project"` mode (the default), `targetRepositories` defaults to `["project"]`.
+
 - `unique_milestone_ids`: boolean — when `true`, generates milestone IDs in `M{seq}-{rand6}` format (e.g. `M001-eh88as`) instead of plain sequential `M001`. Prevents ID collisions in team workflows where multiple contributors create milestones concurrently. Both formats coexist — existing `M001`-style milestones remain valid. Default: `false`.
 
 - `budget_ceiling`: number — maximum dollar amount to spend on auto-mode. When reached, behavior is controlled by `budget_enforcement`. Default: no limit.
@@ -273,10 +277,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`.
@@ -303,7 +307,9 @@ This config sets a parent workspace with two child repositories. The implicit `p
     - `verification`: string[] (optional) — repository-specific verification commands used when global `verification_commands` is not set.
     - `commit_policy`: `"auto"` | `"skip"` (optional) — per-repository closeout commit behavior.
   - `project` is always an implicit repository target mapped to the project root for backward compatibility.
-  - Plan/task `targetRepositories` defaults to `["project"]` when omitted.
+  - `targetRepositories` on `gsd_plan_slice` sets the slice-wide default. `targetRepositories` on `gsd_plan_task` records or overrides the repository IDs for an individual task.
+  - Values must match declared repository IDs or the implicit `project`; omitted plan/task `targetRepositories` defaults to `["project"]`.
+  - `/gsd codebase` is workspace-aware in parent mode with declared child repositories: generated `.gsd/CODEBASE.md` uses workspace-relative paths, groups files under `## [repo-id]` headings, and refreshes when repository registry metadata changes.
 
 - `verification_commands`: string[] — shell commands to run as verification after task execution (e.g., `["npm test", "npm run lint"]`). Commands run in order; if any fails, the task is marked as needing fixes.