hstack 0.16.0 → 0.18.0

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/KERNEL.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."
-        ),
-    }

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

@@ -1,131 +0,0 @@
-"""Quality-outcomes insights: QO-2 severity-resolution mix, QO-3 test-
-immutability audit, QO-4 verifier observed-vs-promised."""
-
-from __future__ import annotations
-
-from collections import defaultdict
-
-
-def compute(commits: list[dict], changes: dict) -> dict:
-    return {
-        "qo_2_severity_resolution_mix": _qo_2(changes),
-        "qo_3_test_immutability_audit": _qo_3(commits),
-        "qo_4_observed_vs_promised": _qo_4(changes),
-    }
-
-
-def _qo_2(changes: dict) -> dict:
-    """QO-2: per finding, cross-tab severity × resolution-type.
-
-    Resolution prefix is the part before the colon: commit | tech-debt |
-    justified-in-prose.
-    """
-    matrix: dict[tuple[str, str], int] = defaultdict(int)
-    smell_cases = []  # high/critical severity resolved as justified-in-prose
-    for cid, arts in changes.items():
-        adv = arts.get("adversarial-review")
-        if not adv:
-            continue
-        findings = adv["fm"].get("findings")
-        if not isinstance(findings, list):
-            continue
-        for f in findings:
-            if not isinstance(f, dict):
-                continue
-            sev = (f.get("severity") or "unknown").lower()
-            res = (f.get("resolution") or "unknown")
-            res_type = res.split(":", 1)[0].strip().lower() if isinstance(res, str) else "unknown"
-            if res_type not in ("commit", "tech-debt", "justified-in-prose"):
-                res_type = "other"
-            matrix[(sev, res_type)] += 1
-            if sev in ("high", "critical") and res_type == "justified-in-prose":
-                smell_cases.append({
-                    "change": cid,
-                    "finding_id": f.get("id"),
-                    "category": f.get("category"),
-                    "severity": sev,
-                })
-    severities = sorted({s for s, _ in matrix.keys()})
-    res_types = ["commit", "tech-debt", "justified-in-prose", "other"]
-    rows = []
-    for sev in severities:
-        row = {"severity": sev}
-        for rt in res_types:
-            row[rt] = matrix.get((sev, rt), 0)
-        rows.append(row)
-    return {
-        "rows": rows,
-        "high_severity_in_prose_smells": smell_cases,
-    }
-
-
-def _qo_3(commits: list[dict]) -> dict:
-    """QO-3: test-immutability audit.
-
-    For every commit touching a test file, check whether the body carries one
-    of the canonical authorization phrases. Unauthorized test-edit commits are
-    hard kernel violations.
-    """
-    import re
-    test_re = re.compile(r"(\.test\.|\.spec\.|/__tests__/|/__snapshots__/|^e2e/|_test\.go$)")
-    auth_re = re.compile(
-        r"Ok to (change|delete) test\s+\S+"
-        r"|Ok to update snapshot\s+\S+"
-        r"|Ok to refresh fixture\s+\S+"
-    )
-    violations = []
-    authorized = []
-    for c in commits:
-        test_files = [f for f in c.get("files", []) if test_re.search(f)]
-        if not test_files:
-            continue
-        is_implement_or_test_plan = c.get("artifact_type") in ("implement", "test-plan")
-        # New-tests-in-an-implement-commit are permitted; we can't distinguish
-        # new-vs-modified without per-file diff inspection. As a heuristic, an
-        # implement commit touching a test file without an auth phrase is
-        # treated as a candidate, not a violation. Adversarial-review-time
-        # changes to a test file without auth ARE violations regardless.
-        has_auth = bool(auth_re.search(c.get("body", "")))
-        if has_auth:
-            authorized.append({"sha": c["sha"], "subject": c["subject"], "test_files": test_files})
-        elif is_implement_or_test_plan:
-            # candidate — could be a new test write, which is permitted
-            pass
-        else:
-            violations.append({
-                "sha": c["sha"],
-                "subject": c["subject"],
-                "test_files": test_files,
-                "artifact_type": c.get("artifact_type"),
-            })
-    return {
-        "authorized_count": len(authorized),
-        "candidate_violations": violations,
-        "note": (
-            "Implement-phase commits touching test files are not flagged here "
-            "(new tests are permitted by the test-immutability protocol). "
-            "Non-implement commits touching test files without an authorization "
-            "phrase are listed as candidate violations for manual review."
-        ),
-    }
-
-
-def _qo_4(changes: dict) -> dict:
-    """QO-4: verifier observed-vs-promised, summarized from
-    verification.test-plan-coverage map."""
-    counts = defaultdict(lambda: defaultdict(int))
-    per_change = []
-    for cid, arts in sorted(changes.items()):
-        v = arts.get("verification")
-        if not v:
-            continue
-        cov = v["fm"].get("test-plan-coverage")
-        if not isinstance(cov, dict):
-            continue
-        row = {"change": cid}
-        for key, value in cov.items():
-            counts[key][str(value)] += 1
-            row[key] = value
-        per_change.append(row)
-    summary = {key: dict(buckets) for key, buckets in counts.items()}
-    return {"summary": summary, "per_change": per_change}