gsd-pi 2.35.0-dev.cd3b7ea → 2.36.0

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

@@ -66,32 +66,24 @@ import { toPosixPath } from "../shared/mod.js";
 import { isParallelActive, shutdownParallel } from "./parallel-orchestrator.js";
 import { DEFAULT_BASH_TIMEOUT_SECS } from "./constants.js";
 
-// ── Agent Instructions ────────────────────────────────────────────────────
-// Lightweight "always follow" files injected into every GSD agent session.
-// Global: ~/.gsd/agent-instructions.md   Project: .gsd/agent-instructions.md
-// Both are loaded and concatenated (global first, project appends).
-
-function loadAgentInstructions(): string | null {
-  const parts: string[] = [];
-
-  const globalPath = join(homedir(), ".gsd", "agent-instructions.md");
-  if (existsSync(globalPath)) {
-    try {
-      const content = readFileSync(globalPath, "utf-8").trim();
-      if (content) parts.push(content);
-    } catch { /* non-fatal — skip unreadable file */ }
-  }
-
-  const projectPath = join(process.cwd(), ".gsd", "agent-instructions.md");
-  if (existsSync(projectPath)) {
-    try {
-      const content = readFileSync(projectPath, "utf-8").trim();
-      if (content) parts.push(content);
-    } catch { /* non-fatal — skip unreadable file */ }
+// ── Agent Instructions (DEPRECATED) ──────────────────────────────────────
+// agent-instructions.md is deprecated. Use AGENTS.md or CLAUDE.md instead.
+// Pi core natively supports AGENTS.md (with CLAUDE.md fallback) per directory.
+
+function warnDeprecatedAgentInstructions(): void {
+  const paths = [
+    join(homedir(), ".gsd", "agent-instructions.md"),
+    join(process.cwd(), ".gsd", "agent-instructions.md"),
+  ];
+  for (const p of paths) {
+    if (existsSync(p)) {
+      console.warn(
+        `[GSD] DEPRECATED: ${p} is no longer loaded. ` +
+        `Migrate your instructions to AGENTS.md (or CLAUDE.md) in the same directory. ` +
+        `See https://github.com/gsd-build/GSD-2/issues/1492`,
+      );
+    }
   }
-
-  if (parts.length === 0) return null;
-  return parts.join("\n\n");
 }
 
 // ── Depth verification state ──────────────────────────────────────────────
@@ -175,7 +167,16 @@ export default function (pi: ExtensionAPI) {
         // Pipe closed — nothing we can write; just exit cleanly
         process.exit(0);
       }
-      // Re-throw anything that isn't EPIPE so real crashes still surface
+      if ((err as NodeJS.ErrnoException).code === "ENOENT" &&
+          (err as any).syscall?.startsWith("spawn")) {
+        // spawn ENOENT — command not found (e.g., npx on Windows).
+        // This surfaces as an uncaught exception from child_process but
+        // is not a fatal process error. Log and continue instead of
+        // crashing auto-mode (#1384).
+        process.stderr.write(`[gsd] spawn ENOENT: ${(err as any).path ?? "unknown"} — command not found\n`);
+        return;
+      }
+      // Re-throw anything that isn't EPIPE/ENOENT so real crashes still surface
       throw err;
     };
     process.on("uncaughtException", _gsdEpipeGuard);
@@ -673,12 +674,8 @@ export default function (pi: ExtensionAPI) {
       }
     }
 
-    // Load agent instructions (global + project)
-    let agentInstructionsBlock = "";
-    const agentInstructions = loadAgentInstructions();
-    if (agentInstructions) {
-      agentInstructionsBlock = `\n\n## Agent Instructions\n\nThe following instructions were provided by the user and must be followed in every session:\n\n${agentInstructions}`;
-    }
+    // Warn if deprecated agent-instructions.md files are still present
+    warnDeprecatedAgentInstructions();
 
     const injection = await buildGuidedExecuteContextInjection(event.prompt, process.cwd());
 
@@ -723,7 +720,7 @@ export default function (pi: ExtensionAPI) {
       ].join("\n");
     }
 
-    const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${agentInstructionsBlock}${knowledgeBlock}${memoryBlock}${newSkillsBlock}${worktreeBlock}`;
+    const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${memoryBlock}${newSkillsBlock}${worktreeBlock}`;
     stopContextTimer({
       systemPromptSize: fullSystem.length,
       injectionSize: injection?.length ?? 0,

package/src/resources/extensions/gsd/migrate-external.ts

@@ -6,10 +6,11 @@
  * symlink replaces the original directory so all paths remain valid.
  */
 
-import { existsSync, lstatSync, mkdirSync, readdirSync, renameSync, cpSync, rmSync, symlinkSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, renameSync, cpSync, rmSync, symlinkSync } from "node:fs";
 import { join } from "node:path";
 import { externalGsdRoot } from "./repo-identity.js";
 import { getErrorMessage } from "./error-utils.js";
+import { hasGitTrackedGsdFiles } from "./gitignore.js";
 
 export interface MigrationResult {
   migrated: boolean;
@@ -51,6 +52,28 @@ export function migrateToExternalState(basePath: string): MigrationResult {
     return { migrated: false, error: `Cannot stat .gsd: ${getErrorMessage(err)}` };
   }
 
+  // Skip if .gsd/ contains git-tracked files — the project intentionally
+  // keeps .gsd/ in version control and migration would destroy that.
+  if (hasGitTrackedGsdFiles(basePath)) {
+    return { migrated: false };
+  }
+
+  // Skip if .gsd/worktrees/ has active worktree directories (#1337).
+  // On Windows, active git worktrees hold OS-level directory handles that
+  // prevent rename/delete. Attempting migration causes EBUSY and data loss.
+  const worktreesDir = join(localGsd, "worktrees");
+  if (existsSync(worktreesDir)) {
+    try {
+      const entries = readdirSync(worktreesDir, { withFileTypes: true });
+      if (entries.some(e => e.isDirectory())) {
+        return { migrated: false };
+      }
+    } catch {
+      // Can't read worktrees dir — skip migration to be safe
+      return { migrated: false };
+    }
+  }
+
   const externalPath = externalGsdRoot(basePath);
   const migratingPath = join(basePath, ".gsd.migrating");
 
@@ -99,7 +122,29 @@ export function migrateToExternalState(basePath: string): MigrationResult {
     // Create symlink .gsd -> external path
     symlinkSync(externalPath, localGsd, "junction");
 
-    // Remove .gsd.migrating
+    // Verify the symlink resolves correctly before removing the backup (#1377).
+    // On Windows, junction creation can silently succeed but resolve to the wrong
+    // target, or the external dir may not be accessible. If verification fails,
+    // restore from the backup.
+    try {
+      const resolved = realpathSync(localGsd);
+      const resolvedExternal = realpathSync(externalPath);
+      if (resolved !== resolvedExternal) {
+        // Symlink points to wrong target — restore backup
+        try { rmSync(localGsd, { force: true }); } catch { /* may not exist */ }
+        renameSync(migratingPath, localGsd);
+        return { migrated: false, error: `Migration verification failed: symlink resolves to ${resolved}, expected ${resolvedExternal}` };
+      }
+      // Verify we can read through the symlink
+      readdirSync(localGsd);
+    } catch (verifyErr) {
+      // Symlink broken or unreadable — restore backup
+      try { rmSync(localGsd, { force: true }); } catch { /* may not exist */ }
+      try { renameSync(migratingPath, localGsd); } catch { /* best-effort restore */ }
+      return { migrated: false, error: `Migration verification failed: ${getErrorMessage(verifyErr)}` };
+    }
+
+    // Remove .gsd.migrating only after symlink is verified
     rmSync(migratingPath, { recursive: true, force: true });
 
     return { migrated: true };

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

@@ -80,8 +80,9 @@ export function findMilestoneIds(basePath: string): string[] {
       .filter((d) => d.isDirectory())
       .map((d) => {
         const match = d.name.match(/^(M\d+(?:-[a-z0-9]{6})?)/);
-        return match ? match[1] : d.name;
-      });
+        return match ? match[1] : null;
+      })
+      .filter((id): id is string => id !== null);
 
     // Apply custom queue order if available, else fall back to numeric sort
     const customOrder = loadQueueOrder(basePath);

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

@@ -10,7 +10,8 @@
  */
 
 import { readdirSync, existsSync, realpathSync, Dirent } from "node:fs";
-import { join } from "node:path";
+import { join, dirname, normalize } from "node:path";
+import { spawnSync } from "node:child_process";
 import { nativeScanGsdTree, type GsdTreeEntry } from "./native-parser-bridge.js";
 import { DIR_CACHE_MAX } from "./constants.js";
 
@@ -277,15 +278,80 @@ const LEGACY_GSD_ROOT_FILES: Record<GSDRootFileKey, string> = {
   KNOWLEDGE: "knowledge.md",
 };
 
+// ─── GSD Root Discovery ───────────────────────────────────────────────────────
+
+const gsdRootCache = new Map<string, string>();
+
+/** Exported for tests only — do not call in production code. */
+export function _clearGsdRootCache(): void {
+  gsdRootCache.clear();
+}
+
+/**
+ * Resolve the `.gsd` directory for a given project base path.
+ *
+ * Probe order:
+ *   1. basePath/.gsd         — fast path (common case)
+ *   2. git rev-parse root    — handles cwd-is-a-subdirectory
+ *   3. Walk up from basePath — handles moved .gsd in an ancestor (bounded by git root)
+ *   4. basePath/.gsd         — creation fallback (init scenario)
+ *
+ * Result is cached per basePath for the process lifetime.
+ */
 export function gsdRoot(basePath: string): string {
-  const local = join(basePath, ".gsd");
-  try {
-    const resolved = realpathSync(local);
-    if (resolved !== local) return resolved; // symlink resolved
-  } catch { /* doesn't exist yet — fall through */ }
-  return local; // backwards compat: unmigrated projects
+  const cached = gsdRootCache.get(basePath);
+  if (cached) return cached;
+
+  const result = probeGsdRoot(basePath);
+  gsdRootCache.set(basePath, result);
+  return result;
 }
 
+function probeGsdRoot(rawBasePath: string): string {
+  // 1. Fast path — check the input path directly
+  const local = join(rawBasePath, ".gsd");
+  if (existsSync(local)) return local;
+
+  // Resolve symlinks so path comparisons work correctly across platforms
+  // (e.g. macOS /var → /private/var). Use rawBasePath as fallback if not resolvable.
+  let basePath: string;
+  try { basePath = realpathSync.native(rawBasePath); } catch { basePath = rawBasePath; }
+
+  // 2. Git root anchor — used as both probe target and walk-up boundary
+  //    Only walk if we're inside a git project — prevents escaping into
+  //    unrelated filesystem territory when running outside any repo.
+  let gitRoot: string | null = null;
+  try {
+    const out = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd: basePath,
+      encoding: "utf-8",
+    });
+    if (out.status === 0) {
+      const r = out.stdout.trim();
+      if (r) gitRoot = normalize(r);
+    }
+  } catch { /* git not available */ }
+
+  if (gitRoot) {
+    const candidate = join(gitRoot, ".gsd");
+    if (existsSync(candidate)) return candidate;
+  }
+
+  // 3. Walk up from basePath to the git root (only if we are in a subdirectory)
+  if (gitRoot && basePath !== gitRoot) {
+    let cur = dirname(basePath);
+    while (cur !== basePath) {
+      const candidate = join(cur, ".gsd");
+      if (existsSync(candidate)) return candidate;
+      if (cur === gitRoot) break;
+      basePath = cur;
+      cur = dirname(cur);
+    }
+  }
+
+  // 4. Fallback for init/creation
+  return local;
+}
 export function milestonesDir(basePath: string): string {
   return join(gsdRoot(basePath), "milestones");
 }

package/src/resources/extensions/gsd/post-unit-hooks.ts

@@ -149,11 +149,15 @@ function dequeueNextHook(basePath: string): HookDispatchResult | null {
 
     // Build the prompt with variable substitution
     const [mid, sid, tid] = triggerUnitId.split("/");
-    const prompt = config.prompt
+    let prompt = config.prompt
       .replace(/\{milestoneId\}/g, mid ?? "")
       .replace(/\{sliceId\}/g, sid ?? "")
       .replace(/\{taskId\}/g, tid ?? "");
 
+    // Inject browser safety instruction for hooks that may use browser tools (#1345).
+    // Vite HMR and other persistent connections prevent networkidle from resolving.
+    prompt += "\n\n**Browser tool safety:** Do NOT use `browser_wait_for` with `condition: \"network_idle\"` — it hangs indefinitely when dev servers keep persistent connections (Vite HMR, WebSocket). Use `selector_visible`, `text_visible`, or `delay` instead.";
+
     return {
       hookName: config.name,
       prompt,

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

@@ -33,9 +33,24 @@ export function validatePreferences(preferences: GSDPreferences): {
   const validated: GSDPreferences = {};
 
   // ─── Unknown Key Detection ──────────────────────────────────────────
+  // Common key migration hints for pi-level settings that don't map to GSD prefs
+  const KEY_MIGRATION_HINTS: Record<string, string> = {
+    taskIsolation: 'use "git.isolation" instead (values: worktree, branch, none)',
+    task_isolation: 'use "git.isolation" instead (values: worktree, branch, none)',
+    isolation: 'use "git.isolation" instead (values: worktree, branch, none)',
+    manage_gitignore: 'use "git.manage_gitignore" instead',
+    auto_push: 'use "git.auto_push" instead',
+    main_branch: 'use "git.main_branch" instead',
+  };
+
   for (const key of Object.keys(preferences)) {
     if (!KNOWN_PREFERENCE_KEYS.has(key)) {
-      warnings.push(`unknown preference key "${key}" — ignored`);
+      const hint = KEY_MIGRATION_HINTS[key];
+      if (hint) {
+        warnings.push(`unknown preference key "${key}" — ${hint}`);
+      } else {
+        warnings.push(`unknown preference key "${key}" — ignored`);
+      }
     }
   }
 

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

@@ -15,9 +15,10 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { parse as parseYaml } from "yaml";
-import type { PostUnitHookConfig, PreDispatchHookConfig } from "./types.js";
+import type { PostUnitHookConfig, PreDispatchHookConfig, TokenProfile } from "./types.js";
 import type { DynamicRoutingConfig } from "./model-router.js";
 import { normalizeStringArray } from "../shared/mod.js";
+import { resolveProfileDefaults as _resolveProfileDefaults } from "./preferences-models.js";
 
 import {
   MODE_DEFAULTS,
@@ -141,6 +142,18 @@ export function loadEffectiveGSDPreferences(): LoadedGSDPreferences | null {
     };
   }
 
+  // Apply token-profile defaults as the lowest-priority layer so that
+  // `token_profile: budget` sets models and phase-skips automatically.
+  // Explicit user preferences always override profile defaults.
+  const profile = result.preferences.token_profile as TokenProfile | undefined;
+  if (profile) {
+    const profileDefaults = _resolveProfileDefaults(profile);
+    result = {
+      ...result,
+      preferences: mergePreferences(profileDefaults as GSDPreferences, result.preferences),
+    };
+  }
+
   // Apply mode defaults as the lowest-priority layer
   if (result.preferences.mode) {
     result = {

package/src/resources/extensions/gsd/prompts/complete-milestone.md

@@ -28,6 +28,8 @@ Then:
 
 **Important:** Do NOT skip the success criteria and definition of done verification (steps 3-4). The milestone summary must reflect actual verified outcomes, not assumed success. If any criterion was not met, document it clearly in the summary and do not mark the milestone as passing verification.
 
+**File system safety:** When scanning milestone directories for evidence, use `ls` or `find` to list directory contents first — never pass a directory path (e.g. `tasks/`, `slices/`) directly to the `read` tool. The `read` tool only accepts file paths, not directories.
+
 **You MUST write `{{milestoneSummaryPath}}` AND update PROJECT.md before finishing.**
 
 When done, say: "Milestone {{milestoneId}} complete."

package/src/resources/extensions/gsd/prompts/validate-milestone.md

@@ -67,4 +67,6 @@ If verdict is `needs-remediation`:
 
 **You MUST write `{{validationPath}}` before finishing.**
 
+**File system safety:** When scanning milestone directories for evidence, use `ls` or `find` to list directory contents first — never pass a directory path (e.g. `tasks/`, `slices/`) directly to the `read` tool. The `read` tool only accepts file paths, not directories.
+
 When done, say: "Milestone {{milestoneId}} validation complete — verdict: <verdict>."

package/src/resources/extensions/gsd/roadmap-mutations.ts

@@ -0,0 +1,66 @@
+/**
+ * Roadmap Mutations — shared utilities for modifying roadmap checkbox state.
+ *
+ * Extracts the duplicated "flip slice checkbox" pattern that existed in
+ * doctor.ts, mechanical-completion.ts, and auto-recovery.ts.
+ */
+
+import { readFileSync } from "node:fs";
+import { atomicWriteSync } from "./atomic-write.js";
+import { resolveMilestoneFile } from "./paths.js";
+import { clearParseCache } from "./files.js";
+
+/**
+ * Mark a slice as done ([x]) in the milestone roadmap.
+ * Idempotent — no-op if already checked or if the slice isn't found.
+ *
+ * @returns true if the roadmap was modified, false if no change was needed
+ */
+export function markSliceDoneInRoadmap(basePath: string, mid: string, sid: string): boolean {
+  const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
+  if (!roadmapFile) return false;
+
+  let content: string;
+  try {
+    content = readFileSync(roadmapFile, "utf-8");
+  } catch {
+    return false;
+  }
+
+  const updated = content.replace(
+    new RegExp(`^(\\s*-\\s+)\\[ \\]\\s+\\*\\*${sid}:`, "m"),
+    `$1[x] **${sid}:`,
+  );
+
+  if (updated === content) return false;
+
+  atomicWriteSync(roadmapFile, updated);
+  clearParseCache();
+  return true;
+}
+
+/**
+ * Mark a task as done ([x]) in the slice plan.
+ * Idempotent — no-op if already checked or if the task isn't found.
+ *
+ * @returns true if the plan was modified, false if no change was needed
+ */
+export function markTaskDoneInPlan(basePath: string, planPath: string, tid: string): boolean {
+  let content: string;
+  try {
+    content = readFileSync(planPath, "utf-8");
+  } catch {
+    return false;
+  }
+
+  const updated = content.replace(
+    new RegExp(`^(\\s*-\\s+)\\[ \\]\\s+\\*\\*${tid}:`, "m"),
+    `$1[x] **${tid}:`,
+  );
+
+  if (updated === content) return false;
+
+  atomicWriteSync(planPath, updated);
+  clearParseCache();
+  return true;
+}

package/src/resources/extensions/gsd/session-lock.ts

@@ -57,9 +57,19 @@ let _lockCompromised: boolean = false;
 /** Whether we've already registered a process.on('exit') handler. */
 let _exitHandlerRegistered: boolean = false;
 
+/** Snapshotted lock file path — captured at acquireSessionLock time to avoid
+ *  gsdRoot() resolving differently in worktree vs project root contexts (#1363). */
+let _snapshotLockPath: string | null = null;
+
+/** Timestamp when the session lock was acquired — used to detect false-positive
+ *  onCompromised events from event loop stalls within the stale window (#1362). */
+let _lockAcquiredAt: number = 0;
+
 const LOCK_FILE = "auto.lock";
 
 function lockPath(basePath: string): string {
+  // If we have a snapshotted path from acquisition, use it for consistency
+  if (_snapshotLockPath) return _snapshotLockPath;
   return join(gsdRoot(basePath), LOCK_FILE);
 }
 
@@ -198,8 +208,19 @@ export function acquireSessionLock(basePath: string): SessionLockResult {
       onCompromised: () => {
         // proper-lockfile detected mtime drift (system sleep, event loop stall, etc.).
         // Default handler throws inside setTimeout — an uncaught exception that crashes
-        // or corrupts process state. Instead, set a flag so validateSessionLock() can
-        // detect the compromise gracefully on the next dispatch cycle.
+        // or corrupts process state.
+        //
+        // False-positive suppression (#1362): If we're still within the stale window
+        // (30 min since acquisition), the mtime mismatch is from an event loop stall
+        // during a long LLM call — not a real takeover. Log and continue.
+        const elapsed = Date.now() - _lockAcquiredAt;
+        if (elapsed < 1_800_000) {
+          process.stderr.write(
+            `[gsd] Lock heartbeat mismatch after ${Math.round(elapsed / 1000)}s — event loop stall, continuing.\n`,
+          );
+          return; // Suppress false positive
+        }
+        // Past the stale window — this is a real compromise
         _lockCompromised = true;
         _releaseFunction = null;
       },
@@ -209,6 +230,8 @@ export function acquireSessionLock(basePath: string): SessionLockResult {
     _lockedPath = basePath;
     _lockPid = process.pid;
     _lockCompromised = false;
+    _lockAcquiredAt = Date.now();
+    _snapshotLockPath = lp; // Snapshot the resolved path for consistent access (#1363)
 
     // Safety net: clean up lock dir on process exit if _releaseFunction
     // wasn't called (e.g., normal exit after clean completion) (#1245).
@@ -237,6 +260,16 @@ export function acquireSessionLock(basePath: string): SessionLockResult {
           stale: 1_800_000, // 30 minutes — match primary lock settings
           update: 10_000,
           onCompromised: () => {
+            // Same false-positive suppression as the primary lock (#1512).
+            // Without this, the retry path fires _lockCompromised unconditionally
+            // on benign mtime drift (laptop sleep, heavy LLM event loop stalls).
+            const elapsed = Date.now() - _lockAcquiredAt;
+            if (elapsed < 1_800_000) {
+              process.stderr.write(
+                `[gsd] Lock heartbeat mismatch after ${Math.round(elapsed / 1000)}s — event loop stall, continuing.\n`,
+              );
+              return;
+            }
             _lockCompromised = true;
             _releaseFunction = null;
           },
@@ -245,6 +278,8 @@ export function acquireSessionLock(basePath: string): SessionLockResult {
         _lockedPath = basePath;
         _lockPid = process.pid;
         _lockCompromised = false;
+        _lockAcquiredAt = Date.now();
+        _snapshotLockPath = lp; // Snapshot for retry path too (#1363)
 
         // Safety net — uses centralized handler to avoid double-registration
         ensureExitHandler(gsdDir);
@@ -336,6 +371,26 @@ export function updateSessionLock(
 export function validateSessionLock(basePath: string): boolean {
   // Lock was compromised by proper-lockfile (mtime drift from sleep, stall, etc.)
   if (_lockCompromised) {
+    // Recovery gate (#1512): Before declaring the lock lost, check if the lock
+    // file still contains our PID. If it does, no other process took over — the
+    // onCompromised fired from benign mtime drift (laptop sleep, event loop stall
+    // beyond the stale window). Attempt re-acquisition instead of giving up.
+    const lp = lockPath(basePath);
+    const existing = readExistingLockData(lp);
+    if (existing && existing.pid === process.pid) {
+      // Lock file still ours — try to re-acquire the OS lock
+      try {
+        const result = acquireSessionLock(basePath);
+        if (result.acquired) {
+          process.stderr.write(
+            `[gsd] Lock recovered after onCompromised — lock file PID matched, re-acquired.\n`,
+          );
+          return true;
+        }
+      } catch {
+        // Re-acquisition failed — fall through to return false
+      }
+    }
     return false;
   }
 
@@ -394,6 +449,8 @@ export function releaseSessionLock(basePath: string): void {
   _lockedPath = null;
   _lockPid = 0;
   _lockCompromised = false;
+  _lockAcquiredAt = 0;
+  _snapshotLockPath = null;
 }
 
 /**

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

@@ -64,11 +64,12 @@ export function isValidationTerminal(validationContent: string): boolean {
   if (!match) return false;
   const verdict = match[1].match(/verdict:\s*(\S+)/);
   if (!verdict) return false;
+  const v = verdict[1] === 'passed' ? 'pass' : verdict[1];
   // 'pass' and 'needs-attention' are always terminal.
   // 'needs-remediation' is treated as terminal to prevent infinite loops
   // when no remediation slices exist in the roadmap (#832). The validation
   // report is preserved on disk for manual review.
-  return verdict[1] === 'pass' || verdict[1] === 'needs-attention' || verdict[1] === 'needs-remediation';
+  return v === 'pass' || v === 'needs-attention' || v === 'needs-remediation';
 }
 
 // ─── State Derivation ──────────────────────────────────────────────────────

package/src/resources/extensions/gsd/templates/plan.md

@@ -113,6 +113,14 @@
   - Tasks execute sequentially in order (T01, T02, T03, ...)
   - est: is informational (e.g. 30m, 1h, 2h) and optional
 
+  Verify field rules:
+  - MUST be a mechanically executable command: `npm test`, `grep -q "pattern" file`, `test -f path`
+  - For content/document tasks: verify file existence, section count, YAML validity, or word count
+    NOT exact phrasing, specific formulas, or "zero TBD" aspirational criteria
+  - If no command can verify the output, write: "Manual review — file exists and is non-empty"
+  - BAD: "Sections 3.1 and 3.2 exist with exact formulas. Zero TBD/TODO."
+  - GOOD: `grep -c "^## " doc.md` returns >= 4 (4+ sections), `! grep -q "TBD\|TODO" doc.md`
+
   Integration closure rule:
   - At least one slice in any multi-boundary milestone should perform real composition/wiring, not just contract hardening
   - For the final assembly slice, verification must exercise the real entrypoint or runtime path

package/src/resources/extensions/gsd/tests/commands-inspect-open-db.test.ts

@@ -0,0 +1,46 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs";
+
+import { handleInspect } from "../commands-inspect.ts";
+import { closeDatabase, openDatabase } from "../gsd-db.ts";
+
+test("/gsd inspect opens existing database when it was not yet opened in session", async () => {
+  closeDatabase();
+
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "gsd-inspect-db-"));
+  const prevCwd = process.cwd();
+
+  try {
+    const gsdDir = path.join(tmp, ".gsd");
+    fs.mkdirSync(gsdDir, { recursive: true });
+    const dbPath = path.join(gsdDir, "gsd.db");
+
+    assert.equal(openDatabase(dbPath), true);
+    closeDatabase();
+
+    process.chdir(tmp);
+
+    const notifications: Array<{ message: string; level: string }> = [];
+    const ctx = {
+      ui: {
+        notify(message: string, level: string) {
+          notifications.push({ message, level });
+        },
+      },
+    } as any;
+
+    await handleInspect(ctx);
+
+    assert.equal(notifications.length, 1);
+    assert.equal(notifications[0].level, "info");
+    assert.match(notifications[0].message, /=== GSD Database Inspect ===/);
+    assert.doesNotMatch(notifications[0].message, /No GSD database available/);
+  } finally {
+    process.chdir(prevCwd);
+    closeDatabase();
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/files-loadfile-eisdir.test.ts

@@ -0,0 +1,20 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs";
+
+import { loadFile } from "../files.ts";
+
+test("loadFile returns null for directory paths instead of throwing EISDIR", async () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "gsd-loadfile-eisdir-"));
+  const dirPath = path.join(tmp, "tasks");
+  fs.mkdirSync(dirPath);
+
+  try {
+    const result = await loadFile(dirPath);
+    assert.equal(result, null);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});