hstack 0.16.0 → 0.17.0

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

@@ -1,94 +1,53 @@
 ---
 name: hstack-commit
-description: Use to commit hand-made edits in the same Commitizen format hstack subagents use for their auto-commits. For work outside a subagent flow only — subagents auto-commit at status transitions on their own.
-tools:
-  - Bash
-  - Read
-  - Grep
+description: "Use to commit: the one Commitizen format Hugo, Luke and the agents all write, so the git log reads the same whoever wrote the commit. Stages by named path, honours every hook, pushes only on confirmation."
 ---
 
 ## Purpose
 
-`hstack-commit` is the human-driven commit Skill that matches the Commitizen format hstack subagents use for their auto-commits. The point is uniform git history: a reader scanning the log cannot tell whether a given commit was a subagent auto-commit or a human-typed one, because both follow `<type>(<scope>): <summary>`. It does not replace the kernel's auto-commit-at-status-transition rule — subagents still auto-commit on their own. The Skill is for everything else: typo fixes, ad-hoc cleanups, edits between hstack invocations, the occasional manual touch.
+One format for every commit in the repo — Hugo's, Luke's, an agent's. A reader scanning `git log` cannot tell which is which, because all three write `<type>(<scope>): <summary>`. It costs nothing per change, which is why it survived the pivot.
 
 ## When to invoke
 
-Invoke when:
-- You've made an edit by hand (outside a hstack subagent flow) and want to commit it.
-- You want to commit work-in-progress before stepping away.
-- A subagent auto-commit didn't fire (rare, but possible if a Skill halted mid-phase) and you need to capture state manually.
-
-Do NOT invoke inside an hstack subagent flow — the subagents auto-commit on status transitions per the kernel.
+Whenever there is something to commit: the end of a change (`/hstack-wrap` commits in this format), a typo fix, work in progress before stepping away.
 
 ## Inputs
 
-- No positional arguments. The Skill drives entirely from `git status` and conversation.
-- Optional `--push` flag: if set, push after committing (still subject to explicit per-invocation confirmation; the system never force-pushes).
-
-## Preconditions
-
-Before any work:
-
-- Verify the working directory is a git repository.
-- Read `hstack/config.yaml` if present, to namespace the commit scope when committing inside an hstack-governed repo. Absent config is fine — the Skill works on any repo, hstack-installed or not.
-- Verify there are changes to commit. If working tree is clean, halt with "nothing to commit."
-
-## Orchestration steps
-
-1. **Read git status.** Run `git status --short` and show the file list with their status markers. Categorize: modified, untracked, deleted, renamed.
+Optional `--push`: push after committing — still subject to per-invocation confirmation.
 
-2. **Stage with intent.** Default to staging by named path, NOT `git add -A`. The latter sweeps in `.env`, credentials, large binaries, and other unintended files. The Skill proposes the specific files to stage based on the change being committed, the engineer confirms.
-   - Exception: if every file is clearly part of one logical change AND none of the file names match common sensitive patterns (`.env`, `secret`, `credential`, `*.key`, `*.pem`), the Skill may propose `git add -A` with the engineer's explicit confirmation.
-   - Sensitive-file guardrail: if any staged file's name matches the sensitive-pattern list, halt and ask before committing.
+## Steps
 
-3. **Show the diff.** Run `git diff --cached --stat` for a summary, then `git diff --cached` for the full diff if the diff is reasonably small. For large diffs, show stat plus a sample of the most-changed files.
+1. **Read `git status --short`** and show the file list with its status markers.
 
