bug: post-commit hook 单目录 scan (hardcoded detailed) 覆盖 scan-all 层级化 README —— hub 目录形态震荡

[dreamlx]

现象

src/codeindex/README_AI.md 的 committed 形态长期是 detailed（~350 行全递归 symbol dump），但 scan-all 对同一目录产出 navigation（~64 行聚合导航）。两者内容差异巨大，每次交替都产生大 diff。最近实证：2026-08-15 01:52 scan-all 写 navigation → 01:56 一个 commit 触发 post-commit hook 写回 detailed，随 PR squash 进 master。

根因（已读码定位）

1. scan-all 走 tree-aware 路径：DirectoryTree.get_level() 对有 indexed children 的目录判 navigation（directory_tree.py:182-184）
2. post-commit hook 走的是单目录路径：run_post_commit_hook 对每个 affected dir 跑 codeindex scan <dir> --quiet（cli_hooks.py:493）
3. 单目录 scan hardcode level = "detailed" + child_dirs=[]（cli_scan.py:266-268，注释自述 "For single directory scan, always use detailed level"）
4. 于是任何 commit 直接改到 hub 目录（如 src/codeindex/__init__.py 的版本号 bump）→ hook 把 navigation README 覆盖成 detailed

Committed 状态长期偏向 detailed，因为 hook 触发频率远高于人肉 scan-all。

影响

• 内容噪声：hub 目录拿到 350 行 detailed dump 而非 64 行导航聚合——违反 README_AI 的 navigation 定位（GH Navigation/overview READMEs double-count files (and symbols) #45/bug(scan): 非叶子目录 README_AI.md ## Files 铺平递归子文件，agent Read 路径会 404 #76 均为层级正确性 fix；消费侧 agent 阅读成本直接翻 5 倍）
• 历史震荡：scan-all ↔ hook 交替覆盖，README_AI.md 的 git diff 噪声大
• 与 audit: README_AI 内容纪律（严格 what/where）+ 小目录跳过 —— 消费侧 agent 视角两项提案 #158 的 0-symbol skip 无交集：hook 路径无 skip 逻辑，但 hook 先查 readme_path.exists()（cli_hooks.py:488），已删除的 README 不会复活；仅用户手动 codeindex scan <dir> 会为 0-symbol 目录再生成（显式请求，可接受）

修复方向（未定稿）

hook 对 affected dirs 复用 tree-aware seam（_process_directory_with_smartwriter，构建一次 DirectoryTree 后逐目录处理），而非 subprocess 单目录 scan。需评估 hook 的 120s timeout 约束下建 tree 的成本。

来源

#158 实现过程中的 A/B 隔离发现：stash 全部改动后 HEAD 代码同样产 navigation → 确认与 #159 无关、系既有漂移。

[dreamlx]

解决提案（3 个，含优缺点与建议）

问题本质

"一个 artifact、N 个 writer、不同世界观"的一致性问题：scan-all（tree-aware）与单目录 scan（hardcode detailed）对同一文件都有写权限、对目录结构认知不同。hook 只是把低频 writer 变成了高频触发器。提案空间三类：限制 writer / 统一世界观 / 共享缓存（否决——制造新 staleness 面，缓存 rot 时错 level 照写）。

提案 A：hook 跳过 hub 目录（限制 writer）

run_post_commit_hook 加 guard：目录下存在带 README_AI.md 的子目录 → 跳过重扫。

• ✅ ~5 行，当天可 ship，零语义变更
• ❌ 误判窗口恰好落在最高频场景：commit 新增子目录时，若 parent 先于新子目录被扫，新子目录尚无 README，parent 被判 leaf → detailed dump 照样覆盖（顺序 race）
• ❌ hub 自身变更不触发更新；"子目录有 README" 是 tree membership 的 proxy，会与真逻辑漂移

提案 B：hook 复用 tree-aware seam（统一 hook 的世界观）— 建议

run_post_commit_hook 进程内构建一次 DirectoryTree，affected dirs 走 _process_directory_with_smartwriter，删 per-dir subprocess。

• ✅ 根修：hook 与 scan-all 同一 writer，输出 byte-consistent，震荡源头消失
• ✅ 白拿 audit: README_AI 内容纪律（严格 what/where）+ 小目录跳过 —— 消费侧 agent 视角两项提案 #158 的 0-symbol skip + stale 清理（seam 已含）；新增子目录场景天然正确（tree 实时建，无 race）
• ✅ 省 N 次 subprocess spawn；隔离性不降级（seam 本身 per-dir try/except）
• ❌ tree build = 全 repo 目录遍历（无 parse，suffix check 而已），hook timeout 语义需从 per-dir 复核为 per-run
• ❌ 不覆盖手动单目录 codeindex scan <dir> 的同款漂移（低频、用户可见，可容忍）

提案 C：修单目录 scan 语义（统一全部 writer）

scan <dir> 向上发现 repo root，建 tree 判 level，与 scan-all 完全一致。

• ✅ 唯一覆盖手动 CLI 的方案，hook 零改动
• ❌ 改变既有 CLI 语义（"快速 dump" → 导航聚合，部分用户信息变少）
• ❌ root discovery 新歧义分支（git root / yaml 层 / 无 repo fallback）；高频单目录调用每次 walk 整 repo；YAGNI 风险最高

建议

直接做 B，跳过 A：A 在"新增子目录"这一最常见 commit 类型上恰好失效（顺序 race），作为中间步会制造"已修"错觉——假绿比不修危险。C 的增量只覆盖低频手动场景，不值得 CLI 语义变更；B 落地后若仍有手动 scan 漂移的实际抱怨再评估 C。