arkaos 2.16.1 → 2.17.1

package/VERSION

@@ -1 +1 @@
-2.16.1
+2.17.1

package/config/agent-allowlists/_base.yaml

@@ -0,0 +1,7 @@
+# Baseline agents every project gets regardless of stack.
+stack: _base
+baseline:
+  - strategy-director
+  - cqo
+  - copy-director
+  - tech-ux-director

package/config/agent-allowlists/laravel.yaml

@@ -0,0 +1,9 @@
+stack: laravel
+baseline:
+  - backend-dev
+  - senior-dev
+  - architect
+  - qa
+  - devops
+  - security
+  - analyst

package/config/agent-allowlists/node.yaml

@@ -0,0 +1,7 @@
+stack: node
+baseline:
+  - backend-dev
+  - senior-dev
+  - architect
+  - qa
+  - devops

package/config/agent-allowlists/nuxt.yaml

@@ -0,0 +1,7 @@
+stack: nuxt
+baseline:
+  - frontend-dev
+  - backend-dev
+  - architect
+  - qa
+  - devops

package/config/agent-allowlists/python.yaml

@@ -0,0 +1,7 @@
+stack: python
+baseline:
+  - senior-dev
+  - architect
+  - qa
+  - devops
+  - analyst

package/config/hooks/agent-provision.sh

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+# ArkaOS PreToolUse hook for dynamic agent provisioning.
+# Intercepts Task tool calls: if subagent_type is not present in the
+# project's .claude/agents/, copies it from ArkaOS core when available,
+# or blocks with an approval-request message when the agent must be
+# created via `/platform-arka agent provision <name>`.
+
+set -euo pipefail
+
+# Hook contract: stdin is a JSON payload with fields tool_name + tool_input.
+payload="$(cat)"
+
+tool_name="$(echo "$payload" | jq -r '.tool_name // ""')"
+if [ "$tool_name" != "Task" ]; then
+    exit 0
+fi
+
+subagent_type="$(echo "$payload" | jq -r '.tool_input.subagent_type // ""')"
+if [ -z "$subagent_type" ] || [ "$subagent_type" = "null" ]; then
+    exit 0
+fi
+
+# Strict allowlist: lowercase alphanumeric + hyphens, max 64 chars, must start with letter.
+if [[ ! "$subagent_type" =~ ^[a-z][a-z0-9-]{0,63}$ ]]; then
+    # Invalid name — skip hook (do not block) so legitimate workflows continue;
+    # the Task dispatch itself will fail naturally if the agent truly doesn't exist.
+    exit 0
+fi
+
+project_root="$(pwd)"
+project_agents_dir="$project_root/.claude/agents"
+target="$project_agents_dir/${subagent_type}.md"
+
+if [ -f "$target" ]; then
+    exit 0
+fi
+
+# Agent missing locally — try copying from ArkaOS core.
+core_root="${ARKAOS_CORE_ROOT:-}"
+if [ -z "$core_root" ]; then
+    core_root="$(npm root -g 2>/dev/null)/arkaos"
+fi
+
+if [ -d "$core_root/departments" ]; then
+    mkdir -p "$project_agents_dir"
+    set +e
+    python3 - "$core_root" "$subagent_type" "$target" <<'PY'
+import os, re, sys
+from pathlib import Path
+
+core = Path(sys.argv[1]).resolve()
+name = sys.argv[2]
+target = Path(sys.argv[3]).resolve()
+
+if not re.fullmatch(r"[a-z][a-z0-9-]{0,63}", name):
+    sys.exit(2)
+
+departments_root = (core / "departments").resolve()
+if not departments_root.exists():
+    sys.exit(2)
+
+# Ensure target stays within .claude/agents of the project
+expected_parent = target.parent.resolve()
+if target.suffix != ".md" or expected_parent.name != "agents":
+    sys.exit(2)
+
+yaml_path = None
+md_path = None
+for dept in departments_root.iterdir():
+    agents = dept / "agents"
+    if not agents.is_dir():
+        continue
+    y = (agents / f"{name}.yaml").resolve()
+    m = (agents / f"{name}.md").resolve()
+    if y.exists() and yaml_path is None:
+        try:
+            y.relative_to(departments_root)
+        except ValueError:
+            continue
+        yaml_path = y
+    if m.exists() and md_path is None:
+        try:
+            m.relative_to(departments_root)
+        except ValueError:
+            continue
+        md_path = m
+
+if yaml_path is None and md_path is None:
+    sys.exit(2)
+
+parts = []
+if yaml_path is not None:
+    parts.append("---")
+    parts.append(yaml_path.read_text().strip())
+    parts.append("---")
+if md_path is not None:
+    parts.append(md_path.read_text().rstrip())
+
+content = "\n".join(parts) + "\n"
+
+# Atomic write: temp file in same dir, then os.replace.
+tmp = target.with_suffix(".md.tmp")
+tmp.write_text(content)
+os.replace(tmp, target)
+PY
+    rc=$?
+    set -e
+
+    case "$rc" in
+        0)
+            echo "[arka:provisioned] Copied agent '$subagent_type' from ArkaOS core." >&2
+            exit 0
+            ;;
+        2)
+            # Agent not found in core; fall through to approval-request message below.
+            ;;
+        *)
+            echo "[arka:provision-error] Unexpected error ($rc) while provisioning '$subagent_type'. Dispatch not blocked." >&2
+            exit 1
+            ;;
+    esac
+fi
+
+# Agent not in project and not in core — surface an approval-request.
+cat >&2 <<MSG
+[arka:provision-needed] Agent '$subagent_type' is not installed in this
+project and does not exist in ArkaOS core. To create it, run:
+
+    /platform-arka agent provision $subagent_type
+
+This opens the Skill Architect flow which drafts the agent YAML with
+4-framework DNA, goes through Quality Gate, and commits to core before
+propagating to the project. Blocking dispatch until the agent exists.
+MSG
+exit 2

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

