sourcecode 5.3.1__tar.gz → 5.4.0__tar.gz

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

@@ -2,6 +2,104 @@
 
 ## [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.3.1
+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.1-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.1 — 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.1 → 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.1-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.1 — 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.

sourcecode-5.4.0/docs/CUSTOMER-VALIDATION.md

@@ -0,0 +1,202 @@
+# First Customer Validation (Increment #3.1)
+
+Prepares ASK Engine to be **shown to real users for the first time** — developers,
+architects, CTOs — and to run **validation interviews**. This is about the *communication*
+of the product, not the engine. Nothing here changes analysis behavior.
+
+Contents:
+1. First-two-minutes audit (what a new user actually understands)
+2. README-as-landing-page review + high-impact / low-cost copy proposals (ready to paste)
+3. End-to-end journey (README → install → first command → first value → Pro) with frictions
+4. The 5-minute demo → [`DEMO-5MIN.md`](DEMO-5MIN.md)
+5. User-interview question bank (validate, don't sell)
+
+The offer being validated: [`COMMERCIAL-OFFER.md`](COMMERCIAL-OFFER.md) ·
+[`MODERNIZATION.md`](MODERNIZATION.md) · [`PRODUCT_TIERS.md`](PRODUCT_TIERS.md).
+
+---
+
+## 1. First-two-minutes audit
+
+Assumes a developer who has never seen ASK Engine and reads only the current repository
+(README first). Observations only — objective, no fixes applied here.
+
+### What they understand in the first 30 seconds
+Reading the title + tagline + first paragraph (`README.md:1–20`):
+- It is a tool called **ASK Engine**; the CLI is `sourcecode`.
+- It gives **AI coding agents** persistent structural context and a fast repeated-analysis
+  cache; the headline benefit framed is **speed** (re-parse avoidance, ~17x on Keycloak).
+- It targets **large Java or TypeScript monoliths**.
+
+### What they understand in the first 2 minutes
+Scrolling to the cache table, token table, install, and Quickstart (`README.md:24–131`):
+- There is a **persistent content-hash cache** with measured speedups and bounded token output.
+- The CLI does much more than caching: `impact`, `migrate-check`, `spring-audit`,
+  `impact-chain`, `endpoints`, `validation`, `onboard`, `review-pr`, `fix-bug` all appear in
+  the Quickstart.
+- It runs **locally / offline** (stated later, `README.md:283`).
+
+### What they do NOT understand
+- **What the flagship is.** Modernization (`migrate-check`) is item #5 in the Quickstart —
+  no emphasis — yet it is the buy-trigger in the offer. The reader can't tell the headline
+  job from the long-tail command list.
+- **That Impact is the differentiator.** "What breaks if I change this?" — the moat vs
+  grep/LLMs — is one line among a dozen commands, not positioned as the reason to care.
+- **Who it's for.** The tagline says "Java **or TypeScript** monolith", but the product
+  monetizes **Java/Spring** and several capabilities are Java/Spring-only. A TypeScript dev
+  is invited in, then hits Java-only walls.
+- **Free vs Pro at a glance.** The split lives at `README.md:264` (Pricing) — below a very
+  long command reference. A buyer scanning "what do I get, why would I pay" must scroll past
+  everything first. (Prior audit gap **D3 / F3**.)
+- **Differentiation.** Nowhere near the top does the README say *why this beats grep, an
+  LLM, or SonarQube/OpenRewrite* — the three things a buyer will compare it to.
+
+### Doubts they still have before installing
+- **Does my code leave the machine?** (Answer — no egress, offline — is true and good, but
+  appears late; a security-conscious buyer wants it up top.)
+- **Do I need an account / license / key to try it?** (Answer — no, fully local, Pro
+  currently unlocked — not stated upfront.)
+- **Will it work on *my* repo?** Non-Spring Java? Non-Java? (Honest limitations exist but are
+  at the very bottom, `README.md:238–261`.)
+
+### What would stop them trying it
+- **No Java repo handy** — nothing to point it at. (Mitigation: the demo names two public
+  repos; the README's first value example should too.)
+- **No single "try it in 30 seconds" line at the very top** — the first runnable command is
+  after the install section.
+- Low friction otherwise: `pip install sourcecode` / `brew install`, then `ask .`.
+
+---
+
+## 2. README as a landing page
+
+Evaluated as the page that has to sell in one scroll.
+
+| Landing criterion | Current state | Verdict |
+|---|---|---|
+| Problem is clear in 1 screen | Problem stated is *agent re-parse latency* only | ⚠ narrow — the expensive-questions problem (impact / modernization) is missing up top |
+| Differentiation vs grep / LLM / static analysis | Not stated near the top | ✗ absent early |
+| Real examples | Strong — measured cache tables, real repos (Keycloak, Broadleaf) | ✓ |
+| Call to action | Install + Quickstart present | ✓ but value CTA ("check your upgrade readiness free") missing |
+| Time-to-first-value | `ask .` is fast; but first *impressive* command isn't foregrounded | ⚠ |
+| Free vs Pro visible without scrolling | No — at `:264` | ✗ (D3/F3) |
+
+### High-impact / low-cost proposals (copy ready to paste — NOT applied this increment)
+
+Each is pure copy near the top; no engine or gating change. Ordered by impact.
+
+**P-1 — Reframe the tagline + one-line problem (highest impact).** Replace the
+agent-only framing (`README.md:3`) with the expensive-questions framing that names the two
+buy-jobs, keeping the agent story as one of them:
+
+> **Deterministic answers to the expensive questions about a large Java codebase —
+> _what breaks if I change this_ and _are we ready to upgrade_ — with the source to prove
+> every answer.**
+> Built for enterprise Java/Spring monoliths. Runs locally, offline, no account. Also
+> serves fast, cached ground-truth to AI coding agents.
+
+**P-2 — Add a "What you get (Free vs Pro)" box right after the tagline** (fixes D3/F3).
+Four rows — Impact, System Map, Modernization, Agent context — each with the one-line job
+and "Free on normal repos · Pro at enterprise scale". Lifts the offer above the fold; links
+to `COMMERCIAL-OFFER.md`.
+
+**P-3 — Add a top "Try it in 30 seconds" block** naming a public repo so a reader with no
+Java repo handy can still see value:
+> ```bash
+> pip install sourcecode
+> git clone https://github.com/spring-projects/spring-petclinic && cd spring-petclinic
+> ask migrate-check .      # upgrade readiness, free, source-backed
+> ask impact OwnerController .   # what breaks if I change this?
+> ```
+
+**P-4 — One "vs grep / LLM / static analysis" line** near the top: *"grep finds text, an
+LLM guesses, ASK Engine proves — every finding carries the source line, and the blast-radius
+graph follows Spring DI that grep and LLMs miss."*
+
+**P-5 — Fix the audience contradiction:** the tagline should say **Java/Spring**; move the
+"other languages get repo-shape only" nuance into the capabilities section so a TypeScript
+reader isn't over-promised.
+
+These are proposals for the next copy pass. Applying them is a one-file, reversible edit.
+
+---
+
+## 3. End-to-end journey & frictions
+
+The path a first user walks, with the friction at each hop.
+
+| Hop | Reference | Friction |
+|---|---|---|
+| **README top** | `README.md:1–20` | Value prop = agent cache only; buy-jobs (impact, modernization) not foregrounded (**F1/F3/D3**). |
+| **Install** | `README.md:62–84` | Clean — `pip install sourcecode` / `brew`. `ask version` confirms. Low friction. |
+| **First command** | `README.md:88–131` | Quickstart is a 12-command wall; no "start here" ordering. A new user doesn't know which command to run first. |
+| **First useful result** | live | `ask .` / `--compact` returns in ~0.3s warm. Good. But the *impressive* first result (blast radius, readiness score) isn't the one signposted first. |
+| **Discover Free vs Pro** | `README.md:264` | Only reachable after the full command reference. Buyer scanning for "why pay" scrolls a long way (**D3**). |
+| **Pro invite / activation** | `license.py`, `PRODUCT_TIERS.md` | Pro currently unlocked for everyone (early-adoption banner honest). When gated, prompt now shows Get-a-license + activate (G1 resolved). No `SOURCECODE_PURCHASE_URL` set yet (points to docs). **F2** — no in-tool pointer to pricing from `--help`/welcome. |
+
+**Net:** install and time-to-first-result are strong; the weakness is entirely
+**positioning / ordering of the value story**, not the tool. All frictions are copy-level
+(F1/F2/F3/D3), already tracked in `RC1-CHECKLIST.md` §4 and `pro-experience-audit.md`.
+
+---
+
+## 4. The 5-minute demo
+
+See [`DEMO-5MIN.md`](DEMO-5MIN.md) — a reproducible script over two public repos
+(BroadleafCommerce, OpenMRS) showing only what impresses a buyer: precise blast radius,
+modernization readiness with real blockers, and the cache speed story. No internal
+architecture shown. All numbers in that script were captured from a real run on 2026-07-05.
+
+---
+
+## 5. User-interview question bank
+
+For validation interviews. **Goal: validate hypotheses, not sell.** Open questions, let the
+user talk, don't lead. Group by whichever hat the interviewee wears.
+
+### Warm-up (any interviewee)
+- Walk me through the last time you had to make a change in a large, unfamiliar codebase.
+  What did you do first?
+- When you join a new service/monolith, how long until you trust yourself to change it?
+
+### Core hypothesis probes (the four questions, asked without naming the product)
+- **What problem were you trying to solve?** — last time you needed to know the blast radius
+  of a change, or plan a framework upgrade. What triggered it?
+- **What did you expect to find / what did you reach for?** — grep, IDE call hierarchy, an
+  LLM, a static-analysis tool, asking a senior? What did that get you, and where did it fall
+  short?
+- **What result would surprise you?** — if a tool told you "changing this class touches 54
+  endpoints across 2 modules" in ten seconds, would you believe it? What would make you
+  trust it?
+- **What would you pay to avoid?** — describe a change or upgrade that went wrong (missed
+  caller, a `@Transactional` bypass, a botched Boot/Jakarta migration). What did it cost —
+  hours, an incident, a delayed release?
+
+### Modernization segment (platform / architecture lead)
+- How do you *currently* estimate a Boot 2→3 / Jakarta / JDK / Hibernate upgrade? How
+  confident is that estimate?
+- What blocks you from starting — unknown scope, unknown effort, fear of what breaks?
+- If you had a per-dimension readiness score with the source line behind every blocker,
+  what would you do with it? Who signs off on the budget?
+
+### Impact segment (developer / tech lead)
+- Before a risky change, how do you find everything it affects today? How often does
+  something get missed?
+- How much do you trust an LLM's answer to "what calls this?" on your monolith? Have you
+  been burned?
+- Spring DI: does your tooling follow interface→impl injection, or do you check by hand?
+
+### AI-agent segment (teams using Claude Code / Cursor / Copilot)
+- How do your agents get repo context today? How often do they hallucinate structure?
+- Would deterministic, cached, source-backed context change how you run agents in CI?
+
+### Pricing / packaging reactions (last, low-pressure)
+- €19/dev/mo, free below 500 Java files and unlimited on normal repos — does that framing
+  make sense? Where would you expect to hit the paywall?
+- Would you rather pay per developer, per repo, or per organization? Why?
+- What single capability, if it worked perfectly, would justify the subscription on its own?
+
+### Anti-goals (do not do in interviews)
+- Don't demo before asking what they do today — you'll bias the answers.
+- Don't defend the tool when they describe a gap — write the gap down.
+- Don't ask "would you buy this?" — ask what they've *already paid for or lost*.