arkaos 2.22.1 → 2.28.0

package/arka/skills/research/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: arka-research
+description: >
+  Fan-out research workflow. Spawns 5 parallel subagents — Perplexity,
+  Exa AI, Context7, Firecrawl, XMCP — synthesises their findings into
+  a single report, and writes a Knowledge Base note to the Obsidian
+  vault. Inspired by the multi-source research pattern surfaced in the
+  2026-05-13 Orgo podcast (Nick Saraev): "I tell Claude Code, hey,
+  spawn five sub-agents — one for Perplexity, one for Exa, one for
+  Context7, one for Firecrawl, one for XMCP — and we get best practices."
+allowed-tools: [Agent, Read, Write, mcp__obsidian__search_notes]
+---
+
+# /arka research — one prompt, five parallel sources
+
+> Companion to `/arka bootstrap-agent`. Where bootstrap-agent generates
+> capability, this skill generates *knowledge*.
+
+## Usage
+
+```
+/arka research <topic>
+```
+
+`<topic>` is a free-form research question. Examples:
+
+- `/arka research "Hermes agent setup with Telegram gateway"`
+- `/arka research "Mistral Medium 3.5 cost vs Sonnet 4.6"`
+- `/arka research "AIOX Squad de Saúde framework"`
+
+## Sources fanned out
+
+| Subagent | MCP / tool | Strength |
+| --- | --- | --- |
+| Perplexity | `mcp__perplexity__ask` | Real-time web with citations |
+| Exa AI | `mcp__exa__search` | Semantic vector search across the web |
+| Context7 | `mcp__context7__query-docs` | Up-to-date official library docs |
+| Firecrawl | `mcp__firecrawl__firecrawl_scrape` | Site-specific deep scraping |
+| XMCP | `mcp__x__search` | X / Twitter conversations and threads |
+
+If any MCP is not registered in `.mcp.json`, that subagent is skipped
+with a `[arka:source-skipped]` note in the report. KB-first protocol
+still applies — Obsidian search runs before any external call.
+
+## Workflow
+
+```
+1. KB-first: search Obsidian vault for prior notes on the topic.
+   If high-confidence matches exist, the report cites them first
+   and asks the user whether external research is still needed.
+
+2. Fan out 5 subagents in parallel via the Agent tool. Each gets
+   the same topic, returns a focused short brief (≤500 words).
+
+3. Critic synthesis (Tier 0 reviewer, opus): collapses overlap,
+   surfaces contradictions, ranks sources by weight (official docs >
+   recent community threads > older articles).
+
+4. Synthesis report saved to:
+     ${VAULT_PATH}/Knowledge Base/Research/<YYYY-MM-DD>-<slug>.md
+   with full citations and a "where to go next" section.
+
+5. Returns a compact summary to the user (the full report links to
+   the Obsidian note).
+```
+
+## Output shape
+
+```markdown
+---
+title: <topic>
+date: <YYYY-MM-DD>
+sources: [perplexity, exa, context7, firecrawl, xmcp]
+status: synthesised
+tags: [research, <topic-tag>]
+---
+
+# <Topic>
+
+## TL;DR
+<3-bullet summary>
+
+## Findings by source
+### Perplexity
+...
+### Exa AI
+...
+(etc.)
+
+## Synthesis
+<contradictions resolved, ranked by source weight>
+
+## Next steps
+<2-3 follow-up questions or actions>
+```
+
+## Cost & budget
+
+This is a heavy operation — 5 parallel LLM calls plus a synthesis call.
+A typical run consumes 3-8k tokens. The `/arka costs` skill tracks the
+spend and the `[arka:warn]` token-hygiene hook flags excessive use.
+
+## Boundaries
+
+- Read-only: this skill never modifies code or configuration. It only
+  writes to the Obsidian Knowledge Base.
+- KB-first: always check the vault first. Many topics already have
+  notes from prior Dreaming / Research sessions.
+- No external research without the user asking — agents do not
+  proactively fan out unless `/arka research` is invoked.
+
+## Cross-references
+
+- Source pattern: 2026-05-13 Orgo podcast
+- Related: `/arka forge` (planning, not research)
+- Related: `/kb research` (Clara, knowledge management)
+- Related: `/arka bootstrap-agent` (capability-from-research)

