wicked-garden 12.27.0

package/scripts/smaht/cheatsheet_store.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+"""Cheatsheet store — CLI wrapper for DomainStore cheatsheet operations.
+
+Usage:
+    python3 cheatsheet_store.py store --library react --data '{"key_apis": [...], ...}'
+    python3 cheatsheet_store.py list [--search query]
+    python3 cheatsheet_store.py get --library react
+    python3 cheatsheet_store.py remove --library react
+    python3 cheatsheet_store.py update-all
+"""
+
+import argparse
+import json
+import sys
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from _domain_store import DomainStore
+
+_sm = DomainStore("wicked-smaht")
+
+
+def _find_existing(library):
+    """Find the most recent cheatsheet for a library. Returns (record, all_matches)."""
+    records = _sm.list("cheatsheets") or []
+    matches = [
+        r for r in records
+        if r.get("library", "").lower() == library.lower()
+    ]
+    if matches:
+        matches.sort(key=lambda r: r.get("timestamp", ""), reverse=True)
+        return matches[0], matches
+    return None, []
+
+
+def _diff_cheatsheets(old, new):
+    """Compute a human-readable diff between two cheatsheet records.
+
+    Returns a dict with changed sections and a boolean indicating whether
+    anything meaningful changed.
+    """
+    changes = {}
+
+    # Compare key_apis by name
+    old_apis = {a["name"]: a for a in old.get("key_apis", [])}
+    new_apis = {a["name"]: a for a in new.get("key_apis", [])}
+    added_apis = sorted(set(new_apis) - set(old_apis))
+    removed_apis = sorted(set(old_apis) - set(new_apis))
+    if added_apis or removed_apis:
+        changes["key_apis"] = {}
+        if added_apis:
+            changes["key_apis"]["added"] = added_apis
+        if removed_apis:
+            changes["key_apis"]["removed"] = removed_apis
+
+    # Compare common_patterns by name
+    old_pats = {p["name"]: p for p in old.get("common_patterns", [])}
+    new_pats = {p["name"]: p for p in new.get("common_patterns", [])}
+    added_pats = sorted(set(new_pats) - set(old_pats))
+    removed_pats = sorted(set(old_pats) - set(new_pats))
+    if added_pats or removed_pats:
+        changes["common_patterns"] = {}
+        if added_pats:
+            changes["common_patterns"]["added"] = added_pats
+        if removed_pats:
+            changes["common_patterns"]["removed"] = removed_pats
+
+    # Compare gotchas
+    old_gotchas = set(old.get("gotchas", []))
+    new_gotchas = set(new.get("gotchas", []))
+    added_g = sorted(new_gotchas - old_gotchas)
+    removed_g = sorted(old_gotchas - new_gotchas)
+    if added_g or removed_g:
+        changes["gotchas"] = {}
+        if added_g:
+            changes["gotchas"]["added"] = added_g
+        if removed_g:
+            changes["gotchas"]["removed"] = removed_g
+
+    has_changes = len(changes) > 0
+    return changes, has_changes
+
+
+def cmd_store(args):
+    """Store a cheatsheet. Detects updates to existing entries and reports diffs."""
+    try:
+        data = json.loads(args.data)
+    except json.JSONDecodeError as e:
+        print(json.dumps({"success": False, "error": f"Invalid JSON: {e}"}))
+        sys.exit(1)
+
+    now = datetime.now(timezone.utc).isoformat()
+    existing, all_matches = _find_existing(args.library)
+
+    data.setdefault("id", str(uuid.uuid4()))
+    data.setdefault("library", args.library)
+    data.setdefault("timestamp", now)
+    data["fetched_at"] = now
+    if existing:
+        data["last_updated"] = now
+        data["previous_fetched_at"] = existing.get("fetched_at", existing.get("timestamp"))
+    if args.version_hint:
+        data.setdefault("version_hint", args.version_hint)
+
+    # Compute diff if updating an existing cheatsheet
+    diff_result = None
+    if existing:
+        changes, has_changes = _diff_cheatsheets(existing, data)
+        diff_result = {"has_changes": has_changes, "changes": changes}
+        # Remove old entries for this library so we don't accumulate duplicates
+        for old_rec in all_matches:
+            old_id = old_rec.get("id")
+            if old_id:
+                try:
+                    _sm.delete("cheatsheets", old_id)
+                except Exception:
+                    pass  # best-effort cleanup
+
+    result = _sm.create("cheatsheets", data)
+    output = {"id": data["id"], "success": result is not None}
+    if result is None:
+        output["error"] = "DomainStore returned None"
+    if existing:
+        output["updated"] = True
+        output["diff"] = diff_result
+    else:
+        output["updated"] = False
+
+    print(json.dumps(output))
+
+
+def cmd_list(args):
+    """List stored cheatsheets."""
+    records = _sm.list("cheatsheets") or []
+    if args.search:
+        q = args.search.lower()
+        records = [
+            r for r in records
+            if q in r.get("library", "").lower()
+        ]
+    # Deduplicate: keep only the most recent per library
+    seen = {}
+    for r in sorted(records, key=lambda x: x.get("timestamp", ""), reverse=True):
+        lib = r.get("library", "").lower()
+        if lib not in seen:
+            seen[lib] = r
+    deduped = sorted(seen.values(), key=lambda x: x.get("timestamp", ""), reverse=True)
+    print(json.dumps(deduped, indent=2))
+
+
+def cmd_get(args):
+    """Get cheatsheet by library name (most recent)."""
+    existing, _ = _find_existing(args.library)
+    if existing:
+        print(json.dumps(existing))
+    else:
+        print(json.dumps({"found": False}))
+
+
+def cmd_remove(args):
+    """Remove all cheatsheet entries for a library."""
+    existing, all_matches = _find_existing(args.library)
+    if not existing:
+        print(json.dumps({"success": False, "error": f"No cheatsheet found for '{args.library}'"}))
+        sys.exit(1)
+
+    removed = 0
+    for rec in all_matches:
+        rec_id = rec.get("id")
+        if rec_id:
+            try:
+                _sm.delete("cheatsheets", rec_id)
+                removed += 1
+            except Exception:
+                pass  # fail open
+    print(json.dumps({"success": True, "library": args.library, "removed": removed}))
+
+
+def cmd_update_all(args):
+    """List all unique libraries that have cached cheatsheets (for re-fetch orchestration)."""
+    records = _sm.list("cheatsheets") or []
+    seen = {}
+    for r in sorted(records, key=lambda x: x.get("timestamp", ""), reverse=True):
+        lib = r.get("library", "").lower()
+        if lib not in seen:
+            seen[lib] = {
+                "library": r.get("library"),
+                "version_hint": r.get("version_hint"),
+                "fetched_at": r.get("fetched_at", r.get("timestamp")),
+            }
+    libraries = sorted(seen.values(), key=lambda x: x.get("fetched_at", ""))
+    print(json.dumps({"libraries": libraries, "count": len(libraries)}))
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Cheatsheet store — CRUD operations via DomainStore"
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # store subcommand
+    store_p = subparsers.add_parser("store", help="Store a cheatsheet")
+    store_p.add_argument("--library", required=True, help="Library name (e.g. react, fastapi)")
+    store_p.add_argument("--data", required=True, help="JSON cheatsheet payload")
+    store_p.add_argument("--version-hint", dest="version_hint", default=None,
+                         help="Optional version string (e.g. 18.x)")
+    store_p.set_defaults(func=cmd_store)
+
+    # list subcommand
+    list_p = subparsers.add_parser("list", help="List stored cheatsheets")
+    list_p.add_argument("--search", default=None, help="Filter by library name substring")
+    list_p.set_defaults(func=cmd_list)
+
+    # get subcommand
+    get_p = subparsers.add_parser("get", help="Get most recent cheatsheet for a library")
+    get_p.add_argument("--library", required=True, help="Library name")
+    get_p.set_defaults(func=cmd_get)
+
+    # remove subcommand
+    remove_p = subparsers.add_parser("remove", help="Remove cheatsheet for a library")
+    remove_p.add_argument("--library", required=True, help="Library name to remove")
+    remove_p.set_defaults(func=cmd_remove)
+
+    # update-all subcommand
+    update_all_p = subparsers.add_parser("update-all",
+                                          help="List all cached libraries for re-fetch")
+    update_all_p.set_defaults(func=cmd_update_all)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/smaht/context_package.py

