sourcecode 5.3.0__tar.gz → 5.4.0__tar.gz

{sourcecode-5.3.0 → sourcecode-5.4.0}/CHANGELOG.md

@@ -2,6 +2,156 @@
 
 ## [Unreleased]
 
+## [5.4.0] — 2026-08-12
+
+**Fourteen rows from one audit, and the worst defect this ledger has recorded.**
+ASK 5.3.1 was audited in the field under a written non-persistence protocol —
+113 instrumented invocations, 50 of 51 non-prohibited commands, zero crashes,
+zero tracebacks, the repository byte-identical to its baseline at the end — and
+16 of its claims were cross-verified line by line against source. Thirteen held.
+Three did not, and one of those three is the headline of this release.
+
+**54,7 % of a monolith's HTTP surface was published as unguarded while carrying
+a live authorization annotation.** A handler whose `@RequestMapping` is declared
+on an abstract superclass was indexed under the *declaring* member, and the gate
+lives on the *override* — so 1 955 of 3 574 endpoints read `none_detected` with
+the annotation right there in source. It propagated to eight commands, ran in
+the unsafe direction, and it retires this project's own most-quoted figure: the
+"2 635 endpoints with no security policy" this repository has cited since
+evaluation #7 is really ≈659.
+
+### Fixed
+- **A handler keeps the gate it declares, not the one it inherits.** The
+  inheritance projection now names the member that *runs* (`effective_symbol`)
+  beside the one that declares the mapping, and every security lookup reads
+  both. The projection can only ever *add* a policy the override declares for
+  itself — the inherited verdict is never widened away. Second half, same root:
+  an inherited-mapping override was classified as a non-handler by the custom
+  gate predicate, putting the only members carrying the gate on the wrong side
+  of the specificity ratio and, on a repository where most controllers extend a
+  generic base, suppressing the gate outright.
+- **A SQL statement's identity is its namespace, not its bare name.** `risk`
+  published as the repository's #1 critical row a `${}` that cannot be exploited,
+  joined to a call trace that does not exist: tainted calls were matched to
+  mapper statements by method name alone, so a controller calling its own
+  service's `actualizar` was reported as reaching a mapper statement `actualizar`
+  in an unrelated namespace. The correct key was already written in the code and
+  unused. A call is now a statement's only when its receiver resolves to that
+  mapper; an unresolvable receiver leaves the sink `undecidable`, never
+  `reaches`. And the interpolated expression is finally read: an OGNL ternary
+  over two string literals is a closed allowlist by construction — precisely the
+  mitigation SEC-008's own `fix_hint` recommends — and leaves the sink
+  population into a published `bounded_interpolations` list.
+- **The security verdict is a fact about the tree, not about the shell.** Two
+  runs of `endpoints` over one unchanged tree returned two different censuses.
+  The programmatic-security fallback read a repository-relative path with no
+  root, resolving it against the process working directory: run from inside the
+  repository it read the file, run from anywhere else it cached a false. The
+  same scan could not tell code from prose — it matched `hasRole(` inside
+  `@PreAuthorize("hasRole('ADMIN')")`, a declarative gate on another method read
+  as runtime enforcement of this one. And a whole-file regex was preempting a
+  per-method gate on both surfaces.
+- **One definition of the working set per document.** `git_context.uncommitted_files:
+  1` sat beside `_cache.has_uncommitted_changes: false` in one payload. One
+  predicate now answers both, and what it excludes is published
+  (`uncommitted_files_not_read`) rather than subtracted in silence.
+- **A declaration that cannot be used says so.** A `sourcecode.config.json` with
+  an invented top-level key, a misspelt `dataLabels` and
+  `customSecurityAnnotations` as an array of strings ran completely clean —
+  `declaration.problems: []`, `declaration_problems: 0`, the two fields the
+  schema publishes for exactly this. `ask config` now distinguishes *not
+  declared* from *declared and unusable*, and prints the keys the file accepts
+  from the registry the loaders read.
+- **`impact` no longer prints the inverse of its own field.** `risk_level: high`
+  above "Low-risk isolated change" is gone; `risk_score` stays `null` where none
+  could be measured, and the floor the level asserts travels under its own name
+  so the row can still be ordered.
+- **A written tail is not a URL, and a comment is not a call.** A client call
+  whose head is an interpolation is no longer promoted to `broken_integration` —
+  the path matched against is the written tail and the head is unknown — and the
+  TypeScript extractor now blanks comments, so a commented-out documentation
+  placeholder is not admitted as a live call.
+- **`generate-tests` binds its budget on the clock a user reads.** 56,45 s to
+  enforce a 30 000 ms limit and return nothing: the abandoned walk was joined at
+  interpreter shutdown. It runs on a daemon thread now, and the default budget
+  is derived from the scope instead of being a constant measured against a walk
+  that no longer exists.
+
+### Changed
+- `--env-map`, `--code-notes`, `--dependencies` and `--architecture` say that
+  `--compact` and `--agent` already enable them, from one sentence in one place.
+- `repo-ir --force` names both guards it bypasses, in both units.
+- `--base-ref` also accepts `--since`; `verify --baseline` also accepts `-b`;
+  `baseline capture --dir` and `migrate-check --history-dir` accept each other's
+  spelling. Nothing is renamed. `--files` takes the same three shapes on every
+  command that has it, through one reader.
+- `docs/USER_GUIDE.md` and `docs/DEFECT-LEDGER.md` ship in the wheel, and the
+  surfaces that name them resolve the pointer from what is actually packaged.
+- `enrich` publishes the pipeline that feeds it (`trivy fs --format sarif` →
+  `ask enrich . --sarif`) in its own help and in the guide.
+- `untested_sources` declares the population it counts over and is present
+  whenever the ranking ran.
+
+### Added
+- `tests/test_cli_grammar.py` — one concept, one spelling, derived from the CLI
+  registry, with every exception declared and reasoned.
+- `tests/test_bundled_docs.py` — a document a surface names is a document this
+  build carries, asserted against the wheel manifest.
+
+Suite: **8 240 passed, 14 skipped.**
+
+## [5.3.1] — 2026-08-11
+
+**Six fixes from one field battery.** 5.3.0 was run over the 14 repositories in
+the field corpus — 22 commands each, plus the symbol-level commands and the
+edge-input battery. No command crashed on its own account: every non-zero exit
+was a well-formed input error. What the battery found instead is the class this
+series keeps returning to — two surfaces answering one question with two
+numbers, and a count published under the name of a population it does not count.
+
+### Fixed
+- **One admission authority for the route population.** `extract_java_endpoints`
+  filtered its Java files with `is_test_path` alone, while `find_java_files` —
+  which feeds the IR and therefore `spring-audit`, `impact`, `validation` and
+  `data-exposure` — also drops the `src/main` of a module that is itself test
+  infrastructure. Measured on jobrunr: `endpoints` published 3 annotation routes
+  from `quarkus-jobrunr-tests` that `spring-audit` could not see at all, 3
+  against `endpoints_analyzed: 0`, under the payload's own
+  `semantic_model_endpoints_note` declaring the two counts to be one figure. The
+  rule is now `repository_ir.is_test_source_file`, called by both builders
+  (jobrunr 14/3 → 12/0; every other repository in the corpus unchanged).
+- **A call site is an HTTP call only where an HTTP client is.** The Java
+  consumer-join matcher admitted `<receiver>.put|patch|delete|exchange("…")` on
+  any receiver — HTTP verbs, and three of the most common method names in Java.
+  Measured on eureka joined against open-banking-gateway: all 20 rows of
+  `calls_unresolved` were `Map.put` literals in one file, and a
+  `map.put("/x", v)` would have been published as a consumer calling `/x` — the
+  direction the module declares decisive. A file must now import or declare an
+  HTTP client type before its call sites are read.
+- **A snapshot that measured nothing reports unknown, not zero.**
+  `update_ris_api_surface` / `update_ris_spring_audit` write a stub snapshot so
+  their own section survives when no full one exists; `cold-start` read that stub
+  as a measurement. On alfresco-community-repo — 7 000+ Java files, 901
+  WebScripts — it answered `validation: {spring_detected: false,
+  controllers_found: 0, status: "valid"}` with every section empty. Now
+  `status: cold_start_incomplete`, `validation.status: empty_snapshot`, every
+  count `null`, with a statement naming what is unknown and how to build the
+  snapshot. A repository measured to have no Spring surface still reports its
+  zeroes — that is a fact.
+- **The scale signal counts files, and says files.** The headline sentence of
+  every Java summary ended with "N Java classes" while counting `.java` paths.
+  BroadleafCommerce is 2 659 Java files and 3 032 declared types, so the label
+  contradicted `repo-ir.analysis_meta.classes` in the same run.
+- **The human audit bundle prints counts, not Python objects.** The two
+  breakdown lines of the markdown report interpolated their dicts directly, so
+  the signed evidence bundle published `- Endpoint access: {'no_rule_matched':
+  676}` on keycloak, and a literal `None` for a section that was never measured.
+- **Bookkeeping never takes down a finished analysis.** `RunRecord.write` had no
+  guard on its terminal write, so a run directory that disappeared during the
+  analysis — a concurrent `ask cache clear`, a tmp reaper, an evicted cache —
+  raised `FileNotFoundError` out of the analysis scope's exit. Observed on
+  `audit-report`, which died with a traceback having already composed the report.
+
 ## [5.3.0] — 2026-08-11
 
 **The capability queue, built on the stable point.** 5.2.0 was the highest-scored

