sourcecode 1.6.0__tar.gz → 1.8.0__tar.gz

{sourcecode-1.6.0 → sourcecode-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.6.0
+Version: 1.8.0
 Summary: Deterministic codebase context for AI coding agents
 License:                                  Apache License
                                    Version 2.0, January 2004

{sourcecode-1.6.0 → sourcecode-1.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "1.6.0"
+version = "1.8.0"
 description = "Deterministic codebase context for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-1.6.0 → sourcecode-1.8.0}/src/sourcecode/__init__.py

@@ -1,3 +1,3 @@
 """sourcecode — Deterministic codebase context maps for AI coding agents."""
 
-__version__ = "1.6.0"
+__version__ = "1.8.0"

{sourcecode-1.6.0 → sourcecode-1.8.0}/src/sourcecode/adaptive_scanner.py

@@ -135,7 +135,8 @@ class AdaptiveScanner:
             if current_depth >= n:
                 # At or inside the source root
                 if rel_parts[:n] == src_parts:
-                    return src_max  # definite source territory — early exit
+                    # base_depth acts as a floor — explicit --depth always wins
+                    return max(src_max, self.base_depth)
             else:
                 # Ancestor check: src_parts starts with rel_parts?
                 if src_parts[:current_depth] == rel_parts:

{sourcecode-1.6.0 → sourcecode-1.8.0}/src/sourcecode/cli.py

@@ -10,6 +10,7 @@ import typer
 
 from sourcecode import __version__
 from sourcecode.entrypoint_classifier import is_production_entry_point, normalize_entry_point
+from sourcecode.progress import Progress
 
 
 # ---------------------------------------------------------------------------
@@ -138,18 +139,19 @@ def _check_pipeline_coherence(sm: "SourceMap") -> list[str]:  # type: ignore[nam
     return issues
 
 _HELP = """\
-Deterministic codebase context for AI coding agents.
+Compressed AI-ready context for Java/Spring enterprise codebases.
 
-[bold]Usage:[/bold]
-  sourcecode                   [dim]# analyze current directory[/dim]
-  sourcecode /path/to/repo     [dim]# analyze specific path[/dim]
-  sourcecode --agent           [dim]# structured output for AI agents[/dim]
+[bold]Examples:[/bold]
+  sourcecode saint-server --compact
+  sourcecode . --changed-only --git-context
+  sourcecode saint-server --symbol SeguridadRestController
+  sourcecode prepare-context onboard saint-server
+  sourcecode prepare-context delta . --since main
 
 [bold]Subcommands:[/bold]
-  prepare-context TASK [PATH]  [dim]# task-specific context[/dim]
+  prepare-context TASK [PATH]  [dim]# task-specific context (onboard, delta, fix-bug, ...)[/dim]
   telemetry status|enable|disable
   version
-  config
 """
 
 # Known subcommand names — tokens matching these are routed as subcommands,
@@ -352,58 +354,55 @@ def main(
         "json",
         "--format",
         "-f",
-        help="Output format: json (default) or yaml. Both carry identical data — yaml is more human-readable, json is preferred for agent pipelines.",
+        help="Output format: json (default) or yaml.",
         show_default=True,
     ),
     output: Optional[Path] = typer.Option(
         None,
         "--output",
         "-o",
-        help="Write output to a file instead of stdout. Useful for storing analysis snapshots or piping to downstream tools.",
+        help="Write output to a file instead of stdout.",
     ),
     compact: bool = typer.Option(
         False,
         "--compact",
         help=(
-            "Compact output (~600–800 tokens): project type, stacks, production entry points, "
-            "dependency summary, confidence summary, and analysis gaps. "
-            "Omits file tree, raw dependency lists, docs, and module graph. "
-            "Designed for agent context windows. Automatically enables --dependencies, --env-map, and --code-notes."
+            "High-signal summary (~600–800 tokens): stacks, entry points, "
+            "dependency summary, confidence, and gaps. "
+            "Optimized for agent context windows."
         ),
     ),
     dependencies: bool = typer.Option(
         False,
         "--dependencies",
-        help=(
-            "Analyze direct and transitive dependencies. Reads manifests (pyproject.toml, package.json, go.mod, etc.) "
-            "and lockfiles when available. Adds dependency_summary and key_dependencies to output."
-        ),
+        hidden=True,
+        help="Analyze direct dependencies from manifests and lockfiles.",
     ),
     graph_modules: bool = typer.Option(
         False,
         "--graph-modules",
-        help=(
-            "Include a structural module graph: nodes (files/symbols) and edges (imports, calls, contains). "
-            "Useful for understanding coupling and call flows. Adds module_graph to output. "
-            "Combine with --graph-detail and --graph-edges to control scope."
-        ),
+        hidden=True,
+        help="Include a structural module graph in output.",
     ),
     graph_detail: str = typer.Option(
         "high",
         "--graph-detail",
-        help="Detail level for --graph-modules: high (top modules by importance), medium (filtered by relevance), full (all nodes and edges). Default: high.",
+        hidden=True,
+        help="Detail level for --graph-modules: high, medium, full.",
         show_default=True,
     ),
     max_nodes: Optional[int] = typer.Option(
         None,
         "--max-nodes",
-        help="Maximum number of nodes in --graph-modules output when using high or medium detail. Prevents oversized graphs in large codebases.",
+        hidden=True,
+        help="Maximum nodes in --graph-modules output.",
         min=1,
     ),
     graph_edges: Optional[str] = typer.Option(
         None,
         "--graph-edges",
-        help="Edge types for --graph-modules, comma-separated: imports,calls,contains,extends. Default: all available. Example: --graph-edges imports,calls",
+        hidden=True,
+        help="Edge types for --graph-modules, comma-separated: imports,calls,contains,extends.",
     ),
     no_tree: bool = typer.Option(
         False,
@@ -414,18 +413,13 @@ def main(
     tree: bool = typer.Option(
         False,
         "--tree",
-        help=(
-            "Include the full file_tree and flat file_paths list in output (deep-dive layer). "
-            "Adds significant size — use when the agent needs to browse the full file structure."
-        ),
+        hidden=True,
+        help="Include the full file_tree and flat file_paths list in output.",
     ),
     no_redact: bool = typer.Option(
         False,
         "--no-redact",
-        help=(
-            "Disable automatic secret redaction. By default, potential secrets (API keys, tokens, passwords) "
-            "are replaced with [REDACTED]. Use with caution — output may contain sensitive values."
-        ),
+        help="Disable secret redaction. Use with caution — output may contain sensitive values.",
     ),
     version: Optional[bool] = typer.Option(
         None,
@@ -438,122 +432,97 @@ def main(
     depth: int = typer.Option(
         4,
         "--depth",
-        help=(
-            "Maximum depth for file tree traversal (default: 4, range: 1–20). "
-            "Increase for deeply nested projects — Maven/Java requires at least 8 (src/main/java/...)."
-        ),
+        help="File tree traversal depth (default: 4). Java/Maven projects auto-adjust to 12.",
         min=1,
         max=20,
     ),
     docs: bool = typer.Option(
         False,
         "--docs",
-        help="Extract documentation: docstrings, function signatures, and module-level comments. Adds doc_summary and docs to output. Combine with --docs-depth to control coverage.",
+        hidden=True,
+        help="Extract documentation: docstrings, function signatures, and module-level comments.",
     ),
     docs_depth: str = typer.Option(
         "symbols",
         "--docs-depth",
-        help="Documentation extraction depth: module (module-level only), symbols (functions and classes), full (all symbols including private). Default: symbols.",
+        hidden=True,
+        help="Documentation extraction depth: module, symbols, full.",
         show_default=True,
     ),
     full_metrics: bool = typer.Option(
         False,
         "--full-metrics",
-        help=(
-            "Technical audit: lines of code, symbol counts, cyclomatic complexity, and test coverage per file. "
-            "Produces file_metrics and metrics_summary. "
-            "Not included in --agent output — designed for CI pipelines and code review tools, not as primary agent context."
-        ),
+        hidden=True,
+        help="Technical audit: LOC, complexity, test coverage per file.",
     ),
     semantics: bool = typer.Option(
         False,
         "--semantics",
-        help=(
-            "Semantic analysis: cross-file symbol resolution, call graph with confidence levels, and import linking. "
-            "Adds semantic_calls, semantic_symbols, semantic_links, semantic_summary, and hotspots (files ranked by fan-in/fan-out). "
-            "Slower than default analysis — skip for quick scans. "
-            "Confidence degrades on dynamic dispatch, decorators, and generated code."
-        ),
+        hidden=True,
+        help="Cross-file symbol resolution and call graph analysis.",
     ),
     architecture: bool = typer.Option(
         False,
         "--architecture",
-        help=(
-            "Architectural inference: detect functional layers (MVC/layered/hexagonal), bounded contexts, "
-            "and dominant structural patterns. Adds architecture to output. "
-            "Confidence is low when based on directory names alone — combine with --semantics for higher accuracy."
-        ),
+        hidden=True,
+        help="Architectural layer inference (MVC/hexagonal/layered).",
     ),
     git_context: bool = typer.Option(
         False,
         "--git-context",
         "-g",
-        help="Include git activity: recent commits, change hotspots (most frequently modified files), pending uncommitted changes, and contributors. Adds git_context to output.",
+        help="Include git activity: recent commits, change hotspots, and uncommitted changes.",
     ),
     git_depth: int = typer.Option(
         20,
         "--git-depth",
-        help="Number of recent commits to include with --git-context (default: 20, max: 100).",
+        hidden=True,
+        help="Number of recent commits to include with --git-context (default: 20).",
         min=1,
         max=100,
     ),
     git_days: int = typer.Option(
         90,
         "--git-days",
-        help="Time window in days for detecting change hotspots with --git-context (default: 90). Hotspots are files with the most commits in this window.",
+        hidden=True,
+        help="Time window in days for change hotspot detection (default: 90).",
         min=1,
         max=3650,
     ),
     env_map: bool = typer.Option(
         False,
         "--env-map",
-        help="Map environment variables: keys, types (string/int/bool/url/path), categories (database/auth/service/...), and which files reference them. Adds env_map and env_summary.",
+        hidden=True,
+        help="Map environment variables referenced across the codebase.",
     ),
     code_notes: bool = typer.Option(
         False,
         "--code-notes",
-        help=(
-            "Extract inline annotations: TODO, FIXME, HACK, NOTE, DEPRECATED, WARNING, BUG, XXX, OPTIMIZE — "
-            "with file location and enclosing symbol. "
-            "Also detects Architecture Decision Records (ADRs) in docs/decisions/, docs/adr/, and similar paths."
-        ),
+        hidden=True,
+        help="Extract inline annotations: TODO, FIXME, HACK, DEPRECATED, ADRs.",
     ),
     agent: bool = typer.Option(
         False,
         "--agent",
-        help=(
-            "Agent-optimized output: structured, noise-free JSON for AI consumption. "
-            "Automatically enables --dependencies, --env-map, and --code-notes. Suppresses file tree. "
-            "Output includes: identity, entry points, architecture, runtime dependencies, "
-            "operational signals, confidence summary, and analysis gaps. No empty sections."
-        ),
+        help="Structured noise-free JSON for AI agents: identity, entry points, dependencies, confidence, gaps.",
     ),
     trace_pipeline: bool = typer.Option(
         False,
         "--trace-pipeline",
-        help=(
-            "Diagnostic mode: include pipeline_trace in output showing every candidate, filter decision, "
-            "and data origin across all pipeline stages. "
-            "Use to diagnose unexpected or contaminated results. Not intended for normal agent use."
-        ),
+        hidden=True,
+        help="Diagnostic: include full pipeline trace in output.",
     ),
     mode: str = typer.Option(
         "contract",
         "--mode",
-        help=(
-            "Output mode: contract (default) | standard | raw. "
-            "contract: minimal per-file contracts — exports, signatures, deps. "
-            "Smallest output, recommended for AI agents. "
-            "minimal is accepted as an alias for contract. "
-            "standard: full per-file detail with imports, relevance scores, extraction method. "
-            "raw: project-level analysis only (stacks, entry points, dependency summary). "
-            "No per-file contracts."
-        ),
+        hidden=True,
+        help="Output mode: contract (default) | standard | raw.",
     ),
     max_symbols: Optional[int] = typer.Option(
         None,
         "--max-symbols",
-        help="Limit total exported semantic nodes across all file contracts. Trims lowest-ranked files first.",
+        hidden=True,
+        help="Limit total exported semantic nodes across all file contracts.",
         min=1,
     ),
     dependency_depth: int = typer.Option(
@@ -567,22 +536,25 @@ def main(
     entrypoints_only: bool = typer.Option(
         False,
         "--entrypoints-only",
-        help="Contract mode: include only files that are runtime entrypoints or have exported symbols (public API surface). Note: 'entrypoints' here includes all files with exports, not strictly detected runtime entry points.",
+        hidden=True,
+        help="Include only files with exported symbols or runtime entrypoints.",
     ),
     changed_only: bool = typer.Option(
         False,
         "--changed-only",
-        help="Contract mode: include only git-modified files (staged, unstaged, untracked).",
+        help="Limit output to git-modified files (staged, unstaged, untracked).",
     ),
     rank_by: str = typer.Option(
         "relevance",
         "--rank-by",
+        hidden=True,
         help="Contract ranking strategy: relevance (default) | centrality | git-churn.",
     ),
     emit_graph: bool = typer.Option(
         False,
         "--emit-graph",
-        help="Contract mode: include a compact dependency graph (nodes + edges) in output.",
+        hidden=True,
+        help="Include a compact dependency graph in contract output.",
     ),
     compress_types: bool = typer.Option(
         False,
@@ -593,16 +565,13 @@ def main(
     symbol: Optional[str] = typer.Option(
         None,
         "--symbol",
-        help="Contract mode: extract localized context for a specific symbol name. Returns defining file + all importers.",
+        help="Extract context for a specific symbol: defining file + all importers.",
     ),
     max_importers: int = typer.Option(
         50,
         "--max-importers",
-        help=(
-            "Maximum importer files returned by --symbol (default: 50). "
-            "Popular symbols can have hundreds of importers — this prevents output explosion. "
-            "Defining files are never truncated. Override: --symbol Foo --max-importers 200."
-        ),
+        hidden=True,
+        help="Maximum importer files returned by --symbol (default: 50).",
         min=1,
         max=10000,
     ),
@@ -788,7 +757,7 @@ def main(
     # Require at least 8: src(1)+main(2)+java(3)+com(4)+co(5)+app(6)+module(7)+file.
     _java_manifest_names = {"pom.xml", "build.gradle", "build.gradle.kts"}
     _is_java = any(Path(m).name in _java_manifest_names for m in manifests)
-    _java_min_depth = 10
+    _java_min_depth = 12
     effective_depth = max(depth, _java_min_depth) if _is_java and depth < _java_min_depth else depth
 
     # --agent: enable signal analyzers; output via agent_view (not compact)
@@ -797,22 +766,9 @@ def main(
         env_map = True
         code_notes = True
         no_tree = True  # agents never need the raw file tree
-        typer.echo("[agent] dependencies env-map code-notes (no-tree)", err=True)
-        # Warn about flags that are computed but excluded from agent_view output
-        _agent_suppressed: list[str] = []
-        if full_metrics:
-            _agent_suppressed.append("--full-metrics")
-        if graph_modules:
-            _agent_suppressed.append("--graph-modules")
-        if docs:
-            _agent_suppressed.append("--docs")
-        if _agent_suppressed:
-            typer.echo(
-                f"[agent] warning: {', '.join(_agent_suppressed)} computed but excluded "
-                "from --agent output — agent_view does not include these sections. "
-                "Remove these flags to skip unnecessary computation.",
-                err=True,
-            )
+
+    _progress = Progress()
+    _progress.start("scanning files")
 
     scanner = AdaptiveScanner(target, topology=_topology, base_depth=effective_depth)
     raw_tree = scanner.scan_tree()
@@ -850,6 +806,7 @@ def main(
                 node = child
         return pruned
 
+    _progress.update("parsing manifests")
     file_tree = filter_sensitive_files(raw_tree)
     detector = ProjectDetector(build_default_detectors())
     workspace_analysis = WorkspaceAnalyzer().analyze(target, manifests)
@@ -1318,6 +1275,7 @@ def main(
 
     # Git Context (--git-context flag)
     if git_context:
+        _progress.update("git analysis")
         from sourcecode.git_analyzer import GitAnalyzer
         sm.git_context = GitAnalyzer().analyze(target, depth=git_depth, days=git_days)
 
@@ -1399,7 +1357,33 @@ def main(
                         ))
         sm = _replace(sm, pipeline_trace=_trace.build_trace())
 
+    # Pre-compute uncommitted files for --changed-only.
+    # The contract pipeline filter and git_context are two separate subsystems;
+    # wire them here so the pipeline uses git_context data, not an independent git call.
+    _allowed_changed_files: Optional[set[str]] = None
+    if changed_only:
+        from sourcecode.git_analyzer import GitAnalyzer as _GitAnalyzerEarly
+        try:
+            _gc_early = _GitAnalyzerEarly().analyze(target, depth=1, days=1)
+            _bad_gc = {"no_git_repo", "git_not_found", "git_timeout"}
+            if _gc_early and not (_bad_gc & set(_gc_early.limitations)):
+                _uc = _gc_early.uncommitted_changes
+                if _uc:
+                    _allowed_changed_files = (
+                        set(_uc.staged) | set(_uc.unstaged) | set(_uc.untracked)
+                    )
+            if not _allowed_changed_files:
+                typer.echo(
+                    "[changed-only] git unavailable or no uncommitted changes — falling back to full scan.",
+                    err=True,
+                )
+                changed_only = False
+        except Exception:
+            typer.echo("[changed-only] git error — falling back to full scan.", err=True)
+            changed_only = False
+
     # Contract pipeline — runs for mode=contract|standard|deep|hybrid (skip for raw)
+    _progress.update("extracting contracts")
     _is_contract_mode = mode in ("contract", "standard")
     _pipeline_error = False
     if _is_contract_mode:
@@ -1432,6 +1416,7 @@ def main(
                 max_importers=max_importers,
                 semantic_calls=sm.semantic_calls or None,
                 code_notes=sm.code_notes or None,
+                allowed_changed_files=_allowed_changed_files,
                 **_java_pipeline_kwargs,
             )
         except Exception as _exc:
@@ -1469,6 +1454,7 @@ def main(
                 )
 
     # 4. Serialize
+    _progress.update("serializing output")
     if _is_contract_mode and not agent:
         from sourcecode.serializer import contract_view as _contract_view
         _depth = _CONTRACT_DEPTH.get(mode, "minimal")
@@ -1560,6 +1546,7 @@ def main(
         pass
 
     # 6. Write output (CLI-04)
+    _progress.finish()
     write_output(content, output=output)
 
     if _pipeline_error:
@@ -1706,8 +1693,13 @@ def prepare_context_cmd(
     if llm_prompt:
         out["llm_prompt"] = builder.render_prompt(output)
 
+    import sys as _sys
     _pc_content = json.dumps(out, indent=2, ensure_ascii=False)
-    typer.echo(_pc_content)
+    _pc_bytes = _pc_content.encode("utf-8")
+    _sys.stdout.buffer.write(_pc_bytes)
+    if not _pc_content.endswith("\n"):
+        _sys.stdout.buffer.write(b"\n")
+    _sys.stdout.buffer.flush()
 
     if copy:
         _trimmed = _pc_content.strip()

{sourcecode-1.6.0 → sourcecode-1.8.0}/src/sourcecode/contract_pipeline.py

@@ -183,6 +183,7 @@ class ContractPipeline:
         code_notes: Optional[list] = None,
         max_contracts: Optional[int] = _MAX_CONTRACTS,
         min_score: Optional[float] = None,
+        allowed_changed_files: Optional[set[str]] = None,
     ) -> tuple[list[FileContract], ContractSummary]:
         """Run the full extraction pipeline.
 
@@ -200,9 +201,14 @@ class ContractPipeline:
         engine = RankingEngine(monorepo_packages)
 
         # 1. Changed files (for --changed-only and ranking)
+        # When allowed_changed_files is provided (from pre-computed git uncommitted_changes),
+        # use it directly. Otherwise fall back to independent git commands.
         changed_files: set[str] = set()
         if changed_only or rank_by == "git-churn":
-            changed_files = _get_changed_files(root)
+            if allowed_changed_files is not None:
+                changed_files = allowed_changed_files
+            else:
+                changed_files = _get_changed_files(root)
 
         # 2. Select files to extract
         # Exclude test files by default — they dominate by count but add noise

{sourcecode-1.6.0 → sourcecode-1.8.0}/src/sourcecode/prepare_context.py

@@ -398,11 +398,27 @@ class TaskContextBuilder:
         from sourcecode.tree_utils import flatten_file_tree
 
         _topology = RepoClassifier().classify(self.root)
-        scanner = AdaptiveScanner(self.root, topology=_topology, base_depth=6)
+        # Shallow pre-scan to detect Java manifests before choosing depth.
+        from sourcecode.scanner import FileScanner as _FileScanner
+        _pre = _FileScanner(self.root, max_depth=1)
+        _pre_manifests = _pre.find_manifests()
+        _java_names = {"pom.xml", "build.gradle", "build.gradle.kts"}
+        _is_java = any(Path(m).name in _java_names for m in _pre_manifests)
+        _base_depth = 12 if _is_java else 6
+        scanner = AdaptiveScanner(self.root, topology=_topology, base_depth=_base_depth)
         file_tree = scanner.scan_tree()
         manifests = scanner.find_manifests()
         all_paths = [p.replace("\\", "/") for p in flatten_file_tree(file_tree)]
 
+        # Warn when Java project has no Mapper.xml — suggests files below scan depth.
+        _mybatis_warning: dict | None = None
+        if _is_java and not any(p.endswith("Mapper.xml") for p in all_paths):
+            _mybatis_warning = {
+                "area": "mybatis",
+                "reason": "Mapper XML files may exist below scan depth. Re-run with --depth 12.",
+                "impact": "high",
+            }
+
         # ── 2. Detect stacks + entry points ───────────────────────────────
         from dataclasses import replace as _replace
         from sourcecode.detectors import ProjectDetector, build_default_detectors
@@ -500,6 +516,7 @@ class TaskContextBuilder:
         code_notes_summary: Optional[dict[str, Any]] = None
         suspected_areas: list[str] = []
         improvement_opportunities: list[str] = []
+        cn_notes_for_ranking: list = []
 
         if spec.enable_code_notes:
             from dataclasses import asdict
@@ -507,6 +524,7 @@ class TaskContextBuilder:
 
             cn_notes, _cn_adrs, cn_summary = CodeNotesAnalyzer().analyze(self.root)
             code_notes_summary = asdict(cn_summary)
+            cn_notes_for_ranking = cn_notes
 
             if task_name == "fix-bug":
                 bug_kinds = {"FIXME", "BUG", "HACK", "XXX"}
@@ -555,6 +573,7 @@ class TaskContextBuilder:
             monorepo_packages=sm.monorepo_packages if sm.monorepo_packages else None,
             git_hotspots=git_hotspots,
             uncommitted_files=uncommitted_files,
+            code_notes=cn_notes_for_ranking if cn_notes_for_ranking else None,
         )
 
         # ── 7. Test gaps (generate-tests only) ────────────────────────────
@@ -594,6 +613,8 @@ class TaskContextBuilder:
         conf_summary, analysis_gaps = ConfidenceAnalyzer().analyze(sm_for_conf)
         confidence = conf_summary.overall
         gaps = [g.reason for g in analysis_gaps]
+        if _mybatis_warning:
+            gaps.append(_mybatis_warning["reason"])
 
         # ── 9. why_these_files ────────────────────────────────────────────────
         why_these_files: dict[str, str] = {
@@ -705,6 +726,7 @@ class TaskContextBuilder:
         monorepo_packages: Optional[list] = None,
         git_hotspots: Optional[dict[str, int]] = None,
         uncommitted_files: Optional[set[str]] = None,
+        code_notes: Optional[list] = None,
     ) -> list[RelevantFile]:
         from sourcecode.ranking_engine import RankingEngine
         from sourcecode.file_classifier import FileClassifier
@@ -719,6 +741,35 @@ class TaskContextBuilder:
         _uncommitted = uncommitted_files or set()
         _max_churn = max(_hotspots.values(), default=1)
 
+        # Pre-compute fix-bug signals (used only when task_name == "fix-bug")
+        _annotated_files: set[str] = set()
+        _dominant_stack = ""
+        _recently_changed_stacks: set[str] = set()
+        if task_name == "fix-bug":
+            _bug_kinds = {"FIXME", "BUG"}
+            for _n in (code_notes or []):
+                if getattr(_n, "kind", "").upper() in _bug_kinds:
+                    _annotated_files.add(getattr(_n, "path", ""))
+
+            def _file_stack(p: str) -> str:
+                ext = Path(p).suffix.lower()
+                if ext == ".java": return "java"
+                if ext in (".ts", ".tsx", ".js", ".jsx", ".mjs"): return "typescript"
+                if ext == ".py": return "python"
+                if ext == ".go": return "go"
+                if ext in (".kt", ".kts"): return "kotlin"
+                if ext == ".rs": return "rust"
+                if ext == ".rb": return "ruby"
+                return "unknown"
+
+            from collections import Counter as _Counter
+            _stk_counts: _Counter[str] = _Counter(
+                _file_stack(f) for f in _uncommitted if _file_stack(f) != "unknown"
+            )
+            if _stk_counts:
+                _dominant_stack = _stk_counts.most_common(1)[0][0]
+                _recently_changed_stacks = set(_stk_counts.keys())
+
         scored: list[tuple[float, str, RelevantFile]] = []
 
         for path in all_paths:
@@ -762,10 +813,28 @@ class TaskContextBuilder:
 
             # Task-specific boosts for differentiated file weighting
             path_lower = path.lower()
+            _fix_bug_why = ""
             if task_name == "fix-bug":
-                if any(x in path_lower for x in ("exception", "error", "handler", "advice")):
-                    content_boost += 1.5
-                    content_reasons.append("exception handler — high risk area")
+                _why_parts: list[str] = []
+                if path in _uncommitted:
+                    content_boost += 0.40
+                    _why_parts.append("uncommitted change (+0.40)")
+                _recency = min(0.30, _hotspots.get(path, 0) * 0.05)
+                if _recency > 0:
+                    content_boost += _recency
+                    _why_parts.append(f"recent commits (+{_recency:.2f})")
+                if path in _annotated_files:
+                    content_boost += 0.20
+                    _why_parts.append("FIXME/BUG annotation (+0.20)")
+                _file_stk = _file_stack(path)
+                if _dominant_stack and _file_stk == _dominant_stack:
+                    content_boost += 0.10
+                    _why_parts.append("dominant changed stack (+0.10)")
+                if _recently_changed_stacks and _file_stk not in _recently_changed_stacks and _file_stk != "unknown":
+                    content_boost -= 0.30
+                    _why_parts.append("different stack from recent changes (-0.30)")
+                if _why_parts:
+                    _fix_bug_why = ", ".join(_why_parts)
             elif task_name == "generate-tests":
                 stem = Path(path).stem.lower()
                 has_test = any(
@@ -797,7 +866,7 @@ class TaskContextBuilder:
             )
             all_reasons = [r for r in fs.reasons if r != "source file"] + content_reasons
             reason_str = ", ".join(all_reasons) if all_reasons else "source file"
-            why_str = _java_why(path, file_class)
+            why_str = _fix_bug_why if _fix_bug_why else _java_why(path, file_class)
 
             scored.append((total, path, RelevantFile(
                 path=path,