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

package/templates/modules/user-testing/agents/ux-researcher/skills/user-testing.fallback.md

@@ -4,10 +4,10 @@ The QA engineer primarily owns test strategy and usability validation. You are t
 
 ## User Testing (Fallback)
 
-1. If no `../../docs/USER-TESTING.md` exists and QA hasn't started:
+1. If no `docs/USER-TESTING.md` exists and QA hasn't started:
    - Design test scenarios covering critical user flows from a user-centered perspective
    - Conduct heuristic evaluation against usability principles
-   - Document findings in `../../docs/USER-TESTING.md`
+   - Document findings in `docs/USER-TESTING.md`
    - Focus on user experience quality — task flows, cognitive load, error recovery
 2. If QA is active, skip this entirely.
 

package/templates/modules/user-testing/module.meta.json

@@ -17,7 +17,7 @@
     {
       "title": "Design and execute initial usability evaluation",
       "assignTo": "capability:user-testing",
-      "description": "Define test scenarios based on the company goal, identify target user personas, create a test plan, execute evaluations, and document findings in ../../docs/USER-TESTING.md."
+      "description": "Define test scenarios based on the company goal, identify target user personas, create a test plan, execute evaluations, and document findings in docs/USER-TESTING.md."
     }
   ]
 }

package/templates/modules/user-testing/skills/user-testing.md

@@ -7,7 +7,7 @@ You own usability evaluations and user testing. This ensures the product meets r
 1. Review the company goal, product description, and user personas
 2. Design test scenarios covering critical user flows
 3. Define success metrics for each scenario (task completion, error rate, time-on-task)
-4. Execute evaluations and document in `../../docs/USER-TESTING.md`:
+4. Execute evaluations and document in `docs/USER-TESTING.md`:
    - **Heuristic analysis**: Apply usability heuristics to key screens and flows
    - **Task flow evaluation**: Walk through core tasks as target personas would
    - **Accessibility review**: Check against basic accessibility standards (contrast, keyboard nav, screen reader)
@@ -16,7 +16,7 @@ You own usability evaluations and user testing. This ensures the product meets r
    - **Major**: Significant friction or confusion
    - **Minor**: Cosmetic or low-impact usability issues
 6. Create follow-up issues for critical and major findings:
-   - `POST /api/companies/{companyId}/issues` with finding details and reproduction steps. Include the active `projectId` (and `goalId` / `parentId` when applicable). For top-level issues (no `parentId`), also include `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so each gets its own worktree; subissues set `parentId` and omit it.
+   - `POST /api/companies/{companyId}/issues` with finding details and reproduction steps. Include `projectId` plus `goalId` / `parentId` when applicable, and set `executionWorkspaceSettings: { "mode": "isolated_workspace" }` for top-level repository implementation issues and subissues when the instance feature, project policy, and initialized repository support isolation. Otherwise follow the rendered project policy and avoid concurrent shared-checkout writes. Reuse only when explicitly required via `inheritExecutionWorkspaceFromIssueId`; keep API-only work project-detached.
 7. Record summary in your daily notes
 
 ## Rules

package/templates/modules/vision-workshop/agents/ceo/skills/vision-workshop.md

@@ -5,14 +5,14 @@ You own the company vision. Refine the initial goal into a strategic foundation
 ## Vision Workshop Process
 
 1. Review the company goal and any existing context (market analysis, team composition)
-2. Define and document in `../../docs/VISION.md`:
+2. Define and document in `docs/VISION.md`:
    - **Vision statement**: One sentence describing the desired future state
    - **Mission**: How the company achieves that vision
    - **Success metrics**: 3-5 measurable KPIs with target values and timeframes
    - **Strategic milestones**: Ordered list of milestones that lead to the vision
    - **Non-goals**: What the company explicitly does NOT do (prevents scope creep)
 3. Create issues for the first milestone's deliverables:
-   - `POST /api/companies/{companyId}/issues` with milestone context. Include the active `projectId` (and `goalId` / `parentId` when applicable). For top-level issues (no `parentId`), also include `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so each gets its own worktree; subissues set `parentId` and omit it.
+   - `POST /api/companies/{companyId}/issues` with milestone context. Include `projectId` plus `goalId` / `parentId` when applicable, and set `executionWorkspaceSettings: { "mode": "isolated_workspace" }` for top-level repository implementation issues and subissues when the instance feature, project policy, and initialized repository support isolation. Otherwise follow the rendered project policy and avoid concurrent shared-checkout writes. Reuse only when explicitly required via `inheritExecutionWorkspaceFromIssueId`; keep API-only work project-detached.
 4. Share the vision doc with the team via daily notes
 
 ## Rules

package/templates/modules/vision-workshop/agents/ux-researcher/skills/vision-workshop.md

@@ -10,7 +10,7 @@ Coordinate with the CEO on the vision by providing:
 - **Metrics reality check**: Propose user-centered KPIs (retention, task completion, satisfaction)
 - **Non-goals validation**: Are we correctly excluding things users don't need?
 
-Document your research inputs in `../../docs/VISION.md` under a `## User Research Inputs` section.
+Document your research inputs in `docs/VISION.md` under a `## User Research Inputs` section.
 
 ## Rules
 

