gsd-pi 2.79.0-dev.ece5fd8ba → 2.80.0-dev.c5f2443b3

package/src/resources/extensions/gsd/tests/guided-discuss-milestone-prompt-rendering.test.ts

@@ -0,0 +1,43 @@
+// Project/App: GSD-2
+// File Purpose: Verifies the guided milestone discussion prompt renders its core interview and persistence contracts.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+test("guided milestone prompt renders compact interview and context guidance", async (t) => {
+  const previousGsdHome = process.env.GSD_HOME;
+  const providedGsdHome = process.env.GSD_TEST_HOME;
+  const isolatedHome = providedGsdHome ?? mkdtempSync(join(tmpdir(), "gsd-guided-milestone-render-"));
+  process.env.GSD_HOME = isolatedHome;
+  t.after(() => {
+    if (previousGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = previousGsdHome;
+    if (!providedGsdHome) rmSync(isolatedHome, { recursive: true, force: true });
+  });
+
+  const { loadPrompt } = await import(`../prompt-loader.ts?test=${Date.now()}`);
+  const prompt = loadPrompt("guided-discuss-milestone", {
+    workingDirectory: process.env.GSD_TEST_WORKSPACE_ROOT ?? process.cwd(),
+    milestoneId: "M001",
+    milestoneTitle: "Baseline And Safety",
+    structuredQuestionsAvailable: "true",
+    fastPathInstruction: "No fast path in this test.",
+    inlinedTemplates: "## Context\n\n## Decisions\n\n## Open Questions",
+    commitInstruction: "Do not commit during this test.",
+  });
+
+  assert.match(prompt, /M001 context written/);
+  assert.match(prompt, /Project Shape/);
+  assert.match(prompt, /default to `complex`/i);
+  assert.match(prompt, /3 or 4 concrete, researched options/);
+  assert.match(prompt, /"Other — let me discuss"/);
+  assert.match(prompt, /CONTEXT-DRAFT/);
+  assert.match(prompt, /Do NOT mention this save to the user/);
+  assert.match(prompt, /depth_verification_M001_confirm/);
+  assert.match(prompt, /artifact_type: "CONTEXT"/);
+  assert.match(prompt, /milestone_id: M001/);
+  assert.doesNotMatch(prompt, /\{\{[a-zA-Z][a-zA-Z0-9_]*\}\}/);
+});

package/src/resources/extensions/gsd/tests/guided-discuss-project-prompt-rendering.test.ts

@@ -0,0 +1,41 @@
+// Project/App: GSD-2
+// File Purpose: Verifies the guided project discussion prompt renders its core interview and persistence contracts.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+test("guided project prompt renders compact interview and artifact guidance", async (t) => {
+  const previousGsdHome = process.env.GSD_HOME;
+  const providedGsdHome = process.env.GSD_TEST_HOME;
+  const isolatedHome = providedGsdHome ?? mkdtempSync(join(tmpdir(), "gsd-guided-project-render-"));
+  process.env.GSD_HOME = isolatedHome;
+  t.after(() => {
+    if (previousGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = previousGsdHome;
+    if (!providedGsdHome) rmSync(isolatedHome, { recursive: true, force: true });
+  });
+
+  const { loadPrompt } = await import(`../prompt-loader.ts?test=${Date.now()}`);
+  const prompt = loadPrompt("guided-discuss-project", {
+    workingDirectory: process.env.GSD_TEST_WORKSPACE_ROOT ?? process.cwd(),
+    structuredQuestionsAvailable: "true",
+    inlinedTemplates: "## Project\n\n## Project Shape\n\n## Capability Contract\n\n## Milestone Sequence",
+    commitInstruction: "Do not commit during this test.",
+  });
+
+  assert.match(prompt, /What do you want to build\?/);
+  assert.match(prompt, /Project shape: simple/);
+  assert.match(prompt, /Default to `complex` when uncertain/);
+  assert.match(prompt, /3 or 4 concrete, researched options/);
+  assert.match(prompt, /"Other — let me discuss"/);
+  assert.match(prompt, /depth_verification_project_confirm/);
+  assert.match(prompt, /artifact_type: "PROJECT"/);
+  assert.match(prompt, /omit `milestone_id`/);
+  assert.match(prompt, /Do NOT use `artifact_type: "CONTEXT"` and do NOT pass `milestone_id: "PROJECT"`/);
+  assert.match(prompt, /\*\*Complexity:\*\* simple/);
+  assert.match(prompt, /\*\*Complexity:\*\* complex/);
+  assert.doesNotMatch(prompt, /\{\{[a-zA-Z][a-zA-Z0-9_]*\}\}/);
+});

