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

package/src/resources/extensions/gsd/tests/uok-kernel-path.test.ts

@@ -2,7 +2,7 @@
 // File Purpose: Verifies UOK kernel path selection and legacy fallback telemetry.
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
@@ -14,6 +14,16 @@ import type { LoopDeps } from "../auto/loop-deps.ts";
 import { gsdRoot } from "../paths.ts";
 import type { GSDPreferences } from "../preferences.ts";
 import { getLegacyTelemetry, resetLegacyTelemetry } from "../legacy-telemetry.ts";
+import { _getAdapter, closeDatabase, openDatabase } from "../gsd-db.ts";
+import { UokGateRunner } from "../uok/gate-runner.ts";
+import { applyModelPolicyFilter } from "../uok/model-policy.ts";
+import {
+  clearUnifiedAuditOverrideForTests,
+  isUnifiedAuditEnabled,
+  setUnifiedAuditEnabled,
+} from "../uok/audit-toggle.ts";
+import { writeEscalationArtifact } from "../escalation.ts";
+import { peekLogs, _resetLogs } from "../workflow-logger.ts";
 
 function makeBasePath(): string {
   return mkdtempSync(join(tmpdir(), "gsd-uok-kernel-"));
@@ -104,7 +114,8 @@ test("runAutoLoopWithUok uses kernel path by default and records uok-kernel pari
     assert.ok(args.calls.kernelDeps);
     assert.notEqual(args.calls.kernelDeps, args.deps);
     assert.ok(args.calls.kernelDeps?.uokObserver);
-    assert.equal(process.env.GSD_UOK_AUDIT_UNIFIED, "0");
+    assert.equal(isUnifiedAuditEnabled(), true);
+    assert.equal(isUnifiedAuditEnabled(basePath), false);
 
     const events = readParityEvents(basePath);
     assert.equal(events.length, 2);
@@ -120,6 +131,37 @@ test("runAutoLoopWithUok uses kernel path by default and records uok-kernel pari
   }
 });
 
