hstack 0.1.0

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

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

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

@@ -0,0 +1,133 @@
+---
+name: hstack-security-review
+description: |
+  Use this skill when a change-spec is at `status: ready-to-plan` or later and needs `security-review.md` produced before the implementer can start. The Skill orchestrates the `security-reviewer` subagent. In v1 the output is an LLM-scored structured judgment (`scoring-mode: llm-scored`), not an executable test result — the Skill enforces this framing on every output. Examples:
+
+  <example>
+  Context: A change-spec introduces a new public-schema table with RLS and is at ready-to-plan.
+  user: "/hstack:security-review 2026-05-billing-overage-warning"
+  assistant: "I'll invoke security-reviewer. Surfaces is [ui, db], so the threat-model-delta section is mandatory. Scoring biases toward CONCERNS over PASS when evidence is thin; the three challenge prompts run regardless of what surfaces declares."
+  <commentary>
+  The Skill is the only authoring path for security-review.md. It enforces SR-03 (threat-model-delta required when surfaces touches agent/auth/api/db) and SR-02 (three challenge prompts mandatory). v1 framing is enforced on every rationale.
+  </commentary>
+  </example>
+
+  <example>
+  Context: A change touches the agent surface — new orchestrator prompt and a new tool boundary — and the threat-model.md has not been touched in eight weeks.
+  user: "/hstack:security-review 2026-06-playbook-runner-prompt"
+  assistant: "I'll invoke security-reviewer. The threat-model-delta is mandatory because surfaces includes agent; I'll halt if the delta can't be produced from the current threat-model. Findings will frame as structured judgment, not verified by test execution."
+  <commentary>
+  Agent-surface changes are exactly where the v1 honesty clause matters most. The Skill ensures the subagent does not claim test-backed evidence for prompt-injection resistance — that is v2 substrate work.
+  </commentary>
+  </example>
+
+  <example>
+  Context: A change is a small refactor with no declared security-sensitive surface, but the diff touches authentication-adjacent code.
+  user: "/hstack:security-review 2026-05-auth-helper-rename"
+  assistant: "I'll invoke security-reviewer. Even on a refactor, the three challenge prompts run — attack vector not covered by checklist, tenant-isolation citation, malicious-payload behavior — to surface anything the surface declaration may have missed."
+  <commentary>
+  Refactors near auth are exactly the place where the surface declaration may understate the risk. The challenge-prompt machinery is the v1 mitigation for humans missing what's missing.
+  </commentary>
+  </example>
+tools:
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Bash
+  - Task
+  - "{{TODO-SCRIPT: hstack/scripts/score-security-review.ts — computes overall status from the scores map}}"
+  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — 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 verbatim:
+   - "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?"
+   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 `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` 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.
+
+## Anti-patterns
+
+- Never produce a PASS when evidence is thin. Default to CONCERNS and let the human acknowledge.
+- Never skip or paraphrase a challenge prompt. The three are verbatim and mandatory.
+- Never claim test-backed evidence in v1. The honesty clause is load-bearing.
+- Never write `concerns-acknowledged-by` without the owner's explicit acknowledgement.
+- Never silently fall back to `data-architecture.md` when the live-schema MCP is unreachable on a db-surface change — flag the degradation in the rationale and (in v1) continue if the change is low-stakes, halt if high-stakes.
+- Never fabricate line numbers in tenant_isolation citations.
+- Never file tech-debt from this Skill; surface the recommendation for the engineer to invoke `hstack-tech-debt-new`.

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

@@ -0,0 +1,128 @@
+---
+name: hstack-ship
+description: |
+  Use this skill when every artifact for a change is at terminal status and the engineer wants the final merge-readiness scorecard and a generated PR description. The Skill is the merge gate's prelude — it checks that every CI gate's preconditions are met, computes the scorecard, and produces the PR description body. It does not perform the merge; the engineer opens or marks the PR ready-for-review themselves. Examples:
+
+  <example>
+  Context: Every artifact for the billing-overage change is at terminal status and the engineer wants to open the PR.
+  user: "/hstack:ship 2026-05-billing-overage-warning"
+  assistant: "I'll compute the scorecard: spec at ready-to-ship, test-plan passed, plan completed, security-review passed, ui-brief drafted, figma-handoff ready, data-review passed, verification passed, adversarial-review findings-resolved, resolves-tech-debt items at in-progress (GT-11). PR description will land in hstack/specs/changes/<id>/pr-body.md for you to paste; after merge, run /hstack:finalize to flip the TD to resolved."
+  <commentary>
+  The Skill is mechanical — it reads frontmatter and computes the gate result. No subagent is invoked. If any gate fails, the Skill names the failing artifact and halts.
+  </commentary>
+  </example>
+
+  <example>
+  Context: The engineer tries to ship a change whose adversarial-review is still at findings-open.
+  user: "/hstack:ship 2026-06-knowledge-citations"
+  assistant: "I'll halt — adversarial-review is at findings-open. Three findings still at status: open with no resolution. Resolve those via the existing adversarial-review.md before re-running ship."
+  <commentary>
+  The Skill names the exact blocker and the exact remediation path. It does not advance any status itself; ship is read-only across the artifact set.
+  </commentary>
+  </example>
+tools:
+  - Read
+  - Write
+  - Grep
+  - Glob
+  - Bash
+  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — validates every artifact's frontmatter}}"
+  - "{{TODO-SCRIPT: hstack/scripts/compute-merge-readiness.ts — computes the nine-gate scorecard from artifact frontmatter}}"
+---
+
+## Purpose
+
+`hstack-ship` is the final merge-readiness Skill. It reads every artifact's frontmatter for the change, computes the nine-gate scorecard from `hstack-gates.yml`, 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`, `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. **Read every change artifact.** Read `spec.md`, `plan.md`, `test-plan.md`, `security-review.md`, `data-review.md` (when surfaces includes db), `ui-brief.md` and `figma-handoff.md` (when surfaces includes ui), `verification.md`, `adversarial-review.md`. Capture each artifact's `status` and key gating fields.
+
+2. **Compute the eleven-gate scorecard.** Run `{{TODO-SCRIPT: hstack/scripts/compute-merge-readiness.ts}}` against the artifact set, or inline the equivalent logic:
+   - GT-01: spec presence — change folder exists with non-draft change-spec, or PR carries `trivial: true`.
+   - GT-02: diff within scope — every file in the PR diff (against the merge target) is a subset of `change-spec.in-scope`.
+   - GT-03: pattern lints — every `hstack/lints/*.yaml` rule passes (the Skill runs `{{TODO-SCRIPT: hstack/scripts/run-gates.sh}}` for this and reads the exit code).
+   - GT-04: adversarial-review at `findings-resolved`.
+   - GT-05: security-review at `passed` or `concerns-acknowledged`.
+   - GT-06: data-review at `passed` or `concerns-acknowledged` (when applicable).
+   - GT-07: ui-brief at `drafted` and figma-handoff at `ready` (when applicable).
+   - GT-08: `user-stories` non-empty (unless `internal-tooling: true`).
+   - GT-09: every cross-reference rule (CG-01..CG-04) passes.
+   - GT-10: test-plan 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 `change-spec.resolves-tech-debt` is non-empty: (a) every referenced tech-debt must exist and be at `status: in-progress` with `resolution-attempted-at` set; (b) the adversarial-review must contain the AR-07 Acceptance-satisfied confirmation enumerating each TD's Acceptance bullets against the diff; (c) no referenced tech-debt may have a non-null `resolved-by` already (that would indicate a double-resolution attempt). When `resolves-tech-debt` is empty, GT-11 is `not-applicable`.
+
+3. **Frontmatter validation.** Run `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` 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 eleven-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`.
+
+## 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.
+- Re-running after fixing a failing gate: the scorecard reports the new state.
+
+## Stop conditions
+
+Beyond the kernel's general stop conditions:
+
+- A required artifact is missing on disk.
+- Any artifact's frontmatter cannot be parsed.
+- 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.
+
+## 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), the Skill computes scorecards for every child and produces 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. 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).
+
+## Anti-patterns
+
+- Never write status transitions on any artifact from this Skill. Ship is read-only across the artifact set.
+- Never call `gh pr create` or perform the merge. The engineer opens the PR.
+- Never silently pass a gate. Every FAIL names the artifact and field.
+- Never collapse the eleven gates into a single PASS / FAIL. The scorecard is per-gate.
+- Never flip a tech-debt status from this Skill. That is `/hstack:finalize`'s job and only runs post-merge. Ship surfaces the directive; it does not perform the write.
+- Never extend `change-spec.in-scope` to make GT-02 pass — the scope amendment goes through `spec-author`, not this Skill.
+- Never overwrite `pr-body.md` content the engineer has hand-edited without confirmation. If the file exists with edits beyond the template, surface a diff and ask before rewriting.

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

@@ -0,0 +1,117 @@
+---
+name: hstack-story-draft
+description: |
+  Use this skill when a user-facing change needs a story drafted or refined, anchored on an existing persona, with a concrete success metric and the user-visible edge cases enumerated. The Skill orchestrates the `product-manager` subagent and is conditional — it does not run when the parent change-spec has `internal-tooling: true`. Examples:
+
+  <example>
+  Context: The engineer just scaffolded a billing-overage change-spec and needs a linked user story before SP-09 lets the spec advance past draft.
+  user: "Draft a story for the billing overage warning, anchored on the growth-marketer persona."
+  assistant: "I'll invoke product-manager to walk the five story sections with the growth-marketer persona as the anchor. The story id will land in the configured story store; the change-spec's user-stories array updates reciprocally."
+  <commentary>
+  Stories are gated by SP-09 (`user-stories` non-empty unless `internal-tooling: true`). The Skill produces the story before the change-spec can advance, and writes the reciprocal `linked-change-specs` entry on the story.
+  </commentary>
+  </example>
+
+  <example>
+  Context: A story exists but the engineer wants to refine the success metric, which the product-manager flagged as too vague.
+  user: "Refine STORY-2026-05-014 — sharpen the success metric."
+  assistant: "I'll invoke product-manager with the existing story as the proposal layer. The other sections are accept-or-correct; the success-metric field gets the full interview treatment."
+  <commentary>
+  Refinement reuses the same orchestration with the existing story as the proposal context. The Skill does not re-walk every field; the subagent reads the existing content and targets the field the engineer named.
+  </commentary>
+  </example>
+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}}"
+  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — 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 `internal-tooling: true`.
+
+## 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 a "story not required" message.
+- Read `hstack/context/vision.md`, `mvp-scope.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, mvp-scope, 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 `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` 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 `mvp-scope.md`. `product-manager` flags; the Skill asks whether to update mvp-scope (via `hstack-configure --interview mvp-scope`) or defer the story.
+
+## Failure modes
+
+- **Parent change-spec is `internal-tooling: true`.** Halt early; the story is unnecessary.
+- **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.
+
+## Anti-patterns
+
+- Never anchor a story on an invented persona. The persona either exists at `current` or is authored first via a sub-interview.
+- Never bypass the Edge Cases challenge prompt, even on refinement.
+- Never write a story without a concretely measurable success metric.
+- Never silently fall back to a local story file when the configured external store's MCP is unreachable.
+- Never write reciprocal `user-stories` entries to a change-spec at a non-draft status without going through the `spec-author`'s field-change machinery — except for the array-append case explicitly carved out by `product-manager`'s contract.