docs: update docs for v0.6.0-rc-1 with AstDiffer and 410 tests

Documents shipped v0.6.0 features: parent scope extraction, structural
AST diffs via AstDiffer, import change detection, doc-vs-code
SpanChangeKind classification, and adaptive token budgeting. Updates
test count from 367 to 410 across README, DOCS, CHANGELOG, and PRD.

Author: Sephyi

CHANGELOG.md

@@ -8,7 +8,7 @@ SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Commercial
 
 All notable changes to CommitBee are documented here.
 
-## `v0.6.0` — Deep Understanding (current, in progress)
+## `v0.6.0-rc.1` — Deep Understanding (release candidate)
 
 ### Semantic Analysis
 
@@ -18,11 +18,20 @@ All notable changes to CommitBee are documented here.
 - **Test file correlation** — New `RELATED FILES:` prompt section shows when source files and their matching test files are both staged. Stem-based matching, capped at 5 entries.
 - **Structural AST diffs** — `AstDiffer` compares old and new tree-sitter nodes for modified symbols, producing structured `SymbolDiff` descriptions (parameter added, return type changed, visibility changed, async toggled, body modified). Shown as `STRUCTURED CHANGES:` section in the prompt.
 - **Whitespace-aware body comparison** — Body diff uses character-stream stripping so reformatting doesn't produce false `BodyModified` results.
+- **Structured changes in prompt** — New `STRUCTURED CHANGES:` section in the LLM prompt shows concise one-line descriptions of what changed per symbol (e.g., `CommitValidator::validate(): +param strict: bool, return bool → Result<()>, body modified`). Omitted when no structural diffs exist.
 
 ### Type Inference
 
 - **Test-to-code ratio** — When >80% of additions are in test files, suggests `test` type even with source files present. Uses cross-multiplication to avoid integer truncation.
 
+### Prompt Quality
+
+- **Token budget rebalance** — Symbol budget reduced from 30% to 20% when structural diffs are available, freeing space for the raw diff. SYSTEM_PROMPT updated to guide the LLM to prefer STRUCTURED CHANGES for signature details.
+
+### Testing
+
+- **410 tests** total (up from 367 at v0.5.0).
+
 ## `v0.5.0` — Beyond the Diff
 
 ### Semantic Analysis
@@ -56,7 +65,7 @@ All notable changes to CommitBee are documented here.
 - **Evaluation harness** — 36 fixtures covering all 11 commit types, AST features, and edge cases. Per-type accuracy reporting with `EvalSummary`.
 - **15+ new unit tests** — Coverage for `detect_primary_change`, `detect_metadata_breaking`, `detect_bug_evidence` (all 7 patterns), Deleted/Renamed status, signature edge cases, connection content assertions.
 - **5 fuzz targets** — `fuzz_sanitizer`, `fuzz_safety`, `fuzz_diff_parser`, `fuzz_signature`, `fuzz_classify_span`.
-- **367 tests** total (up from 308 at v0.4.0).
+- **367 tests** total (up from 308 at v0.4.0). Current count at v0.6.0-rc.1: 410.
 
 ### API
 

DOCS.md

@@ -86,11 +86,11 @@ Here's what each step actually does:
 
 **1. Git Service** reads your staged changes using `gix` for repo discovery and the git CLI for diffs. Paths are parsed with NUL-delimited output (`-z` flag) so filenames with spaces or special characters work correctly.
 
-**2. Tree-sitter Analyzer** parses both the staged version and the HEAD version of every changed file — in parallel, using `rayon` across CPU cores. It extracts **full signatures** (e.g., `pub fn connect(host: &str, timeout: Duration) -> Result<Connection>`) by taking the definition node text before the body child. Modified symbols show old → new signature diffs. Cross-file connections are detected (caller+callee both changed). Symbols are tracked in three states: added, removed, or modified-signature.
+**2. Tree-sitter Analyzer** parses both the staged version and the HEAD version of every changed file — in parallel, using `rayon` across CPU cores. It extracts **full signatures** (e.g., `pub fn connect(host: &str, timeout: Duration) -> Result<Connection>`) by taking the definition node text before the body child. Methods include their **parent scope** (enclosing impl, class, or trait — e.g., `CommitValidator::validate`). Modified symbols show old → new signature diffs, with **structural AST diffs** that describe exactly what changed (parameters added/removed, return type changed, visibility changed, etc.). Cross-file connections are detected (caller+callee both changed). Symbols are tracked in three states: added, removed, or modified-signature, with a **doc-vs-code distinction** indicating whether changes were documentation-only, code-only, or mixed.
 
 **3. Commit Splitter** looks at your staged changes and decides whether they contain logically independent work. It uses diff-shape fingerprinting (what kind of changes — additions, deletions, modifications) combined with Jaccard similarity on content vocabulary to group files. If it finds multiple concerns, it offers to split them into separate commits.
 
-**4. Context Builder** assembles a budget-aware prompt. It classifies modified symbols as whitespace-only or semantic (via character-stream comparison), computes evidence flags (mechanical change? public APIs removed? bug-fix evidence?), detects cross-file connections, calculates the character budget for the subject line, and packs context within the token limit (~6K tokens, 30/70 symbol/diff split when signatures present).
+**4. Context Builder** assembles a budget-aware prompt. It classifies modified symbols as whitespace-only or semantic (via character-stream comparison), computes evidence flags (mechanical change? public APIs removed? bug-fix evidence?), detects cross-file connections, identifies import changes and test file correlations, calculates the character budget for the subject line, and packs context within the token limit (~6K tokens). The token budget adapts: when structural AST diffs are available, symbols get 20% of the budget (diffs carry more detail); when only signatures are available, symbols get 30%.
 
 **5. LLM Provider** streams the prompt to your chosen model (Ollama, OpenAI, or Anthropic) and collects the response token by token.
 
@@ -107,6 +107,10 @@ CommitBee doesn't just send a diff. The prompt includes:
 - **Evidence flags** telling the LLM deterministic facts about the change
 - **Symbol changes with full signatures** — `[+] pub fn connect(host: &str) -> Result<()>`, not just "Function connect"
 - **Signature diffs** — `[~] old_sig → new_sig` for modified symbols
+- **Structured AST diffs** — `CommitValidator::validate(): +param timeout, return Result<()> → Result<Error>` (precise semantic changes from AST comparison)
+- **Import changes** — `analyzer: added use crate::domain::DiffHunk` (tracked per file)
+- **Test file correlations** — `src/services/context.rs <-> tests/context.rs (test file)`
+- **Doc-vs-code annotations** — modified symbols tagged `[docs only]` or `[docs + code]` when change is documentation-only or mixed
 - **Cross-file connections** — `validator calls parse() — both changed`
 - **Primary change detection** — which file has the most significant changes
 - **Constraints** — rules the LLM must follow based on evidence (e.g., "no bug-fix comments found, prefer refactor over fix")
@@ -570,7 +574,9 @@ For supported languages, symbols are tracked in three states:
 - **Removed** `[-]` — Deleted symbol
 - **Modified (signature changed)** `[~]` — Symbol exists in both versions but its signature changed
 
-This information appears in the prompt as a `SYMBOLS CHANGED` section, giving the LLM precise knowledge of what was structurally modified.
+Modified symbols include additional annotations: `[docs only]` when only documentation/comments changed, `[docs + code]` when both documentation and code changed. Methods show their parent scope (e.g., `CommitValidator::validate` rather than just `validate`).
+
+This information appears in the prompt as a `SYMBOLS CHANGED` section. When structural AST diffs are available, a separate `STRUCTURED CHANGES` section provides precise details like `+param timeout`, `return Result<()> → Result<Error>`, or `+field name`.
 
 ## 🔧 Troubleshooting
 
@@ -650,13 +656,15 @@ src/
 ├── error.rs             # Error types (thiserror + miette diagnostics)
 ├── domain/
 │   ├── change.rs        # FileChange, StagedChanges, ChangeStatus
-│   ├── symbol.rs        # CodeSymbol, SymbolKind (Added/Removed/Modified)
+│   ├── symbol.rs        # CodeSymbol, SymbolKind, SpanChangeKind
+│   ├── diff.rs          # SymbolDiff, ChangeDetail (structural AST diffs)
 │   ├── context.rs       # PromptContext — assembles the LLM prompt
 │   └── commit.rs        # CommitType enum (single source of truth)
 └── services/
     ├── git.rs           # GitService — gix for discovery, git CLI for diffs
     ├── analyzer.rs      # AnalyzerService — tree-sitter parsing via rayon
     ├── context.rs       # ContextBuilder — evidence flags, token budget
+    ├── differ.rs        # AstDiffer — structural comparison of old/new symbols
     ├── safety.rs        # Secret scanning (24 patterns), conflict detection
     ├── sanitizer.rs     # CommitSanitizer + CommitValidator
     ├── splitter.rs      # CommitSplitter — diff-shape + Jaccard clustering
@@ -678,7 +686,7 @@ src/
 
 **Streaming with Cancellation** — All providers support Ctrl+C cancellation via `tokio_util::CancellationToken`. The streaming display runs in a separate tokio task with `tokio::select!` for responsive cancellation.
 
-**Token Budget** — The context builder tracks character usage (~4 chars per token) and truncates the diff if it exceeds the budget, prioritizing the most important files. The default 24K char budget (~6K tokens) is safe for 8K context models.
+**Token Budget** — The context builder tracks character usage (~4 chars per token) and truncates the diff if it exceeds the budget, prioritizing the most important files. The budget adapts based on available information: when structural AST diffs are present, the symbol allocation shrinks (20%) since the diffs carry precise detail; when only signatures are available, symbols get 30%. The default 24K char budget (~6K tokens) is safe for 8K context models.
 
 **Single Source of Truth for Types** — `CommitType::ALL` is a const array that defines all valid commit types. The system prompt's type list is verified at compile time (via a `#[test]`) to match this array exactly.
 
@@ -694,7 +702,7 @@ No panics in user-facing code paths. The sanitizer and validator are tested with
 
 ### Testing Strategy
 
-CommitBee has 367 tests across multiple strategies:
+CommitBee has 410 tests across multiple strategies:
 
 | Strategy | What It Covers |
 | --- | --- |
@@ -707,7 +715,7 @@ CommitBee has 367 tests across multiple strategies:
 Run them:
 
 ```bash
-cargo test                    # All 367 tests
+cargo test                    # All 410 tests
 cargo test --test sanitizer   # Just sanitizer tests
 cargo test --test integration # LLM provider mocks
 COMMITBEE_LOG=debug cargo test -- --nocapture  # With logging

PRD.md

@@ -6,8 +6,8 @@ SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Commercial
 
 # CommitBee — Product Requirements Document
 
-**Version**: 4.3
-**Date**: 2026-03-27
+**Version**: 4.3  
+**Date**: 2026-03-27  
 **Status**: Active  
 **Author**: [Sephyi](https://github.com/Sephyi) + [Claude Opus 4.6](https://www.anthropic.com/news/claude-opus-4-6)  
 
@@ -18,7 +18,7 @@ SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Commercial
 
 | Version | Date       | Summary |
 |---------|------------|---------|
-| 4.3     | 2026-03-27 | v0.6.0 deep semantic understanding (in progress): Tier 2 — parent scope extraction for impl/class/trait methods (7 languages), import change detection (Rust/TS/JS/Python/Go/C/C++), doc-vs-code SpanChangeKind classification with Mixed variant, test-to-code ratio type inference, test file correlation. Tier 1 — SymbolDiff types + ChangeDetail enum (15 variants), AstDiffer for structural function diffing (params, return type, visibility, async, body), pipeline integration into extract_symbols/ContextBuilder. Plans dialectic-verified by GLM5 + Codex gpt-5.4 + Gemini 2.5 Pro with 12 fixes applied. 401+ tests. |
+| 4.3     | 2026-03-27 | v0.6.0-rc.1 deep semantic understanding: parent scope, import detection, doc-vs-code classification, structural AST diffs (AstDiffer + SymbolDiff), STRUCTURED CHANGES prompt section, token budget rebalance. 410 tests. |
 | 4.2     | 2026-03-22 | v0.5.0 hardening: security fixes (SSRF prevention, streaming caps), prompt optimization (budget fix, evidence omission, emoji removal), eval harness (36 fixtures, per-type reporting), test coverage (15+ new tests), API hygiene (pub(crate) demotions), 5 fuzz targets. 359 tests. |
 | 4.1     | 2026-03-22 | AST context overhaul (v0.5.0): full signature extraction from tree-sitter nodes, semantic change classification (whitespace vs body vs signature), old→new signature diffs, cross-file connection detection, formatting auto-detection via symbols. 359 tests. |
 | 4.0     | 2026-03-13 | PRD normalization: aligned phases with shipped versions (v0.2.0/v0.3.x/v0.4.0), collapsed revision history, unified status markers, resolved stale critical issues, canonicalized test count to 308, removed dead cross-references. FR-031 (Exclude Files) and FR-033 (Copy to Clipboard) shipped. |
@@ -61,6 +61,8 @@ CommitBee is a Rust-native CLI tool that uses tree-sitter semantic analysis and
 | v0.3.0  | Differentiation core (splitter enhancements, validation, heuristics) | None |
 | v0.3.1  | Patch — default model → `qwen3.5:4b`, subject length validation, `think` config | None |
 | v0.4.0  | Feature completion (templates, languages, rename detection, history learning) | None |
+| v0.5.0  | AST context overhaul (signatures, semantic classification, cross-file connections) | None |
+| v0.6.0-rc.1 | Deep semantic understanding (parent scope, imports, doc-vs-code, structural AST diffs) | None |
 
 ## 2. Competitive Landscape
 
@@ -93,7 +95,7 @@ CommitBee is a Rust-native CLI tool that uses tree-sitter semantic analysis and
 | Multiple message generation (pick from N)          | Common (aicommits, aicommit2) | ✅ v0.2.0       |
 | Commit splitting (multi-concern detection)         | No competitor has this        | ✅ v0.2.0       |
 | Custom prompt/instruction files                    | Growing (Copilot, aicommit2)  | ✅ v0.4.0       |
-| Unit/integration tests                             | Non-negotiable for quality    | ✅ 359 tests    |
+| Unit/integration tests                             | Non-negotiable for quality    | ✅ 410 tests    |
 
 ## 3. Architecture
 
@@ -479,7 +481,37 @@ Project-level `.commitbee.toml` can no longer override `openai_base_url`, `anthr
 
 Subject character budget accounts for `!` suffix on breaking changes. EVIDENCE section omitted when all flags are default (~200 chars saved). Symbol marker legend added to SYSTEM_PROMPT (`[+] added, [-] removed, [~] modified`). Duplicate JSON schema removed from system prompt. Emoji replaced with text labels (`WARNING:` instead of `⚠`). CONNECTIONS instruction softened for small models. Python tree-sitter queries enhanced with `decorated_definition` support.
 
-### 4.6 Future — v0.6.0+ (Market Leadership)
+### 4.6 Shipped — v0.6.0-rc.1 (Deep Semantic Understanding)
+
+#### FR-064: Parent Scope Extraction ✅
+
+Tree-sitter AST walker extracts enclosing `impl`/`class`/`trait` scope for methods, displaying `Parent > signature` format in symbol output. Walks through intermediate nodes (`declaration_list`, `class_body`). Verified across 7 languages (Rust, Python, TypeScript, Java, Go, Ruby, C#). 10 per-language tests.
+
+#### FR-065: Import Change Detection ✅
+
+`detect_import_changes()` scans diff lines for added/removed import statements, producing an `IMPORTS CHANGED:` prompt section with file stem and action. Supports Rust `use`, JS/TS `import`, Python `from`/`import`, Node `require()`, C/C++ `#include`. Capped at 10 entries. 5 tests.
+
+#### FR-066: Doc-vs-Code Change Classification ✅
+
+`SpanChangeKind` enum (`Unchanged`, `WhitespaceOnly`, `DocsOnly`, `Mixed`, `Semantic`) replaces binary `is_whitespace_only` for richer modified-symbol classification. `classify_span_change_rich()` detects comment-line prefixes (`///`, `//!`, `#`, `"""`, `/**`). Doc-only modifications suggest `docs` type. Modified symbols show `[docs only]` or `[docs + code]` suffix in prompt output. 7 tests.
+
+#### FR-067: Test-to-Code Ratio Inference ✅
+
+In `infer_commit_type`, when >80% of additions are in `FileCategory::Test` files, returns `CommitType::Test` even with source files present. Uses cross-multiplication (`test * 100 > total * 80`) to avoid integer truncation. 2 tests.
+
+#### FR-068: Test File Correlation ✅
+
+`detect_test_correlation()` matches staged source files to test files by file stem, producing a `RELATED FILES:` prompt section (e.g., `src/services/context.rs <-> tests/context.rs (test file)`). Capped at 5 entries. 4 tests.
+
+#### FR-069: Structural AST Diffs ✅
+
+`AstDiffer` in `src/services/differ.rs` compares old and new tree-sitter AST nodes for modified symbols, producing `SymbolDiff` with `Vec<ChangeDetail>` (15-variant enum: `ParamAdded`, `ParamRemoved`, `ParamTypeChanged`, `ReturnTypeChanged`, `VisibilityChanged`, `AttributeAdded`/`Removed`, `AsyncChanged`, `GenericChanged`, `BodyModified`, `BodyUnchanged`, `FieldAdded`/`Removed`/`TypeChanged`). Runs inside `extract_for_file()` while both Trees are alive (Node lifetime constraint). `extract_symbols()` returns `(Vec<CodeSymbol>, Vec<SymbolDiff>)`. Struct/enum field diffing stubbed for future. Whitespace-aware body comparison via character-stream stripping. 7 unit tests + 6 per-language integration tests.
+
+#### FR-070: Structured Changes Prompt Section ✅
+
+`STRUCTURED CHANGES:` section in LLM prompt renders `SymbolDiff::format_oneline()` descriptions (e.g., `CommitValidator::validate(): +param strict: bool, return bool → Result<()>, body modified (+5 -2)`). Omitted when no structural diffs exist. Token budget rebalanced: symbol budget reduced from 30% to 20% when structural diffs available, freeing space for raw diff. SYSTEM_PROMPT updated to guide LLM to prefer structured changes for signature details. 3 tests.
+
+### 4.7 Future — v0.7.0+ (Market Leadership)
 
 #### FR-050: MCP Server Mode
 
@@ -661,7 +693,7 @@ commitbee eval                         # Run evaluation harness (dev, feature-ga
 
 ## 8. Testing Requirements
 
-**Current test count: 367**
+**Current test count: 410**
 
 ### TR-001: Unit Tests
 
@@ -819,9 +851,9 @@ Invalid JSON → retry once with repair prompt. Second failure → heuristic ext
 | 2 | v0.3.x | ✅ Shipped | Differentiation — heuristics, validation, spec compliance |
 | 3 | v0.4.0 | ✅ Shipped | Feature completion — templates, languages, rename, history, eval, fuzzing |
 | 4 | v0.4.x | ✅ Shipped | Remaining polish — exclude files (FR-031), clipboard (FR-033) |
-| 5 | v0.5.0 | ✅ Shipped | AST context overhaul — full signatures, semantic change classification, cross-file connections. 359 tests. |
-| 5.5 | v0.5.x | 🔨 Next | Deep semantic understanding — parent scope, imports, doc-vs-code (T2), structural AST diffs (T1), language markers + change intent (T3). Plans dialectic-verified 2026-03-26. |
-| 6 | v0.6.0+ | 📋 Planned | Market leadership — MCP server, changelog, monorepo, version bumping, GitHub Action |
+| 5 | v0.5.0 | ✅ Shipped | AST context overhaul — full signatures, semantic change classification, cross-file connections. 367 tests. |
+| 6 | v0.6.0-rc.1 | ✅ Shipped | Deep semantic understanding — parent scope, import detection, doc-vs-code classification, structural AST diffs, structured changes prompt section. 410 tests. |
+| 7 | v0.7.0+ | 📋 Planned | Market leadership — MCP server, changelog, monorepo, version bumping, GitHub Action |
 
 ## 12. Success Metrics
 
@@ -835,7 +867,7 @@ Invalid JSON → retry once with repair prompt. Second failure → heuristic ext
 | Commit message quality | > 80% "good enough" first try | Manual evaluation + `commitbee eval` |
 | Secret leak rate | 0 | Integration tests with known patterns |
 | MSRV | Rust 1.94 (edition 2024) | CI matrix (stable + 1.94) |
-| Test count | ≥ 308 | `cargo test` (current: 359) |
+| Test count | ≥ 308 | `cargo test` (current: 410) |
 
 ## 13. Non-Goals