agent-lifecycle-kit 1.50.1__py3-none-any.whl

agent_lifecycle/quality/failure_classification.py

@@ -0,0 +1,318 @@
+"""Neutral failure classification receipts for escalation decisions."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from agent_lifecycle.contracts import LifecycleError, canonical_digest
+
+FAILURE_CLASSIFICATION_SCHEMA = "agent-failure-classification-receipt.v1"
+FAILURE_CLASSIFICATION_VALIDATION_SCHEMA = "agent-failure-classification-validation.v1"
+
+FAILURE_CLASSES = (
+    "edge-case",
+    "api-contract",
+    "serialization",
+    "race",
+    "permission",
+    "migration",
+    "performance",
+    "flaky-test",
+    "security-bug",
+    "unknown",
+)
+CONFIDENCE_LEVELS = {"LOW", "MEDIUM", "HIGH"}
+HIGH_RISK_FAILURE_CLASSES = {"security-bug", "race"}
+FORBIDDEN_CORE_KEYS = {
+    "provider",
+    "providerid",
+    "providermodel",
+    "providermodelhash",
+    "providername",
+    "modelid",
+    "modelname",
+}
+
+CLASS_PATTERNS: dict[str, tuple[str, ...]] = {
+    "security-bug": ("security", "vulnerability", "xss", "csrf", "sql injection", "token leak", "secret leak"),
+    "race": ("race", "deadlock", "concurrent", "mutex", "thread", "lock contention", "async ordering"),
+    "flaky-test": ("flaky", "intermittent", "non-deterministic", "rerun passed", "passes on retry"),
+    "permission": ("permissionerror", "permission denied", "forbidden", "access denied", "unauthorized"),
+    "performance": ("timeout", "latency", "slow", "performance", "oom", "out of memory", "cpu", "memory"),
+    "migration": ("migration", "schema version", "database version", "alembic", "migrate"),
+    "serialization": ("serialize", "deserialize", "serialization", "jsondecode", "json decode", "yaml", "encoding"),
+    "api-contract": ("contract", "schema mismatch", "status code", "http ", "expected", "assertionerror"),
+    "edge-case": ("none", "null", "nil", "empty", "missing", "boundary", "indexerror", "out of range"),
+}
+
+
+def build_failure_classification_receipt(
+    *,
+    failure: dict[str, Any],
+    evidence: list[dict[str, Any]] | None = None,
+    failure_fingerprint: dict[str, Any] | None = None,
+    flake_signal: dict[str, Any] | None = None,
+    evidence_ids: list[str] | None = None,
+    declared_class: str | None = None,
+) -> dict[str, Any]:
+    """Classify a failure using neutral evidence, not provider or model names."""
+
+    failure_body = _object(failure, "failure")
+    evidence_rows = _evidence_rows(evidence, failure_body=failure_body, flake_signal=flake_signal)
+    blockers = _neutrality_blockers({"failure": failure_body, "evidence": evidence_rows, "flakeSignal": flake_signal})
+    selected, matched = _classify(failure_body, evidence_rows, flake_signal=flake_signal, declared_class=declared_class)
+    confidence = _confidence(selected, matched, failure_fingerprint=failure_fingerprint, flake_signal=flake_signal, declared_class=declared_class)
+    if declared_class is not None and declared_class not in FAILURE_CLASSES:
+        blockers.append({"code": "failure-classification-declared-class-invalid", "failureClass": declared_class})
+    body = {
+        "schemaVersion": FAILURE_CLASSIFICATION_SCHEMA,
+        "status": "PASS" if not blockers else "FAIL",
+        "failureClass": selected,
+        "confidence": confidence,
+        "highRiskFailureClass": selected in HIGH_RISK_FAILURE_CLASSES,
+        "evidence": {
+            "evidenceBacked": bool(evidence_rows),
+            "matchedSignals": matched,
+            "evidenceCount": len(evidence_rows),
+            "flakeStatus": _flake_status(flake_signal),
+        },
+        "failureFingerprintDigest": _optional_digest(failure_fingerprint, "fingerprintDigest"),
+        "evidenceIds": _string_list(evidence_ids or [], allow_empty=True, label="evidenceIds"),
+        "reasonCodes": _reason_codes(selected, confidence, matched, declared_class=declared_class),
+        "providerModelNamesInCore": False,
+        "productionPromotionClaimed": False,
+        "blockers": blockers,
+    }
+    return {**body, "classificationDigest": canonical_digest(body)}
+
+
+def validate_failure_classification_receipt(receipt: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(receipt, dict):
+        raise LifecycleError("invalid-failure-classification-receipt", "failure classification receipt must be an object")
+    blockers: list[dict[str, Any]] = []
+    if receipt.get("schemaVersion") != FAILURE_CLASSIFICATION_SCHEMA:
+        blockers.append({"code": "failure-classification-schema-invalid"})
+    status = receipt.get("status")
+    if status not in {"PASS", "FAIL"}:
+        blockers.append({"code": "failure-classification-status-invalid", "status": status})
+    failure_class = receipt.get("failureClass")
+    if failure_class not in FAILURE_CLASSES:
+        blockers.append({"code": "failure-classification-class-invalid", "failureClass": failure_class})
+    confidence = receipt.get("confidence")
+    if confidence not in CONFIDENCE_LEVELS:
+        blockers.append({"code": "failure-classification-confidence-invalid", "confidence": confidence})
+    if failure_class == "unknown" and confidence != "LOW":
+        blockers.append({"code": "failure-classification-unknown-confidence"})
+    evidence = receipt.get("evidence")
+    if not isinstance(evidence, dict):
+        blockers.append({"code": "failure-classification-evidence-invalid"})
+    else:
+        if evidence.get("evidenceBacked") is not True:
+            blockers.append({"code": "failure-classification-evidence-missing"})
+        if not isinstance(evidence.get("matchedSignals", []), list):
+            blockers.append({"code": "failure-classification-matched-signals-invalid"})
+    if receipt.get("failureFingerprintDigest") is not None and not _is_digest(receipt.get("failureFingerprintDigest")):
+        blockers.append({"code": "failure-classification-fingerprint-digest-invalid"})
+    _check_string_list(receipt.get("evidenceIds", []), "failure-classification-evidence-ids-invalid", blockers)
+    if receipt.get("providerModelNamesInCore") is not False:
+        blockers.append({"code": "failure-classification-provider-model-core"})
+    if receipt.get("productionPromotionClaimed") is not False:
+        blockers.append({"code": "failure-classification-production-claim"})
+    embedded_blockers = receipt.get("blockers")
+    if not isinstance(embedded_blockers, list) or not all(isinstance(item, dict) for item in embedded_blockers):
+        blockers.append({"code": "failure-classification-blockers-invalid"})
+        embedded_blockers = []
+    if status == "PASS" and embedded_blockers:
+        blockers.append({"code": "failure-classification-pass-with-blockers"})
+    if status == "FAIL" and not embedded_blockers:
+        blockers.append({"code": "failure-classification-fail-without-blockers"})
+    expected_digest = canonical_digest({key: value for key, value in receipt.items() if key != "classificationDigest"})
+    if receipt.get("classificationDigest") != expected_digest:
+        blockers.append({"code": "failure-classification-digest-mismatch"})
+    body = {
+        "schemaVersion": FAILURE_CLASSIFICATION_VALIDATION_SCHEMA,
+        "status": "PASS" if not blockers else "FAIL",
+        "receiptStatus": status if isinstance(status, str) else None,
+        "failureClass": failure_class if failure_class in FAILURE_CLASSES else None,
+        "confidence": confidence if confidence in CONFIDENCE_LEVELS else None,
+        "blockers": blockers,
+        "classificationDigest": receipt.get("classificationDigest"),
+    }
+    return {**body, "validationDigest": canonical_digest(body)}
+
+
+def require_failure_classification_pass(validation: dict[str, Any]) -> dict[str, Any]:
+    if validation.get("status") != "PASS" or validation.get("receiptStatus") != "PASS":
+        raise LifecycleError("failure-classification-validation-failed", "failure classification did not pass", {"validation": validation})
+    return validation
+
+
+def _classify(
+    failure: dict[str, Any],
+    evidence: list[dict[str, Any]],
+    *,
+    flake_signal: dict[str, Any] | None,
+    declared_class: str | None,
+) -> tuple[str, list[dict[str, Any]]]:
+    search_payload: dict[str, Any] = {"failure": failure, "evidence": evidence}
+    if flake_signal is not None:
+        search_payload["flakeSignal"] = flake_signal
+    text = _search_text(search_payload)
+    matches: list[dict[str, Any]] = []
+    if _flake_status(flake_signal) == "flaky":
+        matches.append({"failureClass": "flaky-test", "signal": "flake-status"})
+    for failure_class, patterns in CLASS_PATTERNS.items():
+        for pattern in patterns:
+            if pattern in text:
+                matches.append({"failureClass": failure_class, "signal": pattern})
+    if declared_class in FAILURE_CLASSES:
+        matches.append({"failureClass": declared_class, "signal": "declared-class"})
+    if not matches:
+        return "unknown", []
+    selected = sorted(matches, key=lambda item: (_class_priority(str(item["failureClass"])), str(item["signal"])))[0]
+    return str(selected["failureClass"]), matches
+
+
+def _confidence(
+    selected: str,
+    matches: list[dict[str, Any]],
+    *,
+    failure_fingerprint: dict[str, Any] | None,
+    flake_signal: dict[str, Any] | None,
+    declared_class: str | None,
+) -> str:
+    if selected == "unknown":
+        return "LOW"
+    if selected == "flaky-test" and _flake_status(flake_signal) == "flaky":
+        return "HIGH"
+    selected_matches = [item for item in matches if item.get("failureClass") == selected and item.get("signal") != "declared-class"]
+    if failure_fingerprint is not None and _optional_digest(failure_fingerprint, "fingerprintDigest") is not None:
+        return "HIGH"
+    if len(selected_matches) >= 2:
+        return "HIGH"
+    if selected_matches:
+        return "MEDIUM"
+    return "LOW" if declared_class == selected else "MEDIUM"
+
+
+def _reason_codes(selected: str, confidence: str, matches: list[dict[str, Any]], *, declared_class: str | None) -> list[str]:
+    reasons = [f"failure-class-{selected}", f"confidence-{confidence.lower()}"]
+    if declared_class is not None:
+        reasons.append("declared-class-present")
+    reasons.extend(f"signal-{item['signal']}" for item in matches[:8] if isinstance(item.get("signal"), str))
+    return reasons
+
+
+def _class_priority(failure_class: str) -> int:
+    order = {
+        "security-bug": 0,
+        "race": 1,
+        "flaky-test": 2,
+        "permission": 3,
+        "performance": 4,
+        "migration": 5,
+        "serialization": 6,
+        "api-contract": 7,
+        "edge-case": 8,
+        "unknown": 9,
+    }
+    return order.get(failure_class, 99)
+
+
+def _evidence_rows(
+    evidence: list[dict[str, Any]] | None,
+    *,
+    failure_body: dict[str, Any],
+    flake_signal: dict[str, Any] | None,
+) -> list[dict[str, Any]]:
+    if evidence is None:
+        rows: list[dict[str, Any]] = [{"source": "failure", "fields": sorted(failure_body)}]
+        if flake_signal is not None:
+            rows.append({"source": "flake-signal", "status": _flake_status(flake_signal)})
+        return rows
+    if not isinstance(evidence, list):
+        raise LifecycleError("invalid-failure-classification-receipt", "evidence must be an array")
+    if any(not isinstance(item, dict) or not item for item in evidence):
+        raise LifecycleError("invalid-failure-classification-receipt", "evidence items must be non-empty objects")
+    return [dict(item) for item in evidence]
+
+
+def _object(value: Any, label: str) -> dict[str, Any]:
+    if not isinstance(value, dict) or not value:
+        raise LifecycleError("invalid-failure-classification-receipt", f"{label} must be a non-empty object")
+    return dict(value)
+
+
+def _string_list(value: Any, *, allow_empty: bool, label: str) -> list[str]:
+    if not isinstance(value, list):
+        raise LifecycleError("invalid-failure-classification-receipt", f"{label} must be an array")
+    if not value and not allow_empty:
+        raise LifecycleError("invalid-failure-classification-receipt", f"{label} must not be empty")
+    if not all(isinstance(item, str) and item for item in value):
+        raise LifecycleError("invalid-failure-classification-receipt", f"{label} must contain non-empty strings")
+    return list(value)
+
+
+def _check_string_list(value: Any, code: str, blockers: list[dict[str, Any]]) -> None:
+    if not isinstance(value, list) or not all(isinstance(item, str) and item for item in value):
+        blockers.append({"code": code})
+
+
+def _optional_digest(value: dict[str, Any] | None, key: str) -> str | None:
+    if value is None:
+        return None
+    digest = value.get(key)
+    if digest is None:
+        return None
+    if not _is_digest(digest):
+        raise LifecycleError("invalid-failure-classification-receipt", f"{key} must be a sha256 digest")
+    return str(digest)
+
+
+def _is_digest(value: Any) -> bool:
+    return isinstance(value, str) and len(value) == 64 and all(char in "0123456789abcdef" for char in value)
+
+
+def _flake_status(value: dict[str, Any] | None) -> str | None:
+    if not isinstance(value, dict):
+        return None
+    status = value.get("status") or value.get("flakeStatus")
+    return status if status in {"stable-fail", "stable-pass", "flaky", "inconclusive"} else None
+
+
+def _search_text(value: Any) -> str:
+    return json.dumps(value, sort_keys=True, ensure_ascii=True, default=str).lower()
+
+
+def _neutrality_blockers(value: Any) -> list[dict[str, Any]]:
+    blockers: list[dict[str, Any]] = []
+    for path, _item in _walk(value):
+        key = path.rsplit(".", 1)[-1]
+        normalized = key.replace("_", "").replace("-", "").lower()
+        if normalized in FORBIDDEN_CORE_KEYS:
+            blockers.append({"code": "failure-classification-provider-model-key", "path": path})
+    return blockers
+
+
+def _walk(value: Any, prefix: str = "$") -> list[tuple[str, Any]]:
+    rows: list[tuple[str, Any]] = []
+    if isinstance(value, dict):
+        for key, item in value.items():
+            path = f"{prefix}.{key}"
+            rows.append((path, item))
+            rows.extend(_walk(item, path))
+    elif isinstance(value, list):
+        for index, item in enumerate(value):
+            rows.extend(_walk(item, f"{prefix}[{index}]"))
+    return rows
+
+
+__all__ = [
+    "FAILURE_CLASSES",
+    "FAILURE_CLASSIFICATION_SCHEMA",
+    "HIGH_RISK_FAILURE_CLASSES",
+    "build_failure_classification_receipt",
+    "require_failure_classification_pass",
+    "validate_failure_classification_receipt",
+]

agent_lifecycle/quality/packs.py

@@ -0,0 +1,265 @@
+"""Opt-in quality pack contracts and fixture-based behavior checks."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent_lifecycle.contracts import LifecycleError, canonical_digest
+
+QUALITY_PACK_SCHEMA = "agent-optional-quality-pack.v1"
+QUALITY_PACK_VALIDATION_SCHEMA = "agent-optional-quality-pack-validation.v1"
+BEHAVIOR_CHECK_RUN_SCHEMA = "agent-behavior-check-run.v1"
+FIXTURE_SCHEMA = "agent-behavior-check-fixture.v1"
+RESOURCE_CAP_KEYS = {
+    "maxArtifacts",
+    "maxInputBytes",
+    "maxInputTokens",
+    "maxInvocations",
+    "maxOutputTokens",
+    "maxWallSeconds",
+}
+SIGNAL_NAMES = (
+    "completion",
+    "goal",
+    "budget",
+    "eventCapture",
+    "externalAction",
+    "review",
+)
+NEGATIVE_STATUSES = {"FAIL", "BLOCKED"}
+
+
+def build_default_quality_pack() -> dict[str, Any]:
+    """Return the built-in optional quality pack manifest."""
+
+    return {
+        "schemaVersion": QUALITY_PACK_SCHEMA,
+        "packId": "optional-quality-observability",
+        "status": "OPTIONAL",
+        "enabledByDefault": False,
+        "activationMode": "opt-in",
+        "canonicalLifecycleCommandsChanged": False,
+        "providerSpecificCoreDependency": False,
+        "productionPromotionClaimed": False,
+        "defaultCommandFootprint": {
+            "extraCommands": 0,
+            "extraLiveCalls": 0,
+            "extraRequiredArtifacts": 0,
+        },
+        "commands": [
+            {
+                "name": "quality pack-check",
+                "purpose": "validate an optional quality pack manifest",
+                "inputSchemas": [QUALITY_PACK_SCHEMA],
+                "expectedEvidence": [QUALITY_PACK_VALIDATION_SCHEMA],
+                "resourceCaps": {"maxInputBytes": 32768, "maxOutputTokens": 2048},
+            },
+            {
+                "name": "quality behavior-check",
+                "purpose": "check lifecycle outcome fixtures",
+                "inputSchemas": [FIXTURE_SCHEMA],
+                "expectedEvidence": [BEHAVIOR_CHECK_RUN_SCHEMA],
+                "resourceCaps": {"maxArtifacts": 16, "maxInputBytes": 65536, "maxOutputTokens": 4096},
+            },
+        ],
+    }
+
+
+def validate_quality_pack(manifest: dict[str, Any]) -> dict[str, Any]:
+    """Validate one optional quality pack without enabling it."""
+
+    if not isinstance(manifest, dict):
+        raise LifecycleError("invalid-quality-pack", "quality pack manifest must be an object")
+    blockers: list[dict[str, Any]] = []
+    if manifest.get("schemaVersion") != QUALITY_PACK_SCHEMA:
+        blockers.append({"code": "quality-pack-schema-invalid", "message": "unsupported quality pack schemaVersion"})
+    _required_string(manifest, "packId", blockers)
+    if manifest.get("status") != "OPTIONAL":
+        blockers.append({"code": "quality-pack-not-optional", "message": "quality pack status must be OPTIONAL"})
+    if manifest.get("enabledByDefault") is not False:
+        blockers.append({"code": "quality-pack-default-enabled", "message": "quality packs must be disabled by default"})
+    if manifest.get("activationMode") != "opt-in":
+        blockers.append({"code": "quality-pack-not-opt-in", "message": "quality pack activation must be opt-in"})
+    if manifest.get("canonicalLifecycleCommandsChanged") is not False:
+        blockers.append({"code": "quality-pack-command-drift", "message": "canonical lifecycle commands must remain unchanged"})
+    if manifest.get("providerSpecificCoreDependency") is not False:
+        blockers.append({"code": "quality-pack-provider-core-dependency", "message": "quality packs cannot add provider-specific core dependencies"})
+    if manifest.get("productionPromotionClaimed") is not False:
+        blockers.append({"code": "quality-pack-promotion-overclaim", "message": "quality packs cannot claim production promotion"})
+    _validate_default_footprint(manifest.get("defaultCommandFootprint"), blockers)
+    commands = manifest.get("commands")
+    if not isinstance(commands, list) or not commands:
+        blockers.append({"code": "quality-pack-command-missing", "message": "quality pack must declare opt-in commands"})
+        commands = []
+    seen: set[str] = set()
+    for index, command in enumerate(commands):
+        _validate_command(command, index, blockers, seen)
+    body = {
+        "schemaVersion": QUALITY_PACK_VALIDATION_SCHEMA,
+        "status": "PASS" if not blockers else "FAIL",
+        "packId": manifest.get("packId"),
+        "commandCount": len(commands),
+        "defaultEnabled": manifest.get("enabledByDefault"),
+        "blockers": blockers,
+        "productionPromotionClaimed": False,
+    }
+    return {**body, "packDigest": canonical_digest(manifest), "validationDigest": canonical_digest(body)}
+
+
+def require_quality_pack_pass(payload: dict[str, Any]) -> dict[str, Any]:
+    if payload.get("status") == "FAIL":
+        raise LifecycleError("quality-pack-validation-failed", "quality pack validation failed", {"validation": payload})
+    return payload
+
+
+def run_behavior_checks(pack_manifest: dict[str, Any], fixtures: list[dict[str, Any]]) -> dict[str, Any]:
+    """Run small, deterministic lifecycle outcome checks."""
+
+    pack_validation = validate_quality_pack(pack_manifest)
+    checks: list[dict[str, Any]] = []
+    blockers: list[dict[str, Any]] = []
+    if pack_validation["status"] == "FAIL":
+        blockers.append({"code": "behavior-check-pack-invalid", "message": "quality pack validation failed"})
+    if not fixtures:
+        blockers.append({"code": "behavior-check-fixtures-missing", "message": "at least one fixture is required"})
+    for index, fixture in enumerate(fixtures):
+        checks.append(_evaluate_fixture(fixture, index, blockers))
+    failed_expectations = [item for item in checks if item["expectationStatus"] == "FAIL"]
+    if failed_expectations:
+        blockers.append(
+            {
+                "code": "behavior-check-expectation-failed",
+                "fixtureIds": [item["fixtureId"] for item in failed_expectations],
+            }
+        )
+    body = {
+        "schemaVersion": BEHAVIOR_CHECK_RUN_SCHEMA,
+        "status": "PASS" if not blockers else "FAIL",
+        "packId": pack_manifest.get("packId"),
+        "packDigest": canonical_digest(pack_manifest),
+        "fixtureCount": len(fixtures),
+        "passedExpectationCount": len([item for item in checks if item["expectationStatus"] == "PASS"]),
+        "failedExpectationCount": len(failed_expectations),
+        "checks": checks,
+        "blockers": blockers,
+        "productionPromotionClaimed": False,
+    }
+    return {**body, "runDigest": canonical_digest(body)}
+
+
+def require_behavior_checks_pass(payload: dict[str, Any]) -> dict[str, Any]:
+    if payload.get("status") == "FAIL":
+        raise LifecycleError("behavior-check-failed", "behavior checks failed", {"validation": payload})
+    return payload
+
+
+def _validate_command(command: object, index: int, blockers: list[dict[str, Any]], seen: set[str]) -> None:
+    if not isinstance(command, dict):
+        blockers.append({"code": "quality-pack-command-invalid", "index": index, "message": "command must be an object"})
+        return
+    name = command.get("name")
+    if not isinstance(name, str) or not name:
+        blockers.append({"code": "quality-pack-command-name-missing", "index": index})
+    elif name in seen:
+        blockers.append({"code": "quality-pack-command-duplicate", "command": name})
+    else:
+        seen.add(name)
+    _required_string(command, "purpose", blockers, index=index)
+    _required_string_list(command.get("inputSchemas"), "inputSchemas", blockers, index=index)
+    _required_string_list(command.get("expectedEvidence"), "expectedEvidence", blockers, index=index)
+    _validate_resource_caps(command.get("resourceCaps"), blockers, index=index)
+
+
+def _validate_default_footprint(value: object, blockers: list[dict[str, Any]]) -> None:
+    if not isinstance(value, dict):
+        blockers.append({"code": "quality-pack-default-footprint-missing", "message": "default footprint is required"})
+        return
+    for key in ("extraCommands", "extraLiveCalls", "extraRequiredArtifacts"):
+        if value.get(key) != 0:
+            blockers.append({"code": "quality-pack-default-footprint-nonzero", "field": key})
+
+
+def _validate_resource_caps(value: object, blockers: list[dict[str, Any]], *, index: int | None = None) -> None:
+    if not isinstance(value, dict) or not value:
+        blockers.append({"code": "quality-pack-resource-caps-missing", "index": index})
+        return
+    supported = [key for key in value if key in RESOURCE_CAP_KEYS]
+    if not supported:
+        blockers.append({"code": "quality-pack-resource-caps-unsupported", "index": index})
+    for key in supported:
+        number = value.get(key)
+        if not isinstance(number, (int, float)) or isinstance(number, bool) or number <= 0:
+            blockers.append({"code": "quality-pack-resource-cap-invalid", "index": index, "field": key})
+
+
+def _evaluate_fixture(fixture: dict[str, Any], index: int, blockers: list[dict[str, Any]]) -> dict[str, Any]:
+    fixture_blockers: list[dict[str, Any]] = []
+    if not isinstance(fixture, dict):
+        blockers.append({"code": "behavior-check-fixture-invalid", "index": index})
+        return {
+            "fixtureId": f"fixture-{index}",
+            "expectedOutcome": None,
+            "actualOutcome": "FAIL",
+            "expectationStatus": "FAIL",
+            "blockerCodes": ["behavior-check-fixture-invalid"],
+        }
+    if fixture.get("schemaVersion") != FIXTURE_SCHEMA:
+        fixture_blockers.append({"code": "behavior-check-fixture-schema-invalid"})
+    fixture_id = fixture.get("fixtureId")
+    if not isinstance(fixture_id, str) or not fixture_id:
+        fixture_id = f"fixture-{index}"
+        fixture_blockers.append({"code": "behavior-check-fixture-id-missing"})
+    expected = fixture.get("expectedOutcome")
+    if expected not in {"PASS", "FAIL", "BLOCKED"}:
+        fixture_blockers.append({"code": "behavior-check-expected-outcome-invalid"})
+        expected = "FAIL"
+    signals = fixture.get("signals")
+    if not isinstance(signals, dict):
+        signals = {}
+        fixture_blockers.append({"code": "behavior-check-signals-missing"})
+    signal_blockers = _signal_blockers(signals)
+    for item in fixture_blockers:
+        blockers.append({"fixtureId": fixture_id, **item})
+    actual = "FAIL" if signal_blockers or fixture_blockers else "PASS"
+    if any(item.get("status") == "BLOCKED" for item in signals.values() if isinstance(item, dict)):
+        actual = "BLOCKED"
+    expectation_status = "PASS" if actual == expected else "FAIL"
+    return {
+        "fixtureId": fixture_id,
+        "expectedOutcome": expected,
+        "actualOutcome": actual,
+        "expectationStatus": expectation_status,
+        "signalCount": len(signals),
+        "blockerCodes": [item["code"] for item in [*fixture_blockers, *signal_blockers]],
+    }
+
+
+def _signal_blockers(signals: dict[str, Any]) -> list[dict[str, Any]]:
+    blockers: list[dict[str, Any]] = []
+    for name in SIGNAL_NAMES:
+        signal = signals.get(name)
+        if signal is None:
+            continue
+        if not isinstance(signal, dict):
+            blockers.append({"code": "behavior-check-signal-invalid", "signal": name})
+            continue
+        status = signal.get("status")
+        if status in NEGATIVE_STATUSES:
+            blockers.append({"code": f"behavior-check-{name}-blocked", "status": status})
+    return blockers
+
+
+def _required_string(value: dict[str, Any], key: str, blockers: list[dict[str, Any]], *, index: int | None = None) -> None:
+    if not isinstance(value.get(key), str) or not value.get(key):
+        item = {"code": f"quality-pack-{key}-missing"}
+        if index is not None:
+            item["index"] = index
+        blockers.append(item)
+
+
+def _required_string_list(value: object, key: str, blockers: list[dict[str, Any]], *, index: int | None = None) -> None:
+    if not isinstance(value, list) or not value or not all(isinstance(item, str) and item for item in value):
+        item = {"code": f"quality-pack-{key}-invalid"}
+        if index is not None:
+            item["index"] = index
+        blockers.append(item)

