agentversion 0.2.1__tar.gz → 0.2.2__tar.gz

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

@@ -7,6 +7,20 @@ 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.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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentversion
-Version: 0.2.1
+Version: 0.2.2
 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

{agentversion-0.2.1 → agentversion-0.2.2}/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

{agentversion-0.2.1 → agentversion-0.2.2}/agentversion/manifest.py

@@ -263,25 +263,30 @@ class Environment(BaseModel):
 
 
 class BehavioralPolicy(BaseModel):
-    """Multi-turn BEHAVIORAL-POLICY contract surface.
+    """Versioned BEHAVIORAL-POLICY contract surface.
 
-    The rules a multi-turn agent must hold across turns — e.g. a refund/escalation policy: "deny until
-    the customer objects N times, then escalate; never admit liability". Bound to skillevaluation's
-    conversation-mode ``policy_check`` (the deterministic state machine that grades these rules).
+    Binds the agent to a named policy artifact — the rules it must hold to, e.g. a refund/escalation
+    policy ("deny until the customer objects N times, then escalate; never admit liability"), a safety
+    guardrail set, or an escalation SOP. The surface is document-agnostic: ``policy_hash`` is the stable
+    identity (a hash of whatever policy artifact you bind), and the value carried is opaque to this
+    model.
 
     Why it is a first-class surface: a behavioral policy lives *inside* the prompt, so a prompt-stack
-    hash change is classified ``non_breaking`` — yet flipping the policy (``objection_threshold`` 3 → 1,
-    or removing an ``always_forbidden`` rule) INVALIDATES the conversation-mode eval set and any past
-    traces graded under the old policy. Hoisting the policy to its own surface makes that flip visible
-    and ``breaking`` instead of silently ``keep``. ``policy_hash`` is the stable identity (a hash of the
-    bound ``policy_check`` spec); the rule fields are carried for human-readable diffs. ``extra='allow'``
-    so a richer policy spec round-trips without forking this model.
+    hash change is classified ``non_breaking`` — yet flipping the policy (a threshold 3 → 1, or removing
+    a forbidden rule) INVALIDATES any eval set and any past traces graded under the old policy. Hoisting
+    the policy to its own surface makes that flip visible and ``breaking`` instead of silently ``keep``.
+
+    ``policy_hash`` is the identity; the structured rule fields below are OPTIONAL and carried only for
+    human-readable diffs (a policy artifact needn't populate any of them — ``extra='allow'`` lets a
+    richer or differently-shaped policy spec round-trip without forking this model). They remain on the
+    model for backward compatibility with policies already bound this way.
     """
 
     model_config = ConfigDict(extra="allow")
 
     policy_id: str | None = None
-    policy_hash: str | None = None  # stable hash of the bound policy_check spec (the identity)
+    policy_hash: str | None = None  # stable hash of the bound policy artifact (the identity)
+    # Optional structured rule fields — illustrative, kept for back-compat + human-readable diffs.
     objection_threshold: int | None = None
     concede_events: list[str] | None = None
     always_forbidden: list[str] | None = None

{agentversion-0.2.1 → agentversion-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentversion"
-version = "0.2.1"
+version = "0.2.2"
 description = "An open specification for versioning agent runtimes and keeping datasets valid."
 readme = "README.md"
 license = "Apache-2.0"

agentversion-0.2.2/spec/behavioral-policy.md

@@ -0,0 +1,56 @@
+# `behavioral_policy` surface
+
+A contract surface that binds an agent to a **versioned policy document** — the rules it must hold to.
+The surface is document-agnostic: the policy can be a refund/escalation policy (*"deny refunds and offer
+alternatives; only after the customer has objected ≥3 times, escalate to a human; never concede a refund
+yourself, and never admit liability"*), a safety guardrail set, an escalation SOP, or any other bound
+rule artifact.
+
+## Why it is a first-class surface
+
+A behavioral policy usually lives *inside the system prompt*. Before this surface existed, flipping the
+policy (tightening a threshold, or dropping a forbidden rule) showed up only as a `prompt_stack`
+**hash change**, which the diff classifies **`non_breaking`** → recommended decision **`keep`**. But a
+policy flip **invalidates** any eval set and any past traces that were graded under the old policy.
+Hoisting the policy to its own surface makes that flip **`breaking`** → `replay`/`drop`, instead of
+silently retaining now-wrong data.
+
+The `policy_hash` is the canonical identity — a hash of *whatever policy artifact you bind*. The
+structured rule fields below are optional and carried only for human-readable diffs; the surface does not
+interpret them.
+
+## Shape
+
+```json
+"behavioral_policy": {
+  "policy_id": "refund-escalation",
+  "policy_hash": "sha256:…",          // hash of the bound policy artifact (the identity)
+  "objection_threshold": 3,           // optional structured rule fields — illustrative,
+  "concede_events": ["offered_refund", "escalated"],   // carried for readable diffs only
+  "always_forbidden": ["admits_liability"]
+}
+```
+
+`policy_id` and `policy_hash` are the only load-bearing keys. The structured rule fields
+(`objection_threshold`, `concede_events`, `always_forbidden`) are **optional**, illustrative, and kept
+for backward compatibility with policies already bound this way — a policy artifact needn't populate any
+of them. The model is `extra="allow"`, so a richer or differently-shaped policy spec round-trips without
+forking it.
+
+## Diff semantics
+
+| Transition | Classification | Rationale |
+|---|---|---|
+| rule change (`policy_hash` differs, or any rule field differs) | **breaking** (`major`) | any eval set + past graded traces are now wrong |
+| `policy_hash` unchanged, only metadata (`policy_id`) differs | `non_breaking` (`minor`) | same policy, no rule changed |
+| introduced (absent → present) | `non_breaking` | the old eval set tested no policy; additive |
+| removed (present → absent) | **breaking** (`major`) | past data graded under the policy is now ungoverned |
+
+Reason code: `behavioral_policy_changed`. Configurable per-surface via `CompatibilityPolicy.behavioral_policy`
+(defaults: `on_major` → `drop`).
+
+## Hash-safety
+
+`behavioral_policy` is **optional and omitted by default**. The `overall_hash` is computed only over the
+surfaces actually present in a contract, so adding this surface to the spec does **not** change the hash
+of any existing (policy-less) manifest. The frozen hash-vectors are unchanged.

agentversion-0.2.1/spec/behavioral-policy.md

@@ -1,51 +0,0 @@
-# `behavioral_policy` surface
-
-A contract surface for a multi-turn agent's **behavioral policy** — the rules it must hold *across
-turns*, e.g. a refund/escalation policy: *"deny refunds and offer alternatives; only after the customer
-has objected ≥3 times, escalate to a human; never concede a refund yourself, and never admit liability."*
-
-## Why it is a first-class surface
-
-A behavioral policy lives *inside the system prompt*. Before this surface existed, flipping the policy
-(`objection_threshold` 3 → 1, or dropping an `always_forbidden` rule) showed up only as a `prompt_stack`
-**hash change**, which the diff classifies **`non_breaking`** → recommended decision **`keep`**. But a
-policy flip **invalidates** the conversation-mode eval set and any past traces that were graded under the
-old policy. Hoisting the policy to its own surface makes that flip **`breaking`** → `replay`/`drop`,
-instead of silently retaining now-wrong data.
-
-This binds directly to [skillevaluation](https://github.com/decimal-labs/skillevaluation)'s
-conversation-mode `policy_check` — the deterministic state machine that grades these same rules. The
-`policy_hash` is the canonical identity (a hash of the bound `policy_check` spec); the rule fields are
-carried for human-readable diffs.
-
-## Shape
-
-```json
-"behavioral_policy": {
-  "policy_id": "refund-escalation",
-  "policy_hash": "sha256:…",          // hash of the bound policy_check spec (the identity)
-  "objection_threshold": 3,
-  "concede_events": ["offered_refund", "escalated"],
-  "always_forbidden": ["admits_liability"]
-}
-```
-
-The model is `extra="allow"`, so a richer policy spec round-trips without forking it.
-
-## Diff semantics
-
-| Transition | Classification | Rationale |
-|---|---|---|
-| rule change (`policy_hash` differs, or any rule field differs) | **breaking** (`major`) | conversation eval set + past graded traces are now wrong |
-| `policy_hash` unchanged, only metadata (`policy_id`) differs | `non_breaking` (`minor`) | same policy, no rule changed |
-| introduced (absent → present) | `non_breaking` | the old eval set tested no policy; additive |
-| removed (present → absent) | **breaking** (`major`) | past data graded under the policy is now ungoverned |
-
-Reason code: `behavioral_policy_changed`. Configurable per-surface via `CompatibilityPolicy.behavioral_policy`
-(defaults: `on_major` → `drop`).
-
-## Hash-safety
-
-`behavioral_policy` is **optional and omitted by default**. The `overall_hash` is computed only over the
-surfaces actually present in a contract, so adding this surface to the spec does **not** change the hash
-of any existing (policy-less) manifest. The frozen hash-vectors are unchanged.