pi-orchestrator-config 4.1.5

package/prompts/review-local.md

@@ -0,0 +1,159 @@
+---
+description: Review uncommitted changes or changes compared to a branch
+argument-hint: "[base branch]"
+---
+
+## Raw Arguments
+
+```text
+$ARGUMENTS
+```
+
+# Local Code Review Command
+
+> **Bug Reporting Policy:** If you encounter ANY error, unexpected behavior, or reproducible bug
+> while executing this command — DO NOT work around it silently. Ask the user:
+> "Should I create a GitHub issue for this?" Route to:
+> `myk-org/pi-config` for plugin/command spec or `myk-pi-tools` CLI issues.
+> Do not silently skip steps or apply manual fixes that hide the root cause.
+
+Review uncommitted changes or changes compared to a specified branch.
+
+## Usage
+
+- `/review-local` - Review uncommitted changes (staged + unstaged)
+- `/review-local main` - Review changes compared to main branch
+- `/review-local feature/branch` - Review changes compared to specified branch
+
+## Task Plan
+
+Before starting any work, create ALL tasks upfront using `TaskCreate`, then set their dependencies
+using `TaskUpdate` with `addBlockedBy`. The task system enforces execution order — blocked tasks cannot start.
+
+### Task List
+
+| Task | Title | blockedBy |
+|------|-------|-----------|
+| 1 | Get diff | — |
+| 2 | Review — Code Quality | 1 |
+| 3 | Review — Guidelines | 1 |
+| 4 | Review — Security | 1 |
+| 5 | Review — Docs | 1 |
+| 6 | Review — Spec | 1 |
+| 7 | Merge & deduplicate findings | 2, 3, 4, 5, 6 |
+| 8 | Present review | 7 |
+
+### Dependency Graph
+
+```text
+Task 1 (Get diff)
+ ├── Task 2 (Review: Code Quality)  ──┐
+ ├── Task 3 (Review: Guidelines)    ──┤
+ ├── Task 4 (Review: Security)      ──┤
+ ├── Task 5 (Review: Docs)          ──┤
+ └── Task 6 (Review: Spec)          ──┤
+                                       ▼
+                            Task 7 (Merge findings)
+                                       │
+                            Task 8 (Present review)
+```
+
+Create all 8 tasks using `TaskCreate` NOW, before starting any work.
+Then IMMEDIATELY set dependencies using `TaskUpdate` with `addBlockedBy` for each task per the table above.
+
+`TaskCreate` does NOT accept `addBlockedBy` — dependencies MUST be set via `TaskUpdate` after creation.
+
+Example two-step flow:
+
+```text
+# Step 1: Create all tasks
+TaskCreate(subject="Get diff", ...)                    → Task 1
+TaskCreate(subject="Review — Code Quality", ...)       → Task 2
+TaskCreate(subject="Review — Guidelines", ...)         → Task 3
+TaskCreate(subject="Review — Security", ...)           → Task 4
+TaskCreate(subject="Review — Docs", ...)               → Task 5
+TaskCreate(subject="Review — Spec", ...)               → Task 6
+TaskCreate(subject="Merge & deduplicate findings", ...)→ Task 7
+TaskCreate(subject="Present review", ...)              → Task 8
+
+# Step 2: Set dependencies
+TaskUpdate(taskId="2", addBlockedBy=["1"])
+TaskUpdate(taskId="3", addBlockedBy=["1"])
+TaskUpdate(taskId="4", addBlockedBy=["1"])
+TaskUpdate(taskId="5", addBlockedBy=["1"])
+TaskUpdate(taskId="6", addBlockedBy=["1"])
+TaskUpdate(taskId="7", addBlockedBy=["2", "3", "4", "5", "6"])
+TaskUpdate(taskId="8", addBlockedBy=["7"])
+```
+
+> 🚨 **HARD RULE: NEVER start a task while its `blockedBy` tasks are incomplete.**
+> The task system enforces this via `addBlockedBy` — but even if you could bypass it, **DON'T**.
+> Merging findings from partial reviewer results is a **CRITICAL violation**.
+> ALL 5 reviewers (Tasks 2, 3, 4, 5, 6) MUST complete before merging findings (Task 7).
+
+## Workflow
+
+### Phase 1: Get Diff — Task 1
+
+**If the raw arguments are not empty:**
+
+Compare current branch against the specified branch:
+
+```bash
+git diff "<raw_arguments>"...HEAD
+```
+
+**If no argument provided:**
+
+Get all uncommitted changes (staged + unstaged):
+
+```bash
+git diff HEAD
+```
+
+### Phase 2: Code Analysis — Tasks 2, 3, 4, 5, 6
+
+Spawn ALL 5 review agents as async subagents
+with `taskId` linking each to its task.
+Use the actual task IDs returned by `TaskCreate` — do NOT hardcode IDs.
+
+```text
+subagent(tasks=[
+  {agent: "code-reviewer-quality", task: "Review diff for code quality...", cwd: "...", name: "Review Quality", taskId: "<actual task 2 ID>"},
+  {agent: "code-reviewer-guidelines", task: "Review diff for guidelines...", cwd: "...", name: "Review Guidelines", taskId: "<actual task 3 ID>"},
+  {agent: "code-reviewer-security", task: "Review diff for security...", cwd: "...", name: "Review Security", taskId: "<actual task 4 ID>"},
+  {agent: "code-reviewer-docs", task: "Review diff for documentation quality...", cwd: "...", name: "Review Docs", taskId: "<actual task 5 ID>"},
+  {agent: "code-reviewer-spec", task: "Review diff for spec compliance...", cwd: "...", name: "Review Spec", taskId: "<actual task 6 ID>"},
+])
+```
+
+Provide each agent with the diff content from Phase 1 and ask them to analyze for:
+
+1. Code quality and best practices
+2. Potential bugs or logic errors
+3. Security vulnerabilities
+4. Performance issues
+5. Naming conventions and readability
+6. Missing error handling
+7. Code duplication
+8. Suggestions for improvement
+
+**After spawning, verify the response confirms all 5 agents were spawned.**
+If any spawn fails, STOP and report the error — do NOT continue waiting.
+
+**After spawning, your turn is DONE.** Do NOT poll, sleep, call TaskOutput,
+or check status. Results arrive automatically as follow-up messages.
+When each reviewer finishes, its task is auto-completed via `taskId`.
+Task 7 (Merge findings) auto-unblocks when all 5 reviewer tasks complete.
+
+### Phase 3: Merge & Deduplicate Findings — Task 7
+
+Merge and deduplicate the findings from all 5 reviewers into a single combined findings list.
+
+### Phase 4: Present Review — Task 8
+
+Display findings grouped by severity:
+
+- **Critical issues** (must fix)
+- **Warnings** (should fix)
+- **Suggestions** (nice to have)

