hstack 0.1.0

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

@@ -0,0 +1,115 @@
+"""Overengineering insights: OE-1 artifact/diff ratio, OE-3 context-load ×
+invocations × downstream-refs, OE-5 trivial-eligible that ran the gauntlet."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+
+from telemetry.parsers.bodies import approx_token_count
+from telemetry.parsers.commits import diff_line_count
+
+
+def compute(commits: list[dict], changes: dict, session_rows: list[dict], repo) -> dict:
+    return {
+        "oe_1_artifact_to_diff_ratio": _oe_1(changes, commits, repo),
+        "oe_3_subagent_context_load_amortization": _oe_3(session_rows, changes),
+        "oe_5_trivial_eligible_full_gauntlet": _oe_5(changes, commits),
+    }
+
+
+def _oe_1(changes: dict, commits: list[dict], repo) -> dict:
+    """OE-1: artifact tokens / code-diff lines.
+
+    Sums artifact-body token counts (approx 4 chars/token) per change, divides
+    by total diff lines on implement(<change-id>) commits for that change.
+    Ratio above ~50 is a strong overengineering signal; below ~5 the change is
+    likely under-specified for its complexity.
+    """
+    rows = []
+    for cid, arts in sorted(changes.items()):
+        artifact_tokens = 0
+        for atype, data in arts.items():
+            artifact_tokens += approx_token_count(data["body"])
+        # Sum implement-commit diffs for this change.
+        diff_lines = 0
+        for c in commits:
+            if c["artifact_type"] != "implement" or c["artifact_id"] != cid:
+                continue
+            added, removed = diff_line_count(repo, c["sha"])
+            diff_lines += added + removed
+        ratio = (artifact_tokens / diff_lines) if diff_lines > 0 else None
+        rows.append({
+            "change": cid,
+            "artifact_tokens": artifact_tokens,
+            "diff_lines": diff_lines,
+            "tokens_per_diff_line": round(ratio, 1) if ratio is not None else None,
+        })
+    rows.sort(key=lambda r: r["tokens_per_diff_line"] or 0, reverse=True)
+    return {"rows": rows}
+
+
+def _oe_3(session_rows: list[dict], changes: dict) -> dict:
+    """OE-3: per subagent, invocations × estimated context-load size.
+
+    Without sidecars to attribute downstream-reference-count, this v1 metric
+    surfaces just the subagent × invocation-count × cost dimension and lets
+    the reader eyeball which subagents are paying repeated entry-tax.
+    """
+    appearances = defaultdict(int)
+    total_cost_in_host = defaultdict(int)
+    for s in session_rows:
+        for sa in s["subagents"]:
+            appearances[sa] += 1
+            total_cost_in_host[sa] += s["cost_score"]
+    rows = []
+    for sa, n in sorted(appearances.items(), key=lambda kv: -kv[1]):
+        rows.append({
+            "subagent": sa,
+            "invocations": n,
+            "host_cost_score_total": total_cost_in_host[sa],
+            "cost_per_invocation": total_cost_in_host[sa] // n if n else 0,
+        })
+    return {"rows": rows}
+
+
+def _oe_5(changes: dict, commits: list[dict]) -> dict:
+    """OE-5: trivial-eligible changes that ran the full gauntlet.
+
+    Heuristic: change-spec at `shipped` (or any terminal state) with `trivial:
+    false`, empty `surfaces`, zero or one invariant. These are candidates that
+    might have qualified for the trivial-tag escape hatch but ran every gate.
+    """
+    candidates = []
+    for cid, arts in sorted(changes.items()):
+        spec = arts.get("change-spec")
+        if not spec:
+            continue
+        fm = spec["fm"]
+        if fm.get("trivial") is True:
+            continue
+        status = fm.get("status")
+        if status not in ("shipped", "ready-to-ship", "archived"):
+            continue
+        surfaces = fm.get("surfaces") or []
+        if surfaces:  # any declared surface disqualifies trivial-eligibility
+            continue
+        # diff size heuristic: a "trivial-eligible" change usually has <50 added lines
+        diff_total = 0
+        for c in commits:
+            if c["artifact_type"] == "implement" and c["artifact_id"] == cid:
+                # We can't get accurate line counts here without git access — use file count proxy
+                diff_total += len(c.get("files", []))
+        candidates.append({
+            "change": cid,
+            "status": status,
+            "surfaces": surfaces,
+            "files_touched_in_implement_commits": diff_total,
+        })
+    return {
+        "rows": candidates,
+        "note": (
+            "Heuristic only. A change with empty `surfaces` AND no `trivial: "
+            "true` tag is a candidate for retrospective trivial classification "
+            "— or a sign the surfaces list was under-declared."
+        ),
+    }

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

@@ -0,0 +1,131 @@
+"""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

@@ -0,0 +1,129 @@
+"""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

@@ -0,0 +1,198 @@
+"""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

@@ -0,0 +1,87 @@
+"""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)