sourcecode 4.5.3__py3-none-any.whl → 4.7.0__py3-none-any.whl

sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "4.5.3"
+__version__ = "4.7.0"

sourcecode/archetype.py

@@ -86,6 +86,14 @@ _MIN_CONFIDENT_SCORE = 0.5
 # discriminating. Tuned so a clear library (no app/server/servlet entry) is not confidently
 # labeled an engine, while runnable systems (which never trigger the gate) are untouched.
 _LIBRARY_ENGINE_DISCOUNT = 0.55
+# The same shape for the opposite mistake (C3-43): a repository whose primary
+# surface is HTTP owns storage/kernel packages and hub topology *because* it
+# serves requests with them, so that evidence is not discriminating for "engine"
+# either. Scaled by the measured density, so a repository with a marginal surface
+# is barely discounted and one that is nothing but endpoints is discounted fully.
+# Below the library figure on purpose: an application CAN be built around an
+# engine, whereas a non-runnable artifact cannot be an engine product at all.
+_HTTP_ENGINE_DISCOUNT = 0.45
 # Entry kinds that make a repo a runnable system (an app/server/servlet/daemon) rather
 # than a consumable library. Used to gate the library de-bias (P0).
 _RUNNABLE_ENTRY_KINDS = frozenset({
@@ -409,6 +417,42 @@ class ArchetypeClassifier:
             add("application", "runtime_entry_plus_services",
                 f"bootstrap/server entry + service mass ≈ {cm['service']:.0%}",
                 2.0, 1.0, max(cm["service"], 0.2))
+        # C3-43. The strongest MEASURED discriminator this build has for what a
+        # repository is — its HTTP surface — was read by `_primary_interface` and
+        # ignored here, so a 3 574-endpoint CRUD REST monolith was labelled
+        # `engine` on package-name masses and a fan-in Gini, while the legacy
+        # classifier it supersedes answered `api` and was right. Same ramp as the
+        # interface dimension, from the same features: one authority for the
+        # figure, two dimensions reading it.
+        if f.endpoint_share is None:
+            # Unmeasured is not zero: contribute nothing, and say so.
+            add("application", "http_surface_density",
+                "endpoint surface not measured — this dimension is scored without it",
+                2.5, 0.0, 0.0)
+        else:
+            density = f.endpoint_share * 100
+            http_strength = (
+                max(0.0, min(1.0, (density - 0.5) / 1.5)) if f.endpoint_total else 0.0
+            )
+            add("application", "http_surface_density",
+                f"{f.endpoint_total} endpoints over {f.total_files} files "
+                f"({density:.2f}/100 files) — the repository's primary surface is HTTP",
+                2.5, http_strength, 1.0)
+            # And the same fact as NAMED negative evidence for `engine`, the way
+            # the library de-bias below does it: a codebase whose product is a
+            # request surface owns storage and kernel packages *because* it is an
+            # application, so that mass is not, alone, evidence of an engine.
+            engine_positive_http = sum(max(0.0, e.contribution) for e in cands["engine"])
+            if http_strength > 0 and engine_positive_http > 0:
+                cands["engine"].append(Evidence(
+                    "http_surface_discount",
+                    f"{f.endpoint_total} endpoints over {f.total_files} files: the "
+                    "primary surface of this repository is HTTP, and the storage/"
+                    "kernel mass and hub topology an application needs to serve it "
+                    "are not, alone, evidence of an engine product",
+                    1.0, 1.0, 1.0,
+                    -engine_positive_http * _HTTP_ENGINE_DISCOUNT * http_strength,
+                ))
         # platform: many modules + multiple concept clusters + distribution
         multi = 1.0 if f.module_count >= 8 else f.module_count / 8
         add("platform", "many_modules_multi_concern",

sourcecode/baseline_autocapture.py

@@ -210,7 +210,19 @@ def worktree_dirty(
         return None
     if out.returncode != 0:
         return None
-    lines = [ln for ln in out.stdout.splitlines() if ln.strip()]
+    # C1-27. "Dirty" means the tree *the analysis reads* differs from HEAD. A
+    # change under an editor or agent state directory is not one — no analyser
+    # opens those files — and counting it reported STALE on a snapshot that
+    # described the tree exactly, with `Delta: 0` beside it. One authority answers
+    # which paths qualify (`path_filters.analysis_reads`) and its default is
+    # inclusive: anything not named there still counts, because a missed change
+    # is a false *fresh* and a spurious one only costs a rebuild.
+    from sourcecode.path_filters import analysis_reads
+
+    lines = [
+        ln for ln in out.stdout.splitlines()
+        if ln.strip() and analysis_reads(_porcelain_path(ln))
+    ]
     if ignore is None:
         return bool(lines)
     candidates = [ignore] if isinstance(ignore, (str, Path)) else list(ignore)

sourcecode/cache.py

@@ -213,6 +213,14 @@ def _untracked_tree_fingerprint(target: Path) -> str:
     return f"ff{h.hexdigest()[:14]}"
 
 
+def _porcelain_status_path(line: str) -> str:
+    """The path a `git status --porcelain` line refers to (destination on renames)."""
+    body = line[3:] if len(line) > 3 else ""
+    if " -> " in body:
+        body = body.split(" -> ", 1)[1]
+    return body.strip().strip('"')
+
+
 def worktree_signature(repo_root: Path, scope: Optional[Path] = None) -> str:
     """Hex fingerprint of the **exact tree state an analysis would read**.
 
@@ -252,12 +260,30 @@ def worktree_signature(repo_root: Path, scope: Optional[Path] = None) -> str:
         porcelain = st.stdout if st.returncode == 0 else ""
     except Exception:
         porcelain = ""
+    # C1-27. The signature describes *the tree an analysis would read*, so a line
+    # about a file no analyser opens does not belong in it — an editor settings
+    # file was invalidating every cached answer and publishing STALE beside
+    # `Delta: 0`. One authority decides which paths qualify, and its default is
+    # inclusive: anything not named there still invalidates.
+    from sourcecode.path_filters import analysis_reads
+
+    porcelain = "\n".join(
+        ln for ln in porcelain.splitlines()
+        if ln.strip() and analysis_reads(_porcelain_status_path(ln))
+    )
     if not porcelain.strip():
         return head  # clean — HEAD fully describes the tree
 
     try:
+        from sourcecode.path_filters import _TOOL_STATE_DIRS
+
+        # The same exclusion, expressed to git for the half that is not a list of
+        # paths. A tracked editor-state file must not enter the signature through
+        # the diff after being kept out of the status.
+        _diff_spec = list(pathspec) or ["--", "."]
+        _diff_spec += [f":(exclude,glob)**/{d}/**" for d in sorted(_TOOL_STATE_DIRS)]
         df = subprocess.run(
-            ["git", "-C", str(root), "diff", "HEAD", *pathspec],
+            ["git", "-C", str(root), "diff", "HEAD", *_diff_spec],
             capture_output=True, text=True, timeout=20,
         )
         diff_txt = df.stdout if df.returncode == 0 else ""

sourcecode/cli.py

@@ -354,7 +354,7 @@ of files) in minutes. Semantic analysis itself is sub-second; repo indexing domi
   ask --agent                  [dim]# full structured JSON for AI agents[/dim]
 
 [bold]Change and risk:[/bold]
-  impact-chain <Class> .       [dim]# blast radius w/ TX + security per hop[/dim]
+  impact-chain <Class> .       [dim]# blast radius; TX/SEC findings opt-in[/dim]
   impact <Class> .             [dim]# reverse deps → endpoints reached[/dim]
   pr-impact . --files -        [dim]# same, scoped to a diff on stdin; gating codes[/dim]
   posture . --since main       [dim]# did this branch open an endpoint? (exp.)[/dim]
@@ -8419,8 +8419,16 @@ def impact_chain_cmd(
              "surfaces). Totals stay exact in metadata/truncated_lists. "
              "0 disables the cap.",
     ),
+    with_findings: bool = typer.Option(
+        False, "--with-findings",
+        help=(
+            "Also run the repository-wide TX + security audit and filter findings "
+            "to this chain. Off by default so query cost follows the queried "
+            "subgraph rather than the whole repository."
+        ),
+    ),
 ) -> None:
-    """Spring impact-chain: systemic blast radius of a symbol with TX/SEC enrichment.
+    """Spring impact-chain: systemic blast radius of a symbol; TX/SEC findings are opt-in.
 
     \b
     Given a symbol (class or method), returns:
@@ -8431,6 +8439,7 @@ def impact_chain_cmd(
       - security_surfaces   — per-endpoint security verdict + confidence
                               (security_posture authority) + declared policy + SEC findings
       - impact_findings     — TX/SEC audit findings touching the call chain
+                              (only with --with-findings)
       - risk_level          — critical | high | medium | low
 
     \b
@@ -8537,7 +8546,10 @@ def impact_chain_cmd(
         )
         return
 
-    result = run_impact_chain(cir, symbol, depth=depth, root=target, model=_model)
+    result = run_impact_chain(
+        cir, symbol, depth=depth, root=target, model=_model,
+        include_findings=with_findings,
+    )
 
     data = result.to_dict()
     # Same rule as `impact`: a file is a request for the whole answer (C2-2). An
@@ -8853,7 +8865,9 @@ def explain_cmd(
         except Exception:
             cir = ContextGraph.build(file_list, target).cir  # fallback: never break explain
         model = SpringSemanticModel.build(cir)
-        explanation = explain_class(class_name, cir, model).capped(limit)
+        # `root` is what lets the security section read the request-chain rules a
+        # configuration class declares in a DSL rather than in annotations (C3-41).
+        explanation = explain_class(class_name, cir, model, root=target).capped(limit)
     finally:
         _prog.finish()
     if _cc_look is not None:

sourcecode/detectors/java.py

@@ -457,6 +457,10 @@ class JavaDetector(AbstractDetector):
             or "resteasy" in text       # RESTEasy — a JAX-RS implementation
         ):
             frameworks.append(FrameworkDetection(name="JAX-RS", source=source))
+        if "com.sun.jersey" in text or "org.glassfish.jersey" in text:
+            frameworks.append(FrameworkDetection(name="Jersey", source=source))
+        if "com.netflix.governator" in text:
+            frameworks.append(FrameworkDetection(name="Governator", source=source))
         if "mybatis" in text:
             frameworks.append(FrameworkDetection(name="MyBatis", source=source))
         if "thymeleaf" in text:

sourcecode/explain.py

@@ -15,6 +15,7 @@ are transitional and tracked for a later phase.
 from __future__ import annotations
 
 from dataclasses import dataclass, field
+from pathlib import Path
 from typing import TYPE_CHECKING, Optional
 
 from sourcecode.caller_metrics import CALLER_METRIC_RECONCILIATION
@@ -397,7 +398,15 @@ def _structural_purpose(
 
 
 def _build_public_methods(class_fqn: str, raw_nodes: list[dict]) -> list[str]:
-    """Return public method names for class_fqn from raw_ir nodes."""
+    """Return public method names for class_fqn from raw_ir nodes.
+
+    C3-41: a factory member (`symbol_kind: "bean"`) is a method, and it is the
+    *whole* API of a configuration class. Excluding the kind reported
+    `public_methods: []` for every `@Configuration` in every repository. Its
+    Java visibility is not the test either — a factory member is called by the
+    container, not by a caller in this repository, so a package-private one is
+    still the class's published surface.
+    """
     prefix = class_fqn + "#"
     methods: list[str] = []
     for node in raw_nodes:
@@ -405,6 +414,11 @@ def _build_public_methods(class_fqn: str, raw_nodes: list[dict]) -> list[str]:
         if not fqn.startswith(prefix):
             continue
         kind = node.get("symbol_kind") or node.get("type") or ""
+        if kind == "bean":
+            name = fqn[len(prefix):]
+            if name and not name.startswith("<"):
+                methods.append(name)
+            continue
         if kind not in ("method", "endpoint", "constructor", ""):
             continue
         modifiers: list[str] = node.get("modifiers") or []
@@ -465,10 +479,45 @@ def _build_callers(
     return [_simple(f) if counts[_simple(f)] == 1 else f for f in fqns]
 
 
-def _build_deps(class_fqn: str, graph: "ContextGraph") -> list[str]:
-    """DI injected dependencies, simple names — via the ContextGraph public API."""
-    deps = graph.injected_dependencies_of(class_fqn)
-    return sorted({_simple(d) for d in deps})
+def _build_deps(
+    class_fqn: str, graph: "ContextGraph", raw_nodes: "Optional[list[dict]]" = None
+) -> list[str]:
+    """What this class depends on, simple names — via the ContextGraph public API.
+
+    Injected dependencies for a class that is wired; **plus what a factory
+    declares**, for a class that does the wiring (C3-41). A configuration class
+    injects nothing: it names its collaborators in the signatures of its factory
+    members and builds them in their bodies, so reading only the injection graph
+    reported `outgoing_deps: []` for a class with eight collaborators per method.
+
+    Evidence, not naming: the extra sources are read only when the class actually
+    declares factory members, and both are atoms the IR already publishes — the
+    class-scope type surface and the instantiation facts.
+    """
+    deps = set(graph.injected_dependencies_of(class_fqn))
+    if _factory_members(class_fqn, raw_nodes or []):
+        deps.update(
+            ref.type for ref in graph.class_type_references_in(class_fqn) if ref.type
+        )
+        for member in _factory_members(class_fqn, raw_nodes or []):
+            deps.update(inst.type for inst in graph.instantiations_in(member) if inst.type)
+    return sorted({_simple(d) for d in deps if d})
+
+
+def _factory_members(class_fqn: str, raw_nodes: list[dict]) -> list[str]:
+    """Members of this class that declare a bean rather than behaviour.
+
+    The IR already classifies them (`symbol_kind: "bean"`); this is the one place
+    that reads it, so both the method list and the dependency list agree about
+    what a configuration class contains.
+    """
+    prefix = class_fqn + "#"
+    return [
+        str(node.get("fqn"))
+        for node in raw_nodes
+        if str(node.get("fqn") or "").startswith(prefix)
+        and (node.get("symbol_kind") or "") == "bean"
+    ]
 
 
 def _build_events_published(class_fqn: str, model: "SpringSemanticModel") -> list[str]:
@@ -566,6 +615,44 @@ def _build_security(
     return result
 
 
+def _build_chain_rules(class_fqn: str, cir: "CanonicalRepositoryIR", root) -> list[str]:
+    """Access rules this class declares for the request chain.
+
+    C3-41. A class that configures the chain writes its constraints in a DSL, not
+    in annotations, so the annotation reader returned `[]` for the one class whose
+    entire job is deciding access — while `posture`, in the same build, read its
+    rules from that very file. One authority answers it (`chain_rules`), so the
+    two commands cannot describe the same file differently.
+    """
+    if root is None:
+        return []
+    from sourcecode.chain_rules import rules_from_source
+
+    rel = _source_file_of(class_fqn, cir)
+    if not rel:
+        return []
+    try:
+        source = (Path(root) / rel).read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return []
+    out: list[str] = []
+    for rule in rules_from_source(source, rel):
+        patterns = ", ".join(rule.patterns) if rule.patterns else "**"
+        out.append(
+            f"request chain: {patterns} → {rule.decision} "
+            f"({rel}:{rule.line})"
+        )
+    return out
+
+
+def _source_file_of(class_fqn: str, cir: "CanonicalRepositoryIR") -> str:
+    """The repo-relative file declaring this class, from the IR's own node."""
+    for node in _get_raw_nodes(cir):
+        if node.get("fqn") == class_fqn:
+            return str(node.get("file") or node.get("source_file") or "")
+    return ""
+
+
 def _build_endpoints(class_fqn: str, model: "SpringSemanticModel") -> list[str]:
     """REST endpoints declared on this controller class."""
     endpoints = model.endpoint_index.endpoints_for(class_fqn)
@@ -585,13 +672,27 @@ def explain_class(
     class_name: str,
     cir: "CanonicalRepositoryIR",
     model: "SpringSemanticModel",
+    root: "Optional[Path]" = None,
 ) -> ClassExplanation:
     """Build a ClassExplanation for class_name from existing CIR + model.
 
-    Never raises — wraps all derivation in try/except.
+    Never raises. C3-41: a section that *failed* now says so. Every section was
+    wrapped in a bare `except: []`, which made a crash and a measured emptiness
+    the same output — and an empty section reads as *"there are none"*.
     """
     warnings: list[str] = []
 
+    def _section_of(name: str, build, default):
+        """Run one section builder; a failure becomes a warning, not a silence."""
+        try:
+            return build()
+        except Exception as exc:  # pragma: no cover — defensive by contract
+            warnings.append(
+                f"{name} could not be derived ({type(exc).__name__}): this section "
+                f"is empty because the derivation failed, not because there is none"
+            )
+            return default
+
     try:
         class_fqn, all_matches = _resolve_fqn(class_name, cir)
     except Exception:
@@ -630,40 +731,32 @@ def explain_class(
     except Exception:
         purpose = f"{stereotype} class"
 
-    try:
-        public_methods = _build_public_methods(class_fqn, raw_nodes)
-    except Exception:
-        public_methods = []
-
-    try:
-        incoming_callers = _build_callers(class_fqn, cir, graph)
-    except Exception:
-        incoming_callers = []
-
-    try:
-        outgoing_deps = _build_deps(class_fqn, graph)
-    except Exception:
-        outgoing_deps = []
-
-    try:
-        events_published = _build_events_published(class_fqn, model)
-    except Exception:
-        events_published = []
-
-    try:
-        events_consumed = _build_events_consumed(class_fqn, model)
-    except Exception:
-        events_consumed = []
-
-    try:
-        transactions = _build_transactions(class_fqn, model)
-    except Exception:
-        transactions = []
-
-    try:
-        security_constraints = _build_security(class_fqn, raw_nodes, cir)
-    except Exception:
-        security_constraints = []
+    public_methods = _section_of(
+        "public_methods", lambda: _build_public_methods(class_fqn, raw_nodes), []
+    )
+    incoming_callers = _section_of(
+        "incoming_callers", lambda: _build_callers(class_fqn, cir, graph), []
+    )
+    outgoing_deps = _section_of(
+        "outgoing_deps", lambda: _build_deps(class_fqn, graph, raw_nodes), []
+    )
+    events_published = _section_of(
+        "events_published", lambda: _build_events_published(class_fqn, model), []
+    )
+    events_consumed = _section_of(
+        "events_consumed", lambda: _build_events_consumed(class_fqn, model), []
+    )
+    transactions = _section_of(
+        "transactions", lambda: _build_transactions(class_fqn, model), []
+    )
+    security_constraints = _section_of(
+        "security_constraints", lambda: _build_security(class_fqn, raw_nodes, cir), []
+    )
+    # A class that configures the request chain declares its constraints in a
+    # DSL. Same section, one authority (`chain_rules`) — never a second parser.
+    security_constraints = security_constraints + _section_of(
+        "security_constraints", lambda: _build_chain_rules(class_fqn, cir, root), []
+    )
 
     try:
         rest_endpoints = _build_endpoints(class_fqn, model)

sourcecode/mcp/registry.py

@@ -1324,13 +1324,14 @@ min_severity: "low" (default) | "medium" | "high" | "critical"
 """
 
     _IMPACT_CHAIN_DOC = """\
-Spring impact-chain: blast radius of a symbol with TX/SEC semantic enrichment. JAVA/SPRING ONLY.
+Spring impact-chain: blast radius of a symbol. TX/SEC findings are opt-in. JAVA/SPRING ONLY.
 
 Do NOT call on non-Java repositories — returns resolution=not_found.
 
 Two query modes via query_type:
   "impact" (default) — BFS call graph: direct_callers, indirect_callers, endpoints_affected,
-    transaction_boundary, security_surfaces, impact_findings (TX/SEC patterns in call chain).
+    transaction_boundary, security_surfaces. impact_findings are populated only when
+    with_findings=true, because that runs a repository-wide TX + security audit.
   "events" — event topology: publishers, consumers, propagation graph for an event class
     or event publisher. Use when symbol is an event class (e.g. OrderPlacedEvent).
 
@@ -1344,6 +1345,7 @@ symbol: FQN, class name, or Class#method.
 repo_path: absolute path to the Java repository (default: current working directory).
 depth: BFS traversal depth 1–8 (default 4).
 query_type: "impact" (default) | "events"
+with_findings: false (default) | true to run the repository-wide TX + security audit
 """
 
     spring_audit = _alias_spec(
@@ -1374,7 +1376,7 @@ query_type: "impact" (default) | "events"
 
     impact_chain = _alias_spec(
         "impact_chain",
-        "Spring impact-chain: blast radius + TX/SEC enrichment. JAVA/SPRING ONLY.",
+        "Spring impact-chain: blast radius; TX/SEC findings opt-in. JAVA/SPRING ONLY.",
         ("impact-chain",),
         (
             ToolParamSpec("symbol", "argument", str, required=True, default=None,
@@ -1386,6 +1388,9 @@ query_type: "impact" (default) | "events"
             ToolParamSpec("query_type", "option", str, required=False, default="impact",
                           option_names=("--type",), choices=("impact", "events"),
                           help="impact (default) = call-chain blast radius; events = event topology"),
+            ToolParamSpec("with_findings", "option", bool, required=False, default=False,
+                          option_names=("--with-findings",), is_flag=True,
+                          help="Run TX + security audit and filter findings to this chain."),
         ),
         lambda inputs: [
             "impact-chain",
@@ -1393,7 +1398,7 @@ query_type: "impact" (default) | "events"
             str(inputs.get("repo_path", ".")),
             "--depth", str(inputs.get("depth", 4)),
             "--type", str(inputs.get("query_type", "impact")),
-        ],
+        ] + (["--with-findings"] if inputs.get("with_findings") else []),
         supported_targets=("repo_path", "class_name"),
         unsupported_targets=("file_path",),
         validator=validate_repo_path,

sourcecode/mcp/server.py

@@ -883,24 +883,31 @@ def get_migration_readiness(repo_path: str = ".", min_severity: str = "low") ->
 
 
 @mcp.tool()
-def get_impact_chain(repo_path: str = ".", symbol: str = "", depth: int = 4) -> dict:
-    """Spring impact-chain: systemic blast radius of a symbol with TX/SEC semantic enrichment. JAVA/SPRING ONLY.
+def get_impact_chain(
+    repo_path: str = ".",
+    symbol: str = "",
+    depth: int = 4,
+    with_findings: bool = False,
+) -> dict:
+    """Spring impact-chain: systemic blast radius of a symbol. TX/SEC findings are opt-in. JAVA/SPRING ONLY.
 
     Do NOT call this on non-Java repositories — it will return resolution=not_found.
 
-    Maps to: ask impact-chain <symbol> <repo_path> [--depth <depth>]
+    Maps to: ask impact-chain <symbol> <repo_path> [--depth <depth>] [--with-findings]
     Returns: ImpactChainResult with schema_version, symbol, resolution,
              direct_callers, indirect_callers, endpoints_affected,
              transaction_boundary (propagation/isolation/read_only),
              security_surfaces (per-endpoint verdict/confidence from the
              security_posture authority + declared policy + finding IDs),
-             impact_findings (TX-001..005 + SEC-001..003 findings in call chain),
+             impact_findings (TX/SEC/DEAD findings in call chain, only when
+             with_findings=true),
              analysis_warnings, risk_level, confidence, metadata.
 
     symbol: FQN, class name, or Class#method. Examples:
             "OrderService", "com.example.OrderService#placeOrder"
     repo_path: absolute path to the Java repository (default: current working directory).
     depth: BFS depth for indirect caller traversal (1–8, default: 4).
+    with_findings: run repository-wide TX + security audit and filter findings to this chain.
     """
     _raw = repo_path
     try:
@@ -915,6 +922,8 @@ def get_impact_chain(repo_path: str = ".", symbol: str = "", depth: int = 4) ->
         if _path_err is not None:
             return _path_err
         args = ["impact-chain", symbol.strip(), repo_path, "--depth", str(depth)]
+        if with_findings:
+            args.append("--with-findings")
         timeout_ms = int(os.environ.get("SOURCECODE_IMPACT_TIMEOUT_MS", str(_DEFAULT_IMPACT_TIMEOUT_MS)))
         timeout_s = timeout_ms / 1000.0
         _exec = concurrent.futures.ThreadPoolExecutor(max_workers=1)

sourcecode/migrate_check.py

@@ -1472,6 +1472,11 @@ class MigrationReport:
     # dimension scores it aggregates) so the headline number is fully traceable.
     readiness_aggregate: dict = field(default_factory=dict)
     blocking_count: int = 0
+    # Critical/high product findings on dimensions that participate in the
+    # migration-readiness headline. `blocking_count` remains the broad product
+    # blocker count for backward compatibility; this one excludes orthogonal JDK
+    # upkeep that never feeds readiness_score.
+    migration_blocking_count: int = 0
     # C1-12: null when the total is not a point (a range slice contributes to it).
     # The span always exists — read estimated_effort_range_days for the number.
     estimated_effort_days: Optional[float] = 0.0
@@ -1567,6 +1572,11 @@ class MigrationReport:
         self.blocking_count = sum(
             1 for f in main_findings if f.severity in ("critical", "high")
         )
+        self.migration_blocking_count = sum(
+            1 for f in main_findings
+            if f.severity in ("critical", "high")
+            and f.migration_target in _BOOT3_MIGRATION_TARGETS
+        )
 
         # Per-dimension readiness — independent severity-weighted scores (MAIN only).
         self.jakarta_readiness = _dimension_score(main_findings, _JAKARTA_TARGETS)
@@ -1941,6 +1951,7 @@ class MigrationReport:
             "by_rule": by_rule,
             "by_migration_target": by_target,
             "main_findings": len(main_findings),
+            "migration_blocking_findings": self.migration_blocking_count,
             "non_blocking_findings": self.non_blocking["count"],
             "hygiene_findings": self.hygiene_findings,
         }
@@ -1993,10 +2004,21 @@ class MigrationReport:
                 "(jakarta / boot3 / hibernate); see readiness_aggregate for the exact "
                 "inputs. N/A dimensions are excluded (never counted as 0); "
                 "jdk_modernization is orthogonal upkeep and is NOT in the aggregate. "
-                "For decisions read the per-dimension breakdown + blocking_count."
+                "For decisions read the per-dimension breakdown + "
+                "migration_blocking_count."
             ),
             "headline_blocker": self.headline_blocker,
             "blocking_count": self.blocking_count,
+            "blocking_count_basis": (
+                "critical/high findings in product code across every target, including "
+                "orthogonal JDK modernization"
+            ),
+            "migration_blocking_count": self.migration_blocking_count,
+            "migration_blocking_count_basis": (
+                "critical/high product-code findings whose targets feed the migration "
+                "readiness aggregate (jakarta / boot3 / spring_security_6). Excludes "
+                "orthogonal JDK modernization."
+            ),
             "estimated_effort_days": self.estimated_effort_days,
             "estimated_effort_range_days": self.estimated_effort_range_days,
             "estimated_effort_note": (
@@ -2116,6 +2138,7 @@ class MigrationReport:
                f"(readiness_score reflects jakarta/Boot3 only — Hibernate is a separate rewrite axis)"]
               if self.headline_blocker else []),
             f"Spring present: {self.spring_present}    Spring Boot 2 detected: {_boot}",
+            f"Migration blockers (readiness dimensions): {self.migration_blocking_count}",
             f"Blocking issues (product code): {self.blocking_count}  "
             f"(critical: {main_crit}, high: {main_high})"
             + (f"   [+{nb} in test/generated, non-blocking]" if nb else ""),