Skip to content

majiayu000/spellbook / skills/skill-ecosystem-doctor

skill-ecosystem-doctor

Verified

Audit and safely repair cross-runtime Skill governance: canonical-source ownership, divergent or duplicate projections, exposure scopes and budgets, lifecycle drift, quarantine, and retirement. Use when the user explicitly requests cross-runtime or cross-scope Skill governance; ignore project-local Skill inventory, product/runtime loading or enablement checks, usage statistics, and mentions/traces.

scripts/ecosystem_reconcile.py

View on GitHub
#!/usr/bin/env python3
"""Dry-run or apply trigger and exposure policy to a local Skill registry."""

from __future__ import annotations

import argparse
import hashlib
import json
import os
import re
import shutil
from datetime import datetime
from dataclasses import dataclass
from pathlib import Path

import yaml

from ecosystem_exposure import ExposureError, classify_exposure, expand_profile_scopes
from ecosystem_model import (
    RUNTIME_HOME_DIRS,
    SUPPORTED_RUNTIMES,
    default_runtime_homes,
    runtime_home_dest,
    runtime_home_flag,
    runtime_project_dir,
    runtime_target_ids,
)
from ecosystem_plugins import PluginPolicyError, plan_plugin_states
from ecosystem_runtimes import (
    MIRROR_RUNTIME,
    RuntimePolicyError,
    governed_runtimes,
    parse_managed_global_sources,
    parse_runtime_mirrors,
    projection_runtimes,
)


# Plugin enablement is genuinely Codex-specific: it edits Codex's config.toml.
# It stays bound to the Codex home instead of fanning out per runtime.
PLUGIN_RUNTIME = "codex"
QUOTED_CONTEXT_RE = re.compile(r"quoted|trace|tool output|引用|引述|日志记录", re.I)
GOVERNANCE_CONTEXT_RE = re.compile(r"governance|audit|skill 治理|技能治理|审计", re.I)
FRONTMATTER_KEY_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_-]*:")
PORTABLE_FRONTMATTER_KEYS = {
    "name", "description", "license", "metadata", "allowed-tools", "compatibility"
}


class ReconcileError(RuntimeError):
    """Raised when reconciliation would overwrite an unexpected path."""


@dataclass(frozen=True)
class ReconcilePlan:
    hardened: tuple[str, ...]
    global_links_to_remove: tuple[str, ...]
    global_links_to_create: tuple[tuple[str, str], ...]
    global_links_to_replace: tuple[tuple[str, str], ...]
    project_links_to_remove: tuple[str, ...]
    project_links_to_create: tuple[tuple[str, str], ...]
    project_links_to_replace: tuple[tuple[str, str], ...]
    review_skills: tuple[str, ...]
    profile_skills: tuple[str, ...]
    managed_global_skill_count: int
    managed_description_chars: int
    plugin_state_changes: tuple[tuple[str, bool, bool], ...]
    state_rules_to_remove: int
    state_projections_to_remove: int

    def as_dict(self) -> dict:
        return {
            "hardened": list(self.hardened),
            "global_links_to_remove": list(self.global_links_to_remove),
            "global_links_to_create": [
                {"path": path, "target": target}
                for path, target in self.global_links_to_create
            ],
            "global_links_to_replace": [
                {"path": path, "target": target}
                for path, target in self.global_links_to_replace
            ],
            "project_links_to_remove": list(self.project_links_to_remove),
            "project_links_to_create": [
                {"path": path, "target": target}
                for path, target in self.project_links_to_create
            ],
            "project_links_to_replace": [
                {"path": path, "target": target}
                for path, target in self.project_links_to_replace
            ],
            "review_skills": list(self.review_skills),
            "profile_skills": list(self.profile_skills),
            "managed_global_skill_count": self.managed_global_skill_count,
            "managed_description_chars": self.managed_description_chars,
            "plugin_state_changes": [
                {"plugin": plugin, "from": current, "to": desired}
                for plugin, current, desired in self.plugin_state_changes
            ],
            "state_rules_to_remove": self.state_rules_to_remove,
            "state_projections_to_remove": self.state_projections_to_remove,
        }


def _load_json(path: Path) -> dict:
    try:
        value = json.loads(path.read_text(encoding="utf-8"))
    except FileNotFoundError as exc:
        raise ReconcileError(f"JSON file does not exist: {path}") from exc
    except OSError as exc:
        raise ReconcileError(f"JSON file cannot be read: {path}: {exc}") from exc
    except json.JSONDecodeError as exc:
        raise ReconcileError(f"invalid JSON in {path}: {exc}") from exc
    if not isinstance(value, dict):
        raise ReconcileError(f"{path} must contain a JSON object")
    return value


def _atomic_write(path: Path, text: str) -> None:
    temp = path.with_name(f".{path.name}.governance-{os.getpid()}")
    try:
        temp.write_text(text, encoding="utf-8")
        os.chmod(temp, path.stat().st_mode)
        os.replace(temp, path)
    except OSError:
        temp.unlink(missing_ok=True)
        raise


def _frontmatter_description(text: str, path: Path) -> tuple[str, int, int]:
    lines = text.splitlines()
    if not lines or lines[0].strip() != "---":
        raise ReconcileError(f"{path} has no YAML frontmatter")
    try:
        closing = next(index for index in range(1, len(lines)) if lines[index].strip() == "---")
    except StopIteration as exc:
        raise ReconcileError(f"{path} has unterminated YAML frontmatter") from exc
    try:
        data = yaml.safe_load("\n".join(lines[1:closing]))
    except yaml.YAMLError as exc:
        raise ReconcileError(f"invalid YAML frontmatter in {path}: {exc}") from exc
    if not isinstance(data, dict) or not isinstance(data.get("description"), str):
        raise ReconcileError(f"{path} has no string description")
    start = next(
        (index for index in range(1, closing) if lines[index].startswith("description:")),
        None,
    )
    if start is None:
        raise ReconcileError(f"{path} has no top-level description field")
    end = closing
    for index in range(start + 1, closing):
        if lines[index] and not lines[index][0].isspace() and FRONTMATTER_KEY_RE.match(lines[index]):
            end = index
            break
    return data["description"].strip(), start, end


def _hardened_text(
    path: Path,
    clause: str,
    max_length: int,
    *,
    replace_clause: str | None = None,
) -> tuple[str, bool]:
    original = path.read_text(encoding="utf-8")
    description, start, end = _frontmatter_description(original, path)
    if clause in description:
        return original, False
    if replace_clause and replace_clause in description:
        updated = description.replace(replace_clause, clause)
    elif QUOTED_CONTEXT_RE.search(description) and GOVERNANCE_CONTEXT_RE.search(
        description
    ):
        return original, False
    else:
        updated = description.rstrip() + clause
    if len(updated) > max_length:
        raise ReconcileError(
            f"{path} description would exceed {max_length} characters ({len(updated)})"
        )
    lines = original.splitlines()
    replacement = f"description: {json.dumps(updated, ensure_ascii=False)}"
    result = "\n".join([*lines[:start], replacement, *lines[end:]])
    if original.endswith("\n"):
        result += "\n"
    return result, True


def _scope_map(policy: dict) -> dict[str, Path]:
    result: dict[str, Path] = {}
    project_scopes = policy.get("project_scopes", {})
    if not isinstance(project_scopes, dict):
        raise ReconcileError("project_scopes must be an object")
    for raw_root, raw_skills in project_scopes.items():
        if not isinstance(raw_root, str) or not isinstance(raw_skills, list):
            raise ReconcileError("project_scopes entries must map paths to skill arrays")
        root = Path(raw_root).expanduser()
        if not root.is_dir():
            raise ReconcileError(f"project scope root does not exist: {root}")
        for skill in raw_skills:
            if not isinstance(skill, str):
                raise ReconcileError("project skill names must be strings")
            if skill in result:
                raise ReconcileError(f"skill has multiple project owners: {skill}")
            result[skill] = root
    return result


def _scope_roots(policy: dict, scope_map: dict[str, Path]) -> dict[str, tuple[Path, ...]]:
    result: dict[str, set[Path]] = {skill: {owner} for skill, owner in scope_map.items()}
    raw_globs = policy.get("project_scope_globs", {})
    if not isinstance(raw_globs, dict):
        raise ReconcileError("project_scope_globs must be an object")
    for raw_pattern, raw_skills in raw_globs.items():
        if not isinstance(raw_pattern, str) or not isinstance(raw_skills, list):
            raise ReconcileError("project_scope_globs entries must map patterns to skill arrays")
        pattern = Path(raw_pattern).expanduser()
        if not pattern.is_absolute():
            raise ReconcileError(f"project scope glob must be absolute: {raw_pattern}")
        parent = pattern.parent
        if any(char in str(parent) for char in "*?["):
            raise ReconcileError("project scope glob wildcards are allowed only in the basename")
        matches = sorted(path for path in parent.glob(pattern.name) if path.is_dir())
        if not matches:
            raise ReconcileError(f"project scope glob has no directory matches: {raw_pattern}")
        for skill in raw_skills:
            if not isinstance(skill, str):
                raise ReconcileError("project scope glob skill names must be strings")
            if skill not in scope_map:
                raise ReconcileError(f"project scope glob skill has no primary owner: {skill}")
            result[skill].update(matches)
    return {skill: tuple(sorted(roots)) for skill, roots in result.items()}


def _declared_project_roots(policy: dict) -> tuple[Path, ...]:
    roots: set[Path] = set()
    raw_scopes = policy.get("project_scopes", {})
    if not isinstance(raw_scopes, dict):
        raise ReconcileError("project_scopes must be an object")
    for raw_root in raw_scopes:
        if not isinstance(raw_root, str):
            raise ReconcileError("project scope roots must be strings")
        root = Path(raw_root).expanduser()
        if not root.is_dir():
            raise ReconcileError(f"project scope root does not exist: {root}")
        roots.add(root)

    raw_globs = policy.get("project_scope_globs", {})
    if not isinstance(raw_globs, dict):
        raise ReconcileError("project_scope_globs must be an object")
    for raw_pattern in raw_globs:
        if not isinstance(raw_pattern, str):
            raise ReconcileError("project scope glob patterns must be strings")
        pattern = Path(raw_pattern).expanduser()
        if not pattern.is_absolute():
            raise ReconcileError(f"project scope glob must be absolute: {raw_pattern}")
        parent = pattern.parent
        if any(char in str(parent) for char in "*?["):
            raise ReconcileError("project scope glob wildcards are allowed only in the basename")
        matches = sorted(path for path in parent.glob(pattern.name) if path.is_dir())
        if not matches:
            raise ReconcileError(f"project scope glob has no directory matches: {raw_pattern}")
        roots.update(matches)
    return tuple(sorted(roots))


def _policy_name_set(policy: dict, field: str) -> set[str]:
    values = policy.get(field, [])
    if not isinstance(values, list) or not all(
        isinstance(value, str) and value for value in values
    ):
        raise ReconcileError(f"{field} must be a string array")
    if len(values) != len(set(values)):
        raise ReconcileError(f"{field} contains duplicate names")
    return set(values)


def _project_sources(
    policy: dict, scope_map: dict[str, Path], registry: Path
) -> dict[str, Path]:
    configured = policy.get("project_source_roots", {})
    if not isinstance(configured, dict):
        raise ReconcileError("project_source_roots must be an object")
    unknown = set(configured) - {
        str(Path(root).expanduser()) for root in policy.get("project_scopes", {})
    }
    if unknown:
        raise ReconcileError(f"project source root has no matching scope: {sorted(unknown)}")
    if any(not isinstance(relative, str) or not relative for relative in configured.values()):
        raise ReconcileError("project source paths must be non-empty strings")
    result: dict[str, Path] = {}
    for skill, owner in scope_map.items():
        relative = configured.get(str(owner))
        if relative is None:
            source = registry / "skills" / skill
        else:
            source = owner / relative / skill
        if not (source / "SKILL.md").is_file():
            raise ReconcileError(f"project source is missing: {source}")
        result[skill] = source
    return result


