sourcecode 4.14.0__tar.gz → 4.16.0__tar.gz

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

@@ -2,6 +2,230 @@
 
 ## [Unreleased]
 
+## [4.16.0] — 2026-08-10
+
+**The Part 1 queue of field evaluation #19 — three rows, one commit each — and
+the round where reading the field's *numbers* against our source found more than
+reading its *conclusions* did.** The sixth measurement of the same repository at
+the same commit scored **8,2/10**, the highest of the series: *"4.15.0 es la
+mejor versión medida."* It verified both of the previous release's rows from the
+outside (C3-81's `stage_stopped_in`, C3-83's budget provenance), determinism held
+a **sixth** consecutive build across five version jumps, and five commands got
+much faster (`validation` −57 %, `posture --diff` −54 %).
+
+Two of the three complaints it left open turned out not to be what was filed.
+
+**Fixed in this release:**
+
+- **`risk` declares a budget and never asks whether it is spent (C3-87).** The
+  field filed `risk` at 2 842 s under a 420 s budget as a +41 % performance
+  regression. It is a consumer left unbound. C3-71 and C3-79 made the deadline
+  reach inside the rule pass and bound exactly one: `spring-audit` passes
+  `stop_when=_run.exhausted` at both of its call sites, while `risk` built the
+  same `PhasedRun`, with the same `budget_seconds` and the same `budget_source`,
+  and then constructed its observers with **no `stop_when` at all** — so
+  `should_stop()` answered `False` for the life of the run and the budget could
+  only be observed on the boundary between two phases. Their own two numbers
+  prove it on one machine under one budget: `spring-audit` **1,94×** over, `risk`
+  **6,8×** over. Reproduced here on keycloak (5 486 files) with a 5 s budget —
+  `spring-audit` stops at 9,9 s with `_partial` published; `risk` was still
+  running at **10 minutes, 120×**, and had to be killed. Both rule passes and the
+  composition join now ask, each on the unit it iterates. A cut run publishes the
+  floor marks **where the numbers are** (`partial`, `counts_are_floor`,
+  `counts_basis` — C2-31's rule applied to the second consumer), names the join's
+  own cut (`composition_stopped_after`), and says PARTIAL on the terminal. A
+  complete run gains no field. The three rule-pass keys of `_partial` move into
+  `PhasedRun.status`: for four releases there was one caller, so "the caller" and
+  "the authority" were the same object by accident, and a second consumer would
+  otherwise have duplicated thirty lines of composition or invented a second
+  vocabulary for one fact. **The battery asserts an absence**, because the defect
+  was one — a missing argument at a call site is invisible in the payload of the
+  command that omits it, so it reads `cli.py` and fails on any
+  `_rule_pass_progress(...)` built without `stop_when`. A third consumer cannot
+  be added unbound.
+
+- **A stage of an audit either counts its population or names itself (C3-85).**
+  Six rounds of field reports read the 14,5-minute silence as a dead emitter,
+  proposing that the timer be re-armed. Measured through the real seam, the
+  emitter is alive and correct: a per-unit tick loop produced **5 evenly spaced
+  lines over 5,4 s at a 1 s interval**. What is silent is the work no counter
+  covers — instrumented on keycloak, **8,2 s of a 24 s warm run, 34 %**, between
+  the last `linking` tick and the first rule tick, with `linking 5486/5486`
+  frozen on screen throughout; 2,7 s more inside `GATE-001`; 24,7 s on a cold run
+  after `parsing 50/5486`. Named, not counted: the IR build's tail (`assembling
+  the IR`, `recovering spec-declared routes`, `scanning XML security
+  configuration`), the semantic-model build, the whole-tree walk *inside* the
+  configuration family (through `FamilyBudget.stage`, so the line says which
+  family it belongs to), the rule pass's dedup-and-order tail, and each of the
+  five repository-wide walks `risk` makes before it composes. A single walk has
+  no population, and inventing a denominator for it is the fabrication C3-56
+  refused. The assertion is the invariant rather than the symptom: a build may
+  not end on a completed counter, because everything after it runs under a line
+  that reads as still running.
+
+- **A count that has stopped moving says so, and stops estimating (C3-86).** The
+  field's line — `3340/3342 java files eta=0.5s` — was written **fourteen
+  minutes** after the counter last advanced, and both of its halves are claims
+  the run cannot support: it asserts the stage is 99,9 % done *now*, and the ETA
+  divides the remaining units by a rate measured over a window in which nothing
+  happened, so the longer the stall lasted the more imminent the finish looked. A
+  line whose counted state has not advanced for a whole interval now publishes
+  `unchanged_for=<duration>` and withholds the estimate — the rule
+  `_eta_seconds` already applies to a stage too young to extrapolate from. The
+  count itself is still printed: it is true, and it is what a reader wants; what
+  is withheld is the assertion that it is current. The staleness clock is
+  deliberately not the stage clock — a long, healthy, advancing stage must not be
+  marked frozen, and both directions are asserted. An uncounted stage is never
+  called stale: it never claimed a denominator.
+
+**Measured and not reproduced:** the report's third proposed fix — *"corregir la
+documentación del flag `--jobs`"* — is already shipped. `JOBS_OPTION_HELP` in
+this build reads *"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."* The report quotes a
+truncated earlier string. Recorded on CL-18 so it is not re-opened, which is the
+CL-17 precedent.
+
+**Deliberately not in this release**, and each for a stated reason: **F-AT**
+(parallel rule evaluation — the field's single priority, *"lo único que separa
+este producto de un 9"*: a capability, and it does not start before this queue
+finishes), **F-AV** (a distinct exit code for a partial answer, or renaming
+`total_defects` to `total_defects_floor` when `partial` is true — a published
+contract change, never a side effect of a correction), **F-AU** (reusing the
+cached audit in the compositions), and **C3-76/F-AW** (the cross-version `risk`
+variance: macOS measures both sides flat for the second consecutive A/B, and a
+regression that reproduces on one platform cannot be bisected from the platform
+where it does not).
+
+**What C3-87 does not close, stated plainly: the wall time.** After the fix,
+`risk` on BroadleafCommerce (2 985 files) still runs past ten minutes under a 3 s
+budget, because the cost is not in the passes that now ask. That is **C3-88**,
+and it is open with a measurement rather than a hypothesis — the stage-by-stage
+profile was started and cancelled before it attributed the time, so the row says
+so instead of guessing.
+
+Suite **7 833** (7 813 before), 20 new assertions, zero failures.
+
+## [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.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.14.0
+Version: 4.16.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.16.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.16.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.16.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.16.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.16.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.16.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "4.14.0"
+version = "4.16.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.16.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.16.0"