arkaos 4.8.0 → 4.10.0

package/VERSION

@@ -1 +1 @@
-4.8.0
+4.10.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/bin/arka

@@ -137,7 +137,11 @@ case "${1:-}" in
     REGISTRY="$REPO_DIR/knowledge/commands-registry.json"
     case "${1:-}" in
       rebuild)
-        bash "$REPO_DIR/bin/arka-registry-gen"
+        # Shared resolver (venv-first) with plain python3 fallback —
+        # the generator is stdlib-only.
+        _ARKA_LIB="$REPO_DIR/config/hooks/_lib/arka_python.sh"
+        if [ -f "$_ARKA_LIB" ]; then . "$_ARKA_LIB"; else ARKA_PY="python3"; fi
+        (cd "$REPO_DIR" && "$ARKA_PY" -m core.registry.generator)
         echo "Registry rebuilt: $(jq '._meta.total_commands' "$REGISTRY") commands."
         ;;
       --json)

package/bin/arkaos

@@ -65,8 +65,8 @@ case "${1:-}" in
       agents=$(jq -r '._meta.total_agents // 0' "$REPO_ROOT/knowledge/agents-registry-v2.json")
       echo "  Agents:       ${agents}"
     fi
-    if [ -n "$REPO_ROOT" ] && [ -f "$REPO_ROOT/knowledge/commands-registry-v2.json" ] && command -v jq &>/dev/null; then
-      commands=$(jq -r '._meta.total_commands // 0' "$REPO_ROOT/knowledge/commands-registry-v2.json")
+    if [ -n "$REPO_ROOT" ] && [ -f "$REPO_ROOT/knowledge/commands-registry.json" ] && command -v jq &>/dev/null; then
+      commands=$(jq -r '._meta.total_commands // 0' "$REPO_ROOT/knowledge/commands-registry.json")
       echo "  Commands:     ${commands}"
     fi
     echo ""

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