@starlein/paperclip-plugin-company-wizard 0.4.22 → 0.6.2

package/templates/modules/pr-review/README.md

@@ -1,12 +1,12 @@
 # Module: pr-review
 
-Adds a PR-based review workflow with dedicated reviewer roles.
+Adds PR-based review with role-based executionPolicy stages. Select the optional `lean-delivery` module during setup to use one merge gate and risk-triggered specialist evidence instead.
 
 ## What it adds
 
-- **Core roles**: Product Owner (approval) and Code Reviewer (final merge gate — a non-author who lands the PR)
-- **Extended roles** *(when present)*: QA (substantive review), Security Engineer (security-relevant review), UI/UX/DevOps advisory or domain review when explicitly configured
-- **Shared docs**: `docs/pr-conventions.md` — PR format, review workflow, merge rules
+- **Core role**: Code Reviewer (the final executionPolicy stage and non-author merge gate)
+- **Extended roles** *(when present)*: QA review, Security review for security-relevant changes, then Product Owner approval; UI/UX and DevOps advisory. Lean delivery replaces QA/Security/Product stages with triggered evidence before the merge gate.
+- **Shared docs**: `docs/pr-conventions.md`. Only selecting `lean-delivery` adds the binding `docs/lean-delivery.md` contract.
 - **Engineer skill**: Feature-branch + PR workflow (overrides direct-to-base-ref from `github-repo`)
 - **Reviewer skills**: Review checklists for each reviewer role, plus the Code Reviewer's merge-gate skill
 
@@ -19,17 +19,15 @@ Adds a PR-based review workflow with dedicated reviewer roles.
 1. Engineer resolves the project/worktree base ref first from `heartbeat-context` / project workspace metadata and uses it exactly as configured
 2. Engineer creates a feature branch (`<prefix>-<N>/<short-description>`) from that base
 3. Engineer opens a PR with Conventional Commits title, issue reference, and the matching base branch
-4. Engineer sets the originating issue's `executionPolicy`: review stages for QA/domain reviewers as needed, an approval stage for the Product Owner, and a final Code Reviewer merge-gate approval stage (roles resolved to agentIds); the PR link is added as an issue comment. The engineer never lists themselves as a participant — Paperclip excludes the issue's executor from every stage.
-5. QA reviews with executed evidence when present
-6. Security Engineer reviews security-relevant changes when present
-7. Product Owner reviews for intent alignment, scope discipline, acceptance criteria
-8. Domain reviewers (UI/UX/DevOps) may add advisory PR comments unless explicitly added as executionPolicy participants
-9. DevOps reviews infrastructure impact when explicitly added as a stage
-10. The Code Reviewer (the non-author merge gate) merges when all stages are approved (no `changes_requested` outstanding), confirms the PR landed on the correct base, leaves any isolated execution workspace reusable, and only then records the final approval / closes the issue
+4. Engineer sets the selected `executionPolicy`: standard QA → Security (when triggered) → Product → Code Reviewer, omitting absent roles; lean delivery uses only the Code Reviewer. The author is never a participant. Without an eligible non-author Code Reviewer, set no stages and self-merge.
+5. Standard review stages advance through native verdicts. In lean delivery, acceptance is frozen before implementation and triggered specialists return bounded evidence to the implementation owner before review begins, rather than forming a serial chain.
+6. The Code Reviewer verifies the exact head/base and required company CI. Green CI is authoritative, so only a focused risk check is added; the complete local gate runs once only when CI is unavailable.
+7. Corrections return to the implementation owner on the same issue, branch, and PR. Technical defects never route to the board user.
+8. The Code Reviewer merges, confirms the target base, leaves workspace lifecycle to Paperclip, then records approval / closes the issue.
 
 ## Handover mechanism
 
-The issue's native `executionPolicy` (`review`/`approval` stages). Each reviewer is the active participant of a stage and records an `approved` / `changes_requested` decision through the normal issue update route; Paperclip stores the reviewer/approver audit trail on the issue (`reviewed_by` / `approved_by` metadata where exposed). The decision may be mirrored as a GitHub PR comment. Do not create separate review subissues, and **do not model the merge as a standalone "Code review and merge PR #N" issue that is `blockedBy` the review issues** — it adds a second wake transition and can leave a green PR waiting after reviews finish. The merge gate is the **last `executionPolicy` stage on the same implementation issue**, which advances in place. If a reviewer doesn't wake, or a merge issue stays blocked after becoming dependency-ready, the CEO's stall-detection (if enabled) will use Paperclip's blocker/wake diagnostics and PR-queue reconciliation to recover it.
+The issue's native `executionPolicy` ends with a Code Reviewer approval/merge stage. In standard mode, QA/Security/Product record verdicts only on their active stages and Paperclip wakes the next participant. In lean delivery, those specialists return the issue by assignment to the implementation owner before the sole merge stage. Evidence and corrections stay on the same originating issue and PR. Board interactions are reserved for genuine human decisions.
 
 ## Best for
 

package/templates/modules/pr-review/agents/code-reviewer/skills/code-review.md

@@ -1,6 +1,6 @@
 # Skill: Code Review (final merge gate)
 
-You are the **final merge gate** for pull requests. After QA, the Security Engineer (when relevant), and the Product Owner have approved, the issue's `executionPolicy` routes its final `approval` stage to you. You do a last correctness pass, satisfy the hard verification gate, **merge the PR**, preserve its execution workspace for reuse, and only then record `approved` — which closes the issue to `done`.
+You are the **final non-author merge gate** for pull requests. Follow the selected workflow in `docs/pr-conventions.md`: standard review can include QA, Security, and Product stages before you; only when `docs/lean-delivery.md` exists are you the sole default stage with triggered specialist evidence. You verify the exact reviewed head, merge the PR, preserve its execution workspace for Paperclip lifecycle handling, and only then record `approved` — which closes the issue to `done`.
 
 ## Why you, and not the engineer
 
@@ -8,14 +8,14 @@ Paperclip's runtime **excludes the issue's original executor (the author) from e
 
 ## What to verify before merging
 
