@opengsd/gsd-pi 1.0.2-dev.867e002 → 1.0.2-dev.cce3612

package/src/resources/extensions/gsd/parallel-monitor-overlay.ts

@@ -13,6 +13,7 @@ import { formattedShortcutPair } from "./shortcut-defs.js";
 import { resolveGsdPathContract } from "./paths.js";
 import {
   renderBar,
+  renderDialogFrame,
   renderKeyHints,
   renderProgressBar,
   safeLine,
@@ -378,19 +379,18 @@ export class ParallelMonitorOverlay {
     const t = this.theme;
     const lines: string[] = [];
     const w = Math.max(1, width);
+    const contentWidth = Math.max(1, w - 4);
 
-    // Header
     const totalCost = this.workers.reduce((s, wk) => s + wk.cost, 0);
     const aliveCount = this.workers.filter((wk) => wk.alive).length;
     const now = new Date().toLocaleTimeString();
 
-    lines.push(t.bold(t.fg("accent", " GSD Parallel Monitor ")));
     lines.push(
       t.fg("muted", `  ${now}  │  ${aliveCount}/${this.workers.length} alive  │  Total: `) +
       t.bold(`$${totalCost.toFixed(2)}`) +
       t.fg("muted", "  │  5s refresh"),
     );
-    lines.push(renderBar(t, w));
+    lines.push(renderBar(t, contentWidth));
 
     if (this.workers.length === 0) {
       lines.push("");
@@ -444,7 +444,7 @@ export class ParallelMonitorOverlay {
           lines.push(`     ${t.fg("muted", "slices")}  ${chips.join("  ")}`);
 
           // Task progress bar
-          const barWidth = Math.max(6, Math.min(25, w - 32));
+          const barWidth = Math.max(6, Math.min(25, contentWidth - 32));
           const bar = renderProgressBar(t, wk.doneTasks, wk.totalTasks, barWidth, {
             filledChar: "█",
             emptyChar: "░",
@@ -466,7 +466,7 @@ export class ParallelMonitorOverlay {
 
     // Event feed
     lines.push("");
-    lines.push(renderBar(t, w));
+    lines.push(renderBar(t, contentWidth));
     lines.push(`  ${t.bold("Recent Events")}`);
 
     if (this.events.length === 0) {
@@ -478,7 +478,6 @@ export class ParallelMonitorOverlay {
       }
     }
 
-    // Footer
     lines.push("");
     const allDone = this.workers.length > 0 && this.workers.every((wk) => !wk.alive);
     if (allDone) {
@@ -491,17 +490,22 @@ export class ParallelMonitorOverlay {
       }
       lines.push(`  ${t.bold("Total: $" + this.workers.reduce((s, wk) => s + wk.cost, 0).toFixed(2))}`);
     }
-    lines.push(renderKeyHints(t, [`ESC/q/${formattedShortcutPair("parallel")} close`, "↑↓ scroll"], w));
 
     // Apply scroll — use terminal rows as height estimate
     const termHeight = process.stdout.rows || 40;
-    const maxScroll = Math.max(0, lines.length - termHeight);
+    const maxBodyRows = Math.max(1, Math.min(lines.length, termHeight - 12));
+    const maxScroll = Math.max(0, lines.length - maxBodyRows);
     this.scrollOffset = Math.min(Math.max(this.scrollOffset, 0), maxScroll);
     const visible = lines
-      .slice(this.scrollOffset, this.scrollOffset + termHeight)
-      .map((line) => safeLine(line, w));
-    this.cachedLines = visible;
+      .slice(this.scrollOffset, this.scrollOffset + maxBodyRows)
+      .map((line) => safeLine(line, contentWidth));
+    const footer = renderKeyHints(t, [`ESC/q/${formattedShortcutPair("parallel")} close`, "↑↓ scroll"], contentWidth);
+
+    this.cachedLines = renderDialogFrame(t, "GSD Parallel Monitor", visible, w, {
+      footer,
+      scroll: { offset: this.scrollOffset, visibleRows: maxBodyRows, totalRows: lines.length },
+    });
     this.cachedWidth = width;
-    return visible;
+    return this.cachedLines;
   }
 }

package/src/resources/extensions/gsd/preferences-skills.ts

@@ -23,10 +23,17 @@ import { validatePreferences } from "./preferences-validation.js";
 export type { GSDSkillRule, SkillDiscoveryMode, SkillResolution, SkillResolutionReport } from "./preferences-types.js";
 
 /**
- * Known skill directories, in priority order.
- * GSD bundled skills live in ~/.gsd/agent/skills/ and win name collisions.
- * User-global and project-local ecosystem directories remain available as
- * read-only discovery sources, followed by Claude Code compatibility paths.
+ * Known skill directories for **preference reference resolution** (bare skill names).
+ *
+ * Search order (first match wins):
+ * 1. ~/.gsd/agent/skills/ (GSD bundled)
+ * 2. ~/.agents/skills/ (ecosystem global)
+ * 3. .agents/skills/ (project ecosystem)
+ * 4. ~/.claude/skills/ and .claude/skills/ (Claude Code compatibility)
+ *
+ * Note: the ResourceLoader catalog uses PackageManager precedence instead —
+ * project `.gsd/skills` and `.agents/skills` can override bundled GSD skills
+ * on name collision. See docs/dev/what-is-pi/09-the-customization-stack.md.
  */
 export function getSkillSearchDirs(cwd: string): Array<{ dir: string; method: SkillResolution["method"] }> {
   const dirs: Array<{ dir: string; method: SkillResolution["method"] }> = [

package/src/resources/extensions/gsd/preferences.ts

@@ -570,9 +570,14 @@ function mergePreDispatchHooks(
 
 // ─── System Prompt Rendering ──────────────────────────────────────────────────
 
-export function renderPreferencesForSystemPrompt(preferences: GSDPreferences, resolutions?: Map<string, SkillResolution>): string {
+export function renderPreferencesForSystemPrompt(
+  preferences: GSDPreferences,
+  resolutions?: Map<string, SkillResolution>,
+  options?: { includeResolvedPaths?: boolean },
+): string {
   const validated = validatePreferences(preferences);
   const lines: string[] = ["## GSD Skill Preferences"];
+  const includeResolvedPaths = options?.includeResolvedPaths ?? true;
 
   if (validated.errors.length > 0) {
     lines.push("- Validation: some preference values were ignored because they were invalid.");
@@ -589,7 +594,17 @@ export function renderPreferencesForSystemPrompt(preferences: GSDPreferences, re
     "- Current user instructions still override these defaults.",
   );
 
-  const fmt = (ref: string) => resolutions ? formatSkillRef(ref, resolutions) : ref;
+  const fmt = (ref: string) => {
+    if (!resolutions) return ref;
+    if (!includeResolvedPaths) {
+      const resolution = resolutions.get(ref);
+      if (!resolution || resolution.method === "unresolved") {
+        return `${ref} (⚠ not found — check skill name or path)`;
+      }
+      return ref;
+    }
+    return formatSkillRef(ref, resolutions);
+  };
 
   if (preferences.always_use_skills && preferences.always_use_skills.length > 0) {
     lines.push("- Always use these skills when relevant:");

package/src/resources/extensions/gsd/prompt-loader.ts

@@ -22,6 +22,7 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { logWarning } from "./workflow-logger.js";
 import { gsdHome } from "./gsd-home.js";
+import { chooseVisionAskVariant } from "./vision-ask.js";
 
 type ExistsFn = (path: string) => boolean;
 
@@ -184,6 +185,7 @@ export function loadPrompt(name: string, vars: Record<string, string> = {}): str
     planTemplatePath: join(getTemplatesDir(), "plan.md"),
     taskPlanTemplatePath: join(getTemplatesDir(), "task-plan.md"),
     taskSummaryTemplatePath: join(getTemplatesDir(), "task-summary.md"),
+    visionAsk: chooseVisionAskVariant(),
     skillActivation: "If a `GSD Skill Preferences` block is present in system context, use it and the `<available_skills>` catalog in your system prompt to decide which skills to load and follow for this unit, without relaxing required verification or artifact rules.",
     ...vars,
   };

package/src/resources/extensions/gsd/prompts/discuss.md

@@ -1,8 +1,10 @@
 {{preamble}}
 
-Ask: "What's the vision?" once, then use the reply as vision input.
+Ask exactly this once: "{{visionAsk}}" Then use the user's reply as vision input.
 
-**Special handling:** If the **user's** message is status, branch state, clarification, or any other non-project-description, treat it as vision input and proceed instead of repeating "What's the vision?" Do **not** treat the system preamble above (e.g. "New milestone M00X.") as vision input — wait for the user.
+The opener is intentionally variable so GSD feels alive across project starts. Keep it natural, easy to answer, and assistant/developer shaped: plain language, light guidance, no corporate wording, no roleplay.
+
+**Special handling:** If the **user's** message is status, branch state, clarification, or any other non-project-description, treat it as vision input and proceed instead of repeating the opener. Do **not** treat the system preamble above (e.g. "New milestone M00X.") as vision input — wait for the user.
 
 ## Reflection Step
 

package/src/resources/extensions/gsd/prompts/guided-discuss-milestone.md

@@ -4,6 +4,8 @@ Discuss milestone {{milestoneId}} ("{{milestoneTitle}}"). Identify real gray are
 
 **Structured questions available: {{structuredQuestionsAvailable}}**
 
+**Conversation opener:** For the first user-facing question round, if you need a broad starting question, use: "{{visionAsk}}" Pair it with investigation-shaped follow-ups. Keep the tone natural and easy to answer, like an assistant/developer helping the user shape the next piece of work.
+
 {{inlinedTemplates}}
 
 ---

package/src/resources/extensions/gsd/prompts/system.md

@@ -19,9 +19,7 @@ Leave the project ready for the next agent to understand and continue. Artifacts
 
 ## Skills
 
-GSD ships with bundled skills. When the task matches, load the relevant skill file with `read` before starting. Use bare skill names; GSD resolves paths.
-
-{{bundledSkillsTable}}
+GSD ships with bundled skills. Installed skills are listed in `<available_skills>` in your system prompt — load the relevant skill file with `read` using the path shown there before starting matching work. Use bare skill names in preferences; GSD resolves paths.
 
 ## Hard Rules
 

package/src/resources/extensions/gsd/queue-reorder-ui.ts

@@ -11,9 +11,9 @@
 import type { ExtensionContext } from "@gsd/pi-coding-agent";
 import { type Theme } from "@gsd/pi-coding-agent";
 import { Key, matchesKey, truncateToWidth, type TUI } from "@gsd/pi-tui";
-import { makeUI } from "../shared/tui.js";
 import { GLYPH } from "../shared/mod.js";
 import { validateQueueOrder, type DependencyValidation } from "./queue-order.js";
+import { renderDialogFrame, renderKeyHints } from "./tui/render-kit.js";
 
 export interface ReorderItem {
   id: string;
@@ -45,6 +45,7 @@ export async function showQueueReorder(
     let grabbed = false;
     let scrollOffset = 0;
     let cachedLines: string[] | undefined;
+    let cachedWidth: number | undefined;
     let validation: DependencyValidation;
 
     // Mutable deps map — tracks removals during this session
@@ -66,6 +67,7 @@ export async function showQueueReorder(
 
     function refresh() {
       cachedLines = undefined;
+      cachedWidth = undefined;
       tui.requestRender();
     }
 
@@ -151,17 +153,15 @@ export async function showQueueReorder(
     }
 
     function render(width: number): string[] {
-      if (cachedLines) return cachedLines;
+      if (cachedLines && cachedWidth === width) return cachedLines;
 
-      const ui = makeUI(theme, width);
+      const contentWidth = Math.max(1, width - 4);
       const lines: string[] = [];
       const queueRows: string[] = [];
-      const push = (...rows: string[][]) => { for (const r of rows) lines.push(...r); };
-      const add = (s: string) => truncateToWidth(s, width);
+      const add = (s: string) => truncateToWidth(s, contentWidth);
       let cursorQueueRow = 0;
 
-      const headerText = grabbed ? "  Queue Reorder — Moving Item" : "  Queue Reorder";
-      push(ui.bar(), ui.blank(), ui.header(headerText), ui.blank());
+      const headerText = grabbed ? "Queue Reorder - Moving Item" : "Queue Reorder";
 
       // Completed milestones (dimmed)
       if (completed.length > 0) {
@@ -170,7 +170,7 @@ export async function showQueueReorder(
           const label = m.title && m.title !== m.id ? `${m.id}  ${m.title}` : m.id;
           lines.push(add(`    ${theme.fg("dim", `${GLYPH.statusDone} ${label}`)}`));
         }
-        push(ui.blank());
+        lines.push("");
       }
 
       // Pending milestones
@@ -223,7 +223,7 @@ export async function showQueueReorder(
       // Removed deps feedback
       const trailingLines: string[] = [];
       if (removedDeps.length > 0) {
-        trailingLines.push(...ui.blank());
+        trailingLines.push("");
         for (const r of removedDeps) {
           trailingLines.push(add(`  ${theme.fg("success", `${GLYPH.statusDone} Removed: ${r.milestone} depends_on ${r.dep}`)}`));
         }
@@ -232,12 +232,10 @@ export async function showQueueReorder(
       // Circular warning
       const circ = validation.violations.find(v => v.type === 'circular');
       if (circ) {
-        trailingLines.push(...ui.blank());
+        trailingLines.push("");
         trailingLines.push(add(`  ${theme.fg("error", `${GLYPH.statusWarning} ${circ.message}`)}`));
       }
 
-      trailingLines.push(...ui.blank());
-
       // Hints — context-sensitive based on grab state
       const hints: string[] = [];
       if (grabbed) {
@@ -256,10 +254,9 @@ export async function showQueueReorder(
       }
       hints.push("esc");
 
-      trailingLines.push(...ui.hints(hints), ...ui.bar());
-
       const maxOverlayRows = Math.max(10, process.stdout.rows ? Math.floor(process.stdout.rows * 0.8) : 24);
-      const availableQueueRows = Math.max(1, maxOverlayRows - lines.length - trailingLines.length);
+      const frameRows = 4;
+      const availableQueueRows = Math.max(1, maxOverlayRows - frameRows - lines.length - trailingLines.length);
       const maxScroll = Math.max(0, queueRows.length - availableQueueRows);
       if (cursorQueueRow < scrollOffset) {
         scrollOffset = cursorQueueRow;
@@ -268,13 +265,25 @@ export async function showQueueReorder(
       }
       scrollOffset = Math.min(Math.max(scrollOffset, 0), maxScroll);
 
-      lines.push(...queueRows.slice(scrollOffset, scrollOffset + availableQueueRows), ...trailingLines);
-
-      cachedLines = lines;
-      return lines;
+      const queueStartRow = lines.length;
+      const visibleQueueRows = queueRows.slice(scrollOffset, scrollOffset + availableQueueRows);
+      lines.push(...visibleQueueRows, ...trailingLines);
+
+      cachedLines = renderDialogFrame(theme, headerText, lines, width, {
+        footer: renderKeyHints(theme, hints, contentWidth),
+        scroll: {
+          offset: scrollOffset,
+          visibleRows: availableQueueRows,
+          totalRows: queueRows.length,
+          trackOffset: queueStartRow,
+          trackRows: visibleQueueRows.length,
+        },
+      });
+      cachedWidth = width;
+      return cachedLines;
     }
 
-    return { render, invalidate: () => { cachedLines = undefined; }, handleInput };
+    return { render, invalidate: () => { cachedLines = undefined; cachedWidth = undefined; }, handleInput };
   }, {
     overlay: true,
     overlayOptions: { width: "70%", minWidth: 50, maxHeight: "80%", anchor: "center" },

package/src/resources/extensions/gsd/repository-registry.ts

@@ -77,7 +77,9 @@ export function createRepositoryRegistry(
   workspacePrefs?: WorkspacePreferences,
 ): RepositoryRegistry {
   const contract = resolveGsdPathContract(basePath);
-  const projectRoot = resolveGitWorkingTreeRoot(contract.workRoot) ?? contract.projectRoot;
+  const projectRoot = contract.isWorktree
+    ? resolveGitWorkingTreeRoot(contract.workRoot) ?? contract.projectRoot
+    : contract.projectRoot;
   const mode = workspacePrefs?.mode ?? "project";
   const repoMap = new Map<string, RegisteredRepository>();
 

package/src/resources/extensions/gsd/skill-activation.ts

@@ -0,0 +1,292 @@
+/**
+ * Skill activation and discovery prompt blocks for GSD auto-mode units.
+ */
+
+import { basename } from "node:path";
+import type { Skill } from "@gsd/pi-coding-agent";
+import { parseTaskPlanFile } from "./files.js";
+import {
+  loadEffectiveGSDPreferences,
+  resolveAllSkillReferences,
+  resolveSkillDiscoveryMode,
+} from "./preferences.js";
+import type { GSDPreferences } from "./preferences.js";
+import { filterSkillsByManifest, resolveSkillManifest, warnIfManifestHasMissingSkills } from "./skill-manifest.js";
+import { getInstalledSkills } from "./skills.js";
+import { logWarning } from "./workflow-logger.js";
+
+function normalizeSkillReference(ref: string): string {
+  const normalized = ref.replace(/\\/g, "/").trim();
+  const base = basename(normalized).replace(/\.md$/i, "");
+  const name = /^SKILL$/i.test(base)
+    ? basename(normalized.replace(/\/SKILL(?:\.md)?$/i, ""))
+    : base;
+  return name.trim().toLowerCase();
+}
+
+function tokenizeSkillContext(...parts: Array<string | null | undefined>): Set<string> {
+  const tokens = new Set<string>();
+  const addVariants = (raw: string) => {
+    const value = raw.trim().toLowerCase();
+    if (!value || value.length < 2) return;
+    tokens.add(value);
+    tokens.add(value.replace(/[-_]+/g, " "));
+    tokens.add(value.replace(/\s+/g, "-"));
+    tokens.add(value.replace(/\s+/g, ""));
+  };
+
+  for (const part of parts) {
+    if (!part) continue;
+    const text = part.toLowerCase();
+    const phraseMatches = text.match(/[a-z0-9][a-z0-9+.#/_-]{1,}/g) ?? [];
+    for (const match of phraseMatches) {
+      addVariants(match);
+      for (const piece of match.split(/[^a-z0-9+.#]+/g)) {
+        if (piece.length >= 3) addVariants(piece);
+      }
+    }
+  }
+
+  return tokens;
+}
+
+function skillMatchesContext(skill: Skill, contextTokens: Set<string>): boolean {
+  const haystacks = [
+    skill.name.toLowerCase(),
+    skill.name.toLowerCase().replace(/[-_]+/g, " "),
+    skill.description.toLowerCase(),
+  ];
+
+  return [...contextTokens].some(token =>
+    token.length >= 3 && haystacks.some(haystack => haystack.includes(token)),
+  );
+}
+
+function resolvePreferenceSkillNames(refs: string[], base: string): string[] {
+  if (refs.length === 0) return [];
+  const prefs: GSDPreferences = { always_use_skills: refs };
+  const report = resolveAllSkillReferences(prefs, base);
+  return refs.map(ref => {
+    const resolution = report.resolutions.get(ref);
+    return normalizeSkillReference(resolution?.resolvedPath ?? ref);
+  }).filter(Boolean);
+}
+
+function ruleMatchesContext(when: string, contextTokens: Set<string>): boolean {
+  const whenTokens = tokenizeSkillContext(when);
+  return [...whenTokens].some(token =>
+    contextTokens.has(token) || [...contextTokens].some(ctx => ctx.includes(token) || token.includes(ctx)),
+  );
+}
+
+function resolveSkillRuleMatches(
+  prefs: GSDPreferences | undefined,
+  contextTokens: Set<string>,
+  base: string,
+): { include: string[]; avoid: string[] } {
+  if (!prefs?.skill_rules?.length) return { include: [], avoid: [] };
+
+  const include: string[] = [];
+  const avoid: string[] = [];
+  for (const rule of prefs.skill_rules) {
+    if (!ruleMatchesContext(rule.when, contextTokens)) continue;
+    include.push(...resolvePreferenceSkillNames([...(rule.use ?? []), ...(rule.prefer ?? [])], base));
+    avoid.push(...resolvePreferenceSkillNames(rule.avoid ?? [], base));
+  }
+  return { include, avoid };
+}
+
+function resolvePreferredSkillNames(
+  prefs: GSDPreferences | undefined,
+  visibleSkills: Skill[],
+  contextTokens: Set<string>,
+  base: string,
+): string[] {
+  if (!prefs?.prefer_skills?.length) return [];
+  const preferred = new Set(resolvePreferenceSkillNames(prefs.prefer_skills, base));
+  return visibleSkills
+    .filter(skill => preferred.has(normalizeSkillReference(skill.name)) && skillMatchesContext(skill, contextTokens))
+    .map(skill => normalizeSkillReference(skill.name));
+}
+
+/** Skill names must be lowercase alphanumeric with hyphens — reject anything else
+ *  to prevent prompt injection via crafted directory names. */
+const SAFE_SKILL_NAME = /^[a-z0-9][a-z0-9-]*$/;
+
+function formatSkillActivationBlock(skillNames: string[]): string {
+  const safe = skillNames.filter(name => SAFE_SKILL_NAME.test(name));
+  if (safe.length === 0) return "";
+  // Use explicit parameter syntax so LLMs pass { skill: "..." } instead of { name: "..." }.
+  // The function-call-like syntax `Skill('name')` led LLMs to infer a positional
+  // parameter name, causing tool validation failures — see #2224.
+  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: string | undefined, skillNames: string[]): string {
+  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: {
+  base: string;
+  milestoneId: string;
+  milestoneTitle?: string;
+  sliceId?: string;
+  sliceTitle?: string;
+  taskId?: string;
+  taskTitle?: string;
+  extraContext?: string[];
+  taskPlanContent?: string | null;
+  preferences?: GSDPreferences;
+  /**
+   * Unit type dispatching this prompt. When provided, skills are filtered
+   * through the per-unit-type manifest (see `skill-manifest.ts`). Unknown
+   * or omitted values retain the pre-manifest behavior (all skills eligible).
+   */
+  unitType?: string;
+  /** Installed skills from resourceLoader; defaults to loader cache via skills facade. */
+  skills?: Skill[];
+}): string {
+  const prefs = params.preferences ?? loadEffectiveGSDPreferences(params.base)?.preferences;
+  const contextTokens = tokenizeSkillContext(
+    params.milestoneId,
+    params.milestoneTitle,
+    params.sliceId,
+    params.sliceTitle,
+    params.taskId,
+    params.taskTitle,
+  );
+
+  const loaded = getInstalledSkills(params.skills).filter(skill => !skill.disableModelInvocation);
+
+  // Skill activation here is driven entirely by explicit sources
+  // (always_use_skills, prefer_skills, skill_rules, task-plan skills_used).
+  // Every match is an explicit user/project intent and must not be dropped
+  // by the unit-type manifest — user intent is stronger signal than
+  // defaults. The manifest's real home is the skill catalog rendering
+  // layer (pi-coding-agent `formatSkillsForPrompt`); that wiring is tracked
+  // as the "load-time short-circuit" follow-up to RFC #4779.
+  //
+  // `unitType` stays plumbed so the strict-mode warning can surface
+  // manifest entries that reference uninstalled skills, and so the
+  // activation-block site is ready to opt in once PR B lands.
+  const visibleSkills = loaded;
+  const manifestScopedSkills = filterSkillsByManifest(visibleSkills, params.unitType);
+  const installedNames = new Set(visibleSkills.map(skill => normalizeSkillReference(skill.name)));
+  warnIfManifestHasMissingSkills(params.unitType, installedNames);
+  const avoided = new Set(resolvePreferenceSkillNames(prefs?.avoid_skills ?? [], params.base));
+  const matched = new Set<string>();
+
+  for (const name of resolvePreferenceSkillNames(prefs?.always_use_skills ?? [], params.base)) {
+    matched.add(name);
+  }
+
+  const ruleMatches = resolveSkillRuleMatches(prefs, contextTokens, params.base);
+  for (const name of ruleMatches.include) matched.add(name);
+  for (const name of ruleMatches.avoid) avoided.add(name);
+
+  for (const name of resolvePreferredSkillNames(prefs, visibleSkills, contextTokens, params.base)) {
+    matched.add(name);
+  }
+
+  if (params.taskPlanContent) {
+    try {
+      const taskPlan = parseTaskPlanFile(params.taskPlanContent);
+      for (const skillName of taskPlan.frontmatter.skills_used) {
+        matched.add(normalizeSkillReference(skillName));
+      }
+    } catch (err) {
+      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") {
+    for (const skill of manifestScopedSkills) {
+      const normalized = normalizeSkillReference(skill.name);
+      if (matched.has(normalized) || avoided.has(normalized)) continue;
+      if (skillMatchesContext(skill, contextTokens)) {
+        matched.add(normalized);
+      }
+    }
+  }
+
+  const ordered = [...matched]
+    .filter(name => installedNames.has(name) && !avoided.has(name))
+    .sort();
+  const activationBlock = formatSkillActivationBlock(ordered);
+
+  // Omit recommendations when the system catalog is manifest-scoped for this
+  // unit — skill names are already listed in <available_skills>.
+  let recommendationsBlock = "";
+  if (resolveSkillManifest(params.unitType) === null) {
+    const matchedSet = new Set(ordered);
+    const recommendations = (resolveSkillManifest(params.unitType) ?? [])
+      .filter(name => installedNames.has(name) && !avoided.has(name) && !matchedSet.has(name))
+      .sort();
+    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.
+ * Returns { skillDiscoveryMode, skillDiscoveryInstructions } for template substitution.
+ */
+export function buildSkillDiscoveryVars(): { skillDiscoveryMode: string; skillDiscoveryInstructions: string } {
+  const mode = resolveSkillDiscoveryMode();
+
+  if (mode === "off") {
+    return {
+      skillDiscoveryMode: "off",
+      skillDiscoveryInstructions: " Skill discovery is disabled. Skip this step.",
+    };
+  }
+
+  if (mode === "suggest") {
+    return {
+      skillDiscoveryMode: mode,
+      skillDiscoveryInstructions: `
+   Check \`<available_skills>\` for installed skills matching core technologies. For gaps, run \`npx skills find "<technology>"\` and note promising install commands in your research output — do NOT install.`,
+    };
+  }
+
+  const autoInstall = mode === "auto";
+  const instructions = autoInstall
+    ? `
+   Check \`<available_skills>\` first. For missing core-technology skills, run \`npx skills find "<technology>"\`, install relevant matches with \`npx skills add <owner/repo@skill> -g -y\`, and record them in "Skills Discovered".`
+    : `
+   Check \`<available_skills>\` first. For missing core-technology skills, run \`npx skills find "<technology>"\` and note install commands in your research output — do NOT install.`;
+
+  return {
+    skillDiscoveryMode: mode,
+    skillDiscoveryInstructions: instructions,
+  };
+}