arkaos 4.8.0 → 4.9.0

package/VERSION

@@ -1 +1 @@
-4.8.0
+4.9.0

package/arka/skills/research/SKILL.md

@@ -6,13 +6,13 @@ description: >
   single cited report, and writes a Knowledge Base note to the Obsidian
   vault. KB-first: Obsidian is searched before any external call.
   TRIGGER: "/arka research", "pesquisa sobre", "investiga",
-  "faz research", "research <topic>", "best practices for", "state of
-  the art", "o que se sabe sobre" — general, market, tooling, or KB
-  topics whose deliverable is a synthesised KB note.
+  "faz research", "research <topic>", "best practices for" non-code
+  topics, "state of the art", "o que se sabe sobre" — general, market,
+  tooling, or KB topics whose deliverable is a synthesised KB note.
   SKIP: dev-scoped technical research — library or framework evaluation,
-  "que lib uso", "which library/framework" —
-  /dev research (Lucas) wins; planning a task — arka-forge wins (Forge
-  plans, this skill informs).
+  "que lib uso", "which library/framework", best-practice questions
+  about implementation choices — dev/research (Lucas) wins; planning a
+  task — arka-forge wins.
 allowed-tools: [Agent, Read, Write, mcp__obsidian__search_notes]
 ---
 

package/config/disc-team-validator.sh

@@ -1,26 +1,26 @@
 #!/usr/bin/env bash
 # ============================================================================
 # ARKA OS — DISC Team Balance Validator
-# Reads agents-registry.json and validates team DISC distribution
+# Reads agents-registry-v2.json and validates team DISC distribution
 # ============================================================================
 set -e
 
 ARKA_OS="${ARKA_OS:-$HOME/.claude/skills/arka}"
 REPO_DIR="${REPO_DIR:-$(cat "$ARKA_OS/.repo-path" 2>/dev/null || echo "")}"
-REGISTRY="${REGISTRY:-$REPO_DIR/knowledge/agents-registry.json}"
+REGISTRY="${REGISTRY:-$REPO_DIR/knowledge/agents-registry-v2.json}"
 
 if [ ! -f "$REGISTRY" ]; then
-  echo "Error: agents-registry.json not found at $REGISTRY"
+  echo "Error: agents-registry-v2.json not found at $REGISTRY"
   exit 1
 fi
 
 command -v jq &>/dev/null || { echo "Error: jq is required."; exit 1; }
 
 # Read counts from registry
-D_COUNT=$(jq '.team_composition.by_disc_primary.D' "$REGISTRY")
-I_COUNT=$(jq '.team_composition.by_disc_primary.I' "$REGISTRY")
-S_COUNT=$(jq '.team_composition.by_disc_primary.S' "$REGISTRY")
-C_COUNT=$(jq '.team_composition.by_disc_primary.C' "$REGISTRY")
+D_COUNT=$(jq '._meta.disc_distribution.D' "$REGISTRY")
+I_COUNT=$(jq '._meta.disc_distribution.I' "$REGISTRY")
+S_COUNT=$(jq '._meta.disc_distribution.S' "$REGISTRY")
+C_COUNT=$(jq '._meta.disc_distribution.C' "$REGISTRY")
 TOTAL=$(( D_COUNT + I_COUNT + S_COUNT + C_COUNT ))
 
 # Calculate percentages

package/config/evals/dev.yaml

@@ -0,0 +1,28 @@
+# Dev department reference eval tasks (seed set).
+# Judged against expected_properties + QG verdict; see core/evals/schema.py.
+- id: dev-feature-auth-endpoint
+  department: dev
+  prompt: >
+    Implementa um endpoint de autenticação por token (login + refresh)
+    num serviço Laravel existente, com testes.
+  expected_properties:
+    - FormRequest valida credenciais (nunca validação inline no controller)
+    - Lógica em Service/Repository, controller fino
+    - Feature tests cobrem sucesso, credenciais inválidas e refresh expirado
+    - Nenhum segredo hardcoded; usa config/env
+  rubric: >
+    Rejeitar se os testes não correram (exit code em registo) ou se o
+    fluxo de refresh não invalida o token antigo.
+  tags: [backend, laravel, security-adjacent]
+
+- id: dev-refactor-n-plus-one
+  department: dev
+  prompt: >
+    Este listing de encomendas faz N+1 queries; corrige sem alterar o
+    contrato JSON da API.
+  expected_properties:
+    - Eager loading ou query única substitui o loop de queries
+    - Contrato de resposta byte-idêntico (teste de regressão prova-o)
+    - Query count coberto por teste (assertQueryCount ou equivalente)
+  rubric: Rejeitar qualquer alteração de schema de resposta.
+  tags: [backend, performance]

package/config/evals/finance.yaml

@@ -0,0 +1,28 @@
+# Finance department reference eval tasks (seed set).
+- id: fin-unit-economics-saas
+  department: finance
+  prompt: >
+    Calcula os unit economics de um SaaS com MRR 8000 EUR, 120 clientes,
+    churn mensal 3%, CAC 250 EUR e margem bruta 80%.
+  expected_properties:
+    - LTV derivado com fórmula explícita (ARPU, churn, margem)
+    - Rácio LTV/CAC calculado e interpretado contra o benchmark 3x
+    - Payback period em meses
+    - Aritmética verificável (números batem certo)
+  rubric: >
+    Rejeitar qualquer erro aritmético — o arkaos-not-yes-man aplica-se a
+    matemática impossível do próprio input.
+  tags: [unit-economics, saas]
+
+- id: fin-cashflow-13-weeks
+  department: finance
+  prompt: >
+    Constrói um forecast de cash flow a 13 semanas para uma agência com
+    3 clientes em retainer e folha salarial fixa.
+  expected_properties:
+    - Entradas por cliente com datas de recebimento realistas
+    - Saídas fixas e variáveis separadas
+    - Saldo semanal acumulado com semana crítica identificada
+    - Cenário pessimista (cliente atrasa 30 dias) incluído
+  rubric: Rejeitar forecast sem cenário de stress.
+  tags: [cashflow, forecast]

package/config/evals/kb.yaml

@@ -0,0 +1,26 @@
+# Knowledge department reference eval tasks (seed set).
+- id: kb-research-note-synthesis
+  department: kb
+  prompt: >
+    Pesquisa "estratégias de retry para APIs rate-limited" e produz uma
+    nota KB sintetizada com fontes.
+  expected_properties:
+    - KB consultada primeiro (citação [[wikilink]] ou gap declarado)
+    - Fontes externas citadas com claims atribuídos
+    - Nota com frontmatter YAML + wikilinks + estrutura Zettelkasten
+    - Síntese própria, não colagem de excertos
+  rubric: Rejeitar claims sem fonte ou nota sem ligações ao grafo.
+  tags: [research, zettelkasten]
+
+- id: kb-moc-reorganize
+  department: kb
+  prompt: >
+    Organiza 15 notas soltas sobre "pricing" num MOC (Map of Content)
+    coerente no vault.
+  expected_properties:
+    - MOC com agrupamento temático justificado
+    - Todas as 15 notas ligadas (nenhuma órfã)
+    - Hierarquia máxima de 2 níveis
+    - Notas duplicadas identificadas para merge
+  rubric: Rejeitar agrupamento alfabético ou sem lógica temática.
+  tags: [moc, organization]

package/config/evals/marketing.yaml

@@ -0,0 +1,28 @@
+# Marketing department reference eval tasks (seed set).
+- id: mkt-launch-campaign-plan
+  department: marketing
+  prompt: >
+    Desenha o plano de campanha de lançamento (4 semanas) para um
+    micro-SaaS B2B de gestão de inventário, orçamento 2000 EUR.
+  expected_properties:
+    - Estrutura AARRR explícita com métrica alvo por etapa
+    - Canais escolhidos justificados contra o ICP (não lista genérica)
+    - Orçamento alocado por canal soma 2000 EUR
+    - Calendário semanal com owners
+  rubric: >
+    Rejeitar clichés de AI copy e canais sem justificação de fit; o
+    framework citado tem de ser aplicado, não só nomeado.
+  tags: [gtm, aarrr, budget]
+
+- id: mkt-seo-content-brief
+  department: marketing
+  prompt: >
+    Cria um brief SEO para um artigo pilar sobre "supplier sync para
+    Shopify" com intenção de pesquisa comercial.
+  expected_properties:
+    - Keyword primária + secundárias com intenção classificada
+    - Outline H2/H3 cobre as perguntas do SERP
+    - Internal links e CTA definidos
+    - Meta title/description dentro dos limites de caracteres
+  rubric: Rejeitar keyword stuffing ou outline sem lógica de funil.
+  tags: [seo, content]

package/config/evals/strategy.yaml

@@ -0,0 +1,26 @@
+# Strategy department reference eval tasks (seed set).
+- id: strat-five-forces-entry
+  department: strategy
+  prompt: >
+    Avalia com Porter's Five Forces a entrada de um novo player no
+    mercado de ferramentas de orquestração de agentes AI.
+  expected_properties:
+    - As 5 forças analisadas com evidência específica do mercado, não genérica
+    - Intensidade classificada por força com justificação
+    - Conclusão acionável (entrar/não entrar/entrar com que moat)
+  rubric: >
+    Rejeitar análise que apenas define as forças sem as aplicar ao
+    mercado concreto.
+  tags: [porter, market-entry]
+
+- id: strat-moat-audit
+  department: strategy
+  prompt: >
+    Audita os moats de um produto dev-tools open-source com dashboard
+    pago, usando 7 Powers.
+  expected_properties:
+    - Cada power avaliada como presente/ausente/construível
+    - Pelo menos um trade-off identificado (ex. open-source vs counter-positioning)
+    - Recomendação priorizada de qual power investir primeiro
+  rubric: Rejeitar se citar 7 Powers sem mapear ao produto.
+  tags: [7-powers, moat]

package/core/agents/registry_gen.py

@@ -1,7 +1,9 @@
-"""Generate agents-registry.json from all agent YAML files.
+"""Generate agents-registry-v2.json from all agent YAML files.
 
-Scans departments/*/agents/*.yaml and produces a machine-readable
-registry with all agent metadata including behavioral DNA.
+Scans departments/*/agents/*.yaml and produces the single canonical
+machine-readable registry with all agent metadata including behavioral
+DNA. The legacy knowledge/agents-registry.json (v1) was removed —
+tests/python/test_registry_gen.py guards against its resurrection.
 """
 
 import json
@@ -12,7 +14,7 @@ from core.agents.loader import load_agent
 
 
 def generate_registry(departments_dir: str | Path, output_path: str | Path) -> dict:
-    """Generate agents-registry.json from YAML agent files.
+    """Generate agents-registry-v2.json from YAML agent files.
 
     Args:
         departments_dir: Path to departments/ directory.

package/core/evals/__init__.py

@@ -0,0 +1,19 @@
+"""Eval harness foundation (E2E audit v4.3.6 P2).
+
+Reference eval tasks per department (config/evals/*.yaml) plus the
+QG-verdict label log — the free labeled dataset every future eval run
+or local-model distillation consumes.
+"""
+
+from core.evals.schema import EvalTask, load_eval_tasks
+from core.evals.verdict_labels import (
+    load_verdict_labels,
+    record_verdict_label,
+)
+
+__all__ = [
+    "EvalTask",
+    "load_eval_tasks",
+    "load_verdict_labels",
+    "record_verdict_label",
+]

package/core/evals/schema.py

@@ -0,0 +1,54 @@
+"""Eval task schema and loader.
+
+Reference tasks live in ``config/evals/<department>.yaml`` — one YAML
+list per department, versioned with the repo so evals evolve with the
+agents they measure. See ADR 2026-07-09-evals-and-distillation.md.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, Field
+
+DEFAULT_EVALS_DIR = (
+    Path(__file__).resolve().parent.parent.parent / "config" / "evals"
+)
+
+
+class EvalTask(BaseModel):
+    """One reference task an agent/department run is judged against."""
+
+    id: str = Field(pattern=r"^[a-z0-9][a-z0-9-]*$")
+    department: str
+    prompt: str = Field(min_length=10)
+    expected_properties: list[str] = Field(
+        min_length=1,
+        description="Verifiable properties the deliverable must exhibit",
+    )
+    rubric: str = Field(
+        default="",
+        description="Free-text judging guidance beyond the properties",
+    )
+    tags: list[str] = Field(default_factory=list)
+
+
+def load_eval_tasks(evals_dir: Path | None = None) -> list[EvalTask]:
+    """Load every task from config/evals/*.yaml, validated.
+
+    Raises on schema violations or duplicate ids — a broken eval set
+    must fail loudly, not skew results silently.
+    """
+    base = evals_dir or DEFAULT_EVALS_DIR
+    tasks: list[EvalTask] = []
+    seen: set[str] = set()
+    for path in sorted(base.glob("*.yaml")):
+        raw = yaml.safe_load(path.read_text(encoding="utf-8")) or []
+        for item in raw:
+            task = EvalTask.model_validate(item)
+            if task.id in seen:
+                raise ValueError(f"duplicate eval task id: {task.id}")
+            seen.add(task.id)
+            tasks.append(task)
+    return tasks

package/core/evals/verdict_labels.py

@@ -0,0 +1,72 @@
+"""QG verdicts as free eval labels.
+
+Every Quality Gate review already produces a structured ``QGVerdict``
+(APPROVED/REJECTED + blockers + evidence summary). Persisting them turns
+each review into a labeled example — the training/eval signal the E2E
+audit called "labels gratuitos". Append-only JSONL, same conventions as
+the other ``~/.arkaos/telemetry`` writers: never raises, fcntl advisory
+lock via ``llm_cost_telemetry._locked_append`` (QG reviews run as
+parallel subagents and verdict lines far exceed atomic-write sizes, so
+unlocked appends could interleave and corrupt the label corpus),
+``ARKA_QG_LABELS_PATH`` override for tests.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from core.governance.qg_verdict import QGVerdict
+from core.runtime.llm_cost_telemetry import _locked_append
+
+DEFAULT_LABELS_PATH = (
+    Path.home() / ".arkaos" / "telemetry" / "qg-verdicts.jsonl"
+)
+
+
+def _labels_path() -> Path:
+    override = os.environ.get("ARKA_QG_LABELS_PATH", "").strip()
+    return Path(override) if override else DEFAULT_LABELS_PATH
+
+
+def record_verdict_label(
+    verdict: QGVerdict,
+    deliverable: str = "",
+    department: str = "",
+    eval_task_id: str = "",
+    session_id: str = "",
+) -> None:
+    """Append one labeled QG example. Never raises (telemetry contract)."""
+    try:
+        entry: dict[str, Any] = {
+            "ts": datetime.now(timezone.utc).isoformat(),
+            "deliverable": str(deliverable or ""),
+            "department": str(department or ""),
+            "eval_task_id": str(eval_task_id or ""),
+            "session_id": str(session_id or ""),
+            **verdict.model_dump(),
+        }
+        with _locked_append(_labels_path()) as fh:
+            fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
+    except Exception:  # noqa: BLE001 — telemetry must never raise
+        return
+
+
+def load_verdict_labels(path: Path | None = None) -> list[dict[str, Any]]:
+    """Read all labeled examples; malformed lines are skipped."""
+    target = path or _labels_path()
+    if not target.exists():
+        return []
+    out: list[dict[str, Any]] = []
+    for line in target.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            out.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    return out

package/core/runtime/llm_cost_telemetry.py

@@ -232,6 +232,16 @@ def _load_slice(
     return kept, corrupt
 
 
+def _is_fallback_diagnostic(entry: dict[str, Any]) -> bool:
+    """Provider-fallback rows carry the fallback REASON in the model field
+    (_log_fallback in llm_provider.py: model='unavailable'/'selected').
+    They belong in the by-provider view (degraded chains) but leak bogus
+    zero-token rows into any model-keyed breakdown. Totals and by_provider
+    keep counting them, so sum(by_model[*].call_count) < call_count when
+    fallbacks occurred — intentional, not a reconciliation bug."""
+    return str(entry.get("provider") or "").startswith("fallback:")
+
+
 def _group(entries: list[dict[str, Any]], key: str) -> dict[str, dict[str, Any]]:
     out: dict[str, dict[str, Any]] = {}
     for entry in entries:
@@ -298,7 +308,9 @@ def summarise(
         cache_hit_rate=finalised["cache_hit_rate"],
         call_count=finalised["call_count"],
         by_provider=_group(entries, "provider"),
-        by_model=_group(entries, "model"),
+        by_model=_group(
+            [e for e in entries if not _is_fallback_diagnostic(e)], "model"
+        ),
         by_category=_group(entries, "category"),
         by_session=sessions,
         advisories=_build_advisories(sessions, advisory_threshold_usd),

package/core/synapse/engine.py

@@ -118,6 +118,12 @@ class SynapseEngine:
                 (ctx.user_input or "").encode("utf-8", "replace")
             ).hexdigest()[:12]
             cache_key += f":{digest}"
+        if getattr(layer, "session_sensitive", False):
+            # Session-sensitive layers (KB retrieval) must recompute per
+            # session: a cross-session cache hit would skip their
+            # per-session side effects (KBSessionCache.store).
+            session_id = (ctx.extra or {}).get("session_id", "default")
+            cache_key += f":{session_id}"
 
         # Check cache
         if layer.cache_ttl > 0:

package/core/synapse/layers.py

@@ -86,6 +86,19 @@ class Layer(ABC):
         """
         return False
 
+    @property
+    def session_sensitive(self) -> bool:
+        """True when compute() has per-session side effects or output.
+
+        Session-sensitive layers get ctx.extra['session_id'] added to
+        their cache key — without it, a cache hit from one session
+        suppresses compute() for a concurrent session in the same cwd,
+        skipping that session's side effects (found 2026-07-09: L3.5's
+        KBSessionCache.store() never ran for the second session, so its
+        KB-injected state and overlap markers belonged to the first).
+        """
+        return False
+
     @property
     def priority(self) -> int:
         """Layer priority (lower = computed first)."""
@@ -546,6 +559,10 @@ class KnowledgeRetrievalLayer(Layer):
     def input_sensitive(self) -> bool:
         return True
 
+    @property
+    def session_sensitive(self) -> bool:
+        return True
+
     @property
     def cache_ttl(self) -> int:
         return 30

package/departments/dev/skills/research/SKILL.md

@@ -12,8 +12,9 @@ description: >
   adding a new dependency or committing to an architecture-relevant
   library.
   SKIP: general, market, or knowledge-base research whose deliverable
-  is an Obsidian KB note — arka-research (/arka research, 5-source
-  fan-out) wins; requirements definition — arka-dev-spec wins.
+  is an Obsidian KB note, including "best practices for" a non-code
+  topic — arka-research (/arka research, 5-source fan-out) wins;
+  requirements definition — arka-dev-spec wins.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 

package/knowledge/commands-registry-v2.json

@@ -1,8 +1,8 @@
 {
   "_meta": {
     "version": "2.0.0",
-    "generated": "2026-04-04T22:56:22.122832",
-    "total_commands": 216,
+    "generated": "2026-07-09T15:04:23.205671",
+    "total_commands": 211,
     "generator": "core/registry/generator.py",
     "departments": {
       "brand": 12,
@@ -21,7 +21,7 @@
       "saas": 14,
       "sales": 10,
       "strategy": 10,
-      "arka": 24
+      "arka": 19
     }
   },
   "commands": [
@@ -3587,237 +3587,187 @@
       "id": "arka-status",
       "command": "/arka status",
       "department": "arka",
-      "description": "System status (version, departments, agents, active projects)",
+      "description": "System status (version, departments, agents, active projects). Includes **LLM costs (24h)** section: top-line cost + cache hit rate + call count from `core.runtime.llm_cost_telemetry.summarise(period=\"today\")`. Also includes **Enforcement (24h)** section: total calls, block rate, top blocked tools/reasons from `core.governance.enforcement_telemetry.summarise(period=\"today\")` (PR19 v2.41.0). Plus **Reorganization (today)** section: today's proposal path + artifact count from `core.cognition.reorganizer_scheduler.status_summary()` (PR24 v2.46.0). Plus **Model routing** section: gateway live/off + resolved per-slot routes + served counts from `core.runtime.model_routing_check.status_summary()`. Plus **MCP usage (24h)** section: total calls + servers in use + top servers from `core.runtime.mcp_telemetry.summarise(period=\"today\")`.",
       "keywords": [],
       "tier": 3,
       "modifies_code": false,
       "requires_branch": false
     },
     {
-      "id": "arka-standup",
-      "command": "/arka standup",
+      "id": "arka-costs-[period]",
+      "command": "/arka costs [period]",
       "department": "arka",
-      "description": "Daily standup (projects, priorities, blockers, updates)",
+      "description": "LLM cost visibility — aggregates telemetry by day/week/month/all, with top expensive sessions. See `arka/skills/costs/SKILL.md`. Shells out to `~/.arkaos/bin/arka-py -m core.runtime.llm_cost_telemetry_cli <period>`.",
       "keywords": [],
       "tier": 3,
       "modifies_code": false,
       "requires_branch": false
     },
     {
-      "id": "arka-monitor",
-      "command": "/arka monitor",
+      "id": "arka-enforcement-[period]",
+      "command": "/arka enforcement [period]",
       "department": "arka",
-      "description": "System health monitoring",
+      "description": "Enforcement compliance — aggregates flow-marker enforcement telemetry by day/week/month/all. Shows block rate, top blocked tools, top reasons. Shells out to `~/.arkaos/bin/arka-py -m core.governance.enforcement_telemetry_cli <period>`.",
       "keywords": [],
       "tier": 3,
       "modifies_code": false,
       "requires_branch": false
     },
     {
-      "id": "arka-onboard",
-      "command": "/arka onboard <path>",
+      "id": "arka-mcps-[period]",
+      "command": "/arka mcps [period]",
       "department": "arka",
-      "description": "Onboard an existing project into ArkaOS",
+      "description": "MCP usage — aggregates the PostToolUse MCP telemetry (`~/.arkaos/telemetry/mcp-usage.jsonl`) by day/week/month/all. Shows total calls, servers in use, top servers and top tools. Shells out to `~/.arkaos/bin/arka-py -m core.runtime.mcp_telemetry_cli <period>`.",
       "keywords": [],
       "tier": 3,
       "modifies_code": false,
       "requires_branch": false
     },
     {
-      "id": "arka-help",
-      "command": "/arka help",
+      "id": "arka-compliance-[period]",
+      "command": "/arka compliance [period]",
       "department": "arka",
-      "description": "List all department commands",
+      "description": "Behavior compliance summary (PR29 v2.48.0) — aggregates stop-hook telemetry by day/week/month/all. Shows rates for the four contracts: closing marker, `[arka:meta]` tag, KB citation pass, sycophancy clean. Shells out to `~/.arkaos/bin/arka-py -m core.governance.compliance_telemetry_cli <period>`.",
       "keywords": [],
       "tier": 3,
       "modifies_code": false,
       "requires_branch": false
     },
     {
-      "id": "arka-setup",
-      "command": "/arka setup",
+      "id": "arka-reorganize-[--since-days-N]",
+      "command": "/arka reorganize [--since-days N]",
       "department": "arka",
-      "description": "Interactive profile setup (name, company, role, objectives)",
+      "description": "Dreaming → Agent reorganizer. Aggregates recent KB pattern/anti-pattern/lesson artifacts (default last 7 days) into a markdown proposal at `~/.arkaos/reorganize-proposals/<date>.md`. **Propose-only** — never modifies agent YAMLs. Sanitizes client identifiers from titles and body excerpts; drops `tags:` field entirely to prevent project-name leaks. **Auto-fires on session start when today's proposal is missing** (PR24 v2.46.0 stale-aware trigger, 30s timeout, background). Shells out to `~/.arkaos/bin/arka-py -m core.cognition.reorganizer_cli [--since-days N] [--dry-run]`.",
       "keywords": [],
       "tier": 3,
       "modifies_code": false,
       "requires_branch": false
     },
     {
-      "id": "arka-conclave",
-      "command": "/arka conclave",
-      "department": "arka",
-      "description": "Activate personal AI advisory board (The Conclave)",
-      "keywords": [],
-      "tier": 3,
-      "modifies_code": false,
-      "requires_branch": false
-    },
-    {
-      "id": "do",
-      "command": "/do <description>",
-      "department": "arka",
-      "description": "Universal routing — natural language to department command",
-      "keywords": [],
-      "tier": 3,
-      "modifies_code": false,
-      "requires_branch": false
-    },
-    {
-      "id": "dev",
-      "command": "/dev",
-      "department": "arka",
-      "description": "Development",
-      "keywords": [],
-      "tier": 3,
-      "modifies_code": false,
-      "requires_branch": false
-    },
-    {
-      "id": "mkt",
-      "command": "/mkt",
-      "department": "arka",
-      "description": "Marketing & Growth",
-      "keywords": [],
-      "tier": 3,
-      "modifies_code": false,
-      "requires_branch": false
-    },
-    {
-      "id": "brand",
-      "command": "/brand",
-      "department": "arka",
-      "description": "Brand & Design",
-      "keywords": [],
-      "tier": 3,
-      "modifies_code": false,
-      "requires_branch": false
-    },
-    {
-      "id": "fin",
-      "command": "/fin",
+      "id": "arka-standup",
+      "command": "/arka standup",
       "department": "arka",
-      "description": "Finance & Investment",
+      "description": "Daily standup (projects, priorities, blockers, updates)",
       "keywords": [],
       "tier": 3,
       "modifies_code": false,
       "requires_branch": false
     },
     {
-      "id": "strat",
-      "command": "/strat",
+      "id": "arka-monitor",
+      "command": "/arka monitor",
       "department": "arka",
-      "description": "Strategy & Innovation",
+      "description": "System health monitoring",
       "keywords": [],
       "tier": 3,
       "modifies_code": false,
       "requires_branch": false
     },
     {
-      "id": "ecom",
-      "command": "/ecom",
+      "id": "arka-onboard",
+      "command": "/arka onboard <path>",
       "department": "arka",
-      "description": "E-Commerce",
+      "description": "Onboard an existing project into ArkaOS",
       "keywords": [],
       "tier": 3,
       "modifies_code": false,
       "requires_branch": false
     },
     {
-      "id": "kb",
-      "command": "/kb",
+      "id": "arka-help",
+      "command": "/arka help",
       "department": "arka",
-      "description": "Knowledge Management",
+      "description": "List all department commands",
       "keywords": [],
       "tier": 3,
       "modifies_code": false,
       "requires_branch": false
     },
     {
-      "id": "ops",
-      "command": "/ops",
+      "id": "arka-setup",
+      "command": "/arka setup",
       "department": "arka",
-      "description": "Operations & Automation",
+      "description": "Interactive profile setup (name, company, role, objectives)",
       "keywords": [],
       "tier": 3,
       "modifies_code": false,
       "requires_branch": false
     },
     {
-      "id": "pm",
-      "command": "/pm",
+      "id": "arka-conclave",
+      "command": "/arka conclave",
       "department": "arka",
-      "description": "Project Management",
+      "description": "Activate personal AI advisory board (The Conclave)",
       "keywords": [],
       "tier": 3,
       "modifies_code": false,
       "requires_branch": false
     },
     {
-      "id": "saas",
-      "command": "/saas",
+      "id": "arka-dashboard",
+      "command": "/arka dashboard",
       "department": "arka",
-      "description": "SaaS & Micro-SaaS",
+      "description": "Open monitoring dashboard (localhost:3333)",
       "keywords": [],
       "tier": 3,
       "modifies_code": false,
       "requires_branch": false
     },
     {
-      "id": "landing",
-      "command": "/landing",
+      "id": "arka-index",
+      "command": "/arka index",
       "department": "arka",
-      "description": "Landing Pages & Funnels",
+      "description": "Index Obsidian vault into knowledge base",
       "keywords": [],
       "tier": 3,
       "modifies_code": false,
       "requires_branch": false
     },
     {
-      "id": "content",
-      "command": "/content",
+      "id": "arka-search",
+      "command": "/arka search <query>",
       "department": "arka",
-      "description": "Content & Viralization",
+      "description": "Semantic search in knowledge base",
       "keywords": [],
       "tier": 3,
       "modifies_code": false,
       "requires_branch": false
     },
     {
-      "id": "community",
-      "command": "/community",
+      "id": "arka-keys",
+      "command": "/arka keys",
       "department": "arka",
-      "description": "Communities & Groups",
+      "description": "Manage API keys (OpenAI, Google, fal.ai)",
       "keywords": [],
       "tier": 3,
       "modifies_code": false,
       "requires_branch": false
     },
     {
-      "id": "sales",
-      "command": "/sales",
+      "id": "arka-personas",
+      "command": "/arka personas",
       "department": "arka",
-      "description": "Sales & Negotiation",
+      "description": "Manage AI personas (create, clone to agent)",
       "keywords": [],
       "tier": 3,
       "modifies_code": false,
       "requires_branch": false
     },
     {
-      "id": "lead",
-      "command": "/lead",
+      "id": "arka-resume",
+      "command": "/arka resume <PR_URL>",
       "department": "arka",
-      "description": "Leadership & People",
+      "description": "Re-enter the Claude Code session that produced a PR (GitHub / GitLab / Bitbucket). Wraps the native `/resume` from Claude Code 2.1.122+. Useful with `arka-dev-spec` and `arka-release` archaeology.",
       "keywords": [],
       "tier": 3,
       "modifies_code": false,
       "requires_branch": false
     },
     {
-      "id": "org",
-      "command": "/org",
+      "id": "do",
+      "command": "/do <description>",
       "department": "arka",
-      "description": "Organization & Teams",
+      "description": "Universal routing — natural language to department command",
       "keywords": [],
       "tier": 3,
       "modifies_code": false,

package/knowledge/commands-registry.json.bak

@@ -1,7 +1,7 @@
 {
   "_meta": {
     "version": "1.0.0",
-    "generated": "2026-07-09T01:34:18Z",
+    "generated": "2026-07-09T14:15:06Z",
     "total_commands": 262,
     "generator": "bin/arka-registry-gen"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "4.8.0"
+version = "4.9.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}

package/scripts/tools/prompt_surface_benchmark.py

@@ -0,0 +1,144 @@
+"""Prompt-surface token benchmark (v4.1 Evidence Reform open item).
+
+Measures the UserPromptSubmit hook's injected context (additionalContext)
+across a canonical prompt set, optionally comparing the working tree
+against another git ref (extracted via `git archive`, no worktrees).
+
+Token estimate: bytes / 4 — the same coarse heuristic the Synapse layers
+use (`tokens_est`); good enough for a reduction ratio, not billing.
+
+Usage:
+    arka-py scripts/tools/prompt_surface_benchmark.py [--ref v4.0.2] [--json]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+import tarfile
+import tempfile
+from io import BytesIO
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent
+
+CANONICAL_PROMPTS: dict[str, str] = {
+    "simple": "ok",
+    "question": "como funciona o sync de projetos?",
+    "code-modifying": "implementa auth no backend com testes",
+    "department-routed": "cria uma campanha de marketing para o lançamento",
+    "slash-command": "/dev feature user auth",
+}
+
+HOOK_REL = Path("config") / "hooks" / "user-prompt-submit.sh"
+
+
+def _run_hook(tree: Path, prompt: str) -> int:
+    """Return the additionalContext byte size the hook injects."""
+    payload = json.dumps(
+        {"prompt": prompt, "cwd": "/tmp", "session_id": "bench-1"}
+    )
+    proc = subprocess.run(
+        ["bash", str(tree / HOOK_REL)],
+        input=payload,
+        capture_output=True,
+        text=True,
+        timeout=30,
+        env={
+            "PATH": "/usr/bin:/bin:/usr/local/bin",
+            "HOME": str(Path.home()),
+            "ARKA_HOOK_FORCE_FALLBACK": "1",
+        },
+    )
+    out = proc.stdout.strip()
+    if not out:
+        return 0
+    try:
+        context = json.loads(out).get("additionalContext", "")
+    except json.JSONDecodeError:
+        context = out
+    return len(context.encode("utf-8"))
+
+
+def _extract_ref(ref: str, dest: Path) -> Path:
+    archive = subprocess.run(
+        ["git", "-C", str(REPO_ROOT), "archive", ref],
+        capture_output=True,
+        check=True,
+        timeout=60,
+    )
+    with tarfile.open(fileobj=BytesIO(archive.stdout)) as tar:
+        try:
+            tar.extractall(dest, filter="data")
+        except TypeError:  # Python < 3.12 has no filter param
+            tar.extractall(dest)  # trusted archive: local git, no network
+    return dest
+
+
+def measure(tree: Path) -> dict[str, dict[str, int]]:
+    results: dict[str, dict[str, int]] = {}
+    for name, prompt in CANONICAL_PROMPTS.items():
+        size = _run_hook(tree, prompt)
+        results[name] = {"bytes": size, "tokens_est": size // 4}
+    return results
+
+
+def compare(ref: str) -> dict:
+    with tempfile.TemporaryDirectory(prefix="arka-bench-") as tmp:
+        old_tree = _extract_ref(ref, Path(tmp))
+        before = measure(old_tree)
+    after = measure(REPO_ROOT)
+    total_before = sum(r["bytes"] for r in before.values())
+    total_after = sum(r["bytes"] for r in after.values())
+    reduction = (
+        round(100 * (1 - total_after / total_before), 1)
+        if total_before
+        else 0.0
+    )
+    return {
+        "ref": ref,
+        "before": before,
+        "after": after,
+        "total_bytes_before": total_before,
+        "total_bytes_after": total_after,
+        "reduction_pct": reduction,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--ref", help="git ref to compare against")
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args(argv)
+
+    if args.ref:
+        report = compare(args.ref)
+    else:
+        report = {"current": measure(REPO_ROOT)}
+
+    if args.as_json:
+        print(json.dumps(report, indent=2, ensure_ascii=False))
+        return 0
+
+    if "current" in report:
+        for name, row in report["current"].items():
+            print(f"{name:20s} {row['bytes']:>6d} B  ~{row['tokens_est']} tok")
+        return 0
+
+    print(f"Prompt-surface benchmark: {report['ref']} -> HEAD")
+    for name in CANONICAL_PROMPTS:
+        b = report["before"][name]["bytes"]
+        a = report["after"][name]["bytes"]
+        print(f"{name:20s} {b:>6d} B -> {a:>6d} B")
+    print(
+        f"{'TOTAL':20s} {report['total_bytes_before']:>6d} B -> "
+        f"{report['total_bytes_after']:>6d} B "
+        f"({report['reduction_pct']}% reduction)"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/knowledge/agents-registry.json

@@ -1,254 +0,0 @@
-{
-  "version": "1.0.0",
-  "generated": "2026-03-20",
-  "agents": [
-    {
-      "id": "cto",
-      "display_name": "Marco",
-      "role": "CTO",
-      "department": "dev",
-      "tier": 0,
-      "disc": { "primary": "D", "secondary": "C", "combination": "D+C", "label": "Driver-Analyst" },
-      "file": "departments/dev/agents/cto.md",
-      "memory_path": "~/.claude/agent-memory/arka-cto/MEMORY.md",
-      "key_authority": ["veto", "approve_architecture", "approve_tech_stack", "block_release"]
-    },
-    {
-      "id": "tech-lead",
-      "display_name": "Paulo",
-      "role": "Tech Lead",
-      "department": "dev",
-      "tier": 1,
-      "disc": { "primary": "I", "secondary": "S", "combination": "I+S", "label": "Inspirer-Supporter" },
-      "file": "departments/dev/agents/tech-lead.md",
-      "memory_path": "~/.claude/agent-memory/arka-tech-lead/MEMORY.md",
-      "key_authority": ["orchestrate", "assign_tasks"]
-    },
-    {
-      "id": "architect",
-      "display_name": "Gabriel",
-      "role": "Software Architect",
-      "department": "dev",
-      "tier": 1,
-      "disc": { "primary": "C", "secondary": "D", "combination": "C+D", "label": "Analyst-Driver" },
-      "file": "departments/dev/agents/architect.md",
-      "memory_path": "~/.claude/agent-memory/arka-architect/MEMORY.md",
-      "key_authority": ["design_architecture", "create_adr"]
-    },
-    {
-      "id": "senior-dev",
-      "display_name": "Andre",
-      "role": "Senior Backend Developer",
-      "department": "dev",
-      "tier": 2,
-      "disc": { "primary": "C", "secondary": "S", "combination": "C+S", "label": "Analyst-Supporter" },
-      "file": "departments/dev/agents/senior-dev.md",
-      "memory_path": "~/.claude/agent-memory/arka-senior-dev/MEMORY.md",
-      "key_authority": ["implement"]
-    },
-    {
-      "id": "frontend-dev",
-      "display_name": "Diana",
-      "role": "Senior Frontend Developer",
-      "department": "dev",
-      "tier": 2,
-      "disc": { "primary": "I", "secondary": "C", "combination": "I+C", "label": "Inspirer-Analyst" },
-      "file": "departments/dev/agents/frontend-dev.md",
-      "memory_path": "~/.claude/agent-memory/arka-frontend-dev/MEMORY.md",
-      "key_authority": ["implement"]
-    },
-    {
-      "id": "security",
-      "display_name": "Bruno",
-      "role": "Security Engineer",
-      "department": "dev",
-      "tier": 2,
-      "disc": { "primary": "C", "secondary": "D", "combination": "C+D", "label": "Analyst-Driver" },
-      "file": "departments/dev/agents/security.md",
-      "memory_path": "~/.claude/agent-memory/arka-security/MEMORY.md",
-      "key_authority": ["block_release", "security_audit"]
-    },
-    {
-      "id": "devops",
-      "display_name": "Carlos",
-      "role": "DevOps Lead",
-      "department": "dev",
-      "tier": 2,
-      "disc": { "primary": "D", "secondary": "C", "combination": "D+C", "label": "Driver-Analyst" },
-      "file": "departments/dev/agents/devops.md",
-      "memory_path": "~/.claude/agent-memory/arka-devops/MEMORY.md",
-      "key_authority": ["push", "deploy", "manage_ci"]
-    },
-    {
-      "id": "qa",
-      "display_name": "Rita",
-      "role": "QA Lead",
-      "department": "dev",
-      "tier": 3,
-      "disc": { "primary": "C", "secondary": "S", "combination": "C+S", "label": "Analyst-Supporter" },
-      "file": "departments/dev/agents/qa.md",
-      "memory_path": "~/.claude/agent-memory/arka-qa/MEMORY.md",
-      "key_authority": ["block_release", "validate"]
-    },
-    {
-      "id": "analyst",
-      "display_name": "Lucas",
-      "role": "Technical Analyst",
-      "department": "dev",
-      "tier": 3,
-      "disc": { "primary": "C", "secondary": "I", "combination": "C+I", "label": "Analyst-Inspirer" },
-      "file": "departments/dev/agents/analyst.md",
-      "memory_path": "~/.claude/agent-memory/arka-analyst/MEMORY.md",
-      "key_authority": ["research", "recommend"]
-    },
-    {
-      "id": "cfo",
-      "display_name": "Helena",
-      "role": "CFO",
-      "department": "finance",
-      "tier": 0,
-      "disc": { "primary": "D", "secondary": "C", "combination": "D+C", "label": "Driver-Analyst" },
-      "file": "departments/finance/agents/cfo.md",
-      "memory_path": "~/.claude/agent-memory/arka-cfo/MEMORY.md",
-      "key_authority": ["veto", "approve_budget", "financial_decisions"]
-    },
-    {
-      "id": "coo",
-      "display_name": "Sofia",
-      "role": "COO",
-      "department": "ops",
-      "tier": 0,
-      "disc": { "primary": "S", "secondary": "C", "combination": "S+C", "label": "Supporter-Analyst" },
-      "file": "departments/ops/agents/ops-lead.yaml",
-      "memory_path": "~/.claude/agent-memory/arka-coo/MEMORY.md",
-      "key_authority": ["veto", "approve_operations", "cross_department"]
-    },
-    {
-      "id": "content-creator",
-      "display_name": "Luna",
-      "role": "Content Creator",
-      "department": "marketing",
-      "tier": 1,
-      "disc": { "primary": "I", "secondary": "D", "combination": "I+D", "label": "Inspirer-Driver" },
-      "file": "departments/marketing/agents/content-creator.md",
-      "memory_path": "~/.claude/agent-memory/arka-content-creator/MEMORY.md",
-      "key_authority": ["create_content", "manage_campaigns"]
-    },
-    {
-      "id": "ecommerce-manager",
-      "display_name": "Ricardo",
-      "role": "E-commerce Manager",
-      "department": "ecom",
-      "tier": 1,
-      "disc": { "primary": "D", "secondary": "I", "combination": "D+I", "label": "Driver-Inspirer" },
-      "file": "departments/ecom/agents/ecom-director.yaml",
-      "memory_path": "~/.claude/agent-memory/arka-ecommerce-manager/MEMORY.md",
-      "key_authority": ["manage_store", "pricing_decisions"]
-    },
-    {
-      "id": "strategist",
-      "display_name": "Tomas",
-      "role": "Chief Strategist",
-      "department": "strategy",
-      "tier": 1,
-      "disc": { "primary": "I", "secondary": "D", "combination": "I+D", "label": "Inspirer-Driver" },
-      "file": "departments/strategy/agents/strategist.md",
-      "memory_path": "~/.claude/agent-memory/arka-strategist/MEMORY.md",
-      "key_authority": ["strategic_planning", "market_analysis"]
-    },
-    {
-      "id": "knowledge-curator",
-      "display_name": "Clara",
-      "role": "Knowledge Curator",
-      "department": "kb",
-      "tier": 1,
-      "disc": { "primary": "S", "secondary": "C", "combination": "S+C", "label": "Supporter-Analyst" },
-      "file": "departments/kb/agents/knowledge-curator.yaml",
-      "memory_path": "~/.claude/agent-memory/arka-knowledge-curator/MEMORY.md",
-      "key_authority": ["manage_knowledge", "create_personas"]
-    },
-    {
-      "id": "creative-director",
-      "display_name": "Valentina",
-      "role": "Creative Director",
-      "department": "brand",
-      "tier": 1,
-      "disc": { "primary": "S", "secondary": "I", "combination": "S+I", "label": "Supporter-Inspirer" },
-      "file": "departments/brand/agents/creative-director.md",
-      "memory_path": "~/.claude/agent-memory/arka-creative-director/MEMORY.md",
-      "key_authority": ["approve_brand", "create_brand", "manage_visuals", "orchestrate"]
-    },
-    {
-      "id": "brand-strategist",
-      "display_name": "Mateus",
-      "role": "Brand Strategist",
-      "department": "brand",
-      "tier": 2,
-      "disc": { "primary": "C", "secondary": "I", "combination": "C+I", "label": "Analyst-Inspirer" },
-      "file": "departments/brand/agents/brand-strategist.md",
-      "memory_path": "~/.claude/agent-memory/arka-brand-strategist/MEMORY.md",
-      "key_authority": ["brand_research", "brand_positioning", "recommend"]
-    },
-    {
-      "id": "visual-designer",
-      "display_name": "Isabel",
-      "role": "Visual Designer",
-      "department": "brand",
-      "tier": 2,
-      "disc": { "primary": "I", "secondary": "S", "combination": "I+S", "label": "Inspirer-Supporter" },
-      "file": "departments/brand/agents/visual-designer.md",
-      "memory_path": "~/.claude/agent-memory/arka-visual-designer/MEMORY.md",
-      "key_authority": ["generate_visuals", "create_assets", "implement"]
-    },
-    {
-      "id": "motion-designer",
-      "display_name": "Rafael",
-      "role": "Motion Designer",
-      "department": "brand",
-      "tier": 2,
-      "disc": { "primary": "D", "secondary": "I", "combination": "D+I", "label": "Driver-Inspirer" },
-      "file": "departments/brand/agents/motion-designer.md",
-      "memory_path": "~/.claude/agent-memory/arka-motion-designer/MEMORY.md",
-      "key_authority": ["generate_video", "create_motion", "implement"]
-    },
-    {
-      "id": "cqo",
-      "display_name": "Marta",
-      "role": "Chief Quality Officer",
-      "department": "quality",
-      "tier": 0,
-      "disc": { "primary": "C", "secondary": "D", "combination": "C+D", "label": "Analyst-Driver" },
-      "file": "departments/quality/agents/cqo.md",
-      "memory_path": "~/.claude/agent-memory/arka-cqo/MEMORY.md",
-      "key_authority": ["veto", "block_delivery", "block_release", "approve_quality"]
-    },
-    {
-      "id": "copy-director",
-      "display_name": "Eduardo",
-      "role": "Copy & Language Director",
-      "department": "quality",
-      "tier": 0,
-      "disc": { "primary": "C", "secondary": "S", "combination": "C+S", "label": "Analyst-Supporter" },
-      "file": "departments/quality/agents/copy-director.md",
-      "memory_path": "~/.claude/agent-memory/arka-copy-director/MEMORY.md",
-      "key_authority": ["veto", "block_delivery"]
-    },
-    {
-      "id": "tech-ux-director",
-      "display_name": "Francisca",
-      "role": "Technical & UX Quality Director",
-      "department": "quality",
-      "tier": 0,
-      "disc": { "primary": "D", "secondary": "C", "combination": "D+C", "label": "Driver-Analyst" },
-      "file": "departments/quality/agents/tech-ux-director.md",
-      "memory_path": "~/.claude/agent-memory/arka-tech-ux-director/MEMORY.md",
-      "key_authority": ["veto", "block_delivery", "block_release"]
-    }
-  ],
-  "team_composition": {
-    "by_disc_primary": { "D": 6, "I": 5, "S": 3, "C": 8 },
-    "by_tier": { "0": 6, "1": 7, "2": 7, "3": 2 },
-    "by_department": { "dev": 9, "finance": 1, "operations": 1, "marketing": 1, "ecommerce": 1, "strategy": 1, "knowledge": 1, "brand": 4, "quality": 3 },
-    "balance_notes": "22 agents across 9 departments. Quality Gate team (Marta, Eduardo, Francisca) adds 3 Tier 0 supervisors. C profile strong at 36% reflecting quality-driven culture."
-  }
-}