@mthanh/vespercli 1.8.0 → 2.0.0

package/scripts/generate-claude-assets.js

@@ -1,636 +1,676 @@
 #!/usr/bin/env node
 /**
- * Generate the Claude Code target's extended catalog from the Copilot source assets.
+ * Generate the **Copilot** target's catalog from the canonical **Claude** source trees.
  *
- * Converts:
- *   assets/agents/<name>/<name>.agent.md       -> assets/claude/agents/<name>.md
- *   assets/prompts/<name>/<name>.prompt.md     -> assets/claude/commands/<name>.md
- *   assets/skills/<name>/                      -> assets/claude/skills/<name>/  (near-verbatim)
- *   assets/instructions/<name>/<name>.instructions.md -> assets/claude/skills/<name>/SKILL.md (new skill)
+ * DIRECTION (Vesper 2.0): `assets/claude/` + `assets/claude-committed/` are the sole
+ * hand-authored catalog; `assets/copilot/` is machine-generated, COMMITTED output. The
+ * filename is historical (it is still "the asset generator"); only its direction changed.
  *
- * This is a one-time/periodic build step run by maintainers (like generate-manifests.js) —
- * `vesper add --target claude` copies the *output* of this script, it never transforms
- * 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.
+ * THIS FILE IS AN I/O SHELL. Every Claude → Copilot inversion layer lives in the PURE
+ * module `src/cli/utils/copilot-render.js`, which the runtime Copilot provisioning
+ * module imports too. Runtime code must NEVER import from `scripts/` (enforced by a
+ * test): the CLI bundle once inlined this file's run-as-main guard and regenerated the
+ * installed package's assets mid-command.
  *
- * 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.
+ * Scan roots → outputs:
+ *
+ *   assets/claude/agents/<name>.md               -> copilot/agents/<name>.agent.md (hidden specialist)
+ *   assets/claude/skills/<name>/                 -> copilot/skills/<name>/ (EVERY .md rendered)
+ *   assets/claude/skills/<name>/SKILL.md
+ *     `copilot-apply-to` + tier `core`           -> copilot/instructions/<name>.instructions.md
+ *     `copilot-apply-to` + tier `extended`       -> copilot/instructions-extended/<name>/<name>.instructions.md
+ *   assets/claude-committed/skills/<name>/       -> copilot/prompts/<name>.prompt.md
+ *     (must carry `disable-model-invocation: true`)
+ *   assets/claude/packs/<pack>/agents/<name>.md  -> copilot/packs/<pack>/agents/<name>.agent.md
+ *   assets/claude/packs/<pack>/skills/<name>/    -> copilot/packs/<pack>/skills/<name>/
+ *     (tiered instructions of a packed skill go to the GLOBAL instructions folders above;
+ *      the shared `agent-fundamentals` copy each pack carries is validated, not mirrored;
+ *      a THIRD-PARTY skill — one carrying `UPSTREAM.json` (epic J) — is copied VERBATIM,
+ *      `UPSTREAM.json` and `LICENSE` included: Vesper does not author it, so it is neither
+ *      rendered nor residue-scanned, and its own `disable-model-invocation` marker is allowed)
+ *   assets/manifest.json                         <- written here too (no timestamp); carries
+ *                                                   `packs` + `assetPacks` (pack per asset)
+ *
+ * The instruction TIER restores 1.x's core/extended split (1.x kept them apart by tree:
+ * `assets/core/instructions/` injected for every project, `assets/instructions/<name>/`
+ * opt-in). Only the core folder is default-injected by `settings.js`; each extended
+ * instruction lives in its own folder so it can be injected individually.
+ *
+ * STRICT: any per-entry failure (I/O, missing/unsafe frontmatter, a committed skill
+ * without the maintenance marker, a plugin skill WITH it, an unmapped tool or model,
+ * Claude-host residue outside the allow-list) fails the run with every error listed,
+ * and NOTHING is written.
+ * ATOMIC: the tree is built in memory, written to a sibling temp dir, and swapped in
+ * by rename — an interrupted run never leaves a partial `assets/copilot/`.
+ *
+ * !! LOAD-BEARING !! `disable-model-invocation: true` is NOT globally unique (the third-party
+ * `packs/styles/skills/i-have-adhd/SKILL.md` carries it). Prompt emission is scoped to
+ * `assets/claude-committed/skills/` by TREE LOCATION, never by the marker alone.
  *
  * 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 { readdir, readFile, writeFile, mkdir, rm, rename, stat, chmod } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, dirname, relative, sep } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { MCP_SERVERS } from '../src/cli/utils/settings.js';
+
+import {
+  splitFrontmatter,
+  readFrontmatterValue,
+  isYamlSafeInlineScalar,
+  extractClaudeToolTokens,
+  mapClaudeToolsToCopilot,
+  mapMcpTools,
+  convertAgentToCopilot,
+  convertMaintenanceSkillToPrompt,
+  convertSkillToInstructions,
+  convertSkillMd,
+  convertSkillMarkdownFile,
+  applyCopilotBodyTokenReplacements,
+  renderCopilotText,
+  hasMaintenanceMarker,
+  readInstructionTier,
+  COPILOT_INSTRUCTION_TIERS,
+  __resetDiagnostics,
+  __getDiagnostics,
+  getDiagnosticMessages,
+} from '../src/cli/utils/copilot-render.js';
+
+// Re-exported so the generator's own test suite (and tooling) keeps one import site.
+export {
+  splitFrontmatter,
+  readFrontmatterValue,
+  extractClaudeToolTokens,
+  mapClaudeToolsToCopilot,
+  mapMcpTools,
+  convertAgentToCopilot,
+  convertMaintenanceSkillToPrompt,
+  convertSkillToInstructions,
+  convertSkillMd,
+  applyCopilotBodyTokenReplacements,
+  renderCopilotText,
+  __resetDiagnostics,
+  __getDiagnostics,
+};
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-const ASSETS_DIR = join(__dirname, '..', 'assets');
-const CLAUDE_DIR = join(ASSETS_DIR, 'claude');
-
-/** Tool token map: Copilot tool name -> Claude Code tool name(s) (comma-separated) */
-const TOOL_MAP = {
-  'read/readFile': 'Read',
-  'read': 'Read',
-  'edit/editFiles': 'Edit, Write',
-  'edit/createFile': 'Write',
-  'edit/createDirectory': 'Write',
-  'edit': 'Edit, Write',
-  'execute/runInTerminal': 'Bash',
-  'execute/createAndRunTask': 'Bash',
-  'execute/getTerminalOutput': 'Bash',
-  'execute/testFailure': 'Bash',
-  'execute/runTests': 'Bash',
-  'execute/runNotebookCell': 'Bash',
-  'execute/awaitTerminal': 'Bash',
-  'execute': 'Bash',
-  'search/listDirectory': 'Glob',
-  'search/fileSearch': 'Glob',
-  'search/codebase': 'Grep',
-  'search/changes': 'Bash',
-  'search/searchSubagent': 'Agent',
-  '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',
-};
+export const ASSETS_DIR = join(__dirname, '..', 'assets');
+/** The committed Copilot output root (M-2). Never hand-edited — regenerate instead. */
+export const COPILOT_DIR = join(ASSETS_DIR, 'copilot');
+
+/** The two canonical, hand-authored roots (assets-relative). */
+export const CANONICAL_ROOTS = Object.freeze(['claude', 'claude-committed']);
 
 /**
- * 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).
+ * The four — and only four — scan roots, as assets-relative POSIX paths. `packs` is the root of
+ * the stack packs (epic H): each `claude/packs/<pack>/` is a plugin of its own (`vesper-<pack>`)
+ * with its own `agents/` + `skills/`, listed in the marketplace next to the core plugin.
  */
-const DROP_TOKENS = new Set([
-  // VS Code workspace/editor capabilities with no Claude Code analogue.
-  'vscode/getProjectSetupInfo',
-  'vscode/installExtension',
-  'vscode/newWorkspace',
-  'vscode/openSimpleBrowser',
-  'vscode/runCommand',
-  '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
-]);
+export const SCAN_ROOT_RELATIVE_PATHS = Object.freeze({
+  pluginAgents: 'claude/agents',
+  pluginSkills: 'claude/skills',
+  packs: 'claude/packs',
+  committedSkills: 'claude-committed/skills',
+});
 
-/** MCP-namespaced tokens pass through as mcp__<server>__* wildcards (kept as a note, not expanded) */
-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
-// cost changes. Bump these deliberately when adopting a new model version.
-const MODEL_MAP = {
-  'Claude Opus 4.8': 'claude-opus-4-8',
-  'Claude Opus 4.7': 'claude-opus-4-8',
-  'Claude Sonnet 4.6': 'claude-sonnet-5',
-  'Claude Haiku 4.5': 'claude-haiku-4-5-20251001',
-  'GPT-5.5': 'claude-sonnet-5',
-};
+/** Plugin name prefix of every pack: `vesper-<pack>` (the core plugin is `vesper`). */
+export const PACK_PLUGIN_PREFIX = 'vesper-';
 
 /**
- * Normalize a single tool item: trim, then strip a matching pair of surrounding quotes.
- * @param {string} raw
- * @returns {string}
+ * The provenance record a THIRD-PARTY pack skill carries beside its `SKILL.md` (epic J):
+ * `{ upstream, sha, retrieved, license, path }`, written by `scripts/vendor-sync.js`. Its
+ * presence is what makes a skill third-party to this generator: copied verbatim, never
+ * rendered, never residue-scanned, its own frontmatter markers allowed.
  */
-function normalizeToolItem(raw) {
-  return raw.trim().replace(/^['"]|['"]$/g, '');
-}
+export const UPSTREAM_RECORD_FILE = 'UPSTREAM.json';
 
-/**
- * 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) {
-  // Bracket-array form first (unchanged behavior).
-  const bracket = frontmatter.match(/tools:\s*\[([\s\S]*?)\]/);
-  if (bracket) {
-    return bracket[1]
-      .split(',')
-      .map(normalizeToolItem)
-      .filter(Boolean);
-  }
+/** Is this skill folder third-party (carries an `UPSTREAM.json`)? */
+export function isThirdPartySkillDir(skillDir) {
+  return existsSync(join(skillDir, UPSTREAM_RECORD_FILE));
+}
 
-  // 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;
+/** Validate a third-party skill's `UPSTREAM.json`; errors pushed, never thrown. */
+async function checkUpstreamRecord(skillDir, where, errors) {
+  const rec = await readJsonOrNull(join(skillDir, UPSTREAM_RECORD_FILE));
+  if (!rec) { errors.push(`${where}/${UPSTREAM_RECORD_FILE}: missing or unparseable`); return; }
+  if (typeof rec.upstream !== 'string' || !/^https?:\/\/\S+$/.test(rec.upstream)) errors.push(`${where}/${UPSTREAM_RECORD_FILE}: "upstream" must be a git URL`);
+  if (typeof rec.sha !== 'string' || !/^[0-9a-f]{40}$/.test(rec.sha)) errors.push(`${where}/${UPSTREAM_RECORD_FILE}: "sha" must be a 40-hex commit`);
+  if (typeof rec.retrieved !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(rec.retrieved)) errors.push(`${where}/${UPSTREAM_RECORD_FILE}: "retrieved" must be YYYY-MM-DD`);
+  if (typeof rec.license !== 'string' || !rec.license) errors.push(`${where}/${UPSTREAM_RECORD_FILE}: "license" is required`);
+  if (!existsSync(join(skillDir, 'LICENSE'))) errors.push(`${where}: a third-party skill ships its upstream LICENSE verbatim`);
 }
 
 /**
- * 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.
+ * Skills every pack carries as a byte-identical COPY of the core skill. Every agent preloads
+ * `agent-fundamentals` through its `skills:` frontmatter; the Claude Code docs do not promise
+ * that a plugin agent can preload a skill shipped by a DIFFERENT plugin, so each pack ships its
+ * own copy (kept identical to the core by `syncSharedPackSkills`, asserted by the strict build).
+ * The Copilot mirror does NOT duplicate them: Copilot injects the core `skills/` folder for
+ * every project, so one copy is enough there.
  */
-let sawUnknownToken = false;
+export const SHARED_PACK_SKILLS = Object.freeze(['agent-fundamentals']);
 
-/**
- * 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;
+/** The pack names (directory names under `claude/packs/`), sorted. */
+export async function listPackNames(assetsDir = ASSETS_DIR) {
+  try {
+    const entries = await readdir(join(assetsDir, SCAN_ROOT_RELATIVE_PATHS.packs), { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory() && !e.name.startsWith('.')).map((e) => e.name).sort();
+  } catch {
+    return [];
+  }
+}
 
 /**
- * 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}
+ * Every child of a canonical root that is deliberately NOT a scan root. The
+ * completeness test requires each child of `assets/claude/` and
+ * `assets/claude-committed/` to be EITHER a scan root OR listed here, so a catalog
+ * author adding a tree gets a failing test instead of silent non-emission.
  */
-function mapToolTokens(tokens, agentName) {
-  const claudeTools = new Set();
-  const mcpNotes = new Set();
-
-  for (const token of tokens) {
-    if (DROP_TOKENS.has(token)) continue;
-    if (MCP_PASSTHROUGH.includes(token)) {
-      mcpNotes.add(token.replace('/*', ''));
-      continue;
-    }
-    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));
-  }
+export const EXCLUDED_SOURCE_PATHS = Object.freeze([
+  'claude/.claude-plugin',          // plugin manifest dir (plugin.json, marketplace.json)
+  'claude/vesper-orchestrator.md',  // always-on playbook  \
+  'claude/orchestration.md.tpl',    // roster template      } rendered project-local by the
+  'claude/context.md.tpl',          // whitepaper template /  host modules, not emitted here
+  'claude/evals',                   // `claude plugin eval` suite (epic G): tests the plugin, ships nowhere
+  'claude-committed/agents',        // the thin pickable persona (DEC-7: rendered project-local)
+]);
 
-  return Array.from(claudeTools).join(', ');
+/** Normalize an absolute-or-relative path to an assets-relative POSIX path. */
+function toAssetsRelative(somePath) {
+  const rel = somePath.startsWith(ASSETS_DIR) ? relative(ASSETS_DIR, somePath) : somePath;
+  return rel.split(sep).join('/').replace(/^\.\//, '').replace(/\/+$/, '');
 }
 
 /**
- * Convert an `.agent.md` file's content (frontmatter + body) into Claude subagent format.
- * @param {string} content
- * @param {string} kebabName - directory/asset name, used as the subagent name
- * @returns {string}
+ * Is this source path excluded from scanning? True for the listed canonical-root
+ * children and for anything outside the two canonical roots (`hooks/`, `legacy/`, …).
+ * @param {string} somePath - absolute path, or a path already relative to `assets/`
  */
-function convertAgent(content, kebabName) {
-  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
-  if (!frontmatterMatch) return content;
-
-  const [, frontmatter, body] = frontmatterMatch;
-  const descriptionMatch = frontmatter.match(/description:\s*['"]?(.*?)['"]?\s*(\n|$)/);
-  const modelMatch = frontmatter.match(/model:\s*['"]?(.*?)['"]?\s*(\n|$)/);
-
-  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), kebabName);
-
-  const newFrontmatter = [
-    `name: ${kebabName}`,
-    `description: ${description}`,
-    `model: ${model}`,
-    tools ? `tools: ${tools}` : null,
-    // Preload the universal Vesper baseline skill into every subagent —
-    // guarantees terminal discipline / codebase-query rules without relying
-    // on incidental skill auto-discovery.
-    'skills: [agent-fundamentals]',
-  ].filter(Boolean).join('\n');
-
-  const cleanedBody = applyBodyTokenReplacements(body);
-
-  return `---\n${newFrontmatter}\n---\n${cleanedBody}`;
+export function isExcludedSource(somePath) {
+  const rel = toAssetsRelative(somePath);
+  if (!CANONICAL_ROOTS.some((r) => rel === r || rel.startsWith(`${r}/`))) return true;
+  // Each pack's own plugin manifest dir (`claude/packs/<pack>/.claude-plugin`) — the per-pack
+  // twin of `claude/.claude-plugin`; validated by the build, never emitted.
+  if (/^claude\/packs\/[^/]+\/\.claude-plugin(\/|$)/.test(rel)) return true;
+  return EXCLUDED_SOURCE_PATHS.some((ex) => rel === ex || rel.startsWith(`${ex}/`));
 }
 
 /**
- * Convert a `.prompt.md` file's content into a Claude Code slash command.
- * @param {string} content
- * @returns {string}
+ * THE DISCRIMINATOR (DEC-6, single-key): a skill emits a `.prompt.md` iff it lives
+ * under `assets/claude-committed/skills/` AND carries `disable-model-invocation: true`.
+ * Tree location is the load-bearing signal (the marker is not globally unique).
  */
-function convertPrompt(content) {
-  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
-  if (!frontmatterMatch) return content;
-
-  const [, frontmatter, body] = frontmatterMatch;
-  const descriptionMatch = frontmatter.match(/description:\s*['"]?(.*?)['"]?\s*(\n|$)/);
-  const description = descriptionMatch ? descriptionMatch[1] : '';
-
-  const newFrontmatter = description ? `description: ${description}` : '';
-  const cleanedBody = applyBodyTokenReplacements(body).replace(/\$\{input:[^}]+\}/g, '$ARGUMENTS');
-
-  return newFrontmatter ? `---\n${newFrontmatter}\n---\n${cleanedBody}` : cleanedBody;
+export function isCommittedMaintenanceSkill(skillDir, frontmatter) {
+  const rel = toAssetsRelative(skillDir);
+  if (!rel.startsWith(`${SCAN_ROOT_RELATIVE_PATHS.committedSkills}/`)) return false;
+  return hasMaintenanceMarker(frontmatter);
 }
 
+/** Source-only files never copied into the generated catalog. */
+const SKIPPED_SOURCE_FILES = new Set(['manifest.json', 'skill.json']);
+
 /**
- * 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.
+ * Claude-host residue that must not appear anywhere in the generated tree, and the
+ * explicit allow-list of files where a token is legitimately host-neutral prose
+ * (e.g. a skill ABOUT Claude settings, a vendored-style tool reference). Every
+ * allow-list entry names the file AND the token; nothing is allowed tree-wide.
  */
-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',
-};
+export const COPILOT_RESIDUE_TOKENS = Object.freeze([
+  { token: 'vesper:', pattern: /\bvesper:(?!start\b|end\b|gitignore\b|hook\b)[a-z<*]/, why: 'Copilot delegation names are plain (no plugin namespace)' },
+  { token: 'vesper-<pack>:', pattern: /\bvesper-(?:<pack>|[a-z][a-z0-9-]*):[a-z<*]/, why: 'Copilot delegation names are plain (no pack namespace either)' },
+  { token: '.claude/rules/', pattern: /\.claude\/rules\//, why: 'Copilot brain lives under .vesper/instructions/' },
+  { token: '.claude/vesper/', pattern: /\.claude\/vesper\//, why: 'Copilot brain lives under .vesper/' },
+  { token: '.claude/agents/', pattern: /\.claude\/agents\//, why: 'Copilot agents live under .vesper/agents/' },
+  { token: '.claude/skills/', pattern: /\.claude\/skills\//, why: 'Copilot skills live under .vesper/skills/' },
+  { token: 'unsuffixed brain file', pattern: /\.vesper\/instructions\/vesper-(orchestrator|orchestration|context)\.md/, why: 'Copilot only attaches *.instructions.md' },
+  { token: '.vesper/orchestration.md', pattern: /\.vesper\/(orchestrator|orchestration|context)\.md/, why: 'not the roster/whitepaper path the rendered playbook reads' },
+  { token: '.claude/settings.json', pattern: /\.claude\/settings\.json/, why: 'Copilot has no .claude/settings.json' },
+]);
 
 /**
- * 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.
+ * `path → tokens allowed there`. Keep this list SHORT and justified; the residue
+ * test prints the offending file + line for anything not listed.
  */
-const GLOB_OVERRIDES = {
-  '**/.vesper/.tracking/changes/*.md': 'task change-record files under .vesper/.tracking/changes/',
-};
+export const COPILOT_RESIDUE_ALLOW_LIST = Object.freeze({
+  // The catalog-safety skill is maintainer documentation of BOTH hosts' delivery model;
+  // `.claude/settings.json` (the Claude plugin declaration) is its subject matter, not an
+  // instruction for this host. Its remaining Copilot-copy prose issues are recorded in
+  // the epic (d) change log for a later pass.
+  'skills/vesper-catalog-editing-safety/SKILL.md': ['.claude/settings.json'],
+});
 
 /**
- * Render a list as an Oxford-style human phrase: "A", "A or B", "A, B, or C".
- * @param {string[]} items
- * @returns {string}
+ * Find Claude-host residue in one generated file's text.
+ * @param {string} relPath - path relative to the Copilot output root
+ * @param {string} text
+ * @returns {string[]} human-readable findings (empty = clean)
  */
-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]}`;
+export function findCopilotResidue(relPath, text) {
+  const allowed = new Set(COPILOT_RESIDUE_ALLOW_LIST[relPath] || []);
+  const findings = [];
+  const lines = text.split('\n');
+  for (const { token, pattern, why } of COPILOT_RESIDUE_TOKENS) {
+    if (allowed.has(token)) continue;
+    lines.forEach((line, i) => {
+      if (pattern.test(line)) findings.push(`${relPath}:${i + 1}: ${token} — ${why}: ${line.trim().slice(0, 140)}`);
+    });
+  }
+  return findings;
 }
 
-/**
- * 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;
-    }
+// ---------------------------------------------------------------------------
+// Scan helpers (read-only)
+// ---------------------------------------------------------------------------
+
+async function listChildren(dir, kind) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  return entries
+    .filter((e) => (kind === 'dir' ? e.isDirectory() : e.isFile()))
+    .filter((e) => !e.name.startsWith('.'))
+    .map((e) => e.name)
+    .sort();
+}
 
-    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;
+async function walkFiles(root) {
+  const out = [];
+  const visit = async (dir) => {
+    for (const e of await readdir(dir, { withFileTypes: true })) {
+      const abs = join(dir, e.name);
+      if (e.isDirectory()) await visit(abs);
+      else if (e.isFile()) out.push(relative(root, abs).split(sep).join('/'));
     }
+  };
+  await visit(root);
+  return out.sort();
+}
 
-    // Neither path-scoped nor a recognizable `.<ext>` token.
-    unmapped.push(token);
+/** Validate a canonical source frontmatter for YAML safety of its description. */
+function checkDescriptionYaml(frontmatter, where, errors) {
+  const line = frontmatter.split('\n').find((l) => l.startsWith('description:'));
+  if (!line) {
+    errors.push(`${where}: frontmatter has no description`);
+    return;
   }
-
-  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.`
-    );
+  if (!isYamlSafeInlineScalar(line.slice('description:'.length))) {
+    errors.push(`${where}: unquoted description is not valid YAML (contains ": " or a YAML indicator) — quote it`);
   }
+}
 
-  const pieces = [];
-  if (languages.length) pieces.push(`${oxfordList(languages)} files`);
-  for (const phrase of phrases) pieces.push(phrase);
+/** Read + parse a JSON file; `null` when missing/unparseable (the caller reports it). */
+async function readJsonOrNull(abs) {
+  try { return JSON.parse(await readFile(abs, 'utf-8')); } catch { return null; }
+}
 
-  const clause = pieces.length ? ` Use when working with ${oxfordList(pieces)}.` : '';
-  return { clause, unmapped };
+/** The package version every plugin manifest must carry (`package.json` next to `assets/`). */
+async function readPackageVersion(assetsDir) {
+  const pkg = await readJsonOrNull(join(assetsDir, '..', 'package.json'));
+  return pkg?.version ?? null;
 }
 
 /**
- * Convert an `.instructions.md` file into a new Skill (SKILL.md).
- * @param {string} content
- * @param {string} kebabName
- * @returns {string}
+ * Validate one pack's plugin manifest: `packs/<pack>/.claude-plugin/plugin.json` must exist,
+ * be named `vesper-<pack>` and carry the package version. Errors are pushed, never thrown.
  */
-function convertInstructionToSkill(content, kebabName) {
-  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
-  if (!frontmatterMatch) return content;
-
-  const [, frontmatter, body] = frontmatterMatch;
-  const descriptionMatch = frontmatter.match(/description:\s*['"]?(.*?)['"]?\s*(\n|$)/);
-  const applyToMatch = frontmatter.match(/applyTo:\s*['"]?(.*?)['"]?\s*(\n|$)/);
-
-  const rawBaseDescription = descriptionMatch ? descriptionMatch[1] : `${kebabName} conventions`;
-  const applyTo = applyToMatch ? applyToMatch[1] : '';
-  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);
-
-  return `---\n${newFrontmatter}\n---\n${cleanedBody}`;
+async function checkPackManifest(assetsDir, pack, version, errors) {
+  const where = `claude/packs/${pack}/.claude-plugin/plugin.json`;
+  const manifest = await readJsonOrNull(join(assetsDir, SCAN_ROOT_RELATIVE_PATHS.packs, pack, '.claude-plugin', 'plugin.json'));
+  if (!manifest) { errors.push(`${where}: missing or unparseable`); return; }
+  if (manifest.name !== `${PACK_PLUGIN_PREFIX}${pack}`) errors.push(`${where}: name must be "${PACK_PLUGIN_PREFIX}${pack}" (got "${manifest.name}")`);
+  if (version && manifest.version !== version) errors.push(`${where}: version must equal package.json (${version}), got "${manifest.version}"`);
 }
 
 /**
- * Body-text regex passes shared by all converters: path mentions and a handful
- * of recurring Copilot-only inline tokens. Deliberately conservative — most
- * prose is left untouched (per the generator's design, ~90% of body content
- * is portable process knowledge, not Copilot mechanics).
- * @param {string} body
- * @returns {string}
+ * Validate the marketplace: it must list the core plugin (`vesper`, `source: "./"`) and every
+ * pack (`vesper-<pack>`, `source: "./packs/<pack>"`), and nothing else.
  */
-function applyBodyTokenReplacements(body) {
-  return body
-    .replace(/\.github\/agents/g, '.claude/agents')
-    .replace(/\.github\/instructions/g, '.claude/skills')
-    .replace(/\.github\/prompts/g, '.claude/commands')
-    .replace(/\.github\/skills/g, '.claude/skills')
-    .replace(/\.vscode\/mcp\.json/g, '.mcp.json')
-    .replace(/vscode\/askQuestions/g, 'AskUserQuestion')
-    .replace(/manage_todo_list/g, 'TodoWrite')
-    // Inline VS Code tool-name mentions (frequent in shared Terminal Discipline /
-    // tool-hierarchy boilerplate blocks copied across many agents). Word-boundary
-    // regexes so both `backticked` and bare occurrences are caught.
-    .replace(/\bmulti_replace_string_in_file\b/g, 'Edit')
-    .replace(/\breplace_string_in_file\b/g, 'Edit')
-    .replace(/\bread_file\b/g, 'Read')
-    .replace(/\bgrep_search\b/g, 'Grep')
-    .replace(/\bfile_search\b/g, 'Glob')
-    .replace(/\bsemantic_search\b/g, 'Grep')
-    .replace(/\blist_dir\b/g, 'Glob')
-    .replace(/\bcreate_file\b/g, 'Write')
-    .replace(/`get_terminal_output`/g, 'the background-task output mechanism')
-    .replace(/`isBackground:\s*true`/g, '`run_in_background: true`')
-    .replace(/isBackground:\s*true/g, 'run_in_background: true')
-    // Copilot's subagent-invocation directives — subagents can't nest in Claude
-    // Code; surface the need back to the orchestrator instead
-    .replace(/#tool:agent\/runSubagent/g, 'your available tools')
-    .replace(/#runSubagent:\s*/g, 'request via the orchestrator: ')
-    .replace(/#agent:\s*/g, 'request via the orchestrator: ');
-}
-
-async function ensureDir(dir) {
-  await mkdir(dir, { recursive: true });
+async function checkMarketplace(assetsDir, packs, errors) {
+  const where = 'claude/.claude-plugin/marketplace.json';
+  const abs = join(assetsDir, 'claude', '.claude-plugin', 'marketplace.json');
+  // A minimal fixture tree (no packs, no manifest dir) has nothing to validate.
+  if (packs.length === 0 && !existsSync(abs)) return;
+  const mp = await readJsonOrNull(abs);
+  if (!mp || !Array.isArray(mp.plugins)) { errors.push(`${where}: missing, unparseable or without a plugins array`); return; }
+  const expected = new Map([['vesper', './'], ...packs.map((p) => [`${PACK_PLUGIN_PREFIX}${p}`, `./packs/${p}`])]);
+  const listed = new Map(mp.plugins.map((p) => [p.name, p.source]));
+  for (const [name, source] of expected) {
+    if (!listed.has(name)) errors.push(`${where}: plugin "${name}" (source ${source}) is not listed`);
+    else if (listed.get(name) !== source) errors.push(`${where}: plugin "${name}" must have source "${source}" (got "${listed.get(name)}")`);
+  }
+  for (const name of listed.keys()) {
+    if (!expected.has(name)) errors.push(`${where}: lists "${name}", which is neither the core plugin nor a pack under claude/packs/`);
+  }
 }
 
-async function listAssetFolders(dir) {
-  try {
-    const entries = await readdir(dir, { withFileTypes: true });
-    return entries.filter(e => e.isDirectory() && !e.name.startsWith('.')).map(e => e.name);
-  } catch {
-    return [];
+/**
+ * The expected byte-identical copies of the shared skills, per pack: `Map<relative path under
+ * claude/, Buffer>` (`packs/<pack>/skills/<skill>/<file>`), read from the core skill folder.
+ */
+export async function expectedSharedPackSkillFiles({ assetsDir = ASSETS_DIR } = {}) {
+  const out = new Map();
+  const packs = await listPackNames(assetsDir);
+  for (const skill of SHARED_PACK_SKILLS) {
+    const src = join(assetsDir, SCAN_ROOT_RELATIVE_PATHS.pluginSkills, skill);
+    if (!existsSync(src)) continue;
+    for (const rel of await walkFiles(src)) {
+      const content = await readFile(join(src, rel));
+      for (const pack of packs) out.set(`packs/${pack}/skills/${skill}/${rel}`, content);
+    }
   }
+  return out;
 }
 
-async function generateAgents() {
-  const srcDir = join(ASSETS_DIR, 'agents');
-  const destDir = join(CLAUDE_DIR, 'agents');
-  await ensureDir(destDir);
-
-  const names = await listAssetFolders(srcDir);
-  let count = 0;
-  for (const name of names) {
-    const srcPath = join(srcDir, name, `${name}.agent.md`);
-    try {
-      const content = await readFile(srcPath, 'utf-8');
-      const converted = convertAgent(content, name);
-      await writeFile(join(destDir, `${name}.md`), converted, 'utf-8');
-      count += 1;
-    } catch (error) {
-      console.warn(`  skip agents/${name}: ${error.message}`);
+/**
+ * Refresh every pack's copy of the shared skills from the core (the one write the generator
+ * makes INTO the canonical tree — a sync of duplicates, not authored content). Returns the
+ * paths it changed. Idempotent; the strict build reports any copy that still differs.
+ */
+export async function syncSharedPackSkills({ assetsDir = ASSETS_DIR } = {}) {
+  const changed = [];
+  for (const [rel, content] of await expectedSharedPackSkillFiles({ assetsDir })) {
+    const dest = join(assetsDir, 'claude', ...rel.split('/'));
+    let current = null;
+    try { current = await readFile(dest); } catch { current = null; }
+    if (current && current.equals(content)) continue;
+    await mkdir(dirname(dest), { recursive: true });
+    await writeFile(dest, content);
+    changed.push(`claude/${rel}`);
+  }
+  // Stale extra files inside a pack copy (a file removed from the core) are removed too.
+  const expected = await expectedSharedPackSkillFiles({ assetsDir });
+  for (const pack of await listPackNames(assetsDir)) {
+    for (const skill of SHARED_PACK_SKILLS) {
+      const dir = join(assetsDir, SCAN_ROOT_RELATIVE_PATHS.packs, pack, 'skills', skill);
+      if (!existsSync(dir)) continue;
+      for (const rel of await walkFiles(dir)) {
+        const key = `packs/${pack}/skills/${skill}/${rel}`;
+        if (!expected.has(key)) { await rm(join(dir, rel), { force: true }); changed.push(`claude/${key} (removed)`); }
+      }
     }
   }
-  return count;
+  return changed;
 }
 
-async function generatePrompts() {
-  const srcDir = join(ASSETS_DIR, 'prompts');
-  const destDir = join(CLAUDE_DIR, 'commands');
-  await ensureDir(destDir);
+// ---------------------------------------------------------------------------
+// Build the whole generated tree in memory
+// ---------------------------------------------------------------------------
 
-  const names = await listAssetFolders(srcDir);
-  let count = 0;
-  for (const name of names) {
-    const srcPath = join(srcDir, name, `${name}.prompt.md`);
-    try {
-      const content = await readFile(srcPath, 'utf-8');
-      const converted = convertPrompt(content);
-      await writeFile(join(destDir, `${name}.md`), converted, 'utf-8');
-      count += 1;
-    } catch (error) {
-      console.warn(`  skip prompts/${name}: ${error.message}`);
+/**
+ * Compute the complete expected `assets/copilot/` tree (plus the global manifest)
+ * from the canonical sources, WITHOUT writing anything. `assetsDir` is a test seam
+ * (a fixture tree with the same `claude/` + `claude-committed/` layout). The generator writes exactly
+ * this; the freshness test compares the committed tree against exactly this.
+ *
+ * Packs (epic H): `claude/packs/<pack>/agents|skills` mirror to `copilot/packs/<pack>/agents|skills`;
+ * the tiered instructions of a packed skill go to the same global `instructions/` and
+ * `instructions-extended/` folders as a core skill's (opt-in instructions are a per-project
+ * mechanism of their own, not a pack one); the shared skills are not mirrored per pack.
+ *
+ * @returns {Promise<{files: Map<string, {content: Buffer, mode: number}>, manifest: object, errors: string[], counts: object}>}
+ *   `files` keys are POSIX paths relative to `assets/copilot/`.
+ */
+export async function buildCopilotTree({ assetsDir = ASSETS_DIR } = {}) {
+  __resetDiagnostics();
+  const files = new Map();
+  const errors = [];
+  const put = (rel, content, mode = 0o644) => files.set(rel, { content: Buffer.isBuffer(content) ? content : Buffer.from(content, 'utf-8'), mode });
+  const counts = { agents: 0, skills: 0, coreInstructions: 0, extendedInstructions: 0, prompts: 0, packs: 0, thirdParty: 0 };
+  const coreInstructions = [];
+  const extendedInstructions = [];
+  /** Generated paths copied verbatim from a third-party skill — exempt from the residue scan. */
+  const thirdPartyFiles = new Set();
+  // `pack` per asset: `core` or the pack name. Names are unique across core + packs.
+  const assetPacks = { agents: {}, skills: {} };
+  const claimAssetName = (type, name, pack, where) => {
+    const prior = assetPacks[type][name];
+    if (prior !== undefined && !(type === 'skills' && SHARED_PACK_SKILLS.includes(name))) {
+      errors.push(`${where}: ${type.slice(0, -1)} "${name}" is also shipped by ${prior === 'core' ? 'the core' : `pack "${prior}"`} — names are unique across the marketplace`);
+      return false;
     }
-  }
-  return count;
-}
+    if (prior === undefined) assetPacks[type][name] = pack;
+    return true;
+  };
 
-async function generateSkillsFromSkills() {
-  const srcDir = join(ASSETS_DIR, 'skills');
-  const destDir = join(CLAUDE_DIR, 'skills');
-  await ensureDir(destDir);
+  /** 1. Agents → hidden specialists (one folder: the core, or a pack). */
+  const scanAgents = async (agentsDir, { pack, outPrefix, whereBase }) => {
+    let names = [];
+    try { names = (await listChildren(agentsDir, 'file')).filter((f) => f.endsWith('.md')); } catch { return; }
+    for (const file of names) {
+      const name = file.replace(/\.md$/, '');
+      const where = `${whereBase}/${file}`;
+      try {
+        if (!claimAssetName('agents', name, pack, where)) continue;
+        const content = await readFile(join(agentsDir, file), 'utf-8');
+        const { frontmatter } = splitFrontmatter(content);
+        if (!frontmatter) throw new Error('no parseable frontmatter (an agent without it would ship pickable)');
+        checkDescriptionYaml(frontmatter, where, errors);
+        put(`${outPrefix}agents/${name}.agent.md`, convertAgentToCopilot(content, name));
+        counts.agents += 1;
+      } catch (error) {
+        errors.push(`${where}: ${error.message}`);
+      }
+    }
+  };
 
-  const names = await listAssetFolders(srcDir);
-  let count = 0;
-  for (const name of names) {
-    const srcPath = join(srcDir, name);
-    const destPath = join(destDir, name);
-    try {
-      await cp(srcPath, destPath, {
-        recursive: true,
-        filter: (source) => !source.endsWith('manifest.json') && !source.endsWith('skill.json'),
-      });
-      // Token-replace SKILL.md body in place, if this is a single-skill folder
-      // (some entries, e.g. debugging/problem-solving/document-skills, are bundles
-      // of multiple sub-skills with no top-level SKILL.md — the directory copy above
-      // already handles those correctly, nothing further to patch).
-      const skillMdPath = join(destPath, 'SKILL.md');
+  /** 2. Plugin skills → skills (every file; every .md rendered) + tiered instructions. */
+  const scanSkills = async (skillsDir, { pack, outPrefix, whereBase }) => {
+    let names = [];
+    try { names = await listChildren(skillsDir, 'dir'); } catch { return; }
+    for (const name of names) {
+      const srcDir = join(skillsDir, name);
+      const where = `${whereBase}/${name}`;
+      const shared = pack !== 'core' && SHARED_PACK_SKILLS.includes(name);
+      // A third-party skill (epic J): upstream's bytes, shipped as pack content. Copied verbatim
+      // (`UPSTREAM.json` + `LICENSE` included) so the Copilot mirror is the same snapshot; its
+      // markdown is neither rendered nor residue-scanned (Vesper does not author it), and its
+      // own `disable-model-invocation` marker is allowed — prompt emission is tree-scoped anyway.
+      const thirdParty = isThirdPartySkillDir(srcDir);
       try {
-        const content = await readFile(skillMdPath, 'utf-8');
-        await writeFile(skillMdPath, applyBodyTokenReplacements(content), 'utf-8');
-      } catch {
-        // Bundle folder with no top-level SKILL.md — already fully copied above.
+        if (!claimAssetName('skills', name, pack, where)) continue;
+        if (thirdParty && pack === 'core') throw new Error(`carries ${UPSTREAM_RECORD_FILE} — third-party skills are pack content, never core`);
+        if (thirdParty) await checkUpstreamRecord(srcDir, where, errors);
+        const rels = (await walkFiles(srcDir)).filter((r) => !SKIPPED_SOURCE_FILES.has(r.split('/').pop()));
+        const skillMds = rels.filter((r) => r === 'SKILL.md' || r.endsWith('/SKILL.md'));
+        if (skillMds.length === 0) throw new Error('no SKILL.md at any depth — not a skill');
+        for (const rel of rels) {
+          const abs = join(srcDir, rel);
+          const { mode } = await stat(abs);
+          if (!rel.endsWith('.md') || thirdParty) {
+            if (!shared) put(`${outPrefix}skills/${name}/${rel}`, await readFile(abs), mode & 0o777);
+            if (thirdParty) thirdPartyFiles.add(`${outPrefix}skills/${name}/${rel}`);
+            continue;
+          }
+          const content = await readFile(abs, 'utf-8');
+          const isSkillMd = rel === 'SKILL.md' || rel.endsWith('/SKILL.md');
+          if (isSkillMd) {
+            const { frontmatter } = splitFrontmatter(content);
+            if (!frontmatter) throw new Error(`${rel} has no frontmatter (name + description are required)`);
+            checkDescriptionYaml(frontmatter, `${where}/${rel}`, errors);
+            if (hasMaintenanceMarker(frontmatter)) {
+              throw new Error(`${rel} carries disable-model-invocation: true — maintenance skills belong in assets/claude-committed/skills/, not the plugin tree`);
+            }
+          }
+          if (!shared) put(`${outPrefix}skills/${name}/${rel}`, rel === 'SKILL.md' ? convertSkillMd(content) : convertSkillMarkdownFile(content), mode & 0o777);
+        }
+        if (shared) continue; // a pack's copy of a shared skill: validated below, never mirrored
+        counts.skills += 1;
+        if (thirdParty) { counts.thirdParty += 1; continue; } // no tiers, no instructions: upstream's skill as-is
+
+        if (rels.includes('SKILL.md')) {
+          const content = await readFile(join(srcDir, 'SKILL.md'), 'utf-8');
+          const { frontmatter } = splitFrontmatter(content);
+          const instructions = convertSkillToInstructions(content, name);
+          const tier = readInstructionTier(frontmatter);
+          if (instructions) {
+            if (!COPILOT_INSTRUCTION_TIERS.includes(tier)) {
+              throw new Error(`carries copilot-apply-to but copilot-instructions-tier is ${tier === null ? 'missing' : `"${tier}"`} — set core or extended`);
+            }
+            if (tier === 'core') {
+              put(`instructions/${name}.instructions.md`, instructions);
+              coreInstructions.push(name);
+              counts.coreInstructions += 1;
+            } else {
+              put(`instructions-extended/${name}/${name}.instructions.md`, instructions);
+              extendedInstructions.push(name);
+              counts.extendedInstructions += 1;
+            }
+          } else if (tier !== null) {
+            throw new Error('carries copilot-instructions-tier without copilot-apply-to');
+          }
+        }
+      } catch (error) {
+        errors.push(`${where}: ${error.message}`);
       }
-      count += 1;
-    } catch (error) {
-      console.warn(`  skip skills/${name}: ${error.message}`);
     }
-  }
-  return count;
-}
+  };
 
-async function generateSkillsFromInstructions() {
-  const srcDir = join(ASSETS_DIR, 'instructions');
-  const destDir = join(CLAUDE_DIR, 'skills');
-  await ensureDir(destDir);
+  // The core plugin.
+  await scanAgents(join(assetsDir, SCAN_ROOT_RELATIVE_PATHS.pluginAgents), { pack: 'core', outPrefix: '', whereBase: 'claude/agents' });
+  await scanSkills(join(assetsDir, SCAN_ROOT_RELATIVE_PATHS.pluginSkills), { pack: 'core', outPrefix: '', whereBase: 'claude/skills' });
+
+  // The packs — each a plugin of its own, mirrored under `packs/<pack>/`.
+  const packs = await listPackNames(assetsDir);
+  const version = await readPackageVersion(assetsDir);
+  for (const pack of packs) {
+    if (!/^[a-z][a-z0-9-]*$/.test(pack)) { errors.push(`claude/packs/${pack}: pack names are kebab-case`); continue; }
+    await checkPackManifest(assetsDir, pack, version, errors);
+    const packDir = join(assetsDir, SCAN_ROOT_RELATIVE_PATHS.packs, pack);
+    await scanAgents(join(packDir, 'agents'), { pack, outPrefix: `packs/${pack}/`, whereBase: `claude/packs/${pack}/agents` });
+    await scanSkills(join(packDir, 'skills'), { pack, outPrefix: `packs/${pack}/`, whereBase: `claude/packs/${pack}/skills` });
+    for (const child of await listChildren(packDir, 'dir')) {
+      if (!['agents', 'skills'].includes(child)) errors.push(`claude/packs/${pack}/${child}: a pack holds only agents/ and skills/ (plus .claude-plugin/)`);
+    }
+    counts.packs += 1;
+  }
+  await checkMarketplace(assetsDir, packs, errors);
+
+  // Shared skills: every pack copy must be byte-identical to the core (run the generator to sync).
+  for (const [rel, content] of await expectedSharedPackSkillFiles({ assetsDir })) {
+    let current = null;
+    try { current = await readFile(join(assetsDir, 'claude', ...rel.split('/'))); } catch { current = null; }
+    if (!current || !current.equals(content)) {
+      errors.push(`claude/${rel}: ${current ? 'differs from' : 'missing —'} the core copy in claude/skills/ (run node scripts/generate-claude-assets.js to sync the shared pack skills)`);
+    }
+  }
+  for (const pack of packs) {
+    for (const skill of SHARED_PACK_SKILLS) {
+      if (!existsSync(join(assetsDir, SCAN_ROOT_RELATIVE_PATHS.packs, pack, 'skills', skill))) {
+        errors.push(`claude/packs/${pack}/skills/${skill}: missing — every pack carries a copy of the shared skill (run the generator to sync)`);
+      }
+    }
+  }
 
-  const names = await listAssetFolders(srcDir);
-  let count = 0;
-  for (const name of names) {
-    const srcPath = join(srcDir, name, `${name}.instructions.md`);
+  // 3. Committed skills → maintenance prompts. Every committed skill MUST be one.
+  const committedDir = join(assetsDir, SCAN_ROOT_RELATIVE_PATHS.committedSkills);
+  const prompts = [];
+  for (const name of await listChildren(committedDir, 'dir')) {
+    const where = `claude-committed/skills/${name}`;
     try {
-      const content = await readFile(srcPath, 'utf-8');
-      const converted = convertInstructionToSkill(content, name);
-      const skillDir = join(destDir, name);
-      await ensureDir(skillDir);
-      await writeFile(join(skillDir, 'SKILL.md'), converted, 'utf-8');
-      count += 1;
+      const content = await readFile(join(committedDir, name, 'SKILL.md'), 'utf-8');
+      const { frontmatter } = splitFrontmatter(content);
+      if (!frontmatter) throw new Error('SKILL.md has no frontmatter');
+      if (!isCommittedMaintenanceSkill(`${SCAN_ROOT_RELATIVE_PATHS.committedSkills}/${name}`, frontmatter)) {
+        throw new Error('committed skill lacks disable-model-invocation: true — it would be silently dropped from the Copilot catalog');
+      }
+      checkDescriptionYaml(frontmatter, `${where}/SKILL.md`, errors);
+      put(`prompts/${name}.prompt.md`, convertMaintenanceSkillToPrompt(content));
+      prompts.push(name);
+      counts.prompts += 1;
     } catch (error) {
-      console.warn(`  skip instructions/${name}: ${error.message}`);
+      errors.push(`${where}: ${error.message}`);
     }
   }
-  return count;
-}
 
-async function main() {
-  console.log('Generating Claude Code target assets from Copilot sources...\n');
+  // 4. Mapping gaps recorded by the pure converters are errors here.
+  errors.push(...getDiagnosticMessages());
 
-  const agentCount = await generateAgents();
-  console.log(`✓ agents:       ${agentCount} converted -> assets/claude/agents/`);
+  // 5. Residue over the WHOLE generated tree — except upstream's own text (third-party skills).
+  for (const [rel, { content }] of files) {
+    if (!rel.endsWith('.md') || thirdPartyFiles.has(rel)) continue;
+    errors.push(...findCopilotResidue(rel, content.toString('utf-8')));
+  }
 
-  const promptCount = await generatePrompts();
-  console.log(`✓ prompts:      ${promptCount} converted -> assets/claude/commands/`);
+  const agents = Object.keys(assetPacks.agents).sort();
+  const skills = Object.keys(assetPacks.skills).sort();
+  const sortedRecord = (rec) => Object.fromEntries(Object.keys(rec).sort().map((k) => [k, rec[k]]));
+  const manifest = {
+    version: '1.0.0',
+    description: 'Available Vesper assets. Use with: vespercli add agents|prompts|instructions|skills <name>; packs with: vespercli packs list|enable|disable|sync',
+    packs,
+    agents,
+    prompts: prompts.sort(),
+    coreInstructions: coreInstructions.sort(),
+    instructions: extendedInstructions.sort(),
+    skills,
+    assetPacks: { agents: sortedRecord(assetPacks.agents), skills: sortedRecord(assetPacks.skills) },
+  };
 
-  const skillCount = await generateSkillsFromSkills();
-  console.log(`✓ skills:       ${skillCount} copied -> assets/claude/skills/`);
+  return { files, manifest, errors, counts };
+}
 
-  const instructionSkillCount = await generateSkillsFromInstructions();
-  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.');
+/** Serialize the global manifest (no timestamp: parallel worktrees must merge cleanly). */
+export function serializeManifest(manifest) {
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
 
-  // 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;
+/**
+ * Write the tree atomically: temp sibling dir → rename swap → drop the old tree.
+ * @param {Map<string, {content: Buffer, mode: number}>} files
+ * @param {string} [outDir=COPILOT_DIR]
+ */
+export async function writeTreeAtomically(files, outDir = COPILOT_DIR) {
+  const parent = dirname(outDir);
+  const stamp = `${process.pid}-${Date.now()}`;
+  const tmp = join(parent, `.copilot.tmp-${stamp}`);
+  const old = join(parent, `.copilot.old-${stamp}`);
+  try {
+    for (const [rel, { content, mode }] of files) {
+      const dest = join(tmp, ...rel.split('/'));
+      await mkdir(dirname(dest), { recursive: true });
+      await writeFile(dest, content);
+      await chmod(dest, mode);
+    }
+    if (existsSync(outDir)) await rename(outDir, old);
+    await rename(tmp, outDir);
+  } catch (error) {
+    await rm(tmp, { recursive: true, force: true });
+    if (!existsSync(outDir) && existsSync(old)) await rename(old, outDir); // restore
+    throw error;
   }
-  if (sawUnmappableGlob && strict) {
-    console.error('\n✗ Unmappable applyTo glob(s) encountered (see warnings above). Failing build (CI/--strict).');
+  await rm(old, { recursive: true, force: true });
+}
+
+async function main() {
+  console.log('Generating Copilot target assets from the canonical Claude sources...\n');
+  // The one canonical-tree write: refresh each pack's copy of the shared skills from the core.
+  const synced = await syncSharedPackSkills();
+  if (synced.length) console.log(`✓ shared pack skills synced from the core: ${synced.length} file(s)\n`);
+  const { files, manifest, errors, counts } = await buildCopilotTree();
+  if (errors.length > 0) {
+    console.error(`✗ ${errors.length} error(s) — nothing was written:\n`);
+    for (const e of errors) console.error(`  - ${e}`);
     process.exitCode = 1;
+    return;
   }
+  await writeTreeAtomically(files);
+  await writeFile(join(ASSETS_DIR, 'manifest.json'), serializeManifest(manifest), 'utf-8');
+
+  console.log(`✓ agents:       ${counts.agents} -> assets/copilot/agents/ + packs/<pack>/agents/ (all user-invocable: false)`);
+  console.log(`✓ skills:       ${counts.skills} -> assets/copilot/skills/ + packs/<pack>/skills/ (every .md rendered; ${counts.thirdParty} third-party copied verbatim)`);
+  console.log(`✓ packs:        ${counts.packs} (${manifest.packs.join(', ') || 'none'}) -> assets/copilot/packs/<pack>/`);
+  console.log(`✓ instructions: ${counts.coreInstructions} core -> assets/copilot/instructions/, ${counts.extendedInstructions} extended -> assets/copilot/instructions-extended/<name>/`);
+  console.log(`✓ prompts:      ${counts.prompts} -> assets/copilot/prompts/`);
+  console.log('✓ manifest:     assets/manifest.json');
+  console.log('\nDone. Canonical sources (assets/claude/, assets/claude-committed/) are read-only to this script.');
 }
 
-// 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.
+// Only generate when executed directly — importing the module must NOT regenerate.
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   main().catch((error) => {
     console.error('Generation failed:', error);
     process.exit(1);
   });
 }
-
-export { extractToolTokens, mapToolTokens, convertAgent, describeApplyTo, convertInstructionToSkill };