prr-kit 1.3.0 → 1.4.0

package/README.md

@@ -38,9 +38,137 @@ Then open your IDE in the installed project and use one of these commands to sta
 
 ## How It Works
 
-<p align="center">
-  <img src="docs/assets/how-it-works.svg" alt="How It Works" width="100%"/>
-</p>
+```
+┌─────────────────────────────────────────────────────────┐
+│                    /prr-quick                           │
+│              Load config.yaml                           │
+└───────────────────────┬─────────────────────────────────┘
+                        │
+        ╔═══════════════▼════════════════╗
+        ║       PHASE 1 — SELECT PR      ║
+        ╚═══════════════╤════════════════╝
+                        │
+             ┌──────────▼──────────┐
+             │ 1a. git fetch origin │
+             └──────────┬──────────┘
+                        │
+             ┌──────────▼───────────────┐
+             │ 1b. List open PRs/MRs    │
+             │     + recent branches    │
+             └──────────┬───────────────┘
+                        │
+             ┌──────────▼───────────────┐
+             │ 1c. ⌨️  Select PR/branch  │  ← USER INPUT
+             │     Enter PR# or name    │
+             └──────────┬───────────────┘
+                        │
+             ┌──────────▼──────────┐
+             │ 1d. Load diff        │
+             │     count files/lines│
+             └──────────┬──────────┘
+                        │
+             ┌──────────▼──────────────────────────┐
+             │ 1e. Create session folder            │
+             │     {output}/{date}-{slug}/          │
+             └──────────┬──────────────────────────┘
+                        │
+             ┌──────────▼──────────────────────────┐
+             │ 1f. Generate diffs/ folder           │
+             │     one .md per changed file         │
+             └──────────┬──────────────────────────┘
+                        │
+        ╔═══════════════▼════════════════╗
+        ║      PHASE 2 — DESCRIBE PR     ║
+        ╚═══════════════╤════════════════╝
+                        │
+             ┌──────────▼──────────────┐
+             │ 2a. Classify PR type     │
+             │     bugfix/feature/...   │
+             └──────────┬──────────────┘
+                        │
+             ┌──────────▼──────────────┐
+             │ 2b. File-by-file         │
+             │     walkthrough          │
+             └──────────┬──────────────┘
+                        │
+             ┌──────────▼──────────────┐
+             │ 2c. Print PR description │
+             └──────────┬──────────────┘
+                        │
+        ╔═══════════════▼═══════════════════════╗
+        ║   PHASE 2.5 — COLLECT PR CONTEXT      ║
+        ╚═══════════════╤═══════════════════════╝
+                        │
+             ┌──────────▼──────────────────────────┐
+             │ Step 1. Analyze changed files        │
+             │  detect stacks, domains, file types  │
+             └──────────┬──────────────────────────┘
+                        │
+             ┌──────────▼──────────────────────────┐
+             │ Step 2. Collect context from:        │
+             │  CLAUDE.md · CONTRIBUTING.md         │
+             │  .eslintrc · tsconfig · pyproject    │
+             │  ARCHITECTURE.md · docs/**           │
+             │  @context/@security annotations      │
+             │  stack rules (vue3/react/django/...)  │
+             │  MCP tools · RAG · URL sources       │
+             └──────────┬──────────────────────────┘
+                        │
+             ┌──────────▼──────────────────────────┐
+             │ Step 3. ⌨️  User instructions        │  ← USER INPUT
+             │  scope / focus / requirements /      │
+             │  context — or Enter for full review  │
+             └──────────┬──────────────────────────┘
+                        │
+               ┌────────┴────────┐
+               ▼                 ▼
+          [provided]         [empty]
+        parse scope &      scope = "all"
+        focus/req/ctx      full standard
+               │                 │
+               └────────┬────────┘
+                        │
+             ┌──────────▼──────────────────────────┐
+             │ Step 4. Build pr-context.yaml        │
+             │  all collected context + user_instr  │
+             │  → {session_output}/pr-context.yaml  │
+             └──────────┬──────────────────────────┘
+                        │
+        ╔═══════════════▼════════════════╗
+        ║       PHASE 3 — REVIEW         ║
+        ╚═══════════════╤════════════════╝
+                        │
+             ┌──────────▼──────────────────────────┐
+             │ Scope gate                           │
+             │ read user_instructions.review_scope  │
+             └──────┬───────────────────────────────┘
+                    │
+         ┌──────────┴──────────┐
+    [in scope]           [not in scope]
+         │                     │
+         ▼                     ▼
+  ┌─────────────┐        ⏭️ skipped
+  │  GR · SR    │        (no output file)
+  │  PR · AR    │
+  │     BR      │
+  └──────┬──────┘
+         │
+        ╔▼════════════════════════╗
+        ║  PHASE 4 — REPORT       ║
+        ╚╤════════════════════════╝
+         │
+         │  Compile findings → sort by severity
+         │  🔴 Blockers → 🟡 Warnings
+         │  🟢 Suggestions → ❓ Questions
+         │  Write → final-review.md
+         │
+        ╔▼════════════════════════╗
+        ║  PHASE 5 — DONE         ║
+        ╚╤════════════════════════╝
+         │
+         ├── auto_post_comment: true  → post inline comments automatically
+         └── auto_post_comment: false → ⌨️  type PC to post, Enter to finish
+```
 
 The framework installs into your project as a `_prr/` folder. Agents and workflows are Markdown/YAML files that your AI IDE reads and executes — no server, no background process, no API keys required beyond your IDE's AI.
 