package/src/resources/extensions/gsd/tests/guided-discuss-requirements-prompt-rendering.test.ts

@@ -0,0 +1,45 @@
+// Project/App: GSD-2
+// File Purpose: Verifies the guided requirements discussion prompt renders core requirements and persistence contracts.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+test("guided requirements prompt renders compact capability and persistence guidance", async (t) => {
+  const previousGsdHome = process.env.GSD_HOME;
+  const providedGsdHome = process.env.GSD_TEST_HOME;
+  const isolatedHome = providedGsdHome ?? mkdtempSync(join(tmpdir(), "gsd-guided-requirements-render-"));
+  process.env.GSD_HOME = isolatedHome;
+  t.after(() => {
+    if (previousGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = previousGsdHome;
+    if (!providedGsdHome) rmSync(isolatedHome, { recursive: true, force: true });
+  });
+
+  const { loadPrompt } = await import(`../prompt-loader.ts?test=${Date.now()}`);
+  const prompt = loadPrompt("guided-discuss-requirements", {
+    workingDirectory: process.env.GSD_TEST_WORKSPACE_ROOT ?? process.cwd(),
+    structuredQuestionsAvailable: "true",
+    inlinedTemplates: "## Active\n\n## Validated\n\n## Deferred\n\n## Out of Scope\n\n## Traceability\n\n## Coverage Summary",
+    commitInstruction: "Do not commit during this test.",
+  });
+
+  assert.match(prompt, /PROJECT\.md missing/);
+  assert.match(prompt, /Project Shape/);
+  assert.match(prompt, /R###/);
+  assert.match(prompt, /M###\/none yet/);
+  assert.match(prompt, /never bare `none yet`/);
+  assert.match(prompt, /3 or 4 concrete, researched options/);
+  assert.match(prompt, /"Other — let me discuss"/);
+  assert.match(prompt, /class-assignment and status questions are exempt/);
+  assert.match(prompt, /artifact_type: "REQUIREMENTS-DRAFT"/);
+  assert.match(prompt, /depth_verification_requirements_confirm/);
+  assert.match(prompt, /gsd_requirement_save/);
+  assert.match(prompt, /gsd_summary_save/);
+  assert.match(prompt, /artifact_type: "REQUIREMENTS"/);
+  assert.match(prompt, /Do NOT use `artifact_type: "CONTEXT"`/);
+  assert.match(prompt, /Requirements written\./);
+  assert.doesNotMatch(prompt, /\{\{[a-zA-Z][a-zA-Z0-9_]*\}\}/);
+});

package/src/resources/extensions/gsd/tests/integration/auto-recovery.test.ts

@@ -1,3 +1,5 @@
+// GSD Extension — Auto recovery integration tests.
+
 import test from "node:test";
 import assert from "node:assert/strict";
 import { mkdirSync, writeFileSync, existsSync, readFileSync, rmSync, chmodSync } from "node:fs";
@@ -401,6 +403,57 @@ test("verifyExpectedArtifact plan-slice fails for plan with no tasks (#699)", (t
   assert.equal(result, false, "should fail when plan has no task entries (empty scaffold, #699)");
 });
 
+test("verifyExpectedArtifact plan-slice trusts DB tasks over legacy plan syntax", (t) => {
+  const base = makeTmpBase();
+  t.after(() => {
+    closeDatabase();
+    cleanup(base);
+  });
+
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Milestone", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Slice", status: "pending" });
+  insertTask({ id: "T01", milestoneId: "M001", sliceId: "S01", title: "First task", status: "pending" });
+  insertTask({ id: "T02", milestoneId: "M001", sliceId: "S01", title: "Second task", status: "pending" });
+
+  const sliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01");
+  const tasksDir = join(sliceDir, "tasks");
+  writeFileSync(
+    join(sliceDir, "S01-PLAN.md"),
+    "# S01: Slice\n\n## Tasks\n\nTask rows live in the DB; this projection intentionally has no legacy task syntax.\n",
+  );
+  writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01 Plan\n");
+  writeFileSync(join(tasksDir, "T02-PLAN.md"), "# T02 Plan\n");
+
+  const result = verifyExpectedArtifact("plan-slice", "M001/S01", base);
+  assert.equal(result, true, "DB task rows plus task plan files should verify plan-slice");
+});
+
+test("verifyExpectedArtifact plan-slice still fails when a DB-backed task plan file is missing", (t) => {
+  const base = makeTmpBase();
+  t.after(() => {
+    closeDatabase();
+    cleanup(base);
+  });
+
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Milestone", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Slice", status: "pending" });
+  insertTask({ id: "T01", milestoneId: "M001", sliceId: "S01", title: "First task", status: "pending" });
+  insertTask({ id: "T02", milestoneId: "M001", sliceId: "S01", title: "Second task", status: "pending" });
+
+  const sliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01");
+  const tasksDir = join(sliceDir, "tasks");
+  writeFileSync(
+    join(sliceDir, "S01-PLAN.md"),
+    "# S01: Slice\n\n## Tasks\n\nTask rows live in the DB; this projection intentionally has no legacy task syntax.\n",
+  );
+  writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01 Plan\n");
+
+  const result = verifyExpectedArtifact("plan-slice", "M001/S01", base);
+  assert.equal(result, false, "DB task rows must still require matching task plan files");
+});
+
 // ─── verifyExpectedArtifact: heading-style plan tasks (#1691) ─────────────
 
 test("verifyExpectedArtifact accepts plan-slice with heading-style tasks (### T01 --)", (t) => {
@@ -456,6 +509,32 @@ test("verifyExpectedArtifact accepts plan-slice with colon-style heading tasks (
   );
 });
 
+test("verifyExpectedArtifact accepts indented legacy plan-slice task markers", (t) => {
+  const base = makeTmpBase();
+  t.after(() => cleanup(base));
+
+  const sliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01");
+  const tasksDir = join(sliceDir, "tasks");
+  mkdirSync(tasksDir, { recursive: true });
+  writeFileSync(join(sliceDir, "S01-PLAN.md"), [
+    "# S01: Test Slice",
+    "",
+    "## Tasks",
+    "",
+    "  - [ ] **T01: Implement feature** `est:1h`",
+    "",
+    "  ### T02 -- Write tests",
+  ].join("\n"));
+  writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01 Plan");
+  writeFileSync(join(tasksDir, "T02-PLAN.md"), "# T02 Plan");
+
+  assert.strictEqual(
+    verifyExpectedArtifact("plan-slice", "M001/S01", base),
+    true,
+    "Indented legacy task markers should be treated as completed plan-slice artifacts",
+  );
+});
+
 test("verifyExpectedArtifact execute-task rejects heading-style plan without checked checkbox (#3607)", (t) => {
   const base = makeTmpBase();
   t.after(() => cleanup(base));

package/src/resources/extensions/gsd/tests/integration/auto-worktree-milestone-merge.test.ts

@@ -24,6 +24,7 @@ import {
 } from "../../auto-worktree.ts";
 import { getSliceBranchName } from "../../worktree.ts";
 import { nativeMergeSquash } from "../../native-git-bridge.ts";
+import { drainLogs, setStderrLoggingEnabled } from "../../workflow-logger.ts";
 
 function run(cmd: string, cwd: string): string {
   // Safe: all inputs are hardcoded test strings, not user input
@@ -251,6 +252,42 @@ describe("auto-worktree-milestone-merge", { timeout: 300_000 }, () => {
     assert.strictEqual(typeof result.pushed, "boolean", "pushed flag remains boolean");
   });
 
+  test("external .gsd and local-only auto_push closeout without cleanup or push warnings", () => {
+    const { repo, externalState } = freshRepoWithExternalGsd();
+    const previousStderr = setStderrLoggingEnabled(false);
+    drainLogs();
+
+    try {
+      writeFileSync(
+        join(externalState, "PREFERENCES.md"),
+        "---\nversion: 1\n---\n\ngit:\n  auto_push: true\n",
+      );
+      mkdirSync(join(externalState, "milestones", "M041"), { recursive: true });
+      mkdirSync(join(externalState, "runtime", "units"), { recursive: true });
+      writeFileSync(join(externalState, "runtime", "units", "leftover.json"), "{}\n");
+
+      const wtPath = createAutoWorktree(repo, "M041");
+      addSliceToMilestone(repo, wtPath, "M041", "S01", "Local-only push", [
+        { file: "local-only.ts", content: "export const localOnly = true;\n", message: "add local only file" },
+      ]);
+
+      const roadmap = makeRoadmap("M041", "Local-only closeout", [
+        { id: "S01", title: "Local-only push" },
+      ]);
+
+      const result = mergeMilestoneToMain(repo, "M041", roadmap);
+      const logs = drainLogs();
+      const messages = logs.map((entry) => entry.message).join("\n");
+
+      assert.equal(result.pushed, false, "local-only repo should not report pushed");
+      assert.ok(!messages.includes("untracked file cleanup failed"), "external .gsd cleanup should not call git on paths outside the repo");
+      assert.ok(!messages.includes("git push failed"), "missing origin should skip auto-push instead of running git push");
+    } finally {
+      drainLogs();
+      setStderrLoggingEnabled(previousStderr);
+    }
+  });
+
   test("auto-resolve .gsd/ state file conflicts", () => {
     const repo = freshRepo();
     const wtPath = createAutoWorktree(repo, "M050");

package/src/resources/extensions/gsd/tests/integration/state-machine-live-validation.test.ts

@@ -575,7 +575,7 @@ describe("state-machine-live-validation", () => {
       assert.match((result as any).error, /verification did not pass/);
     });
 
-    test("double milestone completion returns error", async () => {
+    test("double milestone completion is idempotent", async () => {
       base = createFullFixture();
       openDatabase(join(base, ".gsd", "gsd.db"));
       insertMilestone({ id: "M001", title: "Done", status: "complete" });
@@ -583,8 +583,10 @@ describe("state-machine-live-validation", () => {
       insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "complete" });
 
       const result = await handleCompleteMilestone(makeMilestoneParams("M001") as any, base);
-      assert.ok("error" in result);
-      assert.match((result as any).error, /already complete/);
+      assert.ok(!("error" in result), `already-complete milestone should be accepted: ${JSON.stringify(result)}`);
+      assert.equal(result.alreadyComplete, true);
+      assert.match(result.summaryPath, /M001-SUMMARY\.md$/);
+      assert.ok(isClosedStatus(getMilestone("M001")!.status), "milestone remains closed");
     });
   });
 

package/src/resources/extensions/gsd/tests/journal-integration.test.ts

@@ -399,6 +399,140 @@ test("runDispatch pauses when complete-milestone summary exists on disk but the
   assert.equal(stopCalls, 0, "mismatch pause should not hard-stop the loop");
 });
 
+test("runDispatch clears stuck state after Level 1 artifact recovery", async (t) => {
+  const capture = createEventCapture();
+  let invalidateCalls = 0;
+  let stopCalls = 0;
+  const base = join(tmpdir(), `gsd-stuck-plan-${randomUUID()}`);
+  t.after(() => {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  });
+
+  const sliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01");
+  const tasksDir = join(sliceDir, "tasks");
+  mkdirSync(tasksDir, { recursive: true });
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Test", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Slice", status: "pending" });
+  insertTask({ id: "T01", milestoneId: "M001", sliceId: "S01", title: "First task", status: "pending" });
+  writeFileSync(join(sliceDir, "S01-PLAN.md"), "# S01\n\n## Tasks\n\n- [ ] **T01: First task** `est:1h`\n");
+  writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01 Plan\n");
+
+  const deps = makeMockDeps(capture, {
+    invalidateAllCaches: () => { invalidateCalls++; },
+    stopAuto: async () => { stopCalls++; },
+    resolveDispatch: async () => ({
+      action: "dispatch" as const,
+      unitType: "plan-slice",
+      unitId: "M001/S01",
+      prompt: "plan the slice",
+      matchedRule: "planning → plan-slice",
+    }),
+  });
+  const ic = makeIC(deps, {
+    s: {
+      ...makeSession(),
+      basePath: base,
+      originalBasePath: base,
+    } as any,
+  });
+  const preData: PreDispatchData = {
+    state: {
+      phase: "planning",
+      activeMilestone: { id: "M001", title: "Test", status: "active" },
+      activeSlice: { id: "S01", title: "Slice" },
+      registry: [{ id: "M001", status: "active" }],
+      blockers: [],
+    } as any,
+    mid: "M001",
+    midTitle: "Test Milestone",
+  };
+  const loopState: LoopState = {
+    recentUnits: [
+      { key: "plan-slice/M001/S01" },
+      { key: "plan-slice/M001/S01" },
+    ],
+    stuckRecoveryAttempts: 0,
+    consecutiveFinalizeTimeouts: 0,
+  };
+
+  const result = await runDispatch(ic, preData, loopState);
+
+  assert.equal(result.action, "continue");
+  assert.equal(invalidateCalls, 1, "Level 1 artifact recovery should invalidate caches");
+  assert.equal(stopCalls, 0, "Level 1 artifact recovery should not hard-stop");
+  assert.deepEqual(loopState.recentUnits, [], "Level 1 artifact recovery should clear the stuck window");
+  assert.equal(loopState.stuckRecoveryAttempts, 0, "Level 1 artifact recovery should reset the recovery counter");
+});
+
+test("runDispatch escapes Level 2 stuck stop when artifact verifies after cache invalidation", async (t) => {
+  const capture = createEventCapture();
+  let invalidateCalls = 0;
+  let stopCalls = 0;
+  const base = join(tmpdir(), `gsd-stuck-plan-l2-${randomUUID()}`);
+  t.after(() => {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  });
+
+  const sliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01");
+  const tasksDir = join(sliceDir, "tasks");
+  mkdirSync(tasksDir, { recursive: true });
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Test", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Slice", status: "pending" });
+  insertTask({ id: "T01", milestoneId: "M001", sliceId: "S01", title: "First task", status: "pending" });
+  writeFileSync(join(sliceDir, "S01-PLAN.md"), "# S01\n\n## Tasks\n\n- [ ] **T01: First task** `est:1h`\n");
+  writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01 Plan\n");
+
+  const deps = makeMockDeps(capture, {
+    invalidateAllCaches: () => { invalidateCalls++; },
+    stopAuto: async () => { stopCalls++; },
+    resolveDispatch: async () => ({
+      action: "dispatch" as const,
+      unitType: "plan-slice",
+      unitId: "M001/S01",
+      prompt: "plan the slice",
+      matchedRule: "planning → plan-slice",
+    }),
+  });
+  const ic = makeIC(deps, {
+    s: {
+      ...makeSession(),
+      basePath: base,
+      originalBasePath: base,
+    } as any,
+  });
+  const preData: PreDispatchData = {
+    state: {
+      phase: "planning",
+      activeMilestone: { id: "M001", title: "Test", status: "active" },
+      activeSlice: { id: "S01", title: "Slice" },
+      registry: [{ id: "M001", status: "active" }],
+      blockers: [],
+    } as any,
+    mid: "M001",
+    midTitle: "Test Milestone",
+  };
+  const loopState: LoopState = {
+    recentUnits: [
+      { key: "plan-slice/M001/S01" },
+      { key: "plan-slice/M001/S01" },
+    ],
+    stuckRecoveryAttempts: 1,
+    consecutiveFinalizeTimeouts: 0,
+  };
+
+  const result = await runDispatch(ic, preData, loopState);
+
+  assert.equal(result.action, "continue");
+  assert.equal(invalidateCalls, 1, "Level 2 escape should invalidate caches before rechecking artifacts");
+  assert.equal(stopCalls, 0, "verified artifacts should escape Level 2 hard stop");
+  assert.deepEqual(loopState.recentUnits, [], "Level 2 artifact escape should clear the stuck window");
+  assert.equal(loopState.stuckRecoveryAttempts, 0, "Level 2 artifact escape should reset the recovery counter");
+});
+
 test("runUnitPhase emits unit-start and unit-end with causedBy reference", async () => {
   const capture = createEventCapture();
 

package/src/resources/extensions/gsd/tests/legacy-component-format-telemetry.test.ts

@@ -0,0 +1,62 @@
+// Project/App: GSD-2
+// File Purpose: Verifies telemetry for legacy component formats.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { loadComponentFromAgentFile, loadComponentFromDir } from "../component-loader.js";
+import { getLegacyTelemetry, resetLegacyTelemetry } from "../legacy-telemetry.js";
+
+function makeTempDir(): string {
+  return mkdtempSync(join(tmpdir(), "gsd-legacy-component-format-"));
+}
+
+test("legacy component telemetry counts successful skill and agent format loads", () => {
+  const dir = makeTempDir();
+  try {
+    resetLegacyTelemetry();
+
+    const modernDir = join(dir, "modern-skill");
+    mkdirSync(modernDir, { recursive: true });
+    writeFileSync(join(modernDir, "component.yaml"), `
+apiVersion: gsd/v1
+kind: skill
+metadata:
+  name: modern-skill
+  description: "Modern skill"
+spec:
+  prompt: SKILL.md
+`, "utf-8");
+    writeFileSync(join(modernDir, "SKILL.md"), "Modern content.", "utf-8");
+    assert.ok(loadComponentFromDir(modernDir, "user").component);
+    assert.equal(getLegacyTelemetry()["legacy.componentFormatUsed"], 0);
+
+    const legacySkillDir = join(dir, "legacy-skill");
+    mkdirSync(legacySkillDir, { recursive: true });
+    writeFileSync(join(legacySkillDir, "SKILL.md"), `---
+name: legacy-skill
+description: Legacy skill
+---
+Skill content.
+`, "utf-8");
+    assert.ok(loadComponentFromDir(legacySkillDir, "user").component);
+    assert.equal(getLegacyTelemetry()["legacy.componentFormatUsed"], 1);
+
+    const legacyAgentFile = join(dir, "legacy-agent.md");
+    writeFileSync(legacyAgentFile, `---
+name: legacy-agent
+description: Legacy agent
+tools: read, grep
+---
+Agent content.
+`, "utf-8");
+    assert.ok(loadComponentFromAgentFile(legacyAgentFile, "user").component);
+    assert.equal(getLegacyTelemetry()["legacy.componentFormatUsed"], 2);
+  } finally {
+    resetLegacyTelemetry();
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/legacy-telemetry.test.ts

@@ -0,0 +1,144 @@
+// Project/App: GSD-2
+// File Purpose: Tests for telemetry counters guarding legacy compatibility cleanup.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  getLegacyTelemetryReport,
+  getLegacyTelemetry,
+  incrementLegacyTelemetry,
+  listLegacyTelemetryCounters,
+  persistLegacyTelemetrySnapshot,
+  resetLegacyTelemetry,
+} from "../legacy-telemetry.ts";
+import { closeDatabase } from "../gsd-db.ts";
+import { deriveState, invalidateStateCache } from "../state.ts";
+import { _resetLogs, peekLogs, setStderrLoggingEnabled } from "../workflow-logger.ts";
+
+test("legacy telemetry exposes every Phase 8 cleanup counter", () => {
+  resetLegacyTelemetry();
+
+  assert.deepEqual(listLegacyTelemetryCounters(), [
+    "legacy.markdownFallbackUsed",
+    "legacy.workflowEngineUsed",
+    "legacy.uokFallbackUsed",
+    "legacy.mcpAliasUsed",
+    "legacy.componentFormatUsed",
+    "legacy.providerDefaultUsed",
+  ]);
+  assert.equal(getLegacyTelemetry()["legacy.markdownFallbackUsed"], 0);
+});
+
+test("legacy telemetry increments positive finite amounts only", () => {
+  resetLegacyTelemetry();
+
+  incrementLegacyTelemetry("legacy.workflowEngineUsed");
+  incrementLegacyTelemetry("legacy.workflowEngineUsed", 2);
+  incrementLegacyTelemetry("legacy.workflowEngineUsed", 0);
+  incrementLegacyTelemetry("legacy.workflowEngineUsed", Number.NaN);
+
+  assert.equal(getLegacyTelemetry()["legacy.workflowEngineUsed"], 3);
+});
+
+test("legacy telemetry emits one actionable diagnostic per counter", () => {
+  const previousStderr = setStderrLoggingEnabled(false);
+  try {
+    resetLegacyTelemetry();
+    _resetLogs();
+
+    incrementLegacyTelemetry("legacy.mcpAliasUsed");
+    incrementLegacyTelemetry("legacy.mcpAliasUsed");
+
+    const logs = peekLogs();
+    assert.equal(logs.length, 1);
+    assert.equal(logs[0]?.component, "migration");
+    assert.equal(logs[0]?.context?.counter, "legacy.mcpAliasUsed");
+    assert.match(logs[0]?.message ?? "", /canonical gsd_\* tool name/);
+  } finally {
+    _resetLogs();
+    resetLegacyTelemetry();
+    setStderrLoggingEnabled(previousStderr);
+  }
+});
+
+test("legacy telemetry can persist an opt-in snapshot file", () => {
+  const previousStderr = setStderrLoggingEnabled(false);
+  const previousOutput = process.env.GSD_LEGACY_TELEMETRY_FILE;
+  const base = mkdtempSync(join(tmpdir(), "gsd-legacy-telemetry-file-"));
+  const outputPath = join(base, "runtime", "legacy-telemetry.json");
+  try {
+    resetLegacyTelemetry();
+    _resetLogs();
+    process.env.GSD_LEGACY_TELEMETRY_FILE = outputPath;
+
+    incrementLegacyTelemetry("legacy.providerDefaultUsed", 2);
+
+    const report = JSON.parse(readFileSync(outputPath, "utf-8")) as ReturnType<typeof getLegacyTelemetryReport>;
+    assert.equal(typeof report.ts, "string");
+    assert.equal(report.counters["legacy.providerDefaultUsed"], 2);
+    assert.equal(report.counters["legacy.markdownFallbackUsed"], 0);
+  } finally {
+    if (previousOutput === undefined) delete process.env.GSD_LEGACY_TELEMETRY_FILE;
+    else process.env.GSD_LEGACY_TELEMETRY_FILE = previousOutput;
+    _resetLogs();
+    resetLegacyTelemetry();
+    setStderrLoggingEnabled(previousStderr);
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("legacy telemetry can persist a zero-use snapshot for deletion gates", () => {
+  const previousOutput = process.env.GSD_LEGACY_TELEMETRY_FILE;
+  const base = mkdtempSync(join(tmpdir(), "gsd-legacy-zero-telemetry-"));
+  const outputPath = join(base, "legacy-telemetry.json");
+  try {
+    resetLegacyTelemetry();
+    process.env.GSD_LEGACY_TELEMETRY_FILE = outputPath;
+
+    persistLegacyTelemetrySnapshot();
+
+    const report = JSON.parse(readFileSync(outputPath, "utf-8")) as ReturnType<typeof getLegacyTelemetryReport>;
+    assert.equal(typeof report.ts, "string");
+    assert.deepEqual(report.counters, {
+      "legacy.markdownFallbackUsed": 0,
+      "legacy.workflowEngineUsed": 0,
+      "legacy.uokFallbackUsed": 0,
+      "legacy.mcpAliasUsed": 0,
+      "legacy.componentFormatUsed": 0,
+      "legacy.providerDefaultUsed": 0,
+    });
+  } finally {
+    if (previousOutput === undefined) delete process.env.GSD_LEGACY_TELEMETRY_FILE;
+    else process.env.GSD_LEGACY_TELEMETRY_FILE = previousOutput;
+    resetLegacyTelemetry();
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("deriveState increments markdown fallback telemetry on explicit legacy fallback", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-legacy-telemetry-"));
+  const originalFallback = process.env.GSD_ALLOW_MARKDOWN_DERIVE_FALLBACK;
+  try {
+    closeDatabase();
+    resetLegacyTelemetry();
+    invalidateStateCache();
+    process.env.GSD_ALLOW_MARKDOWN_DERIVE_FALLBACK = "1";
+    mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+    writeFileSync(join(base, ".gsd", "milestones", "M001", "M001-CONTEXT.md"), "# M001: Legacy\n");
+
+    const state = await deriveState(base);
+
+    assert.equal(state.activeMilestone?.id, "M001");
+    assert.equal(getLegacyTelemetry()["legacy.markdownFallbackUsed"], 1);
+  } finally {
+    invalidateStateCache();
+    resetLegacyTelemetry();
+    if (originalFallback === undefined) delete process.env.GSD_ALLOW_MARKDOWN_DERIVE_FALLBACK;
+    else process.env.GSD_ALLOW_MARKDOWN_DERIVE_FALLBACK = originalFallback;
+    rmSync(base, { recursive: true, force: true });
+  }
+});