agent-devkit 0.1.6 → 0.3.0

package/runtime/scripts/release-gate.py

@@ -6,19 +6,25 @@ from __future__ import annotations
 import argparse
 import json
 import os
+import shutil
 import subprocess
 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"
+RELEASE_GATE_HOME = ROOT / "tmp" / "release-gate-home"
+COMMAND_TIMEOUT_SECONDS = 900
 
 
 def main() -> int:
@@ -36,16 +42,19 @@ def main() -> int:
 
 
 def run_gate(*, quick: bool = False) -> dict[str, Any]:
+    prepare_release_gate_home()
     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.1 runtime evals", [sys.executable, str(AGENT), "eval", "run", "all", "--json"], validate_v021_evals),
         skill_validation_check(),
     ]
     if quick:
         checks.append(skipped_check("full unittest suite", "skipped by --quick"))
     else:
-        checks.append(check_command("full unittest suite", unittest_command(), validate_unittest))
+        checks.append(check_command("full unittest suite", unittest_command(), validate_unittest, use_release_home=False))
 
     errors = [check["message"] for check in checks if check["status"] == "failed"]
     return {
@@ -57,6 +66,11 @@ def run_gate(*, quick: bool = False) -> dict[str, Any]:
     }
 
 
+def prepare_release_gate_home() -> None:
+    shutil.rmtree(RELEASE_GATE_HOME, ignore_errors=True)
+    RELEASE_GATE_HOME.mkdir(parents=True, exist_ok=True)
+
+
 def skill_validation_check() -> dict[str, Any]:
     if not SKILL_VALIDATOR.exists():
         return skipped_check("claude skill validation", f"skill validator not found at {SKILL_VALIDATOR}")
@@ -71,21 +85,29 @@ 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 ""
     return (0 if first == "tests" else 1, str(relative))
 
 
-def check_json(name: str, command: list[str], validator) -> dict[str, Any]:
-    result = run(command)
+def check_json(name: str, command: list[str], validator, *, use_release_home: bool = True) -> dict[str, Any]:
+    result = run(command, use_release_home=use_release_home)
     if result.returncode != 0:
         return failed_check(name, f"returncode {result.returncode}", result)
     try:
@@ -100,8 +122,8 @@ def check_json(name: str, command: list[str], validator) -> dict[str, Any]:
     return check
 
 
-def check_command(name: str, command: list[str], validator) -> dict[str, Any]:
-    result = run(command)
+def check_command(name: str, command: list[str], validator, *, use_release_home: bool = True) -> dict[str, Any]:
+    result = run(command, use_release_home=use_release_home)
     if result.returncode != 0:
         return failed_check(name, f"returncode {result.returncode}", result)
     message = validator(result)
@@ -110,18 +132,30 @@ def check_command(name: str, command: list[str], validator) -> dict[str, Any]:
     return ok_check(name, result)
 
 
-def run(command: list[str]) -> subprocess.CompletedProcess[str]:
+def run(command: list[str], *, use_release_home: bool = True) -> subprocess.CompletedProcess[str]:
+    env = command_env(use_release_home=use_release_home)
     return subprocess.run(
         command,
         cwd=ROOT,
         check=False,
+        env=env,
         text=True,
         stdout=subprocess.PIPE,
         stderr=subprocess.PIPE,
-        timeout=360,
+        timeout=COMMAND_TIMEOUT_SECONDS,
     )
 
 
+def command_env(*, use_release_home: bool) -> dict[str, str]:
+    env = os.environ.copy()
+    if use_release_home:
+        env["AGENT_DEVKIT_HOME"] = str(RELEASE_GATE_HOME)
+        return env
+    for name in ("AGENT_DEVKIT_HOME", "AI_DEVKIT_CONFIG_HOME", "AIKIT_CONFIG_HOME"):
+        env.pop(name, None)
+    return env
+
+
 def validate_agent_version(result: subprocess.CompletedProcess[str]) -> str | None:
     if not result.stdout.startswith("agent "):
         return "agent --version did not report the agent command"
@@ -141,6 +175,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 +281,37 @@ def validate_mvp_readiness(payload: dict[str, Any]) -> str | None:
     return None
 
 
+def validate_v021_evals(payload: dict[str, Any]) -> str | None:
+    if payload.get("kind") != "eval-run" or payload.get("suite") != "all":
+        return "v0.2.1 eval command returned an unexpected payload"
+    if payload.get("status") != "passed":
+        return "v0.2.1 runtime evals did not pass"
+    checks = payload.get("checks") or []
+    required = {
+        "routing",
+        "catalog",
+        "wizard",
+        "source_config",
+        "identity_enforcement",
+        "review_gate",
+        "model_router",
+        "agentic_plan",
+        "mcp",
+        "workflow_contract",
+        "extension_contract",
+        "contribution_contract",
+        "team_contract",
+        "knowledge_contract",
+        "secret_refs",
+        "prompt-injection",
+    }
+    suites = {item.get("suite") for item in checks if isinstance(item, dict)}
+    missing = sorted(required - suites)
+    if missing:
+        return f"v0.2.1 runtime evals missing suites: {', '.join(missing)}"
+    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 +345,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 +365,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