-1. **Hard gate — executed verification (never skip):**
-   - **Always run the full lint/test/build yourself and paste the real output** into your verdict before merging. This is the authoritative gate, with or without CI. A merge without cited executed verification is invalid.
-   - **CI is an additional gate only when this company runs its own CI/CD** (the `ci-cd` module is active — you have the `ci-cd` skill / a company-authored `docs/CI-CD*.md`). In that case the company-owned CI (lint/test/build) must also be **green** before you merge.
-   - **No company-owned CI/CD:** treat any pre-existing checks on the repository as **advisory signals, not a gate**. Do not refuse to merge solely because a repo-native check the company never configured is red or flaky — your pasted local test/build output is sufficient. (Look into a red repo check if it reveals a real defect in the diff; never let an external/inherited CI you don't own block the merge.)
-   - **Base-branch-red (company-owned CI only):** when the company's own base-branch CI is red, a feature PR's CI is red from the inherited baseline — not from the PR's diff. Detect base-red per `../../docs/git-workflow.md` → *Base-branch-red deadlock* (compare the PR's failing checks to the base commit's own checks). Do not merge a feature PR on a red company-owned base — record `changes_requested` citing `BASE-BRANCH-RED` and route back with "waiting-on-baseline". The single baseline-restore PR (`fix(ci): restore base CI`) may merge under the narrow exception in `../../docs/git-workflow.md` → *Narrow exception*: scoped diff + local executed verification that the fix reduces the failure set + cited base-sha check set. The exception replaces CI-green with local-executed-verification plus diff-scope proof; it never applies to feature PRs.
-2. **All prior stages approved:** QA's `review` (when present), the Security Engineer's `review` (when added), and the Product Owner's `approval` are all recorded `approved`.
-3. **Correctness pass:** read the diff. Does it do what the PR claims? Are edge cases handled? Is it the simplest, clearest solution? Watch for dead code, exposed secrets, and missing validation at boundaries (defer deep security review to the Security Engineer when the change is security-relevant).
-4. **Base ref:** the PR targets the configured project/worktree base from `heartbeat-context` (`repoRef` / `defaultRef` / `workspaceStrategy.baseRef`). Retarget before merging if it points at the wrong branch.
+1. **Hard gate — exact-head verification (never skip):**
+   - **Company-owned CI available:** verify the PR head SHA, target base, and every required company check on that exact head. Green CI is authoritative. Run only the smallest independent check needed for a risky or unclear part of the diff; do not repeat the complete lint/test/typecheck/build suite.
+   - **Company-owned CI unavailable or required checks not yet established:** run the complete local lint/test/typecheck/build gate once and record the real commands and results. Pending or failed required checks are not unavailable CI: wait for or repair them instead of bypassing them with local output. Branch-protection requirements remain binding even for pre-existing checks. A merge without cited verification is invalid.
+   - **No company-owned CI/CD:** existing required checks and repository rules remain binding, regardless of who configured them. Only optional, non-required checks are advisory. Investigate signals of a defect in the diff, and run the complete local gate when no required CI exists. Never weaken protections or bypass a failing required check to merge.
+   - **Base-branch-red (company-owned CI only):** when the company's own base-branch CI is red, a feature PR's CI is red from the inherited baseline — not from the PR's diff. Detect base-red per `docs/git-workflow.md` → *Base-branch-red deadlock* (compare the PR's failing checks to the base commit's own checks). Do not merge a feature PR on a red company-owned base — record `changes_requested` citing `BASE-BRANCH-RED` and route back with "waiting-on-baseline". The single baseline-restore PR (`fix(ci): restore base CI`) may merge under the narrow exception in `docs/git-workflow.md` → *Narrow exception*: scoped diff + local executed verification that the fix reduces the failure set + cited base-sha check set. The exception replaces CI-green with local-executed-verification plus diff-scope proof; it never applies to feature PRs.
+2. **Triggered evidence:** consume any bounded QA, Security, UX, Product, or DevOps evidence already recorded on the originating issue. Do not replay specialists whose finding was already resolved.
+3. **Correctness pass:** read the entire diff and batch all reproducible defects into one verdict. Does it meet acceptance criteria? Are edge cases handled? Is it the simplest clear solution? Watch for dead code, exposed secrets, and missing validation at boundaries.
+4. **Repository and base identity:** treat the PR as `owner/repo#number`, verify that repository against the issue's configured project, and verify the target base from `heartbeat-context`. A bare PR number is not globally unique.
 
 ## Merging
 
@@ -37,20 +37,23 @@ When `gh pr merge` fails or `gh pr view` reports `mergeable: CONFLICTING` / `mer
    - Resolve all conflicts, run checks, commit
    - `git push --force-with-lease origin <branch-name>`
    - Leave an issue comment confirming the rebase, then move the issue back to `in_review`
-3. The issue re-enters the approval chain and returns to you. Re-run the hard verification gate before merging.
+3. The same issue and PR return to you. Verify the new exact head and the requested correction; do not replay an already-satisfied specialist chain.
 
 ## When something is wrong
 
-If correctness, security, or verification is not satisfied, record `changes_requested` (PATCH back toward `in_progress`) with a specific comment. That routes the issue back to the engineer (the `returnAssignee`) — they fix it and resubmit, and the issue returns to you. Do not merge around an unresolved concern.
+Your rounds are limited: each agent-initiated `changes_requested` counts toward Paperclip's review-round cap (default 3; `executionPolicy.maxReviewRounds` overrides it). When the cap is reached, Paperclip keeps the stage pending but hands it to the issue's responsible/creating human instead of the engineer, and nothing moves until that person decides (their decision resets the counter). Spend rounds on complete, actionable verdicts rather than incremental nits.
+
+If correctness, security, or verification is not satisfied, record one precise `changes_requested` verdict that batches all current findings. That routes the same issue back to the implementation owner (`returnAssignee`) for a fix on the same branch and PR. Never assign the board user as the execution participant for a technical defect, stale base, merge conflict, or missing test. Use a board interaction/approval only for an irreducible product, legal, licensing, or residual-risk decision.
 
 ## How to comment
 
-Post verdicts as GitHub PR comments via a Markdown file (`gh pr comment <number> --body-file <file>`) — never inline `--body "..."` (`\n` stays literal in a double-quoted shell string). Open with a heading stating the verdict (`## ✅ Approved & merged`, `## 🔄 Changes requested`), then the verification you ran or confirmed and the specific points you examined. See `../../docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
+Post verdicts as GitHub PR comments via a Markdown file (`gh pr comment <number> --body-file <file>`) — never inline `--body "..."` (`\n` stays literal in a double-quoted shell string). Open with a heading stating the verdict (`## ✅ Approved & merged`, `## 🔄 Changes requested`), then the verification you ran or confirmed and the specific points you examined. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
 
 ## Rules
 
 - You are the merge owner. Reviewers before you do not merge; the engineer (author) cannot.
 - "Looks good" is not a verdict. Cite what you examined and the verification you ran or confirmed.
-- Never merge without your pasted test/build output. When the company runs its own CI/CD (`ci-cd` module active), company-owned CI must also be green — except the baseline-restore PR under the Base-Branch-Red Protocol, which may merge with cited local-executed verification that the fix reduces the base failure set and a scoped diff. A feature PR on a red company-owned base is never merged; record `changes_requested` citing `BASE-BRANCH-RED`. When the company has no CI/CD module, a pre-existing repo check the company didn't configure is advisory — never block a merge solely on it.
+- Never merge without exact-head evidence. With company CI, cite the head SHA and required green checks and avoid duplicating the full suite. Without company CI, cite the complete local gate run once. The baseline-restore exception remains narrow; a feature PR on a red company base never merges under it.
 - Block on real concerns via `changes_requested` rather than merging around them.
 - Never add the issue's author/executor as a participant in any stage — you are the non-author gate that lands the work.
+- Do not create review-only, evidence-only, queue-drain, status-repair, or workspace-cleanup issues. Keep required delivery work on the originating issue and PR; create a follow-up only for independently deliverable, non-blocking work outside current acceptance criteria.

package/templates/modules/pr-review/agents/devops/skills/infra-review.md

@@ -16,8 +16,8 @@ You review PRs for infrastructure impact, performance, security, and operational
 
 1. When a PR changes deployments, configs, dependencies, or system behavior, review it for the infra concerns below.
 2. Focus on infrastructure, deployment, runtime security, observability, and rollback risk.
-3. Post your verdict as an **advisory** GitHub PR comment — you are not a blocking review stage, so do not record a stage verdict (no `approved`/`changes_requested` on the issue's executionPolicy). Write the comment to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `../../docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
-4. If you find a concern that should block the merge, flag it as **blocking-severity** in the comment and name who should act on it — for security issues (exposed secrets, critical vulnerabilities), that is the Security Engineer review stage when one exists, otherwise QA or the Code Reviewer merge gate — so a blocking reviewer can incorporate it into their verdict. You do not block the merge yourself.
+3. Record the verdict on the assigned originating issue. Optionally mirror it as an **advisory** GitHub PR comment — you are not a blocking review stage, so do not record a stage verdict (no `approved`/`changes_requested` on the issue's executionPolicy). Write the comment to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
+4. If you find a concern that should block the merge, flag it as **blocking-severity** and name the correction the implementation owner must make on the same PR. Reassign the originating issue to the implementation owner in the same heartbeat on both pass and fail; they decide whether to fix or open the merge gate. You do not block the merge yourself.
 
 ## Rules
 

package/templates/modules/pr-review/agents/engineer/skills/pr-workflow.md

@@ -1,18 +1,28 @@
 # Skill: PR Workflow
 
-When this skill is active, you work in feature branches and open PRs instead of committing directly to the base ref. Follow the conventions in `../../docs/pr-conventions.md` in the project root.
+When this skill is active, you work in feature branches and open PRs instead of committing directly to the base ref. Follow the conventions in `docs/pr-conventions.md` (paths in this skill are relative to your working directory, the company workspace).
+
+**Select the workflow from company docs:** if `docs/lean-delivery.md` exists, follow its one-gate workflow. Otherwise use standard stages: QA review when present, Security review only for security-relevant changes, Product Owner approval when present, then the non-author Code Reviewer merge gate. Omit absent roles and the author from every stage.
+
+## Acceptance Preflight — before branch or implementation
+
+1. Read the originating issue's outcome and acceptance criteria before creating a branch or changing code.
+2. Proceed only when the intended result is concrete and objectively testable. Do not invent a “sensible” success condition for missing or ambiguous product intent.
+3. If acceptance is missing or ambiguous and a Product Owner is present, stop before implementation, comment the exact unresolved decision on the same issue, and assign it to the Product Owner for clarification. The Product Owner updates/finalizes acceptance criteria and returns the same issue to the implementation owner; this is a pre-code handoff, not a post-code executionPolicy stage.
+4. If no Product Owner is present, route acceptance clarification to the CEO backlog-owner fallback. Use a first-class board interaction only when the remaining choice genuinely requires human product, legal, licensing, or residual-risk authority. Do not create a clarification child/courier issue.
 
 ## Feature Branch Flow
 
-1. Resolve the project/worktree base ref from the issue's `heartbeat-context` / project workspace metadata before branching. Use the configured `repoRef`, `defaultRef`, or `executionWorkspacePolicy.workspaceStrategy.baseRef` exactly as Paperclip provides it. Never guess from your shell's current branch and never rewrite the configured ref to `main`, `master`, or `origin/*`. If no base ref is configured anywhere, use the repository's actual default branch — whatever `origin/HEAD` points at, regardless of name (`main`/`master`/`trunk`/…); fall back to `main` then `master` only if the remote advertises no default HEAD. See `../../docs/git-workflow.md` → *Resolving the default branch*. Never hard-code `main`.
-2. Fetch and update the base:
+1. Resolve the project/worktree base ref from the issue's `heartbeat-context` / project workspace metadata before branching. Use the configured `repoRef`, `defaultRef`, or `executionWorkspacePolicy.workspaceStrategy.baseRef` exactly as Paperclip provides it. Never guess from your shell's current branch and never rewrite the configured ref to `main`, `master`, or `origin/*`. If no base ref is configured anywhere, use the repository's actual default branch — whatever `origin/HEAD` points at, regardless of name (`main`/`master`/`trunk`/…); fall back to `main` then `master` only if the remote advertises no default HEAD. See `docs/git-workflow.md` → *Resolving the default branch*. Never hard-code `main`.
+2. Inspect the resolved execution workspace before changing Git state. If Paperclip already supplied a managed issue branch (`executionWorkspace.branchName`), use that branch unchanged and verify `git branch --show-current` matches it. Do not create, rename, or switch branches inside a managed worktree merely to match a naming convention; runtime finalization validates its persisted branch identity. If a different branch is genuinely required, use the supported workspace transition/owner path before continuing.
+   Fetch and update the base:
    - external: `git fetch origin`, then branch from the configured base ref
    - local: update from the configured local branch
-3. Create branch from that base: `git checkout -b <prefix>-<N>/<short-description> <base-ref>`
-4. **Verify you are on the feature branch** before making changes: `git branch --show-current` must print your branch name, not the base ref. If it prints the base ref name, you forgot step 3 — create the branch now.
+3. When no managed issue branch exists and the checkout is safe for this run, create a feature branch from that base: `git checkout -b <prefix>-<N>/<short-description> <base-ref>`. Otherwise continue on the existing managed issue branch; do not create a second branch.
+4. **Verify you are on the feature branch** before making changes: `git branch --show-current` must print the expected managed or newly created feature branch, not the base ref. Stop and resolve any workspace mismatch before writing code.
 5. Make your changes, commit with Conventional Commits format
 6. **Verify the current branch one more time**, then push: `git push -u origin <branch-name>`. The branch name in the push command must match `git branch --show-current`. Never push the base ref as a feature branch — if `git branch --show-current` returns the base ref name, stop and create a feature branch first.
-7. Open PR against the same resolved base: `gh pr create --base <github-base-branch> --head <branch-name> --title "<type>: <description>" --body-file <file>`. `<github-base-branch>` is the **plain branch name** — strip any `origin/` prefix from the configured base ref (e.g., configured `origin/main` → `--base main`; configured `main` → `--base main`). GitHub does not recognise remote-tracking names. Write the PR body (PR Body Template in `../../docs/pr-conventions.md`) to a file first — never inline `--body "..."` (double-quoted shell string keeps `\n` literal; see *Posting PR Bodies & Comments*).
+7. Open PR against the same resolved base: `gh pr create --base <github-base-branch> --head <branch-name> --title "<type>: <description>" --body-file <file>`. `<github-base-branch>` is the **plain branch name** — strip any `origin/` prefix from the configured base ref (e.g., configured `origin/main` → `--base main`; configured `main` → `--base main`). GitHub does not recognise remote-tracking names. Write the PR body (PR Body Template in `docs/pr-conventions.md`) to a file first — never inline `--body "..."` (double-quoted shell string keeps `\n` literal; see *Posting PR Bodies & Comments*).
 8. **Register the PR as a Paperclip work product** so it is visible on the issue and board (creating it on GitHub alone does not surface it in Paperclip):
    ```
    POST /api/issues/{issueId}/work-products
@@ -28,19 +38,19 @@ When this skill is active, you work in feature branches and open PRs instead of
    }
    ```
    `title` and `url` are required (`url` must be the full PR URL). If the issue runs in an isolated worktree, also pass `"executionWorkspaceId"` from `heartbeat-context`. When the PR later merges, update it with `PATCH /api/work-products/{id}` and `"status": "merged"`.
-9. **Only if a code-reviewer is present on the team:** Set the originating issue's `executionPolicy` to gate the merge on review, ending with the Code Reviewer as the merge gate. **Set executionPolicy stages before moving the issue to `in_review` (step 10) — changing stages after the issue has already entered review is not supported.** If no code-reviewer is assigned to this company, skip steps 9–11 entirely and go directly to the self-merge path at step 12. Setting up executionPolicy stages without an eligible non-author merge gate will stall the issue permanently (`422 No eligible approval participant`).
-   - One `review` stage with **QA** when a QA agent exists (test adequacy / executed verification).
-   - One `review` stage with the **Security Engineer** only when the change is security-relevant (auth, secrets, input boundaries, crypto, dependencies, infra exposure).
-   - Domain reviewers (UI Designer, UX Researcher, DevOps) are advisory — they post PR comments and may flag a concern for QA, the Security Engineer, or the merge gate to act on. They are never themselves a review stage.
-   - An `approval` stage with the **Product Owner** when a Product Owner is on the team — the product sign-off. If no Product Owner is present, omit this stage.
-   - A final `approval` stage with the **Code Reviewer** as participant — the **merge gate**. The Code Reviewer is woken *last*, after every reviewer and the Product Owner have cleared, to satisfy the hard verification gate and merge the PR. If the team has no Code Reviewer, do not set executionPolicy stages at all — use the self-merge path at step 12 instead.
+9. **Resolve advisory evidence before opening review:** in lean delivery, inspect the originating issue and diff for concrete QA, Security, UI/UX, Product, or DevOps triggers. In standard mode, QA/Security/Product use the stages above; only extra advisory checks use this handoff. For each applicable advisory specialist who is present, process one bounded handoff at a time: comment the exact trigger and evidence requested, assign the same originating issue to that specialist, and stop this heartbeat. Assignment is the wake signal because worker agents do not run always-on heartbeats; an `@` mention or passive PR comment is not a wake path. The specialist records pass/fail evidence on the same issue and PR, then always reassigns the originating issue to the implementation owner. On failure, fix the same branch/PR and repeat only the failed evidence; on pass, continue here. Do not create review/courier issues, poll the specialist, or enter `in_review` until every applicable evidence handoff has returned or is explicitly recorded as not applicable.
+10. **Only if an eligible non-author code-reviewer is present on the team:** Set the originating issue's `executionPolicy` to the selected workflow's stages, ending with the Code Reviewer `approval` merge gate. In lean delivery, set exactly one stage. **Set the stages before moving the issue to `in_review` (step 11) — changing stages after review begins is not supported.** If no eligible non-author code-reviewer is available, skip steps 10–12 and use the self-merge path at step 13. A policy without an eligible non-author merge gate stalls permanently.
+   - Product acceptance criteria were settled by the Acceptance Preflight before implementation. Product Owner approves intent/scope in standard review, but is not a routine post-code stage in lean delivery.
+   - In lean delivery, QA, Security, UI/UX, and DevOps provide bounded evidence only when a concrete risk trigger applies. They are not serial executionPolicy stages and do not hand the issue to one another.
+   - The **Code Reviewer** is the final stage (the only stage in lean delivery) and the merge owner. It verifies the exact PR head, required CI, and focused risk evidence, merges the PR, then records `approved` to close the issue.
    - **Never list yourself (the issue's executor) as a participant in any stage.** Paperclip excludes the original executor to prevent self-review; a stage whose only participant is you has no eligible participant and the issue stalls in `in_review` forever (`422 No eligible approval participant is configured for this issue`).
    - Resolve each role to its agentId first (look up active agents), then set the policy on the issue. Include the PR link in an issue comment so reviewers can find it.
-10. Move the originating issue to `in_review`.
-11. Wait for the issue to clear its review/approval stages. Each reviewer and the Product Owner records `approved` by PATCHing the issue toward `done`, or `changes_requested` by PATCHing it back to `in_progress`; Paperclip stores the reviewer/approver decision metadata on the issue. Verdicts may be mirrored as PR comments. A `changes_requested` routes the issue back to you — address it, push to the same branch, and that stage re-runs.
-12. **Merging the PR — two paths:**
-    - **Code Reviewer present (PR-Gate mode):** You do not merge your own PR. The Code Reviewer (the non-author merge gate) lands it after every prior stage approves, satisfies the hard verification gate (green CI or pasted test/build output), and records the final `approved` that closes the issue to `done`. Your job is to respond to `changes_requested`: when a stage routes the issue back to you, address the feedback, push to the same branch, and the stage re-runs. If `changes_requested` is due to a merge conflict (the Code Reviewer will say so), see *Resolving merge conflicts* below.
-    - **No code-reviewer present (PR Self-Merge Flow):** You already skipped steps 9–11. Before merging, check `gh pr view <N> --json mergeable,mergeStateStatus` — if the PR is `CONFLICTING` or `DIRTY`, resolve the conflict first (see *Resolving merge conflicts* below). Then merge: `gh pr merge <N> --merge` once CI is green (or you have pasted test/build output if no CI). All other review roles (qa, product-owner, security-engineer, ui-designer, ux-researcher, devops) may leave advisory comments on the PR, but none block the merge — there are no executionPolicy stages. Update the Paperclip work product to `"status": "merged"` and leave any isolated execution workspace reusable.
+11. Move the originating issue to `in_review`.
+12. Wait for the active executionPolicy participant. A `changes_requested` verdict routes the same issue back to you. Address all concrete findings together, push to the same branch and PR, record the new head and focused verification, then resubmit through the selected policy (directly to the Code Reviewer in lean delivery). Never open a replacement PR or a review-only/courier issue.
+    **Review rounds are capped.** After 3 consecutive agent-initiated `changes_requested` rounds on one stage (Paperclip's default; `executionPolicy.maxReviewRounds` overrides it), Paperclip stops handing the issue back to you and assigns the still-pending stage to the issue's responsible/creating human. If the stage participant becomes a board user, that is the escalation, not a misroute: post the missing context or evidence as a comment and wait for their decision — do not take the issue back, clear the policy, or open a new PR. A human decision resets the counter.
+13. **Merging the PR — two paths:**
+    - **Code Reviewer present (PR-Gate mode):** You do not merge your own PR. The Code Reviewer lands it after verifying exact-head company CI and focused risk evidence, or the complete local gate once when CI is unavailable. Your job is to resolve `changes_requested` on this same issue, branch, and PR. Technical corrections never route to the board user; board involvement is reserved for an irreducible product, legal, licensing, or residual-risk decision through a first-class interaction/approval.
+    - **No code-reviewer present (PR Self-Merge Flow):** You already skipped steps 10–12 after completing any triggered evidence at step 9. Before merging, check `gh pr view <N> --json mergeable,mergeStateStatus` — if the PR is `CONFLICTING` or `DIRTY`, resolve the conflict first (see *Resolving merge conflicts* below). Then merge: `gh pr merge <N> --merge` once CI is green (or you have pasted test/build output if no CI). All other review roles (qa, product-owner, security-engineer, ui-designer, ux-researcher, devops) may leave advisory comments on the PR, but none block the merge — there are no executionPolicy stages. Update the Paperclip work product to `"status": "merged"` and leave any isolated execution workspace reusable.
 
 ## Resolving merge conflicts
 
@@ -49,7 +59,7 @@ When `gh pr merge` fails or `gh pr view` reports `mergeable: CONFLICTING` / `mer
 1. `git fetch origin`
 2. `git checkout <branch-name>`
 3. `git rebase origin/<base-branch>` where `<base-branch>` is the plain branch name — strip any `origin/` prefix from the configured base ref (e.g., configured `origin/main` → `git rebase origin/main`; configured `main` → `git rebase origin/main`). Resolve all conflicts, then `git rebase --continue`.
-4. Run the full check suite (lint, typecheck, tests) to confirm nothing broke.
+4. Run the smallest checks that prove the conflict resolution. If exact-head required company CI is available, rely on it for the complete gate; otherwise run the complete local gate once.
 5. `git push --force-with-lease origin <branch-name>`
 6. Confirm the PR is no longer conflicting: `gh pr view <N> --json mergeable` should return `MERGEABLE`.
 7. Leave an issue comment noting the rebase, then continue with the merge step.
@@ -60,15 +70,15 @@ If the conflict is too complex to resolve safely (large structural conflict with
 
 ## Base-branch-red deadlock
 
-When a PR's CI fails, do not assume the PR is at fault. Detect base-red per `../../docs/git-workflow.md` → *Base-branch-red deadlock*: compare the PR's failing checks against the base commit's own checks. If the base is red, the failure is inherited, not introduced by your diff.
+When a PR's CI fails, do not assume the PR is at fault. Detect base-red per `docs/git-workflow.md` → *Base-branch-red deadlock*: compare the PR's failing checks against the base commit's own checks. If the base is red, the failure is inherited, not introduced by your diff.
 
 - **Do not open new feature PRs on a red base** — they pile up and inherit the failure.
-- Run the baseline-emergency protocol in `../../docs/git-workflow.md` → *Baseline-emergency protocol*: fix main first with a single `fix(ci): restore base CI` PR, fast-track it through merge under the narrow exception, re-verify the base is green, then rebase and drain the feature-PR queue.
+- Run the baseline-emergency protocol in `docs/git-workflow.md` → *Baseline-emergency protocol*: fix main first with a single `fix(ci): restore base CI` PR, fast-track it through merge under the narrow exception, re-verify the base is green, then rebase and drain the feature-PR queue.
 - A feature PR on a red base waits for the base to be restored. It never merges under the baseline-restore exception.
 
-In **PR-Gate mode** (Code Reviewer present): you are the issue author and Paperclip excludes you from every executionPolicy stage, so you **cannot record `changes_requested`** — only a stage participant (the Code Reviewer) can. If you detect BASE-BRANCH-RED before moving the issue to `in_review` (step 10), do not move it — leave it `in_progress`, comment `BASE-BRANCH-RED` with the baseline-restore PR link, and start the baseline-emergency protocol now. If the issue is already `in_review`, comment `BASE-BRANCH-RED` with "waiting-on-baseline; starting baseline-restore PR now", then immediately claim and create the `fix(ci): restore base CI` PR per the baseline-emergency protocol in `../../docs/git-workflow.md` — do not wait for the Code Reviewer's `changes_requested` route-back before beginning the fix. The Code Reviewer reads its `code-review.md` and records `changes_requested` to formally route the issue back; the base fix proceeds in parallel. Do not leave the issue silently in `in_review` against a red base.
+In **PR-Gate mode** (Code Reviewer present): you are the issue author and Paperclip excludes you from every executionPolicy stage, so you **cannot record `changes_requested`** — only the active stage participant can. If you detect BASE-BRANCH-RED before moving the issue to `in_review` (step 11), do not move it; record the inherited failures and route the baseline-emergency protocol to the backlog owner/CEO for explicit assignment. If already `in_review`, comment `BASE-BRANCH-RED` with "waiting-on-baseline" and the separately owned baseline-restore issue/PR. The active participant records `changes_requested` to formally route the feature issue back. Deduplicate detections into one baseline-restore issue, branch, and PR; do not self-claim extra work or put the unrelated base repair on the feature branch. Do not leave the issue silently in `in_review` against a red base.
 
-In the **Self-Merge path** (no Code Reviewer): do not merge your feature PR on a red base; run the baseline-emergency protocol, then rebase and merge once the base is green. If you opened the `fix(ci): restore base CI` PR under a declared baseline emergency, you may merge it despite red CI under the narrow exception in `../../docs/git-workflow.md` → *Narrow exception* (run the failing checks locally, paste passing output, remaining failures exactly the inherited baseline set).
+In the **Self-Merge path** (no Code Reviewer): do not merge your feature PR on a red base; run the baseline-emergency protocol, then rebase and merge once the base is green. If you opened the `fix(ci): restore base CI` PR under a declared baseline emergency, you may merge it despite red CI under the narrow exception in `docs/git-workflow.md` → *Narrow exception* (run the failing checks locally, paste passing output, remaining failures exactly the inherited baseline set).
 
 ## Misrouted in_review (no action path)
 
@@ -76,11 +86,11 @@ In the **Self-Merge path** (no Code Reviewer): do not merge your feature PR on a
 
 1. Move the issue back to `in_progress` (`PATCH /api/issues/{id}` with `status: "in_progress"`).
 2. Take the correct path for the team:
-   - **Code Reviewer present:** set the `executionPolicy` review/approval stages (step 9 above) *before* moving the issue back to `in_review`. Changing stages after the issue re-enters review is not supported.
-   - **No Code Reviewer:** do not set any `executionPolicy` — use the self-merge path (step 12). Merge the PR yourself via `gh pr merge <N> --merge` and mark the issue `done`; do not route it back to `in_review`.
+   - **Code Reviewer present:** set the `executionPolicy` review/approval stages (step 10 above) *before* moving the issue back to `in_review`. Changing stages after the issue re-enters review is not supported.
+   - **No Code Reviewer:** do not set any `executionPolicy` — use the self-merge path (step 13). Merge the PR yourself via `gh pr merge <N> --merge` and mark the issue `done`; do not route it back to `in_review`.
 3. Leave an issue comment naming the missing action path and the recovery action taken.
 
-For new PR work, never move an issue to `in_review` unless an `executionPolicy` with at least one non-author stage is set (PR-Gate mode) or you are on the self-merge path and will merge it yourself this heartbeat (no Code Reviewer). For existing issues, diagnose the full action path before changing state.
+For new PR work, use `in_review` only with a valid non-author executionPolicy stage or a first-class human interaction/approval. The self-merge path stays `in_progress` until merge and completion; intent to merge later in the heartbeat is not a review action path. For existing issues, diagnose the full action path before changing state.
 
 ## Rules
 
@@ -90,7 +100,7 @@ For new PR work, never move an issue to `in_review` unless an `executionPolicy`
 - If a reviewer requests changes, address them, push to the same branch, and re-request review (the stage re-runs).
 - When a code-reviewer is present: the Code Reviewer is the merge owner; you cannot merge your own PR (Paperclip excludes the executor). When no code-reviewer is present: you are the merge owner; skip executionPolicy stages and merge via `gh pr merge <N> --merge` yourself.
 - Before creating a PR, verify the PR base matches the configured project/worktree base. If the base is wrong, retarget the PR before review.
-- **The merge gate must be the last stage, and it must be a non-author.** The Product Owner's `approval` is the product sign-off, not the final stage: if it were last, their verdict would auto-close the issue to `done` with the PR still open on GitHub. Append a final merge-gate `approval` stage for the **Code Reviewer** after the Product Owner's. Never make yourself the merge gate — Paperclip excludes the executor, so that stage stalls with `422 No eligible approval participant`. If no Code Reviewer is on the team, do not set executionPolicy stages; use the self-merge path instead.
+- **Follow the selected policy:** standard review uses role-based stages; only optional lean delivery uses exactly one non-author Code Reviewer stage and bounded advisory specialists. Never make yourself the merge gate — Paperclip excludes the executor, so that stage stalls with `422 No eligible approval participant`. If no eligible non-author Code Reviewer is on the team, set no executionPolicy stages and use the self-merge path.
 - Do not create separate child review issues and do not use @-mentions to request review; the executionPolicy stages are the governance signal.
 - Do not wait for GitHub-native approving reviews when all agents share the same GitHub credential; GitHub rejects self-approval. The Paperclip executionPolicy stages are the required signal unless a separate non-author GitHub reviewer credential is explicitly available.
 - Preserve isolated execution workspaces after merge. Neither the author nor merge-gate agent archives/deletes a workspace during normal issue completion; review, follow-up, or dependent work may reuse it. Retirement is a separate board/operator action, including for abandoned or cancelled work.

package/templates/modules/pr-review/agents/product-owner/skills/product-review.md

@@ -1,6 +1,6 @@
 # Skill: Product Review
 
-You review PRs for intent alignment, scope discipline, and acceptance criteria. You are the product sign-off — the participant of the `approval` stage on the PR's issue immediately before the Code Reviewer merge gate. Your `approved` is required before the merge gate lands the PR, but you are not the final stage: the Code Reviewer's subsequent merge-gate approval is what closes the issue.
+You define product intent and acceptance **before implementation**. In standard PR review, you approve intent/scope as an executionPolicy stage before the Code Reviewer merge gate. If `docs/lean-delivery.md` exists, Product is not a routine serial executionPolicy stage: return after code exists only for a concrete unresolved product decision, accepted-scope change, or release/cutover decision, then return the same issue to the implementation owner.
 
 ## Review Checklist
 
@@ -13,11 +13,11 @@ You review PRs for intent alignment, scope discipline, and acceptance criteria.
 
 ## How to Review
 
-1. When you are the active participant of the approval stage on an issue with a PR link, review the PR against the originating issue.
-2. Record your verdict through the normal issue update route for your approval stage:
-   - **approved** if the change meets product requirements
-   - **changes_requested** with specific feedback tied to acceptance criteria
-3. Optionally mirror the verdict as a GitHub PR comment — write it to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `../../docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
+1. Review the originating issue and PR when Product is the active standard policy stage or a concrete product trigger is recorded for a lean/advisory handoff. Do not create a product-review child/courier issue.
+2. Record one decision tied to acceptance criteria. For lean/advisory handoffs:
+   - **accepted** when the change matches the frozen outcome; return the same issue to the implementation owner so they can open the Code Reviewer gate
+   - **changes required** when a concrete criterion is unmet; return the same issue to the implementation owner and same PR
+3. **Standard active Product stage:** record `approved` or `changes_requested` through the executionPolicy and let Paperclip route the next action; do not manually reassign or close the issue. **Lean/advisory handoff:** reassign the same originating issue to the implementation owner in the same heartbeat. Optionally mirror the verdict as a GitHub PR comment — write it to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
 
 ## Rules
 
@@ -25,5 +25,5 @@ You review PRs for intent alignment, scope discipline, and acceptance criteria.
 - Every PR should trace back to an issue. If it doesn't, ask why.
 - Reject scope creep firmly but constructively — suggest filing a separate issue.
 - If acceptance criteria are ambiguous, clarify them before approving.
-- Your approval stage verdict is the product sign-off; the Code Reviewer's subsequent merge-gate approval is the final governance signal that closes the issue. Do not block only because GitHub rejects formal review submission from the shared PR-author credential — GitHub-native approval is optional unless a distinct non-author reviewer credential is explicitly available.
-- You are not a merge owner. If a Code Reviewer is absent and the team is using the PR Self-Merge Flow, the engineer merges the PR themselves; your role is advisory in that mode — post product concerns as PR comments, do not record a stage verdict.
+- You are not a merge owner. In standard mode, Product approval precedes the Code Reviewer; in lean delivery, the Code Reviewer is the sole default non-author gate. Without an eligible Code Reviewer, the engineer uses the PR Self-Merge Flow.
+- Do not create review-only, evidence-only, queue-drain, or workspace-cleanup issues. Create a follow-up only for independently deliverable, non-blocking scope outside the current acceptance criteria.

package/templates/modules/pr-review/agents/qa/skills/qa-review.md

@@ -1,16 +1,16 @@
 # Skill: QA Review
 
-You are the **substantive review gate** for pull requests. Review is by *doing*, not by reading: your verdict must rest on tests that actually ran. "Looks good" is not a review.
+In standard PR review, you are the QA executionPolicy review stage when present and not the author. If `docs/lean-delivery.md` exists, you instead provide **bounded QA evidence on the originating issue** only for a concrete browser, integration, release, cutover, or regression risk; you are not a serial default executionPolicy stage in that mode. Review is by *doing*, not by reading: your verdict must rest on tests that actually ran.
 
 ## How you verify
 
-**You run the tests yourself — always.** There is no machine arbiter you can defer to: check out the branch, run the full test suite and the build locally, and paste the **real command output** into your stage-record verdict. A verdict without execution output is invalid. Beyond green/red, ensure the tests *mean something*:
+Run the smallest tests that prove coverage and the triggered risk. If required company CI is green on the exact reviewed head, cite it and do not repeat the complete suite. Without CI, record focused QA evidence and leave the complete local gate to the merge owner; do not duplicate it. Beyond green/red, ensure the tests *mean something*:
 - New code paths and edge cases are covered by tests you ran.
 - Tests assert behavior, not implementation.
 - Regression risk is covered.
-Record `approved` only when your executed tests pass AND coverage is adequate. If coverage is inadequate, record `changes_requested` with the specific missing test cases — even if everything is green.
+Record a bounded pass/fail verdict on the originating issue. If coverage is inadequate, return that same issue to the implementation owner with the specific missing cases.
 
-**Company-owned CI/CD (`ci-cd` module active):** in addition to your own executed verification, confirm the company's CI (lint/test/build) is green — both the build and test jobs. **Without a company CI/CD module:** treat any pre-existing repo checks as advisory signals only; your pasted local output is the gate — do not block solely on an external check the company never configured.
+**Required CI available:** confirm the exact-head required checks and add only the focused evidence the risk trigger needs. **Without required CI:** run the relevant local checks, expanding to the complete local gate only when you are the only available verifier. Existing required repository checks remain binding without the `ci-cd` module; only optional, non-required checks are advisory.
 
 Replace `<branch>` with the PR branch name and substitute your project's actual test and build commands:
 
@@ -20,7 +20,7 @@ git fetch origin && git checkout <branch>
 <the project's build command>  # e.g. pnpm build
 ```
 
-Record `approved` only if the suite and build pass and coverage is adequate; otherwise `changes_requested` with the failing output and the gaps.
+Record a bounded `pass` comment only if the checks pass and coverage is adequate; otherwise record a bounded `fail` comment with the failing output and gaps. In lean delivery, these are evidence comments, not `approved` / `changes_requested` executionPolicy verdicts; return the issue as described below. In standard mode, record the corresponding verdict only when QA is the active stage participant.
 
 ## Review checklist
 
@@ -34,14 +34,14 @@ Record `approved` only if the suite and build pass and coverage is adequate; oth
 
 ## How to record your verdict
 
-1. You are the active participant of a `review` stage on the issue carrying the PR link.
-2. Record on your stage through the normal issue update route: `approved` (with the evidence — commands + results) by PATCHing toward `done`, or `changes_requested` (with specific gaps and suggested test cases) by PATCHing back to `in_progress`.
-3. Optionally mirror the verdict as a GitHub PR comment via a Markdown file: open with a heading (`## ✅ Approved` / `## 🔄 Changes requested`), then details, and run `gh pr comment <number> --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal. See `../../docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
+1. Work on the originating issue carrying the PR link and either an active QA stage (standard mode) or explicit QA trigger (lean mode); do not create a QA-only child/courier issue.
+2. **Standard active QA stage:** record `approved` or `changes_requested` with exact-head evidence through the executionPolicy and let Paperclip route the next action. Do not manually reassign or close the issue. **Lean/advisory handoff:** record concise evidence and a pass/fail verdict, then reassign the same originating issue to the implementation owner in the same heartbeat. On failure, name the exact correction required on the same PR. On pass, the implementation owner opens the Code Reviewer merge gate (or takes the documented self-merge path); QA is never inserted as a serial policy stage in lean delivery.
+3. Optionally mirror the verdict as a GitHub PR comment via a Markdown file: open with a heading (`## ✅ Approved` / `## 🔄 Changes requested`), then details, and run `gh pr comment <number> --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
 
 ## Rules
 
-- A verdict that does not cite executed verification (CI green, or your pasted test/build output) is invalid.
+- A verdict that does not cite exact-head verification is invalid.
 - Be constructive — suggest specific test cases, don't just say "needs more tests".
 - Flag untested critical paths as blockers; untested non-critical paths as suggestions.
 - Approve trivial changes (docs, comments, config) without ceremony.
-- If CI is missing or broken, that is a blocker — tests that don't run don't count.
+- Do not create review-only, evidence-only, status-repair, or workspace-cleanup issues.

package/templates/modules/pr-review/agents/security-engineer/skills/pr-security-review.md

@@ -1,6 +1,6 @@
 # Skill: PR Security Review
 
-You review a **specific PR's diff** for security-relevant changes. You are added as a `review` stage **only when the change touches** authentication, authorization, secrets, input boundaries, cryptography, dependencies, or infrastructure exposure — i.e. when it is security-relevant. (For broader threat modeling, see your `security-review` skill from the security-audit module, if present.)
+You review a **specific PR's diff** only when the originating issue records a concrete security trigger: authentication, authorization, tenant/data scope, secrets, input boundaries, cryptography, dependencies, infrastructure exposure, or sensitive egress. In standard PR review, this can be a Security executionPolicy stage before Product/Code Reviewer. If `docs/lean-delivery.md` exists, provide one bounded advisory verdict instead; you are not a serial default executionPolicy stage in lean delivery.
 
 Review is by *probing*, not by reading. Your verdict must state what you actually checked.
 
@@ -15,13 +15,14 @@ Review is by *probing*, not by reading. Your verdict must state what you actuall
 
 ## How to record your verdict
 
-1. You are the active participant of a `review` stage on the issue carrying the PR link.
+1. Work on the originating issue carrying the PR link and recorded security trigger. Do not create a security-review child/courier issue.
 2. State **what you probed and how** (e.g. "checked the new `/upload` endpoint for path traversal with `../` inputs; validated the content-type allowlist"). A verdict without concrete checks is invalid.
-3. Record the stage decision through the normal issue update route: `approved` by PATCHing the issue toward `done` with the checks performed, or `changes_requested` by PATCHing back to `in_progress` with the specific finding, impact, and remediation.
-4. Optionally mirror as a GitHub PR comment via a Markdown file (`## ✅ Approved` / `## 🔄 Changes requested`), run `gh pr comment <number> --body-file <file>`. Never inline `--body "..."`. See `../../docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
+3. **Standard active Security stage:** record `approved` or `changes_requested` through the executionPolicy and let Paperclip route the next action; do not manually reassign or close the issue. **Lean/advisory handoff:** record one bounded pass/fail verdict, then reassign the same originating issue to the implementation owner in the same heartbeat. Blocking in-scope findings name the exact correction required on the same branch and PR; a pass lets the implementation owner open the Code Reviewer gate. Advisory specialists do not hand the issue to one another.
+4. Optionally mirror as a GitHub PR comment via a Markdown file (`## ✅ Approved` / `## 🔄 Changes requested`), run `gh pr comment <number> --body-file <file>`. Never inline `--body "..."`. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
 
 ## Rules
 
 - Block on exploitable issues (injection, auth bypass, secret exposure). Suggest on defense-in-depth hardening.
 - Be specific: name the input, the path, the impact. "Looks secure" is not a review.
 - If the change is not actually security-relevant, say so briefly and approve — don't manufacture findings.
+- Create a follow-up only for independently deliverable, non-blocking work outside the current acceptance criteria. Never create review-only, evidence-only, or workspace-cleanup issues.

package/templates/modules/pr-review/agents/ui-designer/skills/design-review.md

@@ -4,7 +4,7 @@ You review PRs for visual quality, brand consistency, and accessibility. When a
 
 ## Review Checklist
 
-1. **Brand consistency** — If `../../docs/BRAND-IDENTITY.md` exists, check that colors, typography, spacing, and iconography match the brand guidelines. Otherwise, evaluate visual consistency based on the existing codebase patterns.
+1. **Brand consistency** — If `docs/BRAND-IDENTITY.md` exists, check that colors, typography, spacing, and iconography match the brand guidelines. Otherwise, evaluate visual consistency based on the existing codebase patterns.
 2. **Visual hierarchy** — Is the information hierarchy clear? Do primary actions stand out? Is there visual clutter?
 3. **Layout and spacing** — Are margins, padding, and alignment consistent with the design system?
 4. **Responsive behavior** — Does the layout adapt correctly across breakpoints?
@@ -16,12 +16,12 @@ You review PRs for visual quality, brand consistency, and accessibility. When a
 
 1. When a PR touches UI components, styles, or user-facing screens, review it for the design concerns below.
 2. Focus only on visual/design concerns — leave code logic to Code Reviewer and product scope to Product Owner.
-3. Post your verdict as an **advisory** GitHub PR comment — you are not a blocking review stage, so do not record a stage verdict (no `approved`/`changes_requested` on the issue's executionPolicy). Write the comment to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `../../docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
-4. If you find a concern that should block the merge (e.g. a critical accessibility regression or a brand-violating change), flag it explicitly in the comment and name who should act on it — QA, the Security Engineer, or the Code Reviewer merge gate — so a blocking reviewer can incorporate it into their verdict. You do not block the merge yourself.
+3. Record the verdict on the assigned originating issue. Optionally mirror it as an **advisory** GitHub PR comment — you are not a blocking review stage, so do not record a stage verdict (no `approved`/`changes_requested` on the issue's executionPolicy). Write the comment to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
+4. If you find a concern that should block the merge (e.g. a critical accessibility regression or a brand-violating change), flag it explicitly and name the correction the implementation owner must make on the same PR. Reassign the originating issue to the implementation owner in the same heartbeat on both pass and fail; they decide whether to fix or open the merge gate. You do not block the merge yourself.
 
 ## Rules
 
 - Be specific — "the button should use `--color-primary`" beats "wrong color".
 - Comment only on changes that touch UI — not every PR needs design review.
-- If `../../docs/BRAND-IDENTITY.md` doesn't exist yet, note it but don't block the PR.
+- If `docs/BRAND-IDENTITY.md` doesn't exist yet, note it but don't block the PR.
 - Screenshots or before/after comparisons strengthen feedback when possible.

package/templates/modules/pr-review/agents/ux-researcher/skills/ux-review.md

@@ -16,12 +16,12 @@ You review PRs for usability, user flow integrity, and alignment with user needs
 
 1. When a PR changes user-facing behavior, interactions, or flows, review it for the UX concerns below.
 2. Focus only on UX and usability concerns — leave code logic to Code Reviewer and visuals to UI Designer.
-3. Post your verdict as an **advisory** GitHub PR comment — you are not a blocking review stage, so do not record a stage verdict (no `approved`/`changes_requested` on the issue's executionPolicy). Write the comment to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `../../docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
-4. If you find a concern that should block the merge (e.g. a flow that traps users in a dead end), flag it explicitly in the comment and name who should act on it — QA, the Security Engineer, or the Code Reviewer merge gate — so a blocking reviewer can incorporate it into their verdict. You do not block the merge yourself.
+3. Record the verdict on the assigned originating issue. Optionally mirror it as an **advisory** GitHub PR comment — you are not a blocking review stage, so do not record a stage verdict (no `approved`/`changes_requested` on the issue's executionPolicy). Write the comment to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
+4. If you find a concern that should block the merge (e.g. a flow that traps users in a dead end), flag it explicitly and name the correction the implementation owner must make on the same PR. Reassign the originating issue to the implementation owner in the same heartbeat on both pass and fail; they decide whether to fix or open the merge gate. You do not block the merge yourself.
 
 ## Rules
 
 - Ground feedback in user impact — "users might miss this because..." beats "I don't like this".
-- If `../../docs/USER-TESTING.md` exists, reference its findings where relevant. If it doesn't exist yet, ground feedback in the PR and existing app patterns instead.
+- If `docs/USER-TESTING.md` exists, reference its findings where relevant. If it doesn't exist yet, ground feedback in the PR and existing app patterns instead.
 - Comment only on changes that affect user-facing behavior.
 - If the change introduces a new interaction pattern, flag it for consistency tracking.