gsd-pi 2.80.0 → 2.81.0

package/src/resources/extensions/gsd/guided-flow.ts

@@ -30,7 +30,7 @@ import {
   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 {
@@ -72,6 +72,10 @@ import { verifyExpectedArtifact } from "./auto-recovery.js";
 import { createWorkspace, scopeMilestone, type MilestoneScope } from "./workspace.js";
 import { getPendingGate, extractDepthVerificationMilestoneId } from "./bootstrap/write-gate.js";
 
+export function shouldSkipGitBootstrapAfterInit(result: { gitEnabled?: boolean }): boolean {
+  return result.gitEnabled === false;
+}
+
 // ─── Re-exports (preserve public API for existing importers) ────────────────
 export {
   MILESTONE_ID_RE, generateMilestoneSuffix, nextMilestoneId,
@@ -86,6 +90,36 @@ export {
 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";
+
+type AutoStartOptions = Parameters<typeof startAutoDetached>[4];
+type AutoStartLauncher = typeof startAutoDetached;
+
+function scheduleAutoStartAfterIdle(
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+  basePath: string,
+  verboseMode: boolean,
+  options?: AutoStartOptions,
+  launch: AutoStartLauncher = startAutoDetached,
+): void {
+  const waitForIdle =
+    typeof (ctx as { waitForIdle?: unknown }).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
@@ -118,6 +152,22 @@ export function resolveExpectedArtifactPathForScope(
   return resolveExpectedArtifactPath(unitType, unitId, scope.workspace.projectRoot);
 }
 
+async function runQuickTaskChoice(ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
+  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
@@ -159,6 +209,16 @@ function runPlanV2Gate(
   return "pass";
 }
 
+export const _needsPlanV2GateForTest = needsPlanV2Gate;
+export const _runPlanV2GateForTest = runPlanV2Gate;
+
+export function _roadmapHasParseableSlicesForTest(
+  roadmapContent: string | null | undefined,
+): boolean {
+  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. */
@@ -220,7 +280,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",
@@ -430,7 +490,7 @@ async function dispatchNextDeepProjectSetupStage(entry: PendingDeepProjectSetupE
 
   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;
   }
 
@@ -463,7 +523,7 @@ async function dispatchNextDeepProjectSetupStage(entry: PendingDeepProjectSetupE
       entry.ctx.ui.notify(result.reason, result.level);
     } 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;
@@ -471,7 +531,7 @@ async function dispatchNextDeepProjectSetupStage(entry: PendingDeepProjectSetupE
 
   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;
   }
 
@@ -677,7 +737,7 @@ export function checkAutoStartAfterDiscuss(): boolean {
 
   pendingAutoStartMap.delete(basePath);
   ctx.ui.notify(`Milestone ${milestoneId} ready.`, "success");
-  startAutoDetached(ctx, pi, basePath, false, { step });
+  scheduleAutoStartAfterIdle(ctx, pi, basePath, false, { step });
   return true;
 }
 
@@ -1018,49 +1078,66 @@ async function dispatchWorkflow(
     }
   }
 
-  // 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.
-  let savedTools: string[] | null = null;
-  if (unitType?.startsWith("discuss-")) {
-    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,
-    });
-  }
+  // 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: ReturnType<typeof scopeGsdWorkflowToolsForDispatch> = null;
 
-  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(gsdHome(), "agent", "GSD-WORKFLOW.md");
-  const workflow = readFileSync(workflowPath, "utf-8");
+  try {
+    const currentTools = pi.getActiveTools();
+    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;
+    }
 
-  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 },
-  );
+    const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(gsdHome(), "agent", "GSD-WORKFLOW.md");
+    const workflow = readFileSync(workflowPath, "utf-8");
 
-  // 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);
+    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: ExtensionAPI,
   ctx: ExtensionContext | undefined,
@@ -1786,8 +1863,8 @@ function selfHealRuntimeRecords(basePath: string, ctx: ExtensionContext): { clea
         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++;
       }
@@ -1961,7 +2038,7 @@ export async function showSmartEntry(
     // No .gsd/ or zombie .gsd/ — run the project init wizard
     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
@@ -2042,6 +2119,23 @@ export async function showSmartEntry(
     }
   }
 
+  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);
@@ -2064,8 +2158,8 @@ export async function showSmartEntry(
   // 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;
     }
@@ -2124,6 +2218,7 @@ export async function showSmartEntry(
 
     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.`,
@@ -2134,17 +2229,25 @@ export async function showSmartEntry(
         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}.`,
@@ -2181,11 +2284,16 @@ export async function showSmartEntry(
       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",
@@ -2196,7 +2304,9 @@ export async function showSmartEntry(
       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);
@@ -2289,8 +2399,7 @@ export async function showSmartEntry(
     if (hasRoadmap) {
       const roadmapContent = await loadFile(roadmapFile!);
       if (roadmapContent) {
-        const parsed = parseRoadmapSlices(roadmapContent);
-        roadmapHasSlices = parsed.length > 0;
+        roadmapHasSlices = _roadmapHasParseableSlicesForTest(roadmapContent);
       }
     }
 
@@ -2300,13 +2409,18 @@ export async function showSmartEntry(
       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",
@@ -2332,7 +2446,10 @@ export async function showSmartEntry(
         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,
@@ -2465,6 +2582,7 @@ export async function showSmartEntry(
     });
 
     if (choice === "plan") {
+      ctx.ui.setStatus("gsd-step", "Slice Planning · answer the questions above");
       await dispatchWorkflow(
         pi,
         await buildPlanSlicePrompt(milestoneId, milestoneTitle, sliceId, sliceTitle, basePath),
@@ -2527,6 +2645,7 @@ export async function showSmartEntry(
     });
 
     if (choice === "complete") {
+      ctx.ui.setStatus("gsd-step", "Completing Slice · review changes above");
       await dispatchWorkflow(
         pi,
         await buildCompleteSlicePrompt(milestoneId, milestoneTitle, sliceId, sliceTitle, basePath),
@@ -2595,6 +2714,7 @@ export async function showSmartEntry(
     }
 
     if (choice === "execute") {
+      ctx.ui.setStatus("gsd-step", "Executing Task · follow progress above");
       if (hasInterrupted) {
         await dispatchWorkflow(pi, loadPrompt("guided-resume-task", {
           milestoneId,

package/src/resources/extensions/gsd/health-widget.ts

@@ -135,6 +135,9 @@ export function initHealthWidget(ctx: ExtensionContext): void {
       render(width: number): string[] {
         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/src/resources/extensions/gsd/init-wizard.ts

@@ -30,6 +30,10 @@ interface InitWizardResult {
   gitEnabled?: boolean;
 }
 
+export function shouldWriteGitFiles(gitEnabled: boolean): boolean {
+  return gitEnabled;
+}
+
 interface ProjectPreferences {
   mode: "solo" | "team";
   gitIsolation: "worktree" | "branch" | "none";
@@ -299,7 +303,7 @@ export async function showProjectInit(
 
   // 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/src/resources/extensions/gsd/legacy-telemetry.ts

@@ -0,0 +1,99 @@
+// 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";
+
+export type LegacyTelemetryCounter =
+  | "legacy.markdownFallbackUsed"
+  | "legacy.workflowEngineUsed"
+  | "legacy.uokFallbackUsed"
+  | "legacy.mcpAliasUsed"
+  | "legacy.componentFormatUsed"
+  | "legacy.providerDefaultUsed";
+
+export type LegacyTelemetrySnapshot = Record<LegacyTelemetryCounter, number>;
+
+export interface LegacyTelemetryReport {
+  ts: string;
+  counters: LegacyTelemetrySnapshot;
+}
+
+const COUNTERS: LegacyTelemetryCounter[] = [
+  "legacy.markdownFallbackUsed",
+  "legacy.workflowEngineUsed",
+  "legacy.uokFallbackUsed",
+  "legacy.mcpAliasUsed",
+  "legacy.componentFormatUsed",
+  "legacy.providerDefaultUsed",
+];
+
+const values: LegacyTelemetrySnapshot = Object.fromEntries(
+  COUNTERS.map((counter) => [counter, 0]),
+) as LegacyTelemetrySnapshot;
+
+const warnedCounters = new Set<LegacyTelemetryCounter>();
+
+const DIAGNOSTICS: Record<LegacyTelemetryCounter, string> = {
+  "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: LegacyTelemetryCounter, amount = 1): void {
+  if (!Number.isFinite(amount) || amount <= 0) return;
+  values[counter] += amount;
+  emitLegacyDiagnostic(counter);
+  persistLegacyTelemetry();
+}
+
+export function getLegacyTelemetry(): LegacyTelemetrySnapshot {
+  return { ...values };
+}
+
+export function resetLegacyTelemetry(): void {
+  for (const counter of COUNTERS) {
+    values[counter] = 0;
+  }
+  warnedCounters.clear();
+}
+
+export function listLegacyTelemetryCounters(): LegacyTelemetryCounter[] {
+  return [...COUNTERS];
+}
+
+export function getLegacyTelemetryReport(): LegacyTelemetryReport {
+  return {
+    ts: new Date().toISOString(),
+    counters: getLegacyTelemetry(),
+  };
+}
+
+export function persistLegacyTelemetrySnapshot(): void {
+  persistLegacyTelemetry();
+}
+
+function emitLegacyDiagnostic(counter: LegacyTelemetryCounter): void {
+  if (warnedCounters.has(counter)) return;
+  warnedCounters.add(counter);
+  logWarning("migration", DIAGNOSTICS[counter], { counter });
+}
+
+function persistLegacyTelemetry(): void {
+  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/src/resources/extensions/gsd/markdown-renderer.ts

@@ -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.
@@ -23,7 +25,8 @@ import {
   insertArtifact,
   getGateResults,
 } from "./gsd-db.js";
-import type { MilestoneRow, SliceRow, TaskRow, ArtifactRow } from "./gsd-db.js";
+import type { MilestoneRow, ArtifactRow } from "./db-milestone-artifact-rows.js";
+import type { SliceRow, TaskRow } from "./db-task-slice-rows.js";
 import type { GateRow } from "./types.js";
 import {
   resolveMilestoneFile,