@starlein/paperclip-plugin-company-wizard 0.3.24 → 0.4.1

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

@@ -4,20 +4,24 @@ When this skill is active, you work in feature branches and open PRs instead of
 
 ## Feature Branch Flow
 
-1. Pull latest main: `git pull origin main`
-2. Create branch: `git checkout -b <prefix>-<N>/<short-description>`
-3. Make your changes, commit with Conventional Commits format
-4. Push branch: `git push -u origin <branch-name>`
-5. Open PR: write the body (PR Body Template in `docs/pr-conventions.md`) to a file, then `gh pr create --title "<type>: <description>" --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal and the PR renders as `text\ntext` (see *Posting PR Bodies & Comments*).
-6. Set the originating issue's `executionPolicy` to gate the merge on review, ending with your own merge gate:
-   - One `review` stage with the **Code Reviewer** as participant (always).
-   - Additional `review` stages for any relevant domain reviewer that exists in the team (UI Designer for UI diffs, UX Researcher for flow changes, QA for logic/test-sensitive changes, DevOps for infra/deploy/dependency changes).
+1. Resolve the project/worktree base ref from the issue's `heartbeat-context` / project workspace metadata before branching. Use the configured `repoRef`, `defaultRef`, or `executionWorkspacePolicy.workspaceStrategy.baseRef` exactly as Paperclip provides it. Never guess from your shell's current branch and never rewrite the configured ref to `main`, `master`, or `origin/*`.
+2. Fetch and update the base:
+   - external: `git fetch origin`, then branch from the configured base ref
+   - local: update from the configured local branch
+3. Create branch from that base: `git checkout -b <prefix>-<N>/<short-description> <base-ref>`
+4. Make your changes, commit with Conventional Commits format
+5. Push branch: `git push -u origin <branch-name>`
+6. Open PR against the same resolved base: derive the GitHub base branch from the configured ref (for example, strip the remote prefix only when the ref is remote-tracking), write the body (PR Body Template in `docs/pr-conventions.md`) to a file, then `gh pr create --base <github-base-branch> --head <branch-name> --title "<type>: <description>" --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal and the PR renders as `text\ntext` (see *Posting PR Bodies & Comments*).
+7. Set the originating issue's `executionPolicy` to gate the merge on review, ending with your own merge gate:
+   - One `review` stage with **QA** when a QA agent exists (test adequacy / executed verification).
+   - One `review` stage with the **Security Engineer** only when the change is security-relevant (auth, secrets, input boundaries, crypto, dependencies, infra exposure).
+   - Additional `review` stages only for domain reviewers that should block this specific change. Code Reviewer and other specialists are advisory by default unless explicitly configured as participants.
    - An `approval` stage with the **Product Owner** as participant (always) — the product sign-off.
    - A final `approval` stage with **yourself (the Engineer)** as participant — the **merge gate**. This stage exists so you are woken *last*, after every reviewer and the Product Owner have cleared, to perform the merge.
    - Resolve each role to its agentId first (look up active agents), then set the policy on the issue. Include the PR link in an issue comment so reviewers can find it.
-7. Move the originating issue to `in_review`.
-8. Wait for the issue to clear its review/approval stages. Each reviewer and the Product Owner records `approved` or `changes_requested`; 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.
-9. When the issue reaches your final **merge gate** stage (you are the current participant and every prior stage is approved): run `gh pr merge <number> --merge`, confirm the merge landed, **then** record `approved` on your stage — that closes the issue to `done`. Never record `approved` before the merge has actually succeeded, and never set the issue to `done` with the PR still open.
+8. Move the originating issue to `in_review`.
+9. 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.
+10. When the issue reaches your final **merge gate** stage (you are the current participant and every prior stage is approved): run `gh pr merge <number> --merge`, confirm the merge landed into the configured project base, then close/archive the isolated execution workspace if one exists and close-readiness allows it. **Only after merge and workspace close/cleanup succeeds** record `approved` on your stage — that closes the issue to `done`. Never record `approved` before the merge has actually succeeded, and never set the issue to `done` with the PR still open or an execution workspace still active.
 
 ## Rules
 
@@ -26,6 +30,8 @@ When this skill is active, you work in feature branches and open PRs instead of
 - Always include `Closes [PREFIX-N]` in the PR body.
 - If a reviewer requests changes, address them, push to the same branch, and re-request review (the stage re-runs).
 - You are the merge owner — never ask reviewers to merge.
+- Before creating a PR or merging, verify the PR base matches the configured project/worktree base. If the base is wrong, retarget the PR before review/merge.
 - **Your merge gate must be the last stage.** 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` and you would never be woken to merge — leaving the PR open on GitHub. Always append your own merge-gate `approval` stage after the Product Owner's, and do the merge there before recording your verdict.
 - 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.
+- If Paperclip created an isolated execution workspace for this issue, do not leave it behind. Use the current execution workspace id from `heartbeat-context`, check close-readiness, and archive it after the PR is merged and the tree is clean. If archive/cleanup is blocked, leave the issue `blocked` or `in_review` with the exact cleanup blocker instead of marking `done`. If this issue runs in the shared project workspace, do not invent isolated-worktree cleanup.

package/templates/modules/pr-review/agents/product-owner/skills/product-review.md

@@ -14,7 +14,7 @@ You review PRs for intent alignment, scope discipline, and acceptance criteria.
 ## How to Review
 
 1. When you are the active participant of the approval stage on an issue with a PR link, review the PR against the originating issue.
-2. Record your verdict on your approval stage:
+2. Record your verdict through the normal issue update route for your approval stage:
    - **approved** if the change meets product requirements
    - **changes_requested** with specific feedback tied to acceptance criteria
 3. Optionally mirror the verdict as a GitHub PR comment — write it to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.

package/templates/modules/pr-review/agents/qa/skills/qa-review.md

@@ -38,7 +38,7 @@ Record `approved` only if the suite and build pass and coverage is adequate; oth
 ## How to record your verdict
 
 1. You are the active participant of a `review` stage on the issue carrying the PR link.
-2. Record on your stage: `approved` (with the evidence — commands + results) or `changes_requested` (with specific gaps and suggested test cases).
+2. Record on your stage through the normal issue update route: `approved` (with the evidence — commands + results) by PATCHing toward `done`, or `changes_requested` (with specific gaps and suggested test cases) by PATCHing back to `in_progress`.
 3. Optionally mirror the verdict as a GitHub PR comment via a Markdown file: open with a heading (`## ✅ Approved` / `## 🔄 Changes requested`), then details, and run `gh pr comment <number> --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
 
 ## Rules

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

@@ -17,7 +17,7 @@ Review is by *probing*, not by reading. Your verdict must state what you actuall
 
 1. You are the active participant of a `review` stage on the issue carrying the PR link.
 2. State **what you probed and how** (e.g. "checked the new `/upload` endpoint for path traversal with `../` inputs; validated the content-type allowlist"). A verdict without concrete checks is invalid.
-3. Record `approved` (with the checks performed) or `changes_requested` (with the specific finding, its impact, and a remediation).
+3. Record the stage decision through the normal issue update route: `approved` by PATCHing the issue toward `done` with the checks performed, or `changes_requested` by PATCHing back to `in_progress` with the specific finding, impact, and remediation.
 4. Optionally mirror as a GitHub PR comment via a Markdown file (`## ✅ Approved` / `## 🔄 Changes requested`), run `gh pr comment <number> --body-file <file>`. Never inline `--body "..."`. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
 
 ## Rules

package/templates/modules/pr-review/agents/ui-designer/skills/design-review.md

@@ -16,7 +16,7 @@ You review PRs for visual quality, brand consistency, and accessibility. When a
 
 1. When you are the active participant of a review stage on an issue with a PR link, review the PR.
 2. Focus only on visual/design concerns — leave code logic to Code Reviewer and product scope to Product Owner.
-3. Record your verdict on your review stage:
+3. Record your verdict through the normal issue update route for your review stage:
    - **approved** if visually sound
    - **changes_requested** with specific, actionable feedback if not
 4. Optionally mirror the verdict as a GitHub PR comment — write it to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.

package/templates/modules/pr-review/agents/ux-researcher/skills/ux-review.md

@@ -16,7 +16,7 @@ You review PRs for usability, user flow integrity, and alignment with user needs
 
 1. When you are the active participant of a review stage on an issue with a PR link, review the PR.
 2. Focus only on UX and usability concerns — leave code logic to Code Reviewer and visuals to UI Designer.
-3. Record your verdict on your review stage:
+3. Record your verdict through the normal issue update route for your review stage:
    - **approved** if usability is sound
    - **changes_requested** with specific, actionable feedback if not
 4. Optionally mirror the verdict as a GitHub PR comment — write it to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.

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

@@ -63,19 +63,20 @@ Apply one primary label: `feature`, `bug`, `docs`, `chore`, `infra`, `agent`.
 
 Review runs through the issue's native `executionPolicy` (stages), not separate child issues. The gate is **executed verification, not opinion**.
 
-1. **Engineer** opens the PR on GitHub and adds the PR link as an issue comment.
-2. **Engineer** sets the originating issue's `executionPolicy` stages, in order:
+1. **Engineer** resolves the project/worktree base ref before branching from `heartbeat-context` / project workspace metadata. Use the configured `repoRef`, `defaultRef`, or `executionWorkspacePolicy.workspaceStrategy.baseRef` exactly as Paperclip provides it. PRs must target the corresponding GitHub base and must not silently target the wrong branch.
+2. **Engineer** opens the PR on GitHub and adds the PR link as an issue comment.
+3. **Engineer** sets the originating issue's `executionPolicy` stages, in order:
    - a `review` stage for **QA** when a QA agent is on the team (test adequacy / running the tests),
    - a `review` stage for the **Security Engineer** *only when the change is security-relevant* (auth, secrets, input boundaries, crypto, dependencies, infra exposure),
    - an `approval` stage for the **Product Owner** (intent, scope, acceptance),
    - a final `approval` stage for the **Engineer** as the merge gate.
    Resolve each role to its agentId.
-3. **Engineer** sets the issue to `in_review`.
-4. **QA** (when present) reviews and records `approved`/`changes_requested` with executed evidence (see *Merge Rules*).
-5. **Security Engineer** (when present as a stage) probes the security-relevant change and records a verdict stating what was checked.
-6. **Code Reviewer** and other domain reviewers may add **advisory, non-blocking** PR comments. They do not gate the merge.
-7. **Product Owner** reviews for intent match, scope discipline, and acceptance criteria, and records the `approval` verdict.
-8. **Engineer** owns the final `approval` stage (merge gate): once reviewers and the Product Owner have approved, the engineer satisfies the hard gate (CI green, or runs the tests/build and pastes the output), merges the PR, confirms the merge landed, and only then records `approved` — which closes the issue to `done`. The merge must happen before the issue is `done`.
+4. **Engineer** sets the issue to `in_review`.
+5. **QA** (when present) reviews and records `approved`/`changes_requested` through the normal issue update route with executed evidence (see *Merge Rules*), preserving the issue-level review audit trail.
+6. **Security Engineer** (when present as a stage) probes the security-relevant change and records a verdict stating what was checked.
+7. **Code Reviewer** and 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. **Engineer** owns the final `approval` stage (merge gate): once reviewers and the Product Owner have approved, the engineer 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`.
 
 ## Review Roles
 
@@ -97,8 +98,10 @@ The hard gate is **executed verification**, enforced on the Engineer's merge-gat
 - The Code Reviewer and other domain reviewers are advisory — blocking only when they escalate a concern that QA, the Security Engineer, or the Engineer then acts on.
 - No force pushes.
 - Merge using `gh pr merge <number> --merge`.
+- Before merge, verify the PR base matches the configured project/worktree base from `heartbeat-context`. Retarget before review/merge if needed.
 - The Engineer is the merge owner — reviewers never merge.
 - The engineer's merge gate must be the **last** `approval` stage. 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.
+- 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.
 - 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/README.md

@@ -1,27 +1,27 @@
 # Module: stall-detection
 
-Adds periodic stall detection to the CEO heartbeat.
+Adds scheduled stall detection as an assigned routine run.
 
 ## What it adds
 
-- **CEO skill**: Stall check — detects issues stuck in `in_progress` or `in_review` for too long, and nudges the responsible agent or escalates.
+- **CEO skill**: Stall check — detects issues stuck in `in_progress` or `in_review` for too long, then records a structured next action, reassignment, blocker, or escalation.
 
 ## How it works
 
-On every heartbeat, the CEO checks:
+When the CEO is assigned a stall-detection routine run:
 1. Are there issues in `in_progress` or `in_review` that haven't been updated recently?
 2. If an issue appears stalled (no activity for a configurable period):
    - Check if the assigned agent is running or idle
-   - If idle: @-mention the agent on the issue to re-trigger
-   - If the agent has been nudged before without response: escalate to the board
-3. This catches failed handovers where an @-mention didn't trigger a wake.
+   - If idle: leave a structured next-action comment, reassign, or link a blocker as appropriate
+   - If the agent has already failed to respond: escalate to the board/CEO with exact evidence
+3. This catches dropped handoffs without relying on generic mentions.
 
 ## Best for
 
-- Any team using @-mention-based handover (which can be unreliable)
+- Any team with multi-stage handoffs where ownership can become unclear
 - Multi-agent teams where work can get dropped between agents
 - Ensuring nothing falls through the cracks
 
 ## Example
 
-An engineer finishes a PR and @-mentions the Code Reviewer, but the mention doesn't trigger a wake. The CEO detects the stalled issue on the next heartbeat and re-mentions the reviewer or escalates.
+An engineer finishes a PR and moves the issue to `in_review`, but the executionPolicy reviewer never acts. The CEO detects the stalled issue during the scheduled routine run, records the missing next action, and reassigns or escalates.

package/templates/modules/stall-detection/agents/ceo/heartbeat-section.md

@@ -1,12 +1,3 @@
-## Stall Detection Check
+## Stall Detection Routine
 
-After handling assignments and before exit:
-
-1. Query active issues: `GET /api/companies/{companyId}/issues?status=in_progress,in_review`
-2. For each issue, check the latest comment/activity timestamp.
-3. If an issue has had no activity for more than 2 heartbeat cycles:
-   - Agent is `idle` → @-mention with a nudge.
-   - Agent is `running` → skip (may be mid-work).
-   - Agent is `error` or `paused` → escalate to the board.
-4. If already nudged and still no progress → escalate to the board.
-5. Record stall findings in daily notes.
+Do not scan for stalled work during a normal heartbeat. When you are assigned a routine-run issue titled like "Stall detection", use `skills/stall-detection.md`, then summarize findings on the routine issue and exit.

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

@@ -1,21 +1,30 @@
 # Skill: Stall Detection
 
-Add this check to your heartbeat, after handling assignments and before exit.
+You own stall detection when you are explicitly assigned a stall-detection routine run. This is not an every-heartbeat background 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.
 
 ## Stall Check
 
-1. Query active issues: `GET /api/companies/{companyId}/issues?status=in_progress,in_review`
-2. For each issue, check the latest comment/activity timestamp.
-3. If an issue has had no activity for more than 2 heartbeat cycles:
-   - Check the assigned agent's status via `GET /api/agents/{agentId}`
-   - If agent is `idle`: @-mention them on the issue with a nudge: "This issue appears stalled. Please check and continue or report blockers."
-   - If agent is `running`: skip — they may be working on it now.
-   - If agent is `error` or `paused`: escalate to the board with a comment.
-4. If you've already nudged an agent on the same issue in a previous heartbeat and there's still no progress: escalate to the board.
-5. Record stall findings in your daily notes.
+1. Checkout the assigned routine-run issue.
+2. Query active issues for the relevant company/project: `todo`, `in_progress`, `in_review`, and blocked work where applicable.
+3. For each candidate, inspect latest comments/activity, execution state, blockers, approval/review state, and assigned agent status.
+4. Skip issues with an active run, recent activity, valid `blockedByIssueIds`, or pending executionPolicy approval/review.
+5. For a likely stall, leave a structured comment on the issue with:
+   - issue id/title
+   - assigned agent
+   - last activity timestamp/context
+   - why it appears stalled
+   - exact next action requested
+6. Prefer reassignment, blocker linkage, or escalation to CEO/Product Owner over informal nudges.
+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.
 
 ## Rules
 
-- Don't nudge agents that are currently running — they may be mid-work.
-- Only escalate after one failed nudge attempt.
-- When escalating, be specific: which issue, which agent, how long stalled, what was the last activity.
+- Do not @-mention as a generic nudge; use assignment, status, blockers, and explicit next-action comments.
+- 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.

package/templates/modules/stall-detection/module.meta.json

@@ -5,7 +5,7 @@
   "routines": [
     {
       "title": "Stall detection",
-      "description": "Check all in_progress issues for signs of stalling. Nudge assigned agents, escalate if blocked for >24h.",
+      "description": "Routine-run checklist: inspect in_progress/in_review issues for stale activity, verify blockers and executionPolicy gates, record a concrete next action/reassignment/escalation on each stalled issue, summarize on the routine issue, then exit.",
       "assignTo": "ceo",
       "schedule": "0 */3 * * *",
       "priority": "medium",

package/templates/modules/triage/skills/issue-triage.md

@@ -1,42 +1,29 @@
 # Skill: Issue Triage
 
-You are responsible for processing inbound GitHub issues — classifying, responding, and converting them into actionable work.
+You are responsible for processing inbound GitHub issues when assigned a triage issue or triage routine. Classify, respond, and convert actionable reports into Paperclip work.
 
-## Triage Process
+## When To Use This Skill
 
-Run this on every heartbeat, after handling your own assignments.
+Use this only when the current assigned issue/routine asks for GitHub issue triage. Do not scan GitHub on every normal heartbeat.
 
-1. **Fetch new issues** — `gh issue list --state open --label "" --json number,title,body,labels,createdAt` to find untriaged issues (no classification label yet).
-2. **For each untriaged issue:**
-   a. Read the full issue body and any comments.
-   b. **Classify** by type:
-      - `bug` — Something is broken or behaves unexpectedly
-      - `feature` — New functionality request
-      - `enhancement` — Improvement to existing functionality
-      - `question` — User needs help or clarification
-      - `duplicate` — Already reported (link to original)
-      - `invalid` — Not actionable, out of scope, or spam
-   c. **Set priority** (P0–P3):
-      - P0: Production broken, data loss, security vulnerability
-      - P1: Major feature broken, blocking multiple users
-      - P2: Non-critical bug or important feature request
-      - P3: Minor issue, cosmetic, nice-to-have
-   d. **Apply labels** — `gh issue edit <number> --add-label "<type>,<priority>"`
-   e. **Respond to reporter:**
-      - Acknowledge the report
-      - Ask follow-up questions if reproduction steps are unclear (bugs)
-      - Set expectations ("we'll look into this" / "this is out of scope because...")
-      - For duplicates: link to the original issue and close
-      - For invalid: explain why and close politely
-   f. **Convert to Paperclip task** — For actionable issues (bug, feature, enhancement), create a corresponding issue in Paperclip via `POST /api/companies/{companyId}/issues` with the GitHub issue number in the description for traceability. Include the active `projectId` (and `goalId` / `parentId` when applicable).
+## Triage Process
 
-3. **Record** what you triaged in your daily notes.
+1. Checkout the assigned triage issue/routine.
+2. Fetch new issues: `gh issue list --state open --label "" --json number,title,body,labels,createdAt` to find untriaged issues (no classification label yet).
+3. For each untriaged issue:
+   - Read the full issue body and comments.
+   - Classify by type: `bug`, `feature`, `enhancement`, `question`, `duplicate`, `invalid`.
+   - Set priority P0-P3; P0 maps to urgent Paperclip priority.
+   - Apply labels with `gh issue edit <number> --add-label "<type>,<priority>"`.
+   - Respond to the reporter with acknowledgement, follow-up questions, or a polite close reason.
+   - For actionable issues, create a corresponding Paperclip issue via `POST /api/companies/{companyId}/issues`. Include GitHub issue URL/number, active `projectId`, and `goalId` / `parentId` when applicable.
+4. Link bidirectionally: GitHub comment references the Paperclip issue, Paperclip issue references GitHub.
+5. Summarize triage results on the assigned triage issue/routine and mark it done.
 
 ## Rules
 
-- Respond to every issue. No issue should sit without acknowledgment for more than one heartbeat cycle.
-- Be respectful and constructive in responses, even for invalid or duplicate issues.
-- Don't close legitimate issues without explanation. Always comment before closing.
-- Link GitHub issues to Paperclip tasks bidirectionally — include the GitHub URL in the Paperclip issue and the Paperclip task reference in a GitHub comment.
-- If you can't classify an issue (ambiguous report), ask the reporter for clarification and label as `needs-info`.
-- Escalate P0 issues immediately — create the Paperclip task with priority `urgent` and mention it in the CEO's daily notes.
+- Do not triage from unrelated heartbeats.
+- Respond respectfully and constructively, even for invalid or duplicate reports.
+- Do not close legitimate issues without explanation.
+- If you cannot classify an issue, ask for clarification and label `needs-info`.
+- Escalate P0 issues immediately via Paperclip issue assignment/status and a CEO/Product Owner comment.

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

@@ -1,37 +1,53 @@
-# HEARTBEAT.md -- Audio Designer Heartbeat
+# HEARTBEAT.md -- Audio Designer Heartbeat Checklist
 
-## 1. Identity and Context
+Run this checklist on every heartbeat. The Paperclip skill is the source of truth for board coordination; this file records the current expected flow and role-local reminders.
 
-- `GET /api/agents/me` -- confirm your id, role, companyId.
-- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`.
+## 1. Identity and Wake Context
 
-## 2. Get Assignments
+- `GET /api/agents/me` -- confirm your id, role, companyId, budget, and chain of command.
+- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`, `PAPERCLIP_APPROVAL_ID`.
+- If the wake reason is approval/review/routine, treat that object as the active assignment.
 
-- `GET /api/companies/{companyId}/issues?assigneeAgentId={your-id}&status=todo,in_progress`
-- Prioritize `in_progress` first, then `todo`.
+## 2. Get Assigned Work
 
-## 3. Checkout and Work
+- Prefer `GET /api/agents/me/inbox-lite` for your actionable inbox.
+- If `PAPERCLIP_TASK_ID` is set and belongs to you, prioritize it.
+- Otherwise work assigned issues only. Never look for random unassigned work during a normal heartbeat.
+- Include `todo`, `in_progress`, `in_review`, and review/approval tasks surfaced by the inbox. Skip blocked work unless you can unblock it.
 
