prizmkit 1.1.111 → 1.1.113

package/bundled/skills/prizmkit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "prizmkit"
-description: "Full-lifecycle dev toolkit index. Routes to the right PrizmKit skill for spec-driven development, Prizm docs, code quality, deployment, and knowledge management. Use when the user asks 'which command?', 'help', 'how do I start a feature', 'get started', 'what tools', 'dev workflow', 'lifecycle', or '/prizmkit'. Use this as the entry point for the full PrizmKit development lifecycle. (project)"
+description: "Full-lifecycle PrizmKit development toolkit index. Routes users to the right core skill for project init, planning, implementation, review, docs maintenance, testing, commit, and deploy. Use when the user asks 'which command?', 'help', 'how do I start a feature', 'get started', 'what tools', 'dev workflow', 'lifecycle', or '/prizmkit'. Clarifies Direct edit vs Fast path vs Full path and asks whether ambiguous 'ship it' means commit or deploy. (project)"
 ---
 
 # PrizmKit — Full-Lifecycle Development Toolkit
@@ -10,84 +10,130 @@ description: "Full-lifecycle dev toolkit index. Routes to the right PrizmKit ski
 - User wants to understand the PrizmKit development lifecycle
 - User invokes "/prizmkit" or asks about dev workflow
 - User is new to the project and needs orientation
+- User says an ambiguous phrase such as "ship it" and intent could mean commit or deploy
 
 ### When NOT to Use
-- User already knows which specific skill to use — invoke it directly
-- Mid-implementation — use the specific skill needed (/prizmkit-implement, /prizmkit-code-review, etc.)
-- User wants to execute immediately without orientation — go directly to /prizmkit-plan or /prizmkit-implement
+- User already knows which specific skill to use — invoke that skill directly
+- Mid-implementation — use the specific skill needed (`/prizmkit-implement`, `/prizmkit-code-review`, etc.)
+- User wants to execute immediately without orientation — route to the correct specific skill
 
 ## Task Execution Model
 
-PrizmKit uses **headless mode** — each task runs as an independent AI CLI session with NO context carryover between tasks. Every session starts by reading docs and ends by maintaining docs.
+PrizmKit uses self-contained task sessions. Each task starts by reading project context and ends by preserving durable knowledge when the change warrants it.
 
-**Per-task flow**:
-```
-read docs → plan → implement → code-review → retrospective → committer
-```
+Per-task context normally comes from:
 
-Each task begins by reading context at two levels:
+**Application level**:
+- `.prizmkit/prizm-docs/root.prizm` — L0 project architecture index
+- `.prizmkit/plans/project-brief.md` — product vision generated during project initialization
+- `.prizmkit/config.json` — tech stack and runtime config
 
-**Application level** (read every session):
-- `.prizmkit/prizm-docs/root.prizm` — L0 project architecture index (modules, tech stack, conventions)
-- `.prizmkit/plans/project-brief.md` — user's product vision checklist (generated during project initialization)
-- `.prizmkit/config.json` — tech stack config, deploy strategy
+**Task level**:
+- `spec.md` / `plan.md` — change artifact for the current task
+- Relevant `.prizmkit/prizm-docs/<module>.prizm` L1 docs
+- Relevant L2 docs when they exist; if an L2 doc is missing, implementation reads the target source files as fallback and retrospective may create L2 afterward
 
-**Task level** (read for the specific task):
-- `spec.md` / `plan.md` — task specification and implementation plan
-- `.prizmkit/prizm-docs/<module>.prizm` (L1/L2) — architecture docs for affected modules (TRAPS, DECISIONS, INTERFACES)
+## Lifecycle Paths
 
-Each cycle produces spec, plan, and task artifacts that create a traceable record of what was built and why. `.prizmkit/prizm-docs/` stays in sync through retrospective, so the next session starts with up-to-date context.
+Choose the lightest path that still protects correctness. Explain the chosen path briefly before proceeding.
 
