arkaos 2.0.0-alpha.1

package/core/specs/schema.py

@@ -0,0 +1,199 @@
+"""Living Spec schema — specs that evolve with implementation.
+
+A Living Spec tracks:
+- Original specification (what was planned)
+- Implementation status per section
+- Deltas (what changed during implementation and why)
+- Acceptance criteria with pass/fail status
+- Reusable patterns extracted from completed specs
+"""
+
+from datetime import datetime
+from enum import Enum
+from typing import Optional, Any
+from pydantic import BaseModel, Field
+
+
+class SpecStatus(str, Enum):
+    DRAFT = "draft"              # Being written
+    REVIEW = "review"            # Awaiting user approval
+    APPROVED = "approved"        # User approved, ready for implementation
+    IN_PROGRESS = "in_progress"  # Implementation started
+    COMPLETED = "completed"      # Fully implemented and verified
+    ARCHIVED = "archived"        # No longer active
+
+
+class SectionStatus(str, Enum):
+    PENDING = "pending"
+    IMPLEMENTED = "implemented"
+    MODIFIED = "modified"        # Implemented but deviated from spec
+    SKIPPED = "skipped"
+    BLOCKED = "blocked"
+
+
+class AcceptanceCriterion(BaseModel):
+    """A single acceptance criterion with verification status."""
+    id: str
+    description: str
+    status: str = "pending"      # pending, passed, failed
+    verified_by: str = ""        # Agent that verified
+    verified_at: Optional[str] = None
+    notes: str = ""
+
+
+class SpecSection(BaseModel):
+    """A section of the specification."""
+    id: str
+    title: str
+    content: str = ""
+    status: SectionStatus = SectionStatus.PENDING
+    acceptance_criteria: list[AcceptanceCriterion] = Field(default_factory=list)
+    implementation_notes: str = ""
+
+
+class SpecDelta(BaseModel):
+    """A recorded change between spec and implementation.
+
+    Deltas track WHY something changed, not just WHAT.
+    This builds institutional knowledge for future specs.
+    """
+    id: str
+    section_id: str
+    original: str                # What the spec said
+    actual: str                  # What was actually implemented
+    reason: str                  # Why it changed
+    decided_by: str = ""         # Agent or user who decided
+    timestamp: str = ""
+    impact: str = "low"          # low, medium, high
+
+
+class SpecMetadata(BaseModel):
+    """Metadata for a spec."""
+    project: str = ""
+    department: str = ""
+    created_by: str = ""
+    created_at: str = ""
+    updated_at: str = ""
+    approved_by: str = ""
+    approved_at: str = ""
+    tags: list[str] = Field(default_factory=list)
+    obsidian_path: str = ""
+
+
+class Spec(BaseModel):
+    """A Living Specification.
+
+    Unlike traditional specs that become stale, Living Specs
+    track their own implementation status and record deltas
+    between planned and actual outcomes.
+    """
+    id: str
+    title: str
+    description: str = ""
+    status: SpecStatus = SpecStatus.DRAFT
+    metadata: SpecMetadata = Field(default_factory=SpecMetadata)
+
+    # Spec content organized by sections
+    sections: list[SpecSection] = Field(default_factory=list)
+
+    # Changes tracked during implementation
+    deltas: list[SpecDelta] = Field(default_factory=list)
+
+    # Reusable patterns extracted after completion
+    patterns: list[str] = Field(default_factory=list)
+
+    def get_section(self, section_id: str) -> Optional[SpecSection]:
+        """Find a section by ID."""
+        for section in self.sections:
+            if section.id == section_id:
+                return section
+        return None
+
+    def add_delta(
+        self,
+        section_id: str,
+        original: str,
+        actual: str,
+        reason: str,
+        decided_by: str = "",
+    ) -> SpecDelta:
+        """Record a delta between spec and implementation."""
+        delta = SpecDelta(
+            id=f"delta-{len(self.deltas) + 1}",
+            section_id=section_id,
+            original=original,
+            actual=actual,
+            reason=reason,
+            decided_by=decided_by,
+            timestamp=datetime.now().isoformat(),
+        )
+        self.deltas.append(delta)
+
+        # Mark section as modified
+        section = self.get_section(section_id)
+        if section:
+            section.status = SectionStatus.MODIFIED
+
+        return delta
+
+    def mark_section_complete(self, section_id: str, notes: str = "") -> bool:
+        """Mark a section as implemented."""
+        section = self.get_section(section_id)
+        if section is None:
+            return False
+        if section.status != SectionStatus.MODIFIED:
+            section.status = SectionStatus.IMPLEMENTED
+        section.implementation_notes = notes
+        return True
+
+    def verify_criterion(
+        self,
+        section_id: str,
+        criterion_id: str,
+        passed: bool,
+        verified_by: str = "",
+        notes: str = "",
+    ) -> bool:
+        """Verify an acceptance criterion."""
+        section = self.get_section(section_id)
+        if section is None:
+            return False
+        for ac in section.acceptance_criteria:
+            if ac.id == criterion_id:
+                ac.status = "passed" if passed else "failed"
+                ac.verified_by = verified_by
+                ac.verified_at = datetime.now().isoformat()
+                ac.notes = notes
+                return True
+        return False
+
+    @property
+    def completion_percentage(self) -> float:
+        """Calculate completion percentage based on sections."""
+        if not self.sections:
+            return 0.0
+        done = sum(
+            1 for s in self.sections
+            if s.status in (SectionStatus.IMPLEMENTED, SectionStatus.MODIFIED, SectionStatus.SKIPPED)
+        )
+        return round(done / len(self.sections) * 100, 1)
+
+    @property
+    def criteria_summary(self) -> dict[str, int]:
+        """Summary of acceptance criteria status."""
+        counts = {"total": 0, "passed": 0, "failed": 0, "pending": 0}
+        for section in self.sections:
+            for ac in section.acceptance_criteria:
+                counts["total"] += 1
+                counts[ac.status] = counts.get(ac.status, 0) + 1
+        return counts
+
+    @property
+    def delta_count(self) -> int:
+        return len(self.deltas)
+
+    @property
+    def is_fully_verified(self) -> bool:
+        """Check if all acceptance criteria passed."""
+        summary = self.criteria_summary
+        return summary["total"] > 0 and summary["pending"] == 0 and summary["failed"] == 0

package/core/squads/__init__.py

@@ -0,0 +1,7 @@
+"""Squad Framework — YAML-based squad definitions and cross-department collaboration."""
+
+from core.squads.schema import Squad, SquadMember, SquadType
+from core.squads.registry import SquadRegistry
+from core.squads.loader import load_squad
+
+__all__ = ["Squad", "SquadMember", "SquadType", "SquadRegistry", "load_squad"]

package/core/squads/loader.py

@@ -0,0 +1,40 @@
+"""Squad YAML loader."""
+
+from pathlib import Path
+import yaml
+
+from core.squads.schema import Squad
+
+
+def load_squad(path: str | Path) -> Squad:
+    """Load a squad from a YAML file."""
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(f"Squad file not found: {path}")
+
+    with open(path) as f:
+        data = yaml.safe_load(f)
+
+    if data is None:
+        raise ValueError(f"Empty squad file: {path}")
+
+    return Squad.model_validate(data)
+
+
+def load_all_squads(base_dir: str | Path) -> list[Squad]:
+    """Load all squad YAML files from a directory tree.
+
+    Expects squad.yaml files in department directories.
+    """
+    base_dir = Path(base_dir)
+    squads = []
+
+    for squad_file in sorted(base_dir.glob("*/squad.yaml")):
+        try:
+            squad = load_squad(squad_file)
+            squads.append(squad)
+        except Exception as e:
+            import warnings
+            warnings.warn(f"Failed to load squad: {squad_file}: {e}")
+
+    return squads

package/core/squads/registry.py

@@ -0,0 +1,145 @@
+"""Squad registry — manages all squads and enables cross-department collaboration."""
+
+from typing import Optional
+from core.squads.schema import Squad, SquadMember, SquadType, TeamTopologyType
+
+
+class SquadRegistry:
+    """Central registry for all squads.
+
+    Manages department squads (loaded from YAML) and project squads
+    (assembled dynamically). Enables the matrix structure:
+    agents belong to a department squad but can be borrowed
+    into project squads.
+    """
+
+    def __init__(self) -> None:
+        self._squads: dict[str, Squad] = {}
+
+    def register(self, squad: Squad) -> None:
+        """Register a squad."""
+        self._squads[squad.id] = squad
+
+    def get(self, squad_id: str) -> Optional[Squad]:
+        """Get a squad by ID."""
+        return self._squads.get(squad_id)
+
+    def get_by_department(self, department: str) -> Optional[Squad]:
+        """Get the department squad for a given department."""
+        for squad in self._squads.values():
+            if squad.department == department and squad.squad_type == SquadType.DEPARTMENT:
+                return squad
+        return None
+
+    def get_by_prefix(self, prefix: str) -> Optional[Squad]:
+        """Get squad by CLI prefix (e.g., '/dev', '/mkt')."""
+        for squad in self._squads.values():
+            if squad.skills_prefix == prefix:
+                return squad
+        return None
+
+    def list_all(self) -> list[Squad]:
+        """List all registered squads."""
+        return list(self._squads.values())
+
+    def list_by_type(self, squad_type: SquadType) -> list[Squad]:
+        """List squads of a specific type."""
+        return [s for s in self._squads.values() if s.squad_type == squad_type]
+
+    def create_project_squad(
+        self,
+        project_id: str,
+        name: str,
+        description: str,
+        members: list[dict],
+    ) -> Squad:
+        """Assemble an ad-hoc project squad from agents across departments.
+
+        This is the matrix structure in action: agents from different
+        department squads are borrowed into a temporary project squad.
+
+        Args:
+            project_id: Unique ID for the project squad.
+            name: Human-readable name.
+            description: What this squad is working on.
+            members: List of dicts with agent_id and optional role.
+
+        Returns:
+            The assembled project Squad.
+        """
+        squad_members = []
+        for m in members:
+            agent_id = m["agent_id"]
+            role = m.get("role", "")
+
+            # Find which department this agent belongs to
+            source_dept = self._find_agent_department(agent_id)
+
+            squad_members.append(SquadMember(
+                agent_id=agent_id,
+                role=role,
+                is_lead=m.get("is_lead", False),
+                borrowed=True,
+                source_department=source_dept,
+                availability=m.get("availability", 0.5),
+            ))
+
+        squad = Squad(
+            id=f"project-{project_id}",
+            name=name,
+            description=description,
+            department="cross-department",
+            squad_type=SquadType.PROJECT,
+            topology=TeamTopologyType.STREAM_ALIGNED,
+            members=squad_members,
+        )
+
+        self.register(squad)
+        return squad
+
+    def disband_project_squad(self, squad_id: str) -> bool:
+        """Disband a project squad, returning agents to their departments."""
+        squad = self._squads.get(squad_id)
+        if squad is None or squad.squad_type != SquadType.PROJECT:
+            return False
+        del self._squads[squad_id]
+        return True
+
+    def find_agent_across_squads(self, agent_id: str) -> list[Squad]:
+        """Find all squads an agent belongs to."""
+        return [
+            s for s in self._squads.values()
+            if any(m.agent_id == agent_id for m in s.members)
+        ]
+
+    def _find_agent_department(self, agent_id: str) -> str:
+        """Find which department an agent belongs to."""
+        for squad in self._squads.values():
+            if squad.squad_type == SquadType.DEPARTMENT:
+                if any(m.agent_id == agent_id for m in squad.members):
+                    return squad.department
+        return "unknown"
+
+    @property
+    def total_squads(self) -> int:
+        return len(self._squads)
+
+    @property
+    def total_agents(self) -> int:
+        """Count unique agents across all squads."""
+        agents = set()
+        for squad in self._squads.values():
+            for member in squad.members:
+                agents.add(member.agent_id)
+        return len(agents)
+
+    def summary(self) -> dict:
+        """Get registry summary stats."""
+        dept_squads = self.list_by_type(SquadType.DEPARTMENT)
+        project_squads = self.list_by_type(SquadType.PROJECT)
+        return {
+            "total_squads": self.total_squads,
+            "department_squads": len(dept_squads),
+            "project_squads": len(project_squads),
+            "total_agents": self.total_agents,
+        }

package/core/squads/schema.py

@@ -0,0 +1,93 @@
+"""Squad schema — Pydantic models for squad definitions.
+
+Squads come in two flavors:
+- Department squads: Fixed teams within a department (e.g., Dev squad with 9 agents)
+- Project squads: Ad-hoc cross-department teams assembled for a specific task
+
+Inspired by Spotify Model (squads/tribes/chapters) and Team Topologies
+(stream-aligned, platform, enabling, complicated-subsystem).
+"""
+
+from enum import Enum
+from typing import Optional
+from pydantic import BaseModel, Field
+
+
+class SquadType(str, Enum):
+    DEPARTMENT = "department"        # Fixed department squad
+    PROJECT = "project"              # Ad-hoc cross-department squad
+    PLATFORM = "platform"            # Internal platform team (Team Topologies)
+    ENABLING = "enabling"            # Temporary capability boost
+
+
+class TeamTopologyType(str, Enum):
+    STREAM_ALIGNED = "stream-aligned"
+    PLATFORM = "platform"
+    ENABLING = "enabling"
+    COMPLICATED_SUBSYSTEM = "complicated-subsystem"
+
+
+class SquadMember(BaseModel):
+    """An agent assigned to a squad."""
+    agent_id: str
+    role: str = ""                   # Role within this squad
+    is_lead: bool = False            # Is this agent the squad lead?
+    borrowed: bool = False           # Borrowed from another department?
+    source_department: str = ""      # Original department if borrowed
+    availability: float = 1.0        # 0.0-1.0, for shared agents
+
+
+class SquadWorkflow(BaseModel):
+    """Reference to a workflow this squad uses."""
+    workflow_id: str
+    trigger_command: str = ""        # CLI command that triggers this workflow
+    tier: str = "enterprise"         # enterprise, focused, specialist
+
+
+class Squad(BaseModel):
+    """A squad of agents working together.
+
+    Department squads are defined in YAML and loaded at startup.
+    Project squads are assembled dynamically from multiple departments.
+    """
+    id: str
+    name: str
+    description: str = ""
+    department: str                  # Primary department
+    squad_type: SquadType = SquadType.DEPARTMENT
+    topology: TeamTopologyType = TeamTopologyType.STREAM_ALIGNED
+
+    members: list[SquadMember] = Field(default_factory=list)
+    workflows: list[SquadWorkflow] = Field(default_factory=list)
+
+    # Squad metadata
+    max_size: int = 10               # Max members (Two-Pizza Team rule)
+    skills_prefix: str = ""          # CLI prefix (e.g., "/dev", "/mkt")
+    obsidian_path: str = ""          # Output path in Obsidian vault
+    quality_gate_required: bool = True
+
+    def get_lead(self) -> Optional[SquadMember]:
+        """Get the squad lead."""
+        for member in self.members:
+            if member.is_lead:
+                return member
+        return None
+
+    def get_member(self, agent_id: str) -> Optional[SquadMember]:
+        """Find a member by agent ID."""
+        for member in self.members:
+            if member.agent_id == agent_id:
+                return member
+        return None
+
+    def borrowed_members(self) -> list[SquadMember]:
+        """Get all members borrowed from other departments."""
+        return [m for m in self.members if m.borrowed]
+
+    @property
+    def size(self) -> int:
+        return len(self.members)
+
+    @property
+    def has_lead(self) -> bool:
+        return self.get_lead() is not None

package/core/synapse/__init__.py

@@ -0,0 +1,11 @@
+"""Synapse v2 — 8-layer context injection engine.
+
+Injects relevant context into every prompt with <100ms target latency
+and 65% context reduction through intelligent filtering.
+"""
+
+from core.synapse.engine import SynapseEngine
+from core.synapse.layers import Layer, LayerResult
+from core.synapse.cache import LayerCache
+
+__all__ = ["SynapseEngine", "Layer", "LayerResult", "LayerCache"]

package/core/synapse/cache.py

@@ -0,0 +1,82 @@
+"""TTL-based cache for Synapse layers.
+
+Each layer can have its own cache TTL. The cache stores computed
+layer results to avoid re-computation on every prompt.
+"""
+
+import time
+from dataclasses import dataclass, field
+
+
+@dataclass
+class CacheEntry:
+    """A single cached value with TTL."""
+    value: str
+    created_at: float
+    ttl_seconds: int
+
+    @property
+    def is_expired(self) -> bool:
+        if self.ttl_seconds <= 0:
+            return False  # TTL 0 = never expires
+        return (time.time() - self.created_at) > self.ttl_seconds
+
+
+class LayerCache:
+    """TTL-based cache for layer results.
+
+    Each layer key maps to a cached value with its own TTL.
+    Expired entries are evicted on access.
+    """
+
+    def __init__(self) -> None:
+        self._store: dict[str, CacheEntry] = {}
+        self._hits: int = 0
+        self._misses: int = 0
+
+    def get(self, key: str) -> str | None:
+        """Get a cached value, or None if missing/expired."""
+        entry = self._store.get(key)
+        if entry is None:
+            self._misses += 1
+            return None
+        if entry.is_expired:
+            del self._store[key]
+            self._misses += 1
+            return None
+        self._hits += 1
+        return entry.value
+
+    def set(self, key: str, value: str, ttl_seconds: int = 300) -> None:
+        """Cache a value with TTL."""
+        self._store[key] = CacheEntry(
+            value=value,
+            created_at=time.time(),
+            ttl_seconds=ttl_seconds,
+        )
+
+    def invalidate(self, key: str) -> None:
+        """Remove a specific key from cache."""
+        self._store.pop(key, None)
+
+    def clear(self) -> None:
+        """Clear all cached entries."""
+        self._store.clear()
+
+    def evict_expired(self) -> int:
+        """Remove all expired entries. Returns count of evicted entries."""
+        expired = [k for k, v in self._store.items() if v.is_expired]
+        for k in expired:
+            del self._store[k]
+        return len(expired)
+
+    @property
+    def stats(self) -> dict[str, int]:
+        """Cache hit/miss statistics."""
+        total = self._hits + self._misses
+        return {
+            "hits": self._hits,
+            "misses": self._misses,
+            "hit_rate": round(self._hits / total * 100) if total > 0 else 0,
+            "size": len(self._store),
+        }