hstack 0.7.0 → 0.16.0

package/template/scripts/telemetry/report.py

@@ -37,7 +37,7 @@ _SCRIPTS = _THIS.parent.parent
 if str(_SCRIPTS) not in sys.path:
     sys.path.insert(0, str(_SCRIPTS))
 
-from telemetry.parsers import frontmatter, commits, transcripts  # noqa: E402
+from telemetry.parsers import frontmatter, commits, transcripts, sidecars  # noqa: E402
 from telemetry.insights import (  # noqa: E402
     token_economics, workflow_shape, quality_outcomes,
     overengineering, contract_drift, kernel_fit,
@@ -59,7 +59,11 @@ def main(argv: list[str] | None = None) -> int:
     hstack_root = repo / "hstack"
     if not hstack_root.is_dir():
         # Permit running against the template repo itself (no hstack/ prefix).
-        if (repo / "specs").is_dir() and (repo / "CLAUDE.md").is_file():
+        # CLAUDE.md is the pre-ADR-0010 kernel name — still accepted so an
+        # un-migrated tree keeps reporting.
+        if (repo / "specs").is_dir() and (
+            (repo / "KERNEL.md").is_file() or (repo / "CLAUDE.md").is_file()
+        ):
             hstack_root = repo
         else:
             print(f"error: no hstack/ directory at {repo}", file=sys.stderr)
@@ -86,9 +90,14 @@ def main(argv: list[str] | None = None) -> int:
     session_rows = transcripts.collect_session_rows([repo], since=since_dt)
     print(f"telemetry: {len(session_rows)} sessions in window", file=sys.stderr)
 
+    # Phase sidecars (ADR-0009). Gitignored and derivative: absent on a fresh
+    # clone, which reports as zero coverage rather than as zero cost.
+    phase_sidecars = sidecars.load_sidecars(hstack_root)
+    print(f"telemetry: {len(phase_sidecars)} phase sidecars", file=sys.stderr)
+
     findings_dir = hstack_root / "kernel-fit" / "findings"
     metrics = {
-        "token_economics": token_economics.compute(session_rows, changes),
+        "token_economics": token_economics.compute(session_rows, changes, phase_sidecars),
         "workflow_shape": workflow_shape.compute(git_commits, changes, session_rows),
         "quality_outcomes": quality_outcomes.compute(git_commits, changes),
         "overengineering": overengineering.compute(git_commits, changes, session_rows, repo),
@@ -112,7 +121,9 @@ def main(argv: list[str] | None = None) -> int:
     # Consumed by the telemetry UI; carries the same derivative-only guarantee.
     json_path = out_path.with_suffix(".json")
     payload = {
-        "schema_version": 1,
+        # 2 — token_economics gains te_4_cost_per_phase / te_5_cost_per_change
+        # (ADR-0009). Additive: every schema_version-1 key keeps its shape.
+        "schema_version": 2,
         "repo": repo.name,
         "generated": date.today().isoformat(),
         "window_days": window_days,
@@ -123,6 +134,7 @@ def main(argv: list[str] | None = None) -> int:
             "module_specs": len(module_specs),
             "commits": len(git_commits),
             "sessions": len(session_rows),
+            "phase_sidecars": len(phase_sidecars),
         },
         "watch_list": render.watch_items(metrics),
         "metrics": metrics,

package/template/scripts/telemetry/run_kernel_fit.py

@@ -49,8 +49,12 @@ def main(argv: list[str] | None = None) -> int:
     repo = args.repo.resolve()
     hstack_root = repo / "hstack"
     if not hstack_root.is_dir():
-        # Permit running against the template repo itself.
-        if (repo / "specs").is_dir() and (repo / "CLAUDE.md").is_file():
+        # Permit running against the template repo itself. CLAUDE.md is the
+        # pre-ADR-0010 kernel name — still accepted so an un-migrated tree
+        # keeps scanning.
+        if (repo / "specs").is_dir() and (
+            (repo / "KERNEL.md").is_file() or (repo / "CLAUDE.md").is_file()
+        ):
             hstack_root = repo
         else:
             print(f"error: no hstack/ directory at {repo}", file=sys.stderr)

package/template/scripts/telemetry/session_id.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Resolve the active Claude Code session id — the one heuristic, in one place.
+
+Per ADR-0009 § Neutral: `/hstack:flag` resolved the session id inline in its own
+prose; the five sidecar-emitting Skills would have duplicated that prose a sixth
+time. They call this module instead.
+
+The heuristic (unchanged from ADR-0005): Claude Code writes one `*.jsonl`
+transcript per session under `~/.claude/projects/<encoded-cwd>/`, where
+`<encoded-cwd>` is the absolute working directory with `/` replaced by `-`. The
+most recently modified file in that directory is the active session; the session
+id is its basename.
+
+Both the heuristic and the transcript layout are harness implementation details,
+not a contract (ADR-0009 § Negative). Every failure mode resolves to
+`session_id: null` — never a guess, never a halt. A null session id means the
+phase reports as *unmeasured*, which is the whole point of the null-not-zero
+rule.
+
+CLI:
+    python3 scripts/telemetry/session_id.py            # JSON on stdout, always exit 0
+    python3 scripts/telemetry/session_id.py --cwd DIR  # resolve for another dir
+
+Output:
+    {"session_id": "062b8fe8-…" | null,
+     "transcript_path": "/Users/…/062b8fe8-….jsonl" | null,
+     "message_count": 1423,
+     "source": "transcript" | "unresolved",
+     "fallback_id": "a3f9c1d2",
+     "now": "2026-08-15T09:12:44Z"}
+
+`now` is the UTC stamp at resolution time, so a Skill opening a phase gets its
+`session_id` and its `phase_opened_at` from one call. `fallback_id` is short
+random hex for callers that need a non-null id anyway (`/hstack:flag` writes
+`fallback-<id>`); sidecar emitters ignore it and write `null`.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+PROJECTS_ROOT = Path.home() / ".claude" / "projects"
+
+
+def encoded_cwd(cwd: Path | str | None = None) -> str:
+    """`/Users/jane/code/moso` → `-Users-jane-code-moso`."""
+    p = Path(cwd) if cwd is not None else Path.cwd()
+    return str(p.resolve()).replace("/", "-")
+
+
+def project_dir(cwd: Path | str | None = None, projects_root: Path | None = None) -> Path:
+    root = projects_root or PROJECTS_ROOT
+    return root / encoded_cwd(cwd)
+
+
+def utc_now_iso() -> str:
+    """ISO-8601 UTC, second precision, `Z` suffix — the sidecar timestamp format."""
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def resolve_session(cwd: Path | str | None = None,
+                    projects_root: Path | None = None) -> dict:
+    """Resolve the active session for `cwd`. Never raises; never halts."""
+    out = {
+        "session_id": None,
+        "transcript_path": None,
+        "message_count": 0,
+        "source": "unresolved",
+        "fallback_id": os.urandom(4).hex(),
+        "now": utc_now_iso(),
+    }
+    d = project_dir(cwd, projects_root)
+    try:
+        candidates = [f for f in d.glob("*.jsonl") if f.is_file()]
+    except OSError:
+        return out
+    if not candidates:
+        return out
+    try:
+        newest = max(candidates, key=lambda f: f.stat().st_mtime)
+    except OSError:
+        return out
+    out["session_id"] = newest.stem
+    out["transcript_path"] = str(newest)
+    out["source"] = "transcript"
+    out["message_count"] = _count_lines(newest)
+    return out
+
+
+def _count_lines(path: Path) -> int:
+    try:
+        with open(path, "rb") as fh:
+            return sum(1 for _ in fh)
+    except OSError:
+        return 0
+
+
+def transcript_for_session(session_id: str | None,
+                           projects_root: Path | None = None) -> Path | None:
+    """Locate a transcript by session id, across every project directory.
+
+    The sidecar carries the session id, not the path: a Conductor worktree can be
+    renamed or removed between the write and the read, and the encoded-cwd
+    directory with it. Returns None when no transcript is found — retention
+    sweep, another machine, or a harness layout change. None means *unmeasured*.
+    """
+    if not session_id or not isinstance(session_id, str):
+        return None
+    if session_id.startswith("fallback-"):
+        return None
+    root = projects_root or PROJECTS_ROOT
+    if not root.is_dir():
+        return None
+    for d in sorted(root.iterdir()):
+        if not d.is_dir():
+            continue
+        candidate = d / f"{session_id}.jsonl"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Resolve the active Claude Code session id.")
+    parser.add_argument("--cwd", type=Path, default=None,
+                        help="Directory to resolve for (default: current working directory).")
+    args = parser.parse_args(argv)
+    print(json.dumps(resolve_session(args.cwd), indent=1))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())