@opengsd/gsd-pi 1.5.0 → 1.6.0-dev.aa7f94e8

package/src/resources/extensions/gsd/flat-phase-migration.ts

@@ -6,7 +6,7 @@ import { cpSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSyn
 import { join } from "node:path";
 
 import { renderAllFromDb, renderRoadmapFromDb } from "./markdown-renderer.js";
-import { getAllMilestones, getMilestoneSlices } from "./gsd-db.js";
+import { deleteArtifactsByPathPrefix, getAllMilestones, getMilestoneSlices } from "./gsd-db.js";
 import { migrateFromMarkdown } from "./md-importer.js";
 import { countDbHierarchy } from "./migration-auto-check.js";
 import { logWarning } from "./workflow-logger.js";
@@ -108,15 +108,35 @@ function rollbackPartialMigration(
       `rollback: could not remove partial ${LAYOUT_SEGMENTS.level1}/: ${(removeErr as Error).message}`,
     );
   }
+  // Only the standalone .gsd-backups/migrate-<ts>/ copy is disposable once the
+  // restore succeeds. When resuming an interrupted migration, backupDir IS the
+  // preserved migrating tree (the sole surviving data source) and must never be
+  // removed here. Deleting the backup after a successful rollback keeps the gate
+  // from leaking one .gsd-backups/migrate-<ts>/ per session_start.
+  const isDisposableBackup = Boolean(backupDir) && backupDir !== migratingPath;
+  const cleanupBackup = (): void => {
+    if (!isDisposableBackup || !existsSync(backupDir)) return;
+    try {
+      removePathWithRetries(backupDir);
+    } catch (cleanupErr) {
+      logWarning(
+        "migration",
+        `rollback: could not clean backup ${backupDir}: ${(cleanupErr as Error).message}`,
+      );
+    }
+  };
+
   // Restore milestones/ — prefer renaming the preserved migrating copy back.
   const milestonesPath = join(basePath, ".gsd", "milestones");
   try {
     if (migratingPath && existsSync(migratingPath) && !existsSync(milestonesPath)) {
       movePathWithCopyDeleteFallback(migratingPath, milestonesPath);
+      cleanupBackup();
       return;
     }
     if (existsSync(backupDir)) {
       cpSync(backupDir, milestonesPath, { recursive: true });
+      cleanupBackup();
     }
     if (migratingPath && existsSync(migratingPath)) {
       removePathWithRetries(migratingPath);
@@ -195,7 +215,8 @@ export function pruneStaleFlatPhaseBackups(basePath: string): number {
  * 2. Rename .gsd/milestones/ aside so path resolvers target phases/
  * 3. Render flat-phase from the DB (which already has the data)
  * 4. Verify counts match
- * 5. Remove the renamed legacy tree
+ * 5. Prune legacy milestones/ artifact rows
+ * 6. Remove the renamed legacy tree
  *
  * Idempotent: if .gsd/milestones/ doesn't exist, returns immediately.
  */
@@ -313,7 +334,17 @@ export async function migrateToFlatPhase(basePath: string): Promise<void> {
     throw new Error("flat-phase migration verification failed: no artifacts rendered");
   }
 
-  // 6. Verified — remove the renamed legacy tree (backup already on disk).
+  // 6. Verified — prune legacy artifact rows now that renderAllFromDb has
+  // re-inserted flat-phase rows for artifacts that still have files.
+  try {
+    deleteArtifactsByPathPrefix("milestones/");
+  } catch (err) {
+    logWarning("migration", `flat-phase migration could not prune legacy artifact rows: ${(err as Error).message}`);
+    rollbackPartialMigration(basePath, backupDir, migratingPath);
+    throw err;
+  }
+
+  // 7. Remove the renamed legacy tree (backup already on disk).
   try {
     removePathWithRetries(migratingPath);
   } catch (err) {

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

@@ -30,7 +30,7 @@ import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
 import { isDbAvailable, getHierarchyCompletionCounts } from "./gsd-db.js";
 import { formatDuration } from "../shared/format-utils.js";
-import { getAutoWorktreePath } from "./auto-worktree.js";
+import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
 import { clearGSDPreferencesCache, loadEffectiveGSDPreferences, loadGlobalGSDPreferences, getGlobalGSDPreferencesPath } from "./preferences.js";
 import { showNextAction } from "../shared/tui.js";
 import {

package/src/resources/extensions/gsd/git-conflict-resolve.ts

@@ -7,9 +7,9 @@ import {
   nativeCheckoutTheirs,
   nativeRmForce,
 } from "./native-git-bridge.js";
-import { isSafeToAutoResolve } from "./auto-worktree.js";
+import { isSafeToAutoResolve } from "./auto-worktree-conflict-auto-resolve.js";
 
-export { isSafeToAutoResolve } from "./auto-worktree.js";
+export { isSafeToAutoResolve } from "./auto-worktree-conflict-auto-resolve.js";
 
 export interface AutoResolveSafePathsResult {
   resolved: string[];

package/src/resources/extensions/gsd/git-service.ts

@@ -704,6 +704,59 @@ export function runGit(basePath: string, args: string[], options: { allowFailure
   }
 }
 
+/**
+ * Arguments for creating a task/workflow branch.
+ *
+ * When the current branch is a leftover GSD task branch (workflow template,
+ * quick task, or slice), the new branch starts from `baseBranch` — the
+ * caller's resolved integration branch, normally `GitServiceImpl.getMainBranch()`
+ * so `main_branch` preference, milestone integration branch, and worktree base
+ * all take priority over repo-default detection. Branching from HEAD there
+ * silently stacks consecutive workflow branches on top of each other, so every
+ * new gsd/* branch (and its eventual PR) drags along the previous workflow's
+ * commits.
+ *
+ * On any other branch (a user's feature branch, a worktree base, the main
+ * branch itself) the legacy branch-from-HEAD behavior is kept: basing new work
+ * on the branch the user chose to stand on is intentional there.
+ *
+ * Falls back to branch-from-HEAD, with a logged warning, when the base branch
+ * has no local ref or the working tree is still dirty (a start point that
+ * changes the tree would abort the checkout or strand in-flight changes).
+ * The base is the local ref — deliberately no fetch, so branch creation stays
+ * offline-safe even if the local base is behind its remote.
+ */
+export function taskBranchArgs(basePath: string, branchName: string, currentBranch: string, baseBranch: string): string[] {
+  const args = ["checkout", "-b", branchName];
+  const onTaskBranch =
+    WORKFLOW_BRANCH_RE.test(currentBranch) ||
+    QUICK_BRANCH_RE.test(currentBranch) ||
+    SLICE_BRANCH_RE.test(currentBranch);
+  if (!onTaskBranch || !baseBranch || baseBranch === currentBranch) return args;
+  try {
+    if (!nativeBranchExists(basePath, baseBranch)) {
+      logWarning(
+        "engine",
+        `taskBranchArgs: base branch "${baseBranch}" has no local ref — branching ${branchName} from HEAD (${currentBranch})`,
+        { file: "git-service.ts" },
+      );
+      return args;
+    }
+    if (nativeHasChanges(basePath)) {
+      logWarning(
+        "engine",
+        `taskBranchArgs: working tree still dirty after auto-commit — branching ${branchName} from HEAD (${currentBranch}) to preserve in-flight changes`,
+        { file: "git-service.ts" },
+      );
+      return args;
+    }
+  } catch {
+    return args;
+  }
+  args.push(baseBranch);
+  return args;
+}
+
 // ─── Commit Type Inference ─────────────────────────────────────────────────
 
 /**

package/src/resources/extensions/gsd/gsd-db.ts

@@ -454,6 +454,14 @@ export function insertTask(t: {
   fullSummaryMd?: string;
   sequence?: number;
   planning?: Partial<TaskPlanningRecord>;
+  // #1222 (metadata half): when re-importing from markdown, the caller only
+  // knows the plan/status — not the execution prose that gsd_task_complete
+  // wrote to the DB. Setting this preserves the existing row's execution
+  // columns (and completed_at) whenever the incoming value is empty/default,
+  // so a re-import cannot silently blank a completed task's summary metadata
+  // or refresh its completion timestamp. Off by default: callers that own the
+  // execution metadata (gsd_task_complete, planning) keep overwrite semantics.
+  preserveCompletionMetadata?: boolean;
 }): void {
   if (!getDbOrNull()!) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
   getDbOrNull()!.prepare(
@@ -473,17 +481,17 @@ export function insertTask(t: {
     ON CONFLICT(milestone_id, slice_id, id) DO UPDATE SET
       title = CASE WHEN NULLIF(:title, '') IS NOT NULL THEN :title ELSE tasks.title END,
       status = :status,
-      one_liner = :one_liner,
-      narrative = :narrative,
-      verification_result = :verification_result,
-      duration = :duration,
-      completed_at = :completed_at,
-      blocker_discovered = :blocker_discovered,
-      deviations = :deviations,
-      known_issues = :known_issues,
-      key_files = :key_files,
-      key_decisions = :key_decisions,
-      full_summary_md = :full_summary_md,
+      one_liner = CASE WHEN :preserve_completion = 1 AND NULLIF(:one_liner, '') IS NULL THEN tasks.one_liner ELSE :one_liner END,
+      narrative = CASE WHEN :preserve_completion = 1 AND NULLIF(:narrative, '') IS NULL THEN tasks.narrative ELSE :narrative END,
+      verification_result = CASE WHEN :preserve_completion = 1 AND NULLIF(:verification_result, '') IS NULL THEN tasks.verification_result ELSE :verification_result END,
+      duration = CASE WHEN :preserve_completion = 1 AND NULLIF(:duration, '') IS NULL THEN tasks.duration ELSE :duration END,
+      completed_at = CASE WHEN :preserve_completion = 1 AND tasks.completed_at IS NOT NULL THEN tasks.completed_at ELSE :completed_at END,
+      blocker_discovered = CASE WHEN :preserve_completion = 1 AND :blocker_discovered = 0 THEN tasks.blocker_discovered ELSE :blocker_discovered END,
+      deviations = CASE WHEN :preserve_completion = 1 AND NULLIF(:deviations, '') IS NULL THEN tasks.deviations ELSE :deviations END,
+      known_issues = CASE WHEN :preserve_completion = 1 AND NULLIF(:known_issues, '') IS NULL THEN tasks.known_issues ELSE :known_issues END,
+      key_files = CASE WHEN :preserve_completion = 1 AND NULLIF(:key_files, '[]') IS NULL THEN tasks.key_files ELSE :key_files END,
+      key_decisions = CASE WHEN :preserve_completion = 1 AND NULLIF(:key_decisions, '[]') IS NULL THEN tasks.key_decisions ELSE :key_decisions END,
+      full_summary_md = CASE WHEN :preserve_completion = 1 AND NULLIF(:full_summary_md, '') IS NULL THEN tasks.full_summary_md ELSE :full_summary_md END,
       description = CASE WHEN NULLIF(:description, '') IS NOT NULL THEN :description ELSE tasks.description END,
       estimate = CASE WHEN NULLIF(:estimate, '') IS NOT NULL THEN :estimate ELSE tasks.estimate END,
       files = CASE WHEN NULLIF(:files, '[]') IS NOT NULL THEN :files ELSE tasks.files END,
@@ -523,6 +531,7 @@ export function insertTask(t: {
     ":observability_impact": t.planning?.observabilityImpact ?? "",
     ":full_plan_md": t.planning?.fullPlanMd ?? "",
     ":sequence": t.sequence ?? 0,
+    ":preserve_completion": t.preserveCompletionMetadata && (t.status === "complete" || t.status === "done") ? 1 : 0,
     ":target_repositories": JSON.stringify(t.planning?.targetRepositories ?? []),
     ":raw_target_repositories":
       t.planning && "targetRepositories" in t.planning
@@ -1397,6 +1406,19 @@ export function deleteArtifactByPath(path: string): void {
   getDbOrNull()!.prepare("DELETE FROM artifacts WHERE path = :path").run({ ":path": path });
 }
 
+/** Delete artifact rows whose paths share a DB-relative prefix. */
+export function deleteArtifactsByPathPrefix(prefix: string): number {
+  if (!getDbOrNull()!) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+  return transaction(() => {
+    const likePrefix = `${prefix}%`;
+    const countRow = getDbOrNull()!.prepare(
+      "SELECT COUNT(*) AS count FROM artifacts WHERE path LIKE :prefix",
+    ).get({ ":prefix": likePrefix });
+    getDbOrNull()!.prepare("DELETE FROM artifacts WHERE path LIKE :prefix").run({ ":prefix": likePrefix });
+    return Number(countRow?.["count"] ?? 0);
+  });
+}
+
 /**
  * Drop hierarchy rows in dependency order inside a transaction. Used by
  * `gsd recover --confirm` to rebuild engine state from markdown.

package/src/resources/extensions/gsd/guided-flow.ts

@@ -50,8 +50,8 @@ import { readSessionLockData, isSessionLockProcessAlive } from "./session-lock.j
 import { nativeAddAll, nativeCommit, nativeHasCommittedHead, nativeIsRepo, nativeInit } from "./native-git-bridge.js";
 import { isInheritedRepo } from "./repo-identity.js";
 import { ensureGitignore, ensurePreferences, untrackRuntimeFiles } from "./gitignore.js";
-import { getIsolationMode, loadEffectiveGSDPreferences } from "./preferences.js";
-import { getAutoWorktreePath } from "./auto-worktree.js";
+import { getIsolationMode, loadEffectiveGSDPreferences, renderLanguageDirectiveForPrompt } from "./preferences.js";
+import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
 import { resolveUokFlags } from "./uok/flags.js";
 import { ensurePlanV2Graph, isMissingFinalizedContextResult } from "./uok/plan-v2.js";
 import { detectProjectState, hasGsdBootstrapArtifacts } from "./detection.js";
@@ -94,7 +94,7 @@ import {
 import { probeCoversRequiredWorkflowTools } from "./tool-surface-readiness.js";
 import { getRequiredWorkflowToolsForUnit } from "./unit-tool-contracts.js";
 import { isWorkflowToolSurfaceName } from "./workflow-tool-surface.js";
-import { getUnitWorkflowDispatchReadinessError } from "./tool-contract.js";
+import { getUnitWorkflowDispatchReadinessErrorForModel } from "./tool-contract.js";
 import {
   runPreparation,
   formatCodebaseBrief,
@@ -613,7 +613,7 @@ interface DispatchWorkflowOptions {
   deps?: {
     loadPreferences?: typeof loadEffectiveGSDPreferences;
     selectModel?: typeof selectAndApplyModel;
-    getDispatchReadinessError?: typeof getUnitWorkflowDispatchReadinessError;
+    getDispatchReadinessError?: typeof getUnitWorkflowDispatchReadinessErrorForModel;
   };
 }
 
@@ -730,7 +730,7 @@ async function dispatchWorkflow(
   const loadPreferences = resolvedOptions.deps?.loadPreferences ?? loadEffectiveGSDPreferences;
   const selectModel = resolvedOptions.deps?.selectModel ?? selectAndApplyModel;
   const getDispatchReadinessError = resolvedOptions.deps?.getDispatchReadinessError
-    ?? getUnitWorkflowDispatchReadinessError;
+    ?? getUnitWorkflowDispatchReadinessErrorForModel;
 
   // Route through the dynamic routing pipeline (complexity classification,
   // tier downgrade, fallback chains) — same path as auto-mode dispatches (#2958).
@@ -750,16 +750,12 @@ async function dispatchWorkflow(
     }
 
     const compatibilityError = getDispatchReadinessError({
-      provider: result.appliedModel?.provider ?? ctx.model?.provider,
+      model: result.appliedModel,
+      fallbackModel: ctx.model,
+      getProviderAuthMode: (provider) => ctx.modelRegistry.getProviderAuthMode(provider),
       projectRoot,
       surface: "guided flow",
       unitType,
-      authMode: result.appliedModel?.provider
-        ? ctx.modelRegistry.getProviderAuthMode(result.appliedModel.provider)
-        : ctx.model?.provider
-          ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider)
-          : undefined,
-      baseUrl: result.appliedModel?.baseUrl ?? ctx.model?.baseUrl,
       // Guided flow starts the MCP workflow server as part of dispatch, so the
       // parent session's activeTools doesn't include MCP tools yet. The MCP
       // launch config check (detectWorkflowMcpLaunchConfig) is the right gate
@@ -925,7 +921,7 @@ function resolveAvailableModel<T extends { id: string; provider: string }>(
  * Build the discuss-and-plan prompt for a new milestone.
  * Used by all three "new milestone" paths (first ever, no active, all complete).
  */
-function buildDiscussPrompt(nextId: string, preamble: string, _basePath: string, pi: ExtensionAPI, ctx: ExtensionCommandContext, preparationContext?: string): string {
+function buildDiscussPrompt(nextId: string, preamble: string, basePath: string, pi: ExtensionAPI, ctx: ExtensionCommandContext, preparationContext?: string): string {
   const milestoneRel = `.gsd/milestones/${nextId}`;
   const structuredQuestionsAvailable = getStructuredQuestionsAvailability(pi, ctx);
   const inlinedTemplates = [
@@ -935,7 +931,7 @@ function buildDiscussPrompt(nextId: string, preamble: string, _basePath: string,
     inlineTemplate("roadmap", "Roadmap"),
     inlineTemplate("decisions", "Decisions"),
   ].join("\n\n---\n\n");
-  return loadPrompt("discuss", {
+  return prependLanguageDirective(basePath, loadPrompt("discuss", {
     milestoneId: nextId,
     preamble,
     preparationContext: preparationContext ?? "",
@@ -945,14 +941,26 @@ function buildDiscussPrompt(nextId: string, preamble: string, _basePath: string,
     inlinedTemplates,
     commitInstruction: buildDocsCommitInstruction(`docs(${nextId}): context, requirements, and roadmap`),
     multiMilestoneCommitInstruction: buildDocsCommitInstruction("docs: project plan — N milestones"),
-  });
+  }));
+}
+
+/**
+ * Prepend the configured response-language directive to a dispatched discuss
+ * prompt so the discuss/QA conversation is held in the language set in
+ * PREFERENCES.md (#1210). No-op when no language is configured.
+ */
+function prependLanguageDirective(basePath: string, prompt: string): string {
+  const directive = renderLanguageDirectiveForPrompt(
+    loadEffectiveGSDPreferences(basePath)?.preferences,
+  );
+  return directive ? `${directive}\n\n${prompt}` : prompt;
 }
 
 /**
  * Build the discuss prompt for headless milestone creation.
  * Uses the discuss-headless prompt template with seed context injected.
  */
-function buildHeadlessDiscussPrompt(nextId: string, seedContext: string, _basePath: string): string {
+function buildHeadlessDiscussPrompt(nextId: string, seedContext: string, basePath: string): string {
   const milestoneRel = `.gsd/milestones/${nextId}`;
   const inlinedTemplates = [
     inlineTemplate("project", "Project"),
@@ -961,7 +969,7 @@ function buildHeadlessDiscussPrompt(nextId: string, seedContext: string, _basePa
     inlineTemplate("roadmap", "Roadmap"),
     inlineTemplate("decisions", "Decisions"),
   ].join("\n\n---\n\n");
-  return loadPrompt("discuss-headless", {
+  return prependLanguageDirective(basePath, loadPrompt("discuss-headless", {
     milestoneId: nextId,
     seedContext,
     contextPath: `${milestoneRel}/${nextId}-CONTEXT.md`,
@@ -969,7 +977,7 @@ function buildHeadlessDiscussPrompt(nextId: string, seedContext: string, _basePa
     inlinedTemplates,
     commitInstruction: buildDocsCommitInstruction(`docs(${nextId}): context, requirements, and roadmap`),
     multiMilestoneCommitInstruction: buildDocsCommitInstruction("docs: project plan — N milestones"),
-  });
+  }));
 }
 
 /**

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

@@ -142,7 +142,7 @@ export function emitJournalEvent(basePath: string, entry: JournalEntry): void {
     // Silent failure — journal must never break auto-mode
   }
 
-  if (!isUnifiedAuditEnabled()) return;
+  if (!isUnifiedAuditEnabled(basePath)) return;
   try {
     const causedBy = entry.causedBy
       ? `${entry.causedBy.flowId}:${entry.causedBy.seq}`

package/src/resources/extensions/gsd/markdown-renderer.ts

@@ -38,9 +38,10 @@ import {
   resolveSlicePath,
   resolveTaskFile,
   resolveTasksDir,
+  targetMilestoneFile,
+  targetSliceFile,
   gsdProjectionRoot,
   gsdRoot,
-  buildMilestoneFileName,
   buildTaskFileName,
   buildSliceFileName,
 } from "./paths.js";
@@ -52,9 +53,6 @@ import { readCompatMarker, writeCompatMarker, computeProjectionSha } from "./com
 import type { RiskLevel } from "./types.js";
 import {
   phaseDirName,
-  planFileName,
-  milestoneIdToPhaseNum,
-  sliceIdToPlanNum,
   derivePhaseSlug,
 } from "./layout-policy.js";
 
@@ -176,23 +174,6 @@ function sanitizeInlineRoadmapText(value: string | null | undefined): string {
     .trim();
 }
 
-function resolveRoadmapProjectionPath(basePath: string, milestoneId: string): string {
-  const phaseNum = milestoneIdToPhaseNum(milestoneId);
-  const existing = resolveMilestonePath(basePath, milestoneId);
-  const legacyBase = legacyMilestonesDir(basePath);
-  const isLegacyLayout = existing
-    ? existing.startsWith(legacyBase + "/") || existing.startsWith(legacyBase + "\\")
-    : isLegacyMilestonesLayout(basePath);
-  const phaseDir = existing ?? join(
-    isLegacyLayout ? legacyBase : milestonesDir(basePath),
-    isLegacyLayout ? milestoneId : canonicalPhaseDirName(milestoneId, getMilestone(milestoneId)?.title),
-  );
-  const roadmapFileName = isLegacyLayout
-    ? `${milestoneId}-ROADMAP.md`
-    : `${String(phaseNum).padStart(2, "0")}-ROADMAP.md`;
-  return join(phaseDir, roadmapFileName);
-}
-
 function isMilestoneFlatPhaseLayout(basePath: string, milestoneId: string): boolean {
   const existing = resolveMilestonePath(basePath, milestoneId);
   const legacyBase = legacyMilestonesDir(basePath);
@@ -600,7 +581,7 @@ export async function renderRoadmapFromDb(
       "projection",
       `renderRoadmapFromDb skipped unplanned milestone ${milestoneId} (zero slices, empty vision) — refusing to write a stub ROADMAP`,
     );
-    const absPath = resolveRoadmapProjectionPath(basePath, milestoneId);
+    const absPath = targetMilestoneFile(basePath, milestoneId, "ROADMAP", milestone.title);
     if (existsSync(absPath)) {
       const artifactPath = toArtifactPath(absPath, basePath);
       unlinkSync(absPath);
@@ -614,7 +595,7 @@ export async function renderRoadmapFromDb(
     return { skipped: "unplanned-milestone" };
   }
 
-  const absPath = resolveRoadmapProjectionPath(basePath, milestoneId);
+  const absPath = targetMilestoneFile(basePath, milestoneId, "ROADMAP", milestone.title);
   const artifactPath = toArtifactPath(absPath, basePath);
   const content = renderRoadmapMarkdown(milestone, slices);
 
@@ -655,25 +636,20 @@ export async function renderMilestoneArtifactsFromDb(
   const artifacts = getMilestoneScopedArtifacts(milestoneId);
   if (artifacts.length === 0) return false;
 
-  const phaseDir = resolveMilestonePath(basePath, milestoneId) ??
-    join(
-      milestonesDir(basePath),
-      canonicalPhaseDirName(milestoneId, getMilestone(milestoneId)?.title),
-    );
-  mkdirSync(phaseDir, { recursive: true });
-
-  const legacyBase = legacyMilestonesDir(basePath);
-  const isLegacy = phaseDir.startsWith(legacyBase + "/") || phaseDir.startsWith(legacyBase + "\\");
+  const milestone = getMilestone(milestoneId);
 
   let wrote = false;
   for (const artifact of artifacts) {
     if (artifact.artifact_type === "ROADMAP") continue;
     if (!artifact.full_content.trim()) continue;
 
-    const fileName = isLegacy
-      ? `${milestoneId}-${artifact.artifact_type}.md`
-      : buildMilestoneFileName(milestoneId, artifact.artifact_type);
-    const absPath = join(phaseDir, fileName);
+    const absPath = targetMilestoneFile(
+      basePath,
+      milestoneId,
+      artifact.artifact_type,
+      milestone?.title,
+    );
+    mkdirSync(dirname(absPath), { recursive: true });
     const artifactPath = toArtifactPath(absPath, basePath);
     await writeAndStore(absPath, artifactPath, artifact.full_content, {
       artifact_type: artifact.artifact_type,
@@ -824,22 +800,12 @@ export async function renderSliceSummary(
     return false; // No slice data — skip silently
   }
 
-  // Flat-phase: resolve or create the phase dir, since resolveSlicePath only
-  // finds existing dirs. In flat-phase the slice "path" is the phase dir.
-  let slicePath = resolveSlicePath(basePath, milestoneId, sliceId);
-  if (!slicePath) {
-    const mDir = milestonesDir(basePath);
-    const dirName = canonicalPhaseDirName(milestoneId, getMilestone(milestoneId)?.title);
-    slicePath = join(mDir, dirName);
-    mkdirSync(slicePath, { recursive: true });
-  }
-
+  const milestoneTitle = getMilestone(milestoneId)?.title;
   let wrote = false;
 
-  // Write SUMMARY — flat-phase: NN-MM-SUMMARY.md inside phase dir
   if (slice.full_summary_md) {
-    const summaryName = planFileName(milestoneIdToPhaseNum(milestoneId), sliceIdToPlanNum(sliceId), "SUMMARY");
-    const summaryAbs = join(slicePath, summaryName);
+    const summaryAbs = targetSliceFile(basePath, milestoneId, sliceId, "SUMMARY", milestoneTitle);
+    mkdirSync(dirname(summaryAbs), { recursive: true });
     const summaryArtifact = toArtifactPath(summaryAbs, basePath);
 
     await writeAndStore(summaryAbs, summaryArtifact, slice.full_summary_md, {
@@ -850,10 +816,9 @@ export async function renderSliceSummary(
     wrote = true;
   }
 
-  // Write UAT — flat-phase: NN-MM-UAT.md inside phase dir
   if (slice.full_uat_md) {
-    const uatName = planFileName(milestoneIdToPhaseNum(milestoneId), sliceIdToPlanNum(sliceId), "UAT");
-    const uatAbs = join(slicePath, uatName);
+    const uatAbs = targetSliceFile(basePath, milestoneId, sliceId, "UAT", milestoneTitle);
+    mkdirSync(dirname(uatAbs), { recursive: true });
     const uatArtifact = toArtifactPath(uatAbs, basePath);
 
     await writeAndStore(uatAbs, uatArtifact, slice.full_uat_md, {
@@ -1080,7 +1045,7 @@ function detectStaleRendersImpl(basePath: string): StaleEntry[] {
     // TODO(flat-phase): roadmap checkbox parsing may not match flat-phase
     // roadmap format, causing false-positive drift loops. Skip during transition.
     /*
-    const roadmapPath = resolveRoadmapProjectionPath(basePath, milestone.id);
+    const roadmapPath = targetMilestoneFile(basePath, milestone.id, "ROADMAP", milestone.title);
     if (existsSync(roadmapPath)) {
       try {
         const parsed = parseProjectionByIdentity(roadmapPath, parseRoadmap) as ReturnType<typeof parseRoadmap>;
@@ -1172,36 +1137,28 @@ function detectStaleRendersImpl(basePath: string): StaleEntry[] {
         }
       }
 
-      // Check missing slice summary/UAT files
+      // Check missing slice summary/UAT files. Use the same target helper as
+      // renderSliceSummary so detection and repair agree on flat-phase vs legacy
+      // output locations.
       const sliceRow = getSlice(milestone.id, slice.id);
       if (sliceRow && sliceRow.status === "complete") {
-        // Use the SAME path construction as renderSliceSummary (planFileName format)
-        // so the detector and repair always agree on the file location.
-        const slicePath = resolveSlicePath(basePath, milestone.id, slice.id);
-        if (slicePath) {
-          const phaseNum = milestoneIdToPhaseNum(milestone.id);
-          const planNum = sliceIdToPlanNum(slice.id);
-
-          if (sliceRow.full_summary_md) {
-            const summaryName = planFileName(phaseNum, planNum, "SUMMARY");
-            const summaryAbsPath = join(slicePath, summaryName);
-            if (!existsSync(summaryAbsPath)) {
-              stale.push({
-                path: summaryAbsPath,
-                reason: `${slice.id} is complete with summary in DB but SUMMARY.md missing on disk`,
-              });
-            }
+        if (sliceRow.full_summary_md) {
+          const summaryAbsPath = targetSliceFile(basePath, milestone.id, slice.id, "SUMMARY", milestone.title);
+          if (!existsSync(summaryAbsPath)) {
+            stale.push({
+              path: summaryAbsPath,
+              reason: `${slice.id} is complete with summary in DB but SUMMARY.md missing on disk`,
+            });
           }
+        }
 
-          if (sliceRow.full_uat_md) {
-            const uatName = planFileName(phaseNum, planNum, "UAT");
-            const uatAbsPath = join(slicePath, uatName);
-            if (!existsSync(uatAbsPath)) {
-              stale.push({
-                path: uatAbsPath,
-                reason: `${slice.id} is complete with UAT in DB but UAT.md missing on disk`,
-              });
-            }
+        if (sliceRow.full_uat_md) {
+          const uatAbsPath = targetSliceFile(basePath, milestone.id, slice.id, "UAT", milestone.title);
+          if (!existsSync(uatAbsPath)) {
+            stale.push({
+              path: uatAbsPath,
+              reason: `${slice.id} is complete with UAT in DB but UAT.md missing on disk`,
+            });
           }
         }
       }
@@ -1257,12 +1214,14 @@ export async function renderReplanFromDb(
   sliceId: string,
   replanData: ReplanData,
 ): Promise<{ replanPath: string; content: string }> {
-  // Flat-phase: replan file lives in the phase dir
-  const slicePath = resolveSlicePath(basePath, milestoneId, sliceId)
-    ?? join(milestonesDir(basePath), canonicalPhaseDirName(milestoneId, getMilestone(milestoneId)?.title));
-  const phaseNum = milestoneIdToPhaseNum(milestoneId);
-  const planNum = sliceIdToPlanNum(sliceId);
-  const absPath = join(slicePath, planFileName(phaseNum, planNum, "REPLAN"));
+  const absPath = targetSliceFile(
+    basePath,
+    milestoneId,
+    sliceId,
+    "REPLAN",
+    getMilestone(milestoneId)?.title,
+  );
+  mkdirSync(dirname(absPath), { recursive: true });
   const artifactPath = toArtifactPath(absPath, basePath);
 
   const lines: string[] = [];
@@ -1299,12 +1258,14 @@ export async function renderAssessmentFromDb(
   sliceId: string,
   assessmentData: AssessmentData,
 ): Promise<{ assessmentPath: string; content: string }> {
-  // Flat-phase: assessment file lives in the phase dir
-  const slicePath = resolveSlicePath(basePath, milestoneId, sliceId)
-    ?? join(milestonesDir(basePath), canonicalPhaseDirName(milestoneId, getMilestone(milestoneId)?.title));
-  const phaseNum = milestoneIdToPhaseNum(milestoneId);
-  const planNum = sliceIdToPlanNum(sliceId);
-  const absPath = join(slicePath, planFileName(phaseNum, planNum, "ASSESSMENT"));
+  const absPath = targetSliceFile(
+    basePath,
+    milestoneId,
+    sliceId,
+    "ASSESSMENT",
+    getMilestone(milestoneId)?.title,
+  );
+  mkdirSync(dirname(absPath), { recursive: true });
   const artifactPath = toArtifactPath(absPath, basePath);
 
   const lines: string[] = [];