arkaos 2.13.0 → 2.15.0

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)

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

@@ -0,0 +1,15 @@
+name: spec-driven-gate
+added_in: "2.13.0"
+mandatory: true
+section_title: "Spec-Driven Development"
+detection_pattern: "arka-spec"
+deprecated_in: null
+content: |
+  ## Spec-Driven Development
+
+  Phase 0 of all workflows. No implementation begins without a validated spec.
+
+  - Invocation: automatic before any feature/fix work
+  - Gate: spec must be approved before planning phase starts
+  - Storage: `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
+  - Review: user approval required on written spec

package/core/sync/features/workflow-tiers.yaml

@@ -0,0 +1,19 @@
+name: workflow-tiers
+added_in: "2.12.0"
+mandatory: true
+section_title: "Workflow Tiers"
+detection_pattern: "Enterprise.*phase|Focused.*phase|Specialist.*phase"
+deprecated_in: null
+content: |
+  ## Workflow Tiers
+
+  Three workflow tiers based on task complexity:
+
+  | Tier | Phases | When |
+  |------|--------|------|
+  | Enterprise | 7-10 phases | Complex features, multi-file changes |
+  | Focused | 3-5 phases | Medium tasks, single-domain changes |
+  | Specialist | 1-2 phases | Simple tasks, quick fixes |
+
+  Tier selection is automatic based on complexity assessment.
+  Quality Gate phase is mandatory on ALL tiers.

package/core/sync/manifest.py

@@ -0,0 +1,87 @@
+"""Change Manifest Builder — loads feature specs and computes version diffs."""
+
+from pathlib import Path
+
+import yaml
+
+from core.sync.schema import ChangeManifest, FeatureSpec
+
+_FIRST_SYNC_MARKERS = {"pending-sync", "none", ""}
+
+
+def load_features(features_dir: Path) -> list[FeatureSpec]:
+    """Load all FeatureSpec instances from YAML files in features_dir."""
+    if not features_dir.exists():
+        return []
+
+    features: list[FeatureSpec] = []
+    for path in sorted(features_dir.iterdir()):
+        if path.suffix != ".yaml":
+            continue
+        data = yaml.safe_load(path.read_text())
+        features.append(FeatureSpec(**data))
+
+    return features
+
+
+def build_manifest(
+    previous_version: str,
+    current_version: str,
+    features_dir: Path,
+) -> ChangeManifest:
+    """Build a ChangeManifest comparing previous_version to current_version."""
+    features = load_features(features_dir)
+    is_first = previous_version in _FIRST_SYNC_MARKERS
+
+    new_features = _find_new_features(features, previous_version, is_first)
+    deprecated_features = _find_deprecated_features(features, previous_version, is_first)
+
+    return ChangeManifest(
+        previous_version=previous_version,
+        current_version=current_version,
+        is_first_sync=is_first,
+        features=features,
+        new_features=new_features,
+        deprecated_features=deprecated_features,
+    )
+
+
+def _is_version_newer(version: str, baseline: str) -> bool:
+    """Return True if version is strictly newer than baseline (semver int tuple)."""
+    def parse(v: str) -> tuple[int, ...]:
+        return tuple(int(part) for part in v.split("."))
+
+    return parse(version) > parse(baseline)
+
+
+def _find_new_features(
+    features: list[FeatureSpec],
+    previous_version: str,
+    is_first: bool,
+) -> list[str]:
+    """Return names of features that are new relative to previous_version."""
+    if is_first:
+        return [f.name for f in features if f.deprecated_in is None]
+
+    return [
+        f.name
+        for f in features
+        if _is_version_newer(f.added_in, previous_version)
+    ]
+
+
+def _find_deprecated_features(
+    features: list[FeatureSpec],
+    previous_version: str,
+    is_first: bool,
+) -> list[str]:
+    """Return names of features deprecated after previous_version."""
+    if is_first:
+        return []
+
+    return [
+        f.name
+        for f in features
+        if f.deprecated_in is not None
+        and _is_version_newer(f.deprecated_in, previous_version)
+    ]