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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlein/paperclip-plugin-company-wizard",
-  "version": "0.4.7",
+  "version": "0.4.10",
   "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/modules/architecture-plan/agents/ceo/skills/architecture-plan.bar.md

@@ -0,0 +1,17 @@
+## Architecture Plan — Done Bar (CEO Fallback)
+
+**Done:**
+- `docs/ARCHITECTURE.md` exists with at least: a brief system overview (what the system does, its main components), the primary data flows, and a clear note that this is a CEO-generated placeholder pending engineer review.
+- A follow-up issue exists, assigned to an engineer or the architecture-plan capability, to complete the full architecture document.
+
+**Not done:**
+- No `docs/ARCHITECTURE.md` exists at all.
+- The document exists but contains no actionable overview (placeholder text only).
+- No follow-up issue was created for the engineer to complete the work.
+
+**Not required from the CEO fallback:**
+- Full API boundary diagrams
+- ADR-style decision log
+- Deployment topology
+- Data model details
+(These are requirements for the engineer primary — not for the CEO safety-net run.)

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

@@ -4,6 +4,8 @@ When the architecture plan is being created, contribute the UI/frontend perspect
 
 ## UI Architecture Contributions
 
+1. Check that `docs/ARCHITECTURE.md` exists. If it does not exist yet, the engineer's architecture-plan task has not completed — leave an issue comment ("Waiting for engineer to complete docs/ARCHITECTURE.md before adding UI layer") and do not close this issue yet. Check back on your next heartbeat.
+
 If an Engineer is defining the architecture, coordinate with them on:
 - **Frontend component structure**: Page layout, shared components, routing
 - **Design token integration**: How the design system connects to the codebase

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

@@ -5,16 +5,17 @@ You own the visual design system. Establish the foundational patterns that ensur
 ## Design System Process
 
 1. Review the company goal, brand context, and target audience
-2. Define and document in `docs/DESIGN-SYSTEM.md`:
+2. If `docs/BRAND-IDENTITY.md` exists, use it as the authoritative source for color palette, typography, and brand voice. Do not invent a palette that contradicts established brand identity.
+3. Define and document in `docs/DESIGN-SYSTEM.md`:
    - **Color palette**: Primary, secondary, accent, semantic (success, error, warning), neutrals
    - **Typography**: Font families, scale (heading/body/caption sizes), weights, line heights
    - **Spacing**: Base unit and scale (4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px)
    - **Component patterns**: Buttons, inputs, cards, modals, navigation — describe states and variants
    - **Brand guidelines**: Logo usage, tone of visual language, iconography style
    - **Responsive breakpoints**: Mobile, tablet, desktop sizing approach
-3. Create implementation issues for the engineer:
+4. Create implementation issues for the engineer:
    - `POST /api/companies/{companyId}/issues` for CSS/design token setup, component library scaffolding. Include the active `projectId` (and `goalId` / `parentId` when applicable). For top-level issues (no `parentId`), also include `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so each gets its own worktree; subissues set `parentId` and omit it.
-4. Assign or hand off implementation issues to the Engineer with a concrete next action; do not rely on generic @-mentions.
+5. Assign or hand off implementation issues to the Engineer with a concrete next action; do not rely on generic @-mentions.
 
 ## Rules
 

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

@@ -0,0 +1,25 @@
+# Skill: Design System (Engineer Primary)
+
+You are establishing the project's design system foundations when no UI Designer is available. Your output should be practical and hand-off-ready — define the minimum tokens and patterns needed for consistent development, and document them so a UI Designer can refine them later.
+
+## Steps
+
+1. Read `docs/TECH-STACK.md` if it exists to understand the frontend framework and styling approach.
+2. Read `docs/BRAND-IDENTITY.md` if it exists for color palette, typography, and brand direction.
+3. If `docs/DESIGN-SYSTEM.md` does not exist, create it using `docs/design-system-template.md` as a starting point.
+4. Define the minimum viable token set:
+   - **Colors**: primary, secondary, background, surface, text, error/warning/success. Use the brand palette if available, otherwise choose accessible defaults (WCAG AA contrast ratio ≥ 4.5:1 for text).
+   - **Typography**: 2–3 font sizes (body, heading, small), font family (system stack if no brand font specified), line heights.
+   - **Spacing**: a 4px base grid — common values: 4, 8, 12, 16, 24, 32, 48, 64px.
+5. Define 3–5 core component patterns (button, input, card, navigation item) with their states (default, hover, active, disabled, error). Document as usage rules, not full component code.
+6. Write token definitions as CSS custom properties or the equivalent for the project's framework.
+7. Mark the document as **provisional** — created by engineer as primary; a UI Designer should review and extend.
+8. Create a follow-up issue: "Review and extend design system" assigned to the UI Designer if one is ever added to the team.
+9. Mark this issue done.
+
+## Rules
+
+- Keep it practical over perfect. Consistent tokens are more valuable than a comprehensive design system.
+- Do not create visual assets (icons, illustrations) — document where placeholders should go.
+- Reference `docs/ARCHITECTURE.md` for the component hierarchy if it exists.
+- If `docs/DESIGN-SYSTEM.md` already exists (a UI Designer ran first), review it for engineering feasibility and add implementation notes — do not overwrite their work.

package/templates/modules/brand-identity/agents/ceo/skills/brand-identity.fallback.md

@@ -9,11 +9,11 @@ The UI Designer and CMO both own brand identity above you. You are the last-reso
    - Choose a neutral color palette (1 primary, 1 accent, 1 neutral)
    - Pick a safe, widely available font pairing (e.g., Inter + system serif)
    - Document in `docs/BRAND-IDENTITY.md` and mark all choices as **provisional**
-   - Create an issue for the designer or CMO to review and expand the brand guidelines
-2. If a designer or CMO is active, skip this entirely.
+   - Create an issue for the ui-designer or CMO to review and expand the brand guidelines
+2. If a ui-designer or CMO is active, skip this entirely.
 
 ## Rules
 
 - This is a safety net. Choose sensible defaults, not optimal solutions.
-- Mark everything as provisional — the designer owns the final brand.
-- Let the designer or CMO refine and expand the actual brand identity.
+- Mark everything as provisional — the ui-designer owns the final brand.
+- Let the ui-designer or CMO refine and expand the actual brand identity.

package/templates/modules/brand-identity/skills/brand-identity.md

@@ -15,7 +15,7 @@ You own the company's visual identity and brand guidelines. Define a cohesive br
    - **Iconography**: Style, stroke weight, grid alignment
    - **Tone of voice**: Communication style, vocabulary, personality
 3. Document everything in `docs/BRAND-IDENTITY.md`:
-   - Use the brand-identity-template as a starting point
+   - Use `docs/brand-identity-template.md` as a starting point
    - Fill in all sections with concrete values and rationale
    - Include visual examples or references where possible
 4. Create initial design tokens if a tech stack exists:

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

@@ -7,7 +7,7 @@ The DevOps engineer primarily owns CI/CD pipelines. You are the fallback — ste
 1. If no CI workflow exists and DevOps hasn't started:
    - 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`
+   - Document the setup in `docs/CI-CD.md` and mark the setup as **provisional** — a devops agent should review and complete the production configuration.
    - Mark the pipeline as **provisional** — it needs DevOps review for CD, caching optimization, and security hardening
 2. If DevOps is active, skip this entirely.
 
@@ -16,3 +16,4 @@ The DevOps engineer primarily owns CI/CD pipelines. You are the fallback — ste
 - This is a safety net. Set up the basics — lint, test, build.
 - Skip CD (deployment) — that requires infrastructure knowledge best left to DevOps.
 - Let DevOps own pipeline optimization, deployment, and ongoing maintenance.
+- Reference `docs/CI-CD.md` for all configuration details so the devops agent can pick up where you left off.

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

@@ -13,8 +13,19 @@ You manage continuous integration and deployment pipelines. Follow the conventio
    - 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
-5. Document the full pipeline in `docs/CI-CD.md`
+4. Pin every third-party action to a full commit SHA (`uses: actions/checkout@<sha>`, not `@v4`). SHA pinning prevents supply-chain attacks from a compromised action version tag. Record the pinned SHAs in `docs/CI-CD.md` → *Pinned Action SHAs*.
+5. Document the rollback procedure in `docs/CI-CD.md` → *Rollback*: how to revert a failed deploy (e.g., `git revert` + redeploy, or infra rollback command), how to verify the rollback succeeded, and the recovery SLA. A pipeline with no documented rollback path is not done.
+6. Add status badges to the project README
+7. Document the full pipeline in `docs/CI-CD.md`
+
+## Ongoing Health Checks
+
+When assigned a "CI pipeline health check" routine-run issue:
+
+1. Review the last 7 days of pipeline runs. Check: average duration trend (flag if >20% slower), flake rate per job (flag jobs failing >5% of runs), failure rate on the default branch.
+2. If the default branch is red (failing), this is P0 — do not mark the routine done until fixed or escalated.
+3. Check for unpinned action versions added since last check; pin them.
+4. Leave a summary comment on the issue (run counts, any flaky/slow jobs, any fixes applied), then mark the routine issue done.
 
 ## Rules
 

