sourcecode 3.7.0__tar.gz → 3.8.0__tar.gz

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

@@ -1,5 +1,318 @@
 # 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 3.7.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.7.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.7.0 → sourcecode-3.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "3.7.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.7.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.7.0"
+__version__ = "3.8.0"

{sourcecode-3.7.0 → sourcecode-3.8.0}/src/sourcecode/archetype.py

@@ -175,8 +175,13 @@ class _Features:
     module_count: int
     concept_mass: dict[str, float]        # concept → fraction of source files
     entry_kinds: dict[str, int]
-    endpoint_total: int
-    endpoint_share: float                 # endpoints per source file
+    # `None` when the endpoint surface was NOT measured (no root to read, or the
+    # extraction failed). It used to be 0, which is a different claim: a score
+    # that reads "no HTTP surface" off an unknown one refutes `api-first` and
+    # actively supports `worker`, so an unmeasured repository was classified as
+    # if it exposed nothing (I-3/R9, inside a score).
+    endpoint_total: "Optional[int]"
+    endpoint_share: "Optional[float]"     # endpoints per source file
     packaging: Optional[str]
     frameworks: set[str]
     graph_hubs: list[str]
@@ -250,7 +255,11 @@ class ArchetypeClassifier:
             signals_missing=f.signals_missing,
             generated_from=(
                 f"{f.total_files} source files, {f.module_count} modules, "
-                f"{f.endpoint_total} endpoints"
+                + (
+                    f"{f.endpoint_total} endpoints"
+                    if f.endpoint_total is not None
+                    else "endpoint surface not measured"
+                )
             ),
             graph_metrics=f.graph_metrics,
         )
@@ -299,8 +308,10 @@ class ArchetypeClassifier:
             missing.append("entry_points")
 
         endpoint_total = self._endpoint_count(root)
-        endpoint_share = (endpoint_total / total) if total else 0.0
-        if root is not None:
+        endpoint_share = (
+            (endpoint_total / total) if (endpoint_total is not None and total) else None
+        )
+        if endpoint_total is not None:
             used.append("endpoints")
         else:
             missing.append("endpoints")
@@ -519,21 +530,31 @@ class ArchetypeClassifier:
         # api-first: HTTP surface must be significant relative to size. Ramp so a
         # rounding-error surface cannot win: 0 below 0.5 endpoints/100 files, linear
         # to full strength at >=2/100 files. (neo4j: 18/5600 = 0.32/100 -> 0.)
-        density = f.endpoint_share * 100
-        api_strength = max(0.0, min(1.0, (density - 0.5) / 1.5)) if f.endpoint_total else 0.0
-        add("api-first", "endpoint_density",
-            f"{f.endpoint_total} endpoints over {f.total_files} files "
-            f"({density:.2f}/100 files)",
-            3.0, api_strength, 1.0)
+        if f.endpoint_share is None:
+            # Unmeasured, not zero: contribute nothing and say which axis is blind.
+            add("api-first", "endpoint_density",
+                "endpoint surface not measured — this dimension is scored without it",
+                3.0, 0.0, 0.0)
+        else:
+            density = f.endpoint_share * 100
+            api_strength = max(0.0, min(1.0, (density - 0.5) / 1.5)) if f.endpoint_total else 0.0
+            add("api-first", "endpoint_density",
+                f"{f.endpoint_total} endpoints over {f.total_files} files "
+                f"({density:.2f}/100 files)",
+                3.0, api_strength, 1.0)
         cli_entries = f.entry_kinds.get("cli", 0)
         add("cli", "cli_entry_points", f"{cli_entries} CLI entry point(s); cli mass ≈ {cm['cli']:.0%}",
             2.5, 1.0 if cli_entries else (1.0 if cm["cli"] > 0.05 else 0.0), max(cm["cli"], 0.2))
         add("daemon", "server_bootstrap",
             f"server/bootstrap entries: {f.entry_kinds.get('server',0)+f.entry_kinds.get('bootstrap',0)}",
             2.0, 1.0 if ("server" in f.entry_kinds or "bootstrap" in f.entry_kinds) else 0.0, 0.5)
+        # `event_no_http` needs the absence of HTTP as a MEASURED fact: firing it
+        # on an unmeasured surface is how an unknown became evidence for `worker`.
+        _no_http_known = f.endpoint_total == 0
         add("worker", "event_no_http",
-            f"event mass ≈ {cm['event']:.0%}, endpoints={f.endpoint_total}",
-            1.5, 1.0 if (cm["event"] > 0.05 and f.endpoint_total == 0) else 0.0, max(cm["event"], 0.1))
+            f"event mass ≈ {cm['event']:.0%}, endpoints="
+            + (str(f.endpoint_total) if f.endpoint_total is not None else "not measured"),
+            1.5, 1.0 if (cm["event"] > 0.05 and _no_http_known) else 0.0, max(cm["event"], 0.1))
         lib_strength = 1.0 if (f.packaging == "jar" and not f.entry_kinds) else 0.3
         add("library", "consumed_as_dependency",
             f"packaging={f.packaging}, entry kinds={list(f.entry_kinds) or 'none'}",
@@ -666,12 +687,18 @@ class ArchetypeClassifier:
         return head if tail else ""
 
     @staticmethod
-    def _endpoint_count(root: Optional[Path]) -> int:
+    def _endpoint_count(root: Optional[Path]) -> "Optional[int]":
+        """The measured endpoint count, or None when it was not measured.
+
+        Both failure modes — no root to read, and an extraction that raised —
+        return None rather than 0, because every consumer below treats 0 as the
+        measured statement "this repository exposes no HTTP surface".
+        """
         if root is None:
-            return 0
+            return None
         try:
             from sourcecode.repository_ir import extract_java_endpoints
             data = extract_java_endpoints(root)
             return int(data.get("total", len(data.get("endpoints", []))))
         except Exception:
-            return 0
+            return None

{sourcecode-3.7.0 → sourcecode-3.8.0}/src/sourcecode/cache_model.py

@@ -124,16 +124,18 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "`--compact` is what a warm stores by default; `--agent` needs `cache warm --agent`. "
                  "`--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)"),
+                 "--compact 13.3 s cold → 0.3 s warm (cold re-measured on 3.7.0: was 19.3 s, C3-6); "
+                 "--agent --full --env-map --depth 20 34.7 s → 33.9 s (no gain)"),
     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.",
-                 "2.8 s → 2.9 s"),
+    CommandCache("endpoints", ("ris", "parse"), "shared", False,
+                 "Recomputes the endpoint surface on every run, over a parse a warm has already "
+                 "paid for. Until 3.7.0 the extractor parsed every file itself instead of reading "
+                 "the shared parse cache, and a warm measurably bought it nothing (C3-6).",
+                 "3.3 s → 1.4 s (re-measured on 3.7.0; was 2.8 s → 2.9 s)"),
     CommandCache("spring-audit", ("ris", "parse"), "shared", False,
                  "Recomputes every run, but over a parse a warm has already paid for.",
                  "8.8 s → 3.7 s"),
@@ -158,8 +160,8 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "1.1 s → 2.3 s (slower)"),
     CommandCache("plan", ("parse",), "shared", False, "", "9.3 s → 3.8 s"),
     CommandCache("compare", ("parse",), "shared", False, ""),
-    CommandCache("delta", (), "none", False, "Analyses two checkouts; neither is the tree the cache describes."),
-    CommandCache("contract-diff", (), "none", False, "Analyses two checkouts."),
+    CommandCache("delta", (), "none", False, "Analyses two states — two checkouts, or two refs materialised into temporary trees; neither is the tree the cache describes."),
+    CommandCache("contract-diff", (), "none", False, "Analyses two states (checkouts or refs); neither is the tree the cache describes."),
     CommandCache("fix-bug", ("task",), "none", True,
                  "Shorthand for `prepare-context fix-bug`; caches its own answer, which a warm never runs."),
     CommandCache("rename-class", (), "none", False, ""),
@@ -183,6 +185,7 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "Reads the RIS a warm rebuilds — that is all it does. Without one it answers "
                  "`no_ris` instead of a snapshot.",
                  "0.2 s either way"),
+    CommandCache("trend", (), "none", False, "Reads stored baseline artifacts from disk; analyses no source, so no cache layer applies. Same command as `baseline trend`."),
     CommandCache("baseline", ("parse",), "shared", False, "`capture`/`diff`/`trend` over architectural metrics.",
                  "capture 8.7 s → 3.6 s"),
     CommandCache("retrieve", ("cir", "parse"), "shared", False,