docs: README_AI 刷新时机 post-commit per-commit → release-time；post-commit hook 退役

[dreamlx]

背景

README_AI.md 是可重建产物但保留 git tracking（决议取向 B）：它的消费者是"没装 codeindex 的 clone"——队友的 agent、CI、GitHub 浏览。git 是分发通道（lockfile 类比），不只是存储。untrack 会让它从团队资产退化成单机私有产物，与消费侧价值轴矛盾。

但现行"重建即 commit"机制代价实测：

• 848 个 commit 中 257 个（30%）touch README_AI.md
• 为管 noise 长出整套 post-commit hook 机器：loop guard、tree-aware seam（bug: post-commit hook 单目录 scan (hardcoded detailed) 覆盖 scan-all 层级化 README —— hub 目录形态震荡 #160、fix(hooks): post-commit hook renders via tree-aware seam (#160 proposal B) #162 两个 PR 专门修 hook 自身）
• 每 commit 自动刷新的频率是错的：导航索引对"最近几小时的结构变化"本就不敏感

决议（取向 B）

保留 tracking，刷新时机从 per-commit 改为 release-time。post-commit hook（本仓）退役。

版本号语义（勿混淆）

README_AI provenance / CLAUDE.md marker 里的版本号是生成器（codeindex 工具）版本，用于 staleness 检测（工具升级 → 旧 provenance 可发现该重刷），不是被索引 repo 的版本。

• 本仓（dogfood）：工具版本 = repo release 版本，两者巧合重合
• 一般用户仓：release-time 刷进的是当时安装的工具号，顺序不敏感

Rescan 时机：release 流程内、tag 之前

本仓顺序敏感——工具版本与 repo 版本重合，必须先 bump version 再 scan，否则 provenance 带旧号：

1. bump version (pyproject etc.)
2. codeindex scan-all          # provenance 带上新版本号
3. codeindex claude-md update  # CLAUDE.md marker 段
4. commit "docs: refresh README_AI for vX.Y.Z"
5. CHANGELOG / pre_release_check / tag

落点：把 2-4 步并入 scripts/pre_release_check.sh 或 release make target（release 检查本来就强制 CHANGELOG，同处加 scan 是天然位置）。tag 内含新鲜索引。

预期效果：257 次 commit noise → ~40 个 release 节点集中刷新。

中周期（两次 release 之间）

• 不建机制、不加规则：本地想看新索引就随时 codeindex scan-all（enrichment 有 cache，不重复花钱）；产生的 dirty README_AI 顺路带进哪个 commit 都可以，只是不再有 hook 强制每次都刷
• 索引滞后到上个 release 是可接受的 staleness——CLAUDE.md navigation contract 本来就要求 agent 用源码验证机制，索引只管"what/where"

post-commit hook 退役影响

本仓（直接做）

• codeindex hooks uninstall post-commit；pre-commit（lint）与 pre-push（tests）不受影响
• CLAUDE.md / docs 里 post-commit 相关描述更新

产品侧（单独决策，本 issue 不定稿）

• 产品目前向所有用户推荐 post-commit hook；per-commit 频率对用户同样可能过密。候选：默认不装 post-commit（pre-commit/pre-push 保留），文档改为"在有意义节点（release/大 merge）手动 scan-all + commit"
• 若产品级弃用 → 可删代码：_generate_post_commit_script、tree-aware seam、loop guard、hooks rerun post-commit escape hatch 及对应测试
• 用户侧影响：没有正式 release 流程的仓库（多数个人项目）怎么办——"release-time"对他们退化为"手动择时"，需要文档给出姿势
• 需要 A/B 或 dogfood 数据支撑再动产品默认（遵守 no-ship-without-baseline）

Checklist

• release 流程加入 scan-all + claude-md update + commit（顺序见上）
• 本仓 uninstall post-commit hook
• CLAUDE.md / docs 更新（hooks 章节、navigation contract 不变）
• 产品级 post-commit 默认装否 → 独立 issue

[dreamlx]

产品侧待决（post-commit hook 默认装否）已拆到 #167：架构原则『刷新时机策略归编排者/消费者，codeindex 不拥有 timing 策略』给出方向——产品级弃用，节奏待定（deprecate 一版 vs 直接删）。本 issue 剩本仓 checklist 三项。