gsd-pi 2.79.0-dev.ece5fd8ba → 2.80.0-dev.4ea7d80e7

package/src/resources/extensions/gsd/tests/pr-evidence-hardening.test.ts

@@ -0,0 +1,165 @@
+// Project/App: GSD-2
+// File Purpose: Hardening tests for buildPrEvidence — HTML-comment stripping, fake commit-trailer removal, and per-item length capping.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { buildPrEvidence, type PrEvidenceInput } from "../pr-evidence.ts";
+
+test("pr-evidence hardening: strips HTML comments from summaries", () => {
+  const evidence = buildPrEvidence({
+    milestoneId: "M001",
+    summaries: ["visible<!-- hidden secret -->tail"],
+  });
+  assert.ok(!evidence.body.includes("<!--"), "raw <!-- must not appear");
+  assert.ok(!evidence.body.includes("hidden secret"), "comment contents must be stripped");
+  assert.ok(evidence.body.includes("visibletail"), "non-comment text must remain");
+});
+
+test("pr-evidence hardening: removes Co-Authored-By trailer from why", () => {
+  const evidence = buildPrEvidence({
+    milestoneId: "M001",
+    why: "Real reason here.\nCo-Authored-By: Evil <e@evil.com>\nMore reason.",
+  });
+  assert.ok(!evidence.body.includes("Evil <e@evil.com>"));
+  assert.ok(!/Co-Authored-By:/i.test(evidence.body));
+  assert.ok(evidence.body.includes("Real reason here."));
+  assert.ok(evidence.body.includes("More reason."));
+});
+
+test("pr-evidence hardening: removes Signed-off-by trailer from how", () => {
+  const evidence = buildPrEvidence({
+    milestoneId: "M001",
+    how: "Step one.\nSigned-off-by: Forged <f@x.com>\nStep two.",
+  });
+  assert.ok(!evidence.body.includes("Forged <f@x.com>"));
+  assert.ok(!/Signed-off-by:/i.test(evidence.body));
+  assert.ok(evidence.body.includes("Step one."));
+  assert.ok(evidence.body.includes("Step two."));
+});
+
+test("pr-evidence hardening: trailer-name match is case-insensitive", () => {
+  const evidence = buildPrEvidence({
+    milestoneId: "M001",
+    why: "ok\nco-authored-by: lower <l@l.com>\nSIGNED-OFF-BY: upper <u@u.com>\nend",
+  });
+  assert.ok(!evidence.body.includes("lower <l@l.com>"));
+  assert.ok(!evidence.body.includes("upper <u@u.com>"));
+  assert.ok(evidence.body.includes("ok"));
+  assert.ok(evidence.body.includes("end"));
+});
+
+test("pr-evidence hardening: caps oversize summaries item with truncation suffix", () => {
+  const big = "A".repeat(5 * 1024); // 5 KB
+  const evidence = buildPrEvidence({
+    milestoneId: "M001",
+    summaries: [big],
+  });
+  // Find the truncated A-block in the body and assert it is bounded.
+  const lines = evidence.body.split("\n");
+  const longLine = lines.find((l) => l.startsWith("AAAA"));
+  assert.ok(longLine, "expected truncated A-line in body");
+  assert.ok(longLine!.endsWith(" … [truncated]"), "must end with truncation suffix");
+  assert.ok(
+    Buffer.byteLength(longLine!, "utf8") <= 2048,
+    `truncated item must be within 2 KB cap, got ${Buffer.byteLength(longLine!, "utf8")}`,
+  );
+});
+
+test("pr-evidence hardening: HTML comment split across summary items is preserved literally", () => {
+  // Documented behavior: each item is sanitized independently. A comment
+  // that begins in one item and closes in the next is NOT joined, so the
+  // open/close markers remain as literal text. This is intentional — joining
+  // items before sanitizing would let an attacker straddle items to inject
+  // an aligned comment that hides the second item from rendered view.
+  const evidence = buildPrEvidence({
+    milestoneId: "M001",
+    summaries: ["first item ends <!--", "--> second item begins"],
+  });
+  // The literal markers survive because each item was sanitized alone.
+  assert.ok(evidence.body.includes("<!--"), "open marker preserved as literal");
+  assert.ok(evidence.body.includes("-->"), "close marker preserved as literal");
+  assert.ok(evidence.body.includes("first item ends"));
+  assert.ok(evidence.body.includes("second item begins"));
+});
+
+test("pr-evidence hardening: clean input is byte-identical to pre-hardening output", () => {
+  // This test is the contract that protects the golden fixtures: the
+  // sanitizer must be a true no-op for well-formed input. If this fails,
+  // there is a bug in the sanitizer (not in the goldens).
+  const cleanInput: PrEvidenceInput = {
+    milestoneId: "M001",
+    milestoneTitle: "Authentication",
+    changeType: "feat",
+    linkedIssue: "Closes #123",
+    summaries: ["### S01\nImplemented login flow."],
+    blockers: ["Awaiting design review"],
+    roadmapItems: ["- [x] **S01: Login**"],
+    metrics: ["**Units executed:** 3"],
+    testsRun: ["npm test", "npm run typecheck:extensions"],
+    why: "Users need to authenticate before accessing protected resources.",
+    how: "Added password hash check and session token issuance.",
+    rollbackNotes: ["Revert the merge commit."],
+  };
+
+  const expected = [
+    "## TL;DR",
+    "",
+    "**What:** Ship milestone M001 - Authentication",
+    "**Why:** Users need to authenticate before accessing protected resources.",
+    "**How:** Added password hash check and session token issuance.",
+    "",
+    "## What",
+    "",
+    "### S01\nImplemented login flow.",
+    "",
+    "## Blockers",
+    "",
+    "- Awaiting design review",
+    "",
+    "## Why",
+    "",
+    "Users need to authenticate before accessing protected resources.",
+    "",
+    "## How",
+    "",
+    "Added password hash check and session token issuance.",
+    "",
+    "## Linked Issue",
+    "",
+    "Closes #123",
+    "",
+    "## Roadmap",
+    "",
+    "- [x] **S01: Login**",
+    "",
+    "## Metrics",
+    "",
+    "- **Units executed:** 3",
+    "",
+    "## Tests Run",
+    "",
+    "- npm test",
+    "- npm run typecheck:extensions",
+    "",
+    "## Change Type",
+    "",
+    "- [x] `feat` - New feature or capability",
+    "- [ ] `fix` - Bug fix",
+    "- [ ] `refactor` - Code restructuring",
+    "- [ ] `test` - Adding or updating tests",
+    "- [ ] `docs` - Documentation only",
+    "- [ ] `chore` - Build, CI, or tooling changes",
+    "",
+    "## Rollback And Compatibility",
+    "",
+    "- Revert the merge commit.",
+    "",
+    "## AI Assistance Disclosure",
+    "",
+    "This PR was prepared with AI assistance.",
+  ].join("\n");
+
+  const actual = buildPrEvidence(cleanInput).body;
+  assert.equal(actual, expected, "clean input must produce byte-identical output (sanitizer is no-op)");
+});

package/src/resources/extensions/gsd/tests/pr-evidence.test.ts

@@ -0,0 +1,79 @@
+// Project/App: GSD-2
+// File Purpose: Tests for the shared GSD pull request evidence generator.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { buildPrEvidence, type PrChangeType } from "../pr-evidence.ts";
+
+test("pr-evidence: generated body includes contribution-required sections", () => {
+  const evidence = buildPrEvidence({
+    milestoneId: "M001",
+    milestoneTitle: "Authentication",
+    linkedIssue: "Closes #123",
+    summaries: ["### S01\nImplemented login."],
+    roadmapItems: ["- [x] **S01: Login**"],
+    metrics: ["**Units executed:** 3"],
+    testsRun: ["npm test"],
+    rollbackNotes: ["Revert the merge commit."],
+  });
+
+  assert.equal(evidence.title, "feat: Authentication");
+  for (const section of [
+    "## TL;DR",
+    "## What",
+    "## Why",
+    "## How",
+    "## Linked Issue",
+    "## Tests Run",
+    "## Change Type",
+    "## Rollback And Compatibility",
+    "## AI Assistance Disclosure",
+  ]) {
+    assert.ok(evidence.body.includes(section), `missing section: ${section}`);
+  }
+  assert.ok(evidence.body.includes("Closes #123"));
+  assert.ok(evidence.body.includes("npm test"));
+  assert.ok(evidence.body.includes("This PR was prepared with AI assistance."));
+});
+
+test("pr-evidence: every change type selects exactly one checklist row", () => {
+  const changeTypes: PrChangeType[] = ["feat", "fix", "refactor", "test", "docs", "chore"];
+
+  for (const changeType of changeTypes) {
+    const evidence = buildPrEvidence({ milestoneId: "M001", changeType });
+    const checkedRows = evidence.body.split("\n").filter((line) => line.startsWith("- [x] `"));
+    assert.deepEqual(checkedRows, [
+      `- [x] \`${changeType}\` - ${{
+        feat: "New feature or capability",
+        fix: "Bug fix",
+        refactor: "Code restructuring",
+        test: "Adding or updating tests",
+        docs: "Documentation only",
+        chore: "Build, CI, or tooling changes",
+      }[changeType]}`,
+    ]);
+  }
+});
+
+test("pr-evidence: missing issue, tests, and rollback data are explicit", () => {
+  const evidence = buildPrEvidence({ milestoneId: "M001", aiAssisted: false });
+
+  assert.ok(evidence.body.includes("Not specified. Add an issue link"));
+  assert.ok(evidence.body.includes("Not specified. Add exact verification commands"));
+  assert.ok(evidence.body.includes("No behavior-changing rollback notes recorded."));
+  assert.ok(!evidence.body.includes("## AI Assistance Disclosure"));
+});
+
+test("pr-evidence: subject metadata supports non-milestone PRs", () => {
+  const evidence = buildPrEvidence({
+    milestoneId: "M001",
+    subjectId: "S01",
+    subjectKind: "slice",
+    milestoneTitle: "Auth Slice",
+  });
+
+  assert.equal(evidence.title, "feat: Auth Slice");
+  assert.ok(evidence.body.includes("Ship slice S01 - Auth Slice"));
+  assert.ok(evidence.body.includes("Slice work is complete and ready for review."));
+});

package/src/resources/extensions/gsd/tests/process-task-path.test.ts

@@ -0,0 +1,51 @@
+// Project/App: GSD-2
+// File Purpose: Tests for canonical process recommendations by task size.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  formatRecommendedProcessPaths,
+  listRecommendedProcessPaths,
+  recommendProcessPath,
+  type ProcessTaskSize,
+} from "../process-task-path.ts";
+
+test("process task paths cover every Phase 7 task size with one command", () => {
+  const expected: ProcessTaskSize[] = [
+    "hotfix",
+    "bugfix",
+    "small-feature",
+    "large-feature",
+    "architecture-change",
+  ];
+
+  const paths = listRecommendedProcessPaths();
+  assert.deepEqual(paths.map((path) => path.taskSize), expected);
+
+  for (const taskSize of expected) {
+    const path = recommendProcessPath(taskSize);
+    assert.equal(path.taskSize, taskSize);
+    assert.ok(path.templateId.length > 0);
+    assert.match(path.command, /^\/gsd /);
+    assert.ok(path.phases.length > 0);
+    assert.ok(path.guidance.length > 0);
+  }
+});
+
+test("process task paths route large work to the DB-backed milestone flow", () => {
+  const largeFeature = recommendProcessPath("large-feature");
+  assert.equal(largeFeature.templateId, "full-project");
+  assert.match(largeFeature.command, /\/gsd discuss/);
+  assert.match(largeFeature.command, /\/gsd auto/);
+  assert.match(largeFeature.guidance, /DB-backed milestone flow/);
+});
+
+test("formatted process paths are stable for command help", () => {
+  const formatted = formatRecommendedProcessPaths();
+  assert.match(formatted, /hotfix\s+\/gsd start hotfix/);
+  assert.match(formatted, /bugfix\s+\/gsd start bugfix/);
+  assert.match(formatted, /small-feature\s+\/gsd start small-feature/);
+  assert.match(formatted, /large-feature\s+\/gsd discuss/);
+  assert.match(formatted, /architecture-change\s+\/gsd start refactor/);
+});

package/src/resources/extensions/gsd/tests/prompt-step-ordering.test.ts

@@ -2,7 +2,7 @@
  * Regression test for #3696 — prompt step ordering and runtime fixes
  *
  * 1. complete-milestone.md: gsd_requirement_update (step 9) before
- *    gsd_complete_milestone (step 10)
+ *    gsd_complete_milestone, and completion remains the final durable write
  * 2. complete-slice.md: uses gsd_requirement_update
  * 3. register-extension.ts: _gsdEpipeGuard logs instead of re-throwing
  * 4. register-hooks.ts: session_before_compact only checks isAutoActive
@@ -50,6 +50,21 @@ describe('prompt step ordering (#3696)', () => {
     );
   });
 
+  test('project and learnings writes appear before gsd_complete_milestone', () => {
+    const projectMatch = completeMilestoneMd.match(/^\d+\.\s.*PROJECT\.md/m);
+    const learningsMatch = completeMilestoneMd.match(/^\d+\.\s.*Extract structured learnings/m);
+    const completeMilestoneMatch = completeMilestoneMd.match(/^\d+\.\s.*gsd_complete_milestone/m);
+    assert.ok(projectMatch, 'PROJECT.md update should appear in a numbered step');
+    assert.ok(learningsMatch, 'learnings extraction should appear in a numbered step');
+    assert.ok(completeMilestoneMatch, 'gsd_complete_milestone should appear in a numbered step');
+
+    const projectIdx = completeMilestoneMd.indexOf(projectMatch![0]);
+    const learningsIdx = completeMilestoneMd.indexOf(learningsMatch![0]);
+    const completeMilestoneIdx = completeMilestoneMd.indexOf(completeMilestoneMatch![0]);
+    assert.ok(projectIdx < completeMilestoneIdx, 'PROJECT.md update must happen before gsd_complete_milestone');
+    assert.ok(learningsIdx < completeMilestoneIdx, 'learnings extraction must happen before gsd_complete_milestone');
+  });
+
   test('complete-slice.md uses gsd_requirement_update', () => {
     assert.match(completeSliceMd, /gsd_requirement_update/,
       'complete-slice.md should reference gsd_requirement_update');

package/src/resources/extensions/gsd/tests/queue-prompt-rendering.test.ts

@@ -0,0 +1,37 @@
+// Project/App: GSD-2
+// File Purpose: Verifies the queue prompt renders compact discussion and write-gate guidance.
+
+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("queue prompt renders compact draft, verification, 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-queue-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("queue", {
+    preamble: "Queue preamble.",
+    existingMilestonesContext: "No existing milestones.",
+    commitInstruction: "Commit queued milestone artifacts.",
+    inlinedTemplates: "## Context Template\n\nUse standard GSD context.",
+  });
+
+  assert.match(prompt, /Draft Awareness/);
+  assert.match(prompt, /What do you want to add\?/);
+  assert.match(prompt, /Investigate between question rounds/);
+  assert.match(prompt, /Pre-Write Verification/);
+  assert.match(prompt, /depth_verification/);
+  assert.match(prompt, /gsd_milestone_generate_id/);
+  assert.match(prompt, /gsd_summary_save/);
+  assert.doesNotMatch(prompt, /\{\{[a-zA-Z][a-zA-Z0-9_]*\}\}/);
+});

package/src/resources/extensions/gsd/tests/start-auto-detached.test.ts

