agent-alignment-protocol 0.1.7__tar.gz → 0.2.0__tar.gz

{agent_alignment_protocol-0.1.7 → agent_alignment_protocol-0.2.0}/.gitignore

@@ -68,6 +68,10 @@ architecture/
 gtm/
 traces/
 
+# Node
+node_modules/
+
 # Claude Code
 .claude/
 .mcp.json
+*.tgz

{agent_alignment_protocol-0.1.7 → agent_alignment_protocol-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-alignment-protocol
-Version: 0.1.7
+Version: 0.2.0
 Summary: Agent Alignment Protocol - The missing alignment layer for the agent protocol stack
 Project-URL: Homepage, https://github.com/mnemom/aap
 Project-URL: Documentation, https://github.com/mnemom/aap#readme
@@ -46,7 +46,7 @@ Description-Content-Type: text/markdown
 [![PyPI](https://img.shields.io/pypi/v/agent-alignment-protocol.svg)](https://pypi.org/project/agent-alignment-protocol/)
 [![npm](https://img.shields.io/npm/v/@mnemom/agent-alignment-protocol.svg)](https://www.npmjs.com/package/@mnemom/agent-alignment-protocol)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
-[![Spec](https://img.shields.io/badge/spec-v0.1.0-green.svg)](docs/SPEC.md)
+[![Spec](https://img.shields.io/badge/spec-v0.1.0-green.svg)](https://docs.mnemom.ai/protocols/aap/specification)
 
 **A transparency protocol for autonomous agents.**
 
@@ -207,7 +207,7 @@ This matters. Read it.
 
 5. **Tested on transformer-based agents.** Other architectures may exhibit behaviors AAP doesn't capture.
 
-For the complete limitations disclosure, see [Section 10 of the Specification](docs/SPEC.md#10-limitations).
+For the complete limitations disclosure, see [Section 10 of the Specification](https://docs.mnemom.ai/protocols/aap/specification#10-limitations).
 
 ## Installation
 
@@ -216,7 +216,7 @@ For the complete limitations disclosure, see [Section 10 of the Specification](d
 pip install agent-alignment-protocol
 
 # TypeScript
-npm install agent-alignment-protocol
+npm install @mnemom/agent-alignment-protocol
 ```
 
 ## Integration
@@ -236,7 +236,7 @@ AAP extends the A2A Agent Card with an `alignment` block:
 }
 ```
 
-See [A2A Migration Guide](docs/a2a-migration.md).
+See [A2A Integration Guide](https://docs.mnemom.ai/protocols/aap/a2a-integration).
 
 ### With MCP Tools
 
@@ -250,7 +250,7 @@ def my_tool(params):
     ...
 ```
 
-See [MCP Migration Guide](docs/mcp-migration.md).
+See [MCP Migration Guide](https://docs.mnemom.ai/protocols/aap/mcp-migration).
 
 ## Verification
 
@@ -280,6 +280,26 @@ for alert in alerts:
 - Forbidden action compliance (no forbidden actions taken)
 - Behavioral similarity (semantic alignment using SSM analysis)
 
+### Action Name Matching
+
+Bounded and forbidden action lists support flexible matching (v0.1.7+):
+
+```json
+{
+  "bounded_actions": [
+    "search",
+    "exec: execute shell commands",
+    "cron: manage scheduled patrol jobs"
+  ]
+}
+```
+
+- **Exact match**: `"search"` matches action name `"search"`
+- **Colon-prefix match**: `"exec: execute shell commands"` matches action name `"exec"`
+- **Compound actions**: action name `"exec, read"` matches when *each* component is in the bounded list
+
+This allows descriptive entries in alignment cards while keeping verification flexible.
+
 **Similarity scoring:** Each verification returns a `similarity_score` (0.0-1.0) measuring semantic similarity between the trace and declared alignment. If a trace passes structural checks but has `similarity_score < 0.50`, a `low_behavioral_similarity` warning is generated.
 
 ## Try It
@@ -297,24 +317,24 @@ No server required — runs entirely client-side via WebAssembly.
 
 | Document | Description |
 |----------|-------------|
-| [**SPEC.md**](docs/SPEC.md) | Full protocol specification (IETF-style) |
-| [**QUICKSTART.md**](docs/QUICKSTART.md) | Zero to compliant in 5 minutes |
-| [**LIMITS.md**](docs/LIMITS.md) | What AAP guarantees and doesn't |
-| [**SECURITY.md**](docs/SECURITY.md) | Threat model and security considerations |
-| [**CALIBRATION.md**](docs/CALIBRATION.md) | How verification thresholds were derived |
+| [**Specification**](https://docs.mnemom.ai/protocols/aap/specification) | Full protocol specification (IETF-style) |
+| [**Quick Start**](https://docs.mnemom.ai/protocols/aap/quickstart) | Zero to compliant in 5 minutes |
+| [**Limitations**](https://docs.mnemom.ai/protocols/aap/limitations) | What AAP guarantees and doesn't |
+| [**Security**](https://docs.mnemom.ai/protocols/aap/security) | Threat model and security considerations |
+| [**Calibration**](https://docs.mnemom.ai/protocols/aap/calibration) | How verification thresholds were derived |
 
 ## Examples
 
 | Example | Description |
 |---------|-------------|
 | [`simple-agent/`](examples/simple-agent/) | Minimal AAP implementation |
-| [`a2a-integration/`](examples/a2a-integration/) | A2A agent with AAP |
+| [`a2a-integration/`](examples/a2a-integration/) | A2A agent with AAP (Python + TypeScript) |
 | [`mcp-integration/`](examples/mcp-integration/) | MCP tools with alignment |
 | [`alignment-failure/`](examples/alignment-failure/) | Deliberate failure for testing |
 
 ## Status
 
-**Current Version**: 0.1.1 (Draft)
+**Current Version**: 0.1.8
 
 | Component | Status |
 |-----------|--------|
@@ -354,6 +374,19 @@ from aap import (
 # aap drift --card CARD --traces TRACES_DIR   → Uses SSM analysis
 ```
 
+## Standards & Compliance
+
+AAP aligns with and supports compliance for the following international standards and regulatory frameworks:
+
+| Standard | Relevance to AAP |
+|----------|-----------------|
+| **[ISO/IEC 42001:2023](https://www.iso.org/standard/42001)** — AI Management Systems | Alignment Card provides the structured AI system documentation required by 42001 management systems |
+| **[ISO/IEC 42005:2025](https://www.iso.org/standard/42005)** — AI System Impact Assessment | AP-Trace and drift detection support ongoing impact assessment and monitoring |
+| **[IEEE 7001-2021](https://standards.ieee.org/ieee/7001/6929/)** — Transparency of Autonomous Systems | AAP's core design goal — making agent decisions observable — directly implements IEEE 7001 transparency requirements |
+| **[IEEE 3152-2024](https://standards.ieee.org/ieee/3152/11718/)** — Transparent Human and Machine Agency Identification | Alignment Card `agent_id`, `principal` block, and relationship types map to IEEE 3152 agency identification |
+| **[Singapore IMDA Model AI Governance Framework for Agentic AI](https://www.imda.gov.sg/-/media/imda/files/about/emerging-tech-and-research/artificial-intelligence/mgf-for-agentic-ai.pdf)** (Jan 2026) | Alignment Card + Value Coherence Handshake address IMDA's agentic AI governance principles for multi-agent coordination |
+| **[EU AI Act Article 50](https://artificialintelligenceact.eu/article/50/)** — Transparency Obligations (enforcement Aug 2026) | Alignment Card `principal` + disclosure fields, AP-Trace structured audit trails, and `audit_commitment.retention_days` support Article 50 compliance. See [EU AI Act Compliance Guide](https://docs.mnemom.ai/guides/eu-compliance) |
+
 ## Contributing
 
 We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

{agent_alignment_protocol-0.1.7 → agent_alignment_protocol-0.2.0}/README.md

@@ -6,7 +6,7 @@
 [![PyPI](https://img.shields.io/pypi/v/agent-alignment-protocol.svg)](https://pypi.org/project/agent-alignment-protocol/)
 [![npm](https://img.shields.io/npm/v/@mnemom/agent-alignment-protocol.svg)](https://www.npmjs.com/package/@mnemom/agent-alignment-protocol)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
-[![Spec](https://img.shields.io/badge/spec-v0.1.0-green.svg)](docs/SPEC.md)
+[![Spec](https://img.shields.io/badge/spec-v0.1.0-green.svg)](https://docs.mnemom.ai/protocols/aap/specification)
 
 **A transparency protocol for autonomous agents.**
 
@@ -167,7 +167,7 @@ This matters. Read it.
 
 5. **Tested on transformer-based agents.** Other architectures may exhibit behaviors AAP doesn't capture.
 
-For the complete limitations disclosure, see [Section 10 of the Specification](docs/SPEC.md#10-limitations).
+For the complete limitations disclosure, see [Section 10 of the Specification](https://docs.mnemom.ai/protocols/aap/specification#10-limitations).
 
 ## Installation
 
@@ -176,7 +176,7 @@ For the complete limitations disclosure, see [Section 10 of the Specification](d
 pip install agent-alignment-protocol
 
 # TypeScript
-npm install agent-alignment-protocol
+npm install @mnemom/agent-alignment-protocol
 ```
 
 ## Integration
@@ -196,7 +196,7 @@ AAP extends the A2A Agent Card with an `alignment` block:
 }
 ```
 
-See [A2A Migration Guide](docs/a2a-migration.md).
+See [A2A Integration Guide](https://docs.mnemom.ai/protocols/aap/a2a-integration).
 
 ### With MCP Tools
 
@@ -210,7 +210,7 @@ def my_tool(params):
     ...
 ```
 
-See [MCP Migration Guide](docs/mcp-migration.md).
+See [MCP Migration Guide](https://docs.mnemom.ai/protocols/aap/mcp-migration).
 
 ## Verification
 
@@ -240,6 +240,26 @@ for alert in alerts:
 - Forbidden action compliance (no forbidden actions taken)
 - Behavioral similarity (semantic alignment using SSM analysis)
 
+### Action Name Matching
+
+Bounded and forbidden action lists support flexible matching (v0.1.7+):
+
+```json
+{
+  "bounded_actions": [
+    "search",
+    "exec: execute shell commands",
+    "cron: manage scheduled patrol jobs"
+  ]
+}
+```
+
+- **Exact match**: `"search"` matches action name `"search"`
+- **Colon-prefix match**: `"exec: execute shell commands"` matches action name `"exec"`
+- **Compound actions**: action name `"exec, read"` matches when *each* component is in the bounded list
+
+This allows descriptive entries in alignment cards while keeping verification flexible.
+
 **Similarity scoring:** Each verification returns a `similarity_score` (0.0-1.0) measuring semantic similarity between the trace and declared alignment. If a trace passes structural checks but has `similarity_score < 0.50`, a `low_behavioral_similarity` warning is generated.
 
 ## Try It
@@ -257,24 +277,24 @@ No server required — runs entirely client-side via WebAssembly.
 
 | Document | Description |
 |----------|-------------|
-| [**SPEC.md**](docs/SPEC.md) | Full protocol specification (IETF-style) |
-| [**QUICKSTART.md**](docs/QUICKSTART.md) | Zero to compliant in 5 minutes |
-| [**LIMITS.md**](docs/LIMITS.md) | What AAP guarantees and doesn't |
-| [**SECURITY.md**](docs/SECURITY.md) | Threat model and security considerations |
-| [**CALIBRATION.md**](docs/CALIBRATION.md) | How verification thresholds were derived |
+| [**Specification**](https://docs.mnemom.ai/protocols/aap/specification) | Full protocol specification (IETF-style) |
+| [**Quick Start**](https://docs.mnemom.ai/protocols/aap/quickstart) | Zero to compliant in 5 minutes |
+| [**Limitations**](https://docs.mnemom.ai/protocols/aap/limitations) | What AAP guarantees and doesn't |
+| [**Security**](https://docs.mnemom.ai/protocols/aap/security) | Threat model and security considerations |
+| [**Calibration**](https://docs.mnemom.ai/protocols/aap/calibration) | How verification thresholds were derived |
 
 ## Examples
 
 | Example | Description |
 |---------|-------------|
 | [`simple-agent/`](examples/simple-agent/) | Minimal AAP implementation |
-| [`a2a-integration/`](examples/a2a-integration/) | A2A agent with AAP |
+| [`a2a-integration/`](examples/a2a-integration/) | A2A agent with AAP (Python + TypeScript) |
 | [`mcp-integration/`](examples/mcp-integration/) | MCP tools with alignment |
 | [`alignment-failure/`](examples/alignment-failure/) | Deliberate failure for testing |
 
 ## Status
 
-**Current Version**: 0.1.1 (Draft)
+**Current Version**: 0.1.8
 
 | Component | Status |
 |-----------|--------|
@@ -314,6 +334,19 @@ from aap import (
 # aap drift --card CARD --traces TRACES_DIR   → Uses SSM analysis
 ```
 
+## Standards & Compliance
+
+AAP aligns with and supports compliance for the following international standards and regulatory frameworks:
+
+| Standard | Relevance to AAP |
+|----------|-----------------|
+| **[ISO/IEC 42001:2023](https://www.iso.org/standard/42001)** — AI Management Systems | Alignment Card provides the structured AI system documentation required by 42001 management systems |
+| **[ISO/IEC 42005:2025](https://www.iso.org/standard/42005)** — AI System Impact Assessment | AP-Trace and drift detection support ongoing impact assessment and monitoring |
+| **[IEEE 7001-2021](https://standards.ieee.org/ieee/7001/6929/)** — Transparency of Autonomous Systems | AAP's core design goal — making agent decisions observable — directly implements IEEE 7001 transparency requirements |
+| **[IEEE 3152-2024](https://standards.ieee.org/ieee/3152/11718/)** — Transparent Human and Machine Agency Identification | Alignment Card `agent_id`, `principal` block, and relationship types map to IEEE 3152 agency identification |
+| **[Singapore IMDA Model AI Governance Framework for Agentic AI](https://www.imda.gov.sg/-/media/imda/files/about/emerging-tech-and-research/artificial-intelligence/mgf-for-agentic-ai.pdf)** (Jan 2026) | Alignment Card + Value Coherence Handshake address IMDA's agentic AI governance principles for multi-agent coordination |
+| **[EU AI Act Article 50](https://artificialintelligenceact.eu/article/50/)** — Transparency Obligations (enforcement Aug 2026) | Alignment Card `principal` + disclosure fields, AP-Trace structured audit trails, and `audit_commitment.retention_days` support Article 50 compliance. See [EU AI Act Compliance Guide](https://docs.mnemom.ai/guides/eu-compliance) |
+
 ## Contributing
 
 We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

{agent_alignment_protocol-0.1.7 → agent_alignment_protocol-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-alignment-protocol"
-version = "0.1.7"
+version = "0.2.0"
 description = "Agent Alignment Protocol - The missing alignment layer for the agent protocol stack"
 readme = "README.md"
 license = "Apache-2.0"

{agent_alignment_protocol-0.1.7 → agent_alignment_protocol-0.2.0}/src/aap/__init__.py

@@ -38,16 +38,19 @@ See docs/SPEC.md for the full protocol specification.
 
 __version__ = "0.1.0"
 
-# Core verification API
+# EU AI Act compliance presets
+from aap.compliance import (
+    EU_COMPLIANCE_AUDIT_COMMITMENT,
+    EU_COMPLIANCE_EXTENSIONS,
+    EU_COMPLIANCE_VALUES,
+)
+
 # Schema models
 from aap.schemas import (
-    # AP-Trace
     Action,
     ActionCategory,
     ActionType,
-    # Alignment Card
     AlignmentCard,
-    # Value Coherence Handshake
     AlignmentCardRequest,
     AlignmentCardResponse,
     Alternative,
@@ -82,20 +85,27 @@ from aap.tracing import (
 
 # Verification result models
 from aap.verification import (
+    AgentCoherenceSummary,
     CoherenceResult,
     DriftAlert,
     DriftAnalysis,
     DriftDirection,
     DriftIndicator,
+    FleetCluster,
+    FleetCoherenceResult,
+    FleetOutlier,
+    PairwiseEntry,
     Severity,
     ValueAlignment,
     ValueConflict,
+    ValueDivergence,
     VerificationMetadata,
     VerificationResult,
     Violation,
     ViolationType,
     Warning,
     check_coherence,
+    check_fleet_coherence,
     detect_drift,
     verify_trace,
 )
@@ -106,6 +116,7 @@ __all__ = [
     # Core API
     "verify_trace",
     "check_coherence",
+    "check_fleet_coherence",
     "detect_drift",
     # Tracing Decorators
     "trace_decision",
@@ -126,6 +137,13 @@ __all__ = [
     "CoherenceResult",
     "ValueAlignment",
     "ValueConflict",
+    # Fleet Coherence (E-05)
+    "FleetCoherenceResult",
+    "PairwiseEntry",
+    "FleetOutlier",
+    "FleetCluster",
+    "ValueDivergence",
+    "AgentCoherenceSummary",
     "DriftAlert",
     "DriftAnalysis",
     "DriftDirection",
@@ -155,4 +173,8 @@ __all__ = [
     "ValueCoherenceCheck",
     "CoherenceResultMessage",
     "ProposedCollaboration",
+    # EU AI Act Compliance
+    "EU_COMPLIANCE_AUDIT_COMMITMENT",
+    "EU_COMPLIANCE_EXTENSIONS",
+    "EU_COMPLIANCE_VALUES",
 ]

agent_alignment_protocol-0.2.0/src/aap/compliance.py

@@ -0,0 +1,56 @@
+"""EU AI Act Article 50 compliance presets for AAP.
+
+These presets provide recommended configuration values for deploying
+AAP-instrumented agents in EU jurisdictions subject to AI Act
+transparency obligations. Spread them into your AlignmentCard fields.
+
+Usage:
+    from aap.compliance import (
+        EU_COMPLIANCE_AUDIT_COMMITMENT,
+        EU_COMPLIANCE_EXTENSIONS,
+        EU_COMPLIANCE_VALUES,
+    )
+
+    card = AlignmentCard(
+        ...,
+        audit_commitment=AuditCommitment(**EU_COMPLIANCE_AUDIT_COMMITMENT),
+        values=Values(declared=EU_COMPLIANCE_VALUES, ...),
+        extensions=EU_COMPLIANCE_EXTENSIONS,
+    )
+
+DISCLAIMER: These presets reflect a technical mapping of AAP features to
+Article 50 requirements. They do not constitute legal advice. Consult
+qualified legal counsel for your specific compliance obligations.
+"""
+
+from __future__ import annotations
+
+# Audit commitment values that satisfy Article 50(4) audit trail requirements.
+EU_COMPLIANCE_AUDIT_COMMITMENT: dict = {
+    "retention_days": 90,
+    "queryable": True,
+    "query_endpoint": "https://audit.example.com/traces",
+    "tamper_evidence": "append_only",
+    "trace_format": "ap-trace-v1",
+}
+
+# Extension block for EU AI Act metadata on the Alignment Card.
+EU_COMPLIANCE_EXTENSIONS: dict = {
+    "eu_ai_act": {
+        "article_50_compliant": True,
+        "ai_system_classification": "general_purpose",
+        "disclosure_text": (
+            "This system is powered by an AI agent. Its decisions are logged "
+            "and auditable. You may request a human review of any decision."
+        ),
+        "compliance_version": "2026-08",
+    },
+}
+
+# Recommended declared values for Article 50 transparency obligations.
+EU_COMPLIANCE_VALUES: list[str] = [
+    "transparency",
+    "honesty",
+    "user_control",
+    "principal_benefit",
+]

{agent_alignment_protocol-0.1.7 → agent_alignment_protocol-0.2.0}/src/aap/verification/__init__.py

@@ -36,6 +36,7 @@ See SPEC.md Sections 7, 6.4, and 8 for protocol specification.
 
 from aap.verification.api import (
     check_coherence,
+    check_fleet_coherence,
     detect_drift,
     verify_trace,
 )
@@ -57,14 +58,20 @@ from aap.verification.features import (
     cosine_similarity,
 )
 from aap.verification.models import (
+    AgentCoherenceSummary,
     CoherenceResult,
     DriftAlert,
     DriftAnalysis,
     DriftDirection,
     DriftIndicator,
+    FleetCluster,
+    FleetCoherenceResult,
+    FleetOutlier,
+    PairwiseEntry,
     Severity,
     ValueAlignment,
     ValueConflict,
+    ValueDivergence,
     VerificationMetadata,
     VerificationResult,
     Violation,
@@ -80,6 +87,7 @@ __all__ = [
     # Core functions
     "verify_trace",
     "check_coherence",
+    "check_fleet_coherence",
     "detect_drift",
     # SSM and Divergence (Phase 1 Braid extraction)
     "SSMAnalyzer",
@@ -91,6 +99,13 @@ __all__ = [
     "compute_centroid",
     "cosine_similarity",
     "compute_similarity_with_tfidf",
+    # Fleet Coherence (E-05)
+    "FleetCoherenceResult",
+    "PairwiseEntry",
+    "FleetOutlier",
+    "FleetCluster",
+    "ValueDivergence",
+    "AgentCoherenceSummary",
     # Result models
     "VerificationResult",
     "Violation",

{agent_alignment_protocol-0.1.7 → agent_alignment_protocol-0.2.0}/src/aap/verification/api.py

@@ -10,8 +10,10 @@ See SPEC.md Sections 7, 6.4, and 8 for protocol specification.
 
 from __future__ import annotations
 
+import math
 import re
 import time
+from collections import defaultdict
 from datetime import datetime
 from typing import Any
 
@@ -23,14 +25,21 @@ from aap.verification.constants import (
     DEFAULT_SUSTAINED_TURNS_THRESHOLD,
     MIN_COHERENCE_FOR_PROCEED,
     NEAR_BOUNDARY_THRESHOLD,
+    OUTLIER_STD_DEV_THRESHOLD,
 )
 from aap.verification.models import (
+    AgentCoherenceSummary,
     CoherenceResult,
     DriftAlert,
     DriftDirection,
     DriftIndicator,
+    FleetCluster,
+    FleetCoherenceResult,
+    FleetOutlier,
+    PairwiseEntry,
     ValueAlignment,
     ValueConflict,
+    ValueDivergence,
     VerificationMetadata,
     VerificationResult,
     Violation,
@@ -39,6 +48,42 @@ from aap.verification.models import (
 )
 
 
+def action_matches_list(action_name: str, action_list: list[str]) -> bool:
+    """Check if a (possibly compound) action name matches any entry in a list.
+
+    Supports exact match, prefix match (before ':'), and compound name splitting.
+    Port of the TypeScript actionMatchesList() for SDK parity.
+
+    Args:
+        action_name: Action name, possibly compound (e.g. "exec, read")
+        action_list: List of allowed/forbidden action entries,
+                     possibly with colon descriptions (e.g. "exec: execute shell commands")
+
+    Returns:
+        True if the action name matches an entry in the list
+    """
+    components = action_name.split(", ") if ", " in action_name else [action_name]
+
+    return all(
+        _action_component_matches(component.strip(), action_list)
+        for component in components
+        if component.strip()
+    )
+
+
+def _action_component_matches(component: str, action_list: list[str]) -> bool:
+    """Check if a single action component matches any entry in the list."""
+    for entry in action_list:
+        if entry == component:
+            return True
+        colon_index = entry.find(":")
+        if colon_index > 0:
+            prefix = entry[:colon_index].strip()
+            if prefix == component:
+                return True
+    return False
+
+
 def verify_trace(
     trace: dict[str, Any],
     card: dict[str, Any],
@@ -103,7 +148,7 @@ def verify_trace(
 
     if action_category == "bounded":
         bounded_actions = envelope.get("bounded_actions", [])
-        if action_name and action_name not in bounded_actions:
+        if action_name and not action_matches_list(action_name, bounded_actions):
             violations.append(Violation.create(
                 ViolationType.UNBOUNDED_ACTION,
                 f"Action '{action_name}' not in bounded_actions: {bounded_actions}",
@@ -113,7 +158,7 @@ def verify_trace(
     # Check forbidden actions
     checks_performed.append("forbidden")
     forbidden_actions = envelope.get("forbidden_actions", [])
-    if action_name and action_name in forbidden_actions:
+    if action_name and action_matches_list(action_name, forbidden_actions):
         violations.append(Violation.create(
             ViolationType.FORBIDDEN_ACTION,
             f"Action '{action_name}' is in forbidden_actions",
@@ -298,6 +343,227 @@ def check_coherence(
     )
 
 
+def check_fleet_coherence(
+    cards: list[dict[str, Any]],
+    task_values: list[str] | None = None,
+) -> FleetCoherenceResult:
+    """Check fleet-level value coherence across N agents.
+
+    Computes all C(n,2) pairwise coherence scores, then derives:
+    - Fleet score: mean of all pairwise scores
+    - Outlier detection: agents >1 std dev below fleet mean
+    - Cluster analysis: connected components at compatibility threshold
+    - Divergence report: values where agents disagree
+
+    Args:
+        cards: List of dicts with "agent_id" and "card" keys
+        task_values: Optional list of values required for the task
+
+    Returns:
+        FleetCoherenceResult with full analysis
+
+    Raises:
+        ValueError: If fewer than 2 agents provided
+    """
+    if len(cards) < 2:
+        raise ValueError("Fleet coherence requires at least 2 agents")
+
+    agent_ids = [c["agent_id"] for c in cards]
+
+    # Step 1: Compute all pairwise coherence scores
+    pairwise_matrix: list[PairwiseEntry] = []
+    for i in range(len(cards)):
+        for j in range(i + 1, len(cards)):
+            result = check_coherence(cards[i]["card"], cards[j]["card"], task_values)
+            pairwise_matrix.append(PairwiseEntry(
+                agent_a=cards[i]["agent_id"],
+                agent_b=cards[j]["agent_id"],
+                result=result,
+            ))
+
+    # Step 2: Fleet score (mean of all pairwise scores) + min/max
+    all_scores = [p.result.score for p in pairwise_matrix]
+    fleet_score = sum(all_scores) / len(all_scores)
+    min_pair_score = min(all_scores)
+    max_pair_score = max(all_scores)
+
+    # Step 3: Per-agent summaries
+    agent_scores: dict[str, list[float]] = defaultdict(list)
+    agent_compatible: dict[str, int] = defaultdict(int)
+    agent_conflict: dict[str, int] = defaultdict(int)
+
+    for pair in pairwise_matrix:
+        agent_scores[pair.agent_a].append(pair.result.score)
+        agent_scores[pair.agent_b].append(pair.result.score)
+        if pair.result.compatible:
+            agent_compatible[pair.agent_a] += 1
+            agent_compatible[pair.agent_b] += 1
+        if len(pair.result.value_alignment.conflicts) > 0:
+            agent_conflict[pair.agent_a] += 1
+            agent_conflict[pair.agent_b] += 1
+
+    agent_means: dict[str, float] = {}
+    for aid in agent_ids:
+        scores = agent_scores[aid]
+        agent_means[aid] = sum(scores) / len(scores) if scores else 0.0
+
+    # Step 4: Outlier detection
+    mean_values = list(agent_means.values())
+    fleet_mean_of_means = sum(mean_values) / len(mean_values)
+    variance = sum((v - fleet_mean_of_means) ** 2 for v in mean_values) / len(mean_values)
+    stddev = math.sqrt(variance)
+
+    outliers: list[FleetOutlier] = []
+    if stddev > 0 and len(agent_ids) >= 3:
+        for aid in agent_ids:
+            agent_mean = agent_means[aid]
+            deviation = (fleet_mean_of_means - agent_mean) / stddev
+            if deviation >= OUTLIER_STD_DEV_THRESHOLD:
+                primary_conflicts: set[str] = set()
+                for pair in pairwise_matrix:
+                    if pair.agent_a == aid or pair.agent_b == aid:
+                        for conflict in pair.result.value_alignment.conflicts:
+                            if conflict.initiator_value != "(conflicts_with)":
+                                primary_conflicts.add(conflict.initiator_value)
+                            if conflict.responder_value != "(conflicts_with)":
+                                primary_conflicts.add(conflict.responder_value)
+                outliers.append(FleetOutlier(
+                    agent_id=aid,
+                    agent_mean_score=round(agent_mean, 4),
+                    fleet_mean_score=round(fleet_mean_of_means, 4),
+                    deviation=round(deviation, 4),
+                    primary_conflicts=sorted(primary_conflicts),
+                ))
+
+    # Step 5: Cluster analysis (connected components at compatibility threshold)
+    adjacency: dict[str, set[str]] = {aid: set() for aid in agent_ids}
+    for pair in pairwise_matrix:
+        if pair.result.compatible:
+            adjacency[pair.agent_a].add(pair.agent_b)
+            adjacency[pair.agent_b].add(pair.agent_a)
+
+    visited: set[str] = set()
+    clusters: list[FleetCluster] = []
+    cluster_id = 0
+
+    for aid in agent_ids:
+        if aid in visited:
+            continue
+        component: list[str] = []
+        queue = [aid]
+        visited.add(aid)
+        while queue:
+            current = queue.pop(0)
+            component.append(current)
+            for neighbor in adjacency[current]:
+                if neighbor not in visited:
+                    visited.add(neighbor)
+                    queue.append(neighbor)
+
+        # Compute internal coherence
+        internal_sum = 0.0
+        internal_count = 0
+        for ci in range(len(component)):
+            for cj in range(ci + 1, len(component)):
+                for pair in pairwise_matrix:
+                    if ((pair.agent_a == component[ci] and pair.agent_b == component[cj]) or
+                            (pair.agent_a == component[cj] and pair.agent_b == component[ci])):
+                        internal_sum += pair.result.score
+                        internal_count += 1
+                        break
+        internal_coherence = internal_sum / internal_count if internal_count > 0 else 1.0
+
+        # Find shared values
+        cluster_cards_list = [c for c in cards if c["agent_id"] in component]
+        shared: set[str] | None = None
+        for entry in cluster_cards_list:
+            declared = set(entry["card"].get("values", {}).get("declared", []))
+            shared = declared if shared is None else shared & declared
+        shared_values = sorted(shared or set())
+
+        # Find distinguishing values
+        other_values: set[str] = set()
+        for entry in cards:
+            if entry["agent_id"] not in component:
+                for v in entry["card"].get("values", {}).get("declared", []):
+                    other_values.add(v)
+        distinguishing = [v for v in shared_values if v not in other_values]
+
+        clusters.append(FleetCluster(
+            cluster_id=cluster_id,
+            agent_ids=component,
+            internal_coherence=round(internal_coherence, 4),
+            shared_values=shared_values,
+            distinguishing_values=distinguishing,
+        ))
+        cluster_id += 1
+
+    # Step 6: Divergence report
+    all_values: set[str] = set()
+    agent_value_map: dict[str, set[str]] = {}
+    agent_conflict_map: dict[str, set[str]] = {}
+
+    for entry in cards:
+        declared = set(entry["card"].get("values", {}).get("declared", []))
+        conflicts_with = set(entry["card"].get("values", {}).get("conflicts_with", []))
+        agent_value_map[entry["agent_id"]] = declared
+        agent_conflict_map[entry["agent_id"]] = conflicts_with
+        all_values |= declared
+
+    divergence_report: list[ValueDivergence] = []
+    for value in all_values:
+        declaring = [aid for aid in agent_ids if value in agent_value_map[aid]]
+        missing = [aid for aid in agent_ids if value not in agent_value_map[aid]]
+        conflicting = [aid for aid in agent_ids if value in agent_conflict_map[aid]]
+
+        if not missing and not conflicting:
+            continue
+
+        impact = round((len(missing) + len(conflicting)) / len(agent_ids), 4)
+        divergence_report.append(ValueDivergence(
+            value=value,
+            agents_declaring=declaring,
+            agents_missing=missing,
+            agents_conflicting=conflicting,
+            impact_on_fleet_score=impact,
+        ))
+
+    divergence_report.sort(key=lambda d: d.impact_on_fleet_score, reverse=True)
+
+    # Build agent cluster map
+    agent_cluster_map: dict[str, int] = {}
+    for cluster in clusters:
+        for aid in cluster.agent_ids:
+            agent_cluster_map[aid] = cluster.cluster_id
+
+    outlier_ids = {o.agent_id for o in outliers}
+
+    agent_summaries = [
+        AgentCoherenceSummary(
+            agent_id=aid,
+            mean_score=round(agent_means[aid], 4),
+            compatible_count=agent_compatible[aid],
+            conflict_count=agent_conflict[aid],
+            cluster_id=agent_cluster_map.get(aid, 0),
+            is_outlier=aid in outlier_ids,
+        )
+        for aid in agent_ids
+    ]
+
+    return FleetCoherenceResult(
+        fleet_score=round(fleet_score, 4),
+        min_pair_score=round(min_pair_score, 4),
+        max_pair_score=round(max_pair_score, 4),
+        agent_count=len(cards),
+        pair_count=len(pairwise_matrix),
+        pairwise_matrix=pairwise_matrix,
+        outliers=outliers,
+        clusters=clusters,
+        divergence_report=divergence_report,
+        agent_summaries=agent_summaries,
+    )
+
+
 def detect_drift(
     card: dict[str, Any],
     traces: list[dict[str, Any]],

{agent_alignment_protocol-0.1.7 → agent_alignment_protocol-0.2.0}/src/aap/verification/constants.py

@@ -38,6 +38,15 @@ MIN_COHERENCE_FOR_PROCEED: float = 0.70
 CONFLICT_PENALTY_MULTIPLIER: float = 0.50
 
 
+# Fleet Coherence
+# ----------------
+# Standard deviations below fleet mean to flag an agent as outlier
+OUTLIER_STD_DEV_THRESHOLD: float = 1.0
+
+# Minimum pairwise score to consider agents compatible for cluster analysis
+CLUSTER_COMPATIBILITY_THRESHOLD: float = 0.70
+
+
 # Feature Extraction
 # ------------------
 # Minimum word length for content features (filters noise)

{agent_alignment_protocol-0.1.7 → agent_alignment_protocol-0.2.0}/src/aap/verification/models.py

@@ -258,3 +258,108 @@ class ValueConflict(BaseModel):
 
 # Rebuild models with forward references
 CoherenceResult.model_rebuild()
+
+
+# --- Fleet Coherence Types (E-05: N-Way Value Coherence) ---
+
+
+class PairwiseEntry(BaseModel):
+    """A single pairwise coherence entry in the fleet matrix."""
+
+    agent_a: str = Field(..., description="First agent ID")
+    agent_b: str = Field(..., description="Second agent ID")
+    result: CoherenceResult = Field(..., description="Pairwise coherence result")
+
+
+class FleetOutlier(BaseModel):
+    """An agent flagged as an outlier in fleet coherence."""
+
+    agent_id: str = Field(..., description="Agent ID")
+    agent_mean_score: float = Field(..., description="Agent's mean pairwise score")
+    fleet_mean_score: float = Field(..., description="Fleet-wide mean score")
+    deviation: float = Field(..., description="Standard deviations below fleet mean")
+    primary_conflicts: list[str] = Field(
+        default_factory=list, description="Values causing primary conflicts"
+    )
+
+
+class FleetCluster(BaseModel):
+    """A cluster of compatible agents."""
+
+    cluster_id: int = Field(..., description="Cluster identifier")
+    agent_ids: list[str] = Field(..., description="Agent IDs in this cluster")
+    internal_coherence: float = Field(
+        ..., description="Mean coherence score within the cluster"
+    )
+    shared_values: list[str] = Field(
+        default_factory=list,
+        description="Values shared by all agents in the cluster",
+    )
+    distinguishing_values: list[str] = Field(
+        default_factory=list,
+        description="Values that distinguish this cluster from others",
+    )
+
+
+class ValueDivergence(BaseModel):
+    """A value dimension where agents diverge."""
+
+    value: str = Field(..., description="The value in question")
+    agents_declaring: list[str] = Field(
+        default_factory=list, description="Agent IDs that declare this value"
+    )
+    agents_missing: list[str] = Field(
+        default_factory=list, description="Agent IDs missing this value"
+    )
+    agents_conflicting: list[str] = Field(
+        default_factory=list,
+        description="Agent IDs whose conflicts_with includes this value",
+    )
+    impact_on_fleet_score: float = Field(
+        ..., description="Estimated impact on fleet score if resolved"
+    )
+
+
+class AgentCoherenceSummary(BaseModel):
+    """Summary of one agent's position in the fleet."""
+
+    agent_id: str = Field(..., description="Agent ID")
+    mean_score: float = Field(
+        ..., description="Mean pairwise score with all other agents"
+    )
+    compatible_count: int = Field(..., description="Number of compatible pairs")
+    conflict_count: int = Field(..., description="Number of conflicting pairs")
+    cluster_id: int = Field(..., description="Cluster this agent belongs to")
+    is_outlier: bool = Field(
+        ..., description="Whether this agent is flagged as an outlier"
+    )
+
+
+class FleetCoherenceResult(BaseModel):
+    """Result of N-way fleet coherence analysis."""
+
+    fleet_score: float = Field(
+        ..., description="Mean of all pairwise coherence scores"
+    )
+    min_pair_score: float = Field(
+        ..., description="Minimum pairwise score (weakest link)"
+    )
+    max_pair_score: float = Field(..., description="Maximum pairwise score")
+    agent_count: int = Field(..., description="Number of agents analyzed")
+    pair_count: int = Field(..., description="Number of pairwise comparisons")
+    pairwise_matrix: list[PairwiseEntry] = Field(
+        ..., description="All pairwise coherence results"
+    )
+    outliers: list[FleetOutlier] = Field(
+        default_factory=list, description="Agents flagged as outliers"
+    )
+    clusters: list[FleetCluster] = Field(
+        default_factory=list, description="Clusters of compatible agents"
+    )
+    divergence_report: list[ValueDivergence] = Field(
+        default_factory=list,
+        description="Value dimensions where agents diverge",
+    )
+    agent_summaries: list[AgentCoherenceSummary] = Field(
+        default_factory=list, description="Per-agent coherence summaries"
+    )