docs: rewrite 04-15 changelog with system evolution perspective

Position auto-maintenance as closure of the ops capability arc
(04-06 observe → 04-09 align → 04-15 auto-repair), not isolated feature.

Author: codefromkarl

docs/changelog/2026-04-15.md

@@ -1,79 +1,77 @@
 # ContextAtlas 更新总结（2026-04-15）
 
-本轮更新围绕健康检查性能和自动化运维闭环展开：
+本轮更新是 04-06 以来运维能力建设的一次收口：
 
-> 新增 `--quick` 健康检查模式（260x 提速）、幽灵索引目录清理命令、以及 post-checkout/post-merge git hooks 自动维护。
+> 把散落的健康检查、幽灵清理、catalog 重建串成一条 git hook 驱动的自动运维闭环，从"有观测"推进到"自动修复"。
 
-## 一、为什么要更新
+## 一、在系统发展中的位置
 
-- `health:check` 对所有项目逐一初始化 VectorStore + 策略分析，在项目数较多时耗时显著，无法用于自动化流程
-- 旧架构遗留、测试泄漏和临时仓库会导致 baseDir 下堆积无 `current` / `snapshots` 的幽灵索引目录
-- `hub:cleanup-ghost` 只清理 Hub 注册表，不管文件系统层的幽灵目录
-- 缺少开发者本地的自动维护机制，依赖手动执行清理命令
+4 月的运维能力建设经历了三个阶段：
 
-## 二、这次更新的目标
+| 阶段 | 时间 | 内容 |
+|------|------|------|
+| 建观测 | 04-06 ~ 04-07 | health check 面板、queue 监控、daemon 状态、告警引擎 |
+| 对齐与统一 | 04-09 ~ 04-14 | 告警阈值对齐、Hub 注册表清理、application 层统一入口 |
+| 自动闭环 | 04-15 | git hook 触发 → 健康检测 → 条件修复，开发者无感 |
+
+04-15 的核心价值不是新增了某个命令，而是把前两阶段建立的能力**串成了不需要人工干预的闭环**。
+
+## 二、为什么要更新
+
+前两阶段留下了两个断点：
 
-1. 新增 `health:check --quick` 快速模式，跳过 VectorStore / strategySummary / snapshot 扫描
-2. 新增 `hub:cleanup-stale-indexes` 命令，清理无 `current` / `snapshots` 的遗留索引目录
-3. 新增 post-checkout / post-merge git hooks，自动检测并修复索引健康
-4. Hook 安装脚本，`pnpm install` 自动部署
+1. **观测到修复需要人工介入**：health check 能发现问题（04-06/04-07），Hub 清理能清注册表（04-14），但开发者需要手动跑命令，容易遗忘
+2. **全量 health check 在项目数增长后变慢**：04-07 建立的健康面板对所有项目逐一初始化 VectorStore，项目累积后耗时显著，不适合高频触发
+
+此外，旧架构遗留的索引目录（无 snapshot 系统）和测试泄漏会持续产生幽灵项目，`hub:cleanup-ghost`（04-14）只清理 Hub 注册表，不清理文件系统层。
 
 ## 三、如何更新
 
-### 1. `--quick` 健康检查模式
+### 1. `--quick` 健康检查：适配高频场景
 
-`analyzeIndexHealth` 新增 `quick` 参数：
+`analyzeIndexHealth` 新增 `quick` 参数，分两个快速路径：
 
-- **无显式 projectIds**：跳过全部 snapshot 扫描，只查 queue + daemon（~0.36s）
+- **无显式 projectIds**：跳过全部 snapshot 扫描，只查 queue + daemon
 - **有显式 projectIds**：只扫描指定项目，跳过 VectorStore 和 strategySummary
-- CLI 新增 `--quick` 选项：`contextatlas health:check --quick --json`
 
-### 2. 幽灵索引目录清理
+这是对 04-07 建立的健康面板的**性能适配**——原始面板设计用于"完整诊断"，但自动化场景需要"快速筛查"。
+
+### 2. 幽灵索引目录清理：补全 04-14 的清理覆盖面
 
-新增 `cleanupStaleIndexes()` 函数和 `hub:cleanup-stale-indexes` CLI 命令：
+04-14 的 `hub:cleanup-ghost` 清理 Hub 注册表中的幽灵项目，但不触及文件系统。新增 `cleanupStaleIndexes()` 和 `hub:cleanup-stale-indexes` CLI 命令覆盖文件系统层：
 
 - 扫描 baseDir 下所有项目目录
