@opengsd/gsd-pi 1.5.0-dev.4fb2d460 → 1.5.0-dev.c4c8885f

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

@@ -25,6 +25,57 @@ const VALID_UOK_TURN_ACTIONS = new Set([
     "snapshot",
     "status-only",
 ]);
+/**
+ * Sanitize a single model field that accepts either a bare model ID or the
+ * extended `{ model, provider?, fallbacks? }` object form used by phase buckets
+ * (#1229). Returns the sanitized value, or undefined when unset/invalid (in
+ * which case an error describing `label` is pushed onto `errors`).
+ */
+function sanitizeModelField(raw, label, errors, warnings) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw === "string") {
+        const trimmed = raw.trim();
+        if (!trimmed) {
+            errors.push(`${label} must not be an empty string`);
+            return undefined;
+        }
+        return trimmed;
+    }
+    if (raw && typeof raw === "object") {
+        const obj = raw;
+        const model = typeof obj.model === "string" ? obj.model.trim() : "";
+        if (!model) {
+            errors.push(`${label} object form requires a non-empty "model"`);
+            return undefined;
+        }
+        const sanitized = { model };
+        if (typeof obj.provider === "string" && obj.provider.trim()) {
+            sanitized.provider = obj.provider.trim();
+        }
+        if (obj.fallbacks !== undefined) {
+            const fallbacks = normalizeStringArray(obj.fallbacks);
+            if (fallbacks.length > 0)
+                sanitized.fallbacks = fallbacks;
+        }
+        // Preserve the object form's `thinking` sub-field so the dispatch site can
+        // pin the hook/supervisor/subagent reasoning level (#1269). An illegal level
+        // is warned-and-stripped, mirroring inline per-phase thinking, so a typo can't
+        // reach the resolver and be treated as explicit configuration.
+        if (obj.thinking !== undefined) {
+            if (VALID_THINKING_LEVELS.has(obj.thinking)) {
+                sanitized.thinking = obj.thinking;
+            }
+            else {
+                warnings?.push(`${label} thinking "${String(obj.thinking)}" is not a valid thinking level ` +
+                    `(off, minimal, low, medium, high, xhigh) — ignored`);
+            }
+        }
+        return sanitized;
+    }
+    errors.push(`${label} must be a string or an object with a "model" field`);
+    return undefined;
+}
 const VALID_POST_UNIT_HOOK_CRITICALITIES = new Set(["advisory", "blocking"]);
 const VALID_POST_UNIT_HOOK_ON_BLOCK_ACTIONS = new Set([
     "retry-unit",
@@ -452,7 +503,15 @@ export function validatePreferences(preferences) {
     // ─── Auto Supervisor ────────────────────────────────────────────────
     if (preferences.auto_supervisor !== undefined) {
         if (preferences.auto_supervisor && typeof preferences.auto_supervisor === "object") {
-            validated.auto_supervisor = preferences.auto_supervisor;
+            // Validate `model` through the shared sanitizer so the
+            // `{ model, provider?, fallbacks? }` object form is rejected on the same
+            // terms as its post_unit_hooks / reactive_execution siblings (#1229).
+            // Other supervisor fields pass through unchanged.
+            const supervisor = { ...preferences.auto_supervisor };
+            if (supervisor.model !== undefined) {
+                supervisor.model = sanitizeModelField(supervisor.model, "auto_supervisor.model", errors, warnings);
+            }
+            validated.auto_supervisor = supervisor;
         }
         else {
             errors.push("auto_supervisor must be an object");
@@ -548,8 +607,9 @@ export function validatePreferences(preferences) {
                 const mc = typeof hook.max_cycles === "number" ? hook.max_cycles : Number(hook.max_cycles);
                 validHook.max_cycles = Number.isFinite(mc) ? Math.max(1, Math.min(10, Math.round(mc))) : 1;
             }
-            if (typeof hook.model === "string" && hook.model.trim()) {
-                validHook.model = hook.model.trim();
+            const hookModel = sanitizeModelField(hook.model, `post_unit_hooks "${name}" model`, errors, warnings);
+            if (hookModel !== undefined) {
+                validHook.model = hookModel;
             }
             if (typeof hook.artifact === "string" && hook.artifact.trim()) {
                 validHook.artifact = hook.artifact.trim();
@@ -1050,13 +1110,9 @@ export function validatePreferences(preferences) {
                     errors.push('reactive_execution.isolation_mode must be "same-tree"');
                 }
             }
-            if (re.subagent_model !== undefined) {
-                if (typeof re.subagent_model === "string" && re.subagent_model.length > 0) {
-                    validRe.subagent_model = re.subagent_model;
-                }
-                else {
-                    errors.push("reactive_execution.subagent_model must be a non-empty string");
-                }
+            const subagentModel = sanitizeModelField(re.subagent_model, "reactive_execution.subagent_model", errors, warnings);
+            if (subagentModel !== undefined) {
+                validRe.subagent_model = subagentModel;
             }
             const knownReKeys = new Set(["enabled", "max_parallel", "isolation_mode", "subagent_model"]);
             for (const key of Object.keys(re)) {

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/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/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);
+}

package/dist/resources/extensions/gsd/uok/audit-toggle.js

@@ -1,7 +1,36 @@
 const AUDIT_ENV_KEY = "GSD_UOK_AUDIT_UNIFIED";
+const suppressedBasePaths = new Set();
 export function setUnifiedAuditEnabled(enabled) {
     process.env[AUDIT_ENV_KEY] = enabled ? "1" : "0";
 }
-export function isUnifiedAuditEnabled() {
-    return process.env[AUDIT_ENV_KEY] === "1";
+export function setUnifiedAuditSuppressedForBasePath(basePath, suppressed) {
+    if (suppressed) {
+        suppressedBasePaths.add(basePath);
+        return;
+    }
+    suppressedBasePaths.delete(basePath);
+}
+export function isUnifiedAuditEnabled(basePath) {
+    if (basePath && suppressedBasePaths.has(basePath))
+        return false;
+    return process.env[AUDIT_ENV_KEY] !== "0";
+}
+export function getUnifiedAuditOverride() {
+    const raw = process.env[AUDIT_ENV_KEY];
+    if (raw === "0")
+        return false;
+    if (raw === "1")
+        return true;
+    return undefined;
+}
+export function restoreUnifiedAuditOverride(override) {
+    if (override === undefined) {
+        delete process.env[AUDIT_ENV_KEY];
+        return;
+    }
+    setUnifiedAuditEnabled(override);
+}
+export function clearUnifiedAuditOverrideForTests() {
+    delete process.env[AUDIT_ENV_KEY];
+    suppressedBasePaths.clear();
 }

package/dist/resources/extensions/gsd/uok/audit.js

@@ -7,6 +7,7 @@ import { withFileLockSync } from "../file-lock.js";
 import { gsdRoot } from "../paths.js";
 import { isDbAvailable, insertAuditEvent } from "../gsd-db.js";
 import { CURRENT_UOK_CONTRACT_VERSION, validateAuditEvent } from "./contracts.js";
+import { isUnifiedAuditEnabled } from "./audit-toggle.js";
 function auditLogPath(basePath) {
     return join(gsdRoot(basePath), "audit", "events.jsonl");
 }
@@ -30,6 +31,8 @@ export function emitUokAuditEvent(basePath, event) {
     // Drop writes from a turn superseded by timeout recovery / cancellation.
     if (isStaleWrite("uok-audit"))
         return;
+    if (!isUnifiedAuditEnabled(basePath))
+        return;
     const validation = validateAuditEvent(event);
     if (!validation.ok) {
         throw new Error(`Invalid UOK audit event: ${validation.issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`);