gsd-pi 2.63.0 → 2.64.0-dev.9c14bd0

package/dist/resources/extensions/gsd/pre-execution-checks.js

@@ -0,0 +1,464 @@
+/**
+ * Pre-Execution Checks — Validate task plans before execution begins.
+ *
+ * Runs these checks against a slice's task plan:
+ *   1. Package existence — npm view calls in parallel with timeout
+ *   2. File path consistency — verify files exist or are in prior expected_output
+ *   3. Task ordering — detect impossible ordering (task reads file created later)
+ *   4. Interface contracts — detect contradictory function signatures (warn only)
+ *
+ * Design principles:
+ *   - Pure functions taking (tasks: TaskRow[], basePath: string) for testability
+ *   - Network failures warn, don't fail (R012 conservative design)
+ *   - Total execution <2s target (R013)
+ *   - No AST parsers — interface parsing is heuristic (regex on code blocks)
+ */
+import { existsSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { resolve } from "node:path";
+// ─── Package Existence Check ─────────────────────────────────────────────────
+/**
+ * Extract npm package names from task descriptions.
+ * Looks for:
+ *   - `npm install <pkg>` patterns
+ *   - Code blocks with `require('<pkg>')` or `import ... from '<pkg>'`
+ *   - Explicit mentions like "uses lodash" or "package: axios"
+ */
+export function extractPackageReferences(description) {
+    const packages = new Set();
+    // Common words that aren't package names but might appear after install
+    const stopwords = new Set([
+        "then", "and", "the", "to", "a", "an", "in", "for", "with", "from", "or",
+        "npm", "yarn", "pnpm", "i", // Don't capture the command itself
+    ]);
+    // npm install <pkg> patterns (handles npm i, npm add, yarn add, pnpm add)
+    // Use a global pattern to find all install commands, then parse following tokens
+    const installCmdPattern = /(?:npm\s+(?:install|i|add)|yarn\s+add|pnpm\s+add)\s+/g;
+    let cmdMatch;
+    while ((cmdMatch = installCmdPattern.exec(description)) !== null) {
+        // Start after the install command
+        const afterCmd = description.slice(cmdMatch.index + cmdMatch[0].length);
+        // Match package-like tokens (alphanumeric, @, /, -, _) until we hit
+        // something that's not a package (non-token char after whitespace)
+        const tokenPattern = /^([@a-zA-Z][a-zA-Z0-9@/_-]*)(?:\s+|$)/;
+        let remaining = afterCmd;
+        while (remaining.length > 0) {
+            // Skip any flags like -D, --save-dev
+            const flagMatch = remaining.match(/^(-[a-zA-Z-]+)\s*/);
+            if (flagMatch) {
+                remaining = remaining.slice(flagMatch[0].length);
+                continue;
+            }
+            // Try to match a package name
+            const pkgMatch = remaining.match(tokenPattern);
+            if (pkgMatch) {
+                const token = pkgMatch[1];
+                // Skip stopwords - they indicate end of package list
+                if (stopwords.has(token.toLowerCase())) {
+                    break;
+                }
+                packages.add(normalizePackageName(token));
+                remaining = remaining.slice(pkgMatch[0].length);
+            }
+            else {
+                // Not a package name, stop parsing this install command
+                break;
+            }
+        }
+    }
+    // require('pkg') or import from 'pkg' in code blocks
+    const importPattern = /(?:require\s*\(\s*['"]|from\s+['"])([a-zA-Z0-9@/_-]+)['"\)]/g;
+    let importMatch;
+    while ((importMatch = importPattern.exec(description)) !== null) {
+        // Skip relative imports and node builtins
+        const pkg = importMatch[1];
+        if (!pkg.startsWith(".") && !pkg.startsWith("node:")) {
+            packages.add(normalizePackageName(pkg));
+        }
+    }
+    return Array.from(packages);
+}
+/**
+ * Normalize package name to registry-checkable form.
+ * Handles scoped packages (@org/pkg) and subpaths (pkg/subpath → pkg).
+ */
+function normalizePackageName(raw) {
+    // Scoped package: @org/pkg or @org/pkg/subpath
+    if (raw.startsWith("@")) {
+        const parts = raw.split("/");
+        return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : raw;
+    }
+    // Regular package: pkg or pkg/subpath
+    return raw.split("/")[0];
+}
+/**
+ * Check if a package exists on npm registry.
+ * Returns null on success, error message on failure.
+ * Times out after timeoutMs (default 5000ms).
+ */
+async function checkPackageOnNpm(packageName, timeoutMs = 5000) {
+    return new Promise((resolve) => {
+        const child = spawn("npm", ["view", packageName, "name"], {
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: timeoutMs,
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (data) => {
+            stdout += data.toString();
+        });
+        child.stderr.on("data", (data) => {
+            stderr += data.toString();
+        });
+        const timer = setTimeout(() => {
+            child.kill("SIGTERM");
+            resolve({ exists: false, error: `Timeout after ${timeoutMs}ms` });
+        }, timeoutMs);
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (code === 0 && stdout.trim()) {
+                resolve({ exists: true });
+            }
+            else if (stderr.includes("404") || stderr.includes("not found")) {
+                resolve({ exists: false, error: `Package not found: ${packageName}` });
+            }
+            else if (code !== 0) {
+                // Network error or other issue — warn, don't fail
+                resolve({ exists: true, error: `npm view failed (code ${code}): ${stderr.slice(0, 100)}` });
+            }
+            else {
+                resolve({ exists: true });
+            }
+        });
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            resolve({ exists: true, error: `npm spawn error: ${err.message}` });
+        });
+    });
+}
+/**
+ * Check all package references in tasks for existence on npm.
+ * Runs checks in parallel with a 5s timeout per package.
+ * Network failures warn but don't fail (R012 conservative design).
+ */
+export async function checkPackageExistence(tasks, _basePath) {
+    const results = [];
+    const packagesToCheck = new Set();
+    // Collect all package references from task descriptions
+    for (const task of tasks) {
+        const packages = extractPackageReferences(task.description);
+        for (const pkg of packages) {
+            packagesToCheck.add(pkg);
+        }
+    }
+    if (packagesToCheck.size === 0) {
+        return results;
+    }
+    // Check packages in parallel
+    const checkPromises = Array.from(packagesToCheck).map(async (pkg) => {
+        const result = await checkPackageOnNpm(pkg);
+        return { pkg, result };
+    });
+    const checkResults = await Promise.all(checkPromises);
+    for (const { pkg, result } of checkResults) {
+        if (!result.exists && !result.error?.includes("Timeout") && !result.error?.includes("spawn error")) {
+            // Package genuinely doesn't exist — blocking failure
+            results.push({
+                category: "package",
+                target: pkg,
+                passed: false,
+                message: result.error || `Package '${pkg}' not found on npm`,
+                blocking: true,
+            });
+        }
+        else if (result.error) {
+            // Network issue or timeout — warn but don't block
+            results.push({
+                category: "package",
+                target: pkg,
+                passed: true,
+                message: `Warning: ${result.error}`,
+                blocking: false,
+            });
+        }
+        // Silent success for existing packages — no need to report
+    }
+    return results;
+}
+// ─── File Path Consistency Check ─────────────────────────────────────────────
+/**
+ * Normalize a file path for consistent comparison.
+ * - Strips leading ./
+ * - Normalizes path separators to forward slashes
+ * - Resolves redundant segments (e.g., foo/../bar → bar)
+ *
+ * This ensures that "./src/a.ts", "src/a.ts", and "src//a.ts" all compare equal.
+ */
+export function normalizeFilePath(filePath) {
+    if (!filePath)
+        return filePath;
+    // Normalize path separators to forward slashes
+    let normalized = filePath.replace(/\\/g, "/");
+    // Remove leading ./
+    while (normalized.startsWith("./")) {
+        normalized = normalized.slice(2);
+    }
+    // Remove duplicate slashes
+    normalized = normalized.replace(/\/+/g, "/");
+    // Remove trailing slash unless it's the root
+    if (normalized.length > 1 && normalized.endsWith("/")) {
+        normalized = normalized.slice(0, -1);
+    }
+    return normalized;
+}
+/**
+ * Build a set of files that will be created by tasks up to (but not including) taskIndex.
+ * All paths are normalized for consistent comparison.
+ */
+function getExpectedOutputsUpTo(tasks, taskIndex) {
+    const outputs = new Set();
+    for (let i = 0; i < taskIndex; i++) {
+        for (const file of tasks[i].expected_output) {
+            outputs.add(normalizeFilePath(file));
+        }
+    }
+    return outputs;
+}
+/**
+ * Check that all files referenced in task.files and task.inputs either:
+ *   1. Exist on disk, OR
+ *   2. Are in a prior task's expected_output
+ *
+ * All paths are normalized before comparison to ensure ./src/a.ts matches src/a.ts.
+ */
+export function checkFilePathConsistency(tasks, basePath) {
+    const results = [];
+    for (let i = 0; i < tasks.length; i++) {
+        const task = tasks[i];
+        const priorOutputs = getExpectedOutputsUpTo(tasks, i);
+        const filesToCheck = [...task.files, ...task.inputs];
+        for (const file of filesToCheck) {
+            // Skip empty strings
+            if (!file.trim())
+                continue;
+            // Normalize path for consistent comparison
+            const normalizedFile = normalizeFilePath(file);
+            // Check if file exists on disk
+            const absolutePath = resolve(basePath, normalizedFile);
+            const existsOnDisk = existsSync(absolutePath);
+            // Check if file is in prior expected outputs (priorOutputs already normalized)
+            const inPriorOutputs = priorOutputs.has(normalizedFile);
+            if (!existsOnDisk && !inPriorOutputs) {
+                results.push({
+                    category: "file",
+                    target: file,
+                    passed: false,
+                    message: `Task ${task.id} references '${file}' which doesn't exist and isn't created by prior tasks`,
+                    blocking: true,
+                });
+            }
+        }
+    }
+    return results;
+}
+// ─── Task Ordering Check ─────────────────────────────────────────────────────
+/**
+ * Detect impossible task ordering: task N reads a file that task N+M creates.
+ * This is a fatal error — the plan has an impossible dependency.
+ *
+ * All paths are normalized before comparison to ensure ./src/a.ts matches src/a.ts.
+ */
+export function checkTaskOrdering(tasks, _basePath) {
+    const results = [];
+    // Build map: normalized file → task index that creates it
+    const fileCreators = new Map();
+    for (let i = 0; i < tasks.length; i++) {
+        const task = tasks[i];
+        for (const file of task.expected_output) {
+            const normalizedFile = normalizeFilePath(file);
+            if (!fileCreators.has(normalizedFile)) {
+                fileCreators.set(normalizedFile, { taskId: task.id, index: i, originalPath: file });
+            }
+        }
+    }
+    // Check each task's inputs against file creators
+    for (let i = 0; i < tasks.length; i++) {
+        const task = tasks[i];
+        const filesToCheck = [...task.files, ...task.inputs];
+        for (const file of filesToCheck) {
+            const normalizedFile = normalizeFilePath(file);
+            const creator = fileCreators.get(normalizedFile);
+            if (creator && creator.index > i) {
+                // Task reads file that is created later — impossible ordering
+                results.push({
+                    category: "file",
+                    target: file,
+                    passed: false,
+                    message: `Task ${task.id} reads '${file}' but it's created by task ${creator.taskId} (sequence violation)`,
+                    blocking: true,
+                });
+            }
+        }
+    }
+    return results;
+}
+/**
+ * Extract function signatures from code blocks in task description.
+ * Uses heuristic regex — not an AST parser.
+ */
+function extractFunctionSignatures(description, taskId) {
+    const signatures = [];
+    // Match code blocks (```...```)
+    const codeBlockPattern = /```(?:typescript|ts|javascript|js)?\n([\s\S]*?)```/g;
+    let blockMatch;
+    while ((blockMatch = codeBlockPattern.exec(description)) !== null) {
+        const codeBlock = blockMatch[1];
+        // Match function declarations and exports
+        // Patterns:
+        //   function name(params): ReturnType
+        //   export function name(params): ReturnType
+        //   export async function name(params): Promise<ReturnType>
+        //   const name = (params): ReturnType =>
+        //   export const name = (params): ReturnType =>
+        const funcPattern = /(?:export\s+)?(?:async\s+)?(?:function\s+|const\s+)(\w+)(?:\s*=\s*)?\s*\(([^)]*)\)(?:\s*:\s*([^{=>\n]+))?/g;
+        let funcMatch;
+        while ((funcMatch = funcPattern.exec(codeBlock)) !== null) {
+            const [raw, name, params, returnType] = funcMatch;
+            signatures.push({
+                name,
+                params: normalizeParams(params),
+                returnType: normalizeType(returnType || "void"),
+                taskId,
+                raw: raw.trim(),
+            });
+        }
+        // Match interface method signatures
+        // Pattern: methodName(params): ReturnType;
+        const methodPattern = /^\s*(\w+)\s*\(([^)]*)\)\s*:\s*([^;]+);/gm;
+        let methodMatch;
+        while ((methodMatch = methodPattern.exec(codeBlock)) !== null) {
+            const [raw, name, params, returnType] = methodMatch;
+            signatures.push({
+                name,
+                params: normalizeParams(params),
+                returnType: normalizeType(returnType),
+                taskId,
+                raw: raw.trim(),
+            });
+        }
+    }
+    return signatures;
+}
+/**
+ * Normalize parameter list for comparison.
+ * Removes whitespace, comments, and default values.
+ */
+function normalizeParams(params) {
+    return params
+        .replace(/\/\*[\s\S]*?\*\//g, "") // Remove block comments
+        .replace(/\/\/[^\n]*/g, "") // Remove line comments
+        .replace(/\s*=\s*[^,)]+/g, "") // Remove default values
+        .replace(/\s+/g, " ") // Normalize whitespace
+        .trim();
+}
+/**
+ * Normalize type for comparison.
+ */
+function normalizeType(type) {
+    return type
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/**
+ * Check for contradictory function signatures across tasks.
+ * Same function name with different signatures is a warning (not blocking).
+ */
+export function checkInterfaceContracts(tasks, _basePath) {
+    const results = [];
+    // Collect all signatures
+    const allSignatures = [];
+    for (const task of tasks) {
+        const sigs = extractFunctionSignatures(task.description, task.id);
+        allSignatures.push(...sigs);
+    }
+    // Group by function name
+    const byName = new Map();
+    for (const sig of allSignatures) {
+        const existing = byName.get(sig.name) || [];
+        existing.push(sig);
+        byName.set(sig.name, existing);
+    }
+    // Check for contradictions
+    for (const [name, sigs] of byName) {
+        if (sigs.length < 2)
+            continue;
+        // Compare signatures
+        const first = sigs[0];
+        for (let i = 1; i < sigs.length; i++) {
+            const current = sigs[i];
+            // Check parameter mismatch
+            if (first.params !== current.params) {
+                results.push({
+                    category: "schema",
+                    target: name,
+                    passed: true, // Warning only, not blocking
+                    message: `Function '${name}' has different parameters: '${first.params}' (${first.taskId}) vs '${current.params}' (${current.taskId})`,
+                    blocking: false,
+                });
+            }
+            // Check return type mismatch
+            if (first.returnType !== current.returnType) {
+                results.push({
+                    category: "schema",
+                    target: name,
+                    passed: true, // Warning only, not blocking
+                    message: `Function '${name}' has different return types: '${first.returnType}' (${first.taskId}) vs '${current.returnType}' (${current.taskId})`,
+                    blocking: false,
+                });
+            }
+        }
+    }
+    return results;
+}
+// ─── Main Entry Point ────────────────────────────────────────────────────────
+/**
+ * Run all pre-execution checks against a slice's task plan.
+ *
+ * @param tasks - Array of TaskRow from the slice
+ * @param basePath - Base path for resolving file references
+ * @returns PreExecutionResult with status, checks, and duration
+ */
+export async function runPreExecutionChecks(tasks, basePath) {
+    const startTime = Date.now();
+    const allChecks = [];
+    // Run sync checks first
+    const fileChecks = checkFilePathConsistency(tasks, basePath);
+    const orderingChecks = checkTaskOrdering(tasks, basePath);
+    const contractChecks = checkInterfaceContracts(tasks, basePath);
+    allChecks.push(...fileChecks, ...orderingChecks, ...contractChecks);
+    // Run async package checks
+    const packageChecks = await checkPackageExistence(tasks, basePath);
+    allChecks.push(...packageChecks);
+    const durationMs = Date.now() - startTime;
+    // Determine overall status
+    const hasBlockingFailure = allChecks.some((c) => !c.passed && c.blocking);
+    const hasNonBlockingFailure = allChecks.some((c) => !c.passed && !c.blocking);
+    // Interface contract checks pass but still report warnings via message
+    const hasInterfaceWarning = allChecks.some((c) => c.category === "schema" && c.message && !c.message.startsWith("Warning:"));
+    const hasNetworkWarning = allChecks.some((c) => c.passed && c.message?.startsWith("Warning:"));
+    let status;
+    if (hasBlockingFailure) {
+        status = "fail";
+    }
+    else if (hasNonBlockingFailure || hasInterfaceWarning || hasNetworkWarning) {
+        status = "warn";
+    }
+    else {
+        status = "pass";
+    }
+    return {
+        status,
+        checks: allChecks,
+        durationMs,
+    };
+}

package/dist/resources/extensions/gsd/preferences-types.js

@@ -74,6 +74,12 @@ export const KNOWN_PREFERENCE_KEYS = new Set([
     "context_management",
     "experimental",
     "codebase",
+    "slice_parallel",
+    "safety_harness",
+    "enhanced_verification",
+    "enhanced_verification_pre",
+    "enhanced_verification_post",
+    "enhanced_verification_strict",
 ]);
 /** Canonical list of all dispatch unit types. */
 export const KNOWN_UNIT_TYPES = [

package/dist/resources/extensions/gsd/preferences-validation.js

@@ -939,5 +939,38 @@ export function validatePreferences(preferences) {
             errors.push("codebase must be an object");
         }
     }
+    // ─── Enhanced Verification ──────────────────────────────────────────────────
+    if (preferences.enhanced_verification !== undefined) {
+        if (typeof preferences.enhanced_verification === "boolean") {
+            validated.enhanced_verification = preferences.enhanced_verification;
+        }
+        else {
+            errors.push("enhanced_verification must be a boolean");
+        }
+    }
+    if (preferences.enhanced_verification_pre !== undefined) {
+        if (typeof preferences.enhanced_verification_pre === "boolean") {
+            validated.enhanced_verification_pre = preferences.enhanced_verification_pre;
+        }
+        else {
+            errors.push("enhanced_verification_pre must be a boolean");
+        }
+    }
+    if (preferences.enhanced_verification_post !== undefined) {
+        if (typeof preferences.enhanced_verification_post === "boolean") {
+            validated.enhanced_verification_post = preferences.enhanced_verification_post;
+        }
+        else {
+            errors.push("enhanced_verification_post must be a boolean");
+        }
+    }
+    if (preferences.enhanced_verification_strict !== undefined) {
+        if (typeof preferences.enhanced_verification_strict === "boolean") {
+            validated.enhanced_verification_strict = preferences.enhanced_verification_strict;
+        }
+        else {
+            errors.push("enhanced_verification_strict must be a boolean");
+        }
+    }
     return { preferences: validated, errors, warnings };
 }

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

@@ -148,9 +148,11 @@ export function parsePreferencesMarkdown(content) {
     if (/^##\s+\w/m.test(content)) {
         return parseHeadingListFormat(content);
     }
-    if (!_warnedUnrecognizedFormat) {
+    // Warn when a non-empty file exists but lacks frontmatter delimiters (#2036).
+    if (content.trim().length > 0 && !_warnedUnrecognizedFormat) {
         _warnedUnrecognizedFormat = true;
-        console.warn("[parsePreferencesMarkdown] preferences.md exists but uses an unrecognized format — skipping.");
+        console.warn("[GSD] Warning: preferences file has unrecognized format — content does not use YAML frontmatter delimiters (---). " +
+            "Wrap your preferences in --- fences. See https://github.com/gsd-build/gsd-2/issues/2036");
     }
     return null;
 }
@@ -280,6 +282,10 @@ function mergePreferences(base, override) {
         verification_commands: mergeStringLists(base.verification_commands, override.verification_commands),
         verification_auto_fix: override.verification_auto_fix ?? base.verification_auto_fix,
         verification_max_retries: override.verification_max_retries ?? base.verification_max_retries,
+        enhanced_verification: override.enhanced_verification ?? base.enhanced_verification,
+        enhanced_verification_pre: override.enhanced_verification_pre ?? base.enhanced_verification_pre,
+        enhanced_verification_post: override.enhanced_verification_post ?? base.enhanced_verification_post,
+        enhanced_verification_strict: override.enhanced_verification_strict ?? base.enhanced_verification_strict,
         search_provider: override.search_provider ?? base.search_provider,
         context_selection: override.context_selection ?? base.context_selection,
         auto_visualize: override.auto_visualize ?? base.auto_visualize,
@@ -301,6 +307,9 @@ function mergePreferences(base, override) {
                 ].filter(Boolean),
             }
             : undefined,
+        slice_parallel: (base.slice_parallel || override.slice_parallel)
+            ? { ...(base.slice_parallel ?? {}), ...(override.slice_parallel ?? {}) }
+            : undefined,
     };
 }
 function mergeStringLists(base, override) {

package/dist/resources/extensions/gsd/prompt-loader.js

@@ -47,6 +47,13 @@ function resolveExtensionDir() {
 const __extensionDir = resolveExtensionDir();
 const promptsDir = join(__extensionDir, "prompts");
 const templatesDir = join(__extensionDir, "templates");
+/**
+ * Return the resolved templates directory path for use in prompts.
+ * Avoids hardcoding `~/.gsd/agent/extensions/gsd/templates/` in templates. (#3575)
+ */
+export function getTemplatesDir() {
+    return templatesDir;
+}
 // Cache all templates eagerly at module load — a running session uses the
 // template versions that were on disk at startup, immune to later overwrites.
 const templateCache = new Map();

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

@@ -24,6 +24,8 @@ Then:
 7. Fill the **Decision Re-evaluation** table in the milestone summary. For each key decision from `.gsd/DECISIONS.md` made during this milestone, evaluate whether it is still valid given what was actually built. Flag decisions that should be revisited next milestone.
 8. Validate **requirement status transitions**. For each requirement that changed status during this milestone, confirm the transition is supported by evidence. Requirements can move between Active, Validated, Deferred, Blocked, or Out of Scope — but only with proof.
 
+**DB access safety:** Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')` — the engine owns the WAL connection. Use `gsd_milestone_status` to read milestone and slice state. All data you need is already inlined in the context above or accessible via the `gsd_*` tools — never via direct SQL.
+
 ### Verification Gate — STOP if verification failed
 
 **If ANY verification failure was recorded in steps 3, 4, or 5, you MUST follow the failure path below. Do NOT proceed to step 9.**

package/dist/resources/extensions/gsd/prompts/complete-slice.md

@@ -35,6 +35,8 @@ Then:
 
 **Autonomous execution:** Do not call `ask_user_questions` or `secure_env_collect`. You are running in auto-mode — there is no human available to answer questions. Make reasonable assumptions and document them in the slice summary. If a decision genuinely requires human input, note it in the summary and proceed with the best available option.
 
+**File system safety:** Task summaries are preloaded in the inlined context above. If you need to re-read any of them, use `find .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks -name "*-SUMMARY.md"` to list file paths first — never pass `{{slicePath}}` or any other directory path directly to the `read` tool. The `read` tool only accepts file paths, not directories.
+
 **You MUST call `gsd_complete_slice` with the slice summary and UAT content before finishing. The tool persists to both DB and disk and renders `{{sliceSummaryPath}}` and `{{sliceUatPath}}` automatically.**
 
 When done, say: "Slice {{sliceId}} complete."

package/dist/resources/extensions/gsd/prompts/doctor-heal.md

@@ -9,6 +9,7 @@ Rules:
 4. For missing summaries or UAT files, generate the real artifact from existing slice/task context when possible — do not leave placeholders if you can reconstruct the real content.
 5. After each repair cluster, verify the relevant invariant directly from disk.
 6. When done, rerun `/gsd doctor {{doctorCommandSuffix}}` mentally by ensuring the remaining issue set for this scope is reduced or cleared.
+7. Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')` — use `gsd_milestone_status` to inspect DB state. Direct access bypasses the WAL connection owned by the engine and can corrupt in-flight writes.
 
 ## Doctor Summary
 

package/dist/resources/extensions/gsd/prompts/forensics.md

@@ -116,6 +116,8 @@ A unit dispatched more than once (`type/id` appears multiple times) indicates a
 
 5. **Read the actual GSD source code** at `{{gsdSourceDir}}` to confirm or deny each hypothesis. Do not guess what code does — read it.
 
+   **DB inspection:** If you need to check DB state as part of investigation, use `gsd_milestone_status` — never run `sqlite3 .gsd/gsd.db` or `node -e require('better-sqlite3')` directly. The engine holds a WAL write lock; direct access will either fail or return stale data.
+
 6. **Trace the code path** from the entry point (usually `auto-loop.ts` dispatch or `auto-dispatch.ts`) through to the failure point. Follow function calls across files.
 
 7. **Identify the specific file and line** where the bug lives. Determine what kind of defect it is:

package/dist/resources/extensions/gsd/prompts/reassess-roadmap.md

@@ -63,4 +63,6 @@ If `.gsd/REQUIREMENTS.md` exists and requirement ownership or status changed, up
 
 {{commitInstruction}}
 
+**DB access safety:** Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')`. Use `gsd_milestone_status` to read current milestone and slice state. All roadmap mutations go through `gsd_reassess_roadmap` — the tool writes to the DB and re-renders ROADMAP.md atomically.
+
 When done, say: "Roadmap reassessed."

package/dist/resources/extensions/gsd/prompts/system.md

@@ -24,13 +24,9 @@ Leave the project in a state where the next agent can immediately understand wha
 
 ## Skills
 
-GSD ships with bundled skills. Load the relevant skill file with the `read` tool before starting work when the task matches.
+GSD ships with bundled skills. Load the relevant skill file with the `read` tool before starting work when the task matches. Use bare skill names — GSD resolves them to the correct path automatically.
 
-| Trigger | Skill to load |
-|---|---|
-| Frontend UI - web components, pages, landing pages, dashboards, React/HTML/CSS, styling | `~/.gsd/agent/skills/frontend-design/SKILL.md` |
-| macOS or iOS apps - SwiftUI, Xcode, App Store | `~/.gsd/agent/skills/swiftui/SKILL.md` |
-| Debugging - complex bugs, failing tests, root-cause investigation after standard approaches fail | `~/.gsd/agent/skills/debug-like-expert/SKILL.md` |
+{{bundledSkillsTable}}
 
 ## Hard Rules
 
@@ -119,7 +115,7 @@ In all modes, slices commit sequentially on the active branch; there are no per-
 ### Artifact Templates
 
 Templates showing the expected format for each artifact type are in:
-`~/.gsd/agent/extensions/gsd/templates/`
+`{{templatesDir}}`
 
 **Always read the relevant template before writing an artifact** to match the expected structure exactly. The parsers that read these files depend on specific formatting:
 
@@ -175,6 +171,7 @@ Templates showing the expected format for each artifact type are in:
 - Never guess at library APIs from training data — use `get_library_docs`.
 - Never ask the user to run a command, set a variable, or check something you can check yourself.
 - Never await stale async jobs after editing source — `cancel_job` them first, then re-run.
+- Never query `.gsd/gsd.db` directly via `sqlite3`, `better-sqlite3`, or `node -e require('better-sqlite3')` — the database uses a single-writer WAL connection managed by the engine. Direct access causes reader/writer conflicts and bypasses validation logic. Use `gsd_milestone_status`, `gsd_journal_query`, or other `gsd_*` tools exclusively for all DB reads and writes.
 
 ### Ask vs infer
 

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

@@ -38,6 +38,8 @@ All relevant context has been preloaded below — the roadmap, all slice summari
 
 **Persist validation results through `gsd_validate_milestone`.** Call it with: `milestoneId`, `verdict`, `remediationRound`, `successCriteriaChecklist`, `sliceDeliveryAudit`, `crossSliceIntegration`, `requirementCoverage`, `verificationClasses` (when non-empty), `verdictRationale`, and `remediationPlan` (if verdict is `needs-remediation`). The tool writes the validation to the DB and renders VALIDATION.md to disk.
 
+**DB access safety:** Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')` — the engine owns the WAL connection. Use `gsd_milestone_status` to read milestone and slice state. All data you need is already inlined in the context above or accessible via the `gsd_*` tools. Direct DB access corrupts the WAL and bypasses tool-level validation.
+
 If verdict is `needs-remediation`:
 - After calling `gsd_validate_milestone`, use `gsd_reassess_roadmap` to add remediation slices. Pass `milestoneId`, a synthetic `completedSliceId` (e.g. "VALIDATION"), `verdict: "roadmap-adjusted"`, `assessment` text, and `sliceChanges` with the new slices in the `added` array. The tool persists the changes to the DB and re-renders ROADMAP.md.
 - These remediation slices will be planned and executed before validation re-runs.

package/dist/resources/extensions/gsd/roadmap-mutations.js

@@ -31,7 +31,7 @@ export function markSliceDoneInRoadmap(basePath, mid, sid) {
     if (updated === content) {
         updated = content.replace(new RegExp(`^(#{1,4}\\s+(?:\\*{0,2})(?:Slice\\s+)?${sid}\\*{0,2}[:\\s.\\u2014\\u2013-]+\\s*)(.+)`, "m"), (match, prefix, title) => {
             // Already marked done — no-op
-            if (/^\u2713/.test(title) || /\(Complete\)\s*$/i.test(title))
+            if (/^[\u2713\u2705]/.test(title) || /[\u2705]\s*$/.test(title) || /\(Complete\)\s*$/i.test(title))
                 return match;
             return `${prefix}\u2713 ${title}`;
         });