hstack 0.2.0 → 0.3.0

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/kernel-fit-finding.md

@@ -0,0 +1,62 @@
+---
+id: KF-<NNNN>-<slug>
+type: kernel-fit-finding
+status: open                           # open | acknowledged | dismissed | promoted | superseded | archived
+owner: null                            # git-handle of the triager; null until first triage
+pattern: <KF-P1 | KF-P2 | KF-P3 | …>   # detector pattern that fired; enumerated in scripts/telemetry/insights/kernel_fit.py
+confidence: medium                     # high | medium | low
+detected-by: kernel-fit-analyst
+detected-at: <ISO-8601 timestamp>
+evidence-row-count: 0                  # integer; must equal len(evidence-rows) per KF-01
+evidence-rows: []                      # YAML array of {change|adr|td, signal} dicts; one entry per row counted above
+related-findings: []                   # KF ids — prior or adjacent findings on the same kernel surface
+promoted-to: null                      # `adr:<ADR-NNNN-slug>` | `tech-debt:<TD-NNNN-slug>` | null; reciprocal with the target artifact's `promoted-from-kernel-fit`; required when status: promoted
+dismissed-reason: null                 # ≥50 chars of prose; required when status: dismissed (per KF-05)
+superseded-by: null                    # KF id when status: superseded
+created: <YYYY-MM-DD>
+updated: <YYYY-MM-DD>
+schema-version: 1
+---
+
+## Title
+
+_Short noun phrase naming the kernel-fit gap. Example: "Category-A claim spans production paths — engineer likely meant Category B."_
+
+## Pattern fired
+
+_Name the detector pattern (KF-P1 / KF-P2 / KF-P3 / …) and one paragraph describing what the detector found. Quote the pattern's defining condition from `kernel_fit.py` if helpful._
+
+## Evidence
+
+_Per evidence row, a 2–3 sentence prose summary with at least one inline citation (change-id, ADR-id, TD-id, commit-sha, kernel section). KF-01 requires `len(evidence-rows)` in frontmatter to equal `evidence-row-count`; the prose here must cite each row at least once. No prose without a citation._
+
+1. ...
+2. ...
+
+## Kernel surface implicated
+
+_Single-sentence pointer to the kernel section, template, validator rule, or Skill flow that the finding suggests revising. Examples: "`template/CLAUDE.md § Frontmatter contract` — the `internal-tooling` field"; "`template/templates/change-spec.md` frontmatter — `surfaces` enum"; "`/hstack:adversarial-review` precondition check at SKILL.md line 61"._
+
+## Proposed direction
+
+_One paragraph. Name a direction the kernel revision could take — split a flag, add an enum case, add a Skill precondition, amend a section. This is NOT a full ADR — that work is done by `spec-author` if and when the engineer invokes `/hstack:kernel-fit-promote`. Keep this as a sketch, not a specification._
+
+## Counter-explanations (challenge prompt — mandatory)
+
+_Two reasons this finding might NOT warrant a kernel change. If you cannot produce two, the analyst auto-downgrades `confidence` to `low` per KF-03. The challenge defends against false-positives the same way `## Consequences` § "name two consequences that look bad" defends ADRs._
+
+1. ...
+2. ...
+
+## Confidence rationale
+
+_One paragraph defending the `confidence` enum value against the validator rules. `high` requires `evidence-row-count >= 3` AND ≥2 distinct change-specs cited (KF-02). `medium` is the conservative default. `low` carries no notification and is appropriate when evidence is thin or the challenge prompts substantially weaken the finding._
+
+## Triage Log
+
+_Populated by `/hstack:kernel-fit-triage` and `/hstack:kernel-fit-promote` as the finding's status transitions. Section is empty until the first transition out of `open`._
+
+- `status: open → acknowledged` on `<YYYY-MM-DD>` by `<owner>`. Triggered by `/hstack:kernel-fit-triage <id> --action acknowledge`.
+- `status: open → dismissed` on `<YYYY-MM-DD>` by `<owner>`. Reason: `<dismissed-reason>`.
+- `status: acknowledged → promoted` on `<YYYY-MM-DD>` by `<owner>`. Promoted to: `<promoted-to>`. Triggered by `/hstack:kernel-fit-promote <id> --slug <adr-slug>`.
+- `status: open → superseded` on `<YYYY-MM-DD>` by the next `kernel-fit-analyst` run. Superseded by: `<superseded-by>`.