package/templates/modules/codebase-onboarding/agents/ceo/skills/codebase-audit.fallback.md

@@ -17,3 +17,13 @@ The Engineer primarily owns codebase auditing and health. You are the fallback
 - Skip deep code analysis — that requires engineering expertise.
 - Don't create cleanup issues — leave that to the Engineer's thorough audit.
 - Let the Engineer own the ongoing health checks and refactoring work.
+
+## Health Check Refresh (follow-up runs)
+
+When `docs/CODEBASE-AUDIT.md` already exists (a prior audit was completed) and you are assigned a follow-up health check:
+
+1. Read the existing `docs/CODEBASE-AUDIT.md`.
+2. Run a quick surface scan: `find . -name "*.js" -o -name "*.ts" | head -30` to sense if new files or directories have appeared since the last audit date.
+3. Note any obviously new areas (new top-level directories, new dependency groups) not present in the existing document.
+4. Add a dated `## Health Check — <date>` section to `docs/CODEBASE-AUDIT.md` listing: files reviewed, new areas identified, and a note that deep analysis was not performed (this is a CEO fallback — escalate to an engineer for full re-audit if significant new areas were found).
+5. Mark the issue done.

package/templates/modules/competitive-intel/agents/product-owner/skills/competitive-tracking.fallback.md

@@ -0,0 +1,19 @@
+# Skill: Competitive Tracking (Product Owner Fallback)
+
+A specialist in competitive intelligence (Customer Success or CMO) is handling primary competitive tracking. Your role is to surface product-roadmap implications from their findings and ensure competitor insights feed into the backlog.
+
+## Steps
+
+1. Read `docs/COMPETITIVE-INTEL.md` if it exists. If it does not, check back after the primary competitive-tracking agent has completed their initial audit.
+2. Review recent competitor changes for product-roadmap implications:
+   - New features from competitors that close a gap with your product → create a backlog issue "Evaluate [feature] parity with [competitor]" with the relevant section from COMPETITIVE-INTEL.md.
+   - Competitor pricing or positioning shifts that affect your value proposition → add a comment to the relevant goal or create an issue for CEO/CMO review.
+3. Update the product backlog with any priority changes driven by competitive pressure (coordinate with CEO before reprioritising existing high-priority items).
+4. Add a `## Product Implications` section to `docs/COMPETITIVE-INTEL.md` if it doesn't already exist, noting your recommendations.
+5. Mark the issue done.
+
+## Rules
+
+- Do not duplicate the competitor research already done by the primary agent — read their output and add product perspective.
+- If COMPETITIVE-INTEL.md does not exist yet, do not create it — wait for the primary agent. Leave an issue comment noting the dependency and mark done if the issue was routine-triggered.
+- Coordinate with CMO or Customer Success before making any public-facing positioning changes.

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

@@ -0,0 +1,11 @@
+## Competitive Tracking — Done Bar
+
+**Done:**
+- `docs/COMPETITIVE-INTEL.md` exists with a profile for each tracked competitor that includes: product positioning, key differentiators, pricing model (if public), and a specific takeaway for your product ("what this means for us").
+- Differentiation opportunities are explicitly named — not just competitor feature lists, but concrete gaps or advantages your product has or could develop.
+- Each competitor profile was updated within the last tracking cycle (not stale from a previous run).
+
+**Not done:**
+- Competitor profiles are feature lists with no positioning takeaway.
+- "Differentiation opportunities" section is absent or contains only generic observations ("we should improve UX").
+- `docs/COMPETITIVE-INTEL.md` was not updated this run (routine ran but no document was touched).

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

@@ -21,5 +21,14 @@
       "assignTo": "capability:dependency-audit",
       "description": "Audit all project dependencies for outdated versions, known vulnerabilities, and deprecated packages. Document findings and create a prioritized upgrade plan."
     }
+  ],
+  "routines": [
+    {
+      "name": "Dependency audit",
+      "description": "Scan for new vulnerabilities and outdated packages, apply safe patch updates.",
+      "assignTo": "capability:dependency-audit",
+      "schedule": "0 2 * * 1",
+      "concurrencyPolicy": "forbid"
+    }
   ]
 }

package/templates/modules/dependency-management/skills/dependency-audit.md

@@ -27,12 +27,15 @@ You are responsible for keeping the project's dependencies healthy, secure, and
 6. **Execute safe upgrades** — Apply patch and minor updates directly when tests pass.
 7. **Create issues** for major version upgrades or migrations that require dedicated work.
 
-## Ongoing
+## Ongoing Audits (Routine-Triggered)
 
-On each heartbeat when `docs/DEPENDENCY-AUDIT.md` exists:
-1. Run vulnerability scan — if new CVEs appear, create issues immediately.
-2. Check for newly outdated dependencies — update the audit doc.
-3. Apply safe patch updates and verify tests pass.
+When assigned a "Dependency audit" routine-run issue:
+
+1. Run the vulnerability scan: `npm audit --json` (or equivalent for the project's package manager). Flag any new Critical or High CVEs not present in the last audit.
+2. Check for newly outdated dependencies: compare current versions against the latest. Flag anything more than one major version behind.
+3. Apply safe patch updates (semver patch-only, no breaking changes): update, run the test suite, commit if green.
+4. Update `docs/DEPENDENCY-AUDIT.md` with the new scan date, any new findings, and any updates applied.
+5. Mark the routine issue done. If Critical CVEs were found that cannot be patched, create a separate high-priority issue for each and escalate to CEO.
 
 ## Rules
 

package/templates/modules/documentation/skills/project-docs.bar.md

@@ -0,0 +1,13 @@
+## Project Documentation — Done Bar
+
+**Done:**
+- All documentation targets specified in the issue have been created or updated.
+- Setup instructions have been verified: every command listed in README.md or setup guides has been run at least once and produces the expected result.
+- API documentation matches the current implementation — no documented endpoints or parameters that no longer exist, no undocumented endpoints that do.
+- No content is duplicated across files — each fact appears in exactly one place; other files reference it rather than copying.
+- Internal links (cross-references between docs) are valid — no broken anchors or references to non-existent files.
+
+**Not done:**
+- Setup instructions are untested ("this should work" documentation).
+- API docs were not updated after a breaking change.
+- A section is marked "TODO" or "coming soon" without a follow-up issue.

package/templates/modules/game-design/skills/game-design.bar.md

@@ -0,0 +1,13 @@
+## Game Design — Done Bar
+
+**Done:**
+- `docs/GDD.md` (Game Design Document) exists and covers all required sections: Overview, Core Loop, Game Mechanics, Progression System, Technical Constraints, and Art Direction.
+- Tuning parameters are externalized: every balance-critical value (player speed, damage, cooldown, score multipliers) is defined as a named parameter with its default value and valid range documented in the GDD (format: `parameter_name: default (range: min–max)`). No magic numbers hardcoded in engine scripts without a GDD reference.
+- A playtest loop is defined: the GDD specifies at minimum one measurable success criterion per core loop iteration (e.g., "average session length > 8 minutes", "level 1 completion rate > 70%").
+- Art and audio direction are present: the GDD includes a visual style reference (mood board description or reference images) and an audio/music direction note.
+
+**Not done:**
+- Tuning values are hardcoded in source files with no GDD parameter reference.
+- The core game loop has no session-level layer (the player has no reason to return after one play session).
+- Art or audio direction is absent ("TBD" does not count).
+- The GDD exists but is a skeleton with no actual design decisions filled in.

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

@@ -17,11 +17,12 @@ Use this flow when the **pr-review module is not active**. You open a PR and mer
 7. Run available checks (lint, typecheck, tests)
 8. Commit using Conventional Commits: `<type>: <description>`
 9. Verify the current branch one more time, then push: `git push -u origin <branch-name>`. The branch name in the push command must match `git branch --show-current`. Never push the base ref as a feature branch — if `git branch --show-current` returns the base ref name, stop and create a feature branch first.
-10. Open a pull request against the base ref: `gh pr create --base <github-base-branch> --head <branch-name> --title "<type>: <description>" --body-file <file>`. Write the PR body (summary, what changed, how to verify) to a temp file first — never inline `--body "..."`. Register the PR as a Paperclip work product (see *Register the PR as a Work Product* below). Verify the PR base matches the configured base ref before merging.
-11. Merge the PR yourself: `gh pr merge <PR-number> --merge`. After opening the PR, merge it yourself promptly — do not wait for a reviewer if none is present. Confirm the PR is closed and the base branch updated before continuing.
-12. Clean up the feature branch: `git push origin --delete <branch-name>` (remote) and `git branch -d <branch-name>` (local). Update the Paperclip work product to `"status": "merged"` via `PATCH /api/work-products/{workProductId}`.
-13. If the issue uses an isolated execution workspace (worktree), archive it from your `heartbeat-context` after the merge is pushed.
-14. If CI fails on the base branch after the merge, fix immediately.
+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. Also check CI: `gh pr checks <PR-number>`. If CI is failing, run the **base-branch-red detection** in `docs/git-workflow.md` → *Base-branch-red deadlock* before merging — a red base poisons every PR and a feature PR on a red base must not merge. Follow the baseline-emergency protocol there (fix main first, then drain the queue).
+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. **Baseline-restore exception (Self-Merge mode):** if this PR is the `fix(ci): restore base CI` PR opened under a declared baseline emergency, its CI will still be red from the inherited base failure — you may merge it via `gh pr merge <PR-number> --merge` despite red CI, provided you ran the exact failing checks locally and pasted the passing output into the issue, and the remaining failing checks are exactly the inherited baseline failures. See `docs/git-workflow.md` → *Narrow exception*. This exception never applies to a feature PR.
+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, run the baseline-emergency protocol in `docs/git-workflow.md` → *Base-branch-red deadlock* (detect base-red, fix main first with a `fix(ci): restore base CI` PR, fast-track it through merge under the narrow exception, re-verify the base is green, then rebase and drain the feature-PR queue). A red base blocks everyone — do not leave it red and do not pile new feature PRs onto it.
 
 ## Branch Protection Setup
 
@@ -80,11 +81,26 @@ Notes:
 - 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.
 - 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.
+- **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.
+- **Do not open new feature PRs on a red base.** When the base branch's CI is red, every PR inherits the failure at baseline setup and the queue deadlocks under "never merge without green CI". Detect base-red per `docs/git-workflow.md` → *Base-branch-red deadlock* and run the baseline-emergency protocol (fix main first, fast-track the baseline-restore PR, then drain the queue) before opening or merging feature PRs.
+
+## 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

@@ -94,7 +94,7 @@ Use this flow when the **pr-review module is not active** (no Code Reviewer role
 6. Run tests/linting locally if available
 7. Commit with conventional commit message
 8. **Verify the current branch one more time**, then push: `git push -u origin <branch-name>`. The branch name in the push command must match `git branch --show-current`. Never push the base ref as a feature branch — if `git branch --show-current` returns the base ref name, stop and create a feature branch first.
-9. Open a pull request against the base ref: write the PR body to a temp file, then `gh pr create --base <github-base-branch> --head <branch-name> --title "<type>: <description>" --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal (see *Posting PR Bodies & Comments* in `docs/pr-conventions.md`). Verify the PR base matches the configured base ref before merging.
+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.
@@ -145,6 +145,57 @@ For a brand-new local repository there is no remote yet, so initialize on `main`
 - **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.
+
+### Base-branch-red deadlock
+
+A base branch whose own CI is red poisons every PR opened on it: each PR inherits the red baseline and fails CI at setup (often in 1-3 seconds), before the PR's diff is even exercised. "Never merge without green CI" then deadlocks the whole queue — no single feature PR can make CI green, because the failure is pre-existing on the base, not in the diff.
+
+**Detect base-red before treating a PR failure as the PR's fault.** When a PR's CI fails:
+
+1. `gh pr checks <N>` — list the PR's check runs and their conclusions.
+2. Get the base commit SHA: `gh pr view <N> --json baseRefOid --jq .baseRefOid`.
+3. Fetch the base commit's own checks: `gh api repos/{owner}/{repo}/commits/<base-sha>/check-runs --jq '.check_runs[] | {name, conclusion}'` (and `/commits/<base-sha>/statuses` for legacy status contexts).
+4. Compare. A check that is failing on the base commit itself is an **inherited baseline failure** — not introduced by the PR. The PR's *introduced* failures are the set difference: PR failing checks minus base failing checks.
+
+If the base is red, classify the situation **BASE-BRANCH-RED** and run the baseline-emergency protocol below instead of trying to land feature PRs.
+
+### Baseline-emergency protocol
+
+When the base branch's CI is red:
+
+1. **Pause new feature PRs.** Do not open new feature PRs on a red base — they inherit the failure and pile up. In-flight branches can finish, but leave them unmerged with an issue comment tagged `waiting-on-baseline` until the base is green.
+2. **Claim and fix main first.** The first agent to detect BASE-BRANCH-RED claims the restore by commenting on the triage issue (or creating one) so concurrent detectors do not open duplicate restore PRs. Create a single baseline-restore PR from the base ref that fixes the base failure (CI config, the failing code path, or the secret/scan config). Title it `fix(ci): restore base CI` (or `fix: restore base — <cause>`). Scope the diff to the failure fix only — no feature work in this PR.
+3. **Fast-track the baseline-restore PR.** Its own CI will still show the inherited base failure (the base is red), so the normal "green CI" gate cannot pass. The merge owner (the Code Reviewer in PR-Gate mode, or the engineer in Self-Merge mode) merges it under the narrow exception below.
+4. **Re-verify the base.** After the baseline-restore PR merges, re-run CI on the base: `gh api repos/{owner}/{repo}/commits/<new-base-sha>/check-runs`. If still red, repeat from step 2. Once the base is green:
+5. **Drain the queue.** Rebase each queued feature PR onto the now-green base (`git rebase origin/<base-branch>`, resolve, `git push --force-with-lease`), re-run checks, and merge in order. The inherited baseline failures are gone, so feature PR CI now reflects only their own diffs.
+
+**If the failing check cannot be reproduced locally** (env-specific secrets, runner-only state, external service unavailable), the narrow merge exception cannot be satisfied AND the base cannot be made green by an agent. Escalate to the board/human to fix CI directly on the base — do not pile feature PRs onto the red base while waiting.
+
+### Narrow exception: merging the baseline-restore PR on a red base
+
+The baseline-restore PR — and only that PR — may be merged when its CI is still red, provided ALL of the following hold:
+
+- **Scoped diff:** the PR diff is limited to the base failure fix (CI config, the failing code, or the secret/scan config). It is not a feature PR wearing a `fix(ci)` label.
+- **Executed verification reduces the failure set:** run the exact failing check commands locally — the same commands the failing CI check runs, mapped by check name (e.g. the `Secret Scan` check → the repo's scan command; the `Build` check → `npm run build`). Paste the real output showing the previously-failing checks now pass locally. The remaining failing checks on the PR must be exactly the inherited baseline failures (same set as the base commit), and the PR diff must not touch them. If a failing check cannot be run locally, this exception does not apply — escalate to the board/human.
+- **Document the exception in the merge verdict:** cite the base-sha check set, the local verification output, and that the diff is scoped to the fix. A merge under this exception still requires cited executed verification — it replaces CI-green with local-executed-verification plus diff-scope proof; it does not waive the verification gate.
+
+This exception never applies to feature PRs. A feature PR on a red base waits for the base to be restored; it does not merge under the exception.

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/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

@@ -12,17 +12,32 @@ Paperclip's runtime **excludes the issue's original executor (the author) from e
    - 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.
+   - **Base-branch-red:** when the base branch's own CI is red, a feature PR's CI is red from the inherited baseline — not from the PR's diff. Detect base-red per `docs/git-workflow.md` → *Base-branch-red deadlock* (compare the PR's failing checks to the base commit's own checks). Do not merge a feature PR on a red base — record `changes_requested` citing `BASE-BRANCH-RED` and route the issue back with "waiting-on-baseline". The single baseline-restore PR (`fix(ci): restore base CI`) may merge under the narrow exception in `docs/git-workflow.md` → *Narrow exception: merging the baseline-restore PR on a red base*: scoped diff + local executed verification that the fix reduces the failure set + cited base-sha check set. The exception replaces CI-green with local-executed-verification plus diff-scope proof; it does not waive the verification gate and never applies to feature PRs.
 2. **All prior stages approved:** QA's `review` (when present), the Security Engineer's `review` (when added), and the Product Owner's `approval` are all recorded `approved`.
 3. **Correctness pass:** read the diff. Does it do what the PR claims? Are edge cases handled? Is it the simplest, clearest solution? Watch for dead code, exposed secrets, and missing validation at boundaries (defer deep security review to the Security Engineer when the change is security-relevant).
 4. **Base ref:** the PR targets the configured project/worktree base from `heartbeat-context` (`repoRef` / `defaultRef` / `workspaceStrategy.baseRef`). Retarget before merging if it points at the wrong branch.
 
 ## 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
 
@@ -36,6 +51,6 @@ Post verdicts as GitHub PR comments via a Markdown file (`gh pr comment <number>
 
 - 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.
+- Never merge without green CI or pasted test/build output — except the baseline-restore PR under the Base-Branch-Red Protocol, which may merge with cited local-executed verification that the fix reduces the base failure set (remaining failing checks exactly the inherited baseline set) and a scoped diff. A feature PR on a red base is never merged; record `changes_requested` citing `BASE-BRANCH-RED` and route back with "waiting-on-baseline".
 - 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

@@ -12,7 +12,7 @@ When this skill is active, you work in feature branches and open PRs instead of
 4. **Verify you are on the feature branch** before making changes: `git branch --show-current` must print your branch name, not the base ref. If it prints the base ref name, you forgot step 3 — create the branch now.
 5. Make your changes, commit with Conventional Commits format
 6. **Verify the current branch one more time**, then push: `git push -u origin <branch-name>`. The branch name in the push command must match `git branch --show-current`. Never push the base ref as a feature branch — if `git branch --show-current` returns the base ref name, stop and create a feature branch first.
-7. Open PR against the same resolved base: derive the GitHub base branch from the configured ref (for example, strip the remote prefix only when the ref is remote-tracking), write the body (PR Body Template in `docs/pr-conventions.md`) to a file, then `gh pr create --base <github-base-branch> --head <branch-name> --title "<type>: <description>" --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal and the PR renders as `text\ntext` (see *Posting PR Bodies & Comments*).
+7. Open PR against the same resolved base: `gh pr create --base <github-base-branch> --head <branch-name> --title "<type>: <description>" --body-file <file>`. `<github-base-branch>` is the **plain branch name** — strip any `origin/` prefix from the configured base ref (e.g., configured `origin/main` → `--base main`; configured `main` → `--base main`). GitHub does not recognise remote-tracking names. Write the PR body (PR Body Template in `docs/pr-conventions.md`) to a file first — never inline `--body "..."` (double-quoted shell string keeps `\n` literal; see *Posting PR Bodies & Comments*).
 8. **Register the PR as a Paperclip work product** so it is visible on the issue and board (creating it on GitHub alone does not surface it in Paperclip):
    ```
    POST /api/issues/{issueId}/work-products
@@ -28,7 +28,7 @@ When this skill is active, you work in feature branches and open PRs instead of
    }
    ```
    `title` and `url` are required (`url` must be the full PR URL). If the issue runs in an isolated worktree, also pass `"executionWorkspaceId"` from `heartbeat-context`. When the PR later merges, update it with `PATCH /api/work-products/{id}` and `"status": "merged"`.
-9. **Only if a code-reviewer is present on the team:** Set the originating issue's `executionPolicy` to gate the merge on review, ending with the Code Reviewer as the merge gate. 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`).
+9. **Only if a code-reviewer is present on the team:** Set the originating issue's `executionPolicy` to gate the merge on review, ending with the Code Reviewer as the merge gate. **Set executionPolicy stages before moving the issue to `in_review` (step 10) — changing stages after the issue has already entered review is not supported.** If no code-reviewer is assigned to this company, skip steps 9–11 entirely and go directly to the self-merge path at step 12. Setting up executionPolicy stages without an eligible non-author merge gate will stall the issue permanently (`422 No eligible approval participant`).
    - One `review` stage with **QA** when a QA agent exists (test adequacy / executed verification).
    - One `review` stage with the **Security Engineer** only when the change is security-relevant (auth, secrets, input boundaries, crypto, dependencies, infra exposure).
    - Domain reviewers (UI Designer, UX Researcher, DevOps) are advisory — they post PR comments and may flag a concern for QA, the Security Engineer, or the merge gate to act on. They are never themselves a review stage.
@@ -39,8 +39,48 @@ When this skill is active, you work in feature branches and open PRs instead of
 10. Move the originating issue to `in_review`.
 11. Wait for the issue to clear its review/approval stages. Each reviewer and the Product Owner records `approved` by PATCHing the issue toward `done`, or `changes_requested` by PATCHing it back to `in_progress`; Paperclip stores the reviewer/approver decision metadata on the issue. Verdicts may be mirrored as PR comments. A `changes_requested` routes the issue back to you — address it, push to the same branch, and that stage re-runs.
 12. **Merging the PR — two paths:**
-    - **Code Reviewer present (PR-Gate mode):** You do not merge your own PR. The Code Reviewer (the non-author merge gate) lands it after every prior stage approves, satisfies the hard verification gate (green CI or pasted test/build output), and records the final `approved` that closes the issue to `done`. Your job is to respond to `changes_requested`: when a stage routes the issue back to you, address the feedback, push to the same branch, and the stage re-runs.
-    - **No code-reviewer present (PR Self-Merge Flow):** You already skipped steps 9–11. Merge the PR yourself: `gh pr merge <N> --merge` once CI is green (or you have pasted test/build output if no CI). All other review roles (qa, product-owner, security-engineer, ui-designer, ux-researcher, devops) may leave advisory comments on the PR, but none block the merge — there are no executionPolicy stages. Update the Paperclip work product to `"status": "merged"` and archive any isolated worktree.
+    - **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 leaving an explicit issue comment explaining the blocker — in PR-Gate mode you cannot record `changes_requested` yourself (you are the excluded author); comment the blocker so the Code Reviewer can record `changes_requested` and route the issue back. 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.
+
+## Base-branch-red deadlock
+
+When a PR's CI fails, do not assume the PR is at fault. Detect base-red per `docs/git-workflow.md` → *Base-branch-red deadlock*: compare the PR's failing checks against the base commit's own checks. If the base is red, the failure is inherited, not introduced by your diff.
+
+- **Do not open new feature PRs on a red base** — they pile up and inherit the failure.
+- Run the baseline-emergency protocol in `docs/git-workflow.md` → *Baseline-emergency protocol*: fix main first with a single `fix(ci): restore base CI` PR, fast-track it through merge under the narrow exception, re-verify the base is green, then rebase and drain the feature-PR queue.
+- A feature PR on a red base waits for the base to be restored. It never merges under the baseline-restore exception.
+
+In **PR-Gate mode** (Code Reviewer present): you are the issue author and Paperclip excludes you from every executionPolicy stage, so you **cannot record `changes_requested`** — only a stage participant (the Code Reviewer) can. If you detect BASE-BRANCH-RED before moving the issue to `in_review` (step 10), do not move it — leave it `in_progress`, comment `BASE-BRANCH-RED` with the baseline-restore PR link, and start the baseline-emergency protocol now. If the issue is already `in_review`, comment `BASE-BRANCH-RED` with "waiting-on-baseline; starting baseline-restore PR now", then immediately claim and create the `fix(ci): restore base CI` PR per the baseline-emergency protocol in `docs/git-workflow.md` — do not wait for the Code Reviewer's `changes_requested` route-back before beginning the fix. The Code Reviewer reads its `code-review.md` and records `changes_requested` to formally route the issue back; the base fix proceeds in parallel. Do not leave the issue silently in `in_review` against a red base.
+
+In the **Self-Merge path** (no Code Reviewer): do not merge your feature PR on a red base; run the baseline-emergency protocol, then rebase and merge once the base is green. If you opened the `fix(ci): restore base CI` PR under a declared baseline emergency, you may merge it despite red CI under the narrow exception in `docs/git-workflow.md` → *Narrow exception* (run the failing checks locally, paste passing output, remaining failures exactly the inherited baseline set).
+
+## Misrouted in_review (null executionPolicy)
+
+If you find an issue in `in_review` with `executionPolicy: null` (or no stage with a non-author participant), it is stuck — there is no reviewer path and no eligible participant, so it can never advance (`422 No eligible approval participant`). Recover it:
+
+1. Move the issue back to `in_progress` (`PATCH /api/issues/{id}` with `status: "in_progress"`).
+2. Take the correct path for the team:
+   - **Code Reviewer present:** set the `executionPolicy` review/approval stages (step 9 above) *before* moving the issue back to `in_review`. Changing stages after the issue re-enters review is not supported.
+   - **No Code Reviewer:** do not set any `executionPolicy` — use the self-merge path (step 12). Merge the PR yourself via `gh pr merge <N> --merge` and mark the issue `done`; do not route it back to `in_review`.
+3. Leave an issue comment naming the misroute (was `in_review` with no policy) and the recovery action taken.
+
+Never move an issue to `in_review` unless an `executionPolicy` with at least one non-author stage is set (PR-Gate mode) or you are on the self-merge path and will merge it yourself this heartbeat (no Code Reviewer). An `in_review` issue with no policy and no self-merge in progress is a permanent stall.
 
 ## Rules