@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.8e6112e9

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/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/notifications.js

@@ -2,31 +2,36 @@
 // Cross-platform desktop notifications for auto-mode events.
 import { execFileSync } from "node:child_process";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { sendRemoteNotification } from "../remote-questions/notify.js";
+import { sendRemoteNotification as _sendRemoteNotification } from "../remote-questions/notify.js";
+/** Swappable dispatcher for remote notifications — exported so tests can mock it. */
+export const remoteNotificationDispatcher = {
+    send: _sendRemoteNotification,
+};
 /**
  * Send a native desktop notification. Non-blocking, non-fatal.
  * macOS: osascript, Linux: notify-send, Windows: skipped.
  */
-export function sendDesktopNotification(title, message, level = "info", kind = "complete", projectName) {
+export function sendDesktopNotification(title, message, level = "info", kind = "complete", projectName, deps = {}) {
     // When a projectName is provided and the title is the default "GSD",
     // replace it with a project-qualified title for multi-project clarity.
     if (projectName && title === "GSD") {
         title = formatNotificationTitle(projectName);
     }
-    const loaded = loadEffectiveGSDPreferences()?.preferences;
+    const loadedPreferences = loadEffectiveGSDPreferences()?.preferences;
+    const notifications = deps.notifications ?? loadedPreferences?.notifications;
     // Remote notifications fire independently of desktop preferences.
     // sendRemoteNotification handles "not configured" gracefully (early return).
-    void sendRemoteNotification(title, message).catch(() => { });
-    if (!shouldSendDesktopNotification(kind, loaded?.notifications))
+    void remoteNotificationDispatcher.send(title, message).catch(() => { });
+    if (!shouldSendDesktopNotification(kind, notifications))
         return;
     // cmux delivery and desktop delivery are independent — if cmux import or
     // delivery fails, we must still attempt the native desktop notification.
     const runCmux = async () => {
         try {
             const { CmuxClient, emitOsc777Notification, resolveCmuxConfig } = await import("../cmux/index.js");
-            const cmux = resolveCmuxConfig(loaded);
+            const cmux = resolveCmuxConfig(loadedPreferences);
             if (cmux.notifications) {
-                const delivered = CmuxClient.fromPreferences(loaded).notify(title, message);
+                const delivered = CmuxClient.fromPreferences(loadedPreferences).notify(title, message);
                 if (delivered)
                     return true;
                 emitOsc777Notification(title, message);

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"))) {
@@ -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/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/parsers-legacy.js

@@ -1,10 +1,22 @@
 // GSD Extension - Legacy Parsers
 // parseRoadmap() and parsePlan() extracted from files.ts.
-// Used only by: md-importer.ts (migration), state.ts (pre-migration fallback),
-// markdown-renderer.ts (detectStaleRenders disk-vs-DB comparison),
-// commands-maintenance.ts (cold-path branch cleanup), and tests.
 //
-// NOT used in the dispatch loop or any hot-path runtime code.
+// ADR-017: the DB is the single source of truth; `.gsd/*.md` files are
+// projections. These parsers may be imported ONLY for:
+//   - migration/import (md-importer, workflow-migration, migration-auto-check)
+//   - drift detection that compares both sources by design
+//     (state-reconciliation/drift, markdown-renderer stale-render detection)
+//   - explicit pre-migration / DB-unavailable fallbacks (state.ts,
+//     reactive-graph.ts, auto-recovery.ts)
+//   - diagnostics and display/telemetry-only surfaces (doctor,
+//     doctor-git-checks, workspace-index, visualizer-data, auto-prompts
+//     context text, commands-maintenance, milestone-closeout, github-sync)
+//   - tests
+//
+// Dispatch/gate/completion DECISION paths must NOT import this module — they
+// read the DB via gsd-db queries (e.g. getMilestoneSliceSummaries). Enforced
+// by tests/parsers-legacy-importers.test.ts; new importers must be added to
+// its allowlist with a one-line justification.
 import { extractSection, parseBullets, extractBoldField, extractAllSections, registerCacheClearCallback } from './files.js';
 import { splitFrontmatter } from '../shared/frontmatter.js';
 import { nativeParseRoadmap, nativeParsePlanFile } from './native-parser-bridge.js';

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