@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.5fc22c6f

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

@@ -12,6 +12,7 @@ import { rowToActiveDecision, rowToActiveRequirement, rowToDecision, rowToRequir
 import { rowToGate } from "../db-gate-rows.js";
 import { rowToArtifact, rowToMilestone } from "../db-milestone-artifact-rows.js";
 import { rowToSlice, rowToTask } from "../db-task-slice-rows.js";
+import { TERMINAL_STATUS_SQL } from "./sql-constants.js";
 function parseStringArrayColumn(raw) {
     if (Array.isArray(raw))
         return raw.filter((entry) => typeof entry === "string");
@@ -35,6 +36,44 @@ function parseStringArrayColumn(raw) {
 function normalizeRepoPath(file) {
     return file.trim().replace(/\\/g, "/").replace(/^\.\/+/, "");
 }
+function numberColumn(row, column) {
+    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) {
+    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() {
+    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) {
     if (!getDbOrNull())
         return null;
@@ -218,6 +257,46 @@ export function getMilestoneSlices(milestoneId) {
     const rows = getDbOrNull().prepare("SELECT * FROM slices WHERE milestone_id = :mid ORDER BY sequence, id").all({ ":mid": milestoneId });
     return rows.map(rowToSlice);
 }
+export function getParallelMonitorSliceProgress(milestoneId) {
+    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 function getParallelMonitorRecentCompletions(milestoneId, limit = 5) {
+    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.
@@ -248,6 +327,45 @@ export function getSlicesByMilestoneIds(milestoneIds) {
     }
     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) {
+    const bySlice = new Map();
+    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 = [];
+        const params = {};
+        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);
+        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;
+}
 /**
  * Consolidated DB read for dispatch/gate/completion decisions (ADR-017).
  * `done` uses the canonical closed-status predicate (`isClosedStatus`) — the
@@ -281,6 +399,20 @@ export function getArtifact(path) {
         return null;
     return rowToArtifact(row);
 }
+/** Milestone-level artifacts (CONTEXT, RESEARCH, VALIDATION, etc.) from the artifacts table. */
+export function getMilestoneScopedArtifacts(milestoneId) {
+    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, sliceId) {
+    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() {
     if (!getDbOrNull())
@@ -337,6 +469,27 @@ export function getAssessment(path) {
     const row = getDbOrNull().prepare(`SELECT * FROM assessments WHERE path = :path`).get({ ":path": path });
     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, sliceId) {
+    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, scope) {
     if (!getDbOrNull())
         return null;

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

@@ -387,10 +387,31 @@ export function getRecentUnitKeysForWorker(workerId, limit = 20) {
     // Reverse so callers consume oldest-first (sliding-window semantics).
     return rows.reverse().map((r) => ({ key: r.unit_id }));
 }
-export function getRecentUnitKeysForProjectRoot(projectRootRealpath, limit = 20) {
+export function getRecentUnitKeysForProjectRoot(projectRootRealpath, limit = 20, traceId) {
     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,
+        });
+        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
      INNER JOIN workers w ON w.worker_id = ud.worker_id

package/dist/resources/extensions/gsd/db-memory-fts-schema.js

@@ -1,5 +1,7 @@
 // Project/App: gsd-pi
 // File Purpose: Memory FTS5 SQLite schema helpers for the GSD database facade.
+import { createRuntimeKvTableV25 } from "./db-runtime-kv-schema.js";
+export const MEMORIES_FTS_REBUILT_KEY = "memories_fts_rebuilt_at";
 function formatFtsUnavailableError(err) {
     const message = err instanceof Error ? err.message : String(err);
     return message.replace(/\bmoduel\s*:\s*/gi, "module: ");
@@ -54,3 +56,35 @@ export function isMemoriesFtsAvailableSchema(db) {
         return false;
     }
 }
+export function rebuildMemoriesFtsSchemaOnce(db, options = {}) {
+    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.message}`);
+    }
+}

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

@@ -1,10 +1,24 @@
 // Project/App: gsd-pi
 // File Purpose: Workspace-facing Interface for opening and maintaining the workflow database.
 import { existsSync } from "node:fs";
-import { dirname } from "node:path";
-import { backupDatabaseSnapshot, checkpointDatabase, closeAllDatabases, closeDatabase, closeDatabaseByWorkspace, getDbPath, getDbStatus, getDbProvider, isDbAvailable, openDatabase, openDatabaseByScope, openDatabaseByWorkspace, refreshOpenDatabaseFromDisk, vacuumDatabase, wasDbOpenAttempted, } from "./gsd-db.js";
-import { resolveGsdPathContract } from "./paths.js";
-import { setLogBasePath } from "./workflow-logger.js";
+import { dirname, join } from "node:path";
+import { backupDatabaseSnapshot, checkpointDatabase, closeAllDatabases, closeDatabase, closeDatabaseByWorkspace, getDbPath, getDbStatus, getDbProvider, isDbAvailable, openDatabase, openDatabaseByScope, openDatabaseByWorkspace, openIsolatedDatabase, refreshOpenDatabaseFromDisk, vacuumDatabase, wasDbOpenAttempted, } from "./gsd-db.js";
+import { resolveGsdPathContract, gsdRoot } from "./paths.js";
+import { logWarning, setLogBasePath } from "./workflow-logger.js";
+/**
+ * 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) {
     const contract = resolveGsdPathContract(basePath);
     return {
@@ -59,6 +73,18 @@ export function openExistingWorkflowDatabase(basePath) {
 export function openWorkflowDatabasePath(path) {
     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) {
+    return openIsolatedDatabase(path);
+}
 export function openWorkflowDatabaseByWorkspace(workspace) {
     return openDatabaseByWorkspace(workspace);
 }
@@ -92,6 +118,44 @@ export function getWorkflowDatabasePath() {
 export function refreshWorkflowDatabaseFromDisk() {
     return refreshOpenDatabaseFromDisk();
 }
+export function expectedWorkflowDbPathForBase(basePath) {
+    return join(gsdRoot(basePath), "gsd.db");
+}
+export function ensureWorkflowDbAtPath(dbPath) {
+    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.message}`);
+        return false;
+    }
+}
+export function ensureWorkflowDbForBase(basePath, options = {}) {
+    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.message}`);
+        return false;
+    }
+}
 export function checkpointWorkflowDatabase() {
     checkpointDatabase();
 }

package/dist/resources/extensions/gsd/delegation-policy.js

@@ -94,7 +94,7 @@ const POLICY = {
     gsd_plan_task: {
         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.",
+        rationale: "Incremental task planning mutates the active slice plan and re-renders projections; keep it ordered in the foreground plan-slice unit.",
     },
 };
 function resolveCanonical(name) {

package/dist/resources/extensions/gsd/discussion-handoff.js

@@ -6,7 +6,7 @@ import { startAutoDetached } from "./auto.js";
 import { extractDepthVerificationMilestoneId, getPendingGate } from "./bootstrap/write-gate.js";
 import { getMilestone, insertMilestone, isDbAvailable } from "./gsd-db.js";
 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 } from "./pending-auto-start.js";
 import { logWarning } from "./workflow-logger.js";
 import { readManifest } from "./workflow-manifest.js";
@@ -53,8 +53,10 @@ function noteDbRowRecoveryMiss(entry) {
     }
 }
 function ensureMilestoneRowForAcceptedHandoff(entry, contextFile) {
-    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);
     if (milestoneRow)
@@ -77,12 +79,15 @@ function ensureMilestoneRowForAcceptedHandoff(entry, contextFile) {
     }
     logWarning("guided", `R3b: ${milestoneId} has CONTEXT.md but no DB row — inserting placeholder "queued" row ` +
         `(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.message}`);
     }
+    if (inserted)
+        return true;
     if (getMilestone(milestoneId))
         return true;
     noteDbRowRecoveryMiss(entry);
@@ -186,14 +191,18 @@ function cleanupAcceptedHandoffArtifacts(entry) {
 }
 /** Called from agent_end to check if auto-mode should start after discuss. */
 export function checkAutoStartAfterDiscuss(lookupBasePath) {
+    // 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))

package/dist/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.