@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.955e4da0

package/dist/resources/extensions/gsd/milestone-planning-persistence.js

@@ -0,0 +1,156 @@
+// Project/App: gsd-pi
+// File Purpose: Persist planned milestone roadmaps and their DB-backed projections.
+import { clearParseCache } from "./files.js";
+import { isClosedStatus } from "./status-guards.js";
+import { transaction, getMilestone, getMilestoneSlices, getSlice, insertMilestone, insertSlice, upsertMilestonePlanning, upsertSlicePlanning, } from "./gsd-db.js";
+import { invalidateStateCache } from "./state.js";
+import { renderRoadmapFromDb } from "./markdown-renderer.js";
+import { renderAllProjections } from "./workflow-projections.js";
+import { writeManifest } from "./workflow-manifest.js";
+import { appendEvent } from "./workflow-events.js";
+import { logWarning } from "./workflow-logger.js";
+function validatePlanPromotion(params) {
+    const existingMilestone = getMilestone(params.milestoneId);
+    if (existingMilestone && isClosedStatus(existingMilestone.status)) {
+        return `cannot re-plan milestone ${params.milestoneId}: it is already complete`;
+    }
+    // Guard: refuse to re-plan a milestone that would drop completed slices (#2960).
+    // Allow re-planning when all completed slices are still present in the
+    // incoming plan — their status is preserved below (#2558). Block only when
+    // the new plan omits a completed slice, which could shadow completed work.
+    const existingSlices = getMilestoneSlices(params.milestoneId);
+    const completedSlices = existingSlices.filter(s => isClosedStatus(s.status));
+    if (completedSlices.length > 0) {
+        const incomingSliceIds = new Set(params.slices.map(s => s.sliceId));
+        const droppedCompleted = completedSlices.filter(s => !incomingSliceIds.has(s.id));
+        if (droppedCompleted.length > 0) {
+            return `cannot re-plan milestone ${params.milestoneId}: ${droppedCompleted.length} completed slice(s) would be dropped (${droppedCompleted.map(s => s.id).join(", ")}). Use gsd_reassess_roadmap to modify the roadmap.`;
+        }
+    }
+    // Validate depends_on: all dependencies must exist and be complete
+    if (params.dependsOn && params.dependsOn.length > 0) {
+        for (const depId of params.dependsOn) {
+            const dep = getMilestone(depId);
+            if (!dep) {
+                return `depends_on references unknown milestone: ${depId}`;
+            }
+            if (!isClosedStatus(dep.status)) {
+                return `depends_on milestone ${depId} is not yet complete (status: ${dep.status})`;
+            }
+        }
+    }
+    return null;
+}
+function writePlanRows(params) {
+    insertMilestone({
+        id: params.milestoneId,
+        title: params.title,
+        status: params.status ?? "active",
+        depends_on: params.dependsOn ?? [],
+    });
+    upsertMilestonePlanning(params.milestoneId, {
+        title: params.title,
+        status: params.status ?? "active",
+        depends_on: params.dependsOn ?? [],
+        vision: params.vision,
+        successCriteria: params.successCriteria,
+        keyRisks: params.keyRisks,
+        proofStrategy: params.proofStrategy,
+        verificationContract: params.verificationContract,
+        verificationIntegration: params.verificationIntegration,
+        verificationOperational: params.verificationOperational,
+        verificationUat: params.verificationUat,
+        definitionOfDone: params.definitionOfDone,
+        requirementCoverage: params.requirementCoverage,
+        boundaryMapMarkdown: params.boundaryMapMarkdown,
+    });
+    for (let i = 0; i < params.slices.length; i++) {
+        const slice = params.slices[i];
+        // Preserve completed/done status on re-plan (#2558).
+        // Without this, a re-plan after milestone transition would reset
+        // already-completed slices back to "pending".
+        const existing = getSlice(params.milestoneId, slice.sliceId);
+        const status = existing && (existing.status === "complete" || existing.status === "done")
+            ? existing.status
+            : "pending";
+        insertSlice({
+            id: slice.sliceId,
+            milestoneId: params.milestoneId,
+            title: slice.title,
+            status,
+            risk: slice.risk,
+            depends: slice.depends,
+            demo: slice.demo,
+            sequence: i + 1, // Preserve agent-ordered sequence (#3356)
+            // ADR-011: pass undefined through so ON CONFLICT preserves existing values
+            // when the caller omitted the fields on a re-plan.
+            isSketch: slice.isSketch,
+            sketchScope: slice.sketchScope,
+        });
+        upsertSlicePlanning(params.milestoneId, slice.sliceId, {
+            goal: slice.goal,
+            successCriteria: slice.successCriteria,
+            proofLevel: slice.proofLevel,
+            integrationClosure: slice.integrationClosure,
+            observabilityImpact: slice.observabilityImpact,
+        });
+    }
+}
+async function renderPlanArtifacts(basePath, params) {
+    try {
+        const renderResult = await renderRoadmapFromDb(basePath, params.milestoneId);
+        return renderResult.roadmapPath;
+    }
+    catch (renderErr) {
+        logWarning("tool", `plan_milestone — render failed (DB rows preserved for debugging): ${renderErr.message}`);
+        invalidateStateCache();
+        return { error: `render failed: ${renderErr.message}` };
+    }
+}
+async function runPostPlanHooks(basePath, params) {
+    try {
+        await renderAllProjections(basePath, params.milestoneId);
+        writeManifest(basePath);
+        appendEvent(basePath, {
+            cmd: "plan-milestone",
+            params: { milestoneId: params.milestoneId },
+            ts: new Date().toISOString(),
+            actor: "agent",
+            actor_name: params.actorName,
+            trigger_reason: params.triggerReason,
+        });
+    }
+    catch (hookErr) {
+        logWarning("tool", `plan-milestone post-mutation hook warning: ${hookErr.message}`);
+    }
+}
+export async function persistMilestonePlan(params, basePath) {
+    // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
+    // Guards must be inside the transaction so the state they check cannot
+    // change between the read and the write (#2723).
+    let guardError = null;
+    try {
+        transaction(() => {
+            guardError = validatePlanPromotion(params);
+            if (guardError)
+                return;
+            writePlanRows(params);
+        });
+    }
+    catch (err) {
+        return { error: `db write failed: ${err.message}` };
+    }
+    if (guardError) {
+        return { error: guardError };
+    }
+    const roadmapPath = await renderPlanArtifacts(basePath, params);
+    if (typeof roadmapPath !== "string")
+        return roadmapPath;
+    invalidateStateCache();
+    clearParseCache();
+    await runPostPlanHooks(basePath, params);
+    return {
+        milestoneId: params.milestoneId,
+        roadmapPath,
+    };
+}

