@starlein/paperclip-plugin-company-wizard 0.4.6 → 0.4.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlein/paperclip-plugin-company-wizard",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "type": "module",
   "description": "AI-powered wizard to bootstrap paperclip agent companies from composable templates (for latest paperclip version)",
   "repository": "https://github.com/starlein/paperclip-plugin-company-wizard",

package/templates/bootstrap-instructions.md

@@ -19,7 +19,7 @@ Each section (Goals, Projects, Labels, Agents, Issues, Routines) contains object
 2. **Projects** — create with `POST /api/companies/{companyId}/projects` using `{ name, description, goalIds, workspace, executionWorkspacePolicy? }`. Reference goals via `goalIds`; create after all goals exist. Valid project `status` (optional, defaults to `backlog`): `backlog`, `planned`, `in_progress`, `completed`, `cancelled` — **`active` is a goal status, NOT a project status; do not set it on a project.** Create the project workspace as an object, not a raw string. Fresh/new repositories use a local project workspace such as `workspace: { sourceType: "local_path", cwd: "...", defaultRef: "main", setupCommand: "git init -b main", isPrimary: true }` and must initialize Git before work starts; do not attach an `executionWorkspacePolicy` to a fresh local repo (the repo has no base ref yet). Existing repository-backed projects use the workspace refs shown in this bootstrap exactly as rendered; do not rewrite them to `main`, `master`, or add/remove `origin/`. When this bootstrap includes `executionWorkspacePolicy`, send it exactly as rendered; it was included only because Paperclip's experimental isolated-workspaces setting is enabled, and its `workspaceStrategy.baseRef` comes from project/worktree settings. Never inline credentials in repo URLs.
 3. **Labels** — if the bootstrap includes an Issues section, create issue labels first (`POST /api/companies/{companyId}/labels` with `{ name, color }`). Colors must be 6-digit hex strings with a leading `#`.
 4. **Agents** — hire via governance (`POST /api/companies/{companyId}/agent-hires`) using the listed `adapterType`, nested `adapterConfig`, `runtimeConfig`, `capabilities`, and `metadata`. The Company Wizard already created the CEO for this bootstrap issue; reuse/update any existing agent with the same `metadata.templateRole` instead of creating a duplicate.
-5. **Issues** — every issue must include `projectId`, including subtasks. Subtasks must also include `parentId`. Assign via `assigneeAgentId` or `assigneeUserId`, and attach labels via `labelIds`. If you use `POST /api/issues/{parentId}/children`, still pass `projectId` explicitly for clarity; if you use `POST /api/companies/{companyId}/issues`, passing both `parentId` and `projectId` is mandatory for this bootstrap.
+5. **Issues** — every issue must include `projectId`, including subtasks. Subtasks must also include `parentId`. Assign via `assigneeAgentId` or `assigneeUserId`, and attach labels via `labelIds`. If you use `POST /api/issues/{parentId}/children`, still pass `projectId` explicitly for clarity; if you use `POST /api/companies/{companyId}/issues`, passing both `parentId` and `projectId` is mandatory for this bootstrap. Set workspace isolation explicitly: **top-level issues** (no `parentId`) must include `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so each gets its own worktree/branch; **subtasks** set `parentId` and omit `executionWorkspaceSettings` so they reuse the parent's workspace.
 6. **Routines** — reference project and agent. Create the routine first, then add a schedule trigger with `POST /api/routines/{routineId}/triggers` using `{ kind: "schedule", cronExpression: schedule, timezone: "UTC" }`.
 
 **Status + subissue guardrails:**
@@ -27,7 +27,7 @@ Each section (Goals, Projects, Labels, Agents, Issues, Routines) contains object
 - Parent and subissue status are related by intent, not automatically coupled by tooling.
 - Do not auto-mark a parent `done` just because a child changed status.
 - Do not auto-reopen a `done` parent/subissue unless you have an explicit reason and record it in a comment.
-- Do not implicitly reuse a parent workspace for subissues; keep `projectId` explicit and respect the project/issue execution workspace policy. Use isolated workspaces only when Paperclip created one for the issue.
+- Make workspace intent explicit at creation; never rely on implicit inheritance. A top-level issue (no `parentId`) created without `executionWorkspaceSettings` silently adopts the workspace of whatever issue the creator currently has checked out, which serializes work and corrupts branch state. Therefore: top-level issues set `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` (own worktree); subissues set `parentId` and omit `executionWorkspaceSettings` so they deliberately share the parent's workspace (safe because the parent cannot be completed/cleaned up while subissues are open). Keep `projectId` explicit on both.
 
 **Review workflow guardrail:**
 

package/templates/modules/architecture-plan/agents/ui-designer/skills/design-system.md

@@ -13,7 +13,7 @@ You own the visual design system. Establish the foundational patterns that ensur
    - **Brand guidelines**: Logo usage, tone of visual language, iconography style
    - **Responsive breakpoints**: Mobile, tablet, desktop sizing approach
 3. Create implementation issues for the engineer:
-   - `POST /api/companies/{companyId}/issues` for CSS/design token setup, component library scaffolding. Include the active `projectId` (and `goalId` / `parentId` when applicable).
+   - `POST /api/companies/{companyId}/issues` for CSS/design token setup, component library scaffolding. Include the active `projectId` (and `goalId` / `parentId` when applicable). For top-level issues (no `parentId`), also include `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so each gets its own worktree; subissues set `parentId` and omit it.
 4. Assign or hand off implementation issues to the Engineer with a concrete next action; do not rely on generic @-mentions.
 
 ## Rules

package/templates/modules/architecture-plan/skills/architecture-plan.md

@@ -13,7 +13,7 @@ You own system architecture. Design the structure that implements the tech stack
    - **Deployment model**: How the system is built, tested, and deployed
    - **Key decisions**: Architectural decisions with rationale (ADR-style)
 3. Create implementation issues for the foundational structure:
-   - `POST /api/companies/{companyId}/issues` for scaffolding, core modules, etc. Include the active `projectId` (and `goalId` / `parentId` when applicable).
+   - `POST /api/companies/{companyId}/issues` for scaffolding, core modules, etc. Include the active `projectId` (and `goalId` / `parentId` when applicable). For top-level issues (no `parentId`), also include `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so each gets its own worktree; subissues set `parentId` and omit it.
 
 ## Rules
 

package/templates/modules/auto-assign/agents/ceo/heartbeat-section.md

@@ -2,4 +2,4 @@
 
 Primary assignment happens at backlog grooming — issues are assigned to the best-fit agent as they are created. This routine is a **safety net** that catches stragglers when the Product Owner hasn't acted.
 
-Do not scan for unassigned work during a normal heartbeat. If you are assigned a routine-run issue titled like "Auto-assign unassigned issues" and no Product Owner is available, use `skills/auto-assign.md`, then summarize assignments on the routine issue and exit.
+Do not scan for unassigned work during a normal heartbeat. If you are assigned a routine-run issue titled like "Auto-assign unassigned issues" and no Product Owner is available, use `$AGENT_HOME/skills/auto-assign.md`, then summarize assignments on the routine issue and exit.

package/templates/modules/auto-assign/agents/product-owner/heartbeat-section.md

@@ -2,4 +2,4 @@
 
 Primary assignment happens at backlog grooming — issues are assigned to the best-fit agent as they are created, not through this routine. This routine is a **safety net** that catches stragglers every 4 hours.
 
-Do not scan for unassigned work during a normal heartbeat. When you are assigned a routine-run issue titled like "Auto-assign unassigned issues", use `skills/auto-assign.md`, then summarize assignments on the routine issue and exit.
+Do not scan for unassigned work during a normal heartbeat. When you are assigned a routine-run issue titled like "Auto-assign unassigned issues", use `$AGENT_HOME/skills/auto-assign.md`, then summarize assignments on the routine issue and exit.

package/templates/modules/backlog/agents/ceo/heartbeat-section.md

@@ -1,3 +1,3 @@
 ## Backlog Health Routine Fallback
 
-Do not groom the backlog during a normal heartbeat unless that is your assigned issue. If you are assigned a routine-run issue titled like "Backlog grooming" and no Product Owner is available, use `skills/backlog-health.md`, then summarize generated/updated issues on the routine issue and exit.
+Do not groom the backlog during a normal heartbeat unless that is your assigned issue. If you are assigned a routine-run issue titled like "Backlog grooming" and no Product Owner is available, use `$AGENT_HOME/skills/backlog-health.md`, then summarize generated/updated issues on the routine issue and exit.

package/templates/modules/backlog/agents/ceo/skills/backlog-health.fallback.md

@@ -9,6 +9,7 @@ On your heartbeat, after handling assignments:
 1. Query unassigned issues: `GET /api/companies/{companyId}/issues?status=todo&unassigned=true`
 2. If fewer than 1 unassigned issue remains AND the Product Owner hasn't acted recently:
    - Create 1-2 high-priority issues from the roadmap to keep engineers unblocked
+   - For each top-level issue (no `parentId`), include `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so it gets its own worktree; subissues set `parentId` and omit it. Never create a top-level issue without it (it would inherit your checked-out workspace and block parallel work).
    - Attach `labelIds` — fetch available labels via `GET /api/companies/{companyId}/labels`. If no labels exist yet, create the defaults (see `backlog-health` skill for the label table) before creating issues.
    - Comment on the issue tagging the Product Owner to take over backlog grooming
 3. If the Product Owner is active and the backlog has 1+ issues, skip this step.
@@ -18,3 +19,4 @@ On your heartbeat, after handling assignments:
 - This is a safety net, not your primary job. Let the PO own it.
 - Only create issues when engineers would otherwise have nothing to work on.
 - Keep it minimal — just enough to unblock, not a full grooming session.
+- **Review handoff:** When moving an issue to `in_review`, always assign it to the reviewer. If the issue has an executionPolicy with review stages, Paperclip reassigns automatically. Otherwise PATCH `assigneeAgentId` to the reviewer before or at the same time as the status change.

package/templates/modules/backlog/agents/product-owner/heartbeat-section.md

@@ -1,3 +1,3 @@
 ## Backlog Health Routine
 
-Do not groom the backlog during a normal heartbeat unless that is your assigned issue. When you are assigned a routine-run issue titled like "Backlog grooming" or "Backlog health", use `skills/backlog-health.md`, then summarize generated/updated issues on the routine issue and exit.
+Do not groom the backlog during a normal heartbeat unless that is your assigned issue. When you are assigned a routine-run issue titled like "Backlog grooming" or "Backlog health", use `$AGENT_HOME/skills/backlog-health.md`, then summarize generated/updated issues on the routine issue and exit.

package/templates/modules/backlog/docs/backlog-process.md

@@ -9,7 +9,7 @@ Goal → Roadmap → Issues → Assignment → Execution → Done
 ```
 
 1. **Goal decomposition** — The backlog owner breaks the company goal into milestones, then milestones into actionable issues.
-2. **Issue creation** — New issues enter the backlog via `POST /api/companies/{companyId}/issues` with `title`, `description`, `priority`, `projectId`, `goalId`, and `labelIds`. Top-level backlog issues must always include the active roadmap `projectId`.
+2. **Issue creation** — New issues enter the backlog via `POST /api/companies/{companyId}/issues` with `title`, `description`, `priority`, `projectId`, `goalId`, and `labelIds`. Top-level backlog issues must always include the active roadmap `projectId`. They must also set workspace isolation explicitly — see **Workspace Isolation** below.
 3. **Pipeline health** — The backlog owner monitors the ready assigned queue. When fewer than about 8 actionable ready issues remain across the active delivery roles, the next small batch is generated from the roadmap.
 4. **Assignment** — Issues are assigned at creation to the best-fit owner. Engineering-ready issues go directly to the Software Engineer (or matching delivery role) so assignment wakeups start work immediately. Leave an issue unassigned only when no suitable owner exists.
 5. **Execution** — Agents check out assigned issues, work them, and hand off deliberately for review or completion.
@@ -28,6 +28,39 @@ Every issue should be:
 
 Write acceptance criteria in the issue description. Engineers use these to validate their work before marking done. Keep them concrete and testable.
 
+## Workspace Isolation (required at creation)
+
+Every issue runs in a git execution workspace (worktree/branch). To let issues run in
+parallel without colliding in the same worktree, you must declare the workspace intent
+**when you create the issue** — otherwise the issue silently adopts the workspace of
+whatever issue you currently have checked out, which serializes work and corrupts branch
+state.
+
+- **Top-level issue** (independent work, no `parentId`): always send
+  `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` in the create body. This
+  gives the issue its own worktree and branch.
+- **Sub-issue** (part of a larger parent task): set `"parentId": "<parent-issue-id>"` and
+  do **not** send `executionWorkspaceSettings`. The sub-issue deliberately reuses the
+  parent's workspace (the parent cannot be completed/cleaned up while its sub-issues are
+  still open, so sharing is safe and intended).
+
+**Never** create a top-level issue without `executionWorkspaceSettings`. Doing so makes it
+inherit the creator's currently checked-out workspace and blocks parallel execution.
+
+Example top-level create body:
+
+```json
+{
+  "title": "Build campaign onboarding wizard",
+  "description": "...",
+  "priority": "high",
+  "projectId": "<roadmap-project-id>",
+  "goalId": "<goal-id>",
+  "labelIds": ["<label-id>"],
+  "executionWorkspaceSettings": { "mode": "isolated_workspace" }
+}
+```
+
 ## Sources of Issues
 
 Issues can enter the backlog from multiple sources:
@@ -60,3 +93,7 @@ Re-prioritize when milestones shift or new information arrives. Don't let low-pr
 - The backlog owner coordinates with the CEO on strategic priorities when unclear.
 - If the goal is fully decomposed and all issues are done or in progress, report completion to the CEO rather than inventing new work.
 - When multiple agents create issues (e.g., from user-testing findings), the backlog owner reviews and re-prioritizes as needed.
+
+## Review Handoff
+
+When an issue is ready for review (moving to `in_review`), it must be assigned to the reviewer. If an executionPolicy with review stages is configured, Paperclip reassigns automatically. Otherwise, the person moving the issue must PATCH `assigneeAgentId` to the reviewer. An issue in `in_review` that is still assigned to the original implementer will stall — no one picks it up. Always reassign on review handoff.

package/templates/modules/backlog/docs/backlog-template.md

@@ -39,7 +39,7 @@ _Summary of current backlog health. Update on each heartbeat cycle._
 - **Ready assigned issues:** _(count by owner)_
 - **Unassigned todo issues:** _(count; should normally be 0 except items without a suitable owner)_
 - **In-progress issues:** _(count)_
-- **Health:** _(healthy / thin / empty / bloated — see backlog-process.md)_
+- **Health:** _(healthy / thin / empty / bloated — see docs/backlog-process.md)_
 
 ## Decisions Log
 

package/templates/modules/backlog/module.meta.json

@@ -24,7 +24,7 @@
       "title": "Backlog grooming",
       "description": "Routine-run checklist: inspect roadmap/backlog health, ensure at least 8 actionable ready issues exist, create scoped issues (around 3-6 per pass) and assign each to its best-fit agent when capacity is low, link artifacts/goals/projects, summarize changes on the routine issue, then exit.",
       "assignTo": "capability:backlog-health",
-      "schedule": "0 */4 * * *",
+      "schedule": "0 */2 * * *",
       "priority": "medium",
       "concurrencyPolicy": "skip_if_active"
     }

package/templates/modules/backlog/skills/backlog-health.bar.md

@@ -3,7 +3,9 @@
 A good backlog health pass:
 
 - Every issue created is INVEST-shaped: has a clear title, written acceptance criteria in the description, a priority, a label, and is attached to the correct `projectId` and `goalId` — never a top-level issue with `projectId: null`.
+- Every issue declares workspace isolation explicitly: top-level issues (no `parentId`) carry `"executionWorkspaceSettings": { "mode": "isolated_workspace" }`; subissues set `parentId` and omit it. A top-level issue created without it is not done — it would inherit the creator's checked-out workspace and block parallel execution.
 - The team keeps a healthy queue of ready, **assigned** work (toward the grooming target of ~8 actionable ready issues); when the assigned ready queue runs low, new issues are created **and assigned** from the roadmap so no agent goes idle between grooming cycles, and the action is recorded in daily notes. Issues are assigned at creation — do not stockpile a pool of unassigned issues.
+- Review handoff: when moving an issue to `in_review`, always reassign it to the reviewer. Without reassignment, `in_review` issues stall with the implementer still assigned.
 
 Not done:
 

package/templates/modules/backlog/skills/backlog-health.md

@@ -30,10 +30,11 @@ Add additional labels if the roadmap calls for them (e.g., `docs`, `design`, `se
 3. Query existing issues for the relevant project/goal and avoid duplicates.
 4. If the backlog is thin or unclear, create around 3-6 small actionable issues via `POST /api/companies/{companyId}/issues`.
 5. Each issue must include: `title`, acceptance-oriented `description`, `priority`, `projectId`, `goalId` when known, and `labelIds`.
-6. Use `blockedByIssueIds` for real dependencies instead of free-text blockers.
-7. Assign each issue to the best-fit available agent as you create it — engineer-actionable work with clear acceptance criteria goes to the Software Engineer (or the matching role). Direct push-assignment is the primary dispatch path; the assigned queue is the buffer, so do **not** stockpile a pool of unassigned ready work. Leave an issue unassigned only when no suitable owner exists — the low-frequency auto-assign safety net will catch those.
-8. Record generated issue ids and rationale in the routine issue comment; use issue documents for long plans.
-9. Mark the routine-run issue done when complete.
+6. Set workspace isolation explicitly on every issue you create (see Rules): top-level issues send `"executionWorkspaceSettings": { "mode": "isolated_workspace" }`; sub-issues set `parentId` and omit it.
+7. Use `blockedByIssueIds` for real dependencies instead of free-text blockers.
+8. Assign each issue to the best-fit available agent as you create it — engineer-actionable work with clear acceptance criteria goes to the Software Engineer (or the matching role). Direct push-assignment is the primary dispatch path; the assigned queue is the buffer, so do **not** stockpile a pool of unassigned ready work. Leave an issue unassigned only when no suitable owner exists — the low-frequency auto-assign safety net will catch those.
+9. Record generated issue ids and rationale in the routine issue comment; use issue documents for long plans.
+10. Mark the routine-run issue done when complete.
 
 ## Rules
 
@@ -41,6 +42,8 @@ Add additional labels if the roadmap calls for them (e.g., `docs`, `design`, `se
 - Do not create top-level backlog issues with `projectId: null` when a project exists.
 - Keep issues small and actionable. Each should be completable, tested, and reviewed independently.
 - Split into subissues only when each child can be completed independently; avoid splitting tightly coupled implementation across sibling subissues.
+- **Set workspace isolation explicitly at creation.** Top-level issues (no `parentId`) must send `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so each gets its own worktree/branch. Sub-issues set `parentId` and omit `executionWorkspaceSettings` so they reuse the parent's workspace. Never create a top-level issue without it — otherwise it inherits the workspace of whatever issue you currently have checked out and blocks parallel work.
 - Always attach at least one label to every issue you create.
 - If the goal is fully decomposed into issues, do not create more. Report status and next review trigger to the CEO/Product Owner.
 - Work products such as roadmap drafts or decomposition tables belong in issue documents/artifacts, not only comments.
+- **Review handoff:** When moving an issue to `in_review`, always assign it to the reviewer. If the issue has an executionPolicy with review stages, Paperclip reassigns automatically. If there is no executionPolicy, PATCH the issue's `assigneeAgentId` to the reviewer before or at the same time as the status change. An issue in `in_review` that is still assigned to the original implementer will stall — no one picks it up. Always reassign on review handoff.

package/templates/modules/competitive-intel/skills/competitive-tracking.md

@@ -16,7 +16,7 @@ You own competitive intelligence. This is a living analysis — profiles evolve
    - **Gaps and opportunities**: Where competitors are weak and we can win
    - **Threats**: Where competitors are strong and we need to defend
 3. Create follow-up issues for strategic decisions informed by competitive insights:
-   - `POST /api/companies/{companyId}/issues` with specific recommendations. Include the active `projectId` (and `goalId` / `parentId` when applicable).
+   - `POST /api/companies/{companyId}/issues` with specific recommendations. Include the active `projectId` (and `goalId` / `parentId` when applicable). For top-level issues (no `parentId`), also include `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so each gets its own worktree; subissues set `parentId` and omit it.
 4. Record summary in your daily notes
 
 ## Rules

package/templates/modules/github-repo/agents/engineer/skills/git-workflow.md

@@ -2,31 +2,76 @@
 
 You work in a GitHub repository. Follow the conventions in `docs/git-workflow.md` in the project root.
 
-## Direct-to-Base-Ref Flow
+## PR Self-Merge Flow (no pr-review module)
 
-Use this flow when the **pr-review module is not active** — i.e., there is no Code Reviewer role and no executionPolicy review stages. In this flow, you commit and merge directly; there is no external review gate.
+Use this flow when the **pr-review module is not active**. You open a PR and merge it yourself — there is no external review gate, but all changes go through a PR so the branch history is preserved and branch protection is respected.
 
 1. Before the first push on a project, confirm the GitHub credential helper from `docs/git-workflow.md` -> *GitHub Push Authentication* is installed in the primary repository. If `GH_TOKEN` is not injected or the helper cache is empty, stop and escalate instead of attempting unauthenticated pushes.
 2. Resolve the base ref from project workspace metadata or the issue's `heartbeat-context`. Use the configured `repoRef`, `defaultRef`, or `executionWorkspacePolicy.workspaceStrategy.baseRef` exactly as Paperclip provides it. Never guess from the current shell 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`.
 3. Pull/update latest from that base:
    - external: `git fetch origin`, then integrate from the configured base ref
    - local: update from the configured local branch
-4. Make your changes
-5. Run available checks (lint, typecheck, tests)
-6. Commit using Conventional Commits: `<type>: <description>`
-7. Push your branch: `git push -u origin <branch-name>`
-8. Merge to base and push:
-   - `git checkout <base-ref>` (the same resolved base branch from step 2)
-   - `git merge <branch-name> --no-edit`
-   - Resolve any conflicts (favor your changes; if uncertain, escalate to the CEO)
-   - `git push origin <base-ref>`
-9. Clean up the feature branch: `git push origin --delete <branch-name>` (remote) and `git branch -d <branch-name>` (local)
-10. If the issue uses an isolated execution workspace (worktree), archive it from your `heartbeat-context` after the merge is pushed.
-11. If CI fails on the base branch after the merge, fix immediately.
+4. **Create a feature branch** from the base ref: `git checkout -b <branch-name> <base-ref>`. Never commit directly on the base branch. The branch name should reference the issue (e.g., `LEA-5-add-landing-hero`). If you are already on a correctly named feature branch, skip this step.
+5. Verify you are on the feature branch before making changes: `git branch --show-current` must print `<branch-name>`, not the base ref. If it prints the base ref name, you forgot step 4 — create the branch now.
+6. Make your changes
+7. Run available checks (lint, typecheck, tests)
+8. Commit using Conventional Commits: `<type>: <description>`
+9. 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.
+10. Open a pull request against the base ref: `gh pr create --base <github-base-branch> --head <branch-name> --title "<type>: <description>" --body-file <file>`. Write the PR body (summary, what changed, how to verify) to a temp file first — never inline `--body "..."`. Register the PR as a Paperclip work product (see *Register the PR as a Work Product* below). Verify the PR base matches the configured base ref before merging.
+11. Merge the PR yourself: `gh pr merge <PR-number> --merge`. After opening the PR, merge it yourself promptly — do not wait for a reviewer if none is present. Confirm the PR is closed and the base branch updated before continuing.
+12. Clean up the feature branch: `git push origin --delete <branch-name>` (remote) and `git branch -d <branch-name>` (local). Update the Paperclip work product to `"status": "merged"` via `PATCH /api/work-products/{workProductId}`.
+13. If the issue uses an isolated execution workspace (worktree), archive it from your `heartbeat-context` after the merge is pushed.
+14. If CI fails on the base branch after the merge, fix immediately.
+
+## Branch Protection Setup
+
+Configure branch protection once during initial repository setup (this is part of the "Prepare GitHub repository" foundation issue). Branch protection must require a PR before merging but must NOT require GitHub-native approving reviews — all agents share one GitHub account and cannot formally approve their own PRs (unless the project has distinct non-author GitHub reviewer credentials, in which case `required_approving_review_count` may be raised).
+
+```bash
+gh api repos/{owner}/{repo}/branches/{base}/protection \
+  --method PUT --input - <<'EOF'
+{
+  "required_status_checks": null,
+  "enforce_admins": true,
+  "required_pull_request_reviews": {
+    "required_approving_review_count": 0,
+    "dismiss_stale_reviews": false
+  },
+  "restrictions": null
+}
+EOF
+```
+
+Replace `{owner}`, `{repo}`, `{base}` with the actual values. `enforce_admins: true` so the shared admin account cannot bypass the PR requirement with a direct push — with `required_approving_review_count: 0` the admin can still open a PR and merge it with zero approvals, so the self-merge flow keeps working. `restrictions: null` means no push allowlist; the PR gate still applies (do not "fix" it with an empty array, which would block all pushes). If CI is configured (e.g. the ci-cd module is active), replace `"required_status_checks": null` with the CI context string instead of `null`. Escalate to CEO if `GH_TOKEN` does not have admin rights on the repository.
 
 ## When PR Review IS Active
 
-If the pr-review module is active and you have a Code Reviewer role on the team, do NOT use the Direct-to-Base-Ref Flow. Instead, use the PR Workflow skill (`skills/pr-workflow.md`) — open a PR, set executionPolicy review stages, and let the merge gate land the branch. Never merge your own branch when a PR review workflow is in place.
+If the pr-review module is active, do NOT use the PR Self-Merge Flow. Instead, use the PR Workflow skill (`skills/pr-workflow.md`):
+- **With a Code Reviewer on the team (PR-Gate mode):** Open a PR, set executionPolicy review stages, and let the Code Reviewer (non-author merge gate) land the branch. Never merge your own branch in this mode.
+- **Without a Code Reviewer (PR Self-Merge Flow):** Open a PR via `gh pr create`, but skip executionPolicy stages entirely. Other review roles (qa, product-owner, security-engineer) may leave advisory comments. Merge the PR yourself via `gh pr merge <N> --merge` once CI is green. See `skills/pr-workflow.md` step 12 for the full self-merge path.
+
+## Register the PR as a Work Product
+
+Whenever you open a pull request (via `gh pr create`), immediately register it as a Paperclip work product so it shows up on the issue and the board. Creating the PR on GitHub alone does **not** make it visible in Paperclip.
+
+```
+POST /api/issues/{issueId}/work-products
+Headers: Authorization: Bearer $PAPERCLIP_API_KEY, X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID
+{
+  "type": "pull_request",
+  "provider": "github",
+  "externalId": "<PR number, e.g. 132>",
+  "url": "<full PR URL from `gh pr create`>",
+  "title": "<PR title>",
+  "status": "ready_for_review",
+  "isPrimary": true
+}
+```
+
+Notes:
+- `title` and `url` are required; `url` must be the full PR URL.
+- If the issue runs in an isolated execution workspace, also pass `"executionWorkspaceId"` from your `heartbeat-context` so the PR is linked to that worktree.
+- When the PR later merges or closes, update the work product (`PATCH /api/work-products/{workProductId}`) with `"status": "merged"` or `"closed"`.
 
 ## Rules
 
@@ -40,4 +85,6 @@ If the pr-review module is active and you have a Code Reviewer role on the team,
 - Never mark an issue as `done` unless at least one new commit was created for that issue's work and has been pushed.
 - Before marking `done`, verify there is no uncommitted work (`git status --short` should be clean).
 - If no repository change is required, do not mark `done` silently: leave an issue comment explaining why no code change was needed and escalate to the CEO for decision.
-- When working without a PR review flow, you are the merge owner. Merge your branch to base promptly after pushing — do not leave branches dangling unmerged.
+- You are always the merge owner when no code-reviewer is present. Open a PR and merge it yourself via `gh pr merge <N> --merge` promptly — do not leave branches dangling unmerged. Never do a direct `git merge` + push to the base branch; always go through a PR so the branch history is preserved and branch protection is respected (typos/comment-only/doc fixes with an issue reference may be committed directly to the base ref only when branch protection allows it — see `docs/git-workflow.md` → *Dev Cycle Rules*).
+- **Always work on a feature branch, never on the base branch.** Create the branch with `git checkout -b <branch-name> <base-ref>` before committing. Verify with `git branch --show-current` before every push.
+- **Never push the base ref as if it were a feature branch.** Before `git push -u origin <branch-name>`, confirm that `git branch --show-current` matches `<branch-name>`. If it prints the base ref name instead, you are on the wrong branch — create or switch to the feature branch first.

package/templates/modules/github-repo/docs/git-workflow.md

@@ -79,29 +79,26 @@ Rules:
   should print the helper path, and `test -s "$(git rev-parse --git-common-dir)/paperclip-gh-token-cache"`
   should succeed after a run where `GH_TOKEN` was injected.
 
-## Direct-to-Base-Ref Workflow
+## PR Self-Merge Flow
 
-Use this workflow when the **pr-review module is not active** (no Code Reviewer role, no executionPolicy review stages). When PR review is active, use the PR workflow from `docs/pr-conventions.md` instead.
+Use this flow when the **pr-review module is not active** (no Code Reviewer role, no executionPolicy review stages). You open a PR and merge it yourself — there is no external review gate, but all changes go through a PR so branch history is preserved and branch protection is respected. When PR review is active, use the PR workflow from `docs/pr-conventions.md` instead.
 
 1. Resolve the configured base ref from project workspace metadata or the issue's `heartbeat-context` before touching Git. Do not infer it from the current shell branch and do not rewrite it to `main`, `master`, or `origin/*`.
    - External repos: use the project/worktree `repoRef`, `defaultRef`, or `executionWorkspacePolicy.workspaceStrategy.baseRef` exactly as configured.
    - Fresh/local repos: use the configured local branch.
    - Only if no base ref is configured anywhere, detect the repository's default branch — see *Resolving the default branch* below. Never hard-code `main`.
 2. Pull/fetch latest from that base before editing.
-3. Make changes
-4. Run tests/linting locally if available
-5. Commit with conventional commit message
-6. Push your feature branch: `git push -u origin <branch-name>`
-7. Merge to base and push:
-   ```
-   git checkout <base-ref>
-   git merge <branch-name> --no-edit
-   git push origin <base-ref>
-   ```
-   Resolve any merge conflicts (favor your changes; if uncertain, escalate).
-8. Delete the feature branch: `git push origin --delete <branch-name>` and `git branch -d <branch-name>`
-9. If the issue uses an isolated execution workspace (worktree), archive it from `heartbeat-context`.
-10. Verify CI passes on the base branch (if configured). If CI fails, fix immediately.
+3. **Create a feature branch** from the base ref: `git checkout -b <branch-name> <base-ref>`. Never commit directly on the base branch. The branch name should reference the issue (e.g., `LEA-5-add-landing-hero`). If you are already on a correctly named feature branch, skip this step.
+4. **Verify you are on the feature branch** before making changes: `git branch --show-current` must print `<branch-name>`, not the base ref. If it prints the base ref name, you forgot step 3 — create the branch now.
+5. Make changes
+6. Run tests/linting locally if available
+7. Commit with conventional commit message
+8. **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.
+9. Open a pull request against the base ref: write the PR body to a temp file, then `gh pr create --base <github-base-branch> --head <branch-name> --title "<type>: <description>" --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal (see *Posting PR Bodies & Comments* in `docs/pr-conventions.md`). Verify the PR base matches the configured base ref before merging.
+10. Merge the PR yourself: `gh pr merge <PR-number> --merge`. Do not wait for a reviewer if none is present. Confirm the PR is closed and the base branch updated before continuing. Never do a direct `git merge` + push to the base branch; always go through a PR.
+11. Clean up the feature branch: `git push origin --delete <branch-name>` (remote) and `git branch -d <branch-name>` (local).
+12. If the issue uses an isolated execution workspace (worktree), archive it from `heartbeat-context` after the merge is pushed.
+13. Verify CI passes on the base branch (if configured). If CI fails, fix immediately.
 
 ## Resolving the default branch
 
@@ -143,6 +140,11 @@ For a brand-new local repository there is no remote yet, so initialize on `main`
 - If Paperclip created an isolated execution workspace for this issue, close/archive it after the commit/PR has landed and before marking `done`. If cleanup is blocked or fails, leave the issue open with the exact cleanup blocker. If the issue is in the shared project workspace, do not invent isolated-worktree cleanup.
 - If no repository change is required, do not silently close as `done`: add an issue comment explaining why no code change was needed and escalate to the CEO for explicit decision.
 
+## Branch Safety
+
+- **Always work on a feature branch, never on the base branch.** Create the branch with `git checkout -b <branch-name> <base-ref>` before committing any changes. If you are resuming work on an existing issue, `git branch --show-current` should already show the feature branch name.
+- **Verify your branch before pushing.** Before running `git push -u origin <branch-name>`, confirm that `git branch --show-current` prints the feature branch name — not the base ref. If it prints the base ref, you are on the wrong branch: stop and create/switch to the feature branch first. Pushing the base ref as a feature branch corrupts upstream tracking and causes incorrect branch divergence reports.
+
 ## CI
 
 If the project has CI configured (e.g., GitHub Actions), always verify your push passes CI. If CI fails, fix it immediately — a broken base ref blocks everyone.

package/templates/modules/market-analysis/agents/ux-researcher/skills/market-analysis.md

@@ -12,7 +12,7 @@ You own market research with a focus on user needs and behavior. This is your co
    - **Positioning**: Where the biggest user need gaps are
    - **Risks**: Adoption barriers, user switching costs, behavioral resistance
 3. Create follow-up issues for deeper research if needed:
-   - `POST /api/companies/{companyId}/issues` for user interview plans, usability benchmarks. Include the active `projectId` (and `goalId` / `parentId` when applicable).
+   - `POST /api/companies/{companyId}/issues` for user interview plans, usability benchmarks. Include the active `projectId` (and `goalId` / `parentId` when applicable). For top-level issues (no `parentId`), also include `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so each gets its own worktree; subissues set `parentId` and omit it.
 4. Share findings by updating the assigned issue/document and assigning concrete follow-up actions to the Product Owner and CEO when needed; do not rely on generic @-mentions.
 
 ## Rules

package/templates/modules/market-analysis/skills/market-analysis.md

@@ -11,7 +11,7 @@ You own market research and competitive analysis. This informs the product roadm
    - **Positioning**: How do we differentiate? What's our unique value proposition?
    - **Risks**: Market risks, timing risks, adoption barriers
 3. Create follow-up issues for any strategic decisions needed:
-   - `POST /api/companies/{companyId}/issues` with findings that require input. Include the active `projectId` (and `goalId` / `parentId` when applicable).
+   - `POST /api/companies/{companyId}/issues` with findings that require input. Include the active `projectId` (and `goalId` / `parentId` when applicable). For top-level issues (no `parentId`), also include `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so each gets its own worktree; subissues set `parentId` and omit it.
 4. Record summary in your daily notes
 
 ## Rules

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

@@ -14,16 +14,14 @@ You review PRs for infrastructure impact, performance, security, and operational
 
 ## How to Review
 
-1. When you are the active participant of a review stage on an issue with a PR link, review the PR.
+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. Record your verdict through the normal issue update route for your review stage:
-   - **approved** if operationally sound
-   - **changes_requested** with specific concerns if not
-4. 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*.
+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.
 
 ## Rules
 
-- Security issues are always blockers — never approve PRs with exposed secrets or critical vulnerabilities.
-- Performance concerns are blockers only if they affect production. Flag others as suggestions.
-- Approve changes with no infrastructure impact without comment.
+- Flag security issues (exposed secrets, critical vulnerabilities) as blocking-severity in your advisory comment so the Security Engineer (or merge gate) acts on them; you do not yourself withhold a stage verdict. When a Security Engineer review stage exists, defer security blocking to it.
+- Performance concerns are blocking-severity only if they affect production; flag others as suggestions.
+- Comment only on changes with infrastructure impact.
 - If a change needs a migration or deployment step, ensure it's documented in the PR.

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

@@ -9,20 +9,38 @@ When this skill is active, you work in feature branches and open PRs instead of
    - 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. Make your changes, commit with Conventional Commits format
-5. Push branch: `git push -u origin <branch-name>`
-6. Open PR against the same resolved base: derive the GitHub base branch from the configured ref (for example, strip the remote prefix only when the ref is remote-tracking), write the body (PR Body Template in `docs/pr-conventions.md`) to a file, then `gh pr create --base <github-base-branch> --head <branch-name> --title "<type>: <description>" --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal and the PR renders as `text\ntext` (see *Posting PR Bodies & Comments*).
-7. Set the originating issue's `executionPolicy` to gate the merge on review, ending with the Code Reviewer as the merge gate:
+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.
+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: derive the GitHub base branch from the configured ref (for example, strip the remote prefix only when the ref is remote-tracking), write the body (PR Body Template in `docs/pr-conventions.md`) to a file, then `gh pr create --base <github-base-branch> --head <branch-name> --title "<type>: <description>" --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal and the PR renders as `text\ntext` (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
+   Headers: Authorization: Bearer $PAPERCLIP_API_KEY, X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID
+   {
+     "type": "pull_request",
+     "provider": "github",
+     "externalId": "<PR number>",
+     "url": "<full PR URL>",
+     "title": "<PR title>",
+     "status": "ready_for_review",
+     "isPrimary": true
+   }
+   ```
+   `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. 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).
-   - Additional `review` stages only for domain reviewers that should block this specific change.
-   - An `approval` stage with the **Product Owner** as participant (always) — the product sign-off.
-   - 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, use another present non-author agent (e.g. DevOps, the Product Owner, or another engineer) — never yourself.
+   - 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.
    - **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.
-8. Move the originating issue to `in_review`.
-9. 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.
-10. 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, and records the final `approved` that closes the issue to `done`. Your remaining job is to respond to `changes_requested`: when a stage routes the issue back to you (the `returnAssignee`), address the feedback, push to the same branch, and the routed stage re-runs.
+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.
+    - **No code-reviewer present (PR Self-Merge Flow):** You already skipped steps 9–11. Merge the PR yourself: `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 archive any isolated worktree.
 
 ## Rules
 
@@ -30,9 +48,10 @@ When this skill is active, you work in feature branches and open PRs instead of
 - One PR per issue. Keep changes focused.
 - Always include `Closes [PREFIX-N]` in the PR body.
 - If a reviewer requests changes, address them, push to the same branch, and re-request review (the stage re-runs).
-- The Code Reviewer (the non-author merge gate) is the merge owner. You cannot merge your own PR — Paperclip excludes you (the executor) from every review/approval stage. Hand off cleanly by setting the policy correctly, not by merging yourself.
+- 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** (or another present non-author agent) 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`.
+- **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.
 - 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.
 - Post-merge cleanup of any isolated execution workspace belongs to the merge-gate agent (they archive it from `heartbeat-context` when landing the PR). You only clean up your own worktree if you abandon a branch or the issue is cancelled before review. If this issue runs in the shared project workspace, do not invent isolated-worktree cleanup.
+- **Never push the base ref as if it were a feature branch.** Before `git push -u origin <branch-name>`, confirm that `git branch --show-current` matches `<branch-name>`. If it prints the base ref name instead, you are on the wrong branch — create or switch to the feature branch first.

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 final approver — you are the participant of the `approval` stage on the PR's issue, and your sign-off is the last gate before merge.
+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.
 
 ## Review Checklist
 
@@ -25,4 +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 final governance signal. 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.
+- 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.

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

@@ -14,16 +14,14 @@ You review PRs for visual quality, brand consistency, and accessibility. When a
 
 ## How to Review
 
-1. When you are the active participant of a review stage on an issue with a PR link, review the PR.
+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. Record your verdict through the normal issue update route for your review stage:
-   - **approved** if visually sound
-   - **changes_requested** with specific, actionable feedback if not
-4. 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*.
+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.
 
 ## Rules
 
 - Be specific — "the button should use `--color-primary`" beats "wrong color".
-- Approve changes that don't touch UI without comment — not every PR needs design review.
+- 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.
 - Screenshots or before/after comparisons strengthen feedback when possible.