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

package/src/resources/extensions/gsd/state/derive/from-db.ts

@@ -1,7 +1,7 @@
 // Project/App: gsd-pi
 // File Purpose: DB-backed GSD state derivation pipeline stage.
 
-import type { ActiveRef, GSDState, MilestoneRegistryEntry } from '../../types.js';
+import type { ActiveRef, GSDState, MilestoneRegistryEntry, Phase } from '../../types.js';
 import { join } from 'node:path';
 import { existsSync } from 'node:fs';
 import { isClosedStatus, isDeferredStatus } from '../../status-guards.js';
@@ -41,6 +41,59 @@ import {
 
 const isStatusDone = isClosedStatus;
 
+type MilestoneProgress = { done: number; total: number };
+type SliceProgress = { done: number; total: number };
+type TaskProgress = { done: number; total: number };
+
+interface DerivedStateContext {
+  activeMilestone: ActiveRef | null;
+  activeSlice?: ActiveRef | null;
+  activeTask?: ActiveRef | null;
+  registry: MilestoneRegistryEntry[];
+  requirements: GSDState["requirements"];
+  milestoneProgress: MilestoneProgress;
+  sliceProgress?: SliceProgress;
+  taskProgress?: TaskProgress;
+}
+
+interface DerivedStateOptions {
+  blockers?: string[];
+  lastCompletedMilestone?: ActiveRef | null;
+  includeActiveWorkspace?: boolean;
+}
+
+function buildProgress(context: DerivedStateContext): NonNullable<GSDState["progress"]> {
+  return {
+    milestones: context.milestoneProgress,
+    ...(context.sliceProgress ? { slices: context.sliceProgress } : {}),
+    ...(context.taskProgress ? { tasks: context.taskProgress } : {}),
+  };
+}
+
+function buildDerivedState(
+  context: DerivedStateContext,
+  phase: Phase,
+  nextAction: string,
+  options: DerivedStateOptions = {},
+): GSDState {
+  return {
+    activeMilestone: context.activeMilestone,
+    activeSlice: context.activeSlice ?? null,
+    activeTask: context.activeTask ?? null,
+    phase,
+    recentDecisions: [],
+    blockers: options.blockers ?? [],
+    nextAction,
+    ...(options.lastCompletedMilestone !== undefined
+      ? { lastCompletedMilestone: options.lastCompletedMilestone }
+      : {}),
+    ...(options.includeActiveWorkspace ? { activeWorkspace: undefined } : {}),
+    registry: context.registry,
+    requirements: context.requirements,
+    progress: buildProgress(context),
+  };
+}
+
 function stripMilestonePrefix(title: string): string {
   return title.replace(/^M\d+(?:-[a-z0-9]{6})?[^:]*:\s*/, '') || title;
 }
@@ -182,58 +235,47 @@ function handleNoActiveMilestone(
   const pendingEntries = registry.filter(e => e.status === 'pending');
   const parkedEntries = registry.filter(e => e.status === 'parked');
 
+  const context: DerivedStateContext = {
+    activeMilestone: null,
+    registry,
+    requirements,
+    milestoneProgress,
+  };
+
   if (pendingEntries.length > 0) {
     const blockerDetails = pendingEntries
       .filter(e => e.dependsOn && e.dependsOn.length > 0)
       .map(e => `${e.id} is waiting on unmet deps: ${e.dependsOn!.join(', ')}`);
-    return {
-      activeMilestone: null, activeSlice: null, activeTask: null,
-      phase: 'blocked',
-      recentDecisions: [], blockers: blockerDetails.length > 0
+    return buildDerivedState(context, 'blocked', 'Resolve milestone dependencies before proceeding.', {
+      blockers: blockerDetails.length > 0
         ? blockerDetails
         : ['All remaining milestones are dep-blocked but no deps listed — check CONTEXT.md files'],
-      nextAction: 'Resolve milestone dependencies before proceeding.',
-      registry, requirements,
-      progress: { milestones: milestoneProgress },
-    };
+    });
   }
 
   if (parkedEntries.length > 0) {
     const parkedIds = parkedEntries.map(e => e.id).join(', ');
-    return {
-      activeMilestone: null, activeSlice: null, activeTask: null,
-      phase: 'pre-planning',
-      recentDecisions: [], blockers: [],
-      nextAction: `All remaining milestones are parked (${parkedIds}). Run /gsd unpark <id> or create a new milestone.`,
-      registry, requirements,
-      progress: { milestones: milestoneProgress },
-    };
+    return buildDerivedState(
+      context,
+      'pre-planning',
+      `All remaining milestones are parked (${parkedIds}). Run /gsd unpark <id> or create a new milestone.`,
+    );
   }
 
   if (registry.length === 0) {
-    return {
-      activeMilestone: null, activeSlice: null, activeTask: null,
-      phase: 'pre-planning',
-      recentDecisions: [], blockers: [],
-      nextAction: 'No milestones found. Run /gsd to create one.',
-      registry: [], requirements,
-      progress: { milestones: { done: 0, total: 0 } },
-    };
+    return buildDerivedState(
+      { ...context, registry: [], milestoneProgress: { done: 0, total: 0 } },
+      'pre-planning',
+      'No milestones found. Run /gsd to create one.',
+    );
   }
 
   const lastEntry = registry[registry.length - 1];
   const unmappedActive = countUnmappedActiveRequirements();
   const completionNote = formatCompletePhaseNextAction(unmappedActive);
-  return {
-    activeMilestone: null,
+  return buildDerivedState(context, 'complete', completionNote, {
     lastCompletedMilestone: lastEntry ? { id: lastEntry.id, title: lastEntry.title } : null,
-    activeSlice: null, activeTask: null,
-    phase: 'complete',
-    recentDecisions: [], blockers: [],
-    nextAction: completionNote,
-    registry, requirements,
-    progress: { milestones: milestoneProgress },
-  };
+  });
 }
 
 async function handleAllSlicesDone(
@@ -248,52 +290,48 @@ async function handleAllSlicesDone(
   const verdict = typeof validation?.status === "string" ? validation.status : undefined;
   const validationTerminal = verdict != null && verdict !== "";
 
+  const context: DerivedStateContext = {
+    activeMilestone,
+    registry,
+    requirements,
+    milestoneProgress,
+    sliceProgress,
+  };
+
   if (!validationTerminal) {
-    return {
-      activeMilestone, activeSlice: null, activeTask: null,
-      phase: 'validating-milestone',
-      recentDecisions: [], blockers: [],
-      nextAction: `Validate milestone ${activeMilestone.id} before completion.`,
-      registry, requirements,
-      progress: { milestones: milestoneProgress, slices: sliceProgress },
-    };
+    return buildDerivedState(
+      context,
+      'validating-milestone',
+      `Validate milestone ${activeMilestone.id} before completion.`,
+    );
   }
 
   // All roadmap slices are done (enforced by caller) and verdict is
   // needs-remediation — remediation cannot progress without new slices.
   // Return blocked instead of re-dispatching validate-milestone (#4506).
   if (verdict === 'needs-attention') {
-    return {
-      activeMilestone, activeSlice: null, activeTask: null,
-      phase: 'blocked',
-      recentDecisions: [],
-      blockers: [formatNeedsAttentionBlocker(activeMilestone.id)],
-      nextAction: `Resolve ${activeMilestone.id} validation attention before proceeding.`,
-      registry, requirements,
-      progress: { milestones: milestoneProgress, slices: sliceProgress },
-    };
+    return buildDerivedState(
+      context,
+      'blocked',
+      `Resolve ${activeMilestone.id} validation attention before proceeding.`,
+      { blockers: [formatNeedsAttentionBlocker(activeMilestone.id)] },
+    );
   }
 
   if (verdict === 'needs-remediation') {
-    return {
-      activeMilestone, activeSlice: null, activeTask: null,
-      phase: 'blocked',
-      recentDecisions: [],
-      blockers: [formatNeedsRemediationBlocker(activeMilestone.id)],
-      nextAction: `Resolve ${activeMilestone.id} remediation before proceeding.`,
-      registry, requirements,
-      progress: { milestones: milestoneProgress, slices: sliceProgress },
-    };
+    return buildDerivedState(
+      context,
+      'blocked',
+      `Resolve ${activeMilestone.id} remediation before proceeding.`,
+      { blockers: [formatNeedsRemediationBlocker(activeMilestone.id)] },
+    );
   }
 
-  return {
-    activeMilestone, activeSlice: null, activeTask: null,
-    phase: 'completing-milestone',
-    recentDecisions: [], blockers: [],
-    nextAction: `All slices complete in ${activeMilestone.id}. Write milestone summary.`,
-    registry, requirements,
-    progress: { milestones: milestoneProgress, slices: sliceProgress },
-  };
+  return buildDerivedState(
+    context,
+    'completing-milestone',
+    `All slices complete in ${activeMilestone.id}. Write milestone summary.`,
+  );
 }
 
 function resolveSliceDependencies(activeMilestoneSlices: SliceRow[]): { activeSlice: ActiveRef | null, activeSliceRow: SliceRow | null } {
@@ -356,13 +394,16 @@ export async function deriveStateFromDb(
     : allMilestones;
 
   if (milestones.length === 0) {
-    return {
-      activeMilestone: null, activeSlice: null, activeTask: null,
-      phase: 'pre-planning', recentDecisions: [], blockers: [],
-      nextAction: 'No milestones found. Run /gsd to create one.',
-      registry: [], requirements,
-      progress: { milestones: { done: 0, total: 0 } },
-    };
+    return buildDerivedState(
+      {
+        activeMilestone: null,
+        registry: [],
+        requirements,
+        milestoneProgress: { done: 0, total: 0 },
+      },
+      'pre-planning',
+      'No milestones found. Run /gsd to create one.',
+    );
   }
 
   const { completeMilestoneIds, parkedMilestoneIds } = buildCompletenessSet(basePath, milestones);
@@ -384,12 +425,11 @@ export async function deriveStateFromDb(
     const nextAction = activeMilestoneHasDraft
       ? `Discuss draft context for milestone ${activeMilestone.id}.`
       : `Plan milestone ${activeMilestone.id}.`;
-    return {
-      activeMilestone, activeSlice: null, activeTask: null,
-      phase, recentDecisions: [], blockers: [],
-      nextAction, registry, requirements,
-      progress: { milestones: milestoneProgress },
-    };
+    return buildDerivedState(
+      { activeMilestone, registry, requirements, milestoneProgress },
+      phase,
+      nextAction,
+    );
   }
 
   const allSlicesDone = activeMilestoneSlices.every(s => isStatusDone(s.status));
@@ -397,6 +437,13 @@ export async function deriveStateFromDb(
     done: activeMilestoneSlices.filter(s => isStatusDone(s.status)).length,
     total: activeMilestoneSlices.length,
   };
+  const sliceStateContext: DerivedStateContext = {
+    activeMilestone,
+    registry,
+    requirements,
+    milestoneProgress,
+    sliceProgress,
+  };
 
   if (allSlicesDone) {
     return handleAllSlicesDone(basePath, activeMilestone, registry, requirements, milestoneProgress, sliceProgress);
@@ -407,21 +454,19 @@ export async function deriveStateFromDb(
     // If locked slice wasn't found, it returns null but logs warning, we need to return 'blocked'
     const sliceLock = process.env.GSD_PARALLEL_WORKER ? process.env.GSD_SLICE_LOCK : undefined;
     if (sliceLock) {
-      return {
-        activeMilestone, activeSlice: null, activeTask: null,
-        phase: 'blocked', recentDecisions: [], blockers: [`GSD_SLICE_LOCK=${sliceLock} not found in active milestone slices`],
-        nextAction: 'Slice lock references a non-existent slice — check orchestrator dispatch.',
-        registry, requirements,
-        progress: { milestones: milestoneProgress, slices: sliceProgress },
-      };
+      return buildDerivedState(
+        sliceStateContext,
+        'blocked',
+        'Slice lock references a non-existent slice — check orchestrator dispatch.',
+        { blockers: [`GSD_SLICE_LOCK=${sliceLock} not found in active milestone slices`] },
+      );
     }
-    return {
-      activeMilestone, activeSlice: null, activeTask: null,
-      phase: 'blocked', recentDecisions: [], blockers: ['No slice eligible — check dependency ordering'],
-      nextAction: 'Resolve dependency blockers or plan next slice.',
-      registry, requirements,
-      progress: { milestones: milestoneProgress, slices: sliceProgress },
-    };
+    return buildDerivedState(
+      sliceStateContext,
+      'blocked',
+      'Resolve dependency blockers or plan next slice.',
+      { blockers: ['No slice eligible — check dependency ordering'] },
+    );
   }
   const { activeSlice } = activeSliceContext;
   const activeSliceRow = activeSliceContext.activeSliceRow;
@@ -432,13 +477,11 @@ export async function deriveStateFromDb(
   // PLAN.md and preference flags are projections/configuration and are
   // deliberately not used to infer whether the slice itself is a sketch.
   if (activeSliceRow?.is_sketch === 1) {
-    return {
-      activeMilestone, activeSlice, activeTask: null,
-      phase: 'refining', recentDecisions: [], blockers: [],
-      nextAction: `Refine sketch slice ${activeSlice.id} (${activeSlice.title}) using prior slice context.`,
-      registry, requirements,
-      progress: { milestones: milestoneProgress, slices: sliceProgress },
-    };
+    return buildDerivedState(
+      { ...sliceStateContext, activeSlice },
+      'refining',
+      `Refine sketch slice ${activeSlice.id} (${activeSlice.title}) using prior slice context.`,
+    );
   }
 
   const tasks = getSliceTasks(activeMilestone.id, activeSlice.id);
@@ -447,30 +490,35 @@ export async function deriveStateFromDb(
     done: tasks.filter(t => isStatusDone(t.status)).length,
     total: tasks.length,
   };
+  const taskStateContext: DerivedStateContext = {
+    ...sliceStateContext,
+    activeSlice,
+    taskProgress,
+  };
 
   const activeTaskRow = tasks.find(t => !isStatusDone(t.status));
 
   if (!activeTaskRow && tasks.length > 0) {
-    return {
-      activeMilestone, activeSlice, activeTask: null,
-      phase: 'summarizing', recentDecisions: [], blockers: [],
-      nextAction: `All tasks done in ${activeSlice.id}. Write slice summary and complete slice.`,
-      registry, requirements,
-      progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
-    };
+    return buildDerivedState(
+      taskStateContext,
+      'summarizing',
+      `All tasks done in ${activeSlice.id}. Write slice summary and complete slice.`,
+    );
   }
 
   if (!activeTaskRow) {
-    return {
-      activeMilestone, activeSlice, activeTask: null,
-      phase: 'planning', recentDecisions: [], blockers: [],
-      nextAction: `Slice ${activeSlice.id} has no DB tasks. Plan slice tasks before execution.`,
-      registry, requirements,
-      progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
-    };
+    return buildDerivedState(
+      taskStateContext,
+      'planning',
+      `Slice ${activeSlice.id} has no DB tasks. Plan slice tasks before execution.`,
+    );
   }
 
   const activeTask: ActiveRef = { id: activeTaskRow.id, title: activeTaskRow.title };
+  const activeTaskStateContext: DerivedStateContext = {
+    ...taskStateContext,
+    activeTask,
+  };
 
   // ── Quality gate evaluation check ──────────────────────────────────
   // Pause before execution only when gates owned by the `gate-evaluate`
@@ -485,28 +533,26 @@ export async function deriveStateFromDb(
     "gate-evaluate",
   );
   if (pendingGateCount > 0) {
-    return {
-      activeMilestone, activeSlice, activeTask: null,
-      phase: 'evaluating-gates', recentDecisions: [], blockers: [],
-      nextAction: `Evaluate ${pendingGateCount} quality gate(s) for ${activeSlice.id} before execution.`,
-      registry, requirements,
-      progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
-    };
+    return buildDerivedState(
+      taskStateContext,
+      'evaluating-gates',
+      `Evaluate ${pendingGateCount} quality gate(s) for ${activeSlice.id} before execution.`,
+    );
   }
 
   const blockerTaskId = await detectBlockers(basePath, activeMilestone.id, activeSlice.id, tasks);
   if (blockerTaskId) {
     const replanHistory = getReplanHistory(activeMilestone.id, activeSlice.id);
     if (replanHistory.length === 0) {
-      return {
-        activeMilestone, activeSlice, activeTask,
-        phase: 'replanning-slice', recentDecisions: [],
-        blockers: [`Task ${blockerTaskId} discovered a blocker requiring slice replan`],
-        nextAction: `Task ${blockerTaskId} reported blocker_discovered. Replan slice ${activeSlice.id} before continuing.`,
-        activeWorkspace: undefined,
-        registry, requirements,
-        progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
-      };
+      return buildDerivedState(
+        activeTaskStateContext,
+        'replanning-slice',
+        `Task ${blockerTaskId} reported blocker_discovered. Replan slice ${activeSlice.id} before continuing.`,
+        {
+          blockers: [`Task ${blockerTaskId} discovered a blocker requiring slice replan`],
+          includeActiveWorkspace: true,
+        },
+      );
     }
   }
 
@@ -522,15 +568,15 @@ export async function deriveStateFromDb(
   // and the user's prior resolution never lands.
   const escalatingTaskId = detectPendingEscalation(tasks, basePath);
   if (escalatingTaskId) {
-    return {
-      activeMilestone, activeSlice, activeTask,
-      phase: 'escalating-task', recentDecisions: [],
-      blockers: [`Task ${escalatingTaskId} requires a user decision before the loop can proceed`],
-      nextAction: `Run /gsd escalate show ${escalatingTaskId} to review, then /gsd escalate resolve ${escalatingTaskId} <choice> to proceed.`,
-      activeWorkspace: undefined,
-      registry, requirements,
-      progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
-    };
+    return buildDerivedState(
+      activeTaskStateContext,
+      'escalating-task',
+      `Run /gsd escalate show ${escalatingTaskId} to review, then /gsd escalate resolve ${escalatingTaskId} <choice> to proceed.`,
+      {
+        blockers: [`Task ${escalatingTaskId} requires a user decision before the loop can proceed`],
+        includeActiveWorkspace: true,
+      },
+    );
   }
 
   if (!blockerTaskId) {
@@ -538,24 +584,22 @@ export async function deriveStateFromDb(
     if (isTriggered) {
       const replanHistory = getReplanHistory(activeMilestone.id, activeSlice.id);
       if (replanHistory.length === 0) {
-        return {
-          activeMilestone, activeSlice, activeTask,
-          phase: 'replanning-slice', recentDecisions: [],
-          blockers: ['Triage replan trigger detected — slice replan required'],
-          nextAction: `Triage replan triggered for slice ${activeSlice.id}. Replan before continuing.`,
-          activeWorkspace: undefined,
-          registry, requirements,
-          progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
-        };
+        return buildDerivedState(
+          activeTaskStateContext,
+          'replanning-slice',
+          `Triage replan triggered for slice ${activeSlice.id}. Replan before continuing.`,
+          {
+            blockers: ['Triage replan trigger detected — slice replan required'],
+            includeActiveWorkspace: true,
+          },
+        );
       }
     }
   }
 
-  return {
-    activeMilestone, activeSlice, activeTask,
-    phase: 'executing', recentDecisions: [], blockers: [],
-    nextAction: `Execute ${activeTask.id}: ${activeTask.title} in slice ${activeSlice.id}.`,
-    registry, requirements,
-    progress: { milestones: milestoneProgress, slices: sliceProgress, tasks: taskProgress },
-  };
+  return buildDerivedState(
+    activeTaskStateContext,
+    'executing',
+    `Execute ${activeTask.id}: ${activeTask.title} in slice ${activeSlice.id}.`,
+  );
 }

package/src/resources/extensions/gsd/tests/auto-artifact-paths.test.ts

@@ -1,6 +1,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, realpathSync, rmSync, utimesSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
@@ -360,6 +360,174 @@ test("canonical worktree + project-root legacy dir produces legacy filename (#bu
   }
 });
 
+// ── cursor[bot] 3523932401: bare milestone id must not match a team-suffix ────
+//
+// A bare milestone id (M001, no team-mode suffix) resolves its phase dir by
+// scanning phases/NN-*. Before the guard (commit 8f45bf3),
+// phaseDirMatchesMilestoneId returned true for ANY same-number dir, so a
+// leftover team-mode projection (phases/01-<6char>-.../, from a prior
+// team-suffixed run) matched the bare id too. When that stale dir carried a
+// newer mtime, pickPreferredPhaseDir selected it over the real title dir and
+// resolved the ROADMAP into a directory that has no ROADMAP — the file-not-found
+// retry loop. The guard (slugLooksLikeTeamSuffixProjection) rejects
+// team-suffix-looking slugs for bare ids in the primary pass; the suffixed
+// projection stays available only as a fallback when the primary pass finds
+// nothing (#1195, guarded by the second test below).
+
+test("bare milestone id prefers the real title dir over a newer team-suffix projection (cursor 3523932401)", () => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-bare-teamsuffix-")));
+  try {
+    const phasesDir = join(root, ".gsd", "phases");
+    // Intended flat-phase dir for the bare id: 01-<title-slug>/ with the ROADMAP.
+    const intendedDir = join(phasesDir, "01-clean-continuation");
+    mkdirSync(intendedDir, { recursive: true });
+    writeFileSync(join(intendedDir, "01-ROADMAP.md"), "# roadmap\n");
+
+    // Leftover team-mode projection: 01-<6char>-.../ with NO ROADMAP, made
+    // NEWER so an mtime tiebreak would wrongly prefer it without the guard.
+    const staleDir = join(phasesDir, "01-re4q3k-old-team-projection");
+    mkdirSync(staleDir, { recursive: true });
+    const newer = new Date(Date.now() + 60_000);
+    const older = new Date(Date.now() - 60_000);
+    utimesSync(staleDir, newer, newer);
+    utimesSync(intendedDir, older, older);
+
+    _clearGsdRootCache();
+    clearPathCache();
+
+    const resolved = resolveExpectedArtifactPath("plan-milestone", "M001", root);
+    assert.equal(
+      resolved,
+      join(intendedDir, "01-ROADMAP.md"),
+      "bare id must resolve to the real title dir, not the newer team-suffix projection",
+    );
+    assert.notEqual(
+      resolved,
+      join(staleDir, "01-ROADMAP.md"),
+      "must NOT resolve into the team-suffix projection dir that has no ROADMAP",
+    );
+  } finally {
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("bare milestone id still falls back to a lone team-suffix projection (#1195)", () => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-bare-teamsuffix-only-")));
+  try {
+    const phasesDir = join(root, ".gsd", "phases");
+    // The only on-disk dir for the bare id is a team-mode projection. With no
+    // non-suffixed candidate, the fallback pass must still resolve to it.
+    const onlyDir = join(phasesDir, "01-re4q3k-clean-continuation");
+    mkdirSync(onlyDir, { recursive: true });
+    writeFileSync(join(onlyDir, "01-ROADMAP.md"), "# roadmap\n");
+
+    _clearGsdRootCache();
+    clearPathCache();
+
+    const resolved = resolveExpectedArtifactPath("plan-milestone", "M001", root);
+    assert.equal(
+      resolved,
+      join(onlyDir, "01-ROADMAP.md"),
+      "with no non-suffixed dir, the team-suffix projection is the correct fallback",
+    );
+  } finally {
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+// ── #1208: flat-phase execute-task summaries resolve at the phase root ────────
+//
+// In flat-phase layout task summaries are written beside the plan files
+// (phases/<phase>/T##-SUMMARY.md), NOT under a tasks/ subdir. A tasks/ dir may
+// still exist to hold auxiliary task-scoped gate artifacts (e.g. T01-VERIFY.json).
+// Before the fix, the mere existence of that tasks/ dir redirected summary
+// verification into tasks/T##-SUMMARY.md — which never exists — trapping auto-mode
+// in a false verification retry that eventually paused after a successful task.
+
+test("flat-phase execute-task summary resolves at phase root when no tasks/ dir exists (#1208)", () => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-flat-task-summary-")));
+  try {
+    const gsd = join(root, ".gsd");
+    const phaseDir = join(gsd, "phases", "49-end-to-end-mandates");
+    mkdirSync(phaseDir, { recursive: true });
+    writeFileSync(join(phaseDir, "49-03-PLAN.md"), "# plan\n- [x] T02\n");
+
+    _clearGsdRootCache();
+    clearPathCache();
+
+    assert.equal(
+      resolveExpectedArtifactPath("execute-task", "M049/S03/T02", root),
+      join(phaseDir, "T02-SUMMARY.md"),
+    );
+  } finally {
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("flat-phase execute-task summary resolves at phase root even when tasks/ dir holds gate artifacts (#1208)", () => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-flat-task-tasksdir-")));
+  try {
+    const gsd = join(root, ".gsd");
+    const phaseDir = join(gsd, "phases", "49-end-to-end-mandates");
+    mkdirSync(phaseDir, { recursive: true });
+    writeFileSync(join(phaseDir, "49-03-PLAN.md"), "# plan\n- [x] T02\n");
+    // Auxiliary task-scoped gate artifact — creates the tasks/ dir but must not
+    // redirect the T02 summary into tasks/.
+    const tasksDir = join(phaseDir, "tasks");
+    mkdirSync(tasksDir, { recursive: true });
+    writeFileSync(join(tasksDir, "T01-VERIFY.json"), '{"ok":true}');
+
+    _clearGsdRootCache();
+    clearPathCache();
+
+    const resolved = resolveExpectedArtifactPath("execute-task", "M049/S03/T02", root);
+    assert.equal(
+      resolved,
+      join(phaseDir, "T02-SUMMARY.md"),
+      "flat-phase task summary must resolve at the phase root, not tasks/",
+    );
+    assert.notEqual(
+      resolved,
+      join(tasksDir, "T02-SUMMARY.md"),
+      "a tasks/ dir with gate artifacts must NOT redirect summary resolution into tasks/",
+    );
+  } finally {
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("legacy execute-task summary still resolves under slices/<SID>/tasks/ (#1208 regression guard)", () => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "gsd-legacy-task-summary-")));
+  try {
+    const milestoneDir = join(root, ".gsd", "milestones", "M001");
+    const sliceDir = join(milestoneDir, "slices", "S01");
+    const tasksDir = join(sliceDir, "tasks");
+    mkdirSync(tasksDir, { recursive: true });
+    writeFileSync(join(milestoneDir, "M001-CONTEXT.md"), "# context\n");
+    writeFileSync(join(sliceDir, "S01-PLAN.md"), "# plan\n");
+
+    _clearGsdRootCache();
+    clearPathCache();
+
+    assert.equal(
+      resolveExpectedArtifactPath("execute-task", "M001/S01/T02", root),
+      join(tasksDir, "T02-SUMMARY.md"),
+    );
+  } finally {
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
 // ── resolveSliceResearchLocation / resolveExistingSliceResearchPath ───────────
 //
 // Added in the code-quality consolidation PR as the shared dual-path resolver