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

sourcecode/architectural_baseline.py

@@ -37,6 +37,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 from sourcecode import __version__ as TOOL_VERSION
+from sourcecode import readonly as _readonly
 from sourcecode.architectural_delta import ArchMetrics, diff_metrics, extract_metrics
 from sourcecode.perf import collect_env
 
@@ -412,6 +413,9 @@ def protect_ask_dir(out_dir: Path, *, announce: bool = True) -> None:
         marker = ask_dir / ".gitignore"
         if not marker.exists():
             created = not ask_dir.exists()
+            # F-AS: the guard raises an OSError, which the `except OSError` below
+            # turns into "did not write" — the mode's promise, no new branch.
+            _readonly.guard(ask_dir, what="this tool's own directory")
             ask_dir.mkdir(parents=True, exist_ok=True)
             marker.write_text(_ASK_DIR_GITIGNORE, encoding="utf-8")
             if announce and created:
@@ -442,6 +446,7 @@ def _announce_ask_dir(ask_dir: Path) -> None:
 
 def write_baseline(baseline: dict, out_dir: Path) -> Path:
     """Write `baseline` as deterministic JSON under `out_dir`; return the file path."""
+    _readonly.guard(out_dir, what="baseline history directory")
     out_dir.mkdir(parents=True, exist_ok=True)
     protect_ask_dir(out_dir)
     path = out_dir / _baseline_filename(baseline)

sourcecode/cache_model.py

@@ -99,6 +99,15 @@ REFERENCE_REPOSITORY = (
 #: figures are relative to.
 REFERENCE_JAVA_FILES = 2000
 
+#: The build the reference figures were measured on. F-AP's second rider: C3-60
+#: conditioned these figures on the repository in hand; this is the other half —
+#: **keeping them current**, or, when they are not current, saying so. A table
+#: measured nine releases ago and printed without its provenance is a prediction
+#: presented as a measurement, which is the one thing this product does not do.
+#: The nightly gate (`docs/perf/REGRESSION-GATE.md`) is what re-measures them; this
+#: constant is what makes the gap visible until it does.
+REFERENCE_MEASURED_VERSION = "3.2.2"
+
 #: The other end of the measured range, and the reason this module publishes a
 #: *class* rather than a projected duration (C4-19). Field evaluation #16, on
 #: Windows 11 / PowerShell 5.1 / pipx / Python 3.10: `spring-audit` on a
@@ -164,7 +173,9 @@ LAYERS: tuple[Layer, ...] = (
         location="~/.sourcecode/parse-cache-v1/",
         invalidated_by=(
             "the file's own bytes and the extractor's source — content-addressed, "
-            "so it is never stale and never needs invalidating"
+            "so it is never stale and never needs invalidating. Bounded by "
+            "`ASK_PARSE_CACHE_MAX_MB` (default 512 MB, least-recently-used, "
+            "enforced on write) and reported in `cache status` (F-AR)"
         ),
         warmed="filled for every Java file the warm parses",
     ),
@@ -358,6 +369,34 @@ class Conditioning:
         )
 
 
+def reference_currency() -> dict:
+    """How old the reference figures are, in releases the reader can name (F-AP).
+
+    Returns the build the figures were measured on, the build running now, and
+    whether they are the same. The gap is not converted into a count of releases:
+    versions are not a distance and this module does not invent one. Naming both
+    builds is enough for a reader to see that a figure was measured on a different
+    one — which is the whole defect: *"no predice nada a 3 342 ficheros"* applies
+    to the size axis, and this is the same failure on the time axis.
+    """
+    from sourcecode import __version__
+
+    current = __version__
+    return {
+        "measured_on_version": REFERENCE_MEASURED_VERSION,
+        "running_version": current,
+        "current": REFERENCE_MEASURED_VERSION == current,
+        "statement": (
+            f"Measured on {REFERENCE_MEASURED_VERSION}; you are running {current}. "
+            f"The figures are that build's on that repository — they are not a "
+            f"prediction for this one, and the nightly performance gate "
+            f"(docs/perf/REGRESSION-GATE.md) is what re-measures them."
+            if REFERENCE_MEASURED_VERSION != current
+            else f"Measured on {current}, the build you are running."
+        ),
+    }
+
+
 def as_dict(here: "Optional[Conditioning]" = None) -> dict:
     """The whole model as data — what `ask cache model --json` emits."""
     conditioned: dict = {}
