@mthanh/vespercli 1.5.1 → 1.7.0

package/README.md

@@ -2,7 +2,65 @@
 
 CLI tool to manage AI agents, prompts, instructions, and skills for your workspace — for GitHub Copilot Chat in VS Code, and for Claude Code.
 
-**Vesper** is a comprehensive agent suite that supercharges your AI coding assistant with specialized agents, reusable skills, and structured workflows. Everything below describes the default (Copilot) target; see [Claude Code target](#claude-code-target) for the second target.
+**Vesper** is a comprehensive agent suite that supercharges your AI coding assistant with specialized agents, reusable skills, and structured workflows. It supports two platforms — **GitHub Copilot** (VS Code) and **Claude Code** — chosen via a multi-select during `vespercli init`; a single workspace can run both at once, sharing the same `.vesper/` tracking state.
+
+## The Vesper Lifecycle
+
+Vesper is a **pure orchestrator** — it routes, gates, and approves every hand-off, but never does the work itself. Each task travels one revolution of the cycle: the violet **delivery loop** ships it (specialist subagents research, plan, implement, review, and test, with every step reading and writing tracking documents under `.vesper/.tracking/`), and the amber **learning loop** mines what just happened — comparing plan vs. actual, then minting skills, instructions, and knowledge-graph memory that are re-injected into the next task.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/lifecycle-ring-dark.svg">
+  <img src="docs/images/lifecycle-ring-light.svg" alt="Vesper lifecycle ring: Research, Plan, Validate, Implement, Review + Test (delivery), then Retrospect, Store, Re-inject (learning), with Vesper orchestrating at the center" width="760">
+</picture>
+
+Every revolution leaves the system smarter: divergences from plan become glob-scoped instructions, repeated patterns become skills, and task context survives interruption — across sessions and across both client targets.
+
+### Tracking documents — the paper trail
+
+Delegation prompts pass **paths, never contents**. Each document has one writer and defined readers, so a fresh-context subagent can pick up mid-pipeline — even a subagent on the *other client* (Copilot ↔ Claude Code share `.vesper/` by design).
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/panel-ledger-dark.svg">
+  <img src="docs/images/panel-ledger-light.svg" alt="Tracking-documents ledger: research, plans, details, prompts, changes, issues, and stories files — each with one writer and defined consumers; story folders carry status: refining, backlog, inprogress, inreview, completed" width="920">
+</picture>
+
+### Implementation runs on prompts, not vibes
+
+The planner doesn't just plan — it writes the *executable brief* each developer will follow:
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/panel-chain-dark.svg">
+  <img src="docs/images/panel-chain-light.svg" alt="Prompt chain: planner emits plan, details, and one prompt file per track; Vesper's blocking gate verifies all planning files exist; developers execute the prompt exactly in parallel; divergences from plan are logged in the changes file as the retrospective's raw material" width="920">
+</picture>
+
+### Task tracker — board is the source of truth
+
+The Task Management section of the orchestration file names the system (ClickUp, Jira, …) and its Task Agent; the pipeline never talks to a board directly. **Local mode** works with zero configuration — the story folders alone carry status.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/panel-tracker-dark.svg">
+  <img src="docs/images/panel-tracker-light.svg" alt="Task tracker: ClickUp, Jira, or Local; status flow REFINED to IN PROGRESS to IN REVIEW to DONE with routing guards (never re-refine, re-assign, or re-implement); board wins discrepancies; Case A fetches a referenced task, Case B auto-creates one after refinement" width="920">
+</picture>
+
+### The retrospective engine — where skills are born
+
+After every implementation, the Feature Wrap agent compares what was planned against what actually happened, then routes each learning through a decision tree:
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/panel-retro-dark.svg">
+  <img src="docs/images/panel-retro-light.svg" alt="Retrospective engine: mines changes, plans, details, research, and git diffs; patterns in 3+ files become skills, structures in 5+ files become instructions; decision tree routes learnings to INSTRUCTION, SKILL, DOCUMENTATION, or the MEMORY GRAPH, behind Vesper's approval filter" width="920">
+</picture>
+
+### Where learning re-enters the pipeline
+
+Capture is worthless without injection — every knowledge output has a named consumer at a named step:
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/panel-reentry-dark.svg">
+  <img src="docs/images/panel-reentry-light.svg" alt="Four re-entry points: memory search before research, current_task recall before planning, roster skill injection on every delegation, and glob-bound instruction auto-apply on every matching edit" width="920">
+</picture>
+
+The design optimizes for compounding: mistakes convert to rules, workflows convert to skills, and state survives interruption, `/clear`, and even a client switch. When a fix loop caps out (10 iterations), unresolved issues are written to `issues/` and the pipeline continues — dead ends become documents, not lost context.
 
 ## Installation
 
@@ -17,29 +75,24 @@ npx @mthanh/vespercli <command>
 ## Quick Start
 
 ```bash
-# Initialize Vesper in your project
-# (multi-select which platform(s) to set up — GitHub Copilot and/or Claude Code;
-#  pass --target copilot,claude or --target all to skip the prompt)
+# Initialize Vesper in your project — multi-select GitHub Copilot and/or Claude Code
+# (pass --target copilot,claude or --target all to skip the prompt)
 vespercli init
+```
 
-# (Optional) Add local overrides to customize specific assets
-vespercli add --agent code-reviewer code-planner
-
-# Add skills (as local overrides)
-vespercli add --skill aesthetic tailwind-shadcn
+Then say hello:
 
-# List local overrides
-vespercli list
+- **GitHub Copilot** — reload VS Code (`Developer: Reload Window`), open Copilot Chat, select **Vesper** from the agent dropdown, and prompt `Vesperize` — Vesper scans the workspace and assembles your team.
+- **Claude Code** — start a session and prompt `init` — Vesper detects the missing Team Roster and runs the full workspace setup automatically.
 
-# Update local overrides
-vespercli update
-```
+## Settings-based Asset Injection
 
-## Settings-based Asset Injection (New)
+Vesper integrates by **pointing your AI client at the packaged catalog** instead of copying assets into your repo — VS Code workspace settings for Copilot, a user-level plugin for Claude Code. Only project-specific files (roster, context, tracking) live in the workspace.
 
-Vesper now integrates with VS Code by **configuring workspace settings** instead of copying the full asset catalog into your repo.
+<details>
+<summary><b>GitHub Copilot</b> — VS Code settings + MCP servers</summary>
 
-### What `vespercli init` does
+`vespercli init` (with Copilot selected):
 
 - Creates/updates `.vscode/settings.json` to point Copilot Chat at Vesper's packaged assets.
 - Configures core MCP servers in `.vscode/mcp.json`:
@@ -79,7 +132,29 @@ Example (illustrative):
 }
 ```
 
-### Local overrides (still supported)
+</details>
+
+<details>
+<summary><b>Claude Code</b> — user-level plugin + project orchestrator files</summary>
+
+Claude Code has no equivalent of VS Code's `chat.agentFilesLocations` setting, so the specialist catalog is distributed as a **user-level plugin** instead: `vespercli init` (with Claude Code selected) installs it once to `~/.claude/skills/vesper/`, making it available in **every** Claude Code project on the machine. In the current project it creates only:
+
+- `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, 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>
+
+<details>
+<summary><b>Local overrides</b> — customize specific assets</summary>
 
 If you want to customize a specific agent/prompt/instruction/skill, use `vespercli add`.
 
@@ -87,16 +162,12 @@ If you want to customize a specific agent/prompt/instruction/skill, use `vesperc
 - Local copies in `.vesper/` take precedence over the settings-based (package) assets.
 - This is the recommended way to make small, intentional customizations without vendoring everything.
 
-### Migration from legacy `.vesper/` installs
-
-If Vesper detects a legacy install that previously copied assets into `.vesper/`, `vespercli init` will offer to migrate you to the settings-based approach.
-
-- After migrating, you can keep any locally customized files as overrides.
-- Everything else is discovered directly from the Vesper package.
+</details>
 
 ## Commands
 
-### `vespercli init`
+<details>
+<summary><b><code>vespercli init</code></b> — initialize platform(s) in your workspace</summary>
 
 Initialize Vesper in your workspace. Pick one or more platforms (GitHub Copilot
 and/or Claude Code) via a multi-select prompt; the CLI lays down the base setup
@@ -116,7 +187,10 @@ vespercli init --target claude -y       # Non-interactive: Claude with default s
 vespercli init --path /my/project       # Specify workspace path
 ```
 
-### `vespercli add`
+</details>
+
+<details>
+<summary><b><code>vespercli add</code></b> — add local overrides</summary>
 
 Add local overrides (copies) for agents, prompts, instructions, or skills into `.vesper/`.
 
@@ -136,9 +210,15 @@ vespercli add -i nextjs reactjs
 # Add skills
 vespercli add --skill <name> [name2...]
 vespercli add -s aesthetic backend-development
+
+# For Claude Code, adds go to the shared plugin catalog instead
+vespercli add agents code-reviewer --target claude
 ```
 
-### `vespercli list`
+</details>
+
+<details>
+<summary><b><code>vespercli list</code></b> — list local overrides</summary>
 
 List local override assets in `.vesper/`.
 
@@ -149,7 +229,10 @@ vespercli list --type agents      # Filter by type
 vespercli list -t skills          # Short form
 ```
 
-### `vespercli update`
+</details>
+
+<details>
+<summary><b><code>vespercli update</code></b> — refresh local overrides</summary>
 
 Update local override assets from the package to get the latest versions.
 
@@ -158,7 +241,10 @@ vespercli update                  # Interactive confirmation
 vespercli update -y               # Skip confirmation
 ```
 
-### `vespercli reset`
+</details>
+
+<details>
+<summary><b><code>vespercli reset</code></b> — remove configuration and/or overrides</summary>
 
 Remove Vesper configuration and/or local overrides.
 
@@ -170,7 +256,25 @@ vespercli reset --local-only      # Only remove local `.vesper/` folder
 vespercli reset --full            # Remove EVERYTHING including vesper.agent.md (requires typing "YES")
 ```
 
-### `vespercli mcp`
+</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>
 
 Manage MCP servers for whichever target(s) are installed here — Copilot (`.vscode/mcp.json`), Claude Code (`.mcp.json`), or both at once. `mcp add`/`mcp remove`/`mcp list` are for **optional catalog servers** (e.g. `clickup`); the three Vesper-core servers (`vesper-indexing`, `sequential-thinking`, `memory`) are managed separately via `mcp enable`/`mcp disable`/`mcp sync` and are never addable/removable through `mcp add`/`mcp remove`.
 
@@ -187,27 +291,21 @@ vespercli mcp sync                         # Re-sync tool auto-approval (Copilot
 vespercli mcp reindex --full               # Clear and rebuild the shared code index
 ```
 
-`mcp add`/`mcp remove`/`mcp list` are fully supported for the Claude Code target — earlier versions silently no-op'd here for anything beyond the 3 core servers.
-
-### `vespercli --version`
+</details>
 
-Display the current version.
+<details>
+<summary><b><code>vespercli --version</code></b> / <b><code>--help</code></b></summary>
 
 ```bash
-vespercli -v
+vespercli -v                      # Display the current version
 vespercli --version
-```
-
-### `vespercli --help`
-
-Display help information.
-
-```bash
-vespercli -h
+vespercli -h                      # Display help information
 vespercli --help
 vespercli <command> --help
 ```
 
+</details>
+
 ## Asset Types
 
 Vesper provides a full catalog via VS Code settings, and supports optional local overrides.
@@ -221,52 +319,10 @@ Vesper provides a full catalog via VS Code settings, and supports optional local
 
 ## After Installation
 
-1. Open VS Code in your workspace
-2. Open GitHub Copilot Chat (`Ctrl+Shift+I` / `Cmd+Shift+I`)
-3. Select **Vesper** from the agent dropdown
-4. Start working with an AI agent suite that includes specialized developers, planners, reviewers, and more
-
-## Claude Code target
-
-Vesper also targets **Claude Code**, as a second, fully independent install alongside (or instead of) the Copilot target above — nothing here changes the default behavior of the commands described so far.
-
-Claude Code has no equivalent of VS Code's `chat.agentFilesLocations` setting (no way to point it at an arbitrary external directory), so the specialist catalog is distributed as a **user-level plugin** instead of referenced in place: `vespercli init --target claude` installs it once to `~/.claude/skills/vesper/`, and it's then available in **every** Claude Code project on the machine, not just this one. Only genuinely project-specific content lives in the repo:
-
-```bash
-vespercli init --target claude          # Install the plugin catalog + this project's orchestrator/roster/context
-```
-
-This creates, in the current project only:
-
-- `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
-- `.mcp.json` and `.claude/settings.json` — the `vesper-indexing` MCP server + its tool permissions
-
-No `.claude/agents/`, `.claude/commands/`, or `.claude/skills/` appear in the project — the full specialist catalog (subagents, slash commands, skills) lives once in the shared plugin at `~/.claude/skills/vesper/`.
-
-```bash
-vespercli init --target claude                          # Install/refresh everything above
-vespercli add agents code-reviewer --target claude       # Add one subagent to the plugin catalog
-vespercli list --target claude                           # See what's installed
-vespercli update --target claude                         # Refresh the plugin + orchestrator playbook after `npm update`
-vespercli reset --target claude                           # Remove this project's files (leaves the shared plugin catalog alone)
-vespercli mcp status --target claude                      # Check the vesper-indexing MCP server in .mcp.json; also warns on .mcp.json vs .vesperrc drift
-vespercli mcp add clickup --target claude                 # Add an optional catalog MCP server to .mcp.json + record it in .vesperrc
-vespercli mcp remove clickup --target claude              # Remove it (prunes both .mcp.json and .vesperrc)
-vespercli mcp list --target claude                        # List catalog + custom servers configured for this target
-```
-
-Unlike the Copilot target, this one has **no editor dependency** — `~/.claude/...` and a project's `.claude/`/`CLAUDE.md`/`.mcp.json` are read by the Claude Code engine itself, so the same install works whether you drive it from the plain terminal CLI, the VS Code extension, JetBrains, or the desktop app.
-
-### Mixed-target workspaces
-
-A single project can have both targets installed at once — `.vesper/` (the code index, story tracking, `history.md`) is shared and cross-client by design, so a story researched under Copilot can be picked up and implemented under Claude Code, or vice versa. `.vesperrc` records each target under its own key, so running `init --target claude` in an already-Copilot-initialized project adds a `claude` entry without touching the existing Copilot fields.
-
-### Naming and conflicts
+- **GitHub Copilot** — reload VS Code, open Copilot Chat (`Ctrl+Shift+I` / `Cmd+Shift+I`), select **Vesper** from the agent dropdown, and prompt `Vesperize` to assemble your team.
+- **Claude Code** — start a session (terminal, VS Code extension, JetBrains, or desktop app) and prompt `init` — Vesper runs the full workspace setup automatically.
 
-`vespercli init --target claude` asks once whether to prefix the catalog's subagent/skill/command names with `vesper-` (to avoid collisions with other Claude Code kits you may have installed) or keep plain names (the default, matching the Copilot catalog's naming 1:1). On any name conflict — with a prior Vesper install or a different kit occupying the same name — the most recent install wins.
+Either way you end up with the same suite — specialized developers, planners, reviewers, and testers orchestrated by Vesper, sharing one `.vesper/` tracking state across both clients.
 
 ## Requirements
 

package/assets/CATALOG.md

@@ -336,6 +336,12 @@ Core skills provide fundamental capabilities and are installed by default alongs
 - Description: Build distinctive, production-grade frontend interfaces with high design quality.
 - Pick when: Need UI implementation that's polished and non-generic; building reusable components/pages in React/Next; want design-led decisions baked into the code.
 
+### gitlab-guardrails
+
+- Path: `skills/gitlab-guardrails/`
+- Description: Vesper-owned GitLab MR safety policy — blocks the experimental `glab mr create --recover` flag and detects/removes stray `mr.json` recovery files before commit. Self-contained (in force even when the synced GitLab skills are absent).
+- Pick when: Creating/updating/reviewing GitLab merge requests or running any `glab mr` command; want a guardrail against leaking `--recover`/`mr.json` recovery state into the repo; agent role runs `Bash`/`glab`.
+
 ### premium-frontend-ui
 
 - Path: `skills/premium-frontend-ui/`
@@ -403,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/`
@@ -549,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

@@ -2,7 +2,7 @@
 name: feature-wrap-document
 description: Knowledge curator that captures implementation patterns and updates documentation, skills, and context
 model: claude-sonnet-5
-tools: Read, Grep, Glob, Edit, Write, Agent, mcp__vesper-indexing__vesper_search, mcp__memory__create_entities, mcp__memory__create_relations, mcp__memory__add_observations, mcp__memory__search_nodes, mcp__memory__open_nodes, mcp__memory__delete_entities, mcp__memory__delete_observations
+tools: Read, Grep, Glob, Edit, Write, Bash, Agent, mcp__vesper-indexing__vesper_search, mcp__memory__create_entities, mcp__memory__create_relations, mcp__memory__add_observations, mcp__memory__search_nodes, mcp__memory__open_nodes, mcp__memory__delete_entities, mcp__memory__delete_observations
 skills: [agent-fundamentals]
 ---
 
@@ -105,8 +105,34 @@ You WILL categorize knowledge using this example decision tree:
 
 ```
 START: Is this a RULE about how to write/modify code in THIS project?
-├─ YES → PROJECT CONTEXT UPDATE
-│  └─ Update `.claude/vesper/context.md` (Development Standards / Conventions section)
+├─ 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 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`,
+│  │     folding the glob into the skill description:
+│  │     "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
+│     (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).
+│        DEDUP GUARD: before appending, check whether that exact
+│        `@.claude/rules/{name}.md` line already exists in CLAUDE.md — append ONLY
+│        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 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
@@ -131,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:
@@ -276,15 +304,19 @@ 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:**
 
 - Prescriptive rules ("always", "never", "must", "avoid")
-- Applies to code creation/modification in this project
+- Applies **project-wide** to code creation/modification — NOT scoped to a specific file glob
 - Prevents common mistakes
 - Enforces consistency
 
+> Scope boundary: reserve `context.md` for **non-file-scoped** rules only. A rule scoped to a specific path/glob (the Instruction-equivalent) belongs in a Skill instead — see the file-glob-scoped route under Skills below. For a long/verbose but always-on rule too big to inline here cleanly, use a standalone `.claude/rules/{name}.md` with an `@import` from CLAUDE.md (B-vs-C heuristic in the decision tree above).
+
 **Format:**
 
 ```markdown
@@ -306,11 +338,13 @@ You WILL after all approved updates are applied:
 **Applies to:** [scenarios where rule is relevant]
 ```
 
-**Examples:**
+**Examples** (all genuinely project-wide — apply everywhere, not scoped to any file path/glob):
 
-- "Always use path aliases instead of relative imports"
-- "Never use next/dynamic with {ssr: false} in Server Components"
-- "Server actions must validate session before Firestore operations"
+- "Always use path aliases instead of relative imports" (applies to every import in the repo)
+- "Never commit secrets or credentials — load them from environment/config" (applies to all code)
+- "Prefer `node:`-prefixed builtins for standard-library imports" (applies across the whole codebase)
+
+> Counter-example — these are NOT `context.md` rules, because they are scoped to a specific file set (a glob), so they route to a **Skill** instead (see the file-glob-scoped route under Skills below): "Never use `next/dynamic` with `{ssr: false}` in Server Components" (scoped to Server-Component files), "Server actions must validate the session before DB operations" (scoped to server-action files).
 
 ---
 
@@ -322,6 +356,7 @@ You WILL after all approved updates are applied:
 - Reusable patterns with variations
 - Domain-specific knowledge
 - Prerequisites and concrete examples
+- **Also the Instruction-equivalent target**: a file-glob-scoped code rule (Copilot would put this in an `*.instructions.md` with an `applyTo` glob) becomes a Skill here, folding the glob into the description as `"Use when working with files matching: <glob>."` — Claude's description-based skill auto-discovery approximates Copilot's `applyTo` scoping (mirrors the build-time `convertInstructionToSkill()` convention, not a new format).
 
 **Format:**
 
@@ -427,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:**
 
@@ -454,6 +489,79 @@ message: 'Route refresh not yet implemented'
 
 ---
 
+### Pattern: File-Glob-Scoped Rule → Skill
+
+**Input (from changes file):**
+
+```markdown
+## Phase 3 Notes
+
+- Every server action under `src/app/**/actions.ts` now validates the session
+  before touching the database — three PRs shipped without this and regressed.
+```
+
+**Analysis:**
+
+- **Pattern**: A code rule scoped to a specific file set (`src/app/**/actions.ts`) — a real, bounded glob, NOT project-wide
+- **Knowledge type**: Instruction-equivalent → **Skill** (glob folded into the description)
+- **Target**: delegate to `skill-creator` → `.claude/skills/server-actions/SKILL.md`
+
+**Proposal:**
+
+```markdown
+---
+name: server-actions
+description: Use when working with files matching: src/app/**/actions.ts.
+---
+
+# Server Action Session Validation
+
+Validate the session before any DB operation in a server action…
+```
+
+---
+
+### Pattern: Long/Verbose Always-On Rule → `.claude/rules/` + `@import`
+
+**Input (from changes file):**
+
+```markdown
+## Phase 1 Notes
+
+- Documented the full error-handling policy: taxonomy, ret/log/rethrow rules,
+  and 4 worked examples — applies to ALL code, ~40 lines, too big for context.md.
+```
+
+**Analysis:**
+
+- **Pattern**: Project-wide (not file-scoped) but long and self-structured → Branch C
+- **Knowledge type**: standalone rule file + `CLAUDE.md` `@import`
+- **Target**: create `.claude/rules/error-handling.md`; append `@.claude/rules/error-handling.md` to `CLAUDE.md` (outside guard markers, only if the import line isn't already present)
+
+**Proposal:**
+
+```markdown
+<!-- .claude/rules/error-handling.md -->
+# Error Handling Policy
+
+## Taxonomy
+…
+
+## Rules
+…
+
+## Examples
+…
+```
+
+Then append to `CLAUDE.md` (outside `<!-- vesper:start -->…<!-- vesper:end -->`, dedup-checked):
+
+```markdown
+@.claude/rules/error-handling.md
+```
+
+---
+
 ## Quality Standards
 
 You WILL validate ALL proposals against these standards:
@@ -511,14 +619,19 @@ 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
+  - Configuration files — **except** the single narrow `CLAUDE.md` `@import`-append carve-out defined under ALLOWED WRITES above
   - Planning/tracking files (`.vesper/.tracking/*`)
+  - Anything inside the `CLAUDE.md` `<!-- vesper:start -->…<!-- vesper:end -->` guard block
 
 ## Output Format
 
@@ -562,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.