gsd-pi 2.80.0 → 2.81.0

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

@@ -16,7 +16,7 @@ import { invalidateAllCaches } from "./cache.js";
 import { startAutoDetached } from "./auto.js";
 import { clearLock } from "./crash-recovery.js";
 import { assessInterruptedSession, formatInterruptedSessionRunningMessage, formatInterruptedSessionSummary, } from "./interrupted-session.js";
-import { listUnitRuntimeRecords, clearUnitRuntimeRecord } from "./unit-runtime.js";
+import { listUnitRuntimeRecords, clearUnitRuntimeRecord, isInFlightRuntimePhase } from "./unit-runtime.js";
 import { resolveExpectedArtifactPath } from "./auto.js";
 import { gsdHome } from "./gsd-home.js";
 import { gsdRoot, milestonesDir, resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile, relMilestoneFile, relSliceFile, clearPathCache, } from "./paths.js";
@@ -45,12 +45,32 @@ import { runPreparation, formatCodebaseBrief, formatPriorContextBrief, } from ".
 import { verifyExpectedArtifact } from "./auto-recovery.js";
 import { createWorkspace, scopeMilestone } from "./workspace.js";
 import { getPendingGate, extractDepthVerificationMilestoneId } from "./bootstrap/write-gate.js";
+export function shouldSkipGitBootstrapAfterInit(result) {
+    return result.gitEnabled === false;
+}
 // ─── Re-exports (preserve public API for existing importers) ────────────────
 export { MILESTONE_ID_RE, generateMilestoneSuffix, nextMilestoneId, extractMilestoneSeq, parseMilestoneId, milestoneIdSort, maxMilestoneNum, findMilestoneIds, reserveMilestoneId, claimReservedId, getReservedMilestoneIds, clearReservedMilestoneIds, } from "./milestone-ids.js";
 export { showQueue, handleQueueReorder, showQueueAdd, buildExistingMilestonesContext, } from "./guided-flow-queue.js";
 import { logWarning } from "./workflow-logger.js";
 import { deleteRuntimeKv } from "./db/runtime-kv.js";
 import { PAUSED_SESSION_KV_KEY } from "./interrupted-session.js";
+import { buildWorkflowDispatchContent } from "./workflow-protocol.js";
+import { isFullGsdToolSurfaceRequested, restoreGsdWorkflowTools, scopeGsdWorkflowToolsForDispatch } from "./bootstrap/register-hooks.js";
+function scheduleAutoStartAfterIdle(ctx, pi, basePath, verboseMode, options, launch = startAutoDetached) {
+    const waitForIdle = typeof ctx.waitForIdle === "function"
+        ? ctx.waitForIdle.bind(ctx)
+        : async () => { };
+    void waitForIdle()
+        .then(() => {
+        setTimeout(() => launch(ctx, pi, basePath, verboseMode, options), 0);
+    })
+        .catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.ui.notify(`Auto-start failed while waiting for the prior turn to settle: ${message}`, "error");
+        logWarning("guided", `auto-start idle wait failed: ${message}`);
+    });
+}
+export const _scheduleAutoStartAfterIdleForTest = scheduleAutoStartAfterIdle;
 // ─── Scope-based validator wrappers ──────────────────────────────────────────
 // These thin wrappers accept a MilestoneScope so callers that already hold a
 // pinned scope never have to re-derive (basePath, milestoneId) separately.
@@ -71,6 +91,19 @@ export function verifyExpectedArtifactForScope(scope, unitType, unitId) {
 export function resolveExpectedArtifactPathForScope(scope, unitType, unitId) {
     return resolveExpectedArtifactPath(unitType, unitId, scope.workspace.projectRoot);
 }
+async function runQuickTaskChoice(ctx, pi) {
+    if (!ctx.hasUI) {
+        ctx.ui.notify("Run /gsd quick <task> for small bounded work, or /gsd do <task> for natural-language routing.", "info");
+        return;
+    }
+    const task = (await ctx.ui.input("Quick task", "Describe the small task to run with /gsd quick"))?.trim();
+    if (!task) {
+        ctx.ui.notify("Quick task cancelled.", "info");
+        return;
+    }
+    const { handleQuick } = await import("./quick.js");
+    await handleQuick(task, ctx, pi);
+}
 /**
  * Scope-based overload of isGhostMilestone.
  * Binds basePath and milestoneId from the scope, ensuring path resolution
@@ -101,6 +134,13 @@ function runPlanV2Gate(ctx, basePath, state) {
     }
     return "pass";
 }
+export const _needsPlanV2GateForTest = needsPlanV2Gate;
+export const _runPlanV2GateForTest = runPlanV2Gate;
+export function _roadmapHasParseableSlicesForTest(roadmapContent) {
+    if (!roadmapContent)
+        return false;
+    return parseRoadmapSlices(roadmapContent).length > 0;
+}
 // ─── Commit Instruction Helpers ──────────────────────────────────────────────
 /** Build commit instruction for planning prompts. .gsd/ is managed externally and always gitignored. */
 function buildDocsCommitInstruction(_message) {
@@ -124,7 +164,7 @@ const USER_DRIVEN_DEEP_SETUP_UNITS = new Set([
     "discuss-requirements",
     "research-decision",
 ]);
-const FOREGROUND_DEEP_SETUP_RULE_NAMES = new Set([
+export const FOREGROUND_DEEP_SETUP_RULE_NAMES = new Set([
     "deep: pre-planning (no workflow prefs) → workflow-preferences",
     "deep: pre-planning (no PROJECT) → discuss-project",
     "deep: pre-planning (no REQUIREMENTS) → discuss-requirements",
@@ -312,7 +352,7 @@ async function dispatchNextDeepProjectSetupStage(entry) {
     const { DISPATCH_RULES, hasPendingDeepStage } = await import("./auto-dispatch.js");
     if (!hasPendingDeepStage(prefs, entry.basePath)) {
         pendingDeepProjectSetupMap.delete(entry.basePath);
-        startAutoDetached(entry.ctx, entry.pi, entry.basePath, false, { step: entry.step });
+        scheduleAutoStartAfterIdle(entry.ctx, entry.pi, entry.basePath, false, { step: entry.step });
         return true;
     }
     const state = await deriveState(entry.basePath);
@@ -346,14 +386,14 @@ async function dispatchNextDeepProjectSetupStage(entry) {
         }
         else if (hasPendingDeepStage(prefs, entry.basePath)) {
             pendingDeepProjectSetupMap.delete(entry.basePath);
-            startAutoDetached(entry.ctx, entry.pi, entry.basePath, false, { step: entry.step });
+            scheduleAutoStartAfterIdle(entry.ctx, entry.pi, entry.basePath, false, { step: entry.step });
             return true;
         }
         return false;
     }
     if (!USER_DRIVEN_DEEP_SETUP_UNITS.has(result.unitType)) {
         pendingDeepProjectSetupMap.delete(entry.basePath);
-        startAutoDetached(entry.ctx, entry.pi, entry.basePath, false, { step: entry.step });
+        scheduleAutoStartAfterIdle(entry.ctx, entry.pi, entry.basePath, false, { step: entry.step });
         return true;
     }
     entry.currentUnitType = result.unitType;
@@ -531,7 +571,7 @@ export function checkAutoStartAfterDiscuss() {
     }
     pendingAutoStartMap.delete(basePath);
     ctx.ui.notify(`Milestone ${milestoneId} ready.`, "success");
-    startAutoDetached(ctx, pi, basePath, false, { step });
+    scheduleAutoStartAfterIdle(ctx, pi, basePath, false, { step });
     return true;
 }
 /**
@@ -817,40 +857,58 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType)
             return;
         }
     }
-    // Scope tools for discuss flows (#2949).
+    // Scope tools for guided workflow turns (#2949, token-consumption savings).
     // Providers with grammar-based constrained decoding (xAI/Grok) return
     // "Grammar is too complex" when the combined tool schema is too large.
-    // Discuss flows only need a small subset of GSD tools — strip the heavy
-    // planning/execution/completion tools to keep the grammar within limits.
+    // Guided workflow turns only need the active unit's tool surface; strip
+    // unrelated GSD tools and broad non-GSD tools for this queued turn, then
+    // restore so the narrowed surface does not leak into future dispatches.
     let savedTools = null;
-    if (unitType?.startsWith("discuss-")) {
+    try {
         const currentTools = pi.getActiveTools();
-        savedTools = currentTools;
-        // Keep all non-GSD tools (builtins, other extensions) and only the
-        // GSD tools on the discuss allowlist.
-        const scopedTools = currentTools.filter((t) => !t.startsWith("gsd_") || DISCUSS_TOOLS_ALLOWLIST.includes(t));
-        pi.setActiveTools(scopedTools);
-        debugLog("discuss-tool-scoping", {
-            unitType,
-            before: currentTools.length,
-            after: scopedTools.length,
-            removed: currentTools.length - scopedTools.length,
-        });
-    }
-    const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(gsdHome(), "agent", "GSD-WORKFLOW.md");
-    const workflow = readFileSync(workflowPath, "utf-8");
-    pi.sendMessage({
-        customType,
-        content: `Read the following GSD workflow protocol and execute exactly.\n\n${workflow}\n\n## Your Task\n\n${note}`,
-        display: false,
-    }, { triggerTurn: true });
-    // Restore full tool set after the message is queued. The LLM turn has
-    // already captured the scoped set — restoring prevents the narrowed
-    // tools from leaking into subsequent dispatches (#3628).
-    if (savedTools) {
-        pi.setActiveTools(savedTools);
+        savedTools = {
+            tools: currentTools,
+            visibleSkills: typeof pi.getVisibleSkills === "function" ? pi.getVisibleSkills() : undefined,
+            restoreVisibleSkills: typeof pi.setVisibleSkills === "function",
+        };
+        if (unitType?.startsWith("discuss-") && !isFullGsdToolSurfaceRequested()) {
+            // Keep all non-GSD tools (builtins, other extensions) and only the
+            // GSD tools on the discuss allowlist.
+            const scopedTools = currentTools.filter((t) => !t.startsWith("gsd_") || DISCUSS_TOOLS_ALLOWLIST.includes(t));
+            pi.setActiveTools(scopedTools);
+            const scopedState = scopeGsdWorkflowToolsForDispatch(pi, unitType);
+            savedTools = {
+                tools: currentTools,
+                visibleSkills: scopedState?.visibleSkills ?? savedTools.visibleSkills,
+                restoreVisibleSkills: scopedState?.restoreVisibleSkills ?? savedTools.restoreVisibleSkills,
+            };
+            debugLog("discuss-tool-scoping", {
+                unitType,
+                before: currentTools.length,
+                after: pi.getActiveTools().length,
+                removed: currentTools.length - pi.getActiveTools().length,
+            });
+        }
+        else {
+            savedTools = scopeGsdWorkflowToolsForDispatch(pi, unitType) ?? savedTools;
+        }
+        const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(gsdHome(), "agent", "GSD-WORKFLOW.md");
+        const workflow = readFileSync(workflowPath, "utf-8");
+        pi.sendMessage({
+            customType,
+            content: buildWorkflowDispatchContent({ workflow, workflowPath, task: note }),
+            display: false,
+        }, { triggerTurn: true });
+    }
+    finally {
+        // Restore full tool set after the message is queued. The LLM turn has
+        // already captured the scoped set — restoring prevents the narrowed
+        // tools from leaking into subsequent dispatches (#3628). The finally
+        // block ensures restoration even if sendMessage throws.
+        restoreGsdWorkflowTools(pi, savedTools);
     }
 }
+export const _dispatchWorkflowForTest = dispatchWorkflow;
 function getStructuredQuestionsAvailability(pi, ctx) {
     if (!ctx)
         return "false";
@@ -1469,8 +1527,8 @@ function selfHealRuntimeRecords(basePath, ctx) {
                 cleared++;
                 continue;
             }
-            // Clear records stuck in dispatched or timeout phase (process died mid-unit)
-            if (phase === "dispatched" || phase === "timeout") {
+            // Clear records stuck in an in-flight phase (process died mid-unit).
+            if (isInFlightRuntimePhase(phase)) {
                 clearUnitRuntimeRecord(basePath, unitType, unitId);
                 cleared++;
             }
@@ -1619,7 +1677,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
         const result = await showProjectInit(ctx, pi, basePath, detection);
         if (!result.completed)
             return; // User cancelled
-        skipGitBootstrap = result.gitEnabled === false;
+        skipGitBootstrap = shouldSkipGitBootstrapAfterInit(result);
         // Init wizard bootstrapped .gsd/ — fall through to the normal flow below
         // which will detect "no milestones" and start the discuss prompt
     }
@@ -1695,6 +1753,20 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             return;
         }
     }
+    if (interrupted.classification !== "recoverable") {
+        try {
+            const { autoImportMarkdownHierarchyIfDbMismatch } = await import("./migration-auto-check.js");
+            const result = await autoImportMarkdownHierarchyIfDbMismatch(basePath);
+            if (result.action === "imported") {
+                ctx.ui.notify(`Recovered migrated planning state into gsd.db (${result.reason}): ${result.afterDb.milestones} milestone(s), ${result.afterDb.slices} slice(s), ${result.afterDb.tasks} task(s).`, "info");
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            ctx.ui.notify(`GSD could not auto-import existing planning state into gsd.db: ${message}`, "warning");
+            logWarning("guided", `planning state auto-import failed: ${message}`, { file: "guided-flow.ts" });
+        }
+    }
     // Always derive from the project root — the assessment may have derived
     // state from a worktree path that was cleaned up in the stale branch above.
     const state = await deriveState(basePath);
@@ -1716,8 +1788,8 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
     // standard wizard below.
     {
         const prefs = loadEffectiveGSDPreferences(basePath)?.preferences;
-        const { hasPendingDeepStage } = await import("./auto-dispatch.js");
-        if (hasPendingDeepStage(prefs, basePath)) {
+        const { shouldRunDeepProjectSetup } = await import("./auto-dispatch.js");
+        if (shouldRunDeepProjectSetup(state, prefs, basePath)) {
             await startDeepProjectSetupForeground(ctx, pi, basePath, stepMode);
             return;
         }
@@ -1772,6 +1844,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
         const isFirst = milestoneIds.length === 0;
         if (isFirst) {
             // First ever — skip wizard, just ask directly
+            ctx.ui.setStatus("gsd-step", "New Milestone · answer the questions above to plan");
             setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
             await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New project, milestone ${nextId}. Do NOT read or explore .gsd/ — it's empty scaffolding.`, basePath), "gsd-run", ctx, "discuss-milestone");
         }
@@ -1780,16 +1853,25 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
                 title: "GSD — Get Shit Done",
                 summary: ["No active milestone."],
                 actions: [
+                    {
+                        id: "quick_task",
+                        label: "Quick task",
+                        description: "For small bounded work, run /gsd quick <task> or /gsd do <task>.",
+                        recommended: true,
+                    },
                     {
                         id: "new_milestone",
                         label: "Create next milestone",
-                        description: "Define what to build next.",
-                        recommended: true,
+                        description: "Define a larger body of work with planning artifacts.",
                     },
                 ],
                 notYetMessage: "Run /gsd when ready.",
             });
-            if (choice === "new_milestone") {
+            if (choice === "quick_task") {
+                await runQuickTaskChoice(ctx, pi);
+            }
+            else if (choice === "new_milestone") {
+                ctx.ui.setStatus("gsd-step", "New Milestone · answer the questions above to plan");
                 setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
                 await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
             }
@@ -1809,11 +1891,16 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             title: `GSD — ${milestoneId}: ${milestoneTitle}`,
             summary: ["All milestones complete."],
             actions: [
+                {
+                    id: "quick_task",
+                    label: "Quick task",
+                    description: "Do a small bounded task without opening a milestone.",
+                    recommended: true,
+                },
                 {
                     id: "new_milestone",
                     label: "Start new milestone",
                     description: "Define and plan the next milestone.",
-                    recommended: true,
                 },
                 {
                     id: "status",
@@ -1823,7 +1910,10 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             ],
             notYetMessage: "Run /gsd when ready.",
         });
-        if (choice === "new_milestone") {
+        if (choice === "quick_task") {
+            await runQuickTaskChoice(ctx, pi);
+        }
+        else if (choice === "new_milestone") {
             const milestoneIds = findMilestoneIds(basePath);
             const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
             const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds, basePath);
@@ -1907,8 +1997,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
         if (hasRoadmap) {
             const roadmapContent = await loadFile(roadmapFile);
             if (roadmapContent) {
-                const parsed = parseRoadmapSlices(roadmapContent);
-                roadmapHasSlices = parsed.length > 0;
+                roadmapHasSlices = _roadmapHasParseableSlicesForTest(roadmapContent);
             }
         }
         if (!hasRoadmap || !roadmapHasSlices) {
@@ -1916,13 +2005,18 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             const contextFile = resolveMilestoneFile(basePath, milestoneId, "CONTEXT");
             const hasContext = !!(contextFile && await loadFile(contextFile));
             const actions = [
+                {
+                    id: "quick_task",
+                    label: "Quick task instead",
+                    description: "Use this when the work is small and should not become a milestone.",
+                    recommended: true,
+                },
                 {
                     id: "plan",
                     label: "Create roadmap",
                     description: hasContext
                         ? "Context captured. Decompose into slices with a boundary map."
                         : "Decompose the milestone into slices with a boundary map.",
-                    recommended: true,
                 },
                 ...(!hasContext ? [{
                         id: "discuss",
@@ -1946,7 +2040,11 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
                 actions,
                 notYetMessage: "Run /gsd when ready.",
             });
-            if (choice === "plan") {
+            if (choice === "quick_task") {
+                await runQuickTaskChoice(ctx, pi);
+            }
+            else if (choice === "plan") {
+                ctx.ui.setStatus("gsd-step", "Planning Milestone · decomposing into slices");
                 setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId, step: stepMode });
                 await dispatchWorkflow(pi, await buildPlanMilestonePrompt(milestoneId, milestoneTitle, basePath), "gsd-run", ctx, "plan-milestone");
             }
@@ -2071,6 +2169,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             notYetMessage: "Run /gsd when ready.",
         });
         if (choice === "plan") {
+            ctx.ui.setStatus("gsd-step", "Slice Planning · answer the questions above");
             await dispatchWorkflow(pi, await buildPlanSlicePrompt(milestoneId, milestoneTitle, sliceId, sliceTitle, basePath), "gsd-run", ctx, "plan-slice");
         }
         else if (choice === "discuss") {
@@ -2130,6 +2229,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             notYetMessage: "Run /gsd when ready.",
         });
         if (choice === "complete") {
+            ctx.ui.setStatus("gsd-step", "Completing Slice · review changes above");
             await dispatchWorkflow(pi, await buildCompleteSlicePrompt(milestoneId, milestoneTitle, sliceId, sliceTitle, basePath), "gsd-run", ctx, "complete-slice");
         }
         else if (choice === "status") {
@@ -2190,6 +2290,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             return;
         }
         if (choice === "execute") {
+            ctx.ui.setStatus("gsd-step", "Executing Task · follow progress above");
             if (hasInterrupted) {
                 await dispatchWorkflow(pi, loadPrompt("guided-resume-task", {
                     milestoneId,

package/dist/resources/extensions/gsd/health-widget.js

@@ -118,6 +118,9 @@ export function initHealthWidget(ctx) {
             render(width) {
                 if (!cachedLines || cachedWidth !== width) {
                     cachedLines = buildHealthLines(data, width);
+                    if (data.projectState === "active") {
+                        cachedLines = [...cachedLines, _theme.fg("dim", "  /gsd auto to run  ·  /gsd status for overview  ·  /gsd help")];
+                    }
                     cachedWidth = width;
                 }
                 return cachedLines;

package/dist/resources/extensions/gsd/init-wizard.js

@@ -15,6 +15,9 @@ import { assertSafeDirectory } from "./validate-directory.js";
 import { runSkillInstallStep } from "./skill-catalog.js";
 import { generateCodebaseMap, writeCodebaseMap } from "./codebase-generator.js";
 import { handlePrefsWizard, writePreferencesFile } from "./commands-prefs-wizard.js";
+export function shouldWriteGitFiles(gitEnabled) {
+    return gitEnabled;
+}
 // ─── Defaults ───────────────────────────────────────────────────────────────────
 const DEFAULT_PREFS = {
     mode: "solo",
@@ -247,7 +250,7 @@ export async function showProjectInit(ctx, pi, basePath, detection) {
     }
     // Ensure .gitignore only when git is active. A user who selected "Skip"
     // should not have git initialized or git-related files mutated later.
-    if (gitEnabled) {
+    if (shouldWriteGitFiles(gitEnabled)) {
         ensureGitignore(basePath);
         untrackRuntimeFiles(basePath);
     }

package/dist/resources/extensions/gsd/legacy-telemetry.js

@@ -0,0 +1,70 @@
+// Project/App: GSD-2
+// File Purpose: Runtime counters for telemetry-gated legacy compatibility paths.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { logWarning } from "./workflow-logger.js";
+const COUNTERS = [
+    "legacy.markdownFallbackUsed",
+    "legacy.workflowEngineUsed",
+    "legacy.uokFallbackUsed",
+    "legacy.mcpAliasUsed",
+    "legacy.componentFormatUsed",
+    "legacy.providerDefaultUsed",
+];
+const values = Object.fromEntries(COUNTERS.map((counter) => [counter, 0]));
+const warnedCounters = new Set();
+const DIAGNOSTICS = {
+    "legacy.markdownFallbackUsed": "Deprecated markdown state fallback used; migrate projects to DB-authoritative state before removing markdown derivation.",
+    "legacy.workflowEngineUsed": "Deprecated workflow engine path used; prefer auto-milestone workflow templates before removing legacy engines.",
+    "legacy.uokFallbackUsed": "Deprecated UOK fallback path used; resolve UOK kernel blockers before removing parity fallback wrappers.",
+    "legacy.mcpAliasUsed": "Deprecated MCP alias tool used; update callers to the canonical gsd_* tool name before alias removal.",
+    "legacy.componentFormatUsed": "Deprecated component format loaded; migrate skills/agents to component.yaml before removing legacy loaders.",
+    "legacy.providerDefaultUsed": "Provider-specific default fallback used without an explicit available model; configure provider-aware model preferences before removing defaults.",
+};
+process.once("beforeExit", persistLegacyTelemetry);
+export function incrementLegacyTelemetry(counter, amount = 1) {
+    if (!Number.isFinite(amount) || amount <= 0)
+        return;
+    values[counter] += amount;
+    emitLegacyDiagnostic(counter);
+    persistLegacyTelemetry();
+}
+export function getLegacyTelemetry() {
+    return { ...values };
+}
+export function resetLegacyTelemetry() {
+    for (const counter of COUNTERS) {
+        values[counter] = 0;
+    }
+    warnedCounters.clear();
+}
+export function listLegacyTelemetryCounters() {
+    return [...COUNTERS];
+}
+export function getLegacyTelemetryReport() {
+    return {
+        ts: new Date().toISOString(),
+        counters: getLegacyTelemetry(),
+    };
+}
+export function persistLegacyTelemetrySnapshot() {
+    persistLegacyTelemetry();
+}
+function emitLegacyDiagnostic(counter) {
+    if (warnedCounters.has(counter))
+        return;
+    warnedCounters.add(counter);
+    logWarning("migration", DIAGNOSTICS[counter], { counter });
+}
+function persistLegacyTelemetry() {
+    const outputPath = process.env.GSD_LEGACY_TELEMETRY_FILE?.trim();
+    if (!outputPath)
+        return;
+    try {
+        mkdirSync(dirname(outputPath), { recursive: true });
+        writeFileSync(outputPath, `${JSON.stringify(getLegacyTelemetryReport(), null, 2)}\n`, "utf-8");
+    }
+    catch {
+        // Legacy cleanup telemetry must never block runtime paths.
+    }
+}

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

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Markdown projection renderer for GSD workflow database rows.
 // GSD Markdown Renderer — DB → Markdown file generation
 //
 // Transforms DB state into correct markdown files on disk.

package/dist/resources/extensions/gsd/memory-store.js

@@ -14,6 +14,27 @@ const CATEGORY_PRIORITY = {
     environment: 4,
     preference: 5,
 };
+// ─── Scoring Helpers ─────────────────────────────────────────────────────────
+/**
+ * Time-decay factor for memory relevance scoring.
+ * Returns 1.0 for never-hit or recently-hit memories, decaying linearly to
+ * 0.7 for memories not accessed in 90+ days. Floor at 0.7 keeps old-but-valid
+ * knowledge from being fully suppressed.
+ *
+ * Defensive parsing: invalid timestamp strings (NaN from Date.parse) are
+ * treated as "no decay" rather than propagating NaN into score arithmetic.
+ * Future timestamps (clock skew, manual DB edits) clamp to daysAgo=0 so the
+ * factor stays in the documented [0.7, 1.0] contract.
+ */
+export function memoryDecayFactor(lastHitAt) {
+    if (!lastHitAt)
+        return 1.0;
+    const ts = Date.parse(lastHitAt);
+    if (!Number.isFinite(ts))
+        return 1.0;
+    const daysAgo = Math.max(0, (Date.now() - ts) / 86_400_000);
+    return Math.max(0.7, 1.0 - 0.3 * Math.min(1.0, daysAgo / 90));
+}
 // ─── Row Mapping ────────────────────────────────────────────────────────────
 function rowToMemory(row) {
     return {
@@ -31,6 +52,7 @@ function rowToMemory(row) {
         scope: row['scope'] ?? 'project',
         tags: parseTags(row['tags']),
         structured_fields: parseStructuredFields(row['structured_fields']),
+        last_hit_at: row['last_hit_at'] ?? null,
     };
 }
 function parseStructuredFields(raw) {
@@ -114,15 +136,37 @@ export function queryMemoriesRanked(opts) {
         ? semanticSearch(adapter, opts.queryVector, activeClause, 50)
         : [];
     if (keywordHits.length === 0 && semanticHits.length === 0 && !trimmedQuery) {
-        // No query at all — fall back to the existing ranked-by-score listing.
-        return getActiveMemoriesRanked(k).map((memory) => ({
-            memory,
-            score: memory.confidence * (1 + memory.hit_count * 0.1),
-            keywordRank: null,
-            semanticRank: null,
-            confidenceBoost: memory.confidence * (1 + memory.hit_count * 0.1),
-            reason: 'ranked',
-        })).filter((hit) => passesFilters(hit.memory, opts));
+        // No query at all — return top-k by decay-aware ranked score.
+        //
+        // Build the candidate pool from a direct SQL query that honors the
+        // request's activeClause (i.e. include_superseded). Using
+        // getActiveMemoriesRanked here would silently drop superseded rows even
+        // when the caller explicitly opted in, and would slice by raw score
+        // before decay/filters had a chance to reorder.
+        const candidatePool = Math.min(Math.max(k * 5, 50), 500);
+        const rows = adapter
+            .prepare(`SELECT * FROM memories ${activeClause}
+         ORDER BY (confidence * (1.0 + hit_count * 0.1)) DESC
+         LIMIT :limit`)
+            .all({ ':limit': candidatePool });
+        const ranked = [];
+        for (const row of rows) {
+            const memory = rowToMemory(row);
+            if (!passesFilters(memory, opts))
+                continue;
+            const decay = memoryDecayFactor(memory.last_hit_at);
+            const score = memory.confidence * (1 + memory.hit_count * 0.1) * decay;
+            ranked.push({
+                memory,
+                score,
+                keywordRank: null,
+                semanticRank: null,
+                confidenceBoost: score,
+                reason: 'ranked',
+            });
+        }
+        ranked.sort((a, b) => b.score - a.score);
+        return ranked.slice(0, k);
     }
     // 3) Reciprocal rank fusion — each hit contributes 1/(rrfK + rank).
     const fused = new Map();
@@ -155,7 +199,7 @@ export function queryMemoriesRanked(opts) {
     for (const entry of fused.values()) {
         if (!passesFilters(entry.memory, opts))
             continue;
-        const boost = entry.memory.confidence * (1 + entry.memory.hit_count * 0.1);
+        const boost = entry.memory.confidence * (1 + entry.memory.hit_count * 0.1) * memoryDecayFactor(entry.memory.last_hit_at);
         const reason = entry.kwRank != null && entry.semRank != null
             ? 'both'
             : entry.kwRank != null
@@ -194,6 +238,7 @@ function passesFilters(memory, filters) {
     }
     return true;
 }
+let ftsWarningEmitted = false;
 function keywordSearch(adapter, rawQuery, activeClause, limit) {
     const ftsAvailable = isFtsAvailable(adapter);
     if (ftsAvailable) {
@@ -215,14 +260,26 @@ function keywordSearch(adapter, rawQuery, activeClause, limit) {
             // fall through to LIKE
         }
     }
-    // LIKE fallback — scans the candidate pool.
+    // LIKE fallback — scans a capped candidate pool.
+    if (!ftsWarningEmitted) {
+        ftsWarningEmitted = true;
+        logWarning('memory-store', 'FTS5 unavailable — using LIKE fallback scan (consider enabling FTS5)');
+    }
     const terms = rawQuery
         .toLowerCase()
         .split(/[^a-z0-9_]+/)
         .filter((t) => t.length >= 2);
     if (terms.length === 0)
         return [];
-    const rows = adapter.prepare(`SELECT * FROM memories ${activeClause}`).all();
+    const preScanCap = Math.min(limit * 20, 2000);
+    // ORDER BY confidence-weighted hit_count DESC so the cap keeps the most
+    // valuable candidates instead of the oldest-by-rowid (which would silently
+    // exclude recently-stored memories on tables larger than preScanCap).
+    const rows = adapter
+        .prepare(`SELECT * FROM memories ${activeClause}
+       ORDER BY (confidence * (1.0 + hit_count * 0.1)) DESC
+       LIMIT :preScanCap`)
+        .all({ ':preScanCap': preScanCap });
     const scored = [];
     for (const row of rows) {
         const memory = rowToMemory(row);