@routerhub/agent-rules 1.5.210 → 1.5.211

package/AGENTS.base.md

@@ -336,6 +336,10 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 
 ## PR 核心要求
 
+- ⚠️ **建 PR 前先自检「规则是否在场」——规则写得再全，不在你手里就等于不存在**：动手前先在自己的规则文件里搜一次 `详细实现文档`（`grep -l '详细实现文档' CLAUDE.md AGENTS.md .github/copilot-instructions.md`）。**搜不到就说明当前分支的规则集是旧的**（本条置顶链接规则自 `@routerhub/agent-rules` **v1.5.183** 起生效），**必须先升级规则再建 PR**（合并/变基主分支后重装依赖，postinstall 会重新生成 `CLAUDE.md` / `AGENTS.md`），禁止拿着旧流程把 PR 建完。落地动作见 `/create-pr` 步骤 0 的机械校验。
+    - **⚠️ 规则陈旧是静默故障，要当成一级怀疑对象**：旧规则集是**自洽的**——它能把 PR 完整建完、全程不报一个错，你只是少了一批铁律而毫无察觉。**判据是「手里少了什么」，不是「有没有报错」。** 一条铁律无法防止「这条铁律本身没被加载」，所以只能靠这一步主动去搜。
+    - **由来（PR #181 真实事故）**：该 PR 漏掉 Description 置顶文档链接，根因**不是规则没写**——规则当时已经在 `AGENTS.base.md` 与 `/create-pr` 步骤 5 里，而是该 PR 所在分支**落后主分支 65 个提交、依赖锁在 v1.5.170**，这条规则（v1.5.183）**比手里的规则集晚出生**，读到的 `CLAUDE.md` 里没有它、调用的也是旧版 skill，于是按一份完整的旧流程走完了全程。**规则陈旧时你手里少的不止这一条**，所以发现落后要整批升级，不要只补这一条。
+- ⚠️ **PR 建完后的第一个动作是自问「Description 第一行是不是那条 📄 链接」，不是就当场补**：⚠️ **缺这条链接的 PR 一律不算建完**，禁止交付 review、禁止进入发版流程——「正文已经写得很详细」不构成豁免，链接是**必备件**而非可选优化。
 - ⚠️ **每个 PR 的 Description 最顶部必须放一条醒目的「详细实现文档」链接（截图版 HTML→PDF），把 PR 分成「快速浏览」与「详细展开」两层看**：
     - **两层分工**：PR 正文只承载「快速浏览」——What / Why / Test Plan 精华 + 关键效果截图，让人几十秒内看懂这次改了什么；链接指向的 PDF 承载「详细展开」——本次做了什么 + 为什么这样做 + 每一步怎么做的完整实现过程，并配上带箭头标注的真实截图（遵循「⚠️ 截图规范」与「⚠️ 页面功能验证铁律」）。想深入细节的 reviewer 点开链接即看，不用在正文里翻流水账；也禁止只有正文、缺详细文档链接。
     - **位置与醒目度**：链接必须是 Description 第一条、独占一行、加粗高亮，放在任何正文段落之前，让 reviewer 打开 PR 第一眼就能看到。示意格式：`📄 详细实现文档（含箭头标注截图与逐步说明）：[点击查看](https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf)`。reviewer 建议在新标签页打开，看完细节再回正文。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routerhub/agent-rules",
-  "version": "1.5.210",
+  "version": "1.5.211",
   "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
   "main": "AGENTS.base.md",
   "bin": {

package/rules/global.md

@@ -336,6 +336,10 @@ agent-rules 生成的规则文件分两层，行为与归属不同，评审/发
 
 ## PR 核心要求
 
+- ⚠️ **建 PR 前先自检「规则是否在场」——规则写得再全，不在你手里就等于不存在**：动手前先在自己的规则文件里搜一次 `详细实现文档`（`grep -l '详细实现文档' CLAUDE.md AGENTS.md .github/copilot-instructions.md`）。**搜不到就说明当前分支的规则集是旧的**（本条置顶链接规则自 `@routerhub/agent-rules` **v1.5.183** 起生效），**必须先升级规则再建 PR**（合并/变基主分支后重装依赖，postinstall 会重新生成 `CLAUDE.md` / `AGENTS.md`），禁止拿着旧流程把 PR 建完。落地动作见 `/create-pr` 步骤 0 的机械校验。
+    - **⚠️ 规则陈旧是静默故障，要当成一级怀疑对象**：旧规则集是**自洽的**——它能把 PR 完整建完、全程不报一个错，你只是少了一批铁律而毫无察觉。**判据是「手里少了什么」，不是「有没有报错」。** 一条铁律无法防止「这条铁律本身没被加载」，所以只能靠这一步主动去搜。
+    - **由来（PR #181 真实事故）**：该 PR 漏掉 Description 置顶文档链接，根因**不是规则没写**——规则当时已经在 `AGENTS.base.md` 与 `/create-pr` 步骤 5 里，而是该 PR 所在分支**落后主分支 65 个提交、依赖锁在 v1.5.170**，这条规则（v1.5.183）**比手里的规则集晚出生**，读到的 `CLAUDE.md` 里没有它、调用的也是旧版 skill，于是按一份完整的旧流程走完了全程。**规则陈旧时你手里少的不止这一条**，所以发现落后要整批升级，不要只补这一条。
+- ⚠️ **PR 建完后的第一个动作是自问「Description 第一行是不是那条 📄 链接」，不是就当场补**：⚠️ **缺这条链接的 PR 一律不算建完**，禁止交付 review、禁止进入发版流程——「正文已经写得很详细」不构成豁免，链接是**必备件**而非可选优化。
 - ⚠️ **每个 PR 的 Description 最顶部必须放一条醒目的「详细实现文档」链接（截图版 HTML→PDF），把 PR 分成「快速浏览」与「详细展开」两层看**：
     - **两层分工**：PR 正文只承载「快速浏览」——What / Why / Test Plan 精华 + 关键效果截图，让人几十秒内看懂这次改了什么；链接指向的 PDF 承载「详细展开」——本次做了什么 + 为什么这样做 + 每一步怎么做的完整实现过程，并配上带箭头标注的真实截图（遵循「⚠️ 截图规范」与「⚠️ 页面功能验证铁律」）。想深入细节的 reviewer 点开链接即看，不用在正文里翻流水账；也禁止只有正文、缺详细文档链接。
     - **位置与醒目度**：链接必须是 Description 第一条、独占一行、加粗高亮，放在任何正文段落之前，让 reviewer 打开 PR 第一眼就能看到。示意格式：`📄 详细实现文档（含箭头标注截图与逐步说明）：[点击查看](https://github.com/<ORG>/<项目>-docs/blob/docs/<文件名>.pdf)`。reviewer 建议在新标签页打开，看完细节再回正文。

package/skills/create-pr/SKILL.md

@@ -16,6 +16,26 @@ description: >-
 
 ## 核心流程
 
+### 0. 规则在场自检（机械校验，禁止跳过）
+
+⚠️ **建 PR 之前先跑一遍，确认手里的规则集不是旧的。** 旧规则集是**自洽的**——它能把 PR 完整建完、全程不报一个错，你只是少了一批铁律而毫无察觉。**判据是「手里少了什么」，不是「有没有报错」。**
+
+```bash
+# ① 铁律是否在场：三个规则文件里任意一个能搜到「详细实现文档」即通过
+grep -l '详细实现文档' CLAUDE.md AGENTS.md .github/copilot-instructions.md 2>/dev/null
+
+# ② 规则版本新鲜度：当前分支 vs 远程默认分支（默认分支名不写死，从 origin/HEAD 取）
+base=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo origin/main)
+cur=$(grep -o '"@routerhub/agent-rules": "[^"]*"' package.json 2>/dev/null | grep -o '[0-9][0-9.]*')
+ref=$(git show "$base:package.json" 2>/dev/null | grep -o '"@routerhub/agent-rules": "[^"]*"' | grep -o '[0-9][0-9.]*')
+echo "当前分支: ${cur:-未声明}  /  $base: ${ref:-未声明}"
+```
+
+- ① 无输出（三个文件都搜不到），或 ② 当前分支版本落后于远程默认分支 → **中止，先升级规则再建 PR**：合并/变基远程默认分支后重装依赖（`pnpm install`），postinstall 会重新生成 `CLAUDE.md` / `AGENTS.md`。**发现落后要整批升级，不要只补这一条——陈旧时你手里少的不止这一条。**
+- 两边一致 → 通过，继续步骤 1。
+
+⚠️ **本步骤的由来（PR #181 真实事故）**：该 PR 漏掉 Description 置顶「详细实现文档」链接，根因**不是规则没写**——规则当时已经在 `AGENTS.base.md` 与 `create-pr` 步骤 5 里，而是该 PR 所在分支**落后主分支 65 个提交、依赖锁在 `@routerhub/agent-rules` v1.5.170**，而这条规则自 **v1.5.183** 起才生效，**比手里的规则集晚出生**——读到的 `CLAUDE.md` 里没有它、调用的也是旧版 skill，于是按一份完整的旧流程走完了全程。**一条铁律无法防止「这条铁律本身没被加载」**，所以必须用这一步主动去搜。
+
 ### 1. 收集改动信息
 
 ```bash
@@ -162,6 +182,8 @@ gh pr checks <PR>
 - ⚠️ 一个 PR 只做一件事
 - ⚠️ PR 所有文字内容必须中文
 - ⚠️ 必须附截图作为可视化证据
+- ⚠️ **建 PR 前先做步骤 0 的规则在场自检**：规则文件里搜不到 `详细实现文档`，或当前分支规则版本落后远程默认分支 → 先升级规则再建 PR。规则陈旧是静默故障，不报错不等于没缺东西。
+- ⚠️ **PR 建完后的第一个动作是自问「Description 第一行是不是那条 📄 链接」，不是就当场补**：⚠️ **缺这条链接的 PR 一律不算建完**，禁止交付 review、禁止进入发版流程——「正文已经写得很详细」不构成豁免，链接是**必备件**而非可选优化。
 - ⚠️ **PR Description 顶部必须附「详细实现文档」链接（截图版 HTML→PDF，见步骤 5）**：PR 正文只承载快速浏览，链接展开「做了什么 + 为什么 + 每一步怎么做的」完整细节
 - ⚠️ 截图禁止提交到 Git 仓库
 - ⚠️ PR 截图直接内嵌在 Description 正文中（Markdown 图片语法）