@opengsd/gsd-pi 1.2.0-dev.4c756166 → 1.2.0-dev.5457a158

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

@@ -0,0 +1,98 @@
+// Project/App: gsd-pi
+// File Purpose: Guidance module — the single catalog mapping typed findings
+// (Recovery kinds, milestone blocker kinds, doctor issue codes, crash unit
+// classes) to user-facing remediation: what happened and what to do next.
+//
+// Emit sites pass the typed finding; phrasing, command names, and step
+// ordering live here. A missing catalog row is a visible gap, not a silent
+// omission scattered across call sites.
+/** Flatten guidance into a notification / pause-banner string. */
+export function formatGuidance(guidance) {
+    if (guidance.steps.length === 0)
+        return guidance.summary;
+    const numbered = guidance.steps.map((step, index) => `${index + 1}. ${step}`).join("\n");
+    return `${guidance.summary}\n\n${numbered}`;
+}
+const RECOVERY_REMEDIATION = {
+    "tool-schema": "Fix the Unit Tool Contract or tool schema before retrying.",
+    "tool-contract": "Fix the Unit Tool Contract or prompt so the Unit is only asked to use tools owned by its phase.",
+    "tool-unavailable": "The tool surface had not finished registering when the Unit called it (workflow MCP startup race). Retry after the surface is ready; escalate if the tool never appears.",
+    "deterministic-policy": "Resolve the policy blocker; retrying the same Unit will repeat the failure.",
+    "lifecycle-progression": "Route to the required owning Unit or restore the missing artifact before advancing lifecycle state.",
+    "stale-worker": "Run `/gsd doctor` to detect and clear the stale worker or lock, then run `/gsd auto` to resume.",
+    "worktree-invalid": "Run `/gsd doctor` to diagnose the milestone worktree (`gsd worktree list` shows its state). Repair it, or merge salvageable work with `gsd worktree merge <name>` before recreating — recreating discards uncommitted work.",
+    "verification-drift": "Run `/gsd status` to see the verification finding, fix or re-run the verification, then run `/gsd auto` to resume. `/gsd doctor` can repair stale state files.",
+    "reconciliation-drift": "Run `/gsd doctor` to surface the persistent or repair-failed drift kinds, apply its fixes, then run `/gsd auto` to resume.",
+    "illegal-transition": "A derived Phase edge rejected by the Phase Transition Invariant survived reconciliation; inspect deriveState and the State Reconciliation Module before resuming.",
+    "runtime-unknown": "Inspect the runtime error and add a dedicated classification if it is repeatable.",
+    "provider-transient": "Retry after the provider/network condition clears.",
+    "provider-permanent": "Inspect provider credentials, model entitlement, or request shape.",
+};
+export function recoveryRemediation(key) {
+    return RECOVERY_REMEDIATION[key];
+}
+// ─── Milestone validation blockers ──────────────────────────────────────
+// NOTE: the first line of each blocker is load-bearing — validation-block-guard
+// matches /milestone validation returned needs-(?:attention|remediation)/i.
+// Keep that phrase intact when editing.
+export function needsAttentionBlockerGuidance(milestoneId) {
+    return [
+        `Milestone ${milestoneId} is blocked because milestone validation returned needs-attention.`,
+        `Fix options:`,
+        `1. Review the validation details: \`/gsd status\``,
+        `2. If you fixed the missing evidence or issue, re-run milestone validation: \`/gsd validate-milestone\``,
+        `3. If the finding is acceptable, override it: \`/gsd verdict pass --rationale "why this is okay"\``,
+        `4. If this should wait, defer it explicitly: \`/gsd park ${milestoneId}\``,
+        `After validation or override passes, run \`/gsd auto\` to complete and merge the milestone.`,
+    ].join("\n");
+}
+export function needsRemediationBlockerGuidance(milestoneId) {
+    return [
+        `Milestone ${milestoneId} is blocked because milestone validation returned needs-remediation, but all slices are complete.`,
+        `Fix options:`,
+        `1. Run \`/gsd dispatch reassess\` to add remediation slices, then run \`/gsd auto\``,
+        `2. If the finding is acceptable, override it: \`/gsd verdict pass --rationale "why this is okay"\``,
+        `3. If this should wait, defer it explicitly: \`/gsd park ${milestoneId}\``,
+    ].join("\n");
+}
+// ─── Crash recovery resume hints ────────────────────────────────────────
+/** Resume hint for an interrupted auto-mode unit, by unit class. */
+export function crashResumeHint(unitType, unitId) {
+    if (unitType === "starting" && unitId === "bootstrap") {
+        return `No work was lost. Run /gsd auto to restart.`;
+    }
+    if (unitType.includes("research") || unitType.includes("plan")) {
+        return `The ${unitType} unit may be incomplete. Run /gsd auto to re-run it.`;
+    }
+    if (unitType.includes("execute")) {
+        return `Task execution was interrupted. Run /gsd auto to resume — completed work is preserved.`;
+    }
+    if (unitType.includes("complete")) {
+        return `Slice/milestone completion was interrupted. Run /gsd auto to finish.`;
+    }
+    return undefined;
+}
+// ─── Doctor issue fix hints ─────────────────────────────────────────────
+// Partial by design: codes without a row render no hint. Add rows here as
+// guidance is authored — the gap is visible in one place.
+const DOCTOR_FIX_HINTS = {
+    db_unavailable: "The workflow database could not be opened — state derivation is degraded. Restart the session; if it persists, run `/gsd doctor` from the project root.",
+    stale_crash_lock: "Run `/gsd doctor` to clear the stale lock, then `/gsd auto` to resume.",
+    stale_parallel_session: "Run `/gsd doctor` to clear the stale session registration.",
+    unresolved_git_conflicts: "Resolve the conflict markers, commit, then re-run `/gsd auto`.",
+    conflict_markers_in_tracked_files: "Search the listed files for `<<<<<<<` markers, resolve, and commit.",
+    worktree_dirty: "Commit or merge the worktree's changes (`gsd worktree merge <name>`) before removing it.",
+    worktree_branch_merged: "The branch is merged — remove the worktree to reclaim space.",
+    orphaned_auto_worktree: "Run `/gsd doctor` to fix, or merge salvageable work with `gsd worktree merge <name>`.",
+    gitignore_missing_patterns: "Run `/gsd doctor` to append the missing .gitignore patterns.",
+    invalid_preferences: "Edit .gsd/PREFERENCES.md to fix the invalid field, then re-run the command.",
+    provider_key_missing: "Add the provider API key to your environment or provider config, then retry.",
+    provider_key_backedoff: "The key is cooling down after repeated failures — wait, or switch the phase model in .gsd/PREFERENCES.md.",
+    state_file_stale: "Run `/gsd doctor` to rebuild the projection from the database.",
+    state_file_missing: "Run `/gsd doctor` to rebuild the projection from the database.",
+    projection_drift: "Run `/gsd doctor` to rebuild markdown projections from the database (DB is the source of truth).",
+    uat_retry_exhausted: "Review the failing UAT criteria via `/gsd status`, fix the issue, then re-run `/gsd auto`.",
+};
+export function doctorFixHint(code) {
+    return DOCTOR_FIX_HINTS[code];
+}

package/dist/resources/extensions/gsd/guided-flow.js

@@ -47,10 +47,10 @@ import { DISCUSS_TOOLS_ALLOWLIST } from "./constants.js";
 import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForGuidedUnit, supportsStructuredQuestions, } from "./workflow-mcp.js";
 import { runPreparation, formatCodebaseBrief, formatPriorContextBrief, } from "./preparation.js";
 import { verifyExpectedArtifact } from "./auto-recovery.js";
-import { getPendingGate } from "./bootstrap/write-gate.js";
+import { clearPendingGate, extractDepthVerificationMilestoneId, getPendingGate } from "./bootstrap/write-gate.js";
 import { _getPendingAutoStart, deletePendingAutoStart, hasPendingAutoStart, setPendingAutoStart, } from "./pending-auto-start.js";
 import { clearGuidedUnitContext, setGuidedUnitContext } from "./guided-unit-context.js";
-import { scheduleAutoStartAfterIdle } from "./discussion-handoff.js";
+import { checkAutoStartAfterDiscuss, scheduleAutoStartAfterIdle } from "./discussion-handoff.js";
 export { maybeHandleEmptyIntentTurn, maybeHandleReadyPhraseWithoutFiles, resetEmptyTurnCounter, } from "./guided-unit-completion.js";
 export { _getPendingAutoStart, clearPendingAutoStart, getDiscussionMilestoneId, setPendingAutoStart, } from "./pending-auto-start.js";
 export { checkAutoStartAfterDiscuss } from "./discussion-handoff.js";
@@ -1188,6 +1188,27 @@ function selfHealRuntimeRecords(basePath, ctx) {
         return { cleared: 0 };
     }
 }
+/**
+ * True when an agent turn is currently streaming or a dispatched message is
+ * still queued waiting to trigger one. Used by the pending-auto-start stale
+ * check: a live discuss turn can run for minutes before writing its first
+ * artifact, and deleting its entry as "stale" re-dispatches the workflow —
+ * resetting the interview and producing a duplicate completion turn.
+ */
+function isAgentTurnInFlight(ctx) {
+    try {
+        if (typeof ctx.isIdle === "function" && !ctx.isIdle())
+            return true;
+        if (typeof ctx.hasPendingMessages === "function" && ctx.hasPendingMessages())
+            return true;
+    }
+    catch {
+        // assertActive() throws on a stale runner context; fall through to
+        // artifact/age staleness signals.
+        logWarning("guided", "isAgentTurnInFlight: ctx method threw (stale runner); assuming no turn in flight");
+    }
+    return false;
+}
 // ─── Milestone Actions Submenu ──────────────────────────────────────────────
 /**
  * Shows a submenu with Park / Discard / Skip / Back options for the active milestone.
@@ -1479,12 +1500,18 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
         // and fires another dispatchWorkflow, resetting the conversation mid-interview.
         if (hasPendingAutoStart(basePath)) {
             // #3274: If /clear interrupted the discussion, the pending entry is stale.
-            // Detect staleness: no manifest, no milestone CONTEXT artifact, AND entry is older than
-            // 30s (avoids race between .set() and LLM writing first artifact).
+            // Detect staleness: no manifest, no milestone CONTEXT/CONTEXT-DRAFT artifact,
+            // the entry is older than 30s (avoids race between .set() and LLM writing the
+            // first artifact), AND no agent turn is in flight. A dispatched discuss turn
+            // can think for well over 30s before its first question round writes any
+            // artifact; deleting the entry while that turn is live re-dispatches the
+            // workflow, which both resets the interview and queues a duplicate turn that
+            // replays the final "context written" message after the real one.
             const entry = _getPendingAutoStart(basePath);
             const ageMs = Date.now() - (entry.createdAt || 0);
             const manifestExists = existsSync(join(gsdRoot(basePath), "DISCUSSION-MANIFEST.json"));
             const milestoneHasContext = !!resolveMilestoneFile(basePath, entry.milestoneId, "CONTEXT");
+            const milestoneHasDraft = !!resolveMilestoneFile(basePath, entry.milestoneId, "CONTEXT-DRAFT");
             const milestoneHasRoadmap = !!resolveMilestoneFile(basePath, entry.milestoneId, "ROADMAP");
             const milestoneRow = isDbAvailable() ? getMilestone(entry.milestoneId) : null;
             const discussPlanComplete = milestoneHasRoadmap && !!milestoneRow && milestoneRow.status !== "queued";
@@ -1493,11 +1520,30 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
                 // Clear stale in-memory guard and continue through normal active-milestone routing.
                 deletePendingAutoStart(basePath);
             }
-            else if (!manifestExists && !milestoneHasContext && ageMs > 30_000) {
+            else if (!manifestExists &&
+                !milestoneHasContext &&
+                !milestoneHasDraft &&
+                ageMs > 30_000 &&
+                !isAgentTurnInFlight(ctx)) {
                 // Stale entry from an interrupted discussion — clear and continue
                 deletePendingAutoStart(basePath);
             }
             else {
+                if (milestoneHasContext && !isAgentTurnInFlight(ctx)) {
+                    // The discussion already produced CONTEXT but the agent_end handoff
+                    // never consumed the entry — e.g. an external-engine post-hoc gate
+                    // re-arm wiped the depth verification after the save (write-gate
+                    // two-process sync). CONTEXT can only be written through a verified
+                    // depth gate, so a gate still pending for this milestone is stale:
+                    // clear it and re-run the handoff instead of dead-ending.
+                    const gateBasePath = entry.scope.workspace.projectRoot;
+                    const pendingGateId = getPendingGate(gateBasePath);
+                    if (pendingGateId && extractDepthVerificationMilestoneId(pendingGateId) === entry.milestoneId) {
+                        clearPendingGate(gateBasePath);
+                    }
+                    if (checkAutoStartAfterDiscuss(basePath))
+                        return;
+                }
                 ctx.ui.notify("Discussion already in progress — answer the question above to continue.", "info");
                 return;
             }

package/dist/resources/extensions/gsd/mcp-tool-name.js

@@ -1,20 +1,12 @@
 // Project/App: gsd-pi
-// File Purpose: Shared parsing and formatting helpers for MCP-scoped tool names.
+// File Purpose: GSD-facing face over the shared @gsd/pi-ai MCP tool-name helpers.
+import { parseMcpToolName as parsePiAiMcpToolName, stripMcpToolPrefix } from "@gsd/pi-ai";
 const MCP_TOOL_PREFIX = "mcp__";
 export function parseMcpToolName(toolName) {
-    if (!toolName.startsWith(MCP_TOOL_PREFIX))
-        return null;
-    const toolSeparator = toolName.indexOf("__", MCP_TOOL_PREFIX.length);
-    if (toolSeparator < 0)
-        return null;
-    return {
-        serverName: toolName.slice(MCP_TOOL_PREFIX.length, toolSeparator),
-        toolName: toolName.slice(toolSeparator + 2),
-    };
-}
-export function stripMcpToolPrefix(toolName) {
-    return parseMcpToolName(toolName)?.toolName ?? toolName;
+    const parsed = parsePiAiMcpToolName(toolName);
+    return parsed ? { serverName: parsed.server, toolName: parsed.tool } : null;
 }
+export { stripMcpToolPrefix };
 export function toMcpToolName(serverName, toolName) {
     return `${MCP_TOOL_PREFIX}${serverName}__${toolName}`;
 }

package/dist/resources/extensions/gsd/memory-consolidation-scanner.js

@@ -211,7 +211,7 @@ export function reportConsolidationGaps(basePath) {
         const report = scanConsolidationGaps(basePath);
         if (report.totalGaps === 0)
             return report;
-        appendNotification(report.summary, "warning", "workflow-logger");
+        appendNotification(report.summary, "warning", "workflow-logger", { kind: "memory-consolidation" });
         logWarning("memory-consolidation", report.summary);
         return report;
     }

package/dist/resources/extensions/gsd/migrate/safety.js

@@ -8,6 +8,7 @@ import { readCrashLock, isLockProcessAlive } from "../crash-recovery.js";
 import { closeWorkflowDatabase } from "../db-workspace.js";
 import { readPausedSessionMetadata } from "../interrupted-session.js";
 import { gsdRoot } from "../paths.js";
+import { canonicalWorktreesDir } from "../worktree-placement.js";
 export class MigrationBlockedError extends Error {
     constructor(message) {
         super(message);
@@ -78,16 +79,26 @@ export function assertMigrationHasSlices(preview) {
     throw new MigrationBlockedError("Migration blocked - the legacy project would produce zero slices. Add a ROADMAP.md or phases/ content before migrating.");
 }
 function hasWorktreeState(targetRoot) {
-    const worktreesDir = join(gsdRoot(targetRoot), "worktrees");
-    if (!existsSync(worktreesDir))
-        return false;
-    try {
-        return readdirSync(worktreesDir, { withFileTypes: true })
-            .some((entry) => entry.isDirectory() || entry.isFile());
-    }
-    catch {
-        return true;
+    // Legacy container is probed via gsdRoot() (symlink-resolved) on purpose —
+    // migration targets may have .gsd in the external-state layout.
+    const containers = [
+        canonicalWorktreesDir(targetRoot),
+        join(gsdRoot(targetRoot), "worktrees"),
+    ];
+    for (const worktreesDir of containers) {
+        if (!existsSync(worktreesDir))
+            continue;
+        try {
+            if (readdirSync(worktreesDir, { withFileTypes: true })
+                .some((entry) => entry.isDirectory() || entry.isFile())) {
+                return true;
+            }
+        }
+        catch {
+            return true;
+        }
     }
+    return false;
 }
 export async function assertMigrationTargetAvailable(targetRoot) {
     const targetGsdPath = gsdRoot(targetRoot);

package/dist/resources/extensions/gsd/migration-auto-check.js

@@ -8,7 +8,13 @@ function zeroCounts() {
     return { milestones: 0, slices: 0, tasks: 0 };
 }
 function emptyScan() {
-    return { counts: zeroCounts(), milestones: new Set(), slices: new Set(), tasks: new Set() };
+    return {
+        counts: zeroCounts(),
+        milestones: new Set(),
+        slices: new Set(),
+        tasks: new Set(),
+        milestonesWithoutRoadmap: new Set(),
+    };
 }
 function sameCounts(a, b) {
     return a.milestones === b.milestones && a.slices === b.slices && a.tasks === b.tasks;
@@ -65,8 +71,10 @@ export function scanMarkdownHierarchy(basePath) {
         scan.counts.milestones++;
         scan.milestones.add(milestoneId);
         const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
-        if (!roadmapPath || !existsSync(roadmapPath))
+        if (!roadmapPath || !existsSync(roadmapPath)) {
+            scan.milestonesWithoutRoadmap.add(milestoneId);
             continue;
+        }
         const roadmap = parseRoadmap(readFileSync(roadmapPath, "utf-8"));
         scan.counts.slices += roadmap.slices.length;
         for (const slice of roadmap.slices) {
@@ -112,7 +120,6 @@ export function countDbHierarchy() {
 }
 export async function checkMarkdownHierarchyAgainstDb(basePath) {
     const markdownScan = scanMarkdownHierarchy(basePath);
-    const markdown = markdownScan.counts;
     // Always open the DB before deciding. An empty markdown tree does NOT imply
     // an empty project — the DB may hold authoritative rows whose markdown was
     // lost, which is itself recoverable drift. The previous early return here
@@ -128,6 +135,20 @@ export async function checkMarkdownHierarchyAgainstDb(basePath) {
     refreshWorkflowDatabaseFromDisk();
     const dbScan = scanDbHierarchy();
     const beforeDb = dbScan.counts;
+    // Discussion-phase scratch: a milestone dir with no ROADMAP and no DB row is
+    // a pre-registration discussion artifact (CONTEXT/CONTEXT-DRAFT only — the
+    // queued DB row is inserted only at discussion handoff). Treating it as
+    // drift would warn on every live discussion and recommend
+    // `/gsd recover --confirm`, an import that materializes abandoned-discussion
+    // dirs as ghost active milestones. Exclude such dirs from this comparison
+    // only; recover preflights use the raw scans and still see them.
+    for (const id of markdownScan.milestonesWithoutRoadmap) {
+        if (dbScan.milestones.has(id))
+            continue;
+        markdownScan.milestones.delete(id);
+        markdownScan.counts.milestones--;
+    }
+    const markdown = markdownScan.counts;
     const markdownEmpty = sameCounts(markdown, zeroCounts());
     const dbEmpty = sameCounts(beforeDb, zeroCounts());
     // Genuinely empty project: nothing on disk, nothing in the DB.

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/notification-store.js

@@ -34,13 +34,16 @@ export function initNotificationStore(basePath) {
  * Append a notification entry to the store. Synchronous — safe to call
  * from the notify() shim which is declared void (not async).
  */
