agentversion 0.2.1__tar.gz → 0.2.3__tar.gz

agentversion-0.2.3/.gitignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test, lint and type-check caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.benchmarks/
+.deepeval/
+.coverage
+.coverage.*
+coverage.xml
+coverage/
+htmlcov/
+
+# Node
+node_modules/
+.next/
+*.log
+
+# Environment files. Real credentials never belong in the tree;
+# .env.example is the tracked template, so it is re-included.
+.env
+.env.*
+!.env.example
+
+# Editors
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local agent/tool state
+.claude/settings.local.json

{agentversion-0.2.1 → agentversion-0.2.3}/CHANGELOG.md

@@ -7,13 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 > **Package version ≠ spec version.** This file tracks the **package** version. The on-the-wire `spec_version` is independent and frozen at `1.0.0`; a pre-1.0 package can implement a stable 1.0 spec, which is exactly the situation today.
 
+## [0.2.3] - 2026-08-14
+
+Packaging and documentation only. **No code, schema, or `spec_version` change** — the
+on-the-wire spec stays frozen at 1.0.0 and every hash vector is unchanged.
+
+### Fixed
+- **The source distribution now builds a wheel.** The sdist previously packed whatever the
+  working tree happened to contain, and omitted `schemas/`, `spec/`, `examples/` and
+  `compatibility-tests/` — the directories the wheel pulls in via `force-include`. The sdist
+  itself still built, so the gap only surfaced one step later: building a **wheel from that
+  sdist** failed, which is exactly what `uv build` and downstream packagers do. The sdist now
+  ships an explicit allow-list covering those sources.
+- **The conformance fixtures now validate against the published schema.** They had drifted
+  from the schema shipped in the package, so a consumer validating the fixtures as a
+  self-check would see spurious failures.
+
+### Changed
+- Spec wording and README claims tightened to match what the package actually implements.
+
+## [0.2.2] - 2026-07-15
+
+### Changed
+- **`behavioral_policy` re-scoped as a generic versioned policy-document surface** (docs only).
+  The surface previously described itself as bound to skillevaluation's conversation-mode
+  `policy_check` state machine; that eval mode was removed (skillevaluation ADR-0007), so the
+  docstrings + `spec/behavioral-policy.md` now define it document-agnostically: `policy_hash` is a
+  hash of *any* bound policy artifact (refund rules, a safety guardrail set, an escalation SOP…),
+  a rule change diffs **breaking**, an unchanged `policy_hash` is non-breaking. **No code or schema
+  change**: the `BehavioralPolicy` model still carries `objection_threshold`/`concede_events`/
+  `always_forbidden` (now documented as optional, illustrative, back-compat rule fields), the
+  `_BEHAVIORAL_POLICY_RULE_FIELDS` diff logic is byte-identical, and every frozen hash-vector +
+  the 406-test suite are unchanged. `spec_version` unchanged (1.0.0).
+
 ## [0.2.1] - 2026-06-24
 
 ### Fixed
 - **`contract_from_components` now emits the `behavioral_policy` and
   `environment` surfaces.** 0.2.0 added the models, surface keys, and diff
   classifiers, but the shared flat-components → contract assembler silently
-  dropped both — so a producer (the DecimalAI SDK / the platform) could never
+  dropped both — so a producer (e.g. an SDK exporter) could never
   actually populate them from components. They are now assembled verbatim from
   each component's `schema_json`. Additive-only: a manifest that doesn't declare
   them is unchanged (same `overall_hash`).
@@ -43,7 +76,7 @@ byte-identically and is pinned to this assembly by its conformance test.
 - **Extension hatch** (`AgentContract` is now `extra="allow"`): a custom / emerging contract surface
   (RAG corpus, MCP server registry, memory policy, vendor extension) is hashed by the hasher and diffed
   by the engine, and now also **survives `model_validate`** — previously it was silently dropped, so a
-  validate→re-serialize→re-hash round-trip changed `overall_hash` (a moat-breaking non-determinism). The
+  validate→re-serialize→re-hash round-trip changed `overall_hash` (a hash-determinism break). The
   surface set can grow without forking the model. ASCII/known-surface hashes are unchanged.
 - **`COMPONENT_TYPE_TO_SURFACE` + `surface_key_for_component()`** — the canonical routing from a
   producer's flat `component_type` to the contract surface key it lands in (incl. the singular→plural
@@ -51,17 +84,15 @@ byte-identically and is pinned to this assembly by its conformance test.
   translator) share one source of truth instead of hand-copying the map — closing a cross-stack drift
   class where the rename had to be applied independently in every translator copy.
 - **`contract.contract_from_components()`** — the single source of truth for assembling a contract block
-  (every surface, in canonical shape) from a producer's flat component list. Both the DecimalAI SDK
-  exporter and the platform's hash path route through it, so they compute the *same* `jcs-sha256`
-  identity hash for the same agent — the platform can now make the canonical hash authoritative and a
-  customer reproduces the stored hash with the OSS CLI. Closes audit X-2 (two hand-written translators
-  with no shared code/test).
+  (every surface, in canonical shape) from a producer's flat component list, so any producer computes the
+  same `jcs-sha256` identity hash for the same agent and a manifest's stored hash reproduces with the
+  OSS CLI.
 
 ### Fixed (hash-determinism + trust)
 - **Canonical-hash domain** (`hasher.py`): NFC-normalize every string (keys + values) and reject
   non-finite floats (`NaN`/`±Infinity`) **before** JCS canonicalization. JCS canonicalizes bytes but
   does not Unicode-normalize, so a composed `"café"` and a decomposed `"café"` previously produced a
-  different `overall_hash` for the same agent (a cross-language reproduction break in the moat); and a
+  different `overall_hash` for the same agent (a cross-language reproduction break); and a
   `NaN` raised an opaque `jcs` error instead of a clear domain error. NFC of ASCII is a no-op, so
   **existing manifest hashes are unchanged** (frozen vectors still pass). Documented in `spec/hashing.md`.
 - **Attestation integrity** (`validator.py`): an attestation's `signed_payload_hash` must equal the
@@ -123,7 +154,7 @@ byte-identically and is pinned to this assembly by its conformance test.
 
 **First published release** — the first `agentversion` release on PyPI.
 
-The package ships pre-1.0 on purpose. The spec it implements is stable (`spec_version 1.0.0`, with a frozen wire format and conformance suite), but the Python package API hasn't earned its own 1.0 promise yet — so it enters at `0.1.0` (`Development Status :: 4 - Beta`). Feature-wise it's complete against the original audit roadmap; that work landed across the internal milestones listed further below, none of which were ever published.
+The package ships pre-1.0 on purpose. The spec it implements is stable (`spec_version 1.0.0`, with a frozen wire format and conformance suite), but the Python package API hasn't earned its own 1.0 promise yet — so it enters at `0.1.0` (`Development Status :: 4 - Beta`). Feature-wise it's complete against the original capability roadmap; that work landed across the internal milestones listed further below, none of which were ever published.
 
 ### Changed — Project renamed to **AgentVersion**
 
@@ -146,7 +177,7 @@ The entries below were development milestones tracked in-repo on the way to feat
 
 ### 1.0.0 - 2026-05-12 (internal milestone)
 
-**Feature-complete milestone** (never published). The audit roadmap reached feature-completeness at this internal version; the stability promise it anticipated now lives on the spec, which is frozen at `1.0.0`.
+**Feature-complete milestone** (never published). The capability roadmap reached feature-completeness at this internal version; the stability promise it anticipated now lives on the spec, which is frozen at `1.0.0`.
 
 ### What v1.0 looks like
 
@@ -192,7 +223,7 @@ Trust + observability + governance batch. The last three §3 items.
 - avs total: **295 passing** (was 278, net +17).
 
 ### Phase 3 complete
-All 14 missing-capability items from the original audit §3 are now shipped (or, in the case of §3l, were folded into Phase 2). The spec is feature-complete for the audit roadmap. Next milestone: **v1.0** — tighten enforcement (drop permissive ID pattern, drop bare-ID manifest_refs), publish to PyPI.
+All 14 capability items (§3a–§3n) are now shipped, except §3l, which ships no standalone surface of its own. The spec is feature-complete for that roadmap. Next milestone: **v1.0** — tighten enforcement (drop permissive ID pattern, drop bare-ID manifest_refs), publish to PyPI.
 
 ### 0.8.0 - 2026-05-12
 

{agentversion-0.2.1 → agentversion-0.2.3}/CONFORMANCE.md

@@ -23,20 +23,14 @@ Located under [`compatibility-tests/`](./compatibility-tests/). Each subdirector
 
 ```
 compatibility-tests/
-  tool-rename/
+  <scenario-name>/
     before.json          # input manifest A
     after.json           # input manifest B
     expected-diff.json   # ManifestDiff produced by a conforming implementation
-  output-schema-change/
-    before.json
-    after.json
-    expected-diff.json
-  subagent-handoff-change/
-    before.json
-    after.json
-    expected-diff.json
 ```
 
+Every subdirectory of `compatibility-tests/` is a scenario and all of them are normative — run the directory, not a fixed list.
+
 The Python reference verifies conformance via `tests/test_conformance.py`. To verify an implementation in another language:
 
 1. For each scenario, load `before.json` and `after.json`.

{agentversion-0.2.1 → agentversion-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: agentversion
-Version: 0.2.1
+Version: 0.2.3
 Summary: An open specification for versioning agent runtimes and keeping datasets valid.
 Project-URL: Homepage, https://github.com/decimal-labs/agentversion
 Project-URL: Documentation, https://github.com/decimal-labs/agentversion/tree/main/spec
@@ -35,12 +35,16 @@ Description-Content-Type: text/markdown
 
 # AgentVersion
 
+*Part of [DecimalAI](https://decimal.ai). Most users want the Python SDK → [decimal-labs/decimalai-python](https://github.com/decimal-labs/decimalai-python).*
+
 **Your agent changed. Is your saved data still valid?**
 
 [![PyPI](https://img.shields.io/pypi/v/agentversion)](https://pypi.org/project/agentversion/)
+[![Downloads](https://static.pepy.tech/badge/agentversion/month)](https://pepy.tech/project/agentversion)
+[![CI](https://img.shields.io/github/actions/workflow/status/decimal-labs/agentversion/ci.yml?branch=main)](https://github.com/decimal-labs/agentversion/actions/workflows/ci.yml)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/agentversion/)
 [![Spec](https://img.shields.io/badge/spec-v1.0-success)](https://pypi.org/project/agentversion/)
-[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://pypi.org/project/agentversion/)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/decimal-labs/agentversion/blob/main/LICENSE)
 
 When you ship a new version of an agent, everything you collected against the old one — production traces, eval datasets, SFT (supervised fine-tuning) examples — quietly drifts out of date. There's no `package.json` to pin an agent's contract, and no `git diff` to tell you what changed.
 
@@ -148,7 +152,9 @@ A manifest is plain JSON. The top says *which* version this is; `contract` holds
 
 Each surface is hashed on its own, so the diff can say *"`tool_registry` changed, `prompt_stack` didn't"* instead of just *"the manifest changed."*
 
-> Try it yourself — both [`examples/manifest/`](https://pypi.org/project/agentversion/) manifests ship inside the `agentversion` wheel.
+> Try it yourself — both [`examples/manifest/`](https://github.com/decimal-labs/agentversion/tree/main/examples/manifest)
+> manifests ship inside the `agentversion` wheel as well as in the repo; the commands below use the
+> repo-relative paths, so clone first.
 
 ---
 
@@ -158,7 +164,7 @@ You probably already have observability and a trace store. None of them answer *
 
 | You already have | What it gives you | What it doesn't |
 |---|---|---|
-| OpenTelemetry / LangSmith / Langfuse | rich execution traces | a versioned contract for the agent that produced them |
+| OpenTelemetry and the tracing tools built on it | rich execution traces | a versioned contract for the agent that produced them |
 | A2A / ACP agent cards | runtime discovery + I/O types | version identity or data-compatibility |
 | OpenAI JSONL / SFT files | a training format | provenance — *which agent version* produced each row |
 
@@ -177,7 +183,7 @@ Apache-2.0, no config — just needs Python 3.10+.
 There are **two version numbers**, deliberately different:
 
 - the **wire spec** is frozen at **v1.0** (stable format + conformance suite — safe to build against);
-- this **Python package** is **0.1.0** — pre-1.0, so its API may still shift.
+- this **Python package** is still **pre-1.0**, so its API may still shift.
 
 (The `spec-v1.0` and PyPI badges above show each one.)
 
@@ -201,9 +207,11 @@ agentversion hash manifest.json       # a content hash that ignores key order an
 agentversion validate manifest.json   # check it against the spec
 ```
 
-**3. Diff two versions** — runnable right now against the bundled examples (`--compat` adds the keep/repair/replay/drop recommendation; `--json` for machine output):
+**3. Diff two versions** — against the bundled examples. The paths are relative, so run this from a
+checkout (`--compat` adds the keep/repair/replay/drop recommendation; `--json` for machine output):
 
 ```bash
+git clone https://github.com/decimal-labs/agentversion && cd agentversion
 agentversion diff examples/manifest/finance-agent-v1.json \
                   examples/manifest/finance-agent-v2.json --compat
 ```
@@ -216,7 +224,7 @@ agentversion diff examples/manifest/finance-agent-v1.json \
   run: agentversion diff baseline-manifest.json current-manifest.json --fail-on-breaking
 ```
 
-**Use it from Python** — every line below is exercised by the test suite:
+**Use it from Python** — every API below is covered by the test suite:
 
 ```python
 import json
@@ -224,17 +232,20 @@ from agentversion import AgentManifest, validate_manifest_file, hash_manifest
 from agentversion.diff import diff_manifests
 from agentversion.compatibility import classify_compatibility
 
-old = json.load(open("finance-agent-v1.json"))
-new = json.load(open("finance-agent-v2.json"))
+old = json.load(open("examples/manifest/finance-agent-v1.json"))
+new = json.load(open("examples/manifest/finance-agent-v2.json"))
 
 # Validate + identify a version
-assert validate_manifest_file("finance-agent-v2.json").valid
+assert validate_manifest_file("examples/manifest/finance-agent-v2.json").valid
 m = AgentManifest.model_validate(new)
 print(m.agent_name, m.identity.overall_hash)   # finance-agent  sha256:767ebff1...
 
 # Diff, then ask what to do with old data
 result = diff_manifests(old, new)
 print(result.summary.breaking_surfaces)                       # 5
+
+# Pass no policy and the built-in fallback rules apply. They are deliberately
+# non-destructive: the worst they will ever recommend is replay, never drop.
 print(classify_compatibility(result).recommended_decision)   # replay
 ```
 
@@ -267,10 +278,10 @@ The protocol is fully useful standalone:
 
 1. **Track versions locally** — `init` to scaffold, `hash` for a stable id, `diff` between any two. No account, fully offline.
 2. **Gate CI/CD** — `diff --fail-on-breaking` stops a breaking agent change from reaching production.
-3. **Annotate traces** — stamp `identity.overall_hash` onto your OpenTelemetry spans as `agentversion.manifest_hash` for version-scoped filtering. See [`examples/integrations/otel_mapping.md`](https://pypi.org/project/agentversion/), bundled in the package.
+3. **Annotate traces** — stamp `identity.overall_hash` onto your OpenTelemetry spans as `agentversion.manifest_hash` for version-scoped filtering. See [`examples/integrations/otel_mapping.md`](https://github.com/decimal-labs/agentversion/blob/main/examples/integrations/otel_mapping.md), bundled in the package.
 4. **Classify data compatibility** — `diff --compat` (or `decision generate`) gives a per-episode keep / repair / replay / drop verdict you can act on.
 
-It interoperates with LangSmith, Langfuse, Phoenix, and W&B — annotate their traces/datasets with a manifest hash, or read/write compatibility decisions alongside your eval pipeline.
+A manifest hash is just a string, so it drops into whatever trace store or eval tool you already run — put `identity.overall_hash` on the spans or dataset rows you keep, and the compatibility decisions sit alongside your eval pipeline as ordinary JSON.
 
 ---
 
@@ -278,13 +289,13 @@ It interoperates with LangSmith, Langfuse, Phoenix, and W&B — annotate their t
 
 `agentversion` is an open spec so any tool, in any language, can produce interoperable manifests and diffs:
 
-- [`spec/manifest.md`](https://pypi.org/project/agentversion/) — the agent manifest
-- [`spec/diff.md`](https://pypi.org/project/agentversion/) — surface diffs, breaking vs non-breaking
-- [`spec/compatibility-decision.md`](https://pypi.org/project/agentversion/) — keep / repair / replay / drop
-- [`spec/replay.md`](https://pypi.org/project/agentversion/) · [`spec/dataset.md`](https://pypi.org/project/agentversion/) — replay jobs and dataset objects with provenance
-- [`spec/reference.md`](https://pypi.org/project/agentversion/) — full schemas and validation rules · [`schemas/`](https://pypi.org/project/agentversion/) — JSON Schemas
+- [`spec/manifest.md`](https://github.com/decimal-labs/agentversion/blob/main/spec/manifest.md) — the agent manifest
+- [`spec/diff.md`](https://github.com/decimal-labs/agentversion/blob/main/spec/diff.md) — surface diffs, breaking vs non-breaking
+- [`spec/compatibility-decision.md`](https://github.com/decimal-labs/agentversion/blob/main/spec/compatibility-decision.md) — keep / repair / replay / drop
+- [`spec/replay.md`](https://github.com/decimal-labs/agentversion/blob/main/spec/replay.md) · [`spec/dataset.md`](https://github.com/decimal-labs/agentversion/blob/main/spec/dataset.md) — replay jobs and dataset objects with provenance
+- [`spec/reference.md`](https://github.com/decimal-labs/agentversion/blob/main/spec/reference.md) — full schemas and validation rules · [`schemas/`](https://github.com/decimal-labs/agentversion/tree/main/schemas) — JSON Schemas
 
-The full spec and JSON Schemas ship inside the `agentversion` wheel. [`CONFORMANCE.md`](https://pypi.org/project/agentversion/) + [`compatibility-tests/`](https://pypi.org/project/agentversion/) are golden in/out pairs that any implementation must reproduce to claim conformance.
+The full spec and JSON Schemas ship inside the `agentversion` wheel. [`CONFORMANCE.md`](https://github.com/decimal-labs/agentversion/blob/main/CONFORMANCE.md) + [`compatibility-tests/`](https://github.com/decimal-labs/agentversion/tree/main/compatibility-tests) are golden in/out pairs that any implementation must reproduce to claim conformance.
 
 ---
 
@@ -303,7 +314,7 @@ A manifest can carry the eval results that gated its release in `evaluation.gate
 }
 ```
 
-Those scores come from [`skillevaluation`](https://pypi.org/project/skillevaluation/), the sibling open spec for A/B benchmarking skills. `agentversion` records *what an agent version is*; `skillevaluation` measures *whether it's better*.
+Those scores come from [`skillevaluation`](https://github.com/decimal-labs/skillevaluation), the sibling open spec: `agentversion` versions the agent runtime itself (what an agent version *is* and what changed), while `skillevaluation` A/B-benchmarks a single skill (whether it actually helps).
 
 The [`decimalai`](https://pypi.org/project/decimalai/) Python SDK builds on `agentversion` to add framework adapters (capture a manifest straight from your LangGraph/CrewAI app), trace capture, and managed replay — but you never need it to use the spec.
 
@@ -332,13 +343,13 @@ diff = diff_manifests(last_prod_manifest, manifest)
 print(classify_compatibility(diff).recommended_decision)
 ```
 
-This is the seam that makes `agentversion` the **open core** of the paid platform: the manifest the SDK captures *is* the format `agentversion diff` consumes, so you can reproduce the platform's diffs and verdicts entirely outside DecimalAI. A runnable version is in [`examples/integrations/decimalai_bridge.py`](https://pypi.org/project/agentversion/).
+This is the seam that makes `agentversion` the **open core** of the paid platform: the manifest the SDK captures *is* the format `agentversion diff` consumes, so you can reproduce the platform's diffs and verdicts entirely outside DecimalAI. A runnable version is in [`examples/integrations/decimalai_bridge.py`](https://github.com/decimal-labs/agentversion/blob/main/examples/integrations/decimalai_bridge.py).
 
 ---
 
 ## Project
 
-The spec is frozen at v1.0; the package is pre-1.0 (see [Install](#install)). Design decisions are logged in [`adrs/`](https://pypi.org/project/agentversion/), releases in [`CHANGELOG.md`](https://pypi.org/project/agentversion/). Contributions — especially new conformance cases — are genuinely welcome; see [`CONTRIBUTING.md`](https://pypi.org/project/agentversion/):
+The spec is frozen at v1.0; the package is pre-1.0 (see [Install](#install)). Design decisions are logged in [`adrs/`](https://github.com/decimal-labs/agentversion/tree/main/adrs), releases in [`CHANGELOG.md`](https://github.com/decimal-labs/agentversion/blob/main/CHANGELOG.md). Contributions — especially new conformance cases — are genuinely welcome; see [`CONTRIBUTING.md`](https://github.com/decimal-labs/agentversion/blob/main/CONTRIBUTING.md):
 
 ```bash
 pip install agentversion
@@ -348,4 +359,8 @@ git clone https://github.com/decimal-labs/agentversion && cd agentversion
 pip install -e ".[dev]" && pytest
 ```
 
-Licensed under [Apache 2.0](https://pypi.org/project/agentversion/).
+Licensed under [Apache 2.0](https://github.com/decimal-labs/agentversion/blob/main/LICENSE).
+
+---
+
+[Docs](https://docs.decimal.ai) · [Registry](https://app.decimal.ai/skills) · [SDK](https://github.com/decimal-labs/decimalai-python) · [skillevaluation](https://github.com/decimal-labs/skillevaluation) · [regression-check](https://github.com/decimal-labs/regression-check)

{agentversion-0.2.1 → agentversion-0.2.3}/README.md

@@ -1,11 +1,15 @@
 # AgentVersion
 
+*Part of [DecimalAI](https://decimal.ai). Most users want the Python SDK → [decimal-labs/decimalai-python](https://github.com/decimal-labs/decimalai-python).*
+
 **Your agent changed. Is your saved data still valid?**
 
 [![PyPI](https://img.shields.io/pypi/v/agentversion)](https://pypi.org/project/agentversion/)
+[![Downloads](https://static.pepy.tech/badge/agentversion/month)](https://pepy.tech/project/agentversion)
+[![CI](https://img.shields.io/github/actions/workflow/status/decimal-labs/agentversion/ci.yml?branch=main)](https://github.com/decimal-labs/agentversion/actions/workflows/ci.yml)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/agentversion/)
 [![Spec](https://img.shields.io/badge/spec-v1.0-success)](https://pypi.org/project/agentversion/)
-[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://pypi.org/project/agentversion/)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/decimal-labs/agentversion/blob/main/LICENSE)
 
 When you ship a new version of an agent, everything you collected against the old one — production traces, eval datasets, SFT (supervised fine-tuning) examples — quietly drifts out of date. There's no `package.json` to pin an agent's contract, and no `git diff` to tell you what changed.
 
@@ -113,7 +117,9 @@ A manifest is plain JSON. The top says *which* version this is; `contract` holds
 
 Each surface is hashed on its own, so the diff can say *"`tool_registry` changed, `prompt_stack` didn't"* instead of just *"the manifest changed."*
 
-> Try it yourself — both [`examples/manifest/`](https://pypi.org/project/agentversion/) manifests ship inside the `agentversion` wheel.
+> Try it yourself — both [`examples/manifest/`](https://github.com/decimal-labs/agentversion/tree/main/examples/manifest)
+> manifests ship inside the `agentversion` wheel as well as in the repo; the commands below use the
+> repo-relative paths, so clone first.
 
 ---
 
@@ -123,7 +129,7 @@ You probably already have observability and a trace store. None of them answer *
 
 | You already have | What it gives you | What it doesn't |
 |---|---|---|
-| OpenTelemetry / LangSmith / Langfuse | rich execution traces | a versioned contract for the agent that produced them |
+| OpenTelemetry and the tracing tools built on it | rich execution traces | a versioned contract for the agent that produced them |
 | A2A / ACP agent cards | runtime discovery + I/O types | version identity or data-compatibility |
 | OpenAI JSONL / SFT files | a training format | provenance — *which agent version* produced each row |
 
@@ -142,7 +148,7 @@ Apache-2.0, no config — just needs Python 3.10+.
 There are **two version numbers**, deliberately different:
 
 - the **wire spec** is frozen at **v1.0** (stable format + conformance suite — safe to build against);
-- this **Python package** is **0.1.0** — pre-1.0, so its API may still shift.
+- this **Python package** is still **pre-1.0**, so its API may still shift.
 
 (The `spec-v1.0` and PyPI badges above show each one.)
 
@@ -166,9 +172,11 @@ agentversion hash manifest.json       # a content hash that ignores key order an
 agentversion validate manifest.json   # check it against the spec
 ```
 
-**3. Diff two versions** — runnable right now against the bundled examples (`--compat` adds the keep/repair/replay/drop recommendation; `--json` for machine output):
+**3. Diff two versions** — against the bundled examples. The paths are relative, so run this from a
+checkout (`--compat` adds the keep/repair/replay/drop recommendation; `--json` for machine output):
 
 ```bash
+git clone https://github.com/decimal-labs/agentversion && cd agentversion
 agentversion diff examples/manifest/finance-agent-v1.json \
                   examples/manifest/finance-agent-v2.json --compat
 ```
@@ -181,7 +189,7 @@ agentversion diff examples/manifest/finance-agent-v1.json \
   run: agentversion diff baseline-manifest.json current-manifest.json --fail-on-breaking
 ```
 
-**Use it from Python** — every line below is exercised by the test suite:
+**Use it from Python** — every API below is covered by the test suite:
 
 ```python
 import json
@@ -189,17 +197,20 @@ from agentversion import AgentManifest, validate_manifest_file, hash_manifest
 from agentversion.diff import diff_manifests
 from agentversion.compatibility import classify_compatibility
 
-old = json.load(open("finance-agent-v1.json"))
-new = json.load(open("finance-agent-v2.json"))
+old = json.load(open("examples/manifest/finance-agent-v1.json"))
+new = json.load(open("examples/manifest/finance-agent-v2.json"))
 
 # Validate + identify a version
-assert validate_manifest_file("finance-agent-v2.json").valid
+assert validate_manifest_file("examples/manifest/finance-agent-v2.json").valid
 m = AgentManifest.model_validate(new)
 print(m.agent_name, m.identity.overall_hash)   # finance-agent  sha256:767ebff1...
 
 # Diff, then ask what to do with old data
 result = diff_manifests(old, new)
 print(result.summary.breaking_surfaces)                       # 5
+
+# Pass no policy and the built-in fallback rules apply. They are deliberately
+# non-destructive: the worst they will ever recommend is replay, never drop.
 print(classify_compatibility(result).recommended_decision)   # replay
 ```
 
@@ -232,10 +243,10 @@ The protocol is fully useful standalone:
 
 1. **Track versions locally** — `init` to scaffold, `hash` for a stable id, `diff` between any two. No account, fully offline.
 2. **Gate CI/CD** — `diff --fail-on-breaking` stops a breaking agent change from reaching production.
-3. **Annotate traces** — stamp `identity.overall_hash` onto your OpenTelemetry spans as `agentversion.manifest_hash` for version-scoped filtering. See [`examples/integrations/otel_mapping.md`](https://pypi.org/project/agentversion/), bundled in the package.
+3. **Annotate traces** — stamp `identity.overall_hash` onto your OpenTelemetry spans as `agentversion.manifest_hash` for version-scoped filtering. See [`examples/integrations/otel_mapping.md`](https://github.com/decimal-labs/agentversion/blob/main/examples/integrations/otel_mapping.md), bundled in the package.
 4. **Classify data compatibility** — `diff --compat` (or `decision generate`) gives a per-episode keep / repair / replay / drop verdict you can act on.
 
-It interoperates with LangSmith, Langfuse, Phoenix, and W&B — annotate their traces/datasets with a manifest hash, or read/write compatibility decisions alongside your eval pipeline.
+A manifest hash is just a string, so it drops into whatever trace store or eval tool you already run — put `identity.overall_hash` on the spans or dataset rows you keep, and the compatibility decisions sit alongside your eval pipeline as ordinary JSON.
 
 ---
 
@@ -243,13 +254,13 @@ It interoperates with LangSmith, Langfuse, Phoenix, and W&B — annotate their t
 
 `agentversion` is an open spec so any tool, in any language, can produce interoperable manifests and diffs:
 
-- [`spec/manifest.md`](https://pypi.org/project/agentversion/) — the agent manifest
-- [`spec/diff.md`](https://pypi.org/project/agentversion/) — surface diffs, breaking vs non-breaking
-- [`spec/compatibility-decision.md`](https://pypi.org/project/agentversion/) — keep / repair / replay / drop
-- [`spec/replay.md`](https://pypi.org/project/agentversion/) · [`spec/dataset.md`](https://pypi.org/project/agentversion/) — replay jobs and dataset objects with provenance
-- [`spec/reference.md`](https://pypi.org/project/agentversion/) — full schemas and validation rules · [`schemas/`](https://pypi.org/project/agentversion/) — JSON Schemas
+- [`spec/manifest.md`](https://github.com/decimal-labs/agentversion/blob/main/spec/manifest.md) — the agent manifest
+- [`spec/diff.md`](https://github.com/decimal-labs/agentversion/blob/main/spec/diff.md) — surface diffs, breaking vs non-breaking
+- [`spec/compatibility-decision.md`](https://github.com/decimal-labs/agentversion/blob/main/spec/compatibility-decision.md) — keep / repair / replay / drop
+- [`spec/replay.md`](https://github.com/decimal-labs/agentversion/blob/main/spec/replay.md) · [`spec/dataset.md`](https://github.com/decimal-labs/agentversion/blob/main/spec/dataset.md) — replay jobs and dataset objects with provenance
+- [`spec/reference.md`](https://github.com/decimal-labs/agentversion/blob/main/spec/reference.md) — full schemas and validation rules · [`schemas/`](https://github.com/decimal-labs/agentversion/tree/main/schemas) — JSON Schemas
 
-The full spec and JSON Schemas ship inside the `agentversion` wheel. [`CONFORMANCE.md`](https://pypi.org/project/agentversion/) + [`compatibility-tests/`](https://pypi.org/project/agentversion/) are golden in/out pairs that any implementation must reproduce to claim conformance.
+The full spec and JSON Schemas ship inside the `agentversion` wheel. [`CONFORMANCE.md`](https://github.com/decimal-labs/agentversion/blob/main/CONFORMANCE.md) + [`compatibility-tests/`](https://github.com/decimal-labs/agentversion/tree/main/compatibility-tests) are golden in/out pairs that any implementation must reproduce to claim conformance.
 
 ---
 
@@ -268,7 +279,7 @@ A manifest can carry the eval results that gated its release in `evaluation.gate
 }
 ```
 
-Those scores come from [`skillevaluation`](https://pypi.org/project/skillevaluation/), the sibling open spec for A/B benchmarking skills. `agentversion` records *what an agent version is*; `skillevaluation` measures *whether it's better*.
+Those scores come from [`skillevaluation`](https://github.com/decimal-labs/skillevaluation), the sibling open spec: `agentversion` versions the agent runtime itself (what an agent version *is* and what changed), while `skillevaluation` A/B-benchmarks a single skill (whether it actually helps).
 
 The [`decimalai`](https://pypi.org/project/decimalai/) Python SDK builds on `agentversion` to add framework adapters (capture a manifest straight from your LangGraph/CrewAI app), trace capture, and managed replay — but you never need it to use the spec.
 
@@ -297,13 +308,13 @@ diff = diff_manifests(last_prod_manifest, manifest)
 print(classify_compatibility(diff).recommended_decision)
 ```
 
-This is the seam that makes `agentversion` the **open core** of the paid platform: the manifest the SDK captures *is* the format `agentversion diff` consumes, so you can reproduce the platform's diffs and verdicts entirely outside DecimalAI. A runnable version is in [`examples/integrations/decimalai_bridge.py`](https://pypi.org/project/agentversion/).
+This is the seam that makes `agentversion` the **open core** of the paid platform: the manifest the SDK captures *is* the format `agentversion diff` consumes, so you can reproduce the platform's diffs and verdicts entirely outside DecimalAI. A runnable version is in [`examples/integrations/decimalai_bridge.py`](https://github.com/decimal-labs/agentversion/blob/main/examples/integrations/decimalai_bridge.py).
 
 ---
 
 ## Project
 
-The spec is frozen at v1.0; the package is pre-1.0 (see [Install](#install)). Design decisions are logged in [`adrs/`](https://pypi.org/project/agentversion/), releases in [`CHANGELOG.md`](https://pypi.org/project/agentversion/). Contributions — especially new conformance cases — are genuinely welcome; see [`CONTRIBUTING.md`](https://pypi.org/project/agentversion/):
+The spec is frozen at v1.0; the package is pre-1.0 (see [Install](#install)). Design decisions are logged in [`adrs/`](https://github.com/decimal-labs/agentversion/tree/main/adrs), releases in [`CHANGELOG.md`](https://github.com/decimal-labs/agentversion/blob/main/CHANGELOG.md). Contributions — especially new conformance cases — are genuinely welcome; see [`CONTRIBUTING.md`](https://github.com/decimal-labs/agentversion/blob/main/CONTRIBUTING.md):
 
 ```bash
 pip install agentversion
@@ -313,4 +324,8 @@ git clone https://github.com/decimal-labs/agentversion && cd agentversion
 pip install -e ".[dev]" && pytest
 ```
 
-Licensed under [Apache 2.0](https://pypi.org/project/agentversion/).
+Licensed under [Apache 2.0](https://github.com/decimal-labs/agentversion/blob/main/LICENSE).
+
+---
+
+[Docs](https://docs.decimal.ai) · [Registry](https://app.decimal.ai/skills) · [SDK](https://github.com/decimal-labs/decimalai-python) · [skillevaluation](https://github.com/decimal-labs/skillevaluation) · [regression-check](https://github.com/decimal-labs/regression-check)

{agentversion-0.2.1 → agentversion-0.2.3}/agentversion/compatibility.py

@@ -70,7 +70,13 @@ class CompatibilityPolicy(BaseModel):
     kind: Literal["compatibility_policy"] = "compatibility_policy"
     version: str = "0.1"
     name: str = "default"
-    preset: Literal["strict", "default", "permissive", "custom"] | None = "default"
+    preset: Literal["strict", "default", "permissive", "custom"] | None = Field(
+        "default",
+        description=(
+            "Provenance label only — recorded, not evaluated. "
+            "Per-surface rule blocks drive every decision."
+        ),
+    )
 
     prompt_stack: SurfaceRules | None = None
     model_runtime: SurfaceRules | None = None

{agentversion-0.2.1 → agentversion-0.2.3}/agentversion/contract.py

@@ -2,10 +2,10 @@
 
 The single source of truth for how a producer's *flat* components (one entry per
 tool / prompt / model / …) regroup into the contract-keyed surfaces the diff and
-the identity hash are computed from. Both the DecimalAI SDK exporter
-(``ManifestSnapshot.to_agentversion``) and the platform's diff translators call
-this, so a producer and a consumer can't drift on the mapping — and therefore
-compute the *same* ``jcs-sha256`` identity hash for the same agent.
+the identity hash are computed from. The DecimalAI platform calls this directly;
+the DecimalAI SDK exporter (``ManifestSnapshot.to_agentversion``) mirrors it and
+is held byte-identical to it by a cross-implementation test — so a producer and a
+consumer compute the *same* ``jcs-sha256`` identity hash for the same agent.
 
 Each component is a plain dict::
 

{agentversion-0.2.1 → agentversion-0.2.3}/agentversion/diff.py

@@ -741,9 +741,9 @@ _BEHAVIORAL_POLICY_RULE_FIELDS = (
 def _adapt_behavioral_policy(old: dict[str, Any], new: dict[str, Any]) -> tuple[
     Literal["breaking", "non_breaking"], Severity, list[str]
 ]:
-    """A change to the multi-turn behavioral policy RULES is BREAKING: it invalidates the conversation-
-    mode eval set and any past traces graded under the old policy. (A bare metadata change with an
-    unchanged ``policy_hash`` is not a rule change.)
+    """A change to the bound behavioral policy RULES is BREAKING: it invalidates any eval set and any
+    past traces graded under the old policy. (A bare metadata change with an unchanged ``policy_hash``
+    is not a rule change.)
 
     Add/remove are asymmetric and handled here so the surface is severitied by its own
     logic in both directions: *introducing* a policy where there was none is additive
@@ -814,11 +814,9 @@ SURFACE_KEYS = [
     "behavioral_policy",
 ]
 
-# CANONICAL routing from a producer's flat `component_type` to the contract SURFACE_KEY it lands in.
-# This is the single source of truth for that mapping, so a producer (the SDK) and a consumer (the
-# platform's diff path) can't drift — notably the singular→plural `guardrail`→`guardrails` rename,
-# which previously had to be applied by hand in every translator copy (XC-1). An unknown component
-# type maps to itself (so a new/custom surface is diffed generically rather than dropped).
+# Routing from a producer's flat `component_type` to the contract SURFACE_KEY it lands in,
+# including the singular→plural `guardrail`→`guardrails` case. A component type with no entry
+# here maps to itself (so a new/custom surface is diffed generically rather than dropped).
 COMPONENT_TYPE_TO_SURFACE: dict[str, str] = {
     "tool": "tool_registry",
     "skill": "skill_registry",
@@ -834,8 +832,8 @@ COMPONENT_TYPE_TO_SURFACE: dict[str, str] = {
 def surface_key_for_component(component_type: str) -> str:
     """The contract surface a flat ``component_type`` belongs to (identity for unknown types).
 
-    Use this everywhere a producer's component is routed to an agentversion surface, so the routing
-    (including ``guardrail``→``guardrails``) lives in exactly one place.
+    Looks ``component_type`` up in ``COMPONENT_TYPE_TO_SURFACE`` (for example
+    ``guardrail``→``guardrails``) and returns it unchanged when it has no entry.
     """
     return COMPONENT_TYPE_TO_SURFACE.get(component_type, component_type)