@@ -386,6 +425,9 @@ def as_dict(here: "Optional[Conditioning]" = None) -> dict:
         ],
         "reference_repository": REFERENCE_REPOSITORY,
         "reference_java_files": REFERENCE_JAVA_FILES,
+        # F-AP rider: the figures carry the build they were measured on, so a
+        # table nine releases old cannot read as this build's measurement.
+        "reference_currency": reference_currency(),
         # Published beside the reference so no consumer reads the figures as a
         # law: the same command has been measured 46× slower on a repository 1.7×
         # the size, on a different platform (C4-19).
@@ -427,6 +469,15 @@ def render_markdown() -> str:
     out.append("")
     out.append(f"Measured on {REFERENCE_REPOSITORY}, each command in isolation.")
     out.append("")
+    # The build, not the gap: this block is a checked-in document, so naming the
+    # *running* version here would make the doc drift on every release. `cache
+    # model` names both, because there a reader has a running build to compare to.
+    out.append(
+        f"Measured on release {REFERENCE_MEASURED_VERSION}. Figures are that "
+        f"build's on that repository, not a prediction for yours; the nightly "
+        f"performance gate (`docs/perf/REGRESSION-GATE.md`) is what re-measures them."
+    )
+    out.append("")
     out.append("| Command | A warm gives it | Measured (nothing cached → after a warm) | Repeat run cached | Layers | Notes |")
     out.append("|---|---|---|---|---|---|")
     for cmd in COMMANDS:
@@ -504,6 +555,7 @@ def render_text(here: "Optional[Conditioning]" = None) -> str:
     lines.append("")
     lines.append("What a warm gives each command")
     lines.append(f"  Timings: {REFERENCE_REPOSITORY}, each command measured in isolation.")
+    lines.append(f"  {reference_currency()['statement']}")
     width = max(len(c.command) for c in COMMANDS)
     for cmd in COMMANDS:
         repeat = "repeat cached" if cmd.repeat else "recomputes"

sourcecode/cli.py

@@ -18,6 +18,7 @@ from sourcecode import __version__
 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.readonly import WriteRefused
 from sourcecode.progress import output_emitted as _progress_output_emitted
 from sourcecode.output_encoding import json_ensure_ascii as _json_ensure_ascii
 from sourcecode.output_encoding import set_ascii_fallback
@@ -209,6 +210,37 @@ COMMAND_TIERS: "tuple[tuple[str, str, tuple[str, ...]], ...]" = (
     )),
 )
 
+#: What each command creates inside the repository it is pointed at, and when.
+#: The authority for the `--help` block below, so "which commands write" is a
+#: fact with one home rather than a paragraph someone remembers to update — the
+#: field asked for this by name, beside `--no-write` itself.
+#:
+#: A command absent from this table writes nothing inside the scope. That is a
+#: claim the battery checks, not a hope: `tests/test_no_write_mode.py` fails when
+#: a write seam is added without a row here.
+COMMANDS_THAT_WRITE: "tuple[tuple[str, str], ...]" = (
+    ("baseline", "`<repo>/.ask/baselines/` (or `--dir`) — one JSON per capture"),
+    ("migrate-check", "`<repo>/.ask/readiness-history/` — only with `--history`"),
+    ("verify", "`<repo>/.ask/contracts-baseline.json` — only with `--update-baseline`"),
+    ("verify-edit", "the repository's git hooks directory — only with `--install-hook`"),
+    ("*", "`<repo>/.ask/runs/` — only when `ASK_RUNS_IN_REPO=1` is set"),
+)
+
+
+def _writes_help_block() -> str:
+    """The `--no-write` table as `--help` prints it — generated, never typed."""
+    lines = [
+        "Commands that create files inside the repository (everything else reads only):",
+        "",
+    ]
+    width = max(len(name) for name, _ in COMMANDS_THAT_WRITE)
+    for name, what in COMMANDS_THAT_WRITE:
+        lines.append(f"  {name.ljust(width)}  {what}")
+    lines.append("")
+    lines.append("  --no-write (ASK_READONLY=1) refuses all of it and says so on stderr.")
+    return "\n".join(lines)
+
+
 #: Tiers whose membership is short enough to name in `--help`. `supported` is the
 #: remainder by construction, and printing twenty-six names would bury the two lists
 #: a reader acts on.
@@ -473,6 +505,8 @@ ASK_MAX_ANALYSIS_SECONDS/ASK_PROGRESS when CI needs an explicit budget.
 
 {_group_help_block()}
 
+{_writes_help_block()}
+
 [bold]Examples:[/bold]
   ask posture . --diff default:prod -o posture.json
   ask endpoints . -f json | jq '.endpoints | map(select(.method=="POST"))'
@@ -712,7 +746,7 @@ def _preprocess_args(args: list[str]) -> list[str]:
 
 def _preprocess_argv() -> None:
     """Apply _preprocess_args to sys.argv in-place (used by main_entry)."""
-    modified = _preprocess_args(sys.argv[1:])
+    modified = _preprocess_args(_apply_no_write(sys.argv[1:]))
     sys.argv = sys.argv[:1] + modified
 
 
@@ -958,6 +992,15 @@ def _admit_path(
 
     admission = admit_repo_path(raw)
     if admission.admitted:
+        # F-AS: the one gate every command's target passes through is also the
+        # one place that knows which tree the no-write guarantee is about. Declared
+        # here rather than in each command, so a command cannot forget to.
+        try:
+            from sourcecode import readonly
+
+            readonly.declare_scope(admission.resolved)
+        except Exception:
+            pass
         return admission.resolved
     hint = rejection_hint(admission, usage=usage)
     if extra_hint:
@@ -1487,8 +1530,15 @@ def _rule_pass_progress(
             estimate=False,
         )
 
+    def detail_sink(done: int, total: int, label: str, detail_unit: str) -> None:
+        # C3-79: inside a family the units *are* comparable to each other — files
+        # are files — so the ETA is allowed here, unlike the family counter above.
+        prog.work(done, total, stage=f"{stage} ({label})", unit=detail_unit)
+
     return RulePassProgress(
-        sink=sink if watching else None, stop_when=stop_when
+        sink=sink if watching else None,
+        detail_sink=detail_sink if watching else None,
+        stop_when=stop_when,
     )
 
 
@@ -1910,6 +1960,69 @@ def _output_option(help: "Optional[str]" = None) -> Any:
 COMMANDS_WITHOUT_OUTPUT: "frozenset[str]" = frozenset()
 
 
+#: The one help string for `--jobs` (F-AQ).
+JOBS_OPTION_HELP = (
+    "Worker processes used to parse files (default: CPU count − 1). "
+    "`--jobs 1` parses in this process. Parallelism only warms the "
+    "content-addressed parse cache — the answer is byte-identical at any value. "
+    "Env: ASK_JOBS."
+)
+
+
+def _jobs_option() -> Any:
+    """The `--jobs/-j` option, declared once (F-AQ).
+
+    Four field evaluations asked for this, and the fourth measured it from the
+    outside rather than inferring it: `threads=1`, `CPU/wall = 0,92…0,95`,
+    sustained for 54 minutes on a 20-core machine.
+
+    The flag is process-global by nature — one invocation analyses one
+    repository — so it is recorded in :mod:`sourcecode.parallel` rather than
+    threaded through every analysis signature. It is published only on commands
+    that parse a repository; `ASK_JOBS` covers the rest.
+    """
+    return typer.Option(None, "--jobs", "-j", min=1, help=JOBS_OPTION_HELP)
+
+
+def _apply_jobs(jobs: "Optional[int]") -> None:
+    """Put a `--jobs` value in force for this process. Never raises."""
+    try:
+        from sourcecode import parallel
+
+        parallel.set_jobs(jobs)
+    except Exception:
+        pass
+
+
+#: The one help string for `--no-write` (F-AS).
+NO_WRITE_OPTION_HELP = (
+    "Create nothing inside the analysed repository. A command that cannot answer "
+    "without writing says so instead of writing. Shared caches outside the "
+    "repository are unaffected. Env: ASK_READONLY=1."
+)
+
+#: The flag itself, handled before the parser sees it — the `--detach` precedent
+#: (C3-53), for the same reason and a stronger one. A mode whose value is that an
+#: auditor can *rely* on it is worthless if it is accepted by five commands and
+#: rejected by seventy-nine: the one run that refuses the flag is the run that
+#: writes. Declaring it per command would be eighty-four copies of one decision
+#: that is not a command's to make.
+NO_WRITE_FLAG = "--no-write"
+
+
+def _apply_no_write(argv: "list[str]") -> "list[str]":
+    """Consume `--no-write` from *argv*, putting the mode in force. Never raises."""
+    if NO_WRITE_FLAG not in argv:
+        return argv
+    try:
+        from sourcecode import readonly
+
+        readonly.set_readonly(True)
+    except Exception:
+        pass
+    return [a for a in argv if a != NO_WRITE_FLAG]
+
+
 #: The one help string for `--format`, for the same reason as COPY_OPTION_HELP.
 FORMAT_OPTION_HELP = "Output format: json (default) or yaml."
 
@@ -2667,6 +2780,7 @@ def main(
         "--no-cache",
         help="Bypass the scan cache and force a fresh analysis.",
     ),
+    jobs: Optional[int] = _jobs_option(),
 ) -> None:
     """Analyze a repository and produce structured context for AI coding agents.
 
@@ -2677,6 +2791,7 @@ def main(
       ask /path/to/repo --compact  analyze specific path
       ask --agent                agent-optimized output (full detail)
     """
