feat: opt-in --selector review mode (in-session classify + adjudicate, zero spawns)

CHANGELOG.md

@@ -8,6 +8,12 @@ Please choose versions by [Semantic Versioning](http://semver.org/).
 * MINOR version when you add functionality in a backwards-compatible manner, and
 * PATCH version when you make backwards-compatible bug fixes.
 
+## Unreleased
+
+- feat: add opt-in `--selector` mode to `/coding:pr-review` and `/coding:code-review` — replaces per-owner Task fanout (Step 4b-ii) with two in-session steps: Step 4c-sel CLASSIFY (narrows glob candidates via recall-optimized contract) and Step 4d-sel ADJUDICATE (reads only applicable rule blocks, emits findings in existing severity buckets); zero sub-agent spawns; default mode unchanged
+- refactor: extract selector-mode classify/adjudicate procedure to docs/selector-mode-guide.md — commands carry thin pointers (single source of truth; answers pr-reviewer command-thin + single-source-of-truth findings)
+- fix: selector-mode guide resolution is now fail-fast — explicit `GUIDE_OK`/`GUIDE_MISSING` echo, and on missing guide the review STOPS with a Must Fix toolchain failure instead of silently continuing mechanical-only (caught by MiniMax-M2.7 benchmark: weaker model skipped classify+adjudicate entirely when the guide path failed, presenting a judgment-less review as complete)
+
 ## v0.19.0
 - refactor!: BREAKING CHANGE — rename `coding:release-changelog-agent` → `coding:release-changelog-assistant` to match marketplace `<noun>-<role>.md` naming convention (`-assistant` / `-auditor`, not `-agent`). Coordinated rename: agent file `agents/release-changelog-agent.md` → `agents/release-changelog-assistant.md`, `name:` frontmatter, both callers' `subagent_type=` reference, README agents-table entry, llms.txt entry, and CHANGELOG mentions. Callers on v0.18.0 will fail to resolve until updated; v0.18.0 callers are bundled in this same commit so any installer of v0.19.0+ has the matching pair.
 - refactor: restructure `coding:release-changelog-assistant` body to XML schema per agent-command-development-guide — add `<constraints>` block (NEVER commit/tag/push, ALWAYS return error field when malformed, etc.), `<process>` block summarizing the 5-step workflow up-front (was buried), `<output_format>` for the success JSON schema, `<error_handling>` for the three error codes (separates concerns from success). Markdown `#` headings retained only for high-level sections (Purpose, Inputs, classification rules, rewrite rules, caller profiles, invocation example); structural directives now use XML tags as the guide requires.

README.md

@@ -177,6 +177,7 @@ All guides live in [`docs/`](docs/) and can be read standalone without the plugi
 | [Skill Writing](docs/claude-code-skill-writing-guide.md) | Claude Code skill directory structure |
 | [Rule Block Schema](docs/rule-block-schema.md) | `### RULE` block contract and index schema |
 | [ast-grep Rule Writing Guide](docs/ast-grep-rule-writing-guide.md) | ast-grep YAML conventions for mechanical rule enforcement |
+| [Selector Mode Guide](docs/selector-mode-guide.md) | In-session classify + adjudicate procedure for `--selector` mode |
 
 ### Frontend
 

commands/code-review.md

@@ -1,6 +1,6 @@
 ---
 allowed-tools: Task, Bash(git diff:+), Bash(git log:+), Bash(git status:+), Bash(git ls-files:+)
-argument-hint: "[short|standard|full] [directory]"
+argument-hint: "[short|standard|full|selector] [directory]"
 description: Perform a comprehensive code review of recent changes
 ---
 
@@ -20,6 +20,7 @@ Perform a code review with configurable depth based on mode.
 Parse the first argument to determine mode:
 - If first arg is `short|quick|fast` → **Short mode** (manual review only)
 - If first arg is `full|comprehensive|complete` → **Full mode** (all 13 agents)
+- If first arg is `--selector` or `selector` → **Selector mode** (in-session classify + adjudicate, zero sub-agent spawns)
 - Otherwise → **Standard mode** (4 core agents, default)
 
 Any remaining arguments are treated as the directory path.
@@ -179,6 +180,31 @@ echo "{\"event\":\"per_owner_summary\",\"owners_invoked\":$owners_invoked,\"tota
 
 Diagnostic only — operators read it to answer "is Owner X worth dispatching?" with data. Not part of the Step 5 user-facing report. `code-review.md` has no formal cleanup step (the command works against the current branch in-place; there is no review-worktree to remove), so end the run with `rm -f /tmp/code-review-timing.jsonl` to keep the file from accumulating stale lines across reviews.
 
+#### Selector mode: Steps 4c-sel and 4d-sel
+
+When the mode argument is `--selector` or `selector`: Steps 4.0, 4a, and 4b-i run unchanged. Skip Step 4b-ii. Resolve the guide and execute Steps 4c-sel and 4d-sel from it — zero sub-agent spawns.
+
+Run exactly this one command, once:
+
+```bash
+GUIDE="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/coding}/docs/selector-mode-guide.md"
+[ -f "$GUIDE" ] || GUIDE="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plugins/marketplaces/coding/docs/selector-mode-guide.md"
+[ -f "$GUIDE" ] && echo "GUIDE_OK: $GUIDE" || echo "GUIDE_MISSING"
+```
+
+If it prints `GUIDE_MISSING`: report "selector guide unavailable" as a **Must Fix toolchain failure** in Step 5 and STOP the selector path — do NOT continue with a mechanical-findings-only review presented as a complete selector review (a review without the judgment tier silently misses every judgment-tier rule; same fail-fast discipline as Step 4.0). Do NOT investigate further (no `find`, no `ls`, no path probing).
+
+If it prints `GUIDE_OK`: Read the file at that path, then execute its **Step 4c-sel CLASSIFY** and **Step 4d-sel ADJUDICATE** with:
+
+- **DIFF** = `git diff HEAD~1` (or directory diff as parsed in Step 1)
+- **CANDIDATES** = the Step 4b-i `<rule-id> <owner>` output
+- **MECHANICAL_FINDINGS** = `/tmp/code-review-findings.json`
+- **Working directory** = the reviewed directory
+
+On the guide's short-circuit condition the report line is `selector clean — no adjudication needed`. When the mode is anything else (short/standard/full), skip this section entirely.
+
+Include the traceability section per `docs/selector-mode-guide.md` § Traceability Report Section.
+
 #### 4c: Context-specific conventions
 
 Load these conventionally when the diff matches:
@@ -225,6 +251,10 @@ Agent-reported important issues (error handling, architecture, factory/handler p
 #### Nice to Have (Optional)
 Agent-reported minor issues (style, documentation, naming conventions, version updates).
 
+#### Selector Mode: Classify Traceability (selector mode only)
+
+Include the traceability section per `docs/selector-mode-guide.md` § Traceability Report Section.
+
 ### Step 6: Next Steps
 
 If `go-test-coverage-assistant` reported missing tests, suggest:

commands/pr-review.md

@@ -1,6 +1,6 @@
 ---
 allowed-tools: Task, Bash(git diff:+), Bash(git log:+), Bash(git status:+), Bash(git ls-files:+), Bash(git fetch:+), Bash(git worktree:+), Bash(git branch:+), Bash(rm -rf:+)
-argument-hint: "<target-branch> [short|standard|full]"
+argument-hint: "<target-branch> [short|standard|full|selector]"
 description: Review current branch diff against target branch (excludes vendor/node_modules)
 ---
 
@@ -80,6 +80,7 @@ cd <REPO_DIR> && git worktree remove /tmp/pr-review-<repo>-<SOURCE_BRANCH> --for
 
 - `short|quick|fast` → **Short mode** (manual review only)
 - `full|comprehensive|complete` → **Full mode** (all agents)
+- `--selector` or `selector` → **Selector mode** (in-session classify + adjudicate, zero sub-agent spawns)
 - Otherwise → **Standard mode** (4 core agents, default)
 
 ### Step 2: Project Detection
@@ -210,6 +211,31 @@ echo "{\"event\":\"per_owner_summary\",\"owners_invoked\":$owners_invoked,\"tota
 
 The timing file `/tmp/pr-review-timing.jsonl` is purely diagnostic — it lets operators answer "is Owner X worth dispatching?" with data instead of intuition. Not part of the Step 5 user-facing report; include it in the cleanup step for the review worktree so it gets removed after Step 6.
 
+#### Selector mode: Steps 4c-sel and 4d-sel
+
+When the mode argument is `--selector` or `selector`: Steps 4.0, 4a, and 4b-i run unchanged. Skip Step 4b-ii. Resolve the guide and execute Steps 4c-sel and 4d-sel from it — zero sub-agent spawns.
+
+Run exactly this one command, once:
+
+```bash
+GUIDE="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/coding}/docs/selector-mode-guide.md"
+[ -f "$GUIDE" ] || GUIDE="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plugins/marketplaces/coding/docs/selector-mode-guide.md"
+[ -f "$GUIDE" ] && echo "GUIDE_OK: $GUIDE" || echo "GUIDE_MISSING"
+```
+
+If it prints `GUIDE_MISSING`: report "selector guide unavailable" as a **Must Fix toolchain failure** in Step 5 and STOP the selector path — do NOT continue with a mechanical-findings-only review presented as a complete selector review (a review without the judgment tier silently misses every judgment-tier rule; same fail-fast discipline as Step 4.0). Do NOT investigate further (no `find`, no `ls`, no path probing).
+
+If it prints `GUIDE_OK`: Read the file at that path, then execute its **Step 4c-sel CLASSIFY** and **Step 4d-sel ADJUDICATE** with:
+
+- **DIFF** = the Step 0c diff (`git diff origin/<TARGET_BRANCH>...HEAD`)
+- **CANDIDATES** = the Step 4b-i `<rule-id> <owner>` output
+- **MECHANICAL_FINDINGS** = `/tmp/pr-review-findings.json`
+- **Working directory** = `REVIEW_DIR`
+
+On the guide's short-circuit condition the report line is `selector clean — no adjudication needed`. When the mode is anything else (short/standard/full), skip this section entirely.
+
+Include the traceability section per `docs/selector-mode-guide.md` § Traceability Report Section.
+
 #### 4c: Context-specific conventions (kept from prior Step 2.5)
 
 Some review questions still benefit from a full-doc read even in dispatcher mode. Load these conventionally when the diff matches:
@@ -253,6 +279,10 @@ The script exits non-zero if any finding's `rule_id` is not in `rules/index.json
 #### Nice to Have (Optional)
 - Style, code organization, Go patch updates, tool updates, naming conventions, copyright headers
 
+#### Selector Mode: Classify Traceability (selector mode only)
+
+Include the traceability section per `docs/selector-mode-guide.md` § Traceability Report Section.
+
 ### Step 6: Next Steps Recommendation
 
 If test coverage gaps found, suggest `/go-write-test` commands.

docs/selector-mode-guide.md

@@ -0,0 +1,81 @@
+## Selector Mode — Classify and Adjudicate Procedure
+
+Selector mode replaces Step 4b-ii's per-owner Task dispatch with two in-session steps that run in the calling command's session. Steps 4.0, 4a, and 4b-i run unchanged and produce the candidate set. The design goal is zero sub-agent spawns: every rule is evaluated inside the current session context rather than cold-starting one sub-agent per owner.
+
+Selector mode is opt-in (`--selector`/`selector` mode token); the default per-owner dispatch path is unchanged.
+
+## Inputs
+
+| Input | Description |
+|-------|-------------|
+| `DIFF` | The full diff for this review (caller-provided; see note below) |
+| `CANDIDATES` | The `<rule-id> <owner>` list produced by Step 4b-i jq glob output |
+| `MECHANICAL_FINDINGS` | Path to the Step 4a runner output JSON (e.g. `/tmp/pr-review-findings.json`) |
+| Working directory | The directory under review (caller-provided) |
+
+**Diff source differs per caller**: `commands/pr-review.md` uses the Step 0c worktree diff (`git diff origin/<TARGET_BRANCH>...HEAD`); `commands/code-review.md` uses `git diff HEAD~1` (or directory diff as parsed in Step 1).
+
+## Step 4c-sel: CLASSIFY (in-session, no Task spawn)
+
+**Input**: `DIFF`, the `CANDIDATES` list, and the `applies_when` text for each candidate from `rules/index.json`.
+
+For each candidate rule, decide: **applicable** or **skipped** with a one-line reason (≤ 8 words).
+
+**Recall contract (embed verbatim)**: "INCLUDE if a reasonable reviewer would want to read this rule before judging. Do not evaluate compliance. Do not evaluate violations. When uncertain, include."
+
+**Skip justification rule**: a skip decision MUST be justified against the rule's `applies_when` text itself — the reason states why the `applies_when` condition does not hold for this diff. NEVER infer a rule's scope from its rule-id name or prefix (e.g. `go-testing/*` rules are NOT necessarily scoped to test files — read the `applies_when`). If the diff plausibly matches the `applies_when` condition, the rule is applicable.
+
+**HARD INVARIANT**: the applicable set MUST be a subset of the candidate set. Every applicable rule_id must appear in the Step 4b-i candidate list. Never add a rule the glob did not produce.
+
+**Architecture-tier bypass**: any candidate rule whose `enforcement` text contains "architecture" OR whose `doc_path` is `go-architecture-patterns.md` and concerns SRP/layering is unconditionally applicable — do not classify, always include it.
+
+**Short-circuit**: if the applicable set is empty AND the mechanical findings from Step 4a are also empty, report:
+
+> `selector clean — no adjudication needed`
+
+and skip Step 4d-sel, proceeding directly to Step 5. Include the candidate count and a note that all candidates were classified as non-applicable in the Step 5 traceability section.
+
+Produce a classify result:
+```json
+{
+  "applicable": ["<rule-id>", "..."],
+  "skipped": {
+    "<rule-id>": "<one-line reason ≤ 8 words>",
+    "...": "..."
+  }
+}
+```
+
+## Step 4d-sel: ADJUDICATE (in-session, no Task spawn)
+
+**Input**: the full diff (no truncation — this is the load-bearing step), the mechanical findings from `MECHANICAL_FINDINGS`, and the applicable rules from Step 4c-sel.
+
+For each applicable rule: locate the rule's `doc_path` in `rules/index.json`, then read only the matching `### RULE <id>` block from that file (grep for the heading, read the block — do not read the whole document).
+
+Judge the full diff plus mechanical findings. For each violation found, emit a finding that cites `rule_id` + file + line and lands in the existing report buckets:
+
+- **Must Fix (Critical)** — security, context violations, concurrency bugs, data correctness, SRP (3+ concerns)
+- **Should Fix (Important)** — architectural violations, error handling, factory/handler patterns, test gaps
+- **Nice to Have (Optional)** — style, naming, minor version issues
+
+Do not emit a per-rule "passed" entry for rules with no violation — silently omit them.
+
+**Batching**: if the applicable set exceeds 20 rules, split adjudication into 2–3 thematic in-session passes (e.g. architecture rules first, then quality rules, then style rules). Each pass runs in the current session — still zero Task spawns. Collect all findings before proceeding to citation validation.
+
+**Citation validation** (invoked directly — selector mode spawns NO sub-agents, including `coding:simple-bash-runner`): run the validator as a plain Bash call over the adjudication findings before consolidation — findings citing a `rule_id` absent from `rules/index.json` are dropped and logged to stderr. Resolve the script path via the plugin install chain (the working directory may not be the plugin checkout):
+
+```bash
+VALIDATOR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/coding}/scripts/validate-citations.sh"
+[ -x "$VALIDATOR" ] || VALIDATOR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plugins/marketplaces/coding/scripts/validate-citations.sh"
+bash "$VALIDATOR" <findings.json>
+```
+
+## Traceability Report Section
+
+Include this section in the Step 5 report only when the review ran in selector mode. List counts and every classify skip so operators can spot false drops:
+
+- **Candidates**: `<N>` rules matched by Step 4b-i glob filter
+- **Applicable**: `<M>` rules selected by Step 4c-sel (M ≤ N)
+- **Skipped** (one line each):
+  - `<rule-id>` → `<one-line reason>`
+  - …

llms.txt

@@ -73,6 +73,7 @@
 - [Skill Writing](docs/claude-code-skill-writing-guide.md): Structure and conventions for Claude Code skill directories
 - [Rule Block Schema](docs/rule-block-schema.md): `### RULE` block contract and index schema
 - [ast-grep Rule Writing Guide](docs/ast-grep-rule-writing-guide.md): ast-grep YAML conventions for mechanical rule enforcement
+- [Selector Mode Guide](docs/selector-mode-guide.md): In-session classify + adjudicate procedure for `--selector` mode (single source of truth; commands carry thin pointers)
 
 ## Frontend
 - [Vue 3 + TypeScript](docs/vue3-typescript-frontend-guide.md): Composition API, Vite, Vitest