@mthanh/vespercli 1.8.0 → 2.0.0

package/assets/claude/skills/vesper-catalog-editing-safety/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vesper-catalog-editing-safety
-description: Pre-edit safety checklist for touching Vesper's own asset catalog and provisioning code — assets/, scripts/generate-claude-assets.js, src/cli/utils/settings.js, src/cli/utils/claude-target.js. Use before editing any catalog asset (agent, skill, prompt, instruction), the Claude-asset generator, or the Copilot/Claude settings-injection code in this repo. Prevents re-deriving the dual-target distribution model from scratch and catches the generator-boundary and git-hygiene-dual-list traps that have already caused a blocking architecture-review finding and a shipped bug.
+description: Pre-edit safety checklist for touching Vesper's own asset catalog and provisioning code — assets/, scripts/generate-claude-assets.js, src/cli/utils/settings.js, src/cli/utils/claude-target.js. Use before editing any catalog asset (agent or skill), the Copilot-asset generator, or the Copilot/Claude settings-injection code in this repo. Prevents re-deriving the one-host-per-workspace distribution model from scratch and catches the generator-boundary and git-hygiene-dual-list traps that have already caused a blocking architecture-review finding and a shipped bug.
 ---
 
 # Vesper Catalog Editing Safety
@@ -9,16 +9,18 @@ description: Pre-edit safety checklist for touching Vesper's own asset catalog a
 
 This repo (`@mthanh/vespercli`) is self-hosting: it produces the very agent/skill/prompt catalog it installs into itself and every other project. That self-hosting creates footguns that are easy to rediscover the hard way — one already caused a blocking architecture-review finding, another shipped as a real bug. This skill is a **pre-flight checklist**, not the narrative — walk it before touching provisioning code or catalog assets, and follow the links when you need the full story.
 
-Full narrative + citations: [`docs/architecture.md`](../../../docs/architecture.md). Terse always-loaded version: `.claude/vesper/context.md`'s Conventions section. Read this skill first — it tells you *which* parts of those two documents matter for the edit in front of you.
+Full narrative + citations: [`docs/architecture.md`](../../../docs/architecture.md) (rewritten for 2.0) and the user-facing model in [`README.md`](../../../README.md). Terse always-loaded version: the project whitepaper's Conventions section. Read this skill first — it tells you *which* parts of those documents matter for the edit in front of you.
+
+> **Stale-marker note.** A reference anywhere to `assets/core/`, `assets/agents/`, `assets/instructions/`, `assets/prompts/` or `assets/skills/`, to a committed Claude catalog under `.claude/{agents,commands,skills}`, to `@import`ed `.claude/vesper/*.md` playbook files, or to the `SessionStart(clear)` reinject hook describes the retired 1.x layout. Flag it; don't follow it.
 
 ## When to Use This Skill
 
 Load this skill before:
 
-- Editing anything under `assets/` — core, extended, or the generated `assets/claude/` tree
+- Editing anything under `assets/` — the canonical `assets/claude/` + `assets/claude-committed/` trees, or the generated `assets/copilot/` output root
 - Editing `scripts/generate-claude-assets.js`
 - Editing `src/cli/utils/settings.js` or `src/cli/utils/claude-target.js`
-- Planning or reviewing a change that touches how Copilot or Claude Code *discovers* a Vesper asset (settings arrays, plugin install, guard blocks, reinject hooks)
+- Planning or reviewing a change that touches how Copilot or Claude Code *discovers* a Vesper asset (settings arrays, plugin declaration, `.claude/rules/`, the `CLAUDE.md` pointer)
 - Editing `.claude/rules/*.md`, `.vesper/instructions/`, or `.vesper/skills/` override paths
 - Editing `VESPER_GIT_PATHS` (`settings.js`) or `assets/hooks/pre-commit`
 - Reviewing a plan/PR that proposes any of the above — this is a research **and** review-time checklist, not just an implementation-time one
@@ -29,83 +31,104 @@ Load this skill before:
 
 | You're touching...                                                    | Go to        |
 | ----------------------------------------------------------------------- | ------------ |
-| A file under `assets/agents/`, `assets/skills/`, `assets/instructions/`, `assets/prompts/`, or `assets/claude/*` | Checklist A — Dual Asset Tree |
+| A file under `assets/claude/*`, `assets/claude-committed/*`, or `assets/copilot/*` | Checklist A — Dual Asset Tree |
 | `scripts/generate-claude-assets.js` itself                              | Checklist A  |
 | `.vesper/instructions/`, `.vesper/skills/`, or a new `.claude/rules/*.md` | Checklist B — Discovery Wiring |
 | `getCoreAssetEntries()` or `VSCODE_SETTINGS_MAP` in `settings.js`        | Checklist B  |
-| `ensureClaudeMdGuardBlock()` or `VESPER_REINJECT_COMMAND` in `claude-target.js` | Checklist B |
+| `ensureClaudeMdGuardBlock()`, `installClaudeProjectFiles()` or `configureClaudeSettings()` in `claude-target.js` | Checklist B |
 | `VESPER_GIT_PATHS` in `settings.js`, or `assets/hooks/pre-commit`        | Checklist C — Git-Hygiene Dual List |
