@mthanh/vespercli 1.6.0 → 1.7.1

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:

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

@@ -135,6 +135,8 @@ START: Is this a RULE about how to write/modify code?
 
 You MUST present ALL proposed updates as a numbered summary, then wait for user to approve by number (partial approval supported).
 
+**Scope of this approval gate (important):** this numbered-approval workflow applies ONLY to genuinely **structural** edits of the injected `.github/copilot-instructions.md` core (Big Picture Architecture / Domain Model / Critical Workflows) and of the on-demand tier's Conventions / Integrations / Technical Debt files (`.claude/vesper/context/{conventions,integrations,technical-debt}.md`, Claude-namespaced but shared across targets). It does **NOT** cover the trivial, high-frequency `.claude/vesper/context/recent-decisions.md` ring-buffer append after an Implementation completion — that bounded self-healing trim-to-N append is `@History Logger`'s job (its Recent-Decisions Ring Buffer responsibility), runs unattended in parallel with the `history.md` append, and must never be routed through this approval loop. Do not propose or apply `recent-decisions.md` line appends here.
+
 ### Step 1: Analyze and Generate All Proposals
 
 You WILL:
@@ -519,11 +521,14 @@ You WILL respond to these user commands:
 - **READ**: Use any read tool across entire workspace for analysis
 - **WRITE**: Modify files ONLY after explicit user approval by number
 - **ALLOWED WRITES**:
-  - `.vesper/instructions/*.instructions.md`
+  - `.vesper/instructions/*.instructions.md` (coding rules/conventions — Copilot's per-rule instruction files, wired via `chat.instructionsFilesLocations`, kept OUT of the auto-injected `.github/copilot-instructions.md` core)
+  - `.claude/vesper/context/conventions.md`, `.claude/vesper/context/integrations.md`, `.claude/vesper/context/technical-debt.md` — shared on-demand tier (default home for durable whitepaper Conventions / Integrations / Technical Debt; Claude-namespaced paths shared across targets)
+  - `.github/copilot-instructions.md` — structural slim-core only (Big Picture Architecture / Domain Model / Critical Workflows / Freshness); bump `Last incremental update` on a gated structural edit
   - `.vesper/skills/**/SKILL.md`
   - `docs/*.md`
   - `README.md`
 - **FORBIDDEN WRITES**:
+  - `.claude/vesper/context/recent-decisions.md` — `@History Logger`'s ring buffer, never written here
   - Source code files (unless explicitly requested)
   - Configuration files
   - Planning/tracking files (`.vesper/.tracking/*`)
@@ -571,6 +576,18 @@ A **separate, explicitly-invoked mode**, distinct from your normal per-task memo
 
 **Never** perform this compaction as a side effect of a normal feature-wrap invocation — only when explicitly asked for compaction.
 
+## 🔁 Knowledge Revalidation Mode (`/revalidate-knowledge` only — never the default behavior)
+
+A **separate, explicitly-invoked mode**, distinct from both your normal per-task memory-update job and Memory Compaction Mode above. Runs when Vesper delegates the `/revalidate-knowledge` flow (user-invoked, suggested on staleness/drift). `@Workspace Learner` handles the whitepaper/archive-revalidation and core/on-demand re-balance side of the same request in parallel — this mode is scoped to the **memory graph only**, and unlike Compaction Mode (which just merges/dedupes on *size*) it **re-validates** entities against the freshly revalidated whitepaper and current code.
+
+1. `read_graph()` (or `search_nodes` broadly) to see the full set of entities.
+2. Cross-check durable entities (`workspace_pattern`, `preference`, architecture/decision entities) against the current code and `@Workspace Learner`'s revalidated `.claude/vesper/context.md` core + on-demand tier. Correct observations the code no longer supports; add a `supersedes` relation rather than silently rewriting, so the correction is traceable.
+3. Give priority to knowledge tied to `.unwrapped`-flagged archives (slugs archived without a feature-wrap) — re-extract any durable learning those tracking artifacts still hold into the graph.
+4. Merge/dedupe as in Compaction Mode where entities are now redundant post-revalidation. Never touch `current_task` or anything with an active relation.
+5. Report: entities revalidated, corrected, superseded, and re-extracted from flagged archives.
+
+**Never** perform revalidation as a side effect of a normal feature-wrap invocation — only when explicitly asked via `/revalidate-knowledge`.
+
 ## Terminal Discipline
 
 - **Tools-first, terminal-last**: Never use terminal for tasks built-in tools handle (`read_file`, `grep_search`, `file_search`, `create_file`, `replace_string_in_file`). Never use `python -c`, `node -e`, or shell commands to read, write, or modify files.

package/assets/core/agents/history-logger.agent.md

@@ -37,6 +37,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.
 
+### 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 the terminal `date` command, 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."
@@ -70,10 +83,19 @@ This is a **separate, explicitly-invoked mode** — distinct from your normal ap
 
 ### 2. Archive completed tracking stories
 
-1. List `.vesper/.tracking/stories/completed/`. For story files older than N days (default 30, or as specified), move them (via terminal `mv`, not delete) into `.vesper/.tracking/stories/completed/archive/YYYYMM/`, grouped by the month they were completed.
+1. List `.vesper/.tracking/stories/completed/`. Move **every** story file found there (via terminal `mv`, not delete) into `.vesper/.tracking/stories/completed/archive/YYYYMM/`, grouped by the month they were completed. There is no age condition — every run archives the entire current contents of `completed/`.
 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 archived in Step 2 (i.e., every completed story, unconditionally — this section no longer applies its own separate age gate; it always runs for whatever Step 2 just archived), 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 terminal `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 and Retrospective Agent` 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/core/agents/vesper.agent.md

@@ -99,6 +99,7 @@ For verified trivial edits, Vesper MAY perform the change directly instead of de
 
 - `<agents>` section in the system prompt — delegate to `@Workspace Learner` instead. Never embed, quote, or forward its contents in any prompt.
 - `<skills>` section in the system prompt — skill assignments come from the Team Roster only
+- 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.
 
 ### **PACKAGE ASSET PROTECTION**
 
@@ -204,6 +205,8 @@ When workspace is already set up:
 
 **Persisted-knowledge size check** (independent of the resumption logic above): if `.vesper/memory.jsonl` looks large (roughly >500 entities) or `.vesper/history.md` has grown long (roughly >150 entries), suggest the user run the `#compact-knowledge` prompt — a 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. This is a suggestion, never a blocker — proceed with the user's actual request regardless.
 
+**Whitepaper staleness check** (independent of both the resumption logic and the size check above): the always-injected project-context core (`.github/copilot-instructions.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`). Read that header and suggest the user run the `#revalidate-knowledge` prompt when EITHER staleness signal fires: **time drift** — `Last full re-scan` is more than **30 days** old; or **commit drift** — the freshly-fetched base-branch tip 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**. These are the same **30d / 25-commit / 7d** thresholds documented canonically in the Claude orchestrator's staleness block (`assets/claude/vesper-orchestrator.md`) — do not re-derive or diverge them. Suggest-only, never auto-run (`#revalidate-knowledge` reads archives and performs a heavier semantic re-validation — the user's call); proceed with the user's actual request regardless.
+
 ---
 
 ## 🔌 MCP Readiness Preflight

package/assets/core/agents/workspace-learner.agent.md

@@ -136,17 +136,33 @@ If `EXISTING_CONTENT` is not empty, apply this merge strategy:
 **Step 3c — Write/Edit the file:**
 Use the `edit` tool to generate or update `.github/copilot-instructions.md`.
 
-**This file is the single project-context document that helps ALL agents code effectively.** It replaces any separate workspace-learning file — all deep analysis goes here.
+**This file is the single always-injected project-context document that helps ALL agents code effectively.** Because it is auto-injected into every session, 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-injected and are read only when an agent needs that detail. These on-demand files are shared cross-client knowledge (the same canonical location the Claude target and the `history-logger` ring buffer use), alongside the shared `.vesper/` tracking state.
 
-**Required sections:**
+**Slim-core — 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.
+- `.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.
+
+**Freshness header format** (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`. **On a full regen (`/reinit`)** set `Last full re-scan` to today plus the current commit short-sha (`git rev-parse --short HEAD`) AND reset `Last incremental update` to today. `Last revalidation` is set ONLY 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 `orchestration.instructions.md`):
 
@@ -155,15 +171,17 @@ Use the `edit` tool to generate or update `.github/copilot-instructions.md`.
 - System Prompt Deny-List
 - Agent names, skill assignments, or routing rules
 
+**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 the `read` tool to confirm `.github/copilot-instructions.md` exists, contains all required sections (Architecture, Development Standards, Verification, Domain Model, Workflows, Conventions, Integrations), and does NOT contain Team Roster or Task Management sections.
+**Step 3d — Verify (line-budget enforcement):**
+After editing, run `wc -l .github/copilot-instructions.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 with its one-line pointer, then re-run `wc -l` and repeat until ≤ 200 lines. Then use the `read` tool to confirm the file exists, carries the Freshness header, contains only the core sections + one-line pointers, and does NOT contain Team Roster or Task Management sections. Confirm each on-demand file referenced by a pointer actually exists.
 
 ##### File 2: `.github/instructions/orchestration.instructions.md`
 
@@ -468,6 +486,19 @@ When invoked with a **roster review** request (not a full init/re-init), run thi
 7. If Vesper requested validation after this step, return the proposal — Architect validates next.
 8. If Vesper requests application after validation, run Phase 4 Steps 3-6 (install + verify installation + update roster + verify roster against orchestration instructions) 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 and Retrospective Agent` runs the memory-graph side in parallel. Your job: **rescan → revalidate → re-balance**.
+
+### Steps
+
+1. **Reindex first**: call `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 (Freshness header + Big Picture Architecture + Domain Model + Critical Workflows only) and the `.claude/vesper/context/*.md` on-demand tier, re-running the ≤ 200-line `wc -l` budget check and extracting any overflow (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.
+
 ## Terminal Discipline
 
 - **Timeout**: Every command gets one. Quick=15s, build=120s, test=300s. Default=30s.

package/assets/core/prompts/compact-knowledge.prompt.md

@@ -8,7 +8,7 @@ Compact persisted Vesper knowledge — distinct from Claude Code's `/compact` or
 
 Delegate:
 
-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 **every** `.vesper/.tracking/stories/completed/` entry unconditionally, 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 and Retrospective Agent` 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/core/prompts/revalidate-knowledge.prompt.md

@@ -0,0 +1,19 @@
+---
+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.'
+---
+
+# Revalidate Knowledge
+
+Re-establish the truth of the project whitepaper. Unlike `#compact-knowledge` (which is triggered on *size* and 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 and Retrospective Agent` (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/core/skills/agent-fundamentals/SKILL.md

@@ -21,6 +21,7 @@ Universal operating rules for every agent in the Vesper ecosystem. These are non
 - Results include actual source code — skip `read_file` 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_search`, `semantic_search`, `file_search` 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/core/skills/agent-fundamentals/references/codebase-query.md

@@ -11,6 +11,10 @@ How Vesper agents should explore and understand any codebase.
 4. run_in_terminal  (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_search`, `read_file`, 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
 
 ### vesper_search

package/assets/manifest.json

@@ -1,6 +1,6 @@
 {
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.808Z",
+  "generated": "2026-07-19T18:29:56.188Z",
   "description": "Available Vesper assets. Use with: vespercli add agents|prompts|instructions|skills <name>",
   "agents": [],
   "prompts": [],
@@ -29,6 +29,7 @@
     "skill-creator",
     "tailwind-shadcn",
     "vercel-react-best-practices",
+    "vesper-catalog-editing-safety",
     "vscode-agent-config",
     "web-design-guidelines",
     "web-frameworks"

package/assets/skills/aesthetic/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "aesthetic",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.811Z",
+  "generated": "2026-07-19T18:29:56.191Z",
   "files": [
     "SKILL.md",
     "assets/design-guideline-template.md",

package/assets/skills/ai-multimodal/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-multimodal",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.812Z",
+  "generated": "2026-07-19T18:29:56.192Z",
   "files": [
     "SKILL.md",
     "references/audio-processing.md",

package/assets/skills/backend-development/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "backend-development",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.813Z",
+  "generated": "2026-07-19T18:29:56.193Z",
   "files": [
     "SKILL.md",
     "references/backend-api-design.md",

package/assets/skills/better-auth/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "better-auth",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.814Z",
+  "generated": "2026-07-19T18:29:56.194Z",
   "files": [
     "SKILL.md",
     "references/advanced-features.md",

package/assets/skills/chrome-devtools/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "chrome-devtools",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.815Z",
+  "generated": "2026-07-19T18:29:56.195Z",
   "files": [
     "SKILL.md",
     "references/cdp-domains.md",

package/assets/skills/code-review/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "code-review",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.815Z",
+  "generated": "2026-07-19T18:29:56.195Z",
   "files": [
     "SKILL.md",
     "references/code-review-reception.md",

package/assets/skills/databases/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "databases",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.816Z",
+  "generated": "2026-07-19T18:29:56.196Z",
   "files": [
     "SKILL.md",
     "references/mongodb-aggregation.md",

package/assets/skills/debugging/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "debugging",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.817Z",
+  "generated": "2026-07-19T18:29:56.198Z",
   "files": [
     "defense-in-depth/SKILL.md",
     "root-cause-tracing/SKILL.md",

package/assets/skills/devops/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "devops",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.818Z",
+  "generated": "2026-07-19T18:29:56.199Z",
   "files": [
     "SKILL.md",
     "references/browser-rendering.md",

package/assets/skills/docs-seeker/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "docs-seeker",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.819Z",
+  "generated": "2026-07-19T18:29:56.199Z",
   "files": [
     "SKILL.md",
     "WORKFLOWS.md",

package/assets/skills/document-skills/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "document-skills",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.821Z",
+  "generated": "2026-07-19T18:29:56.201Z",
   "files": [
     "docx/LICENSE.txt",
     "docx/SKILL.md",

package/assets/skills/frontend-design/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "frontend-design",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.822Z",
+  "generated": "2026-07-19T18:29:56.202Z",
   "files": [
     "SKILL.md",
     "references/animejs.md"

package/assets/skills/gitlab-guardrails/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "gitlab-guardrails",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.823Z",
+  "generated": "2026-07-19T18:29:56.202Z",
   "files": [
     "SKILL.md"
   ]

package/assets/skills/google-adk-python/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "google-adk-python",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.823Z",
+  "generated": "2026-07-19T18:29:56.203Z",
   "files": [
     "SKILL.md"
   ]

package/assets/skills/mcp-builder/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-builder",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.824Z",
+  "generated": "2026-07-19T18:29:56.203Z",
   "files": [
     "LICENSE.txt",
     "SKILL.md",

package/assets/skills/mermaidjs-v11/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "mermaidjs-v11",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.825Z",
+  "generated": "2026-07-19T18:29:56.204Z",
   "files": [
     "SKILL.md",
     "references/cli-usage.md",

package/assets/skills/premium-frontend-ui/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "premium-frontend-ui",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.825Z",
+  "generated": "2026-07-19T18:29:56.204Z",
   "files": [
     "SKILL.md"
   ]

package/assets/skills/problem-solving/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "problem-solving",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.826Z",
+  "generated": "2026-07-19T18:29:56.205Z",
   "files": [
     "ABOUT.md",
     "collision-zone-thinking/SKILL.md",

package/assets/skills/react-mui-tanstack/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "react-mui-tanstack",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.827Z",
+  "generated": "2026-07-19T18:29:56.205Z",
   "files": [
     "SKILL.md",
     "resources/common-patterns.md",

package/assets/skills/sequential-thinking/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "sequential-thinking",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.827Z",
+  "generated": "2026-07-19T18:29:56.206Z",
   "files": [
     "README.md",
     "SKILL.md",

package/assets/skills/skill-creator/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "skill-creator",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.828Z",
+  "generated": "2026-07-19T18:29:56.206Z",
   "files": [
     "LICENSE.txt",
     "SKILL.md",

package/assets/skills/tailwind-shadcn/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "tailwind-shadcn",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.829Z",
+  "generated": "2026-07-19T18:29:56.207Z",
   "files": [
     "LICENSE.txt",
     "SKILL.md",

package/assets/skills/vercel-react-best-practices/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "vercel-react-best-practices",
   "version": "1.0.0",
-  "generated": "2026-07-18T13:27:53.830Z",
+  "generated": "2026-07-19T18:29:56.208Z",
   "files": [
     "AGENTS.md",
     "README.md",