sourcecode 3.2.0__tar.gz → 3.2.1__tar.gz

{sourcecode-3.2.0 → sourcecode-3.2.1}/CHANGELOG.md

@@ -1,5 +1,200 @@
 # Changelog
 
+## [3.2.1] — 2026-07-29
+
+**M7 complete — the last four seams, the fact registry, and a `--help` that leads with the
+product.** Every fact ADR-0008 named now has one authority, a registered consumer list and an
+assertion that keeps its emitters agreeing. Two of the four seams closed here were found by
+field evaluation #3 *between the two commands it valued most*, and reproducing them showed
+both were worse than reported.
+
+**Upgrade note.** Three published numbers change value. None is a schema break; all are
+corrections, and a pinned threshold may move:
+
+- `modernize.summary.statically_unreferenced` grows sharply — the population it is measured
+  over never matched its own definition (keycloak 14 → 108, BroadleafCommerce 10 → 36,
+  alfresco 13 → 88). `summary.high_coupling_nodes` likewise stops reporting the display cap
+  of 20 and reports the measured count.
+- `endpoints --limit N` no longer reports `total: N`. `total` and the security counters
+  describe the endpoints the *filters* selected; the new `shown` says how many are listed.
+- `posture` verdicts change on repositories that declare `spring.mvc.servlet.path`: rules are
+  matched against the URL the filter chain actually receives, so endpoints previously reported
+  `no_rule_matched` — or, with a catch-all behind the rule, `permit_all` — now carry the
+  decision the matcher makes. Repositories without a declared servlet path are byte-identical.
+
+New keys (`summary.reference_status`, `effective_access.path_basis`, `matched_path`, `shown`,
+and `registries` in both `ask schema` and `ask version`) are additive.
+
+### Changed
+
+- **`--help` no longer introduces the product with its weakest 20 %.** The command table was
+  ordered by the order commands are registered in the source, so a reader met
+  `prepare-context` and `repo-ir` — the two surfaces field evaluation #3 scored lowest —
+  before `posture` and `endpoints`, which the same evaluation called "the product". Commands
+  are now grouped into ordered panels, led by **Java/Spring analysis — start here**
+  (`posture`, `endpoints`, `spring-audit`, `migrate-check`), then *Change and risk*, *Context
+  for AI agents*, *Setup and inspection*, and *Experimental*. Nothing is hidden and nothing is
+  removed; the ordering is one table (`cli.HELP_PANELS`) and the battery fails if a registered
+  command is missing from it, if the table names a command that does not exist, or if the core
+  four stop leading the rendering.
+- **The hand-written "Also available:" catalogue is gone.** A curated list beside a generated
+  one drifts, and it did: it is how `endpoints` shipped while appearing in no `--help` list at
+  all, leaving an evaluator to find the command they valued most inside another command's JSON.
+- **`ask spring-audit --help` now says which gate it is.** `--ci` fails on *any* finding,
+  including debt that was already there — the field read it as baseline-relative and concluded
+  the gate was unusable on a legacy repository. The help now states the gate is absolute and
+  names the baseline-relative one (`ask verify --fail-on new`, `ask pr-impact --fail-on`) and
+  `ask baseline` for tracking the debt. A test asserts those commands and flags exist.
+
+### Added
+
+- **Invariant I-3 in the battery: every registered fact declares what it says when it cannot
+  decide.** ADR-0008 R9 is easy to state and easy to lose — `statically_unreferenced: 0` over
+  3 374 classes is what losing it costs. Each registry entry now carries `unresolved_answer`
+  (the outcome the fact emits when undecidable) plus the reason, or `null` with an explanation
+  of why the fact is total. A declared outcome must exist in the authority that derives it, so
+  the registry cannot document an `unknown` nothing emits — a check that immediately corrected
+  two entries where the unresolved answer belongs to the consumer, not the authority.
+
+- **Invariant I-2 in the battery: a published count may not come from a truncated list.**
+  A static audit over every module (`tests/test_invariant_counts_from_measurement.py`): inside
+  one function, a name bound to a slice and then measured with `len()` in a payload position
+  fails the suite. Display sizes stay legal under an explicit key (`shown`, `omitted`, …),
+  because "how many did you show me" is a different question from "how many are there". The
+  audit is itself guarded against being vacuous.
+  - It found two live ones. `modernize.summary.high_coupling_nodes` reported the display cap
+    (20) as the number of high-coupling classes — a repository with 300 of them said 20; the
+    exact count now ships alongside `high_coupling_nodes_shown`. And `endpoints --limit N`
+    reported `total: N`: `--limit` cuts the rendering, not the population.
+  - **Value change:** with `--limit`, `endpoints` now reports `total` (and the security
+    counters) for the endpoints the *filters* selected, plus a new `shown` for how many are
+    listed. Before, all of them collapsed to the limit. Filters (`--path-prefix`,
+    `--controller`) genuinely change the population and still move `total`.
+
+- **The fact registry ADR-0008 asks for (R11), shipped inside the package and enforced.**
+  `src/sourcecode/facts/registry.json` names every fact that has a single authority: what it
+  means, which `module:symbol` derives it, which modules may emit it, and the parity assertion
+  that keeps those emitters agreeing. Read it from an installed version with
+  `ask schema facts-v1` — a release states its own contract instead of pointing at
+  documentation that can drift from it. No new command: `ask schema` lists it under
+  `registries`, beside the output `schemas`.
+  - The registry is checked, not asserted: the battery fails if an authority does not exist,
+    if a registered consumer does not bind to it (R13 — the LDAP defect survived two releases
+    exactly because a consumer was never rebound), or if a fact carries no parity test (R12).
+    Writing it found two claims of mine that were untrue and one surface — the endpoint
+    security verdict — whose only real consumer is `impact`.
+  - Eleven facts registered, one per M7 seam plus the two each seam split apart.
+
+### Fixed
+
+- **A repository with no tests at all reported `has_tests: true` and "N test files".** Third
+  field evaluation: a Spring monolith whose `src/test` does not exist was described as having
+  4 test files, because production classes living in a package named `test` matched a
+  substring rule. The same document's `analysis_gaps` contradicted it — one document, two
+  derivations of one fact.
+  - New authority `test_sources`: a file is a test source when it sits under a **declared
+    test source root** (`src/test`, `src/it`, `src/androidTest`, `src/testFixtures`, or a
+    repository-level `tests/`, `spec/`, `__tests__/`) or matches an ecosystem **naming
+    convention** (`FooTest.java`, `test_foo.py`, `foo.spec.ts`, `foo_test.go`). A `test`
+    package **inside a main source root is production code** — the build tool's own layout
+    outranks any name.
+  - Five consumers now bind to it instead of re-deriving: `signals.has_tests`, the
+    `analysis_gaps` backend-coverage check (which now also states its basis),
+    `metrics_analyzer.is_test_file`, `prepare-context`'s test/source split, and the review-pr
+    coverage risk.
+  - **Value change:** files under a *main* source root in a directory named `test`/`tests`
+    stop counting as tests. Measured on the fleet: keycloak 2 220 → 1 777 Java test files
+    (443 files under `testsuite/…/src/main/java/…`), BroadleafCommerce 201 → 197,
+    spring-petclinic and openmrs-core unchanged.
+- **`review-pr` reported `test_coverage_risk: "low"` for a diff containing no source files.**
+  In a repository with no tests, a documentation-only PR read as "covered" — the traffic light
+  inverted exactly where a reviewer relies on it. The surface now emits `unknown` with the
+  reason (`no source files changed in this diff`, or `repository declares no test sources`),
+  plus `changed_source_files` and `repository_has_test_sources`. `low` is now reachable only
+  when changed source files were checked and matched (ADR-0008 R9).
+
+- **A class was reported as conditional on a profile *and* on its negation, contradicting
+  `ask posture` in the same run.** Found in the third field evaluation (3.2.0): a
+  configuration class declaring `@Profile("!m3")` — active exactly when `m3` is **absent** —
+  appeared in `signals.spring_profiles.profile_conditional_beans` under `m3` as well. Read as
+  a security fact, it inverts the answer.
+  - Root cause, reproduced: the source scan attributed every `@Profile` to *the next type
+    declaration ahead of it*, falling back to the file name when there was none. A
+  `@Profile("m3")` on a `@Bean` **method** inside that class was therefore attributed to the
+    class itself, next to the class-level `@Profile("!m3")`.
+  - Attribution is now the declaration the annotation actually annotates: only annotations
+    and modifiers may stand between it and a type declaration; a member-level annotation is
+    reported as `Type#member`, and an annotation whose target cannot be read is **not
+    reported at all** rather than attributed to a guess (ADR-0008 R9).
+  - **Value change:** member-level declarations move from the enclosing type to the member.
+    On the reference fleet this affects one symbol (`spring-petclinic`:
+    `MysqlTestApplication` → `MysqlTestApplication#container`); on repositories that put
+    `@Profile` on `@Bean` methods it affects each such method.
+  - New in the payload: `signals.spring_profiles.conditional_beans[]` with `symbol`,
+    `profiles`, `expression` (as written) and `source_file`. The token map
+    (`profile_conditional_beans`) buckets `@Profile("a & !b")` under `a` and `!b` with the
+    operator lost; the list keeps the expression, and both are now projections of **one**
+    derivation, so they cannot disagree.
+  - Parity assertion added: no symbol may be reported as conditional on a profile that
+    `posture` resolves it inactive under (invariant I-1).
+
+- **`ask modernize` reported `statically_unreferenced: 0` across a 3 374-class monolith.**
+  Read as "there is no unreferenced code here", when what it meant was "a check that cannot
+  see framework dispatch found nothing" — the one place the product broke its own rule about
+  never publishing a number where the honest answer is `unknown` (ADR-0008 R9). Two causes:
+  - The population never matched the published definition. The note said "zero static
+    callers", the code examined only types with **no edges in either direction** — so a type
+    that calls something but is called by nothing was never a candidate at all.
+  - The surface had two buckets and the question has three answers.
+  - One authority now derives it, `reference_facts`, as a partition that sums to the classes
+    examined: `referenced` (an incoming edge, or another source naming it) /
+    `unknown_framework_dispatch` (no static caller, but a published annotation, an entry-point
+    signature, or the name wired from a configuration file) / `no_static_callers` (neither —
+    **absence of evidence, never "dead code"**). `summary.reference_status` carries the exact
+    counts and a `statement` that explains a zero instead of publishing it bare.
+  - Counts come from the measurement, not from `len()` of the lists, which are cut to 20 for
+    display (R5). Every listed type carries the `basis` for being there.
+  - Dispatch detection extended with published stereotype, persistence and entry-point
+    vocabulary (`@Component`/`@Service`/`@Repository`/`@Controller`/`@RestController`/
+    `@Configuration`/`@Entity`/`@Embeddable`/`@MappedSuperclass`/`@Aspect`/`@WebServlet`/
+    `@WebFilter`/`@WebListener`/`@SpringBootApplication`, `public static void main`), and the
+    configuration-name scan now matches whole names — `Order` inside `OrderItemImpl` was
+    marking live-looking classes dispatched.
+  - **Value change:** the candidate population is much larger, so the counts move.
+    keycloak 14 → 108 `no_static_callers`, BroadleafCommerce 10 → 36, alfresco 13 → 88;
+    spring-petclinic stays 0 and now says why (its one callerless type is an `@Entity`, so
+    the answer is `unknown`). The scan is also faster than the one it replaces: one repository
+    walk instead of two, and fixed patterns intersected with the candidate set rather than an
+    alternation over it (keycloak 2.5 s → 1.2 s).
+
+- **`ask posture` decided endpoint access against a URL the application never serves.** A
+  repository declaring `spring.mvc.servlet.path=/api` is served at `/api/orders`, and that is
+  the URL its filter chain matches — but the chain rules were compared against the
+  mapping-relative `/orders`. A rule reading `.antMatchers("/api/**").authenticated()`
+  therefore covered nothing. Reported from the field as 2 632 endpoints falsely
+  `no_rule_matched`; reproduced in a fixture, it is worse than that — where a catch-all
+  `anyRequest().permitAll()` follows the rule, those endpoints were reported **`permit_all`**,
+  which states a protected endpoint is open.
+  - One authority for the prefix: `deployment_prefix`, the same module `ask endpoints` reads
+    for `effective_path`. `posture` asks it for the part a matcher actually sees — the
+    **servlet path**, resolved for the profile set you asked about, so a servlet path declared
+    only under `prod` applies exactly when `prod` does. The servlet **context** path is
+    excluded on purpose: the container strips it before the filter chain runs.
+  - Matcher semantics are honoured rather than averaged: `antMatchers`/`regexMatchers` match
+    the servlet-path-prefixed URL, `mvcMatchers` matches relative to the servlet mapping, and
+    `requestMatchers` is either one depending on the Spring Security version and classpath —
+    unreadable from source, so a rule covering the request under either reading is honoured.
+  - New in the payload: `effective_access.path_basis` states the servlet path used and where
+    it came from, and each stated endpoint carries `matched_path` in its evidence when the
+    matched URL differs from the endpoint's mapping-relative path.
+  - **Never a guessed URL** (ADR-0008 R9): where a servlet path is declared but cannot be
+    resolved (a `${PLACEHOLDER}`, or documents that disagree), every verdict that depends on a
+    path pattern is reported `undecided` with `decision_if_unprefixed`, instead of computed
+    against an assumed empty prefix.
+  - **Value change:** none on a repository that declares no servlet path — the two readings
+    coincide and the matching is unchanged. Verified byte-identical on spring-petclinic,
+    keycloak, BroadleafCommerce and spaghetti-api, none of which declare one.
+
 ## [3.2.0] — 2026-07-28
 
 **Answer coherence (M7, first four seams).** One fact, one authority (ADR-0008). Four