-export function appendNotification(message, severity, source = "notify") {
+export function appendNotification(message, severity, source = "notify", meta) {
     if (!_basePath)
         return;
     if (_suppressCount > 0)
         return;
     const persistedMessage = message.length > 500 ? message.slice(0, 500) + "…" : message;
-    const dedupKey = `${_basePath}:${severity}:${source}:${persistedMessage}`;
+    // Structured identity (kind + scope) keys dedup when present, so a rephrased
+    // message of the same event still dedups; otherwise fall back to the prose.
+    const identity = meta?.kind ? `${meta.kind}:${meta.scope ?? ""}` : persistedMessage;
+    const dedupKey = `${_basePath}:${severity}:${source}:${identity}`;
     const now = Date.now();
     const lastSeen = _recentMessageTimestamps.get(dedupKey);
     if (lastSeen !== undefined && now - lastSeen < DEDUP_WINDOW_MS)
@@ -59,6 +62,8 @@ export function appendNotification(message, severity, source = "notify") {
         message: persistedMessage,
         source,
         read: false,
+        ...(meta?.kind ? { kind: meta.kind } : {}),
+        ...(meta?.scope ? { scope: meta.scope } : {}),
     };
     try {
         const dir = join(_basePath, ".gsd");
@@ -77,12 +82,14 @@ export function appendNotification(message, severity, source = "notify") {
 }
 /**
  * Read all notification entries from disk. Returns newest-first.
+ * An optional filter narrows by structured identity (kind and/or scope).
  */
-export function readNotifications(basePath) {
+export function readNotifications(basePath, filter) {
     const bp = basePath ?? _basePath;
     if (!bp)
         return [];
-    return _readEntriesFromDisk(bp).reverse();
+    const entries = _readEntriesFromDisk(bp).filter((e) => (!filter?.kind || e.kind === filter.kind) && (!filter?.scope || e.scope === filter.scope));
+    return entries.reverse();
 }
 /**
  * Mark all notifications as read. Atomic rewrite via temp-file + rename.

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"))) {
@@ -68,8 +70,7 @@ function discoverWorkers(basePath) {
     }
     return [...mids].sort();
 }
-function querySliceProgress(basePath, mid) {
-    const workRoot = join(basePath, ".gsd", "worktrees", mid);
+function querySliceProgress(basePath, mid, workRoot = worktreePathFor(basePath, mid)) {
     const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
     if (!existsSync(dbPath))
         return [];
@@ -115,7 +116,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 [];
@@ -139,9 +140,12 @@ function collectWorkerData(basePath) {
     const parallelDir = join(basePath, ".gsd", "parallel");
     const workers = [];
     for (const mid of mids) {
+        // Resolve the worktree path once per worker per tick — this runs on a
+        // 5-second refresh interval and worktreePathFor probes the filesystem.
+        const workRoot = worktreePathFor(basePath, mid);
         const status = readJsonSafe(join(parallelDir, `${mid}.status.json`));
-        const lock = readJsonSafe(join(basePath, ".gsd", "worktrees", mid, ".gsd", "auto.lock"));
-        const slices = querySliceProgress(basePath, mid);
+        const lock = readJsonSafe(join(workRoot, ".gsd", "auto.lock"));
+        const slices = querySliceProgress(basePath, mid, workRoot);
         const pid = lock?.pid || status?.pid || 0;
         const alive = pid ? isPidAlive(pid) : false;
         // Heartbeat: prefer status.json if PID matches, else use file mtime

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();
@@ -139,6 +139,33 @@ export function clearPathCache() {
     nativeTreeBase = null;
 }
 // ─── Name Builders ─────────────────────────────────────────────────────────
+/** Directories owned by the GSD framework — metadata, never project source. */
+export const FRAMEWORK_METADATA_DIRS = [".gsd", ".planning", ".audits"];
+/**
+ * Every artifact suffix used with the name builders below — the single source
+ * for the `<ID>-<SUFFIX>.md` naming vocabulary. Extend this list when a new
+ * artifact type is introduced; consumers (md-importer walking, pre-execution
+ * artifact detection) pick it up from here.
+ */
+export const PLANNING_ARTIFACT_SUFFIXES = [
+    "CONTEXT",
+    "CONTEXT-DRAFT",
+    "ROADMAP",
+    "PLAN",
+    "REPLAN",
+    "SUMMARY",
+    "RESEARCH",
+    "VALIDATION",
+    "ASSESSMENT",
+    "UAT",
+    "DISCUSSION",
+    "EVAL-REVIEW",
+    "PARKED",
+    "VERIFICATION-FAILED",
+    "CONTINUE",
+];
+/** Matches a bare planning-artifact file name, e.g. "M001-CONTEXT.md", "S01-PLAN.md". */
+export const PLANNING_ARTIFACT_NAME_RE = new RegExp(`^[MST]\\d+-(${PLANNING_ARTIFACT_SUFFIXES.join("|")})\\.md$`, "i");
 /**
  * Build a milestone-level file name.
  * ("M001", "CONTEXT") → "M001-CONTEXT.md"
@@ -422,31 +449,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);