gsd-pi 2.50.0 → 2.51.0-dev.ae8f7cb

package/src/resources/extensions/gsd/dispatch-guard.ts

@@ -2,6 +2,7 @@
 
 import { resolveMilestoneFile } from "./paths.js";
 import { findMilestoneIds } from "./guided-flow.js";
+import { parseUnitId } from "./unit-id.js";
 import { isDbAvailable, getMilestoneSlices } from "./gsd-db.js";
 import { parseRoadmap } from "./parsers-legacy.js";
 import { readFileSync } from "node:fs";
@@ -22,7 +23,7 @@ export function getPriorSliceCompletionBlocker(
 ): string | null {
   if (!SLICE_DISPATCH_TYPES.has(unitType)) return null;
 
-  const [targetMid, targetSid] = unitId.split("/");
+  const { milestone: targetMid, slice: targetSid } = parseUnitId(unitId);
   if (!targetMid || !targetSid) return null;
 
   // Use findMilestoneIds to respect custom queue order.

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -241,6 +241,9 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
 
   **Known unit types for `before`/`after`:** `research-milestone`, `plan-milestone`, `research-slice`, `plan-slice`, `execute-task`, `complete-slice`, `replan-slice`, `reassess-roadmap`, `run-uat`.
 
+- `experimental`: opt-in experimental features. All features here are **off by default** — you must explicitly set each one to `true` to enable it. Features in this block may change or be removed without a deprecation cycle while in experimental status. Keys:
+  - `rtk`: boolean — enable RTK (Real-Time Kompression) shell-command compression. When enabled, GSD wraps shell commands through the RTK binary to reduce token usage during command execution. RTK is downloaded automatically on first use if not already installed. **Default: `false`** (opt-in required). Set `GSD_RTK_DISABLED=1` in the environment to force-disable regardless of this preference.
+
 ---
 
 ## Best Practices
@@ -652,3 +655,15 @@ verification_max_retries: 2
 ```
 
 Runs test, lint, and typecheck after each task. On failure, auto-fix is attempted up to 2 times before reporting the issue.
+
+## Experimental Features Example
+
+```yaml
+---
+version: 1
+experimental:
+  rtk: true
+---
+```
+
+Opts in to RTK shell-command compression. RTK is downloaded automatically on first use. Set `GSD_RTK_DISABLED=1` to force-disable at the environment level regardless of this setting.

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

@@ -269,6 +269,8 @@ function _parseSummaryImpl(content: string): Summary {
       whatHappened: nativeResult.whatHappened,
       deviations: nativeResult.deviations,
       filesModified: nativeResult.filesModified,
+      followUps: extractSection(content, 'Follow-ups') ?? '',
+      knownLimitations: extractSection(content, 'Known Limitations') ?? '',
     };
   }
 
@@ -330,7 +332,10 @@ function _parseSummaryImpl(content: string): Summary {
     }
   }
 
-  return { frontmatter, title, oneLiner, whatHappened, deviations, filesModified };
+  const followUps = extractSection(body, 'Follow-ups') ?? '';
+  const knownLimitations = extractSection(body, 'Known Limitations') ?? '';
+
+  return { frontmatter, title, oneLiner, whatHappened, deviations, filesModified, followUps, knownLimitations };
 }
 
 // ─── Continue Parser ───────────────────────────────────────────────────────

package/src/resources/extensions/gsd/guided-flow.ts

@@ -450,7 +450,10 @@ async function buildDiscussSlicePrompt(
   }
 
   // Completed slice summaries — what was already built that this slice builds on
+  // Ensure DB is open so getMilestoneSlices returns real data (#2560).
   {
+    const { ensureDbOpen } = await import("./bootstrap/dynamic-tools.js");
+    await ensureDbOpen();
     type NormSlice = { id: string; done: boolean };
     let normSlices: NormSlice[] = [];
     if (isDbAvailable()) {
@@ -588,6 +591,14 @@ export async function showDiscuss(
     return;
   }
 
+  // Ensure DB is open before querying slices (#2560).
+  // showDiscuss() is a command handler — unlike tool handlers, it has no
+  // automatic ensureDbOpen() call. Without this, isDbAvailable() returns
+  // false on cold-start sessions and normSlices falls to [] → false
+  // "All slices complete" exit.
+  const { ensureDbOpen } = await import("./bootstrap/dynamic-tools.js");
+  await ensureDbOpen();
+
   // Guard: no roadmap yet (unless DB has slices)
   const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
   const roadmapContent = roadmapFile ? await loadFile(roadmapFile) : null;

package/src/resources/extensions/gsd/init-wizard.ts

@@ -15,6 +15,7 @@ import { ensureGitignore, untrackRuntimeFiles } from "./gitignore.js";
 import { gsdRoot } from "./paths.js";
 import { assertSafeDirectory } from "./validate-directory.js";
 import type { ProjectDetection, ProjectSignals } from "./detection.js";
+import { runSkillInstallStep } from "./skill-catalog.js";
 
 // ─── Types ──────────────────────────────────────────────────────────────────────
 
@@ -223,7 +224,14 @@ export async function showProjectInit(
     await customizeAdvancedPrefs(ctx, prefs);
   }
 
-  // ── Step 8: Bootstrap .gsd/ ────────────────────────────────────────────────
+  // ── Step 8: Skill Installation ─────────────────────────────────────────────
+  try {
+    await runSkillInstallStep(ctx, signals);
+  } catch {
+    // Non-fatal — skill installation failure should never block project init
+  }
+
+  // ── Step 9: Bootstrap .gsd/ ────────────────────────────────────────────────
   bootstrapGsdDirectory(basePath, prefs, signals);
 
   // Ensure .gitignore

package/src/resources/extensions/gsd/model-router.ts

@@ -114,6 +114,21 @@ export function resolveModelForComplexity(
   const configuredTier = getModelTier(configuredPrimary);
   const requestedTier = classification.tier;
 
+  // If the configured model is unknown (not in MODEL_CAPABILITY_TIER),
+  // honor the user's explicit choice — don't downgrade based on a guess.
+  // Unknown models default to "heavy" in getModelTier, which makes every
+  // standard/light unit get downgraded to tier_models, silently ignoring
+  // the user's configuration. (#2192)
+  if (!isKnownModel(configuredPrimary)) {
+    return {
+      modelId: configuredPrimary,
+      fallbacks: phaseConfig.fallbacks,
+      tier: requestedTier,
+      wasDowngraded: false,
+      reason: `configured model "${configuredPrimary}" is not in the known tier map — honoring explicit config`,
+    };
+  }
+
   // Downgrade-only: if requested tier >= configured tier, no change
   if (tierOrdinal(requestedTier) >= tierOrdinal(configuredTier)) {
     return {
@@ -202,6 +217,16 @@ function getModelTier(modelId: string): ComplexityTier {
   return "heavy";
 }
 
+/** Check if a model ID has a known capability tier mapping. (#2192) */
+function isKnownModel(modelId: string): boolean {
+  const bareId = modelId.includes("/") ? modelId.split("/").pop()! : modelId;
+  if (MODEL_CAPABILITY_TIER[bareId]) return true;
+  for (const knownId of Object.keys(MODEL_CAPABILITY_TIER)) {
+    if (bareId.includes(knownId) || knownId.includes(bareId)) return true;
+  }
+  return false;
+}
+
 function findModelForTier(
   tier: ComplexityTier,
   config: DynamicRoutingConfig,

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

@@ -74,6 +74,17 @@ export function buildDesktopNotificationCommand(
   const normalizedMessage = normalizeNotificationText(message);
 
   if (platform === "darwin") {
+    // Prefer terminal-notifier: registers as its own Notification Center app,
+    // so it gets a proper permission entry in System Settings → Notifications.
+    // osascript notifications are silently swallowed when the calling terminal
+    // (Ghostty, iTerm2, etc.) lacks notification permissions — exits 0, no error.
+    // See: https://github.com/gsd-build/gsd-2/issues/2632
+    const tnPath = findExecutable("terminal-notifier");
+    if (tnPath) {
+      const sound = level === "error" ? "Basso" : "Glass";
+      return { file: tnPath, args: ["-title", normalizedTitle, "-message", normalizedMessage, "-sound", sound] };
+    }
+    // Fallback: osascript (works if terminal app has notification permissions)
     const sound = level === "error" ? 'sound name "Basso"' : 'sound name "Glass"';
     const script = `display notification "${escapeAppleScript(normalizedMessage)}" with title "${escapeAppleScript(normalizedTitle)}" ${sound}`;
     return { file: "osascript", args: ["-e", script] };
@@ -94,3 +105,15 @@ function normalizeNotificationText(s: string): string {
 function escapeAppleScript(s: string): string {
   return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
 }
+
+/**
+ * Locate an executable on PATH. Returns absolute path or null.
+ * Non-fatal — returns null on any error.
+ */
+function findExecutable(name: string): string | null {
+  try {
+    return execFileSync("which", [name], { timeout: 2000, stdio: ["ignore", "pipe", "ignore"] }).toString().trim() || null;
+  } catch {
+    return null;
+  }
+}

package/src/resources/extensions/gsd/observability-validator.ts

@@ -0,0 +1,456 @@
+import { loadFile } from "./files.js";
+import { resolveSliceFile, resolveTaskFile, resolveTasksDir, resolveTaskFiles } from "./paths.js";
+
+export interface ValidationIssue {
+  severity: "info" | "warning" | "error";
+  scope: "slice-plan" | "task-plan" | "task-summary" | "slice-summary";
+  file: string;
+  ruleId: string;
+  message: string;
+  suggestion?: string;
+}
+
+function getSection(content: string, heading: string, level: number = 2): string | null {
+  const prefix = "#".repeat(level) + " ";
+  const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const regex = new RegExp(`^${prefix}${escaped}\\s*$`, "m");
+  const match = regex.exec(content);
+  if (!match) return null;
+
+  const start = match.index + match[0].length;
+  const rest = content.slice(start);
+  const nextHeading = rest.match(new RegExp(`^#{1,${level}} `, "m"));
+  const end = nextHeading ? nextHeading.index! : rest.length;
+  return rest.slice(0, end).trim();
+}
+
+function getFrontmatter(content: string): string | null {
+  const trimmed = content.trimStart();
+  if (!trimmed.startsWith("---")) return null;
+  const afterFirst = trimmed.indexOf("\n");
+  if (afterFirst === -1) return null;
+  const rest = trimmed.slice(afterFirst + 1);
+  const endIdx = rest.indexOf("\n---");
+  if (endIdx === -1) return null;
+  return rest.slice(0, endIdx);
+}
+
+function hasFrontmatterKey(content: string, key: string): boolean {
+  const fm = getFrontmatter(content);
+  if (!fm) return false;
+  return new RegExp(`^${key}:`, "m").test(fm);
+}
+
+function normalizeMeaningfulLines(text: string): string[] {
+  return text
+    .split("\n")
+    .map(line => line.trim())
+    .filter(line => line.length > 0)
+    .filter(line => !line.startsWith("<!--"))
+    .filter(line => !line.endsWith("-->"))
+    .filter(line => !/^[-*]\s*\{\{.+\}\}$/.test(line))
+    .filter(line => !/^\{\{.+\}\}$/.test(line));
+}
+
+function sectionLooksPlaceholderOnly(text: string | null): boolean {
+  if (!text) return true;
+  const lines = normalizeMeaningfulLines(text)
+    .map(line => line.replace(/^[-*]\s+/, "").trim())
+    .filter(line => line.length > 0);
+
+  if (lines.length === 0) return true;
+
+  return lines.every(line => {
+    const lower = line.toLowerCase();
+    return lower === "none" ||
+      lower.endsWith(": none") ||
+      lower.includes("{{") ||
+      lower.includes("}}") ||
+      lower.startsWith("required for non-trivial") ||
+      lower.startsWith("describe how a future agent") ||
+      lower.startsWith("prefer:") ||
+      lower.startsWith("keep this section concise");
+  });
+}
+
+function textSuggestsObservabilityRelevant(content: string): boolean {
+  const lower = content.toLowerCase();
+  const needles = [
+    " api", "route", "server", "worker", "queue", "job", "sync", "import",
+    "webhook", "auth", "db", "database", "migration", "cache", "background",
+    "polling", "realtime", "socket", "stateful", "integration", "ui", "form",
+    "submit", "status", "service", "pipeline", "health endpoint", "error path"
+  ];
+  return needles.some(needle => lower.includes(needle));
+}
+
+function verificationMentionsDiagnostics(section: string | null): boolean {
+  if (!section) return false;
+  const lower = section.toLowerCase();
+  const needles = [
+    "error", "failure", "diagnostic", "status", "health", "inspect", "log",
+    "network", "console", "retry", "last error", "correlation", "readiness"
+  ];
+  return needles.some(needle => lower.includes(needle));
+}
+
+export function validateSlicePlanContent(file: string, content: string): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  // ── Plan quality rules (always run, not gated by runtime relevance) ──
+
+  const tasksSection = getSection(content, "Tasks", 2);
+  if (tasksSection) {
+    const lines = tasksSection.split("\n");
+    const taskLinePattern = /^- \[[ x]\] \*\*T\d+:/;
+    const taskLineIndices: number[] = [];
+    for (let i = 0; i < lines.length; i++) {
+      if (taskLinePattern.test(lines[i])) taskLineIndices.push(i);
+    }
+
+    for (let t = 0; t < taskLineIndices.length; t++) {
+      const start = taskLineIndices[t];
+      const end = t + 1 < taskLineIndices.length ? taskLineIndices[t + 1] : lines.length;
+      // Check lines between this task header and the next (or section end)
+      const bodyLines = lines.slice(start + 1, end);
+      const meaningful = bodyLines.filter(l => l.trim().length > 0);
+      if (meaningful.length === 0) {
+        issues.push({
+          severity: "warning",
+          scope: "slice-plan",
+          file,
+          ruleId: "empty_task_entry",
+          message: "Inline task entry has no description content beneath the checkbox line.",
+          suggestion: "Add at least a Why/Files/Do/Verify summary so the task is self-describing.",
+        });
+      }
+    }
+  }
+
+  // ── Observability rules (gated by runtime relevance) ──
+
+  const relevant = textSuggestsObservabilityRelevant(content);
+  if (!relevant) return issues;
+
+  const obs = getSection(content, "Observability / Diagnostics", 2);
+  const verification = getSection(content, "Verification", 2);
+
+  if (!obs) {
+    issues.push({
+      severity: "warning",
+      scope: "slice-plan",
+      file,
+      ruleId: "missing_observability_section",
+      message: "Slice plan appears non-trivial but is missing `## Observability / Diagnostics`.",
+      suggestion: "Add runtime signals, inspection surfaces, failure visibility, and redaction constraints.",
+    });
+  } else if (sectionLooksPlaceholderOnly(obs)) {
+    issues.push({
+      severity: "warning",
+      scope: "slice-plan",
+      file,
+      ruleId: "observability_section_placeholder_only",
+      message: "Slice plan has `## Observability / Diagnostics` but it still looks like placeholder text.",
+      suggestion: "Replace placeholders with concrete signals and inspection surfaces a future agent should trust.",
+    });
+  }
+
+  if (!verificationMentionsDiagnostics(verification)) {
+    issues.push({
+      severity: "warning",
+      scope: "slice-plan",
+      file,
+      ruleId: "verification_missing_diagnostic_check",
+      message: "Slice verification does not appear to include any diagnostic or failure-path check.",
+      suggestion: "Add at least one verification step for inspectable failure state, structured error output, status surface, or equivalent.",
+    });
+  }
+
+  return issues;
+}
+
+export function validateTaskPlanContent(file: string, content: string): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  // ── Plan quality rules (always run, not gated by runtime relevance) ──
+
+  // Rule: empty or missing Steps section
+  const stepsSection = getSection(content, "Steps", 2);
+  if (stepsSection === null || sectionLooksPlaceholderOnly(stepsSection)) {
+    issues.push({
+      severity: "warning",
+      scope: "task-plan",
+      file,
+      ruleId: "empty_steps_section",
+      message: "Task plan has an empty or missing `## Steps` section.",
+      suggestion: "Add concrete numbered implementation steps so execution has a clear sequence.",
+    });
+  }
+
+  // Rule: placeholder-only Verification section
+  const verificationSection = getSection(content, "Verification", 2);
+  if (verificationSection !== null && sectionLooksPlaceholderOnly(verificationSection)) {
+    issues.push({
+      severity: "warning",
+      scope: "task-plan",
+      file,
+      ruleId: "placeholder_verification",
+      message: "Task plan has `## Verification` but it still looks like placeholder text.",
+      suggestion: "Replace placeholders with concrete verification commands, test runs, or observable checks.",
+    });
+  }
+
+  // Rule: scope estimate thresholds
+  const fm = getFrontmatter(content);
+  if (fm) {
+    const stepsMatch = fm.match(/^estimated_steps:\s*(\d+)/m);
+    const filesMatch = fm.match(/^estimated_files:\s*(\d+)/m);
+
+    if (stepsMatch) {
+      const estimatedSteps = parseInt(stepsMatch[1], 10);
+      if (estimatedSteps >= 10) {
+        issues.push({
+          severity: "warning",
+          scope: "task-plan",
+          file,
+          ruleId: "scope_estimate_steps_high",
+          message: `Task plan estimates ${estimatedSteps} steps (threshold: 10). Consider splitting into smaller tasks.`,
+          suggestion: "Break the task into sub-tasks or reduce scope so each task stays focused and completable in one pass.",
+        });
+      }
+    }
+
+    if (filesMatch) {
+      const estimatedFiles = parseInt(filesMatch[1], 10);
+      if (estimatedFiles >= 12) {
+        issues.push({
+          severity: "warning",
+          scope: "task-plan",
+          file,
+          ruleId: "scope_estimate_files_high",
+          message: `Task plan estimates ${estimatedFiles} files (threshold: 12). Consider splitting into smaller tasks.`,
+          suggestion: "Break the task into sub-tasks or reduce scope to keep the change footprint manageable.",
+        });
+      }
+    }
+  }
+
+  // Rule: Inputs and Expected Output should contain backtick-wrapped file paths
+  const inputsSection = getSection(content, "Inputs", 2);
+  const outputSection = getSection(content, "Expected Output", 2);
+  const backtickPathPattern = /`[^`]*[./][^`]*`/;
+
+  if (outputSection === null || !backtickPathPattern.test(outputSection)) {
+    issues.push({
+      severity: "warning",
+      scope: "task-plan",
+      file,
+      ruleId: "missing_output_file_paths",
+      message: "Task plan `## Expected Output` is missing or has no backtick-wrapped file paths.",
+      suggestion: "List concrete output file paths in backticks (e.g. `src/types.ts`). These are machine-parsed to derive task dependencies.",
+    });
+  }
+
+  if (inputsSection !== null && inputsSection.trim().length > 0 && !backtickPathPattern.test(inputsSection)) {
+    issues.push({
+      severity: "info",
+      scope: "task-plan",
+      file,
+      ruleId: "missing_input_file_paths",
+      message: "Task plan `## Inputs` has content but no backtick-wrapped file paths.",
+      suggestion: "List input file paths in backticks (e.g. `src/config.json`). These are machine-parsed to derive task dependencies.",
+    });
+  }
+
+  // ── Observability rules (gated by runtime relevance) ──
+
+  const relevant = textSuggestsObservabilityRelevant(content);
+  if (!relevant) return issues;
+
+  const obs = getSection(content, "Observability Impact", 2);
+  if (!obs) {
+    issues.push({
+      severity: "warning",
+      scope: "task-plan",
+      file,
+      ruleId: "missing_observability_impact",
+      message: "Task plan appears runtime-relevant but is missing `## Observability Impact`.",
+      suggestion: "Explain what signals change, how a future agent inspects this task, and what failure state becomes visible.",
+    });
+  } else if (sectionLooksPlaceholderOnly(obs)) {
+    issues.push({
+      severity: "warning",
+      scope: "task-plan",
+      file,
+      ruleId: "observability_impact_placeholder_only",
+      message: "Task plan has `## Observability Impact` but it still looks empty or placeholder-only.",
+      suggestion: "Fill in concrete inspection surfaces or explicitly justify why observability is not applicable.",
+    });
+  }
+
+  return issues;
+}
+
+export function validateTaskSummaryContent(file: string, content: string): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  if (!hasFrontmatterKey(content, "observability_surfaces")) {
+    issues.push({
+      severity: "warning",
+      scope: "task-summary",
+      file,
+      ruleId: "missing_observability_frontmatter",
+      message: "Task summary is missing `observability_surfaces` in frontmatter.",
+      suggestion: "List the durable status/log/error surfaces a future agent should use.",
+    });
+  }
+
+  const diagnostics = getSection(content, "Diagnostics", 2);
+  if (!diagnostics) {
+    issues.push({
+      severity: "warning",
+      scope: "task-summary",
+      file,
+      ruleId: "missing_diagnostics_section",
+      message: "Task summary is missing `## Diagnostics`.",
+      suggestion: "Document how to inspect what this task built later.",
+    });
+  } else if (sectionLooksPlaceholderOnly(diagnostics)) {
+    issues.push({
+      severity: "warning",
+      scope: "task-summary",
+      file,
+      ruleId: "diagnostics_placeholder_only",
+      message: "Task summary diagnostics section still looks like placeholder text.",
+      suggestion: "Replace placeholders with concrete commands, endpoints, logs, error shapes, or failure artifacts.",
+    });
+  }
+
+  const evidence = getSection(content, "Verification Evidence", 2);
+  if (!evidence) {
+    issues.push({
+      severity: "warning",
+      scope: "task-summary",
+      file,
+      ruleId: "evidence_block_missing",
+      message: "Task summary is missing `## Verification Evidence`.",
+      suggestion: "Add a verification evidence table showing gate check results (command, exit code, verdict, duration).",
+    });
+  } else if (sectionLooksPlaceholderOnly(evidence)) {
+    issues.push({
+      severity: "warning",
+      scope: "task-summary",
+      file,
+      ruleId: "evidence_block_placeholder",
+      message: "Task summary verification evidence section still looks like placeholder text.",
+      suggestion: "Replace placeholders with actual gate results or note that no verification commands were discovered.",
+    });
+  }
+
+  return issues;
+}
+
+export function validateSliceSummaryContent(file: string, content: string): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  if (!hasFrontmatterKey(content, "observability_surfaces")) {
+    issues.push({
+      severity: "warning",
+      scope: "slice-summary",
+      file,
+      ruleId: "missing_observability_frontmatter",
+      message: "Slice summary is missing `observability_surfaces` in frontmatter.",
+      suggestion: "List the authoritative diagnostics and durable inspection surfaces for this slice.",
+    });
+  }
+
+  const diagnostics = getSection(content, "Authoritative diagnostics", 3);
+  if (!diagnostics) {
+    issues.push({
+      severity: "warning",
+      scope: "slice-summary",
+      file,
+      ruleId: "missing_authoritative_diagnostics",
+      message: "Slice summary is missing `### Authoritative diagnostics` in Forward Intelligence.",
+      suggestion: "Tell future agents where to look first and why that signal is trustworthy.",
+    });
+  } else if (sectionLooksPlaceholderOnly(diagnostics)) {
+    issues.push({
+      severity: "warning",
+      scope: "slice-summary",
+      file,
+      ruleId: "authoritative_diagnostics_placeholder_only",
+      message: "Slice summary includes authoritative diagnostics but it still looks like placeholder text.",
+      suggestion: "Replace placeholders with the real first-stop diagnostic surface for this slice.",
+    });
+  }
+
+  return issues;
+}
+
+export async function validatePlanBoundary(basePath: string, milestoneId: string, sliceId: string): Promise<ValidationIssue[]> {
+  const issues: ValidationIssue[] = [];
+  const slicePlan = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN");
+  if (slicePlan) {
+    const content = await loadFile(slicePlan);
+    if (content) issues.push(...validateSlicePlanContent(slicePlan, content));
+  }
+
+  const tasksDir = resolveTasksDir(basePath, milestoneId, sliceId);
+  const taskPlans = tasksDir ? resolveTaskFiles(tasksDir, "PLAN") : [];
+  for (const file of taskPlans) {
+    const taskId = file.split("-")[0];
+    const taskPlan = resolveTaskFile(basePath, milestoneId, sliceId, taskId, "PLAN");
+    if (!taskPlan) continue;
+    const content = await loadFile(taskPlan);
+    if (content) issues.push(...validateTaskPlanContent(taskPlan, content));
+  }
+
+  return issues;
+}
+
+export async function validateExecuteBoundary(basePath: string, milestoneId: string, sliceId: string, taskId: string): Promise<ValidationIssue[]> {
+  const issues: ValidationIssue[] = [];
+  const slicePlan = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN");
+  if (slicePlan) {
+    const content = await loadFile(slicePlan);
+    if (content) issues.push(...validateSlicePlanContent(slicePlan, content));
+  }
+
+  const taskPlan = resolveTaskFile(basePath, milestoneId, sliceId, taskId, "PLAN");
+  if (taskPlan) {
+    const content = await loadFile(taskPlan);
+    if (content) issues.push(...validateTaskPlanContent(taskPlan, content));
+  }
+
+  return issues;
+}
+
+export async function validateCompleteBoundary(basePath: string, milestoneId: string, sliceId: string): Promise<ValidationIssue[]> {
+  const issues: ValidationIssue[] = [];
+  const tasksDir = resolveTasksDir(basePath, milestoneId, sliceId);
+  const taskSummaries = tasksDir ? resolveTaskFiles(tasksDir, "SUMMARY") : [];
+  for (const file of taskSummaries) {
+    const taskId = file.split("-")[0];
+    const taskSummary = resolveTaskFile(basePath, milestoneId, sliceId, taskId, "SUMMARY");
+    if (!taskSummary) continue;
+    const content = await loadFile(taskSummary);
+    if (content) issues.push(...validateTaskSummaryContent(taskSummary, content));
+  }
+
+  const sliceSummary = resolveSliceFile(basePath, milestoneId, sliceId, "SUMMARY");
+  if (sliceSummary) {
+    const content = await loadFile(sliceSummary);
+    if (content) issues.push(...validateSliceSummaryContent(sliceSummary, content));
+  }
+
+  return issues;
+}
+
+export function formatValidationIssues(issues: ValidationIssue[], limit: number = 4): string {
+  if (issues.length === 0) return "";
+  const lines = issues.slice(0, limit).map(issue => {
+    const fileName = issue.file.split("/").pop() || issue.file;
+    return `- ${fileName}: ${issue.message}`;
+  });
+  if (issues.length > limit) lines.push(`- ...and ${issues.length - limit} more`);
+  return lines.join("\n");
+}

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

@@ -8,7 +8,6 @@
 import { existsSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
-import { getAgentDir } from "@gsd/pi-coding-agent";
 import { statSync } from "node:fs";
 
 import type {
@@ -25,13 +24,20 @@ export type { GSDSkillRule, SkillDiscoveryMode, SkillResolution, SkillResolution
 
 /**
  * Known skill directories, in priority order.
- * User skills (~/.gsd/agent/skills/) take precedence over project skills.
+ * Global skills (~/.agents/skills/) take precedence over project skills.
+ * Legacy ~/.gsd/agent/skills/ is included as a fallback for pre-migration installs.
  */
 export function getSkillSearchDirs(cwd: string): Array<{ dir: string; method: SkillResolution["method"] }> {
-  return [
-    { dir: join(getAgentDir(), "skills"), method: "user-skill" },
-    { dir: join(cwd, ".pi", "agent", "skills"), method: "project-skill" },
+  const dirs: Array<{ dir: string; method: SkillResolution["method"] }> = [
+    { dir: join(homedir(), ".agents", "skills"), method: "user-skill" },
+    { dir: join(cwd, ".agents", "skills"), method: "project-skill" },
   ];
+  // Legacy fallback — read skills from old GSD directory only if migration hasn't completed
+  const legacyDir = join(homedir(), ".gsd", "agent", "skills");
+  if (existsSync(legacyDir) && !existsSync(join(legacyDir, ".migrated-to-agents"))) {
+    dirs.push({ dir: legacyDir, method: "user-skill" });
+  }
+  return dirs;
 }
 
 /**