Merge pull request 'Clarify and enforce reviewer-vs-merger role boundaries (#483)' (#486) from feat/issue-483-role-boundaries into master

docs/gitea-dual-namespace-deployment.md

@@ -22,9 +22,12 @@ launched with exactly one static execution profile:
 | Namespace (MCP server name) | Profile (role) | Typical use |
 |-----------------------------|----------------|-------------|
 | `gitea-author` | an author profile | implement issues, push branches, open PRs, comment |
-| `gitea-reviewer` | a reviewer profile | review, approve/request changes, merge |
+| `gitea-reviewer` | a reviewer profile | review, approve/request changes |
+| `gitea-merger` | a merger profile | merge PRs after approval and verification |
 | `gitea-reconciler` | a reconciler profile | close already-landed open PRs after ancestry proof (#304 profile; #310 close tool) |
 
+Review and merge are separate workflow roles. A reviewer approval is not merge authorization.
+
 Properties:
 
 - **One process, one credential.** Each namespace authenticates as exactly
@@ -106,6 +109,14 @@ syntax to the client):
         "GITEA_MCP_CONFIG": "<path-to-profiles.json>",
         "GITEA_MCP_PROFILE": "<reviewer-profile-name>"
       }
+    },
+    "gitea-merger": {
+      "command": "<path-to>/venv/bin/python3",
+      "args": ["<path-to>/mcp_server.py"],
+      "env": {
+        "GITEA_MCP_CONFIG": "<path-to-profiles.json>",
+        "GITEA_MCP_PROFILE": "<merger-profile-name>"
+      }
     }
   }
 }

docs/gitea-execution-profiles.md

@@ -311,7 +311,8 @@ To make Gitea MCP profile activation and runtime identity state explicit, the fo
 ### 2. Dual MCP Namespaces Recommendation
 For security-sensitive or high-risk tasks, the preferred safety model uses separate, isolated MCP server instances (namespaces/sessions) launched with static profiles:
 - `gitea-author`: Exposes tools configured with author permissions; cannot perform approvals or merges.
-- `gitea-reviewer`: Exposes tools configured with reviewer permissions; used for PR reviews and merges.
+- `gitea-reviewer`: Exposes tools configured with reviewer permissions; used for PR reviews. Review and merge are separate workflow roles. A reviewer approval is not merge authorization.
+- `gitea-merger`: Exposes tools configured with merger permissions; used for PR merges.
 This layout maintains physical separation of credentials and prevents privilege escalation within a single session.
 This is the model accepted in #139; deployment details, rationale, and client
 setup live in

docs/llm-workflow-runbooks.md

@@ -704,10 +704,10 @@ loop and do **not** substitute WebFetch/Playwright/manual base64.
 ### Merge a PR
 
 - **Profile:** merger (allowed to merge; must **not** be the PR author).
-- **Steps:** confirm eligibility; require explicit confirmation
-  (`MERGE PR <n>`); optionally pin head SHA / changed-file set; merge only when
-  Gitea reports the PR mergeable (branch-protection checks satisfied). No force,
-  no ignore-checks. Verify that remote master contains the merge commit or the expected squashed changes (do not assume a "closed" PR succeeded without verifying the actual landed changes).
+- **Steps:**
+  - Merger workflow starts only after formal approval at current head. Reviewer workflow ends with review decision and separate merger handoff.
+  - Confirm eligibility; require explicit confirmation (`MERGE PR <n>`); optionally pin head SHA / changed-file set; merge only when Gitea reports the PR mergeable (branch-protection checks satisfied). No force, no ignore-checks. Verify that remote master contains the merge commit or the expected squashed changes (do not assume a "closed" PR succeeded without verifying the actual landed changes).
+  - Review and merge are separate workflow roles. A reviewer approval is not merge authorization.
 - **Prompt:** `Use any eligible merger profile to merge PR #N if checks pass and
   it is mergeable. Confirm with "MERGE PR N". Do not force-merge.`
 
@@ -796,7 +796,7 @@ an author.
 |---|---|---|---|---|
 | Review PR (`review_pr`) | reviewer (e.g. `sysadmin` / `prgs-reviewer`) | read, gated review verdicts | commits, pushes, file edits, author comments, merge without eligibility | active profile is an author profile — stop immediately; do **not** switch to author-side fixes unless the operator explicitly re-tasks |
 | Address PR change requests (`address_pr_change_requests`) | author (e.g. `jcwalker3` / `prgs-author`) | commit/push fixes to the PR branch, PR comment summarizing fixes | review verdicts, approve, request-changes, merge | active profile lacks branch push |
-| Merge PR (`merge_pr`) | reviewer/merger | gated merge after eligibility + approval | merging own PR, merging without pinned head match | active profile is an author profile, or any merge gate fails |
+| Merge PR (`merge_pr`) | merger (e.g. `sysadmin` / `prgs-merger`) | gated merge after eligibility + approval | merging own PR, merging without pinned head match, reviewing PRs | active profile is an author or reviewer-only profile, or any merge gate fails |
 | Comment on issue discussion (`comment_issue`) | any profile with `gitea.issue.comment` | issue thread comments | review verdicts, closing via comment | permission missing (`gitea.pr.comment` does **not** imply it) |
 | Comment on PR (`comment_pr`) | any profile with `gitea.pr.comment` | PR thread comments | review verdicts | permission missing |
 | Author implementation (`create_branch`/`push_branch`/`create_pr`) | author | branch, commit, push, open PR | self-review, self-merge | profile lacks the author permissions |

docs/wiki/Identity-and-Profiles.md

@@ -16,12 +16,21 @@ bind an authenticated Gitea identity to an allowed operation set.
 - **Allowed:** branch create/push, PR create, issue comment/create/close, repo commit, read.
 - **Forbidden:** PR approve, merge, request_changes.
 
-### Reviewer / merger
+### Reviewer
 
 - **Profile:** `prgs-reviewer`
 - **Typical identity:** `sysadmin`
-- **Allowed:** PR review/approve/merge/request_changes, issue comment, read.
-- **Forbidden:** branch push, PR create, repo commit.
+- **Allowed:** PR review/approve/request_changes, issue comment, read.
+- **Forbidden:** branch push, PR create, repo commit, PR merge.
+
+Review and merge are separate workflow roles. A reviewer approval is not merge authorization.
+
+### Merger
+
+- **Profile:** `prgs-merger`
+- **Typical identity:** `sysadmin`
+- **Allowed:** PR merge, issue comment, read.
+- **Forbidden:** branch push, PR create, repo commit, PR approve, PR review, PR request_changes.
 
 ## Configuration