-- 识别无 `current` 指针且无 `snapshots` 目录但有 `index.db` 的幽灵目录
-- 支持 `--dry-run`（仅预览）和 `--json`（脚本消费）
+- 识别无 `current` 指针且无 `snapshots` 目录但有 `index.db` 的幽灵目录（来自旧架构遗留和测试泄漏）
 - 保护有 `current` 或 `snapshots` 的活跃项目
 
-### 3. Git Hooks 自动维护
+### 3. Git Hooks：把检测和修复串成闭环
 
-新增三层防护机制：
-
-| 层级 | 机制 | 效果 |
-|------|------|------|
-| 1 | 60s 防抖 | 快速切换分支不重复触发 |
-| 2 | `--quick` 模式 | health:check 仅查 queue + daemon（0.36s） |
-| 3 | 24h 清理节流 | 幽灵清理每天最多执行一次，先检查再清理 |
+post-checkout / post-merge hooks 实现三层防护：
 
-Hook 行为：
+| 层级 | 机制 | 对接的前序能力 |
+|------|------|----------------|
+| 防抖 | 60s 内不重复触发 | 避免快速切换分支时的重复开销 |
+| 快速筛查 | `health:check --quick` | 对接 04-07 的健康面板（适配高频模式） |
+| 条件清理 | dry-run 先检查，有幽灵才删除 | 对接 04-14 的 Hub 清理 + 新增的文件系统清理 |
 
-1. `health:check --quick --json` 检测健康状态
-2. `healthy` → 跳过（0.36s 结束）
-3. `unhealthy` → 条件触发清理 + catalog 重建
-4. 清理路径：先 `--dry-run` 检查幽灵数量，有才执行删除
-5. 全程 `nohup` 后台执行，不阻塞任何 git 操作
+额外设计：24h 清理节流——重操作（目录扫描和删除）每天最多执行一次，日常切换只跑轻量检查和 catalog 重建。
 
 ### 4. 安装机制
 
-- `scripts/git-hooks/post-checkout` + `scripts/git-hooks/post-merge`：hook 源文件
-- `scripts/setup-hooks.sh`：安装脚本（复制 + chmod）
-- `package.json` → `"prepare"` 脚本：`pnpm install` 自动触发安装
+`package.json` 的 `prepare` 脚本在 `pnpm install` 时自动部署 hooks。无 `contextatlas` CLI 的环境静默跳过。
 
 ## 四、解决了什么问题
 
-| 问题 | 解决方案 |
-|------|----------|
-| health:check 全量扫描过慢 | `--quick` 模式跳过重操作，亚秒级完成 |
-| 幽灵索引目录堆积 | `hub:cleanup-stale-indexes` 一键清理 |
-| 开发者需手动维护 | post-checkout/post-merge 自动后台维护 |
-| 连续切换分支触发多次 | 60s 防抖 + nohup 后台 |
-| 清理每次都跑浪费时间 | 24h 节流 + dry-run 先检查 |
+| 问题 | 来源 | 解决方案 |
+|------|------|----------|
+| 健康观测到修复需要人工 | 04-06/04-07 建了观测但缺闭环 | git hook 自动触发 |
+| 全量 health check 太慢 | 04-07 面板未考虑项目累积 | `--quick` 跳过重操作 |
+| 幽灵目录只在注册表层清理 | 04-14 只覆盖 Hub 注册表 | `cleanup-stale-indexes` 覆盖文件系统 |
+| 开发者忘记手动维护 | 人总是忘 | 自动化到 checkout/merge 触发点 |
 
 ## 五、边界、兼容性与当前状态
 
-- `health:check` 不加 `--quick` 时行为不变（完整扫描）
+- `health:check` 不加 `--quick` 时行为不变（完整扫描，适合手动诊断）
 - `health:full` 不受影响
 - Hook 安装幂等（覆盖写入 `.git/hooks/`）
 - Hook 在无 `contextatlas` CLI 的环境下静默跳过
@@ -99,19 +97,18 @@ Hook 行为：
 新 CLI 命令：
 
 ```bash
-# 快速健康检查
+# 快速健康检查（对接 04-07 健康面板的高频模式）
 contextatlas health:check --quick --json
 
-# 清理幽灵索引目录
+# 清理幽灵索引目录（补全 04-14 Hub 清理的文件系统层）
 contextatlas hub:cleanup-stale-indexes --dry-run --json   # 预览
 contextatlas hub:cleanup-stale-indexes --json              # 执行
-contextatlas hub:cleanup-stale-indexes                     # 文本报告
 ```
 
 ## 七、验证口径
 
 ```bash
-# 单元测试（15 个测试）
+# 单元测试
 node --import tsx --test tests/cleanup-stale-indexes.test.ts tests/index-health.test.ts
 
 # CLI 验证