@@ -263,8 +263,14 @@ if (-not $pythonResult) {
     $pythonResult = (@($l0, $l4, $l7) | Where-Object { $_ }) -join ' '
 }
 
+# --- Persistent Routing Reminder -------------------------------------------
+# High-salience tag - ensures squad routing persists across conversation turns,
+# and enforces visible KB citation when chunks are present.
+# See: docs/superpowers/specs/2026-04-14-persistent-routing-reminder-design.md
+$routeReminder = '[arka:route] Every response MUST route through a department squad. No generic assistant replies. Announce the squad before responding. When [knowledge:N chunks] is present in this context, you MUST cite at least one source and acknowledge KB was consulted; if absent on a non-trivial ArkaOS topic, query Obsidian before responding.'
+
 # --- Output ----------------------------------------------------------------
-$additionalContext = "$syncNotice$pythonResult"
+$additionalContext = "$syncNotice$routeReminder $pythonResult"
 [pscustomobject]@{ additionalContext = $additionalContext } | ConvertTo-Json -Compress
 
 # --- Metrics (JSONL append) ------------------------------------------------

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

@@ -193,8 +193,14 @@ if [ -f "$_HYGIENE_SCRIPT" ]; then
              bash "$_HYGIENE_SCRIPT" 2>/dev/null)
 fi
 
+# ─── Persistent Routing Reminder ────────────────────────────────────────
+# High-salience tag — ensures squad routing persists across conversation turns,
+# not just on turn 1 when /arka skill content is fresh. See spec:
+# docs/superpowers/specs/2026-04-14-persistent-routing-reminder-design.md
+_ROUTE_REMINDER="[arka:route] Every response MUST route through a department squad. No generic assistant replies. Announce the squad before responding. When [knowledge:N chunks] is present in this context, you MUST cite at least one source and acknowledge KB was consulted; if absent on a non-trivial ArkaOS topic, query Obsidian before responding."
+
 # ─── Output ──────────────────────────────────────────────────────────────
-_OUT_CONTEXT="${_ARKA_GREETING:-}${_SYNC_NOTICE:-}$python_result"
+_OUT_CONTEXT="${_ARKA_GREETING:-}${_SYNC_NOTICE:-}${_ROUTE_REMINDER} $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)

package/config/mcp-policy.yaml

@@ -0,0 +1,36 @@
+# ArkaOS MCP Policy Registry
+# Controls which MCPs load eagerly vs deferred per project stack/ecosystem.
+# Rules evaluated top-to-bottom; first match wins. "ambiguous: ['*']" means
+# all other MCPs defer to AI (or fallback heuristic when AI unavailable).
+
+version: 1
+policies:
+  - match:
+      stack_includes: [laravel, php]
+    active: [context7, gh-grep, postgres, supabase]
+    deferred: [canva, clickup, firecrawl, chrome, gmail, calendar, claude-in-chrome]
+    ambiguous: []
+
+  - match:
+      stack_includes: [nuxt, vue, react, next]
+    active: [context7, gh-grep, playwright, claude-in-chrome]
+    deferred: [postgres, supabase, canva, clickup, gmail, calendar]
+    ambiguous: []
+
+  - match:
+      ecosystem: marketing
+    active: [canva, gmail, calendar, firecrawl, clickup]
+    deferred: [postgres, supabase, playwright]
+    ambiguous: []
+
+  - match:
+      ecosystem: content
+    active: [canva, firecrawl, youtube-transcript]
+    deferred: [postgres, clickup]
+    ambiguous: []
+
+  - match:
+      default: true
+    active: [context7]
+    deferred: []
+    ambiguous: ["*"]

package/config/settings-template.json

@@ -59,6 +59,18 @@
           }
         ]
       }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "{{HOOKS_DIR}}/agent-provision.sh",
+            "timeout": 10
+          }
+        ]
+      }
     ]
   }
 }

package/config/standards/claude-md-overlays/laravel.md

@@ -0,0 +1,8 @@
+## Laravel Stack Conventions
+
+- Services + Repositories pattern; no logic in controllers.
+- Form Requests for all input validation.
+- API Resources for response shaping.
+- Feature Tests with RefreshDatabase trait.
+- Eloquent relationships over raw joins.
+- Conventional commits: `feat(scope): ...`, `fix(scope): ...`.

package/config/standards/claude-md-overlays/node.md

@@ -0,0 +1,7 @@
+## Node.js Stack Conventions
+
+- ESM modules (import/export); no CommonJS `require()`.
+- Support Node and Bun runtimes when writing CLI tooling.
+- Graceful fallbacks when optional dependencies are missing.
+- All paths via `os.homedir()` or `path.join`; never hardcoded.
+- No interactive prompts in headless/CI runs.

package/config/standards/claude-md-overlays/nuxt.md

@@ -0,0 +1,8 @@
+## Nuxt / Vue Stack Conventions
+
+- Composition API only; no Options API.
+- TypeScript everywhere; no plain JS Vue files.
+- `composables/` for shared reactive logic.
+- `useFetch`/`useAsyncData` for server-side data.
+- `~` alias for project root imports.
+- Tailwind for styling; avoid scoped styles unless necessary.

package/config/standards/claude-md-overlays/python.md

@@ -0,0 +1,8 @@
+## Python Stack Conventions
+
+- Type hints on every function signature.
+- Pydantic for validation; dataclasses for pure data.
+- `pytest` with fixtures; no `unittest.TestCase`.
+- Functions under 30 lines; one responsibility.
+- Docstrings on public API only; self-documenting code elsewhere.
+- Virtual environments; never global `pip install`.

package/core/runtime/context_compactor.py

@@ -0,0 +1,63 @@
+"""Rule-based context compactor for subagent handoff.
+
+Builds a compact summary of recent conversation turns, files touched,
+and decisions, sized to fit a token budget. No LLM calls — deterministic
+and zero-latency. An LLM-backed variant may be added later behind a flag
+(see spec: docs/superpowers/specs/2026-04-14-subagent-context-handoff-design.md).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Turn:
+    """A single conversation turn for compaction."""
+    role: str  # "user" | "assistant"
+    content: str
+    files_touched: list[str] = field(default_factory=list)
+
+
+class ContextCompactor:
+    """Builds compact context summaries for subagent handoff."""
+
+    def build(self, turns: list[Turn], max_tokens: int = 600) -> str:
+        if not turns:
+            return ""
+
+        files: list[str] = []
+        for t in turns:
+            for f in t.files_touched:
+                if f not in files:
+                    files.append(f)
+
+        # Walk turns from most recent backwards, fitting into budget.
+        budget = max_tokens
+        if files:
+            files_line = "Files touched: " + ", ".join(files[:20])
+            budget -= len(files_line.split())
+        else:
+            files_line = ""
+
+        recent_summaries: list[str] = []
+        for turn in reversed(turns):
+            snippet = turn.content.strip().replace("\n", " ")
+            words = snippet.split()
+            if not words:
+                continue
+            label = "USER" if turn.role == "user" else "ASSISTANT"
+            line_words = [label + ":"] + words
+            if len(line_words) > budget:
+                line_words = line_words[: max(1, budget)]
+                if len(line_words) <= 1:
+                    break
+            recent_summaries.insert(0, " ".join(line_words))
+            budget -= len(line_words)
+            if budget <= 0:
+                break
+
+        parts = ["## Prior Context"]
+        if files_line:
+            parts.append(files_line)
+        parts.extend(recent_summaries)
+        return "\n".join(parts)

package/core/runtime/subagent.py

@@ -130,12 +130,25 @@ class SubagentDispatcher:
             task_description: What the subagent should do.
             relevant_files: File paths the subagent should read.
             context_summary: Compacted context from prior work.
+                Required when ARKAOS_STRICT_HANDOFF=1; otherwise emits a
+                warning. Use ContextCompactor.build() to construct.
             constraints: Boundaries for the subagent.
             expected_output: What format/content is expected back.
 
         Returns:
             HandoffArtifact ready for dispatch.
         """