package/templates/modules/vision-workshop/module.meta.json

@@ -6,7 +6,7 @@
     {
       "title": "Define company vision, success metrics, and strategic milestones",
       "assignTo": "ceo",
-      "description": "Refine the company goal into a clear vision statement, define measurable success metrics, and establish strategic milestones. Document in ../../docs/VISION.md. This becomes the north star for all downstream planning."
+      "description": "Refine the company goal into a clear vision statement, define measurable success metrics, and establish strategic milestones. Document in docs/VISION.md. This becomes the north star for all downstream planning."
     }
   ]
 }

package/templates/modules/website-relaunch/agents/ui-designer/skills/site-audit.md

@@ -54,7 +54,7 @@ Note which visual patterns from the current site should be preserved vs. replace
 
 ## Output
 
-Write the complete audit to `../../docs/SITE-AUDIT.md` with sections:
+Write the complete audit to `docs/SITE-AUDIT.md` with sections:
 1. Page Inventory (table of all URLs with page type and status)
 2. Visual Design Patterns (current color palette, typography, component library)
 3. Content Assessment (quality, structure, and brand voice per page)

package/templates/modules/website-relaunch/module.meta.json

@@ -28,25 +28,25 @@
   "issues": [
     {
       "title": "Technical site audit",
-      "description": "Crawl the current website and document the technical baseline:\n- Complete page inventory (every URL, status codes)\n- Navigation structure and sitemap\n- Content types per page (text, images, videos, downloads)\n- Tech stack and hosting (framework, CMS, CDN, response headers)\n- SEO baseline (meta tags, structured data, canonical URLs, robots.txt, sitemap.xml)\n- Analytics and tracking scripts\n- Performance baseline (page weight, render-blocking resources)\n\nUse WebFetch or Chrome to access each page. Output: `../../docs/SITE-AUDIT.md`.",
+      "description": "Crawl the current website and document the technical baseline:\n- Complete page inventory (every URL, status codes)\n- Navigation structure and sitemap\n- Content types per page (text, images, videos, downloads)\n- Tech stack and hosting (framework, CMS, CDN, response headers)\n- SEO baseline (meta tags, structured data, canonical URLs, robots.txt, sitemap.xml)\n- Analytics and tracking scripts\n- Performance baseline (page weight, render-blocking resources)\n\nUse WebFetch or Chrome to access each page. Output: `docs/SITE-AUDIT.md`.",
       "priority": "high",
       "assignTo": "engineer"
     },
     {
       "title": "Visual and UX audit of current website",
-      "description": "Audit the current website from a design and user experience perspective. Use Chrome to browse the site visually. Follow the `site-audit` skill.\n\nFor each page type, document:\n- **Layout patterns** — grid structure, content zones, visual hierarchy\n- **Design tokens in use** — colors, typography, spacing, component patterns\n- **Content quality** — is copy clear, current, and on-brand? Flag outdated or placeholder content\n- **UX observations** — navigation intuitiveness, user flows, friction points, dead ends\n- **Accessibility** — heading hierarchy, image alt text, color contrast (visual estimate)\n\nFor each page, recommend: **keep** (design is strong), **redesign** (layout needs rethinking), **rewrite** (content is outdated), **merge**, or **drop**.\n\nAppend findings to `../../docs/SITE-AUDIT.md` under a 'Visual Design & UX' section, or create `../../docs/DESIGN-AUDIT.md` if the technical audit is already complete.",
+      "description": "Audit the current website from a design and user experience perspective. Use Chrome to browse the site visually. Follow the `site-audit` skill.\n\nFor each page type, document:\n- **Layout patterns** — grid structure, content zones, visual hierarchy\n- **Design tokens in use** — colors, typography, spacing, component patterns\n- **Content quality** — is copy clear, current, and on-brand? Flag outdated or placeholder content\n- **UX observations** — navigation intuitiveness, user flows, friction points, dead ends\n- **Accessibility** — heading hierarchy, image alt text, color contrast (visual estimate)\n\nFor each page, recommend: **keep** (design is strong), **redesign** (layout needs rethinking), **rewrite** (content is outdated), **merge**, or **drop**.\n\nAppend findings to `docs/SITE-AUDIT.md` under a 'Visual Design & UX' section, or create `docs/DESIGN-AUDIT.md` if the technical audit is already complete.",
       "priority": "high",
       "assignTo": "ui-designer"
     },
     {
       "title": "Content audit of current website",
-      "description": "Crawl every page of the current website and audit the existing content to inform the redesign:\n\nFor each page, document:\n- **Content type** — hero copy, body text, testimonials, FAQs, CTAs, legal, blog posts\n- **Key messages** — what is the page trying to communicate? What value propositions are present?\n- **Content quality** — is the copy clear, current, and on-brand? Flag outdated, placeholder, or thin content\n- **Media assets** — images, videos, downloads — note which are reusable vs need replacement\n- **SEO content** — headings, meta descriptions, alt text — what's working, what's missing\n- **Gaps** — messaging that should exist but doesn't (e.g., missing social proof, no pricing clarity)\n\nFor each page, recommend a migration strategy:\n- **Keep** — content is strong, migrate as-is into the new design\n- **Rewrite** — message is right but copy needs updating for the new design/voice\n- **Merge** — overlapping content across pages, consolidate\n- **Drop** — no longer relevant, redirect or remove\n\nOutput: `../../docs/CONTENT-AUDIT.md` — this is a key input for the design handoff and content migration milestones.",
+      "description": "Crawl every page of the current website and audit the existing content to inform the redesign:\n\nFor each page, document:\n- **Content type** — hero copy, body text, testimonials, FAQs, CTAs, legal, blog posts\n- **Key messages** — what is the page trying to communicate? What value propositions are present?\n- **Content quality** — is the copy clear, current, and on-brand? Flag outdated, placeholder, or thin content\n- **Media assets** — images, videos, downloads — note which are reusable vs need replacement\n- **SEO content** — headings, meta descriptions, alt text — what's working, what's missing\n- **Gaps** — messaging that should exist but doesn't (e.g., missing social proof, no pricing clarity)\n\nFor each page, recommend a migration strategy:\n- **Keep** — content is strong, migrate as-is into the new design\n- **Rewrite** — message is right but copy needs updating for the new design/voice\n- **Merge** — overlapping content across pages, consolidate\n- **Drop** — no longer relevant, redirect or remove\n\nOutput: `docs/CONTENT-AUDIT.md` — this is a key input for the design handoff and content migration milestones.",
       "priority": "high",
       "assignTo": "engineer"
     },
     {
       "title": "Create content inventory spreadsheet",
-      "description": "Based on the site audit and content review, create a structured content inventory:\n- Page URL, title, word count, images, last updated\n- Content status from review (keep / rewrite / merge / drop)\n- Content owner (if identifiable)\n- Migration priority: critical (homepage, key landing pages) vs secondary\n\nOutput: `../../docs/CONTENT-INVENTORY.md`.",
+      "description": "Based on the site audit and content review, create a structured content inventory:\n- Page URL, title, word count, images, last updated\n- Content status from review (keep / rewrite / merge / drop)\n- Content owner (if identifiable)\n- Migration priority: critical (homepage, key landing pages) vs secondary\n\nOutput: `docs/CONTENT-INVENTORY.md`.",
       "priority": "high",
       "assignTo": "ceo"
     },
@@ -58,13 +58,13 @@
     },
     {
       "title": "Analyze design assets and create design spec",
-      "description": "Process all design files in the `designs/` directory. Follow the `design-ingestion` skill for the full process.\n\n**How to read design files:**\n- **PDFs:** Use the Read tool with the `pages` parameter (e.g., pages 1–5, then 6–10) to view each page visually. Do NOT use text extraction as primary method — design PDFs are visual artifacts.\n- **PNG/SVG/JPG:** Use the Read tool directly to view each image.\n- **Fallback for precise values:** Use `markitdown` or `docling` (install via pip) to supplement visual analysis with extracted metadata. Use `pdffonts` for embedded font names.\n\n**Extract:**\n1. Design tokens — colors (hex/oklch), typography, spacing scale, border radii, shadows\n2. Component inventory — recurring UI components\n3. Page layouts — grid system, responsive breakpoints\n4. Asset catalog — images, icons, illustrations\n\nOutput: `../../docs/DESIGN-SPEC.md` with all extracted tokens, components, and layouts.",
+      "description": "Process all design files in the `designs/` directory. Follow the `design-ingestion` skill for the full process.\n\n**How to read design files:**\n- **PDFs:** Use the Read tool with the `pages` parameter (e.g., pages 1–5, then 6–10) to view each page visually. Do NOT use text extraction as primary method — design PDFs are visual artifacts.\n- **PNG/SVG/JPG:** Use the Read tool directly to view each image.\n- **Fallback for precise values:** Use `markitdown` or `docling` (install via pip) to supplement visual analysis with extracted metadata. Use `pdffonts` for embedded font names.\n\n**Extract:**\n1. Design tokens — colors (hex/oklch), typography, spacing scale, border radii, shadows\n2. Component inventory — recurring UI components\n3. Page layouts — grid system, responsive breakpoints\n4. Asset catalog — images, icons, illustrations\n\nOutput: `docs/DESIGN-SPEC.md` with all extracted tokens, components, and layouts.",
       "priority": "critical",
       "assignTo": "engineer"
     },
     {
       "title": "Implement core page layouts",
-      "description": "Configure the project for the new design, then build the primary page templates:\n\n**Project setup:**\n- CSS/styling approach (Tailwind, CSS modules, etc.) configured with design tokens from `../../docs/DESIGN-SPEC.md`\n- Component library structure\n- Framework configuration matching design spec requirements\n\n**Core pages:**\n- Homepage\n- Key landing pages\n- Standard content page layout\n- Navigation (header, footer, mobile menu)\n\nApply design tokens (colors, typography, spacing) from the spec. Ensure responsive behavior matches the design breakpoints.",
+      "description": "Configure the project for the new design, then build the primary page templates:\n\n**Project setup:**\n- CSS/styling approach (Tailwind, CSS modules, etc.) configured with design tokens from `docs/DESIGN-SPEC.md`\n- Component library structure\n- Framework configuration matching design spec requirements\n\n**Core pages:**\n- Homepage\n- Key landing pages\n- Standard content page layout\n- Navigation (header, footer, mobile menu)\n\nApply design tokens (colors, typography, spacing) from the spec. Ensure responsive behavior matches the design breakpoints.",
       "priority": "high",
       "assignTo": "engineer"
     },
