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

package/dist/resources/extensions/gsd/flat-phase-migration.js

@@ -4,7 +4,7 @@
 import { cpSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
 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";
@@ -78,15 +78,33 @@ function rollbackPartialMigration(basePath, backupDir, migratingPath) {
     catch (removeErr) {
         logWarning("migration", `rollback: could not remove partial ${LAYOUT_SEGMENTS.level1}/: ${removeErr.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 = () => {
+        if (!isDisposableBackup || !existsSync(backupDir))
+            return;
+        try {
+            removePathWithRetries(backupDir);
+        }
+        catch (cleanupErr) {
+            logWarning("migration", `rollback: could not clean backup ${backupDir}: ${cleanupErr.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);
@@ -163,7 +181,8 @@ export function pruneStaleFlatPhaseBackups(basePath) {
  * 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.
  */
@@ -262,7 +281,17 @@ export async function migrateToFlatPhase(basePath) {
         rollbackPartialMigration(basePath, backupDir, migratingPath);
         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.message}`);
+        rollbackPartialMigration(basePath, backupDir, migratingPath);
+        throw err;
+    }
+    // 7. Remove the renamed legacy tree (backup already on disk).
     try {
         removePathWithRetries(migratingPath);
     }

package/dist/resources/extensions/gsd/forensics.js

@@ -24,7 +24,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 { isInteractiveCommandContext, notifyForensicsNeedsInteractiveMenu, } from "./command-feedback.js";

package/dist/resources/extensions/gsd/git-conflict-resolve.js

@@ -2,8 +2,8 @@
 // File Purpose: Shared auto-resolution of safe merge conflict paths.
 import { logWarning } from "./workflow-logger.js";
 import { nativeAddPaths, nativeCheckoutTheirs, nativeRmForce, } from "./native-git-bridge.js";
-import { isSafeToAutoResolve } from "./auto-worktree.js";
-export { isSafeToAutoResolve } from "./auto-worktree.js";
+import { isSafeToAutoResolve } from "./auto-worktree-conflict-auto-resolve.js";
+export { isSafeToAutoResolve } from "./auto-worktree-conflict-auto-resolve.js";
 /**
  * Auto-resolve paths that are safe to accept from the milestone side
  * (.gsd/ state and build artifacts).

package/dist/resources/extensions/gsd/git-service.js

@@ -519,6 +519,51 @@ export function runGit(basePath, args, options = {}) {
         throw new GSDError(GSD_GIT_ERROR, `git ${args.join(" ")} failed in ${basePath}: ${filterGitSvnNoise(message)}`);
     }
 }
+/**
+ * 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, branchName, currentBranch, baseBranch) {
+    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 ─────────────────────────────────────────────────
 /**
  * Keyword-to-commit-type mapping. Order matters — first match wins.

package/dist/resources/extensions/gsd/gsd-db.js

@@ -352,17 +352,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,
@@ -401,6 +401,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
             ? JSON.stringify(t.planning.targetRepositories ?? [])
@@ -1000,6 +1001,17 @@ export function deleteArtifactByPath(path) {
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
     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) {
+    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/dist/resources/extensions/gsd/guided-flow.js

@@ -27,8 +27,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";
@@ -50,7 +50,7 @@ import { getCachedWorkflowMcpProbe, probeAndCacheWorkflowMcp, warmWorkflowMcpPro
 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, formatPriorContextBrief, } from "./preparation.js";
 import { verifyExpectedArtifact } from "./auto-recovery.js";
 import { countPlanMilestoneRoadmapSlices } from "./artifact-verification.js";
@@ -491,7 +491,7 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType,
     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).
     if (ctx && unitType) {
@@ -506,16 +506,12 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType,
             });
         }
         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
@@ -646,7 +642,7 @@ function resolveAvailableModel(modelId, availableModels, currentProvider) {
  * 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, preamble, _basePath, pi, ctx, preparationContext) {
+function buildDiscussPrompt(nextId, preamble, basePath, pi, ctx, preparationContext) {
     const milestoneRel = `.gsd/milestones/${nextId}`;
     const structuredQuestionsAvailable = getStructuredQuestionsAvailability(pi, ctx);
     const inlinedTemplates = [
@@ -656,7 +652,7 @@ function buildDiscussPrompt(nextId, preamble, _basePath, pi, ctx, preparationCon
         inlineTemplate("roadmap", "Roadmap"),
         inlineTemplate("decisions", "Decisions"),
     ].join("\n\n---\n\n");
-    return loadPrompt("discuss", {
+    return prependLanguageDirective(basePath, loadPrompt("discuss", {
         milestoneId: nextId,
         preamble,
         preparationContext: preparationContext ?? "",
@@ -666,13 +662,22 @@ function buildDiscussPrompt(nextId, preamble, _basePath, pi, ctx, preparationCon
         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, prompt) {
+    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, seedContext, _basePath) {
+function buildHeadlessDiscussPrompt(nextId, seedContext, basePath) {
     const milestoneRel = `.gsd/milestones/${nextId}`;
     const inlinedTemplates = [
         inlineTemplate("project", "Project"),
@@ -681,7 +686,7 @@ function buildHeadlessDiscussPrompt(nextId, seedContext, _basePath) {
         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`,
@@ -689,7 +694,7 @@ function buildHeadlessDiscussPrompt(nextId, seedContext, _basePath) {
         inlinedTemplates,
         commitInstruction: buildDocsCommitInstruction(`docs(${nextId}): context, requirements, and roadmap`),
         multiMilestoneCommitInstruction: buildDocsCommitInstruction("docs: project plan — N milestones"),
-    });
+    }));
 }
 /**
  * Run preparation phase if enabled, then build the discuss prompt.

package/dist/resources/extensions/gsd/journal.js

@@ -51,7 +51,7 @@ export function emitJournalEvent(basePath, entry) {
     catch {
         // Silent failure — journal must never break auto-mode
     }
-    if (!isUnifiedAuditEnabled())
+    if (!isUnifiedAuditEnabled(basePath))
         return;
     try {
         const causedBy = entry.causedBy

package/dist/resources/extensions/gsd/markdown-renderer.js

@@ -13,13 +13,12 @@ import { logWarning } from "./workflow-logger.js";
 import { isClosedStatus } from "./status-guards.js";
 import { dirname, join, relative } from "node:path";
 import { getAllMilestones, getMilestone, getMilestoneScopedArtifacts, getSliceScopedArtifacts, getMilestoneSlices, getSliceTasks, getTasksBySliceIds, getTask, getSlice, insertArtifact, deleteArtifactByPath, getGateResults, isDbAvailable, } from "./gsd-db.js";
-import { resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, gsdProjectionRoot, gsdRoot, buildMilestoneFileName, buildTaskFileName, } from "./paths.js";
+import { resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, targetMilestoneFile, targetSliceFile, gsdProjectionRoot, gsdRoot, buildTaskFileName, } from "./paths.js";
 import { saveFile, clearParseCache, registerCacheClearCallback } from "./files.js";
 import { parseRoadmap, parsePlan } from "./parsers-legacy.js";
 import { invalidateStateCache } from "./state.js";
 import { clearPathCache, milestonesDir, legacyMilestonesDir, isLegacyMilestonesLayout, resolveMilestonePath, relSliceFile, canonicalPhaseDirName } from "./paths.js";
 import { readCompatMarker, writeCompatMarker, computeProjectionSha } from "./compat/compat-marker.js";
-import { planFileName, milestoneIdToPhaseNum, sliceIdToPlanNum, } from "./layout-policy.js";
 // ─── Compat marker invalidation ───────────────────────────────────────────
 // Every successful projection write pushes its (basePath, projectionPath,
 // entities) here; invalidateCaches() drains it and refreshes .gsd/.compat.json
@@ -134,19 +133,6 @@ function sanitizeInlineRoadmapText(value) {
         .replace(/\s+/g, " ")
         .trim();
 }
-function resolveRoadmapProjectionPath(basePath, milestoneId) {
-    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, milestoneId) {
     const existing = resolveMilestonePath(basePath, milestoneId);
     const legacyBase = legacyMilestonesDir(basePath);
@@ -492,7 +478,7 @@ export async function renderRoadmapFromDb(basePath, milestoneId) {
     // clear "write the ROADMAP" failure) instead of a misleading stub.
     if (slices.length === 0 && !milestone.vision.trim()) {
         logWarning("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);
@@ -506,7 +492,7 @@ export async function renderRoadmapFromDb(basePath, milestoneId) {
         }
         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);
     await writeAndStore(absPath, artifactPath, content, {
@@ -536,21 +522,15 @@ export async function renderMilestoneArtifactsFromDb(basePath, milestoneId) {
     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,
@@ -664,20 +644,11 @@ export async function renderSliceSummary(basePath, milestoneId, sliceId) {
     if (!slice) {
         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, {
             artifact_type: "SUMMARY",
@@ -686,10 +657,9 @@ export async function renderSliceSummary(basePath, milestoneId, sliceId) {
         }, basePath);
         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, {
             artifact_type: "UAT",
@@ -874,7 +844,7 @@ function detectStaleRendersImpl(basePath) {
         // 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>;
@@ -961,34 +931,27 @@ function detectStaleRendersImpl(basePath) {
                     }
                 }
             }
-            // 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`,
+                        });
                     }
                 }
             }
@@ -1013,12 +976,8 @@ export function roadmapRenderMarksSliceDone(roadmapContent, sliceId) {
     return parseRoadmap(roadmapContent).slices.some((slice) => slice.id === sliceId && slice.done);
 }
 export async function renderReplanFromDb(basePath, milestoneId, sliceId, replanData) {
-    // 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 = [];
     lines.push(`# ${sliceId} Replan`);
@@ -1045,12 +1004,8 @@ export async function renderReplanFromDb(basePath, milestoneId, sliceId, replanD
     return { replanPath: absPath, content };
 }
 export async function renderAssessmentFromDb(basePath, milestoneId, sliceId, assessmentData) {
-    // 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 = [];
     lines.push(`# ${sliceId} Assessment`);