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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlein/paperclip-plugin-company-wizard",
-  "version": "0.4.10",
+  "version": "0.4.11",
   "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/pr-review/docs/pr-conventions.md

@@ -70,7 +70,7 @@ Review runs through the issue's native `executionPolicy` (stages), not separate
    - 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** 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`).
+   Resolve each role to its agentId. **Never list the issue's assignee/executor (whoever did the work — engineer, QA, or any role) as a participant in any stage** — the runtime excludes the original executor from every stage, so such a stage has no eligible participant and the issue stalls (`422 No eligible approval participant`). This applies to **every** stage, but is fatal in the **first** stage: a first stage listing only the assignee cannot be passed, so the issue stalls at stage 1 (`422 Only the active reviewer or approver can advance the current execution stage`) even when later stages have non-author participants. If the policy ended up with the assignee as the first/only participant of a stage, recover with `PATCH /api/issues/{id}` `{"executionPolicy":null}` (returns the issue to `in_progress`), then re-set stages with a non-author first stage — or, with no Code Reviewer, self-merge via `gh pr merge <N> --merge`. Non-engineer roles (e.g. QA) must not author implementation work and then self-review it; implementation work belongs to the engineer.
 4. **Engineer** sets the issue to `in_review`.
 5. **QA** (when present) reviews and records `approved`/`changes_requested` through the normal issue update route with executed evidence (see *Merge Rules*), preserving the issue-level review audit trail.
 6. **Security Engineer** (when present as a stage) probes the security-relevant change and records a verdict stating what was checked.

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 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).
+4. Skip issues with an active run, recent activity, valid `blockedByIssueIds`, or a genuinely pending executionPolicy approval/review — meaning `in_review` **whose current (first unapproved) stage has at least one non-author participant**. An issue `in_review` with `executionPolicy: null`, with no non-author stage at all, OR whose first/current stage lists only the assignee (author) as a participant is NOT pending review — it is a stall (see *Misrouted in_review* and *Author-only first stage* below).
 5. For a likely stall, leave a structured comment on the issue with:
    - issue id/title
    - assigned agent
@@ -30,6 +30,14 @@ An issue in `in_review` with `executionPolicy: null` (or no stage with a non-aut
 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".
 
+## Author-only first stage
+
+An issue `in_review` whose **first (current) executionPolicy stage lists only the issue's assignee as a participant** stalls immediately: Paperclip excludes the executor from every stage, so that stage has no eligible participant and the issue can never advance past stage 1 (`422 Only the active reviewer or approver can advance the current execution stage`). This is a stall **even when later stages have non-author participants** — the first stage must pass first, and it cannot. Common cause: a non-engineer (e.g. QA) was assigned implementation work, did it, moved the issue to `in_review`, and the policy's first review stage was set to that same agent (self-review). Detect it during the in_review scan (step 2-5): `GET /api/issues/{id}` for the full `executionPolicy` (the list endpoint omits it), inspect `stages[0].participants`, and compare against `assigneeAgentId`.
+
+1. Flag it in the routine-run summary as `AUTHOR-ONLY-STAGE`.
+2. Leave a structured comment on the issue: `in_review` whose first executionPolicy stage lists only the assignee `<agent>` as participant — author-only stage, no eligible participant, permanent stall (`422`).
+3. Recover by nulling the policy: `PATCH /api/issues/{id}` with `{"executionPolicy":null}` returns the issue to `in_progress` (do not try `{"status":"in_progress"}` alone — a active policy rejects that with `422 Only the active reviewer or approver can advance`). Then reassign to the correct owner (the engineer for implementation work) with the next action: either re-set `executionPolicy` stages with a **non-author first stage** (Code Reviewer present) or self-merge the PR via `gh pr merge <N> --merge` (no Code Reviewer). Never re-add the assignee as a stage participant.
+
 ## 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.

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.
-- 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.
+- 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`). The **first** stage must be a non-author stage: never list yourself (the issue's assignee/executor — whoever did the work) as a participant in any stage. The runtime excludes the original executor from every stage, so a first stage listing only you has no eligible participant and the issue stalls at stage 1 (`422 Only the active reviewer or approver can advance the current execution stage`) — even if later stages have non-author participants. After moving to `in_review`, `GET /api/issues/{id}` (the list endpoint omits `executionPolicy`) and confirm `stages[0].participants` is not just you; if it is, `PATCH /api/issues/{id}` `{"executionPolicy":null}` to return to `in_progress`, then re-set stages with a non-author first stage. 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` or an author-only first stage, it is a stall — recover by nulling the policy (`PATCH {"executionPolicy":null}` → `in_progress`), then either set `executionPolicy` stages with a non-author first stage (Code Reviewer present) or self-merge the PR (no Code Reviewer). Never leave finished work in `in_review` assigned to yourself.
 
 ## 6. Exit
 

package/templates/roles/qa/HEARTBEAT.md

@@ -35,8 +35,9 @@ 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 verification passes:** mark the issue `done` with a comment citing the test evidence — or, if the issue is governed by an executionPolicy with a stage after QA, record `approved` to pass it to the next stage.
+- **If verification passes:** mark the issue `done` with a comment citing the test evidence — or, if the issue is governed by an executionPolicy with a stage after QA, record `approved` pass to the next stage.
 - **If verification fails:** reassign to the relevant engineer with exact reproduction steps, set status back to `in_progress`. Do not mark `done` on a failing issue.
+- **You are a reviewer, not an author.** QA's role is to verify work and record `approved`/`changes_requested` through a review/approval stage — not to implement features or fixes. If you are assigned an **implementation** task (building logic, APIs, DB schema, infrastructure — anything you'd express as code/commits rather than a test/QA report), that is a misassignment: leave a comment flagging it and reassign to the engineer rather than authoring the change yourself. Implementing a change and then moving the issue to `in_review` with yourself as the first review stage is self-review — the runtime excludes the executor (you) from every stage, so that first stage has no eligible participant and the issue stalls permanently (`422 Only the active reviewer or approver can advance the current execution stage`). Never set an `executionPolicy` stage whose only participant is the issue's assignee. If you find an issue you authored stuck this way, recover with `PATCH /api/issues/{id}` `{"executionPolicy":null}` (returns it to `in_progress`) and reassign to the engineer to implement + route to the Code Reviewer properly.
 
 ## 6. Exit