-4. **Draft a Commitizen-format commit message.** Following the format codified for hstack:
-   - Format: `<type>(<scope>): <summary>`
-   - `<type>` is one of: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `style`, `perf`, `ci`
-   - `<scope>` names the area actually touched — never an invented or aspirational one. For commits inside hstack-governed code, prefer the change-id, the area, the Skill name, or the artifact type (e.g., `change-plan`, `billing`, `implement`, `data-review`). For non-hstack commits in the same repo, use the natural area (e.g., `auth`, `orchestrator`, `webhooks`). When the change spans several unrelated areas, no single honest scope exists — propose splitting into multiple commits.
-   - `<summary>` ≤ 72 characters, imperative present tense ("add" not "added"), no trailing period.
-   - Body (optional): the "why" rather than the "what". For commits inside hstack workflow, name the related change-id or artifact. For status transitions, name the transition explicitly.
-   - **Never add "Generated with Claude Code" or similar attribution.** The user's global rule.
-   - Footer: only conventional-commits footers (`BREAKING CHANGE:`, `Refs: <issue>`) when applicable.
+2. **Stage by named path.** Not `git add -A`, which sweeps in `.env`, credentials and large binaries. Propose the specific paths that belong to the change being committed; the engineer confirms. `git add -A` is available when every file is clearly part of one logical change and no filename matches a sensitive pattern (`.env`, `secret`, `credential`, `*.key`, `*.pem`) — with explicit confirmation. If a staged filename matches one of those patterns, halt and ask.
 
-5. **Confirm and commit.** Show the proposed commit message to the engineer. On confirmation, run `git commit -m "<subject>" -m "<body>"` (HEREDOC for multi-line bodies). Honor every git hook — `--no-verify`, `--no-gpg-sign`, and other bypass flags are forbidden.
+3. **Show the diff.** `git diff --cached --stat`, then the full `git diff --cached` when it is small enough to read. For a large one, the stat plus the most-changed files.
 
-6. **Kernel rules still apply.** Committing by hand does not relax the kernel's database-workflow or forbidden-tools rules. A `service_role` key, a `supabase db push` against a remote project, or any other kernel-forbidden artifact is forbidden on this path exactly as it is on the subagent path.
+4. **Draft the message.**
+   - `<type>(<scope>): <summary>`, where `<type>` is one of `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `style`, `perf`, `ci`.
+   - `<scope>` names the area actually touched — never an invented or aspirational one. When the change spans unrelated areas, no single honest scope exists: propose splitting it into several commits.
+   - `<summary>` ≤ 72 characters, imperative present ("add", not "added"), no trailing period.
+   - Body, when it earns its place: the why, not the what.
+   - **Never "Generated with Claude Code" or any similar attribution.**
+   - Footer: conventional-commits footers only (`BREAKING CHANGE:`, `Refs: <issue>`).
 
-7. **Verify the commit landed.** Run `git log -1 --format='%h %s'` and surface the result.
+5. **Confirm, then commit.** Show the message; commit on confirmation. Every hook runs — `--no-verify`, `--no-gpg-sign` and every other bypass are forbidden, whatever the deadline.
 
-8. **Push (only with explicit confirmation).** Push is hard-to-reverse and visible to others — never auto-push. If `--push` was provided, ask for confirmation in the conversation; if not provided, end without pushing. When pushing, use the current branch's tracked upstream (no `--force`, no force-with-lease without per-invocation authorization, no push to `main` if the current branch is `main` without explicit confirmation).
+6. **Verify it landed.** `git log -1 --format='%h %s'`, surfaced.
 
-## Outputs
+7. **Push only on explicit confirmation.** A push is visible to others and hard to reverse, so it is never automatic. Push to the current branch's tracked upstream, never with `--force`.
 
-- One git commit on the current branch.
-- Optionally, a `git push` to the current branch's upstream — but only with explicit per-invocation confirmation.
-- No artifact writes. No subagent invocations.
+## Output
 
-## Auto-commit triggers
-
-None. This Skill IS the commit — there is nothing else for it to auto-commit. Subagents have their own auto-commit logic governed by the kernel.
-
-## Idempotency contract
-
-Not idempotent in the strict sense — a commit is a one-shot operation. Re-running the Skill on a clean working tree halts with "nothing to commit," which is the natural idempotency boundary.
+One commit on the current branch. Optionally one push, confirmed in the conversation.
 
 ## Stop conditions
 
-Beyond the kernel's general stop conditions:
-
-- Working tree is clean. Nothing to commit.
-- A staged file's name matches the sensitive-pattern list (`.env`, `*secret*`, `*credential*`, `*.key`, `*.pem`). Halt and ask.
-- A pre-commit hook fails. Investigate and fix the underlying issue — do NOT bypass with `--no-verify`. If the fix requires out-of-scope edits (when committing inside an hstack-governed change), halt and surface as a scope-amendment situation.
-- The proposed commit message exceeds 72 characters on the summary line. Re-draft.
-- A destructive push operation is requested (`--force`, force-with-lease, push to `main`) without explicit per-invocation authorization in the current conversation. Halt and confirm.
-- `git commit --amend` would rewrite a commit that has already been pushed. Halt and confirm per-invocation; amending published history is not a default.
-- The engineer requested `--push` but the current branch has no upstream. Halt and ask which remote / branch to push to.
-
-## Failure modes
+Beyond the kernel's:
 
-- **Pre-commit hook fails.** Investigate; surface the hook's output; propose a fix. Re-run the commit attempt with the fix in place. Never bypass.
-- **`gpg-sign` configured but signing key unavailable.** Surface the gpg error; do NOT bypass with `--no-gpg-sign`. Engineer fixes their gpg config and re-runs.
-- **`git push` rejected (non-fast-forward).** Surface the rejection; recommend `git pull --rebase` then re-attempt; never propose `--force` without explicit authorization.
-- **Empty commit attempted.** If `git add` left the index empty (e.g., every staged change was already committed), halt with the empty-commit message; do not use `--allow-empty` without engineer confirmation.
+- Nothing to commit — the tree is clean.
+- A staged filename matches the sensitive-pattern list.
+- A pre-commit hook fails. Surface its output and fix the cause; never bypass. A gpg signing failure is the same case — fix the gpg configuration.
+- The push would be forced, or `--amend` would rewrite a commit that is already pushed.
+- `--push` was asked for and the branch has no upstream. Ask which remote and branch.
+- The push is rejected as non-fast-forward. Rebase and retry; never propose `--force`.

package/template/.claude/skills/hstack-data-architecture/SKILL.md

@@ -1,74 +1,52 @@
 ---
 name: hstack-data-architecture
-description: Use to produce or refresh `hstack/context/data-architecture.md` — tenancy model, entity graph, RLS posture, RAG layout, migration sketches. Greenfield Phase 2, the brownfield data-architecture step, or a standalone section refresh.
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "{{TODO-MCP: Supabase MCP — live schema introspection in extract mode}}"
-  - "node hstack/scripts/validate-spec.mjs — frontmatter validator"
+description: "Use when the data layer really moves — tenancy, entities, RLS posture, RAG layout — to write or refresh `hstack/context/data-architecture.md`. Ordinary schema changes are covered by the kernel's same-PR rule."
 ---
 
 ## Purpose
 
-`hstack-data-architecture` is the atom that produces or refreshes `hstack/context/data-architecture.md` via the `data-architect` subagent. The artifact is the foundational design of the data layer in five sections; downstream subagents (`data-specialist` for per-change reviews, `implementer` for migration writing) read it as canonical posture.
+`/hstack-data-architecture` writes or refreshes `hstack/context/data-architecture.md`, the living
+doc that holds the data layer's posture in five sections: tenancy, entities, RLS, RAG, migrations.
+It is what the next session reads before touching the database.
 
-## When to invoke
-
-- Phase 2 of `/hstack:greenfield-init` (elicit mode).
-- Delegated by `/hstack:brownfield-init` mini-session 5a (extract mode).
-- Standalone via `/hstack:data-architecture [--mode extract|elicit] [--section <name>]` for refresh or single-section edits.
-- Routed-into-from-downstream when `/hstack:app-architecture` finds a state-ownership gap that requires an entity addition (the bidirectional drift recovery path).
+It is not how the doc stays current day to day. A change that adds a column updates the doc in its
+own PR — that rule is the kernel's and costs nothing. This Skill is for the moves that rule cannot
+absorb: the first write, a change of tenant, an entity graph that no longer matches the schema, an
+RLS posture that has drifted.
 
 ## Inputs
 
-- `--mode extract | elicit` — defaults: `extract` if the live schema is reachable via Supabase MCP or migration files exist; `elicit` otherwise.
-- `--section <name>` — one of `tenancy | entities | rls | rag | migrations`. Fast-jumps but re-runs end-of-atom coherence.
-
-## Preconditions
-
-- `hstack/config.yaml` at `init-status: minimal-complete` or later.
-- `hstack/context/product/product-brief.md` at `status: current`. The brief is upstream; entities trace to it. If brief is at `draft` or `needs-refresh`, halt with `HSTACK-HALT: reason=upstream-non-terminal`.
-- `hstack/templates/data-architecture.md` present.
-- In extract mode, the Supabase MCP is reachable OR `supabase/migrations/` exists OR equivalent schema source is reachable; otherwise halt.
-
-## Orchestration steps
+`--section tenancy | entities | rls | rag | migrations`, optional — refreshes one section.
 
-1. **Detect mode + entry.** Read disk state. If artifact at `current` and no `--section` and no `--force`: print summary, exit no-op.
-2. **Invoke `data-architect` subagent.** Via the Task tool with `subagent_type: data-architect`. Pass mode, optional section, the canonical session-start context, and (in extract mode) the live-schema introspection results.
-3. **Walk sections.** The subagent walks Section 1 first (Tenancy is gate). For section-targeted entry, jumps directly. Each confirmed section writes to disk + auto-commits.
-4. **Run drift challenge prompts.** Each section ends with a drift challenge before confirmation. A real drift halts with `HSTACK-HALT: reason=upstream-drift` and offers (a) revise this section, (b) re-enter the upstream atom (`/hstack:product-discovery` or `/hstack:configure vision`), (c) log as ADR via `/hstack:adr-new`.
-5. **End-of-atom coherence check.** Even on section-targeted entry, the subagent re-runs all five drift challenges before terminal commit. Any unanswered challenge blocks the commit.
+## Steps
 
-## Outputs
+1. **Extract or elicit.** Extract when a schema exists: the Supabase MCP if it is configured,
+   otherwise `supabase/migrations/`. Elicit when nothing exists yet. **If the MCP is unreachable
+   and the migrations are used instead, say so to the engineer** — the fallback is announced, never
+   silent (kernel § Stop conditions). If neither is reachable, stop.
+2. **Invoke `data-architect`** with the material gathered. It reads the schema, drafts each section
+   and challenges it. The questions and the confirmations happen here, in this session — a subagent
+   cannot interview.
+3. **Walk the sections in order.** Tenancy first: nothing downstream stabilizes until the tenant is
+   one concrete noun with a rule for who is inside one. Then entities, RLS, RAG, migrations.
+4. **Each section ends with its drift challenge** and the answer stays in the doc as evidence the
+   probe ran. A challenge that surfaces a real contradiction stops the section: the engineer
+   revises it, files an ADR, or writes a tech-debt file — none of which this Skill decides.
+5. **A section-targeted refresh re-reads the other four challenges** before the PR. Changing an
+   entity and leaving the RLS section describing the old one is the failure this catches.
 
-- `hstack/context/data-architecture.md` at `status: current` with `assumes-database: postgres` in frontmatter (or alternative with rationale). Section 5 holds migration *sketches* only — no `.sql` file is written from this Skill; the implementer writes them during bootstrap or per-change.
-- `hstack/.session-state/<session-id>.yaml` (transient).
+## Output
 
-## Auto-commit triggers
-
-- Each confirmed section writes immediately and auto-commits.
-- Artifact reaches `status: current` → final commit with the coherence-check evidence in the body.
-
-## Idempotency contract
-
-- Artifact at `current` + no `--section` + no `--force`: print summary, exit no-op.
-- Artifact at `draft` or partial: read disk + session-state, resume at next non-confirmed section.
-- Artifact at `needs-refresh`: walk all sections in confirm-or-revise mode.
+`hstack/context/data-architecture.md`, updated in the PR that changes it. Section 5 holds migration
+*sketches* — no `.sql` file is written here.
 
 ## Stop conditions
 
-- Product-brief at non-terminal status.
-- Section 1's tenant is not yet one concrete noun with a rule for who is inside it, after one re-ask.
-- A drift challenge surfaces an unresolved contradiction.
-- Extract mode invoked but no schema source reachable.
-- The `assumes-database: postgres` value contradicts an in-flight stack decision.
-
-## Failure modes
+Beyond the kernel's:
 
-- **Subagent unreachable.** Persist session state; retry later.
-- **Supabase MCP unreachable in extract mode.** If migrations or other schema source exist, the subagent falls back to those. Otherwise halt with `HSTACK-HALT: reason=mcp-unreachable` per the kernel's load-bearing-MCP rule.
+- No schema source is reachable in extract mode: the Supabase MCP is down *and* there are no
+  migrations. Halt rather than describe a schema from memory.
+- The tenant is still not one concrete noun after one re-ask.
+- A drift challenge surfaces a contradiction the engineer has not resolved.
+- The database in the doc's `assumes-database` is not the one the repo is using. Surface it; a
+  silent switch invalidates every RLS predicate in the doc.

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

@@ -0,0 +1,55 @@
+---
+name: hstack-promote
+description: Use after a PR merges, to release it — pending production migrations, a smoke test on the unpromoted production build, then promotion. The concrete commands live in infrastructure.md § Deploy Pipeline.
+---
+
+## Purpose
+
+`/hstack-promote` is the only deploy step hstack carries. The **sequence** lives here; the **commands** live in `hstack/context/infrastructure.md` § Deploy Pipeline. That split is deliberate: the sequence is the same whoever hosts the product, and a provider hardcoded here would be wrong for the next one.
+
+## When to invoke
+
+After a PR merges. Short trains — promote every two or three days rather than letting merges pile up, and let a change on a sensitive surface travel alone.
+
+One promoter at a time. Say you are promoting before you start, because two overlapping promotions cannot be untangled afterwards.
+
+A hotfix takes the same PR and the same fast lane. It skips the preview and the train, never the checks.
+
+## Preconditions
+
+- The PR is merged and the fast lane is green on what is about to ship.
+- `hstack/context/infrastructure.md` has a § Deploy Pipeline naming the six commands this sequence needs: apply a pending migration to production, list deployments and their state, smoke-test a specific deployment URL, read production logs, promote a deployment, roll back to the previous one.
+
+**If that section is missing, or does not name them, halt.** Guessing a production command from a provider's documentation is how the wrong project gets migrated.
+
+## Steps
+
+1. **Confirm the preconditions.** Merged; fast lane green.
+
+2. **List the pending production migrations** and show them to the human. Ask: *migrations OK?* Apply them only on an explicit yes, then verify they applied.
+
+3. **Wait for the production build** of the merge commit to reach a ready state.
+
+4. **Smoke-test the unpromoted build** at its own URL — the deployment that carries the new code against the new schema, before any user can reach it. Check its health and its error logs, then hand the URL to the human, who tests the behaviour. This step is the entire reason the pipeline is staged.
+
+5. **Check the exposure map.** If this release changes what a user can reach, the Module Map column in `app-architecture.md` is updated before the promotion, not after.
+
+6. **Ask: staging OK, do we promote?** Promote on an explicit yes. Nothing else is an authorization.
+
+7. **Watch production for five minutes** — error logs, then the error tracker. A release nobody looked at is not a release that worked.
+
+8. **If it screams, roll back** by re-promoting the previous deployment. The migrations stay: they are additive by default, so the previous code runs against the new schema. Contraction ships in a later PR (kernel § Security checklist).
+
+## Output
+
+One production deployment promoted, or one rolled back — and, when the exposure map moved, the commit that moved it.
+
+## Stop conditions
+
+Beyond the kernel's:
+
+- The fast lane is not green on what is about to be promoted.
+- `infrastructure.md` has no § Deploy Pipeline, or it does not name the six commands.
+- Someone else is already mid-promotion.
+
+The kernel forbids a write-capable MCP against production outside this skill. This sequence is where that exception is spent — on the migration in step 2, with the human's yes. Enable it for that step; disable it afterwards.

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

@@ -0,0 +1,58 @@
+---
+name: hstack-story
+description: "Use to draft or refine the user story of a Notion feature — five sections, the user's point of view, written into the feature via the Notion MCP. A product tool, never a gate on a change."
+---
+
+## Purpose
+
+`/hstack-story` writes one user story: who it is for, what shipping looks like to them, how we
+know it worked. It exists so the people building the product stay on the user's side of the
+screen — it is not part of any change's path to merge. **No rule requires a change to reference a
+story.** The PR description names the Notion feature it serves, and that is the whole link.
+
+Features live in Notion, in the Epics and Features databases. The story is written into its
+feature page through the Notion MCP; the repo keeps nothing.
+
+## When to invoke
+
+When a feature needs its story written, or when the story it has no longer describes what is being
+built. Nothing invokes this Skill and nothing waits on it.
+
+## Inputs
+
+`--feature <notion-id | url>` and `--persona <slug>`, both optional — the interview asks when they
+are missing.
+
+## Steps
+
+Read `hstack/templates/story.md` first: the five sections are the shape, and filling them is the
+job. Personas at `hstack/context/personas/` are frozen documents — read them for the user's voice,
+and if none fits, say so and anchor the story on the user the interview describes. A missing
+persona never blocks a story.
+
+1. **Who and Why.** The persona and the job to be done, in one or two sentences.
+2. **What Shipping Looks Like.** What the user sees, does and feels. A paragraph, not a spec.
+3. **Success Metric.** One measurable thing. If the answer is not measurable, ask once more with a
+   candidate; record what the engineer settles on rather than inventing a number.
+4. **Edge Cases the User Cares About.** The challenge that earns this section: *what does the user
+   notice if this ships but is slightly broken?* Two bullets minimum, from the user's side.
+5. **Out of Scope for This Story.** The adjacent thing this story is not.
+
+Then write the story into the Notion feature page via the MCP, with `id: NOTION:<id>` naming it.
+Refining an existing story reads it first and proposes the current values as the starting point.
+
+## Output
+
+The story, in its Notion feature. No file in the repo, no status, no link written back onto
+anything.
+
+## Stop conditions
+
+Beyond the kernel's:
+
+- The Notion MCP is unreachable. Say so and stop — no local file stands in for it
+  (kernel § Stop conditions).
+- The named feature page does not exist. Ask which one, or whether to create it; never write the
+  story onto a different page.
+- The story is being asked for as a precondition to writing code. It is not one — say so, and
+  offer to write it afterwards if it is still wanted.

package/template/.claude/skills/hstack-test-audit/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: hstack-test-audit
+description: "Use on demand for one module whose tests look thin: map its business rules against the existing tests, name the gaps, write the missing tests, record the invariants found. Never a per-change phase."
+---
+
+## Purpose
+
+`/hstack-test-audit <module>` audits one module's coverage of its **business rules** — the places
+where the code decides something that would be wrong in silence — and closes the gaps the engineer
+chooses to close. It produces tests and an `invariants.md` update. No artifact, no status, no
+report file.
+
+## When to invoke
+
+When a module's tests look thin (kernel § Workflow trigger table), or before a module starts
+carrying real users' money, data or identity. On demand only: the kernel's per-change rule is one
+question at plan time, and this Skill is never a phase of a change.
+
+## Inputs
+
+`<module>` — a module from the Module Map in `app-architecture.md`, or a path.
+
+## Steps
+
+1. **Map the rules.** Read the module's code, `hstack/context/invariants.md`, the Module Map, and
+   `data-architecture.md` when the module touches the database. Write each rule as *decides X;
+   wrong in silence if Y*. A module whose code decides nothing has no gap to close — say so and
+   stop rather than write tests for the sake of coverage.
+2. **Map the existing tests onto the rules.** Existing test files are read-only here
+   (kernel § Test immutability); this step reads them, it never edits them.
+3. **Name the gaps** — rules with no test, and tests asserting something no rule needs.
+4. **Interview the edges.** A handful of questions, not a script: *what does the user notice if
+   this breaks in silence?* — plus concurrency, retries, and the cross-tenant case when the module
+   touches tenant-scoped data. The answers sharpen the gap list.
+5. **Propose extractions.** A rule buried in a component is a rule nobody can test. Propose
+   pulling it into a pure function; the engineer decides, and an accepted extraction ships in the
+   same PR as the test that justifies it.
+6. **The engineer picks the gaps to close now.** A module with twenty uncovered rules would make
+   an unreviewable PR. Close the chosen ones; name the rest in the PR description so the next
+   audit starts there.
+7. **Write the tests.** New test files need no authorization — "new" means the path did not exist
+   at session start. If closing a gap requires editing or deleting an existing test, halt and ask;
+   nothing in this Skill authorizes that.
+8. **Record the invariants.** Every rule the audit surfaced goes into `hstack/context/invariants.md`
+   in this PR — **including the gaps left open**. The memory is the cheap half; write it whether or
+   not the test was written.
+
+The heavy reading in steps 1–3 goes to the `test-strategist` subagent, which returns the rule map
+and the gap list. Steps 4 and 6 are questions for the engineer and happen here, in this session.
+
+## Output
+
+New test files, an `invariants.md` diff, and a summary for the PR description naming the gaps left
+open. Nothing else.
+
+## Stop conditions
+
+Beyond the kernel's:
+
+- Closing a gap would require touching an existing test. Halt (§ Test immutability).
+- The module cannot be located, or spans so much of the repo that "one module" is not what is
+  being audited. Ask which one.
+- An invariant the audit surfaces contradicts one already in `invariants.md`. Surface both; the
+  engineer decides which is true.

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

@@ -0,0 +1,48 @@
+---
+name: hstack-wrap
+description: Use at the end of a change, before the PR — runs /review and /security-review on the branch diff, audits test immutability, updates the living docs the diff invalidated, and writes the PR description.
+---
+
+## Purpose
+
+`/hstack-wrap` closes a change. It is loaded fresh at the moment it runs, which is the point: the end-of-change rules do not have to survive two hundred turns of conversation in order to be applied. It is a checklist fired by an event, not a phase — nothing here is produced unless a change is actually ending.
+
+## When to invoke
+
+When the code and its tests are done and the next step is a pull request. Once per change; re-running it after a fix is normal and cheap.
+
+Not on a change that is still moving, and never to merge — `/hstack-wrap` opens the PR and stops there.
+
+## Inputs
+
+None. The diff under review is everything that will land in the PR — committed, staged and unstaged — against the merge-base with the default branch.
+
+## Steps
+
+1. **Read `hstack/context/review-miss.md`** when it exists. A category a review has already missed once gets re-checked explicitly in the pass below; that is the whole reason the file exists.
+
+2. **Run `/review`, then `/security-review`** on that diff. Fix what is fixable inside the announced perimeter. Everything else is declared in the PR description — the finding, and why it was not fixed. A finding is never dropped silently, and an empty result is reported as what it is: the reviewer found nothing.
+
+3. **Audit test immutability.** Diff the test files that already existed at the merge-base. An edit or a deletion without the canonical authorization echoed in this conversation is a blocking finding — halt, and do not open the PR (kernel § Test immutability).
+
+4. **Ask each living doc whether this diff invalidated it**, and update it in this PR when it did (kernel § Context docs). When an entry point changed status — live, routable, off — the exposure column of the Module Map in `app-architecture.md` moves with it.
+
+5. **Name the conscious shortcuts.** A shortcut that survives the merge becomes a file under `hstack/tech-debt/`, from the template, written in this PR and named in its description.
+
+6. **Sensitive surface?** If the diff touches one (kernel § Review), the PR says so in its first line and asks for the deep pass in a fresh session — `/hstack-adversarial-review`.
+
+7. **Write the PR description** from `references/pr-description.md`: intention, perimeter, decisions, shortcuts and tech-debt, the review findings split into what was fixed and what was declared, and the Notion feature it serves when there is one. When the consumer has a `.github/pull_request_template.md`, that rendered file is the one you fill — the reference file is the seed it was copied from, not a second authority.
+
+8. **Commit, then push and open the PR.** Commit in the `hstack-commit` format. Run the repo's fast lane locally first — a red PR costs a full round trip; if the repo names no fast-lane command, say so in the PR rather than inventing one. Push and `gh pr create` only after explicit confirmation in the conversation.
+
+## Output
+
+One open PR against the default branch, carrying the code, the living-doc updates, any tech-debt file, and a description that says what the reviews found.
+
+## Stop conditions
+
+Beyond the kernel's:
+
+- A pre-existing test was modified or deleted without authorization.
+- A hook or a check was bypassed to get here.
+- A living doc is invalidated and you cannot update it. Say "stale" in the PR description; never invent the content.

package/template/.claude/skills/hstack-wrap/references/pr-description.md

@@ -0,0 +1,45 @@
+<!-- The PR description hstack expects, filled by /hstack-wrap.
+     This file is the seed: it is copied once to .github/pull_request_template.md,
+     which is what GitHub renders and what /hstack-wrap fills from then on.
+     Delete a section only when it is honestly empty. -->
+
+<!-- SENSITIVE SURFACE — first line of the description, or deleted entirely.
+     Agent or tool boundaries, auth, RLS, schema and migrations, pgvector,
+     payments and credits. When one is touched, say so here and ask for the
+     deep pass in a fresh session (/hstack-adversarial-review). -->
+
+## Intention
+
+<!-- What this change is for, in a sentence or two. The Notion feature it serves, with its URL, when there is one. -->
+
+## Perimeter
+
+<!-- What was announced, and what was actually touched. If they differ, say why. -->
+
+## Decisions
+
+<!-- What a reader would otherwise have to reverse-engineer from the diff: a trade-off taken,
+     an approach rejected, a name chosen on purpose. A one-way door is an ADR, drafted in this
+     PR — link it here. -->
+
+## Living docs
+
+<!-- Which living docs this diff invalidated, and how they were updated here. "None invalidated"
+     is a real answer. A doc that is stale and could not be updated is named as stale — never
+     silently left, never invented. -->
+
+## Shortcuts & tech-debt
+
+<!-- Conscious shortcuts that survive the merge, each with its hstack/tech-debt/TD-NNNN-<slug>.md
+     file. "None" is a real answer when it is true. -->
+
+## Review findings
+
+<!-- /review and /security-review, in full. These are LLM judgments, not evidence: an empty list
+     means the reviewer found nothing, not that there is nothing. CI is the only mechanical check. -->
+
+**Fixed here:**
+
+**Declared, not fixed:**
+
+<!-- Each with the reason it was not fixed. -->