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_legacy.py
View on GitHub"""Normalize the deployed Loom governance policy into Doctor schema v1."""
from __future__ import annotations
from pathlib import Path
from ecosystem_exposure import expand_profile_scopes
from ecosystem_model import (
INVENTORY_ROOT_KINDS,
RUNTIME_HOME_DIRS,
SUPPORTED_RUNTIMES,
expand_path,
)
from ecosystem_plugins import PLUGIN_ID_RE
from ecosystem_runtimes import RuntimePolicyError, projection_runtimes
LEGACY_FIELDS = {
"projection_runtimes",
"schema_version",
"default_scope",
"trigger_boundary",
"project_scopes",
"project_scope_globs",
"project_source_roots",
"cold_storage",
"quarantined",
"retired",
"global_overrides",
"global_allowlist",
"profiles",
"profile_scopes",
"profile_scope_globs",
"exposure_budget",
"plugin_states",
"evidence_policy",
"duplicate_resolution",
"runtime_mirrors",
"managed_global_sources",
"frontmatter_extension_exceptions",
"splits",
"managed_physical_skills",
"inventory_roots",
"retired_reference_allowlist",
}
def is_legacy_policy(data: dict) -> bool:
return "source_policy" not in data and (
"project_scopes" in data or "trigger_boundary" in data
)
def _reject_unknown_fields(data: dict) -> None:
unknown = sorted(set(data) - LEGACY_FIELDS)
if unknown:
raise ValueError(
f"unknown legacy governance fields: {', '.join(unknown)}"
)
def _string_array(data: dict, field: str) -> list[str]:
values = data.get(field, [])
if not isinstance(values, list) or not all(
isinstance(value, str) and value.strip() for value in values
):
raise ValueError(f"legacy policy {field} must be a string array")
if len(values) != len(set(values)):
raise ValueError(f"legacy policy {field} contains duplicate values")
return values
def _scope_map(data: dict, field: str) -> dict[str, list[str]]:
values = data.get(field, {})
if not isinstance(values, dict):
raise ValueError(f"legacy policy {field} must be an object")
for raw_root, names in values.items():
if (
not isinstance(raw_root, str)
or not raw_root.strip()
or not isinstance(names, list)
or not all(isinstance(name, str) and name.strip() for name in names)
):
raise ValueError(
f"legacy policy {field} must map paths to Skill name arrays"
)
return values
def _inventory_roots(data: dict, registry: Path) -> list[dict[str, str]]:
roots: list[dict[str, str]] = []
seen: set[str] = set()
registry_skills = (registry / "skills").resolve(strict=False)
def add(raw_path: str, kind: str, owner: str) -> None:
source = expand_path(raw_path).resolve(strict=False)
if source == registry_skills or source.is_relative_to(registry_skills):
return
normalized = str(source)
if normalized in seen:
return
seen.add(normalized)
roots.append({"path": normalized, "kind": kind, "owner": owner})
configured_roots = data.get("inventory_roots", [])
if not isinstance(configured_roots, list):
raise ValueError("legacy policy inventory_roots must be an array")
configured_paths: set[str] = set()
for index, item in enumerate(configured_roots):
context = f"legacy policy inventory_roots[{index}]"
if not isinstance(item, dict):
raise ValueError(f"{context} must be an object")
unknown = sorted(set(item) - {"path", "kind", "owner"})
if unknown:
raise ValueError(f"{context} has unknown fields: {', '.join(unknown)}")
raw_path = item.get("path")
kind = item.get("kind")
owner = item.get("owner")
if not isinstance(raw_path, str) or not raw_path.strip():
raise ValueError(f"{context}.path must be a non-empty string")
if kind not in INVENTORY_ROOT_KINDS:
allowed = ", ".join(sorted(INVENTORY_ROOT_KINDS))
raise ValueError(f"{context}.kind must be one of: {allowed}")
if not isinstance(owner, str) or not owner.strip():
raise ValueError(f"{context}.owner must be a non-empty string")
normalized = str(expand_path(raw_path).resolve(strict=False))
if normalized == str(registry_skills) or Path(normalized).is_relative_to(
registry_skills
):
raise ValueError(f"{context}.path overlaps the canonical registry")
if normalized in configured_paths:
raise ValueError(f"duplicate legacy inventory root: {normalized}")
configured_paths.add(normalized)
add(raw_path, kind, owner)
source_roots = data.get("project_source_roots", {})
if not isinstance(source_roots, dict):
raise ValueError("legacy policy project_source_roots must be an object")
for raw_owner, relative in source_roots.items():
if (
not isinstance(raw_owner, str)
or not raw_owner.strip()
or not isinstance(relative, str)
or not relative.strip()
):
raise ValueError(
"legacy policy project_source_roots must map paths to relative directories"
)
add(str(expand_path(raw_owner) / relative), "canonical_source", raw_owner)
managed = data.get("managed_global_sources", {})
if not isinstance(managed, dict):
raise ValueError("legacy policy managed_global_sources must be an object")
for name, value in managed.items():
if not isinstance(name, str) or not isinstance(value, dict):
raise ValueError(
"legacy policy managed_global_sources entries must be objects"
)
source = value.get("source")
runtimes = value.get("runtimes")
if (
not isinstance(source, str)
or not source.strip()
or not isinstance(runtimes, list)
or not runtimes
or not all(
isinstance(runtime, str)
and runtime
and runtime in SUPPORTED_RUNTIMES
for runtime in runtimes
)
):
raise ValueError(f"legacy managed global source is invalid: {name}")
add(source, "repository_source", f"managed-global:{name}")
mirrors = data.get("runtime_mirrors", {})
if not isinstance(mirrors, dict):
raise ValueError("legacy policy runtime_mirrors must be an object")
mirror_names = mirrors.get("claude_only", [])
mirror_root = mirrors.get("authoritative_root")
if not isinstance(mirror_names, list) or not all(
isinstance(name, str) for name in mirror_names
):
raise ValueError("legacy policy runtime_mirrors.claude_only must be an array")
if mirror_names:
if not isinstance(mirror_root, str) or not mirror_root.strip():
raise ValueError(
"legacy policy runtime_mirrors.authoritative_root is required"
)
add(mirror_root, "managed_cache", "codex-system")
return roots
def normalize_legacy_policy(data: dict, path: Path) -> dict:
_reject_unknown_fields(data)
if data.get("schema_version") != 1:
raise ValueError("schema_version must be 1")
expanded, _ = expand_profile_scopes(data)
project_scopes = _scope_map(expanded, "project_scopes")
project_globs = _scope_map(expanded, "project_scope_globs")
cold = _string_array(data, "cold_storage")
quarantined = _string_array(data, "quarantined")
overlap = set(cold) & set(quarantined)
if overlap:
raise ValueError(
f"legacy policy cold_storage and quarantined overlap: {sorted(overlap)}"
)
retired = _string_array(data, "retired")
_string_array(data, "global_allowlist")
default_scope = data.get("default_scope", "global")
if default_scope not in {"global", "review"}:
raise ValueError("legacy policy default_scope must be 'global' or 'review'")
plugin_states = data.get("plugin_states", {})
if not isinstance(plugin_states, dict) or not all(
isinstance(name, str)
and PLUGIN_ID_RE.fullmatch(name)
and isinstance(enabled, bool)
for name, enabled in plugin_states.items()
):
raise ValueError("legacy policy plugin_states must map plugin ids to booleans")
evidence_policy = data.get("evidence_policy", {})
if not isinstance(evidence_policy, dict):
raise ValueError("legacy policy evidence_policy must be an object")
unknown_evidence = set(evidence_policy) - {"codex_audit_skill_threshold"}
if unknown_evidence:
raise ValueError(
f"unknown legacy evidence policy field: {sorted(unknown_evidence)[0]}"
)
audit_threshold = evidence_policy.get("codex_audit_skill_threshold", 8)
if not isinstance(audit_threshold, int) or audit_threshold <= 0:
raise ValueError(
"legacy evidence policy codex_audit_skill_threshold must be a positive integer"
)
exposure_budget = data.get("exposure_budget", {})
if not isinstance(exposure_budget, dict):
raise ValueError("legacy policy exposure_budget must be an object")
for field, value in exposure_budget.items():
if field not in {
"max_managed_global_skills",
"max_managed_description_chars",
}:
raise ValueError(f"unknown legacy exposure budget field: {field}")
if not isinstance(value, int) or value <= 0:
raise ValueError(f"legacy exposure budget {field} must be a positive integer")
managed_physical = data.get("managed_physical_skills", {})
if not isinstance(managed_physical, dict) or not all(
isinstance(name, str)
and name.strip()
and isinstance(owner, str)
and owner.strip()
for name, owner in managed_physical.items()
):
raise ValueError(
"legacy policy managed_physical_skills must map Skill names to owners"
)
reference_allowlist = data.get("retired_reference_allowlist", [])
if not isinstance(reference_allowlist, list):
raise ValueError("legacy policy retired_reference_allowlist must be an array")
for index, item in enumerate(reference_allowlist):
if (
not isinstance(item, dict)
or not isinstance(item.get("skill"), str)
or not item["skill"].strip()
or not isinstance(item.get("retired_name"), str)
or not item["retired_name"].strip()
):
raise ValueError(
f"legacy policy retired_reference_allowlist[{index}] is invalid"
)
registry = path.parent.resolve(strict=False)
if not (registry / "skills").is_dir():
raise ValueError(
"legacy governance file must live in a registry containing skills/"
)
try:
runtimes = projection_runtimes(data)
except RuntimePolicyError as exc:
raise ValueError(f"legacy policy {exc}") from exc
projection_globs: list[str] = []
for raw_root in [*project_scopes, *project_globs]:
root = str(expand_path(raw_root))
for runtime in runtimes:
candidate = str(Path(root) / RUNTIME_HOME_DIRS[runtime] / "skills")
if candidate not in projection_globs:
projection_globs.append(candidate)
return {
"schema_version": 1,
"source_policy": {
"local_only_canonical_registry": str(registry),
"projection_roots": [
f"~/{RUNTIME_HOME_DIRS[runtime]}/skills" for runtime in runtimes
],
"projection_globs": projection_globs,
"inventory_roots": _inventory_roots(data, registry),
"managed_physical_skills": managed_physical,
},
"retired_skills": retired,
"quarantined_skills": [*cold, *quarantined],
"projection_denials": [],
"pinned_materializations": [],
"retired_reference_allowlist": reference_allowlist,
"external_actions": [],
}
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 |