def _validate_frontmatter_extensions(policy: dict, sources: dict[str, Path]) -> None:
    configured = policy.get("frontmatter_extension_exceptions", {})
    if not isinstance(configured, dict):
        raise ReconcileError("frontmatter_extension_exceptions must be an object")
    allowed_by_skill: dict[str, set[str]] = {}
    for key, names in configured.items():
        if not isinstance(key, str) or not isinstance(names, list) or not all(
            isinstance(name, str) for name in names
        ):
            raise ReconcileError(
                "frontmatter_extension_exceptions must map keys to skill arrays"
            )
        for name in names:
            if name not in sources:
                raise ReconcileError(f"frontmatter exception references unknown skill: {name}")
            allowed_by_skill.setdefault(name, set()).add(key)
    for name, skill_file in sorted(sources.items()):
        text = skill_file.read_text(encoding="utf-8")
        lines = text.splitlines()
        try:
            closing = next(
                index for index in range(1, len(lines)) if lines[index].strip() == "---"
            )
            data = yaml.safe_load("\n".join(lines[1:closing]))
        except (StopIteration, yaml.YAMLError) as exc:
            raise ReconcileError(f"invalid frontmatter in {skill_file}: {exc}") from exc
        if not isinstance(data, dict):
            raise ReconcileError(f"frontmatter is not a mapping: {skill_file}")
        if "compatibility" in data:
            compatibility = data["compatibility"]
            # Standard compatibility is environment text. Existing legacy
            # mappings remain an explicit, per-skill extension exception.
            legacy_exception = (
                isinstance(compatibility, dict)
                and "compatibility" in allowed_by_skill.get(name, set())
            )
            if not legacy_exception and (
                not isinstance(compatibility, str)
                or not compatibility.strip() or len(compatibility) > 500
            ):
                raise ReconcileError(
                    f"{skill_file} compatibility must be a non-empty string of at most "
                    "500 characters; legacy mappings require an explicit extension exception"
                )
        keys = set(data)
        unexpected = keys - PORTABLE_FRONTMATTER_KEYS - allowed_by_skill.get(name, set())
        if unexpected:
            raise ReconcileError(
                f"unapproved frontmatter extensions for {name}: {sorted(unexpected)}"
            )
        missing = allowed_by_skill.get(name, set()) - keys
        if missing:
            raise ReconcileError(
                f"stale frontmatter extension exceptions for {name}: {sorted(missing)}"
            )


def _directory_manifest(root: Path) -> dict[str, str]:
    result: dict[str, str] = {}
    for path in sorted(root.rglob("*")):
        if not path.is_file() or "__pycache__" in path.parts or path.suffix == ".pyc":
            continue
        result[str(path.relative_to(root))] = hashlib.sha256(path.read_bytes()).hexdigest()
    return result


def _resolved_link(path: Path) -> Path:
    target = Path(os.readlink(path))
    return target if target.is_absolute() else (path.parent / target).resolve()


def _validate_removable_link(
    path: Path, expected: Path, managed_previous: Path | None = None,
    *managed_sources: Path,
) -> bool:
    if path.is_symlink():
        allowed = {expected.resolve(), *(source.resolve() for source in managed_sources)}
        if managed_previous is not None:
            allowed.add(managed_previous.resolve())
        if _resolved_link(path) not in allowed:
            raise ReconcileError(f"refusing to remove unexpected symlink: {path}")
        return True
    if path.exists():
        raise ReconcileError(f"refusing to remove non-symlink path: {path}")
    return False


def _project_link_action(path: Path, expected: Path, managed_previous: Path) -> str | None:
    if path.is_symlink():
        current = _resolved_link(path)
        if current == expected.resolve():
            return None
        if current == managed_previous.resolve():
            return "replace"
        raise ReconcileError(f"project link points elsewhere: {path}")
    if path.exists():
        raise ReconcileError(f"project path already exists and is not a symlink: {path}")
    return "create"


