sourcecode 3.6.0__tar.gz → 3.8.0__tar.gz

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

@@ -1,5 +1,457 @@
 # Changelog
 
+## [Unreleased]
+
+## [3.8.0] — 2026-08-02
+
+### Added
+
+- **The security surface publishes what it does not answer** (CL-2, CL-7, and the framing half
+  of CL-5). A report that lists what it found and says nothing about what it never looks at
+  invites silence to be read as absence — and the audit that raised this found a credential
+  versioned in three deployment descriptors *by hand*, because nothing here reads outside Java
+  and Spring configuration.
+  - One authority, `sourcecode/non_coverage.py`, read by three surfaces: the `non_coverage`
+    block in the `spring-audit` payload, the command's own `--help`, and the README section —
+    all rendered from the same table, because a curated list beside a generated one is how
+    `endpoints` went missing from every help list.
+  - Four rows for the security surface: no dataflow or taint (NC-001), no secrets outside Java
+    and Spring configuration (NC-002), filter-chain order not reconstructed (NC-003), no CVE
+    matching (NC-004). Each states why it is out of scope rather than unimplemented, and what
+    does answer it. Two more state the migration boundary (NC-005, OpenRewrite takes the
+    recipes this publishes) and the environment boundary (NC-006, answered as far as a
+    repository can by `posture --resolve-environments`).
+  - The evaluator's argument for publishing it is commercial, not ethical: *"un producto que
+    publica sus límites no se compara por amplitud; se compara por profundidad, que es donde
+    gana."*
+
+### Changed
+
+- **Two claims corrected with measured figures.** `--compact` is documented as the smallest
+  answer, **not the cheapest run** — 13.3 s cold on BroadleafCommerce against `spring-audit`
+  3.6 s and `posture` 1.9 s, 0.3 s warm — with the reason to warm before a session stated where
+  the claim is made (CL-3). And the product is positioned as the **diagnosis layer** until an
+  executor ships, in the field's own numbers (7/10 as a report generator, 5.5/10 as a
+  development tool) rather than argued with (CL-5).
+
+- **`ask trend` is a top-level command, and capture is automatable** (P-4). The *series* is the
+  asset — a repository that captured a baseline at each release has a history nobody can
+  reconstruct afterwards, and one that did not never will — so reading it is no longer two words
+  deep, and [`docs/baseline-ci.yml`](docs/baseline-ci.yml) captures one per tag and publishes the
+  trend as a build artifact. `ask baseline trend` is the same command.
+  - The read-only half was a **documentation** gap and is closed where the auditor meets it:
+    `--dir` already existed, and the default now says *why* it is inside the repository (the
+    history travels with the code, not with a vendor) and that an audit which must leave the tree
+    untouched writes elsewhere. README and the user guide say the same.
+  - ⚠Adding the command surfaced the **C4-1 shape a sixth time**: `ask trend` was registered,
+    working and documented, and the CLI answered *"'trend' does not exist"* — because the
+    dispatcher matched against a **hand-written set of subcommand names**. It is derived from the
+    registry now, and the battery asserts every registered command is dispatchable.
+
+- **`ask posture --resolve-environments` — which profile set actually runs, and the worst one
+  that could** (CL-8 / M9.5). `posture --diff` was called the strongest thing this product does
+  and it stopped at the repository boundary: which profile set runs is decided by the
+  deployment, so the answer was conditional and a field evaluator closed the last hops by hand
+  with `grep` (build profile → the property the build filters → a placeholder present in no
+  config file → no `context-param` in any descriptor → therefore nothing decides it).
+  - Those hops are now mechanical. Every artefact that can set `spring.profiles.active` is read
+    — config files, Maven/Gradle properties, `web.xml` context parameters, `Dockerfile` `ENV`
+    and `-D` arguments, Compose and Kubernetes manifests, launch scripts — each publishing what
+    it says with `file:line`. The verdict is `decided_in_repository`, `artefacts_disagree` (two
+    deployments, never a contradiction to resolve by picking one), or **`NOT DECIDED IN THIS
+    REPOSITORY`**.
+  - Every admissible profile set is then resolved over one parse and ranked by what it leaves
+    open, so the payload names the worst case and, where the repository does decide, how far the
+    shipped set is from it: *"one environment variable away from dev"*.
+  - **`open_by_rule` and `access_not_decided` are counted separately.** A readable rule that
+    permits a request unauthenticated is not the same fact as no readable rule matching it, and
+    folding them together would publish the confident security falsehood this command exists to
+    prevent. The reading says which is which.
+  - A value found in the repository is published as a default, never a guarantee:
+    `SPRING_PROFILES_ACTIVE` in the process environment outranks every artefact, and this
+    analysis cannot see the process environment.
+
+- **`ask verify --init` derives the contracts a repository already satisfies** (C3-30). The gate
+  had no way to acquire what it gates on: nobody hand-writes contracts for a 3 300-file
+  monolith, so the honest gate (zero contracts is `unverified`, closed as C3-15) stayed empty —
+  and the gate is the recurring half of the value story, where an audit is bought once.
+  - Three shapes, each written with the measurement behind it: a path prefix whose endpoints all
+    carry the same policy today (`require_endpoint_security`), an audit pattern that fires
+    nowhere (`forbid_finding`), and an injection edge between two annotated populations that
+    does not occur, both populations large enough that the absence is a pattern rather than an
+    accident (`forbidden_edge`).
+  - **Every rule is executed before it is written.** The derived set runs through the same engine
+    `verify` runs, and anything that fails on the tree it came from is dropped and reported —
+    `verify --init` followed by `verify` passes by construction, asserted as a round trip in the
+    battery, together with the proof that the populated gate goes red when the invariant breaks.
+  - Violations that exist today are deliberately not proposed: that is debt for
+    `--capture-baseline`, a different claim from an invariant, and the payload says so per
+    rejected candidate.
+  - `--dry-run` prints without writing; an existing contracts file is never replaced without
+    `--force`.
+
+- **`delta` and `contract-diff` take git refs** (C3-33). Both compared two *checkouts* while
+  `review-pr` in the same CLI already took `--since`, so comparing two commits meant
+  orchestrating worktrees first. In the evaluation that recorded this, that cost coverage rather
+  than convenience: the evaluator ran the full catalogue against a client monolith under a
+  promise to leave the environment byte-identical and **omitted both commands** rather than
+  create worktrees in someone else's repository.
+  - `ask delta --base-ref origin/main --head-ref HEAD [--repo <path>]`, same for
+    `contract-diff`. Two checkouts positionally still work, and the payload publishes a
+    `comparison` block saying which basis it used — with both refs and their resolved commits.
+  - **Reading a ref writes nothing to the repository.** `git archive` streams the tree into a
+    temporary directory that is removed on the way out: no `git worktree add` (which registers
+    administrative state under `.git/worktrees` and leaves it behind if the process dies), no
+    checkout, no stash, no index read. The battery asserts `git status` and `git worktree list`
+    are identical before and after.
+  - A ref this repository does not have is refused by name (`git_ref_not_found`, exit 1) and
+    never substituted with something nearby.
+
+### Fixed
+
+- **`retrieve` stopped publishing scores nothing computed** (C3-19, **`entities[].score` and
+  `explanation.score` are nullable**). `retrieve blast-radius` returned eighty dependents each
+  carrying `"score": 0.0`, beside an explanation whose own score was 92.43 — and the step that
+  orders those entities says in its own docstring that no score is computed. The same default put
+  a zero on every entity of every intent, and an `explanation` block with `winner: null,
+  score: 0.0` on the intents that return what they found rather than choose a winner: the shape
+  the field called *a ranking block that never ran*.
+  - Both fields are `None` when nothing wrote them. The order is real and structural, so the
+    payload states it: `entities_ranked_by` — *"reach from the target (direct before indirect),
+    then identity — a structural order, not a per-entity score"*.
+  - `retrieve` remains `[PARKED]`; this is the honesty fix the tier does not excuse.
+
+- **`archetype` no longer scores an unmeasured HTTP surface as an absent one** (C3-7). The
+  command declares `endpoints` as a missing signal on runs with no root to read — and then
+  scored as if the answer were **0**, which is a measured statement. Inside the scorer that zero
+  did two things at once: it refuted `api-first` and it fired `worker`'s `event_no_http`
+  evidence, so a repository nobody measured came back classified as an event worker with the
+  reason published as if it were a finding (I-3/R9, inside a score).
+  - The count is nullable now. Unmeasured contributes nothing and says so in its own evidence
+    row; `event_no_http` requires the absence of HTTP as a *measured* fact. A measured zero
+    behaves exactly as before, which the battery asserts alongside the unmeasured case.
+  - Measured while closing it, and recorded rather than acted on: `archetype` on
+    BroadleafCommerce takes **9.3 s** (the field reported 22 s) and returns two high-confidence
+    dimensions of four, so the tier stays `[EXPERIMENTAL]` — the cost complaint does not
+    reproduce at that magnitude, and a command with two high-confidence answers is not a
+    candidate for `parked`.
+
+- **The summary stopped costing more than the analyses it summarises** (C3-6, C3-21). Measured on
+  BroadleafCommerce with nothing warm: `--compact` **19.3 s → 13.3 s**, and with the parse cache
+  warm **14.0 s → 7.9 s**; `endpoints` **3.3 s → 1.4 s**. Two duplications inside one process, both
+  removed:
+  - The **core view was built twice on every cold run** — once for the L1 cache write and once for
+    the RIS update — and building it rebuilds the CIR. One repository state has one core view; both
+    writers now read it.
+  - The **endpoint extractor parsed every file itself** while `build_repo_ir` read the
+    content-addressed parse cache for the same bytes. A run that does both paid for the same parse
+    twice, and a warm cache measurably bought `endpoints` nothing — a fact this product published
+    in its own cache model. Same key, same extractor, same capture signature: the entry either side
+    writes is the entry the other reads. The cache-model rows for `endpoints` and the root command
+    are re-measured accordingly.
+  - The inversion is **narrowed, not gone**: `--compact` is still slower than `spring-audit`
+    (3.6 s) or `posture` (1.9 s), because it builds the summary *and* the core view where those
+    build one analysis each.
+  - **C3-21 does not reproduce on 3.7.0**: the cache hit that cost 2 647 ms now costs 1.6 s for
+    `explain` against a 1.6 s cold run, and the snapshot hit for `--compact` is 0.29 s. Recorded as
+    measured, not assumed closed.
+  - The battery pins the two mechanisms rather than wall-clock figures: a second extraction must
+    re-parse nothing, the cached and uncached answers must be identical, and one root run must
+    build the core view once.
+
+- **A comment can no longer take a whole file out of the graph** (E-1). The declaration joiner
+  decided whether a line *starts* a type declaration by scanning raw text, so a comment carrying
+  `class` or `interface` followed by an identifier looked like a declaration head with its brace
+  on a later line — `/** Implements the interface only for the legacy path. */`, or a trailing
+  `// starter class is not an utility class` on an annotation. The join then swallowed the
+  annotation and the real declaration into one entry beginning with `@`, which the parser reads
+  as a pending annotation and never examines: the file contributed **zero symbols** — no type,
+  no endpoint, no transaction boundary — and a file that contributes nothing looks exactly like
+  a file with nothing in it, which is why no field report could ever name this.
+  - Comments are stripped before the keyword scan (block state carried across lines, string
+    literal aware), and the brace that ends a join must also be code, so a commented `{` no
+    longer cuts a real multi-line declaration in half.
+  - Measured A/B over six repositories: **open-banking-gateway recovers 6 types, three of them
+    Spring Boot application classes**; petclinic, eureka, openmrs-core, BroadleafCommerce and
+    keycloak are unchanged, and **no repository loses a symbol**.
+
+- **`generate-tests` ranks by what depends on the file, not by how the file is named**
+  (C3-13, **`untested_sources[]` entries change shape**). Two rules, both name matching, both
+  measured on openmrs-core: admission kept only files whose name ends in one of five suffixes
+  (`Service.java`, `Controller.java`, `Repository.java`, `Mapper.java`, `RestController.java`),
+  reducing **866 production files to 11 candidates**; and coverage was a filename pair, so
+  `PersonServiceImpl` was a gap for want of a `PersonServiceImplTest`. What remained was ordered
+  by how often the substring `"public "` appears in the first 16 KB — while `blast_radius`,
+  transaction boundaries and endpoint exposure were already computed elsewhere in the same
+  product and never consulted.
+  - **Coverage is now a reach fact**: a type is covered when a test source reaches it — named
+    directly, or reached along the call, instantiation and injection edges a blast radius
+    already walks, through the interface the container wires it behind, or as a supertype of
+    something a test exercises. One forward traversal from every test type: 0.01 s on
+    BroadleafCommerce. Reaching is not asserting, so the coverage figure is a floor and the gap
+    list is a ceiling, and `notes` says so.
+  - **Admission is the population**, not a naming convention: openmrs-core 866 production files
+    → **161 untested**, BroadleafCommerce 2 765 → **1 494**, published as `population` beside
+    the list.
+  - **Order is the measured axes** — endpoints reached, transaction boundaries declared, classes
+    that depend on it — reusing `caller_reach`, `spring_impact._collect_endpoints` and
+    `spring_semantic.boundaries_declared_within` rather than deriving them again. The weights
+    that fold the three into `score` are published with `rank_weights_basis: "assumption, not a
+    measurement"`, and the order is reproducible from the axes without accepting them.
+  - `untested_sources[]`/`test_gaps[]` rows drop `rank_score`, `public_method_count` and
+    `has_framework_annotations` — measurements of the replaced basis — and carry
+    `endpoints_reached`, `transaction_boundaries` and `caller_classes` instead. `path`, `score`
+    and `reason` are unchanged. The new `test_gap_ranking` block publishes the basis, the
+    population and the caps.
+  - Cost, measured cold: BroadleafCommerce 11.1 s → **15.3 s**, openmrs-core 5.1 s → 10.2 s. A
+    run whose IR cannot be built keeps the filename algorithm and publishes the
+    `test_reach_graph` signal with what taking it costs the answer (I-8).
+
+- **`generate-tests` publishes its time budget, and a cache no longer defeats it** (C3-1). The
+  30 s cap was reachable only through `SOURCECODE_TESTS_TIMEOUT_MS`, a name in no help text —
+  the one knob that turns an empty answer into an answer was invisible to whoever was holding
+  the empty answer. `--timeout <seconds>` is now a documented flag (the variable still works;
+  the flag wins), and an exhausted budget publishes `analysis_budget` carrying the new
+  `time_budget` cap: *"an empty list here means the walk stopped, NOT that the repository has
+  nothing"*, with the budget, its source, and how to raise it.
+  - Closing it surfaced a sharper defect, measured: **the cache key ignored the budget**, so a
+    run that exhausted 2 s answered the re-run at 30 s from cache — the remedy the payload
+    names did nothing at all. The budget is now part of the cache identity, and an exhausted
+    result is never stored: an unfinished walk is worth re-running.
+  - Measured while closing it: the full scan on openmrs-core (3 300 files, cold cache) takes
+    **3.35 s** and returns 13 untested sources, so the field's empty payload does not reproduce
+    and the default budget is not the constraint it was taken for. The ranking half of C3-13
+    stays open — the command still matches file names while `blast_radius`, transactional
+    writes and endpoint exposure are already computed.
+
+- **`review-pr` no longer counts documentation as a runtime change** (C3-11b). The field
+  reported a diff of 227 `.md` files as `runtime_changes: 228` — while every one of those
+  entries carried `artifact_type: "documentation"` and `change_effect: "documentation file (no
+  runtime impact)"`. The list contradicted its own members. Reproduced on a real git repository
+  (12 `.md` files + one touched controller): **13 → 1**. The classifier was never wrong;
+  membership was "not noise and not a build manifest", which admits everything else, and the
+  admission seam (K2) now asks whether the admitted type can carry runtime behaviour at all.
+  - Nothing is dropped: the twelve are reported under `non_runtime_changes` with the same
+    evidence and effect statement, and the GitHub comment names them by count so it cannot look
+    like it missed part of the diff.
+  - The split is asserted **against the effect statements themselves** — a type whose published
+    statement disclaims impact must be in the non-runtime set — so it cannot drift from the
+    prose it is derived from (C4-1).
+
+- **One profile population, whatever surface is asked** (C1-18, **`spring_profiles` changes on
+  repositories with resource bundles or resource folders**). Reproduced on a fixture first: the
+  same repository in one session answered `["qa","dev"]` in the default view, `["dev","prod",
+  "staging"]` in `posture` and `["dev","prod","qa","staging"]` under `--agent`. Three
+  populations under one name — and every conditional-security finding is keyed on that set, so
+  the default agent surface was answering the profile question with the population that had
+  lost the environments.
+  - Authority `spring_profiles.profile_population`: four named signals — the
+    `application-{profile}` filename, the per-environment overlay directory,
+    `spring.config.activate.on-profile` / `spring.profiles` inside config documents, and
+    `@Profile` on a bean — unioned once, with `by_signal` published so each name's provenance
+    is auditable. The Java stack detector, `posture` and the serializer's profile section all
+    read it, asserted per surface.
+  - Closing it exposed two false positives in the signals it inherited, both fixed
+    structurally rather than by name (VAI): an `application-{x}` file counts only **beside its
+    base config** — alfresco-community-repo's `alfresco/messages/application-model_de.properties`
+    and 19 siblings were reported as twenty environments, now none — and an overlay directory
+    counts only when it **holds a config file** — spring-petclinic's `db/`, `messages/`,
+    `static/` and `templates/` were reported as four environments, now `mysql, postgres`, its
+    real profiles.
+
+- **The token-saving ratio is published, and published as a ceiling** (CL-1). `token_economy`
+  emitted `emitted`, `baseline_raw_read` and `saved` — three numbers a reader divides into a
+  multiple and then quotes. The multiple travelled without the label the block put on the
+  inputs, which is how "up to 55×" ends up in a room. `ratio_upper_bound` is now emitted with
+  a `ratio_basis` that states the counterfactual making it a ceiling — every cited file and
+  build manifest read **in full and once** — the band we measured for the ceiling itself
+  (**3.8×–37.6×** over `--compact` and `--agent` on spring-petclinic, BroadleafCommerce,
+  openmrs-core and keycloak; nothing near 55×), and the field's 10×–20× read of the saving an
+  agent actually realizes.
+- `realized_saving` is `null` with its reason rather than a number: which files an agent would
+  truly have read is not observable from this process, and a `0` there would read as "no
+  saving" (I-3).
+
+- **`spring-audit` counts defects as well as observations** (C2-5). A rule fires per
+  observation; a reader counts repairs. The audit published only the first number and let it
+  stand for the second: on openmrs-core `ConceptServiceImpl#checkIfLocked` carried **six
+  TX-006 findings, one per call site, for one annotated method with one fix**, and the
+  ledger's original witness is a private `@Transactional` method that draws TX-001 *and*
+  TX-006 for the same repair. Measured on the fleet: **openmrs-core 38 findings → 29
+  defects, BroadleafCommerce 19 → 14**.
+  - A defect is `(category, defect_kind, symbol)` — the thing you edit, and what is wrong
+    with it. `defect_kind` is **declared by the rule itself** (TX-001 and TX-006 both
+    declare `proxy_bypass`) and defaults to the rule's own id, so a rule that declares
+    nothing is never merged into another by omission, and there is no rule table maintained
+    beside the rules to drift out of date (C4-1).
+  - Nothing is filtered. `findings[]` keeps every observation and each one now names its
+    `defect_id`; the new `defects[]` rows carry `rule_ids`, `witness_count` and the witness
+    ids, so the grouping is auditable in both directions. `summary` publishes
+    `total_findings`, `total_defects`, `defects_by_severity` and a `counts_note` stating
+    which is which — `by_severity` and `by_category` keep counting observations, because a
+    count that changes basis under an unchanged name is the same defect wearing a new suit.
+  - A defect takes the **strongest** severity and confidence among its witnesses, and its id
+    is keyed on the identity, not the witnesses — acquiring a second witness next run does
+    not rename it, so a baseline keeps matching it.
+
+- **`migrate-check` lists the blockers; hygiene is counted, not listed** (C2-6, **default
+  payload changes**). On openmrs-core the default report carried 310 findings of which **184
+  were `java_8_best_practice` advisory hygiene** — findings that block no version and that
+  every readiness score already excludes. A reader scanning the array met three advisory
+  entries for every two blockers. The emitted list now carries the blockers, ordered
+  most-severe first (**310 → 126 listed, 912 KB → 717 KB**), and `--include-hygiene` restores
+  the entries.
+  - **The floor cuts the list, never a figure.** `summary.by_severity`, `by_rule`,
+    `by_migration_target`, `total_findings`, `hygiene_findings`, `blocking_count` and every
+    dimension score are byte-identical to the unfloored run and still cover the whole
+    population — verified as an equality, not a claim.
+  - It is published as a cap, not applied in silence: `findings_floor` (the `severity_floor`
+    row of `CAP_EFFECTS`, I-8) states what was removed, what stayed exact, and the flag that
+    restores it, so `len(findings)` is never read as the total.
+  - The other half of the ledger row — "headline score reads 0/100 while real blockers are
+    481" — was already closed and re-measured here: hygiene is out of the aggregate, and
+    openmrs's 0 is `min(jakarta 0, hibernate 0)` with `jdk_modernization` (58) excluded by
+    design. The score was honest; the finding list was the noise.
+
+## [3.7.0] — 2026-08-01
+
+**The exit-code contract and the C3 surface block.** Seven rows closed: the two the field named
+as blocking for CI (exit codes over correct answers), the fourth and fifth appearance of a
+curated list beside real data, and three surfaces that published a promise the payload did not
+keep.
+
+Minor and not patch, because a pipeline can see the difference: `plan` exits 1 where it exited 0
+over a target it never resolved (C3-29), `ask <cmd> | head` exits 0 where a correct run used to
+exit non-zero (C3-28), `--output FILE` carries the whole answer where it was silently trimmed
+(C3-17), `--agent` publishes sections it used to omit (C3-10), and a path-shaped target that was
+refused as ambiguous now resolves (C3-35).
+
+### Fixed
+
+- **A broken output pipe is no longer a failed run** (C3-28, **exit code changes for
+  `ask <cmd> | head`**). `ask repo-ir . --force | head -c 100` returned the correct bytes and
+  exit 1; under `set -e` that stops a pipeline with no error anywhere to explain it — the field
+  named it one of two blockers for CI. One authority now says what a closed stream means
+  (`pipe_contract.py`, installed at the entry point): **a broken output stream changes nothing
+  except where the remaining bytes go.** The descriptor is redirected to the null device on the
+  first broken write and the command finishes and exits on its own terms.
+  - **It does not overwrite the command's own verdict.** `ask impact <ambiguous target> | head`
+    still exits 1, because a consumer that stopped reading has no opinion about whether the
+    analysis resolved its target.
+  - Redirecting before the shutdown flush is what keeps Python from printing
+    `Exception ignored in: <_io.TextIOWrapper …>` and exiting 120 — the same defect wearing a
+    different number.
+  - **The wrapper covers `.buffer`, which is the whole fix**: payloads are written as bytes
+    through `sys.stdout.buffer` at the single emit seam, so a text-only wrapper sits beside the
+    one write this exists for. Measured: with the text wrapper alone, nothing changed.
+  - Only visible above a pipe buffer, which is why it looked intermittent: `endpoints` on a
+    small repository exits 0 either way, `repo-ir` on the same repository did not.
+
+- **An unresolved target has one exit code across every command** (C3-29, **`plan` now exits 1
+  where it exited 0**). `plan <unknown> <repo>` ran to completion, emitted a plan-shaped payload
+  of zeros with `resolution: "not_found"` and exited **0**, while `impact` on the same input
+  exited 1 — so a gate could not tell "nothing to review" from "I never found what you asked
+  about". One authority (`target_admission.py`), four commands rebound (`impact`,
+  `impact-chain`, `plan`, `explain`), and the two other copies of the same literal set
+  (`compare`, `change_plan`) now read it instead of restating it.
+  - **Ambiguity is the same fact, and it was not in the field report.** A target matching
+    several classes returns `ambiguous_path`, empty results and a message asking for the full
+    FQN — the command declined to answer — and `impact` exited **0** on it. Measured on a
+    purpose-built two-class fixture, since no battery repository carries the shape.
+  - Unresolved is **1, not 2**: 2 is reserved by the `verify` family for a run that could not
+    look, and this run looked. Partial and expanded resolutions stay 0 — they are answers about
+    the target the caller named.
+  - `plan`'s `Note:` on stderr is gone with it: the payload already carries the statement, and
+    a successful-looking run should not be narrating on stderr (the `plan` half of C3-34).
+
+- **`--help` reaches inside command groups** (C4-7). `ask cache model` — what a warm buys each
+  command, per layer, including the commands it buys nothing for — appeared in no help text at
+  all: the root catalogue was generated (C4-1/C4-2) but the Cache and Auth blocks under it were
+  three lines somebody typed by hand. The blocks are now built from the registered groups, so a
+  subcommand is listed the moment it is registered; a group too large to name in full (`retrieve`,
+  29 parked intents) publishes its **exact count** and a pointer, never silence. The battery
+  fails if a subcommand of a listed group is missing, or if a collapsed group's count drifts.
+
+- **A successful run says nothing on stderr — measured over the commands, not over a list**
+  (C3-34, the `repo-ir` half). `ask repo-ir . --force` wrote an 82-byte size advisory on a run
+  that exited 0 with the IR on stdout, which PowerShell 5.1 raises as a `NativeCommandError`.
+  The advisory is terminal-gated now, like every other notice, and so is the `--exclude`
+  directory warning and the output-budget trim warning found beside it.
+  - **The list was the defect.** `tests/test_stderr_purity_matrix.py` enumerated 13 commands by
+    hand for the fourth time in three releases; the rows are now **discovered from the CLI**,
+    with every command either driven or carrying a written reason it cannot be. Nine more
+    commands are driven as a result, `cache` subcommands included.
+  - The `repo-ir` row builds a repository large enough for the advisory to actually fire and
+    **asserts it fired**, because a row that never reaches the branch proves nothing.
+
+- **`--output FILE` is no longer trimmed to an agent's context window** (C3-17). The payload
+  budget exists because a context window is finite — it is a constraint on **stdout**. Written
+  to a file it cut the answer anyway, dropped `key_dependencies` entirely, and the note
+  explaining the cut advised `--output`, the flag already in use. Two of six call sites had the
+  rule and four did not (`prepare-context`, `modernize`, the cached-view rebuild, and `impact`
+  in part), so it now lives in one seam (`cli._apply_budget`) and a battery fails if a seventh
+  call site decides for itself.
+  - **The cache had the same defect one layer down**, found while field-checking the seam:
+    `prepare-context` stored the document *after* trimming, so the first stdout run poisoned the
+    cache and every later `--output FILE` hit received a stdout-sized answer. The cache stores
+    the analysis now and the budget is applied per run — measured on alfresco-community-repo:
+    stdout 5 files, cache hit to a file 26.
+  - **`--full` says what it does.** It raises the caps (boundaries and DTO mappers in full,
+    `file_relevance` to 40); it never removed them — under `--agent --full` the file list stayed
+    capped at 40 of 710 while the flag's help promised "remove truncation limits".
+
+- **`--agent` cannot publish less than `--compact`** (C3-10). `--compact` documents
+  `security_surface` "when custom security annotations detected" and closes with "use `--agent`
+  for maximum signal", while `--agent` was assembled from its own hand-written list of sections:
+  measured on BroadleafCommerce it omitted `deployment` and `language_version` outright, and
+  nothing stopped the security surface going the same way. Both views now read one authority
+  (`serializer.JAVA_SPRING_SECTIONS`), and the battery fails on any section `--compact` publishes
+  that `--agent` does not.
+
+- **A path that names one file resolves to that file** (C3-35). Every resolver reduced a
+  path-shaped target to its basename before anything looked at it, so
+  `ask impact src/main/java/com/a/Service.java` answered `ambiguous_path` and offered
+  `com.a.Service` **and** `com.b.Service` — being more specific made the answer worse. A path is
+  matched against the `source_file` each symbol came from, strongest tier first (exact, then
+  module-relative, then parent-relative), and nested types collapse to the type the file is about
+  (on eureka, `DiscoveryClient.java` declares its outer class and five inner ones). One authority
+  in `target_admission`, because three graphs answer target questions — the repo IR, and the CIR
+  that `explain` and `impact-chain` read, both of which used to answer `not_found` for a path.
+  Parity checked on eureka: by path and by name give byte-identical `stats`.
+
+- **`verify-edit` stops paying for a diff it has already proved empty** (C3-32). It computed the
+  change set and then built the HEAD CIR *and* the working CIR unconditionally — on a clean tree
+  the second is the first by construction. Measured on a clean ofbiz-framework: **5.9 s -> 1.7 s**
+  warm. The shortcut is taken only when git actually answered: a failed `git diff` also returns an
+  empty list, and reading that as "nothing changed" would trade dead cost for a false green.
+
+- **`spring-audit --compact`** (C3-31). The one analysis command with no summary mode: 1.99 MB for
+  14 findings in the field, *"a context overflow against an LLM with no filter in between"*. The
+  weight is not the findings — on BroadleafCommerce `security_posture.endpoints` is 113 KB of a
+  178 KB report, and the counts it supports are published beside it. `--compact` caps that list and
+  `findings` to their top 5, ordered by what asks something of the reader (`probably_exposed`
+  first; most severe first), and recomputes nothing: **178 KB -> 25 KB with every count
+  identical**. A flag changes how much is emitted, never the shape (C2-10) — each list stays a list
+  and the totals live in a `*_cap` sibling that exists only when the cap bit.
+
+
+### Documentation
+
+- **Field evaluation #6 of 3.5.0 recorded** (`.planning/FIELD-EVAL-6-2026-08-01.md`, defect
+  ledger, development roadmap). Full 27-command catalogue, repository left byte-identical,
+  scored 8/10. Every reported defect was re-measured on 3.6.0 before it was written down: two
+  do not reproduce (one closed here as C3-15, one by the 3.5.0 admission authority) and the
+  re-measurement found two the evaluation did not report.
+- **New rows**: C1-18 (profile population differs per command, and the narrower one is what an
+  agent reads) · C3-28/C3-29 (**exit codes that lie over correct answers** — a broken pipe
+  exits non-zero on a successful run, `plan` exits 0 on a target it did not resolve while
+  `impact` exits 1) · C3-30 (`verify --init`) · C3-31…C3-34 · C4-7 (`cache model` in no help
+  panel) · P-4 (`baseline` history nobody automated) · CL-7 (non-coverage: no dataflow, no
+  secrets outside Java/YAML, filter order not reconstructed) · CL-8 (`posture --diff` answers
+  conditionally because the profile is decided outside the repository).
+- **The executive roadmap gains what the product does *not* do**, published beside the
+  capabilities, and the evaluation table is current through eval #6.
+
 ## [3.6.0] — 2026-08-01
 
 **The P0 block and the C1/C2 backlog.** Nine rows closed, three closed by measurement alone

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 3.6.0
+Version: 3.8.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
@@ -251,7 +251,7 @@ from it.
 | `review-pr` / `fix-bug` / `prepare-context` | supported | diff review, symptom triage, task-shaped context | |
 | `plan` / `compare` / `delta` / `contract-diff` | supported | what to review for a change; candidates by measured cost; outcome of a change; public-contract break | no verdicts, measured cost only |
 | `validation` | supported | request-body validation coverage and gaps | |
