arkaos 2.25.0 → 2.28.0

package/core/cognition/retrieval.py

@@ -0,0 +1,383 @@
+"""Hooks-as-retrieval prototype for the ArkaOS Cognitive Layer.
+
+After each tool call, the PostToolUse hook calls into this module to
+extract likely entities from the tool output, find relevant notes in the
+Obsidian vault, and write a small JSON cache that the UserPromptSubmit
+hook injects into the next turn as an ``[arka:context]`` advisory.
+
+This is the prototype unblocked by Claude Code 2.1.122 (late-binding
+``ToolSearch`` + hook-block isolation, see KB note
+2026-04-29-claude-code-2-1-122-and-2-1-123). It uses filesystem grep
+(ripgrep when available, Python fallback otherwise) instead of running
+a separate MCP server with embeddings — a deliberate "smallest thing
+that could possibly work" choice per the 2026-05-13 Conclave ADR.
+
+Performance budget: ≤ 800 ms p95 per ``capture_context`` call. The
+PostToolUse hook enforces this with a hard timeout; the function itself
+caps entities (20), vault hits (5), and ripgrep wall time (1 s).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+from core.runtime.user_paths import user_data_root
+
+_CACHE_DIRNAME = "context-cache"
+_DEFAULT_TTL_SECONDS = 600
+_REAPER_MAX_AGE_SECONDS = 24 * 60 * 60  # cache files older than 24h get pruned
+_MAX_ENTITIES = 20
+_MAX_VAULT_HITS = 5
+_RIPGREP_TIMEOUT_S = 1.0
+_PY_FALLBACK_MAX_FILES = 500
+
+# Common-word stoplist — kept tiny on purpose; we want to capture short
+# domain terms like "auth" or "DSL" but cut out the highest-frequency
+# English filler tokens that dominate any tool output.
+_STOPLIST = frozenset(
+    {
+        "The", "And", "But", "For", "Not", "With", "From", "This", "That",
+        "When", "Where", "Then", "Else", "True", "False", "None", "Null",
+        "Error", "Warning", "Info", "Debug", "Trace", "Yes", "No", "Run",
+        "Read", "Write", "Edit", "Delete", "Show", "Find", "List",
+    }
+)
+
+_FILE_PATH = re.compile(r"(?:^|\s)((?:[\w.-]+/)+[\w.-]+\.[a-zA-Z]{1,6})")
+_CAMEL_OR_PASCAL = re.compile(r"\b([A-Z][a-z]+(?:[A-Z][a-z]+)+)\b")
+_AT_MENTION = re.compile(r"@([\w./_-]+)")
+_PROPER_NOUN = re.compile(r"\b([A-Z][a-zA-Z]{2,})\b")
+
+
+@dataclass
+class ContextHit:
+    """One vault note that matches one or more extracted entities."""
+
+    entity: str
+    vault_path: str
+    snippet: str
+    score: float = 1.0
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class ContextCache:
+    """The JSON payload persisted per session."""
+
+    session_id: str
+    captured_at: str
+    ttl_seconds: int
+    hits: list[ContextHit] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "session_id": self.session_id,
+            "captured_at": self.captured_at,
+            "ttl_seconds": self.ttl_seconds,
+            "hits": [h.to_dict() for h in self.hits],
+        }
+
+
+def extract_entities(text: str) -> list[str]:
+    """Pull file paths, identifiers, and proper nouns out of *text*.
+
+    Returns a deduplicated, capped list ready for vault search. Cheap
+    enough to call on every PostToolUse invocation.
+    """
+    if not text:
+        return []
+    seen: set[str] = set()
+    out: list[str] = []
+
+    def push(tok: str) -> None:
+        tok = tok.strip(" .,;:!?\"'()[]{}")
+        if not tok or tok in _STOPLIST or tok in seen:
+            return
+        if tok.isdigit():
+            return
+        seen.add(tok)
+        out.append(tok)
+        return
+
+    for m in _FILE_PATH.finditer(text):
+        push(m.group(1))
+    for m in _AT_MENTION.finditer(text):
+        push(m.group(1))
+    for m in _CAMEL_OR_PASCAL.finditer(text):
+        push(m.group(1))
+    for m in _PROPER_NOUN.finditer(text):
+        if len(out) >= _MAX_ENTITIES:
+            break
+        push(m.group(1))
+    return out[:_MAX_ENTITIES]
+
+
+def search_vault(entities: list[str], vault_path: str) -> list[ContextHit]:
+    """Find Obsidian notes that mention any of the extracted entities.
+
+    Uses ripgrep when available (sub-second across thousands of notes),
+    falls back to a pure-Python scan capped at ``_PY_FALLBACK_MAX_FILES``
+    files so the hook timeout stays safe on Windows or minimal Linux
+    installs without ripgrep.
+    """
+    vault = Path(vault_path).expanduser()
+    if not entities or not vault.is_dir():
+        return []
+    if _ripgrep_available():
+        hits = _search_ripgrep(entities, vault)
+    else:
+        hits = _search_python(entities, vault)
+    return hits[:_MAX_VAULT_HITS]
+
+
+def capture_context(
+    session_id: str,
+    tool_output: str,
+    vault_path: str,
+    cache_dir: Path | None = None,
+) -> ContextCache:
+    """Run extract + search and persist the cache. Returns the cache.
+
+    Idempotent across overlapping calls in the same second: a second
+    invocation overwrites the first. Empty hits still produce a file
+    so the UserPromptSubmit reader sees a fresh ``captured_at`` and
+    doesn't mistake a quiet turn for stale data.
+    """
+    entities = extract_entities(tool_output)
+    hits = search_vault(entities, vault_path) if entities else []
+    cache = ContextCache(
+        session_id=session_id,
+        captured_at=datetime.now(timezone.utc).isoformat(),
+        ttl_seconds=_DEFAULT_TTL_SECONDS,
+        hits=hits,
+    )
+    _write_cache(cache, cache_dir or _default_cache_dir())
+    return cache
+
+
+def read_context(
+    session_id: str,
+    ttl_seconds: int = _DEFAULT_TTL_SECONDS,
+    cache_dir: Path | None = None,
+) -> list[ContextHit]:
+    """Read cached hits for *session_id* if still within TTL."""
+    path = (cache_dir or _default_cache_dir()) / f"{session_id}.json"
+    if not path.exists():
+        return []
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return []
+    captured = data.get("captured_at", "")
+    if not _within_ttl(captured, ttl_seconds):
+        return []
+    return [ContextHit(**h) for h in data.get("hits", [])]
+
+
+def format_advisory(hits: list[ContextHit], max_chars: int = 1200) -> str:
+    """Render hits into a compact `[arka:context]` advisory string."""
+    if not hits:
+        return ""
+    lines = ["[arka:context] KB matches from last turn:"]
+    for h in hits:
+        line = f"- {h.entity} → {h.vault_path}: {h.snippet[:160]}"
+        if sum(len(l) for l in lines) + len(line) > max_chars:
+            break
+        lines.append(line)
+    return "\n".join(lines)
+
+
+def _default_cache_dir() -> Path:
+    return user_data_root() / _CACHE_DIRNAME
+
+
+def _write_cache(cache: ContextCache, cache_dir: Path) -> None:
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    path = cache_dir / f"{cache.session_id}.json"
+    tmp = cache_dir / f"{cache.session_id}.json.tmp"
+    tmp.write_text(json.dumps(cache.to_dict(), indent=2), encoding="utf-8")
+    os.replace(tmp, path)
+    _prune_stale_cache(cache_dir)
+
+
+def _prune_stale_cache(cache_dir: Path) -> int:
+    """Delete cache files older than 24h to bound disk growth.
+
+    Called from ``_write_cache`` so cleanup amortises across normal use
+    without requiring a separate cron job. Per Marta's PR4 follow-up
+    observation: the read-side TTL hides stale data but on-disk files
+    accumulate one-per-session forever. Returns the count of pruned files.
+    """
+    if not cache_dir.is_dir():
+        return 0
+    cutoff = datetime.now(timezone.utc).timestamp() - _REAPER_MAX_AGE_SECONDS
+    pruned = 0
+    for child in cache_dir.glob("*.json"):
+        try:
+            if child.stat().st_mtime < cutoff:
+                child.unlink()
+                pruned += 1
+        except OSError:
+            continue
+    return pruned
+
+
+def _within_ttl(captured_iso: str, ttl_seconds: int) -> bool:
+    try:
+        captured = datetime.fromisoformat(captured_iso)
+    except ValueError:
+        return False
+    now = datetime.now(timezone.utc)
+    if captured.tzinfo is None:
+        captured = captured.replace(tzinfo=timezone.utc)
+    return (now - captured).total_seconds() <= ttl_seconds
+
+
+def _ripgrep_available() -> bool:
+    try:
+        subprocess.run(
+            ["rg", "--version"], check=True, capture_output=True, timeout=1.0
+        )
+        return True
+    except (FileNotFoundError, subprocess.SubprocessError):
+        return False
+
+
+def _search_ripgrep(entities: list[str], vault: Path) -> list[ContextHit]:
+    pattern = "|".join(re.escape(e) for e in entities)
+    cmd = [
+        "rg", "--json", "--max-count", "1", "--smart-case",
+        "-tmd", "-e", pattern, str(vault),
+    ]
+    try:
+        result = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=_RIPGREP_TIMEOUT_S
+        )
+    except subprocess.SubprocessError:
+        return []
+    return _parse_ripgrep_json(result.stdout, vault, entities)
+
+
+def _parse_ripgrep_json(stdout: str, vault: Path, entities: list[str]) -> list[ContextHit]:
+    hits: list[ContextHit] = []
+    seen: set[str] = set()
+    for line in stdout.splitlines():
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if event.get("type") != "match":
+            continue
+        data = event.get("data", {})
+        path = data.get("path", {}).get("text", "")
+        if not path or path in seen:
+            continue
+        seen.add(path)
+        text = data.get("lines", {}).get("text", "").strip()
+        matched_entity = _pick_matched_entity(text, entities)
+        rel = _relative_to_vault(path, vault)
+        hits.append(ContextHit(entity=matched_entity, vault_path=rel, snippet=text))
+    return hits
+
+
+def _search_python(entities: list[str], vault: Path) -> list[ContextHit]:
+    pattern = re.compile("|".join(re.escape(e) for e in entities), re.IGNORECASE)
+    files = list(vault.rglob("*.md"))[:_PY_FALLBACK_MAX_FILES]
+    hits: list[ContextHit] = []
+    for f in files:
+        try:
+            text = f.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        match = pattern.search(text)
+        if not match:
+            continue
+        snippet_start = max(0, match.start() - 40)
+        snippet_end = min(len(text), match.end() + 80)
+        snippet = text[snippet_start:snippet_end].replace("\n", " ").strip()
+        hits.append(
+            ContextHit(
+                entity=match.group(0),
+                vault_path=str(f.relative_to(vault)),
+                snippet=snippet,
+            )
+        )
+        if len(hits) >= _MAX_VAULT_HITS:
+            break
+    return hits
+
+
+def _pick_matched_entity(text: str, entities: list[str]) -> str:
+    lower = text.lower()
+    for e in entities:
+        if e.lower() in lower:
+            return e
+    return entities[0] if entities else ""
+
+
+def _relative_to_vault(absolute: str, vault: Path) -> str:
+    try:
+        return str(Path(absolute).relative_to(vault))
+    except ValueError:
+        return absolute
+
+
+def _vault_path_or_none() -> str | None:
+    """Resolve the configured vault path or return None when missing.
+
+    Hooks call this; they must never crash because profile.json is absent.
+    """
+    try:
+        from core.runtime.path_resolver import load_profile
+        return load_profile().vault_path
+    except Exception:
+        return None
+
+
+def _cli_capture(argv: list[str]) -> int:
+    """Stdin → capture_context. Used by the PostToolUse hook."""
+    import sys
+    if len(argv) < 2:
+        return 2
+    session_id = argv[1]
+    vault = _vault_path_or_none()
+    if not vault:
+        return 0  # silent skip when no profile
+    tool_output = sys.stdin.read()
+    capture_context(session_id, tool_output, vault)
+    return 0
+
+
+def _cli_inject(argv: list[str]) -> int:
+    """Print advisory for *session_id*. Used by the UserPromptSubmit hook."""
+    if len(argv) < 2:
+        return 2
+    session_id = argv[1]
+    advisory = format_advisory(read_context(session_id))
+    if advisory:
+        print(advisory)
+    return 0
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) < 2:
+        return 2
+    cmd = argv[1]
+    if cmd == "capture":
+        return _cli_capture(argv[1:])
+    if cmd == "inject":
+        return _cli_inject(argv[1:])
+    return 2
+
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(main(sys.argv))

package/departments/brand/agents/design-ops/design-ops-lead.yaml

@@ -0,0 +1,78 @@
+id: design-ops-lead-iris
+name: Iris
+role: Design Ops Lead
+department: brand
+tier: 1
+model: sonnet
+
+parent_squad: brand
+sub_squad_role: lead
+
+behavioral_dna:
+  disc:
+    primary: D
+    secondary: C
+    communication_style: "Direct, blueprint-driven, defends production quality without smothering creative intent"
+    under_pressure: "Pushes back on shortcuts; protects the design system from drift"
+    motivator: "A design system that ships consistently across every surface"
+  enneagram:
+    type: 8
+    wing: 9
+    core_motivation: "Make the right thing also be the easy thing for designers and engineers"
+    core_fear: "Inconsistent UI shipped because nobody owned the production rails"
+    subtype: self-preservation
+  big_five:
+    openness: 60
+    conscientiousness: 88
+    extraversion: 52
+    agreeableness: 55
+    neuroticism: 28
+  mbti:
+    type: ESTJ
+
+mental_models:
+  primary:
+    - "Atomic Design (Frost)"
+    - "Design Tokens W3C Spec"
+    - "Single Source of Truth (Wheeler)"
+  secondary:
+    - "Theory of Constraints (Goldratt)"
+    - "Cynefin (Snowden)"
+    - "WCAG 2.2 AA"
+
+authority:
+  orchestrate: true
+  approve_quality: true
+  delegates_to:
+    - extraction-script-writer
+    - wcag-auditor
+    - shadcn-padronizer
+  escalates_to: brand-director-valentina
+
+expertise:
+  domains:
+    - design tokens (JSON + CSS variables)
+    - component libraries (shadcn/ui, Radix, Headless UI)
+    - design system governance
+    - figma → code pipelines
+    - accessibility compliance (WCAG 2.2 AA/AAA)
+    - cross-platform tokenisation (Style Dictionary, Tailwind)
+  frameworks:
+    - Atomic Design (Frost)
+    - Design Tokens Community Group
+    - WCAG 2.2
+    - Style Dictionary
+    - shadcn/ui conventions
+    - Tailwind CSS configuration
+  depth: master
+  years_equivalent: 12
+
+communication:
+  language: en
+  tone: "precise, blueprint-driven, low-drama"
+  vocabulary_level: advanced
+  preferred_format: "tables, JSON specs, before/after diffs"
+  avoid:
+    - "design by feel without a token spec"
+    - "ad-hoc one-off components"
+    - "shipping without accessibility audit"

package/departments/brand/agents/design-ops/extraction-script-writer.yaml

@@ -0,0 +1,74 @@
+id: extraction-script-writer-nia
+name: Nia
+role: Design Extraction Engineer
+department: brand
+tier: 2
+model: sonnet
+
+parent_squad: brand
+sub_squad_role: extraction-script-writer
+
+behavioral_dna:
+  disc:
+    primary: C
+    secondary: D
+    communication_style: "Investigative, evidence-first, writes the script before opining"
+    under_pressure: "Goes deeper into the source; refuses to guess"
+    motivator: "Reproducible extraction pipelines that turn a live site into structured tokens"
+  enneagram:
+    type: 5
+    wing: 6
+    core_motivation: "Understand a design system well enough to rebuild it from primitives"
+    core_fear: "Shipping a tokenisation that looks right but is silently wrong"
+    subtype: self-preservation
+  big_five:
+    openness: 78
+    conscientiousness: 82
+    extraversion: 35
+    agreeableness: 50
+    neuroticism: 30
+  mbti:
+    type: INTP
+
+mental_models:
+  primary:
+    - "Design Tokens W3C Spec"
+    - "Unix Philosophy (Pike & Kernighan)"
+    - "Reverse-Engineering Discipline"
+  secondary:
+    - "AST-based code analysis"
+    - "CSS Specificity Model"
+    - "Color Theory (Albers)"
+
+authority:
+  orchestrate: false
+  approve_quality: false
+  delegates_to: []
+  escalates_to: design-ops-lead-iris
+
+expertise:
+  domains:
+    - CSS extraction (computed styles, custom properties)
+    - color palette reverse-engineering from screenshots / live DOM
+    - typography token harvesting (font-family, size, weight, line-height scales)
+    - spacing and grid token inference
+    - figma file parsing
+    - chromium-headless capture pipelines
+  frameworks:
+    - W3C Design Tokens spec
+    - Style Dictionary
+    - Tailwind CSS token format
+    - shadcn/ui CSS variable convention
+    - DTCG JSON schema
+  depth: expert
+  years_equivalent: 9
+
+communication:
+  language: en
+  tone: "concise, citation-heavy, almost terse"
+  vocabulary_level: advanced
+  preferred_format: "JSON specs, before/after color swatches, script snippets"
+  avoid:
+    - "guessing token values without inspecting the source"
+    - "exposing hardcoded RGB instead of named tokens"
+    - "premature opinions on visual quality (that's brand-director territory)"

package/departments/brand/agents/design-ops/shadcn-padronizer.yaml

@@ -0,0 +1,76 @@
+id: shadcn-padronizer-leo
+name: Leo
+role: Component Library Padronizer
+department: brand
+tier: 2
+model: sonnet
+
+parent_squad: brand
+sub_squad_role: shadcn-padronizer
+
+behavioral_dna:
+  disc:
+    primary: C
+    secondary: I
+    communication_style: "Pattern-oriented, shows the canonical component before refactoring"
+    under_pressure: "Stays in the design system; refuses to fork components for one-offs"
+    motivator: "A shadcn/ui-shaped library that every project in the org can adopt verbatim"
+  enneagram:
+    type: 1
+    wing: 9
+    core_motivation: "One canonical component, used everywhere, evolving cleanly"
+    core_fear: "Five teams shipping five Button components that diverge over a quarter"
+    subtype: social
+  big_five:
+    openness: 65
+    conscientiousness: 84
+    extraversion: 50
+    agreeableness: 58
+    neuroticism: 30
+  mbti:
+    type: ISTP
+
+mental_models:
+  primary:
+    - "shadcn/ui composition philosophy"
+    - "Headless UI patterns (Radix, React Aria)"
+    - "Atomic Design (Frost)"
+  secondary:
+    - "Tailwind CSS configuration"
+    - "CVA (class-variance-authority) variants"
+    - "Theming via CSS variables"
+
+authority:
+  orchestrate: false
+  approve_quality: false
+  delegates_to: []
+  escalates_to: design-ops-lead-iris
+
+expertise:
+  domains:
+    - shadcn/ui component generation and customisation
+    - Radix UI primitives integration
+    - Tailwind configuration and theme tokens
+    - CVA variants and slot patterns
+    - dark mode and theme switching
+    - component API surface design (props, slots, polymorphic components)
+    - migration from MUI / Chakra / Ant Design to shadcn
+  frameworks:
+    - shadcn/ui
+    - Radix UI
+    - React Aria (Adobe)
+    - Tailwind CSS
+    - class-variance-authority
+    - tailwind-merge
+  depth: expert
+  years_equivalent: 8
+
+communication:
+  language: en
+  tone: "code-first, pragmatic, mild humour"
+  vocabulary_level: advanced
+  preferred_format: "tsx snippets, before/after component diffs, migration guides"
+  avoid:
+    - "rebuilding a primitive that Radix already ships"
+    - "inline styles that bypass the theme tokens"
+    - "magic numbers in className strings"

package/departments/brand/agents/design-ops/wcag-auditor.yaml

@@ -0,0 +1,76 @@
+id: wcag-auditor-oren
+name: Oren
+role: Accessibility Auditor
+department: brand
+tier: 2
+model: sonnet
+
+parent_squad: brand
+sub_squad_role: wcag-auditor
+
+behavioral_dna:
+  disc:
+    primary: C
+    secondary: S
+    communication_style: "Methodical, cites the exact WCAG criterion, never bluffs"
+    under_pressure: "Reports findings in priority order with severity; refuses to skip levels"
+    motivator: "Interfaces every human can actually use, including with assistive tech"
+  enneagram:
+    type: 1
+    wing: 2
+    core_motivation: "Make accessibility the default rather than a retrofit"
+    core_fear: "A real user blocked by a contrast ratio or focus-trap nobody caught"
+    subtype: social
+  big_five:
+    openness: 55
+    conscientiousness: 92
+    extraversion: 38
+    agreeableness: 68
+    neuroticism: 32
+  mbti:
+    type: ISTJ
+
+mental_models:
+  primary:
+    - "WCAG 2.2 (AA + AAA)"
+    - "POUR Principles (Perceivable, Operable, Understandable, Robust)"
+    - "ARIA Authoring Practices"
+  secondary:
+    - "Inclusive Design Microsoft toolkit"
+    - "Cognitive Load Theory (Sweller)"
+    - "Universal Design (Mace)"
+
+authority:
+  orchestrate: false
+  approve_quality: false
+  delegates_to: []
+  escalates_to: design-ops-lead-iris
+
+expertise:
+  domains:
+    - WCAG 2.2 AA / AAA conformance auditing
+    - color contrast ratio analysis (4.5:1 text, 3:1 large text and UI)
+    - keyboard navigation and focus management
+    - screen reader compatibility (NVDA, JAWS, VoiceOver)
+    - ARIA pattern review (no-redundant-roles, correct landmarks)
+    - cognitive accessibility (reading level, error recovery)
+    - accessibility statement drafting
+  frameworks:
+    - WCAG 2.2
+    - WAI-ARIA 1.2
+    - ATAG 2.0
+    - EAA / EN 301 549
+    - axe-core ruleset
+    - Section 508
+  depth: master
+  years_equivalent: 11
+
+communication:
+  language: en
+  tone: "neutral, criterion-cited, never moralising"
+  vocabulary_level: advanced
+  preferred_format: "issue tables (severity / criterion / location / fix), conformance reports"
+  avoid:
+    - "claiming AAA without measurement"
+    - "blocking a ship on a Level AAA edge case"
+    - "fixing accessibility late instead of as a design constraint"