prepare-paperclip-pr

准备 Paperclip PR

Paperclip 的标准流程：将分支上的工作整理成针对 paperclipai/paperclip master 的已审查且通过检查的拉取请求。每个 PR 执行一次（如果一项任务将一个分支拆分成多个 PR，则每个 PR 都要完整执行此流程）。

0. 前提条件——工作树安全

• 所有 PR 工作都必须在专用分支上的 git worktree 中进行。主 ~/paperclip 检出通常运行着在线 Paperclip 服务——绝不要在那里切换分支。如果你当前已在 worktree/分支中，请验证（git rev-parse --git-dir、git branch --show-current）后继续。
• 如果主检出意外地不在 master 上，应先妥善处理，不要丢失工作（通常是将该分支上的工作移到 worktree 中）。
• 确认目标 remote/ref（通常是 paperclipai/paperclip 仓库中的 master；任务可能会指定特定 remote，例如 origin 或 public-gh）。

1. 提交所有更改——不要丢失工作

• 首先将所有未提交的更改整理成逻辑提交。不要 stash 后忘记恢复；不要留下文件。如果缺少提交，就创建提交。
• 提交消息必须以以下内容结尾，且内容必须完全一致： Co-Authored-By: Paperclip <[email protected]>

2. 将更改干净地放到 master 之上

• 获取目标 remote，并将你的分支 rebase（或以其他方式重放）到目标 master 之上，确保 PR 没有合并冲突。
• rebase 后再次验证：相关构建/测试仍然通过，深度应符合任务需要。

3. 防护措施检查清单（每个 PR 都适用）

• 绝不要提交 pnpm-lock.yaml——仓库中有相应操作会管理它。如果它已包含在某个提交中，推送前应重写或删除该更改。
• 除非底层提交明确涉及此内容且任务有明确要求，否则绝不要更改 .github/workflows/*。
• 除非设计截图/线框图确实属于工作成果，否则不要将其提交到仓库。
• 迁移：编号应递增，且不得与 master 冲突。如果 master 有更新并占用了你的编号，应在其基础上重新编号。迁移必须具备幂等性，以确保已应用旧编号的用户不会遇到问题。
• Greptile 文件数量限制：每个 PR 的变更文件数应少于 100；如果超过，应拆分成两个 PR。

4. 创建 PR

• 按照 CONTRIBUTING.md（仓库根目录， https://github.com/paperclipai/paperclip/blob/master/CONTRIBUTING.md）中的要求，编写 PR 标题、消息格式和问题描述。
• 推送分支，并使用 gh 创建 PR。
• 立即记录 PR URL——每份报告都必须包含所有 PR 的 URL。

5. 审查循环

• 运行公司技能 /greploop：触发 Greptile 审查、处理其评论、推送，然后重复，直到 Greptile 达到 5/5 且没有未解决的评论（最多 20 轮）。只要还有剩余轮次，就不要提前停止。
• 然后运行公司技能 /prcheckloop，并处理你能解决的验证/CI 失败。
• 持续运行 GREPTILE，直到达到 5/5——GREPTILE 达到 5/5、所有测试通过、所有验证检查通过且不存在合并冲突后，方可停止。

6. 汇报并交接

• 在驱动任务上发表评论，说明你完成了什么、PR URL、worktree 路径（主目录用 ~ 表示）、Greptile 评分和检查状态。
• 为每个已创建的 PR 创建一个 pull_request 工作成果（如果分支或提交本身作为交接内容，还应创建 branch / commit 工作成果）。
• 如果任务要求针对每个 PR 进行后续处理（例如为每个 PR 创建子问题），请按任务要求创建并关联。

硬性规则

• 绝不要丢失工作：不要遗留无人管理的 stash、不要丢弃文件、不要通过强制推送丢弃提交。
• 始终提供你创建的所有拉取请求的 URL。