gsd-pi 2.38.0-dev.7209774 → 2.38.0-dev.785052f

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

@@ -11,7 +11,7 @@ import { milestoneIdSort, findMilestoneIds } from './milestone-ids.js';
 
 import type {
   Roadmap, BoundaryMapEntry,
-  SlicePlan, TaskPlanEntry,
+  SlicePlan, TaskPlanEntry, TaskPlanFile, TaskPlanFrontmatter,
   Summary, SummaryFrontmatter, SummaryRequires, FileModified,
   Continue, ContinueFrontmatter, ContinueStatus,
   RequirementCounts,
@@ -277,14 +277,52 @@ export function formatSecretsManifest(manifest: SecretsManifest): string {
 
 // ─── Slice Plan Parser ─────────────────────────────────────────────────────
 
+function normalizeTaskPlanFrontmatter(frontmatter: Record<string, unknown>): TaskPlanFrontmatter {
+  const estimatedStepsRaw = frontmatter.estimated_steps;
+  const estimatedFilesRaw = frontmatter.estimated_files;
+  const skillsUsedRaw = frontmatter.skills_used;
+
+  const parseOptionalNumber = (value: unknown): number | undefined => {
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+    if (typeof value === 'string' && value.trim()) {
+      const parsed = parseInt(value, 10);
+      if (Number.isFinite(parsed)) return parsed;
+    }
+    return undefined;
+  };
+
+  const estimated_steps = parseOptionalNumber(estimatedStepsRaw);
+  const estimated_files = parseOptionalNumber(estimatedFilesRaw);
+  const skills_used = Array.isArray(skillsUsedRaw)
+    ? skillsUsedRaw.map(v => String(v).trim()).filter(Boolean)
+    : typeof skillsUsedRaw === 'string' && skillsUsedRaw.trim()
+      ? [skillsUsedRaw.trim()]
+      : [];
+
+  return {
+    ...(estimated_steps !== undefined ? { estimated_steps } : {}),
+    ...(estimated_files !== undefined ? { estimated_files } : {}),
+    skills_used,
+  };
+}
+
+export function parseTaskPlanFile(content: string): TaskPlanFile {
+  const [fmLines] = splitFrontmatter(content);
+  const fm = fmLines ? parseFrontmatterMap(fmLines) : {};
+  return {
+    frontmatter: normalizeTaskPlanFrontmatter(fm),
+  };
+}
+
 export function parsePlan(content: string): SlicePlan {
   return cachedParse(content, 'plan', _parsePlanImpl);
 }
 
 function _parsePlanImpl(content: string): SlicePlan {
   const stopTimer = debugTime("parse-plan");
+  const [, body] = splitFrontmatter(content);
   // Try native parser first for better performance
-  const nativeResult = nativeParsePlanFile(content);
+  const nativeResult = nativeParsePlanFile(body);
   if (nativeResult) {
     stopTimer({ native: true });
     return {
@@ -306,7 +344,7 @@ function _parsePlanImpl(content: string): SlicePlan {
     };
   }
 
-  const lines = content.split('\n');
+  const lines = body.split('\n');
 
   const h1 = lines.find(l => l.startsWith('# '));
   let id = '';
@@ -321,13 +359,13 @@ function _parsePlanImpl(content: string): SlicePlan {
     }
   }
 
-  const goal = extractBoldField(content, 'Goal') || '';
-  const demo = extractBoldField(content, 'Demo') || '';
+  const goal = extractBoldField(body, 'Goal') || '';
+  const demo = extractBoldField(body, 'Demo') || '';
 
-  const mhSection = extractSection(content, 'Must-Haves');
+  const mhSection = extractSection(body, 'Must-Haves');
   const mustHaves = mhSection ? parseBullets(mhSection) : [];
 
-  const tasksSection = extractSection(content, 'Tasks');
+  const tasksSection = extractSection(body, 'Tasks');
   const tasks: TaskPlanEntry[] = [];
 
   if (tasksSection) {
@@ -375,7 +413,7 @@ function _parsePlanImpl(content: string): SlicePlan {
     if (currentTask) tasks.push(currentTask);
   }
 
-  const filesSection = extractSection(content, 'Files Likely Touched');
+  const filesSection = extractSection(body, 'Files Likely Touched');
   const filesLikelyTouched = filesSection ? parseBullets(filesSection) : [];
 
   const result = { id, title, goal, demo, mustHaves, tasks, filesLikelyTouched };

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

@@ -7,9 +7,11 @@
  */
 
 import { join } from "node:path";
+import { execFileSync } from "node:child_process";
 import { existsSync, lstatSync, readFileSync, writeFileSync } from "node:fs";
 import { nativeRmCached, nativeLsFiles } from "./native-git-bridge.js";
 import { gsdRoot } from "./paths.js";
+import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 
 /**
  * GSD runtime patterns for git index cleanup.
@@ -104,10 +106,22 @@ export function hasGitTrackedGsdFiles(basePath: string): boolean {
   // Check if git tracks any files under .gsd/
   try {
     const tracked = nativeLsFiles(basePath, ".gsd");
-    return tracked.length > 0;
-  } catch {
-    // Not a git repo or git not available — safe to proceed
+    if (tracked.length > 0) return true;
+
+    // nativeLsFiles swallows git failures and returns []. An empty result
+    // could mean "nothing tracked" OR "git failed silently". Verify git is
+    // reachable before trusting the empty result — if it isn't, fail safe
+    // by assuming files ARE tracked to prevent data loss.
+    execFileSync("git", ["rev-parse", "--git-dir"], {
+      cwd: basePath,
+      stdio: "pipe",
+      env: GIT_NO_PROMPT_ENV,
+    });
+
     return false;
+  } catch {
+    // git unavailable, index locked, or repo corrupt — fail safe
+    return true;
   }
 }
 

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

@@ -10,6 +10,7 @@ import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext } from "@g
 import { showNextAction } from "../shared/mod.js";
 import { loadFile, parseRoadmap } from "./files.js";
 import { loadPrompt, inlineTemplate } from "./prompt-loader.js";
+import { buildSkillActivationBlock } from "./auto-prompts.js";
 import { deriveState } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { startAuto } from "./auto.js";
@@ -1124,7 +1125,16 @@ export async function showSmartEntry(
         ].join("\n\n---\n\n");
         const secretsOutputPath = relMilestoneFile(basePath, milestoneId, "SECRETS");
         await dispatchWorkflow(pi, loadPrompt("guided-plan-milestone", {
-          milestoneId, milestoneTitle, secretsOutputPath, inlinedTemplates: planMilestoneTemplates,
+          milestoneId,
+          milestoneTitle,
+          secretsOutputPath,
+          inlinedTemplates: planMilestoneTemplates,
+          skillActivation: buildSkillActivationBlock({
+            base: basePath,
+            milestoneId,
+            milestoneTitle,
+            extraContext: [planMilestoneTemplates],
+          }),
         }), "gsd-run", ctx, "plan-milestone");
       } else if (choice === "discuss") {
         const discussMilestoneTemplates = inlineTemplate("context", "Context");
@@ -1254,14 +1264,34 @@ export async function showSmartEntry(
         inlineTemplate("task-plan", "Task Plan"),
       ].join("\n\n---\n\n");
       await dispatchWorkflow(pi, loadPrompt("guided-plan-slice", {
-        milestoneId, sliceId, sliceTitle, inlinedTemplates: planSliceTemplates,
+        milestoneId,
+        sliceId,
+        sliceTitle,
+        inlinedTemplates: planSliceTemplates,
+        skillActivation: buildSkillActivationBlock({
+          base: basePath,
+          milestoneId,
+          sliceId,
+          sliceTitle,
+          extraContext: [planSliceTemplates],
+        }),
       }), "gsd-run", ctx, "plan-slice");
     } else if (choice === "discuss") {
       await dispatchWorkflow(pi, await buildDiscussSlicePrompt(milestoneId, sliceId, sliceTitle, basePath, { rediscuss: hasContext }), "gsd-run", ctx, "plan-slice");
     } else if (choice === "research") {
       const researchTemplates = inlineTemplate("research", "Research");
       await dispatchWorkflow(pi, loadPrompt("guided-research-slice", {
-        milestoneId, sliceId, sliceTitle, inlinedTemplates: researchTemplates,
+        milestoneId,
+        sliceId,
+        sliceTitle,
+        inlinedTemplates: researchTemplates,
+        skillActivation: buildSkillActivationBlock({
+          base: basePath,
+          milestoneId,
+          sliceId,
+          sliceTitle,
+          extraContext: [researchTemplates],
+        }),
       }), "gsd-run", ctx, "research-slice");
     } else if (choice === "status") {
       const { fireStatusViaCommand } = await import("./commands.js");
@@ -1305,7 +1335,18 @@ export async function showSmartEntry(
         inlineTemplate("uat", "UAT"),
       ].join("\n\n---\n\n");
       await dispatchWorkflow(pi, loadPrompt("guided-complete-slice", {
-        workingDirectory: basePath, milestoneId, sliceId, sliceTitle, inlinedTemplates: completeSliceTemplates,
+        workingDirectory: basePath,
+        milestoneId,
+        sliceId,
+        sliceTitle,
+        inlinedTemplates: completeSliceTemplates,
+        skillActivation: buildSkillActivationBlock({
+          base: basePath,
+          milestoneId,
+          sliceId,
+          sliceTitle,
+          extraContext: [completeSliceTemplates],
+        }),
       }), "gsd-run", ctx, "complete-slice");
     } else if (choice === "status") {
       const { fireStatusViaCommand } = await import("./commands.js");
@@ -1370,12 +1411,32 @@ export async function showSmartEntry(
     if (choice === "execute") {
       if (hasInterrupted) {
         await dispatchWorkflow(pi, loadPrompt("guided-resume-task", {
-          milestoneId, sliceId,
+          milestoneId,
+          sliceId,
+          skillActivation: buildSkillActivationBlock({
+            base: basePath,
+            milestoneId,
+            sliceId,
+            taskId,
+            taskTitle,
+          }),
         }), "gsd-run", ctx, "execute-task");
       } else {
         const executeTaskTemplates = inlineTemplate("task-summary", "Task Summary");
         await dispatchWorkflow(pi, loadPrompt("guided-execute-task", {
-          milestoneId, sliceId, taskId, taskTitle, inlinedTemplates: executeTaskTemplates,
+          milestoneId,
+          sliceId,
+          taskId,
+          taskTitle,
+          inlinedTemplates: executeTaskTemplates,
+          skillActivation: buildSkillActivationBlock({
+            base: basePath,
+            milestoneId,
+            sliceId,
+            taskId,
+            taskTitle,
+            extraContext: [executeTaskTemplates],
+          }),
         }), "gsd-run", ctx, "execute-task");
       }
     } else if (choice === "status") {

package/src/resources/extensions/gsd/health-widget-core.ts

@@ -5,10 +5,9 @@
  * runtime integrations so the regressions can be tested directly.
  */
 
-import { existsSync, readdirSync } from "node:fs";
+import { existsSync } from "node:fs";
+import { detectProjectState } from "./detection.js";
 import { gsdRoot } from "./paths.js";
-import { join } from "node:path";
-import type { GSDState, Phase } from "./types.js";
 
 export type HealthWidgetProjectState = "none" | "initialized" | "active";
 
@@ -20,75 +19,19 @@ export interface HealthWidgetData {
   environmentErrorCount: number;
   environmentWarningCount: number;
   lastRefreshed: number;
-  executionPhase?: Phase;
-  executionStatus?: string;
-  executionTarget?: string;
-  nextAction?: string;
-  blocker?: string | null;
-  activeMilestoneId?: string;
-  activeSliceId?: string;
-  activeTaskId?: string;
-  progress?: GSDState["progress"];
-  eta?: string | null;
 }
 
 export function detectHealthWidgetProjectState(basePath: string): HealthWidgetProjectState {
-  const root = gsdRoot(basePath);
-  if (!existsSync(root)) return "none";
+  if (!existsSync(gsdRoot(basePath))) return "none";
 
-  // Lightweight milestone count — avoids the full detectProjectState() scan
-  // (CI markers, Makefile targets, etc.) that is unnecessary on the 60s refresh.
-  try {
-    const milestonesDir = join(root, "milestones");
-    if (existsSync(milestonesDir)) {
-      const entries = readdirSync(milestonesDir, { withFileTypes: true });
-      if (entries.some(e => e.isDirectory())) return "active";
-    }
-  } catch { /* non-fatal */ }
-
-  return "initialized";
+  const { state } = detectProjectState(basePath);
+  return state === "v2-gsd" ? "active" : "initialized";
 }
 
 function formatCost(n: number): string {
   return n >= 1 ? `$${n.toFixed(2)}` : `${(n * 100).toFixed(1)}¢`;
 }
 
-function formatProgress(progress?: GSDState["progress"]): string | null {
-  if (!progress) return null;
-
-  const parts: string[] = [];
-  parts.push(`M ${progress.milestones.done}/${progress.milestones.total}`);
-  if (progress.slices) parts.push(`S ${progress.slices.done}/${progress.slices.total}`);
-  if (progress.tasks) parts.push(`T ${progress.tasks.done}/${progress.tasks.total}`);
-  return parts.length > 0 ? `Progress: ${parts.join(" · ")}` : null;
-}
-
-function formatEnvironmentSummary(errorCount: number, warningCount: number): string | null {
-  if (errorCount <= 0 && warningCount <= 0) return null;
-
-  const parts: string[] = [];
-  if (errorCount > 0) parts.push(`${errorCount} error${errorCount > 1 ? "s" : ""}`);
-  if (warningCount > 0) parts.push(`${warningCount} warning${warningCount > 1 ? "s" : ""}`);
-  return `Env: ${parts.join(", ")}`;
-}
-
-function formatBudgetSummary(data: HealthWidgetData): string | null {
-  if (data.budgetCeiling !== undefined && data.budgetCeiling > 0) {
-    const pct = Math.min(100, (data.budgetSpent / data.budgetCeiling) * 100);
-    return `Budget: ${formatCost(data.budgetSpent)}/${formatCost(data.budgetCeiling)} (${pct.toFixed(0)}%)`;
-  }
-  if (data.budgetSpent > 0) {
-    return `Spent: ${formatCost(data.budgetSpent)}`;
-  }
-  return null;
-}
-
-function buildExecutionHeadline(data: HealthWidgetData): string {
-  const status = data.executionStatus ?? "Active project";
-  const target = data.executionTarget ?? data.blocker ?? "loading status…";
-  return `  GSD  ${status}${target ? ` - ${target}` : ""}`;
-}
-
 /**
  * Build compact health lines for the widget.
  * Returns a string array suitable for setWidget().
@@ -102,28 +45,33 @@ export function buildHealthLines(data: HealthWidgetData): string[] {
     return ["  GSD  Project initialized — run /gsd to continue setup"];
   }
 
-  const lines = [buildExecutionHeadline(data)];
-  const details: string[] = [];
-
-  const progress = formatProgress(data.progress);
-  if (progress) details.push(progress);
-
-  if (data.providerIssue) details.push(data.providerIssue);
+  const parts: string[] = [];
 
-  const environment = formatEnvironmentSummary(
-    data.environmentErrorCount,
-    data.environmentWarningCount,
-  );
-  if (environment) details.push(environment);
+  const totalIssues = data.environmentErrorCount + data.environmentWarningCount + (data.providerIssue ? 1 : 0);
+  if (totalIssues === 0) {
+    parts.push("● System OK");
+  } else if (data.environmentErrorCount > 0 || data.providerIssue?.includes("✗")) {
+    parts.push(`✗ ${totalIssues} issue${totalIssues > 1 ? "s" : ""}`);
+  } else {
+    parts.push(`⚠ ${totalIssues} warning${totalIssues > 1 ? "s" : ""}`);
+  }
 
-  const budget = formatBudgetSummary(data);
-  if (budget) details.push(budget);
+  if (data.budgetCeiling !== undefined && data.budgetCeiling > 0) {
+    const pct = Math.min(100, (data.budgetSpent / data.budgetCeiling) * 100);
+    parts.push(`Budget: ${formatCost(data.budgetSpent)}/${formatCost(data.budgetCeiling)} (${pct.toFixed(0)}%)`);
+  } else if (data.budgetSpent > 0) {
+    parts.push(`Spent: ${formatCost(data.budgetSpent)}`);
+  }
 
-  if (data.eta) details.push(data.eta);
+  if (data.providerIssue) {
+    parts.push(data.providerIssue);
+  }
 
-  if (details.length > 0) {
-    lines.push(`  ${details.join("  │  ")}`);
+  if (data.environmentErrorCount > 0) {
+    parts.push(`Env: ${data.environmentErrorCount} error${data.environmentErrorCount > 1 ? "s" : ""}`);
+  } else if (data.environmentWarningCount > 0) {
+    parts.push(`Env: ${data.environmentWarningCount} warning${data.environmentWarningCount > 1 ? "s" : ""}`);
   }
 
-  return lines;
+  return [`  ${parts.join("  │  ")}`];
 }

package/src/resources/extensions/gsd/health-widget.ts

@@ -16,7 +16,6 @@ import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { loadLedgerFromDisk, getProjectTotals } from "./metrics.js";
 import { describeNextUnit, estimateTimeRemaining, updateSliceProgressCache } from "./auto-dashboard.js";
 import { projectRoot } from "./commands.js";
-import { deriveState, invalidateStateCache } from "./state.js";
 import {
   buildHealthLines,
   detectHealthWidgetProjectState,
@@ -25,7 +24,7 @@ import {
 
 // ── Data loader ────────────────────────────────────────────────────────────────
 
-function loadBaseHealthWidgetData(basePath: string): HealthWidgetData {
+function loadHealthWidgetData(basePath: string): HealthWidgetData {
   let budgetCeiling: number | undefined;
   let budgetSpent = 0;
   let providerIssue: string | null = null;
@@ -69,90 +68,6 @@ function loadBaseHealthWidgetData(basePath: string): HealthWidgetData {
   };
 }
 
-function compactText(text: string, max = 64): string {
-  const trimmed = text.replace(/\s+/g, " ").trim();
-  if (trimmed.length <= max) return trimmed;
-  return `${trimmed.slice(0, max - 1).trimEnd()}…`;
-}
-
-function summarizeExecutionStatus(state: GSDState): string {
-  switch (state.phase) {
-    case "blocked": return "Blocked";
-    case "paused": return "Paused";
-    case "complete": return "Complete";
-    case "executing": return "Executing";
-    case "planning": return "Planning";
-    case "pre-planning": return "Pre-planning";
-    case "summarizing": return "Summarizing";
-    case "validating-milestone": return "Validating";
-    case "completing-milestone": return "Completing";
-    case "needs-discussion": return "Needs discussion";
-    case "replanning-slice": return "Replanning";
-    default: return "Active";
-  }
-}
-
-function summarizeExecutionTarget(state: GSDState): string {
-  switch (state.phase) {
-    case "needs-discussion":
-      return state.activeMilestone ? `Discuss ${state.activeMilestone.id}` : "Discuss milestone draft";
-    case "pre-planning":
-      return state.activeMilestone ? `Plan ${state.activeMilestone.id}` : "Research & plan milestone";
-    case "planning":
-      return state.activeSlice ? `Plan ${state.activeSlice.id}` : "Plan next slice";
-    case "executing":
-      return state.activeTask ? `Execute ${state.activeTask.id}` : "Execute next task";
-    case "summarizing":
-      return state.activeSlice ? `Complete ${state.activeSlice.id}` : "Complete current slice";
-    case "validating-milestone":
-      return state.activeMilestone ? `Validate ${state.activeMilestone.id}` : "Validate milestone";
-    case "completing-milestone":
-      return state.activeMilestone ? `Complete ${state.activeMilestone.id}` : "Complete milestone";
-    case "replanning-slice":
-      return state.activeSlice ? `Replan ${state.activeSlice.id}` : "Replan current slice";
-    case "blocked":
-      return `waiting on ${compactText(state.blockers[0] ?? state.nextAction, 56)}`;
-    case "paused":
-      return compactText(state.nextAction || "waiting to resume", 56);
-    case "complete":
-      return "All milestones complete";
-    default:
-      return compactText(describeNextUnit(state).label, 56);
-  }
-}
-
-async function enrichHealthWidgetData(basePath: string, baseData: HealthWidgetData): Promise<HealthWidgetData> {
-  if (baseData.projectState !== "active") return baseData;
-
-  try {
-    invalidateStateCache();
-    const state = await deriveState(basePath);
-
-    if (state.activeMilestone) {
-      // Warm the slice-progress cache so estimateTimeRemaining() has data
-      updateSliceProgressCache(basePath, state.activeMilestone.id, state.activeSlice?.id);
-    }
-
-    return {
-      ...baseData,
-      executionPhase: state.phase,
-      executionStatus: summarizeExecutionStatus(state),
-      executionTarget: summarizeExecutionTarget(state),
-      nextAction: state.nextAction,
-      blocker: state.blockers[0] ?? null,
-      activeMilestoneId: state.activeMilestone?.id,
-      activeSliceId: state.activeSlice?.id,
-      activeTaskId: state.activeTask?.id,
-      progress: state.progress,
-      eta: state.phase === "blocked" || state.phase === "paused" || state.phase === "complete"
-        ? null
-        : estimateTimeRemaining(),
-    };
-  } catch {
-    return baseData;
-  }
-}
-
 // ── Widget init ────────────────────────────────────────────────────────────────
 
 const REFRESH_INTERVAL_MS = 60_000;
@@ -167,7 +82,7 @@ export function initHealthWidget(ctx: ExtensionContext): void {
   const basePath = projectRoot();
 
   // String-array fallback — used in RPC mode (factory is a no-op there)
-  const initialData = loadBaseHealthWidgetData(basePath);
+  const initialData = loadHealthWidgetData(basePath);
   ctx.ui.setWidget("gsd-health", buildHealthLines(initialData), { placement: "belowEditor" });
 
   // Factory-based widget for TUI mode — replaces the string-array above
@@ -180,8 +95,7 @@ export function initHealthWidget(ctx: ExtensionContext): void {
       if (refreshInFlight) return;
       refreshInFlight = true;
       try {
-        const baseData = loadBaseHealthWidgetData(basePath);
-        data = await enrichHealthWidgetData(basePath, baseData);
+        data = loadHealthWidgetData(basePath);
         cachedLines = undefined;
         _tui.requestRender();
       } catch { /* non-fatal */ } finally {

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

@@ -6,11 +6,13 @@
  * symlink replaces the original directory so all paths remain valid.
  */
 
+import { execFileSync } from "node:child_process";
 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";
+import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 
 export interface MigrationResult {
   migrated: boolean;
@@ -144,7 +146,22 @@ export function migrateToExternalState(basePath: string): MigrationResult {
       return { migrated: false, error: `Migration verification failed: ${getErrorMessage(verifyErr)}` };
     }
 
-    // Remove .gsd.migrating only after symlink is verified
+    // Clean the git index — any .gsd/* files tracked before migration now
+    // sit behind the symlink and git can't follow it, causing them to show
+    // as deleted. Remove them from the index so the working tree stays clean.
+    // --ignore-unmatch makes this a no-op on fresh projects with no tracked .gsd/.
+    try {
+      execFileSync("git", ["rm", "-r", "--cached", "--ignore-unmatch", ".gsd"], {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "ignore"],
+        env: GIT_NO_PROMPT_ENV,
+        timeout: 10_000,
+      });
+    } catch {
+      // Non-fatal — git may be unavailable or nothing was tracked
+    }
+
+    // Remove .gsd.migrating only after symlink is verified and index is clean
     rmSync(migratingPath, { recursive: true, force: true });
 
     return { migrated: true };

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

@@ -14,7 +14,6 @@ import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
-const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 import { gsdRoot } from "./paths.js";
 import { parse as parseYaml } from "yaml";
 import type { PostUnitHookConfig, PreDispatchHookConfig, TokenProfile } from "./types.js";
@@ -83,24 +82,36 @@ export {
 
 // ─── Path Constants & Getters ───────────────────────────────────────────────
 
-const GLOBAL_PREFERENCES_PATH = join(gsdHome, "preferences.md");
-const LEGACY_GLOBAL_PREFERENCES_PATH = join(homedir(), ".pi", "agent", "gsd-preferences.md");
+function gsdHome(): string {
+  return process.env.GSD_HOME || join(homedir(), ".gsd");
+}
+
+function globalPreferencesPath(): string {
+  return join(gsdHome(), "preferences.md");
+}
+
+function legacyGlobalPreferencesPath(): string {
+  return join(homedir(), ".pi", "agent", "gsd-preferences.md");
+}
+
 function projectPreferencesPath(): string {
   return join(gsdRoot(process.cwd()), "preferences.md");
 }
 // Bootstrap in gitignore.ts historically created PREFERENCES.md (uppercase) by mistake.
 // Check uppercase as a fallback so those files aren't silently ignored.
-const GLOBAL_PREFERENCES_PATH_UPPERCASE = join(gsdHome, "PREFERENCES.md");
+function globalPreferencesPathUppercase(): string {
+  return join(gsdHome(), "PREFERENCES.md");
+}
 function projectPreferencesPathUppercase(): string {
   return join(gsdRoot(process.cwd()), "PREFERENCES.md");
 }
 
 export function getGlobalGSDPreferencesPath(): string {
-  return GLOBAL_PREFERENCES_PATH;
+  return globalPreferencesPath();
 }
 
 export function getLegacyGlobalGSDPreferencesPath(): string {
-  return LEGACY_GLOBAL_PREFERENCES_PATH;
+  return legacyGlobalPreferencesPath();
 }
 
 export function getProjectGSDPreferencesPath(): string {
@@ -110,9 +121,9 @@ export function getProjectGSDPreferencesPath(): string {
 // ─── Loading ────────────────────────────────────────────────────────────────
 
 export function loadGlobalGSDPreferences(): LoadedGSDPreferences | null {
-  return loadPreferencesFile(GLOBAL_PREFERENCES_PATH, "global")
-    ?? loadPreferencesFile(GLOBAL_PREFERENCES_PATH_UPPERCASE, "global")
-    ?? loadPreferencesFile(LEGACY_GLOBAL_PREFERENCES_PATH, "global");
+  return loadPreferencesFile(globalPreferencesPath(), "global")
+    ?? loadPreferencesFile(globalPreferencesPathUppercase(), "global")
+    ?? loadPreferencesFile(legacyGlobalPreferencesPath(), "global");
 }
 
 export function loadProjectGSDPreferences(): LoadedGSDPreferences | null {

package/src/resources/extensions/gsd/prompt-loader.ts

@@ -78,6 +78,11 @@ export function loadPrompt(name: string, vars: Record<string, string> = {}): str
     templateCache.set(name, content);
   }
 
+  const effectiveVars = {
+    skillActivation: "If a `GSD Skill Preferences` block is present in system context, use it and the `<available_skills>` catalog in your system prompt to decide which skills to load and follow for this unit, without relaxing required verification or artifact rules.",
+    ...vars,
+  };
+
   // Check BEFORE substitution: find all {{varName}} placeholders the template
   // declares and verify every one has a value in vars. Checking after substitution
   // would also flag {{...}} patterns injected by inlined content (e.g. template
@@ -86,7 +91,7 @@ export function loadPrompt(name: string, vars: Record<string, string> = {}): str
   if (declared) {
     const missing = [...new Set(declared)]
       .map(m => m.slice(2, -2))
-      .filter(key => !(key in vars));
+      .filter(key => !(key in effectiveVars));
     if (missing.length > 0) {
       throw new GSDError(
         GSD_PARSE_ERROR,
@@ -97,7 +102,7 @@ export function loadPrompt(name: string, vars: Record<string, string> = {}): str
     }
   }
 
-  for (const [key, value] of Object.entries(vars)) {
+  for (const [key, value] of Object.entries(effectiveVars)) {
     content = content.replaceAll(`{{${key}}}`, value);
   }
 

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

@@ -16,7 +16,7 @@ All relevant context has been preloaded below — the roadmap, all slice summari
 
 Then:
 1. Use the **Milestone Summary** output template from the inlined context above
-2. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during completion, without relaxing required verification or artifact rules
+2. {{skillActivation}}
 3. Verify each **success criterion** from the milestone definition in `{{roadmapPath}}`. For each criterion, confirm it was met with specific evidence from slice summaries, test results, or observable behavior. List any criterion that was NOT met.
 4. Verify the milestone's **definition of done** — all slices are `[x]`, all slice summaries exist, and any cross-slice integration points work correctly.
 5. 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.