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

package/dist/resources/extensions/gsd/commands-prefs-wizard.js

@@ -533,6 +533,19 @@ export function buildCategorySummaries(prefs) {
         if (parts.length > 0)
             integrationsSummary = parts.join(", ");
     }
+    // Workspace (parent-workspace multi-repo)
+    const workspace = prefs.workspace;
+    const workspaceRepos = workspace?.repositories;
+    let workspaceSummary = "(single-repo)";
+    {
+        const parts = [];
+        if (workspace?.mode)
+            parts.push(`mode: ${workspace.mode}`);
+        if (workspaceRepos && Object.keys(workspaceRepos).length > 0)
+            parts.push(`${Object.keys(workspaceRepos).length} repo(s)`);
+        if (parts.length > 0)
+            workspaceSummary = parts.join(", ");
+    }
     return {
         mode: modeSummary,
         models: modelsSummary,
@@ -550,6 +563,7 @@ export function buildCategorySummaries(prefs) {
         hooks: hooksSummary,
         uok: uokSummary,
         integrations: integrationsSummary,
+        workspace: workspaceSummary,
     };
 }
 // ─── Category configuration functions ────────────────────────────────────────
@@ -716,7 +730,10 @@ async function configureDynamicRouting(ctx, prefs) {
     const hooks = await promptBoolean(ctx, "Route hook sessions dynamically", dr.hooks, true);
     if (hooks !== undefined)
         dr.hooks = hooks;
-    const flatRate = await promptBoolean(ctx, "Allow dynamic routing for flat-rate providers", dr.allow_flat_rate_providers, false);
+    // Opt-out flag (#1115): routing is allowed for flat-rate providers by
+    // default; only an explicit `false` suppresses it. The default hint reflects
+    // that allow-by-default behavior.
+    const flatRate = await promptBoolean(ctx, "Allow dynamic routing for flat-rate providers", dr.allow_flat_rate_providers, true);
     if (flatRate !== undefined)
         dr.allow_flat_rate_providers = flatRate;
     // tier_models.light / standard / heavy — optional model IDs
@@ -892,6 +909,135 @@ async function configureSkills(ctx, prefs) {
     const staleness = await promptInteger(ctx, "Skill staleness days (0 to disable)", prefs.skill_staleness_days, "60");
     applyNumber(prefs, "skill_staleness_days", staleness);
 }
+async function configureWorkspace(ctx, prefs) {
+    let workspace = (prefs.workspace ?? {});
+    // Mode
+    const mode = await promptEnum(ctx, "Workspace mode", workspace.mode, ["project", "parent"]);
+    if (mode !== undefined)
+        workspace = { ...workspace, mode: mode };
+    if (workspace.mode !== "parent") {
+        // Single-repo mode: drop any declared repositories and persist.
+        if (workspace.repositories && Object.keys(workspace.repositories).length > 0) {
+            const clear = await promptBoolean(ctx, "Clear declared repositories (switch to single-repo)?", false, false);
+            if (clear)
+                workspace = { mode: workspace.mode };
+        }
+        persistWorkspace(prefs, workspace);
+        return;
+    }
+    // Parent mode — edit child repositories via a sub-menu.
+    let repositories = { ...(workspace.repositories ?? {}) };
+    while (true) {
+        const ids = Object.keys(repositories).sort();
+        const summary = ids.length === 0 ? "(no repositories — parent mode requires at least one)" : `${ids.length} repo(s)`;
+        const listLabels = ids.map((id) => {
+            const r = repositories[id];
+            const roleStr = r.role ? ` — ${r.role}` : "";
+            const policyStr = r.commit_policy === "skip" ? " [skip]" : "";
+            return `${id} (${r.path})${roleStr}${policyStr}`;
+        });
+        const choice = await ctx.ui.select(`Declared repositories — ${summary}`, [...listLabels, "Add repository", "Done"]);
+        const pick = typeof choice === "string" ? choice : "";
+        if (!pick || pick === "Done")
+            break;
+        if (pick === "Add repository") {
+            const idInput = await ctx.ui.input("Repository id (letters, digits, . _ -; 'project' is reserved):", "");
+            const id = typeof idInput === "string" ? idInput.trim() : "";
+            if (!id || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id)) {
+                ctx.ui.notify("Invalid repository id — must match ^[A-Za-z0-9][A-Za-z0-9._-]*$ and cannot be 'project'.", "warning");
+                continue;
+            }
+            if (id === "project" || repositories[id]) {
+                ctx.ui.notify(`Repository id "${id}" is reserved or already declared.`, "warning");
+                continue;
+            }
+            const pathInput = await ctx.ui.input("Repository path (relative to project root, e.g. frontend):", "");
+            const path = typeof pathInput === "string" ? pathInput.trim() : "";
+            if (!path) {
+                ctx.ui.notify("Repository path is required.", "warning");
+                continue;
+            }
+            const repo = { path };
+            const roleInput = await ctx.ui.input("Role/label (optional):", "");
+            if (typeof roleInput === "string" && roleInput.trim())
+                repo.role = roleInput.trim();
+            const verifyInput = await ctx.ui.input("Verification commands (comma- or newline-separated, optional):", "");
+            if (typeof verifyInput === "string" && verifyInput.trim()) {
+                const cmds = parseStringList(verifyInput);
+                if (cmds.length > 0)
+                    repo.verification = cmds;
+            }
+            const policy = await promptEnum(ctx, "Commit policy", undefined, ["auto", "skip"]);
+            if (policy === "skip")
+                repo.commit_policy = "skip";
+            repositories[id] = repo;
+        }
+        else {
+            // Edit/delete an existing repo (the first token is the id).
+            const id = pick.split(" ")[0];
+            if (!repositories[id])
+                continue;
+            const editChoice = await ctx.ui.select(`Repository ${id}`, ["Edit path", "Edit role", "Edit verification", "Edit commit policy", "Delete repository", "Cancel"]);
+            const ec = typeof editChoice === "string" ? editChoice : "";
+            if (!ec || ec === "Cancel")
+                continue;
+            if (ec === "Delete repository") {
+                delete repositories[id];
+            }
+            else if (ec === "Edit path") {
+                const v = await ctx.ui.input("Repository path:", repositories[id].path);
+                if (typeof v === "string" && v.trim())
+                    repositories[id] = { ...repositories[id], path: v.trim() };
+            }
+            else if (ec === "Edit role") {
+                const v = await ctx.ui.input("Role/label (blank to clear):", repositories[id].role ?? "");
+                if (typeof v === "string" && v.trim())
+                    repositories[id] = { ...repositories[id], role: v.trim() };
+                else if (typeof v === "string") {
+                    const { role, ...rest } = repositories[id];
+                    void role;
+                    repositories[id] = rest;
+                }
+            }
+            else if (ec === "Edit verification") {
+                const v = await ctx.ui.input("Verification commands (blank to clear):", (repositories[id].verification ?? []).join(", "));
+                if (typeof v === "string" && v.trim()) {
+                    const cmds = parseStringList(v);
+                    if (cmds.length > 0)
+                        repositories[id] = { ...repositories[id], verification: cmds };
+                }
+                else if (typeof v === "string") {
+                    const { verification, ...rest } = repositories[id];
+                    void verification;
+                    repositories[id] = rest;
+                }
+            }
+            else if (ec === "Edit commit policy") {
+                const policy = await promptEnum(ctx, "Commit policy", repositories[id].commit_policy, ["auto", "skip"]);
+                if (policy === "skip")
+                    repositories[id] = { ...repositories[id], commit_policy: "skip" };
+                else {
+                    const { commit_policy, ...rest } = repositories[id];
+                    void commit_policy;
+                    repositories[id] = rest;
+                }
+            }
+        }
+    }
+    if (Object.keys(repositories).length === 0) {
+        ctx.ui.notify("Parent mode requires at least one repository — mode not saved.", "warning");
+        return;
+    }
+    persistWorkspace(prefs, { mode: "parent", repositories });
+}
+/** Persist the workspace config onto prefs, dropping it entirely when empty. */
+function persistWorkspace(prefs, workspace) {
+    if (!workspace.mode && (!workspace.repositories || Object.keys(workspace.repositories).length === 0)) {
+        delete prefs.workspace;
+        return;
+    }
+    prefs.workspace = workspace;
+}
 async function configureSkillRules(ctx, prefs) {
     let rules = Array.isArray(prefs.skill_rules) ? [...prefs.skill_rules] : [];
     while (true) {
@@ -1100,6 +1246,8 @@ async function configureVerification(ctx, prefs) {
         prefs.verification_auto_fix = autoFix;
     const maxRetries = await promptInteger(ctx, "Verification max retries", prefs.verification_max_retries, "2");
     applyNumber(prefs, "verification_max_retries", maxRetries);
+    const perUnitCap = await promptNumber(ctx, "Per-unit cost cap (USD; retry cost ceiling, blank = clear to default)", prefs.per_unit_cost_cap_usd, "5.0");
+    applyNumber(prefs, "per_unit_cost_cap_usd", perUnitCap);
     const ev = await promptBoolean(ctx, "Enhanced verification (master toggle)", prefs.enhanced_verification, true);
     if (ev !== undefined)
         prefs.enhanced_verification = ev;
@@ -1164,7 +1312,7 @@ async function configureContextCodebase(ctx, prefs) {
         cm.observation_mask_turns = maskTurns;
     else if (maskTurns === "clear")
         delete cm.observation_mask_turns;
-    const thresh = await promptNumber(ctx, "Compaction threshold percent (0.5–0.95)", cm.compaction_threshold_percent, "0.60");
+    const thresh = await promptNumber(ctx, "Soft context warning threshold percent (0.5–0.95)", cm.compaction_threshold_percent, "0.60");
     if (thresh !== undefined && thresh !== "clear")
         cm.compaction_threshold_percent = thresh;
     else if (thresh === "clear")
@@ -1564,6 +1712,7 @@ export async function handlePrefsWizard(ctx, scope, prefill, opts) {
             `Hooks           ${summaries.hooks}`,
             `UoK             ${summaries.uok}`,
             `Integrations    ${summaries.integrations}`,
+            `Workspace       ${summaries.workspace}`,
             `Advanced        ${summaries.advanced}`,
             `── Save & Exit ──`,
         ];
@@ -1601,6 +1750,8 @@ export async function handlePrefsWizard(ctx, scope, prefill, opts) {
             await configureUoK(ctx, prefs);
         else if (choice.startsWith("Integrations"))
             await configureIntegrations(ctx, prefs);
+        else if (choice.startsWith("Workspace"))
+            await configureWorkspace(ctx, prefs);
         else if (choice.startsWith("Advanced"))
             await configureAdvanced(ctx, prefs);
     }
@@ -1727,6 +1878,7 @@ export function serializePreferencesToFrontmatter(prefs) {
         "reactive_execution", "gate_evaluation",
         "auto_visualize", "auto_report",
         "verification_commands", "verification_auto_fix", "verification_max_retries",
+        "per_unit_cost_cap_usd",
         "enhanced_verification", "enhanced_verification_pre",
         "enhanced_verification_post", "enhanced_verification_strict",
         "safety_harness",

package/dist/resources/extensions/gsd/commands-usage.js

@@ -83,7 +83,7 @@ function formatThresholdLines() {
     }
     const compactionThreshold = prefs?.context_management?.compaction_threshold_percent;
     if (typeof compactionThreshold === "number") {
-        lines.push(`Compaction: ${Math.round(compactionThreshold * 100)}%`);
+        lines.push(`Soft context warning: ${Math.round(compactionThreshold * 100)}%`);
     }
     return lines;
 }

package/dist/resources/extensions/gsd/commands-worktree.js

@@ -251,8 +251,17 @@ async function handleRemove(args, ctx) {
         return;
     }
     try {
-        removeWorktree(basePath, name, { deleteBranch: true });
-        ctx.ui.notify(`Removed worktree ${name}.`, "info");
+        const removed = removeWorktree(basePath, name, { deleteBranch: true });
+        if (removed) {
+            ctx.ui.notify(`Removed worktree ${name}.`, "info");
+        }
+        else {
+            ctx.ui.notify([
+                `Worktree removal aborted for "${name}" to preserve uncommitted changes.`,
+                "",
+                "Manual quarantine recovery may be needed before retrying removal.",
+            ].join("\n"), "warning");
+        }
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);

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

@@ -19,7 +19,7 @@ import { createCoordinationTablesV24 } from "../db-coordination-schema.js";
 import { createDbConnectionCache } from "../db-connection-cache.js";
 import { backupDatabaseBeforeMigration, isMigrationBackupError } from "../db-migration-backup.js";
 import { applyMigrationV2Artifacts, applyMigrationV3Memories, applyMigrationV4DecisionMadeBy, applyMigrationV5HierarchyTables, applyMigrationV6SliceSummaries, applyMigrationV7Dependencies, applyMigrationV8PlanningFields, applyMigrationV9Ordering, applyMigrationV10ReplanTrigger, applyMigrationV11TaskPlanning, applyMigrationV12QualityGates, applyMigrationV13HotPathIndexes, applyMigrationV14SliceDependencies, applyMigrationV15AuditTables, applyMigrationV16EscalationSource, applyMigrationV17TaskEscalation, applyMigrationV18MemorySources, applyMigrationV19MemoryFts, applyMigrationV20MemoryRelations, applyMigrationV21StructuredMemories, applyMigrationV22QualityGateRepair, applyMigrationV23MilestoneQueue, applyMigrationV26MilestoneCommitAttributions, applyMigrationV27ArtifactHash, 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 } from "../db-open-state.js";
 import { createRuntimeKvTableV25 } from "../db-runtime-kv-schema.js";
 import { getCurrentSchemaVersion, recordSchemaVersion } from "../db-schema-metadata.js";
@@ -101,6 +101,9 @@ function initSchema(db, fileBacked, dbPath) {
         throw err;
     }
     migrateSchema(db, dbPath);
+    rebuildMemoriesFtsSchemaOnce(db, {
+        onRebuildFailed: (message) => logWarning("db", message),
+    });
 }
 export function _isLikelyWslDrvFsPathForTest(dbPath) {
     if (!dbPath || process.platform !== "linux")

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

@@ -327,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

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 { 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 } from "./paths.js";
-import { setLogBasePath } from "./workflow-logger.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 {
@@ -104,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

@@ -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);

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.