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

package/src/resources/extensions/gsd/notification-store.ts

@@ -12,6 +12,17 @@ import { randomUUID } from "node:crypto";
 export type NotifySeverity = "info" | "success" | "warning" | "error";
 export type NotificationSource = "notify" | "workflow-logger";
 
+/**
+ * Optional structured identity for a notification. When present, `kind`
+ * (a stable machine name like "auto-stop" or "provider-error-pause") plus
+ * `scope` (e.g. a milestone/slice id) — not the prose — key deduplication,
+ * and consumers can filter without parsing message text.
+ */
+export interface NotificationMeta {
+  kind?: string;
+  scope?: string;
+}
+
 export interface NotificationEntry {
   id: string;
   ts: string;
@@ -19,6 +30,8 @@ export interface NotificationEntry {
   message: string;
   source: NotificationSource;
   read: boolean;
+  kind?: string;
+  scope?: string;
 }
 
 // ─── Constants ──────────────────────────────────────────────────────────
@@ -60,11 +73,15 @@ export function appendNotification(
   message: string,
   severity: NotifySeverity,
   source: NotificationSource = "notify",
+  meta?: NotificationMeta,
 ): void {
   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) return;
@@ -82,6 +99,8 @@ export function appendNotification(
     message: persistedMessage,
     source,
     read: false,
+    ...(meta?.kind ? { kind: meta.kind } : {}),
+    ...(meta?.scope ? { scope: meta.scope } : {}),
   };
 
   try {
@@ -102,11 +121,15 @@ export function appendNotification(
 
 /**
  * Read all notification entries from disk. Returns newest-first.
+ * An optional filter narrows by structured identity (kind and/or scope).
  */
-export function readNotifications(basePath?: string): NotificationEntry[] {
+export function readNotifications(basePath?: string, filter?: NotificationMeta): NotificationEntry[] {
   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();
 }
 
 /**

package/src/resources/extensions/gsd/notifications.ts

@@ -4,7 +4,12 @@
 import { execFileSync } from "node:child_process";
 import type { NotificationPreferences } from "./types.js";
 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,
+};
 
 export type NotifyLevel = "info" | "success" | "warning" | "error";
 export type NotificationKind = "complete" | "error" | "budget" | "milestone" | "attention";
@@ -30,28 +35,30 @@ export function sendDesktopNotification(
   level: NotifyLevel = "info",
   kind: NotificationKind = "complete",
   projectName?: string,
+  deps: { notifications?: NotificationPreferences } = {},
 ): void {
   // 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(() => {});
+  void remoteNotificationDispatcher.send(title, message).catch(() => {});
 
-  if (!shouldSendDesktopNotification(kind, loaded?.notifications)) return;
+  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/src/resources/extensions/gsd/parallel-eligibility.ts

@@ -5,11 +5,11 @@
  * dependency satisfaction and file overlap across slice plans.
  */
 
-import { existsSync } from "node:fs";
 import { deriveState } from "./state.js";
-import { resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "./paths.js";
+import { resolveMilestoneFile, resolveSliceFile } 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";
 import type { MilestoneRegistryEntry } from "./types.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
@@ -98,8 +98,7 @@ export async function analyzeParallelEligibility(
   basePath: string,
 ): Promise<ParallelCandidates> {
   if (!isDbAvailable()) {
-    const { projectDb } = resolveGsdPathContract(basePath);
-    if (existsSync(projectDb)) openDatabase(projectDb);
+    openExistingWorkflowDatabase(basePath);
   }
 
   const milestoneIds = findMilestoneIds(basePath);

package/src/resources/extensions/gsd/parallel-merge.ts

@@ -9,6 +9,7 @@ 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 {
@@ -42,7 +43,7 @@ export type MergeOrder = "sequential" | "by-completion";
  * Returns true when milestones.status = 'complete' in project gsd.db.
  */
 export function isMilestoneCompleteInProjectDb(basePath: string, mid: string): boolean {
-  const workRoot = join(basePath, ".gsd", "worktrees", mid);
+  const workRoot = worktreePathFor(basePath, mid);
   const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
   if (!existsSync(dbPath)) return false;
 
@@ -65,15 +66,17 @@ export function isMilestoneCompleteInProjectDb(basePath: string, mid: string): b
  */
 function discoverDbCompletedMilestones(basePath: string): Set<string> {
   const completed = new Set<string>();
-  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 as Error).message}`);
     }
-  } catch (e) {
-    logWarning("parallel", `readdirSync for completed set failed: ${(e as Error).message}`);
   }
   return completed;
 }
@@ -120,7 +123,7 @@ export function determineMergeOrder(
         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/src/resources/extensions/gsd/parallel-monitor-overlay.ts

@@ -11,6 +11,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,
@@ -101,7 +102,6 @@ function tailRead(filePath: string, maxBytes: number): string {
 
 function discoverWorkers(basePath: string): string[] {
   const parallelDir = join(basePath, ".gsd", "parallel");
-  const worktreeDir = join(basePath, ".gsd", "worktrees");
   const mids = new Set<string>();
 
   if (existsSync(parallelDir)) {
@@ -114,7 +114,8 @@ function discoverWorkers(basePath: string): string[] {
     } 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"))) {
@@ -127,8 +128,7 @@ function discoverWorkers(basePath: string): string[] {
   return [...mids].sort();
 }
 
-function querySliceProgress(basePath: string, mid: string): SliceProgress[] {
-  const workRoot = join(basePath, ".gsd", "worktrees", mid);
+function querySliceProgress(basePath: string, mid: string, workRoot: string = worktreePathFor(basePath, mid)): SliceProgress[] {
   const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
   if (!existsSync(dbPath)) return [];
 
@@ -169,7 +169,7 @@ function extractCostFromNdjson(basePath: string, mid: string): number {
 }
 
 function queryRecentCompletions(basePath: string, mid: string): string[] {
-  const workRoot = join(basePath, ".gsd", "worktrees", mid);
+  const workRoot = worktreePathFor(basePath, mid);
   const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
   if (!existsSync(dbPath)) return [];
   try {
@@ -192,9 +192,12 @@ function collectWorkerData(basePath: string): WorkerView[] {
   const workers: WorkerView[] = [];
 
   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<StatusJson>(join(parallelDir, `${mid}.status.json`));
-    const lock = readJsonSafe<AutoLock>(join(basePath, ".gsd", "worktrees", mid, ".gsd", "auto.lock"));
-    const slices = querySliceProgress(basePath, mid);
+    const lock = readJsonSafe<AutoLock>(join(workRoot, ".gsd", "auto.lock"));
+    const slices = querySliceProgress(basePath, mid, workRoot);
 
     const pid = lock?.pid || status?.pid || 0;
     const alive = pid ? isPidAlive(pid) : false;

package/src/resources/extensions/gsd/parallel-orchestrator.ts

@@ -21,9 +21,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 type { GSDPreferences } from "./preferences.js";
 import type { ParallelConfig } from "./types.js";
@@ -561,7 +562,10 @@ export function _createMilestoneWorktree(basePath: string, milestoneId: string):
   // 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;
 }

package/src/resources/extensions/gsd/parsers-legacy.ts

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

package/src/resources/extensions/gsd/paths.ts

@@ -17,7 +17,7 @@ import { spawnSync } from "node:child_process";
 import { nativeScanGsdTree, type GsdTreeEntry } 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 ──────────────────────────────────────────────────
 
@@ -148,6 +148,39 @@ export function clearPathCache(): void {
 
 // ─── Name Builders ─────────────────────────────────────────────────────────
 
+/** Directories owned by the GSD framework — metadata, never project source. */
+export const FRAMEWORK_METADATA_DIRS: readonly string[] = [".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: readonly string[] = [
+  "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"
@@ -458,29 +491,16 @@ function assertNotGlobalGsdHome(basePath: string, result: string): void {
  * 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: string): boolean {
-  // 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: string): string {

package/src/resources/extensions/gsd/pre-execution-checks.ts

@@ -24,6 +24,7 @@ import { isAbsolute, relative, resolve } from "node:path";
 import type { TaskRow } from "./db-task-slice-rows.js";
 import type { PreExecutionCheckJSON } from "./verification-evidence.ts";
 import { validateVerificationCommand } from "./verification-gate.js";
+import { FRAMEWORK_METADATA_DIRS, PLANNING_ARTIFACT_NAME_RE } from "./paths.js";
 
 const NPM_COMMAND = process.platform === "win32" ? "npm.cmd" : "npm";
 
@@ -586,6 +587,9 @@ export function checkFilePathConsistency(
       // Skip empty strings
       if (!file.trim()) continue;
       if (!shouldValidateInputAsPath(file)) continue;
+      // Planning-artifact references are owned by checkPlanningArtifactReferences,
+      // which reports a precise removal message instead of "doesn't exist".
+      if (isPlanningArtifactReference(file, basePath, context)) continue;
 
       // Normalize path for consistent comparison
       const normalizedFile = toComparisonPath(file, basePath);
@@ -628,6 +632,85 @@ export function checkFilePathConsistency(
   return results;
 }
 
+// ─── Planning Artifact Reference Check ───────────────────────────────────────
+
+function isFrameworkMetadataPath(normalizedFile: string): boolean {
+  return normalizedFile.split("/").some((segment) => FRAMEWORK_METADATA_DIRS.includes(segment.toLowerCase()));
+}
+
+/**
+ * True when a task IO entry references a GSD planning artifact.
+ *
+ * Task inputs are source files only — planning artifacts are projections of DB
+ * state that the framework preloads as composed context (see CONTEXT.md "Task
+ * Input"). Two triggers, deliberately different in strictness:
+ *
+ * - Any path entering framework-owned metadata (.gsd/, .planning/, .audits/)
+ *   is always a violation, even when the file exists.
+ * - A bare artifact-style basename (M001-CONTEXT.md, S01-PLAN.md, …) is a
+ *   violation only when it does NOT resolve to a real file. When such a file
+ *   genuinely exists in the source tree (e.g. a fixture), it is a source file
+ *   and stays legal; a path with directory components is likewise left to the
+ *   ordinary existence checks.
+ */
+function isPlanningArtifactReference(
+  rawEntry: string,
+  basePath: string,
+  context?: PreExecutionCheckContext,
+): boolean {
+  if (!shouldValidateInputAsPath(rawEntry)) return false;
+  const normalized = toComparisonPath(rawEntry, basePath);
+  if (isFrameworkMetadataPath(normalized)) return true;
+  return (
+    !normalized.includes("/") &&
+    PLANNING_ARTIFACT_NAME_RE.test(normalized) &&
+    !inputExistsOnDisk(normalized, basePath, context)
+  );
+}
+
+/**
+ * Block GSD planning artifacts in task IO fields (inputs, files, expectedOutput).
+ *
+ * For inputs/files the violation smuggles a projection into the executor's
+ * preloaded source context; for expectedOutput it promises a write the runtime
+ * write-gate would reject mid-execution. Both get a precise message so the
+ * planning retry steers toward *removing* the reference, not creating the file.
+ * checkFilePathConsistency and checkTaskOrdering skip entries this check owns.
+ */
+export function checkPlanningArtifactReferences(
+  tasks: TaskRow[],
+  basePath: string,
+  context?: PreExecutionCheckContext,
+): PreExecutionCheckJSON[] {
+  const results: PreExecutionCheckJSON[] = [];
+
+  for (const task of tasks) {
+    const fields = [
+      { label: "inputs", entries: task.inputs },
+      { label: "files", entries: task.files },
+      { label: "expectedOutput", entries: task.expected_output },
+    ];
+    for (const { label, entries } of fields) {
+      for (const file of entries) {
+        if (!isPlanningArtifactReference(file, basePath, context)) continue;
+        const message =
+          label === "expectedOutput"
+            ? `Task ${task.id} lists '${file}' in expectedOutput — GSD planning artifacts are written by workflow tools (e.g. gsd_summary_save), never by tasks; remove it`
+            : `Task ${task.id} lists '${file}' in ${label} — GSD planning artifacts are projections preloaded as context, never task ${label}; remove it`;
+        results.push({
+          category: "file",
+          target: file,
+          passed: false,
+          message,
+          blocking: true,
+        });
+      }
+    }
+  }
+
+  return results;
+}
+
 // ─── Task Ordering Check ─────────────────────────────────────────────────────
 
 /**
@@ -671,6 +754,9 @@ export function checkTaskOrdering(
     for (const file of filesToCheck) {
       if (isRuntimeOnlyInput(file)) continue;
       if (!shouldValidateInputAsPath(file)) continue;
+      // Owned by checkPlanningArtifactReferences — avoid a duplicate sequence
+      // finding on top of the removal message.
+      if (isPlanningArtifactReference(file, basePath, context)) continue;
 
       const normalizedFile = toComparisonPath(file, basePath);
       if (containsGlobPattern(normalizedFile)) continue;
@@ -700,6 +786,27 @@ export function checkTaskOrdering(
   return results;
 }
 
+// ─── Shared Path-Check Composition ───────────────────────────────────────────
+
+/**
+ * The synchronous path-shaped checks, in order. One list shared by the
+ * plan-persist gate (gsd_plan_slice) and the dispatch gate
+ * (runPreExecutionChecks) so the two cannot drift — the checks coordinate
+ * ownership of planning-artifact entries via isPlanningArtifactReference
+ * skips, which only works when they run as a set.
+ */
+export function runTaskPathChecks(
+  tasks: TaskRow[],
+  basePath: string,
+  context?: PreExecutionCheckContext,
+): PreExecutionCheckJSON[] {
+  return [
+    ...checkPlanningArtifactReferences(tasks, basePath, context),
+    ...checkFilePathConsistency(tasks, basePath, context),
+    ...checkTaskOrdering(tasks, basePath, context),
+  ];
+}
+
 // ─── Interface Contract Check ────────────────────────────────────────────────
 
 interface FunctionSignature {
@@ -866,12 +973,11 @@ export async function runPreExecutionChecks(
   const allChecks: PreExecutionCheckJSON[] = [];
 
   // Run sync checks first
-  const fileChecks = checkFilePathConsistency(tasks, basePath, context);
-  const orderingChecks = checkTaskOrdering(tasks, basePath, context);
+  const pathChecks = runTaskPathChecks(tasks, basePath, context);
   const contractChecks = checkInterfaceContracts(tasks, basePath);
   const verificationChecks = checkVerificationCommands(tasks);
 
-  allChecks.push(...fileChecks, ...orderingChecks, ...contractChecks, ...verificationChecks);
+  allChecks.push(...pathChecks, ...contractChecks, ...verificationChecks);
 
   // Run async package checks
   const packageChecks = await checkPackageExistence(tasks, basePath);

package/src/resources/extensions/gsd/preferences-diagnostics.ts

@@ -0,0 +1,98 @@
+import type { PreferenceDiagnostic } from "./preferences-types.js";
+import {
+  loadGlobalGSDPreferences,
+  loadProjectGSDPreferences,
+} from "./preferences.js";
+
+interface PreferenceNotificationContext {
+  ui: {
+    notify(message: string, type?: "info" | "warning" | "error" | "success"): void;
+  };
+}
+
+interface PreferenceDiagnosticNotificationOptions {
+  surface?: string;
+}
+
+const notifiedPreferenceDiagnostics = new Set<string>();
+
+export function collectPreferenceDiagnostics(basePath?: string): PreferenceDiagnostic[] {
+  const diagnostics = [
+    ...(loadGlobalGSDPreferences()?.diagnostics ?? []),
+    ...(loadProjectGSDPreferences(basePath)?.diagnostics ?? []),
+  ];
+
+  const seen = new Set<string>();
+  const unique: PreferenceDiagnostic[] = [];
+  for (const diagnostic of diagnostics) {
+    const signature = preferenceDiagnosticSignature(diagnostic);
+    if (seen.has(signature)) continue;
+    seen.add(signature);
+    unique.push(diagnostic);
+  }
+  return unique;
+}
+
+export function formatPreferenceDiagnostic(diagnostic: PreferenceDiagnostic): string {
+  const scope = diagnostic.scope === "global" ? "global" : "project";
+  const level = diagnostic.severity === "error" ? "error" : "warning";
+  const heading = diagnostic.kind === "parse"
+    ? `GSD ${scope} preferences ${level}: ${diagnostic.path} could not be parsed.`
+    : `GSD ${scope} preferences ${level}: ${diagnostic.path} contains invalid settings.`;
+  const detail = formatPreferenceDiagnosticDetail(diagnostic);
+  const impact = diagnostic.ignored
+    ? "Preferences from this file were ignored; auto-mode may be using defaults."
+    : "Invalid settings were ignored or sanitized; auto-mode may be using defaults for them.";
+  return `${heading}\n${detail}\n${impact}\nRun /gsd doctor for details.`;
+}
+
+export function formatPreferenceDiagnosticDetail(diagnostic: PreferenceDiagnostic): string {
+  if (diagnostic.line !== undefined && diagnostic.column !== undefined) {
+    return `YAML error at line ${diagnostic.line}, column ${diagnostic.column}: ${diagnostic.message}`;
+  }
+  return diagnostic.message;
+}
+
+export function notifyPreferenceDiagnostics(
+  ctx: PreferenceNotificationContext,
+  basePath?: string,
+  options?: PreferenceDiagnosticNotificationOptions,
+): number {
+  let notified = 0;
+  for (const diagnostic of collectPreferenceDiagnostics(basePath)) {
+    const signature = preferenceDiagnosticNotificationSignature(diagnostic, options?.surface);
+    if (notifiedPreferenceDiagnostics.has(signature)) continue;
+    notifiedPreferenceDiagnostics.add(signature);
+    ctx.ui.notify(
+      formatPreferenceDiagnostic(diagnostic),
+      diagnostic.severity === "error" ? "error" : "warning",
+    );
+    notified++;
+  }
+  return notified;
+}
+
+export function _resetPreferenceDiagnosticNotificationsForTests(): void {
+  notifiedPreferenceDiagnostics.clear();
+}
+
+function preferenceDiagnosticSignature(diagnostic: PreferenceDiagnostic): string {
+  return [
+    diagnostic.path,
+    diagnostic.scope,
+    diagnostic.severity,
+    diagnostic.kind,
+    diagnostic.message,
+    diagnostic.line ?? "",
+    diagnostic.column ?? "",
+    diagnostic.ignored === true ? "ignored" : "",
+    diagnostic.sanitized === true ? "sanitized" : "",
+  ].join("\u0000");
+}
+
+function preferenceDiagnosticNotificationSignature(
+  diagnostic: PreferenceDiagnostic,
+  surface = "default",
+): string {
+  return `${surface}\u0000${preferenceDiagnosticSignature(diagnostic)}`;
+}