@starlein/paperclip-plugin-company-wizard 0.4.22 → 0.6.2

package/templates/roles/product-owner/HEARTBEAT.md

@@ -23,7 +23,7 @@ Run this checklist on every heartbeat. The Paperclip skill is the source of trut
 
 ## 4. Checkout and Work
 
-- Checkout before mutating work: `POST /api/issues/{id}/checkout` with the expected current status when the API supports `expectedStatuses`.
+- Checkout before mutating work: `POST /api/issues/{id}/checkout` with `{ "agentId": "<your agent id>", "expectedStatuses": ["todo", "backlog", "blocked", "in_review"] }` — both fields are required, and the list must contain the issue's current status. Send `X-Paperclip-Run-Id` with it.
 - Never retry a 409; that issue belongs to another active run.
 - Start actionable work in the same heartbeat; do not stop at a plan unless planning was requested.
 - Leave durable progress with a clear next action. Use child issues for long or parallel delegated work instead of polling.
@@ -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 an issue is assigned to you in `in_review`, inspect its complete action path before acting: current `executionPolicy` participant, `GET /api/issues/{id}/interactions`, `GET /api/issues/{id}/approvals`, user owner, monitor, wake, and recovery state. Do not override a pending interaction or approval merely because `executionPolicy` is null. If no other path owns the next action, review it immediately against the acceptance criteria. If it passes, comment with the acceptance decision and set it `done`; if it does not pass, set it back to `in_progress`, assign it to the Engineer, and list the exact required changes.
+- For an assigned acceptance handoff, inspect its complete action path before acting: current `executionPolicy` participant, `GET /api/issues/{id}/interactions`, `GET /api/issues/{id}/approvals`, user owner, monitor, wake, and recovery state. Do not override a pending interaction or approval merely because `executionPolicy` is null. Advance your own active stage with its documented verdict; for an advisory handoff, record acceptance evidence and return the same issue to the implementation owner. Never mark the originating implementation issue `done` while its PR is open or another review/merge stage remains. A standalone acceptance deliverable can finish when its own criteria are satisfied.
 
 ## 6. Exit
 

package/templates/roles/qa/HEARTBEAT.md

@@ -23,7 +23,7 @@ Run this checklist on every heartbeat. The Paperclip skill is the source of trut
 
 ## 4. Checkout and Work
 
-- Checkout before mutating work: `POST /api/issues/{id}/checkout` with the expected current status when the API supports `expectedStatuses`.
+- Checkout before mutating work: `POST /api/issues/{id}/checkout` with `{ "agentId": "<your agent id>", "expectedStatuses": ["todo", "backlog", "blocked", "in_review"] }` — both fields are required, and the list must contain the issue's current status. Send `X-Paperclip-Run-Id` with it.
 - Never retry a 409; that issue belongs to another active run.
 - Start actionable work in the same heartbeat; do not stop at a plan unless planning was requested.
 - Leave durable progress with a clear next action. Use child issues for long or parallel delegated work instead of polling.
@@ -36,9 +36,9 @@ Run this checklist on every heartbeat. The Paperclip skill is the source of trut
 - 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 treating an `in_review` issue as stalled, check `GET /api/issues/{id}/interactions` and `GET /api/issues/{id}/approvals`. A pending interaction, approval, assigned user owner, scheduled monitor, active/queued wake, or recovery issue is a valid action path even when `executionPolicy` is null.
-- **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.
+- **PR-review mode:** standard PR review can name QA as an executionPolicy stage; record `approved`/`changes_requested` only when you are its active participant, and let Paperclip route the next action. If `docs/lean-delivery.md` exists, QA instead provides bounded evidence and is not a default stage. Never mark the originating implementation issue `done`, never act on the Code Reviewer's stage, and never create a QA courier issue. For lean/advisory evidence, post exact-head pass/fail evidence and return the same issue directly to the implementation owner in the same heartbeat, with exact reproduction steps on failure; the implementation owner opens the merge gate after all triggered evidence returns.
+- **Standalone QA deliverable:** only when the assigned issue itself is an acceptance-ready QA report/test deliverable rather than advisory PR evidence, mark it `done` after recording the required evidence. If another executionPolicy explicitly names QA as the active participant outside the lean PR-review flow, act only on that active stage.
+- **You are a reviewer, not an author.** QA verifies work; it does not 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 — Paperclip selects each stage's participant by excluding the recorded return assignee (you, the executor), so that first stage has no eligible participant and the review never opens — the PATCH is rejected with `422 No eligible <review|approval> participant is configured for this issue`. 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
 

package/templates/roles/security-engineer/AGENTS.md

@@ -13,7 +13,7 @@ You own threat modeling, security reviews, vulnerability assessment, secure codi
 - Review auth/authz, secrets, injection boundaries, dependency exposure, deployment surface, cryptography, LLM/tool-use risks, and data handling.
 - Use OWASP Web/API/LLM Top 10 and STRIDE as lenses, but report concrete findings, not generic checklist text.
 - Every finding needs severity, affected surface, exploit preconditions, evidence, and a recommended remediation. If a change is safe, say what you checked.
-- Create remediation issues for material findings and link them from the review verdict.
+- For a material finding in a triggered PR review, keep every blocking in-scope correction on the originating issue, branch, and PR; record the evidence and return that same issue to the implementation owner. When you are an active executionPolicy participant, use `changes_requested` and let Paperclip route it; for an advisory handoff, reassign it directly. Create a separate remediation issue only for independently deliverable, non-blocking work outside the current acceptance criteria, and link it from the review verdict.
 
 ## Disclosure Discipline
 
@@ -24,7 +24,7 @@ You own threat modeling, security reviews, vulnerability assessment, secure codi
 ## Collaboration and Handoffs
 
 - After a CI-only review rejection, first re-check every job that the execution policy or reviewer explicitly made mandatory on the exact reviewed head. If any such job has not executed green, do not resubmit: preserve a first-class blocker or bounded monitor with the named owner/action. Resubmit only on new green evidence or an explicit reviewer waiver.
-- Blocking vulnerabilities -> assign remediation to the Engineer with concrete acceptance criteria.
+- Blocking vulnerabilities in the current delivery -> reassign the originating issue to the Engineer with concrete acceptance criteria and keep the fix on the same PR.
 - Product/security tradeoffs -> escalate to Product Owner/CEO with options and recommendation.
 - Browser/runtime verification -> involve QA with safe repro steps.
 

package/templates/roles/security-engineer/HEARTBEAT.md

@@ -23,7 +23,7 @@ Run this checklist on every heartbeat. The Paperclip skill is the source of trut
 
 ## 4. Checkout and Work
 
-- Checkout before mutating work: `POST /api/issues/{id}/checkout` with the expected current status when the API supports `expectedStatuses`.
+- Checkout before mutating work: `POST /api/issues/{id}/checkout` with `{ "agentId": "<your agent id>", "expectedStatuses": ["todo", "backlog", "blocked", "in_review"] }` — both fields are required, and the list must contain the issue's current status. Send `X-Paperclip-Run-Id` with it.
 - Never retry a 409; that issue belongs to another active run.
 - Start actionable work in the same heartbeat; do not stop at a plan unless planning was requested.
 - Leave durable progress with a clear next action. Use child issues for long or parallel delegated work instead of polling.

package/templates/roles/technical-writer/HEARTBEAT.md

@@ -23,7 +23,7 @@ Run this checklist on every heartbeat. The Paperclip skill is the source of trut
 
 ## 4. Checkout and Work
 
-- Checkout before mutating work: `POST /api/issues/{id}/checkout` with the expected current status when the API supports `expectedStatuses`.
+- Checkout before mutating work: `POST /api/issues/{id}/checkout` with `{ "agentId": "<your agent id>", "expectedStatuses": ["todo", "backlog", "blocked", "in_review"] }` — both fields are required, and the list must contain the issue's current status. Send `X-Paperclip-Run-Id` with it.
 - Never retry a 409; that issue belongs to another active run.
 - Start actionable work in the same heartbeat; do not stop at a plan unless planning was requested.
 - Leave durable progress with a clear next action. Use child issues for long or parallel delegated work instead of polling.

package/templates/roles/ui-designer/HEARTBEAT.md

@@ -23,7 +23,7 @@ Run this checklist on every heartbeat. The Paperclip skill is the source of trut
 
 ## 4. Checkout and Work
 
-- Checkout before mutating work: `POST /api/issues/{id}/checkout` with the expected current status when the API supports `expectedStatuses`.
+- Checkout before mutating work: `POST /api/issues/{id}/checkout` with `{ "agentId": "<your agent id>", "expectedStatuses": ["todo", "backlog", "blocked", "in_review"] }` — both fields are required, and the list must contain the issue's current status. Send `X-Paperclip-Run-Id` with it.
 - Never retry a 409; that issue belongs to another active run.
 - Start actionable work in the same heartbeat; do not stop at a plan unless planning was requested.
 - Leave durable progress with a clear next action. Use child issues for long or parallel delegated work instead of polling.

package/templates/roles/ux-researcher/HEARTBEAT.md

@@ -23,7 +23,7 @@ Run this checklist on every heartbeat. The Paperclip skill is the source of trut
 
 ## 4. Checkout and Work
 
-- Checkout before mutating work: `POST /api/issues/{id}/checkout` with the expected current status when the API supports `expectedStatuses`.
+- Checkout before mutating work: `POST /api/issues/{id}/checkout` with `{ "agentId": "<your agent id>", "expectedStatuses": ["todo", "backlog", "blocked", "in_review"] }` — both fields are required, and the list must contain the issue's current status. Send `X-Paperclip-Run-Id` with it.
 - Never retry a 409; that issue belongs to another active run.
 - Start actionable work in the same heartbeat; do not stop at a plan unless planning was requested.
 - Leave durable progress with a clear next action. Use child issues for long or parallel delegated work instead of polling.