+test("runAutoLoopWithUok keeps audit disabled for legacy-wrapper while restoring process override", async () => {
+  const basePath = makeBasePath();
+  clearUnifiedAuditOverrideForTests();
+  try {
+    resetLegacyTelemetry();
+    const args = makeArgs(basePath, {
+      uok: {
+        enabled: false,
+        audit_unified: { enabled: false },
+      },
+    });
+    await runAutoLoopWithUok(args);
+
+    assert.equal(args.calls.kernel, 0);
+    assert.equal(args.calls.legacy, 1);
+    assert.equal(isUnifiedAuditEnabled(), true);
+    assert.equal(isUnifiedAuditEnabled(basePath), false);
+
+    const events = readParityEvents(basePath);
+    assert.equal(events.length, 2);
+    assert.equal(events[0]?.path, "legacy-wrapper");
+    assert.equal(events[1]?.path, "legacy-wrapper");
+    assert.equal(events[1]?.status, "ok");
+    assert.equal(getLegacyTelemetry()["legacy.uokFallbackUsed"], 1);
+  } finally {
+    clearUnifiedAuditOverrideForTests();
+    resetLegacyTelemetry();
+    rmSync(basePath, { recursive: true, force: true });
+  }
+});
+
 test("runAutoLoopWithUok uses legacy path when explicit legacy fallback is enabled", async () => {
   const basePath = makeBasePath();
   try {
@@ -176,3 +218,185 @@ test("runAutoLoopWithUok respects GSD_UOK_FORCE_LEGACY emergency switch", async
     rmSync(basePath, { recursive: true, force: true });
   }
 });
+
+test("runAutoLoopWithUok records error exit and restores previous audit override when kernel fails", async () => {
+  const basePath = makeBasePath();
+  clearUnifiedAuditOverrideForTests();
+  setUnifiedAuditEnabled(false);
+  try {
+    resetLegacyTelemetry();
+    const args = makeArgs(basePath, {
+      uok: {
+        enabled: true,
+        audit_unified: { enabled: true },
+        gitops: { enabled: false },
+      },
+    });
+    args.runKernelLoop = async (_ctx, _pi, _s, loopDeps): Promise<void> => {
+      args.calls.kernel += 1;
+      args.calls.kernelDeps = loopDeps;
+      throw new Error("kernel exploded");
+    };
+
+    await assert.rejects(
+      () => runAutoLoopWithUok(args),
+      /kernel exploded/,
+    );
+
+    assert.equal(args.calls.kernel, 1);
+    assert.equal(args.calls.legacy, 0);
+    assert.equal(isUnifiedAuditEnabled(), false);
+
+    const events = readParityEvents(basePath);
+    assert.equal(events.length, 2);
+    assert.equal(events[0]?.phase, "enter");
+    assert.equal(events[1]?.phase, "exit");
+    assert.equal(events[1]?.status, "error");
+    assert.match(String(events[1]?.error), /kernel exploded/);
+  } finally {
+    clearUnifiedAuditOverrideForTests();
+    resetLegacyTelemetry();
+    rmSync(basePath, { recursive: true, force: true });
+  }
+});
+
+test("runAutoLoopWithUok treats kernel-enter audit failures as telemetry-only", async (t) => {
+  const basePath = makeBasePath();
+  const dbPath = join(basePath, ".gsd", "gsd.db");
+  clearUnifiedAuditOverrideForTests();
+  _resetLogs();
+  mkdirSync(join(basePath, ".gsd"), { recursive: true });
+  assert.equal(openDatabase(dbPath), true, "DB must open for this scenario");
+  t.after(() => {
+    clearUnifiedAuditOverrideForTests();
+    closeDatabase();
+    _resetLogs();
+    rmSync(basePath, { recursive: true, force: true });
+  });
+
+  _getAdapter()!.exec("DROP TABLE audit_events");
+
+  const args = makeArgs(basePath, {
+    uok: {
+      enabled: true,
+      audit_unified: { enabled: true },
+      gitops: { enabled: false },
+    },
+  });
+  args.runKernelLoop = async (_ctx, _pi, _s, loopDeps): Promise<void> => {
+    args.calls.kernel += 1;
+    args.calls.kernelDeps = loopDeps;
+    const observer = loopDeps.uokObserver;
+    assert.ok(observer, "kernel path must still install a turn observer");
+    observer.onTurnStart({
+      basePath,
+      traceId: "trace-audit-down",
+      turnId: "turn-audit-down",
+      iteration: 1,
+      unitType: "execute-task",
+      unitId: "M001/S01/T01",
+      startedAt: new Date().toISOString(),
+    });
+    observer.onTurnResult({
+      traceId: "trace-audit-down",
+      turnId: "turn-audit-down",
+      iteration: 1,
+      unitType: "execute-task",
+      unitId: "M001/S01/T01",
+      status: "completed",
+      failureClass: "none",
+      phaseResults: [],
+      startedAt: new Date().toISOString(),
+      finishedAt: new Date().toISOString(),
+    });
+
+    const gateRunner = new UokGateRunner();
+    gateRunner.register({
+      id: "test-gate",
+      type: "policy",
+      execute: async () => ({
+        outcome: "pass",
+        failureClass: "none",
+        rationale: "ok",
+      }),
+    });
+    await gateRunner.run("test-gate", {
+      basePath,
+      traceId: "trace-audit-down",
+      turnId: "turn-audit-down",
+      unitType: "execute-task",
+      unitId: "M001/S01/T01",
+    });
+
+    const filtered = applyModelPolicyFilter(
+      [{ id: "model-a", provider: "openai", api: "responses" }],
+      {
+        basePath,
+        traceId: "trace-audit-down",
+        turnId: "turn-audit-down",
+        unitType: "execute-task",
+      },
+    );
+    assert.equal(filtered.eligible.length, 1);
+
+    mkdirSync(join(basePath, ".gsd", "milestones", "M001", "slices", "S01", "tasks"), {
+      recursive: true,
+    });
+    writeEscalationArtifact(basePath, {
+      version: 1,
+      taskId: "T01",
+      sliceId: "S01",
+      milestoneId: "M001",
+      question: "Choose a path",
+      options: [
+        { id: "a", label: "A", tradeoffs: "First path" },
+        { id: "b", label: "B", tradeoffs: "Second path" },
+      ],
+      recommendation: "a",
+      recommendationRationale: "Test recommendation",
+      continueWithDefault: false,
+      createdAt: new Date().toISOString(),
+    });
+  };
+
+  await runAutoLoopWithUok(args);
+
+  assert.equal(args.calls.kernel, 1);
+  assert.equal(args.calls.legacy, 0);
+
+  const events = readParityEvents(basePath);
+  assert.equal(events.length, 3);
+  assert.equal(events[0]?.phase, "enter");
+  assert.equal(events[1]?.phase, "telemetry-error");
+  assert.equal(events[1]?.telemetry, "uok-kernel-enter");
+  assert.equal(events[2]?.phase, "exit");
+  assert.equal(events[2]?.status, "ok");
+  assert.equal(isUnifiedAuditEnabled(), true);
+  assert.equal(isUnifiedAuditEnabled(basePath), false);
+  assert.ok(
+    peekLogs().some(entry =>
+      entry.severity === "warn" &&
+      entry.component === "db" &&
+      entry.message.includes("uok-kernel-enter audit emit failed"),
+    ),
+    "degraded audit path should emit a non-fatal warning",
+  );
+
+  assert.doesNotThrow(() => {
+    writeEscalationArtifact(basePath, {
+      version: 1,
+      taskId: "T02",
+      sliceId: "S01",
+      milestoneId: "M001",
+      question: "Continue?",
+      options: [
+        { id: "yes", label: "Yes", tradeoffs: "Continue" },
+        { id: "no", label: "No", tradeoffs: "Stop" },
+      ],
+      recommendation: "yes",
+      recommendationRationale: "Audit stayed disabled after degraded enter",
+      continueWithDefault: true,
+      createdAt: new Date().toISOString(),
+    });
+  });
+});

package/src/resources/extensions/gsd/tests/uok-model-policy.test.ts

@@ -12,8 +12,13 @@ import {
   registerToolCompatibility,
   resetToolCompatibilityRegistry,
 } from "@gsd/pi-coding-agent";
+import {
+  clearUnifiedAuditOverrideForTests,
+  setUnifiedAuditEnabled,
+} from "../uok/audit-toggle.ts";
 
 test.afterEach(() => {
+  clearUnifiedAuditOverrideForTests();
   resetToolCompatibilityRegistry();
 });
 
@@ -32,6 +37,7 @@ test("uok model policy builds requirement vectors from unit metadata", () => {
 test("uok model policy enforces provider/api/tool constraints and emits decision audit events", () => {
   const basePath = mkdtempSync(join(tmpdir(), "gsd-uok-model-policy-"));
   try {
+    setUnifiedAuditEnabled(true);
     mkdirSync(join(basePath, ".gsd"), { recursive: true });
     registerToolCompatibility("screenshot", { producesImages: true });
 

package/src/resources/extensions/gsd/tests/workflow-projections.test.ts

@@ -6,10 +6,10 @@ import assert from 'node:assert/strict';
 import { existsSync, mkdtempSync, mkdirSync, rmSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
-import { regenerateIfMissing, renderPlanContent, renderStateProjection } from '../workflow-projections.ts';
+import { regenerateIfMissing, renderPlanContent, renderStateProjection, renderSummaryProjection } from '../workflow-projections.ts';
 import type { SliceRow, TaskRow } from '../gsd-db.ts';
 import { closeDatabase, insertMilestone, insertSlice, insertTask, openDatabase } from '../gsd-db.ts';
-import { clearPathCache, _clearGsdRootCache } from '../paths.ts';
+import { clearPathCache, _clearGsdRootCache, normalizeRealPath, resolveMilestoneFile, resolveTaskFile } from '../paths.ts';
 import { invalidateStateCache } from '../state.ts';
 import { clearParseCache } from '../files.ts';
 
@@ -243,6 +243,217 @@ test('workflow-projections: regenerateIfMissing PLAN restores slice plan and tas
   }
 });
 
+test('workflow-projections: regenerateIfMissing ROADMAP is idempotent for flat-phase roadmap projections', async () => {
+  const base = mkdtempSync(join(tmpdir(), 'gsd-projections-flat-roadmap-'));
+  const dbPath = join(base, '.gsd', 'gsd.db');
+  const phaseDir = join(base, '.gsd', 'phases', '01-milestone');
+  mkdirSync(phaseDir, { recursive: true });
+  openDatabase(dbPath);
+  clearParseCache();
+  clearPathCache();
+  _clearGsdRootCache();
+  invalidateStateCache();
+
+  try {
+    insertMilestone({ id: 'M001', title: 'Milestone', status: 'active', planning: { vision: 'Ship a layout-aware roadmap.' } });
+    insertSlice({
+      id: 'S01',
+      milestoneId: 'M001',
+      title: 'Flat slice',
+      status: 'pending',
+      demo: 'Roadmap exists at the flat-phase path.',
+      planning: { goal: 'Keep ROADMAP regeneration idempotent.' },
+    });
+
+    const roadmapPath = join(phaseDir, '01-ROADMAP.md');
+    writeFileSync(roadmapPath, '# existing flat roadmap\n');
+
+    const regenerated = await regenerateIfMissing(base, 'M001', 'S01', 'ROADMAP');
+
+    assert.equal(regenerated, false, 'existing flat-phase ROADMAP is detected without rewriting');
+    assert.equal(readFileSync(roadmapPath, 'utf-8'), '# existing flat roadmap\n');
+    assert.equal(normalizeRealPath(resolveMilestoneFile(base, 'M001', 'ROADMAP') ?? ''), normalizeRealPath(roadmapPath));
+  } finally {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test('workflow-projections: regenerateIfMissing ROADMAP regenerates missing flat-phase roadmap projections', async () => {
+  const base = mkdtempSync(join(tmpdir(), 'gsd-projections-missing-roadmap-'));
+  const dbPath = join(base, '.gsd', 'gsd.db');
+  const phaseDir = join(base, '.gsd', 'phases', '01-milestone');
+  mkdirSync(phaseDir, { recursive: true });
+  openDatabase(dbPath);
+  clearParseCache();
+  clearPathCache();
+  _clearGsdRootCache();
+  invalidateStateCache();
+
+  try {
+    insertMilestone({ id: 'M001', title: 'Milestone', status: 'active', planning: { vision: 'Ship a layout-aware roadmap.' } });
+    insertSlice({
+      id: 'S01',
+      milestoneId: 'M001',
+      title: 'Flat slice',
+      status: 'pending',
+      demo: 'Roadmap regenerates at the flat-phase path.',
+      planning: { goal: 'Recover ROADMAP from DB.' },
+    });
+
+    const roadmapPath = join(phaseDir, '01-ROADMAP.md');
+    const legacyRoadmapPath = join(base, '.gsd', 'milestones', 'M001', 'M001-ROADMAP.md');
+    assert.ok(!existsSync(roadmapPath), 'precondition: flat-phase ROADMAP is absent');
+
+    const regenerated = await regenerateIfMissing(base, 'M001', 'S01', 'ROADMAP');
+
+    assert.equal(regenerated, true, 'missing flat-phase ROADMAP is regenerated');
+    assert.match(readFileSync(roadmapPath, 'utf-8'), /Ship a layout-aware roadmap/);
+    assert.equal(existsSync(legacyRoadmapPath), false, 'regeneration does not create a legacy ROADMAP path');
+    assert.equal(normalizeRealPath(resolveMilestoneFile(base, 'M001', 'ROADMAP') ?? ''), normalizeRealPath(roadmapPath));
+  } finally {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test('workflow-projections: regenerateIfMissing SUMMARY is idempotent for flat-phase task summaries', async () => {
+  const base = mkdtempSync(join(tmpdir(), 'gsd-projections-flat-summary-'));
+  const dbPath = join(base, '.gsd', 'gsd.db');
+  const phaseDir = join(base, '.gsd', 'phases', '01-milestone');
+  mkdirSync(phaseDir, { recursive: true });
+  openDatabase(dbPath);
+  clearParseCache();
+  clearPathCache();
+  _clearGsdRootCache();
+  invalidateStateCache();
+
+  try {
+    insertMilestone({ id: 'M001', title: 'Milestone', status: 'active' });
+    insertSlice({
+      id: 'S01',
+      milestoneId: 'M001',
+      title: 'Flat slice',
+      status: 'complete',
+      demo: 'Summary regenerates once.',
+      planning: { goal: 'Recover flat-phase summaries from DB.' },
+    });
+    insertTask({
+      id: 'T01',
+      sliceId: 'S01',
+      milestoneId: 'M001',
+      title: 'Completed task',
+      status: 'complete',
+      oneLiner: 'Completed the flat task.',
+      narrative: 'The task was completed through the DB-backed projection path.',
+      verificationResult: 'passed',
+      duration: '5m',
+      keyFiles: ['src/example.ts'],
+      keyDecisions: ['Use centralized task summary paths.'],
+    });
+
+    const summaryPath = join(phaseDir, 'T01-SUMMARY.md');
+    assert.ok(!existsSync(summaryPath), 'precondition: flat-phase task summary absent');
+
+    const first = await regenerateIfMissing(base, 'M001', 'S01', 'SUMMARY');
+    const second = await regenerateIfMissing(base, 'M001', 'S01', 'SUMMARY');
+
+    assert.equal(first, true, 'first call regenerates the missing task summary');
+    assert.equal(second, false, 'second call sees the flat-phase task summary and does not rewrite it');
+    assert.equal(normalizeRealPath(resolveTaskFile(base, 'M001', 'S01', 'T01', 'SUMMARY') ?? ''), normalizeRealPath(summaryPath));
+    assert.match(readFileSync(summaryPath, 'utf-8'), /# T01: Completed the flat task\./);
+  } finally {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test('workflow-projections: flat-phase SUMMARY regeneration ignores stale nested task summaries', async () => {
+  const base = mkdtempSync(join(tmpdir(), 'gsd-projections-flat-stale-nested-'));
+  const dbPath = join(base, '.gsd', 'gsd.db');
+  const phaseDir = join(base, '.gsd', 'phases', '01-milestone');
+  const nestedTasksDir = join(phaseDir, 'tasks');
+  mkdirSync(nestedTasksDir, { recursive: true });
+  writeFileSync(join(nestedTasksDir, 'T01-SUMMARY.md'), '# stale nested summary\n');
+  openDatabase(dbPath);
+  clearParseCache();
+  clearPathCache();
+  _clearGsdRootCache();
+  invalidateStateCache();
+
+  try {
+    insertMilestone({ id: 'M001', title: 'Milestone', status: 'active' });
+    insertSlice({
+      id: 'S01',
+      milestoneId: 'M001',
+      title: 'Flat slice',
+      status: 'complete',
+      demo: 'Summary regenerates at phase root.',
+      planning: { goal: 'Recover canonical flat-phase summaries from DB.' },
+    });
+    insertTask({
+      id: 'T01',
+      sliceId: 'S01',
+      milestoneId: 'M001',
+      title: 'Completed task',
+      status: 'complete',
+    });
+
+    const rootSummaryPath = join(phaseDir, 'T01-SUMMARY.md');
+    assert.ok(!existsSync(rootSummaryPath), 'precondition: canonical flat-phase task summary absent');
+
+    const regenerated = await regenerateIfMissing(base, 'M001', 'S01', 'SUMMARY');
+
+    assert.equal(regenerated, true, 'missing phase-root summary is regenerated despite stale nested summary');
+    assert.equal(normalizeRealPath(resolveTaskFile(base, 'M001', 'S01', 'T01', 'SUMMARY') ?? ''), normalizeRealPath(rootSummaryPath));
+    assert.match(readFileSync(rootSummaryPath, 'utf-8'), /# T01: Completed task/);
+    assert.equal(readFileSync(join(nestedTasksDir, 'T01-SUMMARY.md'), 'utf-8'), '# stale nested summary\n');
+  } finally {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test('workflow-projections: renderSummaryProjection uses milestone title when creating fresh flat-phase dirs', async () => {
+  const base = mkdtempSync(join(tmpdir(), 'gsd-projections-fresh-summary-'));
+  const dbPath = join(base, '.gsd', 'gsd.db');
+  mkdirSync(join(base, '.gsd'), { recursive: true });
+  openDatabase(dbPath);
+  clearParseCache();
+  clearPathCache();
+  _clearGsdRootCache();
+  invalidateStateCache();
+
+  try {
+    insertMilestone({ id: 'M001', title: 'Milestone', status: 'active' });
+    insertSlice({
+      id: 'S01',
+      milestoneId: 'M001',
+      title: 'Flat slice',
+      status: 'complete',
+    });
+    insertTask({
+      id: 'T01',
+      sliceId: 'S01',
+      milestoneId: 'M001',
+      title: 'Completed task',
+      status: 'complete',
+    });
+
+    const titleSummaryPath = join(base, '.gsd', 'phases', '01-milestone', 'T01-SUMMARY.md');
+    const idSummaryPath = join(base, '.gsd', 'phases', '01-m001', 'T01-SUMMARY.md');
+
+    renderSummaryProjection(base, 'M001', 'S01', 'T01');
+
+    assert.ok(existsSync(titleSummaryPath), 'fresh summary projection uses the milestone title slug');
+    assert.equal(existsSync(idSummaryPath), false, 'fresh summary projection does not create an id-slug orphan dir');
+    assert.equal(normalizeRealPath(resolveTaskFile(base, 'M001', 'S01', 'T01', 'SUMMARY') ?? ''), normalizeRealPath(titleSummaryPath));
+  } finally {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
 test('workflow-projections: renderStateProjection does not clobber non-empty STATE.md when manifest has milestones', async () => {
   const base = mkdtempSync(join(tmpdir(), 'gsd-projection-stale-'));
   const gsdDir = join(base, '.gsd');

package/src/resources/extensions/gsd/tools/complete-milestone.ts

@@ -10,7 +10,6 @@
  * for recovery, and invalidates caches.
  */
 
-import { join } from "node:path";
 import { existsSync } from "node:fs";
 
 import {
@@ -21,7 +20,7 @@ import {
   getLatestAssessmentByScope,
   updateMilestoneStatus,
 } from "../gsd-db.js";
-import { gsdProjectionRoot, 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";
@@ -210,9 +209,14 @@ export async function handleCompleteMilestone(
   // ── 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

package/src/resources/extensions/gsd/tools/reassess-roadmap.ts

@@ -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";
@@ -290,12 +290,23 @@ export async function handleReassessRoadmap(
       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 as Error).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): file is string => Boolean(file)));
+      for (const validationFile of validationFiles) {
+        try {
+          if (existsSync(validationFile)) unlinkSync(validationFile);
+        } catch (e) {
+          logWarning("tool", `validation file cleanup failed: ${(e as Error).message}`);
+        }
       }
     }
 

package/src/resources/extensions/gsd/tools/validate-milestone.ts

@@ -12,15 +12,13 @@
  * despite passing validation.
  */
 
-import { join } from "node:path";
-
 import {
   transaction,
   insertAssessment,
   getMilestoneSlices,
   getMilestone,
 } from "../gsd-db.js";
-import { gsdProjectionRoot, 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";
@@ -160,11 +158,12 @@ export async function handleValidateMilestone(
   // 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
@@ -204,7 +203,12 @@ export async function handleValidateMilestone(
     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);
       } catch (mirrorErr) {