sourcecode 3.2.0__py3-none-any.whl → 3.2.1__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__ = "3.2.0"
+__version__ = "3.2.1"

sourcecode/chain_rules.py

@@ -274,16 +274,57 @@ def rule_matches(rule: AccessRule, method: str, path: str) -> bool:
     return any(ant_matches(pattern, path) for pattern in rule.patterns)
 
 
-def first_matching_rule(
-    rules: "list[AccessRule]", method: str, path: str
-) -> "Optional[AccessRule]":
-    """The rule Spring would apply: the first declared one that matches."""
+#: Matchers that see the DispatcherServlet path. An ant matcher matches the URL
+#: the filter chain receives — servlet path included, servlet CONTEXT path never,
+#: because the container has already stripped it. An mvc matcher matches the path
+#: relative to the servlet mapping, so the servlet path is not part of it.
+#: `requestMatchers` is either one depending on the Spring Security version and
+#: what is on the classpath — undecidable from source, so both readings are tried
+#: and the pattern is honoured if it covers the request under either.
+_SERVLET_PATH_MATCHERS = ("antMatchers", "regexMatchers", "requestMatchers")
+_SERVLET_RELATIVE_MATCHERS = ("mvcMatchers", "requestMatchers")
+
+
+def candidate_paths(rule: AccessRule, path: str, servlet_prefix: str = "") -> "tuple[str, ...]":
+    """The path(s) `rule`'s matcher compares against a mapping-relative `path`.
+
+    Without a declared servlet path the two readings coincide and this is just
+    `(path,)` — which is every repository that never set `spring.mvc.servlet.path`.
+    """
+    if not servlet_prefix or rule.is_any_request:
+        return (path,)
+    prefixed = f"{servlet_prefix.rstrip('/')}/{path.lstrip('/')}".rstrip("/") or "/"
+    out: list[str] = []
+    if rule.matcher in _SERVLET_PATH_MATCHERS:
+        out.append(prefixed)
+    if rule.matcher in _SERVLET_RELATIVE_MATCHERS or not out:
+        out.append(path)
+    return tuple(dict.fromkeys(out))
+
+
+def first_match(
+    rules: "list[AccessRule]", method: str, path: str, servlet_prefix: str = ""
+) -> "tuple[Optional[AccessRule], str]":
+    """`(rule Spring would apply, the path it matched)` — first declared wins.
+
+    The matched path is returned because with a servlet path declared it is not
+    the mapping-relative path the endpoint is keyed by, and a reader checking the
+    claim against the source line needs to see the URL the rule actually covers.
+    """
     for rule in rules:
         if rule.paths_unknown:
             # A rule whose paths could not be read may cover this request, and
             # everything after it is only reachable if it does not. Stopping here
             # is what keeps a later `permitAll` from being reported as the answer.
-            return rule
-        if rule_matches(rule, method, path):
-            return rule
-    return None
+            return rule, path
+        for candidate in candidate_paths(rule, path, servlet_prefix):
+            if rule_matches(rule, method, candidate):
+                return rule, candidate
+    return None, path
+
+
+def first_matching_rule(
+    rules: "list[AccessRule]", method: str, path: str, servlet_prefix: str = ""
+) -> "Optional[AccessRule]":
+    """The rule Spring would apply: the first declared one that matches."""
+    return first_match(rules, method, path, servlet_prefix)[0]

sourcecode/cli.py

@@ -170,10 +170,28 @@ Cache warms on first scan; later calls reuse pre-built context instead of rescan
 Scan and warm time scale with repo size — small repos in seconds, large repos (thousands
 of files) in minutes. Semantic analysis itself is sub-second; repo indexing dominates.
 
-[bold]Primary usage:[/bold]
-  ask --compact                  high-signal summary (~2,500–4,000 tokens)
-  ask --compact --git-context    include git hotspots and uncommitted files
-  ask --agent                    full structured JSON for AI agents
+[bold]Start here — Java/Spring analysis:[/bold]
+  posture . --diff dev:prod    [dim]# effective access, two profile sets (exp.)[/dim]
+  endpoints .                  [dim]# endpoints + effective path + policy[/dim]
+  spring-audit .               [dim]# TX anomalies + security surface[/dim]
+  migrate-check . --compact    [dim]# Boot 2→3: located blockers + effort[/dim]
+
+[bold]Agent context:[/bold]
+  ask --compact                [dim]# high-signal summary (~2,500–4,000 tokens)[/dim]
+  ask --compact --git-context  [dim]# + git hotspots and uncommitted files[/dim]
+  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 <Class> .             [dim]# reverse deps → endpoints reached[/dim]
+  pr-impact . --since main     [dim]# same, scoped to a diff; gating codes[/dim]
+  verify .                     [dim]# contract gate, baseline-relative[/dim]
+  verify-edit .                [dim]# did working-tree edits change behaviour?[/dim]
+  [dim]modernize · explain <Class> · validation · export · repo-ir[/dim]
+
+  [dim]Spring commands take the INTERFACE, not the Impl — callers inject it.[/dim]
+
+[dim]Every command is grouped in the panels below; full reference in docs/USER_GUIDE.md[/dim]
 
 [bold]Auth commands:[/bold]
   auth status                  [dim]# show current plan and auth state[/dim]
@@ -181,14 +199,17 @@ of files) in minutes. Semantic analysis itself is sub-second; repo indexing domi
 
 [bold]Cache commands:[/bold]
   cache status                 [dim]# cache size, hit keys, last-warmed timestamp[/dim]
-  cache warm                   [dim]# pre-build cache ahead of an agent session[/dim]
+  cache warm                   [dim]# pre-build structural layers + compact view
+                               #   (--agent warms the agent view too; --full,
+                               #   --env-map and raised --depth are NOT warmed)[/dim]
   cache clear                  [dim]# clear all cached results for this repo[/dim]
 
 [bold]Examples:[/bold]
+  ask posture . --diff default:prod -o posture.json
+  ask endpoints . -f json | jq '.endpoints | map(select(.method=="POST"))'
+  ask spring-audit . --min-severity high -o audit.json
   ask my-project --compact
   ask . --compact --git-context --copy
-  ask . --changed-only --git-context
-  ask prepare-context onboard my-project
   ask prepare-context delta . --since main
 
 [bold]Subcommands:[/bold]
@@ -4332,6 +4353,10 @@ def endpoints_cmd(
     if controller:
         _ctrl_lower = controller.lower()
         endpoints_list = [e for e in endpoints_list if _ctrl_lower in e.get("controller", "").lower()]
+    # A filter changes the population a count is about; `--limit` does not — it
+    # cuts the rendering. Measuring `total` after the cut published the display
+    # size as the measurement (ADR-0008 R5), so the two are separated here.
+    _selected = endpoints_list
     if limit is not None and limit > 0:
         endpoints_list = endpoints_list[:limit]
     if path_prefix or controller or limit is not None:
@@ -4341,11 +4366,12 @@ def endpoints_cmd(
         _no_sec_before = data.get("no_security_signal")
         _undoc_before = data.get("undocumented")
         _no_sec_after = sum(
-            1 for e in endpoints_list
+            1 for e in _selected
             if e.get("security", {}).get("policy") == "none_detected"
         )
         data["endpoints"] = endpoints_list
-        data["total"] = len(endpoints_list)
+        data["total"] = len(_selected)
+        data["shown"] = len(endpoints_list)
         data["no_security_signal"] = _no_sec_after
         data["undocumented"] = _no_sec_after
         data["_filter"] = {
@@ -4355,6 +4381,10 @@ def endpoints_cmd(
             "total_before_filter": _total_before,
             "no_security_signal_before_filter": _no_sec_before,
             "undocumented_before_filter": _undoc_before,
+            "note": (
+                "`total` counts the endpoints the filters selected; `shown` is how "
+                "many of them this document lists, which `--limit` cuts."
+            ),
         }
 
     if by_controller:
@@ -5818,10 +5848,14 @@ def spring_audit_cmd(
       SEC-003 @Transactional on @Controller/@RestController (TX in wrong layer)
 
     \b
-    CI/CD usage:
+    CI/CD usage — this gate is ABSOLUTE (any finding fails, including debt that
+    was already there). For a baseline-relative gate that fails only on findings
+    a change INTRODUCES, use `ask verify --fail-on new` (or `ask pr-impact
+    --fail-on`); `ask baseline capture/diff` tracks the debt over time.
       ask spring-audit . --ci                             # exit 1 on any finding
       ask spring-audit . --ci --min-severity high         # exit 1 only on high/critical
       ask spring-audit . --ci --format github-comment     # Markdown PR comment + exit 1
+      ask verify . --fail-on new                          # exit 1 only on NEW findings
 
     \b
     Examples:
@@ -7330,138 +7364,24 @@ def fix_bug_cmd(
     )
 
 
-# Method signatures that are almost always FRAMEWORK ENTRY POINTS, not dead code —
-# invoked by a dispatcher (reflection / XML / SPI), invisible to a static Java
-# call-graph. Generalizes beyond any one framework.
-_DYNAMIC_ENTRY_SIGNATURE_RE = __import__("re").compile(
-    r"\(\s*DispatchContext\b"                       # OFBiz Service Engine service
-    r"|HttpServletRequest\s+\w+\s*,\s*HttpServletResponse"  # OFBiz event / servlet handler
-    r"|@(?:Scheduled|PostConstruct|PreDestroy|EventListener|Bean|"
-    r"RequestMapping|GetMapping|PostMapping|Path|GET|POST|Provider|"
-    r"ApplicationScoped|Singleton)\b",              # annotation-dispatched entry
-)
-# Config file extensions where a framework wires classes by name (XML/props/yaml).
-_CONFIG_REF_EXTS: frozenset = frozenset({".xml", ".properties", ".yml", ".yaml", ".groovy"})
-_CONFIG_SCAN_MAX_FILES: int = 12000
-_CONFIG_SCAN_MAX_BYTES: int = 256 * 1024
-
-
-def _partition_static_unreferenced(nodes: list[dict], root: Path) -> tuple[list[dict], list[dict]]:
-    """Split zero-degree classes into (truly_unreferenced, framework_dispatched).
-
-    A class with no static callers is NOT necessarily dead: frameworks invoke
-    classes via reflection, XML/SPI config, or annotations that a static call-graph
-    cannot see (e.g. Apache OFBiz Service Engine services, JAX-RS resources,
-    ServiceLoader providers, scheduled beans). We exclude a candidate when EITHER:
-      1. its source declares a dynamic-entry method signature, OR
-      2. its simple name / FQN is referenced from a non-Java config file.
-    Whatever survives is reported as *statically_unreferenced* — never a confident
-    "dead zone".
-    """
-    import os
-    if not nodes:
-        return [], []
-    by_simple: dict[str, list[dict]] = {}
-    for n in nodes:
-        simple = (n.get("fqn") or "").rsplit(".", 1)[-1]
-        if simple:
-            by_simple.setdefault(simple, []).append(n)
-
-    dispatched_fqns: set[str] = set()
-
-    # 1. Source-signature allowlist (bounded — candidate set is small).
-    for n in nodes:
-        src = n.get("source_file")
-        if not src:
-            continue
-        try:
-            txt = (root / src).read_text(encoding="utf-8", errors="replace")
-        except OSError:
-            continue
-        if _DYNAMIC_ENTRY_SIGNATURE_RE.search(txt):
-            dispatched_fqns.add(n["fqn"])
-
-    # 2. Config-reference scan — find candidate names wired from XML/props/yaml.
-    unresolved_simple = {s for s, ns in by_simple.items()
-                         if any(x["fqn"] not in dispatched_fqns for x in ns)}
-    if unresolved_simple:
-        files_scanned = 0
-        for dirpath, dirnames, filenames in os.walk(root):
-            dirnames[:] = [d for d in dirnames
-                           if d not in {".git", "build", "out", "target", "node_modules", ".gradle"}]
-            for fname in filenames:
-                ext = os.path.splitext(fname)[1].lower()
-                if ext not in _CONFIG_REF_EXTS:
-                    continue
-                if files_scanned >= _CONFIG_SCAN_MAX_FILES or not unresolved_simple:
-                    break
-                fpath = os.path.join(dirpath, fname)
-                try:
-                    with open(fpath, "r", encoding="utf-8", errors="replace") as fh:
-                        text = fh.read(_CONFIG_SCAN_MAX_BYTES)
-                except OSError:
-                    continue
-                files_scanned += 1
-                for simple in list(unresolved_simple):
-                    if simple in text:
-                        for x in by_simple.get(simple, []):
-                            dispatched_fqns.add(x["fqn"])
-                        unresolved_simple.discard(simple)
-            if files_scanned >= _CONFIG_SCAN_MAX_FILES or not unresolved_simple:
-                break
+def _partition_static_unreferenced(
+    nodes: list[dict], root: Path
+) -> tuple[list[dict], list[dict]]:
+    """Split callerless types into (no dispatch signal found, framework-dispatched).
 
-    # 3. Nested-type qualified-reference scan (SC-2 residual). The static call-graph
-    #    does not emit an edge for a nested-type member access in ordinary method-body
-    #    code — e.g. `PropertyType.AdminGroupPresentation.NAME` credits the enclosing
-    #    type, not the nested holder — so a referenced nested class can look
-    #    zero-degree. When a candidate is a nested type (its second-to-last FQN segment
-    #    is an UpperCamel enclosing type) and its qualified `Outer.Nested` form appears
-    #    in some OTHER Java source, it is statically referenced: neither dead nor
-    #    framework-dispatched. Structural, name-agnostic (pattern derived from the
-    #    candidate's own FQN).
-    import re as _re_nested
-    statically_referenced: set[str] = set()
-    nested_patterns: dict[str, "tuple"] = {}
-    for n in nodes:
-        if n["fqn"] in dispatched_fqns:
-            continue
-        parts = (n.get("fqn") or "").split(".")
-        if len(parts) >= 2 and parts[-2][:1].isupper():
-            outer, nested = parts[-2], parts[-1]
-            nested_patterns[n["fqn"]] = (
-                _re_nested.compile(r"\b" + _re_nested.escape(outer) + r"\." + _re_nested.escape(nested) + r"\b"),
-                n.get("source_file") or "",
-            )
-    if nested_patterns:
-        files_scanned = 0
-        for dirpath, dirnames, filenames in os.walk(root):
-            dirnames[:] = [d for d in dirnames
-                           if d not in {".git", "build", "out", "target", "node_modules", ".gradle"}]
-            for fname in filenames:
-                if not fname.endswith(".java"):
-                    continue
-                if files_scanned >= _CONFIG_SCAN_MAX_FILES or len(statically_referenced) == len(nested_patterns):
-                    break
-                fpath = os.path.join(dirpath, fname)
-                rel = os.path.relpath(fpath, root)
-                try:
-                    with open(fpath, "r", encoding="utf-8", errors="replace") as fh:
-                        text = fh.read(_CONFIG_SCAN_MAX_BYTES)
-                except OSError:
-                    continue
-                files_scanned += 1
-                for fqn, (pat, own) in nested_patterns.items():
-                    if fqn in statically_referenced or rel == own:
-                        continue
-                    if pat.search(text):
-                        statically_referenced.add(fqn)
-            if files_scanned >= _CONFIG_SCAN_MAX_FILES or len(statically_referenced) == len(nested_patterns):
-                break
+    Kept as the shape `modernize` renders; the fact itself is derived once, in
+    `reference_facts` — the authority that also states the third answer this pair
+    cannot express, `unknown`.
+    """
+    from sourcecode.reference_facts import (
+        NO_STATIC_CALLERS, UNKNOWN_DISPATCH, analyze_type_references,
+    )
 
-    unreferenced = [n for n in nodes
-                    if n["fqn"] not in dispatched_fqns and n["fqn"] not in statically_referenced]
-    dispatched = [n for n in nodes if n["fqn"] in dispatched_fqns]
-    return unreferenced, dispatched
+    facts = analyze_type_references(nodes, root)
+    by_fqn = {str(n.get("fqn")): n for n in nodes}
+    def _nodes_of(status: str) -> list[dict]:
+        return [by_fqn[e.fqn] for e in facts.of_status(status) if e.fqn in by_fqn]
+    return _nodes_of(NO_STATIC_CALLERS), _nodes_of(UNKNOWN_DISPATCH)
 
 
 @app.command("modernize")
@@ -7479,7 +7399,7 @@ def modernize_cmd(
         help="Copy output to clipboard after a successful run.",
     ),
 ) -> None:
-    """[Pro*] Modernization planning: coupling, dead zones, risky modules, refactor candidates.
+    """[Pro*] Modernization planning: coupling, callerless types, risky modules, refactor candidates.
 
     Note: [Pro*] label is reserved for a future licensing gate. This command currently
     runs without authentication. Behavior may change in a future version.
@@ -7489,7 +7409,7 @@ def modernize_cmd(
 
     Analyzes the repo for:
       - High-coupling modules (high in-degree + out-degree nodes)
-      - Dead zones (isolated symbols with no callers)
+      - Types with no static caller, split from those a framework may dispatch (unknown)
       - Risk hotspots (high fan-in + security annotations + transaction boundaries)
       - Cross-module dependency tangles
       - Subsystem summary with member counts
@@ -7559,27 +7479,29 @@ def modernize_cmd(
         if _src and _src in _file_churn:
             _fqn_churn[_n["fqn"]] = _file_churn[_src]
 
-    # High-coupling nodes: high in_degree (many dependents = risky to change)
-    coupling_nodes = sorted(
+    # High-coupling nodes: high in_degree (many dependents = risky to change).
+    # The measurement is the full set; the list below is the display cut, and the
+    # summary counts the first, never the second (ADR-0008 R5).
+    _coupling_all = sorted(
         [n for n in graph_nodes if n.get("in_degree", 0) >= 3],
         key=lambda n: (-n.get("in_degree", 0), n.get("fqn", "")),
-    )[:20]
-
-    # Statically-unreferenced zones: classes with zero in-degree AND zero out-degree
-    # in the Java call-graph. These are NOT necessarily dead — framework dispatch
-    # (reflection / XML / SPI / annotations) is invisible to a static graph — so we
-    # partition out framework-dispatched entry points before reporting, and never
-    # call the survivors "dead". (Defect 5: OFBiz Service-Engine services and event
-    # handlers were false-positive "dead zones".)
-    _zero_degree = sorted(
-        [n for n in graph_nodes
-         if n.get("in_degree", 0) == 0 and n.get("out_degree", 0) == 0
-         and n.get("type") in ("class", "interface")],
-        key=lambda n: n.get("fqn", ""),
     )
-    dead_zones, framework_dispatched = _partition_static_unreferenced(_zero_degree, root)
-    dead_zones = dead_zones[:20]
-    framework_dispatched = framework_dispatched[:20]
+    coupling_nodes = _coupling_all[:20]
+
+    # Which types nothing calls — one authority (`reference_facts`), three answers.
+    # A static call-graph cannot see reflection, XML/SPI wiring or annotation
+    # dispatch, so "no caller found" and "not called" are different statements: the
+    # first is published here, the second never is. (M7 seam 6 / defect C3-8: this
+    # surface examined only types with no edges in EITHER direction while calling
+    # the result "zero static callers", and published `0` where the answer was
+    # unknown.)
+    from sourcecode.reference_facts import (
+        NO_STATIC_CALLERS as _NO_CALLERS,
+        UNKNOWN_DISPATCH as _UNKNOWN_DISPATCH,
+        analyze_type_references as _analyze_type_references,
+    )
+
+    _reference_facts = _analyze_type_references(graph_nodes, root)
 
     # Hotspot candidates: high in-degree service/repository/controller nodes,
     # ranked by composite score (in_degree × 2 + git_churn) for volatility signal.
@@ -7682,11 +7604,17 @@ def modernize_cmd(
     _cross_module_tangles = _cross_module_tangles[:15]
 
     _summary = {
-        "total_classes": len([n for n in graph_nodes if n.get("type") in ("class", "interface")]),
+        # Same population the reference partition is measured over, so the three
+        # statuses below sum to exactly this number.
+        "total_classes": _reference_facts.classes_examined,
         "total_subsystems": len(subsystems),
-        "high_coupling_nodes": len(coupling_nodes),
-        "statically_unreferenced": len(dead_zones),
-        "framework_dispatched": len(framework_dispatched),
+        "high_coupling_nodes": len(_coupling_all),
+        "high_coupling_nodes_shown": len(coupling_nodes),
+        # From the measurement, not from the lists below — those are truncated for
+        # display, and a count taken off them is a different number (ADR-0008 R5).
+        "statically_unreferenced": _reference_facts.count(_NO_CALLERS),
+        "framework_dispatched": _reference_facts.count(_UNKNOWN_DISPATCH),
+        "reference_status": _reference_facts.to_dict(),
     }
     # BUG #6 (v1.68.0): `member_count` counts ALL graph members in the subsystem —
     # classes, methods AND fields — so it runs ~5x higher than the class count and
@@ -7725,7 +7653,7 @@ def modernize_cmd(
             "tier_note": (
                 "This repository exceeds the free-tier size limit. "
                 "Upgrade to Pro for full analysis on enterprise-scale monoliths: "
-                "dead zones, dependency tangles, refactor candidates ranked by git "
+                "callerless types, dependency tangles, refactor candidates ranked by git "
                 "churn, and complete coupling graphs."
             ),
             "summary": _summary,
@@ -7753,19 +7681,36 @@ def modernize_cmd(
             # three share one reconciliation note so they can never contradict.
             "high_coupling_nodes_note": CALLER_METRIC_RECONCILIATION,
             "statically_unreferenced": [
-                {"fqn": n["fqn"], "type": n.get("type", ""), "role": n.get("role", "other")}
-                for n in dead_zones
+                {
+                    "fqn": e.fqn, "type": e.type, "role": e.role,
+                    # Why this type is in this list, so the claim can be checked
+                    # rather than trusted.
+                    "basis": e.basis,
+                }
+                for e in _reference_facts.of_status(_NO_CALLERS)[:20]
             ],
             "statically_unreferenced_note": (
-                "Zero static callers in the Java call-graph. NOT confirmed dead: verify "
-                "no framework dispatch (reflection, XML/SPI config, annotations) before "
-                "removing. Classes detected as framework-dispatched are listed separately "
-                "under framework_dispatched and excluded from this list."
+                "No incoming edge in the Java call-graph and no framework-dispatch "
+                "signal found. This is absence of evidence, NOT confirmed dead code: "
+                "a static graph cannot see reflection, XML/SPI wiring or annotation "
+                "dispatch, and this scan reads only the repository's own sources and "
+                "configuration. Types that DO carry a dispatch signal are reported "
+                "separately as framework_dispatched — status "
+                "`unknown_framework_dispatch`, because whether they run is not "
+                "decidable here. Counts live in summary.reference_status; this list "
+                f"shows at most 20 of {_reference_facts.count(_NO_CALLERS)}."
             ),
             "framework_dispatched": [
-                {"fqn": n["fqn"], "type": n.get("type", ""), "role": n.get("role", "other")}
-                for n in framework_dispatched
+                {"fqn": e.fqn, "type": e.type, "role": e.role, "basis": e.basis}
+                for e in _reference_facts.of_status(_UNKNOWN_DISPATCH)[:20]
             ],
+            "framework_dispatched_note": (
+                "No static caller, but a framework may invoke them (published "
+                "annotation, entry-point signature, or the name wired from a "
+                "configuration file). Status is `unknown`, never 'alive' and never "
+                "'dead'. This list shows at most 20 of "
+                f"{_reference_facts.count(_UNKNOWN_DISPATCH)}."
+            ),
             "subsystem_summary": _subsystem_summary,
             "subsystem_summary_note": _subsystem_summary_note,
             "cross_module_tangles": _cross_module_tangles,
@@ -7787,8 +7732,10 @@ def modernize_cmd(
                     if hotspots else
                     "high_coupling_nodes shows the most-referenced classes — start there. "
                 )
-                + "statically_unreferenced lists classes with no Java callers — review "
-                + "for framework dispatch (XML/reflection/SPI) before removing. "
+                + "statically_unreferenced lists types with no Java caller and no "
+                + "dispatch signal found — a starting point for review, not a "
+                + "removal list; confirm at runtime before deleting. "
+                + _reference_facts.statement + ". "
                 + "In cross_module_tangles, coupling_type=cyclic entries are the "
                 + "real tangles to decompose first; directional entries are normal "
                 + "layering ranked by coupling strength."
@@ -8138,6 +8085,9 @@ def version_cmd() -> None:
             # contract does.
             "envelope_version": ENVELOPE_VERSION,
             "published_schemas": available_schemas(),
+            # Same list `ask schema` prints, so the two surfaces cannot disagree
+            # about what this release publishes.
+            "registries": ["facts-v1"],
         }, ensure_ascii=False))
 
 
@@ -8162,13 +8112,33 @@ def schema_cmd(
     Examples:
       ask schema                  # list published schemas
       ask schema envelope-v1      # print the response-envelope schema
+      ask schema facts-v1         # print the fact registry (one fact, one authority)
     """
     from sourcecode.envelope import available_schemas, load_schema
+    from sourcecode.facts import load_registry
 
+    # The fact registry is a contract too: which facts have a single authority,
+    # who derives each, and which modules may emit it (ADR-0008 R11). Published
+    # through the command that already answers "what shape does this release
+    # produce?" rather than a command of its own.
     names = available_schemas()
+    if name == "facts-v1":
+        _emit_command_output(
+            json.dumps(load_registry(), indent=2, ensure_ascii=False),
+            output_path,
+            False,
+            stamp_envelope=False,
+        )
+        return
     if name is None:
         _emit_command_output(
-            json.dumps({"schemas": names}, indent=2, ensure_ascii=False),
+            # Schemas describe output shapes; the fact registry describes which
+            # answers have a single authority. Both are contracts this release
+            # carries, listed apart because they are not the same kind of thing.
+            json.dumps(
+                {"schemas": names, "registries": ["facts-v1"]},
+                indent=2, ensure_ascii=False,
+            ),
             output_path,
             False,
         )
@@ -9516,6 +9486,78 @@ def _stderr_is_interactive() -> bool:
         return False
 
 
+#: How `--help` groups and orders the commands — one authority for it, applied
+#: below to the registered commands themselves.
+#:
+#: `--help` is the first thing a new user reads, and it was ordered by the file's
+#: registration order: a reader met `prepare-context` and `repo-ir` before
+#: `posture` or `endpoints`, so the surface introduced itself with its weakest
+#: 20 %. Field evaluation #3 scored discoverability 3/10 and found `endpoints` —
+#: the command it valued most — by accident, inside another command's JSON.
+#:
+#: Panels are ordered by what a reader should meet first, and inside a panel by
+#: what answers the most common question. Nothing is hidden: every command is
+#: still listed, and the battery fails if one is missing from this table.
+HELP_PANELS: "tuple[tuple[str, tuple[str, ...]], ...]" = (
+    ("Java/Spring analysis — start here", (
+        "posture", "endpoints", "spring-audit", "migrate-check",
+    )),
+    ("Change and risk", (
+        "impact-chain", "impact", "pr-impact", "verify", "verify-edit",
+        "review-pr", "plan", "compare", "delta", "contract-diff", "fix-bug",
+        "rename-class",
+    )),
+    ("Context for AI agents", (
+        "prepare-context", "onboard", "explain", "export", "repo-ir",
+        "validation", "modernize", "chunk-file", "cold-start",
+    )),
+    # Inside a panel, Typer renders plain commands before command groups, so the
+    # groups (`cache`, `auth`, …) are listed last here to keep this table and the
+    # rendered help in the same order.
+    ("Setup and inspection", (
+        "activate", "config", "schema", "version",
+        "cache", "auth", "mcp", "telemetry", "baseline",
+    )),
+    ("Experimental — shape may change", (
+        "archetype", "retrieve",
+    )),
+)
+
+#: Where a command lands when it is not in the table. Visible on purpose: an
+#: unlisted command must look unfinished, not disappear.
+_UNPANELLED = "Other commands"
+
+
+def _apply_help_panels() -> None:
+    """Group and order the registered commands per `HELP_PANELS`.
+
+    Typer renders panels in the order it first meets them and commands in
+    registration order, so the grouping is applied to the registered objects
+    rather than to thirty decorator call sites — one place to read, one place a
+    new command has to be added to.
+    """
+    rank: dict[str, tuple[int, int]] = {}
+    panel_of: dict[str, str] = {}
+    for panel_index, (panel, names) in enumerate(HELP_PANELS):
+        for name_index, name in enumerate(names):
+            rank[name] = (panel_index, name_index)
+            panel_of[name] = panel
+
+    def _sort_key(entry: Any) -> "tuple[int, int, str]":
+        name = str(getattr(entry, "name", "") or "")
+        position = rank.get(name, (len(HELP_PANELS), 0))
+        return (position[0], position[1], name)
+
+    for registry in (app.registered_commands, app.registered_groups):
+        for entry in registry:
+            name = str(getattr(entry, "name", "") or "")
+            entry.rich_help_panel = panel_of.get(name, _UNPANELLED)
+        registry.sort(key=_sort_key)
+
+
+_apply_help_panels()
+
+
 def _force_utf8_streams() -> None:
     """Force UTF-8 on stdout AND stderr so Unicode characters (em-dash, arrows, box
     drawing) survive on Windows where the default console codec is cp1252 (BUG-1).

sourcecode/confidence_analyzer.py

@@ -315,12 +315,16 @@ class ConfidenceAnalyzer:
         _test_exclude_tokens = frozenset({"test", "tests", "spec", "specs", "it", "testing"})
         _tests_deliberately_excluded = bool(_extra_exc & _test_exclude_tokens)
 
+        # One authority for which files are tests (ADR-0008 R1): the substring
+        # rule this replaces counted production classes living in a package
+        # named `test` as tests, so a repository with none reported "2 test
+        # files" while `has_tests` in the same document said the same wrong
+        # thing from a second derivation.
+        from sourcecode.test_sources import analyze_test_sources
+
         _java_all = [p for p in sm.file_paths if p.endswith(".java")]
-        _java_tests = [
-            p for p in _java_all
-            if "/test/" in p.replace("\\", "/") or "/tests/" in p.replace("\\", "/")
-            or Path(p).stem.endswith(("Test", "Tests", "IT", "Spec"))
-        ]
+        _java_test_facts = analyze_test_sources(_java_all, extensions=(".java",))
+        _java_tests = list(_java_test_facts.test_files)
         _java_prod = [p for p in _java_all if p not in set(_java_tests)]
         if _java_prod and len(_java_prod) >= 10:
             _ratio = len(_java_tests) / len(_java_prod)
@@ -341,7 +345,7 @@ class ConfidenceAnalyzer:
                     reason=(
                         f"Backend test coverage critical: {len(_java_tests)} test files "
                         f"for {len(_java_prod)} Java files "
-                        f"({_ratio:.1%})"
+                        f"({_ratio:.1%}) — {_java_test_facts.basis}"
                     ),
                     impact="high",
                 ))