package/config/cognition/prompts/dreaming.md

@@ -8,7 +8,7 @@ You are ArkaOS performing your nightly Dreaming session. Your job is to review e
 - Read any file from any project
 - Read git logs and diffs
 - Search the web (WebSearch, Firecrawl)
-- Write to Obsidian vault at ~/Documents/Personal/Projects/WizardingCode Internal/ArkaOS/
+- Write to Obsidian vault at ${VAULT_PATH}/Projects/ArkaOS/
 - Write to ~/.arkaos/ (captures, insights, logs, knowledge)
 - Use browser for research
 - Read online documentation
@@ -81,7 +81,7 @@ from core.cognition.memory.writer import DualWriter
 
 writer = DualWriter(
     obsidian_base=os.path.expanduser(
-        "~/Documents/Personal/Projects/WizardingCode Internal/ArkaOS/Knowledge Base"
+        "${VAULT_PATH}/Projects/ArkaOS/Knowledge Base"
     ),
     vector_db_path=os.path.expanduser("~/.arkaos/knowledge.db"),
 )
@@ -113,7 +113,7 @@ Use `DualWriter.write()` for each KnowledgeEntry. This automatically writes to b
 ## Phase 6: Report + Evolution Metrics
 
 Write daily report to Obsidian:
-`~/Documents/Personal/Projects/WizardingCode Internal/ArkaOS/Dreaming/YYYY-MM-DD.md`
+`${VAULT_PATH}/Projects/ArkaOS/Dreaming/YYYY-MM-DD.md`
 
 Format:
 ```markdown

package/config/cognition/prompts/research.md

@@ -8,7 +8,7 @@ You are ArkaOS performing your daily Research session. Your job is to stay curre
 - Read any file from any project
 - Read git logs
 - Search the web extensively (WebSearch, Firecrawl)
-- Write to Obsidian vault at ~/Documents/Personal/Projects/WizardingCode Internal/ArkaOS/
+- Write to Obsidian vault at ${VAULT_PATH}/Projects/ArkaOS/
 - Write to ~/.arkaos/ (insights, logs, knowledge, profiles)
 - Use browser for deep research
 - Read online documentation, blogs, changelogs, GitHub releases
@@ -94,7 +94,7 @@ from core.cognition.memory.writer import DualWriter
 
 writer = DualWriter(
     obsidian_base=os.path.expanduser(
-        "~/Documents/Personal/Projects/WizardingCode Internal/ArkaOS/Knowledge Base"
+        "${VAULT_PATH}/Projects/ArkaOS/Knowledge Base"
     ),
     vector_db_path=os.path.expanduser("~/.arkaos/knowledge.db"),
 )
@@ -114,7 +114,7 @@ writer.write(entry)
 ## Phase 5: Cross-Reference with Dreaming
 
 1. Read tonight's Dreaming report (if it exists):
-   `~/Documents/Personal/Projects/WizardingCode Internal/ArkaOS/Dreaming/YYYY-MM-DD.md`
+   `${VAULT_PATH}/Projects/ArkaOS/Dreaming/YYYY-MM-DD.md`
 
 2. Read pending insights from `~/.arkaos/insights.db`:
 ```python
@@ -145,7 +145,7 @@ store.save(insight)
 ## Phase 6: Intelligence Briefing
 
 Write daily briefing to Obsidian:
-`~/Documents/Personal/Projects/WizardingCode Internal/ArkaOS/Research/YYYY-MM-DD.md`
+`${VAULT_PATH}/Projects/ArkaOS/Research/YYYY-MM-DD.md`
 
 Format:
 ```markdown

package/config/constitution.yaml

@@ -135,6 +135,10 @@ enforcement_levels:
         rule: "All ecosystem skills must follow the standard 7-phase workflow defined in config/standards/ecosystem-workflow.md"
         enforcement: "Ecosystem SKILL.md files must reference or implement all 7 phases"
 
+      - id: sub-squad-hierarchy
+        rule: "Agents in a sub-squad MUST declare parent_squad (department slug) and sub_squad_role. Sub-squads inherit the parent department's authority chain; their lead escalates to the department squad lead, not directly to Tier 0."
+        enforcement: "Agent loader validates parent_squad + sub_squad_role coherence (sub_squad_role requires parent_squad). PR5 v2.27.0 introduced the pattern; AIOX Squad → Sub-Squad → Skills/Scripts is the reference architecture."
+
       - id: forge-persistence
         rule: "All forge plans (approved and rejected) must be persisted to Obsidian"
         enforcement: "persistence.py exports on status change; audit detects missing exports"

package/config/hooks/post-tool-use.sh

@@ -391,6 +391,23 @@ if not match and all_deliverables:
   fi
 fi
 
+# ─── Cognitive layer capture (PR4 v2.26.0 hooks-as-retrieval) ────────────
+# Backgrounded so the hook returns immediately. The retrieval helper has
+# its own internal time caps (ripgrep ≤ 1s, Python fallback capped at 500
+# files) so a runaway extract can never block the next user prompt. We
+# disown so the child cannot zombie if the hook process exits first.
+if [ -n "$SESSION_ID_PTU" ] && [ -n "$TOOL_OUTPUT" ]; then
+  _ARKAOS_REPO=$(cat "$HOME/.arkaos/.repo-path" 2>/dev/null || echo "")
+  if [ -n "$_ARKAOS_REPO" ] && [ -d "$_ARKAOS_REPO" ]; then
+    (
+      PYTHONPATH="$_ARKAOS_REPO" python3 -m core.cognition.retrieval capture "$SESSION_ID_PTU" <<EOF >/dev/null 2>&1
+$TOOL_OUTPUT
+EOF
+    ) &
+    disown 2>/dev/null || true
+  fi
+fi
+
 # ─── Log Metrics ─────────────────────────────────────────────────────────
 _DURATION_MS=$(_hook_ms)
 METRICS_FILE="$HOME/.arkaos/hook-metrics.json"

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

@@ -356,9 +356,25 @@ sequential-validation, full-visibility, arka-supremacy."
   fi
 fi
 
+# ─── Cognitive context injection (PR4 v2.26.0 hooks-as-retrieval) ───────
+# Read the context cache populated by the previous PostToolUse turn and
+# inject any KB hits as an `[arka:context]` advisory. The Python helper
+# has internal TTL filtering (10 min) and returns empty when there is no
+# fresh cache, so this stays a no-op until the cognitive layer has data
+# to share.
+_ARKA_CONTEXT_HITS=""
+if [ -n "$SESSION_ID" ]; then
+  _ARKAOS_REPO=$(cat "$HOME/.arkaos/.repo-path" 2>/dev/null || echo "")
+  if [ -n "$_ARKAOS_REPO" ] && [ -d "$_ARKAOS_REPO" ]; then
+    _ARKA_CONTEXT_HITS=$(PYTHONPATH="$_ARKAOS_REPO" python3 -m core.cognition.retrieval inject "$SESSION_ID" 2>/dev/null)
+  fi
+fi
+
 # ─── Output ──────────────────────────────────────────────────────────────
 _OUT_CONTEXT="${_ARKA_GREETING:-}${_SYNC_NOTICE:-}${_ROUTE_REMINDER}${_WORKFLOW_DIRECTIVE} $python_result"
 [ -n "$_HYGIENE" ] && _OUT_CONTEXT="$_OUT_CONTEXT $_HYGIENE"
+[ -n "$_ARKA_CONTEXT_HITS" ] && _OUT_CONTEXT="$_OUT_CONTEXT
+$_ARKA_CONTEXT_HITS"
 # Escape for JSON
 _OUT_JSON=$(python3 -c "import json,sys; print(json.dumps(sys.stdin.read()))" <<< "$_OUT_CONTEXT" 2>/dev/null)
 if [ -n "$_OUT_JSON" ]; then
@@ -368,7 +384,12 @@ else
 fi
 
 # ─── Metrics ─────────────────────────────────────────────────────────────
+# Count @-mentions in the prompt for at_mention_frequency telemetry. Mirrors
+# the claude_code.at_mention OpenTelemetry event introduced in Claude Code
+# 2.1.122, but works on any version because we count from the same input
+# the hook already receives.
+at_mentions=$(printf '%s' "$user_input" | grep -oE '(^|[[:space:]])@[A-Za-z0-9_./-]+' | wc -l | tr -d ' ')
 elapsed=$(_hook_ms)
 if [ "$elapsed" -gt 0 ] 2>/dev/null; then
-  echo "{\"hook\":\"user-prompt-submit-v2\",\"ms\":$elapsed}" >> "$CACHE_DIR/hook-metrics.jsonl" 2>/dev/null
+  echo "{\"hook\":\"user-prompt-submit-v2\",\"ms\":$elapsed,\"at_mentions\":${at_mentions:-0}}" >> "$CACHE_DIR/hook-metrics.jsonl" 2>/dev/null
 fi

package/core/agents/loader.py

@@ -60,7 +60,10 @@ def load_all_agents(
     for agents_dir in search_dirs:
         if not agents_dir.is_dir():
             continue
-        for yaml_file in sorted(agents_dir.glob("*.yaml")):
+        # Recursive rglob picks up sub-squad subdirectories (e.g.
+        # departments/brand/agents/design-ops/*.yaml) per the v2.27.0
+        # Sub-Squad pattern. Sorted output keeps load order stable.
+        for yaml_file in sorted(agents_dir.rglob("*.yaml")):
             try:
                 agent = load_agent(yaml_file)
                 agents.append(agent)

package/core/agents/schema.py

@@ -273,6 +273,35 @@ class Agent(BaseModel):
         description="Claude model override for dispatch. Falls back to tier default when None.",
     )
 
+    parent_squad: Optional[str] = Field(
+        default=None,
+        description=(
+            "Slug of the parent squad when this agent belongs to a sub-squad. "
+            "Sub-squads are operational specialisations inside a department "
+            "(e.g. brand → design-ops). Optional and backwards-compatible: "
+            "agents without a parent_squad belong directly to their department."
+        ),
+    )
+
+    sub_squad_role: Optional[str] = Field(
+        default=None,
+        description=(
+            "Role within the sub-squad when parent_squad is set "
+            "(e.g. 'lead', 'extraction-script-writer', 'wcag-auditor'). "
+            "Inspired by the AIOX Squad → Sub-Squad pattern (KB note "
+            "AIOX Squads, April 30 2026 live)."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def validate_sub_squad_coherence(self) -> "Agent":
+        """sub_squad_role only makes sense when parent_squad is set."""
+        if self.sub_squad_role and not self.parent_squad:
+            raise ValueError(
+                "sub_squad_role requires parent_squad to be set"
+            )
+        return self
+
     @model_validator(mode="after")
     def auto_fill_memory_path(self) -> "Agent":
         if not self.memory_path:

package/core/cognition/capture/collector.py

@@ -7,13 +7,20 @@ from datetime import datetime, timezone
 
 from core.cognition.capture.store import CaptureStore
 from core.cognition.memory.schemas import RawCapture
+from core.runtime.path_resolver import ProfileMissingError, project_root_regex
+
+_FALLBACK_REGEX = re.compile(
+    r"((?:/Users|/home)/\S+/(?:Herd|Work|AIProjects|code|repos))[/\\]([^\s/\\]+)"
+)
 
 
 def _detect_project(digest: str) -> tuple[str, str]:
     """Try to detect project name and path from digest content."""
-    path_match = re.search(
-        r"(/Users/\S+/(?:Herd|Work|AIProjects)/([^\s/]+))", digest
-    )
+    try:
+        regex = project_root_regex()
+    except ProfileMissingError:
+        regex = _FALLBACK_REGEX
+    path_match = regex.search(digest)
     if path_match:
         return path_match.group(2).rstrip("/"), path_match.group(1).rstrip("/")
     return "unknown", os.getcwd()