Restore v1 evidence compatibility and isolate bound-event v2

CHANGELOG.md

@@ -11,10 +11,14 @@ Why: keep static guard releases auditable while the package is still alpha.
   pattern-length limits. Timeout and limit failures remain deterministic,
   sanitized configuration errors; no raw pattern or context text is emitted.
 - Content-bound optional `agent-policy` audit-event references with a
-  canonical-JSON, profile-bound, public-safe digest. Producers now require a
-  reviewed repo-local event file and explicit profile, while consumers require
-  the separately supplied event and reject missing, malformed, or replaced
-  content. The event body remains outside the fixed seven-file public bundle.
+  canonical-JSON, profile-bound, public-safe digest. Producers require a
+  caller-designated repo-local JSON event and explicit profile; maintainer review
+  and event-schema validation remain external. Consumers require the separately
+  supplied event and reject missing, malformed, or replaced content. Audit-event
+  binding uses report and manifest v2; the released v1
+  schemas remain unchanged and their path-and-role references remain readable
+  as explicitly unbound legacy metadata. The event body remains outside the
+  fixed seven-file public bundle.
 - Defined a bounded demand-validation window through 2026-09-20 and froze
   feature releases pending an explicit maintainer decision after the 2026-09-21
   review. Marketplace publication remains separately prohibited without

README.md

@@ -356,7 +356,7 @@ event, add the same `--agent-policy-audit-event <reviewed-audit-event-path>` and
 both artifacts again after the producer has written the repo-local JSON event
 and a maintainer has reviewed it. The manifest records only a sanitized
 repository-relative path and a profile-bound canonical-content digest, not the
-event body. If the standalone manifest is present, the public bundle consumer
+event body. Audit events select evidence v2; event-free reports stay v1. If the standalone manifest is present, the public bundle consumer
 requires it to match the manifest embedded in the report. It also requires the
 event path and profile again to verify the binding. Keep the event outside
 `.agent-guard/evidence`: the seven-file public bundle allow-list rejects it.
@@ -694,9 +694,9 @@ For `report`, it returns:
   or context-lock coverage, digest, workflow, or policy/spec drift
 - exit `2` on configuration/runtime error
 
-Report output follows `agent-guard.report_evidence.v1`: the evidence payload is
-limited to deterministic scanner metadata and sanitized findings. The shared
-scanner JSON envelope remains `agent-guard.result.v1`.
+Event-free output follows `agent-guard.report_evidence.v1`; attaching a reviewed
+audit event selects `agent-guard.report_evidence.v2` with a bound v2 manifest.
+Both remain sanitized, inside the shared `agent-guard.result.v1` envelope.
 
 #### Packaged JSON schemas
 
@@ -709,13 +709,13 @@ files from the source tree:
   inventory evidence.
 - `agent-guard.context_lock_coverage.v1.schema.json`: hash-free context lock
   coverage evidence, including covered context files.
-- `agent-guard.report_evidence.v1.schema.json`: sanitized report evidence
-  payload for Markdown, JSON, GitHub annotation, and SARIF rendering, including
-  surface inventory and evidence coverage on success/violation payloads.
+- `agent-guard.report_evidence.v1.schema.json` (event-free) and
+  `agent-guard.report_evidence.v2.schema.json` (bound audit event): sanitized
+  report evidence, including surface inventory and evidence coverage.
 - `agent-guard.conformance.v1.schema.json`: profile evidence for `minimal`,
   `recommended`, and `strict` adoption levels.
-- `agent-guard.evidence_pack_manifest.v1.schema.json`: sanitized evidence
-  artifact manifest for reviewer handoff.
+- `agent-guard.evidence_pack_manifest.v1.schema.json` (legacy unbound) and
+  `agent-guard.evidence_pack_manifest.v2.schema.json` (bound): sanitized manifests.
 
 Installed wheels also include `agent-guard.surface_delta.v1.schema.json` for
 sanitized PR base/head agent surface delta evidence.

docs/compatibility.md

@@ -40,16 +40,18 @@ Installed wheels package these JSON Schema resources under
 | Shared result envelope | `agent-guard.result.v1` | `agent-guard.result.v1.schema.json` | none | `schema_version`, `tool`, `scanner`, `status`, `exit_code`, `policy`, `summary`, `finding_count`, `findings`, and optional `error`. |
 | Context inventory | `agent-guard.context_inventory.v1` | `agent-guard.context_inventory.v1.schema.json` | none | Repository-relative context file metadata and permission-boundary status. |
 | Context lock coverage | `agent-guard.context_lock_coverage.v1` | `agent-guard.context_lock_coverage.v1.schema.json` | none | Hash-free coverage counts, covered context files, and digest coverage findings. |
