@opengsd/gsd-pi 1.2.0-dev.b1abb545 → 1.2.0-dev.e8563f58

package/src/resources/extensions/gsd/milestone-closeout.ts

@@ -5,13 +5,23 @@
 // - postUnit: git commit, artifact verify, DB settle, then GitHub finalize
 // - recovery: DB repair from artifacts, then GitHub finalize
 
+import { existsSync } from "node:fs";
+
 import { loadFile } from "./files.js";
-import { parseRoadmap } from "./parsers-legacy.js";
 import { resolveMilestoneFile } from "./paths.js";
-import { getMilestone, getMilestoneSlices, isDbAvailable } from "./gsd-db.js";
+import {
+  getMilestone,
+  getClosedSliceIds,
+  getLatestAssessmentByScope,
+  getMilestoneSlices,
+  isDbAvailable,
+} from "./gsd-db.js";
 import { isClosedStatus } from "./status-guards.js";
+import { resolveExpectedArtifactPath } from "./auto-artifact-paths.js";
+import { handleCompleteMilestone } from "./tools/complete-milestone.js";
 import { runSafely } from "./auto-utils.js";
 import { extractVerdict, isAcceptableUatVerdict } from "./verdict-parser.js";
+import { uatSignoffBlockerGuidance } from "./guidance.js";
 import { logWarning } from "./workflow-logger.js";
 import { hasImplementationArtifacts } from "./milestone-implementation-evidence.js";
 import { buildCompleteMilestonePrompt } from "./auto-prompts.js";
@@ -28,6 +38,76 @@ import {
 const COMPLETE_MILESTONE_DB_SETTLE_MS = 1500;
 const COMPLETE_MILESTONE_DB_SETTLE_POLL_MS = 100;
 
+/**
+ * True when a milestone is terminal for git cleanup (orphaned worktrees, stale branches).
+ * DB-authoritative (ADR-017): closed status, or validation-pass with all slices closed.
+ * When the DB is unavailable we cannot make this decision and conservatively
+ * return false so callers leave the worktree/branch alone instead of cleaning
+ * up based on parsed projections.
+ */
+export async function isCompletedMilestoneTerminal(
+  _basePath: string,
+  milestoneId: string,
+): Promise<boolean> {
+  if (!isDbAvailable()) return false;
+
+  const milestone = getMilestone(milestoneId);
+  if (!milestone) return false;
+
+  if (isClosedStatus(milestone.status)) {
+    return true;
+  }
+
+  const validation = getLatestAssessmentByScope(milestoneId, "milestone-validation");
+  if (validation?.status !== "pass") {
+    return false;
+  }
+
+  const slices = getMilestoneSlices(milestoneId);
+  if (slices.length === 0) return false;
+  return slices.every((slice) => isClosedStatus(slice.status));
+}
+
+/** Write a missing milestone SUMMARY projection when canonical DB closeout already settled. */
+export async function repairMissingMilestoneSummaryProjection(
+  basePath: string,
+  milestoneId: string,
+): Promise<{ ok: true } | { ok: false; error: string }> {
+  const milestone = getMilestone(milestoneId);
+  if (!milestone) {
+    return { ok: false, error: `milestone not found: ${milestoneId}` };
+  }
+
+  const artifactBasePath = resolveCanonicalMilestoneRoot(basePath, milestoneId);
+  const summaryPath = resolveExpectedArtifactPath("complete-milestone", milestoneId, artifactBasePath);
+  if (summaryPath && existsSync(summaryPath)) {
+    return { ok: true };
+  }
+
+  const result = await handleCompleteMilestone(
+    {
+      milestoneId,
+      title: milestone.title,
+      oneLiner: "Canonical closeout completed; summary projection repaired automatically.",
+      narrative:
+        "The workflow database recorded this milestone as complete, but the milestone SUMMARY artifact was missing on disk. " +
+        "Dispatch policy repaired the projection so closeout proof and cleanup can proceed.",
+      verificationPassed: true,
+      triggerReason: "closeout-projection-repair",
+    },
+    basePath,
+  );
+
+  if ("error" in result) {
+    return { ok: false, error: result.error };
+  }
+  const writtenSummaryPath = result.summaryPath;
+  if (result.stale || !writtenSummaryPath || !existsSync(writtenSummaryPath)) {
+    return { ok: false, error: "milestone SUMMARY projection write failed" };
+  }
+  return { ok: true };
+}
+
 /**
  * True when the milestone is closed in the DB and the completion summary artifact exists.
  * Polls briefly so post-unit verification can observe the tool's DB write.
@@ -78,7 +158,22 @@ export async function evaluateCompleteMilestoneDispatch(
   if (isDbAvailable()) {
     const milestone = getMilestone(mid);
     if (milestone && isClosedStatus(milestone.status)) {
-      return { action: "skip" };
+      const artifactBasePath = resolveCanonicalMilestoneRoot(basePath, mid);
+      const summaryPath = resolveExpectedArtifactPath("complete-milestone", mid, artifactBasePath);
+      const summaryMissing = !summaryPath || !existsSync(summaryPath);
+      if (summaryMissing) {
+        const repair = await repairMissingMilestoneSummaryProjection(basePath, mid);
+        if (!repair.ok) {
+          logWarning(
+            "dispatch",
+            `Milestone ${mid} is closed in DB but SUMMARY repair failed: ${repair.error}. Dispatching complete-milestone to retry.`,
+          );
+        } else {
+          return { action: "skip" };
+        }
+      } else {
+        return { action: "skip" };
+      }
     }
   }
 
@@ -86,31 +181,21 @@ export async function evaluateCompleteMilestoneDispatch(
   if (closeoutGitStop) return closeoutGitStop;
 
   if (prefs?.uat_dispatch) {
-    let closedSliceIds: string[];
-    if (isDbAvailable()) {
-      closedSliceIds = getMilestoneSlices(mid)
-        .filter((slice) => isClosedStatus(slice.status))
-        .map((slice) => slice.id);
-    } else {
-      const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
-      const roadmapContent = roadmapFile ? await loadFile(roadmapFile) : null;
-      if (!roadmapContent) {
-        return {
-          action: "stop",
-          reason: `Cannot complete milestone ${mid}: unable to verify UAT verdicts because ROADMAP is unavailable while DB is not accessible.`,
-          level: "warning",
-        };
-      }
-      const roadmap = parseRoadmap(roadmapContent);
-      closedSliceIds = roadmap.slices.filter((slice) => slice.done).map((slice) => slice.id);
+    // DB-authoritative (ADR-017): UAT sign-off gating never parses the
+    // ROADMAP projection. Without a DB we cannot verify — stop conservatively.
+    if (!isDbAvailable()) {
+      return {
+        action: "stop",
+        reason: `Cannot complete milestone ${mid}: unable to verify UAT verdicts because the workflow DB is not accessible.`,
+        level: "warning",
+      };
     }
-
-    for (const sliceId of closedSliceIds) {
+    for (const sliceId of getClosedSliceIds(mid)) {
       const result = await readUatGateVerdict(basePath, mid, sliceId);
       if (!result) {
         return {
           action: "stop",
-          reason: `Cannot complete milestone ${mid}: missing UAT PASS verdict for ${sliceId}. Manual UAT sign-off (PASS) is required before milestone closure.`,
+          reason: uatSignoffBlockerGuidance(mid, sliceId),
           level: "warning",
         };
       }
@@ -118,7 +203,7 @@ export async function evaluateCompleteMilestoneDispatch(
       if (!isAcceptableUatVerdict(verdict, uatType)) {
         return {
           action: "stop",
-          reason: `Cannot complete milestone ${mid}: UAT verdict for ${sliceId} is "${verdict}". Manual UAT sign-off (PASS) is required before milestone closure.`,
+          reason: uatSignoffBlockerGuidance(mid, sliceId, verdict),
           level: "warning",
         };
       }

package/src/resources/extensions/gsd/model-cost-table.ts

@@ -25,6 +25,7 @@ export const BUNDLED_COST_TABLE: ModelCostEntry[] = [
   { 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/src/resources/extensions/gsd/model-router.ts

@@ -101,6 +101,7 @@ export const MODEL_CAPABILITY_TIER: Record<string, ComplexityTier> = {
   "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",
@@ -129,6 +130,7 @@ const MODEL_COST_PER_1K_INPUT: Record<string, number> = {
   "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,
@@ -164,6 +166,7 @@ export const MODEL_CAPABILITY_PROFILES: Record<string, ModelCapabilities> = {
   "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/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/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/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);