arkaos 3.71.1 → 3.73.0

package/VERSION

@@ -1 +1 @@
-3.71.1
+3.73.0

package/arka/skills/flow/SKILL.md

@@ -73,6 +73,26 @@ state the gap explicitly and propose filling it.
 Dispatch specialists via the `Agent` tool. The squad lead from Phase 3
 names them. Specialists run in parallel when work is independent.
 
+**Dispatch must be announced (NON-NEGOTIABLE `dispatch-must-be-announced`).**
+Immediately before each `Agent` tool call, emit on its own line:
+
+```
+[arka:dispatch] <calling-persona> -> <specialist-id>
+```
+
+Example before dispatching a frontend specialist from Paulo's seat:
+
+```
+[arka:dispatch] paulo -> frontend-dev
+```
+
+The PreToolUse specialist-enforcer (`core/workflow/specialist_enforcer.py`)
+reads this marker to identify which specialist holds the floor. Without
+it, the specialist's subsequent `Write`/`Edit` will block when
+`hooks.specialistEnforcement=true`. The marker format mirrors
+`[arka:routing]` exactly but uses the verb `dispatch` and points from
+the caller to the receiver.
+
 ### Phase 7 — Plan and make the spec
 Run six parallel reviewers on the plan:
 

package/config/agent-ownership.yaml

