sourcecode 3.3.0__tar.gz → 3.5.0__tar.gz

{sourcecode-3.3.0 → sourcecode-3.5.0}/CHANGELOG.md

@@ -1,6 +1,358 @@
 # Changelog
 
-## [Unreleased]
+## [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
+
+**Two of the five reconciliation gates, and one commercial surface that answered five ways.**
+The theme of field evaluation #4 was not missing analysis: it was analysis the product had
+already done and did not consult — a migration estimate that ignored its own
+`auto_fix_available`, and a gate that reported `pass` for a file it never looked at.
+
+**A minor, not a patch, and for one reason: `verify-edit` can now exit 2 where it exited 0.**
+No API changed, but a build-configuration-only edit stops being a green light, so an installed
+hook or a pipeline that gates on the exit code will start blocking on it. A patch release must
+never be able to turn a green pipeline red.
+
+**Upgrade notes.**
+
+- `verify-edit`: a change to `pom.xml`, `build.gradle`, `application*.yml`, `web.xml` or a
+  container descriptor now yields `unverified` (exit 2). `git commit --no-verify` and
+  `ask verify-edit --no-ci` are the escape hatches.
+- `migrate-check`: published effort numbers **move down** — the same work, split by what it
+  actually is. Measured: openmrs-core 122.1 → 76.4 d, BroadleafCommerce 163.3 → 157.7,
+  alfresco 22.8 → 5.2. `blocking_count` and `readiness_score` are unchanged.
+- `auth status`: new authoritative fields; `pro`, `pro_effective`, `pro_gating` and `pro_reason`
+  still ship, now derived from the authority and listed in `deprecated_fields`.
+
+### Fixed
+
+- **`verify-edit` sees the files that decide what the code compiles to** (C3-14, the second
+  reconciliation gate). Editing a `pom.xml` produced `changed_files: []`, `verdict: pass`,
+  `exit_code: 0` — and `blast_radius: {"confidence": "high", "note": "no changed files"}`.
+  git reported the file; the gate did not look at it, then said everything was fine about a
+  change that moves every source file in the repository at once.
+  - New blocking axis **`build_config_changed`**, and a new `changed_build_files` list beside
+    `changed_files`. It names what moved: `effective_compiler_release` (from → to) and
+    `dependency_delta` per coordinate.
+  - **The verdict is `unverified`, not `break`.** A build edit is neither a proven regression
+    nor computed-clean, which is exactly what `changed: null` has always meant here — so it
+    flows through the existing "could not compute" path and exits 2. No special case.
+  - Admission is by file name and deliberately narrow — `pom.xml`, `build.gradle`,
+    `settings.gradle`, `gradle.properties`, `application*.yml|properties`, `bootstrap*`,
+    `web.xml`, `weblogic*.xml`, `jboss-*.xml`, `*-context.xml`, `persistence.xml`, `beans.xml`.
+    `messages.properties` and `logback.xml` are out: every admitted file degrades a verdict, and
+    a loose rule turns the gate into noise people learn to ignore.
+  - `blast_radius` stops reporting `confidence: "high"` over a change whose reach it has not
+    measured.
+  - **Upgrade note (behaviour change):** a build-configuration-only edit now exits **2**
+    (unverified) where it exited 0 (pass). An installed pre-commit/pre-push hook will block on
+    such an edit; `git commit --no-verify` remains the escape hatch, and `--no-ci` still reports
+    without gating.
+
+### Changed
+
+- **The migration estimate reads the report's own `auto_fix_available`** (C1-11, the first of
+  the five reconciliation gates from field evaluation #4). `migrate-check` shipped an
+  OpenRewrite recipe for most findings and then billed every one of them at the hand-edit rate.
+  Reproduced on the battery before fixing: **openmrs-core carries a recipe for 296 of 310
+  findings and costed all 310 as hand work**, for a headline of 122.1 person-days.
+  - `effort_breakdown` splits the same total into **`manual_days`** + **`mechanical_days`** +
+    `hibernate_rewrite_effort_days`. The partition is **by file**, because the severity weights
+    are per file: a file is mechanical only when *every* finding in it has a recipe, and one
+    unautomatable finding costs the whole file manually — a human is in that file either way.
+  - **The review factor is published, not buried.** `mechanical_review_factor` (0.2) carries
+    `mechanical_review_factor_basis: "assumption, not a measurement"`, so a team can substitute
+    their own number instead of inheriting ours silently. `recipes[]` lists what would run and
+    `mechanical_basis` states both denominators.
+  - **`validation_days` is `null` with a note, never `0`** — the re-test scope is a different
+    measurement (`migrate-check --blast-radius`), and `0` would read as "no re-testing needed"
+    (invariant I-3).
+  - **Published numbers move.** Measured: openmrs-core 122.1 → **76.4 d**, BroadleafCommerce
+    163.3 → **157.7 d**, alfresco 22.8 → **5.2 d**. `blocking_count` and `readiness_score` are
+    unchanged in all three — the split changes what the work is called, never what blocks.
+
+- **`ask auth status` answers one question instead of five** (P-2). It used to publish
+  `{"status": "unauthenticated", "pro": true, "pro_reason": "early-adoption unlock"}` — every
+  field true on its own axis, and together unreadable: a buyer could not tell what they have,
+  why they have it, or what changes when it ends.
+  - One authority, `license.entitlement()`, now answers it: **`entitlement`** (`pro`/`free` —
+    what runs today), **`source`** (why: `license_key`, `early_adoption_unlock`, `free_tier`),
+    **`authenticated`** (whether a credential exists here — a *separate* fact, since today one
+    can be entitled without one), **`paywall_active`**, **`when_it_changes`** (what you lose
+    when that source stops applying) and **`free_repo_java_file_limit`** (the number the gate
+    actually compares against).
+  - `when_it_changes` states the gate in the terms the gate uses and **never quotes a price** —
+    pricing lives in `docs/PRODUCT_TIERS.md`, and a number printed here would be stale the day
+    it moves. Asserted.
+  - **`is_pro` is derived from the same authority.** It is what every gate reads
+    (`can_use`, `require_feature`), and it used to be computed beside the status block rather
+    than from it — which is how a status page came to contradict the commands next to it.
+  - `pro`, `pro_effective`, `pro_gating` and `pro_reason` are still emitted for existing
+    consumers, are derived from the authority (so they cannot drift), and are listed in the new
+    `deprecated_fields`. They are removed in a future major.
+  - `plan_status` no longer reports `unknown` for a licence file with no explicit status while
+    the authority reads that same file as active.
 
 ## [3.3.0] — 2026-07-29
 

{sourcecode-3.3.0 → sourcecode-3.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 3.3.0
+Version: 3.5.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 |
@@ -283,10 +283,13 @@ Honest limits worth knowing before you rely on it:
 > 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`,
+> **What that means concretely.** Ask the product: `ask auth status` answers in one block —
+> `entitlement` (what runs today), `source` (*why* — a licence, the unlock, or the free tier),
+> `authenticated` (whether a credential exists, which is a separate fact) and
+> `when_it_changes` (what you lose when that source stops applying). A fresh install reads
+> `entitlement: pro`, `source: early_adoption_unlock`, `authenticated: false` — unauthenticated
+> *and* entitled, stated as two facts instead of one contradiction. 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.
 

{sourcecode-3.3.0 → sourcecode-3.5.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 |
@@ -245,10 +245,13 @@ Honest limits worth knowing before you rely on it:
 > 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`,
+> **What that means concretely.** Ask the product: `ask auth status` answers in one block —
+> `entitlement` (what runs today), `source` (*why* — a licence, the unlock, or the free tier),
+> `authenticated` (whether a credential exists, which is a separate fact) and
+> `when_it_changes` (what you lose when that source stops applying). A fresh install reads
+> `entitlement: pro`, `source: early_adoption_unlock`, `authenticated: false` — unauthenticated
+> *and* entitled, stated as two facts instead of one contradiction. 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.
 

{sourcecode-3.3.0 → sourcecode-3.5.0}/pyproject.toml

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

{sourcecode-3.3.0 → sourcecode-3.5.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.3.0"
+__version__ = "3.5.0"

{sourcecode-3.3.0 → sourcecode-3.5.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.3.0 → sourcecode-3.5.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.",