package/dist/resources/extensions/gsd/milestone-readiness.js

@@ -0,0 +1,77 @@
+// Project/App: gsd-pi
+// File Purpose: Classify milestone readiness from DB status, slices, and artifacts.
+import { readFileSync } from "node:fs";
+import { getMilestone, getMilestoneSlices, isDbAvailable } from "./gsd-db.js";
+import { parseRoadmapSlices } from "./roadmap-slices.js";
+import { logWarning } from "./workflow-logger.js";
+export function classifyMilestoneReadiness(input) {
+    const hasContext = input.hasContext === true;
+    const hasDraftContext = !hasContext && input.hasDraftContext === true;
+    const hasSummary = input.hasSummary === true;
+    const sliceCount = input.sliceCount ?? 0;
+    const hasExecutablePlan = sliceCount > 0;
+    const status = input.status ?? null;
+    if (status === "complete" || hasSummary) {
+        return { kind: "terminal", hasContext, hasDraftContext, hasExecutablePlan };
+    }
+    if (status === "queued" && !hasContext && sliceCount === 0) {
+        return { kind: "queued-shell", hasContext, hasDraftContext, hasExecutablePlan };
+    }
+    if ((status === "needs-discussion" && !hasContext) || hasDraftContext) {
+        return { kind: "needs-discussion", hasContext, hasDraftContext, hasExecutablePlan };
+    }
+    if (hasExecutablePlan) {
+        return { kind: "executable-plan", hasContext, hasDraftContext, hasExecutablePlan };
+    }
+    return { kind: "planning-pending", hasContext, hasDraftContext, hasExecutablePlan };
+}
+export function readinessNeedsDiscussion(readiness) {
+    return readiness.kind === "needs-discussion" ||
+        (readiness.kind === "queued-shell" && readiness.hasDraftContext);
+}
+export function describeMilestoneReadinessPhase(phase) {
+    switch (phase) {
+        case "needs-discussion":
+            return {
+                label: "Discuss milestone draft",
+                description: "Milestone has a draft context — needs discussion before planning.",
+            };
+        case "pre-planning":
+            return {
+                label: "Research & plan milestone",
+                description: "Scout the landscape and create the roadmap.",
+            };
+        default:
+            return null;
+    }
+}
+function executablePlanSliceCount(milestoneId, roadmapFile) {
+    if (isDbAvailable()) {
+        return getMilestoneSlices(milestoneId).length;
+    }
+    if (!roadmapFile)
+        return 0;
+    try {
+        return parseRoadmapSlices(readFileSync(roadmapFile, "utf-8")).length;
+    }
+    catch (e) {
+        logWarning("guided", `failed to parse roadmap slices for ${milestoneId}: ${e.message}`);
+        return 0;
+    }
+}
+export function assessMilestoneHandoffReadiness(input) {
+    const milestone = isDbAvailable() ? getMilestone(input.milestoneId) : null;
+    return classifyMilestoneReadiness({
+        status: milestone?.status,
+        hasContext: input.contextFile != null,
+        sliceCount: executablePlanSliceCount(input.milestoneId, input.roadmapFile),
+    });
+}
+export function formatAcceptedDiscussHandoffMessage(milestoneId, readiness) {
+    if (readiness.hasExecutablePlan)
+        return `Milestone ${milestoneId} ready.`;
+    if (readiness.hasContext) {
+        return `Milestone ${milestoneId} context captured. Continuing the planning pipeline.`;
+    }
+    return `Milestone ${milestoneId} planning artifacts captured. Continuing the planning pipeline.`;
+}

