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

sourcecode/audit_report.py

@@ -0,0 +1,158 @@
+"""Signed audit report over existing ASK evidence.
+
+This module packages facts other commands already publish. It does not score ROI,
+choose a fix, or introduce a second judgement layer: the report summary is a
+reader-friendly index over the embedded evidence blocks.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+from sourcecode import __version__
+
+AUDIT_REPORT_SCHEMA = "audit-report-v1"
+
+
+def _canonical_json(data: dict[str, Any]) -> bytes:
+    return json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+def _sign(payload: dict[str, Any], key: bytes) -> dict[str, str]:
+    canonical = _canonical_json(payload)
+    return {
+        "algorithm": "hmac-sha256",
+        "payload_sha256": hashlib.sha256(canonical).hexdigest(),
+        "key_id": hashlib.sha256(key).hexdigest()[:12],
+        "signature": hmac.new(key, canonical, hashlib.sha256).hexdigest(),
+    }
+
+
+def build_audit_report(
+    root: Path,
+    *,
+    profiles: Optional[set[str]] = None,
+    sign_key: Optional[bytes] = None,
+    risk_limit: int = 10,
+) -> dict[str, Any]:
+    """Build the buyer-readable audit bundle from existing command payloads."""
+    from sourcecode.posture import build_posture
+    from sourcecode.risk import build_risk
+
+    root = Path(root).resolve()
+    risk = build_risk(root, limit=risk_limit, min_band="low", profiles=profiles)
+    posture = build_posture(root, profiles or set())
+    top_risks = risk.get("risks", [])[:risk_limit]
+    access = ((posture.get("endpoints") or {}).get("effective_access") or {})
+
+    unsigned: dict[str, Any] = {
+        "schema_version": AUDIT_REPORT_SCHEMA,
+        "tool": {"name": "ask", "version": __version__},
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "repository": {"path": str(root)},
+        **({"profile_set": sorted(profiles)} if profiles else {}),
+        "summary": {
+            "risk_model": risk.get("model"),
+            "total_defects": risk.get("total_defects"),
+            "total_findings": risk.get("total_findings"),
+            "risk_bands": risk.get("by_band", {}),
+            "top_risks_shown": len(top_risks),
+            "endpoint_access": access.get("summary", {}),
+            "unresolved_beans": len(posture.get("unresolved") or []),
+        },
+        "top_risks": top_risks,
+        "evidence": {
+            "risk": risk,
+            "posture": posture,
+        },
+        "limits": {
+            "statement": (
+                "This report packages existing ASK evidence. It does not certify "
+                "compliance, choose fixes, assign ROI, or replace a human audit decision."
+            ),
+            "non_coverage": (risk.get("non_coverage") or {}).get("items", []),
+        },
+    }
+    from sourcecode.provenance import build_evidence_manifest
+    unsigned["evidence_manifest"] = build_evidence_manifest(
+        unsigned,
+        command="audit-report",
+        root=root,
+        inputs={
+            "profiles": sorted(profiles) if profiles else None,
+            "risk_limit": risk_limit,
+            "signed": bool(sign_key),
+        },
+    )
+    # Sign and publish the same JSON-normalized material. Some embedded evidence
+    # may contain tuples or other JSON-coercible values; normalizing before signing
+    # avoids a signature over an in-memory shape the user never receives.
+    normalized = json.loads(_canonical_json(unsigned).decode("utf-8"))
+    if sign_key:
+        normalized["signature"] = _sign(normalized, sign_key)
+    return normalized
+
+
+def render_markdown(report: dict[str, Any]) -> str:
+    """Human report renderer over the JSON contract."""
+    summary = report.get("summary") or {}
+    repo = (report.get("repository") or {}).get("path", "")
+    profile = ", ".join(report.get("profile_set") or []) or "default"
+    lines = [
+        "# ASK Audit Report",
+        "",
+        f"- Repository: `{repo}`",
+        f"- ASK version: `{(report.get('tool') or {}).get('version', '')}`",
+        f"- Profile set: `{profile}`",
+        f"- Total defects: `{summary.get('total_defects')}`",
+        f"- Risk bands: `{summary.get('risk_bands')}`",
+        f"- Endpoint access: `{summary.get('endpoint_access')}`",
+        "",
+        "## Top Risks",
+        "",
+    ]
+    risks = report.get("top_risks") or []
+    if not risks:
+        lines.append("No composed risks were reported.")
+    else:
+        lines.extend([
+            "| Band | Score | Rules | File | Line | Title |",
+            "|---|---:|---|---|---:|---|",
+        ])
+        for row in risks:
+            rules = ", ".join(str(r) for r in row.get("rule_ids", []))
+            lines.append(
+                "| "
+                + " | ".join([
+                    str(row.get("band", "")),
+                    str(row.get("severity_effective", "")),
+                    rules,
+                    str(row.get("source_file", "")),
+                    str(row.get("first_line", "")),
+                    str(row.get("title", "")).replace("|", "\\|"),
+                ])
+                + " |"
+            )
+    lines.extend([
+        "",
+        "## Limits",
+        "",
+        str((report.get("limits") or {}).get("statement", "")),
+    ])
+    signature = report.get("signature")
+    if isinstance(signature, dict):
+        lines.extend([
+            "",
+            "## Signature",
+            "",
+            f"- Algorithm: `{signature.get('algorithm')}`",
+            f"- Payload SHA-256: `{signature.get('payload_sha256')}`",
+            f"- Key ID: `{signature.get('key_id')}`",
+            f"- Signature: `{signature.get('signature')}`",
+        ])
+    return "\n".join(lines) + "\n"

sourcecode/cli.py

@@ -184,7 +184,8 @@ COMMAND_TIERS: "tuple[tuple[str, str, tuple[str, ...]], ...]" = (
         "cache", "auth", "mcp", "telemetry",
     )),
     ("experimental", "shape may change in a minor — do not gate CI on it", (
-        "risk", "enrich", "data-exposure", "migrate-recipe", "posture", "archetype",
+        "risk", "enrich", "audit-report", "data-exposure", "migrate-recipe",
+        "posture", "archetype",
     )),
     # `retrieve` publishes 15+ intents whose answers the other commands already
     # give better: measured on the battery, `security-surface` merely re-states
@@ -332,7 +333,7 @@ def _build_help_text() -> str:
         plan_badge = "[yellow]Free[/yellow]  ·  [dim]ask activate <key>[/dim] to unlock Pro"
 
     text = f"""\
-[bold]ASK Engine[/bold]  [dim]· CLI: ask[/dim]   {plan_badge}
+[bold]ASK Engine {__version__}[/bold]  [dim]· CLI: ask[/dim]   {plan_badge}
 
 Deterministic Java/Spring semantics and reusable structural context for AI coding agents.
 
@@ -344,7 +345,7 @@ of files) in minutes. Semantic analysis itself is sub-second; repo indexing domi
   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]
+  migrate-check . --compact    [dim]# Boot 2→3 + Java LTS/licensing inventory[/dim]
   risk .                       [dim]# defects ranked by reach × access (exp.)[/dim]
 
 {_remedy_help_block()}
@@ -359,6 +360,7 @@ of files) in minutes. Semantic analysis itself is sub-second; repo indexing domi
   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]
+  audit-report . --format markdown [dim]# signed human evidence bundle (exp.)[/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]
@@ -3873,6 +3875,11 @@ def prepare_context_cmd(
       ask prepare-context review-pr . --since main --output review.json
       ask prepare-context onboard --llm-prompt
       ask prepare-context --task-help
+
+    \b
+    Provenance:
+      JSON output includes evidence_manifest: claim IDs for context files and
+      source-backed rows, plus command inputs, ASK version, git HEAD and freshness.
     """
     from sourcecode.prepare_context import TASKS, TaskContextBuilder
 
@@ -4417,6 +4424,20 @@ def prepare_context_cmd(
             _skipped.append("test_gap_discovery")
         out["skipped_analyzers"] = _skipped
 
+    from sourcecode.provenance import build_evidence_manifest as _build_evidence_manifest
+    out["evidence_manifest"] = _build_evidence_manifest(
+        out,
+        command="prepare-context",
+        root=target,
+        inputs={
+            "task": task,
+            "since": since,
+            "format": format or "json",
+            "fast": fast,
+            "llm_prompt": llm_prompt,
+        },
+    )
+
     # P0-1: Apply output budget per task — safety net for large repos.
     _pc_budget = _prepare_context_budget(task)
 
@@ -6908,6 +6929,73 @@ def _render_risk_table(
     return "\n".join(lines)
 
 
+def _render_enrich_table(
+    data: dict[str, Any],
+    *,
+    rule_filter: Optional[str],
+    band_filter: Optional[str],
+    top_n: int,
+) -> str:
+    """Render SARIF-enriched findings as a bounded human triage table."""
+    rule = (rule_filter or "").strip().upper()
+    band = (band_filter or "").strip().lower()
+    rows = []
+    for row in data.get("findings", []):
+        if not isinstance(row, dict):
+            continue
+        external = row.get("external", {}) if isinstance(row.get("external"), dict) else {}
+        rule_id = str(external.get("rule_id") or ",".join(str(r) for r in row.get("rule_ids", [])))
+        if rule and rule != rule_id.upper():
+            continue
+        if band and str(row.get("band", "")).lower() != band:
+            continue
+        rows.append(row)
+    total = len(rows)
+    if top_n > 0:
+        rows = rows[:top_n]
+
+    def _cell(value: object, width: int) -> str:
+        text = "" if value is None else str(value)
+        text = text.replace("\n", " ")
+        if len(text) > width:
+            text = text[: max(0, width - 1)] + "..."
+        return text
+
+    lines = [
+        (
+            f"Enriched findings table: showing {len(rows)}/{total} finding(s)"
+            f"{' (rule=' + rule + ')' if rule else ''}"
+            f"{' (band=' + band + ')' if band else ''}"
+            f"{' (top-n=' + str(top_n) + ')' if top_n > 0 else ''}"
+        )
+    ]
+    if not rows:
+        lines.append("No matching enriched findings.")
+        return "\n".join(lines)
+
+    headers = ("band", "score", "tool", "rule", "reach", "auth", "file", "line", "title")
+    widths = (8, 7, 12, 18, 7, 14, 34, 6, 48)
+    lines.append(" | ".join(_cell(h, w).ljust(w) for h, w in zip(headers, widths)))
+    lines.append("-+-".join("-" * w for w in widths))
+    for row in rows:
+        factors = row.get("factors", {}) if isinstance(row.get("factors"), dict) else {}
+        auth = factors.get("auth_verdict", {}) if isinstance(factors.get("auth_verdict"), dict) else {}
+        external = row.get("external", {}) if isinstance(row.get("external"), dict) else {}
+        values = (
+            row.get("band", ""),
+            row.get("severity_effective", ""),
+            external.get("tool", ""),
+            external.get("rule_id", ""),
+            row.get("endpoints_reached", ""),
+            auth.get("value", ""),
+            row.get("source_file", ""),
+            row.get("first_line", "-"),
+            row.get("title", ""),
+        )
+        lines.append(" | ".join(_cell(v, w).ljust(w) for v, w in zip(values, widths)))
+    return "\n".join(lines)
+
+
 def _render_migrate_check_table(
     data: dict[str, Any],
     *,
@@ -7668,9 +7756,10 @@ def risk_cmd(
     it, and every row publishes every factor with the authority each came from, so
     a reader can disagree with one and keep the rest. An axis that could not be
     measured is `unknown`, multiplies by 1.0, and is named in `blind_axes`. The
-    two input-path axes — a query built by concatenation, a route accepting an
-    unconstrained body — are adjacencies: no dataflow is followed (NC-001, in the
-    payload's `non_coverage`).
+    input-path axes are bounded: a query may be merely concatenated, or may carry
+    an annotated HTTP input through positional calls to a known query sink; a
+    reached route may accept an unconstrained body. General taint is still NC-001,
+    in the payload's `non_coverage`.
 
     \b
     One row is one **defect** — the same identity `spring-audit` groups by, so the
@@ -7758,6 +7847,28 @@ def enrich_cmd(
     limit: int = typer.Option(
         50, "--limit", help="How many enriched findings to publish (highest first)."
     ),
+    table: bool = typer.Option(
+        False,
+        "--table",
+        help="Render a human table instead of JSON/YAML. Use with --rule, --band and --top-n.",
+    ),
+    rule_filter: Optional[str] = typer.Option(
+        None,
+        "--rule",
+        "--only",
+        help="With --table, show only enriched findings from one external rule id.",
+    ),
+    band_filter: Optional[str] = typer.Option(
+        None,
+        "--band",
+        help="With --table, show only one composed band: critical | high | medium | low.",
+    ),
+    top_n: int = typer.Option(
+        0,
+        "--top-n",
+        min=0,
+        help="With --table, show only the top N findings after filtering. 0 means all.",
+    ),
     min_band: str = typer.Option(
         "low",
         "--min-band",
@@ -7779,9 +7890,10 @@ def enrich_cmd(
 
     \b
     This product does not detect injection, CVEs or secrets, and says so in every
-    security payload (NC-001, NC-002). A scanner that does has no bean graph, no
-    profile model and no endpoint id it shares with anything, so its output is a
-    list nobody can order. `enrich` reads that list and answers the question the
+    security payload (NC-001, NC-002). `risk` contributes one bounded HTTP-input
+    to query-sink factor, not a scanner. A scanner has no bean graph, no profile
+    model and no endpoint id it shares with anything, so its output is a list
+    nobody can order. `enrich` reads that list and answers the question the
     scanner cannot: which of these findings sits in code an unauthenticated
     request reaches.
 
@@ -7813,6 +7925,7 @@ def enrich_cmd(
       ask enrich . --sarif semgrep.sarif
       ask enrich . --sarif codeql.sarif --min-band high
       ask enrich . --sarif trivy.sarif --profile prod
+      ask enrich . --sarif semgrep.sarif --table --rule java-sqli --band high --top-n 20
       ask enrich /path/to/repo --sarif trivy.sarif -o enriched.json
     """
     from sourcecode.sarif import enrich_sarif
@@ -7835,6 +7948,16 @@ def enrich_cmd(
             expected="critical|high|medium|low",
         )
         raise typer.Exit(code=1)
+    if band_filter is not None:
+        band_filter = band_filter.strip().lower()
+    if band_filter is not None and band_filter not in ("critical", "high", "medium", "low"):
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            f"--band expects critical | high | medium | low (got {band_filter!r}).",
+            hint="Example: --table --band high",
+            expected="critical|high|medium|low",
+        )
+        raise typer.Exit(code=1)
     if not Path(sarif).is_file():
         _emit_error_json(
             INVALID_INPUT_CODE,
@@ -7844,11 +7967,12 @@ def enrich_cmd(
         )
         raise typer.Exit(code=1)
 
+    enrich_limit = 100000 if table and (rule_filter or band_filter or top_n) else limit
     _prog = Progress()
     _prog.start("composing risk factors")
     try:
         data = enrich_sarif(
-            Path(sarif), path, limit=limit, min_band=min_band,
+            Path(sarif), path, limit=enrich_limit, min_band=min_band,
             profiles=_profile_set(profile),
         )
     except (ValueError, json.JSONDecodeError) as exc:
@@ -7863,8 +7987,14 @@ def enrich_cmd(
     finally:
         _prog.stop()
 
+    if table:
+        output = _render_enrich_table(
+            data, rule_filter=rule_filter, band_filter=band_filter, top_n=top_n
+        )
+    else:
+        output = _serialize_dict(data, format)
     _emit_command_output(
-        _serialize_dict(data, format),
+        output,
         output_path,
         copy,
         success_msg=(
@@ -7874,6 +8004,103 @@ def enrich_cmd(
     )
 
 
+@app.command("audit-report")
+def audit_report_cmd(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository path (default: current directory).",
+    ),
+    profile: Optional[str] = typer.Option(
+        None,
+        "--profile",
+        help="Active profile set, comma-separated (e.g. prod or prod,metrics).",
+    ),
+    sign_key: Optional[Path] = typer.Option(
+        None,
+        "--sign-key",
+        help="Sign the canonical JSON report with this local HMAC key file.",
+    ),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o", help="Write the report to a file instead of stdout."
+    ),
+    format: str = typer.Option(
+        "json", "--format", "-f", help="Output format: json, yaml or markdown."
+    ),
+    copy: bool = _copy_option(),
+) -> None:
+    """[EXPERIMENTAL] Human audit bundle over existing ASK evidence, optionally signed.
+
+    \b
+    This packages the same evidence `risk` and `posture` already publish into a
+    report a buyer can read: top risks, effective runtime posture, source-linked
+    evidence and non-coverage. It does not certify compliance, choose fixes or
+    assign ROI. JSON includes evidence_manifest: claim IDs mapped to source spans,
+    command inputs, ASK version and freshness.
+
+    \b
+    `--sign-key` adds an HMAC-SHA256 signature over the canonical JSON payload.
+    The key is local and explicit; no network trust service or new PKI is implied.
+
+    \b
+    Examples:
+      ask audit-report .
+      ask audit-report . --profile prod --format markdown
+      ask audit-report . --sign-key audit.key -o audit-report.json
+    """
+    from sourcecode.audit_report import build_audit_report, render_markdown
+
+    path = _admit_path(path)
+    fmt = format.strip().lower()
+    if fmt not in ("json", "yaml", "markdown"):
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            f"--format expects json | yaml | markdown (got {format!r}).",
+            hint="Example: ask audit-report . --format markdown",
+            expected="json|yaml|markdown",
+        )
+        raise typer.Exit(code=1)
+    key_bytes = None
+    if sign_key is not None:
+        key_path = Path(sign_key).expanduser()
+        if not key_path.is_file():
+            _emit_error_json(
+                INVALID_INPUT_CODE,
+                f"--sign-key must name a readable file (got {str(sign_key)!r}).",
+                hint="Example: ask audit-report . --sign-key audit.key",
+                expected="an existing key file",
+            )
+            raise typer.Exit(code=1)
+        key_bytes = key_path.read_bytes()
+        if not key_bytes:
+            _emit_error_json(
+                INVALID_INPUT_CODE,
+                "--sign-key file is empty; refusing to publish an unverifiable signature.",
+                hint="Write a random local secret to the key file first.",
+                expected="a non-empty key file",
+            )
+            raise typer.Exit(code=1)
+
+    _prog = Progress()
+    _prog.start("packaging audit evidence")
+    try:
+        data = build_audit_report(
+            path, profiles=_profile_set(profile), sign_key=key_bytes,
+        )
+    finally:
+        _prog.stop()
+    output = render_markdown(data) if fmt == "markdown" else _serialize_dict(data, fmt)
+    _emit_command_output(
+        output,
+        output_path,
+        copy,
+        success_msg=f"audit report written to {output_path}",
+        # A signed artifact cannot be mutated after signing. The report carries
+        # tool/version metadata itself, and `signature.payload_sha256` is over
+        # the exact JSON payload the user receives.
+        stamp_envelope=False,
+    )
+
+
 @app.command("migrate-recipe")
 def migrate_recipe_cmd(
     path: Path = typer.Argument(
@@ -8145,6 +8372,14 @@ def posture_cmd(
             "by what it leaves unauthenticated."
         ),
     ),
+    env_file: Optional[Path] = typer.Option(
+        None,
+        "--env-file",
+        help=(
+            "With --resolve-environments, read SPRING_PROFILES_ACTIVE or "
+            "spring.profiles.active from an explicit deployment env/dotenv file."
+        ),
+    ),
     property_overrides: Optional[list[str]] = typer.Option(
         None,
         "--property",
@@ -8192,6 +8427,7 @@ def posture_cmd(
       ask posture . --since origin/main --fail-on opened
       ask posture . --profile prod --property app.security.enabled=true
       ask posture . --resolve-environments
+      ask posture . --resolve-environments --env-file prod.env
     """
     from sourcecode.posture import (
         FAIL_ON_CHOICES,
@@ -8266,6 +8502,14 @@ def posture_cmd(
             hint="ask posture . --profile prod --diff-ref origin/main:HEAD",
         )
         raise typer.Exit(code=1)
+    if env_file and not resolve_environments_flag:
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            "--env-file supplies deployment evidence for --resolve-environments; it cannot "
+            "be used with a single profile, profile diff or ref comparison.",
+            hint="ask posture . --resolve-environments --env-file prod.env",
+        )
+        raise typer.Exit(code=1)
 
     # One spinner over the whole dispatch: every branch below resolves the
     # conditional bean graph, and `--diff-ref` resolves it twice (once per ref).
@@ -8280,10 +8524,26 @@ def posture_cmd(
                     INVALID_INPUT_CODE,
                     "--resolve-environments answers which profile set runs; it cannot be "
                     "combined with --profile, --diff or --diff-ref/--since, which state one.",
-                    hint="Run `ask posture . --resolve-environments` on its own.",
+                    hint="Run `ask posture . --resolve-environments` on its own, or add "
+                         "`--env-file prod.env` as deployment evidence.",
                 )
                 raise typer.Exit(code=1)
-            data = resolve_environments(path, overrides)
+            deployment_signals = None
+            if env_file is not None:
+                from sourcecode.environment_resolution import collect_env_file_signals
+
+                env_path = Path(env_file).expanduser()
+                if not env_path.is_file():
+                    _emit_error_json(
+                        INVALID_INPUT_CODE,
+                        f"--env-file must name a readable file (got {str(env_file)!r}).",
+                        hint="ask posture . --resolve-environments --env-file prod.env",
+                    )
+                    raise typer.Exit(code=1)
+                deployment_signals = collect_env_file_signals(env_path, root=path)
+            data = resolve_environments(
+                path, overrides, deployment_signals=deployment_signals,
+            )
         elif ref_comparison:
             from sourcecode.git_checkout import RefError
 
@@ -8484,9 +8744,9 @@ def migrate_check_cmd(
         None,
         "--target-jdk",
         help=(
-            "The JDK you are actually moving to (e.g. 11, 17, 21). Rules for a "
-            "later JDK are not your blockers and are not reported. Without it, "
-            "every JDK axis is reported at once."
+            "The JDK you are actually moving to (e.g. 11, 17, 21, 25). Rules "
+            "for a later JDK are not your blockers and are not reported. Also "
+            "sets java_lts_inventory.target_lts."
         ),
     ),
     keep_boot: bool = typer.Option(
@@ -8546,7 +8806,7 @@ def migrate_check_cmd(
         help="Caller BFS depth for --blast-radius (1-8, default: 4).",
     ),
 ) -> None:
-    """Spring Boot 2→3 migration readiness: detect javax→jakarta namespace blockers.
+    """Spring Boot 2→3 migration readiness + Java LTS/licensing inventory.
 
     \b
     Detects:
@@ -8575,6 +8835,7 @@ def migrate_check_cmd(
       ask migrate-check . --compact          bounded decision summary
       ask migrate-check /path/to/repo --format text
       ask migrate-check . --min-severity high
+      ask migrate-check . --target-jdk 25       Java LTS target inventory
       ask migrate-check . --table --rule MIG-001 --band critical --top-n 20
       ask migrate-check . --output migration.json
       ask migrate-check . --snapshot --ref sprint-12   persist a readiness point
@@ -8597,6 +8858,13 @@ def migrate_check_cmd(
       <repo>/.ask/readiness-history). --trend reads that series and reports
       first→last movement — no improving/degrading label, and readiness_score is
       flagged not-comparable when the applicable dimension set changed.
+
+    \b
+    Java LTS/licensing inventory:
+      The JSON report includes java_lts_inventory: Java 8/11/17/21/25 evidence
+      from Maven/Gradle, local runtime hints and container files; target-LTS
+      blockers; and explicit Oracle JDK/licensing-review signals. This is
+      inventory evidence, not legal advice, and it never changes readiness_score.
     """
     from sourcecode.repository_ir import find_java_files
     from sourcecode.migrate_check import run_migrate_check
@@ -11913,7 +12181,8 @@ HELP_PANELS: "tuple[tuple[str, tuple[str, ...]], ...]" = (
         "cache", "auth", "mcp", "telemetry", "baseline",
     )),
     ("Experimental — shape may change", (
-        "risk", "enrich", "data-exposure", "migrate-recipe", "archetype", "retrieve",
+        "risk", "enrich", "audit-report", "data-exposure", "migrate-recipe",
+        "archetype", "retrieve",
     )),
 )