gsd-pi 2.58.0 → 2.59.0-dev.023bd39

package/src/resources/extensions/gsd/tests/completion-hierarchy-guards.test.ts

@@ -0,0 +1,192 @@
+// GSD State Machine Regression Tests — Completion Hierarchy & State Derivation (#3161)
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  openDatabase,
+  closeDatabase,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+  getTask,
+  getSlice,
+  getMilestone,
+  getSliceTasks,
+  updateTaskStatus,
+  updateSliceStatus,
+} from "../gsd-db.ts";
+import { isClosedStatus } from "../status-guards.ts";
+
+// ─── Setup / Teardown ──────────────────────────────────────────────────────
+
+beforeEach(() => {
+  openDatabase(":memory:");
+});
+
+afterEach(() => {
+  try { closeDatabase(); } catch { /* swallow */ }
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Tests
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe("completion-hierarchy-guards", () => {
+
+  // ─── Test 1: isClosedStatus ─────────────────────────────────────────────
+  test("isClosedStatus returns true for 'complete' and 'done'", () => {
+    assert.ok(isClosedStatus("complete"), "'complete' should be closed");
+    assert.ok(isClosedStatus("done"), "'done' should be closed");
+    assert.ok(!isClosedStatus("pending"), "'pending' should not be closed");
+    assert.ok(!isClosedStatus("in-progress"), "'in-progress' should not be closed");
+    assert.ok(!isClosedStatus("blocked"), "'blocked' should not be closed");
+    assert.ok(!isClosedStatus(""), "empty string should not be closed");
+    assert.ok(!isClosedStatus("active"), "'active' should not be closed");
+  });
+
+  // ─── Test 2: vacuous truth guard — slice with zero tasks ───────────────
+  test("cannot complete slice with zero tasks — vacuous truth guard", () => {
+    insertMilestone({ id: "M001" });
+    insertSlice({ id: "S01", milestoneId: "M001" });
+
+    const tasks = getSliceTasks("M001", "S01");
+    assert.equal(tasks.length, 0, "newly inserted slice has zero tasks");
+
+    // The guard: a slice with no tasks is not completable.
+    // isSliceComplete from state.ts: plan.tasks.length > 0 && every done.
+    // Here we replicate the DB-side equivalent: zero tasks means guard fires.
+    const isCompletable = tasks.length > 0 && tasks.every(t => isClosedStatus(t.status));
+    assert.equal(isCompletable, false, "vacuous truth guard: zero tasks → not completable");
+  });
+
+  // ─── Test 3: cannot complete slice with incomplete tasks ─────────────────
+  test("cannot complete slice with incomplete tasks", () => {
+    insertMilestone({ id: "M001" });
+    insertSlice({ id: "S01", milestoneId: "M001" });
+    insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "done" });
+    insertTask({ id: "T02", sliceId: "S01", milestoneId: "M001", status: "pending" });
+
+    const tasks = getSliceTasks("M001", "S01");
+    assert.equal(tasks.length, 2, "slice has 2 tasks");
+
+    const incompleteTasks = tasks.filter(t => !isClosedStatus(t.status));
+    assert.equal(incompleteTasks.length, 1, "exactly one task is not closed");
+    assert.equal(incompleteTasks[0]?.id, "T02", "the incomplete task is T02");
+    assert.equal(incompleteTasks[0]?.status, "pending", "incomplete task status is 'pending'");
+  });
+
+  // ─── Test 4: phantom parent milestone and slice (H6) ────────────────────
+  test("task completion auto-creates phantom parent milestone and slice (H6)", () => {
+    // H6 finding: insertMilestone/insertSlice accept empty titles — phantom
+    // parents can be created without substantive content.
+    insertMilestone({ id: "M001" });
+    insertSlice({ id: "S01", milestoneId: "M001" });
+
+    const milestone = getMilestone("M001");
+    assert.ok(milestone !== null, "phantom milestone M001 should exist in DB");
+    assert.equal(milestone!.title, "", "phantom milestone has empty title by default");
+
+    const slice = getSlice("M001", "S01");
+    assert.ok(slice !== null, "phantom slice S01 should exist in DB");
+    assert.equal(slice!.title, "", "phantom slice has empty title by default");
+
+    // This documents the H6 finding: the DB allows phantom parents with
+    // no meaningful content, which can silently accept task completion calls.
+  });
+
+  // ─── Test 5: double task completion is detectable via isClosedStatus ────
+  test("double task completion is detectable via isClosedStatus", () => {
+    insertMilestone({ id: "M001" });
+    insertSlice({ id: "S01", milestoneId: "M001" });
+    insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", status: "done" });
+
+    const task = getTask("M001", "S01", "T01");
+    assert.ok(task !== null, "task T01 should exist");
+    assert.ok(
+      isClosedStatus(task!.status),
+      "isClosedStatus detects already-closed task — prevents double completion",
+    );
+
+    // The guard that prevents double completion: check isClosedStatus before
+    // calling updateTaskStatus again.
+    const wouldDoubleComplete = isClosedStatus(task!.status);
+    assert.ok(wouldDoubleComplete, "guard fires: task is already closed");
+  });
+
+  // ─── Test 6: updateSliceStatus rollback loses original status (M11) ─────
+  test("updateSliceStatus rollback goes to 'pending' not original status (M11)", () => {
+    insertMilestone({ id: "M001" });
+    // Insert with an explicit non-pending status to simulate an in-progress slice
+    insertSlice({ id: "S01", milestoneId: "M001", status: "pending" });
+
+    // Manually advance to "in_progress" equivalent via updateSliceStatus
+    updateSliceStatus("M001", "S01", "in_progress");
+    const afterProgress = getSlice("M001", "S01");
+    assert.equal(afterProgress!.status, "in_progress", "slice is in_progress after update");
+
+    // Simulate completion
+    updateSliceStatus("M001", "S01", "complete", new Date().toISOString());
+    const afterComplete = getSlice("M001", "S01");
+    assert.equal(afterComplete!.status, "complete", "slice is complete after completion");
+
+    // Simulate rollback — the DB only stores current status, not history.
+    // Rolling back means setting to "pending" — the original "in_progress" is lost.
+    updateSliceStatus("M001", "S01", "pending");
+    const afterRollback = getSlice("M001", "S01");
+    assert.equal(
+      afterRollback!.status,
+      "pending",
+      "M11: rollback sets status to 'pending', original 'in_progress' is lost",
+    );
+    // Document: there is no completed_at or status history to recover from.
+    // The rollback silently discards the in_progress state.
+  });
+
+  // ─── Test 7: milestone completion requires all slices closed ─────────────
+  test("milestone completion requires all slices closed", () => {
+    insertMilestone({ id: "M001" });
+    insertSlice({ id: "S01", milestoneId: "M001", status: "done" });
+    insertSlice({ id: "S02", milestoneId: "M001", status: "pending" });
+
+    const s01 = getSlice("M001", "S01");
+    const s02 = getSlice("M001", "S02");
+
+    assert.ok(s01 !== null, "S01 exists");
+    assert.ok(s02 !== null, "S02 exists");
+
+    const slices = [s01!, s02!];
+    const incompleteSlices = slices.filter(s => !isClosedStatus(s.status));
+    assert.ok(
+      incompleteSlices.length > 0,
+      "milestone is not completable — has incomplete slices",
+    );
+    assert.equal(incompleteSlices[0]?.id, "S02", "S02 is the incomplete slice");
+    assert.equal(incompleteSlices[0]?.status, "pending", "S02 status is 'pending'");
+  });
+
+  // ─── Test 8: closed parent blocks child completion ───────────────────────
+  test("closed parent blocks child completion", () => {
+    // Insert a milestone already in 'complete' state
+    insertMilestone({ id: "M001", status: "complete" });
+    insertSlice({ id: "S01", milestoneId: "M001" });
+
+    const milestone = getMilestone("M001");
+    assert.ok(milestone !== null, "milestone M001 exists");
+    assert.ok(
+      isClosedStatus(milestone!.status),
+      "parent milestone is closed — isClosedStatus returns true",
+    );
+
+    // The guard in complete-slice checks parent status via isClosedStatus.
+    // If isClosedStatus(milestone.status) === true, the child cannot be completed.
+    const parentIsClosed = isClosedStatus(milestone!.status);
+    assert.ok(parentIsClosed, "closed parent guard fires: milestone.status is 'complete'");
+
+    // Verify the slice itself is not yet closed
+    const slice = getSlice("M001", "S01");
+    assert.ok(slice !== null, "slice S01 exists");
+    assert.ok(!isClosedStatus(slice!.status), "slice S01 is not yet closed (parent is already closed)");
+  });
+
+});

package/src/resources/extensions/gsd/tests/complexity-classifier.test.ts

@@ -41,14 +41,14 @@ test("research-slice classifies as standard", () => {
   assert.equal(result.tier, "standard");
 });
 
-test("plan-milestone classifies as standard", () => {
+test("plan-milestone classifies as heavy", () => {
   const result = classifyUnitComplexity("plan-milestone", "M001", "/tmp/fake");
-  assert.equal(result.tier, "standard");
+  assert.equal(result.tier, "heavy");
 });
 
-test("plan-slice classifies as standard", () => {
+test("plan-slice classifies as heavy", () => {
   const result = classifyUnitComplexity("plan-slice", "M001/S01", "/tmp/fake");
-  assert.equal(result.tier, "standard");
+  assert.equal(result.tier, "heavy");
 });
 
 test("replan-slice classifies as heavy", () => {

package/src/resources/extensions/gsd/tests/db-path-worktree-symlink.test.ts

@@ -0,0 +1,131 @@
+/**
+ * db-path-worktree-symlink.test.ts — #2517
+ *
+ * Regression test for the db_unavailable loop in worktree/symlink layouts.
+ *
+ * The path resolver must handle BOTH worktree path families:
+ *   - /.gsd/worktrees/<MID>/...           (direct layout)
+ *   - /.gsd/projects/<hash>/worktrees/<MID>/...  (symlink-resolved layout)
+ *
+ * When the second layout is not recognised, ensureDbOpen derives a wrong DB
+ * path, the open fails silently, and every completion tool call returns
+ * db_unavailable — triggering an artifact retry re-dispatch loop.
+ *
+ * Additionally, the post-unit artifact retry path must NOT retry when the
+ * completion tool failed due to db_unavailable (infra failure), because
+ * retrying can never succeed and causes cost spikes.
+ */
+
+import { readFileSync } from "node:fs";
+import { join, sep } from "node:path";
+import { createTestContext } from "./test-helpers.ts";
+
+const { assertEq, assertTrue, report } = createTestContext();
+
+// ── Part 1: resolveProjectRootDbPath handles symlink-resolved layout ─────
+
+console.log("\n=== #2517 Part 1: resolveProjectRootDbPath symlink layout ===");
+
+// Import the resolver directly
+const { resolveProjectRootDbPath } = await import("../bootstrap/dynamic-tools.js");
+
+// Standard worktree layout (already works)
+const standardPath = `/home/user/myproject/.gsd/worktrees/M001/work`;
+const standardResult = resolveProjectRootDbPath(standardPath);
+assertEq(
+  standardResult,
+  join("/home/user/myproject", ".gsd", "gsd.db"),
+  "Standard worktree layout resolves to project root DB path",
+);
+
+// Symlink-resolved layout (the regression — /.gsd/projects/<hash>/worktrees/...)
+const symlinkPath = `/home/user/myproject/.gsd/projects/abc123def/worktrees/M001/work`;
+const symlinkResult = resolveProjectRootDbPath(symlinkPath);
+assertEq(
+  symlinkResult,
+  join("/home/user/myproject", ".gsd", "gsd.db"),
+  "Symlink-resolved layout (/.gsd/projects/<hash>/worktrees/) resolves to project root DB path (#2517)",
+);
+
+// Windows-style separators for symlink layout
+if (sep === "\\") {
+  const winSymlinkPath = `C:\\Users\\dev\\project\\.gsd\\projects\\abc123def\\worktrees\\M001\\work`;
+  const winResult = resolveProjectRootDbPath(winSymlinkPath);
+  assertEq(
+    winResult,
+    join("C:\\Users\\dev\\project", ".gsd", "gsd.db"),
+    "Windows symlink layout resolves correctly",
+  );
+} else {
+  // On non-Windows, test forward-slash variant explicitly
+  const fwdSymlinkPath = `/home/user/myproject/.gsd/projects/abc123def/worktrees/M001/work`;
+  const fwdResult = resolveProjectRootDbPath(fwdSymlinkPath);
+  assertEq(
+    fwdResult,
+    join("/home/user/myproject", ".gsd", "gsd.db"),
+    "Forward-slash symlink layout resolves correctly on POSIX",
+  );
+}
+
+// Edge: deeper nesting under projects/<hash>/worktrees
+const deepSymlinkPath = `/home/user/myproject/.gsd/projects/deadbeef42/worktrees/M003/sub/dir`;
+const deepResult = resolveProjectRootDbPath(deepSymlinkPath);
+assertEq(
+  deepResult,
+  join("/home/user/myproject", ".gsd", "gsd.db"),
+  "Deep symlink worktree path still resolves to project root DB",
+);
+
+// Non-worktree path should be unchanged
+const normalPath = `/home/user/myproject`;
+const normalResult = resolveProjectRootDbPath(normalPath);
+assertEq(
+  normalResult,
+  join("/home/user/myproject", ".gsd", "gsd.db"),
+  "Non-worktree path is unchanged",
+);
+
+// ── Part 2: ensureDbOpen returns structured failure context ──────────────
+
+console.log("\n=== #2517 Part 2: ensureDbOpen structured diagnostics ===");
+
+const dynamicToolsSrc = readFileSync(
+  join(import.meta.dirname, "..", "bootstrap", "dynamic-tools.ts"),
+  "utf-8",
+);
+
+// ensureDbOpen should return a structured result, not just boolean false
+// Check that the catch block provides diagnostic information
+assertTrue(
+  dynamicToolsSrc.includes("resolvedPath") || dynamicToolsSrc.includes("diagnostic"),
+  "ensureDbOpen catch block surfaces diagnostic information (resolvedPath or diagnostic) instead of bare false (#2517)",
+);
+
+// ── Part 3: post-unit does NOT artifact-retry on db_unavailable ──────────
+
+console.log("\n=== #2517 Part 3: post-unit db_unavailable is infra-fatal ===");
+
+const postUnitSrc = readFileSync(
+  join(import.meta.dirname, "..", "auto-post-unit.ts"),
+  "utf-8",
+);
+
+// The artifact retry block should check DB availability and skip retry
+// when the DB is unavailable (infra failure, not a missing artifact).
+assertTrue(
+  postUnitSrc.includes("db_unavailable") || postUnitSrc.includes("isDbAvailable"),
+  "post-unit artifact retry path checks DB availability to avoid retry loop (#2517)",
+);
+
+// Verify the retry block is guarded: when !isDbAvailable(), the code must
+// NOT return "retry". The pattern should be: if (!verified && !isDbAvailable()) { skip }
+// followed by else if (!verified) { ... return "retry" }
+const dbUnavailableGuard = postUnitSrc.match(
+  /!triggerArtifactVerified\s*&&\s*!isDbAvailable\(\)/,
+);
+assertTrue(
+  !!dbUnavailableGuard,
+  "The retry block explicitly guards against !isDbAvailable() before returning 'retry' (#2517)",
+);
+
+report();

package/src/resources/extensions/gsd/tests/db-writer.test.ts

@@ -416,23 +416,18 @@ describe('db-writer', () => {
     }
   });
 
-  test('updateRequirementInDb — not found', async () => {
+  test('updateRequirementInDb — upserts when not found (#2919)', async () => {
     const tmpDir = makeTmpDir();
     const dbPath = path.join(tmpDir, '.gsd', 'gsd.db');
     openDatabase(dbPath);
 
     try {
-      let threw = false;
-      try {
-        await updateRequirementInDb('R999', { status: 'validated' }, tmpDir);
-      } catch (err) {
-        threw = true;
-        assert.ok(
-          (err as Error).message.includes('R999'),
-          'error message mentions the missing ID',
-        );
-      }
-      assert.ok(threw, 'throws when requirement not found');
+      // Previously threw; now upserts a skeleton requirement with the provided updates
+      await updateRequirementInDb('R999', { status: 'validated' }, tmpDir);
+      const created = getRequirementById('R999');
+      assert.ok(created !== null, 'R999 should be created by upsert');
+      assert.deepStrictEqual(created!.status, 'validated', 'Upserted requirement should have validated status');
+      assert.deepStrictEqual(created!.id, 'R999', 'Upserted requirement should keep the provided ID');
     } finally {
       closeDatabase();
       cleanupDir(tmpDir);

package/src/resources/extensions/gsd/tests/derive-state-db.test.ts

@@ -4,7 +4,7 @@ import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 
-import { deriveState, invalidateStateCache, _deriveStateImpl, deriveStateFromDb } from '../state.ts';
+import { deriveState, invalidateStateCache, _deriveStateImpl, deriveStateFromDb, isGhostMilestone } from '../state.ts';
 import {
   openDatabase,
   closeDatabase,
@@ -934,8 +934,8 @@ describe('derive-state-db', async () => {
     }
   });
 
-  // ─── Test 21: Ghost milestone skipped ─────────────────────────────────
-  test('derive-state-db: ghost milestone skipped', async () => {
+  // ─── Test 21: Ghost milestone skipped (no DB row, no worktree) ─────────
+  test('derive-state-db: ghost milestone skipped when no DB row and no worktree', async () => {
     const base = createFixtureBase();
     try {
       // Ghost: milestone dir exists with only META.json, no context/roadmap/summary
@@ -948,8 +948,7 @@ describe('derive-state-db', async () => {
       const fileState = await _deriveStateImpl(base);
 
       openDatabase(':memory:');
-      // Ghost milestone in DB — no slices, status active
-      insertMilestone({ id: 'M001', title: '', status: 'active' });
+      // Only insert M002 — M001 has no DB row (simulates row loss / never inserted)
       insertMilestone({ id: 'M002', title: 'Real', status: 'active' });
 
       invalidateStateCache();
@@ -1051,4 +1050,78 @@ describe('derive-state-db', async () => {
       closeDatabase();
     }
   });
+
+  // ─── Queued milestone with worktree not flagged as ghost (#2921) ──────
+  test('derive-state-db: queued milestone with worktree not flagged as ghost (#2921)', async () => {
+    const base = createFixtureBase();
+    try {
+      // M001: complete milestone with summary
+      writeFile(base, 'milestones/M001/M001-SUMMARY.md', '# M001 Summary\n\nDone.');
+
+      // M002: queued milestone — directory + slices dir exists, but no content files.
+      // This is what happens when ensureMilestoneDbRow creates M002 but the DB row
+      // is lost during worktree teardown.
+      mkdirSync(join(base, '.gsd', 'milestones', 'M002', 'slices'), { recursive: true });
+
+      // A worktree exists for M002, proving it's a legitimate milestone
+      mkdirSync(join(base, '.gsd', 'worktrees', 'M002'), { recursive: true });
+
+      // isGhostMilestone should NOT treat M002 as ghost when worktree exists
+      assert.ok(!isGhostMilestone(base, 'M002'), 'ghost-wt: M002 with worktree is NOT a ghost');
+
+      // DB has M001 complete but M002 row was lost
+      openDatabase(':memory:');
+      insertMilestone({ id: 'M001', title: 'First', status: 'complete' });
+      // No M002 row — simulates DB row loss during worktree teardown
+
+      invalidateStateCache();
+      const dbState = await deriveStateFromDb(base);
+
+      // M002 should be reconciled from disk (not skipped as ghost) and become active
+      const m002Entry = dbState.registry.find(e => e.id === 'M002');
+      assert.ok(m002Entry !== undefined, 'ghost-wt: M002 should be in registry');
+      assert.deepStrictEqual(dbState.activeMilestone?.id, 'M002', 'ghost-wt: M002 should be active');
+      // Should NOT be phase: complete
+      assert.notEqual(dbState.phase, 'complete', 'ghost-wt: phase should not be complete');
+
+      closeDatabase();
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
+
+  // ─── Queued milestone with DB row not flagged as ghost (#2921) ────────
+  test('derive-state-db: queued milestone with DB row not flagged as ghost (#2921)', async () => {
+    const base = createFixtureBase();
+    try {
+      // M001: complete milestone with summary
+      writeFile(base, 'milestones/M001/M001-SUMMARY.md', '# M001 Summary\n\nDone.');
+
+      // M002: queued milestone — directory exists, no content files, but has DB row
+      mkdirSync(join(base, '.gsd', 'milestones', 'M002', 'slices'), { recursive: true });
+
+      // DB has both M001 complete and M002 queued
+      openDatabase(':memory:');
+      insertMilestone({ id: 'M001', title: 'First', status: 'complete' });
+      insertMilestone({ id: 'M002', title: 'Second', status: 'queued' });
+
+      // isGhostMilestone should NOT treat M002 as ghost when DB row exists
+      assert.ok(!isGhostMilestone(base, 'M002'), 'ghost-dbrow: M002 with DB row is NOT a ghost');
+
+      invalidateStateCache();
+      const dbState = await deriveStateFromDb(base);
+
+      // M002 should not be skipped
+      const m002Entry = dbState.registry.find(e => e.id === 'M002');
+      assert.ok(m002Entry !== undefined, 'ghost-dbrow: M002 should be in registry');
+      assert.deepStrictEqual(dbState.activeMilestone?.id, 'M002', 'ghost-dbrow: M002 should be active');
+      assert.notEqual(dbState.phase, 'complete', 'ghost-dbrow: phase should not be complete');
+
+      closeDatabase();
+    } finally {
+      closeDatabase();
+      cleanup(base);
+    }
+  });
 });

package/src/resources/extensions/gsd/tests/derive-state.test.ts

@@ -930,6 +930,35 @@ slice: S01
     }
   });
 
+  // ─── Test: queued milestone with worktree not flagged as ghost (#2921) ──
+  test('queued milestone with worktree not flagged as ghost (#2921)', async () => {
+    const base = createFixtureBase();
+    try {
+      // Create a milestone directory with only an empty slices subdir — no content files.
+      // This would normally be a ghost, but it has a worktree directory.
+      const milestoneDir = join(base, '.gsd', 'milestones', 'M002');
+      mkdirSync(join(milestoneDir, 'slices'), { recursive: true });
+
+      // Create a worktree directory for M002, simulating an active worktree
+      const worktreeDir = join(base, '.gsd', 'worktrees', 'M002');
+      mkdirSync(worktreeDir, { recursive: true });
+
+      // isGhostMilestone should return false because the worktree exists
+      assert.ok(!isGhostMilestone(base, 'M002'), 'M002 with worktree should NOT be a ghost');
+
+      // Also create a completed M001 so deriveState has something before M002
+      writeMilestoneSummary(base, 'M001', '# M001 Summary\n\nDone.');
+
+      const state = await deriveState(base);
+      // M002 should appear in the registry (not filtered as ghost)
+      const m002Entry = state.registry.find(e => e.id === 'M002');
+      assert.ok(m002Entry !== undefined, 'M002 should be in registry when worktree exists');
+      assert.deepStrictEqual(state.activeMilestone?.id, 'M002', 'M002 should be active milestone');
+    } finally {
+      cleanup(base);
+    }
+  });
+
   // ─── Test: zero-slice roadmap → pre-planning, not blocked (#1785) ────
   test('zero-slice roadmap → pre-planning, not blocked (#1785)', async () => {
     const base = createFixtureBase();

package/src/resources/extensions/gsd/tests/discord-invite-links.test.ts

@@ -0,0 +1,47 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Validates that all Discord invite links in user-facing files point to valid,
+ * consistent invite URLs — not expired vanity links.
+ *
+ * Regression test for https://github.com/gsd-build/gsd-2/issues/2699
+ */
+
+const ROOT = process.cwd();
+
+/** Canonical Discord invite for the GSD community. */
+const VALID_INVITE = "https://discord.com/invite/nKXTsAcmbT";
+
+/** Files that contain user-facing Discord invite links. */
+const FILES_WITH_INVITE_LINKS: string[] = [
+  "README.md",
+  "docs/what-is-pi/15-pi-packages-the-ecosystem.md",
+];
+
+describe("Discord invite links (#2699)", () => {
+  for (const relPath of FILES_WITH_INVITE_LINKS) {
+    it(`${relPath} contains only the canonical Discord invite`, () => {
+      const content = readFileSync(join(ROOT, relPath), "utf8");
+
+      // Extract all Discord invite URLs (discord.gg/X or discord.com/invite/X)
+      const invitePattern = /https?:\/\/(?:discord\.gg|discord\.com\/invite)\/[A-Za-z0-9]+/g;
+      const matches = content.match(invitePattern);
+
+      assert.ok(
+        matches && matches.length > 0,
+        `Expected at least one Discord invite link in ${relPath}`,
+      );
+
+      for (const link of matches) {
+        assert.equal(
+          link,
+          VALID_INVITE,
+          `Invalid Discord invite in ${relPath}: found "${link}", expected "${VALID_INVITE}"`,
+        );
+      }
+    });
+  }
+});