@opengsd/gsd-pi 1.3.0 → 1.4.0

package/src/resources/extensions/gsd/auto-start.ts

@@ -32,6 +32,7 @@ import { ensureGsdSymlink, isInheritedRepo, validateProjectId } from "./repo-ide
 import { migrateToExternalState, recoverFailedMigration } from "./migrate-external.js";
 import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
 import { gsdRoot, resolveMilestoneFile } from "./paths.js";
+import { findMilestoneIds } from "./milestone-ids.js";
 import { milestoneEntryBlockedGuidance } from "./guidance.js";
 import { invalidateAllCaches } from "./cache.js";
 import { writeLock, clearLock, readCrashLock, isLockProcessAlive } from "./crash-recovery.js";
@@ -432,7 +433,7 @@ function formatStrandedWorkBlockerMessage(
 
 export function auditOrphanedMilestoneBranches(
   basePath: string,
-  _isolationMode: "worktree" | "branch" | "none",
+  isolationMode: "worktree" | "branch" | "none",
   gitDeps: {
     branchList?: typeof nativeBranchList;
     branchExists?: typeof nativeBranchExists;
@@ -487,6 +488,17 @@ export function auditOrphanedMilestoneBranches(
     mergedBranches = new Set();
   }
 
+  // Detect the branch currently checked out at the project root once — it
+  // does not change across loop iterations and is used below to avoid
+  // requesting a worktree creation for a branch that git already considers
+  // "in use" by the main worktree.
+  let currentRootBranch: string | null = null;
+  try {
+    currentRootBranch = nativeGetCurrentBranch(basePath) || null;
+  } catch {
+    currentRootBranch = null;
+  }
+
   for (const branch of milestoneBranches) {
     const milestoneId = branch.replace(/^milestone\//, "");
     const milestone = getMilestone(milestoneId);
@@ -515,9 +527,29 @@ export function auditOrphanedMilestoneBranches(
       }
       if ((isMerged || commitsAhead === 0) && !worktreeEvidence.dirty) continue;
 
-      const recoveryMode: StrandedWorkRecoveryMode = worktreeEvidence.path
-        ? "worktree"
-        : "branch";
+      // #812 — the worktree directory being absent on disk does NOT mean the
+      // project is branch-mode. getAutoWorktreePath() returns null whenever the
+      // directory is merely missing (transient/permanent loss after an
+      // interrupted session), which previously collapsed to recoveryMode:
+      // "branch" — silently checking out milestone/<id> in the project root with
+      // no worktree. When the project is *configured* for worktree isolation,
+      // recover as "worktree" so adoptStrandedMilestone re-materializes the
+      // worktree from the existing branch (createAutoWorktree with
+      // reuseExistingBranch) instead of degrading to branch-mode-in-root.
+      //
+      // Exception (#812-followup): if the milestone branch is already checked
+      // out at the project root (e.g. a leftover from the pre-fix #812 recovery
+      // that ran `git checkout milestone/<id>` in the root), git considers that
+      // branch "in use by another worktree" and will refuse `git worktree add`,
+      // causing bootstrap to abort. Degrade to "branch" in that case — the
+      // session resumes on the already-checked-out branch without worktree
+      // creation, same as pre-fix behavior, and the configured isolation is
+      // restored for subsequent milestones after merge/teardown.
+      const isBranchCheckedOutAtRoot = currentRootBranch === branch;
+      const recoveryMode: StrandedWorkRecoveryMode =
+        worktreeEvidence.path || (isolationMode === "worktree" && !isBranchCheckedOutAtRoot)
+          ? "worktree"
+          : "branch";
       const message = strandedWorkMessage({
         milestoneId,
         branch,
@@ -1023,7 +1055,7 @@ export async function bootstrapAutoSession(
   );
   const preferredModel = sessionProviderIsCustom
     ? null
-    : resolveDefaultSessionModel(ctx.model?.provider, base, profileModelIds);
+    : resolveDefaultSessionModel(ctx.model?.provider, base, profileModelIds, ctx.model?.id);
   // Validate the preferred model against the live registry + provider auth so
   // an unconfigured PREFERENCES.md entry (no API key / OAuth) can't become the
   // start-model snapshot. Without this, every subsequent unit would try to
@@ -1469,6 +1501,7 @@ export async function bootstrapAutoSession(
       ctx.modelRegistry,
       base,
       resolveProfileAnchorProvider(ctx.model?.provider, startModelSnapshot?.provider),
+      startModelSnapshot ? `${startModelSnapshot.provider}/${startModelSnapshot.id}` : undefined,
     )?.preferences;
     const { shouldRunDeepProjectSetup } = await import("./auto-dispatch.js");
     const deepProjectStagePending = shouldRunDeepProjectSetup(
@@ -1825,6 +1858,7 @@ export async function bootstrapAutoSession(
       ctx.modelRegistry,
       base,
       resolveProfileAnchorProvider(ctx.model?.provider, s.autoModeStartModel?.provider),
+      s.autoModeStartModel ? `${s.autoModeStartModel.provider}/${s.autoModeStartModel.id}` : undefined,
     )?.preferences;
     const effectiveProvider = s.autoModeStartModel?.provider ?? ctx.model?.provider;
     const effectivelyEnabled = routingConfig.enabled
@@ -1889,37 +1923,32 @@ export async function bootstrapAutoSession(
 
     // Pre-flight: validate milestone queue
     try {
-      const msDir = join(base, ".gsd", "milestones");
-      if (existsSync(msDir)) {
-        const milestoneIds = readdirSync(msDir, { withFileTypes: true })
-          .filter((d) => d.isDirectory() && /^M\d{3}/.test(d.name))
-          .map((d) => d.name.match(/^(M\d{3})/)?.[1] ?? d.name);
-        if (milestoneIds.length > 1) {
-          const issues: string[] = [];
-          for (const id of milestoneIds) {
-            // Skip completed/parked milestones — a leftover CONTEXT-DRAFT.md
-            // on a finished milestone is harmless residue, not an actionable warning.
-            if (isDbAvailable()) {
-              const ms = getMilestone(id);
-              if (ms?.status === "complete" || ms?.status === "parked") continue;
-            }
-            const draft = resolveMilestoneFile(base, id, "CONTEXT-DRAFT");
-            if (draft)
-              issues.push(
-                `${id}: has CONTEXT-DRAFT.md (will pause for discussion)`,
-              );
+      const milestoneIds = findMilestoneIds(base);
+      if (milestoneIds.length > 1) {
+        const issues: string[] = [];
+        for (const id of milestoneIds) {
+          // Skip completed/parked milestones — a leftover CONTEXT-DRAFT.md
+          // on a finished milestone is harmless residue, not an actionable warning.
+          if (isDbAvailable()) {
+            const ms = getMilestone(id);
+            if (ms?.status === "complete" || ms?.status === "parked") continue;
           }
-          if (issues.length > 0) {
-            ctx.ui.notify(
-              `Pre-flight: ${milestoneIds.length} milestones queued.\n${issues.map((i) => `  ⚠ ${i}`).join("\n")}`,
-              "warning",
-            );
-          } else {
-            ctx.ui.notify(
-              `Pre-flight: ${milestoneIds.length} milestones queued. All have full context.`,
-              "info",
+          const draft = resolveMilestoneFile(base, id, "CONTEXT-DRAFT");
+          if (draft)
+            issues.push(
+              `${id}: has CONTEXT-DRAFT.md (will pause for discussion)`,
             );
-          }
+        }
+        if (issues.length > 0) {
+          ctx.ui.notify(
+            `Pre-flight: ${milestoneIds.length} milestones queued.\n${issues.map((i) => `  ⚠ ${i}`).join("\n")}`,
+            "warning",
+          );
+        } else {
+          ctx.ui.notify(
+            `Pre-flight: ${milestoneIds.length} milestones queued. All have full context.`,
+            "info",
+          );
         }
       }
     } catch (err) {

package/src/resources/extensions/gsd/auto-timeout-recovery.ts

@@ -14,6 +14,7 @@ import {
 import {
   resolveExpectedArtifactPath,
   diagnoseExpectedArtifact,
+  verifyExpectedArtifact,
   writeBlockerPlaceholder,
 } from "./auto-recovery.js";
 import { existsSync } from "node:fs";
@@ -194,10 +195,10 @@ export async function recoverTimedOutUnit(
     return "recovered";
   }
 
-  // Check if the artifact already exists on disk — agent may have written it
+  // Check if the artifact is already valid on disk — agent may have written it
   // without signaling completion.
   const artifactPath = resolveExpectedArtifactPath(unitType, unitId, basePath);
-  if (artifactPath && existsSync(artifactPath)) {
+  if (artifactPath && existsSync(artifactPath) && verifyExpectedArtifact(unitType, unitId, basePath)) {
     writeUnitRuntimeRecord(basePath, unitType, unitId, currentUnitStartedAt, {
       phase: "finalized",
       recoveryAttempts: recoveryAttempts + 1,

package/src/resources/extensions/gsd/auto-verification.ts

@@ -15,7 +15,7 @@
 
 import type { ExtensionContext, ExtensionAPI } from "@gsd/pi-coding-agent";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
-import { gsdProjectionRoot, resolveSliceFile, resolveSlicePath } from "./paths.js";
+import { gsdProjectionRoot, relMilestoneFile, resolveSliceFile, resolveSlicePath } from "./paths.js";
 import { resolveMilestoneValidationVerdict } from "./milestone-validation-verdict.js";
 import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
 import { parseUnitId } from "./unit-id.js";
@@ -29,6 +29,7 @@ import {
   runVerificationGate,
   runVerificationGateForTargets,
   formatFailureContext,
+  formatFailureSignature,
   captureRuntimeErrors,
   runDependencyAudit,
 } from "./verification-gate.js";
@@ -262,12 +263,10 @@ async function runValidateMilestonePostCheck(
   };
 
   const validationBasePath = resolveCanonicalMilestoneRoot(s.basePath, mid);
-  const validationFile = join(
-    gsdProjectionRoot(validationBasePath),
-    "milestones",
-    mid,
-    `${mid}-VALIDATION.md`,
-  );
+  // Layout-aware: matches the writer at tools/validate-milestone.ts:167.
+  // Flat-phase resolves to phases/NN-slug/NN-VALIDATION.md; legacy resolves
+  // to milestones/MID/MID-VALIDATION.md. See open-gsd/gsd-pi#876.
+  const validationFile = join(validationBasePath, relMilestoneFile(validationBasePath, mid, "VALIDATION"));
   const validationContent = await loadFile(validationFile);
   if (validationContent !== null && validationContent.trim() === "") {
     if (await reassessmentInvalidatedValidation()) {
@@ -873,10 +872,13 @@ export async function runPostUnitVerification(
         );
       }
       const nextAttempt = attempt + 1;
+      const failureContext = verdict.failureContext || formatFailureContext(result);
+      const failureSignature = formatFailureSignature(result);
       s.verificationRetryCount.set(retryKey, nextAttempt);
       s.pendingVerificationRetry = {
         unitId: s.currentUnit.id,
-        failureContext: verdict.failureContext || formatFailureContext(result),
+        failureContext,
+        ...(failureSignature ? { signature: failureSignature } : {}),
         attempt: nextAttempt,
       };
       const failedCmds = result.checks

package/src/resources/extensions/gsd/auto-worktree.ts

@@ -20,7 +20,7 @@ import {
   unlinkSync,
   lstatSync as lstatSyncFn,
 } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { GSDError, GSD_IO_ERROR, GSD_GIT_ERROR } from "./errors.js";
 import {
   reconcileWorktreeDb,
@@ -36,7 +36,13 @@ import {
 } from "./db-workspace.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { execFileSync } from "node:child_process";
-import { gsdRoot, resolveGsdPathContract } from "./paths.js";
+import {
+  canonicalPhaseDirName,
+  gsdRoot,
+  milestonesDir,
+  resolveGsdPathContract,
+  resolveMilestonePath,
+} from "./paths.js";
 import {
   createWorktree,
   removeWorktree,
@@ -417,10 +423,25 @@ export const SAFE_AUTO_RESOLVE_PATTERNS: RegExp[] = [
   /\/__pycache__\//,
   /\.DS_Store$/,
   /\.map$/,
+  // Regenerable dependency lockfiles. These are fully derivable from their
+  // manifests by the package manager, so accepting the merge side during
+  // auto-resolve clears the conflict markers without losing meaningful edits —
+  // and stops auto-mode from hard-pausing on a lockfile conflict (issue #828).
+  /(?:^|\/)pnpm-lock\.yaml$/,
+  /(?:^|\/)package-lock\.json$/,
+  /(?:^|\/)npm-shrinkwrap\.json$/,
+  /(?:^|\/)yarn\.lock$/,
+  /(?:^|\/)bun\.lockb?$/,
+  /(?:^|\/)Cargo\.lock$/,
+  /(?:^|\/)composer\.lock$/,
+  /(?:^|\/)Gemfile\.lock$/,
+  /(?:^|\/)Pipfile\.lock$/,
+  /(?:^|\/)poetry\.lock$/,
 ];
 
 /** Returns true if the file path is safe to auto-resolve during merge.
- * Covers `.gsd/` state files and common build artifacts. */
+ * Covers `.gsd/` state files, common build artifacts, and regenerable
+ * dependency lockfiles. */
 export const isSafeToAutoResolve = (filePath: string): boolean =>
   filePath.startsWith(".gsd/") ||
   SAFE_AUTO_RESOLVE_PATTERNS.some((re) => re.test(filePath));
@@ -694,9 +715,11 @@ export function syncGsdStateToWorktree(
     }
   }
 
-  // Sync milestones: copy entire milestone directories that are missing
-  const mainMilestonesDir = join(mainGsd, "milestones");
-  const wtMilestonesDir = join(wtGsd, "milestones");
+  // Sync milestone/phase trees: copy entire directories that are missing.
+  // Support both flat-phase (phases/) and legacy (milestones/) layouts.
+  for (const layoutSegment of ["phases", "milestones"] as const) {
+  const mainMilestonesDir = join(mainGsd, layoutSegment);
+  const wtMilestonesDir = join(wtGsd, layoutSegment);
   if (existsSync(mainMilestonesDir)) {
     try {
       mkdirSync(wtMilestonesDir, { recursive: true });
@@ -786,6 +809,7 @@ export function syncGsdStateToWorktree(
       logWarning("worktree", `milestone directory sync failed: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
+  }
 
   return { synced };
 }
@@ -1799,10 +1823,19 @@ export function mergeMilestoneToMain(
   // MUST run BEFORE the pre-merge stash (step 7a) so `--include-untracked`
   // does not sweep queued CONTEXT files into the stash. If stash pop later
   // fails, files trapped inside the stash are permanently lost (#2505).
-  const milestonesDir = join(gsdRoot(originalBasePath_), "milestones");
+  const planningDir = milestonesDir(originalBasePath_);
   const shelterDir = join(gsdRoot(originalBasePath_), ".milestone-shelter");
   const shelteredDirs: string[] = [];
   let shelterRestored = false;
+  const mergeDirNames = new Set<string>([milestoneId]);
+  const resolvedMergeDir = resolveMilestonePath(originalBasePath_, milestoneId);
+  if (resolvedMergeDir) {
+    mergeDirNames.add(basename(resolvedMergeDir));
+  } else {
+    mergeDirNames.add(
+      canonicalPhaseDirName(milestoneId, getMilestone(milestoneId)?.title),
+    );
+  }
 
   // Helper: restore sheltered milestone directories (#2505).
   // Called on both success and error paths to ensure queued CONTEXT files
@@ -1829,11 +1862,11 @@ export function mergeMilestoneToMain(
         continue;
       }
       try {
-        mkdirSync(milestonesDir, { recursive: true });
+        mkdirSync(planningDir, { recursive: true });
         // Test seam: when _restoreEntryFn is injected, route the copy through it
         // so the best-effort failure path (and shelter-retention guarantee) can
         // be exercised deterministically. Production leaves it null → real cpSync.
-        const dest = join(milestonesDir, dirName);
+        const dest = join(planningDir, dirName);
         if (_restoreEntryFn) {
           _restoreEntryFn(src, dest);
         } else {
@@ -1859,13 +1892,13 @@ export function mergeMilestoneToMain(
   };
 
   try {
-    if (existsSync(milestonesDir)) {
-      const entries = readdirSync(milestonesDir, { withFileTypes: true });
+    if (existsSync(planningDir)) {
+      const entries = readdirSync(planningDir, { withFileTypes: true });
       for (const entry of entries) {
         if (!entry.isDirectory()) continue;
         // Only shelter directories that do NOT belong to the milestone being merged
-        if (entry.name === milestoneId) continue;
-        const srcDir = join(milestonesDir, entry.name);
+        if (mergeDirNames.has(entry.name)) continue;
+        const srcDir = join(planningDir, entry.name);
         const dstDir = join(shelterDir, entry.name);
         try {
           mkdirSync(shelterDir, { recursive: true });
@@ -1889,8 +1922,8 @@ export function mergeMilestoneToMain(
   //     branch. Passing NO pathspec lets git skip gitignored paths silently;
   //     adding an explicit pathspec trips a `git add`-style fatal on ignored
   //     entries (e.g. a gitignored `.gsd` symlink under ADR-002) (#4573).
-  //     Queued CONTEXT files under `.gsd/milestones/*` are already sheltered
-  //     in step 7 above, so they won't be swept into the stash.
+  //     Queued CONTEXT files under `.gsd/phases/*` (or legacy milestones/*)
+  //     are already sheltered in step 7 above, so they won't be swept into the stash.
   // On Windows, SQLite holds mandatory file locks on the gsd.db WAL/SHM
   // sidecars while the connection is open. `git stash --include-untracked`
   // walks those files and fails with EBUSY (#4704). Close the DB before

package/src/resources/extensions/gsd/auto.ts

@@ -41,6 +41,7 @@ import {
 import { extractSection, getManifestStatus, splitFrontmatter, parseFrontmatterMap } from "./files.js";
 export { inlinePriorMilestoneSummary } from "./files.js";
 import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
+
 import {
   gsdRoot,
   resolveMilestoneFile,
@@ -51,7 +52,10 @@ import {
   resolveTasksDir,
   resolveTaskFile,
   milestonesDir,
+  legacyMilestonesDir,
+  isLegacyMilestonesLayout,
   buildTaskFileName,
+  canonicalPhaseDirName,
 } from "./paths.js";
 import { invalidateAllCaches } from "./cache.js";
 import { clearActivityLogState } from "./activity-log.js";
@@ -93,8 +97,10 @@ import {
   getNewBudgetAlertLevel,
   getBudgetEnforcementAction,
   getContextPauseAction,
+  HARD_CONTEXT_REROOT_THRESHOLD_PERCENT,
   resolveCompactionThresholdPercent,
   shouldRerootStepSessionForContext,
+  shouldWarnStepSessionForContext,
 } from "./auto-budget.js";
 import {
   markToolStart as _markToolStart,
@@ -697,6 +703,7 @@ export {
   getContextPauseAction,
   resolveCompactionThresholdPercent,
   shouldRerootStepSessionForContext,
+  shouldWarnStepSessionForContext,
 } from "./auto-budget.js";
 
 function closeOutSignalInterruptedUnit(currentBasePath: string): void {
@@ -1371,9 +1378,10 @@ export async function rerootCommandSession(
 }
 
 /**
- * After a completed step-mode unit, reclaim context headroom when usage is at
- * or above the compaction threshold. Writes a context-mode snapshot first, then
- * re-roots the visible command session while leaving the NEXT progress surface.
+ * After a completed step-mode unit, warn when usage reaches the configurable
+ * soft context threshold. At the fixed hard boundary, write a context-mode
+ * snapshot and re-root the visible command session while leaving the NEXT
+ * progress surface.
  */
 export async function maybeRerootStepSessionForHighContext(
   ctx: ExtensionContext,
@@ -1388,7 +1396,19 @@ export async function maybeRerootStepSessionForHighContext(
   const prefs = loadEffectiveGSDPreferences(workspaceRoot);
   const compactionThreshold = prefs?.preferences.context_management?.compaction_threshold_percent;
 
-  if (!shouldRerootStepSessionForContext(contextPercent, compactionThreshold)) {
+  const shouldWarn = shouldWarnStepSessionForContext(contextPercent, compactionThreshold);
+  const shouldReroot = shouldRerootStepSessionForContext(contextPercent);
+  if (!shouldWarn && !shouldReroot) {
+    return { rerooted: false };
+  }
+
+  const displayPercent = (contextPercent as number).toFixed(1);
+  const thresholdDisplay = resolveCompactionThresholdPercent(compactionThreshold).toFixed(0);
+  if (!shouldReroot) {
+    ctx.ui.notify(
+      `Step complete — context at ${displayPercent}% (soft threshold: ${thresholdDisplay}%). Use /compact when convenient; continuing in this session is still safe.`,
+      "info",
+    );
     return { rerooted: false };
   }
 
@@ -1397,12 +1417,10 @@ export async function maybeRerootStepSessionForHighContext(
   const { writeContextModeCompactionSnapshot } = await import("./context-mode-snapshot.js");
   await writeContextModeCompactionSnapshot(snapshotBase);
 
-  const displayPercent = (contextPercent as number).toFixed(1);
-  const thresholdDisplay = resolveCompactionThresholdPercent(compactionThreshold).toFixed(0);
   const result = await rerootCommandSession(cmdCtx, workspaceRoot);
   if (result.status === "ok") {
     ctx.ui.notify(
-      `Step complete — context at ${displayPercent}% (threshold: ${thresholdDisplay}%). Fresh session ready for /gsd next.`,
+      `Step complete — context at ${displayPercent}% (hard threshold: ${HARD_CONTEXT_REROOT_THRESHOLD_PERCENT}%). Fresh session ready for /gsd next.`,
       "info",
     );
     return { rerooted: true };
@@ -2098,7 +2116,7 @@ export function _selectStopAutoWorktreeExit(args: {
 /**
  * Pause auto-mode without destroying state. Context is preserved.
  * The user can interact with the agent, then `/gsd auto` resumes
- * from disk state. Called when the user presses Escape during auto-mode.
+ * from disk state. Called when the user presses Escape or runs `/gsd pause`.
  */
 export async function pauseAuto(
   ctx?: ExtensionContext,
@@ -2125,6 +2143,7 @@ export async function pauseAuto(
 
   s.active = false;
   s.paused = true;
+  if (options.abortActiveTurn && ctx && !ctx.isIdle()) ctx.abort();
   clearUnitTimeout();
   stopAutoCommandPolling();
 
@@ -2354,6 +2373,7 @@ function buildLoopDeps(pi: ExtensionAPI, ctx: ExtensionContext): LoopDeps {
         ctx.modelRegistry,
         s.basePath || undefined,
         resolveProfileAnchorProvider(ctx.model?.provider, s.autoModeStartModel?.provider),
+        s.autoModeStartModel ? `${s.autoModeStartModel.provider}/${s.autoModeStartModel.id}` : undefined,
       ),
 
     // Pre-dispatch health gate
@@ -2513,7 +2533,7 @@ export async function startAuto(
   // resume paths (#4416). The matching call in auto-start.ts covers the
   // bootstrap-only path; this call ensures the resume path is also protected.
   if (recoverFailedMigration(base)) {
-    ctx.ui.notify("Recovered unfinished migration (.gsd.migrating → .gsd).", "info");
+    ctx.ui.notify("Recovered unfinished external state migration.", "info");
   }
 
   const unmergedStartMessage = await getUnmergedMilestoneBlockMessageForBase(base, "auto");
@@ -2997,11 +3017,26 @@ export function ensurePreconditions(
         return;
       }
     }
-    const newDir = join(milestonesDir(base), mid);
-    mkdirSync(join(newDir, "slices"), { recursive: true });
+    // Layout-aware: if the legacy milestones/ dir exists, place the new milestone dir
+    // there (preserves the existing project layout). Otherwise use flat-phase phases/.
+    const legacyBase = legacyMilestonesDir(base);
+    const isLegacyLayout = isLegacyMilestonesLayout(base);
+    const targetBase = isLegacyLayout ? legacyBase : milestonesDir(base);
+    // Flat-phase: look up the milestone title to build the canonical NN-slug dir name
+    // (e.g. "01-foundation") that resolveMilestonePath will later find by prefix.
+    // Legacy layout keeps the raw milestone id (e.g. "M001").
+    const dirName = isLegacyLayout
+      ? mid
+      : canonicalPhaseDirName(mid, getMilestone(mid)?.title);
+    const newDir = join(targetBase, dirName);
+    // Legacy projects use a slices/ subdir; flat-phase uses top-level plan files (no slices/).
+    mkdirSync(isLegacyLayout ? join(newDir, "slices") : newDir, { recursive: true });
   }
 
   if (sid !== undefined) {
+    const isLegacyLayout = isLegacyMilestonesLayout(base);
+    // Flat-phase: tasks are checkboxes in NN-MM-PLAN.md — no slices/ subdir needed.
+    if (!isLegacyLayout) return;
 
     const mDirResolved = resolveMilestonePath(base, mid);
     if (mDirResolved) {