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

package/docs/PAPERCLIP-COMPATIBILITY.md

@@ -0,0 +1,66 @@
+# Paperclip compatibility — Company Wizard 0.6.2
+
+Reviewed on 2026-09-07 against [Paperclip source `856813ba3a083f23694b8554104b3e50abcb1363`](https://github.com/paperclipai/paperclip/tree/856813ba3a083f23694b8554104b3e50abcb1363), the current master snapshot at review time (2026-09-06).
+
+**0.6.2 re-review (2026-09-07).** The 0.6.1 claims below were re-verified line by line against the local Paperclip checkout at `3fb4b65f9d974d8687db8a060f20ec66b6071a79` ("merge upstream master through 2026-09-06"). Approval, hire, watchdog, workspace-policy, Company Skill, and REST-shape claims held. The defects found were on the plugin side and are fixed in 0.6.2: an invalid routine `concurrencyPolicy`, a routine title read from a key the renderer ignored, instruction paths left behind by the Skills Store migration, a misquoted review-gate 422, undocumented review-round escalation, a stale checkout contract, and the host-floor rationale corrected below. See `CHANGELOG.md` for the full list.
+
+The plugin does not vendor, modify, or deploy Paperclip itself. Its runtime SDK remains provided by the host.
+
+The published SDK and shared package both require **Node 24.11+**; their worker/manifest bundler targets Node 24. Use that runtime for a supported Paperclip host. A root `engines` gate is intentionally omitted so existing Node 20/22 build/release workflows remain installable under pnpm 10. Those workflows are supplemental compatibility signals, not proof of a supported Paperclip host runtime; migrating them to Node 24 requires workflow-edit authority.
+
+## Tested package contracts
+
+- Stable SDK/shared: `2026.831.1` (pinned development dependencies; peer floor `>=2026.831.1`).
+- Latest published canary SDK/shared checked separately: `2026.906.0-canary.5`.
+- Validation: TypeScript, production bundle, worker/action tests, assembly/template matrix, and shared-schema payload tests. These are source/contract and mocked integration checks, not a live deployed Paperclip database/browser acceptance test.
+
+### Development-dependency remediation
+
+Outcome: **fixed installed dependency advisories**. The original audit reported 19 advisories (1 critical, 9 high, 7 moderate, 2 low), all in development/build dependencies; production-only audit was already clean. The repository's configured tests use `vitest run` without a UI server, and its build uses PostCSS/esbuild against local files, not their HTTP servers. No deployed-plugin exploit was established.
+
+The narrow fix removes unused `esbuild-postcss-plugin`, updates Vitest within 3.x and PostCSS within 8.x, moves esbuild to patched 0.28.x, and refreshes affected transitive Vite/glob/parser packages. `pnpm-workspace.yaml` limits the esbuild override to Vite and preserves the existing dependency-build allowlist and Paperclip release-age exceptions. No application authentication, approval or runtime control is weakened.
+
+Reproduction substitute: the same full `pnpm audit --json` went from 19 advisories to **zero**; the lockfile contains no reported vulnerable versions or unused plugin chain. This proves dependency removal/update, not a live exploit reproduction. Alternate transitive paths (not only direct dependencies) are included in the audit. `pnpm install --frozen-lockfile`, TypeScript, production build, 72 worker/action tests and 199 logic/API tests pass on Node 24.11.0, preserving normal build and provisioning behavior. The existing tests serve as controls; no artificial exploit fixture was needed for a dependency-version remediation.
+
+API version 1 and declared capability checks remain enabled. There is deliberately no numeric `minimumHostVersion`. `server/src/app.ts` hands the plugin loader `opts.hostVersion ?? serverVersion`, and `server/src/version.ts` resolves `serverVersion` from `git describe`, then a stamped build version, then the server package version — `"0.0.0"` only as a last-resort fallback. A packaged install therefore reports the server package version (`0.3.1` in this snapshot), which `plugin-loader.ts` would compare with `compareSemver` against any CalVer floor and reject, even though the host is current. Older API implementations are not thereby supported; unsupported REST operations surface errors rather than silently downgrading governance.
+
+## Source-aligned behavior
+
+| Area | 0.6.2 behavior | Source contract |
+| --- | --- | --- |
+| Project policies | Required `enabled`, full schema fields, explicit concurrency defaults; preserve existing IDs, goal links and operator settings | `packages/shared/src/validators/project.ts`; `server/src/routes/projects.ts` |
+| Workspace enforcement | Feature-gated; preserve disabled policies and explicit issue/operator overrides | `server/src/services/execution-workspace-policy.ts`; `server/src/services/heartbeat.ts` |
+| Hires | Governed `/agent-hires`, explicit selected board approvals; no approval-policy bypass | `server/src/routes/agents.ts`; `server/src/routes/approvals.ts` |
+| Bootstrap | Separate issue-bound CEO wake; pending/paused/terminated agents rejected, skipped wakes reported, missing watchdog restored best-effort | `server/src/routes/agents.ts`; `server/src/routes/issues.ts` |
+| Company Skills | Metadata, file content and rename use their respective routes; rename reads nested `skill.key`; imported slug collisions are not overwritten | `server/src/routes/company-skills.ts`; `server/src/services/company-skills.ts` |
+| Wizard state | Company-scoped SDK `ctx.state`, not nonexistent `/plugins/:id/company-settings/:companyId` | Plugin SDK state contract; `server/src/services/plugin-state-store.ts` |
+| Review recovery | Active stage/return assignee, not the currently reassigned reviewer, determines author-only blockage | `server/src/services/issue-execution-policy.ts` |
+| Managed worktrees | Preserve assigned branch identity and reusable workspace records; no cleanup shortcut or `--delete-branch` merge | `server/src/services/heartbeat.ts`; `server/src/routes/execution-workspaces.ts` |
+| Routines | Title accepts the legacy `name` key; `concurrencyPolicy` is normalized to the accepted enum before create/sync, so a bad template value degrades instead of losing the routine | `packages/shared/src/validators/routine.ts`; `server/src/routes/routines.ts` |
+| Review gates | An author-only stage fails participant selection (`No eligible <review\|approval> participant is configured for this issue`); after 3 agent rounds the stage escalates to the responsible/creating human | `server/src/services/issue-execution-policy.ts` |
+| Agent instructions | Skills are named by Skills Store slug, and shared docs are referenced as `docs/<file>.md` from the agent working directory; only `AGENTS.md` uses the file-relative `../../docs/` form | `packages/adapters/claude-local/src/server/skills.ts`; assembled `agents/<role>/AGENTS.md` |
+
+### Concurrency is conditional
+
+Storing `sharedWorkspaceConcurrency: "serialize"` is not sufficient by itself. Current source ignores workspace policies/settings when the instance's `enableIsolatedWorkspaces` is disabled. The project policy must also be enabled; explicit per-issue settings win, and project `auto`/`allow` opt-outs are preserved. The shared guard applies to project-bound shared-workspace runs, not arbitrary processes sharing a directory. The wizard never changes the global experimental setting.
+
+Fresh local Git repositories stay shared until bootstrap initializes and seeds them. Existing projects retain their supplied workspace/mode/strategy; no guessed local Git directory replaces them. No Git initialization is generated for remote-managed or non-Git paths.
+
+### Consolidation decisions
+
+- PR #44: retain opt-in lean delivery, skill-update route fixes, exact-head review/CI checks, same-issue advisory handoffs, and template regressions. Standard role-based review remains the default.
+- PR #46: retain explicit shared concurrency and approval UI, fixing partial policy rendering, AI field loss, existing-project application, overly broad approvals, and host-floor incompatibility.
+- PR #47: adopt advisory PR queue counts throughout roles/modules/preset seeds. Actual dependencies, branch protection, required checks, and explicit company capacity policies are still binding.
+- Additional fixes: SDK manifest persistence, existing routine project links, imported-skill collisions, wrong retired-role parent IDs, managed-branch preservation, false stalled-review recovery, and release-pinned template selection.
+
+Official/default templates now come from the installed plugin release. A configured local path remains operator-owned. Custom GitHub sources get URL-specific caches and atomic explicit refresh; a missing custom source never silently becomes official templates. Refresh before preview when intentionally changing a custom source.
+
+## Operator acceptance checklist
+
+1. Install the 0.6.2 package in a current Paperclip host and reload the plugin.
+2. Preview an existing company with multiple projects. Check IDs, goal links, workspace paths, policy opt-outs and newly added routine project links.
+3. Provision a disposable company with board-gated hires. Confirm only this run's hires appear, approve a subset, refresh, then explicitly start bootstrap after the CEO is approved.
+4. Confirm actual shared-run deferral with the instance feature and project policy enabled; confirm disabled/explicit override behavior separately.
+5. Exercise one standard review and one opt-in lean review using a managed worktree and required CI. Verify exact-head evidence, review ownership, merge, and preserved workspace identity.
+
+No production company, repository protection, instance setting, or npm release was changed during contract validation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlein/paperclip-plugin-company-wizard",
-  "version": "0.4.22",
+  "version": "0.6.2",
   "type": "module",
   "description": "AI-powered wizard to bootstrap paperclip agent companies from composable templates (for latest paperclip version)",
   "repository": {
@@ -18,6 +18,7 @@
   "files": [
     "dist/",
     "templates/",
+    "docs/PAPERCLIP-COMPATIBILITY.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md"
   ],
@@ -43,29 +44,28 @@
     "tailwind-merge": "^3.4.1"
   },
   "devDependencies": {
-    "@paperclipai/plugin-sdk": "2026.722.0",
-    "@paperclipai/shared": "2026.722.0",
+    "@paperclipai/plugin-sdk": "2026.831.1",
+    "@paperclipai/shared": "2026.831.1",
     "@rollup/plugin-node-resolve": "^16.0.1",
     "@rollup/plugin-typescript": "^12.1.2",
     "@tailwindcss/postcss": "^4.0.7",
     "@types/node": "^24.6.0",
     "@types/react": "^19.0.8",
     "@types/react-dom": "^19.2.3",
-    "esbuild": "^0.27.3",
-    "esbuild-postcss-plugin": "^0.0.7",
+    "esbuild": "^0.28.1",
     "husky": "^9.1.7",
     "lint-staged": "^16.3.2",
-    "postcss": "^8.5.8",
+    "postcss": "^8.5.28",
     "prettier": "^3.8.1",
     "rollup": "^4.38.0",
     "tailwindcss": "^4.0.7",
     "tslib": "^2.8.1",
     "typescript": "^5.7.3",
-    "vitest": "^3.0.5"
+    "vitest": "^3.2.6"
   },
   "peerDependencies": {
-    "@paperclipai/plugin-sdk": ">=2026.707.0",
-    "@paperclipai/shared": ">=2026.707.0",
+    "@paperclipai/plugin-sdk": ">=2026.831.1",
+    "@paperclipai/shared": ">=2026.831.1",
     "react": ">=18",
     "react-dom": ">=18"
   },
@@ -77,7 +77,7 @@
     "test": "vitest run --config ./vitest.config.ts",
     "test:logic": "node --test src/logic/*.test.js src/api/*.test.js",
     "typecheck": "tsc --noEmit",
-    "build:prod": "NODE_ENV=production node ./esbuild.config.mjs",
+    "build:prod": "node ./esbuild.config.mjs --production",
     "publish:npm": "npm publish --access public"
   }
 }

package/templates/ai-wizard/interview-system.md

@@ -8,6 +8,8 @@ You are conducting a guided interview to understand what company to set up.
 ## Available Modules (can be added on top of preset)
 {{MODULE_CATALOG}}
 
+`lean-delivery` is opt-in: explain its single merge gate and risk-triggered specialist evidence when relevant, and include it only if the user chooses that policy. Open PR count is advisory in either mode, not a numeric assignment cap. Otherwise leave it unselected. When selected, include its `pr-review` and `github-repo` dependencies.
+
 ## Available Optional Roles (can be added on top of preset)
 {{ROLE_CATALOG}}
 

package/templates/ai-wizard/single-shot-system.md

@@ -10,6 +10,8 @@ Given a natural language description of what the user wants to build, you select
 
 {{MODULE_CATALOG}}
 
+`lean-delivery` is opt-in: include it only when the user explicitly requests lean delivery or its single-gate review policy. Open PR count is advisory in either mode, not a numeric assignment cap. Otherwise leave it unselected. When selected, include its `pr-review` and `github-repo` dependencies.
+
 ## Available Optional Roles (can be added on top of preset)
 
 {{ROLE_CATALOG}}

package/templates/bootstrap-instructions.md

@@ -16,10 +16,10 @@ Each section (Goals, Projects, Labels, Agents, Issues, Routines) contains object
 **Creation order** (respects dependencies):
 
 1. **Goals** — create with `POST /api/companies/{companyId}/goals` using `{ title, description, level, parentId? }`. Top-level first, then sub-goals: sub-goals have `parentId: → "Parent Title"`, so create the parent first and use its ID. Valid `level`: `company`, `team`, `agent`, `task`. Valid `status` (optional, defaults to `planned`): `planned`, `active`, `achieved`, `cancelled`.
-2. **Projects** — create with `POST /api/companies/{companyId}/projects` using `{ name, description, goalIds, workspace, executionWorkspacePolicy? }`. Reference goals via `goalIds`; create after all goals exist. Valid project `status` (optional, defaults to `backlog`): `backlog`, `planned`, `in_progress`, `completed`, `cancelled` — **`active` is a goal status, NOT a project status; do not set it on a project.** Create the project workspace as an object, not a raw string. Fresh/new repositories use a local project workspace such as `workspace: { sourceType: "local_path", cwd: "...", defaultRef: "main", setupCommand: "git init -b main", isPrimary: true }` and must initialize Git before work starts; do not attach an `executionWorkspacePolicy` to a fresh local repo (the repo has no base ref yet). Existing repository-backed projects use the workspace refs shown in this bootstrap exactly as rendered; do not rewrite them to `main`, `master`, or add/remove `origin/`. When this bootstrap includes `executionWorkspacePolicy`, send it exactly as rendered; it was included only because Paperclip's experimental isolated-workspaces setting is enabled, and its `workspaceStrategy.baseRef` comes from project/worktree settings. Never inline credentials in repo URLs.
+2. **Projects** — create with `POST /api/companies/{companyId}/projects` using `{ name, description, goalIds, workspace, executionWorkspacePolicy? }`. Reference goals via `goalIds`; create after all goals exist. Valid project `status` (optional, defaults to `backlog`): `backlog`, `planned`, `in_progress`, `completed`, `cancelled` — **`active` is a goal status, NOT a project status; do not set it on a project.** Create the project workspace as an object, not a raw string. Fresh/new repositories use a local workspace such as `workspace: { sourceType: "local_path", cwd: "...", defaultRef: "main", setupCommand: "git init -b main", isPrimary: true }` with the rendered shared-workspace policy until Git has a valid initial commit. Existing repository-backed projects use the workspace refs exactly as rendered; do not rewrite them to `main`, `master`, or add/remove `origin/`. Send any rendered `executionWorkspacePolicy` unchanged, including its `enabled` value. A saved `sharedWorkspaceConcurrency: "serialize"` is effective only when Paperclip's instance feature and project policy are enabled; heed any bootstrap warning instead of assuming that saved configuration is an active lock. Never inline credentials in repo URLs.
 3. **Labels** — if the bootstrap includes an Issues section, create issue labels first (`POST /api/companies/{companyId}/labels` with `{ name, color }`). Colors must be 6-digit hex strings with a leading `#`.
 4. **Agents** — hire via governance (`POST /api/companies/{companyId}/agent-hires`) using the listed `adapterType`, nested `adapterConfig`, `runtimeConfig`, `capabilities`, and `metadata`. The Company Wizard already created the CEO for this bootstrap issue; reuse/update any existing agent with the same `metadata.templateRole` instead of creating a duplicate.
-5. **Issues** — every issue must include `projectId`, including subtasks. Subtasks must also include `parentId`. Assign via `assigneeAgentId` or `assigneeUserId`, and attach labels via `labelIds`. If you use `POST /api/issues/{parentId}/children`, still pass `projectId` explicitly for clarity; if you use `POST /api/companies/{companyId}/issues`, passing both `parentId` and `projectId` is mandatory for this bootstrap. Set workspace isolation explicitly: **top-level issues** (no `parentId`) must include `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so each gets its own worktree/branch; **subtasks** set `parentId` and omit `executionWorkspaceSettings` so they reuse the parent's workspace.
+5. **Issues** — include the rendered `projectId` for project work, including subtasks; keep deliberately project-detached API-only work detached. Subtasks also include `parentId`. Assign via `assigneeAgentId` or `assigneeUserId`, and attach labels via `labelIds`. When using either `POST /api/issues/{parentId}/children` or `POST /api/companies/{companyId}/issues`, keep parent/project links explicit. Declare workspace intent on repository implementation issues, including subtasks: request `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` when the instance feature, project policy, and initialized repository support it; otherwise follow the rendered project policy and avoid concurrent shared-checkout writes. Reuse another issue's workspace only when the task explicitly requires one shared code change; then send `inheritExecutionWorkspaceFromIssueId` with the source issue's internal id instead of relying on `parentId` inheritance.
 6. **Routines** — reference project and agent. Create the routine first, then add a schedule trigger with `POST /api/routines/{routineId}/triggers` using `{ kind: "schedule", cronExpression: schedule, timezone: "UTC" }`.
 
 **Status + subissue guardrails:**
@@ -27,7 +27,7 @@ Each section (Goals, Projects, Labels, Agents, Issues, Routines) contains object
 - Parent and subissue status are related by intent, not automatically coupled by tooling.
 - Do not auto-mark a parent `done` just because a child changed status.
 - Do not auto-reopen a `done` parent/subissue unless you have an explicit reason and record it in a comment.
-- Make workspace intent explicit at creation; never rely on implicit inheritance. A top-level issue (no `parentId`) created without `executionWorkspaceSettings` silently adopts the workspace of whatever issue the creator currently has checked out, which serializes work and corrupts branch state. Therefore: top-level issues set `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` (own worktree); subissues set `parentId` and omit `executionWorkspaceSettings` so they deliberately share the parent's workspace (safe because the parent cannot be completed/cleaned up while subissues are open). Keep `projectId` explicit on both.
+- Make workspace intent explicit at creation; never rely on implicit inheritance. Repository implementation issues and subissues request `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` only when supported by the effective instance/project configuration and initialized repository. `parentId` expresses task hierarchy, not consent to share a checkout. Reuse is exceptional and explicit via `inheritExecutionWorkspaceFromIssueId` only when the task requires the same code change. Keep project work scoped and API-only routines project-detached.
 
 **Secrets guardrail:**
 

package/templates/modules/accessibility/agents/engineer/skills/accessibility-audit.fallback.md

@@ -4,11 +4,11 @@ The QA Engineer and UI Designer own accessibility auditing above you. You are th
 
 ## Accessibility Audit (Fallback)
 
-1. If no `../../docs/ACCESSIBILITY-AUDIT.md` exists and nobody has started:
+1. If no `docs/ACCESSIBILITY-AUDIT.md` exists and nobody has started:
    - Check semantic HTML usage in key pages/components
    - Verify form labels and ARIA attributes are correct
    - Run automated accessibility checks if tooling is available
-   - Document in `../../docs/ACCESSIBILITY-AUDIT.md`
+   - Document in `docs/ACCESSIBILITY-AUDIT.md`
    - Tag QA or UI Designer to expand the audit
 2. If QA or UI Designer is active, skip this entirely.
 

package/templates/modules/accessibility/agents/ui-designer/skills/accessibility-audit.fallback.md

@@ -4,11 +4,11 @@ The QA Engineer owns accessibility auditing above you. You are the fallback —
 
 ## Accessibility Audit (Fallback)
 
-1. If no `../../docs/ACCESSIBILITY-AUDIT.md` exists and QA hasn't started:
+1. If no `docs/ACCESSIBILITY-AUDIT.md` exists and QA hasn't started:
    - Review color contrast and visual accessibility of the design system
    - Check that focus states are designed for all interactive components
    - Verify the design system includes accessible component patterns
-   - Document in `../../docs/ACCESSIBILITY-AUDIT.md`
+   - Document in `docs/ACCESSIBILITY-AUDIT.md`
    - Tag QA to expand with keyboard and screen reader testing
 2. If QA is active, skip this entirely.
 

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

@@ -16,7 +16,7 @@
     {
       "title": "Conduct initial accessibility audit",
       "assignTo": "capability:accessibility-audit",
-      "description": "Audit the project for WCAG 2.2 compliance: check semantic HTML, keyboard navigation, color contrast, ARIA usage, and screen reader compatibility. Document findings and remediation plan in ../../docs/ACCESSIBILITY-AUDIT.md."
+      "description": "Audit the project for WCAG 2.2 compliance: check semantic HTML, keyboard navigation, color contrast, ARIA usage, and screen reader compatibility. Document findings and remediation plan in docs/ACCESSIBILITY-AUDIT.md."
     }
   ]
 }

package/templates/modules/accessibility/skills/accessibility-audit.bar.md

@@ -2,7 +2,7 @@
 
 A good accessibility audit:
 
-- A `../../docs/ACCESSIBILITY-AUDIT.md` covering WCAG 2.2 AA across: semantic HTML, keyboard navigation, colour contrast, ARIA usage, images/media, forms, and zoom/responsive behaviour.
+- A `docs/ACCESSIBILITY-AUDIT.md` covering WCAG 2.2 AA across: semantic HTML, keyboard navigation, colour contrast, ARIA usage, images/media, forms, and zoom/responsive behaviour.
 - Each finding has a severity (Critical / Major / Minor), a specific location, and a concrete remediation — Critical and Major findings have follow-up issues created.
 
 Not done:

package/templates/modules/accessibility/skills/accessibility-audit.md

@@ -5,7 +5,7 @@ You own accessibility compliance. This ensures the product is usable by everyone
 ## Accessibility Audit Process
 
 1. Review the project for WCAG 2.2 compliance at Level AA (minimum).
-2. Check and document in `../../docs/ACCESSIBILITY-AUDIT.md`:
+2. Check and document in `docs/ACCESSIBILITY-AUDIT.md`:
    - **Semantic HTML**: Correct heading hierarchy, landmark regions, form labels
    - **Keyboard navigation**: All interactive elements focusable and operable, logical tab order, visible focus indicators
    - **Color and contrast**: Minimum 4.5:1 for normal text, 3:1 for large text, no color-only information

package/templates/modules/architecture-plan/agents/ceo/skills/architecture-plan.bar.md

@@ -1,11 +1,11 @@
 ## Architecture Plan — Done Bar (CEO Fallback)
 
 **Done:**
-- `../../docs/ARCHITECTURE.md` exists with at least: a brief system overview (what the system does, its main components), the primary data flows, and a clear note that this is a CEO-generated placeholder pending engineer review.
+- `docs/ARCHITECTURE.md` exists with at least: a brief system overview (what the system does, its main components), the primary data flows, and a clear note that this is a CEO-generated placeholder pending engineer review.
 - A follow-up issue exists, assigned to an engineer or the architecture-plan capability, to complete the full architecture document.
 
 **Not done:**
-- No `../../docs/ARCHITECTURE.md` exists at all.
+- No `docs/ARCHITECTURE.md` exists at all.
 - The document exists but contains no actionable overview (placeholder text only).
 - No follow-up issue was created for the engineer to complete the work.
 

package/templates/modules/architecture-plan/agents/ceo/skills/architecture-plan.fallback.md

@@ -4,9 +4,9 @@ The Engineer primarily owns system architecture. You are the fallback — step i
 
 ## Architecture Plan (Fallback)
 
-1. If no `../../docs/ARCHITECTURE.md` exists and no engineer has started:
+1. If no `docs/ARCHITECTURE.md` exists and no engineer has started:
    - Sketch a minimal architecture based on the tech stack and project goals
-   - Document in `../../docs/ARCHITECTURE.md`
+   - Document in `docs/ARCHITECTURE.md`
    - Create an issue for the engineer to review and expand
 2. If an engineer is active, skip this entirely.
 

package/templates/modules/architecture-plan/agents/engineer/skills/design-system.fallback.md

@@ -4,10 +4,10 @@ The UI Designer primarily owns the design system. You are the fallback — set u
 
 ## Design System (Fallback)
 
-1. If no `../../docs/DESIGN-SYSTEM.md` exists and no UI Designer has started:
+1. If no `docs/DESIGN-SYSTEM.md` exists and no UI Designer has started:
    - Choose a sensible default palette (e.g., Tailwind defaults or a minimal custom set)
    - Define basic typography and spacing scales
-   - Document in `../../docs/DESIGN-SYSTEM.md`
+   - Document in `docs/DESIGN-SYSTEM.md`
    - Create an issue for a UI Designer to review and expand if one is hired later
 2. If a UI Designer is active, skip this entirely.
 

package/templates/modules/architecture-plan/agents/ui-designer/skills/architecture-plan.md

@@ -4,7 +4,7 @@ When the architecture plan is being created, contribute the UI/frontend perspect
 
 ## UI Architecture Contributions
 
-1. Check that `../../docs/ARCHITECTURE.md` exists. If it does not exist yet, the engineer's architecture-plan task has not completed — leave an issue comment ("Waiting for engineer to complete ../../docs/ARCHITECTURE.md before adding UI layer") and do not close this issue yet. Check back on your next heartbeat.
+1. Check that `docs/ARCHITECTURE.md` exists. If it does not exist yet, the engineer's architecture-plan task has not completed — leave an issue comment ("Waiting for engineer to complete docs/ARCHITECTURE.md before adding UI layer") and do not close this issue yet. Check back on your next heartbeat.
 
 If an Engineer is defining the architecture, coordinate with them on:
 - **Frontend component structure**: Page layout, shared components, routing
@@ -12,7 +12,7 @@ If an Engineer is defining the architecture, coordinate with them on:
 - **Asset pipeline**: Images, icons, fonts — how they're managed and optimized
 - **Responsive strategy**: How layouts adapt across breakpoints
 
-Document your UI architecture notes in `../../docs/ARCHITECTURE.md` under a `## UI Architecture` section.
+Document your UI architecture notes in `docs/ARCHITECTURE.md` under a `## UI Architecture` section.
 
 ## Rules
 

package/templates/modules/architecture-plan/agents/ui-designer/skills/design-system.md

@@ -5,8 +5,8 @@ You own the visual design system. Establish the foundational patterns that ensur
 ## Design System Process
 
 1. Review the company goal, brand context, and target audience
-2. If `../../docs/BRAND-IDENTITY.md` exists, use it as the authoritative source for color palette, typography, and brand voice. Do not invent a palette that contradicts established brand identity.
-3. Define and document in `../../docs/DESIGN-SYSTEM.md`:
+2. If `docs/BRAND-IDENTITY.md` exists, use it as the authoritative source for color palette, typography, and brand voice. Do not invent a palette that contradicts established brand identity.
+3. Define and document in `docs/DESIGN-SYSTEM.md`:
    - **Color palette**: Primary, secondary, accent, semantic (success, error, warning), neutrals
    - **Typography**: Font families, scale (heading/body/caption sizes), weights, line heights
    - **Spacing**: Base unit and scale (4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px)
@@ -14,7 +14,7 @@ You own the visual design system. Establish the foundational patterns that ensur
    - **Brand guidelines**: Logo usage, tone of visual language, iconography style
    - **Responsive breakpoints**: Mobile, tablet, desktop sizing approach
 4. Create implementation issues for the engineer:
-   - `POST /api/companies/{companyId}/issues` for CSS/design token setup, component library scaffolding. 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` for CSS/design token setup, component library scaffolding. 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.
 5. Assign or hand off implementation issues to the Engineer with a concrete next action; do not rely on generic @-mentions.
 
 ## Rules

package/templates/modules/architecture-plan/module.meta.json

@@ -26,12 +26,12 @@
     {
       "title": "Design initial system architecture",
       "assignTo": "capability:architecture-plan",
-      "description": "Based on the tech stack decisions, design the system architecture: component structure, data flow, API boundaries, and deployment model. Document in ../../docs/ARCHITECTURE.md."
+      "description": "Based on the tech stack decisions, design the system architecture: component structure, data flow, API boundaries, and deployment model. Document in docs/ARCHITECTURE.md."
     },
     {
       "title": "Define design system and visual language",
       "assignTo": "capability:design-system",
-      "description": "Establish the visual foundation: color palette, typography, spacing scale, component patterns, and brand guidelines. Document in ../../docs/DESIGN-SYSTEM.md."
+      "description": "Establish the visual foundation: color palette, typography, spacing scale, component patterns, and brand guidelines. Document in docs/DESIGN-SYSTEM.md."
     }
   ]
 }

package/templates/modules/architecture-plan/skills/architecture-plan.bar.md

@@ -2,7 +2,7 @@
 
 A good architecture plan:
 
-- A `../../docs/ARCHITECTURE.md` with a system overview (text/ASCII component diagram), data flow through the system, API boundaries (internal and external), deployment model, and key decisions recorded in ADR style with rationale.
+- A `docs/ARCHITECTURE.md` with a system overview (text/ASCII component diagram), data flow through the system, API boundaries (internal and external), deployment model, and key decisions recorded in ADR style with rationale.
 - Decomposed into concrete implementation issues for foundational scaffolding so work can start incrementally.
 
 Not done:

package/templates/modules/architecture-plan/skills/architecture-plan.md

@@ -4,8 +4,8 @@ You own system architecture. Design the structure that implements the tech stack
 
 ## Architecture Planning Process
 
-1. If `../../docs/TECH-STACK.md` exists, review it alongside the project requirements. Otherwise, gather tech stack context from the codebase and project docs.
-2. Design and document in `../../docs/ARCHITECTURE.md`:
+1. If `docs/TECH-STACK.md` exists, review it alongside the project requirements. Otherwise, gather tech stack context from the codebase and project docs.
+2. Design and document in `docs/ARCHITECTURE.md`:
    - **System overview**: High-level component diagram (describe in text/ASCII)
    - **Component structure**: Modules, services, or packages and their responsibilities
    - **Data flow**: How data moves through the system
@@ -13,7 +13,7 @@ You own system architecture. Design the structure that implements the tech stack
    - **Deployment model**: How the system is built, tested, and deployed
    - **Key decisions**: Architectural decisions with rationale (ADR-style)
 3. Create implementation issues for the foundational structure:
-   - `POST /api/companies/{companyId}/issues` for scaffolding, core modules, etc. 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` for scaffolding, core modules, etc. 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.
 
 ## Rules
 

