arkaos 2.18.1 → 2.19.0

package/VERSION

@@ -1 +1 @@
-2.18.1
+2.19.0

package/config/hooks/cwd-changed.ps1

@@ -43,7 +43,13 @@ if ([string]::IsNullOrWhiteSpace($newCwd)) { exit 0 }
 if (-not (Test-Path -LiteralPath $newCwd -PathType Container)) { exit 0 }
 
 # ─── Detect ecosystem from ecosystems.json ─────────────────────────────
-$ecosystemsFile = Join-Path $env:USERPROFILE '.claude\skills\arka\knowledge\ecosystems.json'
+# Canonical path is %USERPROFILE%\.arkaos\ecosystems.json (ADR 2026-04-17).
+# Falls back to the legacy skill-dir path until v2.21.0.
+$ecosystemsFile = Join-Path $env:USERPROFILE '.arkaos\ecosystems.json'
+if (-not (Test-Path -LiteralPath $ecosystemsFile)) {
+    $legacyEcosystems = Join-Path $env:USERPROFILE '.claude\skills\arka\knowledge\ecosystems.json'
+    if (Test-Path -LiteralPath $legacyEcosystems) { $ecosystemsFile = $legacyEcosystems }
+}
 $ecosystem = ''
 $ecosystemName = ''
 
@@ -115,15 +121,17 @@ if (Test-Path -LiteralPath $composerJson) {
 
 # ─── Check for project descriptor ─────────────────────────────────────
 $dirName = Split-Path -Leaf $newCwd.TrimEnd('\','/')
-$projectsDir   = Join-Path $env:USERPROFILE '.claude\skills\arka\projects'
-$descriptorFile = Join-Path $projectsDir "$dirName.md"
-$descriptorDir  = Join-Path (Join-Path $projectsDir $dirName) 'PROJECT.md'
+$newProjectsDir    = Join-Path $env:USERPROFILE '.arkaos\projects'
+$legacyProjectsDir = Join-Path $env:USERPROFILE '.claude\skills\arka\projects'
 
 $descriptor = ''
-if (Test-Path -LiteralPath $descriptorFile) {
-    $descriptor = $descriptorFile
-} elseif (Test-Path -LiteralPath $descriptorDir) {
-    $descriptor = $descriptorDir
+foreach ($candidate in @(
+    (Join-Path $newProjectsDir    "$dirName.md"),
+    (Join-Path (Join-Path $newProjectsDir    $dirName) 'PROJECT.md'),
+    (Join-Path $legacyProjectsDir "$dirName.md"),
+    (Join-Path (Join-Path $legacyProjectsDir $dirName) 'PROJECT.md')
+)) {
+    if (Test-Path -LiteralPath $candidate) { $descriptor = $candidate; break }
 }
 
 # ─── Build context output ─────────────────────────────────────────────

package/config/hooks/cwd-changed.sh

@@ -13,7 +13,13 @@ if [ -z "$NEW_CWD" ] || [ ! -d "$NEW_CWD" ]; then
 fi
 
 # ─── Detect ecosystem from ecosystems.json ─────────────────────────────
-ECOSYSTEMS_FILE="$HOME/.claude/skills/arka/knowledge/ecosystems.json"
+# Canonical path is ~/.arkaos/ecosystems.json (ADR 2026-04-17). During the
+# deprecation window we fall back to the legacy skill-dir path. The legacy
+# fallback is removed in v2.21.0.
+ECOSYSTEMS_FILE="$HOME/.arkaos/ecosystems.json"
+if [ ! -f "$ECOSYSTEMS_FILE" ] && [ -f "$HOME/.claude/skills/arka/knowledge/ecosystems.json" ]; then
+  ECOSYSTEMS_FILE="$HOME/.claude/skills/arka/knowledge/ecosystems.json"
+fi
 ECOSYSTEM=""
 ECOSYSTEM_NAME=""
 
@@ -75,16 +81,19 @@ elif [ -f "$NEW_CWD/pyproject.toml" ]; then
 fi
 
 # ─── Check for project descriptor ─────────────────────────────────────
+# New canonical path: ~/.arkaos/projects/. Legacy fallback remains until v2.21.0.
 DIR_NAME=$(basename "$NEW_CWD")
 DESCRIPTOR=""
-DESCRIPTOR_FILE="$HOME/.claude/skills/arka/projects/${DIR_NAME}.md"
-DESCRIPTOR_DIR="$HOME/.claude/skills/arka/projects/${DIR_NAME}/PROJECT.md"
-
-if [ -f "$DESCRIPTOR_FILE" ]; then
-  DESCRIPTOR="$DESCRIPTOR_FILE"
-elif [ -f "$DESCRIPTOR_DIR" ]; then
-  DESCRIPTOR="$DESCRIPTOR_DIR"
-fi
+for CANDIDATE in \
+  "$HOME/.arkaos/projects/${DIR_NAME}.md" \
+  "$HOME/.arkaos/projects/${DIR_NAME}/PROJECT.md" \
+  "$HOME/.claude/skills/arka/projects/${DIR_NAME}.md" \
+  "$HOME/.claude/skills/arka/projects/${DIR_NAME}/PROJECT.md"; do
+  if [ -f "$CANDIDATE" ]; then
+    DESCRIPTOR="$CANDIDATE"
+    break
+  fi
+done
 
 # ─── Build context output ─────────────────────────────────────────────
 CONTEXT=""

package/core/runtime/user_paths.py

@@ -0,0 +1,115 @@
+"""Canonical resolver for ArkaOS user-local data paths.
+
+User-mutable data lives under ~/.arkaos/. The installed skill bundle at
+~/.claude/skills/arka/ is read-only and installer-managed. Two historical
+paths still receive user writes in some installs:
+
+    ~/.claude/skills/arka/projects/*.md
+    ~/.claude/skills/arka/knowledge/ecosystems.json
+
+This module returns the canonical new path when present, falls back to the
+legacy path with a one-shot deprecation warning, and returns None when
+neither exists. Callers treat None as empty. See ADR
+docs/adr/2026-04-17-user-data-separation.md.
+
+Legacy fallback sunsets in v2.21.0.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_LEGACY_SKILLS_ROOT = Path.home() / ".claude" / "skills" / "arka"
+_USER_DATA_ROOT = Path.home() / ".arkaos"
+
+_warned: set[str] = set()
+
+
+def user_data_root() -> Path:
+    """Root directory for ArkaOS user-local state."""
+    return _USER_DATA_ROOT
+
+
+def projects_dir() -> Path | None:
+    """Resolve the user projects directory.
+
+    Returns the new path when it exists, else the legacy path with a
+    one-shot deprecation warning, else None.
+    """
+    new = _USER_DATA_ROOT / "projects"
+    legacy = _LEGACY_SKILLS_ROOT / "projects"
+    return _resolve_with_fallback("projects_dir", new, legacy)
+
+
+def ecosystems_file() -> Path | None:
+    """Resolve the ecosystems registry file.
+
+    Returns the new path when it exists, else the legacy path with a
+    one-shot deprecation warning, else None.
+    """
+    new = _USER_DATA_ROOT / "ecosystems.json"
+    legacy = _LEGACY_SKILLS_ROOT / "knowledge" / "ecosystems.json"
+    return _resolve_with_fallback("ecosystems_file", new, legacy)
+
+
+def projects_dir_for_write() -> Path:
+    """Return the write target for user project descriptors.
+
+    Writers always target the new path. The directory is created if absent.
+    """
+    new = _USER_DATA_ROOT / "projects"
+    new.mkdir(parents=True, exist_ok=True)
+    return new
+
+
+def ecosystems_file_for_write() -> Path:
+    """Return the write target for the ecosystems registry.
+
+    Writers always target the new path. Parent directory is created if absent.
+    """
+    new = _USER_DATA_ROOT / "ecosystems.json"
+    new.parent.mkdir(parents=True, exist_ok=True)
+    return new
+
+
+def legacy_projects_dir() -> Path:
+    """Legacy projects directory (for migration tooling only)."""
+    return _LEGACY_SKILLS_ROOT / "projects"
+
+
+def legacy_ecosystems_file() -> Path:
+    """Legacy ecosystems file (for migration tooling only)."""
+    return _LEGACY_SKILLS_ROOT / "knowledge" / "ecosystems.json"
+
+
+def reset_warnings() -> None:
+    """Clear the per-process deprecation warning cache.
+
+    Intended for tests. Real runtime should emit each warning exactly once.
+    """
+    _warned.clear()
+
+
+def _resolve_with_fallback(kind: str, new: Path, legacy: Path) -> Path | None:
+    if new.exists():
+        return new
+    if legacy.exists():
+        _warn_once(kind, legacy)
+        return legacy
+    return None
+
+
+def _warn_once(kind: str, legacy: Path) -> None:
+    if kind in _warned:
+        return
+    _warned.add(kind)
+    logger.warning(
+        "ArkaOS: reading %s from legacy location %s. "
+        "This path is deprecated and will be removed in v2.21.0. "
+        "Run `npx arkaos@latest migrate-user-data` or `/arka update` to move your data to ~/.arkaos/.",
+        kind,
+        legacy,
+    )

package/core/sync/engine.py

@@ -11,6 +11,10 @@ import re
 import sys
 from pathlib import Path
 
+from core.runtime.user_paths import (
+    ecosystems_file as resolve_ecosystems_file,
+    projects_dir as resolve_projects_dir,
+)
 from core.sync.manifest import build_manifest
 from core.sync.discovery import discover_all_projects
 from core.sync.mcp_optimizer import optimize_all_mcps
@@ -169,13 +173,29 @@ def _parse_scan_dirs(projects_dir_str: str) -> list[Path]:
 
 
 def _discover_projects(arkaos_home: Path, skills_dir: Path) -> list:
-    """Combine profile.json dirs, descriptor dir, and ecosystems into projects."""
-    descriptor_dir = skills_dir / "arka" / "projects"
-    ecosystems_file = skills_dir / "arka" / "knowledge" / "ecosystems.json"
+    """Combine profile.json dirs, descriptor dir, and ecosystems into projects.
+
+    Project descriptors and the ecosystems registry are user-local data and
+    live under ~/.arkaos/ (see ADR 2026-04-17-user-data-separation). During
+    the deprecation window, reads fall back to the legacy paths under
+    skills_dir with a one-shot warning. `skills_dir` is kept in the
+    signature for backward compatibility and test ergonomics but is no
+    longer consulted for user data.
+    """
+    del skills_dir  # retained for signature stability; unused.
+
+    descriptor_dir = resolve_projects_dir()
+    ecosystems_path = resolve_ecosystems_file()
+
+    # discover_all_projects treats missing paths as empty; pass a stable
+    # sentinel when the resolver returned None so downstream .exists()
+    # checks short-circuit cleanly.
+    descriptor_dir = descriptor_dir or (Path.home() / ".arkaos" / "projects")
+    ecosystems_path = ecosystems_path or (Path.home() / ".arkaos" / "ecosystems.json")
 
     scan_dirs = _load_scan_dirs_from_profile(arkaos_home)
 
-    return discover_all_projects(descriptor_dir, scan_dirs, ecosystems_file)
+    return discover_all_projects(descriptor_dir, scan_dirs, ecosystems_path)
 
 
 def _load_scan_dirs_from_profile(arkaos_home: Path) -> list[Path]:

package/installer/cli.js

@@ -41,6 +41,7 @@ Usage:
   npx arkaos init             Initialize project config (.arkaos.json)
   npx arkaos update           Update to latest version
   npx arkaos migrate          Migrate from v1 to v2
+  npx arkaos migrate-user-data  Move user data (~/.claude/skills/arka/ → ~/.arkaos/)
   npx arkaos dashboard        Start monitoring dashboard
   npx arkaos keys             Manage API keys (OpenAI, fal.ai, etc.)
   npx arkaos doctor           Run health checks
@@ -102,6 +103,12 @@ async function main() {
       await migrate();
       break;
 
+    case "migrate-user-data": {
+      const { migrateUserData, printMigrationReport } = await import("./migrate-user-data.js");
+      printMigrationReport(migrateUserData());
+      break;
+    }
+
     case "keys": {
       const { keys: keysCmd } = await import("./keys.js");
       await keysCmd(positionals.slice(1));

package/installer/index.js

@@ -34,8 +34,28 @@ export async function install({ runtime, path, force }) {
   // ═══ Step 1: Create directories ═══
   step(1, 14, "Creating directories...");
   ensureDir(installDir);
-  const dirs = ["config", "config/hooks", "agents", "media", "session-digests", "vault"];
+  const dirs = ["config", "config/hooks", "agents", "media", "session-digests", "vault", "projects", "logs"];
   for (const d of dirs) ensureDir(join(installDir, d));
+
+  // Seed an empty ecosystems.json the first time; never overwrite existing user data.
+  const ecosystemsPath = join(installDir, "ecosystems.json");
+  if (!existsSync(ecosystemsPath)) {
+    writeFileSync(
+      ecosystemsPath,
+      JSON.stringify(
+        {
+          _meta: {
+            description: "ArkaOS — user-local ecosystem registry",
+            note: "Populated by /arka onboard. Never committed to the public repo.",
+            updated: new Date().toISOString().slice(0, 10),
+          },
+          ecosystems: {},
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+  }
   ok(`${dirs.length + 1} directories ready`);
 
   // ═══ Step 2: Detect v1 installation ═══

package/installer/migrate-user-data.js

@@ -0,0 +1,110 @@
+import { existsSync, mkdirSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const LEGACY_SKILLS_ROOT = join(homedir(), ".claude", "skills", "arka");
+const USER_DATA_ROOT = join(homedir(), ".arkaos");
+
+const LEGACY_PROJECTS = join(LEGACY_SKILLS_ROOT, "projects");
+const LEGACY_ECOSYSTEMS = join(LEGACY_SKILLS_ROOT, "knowledge", "ecosystems.json");
+const NEW_PROJECTS = join(USER_DATA_ROOT, "projects");
+const NEW_ECOSYSTEMS = join(USER_DATA_ROOT, "ecosystems.json");
+const LOGS_DIR = join(USER_DATA_ROOT, "logs");
+
+/**
+ * Move user-local project descriptors and ecosystems registry from the
+ * legacy skill directory to ~/.arkaos/. Idempotent: items already present
+ * at the destination are left alone and logged as conflicts.
+ *
+ * @returns {{ moved: string[], skipped: string[], conflicts: string[], logPath: string|null }}
+ */
+export function migrateUserData({ dryRun = false } = {}) {
+  const moved = [];
+  const skipped = [];
+  const conflicts = [];
+
+  if (!existsSync(USER_DATA_ROOT)) {
+    mkdirSync(USER_DATA_ROOT, { recursive: true });
+  }
+  if (!existsSync(NEW_PROJECTS)) {
+    mkdirSync(NEW_PROJECTS, { recursive: true });
+  }
+
+  if (existsSync(LEGACY_PROJECTS) && statSync(LEGACY_PROJECTS).isDirectory()) {
+    for (const entry of readdirSync(LEGACY_PROJECTS)) {
+      const src = join(LEGACY_PROJECTS, entry);
+      const dst = join(NEW_PROJECTS, entry);
+      if (existsSync(dst)) {
+        conflicts.push(`projects/${entry}: destination already present, left source untouched`);
+        continue;
+      }
+      if (dryRun) {
+        moved.push(`projects/${entry} (dry-run)`);
+      } else {
+        try {
+          renameSync(src, dst);
+          moved.push(`projects/${entry}`);
+        } catch (err) {
+          conflicts.push(`projects/${entry}: ${err.message}`);
+        }
+      }
+    }
+  } else {
+    skipped.push("projects/: legacy directory absent");
+  }
+
+  if (existsSync(LEGACY_ECOSYSTEMS)) {
+    if (existsSync(NEW_ECOSYSTEMS)) {
+      conflicts.push("ecosystems.json: destination already present, left source untouched");
+    } else if (dryRun) {
+      moved.push("ecosystems.json (dry-run)");
+    } else {
+      try {
+        renameSync(LEGACY_ECOSYSTEMS, NEW_ECOSYSTEMS);
+        moved.push("ecosystems.json");
+      } catch (err) {
+        conflicts.push(`ecosystems.json: ${err.message}`);
+      }
+    }
+  } else {
+    skipped.push("ecosystems.json: legacy file absent");
+  }
+
+  let logPath = null;
+  if (moved.length > 0 || conflicts.length > 0) {
+    if (!existsSync(LOGS_DIR)) mkdirSync(LOGS_DIR, { recursive: true });
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    logPath = join(LOGS_DIR, `migration-${stamp}.log`);
+    const body = [
+      `ArkaOS user-data migration — ${new Date().toISOString()}`,
+      `Source: ${LEGACY_SKILLS_ROOT}`,
+      `Destination: ${USER_DATA_ROOT}`,
+      `Dry-run: ${dryRun}`,
+      "",
+      `Moved (${moved.length}):`,
+      ...moved.map(m => `  - ${m}`),
+      "",
+      `Conflicts (${conflicts.length}):`,
+      ...conflicts.map(c => `  - ${c}`),
+      "",
+      `Skipped (${skipped.length}):`,
+      ...skipped.map(s => `  - ${s}`),
+      "",
+    ].join("\n");
+    if (!dryRun) writeFileSync(logPath, body);
+  }
+
+  return { moved, skipped, conflicts, logPath };
+}
+
+export function printMigrationReport(result) {
+  const { moved, conflicts, logPath } = result;
+  if (moved.length === 0 && conflicts.length === 0) {
+    console.log("  ✓ User data already migrated, nothing to move.");
+    return;
+  }
+  console.log(`  ✓ Migration: ${moved.length} moved, ${conflicts.length} conflicts`);
+  for (const m of moved) console.log(`    + ${m}`);
+  for (const c of conflicts) console.log(`    ! ${c}`);
+  if (logPath) console.log(`  Log: ${logPath}`);
+}

package/installer/update.js

@@ -5,6 +5,7 @@ import { execSync } from "node:child_process";
 import { ensureVenv, getArkaosPython, pipInstall } from "./python-resolver.js";
 import { getRuntimeConfig } from "./detect-runtime.js";
 import { loadAdapter } from "./index.js";
+import { migrateUserData, printMigrationReport } from "./migrate-user-data.js";
 import { IS_WINDOWS, HOOK_EXT } from "./platform.js";
 import { fileURLToPath } from "node:url";
 
@@ -37,6 +38,14 @@ export async function update() {
     console.log(`         \u26a0 Legacy hook state migration skipped: ${err.message}`);
   }
 
+  // User-data separation (ADR 2026-04-17): move descriptors and ecosystems
+  // from ~/.claude/skills/arka/ to ~/.arkaos/. Idempotent, non-destructive.
+  try {
+    printMigrationReport(migrateUserData());
+  } catch (err) {
+    console.log(`         \u26a0 User-data migration skipped: ${err.message}`);
+  }
+
   const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
   const profile = existsSync(profilePath) ? JSON.parse(readFileSync(profilePath, "utf-8")) : {};
 

package/knowledge/ecosystems.json

@@ -2,7 +2,7 @@
   "_meta": {
     "description": "ARKA OS — Project Ecosystem Registry (user-local, populated after install)",
     "format": "Ecosystems group related projects that share squads, stacks, and conventions.",
-    "note": "This file ships empty. Users define their own ecosystems locally via /arka onboard or by editing ~/.claude/skills/arka/knowledge/ecosystems.json after installation. Client names and internal project data MUST NOT be committed to the public repository.",
+    "note": "This file ships empty. Users define their own ecosystems locally in ~/.arkaos/ecosystems.json (populated by /arka onboard). Client names and internal project data MUST NOT be committed to the public repository.",
     "updated": "2026-04-17"
   },
   "ecosystems": {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "2.18.1",
+  "version": "2.19.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "2.18.1"
+version = "2.19.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}