hstack 0.1.0

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

@@ -0,0 +1,181 @@
+"""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.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections import defaultdict
+from datetime import datetime
+from pathlib import Path
+from typing import Iterable
+
+
+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>")
+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)
+
+
+def message_text(msg) -> str:
+    if msg is None:
+        return ""
+    if isinstance(msg, str):
+        return msg
+    content = msg.get("content") if isinstance(msg, dict) else None
+    if content is None:
+        return ""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = []
+        for blk in content:
+            if isinstance(blk, dict):
+                if blk.get("type") == "text" and isinstance(blk.get("text"), str):
+                    parts.append(blk["text"])
+                else:
+                    parts.append(json.dumps(blk, default=str))
+            else:
+                parts.append(str(blk))
+        return "\n".join(parts)
+    return json.dumps(content, default=str)
+
+
+def discover_transcript_files(repo_paths: Iterable[Path]) -> list[Path]:
+    """Discover transcript jsonl files for the given consuming-repo paths.
+
+    Each repo_path corresponds to a Claude Code project dir (`-Users-...` form).
+    We accept either real repo paths (we convert) or already-converted prefixes.
+    """
+    if not PROJECTS_ROOT.exists():
+        return []
+    prefixes = []
+    for p in repo_paths:
+        p_str = str(Path(p).resolve()).replace("/", "-")
+        prefixes.append(p_str)
+        # Also match Conductor worktrees of the repo's basename
+        basename = Path(p).name
+        prefixes.append(f"-Users-hugoganet-conductor-workspaces-{basename}-")
+    files = []
+    for d in PROJECTS_ROOT.iterdir():
+        if not d.is_dir():
+            continue
+        name = d.name
+        if not any(name.startswith(prefix) or name == prefix.rstrip("-") for prefix in prefixes):
+            continue
+        for f in d.glob("*.jsonl"):
+            files.append(f)
+    return files
+
+
+def load_session(path: Path) -> list[dict]:
+    out = []
+    try:
+        with open(path, "r", errors="replace") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    out.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+    except OSError:
+        return []
+    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)."""
+    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)
+        elif t == "assistant":
+            text = message_text(r.get("message"))
+            for sa in SUBAGENT_TYPE.findall(text):
+                subagents.add(sa)
+            for h in HALT_SENTINEL.findall(text):
+                halts.append(h.lower())
+    return skill, subagents, halts
+
+
+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):
+            continue
+        if first is None or dt < first:
+            first = dt
+        if last is None or dt > last:
+            last = dt
+    return first, last
+
+
+def tally_usage(records: list[dict]) -> dict[str, int]:
+    totals: dict[str, int] = defaultdict(int)
+    for r in records:
+        if r.get("type") != "assistant":
+            continue
+        usage = (r.get("message") or {}).get("usage") or {}
+        for k in ("input_tokens", "cache_creation_input_tokens",
+                  "cache_read_input_tokens", "output_tokens"):
+            totals[k] += usage.get(k, 0) or 0
+        totals["turns"] += 1
+    return dict(totals)
+
+
+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."""
+    return (
+        totals.get("input_tokens", 0)
+        + int(totals.get("cache_creation_input_tokens", 0) * 1.25)
+        + int(totals.get("cache_read_input_tokens", 0) * 0.10)
+        + totals.get("output_tokens", 0) * 5
+    )
+
+
+def collect_session_rows(repo_paths: Iterable[Path], since: datetime | None = None) -> list[dict]:
+    """Walk every transcript for the given repos and return one row per session."""
+    out = []
+    for f in discover_transcript_files(repo_paths):
+        recs = load_session(f)
+        if not recs:
+            continue
+        skill, subagents, halts = classify_session(recs)
+        first, last = session_bounds(recs)
+        if since is not None and last is not None and last < since:
+            continue
+        totals = tally_usage(recs)
+        if totals.get("turns", 0) == 0:
+            continue
+        out.append({
+            "file": f,
+            "project_dir": f.parent.name,
+            "skill": skill,
+            "subagents": sorted(subagents),
+            "halt_reasons": halts,
+            "started_at": first,
+            "ended_at": last,
+            "totals": totals,
+            "cost_score": cost_score(totals),
+        })
+    return out

package/template/scripts/telemetry/render.py

@@ -0,0 +1,311 @@
+"""Render the metrics dict to a markdown report."""
+
+from __future__ import annotations
+
+from datetime import date
+from typing import Any
+
+
+def render_report(metrics: dict, repo_name: str, window_days: int | None) -> str:
+    lines: list[str] = []
+    lines.append(f"# hstack-telemetry — {repo_name}")
+    lines.append("")
+    lines.append(f"_Generated {date.today().isoformat()}; window: "
+                 f"{'last ' + str(window_days) + ' days' if window_days else 'all history'}._")
+    lines.append("")
+    lines.append("Retrospective observability for the hstack workflow. All metrics are derived "
+                 "from on-disk artifacts (frontmatter + bodies), git history, and Claude Code "
+                 "transcripts. This report is read-only; the artifacts are the source of truth.")
+    lines.append("")
+
+    _render_token_economics(lines, metrics.get("token_economics", {}))
+    _render_workflow_shape(lines, metrics.get("workflow_shape", {}))
+    _render_quality_outcomes(lines, metrics.get("quality_outcomes", {}))
+    _render_overengineering(lines, metrics.get("overengineering", {}))
+    _render_contract_drift(lines, metrics.get("contract_drift", {}))
+
+    _render_watch_list(lines, metrics)
+
+    return "\n".join(lines) + "\n"
+
+
+# ---------------- helpers ----------------
+
+def _h(lines: list[str], level: int, text: str) -> None:
+    lines.append("#" * level + " " + text)
+    lines.append("")
+
+
+def _p(lines: list[str], text: str) -> None:
+    lines.append(text)
+    lines.append("")
+
+
+def _table(lines: list[str], headers: list[str], rows: list[list[Any]]) -> None:
+    if not rows:
+        lines.append("_(no data)_")
+        lines.append("")
+        return
+    lines.append("| " + " | ".join(headers) + " |")
+    lines.append("|" + "|".join("---" for _ in headers) + "|")
+    for r in rows:
+        cells = ["" if v is None else str(v) for v in r]
+        lines.append("| " + " | ".join(cells) + " |")
+    lines.append("")
+
+
+# ---------------- buckets ----------------
+
+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)")
+    _p(lines, te1.get("note", ""))
+    _table(
+        lines,
+        ["skill", "sessions", "cost-score total", "cost-score / session"],
+        [[r["skill"], r["sessions"], r["cost_score_total"], r["cost_score_mean"]]
+         for r in te1.get("rows", [])],
+    )
+
+    te2 = te.get("te_2_cache_hit_per_subagent", {})
+    _h(lines, 3, "TE-2 — cache-hit ratio (per Skill, v1 coarse grain)")
+    _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.")
+    _table(
+        lines,
+        ["skill", "turns", "cache_read", "cache_creation", "ratio"],
+        [[r["skill"], r["turns"], r["cache_read"], r["cache_creation"],
+          (f"{r['ratio']:.2%}" if r["ratio"] is not None else "-")]
+         for r in te2.get("rows", [])],
+    )
+
+    te3 = te.get("te_3_subagent_entry_tax", {})
+    _h(lines, 3, "TE-3 — subagent entry-tax amortization")
+    _p(lines, te3.get("note", ""))
+    _table(
+        lines,
+        ["subagent", "appearances", "host cache_creation total", "/ invocation"],
+        [[r["subagent"], r["appearances"], r["host_cache_creation_total"],
+          r["host_cache_creation_per_invocation"]]
+         for r in te3.get("rows", [])],
+    )
+
+
+def _render_workflow_shape(lines: list[str], ws: dict) -> None:
+    _h(lines, 2, "Workflow shape")
+
+    ws1 = ws.get("ws_1_phase_duration", {})
+    _h(lines, 3, "WS-1 — phase duration (between successive implement commits)")
+    summary = ws1.get("summary")
+    if summary:
+        _table(
+            lines,
+            ["intervals counted", "median (h)", "p90 (h)", "max (h)"],
+            [[summary["count"], summary["median_h"], summary["p90_h"], summary["max_h"]]],
+        )
+    else:
+        _p(lines, "_(no implement commits in window)_")
+    _table(
+        lines,
+        ["change", "phases", "min (h)", "mean (h)", "max (h)"],
+        [[r["change"], r["phases"], r["min_h"], r["mean_h"], r["max_h"]]
+         for r in ws1.get("per_change", [])[:10]],
+    )
+
+    ws2 = ws.get("ws_2_gate_findings_density", {})
+    _h(lines, 3, "WS-2 — gate findings density")
+    _table(
+        lines,
+        ["metric", "value"],
+        [
+            ["adversarial-review total findings (all changes)", ws2.get("adversarial_review_total_findings", 0)],
+            ["changes with ≥1 adversarial finding", ws2.get("adversarial_review_changes_with_findings", 0)],
+            ["security-reviews scored", ws2.get("security_review_changes_scored", 0)],
+            ["security-review CONCERNS-or-FAIL items", ws2.get("security_review_concerns_or_fail_items", 0)],
+            ["data-reviews scored", ws2.get("data_review_changes_scored", 0)],
+            ["data-review partial/missing RLS items", ws2.get("data_review_partial_or_missing_items", 0)],
+        ],
+    )
+
+    ws4 = ws.get("ws_4_scope_amendment_rate", {})
+    _h(lines, 3, "WS-4 — scope-amendment rate (upper bound)")
+    _p(lines, ws4.get("note", ""))
+    _table(
+        lines,
+        ["metric", "value"],
+        [
+            ["total spec.md writes after ready-for-implementation", ws4.get("total_spec_writes_after_rfi", 0)],
+            ["changes with ≥1 post-RFI spec write", ws4.get("changes_with_post_rfi_writes", 0)],
+            ["rate (changes-with-amendment / total)", f"{ws4.get('rate', 0):.2%}"],
+        ],
+    )
+
+    ws6 = ws.get("ws_6_halt_reasons", {})
+    _h(lines, 3, "WS-6 — halt reasons (HSTACK-HALT sentinel)")
+    _p(lines, ws6.get("note", ""))
+    _table(
+        lines,
+        ["reason", "count"],
+        [[r["reason"], r["count"]] for r in ws6.get("rows", [])],
+    )
+
+
+def _render_quality_outcomes(lines: list[str], qo: dict) -> None:
+    _h(lines, 2, "Quality outcomes")
+
+    qo2 = qo.get("qo_2_severity_resolution_mix", {})
+    _h(lines, 3, "QO-2 — severity × resolution-type")
+    res_types = ["commit", "tech-debt", "justified-in-prose", "other"]
+    _table(
+        lines,
+        ["severity"] + res_types,
+        [[r["severity"]] + [r.get(rt, 0) for rt in res_types] for r in qo2.get("rows", [])],
+    )
+    smells = qo2.get("high_severity_in_prose_smells", [])
+    if smells:
+        _p(lines, "**High/critical findings resolved as `justified-in-prose` (smell):**")
+        _table(
+            lines,
+            ["change", "finding", "category", "severity"],
+            [[s["change"], s["finding_id"], s["category"], s["severity"]] for s in smells],
+        )
+    else:
+        _p(lines, "_No high/critical findings resolved as `justified-in-prose` — healthy._")
+
+    qo3 = qo.get("qo_3_test_immutability_audit", {})
+    _h(lines, 3, "QO-3 — test-immutability audit")
+    _p(lines, qo3.get("note", ""))
+    _p(lines, f"Authorized test-change commits: **{qo3.get('authorized_count', 0)}**")
+    cv = qo3.get("candidate_violations", [])
+    if cv:
+        _p(lines, "**Non-implement commits touching test files without canonical authorization (review manually):**")
+        _table(
+            lines,
+            ["sha", "subject", "artifact_type", "test files"],
+            [[c["sha"][:8], c["subject"][:80], c["artifact_type"] or "-",
+              ", ".join(c["test_files"][:3]) + ("…" if len(c["test_files"]) > 3 else "")]
+             for c in cv[:20]],
+        )
+    else:
+        _p(lines, "_No candidate violations found — healthy._")
+
+    qo4 = qo.get("qo_4_observed_vs_promised", {})
+    _h(lines, 3, "QO-4 — verifier observed-vs-promised (test-plan-coverage)")
+    summary = qo4.get("summary", {})
+    if summary:
+        for key, buckets in summary.items():
+            _p(lines, f"**{key}:** " + ", ".join(f"{v}={n}" for v, n in sorted(buckets.items())))
+    _table(
+        lines,
+        ["change", "edge-cases", "tenant-isolation", "performance-budgets"],
+        [[r.get("change"), r.get("edge-cases", "-"),
+          r.get("tenant-isolation", "-"), r.get("performance-budgets", "-")]
+         for r in qo4.get("per_change", [])],
+    )
+
+
+def _render_overengineering(lines: list[str], oe: dict) -> None:
+    _h(lines, 2, "Overengineering detection")
+
+    oe1 = oe.get("oe_1_artifact_to_diff_ratio", {})
+    _h(lines, 3, "OE-1 — artifact tokens per diff line")
+    _p(lines, "Ratio above ~50 tokens/line suggests heavy spec-vs-code; ratio below ~5 "
+              "suggests an under-specified change. Honest signal, not a verdict.")
+    _table(
+        lines,
+        ["change", "artifact tokens", "diff lines (implement commits)", "tokens / line"],
+        [[r["change"], r["artifact_tokens"], r["diff_lines"], r["tokens_per_diff_line"] or "-"]
+         for r in oe1.get("rows", [])],
+    )
+
+    oe3 = oe.get("oe_3_subagent_context_load_amortization", {})
+    _h(lines, 3, "OE-3 — subagent invocations × host cost")
+    _table(
+        lines,
+        ["subagent", "invocations", "host cost-score total", "/ invocation"],
+        [[r["subagent"], r["invocations"], r["host_cost_score_total"], r["cost_per_invocation"]]
+         for r in oe3.get("rows", [])],
+    )
+
+    oe5 = oe.get("oe_5_trivial_eligible_full_gauntlet", {})
+    _h(lines, 3, "OE-5 — trivial-eligible changes that ran the full gauntlet")
+    _p(lines, oe5.get("note", ""))
+    _table(
+        lines,
+        ["change", "status", "surfaces", "files touched in implement"],
+        [[r["change"], r["status"], r["surfaces"], r["files_touched_in_implement_commits"]]
+         for r in oe5.get("rows", [])],
+    )
+
+
+def _render_contract_drift(lines: list[str], cd: dict) -> None:
+    _h(lines, 2, "Contract drift")
+
+    ms = cd.get("module_spec_staleness", {})
+    _h(lines, 3, "Module-spec staleness × recent activity")
+    _table(
+        lines,
+        ["module", "spec status", "spec updated", "recent commits touching module", "drift flag"],
+        [[r["module"], r["status"], r["updated"],
+          r["recent_commits_touching_module"], "⚠️" if r["drift_flag"] else ""]
+         for r in ms.get("rows", [])],
+    )
+
+    adr = cd.get("adr_supersession_lag", {})
+    _h(lines, 3, "ADR supersession lag")
+    _table(
+        lines,
+        ["ADR", "superseded by", "lag (days)"],
+        [[r["adr"], r["superseded_by"], r["lag_days"]] for r in adr.get("rows", [])],
+    )
+
+    td = cd.get("tech_debt_half_life", {})
+    _h(lines, 3, "Tech-debt half-life by exit path")
+    summary = td.get("summary", {})
+    _table(
+        lines,
+        ["exit path", "count", "median days", "max days"],
+        [[k, v["count"], v["median_days"], v["max_days"]] for k, v in sorted(summary.items())],
+    )
+
+
+def _render_watch_list(lines: list[str], metrics: dict) -> None:
+    _h(lines, 2, "Watch list")
+    items = []
+
+    # TE-2: any Skill cache-hit below 0.5
+    te2 = metrics.get("token_economics", {}).get("te_2_cache_hit_per_subagent", {})
+    for r in te2.get("rows", []):
+        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.")
+
+    # QO-2 smells
+    smells = metrics.get("quality_outcomes", {}).get("qo_2_severity_resolution_mix", {}).get("high_severity_in_prose_smells", [])
+    if smells:
+        items.append(f"{len(smells)} high/critical adversarial finding(s) resolved as `justified-in-prose` — review.")
+
+    # QO-3 violations
+    cv = metrics.get("quality_outcomes", {}).get("qo_3_test_immutability_audit", {}).get("candidate_violations", [])
+    if cv:
+        items.append(f"{len(cv)} candidate test-immutability violations (non-implement commits touching tests without authorization).")
+
+    # WS-4 amendment rate above 30%
+    ws4 = metrics.get("workflow_shape", {}).get("ws_4_scope_amendment_rate", {})
+    rate = ws4.get("rate", 0)
+    if rate > 0.3:
+        items.append(f"Scope-amendment upper-bound rate at {rate:.0%}. If real (not just status flips), planner/test-strategist may be missing scope up front.")
+
+    # Module drift
+    ms = metrics.get("contract_drift", {}).get("module_spec_staleness", {}).get("rows", [])
+    for r in ms:
+        if r["drift_flag"]:
+            items.append(f"Module-spec drift: `{r['module']}` is `needs-refresh` with {r['recent_commits_touching_module']} recent commits.")
+
+    if not items:
+        _p(lines, "_Nothing flagged. Either everything is healthy, or the metrics need tuning._")
+        return
+    for item in items:
+        lines.append(f"- {item}")
+    lines.append("")

package/template/scripts/telemetry/report.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""hstack-telemetry — generate the retrospective report.
+
+Usage:
+    python scripts/telemetry/report.py [--repo <path>] [--window <days>] [--out <path>]
+
+Defaults:
+    --repo   : the current working directory
+    --window : 30 (days)
+    --out    : <repo>/hstack/telemetry/reports/<YYYY-MM-DD>.md
+
+The report reads:
+    - hstack/specs/changes/*/  (every change artifact)
+    - hstack/tech-debt/*.md
+    - hstack/adr/*.md
+    - hstack/specs/<module>/spec.md
+    - git log of the repo (auto-commit patterns)
+    - ~/.claude/projects/-<repo-path>-*/*.jsonl  (Claude Code transcripts)
+
+Nothing is written outside the report file. All read paths are local; no
+network calls.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from datetime import date, datetime, timedelta, timezone
+from pathlib import Path
+
+# Ensure the parent (`scripts/`) is importable so `telemetry.*` resolves the
+# same way whether run from the repo root or from elsewhere.
+_THIS = Path(__file__).resolve()
+_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.insights import (  # noqa: E402
+    token_economics, workflow_shape, quality_outcomes,
+    overengineering, contract_drift,
+)
+from telemetry import render  # noqa: E402
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Generate hstack-telemetry report.")
+    parser.add_argument("--repo", type=Path, default=Path.cwd(),
+                        help="Consuming-repo root (default: cwd).")
+    parser.add_argument("--window", type=int, default=30,
+                        help="Limit git/transcript history to last N days (default: 30; 0 = all).")
+    parser.add_argument("--out", type=Path, default=None,
+                        help="Output report path (default: <repo>/hstack/telemetry/reports/<today>.md).")
+    args = parser.parse_args(argv)
+
+    repo = args.repo.resolve()
+    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():
+            hstack_root = repo
+        else:
+            print(f"error: no hstack/ directory at {repo}", file=sys.stderr)
+            return 1
+
+    window_days: int | None = args.window if args.window > 0 else None
+    since_dt: datetime | None = (
+        datetime.now(timezone.utc) - timedelta(days=window_days)
+    ) if window_days else None
+
+    print(f"telemetry: reading {hstack_root}", file=sys.stderr)
+    changes = frontmatter.load_change_artifacts(hstack_root)
+    tech_debt = frontmatter.load_tech_debt(hstack_root)
+    adrs = frontmatter.load_adrs(hstack_root)
+    module_specs = frontmatter.load_module_specs(hstack_root)
+    print(f"telemetry: {len(changes)} changes, {len(tech_debt)} TDs, "
+          f"{len(adrs)} ADRs, {len(module_specs)} module-specs", file=sys.stderr)
+
+    print("telemetry: walking git history…", file=sys.stderr)
+    git_commits = commits.parse_commits(repo, since_days=window_days)
+    print(f"telemetry: {len(git_commits)} commits in window", file=sys.stderr)
+
+    print("telemetry: walking Claude Code transcripts…", file=sys.stderr)
+    session_rows = transcripts.collect_session_rows([repo], since=since_dt)
+    print(f"telemetry: {len(session_rows)} sessions in window", file=sys.stderr)
+
+    metrics = {
+        "token_economics": token_economics.compute(session_rows, changes),
+        "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),
+        "contract_drift": contract_drift.compute(git_commits, changes, tech_debt, adrs, module_specs),
+    }
+
+    report_md = render.render_report(metrics, repo_name=repo.name, window_days=window_days)
+
+    out_path = args.out
+    if out_path is None:
+        out_dir = hstack_root / "telemetry" / "reports"
+        out_dir.mkdir(parents=True, exist_ok=True)
+        out_path = out_dir / f"{date.today().isoformat()}.md"
+    else:
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(report_md, encoding="utf-8")
+
+    print(f"telemetry: report written to {out_path}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/template/templates/adr.md

@@ -0,0 +1,38 @@
+---
+id: ADR-<NNNN>-<slug>
+type: adr
+status: proposed                       # proposed | accepted | deprecated | superseded
+owner: <git-handle>
+decision-date: <YYYY-MM-DD>
+supersedes: null                       # ADR id when this ADR replaces another
+superseded-by: null                    # ADR id when this ADR has been replaced; reciprocal with supersedes
+related-change-specs: []
+related-modules: []
+created: <YYYY-MM-DD>
+updated: <YYYY-MM-DD>
+schema-version: 1
+---
+
+## Title
+
+_Short noun phrase._
+
+## Status
+
+_Pointer to frontmatter `status`. Note any supersession relationship._
+
+## Context
+
+_The situation that motivates the decision. The forces at play. Constraints. 2–4 paragraphs._
+
+## Decision
+
+_The choice, stated as an active sentence. One paragraph._
+
+## Consequences
+
+_Positive, negative, and neutral outcomes. Particularly the trade-offs accepted. Challenge prompt: name two consequences that look bad. If you can't, what alternative would have made them visible? 2–4 paragraphs._
+
+## Alternatives Considered
+
+_What was on the table; why each was rejected. One paragraph per alternative._