specrails-core 1.2.0 → 1.4.0

package/README.md

@@ -219,6 +219,18 @@ specrails-core is stack-agnostic — the setup wizard reads your actual files an
 **Can I customize the agents after installation?**
 Yes. Files in `.claude/` are plain markdown — edit agent personalities, adjust CI commands, add rules, create personas.
 
+**How do I customize an agent's personality?**
+Each agent template (`sr-architect`, `sr-developer`, `sr-reviewer`) includes a `## Personality` section with four configurable settings:
+
+| Setting | Options | What it controls |
+|---|---|---|
+| `tone` | `terse` / `verbose` | How much explanation the agent includes in its output |
+| `risk_tolerance` | `conservative` / `aggressive` | How cautious the agent is when making decisions |
+| `detail_level` | `summary` / `full` | Granularity of output artifacts and reports |
+| `focus_areas` | comma-separated keywords | Areas the agent prioritizes (e.g. `security, performance`) |
+
+After running `/setup`, edit `.claude/agents/sr-architect.md` (or `sr-developer.md` / `sr-reviewer.md`) and change the values inline. Existing setups without a `## Personality` section continue to work unchanged — defaults apply.
+
 **Can I re-run setup?**
 Run `npx specrails-core@latest init --root-dir <path>` again to re-scaffold, then `/setup`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "1.2.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/agents/sr-architect.md

@@ -8,6 +8,31 @@ memory: project
 
 You are a world-class software architect with over 20 years of experience designing and building complex systems. Your greatest strength lies not just in writing code, but in translating product vision into pristine technical designs, actionable implementation plans, and well-organized task breakdowns.
 
+## Personality
+
+<!-- Customize this section in `.claude/agents/sr-architect.md` to change how this agent behaves.
+     All settings are optional — omitting them falls back to the defaults shown here. -->
+
+**tone**: `verbose`
+Controls response verbosity and level of explanation.
+- `terse` — emit only what is essential; skip preamble, examples, and elaboration
+- `verbose` — full explanations, examples, and context (default)
+
+**risk_tolerance**: `conservative`
+How cautious to be when making architectural and design decisions.
+- `conservative` — prefer proven patterns, flag all uncertainties, avoid experimental approaches (default)
+- `aggressive` — favor bold, modern approaches; accept more ambiguity; optimize for speed over safety
+
+**detail_level**: `full`
+Granularity of output artifacts (designs, task breakdowns, compatibility reports).
+- `summary` — high-level overview only; skip implementation minutiae
+- `full` — complete, actionable detail in every section (default)
+
+**focus_areas**: _(none — all areas equally weighted)_
+Comma-separated areas to prioritize in analysis and recommendations.
+Examples: `security`, `performance`, `testing`, `scalability`, `api-design`, `database`
+Leave empty to give equal weight to all areas.
+
 ## Your Identity
 
 You are the kind of architect who can sit in a room with a product owner, fully grasp their intent — even when it's vaguely expressed — and produce a design document that makes engineers say "this is exactly what we need to build." You think in systems, communicate in clarity, and organize in precision.

package/templates/agents/sr-developer.md

@@ -8,6 +8,31 @@ memory: project
 
 You are an elite full-stack software engineer. You possess deep mastery across the entire software development stack. You are the agent that gets called when OpenSpec changes need to be applied — turning specifications into flawless, production-grade code.
 
+## Personality
+
+<!-- Customize this section in `.claude/agents/sr-developer.md` to change how this agent behaves.
+     All settings are optional — omitting them falls back to the defaults shown here. -->
+
+**tone**: `verbose`
+Controls response verbosity and level of inline explanation.
+- `terse` — emit only code and essential notes; skip rationale and elaboration
+- `verbose` — explain implementation decisions and architectural choices as you go (default)
+
+**risk_tolerance**: `conservative`
+How cautious to be when choosing implementation approaches and handling edge cases.
+- `conservative` — prefer battle-tested patterns, add defensive checks, flag unknowns before proceeding (default)
+- `aggressive` — favor concise, modern approaches; skip defensive boilerplate; move fast
+
+**detail_level**: `full`
+Granularity of implementation output and verification reports.
+- `summary` — show only changed files with a brief description of each change
+- `full` — show every file created or modified with complete implementation context (default)
+
+**focus_areas**: _(none — all areas equally weighted)_
+Comma-separated areas to prioritize when making implementation trade-offs.
+Examples: `security`, `performance`, `testing`, `accessibility`, `error-handling`, `type-safety`
+Leave empty to give equal weight to all areas.
+
 ## Your Identity & Expertise
 
 You are a polyglot engineer with extraordinary depth in:

package/templates/agents/sr-reviewer.md

@@ -8,6 +8,31 @@ memory: project
 
 You are a meticulous code reviewer and CI/CD quality gate. Your job is to catch every issue that would fail in the CI pipeline BEFORE pushing code. You run the exact same checks as CI, fix problems, and ensure the code is production-ready.
 
+## Personality
+
+<!-- Customize this section in `.claude/agents/sr-reviewer.md` to change how this agent behaves.
+     All settings are optional — omitting them falls back to the defaults shown here. -->
+
+**tone**: `terse`
+Controls verbosity of review output and issue descriptions.
+- `terse` — report findings concisely; one line per issue; skip elaboration (default)
+- `verbose` — explain every finding, its root cause, and the fix rationale in full
+
+**risk_tolerance**: `conservative`
+How strictly to apply quality and security standards.
+- `conservative` — flag all warnings, block on any security or correctness concern (default)
+- `aggressive` — block only on hard failures; treat warnings as advisory; allow ambiguous patterns through
+
+**detail_level**: `full`
+Granularity of the final review report.
+- `summary` — pass/fail table only; omit per-file findings and fixed-file lists
+- `full` — complete report with CI check table, issues fixed, layer findings, and modified files (default)
+
+**focus_areas**: _(none — all areas equally weighted)_
+Comma-separated areas to apply extra scrutiny during review.
+Examples: `security`, `performance`, `test-coverage`, `accessibility`, `sql-injection`, `types`
+Leave empty to review all areas with equal weight.
+
 ## Your Mission
 
 You are the last line of defense between developer output and a PR. You:

package/templates/commands/sr/implement.md

@@ -182,6 +182,65 @@ If neither pattern is found, print:
 
 This advisory is non-blocking and suppressed when `.gitignore` already covers the file.
 
+#### Pipeline state initialization
+
+Set `PIPELINE_STATE_PATH=.claude/pipeline-state/<feature-name>.json` (use the same kebab-case feature name derived above).
+
+Create the directory if it does not exist:
+
+```bash
+mkdir -p .claude/pipeline-state
+```
+
+Write the initial state file:
+
+```json
+{
+  "schema_version": "1",
+  "feature": "<feature-name>",
+  "started_at": "<current ISO 8601 timestamp>",
+  "updated_at": "<current ISO 8601 timestamp>",
+  "phases": {
+    "architect": "pending",
+    "developer": "pending",
+    "test-writer": "pending",
+    "doc-sync": "pending",
+    "reviewer": "pending",
+    "ship": "pending",
+    "ci": "pending"
+  },
+  "last_successful_phase": null,
+  "failed_phase": null,
+  "error_context": null,
+  "openspec_artifacts": "openspec/changes/<feature-name>/",
+  "implemented_files": [],
+  "input": {
+    "issues": [<issue numbers, or null for text-description mode>],
+    "flags": {
+      "dry_run": <DRY_RUN>,
+      "apply_mode": <APPLY_MODE>,
+      "single_mode": <SINGLE_MODE>
+    }
+  }
+}
+```
+
+If the write fails: print `[pipeline-state] Warning: could not write state file. Smart retry (/sr:retry) will not be available for this run.` Set `PIPELINE_STATE_AVAILABLE=false`. Do NOT abort the pipeline.
+
+If the write succeeds: set `PIPELINE_STATE_AVAILABLE=true`.
+
+**State update helper** — used by all subsequent phases to record progress:
+
+When a phase completes or fails, update `PIPELINE_STATE_PATH`:
+1. Read the current file.
+2. Set `phases.<phase-key>` to `"done"`, `"failed"`, or `"skipped"`.
+3. If `"done"`: set `last_successful_phase` to the phase key.
+4. If `"failed"`: set `failed_phase` to the phase key; set `error_context` to a one-line description of the failure (agent name, error type, exit code if known).
+5. Set `updated_at` to the current ISO 8601 timestamp.
+6. Overwrite the file.
+
+If `PIPELINE_STATE_AVAILABLE=false`: skip all state updates silently.
+
 **If the user passed area names**:
 - Check for open backlog issues. If found, filter and pick top 3.
 - If none, proceed to Phase 1.
@@ -331,6 +390,8 @@ Quick-check each architect's artifacts:
 3. File references are real (>70% must exist)
 4. Layer tags present on tasks
 
+**Pipeline state:** update `architect` → `done`. If any architect agent failed (skipped area): update `architect` → `failed` with error context `"sr-architect failed for: <area-names>"`.
+
 ## Phase 3b: Implement
 
 ### Pre-flight: Verify Bash permission
@@ -371,6 +432,8 @@ For each feature, analyze the tasks' layer tags:
 
 Wait for all developers to complete.
 
+**Pipeline state:** update `developer` → `done`. Also update `implemented_files` in the state file with the complete list of files created or modified by the developer agent(s). If developer failed: update `developer` → `failed` with error context `"sr-developer failed: <exit code or error description>"`.
+
 ## Phase 3c: Write Tests
 
 Launch a **sr-test-writer** agent for each feature immediately after its developer completes.
@@ -403,6 +466,8 @@ If a test-writer agent fails or times out:
 - Continue to Phase 4 — the sr-test-writer failure is non-blocking
 - Include in the reviewer agent prompt: "Note: the sr-test-writer failed for this feature. Check for coverage gaps."
 
+**Pipeline state:** update `test-writer` → `done` (or `failed` with error context `"sr-test-writer timed out or errored"`). Failure does not block the pipeline.
+
 ## Phase 3d: Doc Sync
 
 Launch a **sr-doc-sync** agent for each feature after its tests are written.
@@ -435,6 +500,8 @@ If a doc-sync agent fails or times out:
 - Continue to Phase 4 — the sr-doc-sync failure is non-blocking
 - Include in the reviewer agent prompt: "Note: the sr-doc-sync agent failed for this feature."
 
+**Pipeline state:** update `doc-sync` → `done` (or `failed` with error context `"sr-doc-sync timed out or errored"`). Failure does not block the pipeline.
+
 ## Phase 4: Merge & Review
 
 **This phase is fully autonomous.**
@@ -610,6 +677,8 @@ Note: if total layer report length is very large, truncate each layer report to
 
 Launch the **sr-reviewer** agent (foreground, `run_in_background: false`). Wait for it to complete.
 
+**Pipeline state:** update `reviewer` → `done` (or `failed` with error context `"sr-reviewer timed out or did not complete"` if the agent errored out).
+
 **If `DRY_RUN=true`**, add the following to the reviewer agent prompt:
 
 > Note: This is a dry-run review. Developer files are under .claude/.dry-run/\<feature-name\>/.
@@ -838,12 +907,16 @@ All implementation is complete and CI checks pass.
   | #71 / PROJ-71 | Partial progress | Comment: "X completed, Y remaining" |
   ```
 
+**Pipeline state:** update `ship` → `done` if git operations and PR creation succeeded, or `failed` with error context describing which step failed (e.g. `"git push failed: <exit code>"`, `"gh pr create failed"`, `"security gate blocked ship"`). If `DRY_RUN=true`: update `ship` → `skipped`.
+
 ### 4d. Monitor CI
 
 **Only if `GIT_AUTO=true` and code was pushed.**
 
 Check CI status after pushing. Fix failures (up to 2 retries).
 
+**Pipeline state:** update `ci` → `done` if CI passed, or `failed` with error context `"CI failed after 2 retries: <summary>"`. If CI was not run (`GIT_AUTO=false` or dry-run): update `ci` → `skipped`.
+
 If `GIT_AUTO=false`: skip — the user will push and monitor CI themselves.
 
 ### 4e. Report

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/retry.md

@@ -0,0 +1,363 @@
+---
+name: "Smart Failure Recovery"
+description: "Resume a failed /sr:implement pipeline from the last successful phase without restarting from scratch."
+category: Workflow
+tags: [workflow, recovery, retry, resilience]
+phases:
+  - key: load
+    label: Load State
+    description: "Read pipeline state from disk and identify the resume point"
+  - key: resume
+    label: Resume
+    description: "Execute remaining phases starting from the failed phase"
+  - key: report
+    label: Report
+    description: "Print a final status report with outcomes and next steps"
+---
+
+Resume a failed `/sr:implement` run for **{{PROJECT_NAME}}**. Reads pipeline state written by the implement pipeline to identify which phases completed and which failed, then re-executes only the remaining phases.
+
+**MANDATORY: Follow this pipeline exactly. Do NOT skip phases or re-run phases that already succeeded. Read all context from the pipeline state file — do not rely on memory. Do not re-implement anything yourself; delegate to the same agents used by `/sr:implement`.**
+
+**Input:** $ARGUMENTS — accepted forms:
+
+1. `<feature-name>` — kebab-case feature name matching a `.claude/pipeline-state/<feature-name>.json` file
+2. `--list` — list all available pipeline state files and their current status, then exit
+3. `<feature-name> --from <phase>` — force resume from a specific phase (overrides auto-detection)
+4. `<feature-name> --dry-run` — override to resume in dry-run mode (no git/PR operations)
+
+---
+
+## Phase 0: Parse Input
+
+Scan `$ARGUMENTS` for flags:
+
+- `--list`: if present, set `LIST_ONLY=true`.
+- `--from <phase>`: if present, set `RESUME_FROM_OVERRIDE=<phase>`. Valid values: `architect`, `developer`, `test-writer`, `doc-sync`, `reviewer`, `ship`, `ci`.
+- `--dry-run`: if present, set `DRY_RUN_OVERRIDE=true`.
+
+Extract the first positional argument (not starting with `--`) as `FEATURE_NAME`.
+
+**If `--list`:** scan `.claude/pipeline-state/*.json`. For each file found, parse and print:
+
+```
+## Available Pipeline States
+
+| Feature | Last Successful Phase | Failed Phase | Updated At |
+|---------|----------------------|--------------|------------|
+| <name>  | <phase or —>         | <phase or —> | <ISO time> |
+```
+
+If no files found: print `No pipeline state files found. Run /sr:implement first.`
+
+Exit after printing — do not proceed.
+
+**If no positional argument and no `--list`:** print the following usage and exit:
+
+```
+Usage: /sr:retry <feature-name> [--from <phase>] [--dry-run]
+       /sr:retry --list
+
+Phases: architect | developer | test-writer | doc-sync | reviewer | ship | ci
+```
+
+---
+
+## Phase 1: Load Pipeline State
+
+Read: `.claude/pipeline-state/<FEATURE_NAME>.json`
+
+If the file does not exist:
+
+```
+[retry] Error: no pipeline state found for "<FEATURE_NAME>".
+
+Run /sr:retry --list to see available states, or start a new run:
+  /sr:implement <your input>
+```
+
+Exit.
+
+Parse the state file and set the following variables:
+
+- `LAST_SUCCESSFUL_PHASE` ← `last_successful_phase` (may be `null`)
+- `FAILED_PHASE` ← `failed_phase` (may be `null`)
+- `ERROR_CONTEXT` ← `error_context` (may be `null`)
+- `OPENSPEC_ARTIFACTS` ← `openspec_artifacts` (e.g. `openspec/changes/<name>/`)
+- `IMPLEMENTED_FILES` ← `implemented_files` (array, may be empty)
+- `ORIGINAL_ISSUES` ← `input.issues` (array of issue numbers, may be `null`)
+- `ORIGINAL_INPUT_FLAGS` ← `input.flags` object
+- `SINGLE_MODE` ← `input.flags.single_mode` (default `true`)
+- `DRY_RUN` ← if `DRY_RUN_OVERRIDE=true` then `true`, else `input.flags.dry_run` (default `false`)
+- `PHASE_STATUSES` ← `phases` map (`architect`, `developer`, `test-writer`, `doc-sync`, `reviewer`, `ship`, `ci` → `"done"`, `"failed"`, `"skipped"`, or `"pending"`)
+
+**Validation:**
+
+- If all phases are `"pending"`: the pipeline never reached any execution. Print:
+  ```
+  [retry] Warning: all phases are pending — the pipeline may not have started.
+  Recommend running /sr:implement instead.
+  ```
+  Prompt: `Proceed anyway? [y/N]`. If `n` or no response: exit.
+
+---
+
+## Phase 2: Status Report
+
+Print the pipeline status:
+
+```
+## Pipeline State: <FEATURE_NAME>
+
+| Phase        | Status  | Notes                              |
+|--------------|---------|-------------------------------------|
+| architect    | done    |                                     |
+| developer    | done    |                                     |
+| test-writer  | FAILED  | <ERROR_CONTEXT or "no details">     |
+| doc-sync     | pending |                                     |
+| reviewer     | pending |                                     |
+| ship         | pending |                                     |
+| ci           | pending |                                     |
+
+Last successful phase : <LAST_SUCCESSFUL_PHASE or "none">
+Failed phase          : <FAILED_PHASE or "—">
+Error context         : <ERROR_CONTEXT or "no details recorded">
+OpenSpec artifacts    : <OPENSPEC_ARTIFACTS>
+Implemented files     : <count> file(s) tracked
+Original input        : <issues list or "text description">
+```
+
+---
+
+## Phase 3: Determine Resume Point
+
+**Phase execution order (canonical):**
+
+```
+architect → developer → test-writer → doc-sync → reviewer → ship → ci
+```
+
+**If `RESUME_FROM_OVERRIDE` is set:** use it as `RESUME_PHASE`. Validate it is one of the canonical values; if not, print an error and exit.
+
+**Otherwise, auto-detect:**
+
+1. If `FAILED_PHASE` is set: `RESUME_PHASE = FAILED_PHASE`.
+2. Else if `LAST_SUCCESSFUL_PHASE` is set: `RESUME_PHASE` = the next phase after `LAST_SUCCESSFUL_PHASE` in canonical order.
+3. Else: `RESUME_PHASE = architect` (no phases completed).
+
+Print the resume plan:
+
+```
+## Resume Plan
+
+Resuming from phase: <RESUME_PHASE>
+
+Phases to skip (already done):
+  ✓ <phase>   (done)
+  ✓ <phase>   (done)
+
+Phases to execute:
+  ► <RESUME_PHASE>    (resuming here)
+  · <next-phase>
+  · <next-phase>
+  ...
+```
+
+Prompt the user:
+
+```
+Proceed? [Y/n]
+```
+
+If `n` or no response: exit without changes.
+
+---
+
+## Phase 4: Execute Remaining Phases
+
+Execute phases in canonical order starting from `RESUME_PHASE`. For each phase:
+
+- If its status in `PHASE_STATUSES` is `"done"` AND it precedes `RESUME_PHASE` in canonical order: **skip** — do not re-run.
+- If it equals `RESUME_PHASE` or comes after: **run** it.
+
+After each phase completes (or fails), update `.claude/pipeline-state/<FEATURE_NAME>.json`:
+1. Read the current file.
+2. Set `phases.<phase-key>` to `"done"` or `"failed"`.
+3. If `"done"`: update `last_successful_phase`.
+4. If `"failed"`: update `failed_phase` and `error_context`.
+5. Update `updated_at` to current ISO 8601 timestamp.
+6. Overwrite the file.
+
+---
+
+### 4a. Phase: architect
+
+**Only runs if `RESUME_PHASE=architect`.**
+
+Verify that `ORIGINAL_ISSUES` is non-empty or a text description is recoverable. If neither is available: print an error and stop — the original input is required to re-run the architect.
+
+Launch **sr-architect** agent(s) exactly as described in Phase 3a of the implement pipeline. Pass:
+- Original issue numbers from `ORIGINAL_ISSUES` (or text description if stored in state)
+- Same OpenSpec output directory: `OPENSPEC_ARTIFACTS`
+
+Wait for all architects to complete.
+
+**Pipeline state update:** `architect` → `done` or `failed`.
+
+---
+
+### 4b. Phase: developer
+
+**Runs if `RESUME_PHASE` is `architect` or `developer`.**
+
+Before launching, verify architect artifacts exist:
+
+```bash
+ls <OPENSPEC_ARTIFACTS>tasks.md <OPENSPEC_ARTIFACTS>context-bundle.md
+```
+
+If missing and `RESUME_PHASE=developer`: print:
+
+```
+[retry] Error: architect artifacts not found at <OPENSPEC_ARTIFACTS>.
+Retry from the architect phase: /sr:retry <FEATURE_NAME> --from architect
+```
+
+Stop.
+
+Launch **sr-developer** agent(s) exactly as described in Phase 3b of the implement pipeline.
+
+- If `SINGLE_MODE=true`: launch in main repo, foreground.
+- If `SINGLE_MODE=false`: launch in isolated worktrees, background.
+- If `DRY_RUN=true`: use the dry-run redirect instructions from Phase 3b.
+
+Wait for all developers to complete. Collect the list of files created or modified.
+
+**Pipeline state update:** `developer` → `done` (also update `implemented_files` in state with the collected file list) or `failed`.
+
+---
+
+### 4c. Phase: test-writer
+
+**Runs if `RESUME_PHASE` is `architect`, `developer`, or `test-writer`.**
+
+If `IMPLEMENTED_FILES` is empty: warn but continue — the sr-test-writer will discover files from git diff.
+
+Launch **sr-test-writer** agent(s) exactly as in Phase 3c of the implement pipeline. Pass:
+- `IMPLEMENTED_FILES_LIST`: the `implemented_files` array from state
+- `TASK_DESCRIPTION`: derived from `ORIGINAL_ISSUES` or architect artifacts
+
+Wait for completion. Failure is **non-blocking** — record `FAILED` and continue to next phase.
+
+**Pipeline state update:** `test-writer` → `done` or `failed`.
+
+---
+
+### 4d. Phase: doc-sync
+
+**Runs if `RESUME_PHASE` is any phase up to and including `doc-sync`.**
+
+Launch **sr-doc-sync** agent(s) exactly as in Phase 3d of the implement pipeline. Pass:
+- `IMPLEMENTED_FILES_LIST`: the `implemented_files` array from state
+- `TASK_DESCRIPTION`: derived from `ORIGINAL_ISSUES` or architect artifacts
+
+Wait for completion. Failure is **non-blocking** — record `FAILED` and continue.
+
+**Pipeline state update:** `doc-sync` → `done` or `failed`.
+
+---
+
+### 4e. Phase: reviewer
+
+**Runs if `RESUME_PHASE` is any phase up to and including `reviewer`.**
+
+Launch layer reviewers and the generalist sr-reviewer exactly as in Phase 4b of the implement pipeline. Pass:
+- `MODIFIED_FILES_LIST`: the `implemented_files` array from state
+- `PIPELINE_CONTEXT`: brief description from original input and issue titles
+- Layer reports from sr-frontend-reviewer, sr-backend-reviewer, sr-security-reviewer
+
+Wait for all to complete. Parse `SECURITY_BLOCKED`, `FRONTEND_STATUS`, `BACKEND_STATUS`.
+
+**Run the Confidence Gate (Phase 4b-conf)** exactly as defined in the implement pipeline.
+
+**Pipeline state update:** `reviewer` → `done` or `failed`.
+
+---
+
+### 4f. Phase: ship
+
+**Runs if `RESUME_PHASE` is `ship` or `ci`.**
+
+If `DRY_RUN=true`: skip git operations. Record skipped operations, print dry-run summary, proceed to Phase 5.
+
+Otherwise, run Phase 4c (ship) of the implement pipeline exactly as defined:
+- Security gate check (`SECURITY_BLOCKED`)
+- Conflict pre-check (Phase 4c.0)
+- Git branch creation, commit, push, PR creation
+- Backlog updates
+
+**Pipeline state update:** `ship` → `done` or `failed`.
+
+---
+
+### 4g. Phase: ci
+
+**Runs if ship succeeded and code was pushed.**
+
+Run Phase 4d (CI monitoring) of the implement pipeline exactly as defined. Check CI status, fix failures (up to 2 retries).
+
+**Pipeline state update:** `ci` → `done` or `failed`.
+
+---
+
+## Phase 5: Report
+
+Print the final report:
+
+```
+## Retry Complete: <FEATURE_NAME>
+
+Resumed from: <RESUME_PHASE>
+Phases executed this run: <comma-separated list>
+
+| Phase        | Status  |
+|--------------|---------|
+| architect    | done    |
+| developer    | done    |
+| test-writer  | done    |
+| doc-sync     | done    |
+| reviewer     | done    |
+| ship         | done    |
+| ci           | done    |
+```
+
+Include PR URL if ship ran successfully.
+
+**If any phase failed**, add:
+
+```
+## Failures
+
+| Phase       | Error Context          |
+|-------------|------------------------|
+| <phase>     | <error_context>        |
+
+Next steps:
+- To retry from the failed phase: /sr:retry <FEATURE_NAME> --from <failed-phase>
+- To see all pipeline states: /sr:retry --list
+- To restart from scratch: /sr:implement <original-input>
+```
+
+---
+
+## Error Handling
+
+| Phase | Blocking? | On failure |
+|-------|-----------|------------|
+| architect | **Yes** | Stop — cannot proceed without OpenSpec artifacts |
+| developer | **Yes** | Stop — cannot proceed without implemented files |
+| test-writer | No | Record FAILED, continue to doc-sync |
+| doc-sync | No | Record FAILED, continue to reviewer |
+| reviewer | No | Report findings, continue to ship |
+| ship | **Yes** | Stop — report failure with git/PR context |
+| ci | **Yes** | Stop — report failure with CI log and fix suggestions |

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/{}
+```