wicked-garden 12.27.0

package/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "wicked-garden"
+version = "1.33.0"
+description = "AI-Native SDLC delivered as a single Claude Code plugin"
+requires-python = ">=3.10"
+dependencies = [
+    "rapidfuzz>=3.0",
+    "aiofiles>=23.0",
+    "pydantic>=2.0",
+    "pathspec>=0.11.0",
+    "pyyaml>=6.0",
+    "flask>=3.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-asyncio>=0.21",
+    "pytest-benchmark>=4.0",
+    "hypothesis>=6.100",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+# Not a distributable package — this pyproject.toml exists so uv can manage deps
+packages = ["scripts"]
+
+[tool.uv]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-benchmark>=4.0",
+    "hypothesis>=6.100",
+]
+# uv resolves from repo root so all `cd $PLUGIN_ROOT && uv run python ...` invocations work
+
+# Hypothesis config (design-addendum-1 D-8):
+#   derandomize=true keeps PR CI deterministic per T1 (determinism).
+#   Nightly 10K-iter jobs can override with --hypothesis-seed=random.
+[tool.hypothesis]
+database_file = ".hypothesis/examples"
+deadline = 1000
+verbosity = "normal"
+derandomize = true
+
+# pytest config — marker registration keeps the benchmark lane opt-in.
+# Running `pytest` without `-m benchmark` excludes the benchmark suite via
+# the addopts default; CI opts in explicitly in .github/workflows/benchmark.yml.
+[tool.pytest.ini_options]
+testpaths = ["tests", "daemon"]
+markers = [
+    "benchmark: AC-11 gate-result ingestion perf SLO lane (opt-in via `-m benchmark`). See .github/workflows/benchmark.yml.",
+    "slow: integration tests that invoke real subprocesses and take >1s (excluded from fast-CI runs with `-m 'not slow'`).",
+]
+addopts = "-m 'not benchmark'"

package/schemas/README.md

@@ -0,0 +1,32 @@
+# Schemas
+
+JSON contract schemas used by the observability assertion system (`/wicked-garden:platform:assert`).
+
+## Purpose
+
+These schemas define the expected JSON output shape for key observability scripts. The contract assertion runner (`scripts/platform/observability/assert_contracts.py`) loads each schema, invokes the corresponding script, and validates the output matches the contract.
+
+This catches silent regressions — if a script's output shape changes (missing fields, wrong types, new enum values), the assertion fails before users hit runtime errors.
+
+## Files
+
+| Schema | Validates Output Of | What It Checks |
+|--------|---------------------|----------------|
+| `assert_contracts.json` | `assert_contracts.py --health-check` | Array of contract results with ts, plugin, script, result (pass/timeout/empty/malformed), violations, duration_ms |
+| `health_probe.json` | `health_probe.py --health-check` | Health status (healthy/degraded/unhealthy), violation list with severity, summary counts |
+| `plugin_status.json` | `plugin_status.py --health-check` | Plugin metadata (name, version, status), component counts (domains, commands, agents, skills, hooks) |
+
+## Usage
+
+```bash
+# Run all contract assertions
+/wicked-garden:platform:assert
+
+# Or directly via script
+python3 scripts/platform/observability/assert_contracts.py --json
+```
+
+## Adding a New Schema
+
+1. Create `schemas/{script-name}.json` with a JSON Schema defining the expected output
+2. The assertion runner discovers it automatically and matches it to `scripts/**/{script-name}.py`

package/schemas/assert_contracts.json

@@ -0,0 +1,37 @@
+{
+  "$comment": "Contract schema for scripts/observability/assert_contracts.py --health-check output",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "required": ["ts", "plugin", "script", "result", "violations", "duration_ms"],
+    "properties": {
+      "ts": {
+        "type": "string"
+      },
+      "plugin": {
+        "type": "string"
+      },
+      "script": {
+        "type": "string"
+      },
+      "result": {
+        "type": "string",
+        "enum": ["pass", "timeout", "empty", "malformed"]
+      },
+      "violations": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "required": ["field", "message"],
+          "properties": {
+            "field": { "type": "string" },
+            "message": { "type": "string" }
+          }
+        }
+      },
+      "duration_ms": {
+        "type": "number"
+      }
+    }
+  }
+}

package/schemas/health_probe.json

@@ -0,0 +1,46 @@
+{
+  "$comment": "Contract schema for scripts/observability/health_probe.py --health-check output",
+  "type": "object",
+  "required": ["status", "checked_at", "plugins_checked", "violations", "summary"],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["healthy", "degraded", "unhealthy"]
+    },
+    "checked_at": {
+      "type": "string"
+    },
+    "plugins_checked": {
+      "type": "integer"
+    },
+    "violations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["plugin", "type", "severity", "message"],
+        "properties": {
+          "plugin": { "type": "string" },
+          "type": { "type": "string" },
+          "severity": {
+            "type": "string",
+            "enum": ["error", "warning"]
+          },
+          "message": { "type": "string" },
+          "file": { "type": "string" },
+          "line": { "type": "integer" }
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": ["errors", "warnings", "plugins_healthy", "plugins_degraded", "plugins_unhealthy"],
+      "properties": {
+        "errors": { "type": "integer" },
+        "warnings": { "type": "integer" },
+        "plugins_healthy": { "type": "integer" },
+        "plugins_degraded": { "type": "integer" },
+        "plugins_unhealthy": { "type": "integer" }
+      }
+    }
+  }
+}

package/schemas/plugin_status.json

@@ -0,0 +1,37 @@
+{
+  "$comment": "Contract schema for scripts/observability/plugin_status.py --health-check output",
+  "type": "object",
+  "required": ["plugin", "version", "status", "checked_at", "counts", "domains"],
+  "properties": {
+    "plugin": {
+      "type": "string"
+    },
+    "version": {
+      "type": "string"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["installed", "missing", "error"]
+    },
+    "checked_at": {
+      "type": "string"
+    },
+    "counts": {
+      "type": "object",
+      "required": ["domains", "commands", "agents", "skills", "hooks"],
+      "properties": {
+        "domains": { "type": "integer" },
+        "commands": { "type": "integer" },
+        "agents": { "type": "integer" },
+        "skills": { "type": "integer" },
+        "hooks": { "type": "integer" }
+      }
+    },
+    "domains": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+}

package/scripts/_adapters/__init__.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""
+_adapters/__init__.py — External tool adapter base class and factory.
+
+ExternalToolAdapter is the interface DomainStore uses to delegate CRUD
+operations to external MCP tools (Linear, Jira, Notion, Miro, etc.).
+
+All stub implementations return None — DomainStore interprets None as
+"not handled; fall through to local JSON". Real implementations will be
+wired once the MCP-from-Python invocation approach is determined.
+
+Usage:
+    from _adapters import ExternalToolAdapter, from_tool_name
+
+    adapter = from_tool_name("linear")   # → LinearAdapter instance
+    adapter = from_tool_name("unknown")  # → ExternalToolAdapter (base no-op)
+    adapter = from_tool_name(None)       # → None
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+# ---------------------------------------------------------------------------
+# Base class
+# ---------------------------------------------------------------------------
+
+
+class ExternalToolAdapter:
+    """No-op base adapter.  All methods return None so DomainStore falls back
+    to local JSON automatically.
+
+    Subclasses override individual methods as real MCP bindings are added.
+    """
+
+    # The tool name this adapter handles (set on subclasses)
+    tool_name: str = "base"
+
+    # ------------------------------------------------------------------
+    # Read operations
+    # ------------------------------------------------------------------
+
+    def list(self, source: str, **params: Any) -> Optional[list]:
+        """List records.  Returns None → DomainStore uses local JSON."""
+        return None
+
+    def get(self, source: str, id: str) -> Optional[dict]:
+        """Fetch a single record by ID.  Returns None → fall through."""
+        return None
+
+    def search(self, source: str, q: str, **params: Any) -> Optional[list]:
+        """Search records.  Returns None → fall through."""
+        return None
+
+    # ------------------------------------------------------------------
+    # Write operations
+    # ------------------------------------------------------------------
+
+    def create(self, source: str, payload: dict) -> Optional[dict]:
+        """Create a record.  Returns None → DomainStore writes locally."""
+        return None
+
+    def update(self, source: str, id: str, diff: dict) -> Optional[dict]:
+        """Patch a record.  Returns None → fall through."""
+        return None
+
+    def delete(self, source: str, id: str) -> Optional[bool]:
+        """Delete a record.  Returns None → fall through."""
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Factory
+# ---------------------------------------------------------------------------
+
+# Registry: tool name (lowercase) → adapter class
+_REGISTRY: dict[str, type[ExternalToolAdapter]] = {}
+
+
+def _register(cls: type[ExternalToolAdapter]) -> type[ExternalToolAdapter]:
+    """Decorator that registers an adapter class in _REGISTRY."""
+    _REGISTRY[cls.tool_name.lower()] = cls
+    return cls
+
+
+def from_tool_name(tool_name: Optional[str]) -> Optional[ExternalToolAdapter]:
+    """Return an adapter instance for *tool_name*, or None.
+
+    Args:
+        tool_name: Tool name returned by resolve_tool(), e.g. "linear",
+                   "jira", "notion", "miro".  None or "local" returns None
+                   so the caller can skip the external path entirely.
+
+    Returns:
+        An ExternalToolAdapter instance, or None when no tool is configured.
+
+    Lookup order:
+        1. Exact match in _REGISTRY (lazy-loaded on first call).
+        2. Falls back to the base no-op ExternalToolAdapter so callers
+           never have to guard against unknown tool names — the base adapter
+           returns None on every operation and local JSON is used.
+    """
+    if not tool_name or tool_name == "local":
+        return None
+
+    # Lazy-load concrete adapters to avoid import cost when local-only
+    _ensure_adapters_loaded()
+
+    key = tool_name.lower()
+    cls = _REGISTRY.get(key)
+    if cls is not None:
+        return cls()
+
+    # Unknown tool — return base no-op so operations fall through to local
+    return ExternalToolAdapter()
+
+
+# ---------------------------------------------------------------------------
+# Lazy loader
+# ---------------------------------------------------------------------------
+
+_adapters_loaded = False
+
+
+def _ensure_adapters_loaded() -> None:
+    """Import all concrete adapter modules so they register themselves.
+
+    Uses spec_from_file_location so this works whether _adapters is imported
+    as a proper package or simply has its parent directory on sys.path.
+    """
+    global _adapters_loaded
+    if _adapters_loaded:
+        return
+    _adapters_loaded = True
+
+    import importlib.util
+    import os
+    import sys as _sys
+
+    _pkg_dir = os.path.dirname(__file__)
+    # Ensure the _adapters package itself is registered in sys.modules so
+    # that absolute imports like "from _adapters import ..." inside each
+    # adapter module resolve correctly.
+    _pkg_key = "_adapters"
+    import types as _types
+    if _pkg_key not in _sys.modules:
+        _sys.modules[_pkg_key] = _sys.modules.get(__name__, _types.ModuleType(_pkg_key))
+
+    for filename in sorted(os.listdir(_pkg_dir)):
+        if not filename.endswith("_adapter.py") or filename.startswith("_"):
+            continue
+        module_name = filename[:-3]  # strip .py
+        full_key = f"_adapters.{module_name}"
+        if full_key in _sys.modules:
+            continue
+        try:
+            spec = importlib.util.spec_from_file_location(
+                full_key,
+                os.path.join(_pkg_dir, filename),
+            )
+            if spec and spec.loader:
+                mod = importlib.util.module_from_spec(spec)
+                _sys.modules[full_key] = mod
+                spec.loader.exec_module(mod)  # type: ignore[arg-type]
+        except Exception:
+            pass  # Adapter unavailable — continue with base no-op

package/scripts/_adapters/jira_adapter.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python3
+"""
+jira_adapter.py — Jira MCP adapter stub for DomainStore.
+
+All methods return None so DomainStore falls through to local JSON.
+Real Jira MCP integration will be added once the MCP-from-Python
+invocation approach is determined.
+"""
+from __future__ import annotations
+
+from _adapters import ExternalToolAdapter, _register
+
+
+@_register
+class JiraAdapter(ExternalToolAdapter):
+    """Stub adapter for the Jira project-management MCP tool."""
+
+    tool_name = "jira"

package/scripts/_adapters/linear_adapter.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python3
+"""
+linear_adapter.py — Linear MCP adapter stub for DomainStore.
+
+All methods return None so DomainStore falls through to local JSON.
+Real Linear MCP integration will be added once the MCP-from-Python
+invocation approach is determined.
+"""
+from __future__ import annotations
+
+from _adapters import ExternalToolAdapter, _register
+
+
+@_register
+class LinearAdapter(ExternalToolAdapter):
+    """Stub adapter for the Linear project-management MCP tool."""
+
+    tool_name = "linear"

package/scripts/_adapters/miro_adapter.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python3
+"""
+miro_adapter.py — Miro MCP adapter stub for DomainStore.
+
+All methods return None so DomainStore falls through to local JSON.
+Real Miro MCP integration will be added once the MCP-from-Python
+invocation approach is determined.
+"""
+from __future__ import annotations
+
+from _adapters import ExternalToolAdapter, _register
+
+
+@_register
+class MiroAdapter(ExternalToolAdapter):
+    """Stub adapter for the Miro whiteboard/brainstorming MCP tool."""
+
+    tool_name = "miro"

package/scripts/_adapters/notion_adapter.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python3
+"""
+notion_adapter.py — Notion MCP adapter stub for DomainStore.
+
+All methods return None so DomainStore falls through to local JSON.
+Real Notion MCP integration will be added once the MCP-from-Python
+invocation approach is determined.
+"""
+from __future__ import annotations
+
+from _adapters import ExternalToolAdapter, _register
+
+
+@_register
+class NotionAdapter(ExternalToolAdapter):
+    """Stub adapter for the Notion knowledge-management MCP tool."""
+
+    tool_name = "notion"