@starlein/paperclip-plugin-company-wizard 0.4.18 → 0.4.21

package/templates/roles/engineer/HEARTBEAT.md

@@ -35,12 +35,13 @@ 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.
-- **Review path applies only when the pr-review module is active.** Without pr-review there is no PR review flow and no `in_review` step. If the github-repo module installed `skills/git-workflow.md`, follow its Direct-to-Base Flow (verify locally, commit, push to the base ref; open a PR only if branch protection rejects the direct push). Otherwise follow the project workspace instructions and record the verification/commit evidence. The rest of this bullet applies only when pr-review is active. 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 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.
+- **Review path applies only when the pr-review module is active.** Without pr-review there is no PR review flow and no `in_review` step. If the github-repo module installed `skills/git-workflow.md`, follow its Direct-to-Base Flow (verify locally, commit, push to the base ref; open a PR only if branch protection rejects the direct push). Otherwise follow the project workspace instructions and record the verification/commit evidence. The rest of this bullet applies only when pr-review is active. Before moving new PR 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`. 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 new PR work to `in_review`: 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 existing `in_review` issue with `executionPolicy: null`, do not assume it is stalled. Check `GET /api/issues/{id}/interactions`, `GET /api/issues/{id}/approvals`, its user owner, monitor, wake, and recovery state. A pending interaction or another explicit owner is a valid waiting path. Recover to `in_progress` only when none of those paths exists; then either add a non-author `executionPolicy` for PR review or self-merge when no Code Reviewer exists.
 
 ## 6. Exit
 
 - Always comment before exiting any issue you touched: status, evidence, blockers, work products, and next action.
-- If the issue used an isolated execution workspace/worktree, close it before final disposition: read `currentExecutionWorkspace.id` from `heartbeat-context`, check `GET /api/execution-workspaces/{id}/close-readiness`, then archive with `PATCH /api/execution-workspaces/{id}` `{ "status": "archived" }` after commits/PRs are merged and the tree is clean. If close-readiness or cleanup is blocked, do not mark `done`; leave the issue `blocked`/`in_review` with the exact cleanup blocker and next owner.
+- Preserve execution workspaces across issue completion — including the workspace your current run is executing in. **Never archive, retire, or delete an execution workspace as part of your own run.** Do not call `PATCH /api/execution-workspaces/{id}` with `{"status":"archived"}`, do not run `git worktree remove`, and do not delete the run branch — not when marking an issue `done`, not at the end of a routine run, and not as a "cleanup" or "tidy up" gesture. Archiving the workspace your run is using deletes its worktree mid-run: the run then fails workspace validation, and the next run that would reuse the workspace breaks. Follow-up, review, dependent work, and later routine runs may reuse the workspace, and Paperclip can restore a missing worktree only while its workspace record stays reusable. Workspace retirement is a board/operator action only, performed when an issue explicitly requests it. `cleanupEligibleAt` / "Cleanup: Not scheduled" is lifecycle metadata, not an automatic cleanup scheduler.
 - If no assigned work, valid approval/review, or routine-run exists, exit cleanly without scanning unrelated unassigned work.
 
 ## Rules

package/templates/roles/game-artist/HEARTBEAT.md

@@ -35,12 +35,12 @@ 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` and follow its executionPolicy.
+- Before leaving an issue in `in_review`, make the next action explicit. Valid paths include an active `executionPolicy` participant, a pending issue interaction or approval, an assigned user owner, a scheduled monitor, an active/queued wake, or a recovery issue. When `executionPolicy` is null, check `GET /api/issues/{id}/interactions` and `GET /api/issues/{id}/approvals`; null policy alone does not mean the issue is stalled. If no path exists, keep or return it to `in_progress` and assign an owner, or create the structured interaction/approval that will resume it.
 
 ## 6. Exit
 
 - Always comment before exiting any issue you touched: status, evidence, blockers, work products, and next action.
-- If the issue used an isolated execution workspace/worktree, close it before final disposition: read `currentExecutionWorkspace.id` from `heartbeat-context`, check `GET /api/execution-workspaces/{id}/close-readiness`, then archive with `PATCH /api/execution-workspaces/{id}` `{ "status": "archived" }` after commits/PRs are merged and the tree is clean. If close-readiness or cleanup is blocked, do not mark `done`; leave the issue `blocked`/`in_review` with the exact cleanup blocker and next owner.
+- Preserve execution workspaces across issue completion — including the workspace your current run is executing in. **Never archive, retire, or delete an execution workspace as part of your own run.** Do not call `PATCH /api/execution-workspaces/{id}` with `{"status":"archived"}`, do not run `git worktree remove`, and do not delete the run branch — not when marking an issue `done`, not at the end of a routine run, and not as a "cleanup" or "tidy up" gesture. Archiving the workspace your run is using deletes its worktree mid-run: the run then fails workspace validation, and the next run that would reuse the workspace breaks. Follow-up, review, dependent work, and later routine runs may reuse the workspace, and Paperclip can restore a missing worktree only while its workspace record stays reusable. Workspace retirement is a board/operator action only, performed when an issue explicitly requests it. `cleanupEligibleAt` / "Cleanup: Not scheduled" is lifecycle metadata, not an automatic cleanup scheduler.
 - If no assigned work, valid approval/review, or routine-run exists, exit cleanly without scanning unrelated unassigned work.
 
 ## Rules

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

@@ -35,12 +35,12 @@ 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` and follow its executionPolicy.
+- Before leaving an issue in `in_review`, make the next action explicit. Valid paths include an active `executionPolicy` participant, a pending issue interaction or approval, an assigned user owner, a scheduled monitor, an active/queued wake, or a recovery issue. When `executionPolicy` is null, check `GET /api/issues/{id}/interactions` and `GET /api/issues/{id}/approvals`; null policy alone does not mean the issue is stalled. If no path exists, keep or return it to `in_progress` and assign an owner, or create the structured interaction/approval that will resume it.
 
 ## 6. Exit
 
 - Always comment before exiting any issue you touched: status, evidence, blockers, work products, and next action.
-- If the issue used an isolated execution workspace/worktree, close it before final disposition: read `currentExecutionWorkspace.id` from `heartbeat-context`, check `GET /api/execution-workspaces/{id}/close-readiness`, then archive with `PATCH /api/execution-workspaces/{id}` `{ "status": "archived" }` after commits/PRs are merged and the tree is clean. If close-readiness or cleanup is blocked, do not mark `done`; leave the issue `blocked`/`in_review` with the exact cleanup blocker and next owner.
+- Preserve execution workspaces across issue completion — including the workspace your current run is executing in. **Never archive, retire, or delete an execution workspace as part of your own run.** Do not call `PATCH /api/execution-workspaces/{id}` with `{"status":"archived"}`, do not run `git worktree remove`, and do not delete the run branch — not when marking an issue `done`, not at the end of a routine run, and not as a "cleanup" or "tidy up" gesture. Archiving the workspace your run is using deletes its worktree mid-run: the run then fails workspace validation, and the next run that would reuse the workspace breaks. Follow-up, review, dependent work, and later routine runs may reuse the workspace, and Paperclip can restore a missing worktree only while its workspace record stays reusable. Workspace retirement is a board/operator action only, performed when an issue explicitly requests it. `cleanupEligibleAt` / "Cleanup: Not scheduled" is lifecycle metadata, not an automatic cleanup scheduler.
 - If no assigned work, valid approval/review, or routine-run exists, exit cleanly without scanning unrelated unassigned work.
 
 ## Rules

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

@@ -35,12 +35,12 @@ 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` and follow its executionPolicy.
+- Before leaving an issue in `in_review`, make the next action explicit. Valid paths include an active `executionPolicy` participant, a pending issue interaction or approval, an assigned user owner, a scheduled monitor, an active/queued wake, or a recovery issue. When `executionPolicy` is null, check `GET /api/issues/{id}/interactions` and `GET /api/issues/{id}/approvals`; null policy alone does not mean the issue is stalled. If no path exists, keep or return it to `in_progress` and assign an owner, or create the structured interaction/approval that will resume it.
 
 ## 6. Exit
 
 - Always comment before exiting any issue you touched: status, evidence, blockers, work products, and next action.
-- If the issue used an isolated execution workspace/worktree, close it before final disposition: read `currentExecutionWorkspace.id` from `heartbeat-context`, check `GET /api/execution-workspaces/{id}/close-readiness`, then archive with `PATCH /api/execution-workspaces/{id}` `{ "status": "archived" }` after commits/PRs are merged and the tree is clean. If close-readiness or cleanup is blocked, do not mark `done`; leave the issue `blocked`/`in_review` with the exact cleanup blocker and next owner.
+- Preserve execution workspaces across issue completion — including the workspace your current run is executing in. **Never archive, retire, or delete an execution workspace as part of your own run.** Do not call `PATCH /api/execution-workspaces/{id}` with `{"status":"archived"}`, do not run `git worktree remove`, and do not delete the run branch — not when marking an issue `done`, not at the end of a routine run, and not as a "cleanup" or "tidy up" gesture. Archiving the workspace your run is using deletes its worktree mid-run: the run then fails workspace validation, and the next run that would reuse the workspace breaks. Follow-up, review, dependent work, and later routine runs may reuse the workspace, and Paperclip can restore a missing worktree only while its workspace record stays reusable. Workspace retirement is a board/operator action only, performed when an issue explicitly requests it. `cleanupEligibleAt` / "Cleanup: Not scheduled" is lifecycle metadata, not an automatic cleanup scheduler.
 - If no assigned work, valid approval/review, or routine-run exists, exit cleanly without scanning unrelated unassigned work.
 
 ## Rules

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

@@ -20,6 +20,7 @@ You own product intent, backlog health, acceptance criteria, prioritization, and
 
 - Product ambiguity -> clarify options and recommend one.
 - Engineering implementation -> assign the Engineer directly with acceptance criteria and project/goal context. Do not leave ready engineering work unassigned for a later sweep.
+- Codebase audits, dependency upgrades, and implementation work -> assign the Software Engineer; keep the Code Reviewer for explicit non-author review and merge-gate work.
 - UX-visible scope -> involve the UI/UX designer.
 - Security-sensitive scope -> involve the Security Engineer.
 - Browser/user-facing verification -> involve QA.

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

@@ -35,12 +35,12 @@ 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` and no formal executionPolicy participant is waiting, 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.
+- 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.
 
 ## 6. Exit
 
 - Always comment before exiting any issue you touched: status, evidence, blockers, work products, and next action.
-- If the issue used an isolated execution workspace/worktree, close it before final disposition: read `currentExecutionWorkspace.id` from `heartbeat-context`, check `GET /api/execution-workspaces/{id}/close-readiness`, then archive with `PATCH /api/execution-workspaces/{id}` `{ "status": "archived" }` after commits/PRs are merged and the tree is clean. If close-readiness or cleanup is blocked, do not mark `done`; leave the issue `blocked`/`in_review` with the exact cleanup blocker and next owner.
+- Preserve execution workspaces across issue completion — including the workspace your current run is executing in. **Never archive, retire, or delete an execution workspace as part of your own run.** Do not call `PATCH /api/execution-workspaces/{id}` with `{"status":"archived"}`, do not run `git worktree remove`, and do not delete the run branch — not when marking an issue `done`, not at the end of a routine run, and not as a "cleanup" or "tidy up" gesture. Archiving the workspace your run is using deletes its worktree mid-run: the run then fails workspace validation, and the next run that would reuse the workspace breaks. Follow-up, review, dependent work, and later routine runs may reuse the workspace, and Paperclip can restore a missing worktree only while its workspace record stays reusable. Workspace retirement is a board/operator action only, performed when an issue explicitly requests it. `cleanupEligibleAt` / "Cleanup: Not scheduled" is lifecycle metadata, not an automatic cleanup scheduler.
 - If no assigned work, valid approval/review, or routine-run exists, exit cleanly without scanning unrelated unassigned work.
 
 ## Rules

package/templates/roles/qa/HEARTBEAT.md

@@ -35,6 +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 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.
@@ -42,7 +43,7 @@ Run this checklist on every heartbeat. The Paperclip skill is the source of trut
 ## 6. Exit
 
 - Always comment before exiting any issue you touched: status, evidence, blockers, work products, and next action.
-- If the issue used an isolated execution workspace/worktree, close it before final disposition: read `currentExecutionWorkspace.id` from `heartbeat-context`, check `GET /api/execution-workspaces/{id}/close-readiness`, then archive with `PATCH /api/execution-workspaces/{id}` `{ "status": "archived" }` after commits/PRs are merged and the tree is clean. If close-readiness or cleanup is blocked, do not mark `done`; leave the issue `blocked`/`in_review` with the exact cleanup blocker and next owner.
+- Preserve execution workspaces across issue completion — including the workspace your current run is executing in. **Never archive, retire, or delete an execution workspace as part of your own run.** Do not call `PATCH /api/execution-workspaces/{id}` with `{"status":"archived"}`, do not run `git worktree remove`, and do not delete the run branch — not when marking an issue `done`, not at the end of a routine run, and not as a "cleanup" or "tidy up" gesture. Archiving the workspace your run is using deletes its worktree mid-run: the run then fails workspace validation, and the next run that would reuse the workspace breaks. Follow-up, review, dependent work, and later routine runs may reuse the workspace, and Paperclip can restore a missing worktree only while its workspace record stays reusable. Workspace retirement is a board/operator action only, performed when an issue explicitly requests it. `cleanupEligibleAt` / "Cleanup: Not scheduled" is lifecycle metadata, not an automatic cleanup scheduler.
 - If no assigned work, valid approval/review, or routine-run exists, exit cleanly without scanning unrelated unassigned work.
 
 ## Rules

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

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

@@ -35,12 +35,12 @@ 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` and follow its executionPolicy.
+- Before leaving an issue in `in_review`, make the next action explicit. Valid paths include an active `executionPolicy` participant, a pending issue interaction or approval, an assigned user owner, a scheduled monitor, an active/queued wake, or a recovery issue. When `executionPolicy` is null, check `GET /api/issues/{id}/interactions` and `GET /api/issues/{id}/approvals`; null policy alone does not mean the issue is stalled. If no path exists, keep or return it to `in_progress` and assign an owner, or create the structured interaction/approval that will resume it.
 
 ## 6. Exit
 
 - Always comment before exiting any issue you touched: status, evidence, blockers, work products, and next action.
-- If the issue used an isolated execution workspace/worktree, close it before final disposition: read `currentExecutionWorkspace.id` from `heartbeat-context`, check `GET /api/execution-workspaces/{id}/close-readiness`, then archive with `PATCH /api/execution-workspaces/{id}` `{ "status": "archived" }` after commits/PRs are merged and the tree is clean. If close-readiness or cleanup is blocked, do not mark `done`; leave the issue `blocked`/`in_review` with the exact cleanup blocker and next owner.
+- Preserve execution workspaces across issue completion — including the workspace your current run is executing in. **Never archive, retire, or delete an execution workspace as part of your own run.** Do not call `PATCH /api/execution-workspaces/{id}` with `{"status":"archived"}`, do not run `git worktree remove`, and do not delete the run branch — not when marking an issue `done`, not at the end of a routine run, and not as a "cleanup" or "tidy up" gesture. Archiving the workspace your run is using deletes its worktree mid-run: the run then fails workspace validation, and the next run that would reuse the workspace breaks. Follow-up, review, dependent work, and later routine runs may reuse the workspace, and Paperclip can restore a missing worktree only while its workspace record stays reusable. Workspace retirement is a board/operator action only, performed when an issue explicitly requests it. `cleanupEligibleAt` / "Cleanup: Not scheduled" is lifecycle metadata, not an automatic cleanup scheduler.
 - If no assigned work, valid approval/review, or routine-run exists, exit cleanly without scanning unrelated unassigned work.
 
 ## Rules

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

@@ -35,12 +35,12 @@ 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` and follow its executionPolicy.
+- Before leaving an issue in `in_review`, make the next action explicit. Valid paths include an active `executionPolicy` participant, a pending issue interaction or approval, an assigned user owner, a scheduled monitor, an active/queued wake, or a recovery issue. When `executionPolicy` is null, check `GET /api/issues/{id}/interactions` and `GET /api/issues/{id}/approvals`; null policy alone does not mean the issue is stalled. If no path exists, keep or return it to `in_progress` and assign an owner, or create the structured interaction/approval that will resume it.
 
 ## 6. Exit
 
 - Always comment before exiting any issue you touched: status, evidence, blockers, work products, and next action.
-- If the issue used an isolated execution workspace/worktree, close it before final disposition: read `currentExecutionWorkspace.id` from `heartbeat-context`, check `GET /api/execution-workspaces/{id}/close-readiness`, then archive with `PATCH /api/execution-workspaces/{id}` `{ "status": "archived" }` after commits/PRs are merged and the tree is clean. If close-readiness or cleanup is blocked, do not mark `done`; leave the issue `blocked`/`in_review` with the exact cleanup blocker and next owner.
+- Preserve execution workspaces across issue completion — including the workspace your current run is executing in. **Never archive, retire, or delete an execution workspace as part of your own run.** Do not call `PATCH /api/execution-workspaces/{id}` with `{"status":"archived"}`, do not run `git worktree remove`, and do not delete the run branch — not when marking an issue `done`, not at the end of a routine run, and not as a "cleanup" or "tidy up" gesture. Archiving the workspace your run is using deletes its worktree mid-run: the run then fails workspace validation, and the next run that would reuse the workspace breaks. Follow-up, review, dependent work, and later routine runs may reuse the workspace, and Paperclip can restore a missing worktree only while its workspace record stays reusable. Workspace retirement is a board/operator action only, performed when an issue explicitly requests it. `cleanupEligibleAt` / "Cleanup: Not scheduled" is lifecycle metadata, not an automatic cleanup scheduler.
 - If no assigned work, valid approval/review, or routine-run exists, exit cleanly without scanning unrelated unassigned work.
 
 ## Rules

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

@@ -35,12 +35,12 @@ 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` and follow its executionPolicy.
+- Before leaving an issue in `in_review`, make the next action explicit. Valid paths include an active `executionPolicy` participant, a pending issue interaction or approval, an assigned user owner, a scheduled monitor, an active/queued wake, or a recovery issue. When `executionPolicy` is null, check `GET /api/issues/{id}/interactions` and `GET /api/issues/{id}/approvals`; null policy alone does not mean the issue is stalled. If no path exists, keep or return it to `in_progress` and assign an owner, or create the structured interaction/approval that will resume it.
 
 ## 6. Exit
 
 - Always comment before exiting any issue you touched: status, evidence, blockers, work products, and next action.
-- If the issue used an isolated execution workspace/worktree, close it before final disposition: read `currentExecutionWorkspace.id` from `heartbeat-context`, check `GET /api/execution-workspaces/{id}/close-readiness`, then archive with `PATCH /api/execution-workspaces/{id}` `{ "status": "archived" }` after commits/PRs are merged and the tree is clean. If close-readiness or cleanup is blocked, do not mark `done`; leave the issue `blocked`/`in_review` with the exact cleanup blocker and next owner.
+- Preserve execution workspaces across issue completion — including the workspace your current run is executing in. **Never archive, retire, or delete an execution workspace as part of your own run.** Do not call `PATCH /api/execution-workspaces/{id}` with `{"status":"archived"}`, do not run `git worktree remove`, and do not delete the run branch — not when marking an issue `done`, not at the end of a routine run, and not as a "cleanup" or "tidy up" gesture. Archiving the workspace your run is using deletes its worktree mid-run: the run then fails workspace validation, and the next run that would reuse the workspace breaks. Follow-up, review, dependent work, and later routine runs may reuse the workspace, and Paperclip can restore a missing worktree only while its workspace record stays reusable. Workspace retirement is a board/operator action only, performed when an issue explicitly requests it. `cleanupEligibleAt` / "Cleanup: Not scheduled" is lifecycle metadata, not an automatic cleanup scheduler.
 - If no assigned work, valid approval/review, or routine-run exists, exit cleanly without scanning unrelated unassigned work.
 
 ## Rules

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

@@ -35,12 +35,12 @@ 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` and follow its executionPolicy.
+- Before leaving an issue in `in_review`, make the next action explicit. Valid paths include an active `executionPolicy` participant, a pending issue interaction or approval, an assigned user owner, a scheduled monitor, an active/queued wake, or a recovery issue. When `executionPolicy` is null, check `GET /api/issues/{id}/interactions` and `GET /api/issues/{id}/approvals`; null policy alone does not mean the issue is stalled. If no path exists, keep or return it to `in_progress` and assign an owner, or create the structured interaction/approval that will resume it.
 
 ## 6. Exit
 
 - Always comment before exiting any issue you touched: status, evidence, blockers, work products, and next action.
-- If the issue used an isolated execution workspace/worktree, close it before final disposition: read `currentExecutionWorkspace.id` from `heartbeat-context`, check `GET /api/execution-workspaces/{id}/close-readiness`, then archive with `PATCH /api/execution-workspaces/{id}` `{ "status": "archived" }` after commits/PRs are merged and the tree is clean. If close-readiness or cleanup is blocked, do not mark `done`; leave the issue `blocked`/`in_review` with the exact cleanup blocker and next owner.
+- Preserve execution workspaces across issue completion — including the workspace your current run is executing in. **Never archive, retire, or delete an execution workspace as part of your own run.** Do not call `PATCH /api/execution-workspaces/{id}` with `{"status":"archived"}`, do not run `git worktree remove`, and do not delete the run branch — not when marking an issue `done`, not at the end of a routine run, and not as a "cleanup" or "tidy up" gesture. Archiving the workspace your run is using deletes its worktree mid-run: the run then fails workspace validation, and the next run that would reuse the workspace breaks. Follow-up, review, dependent work, and later routine runs may reuse the workspace, and Paperclip can restore a missing worktree only while its workspace record stays reusable. Workspace retirement is a board/operator action only, performed when an issue explicitly requests it. `cleanupEligibleAt` / "Cleanup: Not scheduled" is lifecycle metadata, not an automatic cleanup scheduler.
 - If no assigned work, valid approval/review, or routine-run exists, exit cleanly without scanning unrelated unassigned work.
 
 ## Rules