@mthanh/vespercli 1.7.0 → 1.8.0

package/scripts/generate-claude-assets.js

@@ -13,12 +13,20 @@
  * anything at install time. The 12 core agents + the orchestrator playbook are hand-authored
  * separately in assets/claude/ and are never touched by this script.
  *
+ * NOT scanned or written by this script (by design): `assets/vendor/` — reviewed,
+ * pinned snapshots of third-party assets (e.g. `assets/vendor/i-have-adhd/`). It is
+ * outside the four scan roots (agents/prompts/skills/instructions) and the three write
+ * targets (assets/claude/{agents,commands,skills}), so the generator can never read,
+ * transform, or clobber it. Vendored assets are installed project-level at init time
+ * (see installAdhdProjectAsset in src/cli/utils/claude-target.js), never generated here.
+ *
  * Run: node scripts/generate-claude-assets.js
  */
 
 import { readdir, readFile, writeFile, mkdir, cp, stat } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { MCP_SERVERS } from '../src/cli/utils/settings.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -50,13 +58,20 @@ const TOOL_MAP = {
   'search': 'Grep, Glob',
   'todo': 'TodoWrite',
   'agent': 'Agent',
+  'agent/runSubagent': 'Agent',   // namespaced Copilot spelling of the subagent-invocation capability; equivalent to bare `agent`
   'vscode/askQuestions': 'AskUserQuestion',
   'web/fetch': 'WebFetch',
   'web': 'WebFetch, WebSearch',
 };
 
