@mamdouh-aboammar/agentic-workflow 1.2.0

package/core/integrations/lifecycle_director.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""
+lifecycle_director.py — Sequential Operational Lifecycle Director
+
+Directs the entire autonomous workflow sequentially across 5 core phases:
+1. Continuous Protocol Layer (TOON v4.1 & Caveman Brevity)
+2. Research & Intelligence (Skills Mesh & Fable Discover)
+3. Architecture & Planning (Ponytail YAGNI Ladder Rung 1-3 & Fable Plan)
+4. Production Implementation (Ponytail Rung 4-7 Surgical Diff & Fable Circuit Breaker)
+5. Multi-Pass Verification & Quality Gates (Clean Code Guard, Ponytail Audit & L0-L2)
+6. Handoff & Continuation State (Fable Handoff & TOON Ledger)
+
+Ensures supportive tools are automatically employed in the correct place without
+requiring manual user decision.
+"""
+
+import os
+import json
+import time
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Any
+
+from core.integrations.registry import IntegrationsRegistry, get_default_registry
+
+
+@dataclass
+class PhaseDirectives:
+    phase: str
+    active_integrations: List[str]
+    system_prompt_overlay: str
+    rules: List[str]
+    tools_engaged: List[str]
+
+
+class LifecycleDirector:
+    """Orchestrates supportive tools sequentially throughout the workflow lifecycle."""
+
+    def __init__(self, project_dir: str = ".", registry: Optional[IntegrationsRegistry] = None):
+        self.project_dir = os.path.abspath(project_dir)
+        self.registry = registry or get_default_registry(self.project_dir)
+
+    def get_phase_directives(self, phase: str) -> PhaseDirectives:
+        """Synthesizes unified operational directives for the specified workflow phase."""
+        phase_norm = phase.lower().strip()
+        matched = self.registry.get_for_phase(phase_norm)
+
+        active_names = [m.name for m in matched]
+        tools_engaged = [m.id for m in matched]
+        rules = []
+        directive_sections = []
+
+        # 1. Continuous protocols (TOON & Caveman)
+        toon_item = self.registry.get("toon")
+        if toon_item and "continuous" in toon_item.directives:
+            directive_sections.append(f"### [Continuous Protocol] TOON v4.1 Serialization\n{toon_item.directives['continuous']}")
+            rules.append("Format all structured datasets, task tables, and trace logs in TOON syntax to conserve 30-60% tokens.")
+
+        caveman_item = self.registry.get("caveman")
+        if caveman_item and "continuous" in caveman_item.directives:
+            directive_sections.append(f"### [Communication Protocol] Caveman Terse Mode\n{caveman_item.directives['continuous']}")
+            rules.append("Eliminate pleasantries and conversational filler in logs and thoughts; preserve exact code, paths, and errors.")
+
+        # 2. Phase-specific directives
+        for item in matched:
+            if phase_norm in item.directives:
+                directive_sections.append(f"### [{item.name}] Phase Directives ({phase_norm.capitalize()})\n{item.directives[phase_norm]}")
+                rules.append(f"[{item.name}] {item.directives[phase_norm]}")
+
+        # Phase-specific synthesized overview
+        if phase_norm == "planning":
+            overview = (
+                "## 🧭 Sequential Lifecycle Directive: Phase 2 — Architecture & Planning\n"
+                "Before approving or implementing any architectural design, you MUST enforce the Ponytail YAGNI ladder:\n"
+                "1. Does this speculative requirement need to exist at all? If not, skip it.\n"
+                "2. Is a helper or pattern already present in this codebase? Reuse it.\n"
+                "3. Does the standard library or runtime platform cover it? Use it.\n"
+                "4. Structure deliverables as verifiable Fable contracts with explicit success criteria.\n"
+                "5. Compile and validate OmniSkill SkillSpec contracts and dynamic DAG execution paths."
+            )
+        elif phase_norm == "implementation":
+            overview = (
+                "## 🔨 Sequential Lifecycle Directive: Phase 3 — Production Implementation\n"
+                "Enforce surgical code changes:\n"
+                "1. Shortest working diff wins. Minimum code needed to fulfill requirements.\n"
+                "2. Fix root causes at callers/callees, not symptoms.\n"
+                "3. Fable Circuit Breaker is active: if failure streak >= 2, halt speculative modifications.\n"
+                "4. Follow OmniSkill progressive disclosure: frontmatter <=1024 chars, core SKILL.md, references/, scripts/."
+            )
+        elif phase_norm == "verification":
+            overview = (
+                "## 🛡️ Sequential Lifecycle Directive: Phase 4 — Verification & Quality Gates\n"
+                "1. Run Clean Code Guard (SOLID, 24 Imperatives).\n"
+                "2. Conduct Ponytail Anti-Debt audit: inspect for unnecessary scaffolding, dead config, or bloat.\n"
+                "3. Execute L0 Anti-Skip, L1 Verification, L1.5 pACS (min score >= 70), and L2 Review.\n"
+                "4. Enforce OmniSkill 4-Layer Validation (Artifact, Discovery, Behavior, Portability)."
+            )
+        elif phase_norm == "handoff":
+            overview = (
+                "## 🏁 Sequential Lifecycle Directive: Phase 5 — Handoff & Continuation\n"
+                "1. Compact session learnings into durable continuation state (.fable/state.json and .fable/PROGRESS.md).\n"
+                "2. Archive telemetry and audit logs using high-density TOON format."
+            )
+        else:
+            overview = f"## ⚡ Sequential Lifecycle Directive: {phase_norm.capitalize()} Phase"
+
+        system_prompt = f"{overview}\n\n" + "\n\n".join(directive_sections)
+
+        return PhaseDirectives(
+            phase=phase_norm,
+            active_integrations=active_names,
+            system_prompt_overlay=system_prompt,
+            rules=rules,
+            tools_engaged=tools_engaged
+        )
+
+    def execute_pre_phase_guards(self, phase: str, context: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Runs automated pre-phase safety gates and policy evaluations."""
+        ctx = context or {}
+        phase_norm = phase.lower().strip()
+        result = {
+            "phase": phase_norm,
+            "allowed": True,
+            "warnings": [],
+            "actions_taken": []
+        }
+
+        # Check circuit breaker if in implementation
+        if phase_norm == "implementation":
+            failure_streak = ctx.get("failure_streak", 0)
+            if failure_streak >= 2:
+                result["allowed"] = False
+                result["warnings"].append(
+                    f"Fable Circuit Breaker TRIPPED: Consecutive failures ({failure_streak}) >= 2. "
+                    "Halting speculative execution to prevent thrashing."
+                )
+                result["actions_taken"].append("trip_circuit_breaker")
+
+        # Check planning simplicity gate
+        if phase_norm == "planning":
+            result["actions_taken"].append("enforce_ponytail_yagni_gate")
+
+        return result
+
+    def execute_post_phase_actions(self, phase: str, context: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Executes automated post-phase validations and handoffs."""
+        ctx = context or {}
+        phase_norm = phase.lower().strip()
+        result = {
+            "phase": phase_norm,
+            "success": True,
+            "artifacts_generated": []
+        }
+
+        # If handoff phase, ensure .fable continuation state
+        if phase_norm == "handoff":
+            fable_dir = os.path.join(self.project_dir, ".fable")
+            os.makedirs(fable_dir, exist_ok=True)
+            state_file = os.path.join(fable_dir, "state.json")
+            progress_file = os.path.join(fable_dir, "PROGRESS.md")
+
+            state_payload = {
+                "trace_id": ctx.get("trace_id", f"trace_{int(time.time())}"),
+                "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+                "status": "COMPLETED",
+                "next_action": ctx.get("next_action", "All workflow stages verified cleanly.")
+            }
+            with open(state_file, "w", encoding="utf-8") as f:
+                json.dump(state_payload, f, indent=2)
+
+            with open(progress_file, "w", encoding="utf-8") as f:
+                f.write(f"# Fable Continuation Progress\n\n- Timestamp: {state_payload['timestamp']}\n- Trace: `{state_payload['trace_id']}`\n- Next Action: {state_payload['next_action']}\n")
+
+            result["artifacts_generated"].extend([state_file, progress_file])
+
+        return result

package/core/integrations/registry.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""
+registry.py — Integrations Registry & Manifest Manager
+
+Maintains declarative metadata for supportive tools, frameworks, and agentic skills
+such as Ponytail, TOON, Fable, and Caveman, supporting native dynamic expansion.
+"""
+
+import os
+import json
+from dataclasses import dataclass, field, asdict
+from typing import Dict, List, Optional, Any
+
+
+@dataclass
+class IntegrationDefinition:
+    id: str
+    name: str
+    repo: str
+    description: str
+    category: str  # simplicity_governor, notation_protocol, lifecycle_harness, terse_comm, etc.
+    lifecycle_phases: List[str] = field(default_factory=list)
+    install: Dict[str, Any] = field(default_factory=dict)
+    detection: Dict[str, Any] = field(default_factory=dict)
+    directives: Dict[str, str] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "IntegrationDefinition":
+        return cls(
+            id=data["id"],
+            name=data.get("name", data["id"]),
+            repo=data.get("repo", ""),
+            description=data.get("description", ""),
+            category=data.get("category", "general"),
+            lifecycle_phases=data.get("lifecycle_phases", []),
+            install=data.get("install", {}),
+            detection=data.get("detection", {}),
+            directives=data.get("directives", {})
+        )
+
+
+class IntegrationsRegistry:
+    """Manages the full catalog of supportive integrations."""
+
+    def __init__(self, manifest_path: Optional[str] = None):
+        self.manifest_path = manifest_path
+        self._integrations: Dict[str, IntegrationDefinition] = {}
+        if manifest_path and os.path.exists(manifest_path):
+            self.load_from_file(manifest_path)
+
+    def load_from_file(self, path: str) -> None:
+        """Loads integrations manifest from JSON."""
+        self.manifest_path = os.path.abspath(path)
+        with open(self.manifest_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        self._integrations.clear()
+        for item in data.get("integrations", []):
+            defn = IntegrationDefinition.from_dict(item)
+            self._integrations[defn.id] = defn
+
+    def save_to_file(self, path: Optional[str] = None) -> None:
+        """Persists integrations manifest to JSON."""
+        target = path or self.manifest_path
+        if not target:
+            raise ValueError("No target path specified for saving integrations manifest.")
+        data = {
+            "version": "1.0.0",
+            "description": "Declarative registry of supportive tools, frameworks, and agentic skills for AgenticWorkflow",
+            "integrations": [i.to_dict() for i in self._integrations.values()]
+        }
+        with open(target, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+
+    def register(self, definition: IntegrationDefinition) -> None:
+        """Registers or updates an integration definition."""
+        self._integrations[definition.id] = definition
+
+    def get(self, integration_id: str) -> Optional[IntegrationDefinition]:
+        return self._integrations.get(integration_id)
+
+    def list_all(self) -> List[IntegrationDefinition]:
+        return list(self._integrations.values())
+
+    def get_for_phase(self, phase: str) -> List[IntegrationDefinition]:
+        """Returns all integrations bound to a specific workflow phase or continuous."""
+        phase_clean = phase.lower().strip()
+        matched = []
+        for item in self._integrations.values():
+            if "continuous" in item.lifecycle_phases or phase_clean in item.lifecycle_phases:
+                matched.append(item)
+        return matched
+
+
+def get_default_registry(project_dir: str = ".") -> IntegrationsRegistry:
+    """Instantiates registry from project root integrations.json with repo fallback."""
+    manifest_path = os.path.join(os.path.abspath(project_dir), "integrations.json")
+    if not os.path.exists(manifest_path):
+        repo_fallback = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", "integrations.json"))
+        if os.path.exists(repo_fallback):
+            manifest_path = repo_fallback
+    return IntegrationsRegistry(manifest_path=manifest_path)
+

package/core/multi_agent_system.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""
+multi_agent_system.py — Multi-Agent System Architecture & Governance Engine
+
+Implements patterns from /agency-multi-agent-systems-architect:
+1. Hierarchical Orchestrator-Subagent Topology with Task Ledger
+2. Least-Privilege Agent Permissions & Sandboxing
+3. Circuit Breaker Pattern (CLOSED -> OPEN -> HALF_OPEN)
+4. Trace-Based Observability (trace_id, span_id, latency, cost)
+5. Contradiction Detection & Multi-Agent Arbitration
+"""
+
+import os
+import sys
+import json
+import time
+import uuid
+from enum import Enum
+from dataclasses import dataclass, field, asdict
+from typing import Dict, List, Optional, Any
+
+
+class CircuitBreakerState(Enum):
+    CLOSED = "CLOSED"      # Healthy: calls proceed normally
+    OPEN = "OPEN"          # Tripped: failures exceeded threshold (recovers via diagnosis)
+    HALF_OPEN = "HALF_OPEN"  # Testing recovery with single canary request
+
+
+class AgentRole(Enum):
+    ORCHESTRATOR = "orchestrator"
+    RESEARCHER = "researcher"
+    ARCHITECT = "architect"
+    ENGINEER = "engineer"
+    REVIEWER = "reviewer"
+    FACT_CHECKER = "fact_checker"
+    CLEAN_CODE_GUARD = "clean_code_guard"
+    RECOVERY = "fable_recovery"
+
+
+# Least-Privilege Tool Permissions Matrix
+TOOL_PERMISSIONS: Dict[AgentRole, List[str]] = {
+    AgentRole.ORCHESTRATOR: ["read_file", "write_sot", "dispatch_agent", "log_trace"],
+    AgentRole.RESEARCHER: ["read_file", "search_web", "read_url", "extract_data"],
+    AgentRole.ARCHITECT: ["read_file", "propose_plan", "diagram_topology"],
+    AgentRole.ENGINEER: ["read_file", "write_file", "run_tests", "execute_code"],
+    AgentRole.REVIEWER: ["read_file", "rate_pacs", "lint_code"],  # Strictly read-only
+    AgentRole.FACT_CHECKER: ["read_file", "search_web", "verify_claim"],
+    AgentRole.CLEAN_CODE_GUARD: ["read_file", "ast_check", "report_violations"],
+    AgentRole.RECOVERY: ["read_file", "diagnose_context", "rollback_checkpoint", "repair_state"]
+}
+
+
+@dataclass
+class AgentSpan:
+    trace_id: str
+    span_id: str
+    agent_id: str
+    role: str
+    step: int
+    started_at: float
+    completed_at: Optional[float] = None
+    latency_ms: Optional[float] = None
+    input_tokens: int = 0
+    output_tokens: int = 0
+    confidence: float = 1.0
+    tools_called: List[str] = field(default_factory=list)
+    status: str = "running"  # success, failure, partial, escalated
+    error_message: Optional[str] = None
+    output_summary: Optional[str] = None
+
+    def finish(self, status: str = "success", error: Optional[str] = None) -> None:
+        self.completed_at = time.time()
+        self.latency_ms = (self.completed_at - self.started_at) * 1000.0
+        self.status = status
+        self.error_message = error
+
+
+class CircuitBreaker:
+    """Fable & Distributed Systems Circuit Breaker for agent actions."""
+
+    def __init__(self, failure_threshold: int = 2, cooldown_seconds: float = 30.0):
+        self.failure_threshold = failure_threshold
+        self.cooldown_seconds = cooldown_seconds
+        self.state = CircuitBreakerState.CLOSED
+        self.failure_streak = 0
+        self.last_trip_time: Optional[float] = None
+
+    def record_success(self) -> None:
+        self.failure_streak = 0
+        if self.state == CircuitBreakerState.HALF_OPEN:
+            self.state = CircuitBreakerState.CLOSED
+
+    def record_failure(self) -> None:
+        self.failure_streak += 1
+        if self.failure_streak >= self.failure_threshold:
+            self.state = CircuitBreakerState.OPEN
+            self.last_trip_time = time.time()
+
+    def can_execute(self) -> bool:
+        if self.state == CircuitBreakerState.CLOSED:
+            return True
+        if self.state == CircuitBreakerState.OPEN:
+            if self.last_trip_time and (time.time() - self.last_trip_time) > self.cooldown_seconds:
+                self.state = CircuitBreakerState.HALF_OPEN
+                return True
+            return False
+        return True  # HALF_OPEN allows single test execution
+
+
+class MultiAgentManager:
+    """Coordinates agent role scoping, trace logging, and fault containment."""
+
+    def __init__(self, trace_dir: str = ".traces"):
+        self.trace_dir = trace_dir
+        self.circuit_breakers: Dict[str, CircuitBreaker] = {}
+        os.makedirs(self.trace_dir, exist_ok=True)
+
+    def get_circuit_breaker(self, agent_role: str) -> CircuitBreaker:
+        if agent_role not in self.circuit_breakers:
+            self.circuit_breakers[agent_role] = CircuitBreaker(failure_threshold=2)
+        return self.circuit_breakers[agent_role]
+
+    def authorize_tool(self, role: AgentRole, tool_name: str) -> bool:
+        """Enforces least-privilege boundary. Returns True if tool is permitted."""
+        allowed = TOOL_PERMISSIONS.get(role, [])
+        return tool_name in allowed
+
+    def start_span(self, trace_id: str, agent_id: str, role: AgentRole, step: int) -> AgentSpan:
+        """Initiates an observable trace span for an agent execution step."""
+        return AgentSpan(
+            trace_id=trace_id,
+            span_id=str(uuid.uuid4())[:8],
+            agent_id=agent_id,
+            role=role.value,
+            step=step,
+            started_at=time.time()
+        )
+
+    def record_span(self, span: AgentSpan) -> None:
+        """Persists the trace span to disk for full observability."""
+        trace_file = os.path.join(self.trace_dir, f"trace_{span.trace_id}.jsonl")
+        record = asdict(span)
+        try:
+            with open(trace_file, "a", encoding="utf-8") as f:
+                f.write(json.dumps(record) + "\n")
+        except OSError as log_err:
+            # Telemetry error handling without silent swallowing
+            sys.stderr.write(f"Trace telemetry notice: {log_err}\n")
+
+    def detect_contradictions(self, outputs: Dict[str, str]) -> List[str]:
+        """Detects conflicting claims or opposing verdicts between peer agents."""
+        contradictions = []
+        verdicts = {}
+        for agent_name, text in outputs.items():
+            if "FAIL" in text:
+                verdicts[agent_name] = "FAIL"
+            elif "PASS" in text:
+                verdicts[agent_name] = "PASS"
+
+        if "FAIL" in verdicts.values() and "PASS" in verdicts.values():
+            contradictions.append(
+                f"Verdict contradiction detected between agents: {verdicts}"
+            )
+        return contradictions