{sourcecode-3.2.0 → sourcecode-3.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 3.2.0
+Version: 3.2.1
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -73,6 +73,15 @@ Cache keyed on content hashes — invalidated only when source changes. On repea
 
 At 0.3s per call, ASK Engine becomes **constant infrastructure** inside agent loops — call it before every edit, every PR review, every test run, without batching or caching manually.
 
+**What a warm actually covers.** `ask cache warm` runs the compact analysis: it rebuilds the
+shared structural layers (L1/L2 + the Repository Intelligence Snapshot) and the **compact
+view**. Pass `--agent` to warm the agent view as well. Deeper projections are separate view
+keys and are *not* covered by either — `--full`, `--env-map` and a raised `--depth` recompute
+on first use, as do most `prepare-context` tasks. Measured on a 3,342-file Spring monolith:
+`cache warm` 103s → `--compact --git-context` 1s (hit), but `--agent --full --env-map
+--depth 20` still 171s (miss). Budget the deep run explicitly in CI, or warm exactly the view
+your pipeline consumes. Full model: [USER_GUIDE.md#caching](docs/USER_GUIDE.md#caching).
+
 ---
 
 ## Install
@@ -95,27 +104,55 @@ ask version                    # ask 2.5.1
 
 ## Quickstart
 
+**Start with these four.** In three independent field evaluations they carried most of the
+measured value, and `posture --diff` is the one no evaluator found an equivalent for —
+commercial or open source.
+
 ```bash
-# High-signal structural summary — warm cache ~0.3s, cold 2–10s
-ask --compact
+# What does each profile set ACTUALLY wire — and what changes between them?
+# Resolves conditional beans and the filter chain, then diffs effective endpoint access.
+ask posture /path/to/repo --diff dev:prod
 
-# Blast radius: what breaks if this class changes?
-ask impact OrderService /path/to/repo
+# Every REST endpoint with its effective path (context-path + servlet path resolved),
+# its inferred security policy and a confidence per endpoint.
+ask endpoints /path/to/repo
+
+# Spring semantic audit: transactional anomalies (private @Transactional = silent
+# CGLIB no-op), security surface, request-body validation.
+ask spring-audit /path/to/repo
 
-# Spring Boot 2→3 migration readiness (bounded decision summary)
+# Spring Boot 2→3 readiness: located blockers, per-dimension score, effort estimate.
 ask migrate-check /path/to/repo --compact
+```
 
-# Spring semantic audit: TX anomalies + security surface
-ask spring-audit /path/to/repo
+Then the everyday loop:
+
+```bash
+# High-signal structural summary — warm cache ~0.3s, cold 2–10s
+ask --compact
+
+# Blast radius: what breaks if this class changes?  (target the INTERFACE, not the Impl)
+ask impact OrderService /path/to/repo
 
 # Onboard to an unfamiliar codebase
 ask onboard /path/to/repo
 
 # PR review: risk, test gaps, changed modules
 ask review-pr /path/to/repo --since main
+
+# CI gate on NEW violations only, instead of on pre-existing debt
+ask verify /path/to/repo --capture-baseline   # accept today's debt, once
+ask verify /path/to/repo                      # then: only new violations block
 ```
 
-Full command reference: **[docs/USER_GUIDE.md](docs/USER_GUIDE.md)**.
+> **Adopting a gate on a real codebase.** A repository that starts declaring contracts already
+> violates them somewhere; `ask verify` is **baseline-relative by default** (`--fail-on new`)
+> so the gate survives contact with reality instead of being switched off on day one.
+> `ask baseline capture|diff|trend` is a different thing: versioned architectural metrics over
+> time, for trend reporting rather than blocking.
+
+Full command reference: **[docs/USER_GUIDE.md](docs/USER_GUIDE.md)** · posture in depth:
+**[docs/posture.md](docs/posture.md)**.
 
 ---
 
@@ -148,6 +185,15 @@ Deterministic Spring semantics: transactional anomalies (e.g. `@Transactional` o
 `ask spring-audit` · `ask validation`
 → [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`
+→ [posture.md](docs/posture.md)
+
+Unresolved is a first-class outcome: a condition the resolver cannot decide is reported as a
+hole with the condition named, never folded into active or inactive. **A posture answer that
+guesses is a confident security falsehood — the worst failure mode this tool has.**
+
 ### 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`
@@ -159,6 +205,36 @@ The everyday loop: diff-based PR review, symptom-driven bug triage, and delta co
 
 ---
 
+## Every command, in one table
+
+*`ask --help` shows a short header; this is the full surface. If you only read one row, read
+`posture`.*
+
+| Command | Answers | Note |
+|---|---|---|
+| `posture` | which beans a profile set wires, and how effective endpoint access differs between two sets | **experimental**, most differentiated |
+| `endpoints` | every REST endpoint, effective path, security policy, confidence | Spring MVC + JAX-RS (~65 % recall on JAX-RS sub-resource locators) |
+| `spring-audit` | transactional anomalies + security surface + validation gaps | `--ci`, `-f github-comment` |
+| `migrate-check` | Boot 2→3 readiness: located blockers, per-dimension score, effort | `--blast-radius` orders the re-test plan |
+| `impact` / `impact-chain` | blast radius of a change, to the endpoints it reaches | target the **interface**, not the `Impl` |
+| `pr-impact` | the same, scoped to a PR diff | gating command: `--fail-on`, exit codes |
+| `verify` | does the repo satisfy its declared contracts, **relative to a baseline** | `.ask/contracts.yml`; exit 0/1/2 |
+| `verify-edit` | did the working-tree edits change runtime behaviour | semantic diff gate for the edit loop |
+| `--compact` / `--agent` | bounded structural context for an agent | `--compact` is the token-cheap one |
+| `onboard` / `explain` / `cold-start` | orientation in an unfamiliar repo; per-class summary; bootstrap snapshot | |
+| `export` / `repo-ir` / `schema` | tool-agnostic views (C4, module graph, integrations); symbol-level IR; published JSON Schemas | |
+| `modernize` | coupling hubs, cycles, dead zones, refactor candidates | |
+| `review-pr` / `fix-bug` / `prepare-context` | diff review, symptom triage, task-shaped context | |
+| `plan` / `compare` / `delta` / `contract-diff` | what to review for a change; candidates by measured cost; outcome of a change; public-contract break | no verdicts, measured cost only |
+| `validation` | request-body validation coverage and gaps | |
+| `baseline capture\|diff\|trend` | versioned architectural metrics over time | trend reporting, not gating |
+| `retrieve` | typed knowledge queries over the model | **experimental** |
+| `archetype` | evidence-based architectural archetype | **experimental** |
+| `rename-class` / `chunk-file` | word-boundary Java rename; split a large file for an agent | |
+| `cache status\|warm\|clear` · `auth` · `telemetry` · `mcp` · `config` · `version` | housekeeping | |
+
+---
+
 ## What it does — and doesn't
 
 **ASK Engine reduces exploration cost.** It accelerates context acquisition and computes
@@ -182,6 +258,13 @@ Honest limits worth knowing before you rely on it:
 > **🎉 Early-adoption: Pro is currently unlocked for everyone.** Every install runs with
 > full Pro entitlements — no size gate, no key. The tiers below describe the model the
 > paywall will return to later.
+>
+> **What that means concretely.** `ask auth status` reports `"status": "unauthenticated"`
+> together with `"pro": true`, `"pro_reason": "early-adoption unlock"` — that combination is
+> expected, not a bug: you are unauthenticated *and* unlocked. When the unlock ends, gating
+> returns **by repo size and automation, never by command**: `posture`, `endpoints`,
+> `spring-audit` and `migrate-check` stay in the base tier at full output. Nothing you can run
+> today becomes a paid-only command tomorrow.
 
 **Gating is by repo size and automation — never by command.** Every command runs at full
 power on Free for small and mid-size repos; you upgrade when the work gets bigger or automated.
@@ -209,7 +292,13 @@ ask telemetry disable   # anonymous telemetry is on by default (opt-out)
 
 Telemetry collects version, OS, commands, flags, duration, repo-size range, and errors —
 **no source code, paths, secrets, or output**. Disable any time with
-`export SOURCECODE_TELEMETRY=0` (or `DO_NOT_TRACK=1`).
+`export SOURCECODE_TELEMETRY=0` (or `DO_NOT_TRACK=1`). It defaults to **off in CI**.
+
+> **Auditing someone else's code — regulated, client-owned or public-sector?** Turn it off
+> *before* the first run, not after: `SOURCECODE_TELEMETRY=0 ask …`, or `ask telemetry disable`
+> once (remembered). The default is opt-out today; **moving it to opt-in is on the roadmap**
+> (`docs/DEFECT-LEDGER.md` P-1) precisely because a default you must remember to disable is the
+> wrong default for third-party code.
 
 **Custom security annotations.** Teach `endpoints`, `spring-audit`, and `explain` about
 project-specific authorization annotations via an optional `sourcecode.config.json` at the
@@ -241,3 +330,4 @@ Matching endpoints report `policy: "custom"` and drop out of the `no_security_si
 | [MANUAL-USUARIO.md](docs/MANUAL-USUARIO.md) | Guía de usuario en español |
 | [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 |

{sourcecode-3.2.0 → sourcecode-3.2.1}/README.md

@@ -35,6 +35,15 @@ Cache keyed on content hashes — invalidated only when source changes. On repea
 
 At 0.3s per call, ASK Engine becomes **constant infrastructure** inside agent loops — call it before every edit, every PR review, every test run, without batching or caching manually.
 
+**What a warm actually covers.** `ask cache warm` runs the compact analysis: it rebuilds the
+shared structural layers (L1/L2 + the Repository Intelligence Snapshot) and the **compact
+view**. Pass `--agent` to warm the agent view as well. Deeper projections are separate view
+keys and are *not* covered by either — `--full`, `--env-map` and a raised `--depth` recompute
+on first use, as do most `prepare-context` tasks. Measured on a 3,342-file Spring monolith:
+`cache warm` 103s → `--compact --git-context` 1s (hit), but `--agent --full --env-map
+--depth 20` still 171s (miss). Budget the deep run explicitly in CI, or warm exactly the view
+your pipeline consumes. Full model: [USER_GUIDE.md#caching](docs/USER_GUIDE.md#caching).
+
 ---
 
 ## Install
@@ -57,27 +66,55 @@ ask version                    # ask 2.5.1
 
 ## Quickstart
 
+**Start with these four.** In three independent field evaluations they carried most of the
+measured value, and `posture --diff` is the one no evaluator found an equivalent for —
+commercial or open source.
+
 ```bash
-# High-signal structural summary — warm cache ~0.3s, cold 2–10s
-ask --compact
+# What does each profile set ACTUALLY wire — and what changes between them?
+# Resolves conditional beans and the filter chain, then diffs effective endpoint access.
+ask posture /path/to/repo --diff dev:prod
 
-# Blast radius: what breaks if this class changes?
-ask impact OrderService /path/to/repo
+# Every REST endpoint with its effective path (context-path + servlet path resolved),
+# its inferred security policy and a confidence per endpoint.
+ask endpoints /path/to/repo
+
+# Spring semantic audit: transactional anomalies (private @Transactional = silent
+# CGLIB no-op), security surface, request-body validation.
+ask spring-audit /path/to/repo
 
-# Spring Boot 2→3 migration readiness (bounded decision summary)
+# Spring Boot 2→3 readiness: located blockers, per-dimension score, effort estimate.
 ask migrate-check /path/to/repo --compact
+```
 
-# Spring semantic audit: TX anomalies + security surface
-ask spring-audit /path/to/repo
+Then the everyday loop:
+
+```bash
+# High-signal structural summary — warm cache ~0.3s, cold 2–10s
+ask --compact
+
+# Blast radius: what breaks if this class changes?  (target the INTERFACE, not the Impl)
+ask impact OrderService /path/to/repo
 
 # Onboard to an unfamiliar codebase
 ask onboard /path/to/repo
 
 # PR review: risk, test gaps, changed modules
 ask review-pr /path/to/repo --since main
+
+# CI gate on NEW violations only, instead of on pre-existing debt
+ask verify /path/to/repo --capture-baseline   # accept today's debt, once
+ask verify /path/to/repo                      # then: only new violations block
 ```
 
-Full command reference: **[docs/USER_GUIDE.md](docs/USER_GUIDE.md)**.
+> **Adopting a gate on a real codebase.** A repository that starts declaring contracts already
+> violates them somewhere; `ask verify` is **baseline-relative by default** (`--fail-on new`)
+> so the gate survives contact with reality instead of being switched off on day one.
+> `ask baseline capture|diff|trend` is a different thing: versioned architectural metrics over
+> time, for trend reporting rather than blocking.
+
+Full command reference: **[docs/USER_GUIDE.md](docs/USER_GUIDE.md)** · posture in depth:
+**[docs/posture.md](docs/posture.md)**.
 
 ---
 
@@ -110,6 +147,15 @@ Deterministic Spring semantics: transactional anomalies (e.g. `@Transactional` o
 `ask spring-audit` · `ask validation`
 → [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`
+→ [posture.md](docs/posture.md)
+
+Unresolved is a first-class outcome: a condition the resolver cannot decide is reported as a
+hole with the condition named, never folded into active or inactive. **A posture answer that
+guesses is a confident security falsehood — the worst failure mode this tool has.**
+
 ### 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`
@@ -121,6 +167,36 @@ The everyday loop: diff-based PR review, symptom-driven bug triage, and delta co
 
 ---
 
+## Every command, in one table
+
+*`ask --help` shows a short header; this is the full surface. If you only read one row, read
+`posture`.*
+
+| Command | Answers | Note |
+|---|---|---|
+| `posture` | which beans a profile set wires, and how effective endpoint access differs between two sets | **experimental**, most differentiated |
+| `endpoints` | every REST endpoint, effective path, security policy, confidence | Spring MVC + JAX-RS (~65 % recall on JAX-RS sub-resource locators) |
+| `spring-audit` | transactional anomalies + security surface + validation gaps | `--ci`, `-f github-comment` |
+| `migrate-check` | Boot 2→3 readiness: located blockers, per-dimension score, effort | `--blast-radius` orders the re-test plan |
+| `impact` / `impact-chain` | blast radius of a change, to the endpoints it reaches | target the **interface**, not the `Impl` |
+| `pr-impact` | the same, scoped to a PR diff | gating command: `--fail-on`, exit codes |
+| `verify` | does the repo satisfy its declared contracts, **relative to a baseline** | `.ask/contracts.yml`; exit 0/1/2 |
+| `verify-edit` | did the working-tree edits change runtime behaviour | semantic diff gate for the edit loop |
+| `--compact` / `--agent` | bounded structural context for an agent | `--compact` is the token-cheap one |
+| `onboard` / `explain` / `cold-start` | orientation in an unfamiliar repo; per-class summary; bootstrap snapshot | |
+| `export` / `repo-ir` / `schema` | tool-agnostic views (C4, module graph, integrations); symbol-level IR; published JSON Schemas | |
+| `modernize` | coupling hubs, cycles, dead zones, refactor candidates | |
+| `review-pr` / `fix-bug` / `prepare-context` | diff review, symptom triage, task-shaped context | |
+| `plan` / `compare` / `delta` / `contract-diff` | what to review for a change; candidates by measured cost; outcome of a change; public-contract break | no verdicts, measured cost only |
+| `validation` | request-body validation coverage and gaps | |
+| `baseline capture\|diff\|trend` | versioned architectural metrics over time | trend reporting, not gating |
+| `retrieve` | typed knowledge queries over the model | **experimental** |
+| `archetype` | evidence-based architectural archetype | **experimental** |
+| `rename-class` / `chunk-file` | word-boundary Java rename; split a large file for an agent | |
+| `cache status\|warm\|clear` · `auth` · `telemetry` · `mcp` · `config` · `version` | housekeeping | |
+
+---
+
 ## What it does — and doesn't
 
 **ASK Engine reduces exploration cost.** It accelerates context acquisition and computes
@@ -144,6 +220,13 @@ Honest limits worth knowing before you rely on it:
 > **🎉 Early-adoption: Pro is currently unlocked for everyone.** Every install runs with
 > full Pro entitlements — no size gate, no key. The tiers below describe the model the
 > paywall will return to later.
+>
+> **What that means concretely.** `ask auth status` reports `"status": "unauthenticated"`
+> together with `"pro": true`, `"pro_reason": "early-adoption unlock"` — that combination is
+> expected, not a bug: you are unauthenticated *and* unlocked. When the unlock ends, gating
+> returns **by repo size and automation, never by command**: `posture`, `endpoints`,
+> `spring-audit` and `migrate-check` stay in the base tier at full output. Nothing you can run
+> today becomes a paid-only command tomorrow.
 
 **Gating is by repo size and automation — never by command.** Every command runs at full
 power on Free for small and mid-size repos; you upgrade when the work gets bigger or automated.
@@ -171,7 +254,13 @@ ask telemetry disable   # anonymous telemetry is on by default (opt-out)
 
 Telemetry collects version, OS, commands, flags, duration, repo-size range, and errors —
 **no source code, paths, secrets, or output**. Disable any time with
-`export SOURCECODE_TELEMETRY=0` (or `DO_NOT_TRACK=1`).
+`export SOURCECODE_TELEMETRY=0` (or `DO_NOT_TRACK=1`). It defaults to **off in CI**.
+
+> **Auditing someone else's code — regulated, client-owned or public-sector?** Turn it off
+> *before* the first run, not after: `SOURCECODE_TELEMETRY=0 ask …`, or `ask telemetry disable`
+> once (remembered). The default is opt-out today; **moving it to opt-in is on the roadmap**
+> (`docs/DEFECT-LEDGER.md` P-1) precisely because a default you must remember to disable is the
+> wrong default for third-party code.
 
 **Custom security annotations.** Teach `endpoints`, `spring-audit`, and `explain` about
 project-specific authorization annotations via an optional `sourcecode.config.json` at the
@@ -203,3 +292,4 @@ Matching endpoints report `policy: "custom"` and drop out of the `no_security_si
 | [MANUAL-USUARIO.md](docs/MANUAL-USUARIO.md) | Guía de usuario en español |
 | [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 |

{sourcecode-3.2.0 → sourcecode-3.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "3.2.0"
+version = "3.2.1"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-3.2.0 → sourcecode-3.2.1}/src/sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "3.2.0"
+__version__ = "3.2.1"

{sourcecode-3.2.0 → sourcecode-3.2.1}/src/sourcecode/chain_rules.py

@@ -274,16 +274,57 @@ def rule_matches(rule: AccessRule, method: str, path: str) -> bool:
     return any(ant_matches(pattern, path) for pattern in rule.patterns)
 
 
-def first_matching_rule(
-    rules: "list[AccessRule]", method: str, path: str
-) -> "Optional[AccessRule]":
-    """The rule Spring would apply: the first declared one that matches."""
+#: Matchers that see the DispatcherServlet path. An ant matcher matches the URL
+#: the filter chain receives — servlet path included, servlet CONTEXT path never,
+#: because the container has already stripped it. An mvc matcher matches the path
+#: relative to the servlet mapping, so the servlet path is not part of it.
+#: `requestMatchers` is either one depending on the Spring Security version and
+#: what is on the classpath — undecidable from source, so both readings are tried
+#: and the pattern is honoured if it covers the request under either.
+_SERVLET_PATH_MATCHERS = ("antMatchers", "regexMatchers", "requestMatchers")
+_SERVLET_RELATIVE_MATCHERS = ("mvcMatchers", "requestMatchers")
+
+
+def candidate_paths(rule: AccessRule, path: str, servlet_prefix: str = "") -> "tuple[str, ...]":
+    """The path(s) `rule`'s matcher compares against a mapping-relative `path`.
+
+    Without a declared servlet path the two readings coincide and this is just
+    `(path,)` — which is every repository that never set `spring.mvc.servlet.path`.
+    """
+    if not servlet_prefix or rule.is_any_request:
+        return (path,)
+    prefixed = f"{servlet_prefix.rstrip('/')}/{path.lstrip('/')}".rstrip("/") or "/"
+    out: list[str] = []
+    if rule.matcher in _SERVLET_PATH_MATCHERS:
+        out.append(prefixed)
+    if rule.matcher in _SERVLET_RELATIVE_MATCHERS or not out:
+        out.append(path)
+    return tuple(dict.fromkeys(out))
+
+
+def first_match(
+    rules: "list[AccessRule]", method: str, path: str, servlet_prefix: str = ""
+) -> "tuple[Optional[AccessRule], str]":
+    """`(rule Spring would apply, the path it matched)` — first declared wins.
+
+    The matched path is returned because with a servlet path declared it is not
+    the mapping-relative path the endpoint is keyed by, and a reader checking the
+    claim against the source line needs to see the URL the rule actually covers.
+    """
     for rule in rules:
         if rule.paths_unknown:
             # A rule whose paths could not be read may cover this request, and
             # everything after it is only reachable if it does not. Stopping here
             # is what keeps a later `permitAll` from being reported as the answer.
-            return rule
-        if rule_matches(rule, method, path):
-            return rule
-    return None
+            return rule, path
+        for candidate in candidate_paths(rule, path, servlet_prefix):
+            if rule_matches(rule, method, candidate):
+                return rule, candidate
+    return None, path
+
+
+def first_matching_rule(
+    rules: "list[AccessRule]", method: str, path: str, servlet_prefix: str = ""
+) -> "Optional[AccessRule]":
+    """The rule Spring would apply: the first declared one that matches."""
+    return first_match(rules, method, path, servlet_prefix)[0]