@@ -71,9 +199,6 @@ auto_post_comment: false               # true → auto-post findings after every
 # ─── Context Collection ────────────────────────────────────────────────────
 context_collection:
   enabled: true                        # false → disable context collection entirely
-  skip_manual_input_context: false     # true → skip the manual context input prompt
-                                       # false (default) → agent asks user for additional context
-                                       # before building the knowledge base; input is marked ⚠️ IMPORTANT
   mode: pr-specific                    # only value: pr-specific (always fresh, never cached)
 
   # Sources below are auto-detected — override only if needed:
@@ -139,11 +264,11 @@ external_sources:
 ### Quick mode — one command, full pipeline
 
 ```
-/prr-quick    or    /prr-master → QR
+/prr-quick
 ```
 
-Runs automatically: **select PR → describe → collect context → 5 reviews → generate report**
-Only pauses once to ask which PR/branch to review.
+Runs automatically: **select PR → describe → collect context → review → report**
+Pauses **twice** for user input: once to select the PR/branch, once for review instructions (scope, focus, requirements — or Enter for a full standard review).
 
 ### Manual mode — step by step
 
@@ -218,13 +343,14 @@ All findings use a standard format:
 
 ## Context Collection
 
-After [DP] Describe PR, context is collected **automatically** — no manual step needed:
+After [DP] Describe PR, context is collected **automatically** — then the agent pauses once for your instructions:
 
 1. Analyzes changed files to detect domains (`authentication`, `state-management`, etc.)
 2. Reads relevant config files (`.eslintrc`, `.prettierrc`, `tsconfig.json`) and standards docs (`CONTRIBUTING.md`, `ARCHITECTURE.md`)
 3. Extracts inline `@context:` / `@security:` / `@pattern:` annotations from the diff
 4. Optionally queries **MCP tools** (Confluence, Jira, Figma) and **RAG systems** if configured
-5. Writes `pr-{branch}-context.yaml` — loaded by all reviewers
+5. Asks for **review instructions** — scope (`only security`), focus, requirements, or context. Press Enter for a full standard review
+6. Writes `pr-context.yaml` inside the session folder — loaded by all reviewers
 
 > See [CONFIGURATION.md](CONFIGURATION.md) for MCP intents, RAG setup, and URL sources.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prr-kit",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "AI-driven Pull Request Review Kit — structured agent workflows for thorough, consistent code review",
   "main": "tools/cli/prr-cli.js",
   "bin": {

package/src/core/agents/prr-master.agent.yaml

@@ -82,10 +82,14 @@ agent:
       exec: "{project-root}/_prr/prr/workflows/6-report/post-comments/workflow.md"
       description: "[PC] Post Comments: Post inline review comments to GitHub/GitLab/Azure/Bitbucket PR"
 
+    - trigger: "SS or fuzzy match on select-session or resume-session"
+      exec: "{project-root}/_prr/core/tasks/select-session.md"
+      description: "[SS] Select Session: List past review sessions and resume one"
+
     - trigger: "HH or fuzzy match on help"
       exec: "{project-root}/_prr/core/tasks/help.md"
       description: "[HH] Help: Show review workflow guide and available commands"
 
     - trigger: "CL or fuzzy match on clear or clean or reset"
       exec: "{project-root}/_prr/core/tasks/clear.md"
-      description: "[CL] Clear: Remove context files and/or review reports from output folder"
+      description: "[CL] Clear: Delete one or more past review sessions"

package/src/core/tasks/clear.md

@@ -8,58 +8,41 @@
 
 Read `{project-root}/_prr/prr/config.yaml` to get `review_output` path.
 
-### 2. Scan Output Folder
+### 2. Scan Session Folders
 
-List all files currently in `{review_output}`:
+List all session folders in `{review_output}` (datetime-slug subdirectories):
 
 ```bash
-ls "{review_output}/"
+ls -d "{review_output}"/*/
 ```
 
-Group into three categories:
+Each session folder is named `{YYYY-MM-DD-HHmm}-{slug}` (e.g. `2026-03-02-1430-pr44-feature-auth`).
+Inside each folder are: `pr-context.yaml` (knowledge base) and review `.md` files.
 
-**Context files** (session state + knowledge bases):
-- `current-pr-context.yaml` — active session state (which PR is selected)
-- `pr-*-context.yaml` — per-PR knowledge bases built during context collection
-
-**Intermediate review files** (individual review output, used by [RR] and [PC]):
-- `general-review-*.md`
-- `security-review-*.md`
-- `performance-review-*.md`
-- `architecture-review-*.md`
-- `business-review-*.md`
-- `improve-code-*.md`
-- `pr-description-*.md`
-
-**Review reports** (final compiled reports):
-- `review-*.md` — final review reports generated by [RR]
+Also detect any legacy flat files still directly in `{review_output}/` (pre-session-folder format).
 
 ### 3. Display What Exists
 
-Show the user exactly what will be affected:
+Show the user a summary of each session:
 
 ```
 🗂️ PRR Output — {review_output}
 
-Context files ({n}):
-  • current-pr-context.yaml
-  • pr-feature-auth-...-context.yaml
-  • pr-feature-search-...-context.yaml
-  ... (list all pr-*.yaml)
-
-Intermediate review files ({k}):
-  • general-review-2026-02-21.md
-  • security-review-2026-02-21.md
-  • pr-description-2026-02-21.md
-  ... (list all intermediate review files)
-
-Review reports ({m}):
-  • review-feature-auth-indexeddb-migration-2026-02-21.md
-  • review-feature-add-search-functionality-2026-02-21.md
-  ... (list all review-*.md)
+Session folders ({n}):
+
+  📁 2026-03-02-1430-pr44-feature-auth/
+     Branch: feature/auth  |  PR #44  |  2026-03-02
+     Files: pr-context.yaml, pr-description.md,
+            general-review.md, security-review.md, final-review.md
+
+  📁 2026-03-01-0915-fix-null-pointer/
+     Branch: fix/null-pointer  |  no PR  |  2026-03-01
+     Files: general-review.md
+
+  ... (list all session folders)
 ```
 
-If output folder is already empty or doesn't exist:
+If no session folders exist:
 ```
 ✅ Nothing to clear — output folder is already empty.
 ```
@@ -72,49 +55,32 @@ Ask the user what to clear:
 ```
 What would you like to clear?
 
-  [1] All          — context files + intermediate review files + review reports
-  [2] Context only — clear session state and knowledge bases (keep reports)
-  [3] Reports only — clear intermediate review files + final review reports (keep context)
-  [4] Cancel       — do nothing
+  [1] All sessions      — delete all session folders
+  [2] Select sessions   — choose specific session(s) to delete
+  [3] Cancel            — do nothing
 ```
 
 Wait for user input.
 
-### 5. Execute Deletion
-
-**If [1] All:**
-```bash
-rm -f "{review_output}/current-pr-context.yaml"
-rm -f "{review_output}"/pr-*-context.yaml
-rm -f "{review_output}"/general-review-*.md
-rm -f "{review_output}"/security-review-*.md
-rm -f "{review_output}"/performance-review-*.md
-rm -f "{review_output}"/architecture-review-*.md
-rm -f "{review_output}"/business-review-*.md
-rm -f "{review_output}"/improve-code-*.md
-rm -f "{review_output}"/pr-description-*.md
-rm -f "{review_output}"/review-*.md
+**If [2] Select sessions:** List sessions numbered and ask:
+```
+Which session(s) to delete? (e.g. 1, 3 or 1-3)
 ```
+Wait for response.
+
+### 5. Execute Deletion
 
-**If [2] Context only:**
+**If [1] All sessions:**
 ```bash
-rm -f "{review_output}/current-pr-context.yaml"
-rm -f "{review_output}"/pr-*-context.yaml
+rm -rf "{review_output}"/*/
 ```
 
-**If [3] Reports only:**
+**If [2] Selected sessions:** For each chosen session folder:
 ```bash
-rm -f "{review_output}"/general-review-*.md
-rm -f "{review_output}"/security-review-*.md
-rm -f "{review_output}"/performance-review-*.md
-rm -f "{review_output}"/architecture-review-*.md
-rm -f "{review_output}"/business-review-*.md
-rm -f "{review_output}"/improve-code-*.md
-rm -f "{review_output}"/pr-description-*.md
-rm -f "{review_output}"/review-*.md
+rm -rf "{review_output}/{selected_session_folder}/"
 ```
 
-**If [4] Cancel:**
+**If [3] Cancel:**
 ```
 ❌ Cancelled — nothing was deleted.
 ```
@@ -122,15 +88,14 @@ Stop.
 
 ### 6. Confirm Deletion
 
-Verify files are gone and report:
+Verify folders are gone and report:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ✅ Clear complete
 
 Deleted:
-  🗑️  Context files: {n_ctx} file(s) removed
-  🗑️  Review reports: {n_rpt} file(s) removed
+  🗑️  Sessions removed: {n} folder(s)
 
 Output folder: {review_output}
 Status: clean

package/src/core/tasks/help.md

@@ -36,4 +36,5 @@ Use `/prr-help` anytime for guidance on what to do.
 
 ### Utilities
 
-- **[CL] Clear** — Remove context files and/or review reports from output folder. Useful when starting fresh or cleaning up after a session. Choose: All / Context only / Reports only.
+- **[SS] Select Session** — List past review sessions and resume one. Use this at the start of a new conversation to pick up where you left off.
+- **[CL] Clear** — Delete one or more past review session folders. Choose specific sessions or clear all.

package/src/core/tasks/select-session.md

@@ -0,0 +1,94 @@
+# Select Session
+
+**Goal:** List all past PR review sessions and let the user resume one by restoring `session_output` into working context.
+
+## EXECUTION
+
+### 1. Load Config
+
+Read `{project-root}/_prr/prr/config.yaml` to get `review_output` path.
+
+### 2. Scan Session Folders
+
+List all session folders in `{review_output}`:
+
+```bash
+ls -d "{review_output}"/*/
+```
+
+For each session folder, read its contents to build a summary:
+
+```bash
+ls "{review_output}/{session_folder}/"
+```
+
+From the files present, determine:
+- **Branch / PR** — from folder name (e.g. `2026-03-02-1430-pr44-feature-auth` → PR #44, branch `feature/auth`)
+- **Date / Time** — from folder name prefix (`2026-03-02-1430`)
+- **Reviews done** — which `*-review.md` files exist
+- **Has final report** — `final-review.md` exists
+- **Has description** — `pr-description.md` exists
+
+### 3. Display Sessions
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📂 Review Sessions — {review_output}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  [1] 2026-03-02 14:30 — PR #44  feature/auth-login
+      Reviews: DP ✓  GR ✓  SR ✓  RR ✓
+      Report:  final-review.md ✓
+
+  [2] 2026-03-01 09:15 — fix/null-pointer-checkout
+      Reviews: DP ✓  GR ✓
+      Report:  —
+
+  [3] 2026-02-28 17:00 — PR #41  chore/upgrade-deps
+      Reviews: DP ✓  GR ✓  AR ✓  RR ✓
+      Report:  final-review.md ✓
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+If no sessions exist:
+```
+✅ No sessions found in {review_output}.
+   Run [SP] Select PR or [QR] Quick Review to start a new session.
+```
+Then stop.
+
+### 4. Ask User to Select
+
+```
+Select a session to resume (enter number):
+```
+
+**HALT — wait for user response.**
+
+### 5. Restore Session
+
+Set `session_output` = full path of the selected session folder.
+
+Load PR metadata from working context sources available in the session folder:
+- Parse `session_output` folder name to extract: `datetime_prefix`, `pr_number` (if `prN-` prefix), `branch_slug`
+- Read `pr-context.yaml` if it exists — extract `pr_metadata.pr_number`, `pr_metadata.branch`, `pr_metadata.base_branch`
+- Derive `target_branch` and `base_branch` from knowledge base or folder name
+
+**Store in working context:**
+- `session_output` = selected folder path
+- `target_branch`, `base_branch`, `pr_number` = from above
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ Session restored
+
+📁 {session_output}
+   Branch: {target_branch} → {base_branch}
+   PR #:   {pr_number}  (if applicable)
+
+Reviews completed: {list or "none"}
+Ready to continue — run any command from the menu.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```

package/src/core/workflows/party-mode/steps/step-00-user-instructions.md

@@ -0,0 +1,125 @@
+---
+name: "step-00-user-instructions"
+description: "Collect user instructions before the party review begins"
+nextStepFile: "./step-01-load-reviewers.md"
+---
+
+# Step 0: User Instructions
+
+## Goal
+Always ask the user for scope, focus, requirements, or context before reviewers are loaded.
+This step runs even if a `pr-context.yaml` already exists — fresh instructions override any prior `user_instructions` in the file.
+
+## Sequence of Instructions
+
+### 1. Show PR Summary
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🎉 Party Mode — Review Setup
+
+   Branch: {target_branch} → {base_branch}
+   Files:  {file_count} changed
+   PR:     {pr_number if set, else "local branch"}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### 2. Prompt User
+
+Display EXACTLY:
+
+```
+💬 Any instructions for this review?
+   Press Enter to run a full standard review, or type your instructions below.
+
+   You can specify:
+     • Scope        "only security" / "security and architecture" / "skip performance"
+     • Focus        "focus on SQL injection and rate limiting"
+     • Requirements "all API endpoints must have auth middleware"
+     • Context      "hotfix — ignore refactoring suggestions"
+     • Mix freely   "security only, focus on JWT handling, context: auth rewrite in progress"
+```
+
+**HALT — wait for user response before continuing.**
+
+### 3. Parse Response
+
+**If user pressed Enter / left empty:**
+- Set `user_instructions.provided` = `false`
+- Set `user_instructions.review_scope` = `"all"`
+- Set all other fields to `null`
+
+**If user typed something**, parse the free-form text and extract:
+
+**`review_scope`** — which reviews to run:
+- Parse for scope signals: "only X", "just X", "X only", "skip X", "no X review", "X and Y"
+- Map to codes: `GR` (general), `SR` (security), `PR` (performance), `AR` (architecture), `BR` (business)
+- Examples:
+  - "only security" → `[SR]`
+  - "security and architecture" → `[SR, AR]`
+  - "skip performance" → `[GR, SR, AR, BR]`
+  - "focus on SQL injection" (no scope signal) → `"all"` (focus only, all reviewers still active)
+- If no scope restriction found → `"all"`
+
+**`focus_areas`** — specific things reviewers must prioritize (list of strings), or `null` if none.
+
+**`custom_requirements`** — mandatory checks user specified (list of strings), or `null`.
+
+**`context_notes`** — background info, trade-offs, constraints (list of strings), or `null`.
+
+**`raw`** — full original text from user.
+
+Set `user_instructions.provided` = `true`.
+
+### 4. Acknowledge
+
+**If user provided instructions:**
+
+```
+✅ Instructions captured.
+
+   📋 Scope:        {scope_list joined with ", "  OR  "all reviewers"}
+   🎯 Focus:        {focus_areas joined with ", "  OR  "standard coverage"}
+   ✅ Requirements: {custom_requirements joined with ", "  OR  "none"}
+   📝 Context:      {context_notes joined with "; "  OR  "none"}
+```
+
+**If user left empty:**
+
+```
+▶️  Full standard review — all reviewers, standard focus.
+```
+
+### 5. Write to pr-context.yaml
+
+Write `user_instructions` to `{session_output}/pr-context.yaml`:
+
+- **If `pr-context.yaml` exists**: update only the `user_instructions:` section, leave all other sections intact.
+- **If `pr-context.yaml` does not exist** (Party Mode was run without prior DP/context collection):
+  Create a minimal file with just `pr_metadata` and `user_instructions`:
+
+```yaml
+# PR-Specific Context (minimal — created by Party Mode)
+# Generated: {timestamp}
+
+pr_metadata:
+  pr_number: {pr_number or null}
+  branch: {target_branch}
+  base_branch: {base_branch}
+  collected_at: {ISO timestamp}
+
+user_instructions:
+  provided: {true|false}
+  review_scope: {value}
+  focus_areas: {value}
+  custom_requirements: {value}
+  context_notes: {value}
+  raw: {value}
+```
+
+Store `pr_knowledge_base` = `{session_output}/pr-context.yaml` in working context.
+
+### 6. Load Next Step
+
+Add `step-00-user-instructions` to `stepsCompleted`. Load: `{nextStepFile}`

package/src/core/workflows/party-mode/steps/step-01-load-reviewers.md

@@ -8,35 +8,43 @@ nextStepFile: "./step-02-discussion.md"
 
 ## Sequence of Instructions
 
-### 1. Introduce Party Mode
+### 1. Load PR Knowledge Base
 
-Display:
+Load the PR knowledge base from working context (`pr_knowledge_base`), or read directly at `{session_output}/pr-context.yaml`.
+It contains stack-specific rules, ESLint/linting rules, project guidelines (CLAUDE.md, CONTRIBUTING.md, ARCHITECTURE.md sections), inline code annotations, and external context.
+
+If no knowledge base exists (DP was not run), proceed with local context only — do not block.
+
+**Read `user_instructions.review_scope`** from the knowledge base:
+- If `"all"` (or knowledge base missing) → all 5 reviewers are active.
+- If a list (e.g. `[SR, AR]`) → only activate reviewers matching those codes:
+  `GR` = Alex · `SR` = Sam · `PR` = Petra · `AR` = Arch · `BR` = Biz
+
+### 2. Introduce Party Mode
+
+Display, listing only the **active** reviewers:
 ```
 🎉 Party Mode activated!
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Reviewers joining this session:
 
-  👁️  Alex     — General Code Quality
+  {active reviewers only, e.g.:}
   🔒  Sam      — Security
-  ⚡  Petra    — Performance
   🏗️  Arch     — Architecture
-  💼  Biz      — Business Impact
 
 PR: {target_branch} → {base_branch}
 Files changed: {file_count} | Lines: +{additions} -{deletions}
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-### 2. Load PR Knowledge Base
-
-Read `{review_output}/current-pr-context.yaml` to get `pr_knowledge_base` path.
-Load the knowledge base file — it contains stack-specific rules, ESLint/linting rules, project guidelines (CLAUDE.md, CONTRIBUTING.md, ARCHITECTURE.md sections), inline code annotations, and external context.
-
-If no knowledge base exists (DP was not run), proceed with local context only — do not block.
+If reviewers were filtered, also print:
+```
+⏭️  Skipped: {inactive reviewer names} (not in review scope)
+```
 
 ### 3. Load Reviewer Personas
 
-Internally adopt all reviewer personas simultaneously. All reviewers apply rules from the PR knowledge base in their respective areas.
+Internally adopt only the **active** reviewer personas (determined by scope in step 1). All active reviewers apply rules from the PR knowledge base in their respective areas.
 
 **👁️ Alex (General Reviewer)**
 - Focus: code logic, naming, readability, DRY, best practices, test coverage, side effects, and stack-specific best practices from knowledge base
@@ -64,7 +72,7 @@ Internally adopt all reviewer personas simultaneously. All reviewers apply rules
 - Runs last, references findings from Alex/Sam/Petra/Arch and translates them to business consequences
 - Output format: risk level (CRITICAL/HIGH/MEDIUM/LOW) + user impact + deployment recommendation
 
-### 4. Scan the Diff and Assign Focus Areas
+### 4. Scan the Diff and Assign Focus Areas (active reviewers only)
 
 Read the diff and file list from the knowledge base. Assign focus areas:
 - SQL/DB files → Petra leads (N+1, missing index), Sam checks (injection)
@@ -74,6 +82,6 @@ Read the diff and file list from the knowledge base. Assign focus areas:
 - Any file touching auth, payments, PII → Sam mandatory
 - Schema/migration files → Biz flags (data safety, rollback plan)
 
-### 4. Load Next Step
+### 5. Load Next Step
 
 Add `step-01-load-reviewers` to `stepsCompleted`. Load: `{nextStepFile}`