From 31fcbb79dceb1fe94872962e981a753df175620c Mon Sep 17 00:00:00 2001
From: Suzumiya <suzmii@qq.com>
Date: Sat, 12 Sep 2026 01:28:05 +0800
Subject: [PATCH] =?UTF-8?q?pitfalls=EF=BC=9A=E8=AE=B0=E4=B8=80=E6=9D=A1?=
 =?UTF-8?q?=E3=80=8C=E5=8F=AA=E8=B7=91=E9=97=A8=E7=A6=81=E5=AD=90=E9=9B=86?=
 =?UTF-8?q?=20=E2=86=92=20=E5=90=8C=E4=B8=80=E5=A4=A9=E4=B8=A4=E6=AC=A1=20?=
 =?UTF-8?q?CI=20=E7=BA=A2=E3=80=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 现象：dd7cf401a 给 lint-staged 加 *.rs 键，但本地从未跑过 check:git-hooks（它是 npm run lint 链里的一环），而 scripts/git-hooks.test.mjs 用 assert.deepEqual 钉住 lint-staged 的整份配置形状 → CI 以 deepStrictEqual 失败；本批更早还因 check:rustfmt 红过一次（15660a98b 修 8 处格式偏差），成因是 pre-commit 的 lint-staged 当时只覆盖 *.{js,mjs,cjs,ts,tsx}，Rust 格式本地无守卫
- 原因：npm run lint 是一条 && 长链（encoding / npm-workspaces / git-hooks / rustfmt / spacetime-schema / production-ops / preview-deployer / maintenance-page / eslint / typecheck），中间任一步失败则其后步骤根本不执行，「跑到第 N 步就以为本地绿了」；更隐蔽的是本地若因环境原因在中间断掉（如 Windows 上 check:git-hooks 第 2 个用例的 EBUSY），后面那些本来能通过的步骤也从未被验证
- 处理：push 前按完整链路跑；&& 链在某一步失败时，必须把失败步之后的每一步单独再跑一遍（10 步 + git diff --check）并逐条记 exit code（取 exit code 不要接管道）；改动碰到 package.json / .husky/ / scripts/ 下的门禁资产时，check:git-hooks 是必跑项
- 验证：本次 check:git-hooks 因本机 Windows EBUSY 中断后，补跑其后各步全部 exit 0（spacetime-schema / production-ops / preview-deployer / maintenance-page / lint:eslint / typecheck / encoding），只有 check:rustfmt 红且红在别人在途的 .rs（assets.rs:519 落在其未提交 hunk +470,62、commands.rs:3079 落在其未提交 hunk +3068,58）；变异验证：把 *.rs 从 package.json 摘掉 → 第 1 个用例以同样的 deepStrictEqual operator 变红，还原（SHA256 一致）后回 ok
- 纯文档追加：文件末尾 +8 行、无删改；本条只提交 docs/project-memory/shared-memory/pitfalls.md 一个路径
---
 docs/project-memory/shared-memory/pitfalls.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index 49f221119..d9c30e5ec 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -5347,3 +5347,11 @@
 - **验证**：用内容级复核定案——`git show 28781a420 -- <file> | Select-String '^@@'` 得到两个 hunk；`git show` 的 `^-` 行里出现对方特有的 `data-resource-book-all-page` / `allSections` 字样。这同时排除了另一种解释（"只是 prettier 重排"）：重排会表现为 `-`/`+` 成对出现且**语义相同**，而这里 `-` 掉的断言在 `+` 侧并不存在。
 - **关联**：提交 `28781a420`、`apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts`、`package.json` 的 `format:staged`（lint-staged 配置）。
 
+## 2026-09-12 只跑门禁子集 → 同一天两次 CI 红：本地必须按 npm run lint 的完整链路跑齐
+
+- **现象**：同一天两次 Repository checks 红，都不是代码写错，而是「本地只跑了门禁的一个子集」：① `dd7cf401a` 给 lint-staged 加了 `*.rs` 键，**本地从未跑过 `check:git-hooks`**（它是 `npm run lint` 链里的一环），而 `scripts/git-hooks.test.mjs` 用 `assert.deepEqual` 钉住 lint-staged 的**整份配置形状** → CI 以 `deepStrictEqual` 失败；② 本批更早还因 `check:rustfmt` 红过一次（`15660a98b` 修掉 8 处格式偏差），成因是 pre-commit 的 lint-staged 当时只覆盖 `*.{js,mjs,cjs,ts,tsx}`，Rust 格式在本地没有任何守卫。
+- **原因**：`npm run lint` 是一条 `&&` 长链 —— `check:encoding && check:npm-workspaces && check:git-hooks && check:rustfmt && check:spacetime-schema && check:production-ops && check:preview-deployer && check:maintenance-page && lint:eslint && typecheck`（其中 `check:git-hooks` = `node --test scripts/git-hooks.test.mjs`）。**只要中间某一步失败，它之后的步骤根本不会执行**，于是「跑到第 N 步就以为本地绿了」；而 CI 的 Repository checks 跑的是 `scripts/check-repository-ci.sh` → `SPACETIME_SCHEMA_BASE_REF=… npm run lint`（外加 `appSurface.test.ts`、`npm run build`、基线到候选提交的 `git diff --check`）。更隐蔽的是：本地若因**环境原因**在中间断掉（如 Windows 上 `check:git-hooks` 第 2 个用例的 EBUSY），**后面那些本来能通过的步骤也从未被验证过**。
+- **处理**：push 前按链路逐条跑，不要只跑子集；`&&` 链在某一步失败时，**必须把失败步之后的每一步单独再跑一遍**（上列 10 步 + `git diff --check`），逐条记 exit code（取 exit code 不要接管道）。凡改动碰到 `package.json` / `.husky/` / `scripts/` 下的门禁资产，**`check:git-hooks` 是必跑项**——它钉住 hook 与 lint-staged 配置的形状，增删键都会让它以 `deepStrictEqual` 失败。
+- **验证**：本次 `check:git-hooks` 因本机 Windows EBUSY 中断后，把其后各步单独跑齐：`check:spacetime-schema` / `check:production-ops` / `check:preview-deployer` / `check:maintenance-page` / `lint:eslint` / `typecheck` / `check:encoding` 全部 `exit 0` —— 即「因为前一步红而没跑到」的部分本来是全绿的；只有 `check:rustfmt` 红，且红在别人在途的 `.rs`（`assets.rs:519` 落在其未提交 hunk `+470,62`、`commands.rs:3079` 落在其未提交 hunk `+3068,58`）。变异验证：把 `*.rs` 从 `package.json` 摘掉 → `check:git-hooks` 第 1 个用例以同样的 `deepStrictEqual` operator 变红（`# fail 2`）；还原（`package.json` SHA256 与改前一致）后该用例回 `ok`。
+- **关联**：`package.json` 的 `lint` / `check:git-hooks` / `check:rustfmt`、`scripts/check-repository-ci.sh`、`scripts/git-hooks.test.mjs`、`.husky/pre-commit`、提交 `dd7cf401a` / `2a7bfadd7` / `15660a98b`。
+