-/** Pure-VS-Code tokens with no Claude Code equivalent — dropped, not mapped */
+/**
+ * Copilot / VS Code-only tokens with no Claude Code equivalent — INTENTIONALLY dropped, not mapped.
+ * Every entry here is reviewable, greppable policy: a token in this set is dropped silently and does
+ * NOT trip the unknown-token warning below. A token that is neither here, in TOOL_MAP, nor in
+ * MCP_PASSTHROUGH is treated as a hazard and warned about (see mapToolTokens).
+ */
 const DROP_TOKENS = new Set([
+  // VS Code workspace/editor capabilities with no Claude Code analogue.
   'vscode/getProjectSetupInfo',
   'vscode/installExtension',
   'vscode/newWorkspace',
@@ -65,10 +80,25 @@ const DROP_TOKENS = new Set([
   'vscode/vscodeAPI',
   'vscode/extensions',
   'vscode',
+  // Copilot-only task/terminal/diagnostic capabilities — no Claude Code equivalent.
+  'read/problems',                 // VS Code Problems panel; Claude has no diagnostics feed
+  'execute/runTask',               // VS Code task runner; Claude uses Bash directly
+  'execute/getTaskOutput',         // paired with runTask; N/A in Claude
+  'read/getTaskOutput',            // Copilot task-runner readback (read a VS Code task's output); sibling of execute/getTaskOutput. No Claude equivalent.
+  'read/terminalLastCommand',      // VS Code terminal introspection
+  'read/terminalSelection',        // VS Code terminal introspection
+  // Copilot-only search/context capabilities with no Claude Code analogue.
+  'web/githubRepo',                // Copilot GitHub repo context provider
+  'findTestFiles',                 // Copilot test-file locator; use Glob/Grep in Claude
+  'search/searchResults',          // Copilot search-results context provider
+  'search/usages',                 // Copilot symbol-usages provider
+  // Copilot-only MCP/context providers with no Claude equivalent in this catalog.
+  'microsoft.docs.mcp',            // Copilot-bundled Microsoft Docs MCP
+  'github',                        // Copilot GitHub context provider
 ]);
 
 /** MCP-namespaced tokens pass through as mcp__<server>__* wildcards (kept as a note, not expanded) */
-const MCP_PASSTHROUGH = ['vesper-indexing/*', 'memory/*', 'sequential-thinking/*', 'context7/*'];
+const MCP_PASSTHROUGH = ['vesper-indexing/*', 'memory/*', 'sequential-thinking/*', 'context7/*', 'clickup/*'];
 
 // Pinned model IDs, not floating aliases (`opus`/`sonnet`/`haiku`) — aliases
 // silently track the newest release of each family, which means unreviewed
@@ -82,25 +112,83 @@ const MODEL_MAP = {
 };
 
 /**
- * Parse a simple `tools: [...]` frontmatter array (single or multi-line) into a token list.
+ * Normalize a single tool item: trim, then strip a matching pair of surrounding quotes.
+ * @param {string} raw
+ * @returns {string}
+ */
+function normalizeToolItem(raw) {
+  return raw.trim().replace(/^['"]|['"]$/g, '');
+}
+
+/**
+ * Parse a `tools:` frontmatter value into a token list. Accepts BOTH forms:
+ *   - bracket array:  `tools: [a, b, c]` (single or multi-line)
+ *   - YAML dash-list: `tools:` followed by `  - a` / `  - b` lines
+ *
+ * The dash-list branch is DEFECT 1's fix: without it, a `tools:` written as a
+ * YAML sequence matches no branch and the generated agent ships with no `tools:`
+ * key at all — which, per Claude Code docs, silently inherits ALL tools (including
+ * every live MCP tool). Parser-only fix: authored dash-list sources are NOT rewritten.
  * @param {string} frontmatter
  * @returns {string[]}
  */
 function extractToolTokens(frontmatter) {
-  const match = frontmatter.match(/tools:\s*\[([\s\S]*?)\]/);
-  if (!match) return [];
-  return match[1]
-    .split(',')
-    .map(t => t.trim().replace(/^['"]|['"]$/g, ''))
-    .filter(Boolean);
+  // Bracket-array form first (unchanged behavior).
+  const bracket = frontmatter.match(/tools:\s*\[([\s\S]*?)\]/);
+  if (bracket) {
+    return bracket[1]
+      .split(',')
+      .map(normalizeToolItem)
+      .filter(Boolean);
+  }
+
+  // YAML dash-list form: a bare `tools:` line (optionally carrying a trailing
+  // `# comment`, tolerated for the same reason per-item comments are), then one
+  // or more `- <token>` items. Tolerating the header comment avoids a silent
+  // fall-through to `[]` that would be indistinguishable from a genuinely empty
+  // list — the exact silent-token-loss shape this whole change exists to close.
+  const lines = frontmatter.split('\n');
+  const startIdx = lines.findIndex(l => /^\s*tools:\s*(#.*)?$/.test(l));
+  if (startIdx === -1) return [];
+
+  const tokens = [];
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    const line = lines[i];
+    const dash = line.match(/^\s*-\s+(.*)$/); // tolerate mixed indentation
+    if (dash) {
+      // Strip a trailing inline `# comment`, then normalize (trim + unquote).
+      const item = normalizeToolItem(dash[1].replace(/\s+#.*$/, ''));
+      if (item) tokens.push(item);
+      continue;
+    }
+    if (line.trim() === '') continue; // tolerate blank lines within the block
+    break; // next non-indented, non-dash key ends the block (empty list -> [])
+  }
+  return tokens;
 }
 
+/**
+ * Tracks whether ANY unknown tool token was seen during this process's generation run.
+ * Consulted by main() to fail the build under CI / --strict. Warn-and-continue means a
+ * single stray token never aborts generation mid-run and corrupts every other agent's output.
+ */
+let sawUnknownToken = false;
+
+/**
+ * Tracks whether ANY `applyTo` glob could not be translated to natural language during this run.
+ * Consulted by main() to fail the build under CI / --strict, mirroring `sawUnknownToken`. Emitting
+ * raw glob syntax into a semantically-matched Claude skill description is a regression we refuse to
+ * ship silently — an unmappable token warns loudly and hard-fails strict runs.
+ */
+let sawUnmappableGlob = false;
+
 /**
  * Convert a Copilot tool-token list into a Claude Code `tools:` frontmatter value.
  * @param {string[]} tokens
+ * @param {string} [agentName] - source agent, threaded through for useful warnings
  * @returns {string}
  */
-function mapToolTokens(tokens) {
+function mapToolTokens(tokens, agentName) {
   const claudeTools = new Set();
   const mcpNotes = new Set();
 
@@ -113,15 +201,33 @@ function mapToolTokens(tokens) {
     const mapped = TOOL_MAP[token];
     if (mapped) {
       mapped.split(',').forEach(t => claudeTools.add(t.trim()));
+      continue;
     }
+    // Unknown token: not mapped, not an MCP passthrough, not an intentional drop.
+    // This is exactly the diagnostic that would have surfaced DEFECT 2 (`clickup/*`)
+    // instead of letting it vanish. Warn and continue; CI/--strict escalates in main().
+    sawUnknownToken = true;
+    const where = agentName ? ` (in agent "${agentName}")` : '';
+    console.warn(
+      `  [unknown-tool-token] "${token}"${where} matches no TOOL_MAP, MCP_PASSTHROUGH, or DROP_TOKENS entry — dropped. ` +
+      `Map it, add it to MCP_PASSTHROUGH, or add it to DROP_TOKENS if intentional.`
+    );
   }
 
   // Expand known MCP servers to their concrete tool names (best-effort; unknown servers noted as-is).
+  //
+  // The four entries below are a DELIBERATELY CURATED read-mostly SUBSET — NOT a mirror of
+  // MCP_SERVERS (which is the full auto-approval superset: memory has 9 tools incl. delete_*/
+  // read_graph, context7 has 3). Deriving these from MCP_SERVERS by rule would grant destructive
+  // tools to every agent declaring `memory/*`, re-creating the fail-open class this file fixes.
+  // Leave them literal. `clickup` is the sole exception: it has no curated subset, so its full
+  // set is sourced from the single source of truth in settings.js (MCP_SERVERS.clickup.tools).
   const MCP_TOOL_NAMES = {
     'vesper-indexing': ['mcp__vesper-indexing__vesper_search', 'mcp__vesper-indexing__vesper_symbols', 'mcp__vesper-indexing__vesper_status', 'mcp__vesper-indexing__vesper_reindex'],
     'memory': ['mcp__memory__create_entities', 'mcp__memory__create_relations', 'mcp__memory__add_observations', 'mcp__memory__search_nodes', 'mcp__memory__open_nodes'],
     'sequential-thinking': ['mcp__sequential-thinking__sequentialthinking'],
     'context7': ['mcp__context7__resolve-library-id', 'mcp__context7__get-library-docs'],
+    'clickup': MCP_SERVERS.clickup.tools.map(t => `mcp__clickup__${t}`),
   };
   for (const server of mcpNotes) {
     (MCP_TOOL_NAMES[server] || []).forEach(t => claudeTools.add(t));
@@ -146,7 +252,7 @@ function convertAgent(content, kebabName) {
 
   const description = descriptionMatch ? descriptionMatch[1] : `${kebabName} specialist agent`;
   const model = modelMatch ? (MODEL_MAP[modelMatch[1]] || 'claude-sonnet-5') : 'claude-sonnet-5';
-  const tools = mapToolTokens(extractToolTokens(frontmatter));
+  const tools = mapToolTokens(extractToolTokens(frontmatter), kebabName);
 
   const newFrontmatter = [
     `name: ${kebabName}`,
@@ -183,6 +289,128 @@ function convertPrompt(content) {
   return newFrontmatter ? `---\n${newFrontmatter}\n---\n${cleanedBody}` : cleanedBody;
 }
 
+/**
+ * Map a bare file extension (no dot) to a human-readable language/format name. Deliberately literal
+ * and reviewable — it covers exactly the extensions the six in-tree instruction sources reference,
+ * plus a small margin of common ones. Do NOT grow this speculatively: an unmapped extension trips the
+ * LOUD `sawUnmappableGlob` path in describeApplyTo(), which is the signal to extend this map on demand.
+ */
+const EXT_LANG = {
+  py: 'Python',
+  js: 'JavaScript',
+  ts: 'TypeScript',
+  tsx: 'TSX',
+  jsx: 'JSX',
+  java: 'Java',
+  cs: 'C#',
+  cpp: 'C++',
+  c: 'C',
+  go: 'Go',
+  rb: 'Ruby',
+  css: 'CSS',
+  scss: 'SCSS',
+  md: 'Markdown',
+  json: 'JSON',
+  html: 'HTML',
+};
+
+/**
+ * Curated natural-language phrases for path-scoped applyTo globs — tokens that carry an embedded
+ * directory path (beyond a leading globstar) and therefore have no honest trailing-extension translation.
+ * A naive "trailing .md -> Markdown files" guess for the task-implementation entry would wrongly
+ * re-introduce over-breadth, so path-scoped globs are looked up here or fail LOUD. A stale/unused key
+ * is harmless residue (it simply never matches); prune only when a source stops using it.
+ */
+const GLOB_OVERRIDES = {
+  '**/.vesper/.tracking/changes/*.md': 'task change-record files under .vesper/.tracking/changes/',
+};
+
+/**
+ * Render a list as an Oxford-style human phrase: "A", "A or B", "A, B, or C".
+ * @param {string[]} items
+ * @returns {string}
+ */
+function oxfordList(items) {
+  if (items.length === 0) return '';
+  if (items.length === 1) return items[0];
+  if (items.length === 2) return `${items[0]} or ${items[1]}`;
+  return `${items.slice(0, -1).join(', ')}, or ${items[items.length - 1]}`;
+}
+
+/**
+ * Translate an `applyTo` glob list into a natural-language scope clause for a Claude skill
+ * description. Pure and exported for unit testing — no I/O, no writes.
+ *
+ * Contract:
+ *   - Extension-mappable tokens (no embedded directory path — a leading globstar is allowed — ending in
+ *     a dotted extension, incl. bare filenames like `vite.config.ts`) resolve via EXT_LANG to a name.
+ *   - Path-scoped tokens (an embedded slash beyond a leading globstar, e.g. the task-implementation
+ *     tracking-changes glob) resolve via GLOB_OVERRIDES to a curated phrase; a miss is
+ *     pushed to `unmapped` — we NEVER emit raw glob syntax and NEVER naively guess the trailing ext.
+ *   - Any unmappable token warns (naming skill + token + remediation), sets the module-level
+ *     `sawUnmappableGlob` flag (which main() escalates under CI/--strict), and is omitted from the
+ *     clause — degrade loudly, never silently.
+ *
+ * @param {string} applyTo - raw comma-separated applyTo value ('' when absent)
+ * @param {string} [skillName] - source skill name, threaded through for useful warnings
+ * @returns {{ clause: string, unmapped: string[] }} clause includes a leading space (or '' when empty)
+ */
+function describeApplyTo(applyTo, skillName) {
+  const unmapped = [];
+  if (!applyTo || !applyTo.trim()) return { clause: '', unmapped };
+
+  const tokens = applyTo.split(',').map(t => t.trim()).filter(Boolean);
+  const languages = [];
+  const phrases = [];
+
+  for (const token of tokens) {
+    // A single leading `**/` is a "match anywhere" prefix, not an embedded path — strip it before
+    // deciding whether the remainder is path-scoped.
+    const stripped = token.replace(/^\*\*\//, '');
+
+    if (stripped.includes('/')) {
+      // Path-scoped: only a curated override is acceptable; a miss is LOUD, never a raw-glob leak.
+      const override = GLOB_OVERRIDES[token];
+      if (override) {
+        if (!phrases.includes(override)) phrases.push(override);
+      } else {
+        unmapped.push(token);
+      }
+      continue;
+    }
+
+    const extMatch = stripped.match(/\.([A-Za-z0-9]+)$/);
+    if (extMatch) {
+      const lang = EXT_LANG[extMatch[1].toLowerCase()];
+      if (lang) {
+        if (!languages.includes(lang)) languages.push(lang);
+      } else {
+        unmapped.push(token);
+      }
+      continue;
+    }
+
+    // Neither path-scoped nor a recognizable `.<ext>` token.
+    unmapped.push(token);
+  }
+
+  for (const token of unmapped) {
+    sawUnmappableGlob = true;
+    const where = skillName ? ` (in skill "${skillName}")` : '';
+    console.warn(
+      `  [unmappable-applyto-glob] "${token}"${where} could not be translated to natural language — omitted. ` +
+      `Extend EXT_LANG (for a new extension) or GLOB_OVERRIDES (for a path-scoped glob) to map it.`
+    );
+  }
+
+  const pieces = [];
+  if (languages.length) pieces.push(`${oxfordList(languages)} files`);
+  for (const phrase of phrases) pieces.push(phrase);
+
+  const clause = pieces.length ? ` Use when working with ${oxfordList(pieces)}.` : '';
+  return { clause, unmapped };
+}
+
 /**
  * Convert an `.instructions.md` file into a new Skill (SKILL.md).
  * @param {string} content
@@ -197,11 +425,15 @@ function convertInstructionToSkill(content, kebabName) {
   const descriptionMatch = frontmatter.match(/description:\s*['"]?(.*?)['"]?\s*(\n|$)/);
   const applyToMatch = frontmatter.match(/applyTo:\s*['"]?(.*?)['"]?\s*(\n|$)/);
 
-  const baseDescription = descriptionMatch ? descriptionMatch[1] : `${kebabName} conventions`;
+  const rawBaseDescription = descriptionMatch ? descriptionMatch[1] : `${kebabName} conventions`;
   const applyTo = applyToMatch ? applyToMatch[1] : '';
-  const description = applyTo
-    ? `${baseDescription} Use when working with files matching: ${applyTo}.`
-    : baseDescription;
+  const { clause } = describeApplyTo(applyTo, kebabName);
+  // Normalize the base description before appending the scope clause: trim trailing whitespace and
+  // ensure it ends in terminal punctuation, so the clause's leading space doesn't run the two
+  // sentences together (e.g. "…Java base applications Use when…"). Only append when there IS a clause.
+  const trimmedBase = rawBaseDescription.trimEnd();
+  const normalizedBase = clause && !/[.!?]$/.test(trimmedBase) ? `${trimmedBase}.` : trimmedBase;
+  const description = `${normalizedBase}${clause}`;
 
   const newFrontmatter = [`name: ${kebabName}`, `description: ${description}`].join('\n');
   const cleanedBody = applyBodyTokenReplacements(body);
@@ -375,9 +607,30 @@ async function main() {
   console.log(`✓ instructions: ${instructionSkillCount} converted to skills -> assets/claude/skills/`);
 
   console.log('\nDone. Hand-authored content (assets/claude/agents/vesper-*.md, vesper-orchestrator.md, *.tpl, commands/vesper-*.md) is untouched by this script.');
+
+  // Escalate unknown tokens in CI (or when --strict is passed): an unmapped token means a
+  // mis-permissioned agent would ship. Locally we warn-and-continue; CI must hard-fail.
+  const strict = process.argv.includes('--strict') || Boolean(process.env.CI);
+  if (sawUnknownToken && strict) {
+    console.error('\n✗ Unknown tool token(s) encountered (see warnings above). Failing build (CI/--strict).');
+    process.exitCode = 1;
+  }
+  if (sawUnmappableGlob && strict) {
+    console.error('\n✗ Unmappable applyTo glob(s) encountered (see warnings above). Failing build (CI/--strict).');
+    process.exitCode = 1;
+  }
+}
+
+// Only run generation when executed directly as a script — importing the module
+// (e.g. from vitest) must NOT trigger a full catalog regeneration. Guard on
+// `process.argv[1]` first: when unset (e.g. `node --input-type=module -e`),
+// `pathToFileURL(undefined)` throws ERR_INVALID_ARG_TYPE, so the import-safety
+// guarantee must not depend on argv[1] being populated.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((error) => {
+    console.error('Generation failed:', error);
+    process.exit(1);
+  });
 }
 
-main().catch((error) => {
-  console.error('Generation failed:', error);
-  process.exit(1);
-});
+export { extractToolTokens, mapToolTokens, convertAgent, describeApplyTo, convertInstructionToSkill };

package/scripts/generate-claude-assets.test.js

@@ -0,0 +1,228 @@
+import { describe, it, expect, vi } from 'vitest';
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+import { extractToolTokens, mapToolTokens, convertAgent, describeApplyTo, convertInstructionToSkill } from './generate-claude-assets.js';
+import { MCP_SERVERS } from '../src/cli/utils/settings.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const readInstructionFixture = (name) =>
+  readFileSync(join(__dirname, '..', 'assets', 'instructions', name, `${name}.instructions.md`), 'utf-8');
+const descriptionLineOf = (skillMd) =>
+  skillMd.split('\n').find((l) => l.startsWith('description:'));
+
+describe('extractToolTokens', () => {
+  it('parses a bracket-array tools list (unchanged behavior)', () => {
+    const fm = `name: x\ntools: ['clickup/*', 'search', "read", 'memory/*']\nagents: []`;
+    expect(extractToolTokens(fm)).toEqual(['clickup/*', 'search', 'read', 'memory/*']);
+  });
+
+  it('parses a YAML dash-list tools block equivalently to the bracket form (DEFECT 1)', () => {
+    const dashList = [
+      'name: x',
+      'tools:',
+      '  - search',
+      '  - read',
+      '  - edit',
+      '  - execute',
+      '  - agent',
+      '  - todo',
+      "  - 'vesper-indexing/*'",
+      "  - 'memory/*'",
+      'agents: []',
+    ].join('\n');
+
+    const bracket = "name: x\ntools: [search, read, edit, execute, agent, todo, 'vesper-indexing/*', 'memory/*']\nagents: []";
+
+    expect(extractToolTokens(dashList)).toEqual(extractToolTokens(bracket));
+    expect(extractToolTokens(dashList)).toContain('vesper-indexing/*');
+    expect(extractToolTokens(dashList)).toContain('memory/*');
+  });
+
+  it('strips surrounding quotes on dash items', () => {
+    const fm = `tools:\n  - 'memory/*'\n  - "search"\nagents: []`;
+    expect(extractToolTokens(fm)).toEqual(['memory/*', 'search']);
+  });
+
+  it('strips trailing inline # comments on dash items', () => {
+    const fm = `tools:\n  - read  # legacy\n  - search # keep\nagents: []`;
+    expect(extractToolTokens(fm)).toEqual(['read', 'search']);
+  });
+
+  it('tolerates mixed indentation across dash items', () => {
+    const fm = `tools:\n  - read\n    - search\n      - edit\nnext: []`;
+    expect(extractToolTokens(fm)).toEqual(['read', 'search', 'edit']);
+  });
+
+  it('returns [] for an empty tools list without consuming the next key', () => {
+    const fm = `tools:\nagents: []`;
+    expect(extractToolTokens(fm)).toEqual([]);
+  });
+
+  it('tolerates a trailing inline comment on the tools: header line itself', () => {
+    const fm = `tools: # see below\n  - read\n  - search\nagents: []`;
+    expect(extractToolTokens(fm)).toEqual(['read', 'search']);
+  });
+});
+
+describe('convertAgent (end-to-end frontmatter emission — locks DEFECT 1 at the layer that broke)', () => {
+  it('emits a real tools: line for a dash-list source with real tokens (the actual defect)', () => {
+    const src = [
+      '---',
+      "description: 'demo'",
+      "model: 'Claude Haiku 4.5'",
+      'name: Demo',
+      'tools:',
+      '  - read',
+      '  - edit',
+      "  - 'memory/*'",
+      'agents: []',
+      '---',
+      'Body prose.',
+    ].join('\n');
+
+    const out = convertAgent(src, 'demo');
+    // The regression lived in convertAgent's `tools ? ... : null` ternary: a dropped
+    // key here is exactly what produced inherit-all. Assert the key is present and populated.
+    const toolsLine = out.split('\n').find(l => l.startsWith('tools:'));
+    expect(toolsLine).toBeDefined();
+    expect(toolsLine).toContain('Read');
+    expect(toolsLine).toContain('Edit');
+    expect(toolsLine).toContain('mcp__memory__create_entities');
+  });
+
+  it('omits the tools: key entirely when the source declares genuinely no tools', () => {
+    const src = [
+      '---',
+      "description: 'no tools'",
+      "model: 'Claude Haiku 4.5'",
+      'name: Bare',
+      'agents: []',
+      '---',
+      'Body prose.',
+    ].join('\n');
+
+    const out = convertAgent(src, 'bare');
+    expect(out.split('\n').some(l => l.startsWith('tools:'))).toBe(false);
+  });
+});
+
+describe('mapToolTokens', () => {
+  it('expands clickup/* to all mcp__clickup__* names from the settings.js source of truth (DEFECT 2)', () => {
+    const expected = MCP_SERVERS.clickup.tools.map(t => `mcp__clickup__${t}`);
+    const result = mapToolTokens(['clickup/*']).split(', ');
+    expect(result).toEqual(expected);
+    expect(expected).toHaveLength(32);
+  });
+
+  it('maps the namespaced agent/runSubagent token to the Agent tool (fail-closed capability restore)', () => {
+    expect(mapToolTokens(['agent/runSubagent']).split(', ')).toContain('Agent');
+  });
+
+  it('does not warn on intentional DROP_TOKENS entries', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const drops = ['read/problems', 'execute/runTask', 'web/githubRepo', 'findTestFiles', 'github'];
+    const result = mapToolTokens(drops);
+    expect(result).toBe('');
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it('drops read/getTaskOutput silently (intentional Copilot-only drop, no warning)', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const result = mapToolTokens(['read/getTaskOutput']);
+    expect(result).toBe('');
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it('warns (naming token + agent) on an unrecognized token', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    mapToolTokens(['totally/madeUpTool'], 'demo-agent');
+    expect(warn).toHaveBeenCalledTimes(1);
+    const msg = warn.mock.calls[0][0];
+    expect(msg).toContain('totally/madeUpTool');
+    expect(msg).toContain('demo-agent');
+  });
+});
+
+describe('describeApplyTo', () => {
+  it('translates a single extension glob to a language clause', () => {
+    expect(describeApplyTo('**/*.java', 'java')).toEqual({
+      clause: ' Use when working with Java files.',
+      unmapped: [],
+    });
+  });
+
+  it('dedupes and preserves first-seen order across a multi-extension list (reactjs)', () => {
+    expect(describeApplyTo('**/*.jsx, **/*.tsx, **/*.js, **/*.ts, **/*.css, **/*.scss', 'reactjs')).toEqual({
+      clause: ' Use when working with JSX, TSX, JavaScript, TypeScript, CSS, or SCSS files.',
+      unmapped: [],
+    });
+  });
+
+  it('maps a bare filename via its extension (no path component)', () => {
+    expect(describeApplyTo('vite.config.ts', 'tailwind-v4-vite')).toEqual({
+      clause: ' Use when working with TypeScript files.',
+      unmapped: [],
+    });
+  });
+
+  it('returns an empty clause for empty applyTo', () => {
+    expect(describeApplyTo('', 'anything')).toEqual({ clause: '', unmapped: [] });
+  });
+
+  it('uses the GLOB_OVERRIDES phrase for a path-scoped hit', () => {
+    expect(describeApplyTo('**/.vesper/.tracking/changes/*.md', 'task-implementation')).toEqual({
+      clause: ' Use when working with task change-record files under .vesper/.tracking/changes/.',
+      unmapped: [],
+    });
+  });
+
+  it('reports a path-scoped miss as unmapped (LOUD, not silent) and omits it from the clause', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const result = describeApplyTo('src/weird/**/*.md', 'fabricated');
+    expect(result.unmapped).toContain('src/weird/**/*.md');
+    expect(result.clause).toBe('');
+    expect(warn).toHaveBeenCalled();
+    expect(warn.mock.calls[0][0]).toContain('src/weird/**/*.md');
+  });
+
+  it('reports an unknown extension as unmapped', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const result = describeApplyTo('**/*.zig', 'fabricated');
+    expect(result.unmapped).toContain('**/*.zig');
+    expect(result.clause).toBe('');
+    expect(warn).toHaveBeenCalled();
+  });
+});
+
+// Caller-layer coverage: asserts on convertInstructionToSkill's ACTUAL emitted description, not just
+// the helper in isolation. A regression that bypasses describeApplyTo and reintroduces a raw-glob paste
+// directly in the caller (the helper-vs-caller gap that hid the tool-token defect) would pass every
+// describeApplyTo unit test but fail here.
+describe('convertInstructionToSkill (caller-layer output over real instruction fixtures)', () => {
+  it('emits a translated language clause and NO raw glob for an extension-scoped instruction (reactjs)', () => {
+    const out = convertInstructionToSkill(readInstructionFixture('reactjs'), 'reactjs');
+    const desc = descriptionLineOf(out);
+    expect(desc).toContain('Use when working with JSX, TSX, JavaScript, TypeScript, CSS, or SCSS files.');
+    expect(desc).not.toMatch(/\*\*\//); // no globstar
+    expect(desc).not.toMatch(/\*\./); // no `*.ext` raw glob
+  });
+
+  it('emits the GLOB_OVERRIDES phrase and NO raw glob for the path-scoped instruction (task-implementation)', () => {
+    const out = convertInstructionToSkill(readInstructionFixture('task-implementation'), 'task-implementation');
+    const desc = descriptionLineOf(out);
+    expect(desc).toContain('Use when working with task change-record files under .vesper/.tracking/changes/.');
+    expect(desc).not.toMatch(/\*\*\//);
+    expect(desc).not.toMatch(/\*\./);
+  });
+
+  it('normalizes a base description lacking terminal punctuation so the clause does not run on (java)', () => {
+    const out = convertInstructionToSkill(readInstructionFixture('java'), 'java');
+    const desc = descriptionLineOf(out);
+    // Base is "Guidelines for building Java base applications" (no period) — must gain one at the seam.
+    expect(desc).toContain('Java base applications. Use when working with Java files.');
+    expect(desc).not.toContain('applications Use when'); // the run-on the fix removes
+  });
+});

package/scripts/postinstall.js

@@ -21,7 +21,16 @@ const isDevEnvironment = existsSync(join(packageRoot, '.git'));
 
 // Check if MCP server is already built
 const mcpDistExists = existsSync(join(mcpDir, 'dist', 'index.js'));
-const mcpNodeModulesExists = existsSync(join(mcpDir, 'node_modules'));
+
+// Integrity canary: presence of `node_modules` alone does NOT prove a healthy
+// install — a corrupted tree missing a critical dep manifest crashes the server
+// with ERR_MODULE_NOT_FOUND yet still has the directory. Check the manifests of
+// the two direct runtime deps (`@modelcontextprotocol/sdk`, `zod`) instead, so a
+// corrupt tree falls through to the `npm install` self-heal below. Same canary set
+// as getMcpServerState() in src/cli/commands/mcp.js — keep them in sync.
+const sdkManifest = join(mcpDir, 'node_modules', '@modelcontextprotocol', 'sdk', 'package.json');
+const zodManifest = join(mcpDir, 'node_modules', 'zod', 'package.json');
+const mcpDepsHealthy = existsSync(sdkManifest) && existsSync(zodManifest);
 
 async function runCommand(command, args, cwd) {
   return new Promise((resolve, reject) => {
@@ -45,7 +54,7 @@ async function runCommand(command, args, cwd) {
 
 async function main() {
   // Skip if already built (common during npm pack/publish)
-  if (mcpDistExists && mcpNodeModulesExists) {
+  if (mcpDistExists && mcpDepsHealthy) {
     console.log('✓ vesper-indexing MCP server already built');
     return;
   }
@@ -63,8 +72,10 @@ async function main() {
   try {
     // Install dependencies. When prebuilt dist is shipped (the published
     // package), skip devDependencies — no TypeScript build is needed, only the
-    // runtime deps (incl. the native better-sqlite3, built for this platform).
-    if (!mcpNodeModulesExists) {
+    // runtime deps. The store uses the built-in node:sqlite module (migrated off
+    // better-sqlite3), so there is no native addon to compile here. `npm install`
+    // over a partially-corrupt tree self-heals by reinstalling missing packages.
+    if (!mcpDepsHealthy) {
       console.log('→ Installing dependencies...');
       const installArgs = ['install', '--no-audit', '--no-fund'];
       if (mcpDistExists) installArgs.push('--omit=dev');