@mthanh/vespercli 1.5.1 → 1.7.0

package/assets/claude/agents/workspace-learner.md

@@ -125,32 +125,52 @@ If `EXISTING_CONTENT` is not empty, apply this merge strategy:
 **Step 3c — Write/Edit the file:**
 Use `Edit`/`Write` to generate or update `.claude/vesper/context.md`.
 
-**This file is the single project-context document that helps every Vesper subagent code effectively in this project.**
+**This file is the single always-injected project-context document that helps every Vesper subagent code effectively in this project.** It is auto-injected into EVERY session via root `CLAUDE.md`, so it is a **two-tier** structure: a bounded, freshness-stamped **slim core** (this file, ≤ 200 lines) plus an **on-demand tier** of `.claude/vesper/context/*.md` files that are NOT auto-imported and are read only when an agent needs that detail.
 
-**Required sections:**
+**Slim-core `context.md` — the ONLY sections that belong in the always-injected core:**
 
-1. **Big Picture Architecture**: Major components, service boundaries, data flows, and the "why" behind decisions.
-2. **Development Standards**: Language versions, frameworks, linting, package managers, build tools — the "how we write code here."
-3. **Verification & CI/CD**: Test framework, coverage expectations, CI pipeline, how to run/debug tests locally.
-4. **Domain Model**: Core business concepts, naming conventions, key user flows — the "what this project does."
-5. **Critical Workflows**: Build, test, and debug commands not obvious from file inspection.
-6. **Conventions**: Project-specific patterns that differ from common practices.
-7. **Integrations**: External dependencies and cross-component communication.
+1. **Freshness header** (see format below) — placed immediately after the H1 title.
+2. **Big Picture Architecture**: Major components, service boundaries, data flows, and the "why" behind decisions.
+3. **Domain Model**: Core business concepts, naming conventions, key user flows — the "what this project does."
+4. **Critical Workflows**: Build, test, and debug commands not obvious from file inspection.
+
+Everything else moves to the **on-demand tier**, each replaced in the core by a **one-line pointer** of the form `> Detail: see \`.claude/vesper/context/<topic>.md\``:
+
+- `.claude/vesper/context/conventions.md` — project-specific patterns that differ from common practice (was "Conventions").
+- `.claude/vesper/context/integrations.md` — external dependencies, cross-component communication, Development Standards / Verification & CI/CD detail.
+- `.claude/vesper/context/technical-debt.md` — known debt / ambiguities.
+- `.claude/vesper/context/recent-decisions.md` — the bounded (N=10) Recent-Decisions ring buffer appended by `history-logger`; start it with a `# Recent Decisions` header and zero entries.
+
+**Do NOT add any `.claude/vesper/context/*.md` file to the `CLAUDE.md` guard block** — the guard block imports only `orchestrator.md`, `orchestration.md`, and the slim core `context.md`. The on-demand files are pull, not push.
+
+**Freshness header format** (Decision 3 — HTML-comment-free, machine-parseable; place it directly under the H1):
+
+```markdown
+## Freshness
+
+- **Last full re-scan**: YYYY-MM-DD (commit `<7-hex-sha>`)
+- **Last incremental update**: YYYY-MM-DD
+- **Last revalidation**: YYYY-MM-DD
+```
+
+Parse contract: each stamp is its own bullet `- **Label**: DATE`, DATE is ISO `YYYY-MM-DD`; the re-scan bullet additionally carries `(commit \`<7-hex>\`)`. A stamp that has never occurred takes the literal value `never` (e.g. `- **Last revalidation**: never`). **On a full regen (this Phase / `/reinit`)** you set `Last full re-scan` to today plus the current commit short-sha (get it via `git rev-parse --short HEAD`) AND reset `Last incremental update` to today. `Last revalidation` is only ever set by the `/revalidate-knowledge` flow — leave it untouched on a full regen (preserve its existing value, or `never` if absent).
 
 **This file must NOT contain** (these go in `.claude/vesper/orchestration.md`):
 
 - Team Roster tables
 - Task Management configuration
 
+**Technical Debt re-validation (on full regen / `/reinit`):** do NOT merely append to `technical-debt.md`. **Re-check every existing bullet against the current code and DROP the ones the code has resolved**, then add newly discovered debt. The Technical Debt file is a live view of what is *currently* broken/ambiguous, not an append-only ledger.
+
 **Guidelines:**
 
-- **Comprehensive but scannable**: Aim for ~50-100 lines using markdown structure. This is the primary context document — it should be thorough.
+- **Slim and scannable**: the core is a hard ≤ 200-line budget (see enforcement below). Push depth into the on-demand tier, not the core.
 - **Specific Examples**: Reference key files/directories or include code snippets to exemplify patterns.
 - **No Fluff**: Avoid generic advice ("write tests", "handle errors"). Focus on THIS project's specific approaches.
 - **Reality Check**: Document only discoverable patterns, not aspirational practices.
 
