hstack 0.7.1 → 0.17.0

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

@@ -1,133 +0,0 @@
----
-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

@@ -1,129 +0,0 @@
----
-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`, `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. **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 twelve-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` (Category A) UNLESS `enables` non-empty (Category B). The audit-chain assumption: a Category-B spec's user value lives in one of the change-specs named in `enables`; this gate does not transitively verify that downstream spec has `user-stories` non-empty — that's the downstream's GT-08 check, run at its own ship time.
-   - 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`.
-   - GT-12 (SP-13 mutual exclusion): `internal-tooling: true` AND `enables` non-empty is forbidden. Hard FAIL. Reciprocity (SP-14): for every id in `enables`, the named downstream spec must exist on disk and must list this change-id in its `enabled-by` array. Missing downstream specs are a FAIL (forward references are only legal at authoring time — by ship time, the downstream must be scaffolded so reciprocity holds). The reverse direction (`enabled-by` entries that point at non-existent or non-listing upstream specs) is also FAIL.
-
-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 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`.
-
-## 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 twelve 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-stack-decide/SKILL.md

@@ -1,108 +0,0 @@
----
-name: hstack-stack-decide
-description: |
-  Use this skill when the engineer wants to decide stack choices and capture each as an ADR. The Skill is Phase 4 of `/hstack:greenfield-init`, the stack-decision step of `/hstack:brownfield-init` when stack ADRs are missing, or a standalone atom for mid-project layer swaps (replacing auth, switching the database, rotating the hosting provider). It invokes the `stack-architect` subagent for the technical-discovery interview, then routes each layer's decision through `/hstack:adr-new` (which invokes `spec-author`) with pre-populated Context / Decision / Alternatives. The Consequences challenge prompt fires fresh on every ADR regardless of pre-population. Examples:
-
-  <example>
-  Context: Phase 4 of greenfield-init opens after app-architecture is current. hstack/config.yaml's default-stack declaration is set.
-  user: "/hstack:stack-decide"
-  assistant: "Loading brief, data-architecture, app-architecture, default-stack declaration. Defaults cover framework / database / hosting / auth — I'll fast-path those to a single rollup ADR. Observability is undeclared in config; I'll deep-dive on that layer. Expected: 2 ADRs (rollup + observability) routed through spec-author."
-  <commentary>
-  Default-stack fast-path collapses 80% of the interview when defaults match. Only layers explicitly flagged for deep-dive or undeclared in config get the full constraint interview.
-  </commentary>
-  </example>
-
-  <example>
-  Context: Mid-project, the team decides to replace Supabase Auth with Clerk.
-  user: "/hstack:stack-decide --layer auth"
-  assistant: "Standalone mode. Loading the existing auth ADR, threat-model, hardening-checklist. Constraint interview first (engineering capacity, scale horizon, compliance posture), then surfacing 2–3 Clerk alternatives, then routing to spec-author for the new ADR with supersedes: [<predecessor>]. The predecessor's reciprocal superseded-by writes atomically with the new ADR."
-  <commentary>
-  Standalone mode runs against a single layer. The supersedes / superseded-by reciprocal pair is mandatory; spec-author handles both halves atomically per the kernel's reciprocal-pair atomicity rule.
-  </commentary>
-  </example>
-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}}"
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — 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.
-- 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.
-
-## Anti-patterns
-
-- Never write to `hstack/adr/` from this Skill directly. ADR authoring is `spec-author`'s exclusive ownership per kernel rule.
-- Never let pre-population skip the Consequences challenge prompt. Pre-population covers Context / Decision / Alternatives; Consequences fires fresh.
-- Never propose stack options before constraints are concrete.
-- Never bypass the upstream check (app-architecture must be `current` in greenfield/brownfield mode).
-- Never silently honor a non-Postgres DB choice when `data-architecture.md`'s `assumes-database: postgres` says otherwise. Halt and surface.
-- Never split the supersedes / superseded-by reciprocal pair across two commits in standalone mode.

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

@@ -1,119 +0,0 @@
----
-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 is Category A (`internal-tooling: true`) or Category B (`enables` non-empty), since both carve-outs satisfy SP-09 without a story. 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` UNLESS `enables` non-empty). 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 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`, `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` (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.
-
-## 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.

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

@@ -1,122 +0,0 @@
----
-name: hstack-tech-debt-new
-description: |
-  Use this skill when the engineer needs to capture a tech-debt item — a known compromise the team agreed to live with for now. The Skill orchestrates the `spec-author` subagent through a six-section interview for the TD body (genuine open-ended authoring); the reciprocal `creates-tech-debt` write on the originating change-spec is performed by the Skill directly per ADR-0001 (no second spec-author invocation). Both halves of the reciprocal pair (TD-01) land in a single atomic commit; spec-author defers its terminal-state auto-commit when invoked under this Skill so the Skill can include both files in one commit. Examples:
-
-  <example>
-  Context: The billing-overage change shipped with a one-off Tailwind class for warning-yellow because the design token isn't yet exposed; the engineer wants to log it.
-  user: "/hstack:tech-debt-new --origin 2026-05-billing-overage-warning overage-banner-tailwind-class"
-  assistant: "I'll invoke spec-author for the tech-debt interview. The six sections cover Title, Why we took the shortcut, What it costs us, Fix sketch, Pre-conditions for fixing, Acceptance. Reciprocally, I'll add this tech-debt id to the change-spec's creates-tech-debt array."
-  <commentary>
-  Reciprocity per TD-01 is load-bearing. Without the back-reference, audit queries cannot answer "who put this here?" without grepping every change-spec. Per ADR-0001, the TD body is authored by spec-author (interview) and the reciprocal `creates-tech-debt` write on the change-spec is performed by the Skill directly; both files land in one atomic commit.
-  </commentary>
-  </example>
-
-  <example>
-  Context: The adversarial-reviewer surfaced a deliberate trade-off that should be tracked as tech-debt rather than fixed in the change.
-  user: "F-03 routes to tech-debt. /hstack:tech-debt-new --origin 2026-06-knowledge-citations cookie-samesite-attributes"
-  assistant: "I'll invoke spec-author. The reciprocal write lands on the change-spec; the adversarial-review's finding gets resolution: tech-debt:<this-td-id> once the artifact is created."
-  <commentary>
-  This is the routing the adversarial-review's resolution discipline assumes. The tech-debt is created here, then referenced from the adversarial-review's `findings[].resolution`. The Skill is the only path because spec-author owns reciprocal writes.
-  </commentary>
-  </example>
-tools:
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Bash
-  - Task
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — 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 `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` 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.
-
-## 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.
-
-## Anti-patterns
-
-- Never invent a tech-debt id. Sequential per the implicit rule.
-- Never write a tech-debt item without the Why-we-took-the-shortcut section. Debt without context is paperwork.
-- Never write `origin: <change-spec-id>` without the reciprocal `creates-tech-debt` write on that change-spec.
-- Never advance status past `open` from this Skill. Status transitions happen on the fix side, not the capture side.
-- Never overwrite an existing tech-debt item from this Skill. Updates happen via direct `spec-author` invocation when the item is being actively worked on.