sourcecode 4.14.0__py3-none-any.whl → 4.15.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.14.0"
+__version__ = "4.15.0"

sourcecode/cli.py

@@ -1261,16 +1261,23 @@ def _analysis_budget(command: str) -> dict[str, Any]:
         command, ("repo-wide", 600, "run this command in a supervised or nightly job")
     )
     configured: Optional[float] = None
+    source: Optional[str] = None
     raw = os.environ.get("ASK_MAX_ANALYSIS_SECONDS")
     if raw:
         try:
             configured = float(raw)
         except ValueError:
             configured = None
+        else:
+            # C3-83: a budget is inherited from a shell or a CI runner, so the
+            # person reading `total_defects` is often not the person who set it.
+            # Where it came from travels with it, from here to `_partial`.
+            source = f"ASK_MAX_ANALYSIS_SECONDS={raw} (process environment)"
     return {
         "class": cls,
         "recommended_min_seconds": recommended,
         "configured_max_seconds": configured,
+        "configured_source": source,
         "fallback": fallback,
     }
 
@@ -1318,9 +1325,23 @@ def _enforce_analysis_budget(
     """
     configured = budget.get("configured_max_seconds")
     recommended = float(budget.get("recommended_min_seconds") or 0)
-    if configured is None or float(configured) >= recommended:
+    if configured is None:
+        return
+    source = budget.get("configured_source")
+    from sourcecode.phased_run import budget_provenance, budget_warning
+
+    if float(configured) >= recommended:
+        # C3-83: over the floor there is no advice to give, and there is still a
+        # fact the reader of the answer needs — a limit set in an environment is
+        # invisible to whoever reads `total_defects` afterwards.
+        if not source:
+            return
+        try:
+            sys.stderr.write(budget_provenance(command, float(configured), source))
+            sys.stderr.flush()
+        except Exception:
+            pass
         return
-    from sourcecode.phased_run import budget_warning
 
     _anchors, _scope = _budget_evidence(command, path)
     try:
@@ -1328,7 +1349,7 @@ def _enforce_analysis_budget(
             budget_warning(
                 command, str(budget.get("class") or "repo-wide"),
                 float(configured), recommended,
-                anchors=_anchors, scope=_scope,
+                anchors=_anchors, scope=_scope, source=source,
             )
         )
         sys.stderr.flush()
@@ -1960,12 +1981,14 @@ def _output_option(help: "Optional[str]" = None) -> Any:
 COMMANDS_WITHOUT_OUTPUT: "frozenset[str]" = frozenset()
 
 
-#: The one help string for `--jobs` (F-AQ).
+#: The one help string for `--jobs` (F-AQ; the scope sentence is C3-84/CL-18).
 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."
+    "It does NOT parallelise the rule pass, which is where a repository-wide "
+    "audit spends most of its time, and on a warm cache there is nothing left "
+    "to parse, so raising it buys nothing there. Env: ASK_JOBS."
 )
 
 
@@ -1980,6 +2003,18 @@ def _jobs_option() -> Any:
     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.
+
+    **C3-84 / CL-18.** The fifth evaluation read this help, sampled the process
+    and corrected four rounds of its own diagnosis: parallelism exists and covers
+    the phase that is not the cost. `threads=4` for the first seconds (parsing),
+    then `threads=1` with CPU/wall **0,97** for the remaining ~99 % — the rule
+    pass, applying families over a built IR — and on a warm cache, which is the
+    normal case, there is nothing to parse at all. The old sentence was true
+    about what the flag *does* and silent about what it does not, which is the
+    half that decides whether setting it is worth anything. Saying so costs a
+    line; letting an operator raise it and measure no change costs trust. The
+    capability that makes the rule pass parallel is F-AT, and no help text is a
+    substitute for it.
     """
     return typer.Option(None, "--jobs", "-j", min=1, help=JOBS_OPTION_HELP)
 
@@ -8181,6 +8216,8 @@ def spring_audit_cmd(
         phases=_phases,
         output_path=output_path,
         budget_seconds=_analysis_budget("spring-audit").get("configured_max_seconds"),
+        # C3-83: the budget's origin travels with the budget, into `_partial`.
+        budget_source=_analysis_budget("spring-audit").get("configured_source"),
         writer=_safe_write_file,
     )
     _stopped_early: Optional[str] = None
@@ -8899,6 +8936,8 @@ def risk_cmd(
         phases=["audit", "compose"],
         output_path=output_path,
         budget_seconds=_analysis_budget("risk").get("configured_max_seconds"),
+        # C3-83: the budget's origin travels with the budget, into `_partial`.
+        budget_source=_analysis_budget("risk").get("configured_source"),
         writer=_safe_write_file,
     )
     with _expensive_analysis_scope("risk", path, phase):

sourcecode/phased_run.py

@@ -88,6 +88,11 @@ class PhasedRun:
     phases: "list[str]"
     output_path: Optional[Path] = None
     budget_seconds: Optional[float] = None
+    #: Where `budget_seconds` came from, verbatim (C3-83) — e.g.
+    #: `ASK_MAX_ANALYSIS_SECONDS=420 (process environment)`. A truncated answer
+    #: declares everything about *being* truncated and could not say what decided
+    #: it, and the variable is inherited from a shell or a runner.
+    budget_source: Optional[str] = None
     #: injected by the CLI so a checkpoint uses the same durable write as the
     #: final answer (fsync + atomic rename), rather than a second, worse one.
     writer: Optional[Callable[[Path, str], None]] = None
@@ -140,6 +145,8 @@ class PhasedRun:
         }
         if self.budget_seconds:
             out["budget_seconds"] = float(self.budget_seconds)
+            if self.budget_source:
+                out["budget_source"] = self.budget_source
         return out
 
     # -- checkpoints -------------------------------------------------------
@@ -210,6 +217,7 @@ def budget_warning(
     *,
     anchors: Optional[str] = None,
     scope: Optional[str] = None,
+    source: Optional[str] = None,
 ) -> str:
     """What the operator is told when the budget is under the class floor.
 
@@ -238,6 +246,10 @@ def budget_warning(
         f"[ask] budget: {command} is a {cls} analysis and the configured budget "
         f"is {configured:g}s."
     ]
+    if source:
+        # C3-83: name the origin, because a variable inherited from a shell or a
+        # runner is the one setting nobody in the conversation remembers choosing.
+        lines.append(f"      Budget read from {source}.")
     if anchors:
         lines.append(f"      Measured for this command: {anchors}.")
     else:
@@ -259,3 +271,24 @@ def budget_warning(
         "the ones that did not. It is a floor, not a verdict."
     )
     return "\n".join(lines) + "\n"
+
+
+def budget_provenance(command: str, configured: float, source: str) -> str:
+    """One line naming where a budget over the class floor came from (C3-83).
+
+    Above the floor there is no advice to give and there is still a fact worth
+    stating. The field measured what its absence costs: the same build answers
+    **395 findings / 98 defects** without a budget and **267 / 11** with
+    `ASK_MAX_ANALYSIS_SECONDS=420`, and everything about the truncation is
+    declared in the payload — `partial`, `counts_are_floor`, a capped confidence
+    — while the *reason* the run was cut lives in an environment variable the
+    reader of that payload never saw. So it is named where the run happens, once,
+    on stderr, next to the command it is about.
+    """
+    return (
+        f"[ask] budget: {command} will stop after {configured:g}s. Budget read "
+        f"from {source}.\n"
+        "      A run that hits it publishes a FLOOR: `summary.partial`, "
+        "`summary.counts_are_floor` and `_partial` say so. Unset the variable "
+        "for a complete audit.\n"
+    )

sourcecode/release_info.py

@@ -27,7 +27,7 @@ from typing import Any, Optional
 #: The date `__version__` was released, from that version's CHANGELOG entry.
 #: `tests/test_release_info.py` fails the build if the two disagree, so this is
 #: a copy of a fact rather than a second authority for it.
-RELEASE_DATE = "2026-08-09"
+RELEASE_DATE = "2026-08-10"
 
 #: Releases per day, measured over the 30 releases before this one (the same
 #: computation the test re-runs against the CHANGELOG). Stable across window

sourcecode/rule_pass.py

@@ -155,20 +155,37 @@ class RulePassProgress:
         from the family's duration to a batch's, and the cost of the check is a
         modulo per unit.
 
+        **C3-82.** The sampling constant belongs to the *clock* and not to the
+        *counter*, and until this the two shared it. The field measured what that
+        costs: `1856/3342 java files` at 10,0 s, then **13,6 minutes with no line
+        at all**, then `3328/3342` — because a report that lands between two batch
+        boundaries is never produced, and a stretch of expensive units (or one
+        pathological file) is invisible for as long as it lasts. So the count is
+        reported on **every** unit and the clock is still read once per batch: the
+        emitter throttles itself on an interval, so a per-unit report costs one
+        clock read and produces a line only when one is due, while a per-unit
+        budget check would buy no resolution the deadline can use.
+
         Never raises: an unreadable clock is not evidence the budget is spent, and
         a reporting fault is not a reason to stop analysing.
         """
-        if done % self.sample_every and done != total:
-            return False
         if self.detail_sink is not None:
             try:
                 self.detail_sink(done, total, label, unit)
             except Exception:
                 pass
+        if done % self.sample_every and done != total:
+            return False
         return self.should_stop()
 
     def record_partial(
-        self, rule_ids: "list[str]", done: int, total: int, *, unit: str = "files"
+        self,
+        rule_ids: "list[str]",
+        done: int,
+        total: int,
+        *,
+        unit: str = "files",
+        stage: str = "",
     ) -> None:
         """Record a family the budget cut *in flight* (C3-79).
 
@@ -176,12 +193,29 @@ class RulePassProgress:
         calling it not-run discards findings that were measured and are published.
         It gets its own state, with the count it reached, because *how far* is the
         thing a reader needs in order to decide whether to re-run with more time.
+
+        **C3-81.** The count is the *stage's*, not the family's, and until this
+        seam said so the entry read as its own contradiction. The field measured
+        it: `units_done: 3342, units_total: 3342` in a list meaning *"this family
+        did not finish"*, on a family that walks four populations in sequence
+        (Java sources, then configuration files, then descriptors, then mappers)
+        and was cut at the end of the first. Six `DEAD-001` findings really were
+        missing, and nothing in the entry could say where from. So the stage is
+        named, and `units_basis` states what the two numbers count — which is the
+        difference between a reader concluding *"it finished"* and a reader
+        concluding *"three populations after this one never started"*.
         """
         self.partially_run.append({
             "rule_ids": list(rule_ids),
             "units_done": done,
             "units_total": total,
             "unit": unit,
+            "stage_stopped_in": stage or unit,
+            "units_basis": (
+                "units_done/units_total count the stage named in "
+                "stage_stopped_in, not the whole family: a family cut at the end "
+                "of one stage did not run the stages after it."
+            ),
         })
 
     def partial_rule_ids(self) -> "list[str]":
@@ -223,14 +257,21 @@ class FamilyBudget:
     label: str
     stopped: bool = False
 
-    def tick(self, done: int, total: int, *, unit: str = "files") -> bool:
-        """True when this family must stop. Idempotent once it has said so."""
+    def tick(
+        self, done: int, total: int, *, unit: str = "files", stage: str = ""
+    ) -> bool:
+        """True when this family must stop. Idempotent once it has said so.
+
+        `done` is what the loop has **finished**, so a stage in flight can never
+        report its own population as complete (C3-81); `stage` names the walk the
+        count belongs to, because a family may walk several in sequence.
+        """
         if self.stopped:
             return True
         if self.progress.tick(done, total, label=self.label, unit=unit):
             self.stopped = True
             self.progress.record_partial(
-                list(self.rule_ids), done, total, unit=unit
+                list(self.rule_ids), done, total, unit=unit, stage=stage
             )
             return True
         return False

sourcecode/security_config_scan.py

