sourcecode 5.8.32__tar.gz → 5.9.1__tar.gz

sourcecode-5.9.1/.github/workflows/windows-battery.yml

@@ -0,0 +1,46 @@
+name: Windows battery
+
+# AUD-601-X01 / S-10. Windows remains a release-evidence battery, but a full
+# 20+ minute suite on every worktree commit exhausted the Actions allowance
+# without providing a usable signal. Run it deliberately before a release or
+# while investigating a Windows-specific regression.
+
+on:
+  workflow_dispatch:
+
+concurrency:
+  group: windows-battery-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  battery:
+    runs-on: windows-latest
+    timeout-minutes: 35
+    env:
+      # CLI payloads and diagnostics are UTF-8 contracts. Without this Windows
+      # decodes child-process output with the active code page, turning a valid
+      # JSON answer containing source text into an empty/failed test response.
+      PYTHONUTF8: "1"
+      PYTHONIOENCODING: "utf-8"
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install pytest pytest-xdist
+
+      - name: Suite
+        run: pytest
+        # `runner.*` is valid at step scope. Both stores stay outside the
+        # checkout so their files never become untracked input to an analysis.
+        env:
+          SOURCECODE_CACHE_DIR: ${{ runner.temp }}/ask-cache
+          SOURCECODE_CONTEXT_CACHE_DIR: ${{ runner.temp }}/ask-context-cache

{sourcecode-5.8.32 → sourcecode-5.9.1}/CHANGELOG.md

@@ -1,5 +1,93 @@
 # Changelog
 
+## [5.9.1] — 2026-08-26
+
+*Audit correction and stress-validation patch release. The `AUD-608` fixes
+from the `5.9.0` audit are shipped and documented; command contracts now
+disclose their limits and failure boundaries.*
+
+**Fixed**
+
+- `cve` publishes that its dependency inventory comes from static manifests and
+  supported lockfiles, without implying Maven or Gradle graph resolution.
+- `pr-risk --since` reports unreadable base refs as structured execution errors
+  instead of misleading `non_coverage`.
+- `posture --diff --limit` bounds `permit_all` and effective-access evidence
+  maps while preserving unrelated `evidence` payloads.
+- Seven new command helps state their command-level analysis and memory budget
+  applicability.
+
+**Documentation and validation**
+
+- README, roadmaps and defect ledger identify `5.9.1` as the current release;
+  the `5.9.0` audit remains historical evidence.
+- Focused regression batteries pass for all four corrections. A representative
+  stress smoke test passed on seven repositories under
+  `Documents/workspace/testing` with isolated caches and clean stderr.
+
+## [5.9.0] — 2026-08-26
+
+*The `AUD-607` external round, closed: three defects fixed and the whole feature
+intake built, one commit per row. Seven new commands (`cve`, `intent`,
+`remediate`, `pr-risk`, `drift`, `watch`, `self-audit`) and two extended ones
+(`baseline --kind findings`, `export --c4 --render`) make this the largest
+addition to the command surface since 5.0, so the minor version moves.*
+
+**Fixed**
+
+- `chunk-file` emitted chunk content that did not match its own declared
+  `start_line`/`end_line`: the boundary path serialised the untruncated buffer
+  while declaring a truncated end line, so a chunk ran past its own range and
+  those lines repeated at the head of the next one. A second, separate defect
+  made the annotation buffer's clearing guard unreachable, so a field's
+  `@Autowired` was carried onto the following method while the field's own
+  declaration dropped out of that chunk. The reported "deliberate overlap" is
+  refuted; the declared range is now exact and asserted against file content.
+- `explain` answered *"No stereotype detected"* under **Purpose** while listing
+  that same class's routes under **REST Endpoints**. Fixed by reading the
+  endpoint evidence the answer already computed — not by adding JAX-RS to a
+  Spring annotation list, which is the branching this project does not do.
+- `--files -` claimed *"stdin is a terminal"* for a Git Bash/MSYS redirect it
+  cannot verify. The message now names the outcome and states both routes into
+  it (the C3-106 rule, already applied to `_confirm`).
+
+**Added**
+
+- `ask cve --feed <osv>` — dependency advisories gated on whether a route can
+  **reach** the vulnerable package. Takes no network at analysis time; an
+  unreadable feed is a refusal, never a clean scan; nothing answers *"not
+  reachable"*, and an unresolvable Maven version is `unknown`, never
+  `not_affected`. Schema `cve-reachability-v1`, published as a document.
+- `ask intent "<question>"` — a plain-language question resolved to one of
+  `retrieve`'s typed queries. A scored lexical match against a declared
+  vocabulary: no model, no generation. Ambiguous or unanchored questions are
+  refused with the closest intents named.
+- `ask remediate` — finding → recipe → apply in a dedicated worktree →
+  `verify-edit`. Dry by default; an apply that could not be verified reports
+  `unverified`, never `applied`. Schema `remediation-plan-v1`.
+- `ask pr-risk` — one verdict for one diff, distinct from `pack gate`'s verdict
+  about the repository. `UNKNOWN` outranks `PASS` and fails every gate. Schema
+  `pr-risk-v1`.
+- `ask drift` — what changed in the effective access, across time or across two
+  profile sets, with one arithmetic for both axes. Schema `access-drift-v1`.
+- `ask watch` — one answer per save against a warm index; `--once` is the
+  pre-commit shape. Schema `watch-event-v1`.
+- `ask self-audit` — whether the **installed** build's registries agree with each
+  other, and an explicit statement of what it cannot check. Schema
+  `self-audit-v1`.
+- `ask baseline capture|diff|trend --kind findings` — the defect population as a
+  persisted series, so "how long has this been open?" has an answer. Schema
+  `findings-baseline-v1`.
+- `ask export --c4 --render mermaid|svg` — draws the C4 model instead of only
+  emitting it, with the node cap written on the canvas.
+
+**Note.** Building the features surfaced three defects no audit round had
+reported: the C4 renderer's first version drew report metadata (`summary`,
+`coverage_note`) as system architecture; the watch loop stat-ed
+repository-relative paths against the process CWD and so reported "nothing
+changed" on every tick; and `self-audit` found its own schema identifier
+unregistered on its first run. Each is now held by an assertion.
+
 ## [5.8.32] — 2026-08-26
 
 *MCP and documentation alignment release. MCP assessment packs now support

