How must an instance bind prompt versions to observed behavioral baselines?

**Date of Record:** 2026 October 27 **Scope:** Applies when an agentic session maintains prompts as versioned artifacts and uses them across many sessions, and the prompts' behavioral impact (error rates, refusal rates, output characteristics) must be tracked alongside the prompt text itself. Does not apply to strictly one-shot prompts or sessions where prompts are never versioned or reused.

Core Distinction

The separation between **prompt version identity** (the text of the prompt, its version number) and **prompt-behavior binding** (the observed behavioral profile associated with that prompt version). Relying on text alone creates the **Prompt Version Ambiguity**: two prompts with the same text but different observed behaviors (due to model updates, temperature changes, or context shifts) are treated as equivalent, and the session inherits behavior expectations that no longer hold.

What Was Observed

In prompt-managed agent architectures, failing to bind prompts to behavioral baselines produces three primary failure modes:

  1. **Silent Behavior Drift:** A prompt's text is unchanged, but its behavior drifted due to model updates. Sessions that reuse the prompt expect the old behavior and are surprised by new behavior.
  2. **Regression Blindness:** A prompt revision improves one metric (e.g., accuracy) but degrades another (e.g., refusal safety). Without behavioral baselines per version, the regression goes undetected.
  3. **Cross-Version Confusion:** Two prompts with similar text (v1.1 and v1.2) have different behaviors. Sessions cannot determine which version is more appropriate without behavioral data.

Recorded Elements

  1. **`prompt_version_signature`:** A cryptographic signature of the exact prompt text and its version identifier.
  2. **`behavioral_baseline_receipt`:** For each prompt version, the observed behavioral profile (error rate, refusal rate, output length distribution, latency), timestamped to reflect the measurement window.
  3. **`behavioral_change_event_receipt`:** When the prompt's behavior changes significantly without a text change, a cryptographic record of the change event, allowing sessions to detect silent drift.
  4. **`prompt_selection_rationale_signature`:** The explicit rationale for choosing a specific prompt version (e.g., "v1.2 because lower refusal rate"), allowing audits to verify the choice was informed by the behavioral baseline.

Condition of Validity

* **Applies when:** Prompts are versioned, their behavior can drift, and downstream decisions depend on consistent behavior. * **Does not apply when:** Prompts are strictly ephemeral (never reused), or the prompt's behavioral characteristics do not matter to downstream decisions.

Decision Boundary

  1. **Is the prompt versioned?** If no, standard prompt usage applies. If yes, proceed.
  2. **Does the version have a `behavioral_baseline_receipt`?** If no, the session cannot predict behavior. It must measure the baseline or use a verified prompt.
  3. **Has the prompt's behavior drifted without a text change (`behavioral_change_event_receipt`)?** If yes, the version's baseline must be updated before re-use.
  4. **Conversely, when can the session use a prompt without behavioral baseline?** Only when the prompt is being used for the first time (no baseline exists yet) or when the downstream task is insensitive to behavioral variation.

Operational Effect

  1. **Drift Detection:** Behavioral baselines reveal silent changes to prompt behavior.
  2. **Regression Prevention:** Version comparison uses behavioral data, not just text diffs.
  3. **Informed Selection:** Prompt choice is based on observed behavior, not just version numbers.
from dataclasses import dataclass
from enum import Enum, auto
import hashlib
import json

class PromptVerdict(Enum):
    NO_VERSIONING = auto()
    BASELINE_VERIFIED = auto()
    SILENT_DRIFT_DETECTED = auto()
    NO_BASELINE = auto()

@dataclass(frozen=True)
class PromptVersion:
    version_id: str
    text_hash: str
    behavioral_baseline_hash: str | None
    drift_detected_since_baseline: bool

@dataclass(frozen=True)
class PromptPolicy:
    require_baseline: bool
    require_drift_check: bool

@dataclass(frozen=True)
class PromptManifest:
    verdict: PromptVerdict
    directive: str
    manifest_digest: str

class PromptVersionGuard:
    @staticmethod
    def _hash(data: str) -> str:
        return hashlib.sha256(data.encode("utf-8")).hexdigest()

    @classmethod
    def evaluate_version(
        cls, version: PromptVersion, policy: PromptPolicy
    ) -> PromptManifest:
        
        # Gate 1: Baseline requirement
        if policy.require_baseline and not version.behavioral_baseline_hash:
            return PromptManifest(
                verdict=PromptVerdict.NO_BASELINE,
                directive=f"HALT: Prompt {version.version_id} lacks behavioral baseline.",
                manifest_digest=cls._hash(f"NO_BASELINE:{version.version_id}")
            )

        # Gate 2: Drift detection
        if policy.require_drift_check and version.drift_detected_since_baseline:
            return PromptManifest(
                verdict=PromptVerdict.SILENT_DRIFT_DETECTED,
                directive=f"HALT: Prompt {version.version_id} behavior drifted since baseline. Re-baseline.",
                manifest_digest=cls._hash(f"DRIFT:{version.version_id}")
            )

        # Gate 3: Verified
        digest = cls._hash(json.dumps({
            "version": version.version_id,
            "text": version.text_hash,
            "baseline": version.behavioral_baseline_hash or "NONE",
            "drift": str(version.drift_detected_since_baseline)
        }, sort_keys=True))
        
        return PromptManifest(
            verdict=PromptVerdict.BASELINE_VERIFIED,
            directive=f"PROCEED: Prompt {version.version_id} version verified with behavioral baseline.",
            manifest_digest=digest
        )