sourcecode 3.4.0__tar.gz → 3.6.0__tar.gz

{sourcecode-3.4.0 → sourcecode-3.6.0}/CHANGELOG.md

@@ -1,6 +1,432 @@
 # Changelog
 
-## [Unreleased]
+## [3.6.0] — 2026-08-01
+
+**The P0 block and the C1/C2 backlog.** Nine rows closed, three closed by measurement alone
+(C1-17, C2-11, and C2-12 as stated did not reproduce). `migrate-check` stops billing work a
+declared dependency already did, stops billing a Hibernate rewrite to another vendor's provider,
+and stops assuming a single destination — `--target-jdk 11 --keep-boot` takes MIG-001 from 85 to 0
+on openmrs-core.
+
+Two patterns from 3.5.0 repeat, and both are worth carrying forward. **The reported symptom keeps
+being narrower than the defect**: C1-10 was one rule and was also an evidence rule admitting JPA as
+proof of Hibernate; C2-1 was a `why` trail and was also the ranking key underneath it. **And a
+curated list beside real data keeps being the cause** — C2-3's trim schedule named sections the
+payload does not have while the weight sat in two it never mentions, the third appearance of the
+C4-1 shape in two releases.
+
+**Minor, not patch**: blocking counts move (C1-10), reach-derived counts become nullable (C1-13),
+`compare`'s ranking can move (C2-1), `migrate-check.findings` keeps one type across `--compact`
+(C2-10), and two commands that wrote their confirmation to stderr now write it to stdout (C3-18).
+
+### Added
+
+- **`migrate-check --target-jdk N` and `--keep-boot`** (C1-15, P0 gate 2). Asked about a JDK move,
+  the answer was `headline_blocker: boot3_migration` with fix hints sending a developer to migrate
+  481 `javax.persistence` imports they never planned to touch; nothing could say "JDK 11, keep Boot
+  2.7". The route is filtered over the `migration_target` vocabulary every rule already carried.
+  Measured on openmrs-core with `--target-jdk 11 --keep-boot`: **MIG-001 85 → 0**, blocking 114 → 0,
+  headline `hibernate_rewrite` → `none_applicable`. Narrowing is not silencing — `metadata.route`
+  publishes the target and every excluded axis, and a `limitations` entry states what was left out
+  and that it is unresolved, not fixed. **The default is unchanged**: no flags means every axis at
+  once.
+
+- **`spring-audit` findings carry `first_line`** (C2-4), from the `SourceSpan` index the IR already
+  records. `null` where the symbol has no recorded span, never 0.
+
+### Changed
+
+- **`migrate-check` reconciles findings with the build it already read** (C1-10, P0 gate 1,
+  **blocking counts move**). `MIG-021` fired as blocking while `javax.xml.bind:jaxb-api:2.3.1` sat
+  in the same `pom.xml`. A rule now declares the coordinates that satisfy it; a satisfied finding
+  gets `mitigated_by` and `code_context: "dependency_satisfied"`, leaving `blocking_count` exactly
+  as test scope does, and its hint stops saying "add this dependency". `satisfied_by` is empty for
+  every rule whose remedy is a source change.
+  - **The Hibernate axis now needs Hibernate evidence.** It billed 45.6 days to a repository whose
+    declared provider was EclipseLink because a bare `javax.persistence` import counted as proof —
+    that proves JPA, not Hibernate. A declared competing provider refutes the inference, and only
+    the inference: a repository carrying both coordinates keeps direct evidence. An inference from
+    a JPA import alone now reports `medium`, not `high`.
+  - Battery: `blocking_count` identical on all six repositories.
+
+- **A capped blast radius answers `unknown`, not `0`** (C1-13, **reach-derived counts become
+  nullable**). A hub capped at `depth=1` reported `endpoints_affected_count: 0` for a walk that
+  never looked. Under the cap a reach-derived zero becomes `null`, named in
+  `stats.unknown_under_cap`. A **non-zero** count under the cap stays a number — it is a floor — and
+  an **uncapped** run keeps its measured zero.
+
+- **`compare` ranks on measurements, not on rendered rows** (C1-13/C2-1, **ranking may move**).
+  Three of the seven cost fields were `len()` of a display list, so the ordering was computed over
+  however many rows the renderer had decided to show. Capped magnitudes are declared in
+  `cost_floor_fields` beside `cost`, never inside it.
+
+- **`impact.endpoints_affected[]` gains `controller_class` and `handler_symbol`** (C2-12), the names
+  `impact-chain` already uses. Grouping by controller needed a different key per command on payloads
+  one run produces. Original keys kept as aliases.
+
+- **`effort_breakdown.affected_files` is now `blocking_affected_files`** (C1-14, alias kept). It
+  named a different population from `summary.affected_files` — 264 against 265 on openmrs-core — and
+  the shared name was the whole of the contradiction. Both carry a `_basis`.
+
+### Fixed
+
+- **The payload budget cuts where the bytes are** (C2-3). `_TRIM_SCHEDULE` is a hand-written list of
+  key names: on a 1 222-file `review-pr` diff it trimmed 1 733 KB → 1 732 KB against a 97 KB budget,
+  walking to `execution_paths` while every byte sat in `changed_files` and `runtime_changes`, which
+  it does not mention. Once the schedule is exhausted the remaining cut is chosen by measuring which
+  list is largest. Measured on that payload shape: **566 KB → 71 KB**.
+
+- **`ask verify` no longer passes with zero contracts declared** (C3-15, **behaviour change for
+  pipelines**). It returned `pass` + exit 0 on a repository that declared nothing — a green light
+  for having verified nothing. `evaluate_repo` returns before it even builds the CIR when no
+  contracts exist, so no code was read and no contract was checked: the same standing as a
+  repository that could not be analysed, and now reported the same way — **`unverified`, exit 2**,
+  with the reason stated. Exit 2 and not 1 because the published contract reserves 1 for
+  violations found and 2 for a run that could not verify. Asserted under every `--fail-on` choice:
+  `never` suppresses violations from blocking, it does not turn a run that verified nothing into a
+  verified one. This is C3-22 in different clothes — there a typo in `$DIR` made the gate
+  permanently green, here a repository that never adopted contracts did.
+
+- **A command that writes its answer to a file now confirms on stdout, not stderr** (C3-18,
+  **behaviour change for scripts reading stderr**). `repo-ir`, `modernize`, `export` and
+  `cold-start` wrote the "written to" confirmation to stderr while the payload went to the file
+  and stdout stayed empty, so `ask repo-ir -o ir.json > log.txt` captured **nothing** and
+  PowerShell 5.1 raised `NativeCommandError` over a run that succeeded. Measured on
+  spring-petclinic before the fix: stdout 0 bytes, stderr 155. C3-26 set this rule in 3.5.0 for
+  `cache warm`/`cache clear`; these four were missed because the stderr battery listed its
+  commands **by hand**. The `--output` rows are now discovered from the CLI.
+
+- **Usage errors emit the JSON envelope for a pipeline** (C3-4). The interception was patched onto
+  `click.UsageError.show`, which Typer never calls when `rich_markup_mode` is set — it is, for the
+  help panels — so **no usage error had been emitting an envelope at all** and `ask <cmd>
+  --badflag` answered automation with a rich text box. Split by audience: a pipeline gets the
+  envelope, a person at a terminal keeps the `Usage:` line and the pointer to `--help`.
+
+- **A flag no longer changes the type of a key** (C2-10, **breaking for `--compact` consumers**).
+  `migrate-check.findings` was a bare array in full output and a
+  `{total, shown, omitted, items}` object under `--compact` — the same key, two types. A consumer
+  iterating `findings` broke silently on a flag it did not pass: nothing errored, the loop simply
+  ran over the four keys of a summary object instead of over the findings.
+  - `findings` is a **list in both modes**. The counts moved to a `findings_cap` sibling that
+    exists **only when a cap actually bit**, and it carries the I-8 `display_list` statement of
+    what the cut changed and what stayed exact.
+  - **Five collections had it, not one**: top-level `findings`, `hibernate.rewrite_targets`,
+    `hibernate.findings`, `hibernate.critical_call_chains`, `hibernate.golden_sql_hotspots`, and
+    `blast_radius.files`.
+  - **Half of C2-13 falls out of the same fix.** `migrate-check.findings` is now the bare array
+    `spring-audit.findings` always was — one word, one type, one parser, measured across all
+    three payloads. The `schema_version` fragmentation is the half that stays open.
+  - Enforced rather than documented: `tests/test_flag_shape_stability.py` walks both payloads key
+    by key and fails on any type that moves. The same walk covers the root command's `--compact`
+    and `--agent`, which were **measured clean** while fixing this and are locked so they stay
+    clean.
+
+- **A misplaced global flag is told where that flag lives** (C3-4). `ask spring-audit --full`
+  answered "No such option: --full" about a flag the tool does have — it is declared on the root
+  command. The flag is looked up on the root command, so every global flag typed after every
+  subcommand is covered and no flag name is written into the check; a genuinely unknown flag earns
+  no hint, asserted.
+
+- **`repo-ir` states the output cost before it is paid** (C3-18). The advisory ran after the IR was
+  built, serialized and written — the whole bill settled. It now runs off the file count before the
+  build starts, as a **band** (10.8–27.9 KB per Java file) rather than a point: the per-file cost
+  spreads 2.6× across sampled repositories with how densely the code cross-references, and
+  publishing a midpoint as one figure is the C1-12 defect. The band is asserted to bracket what
+  those repositories actually produced.
+
+- **A capped `file_relevance` list says what was cut, measured** (C3-20). The hint published the
+  *budget* as the number of files shown — on spring-petclinic, "Showing top 40/176" beside a list
+  of **25** — fired even when nothing had been cut, and advised `--full` while `--full` was active.
+  Two constraints trim the list (a visibility threshold and a per-category cap of half the budget)
+  and the sentence knew about neither. Now: nothing unless a cap really bit, the figure is what was
+  shown against the population it samples, a flag is named only when it would change the answer,
+  and the I-8 `display_list` block sits beside it.
+
+- **`--no-cache` on a subcommand says what it does** (C3-5). Six commands claimed "always reads
+  fresh source (no snapshot cache)" while `ask cache model` records them reading `ris`, `cir` and
+  `parse`. One string now, stating the reason it is a no-op: since C1-9 every layer keys on the
+  exact tree state and the parse layer is content-addressed, so there is no staleness to bypass.
+  The flag stays accepted so scripts do not break, and is real on `ask --no-cache` (root).
+
+- **`--output <file>` now returns the whole answer, which is what its own note promised**
+  (C2-2, first M8 increment). Measured on `org.broadleafcommerce.common.money.Money`: the file
+  held **30 of 134** caller classes and **50 of 1 302** indirect callers — the same sample stdout
+  gets — while the payload told the reader *"use `--output` for the full list"*.
+  - **The recorded cause was wrong, and fixing what was recorded would not have worked.** The
+    file carried no `_budget_note` at all: the caps were applied at *construction*, inside
+    `compute_blast_radius`, before any output flag was consulted. No option could have returned
+    the full list.
+  - A cap is now a **rendering** parameter (`list_limit`) and never a measurement one — every
+    `stats.*_count` is taken over the full population either way (ADR-0008 R5-R8). `--output`
+    renders unbounded; stdout keeps the sample and names the total; and the note only claims a
+    cap that actually bit, with the I-8 `display_list` effect block beside it.
+  - The output budget is skipped for a file as well. `--agent` and `--compact` already did this;
+    `impact` was the one that did not.
+  - Same rule for `impact-chain`, with one qualification: an **explicit `--limit` still wins**.
+    A default is not a request; a typed flag is (`_flag_was_given`, off Click's parameter source).
+  - The USER_GUIDE now states the rule where a reader meets it, beside the `impact` output.
+
+## [3.5.0] — 2026-07-31
+
+**M7.7 "Robustness floor" — the axis field evaluation #5 scored 4/10.** Ten pieces, and the
+pattern in eight of them is the same: the reported symptom was real, and the measured cause was
+not the one anyone had assumed. Input admission had four behaviours for one fact, not one broken
+command. `posture`'s cost was not the Java parse but a quadratic scan of two branches that could
+not fire — and that dead code was also a false zero on the security axis. The blast radius
+disagreed with itself because there were two traversals of the reverse graph, not because reach
+is hard. Two reported symptoms did not reproduce at all and are recorded as measured rather than
+fixed blind.
+
+**Minor, not patch**, on two counts: `impact` now publishes endpoints, transaction boundaries and
+a security surface where it published `0`, so its risk score moves and a pipeline gating on it can
+change colour; and `estimated_effort_days` is nullable where a range applies.
+
+### Changed
+
+- **`retrieve` moves from `experimental` to `parked`** (C3-24) — kept working, no longer
+  developed, and saying so: `[PARKED]` in its own help, in the README table and in the user
+  guide, all rendered from `cli.COMMAND_TIERS`. The battery now also asserts that a parked
+  command declares itself, the twin of the assertion that already existed for experimental.
+  **Two of the three reported symptoms did not reproduce**, and are recorded that way rather
+  than repeated: `transaction-propagation` returns one entity because the battery repository
+  has exactly one non-default boundary (`REQUIRES_NEW: 1` of 161) — `observations.total` is the
+  tx-index population standing beside the answer, not a truncated total, and a `--limit` exists
+  (default unbounded) that records `entities_truncated` when it bites; `security-surface`
+  returns 0 where `spring-audit --scope security` also returns 0. What does reproduce is an
+  `explanation` block shaped for a ranking that never ran. The surface is not non-functional —
+  it is undifferentiated, re-stating behind 15+ intents what the core commands answer better.
+
+### Measured
+
+- **`review-pr`'s path argument is not decorative — the reported scope defect does not
+  reproduce** (C3-27, scope half). Field evaluation #5 reported that given a submodule path the
+  command reports the *enclosing* repository as `repo_root` and reviews 227 files from other
+  modules. Re-measured on six shapes: a module subdirectory, that same subdirectory as the
+  working directory, a nested path given relative to the root, an embedded repository, a **real
+  git submodule** (where `.git` is a gitlink *file*, so an `exists()` test is true for it and the
+  walk up has to stop there), and a submodule asked for a ref only its parent has. Every run is
+  bounded to the path it was given: on BroadleafCommerce the scoped runs return exactly
+  `git diff --name-only <ref> -- <scope>` — 5 of 17 files at `core/`, 855 at
+  `core/broadleaf-framework/`, 1 222 at `core/` over a 3 332-file range — `_meta.scope` names the
+  tree answered about, no sibling-module path appears anywhere in the payload, and the
+  missing-ref case is refused (`git_ref_not_found`, exit 1) instead of borrowed from the parent.
+  Recorded as not reproducing rather than fixed blind, and the six shapes are now asserted in
+  `tests/test_git_scope_namespace.py` so the symptom cannot return silently. The probable closer
+  is the Bug A scope-namespace seam, which landed between the evaluated build and this
+  measurement.
+
+### Fixed
+
+- **`impact` reported `endpoints_affected_count: 0` for a symbol `impact-chain` reached 21
+  endpoints from** (C1-16, endpoint half — the caller half closed in 3.5.0). A false zero on the
+  blast-radius axis, which is the number a user takes a risk decision with. The cause was
+  measured, not guessed: there were **two traversals** of the reverse graph, and they disagreed
+  twice.
+  - `impact` looked up the exact reverse-graph key. The callers of a class are stored under its
+    **method** keys (`Foo#doWork`), never under `Foo`, so the walk terminated at every
+    class-level node — which is exactly what a DI `injects` edge normalises to. 125 indirect
+    callers instead of 1 442.
+  - It admitted `implements`/`extends` as caller edges (an implementor does not call an
+    interface by implementing it, CH-006) under a comment claiming its edge set was *"consistent
+    with `spring_impact._SKIP_EDGE_TYPES`"*, which skips both. And it held no interface index, so
+    it never crossed the DI boundary at all: on `Money` it reached 200 classes and **zero
+    controllers**, against 441 and 18.
+  - New authority `sourcecode/caller_reach.py`, registered as fact `blast_radius_reach`, with
+    `impact`, `impact-chain` and `migrate-check --blast-radius` all bound to it. On
+    BroadleafCommerce's `Money`, `impact` now reports **20 of the 21 endpoints** (0 before),
+    **53 transactional boundaries** (0), **20 persistence paths** (2) and **15 security-gated
+    endpoints** (0) — while `stats.direct_caller_count` stays **134**, so the caller axis closed
+    in 3.5.0 does not move. Parity verified command-to-command on spring-petclinic
+    (`OwnerRepository`: 13 = 13 endpoints, exact) and open-banking-gateway (two symbols, exact):
+    the reconciliation adds no false positives. Cost unchanged (5.0 s vs 4.9 s on that repo).
+  - Also fixed here: the explanation prose read *"433 direct callers"* beside a payload
+    publishing 134 caller classes and 433 reference sites, each named for its unit. Prose is
+    what a reader quotes, so it now names its unit too.
+  - **Residual, stated because it is measured:** one endpoint of the 21
+    (`BroadleafOauthRegisterController#processRegister`) is still reached by `impact-chain` and
+    not by `impact`, because the two commands read *different graphs* — `impact` builds the repo
+    IR, `impact-chain` the CIR, and the CIR carries a method key for that handler the repo IR
+    does not. That is a graph-population gap, not a traversal one. Seed expansion is asymmetric
+    for the same reason (`impact-chain` expands a seed to its subtypes, `impact` only to the
+    interfaces it implements).
+
+- **`posture` costs a sixth of what it did, and a warm is finally worth something to it**
+  (C3-25) — 24.5 s → **10.1 s** cold and 19.3 s → **1.6 s** after `cache warm`, measured on
+  BroadleafCommerce in isolation. Field evaluation #5 measured 195 s, ×18 the session median,
+  on the one command the product differentiates on, and the cache model honestly documented
+  that a warm bought it almost nothing. Both had the same cause, and it was not the Java parse
+  everyone blamed:
+  - **The security predicate re-walked every node in the repository for every class** —
+    6 075 × ~29 000 ≈ 176 M dictionary reads on the battery repository, larger than the parse
+    itself — looking for `node["return_type"]` and `node["supertypes"]`. **The IR publishes
+    neither key on a node.** Inheritance and return types are `extends`, `implements` and
+    `returns` *edges*, so both branches were structurally dead in every release: a repository
+    that wires its chain with a `@Bean SecurityFilterChain` or a filter subclass and no
+    `@EnableWebSecurity` was reported as configuring no security at all — a **false zero on the
+    axis this command exists for**. The predicate now reads the edges, once per IR. On
+    BroadleafCommerce it recovers 6 request-chain configurations, verified 6/6 against source
+    with no false positive, one of which is `@ConditionalOnProperty` and now correctly qualifies
+    the endpoint claim as unresolved instead of silently strengthening it.
+  - **`posture` built its own CIR on every run** — the same parse `cache warm`, `explain` and
+    `impact-chain` already share. It now goes through the shared knowledge cache, poison-safe by
+    the `peek_cir` rule: the knowledge key is repo-wide and carries no scope, so a run bounded to
+    a subdirectory neither reads nor writes it and keeps its own unshared build.
+  - **`--diff` parsed the repository once per side.** The IR does not depend on which profiles
+    are asked about — only the resolution over it does — so the second side now costs the
+    resolution alone: 2.3 s warm for a two-set comparison, the shape a per-PR gate runs.
+
+- **A degraded run now states the effect of the degradation** — invariant **I-8**, accepted and
+  enforced (C3-27, and the class field evaluation #5 named). `review-pr` published
+  `analysis_limiter: {"missing_signals": ["dependency_graph", "import_graph"]}`: what was
+  absent, and nothing about what its absence changed. A reader could not tell whether the answer
+  was a floor, a ceiling or unaffected — the same defect shape as `statically_unreferenced: 0`,
+  one level up.
+  - Every signal a command can report as missing now carries **what it feeds**, **what the
+    answer does without it**, and a **`direction`**: `under_reports` (read the answer as a
+    floor — absence of a finding is not evidence of none), `over_reports` (a ceiling), or
+    `undetermined`. Mixed directions collapse to `undetermined`: an answer that is a floor in
+    one place and a ceiling in another is neither. The block ends with one sentence on how to
+    read the result, and the GitHub comment prints it beside the `OMITTED` badge — a reviewer
+    reads the comment, not the JSON.
+  - One authority (`sourcecode/degradation.py`) serves every emitter, and the battery discovers
+    signal names **from the source by AST**, so a signal added without an effect statement fails
+    the suite. That scan found a second emitter the field never reached: **`archetype`** declares
+    `repo_ir_subsystem_masses` and `semantic_ir_spi_fanin` missing on *every* run — signals wired
+    into no release — and its missing `endpoints` signal enters the score as `0.0` rather than as
+    unknown, so an HTTP-facing repository is scored as if it exposed no HTTP surface. Both now
+    say so in the payload; correcting the score itself is separate work.
+  - **The second family is now covered too: what the product cuts on purpose.** A missing signal
+    is something the run did not have; a **cap** is something it had and chose not to publish.
+    Those said only *that* they capped — `"_truncation_summary": {"total_omitted_items": 1442}`,
+    `"bfs_truncation_reason": "hub_class_depth_cap"`, `"is_stale": true` — and a count of omitted
+    items is not an effect. `CAP_EFFECTS` gives each one the same three fields plus a fourth,
+    `exact`, which is what separates a cap from a missing signal: what survived the cut.
+    - **The output budget** publishes the least intuitive effect of all: *nothing moved*. Every
+      figure is computed before serialisation, so the counts stay exact and only the lists became
+      samples — and deriving a count from a truncated list is exactly how the field arrived at
+      four contradictory fan-in figures. The block now says so, and the battery asserts a trimmed
+      payload keeps its count.
+    - **Display caps** (`impact-chain --limit`, `impact`'s 30-class sample, `retrieve --limit`)
+      state that the total beside the list was computed over the whole population, so list and
+      total disagreeing is construction, not contradiction.
+    - **The hub-class depth cap** names every figure it turns into a floor — indirect callers and
+      the endpoints, transaction boundaries, security surface and risk score derived from them —
+      and every figure it leaves exact. A zero under a cap means the capped walk found none.
+    - **A stale snapshot** is `undetermined`, not a floor: it describes a different tree, so a
+      symbol added since is missing *and* a symbol deleted since is still listed.
+    - **An unavailable section** (`migrate-check --blast-radius` when the IR cannot be built)
+      says the failure is bounded to that block and the findings beside it are untouched.
+    - Same enforcement as the signal family: the battery discovers cap names from the source by
+      AST, so a cap applied without an effect statement fails the suite.
+
+- **A run that succeeded now writes nothing to stderr** (C3-26). PowerShell 5.1 — a declared
+  target platform — turns any stderr write from a native command into a `NativeCommandError`,
+  so an informational line makes a successful run look like a failed one and forces the caller
+  to swallow errors it should be reporting. Measured non-TTY before fixing: `migrate-check`
+  wrote a size advisory, `validation` a note about an empty result, `explain` a cache hit/miss
+  line; everything else was already clean. Those three now go through one seam (`cli._notice`)
+  that speaks only when stderr is a terminal. No `--quiet` flag: a flag has to be remembered by
+  every caller, on the platform where forgetting it is fatal.
+  - **`cache warm` and `cache clear` print their status on stdout**, where `cache status` in the
+    same group already printed it. Their status *is* their answer — on stderr, `ask cache warm >
+    log.txt` captured nothing at all.
+  - Errors keep stderr, where they pair with a non-zero exit; `tests/test_stderr_purity_matrix.py`
+    asserts both halves across 13 commands through a real subprocess, because a CliRunner blurs
+    the two streams — which is how three of these survived the stdout-purity battery that
+    already existed.
+
+- **Every example the CLI prints now parses against the CLI that prints it** (C3-16). The root
+  help led its gating panel with `pr-impact . --since main`; `pr-impact` has no `--since`. It
+  was reported by three field evaluations and survived all three, because the check was a
+  person re-reading a hand-written block — and the header panels print invocations *without*
+  the `ask ` prefix, so even grepping for `ask ` missed it. The example is now
+  `pr-impact . --files -` (the stdin form, verified against a real `git diff --name-only`), and
+  `tests/test_help_examples.py` extracts all 156 invocations from every help screen — root
+  panels, command docstrings, group and subcommand help — and parses each one against the
+  command it names. The battery states its own scope: the command and its options exist and
+  take the arity given; values are not validated and nothing is executed.
+
+- **One class, four fan-in figures — two of them wrong about their own unit** (C1-16, field
+  evaluation #5). On `org.broadleafcommerce.common.money.Money` the product published 1 868,
+  673, 418 and 151 under names that all read as fan-in, and the note written to pre-empt that
+  confusion promised an ordering (`modernize.in_degree` *"always the largest"*, the other two
+  within *"a small margin"*) that measurement falsified by 2,8× and 177 %. This is the number
+  a risk decision is taken with: *"¿el blast radius son 484 o 611 clases?"*
+  - **`impact.stats.direct_caller_count` counted caller *symbols*** — 418, of which 346 were
+    method-level, so a class was counted once per method touching the target. It now counts
+    **distinct classes** (134) with the reference sites beside it as
+    **`direct_caller_symbol_count`** (418). The risk score still weighs reference sites; it was
+    the published unit that was false. `direct_callers` is a class list (`direct_caller_symbols`
+    keeps the sites), so the array and its count are finally the same unit.
+  - **`explain.incoming_callers` deduplicated by simple name**, collapsing 186 distinct classes
+    into 151 and dropping 35 real dependents. Identity is the FQN; a colliding simple name is
+    rendered qualified. New **`incoming_callers_count`** is measured before the `--limit` cap,
+    so a consumer never has to take `len()` of a truncated array.
+  - **`impact-chain.metadata.callers_total` was the size of the whole chain**, not fan-in, and
+    was absent from the note. It stays (removing a published key is breaking) and now says so,
+    beside **`chain_classes_total`** (441) and **`direct_caller_count`** (134) — which equals
+    `impact`'s figure by construction. `explain` is a declared superset: it admits import-only
+    references, a blast radius does not.
+  - **The note is generated from a registry** (`caller_metrics.FAN_IN_FIGURES`), each figure
+    carrying its unit and the references it admits, and the battery asserts every figure appears
+    with its unit. No ordering between units is promised any more — the three falsified phrases
+    are banned by test. Registered as fact `caller_fan_in` (ADR-0008 R11-R14).
+  - `compare`'s evidence trail read `len()` of the 30-item display array and told every hub
+    class in the repository it had "30 direct callers". It reads `stats` now.
+  - Still open and stated rather than guessed: `impact` reports `endpoints_affected_count: 0`
+    where `impact-chain` returns 21 endpoints for the same class. Measured today, the two
+    traversals reach different populations (259 vs 441 classes at full depth), so that half is
+    engine reach, not presentation.
+
+- **A command must not answer a question about a repository it could not read** (C3-22, C3-23,
+  the robustness finding of field evaluation #5 — *"un gate que puede pasar sin analizar nada
+  es peor que no tener gate, porque genera confianza injustificada"*). The same nonexistent
+  path produced four different behaviours: six commands refused it correctly, `verify`
+  answered `{"verdict": "pass", "exit_code": 0}`, `posture` answered an all-zeros payload with
+  exit 0, `archetype` raised a `FileNotFoundError` traceback through the JSON-always contract,
+  and `cold-start` reported `no_ris`. In `ask verify $DIR --fail-on new`, one typo in the
+  variable was a permanently green pipeline.
+  - **One admission authority** (`sourcecode.path_admission`): "can this path be analysed?" is
+    one fact, so **25 path-taking commands** now derive it in one place instead of twenty
+    inline copies plus four omissions. The refusal carries a machine-readable **`reason`** —
+    `missing`, `not_a_directory`, or `unreadable`.
+  - **`unreadable` is new and was not in the field report.** A directory that exists but cannot
+    be listed produced the same `archetype` traceback; it is now refused before the scan starts.
+  - **`verify` and `verify-edit` refuse with exit 2, not 1.** Their published contract reserves
+    2 for *unverified* — the run that could not look — as distinct from 1, the run that looked
+    and found violations. A gate that never analysed anything reports neither `pass` nor a
+    violation count.
+  - **`impact-chain` and `impact` name the repository they actually read.** A path in the
+    symbol slot made them report `not_found` about the current working directory. A file path
+    is still a legitimate symbol; a symbol that *is* a directory, or that carries a path
+    separator and does not exist, now says which repository was analysed and how the arguments
+    are ordered.
+  - The battery discovers path-taking commands from the CLI itself: a new command that skips
+    the gate fails the suite.
+
+- **An effort figure is a point only when nothing under it is a range** (C1-12, the third
+  reconciliation gate of field evaluation #4). `migrate-check` folded the Hibernate 5→6 slice
+  into the headline as the **midpoint** of a range the same report labels `confidence: low`,
+  and that the Hibernate effort model itself calls a non-deduplicated *upper bound*. Measured
+  on the battery: BroadleafCommerce billed **157.7 d, 153.7 of them (97%) from 76.5–230.8**;
+  openmrs-core 76.4 d with 62.2 (81%) from 28.9–95.6. The arithmetic was right and the claim
+  was still false — a 3× span presented as one number.
+  - New top-level **`estimated_effort_range_days`** `{low, high, confidence, basis}`. The band
+    is the worst confidence of the contributing slices; findings effort is a per-file
+    measurement and enters as a point.
+  - **`estimated_effort_days` is `null`** when a range slice is in the total (never `0` — that
+    reads as "no work"), and stays a number on every repo where no range applies. The text
+    report prints the span: `Estimated effort: 80.6–234.9d (low confidence — not a point
+    estimate)`.
+  - `effort_breakdown.hibernate_rewrite_effort_days` is `null`: the midpoint is not a
+    measurement of anything, so it is no longer published. The range sits beside it in
+    `hibernate_rewrite_range`, with `hibernate_rewrite_effort_basis` and `unestimated_slices`.
+  - **An inferred version buys no number.** When the 5→6 axis applies only because a Spring
+    Boot 2 BOM manages Hibernate 5.x — no version declared in the build — the rewrite *scope*
+    is a hypothesis: the slice contributes neither a point nor a range, and the gap is named.
+    The readiness dimension stays applicable; not estimating is not pretending it is absent.
+  - Readiness snapshots/trends carry `estimated_effort_low_days` / `estimated_effort_high_days`
+    so the series does not go blind exactly where the effort is largest.
 
 ## [3.4.0] — 2026-07-29
 

{sourcecode-3.4.0 → sourcecode-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 3.4.0
+Version: 3.6.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
@@ -220,8 +220,8 @@ experimental: both are true, and they are two different facts.
 |---|---|---|
 | **core** | contract stable within a major — safe to gate CI on | `endpoints` · `spring-audit` · `migrate-check` · `impact` · `impact-chain` · `pr-impact` · `verify` |
 | **supported** | maintained; fields are added, never removed without a major | every command not named in another row |
-| **experimental** | shape may change in a minor — do not gate CI on it | `posture` · `archetype` · `retrieve` |
-| **parked** | kept working, no longer developed | none today |
+| **experimental** | shape may change in a minor — do not gate CI on it | `posture` · `archetype` |
+| **parked** | kept working, no longer developed | `retrieve` |
 
 The same table is printed by `ask --help`, and both are generated from one authority
 (`cli.COMMAND_TIERS`) — the battery fails if a command is in no tier, or if this file drifts
@@ -252,7 +252,7 @@ from it.
 | `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 | trend reporting, not gating |
-| `retrieve` | experimental | typed knowledge queries over the model | |
+| `retrieve` | parked | typed knowledge queries over the model | |
 | `archetype` | experimental | evidence-based architectural archetype | |
 | `rename-class` / `chunk-file` | supported | word-boundary Java rename; split a large file for an agent | |
 | `cache status\|warm\|model\|clear` · `auth` · `telemetry` · `mcp` · `config` · `version` | supported | housekeeping | `activate` too |

{sourcecode-3.4.0 → sourcecode-3.6.0}/README.md

@@ -182,8 +182,8 @@ experimental: both are true, and they are two different facts.
 |---|---|---|
 | **core** | contract stable within a major — safe to gate CI on | `endpoints` · `spring-audit` · `migrate-check` · `impact` · `impact-chain` · `pr-impact` · `verify` |
 | **supported** | maintained; fields are added, never removed without a major | every command not named in another row |
-| **experimental** | shape may change in a minor — do not gate CI on it | `posture` · `archetype` · `retrieve` |
-| **parked** | kept working, no longer developed | none today |
+| **experimental** | shape may change in a minor — do not gate CI on it | `posture` · `archetype` |
+| **parked** | kept working, no longer developed | `retrieve` |
 
 The same table is printed by `ask --help`, and both are generated from one authority
 (`cli.COMMAND_TIERS`) — the battery fails if a command is in no tier, or if this file drifts
@@ -214,7 +214,7 @@ from it.
 | `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 | trend reporting, not gating |
-| `retrieve` | experimental | typed knowledge queries over the model | |
+| `retrieve` | parked | typed knowledge queries over the model | |
 | `archetype` | experimental | evidence-based architectural archetype | |
 | `rename-class` / `chunk-file` | supported | word-boundary Java rename; split a large file for an agent | |
 | `cache status\|warm\|model\|clear` · `auth` · `telemetry` · `mcp` · `config` · `version` | supported | housekeeping | `activate` too |

{sourcecode-3.4.0 → sourcecode-3.6.0}/pyproject.toml

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

{sourcecode-3.4.0 → sourcecode-3.6.0}/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.4.0"
+__version__ = "3.6.0"

{sourcecode-3.4.0 → sourcecode-3.6.0}/src/sourcecode/archetype.py

@@ -30,6 +30,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Optional
 
+from sourcecode.degradation import analysis_limiter as _analysis_limiter
 from sourcecode.graph_evidence import GraphEvidence, GraphEvidenceProvider, GraphEvidenceResult
 from sourcecode.schema import SourceMap
 from sourcecode.tree_utils import flatten_file_tree
@@ -157,6 +158,9 @@ class ArchetypeAnalysis:
             },
             "signals_used": self.signals_used,
             "signals_missing": self.signals_missing,
+            # I-8: the names alone say nothing about what the classification lost.
+            # Same authority the review-pr limiter uses, so both read alike.
+            "analysis_limiter": _analysis_limiter(self.signals_missing),
             "generated_from": self.generated_from,
             "graph_metrics": {k: round(v, 4) for k, v in self.graph_metrics.items()},
         }

{sourcecode-3.4.0 → sourcecode-3.6.0}/src/sourcecode/cache_model.py

@@ -125,10 +125,11 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "`--env-map`, `--depth N` and `--exclude` change the *analysis*, so they miss the "
                  "warmed core and rescan — this is the 171 s the field measured after a 103 s warm.",
                  "--compact 17.7 s → 0.3 s; --agent --full --env-map --depth 20 34.7 s → 33.9 s (no gain)"),
-    CommandCache("posture", ("parse",), "shared", False,
-                 "Resolves the conditional bean graph on every run; a warm saves it the Java parse, "
-                 "which is the smaller half of its work.",
-                 "24.5 s → 19.3 s"),
+    CommandCache("posture", ("cir", "parse"), "shared", False,
+                 "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.",
+                 "10.1 s → 1.6 s"),
     CommandCache("endpoints", ("ris", "parse"), "none", False,
                  "Recomputes the endpoint surface on every run and refreshes the RIS endpoint index. "
                  "Measured: a warm buys it nothing.",