agent-devkit 0.1.6 → 0.2.0

package/runtime/scripts/release-gate.py

@@ -11,11 +11,14 @@ import sys
 from pathlib import Path
 from typing import Any
 
+import yaml
+
 
 ROOT = Path(__file__).resolve().parents[1]
 AGENT = ROOT / "agent"
 VALIDATE_REPO = ROOT / "scripts" / "validate-repo.py"
 MVP_READINESS = ROOT / "scripts" / "mvp-readiness.py"
+CATALOG_SNAPSHOT = ROOT / "scripts" / "release-catalog-snapshot.json"
 CLAUDE_SKILL = ROOT / "plugins" / "claude-skill-ai-devkit" / "ai-devkit"
 CODEX_HOME = Path(os.environ.get("CODEX_HOME", Path.home() / ".codex"))
 SKILL_VALIDATOR = CODEX_HOME / "skills" / ".system" / "skill-creator" / "scripts" / "quick_validate.py"
@@ -39,7 +42,9 @@ def run_gate(*, quick: bool = False) -> dict[str, Any]:
     checks = [
         check_command("agent version", [sys.executable, str(AGENT), "--version"], validate_agent_version),
         check_json("repo strict validation", [sys.executable, str(VALIDATE_REPO), "--strict", "--json"], validate_repo),
+        catalog_snapshot_check(),
         check_json("mvp readiness", [sys.executable, str(MVP_READINESS), "--json"], validate_mvp_readiness),
+        check_json("v0.2.0 runtime evals", [sys.executable, str(AGENT), "eval", "run", "all", "--json"], validate_v020_evals),
         skill_validation_check(),
     ]
     if quick:
@@ -71,13 +76,21 @@ def unittest_command() -> list[str]:
     paths = [
         path
         for path in ROOT.rglob("test*.py")
-        if "vendor" not in path.relative_to(ROOT).parts
+        if include_unittest_path(path)
     ]
     paths.sort(key=unittest_path_sort_key)
     test_files = [str(path.relative_to(ROOT)) for path in paths]
     return [sys.executable, "-m", "unittest", *test_files]
 
 
+def include_unittest_path(path: Path) -> bool:
+    relative = path.relative_to(ROOT)
+    parts = relative.parts
+    if "vendor" in parts:
+        return False
+    return parts[:3] != ("tooling", "agent-devkit", "runtime")
+
+
 def unittest_path_sort_key(path: Path) -> tuple[int, str]:
     relative = path.relative_to(ROOT)
     first = relative.parts[0] if relative.parts else ""
@@ -141,6 +154,104 @@ def validate_repo(payload: dict[str, Any]) -> str | None:
     return None
 
 
+def catalog_snapshot_check() -> dict[str, Any]:
+    name = "catalog snapshot"
+    if not CATALOG_SNAPSHOT.exists():
+        return failed_static_check(name, f"catalog snapshot not found: {CATALOG_SNAPSHOT}")
+    try:
+        expected = json.loads(CATALOG_SNAPSHOT.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        return failed_static_check(name, f"invalid catalog snapshot json: {exc}")
+    current = build_catalog_snapshot()
+    message = validate_catalog_snapshot(expected, current)
+    if message:
+        check = failed_static_check(name, message)
+        check["summary"] = {"expected": summarize_snapshot(expected), "current": summarize_snapshot(current)}
+        return check
+    check = ok_static_check(name)
+    check["summary"] = summarize_snapshot(current)
+    return check
+
+
+def build_catalog_snapshot() -> dict[str, Any]:
+    agents: list[str] = []
+    capabilities_by_agent: dict[str, list[str]] = {}
+    for manifest_path in sorted(ROOT.glob("agents/*/agent.yaml")):
+        manifest = load_yaml(manifest_path)
+        agent_id = str(manifest.get("id") or manifest_path.parent.name)
+        agents.append(agent_id)
+        capabilities = []
+        for capability_path in sorted((manifest_path.parent / "capabilities").glob("*/capability.yaml")):
+            capability = load_yaml(capability_path)
+            capabilities.append(str(capability.get("id") or capability_path.parent.name).split(".")[-1])
+        capabilities_by_agent[agent_id] = sorted(capabilities)
+
+    providers = [
+        str(load_yaml(path).get("id") or path.stem)
+        for path in sorted(ROOT.glob("providers/*.yaml"))
+    ]
+    plugins = [
+        str(load_json(plugin_manifest_path(path)).get("id") or path.name)
+        for path in sorted((ROOT / "plugins").iterdir())
+        if path.is_dir() and plugin_manifest_path(path).exists()
+    ]
+    return {
+        "schema_version": "ai-devkit.release-catalog-snapshot/v1",
+        "version": expected_version(),
+        "summary": {
+            "agents": len(agents),
+            "capabilities": sum(len(items) for items in capabilities_by_agent.values()),
+            "providers": len(providers),
+            "plugins": len(plugins),
+        },
+        "agents": sorted(agents),
+        "providers": sorted(providers),
+        "plugins": sorted(plugins),
+        "capabilities_by_agent": capabilities_by_agent,
+    }
+
+
+def validate_catalog_snapshot(expected: dict[str, Any], current: dict[str, Any]) -> str | None:
+    if expected.get("schema_version") != current["schema_version"]:
+        return "catalog snapshot schema_version is not supported"
+    for key in ("version", "summary", "agents", "providers", "plugins", "capabilities_by_agent"):
+        if expected.get(key) != current.get(key):
+            return f"catalog snapshot mismatch in {key}; update scripts/release-catalog-snapshot.json intentionally for this release"
+    return None
+
+
+def summarize_snapshot(snapshot: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "version": snapshot.get("version"),
+        "summary": snapshot.get("summary") or {},
+    }
+
+
+def expected_version() -> str:
+    result = run([sys.executable, str(AGENT), "--version"])
+    prefix = "agent "
+    if result.returncode == 0 and result.stdout.startswith(prefix):
+        return result.stdout.strip()[len(prefix) :]
+    return "unknown"
+
+
+def plugin_manifest_path(plugin_dir: Path) -> Path:
+    codex_manifest = plugin_dir / ".codex-plugin" / "plugin.json"
+    if codex_manifest.exists():
+        return codex_manifest
+    return plugin_dir / "plugin.json"
+
+
+def load_yaml(path: Path) -> dict[str, Any]:
+    payload = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    return payload if isinstance(payload, dict) else {}
+
+
+def load_json(path: Path) -> dict[str, Any]:
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    return payload if isinstance(payload, dict) else {}
+
+
 def validate_mvp_readiness(payload: dict[str, Any]) -> str | None:
     if payload.get("kind") != "mvp-readiness" or payload.get("status") != "ok":
         return "mvp readiness is not ok"
@@ -149,6 +260,17 @@ def validate_mvp_readiness(payload: dict[str, Any]) -> str | None:
     return None
 
 
+def validate_v020_evals(payload: dict[str, Any]) -> str | None:
+    if payload.get("kind") != "eval-run" or payload.get("suite") != "all":
+        return "v0.2.0 eval command returned an unexpected payload"
+    if payload.get("status") != "passed":
+        return "v0.2.0 runtime evals did not pass"
+    checks = payload.get("checks") or []
+    if not isinstance(checks, list) or len(checks) < 5:
+        return "v0.2.0 runtime evals returned too few suites"
+    return None
+
+
 def validate_skill_validation(result: subprocess.CompletedProcess[str]) -> str | None:
     if "Skill is valid!" not in result.stdout:
         return "Claude Desktop skill validation did not report success"
@@ -182,6 +304,15 @@ def ok_check(name: str, result: subprocess.CompletedProcess[str]) -> dict[str, A
     }
 
 
+def ok_static_check(name: str) -> dict[str, Any]:
+    return {
+        "name": name,
+        "status": "ok",
+        "returncode": None,
+        "message": "",
+    }
+
+
 def failed_check(name: str, message: str, result: subprocess.CompletedProcess[str]) -> dict[str, Any]:
     return {
         "name": name,
@@ -193,6 +324,15 @@ def failed_check(name: str, message: str, result: subprocess.CompletedProcess[st
     }
 
 
+def failed_static_check(name: str, message: str) -> dict[str, Any]:
+    return {
+        "name": name,
+        "status": "failed",
+        "returncode": None,
+        "message": message,
+    }
+
+
 def skipped_check(name: str, message: str) -> dict[str, Any]:
     return {
         "name": name,

package/runtime/scripts/validate-repo.py

@@ -11,8 +11,14 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
+REPO_ROOT = Path(__file__).resolve().parents[1]
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT))
+
 import yaml
 
+from cli.aikit.write_policy import canonical_write_policies, legacy_write_policy_aliases
+
 
 KEBAB_CASE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
 AGENT_REQUIRED_KEYS = {
@@ -71,6 +77,36 @@ CAPABILITY_PROVIDER_FALLBACKS = {
     "skip_provider",
     "blocked",
 }
+CAPABILITY_EXECUTION_FIELDS = {"modes", "idempotency", "timeout_seconds"}
+CAPABILITY_EXECUTION_MODES = {"run", "dry-run"}
+CAPABILITY_IDEMPOTENCY_VALUES = {
+    "safe-repeat",
+    "creates-artifact",
+    "external-read",
+    "external-write",
+}
+CAPABILITY_ARTIFACT_KINDS = {"markdown", "json", "xlsx", "pptx", "drawio", "log", "other"}
+RUNTIME_SOURCE_FIELDS = {"enabled", "args", "env"}
+SOURCE_CONTRACT_FIELDS = {"enabled", "supported", "args", "env", "mappings", "apply"}
+SOURCE_MAPPING_FIELDS = {"field", "name", "arg", "env"}
+RUNTIME_ROLE_KINDS = {"coordinator", "reviewer", "provider-configurator", "local-worker", "none"}
+AGENT_MODE_TYPES = {"reactive", "workflow", "planner", "reviewer"}
+AGENT_MODE_LLM_VALUES = {False, "optional", "required"}
+AGENT_MODE_FIELDS = {
+    "type",
+    "max_steps",
+    "max_specialists",
+    "max_llm_calls",
+    "timeout_seconds",
+    "can_call_capabilities",
+    "can_call_llm",
+    "can_request_user_input",
+    "external_writes",
+    "allowed_capabilities",
+    "stop_conditions",
+}
+CANONICAL_WRITE_POLICIES = canonical_write_policies()
+LEGACY_WRITE_POLICY_ALIASES = legacy_write_policy_aliases()
 SECRET_MARKERS = ("SECRET", "TOKEN", "PASSWORD", "PAT", "API_KEY", "PRIVATE_KEY")
 ROOT_ARTIFACT_NAMES = {"json", "markdown"}
 ROOT_IGNORED_NAMES = {
@@ -138,6 +174,7 @@ class ValidationState:
             "errors": self.errors,
             "warnings": self.warnings,
             "agents": self.agent_stats,
+            "providers": sorted(self.provider_ids),
             "plugins": self.plugin_stats,
         }
 
@@ -439,6 +476,10 @@ def validate_agent(state: ValidationState, agent_dir: Path, manifest_path: Path)
 
     validate_status(state, manifest_path, manifest.get("status"))
     validate_relative_refs(state, agent_dir, manifest.get("default_context", []), "default_context")
+    validate_agent_write_policy(state, manifest_path, manifest.get("write_policy"))
+    validate_routing(state, manifest_path, manifest.get("routing"))
+    validate_runtime_role(state, manifest_path, manifest.get("runtime_role"), agent_kind=manifest.get("kind"))
+    validate_agent_mode(state, manifest_path, manifest.get("agent_mode"), write_policy=manifest.get("write_policy"))
 
     surface = manifest.get("agent_surface", {}) or {}
     if isinstance(surface, dict):
@@ -498,6 +539,12 @@ def validate_capability(state: ValidationState, agent_dir: Path, manifest_path:
         )
 
     validate_status(state, manifest_path, manifest.get("status"))
+    validate_write_policy_value(state, manifest_path, manifest.get("write_policy"))
+    validate_routing(state, manifest_path, manifest.get("routing"))
+    validate_runtime_contract(state, manifest_path, manifest.get("runtime"))
+    validate_source_contract(state, manifest_path, manifest.get("source"), field_prefix="source")
+    validate_capability_execution(state, manifest_path, manifest.get("execution"))
+    validate_capability_outputs(state, manifest_path, manifest.get("outputs"))
 
     entrypoint = manifest.get("entrypoint", {}) or {}
     if isinstance(entrypoint, dict):
@@ -524,6 +571,220 @@ def validate_capability(state: ValidationState, agent_dir: Path, manifest_path:
     validate_capability_provider_requirements(state, manifest_path, manifest.get("requires", {}))
 
 
+def validate_capability_execution(state: ValidationState, manifest_path: Path, execution: Any) -> None:
+    if execution is None:
+        return
+    relative_manifest = rel(state, manifest_path)
+    if not isinstance(execution, dict):
+        state.error(f"{relative_manifest} execution must be a mapping")
+        return
+    for key in execution:
+        if key not in CAPABILITY_EXECUTION_FIELDS:
+            state.error(f"{relative_manifest} execution has unsupported field: {key}")
+    modes = execution.get("modes")
+    if modes is not None:
+        if not isinstance(modes, list):
+            state.error(f"{relative_manifest} execution.modes must be a list")
+        else:
+            for mode in modes:
+                if mode not in CAPABILITY_EXECUTION_MODES:
+                    state.error(f"{relative_manifest} execution.modes has unsupported mode: {mode}")
+    idempotency = execution.get("idempotency")
+    if idempotency is not None and idempotency not in CAPABILITY_IDEMPOTENCY_VALUES:
+        state.error(f"{relative_manifest} execution.idempotency has unsupported value: {idempotency}")
+    timeout = execution.get("timeout_seconds")
+    if timeout is not None and (not isinstance(timeout, int) or timeout <= 0):
+        state.error(f"{relative_manifest} execution.timeout_seconds must be a positive integer")
+
+
+def validate_capability_outputs(state: ValidationState, manifest_path: Path, outputs: Any) -> None:
+    if outputs is None:
+        return
+    relative_manifest = rel(state, manifest_path)
+    if not isinstance(outputs, dict):
+        state.error(f"{relative_manifest} outputs must be a mapping")
+        return
+    artifacts = outputs.get("artifacts")
+    if artifacts is None:
+        return
+    if not isinstance(artifacts, list):
+        state.error(f"{relative_manifest} outputs.artifacts must be a list")
+        return
+    for item in artifacts:
+        if isinstance(item, str):
+            continue
+        if not isinstance(item, dict):
+            state.error(f"{relative_manifest} outputs.artifacts entries must be strings or mappings")
+            continue
+        path = item.get("path") or item.get("ref")
+        if not isinstance(path, str) or not path.strip():
+            state.error(f"{relative_manifest} outputs.artifacts entry missing path")
+        kind = item.get("kind")
+        if kind is not None and kind not in CAPABILITY_ARTIFACT_KINDS:
+            state.error(f"{relative_manifest} outputs.artifacts has unsupported kind: {kind}")
+        sensitive = item.get("sensitive")
+        if sensitive is not None and not isinstance(sensitive, bool):
+            state.error(f"{relative_manifest} outputs.artifacts sensitive must be boolean")
+
+
+def validate_runtime_contract(state: ValidationState, manifest_path: Path, runtime: Any) -> None:
+    if runtime is None:
+        return
+    relative_manifest = rel(state, manifest_path)
+    if not isinstance(runtime, dict):
+        state.error(f"{relative_manifest} runtime must be a mapping")
+        return
+    provider = runtime.get("provider")
+    if provider is not None:
+        provider_id = str(provider)
+        if not provider_id:
+            state.error(f"{relative_manifest} runtime.provider must be a non-empty string")
+        elif provider_id not in state.provider_ids:
+            state.error(f"{relative_manifest} runtime references unknown provider: {provider_id}")
+    source = runtime.get("source")
+    if source is None:
+        return
+    validate_source_contract(state, manifest_path, source, field_prefix="runtime.source", allowed_fields=RUNTIME_SOURCE_FIELDS)
+
+
+def validate_source_contract(
+    state: ValidationState,
+    manifest_path: Path,
+    source: Any,
+    *,
+    field_prefix: str,
+    allowed_fields: set[str] = SOURCE_CONTRACT_FIELDS,
+) -> None:
+    if source is None:
+        return
+    if not isinstance(source, dict):
+        state.error(f"{rel(state, manifest_path)} {field_prefix} must be a mapping")
+        return
+    relative_manifest = rel(state, manifest_path)
+    for key in source:
+        if key not in allowed_fields:
+            state.error(f"{relative_manifest} {field_prefix} has unsupported field: {key}")
+    for boolean_field in ("enabled", "supported"):
+        if boolean_field in source and not isinstance(source.get(boolean_field), bool):
+            state.error(f"{relative_manifest} {field_prefix}.{boolean_field} must be boolean")
+    for field in ("args", "env"):
+        mapping = source.get(field)
+        if mapping is None:
+            continue
+        if not isinstance(mapping, dict):
+            state.error(f"{relative_manifest} {field_prefix}.{field} must be a mapping")
+            continue
+        for name, value in mapping.items():
+            if not isinstance(name, str) or not name.strip() or not isinstance(value, str) or not value.strip():
+                state.error(f"{relative_manifest} {field_prefix}.{field} entries must be non-empty strings")
+                continue
+            if field == "args" and not value.startswith("--"):
+                state.error(f"{relative_manifest} {field_prefix}.args.{name} must map to a CLI flag")
+            if field == "env" and not re.match(r"^[A-Za-z_][A-Za-z0-9_]*$", value):
+                state.error(f"{relative_manifest} {field_prefix}.env.{name} must map to an environment variable")
+    for list_field in ("mappings", "apply"):
+        mappings = source.get(list_field)
+        if mappings is None:
+            continue
+        if not isinstance(mappings, list):
+            state.error(f"{relative_manifest} {field_prefix}.{list_field} must be a list")
+            continue
+        for index, item in enumerate(mappings):
+            item_prefix = f"{field_prefix}.{list_field}[{index}]"
+            if not isinstance(item, dict):
+                state.error(f"{relative_manifest} {item_prefix} entries must be mappings")
+                continue
+            for key in item:
+                if key not in SOURCE_MAPPING_FIELDS:
+                    state.error(f"{relative_manifest} {item_prefix} has unsupported field: {key}")
+            field_name = item.get("field") or item.get("name")
+            if not isinstance(field_name, str) or not field_name.strip():
+                state.error(f"{relative_manifest} {item_prefix} missing field")
+            arg = item.get("arg")
+            if arg is not None and (not isinstance(arg, str) or not arg.startswith("--")):
+                state.error(f"{relative_manifest} {item_prefix}.arg must map to a CLI flag")
+            env = item.get("env")
+            if env is not None and (not isinstance(env, str) or not re.match(r"^[A-Za-z_][A-Za-z0-9_]*$", env)):
+                state.error(f"{relative_manifest} {item_prefix}.env must map to an environment variable")
+
+
+def validate_runtime_role(state: ValidationState, manifest_path: Path, runtime_role: Any, *, agent_kind: Any) -> None:
+    relative_manifest = rel(state, manifest_path)
+    if agent_kind == "runtime-agent" and runtime_role is None:
+        state.error(f"{relative_manifest} runtime-agent must declare runtime_role")
+        return
+    if runtime_role is None:
+        return
+    if not isinstance(runtime_role, dict):
+        state.error(f"{relative_manifest} runtime_role must be a mapping")
+        return
+    role_kind = str(runtime_role.get("kind") or "")
+    if not role_kind:
+        state.error(f"{relative_manifest} runtime_role.kind must be a non-empty string")
+    elif role_kind not in RUNTIME_ROLE_KINDS:
+        state.error(f"{relative_manifest} runtime_role.kind has unsupported value: {role_kind}")
+
+
+def validate_agent_mode(state: ValidationState, manifest_path: Path, agent_mode: Any, *, write_policy: Any) -> None:
+    if agent_mode is None:
+        return
+    relative_manifest = rel(state, manifest_path)
+    if not isinstance(agent_mode, dict):
+        state.error(f"{relative_manifest} agent_mode must be a mapping")
+        return
+    for key in agent_mode:
+        if key not in AGENT_MODE_FIELDS:
+            state.error(f"{relative_manifest} agent_mode has unsupported field: {key}")
+    mode_type = str(agent_mode.get("type") or "")
+    if not mode_type:
+        state.error(f"{relative_manifest} agent_mode.type must be a non-empty string")
+    elif mode_type not in AGENT_MODE_TYPES:
+        state.error(f"{relative_manifest} agent_mode.type has unsupported value: {mode_type}")
+    max_steps = agent_mode.get("max_steps")
+    if not isinstance(max_steps, int) or max_steps <= 0 or max_steps > 20:
+        state.error(f"{relative_manifest} agent_mode.max_steps must be an integer between 1 and 20")
+    max_specialists = agent_mode.get("max_specialists")
+    if max_specialists is not None and (not isinstance(max_specialists, int) or max_specialists <= 0 or max_specialists > 20):
+        state.error(f"{relative_manifest} agent_mode.max_specialists must be an integer between 1 and 20")
+    max_llm_calls = agent_mode.get("max_llm_calls")
+    if max_llm_calls is not None and (not isinstance(max_llm_calls, int) or max_llm_calls < 0 or max_llm_calls > 20):
+        state.error(f"{relative_manifest} agent_mode.max_llm_calls must be an integer between 0 and 20")
+    timeout = agent_mode.get("timeout_seconds")
+    if timeout is not None and (not isinstance(timeout, int) or timeout <= 0):
+        state.error(f"{relative_manifest} agent_mode.timeout_seconds must be a positive integer")
+    for boolean_field in ("can_call_capabilities", "can_request_user_input", "external_writes"):
+        if boolean_field in agent_mode and not isinstance(agent_mode.get(boolean_field), bool):
+            state.error(f"{relative_manifest} agent_mode.{boolean_field} must be boolean")
+    llm_value = agent_mode.get("can_call_llm")
+    if llm_value not in AGENT_MODE_LLM_VALUES:
+        state.error(f"{relative_manifest} agent_mode.can_call_llm must be false, optional, or required")
+    for list_field in ("allowed_capabilities", "stop_conditions"):
+        values = agent_mode.get(list_field)
+        if values is None:
+            continue
+        if not isinstance(values, list):
+            state.error(f"{relative_manifest} agent_mode.{list_field} must be a list")
+            continue
+        for item in values:
+            if not isinstance(item, str) or not item.strip():
+                state.error(f"{relative_manifest} agent_mode.{list_field} entries must be non-empty strings")
+    if agent_mode.get("external_writes") is True and not agent_write_policy_requires_confirmation(write_policy):
+        state.error(f"{relative_manifest} agent_mode.external_writes=true requires confirm, delegated, or blocked_by_default write_policy")
+
+
+def agent_write_policy_requires_confirmation(write_policy: Any) -> bool:
+    if isinstance(write_policy, dict):
+        values = [normalize_write_policy_value(policy) for policy in write_policy.values()]
+    else:
+        values = [normalize_write_policy_value(write_policy)]
+    return any(value in {"confirm", "delegated", "blocked_by_default"} for value in values)
+
+
+def normalize_write_policy_value(value: Any) -> str:
+    raw = str(value or "").strip()
+    return LEGACY_WRITE_POLICY_ALIASES.get(raw, raw)
+
+
 def validate_capability_provider_requirements(state: ValidationState, manifest_path: Path, requires: Any) -> None:
     if not requires:
         return
@@ -576,6 +837,57 @@ def validate_status(state: ValidationState, path: Path, status: Any) -> None:
         state.error(f"{rel(state, path)} has unsupported status: {status}")
 
 
+def validate_agent_write_policy(state: ValidationState, path: Path, write_policy: Any) -> None:
+    if write_policy is None:
+        return
+    if isinstance(write_policy, dict):
+        for name, value in sorted(write_policy.items()):
+            validate_write_policy_value(state, path, value, field=f"write_policy.{name}")
+        return
+    validate_write_policy_value(state, path, write_policy)
+
+
+def validate_write_policy_value(
+    state: ValidationState,
+    path: Path,
+    write_policy: Any,
+    *,
+    field: str = "write_policy",
+) -> None:
+    if write_policy is None:
+        return
+    policy = str(write_policy)
+    if policy in CANONICAL_WRITE_POLICIES:
+        return
+    if policy in LEGACY_WRITE_POLICY_ALIASES:
+        state.warn(
+            f"{rel(state, path)} uses legacy {field}: {policy!r}; use {LEGACY_WRITE_POLICY_ALIASES[policy]!r}"
+        )
+        return
+    state.error(f"{rel(state, path)} has unsupported {field}: {policy!r}")
+
+
+def validate_routing(state: ValidationState, path: Path, routing: Any) -> None:
+    if routing is None:
+        return
+    relative = rel(state, path)
+    if not isinstance(routing, dict):
+        state.error(f"{relative} routing must be a mapping")
+        return
+    for field in ("aliases", "anchors", "domains", "entities", "intents", "keywords", "examples"):
+        value = routing.get(field)
+        if value is None:
+            continue
+        if not isinstance(value, list):
+            state.error(f"{relative} routing.{field} must be a list")
+            continue
+        for item in value:
+            if not isinstance(item, str) or not item.strip():
+                state.error(f"{relative} routing.{field} entries must be non-empty strings")
+    if "priority" in routing and not isinstance(routing.get("priority"), int):
+        state.error(f"{relative} routing.priority must be an integer")
+
+
 def validate_relative_refs(state: ValidationState, base: Path, refs: Any, field: str) -> None:
     if refs is None:
         return

package/runtime/vendor/skills/napkin/napkin.md

@@ -25,23 +25,29 @@
    Do instead: intercept `--source` only for capabilities that explicitly support Agent DevKit source registry injection; otherwise leave it for the runner domain contract.
 
 ## Domain Behavior Guardrails
-1. **[2026-06-28] Agentes devem ser agnosticos de cliente/projeto**
+1. **[2026-06-28] `write_policy` usa vocabulário canônico**
+   Do instead: usar apenas `read_only`, `dry_run`, `output_only`, `local_write`, `local_config_write`, `confirm`, `blocked_by_default` ou `delegated`; aliases antigos devem ser aceitos só em runtime e rejeitados como warning pelo validator.
+2. **[2026-06-28] Exemplos de roteamento nao sao evidencia por alias**
+   Do instead: ao usar `routing.examples`, comparar tokens reais ou frase exata; anchors/intents carregam aliases, exemplos nao devem promover matches genericos como apenas "analise".
+3. **[2026-06-28] Agentes devem ser agnosticos de cliente/projeto**
    Do instead: mover nomes de produto, cliente, URLs, paths locais, regras de elegibilidade e campos XML especificos para provider/config/env antes de versionar o agente.
-2. **[2026-06-28] Sessao ativa nao deve vazar contexto entre projetos**
+4. **[2026-06-28] Sessao ativa nao deve vazar contexto entre projetos**
    Do instead: ao persistir contexto de conversa, reutilizar automaticamente apenas sessoes do mesmo projeto; para outro projeto, criar nova sessao ou exigir retomada explicita.
-3. **[2026-06-28] Roteamento de PR deve usar tokens reais**
+5. **[2026-06-28] Roteamento de PR deve usar tokens reais**
    Do instead: detectar `pr`, `prs` ou `pull request` como tokens/expressao, nao substring ampla que captura palavras como `problema`.
-4. **[2026-06-28] Tasks com escrita externa devem bloquear por padrao**
+6. **[2026-06-28] Tasks com escrita externa devem bloquear por padrao**
    Do instead: permitir `dry-run`, mas bloquear execucao real quando `action.external_writes=true` sem permissao explicita de escrita externa.
-5. **[2026-06-20] Azure card descriptions may include sensitive production log data**
+7. **[2026-06-20] Azure card descriptions may include sensitive production log data**
    Do instead: retrieve the complete card for validation, but summarize PII-heavy log payloads in user-facing responses unless raw content is explicitly required.
-6. **[2026-06-21] N1 restrictive-base uses a scoped SQL Server override**
+8. **[2026-06-21] N1 restrictive-base uses a scoped SQL Server override**
    Do instead: when the N1 agent checks the restrictive base, prefer `DB_RESTRICTIVE_CONN_STRING` only in the subprocess environment for `sqlserver-data-analyzer`, without changing the global SQL Server analyzer default.
 
 ## User Directives
-1. **[2026-06-22] Implement agentic specs individually**
+1. **[2026-06-28] Rodar testes focados durante patches**
+   Do instead: para melhorias intermediarias, executar apenas testes necessarios para validar o patch; reservar suite completa para o fechamento do conjunto de melhorias.
+2. **[2026-06-22] Implement agentic specs individually**
    Do instead: process one `docs/agentic/*_plan.md` spec at a time with agent-specific analysis, tests, implementation, and review; do not use broad multi-agent waves or mechanical generation.
-2. **[2026-06-22] Use Agent DevKit agents for work**
+3. **[2026-06-22] Use Agent DevKit agents for work**
    Do instead: route every current and future activity through the relevant Agent DevKit agent/capability before doing direct ad-hoc work.
-3. **[2026-06-20] Keep generated docs out of final project versioning**
+4. **[2026-06-20] Keep generated docs out of final project versioning**
    Do instead: treat `docs/` as local development/generated artifact space and keep it ignored.