@trac3r/oh-my-god 2.2.11

package/hooks/shadow_manager.py

@@ -0,0 +1,476 @@
+#!/usr/bin/env python3
+"""OMG v1 Shadow Manager
+
+Maintains overlay-style shadow writes and evidence artifacts.
+"""
+from __future__ import annotations
+
+import hashlib
+import importlib
+import json
+import os
+import platform
+import shutil
+import socket
+import sys
+from datetime import datetime, timezone
+from typing import Any
+
+HOOKS_DIR = os.path.dirname(__file__)
+if HOOKS_DIR not in sys.path:
+    sys.path.insert(0, HOOKS_DIR)
+try:
+    from hooks._common import _resolve_project_dir
+    from hooks.security_validators import ensure_path_within_dir, validate_opaque_identifier
+except ImportError:
+    _common = importlib.import_module("_common")
+    security_validators = importlib.import_module("security_validators")
+    _resolve_project_dir = _common._resolve_project_dir
+    ensure_path_within_dir = security_validators.ensure_path_within_dir
+    validate_opaque_identifier = security_validators.validate_opaque_identifier
+
+
+def _project_dir() -> str:
+    return _resolve_project_dir()
+
+
+def _shadow_root(project_dir: str) -> str:
+    return os.path.join(project_dir, ".omg", "shadow")
+
+
+def _evidence_root(project_dir: str) -> str:
+    return os.path.join(project_dir, ".omg", "evidence")
+
+
+def _active_run_path(project_dir: str) -> str:
+    return os.path.join(_shadow_root(project_dir), "active-run")
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _new_run_id() -> str:
+    return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
+
+
+def _validated_run_id(run_id: str) -> str:
+    return validate_opaque_identifier(run_id, "run_id")
+
+
+def _hash_file(path: str) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        while True:
+            chunk = f.read(8192)
+            if not chunk:
+                break
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def ensure_shadow_dirs(project_dir: str) -> None:
+    os.makedirs(_shadow_root(project_dir), exist_ok=True)
+    os.makedirs(_evidence_root(project_dir), exist_ok=True)
+
+
+def set_active_run_id(project_dir: str, run_id: str) -> None:
+    ensure_shadow_dirs(project_dir)
+    run_id = _validated_run_id(run_id)
+    with open(_active_run_path(project_dir), "w", encoding="utf-8") as f:
+        f.write(run_id)
+
+
+def get_active_run_id(project_dir: str) -> str | None:
+    env_id = os.environ.get("OMG_RUN_ID")
+    if env_id:
+        return env_id
+    path = _active_run_path(project_dir)
+    if not os.path.exists(path):
+        return None
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            value = f.read().strip()
+            return value or None
+    except Exception:
+        return None
+
+
+def begin_shadow_run(project_dir: str, metadata: dict[str, Any] | None = None) -> str:
+    run_id = _validated_run_id(get_active_run_id(project_dir) or _new_run_id())
+    run_dir = os.path.join(_shadow_root(project_dir), run_id)
+    os.makedirs(run_dir, exist_ok=True)
+
+    manifest_path = os.path.join(run_dir, "manifest.json")
+    if not os.path.exists(manifest_path):
+        manifest = {
+            "run_id": run_id,
+            "created_at": _utc_now(),
+            "status": "open",
+            "files": [],
+            "metadata": metadata or {},
+        }
+        with open(manifest_path, "w", encoding="utf-8") as f:
+            json.dump(manifest, f, indent=2)
+
+    set_active_run_id(project_dir, run_id)
+    return run_id
+
+
+def _load_manifest(run_dir: str) -> dict[str, Any]:
+    path = os.path.join(run_dir, "manifest.json")
+    if not os.path.exists(path):
+        return {"files": []}
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+            if isinstance(data, dict):
+                data.setdefault("files", [])
+                return data
+            return {"files": []}
+    except Exception:
+        return {"files": []}
+
+
+def _save_manifest(run_dir: str, manifest: dict[str, Any]) -> None:
+    path = os.path.join(run_dir, "manifest.json")
+    manifest["updated_at"] = _utc_now()
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(manifest, f, indent=2)
+
+
+def map_shadow_path(project_dir: str, run_id: str, file_path: str) -> str:
+    run_id = _validated_run_id(run_id)
+    rel = os.path.relpath(os.path.abspath(file_path), os.path.abspath(project_dir))
+    rel = rel.replace("..", "_up_")
+    return os.path.join(_shadow_root(project_dir), run_id, "overlay", rel)
+
+
+def record_shadow_write(
+    project_dir: str,
+    run_id: str,
+    file_path: str,
+    source: str = "tool",
+    step_id: str | None = None,
+) -> dict[str, Any]:
+    run_id = _validated_run_id(run_id)
+    run_dir = os.path.join(_shadow_root(project_dir), run_id)
+    os.makedirs(run_dir, exist_ok=True)
+
+    shadow_path = map_shadow_path(project_dir, run_id, file_path)
+    os.makedirs(os.path.dirname(shadow_path), exist_ok=True)
+
+    abs_file = file_path if os.path.isabs(file_path) else os.path.join(project_dir, file_path)
+    file_existed_before = os.path.exists(abs_file)
+    if file_existed_before:
+        shutil.copy2(abs_file, shadow_path)
+        file_hash = _hash_file(abs_file)
+    else:
+        file_hash = ""
+
+    manifest = _load_manifest(run_dir)
+    rel = os.path.relpath(abs_file, project_dir)
+    entry = {
+        "file": rel,
+        "shadow_file": os.path.relpath(shadow_path, run_dir),
+        "recorded_at": _utc_now(),
+        "source": source,
+        "sha256": file_hash,
+        "file_existed_before": file_existed_before,
+    }
+    if step_id:
+        entry["step_id"] = step_id
+
+    files = manifest.get("files", [])
+    # Replace existing entry for same file.
+    files = [f for f in files if f.get("file") != rel]
+    files.append(entry)
+    manifest["files"] = files
+    _save_manifest(run_dir, manifest)
+
+    return entry
+
+
+def restore_shadow_entry(project_dir: str, run_id: str, step_id: str) -> dict[str, Any]:
+    run_id = _validated_run_id(run_id)
+    run_dir = os.path.join(_shadow_root(project_dir), run_id)
+    manifest = _load_manifest(run_dir)
+    entries = manifest.get("files", [])
+
+    restored: list[str] = []
+    failed: list[dict[str, str]] = []
+
+    selected_entries: list[dict[str, Any]] = []
+    for item in entries:
+        if not isinstance(item, dict):
+            continue
+        item_step_id = str(item.get("step_id", "")).strip()
+        if item_step_id == step_id:
+            selected_entries.append(item)
+
+    if not selected_entries and isinstance(entries, list) and len(entries) == 1:
+        single = entries[0]
+        if isinstance(single, dict):
+            selected_entries = [single]
+
+    if not selected_entries:
+        return {"restored": restored, "failed": failed, "reason": "step not found"}
+
+    for item in selected_entries:
+        rel = str(item.get("file", "")).strip()
+        shadow_rel = str(item.get("shadow_file", "")).strip()
+        file_existed_before = bool(item.get("file_existed_before", True))
+        if not rel:
+            failed.append({"file": "", "reason": "missing file path"})
+            continue
+
+        dst = os.path.join(project_dir, rel)
+        src = os.path.join(run_dir, shadow_rel) if shadow_rel else ""
+
+        if src and os.path.exists(src):
+            try:
+                os.makedirs(os.path.dirname(dst), exist_ok=True)
+                shutil.copy2(src, dst)
+                restored.append(rel)
+            except Exception as exc:
+                failed.append({"file": rel, "reason": f"copy failed: {exc}"})
+            continue
+
+        if not file_existed_before:
+            try:
+                if os.path.exists(dst):
+                    os.remove(dst)
+                restored.append(rel)
+            except Exception as exc:
+                failed.append({"file": rel, "reason": f"delete failed: {exc}"})
+            continue
+
+        failed.append({"file": rel, "reason": "shadow snapshot missing"})
+
+    manifest["status"] = "restored"
+    manifest["restored_at"] = _utc_now()
+    _save_manifest(run_dir, manifest)
+
+    reason = "shadow restore applied" if restored and not failed else "shadow restore partial"
+    if not restored and failed:
+        reason = "shadow restore failed"
+    return {"restored": restored, "failed": failed, "reason": reason}
+
+
+def create_evidence_pack(
+    project_dir: str,
+    run_id: str,
+    tests: list[dict[str, Any]] | None = None,
+    security_scans: list[dict[str, Any]] | None = None,
+    diff_summary: dict[str, Any] | None = None,
+    reproducibility: dict[str, Any] | None = None,
+    unresolved_risks: list[str] | None = None,
+    provenance: list[dict[str, Any]] | None = None,
+    trust_scores: dict[str, Any] | None = None,
+    api_twin: dict[str, Any] | None = None,
+    route_metadata: dict[str, Any] | None = None,
+    trace_ids: list[str] | None = None,
+    lineage: dict[str, Any] | None = None,
+    executor: dict[str, Any] | None = None,
+    environment: dict[str, Any] | None = None,
+    artifacts: list[dict[str, Any]] | None = None,
+    claims: list[dict[str, Any]] | None = None,
+    test_delta: dict[str, Any] | None = None,
+    browser_evidence_path: str | None = None,
+    repro_pack_path: str | None = None,
+) -> str:
+    ensure_shadow_dirs(project_dir)
+    run_id = _validated_run_id(run_id)
+    
+    # Default executor if not provided
+    if executor is None:
+        executor = {
+            "user": os.getenv("USER", "unknown"),
+            "pid": str(os.getpid()),
+        }
+    
+    # Default environment if not provided
+    if environment is None:
+        environment = {
+            "hostname": socket.gethostname(),
+            "platform": platform.system(),
+        }
+    
+    evidence = {
+        "schema": "EvidencePack",
+        "schema_version": 2,
+        "run_id": run_id,
+        "created_at": _utc_now(),
+        "tests": tests or [],
+        "security_scans": security_scans or [],
+        "diff_summary": diff_summary or {},
+        "reproducibility": reproducibility or {},
+        "unresolved_risks": unresolved_risks or [],
+        "provenance": provenance or [],
+        "trust_scores": trust_scores or {},
+        "api_twin": api_twin or {},
+        "route_metadata": route_metadata or {},
+        "trace_ids": trace_ids or [],
+        "lineage": lineage or {},
+        "executor": executor,
+        "environment": environment,
+        "artifacts": artifacts or [],
+    }
+    if claims is not None:
+        evidence["claims"] = claims
+    if test_delta is not None:
+        evidence["test_delta"] = test_delta
+    if browser_evidence_path is not None:
+        evidence["browser_evidence_path"] = browser_evidence_path
+    if repro_pack_path is not None:
+        evidence["repro_pack_path"] = repro_pack_path
+    evidence_path = ensure_path_within_dir(
+        _evidence_root(project_dir),
+        os.path.join(_evidence_root(project_dir), f"{run_id}.json"),
+    )
+    with open(evidence_path, "w", encoding="utf-8") as f:
+        json.dump(evidence, f, indent=2)
+    return evidence_path
+
+
+def has_recent_evidence(project_dir: str, hours: int = 24) -> bool:
+    ev_dir = _evidence_root(project_dir)
+    if not os.path.isdir(ev_dir):
+        return False
+
+    now = datetime.now(timezone.utc).timestamp()
+    max_age = hours * 3600
+
+    for name in os.listdir(ev_dir):
+        if not name.endswith(".json"):
+            continue
+        path = os.path.join(ev_dir, name)
+        try:
+            age = now - os.path.getmtime(path)
+            if age <= max_age:
+                return True
+        except OSError:
+            continue
+    return False
+
+
+def apply_shadow(project_dir: str, run_id: str) -> dict[str, Any]:
+    run_id = _validated_run_id(run_id)
+    run_dir = os.path.join(_shadow_root(project_dir), run_id)
+    manifest = _load_manifest(run_dir)
+    applied = []
+
+    for item in manifest.get("files", []):
+        rel = item.get("file")
+        shadow_rel = item.get("shadow_file")
+        if not rel or not shadow_rel:
+            continue
+        src = os.path.join(run_dir, shadow_rel)
+        dst = os.path.join(project_dir, rel)
+        if not os.path.exists(src):
+            continue
+        os.makedirs(os.path.dirname(dst), exist_ok=True)
+        shutil.copy2(src, dst)
+        applied.append(rel)
+
+    manifest["status"] = "applied"
+    manifest["applied_at"] = _utc_now()
+    _save_manifest(run_dir, manifest)
+
+    return {"run_id": run_id, "applied": applied}
+
+
+def drop_shadow(project_dir: str, run_id: str) -> dict[str, Any]:
+    run_id = _validated_run_id(run_id)
+    run_dir = os.path.join(_shadow_root(project_dir), run_id)
+    if os.path.isdir(run_dir):
+        print(f"[OMG] Deleting: {run_dir}", file=sys.stderr)
+        shutil.rmtree(run_dir, ignore_errors=True)
+
+    active = get_active_run_id(project_dir)
+    if active == run_id:
+        try:
+            os.remove(_active_run_path(project_dir))
+        except OSError:
+            pass
+
+    return {"run_id": run_id, "dropped": True}
+
+
+def auto_journal_mutation(
+    project_dir: str,
+    tool: str,
+    file_path: str,
+    run_id: str,
+) -> dict[str, Any] | None:
+    try:
+        from runtime.interaction_journal import InteractionJournal
+        from runtime.release_run_coordinator import resolve_current_run_id
+    except ImportError:
+        return None
+
+    canonical_run_id = resolve_current_run_id(project_dir) or run_id
+    shadow_manifest = os.path.join(
+        _shadow_root(project_dir), run_id, "manifest.json"
+    )
+
+    journal = InteractionJournal(project_dir)
+    return journal.record_step(
+        tool.lower(),
+        {
+            "file_path": file_path,
+            "run_id": canonical_run_id,
+            "shadow_manifest": shadow_manifest,
+        },
+    )
+
+
+def _handle_post_tool_use(payload: dict[str, Any]) -> None:
+    tool = payload.get("tool_name", "")
+    if tool not in ("Write", "Edit", "MultiEdit"):
+        return
+
+    tool_input = payload.get("tool_input", {}) if isinstance(payload.get("tool_input"), dict) else {}
+    file_path = tool_input.get("file_path", "")
+    if not file_path:
+        return
+
+    tool_resp = payload.get("tool_response", {})
+    success = None
+    if isinstance(tool_resp, dict):
+        success = tool_resp.get("success")
+
+    if success is False:
+        return
+
+    project_dir = _project_dir()
+    run_id = begin_shadow_run(project_dir, metadata={"source": "post-tool-use"})
+    record_shadow_write(project_dir, run_id, file_path)
+
+    try:
+        auto_journal_mutation(project_dir, tool, file_path, run_id)
+    except Exception:
+        pass
+
+
+def _main() -> int:
+    # Early-exit: skip all work if shadow/evidence mode is not enabled
+    project_dir = _project_dir()
+    policy_path = os.path.join(project_dir, ".omg", "policy.yaml")
+    if not os.path.exists(policy_path) and os.environ.get("OMG_EVIDENCE_REQUIRED", "0") != "1":
+        return 0
+
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        return 0
+
+    try:
+        _handle_post_tool_use(payload)
+    except Exception:
+        pass
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(_main())

package/hooks/state_migration.py

@@ -0,0 +1,228 @@
+#!/usr/bin/env python3
+"""State path resolution and legacy `.omc` -> `.omg` migration utilities."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import hashlib
+import json
+import os
+import shutil
+from typing import Any
+
+DEFAULT_MIGRATION_REPORT = "legacy-to-omg.json"
+LEGACY_MIGRATION_REPORT = "omc-to-omg.json"
+
+
+def paths(project_dir: str) -> dict[str, str]:
+    omg_root = os.path.join(project_dir, ".omg")
+    return {
+        "project": project_dir,
+        "omg_root": omg_root,
+        "omg_state": os.path.join(omg_root, "state"),
+        "omg_knowledge": os.path.join(omg_root, "knowledge"),
+        "omg_migrations": os.path.join(omg_root, "migrations"),
+        "legacy_omc": os.path.join(project_dir, ".omc"),
+    }
+
+
+def ensure_omg_structure(project_dir: str) -> None:
+    p = paths(project_dir)
+    os.makedirs(p["omg_state"], exist_ok=True)
+    os.makedirs(p["omg_knowledge"], exist_ok=True)
+    os.makedirs(p["omg_migrations"], exist_ok=True)
+
+
+def _sha256_file(path: str) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        while True:
+            chunk = f.read(8192)
+            if not chunk:
+                break
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _copy_file(src: str, dst: str) -> str:
+    os.makedirs(os.path.dirname(dst), exist_ok=True)
+    if os.path.exists(dst):
+        try:
+            if _sha256_file(src) == _sha256_file(dst):
+                return "unchanged"
+        except Exception:
+            pass
+    shutil.copy2(src, dst)
+    return "copied"
+
+
+def _copy_tree(src: str, dst: str) -> dict[str, int]:
+    stats = {"copied": 0, "unchanged": 0, "missing": 0, "errors": 0}
+    if not os.path.isdir(src):
+        stats["missing"] += 1
+        return stats
+    for root, _, files in os.walk(src):
+        for fn in files:
+            src_file = os.path.join(root, fn)
+            rel = os.path.relpath(src_file, src)
+            dst_file = os.path.join(dst, rel)
+            try:
+                status = _copy_file(src_file, dst_file)
+                stats[status] += 1
+            except Exception:
+                stats["errors"] += 1
+    return stats
+
+
+MIGRATION_MAP: list[tuple[str, str, str]] = [
+    ("file", "profile.yaml", "state/profile.yaml"),
+    ("file", "working-memory.md", "state/working-memory.md"),
+    ("file", "quality-gate.json", "state/quality-gate.json"),
+    ("file", "_plan.md", "state/_plan.md"),
+    ("file", "_checklist.md", "state/_checklist.md"),
+    ("file", "_context.md", "state/_context.md"),
+    ("file", "handoff.md", "state/handoff.md"),
+    ("file", "handoff.md.consumed", "state/handoff.md.consumed"),
+    ("file", "handoff-portable.md", "state/handoff-portable.md"),
+    # Legacy root-level runtime files used by older OMC installs.
+    ("file", "autopilot-state.json", "state/autopilot-state.json"),
+    ("file", "ultrapilot-state.json", "state/ultrapilot-state.json"),
+    ("file", "ralph-state.json", "state/ralph-state.json"),
+    ("file", "ultrawork-state.json", "state/ultrawork-state.json"),
+    ("file", "ultraqa-state.json", "state/ultraqa-state.json"),
+    ("file", "team-state.json", "state/team-state.json"),
+    ("file", "pipeline-state.json", "state/pipeline-state.json"),
+    ("file", "swarm-state.json", "state/swarm-state.json"),
+    ("file", "hud-state.json", "state/hud-state.json"),
+    ("file", "hud-stdin-cache.json", "state/hud-stdin-cache.json"),
+    ("file", "skill-active-state.json", "state/skill-active-state.json"),
+    ("file", "subagent-tracking.json", "state/subagent-tracking.json"),
+    # Runtime state files for HUD, routing, and session continuity.
+    ("file", "ecosystem-lock.json", "state/ecosystem-lock.json"),
+    ("file", "hashline_cache.json", "state/hashline_cache.json"),
+    ("file", "hashline_cache.json.tmp", "state/hashline_cache.json.tmp"),
+    ("file", "idle_signal.json", "state/idle_signal.json"),
+    ("file", "idle-notif-cooldown.json", "state/idle-notif-cooldown.json"),
+    ("file", "last-tool-error.json", "state/last-tool-error.json"),
+    ("file", "routing_result.json", "state/routing_result.json"),
+    ("file", "theme.json", "state/theme.json"),
+    ("file", "todo_progress.json", "state/todo_progress.json"),
+    # Migrate full runtime state for HUD + routing continuity.
+    ("dir", "state", "state"),
+    ("dir", "checkpoints", "state/checkpoints"),
+    ("dir", "ledger", "state/ledger"),
+    ("dir", "learnings", "state/learnings"),
+    ("dir", "memory", "state/memory"),
+    ("dir", "repl_sessions", "state/repl_sessions"),
+    ("dir", "sessions", "state/sessions"),
+    ("dir", "snapshots", "state/snapshots"),
+    ("file", "current_branch.json", "state/current_branch.json"),
+    ("file", "background-verification.json", "state/background-verification.json"),
+    ("dir", "branches", "state/branches"),
+    ("dir", "knowledge", "knowledge"),
+]
+
+
+def migrate_omc_to_omg(project_dir: str, force: bool = False) -> dict[str, Any]:
+    ensure_omg_structure(project_dir)
+    p = paths(project_dir)
+    legacy = p["legacy_omc"]
+    report: dict[str, Any] = {
+        "started_at": datetime.now(timezone.utc).isoformat(),
+        "project_dir": project_dir,
+        "legacy_path": legacy,
+        "target_path": p["omg_root"],
+        "result": "ok",
+        "entries": [],
+    }
+
+    if not os.path.isdir(legacy):
+        report["result"] = "no_legacy"
+    else:
+        for kind, src_rel, dst_rel in MIGRATION_MAP:
+            src = os.path.join(legacy, src_rel)
+            dst = os.path.join(p["omg_root"], dst_rel)
+            entry = {"kind": kind, "source": src_rel, "target": dst_rel, "status": "missing"}
+            try:
+                if kind == "file":
+                    if os.path.isfile(src):
+                        status = _copy_file(src, dst)
+                        entry["status"] = status
+                    else:
+                        entry["status"] = "missing"
+                else:
+                    stats = _copy_tree(src, dst)
+                    entry["status"] = "copied" if stats["copied"] else ("unchanged" if stats["unchanged"] else "missing")
+                    entry["stats"] = stats
+            except Exception as exc:
+                entry["status"] = "error"
+                entry["error"] = str(exc)
+                report["result"] = "partial_error"
+            report["entries"].append(entry)
+
+    report["finished_at"] = datetime.now(timezone.utc).isoformat()
+    os.makedirs(p["omg_migrations"], exist_ok=True)
+    out_path = os.path.join(p["omg_migrations"], DEFAULT_MIGRATION_REPORT)
+    legacy_out_path = os.path.join(p["omg_migrations"], LEGACY_MIGRATION_REPORT)
+
+    # idempotent write: overwrite with latest summary
+    for path in (out_path, legacy_out_path):
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(report, f, indent=2, ensure_ascii=True)
+    report["report_path"] = out_path
+    report["legacy_report_path"] = legacy_out_path
+    return report
+
+
+def migrate_legacy_to_omg(project_dir: str, force: bool = False) -> dict[str, Any]:
+    """Canonical migration API."""
+    return migrate_omc_to_omg(project_dir, force=force)
+
+
+def resolve_state_file(
+    project_dir: str,
+    omg_relative: str,
+    legacy_relative: str | None = None,
+    auto_migrate: bool = True,
+) -> str:
+    """Return preferred .omg file path; fallback to .omc if needed.
+
+    - If .omg target exists, return it.
+    - If not, and legacy exists, optionally run migration and return target if created.
+    - If still absent, return the preferred target path.
+    """
+    p = paths(project_dir)
+    preferred = os.path.join(p["omg_root"], omg_relative)
+    if os.path.exists(preferred):
+        return preferred
+
+    legacy_rel = legacy_relative or omg_relative
+    legacy_path = os.path.join(p["legacy_omc"], legacy_rel)
+    if os.path.exists(legacy_path) and auto_migrate:
+        migrate_legacy_to_omg(project_dir)
+        if os.path.exists(preferred):
+            return preferred
+    if os.path.exists(legacy_path):
+        return legacy_path
+    return preferred
+
+
+def resolve_state_dir(
+    project_dir: str,
+    omg_relative: str,
+    legacy_relative: str | None = None,
+    auto_migrate: bool = True,
+) -> str:
+    p = paths(project_dir)
+    preferred = os.path.join(p["omg_root"], omg_relative)
+    if os.path.isdir(preferred):
+        return preferred
+
+    legacy_rel = legacy_relative or omg_relative
+    legacy_path = os.path.join(p["legacy_omc"], legacy_rel)
+    if os.path.isdir(legacy_path) and auto_migrate:
+        migrate_legacy_to_omg(project_dir)
+        if os.path.isdir(preferred):
+            return preferred
+    if os.path.isdir(legacy_path):
+        return legacy_path
+    return preferred