arkaos 2.17.1 → 2.17.4

package/core/agents/behavior_enforcer.py

@@ -0,0 +1,255 @@
+"""Behavior enforcement middleware.
+
+Validates agent outputs against their stated behavioral DNA profile.
+Detects "behavior drift" — when an agent acts outside their profile.
+
+This is advisory only (WARN severity) — it doesn't block operations
+but surfaces discrepancies for human review.
+"""
+
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from core.agents.dna_registry import DNARegistry, get_registry
+from core.agents.schema import Agent, DISCType
+
+
+@dataclass
+class BehaviorDrift:
+    """A detected deviation from an agent's DNA profile."""
+
+    agent_id: str
+    drift_type: str  # "tone", "vocabulary", "approach", "communication_style"
+    expected: str
+    detected: str
+    severity: str = "WARN"  # WARN or INFO
+    suggestion: str = ""
+
+
+class BehaviorEnforcer:
+    """Middleware to enforce behavioral DNA profiles on agent outputs."""
+
+    def __init__(self, registry: DNARegistry | None = None):
+        self.registry = registry or get_registry()
+
+    def check_output(
+        self,
+        agent_id: str,
+        output: str,
+        context: str = "",
+    ) -> list[BehaviorDrift]:
+        """Check if an output deviates from the agent's DNA profile.
+
+        Args:
+            agent_id: ID of the agent that produced the output
+            output: The text output to check
+            context: Optional context about the interaction type
+
+        Returns:
+            List of detected behavior drifts
+        """
+        agent = self.registry.get(agent_id)
+        if not agent:
+            return []
+
+        drifts: list[BehaviorDrift] = []
+
+        drifts.extend(self._check_tone(agent, output))
+        drifts.extend(self._check_vocabulary(agent, output))
+        drifts.extend(self._check_communication_style(agent, output))
+        drifts.extend(self._check_avoid_list(agent, output))
+
+        return drifts
+
+    def _check_tone(self, agent: Agent, output: str) -> list[BehaviorDrift]:
+        """Check if output tone matches agent's stated DISC style."""
+        drifts = []
+        disc = agent.behavioral_dna.disc
+        output_lower = output.lower()
+
+        if disc.primary == DISCType.D:
+            if not any(
+                word in output_lower for word in ["need", "must", "require", "demand", "critical"]
+            ):
+                if len(output) > 100 and "?" not in output:
+                    drifts.append(
+                        BehaviorDrift(
+                            agent_id=agent.id,
+                            drift_type="tone",
+                            expected="Direct, decisive, bottom-line first",
+                            detected="Lacks direct command language",
+                            suggestion="Lead with conclusions. Use 'must', 'need', 'critical'.",
+                        )
+                    )
+
+        elif disc.primary == DISCType.I:
+            if not any(
+                word in output_lower
+                for word in [
+                    "great",
+                    "amazing",
+                    "exciting",
+                    "fantastic",
+                    "!" * 3 if "!!" in output else "",
+                ]
+            ):
+                if len(output) > 200 and "!" not in output and "great" not in output_lower:
+                    drifts.append(
+                        BehaviorDrift(
+                            agent_id=agent.id,
+                            drift_type="tone",
+                            expected="Enthusiastic, engaging, positive",
+                            detected="Lacks enthusiasm markers",
+                            suggestion="Show energy. Use 'great', 'amazing', 'exciting'.",
+                        )
+                    )
+
+        elif disc.primary == DISCType.S:
+            if any(word in output_lower for word in ["must", "immediately", "urgent", "asap"]):
+                if output.count("must") > 2 or "immediately" in output:
+                    drifts.append(
+                        BehaviorDrift(
+                            agent_id=agent.id,
+                            drift_type="tone",
+                            expected="Supportive, steady, patient",
+                            detected="Overly urgent or demanding",
+                            suggestion="Soften language. Avoid 'must', 'immediately', 'asap'.",
+                        )
+                    )
+
+        elif disc.primary == DISCType.C:
+            if not any(
+                pattern in output
+                for pattern in ["1.", "2.", "3.", "• ", "- ", "data:", "analysis:"]
+            ):
+                if len(output) > 150 and not re.search(r"\d+", output):
+                    drifts.append(
+                        BehaviorDrift(
+                            agent_id=agent.id,
+                            drift_type="tone",
+                            expected="Precise, analytical, structured",
+                            detected="Lacks structured format",
+                            suggestion="Use numbered lists, bullet points, and data references.",
+                        )
+                    )
+
+        return drifts
+
+    def _check_vocabulary(self, agent: Agent, output: str) -> list[BehaviorDrift]:
+        """Check if output uses appropriate vocabulary level."""
+        drifts = []
+        vocab_level = agent.communication.vocabulary_level
+        output_lower = output.lower()
+
+        if vocab_level == "specialist":
+            tech_terms = ["architecture", "infrastructure", "optimization", "latency", "throughput"]
+            if not any(term in output_lower for term in tech_terms):
+                if len(output) > 150:
+                    drifts.append(
+                        BehaviorDrift(
+                            agent_id=agent.id,
+                            drift_type="vocabulary",
+                            expected="Specialist-level technical vocabulary",
+                            detected="Generic language detected",
+                            suggestion="Use precise technical terms relevant to the domain.",
+                        )
+                    )
+
+        return drifts
+
+    def _check_communication_style(self, agent: Agent, output: str) -> list[BehaviorDrift]:
+        """Check if output matches preferred communication format."""
+        drifts = []
+        preferred = agent.communication.preferred_format
+        output_lower = output.lower()
+
+        if "structured" in preferred or "diagrams" in preferred:
+            if len(output) > 300 and not any(
+                marker in output for marker in ["1.", "2.", "3.", "##", "###", "|"]
+            ):
+                drifts.append(
+                    BehaviorDrift(
+                        agent_id=agent.id,
+                        drift_type="communication_style",
+                        expected=f"Structured with {preferred}",
+                        detected="Free-form text without structure",
+                        suggestion="Add headers, numbered steps, or tabular format.",
+                    )
+                )
+
+        if "code examples" in preferred:
+            if "```" not in output and len(output) > 200:
+                drifts.append(
+                    BehaviorDrift(
+                        agent_id=agent.id,
+                        drift_type="communication_style",
+                        expected="Includes code examples",
+                        detected="No code blocks found",
+                        suggestion="Add code examples to illustrate points.",
+                    )
+                )
+
+        return drifts
+
+    def _check_avoid_list(self, agent: Agent, output: str) -> list[BehaviorDrift]:
+        """Check if output contains items from agent's avoid list."""
+        drifts = []
+        avoid_list = agent.communication.avoid
+        output_lower = output.lower()
+
+        for item in avoid_list:
+            if item.lower() in output_lower:
+                drifts.append(
+                    BehaviorDrift(
+                        agent_id=agent.id,
+                        drift_type="tone",
+                        expected=f"Avoid: {item}",
+                        detected=f"Contains '{item}'",
+                        severity="INFO",
+                        suggestion=f"Avoid using '{item}' when communicating.",
+                    )
+                )
+
+        return drifts
+
+    def enforce_output(
+        self,
+        agent_id: str,
+        output: str,
+        context: str = "",
+    ) -> tuple[str, list[BehaviorDrift]]:
+        """Check output and return (possibly modified) output with drifts.
+
+        This is advisory — it doesn't modify output but returns drifts
+        for logging or review purposes.
+
+        Args:
+            agent_id: ID of the agent
+            output: The output to check
+            context: Optional interaction context
+
+        Returns:
+            Tuple of (output unchanged, list of drifts)
+        """
+        drifts = self.check_output(agent_id, output, context)
+        return output, drifts
+
+
+def check_agent_behavior(
+    agent_id: str,
+    output: str,
+    context: str = "",
+) -> list[BehaviorDrift]:
+    """Convenience function to check an agent's output.
+
+    Args:
+        agent_id: ID of the agent
+        output: Output text to check
+        context: Optional context
+
+    Returns:
+        List of BehaviorDrift objects
+    """
+    enforcer = BehaviorEnforcer()
+    return enforcer.check_output(agent_id, output, context)

