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

package/package.json

@@ -1,9 +1,22 @@
 {
   "name": "@starlein/paperclip-plugin-company-wizard",
-  "version": "0.3.20",
+  "version": "0.3.22",
   "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/code-reviewer/skills/code-review.md

@@ -18,7 +18,7 @@ You review PRs for correctness, security, code quality, and simplicity. You are
 2. Record your verdict on your review stage:
    - **approved** if the code meets quality standards
    - **changes_requested** with specific, actionable feedback if not
-3. Optionally mirror the same verdict as a GitHub PR comment for visibility.
+3. Optionally mirror the verdict as a GitHub PR comment — write it to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
 
 ## Rules
 

package/templates/modules/pr-review/agents/devops/skills/infra-review.md

@@ -19,7 +19,7 @@ You review PRs for infrastructure impact, performance, security, and operational
 3. Record your verdict on your review stage:
    - **approved** if operationally sound
    - **changes_requested** with specific concerns if not
-4. Optionally mirror the same verdict as a GitHub PR comment for visibility.
+4. Optionally mirror the verdict as a GitHub PR comment — write it to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
 
 ## Rules
 

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

@@ -8,15 +8,16 @@ When this skill is active, you work in feature branches and open PRs instead of
 2. Create branch: `git checkout -b <prefix>-<N>/<short-description>`
 3. Make your changes, commit with Conventional Commits format
 4. Push branch: `git push -u origin <branch-name>`
-5. Open PR: `gh pr create --title "<type>: <description>" --body "<template>"`
-6. Set the originating issue's `executionPolicy` to gate the merge on review:
+5. Open PR: write the body (PR Body Template in `docs/pr-conventions.md`) to a file, then `gh pr create --title "<type>: <description>" --body-file <file>`. Never inline `--body "..."` — a double-quoted shell string keeps `\n` literal and the PR renders as `text\ntext` (see *Posting PR Bodies & Comments*).
+6. Set the originating issue's `executionPolicy` to gate the merge on review, ending with your own merge gate:
    - One `review` stage with the **Code Reviewer** as participant (always).
    - Additional `review` stages for any relevant domain reviewer that exists in the team (UI Designer for UI diffs, UX Researcher for flow changes, QA for logic/test-sensitive changes, DevOps for infra/deploy/dependency changes).
-   - 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/agents/product-owner/skills/product-review.md

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

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

@@ -19,7 +19,7 @@ You review PRs for test coverage, edge cases, and regression risk. When a PR cha
 3. Record your verdict on your review stage:
    - **approved** if quality is adequate
    - **changes_requested** with specific gaps and suggested test cases if not
-4. Optionally mirror the same verdict as a GitHub PR comment for visibility.
+4. Optionally mirror the verdict as a GitHub PR comment — write it to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
 
 ## Rules
 

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

@@ -19,7 +19,7 @@ You review PRs for visual quality, brand consistency, and accessibility. When a
 3. Record your verdict on your review stage:
    - **approved** if visually sound
    - **changes_requested** with specific, actionable feedback if not
-4. Optionally mirror the same verdict as a GitHub PR comment for visibility.
+4. Optionally mirror the verdict as a GitHub PR comment — write it to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
 
 ## Rules
 

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

@@ -19,7 +19,7 @@ You review PRs for usability, user flow integrity, and alignment with user needs
 3. Record your verdict on your review stage:
    - **approved** if usability is sound
    - **changes_requested** with specific, actionable feedback if not
-4. Optionally mirror the same verdict as a GitHub PR comment for visibility.
+4. Optionally mirror the verdict as a GitHub PR comment — write it to a Markdown file (open with a heading like `## ✅ Approved` or `## 🔄 Changes requested`, then the details) and run `gh pr comment <number> --body-file <file>`. Never use inline `--body "..."`: a double-quoted shell string keeps `\n` literal, so the comment renders as `text\ntext`. See `docs/pr-conventions.md` → *Posting PR Bodies & Comments*.
 
 ## Rules
 

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

@@ -38,6 +38,24 @@ Rules: lowercase after colon, no period, under 72 chars.
 Closes [PREFIX-N]
 ```
 
+## Posting PR Bodies & Comments
+
+Always pass Markdown through a **file** (`--body-file`), never an inline `--body "..."`. A double-quoted shell argument does **not** turn `\n` into a real newline, so an inline body renders on GitHub as literal `text\ntext\ntext` instead of formatted Markdown. Write the body to a file first:
+
+```bash
+# Real newlines + full Markdown (headings, lists, code blocks) preserved.
+cat > /tmp/pr-body.md <<'EOF'
+## What changed
+...
+EOF
+
+gh pr create  --title "<type>: <description>" --body-file /tmp/pr-body.md
+gh pr comment <number> --body-file /tmp/pr-body.md
+gh pr review  <number> --request-changes --body-file /tmp/pr-body.md
+```
+
+Every PR comment opens with a Markdown heading stating the verdict (`## ✅ Approved`, `## 🔄 Changes requested`, or `## 💬 Review notes`), followed by a short summary and bullet points or code blocks.
+
 ## Labels
 
 Apply one primary label: `feature`, `bug`, `docs`, `chore`, `infra`, `agent`.
@@ -47,13 +65,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`.
+7. Verdicts are recorded on the stages and may be mirrored as PR comments (always via `--body-file`; see *Posting PR Bodies & Comments*).
+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 +90,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."
     }
   ]
 }

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

@@ -15,7 +15,7 @@ You report to the CEO.
    - **Security**: Any injection, XSS, credential exposure, or OWASP risks?
    - **Style**: Consistent with existing codebase patterns?
    - **Simplicity**: Is there unnecessary complexity? Could it be simpler?
-6. Post your review using `gh pr review <number> --approve` or `gh pr review <number> --request-changes --body "<feedback>"`.
+6. Post your review: `gh pr review <number> --approve`, or to request changes write your feedback to a Markdown file (start with a heading, e.g. `## 🔄 Changes requested`) and run `gh pr review <number> --request-changes --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.
 7. Post your verdict on the originating issue.
 8. Mark your issue as `done`.