sourcecode 3.2.1__tar.gz → 3.2.2__tar.gz

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

@@ -1,5 +1,110 @@
 # Changelog
 
+## [Unreleased]
+
+### Changed
+
+- **Telemetry is opt-in** (P-1). It was opt-out; with no explicit choice on record, nothing is
+  now collected or transmitted — not on the first run, not in CI, nowhere. **An explicit choice
+  you made before is honoured unchanged**; if you never chose, telemetry is off.
+  - The default was not a preference. Field evaluation #3 was the first audit of regulated
+    third-party code (public-sector health data), where the reviewer must be able to state that
+    nothing left the machine — and *"disable it after the first run"* cannot give that
+    guarantee. It was recorded as a **procurement** blocker, not an analysis defect.
+  - The CI special case is gone along with the default it existed to override. CI is still
+    detected for exactly one purpose: skipping a first-run notice that has no terminal to
+    appear on.
+  - The first-run notice is now an **invitation**: it says telemetry is off, states what *would*
+    be collected if you enabled it, and names `ask telemetry enable`. It changes no setting.
+  - `ask telemetry status` distinguishes **"no choice recorded"** from **"you chose disabled"**
+    (`stored_choice()` returns `None`, never a silent `False`) — a buyer auditing this needs to
+    know which of the two they have.
+
+## [3.2.2] — 2026-07-29
+
+**M7.5 complete — the product now says what it promises.** Three things a user could only
+infer are written down and enforced: which of their commands a warm cache actually helps, what
+a cold run costs where they meet it, and **what each command's output is worth relying on**.
+Documenting the first of those found the cache had two freshness authorities and was answering
+for trees it had not read — the pattern of this cycle, where writing down the promise is what
+exposes where we do not keep it.
+
+### Added
+
+- **Command tiers, named and published** (C4-6). Every command now carries one of four tiers —
+  `core`, `supported`, `experimental`, `parked` — from a single authority (`cli.COMMAND_TIERS`),
+  rendered by `ask --help`, the README command table and the user guide.
+  - A tier is a **stability promise**: `core` is safe to gate CI on, `experimental` may change
+    shape in a minor, `parked` still works but is no longer developed (empty today, and the help
+    says so rather than leaving the row blank).
+  - It is **not a value ranking** — `posture` is experimental *and* the first command the help
+    recommends — and it is **not the pricing tier**, which gates repository size and never
+    capability. Both distinctions are printed, not implied.
+  - The battery fails if a registered command sits in no tier, if a tier names a command that
+    does not exist, if a command calls itself `[EXPERIMENTAL]` while published in another tier,
+    or if either document drifts from the table.
+  - Which commands *move* between tiers, and whether `parked` disappears from the default help,
+    is the tiering work in M9. This release names the vocabulary before it is used against a
+    command.
+- **The cache model is published, per command, and measured.** `ask cache model` (`--json`,
+  `--markdown`) and [docs/CACHE.md](docs/CACHE.md) answer the question field evaluation #3 could
+  not: *which of my commands does a warm actually help?* One rule for invalidation — every layer
+  keys on the exact tree state — then, per command, whether a warm gives it **the answer**, only
+  **the shared work**, or **nothing**, with the layers it reads and a measured figure.
+  - Which layers each command reads was derived by instrumenting the layers, not by reading the
+    code and hoping. What a warm is worth was then timed **per command in isolation**: cleared
+    caches, `cache warm`, then the command. Timed in a batch instead, one command warms the next
+    and the table lies — `impact-chain` looked unaffected by a warm in a batch and goes 9.9 s →
+    1.7 s in isolation.
+  - Two measured results contradict the obvious assumption and are published as such: a warm
+    buys **`endpoints` nothing** (2.8 s → 2.9 s) and **`migrate-check` nothing** (4.8 s → 4.8 s),
+    and on a small diff it makes `review-pr` *slower* (1.1 s → 2.3 s) because loading the warmed
+    IR costs more than the work it saves.
+  - The battery fails if a registered command has no row, if the model names a command that does
+    not exist, if a row claims a warm helps while reading no layer a warm builds, or if
+    `docs/CACHE.md` has drifted from the registry. This is the `--help` lesson (C4-1) applied: a
+    curated list beside a generated one drifts.
+- **`cache warm` states its cost and its limits when it finishes** (C4-5): elapsed time, what it
+  warmed, what it did **not** — `prepare-context` task answers, runs whose analysis flags differ,
+  and the two commands measured to gain nothing — plus the line that matters in CI: without a
+  persisted `~/.sourcecode`, every pipeline pays that time again. `cache warm --help` says it
+  before the run, not after.
+
+### Fixed
+
+- **One authority for cache freshness: the tree state, never the committed HEAD.** The
+  snapshot cache behind the root command keyed on the HEAD sha alone, so it answered for a
+  tree it had not read. Reproduced on spring-petclinic: add `spring-boot-starter-data-ldap`
+  to a tracked `pom.xml`, do not commit, run `ask --compact` again — the pre-edit analysis
+  comes back from `L2_view` with `is_stale: false`, the new dependency invisible. The context
+  cache sitting next to it keyed on the exact tree and invalidated correctly, which is why
+  field evaluation #3 could only describe the behaviour as *"el modelo de invalidación no
+  está documentado y no es predecible"*: there were two models.
+  - `cache.worktree_signature` is now the single authority every layer keys on — the root
+    command's L1/L2 snapshots, the `prepare-context` task cache, the shared Canonical IR, and
+    the RIS bootstrap. One rule describes all of them: **any change to the analysed files
+    invalidates, committed or not.** A clean tree keys on the sha, so the ordinary repeat run
+    still hits (BroadleafCommerce: 18.1 s cold → 0.3 s warm, unchanged; the signature itself
+    costs ~50 ms on that tree, ~140 ms on keycloak).
+  - Untracked files are covered by size and mtime: they appear in no diff, so a new file — or
+    an edit to one — was invisible to a signature built from `git diff` alone.
+  - A tree git cannot describe (no repository, no commit) gets a fingerprint over the size and
+    mtime of every non-ignored file. Before, such trees used a **constant** key, so the cache
+    answered forever with the first analysis it ever ran; the context cache disabled itself
+    instead. Both now cache and both now invalidate.
+  - `--scope`-style subdirectory runs sign only their own subtree: an edit in a sibling module
+    no longer invalidates the module actually analysed.
+- **RIS staleness answers the question it is asked.** `get_cold_start_context` reported
+  `stale: false` for any tree sharing the commit the snapshot was taken at, while carrying
+  `has_uncommitted_changes: true` in the same object — two facts about one thing, disagreeing.
+  The snapshot now records the tree it describes (`metadata.tree_signature`), and the
+  `prepare-context` RIS fast path serves `onboard`/`explain` only when that tree is still the
+  one on disk. Snapshots written before this release fall back to the old pair of facts.
+- **`prepare-context --all` and `--include-config` are in the cache key.** They changed the
+  answer and were not keyed; the collision could not surface only because the key demanded a
+  git sha, and non-git trees cached nothing at all. Now that every tree has a signature, an
+  unkeyed flag would be served the other flag's answer.
+
 ## [3.2.1] — 2026-07-29
 
 **M7 complete — the last four seams, the fact registry, and a `--help` that leads with the

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 3.2.1
+Version: 3.2.2
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -74,13 +74,17 @@ Cache keyed on content hashes — invalidated only when source changes. On repea
 At 0.3s per call, ASK Engine becomes **constant infrastructure** inside agent loops — call it before every edit, every PR review, every test run, without batching or caching manually.
 
 **What a warm actually covers.** `ask cache warm` runs the compact analysis: it rebuilds the
-shared structural layers (L1/L2 + the Repository Intelligence Snapshot) and the **compact
-view**. Pass `--agent` to warm the agent view as well. Deeper projections are separate view
-keys and are *not* covered by either — `--full`, `--env-map` and a raised `--depth` recompute
-on first use, as do most `prepare-context` tasks. Measured on a 3,342-file Spring monolith:
-`cache warm` 103s → `--compact --git-context` 1s (hit), but `--agent --full --env-map
---depth 20` still 171s (miss). Budget the deep run explicitly in CI, or warm exactly the view
-your pipeline consumes. Full model: [USER_GUIDE.md#caching](docs/USER_GUIDE.md#caching).
+shared structural layers (L1/L2 + the Repository Intelligence Snapshot + the shared Canonical
+IR) and the **compact view**. Pass `--agent` to warm the agent view as well. Deeper projections
+are separate keys and are *not* covered by either — `--full`, `--env-map` and a raised `--depth`
+recompute on first use, as do most `prepare-context` tasks. Measured on a 3,342-file Spring
+monolith: `cache warm` 103s → `--compact --git-context` 1s (hit), but `--agent --full --env-map
+--depth 20` still 171s (miss).
+
+**One rule for invalidation, and a table that names every command.** Every layer keys on the
+exact tree state: any change to the analysed files invalidates it, committed or not. Which of
+*your* commands a warm helps — the answer, only the shared work, or nothing — is published per
+command: `ask cache model`, or [docs/CACHE.md](docs/CACHE.md).
 
 ---
 
@@ -200,38 +204,58 @@ The everyday loop: diff-based PR review, symptom-driven bug triage, and delta co
 → [reference](docs/USER_GUIDE.md#typical-workflows)
 
 ### 7 · Utilities
-`ask rename-class` (word-boundary Java rename) · `ask chunk-file` (split large files for agents) · `ask cache` (status / warm / clear / freshness)
+`ask rename-class` (word-boundary Java rename) · `ask chunk-file` (split large files for agents) · `ask cache` (status / warm / model / clear / freshness)
 → [reference](docs/USER_GUIDE.md)
 
 ---
 
+## Command tiers
+
+A tier says **what an output is worth relying on** — it is a stability promise, not a value
+ranking, and not the [pricing tier](docs/PRODUCT_TIERS.md) (Free/Pro gates repository size,
+never capability). `posture` is the most differentiated command in the product *and* it is
+experimental: both are true, and they are two different facts.
+
+| Tier | Promise | Commands |
+|---|---|---|
+| **core** | contract stable within a major — safe to gate CI on | `endpoints` · `spring-audit` · `migrate-check` · `impact` · `impact-chain` · `pr-impact` · `verify` |
+| **supported** | maintained; fields are added, never removed without a major | every command not named in another row |
+| **experimental** | shape may change in a minor — do not gate CI on it | `posture` · `archetype` · `retrieve` |
+| **parked** | kept working, no longer developed | none today |
+
+The same table is printed by `ask --help`, and both are generated from one authority
+(`cli.COMMAND_TIERS`) — the battery fails if a command is in no tier, or if this file drifts
+from it.
+
+---
+
 ## Every command, in one table
 
 *`ask --help` shows a short header; this is the full surface. If you only read one row, read
 `posture`.*
 
-| Command | Answers | Note |
-|---|---|---|
-| `posture` | which beans a profile set wires, and how effective endpoint access differs between two sets | **experimental**, most differentiated |
-| `endpoints` | every REST endpoint, effective path, security policy, confidence | Spring MVC + JAX-RS (~65 % recall on JAX-RS sub-resource locators) |
-| `spring-audit` | transactional anomalies + security surface + validation gaps | `--ci`, `-f github-comment` |
-| `migrate-check` | Boot 2→3 readiness: located blockers, per-dimension score, effort | `--blast-radius` orders the re-test plan |
-| `impact` / `impact-chain` | blast radius of a change, to the endpoints it reaches | target the **interface**, not the `Impl` |
-| `pr-impact` | the same, scoped to a PR diff | gating command: `--fail-on`, exit codes |
-| `verify` | does the repo satisfy its declared contracts, **relative to a baseline** | `.ask/contracts.yml`; exit 0/1/2 |
-| `verify-edit` | did the working-tree edits change runtime behaviour | semantic diff gate for the edit loop |
-| `--compact` / `--agent` | bounded structural context for an agent | `--compact` is the token-cheap one |
-| `onboard` / `explain` / `cold-start` | orientation in an unfamiliar repo; per-class summary; bootstrap snapshot | |
-| `export` / `repo-ir` / `schema` | tool-agnostic views (C4, module graph, integrations); symbol-level IR; published JSON Schemas | |
-| `modernize` | coupling hubs, cycles, dead zones, refactor candidates | |
-| `review-pr` / `fix-bug` / `prepare-context` | diff review, symptom triage, task-shaped context | |
-| `plan` / `compare` / `delta` / `contract-diff` | what to review for a change; candidates by measured cost; outcome of a change; public-contract break | no verdicts, measured cost only |
-| `validation` | request-body validation coverage and gaps | |
-| `baseline capture\|diff\|trend` | versioned architectural metrics over time | trend reporting, not gating |
-| `retrieve` | typed knowledge queries over the model | **experimental** |
-| `archetype` | evidence-based architectural archetype | **experimental** |
-| `rename-class` / `chunk-file` | word-boundary Java rename; split a large file for an agent | |
-| `cache status\|warm\|clear` · `auth` · `telemetry` · `mcp` · `config` · `version` | housekeeping | |
+| Command | Tier | Answers | Note |
+|---|---|---|---|
+| `posture` | experimental | which beans a profile set wires, and how effective endpoint access differs between two sets | the most differentiated capability here |
+| `endpoints` | core | every REST endpoint, effective path, security policy, confidence | Spring MVC + JAX-RS (~65 % recall on JAX-RS sub-resource locators) |
+| `spring-audit` | core | transactional anomalies + security surface + validation gaps | `--ci`, `-f github-comment` |
+| `migrate-check` | core | Boot 2→3 readiness: located blockers, per-dimension score, effort | `--blast-radius` orders the re-test plan |
+| `impact` / `impact-chain` | core | blast radius of a change, to the endpoints it reaches | target the **interface**, not the `Impl` |
+| `pr-impact` | core | the same, scoped to a PR diff | gating command: `--fail-on`, exit codes |
+| `verify` | core | does the repo satisfy its declared contracts, **relative to a baseline** | `.ask/contracts.yml`; exit 0/1/2 |
+| `verify-edit` | supported | did the working-tree edits change runtime behaviour | semantic diff gate for the edit loop |
+| `--compact` / `--agent` | — | bounded structural context for an agent | flags of the root command, not commands: not tiered |
+| `onboard` / `explain` / `cold-start` | supported | orientation in an unfamiliar repo; per-class summary; bootstrap snapshot | |
+| `export` / `repo-ir` / `schema` | supported | tool-agnostic views (C4, module graph, integrations); symbol-level IR; published JSON Schemas | |
+| `modernize` | supported | coupling hubs, cycles, dead zones, refactor candidates | |
+| `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 |
+| `retrieve` | experimental | typed knowledge queries over the model | |
+| `archetype` | experimental | evidence-based architectural archetype | |
+| `rename-class` / `chunk-file` | supported | word-boundary Java rename; split a large file for an agent | |
+| `cache status\|warm\|model\|clear` · `auth` · `telemetry` · `mcp` · `config` · `version` | supported | housekeeping | `activate` too |
 
 ---
 
@@ -287,18 +311,18 @@ Full breakdown: [docs/PRODUCT_TIERS.md](docs/PRODUCT_TIERS.md).
 
 ```bash
 ask config              # version, config file path, telemetry status
-ask telemetry disable   # anonymous telemetry is on by default (opt-out)
+ask telemetry enable    # anonymous telemetry is OFF by default (opt-in)
 ```
 
-Telemetry collects version, OS, commands, flags, duration, repo-size range, and errors —
-**no source code, paths, secrets, or output**. Disable any time with
-`export SOURCECODE_TELEMETRY=0` (or `DO_NOT_TRACK=1`). It defaults to **off in CI**.
+**Nothing is collected or transmitted unless you turn telemetry on** — not on the first run,
+not in CI. If you do opt in, it collects version, OS, commands, flags, duration, repo-size
+range, and errors: **no source code, paths, secrets, or output**. Turn it off again with
+`ask telemetry disable`, `export SOURCECODE_TELEMETRY=0`, or `DO_NOT_TRACK=1`.
 
-> **Auditing someone else's code — regulated, client-owned or public-sector?** Turn it off
-> *before* the first run, not after: `SOURCECODE_TELEMETRY=0 ask …`, or `ask telemetry disable`
-> once (remembered). The default is opt-out today; **moving it to opt-in is on the roadmap**
-> (`docs/DEFECT-LEDGER.md` P-1) precisely because a default you must remember to disable is the
-> wrong default for third-party code.
+> **Auditing someone else's code — regulated, client-owned or public-sector?** Nothing to do.
+> Telemetry was opt-out until 3.3.0; it is opt-in now (`docs/DEFECT-LEDGER.md` P-1), because a
+> default you must remember to disable is the wrong default for third-party code. An explicit
+> choice you made before is unchanged.
 
 **Custom security annotations.** Teach `endpoints`, `spring-audit`, and `explain` about
 project-specific authorization annotations via an optional `sourcecode.config.json` at the

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

@@ -36,13 +36,17 @@ Cache keyed on content hashes — invalidated only when source changes. On repea
 At 0.3s per call, ASK Engine becomes **constant infrastructure** inside agent loops — call it before every edit, every PR review, every test run, without batching or caching manually.
 
 **What a warm actually covers.** `ask cache warm` runs the compact analysis: it rebuilds the
-shared structural layers (L1/L2 + the Repository Intelligence Snapshot) and the **compact
-view**. Pass `--agent` to warm the agent view as well. Deeper projections are separate view
-keys and are *not* covered by either — `--full`, `--env-map` and a raised `--depth` recompute
-on first use, as do most `prepare-context` tasks. Measured on a 3,342-file Spring monolith:
-`cache warm` 103s → `--compact --git-context` 1s (hit), but `--agent --full --env-map
---depth 20` still 171s (miss). Budget the deep run explicitly in CI, or warm exactly the view
-your pipeline consumes. Full model: [USER_GUIDE.md#caching](docs/USER_GUIDE.md#caching).
+shared structural layers (L1/L2 + the Repository Intelligence Snapshot + the shared Canonical
+IR) and the **compact view**. Pass `--agent` to warm the agent view as well. Deeper projections
+are separate keys and are *not* covered by either — `--full`, `--env-map` and a raised `--depth`
+recompute on first use, as do most `prepare-context` tasks. Measured on a 3,342-file Spring
+monolith: `cache warm` 103s → `--compact --git-context` 1s (hit), but `--agent --full --env-map
+--depth 20` still 171s (miss).
+
+**One rule for invalidation, and a table that names every command.** Every layer keys on the
+exact tree state: any change to the analysed files invalidates it, committed or not. Which of
+*your* commands a warm helps — the answer, only the shared work, or nothing — is published per
+command: `ask cache model`, or [docs/CACHE.md](docs/CACHE.md).
 
 ---
 
@@ -162,38 +166,58 @@ The everyday loop: diff-based PR review, symptom-driven bug triage, and delta co
 → [reference](docs/USER_GUIDE.md#typical-workflows)
 
 ### 7 · Utilities
-`ask rename-class` (word-boundary Java rename) · `ask chunk-file` (split large files for agents) · `ask cache` (status / warm / clear / freshness)
+`ask rename-class` (word-boundary Java rename) · `ask chunk-file` (split large files for agents) · `ask cache` (status / warm / model / clear / freshness)
 → [reference](docs/USER_GUIDE.md)
 
 ---
 
+## Command tiers
+
+A tier says **what an output is worth relying on** — it is a stability promise, not a value
+ranking, and not the [pricing tier](docs/PRODUCT_TIERS.md) (Free/Pro gates repository size,
+never capability). `posture` is the most differentiated command in the product *and* it is
+experimental: both are true, and they are two different facts.
+
+| Tier | Promise | Commands |
+|---|---|---|
+| **core** | contract stable within a major — safe to gate CI on | `endpoints` · `spring-audit` · `migrate-check` · `impact` · `impact-chain` · `pr-impact` · `verify` |
+| **supported** | maintained; fields are added, never removed without a major | every command not named in another row |
+| **experimental** | shape may change in a minor — do not gate CI on it | `posture` · `archetype` · `retrieve` |
+| **parked** | kept working, no longer developed | none today |
+
+The same table is printed by `ask --help`, and both are generated from one authority
+(`cli.COMMAND_TIERS`) — the battery fails if a command is in no tier, or if this file drifts
+from it.
+
+---
+
 ## Every command, in one table
 
 *`ask --help` shows a short header; this is the full surface. If you only read one row, read
 `posture`.*
 
-| Command | Answers | Note |
-|---|---|---|
-| `posture` | which beans a profile set wires, and how effective endpoint access differs between two sets | **experimental**, most differentiated |
-| `endpoints` | every REST endpoint, effective path, security policy, confidence | Spring MVC + JAX-RS (~65 % recall on JAX-RS sub-resource locators) |
-| `spring-audit` | transactional anomalies + security surface + validation gaps | `--ci`, `-f github-comment` |
-| `migrate-check` | Boot 2→3 readiness: located blockers, per-dimension score, effort | `--blast-radius` orders the re-test plan |
-| `impact` / `impact-chain` | blast radius of a change, to the endpoints it reaches | target the **interface**, not the `Impl` |
-| `pr-impact` | the same, scoped to a PR diff | gating command: `--fail-on`, exit codes |
-| `verify` | does the repo satisfy its declared contracts, **relative to a baseline** | `.ask/contracts.yml`; exit 0/1/2 |
-| `verify-edit` | did the working-tree edits change runtime behaviour | semantic diff gate for the edit loop |
-| `--compact` / `--agent` | bounded structural context for an agent | `--compact` is the token-cheap one |
-| `onboard` / `explain` / `cold-start` | orientation in an unfamiliar repo; per-class summary; bootstrap snapshot | |
-| `export` / `repo-ir` / `schema` | tool-agnostic views (C4, module graph, integrations); symbol-level IR; published JSON Schemas | |
-| `modernize` | coupling hubs, cycles, dead zones, refactor candidates | |
-| `review-pr` / `fix-bug` / `prepare-context` | diff review, symptom triage, task-shaped context | |
-| `plan` / `compare` / `delta` / `contract-diff` | what to review for a change; candidates by measured cost; outcome of a change; public-contract break | no verdicts, measured cost only |
-| `validation` | request-body validation coverage and gaps | |
-| `baseline capture\|diff\|trend` | versioned architectural metrics over time | trend reporting, not gating |
-| `retrieve` | typed knowledge queries over the model | **experimental** |
-| `archetype` | evidence-based architectural archetype | **experimental** |
-| `rename-class` / `chunk-file` | word-boundary Java rename; split a large file for an agent | |
-| `cache status\|warm\|clear` · `auth` · `telemetry` · `mcp` · `config` · `version` | housekeeping | |
+| Command | Tier | Answers | Note |
+|---|---|---|---|
+| `posture` | experimental | which beans a profile set wires, and how effective endpoint access differs between two sets | the most differentiated capability here |
+| `endpoints` | core | every REST endpoint, effective path, security policy, confidence | Spring MVC + JAX-RS (~65 % recall on JAX-RS sub-resource locators) |
+| `spring-audit` | core | transactional anomalies + security surface + validation gaps | `--ci`, `-f github-comment` |
+| `migrate-check` | core | Boot 2→3 readiness: located blockers, per-dimension score, effort | `--blast-radius` orders the re-test plan |
+| `impact` / `impact-chain` | core | blast radius of a change, to the endpoints it reaches | target the **interface**, not the `Impl` |
+| `pr-impact` | core | the same, scoped to a PR diff | gating command: `--fail-on`, exit codes |
+| `verify` | core | does the repo satisfy its declared contracts, **relative to a baseline** | `.ask/contracts.yml`; exit 0/1/2 |
+| `verify-edit` | supported | did the working-tree edits change runtime behaviour | semantic diff gate for the edit loop |
+| `--compact` / `--agent` | — | bounded structural context for an agent | flags of the root command, not commands: not tiered |
+| `onboard` / `explain` / `cold-start` | supported | orientation in an unfamiliar repo; per-class summary; bootstrap snapshot | |
+| `export` / `repo-ir` / `schema` | supported | tool-agnostic views (C4, module graph, integrations); symbol-level IR; published JSON Schemas | |
+| `modernize` | supported | coupling hubs, cycles, dead zones, refactor candidates | |
+| `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 |
+| `retrieve` | experimental | typed knowledge queries over the model | |
+| `archetype` | experimental | evidence-based architectural archetype | |
+| `rename-class` / `chunk-file` | supported | word-boundary Java rename; split a large file for an agent | |
+| `cache status\|warm\|model\|clear` · `auth` · `telemetry` · `mcp` · `config` · `version` | supported | housekeeping | `activate` too |
 
 ---
 
@@ -249,18 +273,18 @@ Full breakdown: [docs/PRODUCT_TIERS.md](docs/PRODUCT_TIERS.md).
 
 ```bash
 ask config              # version, config file path, telemetry status
-ask telemetry disable   # anonymous telemetry is on by default (opt-out)
+ask telemetry enable    # anonymous telemetry is OFF by default (opt-in)
 ```
 
-Telemetry collects version, OS, commands, flags, duration, repo-size range, and errors —
-**no source code, paths, secrets, or output**. Disable any time with
-`export SOURCECODE_TELEMETRY=0` (or `DO_NOT_TRACK=1`). It defaults to **off in CI**.
+**Nothing is collected or transmitted unless you turn telemetry on** — not on the first run,
+not in CI. If you do opt in, it collects version, OS, commands, flags, duration, repo-size
+range, and errors: **no source code, paths, secrets, or output**. Turn it off again with
+`ask telemetry disable`, `export SOURCECODE_TELEMETRY=0`, or `DO_NOT_TRACK=1`.
 
-> **Auditing someone else's code — regulated, client-owned or public-sector?** Turn it off
-> *before* the first run, not after: `SOURCECODE_TELEMETRY=0 ask …`, or `ask telemetry disable`
-> once (remembered). The default is opt-out today; **moving it to opt-in is on the roadmap**
-> (`docs/DEFECT-LEDGER.md` P-1) precisely because a default you must remember to disable is the
-> wrong default for third-party code.
+> **Auditing someone else's code — regulated, client-owned or public-sector?** Nothing to do.
+> Telemetry was opt-out until 3.3.0; it is opt-in now (`docs/DEFECT-LEDGER.md` P-1), because a
+> default you must remember to disable is the wrong default for third-party code. An explicit
+> choice you made before is unchanged.
 
 **Custom security annotations.** Teach `endpoints`, `spring-audit`, and `explain` about
 project-specific authorization annotations via an optional `sourcecode.config.json` at the

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

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

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

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

{sourcecode-3.2.1 → sourcecode-3.2.2}/src/sourcecode/cache.py

@@ -178,6 +178,110 @@ def _get_git_head(repo_root: Path) -> str:
     return ""
 
 
+#: Directories never read as source, so their contents cannot change an answer.
+#: Used only by the non-git fingerprint below (git ignores them by .gitignore).
+_SIG_SKIP_DIRS: frozenset[str] = frozenset({
+    ".git", ".hg", ".svn", "target", "build", "out", "dist", "bin",
+    "node_modules", ".gradle", ".idea", ".vscode", "__pycache__", ".venv",
+    "venv", ".sourcecode-cache", ".mypy_cache", ".pytest_cache",
+})
+
+
+def _untracked_tree_fingerprint(target: Path) -> str:
+    """Fingerprint of a tree git cannot describe (no repository, or no commit).
+
+    Hashes ``(relative path, size, mtime_ns)`` of every non-ignored file. It is a
+    fingerprint of the tree, not of a commit — which is the point: without it the
+    key for a non-git tree is constant, and the cache answers forever with the
+    first analysis it ever ran.
+    """
+    h = hashlib.sha256()
+    try:
+        root = Path(target).resolve()
+        for dirpath, dirnames, filenames in os.walk(root):
+            dirnames[:] = sorted(d for d in dirnames if d not in _SIG_SKIP_DIRS)
+            for name in sorted(filenames):
+                p = Path(dirpath) / name
+                try:
+                    st = p.stat()
+                except OSError:
+                    continue
+                h.update(str(p.relative_to(root)).encode("utf-8", "replace"))
+                h.update(f"\x00{st.st_size}\x00{st.st_mtime_ns}\x00".encode())
+    except Exception:
+        return ""
+    return f"ff{h.hexdigest()[:14]}"
+
+
+def worktree_signature(repo_root: Path, scope: Optional[Path] = None) -> str:
+    """Hex fingerprint of the **exact tree state an analysis would read**.
+
+    This is the single authority for cache freshness (ADR-0008): every layer that
+    stores an answer about the tree keys on this, so one rule describes them all —
+    *any change to the analysed files invalidates, committed or not*. Keying on the
+    committed HEAD alone made the root command serve an answer for a tree it had
+    not read: a dependency added to an uncommitted ``pom.xml`` stayed invisible
+    while the payload reported ``is_stale: false``.
+
+    Clean tree → the HEAD sha, so repeated runs hit. Dirty tree → HEAD plus a hash
+    of the porcelain status, the diff against HEAD, and the size/mtime of untracked
+    files (whose bytes the diff does not carry). *scope* restricts the status and
+    the diff to a subdirectory, so an edit in a sibling module does not invalidate
+    the module actually analysed.
+
+    Returns hex only — cache file names embed it and the GC parses them. Empty
+    string when the tree cannot be described at all; callers then skip the cache.
+    """
+    root = Path(repo_root)
+    head = _get_git_head(root)
+    if not head:
+        return _untracked_tree_fingerprint(scope if scope is not None else root)
+
+    pathspec: list[str] = []
+    try:
+        if scope is not None and Path(scope).resolve() != root.resolve():
+            pathspec = ["--", str(Path(scope).resolve())]
+    except Exception:
+        pathspec = []
+
+    try:
+        st = subprocess.run(
+            ["git", "-C", str(root), "status", "--porcelain", *pathspec],
+            capture_output=True, text=True, timeout=10,
+        )
+        porcelain = st.stdout if st.returncode == 0 else ""
+    except Exception:
+        porcelain = ""
+    if not porcelain.strip():
+        return head  # clean — HEAD fully describes the tree
+
+    try:
+        df = subprocess.run(
+            ["git", "-C", str(root), "diff", "HEAD", *pathspec],
+            capture_output=True, text=True, timeout=20,
+        )
+        diff_txt = df.stdout if df.returncode == 0 else ""
+    except Exception:
+        diff_txt = ""
+
+    h = hashlib.sha256()
+    h.update(porcelain.encode("utf-8", "replace"))
+    h.update(b"\x00")
+    h.update(diff_txt.encode("utf-8", "replace"))
+    # Untracked files appear in the porcelain by name only; their bytes are in no
+    # diff, so an edit to one would be invisible without their stat.
+    for line in porcelain.splitlines():
+        if not line.startswith("?? "):
+            continue
+        try:
+            p = root / line[3:].strip().strip('"')
+            st_u = p.stat()
+            h.update(f"\x00{line[3:]}\x00{st_u.st_size}\x00{st_u.st_mtime_ns}".encode("utf-8", "replace"))
+        except OSError:
+            continue
+    return f"{head}d{h.hexdigest()[:12]}"
+
+
 # ---------------------------------------------------------------------------
 # Public API — location helpers
 # ---------------------------------------------------------------------------