wicked-garden 12.27.0

package/scripts/crew/scope_delta.py

@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+"""scope_delta.py — Compute scope-delta metrics for the clarify HITL gate.
+
+Issue #847: the facilitator's clarify HITL gate previously fired only on
+intent ambiguity (the six triggers in ``skills/propose-process/refs/
+ambiguity.md``). It missed the failure where the rubric silently
+expanded a 24-issue wave plan to absorb a 1M-insertion sibling project
+because no trigger looked at scope-size deltas.
+
+This helper computes the four scope-delta metrics that drive the
+seventh trigger added in #847:
+
+- ``new_items``: items in the proposed plan not present in the
+  baseline plan (matched by id).
+- ``oversize_factor``: ratio of the largest new item's size to the
+  median size of items already in the baseline plan. Trips the trigger
+  at >= 3.0.
+- ``total_size_ratio``: total proposed-plan size / baseline-plan size.
+  Trips the trigger at >= 2.0.
+- ``epic_or_project_added``: True iff any new item carries a label
+  matching the epic/project regex.
+
+Stdlib-only; designed for the propose-process facilitator agent or
+the slim caller to consume programmatically. Returns a dict; the
+facilitator agent should surface the trigger as a clarifying question
+when any threshold is crossed (per ambiguity.md trigger #7).
+
+The "size" of an item is whatever the caller measures consistently —
+LOC, file count, sub-task count, or a fused score. The helper does not
+prescribe a unit; it just compares apples to apples.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from typing import Any, Dict, Iterable, List, Optional
+
+
+# Issue #847: items labeled with these patterns are project-sized by
+# convention and must not be silently absorbed into a wave plan.
+EPIC_LABEL_PATTERNS = (
+    re.compile(r"^epic$", re.IGNORECASE),
+    re.compile(r"^project$", re.IGNORECASE),
+    re.compile(r"^large$", re.IGNORECASE),
+    re.compile(r"^xlarge$", re.IGNORECASE),
+    re.compile(r"^xxl$", re.IGNORECASE),
+)
+
+# Threshold defaults — surfaced as constants so callers can override
+# but the trigger doctrine in ambiguity.md stays in sync.
+DEFAULT_OVERSIZE_FACTOR_TRIP = 3.0
+DEFAULT_TOTAL_SIZE_RATIO_TRIP = 2.0
+
+
+def _median(values: List[float]) -> float:
+    if not values:
+        return 0.0
+    sorted_values = sorted(values)
+    mid = len(sorted_values) // 2
+    if len(sorted_values) % 2 == 1:
+        return float(sorted_values[mid])
+    return (sorted_values[mid - 1] + sorted_values[mid]) / 2.0
+
+
+def _has_epic_label(labels: Optional[Iterable[str]]) -> bool:
+    if not labels:
+        return False
+    for label in labels:
+        if not isinstance(label, str):
+            continue
+        for pattern in EPIC_LABEL_PATTERNS:
+            if pattern.match(label.strip()):
+                return True
+    return False
+
+
+def _normalize_item(raw: Any) -> Dict[str, Any]:
+    """Coerce a raw item entry to the canonical shape.
+
+    Accepts either a dict ({"id", "size", "labels"}) or a bare string
+    (treated as id with size=1, no labels). Anything else is dropped.
+    """
+    if isinstance(raw, dict):
+        item_id = raw.get("id") or raw.get("name") or raw.get("title")
+        size = raw.get("size", 1)
+        labels = raw.get("labels", [])
+        if item_id is None:
+            return {}
+        try:
+            size = float(size)
+        except (TypeError, ValueError):
+            size = 1.0
+        # Labels normalization (Gemini PR #860 review): a bare string must
+        # become a single-element list, not be decomposed by list("epic")
+        # into ['e','p','i','c']. A non-iterable type (int, None, etc.)
+        # falls back to []. Only str/list/tuple yield meaningful labels.
+        if isinstance(labels, str):
+            labels_list = [labels]
+        elif isinstance(labels, (list, tuple)):
+            labels_list = list(labels)
+        else:
+            labels_list = []
+        return {"id": str(item_id), "size": size, "labels": labels_list}
+    if isinstance(raw, str):
+        return {"id": raw, "size": 1.0, "labels": []}
+    return {}
+
+
+def compute_scope_delta(
+    baseline: List[Any],
+    proposed: List[Any],
+    *,
+    oversize_factor_trip: float = DEFAULT_OVERSIZE_FACTOR_TRIP,
+    total_size_ratio_trip: float = DEFAULT_TOTAL_SIZE_RATIO_TRIP,
+) -> Dict[str, Any]:
+    """Compute scope-delta metrics for the clarify HITL gate (#847).
+
+    Args:
+        baseline: List of items the user explicitly named in the
+            original ask. Each entry is a dict
+            ``{"id": str, "size": float, "labels": [str]}`` or a bare
+            string id.
+        proposed: List of items in the proposed plan, same shape.
+        oversize_factor_trip: Threshold at or above which the
+            oversize_factor trips the trigger (default 3.0).
+        total_size_ratio_trip: Threshold at or above which the
+            total_size_ratio trips the trigger (default 2.0).
+
+    Returns:
+        Dict with:
+          - ``new_items``: list of {id, size, labels} for items in
+            proposed but not baseline.
+          - ``baseline_median_size`` / ``baseline_total_size``.
+          - ``proposed_total_size``.
+          - ``oversize_factor``: max(new_item.size) / baseline_median_size,
+            or None when baseline_median_size is 0.
+          - ``total_size_ratio``: proposed_total / baseline_total, or
+            None when baseline_total is 0.
+          - ``epic_or_project_added``: True iff any new item has an
+            epic-class label.
+          - ``triggers``: ordered list of human-readable strings naming
+            which thresholds tripped. Empty list = no trigger fired.
+
+    The trigger fires whenever ``triggers`` is non-empty.
+    """
+    base = [it for it in (_normalize_item(x) for x in baseline) if it]
+    prop = [it for it in (_normalize_item(x) for x in proposed) if it]
+
+    base_ids = {it["id"] for it in base}
+    new_items = [it for it in prop if it["id"] not in base_ids]
+
+    baseline_sizes = [it["size"] for it in base]
+    baseline_median = _median(baseline_sizes)
+    baseline_total = sum(baseline_sizes)
+    proposed_total = sum(it["size"] for it in prop)
+
+    if new_items and baseline_median > 0:
+        max_new_size = max(it["size"] for it in new_items)
+        oversize_factor = max_new_size / baseline_median
+    else:
+        oversize_factor = None
+
+    if baseline_total > 0:
+        total_size_ratio = proposed_total / baseline_total
+    else:
+        total_size_ratio = None
+
+    epic_added = any(_has_epic_label(it.get("labels")) for it in new_items)
+
+    triggers: List[str] = []
+    if oversize_factor is not None and oversize_factor >= oversize_factor_trip:
+        triggers.append(
+            f"oversize-factor: largest new item is {oversize_factor:.1f}x "
+            f"the baseline median (trip threshold: {oversize_factor_trip}x)"
+        )
+    if total_size_ratio is not None and total_size_ratio >= total_size_ratio_trip:
+        triggers.append(
+            f"total-size-ratio: proposed plan is {total_size_ratio:.1f}x "
+            f"the baseline total size (trip threshold: {total_size_ratio_trip}x)"
+        )
+    if epic_added:
+        epic_ids = [
+            it["id"] for it in new_items if _has_epic_label(it.get("labels"))
+        ]
+        triggers.append(
+            f"epic-or-project-label: new item(s) {epic_ids} carry an "
+            "epic/project-class label and should be planned separately"
+        )
+
+    return {
+        "new_items": new_items,
+        "baseline_median_size": baseline_median,
+        "baseline_total_size": baseline_total,
+        "proposed_total_size": proposed_total,
+        "oversize_factor": oversize_factor,
+        "total_size_ratio": total_size_ratio,
+        "epic_or_project_added": epic_added,
+        "triggers": triggers,
+    }
+
+
+def _cli() -> None:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Compute scope-delta metrics for the clarify HITL gate "
+            "(Issue #847). Pass --baseline and --proposed as JSON file "
+            "paths or '-' to read from stdin."
+        )
+    )
+    parser.add_argument("--baseline", required=True,
+                        help="Path to JSON file with baseline items, or '-' for stdin.")
+    parser.add_argument("--proposed", required=True,
+                        help="Path to JSON file with proposed items, or '-' for stdin (mutually exclusive with --baseline -).")
+    parser.add_argument("--oversize-factor-trip", type=float,
+                        default=DEFAULT_OVERSIZE_FACTOR_TRIP,
+                        help=f"Override oversize-factor trip (default {DEFAULT_OVERSIZE_FACTOR_TRIP}).")
+    parser.add_argument("--total-size-ratio-trip", type=float,
+                        default=DEFAULT_TOTAL_SIZE_RATIO_TRIP,
+                        help=f"Override total-size-ratio trip (default {DEFAULT_TOTAL_SIZE_RATIO_TRIP}).")
+    parser.add_argument("--exit-nonzero-on-trip", action="store_true",
+                        help="Exit 1 if any trigger fires.")
+    args = parser.parse_args()
+
+    def _load(path: str) -> List[Any]:
+        if path == "-":
+            return json.loads(sys.stdin.read())
+        with open(path, "r", encoding="utf-8") as fh:
+            return json.load(fh)
+
+    # Copilot PR #860 review: stdin can only be consumed once. Reject the
+    # ambiguous '--baseline - --proposed -' case explicitly so a second
+    # empty read doesn't surface as a confusing JSONDecodeError.
+    if args.baseline == "-" and args.proposed == "-":
+        print(
+            "Error: --baseline and --proposed cannot BOTH be '-'. "
+            "stdin can only be consumed once. Pass at most one of them as "
+            "'-' and the other as a file path.",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+
+    baseline = _load(args.baseline)
+    proposed = _load(args.proposed)
+    if not isinstance(baseline, list) or not isinstance(proposed, list):
+        print("Error: baseline and proposed must each be a JSON array.",
+              file=sys.stderr)
+        sys.exit(2)
+
+    result = compute_scope_delta(
+        baseline, proposed,
+        oversize_factor_trip=args.oversize_factor_trip,
+        total_size_ratio_trip=args.total_size_ratio_trip,
+    )
+    json.dump(result, sys.stdout, indent=2, default=str)
+    sys.stdout.write("\n")
+    if args.exit_nonzero_on_trip and result["triggers"]:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    _cli()

package/scripts/crew/specialist_resolver.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+"""Specialist name resolver for the wicked-garden plugin (Issue #573).
+
+Three naming systems used to collide for the same concept:
+
+1. ``.claude-plugin/specialist.json`` lists the **domains**
+   (``engineering``, ``platform``, ``product``, ``qe``, ``data``,
+   ``jam``, ``agentic``).
+2. The facilitator rubric (``skills/propose-process/SKILL.md`` Step 4)
+   picks bare **role** names like ``requirements-analyst`` or
+   ``solution-architect``.
+3. Actual subagents are keyed ``wicked-garden:{domain}:{role}`` — for
+   example ``wicked-garden:product:requirements-analyst``.
+
+This module is the single source of truth that bridges the three. It
+walks ``agents/**/*.md``, parses the YAML-like frontmatter by simple
+line scanning (stdlib only — hooks can import it), and returns lookup
+maps keyed by both bare role and full subagent_type.
+
+Public API:
+    build_resolver(plugin_root: Path) -> dict
+    resolve_role(role_name: str, resolver: dict) -> tuple[str, str] | tuple[None, None]
+
+The builder is cached per ``plugin_root`` string so repeated calls from
+hooks or scripts do not re-walk the agent tree.
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+import re
+from pathlib import Path
+from typing import Optional, Tuple
+
+# The canonical subagent_type prefix used throughout the plugin. Callers
+# may pass either a bare role (``requirements-analyst``) or the full
+# prefixed form — the resolver handles both.
+_SUBAGENT_PREFIX = "wicked-garden:"
+
+# Frontmatter fences: a leading ``---`` starts the YAML-like block and a
+# trailing ``---`` closes it. We stop at the second fence so nothing in
+# the agent body can accidentally masquerade as frontmatter.
+_FRONTMATTER_FENCE = "---"
+
+# Only these two keys are consumed. We deliberately do not pull in a YAML
+# library — hooks are stdlib-only, and the frontmatter in this repo is
+# always a flat, top-level ``key: value`` pattern for these two fields.
+_RE_NAME = re.compile(r"^name:\s*(.+?)\s*$")
+_RE_SUBAGENT_TYPE = re.compile(r"^subagent_type:\s*(.+?)\s*$")
+
+
+def _parse_agent_frontmatter(path: Path) -> dict:
+    """Return ``{"name": ..., "subagent_type": ...}`` for an agent file.
+
+    Missing keys are omitted from the returned dict (callers treat that
+    as "skip this file"). Unreadable files return ``{}``.
+
+    This is NOT a general YAML parser. It scans line-by-line between the
+    first two ``---`` fences, matching only the two keys we care about.
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return {}
+
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != _FRONTMATTER_FENCE:
+        return {}
+
+    result: dict = {}
+    for line in lines[1:]:
+        stripped = line.strip()
+        if stripped == _FRONTMATTER_FENCE:
+            break
+        name_match = _RE_NAME.match(line)
+        if name_match and "name" not in result:
+            result["name"] = name_match.group(1).strip()
+            continue
+        subagent_match = _RE_SUBAGENT_TYPE.match(line)
+        if subagent_match and "subagent_type" not in result:
+            result["subagent_type"] = subagent_match.group(1).strip()
+            continue
+    return result
+
+
+def _load_domains(plugin_root: Path) -> list:
+    """Return the list of specialist-domain names from specialist.json.
+
+    Returns an empty list on any error so the resolver stays usable even
+    if the manifest is briefly malformed during development.
+    """
+    manifest = plugin_root / ".claude-plugin" / "specialist.json"
+    try:
+        data = json.loads(manifest.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return []
+    names = []
+    for entry in data.get("specialists", []):
+        if isinstance(entry, dict) and entry.get("name"):
+            names.append(entry["name"])
+    return names
+
+
+@functools.lru_cache(maxsize=32)
+def _build_resolver_cached(plugin_root_str: str) -> dict:
+    """Cached worker — keyed on the stringified plugin root."""
+    plugin_root = Path(plugin_root_str)
+    agents_dir = plugin_root / "agents"
+
+    role_to_subagent: dict = {}
+    role_to_domain: dict = {}
+    subagent_to_role: dict = {}
+    warnings: list = []
+
+    if agents_dir.is_dir():
+        # Sort for deterministic collision resolution: earlier (alphabetical
+        # by path) wins, later entries become warnings. ``rglob`` order is
+        # filesystem-dependent on some platforms, so we sort explicitly.
+        for agent_path in sorted(agents_dir.rglob("*.md")):
+            meta = _parse_agent_frontmatter(agent_path)
+            name = meta.get("name")
+            subagent_type = meta.get("subagent_type")
+            if not name or not subagent_type:
+                continue
+            # The domain is the middle segment of wicked-garden:{domain}:{role}
+            # — fall back to the parent directory name if the subagent_type
+            # is malformed (keeps lookup working even for drifted files).
+            if subagent_type.startswith(_SUBAGENT_PREFIX):
+                tail = subagent_type[len(_SUBAGENT_PREFIX):]
+                parts = tail.split(":", 1)
+                domain = parts[0] if len(parts) == 2 else agent_path.parent.name
+            else:
+                domain = agent_path.parent.name
+
+            if name in role_to_subagent:
+                existing = role_to_subagent[name]
+                if existing != subagent_type:
+                    warnings.append(
+                        f"role collision: '{name}' maps to both "
+                        f"'{existing}' and '{subagent_type}' — keeping first"
+                    )
+                # Do not overwrite — first match wins.
+                continue
+
+            role_to_subagent[name] = subagent_type
+            role_to_domain[name] = domain
+            subagent_to_role[subagent_type] = name
+
+    return {
+        "role_to_subagent": role_to_subagent,
+        "role_to_domain": role_to_domain,
+        "subagent_to_role": subagent_to_role,
+        "domains": _load_domains(plugin_root),
+        "warnings": warnings,
+    }
+
+
+def build_resolver(plugin_root: Path) -> dict:
+    """Build the resolver by walking ``agents/**/*.md`` under ``plugin_root``.
+
+    Returns a dict with:
+
+    * ``role_to_subagent`` — bare role -> full ``wicked-garden:{domain}:{role}``
+    * ``role_to_domain`` — bare role -> domain (e.g. ``product``)
+    * ``subagent_to_role`` — full subagent_type -> bare role (reverse map)
+    * ``domains`` — list of specialist-domain names from ``specialist.json``
+    * ``warnings`` — list of human-readable strings for collisions
+
+    The result is cached per plugin_root string, so subsequent calls from
+    the same process are O(1).
+    """
+    return _build_resolver_cached(str(plugin_root))
+
+
+def resolve_role(
+    role_name: str, resolver: dict
+) -> Tuple[Optional[str], Optional[str]]:
+    """Return ``(domain, subagent_type)`` for a role, or ``(None, None)``.
+
+    Accepts either a bare role (``requirements-analyst``) or an already-
+    qualified subagent_type (``wicked-garden:product:requirements-analyst``)
+    — idempotent for the latter.
+
+    Unknown roles return ``(None, None)`` without raising. Callers that
+    want close-match suggestions should drive ``difflib.get_close_matches``
+    off ``resolver["role_to_subagent"].keys()``.
+    """
+    if not role_name or not isinstance(role_name, str):
+        return None, None
+    role_name = role_name.strip()
+    if not role_name:
+        return None, None
+
+    # Full subagent_type path: look up the bare role via the reverse map
+    # and then use the forward maps for the domain. This keeps the return
+    # shape consistent regardless of which form the caller passed in.
+    if role_name.startswith(_SUBAGENT_PREFIX):
+        bare = resolver.get("subagent_to_role", {}).get(role_name)
+        if bare is None:
+            return None, None
+        domain = resolver.get("role_to_domain", {}).get(bare)
+        if domain is None:
+            return None, None
+        return domain, role_name
+
+    subagent_type = resolver.get("role_to_subagent", {}).get(role_name)
+    if subagent_type is None:
+        return None, None
+    domain = resolver.get("role_to_domain", {}).get(role_name)
+    if domain is None:
+        return None, None
+    return domain, subagent_type
+
+
+def clear_cache() -> None:
+    """Drop the module-level cache. Useful for tests that mutate agents/."""
+    _build_resolver_cached.cache_clear()

package/scripts/crew/stack_registry.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+"""stack_registry.py — legacy-stack-class -> dispatch reader for `modernize`.
+
+The §B11/G2 seam: `.claude-plugin/stack-registry.json` is the machine-readable
+dispatch truth (stack -> {blueprint, fixes, transform, validate, status}); this
+module is the thin reader the `modernize` archetype's `discover` phase consults.
+
+The load-bearing honesty contract (garden ETHOS — "never invent a pass"):
+on an UNKNOWN stack, or a stack whose ``status`` is ``planned``/``none``, the
+reader does NOT fabricate a transform. It returns a **capability-gap task** dict
+(for the caller to hand to ``TaskCreate``) and fires a ``wicked.modernize.stack_gap``
+bus event (fire-and-forget, fail-open). Only ``status: wired`` returns a runnable
+dispatch. This mirrors the loom gate's fail-closed posture in dispatch data.
+
+Pure resolution; the only I/O is reading the catalog + a fire-and-forget bus emit.
+
+Usage (library):
+    from stack_registry import resolve_dispatch
+    r = resolve_dispatch("node-legacy-to-modern")
+    # r["status"] == "wired"  -> r["dispatch"] = {blueprint, transform, validate}
+    # else                    -> r["gap_task"] = {title, body, ...}, dispatch is None
+
+Usage (CLI):
+    sh "${CLAUDE_PLUGIN_ROOT}/scripts/_python.sh" \\
+      "${CLAUDE_PLUGIN_ROOT}/scripts/crew/stack_registry.py" \\
+      resolve --stack node-legacy-to-modern
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+_THIS_DIR = Path(__file__).resolve().parent
+_PLUGIN_ROOT = _THIS_DIR.parents[1]
+_REGISTRY_PATH = _PLUGIN_ROOT / ".claude-plugin" / "stack-registry.json"
+
+# The ONLY status that returns a runnable dispatch. Everything else —
+# `planned`, `none`, a typo, or any novel/unknown status — fails closed to a
+# capability-gap (the load-bearing honesty contract: dispatch is wired-only).
+_WIRED = "wired"
+
+
+def load_registry(path: Optional[Path] = None) -> Dict[str, Any]:
+    """Return the stack-registry catalog dict. Raises FileNotFoundError when
+    the registry isn't present — callers must not silently fall back."""
+    return json.loads((path or _REGISTRY_PATH).read_text(encoding="utf-8"))
+
+
+def _gap_task(stack_id: str, label: str, status: str, reason: str) -> Dict[str, Any]:
+    """Build a capability-gap task dict for the caller to hand to TaskCreate.
+    This is what we emit INSTEAD of a fabricated migration."""
+    return {
+        "title": f"modernize: capability gap for stack '{stack_id}' (status={status})",
+        "body": (
+            f"{reason}\n\n"
+            f"The `modernize` archetype refuses to fabricate a transform for a "
+            f"stack it cannot actually handle. Wire a transform + validate for "
+            f"'{label}' in .claude-plugin/stack-registry.json (flip status to "
+            f"'wired'), or route this work to a stack that is already wired."
+        ),
+        "stack": stack_id,
+        "status": status,
+        "kind": "capability-gap",
+    }
+
+
+def resolve_dispatch(
+    stack_id: str,
+    *,
+    registry: Optional[Dict[str, Any]] = None,
+    emit: bool = True,
+) -> Dict[str, Any]:
+    """Resolve a legacy stack class to a dispatch decision.
+
+    Returns a dict ``{stack, status, dispatch, gap_task}`` where exactly one of
+    ``dispatch`` / ``gap_task`` is non-None:
+      - status == "wired"           -> dispatch = {blueprint, fixes, transform, validate}
+      - anything else (unknown /
+        planned / none / a typo /
+        any novel status)           -> gap_task = {...}, dispatch = None, and a
+        ``wicked.modernize.stack_gap`` event is emitted (when ``emit``).
+
+    Dispatch is strictly **wired-only**: a stack whose status is anything other
+    than ``wired`` — including an unrecognised/misspelled status — fails closed
+    to a capability-gap rather than fabricating a migration.
+    """
+    reg = registry if registry is not None else load_registry()
+    stacks = reg.get("stacks", {})
+    entry = stacks.get(stack_id)
+
+    if entry is None:
+        gap = _gap_task(stack_id, stack_id, "unknown",
+                        f"Stack '{stack_id}' is not in the registry.")
+        _emit_gap(gap, emit)
+        return {"stack": stack_id, "status": "unknown", "dispatch": None, "gap_task": gap}
+
+    status = entry.get("status") or "none"
+    if status != _WIRED:
+        # Fail closed: planned/none AND any unknown/typo'd status land here.
+        gap = _gap_task(stack_id, entry.get("label", stack_id), status,
+                        f"Stack '{stack_id}' is registered as status={status} "
+                        f"(only status='{_WIRED}' returns a runnable dispatch).")
+        _emit_gap(gap, emit)
+        return {"stack": stack_id, "status": status, "dispatch": None, "gap_task": gap}
+
+    # status == "wired": return the runnable dispatch. `or default` (not
+    # .get(k, default)) so an explicit JSON null coalesces to the empty
+    # container instead of crashing list(None) / passing None downstream.
+    return {
+        "stack": stack_id,
+        "status": status,
+        "dispatch": {
+            "blueprint": entry.get("blueprint"),
+            "fixes": list(entry.get("fixes") or []),
+            "transform": entry.get("transform") or {},
+            "validate": entry.get("validate") or {},
+        },
+        "gap_task": None,
+    }
+
+
+def _emit_gap(gap_task: Dict[str, Any], emit: bool) -> None:
+    """Fire the stack-gap bus event. Fire-and-forget, fail-open — bus absent
+    must never block the dispatch decision (the gap_task is the source of truth)."""
+    if not emit:
+        return
+    try:
+        scripts_dir = str(_THIS_DIR.parent)  # scripts/ for _bus
+        if scripts_dir not in sys.path:      # guard: don't accumulate dups
+            sys.path.insert(0, scripts_dir)
+        from _bus import emit_event  # type: ignore
+        emit_event(
+            "wicked.modernize.stack_gap",
+            {"stack": gap_task["stack"], "status": gap_task["status"],
+             "title": gap_task["title"]},
+            chain_id=f"modernize.{gap_task['stack']}.{gap_task['status']}.gap",
+        )
+    except Exception:
+        pass  # bus is optional infrastructure
+
+
+def list_stacks(registry: Optional[Dict[str, Any]] = None) -> List[Dict[str, str]]:
+    """Return [{id, label, status}, ...] for roadmap display."""
+    reg = registry if registry is not None else load_registry()
+    return [
+        {"id": sid, "label": s.get("label", sid), "status": s.get("status", "none")}
+        for sid, s in reg.get("stacks", {}).items()
+    ]
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def _cli() -> None:
+    parser = argparse.ArgumentParser(
+        description="modernize stack-registry dispatch reader (fail-closed)."
+    )
+    sub = parser.add_subparsers(dest="action", required=True)
+
+    resolve = sub.add_parser("resolve", help="Resolve a stack to a dispatch decision.")
+    resolve.add_argument("--stack", required=True)
+    resolve.add_argument("--no-emit", action="store_true",
+                         help="Do not emit the stack-gap bus event (testing/dry-run).")
+
+    sub.add_parser("list", help="List registered stacks + statuses (roadmap).")
+
+    args = parser.parse_args()
+
+    if args.action == "resolve":
+        result = resolve_dispatch(args.stack, emit=not args.no_emit)
+        json.dump(result, sys.stdout, indent=2, default=str)
+        sys.stdout.write("\n")
+        # Exit 0 when wired (dispatch ready); exit 3 on a gap (fail-closed,
+        # matching prove.py's "backend down / no-pass" convention).
+        sys.exit(0 if result["dispatch"] is not None else 3)
+
+    if args.action == "list":
+        json.dump(list_stacks(), sys.stdout, indent=2, default=str)
+        sys.stdout.write("\n")
+        return
+
+
+if __name__ == "__main__":
+    _cli()