@@ -76,7 +76,7 @@
     },
     {
       "title": "Migrate content from old site",
-      "description": "Using the content inventory (`../../docs/CONTENT-INVENTORY.md`), migrate content to the new site:\n- Transfer text content, updating formatting for the new design\n- Download and optimize images from the old site\n- Preserve SEO-critical content (headings, meta descriptions, alt text)\n- Flag content marked for rewrite and create issues for each\n\nVerify no content is lost by cross-referencing the inventory.",
+      "description": "Using the content inventory (`docs/CONTENT-INVENTORY.md`), migrate content to the new site:\n- Transfer text content, updating formatting for the new design\n- Download and optimize images from the old site\n- Preserve SEO-critical content (headings, meta descriptions, alt text)\n- Flag content marked for rewrite and create issues for each\n\nVerify no content is lost by cross-referencing the inventory.",
       "priority": "high",
       "assignTo": "engineer"
     },

package/templates/modules/website-relaunch/skills/design-ingestion.md

@@ -102,7 +102,7 @@ For each distinct page design:
 
 ## Output
 
-Write the complete specification to `../../docs/DESIGN-SPEC.md` with sections:
+Write the complete specification to `docs/DESIGN-SPEC.md` with sections:
 1. Design Tokens (colors, typography, spacing, etc.)
 2. Component Library (each component with description and states)
 3. Page Layouts (each page with structure and responsive notes)