-| Sanitized report evidence | `agent-guard.report_evidence.v1` | `agent-guard.report_evidence.v1.schema.json` | none | Public-safe report JSON, including the embedded `report.schema_version` contract marker. |
+| Sanitized report evidence | `agent-guard.report_evidence.v1` | `agent-guard.report_evidence.v1.schema.json` | none | Public-safe report JSON without content-bound audit-event references. Existing v1 consumers remain supported. |
+| Sanitized report evidence | `agent-guard.report_evidence.v2` | `agent-guard.report_evidence.v2.schema.json` | none | Public-safe report JSON whose embedded evidence-pack manifest requires at least one bound `agent-policy` audit-event artifact. |
 | Conformance evidence | `agent-guard.conformance.v1` | `agent-guard.conformance.v1.schema.json` | none | Profile, status, required gates/surfaces, counts, and conformance findings. |
-| Evidence pack manifest | `agent-guard.evidence_pack_manifest.v1` | `agent-guard.evidence_pack_manifest.v1.schema.json` | none | Sanitized artifact manifest, gate summary, and optional conformance summary. |
+| Evidence pack manifest | `agent-guard.evidence_pack_manifest.v1` | `agent-guard.evidence_pack_manifest.v1.schema.json` | none | Sanitized artifact manifest, including legacy path-and-role audit-event references that are not content-bound. |
+| Evidence pack manifest | `agent-guard.evidence_pack_manifest.v2` | `agent-guard.evidence_pack_manifest.v2.schema.json` | none | Sanitized artifact manifest whose audit-event entries require a controlled profile and canonical-content digest. |
 | Surface delta evidence | `agent-guard.surface_delta.v1` | `agent-guard.surface_delta.v1.schema.json` | none | Sanitized PR base/head agent-surface delta: added/removed/modified surface entries with controlled-vocabulary `changed_fields` names and risk labels; no raw diffs, base ref names, or instruction/description bodies. |
 
 Standalone conformance and evidence-pack files use the
 `agent-guard.result.v1` outer envelope. The listed
-`agent-guard.conformance.v1` and `agent-guard.evidence_pack_manifest.v1`
-schemas apply to their nested `conformance` and `evidence_pack_manifest`
-members, respectively.
+`agent-guard.conformance.v1` and the selected evidence-pack manifest schema
+apply to their nested `conformance` and `evidence_pack_manifest` members,
+respectively.
 
 These schema file names and `$id` values are frozen by tests. A schema version
 will not change without a new schema identifier and a documented compatibility
@@ -79,20 +81,23 @@ with exit `2`; raw patterns, paths, or file contents are not included in the
 error. These ceilings are implementation safety limits, not evidence-schema
 fields or a promise of generic content/credential scanning.
 
-Optional `agent-policy` audit-event entries are an additive v1 manifest field:
-the existing required `path` and `role` fields retain their meaning, while new
-producer output adds `content_binding`. The binding uses canonical JSON, an
-explicit expected event profile, and a domain-separated SHA-256 digest encoded
-as lowercase base32 with a controlled `b` prefix. This controlled digest is not
-a raw hexadecimal hash and is the only hash-like value admitted on this field.
-Current packaged consumers fail closed when an audit-event role lacks the
-binding or when the separately supplied event does not match. Older v1
-consumers may ignore the optional field, so callers that require content
-binding must use a consumer version that documents this contract. The event
-profile identifies the caller-selected contract but does not itself validate
-the event against an `agent-policy` JSON Schema; that remains producer-owned.
-The event body remains outside the fixed public bundle. Replacing both a
-trusted manifest and its event is outside this binding's threat model.
+Optional `agent-policy` audit-event content binding uses report and manifest v2.
+The producer emits v2 only when at least one caller-designated event is attached; reports
+without an event continue to use v1. Released v1 path-and-role references remain
+structurally valid legacy metadata, but they are explicitly unbound. A current
+consumer can read that v1 evidence, but fails closed if a caller asks it to
+verify event content against the unbound reference.
+
+V2 requires at least one audit-event artifact and `content_binding` on every
+audit-event entry. The binding uses canonical JSON, an explicit expected event profile, and a domain-separated
+SHA-256 digest encoded as lowercase base32 with a controlled `b` prefix. This
+controlled digest is not a raw hexadecimal hash and is the only hash-like value
+admitted on this field. Current consumers fail closed when the separately
+supplied event or expected profile does not match. The profile identifies the
+caller-selected contract but does not itself validate the event against an
+`agent-policy` JSON Schema; that remains producer-owned. The event body remains
+outside the fixed public bundle. Replacing both a trusted manifest and its event
+is outside this binding's threat model.
 
 Workflow inputs use the same fail-closed approach. Workflow policies are capped
 at 256 KiB, individual policy strings at 4 KiB, and workflow files at 1 MiB.
