agent-devkit 0.1.5 → 0.2.0

package/runtime/cli/aikit/doctor_runtime.py

@@ -0,0 +1,79 @@
+"""Doctor and diagnostics payload builder for the CLI."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Any
+
+from cli.aikit.capability_runtime import list_agents, list_all_capabilities
+from cli.aikit.diagnostics import build_diagnostics
+from cli.aikit.lock import lock_status
+from cli.aikit.runtime_paths import AGENTS_DIR, ROOT
+
+
+def doctor(project: str | None = None, home: str | None = None, scope: str = "auto") -> dict[str, Any]:
+    agents = list_agents()
+    capabilities = list_all_capabilities()
+    declared_runners = sum(1 for item in capabilities if item.get("has_runner"))
+    workflows = sum(1 for item in capabilities if item.get("has_workflow"))
+    decision_rules = sum(1 for item in capabilities if item.get("has_decision_rules"))
+    validator = ROOT / "scripts" / "validate-repo.py"
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    if not ROOT.exists():
+        errors.append(f"root not found: {ROOT}")
+    if not AGENTS_DIR.is_dir():
+        errors.append(f"agents directory not found: {AGENTS_DIR}")
+    if not validator.exists():
+        warnings.append("scripts/validate-repo.py not found")
+    project_path = doctor_project_path(project, scope)
+    home_path = Path(home) if home else None
+    locks = lock_status(project_path, home_path)
+    if project and locks["status"] == "diverged":
+        warnings.append("lock divergence between global runtime.lock and project ai-devkit.lock")
+    checks = {
+        "root_exists": ROOT.exists(),
+        "agents_dir_exists": AGENTS_DIR.is_dir(),
+        "validator_exists": validator.exists(),
+        "agent_command_exists": (ROOT / "agent").exists(),
+        "aikit_command_exists": (ROOT / "aikit").exists(),
+        "ai_devkit_command_exists": (ROOT / "ai-devkit").exists(),
+        "agent_on_path": shutil.which("agent") is not None,
+    }
+    diagnostics = build_diagnostics(
+        ROOT,
+        project=project_path,
+        home=home_path,
+        runtime_checks=checks,
+        runtime_status="ok" if not errors else "error",
+        locks=locks,
+    )
+
+    return {
+        "kind": "doctor",
+        "status": "ok" if not errors else "error",
+        "scope": scope,
+        "root": str(ROOT),
+        "summary": {
+            "agents": len(agents),
+            "capabilities": len(capabilities),
+            "declared_runners": declared_runners,
+            "workflows": workflows,
+            "decision_rules": decision_rules,
+        },
+        "checks": checks,
+        "errors": errors,
+        "warnings": warnings,
+        "locks": locks,
+        "diagnostics": diagnostics,
+    }
+
+
+def doctor_project_path(project: str | None, scope: str) -> Path | None:
+    if project:
+        return Path(project)
+    if scope == "project":
+        return Path.cwd()
+    return None

package/runtime/cli/aikit/errors.py

@@ -0,0 +1,7 @@
+"""Shared user-facing CLI errors."""
+
+from __future__ import annotations
+
+
+class DevKitError(RuntimeError):
+    """Raised for user-facing CLI errors."""

package/runtime/cli/aikit/eval.py

@@ -0,0 +1,158 @@
+"""Deterministic eval suites for Agent DevKit runtime contracts."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable
+
+from cli.aikit.catalog import catalog_search
+from cli.aikit.mcp_manifest import mcp_tools
+from cli.aikit.prompt_injection import prompt_injection_eval_fixture
+from cli.aikit.router_explain import explain_route
+from cli.aikit.runtime_paths import ROOT
+
+
+EVAL_SCHEMA_VERSION = "agent-devkit.eval/v1"
+SUITES = (
+    "routing",
+    "catalog",
+    "write_policy",
+    "source_readiness",
+    "mcp",
+    "mcp_contract",
+    "prompt-injection",
+    "prompt_injection",
+    "mini_brain_limits",
+    "generated_agent_contract",
+)
+
+
+def eval_list() -> dict[str, Any]:
+    return {
+        "kind": "eval-suites",
+        "schema_version": EVAL_SCHEMA_VERSION,
+        "status": "ok",
+        "suites": [{"id": display_suite_id(suite_id), "deterministic": True} for suite_id in canonical_suite_ids()],
+    }
+
+
+def eval_run(suite: str, root: Path | None = None) -> dict[str, Any]:
+    root = root or ROOT
+    suite = normalize_suite_id(suite)
+    if suite == "all":
+        runs = [eval_run(item, root) for item in canonical_suite_ids()]
+        status = "passed" if all(item["status"] == "passed" for item in runs) else "failed"
+        return run_payload("all", status, runs)
+    handlers: dict[str, Callable[[Path], list[dict[str, Any]]]] = {
+        "routing": eval_routing,
+        "catalog": eval_catalog,
+        "write_policy": eval_write_policy,
+        "source_readiness": eval_source_readiness,
+        "mcp_contract": eval_mcp_contract,
+        "prompt_injection": eval_prompt_injection,
+        "mini_brain_limits": eval_mini_brain_limits,
+        "generated_agent_contract": eval_generated_agent_contract,
+    }
+    handler = handlers.get(suite)
+    if not handler:
+        raise ValueError(f"unknown eval suite: {suite}")
+    checks = handler(root)
+    status = "passed" if all(item.get("status") == "passed" for item in checks) else "failed"
+    return run_payload(display_suite_id(suite), status, checks)
+
+
+def eval_report() -> dict[str, Any]:
+    return {
+        "kind": "eval-report",
+        "schema_version": EVAL_SCHEMA_VERSION,
+        "status": "ok",
+        "message": "Persistent eval run reports are not enabled in the MVP.",
+        "runs": [],
+    }
+
+
+def eval_routing(root: Path) -> list[dict[str, Any]]:
+    payload = explain_route("revise as prs que recebi hoje", root)
+    return [
+        {
+            "id": "routing.pr-review",
+            "status": "passed" if payload["candidates"] else "failed",
+            "evidence": {"decision": payload["decision"], "candidates": len(payload["candidates"])},
+        }
+    ]
+
+
+def eval_catalog(root: Path) -> list[dict[str, Any]]:
+    payload = catalog_search("pr", root)
+    return [{"id": "catalog.search-pr", "status": "passed" if payload["items"] else "failed", "count": payload["count"]}]
+
+
+def eval_write_policy(_root: Path) -> list[dict[str, Any]]:
+    return [{"id": "write-policy.normalized", "status": "passed"}]
+
+
+def eval_source_readiness(_root: Path) -> list[dict[str, Any]]:
+    return [{"id": "source-readiness.no-external-required", "status": "passed"}]
+
+
+def eval_mcp_contract(_root: Path) -> list[dict[str, Any]]:
+    names = {tool["name"] for tool in mcp_tools()}
+    required = {"agent_devkit_catalog_search", "agent_devkit_route_explain", "agent_devkit_roadmap"}
+    return [{"id": "mcp.v2-tools", "status": "passed" if required <= names else "failed", "required": sorted(required)}]
+
+
+def eval_prompt_injection(_root: Path) -> list[dict[str, Any]]:
+    return [prompt_injection_eval_fixture()]
+
+
+def eval_mini_brain_limits(_root: Path) -> list[dict[str, Any]]:
+    from cli.aikit.mini_brain import FORBIDDEN_TASKS
+
+    return [{"id": "mini-brain.forbidden-high-risk", "status": "passed" if "external_write_decision" in FORBIDDEN_TASKS else "failed"}]
+
+
+def eval_generated_agent_contract(_root: Path) -> list[dict[str, Any]]:
+    return [{"id": "generated-agent.contract-placeholder", "status": "passed"}]
+
+
+def run_payload(suite: str, status: str, checks: list[dict[str, Any]]) -> dict[str, Any]:
+    return {
+        "kind": "eval-run",
+        "schema_version": EVAL_SCHEMA_VERSION,
+        "suite": suite,
+        "status": status,
+        "ok": status == "passed",
+        "started_at": datetime.now(timezone.utc).isoformat(),
+        "finished_at": datetime.now(timezone.utc).isoformat(),
+        "checks": json.loads(json.dumps(checks, ensure_ascii=False)),
+    }
+
+
+def canonical_suite_ids() -> list[str]:
+    return [
+        "routing",
+        "catalog",
+        "write_policy",
+        "source_readiness",
+        "mcp_contract",
+        "prompt_injection",
+        "mini_brain_limits",
+        "generated_agent_contract",
+    ]
+
+
+def normalize_suite_id(value: str) -> str:
+    normalized = (value or "").strip().replace("-", "_")
+    if normalized == "mcp":
+        return "mcp_contract"
+    return normalized
+
+
+def display_suite_id(value: str) -> str:
+    if value == "prompt_injection":
+        return "prompt-injection"
+    if value == "mcp_contract":
+        return "mcp"
+    return value

package/runtime/cli/aikit/execution_reviewer.py

@@ -0,0 +1,195 @@
+"""Runtime execution for the execution-reviewer agent."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cli.aikit.llm import BACKENDS, candidate_backend_ids, doctor_backend, invoke_agent_prompt, load_config
+from cli.aikit.review_gate import mark_reviewed
+
+
+PREFERRED_REVIEW_BACKENDS = ("claude-code", "codex-cli")
+REVIEW_OK_MARKER = "REVIEW OK"
+REVIEW_BLOCKED_MARKER = "REVIEW BLOCKED"
+
+
+def enforce_execution_review(
+    *,
+    prompt: str,
+    result: dict[str, Any],
+    review_gate: dict[str, Any],
+    execution_plan: dict[str, Any] | None = None,
+    producer_backend: str | None = None,
+) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
+    """Run a second concrete review when required and apply the gate outcome."""
+    if not review_gate.get("required"):
+        review_result = {
+            "kind": "execution-review",
+            "agent_id": "execution-reviewer",
+            "capability_id": "review-final-output",
+            "status": "not-required",
+            "ok": True,
+        }
+        return result, review_gate, review_result
+
+    response = str(result.get("response") or result.get("message") or "")
+    review_backend = select_review_backend(producer_backend=producer_backend, preferred=review_gate.get("preferred_reviewers") or [])
+    if not review_backend:
+        review_result = needs_review("No configured independent reviewer backend is available.", producer_backend=producer_backend)
+        return block_for_review(result, review_gate, review_result)
+
+    review_prompt = build_review_prompt(prompt=prompt, response=response, review_gate=review_gate, execution_plan=execution_plan)
+    invoked = invoke_agent_prompt(
+        review_prompt,
+        review_backend,
+        public_name="Execution Reviewer",
+        allow_fallback=False,
+    )
+    decision = parse_review_decision(str(invoked.get("response") or ""))
+    review_result = {
+        "kind": "execution-review",
+        "agent_id": "execution-reviewer",
+        "capability_id": "review-final-output",
+        "capability": "execution-reviewer.review-final-output",
+        "status": review_status(invoked=invoked, decision=decision),
+        "ok": bool(invoked.get("ok")) and decision == "approved",
+        "llm_backend": invoked.get("llm_backend"),
+        "producer_backend": producer_backend,
+        "decision": decision,
+        "response": invoked.get("response"),
+        "message": invoked.get("message"),
+        "attempts": invoked.get("llm_backend_attempts"),
+    }
+    if not invoked.get("ok"):
+        return block_for_review(result, review_gate, review_result)
+    if decision == "blocked":
+        review_result["message"] = "Execution reviewer blocked the proposed final output."
+        return block_for_review(result, review_gate, review_result)
+    if decision != "approved":
+        review_result["message"] = "Execution reviewer did not return REVIEW OK."
+        return block_for_review(result, review_gate, review_result)
+    reviewed_gate = mark_reviewed(review_gate, reviewer=str(invoked.get("llm_backend") or review_backend), notes=str(invoked.get("response") or "Reviewed."))
+    return result, reviewed_gate, review_result
+
+
+def select_review_backend(*, producer_backend: str | None, preferred: list[str]) -> str | None:
+    config = load_config()
+    candidates = candidate_backend_ids(config=config, allow_fallback=True)
+    preferred_order = [item for item in list(preferred or []) + list(PREFERRED_REVIEW_BACKENDS) if item in BACKENDS]
+    ordered = [item for item in preferred_order if item in candidates]
+    ordered.extend(item for item in candidates if item not in ordered and item != "ollama")
+    for backend_id in ordered:
+        if backend_id == producer_backend:
+            continue
+        backend = doctor_backend(BACKENDS[backend_id], config)
+        if backend.get("status") == "ok":
+            return backend_id
+    return None
+
+
+def build_review_prompt(
+    *,
+    prompt: str,
+    response: str,
+    review_gate: dict[str, Any],
+    execution_plan: dict[str, Any] | None,
+) -> str:
+    plan_summary = {}
+    if isinstance(execution_plan, dict):
+        plan_summary = {
+            "status": execution_plan.get("status"),
+            "coordinator": (execution_plan.get("coordinator_agent") or {}).get("id") if isinstance(execution_plan.get("coordinator_agent"), dict) else None,
+            "specialist_tasks": [
+                {
+                    "task_id": task.get("task_id") or task.get("id"),
+                    "agent_id": task.get("agent_id"),
+                    "capability_id": task.get("capability_id"),
+                    "role": task.get("role"),
+                    "depends_on": list(task.get("depends_on") or []),
+                    "status": task.get("status"),
+                }
+                for task in execution_plan.get("specialist_tasks") or []
+                if isinstance(task, dict)
+            ],
+            "collaboration_enabled": execution_plan.get("collaboration_enabled") is True,
+            "shared_context_counts": {
+                key: len((execution_plan.get("shared_context") or {}).get(key) or [])
+                for key in (
+                    "facts",
+                    "inferences",
+                    "artifacts",
+                    "blockers",
+                    "decisions",
+                    "risks",
+                    "questions",
+                    "handoffs",
+                    "conflicts",
+                    "human_escalations",
+                )
+            }
+            if isinstance(execution_plan.get("shared_context"), dict)
+            else None,
+        }
+    return "\n".join(
+        [
+            "Revise a entrega final do Agent DevKit antes da conclusao.",
+            "Verifique aderencia ao pedido, riscos, lacunas, evidencias, uso indevido de credenciais e necessidade de bloquear.",
+            "Responda com uma decisao objetiva: REVIEW OK ou REVIEW BLOCKED, seguida de justificativa curta.",
+            "",
+            f"Motivo do review gate: {review_gate.get('reason')}",
+            f"Prompt original: {prompt}",
+            f"Resumo do plano: {plan_summary}",
+            "",
+            "Resposta final proposta:",
+            response,
+        ]
+    )
+
+
+def parse_review_decision(response: str) -> str:
+    upper = response.upper()
+    if REVIEW_BLOCKED_MARKER in upper:
+        return "blocked"
+    if REVIEW_OK_MARKER in upper:
+        return "approved"
+    return "unstructured"
+
+
+def review_status(*, invoked: dict[str, Any], decision: str) -> str:
+    if not invoked.get("ok"):
+        return str(invoked.get("status", "failed"))
+    if decision == "blocked":
+        return "blocked"
+    if decision != "approved":
+        return "needs-review"
+    return "ok"
+
+
+def needs_review(message: str, *, producer_backend: str | None) -> dict[str, Any]:
+    return {
+        "kind": "execution-review",
+        "agent_id": "execution-reviewer",
+        "capability_id": "review-final-output",
+        "capability": "execution-reviewer.review-final-output",
+        "status": "needs-review",
+        "ok": False,
+        "producer_backend": producer_backend,
+        "message": message,
+    }
+
+
+def block_for_review(
+    result: dict[str, Any],
+    review_gate: dict[str, Any],
+    review_result: dict[str, Any],
+) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
+    blocked = dict(result)
+    blocked["status"] = "needs-review"
+    blocked["ok"] = False
+    blocked["exit_code"] = 2
+    blocked["message"] = review_result.get("message") or "Execution requires review before completion."
+    gate = dict(review_gate)
+    gate["status"] = "needs-review"
+    gate["reviewer"] = None
+    gate["notes"] = review_result.get("message")
+    return blocked, gate, review_result

package/runtime/cli/aikit/extensions.py

@@ -0,0 +1,140 @@
+"""Local extension registry for Agent DevKit MVP."""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+from typing import Any
+
+from cli.aikit.app_home import ensure_app_home, app_home
+from cli.aikit.errors import DevKitError
+
+
+EXTENSIONS_SCHEMA_VERSION = "agent-devkit.local-extensions/v1"
+
+
+def local_extensions_list() -> dict[str, Any]:
+    data = load_extensions()
+    return {
+        "kind": "local-extensions",
+        "schema_version": EXTENSIONS_SCHEMA_VERSION,
+        "status": "ok",
+        "items": public_extensions(data["extensions"]),
+        "scopes": extension_scopes(),
+    }
+
+
+def local_extension_add(path: str | None) -> dict[str, Any]:
+    if not path:
+        raise DevKitError("local add requires --path")
+    source = Path(path).expanduser().resolve()
+    if not source.exists():
+        raise DevKitError(f"local extension path not found: {source}")
+    data = load_extensions()
+    extension_id = source.name
+    if any(item["id"] == extension_id for item in data["extensions"]):
+        raise DevKitError(f"local extension already registered: {extension_id}")
+    item = {"id": extension_id, "path": str(source), "enabled": True, "scope": "user"}
+    data["extensions"].append(item)
+    save_extensions(data)
+    return {"kind": "local-extension", "status": "added", "item": item}
+
+
+def local_extension_enable(extension_id: str, enabled: bool) -> dict[str, Any]:
+    data = load_extensions()
+    item = find_extension(data, extension_id)
+    item["enabled"] = enabled
+    save_extensions(data)
+    return {"kind": "local-extension", "status": "enabled" if enabled else "disabled", "item": item}
+
+
+def local_extension_remove(extension_id: str) -> dict[str, Any]:
+    data = load_extensions()
+    before = len(data["extensions"])
+    data["extensions"] = [item for item in data["extensions"] if item.get("id") != extension_id]
+    save_extensions(data)
+    return {"kind": "local-extension-remove", "status": "removed" if len(data["extensions"]) < before else "not-found"}
+
+
+def local_extension_validate(extension_id: str) -> dict[str, Any]:
+    data = load_extensions()
+    item = find_extension(data, extension_id)
+    path = Path(str(item.get("path") or ""))
+    checks = [
+        {"id": "path-exists", "status": "passed" if path.exists() else "failed"},
+        {"id": "has-known-content", "status": "passed" if has_known_extension_content(path) else "failed"},
+    ]
+    return {
+        "kind": "local-extension-validation",
+        "status": "passed" if all(check["status"] == "passed" for check in checks) else "failed",
+        "item": item,
+        "checks": checks,
+    }
+
+
+def extension_scopes() -> dict[str, str]:
+    return {"user": str(app_home() / "local"), "project": str(Path.cwd() / ".agent-devkit")}
+
+
+def extensions_path() -> Path:
+    ensure_app_home()
+    path = app_home() / "local" / "extensions.json"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def load_extensions() -> dict[str, Any]:
+    path = extensions_path()
+    if not path.exists():
+        return {"version": 1, "extensions": []}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return {"version": 1, "extensions": []}
+    if not isinstance(data, dict) or not isinstance(data.get("extensions"), list):
+        return {"version": 1, "extensions": []}
+    return {"version": 1, "extensions": [item for item in data["extensions"] if isinstance(item, dict)]}
+
+
+def save_extensions(data: dict[str, Any]) -> Path:
+    path = extensions_path()
+    path.write_text(json.dumps(data, ensure_ascii=False, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return path
+
+
+def public_extensions(items: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [
+        {
+            "id": item.get("id"),
+            "path": item.get("path"),
+            "enabled": item.get("enabled") is True,
+            "scope": item.get("scope") or "user",
+        }
+        for item in items
+    ]
+
+
+def find_extension(data: dict[str, Any], extension_id: str) -> dict[str, Any]:
+    for item in data["extensions"]:
+        if item.get("id") == extension_id:
+            return item
+    raise DevKitError(f"local extension not found: {extension_id}")
+
+
+def has_known_extension_content(path: Path) -> bool:
+    if not path.exists():
+        return False
+    if path.is_file():
+        return path.suffix in {".md", ".yaml", ".yml", ".json", ".py", ".sh"}
+    return any((path / name).exists() for name in ("agent.yaml", "capability.yaml", "workflow.yaml", "skill.md", "SKILL.md")) or any(
+        path.glob("**/agent.yaml")
+    )
+
+
+def copy_extension_fixture(source: Path, destination: Path) -> None:
+    if source.is_dir():
+        shutil.copytree(source, destination)
+    else:
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(source, destination)

package/runtime/cli/aikit/fallback.py

@@ -130,6 +130,7 @@ def provider_detail(requirement: dict[str, Any], status_item: dict[str, Any]) ->
         "status": status_item.get("status") or "missing",
         "configured": bool(status_item.get("configured")),
         "purpose": requirement.get("purpose"),
+        "inferred": bool(requirement.get("inferred")),
     }
 
 

package/runtime/cli/aikit/github_pr.py

@@ -188,6 +188,29 @@ def pr_create_automation(*, task_id: str | None = None, title: str | None = None
     return task
 
 
+def summarize_pr_list(payload: dict[str, Any]) -> str:
+    if payload.get("status") != "ok":
+        return str(payload.get("message") or "Nao foi possivel listar PRs.")
+    items = payload.get("items") or []
+    if not items:
+        return "Nenhuma PR aguardando sua revisao foi encontrada."
+    lines = []
+    for item in items:
+        number = item.get("number")
+        title = item.get("title") or "-"
+        url = item.get("url") or ""
+        lines.append(f"- #{number} {title} {url}".strip())
+    return "\n".join(lines)
+
+
+def planned_pr_commands(action: str, *, pr_ref: str | None = None) -> list[list[str]]:
+    if action == "list-review-requests":
+        return [["gh", "pr", "list", "--review-requested", "@me", "--json", "number,title,url,author,headRefName,baseRefName,isDraft"]]
+    if action == "inspect":
+        return [["gh", "pr", "view", str(pr_ref), "--json", "number,title,url,author,body,headRefName,baseRefName,state,isDraft,reviewDecision,mergeable"]]
+    return []
+
+
 def gh_check() -> dict[str, Any]:
     binary = shutil.which("gh")
     if not binary:

package/runtime/cli/aikit/guardrails.py

@@ -4,6 +4,13 @@ from __future__ import annotations
 
 from typing import Any
 
+from cli.aikit.write_policy import (
+    is_blocked_by_default,
+    is_known_write_policy,
+    normalize_write_policy,
+    requires_runtime_confirmation,
+)
+
 
 RUNTIME_CONFIRM_FLAG = "--confirm-execute"
 RUNTIME_DANGEROUS_FLAG = "--allow-dangerous"
@@ -13,13 +20,6 @@ EXECUTE_INTENT_FLAGS = {
     "--yes-confirm",
     "--yes-save",
 }
-DANGEROUS_POLICIES = {"blocked_by_default"}
-WRITE_POLICIES_REQUIRING_CONFIRMATION = {
-    "confirm",
-    "ask_before_write",
-    "template_version_write",
-    "create_new_version",
-}
 
 
 def evaluate_execution_guardrails(
@@ -29,12 +29,27 @@ def evaluate_execution_guardrails(
     """Return sanitized args and an optional blocked guardrail result."""
 
     sanitized_args = strip_runtime_flags(capability_args)
-    write_policy = str(capability.get("write_policy") or "")
+    raw_write_policy = capability.get("write_policy")
+    write_policy = normalize_write_policy(raw_write_policy or "")
     execute_requested = any(flag in capability_args for flag in EXECUTE_INTENT_FLAGS)
     confirmed = RUNTIME_CONFIRM_FLAG in capability_args
     dangerous_allowed = RUNTIME_DANGEROUS_FLAG in capability_args
 
-    if execute_requested and write_policy in DANGEROUS_POLICIES and not dangerous_allowed:
+    if raw_write_policy and not is_known_write_policy(raw_write_policy):
+        return {
+            "ready": False,
+            "args": sanitized_args,
+            "reason": "unknown_write_policy",
+            "write_policy": write_policy,
+            "risks": [
+                "Capability declares an unsupported write policy, so runtime safety semantics are ambiguous.",
+            ],
+            "next_steps": [
+                "Fix the capability manifest to use a canonical write_policy before requesting execution.",
+            ],
+        }
+
+    if execute_requested and is_blocked_by_default(write_policy) and not dangerous_allowed:
         return {
             "ready": False,
             "args": sanitized_args,
@@ -48,7 +63,7 @@ def evaluate_execution_guardrails(
             ],
         }
 
-    if execute_requested and write_policy in WRITE_POLICIES_REQUIRING_CONFIRMATION and not confirmed:
+    if execute_requested and requires_runtime_confirmation(write_policy) and not confirmed:
         return {
             "ready": False,
             "args": sanitized_args,