{sourcecode-5.3.0 → sourcecode-5.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.3.0
+Version: 5.4.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-5.3.0-blue)
+![Version](https://img.shields.io/badge/version-5.4.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`**
@@ -126,7 +126,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.3.0 — and, on a build that has aged,
+ask version                    # ask 5.4.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-5.3.0 → sourcecode-5.4.0}/README.md

@@ -4,7 +4,7 @@
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-5.3.0-blue)
+![Version](https://img.shields.io/badge/version-5.4.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`**
@@ -88,7 +88,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.3.0 — and, on a build that has aged,
+ask version                    # ask 5.4.0 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

sourcecode-5.4.0/docs/CACHE.md

@@ -0,0 +1,180 @@
+# Cache model — what a warm gives you, and what invalidates it
+
+Field evaluation #3 ran `ask cache warm` (103 s), watched `--compact` come back in 1 s, then
+watched `--agent --full --env-map --depth 20` take 171 s **after that warm**, and most of
+`prepare-context` behave as if no cache existed. Their verdict was not that the cache is slow:
+
+> *"El warm no es un warm general — el modelo de invalidación no está documentado y no es
+> predecible."*
+
+Two costs, and the second is the one that hurt: nothing told them which of their commands a
+warm would help. This page is the answer, and it is generated from the same table the CLI
+prints — run `ask cache model` for it in the terminal, `ask cache model --json` in a script.
+
+---
+
+## One rule for invalidation
+
+**Every layer keys on the exact tree state. Any change to the analysed files invalidates it —
+committed or not, staged or not, tracked or not.** A clean tree keys on the commit, so a repeat
+run with no edits hits. A tree without a git repository is signed by the size and mtime of its
+files and follows the same rule.
+
+That was not true before 3.2.2: the snapshot cache keyed on the committed HEAD, so an
+uncommitted edit was served the pre-edit answer (defect C1-9 in the
+[defect ledger](DEFECT-LEDGER.md)). If you are reading this because a stale answer surprised
+you on an older version, that is the bug, and upgrading is the fix.
+
+Two things invalidate everything, everywhere:
+
+- **An analyzer change.** A content hash of the analyzer's own source is in every key, so a new
+  release never serves an answer computed by the old logic.
+- **`ask cache clear`.** `--all` also drops the RIS.
+
+`--no-cache` skips the cache for one run without writing over what is stored.
+
+---
+
+## Where it lives
+
+| Path | Holds |
+|---|---|
+| `~/.sourcecode/cache/<repo-id>/` | snapshot cache (`core-*`, `view-*`), the RIS, `prepare-context` task answers |
+| `~/.sourcecode/ctx-*.json.gz` | the shared Canonical IR |
+| `~/.sourcecode/parse-cache-v1/` | the per-file parse cache |
+
+`SOURCECODE_CACHE_DIR` and `SOURCECODE_CONTEXT_CACHE_DIR` move them. Nothing leaves the machine.
+
+The cache is keyed to **the path you analysed**: `cache warm ./service-a` warms `service-a`, not
+the enclosing monorepo, and `cache status` / `cache clear` resolve to that same scope.
+
+---
+
+## The model
+
+<!-- BEGIN GENERATED: ask cache model --markdown -->
+| Layer | What it stores | What invalidates it | `cache warm` |
+|---|---|---|---|
+| `snapshot` | the rendered answer of the root command (L1 core analysis + L2 view) | tree state · analyzer fingerprint · analysis flags (--env-map, --depth, --docs, --exclude, …) for the core; presentation flags (--compact, --agent, --full, --format, …) for the view | built for the compact view (`--agent` also builds the agent view) |
+| `ris` | the Repository Intelligence Snapshot — structural index, endpoint index, summaries | tree state (the snapshot records the tree it describes) | rebuilt on every warm |
+| `cir` | the shared Canonical IR — the Java parse every knowledge command reuses | tree state · analyzer fingerprint · schema version | built |
+| `task` | one `prepare-context` task answer, per task and per option set | tree state · task · --symptom / --all / --include-config / --format | never — a warm does not run any task |
+| `parse` | the symbol extraction of one file, keyed by its bytes | the file's own bytes and the extractor's source — content-addressed, so it is never stale and never needs invalidating. Bounded by `ASK_PARSE_CACHE_MAX_MB` (default 512 MB, least-recently-used, enforced on write) and reported in `cache status` (F-AR) | filled for every Java file the warm parses |
+
+Measured on BroadleafCommerce (2 000+ Java files, dirty tree), warm machine, 3.2.2, each command in isolation.
+
+Measured on release 3.2.2. Figures are that build's on that repository, not a prediction for yours; the nightly performance gate (`docs/perf/REGRESSION-GATE.md`) is what re-measures them.
+
+The second anchor is the field one, and it carries its own build for the same reason (C3-97): field evaluation #26: spring-audit on 3 342 Java files took 31 s (Windows, pipx, mixed cache) against 8.8 s on the 2 000-file reference. Where a command was measured on an earlier release than the one you are running, `ask cache model` says so on that row rather than presenting the figure as this build's.
+
+| Command | A warm gives it | Measured (nothing cached → after a warm) | Repeat run cached | Layers | Notes |
+|---|---|---|---|---|---|
+| `ask (root)` | the answer | --compact 13.3 s cold → 0.3 s warm (cold re-measured on 3.7.0: was 19.3 s, C3-6); --agent --full --env-map --depth 20 34.7 s → 33.9 s (no gain) | yes | `snapshot`, `ris`, `parse` | `--compact` is what a warm stores by default; `--agent` needs `cache warm --agent`. `--env-map`, `--depth N` and `--exclude` change the *analysis*, so they miss the warmed core and rescan — the 171 s the field measured after a 103 s warm on 4.10.4. Eval #23 timed the same invocation at 72,3 s from a purged cache, and then paid 71,7 s again for `--agent` on the state it had just analysed (C3-103). |
+| `posture` | the shared work | 10.1 s → 1.6 s | no | `cir`, `parse` | Resolves the conditional bean graph on every run, over the shared CIR a warm builds — the parse it used to repeat for itself. `--diff` compares two profile sets over that one IR, so the second side costs the resolution only. |
+| `risk` | the shared work | not measured on the battery yet — the composition is bounded by the `spring-audit` + `impact-chain` costs listed here, not by new analysis | no | `cir`, `parse` | Composes what the audit, impact-chain and the posture already answer, so it pays each of their costs once over the shared CIR a warm builds — one parse for the whole composition, and the reachability query is cached per symbol within the run. |
+| `enrich` | the shared work | not measured on the battery yet — bounded by the `risk` composition, plus reading one JSON file | no | `cir`, `parse` | Runs the same composition as `risk` over the repository, then joins a SARIF log to it. Reading the log is negligible; everything a warm helps with is the repository side, so what it buys is what it buys `risk`. |
+| `audit-report` | the shared work | not measured on the battery yet — bounded by `risk` + `posture`, or by `posture` when `--from-risk` is supplied | no | `cir`, `parse` | Packages `risk` and `posture` evidence. A warm helps the repository side; `--from-risk risk.json` skips risk recomputation entirely and only builds the posture/report projection. |
+| `migrate-recipe` | the shared work | not measured on the battery yet — bounded by `migrate-check` on the same repository (openmrs-core ~2 s) | no | `parse` | Runs the same scan as `migrate-check` and projects its findings into an OpenRewrite recipe, so it buys exactly what a warm buys `migrate-check`: the parse, not the rule pass. |
+| `data-exposure` | the shared work | not measured on the battery yet — one `impact-chain` traversal per declared seed type over a CIR the warm already paid for | no | `cir`, `parse` | Walks the same call reach as `impact-chain` once per declared type and reads the endpoint security surface, both over the shared CIR a warm builds. Cost scales with the number of declared types, not with the size of the label. |
+| `endpoints` | the shared work | 3.3 s → 1.4 s (re-measured on 3.7.0; was 2.8 s → 2.9 s) | no | `ris`, `parse` | Recomputes the endpoint surface on every run, over a parse a warm has already paid for. Until 3.7.0 the extractor parsed every file itself instead of reading the shared parse cache, and a warm measurably bought it nothing (C3-6). |
+| `spring-audit` | the shared work | 8.8 s → 3.7 s | no | `ris`, `parse` | Recomputes every run, but over a parse a warm has already paid for. |
+| `migrate-check` | nothing | 4.8 s → 4.8 s | no | `cir` | Computes its own inventory and shares nothing a warm builds. Only `--blast-radius` reuses the shared CIR. |
+| `impact-chain` | the shared work | 9.9 s → 1.7 s | no | `cir`, `parse` | The CIR is the expensive half — this is where a warm pays most. |
+| `impact` | the shared work | 4.9 s → 2.8 s | no | `parse` | — |
+| `pr-impact` | the shared work | not timed | no | `parse` | Diff-dependent: the answer itself is never stored. What it costs follows the diff, not the repository: 12,5 s on an ordinary one and 11,8 s on a diff of security configuration, measured at field scale. |
+| `verify` | nothing | not timed | no | — | Runs the contracts against a fresh reading. |
+| `verify-edit` | the shared work | 14.6 s → 9.6 s → 5.6 s on repeat | yes | `parse` | Built for the edit loop: the parse cache is what keeps an unchanged file out of the next run. Its own second run is faster again. At field size that loop is not short yet: eval #23 measured 76,6 s on a tree with no edits, because the HEAD side is still built in a throwaway worktree instead of reusing the shared CIR (C3-102). |
+| `review-pr` | nothing | 1.1 s → 2.3 s (slower) | no | `cir` | Diff-dependent, and it reuses the CIR only if one exists. On a small diff, loading the warmed CIR costs more than the work it saves. |
+| `plan` | the shared work | 9.3 s → 3.8 s | no | `parse` | — |
+| `compare` | the shared work | not timed | no | `parse` | — |
+| `delta` | nothing | not timed | no | — | Analyses two states — two checkouts, or two refs materialised into temporary trees; neither is the tree the cache describes. |
+| `contract-diff` | nothing | not timed | no | — | Analyses two states (checkouts or refs); neither is the tree the cache describes. |
+| `fix-bug` | nothing | not timed | yes | `task` | Shorthand for `prepare-context fix-bug`; caches its own answer, which a warm never runs. |
+| `rename-class` | nothing | not timed | no | — | — |
+| `prepare-context` | the answer | onboard 6.5 s → 0.3 s with a warm — but a second run with NO warm recomputes (10.2 s → 9.4 s at 5 486 files; C1-40) · refactor 7.7 s → 7.7 s (0.3 s on repeat) · generate-tests 12.4 s → 11.0 s (0.3 s on repeat) | yes | `task`, `ris`, `cir`, `parse` | Per task: `onboard` and `explain` are served from the RIS a warm rebuilds; `refactor`, `fix-bug` and `generate-tests` cache their own answer, but a warm does not run them, so their first call pays full price; `delta` and `review-pr` are diff-dependent and never cached. |
+| `onboard` | the answer | with a warm: 6.5 s → 0.3 s (2 000 files) · 10.2 s → 0.7 s (5 486 files). WITHOUT a warm, a second identical run: 10.2 s → 9.4 s (5 486 files) — no answer hit | no | `task`, `ris` | Shorthand for `prepare-context onboard`. A warm stores its answer; the command does NOT store its own, so a second run without a warm pays full price. C1-40: the field read `repeat cached` here, ran it twice with no warm, and measured 56 s then 23,5 s — this row said it would be a hit. |
+| `explain` | the shared work | 9.8 s → 1.6 s | no | `cir` | Serves from the shared CIR a warm builds. |
+| `export` | the shared work | 8.8 s → 3.7 s | no | `parse` | — |
+| `repo-ir` | the shared work | 5.1 s → 2.9 s | no | `parse` | Carried as *did not finish* from 4.10.4 until eval #23 ran it at field size in 9,8 s — a run that did not finish once is not a command that cannot finish (C3-100, and the same correction `modernize` needed). |
+| `validation` | the shared work | 11.6 s → 6.4 s | no | `parse` | — |
+| `modernize` | the shared work | 5.2 s → 3.0 s | no | `parse` | Blocked in the session that recorded C3-53 and measured since: a run that did not finish once is not a command that cannot finish. |
+| `chunk-file` | nothing | not timed | no | — | Reads one file; nothing to cache. |
+| `cold-start` | the answer | 0.2 s either way | yes | `ris` | Reads the RIS a warm rebuilds — that is all it does. Without one it answers `no_ris` instead of a snapshot. |
+| `timeline` | nothing | not timed | no | — | Each sample is a fresh materialisation of a different commit, so nothing is shared between samples: two commits are two trees, and a cache keyed on a tree state can only ever serve one of them. The per-sample cost is measured and published in the payload. |
+| `trend` | nothing | not timed | no | — | Reads stored baseline artifacts from disk; analyses no source, so no cache layer applies. Same command as `baseline trend`. |
+| `baseline` | the shared work | capture 8.7 s → 3.6 s | no | `parse` | `capture`/`diff`/`trend` over architectural metrics. The field figure is `capture`, the subcommand that analyses; `trend` reads stored artifacts and has its own row. |
+| `retrieve` | the shared work | not timed | no | `cir`, `parse` | Every query builds or reuses the shared CIR a warm builds. |
+| `archetype` | the shared work | 9.3 s → 5.6 s | no | `parse` | — |
+| `activate` | nothing | not timed | no | — | Not an analysis. |
+| `auth` | nothing | not timed | no | — | Not an analysis. |
+| `cache` | nothing | not timed | no | — | Operates on the caches themselves. |
+| `config` | nothing | not timed | no | — | Not an analysis. |
+| `mcp` | the shared work | not timed | yes | `snapshot`, `ris`, `cir`, `parse` | Serves the same commands over MCP, with the same layers. |
+| `schema` | nothing | not timed | no | — | Prints registries; reads no repository. |
+| `telemetry` | nothing | not timed | no | — | Not an analysis. |
+| `version` | nothing | not timed | no | — | Not an analysis. |
+<!-- END GENERATED -->
+
+---
+
+## What this costs in CI
+
+A pipeline with no persisted cache directory pays the cold price **every run** — the cache is on
+disk, not in the repository, so a fresh container starts cold whatever you did yesterday.
+Measured on BroadleafCommerce (2 000+ Java files, dirty tree, warm machine):
+
+| Run | Nothing cached | After `cache warm` | Repeat |
+|---|---|---|---|
+| `ask --compact` | 17.7 s | **0.3 s** | 0.3 s |
+| `ask --agent --full --env-map --depth 20` | 34.7 s | 33.9 s | 0.3 s |
+| `endpoints` | 2.8 s | 2.9 s | 2.8 s |
+| `spring-audit` | 8.8 s | 3.7 s | 3.6 s |
+| `posture` | 10.1 s | **1.6 s** | 1.6 s |
+| `migrate-check` | 4.8 s | 4.8 s | 4.8 s |
+| `impact-chain` | 9.9 s | **1.7 s** | 1.7 s |
+| `explain` | 9.8 s | **1.6 s** | 1.6 s |
+| `prepare-context onboard` | 6.5 s | **0.3 s** | 0.3 s |
+| `prepare-context refactor` | 7.7 s | 7.7 s | **0.3 s** |
+| `prepare-context generate-tests` | 12.4 s | 11.0 s | **0.3 s** |
+
+`cache warm` itself took **18 s** on that repository, and it reports its own elapsed time when it
+finishes, precisely so the figure is in front of whoever writes the pipeline. On the 3 342-file
+monolith of field evaluation #3 the same warm took 103 s and a cold `--agent --full --env-map
+--depth 20` took 171 s.
+
+Read the table twice. A warm is worth most to `--compact`, `impact-chain`, `explain`, `posture`
+and `prepare-context onboard`; it is worth **nothing** to `endpoints` and `migrate-check`, and the
+`prepare-context` tasks that are not `onboard`/`explain` only get fast on their *own* second run,
+which a warm cannot trigger for them. If your pipeline runs `endpoints` and `migrate-check`, a
+warm is 18 s you will not get back.
+
+Three ways to spend less:
+
+1. **Persist `~/.sourcecode` between jobs** (cache the directory in your CI). Then only the files
+   that changed are re-derived.
+2. **Warm the view your pipeline consumes**, not the default one — `cache warm --agent` if the
+   pipeline reads `--agent`.
+3. **Ask for the command you need**, not for `--full`. `--full` and a raised `--depth` change the
+   analysis, so they are a different, colder question than `--compact`.
+
+---
+
+## Reading the freshness of an answer
+
+Every root-command payload carries `_cache`:
+
+```json
+"_cache": {
+  "cache_source": "L2_view",
+  "git_head_at_generation": "45649e0",
+  "current_git_head": "45649e0",
+  "is_stale": false,
+  "has_uncommitted_changes": true,
+  "generated_at": "2026-07-29T04:57:39Z",
+  "data_scope": "COMPACT"
+}
+```
+
+`cache_source` is `fresh` when the run computed the answer, and `L1_core` / `L2_view` when it was
+served. `ask cache status` reports what is stored for a repository, and `ask cache freshness`
+reports how far the RIS is from the current HEAD.

sourcecode-5.4.0/docs/COMMERCIAL-OFFER.md

@@ -0,0 +1,115 @@
+# ASK Engine — Commercial Offer
+
+The single, coherent Free/Pro offer, defined by **customer value** (not technical
+difficulty). Companion to [`PRODUCT_TIERS.md`](PRODUCT_TIERS.md) (the mechanical split)
+and [`MODERNIZATION.md`](MODERNIZATION.md) (the flagship product narrative). CLI command:
+`sourcecode`.
+
+## The one-sentence offer
+
+> **ASK Engine answers the expensive questions about a large Java codebase —
+> deterministically, with the source to prove it. Free on normal repos; Pro when the
+> work gets enterprise-scale or automated.**
+
+The gating axis is **size + automation**, never capability. Nothing is crippled on Free;
+you pay exactly when the tool is replacing the most engineering time — a monolith above
+**500 Java source files**, or CI/CD automation. **€19/mo · €190/yr, per developer.**
+
+---
+
+## The offer by capability
+
+Each capability framed as a customer job. "Free part / Pro part" is the same size axis:
+full on repos ≤ 500 Java files; Pro on enterprise-scale monoliths (and CI automation).
+
+### 1. Impact — "what breaks if I change this?"
+*Commands: `impact`, `impact-chain`, `review-pr`, `pr-impact`, `fix-bug`.*
+- **Problem:** before touching a monolith, know the blast radius — callers, endpoints,
+  transactional and security surface — without guessing.
+- **Buyer:** enterprise developer, tech lead.
+- **Why pay:** on a codebase too large to hold in your head (or an LLM's context), a
+  precise, source-backed change-risk answer prevents expensive mistakes. This is the moat
+  — determinism where LLMs hallucinate and grep can't follow the logic.
+- **Free:** full power on repos ≤ 500 Java files.
+- **Pro:** enterprise-scale monoliths + CI automation (`review-pr --format github-comment`).
+
+### 2. System Map — "what is this system, and what does it talk to?"
+*Commands: `onboard`, `export` (`--c4`/`--module-graph`/`--integrations`), `endpoints`, `spring-audit`, `explain`.*
+- **Problem:** understand an unfamiliar monolith — module structure, endpoints, external
+  integrations — fast.
+- **Buyer:** architect, newly-onboarded engineer.
+- **Why pay:** an accurate, current map of a system nobody fully understands; onboarding
+  in days, not months.
+- **Free:** full on ≤ 500 Java files.
+- **Pro:** enterprise-scale + rich/CI-consumable exports.
+
+### 3. Modernization — "are we ready to upgrade, and what blocks us?"  ← flagship
+*Commands: `migrate-check` (readiness), `validation`; see [`MODERNIZATION.md`](MODERNIZATION.md).*
+- **Problem:** Boot 2→3, javax→jakarta, Hibernate 5→6, JDK and dependency readiness — a
+  budgeted, deadline-driven project full of unknowns.
+- **Buyer:** platform/architecture lead with an allocated upgrade budget.
+- **Why pay:** turn a months-long unknown into a measured plan; this is the capability
+  tied most directly to a funded project — the clearest willingness-to-pay.
+- **Free:** the **readiness assessment** at any size (see freemium decision below).
+- **Pro:** the **full remediation detail + effort plan** on enterprise-scale monoliths.
+
+### 4. Agent Platform — "give my AI agents ground truth."
+*Commands: `mcp`, `repo-ir`, `cold-start`, `prepare-context`.*
+- **Problem:** AI coding agents re-parse the repo every session and hallucinate structure.
+- **Buyer:** teams using AI coding agents (Claude Code, Cursor, Copilot).
+- **Why pay:** deterministic, cached, source-backed context — and CI automation on every PR.
+- **Free:** local `mcp serve`, `cold-start`, and 30 `prepare-context delta` runs/repo.
+- **Pro:** delta automation beyond the free quota (the CI/CD axis) + `generate-tests` at scale.
+
+---
+
+## Decision: `migrate-check` is FREEMIUM
+
+**Question:** should `migrate-check` be fully Free, fully Pro, or freemium?
+
+**Decision: FREEMIUM** — the assessment is Free at any size; the full at-scale detail is Pro.
+
+**Justification (customer value, not technique):**
+- `migrate-check` is the **buy-trigger**: it maps to a budgeted upgrade project. The
+  *assessment* (a readiness score, the dimension breakdown, the headline blocker) is what
+  creates the *"we have a problem, let's fund this"* moment. **Gating the assessment fully
+  to Pro hides the hook and kills conversion** — the buyer never discovers the value on
+  their real monolith.
+- Fully Free, however, gives away the high-value deliverable — a complete, actionable
+  remediation plan on a 5,000-file monolith — for nothing.
+- **Freemium resolves both:** the diagnosis is free everywhere (maximizes discovery); the
+  detailed, at-scale, actionable plan is the paid deliverable. This mirrors the existing
+  capped-preview model (`fix-bug` top-5, `modernize` structural-only on large repos), so it
+  introduces **no new gating axis** — just the same size axis applied to `migrate-check`.
+
+**The exact split:**
+
+| Signal | Free (any size) | Pro (repos > 500 Java files) |
+|--------|-----------------|------------------------------|
+| `readiness_score` + per-dimension scores (jakarta/boot3/jdk/hibernate) | ✅ | ✅ |
+| `headline_blocker`, `blocking_count`, `applicable_dimensions` | ✅ | ✅ |
+| summary counts (`total_findings`, `by_severity`) | ✅ | ✅ |
+| **full `findings` detail** (per-file, per-rule, code context) | preview (top-N) on large repos | ✅ full |
+| **`effort_breakdown` / estimated effort plan** | — on large repos | ✅ |
+| `hygiene_findings`, `non_blocking` detail | — on large repos | ✅ |
+
+On repos ≤ 500 Java files everything stays free (the model's promise). On enterprise
+monoliths, a Free user gets the **score + a top-N findings preview + an upgrade prompt** —
+enough to see the value and justify the budget.
+
+**Implementation note.** The paywall is currently OFF (`_PRO_UNLOCK_ALL`), so this gate is
+dormant. The capping is specified as a concrete step in
+[`RC1-CHECKLIST.md`](RC1-CHECKLIST.md) / [`RELEASE-CHECKLIST.md`](RELEASE-CHECKLIST.md), to
+land **together with paywall reactivation** (where it is exercised and tested end-to-end).
+It is byte-neutral under the current unlock: with everyone floored to Pro, `migrate-check`
+output is unchanged, so the reference-repo oracles do not move.
+
+---
+
+## Pricing
+
+**€19/mo · €190/yr, per developer.** Self-serve, no metering, no sales motion. Sits at the
+floor of the closest comparable (CodeScene $20–30/dev/mo) and matches dev-tool norms
+(Cursor/Copilot $10–20/mo). ASK Engine is a focused CLI, so pricing at — not above — the
+comp floor maximizes adoption. Enterprise (multi-repo, SSO, dashboards) is a future,
+separately-sold SKU — not advertised until it exists.