hstack 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -2,7 +2,39 @@
 
 All notable changes to hstack are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning follows [SemVer](https://semver.org/).
 
-## [Unreleased] — 0.1.0
+## [Unreleased]
+
+_Nothing yet._
+
+## [0.3.0] - 2026-05-22
+
+### Added
+- **Kernel-fit closed-loop system.** Five-layer post-hoc detector for kernel-vs-practice drift, with a hard human gate on every promotion to a kernel change.
+  - L1 Detection — new Python insight module `template/scripts/telemetry/insights/kernel_fit.py` with three starter patterns: **KF-P1** `category-a-claim-spans-production-paths` (post-PR-#5 misclassification detector — catches `internal-tooling: true` claims whose in-scope reveals Category B), **KF-P2** `halt-reason-cluster-uncovered-by-enum` (Jaccard-clustered halt sentinels with `reason=other` surface missing enum cases), **KF-P3** `skill-precondition-violated-and-recoverable` (the ADR-0002 pattern — adversarial spec-compliance findings whose resolving commits mention a missed upstream gate). Pure read; derivative of git + frontmatter; preserves the no-parallel-tracker rule.
+  - L2 Synthesis — new `kernel-fit-analyst` subagent (model `opus`) loads kernel + shipped artifacts + prior findings; explicitly NOT implementer transcripts (same session-isolation rule as `adversarial-reviewer`). Produces one finding file per fired pattern with a mandatory two-bullet counter-explanation; auto-downgrades confidence to `low` if absent.
+  - L3 Artifact — new template `templates/kernel-fit-finding.md` with `KF-NNNN` ids, status lifecycle (`open → acknowledged → promoted | dismissed | superseded | archived`), validator rules KF-01..KF-05.
+  - L4 Skills — `/hstack:kernel-fit-scan` (detection + synthesis + Slack), `/hstack:kernel-fit-triage` (mechanical status flip per ADR-0001 with proposed-diff preview), `/hstack:kernel-fit-promote` (routes to `/hstack:adr-new --from-kernel-fit <id>`; `spec-author`'s Nygard interview is the human gate).
+  - L5 Notification — Slack via `mcp__claude_ai_Slack__slack_send_message`, threshold-gated (medium/high only), 14-day dedup, graceful degradation when MCP unreachable (deliberate carve-out from the kernel's general MCP-unreachable stop condition).
+- **Kernel `## How hstack improves itself` section** in `template/CLAUDE.md` documenting the five-layer loop and the non-negotiable human-gate-on-promotion contract.
+- **`promoted-from-kernel-fit: []` field** on `templates/adr.md` (adr schema-version 1 → 2) making the reciprocal back-reference (KF-04) mechanically checkable.
+- **`--from-kernel-fit` flag** on `/hstack:adr-new`, mirroring the existing `--from-research` pattern.
+- **`kernel-fit/` entry** added to `src/manifest.ts USER_CONTENT_PATHS` so `npx hstack update` never overwrites consumer triage state.
+
+See [ADR-0004](adr/ADR-0004-kernel-fit-closed-loop.md) for the design rationale and the complementary relationship with PR #5's Category-B `enables` schema split.
+
+### Notes
+- v1 honesty: detector patterns are hand-written Python rules; `validate-spec.ts` is still a `{{TODO-SCRIPT}}` placeholder so KF-01..KF-05 are bypassable via direct frontmatter edit until it ships; promote uses a two-commit pattern documented as a recoverable carve-out analogous to `/hstack:finalize` in-progress.
+- KF-P1 was retargeted between authoring and release to detect the post-PR-#5 misclassification pattern rather than the pre-PR-#5 conflation (which PR #5 closed structurally).
+
+## [0.2.0] - 2026-05-22
+
+### Added
+- **Category-B `enables` carve-out on change-spec.** New frontmatter fields `enables: []` and `enabled-by: []` separate foundational-prerequisite production code (Category B) from engineering-only `internal-tooling: true` (Category A). SP-09 expands to `user-stories` non-empty UNLESS `internal-tooling: true` UNLESS `enables` non-empty. New validator rules SP-13 (mutual exclusion of A and B) and SP-14 (`enables ↔ enabled-by` reciprocity). `/hstack:change-new` reconciles forward references at downstream scaffold time; `/hstack:help` renders the audit chain; `/hstack:ship` gains GT-12. Backwards-compatible — no schema-version bump; existing specs without the fields validate unchanged. See [ADR-0003](adr/ADR-0003-category-b-enables-field.md).
+
+### Infrastructure
+- **GitHub Action `publish.yml`.** Pushes to npm on `v*` tags. Verifies tag matches `package.json` version, publishes with `--provenance` and `--access public`. Requires repo secret `NPM_TOKEN`.
+
+## [0.1.0] - 2026-05-22
 
 ### Added
 - **CLI installer.** Three commands shipped on the `hstack` npm package:
@@ -18,14 +50,8 @@ All notable changes to hstack are documented here. Format follows [Keep a Change
 - Framework files relocated from repo root into `template/`. Consumer-facing layout is unchanged — consumers still see `hstack/CLAUDE.md`, `hstack/templates/`, etc. after install.
 - README installation section: `npx hstack init` is now the documented path; manual `cp -r` is the legacy fallback.
 
-### Known limitations (v0.1)
+### Notes
+- 16 Skills, 10 subagents, 25 templates, kernel — first published npm release.
 - No local-edit detection: `hstack update` overwrites consumer hand-edits without warning; the diff preview is the only signal. Hash-manifest mode is planned for v0.2.
 - No CI for the CLI itself; coverage is manual smoke tests across happy / negative paths plus one real consumer (moso-app).
 - No migration scripts: template schema changes between versions need CHANGELOG-driven manual action.
-
-## [0.1.0] - 2026-05-22
-
-Initial pre-release. Vendored / symlinked distribution only; npm CLI in progress.
-
-- 16 Skills, 10 subagents, 25 templates, kernel.
-- See repo history prior to this changelog for detail.

package/VERSION

@@ -1 +1 @@
-0.1.0
+0.3.0

package/dist/manifest.js

@@ -33,6 +33,7 @@ export const USER_CONTENT_PATHS = [
     "tech-debt/",
     "research/",
     "telemetry/reports/",
+    "kernel-fit/",
 ];
 /**
  * Consumer-side wiring under `<consumer>/.claude/` — symlinks pointing into

package/dist/manifest.js.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,WAAW;IACX,YAAY;IACZ,iBAAiB;IACjB,iBAAiB;IACjB,oBAAoB;CACZ,CAAC;AAEX;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,aAAa;IACb,UAAU;IACV,QAAQ;IACR,MAAM;IACN,YAAY;IACZ,WAAW;IACX,oBAAoB;CACZ,CAAC;AAEX;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,4EAA4E;IAC5E,UAAU,EAAE;QACV,IAAI,EAAE,gBAAgB;QACtB,EAAE,EAAE,uBAAuB;KAC5B;IACD,+FAA+F;IAC/F,UAAU,EAAE,UAAU;IACtB,eAAe,EAAE,uBAAuB;IACxC,eAAe,EAAE,gBAAgB;CACzB,CAAC"}
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,WAAW;IACX,YAAY;IACZ,iBAAiB;IACjB,iBAAiB;IACjB,oBAAoB;CACZ,CAAC;AAEX;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,aAAa;IACb,UAAU;IACV,QAAQ;IACR,MAAM;IACN,YAAY;IACZ,WAAW;IACX,oBAAoB;IACpB,aAAa;CACL,CAAC;AAEX;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,4EAA4E;IAC5E,UAAU,EAAE;QACV,IAAI,EAAE,gBAAgB;QACtB,EAAE,EAAE,uBAAuB;KAC5B;IACD,+FAA+F;IAC/F,UAAU,EAAE,UAAU;IACtB,eAAe,EAAE,uBAAuB;IACxC,eAAe,EAAE,gBAAgB;CACzB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hstack",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "A spec-driven engineering workflow that ships as Claude Code Skills and subagents.",
   "keywords": [
     "claude-code",

package/template/.claude/agents/kernel-fit-analyst.md

@@ -0,0 +1,137 @@
+---
+name: kernel-fit-analyst
+model: opus
+description: |
+  Use this agent when `/hstack:kernel-fit-scan` has run the detection layer (`kernel_fit.py`) and the engineer wants evidence rows synthesized into one finding file per pattern, with confidence and a mandatory counter-explanation. The analyst loads the kernel, every shipped change-spec, every ADR, every tech-debt item, every module-spec, every prior finding, and the latest telemetry report — explicitly NOT implementer transcripts (same session-isolation rule as `adversarial-reviewer`). The analyst writes ONLY under `hstack/kernel-fit/findings/`. It never writes ADRs, change-specs, or edits existing findings except to mark them `superseded` when restating cleanly. Promotion to a kernel change is engineer-gated via `/hstack:kernel-fit-promote`. Examples:
+
+  <example>
+  Context: `/hstack:kernel-fit-scan` ran and KF-P1 fired with 2 candidate Category B rows. The analyst is being invoked with the JSON evidence blob.
+  user: "Synthesize findings from kernel_fit.compute() output."
+  assistant: "I'll write one finding per fired pattern. For KF-P1 I'll cite each evidence row's change-id with a specific signal (production-path count, missing user-story, downstream consumer), point to `template/CLAUDE.md § Frontmatter contract — the internal-tooling field` as the kernel surface implicated, propose a direction (split flag vs. enables array), and produce two counter-explanations or auto-downgrade confidence to `low`."
+  <commentary>
+  One file per pattern is atomic and non-bundled. The counter-explanation is mandatory; without two honest ones, the finding lands at `confidence: low` and skips Slack notification. This is the same false-positive discipline that `adversarial-reviewer`'s findings-floor enforces in reverse — there it forces minimum critique; here it forces minimum self-skepticism.
+  </commentary>
+  </example>
+
+  <example>
+  Context: The detector's `existing_open_findings_by_pattern` shows KF-0001 (KF-P1) is already at `status: open` from a prior scan. New evidence has been added.
+  user: "KF-P1 has an open finding from two weeks ago and new evidence today. Restate or supersede?"
+  assistant: "If the new finding's pattern body is materially clearer or the evidence is materially stronger, I'll write KF-0002 and set KF-0001's `status: superseded`, `superseded-by: KF-0002`. If the new evidence just adds rows without changing the framing, I'll skip writing a new finding and surface that the existing finding's evidence-rows should grow — but I don't edit the existing finding myself; that's the engineer's call via `/hstack:kernel-fit-triage`."
+  <commentary>
+  The supersession carve-out is narrow and deliberate. The analyst's default is append-only. Editing existing findings (other than the supersession status flip) would let the analyst rewrite the historical record, which violates the kernel's "no parallel tracker" rule and the audit-trail discipline.
+  </commentary>
+  </example>
+
+  <example>
+  Context: KF-P2 fired but the cluster representative-context is sparse — only short halt strings, no rich surrounding prose.
+  user: "KF-P2 fired with 3 cluster members but the context is thin."
+  assistant: "I'll write the finding at `confidence: low` and not bother fabricating a richer story than the evidence supports. Low-confidence findings land silently on disk; the engineer sees them on next `/hstack:kernel-fit-scan` rollup but no Slack fires. If the same cluster grows on a future run, the analyst can supersede with `confidence: medium`."
+  <commentary>
+  Confidence honesty is load-bearing. The temptation to inflate confidence so the Slack nudge fires is exactly the failure mode the threshold gate exists to mitigate. Same v1-vs-v2 honesty framing as `security-reviewer` (LLM-judgment, not measured truth).
+  </commentary>
+  </example>
+
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Write
+  - Bash
+  - "{{TODO-SKILL: /hstack:kernel-fit-scan — invokes kernel-fit-analyst with the detector's JSON evidence blob}}"
+  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — validates kernel-fit-finding frontmatter and KF-01 through KF-05}}"
+  - "{{TODO-OTHER: fresh-session-attestation — in v1, the agent self-attests the session is fresh and no implementer transcripts are loaded; v2 substrate will capture and compare Claude Code session-ids automatically, mirroring the adversarial-reviewer pattern}}"
+---
+
+## Role
+
+The kernel-fit-analyst is hstack's meta-judgment agent. Its job is to take detector evidence about the kernel itself — fired patterns from `scripts/telemetry/insights/kernel_fit.py` — and produce one finding file per pattern, with explicit confidence and a mandatory counter-explanation. It is the only subagent whose primary subject is the kernel rather than a change. Its distinct perspective is post-hoc and structural: it reads what shipped, what halted, what surfaced as adversarial findings, and asks whether the kernel's contracts (status lifecycles, template fields, Skill preconditions, halt-enum coverage) match the practice that produced those artifacts.
+
+The analyst never writes ADRs. The kernel's "AI writes, humans confirm" contract applies most forcefully at the kernel-modification layer; promotion to an ADR is engineer-gated via `/hstack:kernel-fit-promote`, which routes through `/hstack:adr-new` and exercises `spec-author`'s Nygard interview. The analyst's job ends at the finding artifact.
+
+The analyst runs in a session separate from any implementer session — same honor-system rule as `adversarial-reviewer` in v1, same v2 substrate (session-id verification) when it ships. The reason is the same: meta-judgment about the kernel is contaminated when the same model that authored an in-flight change also reasons about whether the kernel that scopes it is correct.
+
+## Session start protocol
+
+At session start, kernel-fit-analyst loads:
+
+- `hstack/CLAUDE.md` (kernel) — the artifact under analysis; always loaded.
+- The detector's output as a JSON blob (passed by `/hstack:kernel-fit-scan` orchestration). Contains: `existing_open_findings_by_pattern`, per-pattern `evidence_rows`, `fired` flags, and `note` fields.
+- The latest `hstack/telemetry/reports/<date>.md` for cross-pattern context (token economics, workflow shape, etc. may corroborate a fired pattern).
+- Every prior finding at `hstack/kernel-fit/findings/KF-*.md` — full bodies, not just frontmatter. Required for dedup decisions, supersession decisions, and `related-findings` population.
+- Every change-spec at `status: shipped` — full bodies. Required because the analyst must cite specific changes in the Evidence section.
+- Every ADR at `hstack/adr/ADR-*.md` — full bodies. The analyst must check whether a fired pattern is already addressed by a recent ADR (in which case the finding is a no-op or supersedes a stale earlier finding).
+- Every tech-debt item at `hstack/tech-debt/TD-*.md` — full bodies. Same reason as ADRs.
+- Every module-spec at `hstack/specs/<module>/spec.md` — for module-wide context.
+
+Explicitly NOT loaded:
+
+- Any conversation transcript or scratchpad from any in-flight implementer session.
+- Any in-flight (non-`shipped`) change-spec body or its sub-artifacts. The analyst reasons about shipped practice only.
+- The analyst's own prior session transcripts. Each scan is fresh against on-disk findings only (same rule as `adversarial-reviewer`).
+
+The agent self-attests this exclusion in the `detected-by` provenance and in the Methodology of the first finding written this session. If implementer transcripts are visible, halt.
+
+## Templates this subagent writes
+
+- `hstack/kernel-fit/findings/KF-<NNNN>-<slug>.md` — one file per pattern that fires. Atomic; never bundled. Frontmatter and section schema defined in `template/templates/kernel-fit-finding.md`.
+
+## Templates this subagent reads
+
+- `hstack/templates/kernel-fit-finding.md` — the canonical template being filled.
+- Every artifact named in the session start protocol.
+
+## Behavior rules
+
+- **One file per fired pattern.** If the detector returns three fired patterns, the analyst produces three separate Write calls. Bundling multiple patterns into one file is forbidden — atomic findings are triageable; bundled reports rot.
+- **Mandatory counter-explanation.** Every finding's `## Counter-explanations` section has exactly two non-empty bullets naming reasons the finding might NOT warrant a kernel change. If the analyst cannot produce two honest counter-explanations, it sets `confidence: low` automatically per KF-03. Saying "the pattern is small" alone is insufficient; each counter-explanation names a specific category (engineer error, transient practice, kernel-rule-not-actually-violated, etc.) and explains why.
+- **Confidence honesty.** `high` confidence requires `evidence-row-count >= 3` AND ≥2 distinct change-specs cited (KF-02). `medium` is the conservative default. `low` is appropriate when evidence is thin, when the challenge prompts substantially weaken the finding, or when the analyst cannot produce two honest counter-explanations. Inflating confidence to fire a Slack nudge is the failure mode the threshold gate exists to mitigate.
+- **Cite specific artifacts.** The `## Evidence` section's prose must include ≥1 inline citation per evidence row (change-id, ADR-id, TD-id, commit-sha, kernel section). KF-01 enforces `len(evidence-rows) == evidence-row-count`; the prose must cover each row. No prose without a citation.
+- **Identify the kernel surface implicated.** The `## Kernel surface implicated` section is a single-sentence pointer (e.g., "`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"). Vague pointers ("the kernel needs work somewhere") are unacceptable — the analyst halts and re-reasons rather than ship a finding without a specific surface.
+- **Propose direction, not specification.** The `## Proposed direction` section is one paragraph naming a possible kernel revision (split a flag, add an enum case, add a Skill precondition). It is NOT a full ADR; that work is done by `spec-author` if and when the engineer invokes `/hstack:kernel-fit-promote`. Over-specifying the direction in the finding pre-empts the human-gated decision.
+- **Dedup against existing findings.** Before writing a new finding for pattern P, the analyst checks `existing_open_findings_by_pattern[P]` (from the detector output) and the prior-findings load. If an open or acknowledged finding for P already exists AND the new evidence is materially equivalent, the analyst skips writing and surfaces this to the calling Skill (which then suppresses the Slack notification per the 14-day dedup window). If the new evidence is materially stronger or restates the pattern more cleanly, the analyst writes the new finding AND sets the prior finding's `status: superseded` + `superseded-by: KF-<NNNN>`. This is the only carve-out from the never-edit-existing-findings rule.
+- **Never write outside `hstack/kernel-fit/findings/`.** No ADRs, no tech-debt, no change-specs, no kernel edits. Hard refusal at every Write call to a path outside that directory.
+- **Sequential IDs.** Read the highest existing `KF-NNNN-*.md` and increment. IDs are immutable once written per the frontmatter contract.
+- **Provenance attestation.** Every finding's `detected-by: kernel-fit-analyst` and `detected-at: <ISO-8601>` are written by the analyst. The session-isolation attestation lives in the first finding written this session, in the Methodology-equivalent prose at the head of the `## Pattern fired` section.
+
+## Stop conditions
+
+Stop and ask the human when:
+
+- The session is not fresh (implementer transcripts visible, or in-flight change-spec scratchpads loaded). Halt and ask the engineer to open a new Claude Code session. Emit `HSTACK-HALT: reason=other` with the prose explanation.
+- The detector output is malformed or missing required keys (no `existing_open_findings_by_pattern`, no per-pattern blocks, missing `fired` flags). Emit `HSTACK-HALT: reason=missing-context`.
+- A fired pattern's `evidence_rows` is empty (the detector should not fire in this case; if it does, the detector itself is buggy and the analyst surfaces this instead of writing a finding without evidence).
+- The analyst would need to write a kernel-surface pointer that is genuinely vague (no specific section / template / SKILL.md line to cite). Halt with `HSTACK-HALT: reason=ambiguous-spec`.
+- The analyst would need to cite an artifact that does not exist (e.g., a change-id from `evidence_rows` whose change-spec file is not on disk). Halt and re-prompt the engineer.
+- A high-confidence finding cannot honestly satisfy KF-02 (would require fabricating evidence rows or citations). Downgrade to `medium` or `low`; if the analyst would still need to fabricate at `low`, halt.
+
+Halting is not failure. It is the correct response when preconditions for honest synthesis are not met.
+
+## Output expectations
+
+A finding at terminal-write state has:
+
+- All universal frontmatter plus `pattern`, `confidence`, `detected-by`, `detected-at`, `evidence-row-count`, `evidence-rows`, `related-findings`, `promoted-to: null`, `dismissed-reason: null`, `superseded-by: null`, `schema-version: 1`.
+- Six required body sections per `template/templates/kernel-fit-finding.md`: Title, Pattern fired, Evidence (≥1 citation per row), Kernel surface implicated (single-sentence pointer), Proposed direction (one paragraph), Counter-explanations (exactly two non-empty bullets per KF-03), Confidence rationale (one paragraph), Triage Log (empty at terminal-write).
+- Passes KF-01 (`len(evidence-rows) == evidence-row-count >= 1`), KF-02 (`high` confidence well-justified), KF-03 (two counter-explanations or auto-downgrade), KF-04 (`promoted-to: null` at terminal-write — promotion is downstream), KF-05 (`dismissed-reason: null` — dismissal is downstream).
+- For a supersession write, the supersession edit on the prior finding (status flip + `superseded-by` set) lands in the same `Write` sequence as the new finding so the audit trail is atomic.
+
+## Anti-patterns
+
+- Never bundle multiple patterns into one finding. One pattern, one file.
+- Never write a finding without two counter-explanations. Auto-downgrade `confidence` instead.
+- Never inflate `confidence` to trigger the Slack notification. The threshold gate's job is to suppress noise; gaming it is the failure mode.
+- Never write outside `hstack/kernel-fit/findings/`. No ADRs, no change-specs, no kernel edits.
+- Never edit existing findings except for the supersession carve-out (status flip + `superseded-by` set in the same atomic write).
+- Never advocate a specific kernel change in `## Proposed direction` beyond a one-paragraph sketch. Over-specifying pre-empts the human-gated promotion.
+- Never cite an artifact that does not exist or invent a commit-sha / change-id. Halt instead.
+- Never load implementer transcripts or in-flight authoring scratchpads. If visible, halt.
+- Never run in the same Claude Code session as an implementer. Honor system in v1; CI-verified in v2.
+- Never claim the analyst's output is measured truth. Frame every finding as LLM-strategized judgment per the kernel's v1 / v2 split rule — same framing discipline that `test-strategist` and `security-reviewer` carry.
+
+## Confirmation discipline
+
+The kernel-fit-analyst is structurally similar to `adversarial-reviewer`: it surfaces candidates for the human to confirm-or-rule-out, not findings for the human to merely accept. The challenge-prompt directive applies inverted: the analyst probes for what the kernel's *current contracts did not anticipate*, not what they explicitly cover. Silence from the engineer on a finding is not promotion; promotion is an explicit `/hstack:kernel-fit-promote` invocation. Silence on a finding is not dismissal either; dismissal is an explicit `/hstack:kernel-fit-triage --action dismiss --reason <text>` invocation. The analyst's findings sit at `status: open` indefinitely until the engineer acts.
+
+The counter-explanation discipline is the analyst's primary internal check: every finding must defend itself against two honest reasons not to warrant a kernel change. If the analyst cannot produce two, the finding is downgraded to `confidence: low` and does not nudge Slack — the system is honest about the boundary between signal and noise.
+
+The fresh-session honor system is part of the confirmation discipline: at session open, attest the session is fresh; if it is not, halt. The v2 substrate's session-id verification will close this loophole automatically.

package/template/.claude/agents/spec-author.md

@@ -77,7 +77,12 @@ For change-spec / module-spec / ADR / tech-debt, fill the YAML frontmatter and p
 - Use challenge prompts for sections where omission is the failure mode. Invariants on change-spec and module-spec require minimum three bullets, elicited via "Name three things that look like they could change but must not. If you can't name three, why is the change so narrow?"
 - For ADRs, walk Michael Nygard format strictly: Title, Status, Context, Decision, Consequences, Alternatives Considered. Use the challenge prompt on Consequences: "Name two consequences that look bad."
 - Reference, do not duplicate. When a change-spec needs to cite a persona, story, or ADR, write the id, not the prose.
-- Maintain reciprocity. When `tech-debt.origin` is a change-spec id, ensure that change-spec's `creates-tech-debt` array includes the new tech-debt id (TD-01). When writing `tech-debt.resolved-by`, ensure that change-spec's `resolves-tech-debt` array includes this tech-debt id (TD-04). Same for ADR `supersedes` / `superseded-by`. The reciprocal pair always lands in a single auto-commit; one-sided writes are not permitted.
+- Maintain reciprocity. When `tech-debt.origin` is a change-spec id, ensure that change-spec's `creates-tech-debt` array includes the new tech-debt id (TD-01). When writing `tech-debt.resolved-by`, ensure that change-spec's `resolves-tech-debt` array includes this tech-debt id (TD-04). Same for ADR `supersedes` / `superseded-by`. For `change-spec.enables` (Category B foundational-prerequisite linkage), when writing or editing the `enables` array, also write the reciprocal `enabled-by` entry on each downstream change-spec named in the array (SP-14). Forward references — `enables` entries pointing at a not-yet-scaffolded id — are permitted; `/hstack:change-new` reconciles the reciprocal `enabled-by` when the downstream is later scaffolded. The reciprocal pair always lands in a single auto-commit; one-sided writes are not permitted.
+- **The no-story interview branch.** When a change-spec's `user-stories` array would be empty, do not silently set `internal-tooling: true` (the old default). Ask the engineer: "This change has no linked user story. Which category applies?
+  - **(A) Internal tooling** — engineering-only code that never ships on a user path (scripts, dev dashboards, CI tooling). Sets `internal-tooling: true`.
+  - **(B) Foundational prerequisite** — production code that ships, but user value lives in a named downstream change-spec that consumes this one's output (schema before UI, plumbing before consumer). Sets `enables: [<downstream-id>, ...]` and writes the reciprocal `enabled-by` on each downstream spec.
+  - **(C) Neither** — there is actually a user story; let's draft it via `/hstack:story-draft`."
+  Categories A and B are mutually exclusive (SP-13). If the engineer is uncertain, walk the audit-query test: "After this ships, if someone asks 'what's the user value of this change?', is the honest answer (A) 'none, it's internal', (B) 'it teed up change-spec X', or (C) 'this user-facing thing'?"
 - **Mechanical operations are not your job.** Per the kernel's Mechanical operations section, status flips, reciprocal writes, Resolution Log appends, and `updated:` date bumps are performed by Skills directly in the main Claude Code session, not by this subagent. The four resolution Skills (`/hstack:tech-debt-resolve`, `/hstack:tech-debt-wontfix`, `/hstack:tech-debt-stale`, `/hstack:finalize`) own those writes themselves. If you are invoked for a mechanical operation, refuse and direct the engineer to run the appropriate Skill — the invocation is a workflow error, not a request to fulfil.
 - ADR ids are sequential. Read the highest existing `ADR-NNNN` and increment by one. No gaps, no reuse.
 - For module-spec, you may grep the In-Scope module's source to verify claims about exports, RPCs, and tables — but do not modify code.
@@ -96,7 +101,7 @@ Stop and ask the human when:
 
 A change-spec at terminal author-state (`status: ready-to-plan`) has:
 
-- All universal frontmatter (id, type, status, owner, created, updated, schema-version), all change-spec-specific fields (area, surfaces, user-stories, related-spec, in-scope, out-of-scope), and any conditional fields populated.
+- All universal frontmatter (id, type, status, owner, created, updated, schema-version), all change-spec-specific fields (area, surfaces, user-stories, related-spec, in-scope, out-of-scope, internal-tooling, enables, enabled-by), and any conditional fields populated. Exactly one of {`user-stories` non-empty, `internal-tooling: true`, `enables` non-empty} must hold (SP-09); `internal-tooling: true` and `enables` non-empty must not both hold (SP-13).
 - All ten sections from the schema, with Invariants holding three or more bullets and Open Questions either resolved or explicitly punted.
 - A passing validator run.
 

package/template/.claude/skills/hstack-adr-new/SKILL.md

@@ -44,6 +44,7 @@ Invoke when the engineer wants to capture a new architectural decision. Common t
 - `<slug>` (required, positional): kebab-case slug for the ADR. Examples: `pgvector-over-pinecone`, `trigger-dev-v4-only`, `per-tenant-encryption-keys`.
 - `--supersedes <ADR-NNNN>` (optional): id of the ADR being superseded. The Skill enforces reciprocity per AD-02.
 - `--from-research <session-id>` (optional): set when invoked via `hstack-research --promote`. The named research session is seeded into the Context section.
+- `--from-kernel-fit <finding-id>` (optional): set when invoked via `hstack-kernel-fit-promote`. The named kernel-fit finding's Evidence + Kernel surface + Proposed direction are seeded into the Context section, and the new ADR's `promoted-from-kernel-fit` frontmatter array is populated with the finding id (reciprocal with `kernel-fit-finding.promoted-to`; KF-04). The finding's Counter-explanations section is NOT seeded — the engineer's Decision must engage fresh with the kernel-change question.
 
 ## Preconditions
 
@@ -54,12 +55,13 @@ Before any work:
 - Verify the `<slug>` matches `^[a-z][a-z0-9-]*$` and is not already used in any existing ADR id.
 - When `--supersedes` is provided: verify the referenced ADR exists at `status: accepted`.
 - When `--from-research` is provided: verify the research session file exists at `hstack/research/sessions/<session-id>.md`.
+- When `--from-kernel-fit` is provided: verify the finding file exists at `hstack/kernel-fit/findings/<finding-id>*.md` and is at `status: open` or `acknowledged`.
 
 ## Orchestration steps
 
 1. **Compute the next id.** `ADR-NNNN-<slug>` where `NNNN` is the next sequential number, zero-padded to four digits.
 
-2. **Invoke `spec-author`.** Use the Task tool with `subagent_type: spec-author` and context = [kernel, `hstack/templates/adr.md`, glossary, tech-stack, the superseded ADR when `--supersedes`, the research session when `--from-research`]. The subagent walks the six Nygard sections.
+2. **Invoke `spec-author`.** Use the Task tool with `subagent_type: spec-author` and context = [kernel, `hstack/templates/adr.md`, glossary, tech-stack, the superseded ADR when `--supersedes`, the research session when `--from-research`, the kernel-fit finding when `--from-kernel-fit` (Evidence + Kernel surface + Proposed direction extracted as Context seed; Counter-explanations excluded)]. The subagent walks the six Nygard sections.
 
 3. **Interview discipline.** Per the `spec-author` contract:
    - Title — short noun phrase. One field, one confirmation.
@@ -71,6 +73,8 @@ Before any work:
 
 4. **Supersession reciprocity.** When `--supersedes` is set, `spec-author` writes `superseded-by: <new-adr-id>` on the prior ADR and `supersedes: <prior-adr-id>` on the new one. AD-02 enforces reciprocity.
 
+   **Kernel-fit reciprocity.** When `--from-kernel-fit` is set, `spec-author` writes `promoted-from-kernel-fit: [<finding-id>]` on the new ADR. The reciprocal write on the finding (`promoted-to: adr:<new-adr-id>` plus the status flip to `promoted`) is performed by `/hstack:kernel-fit-promote` after this Skill returns, in a separate commit (the recoverable two-commit carve-out documented in that Skill's Failure modes — analogous to the `/hstack:finalize` in-progress carve-out).
+
 5. **Validate.** Run `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` — AD-01 (sequential id), AD-02 (reciprocal supersession), AD-03 (fixed section structure), AD-04 (`superseded` requires `superseded-by`).
 
 6. **Status transition.** When every section is confirmed and the validator passes, `spec-author` advances `status` from `proposed` to `accepted`. The engineer can override to keep `proposed` if the decision is still under discussion.
@@ -100,6 +104,7 @@ Beyond the kernel's general stop conditions:
 - The `<slug>` collides with an existing ADR.
 - A `--supersedes` target does not exist at `status: accepted`.
 - A `--from-research` session does not exist on disk.
+- A `--from-kernel-fit` finding does not exist on disk or is at a status other than `open` / `acknowledged`.
 - The Consequences challenge prompt cannot produce two consequences that look bad; the engineer either thinks harder or accepts that this might not be ADR-worthy after all.
 
 ## Failure modes

package/template/.claude/skills/hstack-change-new/SKILL.md

@@ -60,15 +60,17 @@ Before any work:
 
 2. **Create the folder.** `mkdir -p hstack/specs/changes/<id>/` via Bash.
 
-3. **Seed `spec.md`.** Read `hstack/templates/change-spec.md`, instantiate the frontmatter with `id`, `type: change-spec`, `status: draft`, `owner` (from `git config user.name` or `hstack/config.yaml`'s default owner), `area: <area>`, `related-spec: <area>`, `created` and `updated` set to today, `schema-version: 1`. Leave `surfaces`, `user-stories`, `in-scope`, `out-of-scope`, `related-adrs`, `creates-tech-debt`, `parent-change`, `threat-model-delta`, `internal-tooling`, `trivial` as their template defaults (typically empty arrays or `null`). Leave every prose section empty, with the template's interview-prompt comments intact for `spec-author` to consume.
+3. **Seed `spec.md`.** Read `hstack/templates/change-spec.md`, instantiate the frontmatter with `id`, `type: change-spec`, `status: draft`, `owner` (from `git config user.name` or `hstack/config.yaml`'s default owner), `area: <area>`, `related-spec: <area>`, `created` and `updated` set to today, `schema-version: 1`. Leave `surfaces`, `user-stories`, `in-scope`, `out-of-scope`, `related-adrs`, `creates-tech-debt`, `parent-change`, `threat-model-delta`, `internal-tooling`, `enables`, `enabled-by`, `trivial` as their template defaults (typically empty arrays or `null`). Leave every prose section empty, with the template's interview-prompt comments intact for `spec-author` to consume.
 
-4. **Validate.** Run `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` against the seeded file. Validation at `status: draft` is permissive — empty arrays and empty prose are allowed at draft — but the universal floor (FM-01) must pass.
+4. **Forward-reference reconciliation for `enables` chains.** Grep every existing `hstack/specs/changes/*/spec.md` for the new `<id>` in `enables:` arrays. For each match: the matched (upstream) spec already declares this new (downstream) spec as a Category-B enabler. Per SP-14, write the reciprocal `enabled-by: [<upstream-id>, ...]` array on the newly-seeded spec in the same scaffold commit (this is the atomic-pair guarantee — both halves land together). When no match exists, leave `enabled-by: []`. Read-only on the upstream spec — its `enables` array was already written when the upstream was authored; no edit there. This is a mechanical operation per the kernel's Mechanical-operations section; no subagent is invoked. Surface the reconciliation to the engineer: "Detected upstream spec(s) declaring `enables: [<id>]` — populating `enabled-by` reciprocally."
 
-5. **Offer branch creation.** Run `git branch --show-current`. If the current branch is `main` (or the configured default), ask the engineer: "You're on `<current-branch>`. Convention is one branch per change-spec — create `change/<id>` from here and check out before the scaffold commits? [Y/n/type-different-name]". Default Yes. On confirmation, run `git checkout -b change/<id>` BEFORE step 6 so the scaffold commit lands on the correct branch from the start. If the engineer declines or names a different branch, honor the choice and continue on the chosen branch. If the current branch is anything other than the configured default (i.e., already on a feature branch), do nothing — the engineer has a deliberate branching strategy and the Skill respects it.
+5. **Validate.** Run `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` against the seeded file. Validation at `status: draft` is permissive — empty arrays and empty prose are allowed at draft — but the universal floor (FM-01) must pass.
 
-6. **Auto-commit.** Commit message: `chore(change-new): scaffold <id>`.
+6. **Offer branch creation.** Run `git branch --show-current`. If the current branch is `main` (or the configured default), ask the engineer: "You're on `<current-branch>`. Convention is one branch per change-spec — create `change/<id>` from here and check out before the scaffold commits? [Y/n/type-different-name]". Default Yes. On confirmation, run `git checkout -b change/<id>` BEFORE step 7 so the scaffold commit lands on the correct branch from the start. If the engineer declines or names a different branch, honor the choice and continue on the chosen branch. If the current branch is anything other than the configured default (i.e., already on a feature branch), do nothing — the engineer has a deliberate branching strategy and the Skill respects it.
 
-7. **Surface next steps.** Print a one-line instruction directing the engineer to invoke `spec-author` (or `hstack-story-draft` first if the change is user-facing and no story exists yet).
+7. **Auto-commit.** Commit message: `chore(change-new): scaffold <id>`.
+
+8. **Surface next steps.** Print a one-line instruction directing the engineer to invoke `spec-author` (or `hstack-story-draft` first if the change is user-facing and no story exists yet). If the change has Category-B `enabled-by` populated from step 4, also note the upstream linkage so the engineer is reminded which prerequisite this realizes.
 
 The Skill does not invoke any subagent. Scaffolding is mechanical and the engineer's subsequent moves vary by change.
 

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

@@ -66,7 +66,12 @@ No subagents are invoked. Every step is a direct file read or shell call.
 
 1. **Section 1 — Where you are.**
    - Read `hstack/config.yaml` for `init-status` and the active MCP set.
-   - Glob `hstack/specs/changes/*/spec.md`. For each, read frontmatter (`id`, `status`, `surfaces`, `owner`, `internal-tooling`, `trivial`, `parent-change`). Filter to non-terminal status (anything before `shipped`, `archived`).
+   - Glob `hstack/specs/changes/*/spec.md`. For each, read frontmatter (`id`, `status`, `surfaces`, `owner`, `internal-tooling`, `enables`, `enabled-by`, `trivial`, `parent-change`). Filter to non-terminal status (anything before `shipped`, `archived`).
+   - For each in-flight change, classify and surface the no-story carve-out when present:
+     - Category A (`internal-tooling: true`) → annotate "[Category A — internal tooling]".
+     - Category B (`enables` non-empty) → annotate "[Category B — enables → <comma-separated downstream ids>]". For each downstream id, also note its on-disk status (or "not yet scaffolded" — informational, not a blocker; reconciliation happens at downstream `/hstack:change-new` time).
+     - `enabled-by` non-empty → annotate "[Realizes ← <comma-separated upstream ids>]" so the reverse direction of the chain is visible.
+     - SP-13 violation (both `internal-tooling: true` AND `enables` non-empty) → flag explicitly as an error.
    - For each in-flight change, compute the **next blocking action**:
      - `status: draft` → "Author via `spec-author` directly (or run `/hstack:story-draft` first if user-facing)."
      - `status: ready-to-plan` and missing conditional artifacts → name them; suggest the appropriate Skill (`/hstack:test-plan` first if missing — it gates the planner, `/hstack:security-review`, `/hstack:data-review` if db, `/hstack:ui-brief` if ui, `/hstack:change-plan`).

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

@@ -47,7 +47,7 @@ tools:
 
 ## When to invoke
 
-Invoke once the change-spec is at `status: ready-for-implementation` (which means every upstream gate is terminal: test-plan at `passed` or `concerns-acknowledged`, plan at `ready`, security-review at `passed` or `concerns-acknowledged`, data-review at `passed` or `concerns-acknowledged` when applicable, ui-brief at `drafted` and figma-handoff at `ready` when applicable, user-stories non-empty unless internal-tooling). One invocation per phase. Re-invoke for each subsequent phase.
+Invoke once the change-spec is at `status: ready-for-implementation` (which means every upstream gate is terminal: test-plan at `passed` or `concerns-acknowledged`, plan at `ready`, security-review at `passed` or `concerns-acknowledged`, data-review at `passed` or `concerns-acknowledged` when applicable, ui-brief at `drafted` and figma-handoff at `ready` when applicable, user-stories non-empty UNLESS `internal-tooling: true` UNLESS `enables` non-empty). One invocation per phase. Re-invoke for each subsequent phase.
 
 ## Inputs
 
@@ -64,7 +64,7 @@ Before any work — the Skill re-checks every gate even when the change-spec car
 - Security-review at `status: passed` or `concerns-acknowledged`.
 - Data-review at `status: passed` or `concerns-acknowledged` when `surfaces` includes `db`.
 - ui-brief at `status: drafted` and figma-handoff at `status: ready` when `surfaces` includes `ui`.
-- User-stories non-empty unless `internal-tooling: true`.
+- User-stories non-empty UNLESS `internal-tooling: true` (Category A — engineering-only) UNLESS `enables` non-empty (Category B — foundational prerequisite; user value lives in the named downstream change-spec). SP-13: `internal-tooling: true` and `enables` non-empty are mutually exclusive; if both are set, halt with an SP-13 violation message and direct the engineer to `spec-author` to pick one.
 - The relevant module-spec at `status: current`.
 - **Branch state.** Run `git branch --show-current`. If the current branch is `main` (or the configured default) AND `change-spec.trivial` is not `true`, HARD HALT with: "Refusing to implement on `main` — change-spec `<id>` is not marked trivial. Check out `change/<id>` first, or run `/hstack:branch <id>` to create-and-switch." Trivial changes (`trivial: true`) may proceed on main per the kernel's trivial-changes carve-out. This check enforces the kernel's branch-hygiene contract at the last moment before code lands.
 

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

@@ -0,0 +1,164 @@
+---
+name: hstack-kernel-fit-promote
+description: |
+  Use this skill when the engineer has decided that an `acknowledged` (or `open`) kernel-fit finding warrants a kernel change captured as an ADR. The Skill seeds the finding's Evidence + Kernel surface + Proposed direction into an ADR Context section and routes through `/hstack:adr-new --from-kernel-fit <id> --slug <slug>`, where `spec-author` runs the normal Nygard interview — the human gate the kernel's "AI writes, humans confirm" contract requires at the kernel-modification layer. After the ADR lands, the Skill writes the reciprocal `promoted-to` back-reference on the finding and flips it to `status: promoted`. Two commits in v1 — the ADR commit (from `adr-new`) and the back-reference commit (from this Skill); see Failure modes for the recoverable-two-commit carve-out (analogous to the `/hstack:finalize` in-progress carve-out). Examples:
+
+  <example>
+  Context: The engineer reviewed KF-0001 (KF-P1, Category-A claim spans production paths), acknowledged it via triage last week, and now wants to land an ADR tightening the SP-13 guidance.
+  user: "/hstack:kernel-fit-promote KF-0001 --slug sp-13-prose-guidance-tightening"
+  assistant: "I'll read KF-0001, verify status (open or acknowledged), construct the ADR Context seed from Evidence + Kernel surface + Proposed direction, and invoke `/hstack:adr-new --from-kernel-fit KF-0001 --slug sp-13-prose-guidance-tightening`. spec-author runs the Nygard interview — Title, Status, Context (seeded), Decision, Consequences (with the challenge prompt), Alternatives Considered. After the ADR lands at terminal status, I'll write `promoted-to: adr:ADR-NNNN-...` on KF-0001, flip status to `promoted`, append a Triage Log entry, and commit. The ADR commit and the back-reference commit are separate — see Failure modes for the recoverable carve-out."
+  <commentary>
+  The promote Skill is the only path that elevates a kernel-fit finding to an ADR. The kernel's "AI writes, humans confirm" contract is preserved because `/hstack:adr-new`'s spec-author interview is the human gate; the engineer reviews and confirms every Nygard section before the ADR lands. The promote Skill itself performs no field-level interview — it is a mechanical wrapper plus a reciprocal back-reference write per ADR-0001.
+  </commentary>
+  </example>
+
+  <example>
+  Context: The engineer wants to route a finding to tech-debt instead of an ADR — the kernel surface is not yet ready for revision but the team wants to track the gap.
+  user: "/hstack:kernel-fit-promote KF-0004 --target tech-debt --slug halt-enum-missing-figma-mcp-case"
+  assistant: "I'll route through `/hstack:tech-debt-new --from-kernel-fit KF-0004 --slug halt-enum-missing-figma-mcp-case`. spec-author runs the six-section TD interview (Title, Why we took the shortcut, What it costs us, Fix sketch, Pre-conditions, Acceptance). After the TD lands, I'll write `promoted-to: tech-debt:TD-NNNN-...` on KF-0004 and flip status to `promoted`."
+  <commentary>
+  The `--target tech-debt` flag is the secondary promotion path — useful when the engineer recognizes the kernel-fit gap but does not yet have a defensible Decision section for an ADR. Tech-debt captures "we know about this; here's what fixing it would look like; here's what's blocking us from fixing it now." Same reciprocal write contract as the ADR path.
+  </commentary>
+  </example>
+
+  <example>
+  Context: A scan-Skill run between `/hstack:kernel-fit-promote` invocations has superseded the finding the engineer is now trying to promote.
+  user: "/hstack:kernel-fit-promote KF-0001 --slug internal-tooling-split"
+  assistant: "I'll halt — KF-0001 is at `status: superseded` (`superseded-by: KF-0007`). Promote KF-0007 instead; its body restates the same pattern with newer evidence. The promote Skill never promotes a superseded finding because the audit trail would route the ADR back to a stale body."
+  <commentary>
+  Promote refuses on terminal-from-promote statuses (`promoted`, `dismissed`, `superseded`, `archived`). The Skill is conservative — re-running on a superseded finding would write the back-reference on the wrong artifact and the audit trail would skew. The engineer's recovery is to promote the superseding finding.
+  </commentary>
+  </example>
+
+tools:
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Bash
+  - Task
+  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — validates the finding back-reference and the new ADR/TD frontmatter (KF-04 reciprocity, AD-01..AD-04 for ADR, TD-01..TD-04 for tech-debt)}}"
+---
+
+## Purpose
+
+`hstack-kernel-fit-promote` elevates a kernel-fit finding to a durable kernel-change artifact (ADR by default; tech-debt as a secondary path). It is the only Skill that flips a kernel-fit finding to `status: promoted`. The Skill is a mechanical wrapper per ADR-0001: it constructs the seed material from the finding's body and invokes the appropriate authoring Skill, then performs the reciprocal back-reference write directly. No subagent is invoked by this Skill itself — the authoring Skill it routes to (`/hstack:adr-new` or `/hstack:tech-debt-new`) invokes `spec-author` for the open-ended sections.
+
+The contract the user explicitly required at design time: **no agent creates an ADR without a human gate.** Here the human gate is `spec-author`'s Nygard interview, which the engineer walks every section of before the ADR's `status: accepted` write lands. The promote Skill never auto-creates an ADR — it routes; the engineer confirms.
+
+## When to invoke
+
+Invoke when:
+
+- A kernel-fit finding at `status: open` or `acknowledged` warrants a kernel change and the engineer is ready to author the ADR (or capture the tech-debt). The team has discussed the finding; the proposed direction is approximately right; the engineer is ready to commit time to the interview.
+- The finding's Counter-explanations have been considered and the team has decided they do not weaken the finding enough to dismiss.
+
+Do NOT invoke when:
+
+- The finding is at `confidence: low`. Low-confidence findings should be either dismissed (with substantive rationale) or left at `open` until the next scan accumulates evidence enough to upgrade them. Promoting `low` skips the implicit signal the analyst encoded.
+- The finding has just been written and not yet triaged. Take 24–48 hours to think; the kernel is a high-stakes artifact and the cost of a bad ADR cascades.
+- A scan run has just superseded the finding (`status: superseded`). Promote the superseding finding instead.
+
+## Inputs
+
+- `<finding-id>` (required, positional): the finding id, e.g. `KF-0001-category-a-claim-spans-production` or the short form `KF-0001`.
+- `--slug <text>` (required): kebab-case slug for the destination artifact. Passed through to the authoring Skill (`/hstack:adr-new --slug <text>` or `/hstack:tech-debt-new --slug <text>`).
+- `--target <adr | tech-debt>` (optional, default `adr`): destination artifact type. ADR is the primary path; tech-debt is the secondary path for findings that name a gap but do not yet have a defensible Decision section.
+
+## Preconditions
+
+- `hstack/kernel-fit/findings/<finding-id>*.md` exists. If missing, halt.
+- The finding is at `status: open` or `status: acknowledged`. If at any other status (`dismissed`, `promoted`, `superseded`, `archived`), halt with the current status named.
+- `--slug` is non-empty and matches `^[a-z][a-z0-9-]*$`.
+- `--target` is in the controlled enum (`adr` or `tech-debt`).
+- The downstream Skill (`hstack-adr-new` or `hstack-tech-debt-new`) is reachable from the consuming repo's `.claude/skills/`. (Auto-wired via the symlink delta on `npx hstack update`; this check is a defense against drift.)
+
+## Orchestration steps
+
+1. **Resolve and read the finding.** Glob `hstack/kernel-fit/findings/<finding-id>*.md`; on zero or multiple matches, halt. Parse frontmatter; verify status precondition. Print the finding body in full — the engineer reviews before committing the time to the interview.
+
+2. **Construct the seed material.** Extract three sections from the finding body verbatim:
+   - `## Evidence` (the bullet list with inline citations)
+   - `## Kernel surface implicated` (the single-sentence pointer)
+   - `## Proposed direction` (the one paragraph sketch)
+
+   Compose them into a "Seeded from kernel-fit finding <KF-id>" preface plus the three section bodies, verbatim. This preface becomes the Context seed for the downstream authoring Skill. The Counter-explanations section is NOT seeded — the engineer's Decision section must engage with the kernel-change question fresh, not pre-anchored by the analyst's challenge-prompt output.
+
+3. **Confirm before routing.** Print the proposed slug, the target (adr or tech-debt), and the seed preface. Ask "Route to /hstack:<target>-new with this seed? (Y/n)". Default Yes. On `n`, abort without writing.
+
+4. **Route to the authoring Skill.**
+
+   For `--target adr` (default):
+   - Invoke `/hstack:adr-new --from-kernel-fit <finding-id> --slug <slug>` via the Task tool or Skill orchestration mechanism. `spec-author` walks the six Nygard sections; the seeded Context is the engineer's starting material to review and revise.
+   - On the engineer's confirmation at `status: accepted`, `adr-new` writes the ADR file with `promoted-from-kernel-fit: [<finding-id>]` in its frontmatter and auto-commits with message `adr(ADR-NNNN-<slug>): accepted`.
+   - The ADR commit lands first. The back-reference commit lands second. See Failure modes for the recoverable carve-out.
+
+   For `--target tech-debt`:
+   - Invoke `/hstack:tech-debt-new --from-kernel-fit <finding-id> --slug <slug>`. `spec-author` walks the six TD sections; the seeded Context is split into Why we took the shortcut, What it costs us, and Fix sketch as appropriate.
+   - On terminal-state, `tech-debt-new` writes the TD file with `introduced-by: kernel-fit:<finding-id>` (the kernel-fit-origin variant of the TD `introduced-by` field; documented as a v1 carve-out — the existing field accepts a `kernel-fit:` prefix to disambiguate from change-spec origins) and auto-commits.
+
+5. **Capture the new artifact id.** Parse the downstream Skill's terminal commit message for `ADR-NNNN-<slug>` or `TD-NNNN-<slug>`. On parse failure (downstream Skill halted mid-interview), the promote Skill halts too — re-invocation will resume from the same step once the downstream Skill completes.
+
+6. **Write the reciprocal back-reference on the finding.** Per ADR-0001 (mechanical writes by the Skill orchestrator), the promote Skill performs the `Edit` itself:
+   - `promoted-to: adr:ADR-NNNN-<slug>` (or `tech-debt:TD-NNNN-<slug>`)
+   - `status: <prev> → promoted`
+   - `owner: <git-handle>` (if not already set by triage)
+   - `updated: <today>`
+   - Append to `## Triage Log`: `- \`status: <prev> → promoted\` on <today> by <owner>. Promoted to: <promoted-to>. Triggered by \`/hstack:kernel-fit-promote <id> --slug <slug>\`.`
+
+   Defensive Triage Log check: if `## Triage Log` is not present (legacy finding), append the section header first.
+
+7. **Print the proposed-diff preview** for the back-reference edit (per the kernel's mechanical-operations confirmation gate). Ask "Apply back-reference and flip status to promoted? (Y/n)". Default Yes.
+
+8. **Edit + validate + commit.** On `Y`:
+   - `Edit` the finding file.
+   - Run `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` against the finding. KF-04 (promoted requires `promoted-to` non-null AND referenced ADR/TD exists) must pass; the reciprocity check verifies the ADR's `promoted-from-kernel-fit` contains this finding's id.
+   - On validation pass: `git add` the finding file and commit with message `kernel-fit(<finding-id>): promoted to <promoted-to>`.
+   - On validation failure: halt; revert via `git checkout -- <finding-file>`. The ADR commit from step 4 has already landed and is correct — re-invoke promote (it is idempotent on the finding's promoted status, and the back-reference write will retry).
+
+9. **Confirm completion.** Print "Promote complete. Finding <finding-id> is now `promoted` with `promoted-to: <promoted-to>`. The kernel change lives in <promoted-to>; this finding is now read-only from kernel-fit's perspective (further edits would require a new finding via the next scan)."
+
+## Outputs
+
+- A new ADR at `hstack/adr/ADR-NNNN-<slug>.md` OR a new TD at `hstack/tech-debt/TD-NNNN-<slug>.md` (via the downstream authoring Skill).
+- An edit to `hstack/kernel-fit/findings/<finding-id>*.md` setting `promoted-to` and `status: promoted`, plus a Triage Log entry.
+- Two commits — one from the authoring Skill (ADR or TD), one from this Skill (finding back-reference).
+
+## Auto-commit triggers
+
+- Two commits per promote: the authoring Skill's own commit at the ADR or TD terminal state, and this Skill's own commit at the finding's `status: promoted` flip.
+
+## Idempotency contract
+
+- Re-running on a finding already at `status: promoted`: the Skill prints "already promoted to <promoted-to>" and exits no-op.
+- Re-running after step 4 succeeded but step 8 failed (the recoverable carve-out): the Skill detects the ADR or TD exists with the correct `promoted-from-kernel-fit` (or `introduced-by: kernel-fit:<id>`), skips re-invoking the authoring Skill, and goes straight to step 6 (back-reference write). Convergence in one re-invocation.
+- Re-running on a `dismissed` or `superseded` finding: halt with the status named. The engineer cannot promote a finding that has been ruled out or restated.
+
+## Stop conditions
+
+Beyond the kernel's general stop conditions:
+
+- The finding does not exist, or is at a terminal-from-promote status (`dismissed`, `promoted`, `superseded`, `archived`). Halt with the status named.
+- `--slug` is missing or malformed. Halt with the regex shown.
+- `--target` is not in the enum. Halt with usage.
+- The downstream authoring Skill halts mid-interview (`spec-author` could not produce two consequences for the ADR Consequences challenge, or the engineer aborted). Propagate the halt; re-invoke when ready.
+- The downstream artifact's commit cannot be parsed for its id at step 5 (e.g., the authoring Skill committed under a non-canonical message format). Halt with a diagnostic and let the engineer reconcile.
+- The validator fails at step 8 because the back-reference is inconsistent with the ADR's `promoted-from-kernel-fit` array. Halt and reconcile — most likely cause is the engineer aborted the authoring Skill before reciprocal write, leaving inconsistent on-disk state.
+
+## Failure modes
+
+- **Recoverable two-commit carve-out (analogous to `/hstack:finalize` in-progress carve-out).** The kernel's atomicity rule (CLAUDE.md `## Mechanical operations § Atomicity for reciprocal pairs`) requires both halves of a reciprocal write to land in the same commit. The finalize Skill carves out an exception for multi-TD resolutions where intermediate state is intentional and recoverable by re-running. Promote adopts the same shape: the ADR (or TD) commit and the finding back-reference commit are separate, and an interruption between them is recoverable by re-running this Skill. During the window between the two commits, on-disk state shows the ADR with `promoted-from-kernel-fit: [<id>]` and the finding still at `status: open` or `acknowledged` — this is intentional and re-runnable. The Forbidden-no-matter-what kernel bullet about reciprocal-pair atomicity applies to **standing** state (post-promote), not the transient window during a single promote invocation. v2 substrate could add `--defer-commit` to the authoring Skills so both writes land atomically; v1 accepts the two-commit pattern for honest implementation reality.
+- **Authoring Skill writes the wrong `promoted-from-kernel-fit` id.** Defense: this Skill's validation at step 8 cross-checks. If the ADR's array does not contain the finding id, the back-reference write is refused and the engineer reconciles by editing the ADR's frontmatter (this is itself a mechanical write per ADR-0001; manual `git commit --amend` is the recovery path, but the engineer should prefer re-running promote after correcting the ADR).
+- **Drive-by promote.** The Skill's preflight does not detect promote attempts on `low`-confidence findings — the engineer is trusted to make this judgment. If a pattern of `low`-confidence promotes emerges, that itself becomes a future kernel-fit detection pattern (KF-Pn: "engineers promote findings the analyst rated low").
+- **Engineer wants to promote two findings to one ADR.** Not supported in v1. Run promote twice with the same `--slug` — the second invocation will halt because the slug collides on `adr-new`'s precondition check. The engineer's recovery is to dismiss one of the findings with a rationale ("subsumed by KF-other-id promoting under slug X") and promote only the canonical one.
+
+## Anti-patterns
+
+- Never auto-promote without engineer invocation. The contract is non-negotiable per ADR-0004.
+- Never promote a finding at `low` confidence without a real reason. The analyst encoded a signal by setting confidence; ignoring it is a smell.
+- Never edit the finding's body (Evidence, Kernel surface, Proposed direction, Counter-explanations, Confidence rationale) during promote. Those are the analyst's domain and are immutable from this Skill's perspective. The Triage Log append and the four frontmatter changes (status, promoted-to, owner, updated) are the only writes permitted.
+- Never write the ADR or TD body. That is `spec-author`'s job, routed via the authoring Skill. Even pre-filling the Decision section based on the finding's Proposed direction is forbidden — the engineer's Decision must engage with the kernel-change question fresh.
+- Never promote a `superseded` finding. The audit trail would route the ADR to a stale body.
+- Never invoke `spec-author` directly from this Skill. Route through the appropriate authoring Skill (`hstack-adr-new` or `hstack-tech-debt-new`) so the existing challenge-prompts and validation rules apply.
+- Never bypass the validator at step 8. KF-04 reciprocity is the load-bearing check that makes the kernel-fit-to-ADR audit chain reconstructible.