wicked-garden 12.27.0

package/scripts/qe/discover_scenarios.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+"""Discover wicked-scenarios plugin and list available E2E scenarios.
+
+Cross-plugin discovery utility that finds wicked-scenarios if installed,
+parses scenario metadata, and returns structured JSON.
+
+Usage:
+    python3 discover_scenarios.py                    # All scenarios
+    python3 discover_scenarios.py --category api     # Filter by category
+    python3 discover_scenarios.py --available-only   # Only runnable scenarios
+    python3 discover_scenarios.py --check-tools      # Include tool availability
+"""
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _parse_version(v: str) -> tuple:
+    """Parse semver string to comparable tuple."""
+    match = re.match(r"(\d+)\.(\d+)\.(\d+)", v)
+    if match:
+        return tuple(int(x) for x in match.groups())
+    return (0, 0, 0)
+
+
+def discover_plugin(plugin_name: str) -> "Path | None":
+    """Find a plugin's root directory via cache or local repo.
+
+    Discovery order:
+    1. Cache path (~/.claude/plugins/cache/wicked-garden/{plugin}/{version}/)
+       - Selects highest semver version
+    2. Local repo sibling path (../../../{plugin}/)
+    """
+    # 1. Cache path (highest semver)
+    cache_base = Path.home() / ".claude" / "plugins" / "cache" / "wicked-garden" / plugin_name
+    if cache_base.exists():
+        versions = []
+        for d in cache_base.iterdir():
+            if d.is_dir():
+                versions.append((_parse_version(d.name), d))
+        if versions:
+            versions.sort(key=lambda x: x[0], reverse=True)
+            return versions[0][1]
+
+    # 2. Local repo sibling path
+    local = Path(__file__).parent.parent.parent / plugin_name
+    if local.exists() and (local / ".claude-plugin" / "plugin.json").exists():
+        return local
+
+    return None
+
+
+def parse_frontmatter(filepath: Path) -> dict:
+    """Parse YAML frontmatter from a scenario markdown file.
+
+    Returns dict with name, description, category, tools, difficulty, timeout, execution.
+    `execution` defaults to "auto" when absent; "manual" indicates the scenario
+    contains only slash commands and needs a Claude runtime to dispatch.
+    Uses simple regex parsing to avoid PyYAML dependency.
+    """
+    try:
+        text = filepath.read_text()
+    except (OSError, UnicodeDecodeError):
+        return {}
+    match = re.match(r"^---\s*\n(.*?)\n---", text, re.DOTALL)
+    if not match:
+        return {}
+
+    fm = match.group(1)
+    result = {}
+
+    # Simple key: value parsing for flat keys
+    for line in fm.split("\n"):
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+
+        kv = re.match(r"^(\w+):\s*(.+)$", line)
+        if kv:
+            key, val = kv.group(1), kv.group(2).strip().strip('"').strip("'")
+            if key in ("name", "description", "category", "difficulty", "execution"):
+                result[key] = val
+            elif key == "timeout":
+                try:
+                    result["timeout"] = int(val)
+                except ValueError:
+                    pass  # intentional: invalid timeout ignored
+
+    # Default execution to "auto" if absent
+    result.setdefault("execution", "auto")
+
+    # Parse tools block (required/optional arrays)
+    # Supports both inline [curl, hurl] and list (- curl) syntax
+    tools_match = re.search(
+        r"^tools:\s*\n((?:[ \t]+.*\n?)*)", fm, re.MULTILINE
+    )
+    if tools_match:
+        tools_block = tools_match.group(1)
+        result["tools"] = {"required": [], "optional": []}
+
+        current_key = None
+        for line in tools_block.split("\n"):
+            stripped = line.strip()
+            for key in ("required", "optional"):
+                if stripped.startswith(f"{key}:"):
+                    current_key = key
+                    # Check for inline array: required: [curl, hurl]
+                    inline = re.search(r"\[([^\]]*)\]", stripped)
+                    if inline:
+                        items = [i.strip() for i in inline.group(1).split(",") if i.strip()]
+                        result["tools"][current_key] = items
+                    break
+            else:
+                if stripped.startswith("- ") and current_key:
+                    result["tools"][current_key].append(stripped[2:].strip())
+
+    return result
+
+
+def discover_scenarios(
+    plugin_root: Path,
+    category: "str | None" = None,
+    check_tools: bool = False,
+) -> dict:
+    """Discover scenarios from a wicked-scenarios plugin root.
+
+    Returns:
+        {
+            "available": true,
+            "plugin_root": "/path/to/wicked-scenarios",
+            "scenarios": [
+                {
+                    "name": "api-health-check",
+                    "file": "scenarios/api-health-check.md",
+                    "category": "api",
+                    "description": "...",
+                    "tools": {"required": [...], "optional": [...]},
+                    "difficulty": "basic",
+                    "runnable": true  # only if check_tools=True
+                }
+            ],
+            "tool_status": {...}  # only if check_tools=True
+        }
+    """
+    scenarios_dir = plugin_root / "scenarios"
+    if not scenarios_dir.exists():
+        return {"available": True, "plugin_root": str(plugin_root), "scenarios": []}
+
+    scenarios = []
+    for md_file in sorted(scenarios_dir.glob("*.md")):
+        if md_file.name == "README.md":
+            continue
+        fm = parse_frontmatter(md_file)
+        if not fm.get("name"):
+            continue
+        if category and fm.get("category") != category:
+            continue
+
+        scenario = {
+            "name": fm.get("name", md_file.stem),
+            "file": str(md_file),
+            "category": fm.get("category", "unknown"),
+            "description": fm.get("description", ""),
+            "tools": fm.get("tools", {"required": [], "optional": []}),
+            "difficulty": fm.get("difficulty", "basic"),
+        }
+        scenarios.append(scenario)
+
+    result = {
+        "available": True,
+        "plugin_root": str(plugin_root),
+        "scenarios": scenarios,
+    }
+
+    # Optionally check tool availability via cli_discovery.py
+    if check_tools:
+        cli_discovery = plugin_root / "scripts" / "cli_discovery.py"
+        if cli_discovery.exists():
+            try:
+                proc = subprocess.run(
+                    [sys.executable, str(cli_discovery)],
+                    capture_output=True,
+                    text=True,
+                    timeout=10,
+                )
+                if proc.returncode == 0:
+                    tool_status = json.loads(proc.stdout)
+                    result["tool_status"] = tool_status
+
+                    # Mark each scenario as runnable or not
+                    for s in scenarios:
+                        required = s["tools"].get("required", [])
+                        s["runnable"] = all(
+                            tool_status.get(t, {}).get("available", False)
+                            for t in required
+                        )
+            except (subprocess.TimeoutExpired, json.JSONDecodeError):
+                pass  # fail open: tool check failed, skip
+
+    return result
+
+
+def main():
+    flags = [a for a in sys.argv[1:] if a.startswith("-")]
+    args = [a for a in sys.argv[1:] if not a.startswith("-")]
+
+    category = None
+    available_only = "--available-only" in flags
+    do_check_tools = "--check-tools" in flags or available_only
+
+    # Parse --category value
+    for i, f in enumerate(flags):
+        if f == "--category" and i + 1 < len(sys.argv[1:]):
+            # Find the value after --category
+            idx = sys.argv.index("--category")
+            if idx + 1 < len(sys.argv):
+                category = sys.argv[idx + 1]
+
+    # Discover wicked-scenarios plugin
+    plugin_root = discover_plugin("wicked-scenarios")
+    if plugin_root is None:
+        print(json.dumps({"available": False, "scenarios": []}, indent=2))
+        return
+
+    result = discover_scenarios(
+        plugin_root, category=category, check_tools=do_check_tools
+    )
+
+    # Filter to runnable only
+    if available_only:
+        if "tool_status" in result:
+            result["scenarios"] = [s for s in result["scenarios"] if s.get("runnable", False)]
+        else:
+            # Can't verify runnability without tool status — return empty
+            result["scenarios"] = []
+
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/scripts/qe/evidence_tracker.py

