sourcecode 4.10.7__tar.gz → 4.12.0__tar.gz

{sourcecode-4.10.7 → sourcecode-4.12.0}/CHANGELOG.md

@@ -2,6 +2,186 @@
 
 ## [Unreleased]
 
+## [4.12.0] — 2026-08-08
+
+**Field evaluation #16 — the third round on the same repository and commit, and the
+first A/B/C of three of our own releases (4.10.6 → 4.10.7 → 4.11.0, 7,0 → 7,0 →
+6,5).** The three value axes did not move: correctness 9,5, unique value 9,0,
+epistemic honesty 10, with `endpoints.json`, `servlets.json` and `validation.json`
+**byte-identical across all three builds**. What fell is engineering, and the
+sentence is about us: *"no es que haya regresiones — es que no hay nada que las
+detecte."* Nine rows close here, one commit each.
+
+**Behaviour changes to read before upgrading a pipeline:**
+
+- **`risk_score` and `risk_score_raw` are `null`, not `0.0`, when the container
+  invokes the queried component** (`@Configuration`, `@Aspect`, a registered
+  filter). The band already said `high` for these while the number said `0.0` — the
+  worst possible value for the most critical symbol in a system, from the same
+  object. `risk_score_basis` says why and names the surfaces that do measure such a
+  component. Affects `impact-chain`, `impact`, `plan` and `compare`; a consumer
+  reading the field with a `0.0` default now sees `null`.
+- **`ASK_MAX_ANALYSIS_SECONDS` actually stops a `spring-audit` rule pass.** It was
+  only ever checked between the three phases, and the last one holds ~85 % of the
+  time, so a 420 s budget produced a 2 351 s run and no `partial` anywhere. A cut
+  run now publishes `metadata.rules_not_run`, a `PARTIAL:` limitation, and
+  `_partial.phases_stopped_inside`. `metadata.rules_run` is present on every run.
+- **`migrate-check` no longer creates `<scope>/.ask/` unless you pass `--snapshot`.**
+  A read-only run left a git-ignored directory in the audited repository — invisible
+  to `git status`, visible only to `git status --ignored`.
+- **`verify` gains `--allow-unverified`** (exit 0 while the verdict stays
+  `unverified`) and publishes `unverified_reason`: `no_contracts_declared` or
+  `gate_could_not_run`. Exit codes are unchanged; the remedy is now the first reason.
+- **The parse cache retires generations.** Entries live under the producing
+  analyzer's fingerprint, and a run purges the generations that can never be read
+  again — the field measured +142,53 MB per release, three copies of one repository,
+  427,59 MB after three runs. `cache status` publishes the composition.
+
+**Also in this release:**
+
+- The rule pass reports the family it is on, counted against the total, and names
+  the two stages that have no population (`spring-audit` and `risk`). The ETA is
+  withheld there on purpose: rule families are not comparable units.
+- `risk` checkpoints — after the audit and every 25 composed rows — with the partial
+  file built by the same assembler as the answer, so it is the same document over
+  fewer rows.
+- The budget message stops quoting a class constant in the grammar of a
+  measurement. It carries this command's measured anchors and the size of the
+  repository in hand, and says plainly that no projection is offered. Anchors
+  recalibrated: `spring-audit` 408 s → 2 351 s at 3 342 files, `endpoints` 4,2 → 5,0,
+  `migrate-check --compact` 26,7 and `posture` 38,0 (both previously recorded as not
+  finishing), `risk` 3 232.
+- The MCP stack's incomplete-model warning no longer reaches stderr, and the models
+  it complains about are rebuilt rather than only muted.
+- A 772-line temp file (`cache.tmp_new`) was shipping inside the wheel; removed, and
+  the package contents are now asserted by allow-list.
+
+**Measured and not fixed, deliberately:** the block performance regression the
+evaluation reports (seven commands 2–3,4× slower on a minor) **does not reproduce
+here** — the A/B of 4.10.7 against 4.11.0 on a 2 985-file repository lands within
+1 % on six commands, with `posture --resolve-environments` byte-identical, and
+`risk` could not be A/B'd because the *4.10.7* side alone passed 61 minutes. Its
+cost is structural, not new. The numbers are in the ledger; the row waits on a
+Windows runner rather than on a guess.
+
+## [4.11.0] — 2026-08-07
+
+**The queue behind Tier D: five ledger rows, and three batteries that were red in
+the release before this one.** C3-59 · C3-56 (second half) · C3-52 · C3-60 (second
+half) · CL-15 close here, one commit each. Two of them were bigger than the row
+said, and both in the same direction — a flag that parses and does not check, a
+message that promises output nobody writes:
+
+- **`--format` was published by eleven commands that validated nothing**, so
+  `ask risk . --format bogus` answered with JSON as if the value had counted
+  (C3-59);
+- **`--detach` told the operator "progress and errors go to `log`"** and the log
+  held one line, because a detached worker has no terminal and the heartbeat
+  switched itself off exactly where it is the only way to tell work from a hang
+  (C3-52).
+
+⚠ **Behaviour changes to read before upgrading a pipeline:**
+
+- **An unsupported `--format` now exits 2** with the values that are valid, on
+  the eleven commands that used to accept anything and answer JSON. A script
+  passing a value that was never supported fails where it used to appear to work.
+- **`--format/-f` is accepted after 34 more commands**, including the 29
+  `retrieve` intents, `modernize`, `schema`, `onboard` and `fix-bug`.
+- **`ask config <path>` refuses a path that does not exist** (exit 1, the standard
+  envelope) instead of reporting "nothing is declared" about it.
+- **A detached run writes heartbeat lines into its own log** unless `--progress`
+  or `ASK_PROGRESS` says otherwise. Nothing changes for a foreground, piped or CI
+  run that does not ask.
+
+Three tests were **already red in 4.10.7** — each a battery that derives its
+population from the CLI, so C4-17's and C4-20's own changes tripped them — and
+they are fixed here. One of the three was not a test defect: it found `ask config`
+answering about a repository that does not exist.
+
+### Changed
+
+- **The `spring-audit` security section says what it is before it says what it
+  found** (CL-15). A field evaluation found the repository's critical SQL
+  injection by hand and ASK did not report it — correctly and by declaration
+  (NC-001: no dataflow) — but the section is announced as a *security surface*,
+  which invites reading it as a defect finder. The surface now states, from one
+  table rendered into both `--help` and the payload, that it reads the security
+  **configuration and exposure** (declared chain rules, open endpoints, disabled
+  controls, bypassable gates, each with file and line), that it is **not** a
+  vulnerability scanner, and where it is strongest: given a defect somebody else
+  found, `ask impact` and `ask risk` quantify what it reaches. The rule-family
+  label follows (`security surface` → `security configuration and exposure`). No
+  rule and no finding changed — this was always a naming defect.
+
+### Fixed
+
+- **`ask config <path>` refuses a repository nobody could read** instead of
+  reporting on it (C4-21 follow-up). The command gained a repository argument in
+  4.10.7 without the admission gate every other path-taking command uses, so
+  `ask config /nonexistent` answered *"Declaration: none at
+  /nonexistent/sourcecode.config.json"* with exit 0 — and *"nothing is declared
+  here"* is indistinguishable from *"nobody could look"*, which is the reading
+  ADR-0008 exists to prevent.
+
+- **`ask cache model` states which repository its figures were measured on, and
+  what that means for yours** (C3-60, second half). It published `verify-edit` as
+  *14,6 s → 9,6 s → 5,6 s* and called it *"built for the edit loop"* while the
+  same command had not answered at 495 s on the field repository — both
+  measurements, one printed. The command now measures the scope it is run in
+  (same authority as `--help` and the remedies), says whether the published
+  figures transfer to it, and gives each command a `here:` line saying how it can
+  be run on *this* repository. No figure changed and nothing is projected: an
+  unmeasurable scope gets the reference figures unqualified, as before.
+
+- **`--progress off | stderr | file:<path>` on every command that can make you
+  wait** (C3-52). The heartbeat existed and the watcher model everybody uses
+  could not see it: a supervisor reading the standard streams got nothing for
+  703 seconds unless it knew to set `ASK_PROGRESS=1` or to poll the run record —
+  knowledge that appeared in no `--help` and in no payload. The choice is now
+  published on the command being typed (62 commands, population from the
+  registry), `ASK_PROGRESS` still sets the same thing in the environment, and an
+  unrecognised value is refused with exit 2 rather than silently falling back to
+  the default. Nothing changes for a piped or CI run that does not ask.
+- **A detached run's log carries the progress its own envelope promises**
+  (C3-52). `--detach` printed *"Progress and errors go to `log`"* and the log
+  held one line, because a detached worker has no terminal and the heartbeat
+  disabled itself exactly where it is the only way to tell work from a hang. A
+  detached run now enables the heartbeat into its own log unless `--progress` or
+  `ASK_PROGRESS` says otherwise; no shell reads those bytes, so the PowerShell
+  `$?` problem (C3-66) cannot be reached from a detached run.
+
+- **The progress heartbeat carries a denominator and an ETA** (C3-56, second
+  half). `phase=auditing 3342 Java files elapsed=6.8m` said the run was alive and
+  nothing about whether it was worth waiting for; the field's only way to tell
+  work from a hang was reading the worker's CPU time. The line now reads
+  `phase=auditing 2766 Java files stage=parsing 1458/2766 files elapsed=2.0s
+  eta=1.8s eta_covers=parsing`, with the counts coming from the loops that read
+  the files rather than from the spinner. The ETA **names what it covers**
+  (nothing here knows the cost of the stages after the counted one), is withheld
+  until it can be measured, and is dropped when the phase changes rather than
+  freezing at `2766/2766`. A run with no heartbeat enabled is not asked to count.
+
+- **`-f` means `--format` on every command that publishes it, and every command
+  that answers with a payload document publishes it** (C3-59). `-f json` was
+  accepted by `endpoints` and `spring-audit` and refused by `modernize`, whose
+  error called `-f` a global flag *"as `ask -f <path>`"* — so the message taught
+  the collision it was meant to remove. The population is now the C4-17 rule one
+  level along (a payload command publishes `--format/-f`; a command that answers
+  in lines is exempt on the record in `cli.COMMANDS_WITHOUT_FORMAT`), and 34
+  commands gained the flag: `modernize`, `archetype`, `cold-start`, `schema`,
+  `onboard`, `fix-bug` and the 29 `retrieve` intents. One conversion in the emit
+  seam serves all of them, on the *stamped* document, so a YAML answer carries
+  the same `_meta` as the JSON one.
+- **An unsupported `--format` is refused instead of silently ignored** (C3-59).
+  Eleven commands published the flag and validated nothing — `ask risk .
+  --format bogus` answered with JSON as if the value had counted. Validation
+  moved into the shared option factory, keyed off the command being run, so a
+  command cannot publish the flag and skip the check;
+  `sourcecode.format_contract.FORMAT_REGISTRY` is the one authority for what
+  each command accepts, and an invalid value exits 2 with the values that are
+  valid. `rename-class` keeps `-f` for `--from` (on the record in
+  `COMMANDS_WITHOUT_FORMAT_SHORTHAND`); its long `--format` is unchanged.
+
 ## [4.10.7] — 2026-08-07
 
 **Tier D, and with it the M13 bug queue.** Five ledger rows close (C4-17 · C4-18 ·

{sourcecode-4.10.7 → sourcecode-4.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.10.7
+Version: 4.12.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.10.7-blue)
+![Version](https://img.shields.io/badge/version-4.12.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`**
@@ -73,8 +73,10 @@ These numbers are cache-layer benchmarks, not a promise for every command. Per-s
 
 With the right command class, ASK Engine becomes **constant infrastructure** inside agent loops — call the fast/context surfaces before edits and reserve deep compositions for the points where their evidence is worth the runtime.
 
-**Large-repo controls.** Set `ASK_PROGRESS=1` to get line heartbeats in non-TTY
-supervised runs. Long repo-wide/deep runs also write durable records under
+**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
@@ -106,7 +108,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.10.7 — and, on a build that has aged,
+ask version                    # ask 4.12.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -322,7 +324,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 surface + 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 |
 | `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 |
@@ -359,7 +361,21 @@ Honest limits worth knowing before you rely on it:
 - Architecture classification is tuned for Spring MVC layered apps; SPI/plugin models (e.g. Quarkus extensions) may be misclassified. JAX-RS subresource-locator endpoint recall is ~65%.
 - Self-invocation `@Transactional` bypass (same-class call skipping the proxy) is not detected.
 
-### What the security surface does not answer
+### What the security section is, and what it does not answer
+
+**What it reads:** the security *configuration and exposure* of a repository — which
+rules the request chain declares, which endpoints they leave open, which controls are
+present but disabled, and which custom gates can be bypassed, each with the file and
+line that says so.
+
+**What it is not:** a vulnerability scanner. No value flows through a program here, so
+an injection, a deserialization sink or a logic flaw inside a method body is not looked
+for, and its absence from the report is not evidence (NC-001, below).
+
+**Where it is strongest:** given a defect somebody else found — a scanner finding, a
+line from a review — `ask impact <symbol>` and `ask risk` quantify what it reaches: the
+endpoints, the transactional boundaries and the modules downstream of it, with the
+confidence of each hop. That is the question a taint scanner does not answer.
 
 Published because a product that states its limits is not compared on breadth — it is
 compared on depth. Each row is emitted in the payload too (`non_coverage`), so an agent

{sourcecode-4.10.7 → sourcecode-4.12.0}/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.7-blue)
+![Version](https://img.shields.io/badge/version-4.12.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`**
@@ -35,8 +35,10 @@ These numbers are cache-layer benchmarks, not a promise for every command. Per-s
 
 With the right command class, ASK Engine becomes **constant infrastructure** inside agent loops — call the fast/context surfaces before edits and reserve deep compositions for the points where their evidence is worth the runtime.
 
-**Large-repo controls.** Set `ASK_PROGRESS=1` to get line heartbeats in non-TTY
-supervised runs. Long repo-wide/deep runs also write durable records under
+**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
@@ -68,7 +70,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.10.7 — and, on a build that has aged,
+ask version                    # ask 4.12.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -284,7 +286,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 surface + 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 |
 | `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 |
@@ -321,7 +323,21 @@ Honest limits worth knowing before you rely on it:
 - Architecture classification is tuned for Spring MVC layered apps; SPI/plugin models (e.g. Quarkus extensions) may be misclassified. JAX-RS subresource-locator endpoint recall is ~65%.
 - Self-invocation `@Transactional` bypass (same-class call skipping the proxy) is not detected.
 
-### What the security surface does not answer
+### What the security section is, and what it does not answer
+
+**What it reads:** the security *configuration and exposure* of a repository — which
+rules the request chain declares, which endpoints they leave open, which controls are
+present but disabled, and which custom gates can be bypassed, each with the file and
+line that says so.
+
+**What it is not:** a vulnerability scanner. No value flows through a program here, so
+an injection, a deserialization sink or a logic flaw inside a method body is not looked
+for, and its absence from the report is not evidence (NC-001, below).
+
+**Where it is strongest:** given a defect somebody else found — a scanner finding, a
+line from a review — `ask impact <symbol>` and `ask risk` quantify what it reaches: the
+endpoints, the transactional boundaries and the modules downstream of it, with the
+confidence of each hop. That is the question a taint scanner does not answer.
 
 Published because a product that states its limits is not compared on breadth — it is
 compared on depth. Each row is emitted in the payload too (`non_coverage`), so an agent

{sourcecode-4.10.7 → sourcecode-4.12.0}/pyproject.toml

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

{sourcecode-4.10.7 → sourcecode-4.12.0}/src/sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "4.10.7"
+__version__ = "4.12.0"

{sourcecode-4.10.7 → sourcecode-4.12.0}/src/sourcecode/architectural_baseline.py

@@ -30,6 +30,7 @@ the perf baselines do.
 from __future__ import annotations
 
 import json
+import os
 import subprocess
 from datetime import datetime, timezone
 from pathlib import Path
@@ -365,21 +366,40 @@ def _baseline_filename(baseline: dict) -> str:
 #: a 14 587-entry structural inventory of the code. A self-confined
 #: `.ask/.gitignore` is the honest form: it never touches the user's own
 #: `.gitignore`, and it stops applying the moment they delete the directory.
+#: C3-74 corrected the last line. It used to read *"Delete this file to version
+#: them deliberately"*, and deleting it is the one action that would commit a
+#: baseline carrying `env.hostname_hash`, `cpu` and `cores` — an invitation to do
+#: the thing the file exists to prevent. It now states the consequence instead.
 _ASK_DIR_GITIGNORE = (
     "# Written by `ask` the first time it created this directory.\n"
     "# These are local analysis artefacts: a structural inventory of your code\n"
     "# and, if you asked for it, the machine that measured it. Nothing here\n"
-    "# belongs in a commit. Delete this file to version them deliberately.\n"
+    "# belongs in a commit.\n"
+    "#\n"
+    "# Removing this file makes everything here committable, including any\n"
+    "# recorded machine fingerprint (`--record-env`: hostname hash, CPU, cores).\n"
+    "# Version these deliberately only if you intend to publish that.\n"
     "*\n"
 )
 
 
-def protect_ask_dir(out_dir: Path) -> None:
+def protect_ask_dir(out_dir: Path, *, announce: bool = True) -> None:
     """Give a freshly created `.ask/` its own `.gitignore` (C3-68).
 
     Best-effort and never overwriting: a user who edited it decided something,
     and a tool that re-imposes its default on every run is worse than one that
     never wrote it.
+
+    **Call this where the write happens, never where the path is computed.** This
+    function *creates* the directory in order to protect it, so calling it
+    speculatively is a write — which is how `migrate-check` came to leave a
+    `.ask/.gitignore` inside a repository it had only read (C3-74).
+
+    `announce` puts one line on stderr the first time the directory is created,
+    with its path. A side effect inside somebody else's repository is exactly what
+    I-8 says must be declared, and this one hides from the check an auditor makes:
+    `git status --porcelain` is clean because the ignore file ignores itself, and
+    only `--ignored` reveals `!! <scope>/.ask/`.
     """
     try:
         ask_dir = Path(out_dir)
@@ -391,12 +411,35 @@ def protect_ask_dir(out_dir: Path) -> None:
             return
         marker = ask_dir / ".gitignore"
         if not marker.exists():
+            created = not ask_dir.exists()
             ask_dir.mkdir(parents=True, exist_ok=True)
             marker.write_text(_ASK_DIR_GITIGNORE, encoding="utf-8")
+            if announce and created:
+                _announce_ask_dir(ask_dir)
     except OSError:
         return
 
 
+def _announce_ask_dir(ask_dir: Path) -> None:
+    """One line, on stderr, naming what was created and how to move it (C3-74)."""
+    import sys
+
+    try:
+        # No flag is named here on purpose: the commands that write under `.ask/`
+        # spell the override differently (`baseline capture --dir`,
+        # `migrate-check --history-dir`), and a message that names the wrong one
+        # is the class of defect this ledger is about.
+        sys.stderr.write(
+            f"[ask] created {ask_dir}{os.sep} for this run's local artefacts — "
+            f"git-ignored by its own .gitignore, so `git status` will not show it "
+            f"(`git status --ignored` will). The command's directory option takes a "
+            f"path outside the repository if you want them elsewhere.\n"
+        )
+        sys.stderr.flush()
+    except Exception:
+        pass
+
+
 def write_baseline(baseline: dict, out_dir: Path) -> Path:
     """Write `baseline` as deterministic JSON under `out_dir`; return the file path."""
     out_dir.mkdir(parents=True, exist_ok=True)

{sourcecode-4.10.7 → sourcecode-4.12.0}/src/sourcecode/cache_model.py

@@ -75,10 +75,17 @@ class CommandCache:
     warm_seconds: "Optional[float]" = None
     #: The other measured point: this command on the field repository
     #: (3 342 Java files, Windows 11 / PowerShell 5.1 / pipx, cold), from field
-    #: evaluations #13 and #14. Seconds where a run finished; `field_blocked`
+    #: evaluations #13, #14 and #16. Seconds where a run finished; `field_blocked`
     #: where it did not — the harness promoted the process and the session died,
     #: which is a measurement of a different kind and is never written as a
     #: duration. Rows with neither were not attempted there.
+    #:
+    #: C3-72: where two evaluations of the same command at this size disagree, the
+    #: figure here is the **most recent** one, because it describes the build a
+    #: reader is about to run — and the previous figure is kept in the comment
+    #: beside it rather than dropped, since a cost that moved by 5,8× between two
+    #: releases (spring-audit, 408 s in #13 against 2 351 s in #16) is itself the
+    #: measurement C3-76 exists for.
     field_seconds: "Optional[float]" = None
     field_blocked: bool = False
 
@@ -93,19 +100,26 @@ REFERENCE_REPOSITORY = (
 REFERENCE_JAVA_FILES = 2000
 
 #: The other end of the measured range, and the reason this module publishes a
-#: *class* rather than a projected duration (C4-19). Field evaluation #13, on
+#: *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
-#: 3 342-file repository ran **408 s** — 46× the 8.8 s the same command takes on
-#: the 2 000-file reference. Cost does not scale with file count in any way this
-#: product has measured, so a projected "~15 s on your repository" would be a
-#: confident falsehood of exactly the kind the ledger exists to prevent. What can
-#: be said honestly is the class, the two measured anchors, and how to run it.
+#: 3 342-file repository ran **2 351 s** — 267× the 8.8 s the same command takes
+#: on the 2 000-file reference, for a repository 1,7× the size. Cost does not
+#: scale with file count in any way this product has measured, so a projected
+#: "~15 s on your repository" would be a confident falsehood of exactly the kind
+#: the ledger exists to prevent. What can be said honestly is the class, the two
+#: measured anchors, and how to run it.
+#:
+#: C3-72 replaced evaluation #13's 408 s with #16's 2 351 s here: the same command
+#: on the same repository at the same commit, measured three releases later
+#: (2 557 s in 4.10.6, 2 398 s in 4.10.7, 2 351 s in 4.11.0). The older figure was
+#: the one a budget message quoted as "~600s" for three releases while the
+#: measurement stood four times higher.
 FIELD_ANCHOR = (
-    "field evaluation #13: spring-audit on 3 342 Java files took 408 s "
-    "(Windows, pipx, cold) against 8.8 s on the 2 000-file reference"
+    "field evaluation #16: spring-audit on 3 342 Java files took 2 351 s "
+    "(Windows, pipx, warm cache) against 8.8 s on the 2 000-file reference"
 )
 FIELD_ANCHOR_JAVA_FILES = 3342
-FIELD_ANCHOR_SECONDS = 408.0
+FIELD_ANCHOR_SECONDS = 2351.4
 
 
 #: Every layer keys on `cache.worktree_signature` — the exact tree state (C1-9).
@@ -176,14 +190,15 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "Resolves the conditional bean graph on every run, over the shared CIR a warm "
                  "builds — the parse it used to repeat for itself. `--diff` compares two profile "
                  "sets over that one IR, so the second side costs the resolution only.",
-                 "10.1 s → 1.6 s", analysis_class="repo-wide", cold_seconds=10.1, warm_seconds=1.6, field_blocked=True),
+                 "10.1 s → 1.6 s", analysis_class="repo-wide", cold_seconds=10.1, warm_seconds=1.6, field_seconds=38.0),
     CommandCache("risk", ("cir", "parse"), "shared", False,
                  "Composes what the audit, impact-chain and the posture already answer, so it "
                  "pays each of their costs once over the shared CIR a warm builds — one parse "
                  "for the whole composition, and the reachability query is cached per symbol "
                  "within the run.",
                  "not measured on the battery yet — the composition is bounded by the "
-                 "`spring-audit` + `impact-chain` costs listed here, not by new analysis", analysis_class="deep"),
+                 "`spring-audit` + `impact-chain` costs listed here, not by new analysis",
+                 analysis_class="deep", field_seconds=3232.2),
     CommandCache("enrich", ("cir", "parse"), "shared", False,
                  "Runs the same composition as `risk` over the repository, then joins a SARIF "
                  "log to it. Reading the log is negligible; everything a warm helps with is the "
@@ -213,14 +228,14 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "Recomputes the endpoint surface on every run, over a parse a warm has already "
                  "paid for. Until 3.7.0 the extractor parsed every file itself instead of reading "
                  "the shared parse cache, and a warm measurably bought it nothing (C3-6).",
-                 "3.3 s → 1.4 s (re-measured on 3.7.0; was 2.8 s → 2.9 s)", analysis_class="repo-wide", cold_seconds=3.3, warm_seconds=1.4, field_seconds=4.2),
+                 "3.3 s → 1.4 s (re-measured on 3.7.0; was 2.8 s → 2.9 s)", analysis_class="repo-wide", cold_seconds=3.3, warm_seconds=1.4, field_seconds=5.0),
     CommandCache("spring-audit", ("ris", "parse"), "shared", False,
                  "Recomputes every run, but over a parse a warm has already paid for.",
-                 "8.8 s → 3.7 s", analysis_class="repo-wide", cold_seconds=8.8, warm_seconds=3.7, field_seconds=408.0),
+                 "8.8 s → 3.7 s", analysis_class="repo-wide", cold_seconds=8.8, warm_seconds=3.7, field_seconds=2351.4),
     CommandCache("migrate-check", ("cir",), "none", False,
                  "Computes its own inventory and shares nothing a warm builds. Only `--blast-radius` "
                  "reuses the shared CIR.",
-                 "4.8 s → 4.8 s", analysis_class="repo-wide", cold_seconds=4.8, warm_seconds=4.8, field_blocked=True),
+                 "4.8 s → 4.8 s", analysis_class="repo-wide", cold_seconds=4.8, warm_seconds=4.8, field_seconds=26.7),
     CommandCache("impact-chain", ("cir", "parse"), "shared", False,
                  "The CIR is the expensive half — this is where a warm pays most.",
                  "9.9 s → 1.7 s", analysis_class="core", cold_seconds=9.9, warm_seconds=1.7),
@@ -301,9 +316,59 @@ def layer(layer_id: str) -> Layer:
     raise KeyError(layer_id)
 
 
-def as_dict() -> dict:
+@dataclass(frozen=True)
+class Conditioning:
+    """The reader's repository, so the figures below are read against it (C3-60).
+
+    `verify-edit` is published here as *14,6 s → 9,6 s → 5,6 s* and described as
+    *"built for the edit loop"*; on the field repository the same command had not
+    answered at 495 s. Both are true, and printing only the first is what made
+    the second read as a defect in the reader's setup rather than as the scale
+    the figure was never measured at. The numbers do not change — what changes is
+    that they arrive with the repository they belong to, and with what is known
+    about the one in hand.
+
+    Built by the caller (`cli`) from `execution_plan`, which owns the scope
+    measurement; this module stays free of that dependency because
+    `execution_plan` already reads *it*.
+    """
+
+    scope: str                              # "3 342 Java files, cache cold"
+    transfers: "Optional[bool]"             # do the reference figures apply here?
+    per_command: "dict[str, str]"           # command → how it can be run here
+
+    def statement(self) -> str:
+        """One sentence about whether the figures below transfer to this scope."""
+        if self.transfers is None:
+            return (
+                f"This repository ({self.scope}) was not measured, so nothing below "
+                f"is claimed about it: the figures are the reference repository's."
+            )
+        if self.transfers:
+            return (
+                f"This repository ({self.scope}) is within the size the figures "
+                f"below were measured at ({REFERENCE_JAVA_FILES} Java files)."
+            )
+        return (
+            f"This repository ({self.scope}) is larger than the repository the "
+            f"figures below were measured on ({REFERENCE_JAVA_FILES} Java files), "
+            f"and cost has not been observed to scale with file count: "
+            f"{FIELD_ANCHOR}. Read each figure as the reference's, not as yours; "
+            f"the `here:` lines say how each command can be run on this one."
+        )
+
+
+def as_dict(here: "Optional[Conditioning]" = None) -> dict:
     """The whole model as data — what `ask cache model --json` emits."""
+    conditioned: dict = {}
+    if here is not None:
+        conditioned = {
+            "scope_measured": here.scope,
+            "reference_figures_transfer": here.transfers,
+            "conditioning": here.statement(),
+        }
     return {
+        **conditioned,
         "invalidation": (
             "Every layer keys on the exact tree state: any change to the analysed files "
             "invalidates it, committed or not. A clean tree keys on the commit, so a repeat "
@@ -334,6 +399,13 @@ def as_dict() -> dict:
                 "note": cmd.note,
                 "measured": cmd.measured or None,
                 "analysis_class": cmd.analysis_class,
+                # How this command can be run on the repository in hand, when one
+                # was measured. Absent rather than guessed otherwise (C3-60).
+                **(
+                    {"here": here.per_command[cmd.command]}
+                    if here is not None and cmd.command in here.per_command
+                    else {}
+                ),
                 "reference_seconds": (
                     None
                     if cmd.cold_seconds is None
@@ -366,7 +438,7 @@ def render_markdown() -> str:
     return "\n".join(out)
 
 
-def render_summary() -> str:
+def render_summary(here: "Optional[Conditioning]" = None) -> 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
@@ -376,6 +448,9 @@ def render_summary() -> str:
     own selling argument is token economy. That detail is still one flag away.
     """
     lines: list[str] = []
+    if here is not None:
+        lines.append(here.statement())
+        lines.append("")
     lines.append(
         "Invalidation: every layer keys on the exact tree state — any change to the "
         "analysed files invalidates it, committed or not."
@@ -396,6 +471,8 @@ def render_summary() -> str:
             f"  {cmd.command.ljust(cmd_width)}  {_WARM_LABEL[cmd.warm].ljust(warm_width)} "
             f"({repeat})  [{layers}]"
         )
+        if here is not None and cmd.command in here.per_command:
+            lines.append(f"  {' ' * cmd_width}  here: {here.per_command[cmd.command]}")
     lines.append("")
     lines.append(
         "Full detail (measured timings, per-command notes): ask cache model --full"
@@ -404,11 +481,14 @@ def render_summary() -> str:
     return "\n".join(lines)
 
 
-def render_text() -> str:
+def render_text(here: "Optional[Conditioning]" = None) -> str:
     """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] = []
+    if here is not None:
+        lines.append(here.statement())
+        lines.append("")
     lines.append("Invalidation — one rule for every layer")
     lines.append("  Every layer keys on the exact tree state. Any change to the analysed files")
     lines.append("  invalidates it, committed or not, tracked or not. A clean tree keys on the")
@@ -432,4 +512,6 @@ def render_text() -> str:
             lines.append(f"  {' ' * width}    measured: {cmd.measured}")
         if cmd.note:
             lines.append(f"  {' ' * width}    {cmd.note}")
+        if here is not None and cmd.command in here.per_command:
+            lines.append(f"  {' ' * width}    here: {here.per_command[cmd.command]}")
     return "\n".join(lines)