package/templates/modules/architecture-plan/skills/design-system.md

@@ -4,9 +4,9 @@ You are establishing the project's design system foundations when no UI Designer
 
 ## Steps
 
-1. Read `../../docs/TECH-STACK.md` if it exists to understand the frontend framework and styling approach.
-2. Read `../../docs/BRAND-IDENTITY.md` if it exists for color palette, typography, and brand direction.
-3. If `../../docs/DESIGN-SYSTEM.md` does not exist, create it using `../../docs/design-system-template.md` as a starting point.
+1. Read `docs/TECH-STACK.md` if it exists to understand the frontend framework and styling approach.
+2. Read `docs/BRAND-IDENTITY.md` if it exists for color palette, typography, and brand direction.
+3. If `docs/DESIGN-SYSTEM.md` does not exist, create it using `docs/design-system-template.md` as a starting point.
 4. Define the minimum viable token set:
    - **Colors**: primary, secondary, background, surface, text, error/warning/success. Use the brand palette if available, otherwise choose accessible defaults (WCAG AA contrast ratio ≥ 4.5:1 for text).
    - **Typography**: 2–3 font sizes (body, heading, small), font family (system stack if no brand font specified), line heights.
@@ -21,5 +21,5 @@ You are establishing the project's design system foundations when no UI Designer
 
 - Keep it practical over perfect. Consistent tokens are more valuable than a comprehensive design system.
 - Do not create visual assets (icons, illustrations) — document where placeholders should go.
-- Reference `../../docs/ARCHITECTURE.md` for the component hierarchy if it exists.
-- If `../../docs/DESIGN-SYSTEM.md` already exists (a UI Designer ran first), review it for engineering feasibility and add implementation notes — do not overwrite their work.
+- Reference `docs/ARCHITECTURE.md` for the component hierarchy if it exists.
+- If `docs/DESIGN-SYSTEM.md` already exists (a UI Designer ran first), review it for engineering feasibility and add implementation notes — do not overwrite their work.

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

@@ -4,16 +4,16 @@ Adds a low-frequency safety net for issue assignment. Primary dispatch happens a
 
 ## What it adds
 
-- **Product Owner skill**: Safety-net assignment check — assigns any still-unassigned backlog items to the best-fit available agent.
+- **Product Owner skill**: Safety-net assignment check — assigns only the next item that fits implementation and review capacity.
 - **CEO fallback skill**: Steps in when the PO is absent or stalled.
 
 ## How it works
 
-Primary assignment happens during backlog grooming: the Product Owner creates issues and assigns each to the best-fit agent immediately. The auto-assign routine is a **safety net** that runs every 4 hours to catch anything that slipped through:
+Primary assignment happens during backlog grooming: the Product Owner assigns acceptance-ready issues to best-fit agents when capacity is free. The auto-assign routine is a **safety net** that runs every 4 hours to catch anything that slipped through:
 
 1. Are there unassigned issues in `todo` status?
 2. Do those issues have enough acceptance criteria and no unresolved blockers?
-3. If yes: assign every suitable straggler to the best-fit available role in one pass — do not drip-feed one issue per routine run.
+3. If yes: assign suitable items to available owners. Open PR count is advisory, not an assignment cap; keep every PR tied to an owner and next action.
 
 ## Best for
 
@@ -22,4 +22,4 @@ Primary assignment happens during backlog grooming: the Product Owner creates is
 
 ## Example
 
-The Product Owner normally assigns issues at creation during backlog grooming. If one slips through unassigned, the safety-net routine assigns it on the next pass and the assignee wakes on the assignment trigger.
+The Product Owner normally assigns issues at creation during backlog grooming. If one slips through unassigned, the safety-net routine assigns it on the next pass and the assignee wakes on the assignment trigger.

package/templates/modules/auto-assign/agents/ceo/heartbeat-section.md

@@ -2,4 +2,4 @@
 
 Primary assignment happens at backlog grooming — issues are assigned to the best-fit agent as they are created. This routine is a **safety net** that catches stragglers when the Product Owner hasn't acted.
 
-Do not scan for unassigned work during a normal heartbeat. If you are assigned a routine-run issue titled like "Auto-assign unassigned issues" and no Product Owner is available, use `$AGENT_HOME/skills/auto-assign.md`, then summarize assignments on the routine issue and exit.
+Do not scan for unassigned work during a normal heartbeat. If you are assigned a routine-run issue titled like "Auto-assign unassigned issues" and no Product Owner is available, use your installed `auto-assign-fallback` skill, then summarize assignments on the routine issue and exit.

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

@@ -4,13 +4,13 @@ Primary assignment happens at backlog grooming — issues are assigned to the be
 
 ## Assignment Check (Fallback)
 
-On your heartbeat, after handling your own assignments:
+Only on an explicitly assigned auto-assignment routine issue:
 
 1. Confirm this is the active routine-run issue and checkout it before mutating the board.
-2. Query unassigned ready issues: `GET /api/companies/{companyId}/issues?status=todo` (filter for unassigned).
+2. Query unassigned ready issues plus active implementation issues and open implementation PRs. Treat PR count as a queue-health signal, not a hard assignment limit.
 3. If unassigned issues are available AND the Product Owner hasn't acted recently:
-   - Assign every suitable still-unassigned issue to its best-fit available agent (an agent may hold a short queue): `PATCH /api/issues/{id}` with `assigneeAgentId` and an assignment comment.
-   - Clear stragglers in one pass instead of drip-feeding one issue per run.
+   - Assign suitable acceptance-ready issues to available owners: `PATCH /api/issues/{id}` with `assigneeAgentId` and an assignment comment.
+   - Keep later roadmap work prioritized but inactive; a safety net must not manufacture a queue that outruns the merge gate.
 4. If the Product Owner is active, skip this step.
 5. Leave a routine-run comment summarizing assigned issue ids and skipped issue ids.
 6. Mark the routine-run issue done when complete.
@@ -18,8 +18,8 @@ On your heartbeat, after handling your own assignments:
 ## Rules
 
 - This is a safety net behind backlog grooming's direct assignment. Let the PO own assignment.
-- Clear stragglers in one pass instead of drip-feeding one issue per run.
+- Treat implementation and review load as advisory scheduling input. Do not leave acceptance-ready work unassigned solely because other PRs are open, and never model open-PR count as blocker relations.
 - Do not run this from normal heartbeats.
 - Do not self-assign random unassigned work.
 - If no suitable match exists, leave the issue unassigned and state the reason in the routine-run comment.
-- Never archive or retire your own routine-run workspace. This is control-plane work via the API; do not `PATCH /api/execution-workspaces/{id}` to `archived` or remove the worktree your run uses — it fails the run's workspace validation and breaks the next reuse. Retirement is a board/operator action only.
+- Never archive or retire your own routine-run workspace. This is control-plane work via the API; do not `PATCH /api/execution-workspaces/{id}` to `archived` or remove the worktree your run uses — it fails the run's workspace validation and breaks the next reuse. Retirement is a board/operator action only.

package/templates/modules/auto-assign/agents/product-owner/heartbeat-section.md

@@ -2,4 +2,4 @@
 
 Primary assignment happens at backlog grooming — issues are assigned to the best-fit agent as they are created, not through this routine. This routine is a **safety net** that catches stragglers every 4 hours.
 
-Do not scan for unassigned work during a normal heartbeat. When you are assigned a routine-run issue titled like "Auto-assign unassigned issues", use `$AGENT_HOME/skills/auto-assign.md`, then summarize assignments on the routine issue and exit.
+Do not scan for unassigned work during a normal heartbeat. When you are assigned a routine-run issue titled like "Auto-assign unassigned issues", use your installed `auto-assign` skill, then summarize assignments on the routine issue and exit.

package/templates/modules/auto-assign/module.meta.json

@@ -17,7 +17,7 @@
   "routines": [
     {
       "title": "Auto-assign unassigned issues",
-      "description": "Safety-net routine-run checklist (primary assignment happens at backlog grooming, so this usually finds nothing): review any still-unassigned todo issues, assign each actionable item to its best-fit available agent based on role/workload — clear out all stragglers, not one at a time — record evidence and next actions on the routine issue, then exit.",
+      "description": "Safety-net routine-run checklist: review still-unassigned todo issues plus active implementation/review ownership, assign acceptance-ready work to available agents, keep every open PR tied to an owner and next action, record evidence and next actions on the routine issue, then exit. Open PR count is advisory, not an assignment cap.",
       "assignTo": "capability:auto-assign",
       "schedule": "0 */4 * * *",
       "priority": "medium",

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

@@ -9,11 +9,11 @@ Use this only when the current assigned issue/routine is titled like "Auto-assig
 ## Assignment Check
 
 1. Confirm this is the active routine-run issue and checkout it before mutating the board.
-2. Query available agents: `GET /api/companies/{companyId}/agents` and consider only active agents that are idle/available and within budget.
+2. Query available agents and current delivery ownership: active implementation issues per agent plus open implementation PRs per repository. Open PR count is advisory and must not freeze independent acceptance-ready work.
 3. Query candidate issues using the board's current issue API for unassigned `todo` work, scoped to the relevant project/goal when the routine has one.
 4. Skip issues that are blocked, awaiting approval/review, missing acceptance criteria, or already have active execution state.
 5. Match issue labels, required skills, project context, and priority to agent role/capabilities.
-6. Assign every suitable still-unassigned issue to its best-fit available agent (an agent may hold a short queue): `PATCH /api/issues/{id}` with `assigneeAgentId` and an assignment comment explaining why. As a safety net, clear out all stragglers in one pass rather than dispatching one at a time.
+6. Assign suitable acceptance-ready issues to available owners: `PATCH /api/issues/{id}` with `assigneeAgentId` and an assignment comment. Do not leave work unassigned solely because a repository already has open PRs, and never model open-PR count as `blockedByIssueIds`.
 7. Leave a routine-run comment summarizing assigned issue ids, skipped issue ids, and gaps needing Product Owner/CEO attention.
 8. Mark the routine-run issue done when complete.
 
@@ -23,5 +23,6 @@ Use this only when the current assigned issue/routine is titled like "Auto-assig
 - Do not self-assign random unassigned work.
 - Do not assign code tasks to non-engineering agents or security-sensitive work without security coverage.
 - Respect budgets, pause/cancel states, approval gates, `blockedByIssueIds`, and executionPolicy.
+- Do not create assigned queues that outrun implementation/review capacity, and do not self-create queue-drain, productivity, status, or watchdog wrapper issues.
 - If no suitable match exists, leave the issue unassigned and state the reason in the routine-run comment.
 - **Never archive or retire your own routine-run workspace.** This routine is pure control-plane work (assigning issues via the API); it needs no repository state. When done, mark the routine issue `done` and exit. Do not `PATCH /api/execution-workspaces/{id}` to `archived` and do not remove the worktree your run is using — archiving it mid-run fails the run's workspace validation and breaks the next reuse. Workspace retirement is a board/operator action only.

package/templates/modules/backlog/agents/ceo/heartbeat-section.md

@@ -1,3 +1,3 @@
 ## Backlog Health Routine Fallback
 
-Do not groom the backlog during a normal heartbeat unless that is your assigned issue. If you are assigned a routine-run issue titled like "Backlog grooming" and no Product Owner is available, use `$AGENT_HOME/skills/backlog-health.md`, then summarize generated/updated issues on the routine issue and exit.
+Do not groom the backlog during a normal heartbeat unless that is your assigned issue. If you are assigned a routine-run issue titled like "Backlog grooming" and no Product Owner is available, use your installed `backlog-health-fallback` skill, then summarize generated/updated issues on the routine issue and exit.

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

@@ -4,20 +4,20 @@ The Product Owner primarily manages the backlog pipeline. You are the fallback
 
 ## Backlog Health Check (Fallback)
 
-On your heartbeat, after handling assignments:
+Only on an explicitly assigned backlog-planning or backlog-grooming routine issue:
 
-1. Query unassigned issues: `GET /api/companies/{companyId}/issues?status=todo&unassigned=true`
-2. If fewer than 1 unassigned issue remains AND the Product Owner hasn't acted recently:
-   - Create 1-2 high-priority issues from the roadmap to keep engineers unblocked
-   - For each top-level issue (no `parentId`), include `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` so it gets its own worktree; subissues set `parentId` and omit it. Never create a top-level issue without it (it would inherit your checked-out workspace and block parallel work).
+1. Query unassigned issues plus active implementation issues and open implementation PRs.
+2. If owner/review capacity is free, no acceptance-ready next issue exists, and the Product Owner has not acted recently:
+   - Create only the next 1-2 high-priority issues from the roadmap
+   - For repository implementation, including subissues, request `"executionWorkspaceSettings": { "mode": "isolated_workspace" }` when the instance feature, project policy, and repository support it. Otherwise follow the rendered project policy and avoid concurrent shared-checkout writes. Reuse is explicit via `inheritExecutionWorkspaceFromIssueId` only when the task requires the same code change.
    - Attach `labelIds` — fetch available labels via `GET /api/companies/{companyId}/labels`. If no labels exist yet, create the defaults (see `backlog-health` skill for the label table) before creating issues.
-   - Comment on the issue tagging the Product Owner to take over backlog grooming
+   - Record the next backlog owner/action in the routine summary; use assignment for a required handoff, not an @-mention as a wake signal
 3. If the Product Owner is active and the backlog has 1+ issues, skip this step.
 
 ## Rules
 
 - This is a safety net, not your primary job. Let the PO own it.
-- Only create issues when engineers would otherwise have nothing to work on.
+- Assign acceptance-ready work to available owners. Open PR count is advisory and must not freeze independent implementation; keep every PR tied to an owner and next action.
 - Keep it minimal — just enough to unblock, not a full grooming session.
-- **Review handoff:** When moving an issue to `in_review`, always assign it to the reviewer. If the issue has an executionPolicy with review stages, Paperclip reassigns automatically. Otherwise PATCH `assigneeAgentId` to the reviewer before or at the same time as the status change.
-- Backlog grooming is intentionally project-detached and must remain API-only. Do not create or enter a git worktree for the grooming run, and do not attach the routine itself to a project. Setting `projectId` and isolated `executionWorkspaceSettings` on the work issues you create is still required and does not change the grooming run's workspace behavior.
+- **Review handoff:** Use `in_review` only with a non-author executionPolicy stage or a first-class human interaction/approval. Agent reassignment alone is not a valid no-policy review path; otherwise keep the issue `in_progress` for the concrete handoff or finish direct/self-merge delivery.
+- Backlog grooming is intentionally project-detached and must remain API-only. Do not create or enter a git worktree for the grooming run, and do not attach the routine itself to a project. Setting `projectId` and explicit workspace intent on repository work issues does not change the grooming run's workspace behavior.

package/templates/modules/backlog/agents/product-owner/heartbeat-section.md

@@ -1,3 +1,3 @@
 ## Backlog Health Routine
 
-Do not groom the backlog during a normal heartbeat unless that is your assigned issue. When you are assigned a routine-run issue titled like "Backlog grooming" or "Backlog health", use `$AGENT_HOME/skills/backlog-health.md`, then summarize generated/updated issues on the routine issue and exit.
+Do not groom the backlog during a normal heartbeat unless that is your assigned issue. When you are assigned a routine-run issue titled like "Backlog grooming" or "Backlog health", use your installed `backlog-health` skill, then summarize generated/updated issues on the routine issue and exit.