hstack 0.7.1 → 0.17.0

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

@@ -1,131 +0,0 @@
-"""Quality-outcomes insights: QO-2 severity-resolution mix, QO-3 test-
-immutability audit, QO-4 verifier observed-vs-promised."""
-
-from __future__ import annotations
-
-from collections import defaultdict
-
-
-def compute(commits: list[dict], changes: dict) -> dict:
-    return {
-        "qo_2_severity_resolution_mix": _qo_2(changes),
-        "qo_3_test_immutability_audit": _qo_3(commits),
-        "qo_4_observed_vs_promised": _qo_4(changes),
-    }
-
-
-def _qo_2(changes: dict) -> dict:
-    """QO-2: per finding, cross-tab severity × resolution-type.
-
-    Resolution prefix is the part before the colon: commit | tech-debt |
-    justified-in-prose.
-    """
-    matrix: dict[tuple[str, str], int] = defaultdict(int)
-    smell_cases = []  # high/critical severity resolved as justified-in-prose
-    for cid, arts in changes.items():
-        adv = arts.get("adversarial-review")
-        if not adv:
-            continue
-        findings = adv["fm"].get("findings")
-        if not isinstance(findings, list):
-            continue
-        for f in findings:
-            if not isinstance(f, dict):
-                continue
-            sev = (f.get("severity") or "unknown").lower()
-            res = (f.get("resolution") or "unknown")
-            res_type = res.split(":", 1)[0].strip().lower() if isinstance(res, str) else "unknown"
-            if res_type not in ("commit", "tech-debt", "justified-in-prose"):
-                res_type = "other"
-            matrix[(sev, res_type)] += 1
-            if sev in ("high", "critical") and res_type == "justified-in-prose":
-                smell_cases.append({
-                    "change": cid,
-                    "finding_id": f.get("id"),
-                    "category": f.get("category"),
-                    "severity": sev,
-                })
-    severities = sorted({s for s, _ in matrix.keys()})
-    res_types = ["commit", "tech-debt", "justified-in-prose", "other"]
-    rows = []
-    for sev in severities:
-        row = {"severity": sev}
-        for rt in res_types:
-            row[rt] = matrix.get((sev, rt), 0)
-        rows.append(row)
-    return {
-        "rows": rows,
-        "high_severity_in_prose_smells": smell_cases,
-    }
-
-
-def _qo_3(commits: list[dict]) -> dict:
-    """QO-3: test-immutability audit.
-
-    For every commit touching a test file, check whether the body carries one
-    of the canonical authorization phrases. Unauthorized test-edit commits are
-    hard kernel violations.
-    """
-    import re
-    test_re = re.compile(r"(\.test\.|\.spec\.|/__tests__/|/__snapshots__/|^e2e/|_test\.go$)")
-    auth_re = re.compile(
-        r"Ok to (change|delete) test\s+\S+"
-        r"|Ok to update snapshot\s+\S+"
-        r"|Ok to refresh fixture\s+\S+"
-    )
-    violations = []
-    authorized = []
-    for c in commits:
-        test_files = [f for f in c.get("files", []) if test_re.search(f)]
-        if not test_files:
-            continue
-        is_implement_or_test_plan = c.get("artifact_type") in ("implement", "test-plan")
-        # New-tests-in-an-implement-commit are permitted; we can't distinguish
-        # new-vs-modified without per-file diff inspection. As a heuristic, an
-        # implement commit touching a test file without an auth phrase is
-        # treated as a candidate, not a violation. Adversarial-review-time
-        # changes to a test file without auth ARE violations regardless.
-        has_auth = bool(auth_re.search(c.get("body", "")))
-        if has_auth:
-            authorized.append({"sha": c["sha"], "subject": c["subject"], "test_files": test_files})
-        elif is_implement_or_test_plan:
-            # candidate — could be a new test write, which is permitted
-            pass
-        else:
-            violations.append({
-                "sha": c["sha"],
-                "subject": c["subject"],
-                "test_files": test_files,
-                "artifact_type": c.get("artifact_type"),
-            })
-    return {
-        "authorized_count": len(authorized),
-        "candidate_violations": violations,
-        "note": (
-            "Implement-phase commits touching test files are not flagged here "
-            "(new tests are permitted by the test-immutability protocol). "
-            "Non-implement commits touching test files without an authorization "
-            "phrase are listed as candidate violations for manual review."
-        ),
-    }
-
-
-def _qo_4(changes: dict) -> dict:
-    """QO-4: verifier observed-vs-promised, summarized from
-    verification.test-plan-coverage map."""
-    counts = defaultdict(lambda: defaultdict(int))
-    per_change = []
-    for cid, arts in sorted(changes.items()):
-        v = arts.get("verification")
-        if not v:
-            continue
-        cov = v["fm"].get("test-plan-coverage")
-        if not isinstance(cov, dict):
-            continue
-        row = {"change": cid}
-        for key, value in cov.items():
-            counts[key][str(value)] += 1
-            row[key] = value
-        per_change.append(row)
-    summary = {key: dict(buckets) for key, buckets in counts.items()}
-    return {"summary": summary, "per_change": per_change}

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

