hstack 0.7.0 → 0.16.0

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

@@ -1,24 +1,49 @@
-"""Token-economics insights: TE-1 cost per change, TE-2 cache-hit ratio per
-subagent, TE-3 subagent entry-tax amortization."""
+"""Token-economics insights: TE-1 cost per Skill, TE-2 cache-hit ratio per
+subagent, TE-3 subagent entry-tax amortization, TE-4 cost per phase, TE-5 cost
+per change (ADR-0009).
+
+TE-1/TE-2/TE-3 are *session-scoped*: they attribute a whole session to the first
+Skill it invoked, because a Skill has a start marker and no end marker. TE-4/TE-5
+are *phase-scoped*: they read the sidecar's `[phase_opened_at, phase_closed_at]`
+window and sum only the turns inside it. Where a sidecar exists, TE-4/TE-5
+supersede TE-1.
+"""
 
 from __future__ import annotations
 
 from collections import defaultdict
 
+from telemetry.parsers.transcripts import phase_usage
+
+
+#: The five Skills that emit sidecars (ADR-0001 § v1 emission list). Every other
+#: Skill is invisible to TE-4/TE-5 — which is what the coverage fraction says.
+EMITTING_SKILLS = (
+    "hstack-test-plan", "hstack-implement", "hstack-verify",
+    "hstack-adversarial-review", "hstack-finalize",
+)
+
+UNATTRIBUTED = "(unattributed)"
+
 
-def compute(session_rows: list[dict], changes: dict) -> dict:
-    """Compute the three TE metrics.
+def compute(session_rows: list[dict], changes: dict, sidecars: list[dict] | None = None) -> dict:
+    """Compute the five TE metrics.
 
     Args:
         session_rows: from transcripts.collect_session_rows
         changes: from frontmatter.load_change_artifacts
+        sidecars: from sidecars.load_sidecars (empty/None → TE-4/TE-5 report no
+            coverage rather than silently vanishing)
 
     Returns a dict ready for rendering.
     """
+    phases = _te_4(sidecars or [])
     return {
         "te_1_cost_per_change": _te_1(session_rows, changes),
         "te_2_cache_hit_per_subagent": _te_2(session_rows),
         "te_3_subagent_entry_tax": _te_3(session_rows),
+        "te_4_cost_per_phase": phases,
+        "te_5_cost_per_change": _te_5(phases["rows"]),
     }
 
 
@@ -44,7 +69,10 @@ def _te_1(session_rows: list[dict], changes: dict) -> dict:
     }
     cost_total = defaultdict(int)
     session_counts = defaultdict(int)
+    unattributed = 0
     for s in session_rows:
+        if s["skill"] is None:
+            unattributed += 1
         if s["skill"] in per_change_skills:
             # Heuristic: we don't have a structured change-id-per-session yet,
             # so accumulate by skill until sidecars exist. The (skill, total)
@@ -62,9 +90,16 @@ def _te_1(session_rows: list[dict], changes: dict) -> dict:
         })
     return {
         "rows": rows,
+        "unattributed_sessions": unattributed,
         "note": (
-            "v1 attribution is per-Skill, not per-change. Per-change cost will "
-            "sharpen once verify.json / finalize.json sidecars carry change_id."
+            "Session-scoped, not phase-scoped: a Skill has a start marker and no "
+            "end marker, so everything a session spends after the invocation "
+            "lands in the first bucket — including later phases and unrelated "
+            "work. Superseded by TE-4/TE-5 for any change that carries sidecars. "
+            "Attribution reads structured invocation markers only (<command-name> "
+            "tags, Skill tool_use blocks); sessions with no marker are "
+            f"unattributed ({unattributed} of {len(session_rows)} in window) "
+            "rather than credited to whichever Skill their prompt mentioned."
         ),
     }
 
@@ -76,7 +111,7 @@ def _te_2(session_rows: list[dict]) -> dict:
     """
     per_skill = defaultdict(lambda: {"cache_read": 0, "cache_creation": 0, "turns": 0})
     for s in session_rows:
-        key = s["skill"] or "(non-hstack)"
+        key = s["skill"] or UNATTRIBUTED
         t = s["totals"]
         per_skill[key]["cache_read"] += t.get("cache_read_input_tokens", 0)
         per_skill[key]["cache_creation"] += t.get("cache_creation_input_tokens", 0)
@@ -92,7 +127,16 @@ def _te_2(session_rows: list[dict]) -> dict:
             "cache_creation": agg["cache_creation"],
             "ratio": ratio,
         })
-    return {"rows": rows}
+    return {
+        "rows": rows,
+        "note": (
+            "Session-scoped, same caveat as TE-1 — the whole session's cache "
+            f"behaviour is credited to its first Skill. `{UNATTRIBUTED}` holds "
+            "every session with no structured hstack invocation marker, "
+            "including plain non-hstack work. Superseded by TE-4/TE-5 wherever "
+            "sidecars exist."
+        ),
+    }
 
 
 def _te_3(session_rows: list[dict]) -> dict:
@@ -127,3 +171,132 @@ def _te_3(session_rows: list[dict]) -> dict:
             "timestamps will sharpen this."
         ),
     }
+
+
+def _te_4(sidecars: list[dict]) -> dict:
+    """TE-4: cost per phase — the sidecar's window, summed from the transcript.
+
+    One row per sidecar. A row is *measured* when the sidecar carries a phase
+    window (schema_version ≥ 2) whose session transcript is still on disk;
+    otherwise `tokens` is `None` and the row is unmeasured. Never zero: a phase
+    whose transcript was swept spent tokens we can no longer count, and printing
+    0 would fold it into the average as if it were free.
+    """
+    rows = []
+    for sc in sidecars:
+        usage = phase_usage(sc.get("data") or {})
+        data = sc.get("data") or {}
+        rows.append({
+            "skill": sc.get("skill"),
+            "change": sc.get("change_id"),
+            "phase_id": sc.get("phase_id"),
+            "sidecar": sc.get("file"),
+            "schema_version": sc.get("schema_version"),
+            "session_id": data.get("session_id"),
+            "opened_at": data.get("phase_opened_at"),
+            "closed_at": data.get("phase_closed_at"),
+            "measured": usage is not None,
+            "unmeasured_reason": None if usage is not None else _unmeasured_reason(sc),
+            "tokens": usage["total_tokens"] if usage else None,
+            "cost_score": usage["cost_score"] if usage else None,
+            "turns": usage["turns"] if usage else None,
+            "wall_clock_h": round(usage["wall_clock_s"] / 3600, 2) if usage else None,
+        })
+    rows.sort(key=lambda r: (-(r["tokens"] or 0), r["change"] or "", r["sidecar"] or ""))
+    measured = [r for r in rows if r["measured"]]
+    return {
+        "rows": rows,
+        "phases_emitted": len(rows),
+        "phases_measured": len(measured),
+        "coverage_fraction": (len(measured) / len(rows)) if rows else None,
+        "note": (
+            "Phase-scoped: tokens are summed over assistant turns whose "
+            "timestamp falls inside the sidecar's [phase_opened_at, "
+            "phase_closed_at] window. Only the five sidecar-emitting Skills "
+            f"({', '.join(EMITTING_SKILLS)}) appear here at all — every other "
+            "Skill is invisible, and subagent spend lands in its host's window "
+            "(isSidechain=False). Unmeasured rows are phases whose window or "
+            "transcript could not be read; they are never counted as zero. "
+            "Sidecars are not window-filtered — every change folder on disk is "
+            "read, unlike the session and git tables above. Read "
+            "this table next to QO-4 (observed vs promised) and WS-2 (gate "
+            "findings density): cost without an outcome beside it can only "
+            "argue for spending less, never for spending well."
+        ),
+    }
+
+
+def _unmeasured_reason(sidecar: dict) -> str:
+    data = sidecar.get("data") or {}
+    if not data.get("phase_opened_at") or not data.get("phase_closed_at"):
+        version = sidecar.get("schema_version")
+        return ("pre-ADR-0009 sidecar (schema_version "
+                f"{version if version is not None else '?'}) — no phase window")
+    if not data.get("session_id"):
+        return "session id unresolved at write time"
+    return "transcript not found (retention sweep, or written on another machine)"
+
+
+def _te_5(phase_rows: list[dict]) -> dict:
+    """TE-5: cost per change — the sum of that change's measured phases.
+
+    The coverage fraction is not decoration. Five of the 27 Skills emit
+    sidecars, so `tokens` is a sum over a subset by construction: the spec, the
+    plan, the security- and data-reviews, the ship gate and the whole configure
+    family are absent, and so is any phase whose transcript has aged out. A
+    reader who takes this column for a change's total cost will read it low.
+    """
+    per_change: dict[str, dict] = {}
+    for r in phase_rows:
+        change = r.get("change") or "(unknown)"
+        agg = per_change.setdefault(change, {
+            "change": change,
+            "phases_emitted": 0,
+            "phases_measured": 0,
+            "skills": set(),
+            "tokens": 0,
+            "cost_score": 0,
+            "turns": 0,
+            "wall_clock_h": 0.0,
+        })
+        agg["phases_emitted"] += 1
+        if r.get("skill"):
+            agg["skills"].add(r["skill"])
+        if not r["measured"]:
+            continue
+        agg["phases_measured"] += 1
+        agg["tokens"] += r["tokens"] or 0
+        agg["cost_score"] += r["cost_score"] or 0
+        agg["turns"] += r["turns"] or 0
+        agg["wall_clock_h"] += r["wall_clock_h"] or 0.0
+    rows = []
+    for agg in per_change.values():
+        measured = agg["phases_measured"]
+        rows.append({
+            "change": agg["change"],
+            "phases_measured": measured,
+            "phases_emitted": agg["phases_emitted"],
+            "coverage_fraction": (measured / agg["phases_emitted"]) if agg["phases_emitted"] else None,
+            "skills_measured": sorted(agg["skills"]),
+            "tokens": agg["tokens"] if measured else None,
+            "cost_score": agg["cost_score"] if measured else None,
+            "turns": agg["turns"] if measured else None,
+            "wall_clock_h": round(agg["wall_clock_h"], 2) if measured else None,
+        })
+    rows.sort(key=lambda r: (-(r["tokens"] or 0), r["change"]))
+    total_emitted = sum(r["phases_emitted"] for r in rows)
+    total_measured = sum(r["phases_measured"] for r in rows)
+    return {
+        "rows": rows,
+        "phases_emitted": total_emitted,
+        "phases_measured": total_measured,
+        "coverage_fraction": (total_measured / total_emitted) if total_emitted else None,
+        "note": (
+            "A subset, not a total. Coverage fraction = measured phases / "
+            "emitted sidecars, and sidecars are emitted by five Skills only — "
+            "change-new, change-plan, security-review, data-review, ship and the "
+            "configure family contribute nothing to these sums. Pair with QO-4 "
+            "and the adversarial-review findings density before concluding that "
+            "an expensive change was a wasteful one."
+        ),
+    }

