@starlein/paperclip-plugin-company-wizard 0.4.3 → 0.4.5-a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlein/paperclip-plugin-company-wizard",
-  "version": "0.4.3",
+  "version": "0.4.5a",
   "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

@@ -31,7 +31,7 @@ Each section (Goals, Projects, Labels, Agents, Issues, Routines) contains object
 
 **Review workflow guardrail:**
 
-- Required PR reviews use the issue's `executionPolicy` review/approval stages, not @-mentions and not separate child review issues. When an engineer opens a PR, set the implementation issue to `in_review` with the resolved execution policy: QA review when present, Security review only for security-relevant changes, Product Owner approval for scope/intent, and a final Engineer merge gate after verification is recorded. Each active participant records their decision through the normal issue update route (`approved` by PATCHing toward `done`, `changes_requested` by PATCHing back to `in_progress`), which is the issue-level reviewed/approved audit trail (`reviewed_by` / `approved_by` metadata where Paperclip exposes it). The Engineer merge gate must verify the PR base against the project/worktree base ref shown in `heartbeat-context`, merge before approving, close/archive any isolated worktree when one exists and close-readiness allows it, and only then record final approval. Follow `docs/pr-conventions.md` when the PR review module is active.
+- Required PR reviews use the issue's `executionPolicy` review/approval stages, not @-mentions and not separate child review issues. When an engineer opens a PR, set the implementation issue to `in_review` with the resolved execution policy: QA review when present, Security review only for security-relevant changes, Product Owner approval for scope/intent, and a final Code Reviewer merge gate after verification is recorded. **Never list the issue's executor/author as a participant in any stage** — Paperclip excludes the original executor from review/approval, so a stage whose only participant is the author stalls the issue in `in_review` (`422 No eligible approval participant`); the merge gate is therefore a non-author (the Code Reviewer), not the engineer who wrote the code. Each active participant records their decision through the normal issue update route (`approved` by PATCHing toward `done`, `changes_requested` by PATCHing back to `in_progress`), which is the issue-level reviewed/approved audit trail (`reviewed_by` / `approved_by` metadata where Paperclip exposes it). The Code Reviewer merge gate must verify the PR base against the project/worktree base ref shown in `heartbeat-context`, merge before approving, close/archive any isolated worktree when one exists and close-readiness allows it, and only then record final approval. Follow `docs/pr-conventions.md` when the PR review module is active.
 
 **Secrets guardrail:**
 

package/templates/modules/ci-cd/agents/devops/skills/ci-cd.md

@@ -6,11 +6,11 @@ You are the DevOps engineer and CI/CD is your core domain. You own the full pipe
 
 1. Review the tech stack to determine build, lint, and test tooling
 2. Create a CI workflow (GitHub Actions or equivalent):
-   - Lint on all PRs and pushes to main
-   - Run tests on all PRs and pushes to main
+   - Lint on all PRs and pushes to the default branch
+   - Run tests on all PRs and pushes to the default branch
    - Build/typecheck to verify compilation
 3. Create a CD workflow:
-   - Trigger on merge to main
+   - Trigger on merge to the default branch
    - Deploy to the target environment
    - Run smoke tests after deployment
 4. Add status badges to the project README
@@ -24,5 +24,5 @@ You are the DevOps engineer and CI/CD is your core domain. You own the full pipe
 - Use dependency caching (e.g., `actions/cache`, `setup-node` cache) to speed up installs.
 - Pin action versions to full SHAs, not tags, for security.
 - Never store secrets in workflow files — use GitHub Secrets or equivalent.
-- If CI breaks main, fix it immediately — a red main blocks everyone.
+- If CI breaks the default branch, fix it immediately — a red default branch blocks everyone.
 - Own pipeline health metrics — track build times, flake rates, deployment frequency.

package/templates/modules/ci-cd/agents/engineer/skills/ci-cd.fallback.md

@@ -5,7 +5,7 @@ The DevOps engineer primarily owns CI/CD pipelines. You are the fallback — ste
 ## CI/CD (Fallback)
 
 1. If no CI workflow exists and DevOps hasn't started:
-   - Create a basic CI workflow: lint + test on PRs, build on push to main
+   - Create a basic CI workflow: lint + test on PRs, build on push to the default branch
    - Use standard caching and pinned action versions
    - Document the setup in `docs/CI-CD.md`
    - Mark the pipeline as **provisional** — it needs DevOps review for CD, caching optimization, and security hardening

package/templates/modules/ci-cd/module.meta.json

@@ -52,7 +52,7 @@
     },
     {
       "title": "Set up deployment automation",
-      "description": "Configure automated deployment to at least one environment (staging or production). Use the CI pipeline to trigger deploys on successful builds from the main branch. Include a rollback strategy.",
+      "description": "Configure automated deployment to at least one environment (staging or production). Use the CI pipeline to trigger deploys on successful builds from the default branch. Include a rollback strategy.",
       "priority": "medium",
       "assignTo": "engineer"
     },
@@ -65,7 +65,7 @@
   ],
   "goal": {
     "title": "Set up CI/CD pipeline",
-    "description": "Establish a complete CI/CD pipeline: automated linting, testing, building, and deployment. Every push to main should be verified automatically, and deployments should be reproducible and low-risk.",
+    "description": "Establish a complete CI/CD pipeline: automated linting, testing, building, and deployment. Every push to the default branch should be verified automatically, and deployments should be reproducible and low-risk.",
     "project": false,
     "subgoals": [
       {
@@ -90,7 +90,7 @@
         "id": "deploy",
         "title": "Automated deployment",
         "level": "team",
-        "description": "Deploy to staging or production with minimal manual intervention. Pushes to main trigger automated deployment to at least one environment."
+        "description": "Deploy to staging or production with minimal manual intervention. Pushes to the default branch trigger automated deployment to at least one environment."
       }
     ]
   },

package/templates/modules/ci-cd/skills/ci-cd.bar.md

@@ -2,10 +2,10 @@
 
 A good CI/CD setup:
 
-- A working pipeline with a CI stage (lint → typecheck → test on every PR and push to main) and a CD stage (deploy on merge to main, smoke tests after deployment), documented in `docs/CI-CD.md` with status badges in the README.
+- A working pipeline with a CI stage (lint → typecheck → test on every PR and push to the default branch) and a CD stage (deploy on merge to the default branch, smoke tests after deployment), documented in `docs/CI-CD.md` with status badges in the README.
 - Pipelines complete in under 5 minutes (dependency caching in place), action versions pinned to full SHAs, and all secrets stored in GitHub Secrets or equivalent — none in workflow files.
 
 Not done:
 
 - A pipeline with no rollback path — deploying with no documented procedure for reverting a bad release or re-running the previous successful build is not done.
-- A pipeline that breaks main and is not fixed immediately, or one that stores secrets directly in the workflow YAML.
+- A pipeline that breaks the default branch and is not fixed immediately, or one that stores secrets directly in the workflow YAML.

package/templates/modules/ci-cd/skills/ci-cd.md

@@ -6,11 +6,11 @@ You manage continuous integration and deployment pipelines. Follow the conventio
 
 1. Review the tech stack to determine build, lint, and test tooling
 2. Create a CI workflow (GitHub Actions or equivalent):
-   - Lint on all PRs and pushes to main
-   - Run tests on all PRs and pushes to main
+   - Lint on all PRs and pushes to the default branch
+   - Run tests on all PRs and pushes to the default branch
    - Build/typecheck to verify compilation
 3. Create a CD workflow:
-   - Trigger on merge to main
+   - Trigger on merge to the default branch
    - Deploy to the target environment
    - Run smoke tests after deployment
 4. Add status badges to the project README
@@ -23,4 +23,4 @@ You manage continuous integration and deployment pipelines. Follow the conventio
 - Use dependency caching (e.g., `actions/cache`, `setup-node` cache) to speed up installs.
 - Pin action versions to full SHAs, not tags, for security.
 - Never store secrets in workflow files — use GitHub Secrets or equivalent.
