arkaos 2.16.1 → 2.17.0

package/VERSION

@@ -1 +1 @@
-2.16.1
+2.17.0

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/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/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))

package/core/sync/content_merger.py

@@ -0,0 +1,100 @@
+"""Managed-region content merger for the ArkaOS Sync Engine.
+
+Merges core-owned content into project files while preserving any
+project-authored content outside the managed region. Uses HTML comment
+markers to delimit the managed block.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass
+from typing import Literal
+
+_START_RE = re.compile(
+    r"<!--\s*arkaos:managed:start(?:\s+version=(?P<version>\S+))?"
+    r"(?:\s+hash=(?P<hash>[0-9a-f]{12}))?\s*-->",
+)
+_END_RE = re.compile(r"<!--\s*arkaos:managed:end\s*-->")
+
+
+@dataclass
+class MergeResult:
+    """Outcome of a managed-region merge operation."""
+
+    status: Literal["updated", "unchanged", "error"]
+    new_text: str
+    error: str | None = None
+
+
+def compute_managed_hash(content: str) -> str:
+    """Return the first 12 hex chars of sha256 over managed content."""
+    return hashlib.sha256(content.encode("utf-8")).hexdigest()[:12]
+
+
+def merge_managed_content(
+    target_text: str, managed_content: str, version: str
+) -> MergeResult:
+    """Merge managed_content into target_text inside the managed region.
+
+    Returns status "updated" when the file changes, "unchanged" when the
+    new hash matches the existing one, or "error" when markers are
+    unbalanced.
+    """
+    starts = list(_START_RE.finditer(target_text))
+    ends = list(_END_RE.finditer(target_text))
+
+    if len(starts) != len(ends):
+        return MergeResult(
+            status="error",
+            new_text=target_text,
+            error=f"unbalanced markers: {len(starts)} starts, {len(ends)} ends",
+        )
+
+    if len(starts) > 1:
+        return MergeResult(
+            status="error",
+            new_text=target_text,
+            error="multiple managed blocks are not supported",
+        )
+
+    new_hash = compute_managed_hash(managed_content)
+    new_block = _render_block(managed_content, version, new_hash)
+
+    if not starts:
+        return _prepend_block(target_text, new_block)
+
+    start_match = starts[0]
+    end_match = ends[0]
+    if end_match.start() < start_match.end():
+        return MergeResult(
+            status="error",
+            new_text=target_text,
+            error="end marker appears before start marker",
+        )
+
+    existing_hash = start_match.group("hash")
+    if existing_hash == new_hash:
+        return MergeResult(status="unchanged", new_text=target_text)
+
+    new_text = (
+        target_text[: start_match.start()]
+        + new_block
+        + target_text[end_match.end() :]
+    )
+    return MergeResult(status="updated", new_text=new_text)
+
+
+def _render_block(content: str, version: str, content_hash: str) -> str:
+    return (
+        f"<!-- arkaos:managed:start version={version} hash={content_hash} -->\n"
+        f"{content}\n"
+        "<!-- arkaos:managed:end -->"
+    )
+
+
+def _prepend_block(target_text: str, new_block: str) -> MergeResult:
+    separator = "\n\n" if target_text else "\n"
+    new_text = f"{new_block}{separator}{target_text}" if target_text else f"{new_block}\n"
+    return MergeResult(status="updated", new_text=new_text)