-| `baseline capture\|diff\|trend` | supported | versioned architectural metrics over time | trend reporting, not gating |
+| `baseline capture\|diff` · `trend` | supported | versioned architectural metrics over time; `ask trend <dir>` reads the series | trend reporting, not gating. Baselines land in `.ask/baselines` **inside the repository** — the history travels with the code, not with a vendor; an audit that must not write passes `--dir`. Automate it: [baseline-ci.yml](docs/baseline-ci.yml) |
 | `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 | |
@@ -275,6 +275,34 @@ Honest limits worth knowing before you rely on it:
 - Architecture classification is tuned for Spring MVC layered apps; SPI/plugin models (e.g. Quarkus extensions) may be misclassified. JAX-RS subresource-locator endpoint recall is ~65%.
 - Self-invocation `@Transactional` bypass (same-class call skipping the proxy) is not detected.
 
+### What the security surface does not answer
+
+Published because a product that states its limits is not compared on breadth — it is
+compared on depth. Each row is emitted in the payload too (`non_coverage`), so an agent
+reading JSON sees the same boundary a buyer reads here.
+
+| Not covered | Why | What answers it |
+|---|---|---|
+| **Whether request input reaches a sink — no dataflow or taint analysis.** | This engine resolves structure and wiring without compiling. Taint needs value flow through a program, which is a different analysis with a different failure mode: an unsound one produces confident findings that are wrong, and every claim here is meant to be checkable against the line that produced it. | A dataflow scanner (Semgrep, CodeQL). What this product adds on top is reachability: which of that tool's findings sit behind an endpoint that is reachable unauthenticated. |
+| **Secrets outside Java and Spring configuration — a credential in a deployment descriptor, a Helm value, a CI variable file.** | The file population this analyzer reads is the Java source and the Spring configuration convention. A secret elsewhere is not missed by a weak rule; it is outside the set of files anything here opens. | A dedicated secret scanner over the whole tree (gitleaks, trufflehog). |
+| **Filter-chain order and per-filter URL patterns — the presence of a custom filter is structural only.** | Which filter runs first is decided by bean ordering this analyzer does not resolve. Where two active configurations both match a request, the answer published is `undecided` rather than a guess. | `ask posture --profile <set>` states per endpoint what the readable rules decide and what they leave undecided. |
+| **Known vulnerabilities in dependencies — no CVE database, no version advisory matching.** | Enriching a vulnerability feed is a different product with a different update cadence; a stale embedded database is worse than no database, because it reads as a clean bill of health. | A dependency scanner (Trivy, OWASP Dependency-Check). `impact-chain` then answers which of its findings anything actually reaches. |
+
+Two more boundaries worth stating in the same voice:
+
+| Not covered | Why | What answers it |
+|---|---|---|
+| **Applying a migration — nothing here edits source.** | This is the diagnosis layer: it measures what must change and what each change would reach. Rewriting code is an execution problem with an established executor, and duplicating it would mean maintaining a second, worse one. | OpenRewrite. `migrate-check` publishes the recipe each finding carries (`recipes[]`), which is the input that executor takes. |
+| **What the process environment sets at start-up — the profile set, properties and secrets a container is given.** | Nothing in a repository can observe the environment of a process that has not started. A value read from a file here is the default the repository ships, never a guarantee of what runs. | `ask posture --resolve-environments` reads every artefact in the repository that names the profile set, says when none of them decides it, and ranks the admissible sets by what each leaves open. |
+
+**Positioning.** Until an executor ships, this is the **diagnosis layer**: it measures what
+must change, what each change reaches, and what a gate should block — and it removes none of
+it. Field evaluation scored it 7/10 as a report generator and 5.5/10 as a development tool,
+and that gap is the honest description, not a defect to argue with. `migrate-check` publishes
+the OpenRewrite recipe each finding carries so the executor that does apply changes has its
+input.
+
+
 ---
 
 ## Pricing
@@ -348,7 +376,8 @@ Matching endpoints report `policy: "custom"` and drop out of the `no_security_si
 | Doc | What it covers |
 |-----|----------------|
 | [USER_GUIDE.md](docs/USER_GUIDE.md) | Full command reference, flags, output schema, workflows |