+        import os, warnings
+        if not context_summary or not context_summary.strip():
+            msg = (
+                "create_handoff called without context_summary — subagent will "
+                "lack prior conversation context. Use ContextCompactor.build() "
+                "to construct one. Set ARKAOS_STRICT_HANDOFF=1 to enforce."
+            )
+            if os.environ.get("ARKAOS_STRICT_HANDOFF") == "1":
+                raise ValueError(msg)
+            warnings.warn(msg, DeprecationWarning, stacklevel=2)
+
         self._task_counter += 1
         task_id = f"task-{self._task_counter}"
 

package/core/sync/agent_provisioner.py

@@ -0,0 +1,150 @@
+"""Agent provisioner — copies baseline agents into each project's .claude/agents/.
+
+Resolves stack-based allowlists (plus the _base allowlist applied to every
+project), locates source agent files under departments/**/agents/, and
+materializes them as flat markdown files with YAML frontmatter the project's
+Claude Code can consume.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+import yaml
+
+from core.sync.schema import AgentProvisionResult, Project
+
+
+def _core_root() -> Path:
+    env = os.environ.get("ARKAOS_CORE_ROOT")
+    if env:
+        return Path(env)
+    return Path(__file__).resolve().parents[2]
+
+
+def resolve_allowlist(stack: list[str]) -> list[str]:
+    """Return the union of baseline agent names for the given stack tokens."""
+    core = _core_root()
+    allowlist_dir = core / "config" / "agent-allowlists"
+    agents: set[str] = set()
+
+    _extend_from_file(allowlist_dir / "_base.yaml", agents)
+    for stack_name in stack:
+        _extend_from_file(allowlist_dir / f"{stack_name.lower()}.yaml", agents)
+
+    return sorted(agents)
+
+
+def sync_project_agents(project: Project) -> AgentProvisionResult:
+    """Materialize baseline agent markdown files in <project>/.claude/agents/."""
+    try:
+        return _do_sync(project)
+    except Exception as exc:  # noqa: BLE001
+        return AgentProvisionResult(
+            path=project.path, status="error", error=str(exc)
+        )
+
+
+def sync_all_agents(projects: list[Project]) -> list[AgentProvisionResult]:
+    return [sync_project_agents(p) for p in projects]
+
+
+def _extend_from_file(path: Path, agents: set[str]) -> None:
+    if not path.exists():
+        return
+    try:
+        data = yaml.safe_load(path.read_text()) or {}
+    except yaml.YAMLError:
+        return
+    for name in data.get("baseline", []) or []:
+        if isinstance(name, str):
+            agents.add(name)
+
+
+def _do_sync(project: Project) -> AgentProvisionResult:
+    core = _core_root()
+    agents_dir = Path(project.path) / ".claude" / "agents"
+    agents_dir.mkdir(parents=True, exist_ok=True)
+
+    allowlist = resolve_allowlist(project.stack)
+    added, unchanged, errored = _apply_allowlist(core, agents_dir, allowlist)
+
+    status = _status_from_counts(added, unchanged, errored)
+    return AgentProvisionResult(
+        path=project.path,
+        status=status,
+        agents_added=added,
+        agents_unchanged=unchanged,
+        agents_errored=errored,
+    )
+
+
+def _apply_allowlist(
+    core: Path, agents_dir: Path, allowlist: list[str]
+) -> tuple[list[str], list[str], list[str]]:
+    added: list[str] = []
+    unchanged: list[str] = []
+    errored: list[str] = []
+
+    for name in allowlist:
+        rendered = _render_agent(core, name)
+        if rendered is None:
+            errored.append(name)
+            continue
+
+        target = agents_dir / f"{name}.md"
+        if target.exists() and target.read_text() == rendered:
+            unchanged.append(name)
+            continue
+        target.write_text(rendered)
+        added.append(name)
+
+    return added, unchanged, errored
+
+
+def _status_from_counts(
+    added: list[str], unchanged: list[str], errored: list[str]
+) -> str:
+    if errored:
+        return "error"
+    if added:
+        return "updated"
+    return "unchanged"
+
+
+def _render_agent(core: Path, name: str) -> str | None:
+    yaml_path = _find_agent_file(core, name, ".yaml")
+    md_path = _find_agent_file(core, name, ".md")
+
+    if yaml_path is None and md_path is None:
+        return None
+
+    parts: list[str] = []
+    if yaml_path is not None:
+        parts.append("---")
+        parts.append(yaml_path.read_text().strip())
+        parts.append("---")
+    if md_path is not None:
+        parts.append(md_path.read_text().rstrip())
+
+    return "\n".join(parts) + "\n"
+
+
+def _find_agent_file(core: Path, name: str, suffix: str) -> Path | None:
+    # Defense in depth: reject names that could escape the agents dir.
+    if not re.fullmatch(r"[a-z][a-z0-9-]{0,63}", name):
+        return None
+    departments_root = (core / "departments").resolve()
+    if not departments_root.exists():
+        return None
+    for dept in departments_root.iterdir():
+        candidate = (dept / "agents" / f"{name}{suffix}").resolve()
+        try:
+            candidate.relative_to(departments_root)
+        except ValueError:
+            continue
+        if candidate.exists():
+            return candidate
+    return None

package/core/sync/ai_mcp_decider.py

@@ -0,0 +1,86 @@
+"""AI-backed decider for MCPs the policy could not classify.
+
+Falls back to deterministic heuristic (defer all unknowns) when the AI
+is unavailable or a call fails. Decisions are cached on disk keyed by
+(stack, ecosystem, mcp_name) to guarantee idempotence across runs.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Callable
+
+
+class AIUnavailable(RuntimeError):
+    pass
+
+
+AiCaller = Callable[[str, list[str], str | None], str]
+
+
+def decide_ambiguous(
+    ambiguous: list[str],
+    stack: list[str],
+    ecosystem: str | None,
+    cache_path: Path,
+    call_ai: AiCaller | None,
+) -> dict[str, str]:
+    if not ambiguous:
+        return {}
+
+    cache = _load_cache(cache_path)
+    result: dict[str, str] = {}
+
+    for mcp in ambiguous:
+        key = _cache_key(mcp, stack, ecosystem)
+        cached = cache.get(key)
+        if cached in {"active", "deferred"}:
+            result[mcp] = cached
+            continue
+
+        decision = _resolve(mcp, stack, ecosystem, call_ai)
+        result[mcp] = decision
+        cache[key] = decision
+
+    _save_cache(cache_path, cache)
+    return result
+
+
+def _resolve(
+    mcp: str,
+    stack: list[str],
+    ecosystem: str | None,
+    call_ai: AiCaller | None,
+) -> str:
+    if call_ai is None:
+        return "deferred"
+    try:
+        raw = call_ai(mcp, stack, ecosystem)
+    except AIUnavailable:
+        return "deferred"
+    return raw if raw in {"active", "deferred"} else "deferred"
+
+
+def _cache_key(mcp: str, stack: list[str], ecosystem: str | None) -> str:
+    payload = json.dumps(
+        {"mcp": mcp, "stack": sorted(stack), "ecosystem": ecosystem},
+        sort_keys=True,
+        separators=(",", ":"),
+    )
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:16]
+
+
+def _load_cache(path: Path) -> dict[str, str]:
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def _save_cache(path: Path, data: dict[str, str]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, sort_keys=True))