@opengsd/gsd-pi 1.8.1 → 1.9.0-dev.5c1a3ff2

package/src/resources/extensions/gsd/tests/prompt-budget-enforcement.test.ts

@@ -13,6 +13,7 @@ import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 
 import { buildExecuteTaskPrompt, buildPlanSlicePrompt, buildReactiveExecutePrompt, buildResearchSlicePrompt, inlineDependencySummaries } from "../auto-prompts.js";
+import { buildDiscussSlicePrompt } from "../guided-flow.js";
 import { computeBudgets, truncateAtSectionBoundary } from "../context-budget.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -735,3 +736,68 @@ describe("prompt-budget: modelRegistry + sessionContextWindow behavior", () => {
     }
   });
 });
+
+// ─── execute-task + discuss-slice inline caps (plan 039) ──────────────────────
+
+describe("prompt-budget: execute-task inline cap (039)", () => {
+  it("keeps the authoritative task plan whole but drops trailing templates when the plan alone exceeds the inline budget", async () => {
+    const base = createFixtureBase();
+    try {
+      const sliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01");
+      const taskDir = join(sliceDir, "tasks");
+      mkdirSync(taskDir, { recursive: true });
+      writeFileSync(join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md"), "# Roadmap\n");
+      writeFileSync(join(sliceDir, "S01-PLAN.md"), "# Slice Plan\n");
+      // Oversized task plan (~60K) — well past the 20K inline ceiling.
+      const bigPlan = "# Task Plan\n\nMARKER_TASKPLAN_HEAD\n\n" + Array.from({ length: 30 }, (_, i) =>
+        `### Step ${i}\n\n${"Implementation detail. ".repeat(90)}`
+      ).join("\n\n");
+      writeFileSync(join(taskDir, "T01-PLAN.md"), bigPlan);
+
+      const prompt = await buildExecuteTaskPrompt("M001", "S01", "Slice", "T01", "Task", base, {
+        level: "standard",
+        sessionContextWindow: 32_000,
+      });
+
+      // The task plan is the authoritative execution contract — never truncated;
+      // its content survives whole even when it alone exceeds the inline budget.
+      assert.match(prompt, /MARKER_TASKPLAN_HEAD/);
+      assert.match(prompt, /### Step 29/);
+      // Trailing lower-priority templates are dropped — the on-demand decisions
+      // template that "standard" normally inlines is gone because the task plan
+      // consumed the entire inline budget. (Baseline: the tiny-plan test above
+      // asserts this block IS present.)
+      assert.doesNotMatch(prompt, /### On-demand Decisions Template/);
+    } finally {
+      cleanup(base);
+    }
+  });
+});
+
+describe("prompt-budget: discuss-slice inline cap (039)", () => {
+  it("caps the inlined block — roadmap survives first, the trailing decisions register truncates", async () => {
+    const base = createFixtureBase();
+    try {
+      const msDir = join(base, ".gsd", "milestones", "M001");
+      mkdirSync(join(msDir, "slices", "S01"), { recursive: true });
+      writeFileSync(join(msDir, "M001-ROADMAP.md"), "# Roadmap\n\nMARKER_ROADMAP\n\n- [ ] **S01: Current** `risk:low`\n");
+      writeFileSync(join(msDir, "M001-CONTEXT.md"), "# Context\n\nMARKER_CONTEXT\n");
+      // Huge decisions register (~60K) — the unbounded-growth surface the cap bounds.
+      const bigDecisions = "# Decisions\n\n" + Array.from({ length: 40 }, (_, i) =>
+        `### D${String(i).padStart(3, "0")}\n\n${"Decision rationale detail. ".repeat(60)}`
+      ).join("\n\n");
+      writeFileSync(join(base, ".gsd", "DECISIONS.md"), bigDecisions);
+
+      const prompt = await buildDiscussSlicePrompt("M001", "S01", "Current", base);
+
+      // Roadmap is first in the inlined block → survives the cap.
+      assert.match(prompt, /MARKER_ROADMAP/);
+      // The cap fired (capPreamble ceiling is 20K; the block is ~60K).
+      assert.match(prompt, /\[\.\.\.truncated/);
+      // The last decision (trailing content) is dropped.
+      assert.doesNotMatch(prompt, /### D039/);
+    } finally {
+      cleanup(base);
+    }
+  });
+});

package/src/resources/extensions/gsd/tests/reactive-executor.test.ts

@@ -608,3 +608,42 @@ test("getDependencyTaskSummaryPaths handles missing dependency summaries gracefu
     rmSync(repo, { recursive: true, force: true });
   }
 });
+
+test("#1343: getPriorTaskSummaryPaths excludes sibling-slice summaries in flat-phase", async () => {
+  const { getPriorTaskSummaryPaths } = await import("../auto-prompts.ts");
+  const repo = mkdtempSync(join(tmpdir(), "gsd-reactive-flat-prior-"));
+  try {
+    // Flat-phase: slices S01 and S02 share the phase dir and overlap task ids.
+    const phaseDir = join(repo, ".gsd", "phases", "01-test");
+    mkdirSync(phaseDir, { recursive: true });
+    writeFileSync(join(phaseDir, "S01-T01-SUMMARY.md"), "---\nid: T01\n---\n# S01 T01\n");
+    writeFileSync(join(phaseDir, "S02-T01-SUMMARY.md"), "---\nid: T01\n---\n# S02 T01\n");
+
+    // S02/T02 prior summaries must not pull the sibling S01-T01 summary.
+    const paths = await getPriorTaskSummaryPaths("M001", "S02", "T02", repo);
+    assert.equal(paths.length, 1, "Should only return the current slice's prior summary");
+    assert.ok(paths[0].includes("S02-T01-SUMMARY"), "Should include S02's T01");
+    assert.ok(!paths.some((p) => p.includes("S01-T01-SUMMARY")), "Should NOT include sibling S01's T01");
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+  }
+});
+
+test("#1343: getDependencyTaskSummaryPaths excludes sibling-slice summaries in flat-phase", async () => {
+  const { getDependencyTaskSummaryPaths } = await import("../auto-prompts.ts");
+  const repo = mkdtempSync(join(tmpdir(), "gsd-reactive-flat-dep-"));
+  try {
+    const phaseDir = join(repo, ".gsd", "phases", "01-test");
+    mkdirSync(phaseDir, { recursive: true });
+    writeFileSync(join(phaseDir, "S01-T01-SUMMARY.md"), "---\nid: T01\n---\n# S01 T01\n");
+    writeFileSync(join(phaseDir, "S02-T01-SUMMARY.md"), "---\nid: T01\n---\n# S02 T01\n");
+
+    // S02/T02 depends on T01 — must resolve S02's T01, not the sibling S01's.
+    const paths = await getDependencyTaskSummaryPaths("M001", "S02", "T02", ["T01"], repo);
+    assert.equal(paths.length, 1, "Should only return the current slice's dependency summary");
+    assert.ok(paths[0].includes("S02-T01-SUMMARY"), "Should include S02's T01");
+    assert.ok(!paths.some((p) => p.includes("S01-T01-SUMMARY")), "Should NOT include sibling S01's T01");
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/reassess-handler.test.ts

@@ -210,6 +210,56 @@ test('handleReassessRoadmap succeeds when modifying only pending slices', async
   }
 });
 
+test('handleReassessRoadmap writes legacy-layout reassessment to S##-ASSESSMENT.md', async () => {
+  const base = mkdtempSync(join(tmpdir(), 'gsd-reassess-legacy-'));
+  mkdirSync(join(base, '.gsd', 'milestones', 'M005-3qxqd7', 'slices', 'S04'), { recursive: true });
+  mkdirSync(join(base, '.gsd', 'phases', '05-3qxqd7-legacy-milestone'), { recursive: true });
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    insertMilestone({ id: 'M005-3qxqd7', title: 'Legacy Milestone', status: 'active' });
+    insertSlice({
+      id: 'S04',
+      milestoneId: 'M005-3qxqd7',
+      title: 'Legacy Slice Four',
+      status: 'complete',
+      demo: 'Demo four.',
+    });
+
+    const result = await handleReassessRoadmap({
+      milestoneId: 'M005-3qxqd7',
+      completedSliceId: 'S04',
+      verdict: 'confirmed',
+      assessment: 'S04 completed successfully. Roadmap remains valid.',
+      sliceChanges: {
+        modified: [],
+        added: [],
+        removed: [],
+      },
+    }, base);
+
+    if ('error' in result) {
+      assert.fail(`unexpected error: ${result.error}`);
+    }
+
+    const correctPath = join(base, '.gsd', 'milestones', 'M005-3qxqd7', 'slices', 'S04', 'S04-ASSESSMENT.md');
+    const wrongFlatNameInLegacyDir = join(base, '.gsd', 'milestones', 'M005-3qxqd7', 'slices', 'S04', '05-04-ASSESSMENT.md');
+    const wrongFlatPhasePath = join(base, '.gsd', 'phases', '05-3qxqd7-legacy-milestone', '05-04-ASSESSMENT.md');
+    assert.match(
+      result.assessmentPath.replace(/\\/g, '/'),
+      /\/\.gsd\/milestones\/M005-3qxqd7\/slices\/S04\/S04-ASSESSMENT\.md$/,
+    );
+    assert.ok(existsSync(correctPath), 'legacy ASSESSMENT should use S## filename inside slices/S##/');
+    assert.equal(existsSync(wrongFlatNameInLegacyDir), false, 'legacy slice dir must not receive flat-phase assessment filename');
+    assert.equal(existsSync(wrongFlatPhasePath), false, 'legacy reassessment must not be diverted to a coexisting flat-phase dir');
+
+    const assessment = getAssessment('.gsd/milestones/M005-3qxqd7/slices/S04/S04-ASSESSMENT.md');
+    assert.ok(assessment, 'assessment row should use the legacy-layout path');
+  } finally {
+    cleanup(base);
+  }
+});
+
 test('handleReassessRoadmap cache invalidation: getMilestoneSlices reflects mutations', async () => {
   const base = makeTmpBase();
   openDatabase(join(base, '.gsd', 'gsd.db'));

package/src/resources/extensions/gsd/tests/replan-task-handler.test.ts

@@ -0,0 +1,103 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import {
+  openDatabase,
+  closeDatabase,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+  upsertTaskPlanning,
+  getTask,
+  getReplanHistory,
+} from '../gsd-db.ts';
+import { handleReplanTask } from '../tools/replan-task.ts';
+
+function makeTmpBase(): string {
+  const base = mkdtempSync(join(tmpdir(), 'gsd-replan-task-'));
+  mkdirSync(join(base, '.gsd', 'phases', '01-test'), { recursive: true });
+  return base;
+}
+
+function cleanup(base: string): void {
+  try { closeDatabase(); } catch { /* noop */ }
+  try { rmSync(base, { recursive: true, force: true }); } catch { /* noop */ }
+}
+
+function seedTask(status = 'pending'): void {
+  insertMilestone({ id: 'M001', title: 'Test Milestone', status: 'active' });
+  insertSlice({ id: 'S01', milestoneId: 'M001', title: 'Test Slice', status: 'active', demo: 'Demo.' });
+  insertTask({ id: 'T01', sliceId: 'S01', milestoneId: 'M001', title: 'Original Task', status });
+  upsertTaskPlanning('M001', 'S01', 'T01', {
+    description: 'Original task description.',
+    estimate: '30m',
+    files: ['src/original.ts'],
+    verify: 'node --test original.test.ts',
+    inputs: ['src/original.ts'],
+    expectedOutput: ['src/original.ts'],
+  });
+}
+
+function validReplanTaskParams() {
+  return {
+    milestoneId: 'M001',
+    sliceId: 'S01',
+    taskId: 'T01',
+    title: 'Replanned Task',
+    description: 'Updated task description with blocking rework scope.',
+    estimate: '45m',
+    files: ['src/replanned.ts'],
+    verify: 'node --test replanned.test.ts',
+    inputs: ['src/original.ts'],
+    expectedOutput: ['src/replanned.ts'],
+    reworkBriefRef: 'RB-001',
+  };
+}
+
+test('handleReplanTask updates one pending task plan and records a task-scoped replan history entry', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    seedTask('pending');
+
+    const result = await handleReplanTask(validReplanTaskParams(), base);
+    assert.ok(!('error' in result), `unexpected error: ${'error' in result ? result.error : ''}`);
+
+    const task = getTask('M001', 'S01', 'T01');
+    assert.ok(task, 'task should still exist');
+    assert.equal(task.title, 'Replanned Task');
+    assert.equal(task.description, 'Updated task description with blocking rework scope.');
+    assert.equal(task.verify, 'node --test replanned.test.ts');
+    assert.deepEqual(task.files, ['src/replanned.ts']);
+
+    const history = getReplanHistory('M001', 'S01');
+    assert.ok(history.some((row) => row['task_id'] === 'T01' && String(row['summary']).includes('RB-001')));
+
+    const planPath = join(base, '.gsd', 'phases', '01-test', '01-01-PLAN.md');
+    assert.ok(existsSync(planPath), 'slice plan projection should be rendered');
+    const planContent = readFileSync(planPath, 'utf-8');
+    assert.match(planContent, /Replanned Task/);
+    assert.match(planContent, /node --test replanned\.test\.ts/);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handleReplanTask rejects completed tasks', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    seedTask('complete');
+
+    const result = await handleReplanTask(validReplanTaskParams(), base);
+    assert.ok('error' in result);
+    assert.match(result.error, /cannot replan completed task T01/i);
+  } finally {
+    cleanup(base);
+  }
+});

package/src/resources/extensions/gsd/tests/rework-brief.test.ts

@@ -0,0 +1,197 @@
+import { createTestContext } from './test-helpers.ts';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {
+  openDatabase,
+  closeDatabase,
+  _getAdapter,
+  type ReworkBriefFindingInput,
+} from '../gsd-db.ts';
+import { handleReworkBriefSave } from '../tools/rework-brief.ts';
+
+const { assertEq, assertTrue, assertMatch, report } = createTestContext();
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Helpers
+// ═══════════════════════════════════════════════════════════════════════════
+
+function tempDbPath(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-rework-brief-'));
+  return path.join(dir, 'test.db');
+}
+
+function cleanup(dbPath: string): void {
+  closeDatabase();
+  try {
+    const dir = path.dirname(dbPath);
+    for (const f of fs.readdirSync(dir)) fs.unlinkSync(path.join(dir, f));
+    fs.rmdirSync(dir);
+  } catch {
+    // best effort
+  }
+}
+
+function finding(overrides: Partial<ReworkBriefFindingInput> = {}): ReworkBriefFindingInput {
+  return {
+    findingId: 'F1',
+    severity: 'blocking',
+    description: 'Compile regression',
+    requiredFix: 'Fix compile error',
+    verificationCommands: ['pnpm run typecheck:extensions'],
+    ...overrides,
+  };
+}
+
+const baseParams = {
+  briefId: 'RB-001',
+  milestoneId: 'M001',
+  sliceId: 'S01',
+  taskId: 'T01',
+};
+
+function findingRow(): { status: string; evidence: string; decision_ref: string } | undefined {
+  return _getAdapter()!
+    .prepare("SELECT status, evidence, decision_ref FROM rework_brief_findings WHERE brief_id = 'RB-001' AND finding_id = 'F1'")
+    .get() as { status: string; evidence: string; decision_ref: string } | undefined;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// rework-brief: a blocking finding saved as non-pending must carry the same
+// justification a reworkResolution would, otherwise it bypasses the
+// gsd_task_complete blocking gate (which only sees `pending` rows).
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== rework-brief: rejects blocking resolved finding without evidence ===');
+{
+  const dbPath = tempDbPath();
+  openDatabase(dbPath);
+
+  const result = await handleReworkBriefSave({
+    ...baseParams,
+    findings: [finding({ status: 'resolved' })],
+  });
+
+  assertTrue('error' in result, 'blocking resolved finding without evidence should be rejected');
+  if ('error' in result) {
+    assertMatch(result.error, /evidence is required/i, 'error should mention the evidence requirement');
+  }
+  const rows = _getAdapter()!.prepare('SELECT COUNT(*) AS n FROM rework_brief_findings').get() as { n: number };
+  assertEq(rows.n, 0, 'no finding rows should be persisted when validation fails');
+
+  cleanup(dbPath);
+}
+
+console.log('\n=== rework-brief: rejects blocking deferred-with-override without decisionRef ===');
+{
+  const dbPath = tempDbPath();
+  openDatabase(dbPath);
+
+  const result = await handleReworkBriefSave({
+    ...baseParams,
+    findings: [finding({ status: 'deferred-with-override', evidence: 'Maintainer accepted temporary deferral.' })],
+  });
+
+  assertTrue('error' in result, 'deferred-with-override without decisionRef should be rejected');
+  if ('error' in result) {
+    assertMatch(result.error, /decisionRef is required/i, 'error should mention the decisionRef requirement');
+  }
+
+  cleanup(dbPath);
+}
+
+console.log('\n=== rework-brief: rejects invalid finding status ===');
+{
+  const dbPath = tempDbPath();
+  openDatabase(dbPath);
+
+  const result = await handleReworkBriefSave({
+    ...baseParams,
+    findings: [finding({ status: 'bogus' as unknown as ReworkBriefFindingInput['status'] })],
+  });
+
+  assertTrue('error' in result, 'an unknown status value should be rejected');
+  if ('error' in result) {
+    assertMatch(result.error, /status must be/i, 'error should name the allowed statuses');
+  }
+
+  cleanup(dbPath);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// rework-brief: legitimate saves still succeed.
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== rework-brief: blocking finding defaults to pending ===');
+{
+  const dbPath = tempDbPath();
+  openDatabase(dbPath);
+
+  const result = await handleReworkBriefSave({
+    ...baseParams,
+    findings: [finding()],
+  });
+
+  assertTrue(!('error' in result), 'a blocking finding without a status should be accepted');
+  assertEq(findingRow()?.status, 'pending', 'finding without status should default to pending');
+
+  cleanup(dbPath);
+}
+
+console.log('\n=== rework-brief: accepts blocking resolved finding with evidence ===');
+{
+  const dbPath = tempDbPath();
+  openDatabase(dbPath);
+
+  const result = await handleReworkBriefSave({
+    ...baseParams,
+    findings: [finding({ status: 'resolved', evidence: 'Fixed compile error and reran pnpm run typecheck:extensions.' })],
+  });
+
+  assertTrue(!('error' in result), 'a resolved blocking finding with evidence should be accepted');
+  assertEq(findingRow()?.status, 'resolved', 'finding should persist as resolved when evidence is supplied');
+  assertMatch(findingRow()?.evidence ?? '', /Fixed compile error/, 'resolution evidence should be persisted');
+
+  cleanup(dbPath);
+}
+
+console.log('\n=== rework-brief: accepts blocking deferred-with-override with evidence and decisionRef ===');
+{
+  const dbPath = tempDbPath();
+  openDatabase(dbPath);
+
+  const result = await handleReworkBriefSave({
+    ...baseParams,
+    findings: [finding({
+      status: 'deferred-with-override',
+      evidence: 'Maintainer accepted temporary deferral.',
+      decisionRef: 'DEC-2026-07-07-rework-deferral',
+    })],
+  });
+
+  assertTrue(!('error' in result), 'a deferred-with-override finding with evidence and decisionRef should be accepted');
+  assertEq(findingRow()?.status, 'deferred-with-override', 'finding should persist the override status');
+  assertEq(findingRow()?.decision_ref, 'DEC-2026-07-07-rework-deferral', 'decision reference should be persisted');
+
+  cleanup(dbPath);
+}
+
+console.log('\n=== rework-brief: advisory resolved finding does not require evidence ===');
+{
+  const dbPath = tempDbPath();
+  openDatabase(dbPath);
+
+  // Advisory findings never gate gsd_task_complete, so pre-resolving one
+  // without evidence is harmless and stays permitted.
+  const result = await handleReworkBriefSave({
+    ...baseParams,
+    findings: [finding({ severity: 'advisory', status: 'resolved' })],
+  });
+
+  assertTrue(!('error' in result), 'an advisory resolved finding should be accepted without evidence');
+  assertEq(findingRow()?.status, 'resolved', 'advisory finding status should be preserved');
+
+  cleanup(dbPath);
+}
+
+report();

package/src/resources/extensions/gsd/tests/service-tier.test.ts

@@ -35,6 +35,10 @@ describe("supportsServiceTier", () => {
     assert.equal(supportsServiceTier("gpt-5.5"), false);
   });
 
+  test("returns false for gpt-5.6 until service_tier payload support is verified", () => {
+    assert.equal(supportsServiceTier("gpt-5.6"), false);
+  });
+
   test("returns false for provider-only identifier without gpt-5.4 model suffix", () => {
     assert.equal(supportsServiceTier("vibeproxy-openai"), false);
   });

package/src/resources/extensions/gsd/tests/single-writer-v3-tool-surface.test.ts

@@ -7,8 +7,9 @@
  *      self-identify (Stream 2: actor identity passthrough).
  *
  *   2. The 3 reversibility handlers (reopen-task/slice/milestone) are
- *      registered as MCP tools with both canonical and alias names
- *      (Stream 3: reversibility tools).
+ *      registered as MCP tools under their canonical names, and additionally
+ *      under their alias names when GSD_ADVERTISE_TOOL_ALIASES=1 (plan 035
+ *      suppresses alias schemas by default) (Stream 3: reversibility tools).
  *
  *   3. The reopen tools accept the documented core params plus optional
  *      reason/actorName/triggerReason without rejecting valid payloads.
@@ -36,6 +37,18 @@ function getTool(name: string) {
   return pi.tools.find((t: any) => t.name === name);
 }
 
+function withEnv(name: string, value: string | undefined, fn: () => void): void {
+  const previous = process.env[name];
+  if (value === undefined) delete process.env[name];
+  else process.env[name] = value;
+  try {
+    fn();
+  } finally {
+    if (previous === undefined) delete process.env[name];
+    else process.env[name] = previous;
+  }
+}
+
 function getRequiredProps(tool: any): string[] {
   return tool.parameters.required ?? [];
 }
@@ -78,7 +91,9 @@ for (const name of ACTOR_TOOLS) {
   });
 }
 
-// ─── Stream 3: reopen tools registered with canonical + alias names ─────────
+// ─── Stream 3: reopen tools registered under canonical names ────────────────
+// Plan 035 suppresses alias schemas by default; the canonical reopen tools are
+// always registered, and their aliases only when GSD_ADVERTISE_TOOL_ALIASES=1.
 
 const REOPEN_TOOLS = [
   { canonical: "gsd_task_reopen", alias: "gsd_reopen_task" },
@@ -87,13 +102,24 @@ const REOPEN_TOOLS = [
 ];
 
 for (const { canonical, alias } of REOPEN_TOOLS) {
-  test(`${canonical} — registered with alias ${alias}`, () => {
+  test(`${canonical} — registered under its canonical name, no alias by default`, () => {
     const canonicalTool = getTool(canonical);
-    const aliasTool = getTool(alias);
     assert.ok(canonicalTool, `${canonical} must be registered`);
-    assert.ok(aliasTool, `${alias} must be registered as alias`);
     assert.ok(typeof canonicalTool.execute === "function", `${canonical} must have an execute function`);
-    assert.ok(typeof aliasTool.execute === "function", `${alias} must have an execute function`);
+    assert.ok(!getTool(alias), `${alias} must not be registered by default (plan 035 alias suppression)`);
+  });
+
+  test(`${canonical} — registered with alias ${alias} when GSD_ADVERTISE_TOOL_ALIASES=1`, () => {
+    withEnv("GSD_ADVERTISE_TOOL_ALIASES", "1", () => {
+      const aliasPi = makeMockPi();
+      registerDbTools(aliasPi);
+      const canonicalTool = aliasPi.tools.find((t: any) => t.name === canonical);
+      const aliasTool = aliasPi.tools.find((t: any) => t.name === alias);
+      assert.ok(canonicalTool, `${canonical} must be registered`);
+      assert.ok(aliasTool, `${alias} must be registered as alias`);
+      assert.ok(typeof canonicalTool.execute === "function", `${canonical} must have an execute function`);
+      assert.ok(typeof aliasTool.execute === "function", `${alias} must have an execute function`);
+    });
   });
 }