sourcecode 4.12.0__tar.gz → 4.15.0__tar.gz

sourcecode-4.15.0/.github/workflows/perf-gate.yml

@@ -0,0 +1,109 @@
+name: Performance regression gate
+
+# F-AP. Field evaluation #16 measured seven commands 2-3.4x slower on a minor
+# release while every payload stayed byte-identical, and named the cause:
+# "no es que haya regresiones - es que no hay nada que las detecte".
+# This is the detector. The threshold, the repository and the gated command
+# population are declared in `sourcecode.perf` and documented in
+# `docs/perf/REGRESSION-GATE.md`; nothing here carries a number of its own.
+
+on:
+  schedule:
+    # Nightly, after the day's merges have settled.
+    - cron: "0 3 * * *"
+  workflow_dispatch:
+    inputs:
+      baseline_ref:
+        description: "Baseline directory under docs/perf/baselines (default: gate-latest)"
+        required: false
+        default: "gate-latest"
+
+concurrency:
+  group: perf-gate
+  cancel-in-progress: false
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    env:
+      # Declares the host class so nightly runs on ephemeral runners are
+      # comparable at all. Recorded in every artifact as `env.host_id_declared`,
+      # so the declaration is visible rather than silent.
+      SOURCECODE_PERF_HOST_ID: github-ubuntu-latest
+      BASELINE_DIR: docs/perf/baselines/${{ github.event.inputs.baseline_ref || 'gate-latest' }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install .
+
+      - name: Prove the gate is armed
+        # A green gate is evidence only when a red one is reachable in the same
+        # job with the same constants. This step fails if a synthetic 3x-slower
+        # cell would have passed.
+        run: python3 scripts/perf_gate.py --self-test
+
+      - name: Read the declared gate configuration
+        id: cfg
+        run: |
+          python3 scripts/perf_gate.py --print-config | tee gate-config.json
+          echo "repo_url=$(python3 -c "import json;print(json.load(open('gate-config.json'))['repository_url'])")" >> "$GITHUB_OUTPUT"
+          echo "repo=$(python3 -c "import json;print(json.load(open('gate-config.json'))['repository'])")" >> "$GITHUB_OUTPUT"
+          echo "mode=$(python3 -c "import json;print(json.load(open('gate-config.json'))['mode'])")" >> "$GITHUB_OUTPUT"
+          echo "runs=$(python3 -c "import json;print(json.load(open('gate-config.json'))['min_runs'])")" >> "$GITHUB_OUTPUT"
+          echo "commands=$(python3 -c "import json;print(' '.join(repr(c) for c in json.load(open('gate-config.json'))['commands']))")" >> "$GITHUB_OUTPUT"
+
+      - name: Clone the gate repository
+        run: |
+          mkdir -p fleet
+          git clone --depth 1 "${{ steps.cfg.outputs.repo_url }}" "fleet/${{ steps.cfg.outputs.repo }}"
+
+      - name: Measure
+        env:
+          PERF_FLEET_ROOT: fleet
+        run: |
+          python3 scripts/perf_harness.py \
+            --repos "${{ steps.cfg.outputs.repo }}" \
+            --commands ${{ steps.cfg.outputs.commands }} \
+            --modes "${{ steps.cfg.outputs.mode }}" \
+            --runs "${{ steps.cfg.outputs.runs }}" \
+            --fleet-root fleet \
+            --out perf-run
+
+      - name: Gate
+        run: |
+          python3 scripts/perf_gate.py \
+            --baseline "$BASELINE_DIR" \
+            --current perf-run \
+            --report perf-run/gate.json \
+            --table perf-run/RELEASE-TABLE.md
+
+      - name: Publish the measured table
+        if: always()
+        run: |
+          if [ -f perf-run/RELEASE-TABLE.md ]; then
+            {
+              echo "## Measured wall time per command"
+              echo
+              cat perf-run/RELEASE-TABLE.md
+            } >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+      - name: Upload artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: perf-gate-${{ github.run_number }}
+          path: |
+            perf-run/**
+            gate-config.json

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

@@ -2,6 +2,253 @@
 
 ## [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,
+one commit each.** The fourth measurement of the same repository at the same
+commit scored **7,5/10**, the highest of the series, and verified six of the
+previous release's fixes from the outside. Both rows it opened are in the fields
+that describe ASK's *own* reliability, which is where this product can least
+afford to be wrong.
+
+**Fixed in this release:**
+
+- **A truncated answer no longer raises its own confidence (C2-31).** Three
+  complete runs published 395 findings / 98 defects at `confidence_level:
+  medium`; the run the budget cut published 289 / 15 at **`high`**, because the
+  level is derived from the confidence of the high/critical findings *that
+  exist* and the family contributing the medium-confidence ones is the family
+  that did not run. `SpringAuditResult.partial` is now one flag — set by the
+  scopes, by the CLI for a phase that never started, and carried through
+  `merge` — and a partial answer is capped at `low` with `confidence_basis`
+  saying the cut is the reason. `summary` gains `partial`, `counts_are_floor`
+  and `counts_basis`, so the mark lives where the numbers a consumer reads are,
+  not only in `_partial` at the root. The cap is a ceiling and never a floor: a
+  complete run keeps its level and gains no fields.
+- **The rule inventory names rules, and both scopes' (C1-42).** `rules_run`
+  listed four SEC ids in a payload whose findings carried DEAD-001, SEC-008,
+  TX-006, TX-001, SEC-005 and SEC-006, and `rules_not_run` said `[GATE-001]`
+  where the arithmetic proves GATE-004 did not run either. The lists were keyed
+  on the pattern *object's* identity, so a family emitting six rules stood for
+  itself, and `merge` overwrote the TX scope's inventory with the security
+  scope's. `rule_pass.rule_ids_of()` is the one authority, the two lists are
+  unioned across scopes, and `rules_run_count` / `rules_total` sit beside them.
+  Three invariants are asserted over a real audit: every rule that fired is in
+  `rules_run`, the lists never overlap, and a complete `--scope all` run
+  inventories exactly `rule_catalog.ids()`.
+- **The heartbeat is emitted by the work, not only by a thread (C3-80).** Four
+  versions with the same shape: one line at `elapsed=20.1s`, 39 minutes of
+  nothing, then the same stage text seconds before the end. A line-mode
+  heartbeat printed only by a daemon thread depends on that thread being
+  scheduled during exactly the CPU-bound stretch the operator is asking about.
+  `Progress._emit()` is now one seam with one throttle and two callers — the
+  loop on its timer and the analysis in-band — sharing one `_last_emit` stamp,
+  so the line rate is unchanged and a running analysis is always heard from.
+- **The budget cuts inside a rule family (C3-79).** Budget 420 s, elapsed
+  2 376 s: `exhausted()` was asked on a whole-family boundary and one family
+  lasts 39 minutes. `RulePassProgress.tick()` reports counted work and answers
+  *"is the time spent"* in one call, sampling the clock once per 64 units; five
+  families that walk a population take a `FamilyBudget` and stop on a batch
+  boundary. A family cut in flight is in neither list — it is
+  `rules_partially_run` with the count it reached, and the findings it produced
+  are kept, because they were measured. Measured on BroadleafCommerce: a 4,5 s
+  budget stops at 1 408 of 2 766 Java files and ends at 5,1 s.
+
+**Verified in the field, not changed here:** `verify` exiting 2 without contracts
+is C3-75's deliberate half (the waiver `--allow-unverified` and the named
+`unverified_reason` are the fix; a distinct code is a contract change, F-AV), and
+the 4.10.7 performance that never came back is C3-76, which does not reproduce on
+this platform and waits on the Windows runner (F-AW).
+
+Suite 7 787.
+
+## [4.13.0] — 2026-08-08
+
+**The capability queue of Amendment M — the four features field evaluation #16
+asked for, one commit each, after Part 1 closed in 4.12.0.** The evaluation's
+verdict on engineering was *"no es que haya regresiones — es que no hay nada que
+las detecte"*, and its "if you could only do two things" was F-AP and F-AQ, in
+that order. Both ship here, with F-AR and F-AS beside them.
+
+**New in this release:**
+
+- **A release performance gate (F-AP).** `perf.gate_report()` turns a whole run
+  into one verdict against a whole baseline, and three of its four outcomes are
+  not a pass: a cell over the threshold **fails**, a baselined cell this run did
+  not measure **fails** (silence is how "nothing detects a regression" happens),
+  and a cell under the ADR-0006 sample floor **fails**. `scripts/perf_gate.py
+  --self-test` proves the gate is armed by failing a synthetic 3×-slower cell —
+  CI runs it *before* it runs the measurement, because a green gate is evidence
+  only when a red one is reachable on the same constants. Threshold **20 %**,
+  warm mode, one ~3 000-file repository, six repository-wide commands, and the
+  three exclusions published with every verdict. All of it lives in
+  `sourcecode.perf`; `docs/perf/REGRESSION-GATE.md` embeds `--print-config`'s
+  output verbatim and a test asserts they are the same bytes.
+- **The measured times are published, generated (F-AP, second rider).**
+  `perf.release_table()` builds the per-command / per-repository-scale table a
+  release note carries, from the run's own artifacts. An axis that was not
+  measured prints `unknown`, never `0`. And `cache model`'s figures now name the
+  build they were measured on (3.2.2) beside the build you are running, so a
+  table nine releases old cannot read as this build's measurement.
+- **`--jobs N` / `-j` / `ASK_JOBS` (F-AQ)**, default `cpu_count() - 1`. The
+  fourth consecutive evaluation to ask for parallelism was the first to sample
+  it: `threads=1`, `CPU/wall = 0,92…0,95`, 54 minutes, 20 cores. Worker
+  processes now parse files into the *same* content-addressed cache the IR loop
+  is about to read, so the loop is untouched and **byte-identity is structural,
+  not inspected** — no worker output reaches the payload by any route. Measured
+  on 2 766 Java files, both sides parse-cold with their own cache root: 5,36 s →
+  3,46 s (**1,55×**), CPU/wall 2,07, IR hash identical. Every failure mode — no
+  pool, a faulting worker, a frozen build, a disabled cache, a repository under
+  the 200-file floor — degrades to today's sequential parse and returns a receipt
+  naming the reason.
+- **`ASK_PARSE_CACHE_MAX_MB` (F-AR)**, default **512 MB**, least-recently-used,
+  enforced on write and published in `cache status` beside the size it bounds.
+  C3-70 retires the generation that can never be read again — an exact rule, and
+  exact rules only cover what they can foresee. This bounds what they cannot:
+  many repositories, many branches, one machine, and an owner who never runs
+  `ask cache clear`. Reads refresh recency (hourly granularity, so a hit is not a
+  disk write), an entry and its body-fact blob are evicted together, and
+  `ASK_PARSE_CACHE_MAX_MB=0` turns the guard off deliberately and says so.
+- **`--no-write` / `ASK_READONLY=1` (F-AS)** — nothing is created inside the
+  analysed repository, and a command that cannot answer without writing says so
+  instead of writing, in the same error envelope every other refusal uses.
+  Accepted by **every** command (consumed before the parser, the `--detach`
+  precedent), because a mode five commands accept and seventy-nine reject is a
+  mode whose one refusing run is the run that writes. Each refusal is announced
+  once on stderr with its path. Shared caches outside the repository are
+  untouched — an auditor is protecting a checkout, not a home directory.
+- **`ask --help` names every command that writes into the repository**, with the
+  condition beside it ("only with `--snapshot`"), generated from one authority.
+
+**Measured, not fixed, and said so:** the second half of F-AQ — *"one audit per
+run, shared by the compositions"* — was measured before being touched.
+Instrumenting `build_risk` on a real repository counts `run_tx_audit` **1×** and
+`run_security_audit` **1×**: `risk` already hands its findings to every impact
+chain it composes (C3-42-b), so the duplication the field named is between two
+*processes*, not inside one. That needs a persisted audit keyed on the worktree
+signature, and it is not in this release. What ships is the regression test that
+keeps the in-run property true.
+
 ## [4.12.0] — 2026-08-08
 
 **Field evaluation #16 — the third round on the same repository and commit, and the

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.12.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.12.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.12.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.12.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.12.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.12.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.12.0 → sourcecode-4.15.0}/pyproject.toml

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