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

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

@@ -2,31 +2,77 @@
 
 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>`. `<github-base-branch>` is the **plain branch name** — strip any `origin/` prefix from the configured base ref (e.g., configured `origin/main` → `--base main`). GitHub does not recognise remote-tracking names. Write the PR body 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. Before merging, check that the PR is not conflicting: `gh pr view <PR-number> --json mergeable,mergeStateStatus`. If `mergeable` is `CONFLICTING` or `mergeStateStatus` is `DIRTY`, resolve the conflict before merging — see *Resolving merge conflicts* below.
+12. 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.
+13. 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}`.
+14. If the issue uses an isolated execution workspace (worktree), archive it from your `heartbeat-context` after the merge is pushed.
+15. 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
 
@@ -35,9 +81,25 @@ If the pr-review module is active and you have a Code Reviewer role on the team,
 - Never force push to the base branch.
 - Use the configured base ref. For external repos, branch and compare from the configured remote/ref and push/merge back to the matching remote branch.
 - Treat push authentication as repository setup, not as an issue blocker. If `git push` says credentials are missing or invalid, verify the helper and `GH_TOKEN` binding first.
-- If you encounter merge conflicts, resolve them carefully. When in doubt, escalate to the CEO.
+- If `gh pr merge` fails or `gh pr view` reports `mergeable: CONFLICTING` / `mergeStateStatus: DIRTY`, resolve the conflict before retrying — see *Resolving merge conflicts* below. Never leave a PR in an unresolved conflicting state without either fixing it or leaving an explicit issue comment with the blocker.
 - Reference the issue ID in the commit body (e.g., `Closes YES-5`).
 - 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.
+
+## Resolving merge conflicts
+
+When `gh pr merge` fails or `gh pr view <N> --json mergeable,mergeStateStatus` returns `CONFLICTING` / `DIRTY`:
+
+1. `git fetch origin`
+2. `git checkout <branch-name>`
+3. `git rebase origin/<base-branch>` where `<base-branch>` is the plain branch name — strip any `origin/` prefix from the configured base ref (e.g., configured `origin/main` → `git rebase origin/main`; configured `main` → `git rebase origin/main`). Resolve each conflict marker, then `git rebase --continue`.
+4. Run the full check suite (lint, typecheck, tests) to confirm nothing broke.
+5. `git push --force-with-lease origin <branch-name>` — never `--force`, use `--force-with-lease` to avoid overwriting concurrent pushes.
+6. Verify the conflict is gone: `gh pr view <N> --json mergeable` should return `MERGEABLE`.
+7. Retry the merge: `gh pr merge <N> --merge`.
+
+If the conflict is too complex to resolve safely (e.g., a large structural conflict with another in-flight PR), leave an issue comment describing the exact conflict and escalate to the CEO for prioritization before abandoning the branch.

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`). `<github-base-branch>` is the **plain branch name** — strip any `origin/` prefix from the configured base ref (e.g., configured ref `origin/main` → `--base main`; configured ref `main` → `--base main`). GitHub does not recognise remote-tracking names. 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,27 @@ 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.
+
+## Resolving merge conflicts
+
+When `gh pr merge` fails or `gh pr view <N> --json mergeable,mergeStateStatus` reports `CONFLICTING` / `DIRTY`:
+
+1. `git fetch origin`
+2. `git checkout <branch-name>`
+3. `git rebase origin/<base-branch>` where `<base-branch>` is the plain branch name — strip any `origin/` prefix from the configured base ref first (e.g., configured `origin/main` → `git rebase origin/main`; configured `main` → `git rebase origin/main`). Resolve each conflict marker, then `git rebase --continue`.
+4. Run the full check suite (lint, typecheck, tests) to confirm nothing broke.
+5. `git push --force-with-lease origin <branch-name>` — use `--force-with-lease`, never bare `--force`.
+6. Verify the conflict is resolved: `gh pr view <N> --json mergeable` should now return `MERGEABLE`.
+7. Retry: `gh pr merge <N> --merge`.
+
+Never leave a PR sitting in a conflicting state without either resolving it or leaving an explicit issue comment with the exact blocker. A dirty PR that is never merged or explicitly closed stalls the entire chain indefinitely.
+
+If the conflict is too complex to resolve safely (large structural conflict with another in-flight PR), comment on the issue with the exact conflict description and escalate to the CEO.
+
 ## 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/docs/market-analysis-template.md

@@ -6,6 +6,23 @@
 - **Problem**: _What problem are we solving?_
 - **Market size**: _How big is the opportunity?_
 
+## User Segments
+
+### Primary Users
+- **Segment name**: [name]
+- **Description**: [who they are]
+- **Key needs**: [what they need from the product]
+- **Pain points**: [what frustrates them today]
+
+### Secondary Users
+- **Segment name**: [name]
+- **Description**: [who they are]
+- **Key needs**: [what they need from the product]
+- **Relationship to primary**: [how they interact with the primary user's workflow]
+
+### Edge Cases
+- [User groups or scenarios that the product must handle but that aren't core users]
+
 ## Competitive Landscape
 
 | Competitor | Strengths | Weaknesses | Differentiation |

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/monitoring/agents/engineer/skills/monitoring.fallback.md

@@ -5,7 +5,7 @@ The DevOps engineer primarily owns monitoring and observability. You are the fal
 ## Monitoring (Fallback)
 
 1. If no `docs/MONITORING.md` exists and DevOps hasn't started:
-   - Add basic health check endpoints (liveness probe returning 200)
+   - Add basic health check endpoints (liveness and readiness probes returning 200)
    - Set up structured JSON logging with timestamp, level, and service fields
    - Document the setup in `docs/MONITORING.md`
    - Mark the strategy as **provisional** — it needs DevOps review for alerting, dashboards, and SLOs

package/templates/modules/monitoring/skills/monitoring.md

@@ -9,7 +9,8 @@ You are responsible for setting up observability, alerting, and health checks fo
 3. Configure error tracking — capture unhandled exceptions with context (request ID, user, stack trace).
 4. Set up structured logging — all log output must be machine-parseable JSON with consistent fields.
 5. Define alert thresholds for key metrics (error rate, latency, uptime, resource usage).
-6. Document the full observability strategy in `docs/MONITORING.md`.
+6. Set up a basic operational dashboard (in the monitoring tool configured for this project) showing: request rate, error rate, latency (p50/p99), and the key health indicators defined above. Document the dashboard URL/name in `docs/MONITORING.md`.
+7. Document the full observability strategy in `docs/MONITORING.md`.
 
 ## Rules
 
@@ -18,3 +19,4 @@ You are responsible for setting up observability, alerting, and health checks fo
 - Log structured JSON — never log unstructured strings. Include timestamp, level, service, and correlation ID.
 - Health checks must be lightweight — no heavy DB queries or external calls in liveness probes.
 - Keep dashboards focused — one dashboard per concern (e.g., API latency, error rates, infrastructure).
+- Every alert definition must link to a runbook in `docs/` explaining: what triggered it, what to check first, and how to respond. No alert should fire without a runbook.

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

@@ -18,11 +18,25 @@ Paperclip's runtime **excludes the issue's original executor (the author) from e
 
 ## 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.
+1. Before merging, check whether the PR branch is up to date with the base: `gh pr view <number> --json mergeable,mergeStateStatus`. If `mergeable` is `CONFLICTING` or `mergeStateStatus` is `DIRTY`, **do not attempt to merge** — go to *Merge conflicts* below first.
+2. Merge with `gh pr merge <number> --merge`. No force pushes.
+3. Confirm the merge landed on the correct base.
+4. 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.
+5. **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.
+6. Never record `approved` before the merge has actually succeeded, and never leave the issue `done` with the PR still open.
+
+## Merge conflicts
+
+When `gh pr merge` fails or `gh pr view` reports `mergeable: CONFLICTING` / `mergeStateStatus: DIRTY`:
+
+1. Record `changes_requested` on the issue immediately (do not leave it in `in_review` indefinitely) with a comment: "PR has merge conflicts with the base branch — returning to engineer to rebase."
+2. The issue routes back to the engineer (`returnAssignee`). The engineer must:
+   - `git fetch origin && git checkout <branch-name>`
+   - `git rebase origin/<base-branch>` where `<base-branch>` is the plain branch name (strip any `origin/` prefix from the configured base ref — e.g., configured `origin/main` → `git rebase origin/main`)
+   - Resolve all conflicts, run checks, commit
+   - `git push --force-with-lease origin <branch-name>`
+   - Leave an issue comment confirming the rebase, then move the issue back to `in_review`
+3. The issue re-enters the approval chain and returns to you. Re-run the hard verification gate before merging.
 
 ## When something is wrong
 

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,54 @@ 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: `gh pr create --base <github-base-branch> --head <branch-name> --title "<type>: <description>" --body-file <file>`. `<github-base-branch>` is the **plain branch name** — strip any `origin/` prefix from the configured base ref (e.g., configured `origin/main` → `--base main`; configured `main` → `--base main`). GitHub does not recognise remote-tracking names. Write the PR body (PR Body Template in `docs/pr-conventions.md`) to a file first — never inline `--body "..."` (double-quoted shell string keeps `\n` literal; see *Posting PR Bodies & Comments*).
+8. **Register the PR as a Paperclip work product** so it is visible on the issue and board (creating it on GitHub alone does not surface it in Paperclip):
+   ```
+   POST /api/issues/{issueId}/work-products
+   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. **Set executionPolicy stages before moving the issue to `in_review` (step 10) — changing stages after the issue has already entered review is not supported.** If no code-reviewer is assigned to this company, skip steps 9–11 entirely and go directly to the self-merge path at step 12. Setting up executionPolicy stages without an eligible non-author merge gate will stall the issue permanently (`422 No eligible approval participant`).
    - One `review` stage with **QA** when a QA agent exists (test adequacy / executed verification).
    - One `review` stage with the **Security Engineer** only when the change is security-relevant (auth, secrets, input boundaries, crypto, dependencies, infra exposure).
