sourcecode 5.8.14__py3-none-any.whl → 5.8.16__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.14"
+__version__ = "5.8.16"

sourcecode/_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/_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.16, `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.14
+# ask 5.8.16
 ```
 
 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/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}"