-- Always checkout before working: `POST /api/issues/{id}/checkout`.
-- Never retry a 409 -- that task belongs to someone else.
-- Do the work. Update status and comment when done.
-- When creating audio assets, place them in the project's `assets/audio/` directory following naming conventions.
+## 3. Load Execution Context
 
-## 4. Handover
+- For the chosen issue, call `GET /api/issues/{id}/heartbeat-context` before changing state.
+- Inspect status, parent/children, project/goal, labels, comments, documents, work products, `blockedByIssueIds`, `executionPolicy`, and current execution state.
+- Respect pause/cancel, budget, sandbox, and approval gates. Do not bypass executionPolicy review or approval stages.
 
-- When audio assets are ready for integration, @-mention the Engineer on the issue.
-- Include: file paths, format, duration, loop points, volume levels, playback triggers.
-- Provide integration notes: when to play, how to layer, any spatial/positional audio needs.
+## 4. Checkout and Work
 
-## 5. Exit
+- Checkout before mutating work: `POST /api/issues/{id}/checkout` with the expected current status when the API supports `expectedStatuses`.
+- Never retry a 409; that issue belongs to another active run.
+- Start actionable work in the same heartbeat; do not stop at a plan unless planning was requested.
+- Leave durable progress with a clear next action. Use child issues for long or parallel delegated work instead of polling.
+- Mark true dependencies with `blockedByIssueIds` instead of free-text blockers.
 
-- Comment on any in_progress work before exiting.
-- If no assignments, exit cleanly.
+## 5. Evidence, Work Products, and Handover
+
+- Record real verification: commands, test results, screenshots, reviewed artifacts, or explicit "not run" rationale.
+- 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.
+
+## 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.
+- If no assigned work, valid approval/review, or routine-run exists, exit cleanly without scanning unrelated unassigned work.
 
 ## Rules
 
 - Always use the Paperclip skill for coordination.
-- Always include `X-Paperclip-Run-Id` header on mutating API calls.
-- Your output is audio assets and audio specifications. Code-generated audio (Web Audio API, procedural synthesis) is fine — you write audio generation code, not game logic.
+- Always include `X-Paperclip-Run-Id` on mutating API calls when available.
+- Keep comments concise markdown: status line + bullets + links.
+- Never expose secrets, credentials, private customer data, or hidden chain-of-thought in comments or artifacts.
 
 <!-- Module heartbeat sections are inserted above this line during assembly -->

package/templates/roles/ceo/HEARTBEAT.md

@@ -1,75 +1,53 @@
-# HEARTBEAT.md -- CEO Heartbeat Checklist
+# HEARTBEAT.md -- Ceo Heartbeat Checklist
 
-Run this checklist on every heartbeat. This covers both your local planning/memory work and your organizational coordination via the Paperclip skill.
+Run this checklist on every heartbeat. The Paperclip skill is the source of truth for board coordination; this file records the current expected flow and role-local reminders.
 
-## 1. Identity and Context
+## 1. Identity and Wake Context
 
-- `GET /api/agents/me` -- confirm your id, role, budget, chainOfCommand.
-- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`.
+- `GET /api/agents/me` -- confirm your id, role, companyId, budget, and chain of command.
+- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`, `PAPERCLIP_APPROVAL_ID`.
+- If the wake reason is approval/review/routine, treat that object as the active assignment.
 
-## 2. Local Planning Check
+## 2. Get Assigned Work
 
-1. Read today's plan from `$AGENT_HOME/memory/YYYY-MM-DD.md` under "## Today's Plan".
-2. Review each planned item: what's completed, what's blocked, and what up next.
-3. For any blockers, resolve them yourself or escalate to the board.
-4. If you're ahead, start on the next highest priority.
-5. **Record progress updates** in the daily notes.
+- Prefer `GET /api/agents/me/inbox-lite` for your actionable inbox.
+- If `PAPERCLIP_TASK_ID` is set and belongs to you, prioritize it.
+- Otherwise work assigned issues only. Never look for random unassigned work during a normal heartbeat.
+- Include `todo`, `in_progress`, `in_review`, and review/approval tasks surfaced by the inbox. Skip blocked work unless you can unblock it.
 
-## 3. Approval Follow-Up
+## 3. Load Execution Context
 
-If `PAPERCLIP_APPROVAL_ID` is set:
+- For the chosen issue, call `GET /api/issues/{id}/heartbeat-context` before changing state.
+- Inspect status, parent/children, project/goal, labels, comments, documents, work products, `blockedByIssueIds`, `executionPolicy`, and current execution state.
+- Respect pause/cancel, budget, sandbox, and approval gates. Do not bypass executionPolicy review or approval stages.
 
-- Review the approval and its linked issues.
-- Close resolved issues or comment on what remains open.
+## 4. Checkout and Work
 
-## 4. Get Assignments
+- Checkout before mutating work: `POST /api/issues/{id}/checkout` with the expected current status when the API supports `expectedStatuses`.
+- Never retry a 409; that issue belongs to another active run.
+- Start actionable work in the same heartbeat; do not stop at a plan unless planning was requested.
+- Leave durable progress with a clear next action. Use child issues for long or parallel delegated work instead of polling.
+- Mark true dependencies with `blockedByIssueIds` instead of free-text blockers.
 
-- `GET /api/companies/{companyId}/issues?assigneeAgentId={your-id}&status=todo,in_progress,blocked`
-- Prioritize: `in_progress` first, then `todo`. Skip `blocked` unless you can unblock it.
-- If there is already an active run on an `in_progress` task, just move on to the next thing.
-- If `PAPERCLIP_TASK_ID` is set and assigned to you, prioritize that task.
+## 5. Evidence, Work Products, and Handover
 
-## 5. Checkout and Work
+- Record real verification: commands, test results, screenshots, reviewed artifacts, or explicit "not run" rationale.
+- 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.
 
-- Always checkout before working: `POST /api/issues/{id}/checkout`.
-- Never retry a 409 -- that task belongs to someone else.
-- Do the work. Update status and comment when done.
+## 6. Exit
 
-## 6. Delegation
-
-- Create subtasks with `POST /api/companies/{companyId}/issues`. Always set `parentId`, `projectId`, and `goalId`. For top-level follow-ons, include the active project's `projectId` explicitly.
-- Create subissues only for independent work slices; avoid splitting tightly coupled implementation across sibling subissues.
-- Use `paperclip-create-agent` skill when hiring new agents.
-- Assign work to the right agent for the job.
-
-## 7. Fact Extraction
-
-1. Check for new conversations since last extraction.
-2. Extract durable facts to the relevant entity in `$AGENT_HOME/life/` (PARA).
-3. Update `$AGENT_HOME/memory/YYYY-MM-DD.md` with timeline entries.
-4. Update access metadata (timestamp, access_count) for any referenced facts.
-
-## 8. Exit
-
-- Comment on any in_progress work before exiting.
-- If no assignments and no valid mention-handoff, exit cleanly.
-
----
-
-## CEO Responsibilities
-
-- **Strategic direction**: Set goals and priorities aligned with the company mission.
-- **Hiring**: Spin up new agents when capacity is needed.
-- **Unblocking**: Escalate or resolve blockers for reports.
-- **Budget awareness**: Above 80% spend, focus only on critical tasks.
-- **Never look for unassigned work** -- only work on what is assigned to you.
-- **Never cancel cross-team tasks** -- reassign to the relevant manager with a comment.
+- 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.
+- If no assigned work, valid approval/review, or routine-run exists, exit cleanly without scanning unrelated unassigned work.
 
 ## Rules
 
 - Always use the Paperclip skill for coordination.
-- Always include `X-Paperclip-Run-Id` header on mutating API calls.
-- Comment in concise markdown: status line + bullets + links.
-- Self-assign via checkout only when explicitly @-mentioned.
+- Always include `X-Paperclip-Run-Id` on mutating API calls when available.
+- Keep comments concise markdown: status line + bullets + links.
+- Never expose secrets, credentials, private customer data, or hidden chain-of-thought in comments or artifacts.
 
 <!-- Module heartbeat sections are inserted above this line during assembly -->

package/templates/roles/cmo/HEARTBEAT.md

@@ -1,37 +1,53 @@
-# HEARTBEAT.md -- Chief Marketing Officer Heartbeat
+# HEARTBEAT.md -- Cmo Heartbeat Checklist
 
-## 1. Identity and Context
+Run this checklist on every heartbeat. The Paperclip skill is the source of truth for board coordination; this file records the current expected flow and role-local reminders.
 
-- `GET /api/agents/me` -- confirm your id, role, companyId.
-- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`.
+## 1. Identity and Wake Context
 
-## 2. Get Assignments
+- `GET /api/agents/me` -- confirm your id, role, companyId, budget, and chain of command.
+- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`, `PAPERCLIP_APPROVAL_ID`.
+- If the wake reason is approval/review/routine, treat that object as the active assignment.
 
-- `GET /api/companies/{companyId}/issues?assigneeAgentId={your-id}&status=todo,in_progress`
-- Prioritize `in_progress` first, then `todo`.
+## 2. Get Assigned Work
 
-## 3. Checkout and Work
+- Prefer `GET /api/agents/me/inbox-lite` for your actionable inbox.
+- If `PAPERCLIP_TASK_ID` is set and belongs to you, prioritize it.
+- Otherwise work assigned issues only. Never look for random unassigned work during a normal heartbeat.
+- Include `todo`, `in_progress`, `in_review`, and review/approval tasks surfaced by the inbox. Skip blocked work unless you can unblock it.
 
-- Always checkout before working: `POST /api/issues/{id}/checkout`.
-- Never retry a 409 -- that task belongs to someone else.
-- Do the work. Update status and comment when done.
-- When producing marketing deliverables, write them as markdown documents in the project workspace.
+## 3. Load Execution Context
 
-## 4. Handover
+- For the chosen issue, call `GET /api/issues/{id}/heartbeat-context` before changing state.
+- Inspect status, parent/children, project/goal, labels, comments, documents, work products, `blockedByIssueIds`, `executionPolicy`, and current execution state.
+- Respect pause/cancel, budget, sandbox, and approval gates. Do not bypass executionPolicy review or approval stages.
 
-- When marketing strategy or analysis is ready for review, @-mention the CEO on the issue.
-- Include links to deliverable files in your comment.
-- Update issue status appropriately.
+## 4. Checkout and Work
 
-## 5. Exit
+- Checkout before mutating work: `POST /api/issues/{id}/checkout` with the expected current status when the API supports `expectedStatuses`.
+- Never retry a 409; that issue belongs to another active run.
+- Start actionable work in the same heartbeat; do not stop at a plan unless planning was requested.
+- Leave durable progress with a clear next action. Use child issues for long or parallel delegated work instead of polling.
+- Mark true dependencies with `blockedByIssueIds` instead of free-text blockers.
 
-- Comment on any in_progress work before exiting.
-- If no assignments, exit cleanly.
+## 5. Evidence, Work Products, and Handover
+
+- Record real verification: commands, test results, screenshots, reviewed artifacts, or explicit "not run" rationale.
+- 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.
+
+## 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.
+- If no assigned work, valid approval/review, or routine-run exists, exit cleanly without scanning unrelated unassigned work.
 
 ## Rules
 
 - Always use the Paperclip skill for coordination.
-- Always include `X-Paperclip-Run-Id` header on mutating API calls.
-- Never commit to external spending or partnerships without board approval.
+- Always include `X-Paperclip-Run-Id` on mutating API calls when available.
+- Keep comments concise markdown: status line + bullets + links.
+- Never expose secrets, credentials, private customer data, or hidden chain-of-thought in comments or artifacts.
 
 <!-- Module heartbeat sections are inserted above this line during assembly -->