hstack 0.1.0 → 0.3.0

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

@@ -0,0 +1,438 @@
+"""Kernel-fit insights: patterns suggesting the kernel itself needs revision.
+
+This module is the detection layer of the kernel-fit closed-loop system. It
+pattern-matches across shipped artifacts and emits evidence rows; an LLM
+subagent (`kernel-fit-analyst`) then synthesizes findings from these rows.
+
+See ADR-0004 for the full design rationale and `template/CLAUDE.md` § How
+hstack improves itself for the loop contract.
+
+Three starter patterns:
+
+- KF-P1 — `category-a-claim-spans-production-paths`: changes flagged
+  `internal-tooling: true` (Category A — engineering-only) whose `in-scope`
+  touches production-code paths AND whose `enables` array is empty.
+  Under the post-PR-#5 schema (`enables` ↔ `enabled-by`, SP-13/SP-14),
+  this is the engineer mis-classifying what should be Category B
+  (foundational prerequisite) as Category A. The in-scope-overlap
+  heuristic surfaces candidate downstream consumers as evidence.
+- KF-P2 — `halt-reason-cluster-uncovered-by-enum`: halt sentinels with
+  `reason=other` whose surrounding prose clusters above the Jaccard
+  threshold, suggesting the enum is missing a case.
+- KF-P3 — `skill-precondition-violated-and-recoverable`: adversarial-review
+  spec-compliance findings whose resolution commit messages reveal a missed
+  upstream gate (the ADR-0002 pattern).
+
+Detection is pure read — no writes. Output is a dict consumed by the
+analyst subagent via the scan Skill orchestration.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+from pathlib import Path
+
+from telemetry.parsers import frontmatter as fm_parser
+from telemetry.parsers.bodies import parse_findings_section, split_sections
+
+
+# File-path prefixes that count as "internal-only" for KF-P1 classification.
+# A change whose in-scope is entirely under these prefixes is genuine
+# Category A (true internal tooling). Anything outside is candidate Category B
+# (foundational prerequisite — production code with deferred user value).
+INTERNAL_ONLY_PREFIXES = (
+    "hstack/",
+    "scripts/",
+    ".github/",
+    "template/",
+    ".claude/",
+    "docs/",
+    "ci/",
+)
+
+# Kernel-rule keywords scanned in resolution commits for KF-P3. A
+# `spec-compliance` adversarial finding whose resolving commit mentions any
+# of these is a candidate "Skill precondition should have halted earlier"
+# signal (the ADR-0002 missing-gate pattern).
+KERNEL_GATE_KEYWORDS = re.compile(
+    r"\b(precondition|missed\s+gate|should\s+have\s+halted|upstream|"
+    r"ready-for-implementation|ready-for-review|ready-to-ship|status\s+gate)\b",
+    re.IGNORECASE,
+)
+
+# Jaccard threshold for KF-P2 cluster membership. Tunable; documented in the
+# plan as a starting value. Lower → more clustering (more cluster merges,
+# fewer clusters). Higher → tighter clusters (fewer merges, more clusters).
+JACCARD_THRESHOLD = 0.6
+
+# Minimum cluster size for KF-P2 to fire. Smaller than this is noise.
+MIN_CLUSTER_SIZE = 3
+
+# Minimum candidate-row count for KF-P1 to fire. A single Category-B mislabel
+# is noise; recurrence is signal.
+KF_P1_MIN_ROWS = 2
+
+
+def compute(commits: list[dict], changes: dict, tech_debt: list[dict],
+            adrs: list[dict], module_specs: list[dict],
+            session_rows: list[dict], findings_dir: Path | None) -> dict:
+    """Run all kernel-fit detection patterns.
+
+    `findings_dir` may be `None` or non-existent on first run — the dedup
+    cross-reference returns an empty index in that case, and the analyst
+    treats every fired pattern as net-new.
+    """
+    existing = _load_existing_findings(findings_dir)
+    return {
+        "existing_open_findings_by_pattern": existing,
+        "kf_p1_category_a_claim_spans_production_paths": _kf_p1(changes, commits),
+        "kf_p2_halt_reason_cluster_uncovered_by_enum": _kf_p2(commits, session_rows),
+        "kf_p3_skill_precondition_violated_and_recoverable": _kf_p3(changes, commits),
+    }
+
+
+# ---------------- existing-findings index ----------------
+
+def _load_existing_findings(findings_dir: Path | None) -> dict:
+    """Read all KF-NNNN-*.md files in findings_dir and build an index of open
+    findings keyed by pattern. Used by the analyst for dedup / supersession
+    decisions. Tolerant of missing directory."""
+    out: dict[str, list[str]] = defaultdict(list)
+    if findings_dir is None or not findings_dir.is_dir():
+        return dict(out)
+    for path in sorted(findings_dir.glob("KF-*.md")):
+        parsed = fm_parser.read_artifact(path)
+        if parsed is None:
+            continue
+        fm, _body = parsed
+        status = fm.get("status")
+        pattern = fm.get("pattern")
+        kid = fm.get("id") or path.stem
+        if not pattern:
+            continue
+        # Only "open" and "acknowledged" findings count for dedup; promoted /
+        # dismissed / superseded / archived are terminal and do not suppress
+        # re-detection.
+        if status in ("open", "acknowledged"):
+            out[pattern].append(kid)
+    return dict(out)
+
+
+# ---------------- KF-P1 ----------------
+
+def _classify_inscope_paths(in_scope: list) -> tuple[list[str], list[str]]:
+    """Partition an in-scope list into (internal_only_paths, production_paths)."""
+    internal_only: list[str] = []
+    production: list[str] = []
+    for entry in in_scope or []:
+        if not isinstance(entry, str):
+            continue
+        path = entry.strip()
+        if not path:
+            continue
+        # Normalize leading "./" and any glob suffixes for prefix checking.
+        normalized = path[2:] if path.startswith("./") else path
+        if any(normalized.startswith(p) for p in INTERNAL_ONLY_PREFIXES):
+            internal_only.append(path)
+        else:
+            production.append(path)
+    return internal_only, production
+
+
+def _forward_consumers(this_change_id: str, this_in_scope: list[str],
+                       changes: dict, commits: list[dict]) -> list[str]:
+    """Return change-ids of later changes whose in-scope OR whose commit
+    file-lists overlap with this change's in-scope production paths."""
+    if not this_in_scope:
+        return []
+    # Build set of production-path-prefixes for cheap overlap checks. We treat
+    # each in-scope entry as a prefix; this is forgiving (catches edits inside
+    # subdirs) and matches what `internal-tooling: true` plumbing changes
+    # typically introduce (a dir of new types or a new module).
+    prefixes = {(p[2:] if p.startswith("./") else p).rstrip("/*") for p in this_in_scope}
+
+    consumers: set[str] = set()
+
+    # (1) Other change-specs whose in-scope overlaps.
+    for other_id, arts in changes.items():
+        if other_id == this_change_id:
+            continue
+        spec = arts.get("change-spec") or arts.get("spec")
+        if not spec:
+            continue
+        other_in_scope = spec["fm"].get("in-scope") or []
+        for entry in other_in_scope:
+            if not isinstance(entry, str):
+                continue
+            normalized = entry[2:] if entry.startswith("./") else entry
+            if any(normalized.startswith(p) for p in prefixes):
+                consumers.add(other_id)
+                break
+
+    # (2) Commits whose file-list touches our production paths AND whose
+    # artifact_id is a different change-spec (avoids self-attribution).
+    for c in commits:
+        cid = c.get("artifact_id")
+        if not cid or cid == this_change_id:
+            continue
+        for f in c.get("files", []):
+            normalized = f[2:] if f.startswith("./") else f
+            if any(normalized.startswith(p) for p in prefixes):
+                consumers.add(cid)
+                break
+
+    return sorted(consumers)
+
+
+def _kf_p1(changes: dict, commits: list[dict]) -> dict:
+    """KF-P1 — Category A (`internal-tooling: true`) claims whose `in-scope`
+    spans production-code paths AND whose `enables` array is empty. Under
+    the post-PR-#5 schema, this is the engineer mis-classifying what should
+    be Category B (foundational prerequisite) as Category A. SP-13 makes
+    A and B mutually exclusive at the validator level; KF-P1 catches the
+    case the validator cannot — claiming A when the in-scope reveals B.
+    Fires on >= KF_P1_MIN_ROWS candidate rows.
+    """
+    rows: list[dict] = []
+    for cid, arts in changes.items():
+        spec = arts.get("change-spec") or arts.get("spec")
+        if not spec:
+            continue
+        fm = spec["fm"]
+        if fm.get("status") != "shipped":
+            continue
+        if not fm.get("internal-tooling"):
+            continue
+        in_scope = fm.get("in-scope") or []
+        enables = fm.get("enables") or []
+        internal_paths, production_paths = _classify_inscope_paths(in_scope)
+        # Classification (post-PR-#5 schema; SP-13 enforces mutual exclusivity):
+        # - no production paths → "true-category-a" (correctly classified)
+        # - has production paths AND enables empty → "category-b-misclassified" (bug)
+        # - has production paths AND enables non-empty → impossible under SP-13;
+        #   if observed the validator failed and the analyst surfaces it separately
+        if not production_paths:
+            classification = "true-category-a"
+        elif not enables:
+            classification = "category-b-misclassified"
+        else:
+            # SP-13 violation should not reach here in a validated repo; flag
+            # explicitly so the analyst can route to a validator-bug finding.
+            classification = "sp-13-violation"
+        consumers: list[str] = []
+        if classification == "category-b-misclassified":
+            consumers = _forward_consumers(cid, production_paths or in_scope, changes, commits)
+        rows.append({
+            "change": cid,
+            "internal_only_paths_count": len(internal_paths),
+            "production_paths_count": len(production_paths),
+            "enables_count": len(enables),
+            "downstream_consumers": consumers,
+            "classification_candidate": classification,
+        })
+
+    candidate_rows = [r for r in rows
+                      if r["classification_candidate"] == "category-b-misclassified"]
+    fired = len(candidate_rows) >= KF_P1_MIN_ROWS
+    return {
+        "pattern_id": "KF-P1",
+        "pattern_name": "category-a-claim-spans-production-paths",
+        "fired": fired,
+        "evidence_row_count": len(candidate_rows),
+        "min_rows_for_firing": KF_P1_MIN_ROWS,
+        "all_rows": rows,
+        "evidence_rows": candidate_rows,
+        "note": ("Changes flagged `internal-tooling: true` (Category A) whose in-scope "
+                 "spans production-code paths AND whose `enables` array is empty. Under "
+                 "the post-PR-#5 schema (Category A vs Category B with `enables`/`enabled-by`), "
+                 "this is the engineer mis-classifying what should be Category B as Category A. "
+                 "SP-13 catches the both-set case; KF-P1 catches the claim-A-while-looking-like-B case."),
+    }
+
+
+# ---------------- KF-P2 ----------------
+
+_TOKEN_RE = re.compile(r"[a-zA-Z][a-zA-Z0-9_-]{2,}")
+
+
+def _tokens(text: str) -> set[str]:
+    """Lowercase token set from text; drops tokens <=3 chars and pure numbers."""
+    if not text:
+        return set()
+    return {t.lower() for t in _TOKEN_RE.findall(text)}
+
+
+def _jaccard(a: set[str], b: set[str]) -> float:
+    if not a or not b:
+        return 0.0
+    inter = len(a & b)
+    union = len(a | b)
+    return inter / union if union else 0.0
+
+
+def _kf_p2(commits: list[dict], session_rows: list[dict]) -> dict:
+    """KF-P2 — cluster halt sentinels with reason=other. Cluster size >=
+    MIN_CLUSTER_SIZE is evidence the enum is missing a case.
+
+    Sources: commit bodies (parser already extracted halt_reasons), and
+    session-row halt_reasons. For commits, we use the commit body as the
+    surrounding-prose context; for session rows we use the row's halt-context
+    if available, falling back to a label-only token set.
+    """
+    docs: list[dict] = []
+    for c in commits:
+        reasons = c.get("halt_reasons") or []
+        if not any(r.lower() == "other" for r in reasons):
+            continue
+        # Use commit body as the prose context — it is what the kernel
+        # contract says accompanies the sentinel.
+        context = c.get("body", "") or c.get("subject", "")
+        docs.append({
+            "source": "commit",
+            "ref": c.get("sha", "")[:8],
+            "context": context,
+            "tokens": _tokens(context),
+        })
+    for s in session_rows:
+        reasons = s.get("halt_reasons") or []
+        for r in reasons:
+            if not isinstance(r, str):
+                continue
+            if r.lower() != "other":
+                continue
+            docs.append({
+                "source": "session",
+                "ref": s.get("file", "") or s.get("skill", "") or "",
+                # Session parser does not capture surrounding prose in v1;
+                # use the session label as a degraded token source.
+                "context": s.get("skill", "") + " " + " ".join(reasons),
+                "tokens": _tokens(s.get("skill", "")),
+            })
+
+    # Greedy clustering: each new doc joins the first cluster whose
+    # representative has Jaccard >= threshold; else starts a new cluster.
+    clusters: list[list[dict]] = []
+    for d in docs:
+        placed = False
+        for cluster in clusters:
+            rep_tokens = cluster[0]["tokens"]
+            if _jaccard(d["tokens"], rep_tokens) >= JACCARD_THRESHOLD:
+                cluster.append(d)
+                placed = True
+                break
+        if not placed:
+            clusters.append([d])
+
+    evidence_clusters = [c for c in clusters if len(c) >= MIN_CLUSTER_SIZE]
+    rows = []
+    for i, cluster in enumerate(evidence_clusters):
+        rows.append({
+            "cluster_id": f"C-{i + 1}",
+            "size": len(cluster),
+            "representative_context": (cluster[0]["context"] or "")[:300],
+            "member_refs": [d["ref"] for d in cluster],
+        })
+
+    return {
+        "pattern_id": "KF-P2",
+        "pattern_name": "halt-reason-cluster-uncovered-by-enum",
+        "fired": len(evidence_clusters) > 0,
+        "evidence_row_count": len(evidence_clusters),
+        "jaccard_threshold": JACCARD_THRESHOLD,
+        "min_cluster_size": MIN_CLUSTER_SIZE,
+        "total_other_halts": len(docs),
+        "evidence_rows": rows,
+        "note": ("HSTACK-HALT sentinels with reason=other clustered by surrounding-prose "
+                 f"token overlap (Jaccard >= {JACCARD_THRESHOLD}). A cluster of "
+                 f">= {MIN_CLUSTER_SIZE} similar halts means the enum is missing a case."),
+    }
+
+
+# ---------------- KF-P3 ----------------
+
+def _commits_by_sha_prefix(commits: list[dict]) -> dict[str, dict]:
+    """Index commits by short sha (8 chars) for quick lookup. Falls back to
+    full sha if entries collide (rare with realistic repo sizes)."""
+    out: dict[str, dict] = {}
+    for c in commits:
+        sha = c.get("sha") or ""
+        if not sha:
+            continue
+        out[sha] = c
+        if len(sha) >= 8:
+            out[sha[:8]] = c
+    return out
+
+
+def _kf_p3(changes: dict, commits: list[dict]) -> dict:
+    """KF-P3 — spec-compliance adversarial findings resolved via a commit
+    whose message reveals a kernel-gate keyword. This is the pattern that
+    produced ADR-0002 (the missed `ready-for-review` transition).
+    """
+    commit_index = _commits_by_sha_prefix(commits)
+    rows: list[dict] = []
+    for cid, arts in changes.items():
+        ar = arts.get("adversarial-review")
+        if not ar:
+            continue
+        ar_fm = ar["fm"]
+        if ar_fm.get("status") != "findings-resolved":
+            continue
+        # Findings array on frontmatter is authoritative; fall back to body
+        # parser when the array is missing or absent.
+        findings = ar_fm.get("findings") or []
+        if not findings:
+            sections = split_sections(ar["body"] or "")
+            findings_section = sections.get("Findings", "")
+            findings = parse_findings_section(findings_section)
+        for f in findings:
+            if not isinstance(f, dict):
+                continue
+            category = (f.get("category") or "").lower()
+            if category != "spec-compliance":
+                continue
+            resolution = (f.get("resolution") or "").strip()
+            if not resolution.startswith("commit:"):
+                continue
+            sha_token = resolution.split(":", 1)[1].strip().split()[0]
+            commit = commit_index.get(sha_token) or commit_index.get(sha_token[:8])
+            if not commit:
+                # Still record the candidate — the analyst can decide whether
+                # missing-commit-context is itself a signal.
+                if KERNEL_GATE_KEYWORDS.search(resolution):
+                    rows.append({
+                        "change": cid,
+                        "finding_id": f.get("id"),
+                        "category": category,
+                        "resolution": resolution,
+                        "commit_subject": None,
+                        "matched_keywords": [],
+                        "commit_resolved": False,
+                    })
+                continue
+            haystack = (commit.get("subject") or "") + "\n" + (commit.get("body") or "")
+            matches = KERNEL_GATE_KEYWORDS.findall(haystack)
+            if not matches:
+                continue
+            rows.append({
+                "change": cid,
+                "finding_id": f.get("id"),
+                "category": category,
+                "resolution": resolution,
+                "commit_subject": commit.get("subject"),
+                "matched_keywords": [m.lower() for m in matches],
+                "commit_resolved": True,
+            })
+
+    return {
+        "pattern_id": "KF-P3",
+        "pattern_name": "skill-precondition-violated-and-recoverable",
+        "fired": len(rows) >= 1,
+        "evidence_row_count": len(rows),
+        "evidence_rows": rows,
+        "note": ("Adversarial spec-compliance findings whose resolving commit message "
+                 "mentions a kernel gate or precondition. Each row is a candidate "
+                 "'a Skill precondition should have halted earlier' signal — the "
+                 "ADR-0002 pattern."),
+    }

package/template/scripts/telemetry/render.py

@@ -23,6 +23,7 @@ def render_report(metrics: dict, repo_name: str, window_days: int | None) -> str
     _render_quality_outcomes(lines, metrics.get("quality_outcomes", {}))
     _render_overengineering(lines, metrics.get("overengineering", {}))
     _render_contract_drift(lines, metrics.get("contract_drift", {}))
+    _render_kernel_fit(lines, metrics.get("kernel_fit", {}))
 
     _render_watch_list(lines, metrics)
 
@@ -271,6 +272,65 @@ def _render_contract_drift(lines: list[str], cd: dict) -> None:
     )
 
 
+def _render_kernel_fit(lines: list[str], kf: dict) -> None:
+    _h(lines, 2, "Kernel-fit candidates")
+    _p(lines, "Patterns suggesting the kernel itself (CLAUDE.md, templates, validators, Skill "
+              "flows) may need revision. Each fired pattern is also written as a durable finding "
+              "by `/hstack:kernel-fit-scan` at `hstack/kernel-fit/findings/KF-NNNN-*.md`. The "
+              "table below is a rollup; the findings are the canonical artifact. See ADR-0004.")
+
+    existing = kf.get("existing_open_findings_by_pattern", {})
+    if existing:
+        total_open = sum(len(v) for v in existing.values())
+        _p(lines, f"**Currently open findings:** {total_open} "
+                  + "(" + ", ".join(f"{p}: {len(ids)}" for p, ids in sorted(existing.items())) + ")")
+
+    patterns = [
+        ("kf_p1_category_a_claim_spans_production_paths", "KF-P1 — category-a-claim-spans-production-paths"),
+        ("kf_p2_halt_reason_cluster_uncovered_by_enum", "KF-P2 — halt-reason-cluster-uncovered-by-enum"),
+        ("kf_p3_skill_precondition_violated_and_recoverable", "KF-P3 — skill-precondition-violated-and-recoverable"),
+    ]
+    for key, heading in patterns:
+        block = kf.get(key, {})
+        _h(lines, 3, heading)
+        _p(lines, block.get("note", ""))
+        fired = block.get("fired", False)
+        rc = block.get("evidence_row_count", 0)
+        if fired:
+            _p(lines, f"**Fired** — {rc} evidence row(s).")
+        else:
+            _p(lines, f"_(not fired — {rc} evidence row(s); threshold not met)_")
+
+        # Per-pattern row rendering.
+        if key == "kf_p1_category_a_claim_spans_production_paths":
+            rows = block.get("evidence_rows", [])
+            _table(
+                lines,
+                ["change", "production paths", "enables", "downstream consumers", "classification"],
+                [[r["change"], r["production_paths_count"], r["enables_count"],
+                  ", ".join(r["downstream_consumers"][:3]) + ("…" if len(r["downstream_consumers"]) > 3 else ""),
+                  r["classification_candidate"]]
+                 for r in rows[:10]],
+            )
+        elif key == "kf_p2_halt_reason_cluster_uncovered_by_enum":
+            rows = block.get("evidence_rows", [])
+            _table(
+                lines,
+                ["cluster", "size", "representative context (truncated)"],
+                [[r["cluster_id"], r["size"], r["representative_context"][:120]]
+                 for r in rows[:10]],
+            )
+        elif key == "kf_p3_skill_precondition_violated_and_recoverable":
+            rows = block.get("evidence_rows", [])
+            _table(
+                lines,
+                ["change", "finding", "matched keywords", "commit subject (truncated)"],
+                [[r["change"], r["finding_id"], ", ".join(r["matched_keywords"]),
+                  (r["commit_subject"] or "-")[:80]]
+                 for r in rows[:10]],
+            )
+
+
 def _render_watch_list(lines: list[str], metrics: dict) -> None:
     _h(lines, 2, "Watch list")
     items = []
