sourcecode 1.30.25__tar.gz → 1.30.27__tar.gz

{sourcecode-1.30.25 → sourcecode-1.30.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.30.25
+Version: 1.30.27
 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
 
 **Deterministic, behavior-aware codebase context for AI agents and PR review.**
 
-![Version](https://img.shields.io/badge/version-1.30.25-blue)
+![Version](https://img.shields.io/badge/version-1.30.27-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -257,7 +257,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.30.25
+# sourcecode 1.30.27
 ```
 
 ---

{sourcecode-1.30.25 → sourcecode-1.30.27}/README.md

@@ -2,7 +2,7 @@
 
 **Deterministic, behavior-aware codebase context for AI agents and PR review.**
 
-![Version](https://img.shields.io/badge/version-1.30.25-blue)
+![Version](https://img.shields.io/badge/version-1.30.27-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -38,7 +38,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.30.25
+# sourcecode 1.30.27
 ```
 
 ---

{sourcecode-1.30.25 → sourcecode-1.30.27}/pyproject.toml

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

{sourcecode-1.30.25 → sourcecode-1.30.27}/src/sourcecode/__init__.py

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

{sourcecode-1.30.25 → sourcecode-1.30.27}/src/sourcecode/confidence_analyzer.py

@@ -290,10 +290,18 @@ class ConfidenceAnalyzer:
         elif production_eps and all(ep.runtime_relevance == "low" for ep in production_eps):
             overall = _min_confidence([overall, "low"])
 
-        # Factor in architecture confidence when available
+        # Factor in architecture confidence when available.
+        # Key rule: if a pattern was detected (not None/"unknown"), arch.confidence="low"
+        # typically reflects missing documentation (no OpenAPI/ADR), not structural uncertainty.
+        # In that case, clamp the downgrade to "medium" so that high stack + high entry_points
+        # is not contradicted by a docs gap.
         arch = sm.architecture
         if arch is not None and arch.requested:
-            overall = _min_confidence([overall, arch.confidence])
+            arch_conf_for_overall = arch.confidence
+            if arch.confidence == "low" and arch.pattern not in (None, "unknown"):
+                # Pattern was detected — low is docs-only, not structural; cap downgrade at medium
+                arch_conf_for_overall = "medium"
+            overall = _min_confidence([overall, arch_conf_for_overall])
             if arch.pattern in (None, "unknown"):
                 # Architecture could not be inferred — don't let stack alone push to high
                 if overall == "high":

{sourcecode-1.30.25 → sourcecode-1.30.27}/src/sourcecode/file_classifier.py

@@ -84,16 +84,17 @@ _JAVA_ANNOTATION_RE = re.compile(r'@(RestController|Controller|Service|Repositor
 # (annotation_set, category, relevance, why_template)
 # Checked in priority order; first match wins.
 _JAVA_STEREOTYPE_RULES: list[tuple[frozenset, str, float, str]] = [
-    (frozenset({"EnableWebSecurity"}),               "security",        0.85, "Spring Security configuration"),
-    (frozenset({"RestController"}),                  "api_endpoint",    0.90, "Spring REST controller — defines HTTP API surface"),
-    (frozenset({"Controller", "RequestMapping"}),    "api_endpoint",    0.80, "Spring MVC controller"),
-    (frozenset({"Service", "Transactional"}),        "business_logic",  0.75, "Transactional service — business logic boundary"),
-    (frozenset({"Service"}),                         "business_logic",  0.65, "Spring service component"),
-    (frozenset({"Repository"}),                      "data_access",     0.65, "Spring repository — data access layer"),
-    (frozenset({"Mapper"}),                          "data_access",     0.65, "MyBatis mapper — SQL data access"),
-    (frozenset({"Configuration"}),                   "configuration",   0.70, "Spring configuration class"),
-    (frozenset({"Entity"}),                          "domain_model",    0.50, "JPA entity — domain model"),
-    (frozenset({"Data"}),                            "dto",             0.40, "Lombok DTO"),
+    (frozenset({"EnableWebSecurity"}),               "security",          0.85, "Spring Security configuration"),
+    (frozenset({"RestController"}),                  "api_endpoint",      0.90, "Spring REST controller — defines HTTP API surface"),
+    (frozenset({"Controller", "RequestMapping"}),    "api_endpoint",      0.80, "Spring MVC controller"),
+    (frozenset({"ControllerAdvice"}),                "exception_handler", 0.75, "Spring @ControllerAdvice — cross-cutting exception handling"),
+    (frozenset({"Service", "Transactional"}),        "business_logic",    0.75, "Transactional service — business logic boundary"),
+    (frozenset({"Service"}),                         "business_logic",    0.65, "Spring service component"),
+    (frozenset({"Repository"}),                      "data_access",       0.65, "Spring repository — data access layer"),
+    (frozenset({"Mapper"}),                          "data_access",       0.65, "MyBatis mapper — SQL data access"),
+    (frozenset({"Configuration"}),                   "configuration",     0.70, "Spring configuration class"),
+    (frozenset({"Entity"}),                          "domain_model",      0.50, "JPA entity — domain model"),
+    (frozenset({"Data"}),                            "dto",               0.40, "Lombok DTO"),
 ]
 
 # Categories produced by Java stereotype detection — used downstream to apply direct relevance

{sourcecode-1.30.25 → sourcecode-1.30.27}/src/sourcecode/prepare_context.py

@@ -2596,6 +2596,10 @@ class TaskContextBuilder:
             # These are INFERRED (LOW CONFIDENCE) — stem match, not annotation evidence.
             if any(kw in stem_lower for kw in ("validator", "validation")):
                 return "validation_component"
+            if any(kw in stem_lower for kw in ("filter", "interceptor", "aspect")):
+                return "runtime_filter"
+            if any(kw in stem_lower for kw in ("advice", "advise", "exceptionhandler", "errorhandler")):
+                return "exception_handler"
             if any(kw in stem_lower for kw in ("controller", "resource", "endpoint", "rest")):
                 return "external_interface"
             if any(kw in stem_lower for kw in ("service", "svc", "usecase", "facade")):

{sourcecode-1.30.25 → sourcecode-1.30.27}/src/sourcecode/ranking_engine.py

@@ -251,3 +251,95 @@ class RankingEngine:
 
     def is_auxiliary(self, path: str) -> bool:
         return self._scorer.is_auxiliary(path)
+
+
+# ---------------------------------------------------------------------------
+# Mandatory scoring formula — deterministic 5-component impact model
+# ---------------------------------------------------------------------------
+
+# runtime_impact: execution-path role of the file
+_RUNTIME_IMPACT: dict[str | None, float] = {
+    "api_endpoint": 1.0,        # @RestController / @Controller
+    "security": 1.0,             # @EnableWebSecurity / security filters
+    "runtime_core": 1.0,         # confirmed production entrypoint
+    "cli_entrypoint": 1.0,
+    "exception_handler": 0.8,    # @ControllerAdvice
+    "business_logic": 0.7,       # @Service (with or without @Transactional)
+    "api_layer": 0.7,            # API framework import (non-annotation evidence)
+    "data_access": 0.5,          # @Repository / @Mapper
+    "database_layer": 0.5,       # DB framework import
+    "infrastructure": 0.5,       # infra dependency import
+    "configuration": 0.4,        # @Configuration
+    "application_logic": 0.3,    # code defs + imports, no framework annotation
+    "domain_model": 0.3,         # @Entity / domain models
+    "dto": 0.2,                  # @Data / pure data carriers
+    "build_system": 0.15,
+    "tests": 0.1,
+    "tooling": 0.05,
+    None: 0.15,                  # unclassified source file
+}
+
+# framework_signal_strength: annotation / import evidence quality
+# Spring annotation → 0.3; security component → +0.2 (total 0.5); import only → 0.2
+_FRAMEWORK_SIGNAL: dict[str | None, float] = {
+    "security": 0.5,             # Spring Security annotation + security component
+    "api_endpoint": 0.3,         # @RestController / @Controller
+    "exception_handler": 0.3,    # @ControllerAdvice
+    "business_logic": 0.3,       # @Service
+    "data_access": 0.3,          # @Repository / @Mapper
+    "configuration": 0.3,        # @Configuration
+    "domain_model": 0.3,         # JPA @Entity
+    "dto": 0.3,                  # Lombok @Data
+    "api_layer": 0.2,            # framework import (weaker than annotation)
+    "database_layer": 0.2,
+    "infrastructure": 0.2,
+}
+
+# Normalization ceiling per evidence tier — used when spread < 0.40
+_NORM_TARGET_HI: dict[str, float] = {
+    "api_endpoint": 0.90,
+    "security": 0.90,
+    "exception_handler": 0.82,
+    "business_logic": 0.80,
+    "api_layer": 0.80,
+    "data_access": 0.70,
+    "database_layer": 0.70,
+    "infrastructure": 0.70,
+    "configuration": 0.65,
+}
+
+
+def resolve_runtime_impact(category: str | None) -> float:
+    """Map FileClassifier category → runtime_impact [0.0, 1.0]."""
+    return _RUNTIME_IMPACT.get(category, _RUNTIME_IMPACT[None])
+
+
+def resolve_framework_signal(category: str | None) -> float:
+    """Map FileClassifier category → framework_signal_strength [0.0, 0.5]."""
+    return _FRAMEWORK_SIGNAL.get(category, 0.0)
+
+
+def compute_impact_score(
+    runtime_impact: float,
+    dependency_centrality: float,
+    framework_signal_strength: float,
+    change_type_severity: float,
+    test_risk_factor: float,
+) -> float:
+    """Mandatory weighted scoring formula.
+
+    score = 0.35×runtime_impact + 0.25×dependency_centrality
+          + 0.20×framework_signal_strength + 0.10×change_type_severity
+          + 0.10×test_risk_factor
+
+    All inputs [0.0, 1.0]. Output clamped [0.0, 1.0].
+    Deterministic: same inputs always produce same output.
+    """
+    raw = (
+        0.35 * runtime_impact
+        + 0.25 * dependency_centrality
+        + 0.20 * framework_signal_strength
+        + 0.10 * change_type_severity
+        + 0.10 * test_risk_factor
+    )
+    return max(0.0, min(1.0, raw))

{sourcecode-1.30.25 → sourcecode-1.30.27}/src/sourcecode/serializer.py

@@ -660,6 +660,116 @@ def _jndi_datasources(sm: "SourceMap") -> "Optional[list[dict[str, Any]]]":
     return datasources
 
 
+def _tiered_display_score(
+    pre_bonus_combined: float,
+    file_class: Any,
+    path: str,
+    entry_paths: set,
+    has_structural_signals: bool = False,
+) -> float:
+    """Evidence-tiered display score [0.0, 1.0].
+
+    Tiers enforce: strong evidence > medium evidence > filesystem/path only.
+    M3 sort bonuses must NOT be included in pre_bonus_combined — they are for
+    ordering only and must not inflate the displayed score.
+
+    Tier ceilings:
+      T1  confirmed production entrypoint           0.92–1.00
+      T2  entrypoint (weaker category)              0.80–0.91
+      T3  annotation-confirmed stereotype           0.40–0.90  (table-calibrated)
+      T4  framework import evidence                 0.55–0.79
+      T5  code definitions + imports                0.38–0.54
+      T6  build manifest / tooling / test           0.25–0.45
+      T7  path/filesystem signal only               0.10–0.39
+    """
+    from sourcecode.file_classifier import JAVA_STEREOTYPE_CATEGORIES
+
+    cat = file_class.category if file_class else None
+    base_rel = file_class.relevance if file_class else 0.0
+
+    # T1: confirmed production entrypoint
+    if path in entry_paths and cat in ("runtime_core", "cli_entrypoint"):
+        return round(min(1.0, max(0.92, base_rel)), 3)
+
+    # T2: in entry_paths but weaker evidence category
+    if path in entry_paths:
+        return round(min(0.91, max(0.80, pre_bonus_combined / 2.0)), 3)
+
+    # T3: annotation-confirmed stereotype — table values are already calibrated
+    if file_class and cat in JAVA_STEREOTYPE_CATEGORIES:
+        return round(base_rel, 3)
+
+    # T4: framework import evidence (medium strength)
+    if cat in ("api_layer", "database_layer", "infrastructure"):
+        return round(min(0.79, max(0.55, pre_bonus_combined / 2.0)), 3)
+
+    # T5: code definitions with imports (medium-low)
+    if cat in ("application_logic", "domain_model"):
+        return round(min(0.54, max(0.38, pre_bonus_combined / 2.0)), 3)
+
+    # T6: build manifest / tooling / test
+    if cat == "build_system":
+        return round(min(0.45, base_rel), 3)
+    if cat in ("tests", "tooling"):
+        return round(min(0.35, base_rel), 3)
+
+    # T7: no content classification — filesystem/structural signals only
+    # has_structural_signals: fan_in, churn, export — allows up to 0.54
+    # pure path/filename only — hard cap 0.39
+    if has_structural_signals:
+        return round(min(0.54, max(0.10, pre_bonus_combined / 2.0)), 3)
+    return round(min(0.39, max(0.10, pre_bonus_combined / 2.0)), 3)
+
+
+def _build_file_signals(
+    file_class: Any,
+    path: str,
+    entry_paths: set,
+    fs_reasons: list,
+    sem_hub: float,
+) -> list[dict]:
+    """Minimal per-file signal breakdown: what contributed to this file's score."""
+    from sourcecode.file_classifier import JAVA_STEREOTYPE_CATEGORIES
+
+    signals: list[dict] = []
+
+    if path in entry_paths:
+        signals.append({"type": "runtime_entrypoint", "strength": "strong"})
+
+    if file_class:
+        cat = file_class.category
+        if cat in JAVA_STEREOTYPE_CATEGORIES:
+            signals.append({"type": "framework_annotation", "strength": "strong"})
+        elif cat in ("api_layer", "database_layer", "infrastructure"):
+            ev = [e for e in (file_class.evidence or [])[:2] if e]
+            signals.append({"type": "framework_import", "strength": "medium", "evidence": ev})
+        elif cat in ("application_logic",):
+            signals.append({"type": "code_definitions_with_imports", "strength": "medium"})
+        elif cat in ("domain_model",):
+            signals.append({"type": "domain_model_definitions", "strength": "medium"})
+        elif cat in ("build_system",):
+            signals.append({"type": "build_manifest", "strength": "medium"})
+
+    for r in fs_reasons:
+        r_lower = r.lower()
+        if "import centrality" in r_lower or "imported by" in r_lower:
+            signals.append({"type": "import_centrality", "strength": "medium"})
+        elif "hub module" in r_lower:
+            signals.append({"type": "hub_module", "strength": "medium"})
+        elif "recent churn" in r_lower:
+            signals.append({"type": "git_churn", "strength": "medium"})
+        elif "uncommitted" in r_lower:
+            signals.append({"type": "uncommitted_changes", "strength": "medium"})
+
+    if sem_hub >= 0.15:
+        signals.append({"type": "call_graph_hub", "strength": "strong"})
+
+    if not signals:
+        signals.append({"type": "filesystem_path", "strength": "weak"})
+
+    return signals
+
+
 def _file_relevance(sm: SourceMap, *, limit: int = _FILE_RELEVANCE_LIMIT) -> list[dict[str, Any]]:
     from sourcecode.ranking_engine import RankingEngine
 
@@ -692,13 +802,13 @@ def _file_relevance(sm: SourceMap, *, limit: int = _FILE_RELEVANCE_LIMIT) -> lis
                 semantic_hub_scores[p] = h.get("importance_score", 0.0) / max_importance
 
     entry_paths = {ep.path for ep in sm.entry_points}
-    # REST/MVC controllers are HTTP surface — surface before @Transactional services
-    _rest_ctrl_paths = {
-        ep.path for ep in sm.entry_points
-        if getattr(ep, "kind", "") in {"rest_controller", "mvc_controller"}
-    }
     scored: list[tuple[float, dict[str, Any]]] = []
 
+    from sourcecode.ranking_engine import (
+        compute_impact_score, resolve_runtime_impact, resolve_framework_signal,
+        _NORM_TARGET_HI,
+    )
+
     for path in sm.file_paths:
         file_class = classifier.classify(path)
         fs = engine.score(
@@ -711,96 +821,129 @@ def _file_relevance(sm: SourceMap, *, limit: int = _FILE_RELEVANCE_LIMIT) -> lis
         if fs.score < -50:  # hard noise
             continue
 
-        content_rel = file_class.relevance if file_class else 0.0
-        # Semantic hub bonus: normalised call-graph centrality adds up to +0.30
-        sem_hub = semantic_hub_scores.get(path, 0.0) * 0.30
-        combined = fs.score + content_rel + sem_hub
-        # REST controller boost: surface above @Transactional service files
-        if path in _rest_ctrl_paths:
-            combined += 2.0
-
-        # M3: Structural importance scoring — priority over alphabetical ordering.
         stem = Path(path).stem
-        stem_lower = stem.lower()
-        path_lower = path.lower()
-        # +10 application entry points
-        if path in entry_paths and any(
-            k in stem for k in ("Application", "Main", "Initializer", "Bootstrap", "Startup")
-        ):
-            combined += 10.0
-        # +8 known base/infrastructure classes
-        elif any(k in stem for k in (
-            "GenericRestController", "GenericCRUDRestController", "GenericController",
-            "AkitaBaseService", "BaseService", "FilterConfig", "AbstractController",
-        )):
-            combined += 8.0
-        # +6 security configuration
-        elif any(k in stem for k in (
-            "SecurityConfig", "SecurityStrategy", "WebSecurityConfig", "SecurityFilter",
-            "JwtFilter", "AuthConfig", "SecurityConfiguration",
-        )):
-            combined += 6.0
-        # +2 shared utilities
-        elif any(k in path_lower for k in ("util", "shared", "common", "helper", "constant")):
-            combined += 2.0
-
-        # Visibility threshold: require meaningful combined signal.
-        # Exception: high/medium-confidence files with strong content relevance
-        # can survive even if structural score is weak.
-        if combined < _FILE_RELEVANCE_MIN_COMBINED:
+        cat = file_class.category if file_class else None
+
+        # ── Component 1: runtime_impact — execution-path role ─────────────────
+        runtime_impact = resolve_runtime_impact(cat)
+
+        # ── Component 2: dependency_centrality — call-graph importance ─────────
+        # Entry points treat external HTTP/CLI callers as high centrality.
+        # Isolated files (no semantic data) score 0.0 — negative weighting by omission.
+        dep_centrality = semantic_hub_scores.get(path, 0.0)
+        if path in entry_paths:
+            dep_centrality = max(dep_centrality, 0.8)
+
+        # ── Component 3: framework_signal_strength — annotation quality ─────────
+        fw_signal = resolve_framework_signal(cat)
+
+        # ── Component 4: change_type_severity — git churn as structural proxy ───
+        churn = git_churn.get(path, 0)
+        change_sev = min(churn / max(max_churn, 1), 1.0) * 0.8
+
+        # ── Component 5: test_risk_factor — no per-file coverage data ──────────
+        test_risk = 0.2
+
+        formula_raw = compute_impact_score(
+            runtime_impact, dep_centrality, fw_signal, change_sev, test_risk
+        )
+
+        # T1 override: confirmed production entrypoints → 0.92–1.00.
+        # Only runtime_core / cli_entrypoint categories justify scores ≥ 0.92.
+        if path in entry_paths and cat in ("runtime_core", "cli_entrypoint"):
+            score_val = round(
+                min(1.0, max(0.92, file_class.relevance if file_class else 0.92)), 3
+            )
+        else:
+            score_val = round(formula_raw, 3)
+
+        # Visibility threshold: formula score or high-relevance content exception.
+        if score_val < _FILE_RELEVANCE_MIN_COMBINED:
             if not (file_class
                     and file_class.relevance > 0.45
                     and file_class.confidence in {"high", "medium"}):
                 continue
 
-        # Suppress low-confidence auxiliary/config files unless structurally prominent
+        # Suppress low-confidence auxiliary/config files
         if (file_class
                 and file_class.confidence == "low"
                 and file_class.category in {"config", "auxiliary"}
-                and combined < 0.45):
+                and score_val < 0.45):
             continue
 
-        # For Java stereotype annotations use the table relevance directly —
-        # the combined/2 formula would dilute the stereotype signal.
-        from sourcecode.file_classifier import JAVA_STEREOTYPE_CATEGORIES
-        if file_class and file_class.category in JAVA_STEREOTYPE_CATEGORIES:
-            relevance_val = round(file_class.relevance, 3)
-        else:
-            relevance_val = round(max(0.0, min(1.0, combined / 2.0)), 3)
+        # relevance: content evidence only — intentionally diverges from score
+        # when dep_centrality or churn are non-zero (score ≠ relevance invariant)
+        relevance_val = round(file_class.relevance, 3) if file_class else round(
+            min(0.39, max(0.10, runtime_impact)), 3
+        )
+
+        # sem_hub retained for signal reporting only — not used in score formula
+        sem_hub = semantic_hub_scores.get(path, 0.0) * 0.30
+        ranking_reasons = [r for r in fs.reasons if r != "source file"]
+        if sem_hub >= 0.15:
+            ranking_reasons.append("call graph hub")
+
+        signals = _build_file_signals(file_class, path, entry_paths, ranking_reasons, sem_hub)
 
         item: dict[str, Any] = {
             "path": path,
             "category": file_class.category if file_class else "source",
             "confidence": file_class.confidence if file_class else "low",
+            "score": score_val,
             "relevance": relevance_val,
-            "score": relevance_val,
             "reason": file_class.reason if file_class else (fs.reasons[0] if fs.reasons else "source file"),
             "evidence": file_class.evidence if file_class else [],
+            "signals": signals,
         }
 
-        ranking_reasons = [r for r in fs.reasons if r != "source file"]
-        if sem_hub >= 0.15:
-            ranking_reasons.append("call graph hub")
         if ranking_reasons:
             item["ranking_reasons"] = ranking_reasons
 
-        # Override metadata for known M3 base controller classes
+        # Override: universal base controller classes score as runtime_core
         if any(k in stem for k in ("GenericRestController", "GenericCRUDRestController")):
             item["category"] = "runtime_core"
-            item["relevance"] = 0.95
             item["score"] = 0.95
+            item["relevance"] = 0.95
             item["reason"] = (
                 "base class for all REST controllers — extends this to get "
                 "centralized exception handling via handlerException()"
             )
             item["evidence"] = ["base_rest_controller"]
             item["ranking_reasons"] = ["universal base class", "exception handling contract"]
+            item["signals"] = [{"type": "framework_annotation", "strength": "strong"}]
 
-        scored.append((combined, item))
+        # sort_key = final score (rank consistency: score order = output order)
+        scored.append((item["score"], item))
 
-    # Deterministic sort: score desc, then path asc
+    # Initial sort: score desc, path asc for deterministic tie-break
     scored.sort(key=lambda x: (-x[0], x[1]["path"]))
 
+    # Normalization: enforce minimum spread ≥ 0.4 among non-T1 files.
+    # T1 files (confirmed entrypoints, 0.92–1.0) are excluded — already correct.
+    # Prevents score compression when structural signals (--semantics, git) absent.
+    _nonep = [(sk, it) for sk, it in scored if it["path"] not in entry_paths]
+    if len(_nonep) > 1:
+        _vals = [it["score"] for _, it in _nonep]
+        _lo, _hi = min(_vals), max(_vals)
+        _spread = _hi - _lo
+        if _spread < 0.40:
+            _top_cat = max(_nonep, key=lambda x: x[1]["score"])[1].get("category", "")
+            _target_hi = _NORM_TARGET_HI.get(_top_cat, 0.60)
+            _target_lo = max(0.10, _target_hi - 0.50)
+            if _spread > 0:
+                _scale = (_target_hi - _target_lo) / _spread
+                for _, it in _nonep:
+                    it["score"] = round(
+                        max(0.0, min(1.0, _target_lo + (it["score"] - _lo) * _scale)), 3
+                    )
+            else:
+                _mid = round((_target_hi + _target_lo) / 2.0, 3)
+                for _, it in _nonep:
+                    it["score"] = _mid
+
+    # Re-sort by final score to guarantee rank consistency after normalization
+    scored.sort(key=lambda x: (-x[1]["score"], x[1]["path"]))
+
     # Diversity cap: at most half the budget from any single category.
     # Prevents 10/10 controllers drowning out services, repositories, domain.
     _CAT_CAP = max(1, limit // 2)