hstack 0.16.0 → 0.17.0

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

@@ -1,142 +0,0 @@
----
-name: hstack-kernel-fit-scan
-description: Use to detect kernel-fit gaps — patterns in shipped practice suggesting the kernel itself needs revision — and synthesize one finding file per fired pattern. The first step of the kernel-fit loop; triage and promotion are separate Skills.
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "{{TODO-MCP: Slack — mcp__claude_ai_Slack__slack_send_message — required for kernel-fit notifications. Without it, findings still land on disk; the Skill logs to stderr and exits 0 (deliberate carve-out from the kernel's general MCP-unreachable stop condition — Slack is a side-channel pointer, not authoritative state).}}"
-  - "node hstack/scripts/validate-spec.mjs — validates kernel-fit-finding frontmatter and KF-01 through KF-05"
----
-
-## Purpose
-
-`hstack-kernel-fit-scan` is the entry point to the kernel-fit closed-loop system. The Skill orchestrates four steps: detection (Python script, pure read), synthesis (`kernel-fit-analyst` subagent, one file per fired pattern), notification (Slack, best-effort), and the atomic commit. Promotion to a kernel change is a separate, human-invoked Skill (`/hstack:kernel-fit-promote`).
-
-The Skill is the only path by which the `kernel-fit-analyst` subagent runs. The kernel's "AI writes, humans confirm" contract is preserved at the kernel-modification layer because the analyst writes findings only — never ADRs, never change-specs, never kernel edits.
-
-## When to invoke
-
-Common cadence:
-
-- Weekly for active engineering — catches kernel-vs-practice drift early.
-- After every ~5 shipped changes — surfaces patterns single-change inspection cannot.
-- After a kernel edit lands — confirm the edit moved the relevant pattern off the fired list (or did not introduce a new one).
-- Whenever a `kernel-fit-analyst` finding is restated or superseded by triage, to let the analyst write the supersession edit atomically.
-
-The Skill is opt-in. There is no cron, no automatic invocation, no event-driven trigger in v1.
-
-## Inputs
-
-- `--window <N>` (optional): limit detector history to the last N days. Default 30. `--window 0` means all-history.
-- `--no-slack` (optional): skip the Slack notification step even if MCP is wired. Useful for dry-runs or for replaying a scan when the engineer has already been notified manually.
-
-## Preconditions
-
-- `hstack/config.yaml` exists at `init-status: complete`. If init is incomplete, halt with `HSTACK-HALT: reason=missing-context`.
-- The wrapper script `hstack/scripts/telemetry/run_kernel_fit.py` exists. If missing, halt with `HSTACK-HALT: reason=missing-context` and the recommendation "re-vendor hstack or run `/hstack:configure`".
-- The repo contains at least 3 shipped change-specs (count by `status: shipped` across `hstack/specs/changes/*/spec.md`). Below this threshold, the corpus is too small for cross-correlation; the Skill halts with a one-line note: "kernel-fit scan needs ≥3 shipped changes; corpus is too small to produce honest evidence."
-- Python 3.10+ is available on PATH (matches `hstack-telemetry`).
-- The git repository is intact (`.git/` present).
-
-## Orchestration steps
-
-1. **Verify preconditions.** Walk the checks above; halt with the named reason if any fail. Print "kernel-fit-scan: preconditions OK, N shipped changes in corpus, M-day window" to stderr.
-
-2. **Run detection.** Shell out: `python3 hstack/scripts/telemetry/run_kernel_fit.py --repo <repo-root> --window <N>`. Capture stdout as JSON; capture stderr as the diagnostic log. On non-zero exit, surface the traceback and halt with `HSTACK-HALT: reason=missing-context`.
-
-3. **Enumerate pending engineer flags.** Glob `hstack/kernel-fit/flags/pending/*.md`. Capture the list (may be empty). The analyst processes these per ADR-0005's Pending Flags Processing loop documented in `template/.claude/agents/kernel-fit-analyst.md`; this Skill is responsible for surfacing the list to the analyst and for the post-analyst pin-file moves at step 5.
-
-4. **Decide whether to invoke the subagent.** Parse the detector JSON. If every pattern has `fired: false` **and** no pending flags exist, exit clean: print "kernel-fit-scan: no patterns fired in window, no pending flags — kernel is consistent with shipped practice in current corpus" to stdout, write nothing, do not invoke the subagent, do not nudge Slack, do not commit. If patterns fired OR pending flags exist (or both), proceed to step 5.
-
-5. **Invoke `kernel-fit-analyst`.** Invoke via Task tool with `subagent_type: kernel-fit-analyst`. The prompt includes (a) the JSON evidence blob verbatim, (b) the list of pending flag paths from step 3 (or "no pending flags" when empty), (c) the canonical reminder of session-isolation (no implementer transcripts loaded), (d) the explicit instruction "one file per fired pattern; mandatory two-bullet counter-explanation; never write outside `hstack/kernel-fit/findings/`; process pending flags per the Pending Flags Processing section of the analyst prompt". The subagent's writes land in the working tree before the subagent returns. The analyst's response object reports the flag-processing counts (`processed`, `folded`, `emitted`, `not_actionable`, `transcript_truncated`).
-
-6. **Move processed pin files.** For each pin the analyst updated to `status: processed`, `git mv hstack/kernel-fit/flags/pending/<pin>.md hstack/kernel-fit/flags/processed/<pin>.md`. Create the `processed/` directory if missing. This move lands in the same commit as the finding writes at step 7 — the analyst's pin frontmatter updates (classification, classification-rationale, folded-into, emitted-as, status) plus the file move must be atomic from git's perspective. **Note**: pin files are gitignored per ADR-0005, so `git mv` operates only on the filesystem (git will not stage either side). The "atomicity" here is filesystem-only — the analyst's in-place frontmatter update and the directory move complete together before stdout reports flag-processing counts. If the gitignore is later relaxed (would require an ADR amendment), this step's `git mv` becomes a real staged operation.
-
-7. **Stage and commit findings.** Compute the set of newly-written or modified finding files (analyst may have superseded a prior finding atomically with a new one, or appended evidence rows to existing findings via fold). Print the proposed diff for engineer confirmation (per the kernel's "AI writes, humans confirm" mechanical-operations adaptation). On Y/n confirmation `Y` (default Yes), `git add` the finding files and commit with message `kernel-fit: <N> finding(s) detected` (or `kernel-fit: <N> finding(s) detected, <M> superseded` when supersession edits landed; or `kernel-fit: <N> finding(s) detected (<F> from flags), <M> superseded` when flag-emit landed). One commit per scan run, atomic across all new/edited findings. When patterns did not fire and only pending flags were processed, the commit message reads `kernel-fit: <F> flag(s) processed (<E> emit, <FF> fold, <NA> not-actionable, <TT> transcript-truncated)`.
-
-8. **Notification — Slack nudge (best-effort).** Compute the notification set:
-
-   ```
-   notify = [f for f in newly_written_findings
-            if f.confidence in ("high", "medium")
-            and not _open_finding_exists_for_pattern_in_window(f.pattern, days=14)]
-   ```
-
-   For each finding in `notify`, send a Slack message via `mcp__claude_ai_Slack__slack_send_message` with the canonical body:
-
-   ```
-   hstack kernel-fit: <N> new finding(s)
-
-   • KF-NNNN — <title>  [confidence: high|medium] [via: detector|flag]
-     Pattern: <KF-P1|KF-P2|KF-P3|KF-FLAG-NNNN>
-     Kernel surface: <one-line>
-     hstack/kernel-fit/findings/KF-NNNN-<slug>.md
-
-   Triage:   /hstack:kernel-fit-triage KF-NNNN --action acknowledge
-   Dismiss:  /hstack:kernel-fit-triage KF-NNNN --action dismiss --reason "..."
-   Promote:  /hstack:kernel-fit-promote KF-NNNN --slug <adr-slug>
-   ```
-
-   Bundle multiple findings into a single message when more than one fires in this scan — one scan, one message, never carried across runs. When flag-processing occurred, append the **flag tail summary** as the last line of the same Slack message:
-
-   ```
-   Flags processed: <P> total — <FF> folded, <E> emitted, <NA> not-actionable, <TT> transcript-truncated.
-   ```
-
-   The tail is included only when at least one pin was processed AND at least one of `folded` or `emitted` is non-zero, OR when `transcript_truncated > 0` (the transcript-truncated count is operationally interesting because it surfaces v1-heuristic edge cases the engineer should know about). When every processed pin was classified `not-actionable` the tail is suppressed — it would otherwise be pure noise. When the scan produces zero detector findings AND only `not-actionable` pin processing, the Slack message is suppressed entirely (no findings, no tail-worthy signal).
-
-9. **Graceful degradation when Slack is unreachable.** If the MCP call raises (tool not configured, network failure, channel-not-found, etc.), log to stderr: `kernel-fit: Slack MCP unreachable; <N> finding(s) written to disk without notification. <P> flag(s) processed; triage via /hstack:help to discover open findings.` Exit 0. The disk write from step 7 is the load-bearing action; Slack is a side-channel pointer. This is a deliberate carve-out from the kernel's general MCP-unreachable stop condition — Slack is not load-bearing for kernel-fit (the canonical state lives on disk and is reachable via `/hstack:help`). The carve-out is documented here and in the kernel's `## How hstack improves itself` section.
-
-10. **Report.** Print to stdout: the count of patterns fired, the count of new findings written, the count of supersessions, the count of flags processed broken down by classification (`folded`, `emitted`, `not-actionable`, `transcript-truncated`), and the count of Slack notifications fired (or "skipped — Slack unreachable" / "skipped — within dedup window for all findings" / "skipped — no signal worth surfacing"). Done.
-
-## Outputs
-
-- Zero or more files at `hstack/kernel-fit/findings/KF-NNNN-<slug>.md` at `status: open`.
-- Zero or more supersession edits (status flip + `superseded-by` set) on prior finding files.
-- Zero or more evidence-row appends to existing findings (from flag fold).
-- Zero or more pin transitions from `hstack/kernel-fit/flags/pending/` to `hstack/kernel-fit/flags/processed/` with `status: processed` and the analyst-owned classification fields populated. Pins are gitignored per ADR-0005, so the moves are filesystem-only — not staged in git.
-- Zero or one git commits (covering finding writes only; pin moves are not staged).
-- Zero or one Slack messages (bundled when multiple findings notify, with the flag tail summary appended when applicable).
-
-## Auto-commit triggers
-
-- One commit at the writing of finding files (per the kernel's auto-commit-at-status-transition rule applied at the artifact-creation moment). No commit when no patterns fire AND no flag-emit or flag-fold landed (i.e., only `not-actionable` / `transcript-truncated` flag processing occurred). Pin file moves are filesystem-only (pins are gitignored) and do not require a commit.
-
-## Idempotency contract
-
-- Re-running the Skill when no patterns fire AND no pending flags exist: zero new disk artifacts, no commit, no Slack message. Pure no-op.
-- Re-running when no patterns fire but pending flags exist: the analyst is invoked to process flags only. Outcomes depend on classification — fold/emit may produce finding writes and a commit; not-actionable/transcript-truncated produce only pin moves (no commit).
-- Re-running when patterns fire that already have open findings within the dedup window: the analyst is invoked, sees existing findings, and may skip-write or supersede; Slack notification is suppressed by the dedup gate.
-- Re-running when the same patterns fire with new evidence: the analyst may produce supersession edits; the dedup gate still suppresses Slack (already-notified within the window).
-- Re-running with `--no-slack`: identical to a run with Slack unreachable — findings land on disk, flags are processed normally, no Slack message.
-- Re-running after pending flags were processed in a prior scan: the prior pins are now in `processed/` and the analyst is forbidden from re-processing them (per the kernel-fit-analyst's discipline rules). Only newly-flagged pins (added to `pending/` since the last scan) are processed this run.
-
-## Stop conditions
-
-Beyond the kernel's general stop conditions:
-
-- Init is incomplete or `run_kernel_fit.py` is missing (`HSTACK-HALT: reason=missing-context`).
-- Corpus is below the 3-shipped-changes floor — halt with the one-line note above.
-- Detector script exits non-zero or produces malformed JSON — halt with the traceback and `HSTACK-HALT: reason=missing-context`.
-- The `kernel-fit-analyst` subagent halts mid-run — propagate the halt sentinel; do not commit partial output (the analyst's writes-so-far remain unstaged on disk; the engineer can either delete them or re-invoke the Skill which will see them on next run).
-- The proposed-diff confirmation at step 5 is declined — abort the commit; the analyst's writes-so-far remain in the working tree. Re-invoke to continue.
-
-Slack-MCP-unreachable is NOT a stop condition. See step 7.
-
-## Failure modes
-
-- **Detector raises on malformed frontmatter in a shipped change-spec.** The detector is read-only and tolerant of missing fields; the parser falls back to a degraded YAML reader. If a corrupted frontmatter file genuinely crashes the parser, the traceback names the offending file — fix it and re-run.
-- **Subagent produces a finding without two counter-explanations.** The analyst auto-downgrades `confidence: low` per KF-03; the finding still lands on disk but does not nudge Slack. No remediation needed — this is the designed behavior.
-- **Subagent writes a finding outside `hstack/kernel-fit/findings/`.** Scope-lock violation. The subagent's prompt forbids this at every Write call. If observed, surface as a kernel-fit-analyst contract violation and do not commit; report the offending path for diagnosis.
-- **Slack message rejected by the MCP server (rate limit, channel-not-found, auth error).** Same as MCP unreachable — log to stderr, exit 0, the engineer triages via `/hstack:help` on next session.
-
-## Configuring Slack notifications (consumer-side)
-
-One-time consumer setup, not scan-time reading. The full procedure — MCP wiring and the `chat:write` scope, the `kernel-fit` block in `hstack/config.yaml` (`slack-channel`, `slack-fallback`), and the `--no-slack` dry-run — lives in `references/slack-setup.md` alongside this file.
-
-Read that file only when the engineer is wiring Slack for the first time, or when a run reported a Slack auth / channel / destination problem. Do not read it on a normal scan: Slack is opt-in, the disk artifact is canonical, and an unwired or unreachable Slack is not a stop condition (step 7).

package/template/.claude/skills/hstack-kernel-fit-scan/references/slack-setup.md

@@ -1,42 +0,0 @@
-# Configuring Slack notifications for `/hstack:kernel-fit-scan` (consumer-side)
-
-Reference file for `hstack-kernel-fit-scan`. Read it **only** when the engineer is
-wiring Slack for the first time, or when a scan run reported a Slack auth /
-channel / destination problem. It is not needed on a normal scan: the disk
-artifact is canonical, and an unwired or unreachable Slack degrades gracefully
-(log to stderr, exit 0).
-
-Slack notifications are opt-in per consumer. Without wiring, the Skill still
-works — findings land on disk and the engineer discovers them via
-`/hstack:help`. To enable Slack nudges on `medium` / `high` confidence findings:
-
-1. **Wire the MCP server.** Add the Slack MCP to your Claude Code MCP
-   configuration so `mcp__claude_ai_Slack__slack_send_message` is callable from
-   the session that runs `/hstack:kernel-fit-scan`. Follow Anthropic's Slack MCP
-   install docs; the auth scope `chat:write` is required.
-
-2. **Configure the destination channel.** Add a `kernel-fit` block to
-   `hstack/config.yaml`:
-
-   ```yaml
-   kernel-fit:
-     slack-channel: "#hstack-kernel-fit"   # public channel id or name; the bot must be invited
-     slack-fallback: "dm"                  # "dm" | "off" — behavior when slack-channel is absent or unreachable
-   ```
-
-   `slack-channel` is optional. When absent and `slack-fallback: "dm"`, the Skill
-   sends to the invoking engineer's DM via the bot. When `slack-fallback: "off"`,
-   a missing channel behaves identically to an unreachable MCP (log to stderr,
-   exit 0).
-
-3. **Verify with a dry-run.** Run `/hstack:kernel-fit-scan --no-slack` first to
-   confirm the detection layer produces output on your corpus, then re-run
-   without the flag once Slack is wired. The first non-`--no-slack` run will
-   surface any auth or channel issues as the documented graceful-degradation log
-   line.
-
-What you do NOT need to do: no code to write, no hook to install. The Skill is
-prose-driven; the runtime LLM agent invokes the MCP when the tool is available in
-the session and the config names a destination. The `{{TODO-MCP}}` placeholder in
-the Skill's `tools` array is the framework convention naming the contract — the
-consumer's MCP wiring satisfies it.

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

@@ -1,121 +0,0 @@
----
-name: hstack-kernel-fit-triage
-description: Use to acknowledge or dismiss an open kernel-fit finding. The second step of the kernel-fit loop — it only flips status and records a rationale; elevating a finding to an ADR is `/hstack:kernel-fit-promote`.
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - "node hstack/scripts/validate-spec.mjs — validates the finding frontmatter flip and KF-05 (dismissed-reason non-null 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 (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. It has to say what about the finding is wrong or not worth acting on, specifically enough that a reader six months from now can tell whether the dismissal still holds. "Not relevant" gives them nothing to check; "the kernel gives a norm here, not a bound" gives them everything, in forty-one characters. Length is not the test and is not checked (ADR-0014).
-
-## 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 re-evaluable by a later reader per the Inputs section. When it is not — the reason restates the finding, or asserts a preference with no referent — say so and ask for the specific claim; do not write the dismissal.
-- 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. When the failure is the `--reason` (`dismiss`), quote the reason back and name what is missing from it — the claim it makes, or the referent it lacks — so the engineer knows what to write rather than how long to write.
-
-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.** These fields, and only these, are triage's to write — `pattern`, `evidence-rows`, `evidence-row-count` and `confidence` are the analyst's domain and are never edited here. 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 log-header check per the kernel: if `## Triage Log` is absent, append it before writing the entry.
-
-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: the engineer sees what will land before it lands. The validator run in step 7 is the mechanical half of the same check.
-
-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 `node hstack/scripts/validate-spec.mjs <path>` against the file. KF-01 through KF-05 must pass; specifically KF-05 (`dismissed-reason` non-null 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 a `--reason` that restates the finding instead of answering it. Halt, quote it back, and name what is missing.
-- `--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 re-evaluability judgment at step 2 is the v1 defense: the reason is read against the finding the Skill just resolved, and one that gives a later reader nothing to check is quoted back 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.

package/template/.claude/skills/hstack-module-spec/SKILL.md

@@ -1,78 +0,0 @@
----
-name: hstack-module-spec
-description: Use to reverse-engineer or refresh the baseline `hstack/specs/<module>/spec.md` for one module. Required before any change-spec whose `area` names that module can validate.
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "{{TODO-TOOL: RepoMix — packs the module slice (paths from hstack/config.yaml) into a single context bundle for spec-author}}"
-  - "node hstack/scripts/validate-spec.mjs — validates module-spec frontmatter and MS-01/MS-02/MS-03"
----
-
-## Purpose
-
-`hstack-module-spec` produces a baseline `hstack/specs/<module>/spec.md` for one named module by orchestrating the `spec-author` subagent against a packed module slice. It is the one Skill where `spec-author` is permitted to grep the code in service of authorship — reading it, never modifying it. The module-spec is the system's anchor between its `area` controlled enum and the actual codebase, and a module-spec disconnected from real paths is worthless.
-
-## When to invoke
-
-Invoke once per critical module after `hstack-init` completes, before any change-spec in that module's `area` can validate. Re-invoke when the 60-day `needs-refresh` cron flags the spec, when the module's shape materially changes (new owned table, new public surface, new dependency), or on demand when the engineer wants a refresh.
-
-## Inputs
-
-- `<module>` (required, positional): the module key as declared in `hstack/config.yaml`'s module-to-area mapping. Must match an existing entry.
-
-## Preconditions
-
-Before any work:
-
-- Verify `hstack/config.yaml` exists at `init-status: complete`. If not, halt and direct the engineer to `hstack-init`.
-- Verify the named module exists in the config's module-to-area mapping. If not, halt and ask the engineer to add it via `hstack-configure` first.
-- Read the module's declared `paths` globs from config and verify at least one path resolves to existing files. If none resolve, halt — the module-to-paths mapping is stale.
-- Check whether `hstack/specs/<module>/spec.md` already exists. If yes and at `status: current`, ask the engineer whether this is a refresh (proceed with the existing spec as the proposal layer) or a re-author (archive the existing spec first).
-- Read `hstack/context/glossary.md` and `hstack/context/tech-stack.md` (required by `spec-author`'s session-start protocol).
-
-## Orchestration steps
-
-1. **Pack the module slice.** Run `{{TODO-TOOL: RepoMix}}` over the module's `paths` globs and write the packed bundle to a temporary location. If RepoMix is unavailable, fall back to having `spec-author` grep the paths directly; flag the degraded read in the conversation.
-
-2. **Invoke `spec-author`.** Use the Task tool with `subagent_type: spec-author` and context = [kernel, `hstack/templates/module-spec.md`, glossary, tech-stack, packed module bundle, existing module-spec instance if refresh]. The subagent reads the bundle, walks the seven module-spec sections — Purpose, Public Surface, Data Owned, External Dependencies, Invariants, Known Tech-Debt and ADRs, Refresh Policy — with confirmation gates per field.
-
-3. **Exercise the Invariants challenge prompt.** Per the `spec-author` contract and MS-03, the Invariants section requires a minimum of three bullets, elicited via the challenge "What would a careless refactor in this module break that the tests would not catch?" The Skill does not bypass this even on refresh.
-
-4. **Validate.** After each confirmed field write, the subagent runs `node hstack/scripts/validate-spec.mjs <path>` against the in-progress file. The Skill verifies MS-01 (paths non-empty and resolve), MS-02 (no overlap with other module-specs' paths — important to surface mis-aligned module-to-paths mapping), MS-03 (Invariants ≥ 3 bullets).
-
-5. **Transition to `status: current`.** When every section is confirmed and the validator passes, `spec-author` advances status from `drafted` to `current` and updates `last-refreshed` to today. Auto-commit fires.
-
-## Outputs
-
-- `hstack/specs/<module>/spec.md` at `status: current`, with frontmatter including the module's `paths` array mirrored from `hstack/config.yaml`. The Skill mirrors those globs; it never edits, substitutes, or invents them — `paths` are config's to change.
-
-## Auto-commit triggers
-
-- Status moves from absent to `drafted` after the first section is confirmed (so partial work survives).
-- Status moves from `drafted` to `current` when the full spec lands. Commit message: `module-spec(<module>): draft baseline` or `module-spec(<module>): refresh` depending on prior state.
-
-## Idempotency contract
-
-- Re-running on a `current` module-spec without specifying refresh intent: the Skill detects the existing spec and asks the engineer whether to refresh.
-- Re-running mid-authoring after a halt: `spec-author` reads the partial file, identifies the first un-confirmed section, and resumes the interview there.
-- Re-running on a refresh where the engineer accepts every section unchanged: a no-op diff body with only the `updated` and `last-refreshed` timestamps changing.
-
-## Stop conditions
-
-Beyond the kernel's general stop conditions:
-
-- The module's `paths` globs resolve to zero existing files. Halt; the module-to-paths mapping in config is wrong.
-- MS-02 fails — the module's paths overlap with another module's paths. Halt and ask the engineer to reconcile the mapping via `hstack-configure`.
-- The Invariants challenge prompt cannot produce three bullets after honest interview. Halt; either the module is too small to merit its own spec (fold into a parent module via `hstack-configure`) or the engineer needs more time to think.
-- `spec-author` halts because a referenced glossary term cannot be reconciled. Halt and surface; the engineer either updates the glossary via `hstack-configure --interview glossary` or rephrases.
-
-## Failure modes
-
-- **RepoMix unavailable.** Degraded mode — flag in the conversation, fall back to direct grep, continue.
-- **Existing module-spec frontmatter does not match config's paths.** Halt; the engineer reconciles before the refresh can proceed.
-- **Validator failure on a partial write.** `spec-author` halts at the field; the Skill surfaces the validator's message and waits.

package/template/.claude/skills/hstack-product-discovery/SKILL.md

@@ -1,75 +0,0 @@
----
-name: hstack-product-discovery
-description: Use to produce or refresh `hstack/context/product/product-brief.md` through one of three discovery techniques. Greenfield Phase 1, optional brownfield enrichment when source docs are thin, or standalone retroactive authoring.
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "node hstack/scripts/validate-spec.mjs — frontmatter validator"
----
-
-## Purpose
-
-`hstack-product-discovery` is the atom that produces `hstack/context/product/product-brief.md` via the `product-discovery` subagent. It is the canonical authoring path for the brief; the brief never lands via a generic spec-author interview.
-
-## When to invoke
-
-- Phase 1 of `/hstack:greenfield-init` (elicit mode, no source).
-- Optional enrichment within `/hstack:brownfield-init` when existing product docs are thin and the engineer wants the deeper reframe-style brief.
-- Standalone via `/hstack:product-discovery [--mode extract|elicit] [--section <name>]` for retroactive brief authoring on any repo.
-
-## Inputs
-
-- `--mode extract | elicit` — defaults: `elicit` if no source docs are reachable; `extract` if a `product-brief.md` exists or the engineer points at source documents.
-- `--section <name>` — optional, fast-jumps to a specific section for refresh. Re-runs the end-of-atom check across all sections before commit.
-
-## Preconditions
-
-- `hstack/config.yaml` exists and `init-status` is at least `minimal-complete` — the atom does not run standalone until config exists.
-- `hstack/KERNEL.md` and `hstack/templates/product-brief.md` are present.
-- `hstack/templates/discovery/{brainstorm,forcing-questions,project-brief}.md` are present.
-- In extract mode, at least one source document must be reachable; otherwise halt and ask the engineer to either supply source pointers or fall back to elicit mode.
-
-## Orchestration steps
-
-1. **Detect mode.** Read disk state. If `hstack/context/product/product-brief.md` exists at `status: current` and no `--section` flag, this is a refresh confirmation — print summary and exit unless engineer opts into full re-interview.
-2. **Pick technique** (elicit mode only). Prompt the engineer to choose Brainstorm / Forcing-Questions / Project-Brief. Persist the choice as `technique-used` in the brief frontmatter.
-3. **Invoke `product-discovery` subagent.** Via the Task tool with `subagent_type: product-discovery`. Pass mode, technique, optional section, and the canonical session-start context (kernel, template, technique script, source docs in extract mode).
-4. **Walk sections.** The subagent runs the chosen technique's script and walks the brief sections with confirmation gates. Each confirmed section writes to disk and auto-commits.
-5. **Run forcing prompts.** The three required reframes (Who pays? What's the wedge? What would falsify this?) fire before terminal state regardless of technique.
-6. **Auto-route at terminal state.** When the brief reaches `status: current`, the Skill prints the auto-route message (with alternative-path commands) and hands off to `product-manager` via the Task tool with `subagent_type: product-manager` to refresh `vision.md`, `roadmap.md`, `personas/`, `glossary.md`. If the engineer types `skip-routing`, the Skill commits the brief and exits cleanly — downstream Skills will halt on missing context docs.
-
-## Outputs
-
-- `hstack/context/product/product-brief.md` at `status: current`.
-- `hstack/.session-state/<session-id>.yaml` (transient).
-- Via auto-route: `vision.md`, `roadmap.md`, `personas/*`, `glossary.md` refreshed (unless skip-routing).
-
-## Auto-commit triggers
-
-- Each confirmed section writes immediately and auto-commits.
-- Brief reaches `status: current` → final commit with the auto-route message in the body.
-- Downstream refreshes by `product-manager` each auto-commit per the product-manager subagent's contract.
-
-## Idempotency contract
-
-- Brief at `current` + no `--section` + no `--force`: print summary, exit no-op.
-- Brief at `draft` or partial: read disk + session-state, resume at next non-confirmed section.
-- Brief at `needs-refresh` (flipped by `/hstack:configure` because upstream changed): walk all sections in confirm-or-revise mode.
-
-## Stop conditions
-
-- A required source document in extract mode is unreachable.
-- Forcing-prompt answer is too vague after one re-ask. The subagent halts with `HSTACK-HALT: reason=ambiguous-spec` or `missing-context`.
-- Mid-technique switch requested.
-- Engineer signals end-of-session.
-- Downstream auto-route fails (e.g., `product-manager` cannot reach the configured personas store). The Skill surfaces the failure; the brief stays at `current`, downstream context docs stay at their prior status until the engineer resolves.
-
-## Failure modes
-
-- **Subagent unreachable.** Persist session state; retry later.
-- **Auto-route partial failure.** If `product-manager` succeeds on vision but fails on personas (e.g., Notion MCP unreachable), the partial state is on disk; re-running auto-route via `/hstack:configure personas --from-brief` recovers.

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

@@ -1,115 +0,0 @@
----
-name: hstack-research
-description: Use when a decision needs grounded external information — API behavior, competitive scans, canonical docs, security CVEs, AI-native patterns — written to a transient research session. `--promote` elevates a session to an ADR, tech-debt, or durable note.
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - WebSearch
-  - WebFetch
-  - "{{TODO-MCP: Notion MCP — optional; useful when research must include prior team decisions in Notion}}"
-  - "{{TODO-MCP: GitHub MCP — optional; useful for searching issues and PRs on third-party SDK repos}}"
-  - "node hstack/scripts/validate-spec.mjs — validates research session frontmatter"
-  - "{{TODO-SCRIPT: hstack/scripts/garbage-collect-research.sh — clears sessions past their garbage-collect-after date; promoted sessions exempt}}"
----
-
-## Purpose
-
-`hstack-research` produces grounded research outputs via the `researcher` subagent and routes explicit promotion to durable artifacts. The Skill has two modes:
-
-- **Default mode.** Invoke the researcher with a query; classify into one of five modes; write a transient session artifact under `hstack/research/sessions/` with sources, confidence markers, and proposed promotion targets.
-- **`--promote <session-id>` mode.** Elevate an existing session to a durable artifact: ADR (route through `hstack-adr-new`), tech-debt (route through `hstack-tech-debt-new`), or a durable note under `hstack/research/promoted/` (the researcher writes this directly).
-
-## When to invoke
-
-Invoke when the engineer wants to ground a decision or implementation choice in current external information rather than speculation. Common triggers: third-party API integration choices, competitive scans before an ADR, security-CVE checks against pinned dependencies, AI-native pattern lookups (prompt-caching, retrieval, orchestration).
-
-## Inputs
-
-Default mode:
-- `<query>` (required, positional): the research question, in natural language. The Skill does not require a pre-classified mode — the researcher classifies during the session.
-
-Promote mode:
-- `--promote <session-id>` (required): the session to elevate.
-- `--target adr | tech-debt | note` (optional): the promotion target. When omitted, the Skill asks the engineer based on the session's proposed promotion targets.
-
-## Preconditions
-
-Before any work:
-
-- Verify `hstack/config.yaml` exists at `init-status: complete`.
-- Default mode: verify `hstack/research/sessions/` exists; create if absent.
-- Promote mode: verify the named session exists at `hstack/research/sessions/<session-id>.md` and is at `status: current`. Verify the session is not already promoted.
-
-## Orchestration steps
-
-### Default mode
-
-1. **Invoke `researcher`.** Use the Task tool with `subagent_type: researcher` and context = [kernel, query, mode-relevant context docs per the researcher's contract — tech-stack for API/documentation modes, vision/roadmap for competitive/AI-native modes, threat-model/hardening-checklist for security-CVE mode]. The subagent classifies the query, applies the mode's source bias, and writes findings incrementally.
-
-2. **Source discipline.** Per the `researcher` contract:
-   - API-lookup: canonical vendor docs over tutorials; 12-month recency window.
-   - Competitive-scan: engineering-side sources over marketing pages; vendors named explicitly.
-   - Documentation: canonical sources only; contradictions surfaced rather than papered.
-   - Security-CVE: CVE databases and vendor advisories; recency window open; cross-checked against `tech-stack.md` pins.
-   - AI-native best practices: 6-month recency bias; engineering blogs and tooling repos over vendor marketing.
-   Every source is named with URL and access timestamp. Single-source claims marked explicitly.
-
-3. **Confidence markers.** Each finding lands with `high | medium | low` confidence per the researcher's contract.
-
-4. **Proposed promotion targets.** The session artifact closes with a Promotion Targets section: "Promote to ADR / tech-debt / research-note? Engineer decides." The Skill does not promote unilaterally.
-
-5. **Session artifact frontmatter.** Includes `garbage-collect-after: <today + 30 days>` per the architecture's retention rule. Promoted sessions are exempt; the `--promote` operation sets a flag that the garbage-collector honors.
-
-### Promote mode
-
-1. **Read the session.** Surface the proposed promotion targets to the engineer.
-
-2. **Route by `--target` value:**
-   - `--target adr`: invoke `hstack-adr-new` with `--from-research <session-id>` and a slug supplied by the engineer. The ADR's Context section is seeded from the session findings; `spec-author` walks the remaining Nygard sections via its conversational interview, exercising the Consequences challenge prompt.
-   - `--target tech-debt`: invoke `hstack-tech-debt-new` with the engineer-supplied slug and any `--origin <change-spec-id>` when applicable. `spec-author` walks the six tech-debt sections.
-   - `--target note`: the `researcher` writes a durable note at `hstack/research/promoted/<topic>.md` directly. Free-form structure; no template constraint. This is the only target where the researcher writes the promoted artifact directly — the kernel's promotion-routing rule explicitly permits this for free-form notes.
-
-3. **Mark the session as promoted.** Update the session's frontmatter with `promoted-to: adr:<ADR-NNNN>` (or `tech-debt:<TD-NNNN>` or `note:<path>`). Exempt from garbage collection.
-
-## Outputs
-
-Default mode:
-- `hstack/research/sessions/<YYYY-MM-DD>-<topic-slug>.md` at `status: current`, with query, classified mode(s), sources, findings, options, and proposed promotion targets.
-
-Promote mode (depending on `--target`):
-- A new ADR at `hstack/adr/ADR-NNNN-<slug>.md` (via `hstack-adr-new`).
-- A new tech-debt item at `hstack/tech-debt/TD-NNNN-<slug>.md` (via `hstack-tech-debt-new`).
-- A new durable note at `hstack/research/promoted/<topic>.md` (written by the researcher).
-- An edit to the source session marking it `promoted-to: ...`.
-
-## Auto-commit triggers
-
-- Default mode: one commit when the session artifact lands. Commit message: `research(<topic>): drafted`.
-- Promote mode: the destination Skill's auto-commit fires (ADR or tech-debt). For `--target note`, one commit when the note lands plus the session's `promoted-to` edit.
-
-## Idempotency contract
-
-- Default mode: re-running with an identical query produces a new session file with today's date in the filename — research is recency-sensitive and re-running is intentional. The engineer may delete the prior session manually, or let the garbage collector handle it after 30 days.
-- Promote mode: re-running on an already-promoted session is a no-op; the Skill detects the `promoted-to` field and exits.
-
-## Stop conditions
-
-Beyond the kernel's general stop conditions:
-
-- Query is too vague to classify into a mode. Ask for clarification.
-- A load-bearing context document is unreachable.
-- Sources are contradictory and the resolution requires a human call.
-- Promote mode: target is unspecified and the engineer has not chosen.
-- Promote mode: the named session does not exist or is already promoted.
-- Promote mode with `--target adr` or `--target tech-debt`: the routed Skill halts; surface the halt message.
-
-## Failure modes
-
-- **WebSearch / WebFetch rate-limited or unavailable.** Surface the limitation; the researcher proceeds with cached or partial results, naming confidence as `low` for affected findings.
-- **A vendor's docs have moved and the canonical URL no longer resolves.** Note the broken canonical source explicitly; do not silently switch to a tutorial.
-- **Promote-to-ADR or promote-to-tech-debt halts inside `spec-author`'s interview.** The session's `promoted-to` field is not written until the destination artifact is at terminal state. Resume by re-running the destination Skill directly.