@mthanh/vespercli 1.6.0 → 1.7.0

package/README.md

@@ -142,11 +142,13 @@ Claude Code has no equivalent of VS Code's `chat.agentFilesLocations` setting, s
 - `CLAUDE.md` — a small guarded `@import` block pointing at the three files below (never touches the rest of your `CLAUDE.md`)
 - `.claude/vesper/orchestrator.md` — the orchestration playbook (routing rules, delegation), refreshed on every `init`/`update`
 - `.claude/vesper/orchestration.md` — this project's Team Roster + Task Management config
-- `.claude/vesper/context.md` — this project's architecture/stack/conventions
+- `.claude/vesper/context.md` — this project's architecture/stack/conventions, as a slim, freshness-stamped core (≤200 lines, auto-injected into every session); a fuller **on-demand** tier under `.claude/vesper/context/` (conventions, integrations, technical debt, a bounded Recent-Decisions ring buffer) fills in as the Vesper agent learns the workspace, and is read only when an agent needs that detail
 - `.mcp.json` and `.claude/settings.json` — the `vesper-indexing` MCP server + its tool permissions
 
 No editor dependency — these files are read by the Claude Code engine itself, so the same install works from the terminal CLI, VS Code extension, JetBrains, or the desktop app. During install you're asked once whether to prefix catalog names with `vesper-` to avoid collisions with other Claude Code kits.
 
+Two slash commands manage that on-demand knowledge over time: `/compact-knowledge` (size-triggered — archives old history/tracking artifacts and trims the memory graph, non-destructively) and `/revalidate-knowledge` (staleness-triggered — re-scans the codebase, re-validates archived and core knowledge against it, and rebalances the slim-core/on-demand split); Vesper only ever suggests these, never auto-runs them.
+
 A single project can have both targets installed at once — `.vesper/` (code index, story tracking, `history.md`) is shared and cross-client by design, so a story researched under Copilot can be implemented under Claude Code, or vice versa.
 
 </details>
@@ -256,6 +258,21 @@ vespercli reset --full            # Remove EVERYTHING including vesper.agent.md
 
 </details>
 
+<details>
+<summary><b><code>vespercli worktree</code></b> — bootstrap a worktree's local-only artifacts</summary>
+
+Bootstrap a git worktree (or the current workspace) with Vesper's **local-only** artifacts — files that are intentionally gitignored (`.mcp.json`, the code index `.vesper/index.db`, the gitignore guard block, the managed git hooks and `.gitattributes` merge strategy) and therefore don't come along with a plain `git worktree add`. Idempotent and safe to re-run; it already runs automatically via the Claude `SessionStart` hook, the VS Code folder-open task, and a `post-checkout` git hook, so you rarely need to invoke it by hand. No-op on a workspace that was never vesperized.
+
+```bash
+vespercli worktree bootstrap            # Regenerate local-only files in this worktree
+vespercli worktree bootstrap --quiet    # Suppress non-error output (used by the hooks above)
+vespercli worktree bootstrap --path /my/project
+```
+
+Bootstrap also refreshes the base branch's remote-tracking ref before rebuilding anything else: it resolves the base branch from `origin/HEAD` (e.g. `origin/master`) and runs a bounded (15s) `git fetch` — never `git pull`, so your checked-out branch and working tree are never touched. This keeps anything orienting against "what's on the base branch" (like a fresh worktree) looking at a recent `origin/<base>` instead of a possibly stale local checkout. It never fails the bootstrap: offline, no configured remote, or an unreachable/auth-expired remote all just log a warning (printed even under `--quiet`) and continue with the existing local refs.
+
+</details>
+
 <details>
 <summary><b><code>vespercli mcp</code></b> — manage MCP servers</summary>
 

package/assets/CATALOG.md

@@ -409,6 +409,12 @@ Core skills provide fundamental capabilities and are installed by default alongs
 - Description: Build accessible UIs with shadcn/ui (Radix UI) + Tailwind CSS — components, theming, dark mode, responsive layouts.
 - Pick when: Project uses Tailwind + shadcn/ui; need accessible component patterns (dialogs, forms, tables); want consistent theming and responsive styling.
 