@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+"""evidence_tracker.py — Track produces-contracts per archetype phase.
+
+Each archetype declares a ``produces`` contract in
+``.claude-plugin/archetypes.json`` (e.g. build → ``shipped-code`` +
+``test-report``; migrate → ``shape-change`` + ``rollback-proof``).
+This module records when each produces item is met and provides
+``produces_satisfied()`` for archetype playbooks to check before
+advancing past their final phase.
+
+The tracker is doctrine-light: it records what the archetype claims
+to have produced, with a path to the artifact. It does not validate
+the artifact's content. Validation is the archetype's job (build's
+test phase runs tests; migrate's cutover phase runs rollback drill;
+review's assess phase applies the rubric). The tracker just answers:
+"have all produces items been claimed?"
+
+Stdlib-only.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+def _evidence_path(project_dir: Path) -> Path:
+    return Path(project_dir) / "audit" / "evidence.json"
+
+
+def _load_archetype_produces(archetype: str) -> List[str]:
+    """Read produces[] from the catalog. Returns [] when unavailable."""
+    try:
+        from pathlib import Path as _Path
+        catalog_path = (
+            _Path(__file__).resolve().parents[2]
+            / ".claude-plugin" / "archetypes.json"
+        )
+        catalog = json.loads(catalog_path.read_text(encoding="utf-8"))
+        return list(
+            catalog.get("archetypes", {}).get(archetype, {}).get("produces", [])
+        )
+    except Exception:
+        return []
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def initialize_for_archetype(
+    project_dir: Path,
+    archetype: str,
+) -> Path:
+    """Initialise the evidence tracker for an archetype run. Pre-populates
+    each declared produces item with verified=False. Idempotent: re-init
+    over an existing tracker preserves prior verifications by name."""
+    project_dir = Path(project_dir)
+    path = _evidence_path(project_dir)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    declared = _load_archetype_produces(archetype)
+
+    existing: Dict[str, Any] = {}
+    if path.exists():
+        try:
+            existing = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            existing = {}
+
+    by_name = {item.get("name"): item
+               for item in (existing.get("produces") or [])
+               if item.get("name")}
+
+    produces = []
+    for name in declared:
+        if name in by_name:
+            produces.append(by_name[name])
+        else:
+            produces.append({
+                "name": name,
+                "verified": False,
+                "claimed_at": None,
+                "artifact_path": None,
+                "claimed_by": None,
+                "note": None,
+            })
+
+    tracker = {
+        "archetype": archetype,
+        "created_at": existing.get("created_at") or _utc_now(),
+        "updated_at": _utc_now(),
+        "produces": produces,
+    }
+    path.write_text(json.dumps(tracker, indent=2))
+    return path
+
+
+def claim_produces(
+    project_dir: Path,
+    name: str,
+    *,
+    artifact_path: str,
+    claimed_by: str,
+    note: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Mark a produces item satisfied. ``artifact_path`` is a file path,
+    URL, or commit reference. ``claimed_by`` is the agent / task / user.
+
+    Raises:
+      FileNotFoundError if no tracker exists.
+      ValueError if ``name`` is not in the tracker (typo guard).
+    """
+    if not artifact_path or not artifact_path.strip():
+        raise ValueError("artifact_path is required")
+    if not claimed_by or not claimed_by.strip():
+        raise ValueError("claimed_by is required")
+
+    project_dir = Path(project_dir)
+    path = _evidence_path(project_dir)
+    if not path.exists():
+        raise FileNotFoundError(f"No evidence tracker at {path}")
+
+    tracker = json.loads(path.read_text(encoding="utf-8"))
+    produces = tracker.get("produces") or []
+
+    for item in produces:
+        if item.get("name") == name:
+            item["verified"] = True
+            item["claimed_at"] = _utc_now()
+            item["artifact_path"] = artifact_path
+            item["claimed_by"] = claimed_by
+            if note:
+                item["note"] = note
+            tracker["updated_at"] = _utc_now()
+            path.write_text(json.dumps(tracker, indent=2))
+            return item
+
+    known = [p.get("name") for p in produces]
+    raise ValueError(
+        f"Produces item '{name}' not declared for this archetype. "
+        f"Declared: {known}"
+    )
+
+
+def status(project_dir: Path) -> Dict[str, Any]:
+    project_dir = Path(project_dir)
+    path = _evidence_path(project_dir)
+    empty = {"exists": False, "total": 0, "verified": 0, "pending": 0,
+             "produces": []}
+    if not path.exists():
+        return empty
+    try:
+        tracker = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return empty
+    produces = tracker.get("produces") or []
+    verified = sum(1 for p in produces if p.get("verified"))
+    return {
+        "exists": True,
+        "archetype": tracker.get("archetype"),
+        "total": len(produces),
+        "verified": verified,
+        "pending": len(produces) - verified,
+        "produces": produces,
+        "created_at": tracker.get("created_at"),
+        "updated_at": tracker.get("updated_at"),
+    }
+
+
+def produces_satisfied(project_dir: Path) -> bool:
+    """True iff every declared produces item is verified, OR no tracker
+    exists. The latter case is intentional — archetype playbooks may
+    skip evidence tracking for low-rigor work."""
+    s = status(project_dir)
+    if not s["exists"]:
+        return True
+    return s["pending"] == 0
+
+
+__all__ = [
+    "initialize_for_archetype", "claim_produces", "status",
+    "produces_satisfied",
+]
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    import argparse, sys
+    parser = argparse.ArgumentParser(description="v11 evidence tracker tool.")
+    sub = parser.add_subparsers(dest="action", required=True)
+
+    init = sub.add_parser("init")
+    init.add_argument("project_dir")
+    init.add_argument("--archetype", required=True)
+
+    claim = sub.add_parser("claim")
+    claim.add_argument("project_dir")
+    claim.add_argument("--name", required=True)
+    claim.add_argument("--artifact", required=True)
+    claim.add_argument("--claimed-by", required=True)
+    claim.add_argument("--note", default=None)
+
+    stat = sub.add_parser("status")
+    stat.add_argument("project_dir")
+
+    args = parser.parse_args()
+
+    if args.action == "init":
+        path = initialize_for_archetype(Path(args.project_dir), args.archetype)
+        print(json.dumps({"ok": True, "path": str(path)}))
+    elif args.action == "claim":
+        try:
+            item = claim_produces(
+                Path(args.project_dir), args.name,
+                artifact_path=args.artifact, claimed_by=args.claimed_by,
+                note=args.note,
+            )
+            print(json.dumps({"ok": True, "produces_item": item}))
+        except (FileNotFoundError, ValueError) as exc:
+            print(json.dumps({"ok": False, "error": str(exc)}), file=sys.stderr)
+            sys.exit(1)
+    elif args.action == "status":
+        print(json.dumps(status(Path(args.project_dir)), indent=2))

package/scripts/qe/prove.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""prove.py — the one-line re-derivation verb.
+
+The produces-gate is the plugin's most valuable feature for an agent: it stops
+"done" from being self-asserted. But using it is a ~5-step ritual (vault init →
+author a contract.json → declare-contract → record --run → gate). That friction
+is exactly why an agent skips it and just *claims* the work is done — turning
+the gate into ceremony that exists but isn't used.
+
+This collapses the ritual into one verb an agent reaches for by reflex:
+
+    prove.py tests-pass --by "pytest -q"
+    prove.py build-clean --by "npm run build" --verifier exit_code_eq:0
+
+It re-derives, never asserts: it RUNS <command>, freezes the real exit code as
+vault evidence, then gates by re-running the verifier against that frozen
+evidence. Exit 0 iff the gate PASSES (re-derived). When the loom/vault backend
+is unresolvable it FAILS CLOSED (exit 3, gate: "unavailable") — never a vacuous
+pass. Reuses scripts/qe/vault_gate.py (resolve + gate_satisfied) and the vault
+CLI; it invents no new gating logic.
+
+Stdlib-only. Cross-platform (argv lists, shell=False).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess  # noqa: S404 — argv lists only, shell=False
+import sys
+import tempfile
+from pathlib import Path
+
+# Importing the sibling gate module must work whether this runs as a CLI
+# (`python3 scripts/qe/prove.py …` → only scripts/qe on sys.path) or imported.
+# Add scripts/ for vault_gate's own sibling import (_loom). This is the same
+# CLI-import discipline a subdir script that imports a top-level sibling needs.
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+try:
+    import vault_gate  # scripts/qe sibling
+except ImportError:  # pragma: no cover
+    vault_gate = None  # type: ignore
+
+
+# Mirror wicked-vault's parseVerifier so prove can validate the OUTPUT, not
+# just an exit code: regex_match / not_contains run against the command's
+# stdout; jq_pred evaluates a predicate over JSON stdout; commit_exists checks
+# a git SHA. This is what lets prove validate produced artifacts (an ADR has a
+# Decision section, a config contains no TODO, a decision JSON has >=2 options),
+# final or interim — not merely "a command exited 0".
+_VERIFIERS = {
+    "exit_code_eq": lambda arg: {"kind": "exit_code_eq", "params": {"code": int(arg or "0")}},
+    "regex_match": lambda arg: {"kind": "regex_match", "params": {"pattern": arg}},
+    "not_contains": lambda arg: {"kind": "not_contains", "params": {"pattern": arg}},
+    "commit_exists": lambda arg: {"kind": "commit_exists", "params": {"sha": arg}},
+    "jq_pred": lambda arg: {"kind": "jq_pred", "params": {"expr": arg}},
+}
+
+
+def _parse_verifier(spec: str) -> dict:
+    """`exit_code_eq:0` / `regex_match:## Decision` / `jq_pred:.options>=2` ->
+    {kind, params}. Defaults to exit_code_eq:0."""
+    name, sep, arg = spec.partition(":")
+    builder = _VERIFIERS.get(name)
+    if builder is None:
+        raise ValueError(f"unsupported verifier '{name}'; known: {sorted(_VERIFIERS)}")
+    if name != "exit_code_eq" and not (sep and arg):
+        raise ValueError(f"verifier '{name}' requires an argument, e.g. {name}:<value>")
+    return builder(arg)
+
+
+def _vault(prefix: list[str], project_dir: Path, *args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(prefix + list(args), cwd=str(project_dir),
+                          capture_output=True, text=True, timeout=300)
+
+
+# The doer identity prove records evidence UNDER. wicked-vault hardens `attest`
+# to fail closed when the recorded artifact's worker identity is "weak" (an
+# ambient `$USER`, i.e. created_by_source='env-user') — so an independent
+# attestation can't be trusted, and a `--with-attestations` hard gate can never
+# reach PASS. We therefore record under an EXPLICIT actor (created_by_source=
+# 'explicit'), which makes the independence check trustworthy with no
+# `--allow-weak-worker-identity` flag. Source from WICKED_VAULT_ACTOR when the
+# harness asserts one, else a deterministic fixed id. Crucially this id is the
+# DOER — an independent reviewer must attest as a DIFFERENT actor (the vault
+# still rejects a self-grade where evaluator == this actor), so the
+# self-grading guarantee is preserved, not reopened.
+def _prove_actor() -> str:
+    env = os.environ.get("WICKED_VAULT_ACTOR", "").strip()
+    return env or "garden-prove"
+
+
+def prove(claim: str, command: str, *, verifier: str = "exit_code_eq:0",
+          scope: str = "prove", phase: str = "verify",
+          project_dir: str = ".", with_attestations: bool = False,
+          kind: str = "check") -> dict:
+    """Re-derive a single claim end to end; return the gate verdict dict.
+
+    ``with_attestations`` forwards to the gate's hard-gate requirement (the
+    evaluator must not be the agent that did the work) — use it for
+    incident/migrate/review gates."""
+    if vault_gate is None:
+        return {"satisfied": False, "gate": "unavailable", "re_derived": False,
+                "error": "vault_gate import failed"}
+    pd = Path(project_dir).resolve()
+    prefix = vault_gate.resolve_vault(project_dir=pd)  # loom-resolved vault argv
+    if prefix is None:
+        return {"satisfied": False, "gate": "unavailable", "re_derived": False,
+                "error": ("evidence backend (wicked-loom/wicked-vault) not "
+                          "resolvable — fails closed, never a vacuous pass")}
+    # jq_pred ergonomics: prove always records via --run, so the payload is the
+    # capture envelope {command, exit_code, stdout, ...}. An agent means "query
+    # my command's JSON OUTPUT", not the envelope — so target stdout-as-JSON.
+    # Rewrite `jq_pred:<expr>` -> evaluate <expr> over fromjson(.stdout), unless
+    # the expr already navigates the envelope (mentions .stdout). regex_match /
+    # not_contains already scan the captured text, so they need no rewrite.
+    if verifier.startswith("jq_pred:") and ".stdout" not in verifier:
+        expr = verifier[len("jq_pred:"):]
+        verifier = f"jq_pred:.stdout | fromjson | ({expr})"
+    try:
+        verifier_spec = _parse_verifier(verifier)
+    except ValueError as e:
+        return {"satisfied": False, "gate": "error", "re_derived": False,
+                "error": str(e)}
+
+    # init (idempotent — ignore "already initialized"), declare, record --run.
+    _vault(prefix, pd, "init")
+    claim_spec = {
+        "claim_id": claim, "kind": kind,
+        "verifier": verifier_spec, "required": True,
+    }
+    if with_attestations:
+        # Hard gate (incident/migrate/review): the doer's own evidence cannot
+        # satisfy it. Opt the contract into the vault's attestation enforcement
+        # (`require_attestation`) so the gate REJECTs as UNATTESTED until an
+        # INDEPENDENT evaluator records `wicked-vault attest` (evaluator !=
+        # creator). Without this flag the contract is integrity-only and the
+        # gate would pass on the doer's evidence alone — a vacuous hard gate.
+        claim_spec["require_attestation"] = True
+    contract = {"required_evidence": [claim_spec]}
+    with tempfile.NamedTemporaryFile("w", suffix=".json", delete=False) as fh:
+        fh.write(json.dumps(contract))
+        spec_path = fh.name
+    try:
+        _vault(prefix, pd, "declare-contract", "--scope", scope, "--phase", phase,
+               "--spec", spec_path)
+        _vault(prefix, pd, "record", "--scope", scope, "--phase", phase,
+               "--claim", claim, "--kind", kind, "--source", command,
+               "--criteria", f"{claim}: `{command}` satisfies {verifier}",
+               "--verifier", verifier, "--actor", _prove_actor(), "--run")
+    finally:
+        try:
+            Path(spec_path).unlink()
+        except OSError:
+            pass
+
+    # The verdict is RE-DERIVED by the gate, not taken from the record above.
+    return vault_gate.gate_satisfied(pd, scope, phase,
+                                     with_attestations=with_attestations)
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(
+        description="Prove a claim by re-deriving it (run + gate), not asserting it.")
+    p.add_argument("claim", help="claim id, e.g. tests-pass")
+    p.add_argument("--by", required=True, metavar="COMMAND",
+                   help="the command whose real exit code is the evidence; it "
+                        "runs in --project-dir, so prefer absolute paths or a "
+                        "command valid from there")
+    p.add_argument("--verifier", default="exit_code_eq:0",
+                   help="verifier spec: exit_code_eq:0 | regex_match:<re> | not_contains:<re> | jq_pred:<expr> | commit_exists:<sha>. The regex/not_contains/jq_pred kinds validate the command's OUTPUT, not just its exit code.")
+    p.add_argument("--kind", default="check",
+                   help="evidence kind label (e.g. test-run, doc, output)")
+    p.add_argument("--scope", default="prove")
+    p.add_argument("--phase", default="verify")
+    p.add_argument("--project-dir", default=".")
+    p.add_argument("--with-attestations", action="store_true",
+                   help="hard gate (incident/migrate/review): require an "
+                        "INDEPENDENT attestation. The gate stays REJECT "
+                        "(UNATTESTED) until someone other than the doer runs "
+                        "`wicked-vault attest <artifact> --opinion pass` — the "
+                        "doer's own evidence cannot satisfy it")
+    a = p.parse_args()
+    verdict = prove(a.claim, a.by, verifier=a.verifier, scope=a.scope,
+                    phase=a.phase, project_dir=a.project_dir,
+                    with_attestations=a.with_attestations, kind=a.kind)
+    print(json.dumps(verdict, indent=2))
+    if verdict.get("satisfied"):
+        return 0
+    # distinguish fail-closed (backend gone) from a real REJECT
+    return 3 if verdict.get("gate") == "unavailable" else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())