gsd-pi 2.29.0-dev.2ccf3fb → 2.29.0-dev.4c155ee

package/src/resources/extensions/gsd/mechanical-completion.ts

@@ -0,0 +1,430 @@
+/**
+ * Mechanical Completion — deterministic post-verification artifact generation.
+ *
+ * Pure functions that aggregate task-level outputs into slice/milestone summaries,
+ * UAT stubs, roadmap checkbox updates, and validation reports. Zero orchestration
+ * dependencies — operates on filesystem paths and parsed structures only.
+ *
+ * ADR-003: replaces LLM-driven complete-slice and validate-milestone units with
+ * mechanical aggregation when the data is sufficient.
+ */
+
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteSync } from "./atomic-write.js";
+import { loadFile, parseSummary } from "./files.js";
+import { extractMarkdownSection } from "./auto-prompts.js";
+import {
+  resolveTaskFiles,
+  resolveTaskJsonFiles,
+  resolveTasksDir,
+  resolveSliceFile,
+  resolveSlicePath,
+  resolveMilestoneFile,
+  resolveMilestonePath,
+  resolveGsdRootFile,
+} from "./paths.js";
+import type { Summary, SummaryFrontmatter } from "./types.js";
+import type { EvidenceJSON } from "./verification-evidence.js";
+
+// ─── Slice Completion ────────────────────────────────────────────────────────
+
+/**
+ * Mechanically complete a slice by aggregating task summaries into:
+ * - S##-SUMMARY.md (aggregated frontmatter + task one-liners)
+ * - S##-UAT.md (extracted from plan Verification section)
+ * - Roadmap checkbox [x] update
+ *
+ * Returns true if completion succeeded, false if data is insufficient
+ * (serves as quality gate — caller falls back to LLM completion).
+ */
+export async function mechanicalSliceCompletion(
+  base: string, mid: string, sid: string,
+): Promise<boolean> {
+  const tDir = resolveTasksDir(base, mid, sid);
+  if (!tDir) return false;
+
+  // Read all task summaries
+  const summaryFiles = resolveTaskFiles(tDir, "SUMMARY");
+  if (summaryFiles.length === 0) return false;
+
+  const taskSummaries: Array<{ taskId: string; summary: Summary }> = [];
+  for (const file of summaryFiles) {
+    const content = readFileSync(join(tDir, file), "utf-8");
+    if (!content.trim()) continue;
+    const summary = parseSummary(content);
+    const taskId = file.match(/^(T\d+)/)?.[1] ?? file;
+    taskSummaries.push({ taskId, summary });
+  }
+
+  if (taskSummaries.length === 0) return false;
+
+  // Quality gate: multi-task slices need substantive summaries
+  if (taskSummaries.length > 1) {
+    const totalContent = taskSummaries
+      .map(ts => ts.summary.whatHappened || ts.summary.oneLiner || "")
+      .join("");
+    if (totalContent.length < 200) return false;
+  }
+
+  // Aggregate frontmatter
+  const aggregated = aggregateFrontmatter(taskSummaries.map(ts => ts.summary.frontmatter));
+
+  // Build SUMMARY.md
+  const summaryLines: string[] = [
+    "---",
+    `id: ${sid}`,
+    `parent: ${mid}`,
+    `milestone: ${mid}`,
+  ];
+  if (aggregated.provides.length > 0)
+    summaryLines.push(`provides:\n${aggregated.provides.map(p => `  - ${p}`).join("\n")}`);
+  if (aggregated.key_files.length > 0)
+    summaryLines.push(`key_files:\n${aggregated.key_files.map(f => `  - ${f}`).join("\n")}`);
+  if (aggregated.key_decisions.length > 0)
+    summaryLines.push(`key_decisions:\n${aggregated.key_decisions.map(d => `  - ${d}`).join("\n")}`);
+  if (aggregated.patterns_established.length > 0)
+    summaryLines.push(`patterns_established:\n${aggregated.patterns_established.map(p => `  - ${p}`).join("\n")}`);
+  if (aggregated.affects.length > 0)
+    summaryLines.push(`affects:\n${aggregated.affects.map(a => `  - ${a}`).join("\n")}`);
+  if (aggregated.observability_surfaces.length > 0)
+    summaryLines.push(`observability_surfaces:\n${aggregated.observability_surfaces.map(o => `  - ${o}`).join("\n")}`);
+  const allPassed = taskSummaries.every(ts => ts.summary.frontmatter.verification_result === "passed");
+  summaryLines.push(`verification_result: ${allPassed ? "passed" : "mixed"}`);
+  summaryLines.push(`completed_at: ${new Date().toISOString()}`);
+  summaryLines.push("---");
+  summaryLines.push("");
+  summaryLines.push(`# ${sid}: Slice Summary`);
+  summaryLines.push("");
+
+  // Task one-liners
+  for (const { taskId, summary } of taskSummaries) {
+    const line = summary.oneLiner || summary.title || taskId;
+    summaryLines.push(`- **${taskId}**: ${line}`);
+  }
+  summaryLines.push("");
+
+  const sDir = resolveSlicePath(base, mid, sid);
+  if (!sDir) return false;
+
+  const summaryPath = join(sDir, `${sid}-SUMMARY.md`);
+  atomicWriteSync(summaryPath, summaryLines.join("\n"));
+  process.stderr.write(`gsd-mechanical: wrote ${summaryPath}\n`);
+
+  // Build UAT.md from plan's Verification section
+  const planPath = resolveSliceFile(base, mid, sid, "PLAN");
+  if (planPath) {
+    const planContent = readFileSync(planPath, "utf-8");
+    const verification = extractMarkdownSection(planContent, "Verification");
+    if (verification) {
+      const uatContent = [
+        "---",
+        `id: ${sid}`,
+        `parent: ${mid}`,
+        "type: artifact-driven",
+        "---",
+        "",
+        `# ${sid}: UAT`,
+        "",
+        verification,
+        "",
+      ].join("\n");
+      const uatPath = join(sDir, `${sid}-UAT.md`);
+      atomicWriteSync(uatPath, uatContent);
+      process.stderr.write(`gsd-mechanical: wrote ${uatPath}\n`);
+    }
+  }
+
+  // Mark slice [x] in ROADMAP
+  await markSliceInRoadmap(base, mid, sid);
+
+  // Append new decisions if any
+  await appendNewDecisions(base, taskSummaries.map(ts => ts.summary));
+
+  // Update requirements if all passed
+  if (allPassed) {
+    await mechanicalRequirementsUpdate(base, mid, sid, taskSummaries.map(ts => ts.summary));
+  }
+
+  return true;
+}
+
+// ─── Requirements Update ─────────────────────────────────────────────────────
+
+/**
+ * Conservative requirements update: mark requirements Validated only if
+ * all tasks' verification passed.
+ */
+export async function mechanicalRequirementsUpdate(
+  _base: string, _mid: string, _sid: string, _taskSummaries: Summary[],
+): Promise<void> {
+  // Conservative: requirements validation requires human or LLM judgment
+  // about whether the requirement is truly met. Mechanical completion only
+  // marks the slice done — requirement status updates are left to the
+  // existing validation pipeline.
+}
+
+// ─── Decision Aggregation ────────────────────────────────────────────────────
+
+/**
+ * Collect key_decisions from task summaries, deduplicate against existing
+ * DECISIONS.md, and append new ones.
+ */
+export async function appendNewDecisions(
+  base: string, taskSummaries: Summary[],
+): Promise<void> {
+  const allDecisions = taskSummaries.flatMap(s => s.frontmatter.key_decisions);
+  if (allDecisions.length === 0) return;
+
+  const decisionsPath = resolveGsdRootFile(base, "DECISIONS");
+  const existing = existsSync(decisionsPath)
+    ? readFileSync(decisionsPath, "utf-8")
+    : "";
+
+  // Deduplicate — skip decisions whose text already appears in the file
+  const newDecisions = allDecisions.filter(d =>
+    d.trim() && !existing.includes(d.trim()),
+  );
+  if (newDecisions.length === 0) return;
+
+  const entries = newDecisions
+    .map(d => `- ${d} _(auto-aggregated from task summaries)_`)
+    .join("\n");
+
+  const updated = existing.trimEnd() + "\n\n### Auto-aggregated Decisions\n\n" + entries + "\n";
+  atomicWriteSync(decisionsPath, updated);
+  process.stderr.write(`gsd-mechanical: appended ${newDecisions.length} decision(s) to DECISIONS.md\n`);
+}
+
+// ─── Milestone Verification ──────────────────────────────────────────────────
+
+export interface MilestoneVerificationResult {
+  verdict: "passed" | "failed" | "mixed";
+  checks: EvidenceJSON[];
+  uatResults: string[];
+  markdown: string;
+}
+
+/**
+ * Aggregate T##-VERIFY.json files and S##-UAT-RESULT.md files across all
+ * slices in a milestone to produce VALIDATION.md.
+ */
+export async function aggregateMilestoneVerification(
+  base: string, mid: string,
+): Promise<MilestoneVerificationResult> {
+  const mDir = resolveMilestonePath(base, mid);
+  if (!mDir) return { verdict: "failed", checks: [], uatResults: [], markdown: "" };
+
+  const allChecks: EvidenceJSON[] = [];
+  const allUatResults: string[] = [];
+
+  // Scan all slices
+  const slicesDir = join(mDir, "slices");
+  if (!existsSync(slicesDir)) return { verdict: "failed", checks: [], uatResults: [], markdown: "" };
+
+  const sliceDirs = readdirSyncSafe(slicesDir).filter(name => /^S\d+/i.test(name)).sort();
+
+  for (const sliceName of sliceDirs) {
+    const sid = sliceName.match(/^(S\d+)/i)?.[1] ?? sliceName;
+    const tDir = resolveTasksDir(base, mid, sid);
+    if (tDir) {
+      const verifyFiles = resolveTaskJsonFiles(tDir, "VERIFY");
+      for (const vf of verifyFiles) {
+        try {
+          const content = readFileSync(join(tDir, vf), "utf-8");
+          const evidence = JSON.parse(content) as EvidenceJSON;
+          allChecks.push(evidence);
+        } catch {
+          // Skip malformed JSON
+        }
+      }
+    }
+
+    // Check for UAT result
+    const uatResultPath = resolveSliceFile(base, mid, sid, "UAT-RESULT");
+    if (uatResultPath) {
+      try {
+        const uatContent = readFileSync(uatResultPath, "utf-8");
+        allUatResults.push(`### ${sid}\n\n${uatContent}`);
+      } catch {
+        // Non-fatal
+      }
+    }
+  }
+
+  // Determine verdict
+  const allPassed = allChecks.length > 0 && allChecks.every(c => c.passed);
+  const anyFailed = allChecks.some(c => !c.passed);
+  const verdict: "passed" | "failed" | "mixed" = allPassed
+    ? "passed"
+    : anyFailed
+      ? (allChecks.some(c => c.passed) ? "mixed" : "failed")
+      : "passed"; // No checks = vacuously passed
+
+  // Build VALIDATION.md
+  const mdLines: string[] = [
+    "---",
+    `milestone: ${mid}`,
+    `verdict: ${verdict}`,
+    "remediation_round: 0",
+    `validated_at: ${new Date().toISOString()}`,
+    "---",
+    "",
+    `# ${mid}: Milestone Validation`,
+    "",
+    `**Verdict:** ${verdict}`,
+    "",
+    "## Verification Results",
+    "",
+  ];
+
+  if (allChecks.length === 0) {
+    mdLines.push("_No verification evidence found._");
+  } else {
+    mdLines.push("| Task | Passed | Checks | Failed |");
+    mdLines.push("|------|--------|--------|--------|");
+    for (const check of allChecks) {
+      const failedCount = check.checks.filter(c => c.verdict === "fail").length;
+      mdLines.push(
+        `| ${check.taskId} | ${check.passed ? "yes" : "no"} | ${check.checks.length} | ${failedCount} |`,
+      );
+    }
+  }
+
+  if (allUatResults.length > 0) {
+    mdLines.push("");
+    mdLines.push("## UAT Results");
+    mdLines.push("");
+    mdLines.push(...allUatResults);
+  }
+
+  mdLines.push("");
+
+  const markdown = mdLines.join("\n");
+
+  // Write VALIDATION.md
+  const validationPath = join(mDir, `${mid}-VALIDATION.md`);
+  atomicWriteSync(validationPath, markdown);
+  process.stderr.write(`gsd-mechanical: wrote ${validationPath}\n`);
+
+  return { verdict, checks: allChecks, uatResults: allUatResults, markdown };
+}
+
+// ─── Milestone Summary ──────────────────────────────────────────────────────
+
+/**
+ * Read all S##-SUMMARY.md files and produce M##-SUMMARY.md.
+ */
+export async function generateMilestoneSummary(
+  base: string, mid: string,
+): Promise<string> {
+  const mDir = resolveMilestonePath(base, mid);
+  if (!mDir) return "";
+
+  const slicesDir = join(mDir, "slices");
+  if (!existsSync(slicesDir)) return "";
+
+  const sliceDirs = readdirSyncSafe(slicesDir).filter(name => /^S\d+/i.test(name)).sort();
+
+  const aggregatedProvides: string[] = [];
+  const aggregatedKeyFiles: string[] = [];
+  const aggregatedKeyDecisions: string[] = [];
+  const aggregatedPatterns: string[] = [];
+  const sliceOneLinerList: string[] = [];
+
+  for (const sliceName of sliceDirs) {
+    const sid = sliceName.match(/^(S\d+)/i)?.[1] ?? sliceName;
+    const summaryPath = resolveSliceFile(base, mid, sid, "SUMMARY");
+    if (!summaryPath) continue;
+
+    try {
+      const content = readFileSync(summaryPath, "utf-8");
+      const summary = parseSummary(content);
+      aggregatedProvides.push(...summary.frontmatter.provides);
+      aggregatedKeyFiles.push(...summary.frontmatter.key_files);
+      aggregatedKeyDecisions.push(...summary.frontmatter.key_decisions);
+      aggregatedPatterns.push(...summary.frontmatter.patterns_established);
+      sliceOneLinerList.push(`- **${sid}**: ${summary.oneLiner || summary.title || sid}`);
+    } catch {
+      sliceOneLinerList.push(`- **${sid}**: _(summary unavailable)_`);
+    }
+  }
+
+  const mdLines: string[] = [
+    "---",
+    `id: ${mid}`,
+  ];
+  if (dedup(aggregatedProvides).length > 0)
+    mdLines.push(`provides:\n${dedup(aggregatedProvides).map(p => `  - ${p}`).join("\n")}`);
+  if (dedup(aggregatedKeyFiles).length > 0)
+    mdLines.push(`key_files:\n${dedup(aggregatedKeyFiles).map(f => `  - ${f}`).join("\n")}`);
+  if (dedup(aggregatedKeyDecisions).length > 0)
+    mdLines.push(`key_decisions:\n${dedup(aggregatedKeyDecisions).map(d => `  - ${d}`).join("\n")}`);
+  if (dedup(aggregatedPatterns).length > 0)
+    mdLines.push(`patterns_established:\n${dedup(aggregatedPatterns).map(p => `  - ${p}`).join("\n")}`);
+  mdLines.push(`completed_at: ${new Date().toISOString()}`);
+  mdLines.push("---");
+  mdLines.push("");
+  mdLines.push(`# ${mid}: Milestone Summary`);
+  mdLines.push("");
+  mdLines.push("## Slices");
+  mdLines.push("");
+  mdLines.push(...sliceOneLinerList);
+  mdLines.push("");
+
+  const content = mdLines.join("\n");
+
+  // Write M##-SUMMARY.md
+  const summaryPath = join(mDir, `${mid}-SUMMARY.md`);
+  atomicWriteSync(summaryPath, content);
+  process.stderr.write(`gsd-mechanical: wrote ${summaryPath}\n`);
+
+  return content;
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function aggregateFrontmatter(fms: SummaryFrontmatter[]): {
+  provides: string[];
+  key_files: string[];
+  key_decisions: string[];
+  patterns_established: string[];
+  affects: string[];
+  observability_surfaces: string[];
+} {
+  return {
+    provides: dedup(fms.flatMap(f => f.provides)),
+    key_files: dedup(fms.flatMap(f => f.key_files)),
+    key_decisions: dedup(fms.flatMap(f => f.key_decisions)),
+    patterns_established: dedup(fms.flatMap(f => f.patterns_established)),
+    affects: dedup(fms.flatMap(f => f.affects)),
+    observability_surfaces: dedup(fms.flatMap(f => f.observability_surfaces)),
+  };
+}
+
+function dedup(arr: string[]): string[] {
+  return [...new Set(arr.filter(s => s.trim()))];
+}
+
+async function markSliceInRoadmap(base: string, mid: string, sid: string): Promise<void> {
+  const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
+  if (!roadmapPath) return;
+  const content = await loadFile(roadmapPath);
+  if (!content) return;
+  const updated = content.replace(
+    new RegExp(`^(\\s*-\\s+)\\[ \\]\\s+\\*\\*${sid}:`, "m"),
+    `$1[x] **${sid}:`,
+  );
+  if (updated !== content) {
+    atomicWriteSync(roadmapPath, updated);
+    process.stderr.write(`gsd-mechanical: marked ${sid} done in ROADMAP\n`);
+  }
+}
+
+function readdirSyncSafe(dir: string): string[] {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}

package/src/resources/extensions/gsd/migrate/command.ts

@@ -12,6 +12,7 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
 import { existsSync, readFileSync } from "node:fs";
 import { resolve, join, dirname } from "node:path";
+import { gsdRoot } from "../paths.js";
 import { fileURLToPath } from "node:url";
 import { showNextAction } from "../../shared/mod.js";
 import {
@@ -144,7 +145,7 @@ export async function handleMigrate(
     );
   }
 
-  const targetGsdExists = existsSync(join(process.cwd(), ".gsd"));
+  const targetGsdExists = existsSync(gsdRoot(process.cwd()));
   if (targetGsdExists) {
     lines.push("");
     lines.push("⚠ A .gsd directory already exists in the current working directory — it will be overwritten.");
@@ -179,7 +180,7 @@ export async function handleMigrate(
   ctx.ui.notify("Writing .gsd directory…", "info");
 
   const result = await writeGSDDirectory(project, process.cwd());
-  const gsdPath = join(process.cwd(), ".gsd");
+  const gsdPath = gsdRoot(process.cwd());
 
   ctx.ui.notify(
     `✓ Migration complete — ${result.paths.length} file(s) written to .gsd/`,

package/src/resources/extensions/gsd/migrate/writer.ts

@@ -5,6 +5,7 @@
 
 import { join } from 'node:path';
 import { saveFile } from '../files.js';
+import { gsdRoot } from '../paths.js';
 
 import type {
   GSDMilestone,
@@ -421,7 +422,7 @@ export async function writeGSDDirectory(
   project: GSDProject,
   targetPath: string,
 ): Promise<WrittenFiles> {
-  const gsdDir = join(targetPath, '.gsd');
+  const gsdDir = gsdRoot(targetPath);
   const milestonesBase = join(gsdDir, 'milestones');
   const paths: string[] = [];
   const counts: WrittenFiles['counts'] = {

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

@@ -0,0 +1,123 @@
+/**
+ * GSD External State Migration
+ *
+ * Migrates legacy in-project `.gsd/` directories to the external
+ * `~/.gsd/projects/<hash>/` state directory. After migration, a
+ * symlink replaces the original directory so all paths remain valid.
+ */
+
+import { existsSync, lstatSync, mkdirSync, readdirSync, renameSync, cpSync, rmSync, symlinkSync } from "node:fs";
+import { join } from "node:path";
+import { externalGsdRoot } from "./repo-identity.js";
+
+export interface MigrationResult {
+  migrated: boolean;
+  error?: string;
+}
+
+/**
+ * Migrate a legacy in-project `.gsd/` directory to external storage.
+ *
+ * Algorithm:
+ * 1. If `<project>/.gsd` is a symlink or doesn't exist -> skip
+ * 2. If `<project>/.gsd` is a real directory:
+ *    a. Compute external path from repoIdentity
+ *    b. mkdir -p external dir
+ *    c. Rename `.gsd` -> `.gsd.migrating` (atomic on same FS, acts as lock)
+ *    d. Copy contents to external dir (skip `worktrees/` subdirectory)
+ *    e. Create symlink `.gsd -> external path`
+ *    f. Remove `.gsd.migrating`
+ * 3. On failure: rename `.gsd.migrating` back to `.gsd` (rollback)
+ */
+export function migrateToExternalState(basePath: string): MigrationResult {
+  const localGsd = join(basePath, ".gsd");
+
+  // Skip if doesn't exist
+  if (!existsSync(localGsd)) {
+    return { migrated: false };
+  }
+
+  // Skip if already a symlink
+  try {
+    const stat = lstatSync(localGsd);
+    if (stat.isSymbolicLink()) {
+      return { migrated: false };
+    }
+    if (!stat.isDirectory()) {
+      return { migrated: false, error: ".gsd exists but is not a directory or symlink" };
+    }
+  } catch (err) {
+    return { migrated: false, error: `Cannot stat .gsd: ${err instanceof Error ? err.message : String(err)}` };
+  }
+
+  const externalPath = externalGsdRoot(basePath);
+  const migratingPath = join(basePath, ".gsd.migrating");
+
+  try {
+    // mkdir -p the external dir
+    mkdirSync(externalPath, { recursive: true });
+
+    // Rename .gsd -> .gsd.migrating (atomic lock)
+    renameSync(localGsd, migratingPath);
+
+    // Copy contents to external dir, skipping worktrees/
+    const entries = readdirSync(migratingPath, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name === "worktrees") continue; // worktrees stay local
+
+      const src = join(migratingPath, entry.name);
+      const dst = join(externalPath, entry.name);
+
+      try {
+        if (entry.isDirectory()) {
+          cpSync(src, dst, { recursive: true, force: true });
+        } else {
+          cpSync(src, dst, { force: true });
+        }
+      } catch {
+        // Non-fatal: continue with other files
+      }
+    }
+
+    // Create symlink .gsd -> external path
+    symlinkSync(externalPath, localGsd, "junction");
+
+    // Remove .gsd.migrating
+    rmSync(migratingPath, { recursive: true, force: true });
+
+    return { migrated: true };
+  } catch (err) {
+    // Rollback: rename .gsd.migrating back to .gsd
+    try {
+      if (existsSync(migratingPath) && !existsSync(localGsd)) {
+        renameSync(migratingPath, localGsd);
+      }
+    } catch {
+      // Rollback failed -- leave .gsd.migrating for doctor to detect
+    }
+
+    return {
+      migrated: false,
+      error: `Migration failed: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+/**
+ * Recover from a failed migration (`.gsd.migrating` exists).
+ * Moves `.gsd.migrating` back to `.gsd` if `.gsd` doesn't exist.
+ */
+export function recoverFailedMigration(basePath: string): boolean {
+  const localGsd = join(basePath, ".gsd");
+  const migratingPath = join(basePath, ".gsd.migrating");
+
+  if (!existsSync(migratingPath)) return false;
+  if (existsSync(localGsd)) return false; // both exist -- ambiguous, don't touch
+
+  try {
+    renameSync(migratingPath, localGsd);
+    return true;
+  } catch {
+    return false;
+  }
+}

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

@@ -9,7 +9,7 @@
  * via prefix matching, so existing projects work without migration.
  */
 
-import { readdirSync, existsSync, Dirent } from "node:fs";
+import { readdirSync, existsSync, realpathSync, Dirent } from "node:fs";
 import { join } from "node:path";
 import { nativeScanGsdTree, type GsdTreeEntry } from "./native-parser-bridge.js";
 import { DIR_CACHE_MAX } from "./constants.js";
@@ -236,6 +236,23 @@ export function resolveTaskFiles(tasksDir: string, suffix: string): string[] {
   }
 }
 
+/**
+ * Find all task JSON files matching a pattern in a tasks directory.
+ * Returns sorted file names matching T##-SUFFIX.json or legacy T##-*-SUFFIX.json
+ */
+export function resolveTaskJsonFiles(tasksDir: string, suffix: string): string[] {
+  if (!existsSync(tasksDir)) return [];
+  try {
+    const currentPattern = new RegExp(`^T\\d+-${suffix}\\.json$`, "i");
+    const legacyPattern = new RegExp(`^T\\d+-.*-${suffix}\\.json$`, "i");
+    return cachedReaddir(tasksDir)
+      .filter(f => currentPattern.test(f) || legacyPattern.test(f))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
 // ─── Full Path Builders ────────────────────────────────────────────────────
 
 export const GSD_ROOT_FILES = {
@@ -261,7 +278,12 @@ const LEGACY_GSD_ROOT_FILES: Record<GSDRootFileKey, string> = {
 };
 
 export function gsdRoot(basePath: string): string {
-  return join(basePath, ".gsd");
+  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
 }
 
 export function milestonesDir(basePath: string): string {

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

@@ -14,6 +14,7 @@ import type {
 import { resolvePostUnitHooks, resolvePreDispatchHooks } from "./preferences.js";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { gsdRoot } from "./paths.js";
 
 // ─── Hook Queue State ──────────────────────────────────────────────────────
 
@@ -210,13 +211,13 @@ export function resolveHookArtifactPath(basePath: string, unitId: string, artifa
   const parts = unitId.split("/");
   if (parts.length === 3) {
     const [mid, sid, tid] = parts;
-    return join(basePath, ".gsd", mid, "slices", sid, "tasks", `${tid}-${artifactName}`);
+    return join(gsdRoot(basePath), mid, "slices", sid, "tasks", `${tid}-${artifactName}`);
   }
   if (parts.length === 2) {
     const [mid, sid] = parts;
-    return join(basePath, ".gsd", mid, "slices", sid, artifactName);
+    return join(gsdRoot(basePath), mid, "slices", sid, artifactName);
   }
-  return join(basePath, ".gsd", parts[0], artifactName);
+  return join(gsdRoot(basePath), parts[0], artifactName);
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -310,7 +311,7 @@ export function runPreDispatchHooks(
 const HOOK_STATE_FILE = "hook-state.json";
 
 function hookStatePath(basePath: string): string {
-  return join(basePath, ".gsd", HOOK_STATE_FILE);
+  return join(gsdRoot(basePath), HOOK_STATE_FILE);
 }
 
 /**
@@ -323,7 +324,7 @@ export function persistHookState(basePath: string): void {
     savedAt: new Date().toISOString(),
   };
   try {
-    const dir = join(basePath, ".gsd");
+    const dir = gsdRoot(basePath);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     writeFileSync(hookStatePath(basePath), JSON.stringify(state, null, 2), "utf-8");
   } catch {