@@ -1,129 +0,0 @@
-"""Token-economics insights: TE-1 cost per change, TE-2 cache-hit ratio per
-subagent, TE-3 subagent entry-tax amortization."""
-
-from __future__ import annotations
-
-from collections import defaultdict
-
-
-def compute(session_rows: list[dict], changes: dict) -> dict:
-    """Compute the three TE metrics.
-
-    Args:
-        session_rows: from transcripts.collect_session_rows
-        changes: from frontmatter.load_change_artifacts
-
-    Returns a dict ready for rendering.
-    """
-    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),
-    }
-
-
-def _te_1(session_rows: list[dict], changes: dict) -> dict:
-    """TE-1: cost-score per change-spec.
-
-    Best-effort attribution: a session is associated with a change when its skill
-    is one of the per-change Skills and any of its user messages mention the
-    change-id. We approximate by matching skill∈{change-new, change-plan,
-    implement, verify, adversarial-review, ship, finalize, test-plan,
-    security-review, data-review, ui-brief, tech-debt-resolve}, then bucket
-    unassigned sessions under '(unassigned)'.
-
-    With sidecars present (v2 of this script), TE-1 sharpens by joining sidecar
-    change_ids directly. v1 produces a coarse-but-honest ranking.
-    """
-    per_change_skills = {
-        "change-new", "change-plan", "implement", "verify",
-        "adversarial-review", "ship", "finalize", "test-plan",
-        "security-review", "data-review", "ui-brief",
-        "tech-debt-resolve", "tech-debt-new", "tech-debt-wontfix",
-        "tech-debt-stale",
-    }
-    cost_total = defaultdict(int)
-    session_counts = defaultdict(int)
-    for s in session_rows:
-        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)
-            # ranking is the v1 surface here.
-            cost_total[s["skill"]] += s["cost_score"]
-            session_counts[s["skill"]] += 1
-    rows = []
-    for skill, total in sorted(cost_total.items(), key=lambda kv: -kv[1]):
-        sessions = session_counts[skill]
-        rows.append({
-            "skill": skill,
-            "sessions": sessions,
-            "cost_score_total": total,
-            "cost_score_mean": total // sessions if sessions else 0,
-        })
-    return {
-        "rows": rows,
-        "note": (
-            "v1 attribution is per-Skill, not per-change. Per-change cost will "
-            "sharpen once verify.json / finalize.json sidecars carry change_id."
-        ),
-    }
-
-
-def _te_2(session_rows: list[dict]) -> dict:
-    """TE-2: cache-hit ratio = cache_read / (cache_read + cache_creation) per
-    subagent appearance. Without isSidechain attribution we group by the host
-    Skill and report per-Skill cache effectiveness — same shape, coarser grain.
-    """
-    per_skill = defaultdict(lambda: {"cache_read": 0, "cache_creation": 0, "turns": 0})
-    for s in session_rows:
-        key = s["skill"] or "(non-hstack)"
-        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)
-        per_skill[key]["turns"] += t.get("turns", 0)
-    rows = []
-    for skill, agg in sorted(per_skill.items(), key=lambda kv: -(kv[1]["cache_read"] + kv[1]["cache_creation"])):
-        denom = agg["cache_read"] + agg["cache_creation"]
-        ratio = (agg["cache_read"] / denom) if denom > 0 else None
-        rows.append({
-            "skill": skill,
-            "turns": agg["turns"],
-            "cache_read": agg["cache_read"],
-            "cache_creation": agg["cache_creation"],
-            "ratio": ratio,
-        })
-    return {"rows": rows}
-
-
-def _te_3(session_rows: list[dict]) -> dict:
-    """TE-3: subagent entry-tax amortization.
-
-    For each subagent type, count invocations and aggregate the host sessions'
-    cache_creation (the entry tax is paid as cache_creation on first turn of a
-    fresh subagent). Without isSidechain attribution, this is a structural
-    proxy: high-cache_creation skills that invoke many subagents are paying
-    the entry tax over and over.
-    """
-    subagent_appearances = defaultdict(int)
-    subagent_host_cache_creation = defaultdict(int)
-    for s in session_rows:
-        for sa in s["subagents"]:
-            subagent_appearances[sa] += 1
-            subagent_host_cache_creation[sa] += s["totals"].get("cache_creation_input_tokens", 0)
-    rows = []
-    for sa, count in sorted(subagent_appearances.items(), key=lambda kv: -kv[1]):
-        rows.append({
-            "subagent": sa,
-            "appearances": count,
-            "host_cache_creation_total": subagent_host_cache_creation[sa],
-            "host_cache_creation_per_invocation": subagent_host_cache_creation[sa] // count if count else 0,
-        })
-    return {
-        "rows": rows,
-        "note": (
-            "Entry-tax attribution is approximate in v1 (isSidechain=False in "
-            "moso-app transcripts means subagent tokens land in the host "
-            "session bucket). v2 with sidecars carrying subagent start/end "
-            "timestamps will sharpen this."
-        ),
-    }

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

@@ -1,198 +0,0 @@
-"""Workflow-shape insights: WS-1 phase duration, WS-2 gate findings density,
-WS-4 scope-amendment rate."""
-
-from __future__ import annotations
-
-from collections import defaultdict
-from datetime import timedelta
-
-
-def compute(commits: list[dict], changes: dict, session_rows: list[dict]) -> dict:
-    return {
-        "ws_1_phase_duration": _ws_1(commits),
-        "ws_2_gate_findings_density": _ws_2(changes),
-        "ws_4_scope_amendment_rate": _ws_4(commits, changes),
-        "ws_6_halt_reasons": _ws_6(commits, session_rows),
-    }
-
-
-def _ws_1(commits: list[dict]) -> dict:
-    """WS-1: time between successive implement(<change-id>) phase commits.
-
-    The implementer auto-commits one commit per completed phase. The interval
-    between adjacent implement commits for the same change is a phase-duration
-    proxy. Note that this includes any cofounder time between phases (review,
-    figma work, etc.) — the metric is per-change-and-phase elapsed, not pure
-    LLM compute. v2 with sidecars (started_at / completed_at) sharpens this.
-    """
-    per_change_implement = defaultdict(list)
-    for c in commits:
-        if c["artifact_type"] != "implement":
-            continue
-        if not c["artifact_id"] or not c["timestamp"]:
-            continue
-        per_change_implement[c["artifact_id"]].append((c["timestamp"], c["phase_id"]))
-    all_intervals = []
-    per_change_rows = []
-    for cid, entries in per_change_implement.items():
-        entries.sort()
-        intervals = []
-        for i in range(1, len(entries)):
-            dt = entries[i][0] - entries[i - 1][0]
-            intervals.append(dt.total_seconds() / 3600.0)  # hours
-        if intervals:
-            per_change_rows.append({
-                "change": cid,
-                "phases": len(entries),
-                "min_h": round(min(intervals), 2),
-                "mean_h": round(sum(intervals) / len(intervals), 2),
-                "max_h": round(max(intervals), 2),
-            })
-            all_intervals.extend(intervals)
-    summary = None
-    if all_intervals:
-        all_intervals.sort()
-        n = len(all_intervals)
-        median = all_intervals[n // 2]
-        summary = {
-            "count": n,
-            "median_h": round(median, 2),
-            "p90_h": round(all_intervals[min(int(n * 0.9), n - 1)], 2),
-            "max_h": round(max(all_intervals), 2),
-        }
-    return {"summary": summary, "per_change": per_change_rows}
-
-
-def _ws_2(changes: dict) -> dict:
-    """WS-2: findings density per gate.
-
-    For each change, count findings on adversarial-review.md and PASS/CONCERNS/
-    FAIL distribution on security-review (via frontmatter scores when present)
-    and RLS-coverage on data-review. Outputs per-gate totals + per-change rows.
-    """
-    adv_findings = []
-    sec_concerns = 0
-    sec_total = 0
-    data_partial = 0
-    data_total = 0
-    per_change = []
-    for cid, arts in sorted(changes.items()):
-        adv = arts.get("adversarial-review")
-        n_findings = 0
-        if adv:
-            findings_arr = adv["fm"].get("findings") or []
-            if isinstance(findings_arr, list):
-                n_findings = len(findings_arr)
-                adv_findings.extend(findings_arr if isinstance(findings_arr, list) else [])
-        sec = arts.get("security-review")
-        sec_status = sec["fm"].get("status") if sec else None
-        if sec_status:
-            sec_total += 1
-            scores = sec["fm"].get("scores") or {}
-            if isinstance(scores, dict):
-                for v in scores.values():
-                    if isinstance(v, str) and v.upper() in ("CONCERNS", "FAIL"):
-                        sec_concerns += 1
-        dr = arts.get("data-review")
-        if dr:
-            data_total += 1
-            rls = dr["fm"].get("rls-coverage") or dr["fm"].get("RLS-coverage")
-            if isinstance(rls, dict):
-                for v in rls.values():
-                    if isinstance(v, str) and v.lower() in ("partial", "missing"):
-                        data_partial += 1
-            elif isinstance(rls, str) and rls.lower() in ("partial", "missing"):
-                data_partial += 1
-        per_change.append({
-            "change": cid,
-            "adv_findings": n_findings,
-            "security": sec_status or "-",
-            "data_review": (dr["fm"].get("status") if dr else "-"),
-        })
-    return {
-        "adversarial_review_total_findings": len(adv_findings),
-        "adversarial_review_changes_with_findings": sum(1 for r in per_change if r["adv_findings"] > 0),
-        "security_review_changes_scored": sec_total,
-        "security_review_concerns_or_fail_items": sec_concerns,
-        "data_review_changes_scored": data_total,
-        "data_review_partial_or_missing_items": data_partial,
-        "per_change": per_change,
-    }
-
-
-def _ws_4(commits: list[dict], changes: dict) -> dict:
-    """WS-4: scope-amendment rate.
-
-    For each change-spec, count commits that touch spec.md after the change-spec
-    first reaches status: ready-for-implementation. Each such commit is a
-    candidate scope amendment (or status flip — we can't tell apart without
-    diff parsing in v1). The metric tracks the upper bound.
-    """
-    spec_writes_after_rfi = defaultdict(int)
-    rfi_timestamps: dict[str, object] = {}
-
-    # First pass: locate when each change-spec first transitioned to
-    # ready-for-implementation, identified by a change-spec(<id>): ready-for-implementation
-    # commit (or any later status's predecessor).
-    for c in commits:
-        if c["artifact_type"] == "change-spec" and c["action"] and "ready-for-implementation" in c["action"]:
-            cid = c["artifact_id"]
-            if cid and cid not in rfi_timestamps:
-                rfi_timestamps[cid] = c["timestamp"]
-
-    # Second pass: count subsequent commits touching that change's spec.md.
-    for c in commits:
-        if not c["timestamp"]:
-            continue
-        for f in c["files"]:
-            # spec.md path: hstack/specs/changes/<change-id>/spec.md
-            if not f.endswith("/spec.md") or "/changes/" not in f:
-                continue
-            parts = f.split("/")
-            try:
-                cid = parts[parts.index("changes") + 1]
-            except (ValueError, IndexError):
-                continue
-            rfi_ts = rfi_timestamps.get(cid)
-            if rfi_ts is None or c["timestamp"] <= rfi_ts:
-                continue
-            spec_writes_after_rfi[cid] += 1
-    total = sum(spec_writes_after_rfi.values())
-    changes_with_amendment = len([v for v in spec_writes_after_rfi.values() if v > 0])
-    return {
-        "total_spec_writes_after_rfi": total,
-        "changes_with_post_rfi_writes": changes_with_amendment,
-        "rate": (changes_with_amendment / len(changes)) if changes else 0.0,
-        "per_change": [
-            {"change": cid, "writes_after_rfi": n}
-            for cid, n in sorted(spec_writes_after_rfi.items(), key=lambda kv: -kv[1])
-        ],
-        "note": (
-            "Upper bound: includes status-flip commits as well as content "
-            "amendments. v2 with structured spec-revision logs disambiguates."
-        ),
-    }
-
-
-def _ws_6(commits: list[dict], session_rows: list[dict]) -> dict:
-    """WS-6: halt frequency by reason.
-
-    Sources: (a) commit-body HSTACK-HALT sentinels; (b) transcript-text
-    HSTACK-HALT sentinels (when the convention is in use).
-    """
-    by_reason = defaultdict(int)
-    for c in commits:
-        for r in c.get("halt_reasons", []):
-            by_reason[r.lower()] += 1
-    for s in session_rows:
-        for r in s.get("halt_reasons", []):
-            by_reason[r.lower()] += 1
-    rows = sorted(by_reason.items(), key=lambda kv: -kv[1])
-    return {
-        "rows": [{"reason": r, "count": n} for r, n in rows],
-        "total": sum(by_reason.values()),
-        "note": (
-            "Counts are zero until the halt-sentinel convention is in use. "
-            "See kernel § Stop conditions for the HSTACK-HALT format."
-        ),
-    }

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

@@ -1,87 +0,0 @@
-"""Extract structured fragments from artifact bodies (Findings, tables, etc.)."""
-
-from __future__ import annotations
-
-import re
-
-
-SECTION_HEADING = re.compile(r"^##+\s+(?P<heading>.+?)\s*$", re.MULTILINE)
-
-
-def split_sections(body: str) -> dict[str, str]:
-    """Split a markdown body into top-level sections keyed by heading text.
-
-    All `##`-or-deeper sections are flattened — later sections with the same
-    heading overwrite earlier ones (rare in our templates)."""
-    matches = list(SECTION_HEADING.finditer(body))
-    out: dict[str, str] = {}
-    for i, m in enumerate(matches):
-        heading = m.group("heading").strip()
-        start = m.end()
-        end = matches[i + 1].start() if i + 1 < len(matches) else len(body)
-        out[heading] = body[start:end].strip()
-    return out
-
-
-# Adversarial-review findings: per-finding subsections like
-#   ### F-01
-#   **Category.** spec-compliance
-#   **What.** ...
-#   **Severity rationale.** medium ...
-#   **Resolution.** commit:abc123
-FINDING_HEADING = re.compile(r"^###\s+(F-\d+)\s*$", re.MULTILINE)
-FINDING_FIELD = re.compile(r"\*\*(?P<field>[^.*]+)\.\*\*\s*(?P<value>[^\n]*)")
-
-
-def parse_findings_section(findings_text: str) -> list[dict]:
-    """Parse the Findings section body into per-finding dicts.
-
-    Returns [{id, category, severity, status, resolution, what, why}, ...].
-    Only used as a fallback / cross-check; the frontmatter `findings:` array is
-    authoritative for category/severity/status/resolution."""
-    out = []
-    matches = list(FINDING_HEADING.finditer(findings_text))
-    for i, m in enumerate(matches):
-        fid = m.group(1)
-        start = m.end()
-        end = matches[i + 1].start() if i + 1 < len(matches) else len(findings_text)
-        block = findings_text[start:end]
-        fields = {}
-        for fm in FINDING_FIELD.finditer(block):
-            fields[fm.group("field").strip().lower()] = fm.group("value").strip()
-        out.append({
-            "id": fid,
-            "category": fields.get("category"),
-            "severity_rationale": fields.get("severity rationale"),
-            "what": fields.get("what"),
-            "why": fields.get("why it matters"),
-            "recommendation": fields.get("recommendation"),
-            "resolution": fields.get("resolution"),
-        })
-    return out
-
-
-# Plan phase overview: a three-column markdown table.
-PHASE_TABLE_LINE = re.compile(r"^\|\s*(?P<step>phase-[a-z0-9-]+)\s*\|")
-
-
-def parse_phase_overview(plan_body: str) -> list[str]:
-    """Return list of phase ids from plan.md's Phase Overview table."""
-    out = []
-    for line in plan_body.splitlines():
-        m = PHASE_TABLE_LINE.match(line)
-        if m:
-            out.append(m.group("step"))
-    return out
-
-
-def count_bullets(text: str) -> int:
-    """Count top-level bullet points (lines starting with `-` or `*`)."""
-    return sum(1 for line in text.splitlines() if re.match(r"^[-*]\s+\S", line))
-
-
-def approx_token_count(text: str) -> int:
-    """Crude token estimator: ~4 chars per token. Adequate for ratio metrics."""
-    if not text:
-        return 0
-    return max(1, len(text) // 4)