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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlein/paperclip-plugin-company-wizard",
-  "version": "0.4.18",
+  "version": "0.4.21",
   "type": "module",
   "description": "AI-powered wizard to bootstrap paperclip agent companies from composable templates (for latest paperclip version)",
   "repository": {
@@ -43,8 +43,8 @@
     "tailwind-merge": "^3.4.1"
   },
   "devDependencies": {
-    "@paperclipai/plugin-sdk": "^2026.529.0",
-    "@paperclipai/shared": "^2026.529.0",
+    "@paperclipai/plugin-sdk": "^2026.707.0",
+    "@paperclipai/shared": "^2026.707.0",
     "@rollup/plugin-node-resolve": "^16.0.1",
     "@rollup/plugin-typescript": "^12.1.2",
     "@tailwindcss/postcss": "^4.0.7",
@@ -64,8 +64,8 @@
     "vitest": "^3.0.5"
   },
   "peerDependencies": {
-    "@paperclipai/plugin-sdk": ">=2026.529.0",
-    "@paperclipai/shared": ">=2026.529.0",
+    "@paperclipai/plugin-sdk": ">=2026.707.0",
+    "@paperclipai/shared": ">=2026.707.0",
     "react": ">=18",
     "react-dom": ">=18"
   },

package/templates/modules/auto-assign/agents/ceo/skills/auto-assign.fallback.md

@@ -21,4 +21,5 @@ On your heartbeat, after handling your own assignments:
 - Clear stragglers in one pass instead of drip-feeding one issue per run.
 - Do not run this from normal heartbeats.
 - Do not self-assign random unassigned work.
-- If no suitable match exists, leave the issue unassigned and state the reason in the routine-run comment.
+- If no suitable match exists, leave the issue unassigned and state the reason in the routine-run comment.
+- Never archive or retire your own routine-run workspace. This is control-plane work via the API; do not `PATCH /api/execution-workspaces/{id}` to `archived` or remove the worktree your run uses — it fails the run's workspace validation and breaks the next reuse. Retirement is a board/operator action only.

package/templates/modules/auto-assign/skills/auto-assign.md

@@ -24,3 +24,4 @@ Use this only when the current assigned issue/routine is titled like "Auto-assig
 - Do not assign code tasks to non-engineering agents or security-sensitive work without security coverage.
 - Respect budgets, pause/cancel states, approval gates, `blockedByIssueIds`, and executionPolicy.
 - If no suitable match exists, leave the issue unassigned and state the reason in the routine-run comment.
+- **Never archive or retire your own routine-run workspace.** This routine is pure control-plane work (assigning issues via the API); it needs no repository state. When done, mark the routine issue `done` and exit. Do not `PATCH /api/execution-workspaces/{id}` to `archived` and do not remove the worktree your run is using — archiving it mid-run fails the run's workspace validation and breaks the next reuse. Workspace retirement is a board/operator action only.

package/templates/modules/backlog/agents/ceo/skills/backlog-health.fallback.md

@@ -20,3 +20,4 @@ On your heartbeat, after handling assignments:
 - Only create issues when engineers would otherwise have nothing to work on.
 - Keep it minimal — just enough to unblock, not a full grooming session.
 - **Review handoff:** When moving an issue to `in_review`, always assign it to the reviewer. If the issue has an executionPolicy with review stages, Paperclip reassigns automatically. Otherwise PATCH `assigneeAgentId` to the reviewer before or at the same time as the status change.
+- Backlog grooming is intentionally project-detached and must remain API-only. Do not create or enter a git worktree for the grooming run, and do not attach the routine itself to a project. Setting `projectId` and isolated `executionWorkspaceSettings` on the work issues you create is still required and does not change the grooming run's workspace behavior.

package/templates/modules/backlog/module.meta.json

@@ -26,7 +26,8 @@
       "assignTo": "capability:backlog-health",
       "schedule": "0 */2 * * *",
       "priority": "medium",
-      "concurrencyPolicy": "skip_if_active"
+      "concurrencyPolicy": "skip_if_active",
+      "useProjectWorkspace": false
     }
   ]
 }

package/templates/modules/backlog/skills/backlog-health.md

@@ -25,7 +25,7 @@ Add additional labels if the roadmap calls for them (e.g., `docs`, `design`, `se
 
 ## Backlog Health Check
 
-1. Checkout the assigned backlog/routine issue before mutating the board.
+1. Checkout the assigned backlog/routine issue in Paperclip before mutating the board. This is API-only control-plane work; do not create or enter a repository worktree for the grooming run.
 2. Read the current company goals, roadmap/project context, existing issue documents, and recent decision log entries.
 3. Query existing issues for the relevant project/goal and avoid duplicates.
 4. If the backlog is thin or unclear, create around 3-6 small actionable issues via `POST /api/companies/{companyId}/issues`.
@@ -44,6 +44,8 @@ Add additional labels if the roadmap calls for them (e.g., `docs`, `design`, `se
 - Split into subissues only when each child can be completed independently; avoid splitting tightly coupled implementation across sibling subissues.
 - **Set workspace isolation explicitly at creation.** Top-level issues (no `parentId`) must send `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so each gets its own worktree/branch. Sub-issues set `parentId` and omit `executionWorkspaceSettings` so they reuse the parent's workspace. Never create a top-level issue without it — otherwise it inherits the workspace of whatever issue you currently have checked out and blocks parallel work.
 - Always attach at least one label to every issue you create.
+- **Attach a task watchdog to every top-level issue you create.** Send `"watchdog": { "agentId": "<CEO agent id>", "instructions": "If this issue's work stalls (runs end without it reaching done, a review is misrouted, or a dependent merge is stranded), re-evaluate and recover: verify blockers and executionPolicy gates, reassign to the right owner with an explicit next action, or escalate. Do not archive or delete any execution workspace." }`. This is native, event-driven stall recovery — Paperclip wakes the watchdog agent when the issue's subtree stops without completing, so you no longer rely only on the periodic stall-detection routine. Use the CEO agent id (resolve it from your `heartbeat-context` or `GET /api/companies/{companyId}/agents`); omit the watchdog only for throwaway sub-issues that reuse a parent's workspace.
 - If the goal is fully decomposed into issues, do not create more. Report status and next review trigger to the CEO/Product Owner.
 - Work products such as roadmap drafts or decomposition tables belong in issue documents/artifacts, not only comments.
 - **Review handoff:** When moving an issue to `in_review`, always assign it to the reviewer. If the issue has an executionPolicy with review stages, Paperclip reassigns automatically. If there is no executionPolicy, PATCH the issue's `assigneeAgentId` to the reviewer before or at the same time as the status change. An issue in `in_review` that is still assigned to the original implementer will stall — no one picks it up. Always reassign on review handoff.
+- **Backlog grooming is intentionally project-detached and must not use a git worktree.** Perform the run through Paperclip APIs only. Setting `projectId` and isolated `executionWorkspaceSettings` on the *work issues you create* is correct; that does not attach the grooming run itself to their project or worktrees. Do not clone, branch, run `git worktree add`, or try to repair the routine by attaching it to a project.

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

@@ -16,7 +16,7 @@ Use this flow when the **pr-review module is not active** — there is no Code R
    - If the push is **rejected as non-fast-forward** (someone else pushed), `git pull --rebase origin <base-branch>`, re-run the checks, and push again.
    - If the push is **rejected by branch protection** (e.g. "protected branch hook declined" / a PR is required), use the **PR fallback** below. This is the only case where you open a PR in this flow.
 8. **Confirm it landed:** `git log origin/<base-branch> -1` shows your commit.
-9. If the issue uses an isolated execution workspace (worktree), archive it from your `heartbeat-context` after the push.
+9. If the issue uses an isolated execution workspace (worktree), leave it reusable after the push. Do not archive/delete it during issue completion; workspace retirement is a separate board/operator action.
 10. **Company-owned CI/CD only:** if the `ci-cd` module is active and the base CI goes red after your push, run the baseline-emergency protocol in `../../docs/git-workflow.md` → *Base-branch-red deadlock*. A pre-existing repo check the company never configured is **advisory** — do not treat it as a gate or let it block your work.
 
 ### PR fallback (only when branch protection requires a PR)

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

@@ -95,7 +95,7 @@ Use this flow when the **pr-review module is not active** (no Code Reviewer role
    - Rejected as **non-fast-forward**: `git pull --rebase origin <base-branch>`, re-run checks, push again.
    - Rejected by **branch protection** (PR required): use the PR fallback — feature branch → `git push -u origin <branch-name>` → `gh pr create --base <base-branch> ... --body-file <file>` (register the PR as a work product) → `gh pr merge <N> --merge --delete-branch`. This is the only case where you open a PR.
 7. Confirm it landed: `git log origin/<base-branch> -1` shows your commit.
-8. If the issue uses an isolated execution workspace (worktree), archive it from `heartbeat-context` after the push.
+8. If the issue uses an isolated execution workspace (worktree), leave it reusable after the push. Do not archive/delete it during issue completion; workspace retirement is a separate board/operator action.
 9. **Company-owned CI/CD only** (`ci-cd` module active): if the base CI goes red after your push, fix it immediately (see *Base-branch-red deadlock*). A pre-existing repo check the company never configured is advisory — not a gate.
 
 ## Resolving the default branch
@@ -135,7 +135,7 @@ For a brand-new local repository there is no remote yet, so initialize on `main`
 
 - Never mark an issue as `done` unless at least one new commit exists for that issue's work and has been pushed.
 - Before marking `done`, ensure the working tree is clean (`git status --short` shows no pending changes).
-- If Paperclip created an isolated execution workspace for this issue, close/archive it after the commit/PR has landed and before marking `done`. If cleanup is blocked or fails, leave the issue open with the exact cleanup blocker. If the issue is in the shared project workspace, do not invent isolated-worktree cleanup.
+- If Paperclip created an isolated execution workspace for this issue, preserve it after the commit/PR lands so review, follow-up, or dependent work can reuse it. Do not archive/delete it as part of marking the issue `done`. Paperclip's `cleanupEligibleAt` / "Cleanup: Not scheduled" value does not run cleanup automatically; retirement is a separate board/operator action.
 - If no repository change is required, do not silently close as `done`: add an issue comment explaining why no code change was needed and escalate to the CEO for explicit decision.
 
 ## Branch Safety

package/templates/modules/pr-review/README.md

@@ -25,11 +25,11 @@ Adds a PR-based review workflow with dedicated reviewer roles.
 7. Product Owner reviews for intent alignment, scope discipline, acceptance criteria
 8. Domain reviewers (UI/UX/DevOps) may add advisory PR comments unless explicitly added as executionPolicy participants
 9. DevOps reviews infrastructure impact when explicitly added as a stage
-10. The Code Reviewer (the non-author merge gate) merges when all stages are approved (no `changes_requested` outstanding), confirms the PR landed on the correct base, closes/archives any isolated worktree that Paperclip created, and only then records the final approval / closes the issue
+10. The Code Reviewer (the non-author merge gate) merges when all stages are approved (no `changes_requested` outstanding), confirms the PR landed on the correct base, leaves any isolated execution workspace reusable, and only then records the final approval / closes the issue
 
 ## Handover mechanism
 
-The issue's native `executionPolicy` (`review`/`approval` stages). Each reviewer is the active participant of a stage and records an `approved` / `changes_requested` decision through the normal issue update route; Paperclip stores the reviewer/approver audit trail on the issue (`reviewed_by` / `approved_by` metadata where exposed). The decision may be mirrored as a GitHub PR comment. Do not create separate review subissues, and **do not model the merge as a standalone "Code review and merge PR #N" issue that is `blockedBy` the review issues** — that strands the merge once the reviews close `done` (Paperclip won't reliably re-wake a `blocked` issue whose blockers are all `done`), so the PR is never merged even when green. The merge gate is the **last `executionPolicy` stage on the same implementation issue**, which advances in place. If a reviewer doesn't wake, or a merge issue ends up stranded `blocked`, the CEO's stall-detection (if enabled) will catch it (*Stranded blocked* / *PR-queue hygiene*).
+The issue's native `executionPolicy` (`review`/`approval` stages). Each reviewer is the active participant of a stage and records an `approved` / `changes_requested` decision through the normal issue update route; Paperclip stores the reviewer/approver audit trail on the issue (`reviewed_by` / `approved_by` metadata where exposed). The decision may be mirrored as a GitHub PR comment. Do not create separate review subissues, and **do not model the merge as a standalone "Code review and merge PR #N" issue that is `blockedBy` the review issues** — it adds a second wake transition and can leave a green PR waiting after reviews finish. The merge gate is the **last `executionPolicy` stage on the same implementation issue**, which advances in place. If a reviewer doesn't wake, or a merge issue stays blocked after becoming dependency-ready, the CEO's stall-detection (if enabled) will use Paperclip's blocker/wake diagnostics and PR-queue reconciliation to recover it.
 
 ## Best for
 

package/templates/modules/pr-review/agents/code-reviewer/skills/code-review.md

@@ -1,6 +1,6 @@
 # Skill: Code Review (final merge gate)
 
-You are the **final merge gate** for pull requests. After QA, the Security Engineer (when relevant), and the Product Owner have approved, the issue's `executionPolicy` routes its final `approval` stage to you. You do a last correctness pass, satisfy the hard verification gate, **merge the PR**, clean up, and only then record `approved` — which closes the issue to `done`.
+You are the **final merge gate** for pull requests. After QA, the Security Engineer (when relevant), and the Product Owner have approved, the issue's `executionPolicy` routes its final `approval` stage to you. You do a last correctness pass, satisfy the hard verification gate, **merge the PR**, preserve its execution workspace for reuse, and only then record `approved` — which closes the issue to `done`.
 
 ## Why you, and not the engineer
 
@@ -22,8 +22,8 @@ Paperclip's runtime **excludes the issue's original executor (the author) from e
 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.
+4. If Paperclip created an isolated execution workspace for the issue, leave it reusable after the merge. Do not archive/delete it during approval; later review, follow-up, or dependent work may still reference the workspace.
+5. **Only after the merge succeeds**, 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

package/templates/modules/pr-review/agents/engineer/skills/pr-workflow.md

@@ -40,7 +40,7 @@ When this skill is active, you work in feature branches and open PRs instead of
 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. 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.
+    - **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 leave any isolated execution workspace reusable.
 
 ## Resolving merge conflicts
 
@@ -70,17 +70,17 @@ In **PR-Gate mode** (Code Reviewer present): you are the issue author and Paperc
 
 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)
+## Misrouted in_review (no action path)
 
-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:
+`executionPolicy: null` is not sufficient evidence that an existing `in_review` issue is stuck. First inspect `GET /api/issues/{id}/interactions`, `GET /api/issues/{id}/approvals`, the issue's user owner, scheduled monitor, active/queued wakes, and `GET /api/issues/{id}/recovery-actions`. A pending interaction or approval, user owner, monitor, wake, active run, or recovery issue is an explicit waiting path; leave it intact. Recover only when the issue has neither a usable non-author execution stage nor any of those paths:
 
 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.
+3. Leave an issue comment naming the missing action path 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.
+For new PR work, 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). For existing issues, diagnose the full action path before changing state.
 
 ## Rules
 
@@ -93,5 +93,5 @@ Never move an issue to `in_review` unless an `executionPolicy` with at least one
 - **The merge gate must be the last stage, and it must be a non-author.** The Product Owner's `approval` is the product sign-off, not the final stage: if it were last, their verdict would auto-close the issue to `done` with the PR still open on GitHub. Append a final merge-gate `approval` stage for the **Code Reviewer** after the Product Owner's. Never make yourself the merge gate — Paperclip excludes the executor, so that stage stalls with `422 No eligible approval participant`. If no Code Reviewer is on the team, do not set executionPolicy stages; use the self-merge path instead.
 - Do not create separate child review issues and do not use @-mentions to request review; the executionPolicy stages are the governance signal.
 - Do not wait for GitHub-native approving reviews when all agents share the same GitHub credential; GitHub rejects self-approval. The Paperclip executionPolicy stages are the required signal unless a separate non-author GitHub reviewer credential is explicitly available.
-- Post-merge cleanup of any isolated execution workspace belongs to the merge-gate agent (they archive it from `heartbeat-context` when landing the PR). You only clean up your own worktree if you abandon a branch or the issue is cancelled before review. If this issue runs in the shared project workspace, do not invent isolated-worktree cleanup.
+- Preserve isolated execution workspaces after merge. Neither the author nor merge-gate agent archives/deletes a workspace during normal issue completion; review, follow-up, or dependent work may reuse it. Retirement is a separate board/operator action, including for abandoned or cancelled work.
 - **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.

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

@@ -76,7 +76,7 @@ Review runs through the issue's native `executionPolicy` (stages), not separate
 6. **Security Engineer** (when present as a stage) probes the security-relevant change and records a verdict stating what was checked.
 7. Other domain reviewers may add **advisory, non-blocking** PR comments. They do not gate the merge.
 8. **Product Owner** reviews for intent match, scope discipline, and acceptance criteria, and records the `approval` verdict through the normal issue update route, preserving the issue-level approval audit trail.
-9. **Code Reviewer** owns the final `approval` stage (merge gate): once reviewers and the Product Owner have approved, the Code Reviewer satisfies the hard gate (CI green, or runs the tests/build and pastes the output), merges the PR into the correct configured base, confirms the merge landed, closes/archives the isolated execution workspace when one exists and close-readiness allows it, and only then records `approved` — which closes the issue to `done`. The merge and workspace cleanup must happen before the issue is `done`. The merge owner must be a non-author: Paperclip excludes the issue's executor (the engineer) from every stage, so the engineer cannot be the merge gate.
+9. **Code Reviewer** owns the final `approval` stage (merge gate): once reviewers and the Product Owner have approved, the Code Reviewer satisfies the hard gate (CI green, or runs the tests/build and pastes the output), merges the PR into the correct configured base, confirms the merge landed, preserves the isolated execution workspace for reuse, and only then records `approved` — which closes the issue to `done`. The merge owner must be a non-author: Paperclip excludes the issue's executor (the engineer) from every stage, so the engineer cannot be the merge gate.
 
 ## Review Roles
 
@@ -103,7 +103,7 @@ The hard gate is **executed verification**, enforced on the merge-gate stage (th
 - Before merge, verify the PR base matches the configured project/worktree base from `heartbeat-context`. Retarget before review/merge if needed.
 - The Code Reviewer is the merge owner (a non-author); the engineer who wrote the PR cannot merge it.
 - The merge gate must be the **last** `approval` stage and must be a **non-author**. If the Product Owner's approval were last, it would auto-close the issue to `done` and the merge would be skipped, leaving the PR open on GitHub. The merge gate can never be the issue's executor — Paperclip excludes the original executor from every stage (`422 No eligible approval participant is configured for this issue`).
-- If Paperclip created an isolated execution workspace for the issue, read its id from `heartbeat-context`, call close-readiness, and archive it after the PR is merged and the tree is clean. If cleanup is blocked or fails, do not mark the issue `done`; record the exact blocker and leave a concrete cleanup next action. If the issue runs in the shared project workspace, do not invent isolated-worktree cleanup.
+- If Paperclip created an isolated execution workspace for the issue, leave it reusable after the PR is merged and the tree is clean. Do not archive/delete it as part of recording approval or marking the issue `done`; review, follow-up, or dependent work may still reference it. Workspace retirement is a separate board/operator action.
 - Do not configure GitHub branch protection to require approving reviews unless the project has distinct non-author GitHub reviewer credentials; all agents using one GitHub account cannot formally approve their own PRs.
 
 ## Dev Cycle Rules

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

@@ -2,6 +2,8 @@
 
 You own stall detection when you are explicitly assigned a stall-detection routine run. This is not an every-heartbeat background scan.
 
+This routine is the **periodic backstop**. Individual top-level issues should also carry a per-issue **task watchdog** (`watchdog: { agentId, instructions }` set at issue creation — see the backlog-health skill), which Paperclip fires event-driven the moment an issue's subtree stalls. When you find a stalled top-level issue here that has no watchdog, add one as part of the fix so it recovers natively next time instead of waiting for this scan.
+
 ## When To Use This Skill
 
 Use this only when the current assigned issue/routine is titled like "Stall detection" or explicitly asks you to inspect stalled work. Otherwise follow the normal Paperclip heartbeat rule: only work assigned issues and do not scan the whole board.
@@ -10,8 +12,8 @@ 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, 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). A `blocked` issue counts as validly blocked **only if at least one of its blockers is still open** (`todo`/`in_progress`/`in_review`/`blocked`). A `blocked` issue whose blockers are **all** `done`/`cancelled` (or that has no blockers at all) is NOT validly blocked — it is a stall (see *Stranded blocked* below).
+3. For each candidate, use Paperclip's liveness views before inferring from status alone: `GET /api/issues/{id}/diagnostics/blockers`, `GET /api/issues/{id}/diagnostics/wakes`, `GET /api/issues/{id}/interactions`, `GET /api/issues/{id}/approvals`, and `GET /api/issues/{id}/recovery-actions`. Inspect latest comments/activity, execution state, assigned agent status, scheduled monitor, and active run as supporting context. Use `GET /api/issues/{id}/diagnostics/subtree` for a bounded dependency chain instead of recursively walking a large tree by hand.
+4. Skip issues with an explicit waiting path: an active run or queued wake, recent activity, a usable current `executionPolicy` participant, a pending issue interaction or approval, an assigned user owner, a future scheduled monitor, or an active recovery issue. In particular, `executionPolicy: null` does **not** make an `in_review` issue stalled when a pending interaction owns the next action. A `blocked` issue is validly blocked while blocker diagnostics report unresolved blockers; diagnose the actionable leaf rather than reassigning every downstream issue.
 5. For a likely stall, leave a structured comment on the issue with:
    - issue id/title
    - assigned agent
@@ -22,32 +24,32 @@ 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)
+## In-review without an action path
 
-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.
+Paperclip classifies `in_review_without_action_path` only when an agent-owned `in_review` issue has no participant, interaction, approval, user owner, monitor, active run/queued wake, or recovery issue owning the next action. A null `executionPolicy` is only one input to that classification.
 
-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".
+1. Check the interaction, approval, wake, monitor, active-run, and recovery routes in *Stall Check*. If any path is pending, record it as `WAITING-INTERACTION`, `WAITING-APPROVAL`, or the matching owner in the routine summary and do not nudge, reassign, or change status.
+2. If every path is absent, flag the issue as `IN-REVIEW-WITHOUT-ACTION-PATH` and leave a structured comment naming the missing owner.
+3. Make the next action explicit according to the work: add the intended reviewer/interaction, return it to `in_progress` with a concrete change request and active assignee, mark it `done` if already accepted, or open a bounded recovery issue. For PR work, set non-author `executionPolicy` stages when a Code Reviewer exists; otherwise return it to the engineer for the self-merge flow.
 
 ## 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`.
+An `in_review` issue whose **first (current) executionPolicy stage lists only the issue's assignee as a participant** has an invalid review participant: Paperclip excludes the executor from every stage, so that stage cannot advance (`422 Only the active reviewer or approver can advance the current execution stage`). Common cause: a non-engineer (e.g. QA) was assigned implementation work, did it, moved the issue to `in_review`, and set itself as the first reviewer. Detect it with `GET /api/issues/{id}` (the list endpoint omits the full `executionPolicy`) and compare the current stage participants with `assigneeAgentId`. If another explicit waiting path is pending, leave it intact and defer policy repair until that path resolves.
 
 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`).
+2. When no other waiting path is pending, leave a structured comment on the issue: `in_review` whose first executionPolicy stage lists only the assignee `<agent>` as participant — author-only stage with no eligible participant (`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.
 
-## Stranded blocked (blockers done, never reactivated)
+## Dependency-ready but still blocked
 
-An issue in `blocked` whose blockers have **all** reached `done`/`cancelled` is permanently stranded: Paperclip only re-wakes a blocked issue's assignee when a blocker transitions to `done` **and** that blocker's execution workspace has recorded a successful finalize. If the wake was missed, or all blockers were already `done` when the block was set, the issue is never reactivated — and because worker agents have heartbeats disabled, the assignee never wakes on its own. The platform's liveness watchdog also skips a blocked issue once its blockers are `done`, so nothing recovers it. **This is the dominant cause of "PRs open but never merged":** the merge step is frequently modeled as a separate `blocked` "Code review and merge PR #N" issue (assigned to the Code Reviewer) that is `blockedBy` the per-role review issues; once those reviews finish (`done`), the merge issue is stranded `blocked` and the PR is never merged — even when it is green and mergeable.
+Treat `GET /api/issues/{id}/diagnostics/blockers` as authoritative. When `readiness.isDependencyReady` is false, the issue is validly blocked; inspect the unresolved leaf and its action path. When readiness is true but the issue remains `blocked`, check wake diagnostics, active-run state, recent activity, and recovery actions before intervening. A queued/claimed wake or active recovery means Paperclip already owns the transition.
 
-Detect it during the blocked scan (step 2-5): `GET /api/issues/{id}` and inspect `blockedBy` (every entry `done`/`cancelled`, or empty) — or `blockerAttention` showing `state: "needs_attention"` with `unresolvedBlockerCount: 0`.
+If `readiness.pendingFinalizeBlockerCount` is non-zero, a blocker may be `done` but still carry `workspace_finalize_pending`, so the dependency is not ready yet. A recent finalization is a valid wait. If finalization remains stale or the corresponding `issue_blockers_resolved` wake is `skipped`/`failed`, flag `WORKSPACE-FINALIZE-PENDING`, attach the blocker and wake diagnostics, and escalate the blocker/finalization failure to the CEO or board operator. Do not force the downstream issue active and do not archive/delete the blocker workspace as a workaround.
 
-1. Flag it in the routine-run summary as `STRANDED-BLOCKED`.
-2. Leave a structured comment on the issue: `blocked` with no open blockers (all blockers `done`/`cancelled`) — never reactivated; recovering.
-3. Reactivate it: `PATCH /api/issues/{id}` with `{"status":"in_progress"}` (a `blocked` issue with `executionPolicy: null` accepts this directly), then **re-assign it to the owner** (for a merge-gate issue, the Code Reviewer; otherwise the role that owns the next action) to trigger a wake, with an explicit next-action comment. For a merge-gate issue the next action is: verify the PR base, satisfy the verification gate (green CI, or paste test/build output where CI is disabled), `gh pr merge <N> --merge`, close/archive any worktree, then mark `done`.
-4. **Prefer prevention over re-stranding:** if you find a *separate* "merge PR #N" issue blocked behind review issues, do not just reactivate it in isolation — the right shape is one implementation issue carrying the PR through its `executionPolicy` stages (which auto-advance) rather than a fan-out of NULL-policy review issues plus a standalone blocked merge issue. Fold the merge back onto the implementation issue's policy where practical, and flag the fan-out pattern to the Product Owner so it stops being created.
+1. If dependency-ready with no active/queued wake or recovery action, flag it in the routine-run summary as `DEPENDENCY-READY-BUT-BLOCKED`.
+2. Leave a structured comment with blocker readiness and wake-diagnostic evidence.
+3. Reactivate it with `PATCH /api/issues/{id}` `{"status":"in_progress"}`, then assign the correct owner with an explicit next action. For a merge-gate issue, the next action is to verify the PR base and verification gate, merge, leave the execution workspace reusable, and mark `done`.
+4. **Prefer prevention:** if you find a *separate* "merge PR #N" issue blocked behind review issues, do not just reactivate it in isolation — the right shape is one implementation issue carrying the PR through its `executionPolicy` stages (which auto-advance) rather than a fan-out of null-policy review issues plus a standalone blocked merge issue. Fold the merge back onto the implementation issue's policy where practical, and flag the fan-out pattern to the Product Owner so it stops being created.
 
 ## PR-queue hygiene
 
@@ -61,7 +63,7 @@ As part of every stall-detection run, scan the repository's open PR queue for pi
 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.
-7. **Reconcile each open PR against its owning issue.** A `CLEAN`/mergeable open PR (CI green or no required CI) whose owning issue is already `done`, or whose dedicated merge issue is `blocked`/stranded, means the merge step never ran — the *exact* "open but never merged" failure. For each such PR: confirm the base is correct and the verification gate is satisfied, then merge it (`gh pr merge <N> --merge`) or route a one-line next-action to the merge owner, and reactivate the stranded merge issue per *Stranded blocked* above. Never leave a green, approved PR unmerged because its tracking issue already closed.
+7. **Reconcile each open PR against its owning issue.** A `CLEAN`/mergeable open PR (CI green or no required CI) whose owning issue is already `done`, or whose dedicated merge issue is still `blocked` despite dependency readiness, means the merge step never ran. For each such PR: confirm the base and verification gate, then merge it (`gh pr merge <N> --merge`) or route a one-line next action to the merge owner, and recover the merge issue per *Dependency-ready but still blocked* above. Never leave a green, approved PR unmerged because its tracking issue already closed.
 
 ## Rules
 
@@ -69,3 +71,4 @@ As part of every stall-detection run, scan the repository's open PR queue for pi
 - Do not interrupt running agents.
 - Do not close or cancel another agent's work unless the issue explicitly grants that authority.
 - Be specific: which issue, which agent, last activity, why stalled, and who owns the next action.
+- **Never archive or retire your own routine-run workspace.** This routine is pure control-plane work (reading and patching the board via the API) — it needs no repository state. When you finish, mark the routine issue `done` and exit. Do not call `PATCH /api/execution-workspaces/{id}` with `{"status":"archived"}`, do not check `close-readiness` to trigger a teardown, and do not otherwise remove the worktree your run is using. Archiving it mid-run makes Paperclip fail the run's workspace validation and breaks the next reuse of that workspace. Workspace retirement is a board/operator action only.

package/templates/roles/audio-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/ceo/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/ceo/role.meta.json

@@ -7,7 +7,7 @@
   "paperclipRole": "ceo",
   "description": "Strategic leader. Sets goals, delegates work, manages approvals.",
   "adapter": {
-    "model": "gpt-5.5",
+    "model": "gpt-5.6",
     "effort": "high",
     "thinkingLevel": "high"
   }

package/templates/roles/cmo/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/code-reviewer/AGENTS.md

@@ -17,7 +17,7 @@ You report to the CEO.
    - **Simplicity**: Is there unnecessary complexity? Could it be simpler?
 6. Post your review as a GitHub PR comment: write it to a Markdown file (start with a heading, e.g. `## 💬 Review notes` or `## 🔄 Changes requested`) and run `gh pr comment <number> --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext` instead of formatted Markdown. Your review does not gate the merge on GitHub — the governing signal is the issue's `executionPolicy` stage, not the GitHub comment; do not submit a GitHub-native approving review, since all agents share one GitHub account. Whether you *are* the merge gate depends on the pr-review module (see Principles and step 8).
 7. Post your verdict on the originating issue.
-8. **When the pr-review module is active**, you are the non-author merge gate: satisfy the hard verification gate — **always run and paste your own lint/test/build output** (authoritative); a green CI is an *additional* requirement only when this company runs its own CI/CD (`ci-cd` module active). A pre-existing repo check the company never configured is advisory, not a gate — never block a merge solely on it. Then merge the PR via `gh pr merge <N> --merge`, archive any isolated worktree, then record `approved` on your approval stage — the executionPolicy closes the issue to `done`. Never record `approved` before the merge has actually succeeded, and never leave the issue `done` with the PR still open. **Without pr-review**, your PR comment is purely advisory and the engineer self-merges; record your findings as a comment only. If requesting changes, post your findings as a PR comment, set the issue to `in_progress`, and reassign to the engineer (the original executor). Do not record `approved` until the concern is resolved.
+8. **When the pr-review module is active**, you are the non-author merge gate: satisfy the hard verification gate — **always run and paste your own lint/test/build output** (authoritative); a green CI is an *additional* requirement only when this company runs its own CI/CD (`ci-cd` module active). A pre-existing repo check the company never configured is advisory, not a gate — never block a merge solely on it. Then merge the PR via `gh pr merge <N> --merge`, leave any isolated execution workspace reusable, then record `approved` on your approval stage — the executionPolicy closes the issue to `done`. Never record `approved` before the merge has actually succeeded, and never leave the issue `done` with the PR still open. **Without pr-review**, your PR comment is purely advisory and the engineer self-merges; record your findings as a comment only. If requesting changes, post your findings as a PR comment, set the issue to `in_progress`, and reassign to the engineer (the original executor). Do not record `approved` until the concern is resolved.
 
 ## Principles
 

package/templates/roles/code-reviewer/HEARTBEAT.md

@@ -35,13 +35,14 @@ 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.
-- **When review/merge is complete:** If you are the merge gate (pr-review module active), record your verdict on the issue: merge the PR (`gh pr merge <number> --merge`), archive any isolated worktree if one exists, then record `approved` — this closes the issue to `done`. If you requested changes (`changes_requested`), set the issue to `in_progress`, reassign to the engineer (the `returnAssignee`), and do not record `approved`.
+- 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.
+- **When review/merge is complete:** If you are the merge gate (pr-review module active), record your verdict on the issue: merge the PR (`gh pr merge <number> --merge`), leave any isolated execution workspace reusable, then record `approved` — this closes the issue to `done`. If you requested changes (`changes_requested`), set the issue to `in_progress`, reassign to the engineer (the `returnAssignee`), and do not record `approved`.
 - **If advisory only** (pr-review module not active): leave your verdict as a PR comment; the engineer self-merges.
 
 ## 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/cto/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/cto/role.meta.json

@@ -12,7 +12,7 @@
     "Adds architecture review pass when pr-review module is active"
   ],
   "adapter": {
-    "model": "claude-opus-4-6",
+    "model": "claude-opus-4-8",
     "effort": "high",
     "thinkingLevel": "auto"
   }

package/templates/roles/customer-success/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/devops/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/engineer/AGENTS.md

@@ -16,6 +16,7 @@ You implement coding tasks end-to-end: write and edit code, debug issues, add fo
 - Make sure you know the success condition for each task. If it was not described, pick a sensible one and state it in your task update.
 - Run the smallest verification that proves the change. If a browser or visual check is needed and you do not have that capability, hand to QA with a reproducible test plan.
 - If asked to fix a bug, identify the root cause, fix the class where practical, and add coverage or guardrails where useful.
+- Keep unrelated follow-up work out of the current issue's isolated workspace. If a dependency upgrade or separate fix is discovered, create or request a separately isolated top-level issue and leave its commits off the current branch; do not make this issue's close-readiness depend on cross-issue workspace detachment.
 - Keep work moving until it is done. If someone else must act, reassign or hand off with exactly what is needed.
 
 ## Collaboration and Handoffs