@@ -612,8 +612,13 @@ def scan_security_configuration(
 
     out: "list[SecurityConfigObservation]" = []
     _java_total = len(java_files)
-    for _seen, rel in enumerate(java_files, start=1):
-        if budget is not None and budget.tick(_seen, _java_total, unit="java files"):
+    for _seen, rel in enumerate(java_files):
+        # C3-81: `_seen` is what this walk has *finished*, so the stage cannot
+        # report a complete population while it is still being cut, and the stage
+        # is named because three more populations follow this one.
+        if budget is not None and budget.tick(
+            _seen, _java_total, unit="java files", stage="scanning java sources"
+        ):
             return sorted(
                 _shared_across_environments(out),
                 key=lambda o: (o.rule, o.file, o.line),
@@ -656,9 +661,10 @@ def scan_security_configuration(
     if config_files is None:
         config_files = _walked_config
     _cfg = sorted(set(config_files))
-    for _seen, rel in enumerate(_cfg, start=1):
+    for _seen, rel in enumerate(_cfg):
         if budget is not None and budget.tick(
-            _seen, len(_cfg), unit="configuration files"
+            _seen, len(_cfg), unit="configuration files",
+            stage="scanning configuration files",
         ):
             break
         try:
@@ -673,9 +679,10 @@ def scan_security_configuration(
     # deployment descriptors, and a per-environment overlay tree is covered
     # because the walk finds the file wherever the build put it.
     _desc = sorted(set(descriptors))
-    for _seen, rel in enumerate(_desc, start=1):
+    for _seen, rel in enumerate(_desc):
         if budget is not None and budget.tick(
-            _seen, len(_desc), unit="deployment descriptors"
+            _seen, len(_desc), unit="deployment descriptors",
+            stage="scanning deployment descriptors",
         ):
             break
         try:
@@ -686,9 +693,9 @@ def scan_security_configuration(
         out.extend(_scan_descriptor(blank_xml_comments(text), rel))
 
     _maps = sorted(set(mappers) - set(descriptors))
-    for _seen, rel in enumerate(_maps, start=1):
+    for _seen, rel in enumerate(_maps):
         if budget is not None and budget.tick(
-            _seen, len(_maps), unit="mapper files"
+            _seen, len(_maps), unit="mapper files", stage="scanning mapper files",
         ):
             break
         try:

sourcecode/spring_security_audit.py

@@ -110,10 +110,13 @@ class _SEC001UnsecuredEndpoint:
         findings: list[SpringFinding] = []
 
         _total = len(cir.endpoints)
-        for _seen, ep in enumerate(cir.endpoints, start=1):
+        for _seen, ep in enumerate(cir.endpoints):
             # C3-79: the population is the endpoints, so that is what the deadline
             # is observed on. What was measured before the cut is returned.
-            if budget is not None and budget.tick(_seen, _total, unit="endpoints"):
+            # C3-81: `_seen` counts what is finished, and the walk is named.
+            if budget is not None and budget.tick(
+                _seen, _total, unit="endpoints", stage="walking endpoints"
+            ):
                 break
             if ep.security is not None and ep.security.policy != "none_detected":
                 continue
@@ -635,12 +638,13 @@ class _GATE00XCustomGateAudit:
         sources = _read_java_sources(Path(root), cir)
         findings: list[SpringFinding] = []
         _token_total = len(tokens)
-        for _token_seen, token in enumerate(tokens, start=1):
+        for _token_seen, token in enumerate(tokens):
             # C3-79: the gate tokens are this family's population. Each one costs
             # three passes over the admissible sources, so the boundary between two
             # tokens is where a deadline can be honoured without a half-built pass.
             if budget is not None and budget.tick(
-                _token_seen, _token_total, unit="gate annotations"
+                _token_seen, _token_total, unit="gate annotations",
+                stage="resolving gate annotations",
             ):
                 break
             # C3-61, second measurement. The `token not in source` guard removed
@@ -1098,8 +1102,9 @@ def run_security_audit(
     _rules_partial = list(getattr(progress, "partially_run", []) or [])
     if _rules_partial:
         _cut = ", ".join(
-            f"{'/'.join(entry['rule_ids'])} after {entry['units_done']} of "
-            f"{entry['units_total']} {entry['unit']}"
+            f"{'/'.join(entry['rule_ids'])} while {entry['stage_stopped_in']}, "
+            f"after {entry['units_done']} of {entry['units_total']} "
+            f"{entry['unit']}"
             for entry in _rules_partial
         )
         _sec_limitations.append(

sourcecode/spring_tx_analyzer.py

@@ -189,10 +189,12 @@ class _TX001ProxyBypass:
         _seen_ids: set[str] = set()
         _declared = tx_index.all_declared
         _total = len(_declared)
-        for _seen, boundary in enumerate(_declared, start=1):
+        for _seen, boundary in enumerate(_declared):
             # C3-79: the declared boundaries are this family's population.
+            # C3-81: counted as finished, and the walk is named.
             if budget is not None and budget.tick(
-                _seen, _total, unit="declared boundaries"
+                _seen, _total, unit="declared boundaries",
+                stage="walking declared boundaries",
             ):
                 break
             if boundary.scope != "method":
@@ -793,9 +795,12 @@ class _TX006SelfInvocation:
         _seen_ids: set[str] = set()
 
         _total = len(body_facts)
-        for _seen, (caller_fqn, atoms) in enumerate(body_facts.items(), start=1):
+        for _seen, (caller_fqn, atoms) in enumerate(body_facts.items()):
             # C3-79: one method body per unit — the population this walk iterates.
-            if budget is not None and budget.tick(_seen, _total, unit="method bodies"):
+            # C3-81: counted as finished, and the walk is named.
+            if budget is not None and budget.tick(
+                _seen, _total, unit="method bodies", stage="walking method bodies"
+            ):
                 break
             if not isinstance(atoms, list):
                 continue
@@ -1046,8 +1051,9 @@ def run_tx_audit(
     _rules_partial = list(getattr(progress, "partially_run", []) or [])
     if _rules_partial:
         _cut = ", ".join(
-            f"{'/'.join(entry['rule_ids'])} after {entry['units_done']} of "
-            f"{entry['units_total']} {entry['unit']}"
+            f"{'/'.join(entry['rule_ids'])} while {entry['stage_stopped_in']}, "
+            f"after {entry['units_done']} of {entry['units_total']} "
+            f"{entry['unit']}"
             for entry in _rules_partial
         )
         _tx_limitations.append(

{sourcecode-4.14.0.dist-info → sourcecode-4.15.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.14.0
+Version: 4.15.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
@@ -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.14.0-blue)
+![Version](https://img.shields.io/badge/version-4.15.0-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`**
@@ -76,13 +76,31 @@ With the right command class, ASK Engine becomes **constant infrastructure** ins
 **Large-repo controls.** Pass `--progress stderr` (or `--progress file:run.log`)
 for line heartbeats in a non-TTY supervised run — with the file being read so
 far and an ETA for the stage being measured. `ASK_PROGRESS` sets the same thing
-in the environment. Long repo-wide/deep runs also write durable records under
-`~/.sourcecode/runs/<repo-hash>/` by default, not inside the audited repository;
-set `ASK_RUNS_IN_REPO=1` only when repo-local `.ask/runs` records are intentional.
-Set `ASK_MAX_ANALYSIS_SECONDS=<seconds>` to fail before starting a repo-wide/deep
-command whose configured budget is below its safe floor. Use
-`ask audit-report --from-risk risk.json` to package an existing risk run instead
-of recomputing it.
+in the environment, and the heartbeat is emitted by the analysis itself, not only
+by a timer thread, so a CPU-bound stretch is never silent. `--jobs N` / `-j`
+(env `ASK_JOBS`) sets the worker processes that parse files — default CPU count
+− 1; parallelism only warms the content-addressed parse cache, so the answer is
+byte-identical at any value. It does **not** parallelise the rule pass, which is
+where a repository-wide audit spends most of its time, and a warm cache leaves it
+nothing to parse — so raising it there buys nothing. Long repo-wide/deep runs also write durable records
+under `~/.sourcecode/runs/<repo-hash>/` by default, not inside the audited
+repository; set `ASK_RUNS_IN_REPO=1` only when repo-local `.ask/runs` records are
+intentional. Use `ask audit-report --from-risk risk.json` to package an existing
+risk run instead of recomputing it.
+
+**A budget is honoured, never a veto.** `ASK_MAX_ANALYSIS_SECONDS=<seconds>`
+bounds a repo-wide/deep command. A value below the class floor prints what that
+class typically needs and **runs anyway** — refusing to answer is the opposite of
+this product's doctrine. A run that spends its budget stops on the loop that is
+spending the time, not only between phases: a rule family cut in flight is
+published as `rules_partially_run` with how far it reached, families that never
+started are named in `rules_not_run`, `_partial` names the phases that completed
+and the ones that did not, and the findings measured before the cut are kept.
+The answer marks itself where the numbers are — `summary.partial`,
+`counts_are_floor`, `counts_basis` — and `confidence_level` is capped at `low`,
+because the confidence of the findings that exist says nothing about the family
+that did not run. Measured on BroadleafCommerce (2 766 Java files): a 4.5s budget
+stops at 1 408 files and ends at 5.1s.
 
 **What a warm actually covers.** `ask cache warm` runs the compact analysis: it rebuilds the
 shared structural layers (L1/L2 + the Repository Intelligence Snapshot + the shared Canonical
@@ -108,7 +126,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.14.0 — and, on a build that has aged,
+ask version                    # ask 4.15.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -204,6 +222,9 @@ ask verify /path/to/repo                      # then: only new violations block
 > A repository that starts declaring contracts already violates them somewhere; `ask verify`
 > is **baseline-relative by default** (`--fail-on new`) so the gate survives contact with
 > reality instead of being switched off on day one.
+> A pipeline wired before the contracts exist exits 2 (`unverified`, with
+> `unverified_reason` naming which state it is); `--allow-unverified` exits 0 while the
+> verdict stays `unverified` — the declared form of `|| true`, and violations still block.
 > `ask baseline capture|diff|trend` is a different thing: versioned architectural metrics over
 > time, for trend reporting rather than blocking.
 
@@ -324,7 +345,7 @@ from it.
 | `migrate-recipe` | experimental | the migration report as the OpenRewrite recipe that applies it | only recipes a finding named; the manual remainder published beside them; writes nothing without `--write`, and never a runnable command for an empty recipe list |
 | `data-exposure` | experimental | which routes can carry the data you labelled, and who reaches them | labels declared in `sourcecode.config.json` — never inferred from a name; `signature` and `call_reach` evidence published apart, field-level flow out of scope (NC-008). With nothing declared, `ask data-exposure /path/to/repo` answers `answered: false` and hands back the file, the key and an example to declare — it never reports zero exposed routes |
 | `endpoints` | core | every REST endpoint, effective path, security policy, confidence | Spring MVC + JAX-RS (~65 % recall on JAX-RS sub-resource locators). `--compact` answers the exposure census without the rows; `--servlets` lists the servlet-mounted surface as its own population; `--client-usage` says which routes the TS/JS client in this repository actually calls |
-| `spring-audit` | core | transactional anomalies + security configuration/exposure + validation gaps | `--ci`, `-f github-comment`; `--table --rule SEC-008 --top-n 20` for human-scale review |
+| `spring-audit` | core | transactional anomalies + security configuration/exposure + validation gaps | `--ci`, `-f github-comment`; `--table --rule SEC-008 --top-n 20` for human-scale review. Every run inventories its own rules — `rules_run`, `rules_not_run`, `rules_partially_run`, `rules_run_count`/`rules_total` — so "all of them" is a fact, not an assumption |
 | `migrate-check` | core | Boot 2→3 readiness + Java LTS/licensing inventory: located blockers, per-dimension score, effort, detected Java 8/11/17/21/25 evidence and explicit licensing-review signals | `--target-jdk 25` sets the target LTS route; `--blast-radius` orders the re-test plan; `--table --rule MIG-001 --band critical --top-n 20` for blocker triage |
 | `impact` / `impact-chain` | core | blast radius of a change, to the endpoints it reaches | target the **interface**, not the `Impl` |
 | `pr-impact` | core | the same, scoped to a PR diff | gating command: `--fail-on`, exit codes |
@@ -499,6 +520,25 @@ range, and errors: **no source code, paths, secrets, or output**. Turn it off ag
 > default you must remember to disable is the wrong default for third-party code. An explicit
 > choice you made before is unchanged.
 
+**A question is not a write — `--no-write` / `ASK_READONLY=1`.** One contract over
+every command: nothing is created inside the analysed repository, and a command
+that cannot answer without writing says so instead of writing. A refusal is never
+silent — each one names the path that was not created, on stderr. The scope is the
+tree you pointed at; the shared caches under `~/.sourcecode` and an `--output` path
+elsewhere on the machine are not refused, because refusing them would make the mode
+unusable without making it safer.
+
+Most commands read only, and the few that create anything inside the repository do
+it under `.ask/` and only behind an explicit flag (`baseline`, `migrate-check
+--history`, `verify --update-baseline`, `verify-edit --install-hook`, and `.ask/runs`
+when `ASK_RUNS_IN_REPO=1`). `ask --help` prints that list in full, generated from the
+one authority the battery checks — a write seam added without a row there fails the
+suite.
+
+```bash
+ask spring-audit /path/to/client-repo --no-write -o audit.json
+```
+
 **Custom security annotations.** Teach `endpoints`, `spring-audit`, and `explain` about
 project-specific authorization annotations via an optional `sourcecode.config.json` at the
 repo root (otherwise they report `policy: "none_detected"`):

{sourcecode-4.14.0.dist-info → sourcecode-4.15.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-sourcecode/__init__.py,sha256=qNowObAMVSm2IHYY_tkZt5xIhyBvBeJ4bDCcnIyty9Q,309
+sourcecode/__init__.py,sha256=Ub5mdlZZyGdFTJZvvfzvTcZgbEJ8EyeNf62l-V-LOP0,309
 sourcecode/adaptive_scanner.py,sha256=yJBKjNpkY6bpueYJ2YnRezen3sYZDecEt7WaaNWdqug,9466
 sourcecode/archetype.py,sha256=CZvRLpkHot_D8D3JFQVorr-EHDJyh0BbS7RnSTqBigM,40499
 sourcecode/architectural_baseline.py,sha256=4GiMVBLJVHvRKSWQGf2ZVurI1-R0qk5pmaevgvGSgVA,26325
@@ -18,7 +18,7 @@ sourcecode/chain_rules.py,sha256=Bi6UHfgd-GxWswmnHRcPz5jdbAuqka3Zkz_P-MTvqhw,127
 sourcecode/change_plan.py,sha256=aX1mp2XnlDN-8R2BcTiu8HlkDwQ_4fN1ZLckj0VMXHM,9945
 sourcecode/cir_graphs.py,sha256=9G0HHj1kw2325IDyzo2OpX73BNswEckecf4MZUXB4JM,12078
 sourcecode/classifier.py,sha256=JBzPwSSrDG-tUHAbcKB678HRbjLpD-ohzbzzO62mgpo,20114
-sourcecode/cli.py,sha256=eiUg6TKullRAlAdRnHTaCXfq3t_oLFRCXp9BTqOTvnc,595227
+sourcecode/cli.py,sha256=lUGvP4xPxLvTlKqMyqJhF-Lomls1L_qYijD6BpxcaQ4,597537
 sourcecode/client_calls.py,sha256=daRTgbXNUOfkzGXJpVb6A737R_Thhka8vw1_YgxCaLg,13548
 sourcecode/code_notes_analyzer.py,sha256=EJemNCNc9Dn-1RZYu-aNbK0ELzmsyC4s6FdHi3XyNEI,9392
 sourcecode/compare.py,sha256=2GdDy0qkDSgmkkpgvoCHitoLj3mt30EeFgJ8PGEXJng,14712
@@ -81,7 +81,7 @@ sourcecode/parse_cache.py,sha256=fhXnoaOgVWwp_8q0ngJ76UZ09qJ6uxDd0jaX8jdezvo,208
 sourcecode/path_admission.py,sha256=OGNSoluhVh8YYOBZBnACUrkmH4Tp_yxjGLifkcsxQpo,5838
 sourcecode/path_filters.py,sha256=LmTYq735orssKTIuxTX1mE1FHAXF7dVEJEse35xE1RA,12371
 sourcecode/perf.py,sha256=vZDEj1wS905peXmREdOniZrWCikElOyPTw-E32zVZAQ,25847
-sourcecode/phased_run.py,sha256=-rO31RnNc26oWTxwloURW6PydkMb-UW6jFO-wuUVN6w,10970
+sourcecode/phased_run.py,sha256=yrTV7qtGDwgOPw0wYEioLMCKwReAZPtml567n4SYED4,12750
 sourcecode/pipe_contract.py,sha256=PML0Er5d8uDyec4OrdUXuyqHbGPUYndjeaKUjkFz2u4,8369
 sourcecode/posture.py,sha256=cZ3By8LR-1bHfzyVpCDo2HHSAsCvePOmUc37E9GXYDw,76206
 sourcecode/pr_comment_renderer.py,sha256=239PmJdf95av_ZW236C7_tvq_ahECeuF9AZxrheJ4OQ,15573
@@ -95,7 +95,7 @@ sourcecode/readonly.py,sha256=dqGiNVvpfi4Ww8VzwUs6E3SdbqcHL1LFHItIK7IjrM0,5830
 sourcecode/reconciliation.py,sha256=GU-1PTcVr8zcbtC7BASfpHcZndP9AdboXPNQiBc0fzo,34251
 sourcecode/redactor.py,sha256=SB4hwIvg8h-hvcqKcDWaZvA-aSyn-at-BIRwa0tUv5E,3227
 sourcecode/reference_facts.py,sha256=Ns495c6eTmq2SrqPkcUrJUJru4_wj_yRWm4YDeJwves,13440
-sourcecode/release_info.py,sha256=dcCjnLmWzkI0LubNKqisdUxm6vwv9V3KP3zR7xloLZQ,5378
+sourcecode/release_info.py,sha256=4Jfym0xPvJpauhXDWLY2An8yIzae5OlAYZeUr24URsc,5378
 sourcecode/relevance_scorer.py,sha256=0AgEt4KrV73nioMqBgjhGjtY7L2C7L7cSyKtj3IKcrw,9408
 sourcecode/remedies.py,sha256=9eAuP9ndw78YvuUtOi2VvoeNnVCMh1q0uxfnPIkvx7c,7838
 sourcecode/rename_refactor.py,sha256=h6dNFlB9aZ_3q6heeHBkgXQeXaT03nvPSsYH6P8qxFg,12965
@@ -104,14 +104,14 @@ sourcecode/repository_ir.py,sha256=t1JNnk5g3ksfjkkrxaXZUKMyszw9zWEb6HQd-vlE3SE,3
 sourcecode/ris.py,sha256=SjjDNMcc9Zr9us9G8ikBVkoPXKK3BpM-dBodSGMh_g4,24783
 sourcecode/risk.py,sha256=jfhCIhxiAqHE0CUO3FZK_-m1bwu-o-yEZfQZrhKnvVs,58449
 sourcecode/rule_catalog.py,sha256=pTkgkQZ1u7atB3fkQJ9BPWo8lNiamvEuRN7MtRgle0c,5263
-sourcecode/rule_pass.py,sha256=qDH-FAc1uJvAN9Ud_7-utHR1oMmR1bpHN0wYzYzWcrA,11121
+sourcecode/rule_pass.py,sha256=lHk2Y9hp73th2Rh6yeJdOBQyVz9NQS3rTZKOiW7Ky1Q,13374
 sourcecode/runs.py,sha256=zIxEPz9DBVVCrX958bZR6bODyfH56A6srAyc8LFMs8I,5303
 sourcecode/runtime_classifier.py,sha256=uTAD6BDCiBLUZEDRfqk718kM4RTT_vAbfkcOI2_Xx58,18432
 sourcecode/sarif.py,sha256=3hQEegUxIZbojFdY59oB-yKsK-rnafHdTNmYsEP2--A,25984
 sourcecode/scanner.py,sha256=z3CV0rcGunu0Y8mpNgp07wI7nxT0pxw1BkXRRtI0Rpo,9609
 sourcecode/schema.py,sha256=aHNXDf8LGyUC8ZDE_VS9kiskC2-Oswhi_WnpdGy6HDw,24897
 sourcecode/security_config.py,sha256=KblMEoRiEjrIE68YsPaUAFebxFp8UM7MS7lAk5CGD8U,3531
-sourcecode/security_config_scan.py,sha256=aH71o6pVju1NJRg_fvz-5vwRzU1nDRLOxYo97xYNWd8,29311
+sourcecode/security_config_scan.py,sha256=dO_z9pquH3pypaZU5gL3eHuWx4rpLEUp5jQVUDZ6u6Y,29693
 sourcecode/security_posture.py,sha256=JH3v8HKBT4oBKaDCrxNOyrlYSleLlxQw_UgRJcvjX4c,51677
 sourcecode/semantic_analyzer.py,sha256=bpgdC6m0_ftVtRf3rSdwhbhWjnZnGxRXaZVcfe4BbcQ,95414
 sourcecode/semantic_impact_engine.py,sha256=t09IirGC3JjQDy33JZd1_WKzQVKXkoNl3-XEUr5kjis,20563
@@ -126,9 +126,9 @@ sourcecode/spring_impact.py,sha256=GW77k7KMn13QmzP5520BbVcXSCYlTFeD1bFibhbmzJM,8
 sourcecode/spring_model.py,sha256=zOAgFmrRbG4a6KLm1TJl55aWMyPNsz3OS3FSczqPG6A,16594
 sourcecode/spring_profiles.py,sha256=-kwrCK0O-MRjrCp6SA1d31t--o4Tg87iqPVrTwxoIUs,19605
 sourcecode/spring_properties.py,sha256=kPTk5qAJxdbHc1hclhHAP0O-hCIzBn8PTh3lzl-I4a4,8400
-sourcecode/spring_security_audit.py,sha256=5hIZUk5-0rFnLEc3nCB3gDCLLHoxxZoRl3PIAhyBXEs,55299
+sourcecode/spring_security_audit.py,sha256=0cS73BXaoFByJk4cMl3YqItPQ2xRUMu4XChURbKLCQo,55519
 sourcecode/spring_semantic.py,sha256=UrmLg_4gmBVmMqvSnUMgSReVEERVGv3X7LYDBEs6k_o,16598
-sourcecode/spring_tx_analyzer.py,sha256=ivKeXFTYAxa5sDoUrjGVf6MeGqKGPHjAOt__w3g0kpw,49134
+sourcecode/spring_tx_analyzer.py,sha256=4pUTaqqlsKRTBUr6tIwYP9oLamHz_IVKmLq3kFcH7Ww,49412
 sourcecode/summarizer.py,sha256=0aD4x3vgPngqBCEBKGuES1J2Vk5f7mqCm_ZWErwm3js,27025
 sourcecode/target_admission.py,sha256=wFZ4pzlxhiF6Q6s2lEAZEzcCfj1Y6xNvujjt8MdO0Qo,7154
 sourcecode/test_gap_ranking.py,sha256=hl-tTyQUXZGJycG1b6npbLeE_DaVHaOsvPwG9qqC5y8,15711
@@ -203,8 +203,8 @@ sourcecode/telemetry/consent.py,sha256=pQdl-QeLl6Gcibn0eWHSKZrm-HYSsjpVqOnjrgFp8
 sourcecode/telemetry/events.py,sha256=4_yeO58U-Cwc1Qb27VB0_EjhmroY0k91n3_VGxeALB8,2776
 sourcecode/telemetry/filters.py,sha256=RzxauTz8HliO4BllQnXEXc7zTeqdCZi5MgqGEDuW7OQ,6570
 sourcecode/telemetry/transport.py,sha256=4gGHsq0WeY9VywEZXA3vUxykfiYnw9uuqfjAAec7F8o,1681
-sourcecode-4.14.0.dist-info/METADATA,sha256=Wjh_U4ayRHzad0wUYf4R8zI6jsW12wn-diDUcqw5jTM,39250
-sourcecode-4.14.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-4.14.0.dist-info/entry_points.txt,sha256=-JEAdChrK5We51kZcb7OaDcyil-dHBjBPL-NhuO-QY8,89
-sourcecode-4.14.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-4.14.0.dist-info/RECORD,,
+sourcecode-4.15.0.dist-info/METADATA,sha256=Pej25eqhwMzbD468yWla-_e00Xg2fwKH5gRJmgBoMW8,42089
+sourcecode-4.15.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-4.15.0.dist-info/entry_points.txt,sha256=-JEAdChrK5We51kZcb7OaDcyil-dHBjBPL-NhuO-QY8,89
+sourcecode-4.15.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-4.15.0.dist-info/RECORD,,