-   - 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. If `changes_requested` is due to a merge conflict (the Code Reviewer will say so), see *Resolving merge conflicts* below.
+    - **No code-reviewer present (PR Self-Merge Flow):** You already skipped steps 9–11. Before merging, check `gh pr view <N> --json mergeable,mergeStateStatus` — if the PR is `CONFLICTING` or `DIRTY`, resolve the conflict first (see *Resolving merge conflicts* below). Then merge: `gh pr merge <N> --merge` once CI is green (or you have pasted test/build output if no CI). All other review roles (qa, product-owner, security-engineer, ui-designer, ux-researcher, devops) may leave advisory comments on the PR, but none block the merge — there are no executionPolicy stages. Update the Paperclip work product to `"status": "merged"` and archive any isolated worktree.
+
+## Resolving merge conflicts
+
+When `gh pr merge` fails or `gh pr view` reports `mergeable: CONFLICTING` / `mergeStateStatus: DIRTY`:
+
+1. `git fetch origin`
+2. `git checkout <branch-name>`
+3. `git rebase origin/<base-branch>` where `<base-branch>` is the plain branch name — strip any `origin/` prefix from the configured base ref (e.g., configured `origin/main` → `git rebase origin/main`; configured `main` → `git rebase origin/main`). Resolve all conflicts, then `git rebase --continue`.
+4. Run the full check suite (lint, typecheck, tests) to confirm nothing broke.
+5. `git push --force-with-lease origin <branch-name>`
+6. Confirm the PR is no longer conflicting: `gh pr view <N> --json mergeable` should return `MERGEABLE`.
+7. Leave an issue comment noting the rebase, then continue with the merge step.
+
+Never leave a PR with unresolved conflicts without either resolving them or explicitly routing the issue back (`changes_requested`) with a comment explaining the blocker. A dirty PR sitting in `in_review` stalls the entire chain.
+
+If the conflict is too complex to resolve safely (large structural conflict with another in-flight PR), leave an issue comment with the exact conflict description and escalate to the CEO for prioritization.
 
 ## Rules
 
@@ -30,9 +64,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.

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

@@ -14,16 +14,14 @@ You review PRs for usability, user flow integrity, and alignment with user needs
 
 ## 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 user-facing behavior, interactions, or flows, review it for the UX concerns below.
 2. Focus only on UX and usability concerns — leave code logic to Code Reviewer and visuals to UI Designer.
-3. Record your verdict through the normal issue update route for your review stage:
-   - **approved** if usability is 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 flow that traps users in a dead end), flag it explicitly in the comment and name who should act on it — QA, the Security Engineer, or the Code Reviewer merge gate — so a blocking reviewer can incorporate it into their verdict. You do not block the merge yourself.
 
 ## Rules
 
 - Ground feedback in user impact — "users might miss this because..." beats "I don't like this".
 - If `docs/USER-TESTING.md` exists, reference its findings where relevant. If it doesn't exist yet, ground feedback in the PR and existing app patterns instead.
-- Approve changes that don't affect user-facing behavior without comment.
+- Comment only on changes that affect user-facing behavior.
 - If the change introduces a new interaction pattern, flag it for consistency tracking.

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

@@ -68,8 +68,8 @@ Review runs through the issue's native `executionPolicy` (stages), not separate
 3. **Engineer** sets the originating issue's `executionPolicy` stages, in order:
    - 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 **Code Reviewer** as the merge gate (a non-author — Paperclip excludes the issue's executor from every stage).
+   - an `approval` stage for the **Product Owner** when one is on the team (intent, scope, acceptance),
+   - a final `approval` stage for the **Code Reviewer** as the merge gate (a non-author — Paperclip excludes the issue's executor from every stage). When no Code Reviewer is on the team, do not set executionPolicy stages at all — use the PR Self-Merge Flow (the engineer opens the PR and merges via `gh pr merge <N> --merge`); other review roles may leave advisory comments but do not block.
    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.
@@ -82,8 +82,8 @@ Review runs through the issue's native `executionPolicy` (stages), not separate
 
 - **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.
-- **Code Reviewer** (`approval` stage, last): the merge gate and hard-gate backstop — a non-author who verifies and lands the PR. See *Merge Rules*.
+- **Product Owner** (`approval` stage, when present): intent alignment, scope discipline, acceptance criteria.
+- **Code Reviewer** (`approval` stage, last, when present): the merge gate and hard-gate backstop — a non-author who verifies and lands the PR. See *Merge Rules*. When no Code Reviewer is present, the engineer self-merges via `gh pr merge <N> --merge` and no executionPolicy stages are set.
 - **Domain reviewers** (advisory): optional, non-blocking comments on correctness, clarity, design, accessibility, UX. They never gate the merge.
 
 ## Merge Rules

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

@@ -25,7 +25,7 @@
         "approver": "product-owner",
         "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 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."
+      "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 when present, 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 (a 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. When no code-reviewer role is present in the company, use PR-Self-Merge mode instead: the engineer opens the PR normally but skips executionPolicy stages entirely and merges via `gh pr merge <N> --merge` themselves. Other review roles (qa, product-owner, security-engineer, ui-designer, ux-researcher, devops) may leave advisory comments on the PR but do not block the merge. Never set up executionPolicy stages when there is no eligible non-author merge gate — the issue will stall with `422 No eligible approval participant`."
     }
   ]
 }

package/templates/modules/release-management/agents/ceo/skills/release-process.fallback.md

@@ -0,0 +1,20 @@
+# Skill: Release Process (CEO Fallback)
+
+You are acting as a fallback for this capability because neither a devops agent nor an engineer is currently on the team. **Do not execute releases** — your role is to ensure release conventions are documented and a proper release owner is hired.
+
+## What you should do
+
+1. Check if `docs/RELEASE-PROCESS.md` exists. If not, create it with:
+   - Versioning convention (SemVer: `MAJOR.MINOR.PATCH`)
+   - Branch and tagging strategy (e.g., tag `vX.Y.Z` on the default branch after each release)
+   - Changelog format: Conventional Commits → CHANGELOG.md grouping
+   - Note: "This document was created by the CEO as a placeholder. A devops or engineer agent should implement and automate the release pipeline."
+2. Check if the project has a CHANGELOG.md. If not, create one with a `## Unreleased` section listing the current commits since the last tag (use `git log --oneline`).
+3. Create a follow-up issue: "Implement automated release pipeline" assigned to `capability:ci-cd` or directly to an engineer, linking to `docs/RELEASE-PROCESS.md`.
+4. Mark this issue done. **Do not push tags, create GitHub releases, or modify version files** — those actions require a devops or engineer agent.
+
+## Rules
+
+- Never execute `git push --tags`, `gh release create`, or version-file bumps without a devops or engineer agent present.
+- Your output is documentation and a follow-up issue — not an executed release.
+- If an urgent release is needed, escalate to the board.

package/templates/modules/release-management/module.meta.json

@@ -21,5 +21,14 @@
       "assignTo": "capability:release-process",
       "description": "Review the current release workflow. If one exists, document it in docs/RELEASE-PROCESS.md. If not, establish a semver + changelog workflow with tagging conventions."
     }
+  ],
+  "routines": [
+    {
+      "name": "Release readiness check",
+      "description": "Check for unreleased changes and cut a release if warranted.",
+      "assignTo": "capability:release-process",
+      "schedule": "0 9 * * 1",
+      "concurrencyPolicy": "forbid"
+    }
   ]
 }