hstack 0.7.0 → 0.16.0

package/template/scripts/coord/coord_scan.py

@@ -35,6 +35,14 @@ addressing). The two local files this script touches are never authoritative:
     hstack/.session-state/coord-cursor   per-worktree acked-id list, shared by all
                                          sessions in that worktree (derivative; losing
                                          it re-surfaces messages — at-least-once)
+    hstack/.session-state/coord-scan-cache.json
+                                         per-worktree scan cache keyed on a refs-state
+                                         fingerprint (derivative; losing it costs one
+                                         full branch walk). Messages only appear via
+                                         commits and commits only move refs, so an
+                                         unchanged fingerprint proves the walk would
+                                         find the same set — the cache never changes
+                                         WHAT surfaces, only how fast.
     hstack/.telemetry/coord/events.jsonl per-worktree usage log (gitignored via the
                                          consumer's `**/.telemetry/` line; measurement
                                          only, never authoritative, safe to delete)
@@ -46,6 +54,7 @@ No network calls. Reads git only via `git show` / `git ls-tree` /
 from __future__ import annotations
 
 import argparse
+import hashlib
 import json
 import os
 import re
@@ -59,6 +68,7 @@ from pathlib import Path
 MESSAGES_DIR = "hstack/coord/messages"
 NAME_RELPATH = "hstack/coord/NAME"
 CURSOR_RELPATH = "hstack/.session-state/coord-cursor"
+CACHE_RELPATH = "hstack/.session-state/coord-scan-cache.json"
 TELEMETRY_RELPATH = "hstack/.telemetry/coord/events.jsonl"
 DEFAULT_HORIZON_DAYS = 30
 # Cursor entries older than twice the default horizon are pruned on ack.
@@ -279,13 +289,8 @@ def sanitize_ref(text: str, limit: int = 60) -> str:
     return re.sub(r"[^A-Za-z0-9._/-]", "_", text)[:limit]
 
 
-def collect_messages(
-    self_name: str,
-    self_main: str,
-    current_branch: str,
-    horizon_days: int,
-) -> list[dict[str, str]]:
-    """Return unacked-agnostic candidate messages addressed to this repo."""
+def resolve_sources(self_name: str, self_main: str) -> list[tuple[str, str]]:
+    """Scan sources: this repo plus every reachable registered peer."""
     registry = load_registry()
     sources: list[tuple[str, str]] = [(self_name, self_main)]
     self_real = os.path.realpath(self_main)
@@ -299,6 +304,19 @@ def collect_messages(
             )
             continue
         sources.append((r["name"], r["path"]))
+    return sources
+
+
+def collect_messages(
+    self_name: str,
+    self_main: str,
+    current_branch: str,
+    horizon_days: int,
+    sources: list[tuple[str, str]] | None = None,
+) -> list[dict[str, str]]:
+    """Return unacked-agnostic candidate messages addressed to this repo."""
+    if sources is None:
+        sources = resolve_sources(self_name, self_main)
 
     horizon = datetime.now() - timedelta(days=horizon_days)
     seen_ids: set[str] = set()
@@ -370,6 +388,88 @@ def collect_messages(
     return found
 
 
+# -------------------------------------------------------- refs-state cache
+
+
+def scan_fingerprint(
+    sources: list[tuple[str, str]],
+    self_name: str,
+    current_branch: str,
+    horizon_days: int,
+) -> str:
+    """Fingerprint of everything the branch walk's result depends on.
+
+    Messages exist only as committed files, and commits only become visible
+    by moving a ref — so if no local ref of any source repo moved, the walk
+    would return byte-identical results. The remaining inputs (identity,
+    branch, horizon, and today's date for the expires/horizon filters) are
+    folded in; the date term bounds cache lifetime at one day.
+
+    The cursor (ack state) is deliberately NOT part of the fingerprint —
+    acked-filtering happens after collection, so acks never require a
+    re-walk.
+    """
+    parts = [
+        "schema=1",
+        f"self={self_name}",
+        f"branch={current_branch}",
+        f"horizon={horizon_days}",
+        f"date={date.today().isoformat()}",
+    ]
+    for name, path in sources:
+        refs = try_git(
+            ["for-each-ref", "--format=%(refname:short) %(objectname)", "refs/heads"],
+            cwd=path,
+        )
+        parts.append(f"repo={name}:{os.path.realpath(path)}\n{refs or ''}")
+    return hashlib.sha256("\n".join(parts).encode("utf-8")).hexdigest()
+
+
+def collect_messages_cached(
+    root: str,
+    self_name: str,
+    self_main: str,
+    current_branch: str,
+    horizon_days: int,
+) -> tuple[list[dict[str, str]], bool]:
+    """collect_messages behind the refs-state cache.
+
+    Returns (messages, cache_hit). The cache is derivative in the strict
+    sense: deleting it costs one full branch walk and changes nothing else.
+    Corrupt or mismatched cache falls through to a full walk (fail open to
+    the slow-but-correct path).
+    """
+    sources = resolve_sources(self_name, self_main)
+    fingerprint = scan_fingerprint(sources, self_name, current_branch, horizon_days)
+    cache_file = Path(root) / CACHE_RELPATH
+    try:
+        cached = json.loads(cache_file.read_text())
+        if (
+            cached.get("schema_version") == 1
+            and cached.get("fingerprint") == fingerprint
+            and isinstance(cached.get("messages"), list)
+        ):
+            return cached["messages"], True
+    except Exception:
+        pass
+    found = collect_messages(
+        self_name, self_main, current_branch, horizon_days, sources=sources
+    )
+    try:
+        cache_file.parent.mkdir(parents=True, exist_ok=True)
+        tmp = cache_file.with_suffix(".tmp")
+        tmp.write_text(
+            json.dumps(
+                {"schema_version": 1, "fingerprint": fingerprint, "messages": found},
+                ensure_ascii=False,
+            )
+        )
+        os.replace(tmp, cache_file)  # atomic; concurrent scans race last-write-wins
+    except Exception:
+        pass  # cache write failure only costs the next caller a full walk
+    return found, False
+
+
 def cmd_scan(horizon_days: int) -> int:
     started = time.monotonic()
     root = repo_root()
@@ -378,16 +478,16 @@ def cmd_scan(horizon_days: int) -> int:
     self_name = resolve_self_name(root, self_main, load_registry())
     acked = load_acked(root)
 
-    new = [
-        m
-        for m in collect_messages(self_name, self_main, current_branch, horizon_days)
-        if m["id"] not in acked
-    ]
+    found, cache_hit = collect_messages_cached(
+        root, self_name, self_main, current_branch, horizon_days
+    )
+    new = [m for m in found if m["id"] not in acked]
     log_usage(
         root,
         "scan",
         new_count=len(new),
         duration_ms=int((time.monotonic() - started) * 1000),
+        cache="hit" if cache_hit else "miss",
     )
     if not new:
         return 0  # silent — the zero-cost path
@@ -437,11 +537,10 @@ def cmd_hook(horizon_days: int) -> int:
         current_branch = try_git(["rev-parse", "--abbrev-ref", "HEAD"], cwd=root) or "HEAD"
         self_name = resolve_self_name(root, self_main, load_registry())
         acked = load_acked(root)
-        new = [
-            m
-            for m in collect_messages(self_name, self_main, current_branch, horizon_days)
-            if m["id"] not in acked
-        ]
+        found, cache_hit = collect_messages_cached(
+            root, self_name, self_main, current_branch, horizon_days
+        )
+        new = [m for m in found if m["id"] not in acked]
         log_usage(
             root,
             "hook",
@@ -449,6 +548,7 @@ def cmd_hook(horizon_days: int) -> int:
             session_id=session_id,
             new_count=len(new),
             duration_ms=int((time.monotonic() - started) * 1000),
+            cache="hit" if cache_hit else "miss",
         )
         if new:
             print(
@@ -469,11 +569,10 @@ def cmd_ack(ids: list[str], ack_all: bool, horizon_days: int) -> int:
         self_main = main_worktree(root)
         current_branch = try_git(["rev-parse", "--abbrev-ref", "HEAD"], cwd=root) or "HEAD"
         self_name = resolve_self_name(root, self_main, load_registry())
-        ids = [
-            m["id"]
-            for m in collect_messages(self_name, self_main, current_branch, horizon_days)
-            if m["id"] not in acked
-        ]
+        found, _ = collect_messages_cached(
+            root, self_name, self_main, current_branch, horizon_days
+        )
+        ids = [m["id"] for m in found if m["id"] not in acked]
     if not ids:
         print("hstack-coord: nothing to ack")
         return 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: