sourcecode 4.8.0__tar.gz → 4.9.1__tar.gz

{sourcecode-4.8.0 → sourcecode-4.9.1}/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 ## [Unreleased]
 
+## [4.9.1] — 2026-08-04
+
+### Added
+
+- **Java LTS/licensing inventory in `migrate-check`.** Reports Java 8/11/17/21/25
+  evidence from Maven/Gradle, local runtime hints and container files, target-LTS
+  blockers via `--target-jdk`, and explicit Oracle JDK licensing-review signals
+  without changing migration readiness scoring.
+- **Claim provenance ledger.** `risk`, `enrich`, `migrate-check`, `audit-report`
+  and `prepare-context` now emit `evidence_manifest` with stable claim IDs,
+  source paths/lines, command inputs, ASK version, git HEAD and freshness metadata.
+
+## [4.9.0] — 2026-08-04
+
+### Added
+
+- **Custom AOP security gate audit.** `spring-audit` now emits `GATE-001` through
+  `GATE-004` for custom authorization gates detected by the security posture
+  authority: Spring AOP proxy bypass, fail-open advice, disabled/tautological
+  annotation attributes, and fragile positional/reflection binding.
+- **Deployment evidence for runtime posture.** `posture --resolve-environments`
+  accepts `--env-file FILE` and binds explicit deployment profile evidence to
+  `decided_case` while keeping repository defaults as lower-priority evidence.
+- **Bounded HTTP-input-to-sink flow in `risk`.** The `query_construction` factor
+  now distinguishes a proven bounded path from annotated HTTP input, through
+  positional calls in repository Java sources, into known concatenated query
+  sinks. General taint remains explicitly outside scope.
+- **SARIF triage table for `enrich`.** `enrich --table` now provides
+  auditor-facing filtering by scanner rule, composed band and top-N while
+  leaving JSON as the contract.
+- **Signed audit report bundle.** New experimental `audit-report` command packages
+  existing `risk` and `posture` evidence into JSON or Markdown, with optional
+  HMAC-SHA256 signing over the canonical JSON payload via `--sign-key`.
+
+### Documentation
+
+- README, user guide and root `ask --help` now list `audit-report`, the 4.9.0
+  version, `posture --env-file`, `enrich --table`, bounded `risk` flow and the
+  `GATE-*` rule family.
+
 ## [4.8.0] — 2026-08-04
 
 ### Fixed

{sourcecode-4.8.0 → sourcecode-4.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 4.8.0
+Version: 4.9.1
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -42,7 +42,7 @@ Description-Content-Type: text/markdown
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-4.8.0-blue)
+![Version](https://img.shields.io/badge/version-4.9.1-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -97,7 +97,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.8.0 — and, on a build that has aged,
+ask version                    # ask 4.9.1 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -137,8 +137,9 @@ ask endpoints /path/to/repo
 # CGLIB no-op), security surface, request-body validation.
 ask spring-audit /path/to/repo
 
-# Spring Boot 2→3 readiness: located blockers, per-dimension score, effort estimate.
+# Spring Boot 2→3 readiness plus Java LTS/licensing inventory.
 ask migrate-check /path/to/repo --compact
+# Add --target-jdk 25 to make the LTS route explicit.
 ```
 
 **Then the three that finish the sentence the four above start.** A profile-set answer stays
@@ -260,10 +261,10 @@ figures and the authority behind each — and an axis this build cannot measure
 weighted 1.0 and named in `blind_axes` rather than silently treated as safe. Measured on a
 field case: a defect both `spring-audit` and `impact-chain` called *medium* composes to
 **high (8.06)** once *reachable unauthenticated* and *writes to the database* are in it.
-The last two factors describe the input path — a query assembled by concatenation, a route
-accepting a body with no declared constraint. They are **adjacencies, not dataflow**: no
-value is followed from a request to a sink, which is `NC-001` and is published in the
-payload's own `non_coverage` block.
+The last two factors describe the input path: a query assembled by concatenation, a bounded
+HTTP-input-to-query-sink path when ASK can prove one, and a route accepting a body with no
+declared constraint. General taint remains `NC-001` and is published in the payload's own
+`non_coverage` block.
 `ask risk .` · `ask risk . --min-band high` · `ask risk . --limit 10`
 → [reference](docs/USER_GUIDE.md)
 
@@ -289,7 +290,7 @@ experimental: both are true, and they are two different facts.
 |---|---|---|
 | **core** | contract stable within a major — safe to gate CI on | `endpoints` · `spring-audit` · `migrate-check` · `impact` · `impact-chain` · `pr-impact` · `verify` |
 | **supported** | maintained; fields are added, never removed without a major | every command not named in another row |
-| **experimental** | shape may change in a minor — do not gate CI on it | `risk` · `enrich` · `data-exposure` · `migrate-recipe` · `posture` · `archetype` |
+| **experimental** | shape may change in a minor — do not gate CI on it | `risk` · `enrich` · `audit-report` · `data-exposure` · `migrate-recipe` · `posture` · `archetype` |
 | **parked** | kept working, no longer developed | `retrieve` |
 
 The same table is printed by `ask --help`, and both are generated from one authority
@@ -307,12 +308,13 @@ from it.
 |---|---|---|---|
 | `posture` | experimental | which beans a profile set wires, and how effective endpoint access differs between two sets | the most differentiated capability here |
 | `risk` | experimental | what each defect actually costs, once reach, access, write effect and the shape of the input path are in it | `defect_severity × reachability × auth_verdict × write_effect × query_construction × input_constraints`; every factor names its authority; `--table --rule SEC-008 --band high --top-n 20` gives audit triage without `jq` |
-| `enrich` | experimental | another scanner's SARIF findings, ranked by what this repository does with them | `--sarif <log>`; the same composition as `risk`, with the scanner as the severity authority |
+| `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` | experimental | 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` | experimental | 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 |
 | `data-exposure` | experimental | 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 |
 | `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 |
 | `spring-audit` | core | transactional anomalies + security surface + validation gaps | `--ci`, `-f github-comment`; `--table --rule SEC-008 --top-n 20` for human-scale review |
-| `migrate-check` | core | Boot 2→3 readiness: located blockers, per-dimension score, effort | `--blast-radius` orders the re-test plan; `--table --rule MIG-001 --band critical --top-n 20` for blocker triage |
+| `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 |
 | `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 |
@@ -356,7 +358,7 @@ reading JSON sees the same boundary a buyer reads here.
 
 | Not covered | Why | What answers it |
 |---|---|---|
-| **Whether request input reaches a sink — no dataflow or taint analysis.** | This engine resolves structure and wiring without compiling. Taint needs value flow through a program, which is a different analysis with a different failure mode: an unsound one produces confident findings that are wrong, and every claim here is meant to be checkable against the line that produced it. | A dataflow scanner (Semgrep, CodeQL). What this product adds on top is reachability: which of that tool's findings sit behind an endpoint that is reachable unauthenticated. |
+| **General request-input-to-sink taint analysis.** | `ask risk` includes a bounded slice for annotated HTTP parameters, positional calls in repository Java sources and known query sinks. Anything broader needs value flow through a program, which is a different analysis with a different failure mode: an unsound one produces confident findings that are wrong, and every claim here is meant to be checkable against the line that produced it. | A dataflow scanner (Semgrep, CodeQL) for complete taint. What this product adds on top is reachability and, for the bounded slice, whether an annotated HTTP input reaches a known concatenated query sink. |
 | **Secrets outside Java, Spring configuration and the deployment descriptors — a Helm value, a CI variable file, a shell script.** | The file population this analyzer reads is the Java source, the Spring configuration convention and the descriptors it already parses to resolve an environment. A secret elsewhere is not missed by a weak rule; it is outside the set of files anything here opens. Narrowed by CL-10: a credential stored in `web.xml` or a Spring XML context IS reported (SEC-007), because those files were already being read. | A dedicated secret scanner over the whole tree (gitleaks, trufflehog). |
 | **Filter-chain order and per-filter URL patterns — the presence of a custom filter is structural only.** | Which filter runs first is decided by bean ordering this analyzer does not resolve. Where two active configurations both match a request, the answer published is `undecided` rather than a guess. | `ask posture --profile <set>` states per endpoint what the readable rules decide and what they leave undecided. |
 | **Known vulnerabilities in dependencies — no CVE database, no version advisory matching.** | Enriching a vulnerability feed is a different product with a different update cadence; a stale embedded database is worse than no database, because it reads as a clean bill of health. | A dependency scanner (Trivy, OWASP Dependency-Check). `impact-chain` then answers which of its findings anything actually reaches. |
@@ -400,6 +402,16 @@ and that gap is the honest description, not a defect to argue with. `migrate-che
 the OpenRewrite recipe each finding carries so the executor that does apply changes has its
 input.
 
+**Java LTS/licensing inventory.** `migrate-check` emits `java_lts_inventory` beside the migration
+scores. It reads Maven/Gradle, local runtime hints and container files for Java 8/11/17/21/25
+evidence, reports target-LTS blockers with `--target-jdk`, and marks explicit Oracle JDK evidence
+as `licensing_review_needed`. This is inventory evidence, not legal advice.
+
+**Claim provenance ledger.** JSON outputs from `risk`, `enrich`, `migrate-check`,
+`audit-report` and `prepare-context` include `evidence_manifest`: stable claim IDs mapped to
+source paths/lines, command inputs, ASK version, git HEAD and freshness metadata. The manifest
+indexes claims already in the payload; it does not add analysis or certify compliance.
+
 
 ---
 

{sourcecode-4.8.0 → sourcecode-4.9.1}/README.md

@@ -4,7 +4,7 @@
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-4.8.0-blue)
+![Version](https://img.shields.io/badge/version-4.9.1-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -59,7 +59,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 4.8.0 — and, on a build that has aged,
+ask version                    # ask 4.9.1 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 
@@ -99,8 +99,9 @@ ask endpoints /path/to/repo
 # CGLIB no-op), security surface, request-body validation.
 ask spring-audit /path/to/repo
 
-# Spring Boot 2→3 readiness: located blockers, per-dimension score, effort estimate.
+# Spring Boot 2→3 readiness plus Java LTS/licensing inventory.
 ask migrate-check /path/to/repo --compact
+# Add --target-jdk 25 to make the LTS route explicit.
 ```
 
 **Then the three that finish the sentence the four above start.** A profile-set answer stays
@@ -222,10 +223,10 @@ figures and the authority behind each — and an axis this build cannot measure
 weighted 1.0 and named in `blind_axes` rather than silently treated as safe. Measured on a
 field case: a defect both `spring-audit` and `impact-chain` called *medium* composes to
 **high (8.06)** once *reachable unauthenticated* and *writes to the database* are in it.
-The last two factors describe the input path — a query assembled by concatenation, a route
-accepting a body with no declared constraint. They are **adjacencies, not dataflow**: no
-value is followed from a request to a sink, which is `NC-001` and is published in the
-payload's own `non_coverage` block.
+The last two factors describe the input path: a query assembled by concatenation, a bounded
+HTTP-input-to-query-sink path when ASK can prove one, and a route accepting a body with no
+declared constraint. General taint remains `NC-001` and is published in the payload's own
+`non_coverage` block.
 `ask risk .` · `ask risk . --min-band high` · `ask risk . --limit 10`
 → [reference](docs/USER_GUIDE.md)
 
@@ -251,7 +252,7 @@ experimental: both are true, and they are two different facts.
 |---|---|---|
 | **core** | contract stable within a major — safe to gate CI on | `endpoints` · `spring-audit` · `migrate-check` · `impact` · `impact-chain` · `pr-impact` · `verify` |
 | **supported** | maintained; fields are added, never removed without a major | every command not named in another row |
-| **experimental** | shape may change in a minor — do not gate CI on it | `risk` · `enrich` · `data-exposure` · `migrate-recipe` · `posture` · `archetype` |
+| **experimental** | shape may change in a minor — do not gate CI on it | `risk` · `enrich` · `audit-report` · `data-exposure` · `migrate-recipe` · `posture` · `archetype` |
 | **parked** | kept working, no longer developed | `retrieve` |
 
 The same table is printed by `ask --help`, and both are generated from one authority
@@ -269,12 +270,13 @@ from it.
 |---|---|---|---|
 | `posture` | experimental | which beans a profile set wires, and how effective endpoint access differs between two sets | the most differentiated capability here |
 | `risk` | experimental | what each defect actually costs, once reach, access, write effect and the shape of the input path are in it | `defect_severity × reachability × auth_verdict × write_effect × query_construction × input_constraints`; every factor names its authority; `--table --rule SEC-008 --band high --top-n 20` gives audit triage without `jq` |
-| `enrich` | experimental | another scanner's SARIF findings, ranked by what this repository does with them | `--sarif <log>`; the same composition as `risk`, with the scanner as the severity authority |
+| `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` | experimental | 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` | experimental | 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 |
 | `data-exposure` | experimental | 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 |
 | `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 |
 | `spring-audit` | core | transactional anomalies + security surface + validation gaps | `--ci`, `-f github-comment`; `--table --rule SEC-008 --top-n 20` for human-scale review |
-| `migrate-check` | core | Boot 2→3 readiness: located blockers, per-dimension score, effort | `--blast-radius` orders the re-test plan; `--table --rule MIG-001 --band critical --top-n 20` for blocker triage |
+| `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 |
 | `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 |
@@ -318,7 +320,7 @@ reading JSON sees the same boundary a buyer reads here.
 
 | Not covered | Why | What answers it |
 |---|---|---|
-| **Whether request input reaches a sink — no dataflow or taint analysis.** | This engine resolves structure and wiring without compiling. Taint needs value flow through a program, which is a different analysis with a different failure mode: an unsound one produces confident findings that are wrong, and every claim here is meant to be checkable against the line that produced it. | A dataflow scanner (Semgrep, CodeQL). What this product adds on top is reachability: which of that tool's findings sit behind an endpoint that is reachable unauthenticated. |
+| **General request-input-to-sink taint analysis.** | `ask risk` includes a bounded slice for annotated HTTP parameters, positional calls in repository Java sources and known query sinks. Anything broader needs value flow through a program, which is a different analysis with a different failure mode: an unsound one produces confident findings that are wrong, and every claim here is meant to be checkable against the line that produced it. | A dataflow scanner (Semgrep, CodeQL) for complete taint. What this product adds on top is reachability and, for the bounded slice, whether an annotated HTTP input reaches a known concatenated query sink. |
 | **Secrets outside Java, Spring configuration and the deployment descriptors — a Helm value, a CI variable file, a shell script.** | The file population this analyzer reads is the Java source, the Spring configuration convention and the descriptors it already parses to resolve an environment. A secret elsewhere is not missed by a weak rule; it is outside the set of files anything here opens. Narrowed by CL-10: a credential stored in `web.xml` or a Spring XML context IS reported (SEC-007), because those files were already being read. | A dedicated secret scanner over the whole tree (gitleaks, trufflehog). |
 | **Filter-chain order and per-filter URL patterns — the presence of a custom filter is structural only.** | Which filter runs first is decided by bean ordering this analyzer does not resolve. Where two active configurations both match a request, the answer published is `undecided` rather than a guess. | `ask posture --profile <set>` states per endpoint what the readable rules decide and what they leave undecided. |
 | **Known vulnerabilities in dependencies — no CVE database, no version advisory matching.** | Enriching a vulnerability feed is a different product with a different update cadence; a stale embedded database is worse than no database, because it reads as a clean bill of health. | A dependency scanner (Trivy, OWASP Dependency-Check). `impact-chain` then answers which of its findings anything actually reaches. |
@@ -362,6 +364,16 @@ and that gap is the honest description, not a defect to argue with. `migrate-che
 the OpenRewrite recipe each finding carries so the executor that does apply changes has its
 input.
 
+**Java LTS/licensing inventory.** `migrate-check` emits `java_lts_inventory` beside the migration
+scores. It reads Maven/Gradle, local runtime hints and container files for Java 8/11/17/21/25
+evidence, reports target-LTS blockers with `--target-jdk`, and marks explicit Oracle JDK evidence
+as `licensing_review_needed`. This is inventory evidence, not legal advice.
+
+**Claim provenance ledger.** JSON outputs from `risk`, `enrich`, `migrate-check`,
+`audit-report` and `prepare-context` include `evidence_manifest`: stable claim IDs mapped to
+source paths/lines, command inputs, ASK version, git HEAD and freshness metadata. The manifest
+indexes claims already in the payload; it does not add analysis or certify compliance.
+
 
 ---
 

{sourcecode-4.8.0 → sourcecode-4.9.1}/pyproject.toml

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

{sourcecode-4.8.0 → sourcecode-4.9.1}/src/sourcecode/__init__.py

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

sourcecode-4.9.1/src/sourcecode/audit_report.py

@@ -0,0 +1,158 @@
+"""Signed audit report over existing ASK evidence.
+
+This module packages facts other commands already publish. It does not score ROI,
+choose a fix, or introduce a second judgement layer: the report summary is a
+reader-friendly index over the embedded evidence blocks.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+from sourcecode import __version__
+
+AUDIT_REPORT_SCHEMA = "audit-report-v1"
+
+
+def _canonical_json(data: dict[str, Any]) -> bytes:
+    return json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+def _sign(payload: dict[str, Any], key: bytes) -> dict[str, str]:
+    canonical = _canonical_json(payload)
+    return {
+        "algorithm": "hmac-sha256",
+        "payload_sha256": hashlib.sha256(canonical).hexdigest(),
+        "key_id": hashlib.sha256(key).hexdigest()[:12],
+        "signature": hmac.new(key, canonical, hashlib.sha256).hexdigest(),
+    }
+
+
+def build_audit_report(
+    root: Path,
+    *,
+    profiles: Optional[set[str]] = None,
+    sign_key: Optional[bytes] = None,
+    risk_limit: int = 10,
+) -> dict[str, Any]:
+    """Build the buyer-readable audit bundle from existing command payloads."""
+    from sourcecode.posture import build_posture
+    from sourcecode.risk import build_risk
+
+    root = Path(root).resolve()
+    risk = build_risk(root, limit=risk_limit, min_band="low", profiles=profiles)
+    posture = build_posture(root, profiles or set())
+    top_risks = risk.get("risks", [])[:risk_limit]
+    access = ((posture.get("endpoints") or {}).get("effective_access") or {})
+
+    unsigned: dict[str, Any] = {
+        "schema_version": AUDIT_REPORT_SCHEMA,
+        "tool": {"name": "ask", "version": __version__},
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "repository": {"path": str(root)},
+        **({"profile_set": sorted(profiles)} if profiles else {}),
+        "summary": {
+            "risk_model": risk.get("model"),
+            "total_defects": risk.get("total_defects"),
+            "total_findings": risk.get("total_findings"),
+            "risk_bands": risk.get("by_band", {}),
+            "top_risks_shown": len(top_risks),
+            "endpoint_access": access.get("summary", {}),
+            "unresolved_beans": len(posture.get("unresolved") or []),
+        },
+        "top_risks": top_risks,
+        "evidence": {
+            "risk": risk,
+            "posture": posture,
+        },
+        "limits": {
+            "statement": (
+                "This report packages existing ASK evidence. It does not certify "
+                "compliance, choose fixes, assign ROI, or replace a human audit decision."
+            ),
+            "non_coverage": (risk.get("non_coverage") or {}).get("items", []),
+        },
+    }
+    from sourcecode.provenance import build_evidence_manifest
+    unsigned["evidence_manifest"] = build_evidence_manifest(
+        unsigned,
+        command="audit-report",
+        root=root,
+        inputs={
+            "profiles": sorted(profiles) if profiles else None,
+            "risk_limit": risk_limit,
+            "signed": bool(sign_key),
+        },
+    )
+    # Sign and publish the same JSON-normalized material. Some embedded evidence
+    # may contain tuples or other JSON-coercible values; normalizing before signing
+    # avoids a signature over an in-memory shape the user never receives.
+    normalized = json.loads(_canonical_json(unsigned).decode("utf-8"))
+    if sign_key:
+        normalized["signature"] = _sign(normalized, sign_key)
+    return normalized
+
+
+def render_markdown(report: dict[str, Any]) -> str:
+    """Human report renderer over the JSON contract."""
+    summary = report.get("summary") or {}
+    repo = (report.get("repository") or {}).get("path", "")
+    profile = ", ".join(report.get("profile_set") or []) or "default"
+    lines = [
+        "# ASK Audit Report",
+        "",
+        f"- Repository: `{repo}`",
+        f"- ASK version: `{(report.get('tool') or {}).get('version', '')}`",
+        f"- Profile set: `{profile}`",
+        f"- Total defects: `{summary.get('total_defects')}`",
+        f"- Risk bands: `{summary.get('risk_bands')}`",
+        f"- Endpoint access: `{summary.get('endpoint_access')}`",
+        "",
+        "## Top Risks",
+        "",
+    ]
+    risks = report.get("top_risks") or []
+    if not risks:
+        lines.append("No composed risks were reported.")
+    else:
+        lines.extend([
+            "| Band | Score | Rules | File | Line | Title |",
+            "|---|---:|---|---|---:|---|",
+        ])
+        for row in risks:
+            rules = ", ".join(str(r) for r in row.get("rule_ids", []))
+            lines.append(
+                "| "
+                + " | ".join([
+                    str(row.get("band", "")),
+                    str(row.get("severity_effective", "")),
+                    rules,
+                    str(row.get("source_file", "")),
+                    str(row.get("first_line", "")),
+                    str(row.get("title", "")).replace("|", "\\|"),
+                ])
+                + " |"
+            )
+    lines.extend([
+        "",
+        "## Limits",
+        "",
+        str((report.get("limits") or {}).get("statement", "")),
+    ])
+    signature = report.get("signature")
+    if isinstance(signature, dict):
+        lines.extend([
+            "",
+            "## Signature",
+            "",
+            f"- Algorithm: `{signature.get('algorithm')}`",
+            f"- Payload SHA-256: `{signature.get('payload_sha256')}`",
+            f"- Key ID: `{signature.get('key_id')}`",
+            f"- Signature: `{signature.get('signature')}`",
+        ])
+    return "\n".join(lines) + "\n"