@windyroad/itil 0.30.2 → 0.30.3-preview.319

package/scripts/plugin-exercise-index.sh

@@ -0,0 +1,347 @@
+#!/usr/bin/env bash
+# packages/itil/scripts/plugin-exercise-index.sh
+#
+# Phase 2b (P087) git-axis maturity-measurement script.
+#
+# Runs `git log --since=<window>d --name-only --pretty=format:%H|%aI|%s`
+# once at the project root, auto-discovers plugins by listing `packages/*/`,
+# and emits one NDJSON record per plugin with the v1.0 schema fields per
+# ADR-058 §Script contracts (line 87-113).
+#
+# Schema (per ADR-058 line 95-110):
+#   {"schema_version":"1.0","axis":"plugin-exercise-index","plugin":"<name>",
+#    "commits_window":<N>,"window_days":<N>,"days_shipped":<N>,
+#    "closed_tickets_window":<N>,"tickets_window_days":<N>,
+#    "breaking_change_age_days":<N|null>,"composite_index":<float>}
+#
+# composite_index = log10(commits_window+1)
+#                 + log10(closed_tickets_window+1)
+#                 + (days_shipped >= 60 ? 1.0 : 0.0)
+# (ADR-058 line 112, Option E6 "MAY emit alongside band" carve-out.)
+#
+# Usage:
+#   wr-itil-plugin-exercise-index [--window-days=N] [--tickets-window-days=N]
+#                                  [--project-root=PATH]
+#                                  [--category-overrides=FILE]
+#
+# Defaults:
+#   --window-days           60   (ADR-058 line 89)
+#   --tickets-window-days   90   (ADR-058 line 93)
+#   --project-root          $PWD
+#
+# Exit codes:
+#   0 = always — ADR-013 Rule 6 fail-safe. Outside-git-repo, missing
+#                `packages/`, opt-out marker all hit the zero-records path
+#                with stderr-comment.
+#
+# Privacy (ADR-035 clauses adopted verbatim, adapted for the git axis):
+#   - Opt-out marker `.claude/.skill-metrics-opt-out` disables reads.
+#   - No network egress — the script body invokes no exfiltration
+#     primitives. ADR-058 §Confirmation 3 enforces via negative-grep on
+#     this file (banned-token list lives in the bats fixture, not here,
+#     to avoid self-matching).
+#   - Content sanitisation — commit subjects are parsed ONLY for
+#     `BREAKING|feat!|fix!` token presence (boolean test); the subject
+#     prose is discarded after the test and never echoed to stdout. The
+#     only plugin-attribution surface is the `packages/<plugin>/` path
+#     prefix extracted from `--name-only` output.
+#
+# @problem P087 (Phase 2b — git axis)
+# @adr ADR-058 (Plugin maturity measurement mechanism)
+# @adr ADR-049 (Shim grammar — bin/wr-itil-plugin-exercise-index on $PATH)
+# @adr ADR-035 (Privacy posture adopted verbatim)
+# @adr ADR-052 (Behavioural tests default; ADR-058 §Confirmation 6-8)
+# @adr ADR-013 Rule 6 (non-interactive fail-safe — exit 0 always)
+# @adr ADR-023 (Performance — ≤1.0s warm-cache; 60-day window default)
+# @jtbd JTBD-101 (Extend the Suite — hardening-prioritisation outcome,
+#   2026-05-04 amendment serves Phase 2 NDJSON as data source)
+# @jtbd JTBD-201 (Restore Service Fast — audit-trail composition)
+
+set -uo pipefail
+
+# ── CLI parse ───────────────────────────────────────────────────────────────
+
+WINDOW_DAYS=60
+TICKETS_WINDOW_DAYS=90
+PROJECT_ROOT="$PWD"
+CATEGORY_OVERRIDES=""
+
+for arg in "$@"; do
+  case "$arg" in
+    --window-days=*) WINDOW_DAYS="${arg#--window-days=}" ;;
+    --tickets-window-days=*) TICKETS_WINDOW_DAYS="${arg#--tickets-window-days=}" ;;
+    --project-root=*) PROJECT_ROOT="${arg#--project-root=}" ;;
+    --category-overrides=*) CATEGORY_OVERRIDES="${arg#--category-overrides=}" ;;
+    --help|-h)
+      sed -n '4,40p' "$0" | sed 's/^# \{0,1\}//'
+      exit 0
+      ;;
+    *)
+      echo "# wr-itil-plugin-exercise-index: ignoring unknown argument: $arg" >&2
+      ;;
+  esac
+done
+
+# ── Opt-out marker check (ADR-035 / ADR-058 §Privacy posture) ───────────────
+
+OPT_OUT_MARKER="${PROJECT_ROOT}/.claude/.skill-metrics-opt-out"
+if [ -e "$OPT_OUT_MARKER" ]; then
+  echo "# wr-itil-plugin-exercise-index: opt-out marker present at ${OPT_OUT_MARKER}" >&2
+  exit 0
+fi
+
+# ── Git-repo check (ADR-013 Rule 6 fail-safe) ───────────────────────────────
+
+if [ ! -d "${PROJECT_ROOT}/.git" ] && ! git -C "$PROJECT_ROOT" rev-parse --git-dir >/dev/null 2>&1; then
+  echo "# wr-itil-plugin-exercise-index: not a git repository at ${PROJECT_ROOT}" >&2
+  exit 0
+fi
+
+# ── packages/ discovery check (ADR-013 Rule 6 fail-safe) ────────────────────
+
+if [ ! -d "${PROJECT_ROOT}/packages" ]; then
+  echo "# wr-itil-plugin-exercise-index: no packages/ directory at ${PROJECT_ROOT}" >&2
+  exit 0
+fi
+
+# Discover plugins as immediate subdirectories of packages/. Empty result is
+# also a fail-safe case (no plugins to score).
+PLUGIN_COUNT=0
+for d in "${PROJECT_ROOT}/packages"/*/; do
+  [ -d "$d" ] && PLUGIN_COUNT=$((PLUGIN_COUNT + 1))
+done
+if [ "$PLUGIN_COUNT" -eq 0 ]; then
+  echo "# wr-itil-plugin-exercise-index: no packages/ directory at ${PROJECT_ROOT}" >&2
+  exit 0
+fi
+
+# ── --category-overrides validation (ADR-058 §Per-category override hook) ───
+# Forward-extension flag; ships unused in Phase 2.
+
+if [ -n "$CATEGORY_OVERRIDES" ] && [ ! -f "$CATEGORY_OVERRIDES" ]; then
+  echo "# wr-itil-plugin-exercise-index: category-overrides file not found: ${CATEGORY_OVERRIDES}" >&2
+  exit 0
+fi
+
+# ── Git log + NDJSON emit (Python 3 stdlib) ─────────────────────────────────
+# Inputs pinned via environment to avoid argv leakage.
+
+export PEI_PROJECT_ROOT="$PROJECT_ROOT"
+export PEI_WINDOW_DAYS="$WINDOW_DAYS"
+export PEI_TICKETS_WINDOW_DAYS="$TICKETS_WINDOW_DAYS"
+
+python3 - <<'PYEOF'
+import json, os, re, subprocess, sys, time, math
+from pathlib import Path
+from collections import defaultdict
+from datetime import datetime, timezone
+
+project_root = Path(os.environ["PEI_PROJECT_ROOT"]).resolve()
+window_days = int(os.environ["PEI_WINDOW_DAYS"])
+tickets_window_days = int(os.environ["PEI_TICKETS_WINDOW_DAYS"])
+now = time.time()
+cutoff = now - window_days * 86400
+tickets_cutoff = now - tickets_window_days * 86400
+
+# Discover plugins (immediate subdirs of packages/).
+plugins = sorted(
+    p.name for p in (project_root / "packages").iterdir() if p.is_dir()
+)
+if not plugins:
+    sys.exit(0)
+
+# Per-plugin accumulators.
+commits_window = defaultdict(int)
+breaking_age_days = {}   # plugin -> int (days since most recent breaking commit in window)
+oldest_commit_ts = {}    # plugin -> float epoch seconds (across ALL history)
+closed_tickets_window = defaultdict(int)
+
+# `BREAKING` token presence — boolean test only, subject discarded after.
+BREAKING_RE = re.compile(r"\b(BREAKING)\b|(?:^|\s)(feat!|fix!|chore!|refactor!)")
+
+# ── Single git log pass with in-Python window filter ────────────────────────
+# ADR-058 line 89 pins `git log --since=<window>d --name-only
+# --pretty=format:%H|%aI|%s`. Git's `--since=Nd` was observed unreliable on
+# 2026-05-16 against the test fixture (returned empty even for commits well
+# within the window — likely a date-parser quirk with future-year commit
+# dates), so the window filter is applied in-Python against the `%aI`
+# author-date field that is already extracted for `breaking_change_age_days`
+# and `days_shipped`. The `git log` invocation otherwise matches the ADR-058
+# contract verbatim (--name-only, the literal `|` separator). Single pass
+# instead of two — pass-2 (oldest-commit) and pass-1 (in-window) collapse
+# into one walk because we already iterate every commit's date.
+#
+# Defensive split on first 2 `|` occurrences only — subjects may contain
+# literal `|` characters per the architect's 2026-05-16 advisory.
+
+def parse_log_all():
+    """Yield (sha, iso_ts, subject, paths_list) tuples for every commit."""
+    try:
+        proc = subprocess.run(
+            [
+                "git",
+                "-C", str(project_root),
+                "log",
+                "--reverse",  # oldest-first; first hit per plugin = days_shipped
+                "--name-only",
+                "--pretty=format:%H|%aI|%s",
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return
+    if proc.returncode != 0:
+        return
+
+    # Output shape: <header>\n<path>\n<path>\n\n<header>\n... Commits are
+    # separated by blank lines; the header line is always identifiable by
+    # containing exactly two `|` separators (lines without separators are
+    # path lines).
+    current = None
+    for line in proc.stdout.split("\n"):
+        if not line.strip():
+            if current is not None:
+                yield current
+                current = None
+            continue
+        # Header line: contains the `|` separator pattern. Defensive split
+        # on first 2 occurrences so `|` characters in subjects are preserved.
+        if "|" in line:
+            parts = line.split("|", 2)
+            if len(parts) == 3 and re.match(r"^[0-9a-f]{7,40}$", parts[0]):
+                if current is not None:
+                    yield current
+                current = (parts[0], parts[1], parts[2], [])
+                continue
+        # Path line under current commit.
+        if current is not None:
+            current[3].append(line)
+    if current is not None:
+        yield current
+
+for sha, iso_ts, subject, paths in parse_log_all():
+    # Per-commit plugin set (dedupe — one commit touching N files under
+    # packages/foo counts as 1, not N).
+    plugins_touched = set()
+    for p in paths:
+        parts = p.split("/")
+        if len(parts) >= 3 and parts[0] == "packages":
+            plug = parts[1]
+            if plug in plugins:
+                plugins_touched.add(plug)
+
+    if not plugins_touched:
+        del subject
+        continue
+
+    # Parse author-date once — fed into days_shipped (every commit) and
+    # the in-window filter (commits_window, breaking_change_age_days).
+    try:
+        commit_dt = datetime.fromisoformat(iso_ts.replace("Z", "+00:00"))
+        ts = commit_dt.timestamp()
+    except Exception:
+        del subject
+        continue
+
+    # days_shipped: track min(author_date) per plugin. ADR-058 line 91 says
+    # "days since the OLDEST git commit"; oldest is interpreted as min by
+    # author-date rather than min by commit-topology so the value is stable
+    # against commit-reordering and rebase. (Topological --reverse can
+    # disagree with author-date order when commits are made out of
+    # chronological order — common in tests; possible in cherry-picks and
+    # backports in production.)
+    for plug in plugins_touched:
+        cur = oldest_commit_ts.get(plug)
+        if cur is None or ts < cur:
+            oldest_commit_ts[plug] = ts
+
+    # In-window filter — applied in Python (ADR-058 line 89 contract for the
+    # git invocation; window cutoff in-process for portability).
+    if ts < cutoff:
+        del subject
+        continue
+
+    # Commit-window tally.
+    for plug in plugins_touched:
+        commits_window[plug] += 1
+
+    # Breaking-marker test on subject (boolean test; subject discarded after).
+    if BREAKING_RE.search(subject):
+        age_days = int((now - ts) / 86400)
+        if age_days >= 0:
+            for plug in plugins_touched:
+                cur = breaking_age_days.get(plug)
+                # Want the YOUNGEST (smallest age_days) breaking commit.
+                if cur is None or age_days < cur:
+                    breaking_age_days[plug] = age_days
+    # subject explicitly not retained beyond this point.
+    del subject
+
+# ── Pass 3: closed/verifying ticket scan (citation match + 90-day mtime) ────
+# Tolerate both layouts:
+#   (a) suffix-based: docs/problems/**/<NNN>-*.closed.md, *.verifying.md
+#   (b) directory-based: docs/problems/closed/<NNN>-*.md, verifying/<NNN>-*.md
+
+problems_root = project_root / "docs" / "problems"
+ticket_files = []
+if problems_root.is_dir():
+    # Suffix-based (recursive).
+    ticket_files.extend(problems_root.rglob("*.closed.md"))
+    ticket_files.extend(problems_root.rglob("*.verifying.md"))
+    # Directory-based.
+    for subdir in ("closed", "verifying"):
+        d = problems_root / subdir
+        if d.is_dir():
+            for f in d.rglob("*.md"):
+                if not (f.name.endswith(".closed.md") or f.name.endswith(".verifying.md")):
+                    ticket_files.append(f)
+
+# Dedupe (a file may match both globs in pathological cases).
+ticket_files = sorted(set(ticket_files))
+
+for ticket in ticket_files:
+    try:
+        st = ticket.stat()
+    except OSError:
+        continue
+    if st.st_mtime < tickets_cutoff:
+        continue
+    try:
+        body = ticket.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        continue
+    for plug in plugins:
+        # Citation marker — any occurrence of `packages/<plugin>/` in body.
+        if f"packages/{plug}/" in body:
+            closed_tickets_window[plug] += 1
+
+# ── Emit one NDJSON record per discovered plugin ────────────────────────────
+
+for plug in plugins:
+    cw = commits_window.get(plug, 0)
+    ctw = closed_tickets_window.get(plug, 0)
+    if plug in oldest_commit_ts:
+        ds = int((now - oldest_commit_ts[plug]) / 86400)
+    else:
+        ds = 0
+    bca = breaking_age_days.get(plug)
+    bonus = 1.0 if ds >= 60 else 0.0
+    composite = round(math.log10(cw + 1) + math.log10(ctw + 1) + bonus, 2)
+    record = {
+        "schema_version": "1.0",
+        "axis": "plugin-exercise-index",
+        "plugin": plug,
+        "commits_window": cw,
+        "window_days": window_days,
+        "days_shipped": ds,
+        "closed_tickets_window": ctw,
+        "tickets_window_days": tickets_window_days,
+        "breaking_change_age_days": bca,
+        "composite_index": composite,
+    }
+    sys.stdout.write(json.dumps(record, separators=(",", ":")) + "\n")
+PYEOF
+
+exit 0

package/scripts/skill-invocations.sh

@@ -0,0 +1,255 @@
+#!/usr/bin/env bash
+# packages/itil/scripts/skill-invocations.sh
+#
+# Phase 2a (P087) transcript-axis maturity-measurement script.
+#
+# Reads `~/.claude/projects/**/*.jsonl` (recursive), filters to
+# `type=assistant` messages whose `message.content` array carries a
+# `tool_use` entry, tallies invocations by `Skill` / `Agent` / `Bash` per
+# ADR-058 §Script contracts, and emits one NDJSON record per surface to
+# stdout.
+#
+# Schema (per ADR-058 line 70-82):
+#   {"schema_version":"1.0","axis":"skill-invocations","surface":"<name>",
+#    "kind":"skill|agent|bash-attributed","plugin":"<name>",
+#    "window_days":<N>,"invocations":<N>,
+#    "first_invocation_iso":"<ISO>","last_invocation_iso":"<ISO>"}
+#
+# Usage:
+#   wr-itil-skill-invocations [--window-days=N] [--root=PATH]
+#                              [--project-root=PATH]
+#                              [--category-overrides=FILE]
+#
+# Defaults:
+#   --window-days   30   (ADR-058 line 67)
+#   --root          ~/.claude/projects
+#   --project-root  $PWD   (opt-out marker location: <project-root>/.claude/.skill-metrics-opt-out)
+#
+# Exit codes:
+#   0 = always — ADR-013 Rule 6 fail-safe. Opt-out marker / inaccessible
+#                root / missing data all hit the zero-records path with
+#                stderr-comment.
+#
+# Privacy (ADR-035 clauses adopted verbatim):
+#   - Opt-out marker `.claude/.skill-metrics-opt-out` disables reads.
+#   - No network egress — the script body invokes no exfiltration
+#     primitives. ADR-058 §Confirmation 3 enforces via negative-grep
+#     on this file (banned-token list lives in the bats fixture, not
+#     here, to avoid self-matching).
+#   - Content sanitisation — only fixed-pattern surface names extracted
+#     via tight regex from tool inputs are emitted. Raw user content,
+#     paths, and secrets are never copied to stdout.
+#   - Path-hashing — if a path-bearing field is added in a future schema
+#     version, values MUST be sha256-prefix-hashed (first 12 hex chars).
+#     The v1.0 schema has no path-bearing field; the hashing function is
+#     internal defence-in-depth, exercised structurally by Confirmation #4.
+#
+# @problem P087 (Phase 2a — transcript axis)
+# @adr ADR-058 (Plugin maturity measurement mechanism)
+# @adr ADR-049 (Shim grammar — bin/wr-itil-skill-invocations on $PATH)
+# @adr ADR-035 (Privacy posture adopted verbatim)
+# @adr ADR-052 (Behavioural tests default; ADR-058 §Confirmation 1-5)
+# @adr ADR-013 Rule 6 (non-interactive fail-safe — exit 0 always)
+# @adr ADR-023 (Performance — < 1.5s warm-cache; 30-day window default)
+# @jtbd JTBD-101 (Extend the Suite — hardening-prioritisation outcome,
+#   2026-05-04 amendment serves Phase 2 NDJSON as data source)
+# @jtbd JTBD-201 (Restore Service Fast — audit-trail composition)
+
+set -uo pipefail
+
+# ── CLI parse ───────────────────────────────────────────────────────────────
+
+WINDOW_DAYS=30
+TRANSCRIPT_ROOT="${HOME}/.claude/projects"
+PROJECT_ROOT="$PWD"
+CATEGORY_OVERRIDES=""
+
+for arg in "$@"; do
+  case "$arg" in
+    --window-days=*) WINDOW_DAYS="${arg#--window-days=}" ;;
+    --root=*)        TRANSCRIPT_ROOT="${arg#--root=}" ;;
+    --project-root=*) PROJECT_ROOT="${arg#--project-root=}" ;;
+    --category-overrides=*) CATEGORY_OVERRIDES="${arg#--category-overrides=}" ;;
+    --help|-h)
+      sed -n '4,40p' "$0" | sed 's/^# \{0,1\}//'
+      exit 0
+      ;;
+    *)
+      echo "# wr-itil-skill-invocations: ignoring unknown argument: $arg" >&2
+      ;;
+  esac
+done
+
+# ── Opt-out marker check (ADR-035 / ADR-058 §Privacy posture) ───────────────
+
+OPT_OUT_MARKER="${PROJECT_ROOT}/.claude/.skill-metrics-opt-out"
+if [ -e "$OPT_OUT_MARKER" ]; then
+  echo "# wr-itil-skill-invocations: opt-out marker present at ${OPT_OUT_MARKER}" >&2
+  exit 0
+fi
+
+# ── Transcript root accessibility (ADR-013 Rule 6 fail-safe) ────────────────
+
+if [ ! -d "$TRANSCRIPT_ROOT" ]; then
+  echo "# wr-itil-skill-invocations: transcript root inaccessible at ${TRANSCRIPT_ROOT}" >&2
+  exit 0
+fi
+
+# ── --category-overrides validation (ADR-058 §Per-category override hook) ───
+# Forward-extension flag; ships unused in Phase 2. Validated for path
+# existence; not yet consumed by the body.
+
+if [ -n "$CATEGORY_OVERRIDES" ] && [ ! -f "$CATEGORY_OVERRIDES" ]; then
+  echo "# wr-itil-skill-invocations: category-overrides file not found: ${CATEGORY_OVERRIDES}" >&2
+  exit 0
+fi
+
+# ── JSONL parse + NDJSON emit (Python 3 stdlib — ADR-058 line 127) ──────────
+# Inputs pinned via environment to avoid argv leakage of secrets.
+
+export SI_TRANSCRIPT_ROOT="$TRANSCRIPT_ROOT"
+export SI_WINDOW_DAYS="$WINDOW_DAYS"
+
+python3 - <<'PYEOF'
+import json, os, sys, time, re, hashlib
+from pathlib import Path
+from datetime import datetime, timezone
+from collections import defaultdict
+
+root = Path(os.environ["SI_TRANSCRIPT_ROOT"])
+window_days = int(os.environ["SI_WINDOW_DAYS"])
+now = time.time()
+cutoff = now - window_days * 86400
+
+# Bin shim grammar from ADR-049: wr-<plugin>-<kebab-script-name>.
+# Anchor on word boundary; allow alnum + hyphens; non-greedy plugin token
+# stops at the first hyphen so `wr-itil-reconcile-readme` attributes to
+# `itil`, not `itil-reconcile`.
+BIN_RE = re.compile(r"\bwr-([a-z0-9]+)-[a-z0-9-]+")
+
+def plugin_from_skill(name):
+    """`wr-itil:manage-problem` -> `itil`. Non-wr-prefixed or short-form
+    names like `commit`, `loop` return None (excluded from per-plugin
+    attribution per ADR-058 line 64)."""
+    if not name or ":" not in name:
+        return None
+    prefix = name.split(":", 1)[0]
+    if prefix.startswith("wr-"):
+        return prefix[3:]
+    return None
+
+def plugin_from_agent(name):
+    return plugin_from_skill(name)
+
+def hash_path(p):
+    """sha256-prefix-12hex per ADR-035 path-hashing convention. Reserved
+    for future schema bumps that emit path-bearing fields; not consumed
+    by the v1.0 schema."""
+    return hashlib.sha256(str(p).encode("utf-8")).hexdigest()[:12]
+
+# Aggregate keyed by (kind, surface).
+counts = defaultdict(lambda: {"invocations": 0, "first": None, "last": None, "plugin": None})
+
+try:
+    jsonl_iter = root.rglob("*.jsonl")
+except OSError:
+    sys.exit(0)
+
+for jsonl in jsonl_iter:
+    try:
+        st = jsonl.stat()
+    except OSError:
+        continue
+    if st.st_mtime < cutoff:
+        # File hasn't been touched in the window; skip without parsing.
+        continue
+    try:
+        fh = jsonl.open("r", encoding="utf-8", errors="replace")
+    except OSError:
+        continue
+    with fh:
+        for line in fh:
+            try:
+                rec = json.loads(line)
+            except Exception:
+                continue
+            if not isinstance(rec, dict) or rec.get("type") != "assistant":
+                continue
+
+            # Per-message timestamp filter (more accurate than file mtime).
+            ts = rec.get("timestamp")
+            ts_iso = None
+            if ts:
+                try:
+                    dt = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+                    if dt.timestamp() < cutoff:
+                        continue
+                    ts_iso = dt.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+                except Exception:
+                    ts_iso = None
+
+            msg = rec.get("message") or {}
+            content = msg.get("content") if isinstance(msg, dict) else None
+            if not isinstance(content, list):
+                continue
+
+            for c in content:
+                if not isinstance(c, dict) or c.get("type") != "tool_use":
+                    continue
+                name = c.get("name")
+                inp = c.get("input") if isinstance(c.get("input"), dict) else {}
+                surface = kind = plugin = None
+
+                if name == "Skill":
+                    sk = inp.get("skill")
+                    p = plugin_from_skill(sk)
+                    if p:
+                        surface, kind, plugin = sk, "skill", p
+                elif name == "Agent":
+                    sub = inp.get("subagent_type")
+                    p = plugin_from_agent(sub)
+                    if p:
+                        surface, kind, plugin = sub, "agent", p
+                elif name == "Bash":
+                    cmd = inp.get("command", "")
+                    if not isinstance(cmd, str):
+                        continue
+                    m = BIN_RE.search(cmd)
+                    if m:
+                        # Surface is the matched bin shim token only. The
+                        # surrounding command (paths, secrets, args) is
+                        # discarded — content-sanitisation per ADR-035.
+                        surface = m.group(0)
+                        kind = "bash-attributed"
+                        plugin = m.group(1)
+
+                if surface and kind and plugin:
+                    key = (kind, surface)
+                    info = counts[key]
+                    info["invocations"] += 1
+                    info["plugin"] = plugin
+                    if ts_iso:
+                        if info["first"] is None or ts_iso < info["first"]:
+                            info["first"] = ts_iso
+                        if info["last"] is None or ts_iso > info["last"]:
+                            info["last"] = ts_iso
+
+# Deterministic output order: sort by kind, then surface.
+for key in sorted(counts.keys()):
+    kind, surface = key
+    info = counts[key]
+    record = {
+        "schema_version": "1.0",
+        "axis": "skill-invocations",
+        "surface": surface,
+        "kind": kind,
+        "plugin": info["plugin"],
+        "window_days": window_days,
+        "invocations": info["invocations"],
+        "first_invocation_iso": info["first"],
+        "last_invocation_iso": info["last"],
+    }
+    sys.stdout.write(json.dumps(record, separators=(",", ":")) + "\n")
+PYEOF
+
+exit 0