dreamlx · dreamlx · Mar 12, 2026 · Mar 12, 2026 · Mar 12, 2026 · Mar 12, 2026
diff --git a/.claude/skills/mo-hooks/SKILL.md b/.claude/skills/mo-hooks/SKILL.md
@@ -9,13 +9,21 @@ Set up Git hooks so README_AI.md files automatically update when code changes ar
 
 ## How It Works
 
+**Architecture**: Thin wrapper shell script → Python logic (auto-upgradeable via pip)
+
 When a developer commits code changes:
-1. **post-commit hook** detects which directories were affected
-2. `codeindex affected --json` analyzes the change scope
-3. `codeindex scan` regenerates README_AI.md for affected directories
-4. Updated README_AI.md files are auto-committed
+1. Shell wrapper skips doc-only commits (loop guard), activates venv
+2. Delegates to `codeindex hooks run post-commit` (Python)
+3. `codeindex affected --json` analyzes the change scope
+4. `codeindex scan` regenerates structural README_AI.md for affected directories
+5. Updated README_AI.md files are auto-committed
+
+**Key**: Hook only updates structural content. AI blockquote descriptions
+(module purpose) are not regenerated per-commit — run `codeindex scan-all`
+to refresh those.
 
-This keeps documentation always in sync with code — zero manual effort.
+**Upgrade**: `pip install --upgrade ai-codeindex` auto-updates hook logic.
+No need to reinstall hooks after package upgrade.
 
 ## Prerequisites
 
@@ -137,6 +145,16 @@ codeindex hooks uninstall post-commit
 codeindex hooks uninstall --all
 ```
 
+## Upgrading Hooks
+
+```bash
+# Usually NOT needed — pip upgrade auto-updates Python logic
+pip install --upgrade ai-codeindex
+
+# Only if release notes say "reinstall hooks":
+codeindex hooks install post-commit --force
+```
+
 ## Troubleshooting
 
 | Problem | Solution |
@@ -146,6 +164,7 @@ codeindex hooks uninstall --all
 | Hook too slow | Set `mode: async` in .codeindex.yaml hooks config |
 | Want manual control | Set `mode: prompt` — shows notification, you decide when to update |
 | Virtual env not found | Ensure `.venv/` or `venv/` exists at project root |
+| Old hook with AI prompts | Run `codeindex hooks install post-commit --force` to upgrade to thin wrapper |
 
 ## Advanced: CLAUDE.md Integration
 

diff --git a/.claude/skills/mo-index/SKILL.md b/.claude/skills/mo-index/SKILL.md
@@ -43,19 +43,21 @@ codeindex list-dirs
 
 ### Step 4: Index Directories
 
-**All directories (recommended - structural documentation, works immediately):**
+**All directories (recommended):**
 ```bash
+# When ai_command is configured, automatically includes AI enrichment (Phase 2)
 codeindex scan-all
+
+# Disable AI enrichment
+codeindex scan-all --no-ai
 ```
 
 **Single directory:**
 ```bash
 codeindex scan ./src/module
-```
 
-**AI-enhanced mode (requires ai_command in config):**
-```bash
-codeindex scan-all --ai
+# Full AI-generated README for a single directory (requires --ai)
+codeindex scan ./src/module --ai
 codeindex scan ./src/module --ai --dry-run  # Preview AI prompt
 ```
 
@@ -110,8 +112,9 @@ Done! Your project is now indexed:
 
 | Mode | Command | Description |
 |------|---------|-------------|
-| Structural (default) | `codeindex scan-all` | Fast, no AI needed, works immediately |
-| AI-enhanced | `codeindex scan-all --ai` | Richer docs, requires ai_command config |
+| Auto (default) | `codeindex scan-all` | Structural + AI enrichment if ai_command configured |
+| No AI | `codeindex scan-all --no-ai` | Structural only, skip AI enrichment |
+| Single dir AI | `codeindex scan ./dir --ai` | Full AI-generated README for one directory |
 
 ## Configuration Reference
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.23.0] - 2026-03-12
+
+### Added
+
+- **AI-Enhanced Module Descriptions** (Epic #25, Stories 25.1–25.3): Redefine `--ai` mode from full AI takeover to structural + AI micro-enhancement.
+  - **Blockquote description support**: `extract_module_description()` now reads `> description` as Strategy 0 (highest priority)
+  - **AI enrichment module** (`src/codeindex/enricher.py`): Generates one-line functional descriptions per module using symbol names + file names
+  - **Concise prompt design**: ~200-400 tokens per directory, ≤30 char output, 10-20x cheaper than old `--ai` mode
+  - **Batch AI calls**: Groups multiple directories per AI invocation to reduce overhead
+  - **scan-all auto-AI**: Automatically enables Phase 2 AI enrichment when `ai_command` is configured (no `--ai` flag needed)
+  - **`--no-ai` opt-out**: Explicitly disable AI enrichment for structural-only output
+  - **`--ai` / `--no-ai` mutual exclusion**: Clear error when both flags are used
+
+- **Post-commit hook thin wrapper** (Issue #30 fix): Redesigned hook architecture for maintainability.
+  - **Thin shell wrapper** (~30 lines): Only handles loop guard + venv activation
+  - **Python logic** via `codeindex hooks run post-commit`: All business logic in upgradeable Python
+  - **Upgrade path**: `pip install --upgrade ai-codeindex` auto-updates hook behavior (no reinstall needed)
+  - **No custom AI prompts**: Uses `codeindex scan` pipeline, eliminating commit changelog noise
+
+### Fixed
+
+- **AI mode commit changelog noise** (#30): Post-commit hook no longer injects git diff into custom AI prompts. Uses standard `codeindex scan` pipeline instead.
+- **Enricher prompt accuracy**: Improved from "20 chars/brief" to "30 chars/concise" for better description quality.
+
+### Changed
+
+- **`--no-ai` flag**: Changed from hidden/deprecated to active opt-out flag for scan-all.
+- **Post-commit hook generation**: `_generate_post_commit_script()` now generates thin wrapper delegating to Python.
+- **Documentation**: All hook and scan-all docs rewritten for AI CLI agent readers.
+
+### Technical Details
+
+- **New module**: `src/codeindex/enricher.py` — AI enrichment with `enrich_directory()` and `_enrich_directories_with_ai()`
+- **New CLI subcommand**: `codeindex hooks run post-commit` — Python-side post-commit logic
+- **New tests**: 15 tests (7 scan-all auto-AI + 8 post-commit hook)
+- **Total tests**: 1532 passed
+
 ## [0.22.2] - 2026-03-08
 
 ### Added

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -607,7 +607,7 @@ codeindex status
 
 ## 📈 Version History
 
-**Current version**: v0.22.2
+**Current version**: v0.23.0
 
 For complete version history, see:
 - **[CHANGELOG.md](CHANGELOG.md)** - Detailed changes for each version

diff --git a/README.md b/README.md
@@ -160,8 +160,14 @@ codeindex scan-all
 # Scan a single directory
 codeindex scan ./src/auth
 
-# AI-enhanced documentation (requires ai_command in config)
-codeindex scan-all --ai
+# When ai_command is configured, auto-enables AI module descriptions
+codeindex scan-all
+
+# Disable AI enrichment (structural only)
+codeindex scan-all --no-ai
+
+# Full AI-generated README for a single directory
+codeindex scan ./src/auth --ai
 
 # Preview AI prompt without executing
 codeindex scan ./src/auth --ai --dry-run
@@ -428,7 +434,7 @@ See [Release Automation Guide](docs/development/QUICK_START_RELEASE.md) for deta
 
 ## Roadmap
 
-**Current version**: v0.22.2
+**Current version**: v0.23.0
 
 **Recent milestones**:
 - v0.22.2 — Auto-update CLAUDE.md on `pip upgrade`, `/codeindex-update-guide` skill

diff --git a/docs/guides/advanced-usage.md b/docs/guides/advanced-usage.md
@@ -7,11 +7,11 @@
 The simplest way to scan entire projects:
 
 ```bash
-# Structural documentation (default, no AI needed)
+# When ai_command is configured, auto-enables AI enrichment
 codeindex scan-all
 
-# AI-enhanced documentation
-codeindex scan-all --ai
+# Disable AI enrichment (structural only)
+codeindex scan-all --no-ai
 
 # Custom timeout per directory
 codeindex scan-all --timeout 180
@@ -20,6 +20,8 @@ codeindex scan-all --timeout 180
 codeindex scan-all --workers 4
 ```
 
+> When `ai_command` is configured, `scan-all` runs in two phases: Phase 1 generates structural README_AI.md for all directories, Phase 2 uses AI to add a short functional description (`> description`) to each non-leaf directory. Cost: ~300-800 tokens input, ~20-50 tokens output per directory. Use `--no-ai` to skip Phase 2.
+
 ### Traditional Parallel with xargs
 
 For fine-grained control, use traditional parallel scanning:
@@ -468,17 +470,20 @@ claude /mo:arch "Where is authentication implemented?"
 
 ## Tips & Tricks
 
-### 1. Selective AI Enhancement
+### 1. AI Enhancement Strategies
 
 ```bash
-# Generate structural docs for everything (fast)
+# Option A: Auto AI enrichment (default when ai_command configured)
 codeindex scan-all
 
-# Then enhance critical modules with AI
-codeindex scan ./src/core --ai
-codeindex scan ./src/auth --ai
+# Option B: Selective full AI README for critical modules only
+codeindex scan-all --no-ai            # Structural docs only
+codeindex scan ./src/core --ai        # Full AI README for core module
+codeindex scan ./src/auth --ai        # Full AI README for auth module
 ```
 
+> **Tip**: When `ai_command` is configured, `scan-all` automatically adds concise AI-generated module descriptions (e.g., "支付网关（微信、支付宝）") at low cost (~$0.5-2 for 2000+ directories). Use `scan --ai` only when you need a full AI-written README for a specific directory.
+
 ### 2. Conditional Scanning
 
 Only scan if README_AI.md is missing:

diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md
@@ -83,7 +83,7 @@ Generate documentation for a single directory:
 # Structural documentation (default, no AI needed)
 codeindex scan ./src/auth
 
-# AI-enhanced documentation (requires ai_command in config)
+# Full AI-generated README for a single directory (requires ai_command)
 codeindex scan ./src/auth --ai
 ```
 
@@ -115,15 +115,18 @@ Scan all directories at once:
 
 ```bash
 # Structural documentation for entire project
+# When ai_command is configured, automatically includes AI module descriptions
 codeindex scan-all
 
-# AI-enhanced documentation for entire project
-codeindex scan-all --ai
+# Disable AI enrichment (structural only)
+codeindex scan-all --no-ai
 
 # Traditional parallel scanning
 codeindex list-dirs | xargs -P 4 -I {} codeindex scan {}
 ```
 
+> **Note**: When `ai_command` is configured in `.codeindex.yaml`, `scan-all` automatically runs a two-phase pipeline: Phase 1 generates structural README_AI.md, Phase 2 adds a short AI-generated functional description (`> ...`) to each non-leaf directory. Use `--no-ai` to skip Phase 2. This is different from `scan --ai`, which uses AI to generate the entire README for a single directory.
+
 ### 6. Symbol Indexes (v0.1.2+)
 
 Generate project-wide indexes for navigation:

diff --git a/docs/guides/git-hooks-integration.md b/docs/guides/git-hooks-integration.md
@@ -171,39 +171,39 @@ All checks passed!
 
 ### Post-commit Hook
 
-**Purpose**: Automatic documentation updates
+**Purpose**: Automatic structural documentation updates
+
+**Architecture** (v0.23.0+): Thin wrapper pattern
+- Shell script (~30 lines): loop guard + venv activation
+- Python logic via `codeindex hooks run post-commit`: all business logic
+- **Upgrade path**: `pip install --upgrade ai-codeindex` automatically updates hook behavior (no need to reinstall hooks)
 
 **Features**:
 - Analyzes commit changes (`codeindex affected`)
-- Updates README_AI.md for affected directories
+- Runs `codeindex scan` for affected directories (structural regeneration)
 - Creates follow-up commit with updates
 - Avoids infinite loops (skips doc-only commits)
+- No custom AI prompts — uses standard codeindex scan pipeline
 
 **Workflow**:
 ```
 Code Change Commit
     ↓
-Post-commit Hook Triggered
+Shell wrapper (loop guard + venv)
+    ↓
+codeindex hooks run post-commit  (Python)
     ↓
-Analyze: Which directories changed?
+codeindex affected --json → affected directories
     ↓
-Update: README_AI.md files
+codeindex scan <dir> for each → structural README_AI.md update
     ↓
 Auto-commit: "docs: auto-update README_AI.md for <hash>"
 ```
 
-**Example Output**:
-```
-📝 Post-commit: Analyzing changes...
-   Update level: full
-   Found 2 directory(ies) to check
-
-→ Updating src/codeindex/README_AI.md
-   Invoking AI CLI...
-   ✓ Updated via AI
-
-✓ Post-commit hook completed
-```
+> **Note**: Post-commit hook only updates structural content. AI-generated
+> module descriptions (blockquotes) are not regenerated on every commit —
+> they describe module purpose which rarely changes. Run `codeindex scan-all`
+> (with `ai_command` configured) to refresh AI descriptions.
 
 ### Pre-push Hook
 
@@ -522,14 +522,34 @@ fi
 
 **Note**: Manual edits will be lost if you reinstall with `--force`.
 
-### Hook Versioning
+### Hook Architecture and Upgrades
+
+**Thin wrapper pattern** (v0.23.0+):
+
+Post-commit hooks use a thin shell wrapper that delegates to Python:
+
+```
+.git/hooks/post-commit (shell, ~30 lines)
+    → loop guard (skip doc-only commits)
+    → activate venv
+    → codeindex hooks run post-commit  ← Python logic
+
+codeindex hooks run post-commit (Python, in cli_hooks.py)
+    → codeindex affected --json
+    → codeindex scan <dir> for each affected dir
+    → git add + git commit
+```
 
-Hooks are marked with `# codeindex-managed hook` comment.
+**Upgrade behavior**:
+- `pip install --upgrade ai-codeindex` → Python logic auto-updates, no hook reinstall needed
+- `codeindex hooks install --force` → only needed if shell wrapper itself changes (rare)
+- Hooks are marked with `# codeindex-managed hook` comment
 
-To update hooks to latest version:
+**To update hooks to latest version**:
 
 ```bash
-# Reinstall all hooks
+# Usually not needed (Python logic auto-updates via pip)
+# Only if instructed by release notes:
 codeindex hooks install --all --force
 ```
 
@@ -597,5 +617,5 @@ A: Hooks persist across branches (stored in `.git/hooks/`, not tracked by Git).
 
 ---
 
-**Last Updated**: 2026-02-13
-**Status**: Production Ready (v0.17.2)
+**Last Updated**: 2026-03-12
+**Status**: Production Ready (v0.23.0)
diff --git a/docs/planning/README.md b/docs/planning/README.md
@@ -1,7 +1,7 @@
 # Planning Index
 
 **Last Updated**: 2026-02-20
-**Current Version**: v0.22.2
+**Current Version**: v0.23.0
 
 ---
 

diff --git a/docs/planning/ROADMAP.md b/docs/planning/ROADMAP.md
@@ -1,7 +1,7 @@
 # codeindex Strategic Roadmap
 
 **Last Updated**: 2026-03-06
-**Current Version**: v0.22.2
+**Current Version**: v0.23.0
 **Vision**: Universal Code Parser - Best-in-class multi-language AST parser for AI-assisted development
 **Positioning**: Focused on code parsing and structured data extraction, not AI analysis
 
@@ -534,4 +534,4 @@
 **Next Review**: 2026-03-31
 **Maintained By**: @dreamlx
 **Last Updated**: 2026-03-06
-**Current Version**: v0.22.2
+**Current Version**: v0.23.0
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "ai-codeindex"
-version = "0.22.2"
+version = "0.23.0"
 description = "AI-native code indexing tool for large codebases"
 readme = "README.md"
 requires-python = ">=3.10"