package/templates/modules/website-relaunch/skills/site-audit.md

@@ -43,7 +43,7 @@ Flag any external integrations (forms, payment, chat widgets) that need replacem
 
 ## Output
 
-Write the complete audit to `../../docs/SITE-AUDIT.md` with sections:
+Write the complete audit to `docs/SITE-AUDIT.md` with sections:
 1. Page Inventory (table of all URLs with metadata)
 2. Site Structure (navigation, information architecture)
 3. Technical Stack (framework, hosting, integrations)

package/templates/presets/build-game/preset.meta.json

@@ -59,19 +59,19 @@
   "issues": [
     {
       "title": "Create Game Design Document",
-      "description": "Define the game's complete design. Follow the GDD template in ../../docs/gdd-template.md.\n\nMust include: concept pitch, core mechanic (input → action → feedback → consequence), three-layer game loop, progression system, win/lose conditions, controls, art direction, audio direction, and all tuning parameters.\n\nOutput: ../../docs/GDD.md",
+      "description": "Define the game's complete design. Follow the GDD template in docs/gdd-template.md.\n\nMust include: concept pitch, core mechanic (input → action → feedback → consequence), three-layer game loop, progression system, win/lose conditions, controls, art direction, audio direction, and all tuning parameters.\n\nOutput: docs/GDD.md",
       "priority": "critical",
       "assignTo": "game-designer"
     },
     {
       "title": "Choose game engine and set up project",
-      "description": "Based on the GDD requirements (genre, platform, art style), evaluate and select a game engine or framework. Options to consider:\n- **Web:** Phaser, PixiJS, Three.js, Kaboom.js, vanilla Canvas/WebGL\n- **Cross-platform:** Godot, Unity, Love2D, Defold\n- **Minimal:** Custom engine if the game is simple enough\n\nSet up the project structure, build pipeline, and basic game loop scaffold. Document the choice in ../../docs/TECH-STACK.md.",
+      "description": "Based on the GDD requirements (genre, platform, art style), evaluate and select a game engine or framework. Options to consider:\n- **Web:** Phaser, PixiJS, Three.js, Kaboom.js, vanilla Canvas/WebGL\n- **Cross-platform:** Godot, Unity, Love2D, Defold\n- **Minimal:** Custom engine if the game is simple enough\n\nSet up the project structure, build pipeline, and basic game loop scaffold. Document the choice in docs/TECH-STACK.md.",
       "priority": "critical",
       "assignTo": "engineer"
     },
     {
       "title": "Define art style guide",
-      "description": "Based on the GDD art direction, create a concrete art style guide:\n- Sprite/asset dimensions and resolution\n- Color palette (exact hex values, limited palette if pixel art)\n- Color language: what colors mean in gameplay (player, enemy, pickup, hazard, background)\n- Animation conventions: frame counts, frame rates, style\n- Asset naming conventions and directory structure\n- Reference images or generated style samples\n\nOutput: ../../docs/ART-STYLE-GUIDE.md and sample assets in assets/reference/",
+      "description": "Based on the GDD art direction, create a concrete art style guide:\n- Sprite/asset dimensions and resolution\n- Color palette (exact hex values, limited palette if pixel art)\n- Color language: what colors mean in gameplay (player, enemy, pickup, hazard, background)\n- Animation conventions: frame counts, frame rates, style\n- Asset naming conventions and directory structure\n- Reference images or generated style samples\n\nOutput: docs/ART-STYLE-GUIDE.md and sample assets in assets/reference/",
       "priority": "high",
       "assignTo": "game-artist"
     },
@@ -95,7 +95,7 @@
     },
     {
       "title": "First playtest and balancing pass",
-      "description": "Play the prototype and document findings:\n- Is the core mechanic fun? Does it feel good?\n- Are controls responsive? Any input lag or awkwardness?\n- Difficulty: too easy, too hard, or unclear?\n- What's missing that would make it fun? What should be cut?\n- Tuning parameter adjustments needed\n\nOutput: ../../docs/PLAYTEST-RESULTS.md with specific findings and recommended changes.",
+      "description": "Play the prototype and document findings:\n- Is the core mechanic fun? Does it feel good?\n- Are controls responsive? Any input lag or awkwardness?\n- Difficulty: too easy, too hard, or unclear?\n- What's missing that would make it fun? What should be cut?\n- Tuning parameter adjustments needed\n\nOutput: docs/PLAYTEST-RESULTS.md with specific findings and recommended changes.",
       "priority": "high",
       "assignTo": "game-designer"
     },
@@ -113,7 +113,7 @@
     },
     {
       "title": "Design all levels and progression",
-      "description": "Create detailed level designs for the full game:\n- Level-by-level breakdown: layout, encounters, mechanics introduced, difficulty target\n- Progression curve: how difficulty ramps across the full game\n- Unlock schedule: what the player earns and when\n- Pacing map: tension/relief rhythm across the full experience\n\nOutput: ../../docs/LEVEL-DESIGNS.md with per-level specs.",
+      "description": "Create detailed level designs for the full game:\n- Level-by-level breakdown: layout, encounters, mechanics introduced, difficulty target\n- Progression curve: how difficulty ramps across the full game\n- Unlock schedule: what the player earns and when\n- Pacing map: tension/relief rhythm across the full experience\n\nOutput: docs/LEVEL-DESIGNS.md with per-level specs.",
       "priority": "high",
       "assignTo": "level-designer"
     },
@@ -131,7 +131,7 @@
     },
     {
       "title": "Final balancing and bug fixing",
-      "description": "Play through the entire game and:\n- Adjust difficulty curve based on full playthrough\n- Fix all gameplay bugs\n- Tune all parameters for satisfying progression\n- Verify no soft-locks or unwinnable states\n- Check edge cases: max score, empty inventory, rapid inputs\n\nUpdate ../../docs/GDD.md with final tuning values.",
+      "description": "Play through the entire game and:\n- Adjust difficulty curve based on full playthrough\n- Fix all gameplay bugs\n- Tune all parameters for satisfying progression\n- Verify no soft-locks or unwinnable states\n- Check edge cases: max score, empty inventory, rapid inputs\n\nUpdate docs/GDD.md with final tuning values.",
       "priority": "high",
       "assignTo": "game-designer"
     },

package/templates/presets/repo-maintenance/preset.meta.json

@@ -29,25 +29,25 @@
           "id": "repo-onboarding",
           "title": "Repo Onboarding",
           "level": "team",
-          "description": "Understand the existing codebase and document its current state. Done when ../../docs/CODEBASE-AUDIT.md exists with architecture overview, tech debt inventory, and test coverage assessment."
+          "description": "Understand the existing codebase and document its current state. Done when docs/CODEBASE-AUDIT.md exists with architecture overview, tech debt inventory, and test coverage assessment."
         },
         {
           "id": "process-setup",
           "title": "Process Setup",
           "level": "team",
-          "description": "Establish PR review, issue triage, and release workflows. Done when PR workflow documented (branch requires PRs, no approval gate), issue labels created, release process documented."
+          "description": "Establish PR review, issue triage, and release workflows. Done when the selected Paperclip review gate is documented, existing repository protections are preserved, issue labels exist, and the release process is documented."
         },
         {
           "id": "initial-sweep",
           "title": "Initial Sweep",
           "level": "team",
-          "description": "Process all existing open PRs and issues, run first dependency audit and codebase health pass. Done when all open PRs reviewed, all open issues triaged, dependency audit complete, first batch of cleanup issues created."
+          "description": "Establish bounded maintenance flow for existing PRs and issues, run the first dependency audit, and complete one highest-priority codebase health fix. Done when every open PR has an originating issue, owner, and next action, triage policy is documented, and one focused cleanup PR has completed the normal gate. PR count is advisory and does not create blockers for independent work."
         },
         {
           "id": "steady-state",
           "title": "Steady State",
           "level": "team",
-          "description": "Ongoing maintenance loop — agents handle PRs, issues, and health on every heartbeat. Done when maintenance processes running autonomously for 3+ heartbeat cycles with no backlog buildup."
+          "description": "Ongoing maintenance is assignment- and wake-driven: agents handle owned PRs, reports, and health checks without scanning unrelated queues on every heartbeat. Done when bounded routines and explicit owners keep every open PR tied to a concrete next action without a numeric repository cap."
         }
       ]
     }
@@ -55,51 +55,50 @@
   "issues": [
     {
       "title": "Audit codebase and document architecture",
-      "description": "Read the existing codebase, map architecture, identify tech debt hotspots and test coverage gaps. Document in ../../docs/CODEBASE-AUDIT.md.",
+      "description": "Read the existing codebase, map architecture, identify tech debt hotspots and test coverage gaps. Document in docs/CODEBASE-AUDIT.md.",
       "priority": "high",
       "assignTo": "engineer"
     },
     {
       "title": "Run initial dependency audit",
-      "description": "Audit all dependencies for outdated versions and known vulnerabilities. Document in ../../docs/DEPENDENCY-AUDIT.md. Apply safe patch updates.",
+      "description": "Audit dependencies for outdated versions and known vulnerabilities. Document in docs/DEPENDENCY-AUDIT.md and apply compatible patch updates with focused verification on this issue's own branch/PR. This work can proceed independently of the codebase-audit PR; open PR count is advisory.",
       "priority": "high",
       "assignTo": "engineer"
     },
     {
       "title": "Configure PR workflow and branch protection",
-      "description": "Configure the PR workflow and set up branch protection on the default branch. Branch protection must require a PR before merging (no direct pushes to the base branch — set enforce_admins: true so the shared admin account cannot bypass the PR rule), but must NOT require GitHub-native approving reviews — all agents share one GitHub account and cannot formally approve their own PRs; the review gate lives in Paperclip's executionPolicy, not in GitHub. Use the exact gh api heredoc command from the git-workflow skill → Branch Protection Setup: `gh api repos/{owner}/{repo}/branches/{base}/protection --method PUT --input - <<'EOF'` with payload {\"required_status_checks\": null, \"enforce_admins\": true, \"required_pull_request_reviews\": {\"required_approving_review_count\": 0, \"dismiss_stale_reviews\": false}, \"restrictions\": null}. With required_approving_review_count: 0 the shared account can still open a PR and merge it with zero approvals, so the self-merge flow keeps working. Document PR conventions in ../../docs/pr-conventions.md.",
+      "description": "Inspect existing branch protection and repository rules before configuring the selected PR workflow. Preserve required checks, review requirements, and organization rules; never overwrite them with null defaults or weaken protections to accommodate shared credentials. For a new repository using one shared GitHub credential, use Paperclip executionPolicy for the non-author review gate and do not add a GitHub-native approval requirement the team cannot satisfy. Existing requirements need eligible credentials or an explicit owner decision. Document PR conventions in docs/pr-conventions.md. Open PR count does not block this independent setup work.",
       "priority": "high",
-      "assignTo": "engineer"
+      "assignTo": "devops"
     },
     {
       "title": "Set up issue labels and triage workflow",
       "description": "Create GitHub labels for issue classification (bug, feature, enhancement, question, duplicate, invalid) and priority levels (P0-P3). Document the triage process.",
       "priority": "medium",
-      "assignTo": "user"
+      "assignTo": "product-owner"
     },
     {
       "title": "Document or establish release process",
-      "description": "Review current release workflow. If none exists, establish semver + changelog. Document in ../../docs/RELEASE-PROCESS.md.",
+      "description": "Review current release workflow. If none exists, establish semver + changelog. Document in docs/RELEASE-PROCESS.md. Assign it when acceptance criteria and an owner are ready; open PR count is not a release cap.",
       "priority": "medium",
-      "assignTo": "engineer"
+      "assignTo": "devops"
     },
     {
-      "title": "Review all open pull requests",
-      "description": "Fetch all open PRs on the GitHub repo. Review each for correctness, security, and style. Approve and merge those that pass, request changes on those that don't.",
+      "title": "Reconcile open pull request ownership",
+      "description": "Inventory open PRs only in the configured project repository. Identify each as owner/repo#number and ensure it has exactly one originating Paperclip issue, implementation owner, current head/base/check evidence, and next gate. Do not review or merge multiple PRs from this setup issue, create replacement PRs, or create queue-drain wrappers. Route work on each existing PR to its own originating issue without freezing independent implementation based on PR count.",
       "priority": "high",
-      "assignTo": "engineer"
+      "assignTo": "devops"
     },
     {
-      "title": "Triage all open GitHub issues",
-      "description": "Review all open issues. Classify by type and priority, respond to reporters, close duplicates and invalid issues, convert actionable items to Paperclip tasks.",
+      "title": "Establish triage policy and process the next report",
+      "description": "Document the classification and priority policy, then triage only the highest-priority unprocessed GitHub report in the configured repository. Create at most one Paperclip issue when it represents independently deliverable work with acceptance criteria and available delivery capacity; do not bulk-convert the issue tracker.",
       "priority": "high",
-      "assignTo": "engineer"
+      "assignTo": "product-owner"
     },
     {
-      "title": "First codebase health pass",
-      "description": "Based on the codebase audit, execute the highest-priority cleanup tasks: remove dead code, fix inconsistencies, simplify overly complex areas. Create PRs for each fix.",
-      "priority": "medium",
-      "assignTo": "engineer"
+      "title": "Implement the highest-priority codebase health fix",
+      "description": "After the codebase audit has completed, the backlog owner assigns this issue for exactly one independently deliverable finding. Implement it on this originating issue and one branch/PR, run focused verification, and send it through the normal Code Reviewer gate. Open PR count is advisory and does not block assignment of this independent work.",
+      "priority": "medium"
     }
   ]
 }

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

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

package/templates/roles/ceo/AGENTS.md