@@ -223,7 +228,7 @@ future `0.x` releases:
   requires a new schema identifier and an explicit release-note compatibility
   decision.
 
-Consumers should fail closed on unknown top-level schema versions, but they
-should tolerate additional optional properties allowed by the schema. The
-packaged `agent_guard.consumer` module demonstrates that policy for sanitized
-report evidence.
+`load_report_schema()` remains an explicit v1 pin. Callers opting into supported
+version dispatch pass `select_report_schema(payload)` to `validate_report`.
+Unknown versions fail closed; allowed optional properties remain tolerated. The
+packaged consumer CLI applies that policy to sanitized report evidence.

docs/evidence-contracts.md

@@ -18,16 +18,16 @@ Installed wheels package these JSON Schema resources under
   discovered agent context files.
 - `agent-guard.context_lock_coverage.v1.schema.json`: hash-free evidence that
   discovered agent context files are pinned by digest policy.
-- `agent-guard.report_evidence.v1.schema.json`: the sanitized report payload
-  used by Markdown, JSON, and GitHub annotation output. Successful and
-  violation reports include agent surface inventory and evidence coverage.
+- `agent-guard.report_evidence.v1.schema.json` (event-free) and
+  `agent-guard.report_evidence.v2.schema.json` (bound audit event): sanitized
+  report payloads with agent surface inventory and evidence coverage.
 - `agent-guard.conformance.v1.schema.json`: profile evidence for `minimal`,
   `recommended`, and `strict` adoption levels. The `recommended` profile
   requires the first-class `mcp_config` gate; the `strict` profile can also fail
   on deterministic malformed MCP config or risk metadata emitted by the v2
   surface inventory.
-- `agent-guard.evidence_pack_manifest.v1.schema.json`: a sanitized manifest of
-  report artifacts and evidence counts for pull request review.
+- `agent-guard.evidence_pack_manifest.v1.schema.json` (legacy unbound) and
+  `agent-guard.evidence_pack_manifest.v2.schema.json` (bound): sanitized manifests.
 
 Installed wheels also include `agent-guard.surface_delta.v1.schema.json`. The
 schema covers sanitized PR base/head agent surface delta evidence emitted by
@@ -112,8 +112,8 @@ Move to recommended evidence after the starter files are reviewed:
    require those repository-specific gates unless supplied.
 4. Pair the static report with a runtime admission event from `agent-policy`
    when the repository uses an agent hook or wrapper before side effects. Pass
-   that event only as an artifact reference; `agent-guard` does not read or
-   embed the event body.
+   that event only as an artifact reference; `agent-guard` reads and
+   canonicalizes it locally, but does not embed or publish the event body.
 5. Review the evidence as a maintainer aid, not as a model-generated verdict.
 
 Example commands for a new repository. Review the `init --print` plan before
@@ -165,7 +165,8 @@ python examples/evidence_consumer.py \
 
 The referenced event must already be produced, reviewed, and stored as a
 repo-local regular JSON file. Pass the identical path and explicit expected
-profile to both producers. The manifest records a sanitized repository-relative
+profile to both producers. Events select v2; event-free reports stay v1. The
+manifest records a sanitized repository-relative
 path and a profile-bound digest. `agent-guard` reads and canonicalizes the
 bounded event JSON locally to compute that binding, but never embeds the event
 body. The consumer requires the event separately and fails closed when the
@@ -229,9 +230,9 @@ The JSON report is a compact statement of what `agent-guard` checked:
   evidence-pack expectations part of conformance.
 - Optional `evidence_pack_manifest` records the sanitized artifact manifest for
   reviewer handoff. Artifact roles are limited to `report` and
-  `agent-policy-audit-event`. Audit-event entries include a controlled binding
-  profile and public-safe canonical-content digest; consumers verify the event
-  supplied outside the public bundle.
+  `agent-policy-audit-event`. V2 entries include a controlled binding profile
+  and public-safe canonical-content digest for the separately supplied event;
+  legacy v1 references remain readable but cannot satisfy content verification.
 - `context_lock` records whether discovered context files are covered by digest
   policy, without emitting hash values.
 - Optional `path`, `content`, `api`, `digest`, and `workflow` sections summarize