@opengsd/get-shit-done-redux 1.0.0

package/sdk/src/runtime-bridge-sync/projectdir-regression.test.ts

@@ -0,0 +1,150 @@
+/**
+ * Regression test for the Phase 5.0 worker bug: projectDir and workstream were
+ * dropped from RuntimeBridgeExecuteInput before being forwarded to
+ * registry.dispatch(). The worker constructed a module-scoped
+ * QueryNativeDirectAdapter with a hardcoded projectDir='' — meaning any handler
+ * that reads .planning/ (e.g. state.*) would either fail silently or read from
+ * the process CWD rather than the requested project directory.
+ *
+ * Fix (Phase 5.1): the adapter is now constructed per-request inside
+ * dispatchNative so request.projectDir and request.workstream close over the
+ * correct values.
+ *
+ * These tests must:
+ * - FAIL against the unfixed worker (projectDir='', handler sees wrong dir).
+ * - PASS against the fixed worker (projectDir threaded correctly).
+ *
+ * NOTE: executeForCjs uses a compiled dist/ worker (see index.ts comments).
+ * The tests here call executeForCjs, which requires the worker to be rebuilt
+ * before the fix is observable. Run `npm run build` in sdk/ first.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdir, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { executeForCjs } from './index.js';
+
+// ─── Fixture STATE.md with parseable frontmatter ──────────────────────────
+
+const FIXTURE_STATE = `---
+gsd_state_version: 1.0
+milestone: v9.1
+milestone_name: Regression Test Milestone
+status: executing
+---
+
+# Project State
+
+## Current Position
+
+Phase: 9 (Regression Tests) — EXECUTING
+Plan: 1 of 2
+Status: Executing Phase 9
+Last activity: 2026-05-15 -- Regression test started
+
+Progress: [█████░░░░░] 50%
+`;
+
+// ─── Helpers ───────────────────────────────────────────────────────────────
+
+let tmpDir: string;
+
+beforeAll(async () => {
+  tmpDir = join(
+    tmpdir(),
+    `gsd-projectdir-regression-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+  await mkdir(join(tmpDir, '.planning'), { recursive: true });
+  await writeFile(join(tmpDir, '.planning', 'STATE.md'), FIXTURE_STATE, 'utf-8');
+});
+
+afterAll(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+// ─── Tests ─────────────────────────────────────────────────────────────────
+
+describe('executeForCjs projectDir regression (Phase 5.0 bug)', () => {
+  it('threads projectDir to the handler: state.json returns frontmatter data from the tmpdir fixture', () => {
+    // This test FAILS against the unfixed worker because projectDir='' causes
+    // the handler to look for .planning/STATE.md relative to '' (process CWD),
+    // which does not have a STATE.md fixture. The handler returns { error: 'STATE.md not found' }.
+    //
+    // With the fix, projectDir=tmpDir is forwarded and the handler reads the fixture.
+    const result = executeForCjs({
+      registryCommand: 'state.json',
+      registryArgs: [],
+      legacyCommand: 'state',
+      legacyArgs: ['json'],
+      mode: 'json',
+      projectDir: tmpDir,
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return; // narrow for TS
+
+    const data = result.data as Record<string, unknown>;
+
+    // The handler should have found the fixture and returned parsed frontmatter.
+    // Key assertions: these fields come from FIXTURE_STATE and are absent from
+    // any STATE.md that might exist at ''.
+    expect(data).not.toHaveProperty('error');
+    expect(data.milestone).toBe('v9.1');
+    expect(data.milestone_name).toBe('Regression Test Milestone');
+    expect(data.status).toBe('executing');
+  });
+
+  it('negative: nonexistent projectDir returns ok:true with {error} (handler-level not-found)', () => {
+    // A completely nonexistent directory: handler cannot find .planning/STATE.md
+    // and returns a structured error payload rather than throwing. This is the
+    // expected "soft failure" shape for state.json on a missing project.
+    const result = executeForCjs({
+      registryCommand: 'state.json',
+      registryArgs: [],
+      legacyCommand: 'state',
+      legacyArgs: ['json'],
+      mode: 'json',
+      projectDir: '/nonexistent-gsd-project-regression-test-dir',
+    });
+
+    // The handler returns { data: { error: 'STATE.md not found' } } — ok:true
+    // because it is a domain-level not-found, not a dispatch error.
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const data = result.data as Record<string, unknown>;
+    expect(data).toHaveProperty('error');
+    expect(String(data.error)).toMatch(/STATE\.md not found/i);
+  });
+
+  it('workstream support: GSDTransport routes workstream requests natively (Phase 6 fix)', () => {
+    // Phase 6 fix: GSDTransport no longer forces subprocess for workstream-scoped
+    // requests. The worker's dispatchNative closure (Phase 5.1 fix) correctly
+    // threads request.workstream through to registry.dispatch(), so native handlers
+    // route to the workstream-scoped .planning/workstreams/<ws>/ directory.
+    //
+    // The workstream 'some-workstream' has no separate STATE.md in tmpDir/
+    // .planning/workstreams/some-workstream/, so the handler returns a domain-level
+    // "not found" error (ok:true with {error:...}) — exactly like the nonexistent
+    // projectDir case. This confirms native dispatch was used (subprocess would
+    // have returned ok:false / errorKind).
+    const result = executeForCjs({
+      registryCommand: 'state.json',
+      registryArgs: [],
+      legacyCommand: 'state',
+      legacyArgs: ['json'],
+      mode: 'json',
+      projectDir: tmpDir,
+      workstream: 'some-workstream',
+    });
+
+    // Native dispatch used → ok:true (handler-level not-found, not a dispatch error).
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const data = result.data as Record<string, unknown>;
+    // Domain-level not-found: workstream's STATE.md doesn't exist in the fixture.
+    expect(data).toHaveProperty('error');
+    expect(String(data.error)).toMatch(/STATE\.md not found/i);
+  });
+});

package/sdk/src/runtime-bridge-sync/worker.ts

@@ -0,0 +1,224 @@
+/**
+ * Synckit worker for executeForCjs.
+ *
+ * Loaded by synckit's worker pool. Constructs a native-only QueryRuntimeBridge
+ * lazily (once per worker lifetime) and handles async execution, projecting
+ * results into the RuntimeBridgeSyncResult discriminated union.
+ *
+ * The bridge is configured with:
+ * - allowFallbackToSubprocess: false — keeps the worker self-contained with no
+ *   child-process spawning. Unknown commands surface as 'unknown_command' errors.
+ * - strictSdk: false — lets the transport surface 'unknown_command' rather than
+ *   throwing before dispatch.
+ */
+import { runAsWorker } from 'synckit';
+import { createRegistry } from '../query/index.js';
+import { GSDTransport } from '../gsd-transport.js';
+import { QueryExecutionPolicy } from '../query-execution-policy.js';
+import { QueryNativeDirectAdapter } from '../query-native-direct-adapter.js';
+import { QueryNativeHotpathAdapter } from '../query-native-hotpath-adapter.js';
+import { QueryRuntimeBridge } from '../query-runtime-bridge.js';
+import { GSDToolsError } from '../gsd-tools-error.js';
+import { GSDError, ErrorClassification } from '../errors.js';
+import { createQueryNativeErrorFactory } from '../query-tools-error-factory.js';
+import { formatQueryRawOutput } from '../query-raw-output-projection.js';
+import type { RuntimeBridgeExecuteInput } from '../query-runtime-bridge.js';
+import type { RuntimeBridgeSyncResult, SyncErrorKind } from './index.js';
+
+// ─── Lazy bridge singleton ──────────────────────────────────────────────────
+
+let bridgeInstance: QueryRuntimeBridge | null = null;
+
+function getBridge(): QueryRuntimeBridge {
+  if (bridgeInstance) return bridgeInstance;
+
+  const registry = createRegistry();
+
+  const NATIVE_TIMEOUT_MS = 30_000; // 30 s ceiling for any single handler
+  const nativeErrorFactory = createQueryNativeErrorFactory(NATIVE_TIMEOUT_MS);
+
+  // Build a per-request adapter inside dispatchNative so that projectDir and
+  // workstream from the request close over the correct values. The Phase 5.0
+  // bug was a module-scoped adapter that hardcoded projectDir = '' — any
+  // handler reading .planning/ (e.g. state.*) received an empty path and
+  // silently failed or read from the process CWD. Constructing per-request
+  // adds microseconds; correctness wins. (fix for latent bug, Phase 5.1)
+  const transport = new GSDTransport(registry, {
+    dispatchNative: (request) => {
+      const adapter = new QueryNativeDirectAdapter({
+        timeoutMs: NATIVE_TIMEOUT_MS,
+        dispatch: (registryCommand, registryArgs) =>
+          registry.dispatch(registryCommand, registryArgs, request.projectDir, request.workstream),
+        ...nativeErrorFactory,
+      });
+      return adapter.dispatchResult(
+        request.legacyCommand,
+        request.legacyArgs,
+        request.registryCommand,
+        request.registryArgs,
+      );
+    },
+    // #3631: forward raw-mode projection so mode:'raw' returns the per-command
+    // scalar string (next-decimal token, get-phase section, etc.) instead of
+    // falling back to generic JSON-stringify. Without this, family-router
+    // sdkHandlers requesting mode:'raw' under --raw receive a stringified
+    // JSON IR — the regression #3577 introduced for every family router.
+    formatNativeRaw: (registryCommand, data) => formatQueryRawOutput(registryCommand, data),
+    // Subprocess fallback stubs — never called because allowFallbackToSubprocess=false
+    execSubprocessJson: () =>
+      Promise.reject(new Error('Subprocess fallback disabled in sync bridge worker')),
+    execSubprocessRaw: () =>
+      Promise.reject(new Error('Subprocess fallback disabled in sync bridge worker')),
+  });
+
+  const executionPolicy = new QueryExecutionPolicy(transport);
+
+  // Hotpath adapter: construct a stub that satisfies the QueryRuntimeBridge
+  // constructor. executeForCjs does not invoke dispatchHotpath so this
+  // adapter is never actually called. We still need a valid instance because
+  // QueryRuntimeBridge requires one at construction time.
+  const stubDirectAdapter = new QueryNativeDirectAdapter({
+    timeoutMs: NATIVE_TIMEOUT_MS,
+    dispatch: () => Promise.reject(new Error('stub: hotpath direct adapter not used')),
+    ...nativeErrorFactory,
+  });
+  const hotpathAdapter = new QueryNativeHotpathAdapter(
+    () => true,
+    stubDirectAdapter,
+    () => Promise.reject(new Error('hotpath json fallback disabled')),
+    () => Promise.reject(new Error('hotpath raw fallback disabled')),
+  );
+
+  bridgeInstance = new QueryRuntimeBridge(
+    registry,
+    executionPolicy,
+    hotpathAdapter,
+    () => true, // always prefer native
+    {
+      allowFallbackToSubprocess: false,
+      strictSdk: false,
+    },
+  );
+
+  return bridgeInstance;
+}
+
+// ─── Error classification ───────────────────────────────────────────────────
+
+/**
+ * Map a caught error into the 6-kind ADR-0001 error taxonomy.
+ *
+ * GSDToolsError.classification.kind: 'timeout' | 'failure'
+ * GSDError.classification: ErrorClassification enum
+ *
+ * Mapping:
+ * - 'Subprocess fallback disabled' message → unknown_command (no native adapter for command)
+ * - GSDToolsError timeout kind → native_timeout
+ * - GSDError Validation → validation_error
+ * - GSDError Blocked → validation_error (semantic: prerequisite missing)
+ * - TypeError (programming error) → internal_error
+ * - GSDToolsError failure + TypeError cause → internal_error
+ * - GSDToolsError failure → native_failure
+ * - Unknown Error → internal_error
+ */
+function readReason(error: unknown): string | undefined {
+  // Handlers can pin a CJS-style ERROR_REASON snake_case code on the GSDError
+  // they throw (e.g. configGet → 'config_key_not_found'). The worker
+  // propagates it through errorDetails so the CJS dispatcher can call
+  // `error(msg, reason)` and `--json-errors` clients see a typed reason
+  // rather than the generic 'unknown'. (Bugs #2943, #3086.)
+  if (error && typeof error === 'object' && 'reason' in error) {
+    const r = (error as { reason?: unknown }).reason;
+    if (typeof r === 'string' && r.length > 0) return r;
+  }
+  return undefined;
+}
+
+function classifyError(error: unknown): { kind: SyncErrorKind; exitCode: number; message: string; reason?: string } {
+  if (error instanceof GSDToolsError) {
+    const { classification, exitCode, message } = error;
+
+    // Unknown command: transport throws 'Subprocess fallback disabled: command ... cannot run without native dispatch'
+    if (
+      classification.kind === 'failure' &&
+      message.includes('Subprocess fallback disabled:') &&
+      message.includes('cannot run without native dispatch')
+    ) {
+      return { kind: 'unknown_command', exitCode: exitCode ?? 1, message };
+    }
+
+    if (classification.kind === 'timeout') {
+      return { kind: 'native_timeout', exitCode: exitCode ?? 1, message };
+    }
+
+    // Unwrap the cause once.  The native direct adapter wraps every non-
+    // GSDToolsError thrown by a handler in a GSDToolsError via
+    // `createNativeFailureError`, preserving the original via `cause`.
+    // Classification of validation / blocked errors therefore has to walk
+    // through to the cause — otherwise every GSDError validation surfaces
+    // as `native_failure` and callers cannot distinguish "you gave me bad
+    // input" from "the SDK crashed."  (Phase 6 / #3592 contract bug.)
+    const cause = (error as NodeJS.ErrnoException & { cause?: unknown }).cause;
+    if (cause instanceof GSDError) {
+      const reason = readReason(cause);
+      if (
+        cause.classification === ErrorClassification.Validation ||
+        cause.classification === ErrorClassification.Blocked
+      ) {
+        return { kind: 'validation_error', exitCode: 10, message: cause.message, reason };
+      }
+      // Execution-classified GSDError is a 'handler said no' result —
+      // exitCode 1, internal_error kind for taxonomy purposes, but pass
+      // the structured reason through so the CJS dispatcher can render
+      // the proper `--json-errors` shape.
+      return { kind: 'internal_error', exitCode: 1, message: cause.message, reason };
+    }
+    if (cause instanceof TypeError) {
+      return { kind: 'internal_error', exitCode: exitCode ?? 1, message };
+    }
+
+    return { kind: 'native_failure', exitCode: exitCode ?? 1, message };
+  }
+
+  if (error instanceof GSDError) {
+    const { classification, message } = error;
+    const reason = readReason(error);
+    if (
+      classification === ErrorClassification.Validation ||
+      classification === ErrorClassification.Blocked
+    ) {
+      return { kind: 'validation_error', exitCode: 10, message, reason };
+    }
+    return { kind: 'internal_error', exitCode: 1, message, reason };
+  }
+
+  if (error instanceof TypeError) {
+    const message = error.message;
+    return { kind: 'internal_error', exitCode: 1, message };
+  }
+
+  const message = error instanceof Error ? error.message : String(error);
+  return { kind: 'internal_error', exitCode: 1, message };
+}
+
+// ─── Worker entry point ─────────────────────────────────────────────────────
+
+runAsWorker(async (input: RuntimeBridgeExecuteInput): Promise<RuntimeBridgeSyncResult> => {
+  const bridge = getBridge();
+
+  try {
+    const data = await bridge.execute(input);
+    return { ok: true, data, exitCode: 0 };
+  } catch (error: unknown) {
+    const { kind, exitCode, message, reason } = classifyError(error);
+    const errorDetails: { message: string; reason?: string } = { message };
+    if (reason) errorDetails.reason = reason;
+    return {
+      ok: false,
+      exitCode,
+      errorKind: kind,
+      errorDetails,
+      stderrLines: [],
+    };
+  }
+});

package/sdk/src/runtime-gate.test.ts

@@ -0,0 +1,84 @@
+/**
+ * Unit tests for runtime-gate.ts
+ *
+ * Regression tests for #2832: gsd-sdk auto silently routed Codex (and other
+ * non-Claude) runtime projects through the Claude Agent SDK, picked
+ * Claude-Sonnet defaults from the profile map, and reported instant failures.
+ * The gate fails fast with an actionable error so users either set the right
+ * runtime or fall back to the in-session GSD slash commands.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { assertRuntimeSupportsAutoMode } from './runtime-gate.js';
+
+describe('assertRuntimeSupportsAutoMode', () => {
+  let prevEnv: string | undefined;
+  beforeEach(() => {
+    prevEnv = process.env.GSD_RUNTIME;
+    delete process.env.GSD_RUNTIME;
+  });
+  afterEach(() => {
+    if (prevEnv === undefined) delete process.env.GSD_RUNTIME;
+    else process.env.GSD_RUNTIME = prevEnv;
+  });
+
+  it('passes for runtime: claude (config)', () => {
+    expect(() => assertRuntimeSupportsAutoMode({ runtime: 'claude' })).not.toThrow();
+  });
+
+  it('passes when no runtime configured (defaults to claude)', () => {
+    expect(() => assertRuntimeSupportsAutoMode(undefined)).not.toThrow();
+    expect(() => assertRuntimeSupportsAutoMode({})).not.toThrow();
+  });
+
+  it('throws for runtime: codex via config', () => {
+    expect(() => assertRuntimeSupportsAutoMode({ runtime: 'codex' })).toThrow(/codex/);
+  });
+
+  it('throws for GSD_RUNTIME=codex even when config says claude', () => {
+    process.env.GSD_RUNTIME = 'codex';
+    expect(() => assertRuntimeSupportsAutoMode({ runtime: 'claude' })).toThrow(/codex/);
+  });
+
+  it('error message references issue #2832 and slash-command workaround', () => {
+    let caught: Error | undefined;
+    try {
+      assertRuntimeSupportsAutoMode({ runtime: 'codex' });
+    } catch (err) {
+      caught = err as Error;
+    }
+    expect(caught).toBeDefined();
+    expect(caught!.message).toMatch(/#2832/);
+    expect(caught!.message).toMatch(/gsd-discuss-phase|gsd-plan-phase|gsd-execute-phase/);
+  });
+
+  it('throws for gemini runtime', () => {
+    expect(() => assertRuntimeSupportsAutoMode({ runtime: 'gemini' })).toThrow();
+  });
+
+  it('throws for opencode runtime', () => {
+    expect(() => assertRuntimeSupportsAutoMode({ runtime: 'opencode' })).toThrow();
+  });
+
+  it('passes for unknown runtime values (fall through to claude default)', () => {
+    // Mirrors detectRuntime: unknown values are NOT in SUPPORTED_RUNTIMES,
+    // so they fall through to 'claude' rather than hard-blocking.
+    expect(() => assertRuntimeSupportsAutoMode({ runtime: 'totally-bogus' })).not.toThrow();
+  });
+
+  it('attributes source to config when GSD_RUNTIME is set to an unsupported value', () => {
+    // Unsupported env values fall through to config in detectRuntime; the
+    // gate's error message must report config (not the discarded env value)
+    // as the source so users debug the right thing.
+    process.env.GSD_RUNTIME = 'unsupported-env';
+    let caught: Error | undefined;
+    try {
+      assertRuntimeSupportsAutoMode({ runtime: 'codex' });
+    } catch (err) {
+      caught = err as Error;
+    }
+    expect(caught).toBeDefined();
+    expect(caught!.message).toMatch(/config\.runtime="codex"/);
+    expect(caught!.message).not.toMatch(/GSD_RUNTIME=unsupported-env/);
+  });
+});

package/sdk/src/runtime-gate.ts

@@ -0,0 +1,52 @@
+/**
+ * Runtime gate — guards entry points that only support the Claude runtime.
+ *
+ * The autonomous SDK orchestrator (`gsd-sdk auto`) currently drives plan
+ * execution through `@anthropic-ai/claude-agent-sdk`. It has no Codex /
+ * Gemini / OpenCode dispatcher today, so silently routing a non-Claude
+ * project's autonomous run through the Claude path is incorrect: it picks
+ * Claude models, hits Claude APIs, and confuses users debugging "why is my
+ * Codex run choosing claude-sonnet-4-6?" (issue #2832).
+ *
+ * Fail fast with an actionable error instead. The fix surfaces the limitation
+ * up front and points users at the supported in-session GSD slash commands
+ * for non-Claude runtimes.
+ */
+import { detectRuntime, SUPPORTED_RUNTIMES, type Runtime } from './query/helpers.js';
+
+/**
+ * Throw a clear error when the active runtime is not Claude.
+ *
+ * Precedence mirrors `detectRuntime`: `GSD_RUNTIME` env var > `config.runtime`
+ * > `'claude'`. Unknown / missing runtime values default to Claude (the
+ * historical behavior) so existing Claude users are unaffected.
+ *
+ * @param config Project config (with optional `runtime` field).
+ * @throws Error with a runtime-specific actionable message when non-Claude.
+ */
+export function assertRuntimeSupportsAutoMode(config?: Record<string, unknown> | { runtime?: unknown }): void {
+  const cfg = (config ?? {}) as Record<string, unknown>;
+  const runtime: Runtime = detectRuntime({ runtime: cfg.runtime });
+  if (runtime === 'claude') return;
+
+  // Source attribution must reflect what `detectRuntime()` actually used:
+  // a `GSD_RUNTIME` value that isn't in SUPPORTED_RUNTIMES falls through to
+  // the config tier, so reporting it as the source would be misleading.
+  const env = process.env.GSD_RUNTIME;
+  const envIsSupported =
+    typeof env === 'string' && (SUPPORTED_RUNTIMES as readonly string[]).includes(env);
+  const source = envIsSupported
+    ? `GSD_RUNTIME=${env}`
+    : `config.runtime="${String(cfg.runtime ?? '')}"`;
+
+  throw new Error(
+    `gsd-sdk auto currently supports the Claude runtime only ` +
+    `(detected runtime=${runtime} via ${source}). ` +
+    `Autonomous terminal runs through the Claude Agent SDK; non-Claude ` +
+    `runtimes (Codex, Gemini, OpenCode, etc.) must drive GSD via the ` +
+    `in-session slash commands (e.g. /gsd-discuss-phase, /gsd-plan-phase, ` +
+    `/gsd-execute-phase) until issue #2832 lands a multi-runtime executor. ` +
+    `To run on Claude anyway, unset GSD_RUNTIME and set runtime: "claude" ` +
+    `in .planning/config.json.`,
+  );
+}