@@ -0,0 +1,169 @@
+# ============================================================================
+# ArkaOS — Agent File Ownership
+#
+# Maps file path patterns to the specialist agents (Tier 2) who own writes
+# to those files. Squad leads (Tier 1) MUST dispatch the specialist via
+# the Agent tool before writing to owned files — otherwise the PreToolUse
+# hook blocks the write.
+#
+# Read by: core/workflow/specialist_enforcer.py
+# Hook: config/hooks/pre-tool-use.sh (between KB-gate and flow-gate)
+#
+# Bypass: emit `[arka:specialist-bypass <reason>]` in the same assistant
+# message immediately before the Write/Edit. Bypass is logged to
+# ~/.arkaos/telemetry/specialist-dispatch.jsonl for accountability.
+#
+# Feature flag: hooks.specialistEnforcement in ~/.arkaos/config.json
+# (defaults to false during rollout — promote to true after telemetry
+# shows the rule set is stable).
+# ============================================================================
+
+version: 1
+
+# Squad leads (Tier 1) — orchestrate, dispatch specialists, do not implement.
+# The routing tag `[arka:routing] <dept> -> <name>` identifies which lead
+# currently holds the floor. Lead names are normalized to lowercase by
+# the enforcer before comparison.
+leads:
+  - paulo       # dev — Tech Lead
+  - luna        # mkt — Marketing Lead
+  - valentina   # brand — Brand Lead
+  - helena      # fin — CFO (also c_suite)
+  - tomas       # strat — Strategy Lead
+  - ricardo     # ecom — E-commerce Lead
+  - clara       # kb — Knowledge Lead
+  - daniel      # ops — Operations Lead
+  - carolina    # pm — Project Management Lead
+  - tiago       # saas — SaaS Lead
+  - ines        # landing — Landing Lead
+  - rafael      # content — Content Lead
+  - beatriz     # community — Community Lead
+  - miguel      # sales — Sales Lead
+  - rodrigo     # leadership — People Lead
+  - sofia       # org — COO (also c_suite)
+
+# C-Suite (Tier 0) — veto power, may write anywhere without dispatch.
+# Listed here so the enforcer treats them as always-authorized.
+c_suite:
+  - marco       # CTO
+  - marta       # CQO
+  - eduardo     # Copy Director
+  - francisca   # Tech Director
+  - sofia       # COO
+  - helena      # CFO
+
+# Ownership rules — evaluated top-to-bottom, FIRST match wins.
+# Patterns use glob syntax (fnmatch + ** for recursive directory).
+# `owners` lists the specialist agent IDs (kebab-case) authorized to write.
+# A persona currently holding the routing floor must match one of `owners`
+# (case-insensitive). Leads always fail unless they appear in `owners`.
+ownership:
+  # ─── Frontend ────────────────────────────────────────────────────────
+  - pattern: "**/*.vue"
+    owners: [frontend-dev]
+    reason: "Vue templates require frontend specialist"
+
+  - pattern: "**/*.tsx"
+    owners: [frontend-dev]
+    reason: "React TSX requires frontend specialist"
+
+  - pattern: "**/*.jsx"
+    owners: [frontend-dev]
+    reason: "React JSX requires frontend specialist"
+
+  - pattern: "**/components/**"
+    owners: [frontend-dev]
+    reason: "Component layer is frontend specialist territory"
+
+  # ─── Backend (PHP/Laravel) ───────────────────────────────────────────
+  - pattern: "**/app/Services/**"
+    owners: [senior-dev, backend-dev]
+    reason: "Service layer requires backend specialist"
+
+  - pattern: "**/app/Repositories/**"
+    owners: [senior-dev, backend-dev]
+    reason: "Repository layer requires backend specialist"
+
+  - pattern: "**/app/Http/Controllers/**"
+    owners: [senior-dev, backend-dev]
+    reason: "Controllers require backend specialist"
+
+  - pattern: "**/database/migrations/**"
+    owners: [dba, backend-dev]
+    reason: "Migrations require DBA review"
+
+  # ─── Security-sensitive ──────────────────────────────────────────────
+  - pattern: "**/.env*"
+    owners: [security-eng]
+    reason: "Environment files require security specialist"
+
+  - pattern: "**/auth/**"
+    owners: [security-eng, backend-dev]
+    reason: "Auth code requires security review"
+
+  - pattern: "core/security/**"
+    owners: [security-eng]
+    reason: "Core security module is security specialist territory"
+
+  - pattern: "config/hooks/**"
+    owners: [security-eng, devops-eng]
+    reason: "Hooks affect runtime behavior — security + devops review required"
+
+  # ─── DevOps / Infrastructure ─────────────────────────────────────────
+  - pattern: ".github/workflows/**"
+    owners: [devops-eng]
+    reason: "CI/CD workflows are devops specialist territory"
+
+  - pattern: "**/Dockerfile*"
+    owners: [devops-eng]
+    reason: "Container builds require devops specialist"
+
+  - pattern: "infrastructure/**"
+    owners: [devops-eng]
+    reason: "Infrastructure-as-code requires devops specialist"
+
+  # ─── Core architecture ──────────────────────────────────────────────
+  - pattern: "core/workflow/**/*.py"
+    owners: [architect, senior-dev]
+    reason: "Workflow engine requires architecture review"
+
+  - pattern: "core/agents/**/*.py"
+    owners: [architect, senior-dev]
+    reason: "Agent schema/loader requires architecture review"
+
+  - pattern: "core/governance/**/*.py"
+    owners: [architect, security-eng]
+    reason: "Governance code requires architecture + security review"
+
+  - pattern: "docs/adr/**"
+    owners: [architect]
+    reason: "ADRs are architect's responsibility"
+
+  # ─── Open-access (any persona may write) ─────────────────────────────
+  # Tests are written by the specialist who owns the code under test.
+  # qa-eng owns test STRATEGY, not individual test files.
+  - pattern: "**/tests/**"
+    owners: ["*"]
+    reason: "Tests written by specialist who owns code under test"
+
+  - pattern: "**/*.md"
+    owners: ["*"]
+    reason: "Markdown docs are open to any persona"
+
+# Lead-allowed files — leads + c-suite ALWAYS allowed without dispatch.
+# Used for cross-cutting files that touch many specialists.
+lead_allowed:
+  - "CHANGELOG.md"
+  - "VERSION"
+  - "package.json"
+  - "package-lock.json"
+  - "pyproject.toml"
+  - "uv.lock"
+  - "README.md"
+  - "CLAUDE.md"
+  - "CONSTITUTION.md"
+  - "config/agent-ownership.yaml"   # bootstrap — this file
+  - "config/constitution.yaml"
+  - "**/*.yaml"                      # squad/workflow configs
+  - "**/*.yml"
+  - "knowledge/**"                   # KB curation

package/config/constitution.yaml

@@ -121,6 +121,11 @@ enforcement_levels:
         rule: "ArkaOS learns from user corrections via hybrid mechanism: implicit auto-detection with confidence scoring for typical corrections (default), explicit Marta-led confirmation for high-leverage rules (NON-NEGOTIABLE candidates) or rules that contradict existing memory. Marta is the owner of the learning loop. Memory rules carry a confidence field that climbs as the rule is applied without correction."
         enforcement: "Correction signals detected via absolute-language keywords ('sempre', 'nunca', 'no exceptions') and correction magnitude; [arka:learned-rule confidence=X] tag emitted when rule auto-saved; explicit Marta confirmation question fired when rule is high-leverage or conflicts with existing memory."
 
+      # ─── Rule added in PR1 Squad Intelligence Upgrade (2026-05-28) ───────
+      - id: dispatch-must-be-announced
+        rule: "When a squad lead dispatches a specialist via the Agent tool, the lead MUST emit `[arka:dispatch] <from> -> <to>` on a line of its own immediately before the dispatch call. The marker identifies the specialist to the PreToolUse specialist-enforcer so writes from the specialist pass `owner-match` instead of falling through as `no-routing-tag` or blocking the lead. The format is identical to `[arka:routing]` but uses the verb `dispatch` and points from the calling persona to the receiving specialist (e.g., `[arka:dispatch] paulo -> frontend-dev`)."
+        enforcement: "PreToolUse hook (config/hooks/pre-tool-use.sh) reads the dispatch marker via core.workflow.specialist_enforcer._resolve_persona. Dispatch tag overrides routing tag because it is more specific. Without it, lead writes to specialist-owned files are blocked when hooks.specialistEnforcement=true. See ADR docs/adr/2026-05-28-specialist-dispatch-subagent-blindspot.md for the architectural constraint this rule mitigates."
+
   quality_gate:
     description: "Mandatory pre-delivery review. Nothing ships without APPROVED verdict."
     trigger: "After the last execution phase, before delivery to user"

package/config/hooks/pre-tool-use.ps1

@@ -116,6 +116,83 @@ print(json.dumps({
     }
 }
 
+# --- Specialist-dispatch gate (between KB-gate and flow-gate) ---
+# Blocks Tier-1 leads from writing to specialist-owned files without
+# dispatching first. Only fires for file-mutation tools.
+$specialistPy = Join-Path $env:ARKAOS_ROOT "core/workflow/specialist_enforcer.py"
+if ((Test-Path $specialistPy) -and ($toolName -in @("Write","Edit","MultiEdit","NotebookEdit"))) {
+    $toolInputJson = "{}"
+    if ($inp.tool_input) {
+        $toolInputJson = ($inp.tool_input | ConvertTo-Json -Compress -Depth 10)
+    }
+    $env:TOOL_NAME = $toolName
+    $env:TRANSCRIPT_PATH = $transcriptPath
+    $env:SESSION_ID = $sessionId
+    $env:CWD = $cwd
+    $env:TOOL_INPUT_JSON = $toolInputJson
+
+    $spScript = @'
+import json
+import os
+import sys
+
+sys.path.insert(0, os.environ["ARKAOS_ROOT"])
+try:
+    from core.workflow.specialist_enforcer import evaluate, record_telemetry
+except Exception:
+    print(json.dumps({"allow": True, "reason": "specialist-import-failed"}))
+    sys.exit(0)
+
+try:
+    tool_input = json.loads(os.environ.get("TOOL_INPUT_JSON", "{}"))
+except json.JSONDecodeError:
+    tool_input = {}
+
+decision = evaluate(
+    tool_name=os.environ.get("TOOL_NAME", ""),
+    transcript_path=os.environ.get("TRANSCRIPT_PATH", ""),
+    session_id=os.environ.get("SESSION_ID", ""),
+    cwd=os.environ.get("CWD", ""),
+    tool_input=tool_input,
+)
+try:
+    record_telemetry(
+        session_id=os.environ.get("SESSION_ID", ""),
+        tool=os.environ.get("TOOL_NAME", ""),
+        decision=decision,
+        cwd=os.environ.get("CWD", ""),
+        target_file=str(tool_input.get("file_path", "")),
+    )
+except Exception:
+    pass
+print(json.dumps({
+    "allow": decision.allow,
+    "reason": decision.reason,
+    "stderr_msg": decision.to_stderr_message(),
+}))
+'@
+
+    $spDecisionJson = $spScript | & $python.Source -
+    if (-not [string]::IsNullOrWhiteSpace($spDecisionJson)) {
+        try {
+            $spDecision = $spDecisionJson | ConvertFrom-Json
+        } catch { $spDecision = $null }
+
+        if ($spDecision -and -not $spDecision.allow) {
+            [Console]::Error.WriteLine($spDecision.stderr_msg)
+            $denyOut = @{
+                hookSpecificOutput = @{
+                    hookEventName = "PreToolUse"
+                    permissionDecision = "deny"
+                    permissionDecisionReason = $spDecision.stderr_msg
+                }
+            } | ConvertTo-Json -Compress -Depth 5
+            Write-Output $denyOut
+            exit 2
+        }
+    }
+}
+
 # --- Fast allow: not a flow-gated tool ---
 if ($toolName -ne "Write" -and $toolName -ne "Edit" -and $toolName -ne "MultiEdit") {
     exit 0

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

@@ -120,6 +120,86 @@ PY
   fi
 fi
 
+# ─── Specialist-dispatch gate (between KB-gate and flow-gate) ──────────
+# Blocks Tier-1 leads from writing to specialist-owned files without
+# dispatching first. Only fires for file-mutation tools. Independent
+# feature flag (`hooks.specialistEnforcement`) — fails open if the
+# Python module is absent or raises.
+if [ -f "$ARKAOS_ROOT/core/workflow/specialist_enforcer.py" ]; then
+  case "$TOOL_NAME" in
+    Write|Edit|MultiEdit|NotebookEdit)
+      TOOL_INPUT_JSON_SP="{}"
+      if command -v jq &>/dev/null; then
+        TOOL_INPUT_JSON_SP=$(echo "$input" | jq -c '.tool_input // {}' 2>/dev/null)
+      fi
+      SP_DECISION_JSON=$(TOOL_NAME="$TOOL_NAME" \
+                         TRANSCRIPT_PATH="$TRANSCRIPT_PATH" \
+                         SESSION_ID="$SESSION_ID" \
+                         CWD="$CWD" \
+                         TOOL_INPUT_JSON="$TOOL_INPUT_JSON_SP" \
+                         ARKAOS_ROOT="$ARKAOS_ROOT" \
+                         python3 - <<'PY' 2>/dev/null
+import json
+import os
+import sys
+
+sys.path.insert(0, os.environ["ARKAOS_ROOT"])
+try:
+    from core.workflow.specialist_enforcer import evaluate, record_telemetry
+except Exception:
+    print(json.dumps({"allow": True, "reason": "specialist-import-failed"}))
+    sys.exit(0)
+
+try:
+    tool_input = json.loads(os.environ.get("TOOL_INPUT_JSON", "{}"))
+except json.JSONDecodeError:
+    tool_input = {}
+
+decision = evaluate(
+    tool_name=os.environ.get("TOOL_NAME", ""),
+    transcript_path=os.environ.get("TRANSCRIPT_PATH", ""),
+    session_id=os.environ.get("SESSION_ID", ""),
+    cwd=os.environ.get("CWD", ""),
+    tool_input=tool_input,
+)
+try:
+    record_telemetry(
+        session_id=os.environ.get("SESSION_ID", ""),
+        tool=os.environ.get("TOOL_NAME", ""),
+        decision=decision,
+        cwd=os.environ.get("CWD", ""),
+        target_file=str(tool_input.get("file_path", "")),
+    )
+except Exception:
+    pass
+print(json.dumps({
+    "allow": decision.allow,
+    "reason": decision.reason,
+    "stderr_msg": decision.to_stderr_message(),
+}))
+PY
+)
+
+      if [ -n "$SP_DECISION_JSON" ]; then
+        SP_ALLOW=$(echo "$SP_DECISION_JSON" | python3 -c "import json,sys; print(json.load(sys.stdin).get('allow', True))" 2>/dev/null)
+        if [ "$SP_ALLOW" != "True" ] && [ "$SP_ALLOW" != "true" ]; then
+          SP_STDERR=$(echo "$SP_DECISION_JSON" | python3 -c "import json,sys; print(json.load(sys.stdin).get('stderr_msg',''))" 2>/dev/null)
+          echo "$SP_STDERR" >&2
+          STDERR_MSG="$SP_STDERR" python3 - <<'PY'
+import json, os
+print(json.dumps({"hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": os.environ.get("STDERR_MSG", ""),
+}}))
+PY
+          exit 2
+        fi
+      fi
+      ;;
+  esac
+fi
+
 # ─── Fast allow: not a flow-gated tool ──────────────────────────────────
 # PR11 v2.33.0 expanded the gated set to include all EFFECT tools.
 # Bash is special — handled per-command by the Python enforcer via

