repo-hygiene

用途

repo-hygiene 是一个工作区整洁检查目录，用于发现仓库中的文件系统垃圾、被跟踪的生成产物、.gitignore 缺口与历史遗留规则、临时目录、孤立文档资源以及 git 辅助状态等问题。它的成员规则由文件系统和 git 决定：不读取任何源文件，也不理解任何符号。需要判断符号用途或引用可达性的检查不属于本目录，而属于 senior-review:cleanup-auditor。

两个 profile，一套检查

检查只定义一次，两个 profile 只决定作用范围，其余完全一致。调用方声明自己的 profile；在所选范围中没有意义的检查会被跳过，而不会被悄悄放宽。

full：作用于整个工作树，调用方为 /repo-hygiene:tidy、repo-hygiene:workspace-auditor。
lite：仅作用于 diff 新增的文件，调用方为 /senior-review:code-review 与 /senior-review:pr-review 的内联卫生检查。

lite profile 不能扩大范围。C4 至 C7 在构造上即属仓库历史层面（2024 年就过期的忽略规则、无人触碰的临时目录、上个月的 stash），这些都不可能由被审查的 diff 引起，在被审查的改动上报出它们属于噪声。如果 lite 调用方在只新增了一个 TypeScript 文件的 PR 上列出 Python 忽略规则，即为范围扩大，属于缺陷。

检查目录

C1 文件系统垃圾

通过 git ls-files 配合正则匹配 nul、.DS_Store、Thumbs.db、desktop.ini、.swp、.swo、#..#、以 ~ 结尾的文件，以及以 <>|& 开头或名为 2>&1 的文件。Shell 重定向产物（nul、名为 2>&1 或起始为 > 的文件）是本目录中置信度最高的一类，因为没有任何合法流程会产生它们。

C2 被 git 跟踪的生成产物

匹配 dist、build、out、.next、.nuxt、.cache、.turbo、.parcel-cache、pycache、.pytest_cache、.mypy_cache、.ruff_cache、.venv、venv、node_modules、target、.gradle、android/app/build、ios/build、src-tauri/gen、src-tauri/target 等目录，以及 .bundle.js、.chunk.js、.min.js.map、pyc、class、o、obj 等文件。

被跟踪的构建产物不一定是错误。仓库可能有意提交 dist/：GitHub Pages 从该目录发布、生成的 SDK 需要交付给包使用者、内置 bundle 让安装无需构建步骤。取消跟踪这些文件会破坏下一次干净检出，而本地所有命令仍然通过，因为文件仍在磁盘上。标记前应检查是否存在要求该路径的发布约定（如 Pages 发布文件、npm publish 白名单、workflow 中的引用）。命中即说明该产物是有意为之，应报告为 KEEP 并注明所依据的约定，而不是作为移除候选。

C3 .gitignore 完整性

先检测项目信号，再检查对应模式是否存在。信号与期望模式包括：package.json 对应 node_modules/、dist/、build/、.env、.env.local、npm-debug.log*；vite.config.* 对应 dist/、.vite/；next.config.* 对应 .next/、out/；src-tauri/ 对应 src-tauri/target/、src-tauri/gen/；Cargo.toml 对应 target/（Cargo.lock 仅库项目）；pyproject.toml 或 requirements.txt 对应 pycache/、.pyc、.venv/、.egg-info/、.pytest_cache/；*.gradle 对应 android/app/build/、android/build/、android/.gradle/；Podfile 对应 ios/build/、ios/Pods/；任意项目对应 .DS_Store、Thumbs.db。缺失模式且存在匹配的被跟踪文件，即为 .gitignore 缺口。

C4 .gitignore 溯源

先用 git check-ignore -v <path> 确定来源（.gitignore、嵌套忽略文件、.git/info/exclude 或全局忽略），只有被跟踪忽略文件中的规则才成为发现；本地和全局来源最多给一条备注，因为它们不属于仓库可改范围。

