hstack 0.7.0 → 0.16.0

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

@@ -1,31 +1,12 @@
 ---
 name: hstack-help
-description: |
-  Use this skill when the engineer (or a cofounder opening the repo cold) wants situation awareness — "where are we, what can I run, what's next." Read-only across every artifact; no subagents invoked, no disk writes, safe to run any time. Examples:
-
-  <example>
-  Context: The cofounder hasn't touched the repo in two weeks and wants to know what's in flight before starting work.
-  user: "/hstack:help"
-  assistant: "I'll read every change folder, the context layer, ADRs, tech-debt, research sessions, and the git state. You'll get a three-section report: where you are, health, commands you can run right now with READY / BLOCKED markers."
-  <commentary>
-  Default mode is the full status report. No arguments needed. Output is computed entirely from disk frontmatter — no subagent invocations, no MCP calls, fast even on a large repo.
-  </commentary>
-  </example>
-
-  <example>
-  Context: The engineer is mid-change and wants a focused view of one change-spec's phase progression.
-  user: "/hstack:help --change 2026-05-billing-overage-warning"
-  assistant: "I'll read every artifact for that change and render the phase DAG: spec → ui-brief / figma-handoff / data-review / security-review / plan → implement (N of M phases) → verify → adversarial-review → ship. Each phase shows status and the next action."
-  <commentary>
-  Detailed mode for one change. Useful when resuming work after an interruption — the DAG view shows exactly which phase is next and what artifact gates it.
-  </commentary>
-  </example>
+description: Use for situation awareness across every hstack artifact — where the work stands, what is healthy, which commands are runnable now, or the phase DAG for one change. Read-only; no subagents, no writes.
 tools:
   - Read
   - Grep
   - Glob
   - Bash
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — invoked in --validate sub-mode to surface any artifact drift}}"
+  - "node hstack/scripts/validate-spec.mjs — invoked in --validate sub-mode to surface any artifact drift"
 ---
 
 ## Purpose
@@ -47,8 +28,8 @@ Safe to run repeatedly. Output is computed from current disk state.
 - No flag (default): full three-section status report.
 - `--change <id>`: detailed view of one change-spec, including the phase DAG.
 - `--commands`: print only the Skills cheat sheet (no current-state computation).
-- `--explain <concept>`: look up a concept from the kernel, the template schemas, or the glossary. Examples: `--explain invariant`, `--explain tenant-isolation`, `--explain trivial-tag`.
-- `--validate`: run `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` against every artifact under `hstack/` and report violations.
+- `--explain <concept>`: look up a concept from the kernel, `hstack/templates/`, the validator registry, or the glossary. Examples: `--explain invariant`, `--explain tenant-isolation`, `--explain trivial-tag`.
+- `--validate`: run `node hstack/scripts/validate-spec.mjs` against every artifact under `hstack/` and report violations.
 
 ## Preconditions
 
@@ -84,11 +65,11 @@ No subagents are invoked. Every step is a direct file read or shell call.
    - Glob `hstack/adr/ADR-*.md`, count those at `status: proposed`. List ids.
    - Glob `hstack/tech-debt/TD-*.md`. For `status: open`: count and list the top 3 by severity, with the suggested command `/hstack:tech-debt-resolve <td-id>` for each. For `status: in-progress`: list each with its resolving change-spec id (from the Resolution Log) and the change-spec's current status — flag any inconsistency where the change-spec is `shipped` but the TD is still `in-progress` as "run /hstack:finalize <change-id> to complete resolution".
    - Glob `hstack/research/sessions/*.md`, count those within the 30-day retention window. List the most recent 3.
-   - **Context docs.** Walk the canonical list from the kernel's "Product context" section: `vision`, `glossary`, `mvp-scope`, `personas/`, `data-architecture`, `tech-stack`, `ci-cd`, `infrastructure`, `threat-model`, `hardening-checklist`, `incident-runbook`. For each, classify:
+   - **Context docs.** Walk the canonical list from the kernel's "Product context" section: `vision`, `glossary`, `roadmap`, `personas/`, `data-architecture`, `tech-stack`, `ci-cd`, `infrastructure`, `threat-model`, `hardening-checklist`, `incident-runbook`. For each, classify:
      - Missing entirely → "Run `/hstack:configure --interview <name>` (or `/hstack:init` if `init-status != complete`)."
      - Status not `current` (e.g., `drafted`, `needs-refresh`) → flag with the same routing.
      Author routing mirrors `/hstack:configure` §`--interview`:
-     - `vision`, `glossary`, `mvp-scope`, `personas`, `data-architecture`, `tech-stack`, `ci-cd` → `product-manager`.
+     - `vision`, `glossary`, `roadmap`, `personas`, `data-architecture`, `tech-stack`, `ci-cd` → `product-manager`.
      - `infrastructure`, `incident-runbook` → `spec-author`.
      - `threat-model`, `hardening-checklist` → `security-reviewer`.
    - Glob `hstack/specs/*/spec.md`, list any module-spec at `status: needs-refresh`.
@@ -114,7 +95,7 @@ No subagents are invoked. Every step is a direct file read or shell call.
 
 ### `--change <id>` mode
 
