agentversion 0.1.0__tar.gz

agentversion-0.1.0/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 3
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 3

agentversion-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install with dev extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      # test_conformance.py exercises the JSON scenarios under
+      # compatibility-tests/ (tool-rename, output-schema-change,
+      # subagent-handoff-change) so no separate job needed.
+      - name: Run pytest
+        run: python -m pytest tests/ -q
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Ruff
+        # Config lives in pyproject.toml ([tool.ruff.lint]) so local and CI
+        # lint stay in lock-step. Lints the whole repo, tests included.
+        run: ruff check .
+
+      - name: Mypy
+        # Strict type-check the package (config in pyproject [tool.mypy]).
+        run: mypy agentversion/

agentversion-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,72 @@
+name: Publish to PyPI
+
+# Triggers when a release is published in GitHub. Tag conventions:
+#   v1.0.0 → publishes agentversion 1.0.0 to PyPI
+#
+# Uses Trusted Publisher (OIDC) — no API token needed.
+# Configure once at https://pypi.org/manage/account/publishing/ with:
+#   project: agentversion
+#   owner: decimal-labs
+#   repo: agentversion
+#   workflow: publish.yml
+#   environment: pypi
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  test:
+    name: Run Tests
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v
+
+  publish:
+    name: Publish to PyPI
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Verify package version matches release tag
+        run: |
+          PKG_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "Version mismatch: pyproject.toml=$PKG_VERSION, tag=$TAG_VERSION"
+            exit 1
+          fi
+          echo "Version match: $PKG_VERSION"
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agentversion-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db

agentversion-0.1.0/CHANGELOG.md

@@ -0,0 +1,242 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> **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.1.0] - 2026-05-29
+
+**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.
+
+### Changed — Project renamed to **AgentVersion**
+
+The project was renamed from "Agent Version Spec (AVS)" to **AgentVersion** before its first public release. The on-the-wire `spec_version` is unchanged (still `1.0.0`); only names and identifiers changed. Because nothing was published prior to this, there is no migration path — the rename is a pre-release change.
+
+- **PyPI distribution**: `agent-version-spec` → `agentversion`.
+- **Python import / package**: `agent_version_spec` → `agentversion`.
+- **CLI command**: `avs` → `agentversion`.
+- **Manifest-ref URI scheme**: `avs:manifest:<id>` / `avs:hash:<algo>:<hex>` → `agentversion:manifest:<id>` / `agentversion:hash:<algo>:<hex>`. Manifests that carry subagent `manifest_ref`s must update those values and recompute `identity.overall_hash` (refs are inside the hashed `subagents` surface). The example `examples/manifest/finance-agent-v2.json` was updated accordingly.
+- **OpenTelemetry attribute key**: `agent_version_spec.manifest_hash` → `agentversion.manifest_hash`.
+- **GitHub repository**: `decimal-labs/agent-version-spec` → `decimal-labs/agentversion`.
+
+Unchanged: object ID prefixes (`amf`, `tsk`, `ep`, `dss`, `cdc`, `rpj`, `rpr`, `mdf`), the `spec_version` value (`1.0.0`), the `jcs-sha256` hash algorithm, and the schema file names (which are object-named, not project-named).
+
+---
+
+## Pre-release development (internal milestones — never published)
+
+The entries below were development milestones tracked in-repo on the way to feature-completeness. None were published to PyPI or any other index, so there is no migration path between them — they're kept as a record of how the spec took shape. Their version numbers are the old internal numbering and overlap the published `0.1.0` above only by coincidence.
+
+### 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`.
+
+### What v1.0 looks like
+
+- **Canonical IDs only.** Every ID matches `^[a-z][a-z0-9]*_[0-9A-HJKMNP-TV-Z]{26}$` (kind-prefixed ULID). The JSON Schema, Pydantic models, and semantic validator all enforce this. `malformed_id` and `wrong_id_prefix` are errors; there is no permissive mode.
+- **Typed manifest references only.** `subagents[].manifest_ref` accepts `avs:manifest:<canonical-id>`, `avs:hash:<algo>:<hex>`, `https://...`, or `file:///...`. Bare IDs are rejected. `malformed_manifest_ref` is an error.
+- **`Development Status` classifier**: `5 - Production/Stable`.
+- **Conformance suite frozen.** `compatibility-tests/` scenarios in v1.0.0 stay stable through v1.x. New scenarios may be added in minors; existing ones don't change.
+- **Semver locked.** `1.x.0` minors are always backward-compatible (additive only). Anything that removes/renames/tightens requires a major bump.
+
+### Migration
+
+There is no migration path from pre-v1.0 — nothing pre-v1.0 was released. Build new manifests at canonical form.
+
+### What's next
+
+- v1.x minors: federated registry resolution, well-known `extensions` namespace registry, streaming manifest support.
+- v2.0 (no timeline): drop legacy `status` field in favor of `lifecycle.current_stage` only.
+
+### 0.9.0 - 2026-05-12
+
+Trust + observability + governance batch. The last three §3 items.
+
+### Added — Attestation (§3d)
+- **`Attestation` model** with `signer`, `algorithm`, `signature`, `signed_payload_hash`, `signed_at`, optional `key_id` + `expires_at`.
+- **`IdentityBlock.attestations: List[Attestation]`** — multiple attestations supported (typical: CI provenance + release-manager approval + security-scan).
+- **Hash isolation**: attestations live on `identity` (not `contract`), so adding or rotating signatures does NOT change `overall_hash`. A manifest's identity is its contract; signatures are evidence about it.
+- **Verification is out of spec**: format-only. Implementations bring their own crypto (Sigstore, cosign, GPG, internal PKI). The validator only enforces well-formedness; it does not check signatures.
+- Spec doc [`spec/attestation.md`](./spec/attestation.md).
+
+### Added — Richer `ComparisonSummary` (§3m)
+- **New fields on `ReplayResult.comparison_summary`**: `final_output_diff_pct` (0-100), `tool_path_diff: ToolPathDiff` (`steps_added`, `steps_removed`, `first_divergence_step_index`), `step_count_delta`, `latency_delta_ms`, `cost_delta_usd`, `eval_score_delta`. All optional — back-compat preserved.
+- **`ToolPathDiff` model** for structural diff of the tool-call sequence.
+- **Use case**: sort divergent replays by severity. Pre-v0.9, you knew which replays diverged; now you know *how much* and *where* they first diverged.
+
+### Added — Data Classification (§3n)
+- **`DataClassification` model** for compliance labels: `pii_state` (`raw|redacted|synthetic|none`), `retention_days`, `residency[]`, `redaction_policy_ref`, `consent_basis` (GDPR Article 6 enum).
+- **`DatasetSnapshot.data_classification`** — optional; defaults to `pii_state="none"` when present without overrides.
+- **`SelectionPolicy.pii_states`** — filter so a snapshot can declare "only include episodes whose data is redacted or synthetic".
+- Spec doc [`spec/data-classification.md`](./spec/data-classification.md).
+
+### Tests
+- 17 new tests in `tests/test_trust_observability.py`.
+- 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.
+
+### 0.8.0 - 2026-05-12
+
+Reproducible-replay batch. Four audit items in one bump because they collectively make most agents bit-reproducibly replayable — adding one without the others leaves replay still flaky.
+
+### Added — Tool semantic_version (§3i)
+- **`ToolDescriptor.semantic_version`** — SemVer string catching *behavioral* drift that schema hashes miss (e.g. "we swapped the upstream Census API from 2019 to 2024; same schema, different numbers").
+- **`ToolDescriptor.implementation_ref`** — opaque pointer to the implementation (git commit, image hash, etc.).
+- **Diff classifier extension**: when schemas are unchanged but a tool's `semantic_version` bumps, the diff now flags the bump kind — major → breaking moderate, minor → non-breaking minor, patch → non-breaking minor.
+- **Validator code**: `malformed_semver` (WARNING).
+
+### Added — Tool schema embedding (§3g)
+- **`ToolDescriptor.input_schema_inline`** and **`output_schema_inline`** — optional inline JSON Schemas alongside the existing hashes.
+- **Validator code**: `schema_hash_mismatch` (ERROR) when `JCS-SHA256(inline) != declared hash`.
+- Enables fully-offline replay: archived agents don't need a live registry to verify tool I/O.
+
+### Added — Model cost & limits envelope (§3h)
+- **`ModelRuntime.envelope`** — new sub-object with `context_window_tokens`, `expected_latency_ms_p50` / `p99`, `cost.{input,output,cached_input}_per_1k_tokens_usd`, `rate_limit.{rpm,tpm}`.
+- Anchors `ReplayConstraints.max_cost_usd` budgeting and lets the diff classifier flag price-tier swaps.
+- Envelope is part of `contract.model_runtime` → participates in `overall_hash`. Provider price changes warrant a new manifest version.
+
+### Added — Replay determinism hints (§3f)
+- **`ReplayInput.determinism`** — new optional sub-object with `random_seed`, `clock_freeze_at`, `tool_response_pinning_ref` (the last a `ManifestRef`-style URI; `avs:hash:` is the typical scheme since you want tamper detection).
+- Spec doc [`spec/replay-determinism.md`](./spec/replay-determinism.md) covers all four §3f/§3g items together and explains why they ship as a set.
+
+### Examples
+- `finance-agent-v2.json` gains a populated `envelope` on `model_runtime` and a `semantic_version` + `implementation_ref` on `get_market_cap`. `overall_hash` updated because both fields are in-contract.
+
+### Tests
+- 14 new tests in `tests/test_reproducible_replay.py`.
+- avs total: **278 passing** (was 264, net +14).
+
+### 0.7.0 - 2026-05-12
+
+### Added — Lifecycle (§3e)
+- **`Lifecycle` model** as an optional top-level field on `AgentManifest` (siblings: `lifecycle`, `evaluation` — both outside `contract`, so they do NOT participate in `identity.overall_hash`).
+- Six stages: `draft → candidate → staging → production → deprecated → archived`.
+- `LifecycleTransition` records each promotion: `stage`, `transitioned_at`, `by` (actor convention: `user:<id>`, `system:<id>`), optional `eval_ref`, `approved_by[]`, `notes`.
+- `supersedes[]` and `superseded_by` for the version-chain bookkeeping. `sunset_at` for scheduled removal.
+- Validator: `lifecycle_history_unsorted` (ERROR), `lifecycle_stage_mismatch` (ERROR), `lifecycle_status_mismatch` (WARNING — when the simple `status` field and `lifecycle.current_stage` disagree under the simple-to-rich mapping).
+- Spec doc [`spec/lifecycle.md`](./spec/lifecycle.md).
+- 13 new tests in `tests/test_lifecycle.py`.
+
+### Added — Evaluation Gates (§3k)
+- **`Evaluation` model** as an optional top-level field carrying `gates[]`. Like lifecycle, NOT in contract — re-running an eval against the same agent produces the same `overall_hash` but updated evaluation data.
+- `EvalGate` records: `name`, optional `dataset_ref`, `threshold`, `actual_score`, `threshold_direction` (`"min"` higher-is-better / `"max"` lower-is-better), `passed`, `ran_at`, optional `evaluator_ref`, `notes`.
+- Validator: `eval_gate_inconsistent` (WARNING) when `passed` disagrees with `actual_score` vs `threshold` under the declared direction.
+- Spec doc [`spec/evaluation.md`](./spec/evaluation.md).
+- 9 new tests in `tests/test_evaluation.py`.
+
+### Added — Manifest Tombstone (§3j, folded in)
+- `IdentityBlock.yanked_at` and `IdentityBlock.yanked_reason` — optional fields for marking a published manifest as no-longer-recommended without rewriting history (PyPI-yank semantics).
+- Identity block is NOT part of contract, so yanking a manifest does NOT change its `overall_hash`.
+
+### Examples
+- `examples/manifest/finance-agent-v2.json` gains populated `lifecycle` and `evaluation` blocks demonstrating a 4-transition path to production with three eval gates (regression, safety, latency).
+- `overall_hash` of the example is **unchanged** — confirming lifecycle + evaluation correctly sit outside `contract`.
+
+### 0.6.0 - 2026-05-12
+
+### Added — Environment Fingerprint Surface (§3a)
+- **New contract surface** `environment` on `AgentContract` with fields: `deployment_id`, `region`, `infra_image_hash`, `runtime_versions`, `secret_refs`, `external_service_pins`, `feature_flags`, `resource_limits`. All optional — older v0.5 manifests still validate.
+- **`ResourceLimits` model** with `memory_mb`, `cpu_cores`, `timeout_seconds`, `max_concurrent_calls`.
+- **JSON Schema** for the new block under `contract.environment`.
+- **Diff classifier** `environment_severity()` with field-level severity rules:
+  - `deployment_id`, `secret_refs`, `feature_flags`, `resource_limits` → minor
+  - `region`, `infra_image_hash`, `runtime_versions`, `external_service_pins` → moderate
+  - Environment changes are always classified `non_breaking` (they affect replayability, not validity of past traces).
+- **New reason codes** in `compatibility_decision.reason_codes` enum: `region_changed`, `infra_image_changed`, `external_service_pin_changed`, `runtime_version_changed`. Plus the existing `environment_unreplayable` as a catch-all.
+- **Condition tokens** `environment_surface_unchanged` / `environment_surface_changed` for `ClassificationRule.condition`.
+- **`CompatibilityPolicy.environment`** for user-configurable rules on the new surface.
+- **Spec doc** [`spec/environment.md`](./spec/environment.md) — full surface spec, field reference, severity rules, security notes, hash participation.
+- **Example** `examples/manifest/finance-agent-v2.json` gains a populated `environment` block.
+- 19 new tests in `tests/test_environment.py`.
+
+### Security note
+`environment.secret_refs` holds **names** (identifiers), not values. Implementations that put plaintext secrets there leak credentials into the manifest hash.
+
+### 0.5.0 - 2026-05-12
+
+### Added — Manifest References (§3c)
+- **`agent_version_spec.refs` module** with `ManifestRef`, `parse_manifest_ref(s)`, `try_parse_manifest_ref(s)`, `is_bare_id_ref(s)`.
+- **URI scheme** for `SubagentDescriptor.manifest_ref`:
+  - `avs:manifest:<id>` — by-ID reference (registry resolution).
+  - `avs:hash:<algo>:<hex>` — content-addressed (immutable).
+  - `https://...` / `http://...` — fetchable URL.
+  - `file:///path/manifest.json` — local file.
+  - Bare `<id>` — implicit `avs:manifest:` (deprecated in v0.x; removed in v1.0).
+- **JSON Schema** pattern on `subagents[].manifest_ref` accepts all five forms.
+- **Validator** semantic rules: `malformed_manifest_ref` (ERROR), `bare_manifest_ref` (WARNING; ERROR under `--strict-ids`). Embedded IDs in `avs:manifest:` URIs run through the same ID checks as `manifest_id`.
+- **Spec doc** [`spec/refs.md`](./spec/refs.md) — full URI scheme, resolution semantics, JSON Schema pattern, v0.x → v1.0 promise.
+- Example `examples/manifest/finance-agent-v2.json` updated: bare-ID subagent refs (`amf_finance_subagent_v3`) → canonical URIs (`avs:manifest:amf_01KREPJH26…`); fixed `manifest_id` from a not-actually-Crockford-base32 placeholder to a real ULID; recomputed `identity.overall_hash`.
+- 25 new tests in `tests/test_refs.py`.
+
+### Added — Generalized ID Enforcement (§3b follow-up)
+- **`check_object_ids(data, kind, strict)`** in `ids.py` validates every known ID field across **all** spec kinds (manifest, task, episode, step, dataset_snapshot, compatibility_decision, compatibility_batch, compatibility_report, replay_job, replay_result, manifest_diff).
+- Walks dotted paths with `[]` array notation; handles `subject.id` specially (its expected prefix depends on `subject.type`).
+- **CLI subcommands** `avs decision validate`, `avs replay validate`, `avs dataset validate` all gained `--strict-ids` and emit the same warning/error vocabulary as `avs validate`.
+- 9 new tests covering non-manifest objects.
+
+### Changed
+- `validate_manifest()` now delegates its ID checks to `check_object_ids()` — single source of truth for ID rules.
+
+### 0.4.0 - 2026-05-12
+
+### Added — Canonical IDs (§3b)
+- **`agent_version_spec.ids` module** with `mint_id(kind)`, `parse_id(s)`, `validate_id(s, expected_kind=None, strict=False)`, `is_canonical_id(s)`, `is_permissive_id(s)`, and the `ID_PREFIXES` map (12 known kinds).
+- **Canonical ID form**: `<kind-prefix>_<26-char Crockford base32 ULID>` (e.g. `amf_01HZK1A2B3C4D5E6F7G8H9J0K1`). Sortable by mint time; one less character than UUID; type-prefixed for at-a-glance kind identification.
+- **Permissive form** (v0.x back-compat): JSON Schema `pattern` accepts both canonical ULID and semantic-slug IDs (e.g. `amf_finance_v3`). The validator emits a `non_canonical_id` WARNING for slug IDs through the v0.x line.
+- **Semantic validator rules** (`validator.py`):
+  - `malformed_id` — ERROR when an ID matches neither canonical nor permissive form.
+  - `wrong_id_prefix` — ERROR (or escalated WARNING) when an ID's prefix doesn't match the object's kind.
+  - `non_canonical_id` — WARNING (or ERROR under `--strict-ids`) for slug IDs.
+- **CLI**: `avs validate --strict-ids` escalates `non_canonical_id` warnings to errors. Matches the v1.0 behavior.
+- **Spec doc**: [`spec/ids.md`](./spec/ids.md) documents the format, prefix table, rationale, API, and the v0.x → v1.0 tightening.
+- 23 new tests in `tests/test_ids.py`.
+
+### Changed
+- `validate_manifest()` and `validate_manifest_file()` accept a `strict_ids: bool = False` keyword.
+
+### Not yet enforced
+- v1.0 will drop the permissive pattern. `non_canonical_id` becomes an error by default. Plan accordingly: tools that mint new IDs should produce canonical ULID form starting now.
+
+### 0.3.0 - 2026-05-12
+
+### Changed (breaking — nothing shipped publicly yet)
+- **Renamed `rescue_decision` → `compatibility_decision`** (`RescueDecision` → `CompatibilityDecision`, schema file, kind, spec doc, CLI group). Aligns with the rest of the compatibility family.
+- **Renamed `rescue_batch` → `compatibility_batch`** (`RescueBatch` → `CompatibilityBatch`, summary class, schema file, kind, spec doc).
+- **Renamed `validators` surface → `guardrails`** (`ValidatorBundle` → `GuardrailBundle`). Removes naming collision with Pydantic and JSON-Schema validators.
+- **Renamed schema file** `agent-version-spec.schema.json` → `agent-manifest.schema.json` to match the kind it defines.
+- **Renamed module** `agent_version_spec/rescue.py` → `agent_version_spec/decision.py`.
+- **CLI:** `avs rescue ...` → `avs decision ...` for both `validate` and `generate`.
+- **Dropped** `validators.requires_confirmation_for_destructive_actions` — promote to per-tool `annotations.requires_confirmation` instead.
+- **Renamed** `GuardrailBundle` fields: `validator_bundle_version` → `bundle_version`, `validator_bundle_hash` → `bundle_hash`.
+- **Reason code** `validator_policy_changed` → `guardrail_policy_changed`; added `skill_missing`, `skill_content_changed`.
+- **Condition tokens** `validator_surface_*` → `guardrail_surface_*`; added `skill_surface_unchanged` / `skill_surface_changed`.
+- **Tool annotations** standardized to snake_case: `requiresConfirmation` → `requires_confirmation`, `readOnlyHint` → `read_only_hint`.
+
+### Added
+- **`skill_registry` contract surface** is now first-class: `SkillRegistry` + `SkillDescriptor` are in the JSON schema (`agent-manifest.schema.json`), reference spec, diff surface enum, compatibility-policy schema, and condition DSL. Previously code-only.
+- **`compatibility-report.schema.json`** — JSON Schema for the `CompatibilityReport` output of `classify_compatibility()`. Closes the gap where the class existed but had no schema.
+- `__version__` is now read from package metadata via `importlib.metadata`, eliminating the package-version / `__version__` drift bug.
+
+### 0.2.0 - 2026-03-18
+
+### Added
+- `skill_registry` Pydantic model + diff classifier (informally; not yet in schemas — see 0.3.0).
+- Quantized float hashing for `generation_config` (temperature step 0.1, top_p step 0.05) so micro-tweaks don't churn manifest hashes.
+- New manifest fields: `status`, `capabilities`, `description`, tool-level `description` + `annotations`.
+- `OutputContract.modalities`.
+- `compatibility-policy.schema.json` — user-configurable rules mapping change severity to actions per surface.
+- Formalized condition DSL for `ClassificationRule.condition` with `SURFACE_STATE_TOKENS` / `PARAMETERIZED_TOKENS` and a `validate_condition()` enforcer.
+
+### 0.1.0 - 2026-03-11
+
+### Added
+- Initial public scaffolding of the Agent Version Spec.
+- Spec documents, JSON Schemas, Pydantic models, JCS-SHA256 hasher, surface-level diff engine, compatibility classifier.
+- CLI entry point (`avs`) with `validate`, `diff`, `hash`, `init`, `upgrade` and subcommand groups.

agentversion-0.1.0/CONFORMANCE.md

@@ -0,0 +1,66 @@
+# Conformance
+
+How an implementation proves it conforms to the AgentVersion.
+
+## Why this exists
+
+The spec is a multi-language target. The Python reference implementation lives in this repo, but an implementation in TypeScript, Rust, Go, or any other language is conforming as long as it produces the same outputs for the same inputs. This document defines "same outputs."
+
+## What an implementation must do
+
+A conforming implementation must support, at minimum:
+
+1. **Manifest validation** — accept a manifest JSON, validate it against `schemas/agent-manifest.schema.json`, and enforce the semantic rules in `spec/manifest.md` § "Required fields" and § "Semantic Validation Rules" (`reference.md` §13).
+2. **Canonical hashing** — given a manifest, produce the same `identity.overall_hash` as the Python reference for any input. The algorithm is JCS-SHA256 (RFC 8785) applied to the `contract` block as documented in [`spec/hashing.md`](spec/hashing.md). Quantization of `generation_config` floats is part of the spec.
+3. **Diff** — given two manifests, produce a `manifest_diff` that matches the expected output of the conformance suite (described below).
+4. **Compatibility classification** — given a `manifest_diff`, produce a `compatibility_report` whose `recommended_decision` matches the reference implementation's output for the same input.
+
+Implementations may add additional capabilities (e.g. signing, registry resolution), but those are extensions and do not affect conformance.
+
+## The conformance suite
+
+Located under [`compatibility-tests/`](./compatibility-tests/). Each subdirectory is a scenario:
+
+```
+compatibility-tests/
+  tool-rename/
+    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
+```
+
+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`.
+2. Run your implementation's diff function.
+3. Compare your output against `expected-diff.json`.
+4. The comparison must be tolerant to list ordering inside `changed_surfaces` (so use a set keyed on `(surface, change_type, severity)`), but the counts in `summary` and the set of surfaces and their `change_type`/`severity` must match exactly.
+
+## Adding scenarios
+
+When the spec gains new behavior, add a new scenario directory with a `before.json`, `after.json`, and `expected-diff.json` produced by the reference implementation. Open a PR that includes both the new scenario and any code changes required to pass it.
+
+When existing semantics change, update the expected diffs in the same PR that changes the implementation. Both the implementation change and the fixture change must be reviewed together.
+
+## What "matches" means
+
+The reference comparison (see `tests/test_conformance.py`):
+
+- `kind == "manifest_diff"`
+- `old_manifest_id` and `new_manifest_id` match
+- The set of `(surface, change_type, severity)` tuples in `changed_surfaces` is identical
+- `summary.breaking_surfaces` and `summary.non_breaking_surfaces` counts match exactly
+
+Things explicitly **not** part of conformance (intentionally tolerant):
+
+- Order of items within `changed_surfaces` or `details` arrays
+- Exact wording of human-readable strings in `details` (these are advisory, not contractual)
+- `max_severity` field — derived; an implementation may omit or include it freely

agentversion-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing to AgentVersion
+
+Thanks for your interest. AgentVersion is intended to be a stable, infrastructure-grade specification, so changes follow a slower and more deliberate process than typical libraries.
+
+## How to propose a change
+
+1. **Open an issue first** describing the problem. Don't open a PR before there's agreement that the change is desirable — spec evolution requires consensus.
+2. **For non-trivial changes, write an ADR** under `adrs/NNNN-<slug>.md` using `adrs/0000-template.md`. ADRs capture the *why*. The spec docs in `spec/` capture the *what*.
+3. **Reference the ADR from the PR.** ADRs may be amended or superseded but never deleted; they are the design log.
+
+## Spec evolution rules
+
+The `spec_version` follows [Semantic Versioning 2.0.0](https://semver.org/). Pre-1.0 (where we are now) is unstable; after 1.0 the rules below apply.
+
+**Allowed in a minor bump (1.x.0):**
+
+- Adding new optional fields to any object
+- Adding new values to enums (`step_type`, `reason_code`, `decision` verbs, etc.)
+- Adding new `kind` values (introducing new spec objects)
+- Adding new `$defs` to JSON Schemas
+
+**Requires a major bump (x.0.0):**
+
+- Removing or renaming any field
+- Making an optional field required
+- Changing field types or value semantics
+- Changing the canonical hashing algorithm
+- Removing enum values
+- Changing the `overall_hash` derivation
+
+When you propose a breaking change, your PR must include:
+
+- The ADR explaining the motivation
+- An entry in `CHANGELOG.md` under the next major version
+- A migration note in `spec/versioning-policy.md`
+- Updates to the conformance fixtures (`compatibility-tests/`) so existing implementations can verify their migrations
+
+## Code conventions
+
+- Python ≥ 3.10, strict typing (`mypy --strict`).
+- Pydantic v2 models are the source of truth for serialization; JSON Schemas mirror them.
+- Tests live under `tests/`. Conformance fixtures live under `compatibility-tests/`.
+- One canonical example per concept under `examples/`. Recompute hashes (`agentversion hash <file>`) whenever you change a manifest's `contract` block.
+
+## What to test
+
+Every PR should run:
+
+```bash
+pip install -e ".[dev]"
+pytest                     # full suite, including conformance scenarios
+ruff check .
+mypy agentversion
+```
+
+The conformance scenarios (`tests/test_conformance.py`) are non-negotiable. If your change breaks them, either the scenario is stale (update it) or your change breaks compatibility (then it's a major bump, not a minor).
+
+## Releases
+
+The maintainer cuts releases. The flow is:
+
+1. PR with the version bump in `pyproject.toml` + a `CHANGELOG.md` entry.
+2. Tag `vX.Y.Z` on `main`.
+3. CI publishes to PyPI via trusted publishing.
+
+## License
+
+By contributing, you agree your contribution is licensed under [Apache 2.0](./LICENSE), the same as the project.