package/dist/resources/extensions/gsd/milestone-settlement.js

@@ -0,0 +1,50 @@
+// Project/App: gsd-pi
+// File Purpose: Milestone closeout settlement state across DB proof, artifacts, merge, and cleanup.
+import { isInAutoWorktree } from "./auto-worktree.js";
+import { formatCloseoutProofBlock, proveMilestoneCloseout, } from "./milestone-closeout-proof.js";
+import { resolveCloseoutArtifactProjection } from "./artifact-projection.js";
+function isActiveUnmergedWorktree(input) {
+    if (!input.milestoneId || input.milestoneMerged)
+        return false;
+    return isInAutoWorktree(input.basePath);
+}
+export function evaluateAllCompleteSettlement(input) {
+    if (input.statePhase !== "complete") {
+        return { ok: true, reason: "not-applicable" };
+    }
+    if (!isActiveUnmergedWorktree(input)) {
+        return { ok: true, reason: "settled" };
+    }
+    const milestoneId = input.milestoneId;
+    if (!milestoneId) {
+        return { ok: true, reason: "settled" };
+    }
+    const projection = resolveCloseoutArtifactProjection({
+        milestoneId,
+        basePath: input.basePath,
+        originalBasePath: input.originalBasePath,
+    });
+    const proof = proveMilestoneCloseout(milestoneId, {
+        refreshFromDisk: true,
+        summaryArtifactBasePath: projection.summaryArtifactBasePath,
+    });
+    if (!proof.ok) {
+        return {
+            ok: false,
+            reason: "closeout-blocked",
+            action: "pause",
+            message: `${formatCloseoutProofBlock(proof)} The milestone branch has not been merged to main.`,
+            nextAction: `Resolve closeout blockers, then retry \`/gsd dispatch complete-milestone ${milestoneId}\`.`,
+            milestoneId,
+        };
+    }
+    return {
+        ok: false,
+        reason: "merge-pending",
+        action: "pause",
+        message: `Milestone ${milestoneId} is complete, but its worktree branch has not been merged to main. ` +
+            `Retry with \`/gsd dispatch complete-milestone ${milestoneId}\` or merge manually.`,
+        nextAction: `Retry \`/gsd dispatch complete-milestone ${milestoneId}\` or merge manually.`,
+        milestoneId,
+    };
+}

package/dist/resources/extensions/gsd/milestone-validation-evidence.js

