Split meta skill CLI and review gates
Merge the beta-ready Yao Meta Skill architecture, report, evidence gate, and release-boundary updates.\n\nRelease boundary: beta/public testing is allowed; formal world-class, fully reviewed, or superiority claims remain blocked until the pending evidence gates are accepted.
This commit is contained in:
YAO
+5
-284
@@ -10,96 +10,15 @@ try:
|
||||
except ImportError: # pragma: no cover
|
||||
yaml = None
|
||||
|
||||
from skill_ir_paths import find_skill_ir as find_skill_ir_document
|
||||
from compile_skill_targets import TARGET_TRANSFORMS, target_native_contract, target_permission_contract
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parent.parent
|
||||
COMPILER_SCHEMA_VERSION = "1.0"
|
||||
COMPILER_NAME = "yao-skill-ir-compiler"
|
||||
|
||||
|
||||
TARGET_TRANSFORMS: dict[str, dict[str, Any]] = {
|
||||
"openai": {
|
||||
"adapter_mode": "metadata-adapter",
|
||||
"generated_files": ["targets/openai/adapter.json", "targets/openai/agents/openai.yaml"],
|
||||
"metadata_mapping": {
|
||||
"display_name": "targets/openai/agents/openai.yaml::interface.display_name",
|
||||
"default_prompt": "targets/openai/agents/openai.yaml::interface.default_prompt",
|
||||
"activation": "targets/openai/agents/openai.yaml::compatibility.activation_mode",
|
||||
"execution": "targets/openai/agents/openai.yaml::compatibility.execution_context",
|
||||
"trust": "targets/openai/agents/openai.yaml::compatibility.trust_level",
|
||||
"permissions": "targets/openai/agents/openai.yaml::compatibility.permission_contract",
|
||||
"degradation": "targets/openai/agents/openai.yaml::compatibility.degradation_strategy",
|
||||
},
|
||||
"preserved_semantics": ["trigger", "workflow-counts", "resources", "eval-plan", "risk", "governance", "runtime", "trust", "permissions"],
|
||||
"unsupported_features": ["client-native script permission prompts are represented as permission contract metadata"],
|
||||
},
|
||||
"claude": {
|
||||
"adapter_mode": "neutral-source-plus-adapter",
|
||||
"generated_files": ["targets/claude/adapter.json", "targets/claude/README.md"],
|
||||
"metadata_mapping": {
|
||||
"display_name": "targets/claude/adapter.json::display_name",
|
||||
"default_prompt": "targets/claude/adapter.json::default_prompt",
|
||||
"activation": "targets/claude/adapter.json::activation_mode",
|
||||
"execution": "targets/claude/adapter.json::execution_context",
|
||||
"trust": "targets/claude/adapter.json::trust_level",
|
||||
"permissions": "targets/claude/adapter.json::target_permission_contract",
|
||||
"degradation": "targets/claude/adapter.json::degradation_strategy",
|
||||
},
|
||||
"preserved_semantics": ["trigger", "workflow-counts", "resources", "eval-plan", "risk", "governance", "runtime", "trust", "permissions"],
|
||||
"unsupported_features": ["vendor-native metadata fields are carried as adapter JSON and README notes"],
|
||||
},
|
||||
"generic": {
|
||||
"adapter_mode": "agent-skills-compatible",
|
||||
"generated_files": ["targets/generic/adapter.json"],
|
||||
"metadata_mapping": {
|
||||
"display_name": "targets/generic/adapter.json::display_name",
|
||||
"default_prompt": "targets/generic/adapter.json::default_prompt",
|
||||
"activation": "targets/generic/adapter.json::activation_mode",
|
||||
"execution": "targets/generic/adapter.json::execution_context",
|
||||
"trust": "targets/generic/adapter.json::trust_level",
|
||||
"permissions": "targets/generic/adapter.json::target_permission_contract",
|
||||
"degradation": "targets/generic/adapter.json::degradation_strategy",
|
||||
},
|
||||
"preserved_semantics": ["trigger", "workflow-counts", "resources", "eval-plan", "risk", "governance", "runtime", "trust", "permissions"],
|
||||
"unsupported_features": [],
|
||||
},
|
||||
"agent-skills-compatible": {
|
||||
"adapter_mode": "neutral-agent-skills-source",
|
||||
"generated_files": ["SKILL.md", "agents/interface.yaml"],
|
||||
"metadata_mapping": {
|
||||
"name": "SKILL.md::frontmatter.name",
|
||||
"description": "SKILL.md::frontmatter.description",
|
||||
"interface": "agents/interface.yaml",
|
||||
"manifest": "manifest.json",
|
||||
},
|
||||
"preserved_semantics": ["trigger", "workflow", "resources", "eval-plan", "risk", "governance", "runtime", "trust", "permissions"],
|
||||
"unsupported_features": [],
|
||||
},
|
||||
"agent-skills": {
|
||||
"adapter_mode": "neutral-agent-skills-source",
|
||||
"generated_files": ["SKILL.md", "agents/interface.yaml"],
|
||||
"metadata_mapping": {
|
||||
"name": "SKILL.md::frontmatter.name",
|
||||
"description": "SKILL.md::frontmatter.description",
|
||||
"interface": "agents/interface.yaml",
|
||||
"manifest": "manifest.json",
|
||||
},
|
||||
"preserved_semantics": ["trigger", "workflow", "resources", "eval-plan", "risk", "governance", "runtime", "trust", "permissions"],
|
||||
"unsupported_features": [],
|
||||
},
|
||||
"vscode": {
|
||||
"adapter_mode": "agent-skills-compatible-project-or-user-scope",
|
||||
"generated_files": ["SKILL.md", "agents/interface.yaml"],
|
||||
"metadata_mapping": {
|
||||
"name": "folder-name-and-SKILL.md::frontmatter.name",
|
||||
"description": "SKILL.md::frontmatter.description",
|
||||
"interface": "agents/interface.yaml",
|
||||
},
|
||||
"preserved_semantics": ["trigger", "workflow", "resources", "eval-plan", "risk", "governance", "runtime", "trust", "permissions"],
|
||||
"unsupported_features": ["VS Code installation scope is documented but not installed by this compiler"],
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
def display_path(path: Path, root: Path = ROOT) -> str:
|
||||
try:
|
||||
return str(path.resolve().relative_to(root.resolve()))
|
||||
@@ -146,20 +65,7 @@ def read_frontmatter(path: Path) -> dict[str, Any]:
|
||||
|
||||
|
||||
def find_skill_ir(skill_dir: Path, name: str) -> tuple[dict[str, Any], str]:
|
||||
candidates = [
|
||||
skill_dir / "reports" / "skill-ir.json",
|
||||
skill_dir / "skill-ir" / "examples" / f"{name}.json",
|
||||
skill_dir / "skill-ir" / "examples" / f"{skill_dir.name}.json",
|
||||
]
|
||||
seen: set[Path] = set()
|
||||
for path in candidates:
|
||||
if path in seen:
|
||||
continue
|
||||
seen.add(path)
|
||||
payload = load_json(path)
|
||||
if payload:
|
||||
return payload, display_path(path, skill_dir)
|
||||
return {}, "frontmatter-fallback"
|
||||
return find_skill_ir_document(skill_dir, name, fallback_source="frontmatter-fallback")
|
||||
|
||||
|
||||
def count_list(payload: dict[str, Any], key: str) -> int:
|
||||
@@ -246,191 +152,6 @@ def permission_contract(skill_dir: Path) -> dict[str, Any]:
|
||||
}
|
||||
|
||||
|
||||
TARGET_PERMISSION_MODELS = {
|
||||
"openai": {
|
||||
"model": "metadata-only",
|
||||
"native_enforcement": False,
|
||||
"representation": "targets/openai/agents/openai.yaml::compatibility.permission_contract plus adapter.json",
|
||||
"operator_note": "OpenAI target carries permission metadata for reviewer visibility; host enforcement remains outside the package.",
|
||||
},
|
||||
"claude": {
|
||||
"model": "neutral-source-plus-adapter",
|
||||
"native_enforcement": False,
|
||||
"representation": "targets/claude/adapter.json::target_permission_contract and README notes",
|
||||
"operator_note": "Claude-compatible package keeps permission intent in adapter metadata for install review.",
|
||||
},
|
||||
"generic": {
|
||||
"model": "agent-skills-compatible-metadata",
|
||||
"native_enforcement": False,
|
||||
"representation": "targets/generic/adapter.json::target_permission_contract",
|
||||
"operator_note": "Generic target exposes permission metadata for downstream clients to enforce or review.",
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
TARGET_NATIVE_MODELS = {
|
||||
"openai": {
|
||||
"native_surface": "OpenAI-style interface metadata plus neutral Agent Skills source",
|
||||
"activation_policy": "Use frontmatter description for catalog routing and targets/openai/agents/openai.yaml for display name, default prompt, and compatibility metadata.",
|
||||
"resource_strategy": "Ship the neutral source tree and expose OpenAI-facing interface metadata as a generated companion file.",
|
||||
"script_strategy": "Keep scripts as local package resources; expose help-smoke and permission metadata for reviewer approval before execution.",
|
||||
"permission_enforcement": "metadata-only",
|
||||
"install_scope": "plugin or skill package consumer",
|
||||
"review_artifacts": ["targets/openai/agents/openai.yaml", "targets/openai/adapter.json", "reports/review-studio.html"],
|
||||
"fallback_behavior": "If OpenAI-native metadata is ignored, the package remains readable as neutral Agent Skills source.",
|
||||
"unsupported_native_features": [
|
||||
"client-native permission prompts",
|
||||
"provider-executed scripts",
|
||||
],
|
||||
},
|
||||
"claude": {
|
||||
"native_surface": "Claude-compatible neutral source folder with adapter notes",
|
||||
"activation_policy": "Use SKILL.md frontmatter description as the primary activation contract and adapter.json for review metadata.",
|
||||
"resource_strategy": "Preserve the source tree directly; write target notes in targets/claude/README.md.",
|
||||
"script_strategy": "Scripts remain local package resources and must be reviewed through trust and permission reports before use.",
|
||||
"permission_enforcement": "metadata-fallback",
|
||||
"install_scope": "user or project skill directory",
|
||||
"review_artifacts": ["targets/claude/README.md", "targets/claude/adapter.json", "reports/review-studio.html"],
|
||||
"fallback_behavior": "If Claude-specific metadata is not consumed, SKILL.md and references remain the source of truth.",
|
||||
"unsupported_native_features": [
|
||||
"vendor-native permission enforcement",
|
||||
"provider-specific execution transforms",
|
||||
],
|
||||
},
|
||||
"generic": {
|
||||
"native_surface": "Agent Skills compatible neutral package",
|
||||
"activation_policy": "Use SKILL.md name and description; consumers decide automatic or manual activation.",
|
||||
"resource_strategy": "Preserve references, scripts, assets, evals, reports, and adapter metadata as relative package resources.",
|
||||
"script_strategy": "Expose script and permission metadata for downstream clients or installers to enforce.",
|
||||
"permission_enforcement": "consumer-enforced-or-metadata-only",
|
||||
"install_scope": "generic Agent Skills compatible root",
|
||||
"review_artifacts": ["targets/generic/adapter.json", "reports/review-studio.html"],
|
||||
"fallback_behavior": "Neutral source is the runtime fallback.",
|
||||
"unsupported_native_features": [],
|
||||
},
|
||||
"agent-skills-compatible": {
|
||||
"native_surface": "Agent Skills standard source tree",
|
||||
"activation_policy": "Use SKILL.md frontmatter name and description for progressive disclosure.",
|
||||
"resource_strategy": "Keep optional directories as relative resources next to SKILL.md.",
|
||||
"script_strategy": "Scripts remain local optional resources and should advertise --help when executable.",
|
||||
"permission_enforcement": "consumer-enforced-or-metadata-only",
|
||||
"install_scope": "Agent Skills source root",
|
||||
"review_artifacts": ["SKILL.md", "agents/interface.yaml", "reports/review-studio.html"],
|
||||
"fallback_behavior": "The source tree itself is the target artifact.",
|
||||
"unsupported_native_features": [],
|
||||
},
|
||||
"agent-skills": {
|
||||
"native_surface": "Agent Skills standard source tree",
|
||||
"activation_policy": "Use SKILL.md frontmatter name and description for progressive disclosure.",
|
||||
"resource_strategy": "Keep optional directories as relative resources next to SKILL.md.",
|
||||
"script_strategy": "Scripts remain local optional resources and should advertise --help when executable.",
|
||||
"permission_enforcement": "consumer-enforced-or-metadata-only",
|
||||
"install_scope": "Agent Skills source root",
|
||||
"review_artifacts": ["SKILL.md", "agents/interface.yaml", "reports/review-studio.html"],
|
||||
"fallback_behavior": "The source tree itself is the target artifact.",
|
||||
"unsupported_native_features": [],
|
||||
},
|
||||
"vscode": {
|
||||
"native_surface": "VS Code/Copilot Agent Skills project or user scope",
|
||||
"activation_policy": "Use folder name plus SKILL.md name/description; keep description under platform limits.",
|
||||
"resource_strategy": "Install as project or user scoped skill source, preserving relative references and scripts.",
|
||||
"script_strategy": "Scripts require workspace trust and operator/client approval outside this compiler.",
|
||||
"permission_enforcement": "client-or-workspace-trust",
|
||||
"install_scope": "VS Code user or project skills directory",
|
||||
"review_artifacts": ["SKILL.md", "agents/interface.yaml", "reports/review-studio.html"],
|
||||
"fallback_behavior": "If VS Code scope is not installed, use the neutral Agent Skills source.",
|
||||
"unsupported_native_features": [
|
||||
"automatic VS Code installation",
|
||||
],
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
def target_permission_contract(target: str, permissions: dict[str, Any]) -> dict[str, Any]:
|
||||
model = TARGET_PERMISSION_MODELS.get(
|
||||
target,
|
||||
{
|
||||
"model": "metadata-only",
|
||||
"native_enforcement": False,
|
||||
"representation": "adapter metadata",
|
||||
"operator_note": "Permission semantics are preserved as metadata for reviewer visibility.",
|
||||
},
|
||||
)
|
||||
return {
|
||||
"schema_version": "1.0",
|
||||
"target": target,
|
||||
"permission_model": model["model"],
|
||||
"native_enforcement": model["native_enforcement"],
|
||||
"representation": model["representation"],
|
||||
"review_required": bool(permissions.get("review_required")),
|
||||
"declared_capabilities": permissions.get("declared_capabilities", []),
|
||||
"capability_counts": {
|
||||
name: item.get("script_count", 0)
|
||||
for name, item in permissions.get("capabilities", {}).items()
|
||||
},
|
||||
"evidence": permissions.get("source", ""),
|
||||
"operator_note": model["operator_note"],
|
||||
}
|
||||
|
||||
|
||||
def target_native_contract(
|
||||
target: str,
|
||||
profile: dict[str, Any],
|
||||
contract: dict[str, Any],
|
||||
target_permissions: dict[str, Any],
|
||||
) -> dict[str, Any]:
|
||||
model = TARGET_NATIVE_MODELS.get(
|
||||
target,
|
||||
{
|
||||
"native_surface": "adapter metadata",
|
||||
"activation_policy": "Carry activation semantics as metadata for the target consumer.",
|
||||
"resource_strategy": "Preserve neutral package resources.",
|
||||
"script_strategy": "Expose script metadata for reviewer visibility.",
|
||||
"permission_enforcement": "metadata-only",
|
||||
"install_scope": "target consumer",
|
||||
"review_artifacts": ["adapter.json", "reports/review-studio.html"],
|
||||
"fallback_behavior": "Use neutral source package.",
|
||||
"unsupported_native_features": [],
|
||||
},
|
||||
)
|
||||
return {
|
||||
"schema_version": "1.0",
|
||||
"target": target,
|
||||
"native_surface": model["native_surface"],
|
||||
"activation": {
|
||||
"policy": model["activation_policy"],
|
||||
"trigger_description": contract.get("trigger", {}).get("description", ""),
|
||||
"manual_activation_supported": True,
|
||||
"automatic_activation_note": "Depends on the target client route/catalog implementation.",
|
||||
},
|
||||
"resources": {
|
||||
"strategy": model["resource_strategy"],
|
||||
"counts": contract.get("resources", {}).get("counts", {}),
|
||||
"generated_files": profile.get("generated_files", []),
|
||||
},
|
||||
"scripts": {
|
||||
"strategy": model["script_strategy"],
|
||||
"script_count": contract.get("resources", {}).get("counts", {}).get("scripts", 0),
|
||||
"help_smoke_failed_count": contract.get("permissions", {}).get("help_smoke", {}).get("failed_count", 0),
|
||||
},
|
||||
"permissions": {
|
||||
"enforcement": model["permission_enforcement"],
|
||||
"native_enforcement": bool(target_permissions.get("native_enforcement")),
|
||||
"declared_capabilities": target_permissions.get("declared_capabilities", []),
|
||||
"review_required": bool(target_permissions.get("review_required")),
|
||||
},
|
||||
"review": {
|
||||
"artifacts": model["review_artifacts"],
|
||||
"fallback_behavior": model["fallback_behavior"],
|
||||
"unsupported_native_features": [
|
||||
*model.get("unsupported_native_features", []),
|
||||
*profile.get("unsupported_features", []),
|
||||
],
|
||||
},
|
||||
"install_scope": model["install_scope"],
|
||||
}
|
||||
|
||||
|
||||
def load_sources(skill_dir: Path) -> dict[str, Any]:
|
||||
skill_dir = skill_dir.resolve()
|
||||
frontmatter = read_frontmatter(skill_dir / "SKILL.md")
|
||||
@@ -545,7 +266,7 @@ def compile_target_contract(skill_dir: Path, target: str) -> dict[str, Any]:
|
||||
"preserved_semantics": [],
|
||||
"unsupported_features": [],
|
||||
}
|
||||
if target not in declared and not (target == "agent-skills" and "agent-skills-compatible" in declared):
|
||||
if target not in declared and not (target in {"agent-skills", "vscode"} and "agent-skills-compatible" in declared):
|
||||
warnings.append(f"Target is not declared in Skill IR or interface metadata: {target}")
|
||||
if not sources["ir"]:
|
||||
warnings.append("Skill IR is missing; compiler used frontmatter fallback")
|
||||
|
||||
Reference in New Issue
Block a user