@mthanh/vespercli 1.7.1 → 2.0.0

package/scripts/generate-claude-assets.js

@@ -1,383 +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.
+ *
+ * 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 { fileURLToPath } from 'node:url';
+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 {
+  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',
-  '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');
 
-/** Pure-VS-Code tokens with no Claude Code equivalent — dropped, not mapped */
-const DROP_TOKENS = new Set([
-  'vscode/getProjectSetupInfo',
-  'vscode/installExtension',
-  'vscode/newWorkspace',
-  'vscode/openSimpleBrowser',
-  'vscode/runCommand',
-  'vscode/vscodeAPI',
-  'vscode/extensions',
-  'vscode',
-]);
+/** The two canonical, hand-authored roots (assets-relative). */
+export const CANONICAL_ROOTS = Object.freeze(['claude', 'claude-committed']);
 
-/** MCP-namespaced tokens pass through as mcp__<server>__* wildcards (kept as a note, not expanded) */
-const MCP_PASSTHROUGH = ['vesper-indexing/*', 'memory/*', 'sequential-thinking/*', 'context7/*'];
-
-// 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',
-};
+/**
+ * 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.
+ */
+export const SCAN_ROOT_RELATIVE_PATHS = Object.freeze({
+  pluginAgents: 'claude/agents',
+  pluginSkills: 'claude/skills',
+  packs: 'claude/packs',
+  committedSkills: 'claude-committed/skills',
+});
+
+/** Plugin name prefix of every pack: `vesper-<pack>` (the core plugin is `vesper`). */
+export const PACK_PLUGIN_PREFIX = 'vesper-';
 
 /**
- * Parse a simple `tools: [...]` frontmatter array (single or multi-line) into a token list.
- * @param {string} frontmatter
- * @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 extractToolTokens(frontmatter) {
-  const match = frontmatter.match(/tools:\s*\[([\s\S]*?)\]/);
-  if (!match) return [];
-  return match[1]
-    .split(',')
-    .map(t => t.trim().replace(/^['"]|['"]$/g, ''))
-    .filter(Boolean);
+export const UPSTREAM_RECORD_FILE = 'UPSTREAM.json';
+
+/** Is this skill folder third-party (carries an `UPSTREAM.json`)? */
+export function isThirdPartySkillDir(skillDir) {
+  return existsSync(join(skillDir, UPSTREAM_RECORD_FILE));
+}
+
+/** 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`);
 }
 
 /**
- * Convert a Copilot tool-token list into a Claude Code `tools:` frontmatter value.
- * @param {string[]} tokens
- * @returns {string}
+ * 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.
  */
-function mapToolTokens(tokens) {
-  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()));
-    }
-  }
+export const SHARED_PACK_SKILLS = Object.freeze(['agent-fundamentals']);
 
-  // Expand known MCP servers to their concrete tool names (best-effort; unknown servers noted as-is).
-  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'],
-  };
-  for (const server of mcpNotes) {
-    (MCP_TOOL_NAMES[server] || []).forEach(t => claudeTools.add(t));
+/** 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 [];
   }
+}
+
+/**
+ * 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.
+ */
+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));
-
-  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;
+export function isCommittedMaintenanceSkill(skillDir, frontmatter) {
+  const rel = toAssetsRelative(skillDir);
+  if (!rel.startsWith(`${SCAN_ROOT_RELATIVE_PATHS.committedSkills}/`)) return false;
+  return hasMaintenanceMarker(frontmatter);
+}
 
-  const [, frontmatter, body] = frontmatterMatch;
-  const descriptionMatch = frontmatter.match(/description:\s*['"]?(.*?)['"]?\s*(\n|$)/);
-  const description = descriptionMatch ? descriptionMatch[1] : '';
+/** Source-only files never copied into the generated catalog. */
+const SKIPPED_SOURCE_FILES = new Set(['manifest.json', 'skill.json']);
 
-  const newFrontmatter = description ? `description: ${description}` : '';
-  const cleanedBody = applyBodyTokenReplacements(body).replace(/\$\{input:[^}]+\}/g, '$ARGUMENTS');
+/**
+ * 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.
+ */
+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' },
+]);
 
-  return newFrontmatter ? `---\n${newFrontmatter}\n---\n${cleanedBody}` : cleanedBody;
-}
+/**
+ * `path → tokens allowed there`. Keep this list SHORT and justified; the residue
+ * test prints the offending file + line for anything not listed.
+ */
+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'],
+});
 
 /**
- * Convert an `.instructions.md` file into a new Skill (SKILL.md).
- * @param {string} content
- * @param {string} kebabName
- * @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 convertInstructionToSkill(content, kebabName) {
-  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
-  if (!frontmatterMatch) return content;
+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;
+}
 
-  const [, frontmatter, body] = frontmatterMatch;
-  const descriptionMatch = frontmatter.match(/description:\s*['"]?(.*?)['"]?\s*(\n|$)/);
-  const applyToMatch = frontmatter.match(/applyTo:\s*['"]?(.*?)['"]?\s*(\n|$)/);
+// ---------------------------------------------------------------------------
+// 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 baseDescription = descriptionMatch ? descriptionMatch[1] : `${kebabName} conventions`;
-  const applyTo = applyToMatch ? applyToMatch[1] : '';
-  const description = applyTo
-    ? `${baseDescription} Use when working with files matching: ${applyTo}.`
-    : baseDescription;
+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();
+}
 
-  const newFrontmatter = [`name: ${kebabName}`, `description: ${description}`].join('\n');
-  const cleanedBody = applyBodyTokenReplacements(body);
+/** 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;
+  }
+  if (!isYamlSafeInlineScalar(line.slice('description:'.length))) {
+    errors.push(`${where}: unquoted description is not valid YAML (contains ": " or a YAML indicator) — quote it`);
+  }
+}
 
-  return `---\n${newFrontmatter}\n---\n${cleanedBody}`;
+/** 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; }
+}
+
+/** 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;
 }
 
 /**
- * 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 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 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 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}"`);
 }
 
-async function ensureDir(dir) {
-  await mkdir(dir, { recursive: true });
+/**
+ * Validate the marketplace: it must list the core plugin (`vesper`, `source: "./"`) and every
+ * pack (`vesper-<pack>`, `source: "./packs/<pack>"`), and nothing else.
+ */
+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`;
 }
 
-main().catch((error) => {
-  console.error('Generation failed:', error);
-  process.exit(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;
+  }
+  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 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);
+  });
+}