hstack 0.16.0 → 0.17.0

package/template/.claude/skills/hstack-greenfield-init/SKILL.md

@@ -1,148 +0,0 @@
----
-name: hstack-greenfield-init
-description: Use to adopt hstack on an empty repository, eliciting the whole context layer across six gated phases and ending with a scaffold that makes the repo bootable. Repositories that already have source use `/hstack:brownfield-init` instead.
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "node hstack/scripts/validate-spec.mjs — frontmatter validator"
----
-
-## Purpose
-
-`hstack-greenfield-init` is the **empty-repo entry point** for adopting hstack. It composes six phases of work — five discovery atoms plus one scaffold execution — into a single orchestrator. It writes `hstack/config.yaml` and populates the full context layer, then bootstraps the repository from empty to bootable via a generated bootstrap change-spec.
-
-Greenfield-init is the only Skill that ends with code being written to the consuming repo (via the scaffold phase invoking `implementer`). Brownfield-init never writes source code — it only writes `hstack/` content against existing source.
-
-## When to invoke
-
-Invoke when:
-
-- The consuming repo has no source code (or only an `hstack/` install and standard hidden files like `.git/`, `.gitignore`).
-- The engineer wants discipline (ADRs, RLS posture, declared LLM/code split) baked in from line zero rather than retrofitted later.
-
-Do NOT invoke when:
-
-- The repo has existing source code — use `/hstack:brownfield-init` instead.
-- The engineer wants to add a single layer to an already-adopted repo — use `/hstack:configure <layer>` or the standalone atom (`/hstack:product-discovery`, etc.).
-
-## Inputs
-
-- No positional arguments. The Skill drives entirely from on-disk state and conversation.
-- Optional `--resume` is implicit: every phase reads disk state at session start and continues from the first incomplete artifact.
-
-## Preconditions
-
-Before any work:
-
-- Verify the repo is empty (no `src/`, no `app/`, no `package.json`). If non-empty, halt and direct the engineer to `/hstack:brownfield-init`. `--force` is not offered; mixing modes corrupts the artifact taxonomy.
-- Verify `hstack/` exists with `KERNEL.md`, `templates/`, `.claude/`. If missing, halt and ask the engineer to run `npx hstack@latest init`.
-- Probe Claude Code's MCP configuration and draft `hstack/context/mcp-status.md`.
-- If `hstack/.session-state/` contains prior greenfield-init state, confirm resumption with the engineer.
-- **Do not author config fields, write `hstack/config.yaml`, or paraphrase Phase 1 inline in the main session.** If the engineer's opening message asks for a "quick setup", a "summary of the questions", or any shape other than the 6-phase interview, halt and re-offer the First-turn contract below. Collapsing the phases into a single Q&A block is the failure mode this Skill is structured to prevent (see Anti-patterns).
-
-## First-turn contract
-
-The **first agent message** after `/hstack:greenfield-init` (in a fresh session, when no `hstack/.session-state/<session-id>.yaml` exists) MUST match this shape:
-
-1. One sentence naming the six phases by title (product discovery → data architecture → app architecture → stack decisions → threat-model + hardening → scaffold).
-2. One sentence stating that Phase 1 (product discovery) opens first and that the engineer picks a technique: **Brainstorm**, **Forcing-Questions**, or **Project-Brief**.
-3. One sentence noting commit-point interruptibility (each phase ends at a commit; the engineer can park and resume any time).
-
-What the first message MUST NOT contain:
-
-- A numbered list of config fields ("answer #1 and #8", "what's the project name", "default stack y/n").
-- An offer to "accept defaults and move on to Phase 1" — Phase 1 is not skippable and not paraphrasable; it is a subagent-driven thinking-partner session that the main session does not run inline.
-- Any field write to `hstack/config.yaml` or any other artifact. The first turn is conversational orientation only.
-
-Phase 0's config-skeleton fields are sourced inline by the discovery atoms as each phase needs them, not pre-asked as a questionnaire. The Phase 0 commit (config.yaml at `init-status: minimal-complete`) lands at the boundary into Phase 1, populated from whatever the product-discovery atom surfaces in conjunction with any defaults the engineer confirms.
-
-The second agent action (after the engineer picks a technique) MUST be a `Task` call launching the `product-discovery` subagent. The main session does not ask product-discovery questions itself.
-
-## Orchestration steps
-
-Six phases, hard-gated. The Skill does not advance past a phase until its artifact is at `status: current`, and `init-status` reaches `complete` only when every phase artifact is at `current` and the bootstrap change-spec is at `shipped`.
-
-The phase structure is doing two jobs at once — it is the resumability contract and the gate-discipline contract — so it is never collapsed into one long block. Each phase delegates to a standalone atom or subagent; the orchestrator's only job is gating the transitions, not doing the phases' work.
-
-### Phase 0 — Config skeleton (inline, deferred to Phase-1 boundary)
-
-Phase 0 is **not** a standalone upfront questionnaire. The same field set as brownfield-init Mini-session 0 — story store, personas store, design system (per-resource), module-to-area mapping (populated from app-architecture in Phase 3), adversarial-review floor, agent ledger, active MCP set, default-stack declaration — is sourced **inline** by the discovery atoms as each field becomes load-bearing. Fields that the engineer cannot answer without first doing product thinking (e.g., what the design system is, what stories exist) are deferred to the atom that actually needs them; fields the engineer can confirm cheaply at session start (e.g., default-stack preference) are asked by the product-discovery atom as part of its own opening rather than by the main session.
-
-At the boundary between Phase 1 and Phase 2, the Skill writes `hstack/config.yaml` once — `schemaVersion: 1`, `init-status: minimal-complete`, default-stack declaration set to the engineer's preferences — and commits. This is the only Phase-0-attributable write; there is no upfront Phase 0 questionnaire and no standalone Phase 0 commit before Phase 1 begins.
-
-### Phase 1 — Product discovery
-
-**The first non-trivial action of this Skill MUST be a `Task` call launching the `product-discovery` subagent in elicit mode.** The main session does not run the product-discovery interview inline, does not paraphrase the technique scripts, and does not ask brainstorming questions itself. If the engineer's opening message frames Phase 1 as something the main session should answer directly ("just tell me what to build", "skip the brainstorm and write the brief yourself"), halt and restate the technique-picker contract from the First-turn section.
-
-`/hstack:product-discovery` runs in elicit mode (no source documents). The atom:
-
-- Prompts the engineer to pick a technique (Brainstorm / Forcing-Questions / Project-Brief).
-- Runs the technique to completion, producing `hstack/context/product/product-brief.md` at `status: current`.
-- Auto-routes to `product-manager` to refresh `vision.md`, `roadmap.md`, `personas/`, `glossary.md` from the brief.
-
-Greenfield-init proceeds to Phase 2 only when the brief AND all four refreshed context docs are at `status: current`.
-
-### Phase 2 — Data architecture
-
-Invokes `/hstack:data-architecture` in elicit mode. The atom walks the five sections (Tenancy, Entities, RLS, RAG, Migrations). Produces `hstack/context/data-architecture.md` at `status: current`. The `assumes-database: postgres` frontmatter is set explicitly so Phase 4 can flag drift if the stack changes the DB choice.
-
-### Phase 3 — App architecture
-
-Invokes `/hstack:app-architecture` in elicit mode. The atom walks the five sections (Module Map, Agent Orchestration, Deterministic-vs-LLM Split, State-Ownership, Surface Boundaries). Produces `hstack/context/app-architecture.md` at `status: current` AND scaffolds `hstack/specs/<module>/spec.md` stubs at `status: draft` for each module from Section 1. Updates `hstack/config.yaml`'s `surfaces` enum to match Section 5.
-
-### Phase 4 — Stack decisions
-
-Invokes `/hstack:stack-decide`. The `stack-architect` reads `hstack/config.yaml`'s default-stack declaration (set in Phase 0) and fast-paths through layers the engineer accepted defaults for. Layers requiring explicit deep-dive get the constraint interview; each layer's choice routes through `spec-author` for ADR authoring. Produces one rollup ADR plus per-layer ADRs for deep-dived layers.
-
-### Phase 5 — Threat model + hardening
-
-Invokes `security-reviewer` in `--mode foundational` (scores against proposed posture, not diff). Walks `threat-model.md` and `hardening-checklist.md` using the now-current product-brief, data-architecture, app-architecture, and stack ADRs as anchors. Also produces `infrastructure.md` (via `spec-author`) and `incident-runbook.md` (via `spec-author`, `git-ignored: true`) per the brownfield-init pattern.
-
-### Phase 6 — Scaffold
-
-Invokes `/hstack:scaffold`. The scaffold Skill generates a bootstrap change-spec from `hstack/templates/bootstrap.md` with `area: bootstrap`, `surfaces: [infra]`, and `in-scope` enumerated from the app-architecture Module Map plus the data-architecture Migration Sketches. Runs `data-review` and `security-review` in `--mode foundational` against the proposed posture, then planner → implementer (phase-by-phase) → verifier. At terminal state the repo is bootable: the build command exits 0, the test command exits 0, the initial migrations have landed with RLS enforced from line zero.
-
-After Phase 6, `hstack/config.yaml`'s `init-status` advances to `complete` and the per-change workflow Skills become available.
-
-## Outputs
-
-- `hstack/config.yaml` at `init-status: complete`.
-- `hstack/context/product/product-brief.md` at `current` (Phase 1).
-- `hstack/context/vision.md`, `roadmap.md`, `personas/*`, `glossary.md` at `current` (Phase 1 auto-route).
-- `hstack/context/data-architecture.md` at `current` (Phase 2).
-- `hstack/context/app-architecture.md` at `current` plus module-spec stubs (Phase 3).
-- `hstack/adr/ADR-*` files — rollup + per-layer (Phase 4).
-- `hstack/context/threat-model.md`, `hardening-checklist.md`, `infrastructure.md`, `incident-runbook.md` (Phase 5).
-- The bootstrap change-spec at `shipped` plus the actual source files, migrations, CI config, and module shells in the consuming repo (Phase 6).
-
-## Auto-commit triggers
-
-- `hstack/config.yaml` reaches `init-status: minimal-complete` (end of Phase 0).
-- Each phase's terminal artifact reaches `status: current` (end of Phases 1–5).
-- Each phase of the bootstrap change-spec's plan completes (Phase 6 per-phase commits).
-- The bootstrap change-spec reaches `shipped` (end of Phase 6).
-- `hstack/config.yaml`'s `init-status` advances to `complete` (after Phase 6 ships).
-
-## Idempotency contract
-
-Re-running `hstack-greenfield-init` reads disk state, recognizes completed phases (artifacts at `current`), and resumes at the first incomplete phase. No re-interview of committed phases. If a downstream phase had triggered an upstream drift recovery, the upstream artifact will be at `needs-refresh` rather than `current`; the Skill resumes at the upstream's refresh interview.
-
-## Stop conditions
-
-Beyond the kernel's general stop conditions, this Skill halts when:
-
-- The repo is not empty at session start.
-- A phase's atom halts (e.g., `HSTACK-HALT: reason=upstream-drift`). The Skill surfaces the halt and offers the engineer the recovery paths the atom named.
-- A configured MCP that a downstream phase requires (Supabase MCP for Phase 2 extract-mode references, Notion MCP for persona storage) is unreachable and the phase is load-bearing on it.
-- The engineer signals end-of-session — persist state, exit cleanly.
-
-## Failure modes
-
-- **Phase 6 implementer halts.** Bootstrap is partially scaffolded; the change-spec is at `ready-for-implementation` with some phases of `plan.md` complete. Re-running greenfield-init resumes from the first incomplete plan phase via the standard `/hstack:implement` idempotency.
-- **Bidirectional drift recovery during Phases 2–4.** A downstream phase finds an upstream gap; the Skill routes the engineer through `/hstack:configure <upstream-atom>` and resumes after the upstream artifact returns to `current`. This path is never bypassed — the upstream MUST be refreshed before the downstream resumes, because a silent override produces contradictions between artifacts that nothing downstream will catch.
-- **Stack-architect contradicts data-architecture's Postgres assumption.** Phase 4 halts and surfaces; the engineer either revises data-architecture or revises the stack choice.

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

