majiayu000/spellbook / skills/skill-ecosystem-doctor
skill-ecosystem-doctor
VerifiedAudit 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.8 KB |
| agents/openai.yaml | config | 354 B |
| assets/remediation-log-template.md | markdown | 1.1 KB |
| assets/skill-governance.example.json | config | 1.2 KB |
| evals/evals.json | config | 5.1 KB |
| references/governance-schema.md | markdown | 9.4 KB |
| references/lifecycle-drift.md | markdown | 2.1 KB |
| references/remediation-playbook.md | markdown | 3.7 KB |
| references/runtime-contracts.md | markdown | 4.3 KB |
| requirements.txt | manifest | 7 B |
| scripts/ecosystem_checks.py | script | 14.1 KB |
| scripts/ecosystem_doctor.pyexecutable | script | 2.1 KB |
| scripts/ecosystem_exposure.py | script | 7.3 KB |
| scripts/ecosystem_governance.py | script | 11.9 KB |
| scripts/ecosystem_legacy.py | script | 11.8 KB |
| scripts/ecosystem_model.py | script | 8.6 KB |
| scripts/ecosystem_plugins.py | script | 2.6 KB |
| scripts/ecosystem_reconcile.py | script | 34.7 KB |
| scripts/ecosystem_runtimes.py | script | 4.6 KB |
| scripts/ecosystem_scans.py | script | 25.3 KB |
| scripts/ecosystem_split.py | script | 8.5 KB |
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())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |