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

package/dist/resources/extensions/gsd/bootstrap/write-gate.js

@@ -21,6 +21,12 @@ import { evaluateGateAnswer } from "../consent-verdict.js";
 export const MILESTONE_CONTEXT_RE = /M\d+(?:-[a-z0-9]{6})?-CONTEXT\.md$/;
 const CONTEXT_MILESTONE_RE = /(?:^|[/\\])(M\d+(?:-[a-z0-9]{6})?)-CONTEXT\.md$/i;
 const DEPTH_VERIFICATION_MILESTONE_RE = /depth_verification[_-](M\d+(?:-[a-z0-9]{6})?)/i;
+function normalizeMilestoneId(milestoneId) {
+    const match = milestoneId.match(/^(M)(\d+)(?:-([a-z0-9]{6}))?$/i);
+    if (!match)
+        return milestoneId;
+    return `M${match[2]}${match[3] ? `-${match[3].toLowerCase()}` : ""}`;
+}
 /**
  * Path segment that identifies .gsd/ planning artifacts.
  * Writes to these paths are allowed during queue mode.
@@ -75,8 +81,18 @@ function createEmptyWriteGateState() {
     };
 }
 const writeGateStatesByBasePath = new Map();
+/**
+ * Write-gate snapshots are project-scoped, not worktree-scoped. When auto-mode
+ * routes MCP tool writes to `.gsd-worktrees/<MID>/`, depth verification still
+ * lands in the authoritative project `.gsd/runtime/` tree (or external-state
+ * symlink target). Without this canonicalization, `loadWriteGateSnapshot(worktree)`
+ * sees an empty snapshot and CONTEXT saves loop forever (#M020 gate loop).
+ */
+function resolveWriteGateSnapshotRoot(basePath) {
+    return resolve(resolveWorktreeProjectRoot(basePath));
+}
 function writeGateStateKey(basePath) {
-    return resolve(basePath);
+    return resolveWriteGateSnapshotRoot(basePath);
 }
 function getWriteGateState(basePath = process.cwd()) {
     const key = writeGateStateKey(basePath);
@@ -117,16 +133,17 @@ function shouldPersistWriteGateSnapshot(env = process.env) {
     return v !== "0" && v !== "false";
 }
 function writeGateSnapshotPath(basePath) {
-    return join(basePath, ".gsd", "runtime", "write-gate-state.json");
+    return join(resolveWriteGateSnapshotRoot(basePath), ".gsd", "runtime", "write-gate-state.json");
 }
 function ensureWriteGateSnapshotDirectory(basePath) {
-    const gsdPath = join(basePath, ".gsd");
+    const snapshotRoot = resolveWriteGateSnapshotRoot(basePath);
+    const gsdPath = join(snapshotRoot, ".gsd");
     if (!existsSync(gsdPath)) {
         try {
             const stat = lstatSync(gsdPath);
             if (stat.isSymbolicLink()) {
                 const target = readlinkSync(gsdPath);
-                mkdirSync(isAbsolute(target) ? target : resolve(basePath, target), { recursive: true });
+                mkdirSync(isAbsolute(target) ? target : resolve(snapshotRoot, target), { recursive: true });
             }
         }
         catch {
@@ -135,7 +152,7 @@ function ensureWriteGateSnapshotDirectory(basePath) {
     }
     mkdirSync(join(gsdPath, "runtime"), { recursive: true });
 }
-function currentWriteGateSnapshot(basePath = process.cwd()) {
+export function currentWriteGateSnapshot(basePath = process.cwd()) {
     const state = getWriteGateState(basePath);
     return {
         verifiedDepthMilestones: [...state.verifiedDepthMilestones].sort(),
@@ -190,7 +207,9 @@ function clearPersistedWriteGateSnapshot(basePath) {
 function normalizeWriteGateSnapshot(value) {
     const record = value && typeof value === "object" ? value : {};
     const verified = Array.isArray(record.verifiedDepthMilestones)
-        ? record.verifiedDepthMilestones.filter((item) => typeof item === "string")
+        ? record.verifiedDepthMilestones
+            .filter((item) => typeof item === "string")
+            .map(normalizeMilestoneId)
         : [];
     const verifiedGates = Array.isArray(record.verifiedApprovalGates)
         ? record.verifiedApprovalGates.filter((item) => typeof item === "string")
@@ -246,7 +265,7 @@ export function loadWriteGateSnapshot(basePath) {
  */
 function mergeSnapshotIntoState(state, disk) {
     for (const milestone of disk.verifiedDepthMilestones)
-        state.verifiedDepthMilestones.add(milestone);
+        state.verifiedDepthMilestones.add(normalizeMilestoneId(milestone));
     for (const gate of disk.verifiedApprovalGates ?? [])
         state.verifiedApprovalGates.add(gate);
     state.activeQueuePhase = disk.activeQueuePhase;
@@ -344,12 +363,12 @@ export function isMilestoneDepthVerified(milestoneId, basePath = process.cwd())
     if (!milestoneId)
         return false;
     refreshWriteGateStateFromDisk(basePath);
-    return getWriteGateState(basePath).verifiedDepthMilestones.has(milestoneId);
+    return getWriteGateState(basePath).verifiedDepthMilestones.has(normalizeMilestoneId(milestoneId));
 }
 export function isMilestoneDepthVerifiedInSnapshot(snapshot, milestoneId) {
     if (!milestoneId)
         return false;
-    return snapshot.verifiedDepthMilestones.includes(milestoneId);
+    return snapshot.verifiedDepthMilestones.includes(normalizeMilestoneId(milestoneId));
 }
 export function isQueuePhaseActive(basePath = process.cwd()) {
     return getWriteGateState(basePath).activeQueuePhase;
@@ -401,14 +420,14 @@ export function isGateQuestionId(questionId) {
  */
 export function extractDepthVerificationMilestoneId(questionId) {
     const match = questionId.match(DEPTH_VERIFICATION_MILESTONE_RE);
-    return match?.[1] ?? null;
+    return match?.[1] ? normalizeMilestoneId(match[1]) : null;
 }
 /**
  * Extract the milestone ID from a milestone CONTEXT file path.
  */
 function extractContextMilestoneId(inputPath) {
     const match = inputPath.match(CONTEXT_MILESTONE_RE);
-    return match?.[1] ?? null;
+    return match?.[1] ? normalizeMilestoneId(match[1]) : null;
 }
 /**
  * Mark a gate as pending (called when ask_user_questions is invoked with a
@@ -465,7 +484,7 @@ export const hostWriteGateAdapter = {
         if (!milestoneId)
             return;
         mutateWriteGateState(basePath, (state) => {
-            state.verifiedDepthMilestones.add(milestoneId);
+            state.verifiedDepthMilestones.add(normalizeMilestoneId(milestoneId));
         }, { writer: "host" });
     },
     markApprovalGateVerified(gateId, basePath) {
@@ -509,7 +528,7 @@ export const childWriteGateAdapter = {
         if (!milestoneId)
             return;
         childMutate(basePath, (state) => {
-            state.verifiedDepthMilestones.add(milestoneId);
+            state.verifiedDepthMilestones.add(normalizeMilestoneId(milestoneId));
         });
     },
     markApprovalGateVerified(gateId, basePath) {
@@ -622,6 +641,17 @@ function verifyAnsweredGate(basePath, question, fallbackMilestoneId) {
 function unresolvedGateResult(verdict, gateId, details) {
     if (verdict === "declined")
         return { status: "declined", gateId };
+    if (verdict === "timeout") {
+        // Host elicitation expired before the user answered. The gate stays
+        // pending (fail-closed — a timeout is never approval), but the status is
+        // "timeout" so the caller pauses-and-waits instead of re-asking into the
+        // same timeout loop (#852).
+        return {
+            status: "timeout",
+            pendingGateId: gateId,
+            interrupted: details.interrupted === true,
+        };
+    }
     // "waiting" (and the unreachable post-cancel case): an empty selection is
     // not an answer — keep the gate pending and make the caller pause.
     return {
@@ -646,6 +676,16 @@ export function applyAskUserQuestionsGateResult(options) {
     const { basePath, questions, details, fallbackMilestoneId } = options;
     const currentPendingGate = getPendingGate(basePath);
     if (currentPendingGate) {
+        if (details.timed_out) {
+            // Host elicitation timed out before the user answered. Keep the gate
+            // pending (fail-closed) but report "timeout" so the caller pauses-and-
+            // waits instead of re-asking into the same timeout loop (#852).
+            return {
+                status: "timeout",
+                pendingGateId: currentPendingGate,
+                interrupted: details.interrupted === true,
+            };
+        }
         if (details.cancelled || !details.response) {
             return {
                 status: "waiting",
@@ -662,6 +702,8 @@ export function applyAskUserQuestionsGateResult(options) {
             return unresolvedGateResult(verdict, currentPendingGate, details);
         }
     }
+    if (details.timed_out)
+        return { status: "not-gate" };
     if (details.cancelled || !details.response)
         return { status: "not-gate" };
     for (const question of questions) {
@@ -691,12 +733,27 @@ export function formatPendingAskUserQuestionsGateMessage(pendingGateId, interrup
         `Re-call ask_user_questions with the same gate question id ("${pendingGateId}") and wait for the user's response.`,
     ].join(" ");
 }
+/**
+ * Format the LLM-facing message returned when a depth-confirmation gate
+ * elicitation times out. Distinct from {@link formatPendingAskUserQuestionsGateMessage}:
+ * a timeout must NOT tell the model to immediately re-ask (that re-triggers
+ * the same timeout loop). Instead it tells the model to stop, that auto-mode
+ * is paused, and that the user will respond on their own (#852).
+ */
+export function formatTimedOutAskUserQuestionsGateMessage(pendingGateId) {
+    return [
+        `Depth confirmation on gate "${pendingGateId}" timed out waiting for a response.`,
+        "The user did not answer within the host elicitation window — do not re-ask in this turn, it will time out again.",
+        "Auto-mode is paused. Stop calling tools and wait for the user to respond on a new turn.",
+        "When the user replies with confirmation, the gate will be satisfied and work will resume.",
+    ].join(" ");
+}
 export function shouldBlockContextWrite(toolName, inputPath, milestoneId, _queuePhaseActive, basePath = process.cwd()) {
     if (toolName !== "write")
         return { block: false };
     if (!MILESTONE_CONTEXT_RE.test(inputPath))
         return { block: false };
-    const targetMilestoneId = extractContextMilestoneId(inputPath) ?? milestoneId;
+    const targetMilestoneId = extractContextMilestoneId(inputPath) ?? (milestoneId ? normalizeMilestoneId(milestoneId) : null);
     if (!targetMilestoneId) {
         return {
             block: true,
@@ -714,8 +771,8 @@ export function shouldBlockContextWrite(toolName, inputPath, milestoneId, _queue
         reason: [
             `HARD BLOCK: Cannot write to milestone CONTEXT.md without depth verification.`,
             `This is a mechanical gate — you MUST NOT proceed, retry, or rationalize past this block.`,
-            `Required action: call ask_user_questions with question id containing "depth_verification".`,
-            `The user MUST select the "(Recommended)" confirmation option to unlock this gate.`,
+            `Required action: call ask_user_questions with question id "depth_verification_${targetMilestoneId}_confirm".`,
+            `The user MUST select the first "(Recommended)" confirmation option to unlock this gate.`,
             `If the user declines, cancels, or the tool fails, you must re-ask — not bypass.`,
         ].join(" "),
     };
@@ -890,7 +947,7 @@ function allowedPlanningDispatchAgentsList() {
     return [...ALLOWED_PLANNING_DISPATCH_AGENTS].join(", ");
 }
 function allowsControlledSubagentDispatch(policy) {
-    return ((policy.mode === "planning-dispatch" || policy.mode === "verification") &&
+    return ((policy.mode === "planning-dispatch" || policy.mode === "verification" || policy.mode === "workflow-only") &&
         Array.isArray(policy.allowedSubagents));
 }
 function warnMissingControlledDispatchAgentClasses(unitType, mode, toolName) {
@@ -918,6 +975,7 @@ function warnMissingControlledDispatchAgentClasses(unitType, mode, toolName) {
 const PLANNING_SAFE_TOOLS = new Set([
     "read", "grep", "find", "ls", "glob",
     "ask_user_questions",
+    "memory_query",
     "search-the-web", "resolve_library", "get_library_docs", "fetch_page",
     "search_and_read",
 ]);
@@ -974,6 +1032,9 @@ function planningBlock(unitType, mode, what) {
  *                  → allows Bash for project verification commands, keeps
  *                    writes restricted to .gsd/, and permits subagent dispatch
  *                    only when the manifest declares allowedSubagents.
+ *   - "workflow-only"
+ *                  → allows reads, GSD workflow tools, and declared read-only
+ *                    subagents; blocks generic Bash and direct file writes.
  *
  * `pathOrCommand` is the file path for write/edit-shaped tools and the
  * shell command for bash. Other tools ignore this argument.
@@ -1044,6 +1105,15 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
         }
         return planningBlock(unitType, policy.mode, "subagent dispatch is not permitted in planning units");
     }
+    if (policy.mode === "workflow-only") {
+        if (tool === "bash") {
+            return planningBlock(unitType, policy.mode, `bash is not permitted; use the unit's dedicated GSD workflow tools for durable validation output`);
+        }
+        if (PLANNING_WRITE_TOOLS.has(tool)) {
+            return planningBlock(unitType, policy.mode, `cannot ${tool} "${pathOrCommand}" — direct artifact writes are disabled; call the required GSD workflow tool instead`);
+        }
+        return planningBlock(unitType, policy.mode, `tool "${tool}" is not on the workflow-only allowlist`);
+    }
     if (tool === "bash") {
         if (policy.mode === "verification") {
             if (BASH_VERIFICATION_RE.test(pathOrCommand) || BASH_READ_ONLY_RE.test(pathOrCommand))

package/dist/resources/extensions/gsd/closeout-consistency-gate.js

@@ -1,10 +1,14 @@
 // Project/App: gsd-pi
 // File Purpose: Shared DB-backed guard for milestone closeout finalization.
-import { dirname } from "node:path";
-import { getLatestAssessmentByScope, getMilestone, getMilestoneSlices, getPendingGates, getSliceTasks, isDbAvailable, } from "./gsd-db.js";
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getLatestAssessmentByScope, getMilestone, getMilestoneSlices, getPendingGates, getSliceTasks, insertAssessment, isDbAvailable, transaction, } from "./gsd-db.js";
 import { getWorkflowDatabasePath, refreshWorkflowDatabaseFromDisk, } from "./db-workspace.js";
-import { isClosedStatus } from "./status-guards.js";
+import { isClosedStatus, isDeferredStatus } from "./status-guards.js";
 import { closeQualityGatesFromEvidence } from "./quality-gate-closure.js";
+import { insertMilestoneValidationGates } from "./milestone-validation-gates.js";
+import { relMilestoneFile, resolveSliceFile } from "./paths.js";
+import { invalidateAllCaches } from "./cache.js";
 export const CLOSEOUT_CONSISTENCY_BLOCKED_REASON = "closeout-consistency-blocked";
 function blocked(reason, message) {
     return {
@@ -23,6 +27,80 @@ function artifactBasePathFromDb() {
         return undefined;
     return dirname(dirname(dbPath));
 }
+function allSlicesHaveCloseoutSummaryEvidence(milestoneId, artifactBasePath) {
+    const slices = getMilestoneSlices(milestoneId);
+    if (slices.length === 0)
+        return false;
+    return slices.every((slice) => {
+        if (!isClosedStatus(slice.status))
+            return false;
+        for (const task of getSliceTasks(milestoneId, slice.id)) {
+            if (!isClosedStatus(task.status))
+                return false;
+        }
+        const summaryPath = resolveSliceFile(artifactBasePath, milestoneId, slice.id, "SUMMARY");
+        return Boolean(summaryPath && existsSync(summaryPath));
+    });
+}
+function renderCloseoutPassThroughValidation(milestoneId) {
+    return [
+        "---",
+        "verdict: pass",
+        "skip_validation: true",
+        "skip_validation_reason: closeout-recovery",
+        "remediation_round: 0",
+        "---",
+        "",
+        "# Milestone Validation (skipped)",
+        "",
+        `Milestone validation was recorded during closeout for ${milestoneId} because all slices already had SUMMARY evidence and no milestone-validation assessment was present.`,
+        "",
+    ].join("\n");
+}
+function recordCloseoutPassThroughValidationIfReady(milestoneId, artifactBasePath) {
+    const basePath = artifactBasePath ?? artifactBasePathFromDb();
+    if (!basePath)
+        return false;
+    const existing = getLatestAssessmentByScope(milestoneId, "milestone-validation");
+    if (existing?.status === "pass")
+        return true;
+    if (existing)
+        return false;
+    if (!allSlicesHaveCloseoutSummaryEvidence(milestoneId, basePath))
+        return false;
+    const validationPath = join(basePath, relMilestoneFile(basePath, milestoneId, "VALIDATION"));
+    const content = renderCloseoutPassThroughValidation(milestoneId);
+    mkdirSync(dirname(validationPath), { recursive: true });
+    writeFileSync(validationPath, content, "utf-8");
+    try {
+        transaction(() => {
+            insertAssessment({
+                path: validationPath,
+                milestoneId,
+                sliceId: null,
+                taskId: null,
+                status: "pass",
+                scope: "milestone-validation",
+                fullContent: content,
+            });
+            const gateSliceId = getMilestoneSlices(milestoneId)[0]?.id;
+            if (gateSliceId) {
+                insertMilestoneValidationGates(milestoneId, gateSliceId, "pass", new Date().toISOString());
+            }
+        });
+    }
+    catch (err) {
+        try {
+            unlinkSync(validationPath);
+        }
+        catch {
+            // best effort cleanup
+        }
+        throw err;
+    }
+    invalidateAllCaches();
+    return true;
+}
 export function checkCloseoutConsistencyGate(milestoneId, options = {}) {
     if (!isDbAvailable()) {
         return blocked("db-unavailable", `Closeout consistency blocked for ${milestoneId}: canonical DB is unavailable.`);
@@ -37,12 +115,22 @@ export function checkCloseoutConsistencyGate(milestoneId, options = {}) {
     if (!isClosedStatus(milestone.status) && !options.allowOpenMilestone) {
         return blocked("milestone-open", `Closeout consistency blocked for ${milestoneId}: canonical DB milestone status is "${milestone.status}".`);
     }
-    const validation = milestone.status === "skipped"
+    let validation = milestone.status === "skipped"
         ? null
         : getLatestAssessmentByScope(milestoneId, "milestone-validation");
+    if (milestone.status !== "skipped" &&
+        validation?.status !== "pass" &&
+        options.allowPassThroughValidation &&
+        recordCloseoutPassThroughValidationIfReady(milestoneId, options.artifactBasePath ?? artifactBasePathFromDb())) {
+        validation = getLatestAssessmentByScope(milestoneId, "milestone-validation");
+    }
     if (milestone.status !== "skipped") {
         if (validation?.status !== "pass") {
-            return blocked("validation-not-pass", `Closeout consistency blocked for ${milestoneId}: latest milestone validation is "${validation?.status ?? "absent"}".`);
+            const validationStatus = validation?.status ?? "absent";
+            const recovery = validationStatus === "absent"
+                ? ` Run \`/gsd validate-milestone ${milestoneId}\` to create the validation, or set \`phases.skip_milestone_validation: true\` in .gsd/PREFERENCES.md to skip it.`
+                : "";
+            return blocked("validation-not-pass", `Closeout consistency blocked for ${milestoneId}: latest milestone validation is "${validationStatus}".${recovery}`);
         }
     }
     const slices = getMilestoneSlices(milestoneId);
@@ -56,6 +144,8 @@ export function checkCloseoutConsistencyGate(milestoneId, options = {}) {
         });
     }
     for (const slice of slices) {
+        if (isDeferredStatus(slice.status))
+            continue;
         if (!isClosedStatus(slice.status)) {
             return blocked("slice-open", `Closeout consistency blocked for ${milestoneId}: slice ${slice.id} status is "${slice.status}".`);
         }

package/dist/resources/extensions/gsd/codebase-generator.js

@@ -9,9 +9,11 @@
  */
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { join, dirname, extname } from "node:path";
+import { join, dirname, extname, relative, sep } from "node:path";
 import { execSync } from "node:child_process";
 import { gsdRoot } from "./paths.js";
+import { createRepositoryRegistryFromPreferences, } from "./repository-registry.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
 // ─── Defaults ────────────────────────────────────────────────────────────────
 const DEFAULT_EXCLUDES = [
     // ── AI / tooling meta ──
@@ -144,6 +146,84 @@ function enumerateFiles(basePath, excludes, maxFiles) {
     const truncated = filtered.length > maxFiles;
     return { files: truncated ? filtered.slice(0, maxFiles) : filtered, truncated };
 }
+/**
+ * Build a workspace-aware registry for parent mode, or null when the project is
+ * single-repo (no declared child repositories). Returns null so the caller falls
+ * back to the legacy single-root enumeration and produces byte-identical output.
+ */
+function loadWorkspaceRegistry(basePath) {
+    const preferences = loadEffectiveGSDPreferences(basePath)?.preferences;
+    const workspace = preferences?.workspace;
+    const mode = workspace?.mode ?? "project";
+    // Parent mode is only meaningful with at least one declared child repo; the
+    // implicit "project" repo is always present, so require a declared non-project id.
+    const hasDeclaredChildRepo = workspace?.repositories
+        ? Object.keys(workspace.repositories).some((id) => id !== "project")
+        : false;
+    if (mode !== "parent" || !hasDeclaredChildRepo) {
+        return null;
+    }
+    return createRepositoryRegistryFromPreferences(basePath, preferences);
+}
+/** Stable key fragment for workspace-aware enumeration inputs (mode + declared repos). */
+function workspaceEnumerationSignature(basePath) {
+    const registry = loadWorkspaceRegistry(basePath);
+    if (!registry)
+        return "single-root";
+    return JSON.stringify({
+        mode: registry.mode,
+        repositories: registry.repositories
+            .map((repo) => ({ id: repo.id, root: repo.root }))
+            .sort((a, b) => a.id.localeCompare(b.id)),
+    });
+}
+/**
+ * Enumerate tracked files across every declared repository in a parent workspace.
+ * Child-repo paths are rewritten to be workspace-relative (e.g. `frontend/src/x`)
+ * and tagged with their declaring repo id so the map can render repo-labelled
+ * sections. The maxFiles cap is applied across the union of all repositories.
+ */
+function enumerateWorkspaceFiles(registry, excludes, maxFiles) {
+    const perRepo = [];
+    const seen = new Set();
+    let totalEligible = 0;
+    for (const repo of registry.repositories) {
+        const rawFiles = lsFiles(repo.root);
+        const repoPrefix = relative(registry.projectRoot, repo.root).split(sep).join("/");
+        const repoEntries = [];
+        for (const file of rawFiles) {
+            // Rewrite before exclusion so workspace-relative patterns (e.g. frontend/…) apply.
+            const workspacePath = repoPrefix ? `${repoPrefix}/${file}` : file;
+            if (shouldExclude(workspacePath, excludes))
+                continue;
+            if (seen.has(workspacePath))
+                continue;
+            seen.add(workspacePath);
+            totalEligible++;
+            repoEntries.push({ workspacePath, repoId: repo.id });
+        }
+        perRepo.push(repoEntries);
+    }
+    const files = [];
+    const repos = [];
+    const indices = new Array(perRepo.length).fill(0);
+    while (files.length < maxFiles) {
+        let progressed = false;
+        for (let i = 0; i < perRepo.length; i++) {
+            if (indices[i] < perRepo[i].length) {
+                const entry = perRepo[i][indices[i]++];
+                files.push(entry.workspacePath);
+                repos.push(entry.repoId);
+                progressed = true;
+                if (files.length >= maxFiles)
+                    break;
+            }
+        }
+        if (!progressed)
+            break;
+    }
+    return { files, repos, truncated: totalEligible > files.length };
+}
 function resolveGeneratorOptions(options) {
     const excludes = [...DEFAULT_EXCLUDES, ...(options?.excludePatterns ?? [])];
     const maxFiles = options?.maxFiles ?? DEFAULT_MAX_FILES;
@@ -159,38 +239,69 @@ function resolveGeneratorOptions(options) {
         }),
     };
 }
-function computeCodebaseFingerprint(files, resolved, truncated) {
+function computeCodebaseFingerprint(files, resolved, truncated, repos) {
     return createHash("sha1")
         .update(JSON.stringify({
         files,
+        ...(repos ? { repos } : {}),
         truncated,
         optionSignature: resolved.optionSignature,
     }))
         .digest("hex");
 }
 // ─── Grouping ────────────────────────────────────────────────────────────────
-function groupByDirectory(files, descriptions, collapseThreshold) {
+function groupByDirectory(files, descriptions, collapseThreshold, repos) {
     const dirMap = new Map();
-    for (const file of files) {
+    for (let i = 0; i < files.length; i++) {
+        const file = files[i];
         const dir = dirname(file);
-        const dirKey = dir === "." ? "" : dir;
-        if (!dirMap.has(dirKey)) {
-            dirMap.set(dirKey, []);
+        const dirPath = dir === "." ? "" : dir;
+        const repoId = repos?.[i];
+        const groupKey = repoId !== undefined ? `${repoId}\0${dirPath}` : dirPath;
+        if (!dirMap.has(groupKey)) {
+            dirMap.set(groupKey, []);
         }
-        dirMap.get(dirKey).push({
+        dirMap.get(groupKey).push({
             path: file,
             description: descriptions.get(file) ?? "",
+            repo: repoId,
         });
     }
     const groups = [];
-    const sortedDirs = [...dirMap.keys()].sort();
-    for (const dir of sortedDirs) {
-        const dirFiles = dirMap.get(dir);
+    const repoOrder = new Map();
+    if (repos) {
+        for (let i = 0; i < repos.length; i++) {
+            if (!repoOrder.has(repos[i])) {
+                repoOrder.set(repos[i], repoOrder.size);
+            }
+        }
+    }
+    const sortedDirs = [...dirMap.keys()].sort((a, b) => {
+        // Single-repo (project) mode must stay byte-identical to the pre-workspace
+        // output, which ordered directories with a bare `.sort()` (UTF-16 code-unit
+        // order, so uppercase sorts before lowercase). localeCompare would diverge
+        // for mixed-case names (e.g. "Zoo" before "apple" flips), so preserve
+        // code-unit ordering here; only the repo-partitioning key is added on top.
+        if (!repos)
+            return a < b ? -1 : a > b ? 1 : 0;
+        const repoA = dirMap.get(a)[0]?.repo ?? "";
+        const repoB = dirMap.get(b)[0]?.repo ?? "";
+        const orderA = repoOrder.get(repoA) ?? 0;
+        const orderB = repoOrder.get(repoB) ?? 0;
+        if (orderA !== orderB)
+            return orderA - orderB;
+        return a.localeCompare(b);
+    });
+    for (const groupKey of sortedDirs) {
+        const dirFiles = dirMap.get(groupKey);
         dirFiles.sort((a, b) => a.path.localeCompare(b.path));
+        const dirPath = repos ? groupKey.slice(groupKey.indexOf("\0") + 1) : groupKey;
         groups.push({
-            path: dir,
+            path: dirPath,
             files: dirFiles,
             collapsed: dirFiles.length > collapseThreshold,
+            // Each group is scoped to one repo in workspace-aware mode.
+            repo: dirFiles[0]?.repo,
         });
     }
     return groups;
@@ -207,7 +318,18 @@ function renderCodebaseMap(groups, totalFiles, truncated, metadata) {
         lines.push(`Note: Truncated to first ${totalFiles} files. Run with higher --max-files to include all.`);
     }
     lines.push("");
+    let emittedRepo;
     for (const group of groups) {
+        // In a workspace-aware map, partition directories under their declaring
+        // repository. `## [repo-id]` headings are used (not `###`) so they never
+        // collide with the per-directory `### <dir>/` headings or the
+        // `parseCodebaseMap` list-item regexes. Groups are sorted by declaring
+        // repo (enumeration order) then directory path so each repo is contiguous.
+        if (group.repo && group.repo !== emittedRepo) {
+            emittedRepo = group.repo;
+            lines.push(`## [${group.repo}]`);
+            lines.push("");
+        }
         const heading = group.path || "(root)";
         lines.push(`### ${heading}/`);
         if (group.collapsed) {
@@ -250,13 +372,15 @@ function renderCodebaseMap(groups, totalFiles, truncated, metadata) {
 function buildCodebaseMap(basePath, resolved, existingDescriptions, enumerated) {
     const listed = enumerated ?? enumerateFiles(basePath, resolved.excludes, resolved.maxFiles);
     const descriptions = existingDescriptions ?? new Map();
-    const groups = groupByDirectory(listed.files, descriptions, resolved.collapseThreshold);
+    const groups = groupByDirectory(listed.files, descriptions, resolved.collapseThreshold, listed.repos);
     const generatedAt = new Date().toISOString().split(".")[0] + "Z";
+    const repoIds = listed.repos ? Array.from(new Set(listed.repos)) : undefined;
     const metadata = {
         generatedAt,
-        fingerprint: computeCodebaseFingerprint(listed.files, resolved, listed.truncated),
+        fingerprint: computeCodebaseFingerprint(listed.files, resolved, listed.truncated, listed.repos),
         fileCount: listed.files.length,
         truncated: listed.truncated,
+        ...(repoIds ? { repositories: repoIds } : {}),
     };
     const content = renderCodebaseMap(groups, listed.files.length, listed.truncated, metadata);
     return {
@@ -273,9 +397,21 @@ function buildCodebaseMap(basePath, resolved, existingDescriptions, enumerated)
  * Generate a fresh CODEBASE.md from scratch.
  * Preserves existing descriptions if `existingDescriptions` is provided.
  */
+/**
+ * Resolve workspace-aware enumeration for parent mode, or undefined to fall
+ * back to the legacy single-root enumeration. Centralized so all three public
+ * entry points (generate/update/ensure) share one discovery path.
+ */
+function resolveWorkspaceEnumeration(basePath, resolved) {
+    const registry = loadWorkspaceRegistry(basePath);
+    if (!registry)
+        return undefined;
+    return enumerateWorkspaceFiles(registry, resolved.excludes, resolved.maxFiles);
+}
 export function generateCodebaseMap(basePath, options, existingDescriptions) {
     const resolved = resolveGeneratorOptions(options);
-    return buildCodebaseMap(basePath, resolved, existingDescriptions);
+    const enumerated = resolveWorkspaceEnumeration(basePath, resolved);
+    return buildCodebaseMap(basePath, resolved, existingDescriptions, enumerated);
 }
 /**
  * Incremental update: re-scan files, preserve existing descriptions,
@@ -293,7 +429,8 @@ export function updateCodebaseMap(basePath, options) {
     const existingFiles = new Set(existingDescriptions.keys());
     // Generate new map preserving descriptions — reuse the returned file list
     // to avoid a second enumeration (prevents race between content and stats).
-    const result = buildCodebaseMap(basePath, resolved, existingDescriptions);
+    const enumerated = resolveWorkspaceEnumeration(basePath, resolved);
+    const result = buildCodebaseMap(basePath, resolved, existingDescriptions, enumerated);
     const currentSet = new Set(result.files);
     // Count changes
     let added = 0;
@@ -326,23 +463,21 @@ function clearFreshnessCache(basePath) {
 }
 export function ensureCodebaseMapFresh(basePath, options, ensureOptions) {
     const resolved = resolveGeneratorOptions(options);
-    const cacheKey = `${basePath}::${resolved.optionSignature}`;
+    const cacheKey = `${basePath}::${resolved.optionSignature}::${workspaceEnumerationSignature(basePath)}`;
     const ttlMs = ensureOptions?.ttlMs ?? DEFAULT_REFRESH_TTL_MS;
     const force = ensureOptions?.force === true;
     const now = Date.now();
-    // Enumerate files and compute fingerprint before the TTL check so that
-    // file changes are always detected, even within the TTL window.
-    const existing = readCodebaseMap(basePath);
-    const listed = enumerateFiles(basePath, resolved.excludes, resolved.maxFiles);
-    const fingerprint = computeCodebaseFingerprint(listed.files, resolved, listed.truncated);
-    // TTL short-circuit: only bypass regeneration when the fingerprint matches,
-    // confirming that no tracked files changed since the last check.
+    // TTL short-circuit: avoid spawning git on the per-turn freshness path.
     if (!force && ttlMs > 0) {
         const cached = freshnessCache.get(cacheKey);
-        if (cached && now - cached.checkedAt < ttlMs && cached.result.fingerprint === fingerprint) {
+        if (cached && now - cached.checkedAt < ttlMs) {
             return cached.result;
         }
     }
+    const existing = readCodebaseMap(basePath);
+    const listed = resolveWorkspaceEnumeration(basePath, resolved)
+        ?? enumerateFiles(basePath, resolved.excludes, resolved.maxFiles);
+    const fingerprint = computeCodebaseFingerprint(listed.files, resolved, listed.truncated, listed.repos);
     const cacheAndReturn = (result) => {
         freshnessCache.set(cacheKey, { checkedAt: now, result });
         return result;