arkaos 2.0.1 → 2.0.3

package/VERSION

@@ -1 +1 @@
-2.0.1
+2.0.3

package/config/constitution.yaml

@@ -60,6 +60,8 @@ enforcement_levels:
 
   quality_gate:
     description: "Mandatory pre-delivery review. Nothing ships without APPROVED verdict."
+    trigger: "After the last execution phase, before delivery to user"
+    frequency: "Once per workflow execution, not per phase"
     agents:
       orchestrator:
         id: cqo-marta
@@ -118,6 +120,10 @@ enforcement_levels:
       - id: complexity-assessment
         rule: "Assess task complexity before starting. Route to appropriate workflow tier."
 
+      - id: communication-standard
+        rule: "Bottom-line first output. Lead with answer, then why, then how. Confidence tags on assessments."
+        enforcement: "See config/standards/communication.md for full standard"
+
 tier_hierarchy:
   description: "Agent authority levels inspired by SpaceX/Google/Anthropic org structures"
   tiers:

package/config/hooks/user-prompt-submit-v2.sh

@@ -7,6 +7,17 @@
 
 input=$(cat)
 
+# ─── V1 Migration Detection ─────────────────────────────────────────────
+V1_PATHS=("$HOME/.claude/skills/arka-os" "$HOME/.claude/skills/arkaos")
+MIGRATION_MARKER="$HOME/.arkaos/migrated-from-v1"
+
+for v1_path in "${V1_PATHS[@]}"; do
+  if [ -d "$v1_path" ] && [ ! -f "$MIGRATION_MARKER" ]; then
+    echo "{\"additionalContext\": \"[MIGRATION] ArkaOS v1 detected at $v1_path. Run: npx arkaos migrate — This will backup v1, preserve your data, and install v2. See: https://github.com/andreagroferreira/arka-os#install\"}"
+    exit 0
+  fi
+done
+
 # ─── Performance Timing ──────────────────────────────────────────────────
 _HOOK_START_NS=$(date +%s%N 2>/dev/null || echo "0")
 _hook_ms() {
@@ -19,7 +30,18 @@ _hook_ms() {
 }
 
 # ─── Paths ───────────────────────────────────────────────────────────────
-ARKAOS_ROOT="${ARKA_OS:-$HOME/.claude/skills/arkaos}"
+# Resolve ARKAOS_ROOT: env var → .repo-path → npm package → fallback
+if [ -n "${ARKAOS_ROOT:-}" ]; then
+  : # already set
+elif [ -f "$HOME/.arkaos/.repo-path" ]; then
+  ARKAOS_ROOT=$(cat "$HOME/.arkaos/.repo-path")
+elif [ -d "$HOME/.arkaos" ]; then
+  ARKAOS_ROOT="$HOME/.arkaos"
+else
+  ARKAOS_ROOT="${ARKA_OS:-$HOME/.claude/skills/arkaos}"
+fi
+export ARKAOS_ROOT
+
 CACHE_DIR="/tmp/arkaos-context-cache"
 CACHE_TTL=300  # Constitution cache: 5 minutes
 
@@ -35,46 +57,17 @@ if [ -z "$user_input" ]; then
   user_input=$(echo "$input" | head -c 2000)
 fi
 
-# ─── Try Python Synapse engine first ─────────────────────────────────────
+# ─── Try Python Synapse bridge first ────────────────────────────────────
 python_result=""
-if command -v python3 &>/dev/null; then
-  python_result=$(python3 -c "
-import sys, os
-sys.path.insert(0, '${ARKAOS_ROOT}')
-try:
-    from core.synapse.engine import create_default_engine
-    from core.synapse.layers import PromptContext
-    from core.governance.constitution import load_constitution
-    import subprocess
-
-    # Load constitution for L0
-    const_path = '${ARKAOS_ROOT}/config/constitution.yaml'
-    compressed = ''
-    if os.path.exists(const_path):
-        c = load_constitution(const_path)
-        compressed = c.compress_for_context()
-
-    # Detect git branch
-    branch = ''
-    try:
-        branch = subprocess.run(['git', 'rev-parse', '--abbrev-ref', 'HEAD'],
-                                capture_output=True, text=True, timeout=2).stdout.strip()
-    except Exception:
-        pass
-
-    # Create engine and inject
-    engine = create_default_engine(constitution_compressed=compressed)
-    ctx = PromptContext(
-        user_input='''${user_input}''',
-        cwd=os.getcwd(),
-        git_branch=branch,
-    )
-    result = engine.inject(ctx)
-    print(result.context_string)
-except Exception as e:
-    print(f'[arkaos:error] {e}', file=sys.stderr)
-    print('')
-" 2>/dev/null)
+BRIDGE_SCRIPT="${ARKAOS_ROOT}/scripts/synapse-bridge.py"
+
+if command -v python3 &>/dev/null && [ -f "$BRIDGE_SCRIPT" ]; then
+  bridge_output=$(echo "{\"user_input\":$(echo "$user_input" | python3 -c "import sys,json; print(json.dumps(sys.stdin.read()))" 2>/dev/null || echo '""')}" \
+    | ARKAOS_ROOT="$ARKAOS_ROOT" python3 "$BRIDGE_SCRIPT" --root "$ARKAOS_ROOT" 2>/dev/null)
+
+  if [ -n "$bridge_output" ]; then
+    python_result=$(echo "$bridge_output" | python3 -c "import sys,json; print(json.loads(sys.stdin.read()).get('context_string',''))" 2>/dev/null)
+  fi
 fi
 
 # ─── Fallback: Bash-only context (if Python unavailable) ────────────────

package/core/budget/__init__.py

@@ -0,0 +1,6 @@
+"""Token budget system — tracking and enforcement for agent operations."""
+
+from core.budget.schema import BudgetConfig, BudgetUsage, BudgetSummary, TierBudget
+from core.budget.manager import BudgetManager
+
+__all__ = ["BudgetConfig", "BudgetUsage", "BudgetSummary", "TierBudget", "BudgetManager"]

package/core/budget/manager.py

@@ -0,0 +1,193 @@
+"""Budget manager — track, enforce, and report on token budgets."""
+
+import json
+from datetime import date, datetime
+from pathlib import Path
+from typing import Optional
+
+from core.budget.schema import BudgetConfig, BudgetSummary, BudgetUsage, TierBudget
+
+
+class BudgetManager:
+    """Manages token budget allocation, tracking, and enforcement.
+
+    Budgets are tier-based with monthly reset. Usage is persisted to JSON.
+    Tier 0 agents have unlimited budgets. Other tiers need Tier 0 approval
+    when usage exceeds the approval threshold (default 80%).
+    """
+
+    def __init__(self, storage_path: str | Path = "", config: BudgetConfig | None = None) -> None:
+        self._config = config or BudgetConfig()
+        self._usages: list[BudgetUsage] = []
+        self._counter: int = 0
+        self._storage_path = Path(storage_path) if storage_path else None
+        if self._storage_path and self._storage_path.exists():
+            self._load()
+
+    def record_usage(
+        self,
+        agent_id: str,
+        tokens: int,
+        tier: int = 2,
+        department: str = "",
+        workflow_id: str = "",
+        task_id: str = "",
+        description: str = "",
+        approved_by: str = "",
+    ) -> BudgetUsage:
+        """Record a token usage event."""
+        self._counter += 1
+        usage = BudgetUsage(
+            id=f"usage-{self._counter:06d}",
+            agent_id=agent_id,
+            department=department,
+            tier=tier,
+            tokens=tokens,
+            workflow_id=workflow_id,
+            task_id=task_id,
+            description=description,
+            timestamp=datetime.now().isoformat(),
+            approved_by=approved_by,
+        )
+        self._usages.append(usage)
+        self._save()
+        return usage
+
+    def get_period_usage(self, tier: int, department: str = "") -> int:
+        """Get total tokens used this billing period for a tier/department."""
+        period_start = self._current_period_start()
+        total = 0
+        for u in self._usages:
+            if u.tier != tier:
+                continue
+            if department and u.department != department:
+                continue
+            if u.timestamp and u.timestamp >= period_start.isoformat():
+                total += u.tokens
+        return total
+
+    def get_remaining(self, tier: int, department: str = "") -> int:
+        """Get remaining tokens for this period. Returns -1 for unlimited."""
+        budget = self._config.get_tier_budget(tier)
+        if budget.is_unlimited:
+            return -1
+        used = self.get_period_usage(tier, department)
+        return max(0, budget.monthly_tokens - used)
+
+    def check_budget(self, tier: int, estimated_tokens: int, department: str = "") -> bool:
+        """Check if there's enough budget for an operation. True = OK."""
+        budget = self._config.get_tier_budget(tier)
+        if budget.is_unlimited:
+            return True
+
+        # Check per-task limit
+        if budget.per_task_max > 0 and estimated_tokens > budget.per_task_max:
+            return False
+
+        # Check remaining monthly budget
+        remaining = self.get_remaining(tier, department)
+        return estimated_tokens <= remaining
+
+    def needs_approval(self, tier: int, department: str = "") -> bool:
+        """Check if usage has exceeded the approval threshold."""
+        budget = self._config.get_tier_budget(tier)
+        if budget.is_unlimited:
+            return False
+        used = self.get_period_usage(tier, department)
+        return used >= (budget.monthly_tokens * budget.approval_threshold)
+
+    def get_summary(self, tier: int, department: str = "") -> BudgetSummary:
+        """Get a complete budget summary for a tier/department."""
+        budget = self._config.get_tier_budget(tier)
+        used = self.get_period_usage(tier, department)
+        period_start = self._current_period_start()
+
+        if budget.is_unlimited:
+            return BudgetSummary(
+                tier=tier,
+                department=department,
+                period_start=period_start.isoformat(),
+                allocated=0,
+                used=used,
+                remaining=-1,
+                percent_used=0,
+                is_unlimited=True,
+                usage_count=self._count_period_usages(tier, department),
+            )
+
+        remaining = max(0, budget.monthly_tokens - used)
+        percent = (used / budget.monthly_tokens * 100) if budget.monthly_tokens > 0 else 0
+        overruns = sum(
+            1 for u in self._usages
+            if u.tier == tier
+            and (not department or u.department == department)
+            and u.timestamp >= period_start.isoformat()
+            and u.is_overrun_approved
+        )
+
+        return BudgetSummary(
+            tier=tier,
+            department=department,
+            period_start=period_start.isoformat(),
+            allocated=budget.monthly_tokens,
+            used=used,
+            remaining=remaining,
+            percent_used=round(percent, 1),
+            is_unlimited=False,
+            needs_approval=self.needs_approval(tier, department),
+            usage_count=self._count_period_usages(tier, department),
+            overruns=overruns,
+        )
+
+    def reset_monthly(self) -> int:
+        """Archive old usages and start a new billing period. Returns archived count."""
+        period_start = self._current_period_start()
+        old = [u for u in self._usages if u.timestamp < period_start.isoformat()]
+        self._usages = [u for u in self._usages if u.timestamp >= period_start.isoformat()]
+        self._save()
+        return len(old)
+
+    def _current_period_start(self) -> date:
+        """Get the start of the current billing period."""
+        today = date.today()
+        day = self._config.billing_start_day
+        if today.day >= day:
+            return date(today.year, today.month, day)
+        # Previous month
+        month = today.month - 1
+        year = today.year
+        if month < 1:
+            month = 12
+            year -= 1
+        return date(year, month, day)
+
+    def _count_period_usages(self, tier: int, department: str = "") -> int:
+        period_start = self._current_period_start()
+        return sum(
+            1 for u in self._usages
+            if u.tier == tier
+            and (not department or u.department == department)
+            and u.timestamp >= period_start.isoformat()
+        )
+
+    def _save(self) -> None:
+        if self._storage_path is None:
+            return
+        self._storage_path.parent.mkdir(parents=True, exist_ok=True)
+        data = {
+            "counter": self._counter,
+            "usages": [u.model_dump(mode="json") for u in self._usages],
+        }
+        with open(self._storage_path, "w") as f:
+            json.dump(data, f, indent=2)
+
+    def _load(self) -> None:
+        if self._storage_path is None or not self._storage_path.exists():
+            return
+        content = self._storage_path.read_text().strip()
+        if not content:
+            return
+        data = json.loads(content)
+        self._counter = data.get("counter", 0)
+        for udata in data.get("usages", []):
+            self._usages.append(BudgetUsage.model_validate(udata))

package/core/budget/schema.py

@@ -0,0 +1,82 @@
+"""Budget schema — token allocation, usage tracking, and summaries."""
+
+from datetime import date, datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class TierBudget(BaseModel):
+    """Token budget for a single agent tier."""
+    tier: int
+    monthly_tokens: int          # 0 = unlimited
+    per_task_max: int            # 0 = unlimited
+    approval_threshold: float = 0.8  # Needs Tier 0 approval at this % used
+
+    @property
+    def is_unlimited(self) -> bool:
+        return self.monthly_tokens == 0
+
+
+# Default tier budgets (configurable via BudgetConfig)
+DEFAULT_TIER_BUDGETS = {
+    0: TierBudget(tier=0, monthly_tokens=0, per_task_max=0),           # Unlimited
+    1: TierBudget(tier=1, monthly_tokens=5_000_000, per_task_max=500_000),
+    2: TierBudget(tier=2, monthly_tokens=2_000_000, per_task_max=200_000),
+    3: TierBudget(tier=3, monthly_tokens=1_000_000, per_task_max=100_000),
+}
+
+
+class BudgetConfig(BaseModel):
+    """Budget configuration for the system."""
+    tier_budgets: dict[int, TierBudget] = Field(default_factory=lambda: dict(DEFAULT_TIER_BUDGETS))
+    billing_start_day: int = 1  # Day of month billing resets
+
+    def get_tier_budget(self, tier: int) -> TierBudget:
+        return self.tier_budgets.get(tier, DEFAULT_TIER_BUDGETS.get(tier, TierBudget(tier=tier, monthly_tokens=1_000_000, per_task_max=100_000)))
+
+
+class BudgetUsage(BaseModel):
+    """A single token usage record."""
+    id: str
+    agent_id: str
+    department: str = ""
+    tier: int = 2
+    tokens: int = 0
+    workflow_id: str = ""
+    task_id: str = ""
+    description: str = ""
+    timestamp: str = ""
+    approved_by: str = ""  # Tier 0 agent who approved overrun
+
+    @property
+    def is_overrun_approved(self) -> bool:
+        return bool(self.approved_by)
+
+
+class BudgetSummary(BaseModel):
+    """Current budget status for a tier or department."""
+    tier: int
+    department: str = ""
+    period_start: str = ""
+    period_end: str = ""
+    allocated: int = 0          # Monthly allocation
+    used: int = 0               # Tokens used this period
+    remaining: int = 0          # Tokens remaining
+    percent_used: float = 0.0   # 0-100
+    is_unlimited: bool = False
+    needs_approval: bool = False  # >80% threshold
+    usage_count: int = 0        # Number of operations this period
+    overruns: int = 0           # Number of approved overruns
+
+    @property
+    def status(self) -> str:
+        if self.is_unlimited:
+            return "UNLIMITED"
+        if self.percent_used >= 100:
+            return "EXCEEDED"
+        if self.needs_approval:
+            return "APPROVAL_REQUIRED"
+        if self.percent_used >= 50:
+            return "MODERATE"
+        return "HEALTHY"

package/core/knowledge/__init__.py

@@ -0,0 +1,6 @@
+"""Knowledge system — vector store, chunking, embedding, and retrieval."""
+
+from core.knowledge.chunker import chunk_markdown
+from core.knowledge.vector_store import VectorStore
+
+__all__ = ["VectorStore", "chunk_markdown"]

package/core/knowledge/chunker.py

@@ -0,0 +1,121 @@
+"""Markdown chunker — split documents into embeddable chunks.
+
+Splits on paragraph boundaries, respects heading structure,
+and maintains overlap for context continuity.
+"""
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass
+class Chunk:
+    """A text chunk ready for embedding."""
+    text: str
+    heading: str = ""       # Current heading context
+    index: int = 0          # Position in document
+    source: str = ""        # Source file path
+
+    @property
+    def token_estimate(self) -> int:
+        return len(self.text.split())
+
+
+def chunk_markdown(
+    content: str,
+    max_tokens: int = 512,
+    overlap_tokens: int = 50,
+    source: str = "",
+) -> list[Chunk]:
+    """Split markdown content into chunks at paragraph boundaries.
+
+    Args:
+        content: Markdown text to chunk.
+        max_tokens: Maximum tokens per chunk.
+        overlap_tokens: Token overlap between consecutive chunks.
+        source: Source file path for metadata.
+
+    Returns:
+        List of Chunk objects.
+    """
+    # Strip frontmatter
+    body = content
+    if content.startswith("---"):
+        end = content.find("---", 3)
+        if end != -1:
+            body = content[end + 3:].strip()
+
+    # Split into paragraphs (double newline) preserving headings
+    blocks = re.split(r'\n\n+', body)
+    blocks = [b.strip() for b in blocks if b.strip()]
+
+    chunks: list[Chunk] = []
+    current_heading = ""
+    current_text = ""
+    current_tokens = 0
+
+    for block in blocks:
+        # Track headings
+        heading_match = re.match(r'^(#{1,6})\s+(.+)', block)
+        if heading_match:
+            current_heading = heading_match.group(2)
+
+        block_tokens = len(block.split())
+
+        # If single block exceeds max, split it
+        if block_tokens > max_tokens:
+            if current_text:
+                chunks.append(Chunk(
+                    text=current_text.strip(),
+                    heading=current_heading,
+                    index=len(chunks),
+                    source=source,
+                ))
+                current_text = ""
+                current_tokens = 0
+
+            # Split large block by sentences
+            sentences = re.split(r'(?<=[.!?])\s+', block)
+            for sentence in sentences:
+                sent_tokens = len(sentence.split())
+                if current_tokens + sent_tokens > max_tokens and current_text:
+                    chunks.append(Chunk(
+                        text=current_text.strip(),
+                        heading=current_heading,
+                        index=len(chunks),
+                        source=source,
+                    ))
+                    # Overlap: keep last few words
+                    words = current_text.split()
+                    current_text = " ".join(words[-overlap_tokens:]) + " " if len(words) > overlap_tokens else ""
+                    current_tokens = len(current_text.split())
+                current_text += sentence + " "
+                current_tokens += sent_tokens
+            continue
+
+        # Check if adding this block exceeds limit
+        if current_tokens + block_tokens > max_tokens and current_text:
+            chunks.append(Chunk(
+                text=current_text.strip(),
+                heading=current_heading,
+                index=len(chunks),
+                source=source,
+            ))
+            # Overlap
+            words = current_text.split()
+            current_text = " ".join(words[-overlap_tokens:]) + " " if len(words) > overlap_tokens else ""
+            current_tokens = len(current_text.split())
+
+        current_text += block + "\n\n"
+        current_tokens += block_tokens
+
+    # Final chunk
+    if current_text.strip():
+        chunks.append(Chunk(
+            text=current_text.strip(),
+            heading=current_heading,
+            index=len(chunks),
+            source=source,
+        ))
+
+    return chunks

package/core/knowledge/embedder.py

@@ -0,0 +1,52 @@
+"""Embedding wrapper — local embeddings via fastembed.
+
+Graceful degradation: if fastembed is not installed, returns None
+and the vector store falls back to keyword matching.
+"""
+
+from typing import Optional
+
+# Lazy import — fastembed is optional
+_model = None
+_model_name = "BAAI/bge-small-en-v1.5"  # 384 dims, fast, good quality
+EMBEDDING_DIMS = 384
+
+
+def get_model():
+    """Get or create the embedding model (lazy singleton)."""
+    global _model
+    if _model is None:
+        try:
+            from fastembed import TextEmbedding
+            _model = TextEmbedding(_model_name)
+        except ImportError:
+            return None
+    return _model
+
+
+def embed(text: str) -> Optional[list[float]]:
+    """Embed a single text. Returns None if fastembed unavailable."""
+    model = get_model()
+    if model is None:
+        return None
+    results = list(model.embed([text]))
+    return results[0].tolist() if results else None
+
+
+def embed_batch(texts: list[str]) -> Optional[list[list[float]]]:
+    """Embed multiple texts. Returns None if fastembed unavailable."""
+    if not texts:
+        return []
+    model = get_model()
+    if model is None:
+        return None
+    return [emb.tolist() for emb in model.embed(texts)]
+
+
+def is_available() -> bool:
+    """Check if embedding model is available."""
+    try:
+        from fastembed import TextEmbedding
+        return True
+    except ImportError:
+        return False