docs: add changelog and CLI reference for quick health check and stale cleanup

- Add 2026-04-15 changelog documenting quick mode, stale cleanup, git hooks
- Update CLI reference with --quick flag and hub:cleanup-stale-indexes commands
- Update README with latest release note and docs map entry

Author: codefromkarl

README.md

@@ -33,6 +33,7 @@
 
 ## Updates
 
+- `2026-04-15`: added git hook auto-maintenance with `--quick` health check (260x speedup), stale index cleanup CLI, and three-layer hook protection (debounce + quick mode + daily throttle).
 - `2026-04-10`: `codebase-retrieval` now includes the lightweight direct graph summary by default, with MCP metadata, tests, and changelog docs updated in sync.
 - `2026-04-06`: tightened the default user path, memory governance, and operational visibility to make first use, feedback loops, and health checks clearer.
 - `2026-04-07`: improved the indexing pipeline with lighter planning, snapshot copy reduction, queue observability, fallback hardening, and repeatable benchmarks.
@@ -288,6 +289,7 @@ ContextAtlas focuses on **what context to provide**, not how the task should be
 
 | Document | Purpose |
 |------|------|
+| [2026-04-15 update summary](./docs/changelog/2026-04-15.md) | Quick health check, stale index cleanup, and git hook auto-maintenance |
 | [Docs index](./docs/README.md) | Unified entry for stable docs, plans, changelog, and archived delivery material |
 | [2026-04-10 update summary](./docs/changelog/2026-04-10.md) | Default-on graph context for codebase retrieval plus MCP/docs sync |
 | [First use guide](./docs/guides/first-use.md) | Fast onboarding path for the default `contextatlas` loop |

docs/changelog/2026-04-15.md

@@ -0,0 +1,124 @@
+# ContextAtlas 更新总结（2026-04-15）
+
+本轮更新围绕健康检查性能和自动化运维闭环展开：
+
+> 新增 `--quick` 健康检查模式（260x 提速）、幽灵索引目录清理命令、以及 post-checkout/post-merge git hooks 自动维护。
+
+## 一、为什么要更新
+
+- `health:check` 对所有项目逐一初始化 VectorStore + 策略分析，在项目数较多时耗时显著，无法用于自动化流程
+- 旧架构遗留、测试泄漏和临时仓库会导致 baseDir 下堆积无 `current` / `snapshots` 的幽灵索引目录
+- `hub:cleanup-ghost` 只清理 Hub 注册表，不管文件系统层的幽灵目录
+- 缺少开发者本地的自动维护机制，依赖手动执行清理命令
+
+## 二、这次更新的目标
+
+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. `--quick` 健康检查模式
+
+`analyzeIndexHealth` 新增 `quick` 参数：
+
+- **无显式 projectIds**：跳过全部 snapshot 扫描，只查 queue + daemon（~0.36s）
+- **有显式 projectIds**：只扫描指定项目，跳过 VectorStore 和 strategySummary
+- CLI 新增 `--quick` 选项：`contextatlas health:check --quick --json`
+
+### 2. 幽灵索引目录清理
+
+新增 `cleanupStaleIndexes()` 函数和 `hub:cleanup-stale-indexes` CLI 命令：
+
+- 扫描 baseDir 下所有项目目录
+- 识别无 `current` 指针且无 `snapshots` 目录但有 `index.db` 的幽灵目录
+- 支持 `--dry-run`（仅预览）和 `--json`（脚本消费）
+- 保护有 `current` 或 `snapshots` 的活跃项目
+
+### 3. Git Hooks 自动维护
+
+新增三层防护机制：
+
+| 层级 | 机制 | 效果 |
+|------|------|------|
+| 1 | 60s 防抖 | 快速切换分支不重复触发 |
+| 2 | `--quick` 模式 | health:check 仅查 queue + daemon（0.36s） |
+| 3 | 24h 清理节流 | 幽灵清理每天最多执行一次，先检查再清理 |
+
+Hook 行为：
+
+1. `health:check --quick --json` 检测健康状态
+2. `healthy` → 跳过（0.36s 结束）
+3. `unhealthy` → 条件触发清理 + catalog 重建
+4. 清理路径：先 `--dry-run` 检查幽灵数量，有才执行删除
+5. 全程 `nohup` 后台执行，不阻塞任何 git 操作
+
+### 4. 安装机制
+
+- `scripts/git-hooks/post-checkout` + `scripts/git-hooks/post-merge`：hook 源文件
+- `scripts/setup-hooks.sh`：安装脚本（复制 + chmod）
+- `package.json` → `"prepare"` 脚本：`pnpm install` 自动触发安装
+
+## 四、解决了什么问题
+
+| 问题 | 解决方案 |
+|------|----------|
+| health:check 全量扫描过慢 | `--quick` 模式跳过重操作，亚秒级完成 |
+| 幽灵索引目录堆积 | `hub:cleanup-stale-indexes` 一键清理 |
+| 开发者需手动维护 | post-checkout/post-merge 自动后台维护 |
+| 连续切换分支触发多次 | 60s 防抖 + nohup 后台 |
+| 清理每次都跑浪费时间 | 24h 节流 + dry-run 先检查 |
+
+## 五、边界、兼容性与当前状态
+
+- `health:check` 不加 `--quick` 时行为不变（完整扫描）
+- `health:full` 不受影响
+- Hook 安装幂等（覆盖写入 `.git/hooks/`）
+- Hook 在无 `contextatlas` CLI 的环境下静默跳过
+- 新增 6 个测试（3 个 quick 模式 + 3 个 stale cleanup）
+
+## 六、涉及文件、命令与入口
+
+新增文件：
+
+- `scripts/git-hooks/post-checkout`
+- `scripts/git-hooks/post-merge`
+- `scripts/setup-hooks.sh`
+- `tests/cleanup-stale-indexes.test.ts`
+
+修改文件：
+
+- `src/monitoring/indexHealth.ts`（`quick` 模式 + `cleanupStaleIndexes` 导出）
+- `src/cli/commands/opsHealth.ts`（`--quick` CLI 选项）
+- `src/cli/commands/hubProjects.ts`（`hub:cleanup-stale-indexes` 命令）
+- `tests/index-health.test.ts`（3 个新测试）
+- `package.json`（`prepare` 脚本）
+
+新 CLI 命令：
+
+```bash
+# 快速健康检查
+contextatlas health:check --quick --json
+
+# 清理幽灵索引目录
+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 验证
+contextatlas health:check --quick --json
+contextatlas hub:cleanup-stale-indexes --dry-run --json
+
+# Hook 端到端验证
+git checkout -b test-branch && git checkout main && git branch -d test-branch
+cat ~/.cache/contextatlas/hooks.log
+```

docs/reference/cli.md

@@ -258,6 +258,10 @@ contextatlas profile:import-omc --force
 ```bash
 contextatlas hub:register-project /path/to/project --name "My Project"
 contextatlas hub:list-projects
+contextatlas hub:cleanup-ghost --mode tmp --dry-run    # 预览 Hub 注册表中的幽灵项目
+contextatlas hub:cleanup-ghost --mode tmp               # 清理 Hub 注册表幽灵项目
+contextatlas hub:cleanup-stale-indexes --dry-run --json # 预览无 current/snapshots 的遗留索引目录
+contextatlas hub:cleanup-stale-indexes --json            # 清理遗留索引目录
 contextatlas hub:save-memory <projectId> "SearchService" --desc "检索编排 facade" --dir "src/search"
 contextatlas hub:search --category search
 contextatlas hub:fts "向量 搜索"
@@ -287,6 +291,7 @@ contextatlas usage:index-report --days 7 --project-id <projectId>
 # 索引健康度
 contextatlas health:check
 contextatlas health:check --json
+contextatlas health:check --quick --json           # 快速模式：跳过 VectorStore/策略分析（~0.3s）
 contextatlas health:check --project-id <projectId>
 contextatlas health:full
 contextatlas health:full --json