@@ -1,5 +1,7 @@
 You are the CEO.
 
+On every wake, follow the `paperclip` skill; it is the source of truth for checkout, task scope, issue comments, and final disposition. For routine or recovery work, do not leave an issue `in_progress` unless a live run, queued continuation, or persisted monitor actually exists.
+
 Your home directory is $AGENT_HOME. Everything personal to you -- life, memory, knowledge -- lives there. Other agents may have their own folders and you may update them when necessary.
 
 Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.

package/templates/roles/ceo/HEARTBEAT.md

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

package/templates/roles/ceo/role.meta.json

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

package/templates/roles/cmo/HEARTBEAT.md

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

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

@@ -17,10 +17,12 @@ 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`, 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.
+8. **When the pr-review module is active**, you are the non-author merge gate. First verify the exact PR head SHA and target base. If required company CI checks actually exist and ran on that exact head, green exact-head CI is the authoritative complete gate: cite those checks and run only the smallest independent check needed for a risky or unclear part of the diff. If required checks do not exist, run and paste the complete local lint/test/typecheck/build gate once. Pending, failed, or wrong-head required checks must be awaited or repaired. Existing required repository checks remain binding; only optional, non-required checks are advisory. 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
 
+- Pending or failed required CI is not unavailable CI. Wait for or repair it; do not substitute local output to bypass it. Local fallback applies only when required checks do not yet exist or CI is unavailable. Branch-protection requirements remain binding even for pre-existing checks.
+
 - Be direct. Approve when good enough — don't bikeshed.
 - Flag security issues as blocking. Everything else is a suggestion unless it's clearly wrong.
 - Ask before guessing. If intent is unclear, ask on the issue rather than assuming.

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

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

package/templates/roles/cto/HEARTBEAT.md

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

package/templates/roles/customer-success/HEARTBEAT.md

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

package/templates/roles/devops/HEARTBEAT.md

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

package/templates/roles/engineer/AGENTS.md

@@ -11,9 +11,9 @@ You implement coding tasks end-to-end: write and edit code, debug issues, add fo
 ## Working Rules
 
 - Work only on issues assigned to you or explicitly handed to you in comments.
-- If you have no assigned actionable work and there are unassigned `todo` issues that clearly match engineering, claim the highest-priority ready issue yourself, set it `in_progress`, and start in the same heartbeat. This is a fallback behind Product Owner push-assignment, not permission to reshuffle work owned by others.
+- Do not self-claim unassigned work. The backlog or auto-assignment owner assigns acceptance-ready issues to available owners. Open PR count is advisory: prioritize stale or conflicting work without freezing independent implementation. Respect explicit company limits, real dependencies, and runtime concurrency controls.
 - 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 blocked work with owner and action. Respect budget, pause/cancel, approval gates, and company boundaries.
-- 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.
+- Make sure you know the success condition for each task before implementation. If acceptance criteria are missing or ambiguous, do not invent a sensible outcome: return the same issue to the Product Owner, or CEO fallback when no Product Owner is present, for a concrete testable decision.
 - 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.
@@ -21,7 +21,7 @@ You implement coding tasks end-to-end: write and edit code, debug issues, add fo
 
 ## Collaboration and Handoffs
 
-- If the PR-review module or an issue `executionPolicy` is active, follow that review/approval flow exactly. Otherwise, when implementation is ready for review, move the issue to `in_review`, assign it to the Product Owner in the same heartbeat, and leave a comment with the change summary, verification, branch/commit details, and any risks. Never leave finished work in `in_review` assigned to yourself.
+- If the PR-review module or an issue `executionPolicy` is active, follow that review/approval flow exactly. Otherwise keep the issue `in_progress` for a concrete handoff to the Product Owner, or CEO fallback, and leave a comment with the change summary, verification, branch/commit details, and any risks. Agent reassignment alone is not a no-policy review path: use `in_review` only with a runtime-recognized execution stage or first-class interaction/approval. Mark delivered work `done` only after the required acceptance and merge steps have completed.
 - UX-facing changes -> route to the UI/UX designer for visual quality and flow review.
 - Security-sensitive changes (auth, crypto, secrets, permissions, adapter/tool access) -> route to the Security Engineer before merge.
 - Browser validation or user-facing verification -> route to QA with exact steps and expected results.

package/templates/roles/engineer/HEARTBEAT.md

@@ -23,7 +23,7 @@ Run this checklist on every heartbeat. The Paperclip skill is the source of trut
 
 ## 4. Checkout and Work
 
-- Checkout before mutating work: `POST /api/issues/{id}/checkout` with the expected current status when the API supports `expectedStatuses`.
+- Checkout before mutating work: `POST /api/issues/{id}/checkout` with `{ "agentId": "<your agent id>", "expectedStatuses": ["todo", "backlog", "blocked", "in_review"] }` — both fields are required, and the list must contain the issue's current status. Send `X-Paperclip-Run-Id` with it.
 - Never retry a 409; that issue belongs to another active run.
 - Start actionable work in the same heartbeat; do not stop at a plan unless planning was requested.
 - Leave durable progress with a clear next action. Use child issues for long or parallel delegated work instead of polling.
@@ -35,7 +35,7 @@ Run this checklist on every heartbeat. The Paperclip skill is the source of trut
 - Upload or attach user-inspectable outputs as work products/artifacts/documents; local filesystem paths alone are not enough.
 - Use issue documents for long plans, specs, QA reports, security reviews, or hiring drafts; comments should summarize and link.
 - Handoffs should use assignment/status/executionPolicy and a concrete next action. Do not rely on generic @-mentions.
-- **Review path applies only when the pr-review module is active.** Without pr-review there is no PR review flow and no `in_review` step. If the github-repo module installed `skills/git-workflow.md`, follow its Direct-to-Base Flow (verify locally, commit, push to the base ref; open a PR only if branch protection rejects the direct push). Otherwise follow the project workspace instructions and record the verification/commit evidence. The rest of this bullet applies only when pr-review is active. Before moving new PR work to `in_review`, verify a review path exists. If a Code Reviewer is on the team, set the `executionPolicy` stages (at least one non-author stage) **before** moving to `in_review`. The **first** stage must be a non-author stage: never list yourself (the issue's assignee/executor — whoever did the work) as a participant in any stage. The runtime excludes the original executor from every stage, so a first stage listing only you has no eligible participant and the issue stalls at stage 1 (`422 Only the active reviewer or approver can advance the current execution stage`) — even if later stages have non-author participants. After moving to `in_review`, `GET /api/issues/{id}` (the list endpoint omits `executionPolicy`) and confirm `stages[0].participants` is not just you; if it is, `PATCH /api/issues/{id}` `{"executionPolicy":null}` to return to `in_progress`, then re-set stages with a non-author first stage. If no Code Reviewer is on the team, do not move new PR work to `in_review`: open the PR and merge it yourself via `gh pr merge <N> --merge` in the same heartbeat (self-merge path), then mark `done`.
+- **Review path applies only when the pr-review module is active.** Without pr-review there is no PR review flow and no `in_review` step. If the github-repo module installed the `git-workflow` skill, follow its Direct-to-Base Flow (verify locally, commit, push to the base ref; open a PR only if branch protection rejects the direct push). Otherwise follow the project workspace instructions and record the verification/commit evidence. The rest of this bullet applies only when pr-review is active. Before moving new PR work to `in_review`, verify a review path exists. If a Code Reviewer is on the team, set the `executionPolicy` stages (at least one non-author stage) **before** moving to `in_review`. The **first** stage must be a non-author stage: never list yourself (the issue's assignee/executor — whoever did the work) as a participant in any stage. Paperclip selects each stage's participant by excluding the recorded return assignee (you, the implementation owner), so a stage whose only participant is you has no eligible participant: the PATCH that would open the review is rejected with `422 No eligible <review|approval> participant is configured for this issue` and the issue never reaches `in_review` — even if later stages have non-author participants. (`422 Only the active reviewer or approver can advance the current execution stage` is the different error you get when you try to advance a stage whose active participant is someone else.) After moving to `in_review`, `GET /api/issues/{id}` (the list endpoint omits `executionPolicy`) and confirm `stages[0].participants` is not just you; if it is, `PATCH /api/issues/{id}` `{"executionPolicy":null}` to return to `in_progress`, then re-set stages with a non-author first stage. If no Code Reviewer is on the team, do not move new PR work to `in_review`: open the PR and merge it yourself via `gh pr merge <N> --merge` in the same heartbeat (self-merge path), then mark `done`.
 - If you find an existing `in_review` issue with `executionPolicy: null`, do not assume it is stalled. Check `GET /api/issues/{id}/interactions`, `GET /api/issues/{id}/approvals`, its user owner, monitor, wake, and recovery state. A pending interaction or another explicit owner is a valid waiting path. Recover to `in_progress` only when none of those paths exists; then either add a non-author `executionPolicy` for PR review or self-merge when no Code Reviewer exists.
 
 ## 6. Exit

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

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

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

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

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

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

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

@@ -9,7 +9,7 @@ You own product intent, backlog health, acceptance criteria, prioritization, and
 ## Working Rules
 
 - Work only on issues assigned to you or explicitly handed to you in comments.
-- If an issue is assigned to you in `in_review` and no formal executionPolicy participant is waiting, review it immediately against the acceptance criteria, branch/commit/PR evidence, and recorded verification. If it passes, comment with the acceptance decision and set it `done`; if it does not pass, set it back to `in_progress`, assign it to the Engineer, and list the exact required changes.
+- For an assigned acceptance handoff, inspect the full action path first: `executionPolicy` and `executionState`, pending interactions/approvals, user owner, wakes, monitors, and recovery actions. Never override another pending path merely because `executionPolicy` is null. An active Product Owner stage advances through its documented verdict; an advisory handoff returns the same issue to the implementation owner. Do not close an originating implementation issue while its PR is open or another review/merge stage remains. Complete a standalone acceptance deliverable only when its own criteria are satisfied.
 - 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 blocked work with owner and action. Respect budget, pause/cancel, approval gates, and company boundaries.
 - Keep issues small, acceptance-driven, project-scoped, and linked to goals when available.
 - Use first-class blockers (`blockedByIssueIds`) for dependencies instead of free-text "blocked by" notes.