package/core/governance/specialist_telemetry.py

@@ -0,0 +1,117 @@
+"""Specialist-dispatch telemetry summarizer (PR1 — Squad Intelligence Upgrade).
+
+Reads ``~/.arkaos/telemetry/specialist-dispatch.jsonl`` (the JSONL stream
+the PreToolUse specialist-enforcer appends to on every gated decision)
+and produces compact summaries for ``/arka status`` and tuning.
+
+Mirrors the pattern of ``core.governance.enforcement_telemetry`` so
+periods, malformed-line tolerance, and zero-division safety behave the
+same way across telemetry surfaces. Read-only.
+"""
+
+from __future__ import annotations
+
+import json
+from collections import Counter
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+DEFAULT_PATH: Path = (
+    Path.home() / ".arkaos" / "telemetry" / "specialist-dispatch.jsonl"
+)
+_VALID_PERIODS: frozenset[str] = frozenset({"today", "week", "month", "all"})
+_TOP_N: int = 5
+
+
+@dataclass(frozen=True)
+class SpecialistSummary:
+    """Aggregated specialist-dispatch telemetry over a time slice."""
+    period: str
+    total_calls: int
+    blocked_calls: int
+    block_rate: float
+    bypass_used: int
+    top_blocked_personas: list[tuple[str, int]] = field(default_factory=list)
+    top_owners_required: list[tuple[str, int]] = field(default_factory=list)
+    corrupt_line_count: int = 0
+
+
+def summarise(period: str, *, path: Path | None = None) -> SpecialistSummary:
+    if period not in _VALID_PERIODS:
+        raise ValueError(f"invalid period: {period!r}")
+    src = path or DEFAULT_PATH
+    cutoff = _period_cutoff(period)
+    entries, corrupt = _read_jsonl(src, cutoff)
+    return _build_summary(period, entries, corrupt)
+
+
+def _period_cutoff(period: str, now: datetime | None = None) -> datetime | None:
+    ref = now or datetime.now(timezone.utc)
+    if period == "today":
+        return ref.replace(hour=0, minute=0, second=0, microsecond=0)
+    if period == "week":
+        return ref - timedelta(days=7)
+    if period == "month":
+        return ref - timedelta(days=30)
+    return None
+
+
+def _read_jsonl(
+    src: Path, cutoff: datetime | None
+) -> tuple[list[dict[str, Any]], int]:
+    if not src.exists():
+        return [], 0
+    entries: list[dict[str, Any]] = []
+    corrupt = 0
+    try:
+        with src.open("r", encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                if not line.strip():
+                    continue
+                try:
+                    entry = json.loads(line)
+                except json.JSONDecodeError:
+                    corrupt += 1
+                    continue
+                if cutoff is not None:
+                    ts_raw = entry.get("ts", "")
+                    try:
+                        ts = datetime.fromisoformat(ts_raw)
+                    except (TypeError, ValueError):
+                        corrupt += 1
+                        continue
+                    if ts < cutoff:
+                        continue
+                entries.append(entry)
+    except OSError:
+        return entries, corrupt
+    return entries, corrupt
+
+
+def _build_summary(
+    period: str, entries: list[dict[str, Any]], corrupt: int
+) -> SpecialistSummary:
+    total = len(entries)
+    blocked = sum(1 for e in entries if e.get("allow") is False)
+    bypass = sum(1 for e in entries if e.get("bypass_used") is True)
+    rate = (blocked / total) if total else 0.0
+    persona_counter: Counter[str] = Counter()
+    owner_counter: Counter[str] = Counter()
+    for e in entries:
+        if e.get("allow") is False:
+            persona = e.get("current_persona") or "unknown"
+            persona_counter[persona] += 1
+            for owner in e.get("required_owners", []) or []:
+                owner_counter[owner] += 1
+    return SpecialistSummary(
+        period=period,
+        total_calls=total,
+        blocked_calls=blocked,
+        block_rate=rate,
+        bypass_used=bypass,
+        top_blocked_personas=persona_counter.most_common(_TOP_N),
+        top_owners_required=owner_counter.most_common(_TOP_N),
+        corrupt_line_count=corrupt,
+    )

package/core/governance/specialist_telemetry_cli.py

@@ -0,0 +1,51 @@
+"""CLI front-end for specialist-dispatch telemetry.
+
+Usage:
+    python -m core.governance.specialist_telemetry_cli today
+    python -m core.governance.specialist_telemetry_cli week
+    python -m core.governance.specialist_telemetry_cli month
+    python -m core.governance.specialist_telemetry_cli all
+"""
+
+from __future__ import annotations
+
+import sys
+
+from core.governance.specialist_telemetry import summarise
+
+
+def _format_human(summary) -> str:
+    pct = f"{summary.block_rate * 100:.1f}%"
+    lines = [
+        f"Specialist Dispatch Telemetry — {summary.period}",
+        f"  Total calls:       {summary.total_calls}",
+        f"  Blocked:           {summary.blocked_calls} ({pct})",
+        f"  Bypasses used:     {summary.bypass_used}",
+    ]
+    if summary.top_blocked_personas:
+        lines.append("  Top blocked personas:")
+        for persona, count in summary.top_blocked_personas:
+            lines.append(f"    - {persona}: {count}")
+    if summary.top_owners_required:
+        lines.append("  Top owners required:")
+        for owner, count in summary.top_owners_required:
+            lines.append(f"    - {owner}: {count}")
+    if summary.corrupt_line_count:
+        lines.append(f"  Corrupt lines:     {summary.corrupt_line_count}")
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = argv if argv is not None else sys.argv[1:]
+    period = args[0] if args else "today"
+    try:
+        summary = summarise(period)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    print(_format_human(summary))
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())