@@ -0,0 +1,73 @@
+// Project/App: gsd-pi
+// File Purpose: Forwarded validation evidence rules for milestone validation.
+import { getArtifact, getMilestone, getMilestoneSlices } from "./gsd-db.js";
+import { loadFile } from "./files.js";
+import { resolveSliceFile } from "./paths.js";
+import { compactTextParts, hasBrowserEvidenceText, hasBrowserRequiredText, } from "./browser-evidence.js";
+export function hasRuntimeExecutableUatEvidenceText(text) {
+    if (!/\buatType:\s*runtime-executable\b/i.test(text))
+        return false;
+    if (!/\bverdict:\s*PASS\b/i.test(text))
+        return false;
+    return /^\|\s*[^|\n]+\s*\|\s*runtime\s*\|\s*PASS\s*\|[^|\n]*\bgsd_uat_exec\b/mi.test(text);
+}
+export async function browserEvidenceGateRequiresAttention(params, basePath) {
+    if (params.verdict !== "pass")
+        return false;
+    const milestone = getMilestone(params.milestoneId);
+    const slices = getMilestoneSlices(params.milestoneId);
+    const requirementText = compactTextParts([
+        milestone?.vision,
+        milestone?.success_criteria,
+        milestone?.verification_uat,
+        params.successCriteriaChecklist,
+        params.verificationClasses,
+        ...slices.flatMap((slice) => [
+            slice.demo,
+            slice.goal,
+            slice.success_criteria,
+        ]),
+    ]);
+    if (!hasBrowserRequiredText(requirementText))
+        return false;
+    const sliceEvidencePairs = [];
+    for (const slice of slices) {
+        const chunks = [];
+        const artifactPath = `milestones/${params.milestoneId}/slices/${slice.id}/${slice.id}-ASSESSMENT.md`;
+        const artifact = getArtifact(artifactPath);
+        if (artifact?.full_content)
+            chunks.push(artifact.full_content);
+        const assessmentPath = resolveSliceFile(basePath, params.milestoneId, slice.id, "ASSESSMENT");
+        const assessmentContent = assessmentPath ? await loadFile(assessmentPath) : null;
+        if (assessmentContent)
+            chunks.push(assessmentContent);
+        sliceEvidencePairs.push({
+            sliceRequirementText: compactTextParts([slice.demo, slice.goal, slice.success_criteria]),
+            evidenceText: chunks.join("\n\n"),
+        });
+    }
+    const browserRequiringSlices = sliceEvidencePairs.filter((slice) => hasBrowserRequiredText(slice.sliceRequirementText));
+    const runtimeBypasses = browserRequiringSlices.length > 0
+        ? browserRequiringSlices.every((slice) => hasRuntimeExecutableUatEvidenceText(slice.evidenceText))
+        : sliceEvidencePairs.some((slice) => hasRuntimeExecutableUatEvidenceText(slice.evidenceText));
+    if (runtimeBypasses)
+        return false;
+    const persistedEvidence = sliceEvidencePairs.map((slice) => slice.evidenceText).join("\n\n");
+    const validationEvidence = compactTextParts([
+        params.successCriteriaChecklist,
+        params.verificationClasses,
+        params.verdictRationale,
+        params.remediationPlan,
+    ]);
+    return !hasBrowserEvidenceText(`${persistedEvidence}\n\n${validationEvidence}`);
+}
+export function applyBrowserEvidenceGate(params) {
+    const note = "Browser evidence gate: Browser-observable acceptance criteria were detected, but no persisted ASSESSMENT or validation evidence recorded browser actions with assertions. Downgraded from pass to needs-attention.";
+    return {
+        ...params,
+        verdict: "needs-attention",
+        verdictRationale: params.verdictRationale.trim()
+            ? `${params.verdictRationale.trim()}\n\n${note}`
+            : note,
+    };
+}

package/dist/resources/extensions/gsd/milestone-validation-verdict.js