-| [contracts.md](docs/contracts.md) | Declare invariants in `.ask/contracts.yml`, enforce them in the edit loop and in CI |
+| [contracts.md](docs/contracts.md) | Declare invariants in `.ask/contracts.yml` (or derive them with `ask verify --init`), enforce them in the edit loop and in CI |
+| [baseline-ci.yml](docs/baseline-ci.yml) | Capture an architectural baseline per release, so the series exists when you want to read it |
 | [posture.md](docs/posture.md) | What a profile set actually wires — down to which endpoints its filter chain permits — and what could not be decided (experimental) |
 | [migrate-check.md](docs/migrate-check.md) | Migration rule catalogue (MIG-001..043) + Hibernate stratification |
 | [MODERNIZATION.md](docs/MODERNIZATION.md) | The modernization product: assess → understand → plan → execute |

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

@@ -213,7 +213,7 @@ from it.
 | `review-pr` / `fix-bug` / `prepare-context` | supported | diff review, symptom triage, task-shaped context | |
 | `plan` / `compare` / `delta` / `contract-diff` | supported | what to review for a change; candidates by measured cost; outcome of a change; public-contract break | no verdicts, measured cost only |
 | `validation` | supported | request-body validation coverage and gaps | |
-| `baseline capture\|diff\|trend` | supported | versioned architectural metrics over time | trend reporting, not gating |
+| `baseline capture\|diff` · `trend` | supported | versioned architectural metrics over time; `ask trend <dir>` reads the series | trend reporting, not gating. Baselines land in `.ask/baselines` **inside the repository** — the history travels with the code, not with a vendor; an audit that must not write passes `--dir`. Automate it: [baseline-ci.yml](docs/baseline-ci.yml) |
 | `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 | |
@@ -237,6 +237,34 @@ Honest limits worth knowing before you rely on it:
 - Architecture classification is tuned for Spring MVC layered apps; SPI/plugin models (e.g. Quarkus extensions) may be misclassified. JAX-RS subresource-locator endpoint recall is ~65%.
 - Self-invocation `@Transactional` bypass (same-class call skipping the proxy) is not detected.
 
+### What the security surface does not answer
+
+Published because a product that states its limits is not compared on breadth — it is
+compared on depth. Each row is emitted in the payload too (`non_coverage`), so an agent
+reading JSON sees the same boundary a buyer reads here.
+
+| Not covered | Why | What answers it |
+|---|---|---|
+| **Whether request input reaches a sink — no dataflow or taint analysis.** | This engine resolves structure and wiring without compiling. Taint needs value flow through a program, which is a different analysis with a different failure mode: an unsound one produces confident findings that are wrong, and every claim here is meant to be checkable against the line that produced it. | A dataflow scanner (Semgrep, CodeQL). What this product adds on top is reachability: which of that tool's findings sit behind an endpoint that is reachable unauthenticated. |
+| **Secrets outside Java and Spring configuration — a credential in a deployment descriptor, a Helm value, a CI variable file.** | The file population this analyzer reads is the Java source and the Spring configuration convention. A secret elsewhere is not missed by a weak rule; it is outside the set of files anything here opens. | A dedicated secret scanner over the whole tree (gitleaks, trufflehog). |
+| **Filter-chain order and per-filter URL patterns — the presence of a custom filter is structural only.** | Which filter runs first is decided by bean ordering this analyzer does not resolve. Where two active configurations both match a request, the answer published is `undecided` rather than a guess. | `ask posture --profile <set>` states per endpoint what the readable rules decide and what they leave undecided. |
+| **Known vulnerabilities in dependencies — no CVE database, no version advisory matching.** | Enriching a vulnerability feed is a different product with a different update cadence; a stale embedded database is worse than no database, because it reads as a clean bill of health. | A dependency scanner (Trivy, OWASP Dependency-Check). `impact-chain` then answers which of its findings anything actually reaches. |
+
+Two more boundaries worth stating in the same voice:
+
+| Not covered | Why | What answers it |
+|---|---|---|
+| **Applying a migration — nothing here edits source.** | This is the diagnosis layer: it measures what must change and what each change would reach. Rewriting code is an execution problem with an established executor, and duplicating it would mean maintaining a second, worse one. | OpenRewrite. `migrate-check` publishes the recipe each finding carries (`recipes[]`), which is the input that executor takes. |
+| **What the process environment sets at start-up — the profile set, properties and secrets a container is given.** | Nothing in a repository can observe the environment of a process that has not started. A value read from a file here is the default the repository ships, never a guarantee of what runs. | `ask posture --resolve-environments` reads every artefact in the repository that names the profile set, says when none of them decides it, and ranks the admissible sets by what each leaves open. |
+
+**Positioning.** Until an executor ships, this is the **diagnosis layer**: it measures what
+must change, what each change reaches, and what a gate should block — and it removes none of
+it. Field evaluation scored it 7/10 as a report generator and 5.5/10 as a development tool,
+and that gap is the honest description, not a defect to argue with. `migrate-check` publishes
+the OpenRewrite recipe each finding carries so the executor that does apply changes has its
+input.
+
+
 ---
 
 ## Pricing
@@ -310,7 +338,8 @@ Matching endpoints report `policy: "custom"` and drop out of the `no_security_si
 | Doc | What it covers |
 |-----|----------------|
 | [USER_GUIDE.md](docs/USER_GUIDE.md) | Full command reference, flags, output schema, workflows |
-| [contracts.md](docs/contracts.md) | Declare invariants in `.ask/contracts.yml`, enforce them in the edit loop and in CI |
+| [contracts.md](docs/contracts.md) | Declare invariants in `.ask/contracts.yml` (or derive them with `ask verify --init`), enforce them in the edit loop and in CI |
+| [baseline-ci.yml](docs/baseline-ci.yml) | Capture an architectural baseline per release, so the series exists when you want to read it |
 | [posture.md](docs/posture.md) | What a profile set actually wires — down to which endpoints its filter chain permits — and what could not be decided (experimental) |
 | [migrate-check.md](docs/migrate-check.md) | Migration rule catalogue (MIG-001..043) + Hibernate stratification |
 | [MODERNIZATION.md](docs/MODERNIZATION.md) | The modernization product: assess → understand → plan → execute |

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

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

{sourcecode-3.6.0 → sourcecode-3.8.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.6.0"
+__version__ = "3.8.0"