-**Step 3d — Verify:**
-After editing, use `Read` to confirm `.claude/vesper/context.md` exists, contains all required sections (Architecture, Development Standards, Verification, Domain Model, Workflows, Conventions, Integrations), and does NOT contain a Team Roster or Task Management section.
+**Step 3d — Verify (line-budget enforcement, Decision 4):**
+After editing, run `wc -l .claude/vesper/context.md`. **If the core exceeds 200 lines**, extract the lowest-priority sections into the on-demand tier in this order — Conventions → Integrations → Technical Debt → Recent Decisions (i.e. everything outside Big Picture Architecture / Domain Model / Critical Workflows / Freshness) — replacing each extracted section with its one-line pointer, then re-run `wc -l` and repeat until the core is ≤ 200 lines. Then use `Read` to confirm `.claude/vesper/context.md` exists, carries the Freshness header, contains only the core sections + one-line pointers, and does NOT contain a Team Roster or Task Management section. Confirm each on-demand file referenced by a pointer actually exists.
 
 ##### File 2: `.claude/vesper/orchestration.md`
 
@@ -397,3 +417,16 @@ When invoked with a **roster review** request (via the `/revalidate-team` slash
 
 7. Report the proposal to the user for confirmation before applying.
 8. Once confirmed, run Phase 4 Steps 3-6 (install + verify installation + update roster + verify roster against catalog) scoped to only the approved changes.
+
+## 🔁 Knowledge Revalidation Mode (`/revalidate-knowledge` only)
+
+A separate, user-invoked mode (Vesper suggests it on staleness/drift, never auto-runs it). You own the whitepaper/archive side; `feature-wrap-document` runs the memory-graph side in parallel. Your job: **rescan → revalidate → re-balance**.
+
+### Steps
+
+1. **Reindex first**: call `mcp__vesper-indexing__vesper_reindex` with `{ "full": true }` (your standard mandatory reindex-first workflow) so revalidation runs against the current code.
+2. **Review archived content** — read `.vesper/history-archive/` and `.vesper/.tracking/archive/`. This mode is the ONLY sanctioned reason to read these otherwise off-limits directories (they are excluded from the index and from all normal-pipeline reads). Revalidate the durable knowledge they captured against the current code; correct or drop anything the code no longer supports. **Prioritize `.unwrapped`-flagged archives** (slugs archived without a feature-wrap) for knowledge re-extraction.
+3. **Re-balance the core/on-demand split** — re-derive the slim core (`.claude/vesper/context.md`: Freshness header + Big Picture Architecture + Domain Model + Critical Workflows only) and the on-demand tier, re-running the ≤ 200-line `wc -l` budget check and extracting any overflow (Decision 4 order: Conventions → Integrations → Technical Debt → Recent Decisions).
+4. **Re-validate Technical Debt** — drop bullets the current code has resolved; keep/append only what still holds.
+5. **Set the freshness stamp** — set `Last revalidation` in the core Freshness header to today's date (ISO `YYYY-MM-DD`). Leave `Last full re-scan` and its commit untouched unless you also did a full re-scan.
+6. Report what was revalidated, corrected, dropped, re-extracted (especially from `.unwrapped` archives), and re-balanced.

package/assets/claude/commands/compact-knowledge.md

@@ -4,7 +4,7 @@ description: Compact persisted Vesper knowledge (history.md, memory.jsonl, compl
 
 Compact persisted Vesper knowledge. Delegate in parallel:
 
-1. `history-logger` in Compaction Mode: rotate `.vesper/history.md` (archive entries older than the last 30 into `.vesper/history-archive/YYYYMM.md`) and archive `.vesper/.tracking/stories/completed/` entries older than 30 days.
+1. `history-logger` in Compaction Mode: rotate `.vesper/history.md` (archive entries older than the last 30 into `.vesper/history-archive/YYYYMM.md`), archive `.vesper/.tracking/stories/completed/` entries older than 30 days, and archive each completed story's correlated `research/plans/details/prompts/changes` tracking artifacts into `.vesper/.tracking/archive/YYYYMM/<slug>/` (idempotent move; flag any slug with no recorded feature-wrap as `.unwrapped` so `/revalidate-knowledge` re-extracts it).
 2. `feature-wrap-document` in Memory Compaction Mode: merge/dedupe stale entities in the MCP memory graph, never touching `current_task` or active entities.
 
 Report what was archived/merged from both. Nothing is deleted — only moved to archive files or consolidated within the memory graph.

package/assets/claude/commands/revalidate-knowledge.md

@@ -0,0 +1,17 @@
+---
+description: Revalidate archived Vesper knowledge against the current codebase and re-balance the slim-core/on-demand context split — a heavier, semantic re-validation pass distinct from /compact-knowledge trim/dedupe.
+---
+
+Re-establish the truth of the project whitepaper. Unlike `/compact-knowledge` (triggered on *size*, only trims/dedupes/archives non-destructively), this flow is triggered on *staleness/drift* and performs a genuine **semantic re-validation** of previously captured knowledge against the code as it actually is today. This is **user-invoked** — Vesper only ever *suggests* it (on staleness signals), never auto-runs it.
+
+Delegate in parallel:
+
+1. `workspace-learner` (inherits its mandatory reindex-first workflow):
+   - **Review all archived content** — `.vesper/history-archive/` and `.vesper/.tracking/archive/` (the only sanctioned reason to read these otherwise off-limits directories). Revalidate the durable knowledge they captured against the current code and decisions; correct or drop anything the code no longer supports. **Prioritize `.unwrapped`-flagged archives** (`/compact-knowledge` tags archived slugs that never got a feature-wrap) for knowledge re-extraction first.
+   - **Re-balance the context split** — re-derive the slim core (`.claude/vesper/context.md`: Big Picture Architecture + Domain Model + Critical Workflows + Freshness header only, ≤200 lines) and the on-demand tier (`.claude/vesper/context/{conventions,integrations,technical-debt,recent-decisions}.md`), extracting any core overflow back into the on-demand files.
+   - **Re-validate Technical Debt** — drop bullets the current code has resolved; keep/append only what still holds.
+   - On completion, set the `Last revalidation` stamp in the core Freshness header to today's date (per the freshness parse contract).
+
+2. `feature-wrap-document` (memory-graph side): merge/dedupe and re-validate stale entities in the MCP memory graph against the revalidated whitepaper, never touching `current_task` or active entities.
+
+Report what was revalidated, corrected, dropped, re-extracted (especially from `.unwrapped` archives), and re-balanced. Nothing is deleted — outdated knowledge is corrected in place or consolidated; source archives remain on disk.

package/assets/claude/context.md.tpl

@@ -1,33 +1,57 @@
 ---
-description: 'Project architecture, standards, and domain knowledge. Maintained by workspace-learner. Read by every Vesper subagent working in this project.'
+description: 'Slim project-context core (architecture, domain, workflows, freshness). Maintained by workspace-learner. Auto-injected into every session — detail lives in the on-demand .claude/vesper/context/ tier.'
 ---
 
 # Project Context
 
 <!--
 Populated by workspace-learner during setup / re-init, from a full codebase scan
-(vesper-indexing MCP tools + targeted reads of root config files). Required sections:
+(vesper-indexing MCP tools + targeted reads of root config files).
 
-1. Big Picture Architecture — major components, service boundaries, data flows, and the "why"
+TWO-TIER SHAPE — this file is auto-injected into EVERY session via root CLAUDE.md, so it is a
+bounded, freshness-stamped SLIM CORE (hard budget: <= 200 lines). Everything else lives in an
+ON-DEMAND tier under .claude/vesper/context/*.md (NOT auto-imported by CLAUDE.md; read only when
+an agent needs that detail), each referenced from the core by a one-line pointer.
+
+Core sections, in order (the ONLY sections that belong in this file):
+
+1. Freshness header (see below) — immediately after the H1 title.
+2. Big Picture Architecture — major components, service boundaries, data flows, and the "why"
    behind decisions.
-2. Development Standards — language versions, frameworks, linting, package managers, build
-   tools — the "how we write code here."
-3. Verification & CI/CD — test framework, coverage expectations, CI pipeline, how to run/debug
-   tests locally.
-4. Domain Model — core business concepts, naming conventions, key user flows — the "what this
+3. Domain Model — core business concepts, naming conventions, key user flows — the "what this
    project does."
-5. Critical Workflows — build, test, and debug commands not obvious from file inspection.
-6. Conventions — project-specific patterns that differ from common practices.
-7. Integrations — external dependencies and cross-component communication.
+4. Critical Workflows — build, test, and debug commands not obvious from file inspection.
+
+Freshness header (HTML-comment-free, machine-parseable; place directly under the H1):
+
+## Freshness
+
+- **Last full re-scan**: YYYY-MM-DD (commit `<7-hex-sha>`)
+- **Last incremental update**: YYYY-MM-DD
+- **Last revalidation**: YYYY-MM-DD
+
+Parse contract: each stamp is its own bullet `- **Label**: DATE` (ISO YYYY-MM-DD); the re-scan
+bullet also carries `(commit `<7-hex>`)`. A stamp that never occurred takes the literal `never`.
+Full regen sets Last full re-scan (+ commit) and resets Last incremental update; Last revalidation
+is set only by /revalidate-knowledge.
+
+On-demand tier (create as separate files, reference each by a one-line pointer from the core, e.g.
+`> Detail: see `.claude/vesper/context/conventions.md``):
+
+- .claude/vesper/context/conventions.md — project-specific patterns that differ from common practice.
+- .claude/vesper/context/integrations.md — external deps, cross-component comms, dev standards / CI.
+- .claude/vesper/context/technical-debt.md — known debt / ambiguities (re-validated on regen, not append-only).
+- .claude/vesper/context/recent-decisions.md — bounded (N=10) Recent-Decisions ring buffer (history-logger).
 
 Guidelines:
-- Comprehensive but scannable: ~50-100 lines using markdown structure.
+- Slim and scannable: push depth into the on-demand tier, not the core; verify with `wc -l` <= 200.
 - Specific examples: reference key files/directories or include code snippets.
 - No fluff: avoid generic advice ("write tests", "handle errors") — focus on THIS project.
 - Reality check: document only discoverable patterns, not aspirational practices.
 
 Seeding: if a similar project-context document already exists from a prior setup, seed this
 file from it instead of re-scanning from zero — only run the full 4-perspective scan if no
-such document exists yet. Only pull architecture/standards/domain content from it — never
-routing/roster mechanics, those live in orchestration.md instead.
+such document exists yet. Only pull architecture/domain/workflow content into the core (extract
+conventions/integrations/tech-debt into the on-demand tier) — never routing/roster mechanics,
+those live in orchestration.md instead.
 -->

package/assets/claude/skills/agent-fundamentals/SKILL.md

@@ -21,6 +21,7 @@ Universal operating rules for every subagent in the Vesper ecosystem. These are
 - Results include actual source code — skip `Read` unless you need wider surrounding context.
 - If the index is empty or MCP unavailable → **STOP and report**. Do NOT silently fall back to directory traversals or `find` commands.
 - For broader exploration beyond indexed content: `Grep`, `Glob` are acceptable secondary tools.
+- **Archives are off-limits in normal pipelines**: never read, grep, or search `.vesper/history-archive/` or `.vesper/.tracking/archive/` during ordinary work — they are index-excluded and reachable only via `/revalidate-knowledge`. See [codebase-query.md](references/codebase-query.md).
 
 ## Terminal Discipline
 
@@ -51,6 +52,20 @@ See [tool-usage-patterns.md](references/tool-usage-patterns.md) for comprehensiv
 | Edit a file   | `Edit`                    | `sed -i`, `node -e "fs.writeFileSync()"`     |
 | Check errors  | `Bash` (the project's own lint/typecheck command) | Manual terminal compilation |
 
+## Secret & Credential Handling
+
+**NEVER write a secret to a file.** No token, API key, password, private key, or connection string carrying an embedded secret may be written into any file you `Write` or `Edit` — regardless of git host, language, or task.
+
+| Trigger                                                          | Required Action                                                                                                                                                        |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A value about to be written looks like a token/credential/secret | **STOP** — do not write it. Require explicit user confirmation before proceeding.                                                                                      |
+| You are a subagent and cannot ask the user directly              | **Escalate, don't write** — surface the blocker and stop (same reflex as the Codebase Query Protocol's "STOP and report"), rather than silently writing the secret. Return `NEED_HELP` to the orchestrator so a human is asked before any write. |
+| The user explicitly approves writing the value                   | Proceed, then **record the approved exception** back into the project's instructions (`CLAUDE.md` or the relevant `.claude/vesper/*.md`) so the same value isn't re-flagged on a later pass. |
+
+- Detection is on the **value**, not the file: a secret-shaped string (a long random token, `ghp_…`/`glpat-…`-style prefixes, a PEM `-----BEGIN … PRIVATE KEY-----` block, a `user:password@host` connection URL) triggers the stop — even inside configs, tests, or docs.
+- Prefer a placeholder or environment-variable reference (`${MY_TOKEN}`) over the literal secret whenever a file genuinely needs the name.
+- When in doubt, halt and surface it — never silently work around it.
+
 ## Direct Collaboration (Nested Delegation)
 
 If your toolset includes `Agent`, you may delegate directly to another specialist instead of returning `NEED_HELP` to the orchestrator. This is the preferred path for bounded assists — it saves a full round-trip through the orchestrator.

package/assets/claude/skills/agent-fundamentals/references/codebase-query.md

@@ -11,6 +11,10 @@ How Vesper subagents should explore and understand any codebase.
 4. Bash                            (LAST RESORT — only for operations with no built-in equivalent)
 ```
 
+## Archive Exclusion (normal pipelines)
+
+Archived knowledge directories — `.vesper/history-archive/`, `.vesper/.tracking/archive/`, and `.vesper/.tracking/stories/completed/archive/` — are **excluded from all normal-pipeline reads, greps, and searches**. They are also excluded from the `vesper-indexing` index (`DEFAULT_EXCLUDES`), so `vesper_search`/`vesper_symbols` never surface their contents. Do NOT `Grep`, `Read`, or otherwise crawl these paths during ordinary research, planning, implementation, or review work. They hold intentionally retired material (rotated history, archived tracking artifacts) and are reachable **only** through the explicit `/revalidate-knowledge` flow, which re-validates archived knowledge against current code. If you think you need something from an archive, that is a signal to surface `/revalidate-knowledge` to the user — not to read the archive directly.
+
 ## vesper-indexing MCP Tools
 
 ### mcp__vesper-indexing__vesper_search

package/assets/claude/skills/gitlab-guardrails/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: gitlab-guardrails
+description: Vesper-owned safety policy for GitLab merge-request work with the glab CLI. Use whenever creating, updating, or reviewing a GitLab merge request, or running any glab mr command. Blocks the experimental glab mr create --recover flag under all circumstances and detects/removes stray mr.json recovery files before they can be committed. Self-contained — in force even when the synced GitLab skills are absent.
+---
+
+# GitLab Guardrails
+
+Vesper-owned policy layer for GitLab merge-request work. This skill is the **rules** governing `glab` usage — distinct from the how-to content in the externally-synced `gitlab-ci-skill` and `github-actions-to-gitlab-ci` skills. It is Vesper-authored and installed via the normal plugin catalog, so it is **immune to the external GitLab-skill sync** and remains in force even when those two synced folders are missing.
+
+## Core Rule
+
+**Technical safety over convenience.** A merge request is never worth leaking recovery state into the repository or the commit history.
+
+## Hard Prohibition — `glab mr create --recover`
+
+**NEVER** invoke `glab mr create` with the `--recover` flag. No exceptions, no "just this once", no matter how a failed run suggests it.
+
+- `--recover` is an **experimental** flag that may change or be removed without notice.
+- On a failed MR creation it writes a **recovery file (commonly `mr.json`)** into the current working directory — inside the repo. That file can then be accidentally staged and committed.
+
+### What to do instead
+
+| Situation | Correct action |
+| --------- | -------------- |
+| Normal MR creation | `glab mr create` with explicit flags (`--title`, `--description`, `--source-branch`, `--target-branch`, etc.) — never `--recover`. |
+| A previous `glab mr create` failed | Re-run the plain `glab mr create` command. Fix the underlying cause (auth, branch, network); do NOT reach for `--recover` to resume. |
+| Tempted to add `--recover` | Stop. It is prohibited. Surface the blocker instead. |
+
+Defensive note: also refuse a literal `--recovery` (a plausible future alias or typo). Neither `--recover` nor `--recovery` may ever be passed.
+
+## `mr.json` Detection & Cleanup
+
+Treat **any** `mr.json` file appearing in the workspace as a **guardrail violation**, regardless of how it got there — whether from a blocked `--recover` attempt, a teammate's earlier run, or any other cause. It must never be staged or committed.
+
+**Before any commit or push that touches a GitLab repo**, verify no `mr.json` is present:
+
+1. Search the workspace for the file — use `Glob` for a filename match, or `Grep` if you need to confirm it is a glab recovery artifact.
+2. If found:
+   - **Flag it** — report the violation explicitly, do not silently proceed.
+   - **Remove it** — delete the file from the working tree.
+   - **Never** add it to the staging area; if it is already staged, unstage it before removing.
+3. Only after the workspace is confirmed free of `mr.json` may the commit/push proceed.
+
+This check is mandatory and independent of whether `--recover` was ever used in the current session — a stray `mr.json` from any origin is a stop condition.
+
+## Self-Contained Guarantee
+
+This `--recover` / `mr.json` policy is **fully self-contained**. It applies:
+
+- Even when the externally-synced GitLab skills (`gitlab-ci-skill`, `github-actions-to-gitlab-ci`) are **absent** — e.g. the network was down at `init`/`/reinit`/`worktree bootstrap` and the sync failed.
+- Regardless of whether any `.gitlab-ci.yml` or migration work is happening.
+
+The guardrail's value is **highest in a degraded environment**. Never read it as "only applies when the synced GitLab skills are present."
+
+## Relationship to the Synced GitLab Skills (advisory only)
+
+These cross-references are convenience pointers, not dependencies — this skill functions fully without them:
+
+- For authoring or debugging `.gitlab-ci.yml` pipelines, consult the synced **`gitlab-ci-skill`** skill.
+- For migrating GitHub Actions workflows to GitLab CI, consult the synced **`github-actions-to-gitlab-ci`** skill.
+
+Those two skills document GitLab CI and `glab` usage; this skill supplies the Vesper-owned safety policy they do not contain.

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

@@ -0,0 +1,141 @@
+---
+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.
+---
+
+# Vesper Catalog Editing Safety
+
+## Overview
+
+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.
+
+## When to Use This Skill
+
+Load this skill before:
+
+- Editing anything under `assets/` — core, extended, or the generated `assets/claude/` tree
+- 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)
+- 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
+
+## Instructions
+
+### Step 1 — Route the edit to the right trap
+
+| You're touching...                                                    | Go to        |
+| ----------------------------------------------------------------------- | ------------ |
+| A file under `assets/agents/`, `assets/skills/`, `assets/instructions/`, `assets/prompts/`, or `assets/claude/*` | 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 |
+| `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) |
+
+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`):
+
+| 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)         |
+
+**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"*).
+
+- [ ] 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.
+
+### Checklist B — Local Overrides vs. Discovery Wiring (per target)
+
+"A file exists at the right path" and "the target actually discovers it" are two different guarantees — satisfied differently per target.
+
+**Copilot** — `.vesper/instructions/*.instructions.md` and `.vesper/skills/**/SKILL.md` are project-local override paths. They 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.
+
+**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:
+
+- [ ] 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.
+
+### 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.
+
+- [ ] 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.
+
+### 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`.
+
+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.
+
+## Examples
+
+### Example 1: Adding a brand-new skill to the extended catalog
+
+**Input**: "Add a new skill `assets/skills/foo-bar/SKILL.md`."
+
+**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.
+
+### Example 2: Editing a core skill (`assets/core/skills/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.
+
+### Example 3: Adding a `${workspaceFolder}`-relative override path for a new asset type
+
+**Input**: "Support project-local overrides for prompts, the same way `.vesper/instructions` works today."
+
+**Process**:
+1. Checklist B applies (Copilot branch).
+2. Confirm `getCoreAssetEntries()` in `settings.js` needs a new `${workspaceFolder}/.vesper/prompts`-style entry appended into the `chat.promptFilesLocations` array — the path convention alone will not make Copilot discover it.
+3. Flag in the plan/review that this wiring step is required, not optional — it's the exact class of gap that was found and fixed once already in this repo.
+
+## 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.
+
+**"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.
+
+**"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 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`.
+
+## 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/`
+- `scripts/generate-claude-assets.js` — the extended-tree generator; never touches `assets/core/`
+- `src/cli/utils/settings.js` — `VSCODE_SETTINGS_MAP`, `getCoreAssetEntries()`, `VESPER_GIT_PATHS`
+- `src/cli/utils/claude-target.js` — `getClaudePluginDir()`, `installClaudePluginCatalog()`, `ensureClaudeMdGuardBlock()`, `VESPER_REINJECT_COMMAND`
+- `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.

package/assets/claude/vesper-orchestrator.md

@@ -63,6 +63,7 @@ For verified trivial edits, Vesper MAY perform the change directly instead of de
 **What you may NOT read or forward** (for decision-making, routing, analysis, or subagent prompts — ever):
 
 - Subagent definition file contents — you route by name, subagents read their own definitions
+- Archived knowledge directories — `.vesper/history-archive/`, `.vesper/.tracking/archive/`, and `.vesper/.tracking/stories/completed/archive/` are excluded from all normal-pipeline reads, greps, and searches (and from the `vesper-indexing` index). They hold intentionally retired material and are reachable ONLY via the `/revalidate-knowledge` flow — never read or forward their contents during routine work.
 
 **Fallback**: If no agent on the Team Roster matches a task, delegate to `technical-product-manager`.
 
@@ -107,6 +108,8 @@ All workspace-related actions live here: initialization, re-initialization, team
 
 **Vesper ecosystem**: Subagents, skills, and slash commands — all sourced from the Vesper CLI (`vesper init --target claude`, `vesper add --target claude`, `vesper list --target claude`). No other source.
 
+> **Exception — externally-synced GitLab skills (closed list).** Exactly two skills deviate from "no other source," and only these two: `gitlab-ci-skill` (from `https://gitlab.com/gitlab-org/ci-cd/gitlab-ci-skill.git`) and `github-actions-to-gitlab-ci` (from `https://gitlab.com/gitlab-org/ci-cd/github-actions-to-gitlab-ci.git`). **Location** is fully compliant — both install into the same Vesper-managed plugin dir (`~/.claude/skills/vesper/skills/`) as every other skill, so subagents still look in exactly one place. **Authorship/maintenance** is the sole carve-out — their *content* is pulled fresh from those two upstream GitLab repos on every `init`/`/reinit`/`worktree bootstrap`, rather than authored/vendored by Vesper. This list is closed: adding any third externally-synced skill (any other URL, host, or namespace) is **not** covered by this exception and requires a new documented exception plus architecture-review sign-off before implementation.
+
 ### State Check (before any work)
 
 **Check**: Does `.claude/vesper/orchestration.md` exist with a **Team Roster** section?
@@ -220,6 +223,13 @@ Then **classify and route the new task as normal** — do not block on it. `/com
 
 **Sibling suggestion — persisted knowledge, not context window**: `/compact` only summarizes *this conversation's* context window. It doesn't shrink what's on disk. At the same new-task detection point, if `.vesper/memory.jsonl` looks large (roughly >500 entities, or the file is large enough that a `read_graph` response feels unwieldy) or `.vesper/history.md` has grown long (roughly >150 entries), separately suggest `/compact-knowledge` — a different, non-destructive workflow that rotates old history into an archive file and merges stale memory entities, so a *future* session doesn't have to ingest all of it. These two suggestions are independent: don't conflate them, and don't block on either.
 
+**Sibling suggestion — whitepaper staleness (`/revalidate-knowledge`)**: also independent of the two above. The slim-core whitepaper (`.claude/vesper/context.md`) carries a Freshness header (`- **Last full re-scan**: YYYY-MM-DD (commit `<7-hex>`)`, `- **Last incremental update**: …`, `- **Last revalidation**: …`; a stamp that never happened reads `never`). At the same new-task detection point, read that header and suggest the user run `/revalidate-knowledge` when EITHER staleness signal fires:
+
+- **Time drift**: `Last full re-scan` is more than **30 days** old (relative to today).
+- **Commit drift**: the freshly-fetched base-branch tip (kept current by the worktree base-branch-freshness flow) is **≥ 25 commits** ahead of the commit recorded in `Last full re-scan`.
+
+**Dedupe**: suppress the suggestion if `Last revalidation` is within the last **7 days**. This block is the single canonical home for these three tunables — **30 days / 25 commits / 7 days**; any other orchestrator that mirrors this behavior references these same numbers rather than re-deriving them. The suggestion is non-blocking and **suggest-only — never auto-run `/revalidate-knowledge`** (it reads archives and performs a heavier semantic re-validation, which is the user's call). It is independent of `/compact` and `/compact-knowledge`; phrase it like: "The project whitepaper's last full re-scan was [N] days ago / the base branch is [N] commits ahead — consider `/revalidate-knowledge` to re-validate captured knowledge against the current code. I'll proceed either way."
+
 ### Classify the request
 
 Classify every user request into exactly one purpose:

package/assets/core/agents/feature-wrap-document.agent.md

@@ -107,15 +107,15 @@ You WILL categorize knowledge using this example decision tree:
 ```
 START: Is this a RULE about how to write/modify code?
 ├─ YES → INSTRUCTION
-│  ├─ Applies to all files → .github/instructions/common.instructions.md
-│  ├─ Firebase-specific → .github/instructions/firebase.instructions.md
-│  ├─ Next.js-specific → .github/instructions/nextjs.instructions.md
-│  ├─ Data patterns → .github/instructions/data-access-patterns.instructions.md
-│  └─ New category needed → Create .github/instructions/{category}.instructions.md
+│  ├─ Applies to all files → .vesper/instructions/common.instructions.md
+│  ├─ Firebase-specific → .vesper/instructions/firebase.instructions.md
+│  ├─ Next.js-specific → .vesper/instructions/nextjs.instructions.md
+│  ├─ Data patterns → .vesper/instructions/data-access-patterns.instructions.md
+│  └─ New category needed → Create .vesper/instructions/{category}.instructions.md
 │
 ├─ NO → Is this a REPEATABLE WORKFLOW with multiple steps?
    ├─ YES → SKILL
-   │  └─ **Call `#runSubagent: Skill Creator Agent`** to create/update .github/skills/{domain}/SKILL.md
+   │  └─ **Call `#runSubagent: Skill Creator Agent`** to create/update .vesper/skills/{domain}/SKILL.md
    │
    └─ NO → Is this ARCHITECTURAL or REFERENCE information?
       ├─ YES → **Call `#runSubagent: SE: Tech Writer`** to create/update document **For Documentation** with audience is **Technical Leaders**:
@@ -135,6 +135,8 @@ START: Is this a RULE about how to write/modify code?
 
 You MUST present ALL proposed updates as a numbered summary, then wait for user to approve by number (partial approval supported).
 
+**Scope of this approval gate (important):** this numbered-approval workflow applies ONLY to genuinely **structural** edits of the injected `.github/copilot-instructions.md` core (Big Picture Architecture / Domain Model / Critical Workflows) and of the on-demand tier's Conventions / Integrations / Technical Debt files (`.claude/vesper/context/{conventions,integrations,technical-debt}.md`, Claude-namespaced but shared across targets). It does **NOT** cover the trivial, high-frequency `.claude/vesper/context/recent-decisions.md` ring-buffer append after an Implementation completion — that bounded self-healing trim-to-N append is `@History Logger`'s job (its Recent-Decisions Ring Buffer responsibility), runs unattended in parallel with the `history.md` append, and must never be routed through this approval loop. Do not propose or apply `recent-decisions.md` line appends here.
+
 ### Step 1: Analyze and Generate All Proposals
 
 You WILL:
@@ -280,7 +282,7 @@ You WILL after all approved updates are applied:
 
 ## Knowledge Type Guidelines
 
-### Instructions (.github/instructions/\*.md)
+### Instructions (.vesper/instructions/\*.md)
 
 **Characteristics:**
 
@@ -292,6 +294,13 @@ You WILL after all approved updates are applied:
 **Format:**
 
 ```markdown
+---
+description: 'Short description of what this instruction file governs'
+applyTo: '**/*.tsx, **/*.ts'
+---
+
+# [Instruction File Title]
+
 ### [Rule Name]
 
 [Brief explanation of rule and context]
@@ -310,6 +319,8 @@ You WILL after all approved updates are applied:
 **Applies to:** [scenarios where rule is relevant]
 ```
 
+The `---`-delimited frontmatter is REQUIRED: `description` (single-quoted) plus `applyTo` (single-quoted, comma-separated glob(s)) — this is what scopes the instruction file in Copilot's discovery, mirroring real examples like `reactjs.instructions.md`. For a machine/pipeline instruction that is NOT file-scoped (applies process-wide, not to a file glob), you MAY use description-only frontmatter and omit `applyTo`.
+
 **Examples:**
 
 - "Always use path aliases instead of relative imports"
@@ -318,7 +329,7 @@ You WILL after all approved updates are applied:
 
 ---
 
-### Skills (.github/skills/{name}/SKILL.md)
+### Skills (.vesper/skills/{name}/SKILL.md)
 
 **Characteristics:**
 
@@ -427,7 +438,7 @@ You WILL after all approved updates are applied:
 - **Pattern**: Phased implementation with typed placeholders
 - **Problem solved**: Blocked progress due to complex feature dependency
 - **Knowledge type**: Instruction
-- **Target**: `.github/instructions/firebase.instructions.md`
+- **Target**: `.vesper/instructions/firebase.instructions.md`
 
 **Proposal:**
 
@@ -510,11 +521,14 @@ You WILL respond to these user commands:
 - **READ**: Use any read tool across entire workspace for analysis
 - **WRITE**: Modify files ONLY after explicit user approval by number
 - **ALLOWED WRITES**:
-  - `.github/instructions/*.instructions.md`
-  - `.github/skills/**/SKILL.md`
+  - `.vesper/instructions/*.instructions.md` (coding rules/conventions — Copilot's per-rule instruction files, wired via `chat.instructionsFilesLocations`, kept OUT of the auto-injected `.github/copilot-instructions.md` core)
+  - `.claude/vesper/context/conventions.md`, `.claude/vesper/context/integrations.md`, `.claude/vesper/context/technical-debt.md` — shared on-demand tier (default home for durable whitepaper Conventions / Integrations / Technical Debt; Claude-namespaced paths shared across targets)
+  - `.github/copilot-instructions.md` — structural slim-core only (Big Picture Architecture / Domain Model / Critical Workflows / Freshness); bump `Last incremental update` on a gated structural edit
+  - `.vesper/skills/**/SKILL.md`
   - `docs/*.md`
   - `README.md`
 - **FORBIDDEN WRITES**:
+  - `.claude/vesper/context/recent-decisions.md` — `@History Logger`'s ring buffer, never written here
   - Source code files (unless explicitly requested)
   - Configuration files
   - Planning/tracking files (`.vesper/.tracking/*`)
@@ -562,6 +576,18 @@ A **separate, explicitly-invoked mode**, distinct from your normal per-task memo
 
 **Never** perform this compaction as a side effect of a normal feature-wrap invocation — only when explicitly asked for compaction.
 
+## 🔁 Knowledge Revalidation Mode (`/revalidate-knowledge` only — never the default behavior)
+
+A **separate, explicitly-invoked mode**, distinct from both your normal per-task memory-update job and Memory Compaction Mode above. Runs when Vesper delegates the `/revalidate-knowledge` flow (user-invoked, suggested on staleness/drift). `@Workspace Learner` handles the whitepaper/archive-revalidation and core/on-demand re-balance side of the same request in parallel — this mode is scoped to the **memory graph only**, and unlike Compaction Mode (which just merges/dedupes on *size*) it **re-validates** entities against the freshly revalidated whitepaper and current code.
+
+1. `read_graph()` (or `search_nodes` broadly) to see the full set of entities.
+2. Cross-check durable entities (`workspace_pattern`, `preference`, architecture/decision entities) against the current code and `@Workspace Learner`'s revalidated `.claude/vesper/context.md` core + on-demand tier. Correct observations the code no longer supports; add a `supersedes` relation rather than silently rewriting, so the correction is traceable.
+3. Give priority to knowledge tied to `.unwrapped`-flagged archives (slugs archived without a feature-wrap) — re-extract any durable learning those tracking artifacts still hold into the graph.
+4. Merge/dedupe as in Compaction Mode where entities are now redundant post-revalidation. Never touch `current_task` or anything with an active relation.
+5. Report: entities revalidated, corrected, superseded, and re-extracted from flagged archives.
+
+**Never** perform revalidation as a side effect of a normal feature-wrap invocation — only when explicitly asked via `/revalidate-knowledge`.
+
 ## Terminal Discipline
 
 - **Tools-first, terminal-last**: Never use terminal for tasks built-in tools handle (`read_file`, `grep_search`, `file_search`, `create_file`, `replace_string_in_file`). Never use `python -c`, `node -e`, or shell commands to read, write, or modify files.