sourcecode 3.2.0__py3-none-any.whl → 3.2.2__py3-none-any.whl

sourcecode/cli.py

@@ -149,6 +149,88 @@ def _check_pipeline_coherence(sm: "SourceMap") -> list[str]:  # type: ignore[nam
 
     return issues
 
+# ---------------------------------------------------------------------------
+# Command tiers — what we promise about a command, published where it is read
+# ---------------------------------------------------------------------------
+
+#: The support commitment behind every command — one authority for it, read by
+#: `--help`, by the README command table and by the user guide.
+#:
+#: A tier is a **stability** promise, never a value ranking. `posture` is the most
+#: differentiated capability in the product *and* it is experimental: its shape can
+#: still change under a minor, so nobody should gate a pipeline on it yet. Those are
+#: two facts, and collapsing them onto one axis is how a surface starts lying — the
+#: first panel of `--help` still says "start here" for the commands worth learning
+#: first, and this table says what each command's output is worth relying on.
+#:
+#: This is not the pricing tier: Free/Pro is a separate axis (docs/PRODUCT_TIERS.md)
+#: and gates repository size, never capability.
+#:
+#: Assigning the tiers is a later milestone's work (commands moving between them,
+#: `parked` disappearing from the default help). Naming them is what ships here, so
+#: the vocabulary exists before it is used against a command.
+COMMAND_TIERS: "tuple[tuple[str, str, tuple[str, ...]], ...]" = (
+    ("core", "contract stable within a major — safe to gate CI on", (
+        "endpoints", "spring-audit", "migrate-check",
+        "impact", "impact-chain", "pr-impact", "verify",
+    )),
+    ("supported", "maintained; fields are added, never removed without a major", (
+        "verify-edit", "review-pr", "plan", "compare", "delta", "contract-diff",
+        "fix-bug", "rename-class", "prepare-context", "onboard", "explain",
+        "export", "repo-ir", "validation", "modernize", "chunk-file",
+        "cold-start", "baseline", "activate", "config", "schema", "version",
+        "cache", "auth", "mcp", "telemetry",
+    )),
+    ("experimental", "shape may change in a minor — do not gate CI on it", (
+        "posture", "archetype", "retrieve",
+    )),
+    ("parked", "kept working, no longer developed", ()),
+)
+
+#: Tiers whose membership is short enough to name in `--help`. `supported` is the
+#: remainder by construction, and printing twenty-six names would bury the two lists
+#: a reader acts on.
+_TIERS_NAMED_IN_HELP = ("core", "experimental", "parked")
+
+
+def command_tier(name: str) -> "str | None":
+    """The tier of a registered command, or None when it is in no tier.
+
+    None is a defect, not a state: the battery fails on it. It is returned rather
+    than defaulted so an unassigned command can never be silently published as
+    `supported`.
+    """
+    for tier, _promise, members in COMMAND_TIERS:
+        if name in members:
+            return tier
+    return None
+
+
+def _tier_help_block() -> str:
+    """The tier table as `--help` prints it — generated from `COMMAND_TIERS`, because
+    a hand-written catalogue beside a generated one drifts (it is what left
+    `endpoints` unlisted while it shipped)."""
+    import textwrap
+
+    lines = ["[bold]Command tiers[/bold] [dim](a stability promise, not a value ranking):[/dim]"]
+    indent = " " * 4
+    for tier, promise, members in COMMAND_TIERS:
+        if tier not in _TIERS_NAMED_IN_HELP:
+            listed = "every other command in the panels below"
+        elif members:
+            listed = " · ".join(members)
+        else:
+            listed = "none today"
+        lines.append(f"  [bold]{tier:<14}[/bold]{promise}")
+        # Pre-wrapped so the renderer never breaks a command name at its hyphen.
+        wrapped = textwrap.fill(
+            listed, width=70, initial_indent=indent, subsequent_indent=indent,
+            break_on_hyphens=False, break_long_words=False,
+        )
+        lines.append(f"[dim]{wrapped}[/dim]")
+    return "\n".join(lines)
+
+
 def _build_help_text() -> str:
     """Build --help text dynamically based on current license state."""
     try:
@@ -170,10 +252,30 @@ 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]
+
+{_tier_help_block()}
 
 [bold]Auth commands:[/bold]
   auth status                  [dim]# show current plan and auth state[/dim]
@@ -181,14 +283,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]
@@ -808,7 +913,7 @@ try:
 except Exception:
     pass
 
-telemetry_app = typer.Typer(help="Manage anonymous telemetry (on by default; opt-out).", rich_markup_mode="rich")
+telemetry_app = typer.Typer(help="Manage anonymous telemetry (off by default; opt-in).", rich_markup_mode="rich")
 app.add_typer(telemetry_app, name="telemetry")
 
 mcp_app = typer.Typer(help="MCP integration: setup, status, serve, remove.", rich_markup_mode="rich")
@@ -836,8 +941,9 @@ app.add_typer(retrieve_app, name="retrieve")
 def _maybe_show_telemetry_notice() -> None:
     """Show first-run telemetry notice once, on interactive TTYs only.
 
-    Telemetry is on by default (opt-out). We inform rather than ask, then
-    mark the notice as shown so it appears only once.
+    Telemetry is off by default (opt-in). The notice is an invitation, not a
+    disclosure: nothing has been collected when it appears. Marked as shown so it
+    appears only once.
     """
     try:
         from sourcecode.telemetry.config import has_been_asked, mark_asked
@@ -1678,12 +1784,21 @@ def main(
                 f"ex={_excl_key},depth={effective_depth}"
             )
             _core_h = _hashlib.sha256(_core_flags_str.encode()).hexdigest()[:8]
-            if _git_sha and _git_root_str:
-                _core_key = f"{_git_sha}-{_core_h}"
+            # Freshness comes from ONE authority (cache.worktree_signature): the exact
+            # tree state an analysis would read, not the committed HEAD. Keyed on HEAD,
+            # this cache answered for a tree it had not read — an uncommitted pom.xml
+            # gaining a dependency was served the pre-edit analysis with is_stale:false.
+            # Clean tree → the sha, so the ordinary repeat run still hits.
+            _tree_sig = _cache_mod.worktree_signature(
+                Path(_git_root_str) if _git_root_str else target,
+                scope=target,
+            )
+            if _tree_sig:
+                _core_key = f"{_tree_sig}-{_core_h}"
             else:
-                # No git history (untracked/no-commit repo) — stable synthetic key
-                # scoped per repo path via cache_dir(); invalidated by --no-cache or cache clear.
-                _core_key = f"nogit-{_core_h}"
+                # The tree cannot be described (no git, unreadable) — a stable synthetic
+                # key would answer forever from the first run, so skip the cache instead.
+                _core_key = ""
 
             # ── View flags: output presentation only (no re-analysis needed) ──
             _view_flags_str = (
@@ -1698,7 +1813,7 @@ def main(
 
             # ── Lookup ──────────────────────────────────────────────────────
             # Step 1: try L1 to obtain the core_hash needed for L2 key
-            _l1_result = _cache_mod.read_core(target, _core_key)
+            _l1_result = _cache_mod.read_core(target, _core_key) if _core_key else None
 
             # Additive overlays (--env-map / --git-context) miss L1 because they sit in
             # the core key, yet neither changes the semantic core — env walks config
@@ -1714,8 +1829,8 @@ def main(
             # we inject exactly the overlays we flipped to land the hit.
             _l1_needs_env_inject = False
             _l1_needs_git_inject = False
-            if _l1_result is None and (env_map or git_context):
-                _sha_prefix = _git_sha if _git_sha else "nogit"
+            if _l1_result is None and _core_key and (env_map or git_context):
+                _sha_prefix = _tree_sig
                 _flippable = []
                 if git_context:
                     _flippable.append("gc")   # inject git is cheap + additive
@@ -3271,10 +3386,11 @@ def prepare_context_cmd(
     from dataclasses import asdict
     import time as _time
 
-    # Task-level cache: keyed on (task, git_head, symptom) so warm calls complete in <1s.
+    # Task-level cache: keyed on (task, tree state, symptom) so warm calls complete in <1s.
+    # The tree state comes from the same authority as every other layer, so an
+    # uncommitted edit invalidates here exactly as it does for the root command.
     # Skip for diff-dependent tasks (delta, review-pr), fast mode, and llm_prompt
     # (those embed per-call content that must not be served from cache).
-    import subprocess as _pctx_sub
     import hashlib as _pctx_hash
     from sourcecode import cache as _pctx_cache
     _pctx_git_sha = ""
@@ -3282,15 +3398,19 @@ def prepare_context_cmd(
     _pctx_cacheable = task not in ("delta", "review-pr") and not fast and not llm_prompt
     if _pctx_cacheable:
         try:
-            _sha_r2 = _pctx_sub.run(
-                ["git", "-C", str(target), "rev-parse", "--short", "HEAD"],
-                capture_output=True, text=True, timeout=3,
+            _pctx_git_sha = _pctx_cache.worktree_signature(
+                _resolve_repo_root(target), scope=target
             )
-            _pctx_git_sha = _sha_r2.stdout.strip()
         except Exception:
             pass
         if _pctx_git_sha:
-            _sym_h = _pctx_hash.sha256((symptom or "").encode()).hexdigest()[:8]
+            # Every option that changes the answer belongs in the key. --all and
+            # --include-config did not, and went unnoticed only because the key
+            # required a git sha: in a non-git tree nothing was cached at all, so
+            # the collision could not surface.
+            _sym_h = _pctx_hash.sha256(
+                f"sym={symptom or ''};all={all_gaps};cfg={include_config}".encode()
+            ).hexdigest()[:8]
             _pctx_cache_key = f"pctx-{task}-{_pctx_git_sha}-{_sym_h}-{format or 'json'}"
             _cached_pctx = _pctx_cache.read(target, _pctx_cache_key)
             if _cached_pctx is not None:
@@ -3722,16 +3842,22 @@ def prepare_context_cmd(
 @telemetry_app.command("status")
 def telemetry_status() -> None:
     """Show current telemetry setting."""
-    from sourcecode.telemetry.config import config_file_path, has_been_asked, is_enabled
+    from sourcecode.telemetry.config import config_file_path, is_enabled, stored_choice
     enabled = is_enabled()
-    asked = has_been_asked()
+    choice = stored_choice()
     status = "enabled" if enabled else "disabled"
-    typer.echo(f"Telemetry: {status} (on by default; opt-out)")
-    if not asked:
-        typer.echo("  (first-run notice not yet shown — will show on next run)")
+    typer.echo(f"Telemetry: {status} (off by default; opt-in)")
+    # "off because you said so" and "off because nobody asked you" are different
+    # answers, and a buyer auditing this needs to be told which one they have.
+    if choice is None:
+        typer.echo("  No choice recorded — nothing has been collected or sent.")
+    else:
+        typer.echo(f"  Your recorded choice: {'enabled' if choice else 'disabled'}.")
     typer.echo(f"  Config: {config_file_path()}")
-    typer.echo("  Disable: ask telemetry disable")
-    typer.echo("  Or set env var: SOURCECODE_TELEMETRY=0  (or DO_NOT_TRACK=1)")
+    if enabled:
+        typer.echo("  Disable: ask telemetry disable  (or SOURCECODE_TELEMETRY=0, DO_NOT_TRACK=1)")
+    else:
+        typer.echo("  Enable:  ask telemetry enable   (or SOURCECODE_TELEMETRY=1)")
 
 
 @telemetry_app.command("enable")
@@ -3753,7 +3879,7 @@ def telemetry_disable() -> None:
     from sourcecode.telemetry.config import set_enabled
     set_enabled(False)
     typer.echo("Telemetry disabled. No data will be collected or sent.")
-    typer.echo("Telemetry is on by default; this opt-out is remembered.")
+    typer.echo("Telemetry is off by default; this choice is recorded so the notice stops asking.")
     typer.echo("Re-enable at any time: ask telemetry enable")
 
 
@@ -4332,6 +4458,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 +4471,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 +4486,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 +5953,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 +7469,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 +7504,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 +7514,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 +7584,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 +7709,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 +7758,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 +7786,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 +7837,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 +8190,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 +8217,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,
         )
@@ -8202,7 +8277,7 @@ def config_cmd() -> None:
     from sourcecode.telemetry.config import config_file_path, is_enabled
     typer.echo(f"ask {__version__}")
     typer.echo(f"Config:    {config_file_path()}")
-    typer.echo(f"Telemetry: {'enabled' if is_enabled() else 'disabled'}")
+    typer.echo(f"Telemetry: {'enabled' if is_enabled() else 'disabled'} (off by default; opt-in)")
     typer.echo("")
     typer.echo("Manage telemetry:")
     typer.echo("  ask telemetry enable")
@@ -9330,17 +9405,32 @@ def cache_warm_cmd(
 ) -> None:
     """Pre-populate the cache by running a fresh analysis.
 
-    Runs a full analysis to populate L1/L2 caches and rebuild the RIS
-    (Repository Intelligence Snapshot). Useful after a merge/pull in CI.
+    Runs a full analysis to populate the snapshot cache, rebuild the RIS and build
+    the shared Canonical IR. Useful after a merge/pull in CI.
+
+    \b
+    It is not a general warm, and it says so when it finishes: it warms the
+    compact view (add --agent for the agent view), and analysis flags that change
+    what is analysed — --env-map, --depth N, --exclude — rescan anyway. Run
+    `ask cache model` for what a warm gives each command.
+
+    \b
+    In CI without a persisted cache directory, every pipeline pays the cold cost
+    this command reports. Cache ~/.sourcecode/cache and ~/.sourcecode between jobs,
+    or budget the cold run explicitly.
     """
     import shutil as _shutil
     import subprocess as _sub
+    import time as _warm_time
     # Warm exactly the path given. Resolving up to the enclosing git root warmed
     # (and reported on) the whole monorepo when asked for one module — every other
     # command scopes to the argument, so `cache warm ./service-a` populated a cache
     # for a different target than `ask ./service-a` reads.
     target = Path(path).resolve()
     _git_root = _resolve_repo_root(Path(path))
+    # Cost is reported for the whole warm, the CIR build included — that is what a
+    # pipeline pays, and quoting only the analysis half would understate it (C4-5).
+    _warm_t0 = _warm_time.monotonic()
     typer.echo(f"Warming cache for {target} …", err=True)
     if _git_root != target:
         typer.echo(
@@ -9375,6 +9465,58 @@ def cache_warm_cmd(
             err=True,
         )
 
+    # A warm that reports only what it built lets the reader assume it built
+    # everything — which is how "el warm no es un warm general" became a field
+    # finding (C4-3) rather than a documented limit. State both halves, and state
+    # the cost, because in CI it is paid per pipeline (C4-5).
+    _warm_elapsed = _warm_time.monotonic() - _warm_t0
+    _warmed_view = "compact + agent views" if (compact and agent) else (
+        "agent view" if agent else "compact view"
+    )
+    typer.echo(
+        f"Warmed in {_warm_elapsed:.0f}s: {_warmed_view}, RIS, shared CIR, parse cache.",
+        err=True,
+    )
+    typer.echo(
+        "NOT warmed: prepare-context task answers (refactor / fix-bug / generate-tests / "
+        "delta / review-pr), and any run whose analysis flags differ (--env-map, --depth N, "
+        "--exclude) — those rescan. Measured: `endpoints` and `migrate-check` gain nothing "
+        "from a warm. `ask cache model` says what a warm gives each command.",
+        err=True,
+    )
+    typer.echo(
+        f"In CI without a persisted ~/.sourcecode, every pipeline pays this {_warm_elapsed:.0f}s again.",
+        err=True,
+    )
+
+
+@cache_app.command("model")
+def cache_model_cmd(
+    json_output: bool = typer.Option(False, "--json", help="Output as JSON."),
+    markdown: bool = typer.Option(False, "--markdown", help="Output the tables published in the user guide."),
+) -> None:
+    """What each cache layer stores, what invalidates it, and what a warm helps.
+
+    \b
+    Answers, per command, the question a warm raises: will this be fast next time?
+      the answer      — a warm stores what this command returns
+      the shared work — a warm removes the Java parse / the shared IR; the command
+                        still computes its own answer
+      nothing         — a warm does not touch it
+
+    One rule covers invalidation: every layer keys on the exact tree state, so any
+    change to the analysed files invalidates it, committed or not.
+    """
+    from sourcecode import cache_model as _cmodel
+
+    if json_output:
+        import json as _j
+        typer.echo(_j.dumps(_cmodel.as_dict(), indent=2, ensure_ascii=False))
+    elif markdown:
+        typer.echo(_cmodel.render_markdown())
+    else:
+        typer.echo(_cmodel.render_text())
+
 
 @cache_app.command("freshness")
 def cache_freshness_cmd(
@@ -9516,6 +9658,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).