hstack 0.16.0 → 0.17.0

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

@@ -1,113 +0,0 @@
----
-name: hstack-scaffold
-description: Use as greenfield Phase 6 to bootstrap an empty repository from the terminal context artifacts to bootable source, via a generated bootstrap change-spec. Greenfield only; the only init path that lands executable code.
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "{{TODO-SKILL: /hstack:change-new — scaffolds the bootstrap change-spec folder}}"
-  - "{{TODO-SKILL: /hstack:test-plan — produces test-plan.md for the bootstrap}}"
-  - "{{TODO-SKILL: /hstack:security-review — invoked in --mode foundational}}"
-  - "{{TODO-SKILL: /hstack:data-review — invoked in --mode foundational}}"
-  - "{{TODO-SKILL: /hstack:change-plan — invokes planner}}"
-  - "{{TODO-SKILL: /hstack:implement — invokes implementer phase-by-phase}}"
-  - "{{TODO-SKILL: /hstack:verify — invokes verifier after the last implement phase}}"
-  - "{{TODO-SKILL: /hstack:adversarial-review — runs in a fresh session for the bootstrap}}"
-  - "{{TODO-SKILL: /hstack:ship — final scorecard; bootstrap ships with a PR like any change}}"
-  - "{{TODO-SKILL: /hstack:finalize — post-merge cleanup}}"
-  - "node hstack/scripts/validate-spec.mjs — frontmatter validator"
----
-
-## Purpose
-
-`hstack-scaffold` is the Phase 6 execution Skill of `/hstack:greenfield-init`. It bridges discovery to working code: the upstream phases (product-brief, data-architecture, app-architecture, stack ADRs, threat-model, hardening-checklist, infrastructure, incident-runbook) declare the design; this Skill executes it. The execution path is the **standard per-change workflow** applied to a one-off change-spec with `area: bootstrap` — there is no special-cased "bootstrap workflow"; the kernel's per-change discipline applies in full, with two adjustments: (a) `security-review` and `data-review` run in `--mode foundational` (score against proposed posture, not diff), and (b) the change-spec uses the `hstack/templates/bootstrap.md` variant.
-
-## When to invoke
-
-- Phase 6 of `/hstack:greenfield-init` (the orchestrator calls this Skill after Phase 5 terminates).
-- Standalone is **not** supported in v1 — scaffold runs once per project lifetime and assumes the full upstream discovery layer is at terminal status. Standalone invocation halts with a directive to run `/hstack:greenfield-init` instead.
-
-## Inputs
-
-- No positional arguments. The Skill reads upstream artifacts and the bootstrap-change-spec scaffolding from disk.
-
-## Preconditions
-
-- All of the following at `status: current`:
-  - `hstack/context/product/product-brief.md`
-  - `hstack/context/data-architecture.md`
-  - `hstack/context/app-architecture.md`
-  - `hstack/context/threat-model.md`, `hardening-checklist.md`, `infrastructure.md`, `incident-runbook.md`
-  - `hstack/context/tech-stack.md`, `ci-cd.md`
-- Stack ADRs from Phase 4 at `status: accepted`.
-- `hstack/templates/bootstrap.md` present.
-- The consuming repo has no source code beyond `hstack/` and standard hidden files. If non-empty, halt — scaffold is a greenfield-only operation.
-
-## Orchestration steps
-
-1. **Generate the bootstrap change-spec.** Invoke `/hstack:change-new` with `area: bootstrap` and a derived id (`<YYYY-MM>-bootstrap`). The change-spec folder is scaffolded with `spec.md` pre-populated from `hstack/templates/bootstrap.md`. The Skill then performs mechanical writes to populate:
-   - `in-scope`: enumerated from app-architecture Module Map (one entry per module directory) + data-architecture Migration Sketches (one entry per `m_NNNN_*.sql`) + standard infra files (`package.json`, `tsconfig.json`, build config, CI workflow path, etc.). The enumeration is explicit; `["."]` is not permitted.
-   - `related-adrs`: the full list of Phase 4 stack ADRs.
-   - `threat-model-delta: true`.
-   The change-spec lands at `status: draft` after this step; `spec-author` walks it to `ready-to-plan` via a confirmation interview (the engineer reviews the enumerated `in-scope` and confirms or revises).
-
-2. **Test plan.** Invoke `/hstack:test-plan` for the bootstrap. The test-strategist produces `test-plan.md` covering build / lint / typecheck / migration / RLS-enforcement smoke tests. Bootstrap test plans bias toward operational-correctness assertions (build exits 0, migrations apply cleanly, RLS denies cross-tenant access) rather than feature behavior.
-
-3. **Foundational-mode security-review.** Invoke `/hstack:security-review` with the security-reviewer in `--mode foundational`. The reviewer scores against the proposed posture (threat-model + hardening-checklist + the stack ADRs) rather than against a diff. Output: `security-review.md` at `status: passed` or `concerns-noted` per the standard contract.
-
-4. **Foundational-mode data-review.** Invoke `/hstack:data-review` with the data-specialist in `--mode foundational`. The reviewer scores the migration sketches from data-architecture Section 5 against RLS coverage rules (DR-02) and tenant-isolation rules (DR-03), scoring proposed-DDL rather than live schema. Output: `data-review.md` at `status: passed` or `concerns-noted`.
-
-5. **Plan.** Invoke `/hstack:change-plan`. The planner produces `plan.md` with atomic phases. A typical bootstrap plan sequence:
-   - Phase 1: install dependencies (`npm install` / `pnpm install` / equivalent).
-   - Phase 2: initialize framework scaffold (e.g., Next.js boilerplate, tsconfig, eslint config).
-   - Phase 3: land migration files in `supabase/migrations/` per data-architecture Section 5.
-   - Phase 4: scaffold module shells per app-architecture Section 1 (one directory per module with index.ts plus any per-module config).
-   - Phase 5: wire CI workflow per `ci-cd.md`.
-   - Phase 6: smoke tests (build, lint, typecheck, run RLS-denial test).
-   Each phase declares its verifier expectations explicitly.
-
-6. **Implement.** Invoke `/hstack:implement <bootstrap-id> <phase-id>` once per plan phase. Each invocation runs the implementer scope-locked to the `in-scope` enumeration. The implementer creates files (no edits — bootstrap is greenfield) and auto-commits at phase completion.
-
-7. **Verify.** Invoke `/hstack:verify` after the last implement phase. The verifier runs the canonical commands from `ci-cd.md` and compares against per-phase Verifier Expectations.
-
-8. **Adversarial review.** Direct the engineer to open a fresh Claude Code session and run `/hstack:adversarial-review`. Bootstrap inherits the standard fresh-session contract (kernel rule).
-
-9. **Ship + finalize.** After adversarial review reaches `findings-resolved`, `/hstack:ship` produces the PR description. The engineer opens the PR, gets it merged, then runs `/hstack:finalize` to advance the bootstrap change-spec from `ready-to-ship` to `shipped` (no tech-debt resolution applies for bootstrap). `hstack/config.yaml`'s `init-status` flips to `complete` in the same finalize commit.
-
-## Outputs
-
-- A complete bootstrap change-spec folder at `hstack/specs/changes/<YYYY-MM>-bootstrap/` with `spec.md`, `test-plan.md`, `security-review.md`, `data-review.md`, `plan.md`, `verification.md`, `adversarial-review.md`, `pr-body.md`.
-- The consuming repo's actual source files, migrations, CI workflow, build config, and per-module shells.
-- `hstack/config.yaml` at `init-status: complete`.
-
-## Auto-commit triggers
-
-- Bootstrap change-spec advances through standard status transitions (`draft → ready-to-plan → ready-for-implementation → ready-for-review → ready-to-ship → shipped`); each transition auto-commits per the kernel.
-- Each plan phase auto-commits when implementer completes it.
-- `hstack/config.yaml` flips to `init-status: complete` in the finalize commit alongside the change-spec's advance to `shipped`.
-
-## Idempotency contract
-
-Scaffold inherits the standard per-change idempotency contract because bootstrap IS a change-spec:
-
-- Re-running `/hstack:scaffold` reads the bootstrap change-spec's status and resumes at the next non-terminal artifact.
-- Plan phases that have committed are skipped; only the first incomplete phase runs.
-- A failed verifier produces `verification.md` at `status: failed-with-discrepancies`; re-running `/hstack:scaffold` does NOT silently retry — it surfaces the discrepancies and waits for the engineer to either re-implement the failing phase or revise the plan.
-
-## Stop conditions
-
-- Any upstream artifact at non-terminal status.
-- The consuming repo is non-empty at scaffold start.
-- Foundational-mode security-review or data-review lands at `concerns-noted` with unresolved CONCERNS. The engineer either resolves the concerns (revises threat-model / hardening / migration sketches) or accepts them via the standard concerns-acknowledgement path.
-- Implementer halts mid-phase (file already exists outside in-scope, verifier expectation unsatisfiable, etc.). Standard implementer halt semantics apply.
-- The engineer signals end-of-session — the standard per-change idempotency picks up on resume.
-
-## Failure modes
-
-- **Foundational-mode reviewer halts.** Foundational mode is honor-system in v1 — the reviewer is asked to score a proposed posture, not a diff. If the reviewer cannot honestly score (e.g., the threat-model is too thin), the reviewer halts with `HSTACK-HALT: reason=upstream-non-terminal` and routes the engineer back to `/hstack:configure threat-model`.
-- **Implementer scope-lock fires on a path NOT in the enumerated in-scope.** This is a scaffold-spec gap, not an implementer bug. The Skill halts; the engineer revises `in-scope` (mechanical edit by the engineer per the kernel's scope-amendment path) and re-runs `/hstack:implement` for the affected phase.
-- **CI runs from `ci-cd.md` haven't been authored yet for fresh projects.** The bootstrap change-spec's test-plan must define the canonical commands; otherwise verifier has nothing to run. The Skill checks this at preconditions.

package/template/.claude/skills/hstack-security-review/SKILL.md

@@ -1,95 +0,0 @@
----
-name: hstack-security-review
-description: Use when a change-spec is at `ready-to-plan` or later and needs `security-review.md` before implementation. Runs independently of `/hstack:change-plan` and `/hstack:data-review`.
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "{{TODO-SCRIPT: hstack/scripts/score-security-review.ts — computes overall status from the scores map}}"
-  - "node hstack/scripts/validate-spec.mjs — validates security-review frontmatter and SR-01..SR-05"
-  - "{{TODO-MCP: Supabase MCP — optional in v1 for live RLS introspection; v2 substrate will hard-fail when unreachable for db-surface changes}}"
----
-
-## Purpose
-
-`hstack-security-review` produces `security-review.md` for a change-spec by orchestrating the `security-reviewer` subagent. In hstack v1, the artifact is a structured LLM judgment against the hardening checklist plus three mandatory challenge prompts. It is not an executable test artifact; v2 substrate replaces the scoring with real probe outcomes (prompt-injection corpora, RLS bypass attempts, tenant_id fuzzing, secret-redaction probes). This Skill enforces the v1 honesty framing on every output.
-
-## When to invoke
-
-Invoke when a change-spec reaches `status: ready-to-plan` or later. Security-review can run before, after, or concurrently with `hstack-change-plan` and `hstack-data-review` — none of those gate one another. The implementer refuses to start unless this artifact is at `status: passed` or `concerns-acknowledged`.
-
-## Inputs
-
-- `<change-id>` (required, positional): the change-spec id.
-
-## Preconditions
-
-Before any work:
-
-- Verify the change-spec exists and is at `status: ready-to-plan` or later.
-- Verify `hstack/context/threat-model.md` is at `status: current` (not `needs-refresh` or absent). Halt otherwise — the subagent refuses to score against a stale or missing threat model.
-- Verify `hstack/context/hardening-checklist.md` is at `status: current`.
-- Read `hstack/context/tech-stack.md` and `ci-cd.md` (loaded by `security-reviewer` for grounding).
-- Determine whether `surfaces` includes any of `agent`, `auth`, `api`, `db`. If yes, set `threat-model-delta-required: true` for the subagent's session.
-- Note whether the Supabase MCP is wired up. If `surfaces` includes `db` and the MCP is unreachable, the Skill proceeds in v1 degraded mode (flagged in rationale) per the v1/v2 split; v2 substrate hard-fails here.
-
-## Orchestration steps
-
-1. **Invoke `security-reviewer`.** Use the Task tool with `subagent_type: security-reviewer` and context = [kernel, `hstack/templates/security-review.md`, change-spec, threat-model, hardening-checklist, tech-stack, ci-cd]. The subagent scores each applicable hardening item against PASS / CONCERNS / FAIL / not-applicable, with a one-paragraph rationale per item.
-
-2. **Threat-model delta.** When `threat-model-delta-required: true`, the subagent writes section 3 with a non-empty delta against the current threat-model.md. SR-03 enforces this at validation.
-
-3. **Three challenge prompts (mandatory).** Per SR-02 and the subagent's contract, the subagent answers all three challenge prompts. The canonical wording:
-   - "What attack vector did the In-Scope diff create that is NOT covered by the hardening checklist? If none, justify."
-   - "Which tenant_isolation guarantee does this change depend on? Cite the line of code that enforces it."
-   - "What part of this change would behave incorrectly under a malicious payload that the test suite does not cover?"
-   The prompts must be answered; they need not be transcribed. Where a probe fits the change poorly as written, the subagent adapts it so it bites harder and records the adapted question in the heading — the `(a)` / `(b)` / `(c)` prefixes stay, because that is what SR-02 locates the answers by. Each answer is at least one paragraph. The Skill verifies `challenge-prompts-answered: 3` in frontmatter.
-
-4. **Scoring discipline.** Per the subagent's contract, scoring biases toward CONCERNS when evidence is thin. The Skill does not override this bias. Tenant-isolation citations reference real lines of code; the subagent greps to verify.
-
-5. **v1 framing.** Every rationale paragraph uses language like "based on the diff, RLS policy mirrors X" rather than "verified". The Skill rejects any rationale that asserts test-backed evidence — that is v2 substrate territory.
-
-6. **Status transitions.** When every applicable score is `pass` or `not-applicable`, the subagent transitions to `status: passed`. When any score is `concerns`, the subagent transitions to `concerns-acknowledged` only when `concerns-acknowledged-by` is non-null (a human handle the owner has explicitly provided) and section 5 enumerates each open concern. Per SR-05, `passed` is impossible if any score is `concerns` or `fail`.
-
-7. **Tech-debt for deferred concerns.** When a CONCERNS finding is being deferred rather than fixed, the subagent prompts the engineer to invoke `hstack-tech-debt-new` to create the paper trail. The Skill does not file the tech-debt itself; it surfaces the recommendation.
-
-8. **Validate.** Run `node hstack/scripts/validate-spec.mjs <path>` and `{{TODO-SCRIPT: hstack/scripts/score-security-review.ts}}` — SR-01 through SR-05.
-
-## Outputs
-
-- `hstack/specs/changes/<change-id>/security-review.md` at `status: passed` or `concerns-acknowledged`.
-- Optional surfaced recommendation to file tech-debt for any deferred CONCERNS.
-
-## Auto-commit triggers
-
-- Status transition to `in-progress` after the first scores land.
-- Status transition to terminal (`passed` or `concerns-acknowledged`). Commit message: `security-review(<change-id>): passed` or `concerns-acknowledged`.
-- Edits to the `scores` map (because SR-05's terminal-gating depends on it).
-- Edits to `concerns-acknowledged-by` (because it gates SR-04).
-
-## Idempotency contract
-
-- Re-running on a terminal security-review without diff changes: the subagent reads the existing artifact and produces a no-op diff aside from `updated` timestamps.
-- Re-running after the change-spec's `in-scope` has expanded: the subagent re-scopes the diff read and may produce new scores; the engineer confirms or amends.
-- Re-running mid-authoring after a halt: the subagent reads the partial artifact and resumes at the next un-scored item or unanswered challenge prompt.
-
-## Stop conditions
-
-Beyond the kernel's general stop conditions:
-
-- `threat-model.md` or `hardening-checklist.md` at `needs-refresh` or absent. Halt.
-- Supabase MCP unreachable and `surfaces` includes `db` in a high-stakes context (new schema, new RLS). Halt in v1 if the change is high-stakes; v2 always hard-fails here.
-- A score would require evidence (a test result, runtime check) that does not yet exist. The subagent marks CONCERNS with the missing evidence named; does not synthesize a PASS.
-- `concerns-acknowledged-by` would be written without the owner's explicit acknowledgement. Halt.
-- A forbidden surface is touched (service_role Supabase key in agent code, raw shell against production, Pipedream Connect against live customer accounts). Halt — kernel-level stop condition.
-
-## Failure modes
-
-- **Threat-model stale.** Halt; refresh via `hstack-configure --interview threat-model`.
-- **Tenant-isolation citation cannot be produced because the In-Scope diff drops tenant context.** Halt and surface — the change introduces a tenant-isolation bug.
-- **Validator fails SR-02 (fewer than 3 challenge prompts answered).** Halt; the subagent re-runs the missing prompt.
-- **v1 framing slips in a rationale.** The Skill detects "verified by test" language in any rationale paragraph and halts; the subagent re-words.

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

@@ -1,119 +0,0 @@
----
-name: hstack-ship
-description: Use when every artifact for a change is at terminal status and the change needs its merge-readiness scorecard and a generated PR body. Read-only — it does not merge, and post-merge cleanup is `/hstack:finalize`.
-tools:
-  - Read
-  - Write
-  - Grep
-  - Glob
-  - Bash
-  - "node hstack/scripts/validate-spec.mjs — validates every artifact's frontmatter"
-  - "node hstack/scripts/compute-merge-readiness.mjs — computes the twelve-gate scorecard from frontmatter and git"
-  - "hstack/scripts/run-gates.sh — runs the pattern lints GT-03 reads the exit code of"
----
-
-## Purpose
-
-`hstack-ship` is the final merge-readiness Skill. It runs the twelve-gate merge-readiness scorecard over the change's artifacts and the PR diff, and generates a PR description body. It does not invoke any subagent and does not write to any artifact — `ship` is read-only across the change-spec, plan, reviews, and verification.
-
-## When to invoke
-
-Invoke when every per-change artifact is at terminal status and the engineer is ready to open or mark the PR ready-for-review. May be invoked multiple times — the Skill is idempotent and is often used as a "what's left?" diagnostic before the final pass.
-
-## Inputs
-
-- `<change-id>` (required, positional): the change-spec id.
-
-## Preconditions
-
-Before any work:
-
-- Verify the change folder `hstack/specs/changes/<change-id>/` exists.
-- Verify the change-spec exists. Read its `surfaces`, `internal-tooling`, `enables`, `enabled-by`, `trivial` flags to know which conditional gates apply.
-
-The Skill does not pre-halt on artifact non-terminal status — that is what the scorecard reports. It halts only on missing artifacts or unreadable frontmatter.
-
-## Orchestration steps
-
-1. **Run the pattern lints.** `hstack/scripts/run-gates.sh --change <change-id> --suite lint` when `hstack/lints/` carries rule files. Keep the exit code — GT-03 is computed from it and from nothing else.
-
-2. **Compute the twelve-gate scorecard.** Run `node hstack/scripts/compute-merge-readiness.mjs <change-id> --json [--gates-exit <code from step 1>]`. The script reads every artifact's frontmatter, the diff against the merge target, and the git branch, and returns one verdict per gate — `pass`, `fail`, `unknown`, `not-applicable` or `deferred`. `fail` and `unknown` block; "not evaluated" is not "passed".
-
-   Do not re-derive any gate in prose. The gates below are the **contract** — what each gate means, one line each — and `compute-merge-readiness.mjs` is the **only** place they are computed. `--gates` prints the same registry from the script itself.
-
-   | Gate | Contract |
-   | --- | --- |
-   | GT-01 | Spec presence: change folder exists with a change-spec past `draft`, or the change carries `trivial: true`. |
-   | GT-02 | Diff within scope: every changed file is a subset of `change-spec.in-scope`, plus hstack's own artifact trail. Mandatory even for `trivial: true`. |
-   | GT-03 | Pattern lints: every `hstack/lints/*.yaml` rule passes, read from `run-gates.sh`'s exit code. |
-   | GT-04 | `adversarial-review.md` at `findings-resolved`. |
-   | GT-05 | `security-review.md` at `passed` or `concerns-acknowledged`. |
-   | GT-06 | `data-review.md` at `passed` or `concerns-acknowledged`, when `surfaces` includes `db`. |
-   | GT-07 | `ui-brief.md` at `drafted` and `figma-handoff.md` at `ready`, when `surfaces` includes `ui`. |
-   | GT-08 | `user-stories` non-empty, unless exactly one carve-out is declared: `internal-tooling: true` (A), non-empty `enables` (B), `area: bootstrap` (C). Category B is an audit chain, not a transitive check — the downstream spec's user value is the downstream's own GT-08. |
-   | GT-09 | Every cross-reference rule CG-01..CG-04 passes. **Deferred**: the range is named but the four rules are stated nowhere, so the script reports `deferred` with that reason rather than inventing them. |
-   | GT-10 | `test-plan.md` at `passed` or `concerns-acknowledged`, and `verification.test-plan-coverage` shows no missing tenant-isolation tests and no out-of-budget performance assertions. |
-   | GT-11 | When `resolves-tech-debt` is non-empty: every referenced tech-debt exists at `status: in-progress` with `resolution-attempted-at` set, none already carries a `resolved-by`, and the adversarial-review carries its AR-07 Acceptance-satisfied confirmation. `not-applicable` when the array is empty. |
-   | GT-12 | SP-13 mutual exclusion (`internal-tooling: true` **and** non-empty `enables` is a hard FAIL) plus SP-14 reciprocity in both directions — a dangling `enables` or a non-reciprocating `enabled-by` is a FAIL, because by ship time the downstream must be scaffolded. |
-
-   Eleven of the twelve are computed from frontmatter, the diff and the branch alone — no artifact body is read (kernel § Reading artifacts). GT-11's AR-07 half is the single exception, and the script reads that one subsection rather than that file.
-
-3. **Frontmatter validation.** Run `node hstack/scripts/validate-spec.mjs` across every artifact. Any FM-* or per-type validation failure blocks ship.
-
-4. **Generate the PR description body.** Write `hstack/specs/changes/<change-id>/pr-body.md` containing:
-   - Title: the change-spec's `Problem` first sentence, prefixed with the change id.
-   - Summary section: pull the Target Behavior bullets from the change-spec.
-   - Surfaces touched: from frontmatter.
-   - Linked artifacts: pointers to spec, plan, test-plan, reviews, verification, adversarial-review.
-   - Tech-debt created: pointers from `change-spec.creates-tech-debt`.
-   - Test plan: pulled from `test-plan.md` — pyramid summary, tenant-isolation tests, and performance budgets — cross-referenced with `verification.test-plan-coverage` to show observed-vs-promised.
-   - Tech-debt resolved: pointers from `change-spec.resolves-tech-debt` with each TD's Title and Acceptance summary. When non-empty, the body explicitly notes that `/hstack:finalize <change-id>` must be run post-merge to flip each TD to `resolved`.
-   - Scorecard summary: the twelve-gate table from step 2.
-
-   The pr-body.md is for the engineer to copy into the actual PR description — the Skill does not call `gh pr create` or otherwise open the PR.
-
-5. **Advance change-spec status.** When every gate passes, the Skill emits the recommended status transition: `ready-for-review` → `ready-to-ship`. The Skill does not write this transition itself — the engineer either confirms (in which case the engineer can advance via direct edit, or `spec-author` is invoked separately) or addresses any remaining issues. This separation preserves the kernel's rule that humans confirm status transitions to ship-readiness.
-
-6. **Surface finalize handoff.** When every gate passes AND `change-spec.resolves-tech-debt` is non-empty, the Skill emits a clear directive: "After this PR merges, run `/hstack:finalize <change-id>` to advance the change-spec to `shipped` and flip [TD-NNNN, TD-MMMM] to `resolved` with `resolved-by` set." When `resolves-tech-debt` is empty, the Skill still notes: "After merge, run `/hstack:finalize <change-id>` to advance the change-spec to `shipped`." The finalize handoff is informational at ship time — the actual writes happen in `/hstack:finalize`, never here.
-
-## Outputs
-
-- `hstack/specs/changes/<change-id>/pr-body.md` (new or updated) — the PR description body.
-- A scorecard printed to the conversation: per-gate pass/fail summary with the failing artifact and field named for any FAIL.
-- A recommended next action: either "open / mark the PR ready-for-review and advance status to `ready-to-ship`" or a list of failing gates.
-
-The Skill does not auto-commit any artifact status transitions. `pr-body.md` is committed when written.
-
-## Auto-commit triggers
-
-- One commit when `pr-body.md` is written or updated. Commit message: `ship(<change-id>): pr-body`.
-
-## Session boundary
-
-`ship` is a natural session cut: the auto-commit above left `pr-body.md` and the scorecard 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: ship complete — cut recommended before the merge, then finalize.
-```
-
-and the next command, `/hstack:finalize <change-id>`.
-
-## Idempotency contract
-
-- Re-running on the same change: re-reads every artifact and recomputes the scorecard. `pr-body.md` is rewritten if any artifact has changed since the prior run; otherwise a no-op. When the existing `pr-body.md` carries engineer edits beyond the generated template, surface a diff and ask before rewriting — never silently overwrite hand-written PR prose.
-- Re-running after fixing a failing gate: the scorecard reports the new state.
-
-## Stop conditions
-
-Beyond the kernel's general stop conditions:
-
-- The change folder or the change-spec is missing on disk, or any artifact's frontmatter cannot be parsed. Both exit `compute-merge-readiness.mjs` with code 2 and a named cause — surface it verbatim rather than scoring a partial set.
-- GT-02 (diff within scope) fails — this is a hard halt with a clear message naming the out-of-scope files; the engineer either reshapes the change-spec via `spec-author` or splits via the multi-module pattern.
-- GT-02 reports `unknown` because HEAD is the merge target. There is no PR diff to score from the default branch; check out `change/<change-id>` (`/hstack:branch <change-id>`) and re-run.
-
-## Failure modes
-
-- **Trivial PRs.** When the change-spec carries `trivial: true`, several gates are skipped per the kernel. The Skill still computes the diff-within-scope and pattern-lint gates (GT-02 and GT-03 remain mandatory even for trivial PRs).
-- **Parent-change (multi-module) records.** When the change-spec is a coordination record (`children` non-empty), run the script once per child id and produce a parent-level summary. The parent reaches ready-to-ship only when every child does.
-- **Pattern-lint failure.** Surface the failing rule and the offending lines from the captured output. The fix is via a new `hstack-implement` invocation against an appropriate phase (or a scope amendment if the lint surfaced new in-scope needs).
-- **A gate reports `unknown`.** Something could not be evaluated — git is unavailable, the merge target does not resolve, or the lint runner was not run. `unknown` blocks exactly like `fail`: report what was not evaluated and why, and do not present the change as ready.

package/template/.claude/skills/hstack-stack-decide/SKILL.md

@@ -1,81 +0,0 @@
----
-name: hstack-stack-decide
-description: Use to decide stack layers — framework, database, auth, hosting, observability — and capture each as an ADR. Greenfield Phase 4, the brownfield stack step when stack ADRs are missing, or a standalone mid-project layer swap.
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "{{TODO-SKILL: /hstack:adr-new — invoked via spec-author handoff for ADR authoring}}"
-  - "{{TODO-SKILL: /hstack:research — invoked for unfamiliar-territory deep-dives}}"
-  - "node hstack/scripts/validate-spec.mjs — frontmatter validator"
----
-
-## Purpose
-
-`hstack-stack-decide` is the atom that produces stack ADRs via the `stack-architect` subagent. It does NOT write to `hstack/adr/` directly; the kernel rule reserves ADR authoring for `spec-author`. Stack-architect produces pre-populated Context / Decision / Alternatives content; spec-author runs the Nygard interview in confirm-or-revise mode with the Consequences challenge firing fresh.
-
-## When to invoke
-
-- Phase 4 of `/hstack:greenfield-init`.
-- The stack-decision step of `/hstack:brownfield-init` when no stack ADRs exist.
-- Standalone via `/hstack:stack-decide [--layer <name>]` for mid-project layer swaps.
-
-## Inputs
-
-- `--layer <name>` — optional, standalone mode. Runs against a single declared layer (`framework | database | auth | hosting | observability | <custom>`). In greenfield/brownfield mode, the Skill walks all declared layers.
-
-## Preconditions
-
-- `hstack/config.yaml` at `init-status: minimal-complete` or later, with the default-stack declaration present (set in greenfield-init Phase 0 or via `/hstack:configure default-stack`).
-- `hstack/context/app-architecture.md` at `status: current` (greenfield/brownfield mode). In standalone mode, the atom may run without app-architecture only if the layer being swapped doesn't depend on architecture decisions (rare).
-- `hstack/templates/adr.md` present.
-- No layer choice contradicts `data-architecture.md`'s `assumes-database`. A non-Postgres choice against `assumes-database: postgres` is never honored silently — halt and surface, and the engineer either refreshes the upstream atom or revises the constraint.
-- Existing ADRs read at session start to set the next sequential ADR id and detect supersession candidates.
-
-## Orchestration steps
-
-1. **Detect mode.** Greenfield/brownfield: walk all declared layers. Standalone: run against the named `--layer`.
-2. **Invoke `stack-architect` subagent.** Via the Task tool with `subagent_type: stack-architect`. Pass mode, layer scope, the canonical session-start context.
-3. **For each layer (greenfield/brownfield mode):**
-   - **Default check.** stack-architect reads `hstack/config.yaml`'s declared default for this layer.
-   - **Fast-path confirmation.** If the engineer accepts the default, the layer is added to a pending rollup ADR.
-   - **Deep-dive.** If the engineer chooses to deep-dive, stack-architect runs the constraint interview (scale, ops capacity, compliance, AI-native specifics), surfaces 2–3 candidate options with tradeoff axes, and lets the engineer choose.
-   - **ADR handoff.** stack-architect prepares the Context / Decision / Alternatives sections, then invokes `/hstack:adr-new` via the Task tool (which invokes `spec-author`). spec-author runs confirm-or-revise on the prepared content. The Consequences challenge prompt fires fresh per the kernel's Nygard challenge rule.
-4. **Rollup ADR (greenfield/brownfield mode).** After per-layer ADRs land, the Skill produces one rollup ADR via `/hstack:adr-new` naming every defaulted layer with the constraint check that confirmed each.
-5. **Standalone mode** runs the same constraint interview + spec-author handoff for the single `--layer`. The new ADR carries `supersedes: [<predecessor>]`; the predecessor gets the reciprocal `superseded-by` written atomically by spec-author.
-6. **Config update (optional).** After ADRs land, the Skill asks the engineer whether any layer's choice diverged from the prior default in a way they want project-wide. If yes, the Skill proposes a `hstack/config.yaml` update via the proposed-diff preview + Y/n gate, then commits the config update as a mechanical operation.
-
-## Outputs
-
-- One rollup ADR plus N per-layer ADRs (greenfield/brownfield mode), or one new ADR with `supersedes` (standalone mode), all at `status: accepted`.
-- Updated `hstack/config.yaml` default-stack declaration (optional, only if changed).
-- `hstack/.session-state/<session-id>.yaml` (transient).
-
-## Auto-commit triggers
-
-- Each ADR commits via `/hstack:adr-new`'s standard pattern (single auto-commit per ADR).
-- Standalone mode's supersedes / superseded-by reciprocal pair commits atomically in one git commit per the kernel.
-- Config update (if any) commits as a separate mechanical operation.
-
-## Idempotency contract
-
-- If a layer's current ADR is at `accepted` and the engineer's constraints + default-stack haven't changed: skip the layer.
-- If a deep-dive interview was started but no ADR landed (engineer parked mid-interview): resume the interview from session-state.
-- Re-running standalone mode for a layer whose ADR is already at `accepted` and no supersession is requested: print summary, exit no-op.
-
-## Stop conditions
-
-- App-architecture at non-terminal status (greenfield/brownfield mode).
-- A chosen option contradicts an upstream invariant (e.g., DB without RLS conflicts with `data-architecture.md`'s tenant-scoped posture). Halt with `HSTACK-HALT: reason=upstream-drift`.
-- A research session is needed (unfamiliar territory) but the engineer has not authorized `/hstack:research`.
-- Standalone mode supersedes an ADR at a non-accepted status.
-- The Postgres assumption in `data-architecture.md` is being contradicted. Halt and surface.
-
-## Failure modes
-
-- **spec-author handoff fails partway** (e.g., Consequences challenge produces a finding the engineer doesn't accept). The pending ADR sits at `draft`; the engineer either revises or routes through `/hstack:configure adr-author <id>` per spec-author's recovery path.
-- **Research subagent unavailable when needed.** Persist constraint interview state; resume later.

package/template/.claude/skills/hstack-story-draft/SKILL.md

@@ -1,92 +0,0 @@
----
-name: hstack-story-draft
-description: "Use when a user-facing change needs a story drafted or refined against an existing persona. Conditional — skipped when the parent change-spec is `internal-tooling: true` or has a non-empty `enables` array."
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "{{TODO-MCP: Notion MCP — required when configured story store is Notion}}"
-  - "{{TODO-MCP: Linear MCP — required when configured story store is Linear}}"
-  - "{{TODO-MCP: GitHub MCP — required when configured story store is GitHub Issues}}"
-  - "node hstack/scripts/validate-spec.mjs — validates story frontmatter and ST-01/ST-02/ST-03"
----
-
-## Purpose
-
-`hstack-story-draft` produces or refines one user story by orchestrating the `product-manager` subagent. It maintains the reciprocal `user-stories` ↔ `linked-change-specs` linkage between the story and its parent change-spec. It is conditional — skipped automatically for changes marked Category A (`internal-tooling: true`) or Category B (`enables` non-empty). For Category B, the user value lives in the downstream change-spec(s) named in `enables`; the story (if any) is drafted against that downstream spec, not this one.
-
-## When to invoke
-
-Invoke when the engineer wants a story for a user-facing change before SP-09 / GT-08 require it, or to refine an existing story whose fields the team is reworking. Run after `hstack-change-new` so the parent change-spec already exists and can receive the reciprocal link.
-
-## Inputs
-
-- `--change <id>` (optional): the parent change-spec id. If omitted, the Skill asks the engineer interactively.
-- `--story <id>` (optional): an existing story id to refine. If omitted, the Skill drafts a new story.
-- `--persona <id>` (optional): the persona to anchor on. If omitted, `product-manager` interviews the engineer for the anchor.
-
-## Preconditions
-
-Before any work:
-
-- Verify `hstack/config.yaml` exists at `init-status: complete`.
-- Verify the parent change-spec exists when `--change` is provided or when context implies it.
-- Verify `hstack/context/personas/` (or the configured personas store) contains at least one persona at `status: current`.
-- Verify the configured story store's MCP is reachable when the store is Notion / Linear / GitHub. If unreachable, halt — the kernel forbids silent fallback to a different store.
-- If the parent change-spec carries `internal-tooling: true`, halt and surface: "Story not required — change is Category A (internal tooling, never on a user path)."
-- If the parent change-spec carries `enables` non-empty, halt and surface: "Story not required — change is Category B (foundational prerequisite; user value lives in <enables-ids>). Draft a story against the downstream spec instead."
-- If the parent change-spec carries BOTH `internal-tooling: true` AND `enables` non-empty, halt with SP-13 violation: "Categories A and B are mutually exclusive. Pick one via `spec-author`."
-- Read `hstack/context/vision.md`, `roadmap.md`, and the personas index (required by `product-manager`'s session-start protocol).
-
-## Orchestration steps
-
-1. **Determine mode.** Draft a new story (no `--story` argument) or refine an existing one (`--story <id>` argument). Read the existing story when refining.
-
-2. **Invoke `product-manager`.** Use the Task tool with `subagent_type: product-manager` and context = [kernel, `hstack/templates/story.md`, vision, roadmap, personas store, parent change-spec when known, existing story when refining]. The subagent runs the five-section interview — Who and Why, What Shipping Looks Like, Success Metric, Edge Cases the User Cares About, Out of Scope for This Story — with confirmation gates.
-
-3. **Verify the persona anchor exists.** Per ST-01, the story's `persona` field must reference an existing persona at `current`. If the engineer names a persona that does not exist, `product-manager` halts and runs a sub-interview to author it first (or the engineer chooses an existing one).
-
-4. **Exercise the Edge Cases challenge.** Per the `product-manager` contract, the Edge Cases section uses the challenge prompt "What does the user notice if this ships but is slightly broken?" with a minimum of two bullets. The Skill does not bypass this on refinement.
-
-5. **Reciprocity.** When the story reaches `status: in-flight` (i.e., its `linked-change-specs` is non-empty), the Skill confirms the parent change-spec's `user-stories` array contains the story id and writes it if absent. The reciprocal write is performed by `product-manager` per its contract (the spec-author handles change-spec field writes generally, but for the `user-stories` array specifically, `product-manager`'s contract permits the reciprocal write).
-
-6. **Persist.** When the story store is external (Notion/Linear/GitHub), `product-manager` writes via the MCP and produces a local sync stub at `hstack/stories/<id>.md` referencing the external record. When the store is `hstack/stories/`, the file is written directly.
-
-7. **Validate.** Run `node hstack/scripts/validate-spec.mjs <path>` against the story — ST-01 (persona references existing), ST-02 (linked-change-specs non-empty at `in-flight`), ST-03 (success metric non-empty string).
-
-## Outputs
-
-- A new or updated story at the configured store, at `status: drafted`, `ready`, or `in-flight` per the engineer's intent.
-- Reciprocal `user-stories: [<story-id>]` entry on the parent change-spec.
-- When the store is external: a sync stub at `hstack/stories/<id>.md`.
-
-## Auto-commit triggers
-
-- Status transition of the story to `drafted` after the first sections land.
-- Status transition to `ready` or `in-flight` at the end of the interview.
-- Reciprocal write to the parent change-spec's `user-stories` array (commits the parent change-spec file).
-
-## Idempotency contract
-
-- Re-running with the same `--story` id and identical engineer answers is a no-op aside from `updated` timestamps.
-- Re-running mid-interview after a halt: `product-manager` reads the partial story and resumes at the next un-confirmed field.
-- Re-running to refine: existing values are the proposal layer; accepting all current values is a no-op.
-
-## Stop conditions
-
-Beyond the kernel's general stop conditions:
-
-- The configured story-store MCP is unreachable. Halt.
-- The named persona does not exist and the engineer declines the sub-interview to author it.
-- The success metric the engineer offers is not concretely measurable. `product-manager` re-prompts; the Skill halts after a reasonable number of re-prompts.
-- The story would drift outside the roadmap's Now horizon. `product-manager` flags; the Skill asks whether to update the roadmap (via `hstack-configure --interview roadmap`) or defer the story.
-
-## Failure modes
-
-- **Parent change-spec is `internal-tooling: true` (Category A) or `enables` non-empty (Category B).** Halt early; the story is unnecessary. For Category B, redirect the engineer to draft a story against the downstream change-spec named in `enables`.
-- **Reciprocal write to the parent change-spec would advance its status.** It should not — the reciprocal write only touches the `user-stories` array. If the validator detects a status change, halt and ask.
-- **Validator fails.** Halt and surface; the engineer rewords the failing field.

package/template/.claude/skills/hstack-tech-debt-new/SKILL.md

@@ -1,95 +0,0 @@
----
-name: hstack-tech-debt-new
-description: Use to capture a new tech-debt item — a compromise the team is agreeing to live with for now — with its reciprocal back-reference on the originating change-spec. Capture only; the three closure paths are separate Skills.
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "node hstack/scripts/validate-spec.mjs — validates tech-debt frontmatter and TD-01..TD-03"
----
-
-## Purpose
-
-`hstack-tech-debt-new` captures a tech-debt item via the `spec-author` subagent. Tech-debt artifacts live at `hstack/tech-debt/TD-NNNN-<slug>.md`, are append-only, and maintain a reciprocal back-reference to the originating change-spec via the `introduced-by` ↔ `creates-tech-debt` pair (TD-01).
-
-## When to invoke
-
-Invoke when:
-- The engineer ships a deliberate compromise (a hack-now-fix-later) and wants it logged.
-- The `adversarial-reviewer` surfaces a finding routed to `tech-debt:<id>` and the artifact does not yet exist.
-- A retrospective surfaces accumulated debt that was not captured at the time it landed (origin: `found-later`).
-
-## Inputs
-
-- `<slug>` (required, positional): kebab-case slug. Examples: `overage-banner-tailwind-class`, `stripe-webhook-idempotency-buffer`.
-- `--origin <change-spec-id>` (optional): the change-spec that introduced this debt. When set, reciprocal writes apply. When omitted, origin defaults to `found-later`.
-
-## Preconditions
-
-Before any work:
-
-- Verify `hstack/config.yaml` exists at `init-status: complete`.
-- Read every existing tech-debt item under `hstack/tech-debt/` to determine the next sequential id.
-- Verify the `<slug>` matches `^[a-z][a-z0-9-]*$` and is not already used.
-- When `--origin <change-spec-id>` is provided: verify the change-spec exists.
-- Scan existing tech-debt for a near-duplicate (same module, similar slug). Surface any candidates to the engineer; if the new debt is genuinely a duplicate, the Skill halts and directs the engineer to update the existing item instead.
-
-## Orchestration steps
-
-1. **Compute the next id.** `TD-NNNN-<slug>`.
-
-2. **Invoke `spec-author` with explicit deferred-commit instruction.** Use the Task tool with `subagent_type: spec-author` and context = [kernel, `hstack/templates/tech-debt.md`, glossary, the originating change-spec when `--origin`]. The subagent walks the six sections — Title, Why we took the shortcut, What it costs us, Fix sketch, Pre-conditions for fixing, Acceptance — with confirmation gates. **Critical instruction to spec-author**: do NOT auto-commit at terminal author-state (`status: open`) when invoked under `/hstack:tech-debt-new`. The Skill will perform the atomic commit after the reciprocal change-spec write in step 7. Spec-author should leave the new TD file staged-but-uncommitted (or unstaged) so the Skill can include both halves of the reciprocal pair in a single commit. This deviation from spec-author's normal auto-commit-at-status-transition behavior is mandated by the kernel's atomicity rule for reciprocal pairs.
-
-3. **Severity.** The subagent elicits severity (critical | high | medium | low). For `severity: critical`, a `target-resolve-by` date is required per TD-02 (this is a future field — surface in the conversation that v1 does not yet enforce it via the validator).
-
-4. **Cost and fix-sketch-effort.** Both are controlled enums (`small | medium | large`).
-
-5. **Reciprocity.** When `--origin <change-spec-id>` is set:
-   - **Authoring half (spec-author).** `spec-author` writes `introduced-by: <change-spec-id>` on the new tech-debt frontmatter during its interview (this field is part of the artifact being authored, so it lands inside the spec-author session). Per the deferred-commit instruction in step 2, spec-author does NOT auto-commit on terminal author-state under this Skill — it leaves the TD file written but uncommitted.
-   - **Reciprocal half (direct write by this Skill).** After `spec-author` finishes the interview and returns, this Skill performs the reciprocal write itself via the `Edit` tool — no second `spec-author` invocation. Edit `hstack/specs/changes/<change-spec-id>/spec.md`:
-     - Append the new tech-debt id to the frontmatter `creates-tech-debt` array (idempotent — if already present, no-op).
-     - Update frontmatter `updated: <today>`.
-   - Per the kernel's Mechanical operations section, this reciprocal write is mechanical: the value to append is fully determined by the just-authored TD's id. No interview is required.
-   - TD-01 enforces this at validation. Both files land in a single auto-commit (step 7 below) so the reciprocal pair is atomic.
-
-6. **Proposed-diff preview (confirmation gate).** Per the kernel's AI-writes-humans-confirm contract for mechanical operations, print the proposed reciprocal-write diff (the `creates-tech-debt` array append on the change-spec, the `updated` bump) and ask "Proceed with these writes? (Y/n)". Default Yes. On `n`, halt without staging the change-spec edit; the TD file remains unstaged so the engineer can `git checkout -- <td-file>` to discard.
-
-7. **Validate and atomic-commit both files.** Run `node hstack/scripts/validate-spec.mjs <path>` against the new TD and (when `--origin` is set) the modified change-spec. TD-01 (reciprocity), TD-02 (severity:critical requires target-resolve-by — v1 surfaces only), TD-03 (no field rewrites once resolved; v1 informational) all checked. On validation pass, `git add` both files and commit with message `tech-debt(TD-NNNN): open` (with `(introduced-by: <change-spec-id>)` appended when applicable). The reciprocal pair (TD `introduced-by` ↔ change-spec `creates-tech-debt`) lands in this single atomic commit. On validation failure, halt; both files remain unstaged for the engineer to inspect or discard.
-
-8. **Status note.** The new artifact lands at `status: open`. Advancing to `in-progress` or `resolved` is a separate later operation, not this Skill's domain. Nor does this Skill ever overwrite an existing tech-debt item: a body revision on an item being actively worked goes through a direct `spec-author` invocation.
-
-## Outputs
-
-- `hstack/tech-debt/TD-NNNN-<slug>.md` at `status: open`.
-- When `--origin` is set: an edit to the originating change-spec's `creates-tech-debt` array.
-
-The tech-debt item lands at `status: open`. To begin resolution work, invoke `/hstack:tech-debt-resolve TD-NNNN`. To close without a fix, invoke `/hstack:tech-debt-wontfix TD-NNNN`. The new fields `resolved-by`, `resolution-attempted-at`, `wontfix-reason`, `wontfix-accepted-alternative` are left as their template defaults (`null`) at creation time — they are written by the corresponding resolution Skill.
-
-## Auto-commit triggers
-
-- One commit at terminal author-state (`status: open`). When reciprocity writes are involved, both files are included in the commit. Commit message: `tech-debt(TD-NNNN): open` (with the origin change-spec in parentheses when applicable).
-
-## Idempotency contract
-
-- Re-running with the same `<slug>` halts because the slug would not be unique.
-- Re-running mid-interview after a halt: `spec-author` reads the partial tech-debt file and resumes.
-- Reciprocal writes are idempotent: if the change-spec's `creates-tech-debt` already contains the tech-debt id, the Skill does not duplicate.
-
-## Stop conditions
-
-Beyond the kernel's general stop conditions:
-
-- The `<slug>` collides with an existing tech-debt item.
-- `--origin` references a change-spec that does not exist.
-- A near-duplicate tech-debt item already exists and the engineer should update it instead.
-- The Why-we-took-the-shortcut field is empty — every tech-debt item must explain its origin, not just enumerate the cost.
-
-## Failure modes
-
-- **Reciprocal write to the change-spec fails (e.g., the change-spec's frontmatter is broken).** Halt before commit; the TD authoring half also rolls back unstaged. The engineer fixes the change-spec frontmatter manually (broken YAML is hand-fixed and validated; if the change-spec body needs prose authoring corrections, `spec-author` can resume the change-spec since change-spec body editing is interview-driven, but `spec-author` cannot touch the `creates-tech-debt` reciprocal field per kernel — the Skill performs that append on the re-run). Then re-run `/hstack:tech-debt-new` — the Skill is idempotent on the TD half (spec-author resumes the existing partial file) and idempotent on the reciprocal append (a no-op if the TD id is already in the array).
-- **The change-spec is at `shipped` or `archived` status.** TD-03 forbids rewrites on resolved items, but the change-spec at `shipped` may still accept `creates-tech-debt` array appends — surface and confirm with the engineer before writing.
-- **Validator fails TD-01.** Halt before commit; the partial state on disk is unstaged. The engineer reconciles by running the Skill again — the reciprocal half is idempotent and the TD half resumes from the existing file.