agent_lifecycle/reporting/__init__.py

@@ -0,0 +1,37 @@
+"""Read-only reporting views over existing lifecycle artifacts."""
+
+from agent_lifecycle.reporting.event_feed import build_workflow_event_feed
+from agent_lifecycle.reporting.change_summary import build_change_summary_receipt
+from agent_lifecycle.reporting.progress_bridge import (
+    build_progress_bridge_config,
+    build_progress_bridge_receipt,
+    render_progress_bridge_terminal,
+)
+from agent_lifecycle.reporting.progress_hooks import (
+    build_progress_hook_policy,
+    build_progress_hook_receipt,
+    write_progress_hook_receipt,
+)
+from agent_lifecycle.reporting.progress_view import build_lifecycle_progress_view, build_lifecycle_progress_watch
+from agent_lifecycle.reporting.progress_terminal import render_goal_view_terminal, render_progress_terminal
+from agent_lifecycle.reporting.status_view import build_status_view, require_status_view_pass
+from agent_lifecycle.reporting.usage_export import render_usage_export_json, render_usage_export_table
+
+__all__ = [
+    "build_change_summary_receipt",
+    "build_lifecycle_progress_view",
+    "build_lifecycle_progress_watch",
+    "build_progress_bridge_config",
+    "build_progress_bridge_receipt",
+    "build_progress_hook_policy",
+    "build_progress_hook_receipt",
+    "build_status_view",
+    "build_workflow_event_feed",
+    "render_progress_bridge_terminal",
+    "render_goal_view_terminal",
+    "render_progress_terminal",
+    "render_usage_export_json",
+    "render_usage_export_table",
+    "require_status_view_pass",
+    "write_progress_hook_receipt",
+]