def _filtered_state(
    path: Path,
    collection: str,
    hidden: set[str],
    runtime_mirrors: set[str],
    mirror_target_ids: frozenset[str],
) -> tuple[dict, int]:
    data = _load_json(path)
    values = data.get(collection)
    if not isinstance(values, list):
        raise ReconcileError(f"{path} has no {collection} array")
    retained = []
    for item in values:
        remove = isinstance(item, dict) and (
            item.get("skill_id") in hidden
            or (
                item.get("skill_id") in runtime_mirrors
                and item.get("target_id") in mirror_target_ids
            )
        )
        if not remove:
            retained.append(item)
    removed = len(values) - len(retained)
    data[collection] = retained
    return data, removed


def build_plan(
    registry: Path,
    policy: dict,
    *,
    runtime_homes: dict[str, Path],
    codex_config_home: Path | None = None,
) -> tuple[ReconcilePlan, dict[Path, str], dict[Path, dict]]:
    unknown_homes = sorted(set(runtime_homes) - SUPPORTED_RUNTIMES)
    if unknown_homes:
        raise ReconcileError(f"unsupported runtime homes: {unknown_homes}")
    skills_root = registry / "skills"
    policy, profile_names = expand_profile_scopes(policy)
    scope_map = _scope_map(policy)
    scope_roots = _scope_roots(policy, scope_map)
    declared_project_roots = _declared_project_roots(policy)
    project_sources = _project_sources(policy, scope_map, registry)
    managed_globals = parse_managed_global_sources(policy)
    # Runtimes that receive automatic projections, and the wider set the policy
    # governs (projection runtimes plus any runtime named by a managed global).
    policy_runtimes = projection_runtimes(policy)
    governed = governed_runtimes(policy_runtimes, managed_globals)
    missing_homes = [runtime for runtime in governed if runtime not in runtime_homes]
    if missing_homes or PLUGIN_RUNTIME not in runtime_homes:
        raise ReconcileError(
            "missing runtime homes: "
            f"{sorted({*missing_homes, PLUGIN_RUNTIME} - set(runtime_homes))}"
        )
    projection_homes = tuple(runtime_homes[runtime] for runtime in policy_runtimes)
    governed_homes = tuple(runtime_homes[runtime] for runtime in governed)
    projection_dirs = tuple(runtime_project_dir(runtime) for runtime in policy_runtimes)
    retired = _policy_name_set(policy, "retired")
    quarantined = _policy_name_set(policy, "quarantined")
    blocked = retired | quarantined
    if retired & quarantined:
        raise ReconcileError(
            f"retired and quarantined overlap: {sorted(retired & quarantined)}"
        )
    trigger = policy.get("trigger_boundary", {})
    clause = trigger.get("clause")
    overrides = trigger.get("overrides", {})
    max_length = trigger.get("max_description_length", 1024)
    if not isinstance(clause, str) or not clause.startswith(" "):
        raise ReconcileError("trigger boundary clause must be a space-prefixed string")
    if not isinstance(overrides, dict) or not all(
        isinstance(name, str) and isinstance(value, str) and value.startswith(" ")
        for name, value in overrides.items()
    ):
        raise ReconcileError("trigger boundary overrides must be space-prefixed strings")
    if not isinstance(max_length, int) or max_length <= 0:
        raise ReconcileError("max_description_length must be a positive integer")

    duplicate_resolution = policy.get("duplicate_resolution", {})
    if not isinstance(duplicate_resolution, dict):
        raise ReconcileError("duplicate_resolution must be an object")
    retired_mirrors = set(duplicate_resolution.get("retire_registry_mirror", []))
    mirror_root, runtime_mirrors = parse_runtime_mirrors(policy)
    managed_names = set(managed_globals)
    canonical_sources = {
        skill_file.parent.name: skill_file
        for skill_file in skills_root.glob("*/SKILL.md")
        if skill_file.parent.name not in retired_mirrors
    }
    canonical_sources.update(
        {skill: source / "SKILL.md" for skill, source in project_sources.items()}
    )
    canonical_sources.update(
        {skill: source / "SKILL.md" for skill, (source, _) in managed_globals.items()}
    )
    explicit_global = _policy_name_set(policy, "global_allowlist") | _policy_name_set(
        policy, "global_overrides"
    )
    explicit_exposure = set(scope_map) | profile_names | managed_names | runtime_mirrors | explicit_global
    if blocked & explicit_exposure:
        raise ReconcileError(
            f"retired or quarantined skills overlap active exposure: {sorted(blocked & explicit_exposure)}"
        )
    exposed_sources = {
        name: source for name, source in canonical_sources.items() if name not in blocked
    }
    classification = classify_exposure(
        policy,
        exposed_sources,
        project_names=set(scope_map),
        profile_names=profile_names,
        managed_names=managed_names,
        runtime_mirror_names=runtime_mirrors,
        validate_budget=False,
    )
    cold = set(classification.cold_names)
    hidden = set(classification.hidden_names)
    overlap = managed_names & (hidden | runtime_mirrors)
    if overlap:
        raise ReconcileError(
            f"managed global sources overlap scoped, cold, or runtime mirror skills: {sorted(overlap)}"
        )
    _validate_frontmatter_extensions(policy, canonical_sources)
    for skill in runtime_mirrors:
        authoritative = mirror_root / skill if mirror_root else None
        mirror = skills_root / skill
        if authoritative is None or not (authoritative / "SKILL.md").is_file():
            raise ReconcileError(f"runtime mirror source is missing: {skill}")
        if not (mirror / "SKILL.md").is_file():
            raise ReconcileError(f"registry runtime mirror is missing: {skill}")
        if _directory_manifest(authoritative) != _directory_manifest(mirror):
            raise ReconcileError(f"runtime mirror drift: {skill}")

    external_project_skills = {
        skill
        for skill, source in project_sources.items()
        if source != skills_root / skill
    }
    inactive_hidden = hidden - set(scope_map)
    harden_exclusions = (
        inactive_hidden
        | blocked
        | retired_mirrors
        | runtime_mirrors
        | external_project_skills
        | managed_names
    )
    text_updates: dict[Path, str] = {}
    hardened: list[str] = []
    for skill_file in sorted(skills_root.glob("*/SKILL.md")):
        skill = skill_file.parent.name
        if skill in harden_exclusions:
            continue
        selected_clause = overrides.get(skill, clause)
        updated, changed = _hardened_text(
            skill_file,
            selected_clause,
            max_length,
            replace_clause=clause if selected_clause != clause else None,
        )
        if changed:
            text_updates[skill_file] = updated
            hardened.append(skill)

    for skill in sorted(external_project_skills):
        skill_file = project_sources[skill] / "SKILL.md"
        selected_clause = overrides.get(skill, clause)
        updated, changed = _hardened_text(
            skill_file,
            selected_clause,
            max_length,
            replace_clause=clause if selected_clause != clause else None,
        )
        if changed:
            text_updates[skill_file] = updated
            hardened.append(skill)

    for skill, (source, _) in sorted(managed_globals.items()):
        selected_clause = overrides.get(skill, clause)
        updated, changed = _hardened_text(
            source / "SKILL.md",
            selected_clause,
            max_length,
            replace_clause=clause if selected_clause != clause else None,
        )
        if changed:
            text_updates[source / "SKILL.md"] = updated
            hardened.append(skill)

    # Exposure determines what to harden, but its budget must describe the
    # proposed result, including longer or shorter trigger overrides. No writes
    # have happened when this final validation rejects an oversized catalog.
    classification = classify_exposure(
        policy,
        exposed_sources,
        project_names=set(scope_map),
        profile_names=profile_names,
        managed_names=managed_names,
        runtime_mirror_names=runtime_mirrors,
        text_overrides=text_updates,
    )

    global_links: list[str] = []
    global_creations: list[tuple[str, str]] = []
    global_replacements: list[tuple[str, str]] = []
    project_removals: list[str] = []
    project_links: list[tuple[str, str]] = []
    project_replacements: list[tuple[str, str]] = []
    for skill in sorted(blocked):
        source = skills_root / skill
        for home in governed_homes:
            global_path = home / "skills" / skill
            if _validate_removable_link(global_path, source):
                global_links.append(str(global_path))

    # Explicit retirement/quarantine authorizes removing matching projections.
    # Scope changes have no historical root-skill ownership records: a canonical
    # link may be user-created, so leave those links for manual confirmation.
    for owner in declared_project_roots:
        relative = policy.get("project_source_roots", {}).get(str(owner))
        source_root = owner / relative if relative is not None else skills_root
        for skill in sorted(blocked):
            source = (source_root / skill if relative is not None else
                      canonical_sources.get(skill, skills_root / skill / "SKILL.md").parent)
            # Glob-created worktrees use the primary project's source too.
            # Retirement removes active scopes, so use the explicitly declared
            # source roots rather than looking up the secondary root as owner.
            declared_sources = tuple(
                Path(primary).expanduser() / relative / skill
                for primary, relative in policy.get("project_source_roots", {}).items()
            )
            desired_roots = set(scope_roots.get(skill, ()))
            for runtime_dir in projection_dirs:
                if owner in desired_roots:
                    continue
                project_path = owner / runtime_dir / "skills" / skill
                if _validate_removable_link(
                    project_path, source, skills_root / skill, *declared_sources
                ):
                    project_removals.append(str(project_path))

    for skill in sorted(hidden):
        source = project_sources.get(skill, skills_root / skill)
        if not (source / "SKILL.md").is_file():
            raise ReconcileError(f"policy references missing skill source: {skill}")
        for home in governed_homes:
            global_path = home / "skills" / skill
            if _validate_removable_link(global_path, source):
                global_links.append(str(global_path))
        for owner in scope_roots.get(skill, ()):
            for runtime_dir in projection_dirs:
                project_path = owner / runtime_dir / "skills" / skill
                action = _project_link_action(project_path, source, skills_root / skill)
                pair = (str(project_path), str(source))
                if action == "create":
                    project_links.append(pair)
                elif action == "replace":
                    project_replacements.append(pair)

    for skill, (source, runtimes) in sorted(managed_globals.items()):
        for runtime in sorted(runtimes):
            global_path = runtime_homes[runtime] / "skills" / skill
            action = _project_link_action(global_path, source, skills_root / skill)
            pair = (str(global_path), str(source))
            if action == "create":
                global_creations.append(pair)
            elif action == "replace":
                global_replacements.append(pair)

    for skill in sorted(classification.global_names):
        source = canonical_sources[skill].parent
        for home in projection_homes:
            global_path = home / "skills" / skill
            action = _project_link_action(global_path, source, skills_root / skill)
            pair = (str(global_path), str(source))
            if action == "create":
                global_creations.append(pair)
            elif action == "replace":
                global_replacements.append(pair)

    # A runtime mirror lives in MIRROR_RUNTIME only: strip its projection from
    # every other projected runtime, both on disk and in registry state.
    mirror_runtimes = tuple(
        runtime for runtime in policy_runtimes if runtime != MIRROR_RUNTIME
    )
    for skill in sorted(runtime_mirrors):
        for runtime in mirror_runtimes:
            global_path = runtime_homes[runtime] / "skills" / skill
            if _validate_removable_link(global_path, skills_root / skill):
                global_links.append(str(global_path))

    state_updates: dict[Path, dict] = {}
    mirror_target_ids = frozenset(
        target_id
        for runtime in mirror_runtimes
        for target_id in runtime_target_ids(runtime)
    )
    rules_path = registry / "state" / "registry" / "rules.json"
    projections_path = registry / "state" / "registry" / "projections.json"
    hidden_state_names = hidden | blocked | managed_names
    rules, removed_rules = _filtered_state(
        rules_path, "rules", hidden_state_names, runtime_mirrors, mirror_target_ids
    )
    projections, removed_projections = _filtered_state(
        projections_path,
        "projections",
        hidden_state_names,
        runtime_mirrors,
        mirror_target_ids,
    )
    state_updates[rules_path] = rules
    state_updates[projections_path] = projections
    # Codex Skills use ~/.agents/skills, while plugin configuration remains in
    # ~/.codex/config.toml. Require programmatic callers that change plugin state
    # to provide the configuration home explicitly instead of guessing from the
    # Skill home.
    if policy.get("plugin_states") and codex_config_home is None:
        raise ReconcileError(
            "codex_config_home is required when plugin_states are configured"
        )
    plugin_config = (codex_config_home or Path.home() / ".codex") / "config.toml"
    plugin_changes, plugin_text = plan_plugin_states(plugin_config, policy)
    if plugin_text is not None:
        text_updates[plugin_config] = plugin_text
    return (
        ReconcilePlan(
            hardened=tuple(hardened),
            global_links_to_remove=tuple(global_links),
            global_links_to_create=tuple(global_creations),
            global_links_to_replace=tuple(global_replacements),
            project_links_to_remove=tuple(project_removals),
            project_links_to_create=tuple(project_links),
            project_links_to_replace=tuple(project_replacements),
            review_skills=tuple(sorted(classification.review_names)),
            profile_skills=tuple(sorted(classification.profile_names)),
            managed_global_skill_count=classification.global_skill_count,
            managed_description_chars=classification.global_description_chars,
            plugin_state_changes=plugin_changes,
            state_rules_to_remove=removed_rules,
            state_projections_to_remove=removed_projections,
        ),
        text_updates,
        state_updates,
    )


def apply_plan(
    plan: ReconcilePlan,
    text_updates: dict[Path, str],
    state_updates: dict[Path, dict],
) -> None:
    if plan.plugin_state_changes:
        config_paths = [path for path in text_updates if path.name == "config.toml"]
        if len(config_paths) != 1:
            raise ReconcileError(
                "plugin changes require exactly one config.toml text update"
            )
        config_path = config_paths[0]
        stamp = datetime.now().strftime("%Y%m%dT%H%M%S")
        backup = config_path.with_name(f"config.toml.bak-skill-governance-{stamp}")
        if backup.exists():
            raise ReconcileError(f"plugin config backup already exists: {backup}")
        shutil.copy2(config_path, backup)
    for path, text in text_updates.items():
        _atomic_write(path, text)
    for path, value in state_updates.items():
        _atomic_write(path, json.dumps(value, ensure_ascii=False, indent=2) + "\n")
    for raw_path in plan.global_links_to_remove:
        Path(raw_path).unlink()
    for raw_path in plan.project_links_to_remove:
        Path(raw_path).unlink()
    for raw_path, raw_target in [
        *plan.global_links_to_replace,
        *plan.global_links_to_create,
        *plan.project_links_to_replace,
        *plan.project_links_to_create,
    ]:
        path = Path(raw_path)
        path.parent.mkdir(parents=True, exist_ok=True)
        if path.is_symlink():
            path.unlink()
        path.symlink_to(Path(raw_target))


def build_reconcile_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--registry", type=Path, required=True)
    parser.add_argument("--policy", type=Path, required=True)
    for runtime, home in default_runtime_homes().items():
        parser.add_argument(runtime_home_flag(runtime), type=Path, default=home)
    parser.add_argument(
        "--codex-config-home",
        type=Path,
        default=Path.home() / ".codex",
        help="Codex configuration home containing config.toml",
    )
    parser.add_argument("--apply", action="store_true")
    return parser


def _runtime_homes(args: argparse.Namespace) -> dict[str, Path]:
    return {
        runtime: getattr(args, runtime_home_dest(runtime)).expanduser()
        for runtime in RUNTIME_HOME_DIRS
    }


def main(argv: list[str] | None = None) -> int:
    args = build_reconcile_parser().parse_args(argv)
    registry = args.registry.expanduser().resolve()
    policy = _load_json(args.policy.expanduser().resolve())
    try:
        plan, text_updates, state_updates = build_plan(
            registry,
            policy,
            runtime_homes=_runtime_homes(args),
            codex_config_home=args.codex_config_home.expanduser(),
        )
        if args.apply:
            apply_plan(plan, text_updates, state_updates)
    except (
        OSError,
        ExposureError,
        PluginPolicyError,
        ReconcileError,
        RuntimePolicyError,
    ) as exc:
        print(json.dumps({"ok": False, "error": str(exc)}, ensure_ascii=False))
        return 2
    print(
        json.dumps(
            {"ok": True, "applied": args.apply, **plan.as_dict()},
            ensure_ascii=False,
            indent=2,
        )
    )
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall