fix(peer-review-jj): address review findings

docs/peer-review-jj/2026-03-16-peer-review-jj-design.md

@@ -26,7 +26,8 @@ Inspired by [Gesoff's duplicate+squash review technique](https://ben.gesoff.uk/p
 
 ```
 peer-review-jj/
-├── plugin.json
+├── .claude-plugin/
+│   └── plugin.json
 ├── commands/
 │   └── peer-review.md              # /peer-review — single entry point
 ├── skills/

plugins/peer-review-jj/agents/change-reviewer.md

@@ -67,7 +67,7 @@ Rate each finding from 0-100:
 
 ## Specialist Recommendation Trigger
 
-When you encounter something outside your depth — complex type invariants, subtle concurrency issues, error handling chains across multiple files — add a `specialist_recommendation` entry with:
+When you encounter something outside your depth — complex type invariants, subtle concurrency issues, error handling chains across multiple files — add a `specialist_recommendations` entry with:
 
 - Concern type (from the enum)
 - Specific file and line locations

plugins/peer-review-jj/commands/peer-review.md

@@ -67,6 +67,16 @@ jj log -r <rev> --no-graph -T 'self.diff().stat().files().map(|entry| "{ \"path\
 
 ### Step 2: If --track, Set Up Progress Tracking
 
+Check for existing review state first:
+
+```bash
+jj log -r 'description("review: <change-id>")' --no-graph -T 'self.change_id().short(8)'
+```
+
+If found, resume from existing state — only dispatch for unreviewed files. Skip setup below.
+
+If not found, set up:
+
 ```bash
 # Duplicate the target change
 DUPLICATE=$(jj duplicate <revision> 2>&1 | sed -n 's/.*as \([a-z]*\) .*/\1/p')
@@ -84,14 +94,6 @@ REVIEWED_PARENT=$(jj log -r '@-' --no-graph -T 'self.change_id().short(8)')
 jj describe -r $REVIEWED_PARENT -m "review: <change-id>"
 ```
 
-Check for existing review state first:
-
-```bash
-jj log -r 'description("review: <change-id>")' --no-graph -T 'self.change_id().short(8)'
-```
-
-If found, resume from existing state — only dispatch for unreviewed files.
-
 ### Step 3: Calculate Generalist Count
 
 ```

plugins/peer-review-jj/scripts/block-review-markers.sh

@@ -1,14 +1,14 @@
 #!/usr/bin/env bash
-# PreToolUse hook: Warn if REVIEW(peer): markers found in code being committed
+# PreToolUse hook: Block commits containing REVIEW(peer): markers
 # Safety backstop for future annotation features
 
 input=$(cat)
 command=$(echo "$input" | jq -r '.tool_input.command // ""')
 
 # Only check jj commit/squash operations
 if echo "$command" | grep -qE '(jj\s+(commit|squash))'; then
-  # Check staged changes for review markers
-  if jj diff 2>/dev/null | grep -q 'REVIEW(peer):'; then
+  # Check staged changes for review markers (exclude hook scripts, docs, and test files that reference the pattern)
+  if jj diff 2>/dev/null | grep -v -E '(block-review-markers|\.md:)' | grep -q 'REVIEW(peer):'; then
     cat <<'EOF'
 {
   "hookSpecificOutput": {

plugins/peer-review-jj/skills/requesting-change-review.md

@@ -56,27 +56,19 @@ Each generalist receives a prompt with:
 - **Change context**: revision, description, change metadata from `jj log -r <rev> --no-graph -T 'json(self) ++ "\n"'`
 - **Output schema**: the generalist response JSON schema (from the change-reviewer agent spec)
 
-## Step 5: Dispatch Generalists
+## Step 5: If --track Enabled
 
-- Use the Agent tool to dispatch generalists in parallel
-- Each generalist is a `change-reviewer` agent (subagent_type: `change-reviewer`)
-- Include the jj-only directive in each agent prompt
-- Collect all JSON responses
+### Resumability Detection
 
-Example dispatch (single generalist):
+Check for existing review state first:
 
+```bash
+jj log -r 'description("review: <change-id>")' --no-graph -T 'self.change_id().short(8)'
 ```
-Agent(
-  subagent_type: "change-reviewer",
-  prompt: "Review these files in revision <rev>: <file list>. <context>. <guidelines>. Return structured JSON."
-)
-```
-
-For multiple generalists, dispatch all in a single message with parallel Agent calls.
 
-## Step 6: If --track Enabled
+If found, check which files are already squashed (reviewed) by comparing `jj diff --stat` on the working copy. Only dispatch generalists for files still in the working copy. Skip setup below.
 
-### Setup (first run)
+### Setup (first run, only if no existing review state)
 
 ```bash
 # 1. Duplicate the target change
@@ -95,17 +87,25 @@ REVIEWED_PARENT=$(jj log -r '@-' --no-graph -T 'self.change_id().short(8)')
 jj describe -r $REVIEWED_PARENT -m "review: <change-id>"
 ```
 
-### Resumability Detection
+## Step 6: Dispatch Generalists
 
-Search for existing review state:
+- Use the Agent tool to dispatch generalists in parallel
+- Each generalist is a `change-reviewer` agent (subagent_type: `change-reviewer`)
+- Include the jj-only directive in each agent prompt
+- Collect all JSON responses
+
+Example dispatch (single generalist):
 
-```bash
-jj log -r 'description("review: <change-id>")' --no-graph -T 'self.change_id().short(8)'
+```
+Agent(
+  subagent_type: "change-reviewer",
+  prompt: "Review these files in revision <rev>: <file list>. <context>. <guidelines>. Return structured JSON."
+)
 ```
 
-If found, check which files are already squashed (reviewed) by comparing `jj diff --stat` on the working copy. Only dispatch generalists for files still in the working copy.
+For multiple generalists, dispatch all in a single message with parallel Agent calls.
 
-### After Each Generalist Completes
+### After Each Generalist Completes (if --track)
 
 Squash clean files (no findings) into the reviewed parent: