@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

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";
@@ -208,6 +208,7 @@ export class MergeConflictError extends GSDError {
  */
 export const RUNTIME_EXCLUSION_PATHS = [
     ".gsd-worktrees/",
+    ".gsd-backups/**",
     ".gsd/activity/",
     ".gsd/audit/",
     ".gsd/forensics/",
@@ -225,6 +226,7 @@ export const RUNTIME_EXCLUSION_PATHS = [
     ".gsd/event-log.jsonl",
     ".gsd/DISCUSSION-MANIFEST.json",
 ];
+const runtimeFilesCleanedUpRepos = new Set();
 // ─── Integration Branch Metadata ───────────────────────────────────────────
 /**
  * Path to the milestone metadata file that stores the integration branch.
@@ -565,7 +567,8 @@ export class GitServiceImpl {
         // and the worktree is torn down. This prevents a mid-execution behavioral
         // discontinuity where the first half of a milestone has .gsd/ artifacts
         // committed but the second half doesn't (#1326).
-        if (!this._runtimeFilesCleanedUp) {
+        const cleanupRepoKey = resolve(this.basePath);
+        if (!runtimeFilesCleanedUpRepos.has(cleanupRepoKey)) {
             let cleaned = false;
             for (const exclusion of RUNTIME_EXCLUSION_PATHS) {
                 const removed = nativeRmCached(this.basePath, [exclusion]);
@@ -575,7 +578,7 @@ export class GitServiceImpl {
             if (cleaned) {
                 nativeCommit(this.basePath, "chore: untrack .gsd/ runtime files from git index", { allowEmpty: false });
             }
-            this._runtimeFilesCleanedUp = true;
+            runtimeFilesCleanedUpRepos.add(cleanupRepoKey);
         }
         // Stage everything using pathspec exclusions so excluded paths are never
         // hashed by git. The old approach of `git add -A` followed by unstaging
@@ -683,8 +686,6 @@ export class GitServiceImpl {
             return false;
         }
     }
-    /** Tracks whether runtime file cleanup has run this session. */
-    _runtimeFilesCleanedUp = false;
     /**
      * Stage files (smart staging) and commit.
      * Returns the commit message string on success, or null if nothing to commit.
@@ -708,11 +709,14 @@ export class GitServiceImpl {
      *
      * Returns the commit message on success, or null if nothing to commit.
      * @param extraExclusions Additional paths to exclude from staging (e.g. [".gsd/"] for pre-switch commits).
+     * @param knownDirty Fresh caller-provided dirty status; when omitted, autoCommit probes the tree.
      */
-    autoCommit(unitType, unitId, extraExclusions = [], taskContext) {
+    autoCommit(unitType, unitId, extraExclusions = [], taskContext, knownDirty) {
         // Quick check: is there anything dirty at all?
         // Native path uses libgit2 (single syscall), fallback spawns git.
-        if (!nativeHasChanges(this.basePath))
+        if (knownDirty === false)
+            return null;
+        if (knownDirty !== true && !nativeHasChanges(this.basePath))
             return null;
         const scoped = taskContext
             ? this.scopedStageTaskFiles(taskContext, extraExclusions)
@@ -1020,25 +1024,78 @@ 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) {
+        dirtyByRepository[repo.id] = isRepositoryDirty(repo.root);
+    }
+    for (const repoRoot of findUndeclaredNestedGitRepositories(registry.projectRoot, registeredRoots)) {
+        const dirty = isRepositoryDirty(repoRoot);
+        if (!dirty)
+            continue;
+        const relPath = relative(registry.projectRoot, repoRoot).split(sep).join("/") || repoRoot;
+        const label = `${relPath} (undeclared)`;
+        dirtyByRepository[label] = true;
+        logWarning("engine", `undeclared dirty nested git repo ${relPath}; declare it under workspace.repositories or commit manually`, { file: "git-service.ts" });
+    }
+    return dirtyByRepository;
+}
+const UNDECLARED_NESTED_REPO_SCAN_MAX_DEPTH = 4;
+const UNDECLARED_NESTED_REPO_SKIP_DIRS = new Set([
+    ".git",
+    ".gsd",
+    ".gsd-worktrees",
+    "node_modules",
+    "dist",
+    "dist-test",
+]);
+function findUndeclaredNestedGitRepositories(projectRoot, registeredRoots) {
+    const found = [];
+    function visit(dir, depth) {
+        if (depth >= UNDECLARED_NESTED_REPO_SCAN_MAX_DEPTH)
+            return;
+        let entries;
         try {
-            dirtyByRepository[repo.id] = runGit(repo.root, ["status", "--porcelain"]).length > 0;
+            entries = readdirSync(dir, { withFileTypes: true });
         }
         catch {
-            // Fallback preserves legacy behavior if explicit status probing fails.
-            dirtyByRepository[repo.id] = nativeHasChanges(repo.root);
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (UNDECLARED_NESTED_REPO_SKIP_DIRS.has(entry.name))
+                continue;
+            const child = join(dir, entry.name);
+            const childRoot = resolve(child);
+            const hasGitDir = existsSync(join(child, ".git"));
+            const isRegistered = registeredRoots.has(childRoot);
+            if (hasGitDir && !isRegistered) {
+                found.push(childRoot);
+                continue;
+            }
+            visit(child, depth + 1);
         }
     }
-    return dirtyByRepository;
+    visit(projectRoot, 0);
+    return found;
 }
 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 = {};
@@ -1054,7 +1111,7 @@ function runPerRepositoryCommitAction(args) {
             continue;
         }
         try {
-            const message = new GitServiceImpl(repo.root, gitPrefs).autoCommit(args.unitType, args.unitId, [], args.taskContext) ?? "";
+            const message = new GitServiceImpl(repo.root, gitPrefs).autoCommit(args.unitType, args.unitId, [], args.taskContext, args.dirtyRepositories?.[repo.id]) ?? "";
             if (message) {
                 commitMessages[repo.id] = message;
             }
@@ -1091,7 +1148,7 @@ export function runTurnGitAction(args) {
                 dirtyRepositories,
             };
         }
-        const repoCommitResult = runPerRepositoryCommitAction(args);
+        const repoCommitResult = runPerRepositoryCommitAction({ ...args, dirtyRepositories });
         if (Object.keys(repoCommitResult.commitErrors).length > 0) {
             return {
                 action: args.action,
@@ -1106,8 +1163,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/gitignore.js

@@ -22,8 +22,9 @@ import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
  * With external state (symlink), these are a no-op in most cases,
  * but retained for backwards compatibility during migration.
  */
-const GSD_RUNTIME_PATTERNS = [
+export const GSD_RUNTIME_PATTERNS = [
     ".gsd-worktrees/",
+    ".gsd-backups/",
     ".gsd/activity/",
     ".gsd/audit/",
     ".gsd/forensics/",
@@ -48,6 +49,8 @@ const BASELINE_PATTERNS = [
     ".gsd",
     // Worktree container sibling — NOT covered by the ".gsd" pattern above.
     ".gsd-worktrees/",
+    // Flat-phase migration snapshots — NOT covered by the ".gsd" pattern above.
+    ".gsd-backups/",
     ".gsd-id",
     ".mcp.json",
     ".bg-shell/",
@@ -201,10 +204,14 @@ export function ensureGitignore(basePath, options) {
         .map((l) => l.trim())
         .filter((l) => l && !l.startsWith("#")));
     // Determine which patterns to apply. If .gsd/ has tracked files,
-    // exclude the ".gsd" pattern to prevent deleting tracked state.
+    // exclude the ".gsd" pattern to prevent deleting tracked state, but
+    // substitute the granular GSD_RUNTIME_PATTERNS so transient artifacts
+    // (STATE.md, runtime/, gsd.db, event-log.jsonl, …) still get ignored.
+    // Without this fallback, the pre-completion commit gate sees those
+    // runtime paths as untracked and blocks milestone close-out forever.
     const gsdIsTracked = hasGitTrackedGsdFiles(basePath);
     const patternsToApply = gsdIsTracked
-        ? BASELINE_PATTERNS.filter((p) => p !== ".gsd")
+        ? Array.from(new Set([...BASELINE_PATTERNS.filter((p) => p !== ".gsd"), ...GSD_RUNTIME_PATTERNS]))
         : BASELINE_PATTERNS;
     // Find patterns not yet present
     const missing = patternsToApply.filter((p) => !existingLines.has(p));

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;

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

@@ -137,20 +137,21 @@ export function crashResumeHint(unitType, unitId) {
 // guidance is authored — the gap is visible in one place.
 const DOCTOR_FIX_HINTS = {
     db_unavailable: "The workflow database could not be opened — state derivation is degraded. Restart the session; if it persists, run `/gsd doctor` from the project root.",
-    stale_crash_lock: "Run `/gsd doctor` to clear the stale lock, then `/gsd auto` to resume.",
-    stale_parallel_session: "Run `/gsd doctor` to clear the stale session registration.",
+    stale_crash_lock: "Run `/gsd doctor fix` to clear the stale lock, then `/gsd auto` to resume.",
+    stale_parallel_session: "Run `/gsd doctor fix` to clear the stale session registration.",
     unresolved_git_conflicts: "Resolve the conflict markers, commit, then re-run `/gsd auto`.",
     conflict_markers_in_tracked_files: "Search the listed files for `<<<<<<<` markers, resolve, and commit.",
     worktree_dirty: "Commit or merge the worktree's changes (`gsd worktree merge <name>`) before removing it.",
     worktree_branch_merged: "The branch is merged — remove the worktree to reclaim space.",
-    orphaned_auto_worktree: "Run `/gsd doctor` to fix, or merge salvageable work with `gsd worktree merge <name>`.",
-    gitignore_missing_patterns: "Run `/gsd doctor` to append the missing .gitignore patterns.",
+    orphaned_auto_worktree: "Run `/gsd doctor fix` to fix, or merge salvageable work with `gsd worktree merge <name>`.",
+    gitignore_missing_patterns: "Run `/gsd doctor fix` to append the missing .gitignore patterns.",
     invalid_preferences: "Edit .gsd/PREFERENCES.md to fix the invalid field, then re-run the command.",
     provider_key_missing: "Add the provider API key to your environment or provider config, then retry.",
     provider_key_backedoff: "The key is cooling down after repeated failures — wait, or switch the phase model in .gsd/PREFERENCES.md.",
-    state_file_stale: "Run `/gsd doctor` to rebuild the projection from the database.",
-    state_file_missing: "Run `/gsd doctor` to rebuild the projection from the database.",
-    projection_drift: "Run `/gsd doctor` to rebuild markdown projections from the database (DB is the source of truth).",
+    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-queue.js

@@ -12,7 +12,7 @@ import { loadFile } from "./files.js";
 import { loadPrompt, inlineTemplate } from "./prompt-loader.js";
 import { deriveState } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
-import { gsdRoot, resolveMilestoneFile, resolveGsdRootFile, relGsdRootFile, } from "./paths.js";
+import { gsdRoot, resolveMilestoneFile, resolveGsdRootFile, relGsdRootFile, relMilestoneFile, } from "./paths.js";
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
 import { nativeAddPaths, nativeCommit } from "./native-git-bridge.js";
@@ -20,6 +20,9 @@ import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { saveQueueOrder } from "./queue-order.js";
 import { findMilestoneIds, nextMilestoneId } from "./milestone-ids.js";
 import { isFutureMilestoneStatus } from "./status-guards.js";
+const QUEUE_ARTIFACT_EXCERPT_MAX_CHARS = 20_000;
+const QUEUE_EXISTING_MILESTONES_CONTEXT_MAX_CHARS = 120_000;
+const QUEUE_CONTEXT_SECTION_SEPARATOR = "\n\n---\n\n";
 // ─── Queue Entry Point ──────────────────────────────────────────────────────
 /**
  * Queue future milestones via conversational intake.
@@ -215,7 +218,7 @@ export async function buildExistingMilestonesContext(basePath, milestoneIds, sta
         if (contextFile) {
             const content = await loadFile(contextFile);
             if (content) {
-                parts.push(`\n**Context:**\n${content.trim()}`);
+                parts.push(`\n**Context:**\n${summarizeArtifactForQueue(content, relMilestoneFile(basePath, mid, "CONTEXT"))}`);
             }
         }
         else {
@@ -224,7 +227,7 @@ export async function buildExistingMilestonesContext(basePath, milestoneIds, sta
             if (draftFile) {
                 const draftContent = await loadFile(draftFile);
                 if (draftContent) {
-                    parts.push(`\n**Draft context available:**\n${draftContent.trim()}`);
+                    parts.push(`\n**Draft context available:**\n${summarizeArtifactForQueue(draftContent, relMilestoneFile(basePath, mid, "CONTEXT-DRAFT"))}`);
                 }
             }
         }
@@ -235,7 +238,7 @@ export async function buildExistingMilestonesContext(basePath, milestoneIds, sta
             if (roadmapFile) {
                 const content = await loadFile(roadmapFile);
                 if (content) {
-                    parts.push(`\n**Roadmap:**\n${content.trim()}`);
+                    parts.push(`\n**Roadmap:**\n${summarizeArtifactForQueue(content, relMilestoneFile(basePath, mid, "ROADMAP"))}`);
                 }
             }
         }
@@ -249,7 +252,65 @@ export async function buildExistingMilestonesContext(basePath, milestoneIds, sta
             sections.push(`### Previous Queue Entries\nSource: \`${relGsdRootFile("QUEUE")}\`\n\n${queueContent.trim()}`);
         }
     }
-    return sections.join("\n\n---\n\n");
+    return capExistingMilestonesContext(sections);
+}
+function summarizeArtifactForQueue(content, sourcePath, cap = QUEUE_ARTIFACT_EXCERPT_MAX_CHARS) {
+    const trimmed = content.trim();
+    if (trimmed.length <= cap) {
+        return `Source: \`${sourcePath}\`\n\n${trimmed}`;
+    }
+    const excerpt = trimmed.slice(0, cap).trimEnd();
+    const omittedChars = trimmed.length - excerpt.length;
+    return [
+        `Source: \`${sourcePath}\``,
+        "",
+        excerpt,
+        "",
+        `[Truncated ${omittedChars} chars. Read \`${sourcePath}\` for full content.]`,
+    ].join("\n");
+}
+function capExistingMilestonesContext(sections, cap = QUEUE_EXISTING_MILESTONES_CONTEXT_MAX_CHARS) {
+    const fullContext = sections.join(QUEUE_CONTEXT_SECTION_SEPARATOR);
+    if (fullContext.length <= cap)
+        return fullContext;
+    const notice = `[Existing milestones context truncated to ${cap} chars. Read source paths in this prompt or the corresponding .gsd artifacts for full details.]`;
+    const noticeSuffix = `${QUEUE_CONTEXT_SECTION_SEPARATOR}${notice}`;
+    const selected = [];
+    for (const section of sections) {
+        const candidate = [...selected, section].join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+        if (candidate.length <= cap) {
+            selected.push(section);
+            continue;
+        }
+        break;
+    }
+    if (selected.length === sections.length) {
+        return selected.join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+    }
+    const compactTail = sections.slice(selected.length).map(compactSectionForQueueBudget);
+    const hybrid = [...selected, ...compactTail].join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+    if (hybrid.length <= cap)
+        return hybrid;
+    const compact = sections.map(compactSectionForQueueBudget);
+    const compactContext = compact.join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+    if (compactContext.length <= cap)
+        return compactContext;
+    return `${compactContext.slice(0, Math.max(0, cap - notice.length - 2)).trimEnd()}\n\n${notice}`;
+}
+function compactSectionForQueueBudget(section) {
+    const lines = section.split("\n");
+    const compact = [];
+    if (lines[0])
+        compact.push(lines[0]);
+    const statusLine = lines.find(line => line.startsWith("**Status:**"));
+    if (statusLine)
+        compact.push(statusLine);
+    const sourceLines = lines.filter(line => line.startsWith("Source: `"));
+    if (sourceLines.length > 0) {
+        compact.push("", "**Sources:**", ...sourceLines);
+        compact.push("", "[Artifact excerpts omitted due to total queue/rethink context budget.]");
+    }
+    return compact.join("\n");
 }
 // ─── Internal Helpers ───────────────────────────────────────────────────────
 /**

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, 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";
@@ -53,6 +53,7 @@ import { isWorkflowToolSurfaceName } from "./workflow-tool-surface.js";
 import { getUnitWorkflowDispatchReadinessError } 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) {
@@ -211,8 +249,11 @@ function hasNestedFileOrSymlink(dir) {
     }
     return false;
 }
-function clearEmptyLegacyDeepSetupPseudoMilestones(basePath, entries) {
-    const mDir = milestonesDir(basePath);
+function clearEmptyLegacyDeepSetupPseudoMilestones(basePath, entries, dir) {
+    // These are LEGACY pseudo-milestone dirs — prefer legacyMilestonesDir (milestones/)
+    // when it exists; caller may also supply the dir directly.
+    const legacyDir = legacyMilestonesDir(basePath);
+    const mDir = dir ?? (existsSync(legacyDir) ? legacyDir : milestonesDir(basePath));
     const remaining = [];
     for (const entry of entries) {
         if (!LEGACY_DEEP_SETUP_PSEUDO_MILESTONE_DIRS.has(entry)) {
@@ -732,7 +773,6 @@ function bootstrapGsdProject(basePath) {
         nativeInit(basePath, mainBranch);
     }
     const root = gsdRoot(basePath);
-    mkdirSync(join(root, "milestones"), { recursive: true });
     mkdirSync(join(root, "runtime"), { recursive: true });
     const gitPrefs = loadEffectiveGSDPreferences(basePath)?.preferences?.git;
     const manageGitignore = gitPrefs?.manage_gitignore;
@@ -1643,9 +1683,12 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
         // cwd, etc). Warn instead of silently starting a new-project flow.
         if (milestoneIds.length === 0) {
             const mDir = milestonesDir(basePath);
-            if (existsSync(mDir)) {
+            const legDir = legacyMilestonesDir(basePath);
+            // Check flat-phase dir first; fall back to legacy milestones/ dir
+            const checkDir = existsSync(mDir) ? mDir : existsSync(legDir) ? legDir : null;
+            if (checkDir) {
                 try {
-                    const entries = clearEmptyLegacyDeepSetupPseudoMilestones(basePath, readdirSync(mDir));
+                    const entries = clearEmptyLegacyDeepSetupPseudoMilestones(basePath, readdirSync(checkDir), checkDir);
                     if (entries.length > 0) {
                         ctx.ui.notify(`Milestone directory has ${entries.length} entries but none were recognized as milestones. ` +
                             `This may indicate a corrupted state or wrong working directory. Run \`/gsd doctor\` to diagnose.`, "warning");