package/sdk/src/sdk-package-compatibility.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it, vi } from 'vitest';
+import { join } from 'node:path';
+
+import {
+  BUNDLED_CORE_CJS_PATH,
+  BUNDLED_GSD_AGENTS_DIR,
+  BUNDLED_GSD_TEMPLATES_DIR,
+  BUNDLED_GSD_TOOLS_PATH,
+  loadLegacyCoreConfig,
+  probeLegacySdkAsset,
+  resolveBundledAgentsDir,
+  resolveBundledTemplatesDir,
+  resolveGsdToolsPath,
+  resolveLegacyInstallDir,
+  resolveLegacyUserProfilePath,
+  resolveLegacyTemplatesDir,
+  resolveLegacyWorkflowsDir,
+} from './sdk-package-compatibility.js';
+import { GSDError } from './errors.js';
+
+describe('SDK Package Seam Module', () => {
+  const projectDir = '/work/project';
+  const homeDir = '/users/tester';
+
+  it('resolves legacy install-relative directories through one seam', () => {
+    expect(resolveLegacyInstallDir(homeDir)).toBe(join(homeDir, '.claude', 'get-shit-done'));
+    expect(resolveLegacyTemplatesDir(homeDir)).toBe(join(homeDir, '.claude', 'get-shit-done', 'templates'));
+    expect(resolveLegacyWorkflowsDir(homeDir)).toBe(join(homeDir, '.claude', 'get-shit-done', 'workflows'));
+    expect(resolveLegacyUserProfilePath(homeDir)).toBe(join(homeDir, '.claude', 'get-shit-done', 'USER-PROFILE.md'));
+    expect(resolveBundledTemplatesDir()).toBe(BUNDLED_GSD_TEMPLATES_DIR);
+    expect(resolveBundledAgentsDir()).toBe(BUNDLED_GSD_AGENTS_DIR);
+  });
+
+  it('probes legacy gsd-tools locations in bundled -> project -> home order', () => {
+    const resolution = probeLegacySdkAsset('gsd-tools', projectDir, {
+      homeDir,
+      existsSync: path => path === join(projectDir, '.claude', 'get-shit-done', 'bin', 'gsd-tools.cjs'),
+    });
+
+    expect(resolution.probes).toEqual([
+      BUNDLED_GSD_TOOLS_PATH,
+      join(projectDir, '.claude', 'get-shit-done', 'bin', 'gsd-tools.cjs'),
+      join(homeDir, '.claude', 'get-shit-done', 'bin', 'gsd-tools.cjs'),
+    ]);
+    expect(resolution.path).toBe(join(projectDir, '.claude', 'get-shit-done', 'bin', 'gsd-tools.cjs'));
+    expect(resolution.fallbackPath).toBe(join(homeDir, '.claude', 'get-shit-done', 'bin', 'gsd-tools.cjs'));
+  });
+
+  it('returns concrete fallback gsd-tools path when no legacy probe exists', () => {
+    const path = resolveGsdToolsPath(projectDir, {
+      homeDir,
+      existsSync: () => false,
+    });
+
+    expect(path).toBe(join(homeDir, '.claude', 'get-shit-done', 'bin', 'gsd-tools.cjs'));
+  });
+
+  it('loads legacy core.cjs through one compatibility adapter', () => {
+    const loadConfig = vi.fn((cwd: string) => ({ cwd, source: 'legacy-core' }));
+    const requireFn = vi.fn(() => ({ loadConfig }));
+    const createRequire = vi.fn(() => requireFn as unknown as NodeJS.Require);
+
+    const result = loadLegacyCoreConfig(projectDir, {
+      homeDir,
+      existsSync: path => path === BUNDLED_CORE_CJS_PATH,
+      createRequire,
+    });
+
+    expect(createRequire).toHaveBeenCalledOnce();
+    expect(requireFn).toHaveBeenCalledWith(BUNDLED_CORE_CJS_PATH);
+    expect(loadConfig).toHaveBeenCalledWith(projectDir);
+    expect(result).toEqual({ cwd: projectDir, source: 'legacy-core' });
+  });
+
+  it('reports checked core.cjs probes when legacy asset missing', () => {
+    expect(() => loadLegacyCoreConfig(projectDir, {
+      homeDir,
+      existsSync: () => false,
+    })).toThrow(GSDError);
+
+    try {
+      loadLegacyCoreConfig(projectDir, {
+        homeDir,
+        existsSync: () => false,
+      });
+      expect.fail('expected GSDError');
+    } catch (error) {
+      expect(error).toBeInstanceOf(GSDError);
+      const message = (error as Error).message;
+      expect(message).toContain('state load: get-shit-done/bin/lib/core.cjs not found.');
+      expect(message).toContain('Checked:');
+      expect(message).toContain(BUNDLED_CORE_CJS_PATH);
+      expect(message).toContain(join(projectDir, '.claude', 'get-shit-done', 'bin', 'lib', 'core.cjs'));
+      expect(message).toContain(join(homeDir, '.claude', 'get-shit-done', 'bin', 'lib', 'core.cjs'));
+    }
+  });
+});