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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlein/paperclip-plugin-company-wizard",
-  "version": "0.4.9",
+  "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/github-repo/agents/engineer/skills/git-workflow.md

@@ -18,11 +18,11 @@ Use this flow when the **pr-review module is not active**. You open a PR and mer
 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.
+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, fix immediately.
+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
 
@@ -89,6 +89,7 @@ Notes:
 - 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.
+- **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
 

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

@@ -164,3 +164,38 @@ If the conflict is too complex to resolve safely (large structural conflict with
 ## 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/pr-review/agents/code-reviewer/skills/code-review.md

@@ -12,6 +12,7 @@ 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.
@@ -50,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

@@ -54,10 +54,34 @@ When `gh pr merge` fails or `gh pr view` reports `mergeable: CONFLICTING` / `mer
 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.
+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
 
 - Never commit directly to the base ref (except typos/comment-only/doc fixes with issue reference).

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

@@ -90,7 +90,7 @@ Review runs through the issue's native `executionPolicy` (stages), not separate
 
 The hard gate is **executed verification**, enforced on the merge-gate stage (the Code Reviewer's) and independent of which reviewers are present:
 
-- **With CI:** CI (lint/test/build) must be **green** before the merge gate merges. This is machine-verified and cannot be skipped.
+- **With CI:** CI (lint/test/build) must be **green** before the merge gate merges. This is machine-verified and cannot be skipped — with one narrow exception: the baseline-restore PR (`fix(ci): restore base CI`) may merge when the base branch's own CI is red and the PR carries cited local-executed verification that its scoped diff reduces the base failure set (remaining failing checks exactly the inherited baseline set). See `docs/git-workflow.md` → *Base-branch-red deadlock* and *Narrow exception*. A feature PR on a red base is never merged; the merge gate records `changes_requested` citing `BASE-BRANCH-RED` and routes back with "waiting-on-baseline".
 - **Without CI:** the merge-gate agent must run the full test suite and build locally and paste the real output into the merge-gate verdict before merging. (When QA is present, QA already produced this evidence; the merge gate confirms it.)
 - A verdict that does not cite executed verification — green CI, or pasted test/build output — is not valid.
 - The Product Owner's `approval` stage must be approved.

package/templates/modules/stall-detection/agents/ceo/skills/stall-detection.md

@@ -11,7 +11,7 @@ Use this only when the current assigned issue/routine is titled like "Stall dete
 1. Checkout the assigned routine-run issue.
 2. Query active issues for the relevant company/project: `todo`, `in_progress`, `in_review`, and blocked work where applicable.
 3. For each candidate, inspect latest comments/activity, execution state, blockers, approval/review state, and assigned agent status.
-4. Skip issues with an active run, recent activity, valid `blockedByIssueIds`, or pending executionPolicy approval/review.
+4. Skip issues with an active run, recent activity, valid `blockedByIssueIds`, or a genuinely pending executionPolicy approval/review (issue `in_review` **with** a non-author stage). An issue `in_review` with `executionPolicy: null` or no non-author stage is NOT pending review — it is a misrouted stall (see *Misrouted in_review* below).
 5. For a likely stall, leave a structured comment on the issue with:
    - issue id/title
    - assigned agent
@@ -22,6 +22,27 @@ Use this only when the current assigned issue/routine is titled like "Stall dete
 7. If an agent is `error`, paused, or repeatedly non-responsive, escalate with an issue comment and assign the manager/CEO as appropriate.
 8. Summarize findings on the routine-run issue and mark it done.
 
+## Misrouted in_review (null executionPolicy)
+
+An issue in `in_review` with `executionPolicy: null` (or no stage with a non-author participant) has no reviewer path and no eligible participant — it can never advance. This is a permanent stall, not a pending review. Detect it during the in_review scan (step 2-5), not after the summary.
+
+1. Flag it in the routine-run summary as `MISROUTED-REVIEW`.
+2. Leave a structured comment on the issue: status `in_review` with no executionPolicy, no eligible reviewer, assigned to the engineer — must recover.
+3. Assign the issue back to the engineer with the next action: move to `in_progress`, then either set `executionPolicy` stages (if a Code Reviewer exists on the team) or self-merge the PR via `gh pr merge <N> --merge` and mark `done` (if no Code Reviewer). An `in_review` issue with no policy and no self-merge in progress is a permanent stall — do not skip it as "pending review".
+
+## PR-queue hygiene
+
+As part of every stall-detection run, scan the repository's open PR queue for pile-ups and red/DIRTY state — the issue queue alone does not surface a growing PR backlog. This scan only applies when the `github-repo` module is active (so `gh` is configured and a repository exists). Discover the repo from the project workspace metadata (`repoUrl` / `repoRef`) or your `heartbeat-context`; for multi-repo companies, scan each project's repo.
+
+1. List open PRs: `gh pr list --repo <owner/repo> --state open --json number,title,mergeStateStatus,headRefName,baseRefName`.
+2. Count PRs in each state: UNSTABLE (mergeable but CI failing), DIRTY/CONFLICTING, CLEAN.
+3. Escalate a triage issue when any threshold is met:
+   - **3 or more** UNSTABLE or DIRTY/CONFLICTING PRs, or
+   - **8 or more** open PRs total.
+4. Before opening the triage issue, run the base-branch-red detection in `docs/git-workflow.md` → *Base-branch-red deadlock* against the base commit (if `docs/git-workflow.md` is present — it ships with `github-repo`, which is active here). If the base is red, the triage issue names `BASE-BRANCH-RED` and instructs the baseline-emergency protocol (fix main first, fast-track the baseline-restore PR, drain the queue) — the pile-up is a symptom of the red base, not individual PR faults.
+5. If the base is green, the triage issue lists each UNSTABLE/DIRTY PR with its owner and the specific next action (rebase for DIRTY, fix the introduced failure for UNSTABLE).
+6. Assign the triage issue to the CEO (or the engineer owning the red base) and summarize on the routine-run issue.
+
 ## Rules
 
 - Do not @-mention as a generic nudge; use assignment, status, blockers, and explicit next-action comments.

package/templates/roles/engineer/HEARTBEAT.md

@@ -35,7 +35,7 @@ Run this checklist on every heartbeat. The Paperclip skill is the source of trut
 - Upload or attach user-inspectable outputs as work products/artifacts/documents; local filesystem paths alone are not enough.
 - Use issue documents for long plans, specs, QA reports, security reviews, or hiring drafts; comments should summarize and link.
 - Handoffs should use assignment/status/executionPolicy and a concrete next action. Do not rely on generic @-mentions.
-- If work awaits review, move the issue to `in_review`. When no executionPolicy is active, reassign to the Product Owner for acceptance review — never leave finished work in `in_review` assigned to yourself. When an executionPolicy is active, follow its review/approval stages.
+- Before moving work to `in_review`, verify a review path exists. If a Code Reviewer is on the team, set the `executionPolicy` stages (at least one non-author stage) **before** moving to `in_review` — an `in_review` issue with `executionPolicy: null` has no eligible participant and stalls forever (`422 No eligible approval participant`). If no Code Reviewer is on the team, do not move to `in_review` at all: open the PR and merge it yourself via `gh pr merge <N> --merge` in the same heartbeat (self-merge path), then mark `done`. If you find an issue already `in_review` with `executionPolicy: null`, it is a misrouted stall — move it back to `in_progress`, then either set `executionPolicy` stages (Code Reviewer present) or self-merge the PR (no Code Reviewer). Never leave finished work in `in_review` assigned to yourself.
 
 ## 6. Exit