sourcecode 5.8.13__py3-none-any.whl → 5.8.15__py3-none-any.whl

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__ = "5.8.13"
+__version__ = "5.8.15"

sourcecode/_docs/DEFECT-LEDGER.md

@@ -16,24 +16,99 @@ 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.13` and the external `5.8.11` re-audit:** this is the current status of
-the 5.8.8/5.8.9 audit queue. The subject remained `saint-server` at `3dde0376`, with a
-byte-identical CIR and the same 53/61 invocables exercised. The score is **78/100**
-(75 in 5.8.8, 80 in 5.8.9). The observations below remain historical evidence; only
-this table declares present state.
+**Latest attached audit of release `5.8.14`; correction battery targets `5.8.15`:** score **93/100**, coverage **53/61
+invocables (87%)**, byte-identical CIR across five versions, and no functional-result
+regression. One reproducible performance regression is now the primary release concern;
+the historical `risk` P0 remains open because five successful runs do not disprove two
+earlier exit-0/no-output failures. Only the fifth-pass section below declares present
+state; older audit rounds remain below for traceability.
+
+**Release status:** entries marked “pending `5.8.14`” in their historical wording are
+shipped in `5.8.14`; the correction battery fixes listed above are included in `5.8.15`.
+
+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`).
+
+### 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 |
 |---|---|---|
-| `AUD-588-B01`, `AUD-589-B01`, `C3-122` | **implemented in 5.8.12** | `9884488` requires `risk` and `audit-report` to deliver stdout or their requested artifact before exit 0; the remaining closure evidence is a field-scale subprocess reproduction. |
+| `AUD-588-B01` / `AUD-589-B01`, `C3-122` | **open, P0 for `risk`; `audit-report` corrected** | `9884488` corrected `audit-report` to refuse with typed `OUTPUT_TOO_LARGE` and produce its requested artifact. `risk` nevertheless exited 0 twice on the first shared-cache invocations with 0 bytes and no `-o` file, then succeeded seven times. `5cfa9ba` now publishes the source, audit-finding, candidate-defect and composed-defect working set, including partial answers. Repeat the real entry-point protocol before closure. |
 | `AUD-511-R01` / `AUD-588-B03` | **implemented in 5.8.12** | `13362ec` makes SEC-009 read comment-blanked Java, so a Javadoc profile cannot override the live `@Profile("!m3")` declaration. |
 | `AUD-588-B04` | **retracted audit premise** | `data-exposure` correctly preserves `chain_decision`; the reported `coverage_unknown` routes were custom-gate annotations whose application was not configured. `fd34eb1` remains a valid additive disclosure, but no further B04 fix is due. |
 | `AUD-588-B05` | **closed** | `c15f5b6`; changed container-wired components block a false `unaffected` disposition. |
-| `AUD-511-R03` / `AUD-588-B07` | **implemented in 5.8.12** | `47aee1e` gives the published `OUTPUT_TOO_LARGE` envelope precedence over an inconsistent process status and preserves the excerpt in every branch. |
+| `AUD-511-R03` / `AUD-588-B07` | **implemented, pending 5.8.14 re-audit** | `f613df9` makes ASK-09 parse the typed document from stdout or stderr, including a progress-prefixed stderr stream, and removes the four inherited variables that change its precondition. The regression exercises the real typed refusal shape. The prior claim that the payload premise was false remains retracted as an environment-contamination artifact. |
 | `AUD-588-B08` | **closed** | `c084555`; `impact` publishes its independent stdout-byte budget. |
 | `MCP-001` | **closed 5.8.13** | Deep corpus testing reproduced concurrent `CliRunner` stream capture leaking a tool response to the host stdout. `b2c9660` serializes the narrow process-global capture seam; concurrent real MCP calls and a regression test verify response isolation. |
-| `AUD-588-B11` (container/units subset) | **partially implemented in 5.8.12** | `d745d31` discovers nested Maven modules; `273ae8e` suppresses unsupported `pr-impact.unaffected_basis`. `impact` naming, source population units, risk tiers and plan narrative remain open. |
-| `AUD-511-R02` / `AUD-589-B02` | **partially mitigated in 5.8.12, still under investigation** | `b93f230` reuses one `SpringSemanticModel` across every declared `data-exposure` seed; `473f47a` routes `validation` through the shared CIR cache, and `91bd0c0` retains subcommand `--no-cache` compatibility. On the local BroadleafCommerce corpus at the final analyzer fingerprint, a first shared-CIR fill took 10.46 s and its warm `validation --compact` hit took 4.01 s with byte-identical output. This is a same-host cache-state observation, not the 5.8.9/5.8.11 external A/B: the six-run C3-120 comparison and the configured `saint-server` reproduction remain required. |
-| `AUD-588-B02`, `B06`, B11 residuals, `B12` | **partially open in 5.8.12** | `3869c87` excludes explicit EclipseLink from Hibernate applicability and effort; `037223e` publishes provider non-coverage. B11 parity and controlled cost calibration remain required. |
+| `AUD-513-N01` (`N-1`) | **closed in 5.8.14** | `rename-class` rewrote three Petclinic files under both `ASK_READONLY=1` and `--no-write`, then exited 0. The audit restored the tree; this is a write-policy breach, not an artifact-directory exception. `readonly.guard_mutation()` now refuses before any planned source write or physical rename; help names the command as mutating and regressions cover both readonly controls plus `--dry-run`. |
+| `AUD-513-N02` / `B-4` / `N-5` | **N02/B-4 implemented in 5.8.14; N-5 open** | `posture.summary.unconditional` counted 1,697 on a non-Spring Struts tree and 1,573 on Mall, and `security` was `0/0/0` with no population. The posture projection now uses the canonical Spring IoC bean population, publishes its population/unit and separates unconditional security beans. Regressions cover non-Spring, mixed-bean and conditional/unconditional security fixtures. Progress/advice still use incompatible “Java files” scopes (`N-5`), so the `AUD-588-F02` family remains open. |
+| `AUD-513-B01` / `B-3` / `B-5` | **B01/B-5 implemented in 5.8.14; B-3 closed as revalidated** | A MyBatis XML paired with a `*Mapper.java` interface now takes precedence over an absent `@Mapper` annotation, preserving XML-backed/`@MapperScan` interfaces in `mapper_interfaces` rather than misclassifying them as DTO mappers. `imports_found` now contains only actual Java imports; code, XML and build matches are emitted as `evidence`, including in compact output. `B-3` was stale against the current source: both views consume `JAVA_SPRING_SECTIONS`; a real MyBatis Mapper/XML regression proves the section is retained by `--agent`. |
+| `AUD-513-N03/N04/N07/N08/N09`, `B-6/B-7/B-8`, `D-09` | **N03/N04/N07/N08/N09 implemented in 5.8.14; remainder open** | `impact` now always publishes the `candidates` field its not-found message names, including `[]` when no close symbol exists. Budget advice no longer calls partial snapshot/RIS evidence a warm cache: it identifies that presence and says context/parse are unknown before analysis, whose payload then reports all four actual layers. README operational sections (`clone`, install, build, getting started, troubleshooting and related headings) are never promoted into a project summary; with no descriptive prose compact output publishes `project_summary: null` and `summary_basis`. `security_posture.limitations` is now cache-state invariant; dynamic execution advice travels in `security_posture.operational_hints`. Every numeric output bound rejects negative values at parse time with a structured `INVALID_INPUT` envelope (`flag`, `value`, `expected`); `--limit 0` still means no cap wherever that behavior was published. Budgets overrun, timing coverage is inconsistent, compact hides unresolved identities and cost anchors remain stale. |
+| `AUD-588-B11` (container/units subset) | **partially implemented in 5.8.14** | `d745d31` discovers nested Maven modules; `273ae8e` suppresses unsupported `pr-impact.unaffected_basis`. `e53507d` separates direct impact matches from analysis seeds and implementation classes; `8386744` carries the established container-wiring fact into plan checklists and compare cost dimensions. Source population units and risk-tier wording remain open. |
+| `AUD-511-R02` / `AUD-589-B02` / `AUD-513-N06` | **partially corrected; `data-exposure` open, P1** | Nine of ten measured commands recovered, many to their best historical timings. `data-exposure --config` did not: 42.7 s versus 16.2 s in 5.8.8 and a 28.9 s model, with byte-equivalent output. Measure it with the idle-host, isolated-cache, interleaved-control protocol before changing code, then compare its reuse path with `validation`. |
+| `AUD-588-B02`, `B06`, B11 residuals, `B12` | **B02/B06 closed; B11/B12 open, P2** | `3869c87` excludes explicit EclipseLink from Hibernate applicability and effort; `037223e` publishes provider non-coverage. The re-audit verifies both and the payload reduction; `cf57457` makes aggregate wording name only applicable dimensions. Complete B11 consumer parity and calibrate B12 only from provenance-bearing controlled samples. |
+
+### Fourth Re-audit: 5.8.13
+
+The fourth pass verifies the current facts that supersede the prior intake. There is no
+crash/traceback and no regression in the published anchors. `B-2/D-05` remains a retracted
+servlet premise, and the audit additionally verifies EclipseLink applicability/non-coverage,
+typed `audit-report` refusal, nested Maven discovery and the `unaffected_basis` correction.
+It leaves the following concrete queue rather than reopening closed facts.
+
+| Recommendation | Status and direction |
+|---|---|
+| `AUD-588-F02` shared answer contracts | **Partial.** Reuse the existing authorities for exact target versus implementation cone, named source populations and container reach in plan/compare; do not add a parallel detector. |
+| `AUD-588-F03` versioned cost calibration | **Open.** Capture repository, cache state, sample count and host provenance. The immediately actionable measurement is `data-exposure --config`; clean data is required before recalibration. |
+| Risk cache observability | **Recommended hardening.** Publish working-set unit counts under progress or in the envelope to distinguish an empty compositor from a present-but-incomplete cache. |
+| `AUD-588-F05` coverage expansion | **Locally verified only.** Dirty-tree `verify-edit` and the eight mutating/denied invocables remain unexercised in all four external rounds. |
+| EclipseLink migration automation | **Deferred product feature.** The current applicability and non-coverage facts are verified; provider-specific migration automation is not a corrective fix. |
 
 ### Re-audit Intake: 5.8.11
 

sourcecode/_docs/USER_GUIDE.md

@@ -6,7 +6,11 @@
 
 ## What is it
 
-A local CLI. No API keys. No network calls. No account required.
+A local CLI. Source analysis runs on your machine; it does not need an API key or
+an account. Anonymous telemetry is enabled by default and may send operational
+event metadata, never source content, paths, secrets, or command output. Disable
+it with `ask telemetry disable`, `SOURCECODE_TELEMETRY=0`, or `DO_NOT_TRACK=1`
+before a run when policy requires it. See [privacy.md](privacy.md).
 
 It builds a deterministic symbol graph (classes, annotations, injection edges, HTTP routes) from your repository's source files and answers structural questions about that graph. All analysis is static — it reads code, not runtime behavior.
 
@@ -42,7 +46,7 @@ CLI commands        — impact, endpoints, spring-audit, explain, … each a pro
 The key idea: the extraction is **content-addressed**. Commands reuse the parse cache and,
 where their analysed scope matches, the shared Canonical IR; `ask cache model` names what a
 warm buys for each command rather than implying that every projection costs the same. In
-5.8.12, `validation` enters through that shared CIR and `data-exposure` reuses one semantic
+5.8.15, `validation` enters through that shared CIR and `data-exposure` reuses one semantic
 model across all declared label seeds. (The extraction and consumption contract is fixed in
 the architecture ADRs 0001–0004 under `docs/architecture/`.)
 
@@ -138,16 +142,20 @@ pipx install sourcecode   # isolated install, no venv needed
 
 # Verify
 ask version
-# ask 5.8.13
+# ask 5.8.15
 ```
 
 Requires Python 3.9+.
 
 ---
 
-## License activation (Pro features)
+## Entitlement and activation
 
-Free features work immediately after install. Pro commands (`impact` full output, `review-pr`, `fix-bug`, `modernize`) require an active license. `spring-audit`, `impact-chain`, `endpoints`, `onboard`, `repo-ir`, and `cold-start` are free.
+Base analysis works immediately after install. The effective entitlement is a runtime
+fact, not a command list in this document: use `ask auth status` to see what runs,
+why it runs, and when that source changes. During the current early-adoption period
+the Pro entitlement may be unlocked without a key; an activated key remains the
+explicit way to establish an entitlement when one is required.
 
 ```bash
 ask activate SC-XXXX-XXXX-XXXX
@@ -179,7 +187,7 @@ estimate scaled by file count would be wrong in the direction that costs you a s
 and an anchor printed without its release goes on recommending a nightly job for a command
 that has come to finish in seconds (C3-97).
 
-Forty commands and six command groups exist. Four of them carry most of the measured
+41 commands and six command groups exist. Four of them carry most of the measured
 value in field use, and they are the ones to learn first:
 
 | Start with | Because |
@@ -256,6 +264,9 @@ ask onboard . --output onboard.json
 ```
 
 Output: architecture summary, subsystems, key entry points, hotspots, tech-debt signals, analysis gaps.
+The payload also publishes `population`, `population_unit` and `population_total`; these
+describe the non-test source-file universe behind the onboarding ranking, not every file
+in the repository.
 
 ### `ask endpoints` *(core)*
 
@@ -342,6 +353,7 @@ ask spring-audit . --output audit.json
 ask spring-audit . --since origin/main --fail-on-new   # gate on what THIS change added
 ask spring-audit . --remediation-diff  # the patches a reviewer applies
 ask spring-audit . --clusters          # the work items behind the findings
+ask spring-audit . --ci --format github-actions  # native CI annotation plus ASK_CI summary
 ```
 
 **`--since <ref>` / `--fail-on-new` — the gate a repository with debt can turn on.**
@@ -379,7 +391,7 @@ disabled changes runtime behaviour nobody measured; a diff is how a person makes
 call with the evidence in front of them.
 
 **TX patterns (TX-001..TX-006):** proxy bypass, nested transactions, readOnly propagation, NOT_SUPPORTED in active TX, exception swallowing, self-invocation of a `@Transactional` sibling.
-**SEC patterns (SEC-001..SEC-008):** unsecured endpoints, CVE-2025-41248 `@PreAuthorize` inheritance bypass, `@Transactional` on controllers, passwords stored under a fast unsalted digest, CSRF disabled under session-bearing authentication, cookies created without the Secure attribute, credentials stored in a deployment descriptor, and SQL built by MyBatis string interpolation. **DEAD-001** reports a security control that is present only in comments and therefore disabled.
+**SEC patterns (SEC-001..SEC-009):** unsecured endpoints, CVE-2025-41248 `@PreAuthorize` inheritance bypass, `@Transactional` on controllers, passwords stored under a fast unsalted digest, CSRF disabled under session-bearing authentication, cookies created without the Secure attribute, credentials stored in a deployment descriptor, SQL built by MyBatis string interpolation, and anonymous request-chain exceptions. **DEAD-001** reports a security control that is present only in comments and therefore disabled.
 **GATE patterns (GATE-001..GATE-004):** custom AOP/security-gate risks over the same custom-gate authority published in `security_posture`: proxy bypass (`private`/`final`/self-invocation), advice that appears to fail open, disabled or tautological annotation attributes, and fragile `args[0]`/reflection binding.
 
 Each finding includes `severity`, `confidence`, `symbol`, `source_file`, `evidence`, `explanation`, and `fix_hint`. JAVA/SPRING ONLY.
@@ -656,6 +668,22 @@ cannot be reviewed as one change (on openmrs-core, including it takes the popula
 — its own, and `migrate-check`'s narrower headline `blocking_count` — because two
 populations under one name is the defect this project keeps finding in its own output.
 
+### `ask migrate-apply` *(supported)*
+
+```bash
+ask migrate-apply .                         # plan only; no mutation
+ask migrate-apply . --write --rewrite-version X.Y.Z
+ask migrate-apply . --write --rewrite-version X.Y.Z --compile
+```
+
+The default is read-only. `--write` requires a clean Git tree and runs the measured
+recipe in a separate branch/worktree with a pinned OpenRewrite version. The main tree
+is not modified and ASK does not commit or merge. Maven and Gradle are supported
+executors; Gradle uses a temporary OpenRewrite init script and does not modify the
+project build files. After rewriting, ASK runs `migrate-check` on the
+isolated result. `--compile` adds a build with tests skipped and a timeout; network access
+requires `--allow-network`. Any failed stage removes the temporary branch/worktree.
+
 ### `ask data-exposure` *(supported)*
 
 **Which routes can carry the data you called sensitive, and who reaches them.** Nothing
@@ -673,9 +701,15 @@ engine never branches on a name. Declare it once, in `sourcecode.config.json`:
 ```bash
 ask data-exposure .                       # every route that can carry a declared label
 ask data-exposure . --profile prod        # …and what THAT deployment leaves reachable
+ask data-exposure . --init --dry-run      # suggest candidates, write nothing
+ask data-exposure . --init                # write proposed_only candidates under .ask/
 ask data-exposure /path/to/repo -o exposure.json
 ```
 
+`--init` never infers or activates a label. It writes only
+`.ask/data-label-candidates-v1.json`; approved labels still require a human declaration
+in `sourcecode.config.json`.
+
 Everything after the declaration is measured, over authorities that already exist: the
 call reach `impact-chain` walks, the endpoint security surface `risk` weighs, and the
 profile resolution `posture` publishes. Two evidence classes, published apart and **never
@@ -1059,6 +1093,7 @@ ask verify                         # gate: only NEW violations block (--fail-on
 ask verify --capture-baseline      # accept today's debt, once
 ask verify --fail-on any           # gate on every violation, debt included
 ask verify --fail-on never         # report without gating
+ask verify --format github-actions # native CI annotation; exit contract is unchanged
 ```
 
 **Start with `--init`.** Nobody hand-writes contracts for a 3 000-file monolith, and a gate
@@ -1130,6 +1165,10 @@ The same blast radius, scoped to a diff, with gating exit codes.
 git diff --name-only origin/main | ask pr-impact . --files -
 ask pr-impact . --files changed_files.txt --fail-on high
 ask pr-impact . --files A.java,B.java
+ask pr-impact .                         # local git diff HEAD
+ask pr-impact . --since origin/main     # local diff from a base ref
+ask pr-impact . --pr 123                # opt-in GitHub CLI adapter
+ask pr-impact . --format github-actions # CI annotations, JSON remains the default
 ```
 
 Reports modified classes, the REST endpoints reachable through their call chains, direct
@@ -1137,6 +1176,10 @@ callers, event publishers and consumers, `@Transactional` methods in the changed
 a consolidated risk level. **A changed Java file that maps to no class caps the verdict at
 `UNKNOWN`** — a partial blast radius is never reported as a low one.
 
+`--pr NUMBER` invokes the local `gh` CLI to obtain the changed paths. It is opt-in, does not
+fetch or modify the repository, and requires local GitHub authentication. It cannot be
+combined with `--files` or `--since`; those modes remain fully offline.
+
 ---
 
 ## Measuring a change, before and after
@@ -1293,7 +1336,9 @@ The MCP server exposes structural analysis tools to AI agents without requiring
 
 ## Output schema
 
-All commands output structured JSON to stdout unless `--output` is specified.
+Analysis and report commands output structured JSON to stdout unless `--output` is
+specified. Status and management commands intentionally return concise text, and
+`ask explain` defaults to text; each command's `--help` names its supported formats.
 
 Common fields:
 - `schema_version` — format version
@@ -1574,11 +1619,12 @@ Allowed formats per command (the first is the default):
 | `endpoints` | `json`, `yaml` | `json` |
 | `validation` | `json`, `yaml` | `json` |
 | `impact-chain` | `json`, `yaml` | `json` |
-| `spring-audit` | `json`, `yaml`, `github-comment` | `json` |
+| `spring-audit` | `json`, `yaml`, `github-comment`, `github-actions` | `json` |
 | `prepare-context` | `json`, `github-comment` | `json` |
-| `migrate-check` | `json`, `text` | `json` |
+| `migrate-check` | `json`, `text`, `github-actions` | `json` |
 | `explain` | `text`, `json` | `text` |
-| `pr-impact` | `json`, `text` | `json` |
+| `pr-impact` | `json`, `text`, `github-actions` | `json` |
+| `verify` | `json`, `yaml`, `github-actions` | `json` |
 
 `explain` defaults to a human-readable `text` view; pass `-f json` for
 programmatic consumption. `pr-impact` defaults to `json` like every other

sourcecode/archetype.py

@@ -134,12 +134,16 @@ class ArchetypeAnalysis:
     signals_used: list[str]
     signals_missing: list[str]
     generated_from: str
+    total_files: int
     graph_metrics: dict[str, float] = field(default_factory=dict)
 
     def to_dict(self) -> dict[str, Any]:
         return {
             "schema_version": "0.1-experimental",
             "note": "Parallel/experimental model. Legacy architecture pattern is unchanged.",
+            "population": "source files",
+            "population_unit": "source files in the scanned repository tree",
+            "population_total": self.total_files,
             "dimensions": {
                 dim: {
                     "primary": r.primary,
@@ -269,6 +273,7 @@ class ArchetypeClassifier:
                     else "endpoint surface not measured"
                 )
             ),
+            total_files=f.total_files,
             graph_metrics=f.graph_metrics,
         )
 

sourcecode/breaking_changes.py

@@ -273,11 +273,51 @@ DEPRECATED_FIELD_REMOVAL = BreakingChange(
 )
 
 
+def _released_schema_removals() -> "list[dict[str, object]]":
+    """Fields removed in 5.8.14, kept as an explicit migration record."""
+    return [
+        {
+            "identifier": identifier,
+            "becomes": replacement,
+            "removed_in": "5.8.14",
+        }
+        for identifier, replacement in (
+            ("migrate-check.findings[].imports_found", "use findings[].evidence"),
+            ("ask.mybatis.dto_mappers", "use the compact sibling view or full output"),
+            ("ask.mybatis.dto_mappers_total", "use mybatis.mapper_interfaces"),
+            ("ask.mybatis.dto_mappers_truncated", "use the view cap metadata"),
+        )
+    ]
+
+
+RELEASED_SCHEMA_REMOVALS = BreakingChange(
+    id="BC-004",
+    kind=KIND_CONTRACT,
+    released_in="5.8.14",
+    takes_effect_in="5.8.14",
+    title="core and supported payload fields removed in a patch release",
+    what_changed=(
+        "The 5.8.14 payload no longer emits the fields listed in "
+        "affected_values. This is a contract change even where the replacement "
+        "is a better signal, because consumers must be able to schedule the "
+        "migration rather than discover a missing key at runtime."
+    ),
+    trigger="a consumer reads one of the removed fields from migrate-check or the root ask payload",
+    compatibility=(
+        "pin 5.8.13 while migrating, or treat each affected field as optional "
+        "and read the replacement named beside it"
+    ),
+    remedy="dispatch on the replacement and gate on its presence before upgrading",
+    affected=_released_schema_removals,
+)
+
+
 #: Every declared breaking change, newest first. A release that breaks a caller
 #: and does not add a row here fails `tests/test_breaking_change_
 #: disclosure_ask11.py` — the policy is enforced, not remembered.
 BREAKING_CHANGES: tuple[BreakingChange, ...] = (
-    DEPRECATED_FIELD_REMOVAL, SCHEMA_VERSION_RENAMES, OUTPUT_CEILING,
+    RELEASED_SCHEMA_REMOVALS, DEPRECATED_FIELD_REMOVAL,
+    SCHEMA_VERSION_RENAMES, OUTPUT_CEILING,
 )
 
 

sourcecode/cache_model.py

@@ -297,6 +297,13 @@ COMMANDS: tuple[CommandCache, ...] = (
                  "the parse, not the rule pass.",
                  "not measured on the battery yet — bounded by `migrate-check` on the same "
                  "repository (openmrs-core ~2 s)", analysis_class="repo-wide"),
+    CommandCache("migrate-apply", ("parse",), "shared", False,
+                 "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.",
+                 "not measured on the battery yet — bounded by `migrate-check` plus the "
+                 "optional OpenRewrite execution", analysis_class="repo-wide"),
     CommandCache("data-exposure", ("cir", "parse"), "shared", False,
                  "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 "

sourcecode/change_plan.py

@@ -139,7 +139,9 @@ def build_change_plan(
             ),
         }
 
-    seeds = list(blast["matched_fqns"])
+    # The user-facing match names the requested target; planning must retain the
+    # subtype-expanded seeds that the blast-radius authority actually analysed.
+    seeds = list(blast.get("analysis_seed_fqns") or blast["matched_fqns"])
     container_wired = [w.to_dict() for w in detect_classes(cir, seeds)]
     meta = _node_meta(cir)
     affected = _dependents_closure(cir.reverse_graph or {}, seeds, max_depth, _NODE_CAP)
@@ -210,6 +212,11 @@ def build_change_plan(
         checklist.append(
             f"{len(sec)} secured endpoint(s) in scope — re-check authorization."
         )
+    if container_wired:
+        checklist.append(
+            f"{len(container_wired)} container-wired component(s) are in scope — "
+            "review their declared framework wiring because fan-in does not measure it."
+        )
     txn = blast.get("transactional_boundaries_touched") or []
     if txn:
         checklist.append(f"{len(txn)} transactional boundary/boundaries in scope.")

sourcecode/ci_output.py

@@ -0,0 +1,73 @@
+"""Small, dependency-free renderers for CI workflow commands."""
+from __future__ import annotations
+
+
+def _escape(value: object) -> str:
+    """Escape values for GitHub Actions command properties and messages."""
+    return (
+        str(value)
+        .replace("%", "%25")
+        .replace("\r", "%0D")
+        .replace("\n", "%0A")
+        .replace(":", "%3A")
+        .replace(",", "%2C")
+    )
+
+
+def render_risk_annotation(
+    risk_level: str,
+    *,
+    reason: str = "",
+    unresolved: int = 0,
+) -> str:
+    """Render one annotation and a stable summary for a risk report."""
+    level = str(risk_level or "UNKNOWN").upper()
+    command = {
+        "CRITICAL": "error",
+        "HIGH": "error",
+        "MEDIUM": "warning",
+        "LOW": "notice",
+        "UNKNOWN": "warning",
+    }.get(level, "warning")
+    message = f"risk={level}"
+    if reason:
+        message += f"; {reason}"
+    if unresolved:
+        message += f"; unresolved_files={unresolved}"
+    return f"::{command} title=ASK PR impact::{_escape(message)}"
+
+
+def render_risk_summary(risk_level: str, *, unresolved: int = 0) -> str:
+    """Render a short machine-readable summary line for CI logs."""
+    suffix = f" unresolved_files={unresolved}" if unresolved else ""
+    return f"ASK_PR_IMPACT risk={str(risk_level or 'UNKNOWN').upper()}{suffix}"
+
+
+def render_ci_result(
+    command: str,
+    *,
+    status: str,
+    severity: str = "unknown",
+    count: int = 0,
+    reason: str = "",
+    partial: bool = False,
+) -> str:
+    """Render one GitHub Actions annotation plus a stable CI summary line."""
+    normalized_status = str(status or "unknown").lower()
+    level = str(severity or "unknown").upper()
+    if partial or normalized_status in {"unverified", "unknown", "partial"}:
+        annotation = "warning"
+    elif normalized_status in {"fail", "failed", "findings"} or level in {"CRITICAL", "HIGH"}:
+        annotation = "error"
+    elif level == "MEDIUM":
+        annotation = "warning"
+    else:
+        annotation = "notice"
+    message = f"status={normalized_status}; severity={level}; findings={int(count)}"
+    if partial:
+        message += "; partial=true"
+    if reason:
+        message += f"; {reason}"
+    annotation_line = f"::{annotation} title=ASK {command}::{_escape(message)}"
+    summary = f"ASK_CI command={_escape(command)} status={_escape(normalized_status)} severity={_escape(level)} findings={int(count)}"
+    return f"{annotation_line}\n{summary}"