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

package/dist/resources/extensions/gsd/validation-block-guard.js

@@ -5,7 +5,7 @@ import { getAutoWorktreePath, isInAutoWorktree } from "./auto-worktree.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import { refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 import { getIsolationMode } from "./preferences.js";
-import { deriveState } from "./state.js";
+import { deriveState, invalidateStateCache } from "./state.js";
 import { detectWorktreeName } from "./worktree.js";
 const VALIDATION_BLOCK_RE = /milestone validation returned needs-(?:attention|remediation)|validation verdict is needs-(?:attention|remediation)/i;
 const VALIDATION_SAFE_DISPATCH_COMMANDS = new Set([
@@ -21,6 +21,27 @@ const VALIDATION_BLOCKED_COMMANDS = new Set([
     "ship",
     "complete-milestone",
     "do",
+    "discuss-phase",
+    "import",
+    "ingest-docs",
+    "review-backlog",
+    "docs-update",
+    "secure-phase",
+    "plan-phase",
+    "execute-phase",
+    "spec-phase",
+    "mvp-phase",
+    "ui-phase",
+    "ai-integration-phase",
+    "ultraplan-phase",
+    "plan-review-convergence",
+    "autonomous",
+    "resume-work",
+    "discuss-phase",
+    "import",
+    "ingest-docs",
+    "review-backlog",
+    "secure-phase",
 ]);
 const VALIDATION_BLOCKED_PARALLEL_SUBCOMMANDS = new Set([
     "",
@@ -38,6 +59,15 @@ const VALIDATION_SAFE_WORKFLOW_SUBCOMMANDS = new Set([
     "install",
     "uninstall",
 ]);
+function hasFlag(command, flag) {
+    const escaped = flag.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(?:^|\\s)${escaped}(?=\\s|$)`).test(command);
+}
+function isMutatingPhaseCommand(subcommand) {
+    if (!subcommand)
+        return false;
+    return ["add", "create", "new", "insert", "remove", "edit"].includes(subcommand);
+}
 export function isValidationBlockedState(state) {
     if (state.phase !== "blocked")
         return false;
@@ -57,6 +87,21 @@ export function isValidationBlockAllowedCommand(trimmed) {
     if (name === "workflow") {
         return VALIDATION_SAFE_WORKFLOW_SUBCOMMANDS.has(subcommand ?? "");
     }
+    if (name === "audit-fix") {
+        return hasFlag(command, "--dry-run");
+    }
+    if (name === "code-review") {
+        return !hasFlag(command, "--fix");
+    }
+    if (name === "docs-update") {
+        return hasFlag(command, "--verify-only");
+    }
+    if (name === "phase") {
+        return !isMutatingPhaseCommand(subcommand);
+    }
+    if (name === "progress") {
+        return !hasFlag(command, "--next") && !hasFlag(command, "--do");
+    }
     return !VALIDATION_BLOCKED_COMMANDS.has(name);
 }
 export function formatValidationBlockedMessage(state, attemptedCommand = "") {
@@ -71,9 +116,7 @@ export function formatValidationBlockedMessage(state, attemptedCommand = "") {
         ...blockers,
     ].join("\n\n");
 }
-export async function getValidationBlockMessageForBase(base, attemptedCommand = "") {
-    await ensureDbOpen(base);
-    refreshWorkflowDatabaseFromDisk();
+async function deriveValidationBlockState(base) {
     let state = await deriveState(base);
     if (state.activeMilestone &&
         getIsolationMode(base) === "worktree" &&
@@ -84,5 +127,12 @@ export async function getValidationBlockMessageForBase(base, attemptedCommand =
             state = await deriveState(wtPath);
         }
     }
+    return state;
+}
+export async function getValidationBlockMessageForBase(base, attemptedCommand = "") {
+    await ensureDbOpen(base);
+    refreshWorkflowDatabaseFromDisk();
+    invalidateStateCache();
+    const state = await deriveValidationBlockState(base);
     return formatValidationBlockedMessage(state, attemptedCommand);
 }

package/dist/resources/extensions/gsd/verification-gate.js

@@ -201,6 +201,13 @@ export function formatFailureContext(result) {
     }
     return header + body;
 }
+export function formatFailureSignature(result) {
+    return result.checks
+        .filter((check) => check.exitCode !== 0)
+        .map((check) => `${check.command.trim()}#${check.exitCode}`)
+        .sort()
+        .join("\n");
+}
 // ─── Gate Execution ─────────────────────────────────────────────────────────
 /** Characters that indicate shell control syntax when unquoted in a command string. */
 const UNQUOTED_SHELL_CONTROL_CHARS = new Set([";", "<", ">"]);

package/dist/resources/extensions/gsd/visualizer-data.js

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { deriveState } from './state.js';
 import { parseSummary, loadFile } from './files.js';
 import { isDbAvailable, getMilestoneSlices, getSliceTasks } from './gsd-db.js';
+import { openExistingWorkflowDatabase } from './db-workspace.js';
 import { parseRoadmap, parsePlan } from './parsers-legacy.js';
 import { findMilestoneIds } from './milestone-ids.js';
 import { resolveMilestoneFile, resolveSliceFile, resolveGsdRootFile, gsdRoot } from './paths.js';
@@ -15,6 +16,7 @@ import { generateSkillHealthReport } from './skill-health.js';
 import { runEnvironmentChecks } from './doctor-environment.js';
 import { computeProgressScore } from './progress-score.js';
 import { getHealthHistory } from './doctor-proactive.js';
+import { getActiveMemories, getActiveMemoriesRanked } from './memory-store.js';
 // ─── Critical Path ────────────────────────────────────────────────────────────
 export function computeCriticalPath(milestones) {
     const empty = {
@@ -351,6 +353,36 @@ function loadKnowledge(basePath) {
     }
     return { rules, patterns, lessons, exists: true };
 }
+// ─── Memory Loader ────────────────────────────────────────────────────────────
+const VISUALIZER_MEMORY_LIMIT = 20;
+const VISUALIZER_MEMORY_CONTENT_LIMIT = 2000;
+function ensureVisualizerDb(basePath) {
+    if (isDbAvailable())
+        return;
+    openExistingWorkflowDatabase(basePath);
+}
+function loadMemories() {
+    const allActive = getActiveMemories();
+    const ranked = getActiveMemoriesRanked(VISUALIZER_MEMORY_LIMIT);
+    return {
+        totalCount: allActive.length,
+        entries: ranked.map((memory) => ({
+            id: memory.id,
+            category: memory.category,
+            content: limitMemoryContent(memory.content),
+            confidence: memory.confidence,
+            hitCount: memory.hit_count,
+            scope: memory.scope,
+            tags: memory.tags,
+            updatedAt: memory.updated_at,
+        })),
+    };
+}
+function limitMemoryContent(content) {
+    if (content.length <= VISUALIZER_MEMORY_CONTENT_LIMIT)
+        return content;
+    return `${content.slice(0, VISUALIZER_MEMORY_CONTENT_LIMIT).trimEnd()}...`;
+}
 // ─── Health Loader ────────────────────────────────────────────────────────────
 function loadHealth(units, totals, basePath) {
     const prefs = loadEffectiveGSDPreferences();
@@ -524,6 +556,7 @@ function readFileCached(filePath) {
 }
 // ─── Loader ───────────────────────────────────────────────────────────────────
 export async function loadVisualizerData(basePath) {
+    ensureVisualizerDb(basePath);
     const state = await deriveState(basePath);
     const milestoneIds = findMilestoneIds(basePath);
     const milestones = [];
@@ -640,6 +673,7 @@ export async function loadVisualizerData(basePath) {
     const agentActivity = loadAgentActivity(units, milestones);
     const { changelog, verifications: sliceVerifications } = await loadChangelogAndVerifications(basePath, milestones);
     const knowledge = loadKnowledge(basePath);
+    const memories = loadMemories();
     const allCaptures = loadAllCaptures(basePath);
     const pendingCount = countPendingCaptures(basePath);
     const captures = {
@@ -666,6 +700,7 @@ export async function loadVisualizerData(basePath) {
         changelog,
         sliceVerifications,
         knowledge,
+        memories,
         captures,
         health,
         discussion,

package/dist/resources/extensions/gsd/visualizer-views.js

@@ -705,11 +705,16 @@ export function renderExportView(_data, th, _width, lastExportPath) {
 export function renderKnowledgeView(data, th, width) {
     const lines = [];
     const knowledge = data.knowledge;
-    if (!knowledge.exists) {
+    const memories = data.memories;
+    if (!knowledge.exists && memories.entries.length === 0) {
         lines.push(th.fg("dim", "No KNOWLEDGE.md found"));
         return lines;
     }
-    if (knowledge.rules.length === 0 && knowledge.patterns.length === 0 && knowledge.lessons.length === 0) {
+    if (knowledge.exists &&
+        knowledge.rules.length === 0 &&
+        knowledge.patterns.length === 0 &&
+        knowledge.lessons.length === 0 &&
+        memories.entries.length === 0) {
         lines.push(th.fg("dim", "KNOWLEDGE.md exists but is empty"));
         return lines;
     }
@@ -740,6 +745,20 @@ export function renderKnowledgeView(data, th, width) {
         }
         lines.push("");
     }
+    if (memories.entries.length > 0) {
+        const countLabel = memories.totalCount > memories.entries.length
+            ? `${memories.entries.length}/${memories.totalCount}`
+            : `${memories.totalCount}`;
+        lines.push(th.fg("accent", th.bold(`Memories (${countLabel})`)));
+        lines.push("");
+        for (const memory of memories.entries) {
+            const scope = memory.scope && memory.scope !== "project" ? ` ${th.fg("dim", `[${memory.scope}]`)}` : "";
+            const tags = memory.tags.length > 0 ? ` ${th.fg("dim", `#${memory.tags.join(" #")}`)}` : "";
+            lines.push(truncateToWidth(`  ${th.fg("accent", memory.id)}  (${memory.category}, ${memory.confidence.toFixed(2)}, hits ${memory.hitCount})${scope}${tags}`, width));
+            lines.push(truncateToWidth(`    ${memory.content}`, width));
+        }
+        lines.push("");
+    }
     return lines;
 }
 // ─── Captures View ───────────────────────────────────────────────────────────

package/dist/resources/extensions/gsd/workflow-manifest.js

@@ -1,11 +1,12 @@
 // Project/App: gsd-pi
 // File Purpose: State manifest snapshot and restore orchestration for GSD workflow data.
 import { _getAdapter, readTransaction, restoreManifest, } from "./gsd-db.js";
-import { atomicWriteSync } from "./atomic-write.js";
+import { atomicWriteAsync, atomicWriteSync } from "./atomic-write.js";
 import { getAllDecisionsFromMemories } from "./context-store.js";
 import { backfillDecisionsToMemories } from "./memory-backfill.js";
 import { invalidateAllCaches } from "./cache.js";
-import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { logWarning } from "./workflow-logger.js";
+import { readFileSync, existsSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
 // ─── helpers ─────────────────────────────────────────────────────────────
 function requireDb() {
@@ -257,22 +258,131 @@ export function snapshotState() {
         return result;
     });
 }
-// ─── restore ─────────────────────────────────────────────────────────────
-//
-// The actual restore() implementation lives in gsd-db.ts (single-writer
-// invariant). This module only orchestrates reading the manifest file
-// and handing it to the writer.
-// ─── writeManifest ───────────────────────────────────────────────────────
+const manifestWrites = new Map();
+let processTeardownFlushInstalled = false;
+let beforeExitFlushStarted = false;
+function manifestWriteKey(basePath) {
+    return resolve(basePath);
+}
+function manifestFilePath(basePath) {
+    return join(resolve(basePath), ".gsd", "state-manifest.json");
+}
+function describeError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function logManifestWriteFailure(filePath, err) {
+    logWarning("manifest", `state manifest write failed: ${describeError(err)}`, { file: filePath });
+}
+async function drainManifestWrites(key, state) {
+    let lastWriteError = null;
+    try {
+        while (state.latestJson !== null && state.syncFlushJson === null) {
+            const json = state.latestJson;
+            state.latestJson = null;
+            state.inFlightJson = json;
+            try {
+                await atomicWriteAsync(state.filePath, json);
+                if (state.syncFlushJson !== null) {
+                    atomicWriteSync(state.filePath, state.syncFlushJson);
+                    break;
+                }
+                lastWriteError = null;
+            }
+            catch (err) {
+                lastWriteError = err;
+                logManifestWriteFailure(state.filePath, err);
+            }
+            finally {
+                state.inFlightJson = null;
+            }
+        }
+    }
+    finally {
+        state.active = null;
+        if (state.latestJson === null && state.inFlightJson === null) {
+            manifestWrites.delete(key);
+        }
+    }
+    if (lastWriteError !== null && state.syncFlushJson === null) {
+        throw lastWriteError;
+    }
+}
+function enqueueManifestWrite(basePath, json) {
+    const key = manifestWriteKey(basePath);
+    let state = manifestWrites.get(key);
+    if (!state) {
+        state = {
+            filePath: manifestFilePath(basePath),
+            latestJson: null,
+            inFlightJson: null,
+            syncFlushJson: null,
+            active: null,
+        };
+        manifestWrites.set(key, state);
+    }
+    state.latestJson = json;
+    if (!state.active) {
+        const active = drainManifestWrites(key, state);
+        void active.catch(() => { });
+        state.active = active;
+    }
+}
 /**
- * Write current DB state to .gsd/state-manifest.json via atomicWriteSync.
+ * Queue current DB state for an async atomic write to .gsd/state-manifest.json.
  * Uses JSON.stringify with 2-space indent for git three-way merge friendliness.
  */
 export function writeManifest(basePath) {
     const manifest = snapshotState();
     const json = JSON.stringify(manifest, null, 2);
-    const dir = join(basePath, ".gsd");
-    mkdirSync(dir, { recursive: true });
-    atomicWriteSync(join(dir, "state-manifest.json"), json);
+    enqueueManifestWrite(basePath, json);
+}
+async function flushManifestByKey(key) {
+    for (;;) {
+        const active = manifestWrites.get(key)?.active;
+        if (!active)
+            return;
+        await active;
+    }
+}
+/**
+ * Wait for any queued manifest write for this base path to become durable.
+ */
+export async function flushManifest(basePath) {
+    await flushManifestByKey(manifestWriteKey(basePath));
+}
+export async function flushAllManifests() {
+    await Promise.all(Array.from(manifestWrites.keys(), key => flushManifestByKey(key)));
+}
+function flushAllManifestsSync() {
+    for (const [key, state] of manifestWrites) {
+        const json = state.latestJson ?? state.inFlightJson;
+        if (json === null)
+            continue;
+        try {
+            atomicWriteSync(state.filePath, json);
+            state.latestJson = null;
+            state.inFlightJson = null;
+            state.syncFlushJson = json;
+            manifestWrites.delete(key);
+        }
+        catch (err) {
+            logManifestWriteFailure(state.filePath, err);
+        }
+    }
+}
+export function installManifestFlushOnProcessTeardown() {
+    if (processTeardownFlushInstalled)
+        return;
+    processTeardownFlushInstalled = true;
+    process.once("beforeExit", () => {
+        if (beforeExitFlushStarted)
+            return;
+        beforeExitFlushStarted = true;
+        void flushAllManifests();
+    });
+    process.once("exit", () => {
+        flushAllManifestsSync();
+    });
 }
 // ─── readManifest ────────────────────────────────────────────────────────
 /**
@@ -317,7 +427,10 @@ function restoreArtifactProjections(basePath, manifest) {
     if (manifest.artifacts === undefined)
         return;
     for (const artifact of manifest.artifacts) {
-        atomicWriteSync(artifactProjectionPath(basePath, artifact.path), artifact.full_content ?? "");
+        const content = artifact.full_content ?? "";
+        if (content === "")
+            continue;
+        atomicWriteSync(artifactProjectionPath(basePath, artifact.path), content);
     }
 }
 // ─── bootstrapFromManifest ──────────────────────────────────────────────

package/dist/resources/extensions/gsd/workflow-mcp.js

@@ -54,6 +54,7 @@ function lookupCommand(command, platform = process.platform) {
         return null;
     }
 }
+const gsdPiRepoRootCache = new Map();
 function findGsdPiRepoRoot(startPath) {
     let current;
     try {
@@ -62,15 +63,22 @@ function findGsdPiRepoRoot(startPath) {
     catch {
         current = resolve(startPath);
     }
+    const cacheKey = current;
+    if (gsdPiRepoRootCache.has(cacheKey)) {
+        return gsdPiRepoRootCache.get(cacheKey) ?? null;
+    }
     while (true) {
         const distCli = resolve(current, "packages", "mcp-server", "dist", "cli.js");
-        if (existsSync(distCli))
+        if (existsSync(distCli)) {
+            gsdPiRepoRootCache.set(cacheKey, current);
             return current;
+        }
         const parent = dirname(current);
         if (parent === current)
             break;
         current = parent;
     }
+    gsdPiRepoRootCache.set(cacheKey, null);
     return null;
 }
 function findWorkflowCliFromAncestorPath(startPath) {

package/dist/resources/extensions/gsd/workflow-projections.js

@@ -13,7 +13,7 @@ import { isClosedStatus } from "./status-guards.js";
 import { deriveState } from "./state.js";
 import { renderPlanFromDb, renderRoadmapFromDb } from "./markdown-renderer.js";
 import { readManifest } from "./workflow-manifest.js";
-import { gsdRoot } from "./paths.js";
+import { gsdRoot, resolveSliceFile, resolveMilestonePath, resolveSlicePath, gsdProjectionRoot } from "./paths.js";
 // ─── Helpers ─────────────────────────────────────────────────────────────
 /**
  * Strip a leading ID prefix (e.g. "M001: " or "S04: ") from a title
@@ -276,7 +276,24 @@ export function renderSummaryProjection(basePath, milestoneId, sliceId, taskId)
         return;
     const evidenceRows = getVerificationEvidence(milestoneId, sliceId, taskId);
     const content = renderSummaryContent(taskRow, sliceId, milestoneId, evidenceRows);
-    const dir = join(basePath, ".gsd", "milestones", milestoneId, "slices", sliceId, "tasks");
+    // Layout-aware: avoid creating a milestones/ directory as a side effect for
+    // flat-phase projects. If milestonesDir() sees a freshly-created milestones/
+    // dir it treats the project as legacy, breaking all subsequent path resolution.
+    const slicePath = resolveSlicePath(basePath, milestoneId, sliceId);
+    const phaseDir = resolveMilestonePath(basePath, milestoneId);
+    let dir;
+    if (slicePath && phaseDir && slicePath !== phaseDir) {
+        // Legacy layout: slice has its own slices/SID/ subdir → tasks/ subdir
+        dir = join(slicePath, "tasks");
+    }
+    else if (phaseDir) {
+        // Flat-phase: task summaries go in the phase dir (no tasks/ subdir needed)
+        dir = phaseDir;
+    }
+    else {
+        // Fallback: legacy hardcoded path (milestone dir not on disk yet)
+        dir = join(gsdProjectionRoot(basePath), "milestones", milestoneId, "slices", sliceId, "tasks");
+    }
     mkdirSync(dir, { recursive: true });
     atomicWriteSync(join(dir, `${taskId}-SUMMARY.md`), content);
 }
@@ -382,15 +399,13 @@ export async function renderStateProjection(basePath) {
         logWarning("projection", `renderStateProjection failed: ${err.message}`);
     }
 }
-// ─── renderAllProjections ───────────────────────────────────────────────
+// ─── renderMilestoneShellProjections ─────────────────────────────────────
 /**
- * Regenerate all projection files for a milestone from DB state.
- * All calls are wrapped in try/catch — projection failure is non-fatal per D-02.
+ * Regenerate milestone-level projections (roadmap, top-level views, STATE.md).
+ * Does not touch slice PLAN.md or task SUMMARY.md — those have authoritative
+ * renderers in plan-slice / complete-task.
  */
-export async function renderAllProjections(basePath, milestoneId) {
-    // Delegate to the authoritative roadmap renderer — the reduced
-    // renderRoadmapProjection omits sections like ## Boundary Map and would
-    // clobber the output written by plan-milestone / reassess-roadmap.
+export async function renderMilestoneShellProjections(basePath, milestoneId) {
     try {
         await renderRoadmapFromDb(basePath, milestoneId);
     }
@@ -409,6 +424,20 @@ export async function renderAllProjections(basePath, milestoneId) {
     catch (err) {
         logWarning("projection", `renderTopLevelQueueFromDb failed: ${err.message}`);
     }
+    try {
+        await renderStateProjection(basePath);
+    }
+    catch (err) {
+        logWarning("projection", `renderStateProjection failed: ${err.message}`);
+    }
+}
+// ─── renderAllProjections ───────────────────────────────────────────────
+/**
+ * Regenerate all projection files for a milestone from DB state.
+ * All calls are wrapped in try/catch — projection failure is non-fatal per D-02.
+ */
+export async function renderAllProjections(basePath, milestoneId) {
+    await renderMilestoneShellProjections(basePath, milestoneId);
     // Query all slices for this milestone
     const sliceRows = getMilestoneSlices(milestoneId);
     for (const slice of sliceRows) {
@@ -428,13 +457,6 @@ export async function renderAllProjections(basePath, milestoneId) {
             }
         }
     }
-    // Render STATE.md
-    try {
-        await renderStateProjection(basePath);
-    }
-    catch (err) {
-        logWarning("projection", `renderStateProjection failed: ${err.message}`);
-    }
 }
 // ─── regenerateIfMissing ────────────────────────────────────────────────
 /**
@@ -447,7 +469,9 @@ export async function regenerateIfMissing(basePath, milestoneId, sliceId, fileTy
     let filePath;
     switch (fileType) {
         case "PLAN":
-            filePath = join(basePath, ".gsd", "milestones", milestoneId, "slices", sliceId, `${sliceId}-PLAN.md`);
+            // Use resolveSliceFile so both flat-phase and legacy layouts are detected.
+            // Falls back to "" (non-existent) when the file hasn't been rendered yet.
+            filePath = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN") ?? "";
             break;
         case "ROADMAP":
             filePath = join(basePath, ".gsd", "milestones", milestoneId, `${milestoneId}-ROADMAP.md`);
@@ -497,7 +521,9 @@ export async function regenerateIfMissing(basePath, milestoneId, sliceId, fileTy
         switch (fileType) {
             case "PLAN":
                 await renderPlanFromDb(basePath, milestoneId, sliceId);
-                return existsSync(filePath);
+                // Re-resolve after render: the rendered file may be at a different path
+                // from the pre-check (flat-phase vs legacy). resolveSliceFile finds it.
+                return !!(resolveSliceFile(basePath, milestoneId, sliceId, "PLAN"));
             case "ROADMAP":
                 await renderRoadmapFromDb(basePath, milestoneId);
                 return existsSync(filePath);

package/dist/resources/extensions/gsd/workspace-git-preflight.js

@@ -4,9 +4,11 @@ import { existsSync, realpathSync } from "node:fs";
 import { getAutoWorktreePath } from "./auto-worktree.js";
 import { isSafeToAutoResolve } from "./auto-worktree.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
-import { probeGitConflictState, reconcileGitConflictsOnSignal, } from "./git-conflict-state.js";
+import { listMergeStateBlockers, probeGitConflictState, reconcileGitConflictsOnSignal, } from "./git-conflict-state.js";
 import { deriveState } from "./state.js";
 import { resolveWorktreeProjectRoot } from "./worktree-root.js";
+const CLEAN_TARGET_CACHE_TTL_MS = 10_000;
+const cleanTargetProbeCache = new Map();
 function normalizeTargetPath(path) {
     try {
         return realpathSync(path);
@@ -77,6 +79,25 @@ function formatBlockReason(severity, conflictedPaths, targets) {
 }
 async function ensureTargetGitReady(target) {
     const fixesApplied = [];
+    const cacheKey = normalizeTargetPath(target);
+    const cachedCleanAt = cleanTargetProbeCache.get(cacheKey);
+    if (cachedCleanAt !== undefined) {
+        if (Date.now() - cachedCleanAt < CLEAN_TARGET_CACHE_TTL_MS) {
+            // Merge-state markers (MERGE_HEAD, rebase-apply, rebase-merge) are the most
+            // common way a repo transitions from clean to dirty within the TTL window,
+            // including when a non-git folder is initialized as a repo mid-TTL and a
+            // merge immediately introduces conflicts. Check them here — they are pure
+            // existsSync calls with no git subprocess — and fall through to a full probe
+            // only when markers are present.
+            if (listMergeStateBlockers(cacheKey).length === 0) {
+                return { ok: true, fixesApplied };
+            }
+            cleanTargetProbeCache.delete(cacheKey);
+        }
+        else {
+            cleanTargetProbeCache.delete(cacheKey);
+        }
+    }
     let probe = probeGitConflictState(target);
     for (let attempt = 0; attempt < 3 && probe.status === "dirty"; attempt++) {
         const beforeKey = JSON.stringify({
@@ -95,6 +116,7 @@ async function ensureTargetGitReady(target) {
             break;
     }
     if (probe.status === "unknown") {
+        cleanTargetProbeCache.delete(cacheKey);
         return {
             ok: false,
             reason: formatBlockReason("unrecoverable", [], [target]),
@@ -106,6 +128,7 @@ async function ensureTargetGitReady(target) {
     }
     const conflictedPaths = productConflictPaths(probe);
     if (conflictedPaths.length > 0 || probe.checkFailures.length > 0) {
+        cleanTargetProbeCache.delete(cacheKey);
         return {
             ok: false,
             reason: formatBlockReason("product-conflicts", conflictedPaths, [target]),
@@ -115,6 +138,12 @@ async function ensureTargetGitReady(target) {
             targets: [target],
         };
     }
+    if (probe.status === "clean") {
+        cleanTargetProbeCache.set(cacheKey, Date.now());
+    }
+    else {
+        cleanTargetProbeCache.delete(cacheKey);
+    }
     return { ok: true, fixesApplied };
 }
 /** Probe and heal a single git root (tests and headless paths). */

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

@@ -1,10 +1,27 @@
 // gsd-pi + Workspace handle: single source of truth for path resolution per milestone
-import { join, resolve } from "node:path";
-import { resolveGsdPathContract, normalizeRealPath } from "./paths.js";
+import { dirname, join, resolve } from "node:path";
+import { buildMilestoneFileName, canonicalPhaseDirName, isLegacyMilestonesLayout, milestonesDir, resolveGsdPathContract, resolveMilestoneFile, resolveMilestonePath, normalizeRealPath, } from "./paths.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
 function tryRealpath(p) {
     return normalizeRealPath(p);
 }
+function isLegacyMilestoneDirectory(dir) {
+    const parent = dirname(dir);
+    return parent.endsWith("/milestones") || parent.endsWith("\\milestones");
+}
+function scopeMilestoneDir(basePath, milestoneId) {
+    return resolveMilestonePath(basePath, milestoneId) ?? join(milestonesDir(basePath), isLegacyMilestonesLayout(basePath) ? milestoneId : canonicalPhaseDirName(milestoneId));
+}
+function scopeMilestoneFile(basePath, milestoneId, suffix) {
+    const existing = resolveMilestoneFile(basePath, milestoneId, suffix);
+    if (existing)
+        return existing;
+    const dir = scopeMilestoneDir(basePath, milestoneId);
+    const filename = isLegacyMilestoneDirectory(dir)
+        ? `${milestoneId}-${suffix}.md`
+        : buildMilestoneFileName(milestoneId, suffix);
+    return join(dir, filename);
+}
 /**
  * Create an immutable GsdWorkspace handle from a raw base path.
  * Resolves both the project root and (when applicable) the worktree root,
@@ -39,21 +56,22 @@ export function createWorkspace(rawBasePath) {
  * Bind a milestoneId to a workspace, producing an immutable MilestoneScope
  * with path-returning closures for DB-authoritative project state.
  *
- * These scope paths intentionally route to contract.projectGsd. In-flight
- * markdown artifact readers outside this scope use the projection-aware
- * resolvers in paths.ts so worktree units can see worktree-local projections.
+ * DB paths route to contract.projectGsd. Milestone artifact paths resolve from
+ * the pinned project root with the layout-aware resolvers, so flat-phase and
+ * legacy projects use the same scope surface.
  */
 export function scopeMilestone(workspace, milestoneId) {
     const { contract } = workspace;
     const gsd = contract.projectGsd;
+    const basePath = workspace.projectRoot;
     const scope = Object.freeze({
         workspace,
         milestoneId,
-        contextFile: () => join(gsd, "milestones", milestoneId, `${milestoneId}-CONTEXT.md`),
-        roadmapFile: () => join(gsd, "milestones", milestoneId, `${milestoneId}-ROADMAP.md`),
+        contextFile: () => scopeMilestoneFile(basePath, milestoneId, "CONTEXT"),
+        roadmapFile: () => scopeMilestoneFile(basePath, milestoneId, "ROADMAP"),
         stateFile: () => join(gsd, "STATE.md"),
         dbPath: () => contract.projectDb,
-        milestoneDir: () => join(gsd, "milestones", milestoneId),
+        milestoneDir: () => scopeMilestoneDir(basePath, milestoneId),
         metaJson: () => join(gsd, `${milestoneId}-META.json`),
     });
     return scope;