hstack 0.2.0 → 0.4.0

package/template/templates/kernel-fit-finding.md

@@ -0,0 +1,63 @@
+---
+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-via: detector                 # detector | flag — `detector` (default) when the finding came from kernel_fit.py pattern matching; `flag` when the finding originated from a /hstack:flag pin (ADR-0005). For folded-in findings (flag signal merged into an existing detector-finding), `detected-via` remains `detector` because the originating signal was the detector pattern.
+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>`.

package/template/templates/kernel-fit-flag.md

@@ -0,0 +1,52 @@
+---
+id: flag-<YYYYMMDD>T<HHMMSS>-<session-id-short>
+type: kernel-fit-flag
+status: pending                          # pending | processed
+session-id: <claude-code-session-uuid>   # FL-01: non-null at pin-time
+session-transcript-path: <abs-path-to-jsonl>  # FL-01: non-null at pin-time
+branch: <current-branch>                 # FL-01: non-null at pin-time
+head: <current-HEAD-sha>                 # FL-01: non-null at pin-time
+workspace: <abs-path-to-cwd>             # FL-01: non-null at pin-time
+timestamp: <ISO-8601 timestamp at pin>   # FL-01: non-null at pin-time
+pre-compaction-message-count: <integer>  # FL-01: non-null at pin-time; analyst uses this to detect truncation between pin and scan
+hint: null                                # one-word string from --hint arg; null when no arg given
+classification: null                      # FL-02: non-null when status: processed; one of friction | missing-guardrail | kernel-vs-practice-mismatch | not-actionable | transcript-truncated
+classification-rationale: null            # FL-02: non-null when status: processed; one-line analyst note
+folded-into: null                         # KF-NNNN-<slug> when the analyst folded the signal into an existing finding
+emitted-as: null                          # KF-NNNN-<slug> when the analyst emitted a fresh finding from this pin
+created: <YYYY-MM-DD>
+updated: <YYYY-MM-DD>
+schema-version: 1
+---
+
+<!--
+A kernel-fit-flag is a frontmatter-only pin. There is no body. Engineer
+interpretation of the friction is deliberately excluded — the analyst reads
+the transcript window and forms its own classification at processing time.
+
+Validator rules (enforced by the proposed-diff preview in v1; validate-spec.ts
+is still a {{TODO-SCRIPT}} placeholder):
+
+- FL-01: at pin-time (status: pending) every field marked above as
+  "non-null at pin-time" must be populated. `hint` may be null; the four
+  analyst-owned fields (classification, classification-rationale,
+  folded-into, emitted-as) must remain null until processing.
+
+- FL-02: at processing-time (status: processed) `classification` and
+  `classification-rationale` must both be non-null. When the classification
+  produced a finding, exactly one of `folded-into` or `emitted-as` is non-null
+  (never both). When the classification did not produce a finding (closed as
+  `not-actionable` or `transcript-truncated`), both remain null.
+
+Pins are immutable from the engineer's perspective. The only legal writes
+after creation are by the kernel-fit-analyst at processing time, setting the
+four analyst-owned fields and flipping status to processed. The engineer
+cannot edit a pin to add commentary — that would re-open the contamination
+surface the analyst guards against. To add context, re-flag in a follow-up
+turn (a new pin with a different timestamp).
+
+Pins live at hstack/kernel-fit/flags/pending/ before processing and at
+hstack/kernel-fit/flags/processed/ after. The directory is gitignored in
+the consuming repo — see ADR-0005 for the rationale and the trade-off
+(provenance gap unique to this artifact type).
+-->