arkaos 2.15.0 → 2.16.0

package/config/hooks/token-hygiene.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# ============================================================================
+# ArkaOS v2 — Token Hygiene Suggestions
+# Non-blocking proactive suggestions for token-efficient usage.
+# Called by user-prompt-submit.sh. Emits suggestion strings to stdout, one
+# per line. Never blocks. Never errors out (swallow everything).
+# ============================================================================
+
+# Inputs (env):
+#   ARKA_PROMPT          — raw user prompt text
+#   ARKA_TRANSCRIPT_PATH — path to Claude Code transcript jsonl (optional)
+#   CLAUDE_CONTEXT_USED  — context percent used (optional, if runtime exposes)
+
+set +e  # never fail
+
+_prompt="${ARKA_PROMPT:-}"
+_transcript="${ARKA_TRANSCRIPT_PATH:-}"
+_suggestions=""
+
+_emit() {
+  if [ -z "$_suggestions" ]; then
+    _suggestions="$1"
+  else
+    _suggestions="$_suggestions $1"
+  fi
+}
+
+# ─── Check 1: Context % monitor ─────────────────────────────────────────
+# Prefer runtime-provided env var. If transcript exists we could count, but
+# the runtime value is canonical when present.
+if [ -n "${CLAUDE_CONTEXT_USED:-}" ]; then
+  _ctx="$CLAUDE_CONTEXT_USED"
+  # strip % if present
+  _ctx="${_ctx%\%}"
+  if [ -n "$_ctx" ] && [ "$_ctx" -eq "$_ctx" ] 2>/dev/null; then
+    if [ "$_ctx" -gt 80 ]; then
+      _emit "[arka:warn] Context at ${_ctx}% — /compact recommended NOW."
+    elif [ "$_ctx" -gt 60 ]; then
+      _emit "[arka:suggest] Context at ${_ctx}% — consider /compact."
+    fi
+  fi
+else
+  : # TODO: runtime does not yet expose context usage reliably; skip.
+fi
+
+# ─── Check 2: Topic drift detector ──────────────────────────────────────
+# Compare keywords in current prompt against last 3 user messages in the
+# transcript (if available). Pure bash/awk — no external semantic libs.
+if [ -n "$_transcript" ] && [ -f "$_transcript" ] && [ -n "$_prompt" ]; then
+  _STOPWORDS=" the a an and or but if then of for to in on at by with from is are was were be been being do does did have has had this that these those it its as i you we they he she them my your our their so not no yes can will would could should may might must need want fix make use get set add remove "
+
+  _kw() {
+    # extract lowercase word tokens > 3 chars, drop stopwords, output uniq
+    echo "$1" | tr '[:upper:]' '[:lower:]' \
+      | tr -c 'a-z0-9' '\n' \
+      | awk 'length($0) > 3' \
+      | awk -v sw=" $(echo " ")$_STOPWORDS" '{
+          key=" "$0" ";
+          if (index(ENVIRON["_STOPWORDS"], key)==0) print $0
+        }' \
+      | sort -u
+  }
+  export _STOPWORDS
+  _cur_kw=$(_kw "$_prompt" | head -20)
+  # pull last 3 user messages from transcript jsonl
+  _prior=$(tail -n 200 "$_transcript" 2>/dev/null \
+    | python3 -c "
+import sys, json
+msgs=[]
+for line in sys.stdin:
+    try:
+        o=json.loads(line)
+    except Exception:
+        continue
+    if o.get('type')=='user' or o.get('role')=='user':
+        c=o.get('content') or o.get('message',{}).get('content','')
+        if isinstance(c, list):
+            c=' '.join(p.get('text','') for p in c if isinstance(p,dict))
+        msgs.append(str(c))
+print('\n'.join(msgs[-3:]))
+" 2>/dev/null)
+
+  if [ -n "$_prior" ] && [ -n "$_cur_kw" ]; then
+    _prior_kw=$(_kw "$_prior")
+    _cur_count=$(echo "$_cur_kw" | grep -c .)
+    if [ "$_cur_count" -gt 2 ]; then
+      _overlap=$(comm -12 <(echo "$_cur_kw") <(echo "$_prior_kw") | grep -c .)
+      # percent overlap
+      _pct=$(( _overlap * 100 / _cur_count ))
+      if [ "$_pct" -lt 30 ]; then
+        _emit "[arka:suggest] Topic shift detected — consider /clear for a fresh session."
+      fi
+    fi
+  fi
+fi
+
+# ─── Check 3: Large paste detector ──────────────────────────────────────
+if [ -n "$_prompt" ]; then
+  _chars=${#_prompt}
+  if [ "$_chars" -gt 2000 ] && echo "$_prompt" | grep -q '```'; then
+    _emit "[arka:suggest] Large paste detected (${_chars} chars) — consider @filepath reference for better token economy."
+  fi
+fi
+
+# ─── Check 4: Vague reference detector ──────────────────────────────────
+if [ -n "$_prompt" ]; then
+  _lower=$(echo "$_prompt" | tr '[:upper:]' '[:lower:]')
+  _vague=0
+  for phrase in "fix the bug" "that file" "the error" "esse ficheiro" "esse erro" "aquele bug"; do
+    if echo "$_lower" | grep -qF "$phrase"; then
+      _vague=1
+      break
+    fi
+  done
+  if [ "$_vague" -eq 1 ] && ! echo "$_prompt" | grep -q '@'; then
+    _emit "[arka:suggest] Vague reference — use @path/to/file.ext for precision."
+  fi
+fi
+
+echo -n "$_suggestions"

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

@@ -145,15 +145,10 @@ if [ -z "$python_result" ]; then
     L4="[branch:$branch]"
   fi
 
-  # L7: Time
-  hour=$(date +%H)
-  if [ "$hour" -ge 5 ] && [ "$hour" -lt 12 ]; then
-    L7="[time:morning]"
-  elif [ "$hour" -ge 12 ] && [ "$hour" -lt 18 ]; then
-    L7="[time:afternoon]"
-  else
-    L7="[time:evening]"
-  fi
+  # L7: Time — intentionally skipped in bash fallback.
+  # Low-signal tag that changed every prompt and invalidated prompt cache.
+  # The Python TimeLayer (cache_ttl=3600) is authoritative when available.
+  L7=""
 
   # L8: Workflow state
   L8=""
@@ -183,8 +178,31 @@ if [ -z "$python_result" ]; then
   python_result="$L0 $L4 $L7 $L8 $L9"
 fi
 
+# ─── Token Hygiene suggestions (non-blocking) ───────────────────────────
+_HYGIENE=""
+_HYGIENE_SCRIPT="$(dirname "$0")/token-hygiene.sh"
+if [ -f "$_HYGIENE_SCRIPT" ]; then
+  # Extract transcript path from input JSON if present
+  _TRANSCRIPT=""
+  if command -v jq &>/dev/null; then
+    _TRANSCRIPT=$(echo "$input" | jq -r '.transcript_path // ""' 2>/dev/null)
+  fi
+  _HYGIENE=$(ARKA_PROMPT="$user_input" \
+             ARKA_TRANSCRIPT_PATH="$_TRANSCRIPT" \
+             CLAUDE_CONTEXT_USED="${CLAUDE_CONTEXT_USED:-}" \
+             bash "$_HYGIENE_SCRIPT" 2>/dev/null)
+fi
+
 # ─── Output ──────────────────────────────────────────────────────────────
-echo "{\"additionalContext\": \"${_ARKA_GREETING:-}${_SYNC_NOTICE:-}$python_result\"}"
+_OUT_CONTEXT="${_ARKA_GREETING:-}${_SYNC_NOTICE:-}$python_result"
+[ -n "$_HYGIENE" ] && _OUT_CONTEXT="$_OUT_CONTEXT $_HYGIENE"
+# 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
+  echo "{\"additionalContext\": $_OUT_JSON}"
+else
+  echo "{\"additionalContext\": \"${_ARKA_GREETING:-}${_SYNC_NOTICE:-}$python_result\"}"
+fi
 
 # ─── Metrics ─────────────────────────────────────────────────────────────
 elapsed=$(_hook_ms)

package/core/agents/schema.py

@@ -8,10 +8,20 @@ Every ArkaOS agent has a complete behavioral profile composed of:
 """
 
 from enum import Enum
-from typing import Optional
+from typing import Literal, Optional
 from pydantic import BaseModel, Field, model_validator
 
 
+ModelTier = Literal["haiku", "sonnet", "opus"]
+
+
+def tier_default_model(tier: int) -> ModelTier:
+    """Return default Claude model for a given agent tier."""
+    if tier == 0:
+        return "opus"
+    return "sonnet"
+
+
 # --- DISC Framework ---
 
 class DISCType(str, Enum):
@@ -258,8 +268,17 @@ class Agent(BaseModel):
 
     memory_path: str = ""
 
+    model: Optional[ModelTier] = Field(
+        default=None,
+        description="Claude model override for dispatch. Falls back to tier default when None.",
+    )
+
     @model_validator(mode="after")
     def auto_fill_memory_path(self) -> "Agent":
         if not self.memory_path:
             self.memory_path = f"~/.claude/agent-memory/arka-{self.id}/MEMORY.md"
         return self
+
+    def get_model(self) -> ModelTier:
+        """Return the resolved Claude model, using tier default when unset."""
+        return self.model or tier_default_model(self.tier)

package/core/synapse/layers.py

@@ -419,6 +419,13 @@ class TimeLayer(Layer):
     def name(self) -> str:
         return "Time"
 
+    @property
+    def cache_ttl(self) -> int:
+        # 1 hour — time-of-day period only changes at 5/12/18 boundaries.
+        # Cache bucket drift of up to 1h is acceptable for a low-signal tag
+        # and dramatically improves prompt-cache hit rate.
+        return 3600
+
     @property
     def priority(self) -> int:
         return 70

package/core/workflow/schema.py

@@ -9,9 +9,11 @@ Workflows define multi-phase execution plans with:
 """
 
 from enum import Enum
-from typing import Optional, Any
+from typing import Optional, Any, Literal
 from pydantic import BaseModel, Field
 
+ModelOverride = Literal["haiku", "sonnet", "opus"]
+
 
 class PhaseStatus(str, Enum):
     PENDING = "pending"
@@ -65,6 +67,7 @@ class Phase(BaseModel):
     outputs: list[PhaseOutput] = Field(default_factory=list)
     depends_on: list[str] = Field(default_factory=list)
     skip_if: Optional[str] = None       # Condition to skip this phase
+    model_override: Optional[ModelOverride] = None  # Force model for this phase (overrides agent defaults)
     status: PhaseStatus = PhaseStatus.PENDING
     result: Optional[str] = None
 

package/departments/brand/SKILL.md

@@ -83,3 +83,16 @@ Level 4 — DELIVERY (Valentina leads)
 4. Archetype consistent — Visual + verbal aligned to chosen archetype?
 5. WCAG AA — Colors pass contrast, fonts readable, accessible?
 6. Rams principles — Design is useful, honest, unobtrusive, thorough?
+
+## Model Selection
+
+When dispatching subagent work via the Task tool, include the `model` parameter from the target agent's YAML `model:` field:
+
+- Agent YAMLs at `departments/*/agents/*.yaml` have `model: opus | sonnet | haiku`
+- Quality Gate dispatch (Marta/Eduardo/Francisca) ALWAYS uses `model: opus` — NON-NEGOTIABLE
+- Default to `sonnet` if the agent YAML has no `model` field
+- Mechanical tasks (commit messages, routing, keyword extraction) use `model: haiku`
+
+Example Task tool call:
+
+    Task(description="...", subagent_type="general-purpose", model="sonnet", prompt="...")

package/departments/brand/agents/brand-director.yaml

@@ -3,6 +3,7 @@ name: Valentina
 role: Creative Director
 department: brand
 tier: 1
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/brand/agents/brand-strategist.yaml

@@ -3,6 +3,7 @@ name: Mateus
 role: Brand Strategist
 department: brand
 tier: 2
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/brand/agents/ux-designer.yaml

@@ -3,6 +3,7 @@ name: Sofia D.
 role: UX/UI Designer
 department: brand
 tier: 2
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/brand/agents/visual-designer.yaml

@@ -3,6 +3,7 @@ name: Isabel
 role: Visual Designer
 department: brand
 tier: 2
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/brand/workflows/identity.yaml

@@ -84,6 +84,7 @@ phases:
 
   - id: quality-gate
     name: Quality Gate
+    model_override: opus
     description: Mandatory quality review
     agents:
       - agent_id: cqo-marta

package/departments/brand/workflows/naming.yaml

@@ -36,6 +36,7 @@ phases:
     description: User selects final name from shortlist
 - id: quality-gate
   name: Quality Gate
+  model_override: opus
   agents:
   - agent_id: cqo-marta
     role: Orchestrate review

package/departments/community/SKILL.md

@@ -60,3 +60,16 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 | Membership Economy | Robbie Kellman Baxter | Recurring revenue design |
 | TRIBE Method | Stu McLaren | Membership site creation |
 | Platform Selection Matrix | ArkaOS | Matching niche to platform |
+
+## Model Selection
+
+When dispatching subagent work via the Task tool, include the `model` parameter from the target agent's YAML `model:` field:
+
+- Agent YAMLs at `departments/*/agents/*.yaml` have `model: opus | sonnet | haiku`
+- Quality Gate dispatch (Marta/Eduardo/Francisca) ALWAYS uses `model: opus` — NON-NEGOTIABLE
+- Default to `sonnet` if the agent YAML has no `model` field
+- Mechanical tasks (commit messages, routing, keyword extraction) use `model: haiku`
+
+Example Task tool call:
+
+    Task(description="...", subagent_type="general-purpose", model="sonnet", prompt="...")

package/departments/community/agents/community-manager.yaml

@@ -3,6 +3,7 @@ name: Maria
 role: Community Manager
 department: community
 tier: 2
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/community/agents/community-strategist.yaml

@@ -3,6 +3,7 @@ name: Beatriz
 role: Community Strategist
 department: community
 tier: 1
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/community/agents/engagement-designer.yaml

@@ -3,6 +3,7 @@ name: Tania
 role: Engagement & Gamification Designer
 department: community
 tier: 2
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/community/workflows/setup.yaml

@@ -40,6 +40,7 @@ phases:
     type: auto
 - id: quality-gate
   name: Quality Gate
+  model_override: opus
   agents:
   - agent_id: cqo-marta
     role: Orchestrate

package/departments/content/SKILL.md

@@ -63,3 +63,16 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 | Content-to-Revenue Pipeline | Creator economy | Monetization strategy |
 | Pillar to Atomize | GaryVee | 1 to 30+ repurposing |
 | Hook-Bridge-Body-CTA | Scriptwriting standard | Video/audio script structure |
+
+## Model Selection
+
+When dispatching subagent work via the Task tool, include the `model` parameter from the target agent's YAML `model:` field:
+
+- Agent YAMLs at `departments/*/agents/*.yaml` have `model: opus | sonnet | haiku`
+- Quality Gate dispatch (Marta/Eduardo/Francisca) ALWAYS uses `model: opus` — NON-NEGOTIABLE
+- Default to `sonnet` if the agent YAML has no `model` field
+- Mechanical tasks (commit messages, routing, keyword extraction) use `model: haiku`
+
+Example Task tool call:
+
+    Task(description="...", subagent_type="general-purpose", model="sonnet", prompt="...")

package/departments/content/agents/content-strategist.yaml

@@ -3,6 +3,7 @@ name: Rafael
 role: Content Strategist
 department: content
 tier: 1
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/content/agents/repurpose-distributor.yaml

@@ -3,6 +3,7 @@ name: Nuno
 role: Repurpose & Distribution Specialist
 department: content
 tier: 2
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/content/agents/scriptwriter.yaml

@@ -3,6 +3,7 @@ name: Joana
 role: Scriptwriter
 department: content
 tier: 2
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/content/agents/viral-engineer.yaml

@@ -3,6 +3,7 @@ name: Filipe
 role: Viral Content Engineer
 department: content
 tier: 2
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/content/workflows/viral.yaml

@@ -70,6 +70,7 @@ phases:
 
   - id: quality-gate
     name: Quality Gate
+    model_override: opus
     description: Quality review of all content
     agents:
       - agent_id: cqo-marta

package/departments/dev/SKILL.md

@@ -133,3 +133,16 @@ All code-modifying commands create a feature branch:
 | Database | PostgreSQL (via Supabase) |
 | CSS | Tailwind CSS |
 | Deploy | Vercel / Azure |
+
+## Model Selection
+
+When dispatching subagent work via the Task tool, include the `model` parameter from the target agent's YAML `model:` field:
+
+- Agent YAMLs at `departments/*/agents/*.yaml` have `model: opus | sonnet | haiku`
+- Quality Gate dispatch (Marta/Eduardo/Francisca) ALWAYS uses `model: opus` — NON-NEGOTIABLE
+- Default to `sonnet` if the agent YAML has no `model` field
+- Mechanical tasks (commit messages, routing, keyword extraction) use `model: haiku`
+
+Example Task tool call:
+
+    Task(description="...", subagent_type="general-purpose", model="sonnet", prompt="...")

package/departments/dev/agents/architect.yaml

@@ -3,6 +3,7 @@ name: Gabriel
 role: Software Architect
 department: dev
 tier: 1
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/dev/agents/backend-dev.yaml

@@ -3,6 +3,7 @@ name: Andre
 role: Senior Backend Developer
 department: dev
 tier: 2
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/dev/agents/cto.yaml

@@ -3,6 +3,7 @@ name: Marco
 role: Chief Technology Officer
 department: dev
 tier: 0
+model: opus
 
 behavioral_dna:
   disc:

package/departments/dev/agents/dba.yaml

@@ -3,6 +3,7 @@ name: Vasco
 role: Database & Data Engineer
 department: dev
 tier: 2
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/dev/agents/devops-eng.yaml

@@ -3,6 +3,7 @@ name: Carlos
 role: DevOps Lead
 department: dev
 tier: 2
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/dev/agents/frontend-dev.yaml

@@ -3,6 +3,7 @@ name: Diana
 role: Senior Frontend Developer
 department: dev
 tier: 2
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/dev/agents/qa-eng.yaml

@@ -3,6 +3,7 @@ name: Rita
 role: QA Engineer
 department: dev
 tier: 2
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/dev/agents/research-assistant.yaml

@@ -3,6 +3,7 @@ name: Maria
 role: Research Assistant
 department: dev
 tier: 3
+model: haiku
 
 behavioral_dna:
   disc:

package/departments/dev/agents/security-eng.yaml

@@ -3,6 +3,7 @@ name: Bruno
 role: Security Engineer
 department: dev
 tier: 2
+model: sonnet
 
 behavioral_dna:
   disc:

package/departments/dev/agents/tech-lead.yaml

@@ -3,6 +3,7 @@ name: Paulo
 role: Tech Lead
 department: dev
 tier: 1
+model: sonnet
 
 behavioral_dna:
   disc: