hstack 0.7.1 → 0.16.0

package/template/scripts/run-gates.sh

@@ -0,0 +1,388 @@
+#!/usr/bin/env bash
+#
+# hstack gate runner — the verifier's machine hands, and the thing
+# {{TODO-SCRIPT: hstack/scripts/run-gates.sh}} stood in for.
+#
+#   hstack/scripts/run-gates.sh --change <change-id>
+#   hstack/scripts/run-gates.sh --change <id> --suite unit --suite lint
+#   hstack/scripts/run-gates.sh --list
+#   hstack/scripts/run-gates.sh --change <id> --json
+#
+# It reads the canonical commands declared in hstack/context/ci-cd.md, runs
+# every one of them, captures combined stdout/stderr to the pointer file the
+# verification artifact references, and emits an observed-test-count PER SUITE
+# so V-05 ("a suite that executed zero tests cannot be recorded as pass") is a
+# measurement rather than a paragraph of parsing instructions in a prompt.
+#
+# Exit codes:
+#   0  every suite ran, exited 0, and every test suite observed > 0 tests
+#   1  a suite failed, or a test suite observed zero tests (V-05)
+#   2  usage / environment error (no ci-cd.md, no canonical-commands block)
+#
+# Dependency-free by construction: POSIX tools only, no jq, no node. The
+# consuming repo has no node_modules for hstack — same constraint that made
+# validate-spec.mjs plain ESM (ADR-0001).
+
+set -uo pipefail
+
+# ---------------------------------------------------------------------------
+# 1. Argument parsing
+# ---------------------------------------------------------------------------
+
+CHANGE_ID=""
+OUT=""
+ROOT=""
+JSON=0
+LIST=0
+SUITES_REQUESTED=""
+
+usage() {
+  cat <<'EOF'
+hstack run-gates — run the canonical test / lint / typecheck suites
+
+  hstack/scripts/run-gates.sh [options]
+
+Options
+  --change ID     change-spec id; the pointer file defaults to
+                  hstack/specs/changes/<ID>/test-output.txt
+  --out PATH      pointer file path (overrides --change)
+  --suite NAME    run only this suite; repeatable
+  --list          print the parsed canonical commands and exit
+  --json          emit the per-suite summary as JSON on stdout
+  --root DIR      repo root to resolve hstack/ from (default: search upward)
+  -h, --help      this text
+
+Exit codes: 0 all green with a non-zero test count per test suite,
+1 a suite failed or observed zero tests (V-05), 2 usage / environment error.
+EOF
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --change) CHANGE_ID="${2:-}"; shift 2 ;;
+    --out) OUT="${2:-}"; shift 2 ;;
+    --suite) SUITES_REQUESTED="$SUITES_REQUESTED ${2:-}"; shift 2 ;;
+    --root) ROOT="${2:-}"; shift 2 ;;
+    --json) JSON=1; shift ;;
+    --list) LIST=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "run-gates: unknown option $1" >&2; usage >&2; exit 2 ;;
+  esac
+done
+
+# ---------------------------------------------------------------------------
+# 2. Locate the hstack tree
+# ---------------------------------------------------------------------------
+
+find_hstack_root() {
+  dir="${1:-$PWD}"
+  dir=$(cd "$dir" 2>/dev/null && pwd) || return 1
+  while :; do
+    if [ -f "$dir/hstack/KERNEL.md" ] || [ -f "$dir/hstack/CLAUDE.md" ] || [ -f "$dir/hstack/config.yaml" ]; then
+      printf '%s\n' "$dir"
+      return 0
+    fi
+    parent=$(dirname "$dir")
+    [ "$parent" = "$dir" ] && return 1
+    dir="$parent"
+  done
+}
+
+REPO_ROOT=$(find_hstack_root "${ROOT:-$PWD}") || {
+  echo "run-gates: no hstack/ tree found (looked for hstack/KERNEL.md upward from ${ROOT:-$PWD}). Pass --root <repo>." >&2
+  exit 2
+}
+HSTACK="$REPO_ROOT/hstack"
+CI_CD="$HSTACK/context/ci-cd.md"
+
+[ -f "$CI_CD" ] || {
+  echo "run-gates: $CI_CD not found. The canonical commands live there; run \`/hstack:configure --interview ci-cd\` first." >&2
+  exit 2
+}
+
+# ---------------------------------------------------------------------------
+# 3. Parse the canonical commands
+# ---------------------------------------------------------------------------
+#
+# ci-cd.md declares them in a fenced block with the info string `hstack-gates`,
+# one `suite: command` pair per line. The fence is the contract: everything
+# else in ci-cd.md is prose written for humans, and a runner that guessed at
+# prose would produce a confident wrong answer about what the repo's tests are.
+
+CANONICAL=$(awk '
+  /^```[[:space:]]*hstack-gates[[:space:]]*$/ { inblock=1; next }
+  inblock && /^```/ { inblock=0; next }
+  inblock {
+    line=$0
+    sub(/#.*$/, "", line)                                  # trailing comment
+    if (line ~ /^[[:space:]]*$/) next
+    idx = index(line, ":")
+    if (idx == 0) next
+    key = substr(line, 1, idx-1)
+    val = substr(line, idx+1)
+    gsub(/^[[:space:]]+|[[:space:]]+$/, "", key)
+    gsub(/^[[:space:]]+|[[:space:]]+$/, "", val)
+    if (val == "" || val == "none" || val == "null") next  # declared absent
+    printf "%s\t%s\n", key, val
+  }
+' "$CI_CD")
+
+if [ -z "$CANONICAL" ]; then
+  echo "run-gates: no \`hstack-gates\` fenced block in hstack/context/ci-cd.md." >&2
+  echo "           Declare the canonical commands there — see hstack/templates/ci-cd.md § Canonical Commands." >&2
+  exit 2
+fi
+
+# Suites that are evidence of behaviour, and therefore subject to V-05. Lint
+# and typecheck are exempt: both produce a diagnostic count whose floor is
+# naturally zero on a clean repo, so zero is not a signal of a skipped run.
+is_test_suite() {
+  case "$1" in
+    unit|integration|e2e) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+wanted() {
+  [ -z "$SUITES_REQUESTED" ] && return 0
+  for s in $SUITES_REQUESTED; do [ "$s" = "$1" ] && return 0; done
+  return 1
+}
+
+if [ "$LIST" -eq 1 ]; then
+  echo "hstack run-gates — canonical commands from hstack/context/ci-cd.md"
+  echo ""
+  printf '%s\n' "$CANONICAL" | while IFS="$(printf '\t')" read -r suite cmd; do
+    printf '  %-12s %s\n' "$suite" "$cmd"
+  done
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# 4. Pointer file
+# ---------------------------------------------------------------------------
+
+if [ -z "$OUT" ]; then
+  if [ -n "$CHANGE_ID" ]; then
+    OUT="$HSTACK/specs/changes/$CHANGE_ID/test-output.txt"
+    [ -d "$HSTACK/specs/changes/$CHANGE_ID" ] || {
+      echo "run-gates: no change folder at hstack/specs/changes/$CHANGE_ID/" >&2
+      exit 2
+    }
+  else
+    OUT="$REPO_ROOT/hstack-gates-output.txt"
+  fi
+fi
+mkdir -p "$(dirname "$OUT")" || exit 2
+: > "$OUT" || { echo "run-gates: cannot write $OUT" >&2; exit 2; }
+
+{
+  echo "hstack run-gates"
+  echo "repo:   $REPO_ROOT"
+  echo "source: hstack/context/ci-cd.md"
+  echo "====================================================================="
+} >> "$OUT"
+
+# ---------------------------------------------------------------------------
+# 5. Observed-test-count extraction
+# ---------------------------------------------------------------------------
+#
+# One awk pass per suite over that suite's captured output. The runners hstack
+# meets in practice all print a summary line; the point is not to understand
+# every runner, it is to answer one question honestly: did this suite execute
+# anything? When no known pattern matches, the answer is "unknown" — and
+# unknown is treated as zero, because a count nobody could read is not evidence.
+#
+# "Executed" is passed + failed, NOT total. A run that collected fifteen tests
+# and skipped all fifteen executed nothing, and V-05 exists precisely for that
+# case: `Tests: 15 skipped, 15 total` is a non-zero total with zero assertions.
+#
+#   Jest / Vitest   Tests:  12 passed, 3 skipped, 15 total   |  No tests found
+#   Mocha           12 passing / 3 pending / 1 failing
+#   Playwright      12 passed (4.2s) / 1 failed / 3 skipped
+#   pytest          collected 15 items  |  12 passed, 3 skipped  |  no tests ran
+#   go test         ok  pkg  0.4s   |  testing: warning: no tests to run
+
+count_tests() {
+  # $1 = file holding this suite's output
+  awk '
+    function num(s) { return s + 0 }
+    # --- explicit zero-collection statements, strongest signal ----------------
+    /[Nn]o tests found/          { zero=1 }
+    /collected 0 items/          { zero=1; seen=1 }
+    /no tests ran/               { zero=1; seen=1 }
+    /no tests to run/            { zero=1 }
+    /^[[:space:]]*Test Files[[:space:]]+no tests/ { zero=1 }
+
+    # --- Jest / Vitest summary ----------------------------------------------
+    /^[[:space:]]*Tests:?[[:space:]]/ {
+      seen=1
+      line=$0
+      if (match(line, /[0-9]+ passed/))  { s=substr(line, RSTART, RLENGTH); passed=num(s) }
+      if (match(line, /[0-9]+ failed/))  { s=substr(line, RSTART, RLENGTH); failed=num(s) }
+      if (match(line, /[0-9]+ skipped/)) { s=substr(line, RSTART, RLENGTH); skipped=num(s) }
+      if (match(line, /[0-9]+ todo/))    { s=substr(line, RSTART, RLENGTH); skipped+=num(s) }
+      if (match(line, /[0-9]+ total/))   { s=substr(line, RSTART, RLENGTH); total=num(s) }
+    }
+
+    # --- pytest short summary ------------------------------------------------
+    /=+ .*(passed|failed|error|skipped).* =+/ {
+      seen=1
+      line=$0
+      if (match(line, /[0-9]+ passed/))  { s=substr(line, RSTART, RLENGTH); passed=num(s) }
+      if (match(line, /[0-9]+ failed/))  { s=substr(line, RSTART, RLENGTH); failed=num(s) }
+      if (match(line, /[0-9]+ error/))   { s=substr(line, RSTART, RLENGTH); failed+=num(s) }
+      if (match(line, /[0-9]+ skipped/)) { s=substr(line, RSTART, RLENGTH); skipped=num(s) }
+    }
+    /collected [0-9]+ item/ {
+      seen=1
+      if (match($0, /collected [0-9]+/)) { s=substr($0, RSTART+10, RLENGTH-10); collected=num(s) }
+    }
+
+    # --- Mocha ---------------------------------------------------------------
+    /^[[:space:]]*[0-9]+ passing/ { seen=1; if (match($0, /[0-9]+/)) { passed=num(substr($0, RSTART, RLENGTH)) } }
+    /^[[:space:]]*[0-9]+ pending/ { seen=1; if (match($0, /[0-9]+/)) { skipped=num(substr($0, RSTART, RLENGTH)) } }
+    /^[[:space:]]*[0-9]+ failing/ { seen=1; if (match($0, /[0-9]+/)) { failed=num(substr($0, RSTART, RLENGTH)) } }
+
+    # --- Playwright ("12 passed (4.2s)") and bare runner tallies -------------
+    # No \b here: POSIX awk reads it as a backspace, not a word boundary.
+    /^[[:space:]]*[0-9]+ (passed|failed|skipped|flaky)([^a-z]|$)/ {
+      seen=1
+      line=$0
+      if (match(line, /[0-9]+ passed/))  { s=substr(line, RSTART, RLENGTH); passed=num(s) }
+      if (match(line, /[0-9]+ failed/))  { s=substr(line, RSTART, RLENGTH); failed=num(s) }
+      if (match(line, /[0-9]+ skipped/)) { s=substr(line, RSTART, RLENGTH); skipped=num(s) }
+      if (match(line, /[0-9]+ flaky/))   { s=substr(line, RSTART, RLENGTH); passed+=num(s) }
+    }
+
+    END {
+      if (total == 0) total = passed + failed + skipped
+      if (total == 0 && collected > 0) { total = collected }
+      if (zero) { total = 0; passed = 0; failed = 0 }
+      executed = passed + failed
+      # `known` says whether any pattern matched at all. An unreadable summary
+      # is reported as unknown and treated as zero downstream — a count nobody
+      # could read is not evidence that tests ran.
+      known = (seen || zero) ? 1 : 0
+      printf "%d %d %d %d %d %d\n", passed+0, failed+0, skipped+0, total+0, executed+0, known
+    }
+  ' "$1"
+}
+
+# ---------------------------------------------------------------------------
+# 6. Run
+# ---------------------------------------------------------------------------
+
+TMPDIR_RUN=$(mktemp -d "${TMPDIR:-/tmp}/hstack-run-gates.XXXXXX") || exit 2
+trap 'rm -rf "$TMPDIR_RUN"' EXIT
+
+SUMMARY="$TMPDIR_RUN/summary"
+: > "$SUMMARY"
+OVERALL=0
+RAN_ANY=0
+
+while IFS="$(printf '\t')" read -r suite cmd; do
+  [ -n "$suite" ] || continue
+  wanted "$suite" || continue
+  RAN_ANY=1
+
+  suite_out="$TMPDIR_RUN/$suite.out"
+  {
+    echo ""
+    echo "--- suite: $suite ------------------------------------------------"
+    echo "\$ $cmd"
+  } >> "$OUT"
+
+  # stdin from /dev/null, not inherited: the loop below is fed by a heredoc of
+  # the canonical commands, and a suite that reads stdin (an interactive watch
+  # mode, a prompt) would otherwise eat the remaining suites.
+  ( cd "$REPO_ROOT" && eval "$cmd" ) > "$suite_out" 2>&1 < /dev/null
+  code=$?
+  cat "$suite_out" >> "$OUT"
+
+  if is_test_suite "$suite"; then
+    read -r passed failed skipped total executed known <<EOF
+$(count_tests "$suite_out")
+EOF
+  else
+    passed=0; failed=0; skipped=0; total=0; executed=0; known=1
+  fi
+
+  # V-05: zero executed tests is `not-run`, never `pass`. "Zero failures" is
+  # not evidence of correctness when there were zero assertions to fail.
+  if [ "$code" -ne 0 ]; then
+    verdict="fail"
+    reason="command exited $code"
+    OVERALL=1
+  elif is_test_suite "$suite" && [ "$executed" -eq 0 ]; then
+    verdict="not-run"
+    if [ "$known" -eq 0 ]; then
+      reason="no test count could be read from the runner's output (unrecognised summary format)"
+    elif [ "$skipped" -gt 0 ]; then
+      reason="the runner reported zero executed tests — $skipped skipped of $total collected (all-skipped, or a filter that collapsed the set)"
+    else
+      reason="the runner reported zero executed tests (env-gated, empty-collection, or filter-collapse)"
+    fi
+    OVERALL=1
+  else
+    verdict="pass"
+    reason=""
+  fi
+
+  printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' \
+    "$suite" "$cmd" "$code" "$verdict" "$passed" "$failed" "$skipped" "$total" "$executed" "$reason" >> "$SUMMARY"
+
+  {
+    echo "--- suite: $suite → $verdict (exit $code, $executed of $total test(s) executed)"
+  } >> "$OUT"
+done <<EOF
+$CANONICAL
+EOF
+
+if [ "$RAN_ANY" -eq 0 ]; then
+  echo "run-gates: no suite matched --suite${SUITES_REQUESTED}" >&2
+  exit 2
+fi
+
+# ---------------------------------------------------------------------------
+# 7. Report
+# ---------------------------------------------------------------------------
+
+REL_OUT="${OUT#"$REPO_ROOT"/}"
+
+if [ "$JSON" -eq 1 ]; then
+  printf '{\n'
+  printf '  "ok": %s,\n' "$([ "$OVERALL" -eq 0 ] && echo true || echo false)"
+  printf '  "test-output": "%s",\n' "$REL_OUT"
+  printf '  "suites": [\n'
+  first=1
+  while IFS="$(printf '\t')" read -r suite cmd code verdict passed failed skipped total executed reason; do
+    [ "$first" -eq 1 ] || printf ',\n'
+    first=0
+    esc_cmd=$(printf '%s' "$cmd" | sed 's/\\/\\\\/g; s/"/\\"/g')
+    esc_reason=$(printf '%s' "$reason" | sed 's/\\/\\\\/g; s/"/\\"/g')
+    printf '    {"suite": "%s", "command": "%s", "exit": %s, "verdict": "%s", "observed": {"passed": %s, "failed": %s, "skipped": %s, "total": %s, "executed": %s}, "reason": "%s"}' \
+      "$suite" "$esc_cmd" "$code" "$verdict" "$passed" "$failed" "$skipped" "$total" "$executed" "$esc_reason"
+  done < "$SUMMARY"
+  printf '\n  ]\n}\n'
+else
+  echo ""
+  echo "hstack run-gates — $REPO_ROOT"
+  echo ""
+  printf '  %-12s %-9s %-6s %s\n' "suite" "verdict" "exit" "observed (passed/failed/skipped/total)"
+  while IFS="$(printf '\t')" read -r suite cmd code verdict passed failed skipped total executed reason; do
+    printf '  %-12s %-9s %-6s %s/%s/%s/%s\n' "$suite" "$verdict" "$code" "$passed" "$failed" "$skipped" "$total"
+    [ -n "$reason" ] && printf '               %s\n' "$reason"
+  done < "$SUMMARY"
+  echo ""
+  echo "  captured output: $REL_OUT"
+  echo "  → verification.artifacts.test-output: $REL_OUT"
+  echo ""
+  if [ "$OVERALL" -eq 0 ]; then
+    echo "run-gates: all suites green with a non-zero executed-test count."
+  else
+    echo "run-gates: at least one suite failed or executed zero tests (V-05). status: passed is blocked."
+  fi
+fi
+
+exit "$OVERALL"

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

@@ -4,7 +4,7 @@ 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
+See ADR-0004 for the full design rationale and `template/KERNEL.md` § How
 hstack improves itself for the loop contract.
 
 Three starter patterns:

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