hstack 0.7.1 → 0.17.0

package/template/scripts/telemetry/insights/contract_drift.py

@@ -1,137 +0,0 @@
-"""Contract-drift insights: module-spec staleness, ADR supersession lag,
-tech-debt half-life by exit path."""
-
-from __future__ import annotations
-
-from collections import defaultdict
-from datetime import date, datetime
-
-
-def compute(commits: list[dict], changes: dict, tech_debt: list[dict],
-            adrs: list[dict], module_specs: list[dict]) -> dict:
-    return {
-        "module_spec_staleness": _module_staleness(module_specs, commits),
-        "adr_supersession_lag": _adr_lag(adrs),
-        "tech_debt_half_life": _td_half_life(tech_debt),
-    }
-
-
-def _parse_date(value) -> date | None:
-    if value is None:
-        return None
-    if isinstance(value, date):
-        return value
-    if isinstance(value, datetime):
-        return value.date()
-    if isinstance(value, str):
-        try:
-            return datetime.fromisoformat(value).date()
-        except ValueError:
-            return None
-    return None
-
-
-def _module_staleness(module_specs: list[dict], commits: list[dict]) -> dict:
-    """Per module: spec status + count of recent commits touching that module's
-    files. A `needs-refresh` module with high recent activity is the drift
-    pathology."""
-    # Count commits touching each module dir.
-    module_activity: dict[str, int] = defaultdict(int)
-    for c in commits:
-        for f in c.get("files", []):
-            for ms in module_specs:
-                module = ms["module"]
-                # Use a heuristic — count when a commit touches files outside
-                # hstack/ in directories named like the module. Imperfect, but
-                # avoids requiring a module→file-path map.
-                if module in f and not f.startswith("hstack/"):
-                    module_activity[module] += 1
-                    break
-    rows = []
-    for ms in module_specs:
-        status = ms["fm"].get("status", "-")
-        updated = _parse_date(ms["fm"].get("updated"))
-        rows.append({
-            "module": ms["module"],
-            "status": status,
-            "updated": str(updated) if updated else "-",
-            "recent_commits_touching_module": module_activity.get(ms["module"], 0),
-            "drift_flag": status == "needs-refresh" and module_activity.get(ms["module"], 0) > 0,
-        })
-    rows.sort(key=lambda r: -r["recent_commits_touching_module"])
-    return {"rows": rows}
-
-
-def _adr_lag(adrs: list[dict]) -> dict:
-    """Among ADRs at `superseded` status, how long they lived before the
-    superseding ADR landed."""
-    by_id = {a["fm"].get("id") or a["path"].stem: a for a in adrs}
-    lags = []
-    for a in adrs:
-        status = a["fm"].get("status")
-        if status != "superseded":
-            continue
-        sup = a["fm"].get("superseded-by")
-        a_created = _parse_date(a["fm"].get("created"))
-        if not sup or not a_created:
-            continue
-        sup_adr = by_id.get(sup)
-        if not sup_adr:
-            continue
-        sup_created = _parse_date(sup_adr["fm"].get("created"))
-        if not sup_created:
-            continue
-        days = (sup_created - a_created).days
-        lags.append({
-            "adr": a["fm"].get("id"),
-            "superseded_by": sup,
-            "lag_days": days,
-        })
-    return {"rows": lags}
-
-
-def _td_half_life(tech_debt: list[dict]) -> dict:
-    """For each TD, compute days from created → exit (resolved | wontfix |
-    stale-no-longer-reproducible). Surface by exit-path histogram + per-TD
-    rows."""
-    today = date.today()
-    by_exit = defaultdict(list)
-    rows = []
-    for td in tech_debt:
-        fm = td["fm"]
-        status = fm.get("status")
-        created = _parse_date(fm.get("created"))
-        if not created:
-            continue
-        exit_date = None
-        if status == "resolved":
-            exit_date = _parse_date(fm.get("updated"))
-        elif status == "wontfix":
-            exit_date = _parse_date(fm.get("updated"))
-        elif status == "stale-no-longer-reproducible":
-            exit_date = _parse_date(fm.get("stale-verified-at") or fm.get("updated"))
-        if exit_date:
-            days = (exit_date - created).days
-            by_exit[status].append(days)
-        elif status == "open" or status == "in-progress":
-            days = (today - created).days
-            by_exit[f"{status} (still open)"].append(days)
-            exit_date = None
-        rows.append({
-            "id": fm.get("id"),
-            "status": status,
-            "created": str(created),
-            "days_to_exit": (exit_date - created).days if exit_date else (today - created).days,
-            "exit_path": status if exit_date else None,
-        })
-    summary = {}
-    for exit_path, days_list in by_exit.items():
-        if not days_list:
-            continue
-        days_list.sort()
-        summary[exit_path] = {
-            "count": len(days_list),
-            "median_days": days_list[len(days_list) // 2],
-            "max_days": max(days_list),
-        }
-    return {"summary": summary, "rows": rows}

package/template/scripts/telemetry/insights/kernel_fit.py

@@ -1,438 +0,0 @@
-"""Kernel-fit insights: patterns suggesting the kernel itself needs revision.
-
-This module is the detection layer of the kernel-fit closed-loop system. It
-pattern-matches across shipped artifacts and emits evidence rows; an LLM
-subagent (`kernel-fit-analyst`) then synthesizes findings from these rows.
-
-See ADR-0004 for the full design rationale and `template/CLAUDE.md` § How
-hstack improves itself for the loop contract.
-
-Three starter patterns:
-
-- KF-P1 — `category-a-claim-spans-production-paths`: changes flagged
-  `internal-tooling: true` (Category A — engineering-only) whose `in-scope`
-  touches production-code paths AND whose `enables` array is empty.
-  Under the post-PR-#5 schema (`enables` ↔ `enabled-by`, SP-13/SP-14),
-  this is the engineer mis-classifying what should be Category B
-  (foundational prerequisite) as Category A. The in-scope-overlap
-  heuristic surfaces candidate downstream consumers as evidence.
-- KF-P2 — `halt-reason-cluster-uncovered-by-enum`: halt sentinels with
-  `reason=other` whose surrounding prose clusters above the Jaccard
-  threshold, suggesting the enum is missing a case.
-- KF-P3 — `skill-precondition-violated-and-recoverable`: adversarial-review
-  spec-compliance findings whose resolution commit messages reveal a missed
-  upstream gate (the ADR-0002 pattern).
-
-Detection is pure read — no writes. Output is a dict consumed by the
-analyst subagent via the scan Skill orchestration.
-"""
-
-from __future__ import annotations
-
-import re
-from collections import defaultdict
-from pathlib import Path
-
-from telemetry.parsers import frontmatter as fm_parser
-from telemetry.parsers.bodies import parse_findings_section, split_sections
-
-
-# File-path prefixes that count as "internal-only" for KF-P1 classification.
-# A change whose in-scope is entirely under these prefixes is genuine
-# Category A (true internal tooling). Anything outside is candidate Category B
-# (foundational prerequisite — production code with deferred user value).
-INTERNAL_ONLY_PREFIXES = (
-    "hstack/",
-    "scripts/",
-    ".github/",
-    "template/",
-    ".claude/",
-    "docs/",
-    "ci/",
-)
-
-# Kernel-rule keywords scanned in resolution commits for KF-P3. A
-# `spec-compliance` adversarial finding whose resolving commit mentions any
-# of these is a candidate "Skill precondition should have halted earlier"
-# signal (the ADR-0002 missing-gate pattern).
-KERNEL_GATE_KEYWORDS = re.compile(
-    r"\b(precondition|missed\s+gate|should\s+have\s+halted|upstream|"
-    r"ready-for-implementation|ready-for-review|ready-to-ship|status\s+gate)\b",
-    re.IGNORECASE,
-)
-
-# Jaccard threshold for KF-P2 cluster membership. Tunable; documented in the
-# plan as a starting value. Lower → more clustering (more cluster merges,
-# fewer clusters). Higher → tighter clusters (fewer merges, more clusters).
-JACCARD_THRESHOLD = 0.6
-
-# Minimum cluster size for KF-P2 to fire. Smaller than this is noise.
-MIN_CLUSTER_SIZE = 3
-
-# Minimum candidate-row count for KF-P1 to fire. A single Category-B mislabel
-# is noise; recurrence is signal.
-KF_P1_MIN_ROWS = 2
-
-
-def compute(commits: list[dict], changes: dict, tech_debt: list[dict],
-            adrs: list[dict], module_specs: list[dict],
-            session_rows: list[dict], findings_dir: Path | None) -> dict:
-    """Run all kernel-fit detection patterns.
-
-    `findings_dir` may be `None` or non-existent on first run — the dedup
-    cross-reference returns an empty index in that case, and the analyst
-    treats every fired pattern as net-new.
-    """
-    existing = _load_existing_findings(findings_dir)
-    return {
-        "existing_open_findings_by_pattern": existing,
-        "kf_p1_category_a_claim_spans_production_paths": _kf_p1(changes, commits),
-        "kf_p2_halt_reason_cluster_uncovered_by_enum": _kf_p2(commits, session_rows),
-        "kf_p3_skill_precondition_violated_and_recoverable": _kf_p3(changes, commits),
-    }
-
-
-# ---------------- existing-findings index ----------------
-
-def _load_existing_findings(findings_dir: Path | None) -> dict:
-    """Read all KF-NNNN-*.md files in findings_dir and build an index of open
-    findings keyed by pattern. Used by the analyst for dedup / supersession
-    decisions. Tolerant of missing directory."""
-    out: dict[str, list[str]] = defaultdict(list)
-    if findings_dir is None or not findings_dir.is_dir():
-        return dict(out)
-    for path in sorted(findings_dir.glob("KF-*.md")):
-        parsed = fm_parser.read_artifact(path)
-        if parsed is None:
-            continue
-        fm, _body = parsed
-        status = fm.get("status")
-        pattern = fm.get("pattern")
-        kid = fm.get("id") or path.stem
-        if not pattern:
-            continue
-        # Only "open" and "acknowledged" findings count for dedup; promoted /
-        # dismissed / superseded / archived are terminal and do not suppress
-        # re-detection.
-        if status in ("open", "acknowledged"):
-            out[pattern].append(kid)
-    return dict(out)
-
-
-# ---------------- KF-P1 ----------------
-
-def _classify_inscope_paths(in_scope: list) -> tuple[list[str], list[str]]:
-    """Partition an in-scope list into (internal_only_paths, production_paths)."""
-    internal_only: list[str] = []
-    production: list[str] = []
-    for entry in in_scope or []:
-        if not isinstance(entry, str):
-            continue
-        path = entry.strip()
-        if not path:
-            continue
-        # Normalize leading "./" and any glob suffixes for prefix checking.
-        normalized = path[2:] if path.startswith("./") else path
-        if any(normalized.startswith(p) for p in INTERNAL_ONLY_PREFIXES):
-            internal_only.append(path)
-        else:
-            production.append(path)
-    return internal_only, production
-
-
-def _forward_consumers(this_change_id: str, this_in_scope: list[str],
-                       changes: dict, commits: list[dict]) -> list[str]:
-    """Return change-ids of later changes whose in-scope OR whose commit
-    file-lists overlap with this change's in-scope production paths."""
-    if not this_in_scope:
-        return []
-    # Build set of production-path-prefixes for cheap overlap checks. We treat
-    # each in-scope entry as a prefix; this is forgiving (catches edits inside
-    # subdirs) and matches what `internal-tooling: true` plumbing changes
-    # typically introduce (a dir of new types or a new module).
-    prefixes = {(p[2:] if p.startswith("./") else p).rstrip("/*") for p in this_in_scope}
-
-    consumers: set[str] = set()
-
-    # (1) Other change-specs whose in-scope overlaps.
-    for other_id, arts in changes.items():
-        if other_id == this_change_id:
-            continue
-        spec = arts.get("change-spec") or arts.get("spec")
-        if not spec:
-            continue
-        other_in_scope = spec["fm"].get("in-scope") or []
-        for entry in other_in_scope:
-            if not isinstance(entry, str):
-                continue
-            normalized = entry[2:] if entry.startswith("./") else entry
-            if any(normalized.startswith(p) for p in prefixes):
-                consumers.add(other_id)
-                break
-
-    # (2) Commits whose file-list touches our production paths AND whose
-    # artifact_id is a different change-spec (avoids self-attribution).
-    for c in commits:
-        cid = c.get("artifact_id")
-        if not cid or cid == this_change_id:
-            continue
-        for f in c.get("files", []):
-            normalized = f[2:] if f.startswith("./") else f
-            if any(normalized.startswith(p) for p in prefixes):
-                consumers.add(cid)
-                break
-
-    return sorted(consumers)
-
-
-def _kf_p1(changes: dict, commits: list[dict]) -> dict:
-    """KF-P1 — Category A (`internal-tooling: true`) claims whose `in-scope`
-    spans production-code paths AND whose `enables` array is empty. Under
-    the post-PR-#5 schema, this is the engineer mis-classifying what should
-    be Category B (foundational prerequisite) as Category A. SP-13 makes
-    A and B mutually exclusive at the validator level; KF-P1 catches the
-    case the validator cannot — claiming A when the in-scope reveals B.
-    Fires on >= KF_P1_MIN_ROWS candidate rows.
-    """
-    rows: list[dict] = []
-    for cid, arts in changes.items():
-        spec = arts.get("change-spec") or arts.get("spec")
-        if not spec:
-            continue
-        fm = spec["fm"]
-        if fm.get("status") != "shipped":
-            continue
-        if not fm.get("internal-tooling"):
-            continue
-        in_scope = fm.get("in-scope") or []
-        enables = fm.get("enables") or []
-        internal_paths, production_paths = _classify_inscope_paths(in_scope)
-        # Classification (post-PR-#5 schema; SP-13 enforces mutual exclusivity):
-        # - no production paths → "true-category-a" (correctly classified)
-        # - has production paths AND enables empty → "category-b-misclassified" (bug)
-        # - has production paths AND enables non-empty → impossible under SP-13;
-        #   if observed the validator failed and the analyst surfaces it separately
-        if not production_paths:
-            classification = "true-category-a"
-        elif not enables:
-            classification = "category-b-misclassified"
-        else:
-            # SP-13 violation should not reach here in a validated repo; flag
-            # explicitly so the analyst can route to a validator-bug finding.
-            classification = "sp-13-violation"
-        consumers: list[str] = []
-        if classification == "category-b-misclassified":
-            consumers = _forward_consumers(cid, production_paths or in_scope, changes, commits)
-        rows.append({
-            "change": cid,
-            "internal_only_paths_count": len(internal_paths),
-            "production_paths_count": len(production_paths),
-            "enables_count": len(enables),
-            "downstream_consumers": consumers,
-            "classification_candidate": classification,
-        })
-
-    candidate_rows = [r for r in rows
-                      if r["classification_candidate"] == "category-b-misclassified"]
-    fired = len(candidate_rows) >= KF_P1_MIN_ROWS
-    return {
-        "pattern_id": "KF-P1",
-        "pattern_name": "category-a-claim-spans-production-paths",
-        "fired": fired,
-        "evidence_row_count": len(candidate_rows),
-        "min_rows_for_firing": KF_P1_MIN_ROWS,
-        "all_rows": rows,
-        "evidence_rows": candidate_rows,
-        "note": ("Changes flagged `internal-tooling: true` (Category A) whose in-scope "
-                 "spans production-code paths AND whose `enables` array is empty. Under "
-                 "the post-PR-#5 schema (Category A vs Category B with `enables`/`enabled-by`), "
-                 "this is the engineer mis-classifying what should be Category B as Category A. "
-                 "SP-13 catches the both-set case; KF-P1 catches the claim-A-while-looking-like-B case."),
-    }
-
-
-# ---------------- KF-P2 ----------------
-
-_TOKEN_RE = re.compile(r"[a-zA-Z][a-zA-Z0-9_-]{2,}")
-
-
-def _tokens(text: str) -> set[str]:
-    """Lowercase token set from text; drops tokens <=3 chars and pure numbers."""
-    if not text:
-        return set()
-    return {t.lower() for t in _TOKEN_RE.findall(text)}
-
-
-def _jaccard(a: set[str], b: set[str]) -> float:
-    if not a or not b:
-        return 0.0
-    inter = len(a & b)
-    union = len(a | b)
-    return inter / union if union else 0.0
-
-
-def _kf_p2(commits: list[dict], session_rows: list[dict]) -> dict:
-    """KF-P2 — cluster halt sentinels with reason=other. Cluster size >=
-    MIN_CLUSTER_SIZE is evidence the enum is missing a case.
-
-    Sources: commit bodies (parser already extracted halt_reasons), and
-    session-row halt_reasons. For commits, we use the commit body as the
-    surrounding-prose context; for session rows we use the row's halt-context
-    if available, falling back to a label-only token set.
-    """
-    docs: list[dict] = []
-    for c in commits:
-        reasons = c.get("halt_reasons") or []
-        if not any(r.lower() == "other" for r in reasons):
-            continue
-        # Use commit body as the prose context — it is what the kernel
-        # contract says accompanies the sentinel.
-        context = c.get("body", "") or c.get("subject", "")
-        docs.append({
-            "source": "commit",
-            "ref": c.get("sha", "")[:8],
-            "context": context,
-            "tokens": _tokens(context),
-        })
-    for s in session_rows:
-        reasons = s.get("halt_reasons") or []
-        for r in reasons:
-            if not isinstance(r, str):
-                continue
-            if r.lower() != "other":
-                continue
-            docs.append({
-                "source": "session",
-                "ref": s.get("file", "") or s.get("skill", "") or "",
-                # Session parser does not capture surrounding prose in v1;
-                # use the session label as a degraded token source.
-                "context": s.get("skill", "") + " " + " ".join(reasons),
-                "tokens": _tokens(s.get("skill", "")),
-            })
-
-    # Greedy clustering: each new doc joins the first cluster whose
-    # representative has Jaccard >= threshold; else starts a new cluster.
-    clusters: list[list[dict]] = []
-    for d in docs:
-        placed = False
-        for cluster in clusters:
-            rep_tokens = cluster[0]["tokens"]
-            if _jaccard(d["tokens"], rep_tokens) >= JACCARD_THRESHOLD:
-                cluster.append(d)
-                placed = True
-                break
-        if not placed:
-            clusters.append([d])
-
-    evidence_clusters = [c for c in clusters if len(c) >= MIN_CLUSTER_SIZE]
-    rows = []
-    for i, cluster in enumerate(evidence_clusters):
-        rows.append({
-            "cluster_id": f"C-{i + 1}",
-            "size": len(cluster),
-            "representative_context": (cluster[0]["context"] or "")[:300],
-            "member_refs": [d["ref"] for d in cluster],
-        })
-
-    return {
-        "pattern_id": "KF-P2",
-        "pattern_name": "halt-reason-cluster-uncovered-by-enum",
-        "fired": len(evidence_clusters) > 0,
-        "evidence_row_count": len(evidence_clusters),
-        "jaccard_threshold": JACCARD_THRESHOLD,
-        "min_cluster_size": MIN_CLUSTER_SIZE,
-        "total_other_halts": len(docs),
-        "evidence_rows": rows,
-        "note": ("HSTACK-HALT sentinels with reason=other clustered by surrounding-prose "
-                 f"token overlap (Jaccard >= {JACCARD_THRESHOLD}). A cluster of "
-                 f">= {MIN_CLUSTER_SIZE} similar halts means the enum is missing a case."),
-    }
-
-
-# ---------------- KF-P3 ----------------
-
-def _commits_by_sha_prefix(commits: list[dict]) -> dict[str, dict]:
-    """Index commits by short sha (8 chars) for quick lookup. Falls back to
-    full sha if entries collide (rare with realistic repo sizes)."""
-    out: dict[str, dict] = {}
-    for c in commits:
-        sha = c.get("sha") or ""
-        if not sha:
-            continue
-        out[sha] = c
-        if len(sha) >= 8:
-            out[sha[:8]] = c
-    return out
-
-
-def _kf_p3(changes: dict, commits: list[dict]) -> dict:
-    """KF-P3 — spec-compliance adversarial findings resolved via a commit
-    whose message reveals a kernel-gate keyword. This is the pattern that
-    produced ADR-0002 (the missed `ready-for-review` transition).
-    """
-    commit_index = _commits_by_sha_prefix(commits)
-    rows: list[dict] = []
-    for cid, arts in changes.items():
-        ar = arts.get("adversarial-review")
-        if not ar:
-            continue
-        ar_fm = ar["fm"]
-        if ar_fm.get("status") != "findings-resolved":
-            continue
-        # Findings array on frontmatter is authoritative; fall back to body
-        # parser when the array is missing or absent.
-        findings = ar_fm.get("findings") or []
-        if not findings:
-            sections = split_sections(ar["body"] or "")
-            findings_section = sections.get("Findings", "")
-            findings = parse_findings_section(findings_section)
-        for f in findings:
-            if not isinstance(f, dict):
-                continue
-            category = (f.get("category") or "").lower()
-            if category != "spec-compliance":
-                continue
-            resolution = (f.get("resolution") or "").strip()
-            if not resolution.startswith("commit:"):
-                continue
-            sha_token = resolution.split(":", 1)[1].strip().split()[0]
-            commit = commit_index.get(sha_token) or commit_index.get(sha_token[:8])
-            if not commit:
-                # Still record the candidate — the analyst can decide whether
-                # missing-commit-context is itself a signal.
-                if KERNEL_GATE_KEYWORDS.search(resolution):
-                    rows.append({
-                        "change": cid,
-                        "finding_id": f.get("id"),
-                        "category": category,
-                        "resolution": resolution,
-                        "commit_subject": None,
-                        "matched_keywords": [],
-                        "commit_resolved": False,
-                    })
-                continue
-            haystack = (commit.get("subject") or "") + "\n" + (commit.get("body") or "")
-            matches = KERNEL_GATE_KEYWORDS.findall(haystack)
-            if not matches:
-                continue
-            rows.append({
-                "change": cid,
-                "finding_id": f.get("id"),
-                "category": category,
-                "resolution": resolution,
-                "commit_subject": commit.get("subject"),
-                "matched_keywords": [m.lower() for m in matches],
-                "commit_resolved": True,
-            })
-
-    return {
-        "pattern_id": "KF-P3",
-        "pattern_name": "skill-precondition-violated-and-recoverable",
-        "fired": len(rows) >= 1,
-        "evidence_row_count": len(rows),
-        "evidence_rows": rows,
-        "note": ("Adversarial spec-compliance findings whose resolving commit message "
-                 "mentions a kernel gate or precondition. Each row is a candidate "
-                 "'a Skill precondition should have halted earlier' signal — the "
-                 "ADR-0002 pattern."),
-    }

package/template/scripts/telemetry/insights/overengineering.py

@@ -1,115 +0,0 @@
-"""Overengineering insights: OE-1 artifact/diff ratio, OE-3 context-load ×
-invocations × downstream-refs, OE-5 trivial-eligible that ran the gauntlet."""
-
-from __future__ import annotations
-
-from collections import defaultdict
-
-from telemetry.parsers.bodies import approx_token_count
-from telemetry.parsers.commits import diff_line_count
-
-
-def compute(commits: list[dict], changes: dict, session_rows: list[dict], repo) -> dict:
-    return {
-        "oe_1_artifact_to_diff_ratio": _oe_1(changes, commits, repo),
-        "oe_3_subagent_context_load_amortization": _oe_3(session_rows, changes),
-        "oe_5_trivial_eligible_full_gauntlet": _oe_5(changes, commits),
-    }
-
-
-def _oe_1(changes: dict, commits: list[dict], repo) -> dict:
-    """OE-1: artifact tokens / code-diff lines.
-
-    Sums artifact-body token counts (approx 4 chars/token) per change, divides
-    by total diff lines on implement(<change-id>) commits for that change.
-    Ratio above ~50 is a strong overengineering signal; below ~5 the change is
-    likely under-specified for its complexity.
-    """
-    rows = []
-    for cid, arts in sorted(changes.items()):
-        artifact_tokens = 0
-        for atype, data in arts.items():
-            artifact_tokens += approx_token_count(data["body"])
-        # Sum implement-commit diffs for this change.
-        diff_lines = 0
-        for c in commits:
-            if c["artifact_type"] != "implement" or c["artifact_id"] != cid:
-                continue
-            added, removed = diff_line_count(repo, c["sha"])
-            diff_lines += added + removed
-        ratio = (artifact_tokens / diff_lines) if diff_lines > 0 else None
-        rows.append({
-            "change": cid,
-            "artifact_tokens": artifact_tokens,
-            "diff_lines": diff_lines,
-            "tokens_per_diff_line": round(ratio, 1) if ratio is not None else None,
-        })
-    rows.sort(key=lambda r: r["tokens_per_diff_line"] or 0, reverse=True)
-    return {"rows": rows}
-
-
-def _oe_3(session_rows: list[dict], changes: dict) -> dict:
-    """OE-3: per subagent, invocations × estimated context-load size.
-
-    Without sidecars to attribute downstream-reference-count, this v1 metric
-    surfaces just the subagent × invocation-count × cost dimension and lets
-    the reader eyeball which subagents are paying repeated entry-tax.
-    """
-    appearances = defaultdict(int)
-    total_cost_in_host = defaultdict(int)
-    for s in session_rows:
-        for sa in s["subagents"]:
-            appearances[sa] += 1
-            total_cost_in_host[sa] += s["cost_score"]
-    rows = []
-    for sa, n in sorted(appearances.items(), key=lambda kv: -kv[1]):
-        rows.append({
-            "subagent": sa,
-            "invocations": n,
-            "host_cost_score_total": total_cost_in_host[sa],
-            "cost_per_invocation": total_cost_in_host[sa] // n if n else 0,
-        })
-    return {"rows": rows}
-
-
-def _oe_5(changes: dict, commits: list[dict]) -> dict:
-    """OE-5: trivial-eligible changes that ran the full gauntlet.
-
-    Heuristic: change-spec at `shipped` (or any terminal state) with `trivial:
-    false`, empty `surfaces`, zero or one invariant. These are candidates that
-    might have qualified for the trivial-tag escape hatch but ran every gate.
-    """
-    candidates = []
-    for cid, arts in sorted(changes.items()):
-        spec = arts.get("change-spec")
-        if not spec:
-            continue
-        fm = spec["fm"]
-        if fm.get("trivial") is True:
-            continue
-        status = fm.get("status")
-        if status not in ("shipped", "ready-to-ship", "archived"):
-            continue
-        surfaces = fm.get("surfaces") or []
-        if surfaces:  # any declared surface disqualifies trivial-eligibility
-            continue
-        # diff size heuristic: a "trivial-eligible" change usually has <50 added lines
-        diff_total = 0
-        for c in commits:
-            if c["artifact_type"] == "implement" and c["artifact_id"] == cid:
-                # We can't get accurate line counts here without git access — use file count proxy
-                diff_total += len(c.get("files", []))
-        candidates.append({
-            "change": cid,
-            "status": status,
-            "surfaces": surfaces,
-            "files_touched_in_implement_commits": diff_total,
-        })
-    return {
-        "rows": candidates,
-        "note": (
-            "Heuristic only. A change with empty `surfaces` AND no `trivial: "
-            "true` tag is a candidate for retrospective trivial classification "
-            "— or a sign the surfaces list was under-declared."
-        ),
-    }