@@ -0,0 +1,386 @@
+#!/usr/bin/env python3
+"""
+Context Package Builder for subagent dispatches.
+
+Builds structured context packages for subagents instead of prose dumps.
+Called by other plugins (wicked-crew, etc.) via direct import or subprocess.
+
+Usage:
+    context_package.py build --task "Review auth implementation" [--project myproject] [--files src/auth/]
+    context_package.py build --task "..." --json
+    context_package.py build --task "..." --dispatch   # includes ecosystem orientation for subagents
+
+Output: A structured JSON context package with typed fields:
+{
+    "task": "Review auth implementation",
+    "constraints": ["Must use JWT", "No session storage"],
+    "decisions": ["Chose JWT for stateless auth"],
+    "files": ["src/auth/handler.py", "src/auth/middleware.py"],
+    "tools": ["Read", "Grep", "Glob"],
+    "project_state": {"phase": "build", "complexity": 4},
+    "memories": [{"title": "...", "summary": "..."}],
+    "ecosystem": {"installed_plugins": [...], "key_skills": [...]}
+}
+
+The --dispatch flag adds ecosystem orientation: which plugins are installed,
+what skills/tools are available, and conciseness guidance. This supplements
+the SubagentStart hook with richer context for dispatched subagents.
+"""
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+from pathlib import Path
+
+# All domain scripts live under plugins/wicked-garden/scripts/
+# context_package.py is at scripts/smaht/, so parents[1] = scripts/
+_SCRIPTS_ROOT = Path(__file__).resolve().parents[1]
+if str(_SCRIPTS_ROOT) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_ROOT))
+
+from _domain_store import DomainStore
+
+# Add smaht sub-paths for adapter/v2 imports
+_smaht_dir = Path(__file__).resolve().parent
+if str(_smaht_dir) not in sys.path:
+    sys.path.insert(0, str(_smaht_dir))
+if str(_smaht_dir / "v2") not in sys.path:
+    sys.path.insert(0, str(_smaht_dir / "v2"))
+
+
+# Maps installed plugins → their most useful skills/tools for subagents.
+# This is the static reference that replaces SubagentStart hook's pointer injection.
+PLUGIN_SKILL_MAP = {
+    "mem": [
+        "wicked-brain:memory (recall mode) — retrieve past decisions, constraints, patterns",
+        "wicked-brain:memory (store mode) — persist a decision or learning for future sessions",
+    ],
+    "search": [
+        "wicked-brain:search — find code symbols (functions, classes, methods)",
+        "/wicked-garden:search:refs — find where a symbol is referenced",
+        "/wicked-garden:search:blast-radius — analyze what changing a symbol affects",
+        "wicked-brain:search — search documents (PDF, markdown, Office)",
+    ],
+    "tasks": [
+        "TaskCreate/TaskUpdate/TaskList/TaskGet — native Claude Code task tools; metadata validated by PreToolUse",
+    ],
+    "testing": [
+        "/wicked-testing:authoring — generate test scenarios with edge cases",
+        "/wicked-testing:plan — generate comprehensive test plan",
+    ],
+    "engineering": [
+        "/wicked-garden:engineering:review — code review with senior engineering perspective",
+    ],
+    "platform": [
+        "/wicked-garden:platform:security — security review and vulnerability assessment",
+    ],
+    "wicked-garden": [
+        "context7 MCP tools — query up-to-date library documentation",
+    ],
+}
+
+
+def discover_installed_plugins() -> list:
+    """Discover which wicked-garden domain modules are available.
+
+    Since all plugins are consolidated into scripts/{domain}/, we check
+    which domain directories exist under _SCRIPTS_ROOT.
+    """
+    installed = []
+
+    # Check co-located domain directories
+    for entry in _SCRIPTS_ROOT.iterdir():
+        if entry.is_dir() and not entry.name.startswith("_") and not entry.name.startswith("."):
+            installed.append(entry.name)
+
+    return sorted(set(installed))
+
+
+def build_ecosystem_orientation(installed_plugins: list = None) -> dict:
+    """Build ecosystem orientation metadata for subagent prompts.
+
+    Returns dict with:
+    - installed_plugins: list of installed wicked-garden plugins
+    - key_skills: list of skill references relevant to subagents
+    - built_in_tools: list of Claude's built-in tools
+    """
+    if installed_plugins is None:
+        installed_plugins = discover_installed_plugins()
+
+    # Collect skill references for installed plugins
+    key_skills = []
+    for plugin in installed_plugins:
+        if plugin in PLUGIN_SKILL_MAP:
+            key_skills.extend(PLUGIN_SKILL_MAP[plugin])
+
+    return {
+        "installed_plugins": installed_plugins,
+        "key_skills": key_skills,
+        "built_in_tools": [
+            "Read, Grep, Glob — file reading and search",
+            "Edit, Write — file modification",
+            "Bash — shell commands",
+            "TaskCreate/TaskUpdate/TaskList/TaskGet — task management",
+            "WebSearch, WebFetch — web research",
+        ],
+    }
+
+
+async def gather_memories(task: str, limit: int = 3) -> list:
+    """Query wicked-brain for task-relevant memories.
+
+    Uses brain_adapter directly — brain_adapter.query() returns ContextItems
+    with source="brain". The previous domain_adapter.query() only returned
+    items with source="crew" or source="jam", so the `source == "brain"`
+    filter always dropped every item, making this function silently return [].
+    Fix: route directly to brain_adapter, which queries the wicked-brain FTS5
+    index. Returns [] gracefully when brain is unavailable.
+    """
+    try:
+        from adapters import brain_adapter
+        items = await brain_adapter.query(task)
+        results = []
+        for item in items:
+            results.append({
+                "title": getattr(item, "title", ""),
+                "summary": getattr(item, "summary", "")[:200],
+                "type": getattr(item, "metadata", {}).get("type", "unknown"),
+            })
+            if len(results) >= limit:
+                break
+        return results
+    except Exception:
+        return []
+
+
+async def gather_code_context(task: str, files: list = None, limit: int = 5) -> list:
+    """Query domain adapter for relevant code context.
+
+    Source-agnostic: returns items from any adapter (brain, domain, etc.).
+    The former source=="search" filter was removed because no adapter emits
+    source="search" — items come from brain/domain adapters instead.
+    """
+    try:
+        from adapters import domain_adapter
+        items = await domain_adapter.query(task)
+        results = []
+        for item in items:
+            results.append({
+                "title": getattr(item, "title", ""),
+                "file": getattr(item, "metadata", {}).get("file", ""),
+                "summary": getattr(item, "summary", "")[:200],
+            })
+            if len(results) >= limit:
+                break
+        return results
+    except Exception:
+        return []
+
+
+def get_session_state() -> dict:
+    """Get current session state from SessionState (v6).
+
+    Replaces the v5 HistoryCondenser.get_session_state() read. The v5 condenser
+    maintained a "ticket rail" (current_task, topics, decisions, constraints,
+    file_scope, open_questions) that is no longer tracked — v6 relies on the
+    facilitator's process-plan.md for the durable plan view, and SessionState
+    for per-session flags.
+
+    Returns whatever SessionState exposes as a dict, or {} on failure. Callers
+    that expected the v5 ticket-rail keys should treat missing keys as "".
+    """
+    try:
+        # scripts/smaht/context_package.py — scripts/ is parents[1]
+        import sys
+        from pathlib import Path
+        _SCRIPTS_DIR = Path(__file__).resolve().parents[1]
+        if str(_SCRIPTS_DIR) not in sys.path:
+            sys.path.insert(0, str(_SCRIPTS_DIR))
+        from _session import SessionState
+        state = SessionState.load()
+        if hasattr(state, "to_dict"):
+            return state.to_dict()
+        # Fallback: best-effort dataclass/attr snapshot
+        return {k: v for k, v in vars(state).items() if not k.startswith("_")}
+    except Exception:
+        return {}
+
+
+async def build_package(task: str, project: str = None, files: list = None,
+                        include_ecosystem: bool = False) -> dict:
+    """Build a structured context package for a subagent.
+
+    This is the core function — assembles task-scoped context from
+    wicked-brain (decisions, constraints) and wicked-garden:search (code context),
+    plus session state from the history condenser.
+
+    Args:
+        task: Task description for the subagent
+        project: Crew project name (optional)
+        files: Explicit file scope (optional)
+        include_ecosystem: Include ecosystem orientation (tools, skills, plugins)
+    """
+    # Gather from multiple sources in parallel
+    mem_task = gather_memories(task)
+    code_task = gather_code_context(task, files)
+
+    memories, code_context = await asyncio.gather(mem_task, code_task)
+
+    # Get session state (sync)
+    session = get_session_state()
+
+    # Extract typed fields from session state
+    constraints = session.get("active_constraints", [])
+    decisions = session.get("decisions", [])
+    file_scope = files or session.get("file_scope", [])
+    current_task = session.get("current_task", "")
+
+    # Get project state if available (via DomainStore)
+    project_state = {}
+    if project:
+        try:
+            sm = DomainStore("wicked-crew")
+            data = sm.get("projects", project)
+            if data:
+                project_state = {
+                    "phase": data.get("current_phase", ""),
+                    "complexity": data.get("complexity_score", 0),
+                    "signals": data.get("signals_detected", []),
+                }
+        except Exception:
+            pass  # fail open: crew data optional
+
+    package = {
+        "task": task,
+        "current_task": current_task,
+        "constraints": constraints,
+        "decisions": decisions,
+        "files": file_scope,
+        "code_context": code_context,
+        "memories": memories,
+        "project_state": project_state,
+        "session_topics": session.get("topics", []),
+    }
+
+    # Add ecosystem orientation for dispatch mode
+    if include_ecosystem:
+        package["ecosystem"] = build_ecosystem_orientation()
+
+    return package
+
+
+def format_as_prompt(package: dict) -> str:
+    """Format a context package as a prompt section for subagent injection.
+
+    This converts the structured JSON into a readable prompt block that
+    can be included in Task() dispatches.
+    """
+    lines = ["## Context Package", ""]
+
+    if package.get("task"):
+        lines.append(f"**Task**: {package['task']}")
+    if package.get("current_task"):
+        lines.append(f"**Session task**: {package['current_task']}")
+    lines.append("")
+
+    # Ecosystem orientation (dispatch mode) — goes first so subagent
+    # knows what tools are available before reading the task context
+    eco = package.get("ecosystem")
+    if eco:
+        lines.append("### Available Tools & Skills")
+        if eco.get("built_in_tools"):
+            for tool in eco["built_in_tools"]:
+                lines.append(f"- {tool}")
+        if eco.get("key_skills"):
+            lines.append("")
+            lines.append("**Ecosystem skills** (from installed plugins):")
+            for skill in eco["key_skills"]:
+                lines.append(f"- {skill}")
+        lines.append("")
+
+    if package.get("decisions"):
+        lines.append("### Decisions Made")
+        for d in package["decisions"]:
+            lines.append(f"- {d}")
+        lines.append("")
+
+    if package.get("constraints"):
+        lines.append("### Active Constraints")
+        for c in package["constraints"]:
+            lines.append(f"- {c}")
+        lines.append("")
+
+    if package.get("files"):
+        lines.append("### File Scope")
+        for f in package["files"][:10]:
+            lines.append(f"- `{f}`")
+        lines.append("")
+
+    if package.get("code_context"):
+        lines.append("### Relevant Code")
+        for c in package["code_context"]:
+            title = c.get("title", "")
+            file = c.get("file", "")
+            summary = c.get("summary", "")
+            lines.append(f"- **{title}** (`{file}`): {summary}")
+        lines.append("")
+
+    if package.get("memories"):
+        lines.append("### Relevant Memories")
+        for m in package["memories"]:
+            lines.append(f"- [{m.get('type', '')}] **{m.get('title', '')}**: {m.get('summary', '')}")
+        lines.append("")
+
+    if package.get("project_state"):
+        ps = package["project_state"]
+        if ps.get("phase"):
+            lines.append("### Project State")
+            lines.append(f"- Phase: {ps['phase']}")
+            if ps.get("complexity"):
+                lines.append(f"- Complexity: {ps['complexity']}/7")
+            if ps.get("signals"):
+                lines.append(f"- Signals: {', '.join(ps['signals'])}")
+            lines.append("")
+
+    # Conciseness guidance for subagents (replaces PreToolUse pressure gate)
+    if eco:
+        lines.append("### Output Guidance")
+        lines.append("Keep responses focused and concise. Return structured data (JSON) "
+                      "when possible. For CLI outputs or evidence artifacts, summarize "
+                      "rather than including verbatim. The parent orchestrator manages "
+                      "context pressure — help by keeping your output lean.")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Build structured context packages for subagents")
+    parser.add_argument("command", choices=["build", "format"], help="Command to run")
+    parser.add_argument("--task", required=True, help="Task description for the subagent")
+    parser.add_argument("--project", help="Crew project name (optional)")
+    parser.add_argument("--files", nargs="*", help="Explicit file scope (optional)")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    parser.add_argument("--prompt", action="store_true", help="Output as formatted prompt section")
+    parser.add_argument("--dispatch", action="store_true",
+                        help="Include ecosystem orientation (tools, skills, plugins) for subagent dispatch")
+
+    args = parser.parse_args()
+
+    include_ecosystem = args.dispatch
+    package = asyncio.run(build_package(args.task, args.project, args.files,
+                                        include_ecosystem=include_ecosystem))
+
+    if args.command == "format" or args.prompt:
+        print(format_as_prompt(package))
+    elif args.json:
+        print(json.dumps(package, indent=2))
+    else:
+        # Default: formatted prompt
+        print(format_as_prompt(package))
+
+
+if __name__ == "__main__":
+    main()