-- If CI breaks main, fix it immediately — a red main blocks everyone.
+- If CI breaks the default branch, fix it immediately — a red default branch blocks everyone.

package/templates/modules/github-repo/README.md

@@ -10,7 +10,7 @@ Enables the Engineer to work in a GitHub repository.
 
 ## Variants
 
-- **direct-to-main** (default): Engineer commits directly on main. No branches, no PRs. Fast iteration for solo engineer setups.
+- **direct-to-base-ref** (default): Engineer commits directly on the default branch. No branches, no PRs. Fast iteration for solo engineer setups.
 - When combined with `pr-review` module: switches to feature-branch workflow automatically.
 
 ## Best for
@@ -21,4 +21,4 @@ Enables the Engineer to work in a GitHub repository.
 
 ## Example
 
-A company building a web app with one engineer. The engineer picks up issues, implements them, commits to main, and marks the issue done. CI runs on push.
+A company building a web app with one engineer. The engineer picks up issues, implements them, commits to the default branch, and marks the issue done. CI runs on push.

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

@@ -2,9 +2,9 @@
 
 You work in a GitHub repository. Follow the conventions in `docs/git-workflow.md` in the project root.
 
-## Direct-to-Main Flow
+## Direct-to-Base-Ref Flow
 
-1. 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/*`.
+1. 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`.
 2. Pull/update latest from that base:
    - external: `git fetch origin`, then integrate from the configured base ref
    - local: update from the configured local branch

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

@@ -33,11 +33,12 @@ directory inside the repository. This must never be committed.
 - Committing `.paperclip/` pollutes history and can nest isolated worktrees inside the
   repo, which causes confusing git state for every agent.
 
-## Direct-to-Main Workflow
+## Direct-to-Base-Ref Workflow
 
 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
@@ -45,6 +46,30 @@ directory inside the repository. This must never be committed.
 6. Push to the matching configured base branch
 7. Verify CI passes (if configured)
 
+## Resolving the default branch
+
+A configured base ref (`repoRef` / `defaultRef` / `workspaceStrategy.baseRef`) always wins — use it verbatim. Only when **none** is configured (typically at first-time setup of an existing repository) detect the default branch from the remote, and record it on the project workspace so later isolated worktrees branch from the right base.
+
+The base ref for worktrees should simply **be the repository's default branch, whatever it is named** — `main`, `master`, `trunk`, `develop`, anything. The authoritative source is what `origin/HEAD` points at. Resolution priority:
+
+1. **The remote's default branch** — whatever `origin/HEAD` resolves to. This is name-agnostic and is the answer in almost all cases.
+2. **`main`, then `master`** — only as a fallback when the remote advertises no default HEAD (rare/ambiguous).
+
+```bash
+# Prints the repository's default branch name (origin/HEAD; main/master only as fallback).
+git remote set-head origin --auto >/dev/null 2>&1 || true
+def=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@')
+[ -z "$def" ] && def=$(git ls-remote --symref origin HEAD 2>/dev/null | sed -n 's@^ref: refs/heads/\(.*\)\tHEAD@\1@p')
+if [ -z "$def" ]; then
+  if   git ls-remote --exit-code --heads origin main   >/dev/null 2>&1; then def=main
+  elif git ls-remote --exit-code --heads origin master >/dev/null 2>&1; then def=master
+  fi
+fi
+echo "$def"
+```
+
+For a brand-new local repository there is no remote yet, so initialize on `main` (`git init -b main`) — that is the conventional default for fresh repos.
+
 ## What Requires a Commit
 
 - Code logic changes
@@ -63,4 +88,4 @@ directory inside the repository. This must never be committed.
 
 ## 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 main blocks everyone.
+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/github-repo/module.meta.json

@@ -9,7 +9,7 @@
       "priority": "critical",
       "bootstrapPhase": "foundation",
       "labels": ["chore"],
-      "description": "Foundation setup: handle this before normal implementation issues. For a fresh repository, create the GitHub repository, initialize local workspace with a README or bootstrap commit, add origin, push main, and record the repository URL. For an existing repository, verify the workspace has a reachable remote, current default branch, and starter commit state; escalate to CEO if repo setup is missing instead of silently closing the issue. Before the first commit, ensure the repository's `.gitignore` ignores Paperclip's local state — add a `.paperclip/` entry (this is where Paperclip keeps per-issue git worktrees and workspace metadata inside the repo; committing it pollutes history and can nest worktrees inside the repo). Create `.gitignore` if it is missing. Branch protection is tracked separately by the pr-review module when that workflow is enabled."
+      "description": "Foundation setup: handle this before normal implementation issues. For a fresh repository, create the GitHub repository, initialize the local workspace with a README or bootstrap commit, add origin, push the default branch (`main` for a fresh repo), and record the repository URL. For an existing repository, verify the workspace has a reachable remote and a starter commit state, then determine the repository's default branch and confirm it is recorded as the project workspace `defaultRef`/`repoRef` so isolated worktrees branch from the correct base. The default branch is whatever `origin/HEAD` points at — name-agnostic (`main`, `master`, `trunk`, etc.); use it exactly as the remote advertises it (`git ls-remote --symref origin HEAD`). Only if the remote advertises no default HEAD, fall back to `main`, then `master`. Never assume `main` for an existing repo. Escalate to CEO if repo setup is missing instead of silently closing the issue. Before the first commit, ensure the repository's `.gitignore` ignores Paperclip's local state — add a `.paperclip/` entry (this is where Paperclip keeps per-issue git worktrees and workspace metadata inside the repo; committing it pollutes history and can nest worktrees inside the repo). Create `.gitignore` if it is missing. Branch protection is tracked separately by the pr-review module when that workflow is enabled."
     }
   ]
 }

package/templates/modules/launch-mvp/module.meta.json

@@ -36,7 +36,7 @@
   "issues": [
     {
       "title": "Create project repository and initial structure",
-      "description": "Initialize the repository with README, .gitignore, package.json (or equivalent), and a basic project structure. Push to main.",
+      "description": "Initialize the repository with README, .gitignore, package.json (or equivalent), and a basic project structure. Push to the default branch.",
       "priority": "high",
       "assignTo": "engineer"
     },

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

@@ -4,11 +4,11 @@ Adds a PR-based review workflow with dedicated reviewer roles.
 
 ## What it adds
 
-- **Core roles**: Product Owner (approval) and Engineer (final merge gate)
-- **Extended roles** *(when present)*: QA (substantive review), Security Engineer (security-relevant review), Code Reviewer/UI/UX/DevOps advisory or domain review when explicitly configured
+- **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
-- **Engineer skill**: Feature-branch + PR workflow (overrides direct-to-main from `github-repo`)
-- **Reviewer skills**: Review checklists for each reviewer role
+- **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
 
 ## Dependencies
 
@@ -19,13 +19,13 @@ 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 Engineer merge-gate approval stage (roles resolved to agentIds); the PR link is added as an issue comment
+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. Code Reviewer and domain reviewers may add advisory PR comments unless explicitly added as executionPolicy participants
+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. Engineer merges when all stages are approved (no `changes_requested` outstanding), confirms the PR landed on the correct base, closes/archives any isolated worktree that Paperclip created, and only then records the final approval / closes the issue
+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, closes/archives any isolated worktree that Paperclip created, and only then records the final approval / closes the issue
 
 ## Handover mechanism
 

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

@@ -1,25 +1,41 @@
-# Skill: Code Review (advisory)
+# Skill: Code Review (final merge gate)
 
-You provide an **advisory, non-binding** code review. You are *not a merge gate*: the merge is gated by executed verification — green CI, or QA running the tests (see `docs/pr-conventions.md`). Your value is a second pair of eyes on correctness, clarity, and simplicity that automated checks miss.
+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**, clean up, and only then record `approved` — which closes the issue to `done`.
 
-## What to look for
+## Why you, and not the engineer
 
-1. **Correctness** — Does the code do what the PR claims? Are edge cases handled? Does the logic match the stated intent?
-2. **Simplicity** — Is this the simplest solution that works? Could anything be removed without losing functionality?
-3. **Clarity** — Naming, structure, comments. Will the next reader understand this?
-4. **Security smells** — Obvious injection, exposed secrets, missing validation at boundaries. Defer deep security review to the Security Engineer when the change is security-relevant.
-5. **Dead code** — Commented-out blocks, unused branches.
+Paperclip's runtime **excludes the issue's original executor (the author) from every review and approval stage** to prevent self-review. A stage whose only participant is the author has *no eligible participant*, so the issue stalls in `in_review` forever (`422 No eligible approval participant is configured for this issue`). The merge therefore cannot be performed by the engineer who wrote the code — it must be a non-author. That is you.
+
+## What to verify before merging
+
+1. **Hard gate — executed verification (never skip):**
+   - With CI: the PR's CI (lint/test/build) must be **green**. Confirm it on the PR.
+   - Without CI: run the full test suite and build yourself and paste the real output into your verdict before merging.
+   - A merge without cited executed verification is invalid.
+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.
+
+## Merging
+
+1. Merge with `gh pr merge <number> --merge`. No force pushes.
+2. Confirm the merge landed on the correct base.
+3. If Paperclip created an isolated execution workspace for the issue, read its id from `heartbeat-context`, call close-readiness, and archive it after the merge and once the tree is clean. If cleanup is blocked or fails, do **not** record approval — leave the issue open with the exact blocker. If the issue runs in the shared project workspace, do not invent isolated-worktree cleanup.
+4. **Only after the merge and cleanup succeed**, record `approved` (PATCH toward `done`) with a comment citing the executed verification and the merge confirmation. That closes the issue.
+5. Never record `approved` before the merge has actually succeeded, and never leave the issue `done` with the PR still open.
+
+## 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.
 
 ## How to comment
 
-1. When the PR has a review stage assigned to you, read the diff (check it out locally if useful).
-2. Post your feedback as a GitHub PR comment via a Markdown file: open with a heading (`## 💬 Review notes`), then specific, actionable points, and run `gh pr comment <number> --body-file <file>`. Never inline `--body "..."` — `\n` stays literal in a double-quoted shell string. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
-3. If you are a participant on an advisory review stage, record your notes there too — but understand it does not gate the merge.
+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
 
-- Be constructive — suggest alternatives, don't just criticize.
-- Focus on substance over style; auto-formatters handle style.
-- "Looks good" is not useful feedback. Point at what you actually examined.
-- Raise correctness or security concerns clearly so QA / the Security Engineer / the Engineer can act on them before merge.
-- You do not gate the merge. If something must block, it belongs to QA (tests), the Security Engineer (security-relevant), or CI.
+- 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 green CI or pasted test/build output.
+- 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.

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

@@ -1,10 +1,10 @@
 # Skill: PR Workflow
 
-When this skill is active, you work in feature branches and open PRs instead of committing directly to main. 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` in the project root.
 
 ## 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/*`.
+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:
    - external: `git fetch origin`, then branch from the configured base ref
    - local: update from the configured local branch
@@ -12,26 +12,27 @@ When this skill is active, you work in feature branches and open PRs instead of
 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 your own merge gate:
+7. Set the originating issue's `executionPolicy` to gate the merge on review, ending with the Code Reviewer as the merge gate:
    - 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. Code Reviewer and other specialists are advisory by default unless explicitly configured as participants.
+   - 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 **yourself (the Engineer)** as participant — the **merge gate**. This stage exists so you are woken *last*, after every reviewer and the Product Owner have cleared, to perform the merge.
+   - 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.
+   - **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. When the issue reaches your final **merge gate** stage (you are the current participant and every prior stage is approved): run `gh pr merge <number> --merge`, confirm the merge landed into the configured project base, then close/archive the isolated execution workspace if one exists and close-readiness allows it. **Only after merge and workspace close/cleanup succeeds** record `approved` on your stage — that closes the issue to `done`. Never record `approved` before the merge has actually succeeded, and never set the issue to `done` with the PR still open or an execution workspace still active.
+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.
 
 ## Rules
 
-- Never commit directly to main (except typos/comment-only/doc fixes with issue reference).
+- Never commit directly to the base ref (except typos/comment-only/doc fixes with issue reference).
 - 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).
-- You are the merge owner — never ask reviewers to merge.
-- Before creating a PR or merging, verify the PR base matches the configured project/worktree base. If the base is wrong, retarget the PR before review/merge.
-- **Your merge gate must be the last stage.** 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` and you would never be woken to merge — leaving the PR open on GitHub. Always append your own merge-gate `approval` stage after the Product Owner's, and do the merge there before recording your verdict.
+- 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.
+- 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`.
 - 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.
-- If Paperclip created an isolated execution workspace for this issue, do not leave it behind. Use the current execution workspace id from `heartbeat-context`, check close-readiness, and archive it after the PR is merged and the tree is clean. If archive/cleanup is blocked, leave the issue `blocked` or `in_review` with the exact cleanup blocker instead of marking `done`. If this issue runs in the shared project workspace, do not invent isolated-worktree cleanup.
+- 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.

package/templates/modules/pr-review/docs/pr-conventions.md

@@ -69,42 +69,42 @@ Review runs through the issue's native `executionPolicy` (stages), not separate
    - a `review` stage for **QA** when a QA agent is on the team (test adequacy / running the tests),
    - a `review` stage for the **Security Engineer** *only when the change is security-relevant* (auth, secrets, input boundaries, crypto, dependencies, infra exposure),
    - an `approval` stage for the **Product Owner** (intent, scope, acceptance),
-   - a final `approval` stage for the **Engineer** as the merge gate.
-   Resolve each role to its agentId.
+   - a final `approval` stage for the **Code Reviewer** as the merge gate (a non-author — Paperclip excludes the issue's executor from every stage).
+   Resolve each role to its agentId. **Never list the issue's executor (the engineer who authored the work) as a participant in any stage** — the runtime excludes the original executor, so such a stage has no eligible participant and the issue stalls (`422 No eligible approval participant`).
 4. **Engineer** sets the issue to `in_review`.
 5. **QA** (when present) reviews and records `approved`/`changes_requested` through the normal issue update route with executed evidence (see *Merge Rules*), preserving the issue-level review audit trail.
 6. **Security Engineer** (when present as a stage) probes the security-relevant change and records a verdict stating what was checked.
-7. **Code Reviewer** and other domain reviewers may add **advisory, non-blocking** PR comments. They do not gate the merge.
+7. Other domain reviewers may add **advisory, non-blocking** PR comments. They do not gate the merge.
 8. **Product Owner** reviews for intent match, scope discipline, and acceptance criteria, and records the `approval` verdict through the normal issue update route, preserving the issue-level approval audit trail.
-9. **Engineer** owns the final `approval` stage (merge gate): once reviewers and the Product Owner have approved, the engineer satisfies the hard gate (CI green, or runs the tests/build and pastes the output), merges the PR into the correct configured base, confirms the merge landed, closes/archives the isolated execution workspace when one exists and close-readiness allows it, and only then records `approved` — which closes the issue to `done`. The merge and workspace cleanup must happen before the issue is `done`.
+9. **Code Reviewer** owns the final `approval` stage (merge gate): once reviewers and the Product Owner have approved, the Code Reviewer satisfies the hard gate (CI green, or runs the tests/build and pastes the output), merges the PR into the correct configured base, confirms the merge landed, closes/archives the isolated execution workspace when one exists and close-readiness allows it, and only then records `approved` — which closes the issue to `done`. The merge and workspace cleanup must happen before the issue is `done`. The merge owner must be a non-author: Paperclip excludes the issue's executor (the engineer) from every stage, so the engineer cannot be the merge gate.
 
 ## Review Roles
 
 - **QA** (`review` stage, when present): the substantive gate. Test coverage, regression risk, and validation — backed by tests that actually ran.
 - **Security Engineer** (`review` stage, only when the change is security-relevant): probes the diff for injection, auth, secrets, crypto, dependency, and exposure issues.
 - **Product Owner** (`approval` stage): intent alignment, scope discipline, acceptance criteria.
-- **Engineer** (`approval` stage, last): the merge gate and hard-gate backstop — see *Merge Rules*.
-- **Code Reviewer / domain reviewers** (advisory): optional, non-blocking comments on correctness, clarity, design, accessibility, UX. They never gate the merge.
+- **Code Reviewer** (`approval` stage, last): the merge gate and hard-gate backstop — a non-author who verifies and lands the PR. See *Merge Rules*.
+- **Domain reviewers** (advisory): optional, non-blocking comments on correctness, clarity, design, accessibility, UX. They never gate the merge.
 
 ## Merge Rules
 
-The hard gate is **executed verification**, enforced on the Engineer's merge-gate stage and independent of which reviewers are present:
+The hard gate is **executed verification**, enforced on the merge-gate stage (the Code Reviewer's) and independent of which reviewers are present:
 
-- **With CI:** CI (lint/test/build) must be **green** before the Engineer merges. This is machine-verified and cannot be skipped.
-- **Without CI:** the Engineer must run the full test suite and build locally and paste the real output into the merge-gate verdict before merging. (When QA is present, QA already produced this evidence; the Engineer confirms it.)
+- **With CI:** CI (lint/test/build) must be **green** before the merge gate merges. This is machine-verified and cannot be skipped.
+- **Without CI:** the merge-gate agent must run the full test suite and build locally and paste the real output into the merge-gate verdict before merging. (When QA is present, QA already produced this evidence; the merge gate confirms it.)
 - A verdict that does not cite executed verification — green CI, or pasted test/build output — is not valid.
 - The Product Owner's `approval` stage must be approved.
 - QA's `review` stage (when present) and the Security Engineer's `review` stage (when added) must be approved.
-- The Code Reviewer and other domain reviewers are advisory — blocking only when they escalate a concern that QA, the Security Engineer, or the Engineer then acts on.
+- Domain reviewers are advisory — blocking only when they escalate a concern that QA, the Security Engineer, or the merge gate then acts on.
 - No force pushes.
 - Merge using `gh pr merge <number> --merge`.
 - Before merge, verify the PR base matches the configured project/worktree base from `heartbeat-context`. Retarget before review/merge if needed.
-- The Engineer is the merge owner — reviewers never merge.
-- The engineer's merge gate must be the **last** `approval` stage. If the Product Owner's approval were last, it would auto-close the issue to `done` and the merge would be skipped, leaving the PR open on GitHub.
+- The Code Reviewer is the merge owner (a non-author); the engineer who wrote the PR cannot merge it.
+- The merge gate must be the **last** `approval` stage and must be a **non-author**. If the Product Owner's approval were last, it would auto-close the issue to `done` and the merge would be skipped, leaving the PR open on GitHub. The merge gate can never be the issue's executor — Paperclip excludes the original executor from every stage (`422 No eligible approval participant is configured for this issue`).
 - If Paperclip created an isolated execution workspace for the issue, read its id from `heartbeat-context`, call close-readiness, and archive it after the PR is merged and the tree is clean. If cleanup is blocked or fails, do not mark the issue `done`; record the exact blocker and leave a concrete cleanup next action. If the issue runs in the shared project workspace, do not invent isolated-worktree cleanup.
 - Do not configure GitHub branch protection to require approving reviews unless the project has distinct non-author GitHub reviewer credentials; all agents using one GitHub account cannot formally approve their own PRs.
 
 ## Dev Cycle Rules
 
 **Requires PR**: code logic, APIs, DB schema, agent configs, infrastructure
-**Direct-to-main OK**: typos, comment-only changes, minor doc fixes (must reference issue)
+**Direct-to-base-ref OK**: typos, comment-only changes, minor doc fixes (must reference issue)

package/templates/modules/pr-review/module.meta.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-review",
-  "description": "Coordinates substantive PR review through the issue's native executionPolicy. The merge gate is executed verification — green CI, or the engineer running the tests/build and pasting the output — not opinion. QA is the substantive reviewer when present; the Security Engineer reviews only security-relevant changes; the Code Reviewer is advisory.",
+  "description": "Coordinates substantive PR review through the issue's native executionPolicy. The merge gate is executed verification — green CI, or running the tests/build and pasting the output — not opinion. QA is the substantive reviewer when present; the Security Engineer reviews only security-relevant changes; the Code Reviewer is the non-author merge gate that verifies and lands the PR (Paperclip excludes the issue's author from every stage, so the engineer cannot merge their own work).",
   "requires": [
     "github-repo"
   ],
@@ -23,9 +23,9 @@
       "reviewGate": {
         "reviewers": ["qa"],
         "approver": "product-owner",
-        "mergeGate": "engineer"
+        "mergeGate": "code-reviewer"
       },
-      "description": "Document and verify the PR workflow via the issue's executionPolicy. The merge gate is executed verification: with CI, builds must be green before merge; without CI, the engineer runs the test suite/build and pastes the output before merging. Stages: a review stage for QA when present, a review stage for the Security Engineer only on security-relevant changes, an approval stage for the Product Owner, and a final approval stage for the Engineer as the merge gate (woken last to merge the PR before recording approval, which closes the issue). The merge gate must be the last stage so the Product Owner's approval does not auto-close the issue with the PR still open. The Code Reviewer and other domain reviewers add advisory, non-blocking comments. Optional branch protection may disable direct pushes, but do not require GitHub-native approving reviews unless the project has distinct non-author GitHub reviewer credentials."
+      "description": "Document and verify the PR workflow via the issue's executionPolicy. The merge gate is executed verification: with CI, builds must be green before merge; without CI, the merge-gate agent runs the test suite/build and pastes the output before merging. Stages: a review stage for QA when present, a review stage for the Security Engineer only on security-relevant changes, an approval stage for the Product Owner, and a final approval stage for the Code Reviewer as the merge gate (a non-author woken last to merge the PR before recording approval, which closes the issue). Never list the issue's executor/author as a participant in any stage — Paperclip excludes the original executor, so a stage whose only participant is the author has no eligible participant and the issue stalls (`422 No eligible approval participant is configured for this issue`); this is why the merge gate is the Code Reviewer (or another non-author), not the engineer. The merge gate must be the last stage so the Product Owner's approval does not auto-close the issue with the PR still open. Other domain reviewers add advisory, non-blocking comments. Optional branch protection may disable direct pushes, but do not require GitHub-native approving reviews unless the project has distinct non-author GitHub reviewer credentials."
     }
   ]
 }

package/templates/presets/fast/preset.meta.json

@@ -1,8 +1,8 @@
 {
   "name": "fast",
-  "description": "Speed-optimized for solo engineer. CEO + one Engineer, commit directly on main, no PR review. Automatic issue generation and assignment.",
+  "description": "Speed-optimized for solo engineer. CEO + one Engineer, commit directly on the default branch, no PR review. Automatic issue generation and assignment.",
   "constraints": [
-    "Not suited for more than one implementing engineer \u2014 lacks review process and parallel commits to main will cause conflicts."
+    "Not suited for more than one implementing engineer \u2014 lacks review process and parallel commits to the default branch will cause conflicts."
   ],
   "modules": [
     "github-repo",

package/templates/presets/repo-maintenance/preset.meta.json

@@ -67,7 +67,7 @@
     },
     {
       "title": "Configure branch protection and PR workflow",
-      "description": "Set up branch protection on main, require PR reviews, configure review conventions. Document in docs/pr-conventions.md.",
+      "description": "Set up branch protection on the default branch, require PR reviews, configure review conventions. Document in docs/pr-conventions.md.",
       "priority": "high",
       "assignTo": "engineer"
     },

package/templates/roles/engineer/SOUL.md

@@ -15,6 +15,6 @@ You are the Engineer.
 
 - Be precise. Use technical terms correctly.
 - Lead with what you did, then why, then how.
-- Keep status updates short. "Done. Merged to main. CI green." is a perfect update.
+- Keep status updates short. "Done. Merged to the base branch. CI green." is a perfect update.
 - Flag risks early and clearly. "This will break X if Y" is better than discovering it later.
 - No fluff. Skip "I think we should consider possibly..." -- just state the recommendation.