stdtel 0.2.3__py3-none-any.whl

eval/fixtures/fastapi-min/app/main.py

@@ -0,0 +1,14 @@
+"""Minimal FastAPI app. The eval task asks for request logging to be added."""
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok"}
+
+
+@app.post("/orders")
+def create_order(order: dict):
+    return {"id": 1, "total": order.get("total", 0)}

eval/power.py

@@ -0,0 +1,199 @@
+"""Sample-size arithmetic for the skill/harness evaluation design.
+
+Every figure in docs/evaluation-power.md is produced here, so the numbers can be
+re-derived rather than trusted. `--check` fails if the committed doc has drifted.
+
+Two different questions, two different tests:
+
+  1. Does a skill raise the FIRST-TIME POLICY PASS RATE? A proportion, compared
+     between a with-skill and a without-skill arm.
+  2. Does a harness or skill change TOKENS PER MERGED PR? A continuous, strongly
+     right-skewed quantity, compared within developer under a crossover.
+
+The second needs a design effect: PRs from one developer resemble each other, so
+they carry less information than the same number of PRs from different people.
+"""
+from __future__ import annotations
+
+import argparse
+import math
+import re
+import sys
+from pathlib import Path
+from statistics import NormalDist
+
+DOC = Path(__file__).resolve().parent.parent / "docs" / "evaluation-power.md"
+
+# The one sentence that must read identically everywhere it appears: README, the
+# scorecard agent, stdtel-query and the power doc. A floor stated three different
+# ways is three different floors, and the loosest one wins in practice.
+HARD_FLOOR = ("below 30 merged PRs per arm, or fewer than 5 developers, report "
+              "descriptively and make no comparative claim")
+FLOOR_SURFACES = ("README.md", "docs/evaluation-power.md",
+                  "agents/skill-scorecard-analyst.md", "skills/stdtel-query/SKILL.md")
+ALPHA, POWER = 0.05, 0.80
+
+
+def z(p: float) -> float:
+    return NormalDist().inv_cdf(p)
+
+
+def _zsum(alpha: float, power: float) -> float:
+    return z(1 - alpha / 2) + z(power)
+
+
+def n_two_proportion(p1: float, p2: float, alpha: float = ALPHA, power: float = POWER) -> int:
+    """Per-arm PRs to detect p1 -> p2, two independent proportions, two-sided.
+
+        n = (z_{1-a/2} + z_{1-b})^2 * [p1(1-p1) + p2(1-p2)] / (p1 - p2)^2
+    """
+    if p1 == p2:
+        raise ValueError("no effect to detect")
+    return math.ceil(_zsum(alpha, power) ** 2
+                     * (p1 * (1 - p1) + p2 * (1 - p2)) / (p1 - p2) ** 2)
+
+
+def design_effect(prs_per_dev: int, icc: float) -> float:
+    """DEFF = 1 + (m-1) * ICC. Clustering by developer inflates the requirement."""
+    return 1 + (prs_per_dev - 1) * icc
+
+
+def n_token_ratio(cv: float, rel_effect: float, icc: float, prs_per_dev: int,
+                  alpha: float = ALPHA, power: float = POWER) -> int:
+    """Per-arm PRs to detect a fractional change in mean tokens per PR.
+
+        n_iid = (z_{1-a/2} + z_{1-b})^2 * 2*CV^2 / effect^2      then  x DEFF
+
+    Working on the ratio scale means the standard deviation enters as the
+    coefficient of variation, so no absolute token count is needed.
+    """
+    n_iid = _zsum(alpha, power) ** 2 * 2 * cv ** 2 / rel_effect ** 2
+    return math.ceil(n_iid * design_effect(prs_per_dev, icc))
+
+
+def n_paired_by_developer(cv: float, rel_effect: float, rho: float = 0.5,
+                          alpha: float = ALPHA, power: float = POWER) -> int:
+    """Pairs (developer-periods) when each developer contributes ONE mean per arm.
+
+    Kept only to show why this framing is wrong for our data: collapsing a
+    developer's PRs to a single mean discards the within-developer variation the
+    crossover exists to exploit, and overstates what is needed by roughly 5x.
+    """
+    sd_diff = cv * math.sqrt(2 * (1 - rho))
+    return math.ceil(_zsum(alpha, power) ** 2 * sd_diff ** 2 / rel_effect ** 2)
+
+
+# --- table rendering -------------------------------------------------------
+
+def table_pass_rate() -> str:
+    rows = [(0.60, 0.80), (0.60, 0.75), (0.60, 0.70), (0.70, 0.85), (0.70, 0.80), (0.80, 0.90)]
+    out = [f"*alpha={ALPHA}, power={POWER:.0%}, two-sided, independent arms.*", "",
+           "| baseline | with skill | absolute lift | PRs per arm |",
+           "|---|---|---|---|"]
+    for p1, p2 in rows:
+        out.append(f"| {p1:.0%} | {p2:.0%} | {p2 - p1:+.0%} | **{n_two_proportion(p1, p2)}** |")
+    return "\n".join(out)
+
+
+def table_token_ratio() -> str:
+    iccs = (0.1, 0.2, 0.4)
+    out = [f"*alpha={ALPHA}, power={POWER:.0%}, CV=0.9, m=10 PRs per developer per arm.*", "",
+           "| effect to detect | " + " | ".join(f"ICC={i}" for i in iccs) + " |",
+           "|---|" + "---|" * len(iccs)]
+    for eff in (0.40, 0.30, 0.20, 0.10):
+        cells = " | ".join(str(n_token_ratio(0.9, eff, i, 10)) for i in iccs)
+        out.append(f"| {eff:.0%} | {cells} |")
+    return "\n".join(out)
+
+
+def table_cv_sensitivity() -> str:
+    cvs = (0.6, 0.9, 1.2)
+    out = ["*Same as above at ICC=0.2, varying only the coefficient of variation.*", "",
+           "| effect to detect | " + " | ".join(f"CV={c}" for c in cvs) + " |",
+           "|---|" + "---|" * len(cvs)]
+    for eff in (0.40, 0.30, 0.20):
+        cells = " | ".join(str(n_token_ratio(c, eff, 0.2, 10)) for c in cvs)
+        out.append(f"| {eff:.0%} | {cells} |")
+    return "\n".join(out)
+
+
+def table_calendar() -> str:
+    need = n_token_ratio(0.9, 0.30, 0.2, 10)
+    out = [f"*A 30% token effect at CV=0.9, ICC=0.2 needs **{need} PRs per arm**. "
+           f"One crossover cycle = one fortnight per arm = 4 weeks.*", "",
+           "| team | PRs/dev/fortnight | PRs per arm per cycle | cycles | calendar |",
+           "|---|---|---|---|---|"]
+    for devs in (4, 8, 15, 30):
+        for prs in (3, 5):
+            per_cycle = devs * prs
+            cycles = math.ceil(need / per_cycle)
+            out.append(f"| {devs} devs | {prs} | {per_cycle} | {cycles} | ~{cycles * 4} weeks |")
+    return "\n".join(out)
+
+
+def table_correction() -> str:
+    out = ["*Why the first attempt was wrong: pairing at developer level versus "
+           "PR level with developer as a blocking factor, both for a 30% effect at CV=0.9.*", "",
+           "| framing | unit of analysis | n required | in PRs (10 per dev per arm) |",
+           "|---|---|---|---|"]
+    pairs = n_paired_by_developer(0.9, 0.30)
+    prs = n_token_ratio(0.9, 0.30, 0.2, 10)
+    out.append(f"| paired by developer (**wrong**) | developer-periods | {pairs} pairs "
+               f"| {pairs * 10} |")
+    out.append(f"| PR-level, developer as block | PRs | {prs} PRs | {prs} |")
+    return "\n".join(out)
+
+
+TABLES = {
+    "pass-rate": table_pass_rate,
+    "token-ratio": table_token_ratio,
+    "cv-sensitivity": table_cv_sensitivity,
+    "calendar": table_calendar,
+    "correction": table_correction,
+}
+BLOCK = re.compile(r"<!-- generated:(?P<name>[\w-]+) -->.*?<!-- /generated -->", re.S)
+
+
+def render(doc_text: str) -> tuple[str, list[str]]:
+    """Fill every generated block; returns (text, names filled).
+
+    The caller checks that every table was placed. An earlier version reported
+    success by counting table *definitions* rather than substitutions, so a regex
+    that matched nothing still printed "regenerated 5 tables" and left the
+    document empty.
+    """
+    filled: list[str] = []
+
+    def swap(m):
+        name = m.group("name")
+        if name not in TABLES:
+            raise SystemExit(f"unknown generated block: {name!r}")
+        filled.append(name)
+        return f"<!-- generated:{name} -->\n{TABLES[name]()}\n<!-- /generated -->"
+
+    return BLOCK.sub(swap, doc_text), filled
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="regenerate the tables in docs/evaluation-power.md")
+    ap.add_argument("--check", action="store_true", help="fail if the doc is out of date")
+    a = ap.parse_args(argv)
+    current = DOC.read_text()
+    updated, filled = render(current)
+    missing = sorted(set(TABLES) - set(filled))
+    if missing:
+        print(f"no placeholder found for: {', '.join(missing)}", file=sys.stderr)
+        return 1
+    if a.check:
+        if current != updated:
+            print("docs/evaluation-power.md is stale; run `mise run power`", file=sys.stderr)
+            return 1
+        print(f"evaluation-power.md is up to date ({len(filled)} tables verified)")
+        return 0
+    DOC.write_text(updated)
+    print(f"wrote {len(filled)} table(s) into {DOC.name}: {', '.join(filled)}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

eval/run_eval.py

@@ -0,0 +1,139 @@
+"""Offline skill evaluation runner: headless harness run + OPA grading, recorded in std.eval.* form.
+
+    stdtel-eval --harness claude-code --tasks eval/tasks.yaml --out eval/results.jsonl [--dry-run]
+
+Runners are pluggable; the default shells out to `claude -p` or `copilot` and `opa eval`.
+`--dry-run` exercises the pipeline without calling any harness (used by CI smoke test).
+"""
+from __future__ import annotations
+import argparse, json, os, re, shutil, subprocess, sys, tempfile, time, uuid
+from pathlib import Path
+import yaml
+from stdtel.manifest import load_catalogue
+
+def run_harness(harness: str, prompt: str, workdir: Path, skill_dir: Path | None, dry_run: bool) -> dict:
+    if dry_run:
+        return {"total_tokens": 1234 if skill_dir else 1500, "ok": True}
+    if harness == "claude-code":
+        env = dict(os.environ)
+        cmd = ["claude", "-p", prompt, "--output-format", "json"]
+        if skill_dir: cmd += ["--add-dir", str(skill_dir)]
+        out = subprocess.run(cmd, cwd=workdir, env=env, capture_output=True, text=True, timeout=900)
+        data = json.loads(out.stdout or "{}")
+        u = data.get("usage", {})
+        return {"total_tokens": sum(int(u.get(k, 0)) for k in ("input_tokens","output_tokens","cache_read_input_tokens","cache_creation_input_tokens")), "ok": out.returncode == 0}
+    if harness == "copilot-cli":
+        out = subprocess.run(["copilot", "-p", prompt, "--allow-all-tools"], cwd=workdir, capture_output=True, text=True, timeout=900)
+        return {"total_tokens": 0, "ok": out.returncode == 0}   # token count from OTel export, not stdout
+    raise SystemExit(f"unknown harness {harness}")
+
+GRADED_SUFFIXES = {".py", ".ts", ".tsx", ".js", ".go", ".java", ".rb", ".cs",
+                   ".yaml", ".yml", ".md"}   # .md so SKILL.md manifests are gradeable
+MAX_GRADED_BYTES = 512_000
+LOG_CALL = re.compile(r"\b(?:logger|logging|log|LOG)\s*\.\s*"
+                      r"(?:debug|info|warn|warning|error|critical|exception)\s*\(")
+
+
+def extract_log_calls(content: str) -> list[str]:
+    """The full argument list of each logging call, brackets matched.
+
+    Real log calls span several lines, so a line-bound regex misses exactly the
+    multi-line calls where a leaked field is most likely to hide. Matching
+    brackets here keeps the Rego declarative and precise instead of asking RE2
+    to approximate a parser.
+    """
+    calls = []
+    for m in LOG_CALL.finditer(content):
+        depth, i = 0, m.end() - 1
+        while i < len(content):
+            if content[i] == "(":
+                depth += 1
+            elif content[i] == ")":
+                depth -= 1
+                if depth == 0:
+                    calls.append(content[m.start():i + 1])
+                    break
+            i += 1
+        else:
+            calls.append(content[m.start():])      # unbalanced: grade what we have
+    return calls
+
+
+def build_input(workdir: Path) -> dict:
+    """The document the Rego policies evaluate.
+
+    `opa eval -i` takes a JSON file, never a directory, so the generated tree is
+    collected into {"files": [{path, content}]}. This is local grading of code the
+    eval itself produced; nothing here is emitted as telemetry (the eval record
+    carries booleans only).
+    """
+    files = []
+    for f in sorted(workdir.rglob("*")):
+        if f.is_file() and f.suffix in GRADED_SUFFIXES and f.stat().st_size <= MAX_GRADED_BYTES:
+            content = f.read_text(encoding="utf-8", errors="replace")
+            files.append({"path": str(f.relative_to(workdir)),
+                          "content": content,
+                          "log_calls": extract_log_calls(content)})
+    return {"files": files}
+
+
+def grade(workdir: Path, policies: list[str], policy_root: Path, dry_run: bool) -> dict[str, bool]:
+    """first-time policy pass per policy id. A policy that cannot be evaluated
+    fails loudly and counts as a failure — never a silent pass."""
+    if dry_run:
+        return {p: True for p in policies}
+    if not policy_root.is_dir():
+        raise SystemExit(f"policy root {policy_root} does not exist; run with --dry-run or add Rego packages")
+    results = {}
+    with tempfile.NamedTemporaryFile("w", suffix=".json", delete=False) as fh:
+        json.dump(build_input(workdir), fh)
+        input_path = fh.name
+    try:
+        for p in policies:
+            out = subprocess.run(
+                ["opa", "eval", "-d", str(policy_root), "-i", input_path, f"data.{p}.deny", "--format", "json"],
+                capture_output=True, text=True)
+            if out.returncode != 0:
+                print(f"stdtel-eval: opa failed for {p}: {out.stderr.strip()}", file=sys.stderr)
+                results[p] = False
+                continue
+            try:
+                expressions = json.loads(out.stdout)["result"][0]["expressions"][0]["value"]
+            except (KeyError, IndexError, json.JSONDecodeError) as e:
+                print(f"stdtel-eval: cannot read opa output for {p}: {e}", file=sys.stderr)
+                results[p] = False
+                continue
+            results[p] = not expressions
+    finally:
+        os.unlink(input_path)
+    return results
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--harness", default="claude-code"); ap.add_argument("--tasks", default="eval/tasks.yaml")
+    ap.add_argument("--skills", default="skills"); ap.add_argument("--policies", default="policies")
+    ap.add_argument("--out", default="eval/results.jsonl"); ap.add_argument("--dry-run", action="store_true")
+    a = ap.parse_args(argv)
+    cat = load_catalogue(Path(a.skills)); tasks = yaml.safe_load(Path(a.tasks).read_text())
+    commit = subprocess.run(["git", "rev-parse", "--short", "HEAD"], capture_output=True, text=True).stdout.strip() or "unknown"
+    n = 0
+    with open(a.out, "a") as fh:
+        for t in tasks:
+            m = cat[t["skill"]]
+            for arm in ("without", "with"):
+                with tempfile.TemporaryDirectory() as tmp:
+                    wd = Path(tmp)
+                    fx = Path("eval") / t.get("fixture", "")
+                    if fx.is_dir(): shutil.copytree(fx, wd, dirs_exist_ok=True)
+                    t0 = time.time()
+                    r = run_harness(a.harness, t["prompt"], wd, m.path.parent if arm == "with" else None, a.dry_run)
+                    g = grade(wd, t["policies"], Path(a.policies), a.dry_run)
+                    rec = {"eval_id": str(uuid.uuid4()), "task_id": t["id"], "arm": arm, "skill_name": m.name, "skill_version": m.version,
+                           "harness": a.harness, "run_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()), "passed": all(g.values()),
+                           "policy_results": g, "total_tokens": r["total_tokens"], "duration_seconds": round(time.time() - t0, 2),
+                           "catalogue_commit": commit}
+                    fh.write(json.dumps(rec) + "\n"); n += 1
+    print(f"wrote {n} eval record(s) to {a.out}"); return 0
+
+if __name__ == "__main__":
+    sys.exit(main())

stdtel/__init__.py

@@ -0,0 +1,2 @@
+"""stdtel — standards-as-skills telemetry."""
+__version__ = "0.1.0"

stdtel/doctor.py

@@ -0,0 +1,211 @@
+"""`stdtel doctor` — make a silently-broken install visible.
+
+Hooks exit 0 so telemetry never blocks the developer. The cost of that rule is
+that a broken install looks exactly like a working one: no spans and a healthy
+session are indistinguishable from the outside. Four install-time failures in
+this project's history were found by a person using it, none by its tests.
+
+Every check reports a verdict, what was observed, and **the remedy** — the part a
+diagnostic usually leaves out.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+TIMEOUT_S = 3
+
+
+@dataclass
+class Check:
+    name: str
+    ok: bool
+    detail: str
+    remedy: str = ""
+
+
+def _git_branch() -> str:
+    """Current branch, or empty when git cannot answer."""
+    try:
+        r = subprocess.run(["git", "rev-parse", "--abbrev-ref", "HEAD"],
+                           capture_output=True, text=True, timeout=TIMEOUT_S)
+        return r.stdout.strip() if r.returncode == 0 else ""
+    except Exception:                             # noqa: BLE001 - not a git repo, no git, etc.
+        return ""
+
+
+def hook_resolvable() -> Check:
+    """Can a hook actually run `stdtel-hook`?
+
+    Checked the way a hook resolves it — a non-login `sh -c` — not the way an
+    interactive shell does. Shipping the bare name failed exactly here, with
+    "command not found" on every tool call (#13), while it resolved fine in a
+    terminal because a version manager had it on PATH.
+    """
+    try:
+        # /bin/sh by absolute path: a diagnostic for a broken PATH must not need
+        # a working PATH to run, and /bin/sh is what a hook is given anyway
+        r = subprocess.run(["/bin/sh", "-c", "command -v stdtel-hook"],
+                           capture_output=True, text=True, timeout=TIMEOUT_S)
+        found = r.stdout.strip()
+    except Exception as e:                        # noqa: BLE001 - diagnostics must not raise
+        return Check("hook resolvable", False, f"could not probe: {e}",
+                     "check that `sh` is available")
+    if found:
+        return Check("hook resolvable", True, f"sh -c finds {found}")
+    which = shutil.which("stdtel-hook")
+    detail = ("not on the PATH a hook gets (sh -c); "
+              + (f"an interactive shell finds {which}" if which else "not on this shell's PATH either"))
+    return Check("hook resolvable", False, detail,
+                 "uv tool install stdtel, then `stdtel-install settings` to write an absolute path")
+
+
+def hooks_registered() -> Check:
+    """Registered once, in exactly one place.
+
+    Plugin hooks and settings hooks do not deduplicate against each other, so
+    both firing means every window is counted twice.
+    """
+    import json
+    settings = Path.home() / ".claude" / "settings.json"
+    in_settings = False
+    if settings.is_file():
+        try:
+            # Look for OUR hooks specifically. Testing `bool(hooks)` reported
+            # "registered in settings AND as a plugin" to anyone with hooks of
+            # their own — a confidently wrong warning, in the tool meant to
+            # diagnose confidently wrong behaviour.
+            raw = json.loads(settings.read_text() or "{}").get("hooks") or {}
+            in_settings = "stdtel-hook" in json.dumps(raw)
+        except json.JSONDecodeError:
+            return Check("hooks registered", False, f"{settings} is not valid JSON",
+                         "fix or remove the file, then run `stdtel-install settings`")
+    plugin = (Path.home() / ".claude" / "plugins" / "installed_plugins.json")
+    in_plugin = plugin.is_file() and "stdtel" in plugin.read_text()
+    if in_settings and in_plugin:
+        return Check("hooks registered", False, "registered in settings AND as a plugin",
+                     "remove the hooks block from ~/.claude/settings.json; plugin hooks and settings "
+                     "hooks both fire, double-counting every skill window")
+    if in_settings or in_plugin:
+        return Check("hooks registered", True,
+                     "via settings.json" if in_settings else "via the plugin")
+    return Check("hooks registered", False, "no stdtel hooks found",
+                 "run `stdtel-install settings`, or install the plugin")
+
+
+def ticket_key() -> Check:
+    """Does this branch yield a ticket key?
+
+    Only fixable now: a branch renamed tomorrow does not retroactively attribute
+    today's work, and unattributed sessions are excluded from outcome analysis.
+    """
+    from stdtel.enrich import ticket_from_branch
+    branch = os.environ.get("STDTEL_BRANCH") or _git_branch()
+    key = ticket_from_branch(branch or "")
+    if key == "unattributed":
+        return Check("ticket key", False,
+                     f"branch {branch or '(unknown)'!r} yields 'unattributed'",
+                     "rename the branch to carry a ticket key, e.g. feature/PLAT-42-thing — "
+                     "this work is excluded from outcome analysis until it does")
+    return Check("ticket key", True, f"{branch} -> {key}")
+
+
+def catalogue_ok() -> Check:
+    """Can the catalogue be found, and does it contain anything?
+
+    An empty or unfindable catalogue does not fail loudly: skills are simply
+    recorded as `unversioned`, with no standard_id and no policy_ids.
+    """
+    from stdtel.hooks.cli import _catalogue, skills_roots
+    roots = skills_roots()
+    cat = _catalogue()
+    if not roots:
+        return Check("skill catalogue", False, "no catalogue root exists",
+                     "symlink skills into ~/.claude/skills, or set STDTEL_SKILLS_ROOT")
+    if not cat:
+        return Check("skill catalogue", False,
+                     f"{len(roots)} root(s) searched, 0 skills found",
+                     "skills will record as `unversioned` with no standard_id; check "
+                     "STDTEL_SKILLS_ROOT and run `stdtel-validate` on it")
+    return Check("skill catalogue", True, f"{len(cat)} skill(s) across {len(roots)} root(s)")
+
+
+def collector_ok() -> Check:
+    """Is anything listening where spans are being sent?
+
+    A dead collector is the quietest failure of all: the exporter times out and
+    drops, leaving one stderr line no editor shows.
+    """
+    import urllib.error
+    import urllib.request
+    from stdtel.exporter import _endpoint
+    endpoint = _endpoint()
+    req = urllib.request.Request(endpoint, data=b"{}", method="POST",
+                                 headers={"content-type": "application/json"})
+    try:
+        urllib.request.urlopen(req, timeout=TIMEOUT_S)
+        return Check("collector reachable", True, f"{endpoint} answered")
+    except urllib.error.HTTPError:
+        # any HTTP status means something is listening and speaking OTLP
+        return Check("collector reachable", True, f"{endpoint} answered")
+    except Exception as e:                        # noqa: BLE001
+        return Check("collector reachable", False, f"{endpoint}: {type(e).__name__}",
+                     "spans are being dropped right now. Start the stack with `make up`, or point "
+                     "STDTEL_OTLP_ENDPOINT at a live collector (OTEL_* cannot reach a hook)")
+
+
+def recent_state() -> Check:
+    """Has a hook actually run recently? Registration alone proves nothing."""
+    from stdtel.state import state_dir
+    try:
+        files = sorted(state_dir().glob("*.json"), key=lambda p: p.stat().st_mtime, reverse=True)
+    except Exception as e:                        # noqa: BLE001
+        return Check("hooks running", False, f"cannot read state dir: {e}", "check STDTEL_STATE_DIR")
+    if not files:
+        return Check("hooks running", False, "no session state has ever been written",
+                     "the hooks are registered but not firing; run `stdtel-install where` and "
+                     "invoke stdtel-hook by hand to see the error")
+    import datetime as dt
+    newest = dt.datetime.fromtimestamp(files[0].stat().st_mtime)
+    return Check("hooks running", True, f"last session state {newest:%Y-%m-%d %H:%M}")
+
+
+CHECKS = (hook_resolvable, hooks_registered, ticket_key, catalogue_ok, collector_ok, recent_state)
+
+
+def check_all() -> list[Check]:
+    out = []
+    for fn in CHECKS:
+        try:
+            out.append(fn())
+        except Exception as e:                    # noqa: BLE001 - a diagnostic must never crash
+            out.append(Check(fn.__name__, False, f"check itself failed: {e}",
+                             "this is a bug in stdtel doctor"))
+    return out
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+    ap = argparse.ArgumentParser(prog="stdtel-doctor", description=__doc__.splitlines()[0])
+    ap.add_argument("--quiet", "-q", action="store_true", help="only show problems")
+    a = ap.parse_args(sys.argv[1:] if argv is None else argv)
+
+    checks = check_all()
+    failed = [c for c in checks if not c.ok]
+    for c in checks:
+        if c.ok and a.quiet:
+            continue
+        mark = "ok  " if c.ok else "FAIL"
+        print(f"  {mark}  {c.name:<20} {c.detail}")
+        if not c.ok and c.remedy:
+            print(f"        -> {c.remedy}")
+    print(f"\n{len(checks) - len(failed)} passed, {len(failed)} failed")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

stdtel/enrich.py

@@ -0,0 +1,59 @@
+"""Resource enrichment: join keys derived from git (ticket id, repo, team)."""
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from pathlib import Path
+
+TICKET = re.compile(r"\b([A-Z][A-Z0-9]{1,9}-\d{1,6})\b")
+
+
+def _git(args: list[str], cwd: Path | None) -> str:
+    try:
+        return subprocess.check_output(["git", *args], cwd=cwd, stderr=subprocess.DEVNULL, text=True).strip()
+    except Exception:
+        return ""
+
+
+def ticket_from_branch(branch: str) -> str:
+    m = TICKET.search(branch.upper())
+    return m.group(1) if m else "unattributed"
+
+
+# Copilot's native hook dialect is camelCase; its "VS Code compatible" dialect
+# is snake_case and indistinguishable from Claude Code's. These keys are only
+# positive evidence of Copilot, never of Claude Code.
+COPILOT_ONLY_KEYS = (("sessionId", "session_id"), ("toolName", "tool_name"),
+                     ("transcriptPath", "transcript_path"))
+
+
+def detect_harness(payload: dict | None = None) -> str | None:
+    """Harness inferred from the hook payload, or None when it cannot be told.
+
+    VS Code Copilot reads `~/.claude/settings.json` and `.claude/settings.json`
+    for hooks, so Copilot events arrive through hooks registered for Claude Code
+    and would otherwise be stamped `std.harness=claude-code` — silently
+    corrupting the cross-harness comparison this project exists to make.
+    camelCase keys prove Copilot. The snake_case dialect cannot be told apart
+    from the payload alone: set STDTEL_HARNESS in that hook's own `env` block.
+    """
+    if not payload:
+        return None
+    for camel, snake in COPILOT_ONLY_KEYS:
+        if camel in payload and snake not in payload:
+            return "copilot"      # vscode vs cli needs STDTEL_HARNESS to say
+    return None
+
+
+def resource_attributes(cwd: Path | None = None, payload: dict | None = None) -> dict:
+    branch = os.environ.get("STDTEL_BRANCH") or _git(["rev-parse", "--abbrev-ref", "HEAD"], cwd)
+    remote = os.environ.get("STDTEL_REPO") or _git(["config", "--get", "remote.origin.url"], cwd)
+    repo = re.sub(r"\.git$", "", remote.rsplit("/", 1)[-1]) if remote else "unknown"
+    return {
+        "std.ticket.id": ticket_from_branch(branch or ""),
+        "std.repo": repo,
+        "std.team": os.environ.get("STDTEL_TEAM", "unknown"),
+        "std.harness": detect_harness(payload) or os.environ.get("STDTEL_HARNESS", "claude-code"),
+        "std.harness.mode": os.environ.get("STDTEL_HARNESS_MODE", "agent"),
+    }