+    _apply_jobs(jobs)
     # First-run telemetry notice (skip for telemetry/version/config subcommands)
     if ctx.invoked_subcommand not in ("telemetry", "version", "config"):
         _maybe_show_telemetry_notice()
@@ -4557,6 +4672,7 @@ def prepare_context_cmd(
         ),
     ),
     progress_mode: Optional[str] = _progress_option(),
+    jobs: Optional[int] = _jobs_option(),
 ) -> None:
     """Task-specific context for AI coding agents.
 
@@ -4586,6 +4702,7 @@ def prepare_context_cmd(
       JSON output includes evidence_manifest: claim IDs for context files and
       source-backed rows, plus command inputs, ASK version, git HEAD and freshness.
     """
+    _apply_jobs(jobs)
     from sourcecode.prepare_context import TASKS, TaskContextBuilder
 
     if task_help:
@@ -5352,6 +5469,7 @@ def repo_ir_cmd(
         help="Compress output with gzip. Requires --output. Reduces large IR files by ~70-80%.",
     ),
     progress_mode: Optional[str] = _progress_option(),
+    jobs: Optional[int] = _jobs_option(),
 ) -> None:
     """Deterministic symbol-level IR for Java repositories.
 
@@ -5376,6 +5494,7 @@ def repo_ir_cmd(
       ask repo-ir --max-nodes 200 --max-edges 500
       ask repo-ir --output ir.json.gz --gzip
     """
+    _apply_jobs(jobs)
     import json as _json
 
     from sourcecode.repository_ir import apply_ir_size_limits, build_repo_ir, find_java_files
@@ -5868,6 +5987,7 @@ def endpoints_cmd(
              "(implies --client-usage).",
     ),
     progress_mode: Optional[str] = _progress_option(),
+    jobs: Optional[int] = _jobs_option(),
 ) -> None:
     """Extract REST API endpoint surface from Java source files.
 
@@ -5899,6 +6019,7 @@ def endpoints_cmd(
       ask endpoints . --limit 10
       ask endpoints . --compact
     """
+    _apply_jobs(jobs)
     _enforce_format("endpoints", format)
 
     target = _admit_path(path)
@@ -6418,6 +6539,7 @@ def export_cmd(
              "default because it dominates the export size (18 MB on a large repo).",
     ),
     progress_mode: Optional[str] = _progress_option(),
+    jobs: Optional[int] = _jobs_option(),
 ) -> None:
     """Export structured, tool-agnostic codebase views for downstream tooling.
 
@@ -6446,6 +6568,7 @@ def export_cmd(
     The section flags compose; pass several to emit multiple sections in one
     document. --c4 assembles the full architecture export on its own.
     """
+    _apply_jobs(jobs)
     from sourcecode.repository_ir import build_repo_ir, find_java_files
 
     _enforce_format("export", format)
@@ -6563,6 +6686,7 @@ def validation_cmd(
         help=_NO_CACHE_SUBCOMMAND_HELP,
     ),
     progress_mode: Optional[str] = _progress_option(),
