arkaos 2.14.0 → 2.15.0

package/VERSION

@@ -1 +1 @@
-2.14.0
+2.15.0

package/core/sync/__init__.py

@@ -0,0 +1,25 @@
+"""ArkaOS Sync Engine — Hybrid sync for /arka update."""
+
+from core.sync.engine import run_sync
+from core.sync.schema import (
+    ChangeManifest,
+    DescriptorSyncResult,
+    FeatureSpec,
+    McpSyncResult,
+    Project,
+    SettingsSyncResult,
+    SkillSyncResult,
+    SyncReport,
+)
+
+__all__ = [
+    "run_sync",
+    "ChangeManifest",
+    "DescriptorSyncResult",
+    "FeatureSpec",
+    "McpSyncResult",
+    "Project",
+    "SettingsSyncResult",
+    "SkillSyncResult",
+    "SyncReport",
+]

package/core/sync/descriptor_syncer.py

@@ -0,0 +1,166 @@
+"""Descriptor syncer for the ArkaOS Sync Engine.
+
+Syncs project descriptor YAML frontmatter: auto-pauses inactive projects,
+archives missing paths, and updates detected stacks.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+
+import yaml
+
+from core.sync.schema import DescriptorSyncResult, Project
+
+_PAUSE_THRESHOLD_DAYS = 30
+_REACTIVATE_THRESHOLD_DAYS = 7
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def sync_descriptor(project: Project) -> DescriptorSyncResult:
+    """Sync a single project's descriptor file.
+
+    Reads the descriptor, checks if the project path exists, compares the
+    detected stack, checks git activity, and writes any updates back.
+    """
+    if not project.descriptor_path:
+        return DescriptorSyncResult(path=project.path, status="unchanged")
+
+    desc_path = Path(project.descriptor_path)
+    if not desc_path.exists():
+        return DescriptorSyncResult(path=project.path, status="unchanged")
+
+    try:
+        return _do_sync(project)
+    except Exception as exc:  # noqa: BLE001
+        return DescriptorSyncResult(
+            path=project.path, status="error", error=str(exc)
+        )
+
+
+def _do_sync(project: Project) -> DescriptorSyncResult:
+    """Execute the descriptor sync logic for a single project."""
+    desc_path = Path(project.descriptor_path)  # type: ignore[arg-type]
+    text = desc_path.read_text()
+    frontmatter, body = _split_frontmatter(text)
+    changes: list[str] = []
+
+    if not Path(project.path).exists():
+        frontmatter["status"] = "archived"
+        changes.append("status: archived (path not found)")
+        _write_descriptor(desc_path, frontmatter, body)
+        return DescriptorSyncResult(
+            path=project.path, status="updated", changes=changes
+        )
+
+    _check_stack(frontmatter, project.stack, changes)
+    _check_activity(frontmatter, project.path, changes)
+
+    if not changes:
+        return DescriptorSyncResult(path=project.path, status="unchanged")
+
+    _write_descriptor(desc_path, frontmatter, body)
+    return DescriptorSyncResult(
+        path=project.path, status="updated", changes=changes
+    )
+
+
+def sync_all_descriptors(projects: list[Project]) -> list[DescriptorSyncResult]:
+    """Sync descriptor files for all projects."""
+    return [sync_descriptor(p) for p in projects]
+
+
+# ---------------------------------------------------------------------------
+# Private helpers
+# ---------------------------------------------------------------------------
+
+
+def _split_frontmatter(text: str) -> tuple[dict, str]:
+    """Split a markdown file into its YAML frontmatter dict and body string.
+
+    Expects the file to start with '---' and have a closing '---' marker.
+    Returns ({}, full_text) if frontmatter markers are not found.
+    """
+    if not text.startswith("---"):
+        return {}, text
+
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        return {}, text
+
+    raw_yaml = parts[1]
+    body = parts[2]
+    parsed = yaml.safe_load(raw_yaml) or {}
+    return parsed, body
+
+
+def _normalize_stack_item(item: str) -> str:
+    """Normalize a stack item to lowercase first word for comparison."""
+    return item.strip().lower().split()[0]
+
+
+def _check_stack(
+    frontmatter: dict, detected_stack: list[str], changes: list[str]
+) -> None:
+    """Compare frontmatter stack with detected stack and update if different."""
+    fm_stack: list[str] = frontmatter.get("stack") or []
+    fm_normalized = {_normalize_stack_item(s) for s in fm_stack}
+    detected_normalized = {_normalize_stack_item(s) for s in detected_stack}
+
+    if fm_normalized != detected_normalized and detected_stack:
+        frontmatter["stack"] = detected_stack
+        changes.append(f"stack updated: {fm_stack} -> {detected_stack}")
+
+
+def _check_activity(
+    frontmatter: dict, project_path: str, changes: list[str]
+) -> None:
+    """Check git activity and auto-pause or auto-reactivate the project."""
+    days = _get_last_commit_days(project_path)
+    if days is None:
+        return
+
+    current_status = frontmatter.get("status", "active")
+
+    if days > _PAUSE_THRESHOLD_DAYS and current_status == "active":
+        frontmatter["status"] = "paused"
+        changes.append(f"status: active -> paused ({days}d since last commit)")
+    elif days < _REACTIVATE_THRESHOLD_DAYS and current_status == "paused":
+        frontmatter["status"] = "active"
+        changes.append(f"status: paused -> active ({days}d since last commit)")
+
+
+def _get_last_commit_days(project_path: str) -> int | None:
+    """Return days since the last git commit in project_path, or None."""
+    try:
+        result = subprocess.run(
+            ["git", "log", "-1", "--format=%ci"],
+            cwd=project_path,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        raw = result.stdout.strip()
+        if not raw:
+            return None
+
+        commit_dt = datetime.fromisoformat(raw)
+        if commit_dt.tzinfo is None:
+            commit_dt = commit_dt.replace(tzinfo=timezone.utc)
+
+        now = datetime.now(tz=timezone.utc)
+        return (now - commit_dt).days
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _write_descriptor(desc_path: Path, frontmatter: dict, body: str) -> None:
+    """Write updated frontmatter and preserved body back to the descriptor file."""
+    fm_text = yaml.dump(frontmatter, default_flow_style=False, allow_unicode=True)
+    desc_path.write_text(f"---\n{fm_text}---{body}")

package/core/sync/discovery.py

@@ -0,0 +1,256 @@
+"""Project discovery for the ArkaOS Sync Engine.
+
+Discovers projects from 3 sources: descriptors, filesystem, and ecosystems.
+Detects tech stacks and deduplicates across sources.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import yaml
+
+from core.sync.schema import Project
+
+
+# --- Stack detection helpers ---
+
+def _detect_from_composer(project_path: Path) -> list[str]:
+    composer = project_path / "composer.json"
+    if not composer.exists():
+        return []
+    try:
+        data = json.loads(composer.read_text())
+        require = data.get("require", {})
+        if "laravel/framework" in require:
+            return ["php", "laravel"]
+        return ["php"]
+    except (json.JSONDecodeError, OSError):
+        return []
+
+
+def _detect_from_package_json(project_path: Path) -> list[str]:
+    pkg = project_path / "package.json"
+    if not pkg.exists():
+        return []
+    try:
+        data = json.loads(pkg.read_text())
+        deps = {
+            **data.get("dependencies", {}),
+            **data.get("devDependencies", {}),
+        }
+        stack: list[str] = []
+        if "nuxt" in deps:
+            stack.extend(["javascript", "nuxt", "vue"])
+        elif "vue" in deps:
+            stack.extend(["javascript", "vue"])
+        elif "next" in deps:
+            stack.extend(["javascript", "next", "react"])
+        elif "react" in deps:
+            stack.extend(["javascript", "react"])
+        else:
+            stack.append("javascript")
+        return stack
+    except (json.JSONDecodeError, OSError):
+        return []
+
+
+def _detect_from_pyproject(project_path: Path) -> list[str]:
+    pyproject = project_path / "pyproject.toml"
+    if not pyproject.exists():
+        return []
+    return ["python"]
+
+
+def detect_stack(project_path: Path) -> list[str]:
+    """Detect tech stack from project files.
+
+    Checks composer.json, package.json, and pyproject.toml in order.
+    Returns a deduplicated list of detected technologies.
+    """
+    stack: list[str] = []
+    stack.extend(_detect_from_composer(project_path))
+    stack.extend(_detect_from_package_json(project_path))
+    stack.extend(_detect_from_pyproject(project_path))
+    seen: set[str] = set()
+    result: list[str] = []
+    for item in stack:
+        if item not in seen:
+            seen.add(item)
+            result.append(item)
+    return result
+
+
+# --- Descriptor discovery helpers ---
+
+def _parse_descriptor_frontmatter(text: str) -> dict:
+    """Extract YAML frontmatter from a markdown file."""
+    if not text.startswith("---"):
+        return {}
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        return {}
+    try:
+        return yaml.safe_load(parts[1]) or {}
+    except yaml.YAMLError:
+        return {}
+
+
+def _read_descriptor_item(item: Path) -> dict:
+    """Read a descriptor file and return its frontmatter as a dict."""
+    try:
+        return _parse_descriptor_frontmatter(item.read_text())
+    except OSError:
+        return {}
+
+
+def _process_descriptor_item(item: Path, descriptor_dir: Path) -> "Project | None":
+    """Parse a single descriptor file and return a Project or None."""
+    fm = _read_descriptor_item(item)
+    raw_path = fm.get("path", "")
+    if not raw_path:
+        return None
+    project_path = Path(raw_path)
+    if not project_path.exists():
+        return None
+    name = fm.get("name", project_path.name)
+    stack = detect_stack(project_path)
+    return Project(
+        path=str(project_path),
+        name=name,
+        ecosystem=fm.get("ecosystem") or None,
+        stack=stack,
+        descriptor_path=str(item),
+        has_mcp_json=(project_path / ".mcp.json").exists(),
+        has_settings=(project_path / ".claude").is_dir(),
+    )
+
+
+def discover_from_descriptors(descriptor_dir: Path) -> list[Project]:
+    """Discover projects from .md descriptor files with YAML frontmatter.
+
+    Reads .md files in descriptor_dir and PROJECT.md in subdirectories.
+    Skips entries whose paths don't exist on the filesystem.
+    """
+    if not descriptor_dir.exists():
+        return []
+
+    candidates: list[Path] = list(descriptor_dir.glob("*.md"))
+    for subdir in descriptor_dir.iterdir():
+        if subdir.is_dir():
+            project_md = subdir / "PROJECT.md"
+            if project_md.exists():
+                candidates.append(project_md)
+
+    projects: list[Project] = []
+    for item in candidates:
+        project = _process_descriptor_item(item, descriptor_dir)
+        if project is not None:
+            projects.append(project)
+
+    return projects
+
+
+# --- Filesystem discovery ---
+
+def discover_from_filesystem(scan_dirs: list[Path]) -> list[Project]:
+    """Discover projects by scanning directories for .mcp.json or .claude/ markers."""
+    projects: list[Project] = []
+    for scan_dir in scan_dirs:
+        if not scan_dir.exists():
+            continue
+        for subdir in scan_dir.iterdir():
+            if not subdir.is_dir():
+                continue
+            has_mcp = (subdir / ".mcp.json").is_file()
+            has_claude = (subdir / ".claude").is_dir()
+            has_claude_md = (subdir / "CLAUDE.md").is_file()
+            if not has_mcp and not has_claude and not has_claude_md:
+                continue
+            stack = detect_stack(subdir)
+            projects.append(Project(
+                path=str(subdir),
+                name=subdir.name,
+                stack=stack,
+                has_mcp_json=has_mcp,
+                has_settings=has_claude,
+            ))
+
+    return projects
+
+
+# --- Ecosystem discovery ---
+
+def discover_from_ecosystems(ecosystems_file: Path) -> list[Project]:
+    """Discover projects from an ecosystems.json registry file."""
+    if not ecosystems_file.exists():
+        return []
+    try:
+        data = json.loads(ecosystems_file.read_text())
+    except (json.JSONDecodeError, OSError):
+        return []
+
+    projects: list[Project] = []
+    for eco_key, eco_data in data.get("ecosystems", {}).items():
+        for proj_name, proj_path_str in eco_data.get("project_paths", {}).items():
+            proj_path = Path(proj_path_str)
+            if not proj_path.exists():
+                continue
+            stack = detect_stack(proj_path)
+            projects.append(Project(
+                path=str(proj_path),
+                name=proj_name,
+                ecosystem=eco_key,
+                stack=stack,
+                has_mcp_json=(proj_path / ".mcp.json").exists(),
+                has_settings=(proj_path / ".claude").is_dir(),
+            ))
+
+    return projects
+
+
+# --- Merge and deduplication helpers ---
+
+def _merge_project(primary: Project, secondary: Project) -> Project:
+    """Merge two Project records — primary data wins over secondary."""
+    return Project(
+        path=primary.path,
+        name=primary.name,
+        ecosystem=primary.ecosystem or secondary.ecosystem,
+        stack=primary.stack if primary.stack else secondary.stack,
+        descriptor_path=primary.descriptor_path or secondary.descriptor_path,
+        has_mcp_json=primary.has_mcp_json or secondary.has_mcp_json,
+        has_settings=primary.has_settings or secondary.has_settings,
+    )
+
+
+def _deduplicate(projects: list[Project]) -> list[Project]:
+    """Deduplicate projects by resolved absolute path. First entry wins."""
+    seen: dict[str, Project] = {}
+    for project in projects:
+        key = str(Path(project.path).resolve())
+        if key not in seen:
+            seen[key] = project
+        else:
+            seen[key] = _merge_project(seen[key], project)
+    return list(seen.values())
+
+
+def discover_all_projects(
+    descriptor_dir: Path,
+    scan_dirs: list[Path],
+    ecosystems_file: Path,
+) -> list[Project]:
+    """Discover all projects from all sources, deduplicate, and sort by name.
+
+    Descriptor data wins over filesystem/ecosystem data during merging.
+    """
+    descriptor_projects = discover_from_descriptors(descriptor_dir)
+    filesystem_projects = discover_from_filesystem(scan_dirs)
+    ecosystem_projects = discover_from_ecosystems(ecosystems_file)
+
+    all_projects = descriptor_projects + ecosystem_projects + filesystem_projects
+    deduplicated = _deduplicate(all_projects)
+
+    return sorted(deduplicated, key=lambda p: p.name)

package/core/sync/engine.py

@@ -0,0 +1,177 @@
+"""Engine Orchestrator for the ArkaOS Sync Engine.
+
+Coordinates all sync phases and provides a CLI entry point for /arka update.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+from core.sync.manifest import build_manifest
+from core.sync.discovery import discover_all_projects
+from core.sync.mcp_syncer import sync_all_mcps
+from core.sync.settings_syncer import sync_all_settings
+from core.sync.descriptor_syncer import sync_all_descriptors
+from core.sync.reporter import build_report, format_report, write_sync_state
+from core.sync.schema import SyncReport
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def run_sync(arkaos_home: Path, skills_dir: Path, home_path: str) -> SyncReport:
+    """Orchestrate all deterministic sync phases and return a SyncReport."""
+    previous_version = _read_previous_version(arkaos_home)
+    current_version = _read_current_version(arkaos_home)
+    features_dir = _resolve_features_dir(arkaos_home)
+
+    manifest = build_manifest(previous_version, current_version, features_dir)
+
+    projects = _discover_projects(arkaos_home, skills_dir)
+
+    registry_path = skills_dir / "arka" / "mcps" / "registry.json"
+    mcp_results = sync_all_mcps(projects, registry_path, home_path)
+    settings_results = sync_all_settings(mcp_results)
+    descriptor_results = sync_all_descriptors(projects)
+
+    report = build_report(
+        previous_version,
+        current_version,
+        mcp_results,
+        settings_results,
+        descriptor_results,
+        [],
+        new_features=manifest.new_features,
+        deprecated_features=manifest.deprecated_features,
+    )
+
+    state_file = arkaos_home / "sync-state.json"
+    write_sync_state(state_file, report)
+
+    return report
+
+
+def main() -> None:
+    """CLI entry point for the sync engine."""
+    parser = argparse.ArgumentParser(description="ArkaOS Sync Engine")
+    parser.add_argument("--home", required=True, help="ArkaOS home directory")
+    parser.add_argument("--skills", required=True, help="Skills directory")
+    parser.add_argument(
+        "--output",
+        choices=["text", "json"],
+        default="text",
+        help="Output format",
+    )
+    args = parser.parse_args()
+
+    report = run_sync(
+        arkaos_home=Path(args.home),
+        skills_dir=Path(args.skills),
+        home_path=str(Path.home()),
+    )
+
+    if args.output == "json":
+        print(report.model_dump_json(indent=2))
+    else:
+        print(format_report(report))
+
+
+# ---------------------------------------------------------------------------
+# Private helpers
+# ---------------------------------------------------------------------------
+
+
+def _read_previous_version(arkaos_home: Path) -> str:
+    """Read version field from sync-state.json, defaulting to pending-sync."""
+    state_file = arkaos_home / "sync-state.json"
+    if not state_file.exists():
+        return "pending-sync"
+    try:
+        data = json.loads(state_file.read_text())
+        return data.get("version", "pending-sync") or "pending-sync"
+    except (json.JSONDecodeError, OSError):
+        return "pending-sync"
+
+
+def _read_current_version(arkaos_home: Path) -> str:
+    """Read version from VERSION file in the ArkaOS repo."""
+    repo_path = _read_repo_path(arkaos_home)
+    if repo_path is None:
+        return "unknown"
+    version_file = repo_path / "VERSION"
+    if not version_file.exists():
+        return "unknown"
+    try:
+        return version_file.read_text().strip()
+    except OSError:
+        return "unknown"
+
+
+def _read_repo_path(arkaos_home: Path) -> Path | None:
+    """Read the absolute repo path from .repo-path file."""
+    repo_path_file = arkaos_home / ".repo-path"
+    if not repo_path_file.exists():
+        return None
+    try:
+        raw = repo_path_file.read_text().strip()
+        return Path(raw) if raw else None
+    except OSError:
+        return None
+
+
+def _resolve_features_dir(arkaos_home: Path) -> Path:
+    """Resolve the features directory from repo or fallback config."""
+    repo_path = _read_repo_path(arkaos_home)
+    if repo_path is not None:
+        repo_features = repo_path / "core" / "sync" / "features"
+        if repo_features.exists():
+            return repo_features
+
+    fallback = arkaos_home / "config" / "sync" / "features"
+    return fallback
+
+
+def _parse_scan_dirs(projects_dir_str: str) -> list[Path]:
+    """Parse a projectsDir string, extracting all paths starting with /."""
+    segments = re.split(r",\s*", projects_dir_str.strip())
+    paths: list[Path] = []
+    for segment in segments:
+        match = re.match(r"(/[^\s]+)", segment.strip())
+        if match:
+            paths.append(Path(match.group(1)))
+    return paths
+
+
+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"
+
+    scan_dirs = _load_scan_dirs_from_profile(arkaos_home)
+
+    return discover_all_projects(descriptor_dir, scan_dirs, ecosystems_file)
+
+
+def _load_scan_dirs_from_profile(arkaos_home: Path) -> list[Path]:
+    """Read projectsDir from profile.json and parse into scan directory paths."""
+    profile_file = arkaos_home / "profile.json"
+    if not profile_file.exists():
+        return []
+    try:
+        data = json.loads(profile_file.read_text())
+        projects_dir_str = data.get("projectsDir", "")
+        if not projects_dir_str:
+            return []
+        return _parse_scan_dirs(projects_dir_str)
+    except (json.JSONDecodeError, OSError):
+        return []
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/core/sync/features/forge.yaml

@@ -0,0 +1,16 @@
+name: forge-integration
+added_in: "2.14.0"
+mandatory: true
+section_title: "Forge Integration"
+detection_pattern: "arka-forge"
+deprecated_in: null
+content: |
+  ## Forge Integration
+
+  Complex requests (complexity score >= 5) are automatically routed to
+  The Forge for multi-agent planning before execution.
+
+  - Phase 0.5: Forge analysis (after spec creation, before squad planning)
+  - Complexity assessment: automatic via Synapse L8 (ForgeContextLayer)
+  - Manual invocation: `/forge` command
+  - Handoff: Forge outputs structured plan → squad executes phases

package/core/sync/features/quality-gate.yaml

@@ -0,0 +1,15 @@
+name: quality-gate
+added_in: "2.10.0"
+mandatory: true
+section_title: "Quality Gate"
+detection_pattern: "Marta.*CQO|Quality Gate"
+deprecated_in: null
+content: |
+  ## Quality Gate
+
+  Mandatory on every workflow. Nothing ships without approval.
+
+  - **Marta (CQO):** Orchestrates review, absolute veto power
+  - **Eduardo (Copy Director):** Reviews all text output
+  - **Francisca (Tech Director):** Reviews all code and technical output
+  - Verdict: APPROVED or REJECTED (binary, no partial)