+### vesper-catalog-editing-safety
+
+- Path: `skills/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`).
+- Pick when: Editing any catalog asset (agent/skill/prompt/instruction), the Claude-asset generator, or Copilot/Claude settings-injection code in this repo; need to know the dual asset tree boundary, discovery wiring, or the git-hygiene dual list before making the change.
+
 ### web-design-guidelines
 
 - Path: `skills/web-design-guidelines/`
@@ -555,9 +561,15 @@ Core instructions are part of Vesper's orchestration workflows.
 - Description: Generate a comprehensive repository summary and narrative story from commit history.
 - Pick when: Want a "what happened" narrative for onboarding or review; need a summary of evolution and major decisions; preparing documentation or a project retrospective.
 
+### revalidate-knowledge
+
+- Path: `core/prompts/revalidate-knowledge.prompt.md`
+- 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`'s trim/dedupe.
+- Pick when: The project context feels stale or drifted from the code (staleness signal, not size); want archived knowledge (prioritizing `.unwrapped` entries) re-checked and re-extracted; need the slim core and on-demand context tiers rebalanced. User-invoked only — Vesper suggests it, never auto-runs it.
+
 ---
 
 ## Catalog Metadata
 
 - **Version**: 1.4.0
-- **Last Updated**: 2026-02-27
+- **Last Updated**: 2026-07-21

package/assets/claude/agents/feature-wrap-document.md

@@ -108,7 +108,7 @@ START: Is this a RULE about how to write/modify code in THIS project?
 ├─ YES → Is the rule scoped to a specific set of files (a path/glob)?
 │  │  TIE-BREAKER: a glob that effectively matches all files (e.g. `**/*`, `**`,
 │  │  `*`) is NOT file-scoped — it is semantically project-wide. Treat it as the
-│  │  NO branch (→ context.md / rules), never as a Skill with an always-firing
+│  │  NO branch (→ context tier / rules), never as a Skill with an always-firing
 │  │  "matching: **/*" description.
 │  ├─ YES (a real, bounded glob) → INSTRUCTION (file-glob-scoped) → SKILL
 │  │  └─ delegate to `skill-creator` to create/update `.claude/skills/{domain}/SKILL.md`,
@@ -116,9 +116,13 @@ START: Is this a RULE about how to write/modify code in THIS project?
 │  │     "Use when working with files matching: <glob>."
 │  │     (mirrors the build-time convertInstructionToSkill() convention — not a new format)
 │  └─ NO (project-wide / not file-scoped) → PROJECT CONTEXT UPDATE
-│     ├─ Concise, always-applicable → update `.claude/vesper/context.md`
-│     │  (Development Standards / Conventions section)
-│     └─ Long/verbose but always-on (too big to inline cleanly in context.md) →
+│     (on-demand tier by default — keep the auto-injected slim core small)
+│     ├─ Coding rule / convention → `.claude/vesper/context/conventions.md`
+│     ├─ External dep / integration / dev-standard / CI detail → `.claude/vesper/context/integrations.md`
+│     ├─ Known debt / ambiguity → `.claude/vesper/context/technical-debt.md`
+│     ├─ Structural only (Big Picture Architecture / Domain Model / Critical Workflows) →
+│     │  `.claude/vesper/context.md` core (then bump its `Last incremental update` stamp)
+│     └─ Long/verbose but always-on (too big to inline cleanly in a context file) →
 │        create a standalone `.claude/rules/{name}.md` and append
 │        `@.claude/rules/{name}.md` to CLAUDE.md OUTSIDE the vesper:start/vesper:end
 │        guard markers (survives update/reinit — see ensureClaudeMdGuardBlock).
@@ -127,8 +131,8 @@ START: Is this a RULE about how to write/modify code in THIS project?
 │        if absent, so re-running a retrospective for an updated same-named rule
 │        overwrites `.claude/rules/{name}.md` without appending a duplicate import.
 │        HEURISTIC (B-vs-C): more than ~20-30 lines, or it carries its own
-│        examples / sub-structure → standalone rules file; otherwise inline in
-│        context.md. Misfiling here is low-stakes and self-correcting.
+│        examples / sub-structure → standalone rules file; otherwise route to the
+│        on-demand tier / core above. Misfiling here is low-stakes and self-correcting.
 │
 ├─ NO → Is this a REPEATABLE WORKFLOW with multiple steps?
    ├─ YES → SKILL
@@ -153,6 +157,8 @@ START: Is this a RULE about how to write/modify code in THIS project?
 
 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** `.claude/vesper/context.md` edits — the slim core's Big Picture Architecture / Domain Model / Critical Workflows, and the on-demand tier's Conventions / Integrations / Technical Debt files. 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:
@@ -298,7 +304,9 @@ You WILL after all approved updates are applied:
 
 ## Knowledge Type Guidelines
 
-### Project Context (`.claude/vesper/context.md`)
+### Project Context (two-tier: slim core + on-demand tier)
+
+**Target routing (avoid slim-core creep):** durable prose lands in the on-demand tier, NOT the auto-injected core. A coding rule/convention → `.claude/vesper/context/conventions.md`; an external dep / integration / dev-standard / CI detail → `.claude/vesper/context/integrations.md`; a known debt/ambiguity → `.claude/vesper/context/technical-debt.md`. Only genuinely **structural** content (Big Picture Architecture / Domain Model / Critical Workflows) belongs in the injected `.claude/vesper/context.md` core — and any such gated structural edit also bumps the core's `Last incremental update` freshness stamp. `recent-decisions.md` is `history-logger`'s ring buffer, never written here.
 
 **Characteristics:**
 
@@ -454,8 +462,8 @@ description: [What it does + when to use it]
 
 - **Pattern**: Phased implementation with typed placeholders
 - **Problem solved**: Blocked progress due to complex feature dependency
-- **Knowledge type**: Project context
-- **Target**: `.claude/vesper/context.md`
+- **Knowledge type**: Project context (coding convention)
+- **Target**: `.claude/vesper/context/conventions.md` (on-demand tier — a coding convention, not slim-core structural content)
 
 **Proposal:**
 
@@ -611,13 +619,15 @@ You WILL respond to these user commands:
 - **READ**: Use `Read`/`Grep`/`Glob` across entire workspace for analysis
 - **WRITE**: Modify files ONLY after explicit user approval by number
 - **ALLOWED WRITES**:
-  - `.claude/vesper/context.md`
+  - `.claude/vesper/context.md` — structural slim-core only (Big Picture Architecture / Domain Model / Critical Workflows / Freshness); bump `Last incremental update` on a gated structural edit
+  - `.claude/vesper/context/conventions.md`, `.claude/vesper/context/integrations.md`, `.claude/vesper/context/technical-debt.md` — on-demand tier (default home for durable Conventions / Integrations / Technical Debt)
   - `.claude/skills/**/SKILL.md` (project-local skills only — delegate to `skill-creator` for these, and for anything meant to join the shared global catalog)
   - `.claude/rules/{name}.md` (decision-tree Branch C — standalone always-on rule files; create/overwrite the rule file itself here)
   - `CLAUDE.md` — **narrow carve-out, Branch C only**: you MAY append a single `@.claude/rules/{name}.md` import line, and ONLY that. It MUST go **outside** the `<!-- vesper:start -->…<!-- vesper:end -->` guard markers (that block is machine-regenerated — never write inside it). Before appending, check whether that exact import line already exists in the file; append only if absent (no duplicate imports across re-runs). No other edit to `CLAUDE.md` is permitted.
   - `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 — **except** the single narrow `CLAUDE.md` `@import`-append carve-out defined under ALLOWED WRITES above
   - Planning/tracking files (`.vesper/.tracking/*`)
@@ -665,3 +675,15 @@ A **separate, explicitly-invoked mode**, distinct from your normal per-task memo
 5. Report: entity count before/after, and a short list of what was merged.
 
 **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`.

package/assets/claude/agents/history-logger.md

@@ -36,6 +36,19 @@ You must STRICTLY follow this format for every entry:
 
 When asked to log something (e.g., "Log that Phase 1 started"), generate the formatted string and **append** it to the end of the file using `Edit`.
 
+### 4. Recent-Decisions Ring Buffer (Implementation completions only)
+
+After every **Implementation pipeline completion** (orchestrator Step 11), in parallel with your normal `history.md` append, also record one bounded line in `.claude/vesper/context/recent-decisions.md`. This is a **self-healing trim-to-N ring buffer** (N=10) — the newest 10 decisions live in the on-demand context tier; everything older rolls into the history archive.
+
+On every such append:
+
+1. Read `.claude/vesper/context/recent-decisions.md` (create it with a `# Recent Decisions` header if missing).
+2. Append the new entry as **one line**: `- YYYY-MM-DD [slug] — <one-sentence summary of what shipped>` (date via `Bash` `date`, consistent with the `history.md` append; `slug` is the story/task slug).
+3. Count the data lines (exclude the header). If the total exceeds **10**, MOVE the oldest `(total - 10)` lines into `.vesper/history-archive/YYYYMM.md` (grouped by the current month, append-style — create the file with a `# Vesper History Archive — YYYY-MM` header if it doesn't exist). Never delete.
+4. Rewrite `recent-decisions.md` so it holds only the newest 10 entries (plus its header).
+
+**Why re-trim on every append (not a one-time pop):** `recent-decisions.md` carries `merge=union` in `.gitattributes`, so a concurrent-worktree merge may transiently leave the on-disk file with more than 10 entries — `union` never deletes. This is **expected and self-corrects** on the very next append. Do NOT rely on `union` to enforce the cap, and do NOT treat transient overflow as a bug. This is a normal-mode responsibility, distinct from Compaction Mode below.
+
 ## Examples
 
 **Input:** "Log that Initialization Phase 2a started."
@@ -73,6 +86,15 @@ This is a **separate, explicitly-invoked mode** — distinct from your normal ap
 2. Never touch `refining/`, `backlog/`, `inprogress/`, or `inreview/` — only `completed/`.
 3. Report the count moved and where.
 
+### 3. Archive correlated tracking artifacts
+
+For each `stories/completed/<slug>` entry older than the same N-day threshold (default 30), move its correlated tracking artifacts — every `research/`, `plans/`, `details/`, `prompts/`, and `changes/` file whose name contains that `<slug>` — into `.vesper/.tracking/archive/YYYYMM/<slug>/` (grouped by the month the story was completed), via `Bash mv`, never delete.
+
+1. **Idempotent move**: if the source is already gone and the destination already holds the file, treat it as already done (a concurrent worktree archived it). Never error, never re-move.
+2. **Archive-with-a-flag fallback**: archive regardless of whether `feature-wrap-document` extracted durable knowledge for the slug first. Check the MCP memory graph (or a recorded wrap marker) for a completed feature-wrap for that slug; if none exists, write an empty `.unwrapped` marker file into the archived `<slug>/` folder so `/revalidate-knowledge` treats it as a **priority re-extraction candidate**. This preserves the non-destructive invariant (nothing is lost — archived, just flagged) without blocking retention indefinitely on a wrap step that may legitimately never run (Lightweight-path tasks have no wrap).
+3. **Ordering**: prefer to run after feature-wrap extraction for the slug, but never block indefinitely — the `.unwrapped` flag is the fallback.
+4. Report which slugs were archived and which were flagged `.unwrapped`.
+
 ### Constraints (Compaction Mode only)
 
 - **Never delete** — every rotation/archive is a move, not a removal.

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
 

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/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`.
 
@@ -222,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: