@mthanh/vespercli 1.8.0 → 2.0.0

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

@@ -1,228 +1,665 @@
-import { describe, it, expect, vi } from 'vitest';
+/**
+ * Generator test suite — REWRITTEN FOR THE FLIPPED DIRECTION (epic (d) Stage 2).
+ *
+ * The pre-flip suite asserted Copilot-source -> Claude-output. That direction no longer exists:
+ * `assets/claude/` + `assets/claude-committed/` are now the canonical hand-authored source and
+ * `assets/copilot/` is the generated output. Every describe block below asserts the reverse
+ * transform, so none of these tests can pass against the old generator (the old module exported
+ * neither these symbols nor this direction).
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
 
-import { readFileSync } from 'node:fs';
+import { readFileSync, readdirSync, existsSync } 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 {
+  SCAN_ROOT_RELATIVE_PATHS,
+  EXCLUDED_SOURCE_PATHS,
+  CANONICAL_ROOTS,
+  isExcludedSource,
+  splitFrontmatter,
+  readFrontmatterValue,
+  extractClaudeToolTokens,
+  mapClaudeToolsToCopilot,
+  mapMcpTools,
+  convertAgentToCopilot,
+  isCommittedMaintenanceSkill,
+  convertMaintenanceSkillToPrompt,
+  convertSkillToInstructions,
+  convertSkillMd,
+  applyCopilotBodyTokenReplacements,
+  __resetDiagnostics,
+  __getDiagnostics,
+} from './generate-claude-assets.js';
+import { getDiagnosticMessages } from '../src/cli/utils/copilot-render.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 ASSETS = join(__dirname, '..', 'assets');
+const readAsset = (...parts) => readFileSync(join(ASSETS, ...parts), 'utf-8');
+
+// Epic H: the catalog is the core plus the packs. These resolve a canonical asset wherever it
+// ships (`claude/<type>/…` or `claude/packs/<pack>/<type>/…`).
+const packNames = () => (existsSync(join(ASSETS, SCAN_ROOT_RELATIVE_PATHS.packs))
+  ? readdirSync(join(ASSETS, SCAN_ROOT_RELATIVE_PATHS.packs), { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort()
+  : []);
+const skillDirOf = (name) => {
+  const core = join(ASSETS, SCAN_ROOT_RELATIVE_PATHS.pluginSkills, name);
+  if (existsSync(core)) return core;
+  for (const pack of packNames()) {
+    const abs = join(ASSETS, SCAN_ROOT_RELATIVE_PATHS.packs, pack, 'skills', name);
+    if (existsSync(abs)) return abs;
+  }
+  throw new Error(`skill ${name} not found in the core or any pack`);
+};
+const readSkill = (name, ...rest) => readFileSync(join(skillDirOf(name), ...rest), 'utf-8');
+/** Every canonical agent file (core + packs) as `{file, abs}`. */
+const allAgentFiles = () => {
+  const out = [];
+  const roots = [join(ASSETS, SCAN_ROOT_RELATIVE_PATHS.pluginAgents), ...packNames().map((p) => join(ASSETS, SCAN_ROOT_RELATIVE_PATHS.packs, p, 'agents'))];
+  for (const dir of roots) {
+    if (!existsSync(dir)) continue;
+    for (const file of readdirSync(dir).filter((f) => f.endsWith('.md'))) out.push({ file, abs: join(dir, file) });
+  }
+  return out;
+};
+/** Every canonical skill dir name (core + packs, deduplicated — the shared copies). */
+const allSkillDirs = () => {
+  const out = new Map();
+  const roots = [join(ASSETS, SCAN_ROOT_RELATIVE_PATHS.pluginSkills), ...packNames().map((p) => join(ASSETS, SCAN_ROOT_RELATIVE_PATHS.packs, p, 'skills'))];
+  for (const root of roots) {
+    if (!existsSync(root)) continue;
+    for (const e of readdirSync(root, { withFileTypes: true })) if (e.isDirectory() && !out.has(e.name)) out.set(e.name, join(root, e.name));
+  }
+  return out;
+};
+const frontmatterOf = (content) => splitFrontmatter(content).frontmatter;
+const lineOf = (doc, key) => doc.split('\n').find((l) => l.startsWith(`${key}:`));
+
+beforeEach(() => {
+  __resetDiagnostics();
+});
+
+// ---------------------------------------------------------------------------
+// Task 2.0 — the two-root scan surface and its exclusion set
+// ---------------------------------------------------------------------------
 
-    const bracket = "name: x\ntools: [search, read, edit, execute, agent, todo, 'vesper-indexing/*', 'memory/*']\nagents: []";
+describe('scan roots + exclusion predicate (Task 2.0)', () => {
+  it('declares exactly the four canonical scan roots (core agents, core skills, the packs root, committed skills)', () => {
+    expect(SCAN_ROOT_RELATIVE_PATHS).toEqual({
+      pluginAgents: 'claude/agents',
+      pluginSkills: 'claude/skills',
+      packs: 'claude/packs',
+      committedSkills: 'claude-committed/skills',
+    });
+  });
+
+  // Epic H: each pack's own manifest dir is excluded like the core's; its agents/skills are input.
+  it('excludes every pack\'s .claude-plugin dir but not its agents/skills (kills: packs scanned as a flat root)', () => {
+    expect(isExcludedSource('claude/packs/frontend/.claude-plugin')).toBe(true);
+    expect(isExcludedSource('claude/packs/frontend/.claude-plugin/plugin.json')).toBe(true);
+    expect(isExcludedSource('claude/packs/frontend/agents/expert-react-frontend-engineer.md')).toBe(false);
+    expect(isExcludedSource('claude/packs/frontend/skills/reactjs/SKILL.md')).toBe(false);
+  });
 
-    expect(extractToolTokens(dashList)).toEqual(extractToolTokens(bracket));
-    expect(extractToolTokens(dashList)).toContain('vesper-indexing/*');
-    expect(extractToolTokens(dashList)).toContain('memory/*');
+  it('every declared scan root exists on disk', () => {
+    for (const rel of Object.values(SCAN_ROOT_RELATIVE_PATHS)) {
+      expect(existsSync(join(ASSETS, rel)), rel).toBe(true);
+    }
   });
 
-  it('strips surrounding quotes on dash items', () => {
-    const fm = `tools:\n  - 'memory/*'\n  - "search"\nagents: []`;
-    expect(extractToolTokens(fm)).toEqual(['memory/*', 'search']);
+  it.each([
+    ['claude/.claude-plugin', 'plugin manifest dir'],
+    ['claude/.claude-plugin/plugin.json', 'plugin manifest file'],
+    ['claude/vesper-orchestrator.md', 'the always-on playbook'],
+    ['claude/orchestration.md.tpl', 'the roster template'],
+    ['claude/context.md.tpl', 'the whitepaper template'],
+    ['claude-committed/agents', 'the thin pickable persona dir (DEC-7)'],
+    ['claude-committed/agents/vesper-orchestrator.md', 'the thin pickable persona'],
+    ['legacy', 'the 1.x proof table'],
+    ['legacy/claude-1x-digests.json', 'the pinned 1.x digests'],
+    ['hooks', 'git hook assets'],
+  ])('excludes %s (%s)', (rel) => {
+    expect(isExcludedSource(rel)).toBe(true);
+    expect(isExcludedSource(join(ASSETS, rel))).toBe(true);
   });
 
-  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.each([
+    'claude/agents/code-tester.md',
+    'claude/skills/code-review/SKILL.md',
+    'claude-committed/skills/reinit/SKILL.md',
+  ])('does NOT exclude the real emission input %s', (rel) => {
+    expect(isExcludedSource(rel)).toBe(false);
   });
 
-  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('excludes a directory by prefix, not by substring (no false positives)', () => {
+    // `claude-committed/agents` is excluded; a *different* dir that merely starts with the
+    // same characters must not be swept up by a naive startsWith check.
+    expect(isExcludedSource('claude-committed/agents-archive/x.md')).toBe(false);
+    expect(EXCLUDED_SOURCE_PATHS).toContain('claude-committed/agents');
   });
 
-  it('returns [] for an empty tools list without consuming the next key', () => {
-    const fm = `tools:\nagents: []`;
-    expect(extractToolTokens(fm)).toEqual([]);
+  // COMPLETENESS (epic (d) review): the old exclusion list filtered nothing real — the scan
+  // only ever listed children of the scan roots. Now every child of each canonical root must
+  // be EITHER a scan root OR explicitly excluded, so a catalog author who adds a tree is
+  // told, instead of the generator silently ignoring it.
+  it('every child of the two canonical roots is a scan root or explicitly excluded', () => {
+    const scanRoots = new Set(Object.values(SCAN_ROOT_RELATIVE_PATHS));
+    const excluded = new Set(EXCLUDED_SOURCE_PATHS);
+    const unaccounted = [];
+    for (const root of CANONICAL_ROOTS) {
+      for (const child of readdirSync(join(ASSETS, root))) {
+        const rel = `${root}/${child}`;
+        if (!scanRoots.has(rel) && !excluded.has(rel)) unaccounted.push(rel);
+      }
+    }
+    expect(unaccounted, 'add each to SCAN_ROOT_RELATIVE_PATHS or EXCLUDED_SOURCE_PATHS').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']);
+  it('every exclusion names something that actually exists (no dead entries)', () => {
+    for (const rel of EXCLUDED_SOURCE_PATHS) expect(existsSync(join(ASSETS, rel)), rel).toBe(true);
   });
 });
 
-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');
+// ---------------------------------------------------------------------------
+// Frontmatter reading (folded scalars are load-bearing for the maintenance skills)
+// ---------------------------------------------------------------------------
 
-    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');
+describe('readFrontmatterValue', () => {
+  it('reads an inline scalar and strips surrounding quotes', () => {
+    expect(readFrontmatterValue("description: 'hello there'", 'description')).toBe('hello there');
   });
 
-  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');
+  it('flattens a YAML folded block into one line (the committed maintenance-skill shape)', () => {
+    const fm = ['description: >', '  first line', '  second line', 'disable-model-invocation: true'].join('\n');
+    expect(readFrontmatterValue(fm, 'description')).toBe('first line second line');
+  });
 
-    const out = convertAgent(src, 'bare');
-    expect(out.split('\n').some(l => l.startsWith('tools:'))).toBe(false);
+  it('returns null for a missing key and for absent frontmatter', () => {
+    expect(readFrontmatterValue('name: x', 'description')).toBeNull();
+    expect(readFrontmatterValue(null, 'description')).toBeNull();
+  });
+
+  it('reads a real committed maintenance skill description (folded, non-empty)', () => {
+    const fm = frontmatterOf(readAsset('claude-committed', 'skills', 'reinit', 'SKILL.md'));
+    expect(readFrontmatterValue(fm, 'description')).toContain('re-initialize');
   });
 });
 
-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);
+describe('extractClaudeToolTokens', () => {
+  it('parses the canonical comma-separated Claude tools value', () => {
+    const fm = 'name: x\ntools: Read, Edit, Bash, mcp__memory__search_nodes\nskills: [agent-fundamentals]';
+    expect(extractClaudeToolTokens(fm)).toEqual(['Read', 'Edit', 'Bash', 'mcp__memory__search_nodes']);
   });
 
-  it('maps the namespaced agent/runSubagent token to the Agent tool (fail-closed capability restore)', () => {
-    expect(mapToolTokens(['agent/runSubagent']).split(', ')).toContain('Agent');
+  it('returns [] when no tools key is present', () => {
+    expect(extractClaudeToolTokens('name: x')).toEqual([]);
   });
+});
 
-  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();
+// ---------------------------------------------------------------------------
+// Task 2.2 — reverse token map: 1:1 names, collapse rules, documented over-grants
+// ---------------------------------------------------------------------------
+
+describe('mapClaudeToolsToCopilot — 1:1 reverse names', () => {
+  it.each([
+    ['Read', 'read/readFile'],
+    ['Bash', 'execute/runInTerminal'],
+    ['Grep', 'search/codebase'],
+    ['Glob', 'search/fileSearch'],
+    ['TodoWrite', 'todo'],
+    ['AskUserQuestion', 'vscode/askQuestions'],
+    ['Agent', 'agent/runSubagent'],
+  ])('%s -> %s', (claude, copilot) => {
+    expect(mapClaudeToolsToCopilot([claude])).toEqual([copilot]);
+  });
+
+  it('emits a deterministic order regardless of source order', () => {
+    const a = mapClaudeToolsToCopilot(['Bash', 'Read', 'TodoWrite', 'Grep']);
+    const b = mapClaudeToolsToCopilot(['Grep', 'TodoWrite', 'Read', 'Bash']);
+    expect(a).toEqual(b);
+    expect(a).toEqual(['read/readFile', 'search/codebase', 'execute/runInTerminal', 'todo']);
+  });
+
+  it('records an unrecognized Claude tool name as a diagnostic (the generator fails on it)', () => {
+    expect(mapClaudeToolsToCopilot(['TotallyMadeUp'], 'demo-agent')).toEqual([]);
+    expect(__getDiagnostics().sawUnknownToken).toBe(true);
+    const [message] = getDiagnosticMessages();
+    expect(message).toContain('TotallyMadeUp');
+    expect(message).toContain('demo-agent');
+  });
+});
+
+describe('mapClaudeToolsToCopilot — collapse rules and the two documented over-grants (G-3)', () => {
+  it('Edit + Write collapse to the single edit/editFiles token', () => {
+    expect(mapClaudeToolsToCopilot(['Edit', 'Write'])).toEqual(['edit/editFiles']);
+  });
+
+  it('Write alone narrows to edit/createFile', () => {
+    expect(mapClaudeToolsToCopilot(['Write'])).toEqual(['edit/createFile']);
+  });
+
+  it('OVER-GRANT: Edit alone emits edit/editFiles, silently regranting Write', () => {
+    // Copilot has no "edit without create" token. This is an accepted, documented consequence
+    // of the forward map's Edit+Write -> edit/editFiles collapse, not a bug — lock it so the
+    // over-grant can never change silently.
+    expect(mapClaudeToolsToCopilot(['Edit'])).toEqual(['edit/editFiles']);
+    expect(mapClaudeToolsToCopilot(['Edit'])).toEqual(mapClaudeToolsToCopilot(['Edit', 'Write']));
   });
 
-  it('drops read/getTaskOutput silently (intentional Copilot-only drop, no warning)', () => {
+  it('WebFetch + WebSearch collapse to the single web token', () => {
+    expect(mapClaudeToolsToCopilot(['WebFetch', 'WebSearch'])).toEqual(['web']);
+  });
+
+  it('WebFetch alone narrows to web/fetch', () => {
+    expect(mapClaudeToolsToCopilot(['WebFetch'])).toEqual(['web/fetch']);
+  });
+
+  it('OVER-GRANT: WebSearch alone emits web, silently regranting WebFetch', () => {
+    expect(mapClaudeToolsToCopilot(['WebSearch'])).toEqual(['web']);
+    expect(mapClaudeToolsToCopilot(['WebSearch'])).toEqual(mapClaudeToolsToCopilot(['WebFetch', 'WebSearch']));
+  });
+
+  it('does not warn on any collapse-rule input (they are rules, not unknown tokens)', () => {
     const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const result = mapToolTokens(['read/getTaskOutput']);
-    expect(result).toBe('');
+    mapClaudeToolsToCopilot(['Edit', 'Write', 'WebFetch', 'WebSearch']);
     expect(warn).not.toHaveBeenCalled();
+    expect(__getDiagnostics().sawUnknownToken).toBe(false);
+    warn.mockRestore();
   });
+});
 
-  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');
+// ---------------------------------------------------------------------------
+// Task 2.3 — per-agent MCP allow-list (wildcard vs explicit)
+// ---------------------------------------------------------------------------
+
+describe('mapMcpTools — per-agent MCP allow-list (Task 2.3)', () => {
+  it('collapses to server/* only when the agent covers EVERY tool the server exposes', () => {
+    const all = MCP_SERVERS['vesper-indexing'].tools.map((t) => `mcp__vesper-indexing__${t}`);
+    expect(mapMcpTools(all)).toEqual(['vesper-indexing/*']);
+  });
+
+  it('keeps a narrowed surface explicit rather than widening it to a wildcard', () => {
+    expect(mapMcpTools(['mcp__vesper-indexing__vesper_search', 'mcp__vesper-indexing__vesper_symbols']))
+      .toEqual(['vesper-indexing/vesper_search', 'vesper-indexing/vesper_symbols']);
+  });
+
+  it('keeps the curated memory subset explicit (it is NOT the full 9-tool server surface)', () => {
+    const curated = ['create_entities', 'create_relations', 'add_observations', 'search_nodes', 'open_nodes'];
+    expect(MCP_SERVERS.memory.tools.length).toBeGreaterThan(curated.length);
+    const out = mapMcpTools(curated.map((t) => `mcp__memory__${t}`));
+    expect(out).not.toContain('memory/*');
+    expect(out).toEqual([
+      'memory/add_observations',
+      'memory/create_entities',
+      'memory/create_relations',
+      'memory/open_nodes',
+      'memory/search_nodes',
+    ]);
+  });
+
+  it('preserves hyphens in server names and the tool segment verbatim', () => {
+    expect(mapMcpTools(['mcp__sequential-thinking__sequentialthinking'])).toEqual(['sequential-thinking/*']);
+  });
+
+  it('never wildcards a server absent from MCP_SERVERS (full coverage is unprovable)', () => {
+    expect(mapMcpTools(['mcp__unknown-server__do_thing'])).toEqual(['unknown-server/do_thing']);
+  });
+
+  it('is deterministic across servers and tools', () => {
+    const tokens = ['mcp__memory__search_nodes', 'mcp__vesper-indexing__vesper_search'];
+    expect(mapMcpTools(tokens)).toEqual(mapMcpTools([...tokens].reverse()));
+  });
+
+  it('ignores malformed mcp__ tokens instead of emitting a broken allow-list entry', () => {
+    expect(mapMcpTools(['mcp__nosplit'])).toEqual([]);
   });
 });
 
-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: [],
-    });
+// ---------------------------------------------------------------------------
+// Task 2.1 — reversed agent conversion (hidden specialists only)
+// ---------------------------------------------------------------------------
+
+describe('convertAgentToCopilot (Task 2.1)', () => {
+  const fixture = [
+    '---',
+    'name: demo',
+    'description: A demo specialist.',
+    'model: claude-opus-4-8',
+    'tools: Read, Edit, Write, Bash, mcp__memory__search_nodes',
+    'skills: [agent-fundamentals]',
+    '---',
+    'Body prose mentioning .claude/skills and TodoWrite.',
+    '',
+  ].join('\n');
+
+  it('emits Copilot frontmatter with the reversed model, tokens and kebab name', () => {
+    const out = convertAgentToCopilot(fixture, 'demo');
+    expect(lineOf(out, 'description')).toBe("description: 'A demo specialist.'");
+    expect(lineOf(out, 'name')).toBe('name: demo');
+    expect(lineOf(out, 'model')).toBe("model: 'Claude Opus 4.8'");
+    expect(lineOf(out, 'tools')).toBe(
+      "tools: ['read/readFile', 'edit/editFiles', 'execute/runInTerminal', 'memory/search_nodes']"
+    );
+    expect(lineOf(out, 'agents')).toBe('agents: []');
   });
 
-  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('marks EVERY emitted agent as a hidden specialist (DEC-7 / BR-1)', () => {
+    expect(convertAgentToCopilot(fixture, 'demo')).toContain('user-invocable: false');
+    expect(convertAgentToCopilot(fixture, 'demo')).not.toContain('user-invocable: true');
   });
 
-  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('drops the Claude-only skills: preload key (no Copilot analogue)', () => {
+    expect(convertAgentToCopilot(fixture, 'demo')).not.toContain('skills:');
   });
 
-  it('returns an empty clause for empty applyTo', () => {
-    expect(describeApplyTo('', 'anything')).toEqual({ clause: '', unmapped: [] });
+  it('inverts body path/tool tokens toward the Copilot .vesper/ homes', () => {
+    const out = convertAgentToCopilot(fixture, 'demo');
+    expect(out).toContain('.vesper/skills');
+    expect(out).not.toContain('.claude/skills');
+    expect(out).toContain('manage_todo_list');
   });
 
-  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('omits the tools key entirely when the source declares no tools', () => {
+    const bare = '---\nname: bare\ndescription: none\nmodel: claude-sonnet-5\n---\nBody.\n';
+    expect(convertAgentToCopilot(bare, 'bare').split('\n').some((l) => l.startsWith('tools:'))).toBe(false);
   });
 
-  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('falls back on an unmapped model id and records it (trips the strict flag)', () => {
+    const src = '---\nname: x\ndescription: d\nmodel: claude-from-the-future\n---\nBody.\n';
+    expect(lineOf(convertAgentToCopilot(src, 'x'), 'model')).toBe("model: 'Claude Sonnet 4.6'");
+    expect(__getDiagnostics().sawUnknownModel).toBe(true);
+  });
+
+  it('THROWS on an agent with no parseable frontmatter (verbatim emission would be pickable)', () => {
+    expect(() => convertAgentToCopilot('# no frontmatter\n', 'rogue')).toThrow(/no parseable frontmatter/);
+  });
+
+  it('reads CRLF frontmatter (a Windows-saved agent is still hidden, not emitted verbatim)', () => {
+    const crlf = '---\r\nname: demo\r\ndescription: Crlf agent.\r\nmodel: claude-sonnet-5\r\n---\r\nBody.\r\n';
+    const out = convertAgentToCopilot(crlf, 'demo');
+    expect(out).toContain('user-invocable: false');
+    expect(out).not.toContain('\r');
+  });
+
+  it('quotes the emitted description so a colon in it stays valid YAML', () => {
+    const src = '---\nname: x\ndescription: Reviews code: fast\n---\nBody.\n';
+    expect(lineOf(convertAgentToCopilot(src, 'x'), 'description')).toBe("description: 'Reviews code: fast'");
   });
 
-  it('reports an unknown extension as unmapped', () => {
+  it('converts every real canonical agent to a hidden specialist with no unknown tokens', () => {
     const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const result = describeApplyTo('**/*.zig', 'fabricated');
-    expect(result.unmapped).toContain('**/*.zig');
-    expect(result.clause).toBe('');
-    expect(warn).toHaveBeenCalled();
+    const files = allAgentFiles(); // the core plus every pack (epic H)
+    expect(files.length).toBeGreaterThan(30);
+    for (const { file, abs } of files) {
+      const out = convertAgentToCopilot(readFileSync(abs, 'utf-8'), file.replace(/\.md$/, ''));
+      expect(out, file).toContain('user-invocable: false');
+      expect(out, file).toMatch(/^---\ndescription: /);
+    }
+    expect(__getDiagnostics()).toEqual({ sawUnknownToken: false, sawUnknownModel: false });
+    warn.mockRestore();
   });
 });
 
-// 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
+// ---------------------------------------------------------------------------
+// Task 2.1 / S-1 — the single-key discriminator, gated on TREE LOCATION
+// ---------------------------------------------------------------------------
+
+describe('isCommittedMaintenanceSkill — single-key discriminator (DEC-6 amended)', () => {
+  const marker = '---\ndescription: x\ndisable-model-invocation: true\n---\n';
+
+  it('matches exactly the four real committed maintenance skills', () => {
+    const root = join(ASSETS, SCAN_ROOT_RELATIVE_PATHS.committedSkills);
+    const names = readdirSync(root, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+    const matched = names.filter((n) =>
+      isCommittedMaintenanceSkill(join(root, n), frontmatterOf(readAsset('claude-committed', 'skills', n, 'SKILL.md')))
+    );
+    expect(matched.sort()).toEqual(['compact-knowledge', 'reinit', 'revalidate-knowledge', 'revalidate-team']);
+  });
+
+  it('does not match a real plugin catalog skill (they carry no marker)', () => {
+    const fm = frontmatterOf(readSkill('code-review', 'SKILL.md'));
+    expect(isCommittedMaintenanceSkill('claude/skills/code-review', fm)).toBe(false);
+  });
+
+  // S-1 ROBUSTNESS LOCK. The marker is NOT globally unique — the third-party
+  // assets/claude/packs/styles/skills/i-have-adhd/SKILL.md carries it. These two cases prove the
+  // discriminator is gated on scan-scope to assets/claude-committed/skills/, not on the marker
+  // being absent elsewhere.
+  it('S-1: a PLUGIN-tree skill carrying the marker still emits no prompt (tree location is the signal)', () => {
+    expect(isCommittedMaintenanceSkill('claude/skills/rogue-skill', marker)).toBe(false);
+  });
+
+  it('S-1: a PACK-tree third-party skill carrying the marker still emits no prompt', () => {
+    expect(isCommittedMaintenanceSkill('claude/packs/styles/skills/i-have-adhd', marker)).toBe(false);
+    // ...and the real third-party skill really does carry the marker, so this is not a hypothetical.
+    expect(readAsset('claude', 'packs', 'styles', 'skills', 'i-have-adhd', 'SKILL.md')).toContain('disable-model-invocation: true');
+  });
+
+  it('is single-key: it does NOT additionally require user-invocable (which no committed skill has)', () => {
+    expect(isCommittedMaintenanceSkill('claude-committed/skills/demo', marker)).toBe(true);
+    const all = readdirSync(join(ASSETS, SCAN_ROOT_RELATIVE_PATHS.committedSkills), { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => readAsset('claude-committed', 'skills', e.name, 'SKILL.md'));
+    for (const content of all) expect(frontmatterOf(content)).not.toContain('user-invocable');
+  });
+
+  it('a committed skill WITHOUT the marker opts out (marker is still required)', () => {
+    expect(isCommittedMaintenanceSkill('claude-committed/skills/demo', '---\ndescription: x\n---')).toBe(false);
+    expect(isCommittedMaintenanceSkill('claude-committed/skills/demo', 'disable-model-invocation: false')).toBe(false);
+  });
+});
+
+describe('convertMaintenanceSkillToPrompt', () => {
+  it('renders a Copilot .prompt.md with the folded description flattened onto one line', () => {
+    const out = convertMaintenanceSkillToPrompt(readAsset('claude-committed', 'skills', 'reinit', 'SKILL.md'));
+    const desc = lineOf(out, 'description');
+    expect(desc).toMatch(/^description: '.*'$/);
+    expect(desc).toContain('/reinit');
+    expect(out.split('\n').filter((l) => l === '---')).toHaveLength(2);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Task 2.1 / DEC-1 — copilot-apply-to re-emission (deterministic glob attachment)
+// ---------------------------------------------------------------------------
+
+describe('convertSkillToInstructions — copilot-apply-to re-emission (DEC-1)', () => {
+  it('re-emits the glob VERBATIM into applyTo (no reverse parse, no NL translation)', () => {
+    const glob = '**/*.jsx, **/*.tsx, **/*.js, **/*.ts, **/*.css, **/*.scss';
+    const out = convertSkillToInstructions(readSkill('reactjs', 'SKILL.md'), 'reactjs');
+    expect(lineOf(out, 'applyTo')).toBe(`applyTo: '${glob}'`);
+  });
+
+  it('preserves a path-scoped glob without collapsing it to a language phrase', () => {
+    const out = convertSkillToInstructions(readSkill('task-implementation', 'SKILL.md'), 'task-implementation');
+    expect(lineOf(out, 'applyTo')).toBe("applyTo: '**/.vesper/.tracking/changes/*.md'");
+  });
+
+  it('returns null for a skill without the field (plain relevance-skill, no .instructions.md)', () => {
+    expect(convertSkillToInstructions(readSkill('code-review', 'SKILL.md'), 'code-review')).toBeNull();
+  });
+
+  it('emits an instructions file for every canonical skill carrying the field, and only those', () => {
+    // The core plus every pack (epic H): the tiered instructions of a packed skill still go to the
+    // global folders, so the expected list spans the whole catalog.
+    const withField = [...allSkillDirs().entries()]
+      .filter(([, dir]) => existsSync(join(dir, 'SKILL.md')))
+      .filter(([, dir]) => (frontmatterOf(readFileSync(join(dir, 'SKILL.md'), 'utf-8')) || '').includes('copilot-apply-to:'))
+      .map(([n]) => n);
+    expect(withField.sort()).toEqual([
+      'flutter',
+      'java',
+      'nextjs-tailwind',
+      'reactjs',
+      'self-explanatory-code-commenting',
+      'tailwind-v4-vite',
+      'task-implementation',
+    ]);
+  });
+});
+
+describe('convertSkillMd', () => {
+  it('strips the source-only copilot-apply-to field from the generated skill', () => {
+    const out = convertSkillMd(readSkill('reactjs', 'SKILL.md'));
+    expect(out).not.toContain('copilot-apply-to:');
+    expect(out).toContain('name: reactjs');
+  });
+
+  it('passes a token-free skill through byte-identically (near-verbatim copy)', () => {
+    const src = readSkill('code-review', 'SKILL.md');
+    expect(convertSkillMd(src)).toBe(src);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Task 2.2 — inverted body-token replacements (conservative by design)
+// ---------------------------------------------------------------------------
+
+describe('applyCopilotBodyTokenReplacements', () => {
+  it.each([
+    ['.claude/agents/foo.md', '.vesper/agents/foo.md'],
+    ['.claude/commands/reinit.md', '.vesper/prompts/reinit.md'],
+    ['.claude/skills/x/SKILL.md', '.vesper/skills/x/SKILL.md'],
+    ['.claude/rules/error-handling.md', '.vesper/instructions/error-handling.instructions.md'],
+    ['.claude/vesper/context.md', '.vesper/instructions/vesper-context.instructions.md'],
+    ['.claude/rules/vesper-context.md', '.vesper/instructions/vesper-context.instructions.md'],
+    ['.claude/vesper/orchestration.md', '.vesper/instructions/vesper-orchestration.instructions.md'],
+    ['.claude/rules/vesper-orchestration.md', '.vesper/instructions/vesper-orchestration.instructions.md'],
+    ['.claude/vesper/orchestrator.md', '.vesper/instructions/vesper-orchestrator.instructions.md'],
+    ['.claude/agents/vesper-orchestrator.md', '.vesper/agents/vesper-orchestrator.agent.md'],
+    ['.claude/vesper/context/conventions.md', '.vesper/context/conventions.md'],
+    ['see .mcp.json', 'see .vscode/mcp.json'],
+    ['use AskUserQuestion here', 'use vscode/askQuestions here'],
+    ['track with TodoWrite', 'track with manage_todo_list'],
+    ['`run_in_background: true`', '`isBackground: true`'],
+  ])('inverts %s', (input, expected) => {
+    expect(applyCopilotBodyTokenReplacements(input)).toBe(expected);
+  });
+
+  it('is idempotent on an already-Copilot mcp config path', () => {
+    expect(applyCopilotBodyTokenReplacements('.vscode/mcp.json')).toBe('.vscode/mcp.json');
+  });
+
+  it('deliberately leaves ambiguous English tool words alone (conservative inversion)', () => {
+    const prose = 'Read the plan, Edit the file, Write a note, Grep the tree, Glob the paths, run Bash.';
+    expect(applyCopilotBodyTokenReplacements(prose)).toBe(prose);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// G-4 — golden snapshots for the deterministic subset
+// ---------------------------------------------------------------------------
+
+describe('golden snapshots (G-4) — the deterministic subset only', () => {
+  it('agent conversion is byte-stable for a fixed fixture', () => {
+    const src = [
+      '---',
+      'name: golden-agent',
+      'description: Golden fixture specialist.',
+      'model: claude-sonnet-5',
+      'tools: Read, Grep, Glob, Edit, Write, Bash, WebFetch, WebSearch, Agent, TodoWrite, AskUserQuestion, mcp__vesper-indexing__vesper_search, mcp__vesper-indexing__vesper_symbols, mcp__vesper-indexing__vesper_status, mcp__vesper-indexing__vesper_reindex, mcp__memory__search_nodes',
+      'skills: [agent-fundamentals]',
+      '---',
+      '# Golden Agent',
+      '',
+      'Consult `.claude/vesper/context.md` and the rules in `.claude/rules/`.',
+      '',
+    ].join('\n');
+    expect(convertAgentToCopilot(src, 'golden-agent')).toMatchSnapshot();
+  });
+
+  it('copilot-apply-to re-emission is byte-stable for a real canonical skill', () => {
+    const out = convertSkillToInstructions(readSkill('java', 'SKILL.md'), 'java');
+    expect(out.slice(0, out.indexOf('\n---\n') + 5)).toMatchSnapshot();
+  });
+
+  it('maintenance-skill prompt frontmatter is byte-stable', () => {
+    const out = convertMaintenanceSkillToPrompt(readAsset('claude-committed', 'skills', 'revalidate-team', 'SKILL.md'));
+    expect(out.slice(0, out.indexOf('\n---\n') + 5)).toMatchSnapshot();
+  });
+
+  it('skill pass-through is byte-identical in the no-token case (either-direction claim)', () => {
+    const src = readSkill('code-review', 'SKILL.md');
+    expect(convertSkillMd(src)).toBe(src);
+    expect(applyCopilotBodyTokenReplacements(src)).toBe(src);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Generated-output invariants (the flip actually ran and produced the committed root)
+// ---------------------------------------------------------------------------
+
+describe('generated Copilot output root (committed, M-2)', () => {
+  const OUT = join(ASSETS, 'copilot');
+
+  it('exists beside the canonical trees with the expected type dirs', () => {
+    expect(existsSync(OUT)).toBe(true);
+    for (const type of ['agents', 'skills', 'instructions-extended', 'prompts']) {
+      expect(existsSync(join(OUT, type)), type).toBe(true);
+    }
+  });
+
+  it('emits ONLY hidden specialists — zero pickable agents (BR-1 / DEC-7)', () => {
+    // The flat core folder plus every pack's (epic H).
+    const dirs = [join(OUT, 'agents'), ...packNames().map((p) => join(OUT, 'packs', p, 'agents')).filter((d) => existsSync(d))];
+    const files = dirs.flatMap((dir) => readdirSync(dir).filter((f) => f.endsWith('.agent.md')).map((f) => join(dir, f)));
+    expect(files.length).toBeGreaterThan(30);
+    for (const f of files) {
+      const content = readFileSync(f, 'utf-8');
+      expect(content, f).toContain('user-invocable: false');
+      expect(content, f).not.toContain('user-invocable: true');
+    }
+  });
+
+  it('emits no orchestrator persona (the pickable one is project-local, not package-resident)', () => {
+    const files = readdirSync(join(OUT, 'agents'));
+    expect(files.filter((f) => f.startsWith('vesper'))).toEqual([]);
+  });
+
+  it('emits a prompt for exactly the four committed maintenance skills', () => {
+    expect(readdirSync(join(OUT, 'prompts')).sort()).toEqual([
+      'compact-knowledge.prompt.md',
+      'reinit.prompt.md',
+      'revalidate-knowledge.prompt.md',
+      'revalidate-team.prompt.md',
+    ]);
+  });
+
+  it('emits an instructions file for exactly the copilot-apply-to skills, by tier', () => {
+    // Every 2.0 instruction descends from a 1.x EXTENDED (opt-in) instruction; 1.x's core
+    // instructions were all folded into skills / the project-local brain. So the core
+    // folder is empty and therefore absent (git carries no empty dir).
+    expect(existsSync(join(OUT, 'instructions'))).toBe(false);
+    const extended = readdirSync(join(OUT, 'instructions-extended')).sort();
+    expect(extended).toEqual([
+      'flutter',
+      'java',
+      'nextjs-tailwind',
+      'reactjs',
+      'self-explanatory-code-commenting',
+      'tailwind-v4-vite',
+      'task-implementation',
+    ]);
+    for (const name of extended) {
+      expect(readdirSync(join(OUT, 'instructions-extended', name))).toEqual([`${name}.instructions.md`]);
+    }
+  });
+
+  it('never emits the excluded inputs into the output root', () => {
+    expect(existsSync(join(OUT, 'commands'))).toBe(false);
+    expect(existsSync(join(OUT, '.claude-plugin'))).toBe(false);
+    expect(existsSync(join(OUT, 'skills', 'i-have-adhd'))).toBe(false);
+    expect(existsSync(join(OUT, 'agents', 'vesper-orchestrator.agent.md'))).toBe(false);
+  });
+
+  it('carries no leaked source-only copilot-apply-to field in any generated skill', () => {
+    const root = join(OUT, 'skills');
+    for (const name of readdirSync(root)) {
+      const skillMd = join(root, name, 'SKILL.md');
+      if (!existsSync(skillMd)) continue;
+      expect(readFileSync(skillMd, 'utf-8'), name).not.toContain('copilot-apply-to:');
+    }
   });
 });