@starlein/paperclip-plugin-company-wizard 0.3.20 → 0.3.21

package/package.json

@@ -1,9 +1,22 @@
 {
   "name": "@starlein/paperclip-plugin-company-wizard",
-  "version": "0.3.20",
+  "version": "0.3.21",
   "type": "module",
   "description": "AI-powered wizard to bootstrap paperclip agent companies from composable templates (for latest paperclip version)",
   "repository": "https://github.com/starlein/paperclip-plugin-company-wizard",
+  "scripts": {
+    "build": "node ./esbuild.config.mjs",
+    "build:rollup": "rollup -c",
+    "dev": "node ./esbuild.config.mjs --watch",
+    "dev:ui": "paperclip-plugin-dev-server --root . --ui-dir dist/ui --port 4177",
+    "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",
+    "publish:npm": "npm publish --access public",
+    "prepublishOnly": "pnpm build:prod",
+    "prepare": "husky"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -64,16 +77,5 @@
     "@paperclipai/shared": ">=2026.529.0",
     "react": ">=18",
     "react-dom": ">=18"
-  },
-  "scripts": {
-    "build": "node ./esbuild.config.mjs",
-    "build:rollup": "rollup -c",
-    "dev": "node ./esbuild.config.mjs --watch",
-    "dev:ui": "paperclip-plugin-dev-server --root . --ui-dir dist/ui --port 4177",
-    "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",
-    "publish:npm": "npm publish --access public"
   }
-}
+}

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

@@ -21,6 +21,18 @@ Rules:
 - Under 72 characters
 - Reference issue ID in commit body when applicable
 
+## Repository Hygiene: ignore `.paperclip/`
+
+Paperclip stores per-issue git worktrees and workspace metadata under a `.paperclip/`
+directory inside the repository. This must never be committed.
+
+- When preparing the repository (fresh or existing), make sure `.gitignore` contains a
+  `.paperclip/` line. Add it before the first commit; create `.gitignore` if missing.
+- If `.paperclip/` was already committed, remove it from tracking with
+  `git rm -r --cached .paperclip` and commit the removal.
+- Committing `.paperclip/` pollutes history and can nest isolated worktrees inside the
+  repo, which causes confusing git state for every agent.
+
 ## Direct-to-Main Workflow
 
 1. Pull latest from main

package/templates/modules/github-repo/module.meta.json

@@ -9,7 +9,7 @@
       "priority": "critical",
       "bootstrapPhase": "foundation",
       "labels": ["chore"],
-      "description": "Foundation setup: handle this before normal implementation issues. For a fresh repository, create the GitHub repository, initialize local workspace with a README or bootstrap commit, add origin, push main, and record the repository URL. For an existing repository, verify the workspace has a reachable remote, current default branch, and starter commit state; escalate to CEO if repo setup is missing instead of silently closing the issue. Branch protection is tracked separately by the pr-review module when that workflow is enabled."
+      "description": "Foundation setup: handle this before normal implementation issues. For a fresh repository, create the GitHub repository, initialize local workspace with a README or bootstrap commit, add origin, push main, and record the repository URL. For an existing repository, verify the workspace has a reachable remote, current default branch, and starter commit state; escalate to CEO if repo setup is missing instead of silently closing the issue. Before the first commit, ensure the repository's `.gitignore` ignores Paperclip's local state — add a `.paperclip/` entry (this is where Paperclip keeps per-issue git worktrees and workspace metadata inside the repo; committing it pollutes history and can nest worktrees inside the repo). Create `.gitignore` if it is missing. Branch protection is tracked separately by the pr-review module when that workflow is enabled."
     }
   ]
 }

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

@@ -9,14 +9,15 @@ When this skill is active, you work in feature branches and open PRs instead of
 3. Make your changes, commit with Conventional Commits format
 4. Push branch: `git push -u origin <branch-name>`
 5. Open PR: `gh pr create --title "<type>: <description>" --body "<template>"`
-6. Set the originating issue's `executionPolicy` to gate the merge on review:
+6. Set the originating issue's `executionPolicy` to gate the merge on review, ending with your own merge gate:
    - One `review` stage with the **Code Reviewer** as participant (always).
    - Additional `review` stages for any relevant domain reviewer that exists in the team (UI Designer for UI diffs, UX Researcher for flow changes, QA for logic/test-sensitive changes, DevOps for infra/deploy/dependency changes).
-   - A final `approval` stage with the **Product Owner** as participant (always).
+   - An `approval` stage with the **Product Owner** as participant (always) — the product sign-off.
+   - A final `approval` stage with **yourself (the Engineer)** as participant — the **merge gate**. This stage exists so you are woken *last*, after every reviewer and the Product Owner have cleared, to perform the merge.
    - Resolve each role to its agentId first (look up active agents), then set the policy on the issue. Include the PR link in an issue comment so reviewers can find it.
 7. Move the originating issue to `in_review`.
-8. Wait for the issue to clear its stages. Each reviewer records `approved` or `changes_requested` on their stage; verdicts may be mirrored as PR comments.
-9. When all stages are approved (no `changes_requested` outstanding): `gh pr merge <number> --merge`, then set the issue to `done`.
+8. Wait for the issue to clear its review/approval stages. Each reviewer and the Product Owner records `approved` or `changes_requested`; verdicts may be mirrored as PR comments. A `changes_requested` routes the issue back to you — address it, push to the same branch, and that stage re-runs.
+9. When the issue reaches your final **merge gate** stage (you are the current participant and every prior stage is approved): run `gh pr merge <number> --merge`, confirm the merge landed, **then** record `approved` on your stage — that closes the issue to `done`. Never record `approved` before the merge has actually succeeded, and never set the issue to `done` with the PR still open.
 
 ## Rules
 
@@ -25,5 +26,6 @@ When this skill is active, you work in feature branches and open PRs instead of
 - Always include `Closes [PREFIX-N]` in the PR body.
 - If a reviewer requests changes, address them, push to the same branch, and re-request review (the stage re-runs).
 - You are the merge owner — never ask reviewers to merge.
+- **Your merge gate must be the last stage.** The Product Owner's `approval` is the product sign-off, not the final stage. If it were last, their verdict would auto-close the issue to `done` and you would never be woken to merge — leaving the PR open on GitHub. Always append your own merge-gate `approval` stage after the Product Owner's, and do the merge there before recording your verdict.
 - Do not create separate child review issues and do not use @-mentions to request review; the executionPolicy stages are the governance signal.
 - Do not wait for GitHub-native approving reviews when all agents share the same GitHub credential; GitHub rejects self-approval. The Paperclip executionPolicy stages are the required signal unless a separate non-author GitHub reviewer credential is explicitly available.

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

@@ -47,13 +47,13 @@ Apply one primary label: `feature`, `bug`, `docs`, `chore`, `infra`, `agent`.
 Review runs through the issue's native `executionPolicy` (stages), not separate child issues:
 
 1. **Engineer** opens the PR on GitHub.
-2. **Engineer** sets the originating issue's `executionPolicy`: a `review` stage for the Code Reviewer, optional `review` stages for relevant domain reviewers (UI Designer / UX Researcher / QA / DevOps), and a final `approval` stage for the Product Owner. Reviewer/approver roles are resolved to agentIds. The PR link is added as an issue comment.
+2. **Engineer** sets the originating issue's `executionPolicy`: a `review` stage for the Code Reviewer, optional `review` stages for relevant domain reviewers (UI Designer / UX Researcher / QA / DevOps), an `approval` stage for the Product Owner (product sign-off), and a final `approval` stage for the **Engineer** as the merge gate. Reviewer/approver/merge-owner roles are resolved to agentIds. The PR link is added as an issue comment.
 3. **Engineer** sets the originating issue to `in_review`.
 4. **Code Reviewer** reviews for correctness, security, code style, simplicity and records `approved` / `changes_requested` on the review stage.
 5. **Domain reviewers** (when present as stages) review their concern and record their verdict.
 6. **Product Owner** reviews for intent match, scope discipline, acceptance criteria, and records the final `approval` verdict.
 7. Verdicts are recorded on the stages and may be mirrored as PR comments.
-8. **Engineer** merges when all stages are approved (no `changes_requested` outstanding), then sets the originating issue to `done`.
+8. **Engineer** owns the final `approval` stage (merge gate): once every reviewer and the Product Owner has approved, the engineer is woken last, merges the PR, confirms the merge landed, and only then records `approved` — which closes the originating issue to `done`. The merge must happen before the issue is `done`.
 
 ## Review Roles
 
@@ -72,6 +72,7 @@ Reviewers may also add a PR comment, but GitHub-native approving reviews require
 - No force pushes
 - Merge using `gh pr merge <number> --merge`
 - Engineer is the merge owner — reviewers never merge
+- The engineer's merge gate must be the **last** `approval` stage. If the Product Owner's approval were last, it would auto-close the issue to `done` and the merge would be skipped, leaving the PR open on GitHub.
 
 ## Dev Cycle Rules
 

package/templates/modules/pr-review/module.meta.json

@@ -21,9 +21,10 @@
       "assignTo": "engineer",
       "reviewGate": {
         "reviewers": ["code-reviewer"],
-        "approver": "product-owner"
+        "approver": "product-owner",
+        "mergeGate": "engineer"
       },
-      "description": "Document and verify the PR workflow: feature branches, PR links, and review via the issue's executionPolicy — a review stage for the Code Reviewer (plus relevant domain reviewers) and a final approval stage for the Product Owner, with engineer-owned merges once all stages clear. Optional branch protection may disable direct pushes or require CI, but do not require GitHub-native approving reviews unless the project has distinct non-author GitHub reviewer credentials."
+      "description": "Document and verify the PR workflow: feature branches, PR links, and review via the issue's executionPolicy — a review stage for the Code Reviewer (plus relevant domain reviewers), an approval stage for the Product Owner, and a final approval stage for the Engineer as the merge gate (the engineer is woken last to merge the PR before recording approval, which closes the issue). The merge gate must be the last stage so the Product Owner's approval does not auto-close the issue with the PR still open. Optional branch protection may disable direct pushes or require CI, but do not require GitHub-native approving reviews unless the project has distinct non-author GitHub reviewer credentials."
     }
   ]
 }