package/core/agents/dna_registry.py

@@ -0,0 +1,235 @@
+"""Agent DNA Registry — query and filter agents by behavioral DNA traits.
+
+Provides:
+- Load all agents from departments/*/agents/*.yaml
+- Query agents by DISC type, Enneagram, Big Five traits, MBTI
+- Find compatible agents for collaboration
+- Validate DNA profile completeness
+"""
+
+from pathlib import Path
+from typing import Iterator
+
+from core.agents.loader import load_all_agents
+from core.agents.schema import (
+    Agent,
+    BehavioralDNA,
+    DISCType,
+    EnneagramType,
+    BigFiveProfile,
+    MBTIType,
+)
+
+
+class DNARegistry:
+    """Registry for querying agents by behavioral DNA traits."""
+
+    def __init__(self, base_dir: str | Path | None = None):
+        """Initialize registry.
+
+        Args:
+            base_dir: Root of departments tree. Defaults to repo root.
+        """
+        if base_dir is None:
+            base_dir = Path(__file__).parent.parent.parent / "departments"
+        self.base_dir = Path(base_dir)
+        self._agents: list[Agent] = []
+        self._by_id: dict[str, Agent] = {}
+        self._load_agents()
+
+    def _load_agents(self) -> None:
+        """Load all agents from YAML files."""
+        self._agents = load_all_agents(self.base_dir)
+        self._by_id = {a.id: a for a in self._agents}
+
+    def reload(self) -> None:
+        """Reload all agents from disk."""
+        self._load_agents()
+
+    def get(self, agent_id: str) -> Agent | None:
+        """Get agent by ID."""
+        return self._by_id.get(agent_id)
+
+    def all(self) -> list[Agent]:
+        """Get all loaded agents."""
+        return self._agents.copy()
+
+    def by_disc(self, primary: DISCType) -> list[Agent]:
+        """Find agents by DISC primary type."""
+        return [a for a in self._agents if a.behavioral_dna.disc.primary == primary]
+
+    def by_enneagram(self, type_: EnneagramType) -> list[Agent]:
+        """Find agents by Enneagram type."""
+        return [a for a in self._agents if a.behavioral_dna.enneagram.type == type_]
+
+    def by_mbti(self, type_: MBTIType) -> list[Agent]:
+        """Find agents by MBTI type."""
+        return [a for a in self._agents if a.behavioral_dna.mbti.type == type_]
+
+    def by_department(self, department: str) -> list[Agent]:
+        """Find agents by department."""
+        return [a for a in self._agents if a.department == department]
+
+    def by_tier(self, tier: int) -> list[Agent]:
+        """Find agents by tier (0-3)."""
+        return [a for a in self._agents if a.tier == tier]
+
+    def by_big_five(
+        self,
+        openness_min: int = 0,
+        conscientiousness_min: int = 0,
+        extraversion_min: int = 0,
+        agreeableness_min: int = 0,
+        neuroticism_max: int = 100,
+    ) -> list[Agent]:
+        """Find agents matching Big Five thresholds."""
+        results = []
+        for a in self._agents:
+            bf = a.behavioral_dna.big_five
+            if (
+                bf.openness >= openness_min
+                and bf.conscientiousness >= conscientiousness_min
+                and bf.extraversion >= extraversion_min
+                and bf.agreeableness >= agreeableness_min
+                and bf.neuroticism <= neuroticism_max
+            ):
+                results.append(a)
+        return results
+
+    def compatible_with(self, agent_id: str) -> list[Agent]:
+        """Find agents compatible for collaboration.
+
+        Compatibility is based on complementary DISC profiles
+        and similar communication styles.
+        """
+        agent = self.get(agent_id)
+        if not agent:
+            return []
+
+        disc = agent.behavioral_dna.disc
+        disc_map = {
+            DISCType.D: {DISCType.I, DISCType.S},  # D works with I and S
+            DISCType.I: {DISCType.D, DISCType.S},  # I works with D and S
+            DISCType.S: {DISCType.D, DISCType.I, DISCType.C},  # S works with most
+            DISCType.C: {DISCType.S, DISCType.C},  # C works with S and C
+        }
+        compatible_types = disc_map.get(disc.primary, set())
+
+        return [
+            a
+            for a in self._agents
+            if a.id != agent_id and a.behavioral_dna.disc.primary in compatible_types
+        ]
+
+    def contrasting_disc(self, agent_id: str) -> list[Agent]:
+        """Find agents with contrasting DISC profiles.
+
+        Useful for getting different perspectives.
+        """
+        agent = self.get(agent_id)
+        if not agent:
+            return []
+
+        primary = agent.behavioral_dna.disc.primary
+        opposites = {
+            DISCType.D: {DISCType.S, DISCType.C},
+            DISCType.I: {DISCType.C},
+            DISCType.S: {DISCType.D},
+            DISCType.C: {DISCType.D, DISCType.I},
+        }
+        opposite_types = opposites.get(primary, set())
+
+        return [
+            a
+            for a in self._agents
+            if a.id != agent_id and a.behavioral_dna.disc.primary in opposite_types
+        ]
+
+    def validate_dna_completeness(self) -> dict[str, list[str]]:
+        """Validate that all agents have complete DNA profiles.
+
+        Returns:
+            Dict mapping agent_id to list of missing fields
+        """
+        missing: dict[str, list[str]] = {}
+        for agent in self._agents:
+            issues = []
+            dna = agent.behavioral_dna
+
+            if not dna.disc.primary:
+                issues.append("disc.primary")
+            if not dna.enneagram.type:
+                issues.append("enneagram.type")
+            if not dna.big_five.openness:
+                issues.append("big_five.openness")
+            if not dna.mbti.type:
+                issues.append("mbti.type")
+
+            if issues:
+                missing[agent.id] = issues
+
+        return missing
+
+    def get_communication_style(self, agent_id: str) -> str | None:
+        """Get the communication style hint for an agent."""
+        agent = self.get(agent_id)
+        if not agent:
+            return None
+        return agent.communication.tone
+
+    def get_tone_for_recipient(self, sender_id: str, recipient_id: str) -> str:
+        """Get adapted tone when sender communicates with recipient.
+
+        Args:
+            sender_id: The sender's agent ID
+            recipient_id: The recipient's agent ID
+
+        Returns:
+            Communication tone adapted for the recipient
+        """
+        sender = self.get(sender_id)
+        recipient = self.get(recipient_id)
+        if not sender or not recipient:
+            return "professional"
+
+        sender_disc = sender.behavioral_dna.disc.primary
+        recipient_disc = recipient.behavioral_dna.disc.primary
+
+        tone_map = {
+            (DISCType.D, DISCType.D): "direct and decisive",
+            (DISCType.D, DISCType.I): "direct but enthusiastic",
+            (DISCType.D, DISCType.S): "direct and supportive",
+            (DISCType.D, DISCType.C): "direct and precise",
+            (DISCType.I, DISCType.D): "enthusiastic but direct",
+            (DISCType.I, DISCType.I): "enthusiastic and collaborative",
+            (DISCType.I, DISCType.S): "enthusiastic and warm",
+            (DISCType.I, DISCType.C): "enthusiastic but detailed",
+            (DISCType.S, DISCType.D): "supportive but direct",
+            (DISCType.S, DISCType.I): "warm and collaborative",
+            (DISCType.S, DISCType.S): "warm and steady",
+            (DISCType.S, DISCType.C): "supportive and precise",
+            (DISCType.C, DISCType.D): "precise and direct",
+            (DISCType.C, DISCType.I): "precise but friendly",
+            (DISCType.C, DISCType.S): "precise and supportive",
+            (DISCType.C, DISCType.C): "precise and thorough",
+        }
+
+        return tone_map.get((sender_disc, recipient_disc), "professional")
+
+
+_REGISTRY: DNARegistry | None = None
+
+
+def get_registry() -> DNARegistry:
+    """Get the global DNA registry (singleton)."""
+    global _REGISTRY
+    if _REGISTRY is None:
+        _REGISTRY = DNARegistry()
+    return _REGISTRY
+
+
+def reload_registry() -> DNARegistry:
+    """Reload and return the global registry."""
+    global _REGISTRY
+    _REGISTRY = DNARegistry()
+    return _REGISTRY

package/core/forge/__init__.py

@@ -55,6 +55,26 @@ from core.forge.handoff import (
     check_repo_drift,
 )
 
+from core.forge.orchestrator import (
+    ForgeOrchestrator,
+    ForgeDecision,
+    ForgeStep,
+    ForgeStatusOutput,
+    ForgeHistoryEntry,
+    ForgeCompareOutput,
+    CONSTITUTION_PHASES,
+)
+
+from core.forge.runtime_dispatcher import (
+    ForgeTaskDispatcher,
+    ClaudeCodeForgeDispatcher,
+    ExplorerDispatchRequest,
+    CriticDispatchRequest,
+    DispatchResult,
+    _tier_to_model,
+    create_dispatcher,
+)
+
 __all__ = [
     # schema
     "ForgeTier",
@@ -101,4 +121,20 @@ __all__ = [
     "select_execution_path",
     "generate_workflow_yaml",
     "check_repo_drift",
+    # orchestrator
+    "ForgeOrchestrator",
+    "ForgeDecision",
+    "ForgeStep",
+    "ForgeStatusOutput",
+    "ForgeHistoryEntry",
+    "ForgeCompareOutput",
+    "CONSTITUTION_PHASES",
+    # runtime dispatcher
+    "ForgeTaskDispatcher",
+    "ClaudeCodeForgeDispatcher",
+    "ExplorerDispatchRequest",
+    "CriticDispatchRequest",
+    "DispatchResult",
+    "_tier_to_model",
+    "create_dispatcher",
 ]