package/prompts/scout-and-plan.md

@@ -0,0 +1,21 @@
+---
+description: "Scout → plan without implementing — /scout-and-plan <task>"
+argument-hint: "<task>"
+---
+
+## Raw Arguments
+
+```text
+$ARGUMENTS
+```
+
+Use the subagent tool with a chain of 2 agents:
+
+1. **scout** — Explore the codebase to find all relevant code for the task from the raw arguments above.
+   Return a compressed summary of file locations, key functions, and dependencies.
+
+2. **planner** — Based on {previous}, create a detailed implementation plan:
+   - Files to modify/create
+   - Step-by-step changes
+   - Edge cases to handle
+   - Testing approach

package/rules/00-orchestrator-core.md

@@ -0,0 +1,42 @@
+# Orchestrator Core Rules
+
+## Scope
+
+> **If you are a SPECIALIST AGENT** (python-expert, git-expert, etc.):
+> IGNORE all rules below. Do your work directly using edit/write/bash.
+> These rules are for the ORCHESTRATOR only.
+
+---
+
+## Delegation Model
+
+The orchestrator delegates — never implements directly.
+⚠️ Pi does not enforce these restrictions — you SHOULD NOT violate them.
+
+**Allowed direct actions:** read files, run `mcpl`, ask questions, analyze, plan,
+route to agents via `subagent`, execute slash commands AND all their internal operations.
+
+Outside slash commands, never use edit, write, or bash directly (except `mcpl`) — delegate to specialists.
+
+**Always delegate via `subagent`:**
+
+- Code changes (edit/write) → language specialist
+- Git commands → git-expert
+- MCP tools → manager agents
+- Multi-file exploration → worker
+
+**Never delegate:** slash commands — execute them directly (see slash command rules).
+
+---
+
+## Before Implementation (MANDATORY)
+
+Before ANY code changes, run the pre-implementation checklist:
+
+→ **See the "Pre-Implementation Checklist" section below** — Do NOT skip this step.
+
+**Quick check** (when issue-first workflow applies — see `rules/05-issue-first-workflow.md` for skip conditions):
+
+- [ ] Root cause investigated? (read relevant code, understand the problem)
+- [ ] GitHub issue created?
+- [ ] On issue branch (`feat/issue-N-...` or `fix/issue-N-...`)?