@@ -0,0 +1,57 @@
+// Project/App: gsd-pi
+// File Purpose: Resolve the authoritative milestone validation verdict across DB and disk projections.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { resolveExpectedArtifactPath } from "./auto-artifact-paths.js";
+import { loadFile } from "./files.js";
+import { getLatestAssessmentByScope, isDbAvailable } from "./gsd-db.js";
+import { gsdProjectionRoot } from "./paths.js";
+import { extractVerdict, isValidMilestoneVerdict, } from "./verdict-parser.js";
+import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
+import { resolveWorktreeProjectRoot } from "./worktree-root.js";
+function verdictFromContent(content) {
+    if (!content)
+        return undefined;
+    const verdict = extractVerdict(content);
+    return verdict && isValidMilestoneVerdict(verdict) ? verdict : undefined;
+}
+function verdictFromDb(milestoneId) {
+    if (!isDbAvailable())
+        return undefined;
+    const assessment = getLatestAssessmentByScope(milestoneId, "milestone-validation");
+    const status = typeof assessment?.status === "string" ? assessment.status : undefined;
+    return status && isValidMilestoneVerdict(status) ? status : undefined;
+}
+async function verdictFromValidationPath(path) {
+    if (!path || !existsSync(path))
+        return undefined;
+    return verdictFromContent(await loadFile(path));
+}
+/**
+ * Resolve the milestone validation verdict using the same authority order as
+ * DB-backed state derivation, with filesystem fallbacks that mirror
+ * `resolveExpectedArtifactPath` (canonical worktree projection, then project
+ * root). Manual `/gsd verdict` overrides persist to the DB first; a stale
+ * worktree-local VALIDATION.md must not re-block auto-mode after the override.
+ */
+export async function resolveMilestoneValidationVerdict(basePath, milestoneId) {
+    const dbVerdict = verdictFromDb(milestoneId);
+    if (dbVerdict)
+        return dbVerdict;
+    const canonicalBase = resolveCanonicalMilestoneRoot(basePath, milestoneId);
+    const canonicalPath = resolveExpectedArtifactPath("validate-milestone", milestoneId, canonicalBase);
+    const canonicalVerdict = await verdictFromValidationPath(canonicalPath);
+    if (canonicalVerdict)
+        return canonicalVerdict;
+    const projectRoot = resolveWorktreeProjectRoot(basePath);
+    if (projectRoot !== canonicalBase) {
+        const projectPath = resolveExpectedArtifactPath("validate-milestone", milestoneId, projectRoot);
+        const projectVerdict = await verdictFromValidationPath(projectPath);
+        if (projectVerdict)
+            return projectVerdict;
+    }
+    // Last resort: direct canonical projection path even when resolveDir helpers
+    // have not materialized the milestone directory yet.
+    const directPath = join(gsdProjectionRoot(canonicalBase), "milestones", milestoneId, `${milestoneId}-VALIDATION.md`);
+    return verdictFromValidationPath(directPath);
+}

package/dist/resources/extensions/gsd/model-cost-table.js

@@ -13,6 +13,7 @@ export const BUNDLED_COST_TABLE = [
     { id: "claude-opus-4-6", inputPer1k: 0.005, outputPer1k: 0.025, updatedAt: "2026-04-16" },
     { id: "claude-opus-4-7", inputPer1k: 0.005, outputPer1k: 0.025, updatedAt: "2026-04-16" },
     { id: "claude-opus-4-8", inputPer1k: 0.005, outputPer1k: 0.025, updatedAt: "2026-05-28" },
+    { id: "claude-fable-5", inputPer1k: 0.010, outputPer1k: 0.050, updatedAt: "2026-06-09" },
     { id: "claude-sonnet-4-6", inputPer1k: 0.003, outputPer1k: 0.015, updatedAt: "2025-03-15" },
     { id: "claude-haiku-4-5", inputPer1k: 0.0008, outputPer1k: 0.004, updatedAt: "2025-03-15" },
     { id: "claude-sonnet-4-5-20250514", inputPer1k: 0.003, outputPer1k: 0.015, updatedAt: "2025-03-15" },

package/dist/resources/extensions/gsd/model-router.js

@@ -35,6 +35,7 @@ export const MODEL_CAPABILITY_TIER = {
     "claude-opus-4-6": "heavy",
     "claude-opus-4-7": "heavy",
     "claude-opus-4-8": "heavy",
+    "claude-fable-5": "heavy",
     "claude-3-opus-latest": "heavy",
     "gpt-4-turbo": "heavy",
     "gpt-5": "heavy",
@@ -61,6 +62,7 @@ const MODEL_COST_PER_1K_INPUT = {
     "claude-opus-4-6": 0.005,
     "claude-opus-4-7": 0.005,
     "claude-opus-4-8": 0.005,
+    "claude-fable-5": 0.010,
     "gpt-4o-mini": 0.00015,
     "gpt-4o": 0.0025,
     "gpt-4.1": 0.002,
@@ -94,6 +96,7 @@ export const MODEL_CAPABILITY_PROFILES = {
     "claude-opus-4-6": { coding: 95, debugging: 90, research: 85, reasoning: 95, speed: 30, longContext: 80, instruction: 90 },
     "claude-opus-4-7": { coding: 95, debugging: 90, research: 85, reasoning: 95, speed: 30, longContext: 80, instruction: 90 },
     "claude-opus-4-8": { coding: 97, debugging: 92, research: 87, reasoning: 97, speed: 30, longContext: 85, instruction: 92 },
+    "claude-fable-5": { coding: 97, debugging: 92, research: 87, reasoning: 97, speed: 30, longContext: 85, instruction: 92 },
     "claude-sonnet-4-6": { coding: 85, debugging: 80, research: 75, reasoning: 80, speed: 60, longContext: 75, instruction: 85 },
     "claude-sonnet-4-5-20250514": { coding: 85, debugging: 80, research: 75, reasoning: 80, speed: 60, longContext: 75, instruction: 85 },
     "claude-3-5-sonnet-latest": { coding: 82, debugging: 78, research: 72, reasoning: 78, speed: 62, longContext: 70, instruction: 82 },

package/dist/resources/extensions/gsd/parallel-eligibility.js

@@ -4,11 +4,10 @@
  * Analyzes which milestones can safely run in parallel by checking
  * dependency satisfaction and file overlap across slice plans.
  */
-import { existsSync } from "node:fs";
 import { deriveState } from "./state.js";
-import { resolveGsdPathContract } from "./paths.js";
 import { findMilestoneIds } from "./guided-flow.js";
-import { isDbAvailable, getMilestoneSlices, getSliceTasks, openDatabase } from "./gsd-db.js";
+import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
+import { openExistingWorkflowDatabase } from "./db-workspace.js";
 // ─── File Collection ─────────────────────────────────────────────────────────
 /**
  * Collect all `filesLikelyTouched` across every slice plan in a milestone.
@@ -64,9 +63,7 @@ function detectFileOverlaps(fileSets) {
  */
 export async function analyzeParallelEligibility(basePath) {
     if (!isDbAvailable()) {
-        const { projectDb } = resolveGsdPathContract(basePath);
-        if (existsSync(projectDb))
-            openDatabase(projectDb);
+        openExistingWorkflowDatabase(basePath);
     }
     const milestoneIds = findMilestoneIds(basePath);
     const state = await deriveState(basePath);

package/dist/resources/extensions/gsd/parallel-merge.js

@@ -5,9 +5,9 @@
  * with safety checks for parallel execution context.
  */
 import { existsSync, readdirSync } from "node:fs";
-import { join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { resolveGsdPathContract } from "./paths.js";
+import { worktreePathFor, worktreesDirs } from "./worktree-placement.js";
 import { getAutoWorktreePath } from "./auto-worktree.js";
 import { buildWorktreeLifecycleDeps } from "./auto.js";
 import { mergeMilestoneStandalone, } from "./worktree-lifecycle.js";
@@ -22,7 +22,7 @@ import { logWarning } from "./workflow-logger.js";
  * Returns true when milestones.status = 'complete' in project gsd.db.
  */
 export function isMilestoneCompleteInProjectDb(basePath, mid) {
-    const workRoot = join(basePath, ".gsd", "worktrees", mid);
+    const workRoot = worktreePathFor(basePath, mid);
     const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
     if (!existsSync(dbPath))
         return false;
@@ -41,16 +41,19 @@ export function isMilestoneCompleteInProjectDb(basePath, mid) {
  */
 function discoverDbCompletedMilestones(basePath) {
     const completed = new Set();
-    const worktreeDir = join(basePath, ".gsd", "worktrees");
-    try {
-        for (const entry of readdirSync(worktreeDir)) {
-            if (entry.startsWith("M") && isMilestoneCompleteInProjectDb(basePath, entry)) {
-                completed.add(entry);
+    for (const worktreeDir of worktreesDirs(basePath)) {
+        if (!existsSync(worktreeDir))
+            continue;
+        try {
+            for (const entry of readdirSync(worktreeDir)) {
+                if (entry.startsWith("M") && isMilestoneCompleteInProjectDb(basePath, entry)) {
+                    completed.add(entry);
+                }
             }
         }
-    }
-    catch (e) {
-        logWarning("parallel", `readdirSync for completed set failed: ${e.message}`);
+        catch (e) {
+            logWarning("parallel", `readdirSync for completed set failed: ${e.message}`);
+        }
     }
     return completed;
 }
@@ -88,7 +91,7 @@ export function determineMergeOrder(workers, order = "sequential", basePath) {
                 title: mid,
                 pid: 0,
                 process: null,
-                worktreePath: basePath ? join(basePath, ".gsd", "worktrees", mid) : "",
+                worktreePath: basePath ? worktreePathFor(basePath, mid) : "",
                 startedAt: 0,
                 state: "stopped",
                 cost: 0,

package/dist/resources/extensions/gsd/parallel-monitor-overlay.js

@@ -7,6 +7,7 @@ import { matchesKey, Key } from "@gsd/pi-tui";
 import { formatDuration } from "../shared/mod.js";
 import { formattedShortcutPair } from "./shortcut-defs.js";
 import { resolveGsdPathContract } from "./paths.js";
+import { worktreePathFor, worktreesDirs } from "./worktree-placement.js";
 import { renderBar, renderDialogFrame, renderKeyHints, renderProgressBar, safeLine, statusGlyph, } from "./tui/render-kit.js";
 // ─── Data Helpers ─────────────────────────────────────────────────────────
 function readJsonSafe(filePath) {
@@ -42,7 +43,6 @@ function tailRead(filePath, maxBytes) {
 }
 function discoverWorkers(basePath) {
     const parallelDir = join(basePath, ".gsd", "parallel");
-    const worktreeDir = join(basePath, ".gsd", "worktrees");
     const mids = new Set();
     if (existsSync(parallelDir)) {
         try {
@@ -56,7 +56,9 @@ function discoverWorkers(basePath) {
         }
         catch { /* skip */ }
     }
-    if (existsSync(worktreeDir)) {
+    for (const worktreeDir of worktreesDirs(basePath)) {
+        if (!existsSync(worktreeDir))
+            continue;
         try {
             for (const d of readdirSync(worktreeDir)) {
                 if (d.startsWith("M") && existsSync(join(worktreeDir, d, ".gsd", "auto.lock"))) {
@@ -69,7 +71,7 @@ function discoverWorkers(basePath) {
     return [...mids].sort();
 }
 function querySliceProgress(basePath, mid) {
-    const workRoot = join(basePath, ".gsd", "worktrees", mid);
+    const workRoot = worktreePathFor(basePath, mid);
     const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
     if (!existsSync(dbPath))
         return [];
@@ -115,7 +117,7 @@ function extractCostFromNdjson(basePath, mid) {
     }
 }
 function queryRecentCompletions(basePath, mid) {
-    const workRoot = join(basePath, ".gsd", "worktrees", mid);
+    const workRoot = worktreePathFor(basePath, mid);
     const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
     if (!existsSync(dbPath))
         return [];
@@ -140,7 +142,7 @@ function collectWorkerData(basePath) {
     const workers = [];
     for (const mid of mids) {
         const status = readJsonSafe(join(parallelDir, `${mid}.status.json`));
-        const lock = readJsonSafe(join(basePath, ".gsd", "worktrees", mid, ".gsd", "auto.lock"));
+        const lock = readJsonSafe(join(worktreePathFor(basePath, mid), ".gsd", "auto.lock"));
         const slices = querySliceProgress(basePath, mid);
         const pid = lock?.pid || status?.pid || 0;
         const alive = pid ? isPidAlive(pid) : false;

package/dist/resources/extensions/gsd/parallel-orchestrator.js

@@ -12,9 +12,10 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { gsdRoot } from "./paths.js";
 import { createWorktree, worktreePath } from "./worktree-manager.js";
-import { autoWorktreeBranch, fastForwardReusedMilestoneBranchIfSafe, runWorktreePostCreateHook, syncGsdStateToWorktree } from "./auto-worktree.js";
+import { autoWorktreeBranch, fastForwardReusedMilestoneBranchIfSafe, runWorktreePostCreateHook, syncGsdStateToWorktreeByScope } from "./auto-worktree.js";
 import { nativeBranchExists } from "./native-git-bridge.js";
 import { readIntegrationBranch } from "./git-service.js";
+import { createWorkspace, scopeMilestone } from "./workspace.js";
 import { resolveParallelConfig } from "./preferences.js";
 import { writeSessionStatus, readAllSessionStatuses, readSessionStatus, removeSessionStatus, sendSignal, cleanupStaleSessions, } from "./session-status-io.js";
 import { analyzeParallelEligibility, } from "./parallel-eligibility.js";
@@ -448,7 +449,7 @@ export function _createMilestoneWorktree(basePath, milestoneId) {
     // Copy .gsd/ planning artifacts (milestones, CONTEXT, ROADMAP, etc.) from the
     // project root into the worktree. Without this, workers for newly-planned
     // milestones can't find their roadmap and exit immediately (#2184 Bug 4).
-    syncGsdStateToWorktree(basePath, info.path);
+    syncGsdStateToWorktreeByScope(scopeMilestone(createWorkspace(basePath), milestoneId), scopeMilestone(createWorkspace(info.path), milestoneId));
     return info.path;
 }
 // ─── Worker Spawning ───────────────────────────────────────────────────

package/dist/resources/extensions/gsd/paths.js

@@ -16,7 +16,7 @@ import { spawnSync } from "node:child_process";
 import { nativeScanGsdTree } from "./native-parser-bridge.js";
 import { DIR_CACHE_MAX } from "./constants.js";
 import { gsdHome } from "./gsd-home.js";
-import { isGsdWorktreePath, resolveExternalStateProjectGsdFromWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
+import { findWorktreeSegment, isGsdWorktreePath, resolveExternalStateProjectGsdFromWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
 // ─── Directory Listing Cache ──────────────────────────────────────────────────
 const dirEntryCache = new Map();
 const dirListCache = new Map();
@@ -422,31 +422,17 @@ function assertNotGlobalGsdHome(basePath, result) {
  * When gsdRoot() is called with such a path, we must NOT walk up to the
  * project root's .gsd — each worktree manages its own .gsd state (#2594).
  *
- * Matches both forward-slash and platform-native separators to handle
- * Windows paths (path.sep = '\\') and normalized Unix paths.
+ * Layout matching is owned by worktree-root's findWorktreeSegment; this
+ * only adds the requirement that a non-empty worktree name follows the
+ * marker (the worktrees container dir itself is not a worktree).
  */
 function isInsideGsdWorktree(p) {
-    // Match /.gsd/worktrees/<name> where <name> is the final segment or
-    // followed by a separator. The <name> segment must be non-empty.
-    const sepFwd = "/";
-    const sepNative = "\\";
-    const markers = [
-        `${sepFwd}.gsd${sepFwd}worktrees${sepFwd}`,
-        `${sepNative}.gsd${sepNative}worktrees${sepNative}`,
-    ];
-    for (const marker of markers) {
-        const idx = p.indexOf(marker);
-        if (idx === -1)
-            continue;
-        // Verify there's a non-empty worktree name after the marker
-        const afterMarker = p.slice(idx + marker.length);
-        // The name is everything up to the next separator (or end of string)
-        const nameEnd = afterMarker.search(/[/\\]/);
-        const name = nameEnd === -1 ? afterMarker : afterMarker.slice(0, nameEnd);
-        if (name.length > 0)
-            return true;
-    }
-    return false;
+    const normalized = p.replaceAll("\\", "/");
+    const segment = findWorktreeSegment(normalized);
+    if (!segment)
+        return false;
+    const name = normalized.slice(segment.afterWorktrees).split("/")[0];
+    return name.length > 0;
 }
 function probeGsdRoot(rawBasePath) {
     const contract = resolveGsdPathContract(rawBasePath);