{sourcecode-5.8.32 → sourcecode-5.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.8.32
+Version: 5.9.1
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 Project-URL: Homepage, https://github.com/HarounDominique/sourcecode
 Project-URL: Repository, https://github.com/HarounDominique/sourcecode
@@ -59,7 +59,7 @@ Description-Content-Type: text/markdown
 > question. All analysis is local and deterministic; see [Privacy](#configuration--privacy)
 > before inspecting a repository whose telemetry policy you need to control.
 
-![Version](https://img.shields.io/badge/version-5.8.32-blue)
+![Version](https://img.shields.io/badge/version-5.9.1-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 Copyright (c) 2026 Dominique Haroun. All rights reserved. ASK Engine 5.7.0 and
@@ -188,13 +188,13 @@ set `ASK_MAX_RSS_MB=<megabytes>`; if the process exceeds it, ASK refuses the
 answer with `MEMORY_TOO_LARGE`, including the observed peak and limit. Leave it
 unset, or set it to `0`, to disable the ceiling explicitly.
 
-**Current performance status.** Release 5.8.32 retains the shared Canonical IR
+**Current performance status.** Release 5.9.1 retains the shared Canonical IR
 path used by `validation` and now passes that same CIR into labelled `data-exposure`
 runs; the no-label path remains parse-free. These are implementation properties,
 not duration promises. A controlled external warm-path audit has opened performance
 and bounded-output regressions for this release; use `ask cache model <repo>` and
 `--progress stderr` for supervised runs, and consult the
-[latest external audit intake](docs/AUDIT-2026-08-26-EXTERNAL-5.8.31.md) before
+[latest external audit intake](docs/AUDIT-2026-08-26-EXTERNAL-5.9.0.md) before
 treating a historical timing or bounded flag as a current guarantee.
 
 **What a warm actually covers.** `ask cache warm` rebuilds the declared root views and their
@@ -222,7 +222,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.8.32 — and, on a build that has aged,
+ask version                    # ask 5.9.1 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -332,6 +332,41 @@ ask verify /path/to/repo --capture-baseline   # accept today's debt, once
 ask verify /path/to/repo                      # then: only new violations block
 ```
 
+**And the loop that closes.** Finding, question and change each had a command; what they
+did not have was a way through. These are the joins, and each refuses rather than guess:
+
+```bash
+# Which advisories a route can actually REACH — not which are on the classpath.
+# Reads a LOCAL feed; no network is taken, so a CI gate can never pass because a
+# fetch timed out. Nothing answers "not reachable": absence of a resolved edge is
+# not absence of use, and the payload says so.
+ask cve /path/to/repo --feed ./osv-maven.json --reachable-only
+
+# Ask in your own words. It SELECTS one of retrieve's 29 typed queries and prints
+# it (--run executes it); it never invents an answer, and a question that fits two
+# intents too closely is refused with both named.
+ask intent "what breaks if I change OrderService?"
+
+# Finding → recipe → apply in a dedicated worktree → verify. Dry by default. Most
+# findings are not mechanical, and the plan says which and why.
+ask remediate /path/to/repo
+
+# One verdict for THIS diff, not for the repository. A changed file that maps to no
+# class caps the verdict at UNKNOWN — a partial blast radius is not a small one —
+# and UNKNOWN fails every gate.
+git diff --name-only main | ask pr-risk /path/to/repo --files - --fail-on block
+
+# What opened up since the last capture, on the axis posture --diff does not have.
+ask drift /path/to/repo --profile prod --capture   # record today
+ask drift /path/to/repo --profile prod             # then: what moved
+
+# While you edit: one answer per save, against the warm index.
+ask watch /path/to/repo --once
+
+# Show me the architecture, don't hand me JSON to render.
+ask export /path/to/repo --c4 --render mermaid
+```
+
 > **Adopting a gate on a real codebase.** Nobody hand-writes contracts for a 3 000-file
 > monolith, so `ask verify --init` derives the ones the repository satisfies **today** and
 > executes each before writing it — init followed by verify passes by construction.
@@ -360,27 +395,27 @@ Bounded, noise-free repo context designed to drop straight into an agent's conte
 
 ### 2 · Impact Analysis
 Blast radius from a class or interface — reverse dependencies, through Spring DI, to the HTTP endpoints a change reaches.
-`ask impact` · `ask impact-chain` (blast radius; `--with-findings` for TX/SEC audit findings) · `ask pr-impact`
+`ask impact` · `ask impact-chain` (blast radius; `--with-findings` for TX/SEC audit findings) · `ask pr-impact` · `ask pr-risk` (one verdict for the diff — `UNKNOWN` when the blast radius has a hole, and `UNKNOWN` fails the gate)
 → [reference](docs/USER_GUIDE.md#core-commands)
 
 ### 3 · Architecture Intelligence
 The system map: module graph, dependency views, REST surface, per-class summaries, and a symbol-level IR for downstream tooling.
-`ask export` · `ask repo-ir` · `ask endpoints` · `ask explain` · `ask timeline` (*experimental* — the same views over the commit series: when a number moved, and in which window)
+`ask export` (`--c4 --render mermaid|svg` draws it) · `ask repo-ir` · `ask endpoints` · `ask explain` · `ask timeline` (*experimental* — the same views over the commit series: when a number moved, and in which window)
 → [reference](docs/USER_GUIDE.md#core-commands)
 
 ### 4 · Migration & Modernization
 Is this codebase ready to upgrade? Per-dimension readiness (Jakarta / Spring Boot / JDK / Hibernate), located blockers, an effort estimate, and — with `--blast-radius` — the endpoints whose call path runs through each blocker, so the re-test plan is ordered by regression scope.
-`ask migrate-check` · `ask modernize`
+`ask migrate-check` · `ask modernize` · `ask remediate` (finding → recipe → apply → **verify**; dry by default, and an apply it could not verify is never reported as applied)
 → [migrate-check reference](docs/migrate-check.md) · [MODERNIZATION.md](docs/MODERNIZATION.md)
 
 ### 5 · Spring Analysis
 Deterministic Spring semantics: transactional anomalies (e.g. `@Transactional` on a private method = silent CGLIB no-op), security surface, request-body validation.
-`ask spring-audit` · `ask validation`
+`ask spring-audit` · `ask validation` · `ask cve` (dependency advisories gated on whether a route can **reach** the vulnerable package — from a local feed, with no network taken)
 → [reference](docs/USER_GUIDE.md#core-commands)
 
 ### 5b · Runtime Posture *(experimental — and the most differentiated thing here)*
 What a profile set **actually wires**: which conditional beans register, which do not, and which conditions could not be decided at all — then the effective endpoint access that follows from the filter chain. `--diff` answers the question nobody else answers in one command: *what changes between `dev` and `prod`, across every endpoint at once.*
-`ask posture` · `ask posture --diff dev:prod` · `ask posture --property k=v`
+`ask posture` · `ask posture --diff dev:prod` · `ask posture --property k=v` · `ask drift` (the same comparison across **time** — what opened up since the last capture)
 → [posture.md](docs/posture.md)
 
 **`--diff-ref` makes it a gate instead of a report.** `--diff` moves the profile set; `--diff-ref origin/main:HEAD` (or `--since origin/main`, which compares a ref with the working tree) moves the *tree* under one profile set and answers *did this branch open an endpoint*. `--fail-on opened` exits 1 when it did. Both refs are read with `git archive` — nothing is written to the repository. The comparison is keyed on the request (`METHOD path`), counts requests only one side serves, and never reports a rule that disappeared as protection gained.
@@ -432,11 +467,11 @@ remains `NC-001` and is published in the payload's own `non_coverage` block.
 
 ### 6 · Developer Workflows
 The everyday loop: diff-based PR review, symptom-driven bug triage, and delta context for continuous agent runs.
-`ask review-pr` · `ask fix-bug` · `ask prepare-context`
+`ask review-pr` · `ask fix-bug` · `ask prepare-context` · `ask watch` (one answer per save, against a warm index) · `ask intent "<question>"` (a plain-language question resolved to a typed query — it selects one, it never invents an answer)
 → [reference](docs/USER_GUIDE.md#typical-workflows)
 
 ### 7 · Utilities
-`ask rename-class` (word-boundary Java rename) · `ask chunk-file` (split large files for agents) · `ask cache` (status / warm / model / clear / freshness)
+`ask rename-class` (word-boundary Java rename) · `ask chunk-file` (split large files for agents) · `ask cache` (status / warm / model / clear / freshness) · `ask self-audit` (does the installed build's own registry agree with itself?)
 → [reference](docs/USER_GUIDE.md)
 
 ---
@@ -485,12 +520,19 @@ from it.
 | `verify-edit` | supported | did the working-tree edits change runtime behaviour | semantic diff gate for the edit loop |
 | `--compact` / `--agent` | — | bounded structural context for an agent | flags of the root command, not commands: not tiered |
 | `onboard` / `explain` / `cold-start` | supported | orientation in an unfamiliar repo; per-class summary; bootstrap snapshot | `onboard` publishes `population`, `population_unit` and `population_total` for its source-file universe |
-| `export` / `repo-ir` / `schema` | supported | tool-agnostic views (C4, module graph, integrations); symbol-level IR; published JSON Schemas | |
+| `export` / `repo-ir` / `schema` | supported | tool-agnostic views (C4, module graph, integrations); symbol-level IR; published JSON Schemas | `export --c4 --render mermaid\|svg` **draws** the model instead of only emitting it — presentation over the same payload, with the node cap written on the canvas |
 | `modernize` | supported | coupling hubs, cycles, dead zones, refactor candidates | |
 | `review-pr` / `fix-bug` / `prepare-context` | supported | diff review, symptom triage, task-shaped context | |
 | `plan` / `compare` / `delta` / `contract-diff` | supported | what to review for a change; candidates by measured cost; outcome of a change; public-contract break | no verdicts, measured cost only |
 | `validation` | supported | request-body validation coverage and gaps | |
-| `baseline capture\|diff` · `trend` | supported | versioned architectural metrics over time; `ask trend .` reads the series (a repository path or a baselines directory), `ask baseline diff .` compares the tree against its newest point | trend reporting, not gating. Baselines land in `.ask/baselines` **inside the repository** — the history travels with the code, not with a vendor; an audit that must not write passes `--dir`. `capture --auto` is the unattended form (one baseline per commit, never rewrites one, never fails the build) — automate it: [baseline-ci.yml](docs/baseline-ci.yml) |
+| `baseline capture\|diff` · `trend` | supported | versioned architectural metrics over time — and, with `--kind findings`, the **defect population** as a series, so "open since 5.8.28" is answerable without anybody keeping the tally (`first_seen` is the earliest STORED capture, and the payload says so); `ask trend .` reads the series (a repository path or a baselines directory), `ask baseline diff .` compares the tree against its newest point | trend reporting, not gating. Baselines land in `.ask/baselines` **inside the repository** — the history travels with the code, not with a vendor; an audit that must not write passes `--dir`. `capture --auto` is the unattended form (one baseline per commit, never rewrites one, never fails the build) — automate it: [baseline-ci.yml](docs/baseline-ci.yml) |
+| `cve` | supported | which dependency advisories a route can actually **reach** — not which are on the classpath | reads a **local** OSV feed (`--feed`); takes no network at analysis time, so a CI gate can never pass because a fetch timed out. Four verdicts: `reachable` (with the routes), `imported_not_exposed`, `not_observed` and `unknown`. Nothing answers *"not reachable"* — reflection, SPI loading and container wiring reach code no source edge names — and an unresolved Maven version is `unknown`, never `not_affected`. Feed staleness is read off the feed's own dates |
+| `intent` | supported | a plain-language question, resolved to the typed `retrieve` query that answers it | `ask intent "what breaks if I change OrderService?"`. A scored lexical match against a declared vocabulary — **no model, no generation** — so it resolves identically on every machine. It selects a query and prints it; `--run` executes it. A question fitting two intents too closely is refused with both named, because a well-formed answer to a question you did not ask is invisible once printed |
+| `remediate` | supported | the loop from a finding to a **verified** change | audit → recipe → apply in a dedicated worktree → `verify-edit`. Dry by default. Most findings are not mechanical and the plan says which and why; an apply that could not be verified reports `unverified`, never `applied` |
+| `pr-risk` | supported | one verdict for **this diff** — does the change make things worse? | `pack gate` answers about the repository; this answers about the change. Joins `pr-impact` reach, endpoint access, the shared risk model and CODEOWNERS. `--since` differences route inventories so `new_endpoints` is a fact rather than a guess. A changed file that maps to no class caps the verdict at `UNKNOWN`, which fails every gate — a partial blast radius is not a small one |
+| `drift` | supported | what changed in the **effective access**, and when | `--capture` records; the default compares against the last record; `--against` compares two profile sets. One arithmetic for both axes, so the time answer and the environment answer cannot disagree. `newly_unmatched` and `newly_matched` are separate buckets, and a `removed` route is never reported as having become safe |
+| `watch` | supported | what each save affected, against a warm index | one JSON line per tick. `--once` is the pre-commit shape; `--ticks`/`--for` bound the loop. A failed analysis is an `error` tick, never an empty change list; a file added since the warm is `unresolved`, not `unreachable` |
+| `self-audit` | supported | whether the **installed build's** own registries agree with each other | a battery proves the source tree consistent while a user runs a wheel. Checks the cache model, format contract, schema registry and output affordances. Says plainly what it cannot check: the semantic engine analyses Java and this build is Python, so those figures are declared absent rather than reported as zeros |
 | `retrieve` | parked | typed knowledge queries over the model | symbol-oriented queries accept `--target/-t`; domain aliases such as `--module/-m`, `--subsystem/-s` and `--endpoint/-e` remain supported |
 | `timeline` | experimental | since when a number moved, and in which commit window | walks the commit series and re-runs the shipped analyses (`posture`, `data-exposure`, `endpoints`, `spring-audit`) on a read-only materialisation of each sampled tree; publishes transitions, not a per-commit dump. A sample that could not be analysed is `null` with a reason, never 0, and a transition under sampling carries the window it could have happened in |
 | `regress` | supported | what moved between two payloads of the same command, and which declaration accounts for it | attributes each delta to a declaration the answers carry (`test_source_excluded`, `symbols_excluded`, `coverage.gaps`, `*_cap`, `waivers`); a delta nothing explains is `unattributed`. Refuses the comparison when `cache_layers`, `base_env` or the analyzer fingerprint differ |
@@ -543,7 +585,7 @@ reading JSON sees the same boundary a buyer reads here.
 | **General request-input-to-sink taint analysis.** | `ask risk` includes two bounded slices for annotated HTTP parameters and positional calls in repository Java sources: known query sinks, and MyBatis statements that splice a value into their SQL. “Known” is a published list — `risk` prints it as `query_sink_vocabulary`, with the calls it deliberately leaves out and why — so a concatenation into a call outside that list is not a miss to be discovered, it is a stated boundary. Anything broader needs value flow through a program, which is a different analysis with a different failure mode: an unsound one produces confident findings that are wrong, and every claim here is meant to be checkable against the line that produced it. | A dataflow scanner (Semgrep, CodeQL) for complete taint. What this product adds on top is reachability and, for the two bounded slices, whether an annotated HTTP input reaches a known concatenated query sink or a spliced SQL statement — the latter with a three-state verdict that says `undecidable` rather than clearing a route it could not follow. |
 | **Secrets outside Java, Spring configuration and the deployment descriptors — a Helm value, a CI variable file, a shell script.** | The file population this analyzer reads is the Java source, the Spring configuration convention and the descriptors it already parses to resolve an environment. A secret elsewhere is not missed by a weak rule; it is outside the set of files anything here opens. Narrowed by CL-10: a credential stored in `web.xml` or a Spring XML context IS reported (SEC-007), because those files were already being read. | A dedicated secret scanner over the whole tree (gitleaks, trufflehog). |
 | **Filter-chain order and per-filter URL patterns — the presence of a custom filter is structural only.** | Which filter runs first is decided by bean ordering this analyzer does not resolve. Where two active configurations both match a request, the answer published is `undecided` rather than a guess. | `ask posture --profile <set>` states per endpoint what the readable rules decide and what they leave undecided. |
-| **Known vulnerabilities in dependencies — no CVE database, no version advisory matching.** | Enriching a vulnerability feed is a different product with a different update cadence; a stale embedded database is worse than no database, because it reads as a clean bill of health. | A dependency scanner (Trivy, OWASP Dependency-Check). `impact-chain` then answers which of its findings anything actually reaches. |
+| **Discovering vulnerabilities, and shipping the database that lists them — no embedded CVE feed, no network lookup at analysis time.** | Maintaining a vulnerability feed is a different product with a different update cadence, and a stale embedded database is worse than no database because it reads as a clean bill of health. That boundary is unchanged. What IS built is the half this project can be responsible for: `ask cve --feed <osv.json>` takes a feed you supply and pin, and answers whether a route can actually REACH the vulnerable package, using the same blast radius as `impact-chain`. The feed's own staleness travels with the answer, an unreadable feed is a refusal rather than a clean scan, and nothing there answers "not reachable". | A dependency scanner (Trivy, OWASP Dependency-Check, an OSV export) supplies the advisories; `ask cve` says which of them anything actually reaches. |
 
 Two more boundaries worth stating in the same voice:
 
@@ -643,6 +685,10 @@ power on Free for small and mid-size repos; you upgrade when the work gets bigge
 ASK Engine monetises enterprise Java monoliths. Activate with `ask activate <key>`.
 Full breakdown: [docs/PRODUCT_TIERS.md](docs/PRODUCT_TIERS.md).
 
+The future commercial direction is staged rather than an immediate product
+restriction: free adoption, self-serve scale, B2B infrastructure licensing and
+a generated public trust projection. See the [monetization review](docs/AUDIT-2026-08-26-MONETIZATION.md).
+
 ---
 
 ## Configuration & privacy
@@ -717,4 +763,5 @@ Matching endpoints report `policy: "custom"` and drop out of the `no_security_si
 | [PRODUCT_IDENTITY.md](docs/PRODUCT_IDENTITY.md) | `ask` (command) vs `sourcecode` (package/alias) |
 | [privacy.md](docs/privacy.md) | Telemetry and data-handling policy |
 | [DEFECT-LEDGER.md](docs/DEFECT-LEDGER.md) | Every defect found in the field, its class, and which release closed it — published on purpose |
+| [AUDIT-2026-08-26-EXTERNAL-5.8.32.md](docs/AUDIT-2026-08-26-EXTERNAL-5.8.32.md) | The most recent external review, its reproduced and **unreproduced** findings, and the feature intake it opened |
 | [spec/envelope-v1.md](docs/spec/envelope-v1.md) | The output format as an **open specification** — provenance, a named unit, a stated basis, declared non-coverage. Implementable by tools that are not this one; the field table is generated from the schema `ask schema envelope-v1` prints |

{sourcecode-5.8.32 → sourcecode-5.9.1}/README.md

@@ -10,7 +10,7 @@
 > question. All analysis is local and deterministic; see [Privacy](#configuration--privacy)
 > before inspecting a repository whose telemetry policy you need to control.
 
-![Version](https://img.shields.io/badge/version-5.8.32-blue)
+![Version](https://img.shields.io/badge/version-5.9.1-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 Copyright (c) 2026 Dominique Haroun. All rights reserved. ASK Engine 5.7.0 and
@@ -139,13 +139,13 @@ set `ASK_MAX_RSS_MB=<megabytes>`; if the process exceeds it, ASK refuses the
 answer with `MEMORY_TOO_LARGE`, including the observed peak and limit. Leave it
 unset, or set it to `0`, to disable the ceiling explicitly.
 
-**Current performance status.** Release 5.8.32 retains the shared Canonical IR
+**Current performance status.** Release 5.9.1 retains the shared Canonical IR
 path used by `validation` and now passes that same CIR into labelled `data-exposure`
 runs; the no-label path remains parse-free. These are implementation properties,
 not duration promises. A controlled external warm-path audit has opened performance
 and bounded-output regressions for this release; use `ask cache model <repo>` and
 `--progress stderr` for supervised runs, and consult the
-[latest external audit intake](docs/AUDIT-2026-08-26-EXTERNAL-5.8.31.md) before
+[latest external audit intake](docs/AUDIT-2026-08-26-EXTERNAL-5.9.0.md) before
 treating a historical timing or bounded flag as a current guarantee.
 
 **What a warm actually covers.** `ask cache warm` rebuilds the declared root views and their
@@ -173,7 +173,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.8.32 — and, on a build that has aged,
+ask version                    # ask 5.9.1 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -283,6 +283,41 @@ ask verify /path/to/repo --capture-baseline   # accept today's debt, once
 ask verify /path/to/repo                      # then: only new violations block
 ```
 
+**And the loop that closes.** Finding, question and change each had a command; what they
+did not have was a way through. These are the joins, and each refuses rather than guess:
+
+```bash
+# Which advisories a route can actually REACH — not which are on the classpath.
+# Reads a LOCAL feed; no network is taken, so a CI gate can never pass because a
+# fetch timed out. Nothing answers "not reachable": absence of a resolved edge is
+# not absence of use, and the payload says so.
+ask cve /path/to/repo --feed ./osv-maven.json --reachable-only
+
+# Ask in your own words. It SELECTS one of retrieve's 29 typed queries and prints
+# it (--run executes it); it never invents an answer, and a question that fits two
+# intents too closely is refused with both named.
+ask intent "what breaks if I change OrderService?"
+
+# Finding → recipe → apply in a dedicated worktree → verify. Dry by default. Most
+# findings are not mechanical, and the plan says which and why.
+ask remediate /path/to/repo
+
+# One verdict for THIS diff, not for the repository. A changed file that maps to no
+# class caps the verdict at UNKNOWN — a partial blast radius is not a small one —
+# and UNKNOWN fails every gate.
+git diff --name-only main | ask pr-risk /path/to/repo --files - --fail-on block
+
+# What opened up since the last capture, on the axis posture --diff does not have.
+ask drift /path/to/repo --profile prod --capture   # record today
+ask drift /path/to/repo --profile prod             # then: what moved
+
+# While you edit: one answer per save, against the warm index.
+ask watch /path/to/repo --once
+
+# Show me the architecture, don't hand me JSON to render.
+ask export /path/to/repo --c4 --render mermaid
+```
+
 > **Adopting a gate on a real codebase.** Nobody hand-writes contracts for a 3 000-file
 > monolith, so `ask verify --init` derives the ones the repository satisfies **today** and
 > executes each before writing it — init followed by verify passes by construction.
@@ -311,27 +346,27 @@ Bounded, noise-free repo context designed to drop straight into an agent's conte
 
 ### 2 · Impact Analysis
 Blast radius from a class or interface — reverse dependencies, through Spring DI, to the HTTP endpoints a change reaches.
-`ask impact` · `ask impact-chain` (blast radius; `--with-findings` for TX/SEC audit findings) · `ask pr-impact`
+`ask impact` · `ask impact-chain` (blast radius; `--with-findings` for TX/SEC audit findings) · `ask pr-impact` · `ask pr-risk` (one verdict for the diff — `UNKNOWN` when the blast radius has a hole, and `UNKNOWN` fails the gate)
 → [reference](docs/USER_GUIDE.md#core-commands)
 
 ### 3 · Architecture Intelligence
 The system map: module graph, dependency views, REST surface, per-class summaries, and a symbol-level IR for downstream tooling.
-`ask export` · `ask repo-ir` · `ask endpoints` · `ask explain` · `ask timeline` (*experimental* — the same views over the commit series: when a number moved, and in which window)
+`ask export` (`--c4 --render mermaid|svg` draws it) · `ask repo-ir` · `ask endpoints` · `ask explain` · `ask timeline` (*experimental* — the same views over the commit series: when a number moved, and in which window)
 → [reference](docs/USER_GUIDE.md#core-commands)
 
 ### 4 · Migration & Modernization
 Is this codebase ready to upgrade? Per-dimension readiness (Jakarta / Spring Boot / JDK / Hibernate), located blockers, an effort estimate, and — with `--blast-radius` — the endpoints whose call path runs through each blocker, so the re-test plan is ordered by regression scope.
-`ask migrate-check` · `ask modernize`
+`ask migrate-check` · `ask modernize` · `ask remediate` (finding → recipe → apply → **verify**; dry by default, and an apply it could not verify is never reported as applied)
 → [migrate-check reference](docs/migrate-check.md) · [MODERNIZATION.md](docs/MODERNIZATION.md)
 
 ### 5 · Spring Analysis
 Deterministic Spring semantics: transactional anomalies (e.g. `@Transactional` on a private method = silent CGLIB no-op), security surface, request-body validation.
-`ask spring-audit` · `ask validation`
+`ask spring-audit` · `ask validation` · `ask cve` (dependency advisories gated on whether a route can **reach** the vulnerable package — from a local feed, with no network taken)
 → [reference](docs/USER_GUIDE.md#core-commands)
 
 ### 5b · Runtime Posture *(experimental — and the most differentiated thing here)*
 What a profile set **actually wires**: which conditional beans register, which do not, and which conditions could not be decided at all — then the effective endpoint access that follows from the filter chain. `--diff` answers the question nobody else answers in one command: *what changes between `dev` and `prod`, across every endpoint at once.*
-`ask posture` · `ask posture --diff dev:prod` · `ask posture --property k=v`
+`ask posture` · `ask posture --diff dev:prod` · `ask posture --property k=v` · `ask drift` (the same comparison across **time** — what opened up since the last capture)
 → [posture.md](docs/posture.md)
 
 **`--diff-ref` makes it a gate instead of a report.** `--diff` moves the profile set; `--diff-ref origin/main:HEAD` (or `--since origin/main`, which compares a ref with the working tree) moves the *tree* under one profile set and answers *did this branch open an endpoint*. `--fail-on opened` exits 1 when it did. Both refs are read with `git archive` — nothing is written to the repository. The comparison is keyed on the request (`METHOD path`), counts requests only one side serves, and never reports a rule that disappeared as protection gained.
@@ -383,11 +418,11 @@ remains `NC-001` and is published in the payload's own `non_coverage` block.
 
 ### 6 · Developer Workflows
 The everyday loop: diff-based PR review, symptom-driven bug triage, and delta context for continuous agent runs.
-`ask review-pr` · `ask fix-bug` · `ask prepare-context`
+`ask review-pr` · `ask fix-bug` · `ask prepare-context` · `ask watch` (one answer per save, against a warm index) · `ask intent "<question>"` (a plain-language question resolved to a typed query — it selects one, it never invents an answer)
 → [reference](docs/USER_GUIDE.md#typical-workflows)
 
 ### 7 · Utilities
-`ask rename-class` (word-boundary Java rename) · `ask chunk-file` (split large files for agents) · `ask cache` (status / warm / model / clear / freshness)
+`ask rename-class` (word-boundary Java rename) · `ask chunk-file` (split large files for agents) · `ask cache` (status / warm / model / clear / freshness) · `ask self-audit` (does the installed build's own registry agree with itself?)
 → [reference](docs/USER_GUIDE.md)
 
 ---
@@ -436,12 +471,19 @@ from it.
 | `verify-edit` | supported | did the working-tree edits change runtime behaviour | semantic diff gate for the edit loop |
 | `--compact` / `--agent` | — | bounded structural context for an agent | flags of the root command, not commands: not tiered |
 | `onboard` / `explain` / `cold-start` | supported | orientation in an unfamiliar repo; per-class summary; bootstrap snapshot | `onboard` publishes `population`, `population_unit` and `population_total` for its source-file universe |
-| `export` / `repo-ir` / `schema` | supported | tool-agnostic views (C4, module graph, integrations); symbol-level IR; published JSON Schemas | |
+| `export` / `repo-ir` / `schema` | supported | tool-agnostic views (C4, module graph, integrations); symbol-level IR; published JSON Schemas | `export --c4 --render mermaid\|svg` **draws** the model instead of only emitting it — presentation over the same payload, with the node cap written on the canvas |
 | `modernize` | supported | coupling hubs, cycles, dead zones, refactor candidates | |
 | `review-pr` / `fix-bug` / `prepare-context` | supported | diff review, symptom triage, task-shaped context | |
 | `plan` / `compare` / `delta` / `contract-diff` | supported | what to review for a change; candidates by measured cost; outcome of a change; public-contract break | no verdicts, measured cost only |
 | `validation` | supported | request-body validation coverage and gaps | |
-| `baseline capture\|diff` · `trend` | supported | versioned architectural metrics over time; `ask trend .` reads the series (a repository path or a baselines directory), `ask baseline diff .` compares the tree against its newest point | trend reporting, not gating. Baselines land in `.ask/baselines` **inside the repository** — the history travels with the code, not with a vendor; an audit that must not write passes `--dir`. `capture --auto` is the unattended form (one baseline per commit, never rewrites one, never fails the build) — automate it: [baseline-ci.yml](docs/baseline-ci.yml) |
+| `baseline capture\|diff` · `trend` | supported | versioned architectural metrics over time — and, with `--kind findings`, the **defect population** as a series, so "open since 5.8.28" is answerable without anybody keeping the tally (`first_seen` is the earliest STORED capture, and the payload says so); `ask trend .` reads the series (a repository path or a baselines directory), `ask baseline diff .` compares the tree against its newest point | trend reporting, not gating. Baselines land in `.ask/baselines` **inside the repository** — the history travels with the code, not with a vendor; an audit that must not write passes `--dir`. `capture --auto` is the unattended form (one baseline per commit, never rewrites one, never fails the build) — automate it: [baseline-ci.yml](docs/baseline-ci.yml) |
+| `cve` | supported | which dependency advisories a route can actually **reach** — not which are on the classpath | reads a **local** OSV feed (`--feed`); takes no network at analysis time, so a CI gate can never pass because a fetch timed out. Four verdicts: `reachable` (with the routes), `imported_not_exposed`, `not_observed` and `unknown`. Nothing answers *"not reachable"* — reflection, SPI loading and container wiring reach code no source edge names — and an unresolved Maven version is `unknown`, never `not_affected`. Feed staleness is read off the feed's own dates |
+| `intent` | supported | a plain-language question, resolved to the typed `retrieve` query that answers it | `ask intent "what breaks if I change OrderService?"`. A scored lexical match against a declared vocabulary — **no model, no generation** — so it resolves identically on every machine. It selects a query and prints it; `--run` executes it. A question fitting two intents too closely is refused with both named, because a well-formed answer to a question you did not ask is invisible once printed |
+| `remediate` | supported | the loop from a finding to a **verified** change | audit → recipe → apply in a dedicated worktree → `verify-edit`. Dry by default. Most findings are not mechanical and the plan says which and why; an apply that could not be verified reports `unverified`, never `applied` |
+| `pr-risk` | supported | one verdict for **this diff** — does the change make things worse? | `pack gate` answers about the repository; this answers about the change. Joins `pr-impact` reach, endpoint access, the shared risk model and CODEOWNERS. `--since` differences route inventories so `new_endpoints` is a fact rather than a guess. A changed file that maps to no class caps the verdict at `UNKNOWN`, which fails every gate — a partial blast radius is not a small one |
+| `drift` | supported | what changed in the **effective access**, and when | `--capture` records; the default compares against the last record; `--against` compares two profile sets. One arithmetic for both axes, so the time answer and the environment answer cannot disagree. `newly_unmatched` and `newly_matched` are separate buckets, and a `removed` route is never reported as having become safe |
+| `watch` | supported | what each save affected, against a warm index | one JSON line per tick. `--once` is the pre-commit shape; `--ticks`/`--for` bound the loop. A failed analysis is an `error` tick, never an empty change list; a file added since the warm is `unresolved`, not `unreachable` |
+| `self-audit` | supported | whether the **installed build's** own registries agree with each other | a battery proves the source tree consistent while a user runs a wheel. Checks the cache model, format contract, schema registry and output affordances. Says plainly what it cannot check: the semantic engine analyses Java and this build is Python, so those figures are declared absent rather than reported as zeros |
 | `retrieve` | parked | typed knowledge queries over the model | symbol-oriented queries accept `--target/-t`; domain aliases such as `--module/-m`, `--subsystem/-s` and `--endpoint/-e` remain supported |
 | `timeline` | experimental | since when a number moved, and in which commit window | walks the commit series and re-runs the shipped analyses (`posture`, `data-exposure`, `endpoints`, `spring-audit`) on a read-only materialisation of each sampled tree; publishes transitions, not a per-commit dump. A sample that could not be analysed is `null` with a reason, never 0, and a transition under sampling carries the window it could have happened in |
 | `regress` | supported | what moved between two payloads of the same command, and which declaration accounts for it | attributes each delta to a declaration the answers carry (`test_source_excluded`, `symbols_excluded`, `coverage.gaps`, `*_cap`, `waivers`); a delta nothing explains is `unattributed`. Refuses the comparison when `cache_layers`, `base_env` or the analyzer fingerprint differ |
@@ -494,7 +536,7 @@ reading JSON sees the same boundary a buyer reads here.
 | **General request-input-to-sink taint analysis.** | `ask risk` includes two bounded slices for annotated HTTP parameters and positional calls in repository Java sources: known query sinks, and MyBatis statements that splice a value into their SQL. “Known” is a published list — `risk` prints it as `query_sink_vocabulary`, with the calls it deliberately leaves out and why — so a concatenation into a call outside that list is not a miss to be discovered, it is a stated boundary. Anything broader needs value flow through a program, which is a different analysis with a different failure mode: an unsound one produces confident findings that are wrong, and every claim here is meant to be checkable against the line that produced it. | A dataflow scanner (Semgrep, CodeQL) for complete taint. What this product adds on top is reachability and, for the two bounded slices, whether an annotated HTTP input reaches a known concatenated query sink or a spliced SQL statement — the latter with a three-state verdict that says `undecidable` rather than clearing a route it could not follow. |
 | **Secrets outside Java, Spring configuration and the deployment descriptors — a Helm value, a CI variable file, a shell script.** | The file population this analyzer reads is the Java source, the Spring configuration convention and the descriptors it already parses to resolve an environment. A secret elsewhere is not missed by a weak rule; it is outside the set of files anything here opens. Narrowed by CL-10: a credential stored in `web.xml` or a Spring XML context IS reported (SEC-007), because those files were already being read. | A dedicated secret scanner over the whole tree (gitleaks, trufflehog). |
 | **Filter-chain order and per-filter URL patterns — the presence of a custom filter is structural only.** | Which filter runs first is decided by bean ordering this analyzer does not resolve. Where two active configurations both match a request, the answer published is `undecided` rather than a guess. | `ask posture --profile <set>` states per endpoint what the readable rules decide and what they leave undecided. |
-| **Known vulnerabilities in dependencies — no CVE database, no version advisory matching.** | Enriching a vulnerability feed is a different product with a different update cadence; a stale embedded database is worse than no database, because it reads as a clean bill of health. | A dependency scanner (Trivy, OWASP Dependency-Check). `impact-chain` then answers which of its findings anything actually reaches. |
+| **Discovering vulnerabilities, and shipping the database that lists them — no embedded CVE feed, no network lookup at analysis time.** | Maintaining a vulnerability feed is a different product with a different update cadence, and a stale embedded database is worse than no database because it reads as a clean bill of health. That boundary is unchanged. What IS built is the half this project can be responsible for: `ask cve --feed <osv.json>` takes a feed you supply and pin, and answers whether a route can actually REACH the vulnerable package, using the same blast radius as `impact-chain`. The feed's own staleness travels with the answer, an unreadable feed is a refusal rather than a clean scan, and nothing there answers "not reachable". | A dependency scanner (Trivy, OWASP Dependency-Check, an OSV export) supplies the advisories; `ask cve` says which of them anything actually reaches. |
 
 Two more boundaries worth stating in the same voice:
 
@@ -594,6 +636,10 @@ power on Free for small and mid-size repos; you upgrade when the work gets bigge
 ASK Engine monetises enterprise Java monoliths. Activate with `ask activate <key>`.
 Full breakdown: [docs/PRODUCT_TIERS.md](docs/PRODUCT_TIERS.md).
 
+The future commercial direction is staged rather than an immediate product
+restriction: free adoption, self-serve scale, B2B infrastructure licensing and
+a generated public trust projection. See the [monetization review](docs/AUDIT-2026-08-26-MONETIZATION.md).
+
 ---
 
 ## Configuration & privacy
@@ -668,4 +714,5 @@ Matching endpoints report `policy: "custom"` and drop out of the `no_security_si
 | [PRODUCT_IDENTITY.md](docs/PRODUCT_IDENTITY.md) | `ask` (command) vs `sourcecode` (package/alias) |
 | [privacy.md](docs/privacy.md) | Telemetry and data-handling policy |
 | [DEFECT-LEDGER.md](docs/DEFECT-LEDGER.md) | Every defect found in the field, its class, and which release closed it — published on purpose |
+| [AUDIT-2026-08-26-EXTERNAL-5.8.32.md](docs/AUDIT-2026-08-26-EXTERNAL-5.8.32.md) | The most recent external review, its reproduced and **unreproduced** findings, and the feature intake it opened |
 | [spec/envelope-v1.md](docs/spec/envelope-v1.md) | The output format as an **open specification** — provenance, a named unit, a stated basis, declared non-coverage. Implementable by tools that are not this one; the field table is generated from the schema `ask schema envelope-v1` prints |