package/template/scripts/telemetry/parsers/sidecars.py

@@ -0,0 +1,61 @@
+"""Load the per-change telemetry sidecars written by the five emitting Skills.
+
+Sidecars live at `hstack/specs/changes/<change-id>/.telemetry/*.json` and are
+derivative, gitignored, and never authoritative (ADR-0001). This parser only
+reads them; a malformed or absent sidecar is skipped, never repaired.
+
+Schema versions (see `templates/telemetry-sidecar.md`):
+  1 — no phase window. Reads as *unmeasured*: `phase_usage` returns None.
+  2 — carries `session_id`, `phase_opened_at`, `phase_closed_at` (ADR-0009).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def load_sidecars(hstack_root: Path) -> list[dict]:
+    """Every sidecar under every change folder, sorted by change then filename.
+
+    Each entry: {path, change_id, file, skill, phase_id, schema_version, data}.
+    `skill` and `phase_id` fall back to the filename when the payload omits them
+    (`implement-<phase-id>.json`), so a hand-truncated sidecar still groups.
+    """
+    out: list[dict] = []
+    changes_dir = hstack_root / "specs" / "changes"
+    if not changes_dir.is_dir():
+        return out
+    for change_dir in sorted(changes_dir.iterdir()):
+        if not change_dir.is_dir():
+            continue
+        telemetry_dir = change_dir / ".telemetry"
+        if not telemetry_dir.is_dir():
+            continue
+        for f in sorted(telemetry_dir.glob("*.json")):
+            data = _read_json(f)
+            if data is None:
+                continue
+            stem = f.stem
+            skill = data.get("skill") or f"hstack-{stem.split('-')[0]}"
+            phase_id = data.get("phase_id")
+            if phase_id is None and stem.startswith("implement-"):
+                phase_id = stem[len("implement-"):]
+            out.append({
+                "path": f,
+                "file": f.name,
+                "change_id": data.get("change_id") or change_dir.name,
+                "skill": skill,
+                "phase_id": phase_id,
+                "schema_version": data.get("schema_version"),
+                "data": data,
+            })
+    return out
+
+
+def _read_json(path: Path) -> dict | None:
+    try:
+        loaded = json.loads(path.read_text(encoding="utf-8", errors="replace"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    return loaded if isinstance(loaded, dict) else None

package/template/scripts/telemetry/parsers/transcripts.py

@@ -1,8 +1,15 @@
 """Walk Claude Code transcript JSONL files for token economics and halt signals.
 
-Generalized from scripts/audit-token-usage.py. Same cost-score weighting; same
-classify-by-Skill heuristic. Adds: halt-sentinel detection, per-session
-start/end timestamps, cwd grouping for Conductor worktree dedup.
+Generalized from scripts/audit-token-usage.py. Same cost-score weighting. Adds:
+halt-sentinel detection, per-session start/end timestamps, cwd grouping for
+Conductor worktree dedup, and (ADR-0009) per-phase usage summation bounded by a
+sidecar's phase window.
+
+Session→Skill attribution reads *structured invocation markers only* — the
+`<command-name>` tag the harness writes for a slash command, and `Skill`
+tool_use blocks. Free text is never matched: a prompt that merely mentions
+`/hstack:coord` used to capture the whole session, which credited `coord` with
+roughly half of all measured cache-read tokens (ADR-0009 § Context, defect 2).
 """
 
 from __future__ import annotations
@@ -10,18 +17,27 @@ from __future__ import annotations
 import json
 import re
 from collections import defaultdict
-from datetime import datetime
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Iterable
 
+from telemetry.session_id import transcript_for_session
+
 
 PROJECTS_ROOT = Path.home() / ".claude" / "projects"
 
-HSTACK_SLASH = re.compile(r"/hstack:([a-z][a-z0-9\-]*)")
-HSTACK_CMD_TAG = re.compile(r"<command-name>/?hstack:?-?([a-z][a-z0-9\-]*)</command-name>")
+# Structured markers only. `<command-name>` is emitted by the harness around a
+# slash-command invocation; both the `/hstack:foo` and `/hstack-foo` spellings
+# appear in real transcripts.
+HSTACK_CMD_TAG = re.compile(r"<command-name>/?hstack[:\-]([a-z][a-z0-9\-]*)</command-name>")
+# `Skill` tool_use input, optionally namespaced by a plugin prefix.
+HSTACK_SKILL_NAME = re.compile(r"^(?:[A-Za-z0-9_.\-]+:)?hstack[:\-]([a-z][a-z0-9\-]*)$")
 SUBAGENT_TYPE = re.compile(r'"subagent_type"\s*:\s*"([a-z][a-z0-9\-]*)"')
 HALT_SENTINEL = re.compile(r"HSTACK-HALT:\s*reason=([a-z-]+)", re.IGNORECASE)
 
+USAGE_KEYS = ("input_tokens", "cache_creation_input_tokens",
+              "cache_read_input_tokens", "output_tokens")
+
 
 def message_text(msg) -> str:
     if msg is None:
@@ -91,20 +107,58 @@ def load_session(path: Path) -> list[dict]:
     return out
 
 
+def skill_tool_uses(msg) -> list[str]:
+    """hstack Skill names invoked via a `Skill` tool_use block in this message.
+
+    Structural walk, not a regex over flattened text: the marker is the block's
+    `type`/`name`/`input.skill` triple, which prose cannot forge.
+    """
+    if not isinstance(msg, dict):
+        return []
+    content = msg.get("content")
+    if not isinstance(content, list):
+        return []
+    out = []
+    for blk in content:
+        if not isinstance(blk, dict):
+            continue
+        if blk.get("type") != "tool_use" or blk.get("name") != "Skill":
+            continue
+        inp = blk.get("input")
+        name = inp.get("skill") if isinstance(inp, dict) else None
+        if not isinstance(name, str):
+            continue
+        m = HSTACK_SKILL_NAME.match(name.strip())
+        if m:
+            out.append(m.group(1))
+    return out
+
+
 def classify_session(records: list[dict]) -> tuple[str | None, set[str], list[str]]:
-    """Return (skill_name, set of subagent types invoked, halt reasons)."""
+    """Return (skill_name, set of subagent types invoked, halt reasons).
+
+    `skill_name` is the first hstack Skill invoked through a structured marker —
+    a `<command-name>` tag or a `Skill` tool_use block. A session carrying
+    neither returns `None` and is reported as *unattributed* (ADR-0009 piece 3);
+    it is never captured by whatever hstack command its prompt happened to name.
+    """
     skill = None
     subagents: set[str] = set()
     halts: list[str] = []
     for r in records:
         t = r.get("type")
-        if t == "user" and skill is None:
-            text = message_text(r.get("message"))
-            m = HSTACK_CMD_TAG.search(text) or HSTACK_SLASH.search(text)
-            if m:
-                skill = m.group(1)
+        if t == "user":
+            if skill is None:
+                m = HSTACK_CMD_TAG.search(message_text(r.get("message")))
+                if m:
+                    skill = m.group(1)
         elif t == "assistant":
-            text = message_text(r.get("message"))
+            msg = r.get("message")
+            if skill is None:
+                invoked = skill_tool_uses(msg)
+                if invoked:
+                    skill = invoked[0]
+            text = message_text(msg)
             for sa in SUBAGENT_TYPE.findall(text):
                 subagents.add(sa)
             for h in HALT_SENTINEL.findall(text):
@@ -112,15 +166,24 @@ def classify_session(records: list[dict]) -> tuple[str | None, set[str], list[st
     return skill, subagents, halts
 
 
+def parse_ts(value) -> datetime | None:
+    """Parse an ISO-8601 stamp to an aware UTC datetime. None on anything else."""
+    if not isinstance(value, str) or not value:
+        return None
+    try:
+        dt = datetime.fromisoformat(value.strip().replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(timezone.utc)
+
+
 def session_bounds(records: list[dict]) -> tuple[datetime | None, datetime | None]:
     first = last = None
     for r in records:
-        ts = r.get("timestamp")
-        if not ts:
-            continue
-        try:
-            dt = datetime.fromisoformat(ts.replace("Z", "+00:00"))
-        except (ValueError, AttributeError):
+        dt = parse_ts(r.get("timestamp"))
+        if dt is None:
             continue
         if first is None or dt < first:
             first = dt
@@ -129,19 +192,69 @@ def session_bounds(records: list[dict]) -> tuple[datetime | None, datetime | Non
     return first, last
 
 
-def tally_usage(records: list[dict]) -> dict[str, int]:
+def tally_usage(records: list[dict], start: datetime | None = None,
+                end: datetime | None = None) -> dict[str, int]:
+    """Sum assistant-turn usage. With `start`/`end`, only turns whose timestamp
+    falls inside the closed interval are counted."""
     totals: dict[str, int] = defaultdict(int)
+    for k in USAGE_KEYS:
+        totals[k] = 0
+    totals["turns"] = 0
     for r in records:
         if r.get("type") != "assistant":
             continue
+        if start is not None or end is not None:
+            ts = parse_ts(r.get("timestamp"))
+            if ts is None:
+                continue
+            if start is not None and ts < start:
+                continue
+            if end is not None and ts > end:
+                continue
         usage = (r.get("message") or {}).get("usage") or {}
-        for k in ("input_tokens", "cache_creation_input_tokens",
-                  "cache_read_input_tokens", "output_tokens"):
+        for k in USAGE_KEYS:
             totals[k] += usage.get(k, 0) or 0
         totals["turns"] += 1
     return dict(totals)
 
 
+def phase_usage(sidecar: dict, projects_root: Path | None = None) -> dict | None:
+    """Token usage inside one phase window, per ADR-0009 piece 2.
+
+    Reads the transcript named by `sidecar["session_id"]` and sums assistant-turn
+    usage over records whose `timestamp` falls in
+    `[phase_opened_at, phase_closed_at]`.
+
+    Returns `None` — *unmeasured* — whenever the window cannot be honoured: a
+    schema_version-1 sidecar with no window, a null session id, a transcript
+    swept by `cleanupPeriodDays` or living on another machine, an unparseable or
+    inverted window. Never zero: zero is a measurement, and a phase whose
+    transcript is gone was not measured. Read-only; nothing is written.
+    """
+    if not isinstance(sidecar, dict):
+        return None
+    opened = parse_ts(sidecar.get("phase_opened_at"))
+    closed = parse_ts(sidecar.get("phase_closed_at"))
+    if opened is None or closed is None or closed < opened:
+        return None
+    path = transcript_for_session(sidecar.get("session_id"), projects_root=projects_root)
+    if path is None:
+        return None
+    records = load_session(path)
+    if not records:
+        return None
+    totals = tally_usage(records, start=opened, end=closed)
+    total_tokens = sum(totals.get(k, 0) for k in USAGE_KEYS)
+    return {
+        **totals,
+        "total_tokens": total_tokens,
+        "cost_score": cost_score(totals),
+        "wall_clock_s": (closed - opened).total_seconds(),
+        "session_id": sidecar.get("session_id"),
+        "transcript": str(path),
+    }
+
+
 def cost_score(totals: dict[str, int]) -> int:
     """Same weighting as scripts/audit-token-usage.py: input + 1.25*cache_creation
     + 0.10*cache_read + 5*output. Approximates billable $-weight for ranking."""

package/template/scripts/telemetry/render.py

@@ -61,7 +61,7 @@ def _render_token_economics(lines: list[str], te: dict) -> None:
     _h(lines, 2, "Token economics")
 
     te1 = te.get("te_1_cost_per_change", {})
-    _h(lines, 3, "TE-1 — cost-score per Skill (proxy for per-change cost)")
+    _h(lines, 3, "TE-1 — cost-score per Skill (session-scoped)")
     _p(lines, te1.get("note", ""))
     _table(
         lines,
@@ -71,9 +71,10 @@ def _render_token_economics(lines: list[str], te: dict) -> None:
     )
 
     te2 = te.get("te_2_cache_hit_per_subagent", {})
-    _h(lines, 3, "TE-2 — cache-hit ratio (per Skill, v1 coarse grain)")
+    _h(lines, 3, "TE-2 — cache-hit ratio (per Skill, session-scoped)")
     _p(lines, "ratio = cache_read / (cache_read + cache_creation). Below 0.5 → context "
               "is being rebuilt rather than reused. Above 0.8 → cross-session reuse is healthy.")
+    _p(lines, te2.get("note", ""))
     _table(
         lines,
         ["skill", "turns", "cache_read", "cache_creation", "ratio"],
@@ -93,6 +94,61 @@ def _render_token_economics(lines: list[str], te: dict) -> None:
          for r in te3.get("rows", [])],
     )
 
+    te4 = te.get("te_4_cost_per_phase", {})
+    _h(lines, 3, "TE-4 — cost per phase (sidecar phase window)")
+    _p(lines, _coverage_line(te4, "phase"))
+    _p(lines, te4.get("note", ""))
+    rows4 = te4.get("rows", [])
+    measured4 = [r for r in rows4 if r["measured"]]
+    _table(
+        lines,
+        ["skill", "change", "phase", "tokens", "turns", "wall-clock (h)"],
+        [[r["skill"], r["change"], r["phase_id"] or "-",
+          f"{r['tokens']:,}", r["turns"], r["wall_clock_h"]]
+         for r in measured4[:40]],
+    )
+    unmeasured4 = [r for r in rows4 if not r["measured"]]
+    if unmeasured4:
+        by_reason: dict[str, int] = {}
+        for r in unmeasured4:
+            by_reason[r["unmeasured_reason"] or "unknown"] = by_reason.get(r["unmeasured_reason"] or "unknown", 0) + 1
+        _p(lines, f"**{len(unmeasured4)} unmeasured phase(s)** — counted as nothing, never as zero:")
+        _table(
+            lines,
+            ["reason", "phases"],
+            [[reason, count] for reason, count in sorted(by_reason.items(), key=lambda kv: -kv[1])],
+        )
+
+    te5 = te.get("te_5_cost_per_change", {})
+    _h(lines, 3, "TE-5 — cost per change (sum of measured phases)")
+    _p(lines, _coverage_line(te5, "phase"))
+    _p(lines, te5.get("note", ""))
+    _table(
+        lines,
+        ["change", "tokens", "turns", "wall-clock (h)", "phases measured / emitted", "coverage"],
+        [[r["change"],
+          f"{r['tokens']:,}" if r["tokens"] is not None else "unmeasured",
+          r["turns"] if r["turns"] is not None else "-",
+          r["wall_clock_h"] if r["wall_clock_h"] is not None else "-",
+          f"{r['phases_measured']} / {r['phases_emitted']}",
+          f"{r['coverage_fraction']:.0%}" if r["coverage_fraction"] is not None else "-"]
+         for r in te5.get("rows", [])[:20]],
+    )
+
+
+def _coverage_line(block: dict, unit: str) -> str:
+    emitted = block.get("phases_emitted", 0)
+    measured = block.get("phases_measured", 0)
+    frac = block.get("coverage_fraction")
+    if not emitted:
+        return (f"**Coverage: 0 sidecars in this repo.** No {unit} is measurable — "
+                "either no change has reached a sidecar-emitting terminal state yet, "
+                "or the sidecars pre-date ADR-0009's phase window.")
+    return (f"**Coverage: {measured} of {emitted} emitted sidecars measurable"
+            + (f" ({frac:.0%})" if frac is not None else "") + ".** "
+            "Emitted sidecars come from five Skills only, so this is a subset of the "
+            "change's real cost — read the fraction before reading the totals.")
+
 
 def _render_workflow_shape(lines: list[str], ws: dict) -> None:
     _h(lines, 2, "Workflow shape")
@@ -274,7 +330,7 @@ def _render_contract_drift(lines: list[str], cd: dict) -> None:
 
 def _render_kernel_fit(lines: list[str], kf: dict) -> None:
     _h(lines, 2, "Kernel-fit candidates")
-    _p(lines, "Patterns suggesting the kernel itself (CLAUDE.md, templates, validators, Skill "
+    _p(lines, "Patterns suggesting the kernel itself (KERNEL.md, templates, validators, Skill "
               "flows) may need revision. Each fired pattern is also written as a durable finding "
               "by `/hstack:kernel-fit-scan` at `hstack/kernel-fit/findings/KF-NNNN-*.md`. The "
               "table below is a rollup; the findings are the canonical artifact. See ADR-0004.")
@@ -345,6 +401,15 @@ def watch_items(metrics: dict) -> list[str]:
         if r.get("ratio") is not None and r["ratio"] < 0.5 and r["turns"] > 5:
             items.append(f"Low cache-hit on `{r['skill']}` ({r['ratio']:.0%}) — context is being rebuilt.")
 
+    # TE-4: emitted sidecars the parser could not measure
+    te4 = metrics.get("token_economics", {}).get("te_4_cost_per_phase", {})
+    emitted = te4.get("phases_emitted", 0)
+    measured = te4.get("phases_measured", 0)
+    if emitted and measured < emitted:
+        items.append(f"{emitted - measured} of {emitted} phase sidecars are unmeasured "
+                     "(no phase window, or the session transcript is gone) — TE-4/TE-5 "
+                     "totals are a subset, not a total.")
+
     # QO-2 smells
     smells = metrics.get("quality_outcomes", {}).get("qo_2_severity_resolution_mix", {}).get("high_severity_in_prose_smells", [])
     if smells: