@opengsd/gsd-pi 1.5.0-dev.553dc518 → 1.5.0-dev.c4c8885f

package/dist/resources/extensions/gsd/rule-registry.js

@@ -8,21 +8,53 @@
 import { logWarning } from "./workflow-logger.js";
 import { resolvePostUnitHooks, resolvePreDispatchHooks } from "./preferences.js";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { parseUnitId } from "./unit-id.js";
+import { resolveMilestonePath } from "./paths.js";
 import { queryJournal } from "./journal.js";
 import { readUnitRuntimeRecord } from "./unit-runtime.js";
 import { extractFrontmatterVerdict } from "./verdict-parser.js";
 // ─── Artifact Path Resolution ──────────────────────────────────────────────
 export function resolveHookArtifactPath(basePath, unitId, artifactName) {
     const { milestone, slice, task } = parseUnitId(unitId);
+    // Prefer the active phase directory (flat-phase layout: .gsd/phases/<NN>-.../).
+    // Configured gate artifacts are canonical phase-level files (e.g.
+    // BROWSER-RUNTIME-EVIDENCE.md), so resolve the exact declared name first,
+    // then a task-prefixed variant for retry sentinels / rework briefs.
+    const candidates = [];
+    const phaseDir = resolveMilestonePath(basePath, milestone);
+    const isFlatPhaseDir = phaseDir !== null
+        && !(dirname(phaseDir).endsWith("/milestones") || dirname(phaseDir).endsWith("\\milestones"));
+    if (isFlatPhaseDir) {
+        candidates.push(join(phaseDir, artifactName));
+        if (task !== undefined) {
+            candidates.push(join(phaseDir, `${task}-${artifactName}`));
+        }
+    }
+    // Legacy nested layout fallbacks (.gsd/milestones/<M>/slices/<S>/tasks/...).
+    const legacyBase = join(basePath, ".gsd", "milestones", milestone);
+    let legacyDefault;
     if (task !== undefined && slice !== undefined) {
-        return join(basePath, ".gsd", "milestones", milestone, "slices", slice, "tasks", `${task}-${artifactName}`);
-    }
-    if (slice !== undefined) {
-        return join(basePath, ".gsd", "milestones", milestone, "slices", slice, artifactName);
-    }
-    return join(basePath, ".gsd", "milestones", milestone, artifactName);
+        legacyDefault = join(legacyBase, "slices", slice, "tasks", `${task}-${artifactName}`);
+        candidates.push(legacyDefault);
+        candidates.push(join(legacyBase, "slices", slice, "tasks", artifactName));
+        candidates.push(join(legacyBase, "slices", slice, artifactName));
+    }
+    else if (slice !== undefined) {
+        legacyDefault = join(legacyBase, "slices", slice, artifactName);
+        candidates.push(legacyDefault);
+    }
+    else {
+        legacyDefault = join(legacyBase, artifactName);
+    }
+    candidates.push(join(legacyBase, artifactName));
+    const existing = candidates.find((candidate) => existsSync(candidate));
+    if (existing)
+        return existing;
+    // Nothing on disk yet: prefer the active phase path when the phase dir is
+    // known, otherwise fall back to the legacy default (preserves pre-flat-phase
+    // behavior for missing-artifact diagnostics).
+    return isFlatPhaseDir ? join(phaseDir, artifactName) : legacyDefault;
 }
 // ─── Dispatch Rule Conversion ──────────────────────────────────────────────
 /**
@@ -70,6 +102,13 @@ export class RuleRegistry {
     activeHook = null;
     hookQueue = [];
     cycleCounts = new Map();
+    /**
+     * Cycle keys that have already been granted a one-shot re-dispatch after a
+     * lost/interrupted dispatch (hook charged a cycle but never produced its own
+     * unit-end). Bounds the dispatch-cycle refund to exactly one per gate so a
+     * hook that repeatedly fails to complete cannot loop forever.
+     */
+    redispatchedGateKeys = new Set();
     retryPending = false;
     retryTrigger = null;
     hookFailure = null;
@@ -269,6 +308,10 @@ export class RuleRegistry {
             cycle: currentCycle,
             pendingRetry: false,
         };
+        return this._buildHookDispatch(config, triggerUnitId);
+    }
+    /** Construct the sidecar dispatch for a hook without mutating registry state. */
+    _buildHookDispatch(config, triggerUnitId) {
         const { milestone: mid, slice: sid, task: tid } = parseUnitId(triggerUnitId);
         let prompt = config.prompt
             .replace(/\{milestoneId\}/g, mid ?? "")
@@ -278,11 +321,27 @@ export class RuleRegistry {
         return {
             hookName: config.name,
             prompt,
-            model: config.model,
+            // Model selection (including fallbacks[]) is handled by
+            // resolveModelWithFallbacksForUnit for the `hook/<name>` unit type (#1229).
             unitType: `hook/${config.name}`,
             unitId: triggerUnitId,
         };
     }
+    /**
+     * Reconstruct the in-flight hook's dispatch from the restored `activeHook`
+     * state, without mutating the registry. Used to reconcile a persisted
+     * `activeHook` whose session-local dispatch was lost across a pause/resume
+     * or crash-recovery, so the hook actually runs instead of being charged
+     * against the next unrelated unit's close-out (#1246).
+     */
+    getPendingHookDispatch(basePath) {
+        if (!this.activeHook)
+            return null;
+        const config = resolvePostUnitHooks(basePath).find(h => h.name === this.activeHook.hookName);
+        if (!config)
+            return null;
+        return this._buildHookDispatch(config, this.activeHook.triggerUnitId);
+    }
     _assessHookCompletion(basePath, hook) {
         return this._assessConfiguredHookCompletion(basePath, hook.hookName, hook.triggerUnitId);
     }
@@ -368,6 +427,30 @@ export class RuleRegistry {
     }
     _handleBlockingGateCompletion(config, hook, basePath, observedCleanExecution) {
         if (!observedCleanExecution) {
+            // The hook was charged a cycle at dispatch but never produced its own
+            // unit-end — its dispatch was lost/interrupted (pause/resume, crash
+            // recovery). Refund that dispatch-consumed cycle exactly once so the gate
+            // is re-dispatched at least once instead of hard-blocking on a hook that
+            // never actually ran.
+            //
+            // This refund is intentionally UNCONDITIONAL on the first lost dispatch —
+            // it must NOT be gated on `currentCycle >= max_cycles`. A lost dispatch is
+            // a non-run: charging its cycle at dispatch time must not consume the
+            // hook's real-run budget. Gating the refund on "budget already exhausted"
+            // lets a lost dispatch below max_cycles silently eat a genuine cycle, so
+            // the hook gets one fewer real run than configured — reintroducing #1244
+            // for max_cycles >= 2 (see the "does not steal a real-run cycle" test).
+            // The redispatchedGateKeys flag bounds this to a single refund per gate,
+            // so repeated lost dispatches still terminate (total dispatches never
+            // exceed max_cycles + 1) and a hook that keeps failing blocks normally.
+            const cycleKey = hookCycleKey(config, hook);
+            if (!this.redispatchedGateKeys.has(cycleKey)) {
+                this.redispatchedGateKeys.add(cycleKey);
+                const currentCycle = this.cycleCounts.get(cycleKey);
+                if (typeof currentCycle === "number" && currentCycle > 0) {
+                    this.cycleCounts.set(cycleKey, currentCycle - 1);
+                }
+            }
             return this._rerunGateOrBlock(config, hook, basePath, {
                 reason: `hook/${config.name} did not complete cleanly before the trigger unit resumed`,
             });
@@ -639,6 +722,7 @@ export class RuleRegistry {
         this.activeHook = null;
         this.hookQueue = [];
         this.cycleCounts.clear();
+        this.redispatchedGateKeys.clear();
         this.retryPending = false;
         this.retryTrigger = null;
         this.hookFailure = null;
@@ -652,6 +736,7 @@ export class RuleRegistry {
     persistState(basePath) {
         const state = {
             cycleCounts: Object.fromEntries(this.cycleCounts),
+            redispatchedGateKeys: Array.from(this.redispatchedGateKeys),
             activeHook: this.activeHook ? { ...this.activeHook } : null,
             hookQueue: this.hookQueue.map(entry => ({
                 hookName: entry.config.name,
@@ -687,6 +772,14 @@ export class RuleRegistry {
                     }
                 }
             }
+            this.redispatchedGateKeys.clear();
+            if (Array.isArray(state.redispatchedGateKeys)) {
+                for (const key of state.redispatchedGateKeys) {
+                    if (typeof key === "string") {
+                        this.redispatchedGateKeys.add(key);
+                    }
+                }
+            }
             this.activeHook = state.activeHook && typeof state.activeHook === "object"
                 ? { ...state.activeHook }
                 : null;
@@ -715,7 +808,7 @@ export class RuleRegistry {
         try {
             const filePath = this._hookStatePath(basePath);
             if (existsSync(filePath)) {
-                writeFileSync(filePath, JSON.stringify({ cycleCounts: {}, activeHook: null, hookQueue: [], savedAt: new Date().toISOString() }, null, 2), "utf-8");
+                writeFileSync(filePath, JSON.stringify({ cycleCounts: {}, redispatchedGateKeys: [], activeHook: null, hookQueue: [], savedAt: new Date().toISOString() }, null, 2), "utf-8");
             }
         }
         catch (e) {
@@ -793,7 +886,10 @@ export class RuleRegistry {
         return {
             hookName: hook.name,
             prompt,
-            model: hook.model,
+            // Model selection (including fallbacks[]) is resolved by dispatchHookUnit
+            // via resolveModelWithFallbacksForUnit for the `hook/<name>` unit type,
+            // matching the auto-mode path. Emitting the primary-only model here would
+            // discard the configured fallback chain (#1229).
             unitType: `hook/${hook.name}`,
             unitId,
         };

package/dist/resources/extensions/gsd/skill-discovery.js

@@ -8,41 +8,49 @@
  * prompt block when reload fails before the next agent turn.
  */
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
+import { getSkillDirectories } from "@gsd/pi-coding-agent";
 import { gsdHome } from "./gsd-home.js";
 import { getInstalledSkills, normalizeSkillName } from "./skills.js";
-/** Snapshot of normalized skill names at auto-mode start */
-let baselineSkills = null;
+let snapshot = null;
 /**
  * Snapshot the current installed skill catalog. Call at auto-mode start.
+ * `cwd` is the project base path; skills dropped into `<cwd>/.agents/skills/`,
+ * `<cwd>/.claude/skills/`, or `<cwd>/.gsd/skills/` mid-session are detected.
  */
-export function snapshotSkills() {
-    baselineSkills = snapshotCurrentSkillNames();
+export function snapshotSkills(options) {
+    const searchDirs = getSkillDirectories({
+        cwd: options?.cwd ?? process.cwd(),
+        gsdHome: gsdHome(),
+    }).map((entry) => entry.path);
+    snapshot = {
+        baselineNames: snapshotCurrentSkillNames(searchDirs),
+        searchDirs,
+    };
 }
 /**
  * Clear the snapshot. Call when auto-mode stops.
  */
 export function clearSkillSnapshot() {
-    baselineSkills = null;
+    snapshot = null;
 }
 /**
  * Check if a snapshot is active (auto-mode is running with discovery).
  */
 export function hasSkillSnapshot() {
-    return baselineSkills !== null;
+    return snapshot !== null;
 }
 /**
  * Detect skills installed since the snapshot was taken.
  * Returns skill metadata for any new skills found in the loader catalog or on disk.
  */
 export function detectNewSkills() {
-    if (!baselineSkills)
+    if (!snapshot)
         return [];
     const newSkills = [];
-    for (const skill of getCurrentSkillsForDiscovery()) {
+    for (const skill of getCurrentSkillsForDiscovery(snapshot.searchDirs)) {
         const normalized = normalizeSkillName(skill.name);
-        if (baselineSkills.has(normalized))
+        if (snapshot.baselineNames.has(normalized))
             continue;
         newSkills.push(skill);
     }
@@ -68,7 +76,13 @@ export async function refreshCatalogForNewSkills(options) {
             return newSkills;
         }
     }
-    snapshotSkills();
+    // Re-snapshot, preserving the search dirs captured at auto-mode start.
+    if (snapshot) {
+        snapshot = {
+            baselineNames: snapshotCurrentSkillNames(),
+            searchDirs: snapshot.searchDirs,
+        };
+    }
     const names = newSkills.map((skill) => skill.name).join(", ");
     options?.notify?.(`GSD: loaded new skills: ${names}`, "info");
     return newSkills;
@@ -103,17 +117,16 @@ function escapeXml(value) {
         }
     });
 }
-function skillSearchDirs() {
-    return [
-        join(gsdHome(), "agent", "skills"),
-        join(homedir(), ".agents", "skills"),
-        join(homedir(), ".claude", "skills"),
-    ];
+function snapshotCurrentSkillNames(searchDirsOverride) {
+    // Uses explicit dirs, the snapshot's search dirs when active, or user-only dirs
+    // (no project context) when called before a snapshot is taken.
+    const searchDirs = searchDirsOverride ?? snapshot?.searchDirs ?? defaultSearchDirs();
+    return new Set(getCurrentSkillsForDiscovery(searchDirs).map(skill => normalizeSkillName(skill.name)));
 }
-function snapshotCurrentSkillNames() {
-    return new Set(getCurrentSkillsForDiscovery().map(skill => normalizeSkillName(skill.name)));
+function defaultSearchDirs() {
+    return getSkillDirectories({ cwd: process.cwd(), gsdHome: gsdHome() }).map((entry) => entry.path);
 }
-function getCurrentSkillsForDiscovery() {
+function getCurrentSkillsForDiscovery(searchDirs) {
     const skills = new Map();
     for (const skill of getInstalledSkills()) {
         const normalized = normalizeSkillName(skill.name);
@@ -123,16 +136,16 @@ function getCurrentSkillsForDiscovery() {
             location: skill.filePath,
         });
     }
-    for (const skill of getDiskSkills()) {
+    for (const skill of getDiskSkills(searchDirs)) {
         const normalized = normalizeSkillName(skill.name);
         if (!skills.has(normalized))
             skills.set(normalized, skill);
     }
     return [...skills.values()];
 }
-function getDiskSkills() {
+function getDiskSkills(searchDirs) {
     const skills = new Map();
-    for (const dir of skillSearchDirs()) {
+    for (const dir of searchDirs) {
         if (!existsSync(dir))
             continue;
         let entries;

package/dist/resources/extensions/gsd/state-reconciliation/drift/artifact-db.js

@@ -140,16 +140,7 @@ function detectArtifactDbStatusDriftForMilestone(basePath, milestoneId) {
         for (const task of tasks) {
             if (isClosedStatus(task.status))
                 continue;
-            // Flat-phase: task summaries live in the phase dir as TID-SUMMARY.md
-            let diskTaskSummary = resolveTaskFile(basePath, milestoneId, slice.id, task.id, "SUMMARY");
-            if (!diskTaskSummary) {
-                const phaseDir = resolveMilestonePath(basePath, milestoneId);
-                if (phaseDir) {
-                    const flatSummary = join(phaseDir, `${task.id}-SUMMARY.md`);
-                    if (existsSync(flatSummary))
-                        diskTaskSummary = flatSummary;
-                }
-            }
+            const diskTaskSummary = resolveTaskFile(basePath, milestoneId, slice.id, task.id, "SUMMARY");
             if (!diskTaskSummary || !existsSync(diskTaskSummary))
                 continue;
             addUniqueDrift(drifts, seen, {

package/dist/resources/extensions/gsd/state-reconciliation/drift/completion.js

@@ -7,8 +7,7 @@
 // same value).
 import { existsSync, statSync } from "node:fs";
 import { getAllMilestones, getMilestone, getMilestoneSlices, getSliceTasks, isDbAvailable, updateMilestoneStatus, updateSliceStatus, updateTaskStatus, } from "../../gsd-db.js";
-import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveTaskFile, } from "../../paths.js";
-import { join } from "node:path";
+import { resolveMilestoneFile, resolveSliceFile, resolveTaskFile, } from "../../paths.js";
 const COMPLETE_STATUSES = new Set(["complete", "done"]);
 function summaryMtimeIso(path) {
     try {
@@ -68,18 +67,7 @@ function collectMilestoneCompletionDrift(mid, ctx, drifts) {
                 continue;
             if (task.completed_at !== null)
                 continue;
-            // Flat-phase: task summaries live in the phase dir as TID-SUMMARY.md.
-            // Legacy: resolveTaskFile returns the tasks/TID/TID-SUMMARY.md path.
-            let taskSummary = resolveTaskFile(ctx.basePath, mid, slice.id, task.id, "SUMMARY");
-            // Flat-phase fallback: check the phase dir directly
-            if (!taskSummary) {
-                const phaseDir = resolveMilestonePath(ctx.basePath, mid);
-                if (phaseDir) {
-                    const flatSummary = join(phaseDir, `${task.id}-SUMMARY.md`);
-                    if (existsSync(flatSummary))
-                        taskSummary = flatSummary;
-                }
-            }
+            const taskSummary = resolveTaskFile(ctx.basePath, mid, slice.id, task.id, "SUMMARY");
             if (taskSummary && existsSync(taskSummary)) {
                 drifts.push({
                     kind: "missing-completion-timestamp",
@@ -136,16 +124,7 @@ export function repairMissingCompletionTimestamp(record, ctx) {
             task.completed_at !== null ||
             !COMPLETE_STATUSES.has(task.status))
             return;
-        // Flat-phase: task summaries live in the phase dir as TID-SUMMARY.md
-        let summary = resolveTaskFile(ctx.basePath, mid, sid, tid, "SUMMARY");
-        if (!summary) {
-            const phaseDir = resolveMilestonePath(ctx.basePath, mid);
-            if (phaseDir) {
-                const flatSummary = join(phaseDir, `${tid}-SUMMARY.md`);
-                if (existsSync(flatSummary))
-                    summary = flatSummary;
-            }
-        }
+        const summary = resolveTaskFile(ctx.basePath, mid, sid, tid, "SUMMARY");
         const ts = summary ? summaryMtimeIso(summary) : null;
         if (!ts)
             return;

package/dist/resources/extensions/gsd/state-reconciliation/index.js

@@ -41,6 +41,16 @@ export async function reconcileBeforeDispatch(basePath, partialDeps = {}) {
     if (!deps.dryRun) {
         const { capturePlanningCompatIfNeeded } = await import("../compat/planning-compat.js");
         await capturePlanningCompatIfNeeded(basePath);
+        // Self-heal phantom projection entries (#1257): a renamed/removed phase
+        // directory leaves stale `.compat.json` projection paths that no detector
+        // ever prunes (they all skip missing files), so the marker drifts from disk
+        // reality permanently. Drop entries whose backing file is gone before the
+        // detect passes run. Gated on !dryRun to keep detection read-only.
+        const { pruneOrphanedProjectionEntries } = await import("../compat/compat-marker.js");
+        const prunedCount = pruneOrphanedProjectionEntries(basePath);
+        if (prunedCount > 0) {
+            logWarning("reconcile", `pruned ${prunedCount} orphaned projection entr${prunedCount === 1 ? "y" : "ies"} from .compat.json (backing file no longer on disk)`);
+        }
     }
     for (let pass = 0; pass < MAX_PASSES; pass++) {
         deps.invalidateStateCache();

package/dist/resources/extensions/gsd/tools/complete-milestone.js

@@ -8,10 +8,9 @@
  * renders MILESTONE-SUMMARY.md to disk, stores rendered markdown in DB
  * for recovery, and invalidates caches.
  */
-import { join } from "node:path";
 import { existsSync } from "node:fs";
 import { transaction, getMilestone, getMilestoneSlices, getSliceTasks, getLatestAssessmentByScope, updateMilestoneStatus, } from "../gsd-db.js";
-import { clearPathCache, relMilestoneFile } from "../paths.js";
+import { clearPathCache, resolveMilestoneFile, targetMilestoneFile } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { isClosedStatus, isDeferredStatus } from "../status-guards.js";
 import { saveFile, clearParseCache } from "../files.js";
@@ -144,9 +143,8 @@ export async function handleCompleteMilestone(params, basePath) {
     }
     // ── Filesystem operations (outside transaction) ─────────────────────────
     const summaryMd = renderMilestoneSummaryMarkdown(params, completedAt);
-    // Layout-aware: flat-phase → phases/NN-slug/NN-SUMMARY.md;
-    // legacy → milestones/MID/MID-SUMMARY.md.
-    const summaryPath = join(artifactBasePath, relMilestoneFile(artifactBasePath, params.milestoneId, "SUMMARY"));
+    const summaryPath = resolveMilestoneFile(artifactBasePath, params.milestoneId, "SUMMARY") ??
+        targetMilestoneFile(artifactBasePath, params.milestoneId, "SUMMARY", getMilestone(params.milestoneId)?.title);
     // Guard (#4598): if SUMMARY.md already exists on disk, do not overwrite it.
     // This handles re-dispatch scenarios (DB/disk state divergence) where a prior
     // completion already wrote the file. Overwriting would silently destroy the

package/dist/resources/extensions/gsd/tools/reassess-roadmap.js

@@ -1,6 +1,6 @@
-import { join } from "node:path";
 import { existsSync, unlinkSync } from "node:fs";
-import { relSliceFile, relMilestoneFile } from "../paths.js";
+import { join } from "node:path";
+import { relSliceFile, resolveMilestoneFile, resolveMilestonePath, targetMilestoneFile } from "../paths.js";
 import { clearParseCache } from "../files.js";
 import { isClosedStatus } from "../status-guards.js";
 import { isNonEmptyString } from "../validation.js";
@@ -225,14 +225,20 @@ export async function handleReassessRoadmap(rawParams, basePath) {
             params.sliceChanges.modified.length > 0 ||
             params.sliceChanges.removed.length > 0;
         if (hasStructuralChanges) {
-            // Layout-aware: flat-phase → phases/NN-slug/NN-VALIDATION.md; legacy → milestones/MID/MID-VALIDATION.md
-            const validationFile = join(basePath, relMilestoneFile(basePath, params.milestoneId, "VALIDATION"));
-            try {
-                if (existsSync(validationFile))
-                    unlinkSync(validationFile);
-            }
-            catch (e) {
-                logWarning("tool", `validation file cleanup failed: ${e.message}`);
+            const milestoneDir = resolveMilestonePath(basePath, params.milestoneId);
+            const validationFiles = new Set([
+                resolveMilestoneFile(basePath, params.milestoneId, "VALIDATION"),
+                targetMilestoneFile(basePath, params.milestoneId, "VALIDATION", getMilestone(params.milestoneId)?.title),
+                milestoneDir ? join(milestoneDir, `${params.milestoneId}-VALIDATION.md`) : null,
+            ].filter((file) => Boolean(file)));
+            for (const validationFile of validationFiles) {
+                try {
+                    if (existsSync(validationFile))
+                        unlinkSync(validationFile);
+                }
+                catch (e) {
+                    logWarning("tool", `validation file cleanup failed: ${e.message}`);
+                }
             }
         }
         // ── Invalidate caches ─────────────────────────────────────────

package/dist/resources/extensions/gsd/tools/reopen-slice.js

@@ -5,6 +5,11 @@
  * tasks back to "pending". This is intentional — if you're reopening a
  * slice, you're re-doing the work. Partial resets create ambiguous state.
  *
+ * Also recovers a desynced slice (#1205): when a UAT→planning fallback leaves
+ * the slice open (e.g. "pending") but its tasks still "complete", this clears
+ * that state so the planner can re-plan without hitting "already complete"
+ * rejections.
+ *
  * The parent milestone must still be open (not complete).
  */
 // GSD — reopen-slice tool handler

package/dist/resources/extensions/gsd/tools/reopen-task.js

@@ -16,8 +16,8 @@ import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
 import { existsSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
-import { resolveTasksDir, clearPathCache } from "../paths.js";
+import { join, basename, dirname } from "node:path";
+import { resolveTasksDir, resolveSlicePath, clearPathCache } from "../paths.js";
 export async function handleReopenTask(params, basePath) {
     // ── Validate required fields ────────────────────────────────────────────
     if (!params.taskId || typeof params.taskId !== "string" || params.taskId.trim() === "") {
@@ -69,10 +69,18 @@ export async function handleReopenTask(params, basePath) {
     // ── Clean up stale filesystem artifacts (M12 fix) ────────────────────────
     // Without this, the DB-filesystem reconciler sees the SUMMARY.md and
     // auto-corrects the task back to "complete", making reopen a no-op (#3161).
+    // Legacy layout keeps the summary under a tasks/ subdir; flat-phase writes
+    // TID-SUMMARY.md directly in the phase dir. A tasks/ subdir may still exist
+    // in flat-phase for auxiliary artifacts — its mere existence must NOT redirect
+    // summary cleanup into tasks/ (#1208).
     try {
-        const tasksDir = resolveTasksDir(basePath, params.milestoneId, params.sliceId);
-        if (tasksDir) {
-            const summaryPath = join(tasksDir, `${params.taskId}-SUMMARY.md`);
+        const slicePath = resolveSlicePath(basePath, params.milestoneId, params.sliceId);
+        if (slicePath) {
+            const isLegacySlice = basename(dirname(slicePath)) === "slices";
+            const summaryDir = isLegacySlice
+                ? (resolveTasksDir(basePath, params.milestoneId, params.sliceId) ?? slicePath)
+                : slicePath;
+            const summaryPath = join(summaryDir, `${params.taskId}-SUMMARY.md`);
             if (existsSync(summaryPath))
                 unlinkSync(summaryPath);
         }

package/dist/resources/extensions/gsd/tools/validate-milestone.js

@@ -10,9 +10,8 @@
  * were never persisted, causing M002+ milestones to have zero gate records
  * despite passing validation.
  */
-import { join } from "node:path";
 import { transaction, insertAssessment, getMilestoneSlices, getMilestone, } from "../gsd-db.js";
-import { clearPathCache, relMilestoneFile } from "../paths.js";
+import { clearPathCache, targetMilestoneFile } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { saveFile, clearParseCache } from "../files.js";
@@ -113,11 +112,7 @@ export async function handleValidateMilestone(params, basePath, opts) {
     // worktree exists for this milestone, validation reads/writes the
     // worktree's artifacts instead of stale project-root state.
     const validationMd = renderValidationMarkdown(effectiveParams);
-    // Layout-aware: flat-phase → phases/NN-slug/NN-VALIDATION.md;
-    // legacy → milestones/MID/MID-VALIDATION.md.
-    // join(artifactBasePath, relMilestoneFile) gives the absolute path; relMilestoneFile
-    // returns ".gsd/..."-relative so joining with basePath (project/worktree root) is correct.
-    const validationPath = join(artifactBasePath, relMilestoneFile(artifactBasePath, effectiveParams.milestoneId, "VALIDATION"));
+    const validationPath = targetMilestoneFile(artifactBasePath, effectiveParams.milestoneId, "VALIDATION", getMilestone(effectiveParams.milestoneId)?.title);
     // ── DB write first — matches complete-task/complete-slice pattern ───
     // Write DB before disk so a crash between the two leaves a recoverable
     // state: the DB row exists but the file is missing, which projection
@@ -148,7 +143,7 @@ export async function handleValidateMilestone(params, basePath, opts) {
         const projectRoot = resolveWorktreeProjectRoot(basePath);
         if (projectRoot !== artifactBasePath) {
             // Mirror to project root using the project root's layout (same logic as above).
-            const projectValidationPath = join(projectRoot, relMilestoneFile(projectRoot, effectiveParams.milestoneId, "VALIDATION"));
+            const projectValidationPath = targetMilestoneFile(projectRoot, effectiveParams.milestoneId, "VALIDATION", getMilestone(effectiveParams.milestoneId)?.title);
             try {
                 await saveFile(projectValidationPath, validationMd);
             }

package/dist/resources/extensions/gsd/uat-dispatch.js

@@ -0,0 +1,94 @@
+// Project/App: gsd-pi
+// File Purpose: Resolve whether a completed slice needs run-uat dispatch.
+import { loadFile } from "./files.js";
+import { resolveSliceFile } from "./paths.js";
+import { classifyUatContentForRun, shouldDispatchUatForContent, } from "./uat-policy.js";
+import { hasVerdict } from "./verdict-parser.js";
+import { logWarning } from "./workflow-logger.js";
+async function loadSliceFileContent(base, milestoneId, sliceId, kind) {
+    const filePath = resolveSliceFile(base, milestoneId, sliceId, kind);
+    return filePath ? ((await loadFile(filePath)) ?? "") : "";
+}
+async function resolveRunUatEffectiveType(base, milestoneId, sliceId, uatContent) {
+    let summaryContent = "";
+    try {
+        summaryContent = await loadSliceFileContent(base, milestoneId, sliceId, "SUMMARY");
+    }
+    catch (err) {
+        logWarning("prompt", `resolveRunUatEffectiveType SUMMARY load failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return classifyUatContentForRun(uatContent, summaryContent).effectiveType;
+}
+async function resolveCandidateRunUatDispatch(base, milestoneId, candidate, prefs) {
+    const uatContent = await loadSliceFileContent(base, milestoneId, candidate.sliceId, "UAT");
+    if (!uatContent)
+        return null;
+    if (hasVerdict(uatContent))
+        return null;
+    const assessmentContent = await loadSliceFileContent(base, milestoneId, candidate.sliceId, "ASSESSMENT");
+    if (assessmentContent && hasVerdict(assessmentContent))
+        return null;
+    if (!shouldDispatchUatForContent(uatContent, prefs))
+        return null;
+    return {
+        sliceId: candidate.sliceId,
+        uatType: await resolveRunUatEffectiveType(base, milestoneId, candidate.sliceId, uatContent),
+    };
+}
+async function getDbCompletedSliceCandidates(milestoneId) {
+    const { isDbAvailable, getMilestoneSlices } = await import("./gsd-db.js");
+    if (!isDbAvailable())
+        return null;
+    const slices = getMilestoneSlices(milestoneId);
+    // No DB slice rows for this milestone: the DB has no authoritative view, so
+    // return null to let the caller defer to the roadmap fallback.
+    if (slices.length === 0)
+        return null;
+    // The DB has slice rows and is therefore authoritative for this milestone.
+    // Return a (possibly empty) array rather than null: an empty result must NOT
+    // fall through to the roadmap fallback, because the DB, not stale roadmap
+    // checkboxes, is the source of truth for which slices are complete.
+    return slices
+        .filter((slice) => slice.status === "complete")
+        .map((slice) => ({ sliceId: slice.id }))
+        .reverse();
+}
+export async function findRunUatDispatchFromCandidates(base, milestoneId, candidates, prefs) {
+    for (const candidate of candidates) {
+        const dispatch = await resolveCandidateRunUatDispatch(base, milestoneId, candidate, prefs);
+        if (dispatch)
+            return dispatch;
+    }
+    return null;
+}
+/**
+ * Check if the most recently completed slice needs a UAT run.
+ * Returns { sliceId, uatType } if UAT should be dispatched, null otherwise.
+ *
+ * When the DB has slice rows for the milestone it is authoritative: only its
+ * completed slices are considered and the `fallbackCandidates` (roadmap-derived)
+ * are ignored, even when no DB slice is complete. The fallback candidates are
+ * only consulted when the DB has no slice rows for the milestone, is
+ * unavailable, or errors.
+ *
+ * Skips when:
+ * - No completed slices exist in DB or the caller-provided fallback candidates
+ * - uat_dispatch is not enabled and the UAT spec does not require runtime/browser evidence
+ * - No UAT file exists for the slice
+ * - UAT result already exists in the UAT or ASSESSMENT file
+ */
+export async function checkNeedsRunUat(base, milestoneId, prefs, fallbackCandidates = []) {
+    try {
+        const dbCandidates = await getDbCompletedSliceCandidates(milestoneId);
+        // A non-null result (including an empty array) means the DB is authoritative
+        // for this milestone; only fall through to the roadmap fallback when the DB
+        // has no slice rows at all (null).
+        if (dbCandidates !== null) {
+            return findRunUatDispatchFromCandidates(base, milestoneId, dbCandidates, prefs);
+        }
+    }
+    catch (err) {
+        logWarning("prompt", `checkNeedsRunUat DB lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return findRunUatDispatchFromCandidates(base, milestoneId, fallbackCandidates, prefs);
+}