@0dai-dev/cli 4.3.5 → 4.3.7

package/lib/python/anti_pattern_detector.py

@@ -0,0 +1,799 @@
+#!/usr/bin/env python3
+"""Anti-pattern detection from experience events.
+
+Analyzes structured experience events to detect recurring failure patterns
+and produces actionable warnings for users.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import hashlib
+import json
+import pathlib
+import sys
+import time
+
+import experience_pipeline as exp
+from json_utils import load_json, save_json
+
+CACHE_TTL = 600  # seconds (10 minutes)
+WARNING_VERSION = 1
+
+SEVERITY_ORDER = {"critical": 0, "warning": 1, "info": 2}
+UTC = getattr(dt, "UTC", dt.timezone.utc)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _now_dt() -> dt.datetime:
+    return dt.datetime.now(UTC).replace(microsecond=0)
+
+
+def _now() -> str:
+    return _now_dt().isoformat().replace("+00:00", "Z")
+
+
+def _dt_from_iso(value: str | None) -> dt.datetime | None:
+    if not value:
+        return None
+    try:
+        parsed = dt.datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=UTC)
+    return parsed.astimezone(UTC)
+
+
+def _safe_div(num: float, den: float) -> float:
+    return round(num / den, 4) if den else 0.0
+
+
+def _detect_target(target: str | pathlib.Path = ".") -> pathlib.Path:
+    return pathlib.Path(target).resolve()
+
+
+def _warnings_path(target: pathlib.Path) -> pathlib.Path:
+    return target / "ai" / "experience" / "warnings.json"
+
+
+def _evidence_hash(evidence: dict) -> str:
+    raw = json.dumps(evidence, sort_keys=True, default=str)
+    return hashlib.sha256(raw.encode()).hexdigest()[:12]
+
+
+def _task_events(events: list[dict]) -> list[dict]:
+    return [e for e in events if str(e.get("event_type") or "").startswith("task_")]
+
+
+def _task_result(event: dict) -> str:
+    return str((event.get("task") or {}).get("result") or "unknown")
+
+
+def _task_type(event: dict) -> str:
+    return str((event.get("task") or {}).get("task_type") or "unknown")
+
+
+def _task_cost(event: dict) -> float:
+    try:
+        return float((event.get("task") or {}).get("cost_usd") or 0)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def _task_elapsed(event: dict) -> float:
+    try:
+        return float((event.get("task") or {}).get("elapsed_seconds") or 0)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def _event_ts(event: dict) -> dt.datetime | None:
+    return _dt_from_iso(str(event.get("timestamp") or ""))
+
+
+def _make_warning(
+    pattern_id: str,
+    pattern_type: str,
+    severity: str,
+    title: str,
+    detail: str,
+    evidence: dict,
+) -> dict:
+    return {
+        "pattern_id": pattern_id,
+        "pattern_type": pattern_type,
+        "severity": severity,
+        "title": title,
+        "detail": detail,
+        "evidence": evidence,
+        "detected_at": _now(),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Detector 1: Agent-task mismatch
+# ---------------------------------------------------------------------------
+
+def detect_agent_task_mismatch(
+    events: list[dict],
+    *,
+    min_attempts: int = 3,
+    fail_threshold: float = 0.5,
+) -> list[dict]:
+    tasks = _task_events(events)
+    buckets: dict[tuple[str, str], dict] = {}
+    for e in tasks:
+        agent = str(e.get("agent") or "unknown")
+        ttype = _task_type(e)
+        key = (agent, ttype)
+        b = buckets.setdefault(key, {"total": 0, "fail": 0})
+        b["total"] += 1
+        if _task_result(e) in exp.FAIL_RESULTS:
+            b["fail"] += 1
+
+    # Find best alternative agents per task_type
+    type_stats: dict[str, dict[str, dict]] = {}
+    for (agent, ttype), b in buckets.items():
+        type_stats.setdefault(ttype, {})[agent] = b
+
+    warnings: list[dict] = []
+    for (agent, ttype), b in buckets.items():
+        if b["total"] < min_attempts:
+            continue
+        fail_rate = _safe_div(b["fail"], b["total"])
+        if fail_rate <= fail_threshold:
+            continue
+
+        # Find best alternative
+        alt_msg = ""
+        alts = type_stats.get(ttype, {})
+        best_alt = None
+        best_rate = fail_rate
+        for other_agent, ob in alts.items():
+            if other_agent == agent or ob["total"] < min_attempts:
+                continue
+            other_fail = _safe_div(ob["fail"], ob["total"])
+            if other_fail < best_rate:
+                best_rate = other_fail
+                best_alt = other_agent
+        if best_alt:
+            alt_success = round((1 - best_rate) * 100)
+            alt_msg = f"Consider using {best_alt} for {ttype} tasks ({alt_success}% success rate)"
+        else:
+            alt_msg = f"Consider trying a different agent for {ttype} tasks"
+
+        warnings.append(_make_warning(
+            pattern_id=f"agent_task_mismatch:{agent}:{ttype}",
+            pattern_type="agent_task_mismatch",
+            severity="warning",
+            title=f"{agent} fails on {ttype} tasks {round(fail_rate * 100)}% ({b['fail']}/{b['total']})",
+            detail=alt_msg,
+            evidence={
+                "agent": agent,
+                "task_type": ttype,
+                "attempts": b["total"],
+                "failures": b["fail"],
+                "fail_rate": fail_rate,
+            },
+        ))
+    return warnings
+
+
+# ---------------------------------------------------------------------------
+# Detector 2: Cost escalation
+# ---------------------------------------------------------------------------
+
+def detect_cost_escalation(
+    events: list[dict],
+    *,
+    growth_threshold: float = 0.3,
+    min_tasks: int = 3,
+    window_days: int = 7,
+) -> list[dict]:
+    now = _now_dt()
+    recent_cutoff = now - dt.timedelta(days=window_days)
+    prev_cutoff = now - dt.timedelta(days=window_days * 2)
+
+    recent_costs: list[float] = []
+    prev_costs: list[float] = []
+    for e in _task_events(events):
+        ts = _event_ts(e)
+        if not ts:
+            continue
+        cost = _task_cost(e)
+        if ts >= recent_cutoff:
+            recent_costs.append(cost)
+        elif ts >= prev_cutoff:
+            prev_costs.append(cost)
+
+    if len(recent_costs) < min_tasks or len(prev_costs) < min_tasks:
+        return []
+
+    recent_avg = _safe_div(sum(recent_costs), len(recent_costs))
+    prev_avg = _safe_div(sum(prev_costs), len(prev_costs))
+    if prev_avg <= 0:
+        return []
+
+    growth = _safe_div(recent_avg - prev_avg, prev_avg)
+    if growth <= growth_threshold:
+        return []
+
+    return [_make_warning(
+        pattern_id="cost_escalation",
+        pattern_type="cost_escalation",
+        severity="info",
+        title=f"Average task cost increased {round(growth * 100)}%: ${prev_avg:.2f} -> ${recent_avg:.2f}",
+        detail="Consider using cheaper models for simple tasks. Run: 0dai experience stats --by model",
+        evidence={
+            "recent_avg": recent_avg,
+            "previous_avg": prev_avg,
+            "growth_pct": growth,
+            "recent_count": len(recent_costs),
+            "previous_count": len(prev_costs),
+        },
+    )]
+
+
+# ---------------------------------------------------------------------------
+# Detector 3: File churn
+# ---------------------------------------------------------------------------
+
+def detect_file_churn(
+    target: pathlib.Path,
+    *,
+    max_touches: int = 3,
+    window_hours: int = 24,
+) -> list[dict]:
+    done_dir = target / "ai" / "swarm" / "done"
+    if not done_dir.is_dir():
+        return []
+
+    cutoff = _now_dt() - dt.timedelta(hours=window_hours)
+    file_tasks: dict[str, set[str]] = {}  # file_path -> set of task_ids
+
+    for task_file in done_dir.glob("*.json"):
+        task = load_json(task_file)
+        completed = _dt_from_iso(str(task.get("completed_at") or task.get("done_at") or ""))
+        if not completed or completed < cutoff:
+            continue
+        task_id = str(task.get("id") or task_file.stem)
+        files = task.get("files") or task.get("context", {}).get("files") or []
+        if isinstance(files, str):
+            files = [f.strip() for f in files.split(",") if f.strip()]
+        for f in files:
+            f_str = str(f).strip()
+            if f_str:
+                file_tasks.setdefault(f_str, set()).add(task_id)
+
+    warnings: list[dict] = []
+    for fpath, task_ids in file_tasks.items():
+        if len(task_ids) <= max_touches:
+            continue
+        fhash = hashlib.sha256(fpath.encode()).hexdigest()[:8]
+        warnings.append(_make_warning(
+            pattern_id=f"file_churn:{fhash}",
+            pattern_type="file_churn",
+            severity="warning",
+            title=f"{fpath} modified {len(task_ids)} times in {window_hours}h",
+            detail="This file may need architectural review. Multiple agents are fighting over it.",
+            evidence={
+                "file": fpath,
+                "touches": len(task_ids),
+                "task_ids": sorted(task_ids),
+                "window_hours": window_hours,
+            },
+        ))
+    return warnings
+
+
+# ---------------------------------------------------------------------------
+# Detector 4: Stuck agent
+# ---------------------------------------------------------------------------
+
+def detect_stuck_agent(
+    target: pathlib.Path,
+    events: list[dict],
+    *,
+    multiplier: float = 2.0,
+    min_history: int = 3,
+) -> list[dict]:
+    # Compute historical averages per task_type
+    type_elapsed: dict[str, list[float]] = {}
+    for e in _task_events(events):
+        ttype = _task_type(e)
+        elapsed = _task_elapsed(e)
+        if elapsed > 0:
+            type_elapsed.setdefault(ttype, []).append(elapsed)
+
+    type_avg: dict[str, float] = {}
+    for ttype, times in type_elapsed.items():
+        if len(times) >= min_history:
+            type_avg[ttype] = sum(times) / len(times)
+
+    if not type_avg:
+        return []
+
+    # Check active tasks
+    active_dir = target / "ai" / "swarm" / "active"
+    if not active_dir.is_dir():
+        return []
+
+    now_ts = time.time()
+    warnings: list[dict] = []
+    for task_file in active_dir.glob("*.json"):
+        task = load_json(task_file)
+        if not task:
+            continue
+        task_id = str(task.get("id") or task_file.stem)
+        ttype = str(task.get("type") or "feat")
+        started = _dt_from_iso(str(task.get("started_at") or task.get("created_at") or ""))
+        if not started:
+            continue
+        elapsed = now_ts - started.timestamp()
+        avg = type_avg.get(ttype)
+        if avg and elapsed > avg * multiplier:
+            agent = str(task.get("assigned_to") or "unknown")
+            warnings.append(_make_warning(
+                pattern_id=f"stuck_agent:{task_id}",
+                pattern_type="stuck_agent",
+                severity="warning",
+                title=f"{agent} task running {int(elapsed)}s (avg for {ttype}: {int(avg)}s)",
+                detail="Agent may be stuck. Consider: 0dai swarm kill + retry with different model",
+                evidence={
+                    "task_id": task_id,
+                    "agent": agent,
+                    "task_type": ttype,
+                    "elapsed": int(elapsed),
+                    "avg_elapsed": int(avg),
+                    "multiplier": multiplier,
+                },
+            ))
+    return warnings
+
+
+# ---------------------------------------------------------------------------
+# Detector 5: Repeated failure
+# ---------------------------------------------------------------------------
+
+def detect_repeated_failure(
+    events: list[dict],
+    *,
+    streak_threshold: int = 3,
+) -> list[dict]:
+    tasks = _task_events(events)
+    # Sort by timestamp descending (most recent first)
+    tasks.sort(key=lambda e: str(e.get("timestamp") or ""), reverse=True)
+
+    streak = 0
+    streak_ids: list[str] = []
+    for e in tasks:
+        result = _task_result(e)
+        if result in exp.FAIL_RESULTS:
+            streak += 1
+            streak_ids.append(str((e.get("task") or {}).get("task_id") or "?"))
+        else:
+            break  # streak broken
+
+    if streak < streak_threshold:
+        return []
+
+    return [_make_warning(
+        pattern_id="repeated_failure",
+        pattern_type="repeated_failure",
+        severity="critical",
+        title=f"{streak} tasks failed in a row ({', '.join(streak_ids[:5])})",
+        detail="Something systematic is wrong. Check: test suite broken? API down? Auth expired?",
+        evidence={
+            "streak": streak,
+            "task_ids": streak_ids[:10],
+        },
+    )]
+
+
+# ---------------------------------------------------------------------------
+# Detector 6: Model overspend
+# ---------------------------------------------------------------------------
+
+def detect_model_overspend(
+    events: list[dict],
+    *,
+    usage_threshold: float = 0.8,
+    min_tasks: int = 5,
+    success_tolerance: float = 0.05,
+) -> list[dict]:
+    tasks = _task_events(events)
+    total = len(tasks)
+    if total < min_tasks:
+        return []
+
+    # Group by model
+    model_stats: dict[str, dict] = {}
+    for e in tasks:
+        model = str(e.get("model") or "unknown")
+        b = model_stats.setdefault(model, {"count": 0, "success": 0, "cost": 0.0})
+        b["count"] += 1
+        if _task_result(e) in exp.SUCCESS_RESULTS:
+            b["success"] += 1
+        b["cost"] += _task_cost(e)
+
+    # Sort by avg cost descending
+    ranked = sorted(
+        model_stats.items(),
+        key=lambda item: _safe_div(item[1]["cost"], item[1]["count"]),
+        reverse=True,
+    )
+
+    warnings: list[dict] = []
+    for model, stats in ranked:
+        usage_pct = _safe_div(stats["count"], total)
+        if usage_pct < usage_threshold:
+            continue
+        success_rate = _safe_div(stats["success"], stats["count"])
+        avg_cost = _safe_div(stats["cost"], stats["count"])
+
+        # Find cheaper alternative with comparable success rate
+        for alt_model, alt_stats in ranked:
+            if alt_model == model or alt_stats["count"] < 2:
+                continue
+            alt_avg_cost = _safe_div(alt_stats["cost"], alt_stats["count"])
+            if alt_avg_cost >= avg_cost:
+                continue
+            alt_success = _safe_div(alt_stats["success"], alt_stats["count"])
+            if alt_success >= success_rate - success_tolerance:
+                cost_ratio = _safe_div(avg_cost, alt_avg_cost) if alt_avg_cost > 0 else 0
+                warnings.append(_make_warning(
+                    pattern_id=f"model_overspend:{model}",
+                    pattern_type="model_overspend",
+                    severity="info",
+                    title=f"{model} used for {round(usage_pct * 100)}% of tasks, "
+                          f"but {alt_model} has similar success at lower cost",
+                    detail=f"Switch to {alt_model}: save ~${stats['cost'] - alt_stats['cost']:.2f}/period",
+                    evidence={
+                        "model": model,
+                        "usage_pct": usage_pct,
+                        "success_rate": success_rate,
+                        "avg_cost": avg_cost,
+                        "cheaper_alt": alt_model,
+                        "alt_success_rate": alt_success,
+                        "alt_avg_cost": alt_avg_cost,
+                        "cost_ratio": cost_ratio,
+                    },
+                ))
+                break  # one recommendation per model
+    return warnings
+
+
+# ---------------------------------------------------------------------------
+# Detector 7: Abandoned sessions
+# ---------------------------------------------------------------------------
+
+def detect_abandoned_session(
+    target: pathlib.Path,
+    *,
+    stale_hours: int = 48,
+) -> list[dict]:
+    try:
+        import session_roaming as sr
+        sessions = sr.list_saved_sessions(target)
+    except (ImportError, OSError, json.JSONDecodeError, ValueError, AttributeError):
+        # session_roaming is optional (ImportError); list_saved_sessions
+        # reads JSON files (OSError/JSONDecodeError/ValueError); shape drift
+        # would surface as AttributeError. All non-fatal — return [].
+        return []
+
+    cutoff = _now_dt() - dt.timedelta(hours=stale_hours)
+    warnings: list[dict] = []
+    for sess in sessions:
+        status = str(sess.get("status") or "").lower()
+        if status in ("completed", "done", "closed"):
+            continue
+        saved_at = _dt_from_iso(str(sess.get("saved_at") or sess.get("updated") or ""))
+        if not saved_at or saved_at > cutoff:
+            continue
+        hours_stale = int((_now_dt() - saved_at).total_seconds() / 3600)
+        sess_id = str(sess.get("session_id") or sess.get("id") or "?")
+        goal = str((sess.get("goal") or {}).get("refined")
+                    or (sess.get("goal") or {}).get("original")
+                    or sess.get("goal") or "?")
+        if isinstance(goal, dict):
+            goal = str(goal.get("refined") or goal.get("original") or "?")
+        warnings.append(_make_warning(
+            pattern_id=f"abandoned_session:{sess_id}",
+            pattern_type="abandoned_session",
+            severity="info",
+            title=f"Session {sess_id[:16]} ({goal[:40]}) saved {hours_stale}h ago, never resumed",
+            detail=f"Resume or close: 0dai session resume --session {sess_id}",
+            evidence={
+                "session_id": sess_id,
+                "goal": goal[:80],
+                "saved_at": str(saved_at.isoformat()),
+                "hours_stale": hours_stale,
+            },
+        ))
+    return warnings
+
+
+# ---------------------------------------------------------------------------
+# Detector 8: Graph stale
+# ---------------------------------------------------------------------------
+
+def detect_graph_stale(
+    target: pathlib.Path,
+    events: list[dict],
+    *,
+    stale_days: int = 7,
+) -> list[dict]:
+    graph_path = target / "ai" / "manifest" / "project_graph.json"
+    graph = load_json(graph_path)
+    synced_at = _dt_from_iso(str(
+        graph.get("_synced_at")
+        or graph.get("meta", {}).get("updated_at")
+        or ""
+    ))
+
+    # Also check experience events for recent graph_synced
+    for e in events:
+        if str(e.get("event_type") or "") == "graph_synced":
+            ev_ts = _event_ts(e)
+            if ev_ts and (not synced_at or ev_ts > synced_at):
+                synced_at = ev_ts
+            break  # events are sorted newest first
+
+    if not synced_at:
+        return []  # no graph data at all, nothing to warn about
+
+    cutoff = _now_dt() - dt.timedelta(days=stale_days)
+    if synced_at > cutoff:
+        return []
+
+    # Check for active swarm tasks
+    active_dir = target / "ai" / "swarm" / "active"
+    has_active = active_dir.is_dir() and any(active_dir.glob("*.json"))
+    # Also count recent task events as activity
+    recent_tasks = len(_task_events(events[:20]))
+
+    if not has_active and recent_tasks == 0:
+        return []
+
+    days_stale = int((_now_dt() - synced_at).total_seconds() / 86400)
+    return [_make_warning(
+        pattern_id="graph_stale",
+        pattern_type="graph_stale",
+        severity="warning",
+        title=f"Graph last synced {days_stale} days ago with active swarm tasks",
+        detail="Graph is out of date. Run: 0dai graph push",
+        evidence={
+            "last_sync": synced_at.isoformat(),
+            "days_stale": days_stale,
+            "has_active_tasks": has_active,
+        },
+    )]
+
+
+# ---------------------------------------------------------------------------
+# Orchestrator
+# ---------------------------------------------------------------------------
+
+def run_all_detectors(target: pathlib.Path) -> list[dict]:
+    events = exp.load_events(target, since="30d", limit=10000)
+    warnings: list[dict] = []
+
+    detectors = [
+        lambda: detect_agent_task_mismatch(events),
+        lambda: detect_cost_escalation(events),
+        lambda: detect_file_churn(target),
+        lambda: detect_stuck_agent(target, events),
+        lambda: detect_repeated_failure(events),
+        lambda: detect_model_overspend(events),
+        lambda: detect_abandoned_session(target),
+        lambda: detect_graph_stale(target, events),
+    ]
+
+    for detector in detectors:
+        try:
+            warnings.extend(detector())
+        except Exception as exc:  # noqa: BLE001 — defensive dispatch loop
+            # Intentional broad catch: each detector is independently fallible
+            # (filesystem, JSON parse, third-party shape drift) and one failing
+            # detector must not silence the others. Surface to stderr so
+            # operators can still see which detector misbehaved instead of the
+            # previous fully-silent `pass`.
+            print(
+                f"anti_pattern_detector: {detector!r} failed: {exc!r}",
+                file=sys.stderr,
+            )
+
+    # Sort: critical first, then warning, then info
+    warnings.sort(key=lambda w: SEVERITY_ORDER.get(w.get("severity", "info"), 9))
+    return warnings
+
+
+# ---------------------------------------------------------------------------
+# Cache layer
+# ---------------------------------------------------------------------------
+
+def load_warnings(
+    target: pathlib.Path | str,
+    *,
+    force_refresh: bool = False,
+) -> dict:
+    target = _detect_target(target)
+    path = _warnings_path(target)
+    cached = load_json(path)
+
+    if not force_refresh and cached.get("refreshed_at"):
+        refreshed = _dt_from_iso(cached["refreshed_at"])
+        if refreshed and (_now_dt() - refreshed).total_seconds() < CACHE_TTL:
+            return cached
+
+    return refresh_warnings(target, cached)
+
+
+def refresh_warnings(target: pathlib.Path, previous: dict | None = None) -> dict:
+    previous = previous or {}
+    dismissed: dict[str, str] = dict(previous.get("dismissed") or {})
+    new_warnings = run_all_detectors(target)
+
+    # Filter out dismissed warnings with same evidence
+    active: list[dict] = []
+    for w in new_warnings:
+        pid = w["pattern_id"]
+        ehash = _evidence_hash(w["evidence"])
+        w["evidence_hash"] = ehash
+        if pid in dismissed and dismissed[pid] == ehash:
+            continue  # still dismissed, same evidence
+        active.append(w)
+
+    result = {
+        "version": WARNING_VERSION,
+        "refreshed_at": _now(),
+        "warnings": active,
+        "dismissed": dismissed,
+    }
+    save_json(_warnings_path(target), result)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Dismiss
+# ---------------------------------------------------------------------------
+
+def dismiss_warning(target: pathlib.Path | str, pattern_id: str) -> dict:
+    target = _detect_target(target)
+    data = load_warnings(target, force_refresh=True)
+    for w in data.get("warnings", []):
+        if w["pattern_id"] == pattern_id:
+            data["dismissed"][pattern_id] = w.get("evidence_hash", _evidence_hash(w["evidence"]))
+            data["warnings"] = [x for x in data["warnings"] if x["pattern_id"] != pattern_id]
+            save_json(_warnings_path(target), data)
+            return {"ok": True, "dismissed": pattern_id}
+    return {"ok": False, "error": f"warning not found: {pattern_id}"}
+
+
+def get_active_warnings(target: pathlib.Path | str) -> list[dict]:
+    data = load_warnings(target)
+    return data.get("warnings", [])
+
+
+# ---------------------------------------------------------------------------
+# CLI formatting
+# ---------------------------------------------------------------------------
+
+_SEVERITY_ICON = {"critical": "\u0052\u0045\u0044", "warning": "\u0059\u0045\u004c", "info": "\u0049\u004e\u0046"}
+
+def _severity_prefix(severity: str) -> str:
+    if severity == "critical":
+        return "  CRITICAL"
+    if severity == "warning":
+        return "  WARNING"
+    return "  INFO"
+
+
+def format_warnings(warnings: list[dict], *, verbose: bool = False) -> str:
+    if not warnings:
+        return "No active warnings."
+
+    lines = [f"Anti-pattern warnings ({len(warnings)}):"]
+    lines.append("")
+    for w in warnings:
+        prefix = _severity_prefix(w.get("severity", "info"))
+        lines.append(f"{prefix}: {w.get('title', '')}")
+        lines.append(f"  -> {w.get('detail', '')}")
+        if verbose:
+            lines.append(f"  id: {w.get('pattern_id', '')}")
+            for k, v in (w.get("evidence") or {}).items():
+                lines.append(f"  {k}: {v}")
+        lines.append("")
+
+    lines.append("Dismiss: 0dai experience dismiss <pattern_id>")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# CLI commands
+# ---------------------------------------------------------------------------
+
+def cmd_warnings(args: argparse.Namespace) -> int:
+    target = _detect_target(args.target)
+    data = load_warnings(target, force_refresh=getattr(args, "refresh", False))
+    active = data.get("warnings", [])
+
+    if getattr(args, "severity", None):
+        active = [w for w in active if w.get("severity") == args.severity]
+
+    if getattr(args, "json", False):
+        print(json.dumps({"warnings": active, "count": len(active)}, indent=2))
+    else:
+        print(format_warnings(active, verbose=getattr(args, "verbose", False)))
+    return 0
+
+
+def cmd_dismiss(args: argparse.Namespace) -> int:
+    target = _detect_target(args.target)
+    result = dismiss_warning(target, args.pattern_id)
+    if getattr(args, "json", False):
+        print(json.dumps(result, indent=2))
+    elif result["ok"]:
+        print(f"Dismissed {args.pattern_id}. Will not show again unless pattern reoccurs with new data.")
+    else:
+        print(result["error"])
+    return 0 if result["ok"] else 1
+
+
+def cmd_count(args: argparse.Namespace) -> int:
+    target = _detect_target(args.target)
+    data = load_warnings(target)
+    active = data.get("warnings", [])
+    by_severity: dict[str, int] = {}
+    for w in active:
+        s = w.get("severity", "info")
+        by_severity[s] = by_severity.get(s, 0) + 1
+    print(json.dumps({"count": len(active), "by_severity": by_severity}))
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Argparse
+# ---------------------------------------------------------------------------
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="anti_pattern_detector")
+    sub = parser.add_subparsers(dest="command")
+
+    w = sub.add_parser("warnings", help="Show active anti-pattern warnings")
+    w.add_argument("--target", default=".")
+    w.add_argument("--json", action="store_true")
+    w.add_argument("--refresh", action="store_true")
+    w.add_argument("--verbose", action="store_true")
+    w.add_argument("--severity", choices=["critical", "warning", "info"])
+    w.set_defaults(func=cmd_warnings)
+
+    d = sub.add_parser("dismiss", help="Dismiss a warning by pattern_id")
+    d.add_argument("pattern_id")
+    d.add_argument("--target", default=".")
+    d.add_argument("--json", action="store_true")
+    d.set_defaults(func=cmd_dismiss)
+
+    c = sub.add_parser("count", help="Output warning count as JSON")
+    c.add_argument("--target", default=".")
+    c.set_defaults(func=cmd_count)
+
+    return parser
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    if hasattr(args, "func"):
+        sys.exit(args.func(args))
+    else:
+        parser.print_help()
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()