# 2026-05-12 — Slot 工作流的 cwd 坑 + Schema 变更被 pre-commit hook 三连拦截

## 背景

修系列会议两个 bug 时，在 slot-5 worktree 里并行做两条分支（hotfix + feature）的过程中踩了两组坑，整顿了两次。

## 坑 1：bash 命令 cwd 不持久，导致主仓库与 slot 状态错乱

### 现象

`git stash push`、`git switch <branch>`、`git stash pop` 一连串命令以为在 slot-5 跑，实际在 main repo 跑——因为前一个 `cd backend && npm run build` 的下一个 Bash call 不继承 cwd，默认回到 `/home/chentao/Code/workspace`（main repo）。结果：
- Bug 1 stash 被恢复到 main repo 工作树（不是 slot-5）
- Bug 2 提交 commit message 是 Bug 1 的，但内容是 Bug 2（只 1 个文件，因为 slot-5 当时只有 Bug 2 的 series.service.ts）
- 修复成本：抢救 patches 到 `/tmp/`，硬 reset，重做

### 教训 / 可复用做法

每个涉及 git 状态变更的 Bash call **必须**绝对路径 `cd` 前缀：

```bash
# 错（cwd 不持久）：
git stash push -u && git switch <branch> && git stash pop

# 对：
cd /home/chentao/Code/ffworkspace-wt/.agent-pool/slot-N && \
  git stash push -u && git switch <branch> && git stash pop
```

或者把整条流程塞一个脚本里，从外面 `bash scripts/foo.sh`，由脚本内 `cd` 一次。

**另一个救命习惯**：每次切分支 / pop stash 之后立刻 `git branch --show-current && git status --short` 双重验证，别假设 `git switch` 的 stdout 反映了真实当前 cwd 的仓库。

## 坑 2：pre-commit hook 链式拦截，每加一层才暴露下一层

修一个 service 文件，pre-commit hook 按顺序拦了三次：

1. **assertAccess 静态契约检查** — `prisma.X.deleteMany(` 必须有 `assertAccess` 调用或方法上加 `@SkipAssertAccess('原因')`。规则文档 `docs/standards/09-iam-security.md §7.1 / §8 禁止事项 #10`。
2. **API 端点 docs 缺失** — `controllers/*.ts` 新增端点没在 `docs/modules/{module}/07-api.md` 找到对应章节会列 warning（mode=warn，不阻断）。
3. **DataScope 标准字段契约** — 新建 model 缺 `id / createdAt / updatedAt / createdById / organizationId` 五个强制字段，关联表 / 字典表豁免方式是 model 上方加 `/// @skip-data-scope <原因>` 注释。

### 教训

- 改后端文件之前先 grep `@SkipAssertAccess` 在该模块的使用，了解豁免理由模板
- 改 schema 加新 model 前先看 `docs/standards/04-database-architecture.md「标准字段」` —— 关联表 / 字典表先一并加 `/// @skip-data-scope` 注释，省一次 commit retry
- `assertAccess` hook 触发不依赖你是否新增了 `deleteMany`，而是"修改的文件里包含 `deleteMany` 的方法"——pre-existing 代码也会被扫到。所以即使本次 PR 不动 deleteMany 那行，只要那个方法在 staging 的文件里，hook 就触发

### 可复用清单（schema 新增 model 时）

豁免标记速查：
- `/// @skip-data-scope IAM 配置表` — IAM 治理类
- `/// @skip-data-scope 关联表，无业务归属` — junction / lookup
- `/// @skip-data-scope 事件流型表（系统观察记录，非用户操作）` — audit / event log
- 真业务表必须老老实实加 5 个标准字段（参考 `docs/standards/04-database-architecture.md`）

## 跨坑共通

两坑都揭示一个模式：**项目里有大量"半隐式"约束**（pre-commit、CI、契约检查、文档同步、cwd 行为）。AI 默认走"实现 + commit"会反复撞墙。改进做法：

- 大改动开工前先 `cd <slot>` 一次到位 + `bash --rcfile`（不靠环境变量传 cwd）
- 写 schema / controller 之前先扫一遍 `docs/standards/` 下相关条目
- 写完代码先 `git diff --check` + `git add` 全量 + 一次 `pre-commit` 试探（如有 hook 入口），把所有 hook 一次性触发再修，比 commit retry 链快