sourcecode 1.23.0__tar.gz → 1.26.0__tar.gz

{sourcecode-1.23.0 → sourcecode-1.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.23.0
+Version: 1.26.0
 Summary: Deterministic codebase context for AI coding agents
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -221,7 +221,7 @@ Description-Content-Type: text/markdown
 
 **Compressed AI-ready context for Java/Spring enterprise codebases.**
 
-![Version](https://img.shields.io/badge/version-1.23.0-blue)
+![Version](https://img.shields.io/badge/version-1.26.0-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -255,7 +255,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.23.0
+# sourcecode 1.26.0
 ```
 
 ---
@@ -263,7 +263,7 @@ sourcecode version
 ## Quickstart
 
 ```bash
-# High-signal summary (~600-800 tokens) — recommended starting point
+# High-signal summary (1000–3000 tokens depending on repo size) — recommended starting point
 sourcecode --compact
 
 # Add git hotspots and uncommitted file count
@@ -311,8 +311,9 @@ Example output for a Spring Boot project (`--compact`):
 
 | Flag | Alias | Default | Description |
 |------|-------|---------|-------------|
-| `--compact` | | off | **Recommended.** ~600-800 token summary: stack, entry points, dependencies, risk flags, confidence, gaps. Optimized for agent context windows. |
+| `--compact` | | off | High-signal summary (1000–3000 tokens): stacks, entry points, dependencies, risk flags, confidence, gaps. Includes `security_surface`, `mybatis`, and `transactional_boundaries` for Java projects. |
 | `--agent` | | off | Structured noise-free JSON for AI agents: identity, entry points, dependencies, confidence, gaps. Auto-enables dependency, env-var, and code-notes analysis. |
+| `--full` | | off | Remove truncation limits on `transactional_boundaries`, `mybatis.dto_mappers`, and other capped lists. |
 | `--git-context` | `-g` | off | Include git activity: recent commits, change hotspots, and uncommitted changes. |
 | `--changed-only` | | off | Limit output to git-modified files (staged, unstaged, untracked). Forces compact output. |
 | `--depth` | | `4` | File tree traversal depth (1–20). Java/Maven projects auto-adjust to 12. |
@@ -342,16 +343,18 @@ sourcecode prepare-context TASK [PATH] [OPTIONS]
 | `refactor` | Structural problems, improvement opportunities, high-annotation files | Code quality review |
 | `generate-tests` | Source files without test pairs, coverage gap analysis | Writing missing tests |
 | `review-pr` | Uncommitted/changed files + architectural impact | Pre-merge review |
-| `delta` | Only files changed in a git range (`--since`), affected entry points | Incremental CI context |
+| `delta` | Changed files with multi-hop impact analysis, structural import graph, system-level impact summary | Incremental CI/review context |
 
 ### Options
 
 | Option | Description |
 |--------|-------------|
 | `--since REF` | Git ref for `delta` task (e.g. `HEAD~3`, `main`, `v1.2.0`). Required for `delta`; ignored for other tasks. |
+| `--symptom TEXT` | *(fix-bug only)* Keyword hint for the bug — boosts matching files and surfaces related code notes. |
 | `--llm-prompt` | Append a ready-to-use LLM prompt to the output. |
 | `--dry-run` | Show what would be analyzed without running it. |
 | `--copy` / `-c` | Copy output to clipboard after a successful run. |
+| `--output` / `-o` | Write output to a file. |
 | `--task-help` | List all tasks with descriptions and exit. |
 
 ### Examples
@@ -360,11 +363,8 @@ sourcecode prepare-context TASK [PATH] [OPTIONS]
 # Explain the current repo
 sourcecode prepare-context explain
 
-# Analyze a specific repo path
-sourcecode prepare-context explain /path/to/repo
-
-# Focus on bug-prone files
-sourcecode prepare-context fix-bug
+# Focus on bug-prone files, with a symptom hint
+sourcecode prepare-context fix-bug --symptom "NullPointerException in OrderService"
 
 # Incremental context: files changed since branch diverged from main
 sourcecode prepare-context delta . --since main
@@ -378,6 +378,51 @@ sourcecode prepare-context --task-help
 
 ---
 
+## `delta` — incremental impact analysis
+
+The `delta` task is the recommended mode for CI pipelines and PR reviews. It goes beyond listing changed files: it builds a structural import graph and propagates impact transitively up to 3 hops.
+
+```bash
+sourcecode prepare-context delta [PATH] --since REF
+```
+
+**Output fields:**
+
+| Field | Description |
+|-------|-------------|
+| `changed_files` | Files modified in the git range |
+| `relevant_files` | Changed files + files pulled in by the import graph (scored by artifact type and hop distance) |
+| `impact_summary` | Human-readable summary: artifact types changed and active risk areas |
+| `affected_modules` | DDD domain modules touched by the change |
+| `risk_areas` | Per-area severity breakdown (`security`, `api`, `persistence`, etc.) |
+| `change_type` | Closed taxonomy: `behavioral_change`, `structural_change`, `configuration_change`, `dependency_change`, `security_change` |
+| `system_impact` | Subsystems affected, behavioral changes, runtime impact notes |
+| `dependency_graph_summary` | Verified structural import edges (hop 1–3) and `propagation_depth`. **Only real imports — no heuristics, no test files.** |
+| `impact_score_per_file` | Per-file numeric impact score (0–1) |
+| `since` | The git ref used |
+| `gaps` | What the analysis could not determine |
+
+**How the import graph works:**
+
+1. Each changed file is classified by artifact type (`controller`, `service`, `repository`, `security`, `spring_config`, etc.).
+2. A BFS traversal walks the import graph **repo-wide** (not restricted to the same module), up to 3 hops deep.
+3. `dependency_graph_summary.edges` only contains verified `import` / `@Autowired` / constructor-injection relationships. Test files and heuristic proximity matches are excluded from edges (they appear in `relevant_files` only if they have real imports of changed files).
+4. Score decays 30% per hop: a directly-changed `SecurityConfig.java` scores 0.90; its direct importer scores 0.63; a transitive importer scores 0.44.
+
+```bash
+# Changed service → controller → facade (3 hops)
+sourcecode prepare-context delta . --since main
+
+# Output includes:
+# dependency_graph_summary.edges:
+#   hop-1: OrderService.java → OrderRepository.java
+#   hop-2: OrderRepository.java → OrderController.java
+#   hop-3: OrderController.java → OrderFacade.java
+# propagation_depth: 3
+```
+
+---
+
 ## Output schema
 
 All outputs include a `confidence_summary` block with `overall`, `stack`, and `entry_points` confidence levels (`high` / `medium` / `low`), plus an `analysis_gaps` list describing what could not be analyzed and why.

{sourcecode-1.23.0 → sourcecode-1.26.0}/README.md

@@ -2,7 +2,7 @@
 
 **Compressed AI-ready context for Java/Spring enterprise codebases.**
 
-![Version](https://img.shields.io/badge/version-1.23.0-blue)
+![Version](https://img.shields.io/badge/version-1.26.0-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -36,7 +36,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.23.0
+# sourcecode 1.26.0
 ```
 
 ---
@@ -44,7 +44,7 @@ sourcecode version
 ## Quickstart
 
 ```bash
-# High-signal summary (~600-800 tokens) — recommended starting point
+# High-signal summary (1000–3000 tokens depending on repo size) — recommended starting point
 sourcecode --compact
 
 # Add git hotspots and uncommitted file count
@@ -92,8 +92,9 @@ Example output for a Spring Boot project (`--compact`):
 
 | Flag | Alias | Default | Description |
 |------|-------|---------|-------------|
-| `--compact` | | off | **Recommended.** ~600-800 token summary: stack, entry points, dependencies, risk flags, confidence, gaps. Optimized for agent context windows. |
+| `--compact` | | off | High-signal summary (1000–3000 tokens): stacks, entry points, dependencies, risk flags, confidence, gaps. Includes `security_surface`, `mybatis`, and `transactional_boundaries` for Java projects. |
 | `--agent` | | off | Structured noise-free JSON for AI agents: identity, entry points, dependencies, confidence, gaps. Auto-enables dependency, env-var, and code-notes analysis. |
+| `--full` | | off | Remove truncation limits on `transactional_boundaries`, `mybatis.dto_mappers`, and other capped lists. |
 | `--git-context` | `-g` | off | Include git activity: recent commits, change hotspots, and uncommitted changes. |
 | `--changed-only` | | off | Limit output to git-modified files (staged, unstaged, untracked). Forces compact output. |
 | `--depth` | | `4` | File tree traversal depth (1–20). Java/Maven projects auto-adjust to 12. |
@@ -123,16 +124,18 @@ sourcecode prepare-context TASK [PATH] [OPTIONS]
 | `refactor` | Structural problems, improvement opportunities, high-annotation files | Code quality review |
 | `generate-tests` | Source files without test pairs, coverage gap analysis | Writing missing tests |
 | `review-pr` | Uncommitted/changed files + architectural impact | Pre-merge review |
-| `delta` | Only files changed in a git range (`--since`), affected entry points | Incremental CI context |
+| `delta` | Changed files with multi-hop impact analysis, structural import graph, system-level impact summary | Incremental CI/review context |
 
 ### Options
 
 | Option | Description |
 |--------|-------------|
 | `--since REF` | Git ref for `delta` task (e.g. `HEAD~3`, `main`, `v1.2.0`). Required for `delta`; ignored for other tasks. |
+| `--symptom TEXT` | *(fix-bug only)* Keyword hint for the bug — boosts matching files and surfaces related code notes. |
 | `--llm-prompt` | Append a ready-to-use LLM prompt to the output. |
 | `--dry-run` | Show what would be analyzed without running it. |
 | `--copy` / `-c` | Copy output to clipboard after a successful run. |
+| `--output` / `-o` | Write output to a file. |
 | `--task-help` | List all tasks with descriptions and exit. |
 
 ### Examples
@@ -141,11 +144,8 @@ sourcecode prepare-context TASK [PATH] [OPTIONS]
 # Explain the current repo
 sourcecode prepare-context explain
 
-# Analyze a specific repo path
-sourcecode prepare-context explain /path/to/repo
-
-# Focus on bug-prone files
-sourcecode prepare-context fix-bug
+# Focus on bug-prone files, with a symptom hint
+sourcecode prepare-context fix-bug --symptom "NullPointerException in OrderService"
 
 # Incremental context: files changed since branch diverged from main
 sourcecode prepare-context delta . --since main
@@ -159,6 +159,51 @@ sourcecode prepare-context --task-help
 
 ---
 
+## `delta` — incremental impact analysis
+
+The `delta` task is the recommended mode for CI pipelines and PR reviews. It goes beyond listing changed files: it builds a structural import graph and propagates impact transitively up to 3 hops.
+
+```bash
+sourcecode prepare-context delta [PATH] --since REF
+```
+
+**Output fields:**
+
+| Field | Description |
+|-------|-------------|
+| `changed_files` | Files modified in the git range |
+| `relevant_files` | Changed files + files pulled in by the import graph (scored by artifact type and hop distance) |
+| `impact_summary` | Human-readable summary: artifact types changed and active risk areas |
+| `affected_modules` | DDD domain modules touched by the change |
+| `risk_areas` | Per-area severity breakdown (`security`, `api`, `persistence`, etc.) |
+| `change_type` | Closed taxonomy: `behavioral_change`, `structural_change`, `configuration_change`, `dependency_change`, `security_change` |
+| `system_impact` | Subsystems affected, behavioral changes, runtime impact notes |
+| `dependency_graph_summary` | Verified structural import edges (hop 1–3) and `propagation_depth`. **Only real imports — no heuristics, no test files.** |
+| `impact_score_per_file` | Per-file numeric impact score (0–1) |
+| `since` | The git ref used |
+| `gaps` | What the analysis could not determine |
+
+**How the import graph works:**
+
+1. Each changed file is classified by artifact type (`controller`, `service`, `repository`, `security`, `spring_config`, etc.).
+2. A BFS traversal walks the import graph **repo-wide** (not restricted to the same module), up to 3 hops deep.
+3. `dependency_graph_summary.edges` only contains verified `import` / `@Autowired` / constructor-injection relationships. Test files and heuristic proximity matches are excluded from edges (they appear in `relevant_files` only if they have real imports of changed files).
+4. Score decays 30% per hop: a directly-changed `SecurityConfig.java` scores 0.90; its direct importer scores 0.63; a transitive importer scores 0.44.
+
+```bash
+# Changed service → controller → facade (3 hops)
+sourcecode prepare-context delta . --since main
+
+# Output includes:
+# dependency_graph_summary.edges:
+#   hop-1: OrderService.java → OrderRepository.java
+#   hop-2: OrderRepository.java → OrderController.java
+#   hop-3: OrderController.java → OrderFacade.java
+# propagation_depth: 3
+```
+
+---
+
 ## Output schema
 
 All outputs include a `confidence_summary` block with `overall`, `stack`, and `entry_points` confidence levels (`high` / `medium` / `low`), plus an `analysis_gaps` list describing what could not be analyzed and why.

{sourcecode-1.23.0 → sourcecode-1.26.0}/pyproject.toml

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

{sourcecode-1.23.0 → sourcecode-1.26.0}/src/sourcecode/__init__.py

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

{sourcecode-1.23.0 → sourcecode-1.26.0}/src/sourcecode/cli.py

@@ -1773,6 +1773,25 @@ def prepare_context_cmd(
         out["affected_entry_points"] = output.affected_entry_points
     # Delta-specific impact fields
     if task == "delta":
+        if output.error_code:
+            # Hard error — emit structured error JSON and exit, skip normal delta fields
+            _err_out: dict[str, Any] = {
+                "task": output.task,
+                "error": output.error_code,
+                "since": output.since,
+                "message": output.error_message,
+            }
+            if output.error_hints:
+                _err_out["hint"] = output.error_hints
+            _err_json = json.dumps(_err_out, indent=2, ensure_ascii=False)
+            if output_path is not None:
+                output_path.write_text(_err_json, encoding="utf-8")
+            else:
+                import sys as _sys
+                _sys.stdout.buffer.write(_err_json.encode("utf-8"))
+                _sys.stdout.buffer.write(b"\n")
+                _sys.stdout.buffer.flush()
+            raise typer.Exit(code=1)
         if output.since:
             out["since"] = output.since
         if output.impact_summary:

{sourcecode-1.23.0 → sourcecode-1.26.0}/src/sourcecode/prepare_context.py

@@ -333,6 +333,10 @@ class TaskOutput:
     change_type: list[str] = field(default_factory=list)
     dependency_graph_summary: dict = field(default_factory=dict)
     impact_score_per_file: dict = field(default_factory=dict)
+    # error state (git ref not found, etc.)
+    error_code: Optional[str] = None
+    error_message: Optional[str] = None
+    error_hints: list[str] = field(default_factory=list)
 
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -618,7 +622,34 @@ class TaskContextBuilder:
         _delta_files: Optional[set[str]] = None
         if task_name == "delta":
             _delta_raw = self._get_git_changed_files(since=since)
-            if _delta_raw:
+            if _delta_raw is None:
+                # Explicit --since ref couldn't be resolved — hard error, no fallback
+                _avail_branches, _suggested = self._get_available_refs(since or "")
+                _hints: list[str] = []
+                if _suggested:
+                    _hints.append(f"Did you mean '{_suggested}'?")
+                if _avail_branches:
+                    _hints.append(f"Available refs: {', '.join(_avail_branches[:8])}")
+                return TaskOutput(
+                    task="delta",
+                    goal="Produce incremental context for changed files — avoids re-reading the full repo.",
+                    project_summary=None,
+                    architecture_summary=None,
+                    relevant_files=[],
+                    suspected_areas=[],
+                    improvement_opportunities=[],
+                    test_gaps=[],
+                    key_dependencies=[],
+                    code_notes_summary=None,
+                    limitations=[],
+                    confidence="low",
+                    since=since,
+                    error_code="git_ref_not_found",
+                    error_message=f"Git reference '{since}' does not exist in this repository.",
+                    error_hints=_hints,
+                    gaps=[f"Cannot compute delta: git ref '{since}' not found."] + _hints,
+                )
+            elif _delta_raw:
                 _delta_files = set(_delta_raw)
 
         # ── 5c. review-pr suspected_areas (needs git uncommitted_files) ──────
@@ -1777,118 +1808,108 @@ class TaskContextBuilder:
                 path=path, role=role, score=rel_score, reason=reason, why=why_str
             )))
             why[path] = why_str
-            for trigger_name in triggers[:3]:
-                trigger_full = next((f for f in changed_files if Path(f).name == trigger_name), None)
-                if trigger_full:
-                    graph_edges.append({"from": trigger_full, "to": path, "edge_type": "module_proximity", "hop": 1})
+            # module_proximity is heuristic (not a verified import) — excluded from structural graph
 
         related.sort(key=lambda x: (-x[0], x[1]))
         relevant.extend(rf for _, _, rf in related[:10])
 
-        # ── Step 3b: import-link expansion (bounded file scan) ────────────────
-        # Find files in the same module that import/reference a changed file.
-        # More precise than directory proximity: based on actual import statements.
-        _import_candidates = [
+        # ── Steps 3b–3c: BFS multi-hop import propagation (repo-wide, 3 hops max) ─
+        # Each hop expands from whatever was found in the previous hop into ALL
+        # remaining source files — not restricted to original module/dir.
+        # This enables A→B→C discovery even when B and C are in different modules.
+        _BFS_SCANNABLE = frozenset({".py", ".java", ".kt", ".ts", ".js", ".tsx", ".jsx", ".mjs"})
+        _bfs_all_sources = [
             p for p in all_paths
-            if p not in existing_paths and Path(p).suffix.lower() in {
-                ".py", ".java", ".kt", ".ts", ".js", ".tsx", ".jsx", ".mjs"
-            }
-            and (
-                _extract_ddd_domain(p) in affected_modules_set
-                or str(Path(p).parent).replace("\\", "/") in changed_dirs
-            )
+            if Path(p).suffix.lower() in _BFS_SCANNABLE
+        ]
+
+        _bfs_seen: set[str] = {rf.path for rf in relevant}
+        _bfs_frontier: list[str] = [
+            f for f in changed_files
+            if Path(f).suffix.lower() in _BFS_SCANNABLE
         ]
-        if _import_candidates:
-            _import_dep_map = self._scan_import_dependents(
-                changed_paths=changed_files,
-                candidate_paths=_import_candidates,
+
+        # (max results added from this hop, max_candidates scanned per seed)
+        _BFS_HOP_BUDGET = [
+            (8, 60),   # hop 1 — broad: callers of changed files
+            (6, 50),   # hop 2 — transitives: callers of hop-1 files
+            (4, 30),   # hop 3 — deep transitives: callers of hop-2 files
+        ]
+
+        # (hop_num, score, path, RelevantFile) — merged across all hops then added to relevant
+        _bfs_collected: list[tuple[int, float, str, RelevantFile]] = []
+
+        for _hop_num, (_max_results, _max_cands) in enumerate(_BFS_HOP_BUDGET, start=1):
+            if not _bfs_frontier:
+                break
+
+            _bfs_candidates = [p for p in _bfs_all_sources if p not in _bfs_seen]
+            if not _bfs_candidates:
+                break
+
+            _hop_dep_map = self._scan_import_dependents(
+                changed_paths=_bfs_frontier,
+                candidate_paths=_bfs_candidates,
+                max_candidates=_max_cands,
             )
-            _import_seen = {rf.path for rf in relevant}
-            _import_extra: list[tuple[float, str, RelevantFile]] = []
-            for changed_path, dep_paths in _import_dep_map.items():
-                changed_atype = classifications[changed_path]["artifact_type"]
-                for dep_path in dep_paths:
-                    if dep_path in _import_seen:
+
+            # collect (score, path) pairs for this hop to build the next frontier
+            _hop_scored: list[tuple[float, str]] = []
+
+            for _seed_path, _dep_paths in _hop_dep_map.items():
+                _seed_atype = (
+                    classifications[_seed_path]["artifact_type"]
+                    if _seed_path in classifications
+                    else self._classify_changed_file(_seed_path)["artifact_type"]
+                )
+                for _dep_path in _dep_paths:
+                    if _dep_path in _bfs_seen:
                         continue
-                    dep_cls = self._classify_changed_file(dep_path)
-                    if dep_cls["is_noise"]:
+                    _bfs_seen.add(_dep_path)
+
+                    _dep_cls = self._classify_changed_file(_dep_path)
+                    if _dep_cls["is_noise"]:
                         continue
-                    dep_atype = dep_cls["artifact_type"]
-                    dep_base = _ARTIFACT_SCORE.get(dep_atype, 0.45)
-                    dep_score = round(dep_base * 0.70, 2)
-                    dep_role = _role_in_system(dep_path, dep_atype, dep_path in ep_paths)
-                    why_str = (
-                        f"artifact_type: {dep_atype} | role_in_system: {dep_role}"
-                        f" | impact_area: {_classify_impact_area(dep_path, dep_cls['risk_areas'], dep_atype)}"
-                        f" | propagation_risk: {_PROPAGATION_RISK.get(dep_atype, 'low')}"
-                        f" | change_effect: {_CHANGE_EFFECT.get(dep_atype, 'modifies application logic')}"
-                        f" | pulled_by: import-link from {Path(changed_path).name}"
+
+                    _dep_atype = _dep_cls["artifact_type"]
+                    _dep_score_base = _ARTIFACT_SCORE.get(_dep_atype, 0.45)
+                    # score decays 30% per hop so transitives rank below direct dependents
+                    _dep_score = round(_dep_score_base * (0.70 ** _hop_num), 2)
+                    _dep_role = _role_in_system(_dep_path, _dep_atype, _dep_path in ep_paths)
+
+                    _why_str = (
+                        f"artifact_type: {_dep_atype} | role_in_system: {_dep_role}"
+                        f" | impact_area: {_classify_impact_area(_dep_path, _dep_cls['risk_areas'], _dep_atype)}"
+                        f" | propagation_risk: {_PROPAGATION_RISK.get(_dep_atype, 'low')}"
+                        f" | change_effect: {_CHANGE_EFFECT.get(_dep_atype, 'modifies application logic')}"
+                        f" | pulled_by: hop-{_hop_num} import from {Path(_seed_path).name}"
                     )
-                    reason = f"import-dependent of {Path(changed_path).name} ({changed_atype}) | score: {dep_score:.2f}"
-                    _import_extra.append((dep_score, dep_path, RelevantFile(
-                        path=dep_path, role=dep_role, score=dep_score,
-                        reason=reason, why=why_str,
+                    _reason = (
+                        f"hop-{_hop_num} import-dependent of {Path(_seed_path).name}"
+                        f" ({_seed_atype}) | score: {_dep_score:.2f}"
+                    )
+                    why[_dep_path] = _why_str
+                    # Tests are consumers, not structural dependencies — exclude from import graph.
+                    # They remain in relevant_files but must not seed further BFS hops.
+                    _is_test = _dep_atype == "test"
+                    if not _is_test:
+                        graph_edges.append({
+                            "from": _seed_path, "to": _dep_path,
+                            "edge_type": "import_dependency", "hop": _hop_num,
+                        })
+                        _hop_scored.append((_dep_score, _dep_path))
+                    _bfs_collected.append((_hop_num, _dep_score, _dep_path, RelevantFile(
+                        path=_dep_path, role=_dep_role, score=_dep_score,
+                        reason=_reason, why=_why_str,
                     )))
-                    why[dep_path] = why_str
-                    _import_seen.add(dep_path)
-                    graph_edges.append({"from": changed_path, "to": dep_path, "edge_type": "import_dependency", "hop": 1})
-            _import_extra.sort(key=lambda x: (-x[0], x[1]))
-            relevant.extend(rf for _, _, rf in _import_extra[:8])
-
-        # ── Step 3c: hop-2 import propagation (callers of hop-1 dependents) ────
-        _hop1_seeds = list(dict.fromkeys(
-            dep_path
-            for dep_paths in (_import_dep_map.values() if _import_candidates else [])
-            for dep_path in dep_paths
-        ))
-        if _hop1_seeds:
-            _hop2_seen = {rf.path for rf in relevant}
-            _hop2_candidates = [
-                p for p in all_paths
-                if p not in _hop2_seen
-                and Path(p).suffix.lower() in {".py", ".java", ".kt", ".ts", ".js", ".tsx", ".jsx", ".mjs"}
-                and (
-                    _extract_ddd_domain(p) in affected_modules_set
-                    or str(Path(p).parent).replace("\\", "/") in changed_dirs
-                )
-            ]
-            if _hop2_candidates:
-                _hop2_dep_map = self._scan_import_dependents(
-                    changed_paths=_hop1_seeds,
-                    candidate_paths=_hop2_candidates,
-                    max_candidates=20,
-                )
-                _hop2_extra: list[tuple[float, str, RelevantFile]] = []
-                for hop1_path, dep_paths in _hop2_dep_map.items():
-                    hop1_cls = self._classify_changed_file(hop1_path)
-                    hop1_atype = hop1_cls["artifact_type"]
-                    for dep_path in dep_paths:
-                        if dep_path in _hop2_seen:
-                            continue
-                        dep_cls = self._classify_changed_file(dep_path)
-                        if dep_cls["is_noise"]:
-                            continue
-                        dep_atype = dep_cls["artifact_type"]
-                        dep_base = _ARTIFACT_SCORE.get(dep_atype, 0.45)
-                        dep_score = round(dep_base * 0.50, 2)
-                        dep_role = _role_in_system(dep_path, dep_atype, dep_path in ep_paths)
-                        why_str = (
-                            f"artifact_type: {dep_atype} | role_in_system: {dep_role}"
-                            f" | impact_area: {_classify_impact_area(dep_path, dep_cls['risk_areas'], dep_atype)}"
-                            f" | propagation_risk: {_PROPAGATION_RISK.get(dep_atype, 'low')}"
-                            f" | change_effect: {_CHANGE_EFFECT.get(dep_atype, 'modifies application logic')}"
-                            f" | pulled_by: hop-2 import from {Path(hop1_path).name}"
-                        )
-                        reason = f"hop-2 import-dependent of {Path(hop1_path).name} ({hop1_atype}) | score: {dep_score:.2f}"
-                        _hop2_extra.append((dep_score, dep_path, RelevantFile(
-                            path=dep_path, role=dep_role, score=dep_score,
-                            reason=reason, why=why_str,
-                        )))
-                        why[dep_path] = why_str
-                        _hop2_seen.add(dep_path)
-                        graph_edges.append({"from": hop1_path, "to": dep_path, "edge_type": "import_dependency", "hop": 2})
-                _hop2_extra.sort(key=lambda x: (-x[0], x[1]))
-                relevant.extend(rf for _, _, rf in _hop2_extra[:5])
+
+            # next frontier = top-N files by score from this hop
+            _hop_scored.sort(key=lambda x: -x[0])
+            _bfs_frontier = [p for _, p in _hop_scored[:_max_results]]
+
+        # merge into relevant: closer hops first, then higher score; cap total at 20
+        _bfs_collected.sort(key=lambda x: (x[0], -x[1], x[2]))
+        relevant.extend(rf for _, _, _, rf in _bfs_collected[:20])
 
         # ── Step 3d: per-file impact scores, change_type, system_impact ─────────
         # Downstream fanout: count graph edges originating from each changed file
@@ -2054,9 +2075,13 @@ class TaskContextBuilder:
         }
 
         # ── Step 6: analysis gaps ──────────────────────────────────────────────
-        _hop_desc = f"+ hop-2 import propagation (propagation_depth={_max_hop})" if _max_hop >= 2 else ""
+        _bfs_note = (
+            f"BFS multi-hop import propagation repo-wide (propagation_depth={_max_hop})"
+            if _max_hop >= 1
+            else "no import-link propagation (no scannable changed files)"
+        )
         analysis_gaps: list[str] = [
-            f"Related file expansion uses type-aware propagation chains + bounded import-link scanning {_hop_desc}+ module/directory heuristics".replace("  ", " ").strip(),
+            f"Related file expansion: type-aware chain expansion + {_bfs_note} + module/directory heuristics",
         ]
         if noise_count > 0 and meaningful > 0:
             analysis_gaps.append(
@@ -2093,9 +2118,13 @@ class TaskContextBuilder:
             impact_score_per_file,
         )
 
-    def _get_git_changed_files(self, since: Optional[str] = None) -> list[str]:
+    def _get_git_changed_files(self, since: Optional[str] = None) -> Optional[list[str]]:
         """Get files changed since a git ref (default: HEAD~1) relative to self.root.
 
+        Returns None when `since` is explicitly provided but cannot be resolved —
+        this is an error state, not "no changes". Callers must distinguish None
+        (ref invalid) from [] (ref valid, no changes).
+
         Uses --relative so paths are relative to cwd (self.root), not the git repo
         root. This is critical for monorepos where self.root is a subpath of the
         git root and git diff would otherwise return prefixed paths that don't match
@@ -2118,9 +2147,13 @@ class TaskContextBuilder:
                     line.strip() for line in (result.stdout or "").splitlines()
                     if line.strip()
                 ]
+            # Non-zero exit with explicit ref = ref doesn't exist — no silent fallback
+            if since:
+                return None
         except (subprocess.TimeoutExpired, FileNotFoundError):
-            pass
-        # Fallback: uncommitted changes
+            if since:
+                return None
+        # No explicit since: fall back to uncommitted changes
         try:
             result = subprocess.run(
                 ["git", "diff", "--name-only", "--relative"],
@@ -2136,3 +2169,26 @@ class TaskContextBuilder:
         except (subprocess.TimeoutExpired, FileNotFoundError):
             pass
         return []
+
+    def _get_available_refs(self, invalid_ref: str) -> tuple[list[str], Optional[str]]:
+        """Return (available_branch_names, suggested_alternative) for error hints."""
+        import subprocess
+        branches: list[str] = []
+        suggested: Optional[str] = None
+        try:
+            r = subprocess.run(
+                ["git", "branch", "-a", "--format=%(refname:short)"],
+                cwd=str(self.root),
+                capture_output=True, text=True, timeout=5,
+            )
+            if r.returncode == 0:
+                all_refs = [b.strip() for b in r.stdout.splitlines() if b.strip()]
+                branches = [b for b in all_refs if "HEAD" not in b][:10]
+                ref_lower = invalid_ref.lower()
+                if ref_lower == "master" and any(b.rstrip("/").endswith("main") for b in all_refs):
+                    suggested = "main"
+                elif ref_lower == "main" and any(b.rstrip("/").endswith("master") for b in all_refs):
+                    suggested = "master"
+        except (subprocess.TimeoutExpired, FileNotFoundError):
+            pass
+        return branches, suggested