+    jobs: Optional[int] = _jobs_option(),
 ) -> None:
     """Map request-body validation per endpoint (constraints + custom validators).
 
@@ -6587,6 +6711,7 @@ def validation_cmd(
       ask validation . --path-prefix /owners
       ask validation . --format yaml
     """
+    _apply_jobs(jobs)
     _enforce_format("validation", format)
 
     target = _admit_path(path)
@@ -7940,6 +8065,7 @@ def spring_audit_cmd(
     ),
     detach: bool = _detach_option(),
     progress_mode: Optional[str] = _progress_option(),
+    jobs: Optional[int] = _jobs_option(),
 ) -> None:
     """Spring semantic audit: {{RULE_SUMMARY}}.
 
@@ -7993,6 +8119,7 @@ def spring_audit_cmd(
 {{NON_COVERAGE}}
     Silence about those is not evidence that there is nothing to find.
 """
+    _apply_jobs(jobs)
     import json as _json
 
     from sourcecode.repository_ir import find_java_files
@@ -8085,6 +8212,8 @@ def spring_audit_cmd(
             # that the rule pass asks it.
             _rules_cut: list[str] = []
             _phases_cut: list[str] = []
+            # C3-79: families the budget stopped *inside*, with how far each got.
+            _rules_partial: list[dict] = []
             if scope in ("all", "tx"):
                 if _run.exhausted():
                     _stopped_early = _WHY_BUDGET
@@ -8098,7 +8227,11 @@ def spring_audit_cmd(
                     ))
                     _cut = list(getattr(_tx_watch, "not_run", []) or [])
                     _rules_cut.extend(_cut)
-                    if _cut:
+                    _partial_families = list(
+                        getattr(_tx_watch, "partially_run", []) or []
+                    )
+                    _rules_partial.extend(_partial_families)
+                    if _cut or _partial_families:
                         _stopped_early = _WHY_BUDGET
                         _phases_cut.append("tx_audit")
                     else:
@@ -8119,7 +8252,11 @@ def spring_audit_cmd(
                     ))
                     _cut = list(getattr(_sec_watch, "not_run", []) or [])
                     _rules_cut.extend(_cut)
-                    if _cut:
+                    _partial_families = list(
+                        getattr(_sec_watch, "partially_run", []) or []
+                    )
+                    _rules_partial.extend(_partial_families)
+                    if _cut or _partial_families:
                         _stopped_early = _WHY_BUDGET
                         _phases_cut.append("security_audit")
                     else:
@@ -8130,6 +8267,14 @@ def spring_audit_cmd(
 
             combined = SpringAuditResult.merge(results, scope=scope)
 
+            # C2-31: a phase that never *started* is a cut this envelope cannot
+            # learn from its own scopes — no auditor ran to record it. The run
+            # knows, so it says so here, and `finalize()` applies the same ceiling
+            # and the same floor marks it applies to a scope cut mid-pass.
+            if _stopped_early and not combined.partial:
+                combined.partial = True
+                combined.finalize()
+
             if _file_limitations:
                 combined.limitations.extend(_file_limitations)
 
@@ -8172,6 +8317,22 @@ def spring_audit_cmd(
             data = combined.to_compact_dict() if compact else combined.to_dict()
             if _stopped_early:
                 data["_partial"] = _run.status(_stopped_early)
+                if _rules_partial:
+                    # C3-79: neither run nor not-run. How far it got is what a
+                    # reader needs to decide whether to re-run with more time, and
+                    # the findings it produced before the cut are in the payload.
+                    data["_partial"]["rules_partially_run"] = _rules_partial
+                    data["_partial"]["how_to_read"] += (
+                        " One rule family was stopped part-way through its own "
+                        "population: "
+                        + "; ".join(
+                            f"{'/'.join(entry['rule_ids'])} after "
+                            f"{entry['units_done']} of {entry['units_total']} "
+                            f"{entry['unit']}"
+                            for entry in _rules_partial
+                        )
+                        + ". What it found before the cut is reported and is a floor."
+                    )
                 if _rules_cut:
                     # C3-71: a phase stopped *inside* is neither completed nor
                     # pending, and calling it either would misreport the run. The
@@ -8652,6 +8813,7 @@ def risk_cmd(
     copy: bool = _copy_option(),
     detach: bool = _detach_option(),
     progress_mode: Optional[str] = _progress_option(),
+    jobs: Optional[int] = _jobs_option(),
 ) -> None:
     """[EXPERIMENTAL] What each defect actually costs, once reach and access are in it.
 
@@ -8697,6 +8859,7 @@ def risk_cmd(
       ask risk . --table --rule SEC-008 --band high --top-n 20
       ask risk . --limit 10 -o risk.json
     """
+    _apply_jobs(jobs)
     from sourcecode.risk import build_risk
 
     path = _admit_path(path)
@@ -9373,6 +9536,7 @@ def posture_cmd(
     format: str = _format_option(help="Output format: json or yaml."),
     copy: bool = _copy_option(),
     progress_mode: Optional[str] = _progress_option(),
+    jobs: Optional[int] = _jobs_option(),
 ) -> None:
     """Which beans are wired under a profile set — and which cannot be decided.
 
@@ -9410,6 +9574,7 @@ def posture_cmd(
       ask posture . --resolve-environments
       ask posture . --resolve-environments --env-file prod.env
     """
+    _apply_jobs(jobs)
     from sourcecode.posture import (
         FAIL_ON_CHOICES,
         build_posture,
@@ -9782,6 +9947,7 @@ def migrate_check_cmd(
     ),
     detach: bool = _detach_option(),
     progress_mode: Optional[str] = _progress_option(),
+    jobs: Optional[int] = _jobs_option(),
 ) -> None:
     """Spring Boot 2→3 migration readiness + Java LTS/licensing inventory.
 
@@ -9851,6 +10017,7 @@ def migrate_check_cmd(
       blockers; and explicit Oracle JDK/licensing-review signals. This is
       inventory evidence, not legal advice, and it never changes readiness_score.
     """
+    _apply_jobs(jobs)
     from sourcecode.repository_ir import find_java_files
     from sourcecode.migrate_check import run_migrate_check
 
@@ -10106,6 +10273,7 @@ def impact_chain_cmd(
         ),
     ),
     progress_mode: Optional[str] = _progress_option(),
+    jobs: Optional[int] = _jobs_option(),
 ) -> None:
     """Spring impact-chain: systemic blast radius of a symbol; TX/SEC findings are opt-in.
 
@@ -10139,6 +10307,7 @@ def impact_chain_cmd(
       ask impact-chain com.example.OrderService#placeOrder /path/to/repo
       ask impact-chain PaymentService . --depth 6 --output impact.json
     """
+    _apply_jobs(jobs)
     import json as _json
 
     from sourcecode.repository_ir import find_java_files
@@ -12996,6 +13165,18 @@ def cache_status_cmd(
                     "written by another build and can never be read again — the next "
                     "analysis retires them"
                 )
+            # F-AR: a store in somebody else's home directory says what bounds it.
+            if "budget_bytes" in _store:
+                _budget_mb = _store.get("budget_mb")
+                _env = _store.get("budget_env")
+                if _store.get("budget_bytes"):
+                    _over = " — OVER, the next write evicts" if _store.get("over_budget") else ""
+                    _answer.say(
+                        f"{'':<13}budget {_budget_mb} MB, {_store.get('policy')} "
+                        f"(${_env}){_over}"
+                    )
+                else:
+                    _answer.say(f"{'':<13}{_store.get('policy')} (${_env})")
         # RIS section
         if stats.get("ris_exists"):
             _stale_tag = " [STALE]" if stats.get("ris_is_stale") else ""
@@ -13604,6 +13785,24 @@ def main_entry() -> None:
     try:
         # prog_name pins usage/help to the canonical `ask`, whatever the alias.
         app(prog_name="ask")
+    except WriteRefused as _refused:
+        # F-AS. "A command that cannot answer without writing says so instead of
+        # writing" — and *says so* means one sentence in the error envelope every
+        # other refusal uses, never a traceback. The write did not happen; that is
+        # the guarantee holding, not a fault.
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            str(_refused),
+            hint=(
+                "The run was asked to create something inside the repository while "
+                "--no-write (ASK_READONLY=1) was in force. Drop the flag that "
+                "persists — or point its directory option outside the repository — "
+                "and the same answer is produced with the artefact."
+            ),
+            expected="A run that creates nothing inside the analysed repository.",
+            path=_refused.path,
+        )
+        raise SystemExit(1)
     finally:
         # Best-effort "new version available" nudge. Only speaks on an
         # interactive terminal; never blocks, raises, or affects exit status.