hstack 0.2.0 → 0.3.0

package/template/.claude/skills/hstack-kernel-fit-triage/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: hstack-kernel-fit-triage
+description: |
+  Use this skill when the engineer wants to triage an open kernel-fit finding — either acknowledge it (intent to act, not yet promoted) or dismiss it (won't pursue). The Skill is mechanical per ADR-0001: structured-elicitation loop, proposed-diff preview, Y/n confirmation, direct `Edit` writes, one atomic commit. No subagent invoked. Promotion to an ADR is a separate Skill (`/hstack:kernel-fit-promote`); this Skill never touches ADRs or change-specs. Examples:
+
+  <example>
+  Context: The engineer received a Slack nudge about KF-0001 (KF-P1, Category-A claim with production paths) and wants to acknowledge it for later promotion.
+  user: "/hstack:kernel-fit-triage KF-0001 --action acknowledge"
+  assistant: "I'll read KF-0001, print it in full, show the proposed-diff (status: open → acknowledged; owner: <git-handle>; updated: today; Triage Log entry appended), wait for Y/n, then Edit + commit `kernel-fit(KF-0001): acknowledge`. No reason is required for acknowledge. If you later decide to promote, run `/hstack:kernel-fit-promote KF-0001 --slug <adr-slug>`."
+  <commentary>
+  Acknowledge does not require a `--reason`. It is the "I've seen this, I intend to act, but I'm not promoting yet" state. The Triage Log records the transition. The finding stays at `status: acknowledged` until promote or dismiss happens.
+  </commentary>
+  </example>
+
+  <example>
+  Context: The engineer reviewed KF-0002 and decided the pattern is engineer-error, not a kernel gap.
+  user: "/hstack:kernel-fit-triage KF-0002 --action dismiss --reason \"The two changes flagged actually do have downstream consumers; the change-specs simply omitted the user-stories array because the engineer copied an old template. Not a kernel-flag issue, just stale boilerplate.\""
+  assistant: "I'll verify the reason is ≥50 characters (KF-05), read KF-0002, print the proposed-diff (status: open → dismissed; dismissed-reason: <text>; owner; updated; Triage Log entry), wait for Y/n, then commit `kernel-fit(KF-0002): dismiss`. Dismissal is terminal — re-running on this finding will surface that it's already dismissed and exit no-op."
+  <commentary>
+  Dismissal requires a reason of ≥50 characters per KF-05. The check is mechanical at validation time; the Skill enforces it at step 2. Drive-by dismissals are exactly the failure mode the rule exists to catch. The dismissed-reason is itself audit signal — a high rate of dismissals on a given pattern means either the pattern is poorly tuned or the engineer is gaming the gate.
+  </commentary>
+  </example>
+
+  <example>
+  Context: The engineer tries to dismiss a finding with too-short reason.
+  user: "/hstack:kernel-fit-triage KF-0003 --action dismiss --reason \"not relevant\""
+  assistant: "I'll halt — `dismissed-reason` is 12 characters; KF-05 requires ≥50. Drive-by dismissals defeat the audit signal. Either provide a more substantive reason or leave the finding at `open` (open is a legitimate long-term state when triage is genuinely deferred)."
+  <commentary>
+  Short-reason rejection is a hard halt. The Skill does not negotiate — write a real reason or leave the finding alone. Same shape as the deferral-check in `hstack-tech-debt-wontfix`.
+  </commentary>
+  </example>
+
+tools:
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Bash
+  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — validates the finding frontmatter flip and KF-05 (dismissed-reason ≥50 chars when status: dismissed)}}"
+---
+
+## Purpose
+
+`hstack-kernel-fit-triage` is the mechanical status-flip Skill for kernel-fit findings. It moves a finding from `status: open` to either `acknowledged` (intent to promote, not yet) or `dismissed` (won't pursue, with mandatory rationale). Per ADR-0001, the Skill performs the `Edit` writes directly in the main session — no subagent invocation; the value to write is fully determined by the engineer's invocation arguments.
+
+This Skill does not promote findings to ADRs. Promotion is a separate Skill (`/hstack:kernel-fit-promote`) with its own structured flow. This Skill also does not edit ADRs, change-specs, or any artifact outside `hstack/kernel-fit/findings/`.
+
+## When to invoke
+
+Invoke when a finding is at `status: open` and the engineer wants to:
+
+- **Acknowledge** (`--action acknowledge`): record intent to act on the finding without committing to an ADR yet. Useful when the finding is real but the team needs more thinking time, or when the right kernel-change shape is unclear.
+- **Dismiss** (`--action dismiss --reason <text>`): close the finding without pursuing a kernel change. The reason is mandatory (≥50 characters per KF-05) and becomes part of the audit trail.
+
+For findings already at `acknowledged`, re-invoking with `--action acknowledge` is a no-op; re-invoking with `--action dismiss --reason <text>` is permitted (acknowledged → dismissed is a valid transition when the engineer reconsiders). Findings at terminal status (`dismissed`, `promoted`, `superseded`, `archived`) are immutable from this Skill's perspective — the Skill halts.
+
+## Inputs
+
+- `<finding-id>` (required, positional): the finding id, e.g. `KF-0001-category-a-claim-spans-production` or the short form `KF-0001` (the Skill resolves the latter to the matching file via glob).
+- `--action <acknowledge | dismiss>` (required): the triage action.
+- `--reason <text>` (required when `--action dismiss`; forbidden when `--action acknowledge`): the dismissal rationale. Must be ≥50 characters per KF-05.
+
+## Preconditions
+
+- `hstack/kernel-fit/findings/<finding-id>*.md` exists. If missing, halt.
+- The finding is at `status: open` (or `acknowledged` when transitioning to `dismissed`). If at any other status, halt with the current status named and the explanation that the status is terminal.
+- `--action` is one of `acknowledge | dismiss` (controlled enum).
+- When `--action dismiss`, `--reason` is non-empty and ≥50 characters.
+- When `--action acknowledge`, `--reason` is absent (the Skill rejects redundant reasons to keep the audit signal clean — acknowledge reasons live in the next promote / dismiss invocation if needed).
+
+## Orchestration steps
+
+1. **Resolve the finding file.** Glob `hstack/kernel-fit/findings/<finding-id>*.md`. If zero matches, halt. If multiple matches (shouldn't happen with the immutable-id rule, but defense in depth), halt and ask the engineer to disambiguate.
+
+2. **Validate inputs against preconditions.** Walk the precondition checks above. On any failure, halt with the named reason. For the `--reason` length check (`dismiss`), surface the actual character count in the halt message so the engineer can size their next attempt.
+
+3. **Print the finding in full.** Read the resolved file and print its full body to the conversation. The engineer should re-read before committing to the triage action.
+
+4. **Compose the frontmatter edit.** Compute the exact frontmatter changes:
+
+   For `--action acknowledge`:
+   - `status: open → acknowledged`
+   - `owner: <git-handle>` (read from git config; fall back to the engineer's hstack config owner)
+   - `updated: <today>` (ISO date)
+
+   For `--action dismiss`:
+   - `status: open → dismissed` (or `acknowledged → dismissed`)
+   - `dismissed-reason: <text>` (the engineer's `--reason` verbatim)
+   - `owner: <git-handle>`
+   - `updated: <today>`
+
+5. **Compose the Triage Log append.** Compute the entry to append to the `## Triage Log` section:
+
+   For acknowledge:
+   ```
+   - `status: open → acknowledged` on <today> by <owner>. Triggered by `/hstack:kernel-fit-triage <id> --action acknowledge`.
+   ```
+
+   For dismiss:
+   ```
+   - `status: <prev> → dismissed` on <today> by <owner>. Reason: <dismissed-reason>.
+   ```
+
+   Defensive Triage Log check: if `## Triage Log` is not present in the file (legacy findings authored before the template included this section), append `\n## Triage Log\n` to the end of the file first.
+
+6. **Print the proposed diff.** Show the engineer the exact frontmatter changes and the exact Triage Log entry that will land. This is the kernel's mechanical-operations confirmation gate — until `validate-spec.ts` ships, the proposed-diff preview is the only contract check between the `Edit` and the commit.
+
+7. **Confirm.** Print "Apply triage to <finding-id>? (Y/n)". Default Yes. On `n`, abort without writing.
+
+8. **Edit + validate + commit.** On `Y`:
+   - `Edit` the file: frontmatter changes + Triage Log append.
+   - Run `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` against the file. KF-01 through KF-05 must pass; specifically KF-05 (`dismissed-reason` non-null and ≥50 chars when `status: dismissed`) gates dismissal.
+   - On validation pass: `git add` the file and commit with message `kernel-fit(<finding-id>): <action>` (e.g. `kernel-fit(KF-0001): acknowledge`).
+   - On validation failure: halt; revert via `git checkout -- <finding-file>`. Report the failing rule to the engineer.
+
+9. **Confirm completion.** Print "Triage applied: <finding-id> is now `<new-status>`. Next steps: `/hstack:kernel-fit-promote <finding-id> --slug <adr-slug>` to elevate to an ADR; or leave at <new-status> and let the next `/hstack:kernel-fit-scan` re-evaluate."
+
+## Outputs
+
+- One edit to `hstack/kernel-fit/findings/<finding-id>*.md` — frontmatter flip + Triage Log append.
+- One commit. Message: `kernel-fit(<finding-id>): <action>`.
+
+## Auto-commit triggers
+
+- One commit at the status flip. The kernel's auto-commit-at-status-transition rule applies.
+
+## Idempotency contract
+
+- Re-running with `--action acknowledge` on a finding already at `acknowledged`: no-op. The Skill prints "already acknowledged" and exits without writing.
+- Re-running with `--action dismiss` on a finding already at `dismissed`: no-op. The Skill prints "already dismissed" + the existing `dismissed-reason` and exits without writing.
+- Re-running with `--action dismiss` on a finding at `acknowledged`: permitted — the `acknowledged → dismissed` transition is valid. The Triage Log entry uses the `<prev> → dismissed` shape.
+- Re-running on a finding at `promoted`, `superseded`, or `archived`: halt with the status named. These are terminal from this Skill's perspective.
+
+## Stop conditions
+
+Beyond the kernel's general stop conditions:
+
+- The finding does not exist or is at a terminal-from-triage status (`dismissed`, `promoted`, `superseded`, `archived`). Halt with the status named.
+- `--action` is missing or not in the enum. Halt with usage.
+- `--action dismiss` without `--reason`, or with `--reason` <50 characters. Halt with the actual length count.
+- `--action acknowledge` with `--reason` present. Halt — acknowledge does not take a reason.
+- The engineer declines confirmation at step 7. Abort cleanly.
+- Validator fails at step 8 — halt with the failing rule; revert the unstaged edit.
+
+## Failure modes
+
+- **Edit fails (filesystem, validator, git).** The frontmatter flip and the Triage Log append must land together in a single auto-commit. If `Edit` succeeds but `git add` or `git commit` fails, the working tree carries the unstaged change — revert via `git checkout -- <finding-file>` and re-invoke.
+- **Drive-by dismissal attempt.** The ≥50-character check at step 2 is the v1 defense. Short reasons fail before any write occurs.
+- **Stale finding (post-scan supersession in flight).** If a concurrent `/hstack:kernel-fit-scan` has just superseded the finding the engineer is triaging, the post-edit validator would catch the inconsistent state (superseded finding cannot be re-triaged). Halt and let the engineer re-fetch the working tree.
+
+## Anti-patterns
+
+- Never invoke a subagent for triage. The action's value is fully determined by `--action` and `--reason`; the kernel's Mechanical operations section requires direct Skill writes for cases like this (saving ~25k subagent-context tokens per call).
+- Never accept a dismissal reason shorter than 50 characters. The audit signal depends on substantive rationales — drive-bys defeat the loop.
+- Never edit a finding's `pattern`, `evidence-rows`, `confidence`, or `evidence-row-count` fields. Those are the analyst's domain; triage only flips `status`, sets `owner` / `updated`, and writes `dismissed-reason` (when dismissing).
+- Never edit a `promoted` finding's `promoted-to` field. That is owned by `/hstack:kernel-fit-promote` and is reciprocally bound to the target ADR.
+- Never re-open a `dismissed` or `superseded` finding. If the kernel-fit pattern recurs with new evidence, the next `/hstack:kernel-fit-scan` will produce a new finding with a new id — that's the right path.
+- Never invoke `spec-author` for the triage action. Per ADR-0001, the Skill writes directly.

package/template/.claude/skills/hstack-telemetry/SKILL.md

@@ -31,15 +31,16 @@ tools:
 
 `hstack-telemetry` produces a retrospective observability report — a markdown file under `hstack/telemetry/reports/` — by parsing on-disk artifacts, git history, and Claude Code transcripts. The Skill is mechanical: it shells out to a Python script, reports the output path, and returns. No subagent is invoked. The kernel's "no parallel tracker" rule is preserved because the report is derivative — re-runnable from source, never authoritative.
 
-The report covers five buckets:
+The report covers six buckets:
 
 1. **Token economics** — TE-1 cost-score per Skill, TE-2 cache-hit ratio per Skill, TE-3 subagent entry-tax amortization.
 2. **Workflow shape** — WS-1 phase duration, WS-2 gate findings density, WS-4 scope-amendment rate, WS-6 halt reasons.
 3. **Quality outcomes** — QO-2 severity × resolution-type mix, QO-3 test-immutability audit, QO-4 verifier observed-vs-promised.
 4. **Overengineering** — OE-1 artifact tokens per diff line, OE-3 subagent invocations × host cost, OE-5 trivial-eligible changes that ran the full gauntlet.
 5. **Contract drift** — module-spec staleness × recent commit activity, ADR supersession lag, tech-debt half-life by exit path.
+6. **Kernel-fit candidates** — KF-P1 Category-A claim spans production paths (post-PR-#5 misclassification), KF-P2 halt-reason cluster, KF-P3 missed-gate recovery. Detection-only rollup; the canonical findings live at `hstack/kernel-fit/findings/` and are produced by `/hstack:kernel-fit-scan`. See ADR-0004.
 
-A watch-list at the report bottom surfaces anomalies (low cache-hit Skills, high-severity findings resolved as `justified-in-prose`, candidate test-immutability violations, scope-amendment rate above 30%, module drift).
+A watch-list at the report bottom surfaces anomalies (low cache-hit Skills, high-severity findings resolved as `justified-in-prose`, candidate test-immutability violations, scope-amendment rate above 30%, module drift, fired kernel-fit patterns).
 
 ## When to invoke
 

package/template/CLAUDE.md

@@ -321,6 +321,7 @@ Load-at-session-start rules by subagent:
 - `implementer`: change-spec, plan, test-plan, security-review, data-review and ui-brief and figma-handoff when present, tech-stack, infrastructure (when surfaces includes infra).
 - `verifier`: change-spec, plan, test-plan, ci-cd.
 - `adversarial-reviewer`: all change artifacts (including test-plan); explicitly no implementer transcripts.
+- `kernel-fit-analyst`: hstack/CLAUDE.md (the artifact under analysis), the latest hstack/telemetry/reports/<date>.md, every prior finding at hstack/kernel-fit/findings/, all change-specs at status: shipped (full bodies), all ADRs, all tech-debt, all module-specs; explicitly no implementer transcripts and no scratchpads from in-flight authoring sessions.
 - `researcher`: query context plus relevant product-context docs as the query requires.
 
 A subagent that cannot reach a required context document halts and asks the human, rather than proceeding without it.
@@ -390,6 +391,24 @@ When this kernel is loaded in a session that is adding or removing a Skill or su
 
 ---
 
+## How hstack improves itself
+
+hstack ships a closed-loop system for detecting when the kernel itself — this file, the templates, the validators, the Skill flows — is misaligned with how engineers and AI agents actually use it. The loop has five layers and one non-negotiable contract: **the human gates promotion to a kernel change.** Detection and synthesis can be automated; the decision to amend the kernel cannot.
+
+- **Detection is post-hoc and derivative.** `hstack/scripts/telemetry/insights/kernel_fit.py` pattern-matches across shipped change-specs, ADRs, tech-debt, halt sentinels, and adversarial-review findings. Every detection is reconstructible from git + frontmatter; the no-parallel-tracker rule is preserved because the detector reads, never writes.
+
+- **Synthesis is delegated to the `kernel-fit-analyst` subagent.** Model `opus`, loads the kernel and all shipped artifacts and every prior finding, explicitly *not* implementer transcripts (same session-isolation rule as `adversarial-reviewer`). The analyst produces one finding file per pattern at `hstack/kernel-fit/findings/KF-NNNN-<slug>.md`, with a mandatory two-bullet counter-explanation challenge prompt that defends against false-positives. Findings carry a `confidence` enum and a `status` lifecycle (`open → acknowledged → promoted` for actionable findings; `open → dismissed` for non-actionable; `open → superseded` for restated findings).
+
+- **Three Skills drive the lifecycle.** `/hstack:kernel-fit-scan` runs detection + synthesis + Slack nudge. `/hstack:kernel-fit-triage <id> --action acknowledge|dismiss --reason <text>` is a mechanical status flip per ADR-0001. `/hstack:kernel-fit-promote <id> --slug <adr-slug>` routes to `/hstack:adr-new --from-kernel-fit <id>`, mirroring the `--from-research` pattern already in use by `/hstack:research --promote`. The ADR's Context section is seeded from the finding's Evidence + Kernel Surface + Proposed Direction; `spec-author` runs the normal Nygard interview — this is the human gate. The reciprocal `promoted-to` write on the finding lands atomically with the ADR commit per the kernel's reciprocal-pair atomicity rule.
+
+- **Notification is best-effort via Slack MCP.** Threshold-gated (notify on `high` and `medium` confidence only; `low` lands silently on disk) and de-duplicated (no re-notification on an open pattern within a 14-day window). Graceful degradation: if the Slack MCP is unreachable or unwired, findings still land on disk; the Skill logs to stderr and exits 0. This is a deliberate carve-out from the kernel's general MCP-unreachable stop condition — the disk write is load-bearing, Slack is a side-channel pointer, not authoritative state.
+
+- **The analyst never writes ADRs, change-specs, or edits existing findings** (one carve-out: it may set `status: superseded` on a prior finding when restating it more cleanly). Promotion is engineer-initiated and routes through the established authoring Skills. Auto-creation of ADRs is forbidden — the kernel's "AI writes, humans confirm" contract applies most forcefully at the kernel-modification layer, where the cost of a bad ADR cascades through every subsequent change.
+
+The loop is the smallest expression of the kernel reasoning about itself without auto-modifying itself. v1 honesty: the analyst's output is an LLM-strategized judgment, not measured truth; the counter-explanation challenge is the false-positive mitigation. Same framing rule as `test-strategist` and `security-reviewer`. See ADR-0004 for the rationale; see `template/templates/kernel-fit-finding.md` for the artifact schema.
+
+---
+
 ## References
 
 - Architecture document (long-form companion): https://www.notion.so/360d6791656c813d955af822cb8814d1

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."),
+    }