-Read every artifact in `hstack/specs/changes/<id>/`. Render the phase DAG as ASCII with status per node:
+Read the **frontmatter** of every artifact in `hstack/specs/changes/<id>/` — the DAG below is computed entirely from `status`, `steps-completed` and `blocked-on`, so no artifact body is read (kernel § Reading artifacts). Open a body only when the engineer asks a follow-up the frontmatter cannot answer. Render the phase DAG as ASCII with status per node:
 
 ```
 spec [ready-for-implementation]
@@ -138,15 +119,16 @@ Just the Skills cheat sheet. No state computation. Useful when typing in muscle
 
 ### `--explain <concept>` mode
 
-Grep `hstack/CLAUDE.md`, `hstack/context/glossary.md`, and (if available) the cached template schemas for the concept. Print the most relevant paragraph plus a pointer to the source file. If the concept is not found in any source, print: "Not in the kernel, glossary, or template schemas. Try the architecture doc at the URL in `hstack/README.md`, or ask in natural language and I'll pull from kernel context."
+Grep `hstack/KERNEL.md`, `hstack/context/glossary.md`, and `hstack/templates/*.md` for the concept, and run `node hstack/scripts/validate-spec.mjs --rules` when the concept looks like a rule id (`SP-*`, `TD-*`, `AR-*`, …). Print the most relevant paragraph plus a pointer to the source file. If the concept is not found in any source, print: "Not in the kernel, the glossary, the templates, or the validator registry. Ask in natural language and I'll pull from kernel context."
 
 ### `--validate` mode
 
-Run `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` against every artifact under `hstack/`. Group failures by validation-rule id (SP-*, PL-*, AR-*, etc.) and name the offending file. Read-only — does not auto-fix anything.
+Run `node hstack/scripts/validate-spec.mjs` against every artifact under `hstack/`. Group failures by validation-rule id (SP-*, PL-*, AR-*, etc.) and name the offending file. Read-only — does not auto-fix anything.
 
 ## Outputs
 
-- Console-rendered status report. No disk writes. No commits.
+- Console-rendered status report. No disk writes, no commits, and no network: the report is computed from local file reads and git alone, never from an MCP call.
+- Where an artifact's status is ambiguous, the report prints the ambiguity. It never invents a next action to fill the gap.
 - No mutation of any artifact frontmatter.
 
 ## Auto-commit triggers
@@ -169,11 +151,3 @@ Beyond the kernel's general stop conditions:
 - **Cofounder runs the Skill before vendoring is complete.** Print the install pointer; do not try to compute a status report.
 - **Many in-flight change-specs with conflicting next-action recommendations.** Just list them all; let the engineer prioritize.
 - **Git state cannot be read (not a git repo).** Skip the git-related health lines; surface a "git not initialized" note.
-
-## Anti-patterns
-
-- Never write to any artifact, never auto-commit. The Skill's value is that it's safe to run any time.
-- Never invoke a subagent. Status awareness does not require the conversational interview machinery.
-- Never invent a "next action" for an artifact whose status is ambiguous — print the ambiguity, not a guess.
-- Never run the validators with `--fix` or any write flag (when the validator gains those).
-- Never call MCPs or perform network requests for the status report. Local file reads only.

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

@@ -1,34 +1,6 @@
 ---
 name: hstack-implement
-description: |
-  Use this skill when a change-spec is at `ready-for-implementation` and the engineer wants to execute one task from the plan. This is the only Skill that causes code to be written, and it does so exclusively by invoking the `implementer` subagent against one `task-id` at a time, scope-locked to the change-spec's `in-scope` allowlist. Defense in depth: the Skill checks preconditions and forbidden surfaces before invoking the subagent, and the subagent re-checks at every Read / Edit / Write. Examples:
-
-  <example>
-  Context: A UI-only change-spec for the billing-overage banner is at ready-for-implementation; the plan has five phases and phase-3 is next.
-  user: "/hstack:implement 2026-05-billing-overage-warning phase-3-component"
-  assistant: "I'll verify upstream gates (security-review passed, ui-brief drafted, figma-handoff ready), then invoke implementer for phase-3. Files Touched is a strict subset of in-scope; the subagent refuses any path outside it."
-  <commentary>
-  The Skill enforces the scope-lock contract from the kernel — Reads as well as Writes are restricted to `in-scope` plus the canonical session-start context loads. Phase-3 is the only thing executed; the Skill does not anticipate phase-4.
-  </commentary>
-  </example>
-
-  <example>
-  Context: A multi-surface change touching ui, db, and api is at ready-for-implementation; phase-2 lands a migration and regenerates types.
-  user: "/hstack:implement 2026-06-knowledge-citations phase-2-migration"
-  assistant: "I'll invoke implementer for phase-2. The migration runs against local Supabase only; types regen via `supabase gen types typescript --local`; no `supabase db push` against any remote project."
-  <commentary>
-  The kernel's database workflow is enforced both at the Skill level (the Skill refuses to invoke if the engineer attempts a remote-environment migration) and at the subagent level. Defense in depth on the highest-risk surface.
-  </commentary>
-  </example>
-
-  <example>
-  Context: Mid-phase, the implementer halts because lib/billing/queries.ts is needed but is not in `in-scope`.
-  user: "/hstack:implement 2026-05-billing-overage-warning phase-4-wire"
-  assistant: "The implementer halted at the queries.ts edit — that file is out-of-scope. Don't proceed; emit the scope-amendment request to the conversation, halt, and wait for the engineer to update the change-spec via spec-author."
-  <commentary>
-  This is the precondition-failure / scope-amendment case. The Skill does not unilaterally extend in-scope. The engineer invokes spec-author to amend the change-spec, the Skill re-runs, the implementer re-loads and continues.
-  </commentary>
-  </example>
+description: Use when a change-spec is at `ready-for-implementation` and one named phase of the plan should be executed. The only Skill that causes code to be written, one task at a time, scope-locked to `in-scope`.
 tools:
   - Read
   - Write
@@ -37,13 +9,13 @@ tools:
   - Glob
   - Bash
   - Task
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — validates plan.steps-completed updates against PL-03/PL-04/PL-05}}"
+  - "node hstack/scripts/validate-spec.mjs — validates plan.steps-completed updates against PL-03/PL-04/PL-05"
   - "{{TODO-OTHER: in-scope-enforcement guard — runtime check at every Edit/Write that refuses paths outside change-spec.in-scope; v1 implemented inside the implementer subagent's prompt; v2 substrate moves to a subagent-runtime hook}}"
 ---
 
 ## Purpose
 
-`hstack-implement` is the only Skill that causes code to be written. It orchestrates the `implementer` subagent against one named task from the plan, scope-locked to the change-spec's `in-scope` allowlist. It is the workflow's last line of gating before code lands on disk: it re-checks every upstream gate, enumerates the kernel's forbidden tools, and refuses to invoke the implementer when preconditions are not met.
+`hstack-implement` is the only Skill that causes code to be written. It orchestrates the `implementer` subagent against one named task from the plan. It is the workflow's last line of gating before code lands on disk: it re-checks every upstream gate, enumerates the kernel's forbidden tools, and refuses to invoke the implementer when preconditions are not met.
 
 ## When to invoke
 
@@ -56,7 +28,7 @@ Invoke once the change-spec is at `status: ready-for-implementation` (which mean
 
 ## Preconditions
 
-Before any work — the Skill re-checks every gate even when the change-spec carries `status: ready-for-implementation`, because frontmatter can drift:
+Before any work — the Skill re-checks every gate even when the change-spec carries `status: ready-for-implementation`, because frontmatter can drift. Every check below reads **frontmatter only**, except the two that name a body section (the plan's phase ids and Files Touched); the Skill does not load artifact bodies, because the `implementer` subagent loads what it needs from its own session-start list (kernel § Reading artifacts):
 
 - Change-spec at `hstack/specs/changes/<change-id>/spec.md`. `status` must be `ready-for-implementation` or `in-progress`. `Invariants` ≥ 3 bullets, `in-scope` non-empty, every `in-scope` glob resolves.
 - Plan at `hstack/specs/changes/<change-id>/plan.md` at `status: ready` or `in-progress`. `<task-id>` must match a phase id in the plan body. `Files Touched` for the phase must be a strict subset of `in-scope`.
@@ -74,24 +46,25 @@ Enumerate the kernel's forbidden tool surfaces explicitly before invoking the su
 - Raw shell (`psql`, `bash`, `sh`) executed against production or remote Supabase. Local Supabase only.
 - `supabase db push` / `supabase db reset` against any remote project. Local stack only.
 - Pipedream Connect against live customer accounts without per-invocation explicit human approval.
-- Any tool that mutates state outside the `in-scope` list.
 - MCPs not in the consuming repo's configured allow set.
 - `--no-verify` or other hook-bypassing git flags.
 - `--update-snapshots`, `jest --updateSnapshot`, `vitest -u`, or any equivalent bulk snapshot-update flag.
 - Destructive git operations (`git push --force`, `git reset --hard`, `git checkout .`) without explicit per-invocation authorization.
-- Modifications to existing test files without per-test authorization via the test-immutability protocol (`Ok to change test <name>`, `Ok to delete test <name>`, `Ok to update snapshot <name>`, `Ok to refresh fixture <name>`).
+- Modifications to existing test files without per-test authorization via the test-immutability protocol (step 8).
 
 If the named phase appears to require any of the above, halt before invoking — surface the violation, ask the engineer to either reshape the phase or authorize per-invocation.
 
 ## Orchestration steps
 
+0. **Open the phase window (mechanical, no LLM turn, no commit).** The moment the preconditions above pass and *before* any subagent invocation, run `python3 hstack/scripts/telemetry/session_id.py` and keep its `session_id` and `now` values — they become `session_id` and `phase_opened_at` in the sidecar below (ADR-0009). On failure or a null session id, hold `null` for both and continue.
+
 1. **Re-verify gates.** Run the precondition checks above. Any failure halts the Skill with a precise message naming the failing artifact and field.
 
 2. **Invoke `implementer`.** Use the Task tool with `subagent_type: implementer` and context = [kernel, change-spec, plan, test-plan, security-review, data-review when present, ui-brief and figma-handoff when present, module-spec, tech-stack]. The subagent loads only the In-Scope file list for code reading; everything outside the canonical session-start context plus In-Scope is refused per the kernel.
 
-3. **Phase execution.** The subagent executes one phase per invocation. It writes the code diff scoped to the phase's Files Touched, updates `plan.steps-completed` to include `<task-id>` when the phase completes, and writes the tests named in the test-plan sections the phase's Test Strategy references. Test names, file paths, and assertion shape come from the test-plan; the implementer does not rename or omit tests.
+3. **Phase execution.** The subagent executes one phase per invocation — the named task, then stop, never anticipating the next phase. It writes the code diff scoped to the phase's Files Touched, updates `plan.steps-completed` to include `<task-id>` when the phase completes, and writes the tests named in the test-plan sections the phase's Test Strategy references. Test names, file paths, and assertion shape come from the test-plan; the implementer does not rename or omit tests.
 
-4. **Database workflow enforcement.** For phases touching schema: the subagent creates migration files via `supabase migration new <descriptive_name>`; enables RLS in the same migration as a new table; regenerates types via `supabase gen types typescript --local > types/database.types.ts`. Never `supabase db push` / `supabase db reset` against a remote project.
+4. **Database workflow enforcement.** For phases touching schema: the subagent creates migration files via `supabase migration new <descriptive_name>` and never invents a filename; enables RLS in the same migration as a new table; regenerates types via `supabase gen types typescript --local > types/database.types.ts`. Never `supabase db push` / `supabase db reset` against a remote project.
 
 5. **Trigger.dev v4 only.** For phases touching trigger code, the subagent uses `@trigger.dev/sdk` task / schemaTask; never `client.defineJob` (v2 deprecated). `triggerAndWait` returns a `Result`; `result.ok` is checked before reading `result.output`.
 
@@ -99,13 +72,13 @@ If the named phase appears to require any of the above, halt before invoking —
 
 7. **Hook failures.** If a pre-commit hook fails on the auto-commit, the subagent investigates and fixes the underlying issue; does not bypass via `--no-verify`. If the fix would require out-of-scope edits, halt with a scope-amendment request.
 
-8. **Test-immutability protocol.** When the subagent determines an existing test file must be modified, deleted, or have a snapshot updated, it halts before touching the file and runs the kernel's authorization protocol: surface the test name, the reason, the proposed change, and the alternatives; wait for the canonical phrase verbatim (`Ok to change test <name>`, `Ok to delete test <name>`, `Ok to update snapshot <name>`, `Ok to refresh fixture <name>`); echo the phrase in the commit message body and add a footnote under the relevant phase in `plan.md`. The Skill enforces this defense-in-depth — if a subagent's diff shows a modified pre-existing test file without a matching authorization in the conversation, the Skill blocks the commit.
+8. **Test-immutability protocol.** When the subagent determines an existing test file must be modified, deleted, or have a snapshot updated, it halts before touching the file and runs the kernel's authorization protocol: surface the test name, the reason, the proposed change, and the alternatives; wait for the canonical phrase verbatim (`Ok to change test <name>`, `Ok to delete test <name>`, `Ok to update snapshot <name>`, `Ok to refresh fixture <name>`); echo the phrase in the commit message body and add a footnote under the relevant phase in `plan.md`. Authorization is per-test and per-conversation; a blanket "fix the tests" is refused, and bulk snapshot-update flags are forbidden regardless of scope. The Skill enforces this defense-in-depth — if a subagent's diff shows a modified pre-existing test file without a matching authorization in the conversation, the Skill blocks the commit.
 
-8. **Validate.** Run `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` against the plan — PL-03 (every `steps-completed` entry matches a plan phase id), PL-04 (every Files Touched path is a subset of `in-scope`), PL-05 (plan status gating).
+9. **Validate.** Run `node hstack/scripts/validate-spec.mjs <path>` against the plan — PL-03 (every `steps-completed` entry matches a plan phase id), PL-04 (every Files Touched path is a subset of `in-scope`), PL-05 (plan status gating).
 
 ## Outputs
 
-- Code diffs in the consuming repo, scoped to `change-spec.in-scope` and matching the phase's Files Touched.
+- Code diffs in the consuming repo, matching the phase's Files Touched.
 - Test files written or updated per the phase's Test Strategy.
 - `plan.md` updated with `<task-id>` appended to `steps-completed`; `blocked-on: null` (or set to a phase id when interactive blocker stops progress).
 - One git commit on the active working branch naming `<change-id>` and `<task-id>`.
@@ -123,9 +96,12 @@ At the phase-completion auto-commit above, write `hstack/specs/changes/<change-i
 
 ```json
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "skill": "hstack-implement",
   "change_id": "<change-id>",
+  "session_id": "<session id from step 0, or null>",
+  "phase_opened_at": "<ISO-8601 from step 0, or null>",
+  "phase_closed_at": "<ISO-8601, now — same write as this sidecar, or null>",
   "phase_id": "<task-id>",
   "started_at": "<ISO-8601, session start of this phase>",
   "completed_at": "<ISO-8601, now>",
@@ -139,6 +115,18 @@ At the phase-completion auto-commit above, write `hstack/specs/changes/<change-i
 
 `.telemetry/` is git-ignored in the consuming repo. The sidecar write must not introduce any new LLM turn or confirmation gate — it is a deterministic write bundled with the existing commit. If the sidecar write fails, log and continue; the canonical commit must still land.
 
+The three phase-window fields (`session_id`, `phase_opened_at`, `phase_closed_at`) come from step 0 and from this write. Their rules — best-effort, unmeasured rather than zero, never a halt — are stated once in `hstack/templates/telemetry-sidecar.md` § The phase window, which is the canonical schema and wins over any Skill.
+
+## Session boundary
+
+`implement` is a natural session cut: the auto-commit above left `plan.md` (`steps-completed`) and the committed code on disk, so the conversation holds nothing the next phase needs. The cut-notice format, the kickoff-prompt template and the context-block rules are in `KERNEL.md` § Session boundaries; this Skill's two variables are:
+
+```
+HSTACK-CUT: implement complete — cut recommended before the next phase, or verify once every phase is done.
+```
+
+and the next command, `/hstack:implement <next-phase-id> <change-id>`.
+
 ## Idempotency contract
 
 - Re-running with the same `<task-id>` after the phase already landed: the subagent reads `steps-completed`, recognizes the phase as done, and produces a no-op diff. Re-running on a partially applied phase: the subagent reads current file state and applies only the remaining diff.
@@ -165,21 +153,3 @@ Beyond the kernel's general stop conditions:
 - **Type regen fails after a migration.** The phase is incomplete; `steps-completed` is not advanced; halt and surface.
 - **Tests written but failing.** Halt at `steps-completed` not advanced; the engineer either re-invokes after fixing or amends the plan via the planner.
 - **Validator fails PL-04.** A Files Touched path crept outside `in-scope` — halt; this should have been caught upstream.
-
-## Anti-patterns
-
-- Never bypass scope-lock by one file, even one line. Halt and amend.
-- Never modify the change-spec. `steps-completed` lives on the plan.
-- Never weaken or remove an invariant.
-- Never use `service_role` Supabase keys in agent code paths.
-- Never use raw shell or `supabase db push` against production or any remote project.
-- Never use Pipedream Connect against live customer accounts without explicit per-invocation approval.
-- Never skip a hook with `--no-verify`. Fix the failing check.
-- Never execute destructive git operations without explicit authorization in the current conversation.
-- Never anticipate the next phase. Execute the named task and stop.
-- Never use `client.defineJob` (Trigger.dev v2 deprecated).
-- Never invent a migration filename. Use `supabase migration new <descriptive_name>`.
-- Never claim a phase complete when tests fail or types are stale.
-- Never edit, delete, or neutralize an existing test without per-test authorization. The kernel's test-immutability rule is non-negotiable; the default fix for a failing test is to fix the code under test.
-- Never run bulk snapshot-update flags. Each snapshot update needs its own authorization.
-- Never accept a blanket "fix the tests" authorization. Per-test scope is mandatory.

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

@@ -1,35 +1,6 @@
 ---
 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>
-
+description: Use to elevate an `open` or `acknowledged` kernel-fit finding into an ADR (or a tech-debt item) and write the reciprocal back-reference. The third step of the kernel-fit loop, after `/hstack:kernel-fit-scan` and `/hstack:kernel-fit-triage`.
 tools:
   - Read
   - Write
@@ -38,7 +9,7 @@ tools:
   - 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)}}"
+  - "node hstack/scripts/validate-spec.mjs — 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
@@ -87,7 +58,7 @@ Do NOT invoke when:
 
 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.**
+4. **Route to the authoring Skill.** Always through `/hstack:adr-new` or `/hstack:tech-debt-new`, never by invoking `spec-author` directly — routing is what keeps the authoring Skills' challenge prompts and validation rules in the path.
 
    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.
@@ -100,20 +71,20 @@ Do NOT invoke when:
 
 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:
+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. These four fields plus the Triage Log append are the only writes permitted here; the finding's body — Evidence, Kernel surface, Proposed direction, Counter-explanations, Confidence rationale — is the analyst's and is immutable from this Skill:
    - `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.
+   Defensive log-header check per the kernel: if `## Triage Log` is absent, append it before writing the entry.
 
 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.
+   - Run `node hstack/scripts/validate-spec.mjs <path>` 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).
 
@@ -148,17 +119,7 @@ Beyond the kernel's general stop conditions:
 
 ## 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.
+- **Recoverable two-commit carve-out (analogous to `/hstack:finalize` in-progress carve-out).** The kernel's atomicity rule (KERNEL.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.

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

@@ -1,35 +1,6 @@
 ---
 name: hstack-kernel-fit-scan
-description: |
-  Use this skill when the engineer wants to scan for kernel-fit gaps — patterns in shipped practice suggesting the kernel itself (CLAUDE.md, templates, validators, Skill flows) needs revision. The Skill runs the detection layer (`scripts/telemetry/run_kernel_fit.py`), invokes the `kernel-fit-analyst` subagent to synthesize one finding file per fired pattern, then nudges Slack on `high`/`medium` confidence findings with a 14-day dedup gate. Findings land at `hstack/kernel-fit/findings/KF-NNNN-<slug>.md`; the disk artifact is canonical, Slack is a side-channel pointer with graceful degradation when MCP is unwired. Promotion to a kernel change is human-gated via `/hstack:kernel-fit-promote`. See ADR-0004.
-
-  <example>
-  Context: The engineer wants a weekly kernel-fit scan after shipping several changes.
-  user: "/hstack:kernel-fit-scan"
-  assistant: "I'll run the detector against this repo's shipped changes / ADRs / tech-debt / commits / transcripts in the last 30 days. If any pattern fires, I'll invoke `kernel-fit-analyst` to synthesize findings (one file per pattern). Slack nudge on medium/high; dedup against open findings within 14 days. Disk-write is the load-bearing action — if Slack MCP is unreachable, the scan still completes and findings land on disk."
-  <commentary>
-  The Skill is opt-in by invocation. It is the only Skill that causes the `kernel-fit-analyst` subagent to run. Detection is post-hoc and derivative — no decision-time instrumentation; the no-parallel-tracker rule is preserved because the detector reads, never writes.
-  </commentary>
-  </example>
-
-  <example>
-  Context: The detector returns no fired patterns — the kernel is in good shape against the current corpus.
-  user: "/hstack:kernel-fit-scan"
-  assistant: "Detection ran; no patterns fired. No findings written, no Slack notification, no commit. The kernel-fit-analyst subagent was not invoked (no work to do). Exit clean."
-  <commentary>
-  No-fire is the most common output on a healthy repo, especially in the first 4–8 weeks of operation. The Skill must not invoke the subagent or write anything when no pattern fires — every Slack message has a cost in attention, and the dedup gate's purpose is undermined if scans run noise-free but the engineer still sees messages.
-  </commentary>
-  </example>
-
-  <example>
-  Context: KF-P1 fires but an open finding for the same pattern already exists from a scan 5 days ago.
-  user: "/hstack:kernel-fit-scan"
-  assistant: "KF-P1 fired with 3 evidence rows. An open finding (KF-0003) already exists for KF-P1 from 5 days ago — within the 14-day dedup window. I'll invoke the analyst; if the new evidence is materially equivalent the analyst will skip writing and surface the dedup; if it is materially stronger, the analyst writes a new KF-NNNN and supersedes KF-0003. Either way no Slack message fires today — the engineer was already notified within the window."
-  <commentary>
-  Dedup happens at two layers: (a) the analyst decides whether to write a new finding or skip (per its supersession carve-out); (b) the Skill decides whether to fire Slack. The 14-day window is the v1 default — tunable when calibration data exists.
-  </commentary>
-  </example>
-
+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
@@ -39,7 +10,7 @@ tools:
   - 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).}}"
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — validates kernel-fit-finding frontmatter and KF-01 through KF-05}}"
+  - "node hstack/scripts/validate-spec.mjs — validates kernel-fit-finding frontmatter and KF-01 through KF-05"
 ---
 
 ## Purpose
@@ -111,7 +82,7 @@ The Skill is opt-in. There is no cron, no automatic invocation, no event-driven
    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. When flag-processing occurred, append the **flag tail summary** as the last line of the same Slack message:
+   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.
@@ -166,32 +137,6 @@ Slack-MCP-unreachable is NOT a stop condition. See step 7.
 
 ## Configuring Slack notifications (consumer-side)
 
-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"`, missing channel behaves identically to 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 tools array is the framework convention naming the contract — the consumer's MCP wiring satisfies it.
-
-## Anti-patterns
+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.
 
-- Never invoke the `kernel-fit-analyst` subagent when no patterns fired. Empty invocations waste tokens and produce nothing.
-- Never auto-promote a finding to an ADR. Promotion is a separate, human-invoked Skill (`/hstack:kernel-fit-promote`). The contract is non-negotiable per ADR-0004.
-- Never silently retry Slack on transient failure. The disk artifact is canonical; the engineer's `/hstack:help` covers the missed-notification case.
-- Never write outside `hstack/kernel-fit/findings/` or modify any artifact not produced by the analyst this run. This Skill orchestrates; it does not author.
-- Never claim the analyst's output is measured truth. Frame every finding as LLM-strategized judgment per the kernel's v1 / v2 split rule.
-- Never bundle a Slack notification across scan runs. One scan, one message (or zero, when the dedup gate suppresses or Slack is unreachable).
-- Never re-process a pin already in `hstack/kernel-fit/flags/processed/`. The analyst's discipline rule (no re-processing) is mirrored here: the Skill globs only `pending/`, never `processed/`. If the engineer believes a processed pin was mis-classified, the path is to re-flag (creating a fresh pin), not to move the prior pin back.
-- Never include the flag tail summary in the Slack message when every pin was classified `not-actionable`. The tail's purpose is to surface actionable signal — the all-not-actionable case is pure noise and the suppression is deliberate.
-- Never commit a pin move. Pins are gitignored per ADR-0005; the `git mv` from `pending/` to `processed/` is filesystem-only and produces no staged change.
+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

@@ -0,0 +1,42 @@
+# 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.