gsd-pi 2.78.1-dev.84a383f51 → 2.78.1-dev.8a893322c

package/README.md

@@ -471,6 +471,7 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `/gsd logs`             | Browse activity, debug, and metrics logs                                      |
 | `/gsd export --html`    | Generate HTML report for current or completed milestone                       |
 | `/worktree` (`/wt`)     | Git worktree lifecycle — create, switch, merge, remove                        |
+| `/gsd worktree` (`/gsd wt`) | TUI worktree management — list, merge, clean, remove with safety checks   |
 | `/voice`                | Toggle real-time speech-to-text (macOS, Linux)                                |
 | `/exit`                 | Graceful shutdown — saves session state before exiting                        |
 | `/kill`                 | Kill GSD process immediately                                                  |

package/dist/bundled-resource-path.d.ts

@@ -1,3 +1,10 @@
+export type FileExists = (path: string) => boolean;
+export declare function resolvePackageRoot(importUrl: string): string;
+export declare function hasCompleteBundledResources(resourcesDir: string, fileExists?: FileExists): boolean;
+export declare function resolveBundledResourcesDirFromPackageRoot(packageRoot: string, fileExists?: FileExists): string;
+export declare function resolveBundledResourcesDir(importUrl: string, fileExists?: FileExists): string;
+export declare function resolveBundledResource(importUrl: string, ...segments: string[]): string;
+export declare function resolveBundledGsdExtensionModule(importUrl: string, moduleFile: string, fileExists?: FileExists): string;
 /**
  * Resolve bundled raw resource files from the package root.
  *

package/dist/bundled-resource-path.js

@@ -1,5 +1,38 @@
+import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+export function resolvePackageRoot(importUrl) {
+    const moduleDir = dirname(fileURLToPath(importUrl));
+    return resolve(moduleDir, "..");
+}
+export function hasCompleteBundledResources(resourcesDir, fileExists = existsSync) {
+    return fileExists(join(resourcesDir, "agents")) &&
+        fileExists(join(resourcesDir, "extensions"));
+}
+export function resolveBundledResourcesDirFromPackageRoot(packageRoot, fileExists = existsSync) {
+    const distResources = join(packageRoot, "dist", "resources");
+    const srcResources = join(packageRoot, "src", "resources");
+    return hasCompleteBundledResources(distResources, fileExists)
+        ? distResources
+        : srcResources;
+}
+export function resolveBundledResourcesDir(importUrl, fileExists = existsSync) {
+    return resolveBundledResourcesDirFromPackageRoot(resolvePackageRoot(importUrl), fileExists);
+}
+export function resolveBundledResource(importUrl, ...segments) {
+    return join(resolveBundledResourcesDir(importUrl), ...segments);
+}
+export function resolveBundledGsdExtensionModule(importUrl, moduleFile, fileExists = existsSync) {
+    const packageRoot = resolvePackageRoot(importUrl);
+    const distResources = join(packageRoot, "dist", "resources");
+    const jsFile = moduleFile.replace(/\.ts$/, ".js");
+    const distModule = join(distResources, "extensions", "gsd", jsFile);
+    if (hasCompleteBundledResources(distResources, fileExists) && fileExists(distModule)) {
+        return distModule;
+    }
+    const tsFile = moduleFile.replace(/\.js$/, ".ts");
+    return join(packageRoot, "src", "resources", "extensions", "gsd", tsFile);
+}
 /**
  * Resolve bundled raw resource files from the package root.
  *
@@ -8,7 +41,6 @@ import { fileURLToPath } from "node:url";
  * `src/resources/**`, not next to the compiled entry point.
  */
 export function resolveBundledSourceResource(importUrl, ...segments) {
-    const moduleDir = dirname(fileURLToPath(importUrl));
-    const packageRoot = resolve(moduleDir, "..");
+    const packageRoot = resolvePackageRoot(importUrl);
     return join(packageRoot, "src", "resources", ...segments);
 }

package/dist/claude-cli-check.js

@@ -5,6 +5,21 @@
 // Set GSD_CLAUDE_DEBUG=1 to log probe output to stderr. Useful when
 // diagnosing platform-specific detection failures (Issue #4997).
 import { execFileSync } from 'node:child_process';
+/**
+ * Spawn the Claude CLI without triggering Node's DEP0190.
+ *
+ * Passing `args` together with `shell: true` is deprecated in Node 22+
+ * because the args are concatenated into the command string without
+ * escaping. On Windows we still need a shell to resolve `.cmd` shims, so
+ * we invoke `cmd /c <command> <args...>` explicitly. On POSIX we don't
+ * need a shell at all.
+ */
+function spawnClaude(command, args, opts) {
+    if (process.platform === 'win32') {
+        return execFileSync('cmd', ['/c', command, ...args], opts);
+    }
+    return execFileSync(command, args, opts);
+}
 /**
  * Platform-correct binary name for the Claude Code CLI.
  *
@@ -44,10 +59,9 @@ function debugLog(...parts) {
 function findWorkingCommand() {
     for (const command of CLAUDE_COMMAND_CANDIDATES) {
         try {
-            execFileSync(command, ['--version'], {
+            spawnClaude(command, ['--version'], {
                 timeout: VERSION_TIMEOUT_MS,
                 stdio: 'pipe',
-                shell: process.platform === 'win32',
             });
             debugLog('version probe ok via', command);
             return command;
@@ -93,10 +107,9 @@ function parseAuthStatus(output) {
 function probeAuth(command) {
     // Try --json first (newer CLIs).
     try {
-        const out = execFileSync(command, ['auth', 'status', '--json'], {
+        const out = spawnClaude(command, ['auth', 'status', '--json'], {
             timeout: AUTH_TIMEOUT_MS,
             stdio: 'pipe',
-            shell: process.platform === 'win32',
         }).toString();
         debugLog('auth status --json output:', out.slice(0, 200));
         const parsed = parseAuthStatus(out);
@@ -108,10 +121,9 @@ function probeAuth(command) {
     }
     // Fallback: plain `auth status` (older CLIs that don't accept --json).
     try {
-        const out = execFileSync(command, ['auth', 'status'], {
+        const out = spawnClaude(command, ['auth', 'status'], {
             timeout: AUTH_TIMEOUT_MS,
             stdio: 'pipe',
-            shell: process.platform === 'win32',
         }).toString();
         debugLog('auth status output:', out.slice(0, 200));
         return parseAuthStatus(out);

package/dist/headless-query.js

@@ -17,7 +17,7 @@ import { createJiti } from '@mariozechner/jiti';
 import { fileURLToPath } from 'node:url';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
-import { resolveBundledSourceResource } from './bundled-resource-path.js';
+import { resolveBundledGsdExtensionModule } from './bundled-resource-path.js';
 const jiti = createJiti(fileURLToPath(import.meta.url), { interopDefault: true, debug: false });
 const { existsSync } = await import('node:fs');
 /**
@@ -30,7 +30,8 @@ const { existsSync } = await import('node:fs');
  * #3471 contract can be exercised in tests without spawning a subprocess.
  */
 export function resolveGsdAgentExtensionsDir(env = process.env) {
-    return join(env.GSD_AGENT_DIR || join(homedir(), '.gsd', 'agent'), 'extensions', 'gsd');
+    const agentRoot = env.GSD_AGENT_DIR || join(env.GSD_HOME || join(homedir(), '.gsd'), 'agent');
+    return join(agentRoot, 'extensions', 'gsd');
 }
 /**
  * Decide whether headless-query should load extensions from the agent
@@ -41,13 +42,27 @@ export function shouldUseAgentExtensionsDir(opts) {
     const env = opts.env ?? process.env;
     const fileExists = opts.fileExists ?? existsSync;
     const agentDir = resolveGsdAgentExtensionsDir(env);
-    return { agentDir, useAgentDir: fileExists(join(agentDir, 'state.ts')) };
+    return {
+        agentDir,
+        useAgentDir: fileExists(join(agentDir, 'state.ts')) || fileExists(join(agentDir, 'state.js')),
+    };
 }
 const agentExtensionsDir = resolveGsdAgentExtensionsDir();
-const useAgentDir = existsSync(join(agentExtensionsDir, 'state.ts'));
+const { useAgentDir } = shouldUseAgentExtensionsDir({ env: process.env });
 const gsdExtensionPath = (...segments) => useAgentDir
-    ? join(agentExtensionsDir, ...segments)
-    : resolveBundledSourceResource(import.meta.url, 'extensions', 'gsd', ...segments);
+    ? resolveAgentExtensionModule(agentExtensionsDir, segments)
+    : resolveBundledGsdExtensionModule(import.meta.url, segments.join('/'));
+function resolveAgentExtensionModule(agentDir, segments) {
+    const requested = join(agentDir, ...segments);
+    if (existsSync(requested))
+        return requested;
+    if (segments.length === 1 && segments[0].endsWith('.ts')) {
+        const jsPath = join(agentDir, segments[0].replace(/\.ts$/, '.js'));
+        if (existsSync(jsPath))
+            return jsPath;
+    }
+    return requested;
+}
 async function loadExtensionModules() {
     const stateModule = await jiti.import(gsdExtensionPath('state.ts'), {});
     const dispatchModule = await jiti.import(gsdExtensionPath('auto-dispatch.ts'), {});

package/dist/loader.js

@@ -60,6 +60,7 @@ if (firstArg === '--help' || firstArg === '-h') {
 import { agentDir, appRoot } from './app-paths.js';
 import { applyRtkProcessEnv } from './rtk-shared.js';
 import { serializeBundledExtensionPaths } from './bundled-extension-paths.js';
+import { resolveBundledResourcesDirFromPackageRoot } from './bundled-resource-path.js';
 import { discoverExtensionEntryPaths } from './extension-discovery.js';
 import { loadRegistry, readManifestFromEntryPath, isExtensionEnabled } from './extension-registry.js';
 import { renderLogo } from './logo.js';
@@ -118,9 +119,7 @@ process.env.GSD_BIN_PATH = process.argv[1];
 // GSD_WORKFLOW_PATH — absolute path to bundled GSD-WORKFLOW.md, used by patched gsd extension
 // when dispatching workflow prompts. Prefers dist/resources/ (stable, set at build time)
 // over src/resources/ (live working tree) — see resource-loader.ts for rationale.
-const distRes = join(gsdRoot, 'dist', 'resources');
-const srcRes = join(gsdRoot, 'src', 'resources');
-const resourcesDir = existsSync(distRes) ? distRes : srcRes;
+const resourcesDir = resolveBundledResourcesDirFromPackageRoot(gsdRoot);
 process.env.GSD_WORKFLOW_PATH = join(resourcesDir, 'GSD-WORKFLOW.md');
 // GSD_BUNDLED_EXTENSION_PATHS — dynamically discovered bundled extension entry points.
 // Uses the shared discoverExtensionEntryPaths() to scan the bundled resources

package/dist/resource-loader.js

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { compareSemver } from './update-check.js';
 import { discoverExtensionEntryPaths } from './extension-discovery.js';
 import { loadRegistry, readManifestFromEntryPath, isExtensionEnabled, ensureRegistryEntries } from './extension-registry.js';
+import { resolveBundledResourcesDirFromPackageRoot } from './bundled-resource-path.js';
 let piCodingAgentModulePromise;
 function loadPiCodingAgentModule() {
     return (piCodingAgentModulePromise ??= import('@gsd/pi-coding-agent'));
@@ -19,14 +20,7 @@ function loadPiCodingAgentModule() {
 // dist/resources/ is populated by the build step (`npm run copy-resources`) and
 // reflects the built state, not the currently checked-out branch.
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const distResources = join(packageRoot, 'dist', 'resources');
-const srcResources = join(packageRoot, 'src', 'resources');
-// Use dist/resources only if it has the full expected structure.
-// A partial build (tsc without copy-resources) creates dist/resources/extensions/
-// but not agents/ or skills/, causing initResources to sync from an incomplete source.
-const resourcesDir = (existsSync(distResources) && existsSync(join(distResources, 'agents')))
-    ? distResources
-    : srcResources;
+const resourcesDir = resolveBundledResourcesDirFromPackageRoot(packageRoot);
 const bundledExtensionsDir = join(resourcesDir, 'extensions');
 const resourceVersionManifestName = 'managed-resources.json';
 const resourceFingerprintFileName = '.managed-resources-content-hash';

package/dist/resources/.managed-resources-content-hash

@@ -1 +1 @@
-afb1073f61989a78
+868d22f3f04d038e

package/dist/resources/extensions/claude-code-cli/readiness.js

@@ -14,6 +14,21 @@
  * failures (Issue #4997).
  */
 import { execFileSync } from "node:child_process";
+/**
+ * Spawn the Claude CLI without triggering Node's DEP0190.
+ *
+ * Passing `args` together with `shell: true` is deprecated in Node 22+
+ * because the args are concatenated into the command string without
+ * escaping. On Windows we still need a shell to resolve `.cmd` shims, so
+ * we invoke `cmd /c <command> <args...>` explicitly. On POSIX we don't
+ * need a shell at all.
+ */
+function spawnClaude(command, args, opts) {
+    if (process.platform === "win32") {
+        return execFileSync("cmd", ["/c", command, ...args], opts);
+    }
+    return execFileSync(command, args, opts);
+}
 /**
  * Candidate executable names for the Claude Code CLI.
  *
@@ -43,7 +58,7 @@ function debugLog(...parts) {
  * Find the first candidate that responds to `--version`. Returns the
  * candidate name on success, null if none worked.
  *
- * On Windows with `shell: true`, a missing candidate surfaces as a
+ * On Windows with `cmd /c`, a missing candidate surfaces as a
  * non-zero exit from cmd.exe rather than ENOENT — so we cannot rely on
  * the error code to decide "try next". Treat any failure as "try next"
  * for the version probe; the only thing that matters for binary
@@ -53,10 +68,9 @@ function debugLog(...parts) {
 function findWorkingCommand() {
     for (const command of CLAUDE_COMMAND_CANDIDATES) {
         try {
-            execFileSync(command, ["--version"], {
+            spawnClaude(command, ["--version"], {
                 timeout: VERSION_TIMEOUT_MS,
                 stdio: "pipe",
-                shell: process.platform === "win32",
             });
             debugLog("version probe ok via", command);
             return command;
@@ -103,10 +117,9 @@ function parseAuthStatus(output) {
 function probeAuth(command) {
     // Try --json first (newer CLIs).
     try {
-        const out = execFileSync(command, ["auth", "status", "--json"], {
+        const out = spawnClaude(command, ["auth", "status", "--json"], {
             timeout: AUTH_TIMEOUT_MS,
             stdio: "pipe",
-            shell: process.platform === "win32",
         }).toString();
         debugLog("auth status --json output:", out.slice(0, 200));
         const parsed = parseAuthStatus(out);
@@ -118,10 +131,9 @@ function probeAuth(command) {
     }
     // Fallback: plain `auth status` (older CLIs that don't accept --json).
     try {
-        const out = execFileSync(command, ["auth", "status"], {
+        const out = spawnClaude(command, ["auth", "status"], {
             timeout: AUTH_TIMEOUT_MS,
             stdio: "pipe",
-            shell: process.platform === "win32",
         }).toString();
         debugLog("auth status output:", out.slice(0, 200));
         return parseAuthStatus(out);

package/dist/resources/extensions/google-search/index.js

@@ -1,7 +1,3 @@
-export default function (pi) {
-    pi.on("session_start", async (_event, ctx) => {
-        ctx.ui.notify("google_search is being extracted to @gsd-extensions/google-search " +
-            "(not yet published to npm). This stub will be replaced once the " +
-            "package is available. No action needed for now.", "warning");
-    });
+export default function (_pi) {
+    // Deprecation notice intentionally suppressed until @gsd-extensions/google-search ships.
 }

package/dist/resources/extensions/gsd/auto/phases.js

@@ -11,6 +11,7 @@ import { MAX_RECOVERY_CHARS, BUDGET_THRESHOLDS, MAX_FINALIZE_TIMEOUTS, } from ".
 import { detectStuck } from "./detect-stuck.js";
 import { runUnit } from "./run-unit.js";
 import { debugLog } from "../debug-logger.js";
+import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { PROJECT_FILES, hasProjectFileInAncestor } from "../detection.js";
 import { MergeConflictError } from "../git-service.js";
 import { setCurrentPhase, clearCurrentPhase } from "../../shared/gsd-phase-state.js";
@@ -48,11 +49,7 @@ export function resetSessionTimeoutState() {
  * Exported for testing as _resolveReportBasePath.
  */
 export function _resolveReportBasePath(s) {
-    // Strip /.gsd/worktrees/ suffix when basePath is itself a worktree path and
-    // originalBasePath is falsy — prevents reports landing in the worktree (#3729).
-    const resolved = s.originalBasePath || s.basePath;
-    const markerIdx = resolved.indexOf("/.gsd/worktrees/");
-    return markerIdx !== -1 ? resolved.slice(0, markerIdx) : resolved;
+    return resolveWorktreeProjectRoot(s.basePath, s.originalBasePath);
 }
 /**
  * Resolve the authoritative project base for dispatch guards.
@@ -60,12 +57,7 @@ export function _resolveReportBasePath(s) {
  * unit is running inside an auto worktree.
  */
 export function _resolveDispatchGuardBasePath(s) {
-    // Strip /.gsd/worktrees/ suffix when basePath is itself a worktree path and
-    // originalBasePath is falsy — prevents guard checks running against the
-    // worktree instead of the project root (#3729).
-    const resolved = s.originalBasePath || s.basePath;
-    const markerIdx = resolved.indexOf("/.gsd/worktrees/");
-    return markerIdx !== -1 ? resolved.slice(0, markerIdx) : resolved;
+    return resolveWorktreeProjectRoot(s.basePath, s.originalBasePath);
 }
 const PLAN_V2_GATE_PHASES = new Set([
     "executing",

package/dist/resources/extensions/gsd/auto/session.js

@@ -15,6 +15,7 @@
  * auto-session-encapsulation.test.ts enforce that auto.ts has no module-level
  * `let` or `var` declarations.
  */
+import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 // ─── Constants ───────────────────────────────────────────────────────────────
 export const STUB_RECOVERY_THRESHOLD = 2;
 export const NEW_SESSION_TIMEOUT_MS = 120_000;
@@ -155,12 +156,7 @@ export class AutoSession {
         this.unitLifetimeDispatches.clear();
     }
     get lockBasePath() {
-        // Prefer originalBasePath (project root); fall back to basePath.
-        // Strip /.gsd/worktrees/ suffix if basePath is itself a worktree path
-        // to avoid reading/writing the lock inside the worktree (#3729).
-        const resolved = this.originalBasePath || this.basePath;
-        const markerIdx = resolved.indexOf("/.gsd/worktrees/");
-        return markerIdx !== -1 ? resolved.slice(0, markerIdx) : resolved;
+        return resolveWorktreeProjectRoot(this.basePath, this.originalBasePath);
     }
     reset() {
         this.clearTimers();

package/dist/resources/extensions/gsd/auto-dashboard.js

@@ -10,6 +10,7 @@ import { getActiveHook } from "./post-unit-hooks.js";
 import { getLedger, getProjectTotals } from "./metrics.js";
 import { getErrorMessage } from "./error-utils.js";
 import { nativeIsRepo } from "./native-git-bridge.js";
+import { getHomeDir } from "./home-dir.js";
 import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { execFileSync } from "node:child_process";
@@ -461,8 +462,8 @@ export function updateProgressWidget(ctx, unitType, unitId, state, accessors, ti
     let widgetPwd;
     {
         let fullPwd = process.cwd();
-        const widgetHome = process.env.HOME || process.env.USERPROFILE;
-        if (widgetHome && fullPwd.startsWith(widgetHome)) {
+        const widgetHome = getHomeDir();
+        if (widgetHome && (fullPwd === widgetHome || fullPwd.startsWith(widgetHome + "/") || fullPwd.startsWith(widgetHome + "\\"))) {
             fullPwd = `~${fullPwd.slice(widgetHome.length)}`;
         }
         const parts = fullPwd.split("/");

package/dist/resources/extensions/gsd/auto-dispatch.js

@@ -655,14 +655,25 @@ export const DISPATCH_RULES = [
                 return null;
             if (!state.activeSlice)
                 return null; // fall through
-            // Only activate when reactive_execution is explicitly enabled
+            // Reactive dispatch is on by default when there are enough ready tasks to
+            // benefit from parallelism. Users opt out explicitly via
+            // `reactive_execution.enabled: false`. The downstream safety checks
+            // (graph ambiguity, ready-task count, conflict-free selection) still gate
+            // every actual dispatch, so the worst-case "default-on" outcome is the
+            // same fall-through to sequential execution as before.
             const reactiveConfig = prefs?.reactive_execution;
-            if (!reactiveConfig?.enabled)
+            if (reactiveConfig?.enabled === false)
                 return null;
             const sid = state.activeSlice.id;
             const sTitle = state.activeSlice.title;
-            const maxParallel = reactiveConfig.max_parallel ?? 2;
-            const subagentModel = reactiveConfig.subagent_model ?? resolveModelWithFallbacksForUnit("subagent")?.primary;
+            const maxParallel = reactiveConfig?.max_parallel ?? 2;
+            const subagentModel = reactiveConfig?.subagent_model ?? resolveModelWithFallbacksForUnit("subagent")?.primary;
+            // Default-on safety threshold: only activate reactive dispatch when at
+            // least N tasks are ready. Users who explicitly enabled reactive_execution
+            // keep the legacy threshold of 2 (matches the prior "any parallelism is
+            // better than none" intent). Default-on installs require >=3 to avoid
+            // surprising users with parallelism on small slices.
+            const minReadyTasksForReactive = reactiveConfig?.enabled === true ? 2 : 3;
             // Dry-run mode: max_parallel=1 means graph is derived and logged but
             // execution remains sequential
             if (maxParallel <= 1)
@@ -678,8 +689,9 @@ export const DISPATCH_RULES = [
                     return null;
                 const completed = new Set(graph.filter((n) => n.done).map((n) => n.id));
                 const readyIds = getReadyTasks(graph, completed, new Set());
-                // Only activate reactive dispatch when >1 task is ready
-                if (readyIds.length <= 1)
+                // Only activate reactive dispatch when enough tasks are ready.
+                // Threshold is 2 when explicitly opted in, 3 when default-on.
+                if (readyIds.length < minReadyTasksForReactive)
                     return null;
                 const uokFlags = resolveUokFlags(prefs);
                 const selected = uokFlags.executionGraph

package/dist/resources/extensions/gsd/auto-prompts.js

@@ -23,7 +23,7 @@ import { composeInlinedContext } from "./unit-context-composer.js";
 import { logWarning } from "./workflow-logger.js";
 import { inlineGraphSubgraph } from "./graph-context.js";
 import { buildExtractionStepsBlock } from "./commands-extract-learnings.js";
-import { warnIfManifestHasMissingSkills } from "./skill-manifest.js";
+import { resolveSkillManifest, warnIfManifestHasMissingSkills } from "./skill-manifest.js";
 // ─── Preamble Cap ─────────────────────────────────────────────────────────────
 /**
  * Historical static ceiling for the preamble cap. Kept as an upper bound even
@@ -675,6 +675,26 @@ function formatSkillActivationBlock(skillNames) {
     const calls = safe.map(name => `Call Skill({ skill: '${name}' })`).join('. ');
     return `<skill_activation>${calls}.</skill_activation>`;
 }
+/**
+ * Manifest-driven recommendations block — informational only, does NOT
+ * auto-invoke. Lists per-unit-type skills that are installed but not already
+ * activated by explicit user intent (always_use_skills / prefer_skills /
+ * skill_rules / task-plan skills_used). Surfaces relevant skills to the
+ * model so they can be invoked when the model judges them useful.
+ *
+ * This is the additive complement to the existing activation directive:
+ * activation force-invokes (explicit intent), recommendations remind
+ * (manifest defaults). User intent is preserved as the stronger signal
+ * (RFC #4779 design principle); this block only adds visibility.
+ */
+function formatSkillRecommendationsBlock(unitType, skillNames) {
+    if (!unitType)
+        return "";
+    const safe = skillNames.filter(name => SAFE_SKILL_NAME.test(name));
+    if (safe.length === 0)
+        return "";
+    return `<skill_recommendations unit="${unitType}">For this unit type, also consider invoking: ${safe.join(", ")}. Use Skill({ skill: 'name' }) when relevant — these are recommendations, not requirements.</skill_recommendations>`;
+}
 export function buildSkillActivationBlock(params) {
     const prefs = params.preferences ?? loadEffectiveGSDPreferences(params.base)?.preferences;
     const contextTokens = tokenizeSkillContext(params.milestoneId, params.milestoneTitle, params.sliceId, params.sliceTitle, params.taskId, params.taskTitle);
@@ -717,10 +737,51 @@ export function buildSkillActivationBlock(params) {
             logWarning("prompt", `parseTaskPlanFile failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    // Heuristic auto-match (gated on skill_discovery: "auto").
+    // For each installed skill, check if its name or description appears in the
+    // unit's context tokens (milestone/slice/task titles). Only consider skills
+    // already on the unit-type manifest allowlist — this keeps the heuristic
+    // narrow and avoids wildly off-topic activations.
+    // Users who set `skill_discovery: "off"` or "suggest" do not get
+    // auto-matched skills (the recommendations block still surfaces manifest
+    // skills passively); only "auto" actually adds them to the activation
+    // directive set. Default `skill_discovery` is "suggest", so this is opt-in.
+    if ((prefs?.skill_discovery ?? "suggest") === "auto") {
+        const manifestAllow = resolveSkillManifest(params.unitType);
+        const allowSet = manifestAllow ? new Set(manifestAllow) : null;
+        for (const skill of visibleSkills) {
+            const normalized = normalizeSkillReference(skill.name);
+            if (matched.has(normalized) || avoided.has(normalized))
+                continue;
+            // Respect the manifest allowlist when present; wildcard (null) lets all
+            // installed skills compete for keyword match.
+            if (allowSet && !allowSet.has(normalized))
+                continue;
+            if (skillMatchesContext(skill, contextTokens)) {
+                matched.add(normalized);
+            }
+        }
+    }
     const ordered = [...matched]
         .filter(name => installedNames.has(name) && !avoided.has(name))
         .sort();
-    return formatSkillActivationBlock(ordered);
+    const activationBlock = formatSkillActivationBlock(ordered);
+    // Manifest-driven recommendations (additive, does not override explicit intent).
+    // Only surface skills the manifest declares for this unit type that are
+    // installed and not already in matched/avoided.
+    const matchedSet = new Set(ordered);
+    const manifestList = resolveSkillManifest(params.unitType);
+    const recommendations = (manifestList ?? [])
+        .filter(name => installedNames.has(name) && !avoided.has(name) && !matchedSet.has(name))
+        .sort();
+    const recommendationsBlock = formatSkillRecommendationsBlock(params.unitType, recommendations);
+    if (!activationBlock && !recommendationsBlock)
+        return "";
+    if (!activationBlock)
+        return recommendationsBlock;
+    if (!recommendationsBlock)
+        return activationBlock;
+    return `${activationBlock}\n${recommendationsBlock}`;
 }
 /**
  * Build the skill discovery template variables for research prompts.

package/dist/resources/extensions/gsd/auto-worktree.js

@@ -16,6 +16,7 @@ import { safeCopy, safeCopyRecursive } from "./safe-fs.js";
 import { gsdRoot } from "./paths.js";
 import { createWorktree, removeWorktree, resolveGitDir, worktreePath, isInsideWorktreesDir, } from "./worktree-manager.js";
 import { detectWorktreeName, nudgeGitBranchCache, } from "./worktree.js";
+import { isGsdWorktreePath, normalizeWorktreePathForCompare, resolveWorktreeProjectRoot, } from "./worktree-root.js";
 import { MergeConflictError, readIntegrationBranch, RUNTIME_EXCLUSION_PATHS } from "./git-service.js";
 import { debugLog } from "./debug-logger.js";
 import { logWarning, logError } from "./workflow-logger.js";
@@ -1038,6 +1039,7 @@ function reconcilePlanCheckboxes(projectRoot, wtPath, milestoneId) {
     }
 }
 export function createAutoWorktree(basePath, milestoneId) {
+    basePath = resolveWorktreeProjectRoot(basePath);
     // Check if repo has commits — git worktree requires a valid HEAD
     try {
         execFileSync("git", ["rev-parse", "--verify", "HEAD"], { cwd: basePath, stdio: "pipe" });
@@ -1171,6 +1173,7 @@ function copyPlanningArtifacts(srcBase, wtPath) {
  * the worktree and its branch.
  */
 export function teardownAutoWorktree(originalBasePath, milestoneId, opts = {}) {
+    originalBasePath = resolveWorktreeProjectRoot(originalBasePath);
     const branch = autoWorktreeBranch(milestoneId);
     const { preserveBranch = false } = opts;
     const previousCwd = process.cwd();
@@ -1212,18 +1215,26 @@ export function teardownAutoWorktree(originalBasePath, milestoneId, opts = {}) {
 }
 /**
  * Detect if the process is currently inside an auto-worktree.
- * Checks both module state and git branch prefix.
+ * Uses the current directory structure plus git branch prefix so detection
+ * still works after process restart when module state has been reset.
  */
 export function isInAutoWorktree(basePath) {
-    if (!originalBase)
-        return false;
     const cwd = process.cwd();
-    const resolvedBase = existsSync(basePath) ? realpathSync(basePath) : basePath;
-    const wtDir = join(resolvedBase, ".gsd", "worktrees");
-    if (!cwd.startsWith(wtDir))
+    if (!isGsdWorktreePath(cwd))
         return false;
-    const branch = nativeGetCurrentBranch(cwd);
-    return branch.startsWith("milestone/");
+    const projectRoot = resolveWorktreeProjectRoot(basePath, originalBase);
+    const cwdProjectRoot = resolveWorktreeProjectRoot(cwd, originalBase);
+    if (normalizeWorktreePathForCompare(projectRoot) !==
+        normalizeWorktreePathForCompare(cwdProjectRoot)) {
+        return false;
+    }
+    try {
+        const branch = nativeGetCurrentBranch(cwd);
+        return branch.startsWith("milestone/");
+    }
+    catch {
+        return false;
+    }
 }
 /**
  * Get the filesystem path for an auto-worktree, or null if it doesn't exist
@@ -1234,6 +1245,7 @@ export function isInAutoWorktree(basePath) {
  * mis-detection of leftover directories as active worktrees (#695).
  */
 export function getAutoWorktreePath(basePath, milestoneId) {
+    basePath = resolveWorktreeProjectRoot(basePath);
     const p = worktreePath(basePath, milestoneId);
     if (!existsSync(p))
         return null;
@@ -1260,6 +1272,7 @@ export function getAutoWorktreePath(basePath, milestoneId) {
  * Atomic: chdir + originalBase update in same try block.
  */
 export function enterAutoWorktree(basePath, milestoneId) {
+    basePath = resolveWorktreeProjectRoot(basePath);
     const p = worktreePath(basePath, milestoneId);
     if (!existsSync(p)) {
         throw new GSDError(GSD_IO_ERROR, `Auto-worktree for ${milestoneId} does not exist at ${p}`);
@@ -1298,16 +1311,20 @@ export function enterAutoWorktree(basePath, milestoneId) {
 export function getAutoWorktreeOriginalBase() {
     return originalBase;
 }
+export function _resetAutoWorktreeOriginalBaseForTests() {
+    originalBase = null;
+}
 export function getActiveAutoWorktreeContext() {
     if (!originalBase)
         return null;
     const cwd = process.cwd();
-    const resolvedBase = existsSync(originalBase)
-        ? realpathSync(originalBase)
-        : originalBase;
-    const wtDir = join(resolvedBase, ".gsd", "worktrees");
-    if (!cwd.startsWith(wtDir))
+    if (!isGsdWorktreePath(cwd))
+        return null;
+    const cwdProjectRoot = resolveWorktreeProjectRoot(cwd, originalBase);
+    if (normalizeWorktreePathForCompare(cwdProjectRoot) !==
+        normalizeWorktreePathForCompare(originalBase)) {
         return null;
+    }
     const worktreeName = detectWorktreeName(cwd);
     if (!worktreeName)
         return null;