-**Fast path** — for small, well-scoped changes, always ask user whether to use fast path:
-```
-/prizmkit-plan → /prizmkit-implement → /prizmkit-committer
+### Direct edit
+
+Use for low-risk work with no meaningful behavior or interface impact.
+
+Examples:
+- Typo or wording fixes
+- Pure formatting
+- Small documentation edits
+- Tiny config tweaks with no behavior change
+
+Direct edit does not create `spec.md` or `plan.md`. Run only the verification that fits the edit.
+
+### Fast path
+
+Use for small, well-scoped behavior changes where a full lifecycle would add more process than value.
+
+Default flow:
+
+```text
+simplified /prizmkit-plan -> /prizmkit-implement -> conditional test/retro -> /prizmkit-committer
 ```
 
-### Development Scenarios
+Rules:
+- Use a simplified `plan.md` with a Tasks section so implementation can resume safely.
+- Full `/prizmkit-code-review` is optional unless risk or user request requires it.
+- Run `/prizmkit-test` only when the change hits the risk-triggered testing criteria.
+- Run `/prizmkit-retrospective` only when structure, interfaces, dependencies, behavior, or durable project knowledge changed.
 
-PrizmKit supports any development scenario through the same skill chain. `/prizmkit-plan` produces `spec.md` + `plan.md` regardless of the task type:
+### Full path
 
-| Scenario | Artifacts | When to Use |
-|----------|-----------|-------------|
-| **Feature** | `spec.md` → `plan.md` → code | New functionality, UI, API, data model changes |
-| **Bug Fix** | `spec.md` → `plan.md` → code | Complex defects, regressions, crash fixes. Simple bugs can use fast path directly. |
-| **Refactor** | `spec.md` → `plan.md` → code | Restructure, extract, rename, performance. No behavior change. |
+Use for high-risk work, multi-module changes, new capabilities, architecture changes, public API/interface changes, data model/schema changes, security/permission/payment logic, or unclear requirements.
+
+Default flow:
 
-All three follow the same per-task flow. Detailed documentation policies (when to update `.prizmkit/prizm-docs/`, when to skip steps) are defined within each skill — not here.
+```text
+/prizmkit-plan -> /prizmkit-implement -> risk-triggered /prizmkit-test if needed -> /prizmkit-code-review -> /prizmkit-retrospective -> /prizmkit-committer
+```
+
+Rules:
+- `/prizmkit-plan` produces a full `spec.md` and `plan.md`.
+- `/prizmkit-code-review` is the default quality gate.
+- `/prizmkit-retrospective` is the normal development writer for `.prizmkit/prizm-docs/`.
+- `/prizmkit-test` is risk-triggered rather than always mandatory.
 
-### Best Practices for AI-Driven Development
+## Risk-Triggered Testing
 
-**Monorepo structure recommended**: Keep frontend, backend, and shared libraries in one repository. AI needs visibility into the full call chain — cross-repo references are invisible to it. If you have a multi-repo setup, add all related repos to the AI workspace so module boundaries and API contracts are discoverable.
+Recommend or require `/prizmkit-test` when the change affects:
+- Observable behavior
+- Public interfaces or API contracts
+- Data models, migrations, or schema
+- Security, permissions, authentication, billing, payments, or entitlements
+- Deployment readiness or user-requested quality verification
 
-**Module organization**: Ensure every meaningful module has a `.prizmkit/prizm-docs/` L1 doc. AI reads TRAPS and DECISIONS before modifying files — undocumented modules get no guardrails.
+Skip `/prizmkit-test` for pure docs, formatting, internal renames with no behavior change, or tiny config tweaks unless the user asks for tests.
 
-**Small, focused tasks**: Break large features into tasks that can each be completed in one AI session. The pipeline handles this automatically via `/prizmkit-plan` task decomposition.
+## Development Scenarios
+
+PrizmKit supports any development scenario through the same skill chain. `/prizmkit-plan` produces a change artifact (`spec.md` + `plan.md`) regardless of whether the task is a feature, bug fix, refactor, or migration.
+
+| Scenario | Artifacts | When to Use |
+|----------|-----------|-------------|
+| Feature | `spec.md` -> `plan.md` -> code | New functionality, UI, API, data model changes |
+| Bug fix | `spec.md` -> `plan.md` -> code | Complex defects, regressions, crash fixes; simple bugs can use Direct edit or Fast path |
+| Refactor | `spec.md` -> `plan.md` -> code | Restructure, extract, rename, performance work with behavior preservation |
 
 ## Core Skill Reference
 
 | Skill | Purpose | Trigger Phrases |
 |-------|---------|-----------------|
-| `/prizmkit-plan` | Specify and plan: turns natural language into spec.md + plan.md with architecture and executable tasks. Use as the **first implementation step** in the lifecycle, before /prizmkit-implement. | "specify", "plan", "new feature", "I want to add...", "architect", "break it down" |
-| `/prizmkit-implement` | Execute plan.md tasks with **TDD approach**, respecting task ordering and dependencies. Use after /prizmkit-plan as the **implementation step** of the lifecycle. | "implement", "build", "code it", "start coding" |
-| `/prizmkit-code-review` | **Iterative review-fix loop** against spec and plan (max 3 rounds until PASS). Spawns a reviewer agent; the main orchestrator applies accepted fixes directly. Use after /prizmkit-implement as the **quality gate**. | "review", "check code", "code review", "is it ready to commit" |
-| `/prizmkit-retrospective` | Incremental .prizmkit/prizm-docs/ maintainer: (1) **structural sync** of KEY_FILES/INTERFACES/DEPENDENCIES, (2) inject **TRAPS/RULES/DECISIONS**. Run after code review and **before committing**. | "retrospective", "retro", "update docs", "sync docs", "wrap up" |
-| `/prizmkit-committer` | **Pure git commit** with safety checks: stages files, generates Conventional Commits message, commits. Does NOT modify docs — run /prizmkit-retrospective first. Use as the **final lifecycle step**. | "commit", "submit", "finish", "ship it" |
-| `/prizmkit-test` | **Full-stack test orchestration**: detects architecture, analyzes coverage gaps, generates missing unit/integration/E2E tests with a boundary coverage matrix, and outputs a unified report. Use after development and **before deploy** for quality verification. | "test", "run tests", "check quality", "verify code", "generate tests", "add tests" |
-| `/prizmkit-deploy` | **Universal deployment gateway**: discovers project type/target, automates SSH Linux PM2+Nginx+blue-green deploys, and manages operations — status, logs, restart, rollback, health checks. | "deploy", "ship it", "go live", "rollback", "deploy status" |
-| `/prizmkit-init` | **Project bootstrap**: scans codebase, generates .prizmkit/prizm-docs/ and project brief, detects tech stack. Use as the **first lifecycle step for new projects**, or after `npx prizmkit install`. | "init", "initialize", "take over this project", "bootstrap" |
-| `/prizmkit-prizm-docs` | **Doc system spec and management**: defines the 3-level .prizmkit/prizm-docs/ hierarchy (L0/L1/L2), format rules, size limits, and loading protocol. Use for doc init/status/rebuild/validate/migrate. For **incremental code-driven updates**, use /prizmkit-retrospective instead. | "check docs", "rebuild docs", "validate docs", "prizm docs" |
-
-**Reading guide**:
-- Need code structure/modules/interfaces/traps/decisions? → `.prizmkit/prizm-docs/`
-
-## Quick Start (First-Time Setup)
-
-1. `npx prizmkit install .` → installs skills, rules (`prizm-documentation.md`, `prizm-commit-workflow.md`), hooks, platform scaffolding
-2. `/prizmkit-init` → scans project code, generates `.prizmkit/prizm-docs/`, detects tech stack, populates `.prizmkit/config.json`
-3. `/prizmkit-plan` → specify your first feature → produces spec.md + plan.md
-4. `/prizmkit-implement` → TDD implementation following the plan
-5. `/prizmkit-code-review` → review before commit
-6. `/prizmkit-retrospective` → sync `.prizmkit/prizm-docs/` with changes
-7. `/prizmkit-committer` → safe Conventional Commit
-
-> **Note**: Rules and hooks are installed by `npx prizmkit install`, not by `/prizmkit-init`.
+| `/prizmkit-init` | Project bootstrap entry point: use before planning in a newly installed/taken-over project; scans codebase, generates `.prizmkit/prizm-docs/`, config, and project brief. | "init", "initialize", "take over this project", "bootstrap" |
+| `/prizmkit-plan` | First implementation planning step: run ahead of `/prizmkit-implement` to turn natural language into `spec.md` + `plan.md` with executable tasks. | "specify", "plan", "new task", "architect", "break it down" |
+| `/prizmkit-implement` | Implementation step: use after `/prizmkit-plan` to execute `plan.md` tasks with TDD where applicable, task order, and checkpoints. | "implement", "build", "code it", "start coding" |
+| `/prizmkit-test` | Risk-triggered quality gate: run after implementation when behavior, interfaces, data, security, or deploy risk requires tests and boundary coverage. | "test", "run tests", "verify", "quality check", "boundary tests" |
+| `/prizmkit-code-review` | Full path quality gate: run after implementation; requires the dedicated reviewer agent in the active checkout and stops if that launch mode is unavailable. | "review", "check code", "code review", "is it ready to commit" |
+| `/prizmkit-retrospective` | Docs maintenance step: run after review/implementation when structure, interfaces, dependencies, behavior, or durable knowledge changed. | "retrospective", "retro", "update docs", "sync docs", "wrap up" |
+| `/prizmkit-committer` | Final lifecycle commit step: use after required gates are satisfied; safely stages and creates a Conventional Commit without changing changelog by default. | "commit", "submit", "finish", "done" |
+| `/prizmkit-prizm-docs` | Documentation system entry point: use for init/status/rebuild/validate/migrate or out-of-band repair, not normal development sync. | "initialize docs", "check docs", "rebuild docs", "validate docs", "docs drifted" |
+| `/prizmkit-deploy` | Deployment lifecycle entry point: use after code is ready to release or for existing deployment operations. | "deploy", "go live", "take live", "release", "rollback", "deploy status" |
+
+## Ambiguous Ship Intent
+
+If the user says only "ship it", ask whether they mean:
+
+1. Commit the current changes with `/prizmkit-committer`.
+2. Deploy or release the project with `/prizmkit-deploy`.
+
+Do not route ambiguous "ship it" directly to commit or deploy without clarification.
+
+## Quick Start
+
+1. `npx prizmkit install .` — install skills, rules, hooks, and platform scaffolding
+2. `/prizmkit-init` — scan project, generate docs/config/brief
+3. `/prizmkit-plan` — create a change artifact for the first non-trivial task
+4. `/prizmkit-implement` — implement plan tasks
+5. Run `/prizmkit-test` if risk-triggered
+6. Run `/prizmkit-code-review` for Full path or when requested/risk-triggered
+7. Run `/prizmkit-retrospective` if docs or durable knowledge changed
+8. `/prizmkit-committer` — safe Conventional Commit
+
+> Rules and hooks are installed by `npx prizmkit install`, not by `/prizmkit-init`.

package/bundled/skills/prizmkit-code-review/SKILL.md

@@ -1,182 +1,163 @@
 ---
 name: "prizmkit-code-review"
-description: "Iterative review-fix loop against spec and plan. Spawns the dedicated prizm-dev-team-reviewer agent, filters findings, then the main orchestrator applies accepted fixes directly. Loops until PASS (max 3 rounds). Use after /prizmkit-implement as quality gate. Trigger on: 'review', 'check code', 'code review', 'is it ready to commit'. (project)"
+description: "Iterative review-fix loop against spec and plan. Always uses the dedicated prizm-dev-team-reviewer agent in the active checkout with current-workspace / active-checkout / no-worktree launch; the Main Agent filters findings and applies accepted fixes directly. If the current platform cannot start an active-checkout reviewer, stop with tool incompatibility instead of falling back to Main-Agent self-review. Loops until PASS or max 3 rounds. Use after /prizmkit-implement for Full path quality gate or when the user says 'review', 'check code', 'code review', or 'is it ready to commit'. (project)"
 ---
 
 # PrizmKit Code Review
 
-An iterative review-fix loop that reviews code changes against the spec and plan, then automatically fixes accepted issues. Uses two separated roles:
+An iterative review-fix loop that checks workspace changes against the task spec and plan. It separates review judgment from fix application by requiring a dedicated `prizm-dev-team-reviewer` subagent in the active checkout. Main Agent applies accepted fixes directly after filtering reviewer findings.
 
-- **Reviewer Agent** (`prizm-dev-team-reviewer`, read-only): analyzes orchestrator-provided workspace context against spec goals and plan decisions, then produces structured findings
-- **Main Agent** (orchestrator): filters Reviewer findings for reasonableness, applies accepted fixes directly in the active checkout, and coordinates the loop
+Review modes:
+- `reviewer-agent-active-checkout`: required mode. Always spawn `prizm-dev-team-reviewer` in the current active checkout with no worktree or remote isolation.
+- `not-run-no-changes`: no workspace changes were detected.
 
-The loop repeats until the Reviewer finds no issues or the max round limit is reached.
+If the platform cannot launch `prizm-dev-team-reviewer` in current-workspace / active-checkout / no-worktree mode, stop with this tool incompatibility message:
+
+```text
+Cannot run /prizmkit-code-review because this platform cannot start prizm-dev-team-reviewer in the active checkout without worktree isolation.
+```
 
 ### When to Use
-- After `/prizmkit-implement` to verify code quality before commit
-- User says "review", "check code", "review my implementation"
-- As a quality gate before `/prizmkit-committer`
+- After `/prizmkit-implement` as the Full path quality gate
+- For Fast path only when risk, scope, or user request warrants review
+- User says "review", "check code", "review my implementation", or "is it ready to commit"
+- Before `/prizmkit-committer` when the chosen lifecycle path requires review
 
 ### When NOT to Use
-- Trivial changes (typo, single-line config) → commit directly
-- No spec.md or plan.md exists → nothing to review against
+- Direct edit or low-risk Fast path where review is not required
+- No spec.md or plan.md exists and there is no clear task goal to review against
+- Trivial typo, formatting, or config-only changes that the user wants committed directly
 
 ## Input
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| `artifact_dir` | No | Directory containing spec.md + plan.md. If omitted, scan `.prizmkit/` subdirectories for the most recently modified directory with a `plan.md` whose tasks are all completed. When invoked as a handoff step, reuse the caller's `artifact_dir` rather than re-detecting. |
+| `artifact_dir` | No | Directory containing `spec.md` + `plan.md`. If omitted, scan `.prizmkit/` subdirectories for the most recently modified directory with a completed `plan.md`. When invoked as a handoff step, reuse the caller's `artifact_dir` rather than re-detecting. |
 
 ## Phase 0: Context Loading
 
-1. **Read spec.md** from the artifact directory — extract goals and acceptance criteria.
-2. **Read plan.md** from the artifact directory — extract architecture decisions and completed tasks.
-3. **Read scoped test report when present**:
-   - If `{artifact_dir}/test-report-path.txt` exists, read the path, then read that `/prizmkit-test` report.
-   - Extract `Scope`, `Generated / Updated Tests`, `In-Scope Failures`, `Baseline Failures`, `Out of Scope Gaps`, `Boundary Matrix` / `Boundary Completion Gate` when present, and `Verdict`.
-   - If `context-snapshot.md` contains `## PrizmKit Test Gate`, read that summary too.
-   - If this is a feature artifact under `.prizmkit/specs/` and no test report pointer or summary exists, pass `No scoped /prizmkit-test report found (expected for pre-test review)` into the Reviewer context as informational scope context only. Do not ask the Reviewer to report it as a missing gate unless the calling workflow explicitly requires a prior test report.
-4. **Read dev rules** (if configured): If `.prizmkit/prizm-docs/root.prizm` exists, read it and check for a `RULES:` line. If present, read all referenced `.prizmkit/rules/<layer>-rules.md` files. If `root.prizm` or a referenced rules file does not exist, continue with "No custom dev rules configured — use general best practices."
-5. **Capture workspace context from the active checkout** (do NOT open a separate worktree or clone):
-   - Run `git status` to list modified, staged, untracked, and deleted files.
-   - Run `git diff` for unstaged changes and `git diff --cached` for staged changes.
-   - For new (untracked) files and renamed files in `git status`, note their full paths so the Reviewer can request targeted reads.
-   - Capture the current project context: read `.prizmkit/prizm-docs/root.prizm` for relevant RULES, and the artifact's `plan.md` for architecture decisions — this is the reviewer's context baseline.
-   - The workspace context is the **primary review scope**. The Reviewer must review this context and request only targeted file reads for lines it needs — it must not rediscover or re-index the whole repository.
-   - If no changes are detected, skip Phase 1 and proceed to Phase 2 with verdict PASS, rounds 0, and an empty findings list. Always write `review-report.md`; downstream pipeline steps use it as the review gate.
+1. Read `spec.md` from the artifact directory and extract goals plus acceptance criteria.
+2. Read `plan.md` from the artifact directory and extract architecture decisions plus completed tasks.
+3. Read scoped `/prizmkit-test` report when present:
+   - If `{artifact_dir}/test-report-path.txt` exists, read the pointed report.
+   - Extract Scope, Generated / Updated Tests, In-Scope Failures, Baseline Failures, Out of Scope Gaps, Boundary Matrix / Boundary Completion Gate, and Verdict when present.
+   - If no test report exists, pass `No scoped /prizmkit-test report found` as informational context. Do not treat missing tests as a review finding unless the current lifecycle path explicitly required testing.
+4. Read dev rules when configured: load `.prizmkit/prizm-docs/root.prizm`, then referenced `.prizmkit/rules/<layer>-rules.md` files if any exist.
+5. Capture active checkout workspace context:
+   - `git status`
+   - `git diff`
+   - `git diff --cached`
+   - full paths for untracked and renamed files
+   - relevant root.prizm RULES and plan decisions
+6. If no changes are detected, skip Phase 1 and write `review-report.md` with verdict PASS, rounds 0, and review mode `not-run-no-changes`.
 
 ## Phase 1: Review-Fix Loop
 
 ### Gate Mode Detection
 
-The loop exit conditions are enforced by a gatekeeper. Check Python availability first:
+Check Python availability:
 
 ```bash
 python3 --version 2>/dev/null && echo "SCRIPT_MODE" || echo "TEXT_MODE"
 ```
 
-- **Script mode** (Python available): Use `${SKILL_DIR}/scripts/check_loop.py` to enforce exit conditions with round tracking, max-rounds enforcement, and divergence detection. The script prevents accidentally exceeding the 3-round limit.
-- **Text mode** (no Python): Follow §Text Fallback Constraints — identical behavior enforced manually.
+- Script mode: use `${SKILL_DIR}/scripts/check_loop.py` for round tracking, max-round enforcement, and divergence detection.
+- Text mode: follow §Text Fallback Constraints manually with identical behavior.
 
 ### Step 0: Initialize Loop State
 
-The script is stateless — no `--reset` or runtime files. Initialize these values before starting:
-
-**Script mode** — `findings_history = []`, `max_rounds = 3`, `round = 1`.
-**Text mode** — track manually: `round = 1`, `findings_history = []`.
+- `round = 1`
+- `max_rounds = 3`
+- `findings_history = []`
+- `review_mode = reviewer-agent-active-checkout` after confirming the dedicated reviewer can launch in the active checkout
 
-### Loop Flow
-
-```
-1. Spawn Reviewer Agent (`subagent_type: prizm-dev-team-reviewer`) → findings or PASS
-2. Parse result:
-   - PASS → Call Loop Exit Gate → Phase 2
-   - NEEDS_FIXES → count findings → Step 3 (do not call gate yet)
-3. Main Agent filters findings → Call Loop Exit Gate → if endLoop: Phase 2
-4. Main Agent applies accepted fixes directly in the active checkout
-5. Increment round and return to Step 1
-```
+### Step 1: Launch Required Reviewer
 
-### Loop Exit Gate
+Always spawn `prizm-dev-team-reviewer` using the dedicated subagent contract:
 
-Call the gate only in these cases:
-
-1. Reviewer returned `PASS`.
-2. Main Agent has finished filtering `NEEDS_FIXES` findings.
-
-Do not call the gate for `NEEDS_FIXES` before filtering, because `accepted_count` is not known yet. Only exit the loop when `endLoop` is `true` — the gate is the sole authority on exit decisions.
-
-**Script mode invocation:**
-```bash
-echo '{"reviewer_result":"NEEDS_FIXES","accepted_count":2,"findings_count":3,"round":1,"findings_history":[],"max_rounds":3,"filtering_done":true}' | python3 ${SKILL_DIR}/scripts/check_loop.py
+```yaml
+subagent_type: prizm-dev-team-reviewer
+isolation: current-workspace / active-checkout / no-worktree
 ```
 
-| Input field | Type | Description |
-|-------------|------|-------------|
-| `reviewer_result` | `"PASS"` or `"NEEDS_FIXES"` | Reviewer's verdict |
-| `accepted_count` | int | Findings accepted by Main Agent. Use `0` for Reviewer PASS or when all findings were rejected after filtering. |
-| `findings_count` | int | Total findings returned by Reviewer this round |
-| `round` | int | Current round number (1-based, model-supplied — the script does not auto-increment) |
-| `findings_history` | `[int, ...]` | Findings count per round, used for divergence detection. Initialize as `[]`. Pass back the value from the previous gate call's output. |
-| `max_rounds` | int | Maximum review rounds before forced exit. Default `3`. |
-| `filtering_done` | bool | `true` only after Main Agent has filtered `NEEDS_FIXES` findings. For Reviewer PASS, this may be omitted. |
-
-Output: `{"endLoop": bool, "reason": str, "verdict": "PASS"|"NEEDS_FIXES"|null, "round": int, "maxRounds": int, "divergenceWarning": bool, "findings_history": [int, ...]}`
-
-The script enforces three exit conditions in order: (1) Reviewer PASS → exit with verdict PASS, (2) filtered `NEEDS_FIXES` with zero accepted findings → exit with verdict PASS, (3) max rounds reached after filtering → exit with verdict NEEDS_FIXES. It records `findings_count` once per round by round index, so repeated gate calls cannot duplicate history entries. If `divergenceWarning` is true, warn the user the loop may not be converging.
+1. Pass the active-checkout context from Phase 0 and the prompt template from `${SKILL_DIR}/references/reviewer-agent-prompt.md`.
+2. The captured git diff, staged diff, untracked files, spec, plan, dev rules, and scoped test report are the primary review scope.
+3. Never use `worktree`, remote isolation, copied checkouts, `Explore`, or a generic code explorer as a substitute for the PrizmKit reviewer. Do not request or create worktree isolation for this review path, including tool-created `.claude/worktrees/...` directories or pipeline-managed `.prizmkit/state/worktrees/...` directories. Pipeline `USE_WORKTREE` controls implementation infrastructure only; it does not change `/prizmkit-code-review` active-checkout review location.
+4. Never perform Main-Agent self-review or fallback review; the Main Agent's job is filtering and fixing, not acting as the reviewer.
+5. If the platform cannot launch the reviewer in the active checkout without worktree isolation, stop with the tool incompatibility message from this skill's introduction.
 
-**Text mode** — enforce §Text Fallback Constraints manually with identical logic.
+### Step 2: Run Review
 
-### Text Fallback Constraints
-
-When Python is unavailable, apply these rules exactly — they match the script's logic:
+Round context:
+- Round 1: examine all current changes comprehensively.
+- Round 2+: focus on whether prior fixes are correct, whether fixes introduced new issues, and whether accepted findings remain.
 
-1. **PASS exit**: Reviewer returns `PASS` → exit loop, verdict PASS.
-2. **Pre-filter NEEDS_FIXES**: Count findings and continue to filtering. Do not apply all-rejected or max-round exits before filtering.
-3. **All-rejected exit**: After filtering, if all findings were rejected → exit loop, verdict PASS.
-4. **Max rounds**: After filtering, if `round >= 3` and accepted findings remain → exit loop, verdict NEEDS_FIXES. Write `review-report.md` with unresolved findings.
-5. **Divergence**: If findings count strictly increases for 3 consecutive recorded rounds, warn user the loop may not converge.
-6. **Counter**: Increment `round` after each complete cycle (Steps 1-4). Track `findings_history` by round index to detect divergence — record `findings_count` once per round.
+Review result:
+- `PASS`: no findings.
+- `NEEDS_FIXES`: one or more findings with severity, dimension, location, problem, and suggested fix.
 
-### Step 1: Spawn Reviewer Agent
+### Step 3: Loop Exit Gate
 
-Include the dev rules read in Phase 0 step 4 and the workspace context captured in Phase 0 step 5 in the Reviewer prompt.
+Call the gate only in these cases:
 
-**Reviewer Agent Invocation Contract (MANDATORY):**
+1. Review returned `PASS`.
+2. Main Agent has filtered `NEEDS_FIXES` findings.
 
-| Parameter | Value | Rationale |
-|-----------|-------|-----------|
-| `subagent_type` | `prizm-dev-team-reviewer` | Dedicated PrizmKit reviewer agent |
-| `run_in_background` | `false` | Orchestrator waits for review results |
-| `isolation` | **omit or `"none"`** — default/no worktree isolation | Reviewer must review the active checkout's changes, not a separate repository copy |
-| worktree tool access | **Forbidden** — do NOT pass `EnterWorktree` tool; do NOT request or create `.claude/worktrees/...` subagent worktrees | Tool-created worktrees defeat checkout-scoped review |
+Do not call the gate for `NEEDS_FIXES` before filtering because `accepted_count` is not known yet.
 
-PrizmKit pipeline-managed linked git worktrees under `.prizmkit/state/worktrees/...` are separate infrastructure controlled by `USE_WORKTREE` and are not relevant to the Reviewer invocation.
+Script mode invocation:
 
-Do not route the PrizmKit reviewer flow through `Explore` or a generic code-explorer agent.
+```bash
+echo '{"reviewer_result":"NEEDS_FIXES","accepted_count":2,"findings_count":3,"round":1,"findings_history":[],"max_rounds":3,"filtering_done":true}' | python3 ${SKILL_DIR}/scripts/check_loop.py
+```
 
-**Fallback clause**: If the current platform or Agent-tool invocation path cannot guarantee a no-worktree Reviewer Agent (e.g., the platform does not support `prizm-dev-team-reviewer` or always creates worktree isolation for subagents), perform the review pass **in the Main Agent as a read-only pass** in the active checkout — do NOT edit files during that pass. Use the same review dimensions and output format as the Reviewer prompt template, and write `review-report.md` directly.
+Gate output determines whether to end the loop. If `divergenceWarning` is true, warn the user that the loop may not be converging.
 
-Read `${SKILL_DIR}/references/reviewer-agent-prompt.md` for the full prompt template — fill `{goals}`, `{plan decisions}`, `{scoped test report}`, `{workspace context}`, `{dev rules}`, `{round N}`, and `{round_context}` before spawning.
+### Text Fallback Constraints
 
-Round context varies by round:
-- Round 1: "This is the first review. Examine all changes comprehensively."
-- Round 2+: "Previous round found issues that were fixed. Focus on: (1) whether previous fixes are correct, (2) whether fixes introduced new problems, (3) any remaining issues. Do not re-report issues that have already been fixed."
+When Python is unavailable, apply these rules manually:
 
-### Step 2: Check Result + Gate
+1. `PASS` exits with verdict PASS.
+2. `NEEDS_FIXES` continues to filtering before any all-rejected or max-round exit.
+3. If all findings are rejected after filtering, exit with verdict PASS.
+4. If `round >= 3` after filtering and accepted findings remain, exit with verdict NEEDS_FIXES.
+5. If findings count strictly increases for 3 consecutive recorded rounds, warn about possible divergence.
+6. Record `findings_history` once per round and increment `round` after a complete review/filter/fix cycle.
 
-Parse the Reviewer Agent's output:
-- If `Result: PASS` → call the **Loop Exit Gate** with `{"reviewer_result": "PASS", "accepted_count": 0, "findings_count": 0, "round": <current_round>, "findings_history": <current_history>, "max_rounds": 3}`. If `endLoop=true`, proceed to Phase 2.
-- If `Result: NEEDS_FIXES` → count findings, do not call the gate yet, then continue to Step 3.
+### Step 4: Main Agent Filters Findings
 
-### Step 3: Main Agent Filters Findings + Gate
+For each finding, decide whether it is reasonable:
 
-Review each finding and decide whether it's reasonable. This prevents unnecessary or harmful changes.
+- Is this relevant to the current changes?
+- Is this a real problem rather than subjective style preference?
+- Would fixing this improve the code without broad out-of-scope refactoring?
+- Does it conflict with spec, plan, dev rules, or current test evidence?
 
-**For each finding, evaluate:**
-- Is this relevant to the current changes? (Reject findings about unmodified, unrelated code.)
-- Is this a real problem or a subjective style preference? (Reject pure style preferences unless they violate clear project conventions.)
-- Would fixing this improve the code without introducing risk? (Reject fixes that require large refactors outside scope.)
+Output per finding:
+- Accepted: queue for direct Main Agent fix work.
+- Rejected: record a short reason such as out of scope, not a defect, or too risky for current task.
 
-**Output per finding:**
-- **Accepted**: The finding is reasonable — queue it for direct Main Agent fix work.
-- **Rejected** (with reason): Brief explanation (e.g., "Out of scope", "Style preference, not a defect").
+After filtering, call the Loop Exit Gate. If `endLoop=true`, proceed to Phase 2.
 
-After filtering: call the **Loop Exit Gate** with `{"reviewer_result": "NEEDS_FIXES", "accepted_count": <N>, "findings_count": <total findings this round>, "round": <current_round>, "findings_history": <current_history>, "max_rounds": 3, "filtering_done": true}`. If `endLoop=true`, proceed to Phase 2.
+### Step 5: Main Agent Applies Accepted Fixes
 
-### Step 4: Main Agent Applies Accepted Fixes
+The Main Agent applies accepted findings directly in the active checkout. Do not spawn a separate Dev Agent for fixes.
 
-Do not spawn a Dev Agent or any review-fix developer subagent. The Main Agent applies accepted findings directly in the active checkout, using the spec context and filtered findings as the fix list. If an accepted finding cannot be safely fixed within scope, record the reason and carry it into `review-report.md` as unresolved.
+If an accepted finding cannot be safely fixed within scope, record the reason and carry it into `review-report.md` as unresolved.
 
-After direct fixes are complete, record results and return to Step 1 for the next round.
+After fixes are complete, record results, increment the round, and return to Step 2.
 
 ## Phase 2: Output
 
 Always write `review-report.md` to the artifact directory, including no-change PASS results. Read `${SKILL_DIR}/references/review-report-template.md` for the full output format.
 
-- `PASS`: Reviewer returned no findings (or all remaining findings were rejected as unreasonable)
-- `NEEDS_FIXES`: 3 rounds completed but unresolved findings remain
-
-Also output a completion summary to conversation.
+Required report fields:
+- Verdict: `PASS` or `NEEDS_FIXES`
+- Review Mode: `reviewer-agent-active-checkout` or `not-run-no-changes`
+- Rounds and total findings
+- Fixed, rejected, and unresolved findings
+- Final summary
 
-**HANDOFF:** `/prizmkit-retrospective` (if PASS) or inform the caller of remaining issues (if NEEDS_FIXES after max rounds)
+Completion summary:
+- `PASS`: hand off to `/prizmkit-retrospective` when docs or durable knowledge changed, otherwise `/prizmkit-committer`.
+- `NEEDS_FIXES`: inform the caller of remaining unresolved findings.

package/bundled/skills/prizmkit-code-review/references/review-report-template.md

@@ -6,6 +6,7 @@ Used in Phase 2 of `/prizmkit-code-review`. Always write `review-report.md` to t
 # Review Report
 
 ## Verdict: <PASS|NEEDS_FIXES>
+## Review Mode: <reviewer-agent-active-checkout|not-run-no-changes>
 ## Rounds: <number of review rounds completed; use 0 for no-change PASS>
 ## Total findings: <total> → Fixed: <fixed>, Rejected: <rejected>, Unresolved: <unresolved>
 

package/bundled/skills/prizmkit-code-review/references/reviewer-agent-prompt.md

@@ -12,10 +12,21 @@ You are the dedicated PrizmKit Reviewer agent (`prizm-dev-team-reviewer`). Revie
 {architecture decisions and task list from plan.md}
 
 ## Scoped Test Report
-{summary from artifact_dir/test-report-path.txt and test-report.md, including Scope, Generated / Updated Tests, In-Scope Failures, Baseline Failures, Out of Scope Gaps, Boundary Matrix / Boundary Completion Gate if present, and Verdict. If no scoped report exists for a feature artifact, write "No scoped /prizmkit-test report found (expected for pre-test review)." Treat that absence as informational unless the calling workflow explicitly requires a prior test report.}
+{summary from artifact_dir/test-report-path.txt and test-report.md, including Scope, Generated / Updated Tests, In-Scope Failures, Baseline Failures, Out of Scope Gaps, Boundary Matrix / Boundary Completion Gate if present, and Verdict. If no scoped report exists for a change artifact, write "No scoped /prizmkit-test report found (expected for pre-test review)." Treat that absence as informational unless the calling workflow explicitly requires a prior test report.}
 
 ## Workspace Context
-{git status, unstaged diff summary, staged diff summary, and new-file paths captured by the Main Agent in Phase 0 from the active checkout. This is your primary review scope — use this context to understand what changed. Request targeted file reads only when you need specific line-level detail for a finding, not to re-discover or re-index the repository. Do not read files that are not in the workspace context unless you need them to verify impact (callers, dependents, shared patterns). Do not switch to a separate worktree or repository copy — the Main Agent has provided everything needed to understand the change set.}
+{git status, unstaged diff summary, staged diff summary, current working directory, expected active checkout git top-level, and new-file paths captured by the Main Agent in Phase 0 from the active checkout. This is your primary review scope — use this context to understand what changed. Request targeted file reads only when you need specific line-level detail for a finding, not to re-discover or re-index the repository. Do not read files that are not in the workspace context unless you need them to verify impact (callers, dependents, shared patterns). Do not switch to a separate worktree or repository copy — the Main Agent has provided everything needed to understand the change set.}
+
+## Active Checkout Guard
+The orchestrator must provide the expected active checkout git top-level in Workspace Context. Before reviewing, verify that your current git top-level matches that expected active checkout.
+
+If your current checkout is different, or appears to be under `.claude/worktrees/`, `.prizmkit/state/worktrees/`, a remote checkout, or any copied/temporary checkout:
+- Stop immediately.
+- Do not review files.
+- Do not produce normal findings.
+- Report `WRONG_CHECKOUT` and state that `/prizmkit-code-review` cannot continue because the reviewer subagent was not started in the active checkout/no-worktree mode required by this skill.
+
+Worktree review is not supported by `/prizmkit-code-review`; do not continue from a worktree even if the files appear similar.
 
 ## Dev Rules (per-layer conventions)
 {rules from .prizmkit/rules/<layer>-rules.md, or "No custom dev rules configured — use general best practices."}
@@ -38,7 +49,7 @@ Evaluate the changes across these dimensions (focus on what's relevant):
 3. **Completeness**: Files that should have been changed but weren't? Missing tests, types, imports, exports?
 4. **Consistency**: Do changes follow the project's existing patterns, naming conventions, and code style?
 5. **Security**: Hardcoded secrets, injection vulnerabilities, unsafe operations.
-6. **Test quality**: If a scoped `/prizmkit-test` report is present, verify the report scope is `this-change`, the artifact dir matches the feature, generated/updated tests assert real behavior rather than mock success or empty assertions, in-scope failures are not mislabeled as baseline failures, baseline failures are genuinely unrelated or pre-existing, out-of-scope gaps were not turned into unrelated test changes, and the report verdict is compatible with proceeding.
+6. **Test quality**: If a scoped `/prizmkit-test` report is present, verify the report scope is `this-change`, the artifact dir matches the reviewed change, generated/updated tests assert real behavior rather than mock success or empty assertions, in-scope failures are not mislabeled as baseline failures, baseline failures are genuinely unrelated or pre-existing, out-of-scope gaps were not turned into unrelated test changes, and the report verdict is compatible with proceeding.
 7. **Rules compliance**: (Skip this dimension if no dev rules were provided.) Do changes follow the per-layer dev rules? Flag violations of framework conventions, naming patterns, state management, or other rules defined for that layer.
 
 ## Output Format