gsd-pi 2.72.0 → 2.73.0-dev.27730dc

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

@@ -18,6 +18,11 @@ import {
   transaction,
   _getAdapter,
   _resetProvider,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+  getTask,
+  getSliceTasks,
 } from '../gsd-db.ts';
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -43,6 +48,16 @@ function cleanup(dbPath: string): void {
   }
 }
 
+function withPlatform<T>(platform: NodeJS.Platform, fn: () => T): T {
+  const original = process.platform;
+  Object.defineProperty(process, 'platform', { value: platform });
+  try {
+    return fn();
+  } finally {
+    Object.defineProperty(process, 'platform', { value: original });
+  }
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // gsd-db tests
 // ═══════════════════════════════════════════════════════════════════════════
@@ -279,6 +294,26 @@ describe('gsd-db', () => {
     cleanup(dbPath);
   });
 
+  test('gsd-db: mmap stays disabled on darwin file-backed DBs', () => {
+    const darwinDbPath = tempDbPath();
+    withPlatform('darwin', () => {
+      openDatabase(darwinDbPath);
+      const adapter = _getAdapter()!;
+      const mmap = adapter.prepare('PRAGMA mmap_size').get();
+      assert.deepStrictEqual(mmap?.['mmap_size'], 0, 'darwin should leave mmap_size disabled');
+      cleanup(darwinDbPath);
+    });
+
+    const linuxDbPath = tempDbPath();
+    withPlatform('linux', () => {
+      openDatabase(linuxDbPath);
+      const adapter = _getAdapter()!;
+      const mmap = adapter.prepare('PRAGMA mmap_size').get();
+      assert.deepStrictEqual(mmap?.['mmap_size'], 67108864, 'non-darwin should still enable mmap_size');
+      cleanup(linuxDbPath);
+    });
+  });
+
   test('gsd-db: transaction rollback on error', () => {
     openDatabase(':memory:');
 
@@ -329,6 +364,79 @@ describe('gsd-db', () => {
     closeDatabase();
   });
 
+  test('gsd-db: recreates missing verification evidence dedup index after removing duplicate rows', () => {
+    const dbPath = tempDbPath();
+    openDatabase(dbPath);
+
+    let adapter = _getAdapter()!;
+    adapter.prepare("INSERT INTO milestones (id, created_at) VALUES (?, '')").run('M001');
+    adapter.prepare("INSERT INTO slices (milestone_id, id, created_at) VALUES (?, ?, '')").run('M001', 'S01');
+    adapter.prepare("INSERT INTO tasks (milestone_id, slice_id, id) VALUES (?, ?, ?)").run('M001', 'S01', 'T01');
+    adapter.exec('DROP INDEX IF EXISTS idx_verification_evidence_dedup');
+
+    const insertEvidence = adapter.prepare(
+      `INSERT INTO verification_evidence (
+        task_id, slice_id, milestone_id, command, exit_code, verdict, duration_ms, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+    insertEvidence.run('T01', 'S01', 'M001', 'npm test', 1, 'fail', 125, '2026-04-12T00:00:00.000Z');
+    insertEvidence.run('T01', 'S01', 'M001', 'npm test', 1, 'fail', 125, '2026-04-12T00:00:01.000Z');
+    insertEvidence.run('T01', 'S01', 'M001', 'npm run lint', 0, 'pass', 90, '2026-04-12T00:00:02.000Z');
+
+    closeDatabase();
+
+    assert.equal(openDatabase(dbPath), true, 'openDatabase should repair legacy duplicate evidence rows');
+
+    adapter = _getAdapter()!;
+    const countRow = adapter.prepare(
+      `SELECT count(*) as cnt
+       FROM verification_evidence
+       WHERE task_id = ? AND slice_id = ? AND milestone_id = ? AND command = ? AND verdict = ?`,
+    ).get('T01', 'S01', 'M001', 'npm test', 'fail');
+    assert.equal(countRow?.['cnt'], 1, 'duplicate verification evidence rows should be deduplicated before index creation');
+
+    const indexRow = adapter.prepare(
+      "SELECT name FROM sqlite_master WHERE type = 'index' AND name = 'idx_verification_evidence_dedup'",
+    ).get();
+    assert.equal(indexRow?.['name'], 'idx_verification_evidence_dedup', 'dedup index should be recreated on reopen');
+
+    cleanup(dbPath);
+  });
+
+  test('gsd-db: rowToTask tolerates legacy comma-separated task arrays', () => {
+    openDatabase(':memory:');
+
+    const adapter = _getAdapter()!;
+    adapter.prepare("INSERT INTO milestones (id, created_at) VALUES (?, '')").run('M001');
+    adapter.prepare("INSERT INTO slices (milestone_id, id, created_at) VALUES (?, ?, '')").run('M001', 'S01');
+    adapter.prepare(
+      `INSERT INTO tasks (
+        milestone_id, slice_id, id, key_files, key_decisions, files, inputs, expected_output
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(
+      'M001',
+      'S01',
+      'T01',
+      '[]',
+      '[]',
+      'tests/test_verify.py, config.yaml, configs/roster_2026-05-11.yaml',
+      'tests/test_verify.py',
+      'reports/summary.md, artifacts/output.json',
+    );
+
+    const task = getTask('M001', 'S01', 'T01');
+    assert.ok(task, 'task should load successfully from DB');
+    assert.deepEqual(task?.files, [
+      'tests/test_verify.py',
+      'config.yaml',
+      'configs/roster_2026-05-11.yaml',
+    ]);
+    assert.deepEqual(task?.inputs, ['tests/test_verify.py']);
+    assert.deepEqual(task?.expected_output, ['reports/summary.md', 'artifacts/output.json']);
+
+    closeDatabase();
+  });
+
   test('gsd-db: query wrappers return null/empty when DB unavailable', () => {
     // Ensure DB is closed
     closeDatabase();
@@ -347,15 +455,67 @@ describe('gsd-db', () => {
     assert.deepStrictEqual(ar, [], 'getActiveRequirements returns [] when DB closed');
   });
 
-  test('gsd-db: wasDbOpenAttempted tracks openDatabase calls', () => {
-    // wasDbOpenAttempted should return true once openDatabase has been called
-    // (previous tests in this suite already called openDatabase, so the flag is set)
+  test('gsd-db: closeDatabase resets wasDbOpenAttempted after an intentional close', () => {
+    openDatabase(':memory:');
     assert.ok(wasDbOpenAttempted(), 'wasDbOpenAttempted should be true after openDatabase was called');
 
-    // Verify the flag persists even after closeDatabase
     closeDatabase();
     assert.ok(!isDbAvailable(), 'DB should not be available after close');
-    assert.ok(wasDbOpenAttempted(), 'wasDbOpenAttempted should remain true after closeDatabase');
+    assert.ok(!wasDbOpenAttempted(), 'wasDbOpenAttempted should reset after closeDatabase');
+  });
+
+  test('gsd-db: rowToTask tolerates corrupt comma-separated task arrays', () => {
+    openDatabase(':memory:');
+    insertMilestone({ id: 'M001', status: 'active' });
+    insertSlice({ milestoneId: 'M001', id: 'S01', status: 'active' });
+    insertTask({
+      milestoneId: 'M001',
+      sliceId: 'S01',
+      id: 'T01',
+      title: 'Recover corrupt arrays',
+      planning: {
+        description: 'desc',
+        estimate: 'small',
+        files: ['src/original.ts'],
+        verify: 'npm test',
+        inputs: ['docs/original.md'],
+        expectedOutput: ['dist/original.md'],
+        observabilityImpact: '',
+      },
+    });
+
+    const adapter = _getAdapter()!;
+    adapter.prepare(
+      `UPDATE tasks
+         SET files = ?, inputs = ?, expected_output = ?, key_files = ?, key_decisions = ?
+       WHERE milestone_id = ? AND slice_id = ? AND id = ?`,
+    ).run(
+      'src-erf/Models/foo.cs, src-erf/Models/bar.cs',
+      'docs/input-a.md, docs/input-b.md',
+      'dist/out-a.md, dist/out-b.md',
+      'src/resources/extensions/gsd/gsd-db.ts, src/resources/extensions/gsd/state.ts',
+      '"decision-1"',
+      'M001',
+      'S01',
+      'T01',
+    );
+
+    const task = getTask('M001', 'S01', 'T01');
+    assert.ok(task, 'getTask should still return the corrupt row');
+    assert.deepStrictEqual(task!.files, ['src-erf/Models/foo.cs', 'src-erf/Models/bar.cs']);
+    assert.deepStrictEqual(task!.inputs, ['docs/input-a.md', 'docs/input-b.md']);
+    assert.deepStrictEqual(task!.expected_output, ['dist/out-a.md', 'dist/out-b.md']);
+    assert.deepStrictEqual(
+      task!.key_files,
+      ['src/resources/extensions/gsd/gsd-db.ts', 'src/resources/extensions/gsd/state.ts'],
+    );
+    assert.deepStrictEqual(task!.key_decisions, ['decision-1']);
+
+    const sliceTasks = getSliceTasks('M001', 'S01');
+    assert.equal(sliceTasks.length, 1, 'getSliceTasks should also survive corrupt rows');
+    assert.deepStrictEqual(sliceTasks[0]!.files, task!.files);
+
+    closeDatabase();
   });
 
   // ─── Final Report ──────────────────────────────────────────────────────────

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

@@ -248,23 +248,25 @@ describe('git-service', async () => {
 
   assert.deepStrictEqual(
     RUNTIME_EXCLUSION_PATHS.length,
-    13,
-    "exactly 13 runtime exclusion paths"
+    15,
+    "exactly 15 runtime exclusion paths"
   );
 
   const expectedPaths = [
     ".gsd/activity/",
+    ".gsd/forensics/",
     ".gsd/runtime/",
     ".gsd/worktrees/",
+    ".gsd/parallel/",
     ".gsd/auto.lock",
     ".gsd/metrics.json",
-    ".gsd/completed-units.json",
+    ".gsd/completed-units*.json",
+    ".gsd/state-manifest.json",
     ".gsd/STATE.md",
-    ".gsd/gsd.db",
-    ".gsd/gsd.db-shm",
-    ".gsd/gsd.db-wal",
+    ".gsd/gsd.db*",
     ".gsd/journal/",
     ".gsd/doctor-history.jsonl",
+    ".gsd/event-log.jsonl",
     ".gsd/DISCUSSION-MANIFEST.json",
   ];
 

package/src/resources/extensions/gsd/tests/key-manager.test.ts

@@ -427,3 +427,66 @@ test("formatDoctorFindings shows findings with appropriate icons", () => {
   assert.ok(output.includes("1 warning"));
   assert.ok(output.includes("1 fixed"));
 });
+
+// ─── Regression #3891 — alibaba-coding-plan missing from PROVIDER_REGISTRY ───────
+//
+// Before this fix, `alibaba-coding-plan` was not in PROVIDER_REGISTRY, causing
+// `/gsd keys add alibaba-coding-plan` to silently fail (provider not found).
+// alibaba-dashscope is the new standalone provider added in the same PR.
+
+test("regression #3891 — alibaba-coding-plan is in PROVIDER_REGISTRY", () => {
+  const provider = findProvider("alibaba-coding-plan");
+  assert.ok(provider, "alibaba-coding-plan must be in PROVIDER_REGISTRY for /gsd keys add to work");
+  assert.equal(provider.id, "alibaba-coding-plan");
+  assert.equal(provider.category, "llm");
+  assert.equal(provider.envVar, "ALIBABA_API_KEY");
+});
+
+test("alibaba-dashscope is in PROVIDER_REGISTRY", () => {
+  const provider = findProvider("alibaba-dashscope");
+  assert.ok(provider, "alibaba-dashscope must be in PROVIDER_REGISTRY for /gsd keys add to work");
+  assert.equal(provider.id, "alibaba-dashscope");
+  assert.equal(provider.category, "llm");
+  assert.equal(provider.envVar, "DASHSCOPE_API_KEY");
+});
+
+test("alibaba-coding-plan and alibaba-dashscope are separate providers (different env vars)", () => {
+  const codingPlan = findProvider("alibaba-coding-plan");
+  const dashscope = findProvider("alibaba-dashscope");
+  assert.ok(codingPlan, "alibaba-coding-plan must exist");
+  assert.ok(dashscope, "alibaba-dashscope must exist");
+  assert.notEqual(
+    codingPlan.envVar,
+    dashscope.envVar,
+    "alibaba-coding-plan and alibaba-dashscope must use different env vars",
+  );
+});
+
+test("getAllKeyStatuses includes alibaba-coding-plan", () => {
+  const auth = makeAuth();
+  const statuses = getAllKeyStatuses(auth);
+  const found = statuses.find((s) => s.provider.id === "alibaba-coding-plan");
+  assert.ok(found, "getAllKeyStatuses must include alibaba-coding-plan");
+});
+
+test("getAllKeyStatuses includes alibaba-dashscope", () => {
+  const auth = makeAuth();
+  const statuses = getAllKeyStatuses(auth);
+  const found = statuses.find((s) => s.provider.id === "alibaba-dashscope");
+  assert.ok(found, "getAllKeyStatuses must include alibaba-dashscope");
+});
+
+test("getAllKeyStatuses detects DASHSCOPE_API_KEY for alibaba-dashscope (failure path: missing key shows not configured)", () => {
+  const saved = process.env.DASHSCOPE_API_KEY;
+  delete process.env.DASHSCOPE_API_KEY;
+  try {
+    const auth = makeAuth();
+    const statuses = getAllKeyStatuses(auth);
+    const found = statuses.find((s) => s.provider.id === "alibaba-dashscope");
+    assert.ok(found);
+    assert.equal(found.configured, false);
+    assert.equal(found.source, "none");
+  } finally {
+    if (saved !== undefined) process.env.DASHSCOPE_API_KEY = saved;
+  }
+});

package/src/resources/extensions/gsd/tests/memory-pressure-stuck-state.test.ts

@@ -0,0 +1,54 @@
+/**
+ * Regression tests for memory pressure monitoring (#3331) and
+ * stuck detection persistence (#3704) in auto/loop.ts.
+ */
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const loopSource = readFileSync(join(__dirname, "..", "auto", "loop.ts"), "utf-8");
+
+describe("memory pressure monitoring (#3331)", () => {
+  test("checkMemoryPressure function exists", () => {
+    assert.match(loopSource, /function checkMemoryPressure/);
+  });
+
+  test("MEMORY_PRESSURE_THRESHOLD constant is defined", () => {
+    assert.match(loopSource, /MEMORY_PRESSURE_THRESHOLD\s*=\s*0\.\d+/);
+  });
+
+  test("memory check runs every MEMORY_CHECK_INTERVAL iterations", () => {
+    assert.match(loopSource, /iteration\s*%\s*MEMORY_CHECK_INTERVAL\s*===\s*0/);
+  });
+
+  test("memory pressure triggers graceful stopAuto", () => {
+    assert.match(loopSource, /mem\.pressured/);
+    assert.match(loopSource, /Stopping gracefully to prevent OOM/);
+  });
+});
+
+describe("stuck detection persistence (#3704)", () => {
+  test("loadStuckState function exists", () => {
+    assert.match(loopSource, /function loadStuckState/);
+  });
+
+  test("saveStuckState function exists", () => {
+    assert.match(loopSource, /function saveStuckState/);
+  });
+
+  test("loopState initialized from persisted state", () => {
+    assert.match(loopSource, /loadStuckState\(s\.basePath\)/);
+  });
+
+  test("stuck state saved after each iteration", () => {
+    assert.match(loopSource, /saveStuckState\(s\.basePath,\s*loopState\)/);
+  });
+
+  test("stuck state file path uses runtime directory", () => {
+    assert.match(loopSource, /stuck-state\.json/);
+  });
+});

package/src/resources/extensions/gsd/tests/park-milestone.test.ts

@@ -3,10 +3,22 @@ import assert from 'node:assert/strict';
 import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
+import { execSync } from 'node:child_process';
 
 import { deriveState, invalidateStateCache, getActiveMilestoneId } from '../state.ts';
 import { clearPathCache } from '../paths.ts';
 import { parkMilestone, unparkMilestone, discardMilestone, isParked, getParkedReason } from '../milestone-actions.ts';
+import {
+  closeDatabase,
+  getMilestone,
+  getMilestoneSlices,
+  getSliceTasks,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+  openDatabase,
+} from "../gsd-db.ts";
+import { createWorktree } from "../worktree-manager.ts";
 
 
 
@@ -60,9 +72,29 @@ function createMilestone(base: string, mid: string, opts?: { withRoadmap?: boole
 }
 
 function cleanup(base: string): void {
+  try {
+    closeDatabase();
+  } catch {
+    // ignore
+  }
   rmSync(base, { recursive: true, force: true });
 }
 
+function run(cmd: string, cwd: string): string {
+  return execSync(cmd, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
+}
+
+function initGitRepo(base: string): void {
+  writeFileSync(join(base, "README.md"), "# test\n", "utf-8");
+  writeFileSync(join(base, ".gsd", "STATE.md"), "# State\n", "utf-8");
+  run("git init", base);
+  run("git config user.email test@test.com", base);
+  run("git config user.name Test", base);
+  run("git add .", base);
+  run('git commit -m "init"', base);
+  run("git branch -M main", base);
+}
+
 function clearCaches(): void {
   clearPathCache();
   invalidateStateCache();
@@ -294,6 +326,38 @@ test('discardMilestone updates queue order', () => {
     }
 });
 
+test('discardMilestone removes DB rows, worktree, and milestone branch', () => {
+    const base = createFixtureBase();
+    try {
+      createMilestone(base, 'M001', { withRoadmap: true });
+      initGitRepo(base);
+      clearCaches();
+
+      assert.ok(openDatabase(join(base, '.gsd', 'gsd.db')), 'database opens');
+      insertMilestone({ id: 'M001', title: 'Discard me', status: 'active' });
+      insertSlice({ milestoneId: 'M001', id: 'S01', title: 'Only slice', status: 'pending' });
+      insertTask({ milestoneId: 'M001', sliceId: 'S01', id: 'T01', title: 'Only task', status: 'pending' });
+
+      const wt = createWorktree(base, 'M001', { branch: 'milestone/M001' });
+      assert.ok(existsSync(wt.path), 'worktree exists before discard');
+      assert.ok(run('git branch', base).includes('milestone/M001'), 'milestone branch exists before discard');
+      assert.ok(getMilestone('M001'), 'milestone exists in DB before discard');
+      assert.equal(getMilestoneSlices('M001').length, 1, 'slice exists in DB before discard');
+      assert.equal(getSliceTasks('M001', 'S01').length, 1, 'task exists in DB before discard');
+
+      const success = discardMilestone(base, 'M001');
+      assert.ok(success, 'discardMilestone returns true');
+
+      assert.equal(getMilestone('M001'), null, 'milestone row removed from DB');
+      assert.equal(getMilestoneSlices('M001').length, 0, 'slice rows removed from DB');
+      assert.equal(getSliceTasks('M001', 'S01').length, 0, 'task rows removed from DB');
+      assert.ok(!existsSync(wt.path), 'worktree removed after discard');
+      assert.ok(!run('git branch', base).includes('milestone/M001'), 'milestone branch removed after discard');
+    } finally {
+      cleanup(base);
+    }
+});
+
   // ─── Test 12: All milestones parked → no active milestone ─────────────
 test('All milestones parked → no active', async () => {
     const base = createFixtureBase();

package/src/resources/extensions/gsd/tests/plan-milestone-artifact-verification.test.ts

@@ -0,0 +1,62 @@
+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 { verifyExpectedArtifact } from "../auto-recovery.ts";
+
+function createFixtureBase(): string {
+  const base = mkdtempSync(join(tmpdir(), "gsd-plan-milestone-artifact-"));
+  mkdirSync(join(base, ".gsd", "milestones"), { recursive: true });
+  return base;
+}
+
+function writeRoadmap(base: string, milestoneId: string, content: string): void {
+  const milestoneDir = join(base, ".gsd", "milestones", milestoneId);
+  mkdirSync(milestoneDir, { recursive: true });
+  writeFileSync(join(milestoneDir, `${milestoneId}-ROADMAP.md`), content, "utf-8");
+}
+
+test("#3405: plan-milestone roadmap stub does not count as a verified artifact", () => {
+  const base = createFixtureBase();
+  try {
+    writeRoadmap(base, "M001", [
+      "# M001: Placeholder",
+      "",
+      "**Vision:** Stub only.",
+      "",
+      "## Slices",
+      "",
+      "_TBD_",
+      "",
+    ].join("\n"));
+
+    const result = verifyExpectedArtifact("plan-milestone", "M001", base);
+    assert.equal(result, false, "zero-slice roadmap stubs must fail verification");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("#3405: plan-milestone roadmap with real slices still passes artifact verification", () => {
+  const base = createFixtureBase();
+  try {
+    writeRoadmap(base, "M001", [
+      "# M001: Real roadmap",
+      "",
+      "**Vision:** Real work.",
+      "",
+      "## Slices",
+      "",
+      "- [ ] **S01: First slice** `risk:low` `depends:[]`",
+      "  > After this: a real slice exists.",
+      "",
+    ].join("\n"));
+
+    const result = verifyExpectedArtifact("plan-milestone", "M001", base);
+    assert.equal(result, true, "real roadmap slices should keep passing verification");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/post-unit-state-rebuild.test.ts

@@ -0,0 +1,34 @@
+/**
+ * Regression test for #3869: normal post-unit flow should rebuild STATE.md
+ * before syncing worktree state back to the project root.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const source = readFileSync(join(import.meta.dirname, "..", "auto-post-unit.ts"), "utf-8");
+
+test("auto-post-unit imports rebuildState", () => {
+  assert.ok(
+    source.includes('import { rebuildState } from "./doctor.js";'),
+    "auto-post-unit.ts should import rebuildState from doctor.ts",
+  );
+});
+
+test("postUnitPreVerification rebuilds STATE.md before worktree sync", () => {
+  const fnStart = source.indexOf("export async function postUnitPreVerification");
+  assert.ok(fnStart > 0, "postUnitPreVerification should exist");
+
+  const section = source.slice(fnStart, fnStart + 8000);
+  const rebuildIdx = section.indexOf('await runSafely("postUnit", "state-rebuild"');
+  const syncIdx = section.indexOf('await runSafely("postUnit", "worktree-sync"');
+
+  assert.ok(rebuildIdx > 0, "postUnitPreVerification should rebuild STATE.md after unit completion");
+  assert.ok(syncIdx > 0, "postUnitPreVerification should sync worktree state back to the project root");
+  assert.ok(
+    rebuildIdx < syncIdx,
+    "STATE.md rebuild should happen before worktree sync so synced state is fresh",
+  );
+});

package/src/resources/extensions/gsd/tests/preferences-formatting.test.ts

@@ -0,0 +1,87 @@
+/**
+ * Tests for formatSkillRef — pure formatting logic for skill references
+ * in the system prompt. Moved from preferences-skills.ts to preferences-types.ts
+ * to break the preferences ↔ preferences-skills circular dependency.
+ */
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+
+import { formatSkillRef } from "../preferences-types.ts";
+import type { SkillResolution } from "../preferences-types.ts";
+
+function makeResolutions(entries: [string, Partial<SkillResolution>][]): Map<string, SkillResolution> {
+  const map = new Map<string, SkillResolution>();
+  for (const [key, partial] of entries) {
+    map.set(key, {
+      original: partial.original ?? key,
+      resolvedPath: partial.resolvedPath ?? null,
+      method: partial.method ?? "unresolved",
+    });
+  }
+  return map;
+}
+
+describe("formatSkillRef", () => {
+  test("marks unresolved references with a warning", () => {
+    const resolutions = makeResolutions([
+      ["my-skill", { method: "unresolved" }],
+    ]);
+    const result = formatSkillRef("my-skill", resolutions);
+    assert.match(result, /my-skill/);
+    assert.match(result, /not found/);
+  });
+
+  test("marks unknown references (not in map) with a warning", () => {
+    const resolutions = new Map<string, SkillResolution>();
+    const result = formatSkillRef("unknown-skill", resolutions);
+    assert.match(result, /unknown-skill/);
+    assert.match(result, /not found/);
+  });
+
+  test("returns bare ref for absolute-path resolution", () => {
+    const resolutions = makeResolutions([
+      ["/home/user/skills/SKILL.md", {
+        method: "absolute-path",
+        resolvedPath: "/home/user/skills/SKILL.md",
+      }],
+    ]);
+    const result = formatSkillRef("/home/user/skills/SKILL.md", resolutions);
+    assert.equal(result, "/home/user/skills/SKILL.md");
+  });
+
+  test("returns bare ref for absolute-dir resolution", () => {
+    const resolutions = makeResolutions([
+      ["/home/user/skills/my-skill", {
+        method: "absolute-dir",
+        resolvedPath: "/home/user/skills/my-skill/SKILL.md",
+      }],
+    ]);
+    const result = formatSkillRef("/home/user/skills/my-skill", resolutions);
+    assert.equal(result, "/home/user/skills/my-skill");
+  });
+
+  test("shows resolved path for user-skill resolution", () => {
+    const resolutions = makeResolutions([
+      ["code-review", {
+        method: "user-skill",
+        resolvedPath: "/home/user/.claude/skills/code-review/SKILL.md",
+      }],
+    ]);
+    const result = formatSkillRef("code-review", resolutions);
+    assert.match(result, /code-review/);
+    assert.match(result, /\.claude\/skills\/code-review\/SKILL\.md/);
+  });
+
+  test("shows resolved path for project-skill resolution", () => {
+    const resolutions = makeResolutions([
+      ["lint-fix", {
+        method: "project-skill",
+        resolvedPath: "/repo/.gsd/skills/lint-fix/SKILL.md",
+      }],
+    ]);
+    const result = formatSkillRef("lint-fix", resolutions);
+    assert.match(result, /lint-fix/);
+    assert.match(result, /\.gsd\/skills\/lint-fix\/SKILL\.md/);
+  });
+});