-| Anything about which target (Copilot vs Claude) gets what               | Checklist D — Distribution Model (background only) |
+| Anything about which host (Copilot vs Claude) gets what                 | Checklist D — Distribution Model (background only) |
 
 Most edits hit exactly one checklist. If unsure, read Checklist D first — it's the model everything else sits on.
 
 ### Checklist A — Dual Asset Tree (the highest-value trap)
 
-`scripts/generate-claude-assets.js` has a narrow, explicit remit — verified against its own header comment (`scripts/generate-claude-assets.js:11-14`):
+**Direction of travel (Vesper 2.0): Claude-format is the hand-authored source; Copilot-format is generated output.** This is the reverse of the 1.x model — if you remember it the other way round, you are remembering a retired layout. The old hand-authored Copilot-format trees (`assets/core/`, `assets/agents/`, `assets/instructions/`, `assets/prompts/`, `assets/skills/`) **no longer exist**; do not look for them, do not re-create them.
+
+There are exactly **two canonical authored roots**, and `scripts/generate-claude-assets.js` scans them to emit **one** generated root:
 
-| Copilot source                                        | Claude output                                           |
-| ------------------------------------------------------- | ----------------------------------------------------------- |
-| `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)         |
+| Canonical source (hand-authored)                                              | Generated Copilot output (never hand-edited)             |
+| ------------------------------------------------------------------------------ | ---------------------------------------------------------- |
+| `assets/claude/agents/<name>.md`                                              | `assets/copilot/agents/<name>.agent.md` (`user-invocable: false`) |
+| `assets/claude/skills/<name>/`                                                | `assets/copilot/skills/<name>/` (every `.md` rendered by `src/cli/utils/copilot-render.js`) |
+| `assets/claude/skills/<name>/SKILL.md` carrying `copilot-apply-to` + `copilot-instructions-tier: core` | *also* `assets/copilot/instructions/<name>.instructions.md` (injected for every project) |
+| `assets/claude/skills/<name>/SKILL.md` carrying `copilot-apply-to` + `copilot-instructions-tier: extended` | *also* `assets/copilot/instructions-extended/<name>/<name>.instructions.md` (opt-in per project) |
+| `assets/claude-committed/skills/<name>/` carrying `disable-model-invocation: true` | `assets/copilot/prompts/<name>.prompt.md`              |
 
-**That table is the entire remit.** `assets/core/` is never read by this script, at all — by design, not by omission (the script's own comment: *"the 12 core agents + the orchestrator playbook are hand-authored separately in assets/claude/ and are never touched by this script"*). Neither is `assets/vendor/` — reviewed, pinned third-party snapshots (e.g. `assets/vendor/i-have-adhd/`, `assets/vendor/ponytail/`) live outside the four scan roots and the three write targets on purpose. A vendored asset is edited only by re-vendoring (a reviewed PR bumping its pinned SHA), never through the generator; do not move it under `assets/skills/` or `assets/claude/` to "make the generator pick it up."
+**That table is the entire remit.** Everything else under the two roots is **explicitly excluded** from the scan (`EXCLUDED_SOURCE_PATHS` / `isExcludedSource()` in the generator): `assets/claude/.claude-plugin/`, `assets/claude/commands/`, the three root files `assets/claude/{vesper-orchestrator.md, orchestration.md.tpl, context.md.tpl}`, and `assets/claude-committed/agents/`. `assets/hooks/` and `assets/legacy/` are excluded too — git-hook assets and the 1.x proof table live outside the scan roots on purpose. **Third-party skills** (`gitlab-ci-skill`, `github-actions-to-gitlab-ci` in `packs/integrations`; `i-have-adhd`, `ponytail` in the opt-in `packs/styles`) ARE under a scan root, but each carries an `UPSTREAM.json` beside its `SKILL.md`, which makes it third-party to the generator: copied verbatim into the Copilot mirror (`UPSTREAM.json` and `LICENSE` included), never rendered, never residue-scanned. Never hand-edit one: its bytes are upstream's, refreshed only by `npm run vendor:sync [name]` (`scripts/vendor-sync.js`, which rewrites `UPSTREAM.json`); a hand edit is silently undone by the next sync.
 
-- [ ] Is the file under `assets/core/`?
-  - **Yes** → There is no generator step for you. Hand-edit **both** the Copilot source (`assets/core/{agents,skills,instructions,prompts}/...`) **and** its `assets/claude/` twin. Before editing the twin, check it for **Claude-only content that doesn't exist in the Copilot source** and preserve it — e.g. `assets/claude/skills/agent-fundamentals/SKILL.md`'s `## Direct Collaboration (Nested Delegation)` section has no Copilot-side counterpart. Never diff the two sides expecting them to match; they're allowed to diverge by design.
-  - **No** (it's under `assets/agents/`, `assets/skills/`, `assets/instructions/`, or `assets/prompts/`) → Edit the Copilot source only, then run `node scripts/generate-claude-assets.js` to regenerate its Claude twin. **Never hand-edit anything under `assets/claude/`** for a file that came from this table — your edit will be silently clobbered (or drift undetected) the next time the generator runs.
-- [ ] If you're editing `assets/claude/` directly right now — stop and confirm which case above you're actually in. Hand-editing generated output is the single most common way this trap gets tripped.
-- [ ] If your task is planning/reviewing (not implementing) a catalog change: confirm the plan doesn't assume a core-skill/core-agent edit will "just flow through" the generator step. It won't — this exact wrong assumption produced a blocking architecture-review finding (BC-2) and a near-miss self-contradiction in an agent's own file-write rules in a prior session.
+- [ ] Is the file under `assets/copilot/`?
+  - **Yes** → **Stop. That is generated output.** Find the canonical source in the table above, edit *that*, and regenerate. Your edit here will be silently clobbered — the generator rebuilds the whole output root from the canonical sources on every run (atomically: temp dir, then rename). Hand-editing generated output is the single most common way this trap gets tripped.
+  - **No** (it's under `assets/claude/` or `assets/claude-committed/`) → This is hand-authored canonical source. Edit it directly, then regenerate (see the run order below).
+- [ ] **One command.** `node scripts/generate-claude-assets.js` rebuilds `assets/copilot/` AND `assets/manifest.json` (no timestamp, no per-skill manifests). It is STRICT — any bad source (missing/unsafe frontmatter, a committed skill without its marker, a plugin skill with it, an unmapped tool or model, Claude-host residue) fails the run and writes nothing — so fix the reported source rather than working around it. `scripts/generate-manifests.js` still exists but only rewrites the global manifest.
+- [ ] **All Copilot renaming lives in ONE pure module**, `src/cli/utils/copilot-render.js` (path homes, the single roster/whitepaper path, `vesper:` namespace stripping). The generator and the runtime Copilot provisioning both import it. Never add a Copilot inversion anywhere else, and never import from `scripts/` under `src/` (a test enforces it — the CLI bundle once inlined the generator and regenerated the installed assets mid-command).
+- [ ] The generated output root is **committed**, not gitignored — that is deliberate (it keeps `init` offline-capable and the injected Copilot settings paths resolvable before any build step). So a regeneration shows up as a real file diff in your PR. That diff is expected; an *absent* diff after a source edit means you forgot to regenerate.
+- [ ] The two canonical roots are **not** twins of each other and must never be diffed expecting a match. `assets/claude/` is the marketplace **plugin** catalog; `assets/claude-committed/` is the **project-committed** partition (see Checklist D). A name appearing in both is a real bug, not a mirror.
+- [ ] The maintenance-skill discriminator (`disable-model-invocation: true`) is **not globally unique** — the third-party `assets/claude/packs/styles/skills/i-have-adhd/SKILL.md` also carries it (allowed there because the skill is third-party). The single-key rule is safe *only* because prompt emission is scan-scoped to `assets/claude-committed/skills/`. If you change the scan roots, you can silently start emitting prompts from third-party or plugin content. Tree location is the signal, not the key alone.
+- [ ] If your task is planning/reviewing (not implementing) a catalog change: confirm the plan doesn't assume the 1.x direction (Copilot source → Claude output). It is inverted. The 1.x-shaped wrong assumption produced a blocking architecture-review finding (BC-2) and a near-miss self-contradiction in an agent's own file-write rules in a prior session; the same class of error now looks like "edit `assets/copilot/` and expect it to stick."
 
-### Checklist B — Local Overrides vs. Discovery Wiring (per target)
+### Checklist B — Local Overrides vs. Discovery Wiring (per host)
 
-"A file exists at the right path" and "the target actually discovers it" are two different guarantees — satisfied differently per target.
+"A file exists at the right path" and "the host actually discovers it" are two different guarantees — satisfied differently per host. A workspace runs exactly **one** host (`.vesperrc.host`); a Copilot workspace never gets a `.claude/*` file and a Claude workspace never gets Copilot settings, apart from the cross-host guard trigger.
 
-**Copilot** — `.vesper/instructions/*.instructions.md` and `.vesper/skills/**/SKILL.md` are project-local override paths. They are **inert on their own**.
+**Copilot** — the per-project brain (`.vesper/agents/vesper-orchestrator.agent.md`, `.vesper/instructions/vesper-*.instructions.md`, `.vesper/context/`) and the override paths `.vesper/instructions/*.instructions.md` / `.vesper/skills/**/SKILL.md` are **inert on their own**.
 
-- [ ] Does `getCoreAssetEntries()` (`src/cli/utils/settings.js:1321-1363`, appending entries around lines 1348-1360) explicitly include a `${workspaceFolder}/.vesper/instructions` and `${workspaceFolder}/.vesper/skills` entry in the arrays it writes into `.vscode/settings.json` (keyed by `VSCODE_SETTINGS_MAP`, `settings.js:70-75`)? If you're adding a *new* override path convention, it needs the equivalent wiring here — a path convention alone is invisible to Copilot without a matching settings-array entry. This exact gap was found and fixed once already.
+- [ ] Does `getCoreAssetEntries()` (`src/cli/utils/settings.js`) include the `${workspaceFolder}/.vesper/{agents,instructions,skills}` entries it writes into `.vscode/settings.json` (keyed by `VSCODE_SETTINGS_MAP` in the same file), next to the package's `assets/copilot/` folders? A *new* project-local path convention needs the equivalent wiring here — a path alone is invisible to Copilot without a matching `chat.*Locations` entry. This exact gap was found and fixed once already.
+- [ ] Is `${workspaceFolder}/.vesper/agents` still written? It is also a Copilot **fingerprint** (`fingerprints.js`): the checked-out tree resolves the host from it. Renaming or dropping it changes host resolution, not just discovery.
 
-**Claude Code** — `.claude/skills/{domain}/SKILL.md` needs no wiring; it's natively auto-discovered. `.claude/rules/{name}.md` is different — it has two moving parts, neither of which is native Claude Code behavior:
+**Claude Code** — `.claude/skills/{name}/SKILL.md` and `.claude/rules/*.md` are both **natively** discovered; no settings wiring and no `@import`.
 
-- [ ] Does `CLAUDE.md` carry an `@.claude/rules/{name}.md` import line **outside** the `<!-- vesper:start -->...<!-- vesper:end -->` guard block? (`ensureClaudeMdGuardBlock()`, `src/cli/utils/claude-target.js:257`.) Inside the guard block, it gets regenerated away on the next `update`/`/reinit`.
-- [ ] Does the rule still need to survive `/clear`? The `SessionStart(clear)` reinject hook (`VESPER_REINJECT_COMMAND`, `claude-target.js:723-753`) dynamically enumerates `.claude/rules/*.md` at hook-fire time — sorted, `.md`-filtered — alongside the three fixed `.claude/vesper/*.md` playbook files. You don't need to register a new rule file anywhere for this to work; a missing `.claude/rules/` directory is swallowed by an outer try/catch (no-op). But if you're changing the *enumeration logic itself*, verify it still globs correctly.
+- [ ] The always-on playbook, roster and slim whitepaper are `.claude/rules/vesper-{orchestrator,orchestration,context}.md` (`installClaudeProjectFiles()`). A new always-on Vesper rule goes in `.claude/rules/` too — never an `@import` in `CLAUDE.md`, which would double-load it.
+- [ ] The `CLAUDE.md` guard block (`<!-- vesper:start -->…<!-- vesper:end -->`, `ensureClaudeMdGuardBlock()`) is a **prose pointer only**. Don't add `@import` lines to it; it is regenerated on every `init`/`update`.
+- [ ] Vesper writes **no** `CLAUDE.md` `@import` at all any more (the pre-epic-J opt-in styles' marker-scoped blocks are stripped by `init` / `reset`). The one always-on file a pack writes is the `styles` pack's pointer rule `.claude/rules/vesper-styles.md` (`pack-rules.js`), a Vesper-authored ~10-line file, never third-party text.
+- [ ] The plugin is **declared, not copied**: `configureClaudeSettings()` writes `enabledPlugins["vesper@vesper-marketplace"]` and `agent: "vesper-orchestrator"` into the committed `.claude/settings.json`; `configureClaudeMarketplaceLocal()` writes the machine-local marketplace `source` into the gitignored `.claude/settings.local.json`. Both committed keys are Claude **fingerprints** — the same resolution caveat as Copilot's `.vesper/agents`.
+- [ ] There is no `SessionStart(clear)` reinject hook in 2.0 (rules survive `/clear` natively). The one Vesper `SessionStart` entry is the host guard (`VESPER_CLAUDE_GUARD_COMMAND`).
 
 ### Checklist C — Git-Hygiene Dual List (no single source of truth)
 
-`VESPER_GIT_PATHS` (`src/cli/utils/settings.js:173-185`) and the `vesper_git_paths` shell string in `assets/hooks/pre-commit:16` describe the same set of "project knowledge that must ride along with any commit touching other work." They are **hand-mirrored**, not generated from one source.
+`VESPER_GIT_PATHS` (`src/cli/utils/settings.js`) and the `vesper_git_paths` shell string in `assets/hooks/pre-commit` describe the same set of "project knowledge that must ride along with any commit touching other work." They are **hand-mirrored**, not generated from one source.
 
 - [ ] Edited one list? Edit the other too, in the **same relative order**. There is no codegen link between them (open technical debt) — nothing will catch a divergence for you.
 - [ ] Every entry is **slash-less** (`.claude/skills`, never `.claude/skills/`). A trailing slash turns the pre-commit hook's match clause (`case "$candidate" in "$p"/*)`) into a pattern with a literal double slash that never matches a real staged path — silently defeating the guardrail for that one entry. This has already shipped as a real bug once.
+- [ ] The sweep is for **human** commits. `VESPER_NO_SWEEP=1` (set by agents, which stage by path) skips it: nothing is staged, and one line names the dirty paths left out. Changing what the block does? `doctor`'s `git-hook-outdated` check keys on marker strings in the installed block (`vesper.hooks`, and `VESPER_NO_SWEEP` for pre-commit) — add a marker when older installed blocks must be flagged; `worktree bootstrap` rewrites any block that differs.
 
 ### Checklist D — Distribution Model (background, read when the trap isn't obvious)
 
-- **Copilot**: nothing is copied into the project. Vesper injects settings entries (`chat.agentFilesLocations` / `chat.instructionsFilesLocations` / `chat.promptFilesLocations` / `chat.agentSkillsLocations`, see `VSCODE_SETTINGS_MAP` at `settings.js:70-75`) into `.vscode/settings.json`, pointing at the installed npm package's `assets/` tree. `getCoreAssetEntries()` (`settings.js:1321-1363`) assembles the full entry list.
-- **Claude Code**: the catalog is a **user-level plugin**, installed once and shared across every project on the machine — `~/.claude/skills/vesper/{agents,commands,skills}/`. `getClaudePluginDir()` (`claude-target.js:36-38`) resolves the path; `installClaudePluginCatalog()` (`claude-target.js:157-171`) performs the install/refresh. Only a small per-project set of files lives in the repo itself: `.claude/vesper/{orchestrator,orchestration,context}.md`, `.mcp.json`, `.claude/settings.json`.
-- Both targets share one on-disk index at `.vesper/index.db`.
+**One host per workspace.** `.vesperrc.host` is `claude` or `copilot`, never both; the checked-out tree decides it from Vesper-only keys in git-visible files (`host-authority.js#resolveCheckoutHost`). `.vesperrc` is a gitignored per-worktree **ledger**, not evidence. 1.x "targets" and `getInstalledTargets()` survive only as the 1.x record recogniser (it returns `[]` for any v2 ledger) — never derive a 2.0 decision from them.
 
-If your edit changes *where* either target looks, or *what* gets written into the project vs. the shared install location, this is the model to reason from before touching Checklist A/B.
+- **Copilot**: the generated catalog stays **package-resident**. `getCoreAssetEntries()` injects the installed package's `assets/copilot/{agents,prompts,skills}` folders and core `instructions/`, plus the project's `${workspaceFolder}/.vesper/{agents,instructions,skills}` into `chat.{agent,instructions,prompt,agentSkills}FilesLocations` in `.vscode/settings.json`. That is why `assets/copilot/` is committed: the paths must resolve straight out of an npm install. The per-project brain is rendered under `.vesper/` by `copilot-target.js` (through `copilot-render.js`). Nothing is written to `.github/` or `.claude/`.
+- **Claude Code**: delivery is **two-part**, and conflating the halves is the highest-value mistake here.
+  1. **The marketplace plugin (referenced, never copied).** `assets/claude/` *is* the plugin root (`.claude-plugin/`, `agents/`, `skills/`), declared in the committed `.claude/settings.json` and sourced from the gitignored `.claude/settings.local.json` (Checklist B). Specialists resolve as `vesper:<name>`. Nothing is written under `~/.claude` except what Claude Code itself writes in `~/.claude/plugins/`; `NEVER_WRITE_USER_PATHS` refuses the rest.
+  2. **The committed fallback (rendered into the repo, tracked in git).** `installClaudePluginCatalog()` writes `.claude/agents/vesper-orchestrator.md` and the four maintenance skills from `assets/claude-committed/`; `installClaudeProjectFiles()` writes `.claude/rules/vesper-*.md` and the `CLAUDE.md` pointer. This keeps a working orchestrator where the plugin doesn't resolve (cloud, headless: degraded mode). If you find yourself adding the playbook, roster, whitepaper, orchestrator agent or a maintenance skill to `assets/claude/agents/` or `assets/claude/skills/`, you are creating a competing duplicate of something that already has a committed home.
+- **Every write is recorded** in the `.vesperrc` v2 manifest (`ownership.js`: whole file + sha256, or region/key), and **removal needs proof** (`proven-removal.js`: recorded hash or pinned 1.x digest). Directories go through `removeProvenDirectory`, file by file, only when empty — a user file beside a Vesper file always survives. Never delete on name, location or a manifest entry alone (both shipped as real data loss in epic (d)).
+- **`.claude/skills/` (Claude) and `.vesper/skills/` (Copilot) are shared namespaces**: Vesper maintenance skills (Claude only), `--override` pins, and agent-authored project skills. Every prune and `reset` (`resetClaudeProjectFiles`, `removeCopilotTarget`) is manifest-scoped; there is never an enumerate-and-delete or `rm -r`.
+  - **Third-party skills are pack content, never project content (epic J).** `gitlab-ci-skill` and `github-actions-to-gitlab-ci` ship in `packs/integrations`, `i-have-adhd` and `ponytail` in the opt-in `packs/styles`, each with an `UPSTREAM.json` (`third-party.js`). Nothing installs them into a project, there is no consent prompt or flag, and `vespercli packs enable styles` is the consent for the styles — it writes the Vesper-authored pointer rule (`pack-rules.js`), recorded as `pack-rule` and removed by `packs disable` / `reset` / a host clean. `vespercli packs upstream` (and an attended `update`) only WARN about a newer upstream (`upstream.js`); `npm run vendor:sync` is the maintainer refresh.
+  - **The copies an older build placed** (`.claude/skills/<name>`, `.vesper/skills/<name>`, the rules, the `CLAUDE.md` blocks) are retired by `init` through `third-party-migration.js`, proof-first (shipped snapshot, the legacy `vendored-body` row's hashes, the pinned 1.x digests); an edited copy is kept and reported once. Never reintroduce a writer for those paths.
+- **Shared by both hosts**: `.vesper/.tracking/` (run ledger `runs/` included), `.vesper/memory.jsonl`, the read-only `.vesper/history-archive/` and the code index `.vesper/index.db`. No host switch, reset or migration touches them.
+
+If your edit changes *where* either host looks, or *what* gets written into the project vs. the shared install location, this is the model to reason from before touching Checklist A/B.
 
 ## Examples
 
-### Example 1: Adding a brand-new skill to the extended catalog
+### Example 1: Adding a brand-new skill to the catalog
 
-**Input**: "Add a new skill `assets/skills/foo-bar/SKILL.md`."
+**Input**: "Add a new skill `foo-bar`."
 
 **Process**:
-1. Checklist A applies (extended tree, not `assets/core/`).
-2. Write `assets/skills/foo-bar/SKILL.md` (+ any `references/`, `scripts/`, `assets/` subfolders) under the Copilot source tree only.
-3. Do **not** hand-write anything under `assets/claude/skills/foo-bar/` — that's the generator's job.
-4. Note in the handoff/PR that `node scripts/generate-claude-assets.js` must be run (by a maintainer or a later pipeline step with Bash access) before the skill exists on the Claude Code target.
+1. Checklist A applies. Decide which canonical root it belongs to: an ordinary model-invocable catalog skill goes in the **plugin** tree, `assets/claude/skills/foo-bar/`. It belongs in `assets/claude-committed/skills/` only if it is a project-committed maintenance workflow (and then it carries `disable-model-invocation: true`).
+2. Write `assets/claude/skills/foo-bar/SKILL.md` (+ any `references/`, `scripts/` subfolders) under the canonical tree only.
+3. Do **not** hand-write anything under `assets/copilot/skills/foo-bar/` — that's the generator's job, and the next run would clobber it anyway.
+4. If the skill should *also* surface to Copilot as an auto-applied instructions file, add a `copilot-apply-to` glob key AND a `copilot-instructions-tier:` key (`extended` = opt-in per project, the default choice for anything stack-specific; `core` = injected for every project, which counts against the 80 KB always-on budget). That is the only lossless way to get an `.instructions.md` emitted; there is no separate instructions source tree any more.
+5. Run `node scripts/generate-claude-assets.js` and commit the resulting `assets/copilot/` diff. If you lack Bash access, say so explicitly in the handoff — the change is incomplete on the Copilot host until a maintainer runs it.
 
-### Example 2: Editing a core skill (`assets/core/skills/agent-fundamentals/`)
+### Example 2: Editing a shared skill with by-design divergence (`agent-fundamentals`)
 
 **Input**: "Add a new rule to `agent-fundamentals`'s Terminal Discipline table."
 
 **Process**:
-1. Checklist A applies, `assets/core/` branch — no generator step exists.
-2. Edit `assets/core/skills/agent-fundamentals/SKILL.md` (Copilot source).
-3. Before editing `assets/claude/skills/agent-fundamentals/SKILL.md`, re-read it fully — it already carries the Claude-only `## Direct Collaboration (Nested Delegation)` section that has no Copilot-side counterpart. Add the new rule to both files without disturbing that section.
+1. Checklist A applies. There is exactly **one** authored copy now: `assets/claude/skills/agent-fundamentals/SKILL.md`. Edit it.
+2. Note that this skill carries Claude-specific content — e.g. its `## Direct Collaboration (Nested Delegation)` section — which in the 1.x layout had no Copilot-side counterpart and had to be hand-preserved across two files. That hazard is gone: there is no second authored copy to keep in sync, and the generator carries the body across through the shared render.
+3. Regenerate (Example 1, step 5). If the section genuinely should not reach Copilot, that is a generator-transform question — raise it, don't solve it by hand-editing the output.
 
 ### Example 3: Adding a `${workspaceFolder}`-relative override path for a new asset type
 
@@ -118,25 +141,32 @@ If your edit changes *where* either target looks, or *what* gets written into th
 
 ## Edge Cases
 
-**"I'm only touching `assets/claude/` to fix an obvious typo."** Still routes through Checklist A. If the source file is under the extended tree, fix the typo in the Copilot source and regenerate — don't patch the generated copy even for a one-character fix, or the next generator run silently reverts it.
+**"I'm only touching `assets/copilot/` to fix an obvious typo."** Still routes through Checklist A. Fix the typo in the canonical source and regenerate — don't patch the generated copy even for a one-character fix, or the next generator run silently reverts it.
+
+**"I'm looking for `assets/core/`, `assets/agents/`, `assets/instructions/`, `assets/prompts/` or `assets/skills/` and they're not there."** Correct — those five hand-authored Copilot-format trees were retired in 2.0. Every one of their assets has a home in `assets/claude/` or `assets/claude-committed/` (or a recorded retirement decision). Do not re-create them; find the canonical home instead. If you are reading a doc or comment that still references them, that doc is stale — flag it, don't follow it.
 
-**"The instruction/prompt/agent I'm adding doesn't map cleanly to the generator's table."** `assets/core/instructions/*.instructions.md` files are hand-folded into the orchestrator/rules constructs (Checklist B), not mechanically converted — there is no automatic instructions → Claude-skill path for core instructions the way there is for the extended tree.
+**"The asset I'm adding doesn't map cleanly to the generator's table."** The table is exhaustive for the two scan roots. Everything else under them — the plugin manifest dir, `commands/`, the root template files, `claude-committed/agents/` — is explicitly excluded and is provisioned by the Claude target code, not the generator. If your asset needs to land somewhere outside the table, that is a provisioning change (`claude-target.js` / the Copilot provisioning module), not a generator change.
 
-**"I can't tell if a file is 'core' or 'extended.'"** Core = anything under `assets/core/`. Extended = `assets/agents/`, `assets/skills/`, `assets/instructions/`, `assets/prompts/` (no `core/` segment). If genuinely ambiguous, check whether an `assets/claude/` twin already exists and whether it looks hand-authored (has Claude-only sections) vs. mechanically generated (near-verbatim mirror) — that's a strong signal of which bucket it's in.
+**"I can't tell which canonical root a file belongs to."** Plugin tree (`assets/claude/`) = shipped to every project by reference, model-invocable, not committed into the workspace. Committed partition (`assets/claude-committed/`) = rendered into the project's own `.claude/`, tracked in git, and for skills carries `disable-model-invocation: true`. If it is the orchestrator playbook, roster, whitepaper, main-thread orchestrator agent, or one of the four maintenance skills, it is committed — `plugin.json`'s description names them explicitly.
 
-**"I don't have Bash tool access to run the generator."** Note it explicitly in your output/handoff rather than silently skipping it — the change is incomplete on the Claude Code target until a maintainer or a later pipeline step runs `node scripts/generate-claude-assets.js`.
+**"I don't have Bash tool access to run the generator."** Note it explicitly in your output/handoff rather than silently skipping it — the change is incomplete on the Copilot host until a maintainer or a later pipeline step runs `node scripts/generate-claude-assets.js`.
 
 ## Related Files
 
-- `assets/` — the Copilot-format source catalog (`core/` hand-authored default install; `agents/`, `skills/`, `instructions/`, `prompts/` extended/opt-in)
-- `assets/claude/` — generated Claude-target twin of the extended tree, plus hand-maintained Claude-only twins of `assets/core/`
-- `assets/vendor/` — reviewed, pinned snapshots of third-party assets (e.g. `assets/vendor/i-have-adhd/`, `assets/vendor/ponytail/`); a generator-excluded category, installed project-level at init time, never scanned/written by the generator and never a scan root
-- `scripts/generate-claude-assets.js` — the extended-tree generator; never touches `assets/core/`
+- `assets/claude/` — **canonical hand-authored source**, and simultaneously the `vesper` marketplace plugin root (`.claude-plugin/`, `agents/`, `skills/`, plus the excluded `commands/` and root template files)
+- `assets/claude-committed/` — **canonical hand-authored source** for the project-committed partition (`agents/vesper-orchestrator.md`, the four maintenance skills)
+- `assets/copilot/` — **generated output**, committed but never hand-edited; the Copilot settings entries point here
+- `assets/claude/packs/<pack>/skills/<name>/UPSTREAM.json` — the provenance record that marks a pack skill third-party (`gitlab-ci-skill`, `github-actions-to-gitlab-ci`, `i-have-adhd`, `ponytail`); copied verbatim by the generator, refreshed only by `scripts/vendor-sync.js`
+- `scripts/generate-claude-assets.js` — the Copilot-output generator (name predates the 2.0 flip); scans the two canonical roots, wipes and rebuilds `assets/copilot/`
+- `scripts/generate-manifests.js` — rewrites only `assets/manifest.json` (the generator already writes it); no run-order constraint
 - `src/cli/utils/settings.js` — `VSCODE_SETTINGS_MAP`, `getCoreAssetEntries()`, `VESPER_GIT_PATHS`
-- `src/cli/utils/claude-target.js` — `getClaudePluginDir()`, `installClaudePluginCatalog()`, `ensureClaudeMdGuardBlock()`, `VESPER_REINJECT_COMMAND`
+- `src/cli/utils/claude-target.js` — `installClaudePluginCatalog()`, `installClaudeProjectFiles()`, `ensureClaudeMdGuardBlock()`, `configureClaudeSettings()`, `configureClaudeMarketplaceLocal()`
+- `src/cli/utils/packs.js`, `pack-rules.js`, `third-party.js`, `upstream.js`, `third-party-migration.js` — the packs, the `styles` pointer rule, the third-party registry, the upstream check and the migration of pre-J copies
+- `src/cli/utils/copilot-target.js` / `copilot-render.js` — the Copilot per-project brain and all Copilot path renaming
 - `assets/hooks/pre-commit` — the hand-mirrored `vesper_git_paths` shell list
 
 ## References
 
 - [`docs/architecture.md`](../../../docs/architecture.md) — full narrative, all four facts, with additional citations and the specific incidents (BC-2 architecture-review finding, the trailing-slash bug) that motivated this checklist.
-- `.claude/vesper/context.md` — terse, always-loaded version of the same conventions, auto-injected into every session in this repo.
+- [`README.md`](../../../README.md) — the user-facing 2.0 model: what each host writes, git hooks, `doctor`, migration.
+- The project whitepaper (`.claude/rules/vesper-context.md` on a 2.0 Claude workspace) — terse, always-loaded version of the same conventions.

package/assets/claude/skills/vesper-orchestration/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: vesper-orchestration
+description: Detailed step-by-step orchestration pipelines used by the Vesper super-orchestrator to delegate multi-step work to the specialist team — research & plan, implementation, QA/E2E testing, and re-initialization, including the bug-fix and skill-creation context overrides. Use when running or resuming a Vesper purpose pipeline and you need the per-step delegation prompts, tracking-file naming, output contracts, or the bug-fix overrides that the orchestrator playbook defers to.
+---
+
+# Vesper Orchestration Pipelines
+
+Detailed orchestration workflows for delegating multi-step tasks to the specialist team.
+
+The always-on orchestrator playbook (`.claude/rules/vesper-orchestrator.md`) is the authority for
+**routing** — which purpose a request belongs to, which agent fills which role, and the global
+rules (delegation law, loop limits, concurrency limits, context discipline). This skill carries the
+**step-level detail** the playbook defers to: the per-step delegation prompts, the tracking-file
+contracts, and the bug-fix / skill-creation overrides.
+
+Where the two ever disagree, the playbook wins.
+
+## Pipelines
+
+| Pipeline              | When to use                                                 | Reference                                                         |
+| --------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------- |
+| **Research & Plan**   | Steps 1-3: task fetch, research, architect validation (M: 1-2) | [research-plan-pipeline.md](references/research-plan-pipeline.md) |
+| **Implementation**    | Steps 4-11: validation, coding, review, gate, testing, docs, wrap | [implement-pipeline.md](references/implement-pipeline.md)       |
+| **Multi-Task Dispatch** | Several tasks at once: per-task tier, phases, cross-task check | [multi-task-dispatch.md](references/multi-task-dispatch.md)     |
+| **QA / E2E Testing**  | Post-implementation or standalone test requests             | [qa-e2e-pipeline.md](references/qa-e2e-pipeline.md)               |
+| **Re-initialization** | "Re-vesperize", "refresh workspace setup", `/reinit`        | [reinit-pipeline.md](references/reinit-pipeline.md)               |
+
+## Scope tiers
+
+The playbook's **tier table** (section *2. Implementation* → *Scope tiers*) is the single
+definition of which steps run for a given change: **S** (implement → `vespercli gate` → log),
+**M** (research → plan → implement → one review → gate → conditional docs/wrap → log) and **L**
+(the full step table). These references describe the *steps* and never restate the tiers — when a
+step below says "L only" or "conditional", the tier table is what decides. `vespercli gate` is the
+orchestrator's own CLI call (exit code + headline only), never a delegation.
+
+## Routing
+
+- **Implementation request** → the orchestrator has already chosen the tier. **S**: skip both
+  references' planning steps and use the playbook's S delegation directly. **M**: read
+  `research-plan-pipeline.md` (Steps 1-2), then `implement-pipeline.md` (Steps 5-7, 9-10 conditional,
+  11). **L**: `research-plan-pipeline.md` (Steps 1-3), then `implement-pipeline.md` (Steps 4-11)
+- **Bug fix** → same pipeline; the research-plan and implement references carry the bug-fix overrides
+- **Skill creation** → same pipeline; the same two references carry the skill-creation overrides
+- **Testing request** → read `qa-e2e-pipeline.md` (Mode B for standalone, Mode A for post-implementation — auto-triggered after L only)
+- **Re-initialization** → read `reinit-pipeline.md`
+
+## File Naming Convention
+
+All tracking output uses `YYYYMMDD-[slug]-<type>.md`, where `[slug]` is a short task identifier
+(3-5 words, kebab-case). When the orchestrator delegates with a `Task slug: [slug]` directive, use
+that exact slug — it is what isolates artifacts when several tasks run in parallel.
+
+## Shared Rules
+
+- Delegation prompts pass **file paths** — never embed file content.
+- Subagents write outputs to `.vesper/.tracking/` — never to the plugin or global install location.
+- Every delegation prompt carries `Nesting depth: 1` so delegates can track their own nesting budget.
+- Every delegated subagent ends its final message with the `Status:` / `Summary:` / `Next:` handoff block.
+- Loop limits, concurrency limits, and the delegation law live in the orchestrator playbook —
+  these pipelines reference them and never override them.
+- Specialists are delegated to by their namespaced plugin names (`vesper:<name>`) exactly as the
+  Team Roster in `.claude/rules/vesper-orchestration.md` writes them. The committed maintenance
+  skills are invoked unqualified (`/reinit`, `/compact-knowledge`, `/revalidate-knowledge`,
+  `/revalidate-team`).
+- Memory integration: subagents use the MCP `memory` server's tools per the `mcp-memory` skill.
+
+> **Note on two similarly-named files.** This skill is `vesper-orchestration` — the pipeline
+> detail. `.claude/rules/vesper-orchestration.md` is a *different* artifact: the generated
+> per-project **Team Roster + task-management config**. References to that path throughout these
+> pipelines mean the roster file, not this skill.