@@ -1,153 +0,0 @@
----
-name: hstack-help
-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
-  - "node hstack/scripts/validate-spec.mjs — invoked in --validate sub-mode to surface any artifact drift"
----
-
-## Purpose
-
-`hstack-help` is the read-only situation-awareness Skill. Its job is to answer three questions without writing anything: where is the team in their hstack-governed work, what is healthy / unhealthy, and what commands are available to run right now. It invokes no subagent. It writes no artifact. It is safe to run any time, by any team member, on any branch.
-
-## When to invoke
-
-Invoke when:
-- You open the repo after a break and need a refresher.
-- A cofounder or new contributor is orienting themselves.
-- Something feels off (a Skill halted, a status seems wrong) and you want a system-level view before debugging.
-- Mid-change, before invoking the next workflow Skill, when you want to confirm preconditions are met without trial-and-error halts.
-
-Safe to run repeatedly. Output is computed from current disk state.
-
-## Inputs
-
-- 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, `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
-
-Minimal. The Skill is best-effort and degrades gracefully:
-
-- Verify `hstack/` exists. If not, print "hstack is not installed in this repo. See `hstack/README.md` if vendoring, or run the vendoring procedure from the framework source."
-- Verify `hstack/config.yaml` exists. If not (init not started), print "hstack is installed but not initialized. Run `/hstack:init` to bootstrap. Other Skills will halt until init completes."
-- Beyond that, the Skill tolerates missing or partial artifacts — they show up in the report as "not present" or "draft", which is useful information, not an error.
-
-## Orchestration steps
-
-No subagents are invoked. Every step is a direct file read or shell call.
-
-### Default mode (no flag)
-
-1. **Section 1 — Where you are.**
-   - Read `hstack/config.yaml` for `init-status` and the active MCP set.
-   - Glob `hstack/specs/changes/*/spec.md`. For each, read frontmatter (`id`, `status`, `surfaces`, `owner`, `internal-tooling`, `enables`, `enabled-by`, `trivial`, `parent-change`). Filter to non-terminal status (anything before `shipped`, `archived`).
-   - For each in-flight change, classify and surface the no-story carve-out when present:
-     - Category A (`internal-tooling: true`) → annotate "[Category A — internal tooling]".
-     - Category B (`enables` non-empty) → annotate "[Category B — enables → <comma-separated downstream ids>]". For each downstream id, also note its on-disk status (or "not yet scaffolded" — informational, not a blocker; reconciliation happens at downstream `/hstack:change-new` time).
-     - `enabled-by` non-empty → annotate "[Realizes ← <comma-separated upstream ids>]" so the reverse direction of the chain is visible.
-     - SP-13 violation (both `internal-tooling: true` AND `enables` non-empty) → flag explicitly as an error.
-   - For each in-flight change, compute the **next blocking action**:
-     - `status: draft` → "Author via `spec-author` directly (or run `/hstack:story-draft` first if user-facing)."
-     - `status: ready-to-plan` and missing conditional artifacts → name them; suggest the appropriate Skill (`/hstack:test-plan` first if missing — it gates the planner, `/hstack:security-review`, `/hstack:data-review` if db, `/hstack:ui-brief` if ui, `/hstack:change-plan`).
-     - `status: ready-for-implementation` and plan has un-completed phases → "/hstack:implement <id> <next-task-id>" with the next phase id computed from `plan.steps-completed`.
-     - `status: in-progress` → continue implementing remaining phases; verify after.
-     - `status: ready-for-review` and no `verification.md` at passed → "/hstack:verify <id>".
-     - `status: ready-for-review` and no `adversarial-review.md` at `findings-resolved` → "/hstack:adversarial-review <id> (FRESH SESSION REQUIRED)".
-     - `status: ready-to-ship` → "/hstack:ship <id>" (if pr-body not yet produced) or "open/merge the PR, then run /hstack:finalize <id>" (if pr-body exists).
-     - `status: shipped` and `resolves-tech-debt` is non-empty but referenced TDs are still at `in-progress` → "/hstack:finalize <id>" (finalize is incomplete; this is an inconsistent state).
-   - 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`, `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`, `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`.
-
-2. **Section 2 — Health.**
-   - MCPs: read `hstack/context/mcp-status.md` for wired vs degraded.
-   - **Branch hygiene.** Run `git branch --show-current`. For each in-flight non-trivial change-spec, the expected branch is `change/<change-id>` per the kernel's branch-hygiene rule. Compare:
-     - Current branch is `main` AND ≥ 1 non-trivial in-flight change exists → flag explicitly: "On `main` with in-flight non-trivial change `<id>`; expected `change/<id>`. Run `/hstack:branch <id>` to switch."
-     - Current branch matches the expected `change/<id>` of one in-flight change → "Branch `change/<id>` matches in-flight change `<id>`."
-     - Current branch is `change/<other-id>` and `<other-id>` is no longer in-flight (shipped or archived) → "On `change/<other-id>` (shipped); ready to start something new."
-     - Trivial-only in-flight changes → no branch warning (trivial may commit on main).
-   - Git state: `git status --short` count. Flag uncommitted hstack-relevant files.
-   - Last hstack commit: `git log -1 --format='%h %s (%cr)' -- hstack/`. Shows when hstack-touching work last landed.
-   - Local-ahead-of-remote: `git rev-list --count @{u}..HEAD 2>/dev/null` (silently skip if no upstream).
-
-3. **Section 3 — Commands you can run right now.**
-   - List every Skill grouped by category (setup, workflow, cross-cutting).
-   - For each, compute a marker:
-     - `READY` — preconditions detectable as met.
-     - `BLOCKED: <reason>` — name the missing precondition.
-     - `N/A — context` — e.g., `/hstack:ui-brief` for a repo with no in-flight ui-surface change.
-   - For Skills that take arguments, show a parameterized example using the most likely current value (e.g., the active in-flight change-id).
-
-### `--change <id>` mode
-
-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]
-  ├── test-plan [passed] ✓
-  ├── ui-brief [drafted] ✓
-  ├── figma-handoff [ready] ✓
-  ├── data-review [passed] ✓
-  ├── security-review [concerns-acknowledged] ✓
-  └── plan [in-progress]
-        steps-completed: phase-1, phase-2, phase-3 of phase-1..phase-5
-        next phase: phase-4-wire (depends on phase-3 ✓)
-verification [not present]
-adversarial-review [not present]
-```
-
-Below the DAG, the explicit next-action recommendation.
-
-### `--commands` mode
-
-Just the Skills cheat sheet. No state computation. Useful when typing in muscle memory.
-
-### `--explain <concept>` mode
-
-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 `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, 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
-
-None. This Skill is strictly read-only.
-
-## Idempotency contract
-
-Trivially idempotent. Re-runs produce a fresh report from current disk state. No persisted state, no side effects.
-
-## Stop conditions
-
-Beyond the kernel's general stop conditions:
-
-- The `--explain <concept>` lookup finds no match in any canonical source. Print the "not found" message and exit cleanly — not a failure.
-- `--validate` mode requires the validator script. If absent, print a clear "validator not yet implemented" message (it's a known TODO) and skip the validation; the other modes still work.
-
-## Failure modes
-
-- **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.

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

@@ -1,155 +0,0 @@
----
-name: hstack-implement
-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
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "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. 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
-
-Invoke once the change-spec is at `status: ready-for-implementation` (which means every upstream gate is terminal: test-plan at `passed` or `concerns-acknowledged`, plan at `ready`, security-review at `passed` or `concerns-acknowledged`, data-review at `passed` or `concerns-acknowledged` when applicable, ui-brief at `drafted` and figma-handoff at `ready` when applicable, user-stories non-empty UNLESS `internal-tooling: true` UNLESS `enables` non-empty). One invocation per phase. Re-invoke for each subsequent phase.
-
-## Inputs
-
-- `<change-id>` (required, positional): the change-spec id.
-- `<task-id>` (required, positional): the phase id (e.g., `phase-3-component`). Must match an existing `step-id` in the plan body.
-
-## Preconditions
-
-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`.
-- **Test-plan at `hstack/specs/changes/<change-id>/test-plan.md` at `status: passed` or `concerns-acknowledged`.** The implementer reads it at session start and writes the tests it specifies; without a terminal test-plan, the implementer halts.
-- Security-review at `status: passed` or `concerns-acknowledged`.
-- Data-review at `status: passed` or `concerns-acknowledged` when `surfaces` includes `db`.
-- ui-brief at `status: drafted` and figma-handoff at `status: ready` when `surfaces` includes `ui`.
-- User-stories non-empty UNLESS `internal-tooling: true` (Category A — engineering-only) UNLESS `enables` non-empty (Category B — foundational prerequisite; user value lives in the named downstream change-spec). SP-13: `internal-tooling: true` and `enables` non-empty are mutually exclusive; if both are set, halt with an SP-13 violation message and direct the engineer to `spec-author` to pick one.
-- The relevant module-spec at `status: current`.
-- **Branch state.** Run `git branch --show-current`. If the current branch is `main` (or the configured default) AND `change-spec.trivial` is not `true`, HARD HALT with: "Refusing to implement on `main` — change-spec `<id>` is not marked trivial. Check out `change/<id>` first, or run `/hstack:branch <id>` to create-and-switch." Trivial changes (`trivial: true`) may proceed on main per the kernel's trivial-changes carve-out. This check enforces the kernel's branch-hygiene contract at the last moment before code lands.
-
-Enumerate the kernel's forbidden tool surfaces explicitly before invoking the subagent — defense in depth with the implementer's own check:
-
-- `service_role` Supabase keys in agent-touching code paths.
-- 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.
-- 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 (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 — 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>` 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`.
-
-6. **Scope-amendment halt.** If the subagent would touch a file outside `in-scope`, it halts and emits a scope-amendment request to the conversation. The Skill does not extend `in-scope` unilaterally. The engineer invokes `spec-author` (typically via direct request, not a Skill) to amend the change-spec, the Skill re-runs, the subagent re-loads.
-
-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`. 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.
-
-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, 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>`.
-
-The change-spec is never written by the implementer or by this Skill (architecture amendment A3).
-
-## Auto-commit triggers
-
-- One commit when the phase completes and `steps-completed` advances. Commit message: `implement(<change-id>) <task-id>`.
-- An additional commit when `plan.status` advances to `completed` after the final phase.
-
-## Telemetry sidecar
-
-At the phase-completion auto-commit above, write `hstack/specs/changes/<change-id>/.telemetry/implement-<task-id>.json` in the same `git add && git commit` as the canonical phase commit. The sidecar is derivative of git + frontmatter (see `hstack/templates/telemetry-sidecar.md`). Schema:
-
-```json
-{
-  "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>",
-  "files_touched_count": <int>,
-  "tests_written_count": <int, new test files only>,
-  "scope_amendment_emitted": <bool>,
-  "halt_reasons": [<kernel halt-sentinel enum values, if any>],
-  "test_immutability_authorizations": [<canonical phrase strings, if any>]
-}
-```
-
-`.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.
-- Re-running on a phase whose dependencies are not yet complete (`depends-on` references a phase not in `steps-completed`): the subagent halts and surfaces the missing dependency.
-
-## Stop conditions
-
-Beyond the kernel's general stop conditions:
-
-- A modification outside `in-scope` is needed. Halt; emit scope-amendment request.
-- An invariant would be weakened, dropped, or modified.
-- A required upstream artifact is non-terminal.
-- A forbidden tool would be used (see enumeration above).
-- A load-bearing MCP is unreachable mid-phase.
-- The change requires a migration against a remote environment.
-- A pre-commit or pre-push hook fails after investigation — halt and surface; do not bypass.
-- An existing test would need to be modified, deleted, or have its snapshot updated, and the human has not yet typed the canonical authorization phrase.
-- The engineer has not authorized a destructive git operation that the situation seems to call for.
-- An ambiguity in the plan or change-spec would require the implementer to make a design call beyond its role.
-
-## Failure modes
-
-- **Phase depends-on a phase not yet in `steps-completed`.** Halt and surface the dependency.
-- **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.

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

@@ -1,125 +0,0 @@
----
-name: hstack-kernel-fit-promote
-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
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "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
-
-`hstack-kernel-fit-promote` elevates a kernel-fit finding to a durable kernel-change artifact (ADR by default; tech-debt as a secondary path). It is the only Skill that flips a kernel-fit finding to `status: promoted`. The Skill is a mechanical wrapper per ADR-0001: it constructs the seed material from the finding's body and invokes the appropriate authoring Skill, then performs the reciprocal back-reference write directly. No subagent is invoked by this Skill itself — the authoring Skill it routes to (`/hstack:adr-new` or `/hstack:tech-debt-new`) invokes `spec-author` for the open-ended sections.
-
-The contract the user explicitly required at design time: **no agent creates an ADR without a human gate.** Here the human gate is `spec-author`'s Nygard interview, which the engineer walks every section of before the ADR's `status: accepted` write lands. The promote Skill never auto-creates an ADR — it routes; the engineer confirms.
-
-## When to invoke
-
-Invoke when:
-
-- A kernel-fit finding at `status: open` or `acknowledged` warrants a kernel change and the engineer is ready to author the ADR (or capture the tech-debt). The team has discussed the finding; the proposed direction is approximately right; the engineer is ready to commit time to the interview.
-- The finding's Counter-explanations have been considered and the team has decided they do not weaken the finding enough to dismiss.
-
-Do NOT invoke when:
-
-- The finding is at `confidence: low`. Low-confidence findings should be either dismissed (with substantive rationale) or left at `open` until the next scan accumulates evidence enough to upgrade them. Promoting `low` skips the implicit signal the analyst encoded.
-- The finding has just been written and not yet triaged. Take 24–48 hours to think; the kernel is a high-stakes artifact and the cost of a bad ADR cascades.
-- A scan run has just superseded the finding (`status: superseded`). Promote the superseding finding instead.
-
-## Inputs
-
-- `<finding-id>` (required, positional): the finding id, e.g. `KF-0001-category-a-claim-spans-production` or the short form `KF-0001`.
-- `--slug <text>` (required): kebab-case slug for the destination artifact. Passed through to the authoring Skill (`/hstack:adr-new --slug <text>` or `/hstack:tech-debt-new --slug <text>`).
-- `--target <adr | tech-debt>` (optional, default `adr`): destination artifact type. ADR is the primary path; tech-debt is the secondary path for findings that name a gap but do not yet have a defensible Decision section.
-
-## Preconditions
-
-- `hstack/kernel-fit/findings/<finding-id>*.md` exists. If missing, halt.
-- The finding is at `status: open` or `status: acknowledged`. If at any other status (`dismissed`, `promoted`, `superseded`, `archived`), halt with the current status named.
-- `--slug` is non-empty and matches `^[a-z][a-z0-9-]*$`.
-- `--target` is in the controlled enum (`adr` or `tech-debt`).
-- The downstream Skill (`hstack-adr-new` or `hstack-tech-debt-new`) is reachable from the consuming repo's `.claude/skills/`. (Auto-wired via the symlink delta on `npx hstack update`; this check is a defense against drift.)
-
-## Orchestration steps
-
-1. **Resolve and read the finding.** Glob `hstack/kernel-fit/findings/<finding-id>*.md`; on zero or multiple matches, halt. Parse frontmatter; verify status precondition. Print the finding body in full — the engineer reviews before committing the time to the interview.
-
-2. **Construct the seed material.** Extract three sections from the finding body verbatim:
-   - `## Evidence` (the bullet list with inline citations)
-   - `## Kernel surface implicated` (the single-sentence pointer)
-   - `## Proposed direction` (the one paragraph sketch)
-
-   Compose them into a "Seeded from kernel-fit finding <KF-id>" preface plus the three section bodies, verbatim. This preface becomes the Context seed for the downstream authoring Skill. The Counter-explanations section is NOT seeded — the engineer's Decision section must engage with the kernel-change question fresh, not pre-anchored by the analyst's challenge-prompt output.
-
-3. **Confirm before routing.** Print the proposed slug, the target (adr or tech-debt), and the seed preface. Ask "Route to /hstack:<target>-new with this seed? (Y/n)". Default Yes. On `n`, abort without writing.
-
-4. **Route to the authoring Skill.** 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.
-   - On the engineer's confirmation at `status: accepted`, `adr-new` writes the ADR file with `promoted-from-kernel-fit: [<finding-id>]` in its frontmatter and auto-commits with message `adr(ADR-NNNN-<slug>): accepted`.
-   - The ADR commit lands first. The back-reference commit lands second. See Failure modes for the recoverable carve-out.
-
-   For `--target tech-debt`:
-   - Invoke `/hstack:tech-debt-new --from-kernel-fit <finding-id> --slug <slug>`. `spec-author` walks the six TD sections; the seeded Context is split into Why we took the shortcut, What it costs us, and Fix sketch as appropriate.
-   - On terminal-state, `tech-debt-new` writes the TD file with `introduced-by: kernel-fit:<finding-id>` (the kernel-fit-origin variant of the TD `introduced-by` field; documented as a v1 carve-out — the existing field accepts a `kernel-fit:` prefix to disambiguate from change-spec origins) and auto-commits.
-
-5. **Capture the new artifact id.** Parse the downstream Skill's terminal commit message for `ADR-NNNN-<slug>` or `TD-NNNN-<slug>`. On parse failure (downstream Skill halted mid-interview), the promote Skill halts too — re-invocation will resume from the same step once the downstream Skill completes.
-
-6. **Write the reciprocal back-reference on the finding.** Per ADR-0001 (mechanical writes by the Skill orchestrator), the promote Skill performs the `Edit` itself. 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 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 `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).
-
-9. **Confirm completion.** Print "Promote complete. Finding <finding-id> is now `promoted` with `promoted-to: <promoted-to>`. The kernel change lives in <promoted-to>; this finding is now read-only from kernel-fit's perspective (further edits would require a new finding via the next scan)."
-
-## Outputs
-
-- A new ADR at `hstack/adr/ADR-NNNN-<slug>.md` OR a new TD at `hstack/tech-debt/TD-NNNN-<slug>.md` (via the downstream authoring Skill).
-- An edit to `hstack/kernel-fit/findings/<finding-id>*.md` setting `promoted-to` and `status: promoted`, plus a Triage Log entry.
-- Two commits — one from the authoring Skill (ADR or TD), one from this Skill (finding back-reference).
-
-## Auto-commit triggers
-
-- Two commits per promote: the authoring Skill's own commit at the ADR or TD terminal state, and this Skill's own commit at the finding's `status: promoted` flip.
-
-## Idempotency contract
-
-- Re-running on a finding already at `status: promoted`: the Skill prints "already promoted to <promoted-to>" and exits no-op.
-- Re-running after step 4 succeeded but step 8 failed (the recoverable carve-out): the Skill detects the ADR or TD exists with the correct `promoted-from-kernel-fit` (or `introduced-by: kernel-fit:<id>`), skips re-invoking the authoring Skill, and goes straight to step 6 (back-reference write). Convergence in one re-invocation.
-- Re-running on a `dismissed` or `superseded` finding: halt with the status named. The engineer cannot promote a finding that has been ruled out or restated.
-
-## Stop conditions
-
-Beyond the kernel's general stop conditions:
-
-- The finding does not exist, or is at a terminal-from-promote status (`dismissed`, `promoted`, `superseded`, `archived`). Halt with the status named.
-- `--slug` is missing or malformed. Halt with the regex shown.
-- `--target` is not in the enum. Halt with usage.
-- The downstream authoring Skill halts mid-interview (`spec-author` could not produce two consequences for the ADR Consequences challenge, or the engineer aborted). Propagate the halt; re-invoke when ready.
-- The downstream artifact's commit cannot be parsed for its id at step 5 (e.g., the authoring Skill committed under a non-canonical message format). Halt with a diagnostic and let the engineer reconcile.
-- The validator fails at step 8 because the back-reference is inconsistent with the ADR's `promoted-from-kernel-fit` array. Halt and reconcile — most likely cause is the engineer aborted the authoring Skill before reciprocal write, leaving inconsistent on-disk state.
-
-## Failure modes
-
-- **Recoverable two-commit carve-out (analogous to `/hstack:finalize` in-progress carve-out).** The kernel's atomicity rule (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.