sourcecode 5.8.14__tar.gz → 5.8.16__tar.gz

{sourcecode-5.8.14 → sourcecode-5.8.16}/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## [5.8.16] — 2026-08-20
+
+*Post-audit correction release with cache and compact-output hardening.*
+
+### Fixed
+- `cold-start --compact` now preserves its immutable identity contract even when
+  no Repository Intelligence Snapshot exists; unknown identity fields remain
+  explicit instead of being silently omitted.
+- Dependency manifest cache keys now include `requirements.txt` and
+  `requirements-dev.txt`, preventing stale empty results after Python dependency
+  manifests are added or changed.
+
+### Verified
+- ASK exercised against all 36 repositories under `documents/workspace/testing`
+  across context, endpoint inventory and migration-check workflows: 108/108 runs
+  returned valid JSON with exit code 0.
+- Focused regression coverage for compact identity, RIS, manifest caching and the
+  prior correction battery passes.
+
+## [5.8.15] — 2026-08-20
+
+*Correction battery release based on the fifth 5.8.14 audit.*
+
+### Fixed
+- Labelled `data-exposure` runs reuse the shared CIR without changing the no-label fast path.
+- `onboard` and `archetype` publish explicit source-file population units and totals.
+- `risk` help, tier metadata and user documentation consistently describe the command as supported.
+- SEC-009 keeps its contextual `medium` calibration, pinned by a regression and active/profile evidence.
+- `migrate-apply` is now present in help, progress, path-admission, output-purity,
+  cache and schema contracts.
+- Endpoint inventories disclose excluded test modules while preserving test-fixture
+  routes as a separately scoped population.
+- `posture --compact` preserves complete counts while bounding unresolved bodies;
+  `cold-start` remains a bounded RIS projection.
+
+### Verified
+- Six-run steady `risk` on Broadleaf converged at 6.56s with a clean interleaved control.
+- BUG-1 and BUG-2 were not reproduced locally; external reproduction remains required before closure.
+- Dirty-tree `verify-edit` and readonly/mutation controls pass locally; external F05 coverage remains open.
+
+### Pending
+- Portable cross-host cost-anchor recalibration and external confirmation of `data-exposure --config`.
+
 ## [5.8.14] — 2026-08-20
 
 *Fourth-audit remediation release. The external `5.8.13` audit subject remains
@@ -19,6 +62,10 @@ the evidence for outstanding field reproduction and performance work.*
 - `risk` now publishes its composition working set: source files, audit findings,
   candidate defects and composed defects. This instruments the rare field-scale
   zero-output report without claiming it is closed before reproduction.
+- BC-004 declares the 5.8.14 removal of core/supported payload fields, including
+  `migrate-check.findings[].imports_found` and the MyBatis DTO mapper fields;
+  consumers should use the replacements listed by `ask schema
+  breaking-changes-v1` before upgrading.
 - The roadmap and defect ledger distinguish these shipped changes from the two
   remaining field-gated items: `risk` output reproduction and controlled
   `data-exposure --config` performance measurement.

{sourcecode-5.8.14 → sourcecode-5.8.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.8.14
+Version: 5.8.16
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 Project-URL: Homepage, https://github.com/HarounDominique/sourcecode
 Project-URL: Repository, https://github.com/HarounDominique/sourcecode
@@ -49,7 +49,13 @@ Description-Content-Type: text/markdown
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-5.8.14-blue)
+> **First run.** From the repository you want to inspect, run `ask --help` and then
+> `ask . --compact`. Use `ask endpoints .`, `ask spring-audit .`,
+> `ask migrate-check . --compact`, or `ask impact <Interface> .` for a specific
+> question. All analysis is local and deterministic; see [Privacy](#configuration--privacy)
+> before inspecting a repository whose telemetry policy you need to control.
+
+![Version](https://img.shields.io/badge/version-5.8.16-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 Copyright (c) 2026 Dominique Haroun. All rights reserved. ASK Engine 5.7.0 and
@@ -119,12 +125,14 @@ stops at 1 408 files and ends at 5.1s. Commands outside that phase-runner set
 must not be gated on this variable; their budget applicability remains visible in
 the [defect ledger](docs/DEFECT-LEDGER.md).
 
-**Current performance status.** In 5.8.12, `validation` reuses the shared
-Canonical IR and `data-exposure` reuses one semantic model across all declared
-label seeds. On the local BroadleafCommerce corpus, the final fingerprint filled
-the shared CIR in 10.46s and a warm `validation --compact` run took 4.01s with
-byte-identical output. This is a same-host cache observation, not a replacement
-for the controlled `saint-server` cross-version comparison still tracked in the
+**Current performance status.** Release 5.8.16 retains the shared Canonical IR
+path used by `validation` and now passes that same CIR into labelled `data-exposure`
+runs; the no-label path remains parse-free. The one-model-per-declared-label path is
+also retained. These are implementation properties, not duration promises:
+run `ask cache model <repo>` to see which command benefits from a warm cache and
+use `--progress stderr` for supervised runs. The external `data-exposure --config`
+remeasurement and portable cost-anchor calibration remain open because measurements
+from different hosts are not interchangeable; see the
 [roadmap](docs/DEVELOPMENT-ROADMAP.md).
 
 **What a warm actually covers.** `ask cache warm` runs the compact analysis: it rebuilds the
@@ -151,7 +159,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.8.14 — and, on a build that has aged,
+ask version                    # ask 5.8.16 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -405,16 +413,18 @@ from it.
 | `enrich` | experimental | another scanner's SARIF findings, ranked by what this repository does with them | `--sarif <log>`; same composition as `risk`, with `--table --rule <id> --band high --top-n 20` for triage |
 | `audit-report` | supported | human audit bundle over existing `risk` + `posture` evidence, optionally signed | includes `evidence_manifest` claim provenance; `--format markdown`; `--sign-key <file>` signs canonical JSON with HMAC-SHA256 |
 | `migrate-recipe` | supported | the migration report as the OpenRewrite recipe that applies it | only recipes a finding named; the manual remainder published beside them; writes nothing without `--write`, and never a runnable command for an empty recipe list |
+| `migrate-apply` | supported | apply a measured recipe without touching the main tree | Maven and Gradle executors; plan by default; `--write` requires clean Git, pinned version and isolated worktree; no automatic commit or merge |
 | `data-exposure` | supported | which routes can carry the data you labelled, and who reaches them | labels declared in `sourcecode.config.json` — never inferred from a name; `signature` and `call_reach` evidence published apart, field-level flow out of scope (NC-008). With nothing declared, `ask data-exposure /path/to/repo` answers `answered: false` and hands back the file, the key and an example to declare — it never reports zero exposed routes |
+| `data-exposure --init` | supported | generate review-only label candidates | writes only `.ask/data-label-candidates-v1.json` with `status: proposed_only`; it never activates labels |
 | `endpoints` | core | every REST endpoint, effective path, security policy, confidence | Spring MVC + JAX-RS (~65 % recall on JAX-RS sub-resource locators). `--compact` answers the exposure census without the rows; `--servlets` lists the servlet-mounted surface as its own population; `--client-usage` says which routes the TS/JS client in this repository actually calls; `--consumer <repo>` (repeatable) joins the routes against consumers in **other** repositories — TypeScript/JS and Java — and turns the census into a surface-reduction plan: open and called (fix now), open and called by nobody (delete rather than guard), and calls this server serves no route for |
-| `spring-audit` | core | transactional anomalies + security configuration/exposure + validation gaps | `--ci`, `-f github-comment`; `--table --rule SEC-008 --top-n 20` for human-scale review. Every run inventories its own rules — `rules_run`, `rules_not_run`, `rules_partially_run`, `rules_run_count`/`rules_total` — so "all of them" is a fact, not an assumption |
-| `migrate-check` | core | Boot 2→3 readiness + Java LTS/licensing inventory: located blockers, per-dimension score, effort, detected Java 8/11/17/21/25 evidence and explicit licensing-review signals | `--target-jdk 25` sets the target LTS route; `--blast-radius` orders the re-test plan; `--table --rule MIG-001 --band critical --top-n 20` for blocker triage |
+| `spring-audit` | core | transactional anomalies + security configuration/exposure + validation gaps | `--ci`, `-f github-comment`, or `-f github-actions` for native CI annotations; `--table --rule SEC-008 --top-n 20` for human-scale review. Every run inventories its own rules — `rules_run`, `rules_not_run`, `rules_partially_run`, `rules_run_count`/`rules_total` — so "all of them" is a fact, not an assumption |
+| `migrate-check` | core | Boot 2→3 readiness + Java LTS/licensing inventory: located blockers, per-dimension score, effort, detected Java 8/11/17/21/25 evidence and explicit licensing-review signals | `--target-jdk 25` sets the target LTS route; `--blast-radius` orders the re-test plan; `--format github-actions` emits a stable CI annotation; `--table --rule MIG-001 --band critical --top-n 20` for blocker triage |
 | `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. `.ask/waivers.yml` adjudicates a finding as *not a defect here* (stable id + required reason, optional expiry) so a reviewed row stops holding the gate red — a baseline records accepted debt, a waiver says it was never a defect |
+| `pr-impact` | core | the same, scoped to a PR diff | local `git diff HEAD`, `--since REF`, explicit `--files`, or opt-in `--pr NUMBER`; `--format github-actions` emits CI annotations; `--fail-on` gates |
+| `verify` | core | does the repo satisfy its declared contracts, **relative to a baseline** | `.ask/contracts.yml`; `--format github-actions` emits a native CI annotation while preserving exit 0/1/2. `.ask/waivers.yml` adjudicates a finding as *not a defect here* (stable id + required reason, optional expiry) so a reviewed row stops holding the gate red — a baseline records accepted debt, a waiver says it was never a defect |
 | `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 | |
+| `onboard` / `explain` / `cold-start` | supported | orientation in an unfamiliar repo; per-class summary; bootstrap snapshot | `onboard` publishes `population`, `population_unit` and `population_total` for its source-file universe |
 | `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 | |
@@ -426,7 +436,7 @@ from it.
 | `regress` | supported | what moved between two payloads of the same command, and which declaration accounts for it | attributes each delta to a declaration the answers carry (`test_source_excluded`, `symbols_excluded`, `coverage.gaps`, `*_cap`, `waivers`); a delta nothing explains is `unattributed`. Refuses the comparison when `cache_layers`, `base_env` or the analyzer fingerprint differ |
 | `explain-endpoint` | supported | the derivation behind one route's verdict | six steps — match, declaration, handler, chain, profiles, verdict — each naming the authority that produced it and the file it can be checked against; a step that could not be derived is `undetermined` with the reason, never absent |
 | `selftest` | supported | this product's own defect ledger, run against your repository | each ledger row's acceptance criterion as an executable assertion, with the subject (repository, size, platform, entry point) beside every verdict; a row whose precondition the repository does not meet is `not_applicable` with the reason, never a pass |
-| `archetype` | experimental | evidence-based architectural archetype | |
+| `archetype` | experimental | evidence-based architectural archetype | publishes the scanned source-file population explicitly |
 | `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 | `cache model [path]` explains what a warm buys per command; `activate` too |
 
@@ -479,7 +489,9 @@ 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. |
+| **Applying a migration to the main tree.** | ASK never edits the main tree. The explicit `migrate-apply --write` path requires a clean Git tree, a pinned OpenRewrite version, and an isolated branch/worktree; it runs `migrate-check` afterwards, and never commits or merges. | OpenRewrite via `ask migrate-apply . --write --rewrite-version X.Y.Z`; add `--compile` for an optional timed build, then review the retained worktree before merging. |
+
+`migrate-check` does not cover **Applying a migration — nothing here edits source.**
 | **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. `--profile-from <file>` goes one step further and reads the deployment artefact itself, which is where that decision is actually written — still a file, so the process environment still outranks it, and the payload says so. |
 
 
@@ -639,6 +651,7 @@ Matching endpoints report `policy: "custom"` and drop out of the `no_security_si
 | [PRODUCT_TIERS.md](docs/PRODUCT_TIERS.md) | Free vs Pro, pricing model |
 | [DEMO-5MIN.md](docs/DEMO-5MIN.md) | A reproducible 5-minute demo |
 | [MANUAL-USUARIO.md](docs/MANUAL-USUARIO.md) | Guía de usuario en español |
+| [CACHE.md](docs/CACHE.md) | What `cache warm` stores, what it does not, and how cache invalidation works |
 | [PRODUCT_IDENTITY.md](docs/PRODUCT_IDENTITY.md) | `ask` (command) vs `sourcecode` (package/alias) |
 | [privacy.md](docs/privacy.md) | Telemetry and data-handling policy |
 | [DEFECT-LEDGER.md](docs/DEFECT-LEDGER.md) | Every defect found in the field, its class, and which release closed it — published on purpose |

{sourcecode-5.8.14 → sourcecode-5.8.16}/README.md

@@ -4,7 +4,13 @@
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-5.8.14-blue)
+> **First run.** From the repository you want to inspect, run `ask --help` and then
+> `ask . --compact`. Use `ask endpoints .`, `ask spring-audit .`,
+> `ask migrate-check . --compact`, or `ask impact <Interface> .` for a specific
+> question. All analysis is local and deterministic; see [Privacy](#configuration--privacy)
+> before inspecting a repository whose telemetry policy you need to control.
+
+![Version](https://img.shields.io/badge/version-5.8.16-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 Copyright (c) 2026 Dominique Haroun. All rights reserved. ASK Engine 5.7.0 and
@@ -74,12 +80,14 @@ stops at 1 408 files and ends at 5.1s. Commands outside that phase-runner set
 must not be gated on this variable; their budget applicability remains visible in
 the [defect ledger](docs/DEFECT-LEDGER.md).
 
-**Current performance status.** In 5.8.12, `validation` reuses the shared
-Canonical IR and `data-exposure` reuses one semantic model across all declared
-label seeds. On the local BroadleafCommerce corpus, the final fingerprint filled
-the shared CIR in 10.46s and a warm `validation --compact` run took 4.01s with
-byte-identical output. This is a same-host cache observation, not a replacement
-for the controlled `saint-server` cross-version comparison still tracked in the
+**Current performance status.** Release 5.8.16 retains the shared Canonical IR
+path used by `validation` and now passes that same CIR into labelled `data-exposure`
+runs; the no-label path remains parse-free. The one-model-per-declared-label path is
+also retained. These are implementation properties, not duration promises:
+run `ask cache model <repo>` to see which command benefits from a warm cache and
+use `--progress stderr` for supervised runs. The external `data-exposure --config`
+remeasurement and portable cost-anchor calibration remain open because measurements
+from different hosts are not interchangeable; see the
 [roadmap](docs/DEVELOPMENT-ROADMAP.md).
 
 **What a warm actually covers.** `ask cache warm` runs the compact analysis: it rebuilds the
@@ -106,7 +114,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.8.14 — and, on a build that has aged,
+ask version                    # ask 5.8.16 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -360,16 +368,18 @@ from it.
 | `enrich` | experimental | another scanner's SARIF findings, ranked by what this repository does with them | `--sarif <log>`; same composition as `risk`, with `--table --rule <id> --band high --top-n 20` for triage |
 | `audit-report` | supported | human audit bundle over existing `risk` + `posture` evidence, optionally signed | includes `evidence_manifest` claim provenance; `--format markdown`; `--sign-key <file>` signs canonical JSON with HMAC-SHA256 |
 | `migrate-recipe` | supported | the migration report as the OpenRewrite recipe that applies it | only recipes a finding named; the manual remainder published beside them; writes nothing without `--write`, and never a runnable command for an empty recipe list |
+| `migrate-apply` | supported | apply a measured recipe without touching the main tree | Maven and Gradle executors; plan by default; `--write` requires clean Git, pinned version and isolated worktree; no automatic commit or merge |
 | `data-exposure` | supported | which routes can carry the data you labelled, and who reaches them | labels declared in `sourcecode.config.json` — never inferred from a name; `signature` and `call_reach` evidence published apart, field-level flow out of scope (NC-008). With nothing declared, `ask data-exposure /path/to/repo` answers `answered: false` and hands back the file, the key and an example to declare — it never reports zero exposed routes |
+| `data-exposure --init` | supported | generate review-only label candidates | writes only `.ask/data-label-candidates-v1.json` with `status: proposed_only`; it never activates labels |
 | `endpoints` | core | every REST endpoint, effective path, security policy, confidence | Spring MVC + JAX-RS (~65 % recall on JAX-RS sub-resource locators). `--compact` answers the exposure census without the rows; `--servlets` lists the servlet-mounted surface as its own population; `--client-usage` says which routes the TS/JS client in this repository actually calls; `--consumer <repo>` (repeatable) joins the routes against consumers in **other** repositories — TypeScript/JS and Java — and turns the census into a surface-reduction plan: open and called (fix now), open and called by nobody (delete rather than guard), and calls this server serves no route for |
-| `spring-audit` | core | transactional anomalies + security configuration/exposure + validation gaps | `--ci`, `-f github-comment`; `--table --rule SEC-008 --top-n 20` for human-scale review. Every run inventories its own rules — `rules_run`, `rules_not_run`, `rules_partially_run`, `rules_run_count`/`rules_total` — so "all of them" is a fact, not an assumption |
-| `migrate-check` | core | Boot 2→3 readiness + Java LTS/licensing inventory: located blockers, per-dimension score, effort, detected Java 8/11/17/21/25 evidence and explicit licensing-review signals | `--target-jdk 25` sets the target LTS route; `--blast-radius` orders the re-test plan; `--table --rule MIG-001 --band critical --top-n 20` for blocker triage |
+| `spring-audit` | core | transactional anomalies + security configuration/exposure + validation gaps | `--ci`, `-f github-comment`, or `-f github-actions` for native CI annotations; `--table --rule SEC-008 --top-n 20` for human-scale review. Every run inventories its own rules — `rules_run`, `rules_not_run`, `rules_partially_run`, `rules_run_count`/`rules_total` — so "all of them" is a fact, not an assumption |
+| `migrate-check` | core | Boot 2→3 readiness + Java LTS/licensing inventory: located blockers, per-dimension score, effort, detected Java 8/11/17/21/25 evidence and explicit licensing-review signals | `--target-jdk 25` sets the target LTS route; `--blast-radius` orders the re-test plan; `--format github-actions` emits a stable CI annotation; `--table --rule MIG-001 --band critical --top-n 20` for blocker triage |
 | `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. `.ask/waivers.yml` adjudicates a finding as *not a defect here* (stable id + required reason, optional expiry) so a reviewed row stops holding the gate red — a baseline records accepted debt, a waiver says it was never a defect |
+| `pr-impact` | core | the same, scoped to a PR diff | local `git diff HEAD`, `--since REF`, explicit `--files`, or opt-in `--pr NUMBER`; `--format github-actions` emits CI annotations; `--fail-on` gates |
+| `verify` | core | does the repo satisfy its declared contracts, **relative to a baseline** | `.ask/contracts.yml`; `--format github-actions` emits a native CI annotation while preserving exit 0/1/2. `.ask/waivers.yml` adjudicates a finding as *not a defect here* (stable id + required reason, optional expiry) so a reviewed row stops holding the gate red — a baseline records accepted debt, a waiver says it was never a defect |
 | `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 | |
+| `onboard` / `explain` / `cold-start` | supported | orientation in an unfamiliar repo; per-class summary; bootstrap snapshot | `onboard` publishes `population`, `population_unit` and `population_total` for its source-file universe |
 | `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 | |
@@ -381,7 +391,7 @@ from it.
 | `regress` | supported | what moved between two payloads of the same command, and which declaration accounts for it | attributes each delta to a declaration the answers carry (`test_source_excluded`, `symbols_excluded`, `coverage.gaps`, `*_cap`, `waivers`); a delta nothing explains is `unattributed`. Refuses the comparison when `cache_layers`, `base_env` or the analyzer fingerprint differ |
 | `explain-endpoint` | supported | the derivation behind one route's verdict | six steps — match, declaration, handler, chain, profiles, verdict — each naming the authority that produced it and the file it can be checked against; a step that could not be derived is `undetermined` with the reason, never absent |
 | `selftest` | supported | this product's own defect ledger, run against your repository | each ledger row's acceptance criterion as an executable assertion, with the subject (repository, size, platform, entry point) beside every verdict; a row whose precondition the repository does not meet is `not_applicable` with the reason, never a pass |
-| `archetype` | experimental | evidence-based architectural archetype | |
+| `archetype` | experimental | evidence-based architectural archetype | publishes the scanned source-file population explicitly |
 | `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 | `cache model [path]` explains what a warm buys per command; `activate` too |
 
@@ -434,7 +444,9 @@ 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. |
+| **Applying a migration to the main tree.** | ASK never edits the main tree. The explicit `migrate-apply --write` path requires a clean Git tree, a pinned OpenRewrite version, and an isolated branch/worktree; it runs `migrate-check` afterwards, and never commits or merges. | OpenRewrite via `ask migrate-apply . --write --rewrite-version X.Y.Z`; add `--compile` for an optional timed build, then review the retained worktree before merging. |
+
+`migrate-check` does not cover **Applying a migration — nothing here edits source.**
 | **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. `--profile-from <file>` goes one step further and reads the deployment artefact itself, which is where that decision is actually written — still a file, so the process environment still outranks it, and the payload says so. |
 
 
@@ -594,6 +606,7 @@ Matching endpoints report `policy: "custom"` and drop out of the `no_security_si
 | [PRODUCT_TIERS.md](docs/PRODUCT_TIERS.md) | Free vs Pro, pricing model |
 | [DEMO-5MIN.md](docs/DEMO-5MIN.md) | A reproducible 5-minute demo |
 | [MANUAL-USUARIO.md](docs/MANUAL-USUARIO.md) | Guía de usuario en español |
+| [CACHE.md](docs/CACHE.md) | What `cache warm` stores, what it does not, and how cache invalidation works |
 | [PRODUCT_IDENTITY.md](docs/PRODUCT_IDENTITY.md) | `ask` (command) vs `sourcecode` (package/alias) |
 | [privacy.md](docs/privacy.md) | Telemetry and data-handling policy |
 | [DEFECT-LEDGER.md](docs/DEFECT-LEDGER.md) | Every defect found in the field, its class, and which release closed it — published on purpose |

{sourcecode-5.8.14 → sourcecode-5.8.16}/docs/CACHE.md

@@ -11,6 +11,24 @@ Two costs, and the second is the one that hurt: nothing told them which of their
 warm would help. This page is the answer, and it is generated from the same table the CLI
 prints — run `ask cache model` for it in the terminal, `ask cache model --json` in a script.
 
+## Use it first
+
+Before optimising a workflow, ask the model that ships with the installed CLI:
+
+```bash
+ask cache status .       # what this repository already has
+ask cache model .        # whether a warm helps each command
+ask cache warm .         # compact view plus shared structural layers
+ask cache warm . --agent # add the agent view when that is what the workflow reads
+```
+
+`cache warm` is not a general acceleration switch. It warms the compact view and shared
+layers for the exact tree and scope you name. A command may receive the finished answer,
+reuse only shared work, or receive no benefit; `cache model` names which. Any analysed-file
+change, committed or not, creates a different cache identity. In CI, persist the ASK cache
+directory only when the job policy allows it; otherwise budget a cold run and use
+`--progress stderr` to make supervised work observable.
+
 ---
 
 ## One rule for invalidation
@@ -82,6 +100,7 @@ The second anchor is the field one, and it carries its own build for the same re
 | `enrich` | the shared work | not measured on the battery yet — bounded by the `risk` composition, plus reading one JSON file | no | `cir`, `parse` | Runs the same composition as `risk` over the repository, then joins a SARIF log to it. Reading the log is negligible; everything a warm helps with is the repository side, so what it buys is what it buys `risk`. |
 | `audit-report` | the shared work | not measured on the battery yet — bounded by `risk` + `posture`, or by `posture` when `--from-risk` is supplied | no | `cir`, `parse` | Packages `risk` and `posture` evidence. A warm helps the repository side; `--from-risk risk.json` skips risk recomputation entirely and only builds the posture/report projection. |
 | `migrate-recipe` | the shared work | not measured on the battery yet — bounded by `migrate-check` on the same repository (openmrs-core ~2 s) | no | `parse` | Runs the same scan as `migrate-check` and projects its findings into an OpenRewrite recipe, so it buys exactly what a warm buys `migrate-check`: the parse, not the rule pass. |
+| `migrate-apply` | the shared work | not measured on the battery yet — bounded by `migrate-check` plus the optional OpenRewrite execution | no | `parse` | Plan mode reads the same migration findings as `migrate-check`; apply mode then uses an isolated worktree and never mutates the main tree. A warm can remove shared parse work, but it does not cache the generated plan or the optional rewrite/compile execution. |
 | `data-exposure` | the shared work | not measured on the battery yet — one `impact-chain` traversal per declared seed type over a CIR the warm already paid for | no | `cir`, `parse` | Walks the same call reach as `impact-chain` once per declared type and reads the endpoint security surface, both over the shared CIR a warm builds. Cost scales with the number of declared types, not with the size of the label. |
 | `endpoints` | the shared work | 3.3 s → 1.4 s (re-measured on 3.7.0; was 2.8 s → 2.9 s) | no | `ris`, `parse` | 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). |
 | `spring-audit` | the shared work | 8.8 s → 3.7 s | no | `ris`, `parse` | Recomputes every run, but over a parse a warm has already paid for. |

{sourcecode-5.8.14 → sourcecode-5.8.16}/docs/DEFECT-LEDGER.md

@@ -16,16 +16,87 @@ The facts these rows are keyed to are published: `ask schema facts-v1` prints th
 
 ## Current Synchronization
 
-**As of 2026-08-20, release `5.8.14` and the fourth external re-audit:** the audited
-snapshot remains `3dde0376`; the report compares the four audit rounds and scores this one
-**90/100** (75, 80, 78, 90). It exercised 53/61 invocables (87%), ran no application and
-left the repository unchanged. Its 40+ longitudinal functional anchors are unchanged, so
-there is no reported product regression. The `5.8.14` release ships the implementations
-recorded below; they remain distinguished from facts verified on the `5.8.13` subject.
-Only this table declares present state.
+**Latest attached audit of release `5.8.15`:** score **90/100**, coverage **54/62
+invocables (87%)**, byte-identical CIR across six versions, and no longitudinal functional
+regression. A new P1 affects dirty-tree `verify-edit`; BUG-1 is reproduced on the
+Windows/NTFS audit host. The historical `risk` P0 remains open because nine successful
+runs do not disprove two earlier exit-0/no-output failures. Only the sixth-pass section
+below declares present state; older audit rounds remain for traceability.
 
 **Release status:** entries marked “pending `5.8.14`” in their historical wording are
-shipped in `5.8.14`; a re-audit is still required wherever the row says so.
+shipped in `5.8.14`; the correction battery fixes listed above are included in `5.8.15`.
+
+**Current release:** `5.8.16` includes two post-audit corrections: compact cold-start
+identity is preserved for `no_ris`, and manifest-cache keys include Python requirements
+files. The testing-repository hygiene exercise changed no external repository; it
+completed 108/108 read-only workflow runs with valid JSON and exit code 0.
+
+The battery also closed the following reproducible contract defects in `5.8.15`:
+`migrate-apply` is registered across help, progress, path-admission, output-purity,
+cache and schema authorities (`1d00ba2`); endpoint census output distinguishes excluded
+test modules from retained test-fixture routes (`f65336d`, `014dec7`, `1c6cd0b`);
+and compact posture output retains counts while omitting unresolved bodies (`dad5dad`).
+
+The sixth audit supersedes the previous queue where it has stronger evidence: BUG-3 is
+closed in stable-cache regime, BUG-1 is reproduced on the audit host, and BUG-4a is
+partial because `onboard` still has no machine-readable population block.
+
+### Sixth Audit Pass: `5.8.15` / `saint-server` / 2026-08-20
+
+| ID | Severity | Current status | Required direction |
+|---|---|---|---|
+| `BUG-6` / `AUD-588-F02` | P1 | **implemented in working tree** (`26b4ab0`), external clone integration pending: removed security findings now count as changes and both-direction unit coverage passes. | Prove the real `authenticated() -> permitAll()` clone case before release; access opening remains the gate. |
+| `BUG-1` / `AUD-511-R02`, `AUD-589-B02`, `AUD-513-N06` | P1 | **reproduced on Windows/NTFS**: `spring-audit` x1.66, `modernize` x1.67, `migrate-check` x1.90, `cache warm` x2.82 versus 5.8.13; output remains byte-identical. | Profile the target host and isolate the shared slow path; add a cross-host performance guard. |
+| `BUG-3` / `443b345` | P1 | **closed in stable-cache regime**: `data-exposure` is 15.6s median, 7.2s best versus 41–44s historically, with identical output. | Preserve shared-CIR reuse and record host/cache provenance. |
+| `BUG-4a` / `24b4185` | P2 | **implemented in working tree** (`89ee4a5`): the RIS fast path now publishes population/unit/total like the full path. | Validate and reconcile the 6939 versus 6947 scopes/bases before release. |
+| `BUG-2` / `b5acc63` | P0 | **open, hardened**: 4/4 current runs delivered artifacts; historical failures remain unrefuted. | Keep the real subprocess invariant and reproduce historical failure conditions before closure. |
+| `BUG-5` / `AUD-588-B12`, `AUD-588-F03` | P2 | **open**: cost anchors remain stale; `risk` model 77.2s versus ~305s observed, warm 166.7s versus 316s. | Rebuild anchors with host, cache state, version and sample provenance. |
+| `AUD-588-F05` | Validation gap | **partially covered**: dirty-tree `verify-edit` is covered; seven mutating/denied invocables remain. | Finish the clone-based matrix without modifying the original repository. |
+
+### Fifth Audit Pass: `5.8.14` / `saint-server` / 2026-08-20
+
+| ID | Severity | Current status | Required direction |
+|---|---|---|---|
+| `BUG-1` / `AUD-511-R02`, `AUD-589-B02`, `AUD-513-N06` | P1 | **not reproduced locally; external closure pending**: isolated/interleaved controls did not reproduce the reported slowdown. | Repeat the six-run protocol on the audit host and compare 5.8.13/5.8.15 with byte-equivalent output. |
+| `BUG-2` / `AUD-588-B01`, `AUD-589-B01`, `C3-122` | P0 | **open, not reproduced in five runs**: all five current `risk` runs produced exit 0 and a ~311 KB artifact; historical failures remain material. | Keep the real-entry-point output invariant. Treat `b5acc63` and the existing working-set/timing instrumentation as hardening, not field closure. |
+| `BUG-3` / `AUD-511-R02`, `AUD-589-B02`, `AUD-513-N06` | P1 | **implemented in 5.8.15; numeric external remeasurement pending**: labelled runs now reuse shared CIR (`443b345`). | Re-run the controlled external benchmark; do not infer a speedup from a different host. |
+| `BUG-4a` / `AUD-588-B11` residual | P2 | **closed in 5.8.15** (`24b4185`): `onboard` and `archetype` publish explicit source-file population units and totals. | Keep parity tests on both payloads. |
+| `BUG-4b` / `AUD-588-B11` residual | P2 | **closed in 5.8.15** (`0376350`): help, tier table and docs agree that `risk` is supported. | Keep the single `COMMAND_TIERS` authority. |
+| `BUG-4c` / `SEC-009` calibration | P2 / product decision | **by-design in 5.8.15** (`fb7632a`): medium is retained and pinned; active/profile evidence supplies context. | Reopen only with a new product-risk decision, not from the same observation. |
+| `BUG-5` / `AUD-588-B12`, `AUD-588-F03` | P2 | **open, measurement improved but not portable yet**: local six-run `risk` converged at 6.56s (clean control, Broadleaf, 5.8.14); this is not comparable to the historical Windows anchor. | Add a provenance-bearing, cross-host anchor before changing the operational model. |
+| `AUD-588-F05` | Validation gap | **locally verified only**: dirty-tree `verify-edit` and eight mutating/denied invocables remain unexercised externally. | Clone the repository into scratch space, edit the clone and run the dirty-tree protocol; do not use an archive without `.git`. |
+
+**Fifth-pass anchor correction:** `posture.summary` now reports the Spring IoC population
+(`population_total: 1904`, `conditional: 5`, `active: 3`, `inactive: 2`, `unconditional:
+1899`) instead of the former type count (`6667`). This is an intentional correction with
+explicit units, not a regression. The audit remains static: it did not start the application.
+
+**Recommended order:** BUG-1 measurement/isolation → `risk` phase-cost investigation →
+BUG-3 reuse comparison → BUG-4 contract cleanup → BUG-5 calibration. Keep EclipseLink
+automation deferred; provider non-coverage is the honest current behavior. `F02` remains
+partial, `F03` open, `F04` explicit opt-in and `F05` locally verified only.
+
+### Historical Execution Queue: `5.8.14` Intake
+
+| ID | Severity | Current status | Required direction |
+|---|---|---|---|
+| `R-1` | High | **closed by `424fb1c`** | Delivery timing now publishes current elapsed time plus cache and phase provenance. |
+| `R-2` | Medium | **closed by `5158b92`** | `BC-004` declares removed fields, replacements and effective version. |
+| `R-3` | Medium | **closed by `88aec04`** | Global cache purge now clears parse and Shared CIR stores. |
+| `R-4` | Medium | **closed by `04fd04f`** | Payload layers are homonymous with their authorities: `cir`, `parse_store`, `snapshot`, `ris`. |
+| `N-6` | Medium | **not reproduced after cache fixes** | Isolated cold `openmrs-core`: 5.18 s wall / 4.76 s internal, all four layers cold. Retain the field report as an environment-specific reproduction request. |
+| `B-3` | Medium, core/supported | **closed by `773268d`** | Help no longer claims maximum signal; `sibling_view` points to compact. |
+| `B-6` | Medium, core | **closed by `17c6e06`** | Partial answers publish `overrun_bound` and its wall-clock basis. |
+| `B-8` | Low | **closed by `52593b6`** | Compact posture retains one unresolved sample when the total is non-zero. |
+| `N-5` | Low, core | **closed by `c68083f`** | Progress and payload name the Java population. |
+| `N-7` | Low, core | **closed by `082e9de`** | Bounded fuzzy candidates and matching message hints handle close typos. |
+
+**Recommended features/hardening:** response timing provenance and root cache-layer
+disclosure; a single cache reset/state authority; compact/agent parity or sibling-view
+metadata; a partial-budget exit contract; shared population/units authority; reusable fuzzy
+symbol suggestions; and a release gate for `breaking-changes-v1` whenever core or supported
+fields are removed. These extend `AUD-588-F02` and `AUD-588-F03`. `AUD-588-F01` EclipseLink
+automation remains deferred; provider non-coverage is the current product behavior.
 
 | Rows | Current status | Evidence |
 |---|---|---|

sourcecode-5.8.16/docs/DEMO-5MIN.md

@@ -0,0 +1,102 @@
+# ASK Engine - 5-Minute Demo
+
+A short, reproducible first demonstration for a Java/Spring repository. It shows
+three user outcomes: understand a change, assess migration work, and reuse local
+context. It deliberately does not promise fixed counts or timings: those depend on
+the repository commit, machine, cache state, and ASK release.
+
+## Before the meeting
+
+Install the current package, verify the build, and decide the telemetry policy before
+cloning or inspecting customer code.
+
+```bash
+pipx install sourcecode             # or: pip install sourcecode
+ask version
+ask telemetry disable               # only when the engagement policy requires it
+
+git clone --depth 1 https://github.com/BroadleafCommerce/BroadleafCommerce
+git clone --depth 1 https://github.com/openmrs/openmrs-core
+
+# Build the compact view and shared structural layers ahead of the live session.
+ask cache warm BroadleafCommerce
+ask cache warm openmrs-core
+```
+
+For a customer repository, use its approved local checkout instead of cloning a public
+sample. Record `ask version`, the repository commit, and whether the cache was warm if
+you need to compare runs later.
+
+## Act 1 - What changes if I touch this? (about 90 seconds)
+
+Start from the service interface used by callers, not a Spring implementation class.
+
+```bash
+ask impact CatalogService BroadleafCommerce -o impact.json
+jq '{risk_level, risk_score, stats}' impact.json
+```
+
+**Show:** direct and indirect callers, affected endpoints, cross-module reach, confidence,
+and source-backed evidence. If `CatalogService` has moved in the upstream checkout, ASK
+returns candidates; choose one of those candidates before the meeting rather than making up
+a class name.
+
+**Say:** “This is a structural dependency answer. It follows declared calls and Spring
+injection edges; it does not infer runtime traffic or prove that a path executes in
+production.”
+
+For a Spring-specific request-path view, use the interface with `impact-chain`:
+
+```bash
+ask impact-chain CatalogService BroadleafCommerce --with-findings -o impact-chain.json
+```
+
+## Act 2 - Is the migration work understood? (about 2 minutes)
+
+Use the compact decision report first; persist the full report only when someone needs the
+leaf findings.
+
+```bash
+ask migrate-check openmrs-core --compact -o migration-summary.json
+jq '{readiness_score, headline_blocker, blocking_count, applicable_dimensions, java_lts_inventory}' \
+  migration-summary.json
+```
+
+**Show:** applicable readiness dimensions, the headline blocker when one exists, located
+findings, Java target evidence, and the distinction between blockers and advisory hygiene.
+The report may mark a dimension as not applicable; that is different from a score of zero.
+
+To prepare a re-test order for a real migration, add reach as a separate scope:
+
+```bash
+ask migrate-check openmrs-core --blast-radius --compact -o migration-retest.json
+```
+
+**Say:** “Reach orders regression testing. It does not make a compile blocker safe, and
+the report never treats unresolved reach as zero.”
+
+## Act 3 - Reuse the right local context (about 45 seconds)
+
+Show what the warm cache helps before showing a timing. This avoids implying that every
+command becomes instant after a warm.
+
+```bash
+ask cache model BroadleafCommerce
+time ask BroadleafCommerce --compact -o compact.json
+```
+
+**Show:** the `ask (root)` row in `cache model`, then the compact context. Explain that
+`cache warm` warms the compact view and shared layers, while analysis flags such as
+`--full`, `--env-map`, `--depth`, and `--exclude` can describe a different analysis and
+therefore need fresh work.
+
+## Close (about 30 seconds)
+
+“ASK is a local, deterministic structural-analysis CLI for Java/Spring repositories. It
+gives an auditable answer about change reach, migration evidence, and reusable context. It
+does not execute the application, replace runtime testing, or claim behavior the repository
+does not establish.”
+
+Next references: [USER_GUIDE.md](USER_GUIDE.md) for command workflows,
+[CACHE.md](CACHE.md) for cache behavior, [posture.md](posture.md) for profile-aware
+Spring wiring, and [migrate-check.md](migrate-check.md) for migration semantics.