specrails-core 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "AI agent workflow system for Claude Code — installs 12 specialized agents, orchestration commands, and persona-driven product discovery into any repository",
   "bin": {
     "specrails-core": "bin/specrails-core.js"

package/templates/commands/sr/memory-inspect.md

@@ -0,0 +1,259 @@
+---
+name: "Agent Memory Inspector"
+description: "Inspect and manage agent memory directories. Lists all sr-* agent memory stores, shows per-agent stats (file count, size, last modified), displays recent entries, and detects stale or orphaned files."
+category: Workflow
+tags: [workflow, memory, agents, maintenance, diagnostics]
+---
+
+Inspect agent memory directories under `.claude/agent-memory/sr-*/` for **{{PROJECT_NAME}}**. Show per-agent stats, recent entries, and actionable recommendations.
+
+**Input:** `$ARGUMENTS` — optional:
+- `<agent-name>` — inspect a specific agent's memory (e.g. `sr-developer`, `sr-reviewer`)
+- `--stale <days>` — flag files not modified in more than N days as stale (default: 30)
+- `--prune` — delete stale files after confirmation (prints the list first, then asks)
+
+---
+
+## Phase 0: Argument Parsing
+
+Parse `$ARGUMENTS` to set runtime variables.
+
+**Variables to set:**
+
+- `AGENT_FILTER` — string or empty string. Default: `""` (inspect all agents).
+- `STALE_DAYS` — integer. Default: `30`.
+- `PRUNE_MODE` — boolean. Default: `false`.
+
+**Parsing rules:**
+
+1. Scan `$ARGUMENTS` for `--stale <N>`. If found, set `STALE_DAYS=<N>`. Validate that `<N>` is a positive integer; if not, print `Error: --stale requires a positive integer (e.g. --stale 14)` and stop. Strip from arguments.
+2. Scan for `--prune`. If found, set `PRUNE_MODE=true`. Strip from arguments.
+3. Remaining non-flag text (if any) is treated as `AGENT_FILTER`. Strip leading/trailing whitespace.
+
+**Print active configuration:**
+
+```
+Scanning: <all agents | agent: AGENT_FILTER> | Stale threshold: STALE_DAYS days | Prune: yes/no
+```
+
+---
+
+## Phase 1: Discover Memory Directories
+
+Glob all directories matching `.claude/agent-memory/sr-*/`.
+
+If no directories are found:
+```
+No agent memory directories found under .claude/agent-memory/.
+
+Agent memory is written by sr-* agents during the /sr:implement pipeline.
+Run /sr:implement on a feature to generate your first memory entries.
+```
+Then stop.
+
+If `AGENT_FILTER` is set, filter to only the directory `.claude/agent-memory/<AGENT_FILTER>/`. If that directory does not exist:
+```
+No memory directory found for agent: <AGENT_FILTER>
+
+Available agents:
+  <list of discovered sr-* directory names>
+```
+Then stop.
+
+Set `AGENT_DIRS` = list of matching directories (full paths), sorted alphabetically.
+
+---
+
+## Phase 2: Collect Per-Agent Stats
+
+For each directory in `AGENT_DIRS`, collect:
+
+- `AGENT_NAME` — directory name (e.g. `sr-developer`)
+- `FILE_COUNT` — total number of files (recursive, all types)
+- `TOTAL_SIZE` — total size in bytes; display as human-readable (KB, MB)
+- `LAST_MODIFIED` — ISO date of the most recently modified file
+- `OLDEST_MODIFIED` — ISO date of the least recently modified file
+- `STALE_FILES` — list of files not modified in more than `STALE_DAYS` days (full paths)
+- `STALE_COUNT` — count of stale files
+
+Use the current date to compute stale age. A file is stale if `(today - last_modified) > STALE_DAYS`.
+
+Print a summary table after collecting all stats:
+
+```
+## Agent Memory Overview
+
+| Agent | Files | Size | Last Modified | Stale (>STALE_DAYS days) |
+|-------|-------|------|---------------|--------------------------|
+| sr-developer   | N | N KB | YYYY-MM-DD | N files |
+| sr-reviewer    | N | N KB | YYYY-MM-DD | N files |
+| ...            | ... | ... | ...        | ...     |
+
+Total: N agents | N files | N KB
+```
+
+---
+
+## Phase 3: Display Recent Entries
+
+For each agent in `AGENT_DIRS`, show the 5 most recently modified files.
+
+Print per agent:
+
+```
+### <agent-name>
+
+Recent entries (5 most recent):
+
+| File | Size | Last Modified |
+|------|------|---------------|
+| common-fixes.md | 2.1 KB | 2026-03-18 |
+| ...             | ...    | ...         |
+```
+
+If the agent directory has fewer than 5 files, show all of them.
+
+If `AGENT_FILTER` is set (single-agent mode), show the full content of each file up to 50 lines. For files exceeding 50 lines, print the first 50 lines followed by:
+```
+... (N more lines — view full file at <relative-path>)
+```
+
+---
+
+## Phase 4: Orphan Detection
+
+An **orphaned** memory directory is one whose agent name does not correspond to a known sr-agent persona.
+
+Known sr-agent names (check for exact match):
+`sr-architect`, `sr-developer`, `sr-test-writer`, `sr-reviewer`, `sr-frontend-reviewer`, `sr-backend-reviewer`, `sr-security-reviewer`, `sr-doc-sync`, `sr-product-manager`
+
+For each directory in `AGENT_DIRS`, check whether its `AGENT_NAME` is in the known list. Collect non-matching directories as `ORPHANED_DIRS`.
+
+If `ORPHANED_DIRS` is non-empty, print:
+
+```
+### Orphaned Memory Directories
+
+The following directories do not match any known sr-agent name and may be leftover from renamed or removed agents:
+
+| Directory | Files | Size | Recommendation |
+|-----------|-------|------|----------------|
+| sr-old-agent | N | N KB | Review and delete if no longer needed |
+```
+
+If `ORPHANED_DIRS` is empty: skip this section entirely.
+
+---
+
+## Phase 5: Stale File Report
+
+Collect all stale files across all agents (from Phase 2 `STALE_FILES` lists).
+
+If no stale files exist:
+```
+No stale files found (threshold: STALE_DAYS days). Memory is up to date.
+```
+Skip the rest of Phase 5.
+
+Otherwise, print:
+
+```
+### Stale Files (not modified in >STALE_DAYS days)
+
+| Agent | File | Size | Last Modified | Age (days) |
+|-------|------|------|---------------|------------|
+| sr-developer | common-fixes.md | 1.2 KB | 2026-01-10 | 69 |
+| ...          | ...             | ...    | ...        | ...        |
+
+N stale files total (N KB).
+```
+
+---
+
+## Phase 6: Prune (if --prune)
+
+Skip this phase if `PRUNE_MODE=false`.
+
+If `PRUNE_MODE=true` and there are no stale files and no orphaned directories:
+```
+Nothing to prune. All memory files are within the STALE_DAYS-day threshold.
+```
+Then stop.
+
+Otherwise, print the full list of files and directories that will be deleted:
+
+```
+## Files to Delete
+
+The following N files will be permanently deleted:
+
+Stale files:
+  - .claude/agent-memory/sr-developer/common-fixes.md (69 days old)
+  - ...
+
+Orphaned directories:
+  - .claude/agent-memory/sr-old-agent/ (N files, N KB)
+
+Proceed? [y/N]:
+```
+
+Wait for user input.
+
+- If the user enters `y` or `Y`:
+  - Delete each stale file individually.
+  - Delete each orphaned directory recursively.
+  - Print a confirmation for each deletion: `Deleted: <path>`
+  - Print a summary:
+    ```
+    Pruned N files (N KB freed).
+    ```
+- If the user enters anything else (or presses Enter):
+  - Print: `Prune cancelled. No files were deleted.`
+  - Stop.
+
+---
+
+## Phase 7: Recommendations
+
+Print a final recommendations section based on findings:
+
+```
+## Recommendations
+
+<one or more of the following, based on findings>
+```
+
+**Recommendation rules (print only applicable ones):**
+
+1. **Prune stale data** — if `STALE_COUNT > 0` across any agent and `PRUNE_MODE=false`:
+   ```
+   - N stale files detected. Run `/sr:memory-inspect --prune` to remove them and free N KB.
+   ```
+
+2. **Investigate large memory** — if any single agent's `TOTAL_SIZE > 1 MB`:
+   ```
+   - <agent-name> memory exceeds 1 MB (TOTAL_SIZE). Consider reviewing large files:
+     <list files over 100 KB>
+   ```
+
+3. **Orphaned directories** — if `ORPHANED_DIRS` is non-empty:
+   ```
+   - N orphaned director(y|ies) found. Review and delete manually if no longer needed.
+   ```
+
+4. **Empty memory directories** — if any agent directory has `FILE_COUNT = 0`:
+   ```
+   - <agent-name> memory directory is empty. It may be safe to delete:
+     rm -rf .claude/agent-memory/<agent-name>/
+   ```
+
+5. **Gitignore advisory** — check whether `.claude/agent-memory` appears in `.gitignore`. If not:
+   ```
+   - Agent memory is local runtime state. Add to .gitignore:
+       echo '.claude/agent-memory/' >> .gitignore
+   ```
+
+If no recommendations apply, print:
+```
+All agent memory looks healthy. No action required.
+```

package/templates/commands/sr/vpc-drift.md

@@ -0,0 +1,405 @@
+---
+name: "VPC Persona Drift Detector"
+description: "Detect when user personas defined in the VPC are drifting from actual usage patterns. Compares persona Jobs/Pains/Gains against the product backlog, implemented features, and agent memory to surface alignment gaps and recommend VPC updates."
+category: Product
+tags: [product, vpc, personas, drift, alignment]
+---
+
+Analyze **{{PROJECT_NAME}}** for VPC persona drift — gaps between what persona definitions promise and what the product actually delivers. Produces a per-persona alignment score, drifted attributes, and concrete VPC update recommendations.
+
+**Input:** $ARGUMENTS — optional flags:
+- `--persona <names>` — comma-separated persona names to analyze. Default: all personas.
+- `--verbose` — show full attribute lists in output (default: summarized).
+- `--format json` — emit the drift report as JSON instead of Markdown.
+
+---
+
+## Phase 0: Argument Parsing
+
+Parse `$ARGUMENTS` to set runtime variables.
+
+**Variables to set:**
+
+- `PERSONA_FILTER` — array of lowercased persona names, or `"all"`. Default: `"all"`.
+- `VERBOSE` — boolean. Default: `false`.
+- `FORMAT` — `"markdown"` or `"json"`. Default: `"markdown"`.
+
+**Parsing rules:**
+
+1. Scan `$ARGUMENTS` for `--persona <names>`. If found, split `<names>` on commas, lowercase each, set `PERSONA_FILTER=<array>`. Strip from arguments.
+2. Scan for `--verbose`. If found, set `VERBOSE=true`. Strip from arguments.
+3. Scan for `--format <value>`. If found and value is `json`, set `FORMAT="json"`. Any other value: print `Error: unknown format "<value>". Valid: markdown, json` and stop.
+
+**Print active configuration:**
+
+```
+Analyzing personas: <all | comma-separated list>
+Format: <markdown|json>
+Verbose: <yes|no>
+```
+
+---
+
+## Phase 1: Load VPC Personas
+
+Read the persona files to extract the VPC attribute definitions.
+
+### Step 1a: Discover persona files
+
+Glob for persona files using these paths in order (use the first that yields results):
+
+1. `.claude/agents/` — look for `.md` files whose content includes a `## Value Proposition Canvas` section.
+2. `{{PERSONA_DIR}}/` — project-level persona directory (set by installer).
+
+If no persona files are found in either location:
+
+```
+Error: No VPC persona files found.
+Expected location: .claude/agents/*.md or {{PERSONA_DIR}}/*.md
+Each persona file must contain a ## Value Proposition Canvas section.
+Run /setup to generate persona files from templates.
+```
+
+Stop.
+
+### Step 1b: Parse each persona
+
+For each discovered file, extract:
+
+- `PERSONA_NAME` — from the `# Persona:` heading or frontmatter `name:` field.
+- `PERSONA_ROLE` — from the profile table row `**Name**` (the role portion after "— The ").
+- `JOBS` — rows from the `### Customer Jobs` table. Each row: `{ type, job }`.
+- `PAINS` — rows from the `### Pains` table. Each row: `{ severity, pain }`.
+- `GAINS` — rows from the `### Gains` table. Each row: `{ impact, gain }`.
+
+If `PERSONA_FILTER` is not `"all"`, skip any persona whose lowercased name is not in `PERSONA_FILTER`.
+
+Store parsed personas in `PERSONAS` (array of objects).
+
+**Print after discovery:**
+
+```
+Found <N> persona(s): <Name1> (<Role1>), <Name2> (<Role2>), ...
+```
+
+If `PERSONA_FILTER` was applied and yielded 0 matches:
+
+```
+Error: No personas matched filter: <PERSONA_FILTER>. Check spelling and try again.
+```
+
+Stop.
+
+---
+
+## Phase 2: Load Product Signals
+
+Gather the three signal sources: backlog, implemented features, and agent memory.
+
+### Step 2a: Backlog (requested features)
+
+Load open/pending feature requests — these represent what the product *intends* to deliver.
+
+1. **Cache:** Check whether `.claude/backlog-cache.json` exists and is valid JSON. If so, read all issues from it (`issues` map). Set `BACKLOG_SOURCE="cache"`.
+2. **Live:** If no cache, run:
+   ```bash
+   {{BACKLOG_FETCH_ALL_CMD}}
+   ```
+   If the backlog provider is unavailable, set `BACKLOG_ITEMS=[]` and print:
+   ```
+   Warning: backlog provider unavailable. Backlog signal will be skipped.
+   ```
+3. Parse each backlog item to extract:
+   - `title` — feature name.
+   - `description` — feature description (first 300 chars).
+   - `persona_scores` — per-persona scores from the Overview table (if present). Format: `{ "Alex": 3, "Sara": 5, "Kai": 0 }`.
+   - `area` — from the `area:*` label.
+
+Store in `BACKLOG_ITEMS`. Print: `Backlog loaded: <N> items (source: <cache|live>)`.
+
+### Step 2b: Implemented features
+
+Gather signals about what has *actually been built*.
+
+Run the following in sequence (each is best-effort — continue even if any fails):
+
+**i. Git log (last 90 days):**
+```bash
+git log --oneline --since="90 days ago" --no-merges 2>/dev/null
+```
+Extract commit subjects. Filter out pure chore/docs/test/ci commits (those whose subject starts with `chore:`, `docs:`, `test:`, `ci:`). Store in `COMMIT_MESSAGES`.
+
+**ii. CHANGELOG.md / CHANGELOG:**
+Check whether `CHANGELOG.md` or `CHANGELOG` exists at the repo root. If found, read the last 500 lines. Extract headings and bullet points as feature descriptions. Store in `CHANGELOG_ENTRIES`.
+
+**iii. Closed backlog issues (if GH available):**
+```bash
+{{BACKLOG_FETCH_CLOSED_CMD}}
+```
+Parse closed items the same way as open backlog items. Store in `CLOSED_ITEMS`.
+
+Build `IMPLEMENTED_FEATURES` = array of strings combining `COMMIT_MESSAGES` + `CHANGELOG_ENTRIES` + closed item titles. Deduplicate by lowercased text.
+
+Print: `Implemented signals: <N commits> commits, <N> changelog entries, <N> closed items`.
+
+### Step 2c: Agent memory usage patterns
+
+Check whether `.claude/agent-memory/` exists. If it does, glob all `.md` files within it. For each file:
+- Read the filename and first 200 chars of content.
+- Extract any feature names, tool names, or workflow keywords mentioned.
+
+Store extracted terms in `MEMORY_SIGNALS` (flat string array).
+
+If the directory does not exist or is empty: set `MEMORY_SIGNALS=[]`. Print: `Agent memory: no signals found.`
+
+Otherwise: Print: `Agent memory: <N> signals from <N> files.`
+
+---
+
+## Phase 3: Drift Analysis — Per Persona
+
+For each persona in `PERSONAS`, perform a full alignment analysis.
+
+### Step 3a: Build a feature corpus
+
+Create a combined text corpus:
+```
+CORPUS = BACKLOG_ITEMS titles + descriptions
+       + IMPLEMENTED_FEATURES
+       + MEMORY_SIGNALS
+```
+
+### Step 3b: Attribute matching
+
+For each VPC attribute (Job, Pain, Gain), determine whether it is *addressed* by the corpus.
+
+**Matching rule:** An attribute is considered addressed if at least one corpus entry contains 2+ meaningful keyword matches from the attribute text. Use semantic matching (synonyms count — e.g., "slow" matches "latency", "performance"). If exact matching is insufficient, use AI-assisted reasoning to determine relevance.
+
+For each attribute, record:
+- `addressed` — boolean: is this attribute addressed?
+- `matched_by` — array of corpus items (up to 3) that most strongly address it.
+- `match_confidence` — `"strong"` (3+ keywords or explicit mention), `"weak"` (2 keywords, indirect), `"none"`.
+
+### Step 3c: Compute alignment scores
+
+```
+JOBS_ADDRESSED   = count(jobs where addressed=true)
+PAINS_RELIEVED   = count(pains where addressed=true)
+GAINS_CREATED    = count(gains where addressed=true)
+
+JOBS_SCORE       = JOBS_ADDRESSED / total_jobs  (0.0–1.0)
+PAINS_SCORE      = PAINS_RELIEVED / total_pains (0.0–1.0)
+GAINS_SCORE      = GAINS_CREATED / total_gains  (0.0–1.0)
+
+OVERALL_SCORE    = (JOBS_SCORE + PAINS_SCORE + GAINS_SCORE) / 3
+```
+
+If a category has 0 attributes (e.g., no pains defined): exclude it from the OVERALL_SCORE denominator.
+
+### Step 3d: Classify drift level
+
+| Overall Score | Drift Level |
+|---------------|-------------|
+| ≥ 0.80        | Low         |
+| 0.60–0.79     | Medium      |
+| 0.40–0.59     | High        |
+| < 0.40        | Critical    |
+
+### Step 3e: Identify drifted attributes
+
+A VPC attribute is **drifted** when `addressed=false`.
+
+Rank drifted attributes by severity/impact weight:
+- Pains with severity `critical` → weight 3
+- Pains with severity `high` or Jobs/Gains with impact `high` → weight 2
+- All others → weight 1
+
+Sort drifted attributes by weight descending.
+
+### Step 3f: Identify misaligned backlog items
+
+A backlog item is **misaligned** for this persona when:
+1. The item's `persona_scores` gives this persona a score of 0, AND
+2. The item's description does not match any of this persona's VPC attributes (by the same matching rule as Step 3b).
+
+OR when the item has no persona score data at all and its description does not semantically relate to any of this persona's Jobs/Pains/Gains.
+
+### Step 3g: Generate VPC update recommendations
+
+For each drifted attribute (weight ≥ 2), produce a concrete recommendation:
+
+- If many features address a *different* pain than what's defined: "Consider updating the `<Pain>` attribute to reflect the observed pattern: [observed pattern]."
+- If a Job is completely unaddressed across the product: "Either prioritize features addressing `<Job>`, or remove it from the VPC if no longer relevant."
+- If a Gain is partially addressed: "Strengthen the `<Gain>` attribute description to capture the nuance being delivered by [feature(s)]."
+
+Limit to top 5 recommendations per persona, sorted by weight descending.
+
+Store per-persona results in `PERSONA_DRIFT` array.
+
+---
+
+## Phase 4: Detect Cross-Persona Patterns
+
+After all per-persona analyses are complete, look for systemic patterns.
+
+**Over-represented persona:** If one persona's backlog items make up > 60% of total items, flag it:
+```
+⚠️  Over-representation detected: <PersonaName> drives <N>% of backlog items.
+    This may indicate under-investment in other personas' pain points.
+```
+
+**Under-served persona:** If a persona's OVERALL_SCORE < 0.40:
+```
+🚨  Critical drift for <PersonaName>: only <N>% of their VPC attributes are being addressed.
+```
+
+**Orphan backlog items:** Items with no persona scores at all (neither from score data nor semantic matching). Count them. If > 20% of total backlog, flag:
+```
+⚠️  <N> backlog items (<N>%) have no clear persona linkage.
+    Consider running /sr:update-product-driven-backlog to re-evaluate them.
+```
+
+Store in `CROSS_PERSONA_FINDINGS`.
+
+---
+
+## Phase 5: Build and Render Drift Report
+
+### If FORMAT = "json"
+
+Emit a single JSON object:
+
+```json
+{
+  "schema_version": "1",
+  "project": "{{PROJECT_NAME}}",
+  "generated_at": "<ISO 8601 timestamp>",
+  "personas": [
+    {
+      "name": "<PersonaName>",
+      "role": "<Role>",
+      "drift_level": "<Low|Medium|High|Critical>",
+      "scores": {
+        "jobs": <0.0–1.0>,
+        "pains": <0.0–1.0>,
+        "gains": <0.0–1.0>,
+        "overall": <0.0–1.0>
+      },
+      "drifted_attributes": [
+        { "category": "<job|pain|gain>", "text": "...", "weight": <1|2|3> }
+      ],
+      "misaligned_items": ["<title>", ...],
+      "recommendations": ["..."]
+    }
+  ],
+  "cross_persona_findings": ["..."],
+  "summary": {
+    "total_personas": <N>,
+    "critical": <N>,
+    "high": <N>,
+    "medium": <N>,
+    "low": <N>
+  }
+}
+```
+
+Stop after emitting JSON.
+
+### If FORMAT = "markdown"
+
+Render the full drift report:
+
+```
+## VPC Persona Drift Report — {{PROJECT_NAME}}
+Generated: <YYYY-MM-DD HH:MM> | Backlog: <N> items | Implemented signals: <N>
+
+### Summary
+
+| Persona | Role | Jobs | Pains | Gains | Overall | Drift Level |
+|---------|------|------|-------|-------|---------|-------------|
+| <Name>  | <Role> | <N%> | <N%> | <N%> | <N%>  | 🟢 Low / 🟡 Medium / 🟠 High / 🔴 Critical |
+
+<for each CROSS_PERSONA_FINDING: render the warning/flag block>
+
+---
+```
+
+Then for each persona:
+
+```
+### Persona: <Name> — <Role>
+
+**Drift Level:** 🟢/🟡/🟠/🔴 <Level> | **Alignment: <N>%** (Jobs: <N>%, Pains: <N>%, Gains: <N>%)
+
+#### ✅ Addressed Attributes (<N> of <total>)
+
+<if VERBOSE=true:>
+| Category | Attribute | Confidence | Matched by |
+|----------|-----------|------------|------------|
+| Job      | <text>    | Strong     | <feature1>, <feature2> |
+| Pain     | <text>    | Weak       | <feature1> |
+
+<if VERBOSE=false:>
+- **Jobs**: <N> of <total> addressed
+- **Pains**: <N> of <total> relieved
+- **Gains**: <N> of <total> created
+
+#### ⚠️ Drifted Attributes (<N> unaddressed)
+
+| Category | Attribute | Severity/Impact | Weight |
+|----------|-----------|-----------------|--------|
+| Pain     | <text>    | critical        | ●●●    |
+| Job      | <text>    | high            | ●●     |
+| Gain     | <text>    | medium          | ●      |
+
+<if no drifted attributes:>
+_No drifted attributes — all VPC definitions are reflected in the product._
+
+#### ❌ Misaligned Backlog Items (<N> items)
+
+<if items exist:>
+| # | Title | Persona Score | Why Misaligned |
+|---|-------|---------------|----------------|
+| <number> | <title> | 0/5 | No matching VPC attribute |
+
+<if no items:>
+_All backlog items have clear VPC alignment for this persona._
+
+#### 💡 Recommended VPC Updates
+
+<numbered list of up to 5 recommendations>
+
+---
+```
+
+After all personas:
+
+```
+### Next Steps
+
+1. Review drifted attributes and decide: **update VPC** (if the product has legitimately evolved) or **add backlog items** (if the persona's needs are being neglected).
+2. Run `/sr:update-product-driven-backlog` after updating personas to regenerate aligned feature ideas.
+3. Re-run `/sr:vpc-drift` after one sprint to measure improvement.
+
+_Generated by `/sr:vpc-drift` in {{PROJECT_NAME}} on <ISO date>_
+```
+
+---
+
+## Phase 6: Save Snapshot (optional)
+
+After rendering, write a drift snapshot to `.claude/health-history/`:
+
+1. Filename: `vpc-drift-<YYYY-MM-DD>.json`
+2. Directory: `.claude/vpc-drift-history/` (create if absent, idempotent).
+3. Content: the same JSON object described in Phase 5 (regardless of FORMAT setting).
+
+Print: `Snapshot saved: .claude/vpc-drift-history/vpc-drift-<YYYY-MM-DD>.json`
+
+If the write fails: print `Warning: could not write drift snapshot. Continuing.` Do not abort.
+
+**Housekeeping:** If `.claude/vpc-drift-history/` has more than 30 `.json` files, print:
+```
+Note: .claude/vpc-drift-history/ has <N> snapshots. Prune old ones with:
+  ls -t .claude/vpc-drift-history/ | tail -n +31 | xargs -I{} rm .claude/vpc-drift-history/{}
+```