sourcecode 3.5.0__tar.gz → 3.6.0__tar.gz

{sourcecode-3.5.0 → sourcecode-3.6.0}/CHANGELOG.md

@@ -1,5 +1,171 @@
 # Changelog
 
+## [3.6.0] — 2026-08-01
+
+**The P0 block and the C1/C2 backlog.** Nine rows closed, three closed by measurement alone
+(C1-17, C2-11, and C2-12 as stated did not reproduce). `migrate-check` stops billing work a
+declared dependency already did, stops billing a Hibernate rewrite to another vendor's provider,
+and stops assuming a single destination — `--target-jdk 11 --keep-boot` takes MIG-001 from 85 to 0
+on openmrs-core.
+
+Two patterns from 3.5.0 repeat, and both are worth carrying forward. **The reported symptom keeps
+being narrower than the defect**: C1-10 was one rule and was also an evidence rule admitting JPA as
+proof of Hibernate; C2-1 was a `why` trail and was also the ranking key underneath it. **And a
+curated list beside real data keeps being the cause** — C2-3's trim schedule named sections the
+payload does not have while the weight sat in two it never mentions, the third appearance of the
+C4-1 shape in two releases.
+
+**Minor, not patch**: blocking counts move (C1-10), reach-derived counts become nullable (C1-13),
+`compare`'s ranking can move (C2-1), `migrate-check.findings` keeps one type across `--compact`
+(C2-10), and two commands that wrote their confirmation to stderr now write it to stdout (C3-18).
+
+### Added
+
+- **`migrate-check --target-jdk N` and `--keep-boot`** (C1-15, P0 gate 2). Asked about a JDK move,
+  the answer was `headline_blocker: boot3_migration` with fix hints sending a developer to migrate
+  481 `javax.persistence` imports they never planned to touch; nothing could say "JDK 11, keep Boot
+  2.7". The route is filtered over the `migration_target` vocabulary every rule already carried.
+  Measured on openmrs-core with `--target-jdk 11 --keep-boot`: **MIG-001 85 → 0**, blocking 114 → 0,
+  headline `hibernate_rewrite` → `none_applicable`. Narrowing is not silencing — `metadata.route`
+  publishes the target and every excluded axis, and a `limitations` entry states what was left out
+  and that it is unresolved, not fixed. **The default is unchanged**: no flags means every axis at
+  once.
+
+- **`spring-audit` findings carry `first_line`** (C2-4), from the `SourceSpan` index the IR already
+  records. `null` where the symbol has no recorded span, never 0.
+
+### Changed
+
+- **`migrate-check` reconciles findings with the build it already read** (C1-10, P0 gate 1,
+  **blocking counts move**). `MIG-021` fired as blocking while `javax.xml.bind:jaxb-api:2.3.1` sat
+  in the same `pom.xml`. A rule now declares the coordinates that satisfy it; a satisfied finding
+  gets `mitigated_by` and `code_context: "dependency_satisfied"`, leaving `blocking_count` exactly
+  as test scope does, and its hint stops saying "add this dependency". `satisfied_by` is empty for
+  every rule whose remedy is a source change.
+  - **The Hibernate axis now needs Hibernate evidence.** It billed 45.6 days to a repository whose
+    declared provider was EclipseLink because a bare `javax.persistence` import counted as proof —
+    that proves JPA, not Hibernate. A declared competing provider refutes the inference, and only
+    the inference: a repository carrying both coordinates keeps direct evidence. An inference from
+    a JPA import alone now reports `medium`, not `high`.
+  - Battery: `blocking_count` identical on all six repositories.
+
+- **A capped blast radius answers `unknown`, not `0`** (C1-13, **reach-derived counts become
+  nullable**). A hub capped at `depth=1` reported `endpoints_affected_count: 0` for a walk that
+  never looked. Under the cap a reach-derived zero becomes `null`, named in
+  `stats.unknown_under_cap`. A **non-zero** count under the cap stays a number — it is a floor — and
+  an **uncapped** run keeps its measured zero.
+
+- **`compare` ranks on measurements, not on rendered rows** (C1-13/C2-1, **ranking may move**).
+  Three of the seven cost fields were `len()` of a display list, so the ordering was computed over
+  however many rows the renderer had decided to show. Capped magnitudes are declared in
+  `cost_floor_fields` beside `cost`, never inside it.
+
+- **`impact.endpoints_affected[]` gains `controller_class` and `handler_symbol`** (C2-12), the names
+  `impact-chain` already uses. Grouping by controller needed a different key per command on payloads
+  one run produces. Original keys kept as aliases.
+
+- **`effort_breakdown.affected_files` is now `blocking_affected_files`** (C1-14, alias kept). It
+  named a different population from `summary.affected_files` — 264 against 265 on openmrs-core — and
+  the shared name was the whole of the contradiction. Both carry a `_basis`.
+
+### Fixed
+
+- **The payload budget cuts where the bytes are** (C2-3). `_TRIM_SCHEDULE` is a hand-written list of
+  key names: on a 1 222-file `review-pr` diff it trimmed 1 733 KB → 1 732 KB against a 97 KB budget,
+  walking to `execution_paths` while every byte sat in `changed_files` and `runtime_changes`, which
+  it does not mention. Once the schedule is exhausted the remaining cut is chosen by measuring which
+  list is largest. Measured on that payload shape: **566 KB → 71 KB**.
+
+- **`ask verify` no longer passes with zero contracts declared** (C3-15, **behaviour change for
+  pipelines**). It returned `pass` + exit 0 on a repository that declared nothing — a green light
+  for having verified nothing. `evaluate_repo` returns before it even builds the CIR when no
+  contracts exist, so no code was read and no contract was checked: the same standing as a
+  repository that could not be analysed, and now reported the same way — **`unverified`, exit 2**,
+  with the reason stated. Exit 2 and not 1 because the published contract reserves 1 for
+  violations found and 2 for a run that could not verify. Asserted under every `--fail-on` choice:
+  `never` suppresses violations from blocking, it does not turn a run that verified nothing into a
+  verified one. This is C3-22 in different clothes — there a typo in `$DIR` made the gate
+  permanently green, here a repository that never adopted contracts did.
+
+- **A command that writes its answer to a file now confirms on stdout, not stderr** (C3-18,
+  **behaviour change for scripts reading stderr**). `repo-ir`, `modernize`, `export` and
+  `cold-start` wrote the "written to" confirmation to stderr while the payload went to the file
+  and stdout stayed empty, so `ask repo-ir -o ir.json > log.txt` captured **nothing** and
+  PowerShell 5.1 raised `NativeCommandError` over a run that succeeded. Measured on
+  spring-petclinic before the fix: stdout 0 bytes, stderr 155. C3-26 set this rule in 3.5.0 for
+  `cache warm`/`cache clear`; these four were missed because the stderr battery listed its
+  commands **by hand**. The `--output` rows are now discovered from the CLI.
+
+- **Usage errors emit the JSON envelope for a pipeline** (C3-4). The interception was patched onto
+  `click.UsageError.show`, which Typer never calls when `rich_markup_mode` is set — it is, for the
+  help panels — so **no usage error had been emitting an envelope at all** and `ask <cmd>
+  --badflag` answered automation with a rich text box. Split by audience: a pipeline gets the
+  envelope, a person at a terminal keeps the `Usage:` line and the pointer to `--help`.
+
+- **A flag no longer changes the type of a key** (C2-10, **breaking for `--compact` consumers**).
+  `migrate-check.findings` was a bare array in full output and a
+  `{total, shown, omitted, items}` object under `--compact` — the same key, two types. A consumer
+  iterating `findings` broke silently on a flag it did not pass: nothing errored, the loop simply
+  ran over the four keys of a summary object instead of over the findings.
+  - `findings` is a **list in both modes**. The counts moved to a `findings_cap` sibling that
+    exists **only when a cap actually bit**, and it carries the I-8 `display_list` statement of
+    what the cut changed and what stayed exact.
+  - **Five collections had it, not one**: top-level `findings`, `hibernate.rewrite_targets`,
+    `hibernate.findings`, `hibernate.critical_call_chains`, `hibernate.golden_sql_hotspots`, and
+    `blast_radius.files`.
+  - **Half of C2-13 falls out of the same fix.** `migrate-check.findings` is now the bare array
+    `spring-audit.findings` always was — one word, one type, one parser, measured across all
+    three payloads. The `schema_version` fragmentation is the half that stays open.
+  - Enforced rather than documented: `tests/test_flag_shape_stability.py` walks both payloads key
+    by key and fails on any type that moves. The same walk covers the root command's `--compact`
+    and `--agent`, which were **measured clean** while fixing this and are locked so they stay
+    clean.
+
+- **A misplaced global flag is told where that flag lives** (C3-4). `ask spring-audit --full`
+  answered "No such option: --full" about a flag the tool does have — it is declared on the root
+  command. The flag is looked up on the root command, so every global flag typed after every
+  subcommand is covered and no flag name is written into the check; a genuinely unknown flag earns
+  no hint, asserted.
+
+- **`repo-ir` states the output cost before it is paid** (C3-18). The advisory ran after the IR was
+  built, serialized and written — the whole bill settled. It now runs off the file count before the
+  build starts, as a **band** (10.8–27.9 KB per Java file) rather than a point: the per-file cost
+  spreads 2.6× across sampled repositories with how densely the code cross-references, and
+  publishing a midpoint as one figure is the C1-12 defect. The band is asserted to bracket what
+  those repositories actually produced.
+
+- **A capped `file_relevance` list says what was cut, measured** (C3-20). The hint published the
+  *budget* as the number of files shown — on spring-petclinic, "Showing top 40/176" beside a list
+  of **25** — fired even when nothing had been cut, and advised `--full` while `--full` was active.
+  Two constraints trim the list (a visibility threshold and a per-category cap of half the budget)
+  and the sentence knew about neither. Now: nothing unless a cap really bit, the figure is what was
+  shown against the population it samples, a flag is named only when it would change the answer,
+  and the I-8 `display_list` block sits beside it.
+
+- **`--no-cache` on a subcommand says what it does** (C3-5). Six commands claimed "always reads
+  fresh source (no snapshot cache)" while `ask cache model` records them reading `ris`, `cir` and
+  `parse`. One string now, stating the reason it is a no-op: since C1-9 every layer keys on the
+  exact tree state and the parse layer is content-addressed, so there is no staleness to bypass.
+  The flag stays accepted so scripts do not break, and is real on `ask --no-cache` (root).
+
+- **`--output <file>` now returns the whole answer, which is what its own note promised**
+  (C2-2, first M8 increment). Measured on `org.broadleafcommerce.common.money.Money`: the file
+  held **30 of 134** caller classes and **50 of 1 302** indirect callers — the same sample stdout
+  gets — while the payload told the reader *"use `--output` for the full list"*.
+  - **The recorded cause was wrong, and fixing what was recorded would not have worked.** The
+    file carried no `_budget_note` at all: the caps were applied at *construction*, inside
+    `compute_blast_radius`, before any output flag was consulted. No option could have returned
+    the full list.
+  - A cap is now a **rendering** parameter (`list_limit`) and never a measurement one — every
+    `stats.*_count` is taken over the full population either way (ADR-0008 R5-R8). `--output`
+    renders unbounded; stdout keeps the sample and names the total; and the note only claims a
+    cap that actually bit, with the I-8 `display_list` effect block beside it.
+  - The output budget is skipped for a file as well. `--agent` and `--compact` already did this;
+    `impact` was the one that did not.
+  - Same rule for `impact-chain`, with one qualification: an **explicit `--limit` still wins**.
+    A default is not a request; a typed flag is (`_flag_was_given`, off Click's parameter source).
+  - The USER_GUIDE now states the rule where a reader meets it, beside the `impact` output.
+
 ## [3.5.0] — 2026-07-31
 
 **M7.7 "Robustness floor" — the axis field evaluation #5 scored 4/10.** Ten pieces, and the

{sourcecode-3.5.0 → sourcecode-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 3.5.0
+Version: 3.6.0
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm

{sourcecode-3.5.0 → sourcecode-3.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "3.5.0"
+version = "3.6.0"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-3.5.0 → sourcecode-3.6.0}/src/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.5.0"
+__version__ = "3.6.0"

{sourcecode-3.5.0 → sourcecode-3.6.0}/src/sourcecode/cli.py

@@ -857,7 +857,13 @@ def _emit_command_output(
     if output_path is not None:
         _safe_write_file(output_path, content)
         if success_msg:
-            typer.echo(success_msg, err=True)
+            # C3-26/C3-18: the payload went to the file, so stdout is free and
+            # this confirmation is the run's whole answer — `cache warm` and
+            # `cache clear` were corrected for exactly this in 3.5.0 and these
+            # three (`repo-ir`, `modernize`, `export`) were missed because the
+            # stderr battery listed its commands by hand. Measured before the
+            # fix on spring-petclinic: stdout 0 bytes, stderr 155.
+            typer.echo(success_msg)
     else:
         try:
             sys.stdout.buffer.write(content.encode("utf-8"))
@@ -874,30 +880,112 @@ def _emit_command_output(
         except AttributeError:
             sys.stdout.write(content + "\n")
         if copy and _copy_to_clipboard(content):
-            typer.echo("✓ copied to clipboard", err=True)
+            # The payload is on stdout here, so this cannot join it; it is a
+            # notice and takes the terminal gate rather than dirtying a capture.
+            _notice("✓ copied to clipboard")
 
 
 # H-06: Intercept Click-level UsageError (unknown options, bad args) and emit JSON.
 # Click's default show() writes "Error: No such option: --foo" as plain text.
 # Automation consumers need JSON on stderr regardless of how the error originated.
+def _root_level_flags() -> set[str]:
+    """Every option declared on the root command, discovered from the CLI.
+
+    Read at error time so a flag added to the root callback is covered without
+    anyone remembering to list it here — the C4-1 lesson about curated lists
+    living beside generated ones. Never raises: a failure here must not turn a
+    usage error into a traceback.
+    """
+    try:
+        import typer.main as _tm
+
+        group = _tm.get_command(app)
+        return {opt for param in group.params for opt in param.opts}
+    except Exception:
+        return set()
+
+
 try:
     import click.exceptions as _click_exc
 
+    def _misplaced_global_flag_hint(exc: Any) -> "tuple[Optional[str], Optional[str]]":
+        """(flag, hint) when a rejected option is really a root-level one.
+
+        C3-4: `ask spring-audit --full` answered "No such option: --full" about
+        a flag the tool does have — it is declared on the root command, not on
+        the subcommand, and nothing said so. Refusing is right; refusing
+        without naming where the flag lives is what cost the user the run.
+
+        The flag is looked up on the root command, so every global flag typed
+        after every subcommand is covered and no flag name is written here.
+        """
+        flag = str(
+            (getattr(exc, "option_name", None) or getattr(exc, "param_hint", None)) or ""
+        ).strip("'\"")
+        if not flag or flag not in _root_level_flags():
+            return (flag or None), None
+        cmd_path = getattr(getattr(exc, "ctx", None), "command_path", "") or ""
+        parts = cmd_path.split()
+        sub = parts[-1] if len(parts) > 1 else ""
+        hint = (
+            f"`{flag}` is a global flag: it goes before the command, "
+            f"as `ask {flag} <path>`" + (f", not after `{sub}`." if sub else ".")
+        )
+        return flag, hint
+
     def _json_click_usage_error_show(self: Any, file: Any = None) -> None:  # type: ignore[override]
         import json as _je
-        _flag = str((getattr(self, "option_name", None) or getattr(self, "param_hint", None)) or "").strip("'\"")
+        _flag, _hint = _misplaced_global_flag_hint(self)
         _context: dict[str, object] = {}
         if _flag:
             _context["flag"] = _flag
+        if _hint:
+            _context["scope"] = "root"
         payload = build_error_envelope(
             INVALID_INPUT_CODE,
             self.format_message(),
+            hint=_hint,
             **_context,
         )
         sys.stderr.write(_je.dumps(payload, ensure_ascii=False) + "\n")
         sys.stderr.flush()
 
     _click_exc.UsageError.show = _json_click_usage_error_show  # type: ignore[method-assign]
+
+    # ...and again where Typer actually goes. With `rich_markup_mode` set — it
+    # is, for the help panels — typer.core routes every ClickException to
+    # `rich_utils.rich_format_error` and *never* calls `.show()`, so the patch
+    # above was dead for this app and no usage error has been emitting the JSON
+    # envelope: `ask <cmd> --badflag` answered with a rich text box on stderr.
+    # That is the same broken contract C3-23 closed for `archetype`, reached by
+    # a different route. Patched here rather than by dropping rich mode, which
+    # would cost the C4-1/C4-2 help panels.
+    try:
+        import typer.rich_utils as _typer_rich
+
+        _rich_format_error_original = _typer_rich.rich_format_error
+
+        def _json_rich_format_error(exc: Any) -> None:
+            """JSON for a pipeline, the usage box for a person.
+
+            Audience, not preference — the same reasoning as `_notice`. A
+            consumer parses stderr and needs the envelope; a human at a
+            terminal needs the `Usage:` line and the pointer to `--help`, and
+            would get neither from JSON. Nothing is lost either way.
+            """
+            if sys.stderr.isatty():
+                _rich_format_error_original(exc)
+                # The person who mistyped the flag is exactly who needs C3-4's
+                # hint, so it follows the box rather than living only in JSON.
+                _, _hint = _misplaced_global_flag_hint(exc)
+                if _hint:
+                    typer.echo(_hint, err=True)
+            else:
+                _json_click_usage_error_show(exc)
+
+        _typer_rich.rich_format_error = _json_rich_format_error  # type: ignore[assignment]
+    except Exception:
+        pass  # rich unavailable — .show() above already covers the plain path
 except Exception:
     pass  # click unavailable — plain-text fallback
 
@@ -1081,6 +1169,64 @@ _FREE_TIER_NODE_CAP: int = 50  # graph/semantic node cap — applies only to lar
 _JAVA_MIN_SCAN_DEPTH: int = 12  # Maven src/main/java/<pkg>/<module>/File depth floor
 _LARGE_REPO_ADVISORY_FILES: int = 3000  # cold-scan advisory threshold (files); honest expectation-setting, not a speed claim
 
+#: What one Java file costs in serialized `repo-ir` output, measured across four
+#: repositories (C3-18): spring-petclinic 30 files/318 KB (10.8 KB/file),
+#: jobrunr 581/9.5 MB (16.8), openmrs-core 866/21 MB (25.2), eureka 299/8.0 MB
+#: (27.3). Kept as a band, never collapsed to a midpoint: the 2.6x spread is
+#: real — it tracks how densely the code cross-references — and a point estimate
+#: would assert a precision the sample does not support (the C1-12 rule).
+_IR_BYTES_PER_FILE_LOW: int = 10_800
+_IR_BYTES_PER_FILE_HIGH: int = 27_900
+_IR_SIZE_WARN_MB: int = 10  # advise above this; below it the write is not worth a sentence
+
+#: What `--no-cache` means on a subcommand (C3-5). The old text — "this command
+#: always reads fresh source (no snapshot cache)" — was false: `cache model`, the
+#: authority, records these commands reading the `ris`, `cir` and `parse` layers.
+#: They do skip the *snapshot* layer, which is the only thing the sentence got
+#: right, and it read as a promise about all caching.
+#:
+#: The flag is a genuine no-op here, and for a reason worth stating rather than
+#: asserting: since C1-9 every layer keys on the exact tree state and the
+#: analyzer fingerprint, and the parse layer is content-addressed, so none of
+#: them can serve an answer for code that has changed. There is no staleness for
+#: the flag to bypass. It is accepted so a script can pass it uniformly, and it
+#: is real on the root command, where the snapshot layer does store a rendered
+#: answer.
+_NO_CACHE_SUBCOMMAND_HELP = (
+    "Accepted for compatibility; a no-op here. This command's layers key on the "
+    "tree state, so none can serve a stale answer. Real on `ask --no-cache` "
+    "(root), which caches a rendered answer. See `ask cache model`."
+)
+
+
+def _ir_size_advisory_message(file_count: int) -> "Optional[str]":
+    """Return the `repo-ir` output-size advisory, or ``None`` below the threshold.
+
+    C3-18: the cost is stated *before* it is paid. The old advisory ran after
+    the IR was built and serialized — the whole bill already settled and the
+    file already on disk — so it could tell a user what they had just spent,
+    never what they were about to.
+
+    The figure is a band, not a point. Sampled across four repositories the IR
+    costs 10.8-27.9 KB per Java file, and that 2.6x spread is a real property of
+    the input (how densely the code cross-references), not sampling noise.
+    Publishing its midpoint as one number would assert a precision the sample
+    does not support — the same defect C1-12 records for migration effort — so
+    the band is published with the word "estimate" on it.
+
+    Pure and TTY-agnostic: the caller owns the terminal gate, so this never
+    reaches stdout or a pipeline (C3-26).
+    """
+    est_low_mb = file_count * _IR_BYTES_PER_FILE_LOW / (1024 * 1024)
+    est_high_mb = file_count * _IR_BYTES_PER_FILE_HIGH / (1024 * 1024)
+    if est_high_mb <= _IR_SIZE_WARN_MB:
+        return None
+    return (
+        f"[repo-ir] {file_count} files — estimated output "
+        f"{est_low_mb:.0f}-{est_high_mb:.0f}MB (estimate, not a measurement). "
+        "To spend less: --summary-only, --max-nodes N --max-edges N, or --gzip."
+    )
+
 
 def _cold_scan_advisory_message(
     file_tree: dict,
@@ -4091,6 +4237,19 @@ def repo_ir_cmd(
             )
             raise typer.Exit(code=1)
 
+    # C3-18: state the cost before paying it, not after. The old advisory fired
+    # once the IR was built AND serialized — the whole bill already paid, and the
+    # file already on disk. The estimate is a RANGE because a point would be a
+    # measurement we do not have: sampled across four repositories the IR costs
+    # 10.8-27.9 KB per Java file (petclinic 30 files/318 KB, jobrunr 581/9.5 MB,
+    # openmrs-core 866/21 MB, eureka 299/8.0 MB), a 2.6x spread that depends on
+    # how densely the code cross-references. Reporting the midpoint of that as a
+    # single figure is the C1-12 defect.
+    if output_path and not gzip_output:
+        _notice_msg = _ir_size_advisory_message(len(file_list))
+        if _notice_msg:
+            _notice(_notice_msg)
+
     _ir_phase = f"extracting IR ({len(file_list)} files)"
     if since:
         _ir_phase += f" since {since}"
@@ -4113,38 +4272,32 @@ def repo_ir_cmd(
             output_path = output_path.with_suffix(output_path.suffix + ".gz")
         raw_bytes = output.encode("utf-8")
         size_bytes = len(raw_bytes)
-        _SIZE_WARN_BYTES = 10 * 1024 * 1024  # 10MB
-        if size_bytes > _SIZE_WARN_BYTES and not gzip_output:
-            typer.echo(
-                f"[repo-ir] Output is {size_bytes // (1024 * 1024)}MB — "
-                "consider --summary-only, --max-nodes N --max-edges N, or --gzip to compress.",
-                err=True,
-            )
         if gzip_output:
             import gzip as _gzip
             with _gzip.open(output_path, "wb") as _gz:
                 _gz.write(raw_bytes)
             compressed_kb = output_path.stat().st_size // 1024
             size_kb = size_bytes // 1024
+            # C3-26: when the payload went to a file, this confirmation IS the
+            # answer of the run — the same case as `cache warm`. On stderr,
+            # `ask repo-ir -o ir.json > log.txt` captured nothing and PowerShell
+            # 5.1 raised NativeCommandError over a run that succeeded.
             typer.echo(
-                f"IR written to {output_path} ({compressed_kb}KB gzip, {size_kb}KB uncompressed)",
-                err=True,
+                f"IR written to {output_path} ({compressed_kb}KB gzip, {size_kb}KB uncompressed)"
             )
         else:
             output_path.write_bytes(raw_bytes)
             size_kb = size_bytes // 1024
             if summary_only:
                 typer.echo(
-                    f"IR written to {output_path} ({size_kb}KB, graph omitted by --summary-only)",
-                    err=True,
+                    f"IR written to {output_path} ({size_kb}KB, graph omitted by --summary-only)"
                 )
             else:
                 n_nodes = len((ir.get("graph") or {}).get("nodes") or [])
                 n_edges = len((ir.get("graph") or {}).get("edges") or [])
                 typer.echo(
                     f"IR written to {output_path} "
-                    f"({size_kb}KB, {n_nodes} nodes, {n_edges} edges)",
-                    err=True,
+                    f"({size_kb}KB, {n_nodes} nodes, {n_edges} edges)"
                 )
     else:
         if gzip_output:
@@ -4239,7 +4392,7 @@ def impact_cmd(
     ),
     no_cache: bool = typer.Option(
         False, "--no-cache",
-        help="Accepted for compatibility; this command always reads fresh source (no snapshot cache). No-op.",
+        help=_NO_CACHE_SUBCOMMAND_HELP,
     ),
 ) -> None:
     """Blast-radius analysis: who calls this class and what breaks if it changes?
@@ -4333,8 +4486,16 @@ def impact_cmd(
     finally:
         _prog.finish()
 
-    result = compute_blast_radius(ir, target, max_depth=depth)
-    result = _trim(result, BUDGET_IMPACT, label="impact")
+    # `--output <file>` asks for the whole answer, and its own note promised it.
+    # Both halves of that promise were broken: the caller lists were capped at
+    # construction, so the file held the same 30 of 134, and the output budget
+    # trimmed the file too — while `--agent` and `--compact` beside it already
+    # skipped the budget when writing to a file (C2-2).
+    _to_file = output_path is not None
+    result = compute_blast_radius(
+        ir, target, max_depth=depth, list_limit=0 if _to_file else None
+    )
+    result = _trim(result, BUDGET_IMPACT, label="impact", skip=_to_file)
     if _misread and result.get("resolution") == "not_found":
         result["analysis_warnings"] = [*(result.get("analysis_warnings") or []), _misread]
 
@@ -4422,7 +4583,7 @@ def endpoints_cmd(
     ),
     no_cache: bool = typer.Option(
         False, "--no-cache",
-        help="Accepted for compatibility; this command always reads fresh source (no snapshot cache). No-op.",
+        help=_NO_CACHE_SUBCOMMAND_HELP,
     ),
     by_controller: bool = typer.Option(
         False, "--by-controller",
@@ -5047,7 +5208,7 @@ def validation_cmd(
     ),
     no_cache: bool = typer.Option(
         False, "--no-cache",
-        help="Accepted for compatibility; this command always reads fresh source (no snapshot cache). No-op.",
+        help=_NO_CACHE_SUBCOMMAND_HELP,
     ),
 ) -> None:
     """Map request-body validation per endpoint (constraints + custom validators).
@@ -5910,7 +6071,7 @@ def spring_audit_cmd(
     ),
     no_cache: bool = typer.Option(
         False, "--no-cache",
-        help="Accepted for compatibility; this command always reads fresh source (no snapshot cache). No-op.",
+        help=_NO_CACHE_SUBCOMMAND_HELP,
     ),
 ) -> None:
     """Spring semantic audit: TX anomalies (TX-001..006) + security surface (SEC-001..003).
@@ -6182,12 +6343,13 @@ def verify_cmd(
 
     \b
     Contracts live in `.ask/contracts.yml` (see `ask verify-edit --help` for the
-    rule kinds). No contracts declared → nothing to verify, exit 0.
+    rule kinds). No contracts declared → nothing was verified, exit 2.
 
     \b
     Exit codes (with --ci, the default): 0 = pass, 1 = violations blocked,
-    2 = unverified (contracts unreadable or the repository could not be
-    analysed — never a silent pass). Same codes as `verify-edit`.
+    2 = unverified (no contracts declared, contracts unreadable, or the
+    repository could not be analysed — never a silent pass). Same codes as
+    `verify-edit`.
 
     \b
     Examples:
@@ -6451,6 +6613,24 @@ def migrate_check_cmd(
         help="Minimum severity to include: critical, high, medium, or low (default).",
         show_default=True,
     ),
+    target_jdk: Optional[int] = typer.Option(
+        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."
+        ),
+    ),
+    keep_boot: bool = typer.Option(
+        False,
+        "--keep-boot",
+        help=(
+            "You are staying on Spring Boot 2.x. Drops the Boot 3 axes — the "
+            "jakarta namespace, Spring Security 6 and the Hibernate 5→6 rewrite "
+            "— which are not blockers for a move you are not making."
+        ),
+    ),
     compact: bool = typer.Option(
         False,
         "--compact",
@@ -6463,7 +6643,7 @@ def migrate_check_cmd(
     ),
     no_cache: bool = typer.Option(
         False, "--no-cache",
-        help="Accepted for compatibility; this command always reads fresh source (no snapshot cache). No-op.",
+        help=_NO_CACHE_SUBCOMMAND_HELP,
     ),
     snapshot: bool = typer.Option(
         False, "--snapshot",
@@ -6594,7 +6774,13 @@ def migrate_check_cmd(
     _prog = Progress()
     _prog.start(f"checking migration ({len(file_list)} files)")
     try:
-        report = run_migrate_check(file_list, target, min_severity=min_severity)
+        report = run_migrate_check(
+            file_list,
+            target,
+            min_severity=min_severity,
+            target_jdk=target_jdk,
+            keep_boot=keep_boot,
+        )
     finally:
         _prog.finish()
     if _file_limitations:
@@ -6669,6 +6855,26 @@ _IMPACT_CAPPED_LISTS = (
 )
 
 
+def _flag_was_given(name: str) -> bool:
+    """True when the user typed this option, rather than inheriting its default.
+
+    A default is not a request: `--output` means "give me the whole answer", and
+    that reading must not override a cap the user explicitly asked for on the same
+    line. Click records where each value came from, which is the only way to tell
+    `--limit 100` apart from the 100 nobody typed.
+    """
+    try:
+        import click
+
+        ctx = click.get_current_context(silent=True)
+        if ctx is None:
+            return False
+        source = ctx.get_parameter_source(name)
+    except Exception:
+        return False
+    return source is not None and getattr(source, "name", "") == "COMMANDLINE"
+
+
 def _cap_impact_lists(data: dict, limit: int) -> dict:
     """Cap impact-chain leaf arrays, keeping every total exact.
 
@@ -6745,7 +6951,7 @@ def impact_chain_cmd(
     ),
     no_cache: bool = typer.Option(
         False, "--no-cache",
-        help="Accepted for compatibility; this command always reads fresh source (no snapshot cache). No-op.",
+        help=_NO_CACHE_SUBCOMMAND_HELP,
     ),
     limit: int = typer.Option(
         100, "--limit",
@@ -6874,6 +7080,11 @@ def impact_chain_cmd(
     result = run_impact_chain(cir, symbol, depth=depth, root=target, model=_model)
 
     data = result.to_dict()
+    # Same rule as `impact`: a file is a request for the whole answer (C2-2). An
+    # explicit `--limit` still wins — the user asking for a cap on a file has said
+    # so, and a default is not a request.
+    if output_path is not None and not _flag_was_given("limit"):
+        limit = 0
     data = _cap_impact_lists(data, limit)
     if _misread and result.resolution == "not_found":
         data["analysis_warnings"] = [*(data.get("analysis_warnings") or []), _misread]
@@ -7821,7 +8032,9 @@ def modernize_cmd(
 
     if output_path:
         _safe_write_file(output_path, output)
-        typer.echo(f"Modernization analysis written to {output_path}", err=True)
+        # C3-26: the payload is in the file; this line is the answer (see
+        # _emit_command_output, which this branch predates).
+        typer.echo(f"Modernization analysis written to {output_path}")
     else:
         try:
             sys.stdout.buffer.write(output.encode("utf-8"))
@@ -8775,16 +8988,17 @@ def cold_start_cmd(
     _meta_cs["token_economy"] = _tok_econ(_out, _out_with_meta, target)
     _out = _json.dumps(_out_with_meta, indent=2, ensure_ascii=False)
     if not compact and _size > 400_000:
-        sys.stderr.write(
+        # Informational: the answer is still on stdout, so this is a notice and
+        # takes the terminal gate (C3-26).
+        _notice(
             f"WARNING: Output is ~{_tokens // 1000}K tokens. This exceeds the context window of "
             "most LLMs (GPT-4o: 128K, Claude Sonnet: 200K). "
-            "Use --compact for a ~10K token subset, or --output FILE to save.\n"
+            "Use --compact for a ~10K token subset, or --output FILE to save."
         )
-        sys.stderr.flush()
     if output_path:
         _safe_write_file(output_path, _out)
-        sys.stderr.write(f"Saved {len(_out.encode('utf-8'))} bytes to {output_path}\n")
-        sys.stderr.flush()
+        # C3-26: payload in the file, so this line is the answer — stdout.
+        typer.echo(f"Saved {len(_out.encode('utf-8'))} bytes to {output_path}")
     else:
         typer.echo(_out)