Pitfall Journal

开发过程中踩过的坑，按时间倒序排列。Agent 进入调试或遇到运行时错误时可检索本文件。

症状: Hook 跨平台测试在 bash --version 阶段长期无输出，整套测试超过超时仍不结束。
根因: shutil.which("bash") 优先命中了 WindowsApps 的 WSL 应用执行别名；该占位 bash.exe 存在但不会像 Git Bash 一样快速返回版本，原探测也没有 subprocess timeout。
解法: 给候选 bash 的版本探测增加短超时，捕获 subprocess.TimeoutExpired 后继续尝试 Git 安装目录中的 bin/bash.exe；Hook 子进程本身也设置超时，避免再次无限等待。
防御: Windows 上不能仅凭 which 和文件存在判断 CLI 可用；外部工具探测必须执行带超时的无副作用命令，并把单个候选超时视为“不可用”而不是全局失败。
关联: .cursor/hooks/tests/test_check_changelog.py、WindowsApps、WSL alias、Git Bash、subprocess timeout

症状: Git 工作区没有任何内容差异，stop Hook 却因 .vscode/settings.json 时间戳较新而要求创建 changelog fragment。
根因: .session-start 缺失时 Hook 回退到旧 changelog 时间，并且只比较宽泛扫描范围内文件的 mtime，没有验证候选文件是否存在真实 Git 内容差异。
解法: .session-start 缺失或 Git 状态不可用时 fail-open；工作区干净时立即退出；候选文件还必须被 git status --porcelain 判定为未提交改动。PowerShell 与 Bash 实现同步修复并添加回归测试。
防御: 文件时间只能限定“本会话之后”，不能作为内容改动证据；Hook 提示写日志前必须同时满足会话时间与版本控制状态，并覆盖“仅 touch、无内容变化”的测试。
关联: .cursor/hooks/check-changelog.ps1、.cursor/hooks/check-changelog.sh、.cursor/hooks/tests/test_check_changelog.py、Cursor stop Hook、Windows/Bash