sourcecode 1.5.0__tar.gz → 1.7.0__tar.gz

sourcecode-1.7.0/.continue-here.md

@@ -0,0 +1,105 @@
+# Continue Here — sourcecode Java/Spring Enterprise Bug Fixes v1.5.x
+**Created:** 2026-05-08  
+**Session context:** Ad-hoc benchmark-driven bug fixes (not a GSD phase execution)
+
+---
+
+## What Was Done This Session
+
+Applied 5 fixes targeting regressions in v1.5.0 benchmark report on saint-server (3681 .java, 460 *RestController*, 52 *Mapper.xml, Spring Boot 2.7.18 DDD+legacy layout).
+
+### Root Causes Found and Fixed
+
+| ID | File(s) | Root Cause | Fix |
+|----|---------|-----------|-----|
+| N1 | `detectors/java.py` | Scanner `depth >= max_depth=10` cuts `ddd/*/infraestructure/rest/` files silently. Path `src/main/java/com/m3/saint/ddd/domain/infraestructure/rest/` = 10 parts → excluded from file_tree → not in entry_points. | New `_augment_deep_java_controllers()`: direct `os.walk` of `src/main/java/` for `*Controller*.java` files not in file_tree |
+| G3 | `contract_pipeline.py` | Mapper.xml score=0.3 (no `.xml` suffix boost) < Java score=0.4. 3000+ files compete for 2500-file cap — all 52 Mapper.xml cut. | `_is_priority()`: Mapper.xml gets same priority as entry_points in cap sort |
+| T11 | `contract_pipeline.py` | Centrality sort key ignored `is_entrypoint`. REST controllers have low fan_in → ranked below JPA entities. | Added `-c.is_entrypoint` as primary key in centrality sort |
+| P3-B | `cli.py` | Auto-switch to centrality when DDD architecture detected — actively hurt REST controller visibility. | Removed 5-line P3-B block |
+| N2 | `serializer.py` | `hotspots` removed from top-level output in v1.5.0, only in `semantic_summary`. Breaking for consumers using `d["hotspots"]`. | Restore `result["hotspots"]` at top level when `semantic_summary.hotspots` exists |
+
+### Modified Files (uncommitted — user requested no commits)
+
+```
+src/sourcecode/cli.py               # P3-B removed (DDD auto-centrality switch)
+src/sourcecode/contract_pipeline.py # G3: _is_priority() + T11: centrality sort key
+src/sourcecode/detectors/java.py    # N1: _augment_deep_java_controllers() method
+src/sourcecode/serializer.py        # N2: result["hotspots"] top-level restored
+```
+
+### Test Status
+- 651 passed, 3 skipped (subset excluding pre-existing failures) — zero regressions
+
+---
+
+## What Remains
+
+### Not Fixed (deferred)
+
+| ID | Description |
+|----|-------------|
+| M1 | `prepare-context` from monorepo root detects Angular instead of saint-server Java. Requires monorepo subproject routing in `prepare_context.py` → `TaskContextBuilder` / `RepoClassifier`. |
+| M2 | `@M3FiltroSeguridad` custom security annotation not aggregated into security map |
+| M3 | Spring profiles detected but not linked to `application-{profile}.yml` files |
+
+### Verification Commands (run against saint-server after commit)
+
+```bash
+# N1: DDD controllers now captured (need --depth 12+ for tree, augment works at any depth)
+sourcecode saint-server --depth 12 --entrypoints-only --format json | python -c "
+import sys, json
+d = json.load(sys.stdin)
+rest = [x for x in d.get('contracts', []) if 'RestController' in x.get('path','')]
+ddd  = [x for x in rest if '/ddd/' in x['path'] or '/infraestructure/' in x['path']]
+print(f'REST total: {len(rest)} | DDD: {len(ddd)}')"
+
+# G3: MyBatis XML in contracts
+sourcecode saint-server --depth 10 --format json | python -c "
+import sys, json
+d = json.load(sys.stdin)
+xml = [x for x in d.get('contracts', []) if x.get('language') == 'mybatis-xml']
+print(f'MyBatis contracts: {len(xml)}')"
+
+# N2: hotspots at top level restored
+sourcecode saint-server --semantics --format json | python -c "
+import sys, json
+d = json.load(sys.stdin)
+print('top-level hotspots:', len(d.get('hotspots', [])))
+print('semantic_summary.hotspots:', len(d.get('semantic_summary',{}).get('hotspots',[])))"
+
+# T11: centrality now surfaces REST controllers
+sourcecode saint-server --rank-by centrality --depth 10 --format json | python -c "
+import sys, json
+d = json.load(sys.stdin)
+rest = [x for x in d.get('contracts', []) if 'RestController' in x.get('path','')]
+print(f'REST in centrality: {len(rest)}')"
+```
+
+**Note on N1 depth:** `_augment_deep_java_controllers` bypasses the scanner depth limit and always walks `src/main/java/` directly. DDD controllers will be detected as entry_points regardless of `--depth`. However, for these same files to appear in the general file_paths (not just entry_points), the scanner itself needs `--depth >= 11`.
+
+---
+
+## Previous Session Fixes (already committed)
+
+C1/C2/C3/G1/G2/G3 from v1.4.0→v1.5.0:
+- `--mode standard` key `file_contracts` → `contracts`
+- Controller-first scan, cap 500→1000
+- DDD bounded contexts from package structure
+- Maven BOM limitation warning
+- MyBatis XML extractor (code existed but files were cut by cap — fixed in this session)
+
+---
+
+## GSD Project State (unchanged)
+
+All 13 phases complete (see `.planning/STATE.md`). Both sessions were ad-hoc bug work from benchmark reports, not planned phase executions.
+
+---
+
+## Resume Instructions
+
+1. `git diff --stat` — verify 4 uncommitted files
+2. `python -m pytest tests/ --ignore=tests/test_block2_coverage.py --ignore=tests/test_dependency_analyzer_node_python.py --ignore=tests/test_pipeline_integrity.py -q`
+3. Commit the fixes
+4. Run verification commands above against saint-server
+5. If tackling M1, entry point is `prepare_context.py:TaskContextBuilder.build()` + `repo_classifier.py`

{sourcecode-1.5.0 → sourcecode-1.7.0}/PKG-INFO

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

{sourcecode-1.5.0 → sourcecode-1.7.0}/pyproject.toml

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

{sourcecode-1.5.0 → sourcecode-1.7.0}/src/sourcecode/__init__.py

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

{sourcecode-1.5.0 → sourcecode-1.7.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.5.0 → sourcecode-1.7.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,
@@ -382,28 +384,28 @@ def main(
     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,10 +416,8 @@ 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,
@@ -448,41 +448,33 @@ def main(
     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,
@@ -788,7 +780,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)
@@ -1399,11 +1391,30 @@ def main(
                         ))
         sm = _replace(sm, pipeline_trace=_trace.build_trace())
 
-    # P3-B: Auto-switch to centrality ranking when DDD layout detected
-    if (rank_by == "relevance"
-            and sm.architecture is not None
-            and sm.architecture.pattern == "ddd"):
-        rank_by = "centrality"
+    # 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)
     _is_contract_mode = mode in ("contract", "standard")
@@ -1438,6 +1449,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:
@@ -1712,8 +1724,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.5.0 → sourcecode-1.7.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
@@ -240,10 +246,18 @@ class ContractPipeline:
 
         # Apply max_files cap — bypass when symbol search to ensure defining files are found.
         # A symbol query over a large repo needs all files; result set is small after filtering.
+        # MyBatis Mapper.xml contracts rank below Java files on path score alone (.xml has no
+        # suffix boost). Give them the same priority slot as entry_points so they survive the cap.
+        def _is_priority(p: str) -> bool:
+            if p in entry_paths:
+                return True
+            name = p.rsplit("/", 1)[-1]
+            return name.lower().endswith("mapper.xml")
+
         if symbol is None and len(src_paths) > self.max_files:
             src_paths = sorted(
                 src_paths,
-                key=lambda p: (p in entry_paths, scorer.score(p)),
+                key=lambda p: (_is_priority(p), scorer.score(p)),
                 reverse=True,
             )[:self.max_files]
 
@@ -362,7 +376,9 @@ class ContractPipeline:
 
     def _rank(self, contracts: list[FileContract], rank_by: RankStrategy) -> list[FileContract]:
         if rank_by == "centrality":
-            return sorted(contracts, key=lambda c: (-(c.fan_in + c.fan_out), c.path))
+            # Entrypoints (REST controllers, main classes) surface first even in centrality mode:
+            # they have low fan_in (not imported) but are the primary API surface.
+            return sorted(contracts, key=lambda c: (-c.is_entrypoint, -(c.fan_in + c.fan_out), c.path))
         if rank_by == "git-churn":
             return sorted(contracts, key=lambda c: (-c.is_changed, -c.relevance_score, c.path))
         # Default: relevance — path breaks ties deterministically

{sourcecode-1.5.0 → sourcecode-1.7.0}/src/sourcecode/detectors/java.py

@@ -225,6 +225,12 @@ class JavaDetector(AbstractDetector):
         all_paths = flatten_file_tree(context.file_tree)
         all_java = [p for p in all_paths if p.endswith(".java")]
 
+        # Augment with a direct scan of standard Java source roots for Controller-named
+        # files that the depth-limited file_tree scanner may have missed.
+        # DDD layouts place REST controllers at depth 10+ (e.g.
+        # src/main/java/com/org/app/ddd/domain/infraestructure/rest/XxxRestController.java).
+        self._augment_deep_java_controllers(context, all_java)
+
         # 1. @SpringBootApplication entry: Application.java / Main.java by name
         app_candidates = [
             p for p in all_java
@@ -270,6 +276,40 @@ class JavaDetector(AbstractDetector):
                 unique_eps.append(ep)
         return unique_eps
 
+    def _augment_deep_java_controllers(self, context: DetectionContext, all_java: list[str]) -> None:
+        """Scan standard Java source roots for *Controller*.java files not in all_java.
+
+        The depth-limited file_tree scanner misses files at depth >= max_depth.
+        DDD layouts place REST controllers deep (e.g. depth 10+), so we supplement
+        with a direct filesystem walk scoped to the standard Maven/Gradle source root.
+        """
+        import os as _os
+        existing = set(all_java)
+        # Standard Java source root candidates (Maven first, then Gradle/other)
+        _SRC_ROOTS = ("src/main/java", "src/main/kotlin", "src/java", "src")
+        for src_root_name in _SRC_ROOTS:
+            src_root = context.root / src_root_name
+            if not src_root.is_dir():
+                continue
+            try:
+                for dirpath, _dirs, filenames in _os.walk(str(src_root)):
+                    for fname in filenames:
+                        if "Controller" not in fname or not fname.endswith(".java"):
+                            continue
+                        full = Path(dirpath) / fname
+                        if full.is_symlink():
+                            continue
+                        try:
+                            rel = str(full.relative_to(context.root)).replace("\\", "/")
+                            if rel not in existing:
+                                all_java.append(rel)
+                                existing.add(rel)
+                        except ValueError:
+                            pass
+            except OSError:
+                pass
+            return  # use only first matching source root
+
     def _scan_java_file_for_entry_points(self, abs_path: Path, rel_path: str) -> list[EntryPoint]:
         try:
             if abs_path.stat().st_size > _MAX_FILE_SIZE:

{sourcecode-1.5.0 → sourcecode-1.7.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,