@@ -303,6 +363,19 @@ def _render_watch_list(lines: list[str], metrics: dict) -> None:
         if r["drift_flag"]:
             items.append(f"Module-spec drift: `{r['module']}` is `needs-refresh` with {r['recent_commits_touching_module']} recent commits.")
 
+    # Kernel-fit fired patterns
+    kf = metrics.get("kernel_fit", {})
+    for key, label in (
+        ("kf_p1_category_a_claim_spans_production_paths", "KF-P1"),
+        ("kf_p2_halt_reason_cluster_uncovered_by_enum", "KF-P2"),
+        ("kf_p3_skill_precondition_violated_and_recoverable", "KF-P3"),
+    ):
+        block = kf.get(key, {})
+        if block.get("fired"):
+            rc = block.get("evidence_row_count", 0)
+            items.append(f"Kernel-fit {label} fired with {rc} evidence row(s) — "
+                         f"run `/hstack:kernel-fit-scan` to synthesize findings.")
+
     if not items:
         _p(lines, "_Nothing flagged. Either everything is healthy, or the metrics need tuning._")
         return

package/template/scripts/telemetry/report.py

@@ -39,7 +39,7 @@ if str(_SCRIPTS) not in sys.path:
 from telemetry.parsers import frontmatter, commits, transcripts  # noqa: E402
 from telemetry.insights import (  # noqa: E402
     token_economics, workflow_shape, quality_outcomes,
-    overengineering, contract_drift,
+    overengineering, contract_drift, kernel_fit,
 )
 from telemetry import render  # noqa: E402
 
@@ -85,12 +85,15 @@ def main(argv: list[str] | None = None) -> int:
     session_rows = transcripts.collect_session_rows([repo], since=since_dt)
     print(f"telemetry: {len(session_rows)} sessions in window", file=sys.stderr)
 
+    findings_dir = hstack_root / "kernel-fit" / "findings"
     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),
+        "kernel_fit": kernel_fit.compute(git_commits, changes, tech_debt, adrs, module_specs,
+                                         session_rows, findings_dir),
     }
 
     report_md = render.render_report(metrics, repo_name=repo.name, window_days=window_days)

package/template/scripts/telemetry/run_kernel_fit.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""Run the kernel-fit detection layer in isolation and dump JSON to stdout.
+
+Thin wrapper around `telemetry.insights.kernel_fit.compute()`. Used by
+`/hstack:kernel-fit-scan` to obtain the structured evidence blob the
+`kernel-fit-analyst` subagent consumes, without producing the full
+telemetry report.
+
+Usage:
+    python scripts/telemetry/run_kernel_fit.py [--repo <path>] [--window <days>]
+
+Defaults match `report.py`: `--repo` is cwd; `--window` is 30 days.
+
+The output is a single JSON object whose top-level keys mirror the
+`compute()` return value (`existing_open_findings_by_pattern`, and one
+key per pattern). The scan Skill reads stdout, parses, and passes the
+blob to the subagent.
+
+Read-only. No writes, no git side-effects.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+# Match report.py's import-path bootstrap so this script can be invoked
+# from any directory.
+_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 kernel_fit  # noqa: E402
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Run kernel-fit detection and dump JSON.")
+    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).")
+    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.
+        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
+
+    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)
+    git_commits = commits.parse_commits(repo, since_days=window_days)
+    session_rows = transcripts.collect_session_rows([repo], since=since_dt)
+
+    findings_dir = hstack_root / "kernel-fit" / "findings"
+
+    result = kernel_fit.compute(
+        commits=git_commits,
+        changes=changes,
+        tech_debt=tech_debt,
+        adrs=adrs,
+        module_specs=module_specs,
+        session_rows=session_rows,
+        findings_dir=findings_dir,
+    )
+
+    # Path objects are not JSON-serializable; strip them where they appear
+    # (existing-findings paths get re-derived by the analyst from the id).
+    json.dump(result, sys.stdout, default=str, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/template/templates/adr.md

@@ -8,9 +8,10 @@ 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: []
+promoted-from-kernel-fit: []           # KF-NNNN ids that motivated this ADR; reciprocal with kernel-fit-finding.promoted-to (KF-04)
 created: <YYYY-MM-DD>
 updated: <YYYY-MM-DD>
-schema-version: 1
+schema-version: 2
 ---
 
 ## Title

package/template/templates/change-spec.md

@@ -13,7 +13,9 @@ resolves-tech-debt: []                 # tech-debt ids this change is intended t
 parent-change: null
 children: []
 revisits-change: []                    # change-spec ids this change is filed to repair (defects, regressions, missed findings). Informational, not gating.
-internal-tooling: false
+internal-tooling: false                 # Category A — engineering-only, never on a user path
+enables: []                              # Category B — downstream change-spec ids that realize user value from this change
+enabled-by: []                           # reciprocal of upstream specs' `enables` arrays; written by /hstack:change-new at scaffold time
 trivial: false
 in-scope: []                           # repo-relative globs; must be non-empty
 out-of-scope: []                       # required, may be empty