sourcecode 4.14.0__tar.gz → 4.15.0__tar.gz

{sourcecode-4.14.0 → sourcecode-4.15.0}/CHANGELOG.md

@@ -2,6 +2,126 @@
 
 ## [Unreleased]
 
+## [4.15.0] — 2026-08-10
+
+**The Part 1 queue of Amendment O — the four rows field evaluation #18 opened,
+one commit each, plus one row closed by measurement.** The fifth measurement of
+the same repository at the same commit scored **8,0/10**, the highest of the
+series, and it is the first round where **performance moves**: `spring-audit`
+2 377,9 → **816,0 s** (40 minutes to 13,6), the whole fast path under 16 s, and
+the budget overshoot 5,66× → **1,94×**. It verified five of the previous
+release's fixes from the outside. Every row it opened is a **residue of a fix
+that landed**, which is what a fifth round on one subject produces.
+
+**Fixed in this release:**
+
+- **The heartbeat reports every unit; the clock still reads once per batch
+  (C3-82).** The field watched `1856/3342 java files` at 10,0 s, then **13,6
+  minutes with no line at all**, then `3328/3342`. C3-80 made the work emit
+  in-band and C3-73 gave the line its vocabulary, so the content was right —
+  what was wrong is that the only path to the emitter is
+  `RulePassProgress.tick()`, which returned early on a `done % sample_every`
+  remainder. A report falling between two boundaries 64 units apart is never
+  produced, so a stretch of expensive units is invisible for as long as it
+  lasts. One number was doing two jobs: the sampling constant belongs to the
+  **deadline** (a wall-clock budget buys no resolution from being asked 3 342
+  times instead of 52 — that is what took the overshoot to 1,94×) and not to the
+  **counter**, because `Progress` already throttles emission on an interval.
+  Asserted both ways: a thousand cheap units print at most one line, five units
+  that each outlast the interval print five.
+- **A cut rule family names the stage it stopped in, and no stage claims a
+  population it did not finish (C3-81).** `rules_partially_run` published
+  `units_done: 3342, units_total: 3342` — a complete population, in a list
+  meaning *"this family did not finish"* — while `DEAD-001` returned 248
+  findings against 254 on the complete run. The `SEC-004` group walks four
+  populations in sequence (Java sources, configuration files, deployment
+  descriptors, MyBatis mappers) and the entry recorded whichever one held the
+  deadline; and the counter reported the unit it was *about to* process, so a
+  walk stopped at its own last file published a finished population. Every walk
+  now ticks with what it has **finished** and names itself, the entry carries
+  `stage_stopped_in` and a `units_basis` stating that the two numbers count the
+  stage rather than the family, and the `PARTIAL:` sentence carries the same
+  fact as the payload.
+- **An inherited analysis budget says so, on the terminal and in the payload
+  (C3-83).** The same build answers 395 findings / 98 defects with no budget and
+  267 / 11 with `ASK_MAX_ANALYSIS_SECONDS=420`. The truncation is declared
+  impeccably — `_partial`, `summary.partial`, `counts_are_floor`, a confidence
+  capped at `low` — and the variable is inherited from a shell or a CI runner,
+  so whoever reads `total_defects: 11` is routinely not whoever set the limit.
+  The budget now carries its origin verbatim from where it is read to where it
+  is published: the measured under-floor warning gains a line naming the
+  variable and its value, a budget **over** the floor prints a single provenance
+  line saying what a cut run publishes and how to get a complete audit, and
+  `_partial` carries `budget_source` beside `budget_seconds`. A value that does
+  not parse is not a budget and invents no source. The distinct exit code for a
+  partial answer and any renaming of a truncated total remain a published-contract
+  change (F-AV), deliberately not done here.
+
+**Claims corrected:**
+
+- **`--jobs` states which phase it does not cover (C3-84 / CL-18).** The
+  evaluation sampled the process and corrected four rounds of its own reporting:
+  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 over a built IR), and on a warm cache there is
+  nothing left to parse at all. The help 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. `JOBS_OPTION_HELP` — the one string every command
+  declares the flag with — now says both; the README and the user guide are
+  qualifications of that claim rather than three versions of it; F-AQ's promise
+  (byte-identical at any value) is untouched. Making the rule pass itself
+  parallel is F-AT.
+
+**Measured, not assumed:**
+
+- **The three commands the field reports as regressed are flat here, for the
+  second consecutive A/B (C3-76c).** A/B/C of 4.10.7, 4.12.0 and HEAD on
+  BroadleafCommerce, each side with its own `HOME` and both cache roots, each
+  command warmed and then timed in isolation: `validation` 5,72 / 5,68 / 5,68 s,
+  `endpoints` 1,49 / 1,48 / 1,48 s, `posture --diff` 2,87 / 2,86 / 2,85 s. The
+  field measures the same three at 14,0 → 35,8 → 41,8 s, 3,5 → 4,2 → 4,7 s and
+  10,5 → 27,6 → 32,8 s. A regression that reproduces on one platform and not the
+  other cannot be bisected from the platform where both sides are equal; the
+  row's only open item is the Windows runner (F-AW).
+
+**Documentation:**
+
+The front-page catch-up written after 4.14.0 ships here too — no code, no
+`--help`, no output changed by it:
+
+- **README stated a budget rule the product stopped following in 4.10.6.**
+  `ASK_MAX_ANALYSIS_SECONDS` was described as failing a repo-wide/deep command
+  before it starts when the value is below the class floor; C3-55 made the floor
+  advice and the budget honoured, and C3-79 moved the cut inside the rule family.
+  The paragraph now says what the code does: below the floor it warns and runs,
+  a cut publishes `rules_partially_run` / `rules_not_run` / `_partial`, and the
+  answer marks itself with `summary.partial`, `counts_are_floor`, `counts_basis`
+  and a `confidence_level` capped at `low` (C2-31).
+- **`--no-write` / `ASK_READONLY=1` (F-AS, 4.13.0) reached the README**, beside
+  the third-party-audit note that is its audience. The list of what writes into a
+  repository is left to `ask --help`, which generates it from
+  `cli.COMMANDS_THAT_WRITE`, rather than copied into a second catalogue.
+- **`--jobs` / `-j` / `ASK_JOBS` (F-AQ) and the in-band heartbeat (C3-80)** added
+  to the large-repo controls; `verify --allow-unverified` with its named
+  `unverified_reason` (C3-75) added to the gate-adoption note; the `spring-audit`
+  row now names the rule inventory fields (C1-42).
+- **`docs/USER_GUIDE.md`**: the budget section still described a run stopping
+  *between phases* (4.12.0); it now describes the in-family cut. The flags table
+  gained the rows for `--jobs`, `--no-write` and `--progress`.
+
+- `docs/DEFECT-LEDGER.md` — rows C3-81, C3-82, C3-83, C3-84, claim CL-18 and
+  measurement C3-76c, with the five rows 4.14.0 closed marked verified in the
+  field; `docs/DEVELOPMENT-ROADMAP.md` — the eval #18 phase update;
+  `.planning/ROADMAP-STRATEGIC-2026-07-28.md` — **Amendment O**, which
+  respecifies F-AT from the field's own analysis: the unit of parallelism is the
+  **file inside the per-file families**, the reduction is the
+  `(category, defect_kind, symbol)` identity `defect_identity` already
+  publishes, and graph-scope families stay in a serial tail.
+
+**No behaviour changed for a complete run.** Answers stay byte-identical; what
+moved is the heartbeat's cadence, the metadata of a truncated run, and what the
+surface claims about `--jobs`.
+
 ## [4.14.0] — 2026-08-09
 
 **The Part 1 queue of Amendment N — the four rows field evaluation #17 opened,

{sourcecode-4.14.0 → sourcecode-4.15.0}/PKG-INFO

@@ -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 → sourcecode-4.15.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.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`**
@@ -38,13 +38,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
@@ -70,7 +88,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
 ```
 
@@ -166,6 +184,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.
 
@@ -286,7 +307,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 |
@@ -461,6 +482,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 → sourcecode-4.15.0}/pyproject.toml

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

{sourcecode-4.14.0 → sourcecode-4.15.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.14.0"
+__version__ = "4.15.0"

{sourcecode-4.14.0 → sourcecode-4.15.0}/src/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-4.14.0 → sourcecode-4.15.0}/src/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-4.14.0 → sourcecode-4.15.0}/src/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-4.14.0 → sourcecode-4.15.0}/src/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