@@ -3,6 +3,8 @@ import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
+import { _withDetachedAutoKeepaliveForTest } from "../auto.ts";
+
 const gsdDir = resolve(import.meta.dirname, "..");
 
 function readGsdFile(relativePath: string): string {
@@ -102,8 +104,8 @@ test("startAutoDetached reports failures asynchronously (#3733)", () => {
     "auto.ts should export startAutoDetached",
   );
   assert.ok(
-    autoSrc.includes("void startAuto(ctx, pi, base, verboseMode, options).catch"),
-    "startAutoDetached should launch startAuto without awaiting it",
+    autoSrc.includes("void withDetachedAutoKeepalive(startAuto(ctx, pi, base, verboseMode, options)).catch"),
+    "startAutoDetached should launch startAuto without awaiting it and keep the process alive",
   );
   assert.ok(
     autoSrc.includes("ctx.ui.notify(`Auto-start failed: ${message}`, \"error\")"),
@@ -111,6 +113,48 @@ test("startAutoDetached reports failures asynchronously (#3733)", () => {
   );
 });
 
+test("detached auto-start keeps a ref'ed handle until the run settles", async () => {
+  const originalSetInterval = globalThis.setInterval;
+  const originalClearInterval = globalThis.clearInterval;
+  let intervalCreated = false;
+  let intervalCleared = false;
+  let createdHandle: NodeJS.Timeout | undefined;
+  let resolveRun!: () => void;
+  const run = new Promise<void>((resolve) => {
+    resolveRun = resolve;
+  });
+
+  globalThis.setInterval = ((handler: TimerHandler, timeout?: number, ...args: unknown[]) => {
+    intervalCreated = true;
+    assert.equal(timeout, 30_000);
+    void handler;
+    void args;
+    createdHandle = originalSetInterval(() => {}, 1_000_000);
+    assert.equal(createdHandle.hasRef(), true, "detached auto keepalive must be ref'ed");
+    return createdHandle;
+  }) as unknown as typeof setInterval;
+
+  globalThis.clearInterval = ((handle?: NodeJS.Timeout | number | string) => {
+    if (handle === createdHandle) intervalCleared = true;
+    return originalClearInterval(handle);
+  }) as unknown as typeof clearInterval;
+
+  try {
+    const heldRun = _withDetachedAutoKeepaliveForTest(run);
+    assert.equal(intervalCreated, true, "keepalive interval should start immediately");
+    assert.equal(intervalCleared, false, "keepalive should remain active while auto-mode is running");
+
+    resolveRun();
+    await heldRun;
+
+    assert.equal(intervalCleared, true, "keepalive interval should clear when auto-mode settles");
+  } finally {
+    if (createdHandle) originalClearInterval(createdHandle);
+    globalThis.setInterval = originalSetInterval;
+    globalThis.clearInterval = originalClearInterval;
+  }
+});
+
 test("detached auto-start preserves milestone lock across pause/stop cleanup (#3733)", () => {
   const autoSrc = readGsdFile("auto.ts");
   const sessionSrc = readGsdFile("auto/session.ts");

package/src/resources/extensions/gsd/tests/tool-naming.test.ts

@@ -1,12 +1,10 @@
-// tool-naming — Verifies canonical + alias tool registration for GSD DB tools.
-//
-// Each DB tool must register under its canonical gsd_concept_action name
-// AND under a backward-compatible alias name.
-// The alias must share the exact same execute function reference as the canonical tool.
+// Project/App: GSD-2
+// File Purpose: Verifies canonical and alias DB tool registration plus legacy alias telemetry.
 
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { registerDbTools } from '../bootstrap/db-tools.ts';
+import { getLegacyTelemetry, resetLegacyTelemetry } from '../legacy-telemetry.ts';
 
 
 // ─── Mock PI ──────────────────────────────────────────────────────────────────
@@ -66,9 +64,9 @@ for (const { canonical, alias } of RENAME_MAP) {
   assert.ok(aliasTool !== undefined, `Alias tool "${alias}" should be registered`);
 }
 
-// ─── Execute function identity ───────────────────────────────────────────────
+// ─── Execute function wrapping ───────────────────────────────────────────────
 
-console.log('\n── Tool naming: execute function identity (===) ──');
+console.log('\n── Tool naming: alias execute wrapper ──');
 
 for (const { canonical, alias } of RENAME_MAP) {
   const canonicalTool = pi.tools.find((t: any) => t.name === canonical);
@@ -76,12 +74,37 @@ for (const { canonical, alias } of RENAME_MAP) {
 
   if (canonicalTool && aliasTool) {
     assert.ok(
-      canonicalTool.execute === aliasTool.execute,
-      `"${canonical}" and "${alias}" should share the same execute function reference`,
+      canonicalTool.execute !== aliasTool.execute,
+      `"${alias}" should wrap "${canonical}" so alias usage can be counted`,
     );
   }
 }
 
+test("alias execute increments legacy MCP alias telemetry before delegating", async () => {
+  const canonicalTool = pi.tools.find((t: any) => t.name === "gsd_decision_save");
+  const aliasTool = pi.tools.find((t: any) => t.name === "gsd_save_decision");
+  assert.ok(canonicalTool);
+  assert.ok(aliasTool);
+
+  const originalCanonicalExecute = canonicalTool.execute;
+  try {
+    resetLegacyTelemetry();
+    let delegated = false;
+    canonicalTool.execute = async () => {
+      delegated = true;
+      return { content: [{ type: "text", text: "ok" }], details: { ok: true } };
+    };
+
+    await aliasTool.execute("call-1", {}, undefined, undefined, undefined);
+
+    assert.equal(delegated, true);
+    assert.equal(getLegacyTelemetry()["legacy.mcpAliasUsed"], 1);
+  } finally {
+    canonicalTool.execute = originalCanonicalExecute;
+    resetLegacyTelemetry();
+  }
+});
+
 // ─── Alias descriptions include "(alias for ...)" ───────────────────────────
 
 console.log('\n── Tool naming: alias descriptions ──');

package/src/resources/extensions/gsd/tests/unit-context-composer.test.ts

@@ -1,6 +1,5 @@
-// GSD-2 — #4782 phase 2 composer tests. Pure-function tests using mock
-// resolvers plus an integration check that reassess-roadmap's migrated
-// builder produces a prompt matching expectations.
+// Project/App: GSD-2
+// File Purpose: Tests unit context composer rendering, budgets, and reassess-roadmap prompt integration.
 
 import test from "node:test";
 import assert from "node:assert/strict";
@@ -122,9 +121,9 @@ test("Context Mode composer: standalone output starts with heading and includes
   assert.ok(out.startsWith("## Context Mode"));
   assert.match(out, /execution lane/i);
   assert.match(out, /`gsd_exec`/);
-  assert.match(out, /noisy scans, builds, and tests/);
+  assert.match(out, /noisy commands/);
   assert.match(out, /`gsd_exec_search`/);
-  assert.match(out, /before repeating prior runs/);
+  assert.match(out, /before reruns/);
   assert.match(out, /`gsd_resume`/);
   assert.match(out, /after compaction or resume/);
 });
@@ -137,6 +136,7 @@ test("Context Mode composer: nested output is compact single sentence", () => {
   assert.match(out, /`gsd_exec`/);
   assert.match(out, /`gsd_exec_search`/);
   assert.match(out, /`gsd_resume`/);
+  assert.ok(out.length < 180, `nested guidance should stay compact, got ${out.length} chars`);
 });
 
 // ─── Integration: migrated buildReassessRoadmapPrompt ─────────────────────
@@ -224,7 +224,7 @@ test("#4782 phase 2: buildReassessRoadmapPrompt emits composer-shaped context wi
 
 const fakeBase: BaseResolverContext = {
   unitType: "reassess-roadmap",
-  basePath: "/tmp/fake",
+  basePath: process.env.GSD_TEST_WORKSPACE_ROOT ?? process.cwd(),
   milestoneId: "M001",
   sliceId: "S01",
 };

package/src/resources/extensions/gsd/tests/uok-kernel-path.test.ts

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Verifies UOK kernel path selection and legacy fallback telemetry.
 import test from "node:test";
 import assert from "node:assert/strict";
 import { mkdtempSync, readFileSync, rmSync } from "node:fs";
@@ -11,6 +13,7 @@ import type { AutoSession } from "../auto/session.ts";
 import type { LoopDeps } from "../auto/loop-deps.ts";
 import { gsdRoot } from "../paths.ts";
 import type { GSDPreferences } from "../preferences.ts";
+import { getLegacyTelemetry, resetLegacyTelemetry } from "../legacy-telemetry.ts";
 
 function makeBasePath(): string {
   return mkdtempSync(join(tmpdir(), "gsd-uok-kernel-"));
@@ -86,6 +89,7 @@ function readParityEvents(basePath: string): Array<Record<string, unknown>> {
 test("runAutoLoopWithUok uses kernel path by default and records uok-kernel parity", async () => {
   const basePath = makeBasePath();
   try {
+    resetLegacyTelemetry();
     const args = makeArgs(basePath, {
       uok: {
         enabled: true,
@@ -109,7 +113,9 @@ test("runAutoLoopWithUok uses kernel path by default and records uok-kernel pari
     assert.equal(events[1]?.path, "uok-kernel");
     assert.equal(events[1]?.phase, "exit");
     assert.equal(events[1]?.status, "ok");
+    assert.equal(getLegacyTelemetry()["legacy.uokFallbackUsed"], 0);
   } finally {
+    resetLegacyTelemetry();
     rmSync(basePath, { recursive: true, force: true });
   }
 });
@@ -117,6 +123,7 @@ test("runAutoLoopWithUok uses kernel path by default and records uok-kernel pari
 test("runAutoLoopWithUok uses legacy path when explicit legacy fallback is enabled", async () => {
   const basePath = makeBasePath();
   try {
+    resetLegacyTelemetry();
     const args = makeArgs(basePath, {
       uok: {
         enabled: true,
@@ -134,7 +141,9 @@ test("runAutoLoopWithUok uses legacy path when explicit legacy fallback is enabl
     assert.equal(events[0]?.path, "legacy-fallback");
     assert.equal(events[1]?.path, "legacy-fallback");
     assert.equal(events[1]?.status, "ok");
+    assert.equal(getLegacyTelemetry()["legacy.uokFallbackUsed"], 1);
   } finally {
+    resetLegacyTelemetry();
     rmSync(basePath, { recursive: true, force: true });
   }
 });
@@ -144,6 +153,7 @@ test("runAutoLoopWithUok respects GSD_UOK_FORCE_LEGACY emergency switch", async
   const previous = process.env.GSD_UOK_FORCE_LEGACY;
   process.env.GSD_UOK_FORCE_LEGACY = "1";
   try {
+    resetLegacyTelemetry();
     const args = makeArgs(basePath, {
       uok: {
         enabled: true,
@@ -158,7 +168,9 @@ test("runAutoLoopWithUok respects GSD_UOK_FORCE_LEGACY emergency switch", async
     assert.equal(events.length, 2);
     assert.equal(events[0]?.path, "legacy-fallback");
     assert.equal(events[1]?.path, "legacy-fallback");
+    assert.equal(getLegacyTelemetry()["legacy.uokFallbackUsed"], 1);
   } finally {
+    resetLegacyTelemetry();
     if (previous === undefined) delete process.env.GSD_UOK_FORCE_LEGACY;
     else process.env.GSD_UOK_FORCE_LEGACY = previous;
     rmSync(basePath, { recursive: true, force: true });

package/src/resources/extensions/gsd/tests/uok-plan-v2-wiring.test.ts

@@ -118,7 +118,7 @@ test("guided flow checks pending deep setup before plan-v2 gate", () => {
   const source = readFileSync(join(gsdDir, "guided-flow.ts"), "utf-8");
   const showSmartEntryIdx = source.indexOf("export async function showSmartEntry");
   assert.notEqual(showSmartEntryIdx, -1);
-  const deepIdx = source.indexOf("hasPendingDeepStage(prefs, basePath)", showSmartEntryIdx);
+  const deepIdx = source.indexOf("shouldRunDeepProjectSetup(state, prefs, basePath)", showSmartEntryIdx);
   const planIdx = source.indexOf("runPlanV2Gate(ctx, basePath, state)", showSmartEntryIdx);
   assert.ok(
     deepIdx > -1 && planIdx > -1 && deepIdx < planIdx,

package/src/resources/extensions/gsd/tests/workflow-custom-engine-dispatch-outcome.test.ts

@@ -0,0 +1,55 @@
+// Project/App: GSD-2
+// File Purpose: Unit tests for custom-engine dispatch outcome side-effect adapter.
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { handleCustomEngineDispatchOutcome } from "../auto/workflow-custom-engine-dispatch-outcome.ts";
+
+test("handleCustomEngineDispatchOutcome stops auto on stop decision", async () => {
+  const calls: unknown[] = [];
+
+  const flow = await handleCustomEngineDispatchOutcome({
+    decision: { action: "stop", reason: "done" },
+    deps: {
+      stopAuto: async reason => {
+        calls.push(["stopAuto", reason]);
+      },
+    },
+  });
+
+  assert.deepEqual(flow, { action: "break" });
+  assert.deepEqual(calls, [["stopAuto", "done"]]);
+});
+
+test("handleCustomEngineDispatchOutcome continues on skip decision", async () => {
+  const calls: unknown[] = [];
+
+  const flow = await handleCustomEngineDispatchOutcome({
+    decision: { action: "skip" },
+    deps: {
+      stopAuto: async reason => {
+        calls.push(["stopAuto", reason]);
+      },
+    },
+  });
+
+  assert.deepEqual(flow, { action: "continue" });
+  assert.deepEqual(calls, []);
+});
+
+test("handleCustomEngineDispatchOutcome dispatches without side effects", async () => {
+  const calls: unknown[] = [];
+
+  const flow = await handleCustomEngineDispatchOutcome({
+    decision: { action: "dispatch" },
+    deps: {
+      stopAuto: async reason => {
+        calls.push(["stopAuto", reason]);
+      },
+    },
+  });
+
+  assert.deepEqual(flow, { action: "dispatch" });
+  assert.deepEqual(calls, []);
+});