@opengsd/gsd-pi 1.4.0 → 1.5.0-dev.553dc518

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

@@ -4,21 +4,67 @@
 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";
 import { LAYOUT_SEGMENTS } from "./layout-policy.js";
-import { canonicalPhaseDirName, milestonesDir, resolveMilestonePath } from "./paths.js";
+import { canonicalPhaseDirName, dirIsContentBearingLegacyMilestone, milestonesDir, resolveMilestonePath, } from "./paths.js";
 const LEGACY_MIGRATING_SEGMENT = "milestones.migrating";
+const RETRYABLE_FS_ERROR_CODES = new Set(["EPERM", "EBUSY", "ENOTEMPTY"]);
+const RM_RETRY_OPTIONS = { recursive: true, force: true, maxRetries: 5, retryDelay: 100 };
+let fsOps = { cpSync, renameSync, rmSync };
+export function _setFlatPhaseMigrationFsOpsForTest(overrides) {
+    const previous = fsOps;
+    fsOps = { ...fsOps, ...overrides };
+    return () => {
+        fsOps = previous;
+    };
+}
 function legacyMigratingPath(basePath) {
     return join(basePath, ".gsd", LEGACY_MIGRATING_SEGMENT);
 }
+function removePathWithRetries(path) {
+    fsOps.rmSync(path, { recursive: true, force: true, maxRetries: RM_RETRY_OPTIONS.maxRetries, retryDelay: RM_RETRY_OPTIONS.retryDelay });
+}
+function isRetryableFsError(err) {
+    const code = err?.code;
+    return typeof code === "string" && RETRYABLE_FS_ERROR_CODES.has(code);
+}
+function movePathWithCopyDeleteFallback(src, dst) {
+    try {
+        fsOps.renameSync(src, dst);
+        return;
+    }
+    catch (err) {
+        if (!isRetryableFsError(err))
+            throw err;
+    }
+    try {
+        fsOps.cpSync(src, dst, { recursive: true, force: true });
+        removePathWithRetries(src);
+    }
+    catch (fallbackErr) {
+        if (existsSync(src) && existsSync(dst)) {
+            try {
+                removePathWithRetries(dst);
+            }
+            catch {
+                // Leave the original error intact; the next run can pre-clean dst.
+            }
+        }
+        throw fallbackErr;
+    }
+}
+function expectedPhaseDirs(basePath) {
+    return getAllMilestones().map((milestone) => resolveMilestonePath(basePath, milestone.id) ??
+        join(milestonesDir(basePath), canonicalPhaseDirName(milestone.id, milestone.title)));
+}
 function hasLegacyMilestoneSubdirs(dirPath) {
     if (!existsSync(dirPath))
         return false;
     try {
-        return readdirSync(dirPath).some(e => statSync(join(dirPath, e)).isDirectory());
+        return readdirSync(dirPath).some((e) => statSync(join(dirPath, e)).isDirectory() && dirIsContentBearingLegacyMilestone(join(dirPath, e)));
     }
     catch {
         return false;
@@ -26,19 +72,24 @@ function hasLegacyMilestoneSubdirs(dirPath) {
 }
 function rollbackPartialMigration(basePath, backupDir, migratingPath) {
     // Remove the partially-written phases/ dir.
-    rmSync(join(basePath, ".gsd", LAYOUT_SEGMENTS.level1), { recursive: true, force: true });
+    try {
+        removePathWithRetries(join(basePath, ".gsd", LAYOUT_SEGMENTS.level1));
+    }
+    catch (removeErr) {
+        logWarning("migration", `rollback: could not remove partial ${LAYOUT_SEGMENTS.level1}/: ${removeErr.message}`);
+    }
     // Restore milestones/ — prefer renaming the preserved migrating copy back.
     const milestonesPath = join(basePath, ".gsd", "milestones");
     try {
         if (migratingPath && existsSync(migratingPath) && !existsSync(milestonesPath)) {
-            renameSync(migratingPath, milestonesPath);
+            movePathWithCopyDeleteFallback(migratingPath, milestonesPath);
             return;
         }
         if (existsSync(backupDir)) {
             cpSync(backupDir, milestonesPath, { recursive: true });
         }
         if (migratingPath && existsSync(migratingPath)) {
-            rmSync(migratingPath, { recursive: true, force: true });
+            removePathWithRetries(migratingPath);
         }
     }
     catch (restoreErr) {
@@ -112,7 +163,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.
  */
@@ -146,20 +198,29 @@ export async function migrateToFlatPhase(basePath) {
             logWarning("migration", `flat-phase migration backup failed: ${err.message}`);
             throw err;
         }
+        if (existsSync(migratingPath)) {
+            removePathWithRetries(migratingPath);
+        }
         // 3. Rename legacy tree aside before rendering so path resolvers target
         // phases/ instead of writing back into the nested milestones/ layout.
         // Keep the full tree on disk until render+verify succeed (unlike rmSync).
         try {
-            renameSync(milestonesPath, migratingPath);
+            movePathWithCopyDeleteFallback(milestonesPath, migratingPath);
         }
         catch (err) {
             logWarning("migration", `failed to rename legacy milestones/ before render: ${err.message}`);
             throw err;
         }
     }
-    else {
-        // Interrupted run: clear any partial phases/ projection before retrying.
-        rmSync(phasesPath, { recursive: true, force: true });
+    // Clear any stale or partially-rendered flat projection before this run
+    // writes. Verification below checks the current DB render, not leftovers.
+    try {
+        removePathWithRetries(phasesPath);
+    }
+    catch (err) {
+        logWarning("migration", `failed to clear stale phases/ before render: ${err.message}`);
+        rollbackPartialMigration(basePath, backupDir, migratingPath);
+        throw err;
     }
     // 4. Render flat-phase from DB
     let renderResult;
@@ -191,29 +252,30 @@ export async function migrateToFlatPhase(basePath) {
         throw new Error(`flat-phase migration render failed: ${renderResult.errors.slice(0, 3).join("; ")}`);
     }
     const db = countDbHierarchy();
-    let renderedDirCount = 0;
-    try {
-        // /^\d+-/ matches any numeric prefix (01-, 10-, 100-) so M100+ milestones
-        // whose dirs start with "100-slug" are counted correctly.
-        renderedDirCount = readdirSync(phasesPath, { withFileTypes: true })
-            .filter((entry) => entry.isDirectory() && /^\d+-/.test(entry.name)).length;
-    }
-    catch {
-        // phases/ doesn't exist or is unreadable — same as zero dirs
-    }
-    if (db.milestones > 0 && renderedDirCount !== db.milestones) {
-        logWarning("migration", `phases/ dir count mismatch: expected ${db.milestones}, found ${renderedDirCount}`);
+    const missingPhaseDirs = expectedPhaseDirs(basePath).filter((phaseDir) => !existsSync(phaseDir));
+    if (db.milestones > 0 && missingPhaseDirs.length > 0) {
+        logWarning("migration", `flat-phase migration missing ${missingPhaseDirs.length} expected phase dir(s): ${missingPhaseDirs.join(", ")}`);
         rollbackPartialMigration(basePath, backupDir, migratingPath);
-        throw new Error("flat-phase migration verification failed: phases dir milestone count mismatch");
+        throw new Error("flat-phase migration verification failed: missing rendered phase directories");
     }
     if (db.slices > 0 && renderResult.rendered === 0) {
         logWarning("migration", "flat-phase migration verification failed: render produced no artifacts for populated DB");
         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 {
-        rmSync(migratingPath, { recursive: true, force: true });
+        removePathWithRetries(migratingPath);
     }
     catch (err) {
         logWarning("migration", `flat-phase migration succeeded but could not remove ${LEGACY_MIGRATING_SEGMENT}: ${err.message}`);

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

@@ -16,7 +16,7 @@ import { gsdRoot } from "./paths.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { logWarning } from "./workflow-logger.js";
-import { createRepositoryRegistryFromPreferences } from "./repository-registry.js";
+import { createRepositoryRegistryFromPreferences, defaultRepositoryTargets } from "./repository-registry.js";
 import { isGsdGitignored } from "./gitignore.js";
 import { detectWorktreeName, } from "./worktree.js";
 import { SLICE_BRANCH_RE, QUICK_BRANCH_RE, WORKFLOW_BRANCH_RE } from "./branch-patterns.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.
@@ -1024,28 +1069,25 @@ export function handleTurnGitActionError(action, err) {
         error: errorWithStreams.stderr?.trim() || errorWithStreams.message || getErrorMessage(err),
     };
 }
+export function isRepositoryDirty(repoRoot) {
+    try {
+        return runGit(repoRoot, ["status", "--porcelain"]).length > 0;
+    }
+    catch {
+        // Fallback preserves legacy behavior if explicit status probing fails.
+        return nativeHasChanges(repoRoot);
+    }
+}
 function collectRepositoryDirtyStatus(basePath) {
     const preferences = loadEffectiveGSDPreferences(basePath)?.preferences;
     const registry = createRepositoryRegistryFromPreferences(basePath, preferences);
     const dirtyByRepository = {};
     const registeredRoots = new Set(registry.repositories.map((repo) => resolve(repo.root)));
     for (const repo of registry.repositories) {
-        try {
-            dirtyByRepository[repo.id] = runGit(repo.root, ["status", "--porcelain"]).length > 0;
-        }
-        catch {
-            // Fallback preserves legacy behavior if explicit status probing fails.
-            dirtyByRepository[repo.id] = nativeHasChanges(repo.root);
-        }
+        dirtyByRepository[repo.id] = isRepositoryDirty(repo.root);
     }
     for (const repoRoot of findUndeclaredNestedGitRepositories(registry.projectRoot, registeredRoots)) {
-        let dirty = false;
-        try {
-            dirty = runGit(repoRoot, ["status", "--porcelain"]).length > 0;
-        }
-        catch {
-            dirty = nativeHasChanges(repoRoot);
-        }
+        const dirty = isRepositoryDirty(repoRoot);
         if (!dirty)
             continue;
         const relPath = relative(registry.projectRoot, repoRoot).split(sep).join("/") || repoRoot;
@@ -1098,7 +1140,7 @@ function findUndeclaredNestedGitRepositories(projectRoot, registeredRoots) {
 function runPerRepositoryCommitAction(args) {
     const preferences = loadEffectiveGSDPreferences(args.basePath)?.preferences;
     const registry = createRepositoryRegistryFromPreferences(args.basePath, preferences);
-    const repoIds = args.targetRepositories?.length ? args.targetRepositories : ["project"];
+    const repoIds = args.targetRepositories?.length ? args.targetRepositories : defaultRepositoryTargets(registry);
     const gitPrefs = preferences?.git ?? {};
     const commitMessages = {};
     const commitErrors = {};
@@ -1166,8 +1208,7 @@ export function runTurnGitAction(args) {
                 skippedRepositories: repoCommitResult.skippedRepositories,
             };
         }
-        const primaryMessage = repoCommitResult.commitMessages[args.targetRepositories?.[0] ?? "project"]
-            ?? Object.values(repoCommitResult.commitMessages)[0];
+        const primaryMessage = Object.values(repoCommitResult.commitMessages)[0];
         return {
             action: args.action,
             status: "ok",

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

@@ -410,6 +410,58 @@ export function insertTask(t) {
 export function updateTaskStatus(milestoneId, sliceId, taskId, status, completedAt) {
     applyStatusTransition({ entity: "task", milestoneId, sliceId, taskId, status, completedAt });
 }
+export function repairTaskCompletionFromSummary(t) {
+    const db = getDbOrNull();
+    if (!db)
+        throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    transaction(() => {
+        const seq = db.prepare(`SELECT COALESCE(MAX(sequence), 0) + 1 AS next_sequence
+       FROM tasks
+       WHERE milestone_id = :mid AND slice_id = :sid`).get({ ":mid": t.milestoneId, ":sid": t.sliceId });
+        db.prepare(`INSERT INTO tasks (
+        milestone_id, slice_id, id, title, status, one_liner, narrative,
+        verification_result, duration, completed_at, blocker_discovered,
+        deviations, known_issues, key_files, key_decisions, full_summary_md,
+        sequence
+      ) VALUES (
+        :milestone_id, :slice_id, :id, :title, 'complete', :one_liner, :narrative,
+        :verification_result, :duration, :completed_at, :blocker_discovered,
+        :deviations, :known_issues, :key_files, :key_decisions, :full_summary_md,
+        :sequence
+      )
+      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 = 'complete',
+        one_liner = CASE WHEN NULLIF(:one_liner, '') IS NOT NULL THEN :one_liner ELSE tasks.one_liner END,
+        narrative = CASE WHEN NULLIF(:narrative, '') IS NOT NULL THEN :narrative ELSE tasks.narrative END,
+        verification_result = :verification_result,
+        duration = CASE WHEN NULLIF(:duration, '') IS NOT NULL THEN :duration ELSE tasks.duration END,
+        completed_at = :completed_at,
+        blocker_discovered = :blocker_discovered,
+        deviations = CASE WHEN NULLIF(:deviations, '') IS NOT NULL THEN :deviations ELSE tasks.deviations END,
+        known_issues = CASE WHEN NULLIF(:known_issues, '') IS NOT NULL THEN :known_issues ELSE tasks.known_issues END,
+        key_files = :key_files,
+        key_decisions = :key_decisions,
+        full_summary_md = :full_summary_md`).run({
+            ":milestone_id": t.milestoneId,
+            ":slice_id": t.sliceId,
+            ":id": t.taskId,
+            ":title": t.title ?? "",
+            ":one_liner": t.oneLiner ?? "",
+            ":narrative": t.narrative ?? "",
+            ":verification_result": t.verificationResult,
+            ":duration": t.duration ?? "",
+            ":completed_at": t.completedAt,
+            ":blocker_discovered": t.blockerDiscovered ? 1 : 0,
+            ":deviations": t.deviations ?? "",
+            ":known_issues": t.knownIssues ?? "",
+            ":key_files": JSON.stringify(t.keyFiles ?? []),
+            ":key_decisions": JSON.stringify(t.keyDecisions ?? []),
+            ":full_summary_md": t.fullSummaryMd,
+            ":sequence": seq?.next_sequence ?? 1,
+        });
+    });
+}
 export function setTaskBlockerDiscovered(milestoneId, sliceId, taskId, discovered) {
     if (!getDbOrNull())
         return;
@@ -948,6 +1000,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/guidance.js

@@ -151,6 +151,7 @@ const DOCTOR_FIX_HINTS = {
     state_file_stale: "Run `/gsd doctor fix` to rebuild the projection from the database.",
     state_file_missing: "Run `/gsd doctor fix` to rebuild the projection from the database.",
     projection_drift: "Run `/gsd doctor fix` to rebuild markdown projections from the database (DB is the source of truth).",
+    artifact_user_content_missing: "Doctor cannot recreate user-authored content from the database. Re-run `/gsd discuss` for CONTEXT artifacts or `/gsd auto` for RESEARCH artifacts in that milestone.",
     uat_retry_exhausted: "Review the failing UAT criteria via `/gsd status`, fix the issue, then re-run `/gsd auto`.",
 };
 export function doctorFixHint(code) {

package/dist/resources/extensions/gsd/guided-flow.js

@@ -20,7 +20,7 @@ import { assessInterruptedSession, formatInterruptedSessionRunningMessage, forma
 import { listUnitRuntimeRecords, clearUnitRuntimeRecord, isInFlightRuntimePhase } from "./unit-runtime.js";
 import { resolveExpectedArtifactPath } from "./auto.js";
 import { gsdHome } from "./gsd-home.js";
-import { gsdRoot, milestonesDir, legacyMilestonesDir, resolveMilestoneFile, resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile, relMilestoneFile, relSliceFile, } from "./paths.js";
+import { gsdRoot, milestonesDir, legacyMilestonesDir, resolveMilestoneFile, resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile, relMilestoneFile, relSliceFile, clearPathCache, } from "./paths.js";
 import { join } from "node:path";
 import { readFileSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
 import { readSessionLockData, isSessionLockProcessAlive } from "./session-lock.js";
@@ -28,7 +28,7 @@ import { nativeAddAll, nativeCommit, nativeHasCommittedHead, nativeIsRepo, nativ
 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 { 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,9 +50,10 @@ 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";
 import { clearPendingGate, extractDepthVerificationMilestoneId, getPendingGate } from "./bootstrap/write-gate.js";
 import { _getPendingAutoStart, deletePendingAutoStart, hasPendingAutoStart, setPendingAutoStart, } from "./pending-auto-start.js";
 import { clearGuidedUnitContext, setGuidedUnitContext } from "./guided-unit-context.js";
@@ -78,20 +79,57 @@ export const _scheduleAutoStartAfterIdleForTest = scheduleAutoStartAfterIdle;
 // These thin wrappers accept a MilestoneScope so callers that already hold a
 // pinned scope never have to re-derive (basePath, milestoneId) separately.
 // The underlying implementations in auto-recovery.ts / auto-artifact-paths.ts /
-// state.ts are unchanged — only the call surface in guided-flow.ts is migrated.
+// state.ts remain the default for non-scope-specific units.
 /**
  * Scope-based overload of verifyExpectedArtifact.
  * Uses scope.workspace.projectRoot as the authoritative base path, making
  * the check immune to cwd-drift and worktree-path divergence.
  */
 export function verifyExpectedArtifactForScope(scope, unitType, unitId) {
+    if (unitId === scope.milestoneId &&
+        (unitType === "discuss-milestone" || unitType === "plan-milestone")) {
+        // Layout-aware scope paths use resolveMilestoneFile; clear stale dir listings
+        // primed before discuss/plan wrote CONTEXT.md or ROADMAP.md (see checkAutoStartAfterDiscuss).
+        clearPathCache();
+    }
+    if (unitId === scope.milestoneId &&
+        unitType === "discuss-milestone") {
+        const path = resolveExpectedArtifactPathForScope(scope, unitType, unitId);
+        return path ? existsSync(path) : false;
+    }
+    if (unitId === scope.milestoneId && unitType === "plan-milestone") {
+        const path = resolveExpectedArtifactPathForScope(scope, unitType, unitId);
+        return verifyScopedPlanMilestoneArtifact(path, unitType, unitId);
+    }
     return verifyExpectedArtifact(unitType, unitId, scope.workspace.projectRoot);
 }
+function verifyScopedPlanMilestoneArtifact(path, unitType, unitId) {
+    if (!path || !existsSync(path))
+        return false;
+    try {
+        const roadmapContent = readFileSync(path, "utf-8");
+        if (countPlanMilestoneRoadmapSlices(roadmapContent) === 0) {
+            logWarning("recovery", `verify-fail ${unitType} ${unitId}: roadmap has zero slices at ${path}`);
+            return false;
+        }
+        return true;
+    }
+    catch (err) {
+        logWarning("recovery", `plan-milestone roadmap verification failed: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+}
 /**
  * Scope-based overload of resolveExpectedArtifactPath.
  * Returns the canonical absolute path (or null) using the scope's projectRoot.
  */
 export function resolveExpectedArtifactPathForScope(scope, unitType, unitId) {
+    if (unitId === scope.milestoneId) {
+        if (unitType === "discuss-milestone")
+            return scope.contextFile();
+        if (unitType === "plan-milestone")
+            return scope.roadmapFile();
+    }
     return resolveExpectedArtifactPath(unitType, unitId, scope.workspace.projectRoot);
 }
 async function runQuickTaskChoice(ctx, pi) {
@@ -453,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) {
@@ -468,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

package/dist/resources/extensions/gsd/key-manager.js

@@ -19,6 +19,7 @@ export const PROVIDER_REGISTRY = [
     // must be in the canonical registry so all consumers see the same catalog.
     // See: https://github.com/open-gsd/gsd-pi/issues/4541
     { id: "claude-code", label: "Claude Code CLI", category: "llm", authMode: "externalCli" },
+    { id: "cursor-agent", label: "Cursor Agent", category: "llm", envVar: "CURSOR_API_KEY", authMode: "externalCli" },
     { id: "openai", label: "OpenAI", category: "llm", envVar: "OPENAI_API_KEY", prefixes: ["sk-"], dashboardUrl: "platform.openai.com/api-keys" },
     { id: "github-copilot", label: "GitHub Copilot", category: "llm", envVar: "GITHUB_TOKEN", authMode: "browserOAuth" },
     { id: "openai-codex", label: "ChatGPT Plus/Pro (Codex)", category: "llm", authMode: "browserOAuth" },