sourcecode 4.10.3__tar.gz → 4.10.5__tar.gz

{sourcecode-4.10.3 → sourcecode-4.10.5}/CHANGELOG.md

@@ -2,6 +2,128 @@
 
 ## [Unreleased]
 
+## [4.10.5] — 2026-08-07
+
+Second release of the field-evaluation #13 queue. Three rows close and one closes
+in part; the suite is 6 691 tests green.
+
+⚠ **Two behaviour changes to read before upgrading a pipeline.** Both are the fix
+working, and both can move a gate:
+
+- On Windows, `pr-impact --files -` now resolves paths it previously mangled, so a
+  pipeline that was passing because its diff decoded to nothing can start failing —
+  with the verdict the diff always deserved (C3-58).
+- A security finding that existed only in build output (`target/classes`) is no
+  longer reported, so a repository audited mid-build can report fewer findings
+  (C3-64).
+
+### Performance
+
+- **The security configuration scan discovers its files 8.7× faster** (C3-64):
+  0.61 s → 0.07 s on keycloak, 0.45 s → 0.05 s on alfresco. Five `rglob` calls
+  became one pruned walk. `rglob` cannot skip a subtree, so the old cost was set by
+  the build output and the VCS metadata rather than by the source: 48.4 % of
+  openmrs-core's tree entries and 53.3 % of this repository's live under directories
+  that hold no source at all. On a clean checkout the end-to-end scan moves 1.73 s →
+  1.43 s (the rest is reading Java sources); the win grows with how built the tree
+  is, which is the state a developer's repository is normally in.
+
+### Fixed
+
+- **A path list is decoded by its bytes, never by the platform locale** (C3-58).
+  `ask pr-impact --files -` read stdin through Python's locale decoding, which on
+  Windows is the ANSI codepage: `git diff --name-only | ask pr-impact --files -`
+  returned `risk: UNKNOWN` and 0 endpoints where the same list without the shell's
+  default byte-order mark returned `CRITICAL` and 1 144 — a green pipeline on the
+  gating command. The BOM was the visible half; `AñoService.java` arriving as
+  `AñoService.java` was the cause. The new authority `sourcecode/text_input.py`
+  reads `sys.stdin.buffer` and lets the bytes name the encoding, and the list-file
+  shape goes through it too: PowerShell 5.1 writes UTF-16-LE by default, which the
+  previous UTF-8 read raised on. Undecodable bytes now yield an unusable path with
+  encoding named as a cause, never a traceback.
+- **No command claims `done` before its answer exists** (C3-54, part 2). The
+  completion line moved out of `Progress.finish()` entirely: `finish()` claims the
+  work is done, and the line is printed when the answer has actually been handed
+  over. A run killed in between prints nothing, and a run that raised prints
+  nothing — previously ~20 commands emitted `done (Xs)` while their `--output` file
+  did not exist yet, which in the field meant 6.8 minutes of analysis reported as
+  success over an absent file. Output files are also durable now: the shared writer
+  fsyncs data and directory entry before anything reports a write, and `repo-ir` —
+  the one `-o` path that bypassed that writer — goes through it.
+- **A rejected progress write no longer silences progress for the rest of the run**
+  (C3-56, part). The heartbeat treated any write failure as terminal; it now retries
+  and gives up only after five consecutive failures. The reported 393 s of silence
+  did not reproduce: the cadence is timer-driven and measured exact on a cold
+  29.9 s run (5.0 / 10.0 / 15.0 / 20.0 / 25.1 s). The progress denominator and ETA
+  the row also asks for are still open.
+- **A build copy is no longer a second security finding** (C3-64). The configuration
+  scan walked the whole tree five times and could not skip a subtree, so a compiled
+  copy of `application.properties` under `target/classes` was reported beside the
+  source file it came from. It now walks once, pruning build output and VCS metadata
+  with the same ignore set Java discovery uses.
+- **An unresolved changed file names the right thing to check** (C3-58). One message
+  covered both causes and pointed at the wrong one: a path that is *not on disk* is a
+  path problem (form and encoding), while a path that *is* there but maps to no class
+  is a fact about the file. They now say so separately.
+
+## [4.10.4] — 2026-08-07
+
+First release of the queue opened by field evaluation #13. Four of its rows close,
+one closes largely, and the suite goes green: `master` was carrying four failing
+tests before this release, none of them noticed by the release that shipped over
+them.
+
+### Fixed
+
+- **`baseline` no longer emits a JSON object keyed by symbol** (C3-62). PowerShell's
+  `ConvertFrom-Json` folds object keys case-insensitively, so two Java symbols
+  differing only by case — legal, Java is case-sensitive — collided and aborted
+  parsing of the *entire* baseline document on the default Windows consumer. `fan_in`
+  now serialises as a sorted array of `{symbol, fan_in}`, the shape `hotspots` already
+  used. Baselines captured before this release keep diffing and trending: the reader
+  accepts both shapes.
+- **`spring-audit` no longer prints `done` before the answer exists** (C3-54, part 1).
+  The completion line was emitted inside the `finally` around the analysis, so a
+  teardown landing between it and the write left 6.8 minutes of CPU and no output
+  file behind a reported success. It now prints after the write it describes. The
+  same reorder also stops `done` from being claimed on a run whose analysis *raised*.
+- **`ask cache model` answers in ~830 tokens instead of ~2 590** (C3-63). One line per
+  layer and per command by default; the per-command measured timings and notes move
+  behind `--full`. Every command and every layer is still named, and the invalidation
+  rule is still stated — the density fix is not a coverage cut. `--json` and
+  `--markdown` are unchanged.
+- **The evidence manifest publishes how many claims exist, not how many fitted**
+  (invariant I-2). The claim builder returned the moment it reached its 200-claim cap,
+  so the real total was never computed and the cap was published in its place, with no
+  field carrying the truth. `claims_cap` now reads `{total, total_indexed, capped}`
+  with `total` measured before truncation. `capped` is also corrected: exactly 200
+  claims reported a cut that had not happened.
+
+### Performance
+
+- **The `spring-audit` rule pass is 7.8× faster on a large repository** (C3-61):
+  42.1 s → 5.4 s measured on keycloak (5 486 non-test sources, 59 144 symbols), with
+  the finding set byte-identical before and after. The cost was not spread across the
+  file population — one rule was 94 % of it, and inside it `_proxy_bypass` scanned
+  every source for every inferred gate token before establishing that the source never
+  mentions the token: 98.9 % of the work was provably empty. The guard is an
+  equivalence, not a heuristic, and no threads or processes were added, so output
+  determinism is untouched. The rule pass is no longer the dominant phase.
+
+### Tests
+
+- The four batteries that were red on `master` before this release are green:
+  `test_flag_normalization` compared a wall-clock timestamp between two runs;
+  `test_path_admission` had no invocation row for `audit-report`; and
+  `test_invariant_counts_from_measurement` failed on `provenance.py` (a real defect,
+  fixed above) and on `audit_report.py` (a false positive from a hand-maintained key
+  catalogue, now a rule on the key's final token — the audit's anti-vacuous guard is
+  extended rather than trusted).
+- Every fix in this release ships a regression battery that was mutation-checked:
+  reverting the fix fails the new tests. Two of them were rewritten after the first
+  draft passed under that mutation — a summary that exists but is never reached by the
+  command, and an error path that exits before the spinner is created.
+
 ## [4.10.3] — 2026-08-05
 
 ### Fixed

{sourcecode-4.10.3 → sourcecode-4.10.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.10.3
+Version: 4.10.5
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -18,7 +18,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Utilities
 Requires-Python: >=3.9
 Requires-Dist: defusedxml>=0.7
-Requires-Dist: mcp>=1.0.0
+Requires-Dist: mcp<2,>=1.2
 Requires-Dist: pathspec>=1.0
 Requires-Dist: ruamel-yaml>=0.18
 Requires-Dist: tomli>=2.0; python_version < '3.11'
@@ -28,12 +28,12 @@ Requires-Dist: tree-sitter-javascript>=0.21; extra == 'ast'
 Requires-Dist: tree-sitter-typescript>=0.21; extra == 'ast'
 Requires-Dist: tree-sitter>=0.21; extra == 'ast'
 Provides-Extra: dev
-Requires-Dist: mcp>=1.0.0; extra == 'dev'
+Requires-Dist: mcp<2,>=1.2; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: ruff>=0.15; extra == 'dev'
 Provides-Extra: mcp
-Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Requires-Dist: mcp<2,>=1.2; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # ASK Engine
@@ -42,7 +42,7 @@ Description-Content-Type: text/markdown
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-4.10.3-blue)
+![Version](https://img.shields.io/badge/version-4.10.5-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -106,7 +106,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.10.3 — and, on a build that has aged,
+ask version                    # ask 4.10.5 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-4.10.3 → sourcecode-4.10.5}/README.md

@@ -4,7 +4,7 @@
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-4.10.3-blue)
+![Version](https://img.shields.io/badge/version-4.10.5-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -68,7 +68,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.10.3 — and, on a build that has aged,
+ask version                    # ask 4.10.5 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-4.10.3 → sourcecode-4.10.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "4.10.3"
+version = "4.10.5"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -30,7 +30,7 @@ dependencies = [
     "pathspec>=1.0",
     "ruamel.yaml>=0.18",
     "tomli>=2.0; python_version < '3.11'",
-    "mcp>=1.0.0",
+    "mcp>=1.2,<2",
     "defusedxml>=0.7",
 ]
 
@@ -43,7 +43,7 @@ dev = [
     "pytest>=8",
     "ruff>=0.15",
     "mypy>=1.10",
-    "mcp>=1.0.0",
+    "mcp>=1.2,<2",
 ]
 ast = [
     "tree-sitter>=0.21",
@@ -51,7 +51,7 @@ ast = [
     "tree-sitter-javascript>=0.21",
 ]
 mcp = [
-    "mcp>=1.0.0",
+    "mcp>=1.2,<2",
 ]
 
 [[tool.mypy.overrides]]

{sourcecode-4.10.3 → sourcecode-4.10.5}/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__ = "4.10.3"
+__version__ = "4.10.5"

{sourcecode-4.10.3 → sourcecode-4.10.5}/src/sourcecode/architectural_baseline.py

@@ -33,7 +33,7 @@ import json
 import subprocess
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from sourcecode import __version__ as TOOL_VERSION
 from sourcecode.architectural_delta import ArchMetrics, diff_metrics, extract_metrics
@@ -107,6 +107,35 @@ def _hotspots(fan_in: dict[str, int], top_n: int) -> list[dict]:
     return [{"symbol": s, "fan_in": c} for s, c in ranked[:top_n]]
 
 
+def _fan_in_to_list(fan_in: dict[str, int]) -> list[dict]:
+    """Serialise the full fan-in map as an array of ``{symbol, fan_in}`` objects,
+    sorted by symbol — never a JSON object keyed by symbol.
+
+    C3-62: PowerShell's `ConvertFrom-Json` folds object keys case-insensitively, so
+    two distinct Java symbols differing only by case (legal — Java is case-sensitive)
+    collapse into one key and abort parsing the *whole* baseline document. `hotspots`
+    already used this array shape (`_hotspots`); the full map stored beside it did
+    not. An array of objects has no such ceiling on any consumer."""
+    return [{"symbol": s, "fan_in": c} for s, c in sorted(fan_in.items())]
+
+
+def _fan_in_from_stored(value: Any) -> dict[str, int]:
+    """Read a stored ``fan_in`` field back into a symbol → count map.
+
+    Accepts both the array-of-objects shape (C3-62, current) and the legacy
+    object-keyed-by-symbol shape (baselines captured before this fix) so an older
+    baseline already committed to disk keeps diffing and trending correctly."""
+    if isinstance(value, list):
+        return {
+            str(item["symbol"]): int(item.get("fan_in", 0))
+            for item in value
+            if isinstance(item, dict) and "symbol" in item
+        }
+    if isinstance(value, dict):
+        return {str(k): int(v) for k, v in value.items()}
+    return {}
+
+
 def build_baseline(
     cir: "CanonicalRepositoryIR",
     *,
@@ -126,7 +155,6 @@ def build_baseline(
     that share them."""
     m = extract_metrics(cir)
     endpoints = sorted([meth, path] for (meth, path) in m.endpoints)
-    fan_in = dict(sorted(m.fan_in.items()))
     cycles = sorted((sorted(c) for c in m.cycles), key=lambda mm: (len(mm), mm))
     return {
         "schema": ARCH_BASELINE_SCHEMA,
@@ -145,7 +173,7 @@ def build_baseline(
         },
         "hotspots": _hotspots(m.fan_in, hotspot_n),
         "endpoint_surface": endpoints,
-        "fan_in": fan_in,
+        "fan_in": _fan_in_to_list(m.fan_in),
         "import_cycles": cycles,
         "env": env if env is not None else collect_env(),
         "provenance": (
@@ -209,7 +237,7 @@ def baseline_to_metrics(baseline: dict) -> ArchMetrics:
         endpoint_count=int(totals.get("endpoints", 0)),
         dependency_edge_count=int(totals.get("dependency_edges", 0)),
         endpoints=endpoints,
-        fan_in={str(k): int(v) for k, v in (baseline.get("fan_in") or {}).items()},
+        fan_in=_fan_in_from_stored(baseline.get("fan_in")),
         cycles=frozenset(
             frozenset(str(m) for m in members)
             for members in baseline.get("import_cycles", [])
@@ -397,9 +425,10 @@ def build_trend(baselines: list[dict]) -> dict:
             if isinstance(h, dict) and h.get("symbol"):
                 tracked.add(str(h["symbol"]))
 
+    fan_in_by_baseline = [_fan_in_from_stored(b.get("fan_in")) for b in baselines]
     hotspot_trends: list[dict] = []
     for sym in sorted(tracked):
-        series = [int((b.get("fan_in") or {}).get(sym, 0)) for b in baselines]
+        series = [fmap.get(sym, 0) for fmap in fan_in_by_baseline]
         first, last = series[0], series[-1]
         hotspot_trends.append({
             "symbol": sym,

{sourcecode-4.10.3 → sourcecode-4.10.5}/src/sourcecode/cache_model.py

@@ -302,8 +302,48 @@ def render_markdown() -> str:
     return "\n".join(out)
 
 
+def render_summary() -> str:
+    """The model as `ask cache model` prints it by default (C3-63).
+
+    One line per layer and one line per command — every command named (nothing
+    curated out, so the same completeness the battery checks against `render_text`
+    holds here too), but without the per-command prose (`note`) and timing
+    (`measured`) detail that made the default ~2 500 tokens of prose in a CLI whose
+    own selling argument is token economy. That detail is still one flag away.
+    """
+    lines: list[str] = []
+    lines.append(
+        "Invalidation: every layer keys on the exact tree state — any change to the "
+        "analysed files invalidates it, committed or not."
+    )
+    lines.append("")
+    lines.append("Layers")
+    id_width = max(len(lyr.id) for lyr in LAYERS)
+    for lyr in LAYERS:
+        lines.append(f"  {lyr.id.ljust(id_width)}  {lyr.stores}")
+    lines.append("")
+    lines.append(f"What a warm gives each command  ({REFERENCE_REPOSITORY})")
+    cmd_width = max(len(c.command) for c in COMMANDS)
+    warm_width = max(len(label) for label in _WARM_LABEL.values())
+    for cmd in COMMANDS:
+        repeat = "repeat cached" if cmd.repeat else "recomputes"
+        layers = ", ".join(cmd.reads) or "none"
+        lines.append(
+            f"  {cmd.command.ljust(cmd_width)}  {_WARM_LABEL[cmd.warm].ljust(warm_width)} "
+            f"({repeat})  [{layers}]"
+        )
+    lines.append("")
+    lines.append(
+        "Full detail (measured timings, per-command notes): ask cache model --full"
+    )
+    lines.append("Tables for docs: ask cache model --markdown   ·   machine-readable: --json")
+    return "\n".join(lines)
+
+
 def render_text() -> str:
-    """The model as `ask cache model` prints it."""
+    """The model in full: every layer and command with its measured timing and note.
+
+    `ask cache model --full`. See `render_summary` for the default."""
     lines: list[str] = []
     lines.append("Invalidation — one rule for every layer")
     lines.append("  Every layer keys on the exact tree state. Any change to the analysed files")

{sourcecode-4.10.3 → sourcecode-4.10.5}/src/sourcecode/cli.py

@@ -15,9 +15,10 @@ from typing import Any, NoReturn, Optional, cast
 import typer
 
 from sourcecode import __version__
-from sourcecode.error_schema import INVALID_INPUT_CODE, build_error_envelope
+from sourcecode.error_schema import EXECUTION_FAILED_CODE, INVALID_INPUT_CODE, build_error_envelope
 from sourcecode.entrypoint_classifier import is_production_entry_point, normalize_entry_point
 from sourcecode.progress import Progress
+from sourcecode.progress import output_emitted as _progress_output_emitted
 from sourcecode import perf
 from sourcecode.caller_metrics import (
     CALLER_METRIC_RECONCILIATION,
@@ -888,8 +889,27 @@ def _safe_write_file(path: "Path", content: str) -> None:
         path = Path(path)
         path.parent.mkdir(parents=True, exist_ok=True)
         tmp = path.with_name(f".{path.name}.tmp-{os.getpid()}-{time.time_ns()}")
-        tmp.write_text(content, encoding="utf-8")
+        # C3-54 part 2: the rename is atomic, the bytes were not durable. A
+        # process torn down between `write_text` and the OS flushing its page
+        # cache leaves a file that exists at full length and holds nothing —
+        # the same total loss the false `done` line reported as success, one
+        # layer down. fsync the data before the rename, then the directory
+        # entry, so a run that reports an output file has one.
+        with open(tmp, "w", encoding="utf-8") as fh:
+            fh.write(content)
+            fh.flush()
+            os.fsync(fh.fileno())
         tmp.replace(path)
+        try:
+            dir_fd = os.open(str(path.parent), os.O_RDONLY)
+            try:
+                os.fsync(dir_fd)
+            finally:
+                os.close(dir_fd)
+        except (OSError, AttributeError):
+            # Directory fsync is POSIX-only; on Windows the rename is already
+            # ordered against the data write. Never fail a good run over it.
+            pass
         try:
             from sourcecode.runs import active_run
             run = active_run()
@@ -1213,6 +1233,9 @@ def _emit_command_output(
             # 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")
+    # The answer has been handed over. Any `done (Xs)` a command deferred is now
+    # a true claim and prints here — never before this line (C3-54).
+    _progress_output_emitted()
 
 
 def _emit_text_output(text: str, copy: bool) -> None:
@@ -1228,6 +1251,7 @@ def _emit_text_output(text: str, copy: bool) -> None:
     typer.echo(text)
     if copy and _copy_to_clipboard(text):
         _notice("✓ copied to clipboard")
+    _progress_output_emitted()
 
 
 class _TextAnswer:
@@ -1257,6 +1281,7 @@ class _TextAnswer:
     def done(self, copy: bool) -> None:
         if copy and self._lines and _copy_to_clipboard(self.text):
             _notice("✓ copied to clipboard")
+        _progress_output_emitted()
 
 
 # H-06: Intercept Click-level UsageError (unknown options, bad args) and emit JSON.
@@ -4825,8 +4850,15 @@ def repo_ir_cmd(
         size_bytes = len(raw_bytes)
         if gzip_output:
             import gzip as _gzip
+            # Same durability rule as `_safe_write_file`: the bytes are on disk
+            # before anything says they are (C3-54).
             with _gzip.open(output_path, "wb") as _gz:
                 _gz.write(raw_bytes)
+                _gz.flush()
+                try:
+                    os.fsync(_gz.fileno())
+                except (OSError, AttributeError):
+                    pass
             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
@@ -4837,7 +4869,9 @@ def repo_ir_cmd(
                 f"IR written to {output_path} ({compressed_kb}KB gzip, {size_kb}KB uncompressed)"
             )
         else:
-            output_path.write_bytes(raw_bytes)
+            # Was a bare `write_bytes`: neither atomic nor durable, and the only
+            # `-o` write in the CLI that skipped the shared seam (C3-54).
+            _safe_write_file(output_path, output)
             size_kb = size_bytes // 1024
             if summary_only:
                 typer.echo(
@@ -4850,6 +4884,7 @@ def repo_ir_cmd(
                     f"IR written to {output_path} "
                     f"({size_kb}KB, {n_nodes} nodes, {n_edges} edges)"
                 )
+        _progress_output_emitted()
     else:
         if gzip_output:
             _emit_error_json(
@@ -7402,7 +7437,14 @@ def spring_audit_cmd(
             except Exception:
                 pass
         finally:
-            _prog.finish()
+            # C3-54: `done` must not claim the answer exists before it does. The
+            # field log showed `[ask] done (6.8m)` printed, then the process torn
+            # down before `-o` was written — a false success on 6.8 minutes of
+            # CPU. `stop()` here only clears the spinner (satisfies the standing
+            # rule that a raised error must never print under a live spinner
+            # frame); it prints no completion line. `_prog.finish()` runs below,
+            # after the render AND the write have actually happened.
+            _prog.stop()
     if table:
         output = _render_spring_audit_table(
             combined, rule_filter=rule_filter, top_n=top_n, min_severity=min_severity
@@ -7415,6 +7457,7 @@ def spring_audit_cmd(
     _total = combined.summary.get("total_findings", 0)
     _emit_command_output(output, output_path, copy,
                          success_msg=f"Spring audit written to {output_path} ({_total} findings)")
+    _prog.finish()
 
     if ci and combined.findings:
         raise typer.Exit(code=1)
@@ -9453,18 +9496,21 @@ def pr_impact_cmd(
     # --files accepts three shapes: a list file, '-' for stdin, or an inline
     # comma-separated list. The list-file shape was the only documented one and
     # the only one the error hint mentioned.
-    _files_raw = str(files).strip()
+    # Both byte-carrying shapes decode through `text_input`: stdin and list files
+    # arrive as somebody else's shell wrote them, and the locale codepage is not
+    # evidence of their encoding (C3-58).
+    from sourcecode import text_input as _text_input
+
+    _files_raw = str(files).replace(_text_input.BOM_CHAR, "").strip()
     if _files_raw == "-":
-        changed_files = [ln.strip() for ln in sys.stdin.read().splitlines() if ln.strip()]
+        changed_files = _text_input.parse_path_lines(_text_input.read_stdin_text())
         _files_desc = "stdin"
     else:
         _files_path = Path(_files_raw)
         if _files_path.is_file():
-            changed_files = [
-                line.strip()
-                for line in _files_path.read_text(encoding="utf-8").splitlines()
-                if line.strip()
-            ]
+            changed_files = _text_input.parse_path_lines(
+                _text_input.read_text_file(_files_path)
+            )
             _files_desc = str(_files_path)
         elif all(
             p.strip().lower().endswith(".java")
@@ -10301,6 +10347,9 @@ def modernize_cmd(
             sys.stdout.buffer.flush()
         except AttributeError:
             sys.stdout.write(output + "\n")
+    # This branch predates `_emit_command_output`, so it also has to release the
+    # deferred completion line itself (C3-54).
+    _progress_output_emitted()
 
     if copy:
         _copy_to_clipboard(output)
@@ -11569,12 +11618,33 @@ def mcp_status(copy: bool = _copy_option()) -> None:
     _answer.say("")
 
     # Stage 1: Dependencies
+    # C3-57: check the symbol this CLI actually consumes (FastMCP), not just
+    # whether the root `mcp` package imports — `mcp>=2.0` imports cleanly but
+    # has no `mcp.server.fastmcp` module, so importing only the root package
+    # reports a green check for a build that will fail on `mcp serve`/`mcp list-tools`.
+    def _installed_mcp_version() -> str:
+        # The `mcp` package does not set `__version__`; read installed
+        # distribution metadata instead, and fall back gracefully off a
+        # normal install (editable installs, vendored copies, etc.).
+        try:
+            from importlib.metadata import version as _dist_version
+            return _dist_version("mcp")
+        except Exception:
+            return "unknown"
+
     try:
-        import mcp as _mcp_pkg  # noqa: F401
-        _answer.say("Dependencies  ✓ installed")
+        from mcp.server.fastmcp import FastMCP  # noqa: F401
+        _mcp_ver = _installed_mcp_version()
+        _answer.say(f"Dependencies  ✓ installed   (mcp {_mcp_ver})")
     except ImportError:
-        _answer.say("Dependencies  ✗ missing")
-        _answer.say("  Fix: pip install sourcecode[mcp]")
+        try:
+            import mcp as _mcp_pkg  # noqa: F401
+            _mcp_ver = _installed_mcp_version()
+            _answer.say(f"Dependencies  ✗ mcp {_mcp_ver} incompatible (requires mcp>=1.2,<2)")
+            _answer.say("  Fix: pip install 'sourcecode[mcp]' --upgrade")
+        except ImportError:
+            _answer.say("Dependencies  ✗ missing")
+            _answer.say("  Fix: pip install sourcecode[mcp]")
     _answer.say("")
 
     clients = detect_clients()
@@ -11789,9 +11859,32 @@ def mcp_list_tools(
     import asyncio
     import json as _json
 
-    from sourcecode.mcp.server import mcp as _mcp
+    # C3-57: this command previously let a raw Python traceback through when
+    # the installed `mcp` package was incompatible (e.g. mcp>=2.0, which has
+    # no mcp.server.fastmcp) — the only command in the catalogue to do so.
+    # Route failures through the same structured error contract as every
+    # other command instead.
+    try:
+        from sourcecode.mcp.server import mcp as _mcp
+        tools = asyncio.run(_mcp.list_tools())
+    except ImportError as exc:
+        _emit_error_json(
+            EXECUTION_FAILED_CODE,
+            f"MCP server dependencies are not importable: {exc}",
+            hint="Run 'ask mcp status' to check the installed mcp package version — "
+                 "this CLI requires mcp>=1.2,<2. Fix: pip install 'sourcecode[mcp]' --upgrade",
+            expected="mcp>=1.2,<2 installed with mcp.server.fastmcp.FastMCP importable.",
+        )
+        raise typer.Exit(code=1)
+    except Exception as exc:
+        _emit_error_json(
+            EXECUTION_FAILED_CODE,
+            f"Failed to list MCP tools: {type(exc).__name__}: {exc}",
+            hint="Run 'ask mcp status' to check MCP server health.",
+            expected="A list of registered MCP tools.",
+        )
+        raise typer.Exit(code=1)
 
-    tools = asyncio.run(_mcp.list_tools())
     tools_sorted = sorted(tools, key=lambda t: t.name)
 
     if json_output:
@@ -12057,6 +12150,11 @@ def cache_model_cmd(
     path: Path = typer.Argument(Path("."), help="Repository path for CLI consistency (model is global)."),
     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."),
+    full: bool = typer.Option(
+        False, "--full",
+        help="Full prose: every command's measured timing and note (~2.5k tokens). "
+             "Default is a compact one-line-per-command summary.",
+    ),
     copy: bool = _copy_option(),
 ) -> None:
     """What each cache layer stores, what invalidates it, and what a warm helps.
@@ -12070,6 +12168,10 @@ def cache_model_cmd(
 
     One rule covers invalidation: every layer keys on the exact tree state, so any
     change to the analysed files invalidates it, committed or not.
+
+    \b
+    Default output is a compact summary (C3-63) — every command named, without the
+    per-command measured timing and note. Pass --full for that detail.
     """
     from sourcecode import cache_model as _cmodel
 
@@ -12089,7 +12191,8 @@ def cache_model_cmd(
             f"Scope: {Path(path).resolve()} (model is global; path accepted for "
             "cache command grammar consistency)\n\n"
         )
-        _emit_text_output(_prefix + _cmodel.render_text(), copy)
+        _body = _cmodel.render_text() if full else _cmodel.render_summary()
+        _emit_text_output(_prefix + _body, copy)
 
 
 @cache_app.command("freshness", short_help="RIS freshness relative to the current git HEAD")