package/rules/05-issue-first-workflow.md

@@ -0,0 +1,119 @@
+# Issue-First Workflow
+
+## Scope
+
+> **If you are a SPECIALIST AGENT:**
+> IGNORE this rule. This is for the ORCHESTRATOR only.
+
+---
+
+## Pre-Implementation Checklist (START HERE)
+
+Before ANY code changes, complete this checklist:
+
+1. **Should this workflow be skipped?** (see "SKIP" list below)
+   - YES → Do directly, skip remaining steps
+   - NO → Continue checklist
+
+2. **Root cause investigated?**
+   - Read the relevant source code — identify files, functions, and lines involved
+   - Understand the current behavior and why it happens
+   - Know what the fix looks like (at least conceptually)
+   - If the user's request is based on a misunderstanding, clarify before proceeding
+   - NO → Investigate first.
+   - YES → Continue
+
+3. **GitHub issue created?**
+   - NO → Create issue first (delegate to `github-expert`)
+   - YES → Continue
+
+4. **On correct branch?** (`feat/issue-N-...` or `fix/issue-N-...`)
+   - NO → Create branch from origin/main (delegate to `git-expert`)
+   - YES → Continue
+
+5. **User confirmed "work on it now"?**
+   - NO → Ask user
+   - YES → Proceed with implementation
+
+🚨 **NEVER create issues blindly from user requests.** Before creating ANY issue:
+
+- Read and understand the relevant code
+- Verify the problem exists (don't take the user's word — check the code)
+- Know what files/functions are involved
+- Have a conceptual fix in mind
+- If a fix PR already exists, link to it instead of creating a duplicate issue
+
+An issue without root cause analysis is a TODO, not a useful issue.
+
+---
+
+## When This Workflow Applies
+
+**USE for:**
+
+- New features, enhancements, bug fixes requiring code changes
+- Refactoring tasks
+- Multi-file modifications
+- Tasks benefiting from tracking/documentation
+
+**SKIP for:**
+
+- Trivial fixes (typos, single-line changes)
+- Questions, explanations, exploration (no code changes)
+- User says "just do it" / "quick fix"
+- Urgent hotfixes with time pressure
+
+---
+
+## Branch Workflow
+
+When user confirms, **delegate to git-expert**: fetch main (`git fetch origin main`), create branch (`git checkout -b <type>/issue-<N>-<short-desc> origin/main`).
+
+Branch types: `feat/`, `fix/`, `refactor/`, `docs/` — always prefixed with `issue-<N>-`.
+
+After creating the issue, present the issue number, title, and URL, then ask:
+'Do you want to work on it now?' Wait for explicit confirmation before creating the branch or starting implementation.
+
+---
+
+## Issue Format
+
+Delegate to `github-expert` with: type (fix/feat/refactor/docs), problem description, root cause analysis for bugs/fixes
+(affected files, functions, lines, and why), proposed approach, and requirements.
+
+**Every issue MUST include a `## Done` section with checkboxes** — the contract for when the issue can be closed:
+
+```markdown
+## Done
+
+- [ ] Deliverable 1
+- [ ] Deliverable 2
+- [ ] Deliverable 3
+```
+
+---
+
+## Tracking Progress
+
+Check off deliverables in the issue as you complete them.
+All code changes go through the review loop (see `rules/20-code-review-loop.md`).
+When all deliverables are complete, verify all `## Done` checkboxes are checked, ensure reviews/tests pass, then close with a summary comment.
+🚨 **NEVER close an issue with unchecked deliverables** — remove or mark N/A first if no longer needed.
+
+---
+
+## Integration with Code Review Loop
+
+Each deliverable follows the code review loop defined in `rules/20-code-review-loop.md`; once all deliverables pass review, close the issue.
+
+---
+
+## Edge Cases
+
+| Scenario | Behavior |
+|---|---|
+| User says "just fix it" | Skip workflow, do directly |
+| Partial requirements | Ask clarifying questions, then create issue |
+| Issue already exists | Ask to continue existing issue |
+| Urgent/hotfix | Skip workflow, note in commit message |
+| Multiple unrelated requests | Create separate issues for each |

package/rules/10-agent-routing.md

@@ -0,0 +1,58 @@
+# Agent Routing
+
+## Routing Table
+
+| Domain/Tool | Agent |
+|---|---|
+| Python (.py) | `python-expert` |
+| Go (.go) | `go-expert` |
+| Frontend (JS/TS/React/Vue/Angular) | `ts-expert` |
+| Java (.java) | `java-expert` |
+| Shell scripts (.sh) | `bash-expert` |
+| Markdown (.md) | `technical-documentation-writer` |
+| Docker | `docker-expert` |
+| Kubernetes/OpenShift | `kubernetes-expert` |
+| Jenkins/CI/Groovy | `jenkins-expert` |
+| Git operations (local) | `git-expert` |
+| GitHub (PRs, issues, releases, workflows) | `github-expert` |
+| Tests | `test-automator` |
+| Debugging | `debugger` |
+| API docs | `api-documenter` |
+| External repo security audit | `security-auditor` |
+| External AI agents (cursor, codex, gemini, claude, copilot, etc.) | `/acpx-prompt` |
+| External library/framework docs (React, FastAPI, Django, etc.) | `docs-fetcher` |
+
+## Routing by Intent, Not Tool
+
+Route based on the task intent, not just the tool being used.
+
+- Running Python tests? → `python-expert` (not bash-expert)
+- Editing Python files? → `python-expert` (even with sed/awk)
+- Creating a PR? → `github-expert` (not git-expert)
+- External library docs? → `docs-fetcher` (not direct fetch)
+
+## Documentation Routing (MANDATORY)
+
+The orchestrator MUST NEVER fetch external docs directly — always delegate to `docs-fetcher`, which tries `llms.txt` first and extracts only relevant sections.
+
+**Spawn `docs-fetcher` when:**
+
+- Fetching library/framework docs (React, FastAPI, Django, etc.)
+- Looking up config guides or API references for external tools
+
+**Skip when:**
+
+- Standard library only (no external dependencies)
+- Already fetched docs in current conversation
+
+## Agents Not in Routing Table
+
+Some agents are dispatched internally by rules or prompt templates, not by the routing table:
+
+- `code-reviewer-quality`, `code-reviewer-guidelines`, `code-reviewer-security`, `code-reviewer-docs`, `code-reviewer-spec` — dispatched via `rules/20-code-review-loop.md`
+- `issue-reviewer-spec`, `issue-reviewer-feasibility`, `issue-reviewer-scope` — dispatched via `prompts/issue-review.md`
+- `reviewer` — dispatched via prompt templates
+
+## Fallback
+
+**Fallback:** No specialist? → `worker` agent

package/rules/15-mcp-launchpad.md

@@ -0,0 +1,46 @@
+# MCP Launchpad (mcpl)
+
+Use the `mcpl` command for all MCP server interactions.
+If a task requires functionality outside current capabilities, check `mcpl` for available tools.
+Orchestrator discovers tools via `mcpl search`/`mcpl list` and delegates execution to agents.
+
+---
+
+## mcpl Commands
+
+| Command                                      | Purpose                                             |
+|----------------------------------------------|-----------------------------------------------------|
+| `mcpl search "<query>"`                      | Search all tools (shows required params, 5 results) |
+| `mcpl search "<query>" --limit N`            | Search with more results                            |
+| `mcpl list`                                  | List all MCP servers                                |
+| `mcpl list <server>`                         | List tools for a server (shows required params)     |
+| `mcpl list --refresh`                        | Refresh and list all MCP servers                    |
+| `mcpl inspect <server> <tool>`               | Get full schema                                     |
+| `mcpl inspect <server> <tool> --example`     | Get schema + example call                           |
+| `mcpl call <server> <tool> '{}'`             | Execute tool (no arguments)                         |
+| `mcpl call <server> <tool> '{"param": "v"}'` | Execute tool with arguments                         |
+| `mcpl call <server> <tool> '{}' --no-daemon` | Bypass daemon for debugging                         |
+| `mcpl verify`                                | Test all server connections                         |
+| `mcpl session status`                        | Check daemon and server connection status           |
+| `mcpl session stop`                          | Restart daemon (stops current, auto-restarts)       |
+| `mcpl config`                                | Show current configuration                          |
+
+---
+
+## Workflow
+
+**Never guess tool names** — always discover first.
+
+1. **Search** → `mcpl search "list projects"` (or `mcpl list <server>` if you know the server)
+2. **Inspect** → `mcpl inspect sentry search_issues --example` (for complex tools)
+3. **Call** → `mcpl call vercel list_projects '{"teamId": "team_xxx"}'`
+
+---
+
+## Error Recovery
+
+On failure, mcpl suggests fixes: similar tool names (not found), required params + example (missing params), or expected types (validation errors).
+
+## Troubleshooting
+
+- **Server not connecting**: `mcpl verify` → **Stale connections**: `mcpl session stop` then retry → **Timeouts**: set `MCPL_CONNECTION_TIMEOUT=120`

package/rules/20-code-review-loop.md

@@ -0,0 +1,234 @@
+# Code Review Loop (MANDATORY)
+
+After ANY code change, send to ALL 6 agents (5 reviewers + test-automator) IN PARALLEL. **Never skip the first review.**
+
+## Commit enforcement
+
+When `review_loop_enforcement` is enabled, the enforcement rule in `enforcement.ts` blocks `git commit` unless:
+
+- Review status is `clean` (all reviewers returned 0 findings)
+- `tests_passed: true` (test-automator or test command succeeded)
+
+**You MUST run the review loop BEFORE attempting `git commit`.** The enforcement rule will reject the commit otherwise.
+Do NOT try to work around it — run the actual review agents to reach `clean` status.
+
+🚫 **NEVER manipulate review state directly.** Do not import `pi-config-review-state.ts`,
+call `addReviewerPending`/`recordReviewerResult` from bash, write to the JSON file,
+or use any method to fake a clean state. The enforcement system detects and blocks this.
+The ONLY way to reach `clean` status is to run the actual review agents.
+
+Resolution: project `.pi/pi-config-settings.json` → global `~/.pi/pi-config-settings.json` → `PI_REVIEW_LOOP_ENFORCEMENT` env var → `false`.
+
+- MUST loop until clean or the max cycle cap is reached — see "Cycle Definition & Max Cycles" below.
+
+If disabled:
+
+- Single review pass is sufficient
+- No commit blocking
+
+**In both cases, all 6 agents are always called.** `review_loop_enforcement` controls whether the loop repeats; when enabled,
+`review_loop_max_cycles` caps **total** cycles including the first (see Cycle Definition below).
+
+### Cycle Definition & Max Cycles
+
+One **cycle** = call all 6 reviewers (in parallel) → fix/explain findings → end of cycle.
+
+**The cycle count IS the `cycle` field in `pi-config-review-state.json`** — the same counter shown by
+`/review-status` and the review UI status card. It increments each time reviewers are (re-)dispatched
+for a fresh pass. Step 5's branches below MUST compare against that same counter — do not track cycles
+mentally or separately.
+
+The review loop repeats for at most `review_loop_max_cycles` cycles (default `3`, range `1`-`10` only;
+current value: `{{REVIEW_LOOP_MAX_CYCLES}}`), including the first cycle. Invalid values fall through to the
+next resolution layer / default `3` — see `dev-docs/project-settings.md` for the full resolution order.
+Disable the review loop via `review_loop_enforcement: false` — not via max_cycles.
+
+Cap check is after 5a; it only blocks `go to 2` (re-dispatch of step 2 / all 6 agents,
+including test-automator), not completing the current cycle's fix/explain.
+
+**After 5a completes on the max cycle, two outcomes — neither unblocks `git commit`**
+(still controlled solely by `review_loop_enforcement`; status must be `clean` + `tests_passed: true`):
+
+- **Not fixed** (explained why not) → outstanding — report them.
+- **Fixed** (verification blocked by the cap) → cannot re-dispatch to confirm clean — report that
+  verification is blocked by the cap, NOT "leftovers from skipping 5a".
+
+**Example (`max_cycles=3`):**
+
+```text
+cycle1: dispatch → findings → 5a (fix|explain) → re-dispatch (cycle < max)
+cycle2: dispatch → findings → 5a (fix|explain) → re-dispatch (cycle < max)
+cycle3: dispatch → findings → 5a (fix|explain) → cycle >= max → stop (no cycle4)
+```
+
+```text
+1. Specialist writes/fixes code
+2. Send ALL 6 agents IN PARALLEL (async): 5 reviewers + test-automator
+3. Wait for all 6 to complete
+4. Merge & deduplicate review findings
+5. Has findings OR tests failed?
+   ── Neither? ↓ status: clean, tests_passed: true
+   ── Findings and/or tests failed? → ALWAYS run 5a first: fix code OR explain why not, for EACH finding;
+      fix code for failing tests. Then check state.cycle (from `pi-config-review-state.json`):
+        · cycle < {{REVIEW_LOOP_MAX_CYCLES}}? → go to 2 (re-run all 6 with prior findings + responses)
+        · cycle >= {{REVIEW_LOOP_MAX_CYCLES}}? → **STOP** (terminal): report the two-outcome result
+          (see "Cycle Definition & Max Cycles" above). Do NOT proceed to step 6.
+6. NOW you can commit — the pre-commit hook will pass (only when status is `clean` AND `tests_passed: true`)
+✅ DONE — commit/push allowed (enforcement checks status: clean AND tests_passed: true)
+```
+
+🚨 **Step 6 applies only when clean.** Do NOT attempt `git commit` before reaching `clean` + `tests_passed: true`.
+The enforcement rule blocks commits until this is satisfied — if it blocks you, run the reviewers.
+**After a cap stop:** report the two-outcome result (**Not fixed** → outstanding, **Fixed** → verification
+blocked); raise `review_loop_max_cycles` or disable `review_loop_enforcement` if needed — do **not**
+return to step 2 (re-dispatch of all 6 agents, including test-automator).
+
+## Review Agents
+
+Six agents run in parallel for comprehensive coverage:
+
+| Agent | Focus |
+|---|---|
+| `code-reviewer-quality` | General code quality and maintainability |
+| `code-reviewer-guidelines` | Project guidelines and style adherence (AGENTS.md) |
+| `code-reviewer-security` | Bugs, logic errors, and security vulnerabilities |
+| `code-reviewer-docs` | Documentation quality, completeness, and accuracy |
+| `code-reviewer-spec` | Code/PR/issue spec alignment and compliance |
+| `test-automator` | Run project tests (pytest, node tests, pre-commit) |
+
+**All 6 MUST be invoked as async subagents (`async: true`) in the same assistant turn.
+Do NOT block waiting for results — continue working while they run.**
+
+Send reviewers "Review the code changes" — never mention `git diff HEAD` in the task prompt.
+Reviewers get `$PI_REVIEW_BASE_BRANCH` env var and use `git diff origin/$PI_REVIEW_BASE_BRANCH...HEAD` themselves.
+
+Reviewers return structured JSON: `{"findings": [{"severity": "...", "file": "...", "line": N, "description": "...", "suggestion": "..."}]}`.
+The async runner validates the output is valid JSON and retries if not (up to 3 times).
+
+Overlapping scope is intentional for comprehensive coverage; step 4's deduplication handles duplicates.
+
+## Deduplication Criteria
+
+Same file/line + same issue or root cause = duplicate — keep the most actionable version.
+Conflicts follow priority: security > correctness > performance > style; complementary findings on the same code are kept.
+
+**Spec findings are never deduplicated against non-spec findings.** Findings from `code-reviewer-spec`
+(missing deliverables, scope creep, spec misalignment) are never suppressed by findings from other
+reviewers, even on the same file/line. A quality finding about *how* code is written does not
+address *whether* the code matches the spec. Always keep both. Spec findings CAN still be
+deduplicated against other spec findings when they are truly the same issue.
+
+## Step 5a: Respond to Findings (when `review_loop_enforcement` is enabled)
+
+For each finding from step 4, do ONE of:
+
+1. **Fix it** — change the code to address the finding
+2. **Explain why not** — provide a specific technical reason (e.g., "pre-existing pattern,
+   changing it would break X", "intentional for performance", "out of scope for this PR")
+
+**Every finding MUST get a response. No silent ignoring.**
+
+When re-running reviewers (step 2, cycle N+1), pass the prior cycle's findings and
+responses in each reviewer's task prompt using this format:
+
+```text
+<prior-review-cycle>
+The following findings were raised in review cycle {N}. Each has been either fixed or
+explained. Do NOT re-raise findings that were adequately addressed. Only re-raise if:
+- The code fix is incorrect or incomplete
+- The explanation is invalid or factually wrong
+- You disagree with the reasoning (explain why)
+
+Findings with valid explanations that you accept → do not re-raise.
+Findings that were fixed in code → verify the fix, do not re-raise if correct.
+
+{numbered list of findings with their fix/explanation}
+</prior-review-cycle>
+```
+
+**Reviewers MUST respect valid responses:**
+
+- If a finding was fixed → verify the fix is correct, don't re-raise
+- If a finding was explained with a valid technical reason → accept it, don't re-raise
+- If the explanation is wrong or the fix is incomplete → re-raise with specific pushback
+
+**When `review_loop_enforcement` is disabled:** Step 5a is optional. Single review pass
+is sufficient — fix what you agree with, skip what you don't. No need to explain skips.
+
+## Key Rules
+
+Never skip code review — all 6 agents always run (5 reviewers + test-automator).
+When `review_loop_enforcement` is enabled: loop, respond to each finding (fix or explain), and re-run all 6 from step 2
+until clean or the cycle cap is reached — see "Cycle Definition & Max Cycles" above for the exact stop conditions.
+When disabled: single pass is sufficient; no mandatory re-loop or explanations.
+Minor test/config-only fixes skip re-review (go to step 5); substantive code changes require full re-review.
+
+## Test Tracking
+
+Test results are tracked in `pi-config-review-state.json` via the `tests_passed` field.
+This is **code-enforced** — commit/push is blocked unless `tests_passed: true` (when `review_loop_enforcement` is enabled).
+
+**How `tests_passed` gets set:**
+
+- **Bash hook detection:** When any agent runs a test command (`pytest`, `npm test`, `npx tsx --test`, `tox`, `go test`, `vitest`, `jest`, `mocha`),
+  the enforcement hook detects it and auto-marks `tests_passed` based on exit code.
+- **Agent completion:** When `test-automator` or `test-runner` agents complete, their result auto-marks `tests_passed`.
+- **Reset on edit:** Any file edit triggers `markNeedsReview()`, which resets `tests_passed: false` —
+  preventing stale results.
+
+**Duplicate test run avoidance:** If a specialist already ran tests before the review loop, `tests_passed` may already be `true`.
+Any file edit resets it, so test-automator in the parallel batch always validates the latest code.
+
+## Baseline Test Comparison (Step 5)
+
+Compare against baseline before declaring test failures as blockers:
+
+```bash
+BASELINE_DIR="${PROJECT_TMP_DIR}"
+mkdir -p "$BASELINE_DIR"
+
+# 1. Save ALL changes (staged + unstaged + untracked)
+git diff HEAD > "$BASELINE_DIR/baseline.patch"
+git ls-files --others --exclude-standard > "$BASELINE_DIR/untracked.list"
+
+# 2. Reset to clean state
+git reset --hard HEAD
+xargs -r -d '\n' rm -f < "$BASELINE_DIR/untracked.list" 2>/dev/null || true
+
+# 3. Run tests → record baseline failure count
+
+# 4. Restore changes
+git apply "$BASELINE_DIR/baseline.patch" \
+  || git apply --3way "$BASELINE_DIR/baseline.patch"
+
+# 5. Clean up
+rm -f "$BASELINE_DIR/baseline.patch" "$BASELINE_DIR/untracked.list"
+
+# 6. Run tests → record current failure count
+```
+
+Only **new failures** (current minus baseline) block the review; pre-existing failures are noted but don't block.
+If both `git apply` methods fail, skip baseline comparison and note "baseline comparison unavailable" — do NOT block on all failures.
+
+## Staged Review Mode (Automated Workflows)
+
+For automated review flows (autorabbit, autoqodo), use **two-stage order** instead of parallel:
+
+1. **Stage 1 — Spec Compliance:** Does code meet requirements? All deliverables implemented? No scope creep?
+   Loop Stage 1 until passed OR the shared cycle cap is reached.
+2. **Stage 2 — Code Quality:** Quality, security, guidelines adherence.
+   Loop Stage 2 until passed OR the shared cycle cap is reached.
+
+**Staged cycle definition:** one **cycle** = one pass of the *current* stage's reviewers (in parallel)
+→ fix/explain that stage's findings → end of cycle. This mirrors the parallel-mode cycle definition
+(see "Cycle Definition & Max Cycles" above), scoped to one stage's reviewers instead of all 6.
+
+**The `review_loop_max_cycles` cap is shared across both stages — one total budget, not one per stage.**
+Stage 1 and Stage 2 both draw from and increment the same `cycle` counter in
+`pi-config-review-state.json`. Cap check, 5a-before-cap, and two-outcome reporting follow
+"Cycle Definition & Max Cycles" above. Stage-specific stops: if Stage 1 is **not clean** when the cap is hit, stop entirely — do not proceed
+to Stage 2 (covers both **Not fixed** and **Fixed** (verification blocked)). If hit during Stage 2,
+stop looping Stage 2.
+
+Don't polish code that doesn't meet spec — it wastes work.
+Parallel mode (all 6 agents at once) remains default for manual reviews.