@opengsd/gsd-pi 1.3.0 → 1.4.0

package/src/resources/extensions/gsd/tools/exec-tool.ts

@@ -31,6 +31,7 @@ export interface ExecToolDeps {
   env?: NodeJS.ProcessEnv;
   now?: () => Date;
   generateId?: () => string;
+  signal?: AbortSignal;
 }
 
 export type UatExecIntent =
@@ -74,7 +75,7 @@ const UAT_EXEC_INTENT_ALIASES: Record<string, UatExecIntent> = {
 export function buildExecOptions(
   baseDir: string,
   cfg: ContextModeConfig | undefined,
-  extras?: Pick<ExecSandboxOptions, "env" | "now" | "generateId">,
+  extras?: Pick<ExecSandboxOptions, "env" | "now" | "generateId" | "signal">,
 ): ExecSandboxOptions {
   const allowlist = Array.isArray(cfg?.exec_env_allowlist) ? cfg!.exec_env_allowlist! : EXEC_DEFAULTS.envAllowlist;
   const stdoutCap = clampNumber(
@@ -209,7 +210,7 @@ export async function executeGsdExec(
   const opts = buildExecOptions(
     deps.baseDir,
     deps.preferences?.context_mode,
-    { env: deps.env, now: deps.now, generateId: deps.generateId },
+    { env: deps.env, now: deps.now, generateId: deps.generateId, signal: deps.signal },
   );
   const run = deps.run ?? runExecSandbox;
 
@@ -308,6 +309,7 @@ function formatResult(result: ExecSandboxResult): ToolExecutionResult {
       exit_code: result.exit_code,
       signal: result.signal,
       timed_out: result.timed_out,
+      aborted: result.aborted === true,
       force_resolved: result.force_resolved,
       duration_ms: result.duration_ms,
       stdout_bytes: result.stdout_bytes,
@@ -318,13 +320,15 @@ function formatResult(result: ExecSandboxResult): ToolExecutionResult {
       stderr_path: result.stderr_path,
       meta_path: result.meta_path,
     },
-    isError: result.timed_out || result.signal !== null || result.exit_code !== 0,
+    isError: result.aborted === true || result.timed_out || result.signal !== null || result.exit_code !== 0,
   };
 }
 
 function formatExit(result: ExecSandboxResult): string {
   // force_resolved means a non-closing (D-state) child was force-resolved past its
   // hard deadline rather than observed exiting; distinguish it from a clean timeout.
+  if (result.aborted && result.force_resolved) return "aborted(force-killed)";
+  if (result.aborted) return "aborted";
   if (result.force_resolved) return "timeout(force-killed)";
   if (result.timed_out) return "timeout";
   if (result.signal) return `signal:${result.signal}`;

package/src/resources/extensions/gsd/tools/plan-slice.ts

@@ -21,7 +21,6 @@ import {
 import type { GateEvaluationConfig, GateId } from "../types.js";
 import { invalidateStateCache } from "../state.js";
 import { renderPlanFromDb } from "../markdown-renderer.js";
-import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -52,7 +51,7 @@ export interface PlanSliceParams {
   milestoneId: string;
   sliceId: string;
   goal: string;
-  tasks: PlanSliceTaskInput[];
+  tasks?: PlanSliceTaskInput[];
   /** @optional — omitted fields render as conservative defaults */
   successCriteria?: string;
   /** @optional — omitted fields render as conservative defaults */
@@ -87,10 +86,12 @@ function validateRepositoryTargetIds(
   return deduped;
 }
 
-function validateTasks(value: unknown): PlanSliceTaskInput[] {
-  if (!Array.isArray(value) || value.length === 0) {
-    throw new Error("tasks must be a non-empty array");
+function validateTasks(value: unknown): PlanSliceTaskInput[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value)) {
+    throw new Error("tasks must be an array");
   }
+  if (value.length === 0) return undefined;
 
   const seen = new Set<string>();
   return value.map((entry, index) => {
@@ -201,7 +202,7 @@ function validateReferencedRepositories(
   };
 
   for (const id of params.targetRepositories ?? defaultTargets) noteMissing(id);
-  for (const task of params.tasks) {
+  for (const task of params.tasks ?? []) {
     for (const id of task.targetRepositories ?? params.targetRepositories ?? defaultTargets) noteMissing(id);
   }
 
@@ -212,7 +213,7 @@ function validateReferencedRepositories(
 function resolveAllowedRootsForPathScope(params: PlanSliceParams, registry: RepositoryRegistry, defaultTargets: string[]): string[] {
   const requested = new Set<string>();
   for (const id of params.targetRepositories ?? defaultTargets) requested.add(id);
-  for (const task of params.tasks) {
+  for (const task of params.tasks ?? []) {
     for (const id of task.targetRepositories ?? params.targetRepositories ?? defaultTargets) requested.add(id);
   }
   if (requested.size === 0) return [registry.projectRoot];
@@ -223,7 +224,7 @@ function resolveAllowedRootsForPathScope(params: PlanSliceParams, registry: Repo
 }
 
 function toTaskRows(params: PlanSliceParams, defaultTargets: string[]): TaskRow[] {
-  return params.tasks.map((task, index) => ({
+  return (params.tasks ?? []).map((task, index) => ({
     milestone_id: params.milestoneId,
     slice_id: params.sliceId,
     id: task.taskId,
@@ -310,6 +311,8 @@ export async function handlePlanSlice(
     return { error: `validation failed: ${message}` };
   }
   const defaultTargets = defaultRepositoryTargets(repositoryRegistry);
+  const taskPayload = params.tasks ?? [];
+  const hasTaskPayload = taskPayload.length > 0;
   const repoValidationError = validateReferencedRepositories(params, repositoryRegistry, defaultTargets);
   if (repoValidationError) {
     return { error: `validation failed: ${repoValidationError}` };
@@ -318,7 +321,7 @@ export async function handlePlanSlice(
   const allowedAbsoluteRoots = resolveAllowedRootsForPathScope(params, repositoryRegistry, defaultTargets);
 
   const pathOnlyError = validatePathOnlyPlanningFields(
-    params.tasks.map((task, index) => ({
+    taskPayload.map((task, index) => ({
       field: `tasks[${index}].expectedOutput`,
       values: task.expectedOutput,
     })),
@@ -329,7 +332,7 @@ export async function handlePlanSlice(
 
   const pathScopeError = validatePlanningPathScope(
     basePath,
-    params.tasks.flatMap((task, index) => [
+    taskPayload.flatMap((task, index) => [
       { field: `tasks[${index}].files`, values: task.files },
       { field: `tasks[${index}].inputs`, values: task.inputs },
       { field: `tasks[${index}].expectedOutput`, values: task.expectedOutput },
@@ -373,16 +376,18 @@ export async function handlePlanSlice(
         return;
       }
 
-      const newTaskIds = new Set(params.tasks.map((task) => task.taskId));
+      const newTaskIds = new Set(taskPayload.map((task) => task.taskId));
       const existingTasks = getSliceTasks(params.milestoneId, params.sliceId);
-      omittedTaskIds = existingTasks
-        .filter((task) => !newTaskIds.has(task.id))
-        .map((task) => task.id);
-
-      for (const task of existingTasks) {
-        if (!newTaskIds.has(task.id) && isClosedStatus(task.status)) {
-          guardError = `cannot remove completed task ${task.id}`;
-          return;
+      if (hasTaskPayload) {
+        omittedTaskIds = existingTasks
+          .filter((task) => !newTaskIds.has(task.id))
+          .map((task) => task.id);
+
+        for (const task of existingTasks) {
+          if (!newTaskIds.has(task.id) && isClosedStatus(task.status)) {
+            guardError = `cannot remove completed task ${task.id}`;
+            return;
+          }
         }
       }
 
@@ -399,35 +404,37 @@ export async function handlePlanSlice(
         targetRepositories: params.targetRepositories ?? defaultTargets,
       });
 
-      for (const taskId of omittedTaskIds) {
-        deleteTask(params.milestoneId, params.sliceId, taskId);
-      }
+      if (hasTaskPayload) {
+        for (const taskId of omittedTaskIds) {
+          deleteTask(params.milestoneId, params.sliceId, taskId);
+        }
 
-      const existingTaskById = new Map(existingTasks.map((task) => [task.id, task]));
-      for (const task of params.tasks) {
-        const planning = {
-          title: task.title,
-          description: task.description,
-          estimate: task.estimate,
-          files: task.files,
-          verify: task.verify,
-          inputs: task.inputs,
-          expectedOutput: task.expectedOutput,
-          observabilityImpact: task.observabilityImpact ?? "",
-          fullPlanMd: task.fullPlanMd,
-          targetRepositories: task.targetRepositories ?? params.targetRepositories ?? defaultTargets,
-        };
-        const existingTask = existingTaskById.get(task.taskId);
-        if (!existingTask || !isClosedStatus(existingTask.status)) {
-          insertTask({
-            id: task.taskId,
-            sliceId: params.sliceId,
-            milestoneId: params.milestoneId,
+        const existingTaskById = new Map(existingTasks.map((task) => [task.id, task]));
+        for (const task of taskPayload) {
+          const planning = {
             title: task.title,
-            status: "pending",
-          });
+            description: task.description,
+            estimate: task.estimate,
+            files: task.files,
+            verify: task.verify,
+            inputs: task.inputs,
+            expectedOutput: task.expectedOutput,
+            observabilityImpact: task.observabilityImpact ?? "",
+            fullPlanMd: task.fullPlanMd,
+            targetRepositories: task.targetRepositories ?? params.targetRepositories ?? defaultTargets,
+          };
+          const existingTask = existingTaskById.get(task.taskId);
+          if (!existingTask || !isClosedStatus(existingTask.status)) {
+            insertTask({
+              id: task.taskId,
+              sliceId: params.sliceId,
+              milestoneId: params.milestoneId,
+              title: task.title,
+              status: "pending",
+            });
+          }
+          upsertTaskPlanning(params.milestoneId, params.sliceId, task.taskId, planning);
         }
-        upsertTaskPlanning(params.milestoneId, params.sliceId, task.taskId, planning);
       }
 
       // Seed quality gate rows inside the transaction — all-or-nothing with
@@ -437,7 +444,7 @@ export async function handlePlanSlice(
         insertGateRow({ milestoneId: params.milestoneId, sliceId: params.sliceId, gateId: gid, scope: "slice" });
       }
       const taskGates = resolveTaskGates(gateEvaluation);
-      for (const task of params.tasks) {
+      for (const task of taskPayload) {
         for (const gid of taskGates) {
           insertGateRow({ milestoneId: params.milestoneId, sliceId: params.sliceId, gateId: gid, scope: "task", taskId: task.taskId });
         }
@@ -461,14 +468,18 @@ export async function handlePlanSlice(
       deleteArtifactByPath(artifactPath);
     }
 
-    const renderResult = await renderPlanFromDb(basePath, params.milestoneId, params.sliceId);
-    setSliceSketchFlag(params.milestoneId, params.sliceId, false);
+    const sliceTasks = getSliceTasks(params.milestoneId, params.sliceId);
+    const renderResult = sliceTasks.length === 0
+      ? { planPath: "", taskPlanPaths: [] as string[] }
+      : await renderPlanFromDb(basePath, params.milestoneId, params.sliceId);
+    if (sliceTasks.length > 0) {
+      setSliceSketchFlag(params.milestoneId, params.sliceId, false);
+    }
     invalidateStateCache();
     clearParseCache();
 
-    // ── Post-mutation hook: projections, manifest, event log ─────────────
+    // ── Post-mutation hook: manifest, event log ─────────────────────────
     try {
-      await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
       writeManifest(basePath);
       appendEvent(basePath, {
         cmd: "plan-slice",

package/src/resources/extensions/gsd/tools/plan-task.ts

@@ -1,14 +1,18 @@
 import { clearParseCache } from "../files.js";
 import { isClosedStatus } from "../status-guards.js";
 import { isNonEmptyString, validateStringArray } from "../validation.js";
-import { transaction, getSlice, getTask, insertTask, upsertTaskPlanning } from "../gsd-db.js";
+import { getGateIdsForTurn } from "../gate-registry.js";
+import { transaction, getSlice, getTask, insertTask, upsertTaskPlanning, insertGateRow, setSliceSketchFlag } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
-import { renderTaskPlanFromDb } from "../markdown-renderer.js";
+import { renderTaskPlanFromDb, renderPlanFromDb } from "../markdown-renderer.js";
+import { resolveTasksDir } from "../paths.js";
 import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
+import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { validatePathOnlyPlanningFields, validatePlanningPathScope } from "../planning-path-scope.js";
+import type { GateId } from "../types.js";
 
 export interface PlanTaskParams {
   milestoneId: string;
@@ -56,6 +60,12 @@ function validateParams(params: PlanTaskParams): PlanTaskParams {
   };
 }
 
+function resolveTaskGates(basePath: string): GateId[] {
+  const loaded = loadEffectiveGSDPreferences(basePath);
+  if (loaded?.preferences?.gate_evaluation?.task_gates === false) return [];
+  return [...getGateIdsForTurn("execute-task")];
+}
+
 export async function handlePlanTask(
   rawParams: PlanTaskParams,
   basePath: string,
@@ -83,6 +93,14 @@ export async function handlePlanTask(
     return { error: `validation failed: ${pathScopeError}` };
   }
 
+  let taskGates: GateId[];
+  try {
+    taskGates = resolveTaskGates(basePath);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { error: `validation failed: ${message}` };
+  }
+
   // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
   // Guards must be inside the transaction so the state they check cannot
   // change between the read and the write (#2723).
@@ -126,6 +144,9 @@ export async function handlePlanTask(
         observabilityImpact: params.observabilityImpact ?? "",
         fullPlanMd: params.fullPlanMd,
       });
+      for (const gid of taskGates) {
+        insertGateRow({ milestoneId: params.milestoneId, sliceId: params.sliceId, gateId: gid, scope: "task", taskId: params.taskId });
+      }
     });
   } catch (err) {
     return { error: `db write failed: ${(err as Error).message}` };
@@ -137,6 +158,26 @@ export async function handlePlanTask(
 
   try {
     const renderResult = await renderTaskPlanFromDb(basePath, params.milestoneId, params.sliceId, params.taskId);
+
+    // Flat-phase: tasks live as checkboxes in the slice plan's <tasks> block,
+    // not as standalone TID-PLAN.md files. Re-render the slice plan so the
+    // new/updated task appears in the plan file that gsd-core reads.
+    // Guard: resolveTasksDir is null in flat-phase (no tasks/ subdir exists).
+    let slicePlanSynced = false;
+    try {
+      const tDir = resolveTasksDir(basePath, params.milestoneId, params.sliceId);
+      if (!tDir) {
+        await renderPlanFromDb(basePath, params.milestoneId, params.sliceId);
+        slicePlanSynced = true;
+      }
+    } catch (syncErr) {
+      logWarning("tool", `plan-task: slice-plan sync failed: ${(syncErr as Error).message}`);
+    }
+
+    if (slicePlanSynced) {
+      setSliceSketchFlag(params.milestoneId, params.sliceId, false);
+    }
+
     invalidateStateCache();
     clearParseCache();
 

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

@@ -1,5 +1,6 @@
 import { join } from "node:path";
 import { existsSync, unlinkSync } from "node:fs";
+import { relSliceFile, relMilestoneFile } from "../paths.js";
 import { clearParseCache } from "../files.js";
 import { isClosedStatus } from "../status-guards.js";
 import { isNonEmptyString } from "../validation.js";
@@ -119,12 +120,9 @@ export async function handleReassessRoadmap(
   }
 
   // ── Compute assessment artifact path ──────────────────────────────
-  // Assessment lives in the completed slice's directory
-  const assessmentRelPath = join(
-    ".gsd", "milestones", params.milestoneId,
-    "slices", params.completedSliceId,
-    `${params.completedSliceId}-ASSESSMENT.md`,
-  );
+  // Assessment lives in the completed slice's directory.
+  // Use relSliceFile so the path is layout-aware (flat-phase or legacy).
+  const assessmentRelPath = relSliceFile(basePath, params.milestoneId, params.completedSliceId, "ASSESSMENT");
 
   // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
   // Guards must be inside the transaction so the state they check cannot
@@ -276,6 +274,9 @@ export async function handleReassessRoadmap(
   // ── Render artifacts ──────────────────────────────────────────────
   try {
     const roadmapResult = await renderRoadmapFromDb(basePath, params.milestoneId);
+    if ("skipped" in roadmapResult) {
+      return { error: `roadmap render skipped: milestone ${params.milestoneId} has no planned slices` };
+    }
     const assessmentResult = await renderAssessmentFromDb(basePath, params.milestoneId, params.completedSliceId, {
       verdict: params.verdict,
       assessment: params.assessment,
@@ -289,10 +290,8 @@ export async function handleReassessRoadmap(
       params.sliceChanges.removed.length > 0;
 
     if (hasStructuralChanges) {
-      const validationFile = join(
-        basePath, ".gsd", "milestones", params.milestoneId,
-        `${params.milestoneId}-VALIDATION.md`,
-      );
+      // 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) {

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

@@ -20,7 +20,7 @@ import {
   getMilestoneSlices,
   getMilestone,
 } from "../gsd-db.js";
-import { gsdProjectionRoot, clearPathCache } from "../paths.js";
+import { gsdProjectionRoot, clearPathCache, relMilestoneFile } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { saveFile, clearParseCache } from "../files.js";
@@ -160,12 +160,11 @@ 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);
-  const validationPath = join(
-    gsdProjectionRoot(artifactBasePath),
-    "milestones",
-    effectiveParams.milestoneId,
-    `${effectiveParams.milestoneId}-VALIDATION.md`,
-  );
+  // 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"));
 
   // ── DB write first — matches complete-task/complete-slice pattern ───
   // Write DB before disk so a crash between the two leaves a recoverable
@@ -204,12 +203,8 @@ export async function handleValidateMilestone(
     await saveFile(validationPath, validationMd);
     const projectRoot = resolveWorktreeProjectRoot(basePath);
     if (projectRoot !== artifactBasePath) {
-      const projectValidationPath = join(
-        gsdProjectionRoot(projectRoot),
-        "milestones",
-        effectiveParams.milestoneId,
-        `${effectiveParams.milestoneId}-VALIDATION.md`,
-      );
+      // Mirror to project root using the project root's layout (same logic as above).
+      const projectValidationPath = join(projectRoot, relMilestoneFile(projectRoot, effectiveParams.milestoneId, "VALIDATION"));
       try {
         await saveFile(projectValidationPath, validationMd);
       } catch (mirrorErr) {

package/src/resources/extensions/gsd/tools/workflow-tool-executors.ts

@@ -15,11 +15,13 @@ import {
   insertGateRun,
   readTransaction,
   saveGateResult,
+  upsertMilestonePlanning,
   upsertQualityGate,
 } from "../gsd-db.js";
+import { extractMilestoneSeq } from "../milestone-ids.js";
 import { GATE_REGISTRY } from "../gate-registry.js";
 import { generateRequirementsMd, saveArtifactToDb } from "../db-writer.js";
-import { clearPathCache, normalizeRealPath, relSliceFile, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
+import { clearPathCache, normalizeRealPath, relMilestoneFile, relSliceFile, relSlicePath, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { unlinkSync } from "node:fs";
 import { hostname } from "node:os";
@@ -143,7 +145,34 @@ export interface SummarySaveParams {
 function registerProjectMilestoneSequence(content: string): string[] {
   const parsed = parseProject(content);
   const registered: string[] = [];
+  // Reconcile parsed IDs against existing DB milestones before inserting (#807).
+  // Under unique_milestone_ids the planner mints suffixed IDs (e.g. "M001-b1nole"),
+  // while PROJECT.md's template uses bare sequence IDs (e.g. "M001"). Inserting the
+  // bare ID verbatim mints a phantom milestone row that collides with the planner's
+  // canonical one: the bare row gets its own git worktree, and at dispatch time the
+  // worktree/session scope ("M001") disagrees with ctx.mid ("M001-b1nole"), pausing
+  // auto-mode with "Dispatch milestone mismatch". A project DB holds at most one
+  // milestone per sequence number, so map each parsed line onto the existing row
+  // that shares its sequence number instead of minting a duplicate bare-ID row.
+  const existingBySeq = new Map<number, string>();
+  for (const existing of getAllMilestones()) {
+    const seq = extractMilestoneSeq(existing.id);
+    if (seq > 0 && !existingBySeq.has(seq)) existingBySeq.set(seq, existing.id);
+  }
   for (const milestone of parsed.milestones) {
+    const canonicalId = existingBySeq.get(extractMilestoneSeq(milestone.id));
+    if (canonicalId && canonicalId !== milestone.id) {
+      // An existing milestone already owns this sequence number. Treat the markdown
+      // line as referring to it: refresh the human title, and promote to complete
+      // when the line is checked — but never demote an in-flight milestone back to
+      // "queued" (the planner's row stays the single source of truth).
+      upsertMilestonePlanning(canonicalId, {
+        title: milestone.title,
+        ...(milestone.done ? { status: "complete" } : {}),
+      });
+      registered.push(canonicalId);
+      continue;
+    }
     insertMilestone({
       id: milestone.id,
       title: milestone.title,
@@ -353,11 +382,21 @@ export async function executeSummarySave(
     } else if (params.artifact_type === "REQUIREMENTS-DRAFT") {
       relativePath = "REQUIREMENTS-DRAFT.md";
     } else if (params.task_id && params.slice_id) {
-      relativePath = `milestones/${params.milestone_id}/slices/${params.slice_id}/tasks/${params.task_id}-${params.artifact_type}.md`;
+      // Layout-aware path for task-scoped artifacts.
+      // Flat-phase: <phaseDir>/TID-TYPE.md  Legacy: milestones/MID/slices/SID/tasks/TID-TYPE.md
+      // relSlicePath returns ".gsd/phases/NN-slug" (flat) or ".gsd/milestones/MID/slices/SID" (legacy).
+      const sRel = relSlicePath(basePath, params.milestone_id!, params.slice_id).replace(/^\.gsd\//, "");
+      relativePath = sRel.startsWith("milestones/")
+        ? `${sRel}/tasks/${params.task_id}-${params.artifact_type}.md`
+        : `${sRel}/${params.task_id}-${params.artifact_type}.md`;
     } else if (params.slice_id) {
-      relativePath = `milestones/${params.milestone_id}/slices/${params.slice_id}/${params.slice_id}-${params.artifact_type}.md`;
+      // Layout-aware path for slice-scoped artifacts.
+      // relSliceFile returns ".gsd/..." prefix — strip it to get the DB-relative path.
+      relativePath = relSliceFile(basePath, params.milestone_id!, params.slice_id, params.artifact_type).replace(/^\.gsd\//, "");
     } else {
-      relativePath = `milestones/${params.milestone_id}/${params.milestone_id}-${params.artifact_type}.md`;
+      // Layout-aware path for milestone-scoped artifacts.
+      // relMilestoneFile returns ".gsd/..." prefix — strip it to get the DB-relative path.
+      relativePath = relMilestoneFile(basePath, params.milestone_id!, params.artifact_type).replace(/^\.gsd\//, "");
     }
 
     const activeRequirements = params.artifact_type === "REQUIREMENTS"

package/src/resources/extensions/gsd/triage-resolution.ts

@@ -14,7 +14,7 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
 import { join } from "node:path";
 import { createRequire } from "node:module";
-import { gsdRoot, milestonesDir } from "./paths.js";
+import { gsdRoot, milestonesDir, legacyMilestonesDir, resolveMilestonePath } from "./paths.js";
 import { MILESTONE_ID_RE } from "./milestone-ids.js";
 import type { Classification, CaptureEntry } from "./captures.js";
 import {
@@ -185,8 +185,9 @@ export function executeBacktrack(
     // so deriveState() will re-enter it as the active milestone.
     if (targetMilestoneId) {
       try {
-        const targetDir = join(milestonesDir(basePath), targetMilestoneId);
-        if (existsSync(targetDir)) {
+        // Use resolveMilestonePath to locate the dir in either legacy or flat-phase layout.
+        const targetDir = resolveMilestonePath(basePath, targetMilestoneId);
+        if (targetDir && existsSync(targetDir)) {
           // Write a regression marker so the state machine knows this milestone
           // needs re-discussion, not just re-execution
           const regressionPath = join(targetDir, `${targetMilestoneId}-REGRESSION.md`);
@@ -334,8 +335,13 @@ export function ensureDeferMilestoneDir(
 ): boolean {
   if (!MILESTONE_ID_RE.test(targetMilestone)) return false;
 
-  const msDir = join(milestonesDir(basePath), targetMilestone);
-  if (existsSync(msDir)) return true;
+  // Check if the milestone dir already exists in either layout.
+  const existingDir = resolveMilestonePath(basePath, targetMilestone);
+  if (existingDir && existsSync(existingDir)) return true;
+  // Create new dir in the layout-appropriate location.
+  const legacyBase = legacyMilestonesDir(basePath);
+  const msBase = existsSync(legacyBase) ? legacyBase : milestonesDir(basePath);
+  const msDir = join(msBase, targetMilestone);
 
   try {
     mkdirSync(msDir, { recursive: true });
@@ -495,8 +501,9 @@ export function executeTriageResolutions(
       }
     }
     for (const [milestoneId, captures] of byMilestone) {
-      const msDir = join(milestonesDir(basePath), milestoneId);
-      if (!existsSync(msDir)) {
+      // Use resolveMilestonePath to check existence in either layout.
+      const existingMs = resolveMilestonePath(basePath, milestoneId);
+      if (!existingMs || !existsSync(existingMs)) {
         const created = ensureDeferMilestoneDir(basePath, milestoneId, captures);
         if (created) {
           result.deferredMilestones++;