过期规则：匹配不到磁盘上任何内容、近期历史中也不可能有合理匹配的模式。严重度 LOW。不要标记预防性的生态默认规则（node_modules/、pycache/、.DS_Store），它们的价值恰恰在于暂时匹配不到任何东西。
过宽规则：其忽略匹配中包含生成目录之外的源码或配置形态文件。处置为 UNIGNORE。标记前需逐个确认候选并非生成文件。

C5 临时与管道输出目录

检查 .upstream-scratch、.codebase-xray、.daodan、.team-review、.codebase-map、.research、.brainstorm、.peer-review、.frontend-review、tmp、temp、scratch、_wip、wip、_drafts 等目录，以及 NOTES.md、TODO.md、SCRATCH.md 文件。

受保护的协议根目录：绝不提议移除 .daodan/ 或 .codebase-xray/；同时保护任何包含 .daodan-root 哨兵文件的目录及其祖先目录。仅按名称/哨兵存在性识别，不解析 work.json、不分类运行、不推断保留资格，那属于生命周期整合的决策。该排除在下列三种状态之前应用。

三种状态与处置：未跟踪且已被忽略——仅为本地杂乱，LOW；受保护根目录除外，其他未跟踪候选只能在已接受的 tidy 计划下移入隔离区。已跟踪——污染每一次克隆，HIGH，git rm -r 并添加忽略条目。已跟踪且已被忽略——不可能的状态，说明文件在模式存在之前就被提交，操作前需合理性检查。

C6 孤立文档资源

列出 docs/、docs/images/、docs/assets/、docs/diagrams/、.github/assets/ 下的图片与图表，然后在 /*.md、/.mdx、**/.rst、**/.adoc 中检索每个基名。零字面引用并不等于孤立：文档资源可能通过基名检索看不到的路径进入渲染站点，例如 mkdocs.yml 或 docusaurus.config.js 中的值、样式表中的 url()、生成的导航条目、模板中拼接的路径。在下结论前应扩大搜索范围（覆盖 .yml、.yaml、.toml、.json、.css、.scss、.html、.j2，以及 mkdocs.yml、docusaurus.config.、_config.yml 中的 logo/banner/icon/favicon/social 等）。两项搜索后仍存活的资源只是候选，而非确认的孤立项；移除需要逐项批准，发现中应说明这一点。

C7 Git 辅助状态

检查 git stash list、git worktree list、上游已消失的分支、已合并分支。闲置超过 90 天的 stash、指向已删除分支或路径的 worktree、上游已消失的本地分支、已合并但未删除的分支，属于 LOW 到 MEDIUM 发现。

该维度永久且结构性地只做检测。本目录其他检查都会改动被跟踪内容，因而提交能记录变化、回滚该提交即可恢复；这四项不会：丢弃的 stash 不在任何提交中留痕，移除含未提交文件的 worktree 会一并带走这些文件，删除分支的顶端只存在于会过期的 reflog 中。没有 diff 的变更无法用分阶段提交作为回滚机制，因此这里的内容在任何确认级别下都不会自动应用；移除命令只写在发现文本中，由用户自行执行并负责。

发现格式

应用安全性

目录按处置类型允许的操作：未跟踪文件的 REMOVE 会移入 .repo-hygiene/quarantine/<timestamp>/ 而非删除（git 不保存未跟踪文件的副本，删除是唯一不可逆操作，故不采用）；已跟踪文件的 REMOVE 使用 git rm，可从历史恢复；KEEP+IGNORE 与 REMOVE+IGNORE 追加模式后逐项 git rm --cached 并逐项确认，因为 C2 的发布检查是启发式的，判错会破坏干净检出而本地信号全部正常；UNIGNORE 只编辑忽略规则，绝不代替用户 git add；REVIEW 与 REPORT-ONLY 永不应用，只报告用户会执行的命令。

适用范围与限制

本目录仅依据文件系统与 git 状态做判定，不读取源文件、不分析符号语义；因此不适用于需要代码语义理解的清理判断。C4 至 C7 仅在 full profile 下执行，lite profile 无法扩大范围。C6 的搜索结果只能给出候选而非确认孤立，移除需逐项批准。C7 永久只检测，不自动执行任何变更。C2 的 KEEP 判定基于发布约定的启发式检查。