hstack 0.3.0 → 0.5.0

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

@@ -0,0 +1,100 @@
+---
+name: hstack-data-architecture
+description: |
+  Use this skill when the engineer wants to produce or refresh `hstack/context/data-architecture.md` — the deep five-section foundational data-layer design (Tenancy, Entities, RLS, RAG, Migration Sketches). The Skill is Phase 2 of `/hstack:greenfield-init`, the data-architecture step of `/hstack:brownfield-init`, or a standalone atom for refreshing a single section after drift. It invokes the `data-architect` subagent and routes downstream phases to halt at `HSTACK-HALT: reason=upstream-drift` when contradictions surface. Examples:
+
+  <example>
+  Context: Phase 2 of greenfield-init opens after product-brief is current.
+  user: "/hstack:data-architecture"
+  assistant: "Loading product-brief, vision, mvp-scope, personas. Section 1 — Tenancy — is load-bearing: I'll walk Patterns A/B/C explicitly and refuse to advance until the tenant definition is concrete with a rationale tied to a persona. Subsequent sections (Entities, RLS, RAG, Migration Sketches) build on it."
+  <commentary>
+  Tenancy ambiguity is the #1 multi-tenant SaaS failure mode. The atom enforces concreteness at Section 1 before any downstream section can stabilize.
+  </commentary>
+  </example>
+
+  <example>
+  Context: An app-architect drift challenge revealed a missing entity in data-architecture. The engineer routes back.
+  user: "/hstack:data-architecture --section entities"
+  assistant: "Section-targeted entry. I'll fast-jump to Section 2 Entities for the missing entity, but the end-of-atom coherence check still runs across all five sections before commit — section edits cannot silently break other sections."
+  <commentary>
+  Section-targeted re-entry is precision when needed, but coherence is non-negotiable. The end-of-atom check is the v1 guarantee against drift-from-edit.
+  </commentary>
+  </example>
+tools:
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Bash
+  - Task
+  - "{{TODO-MCP: Supabase MCP — live schema introspection in extract mode}}"
+  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — frontmatter validator}}"
+---
+
+## Purpose
+
+`hstack-data-architecture` is the atom that produces or refreshes `hstack/context/data-architecture.md` via the `data-architect` subagent. The artifact is the foundational design of the data layer in five sections; downstream subagents (`data-specialist` for per-change reviews, `implementer` for migration writing) read it as canonical posture.
+
+## When to invoke
+
+- Phase 2 of `/hstack:greenfield-init` (elicit mode).
+- Delegated by `/hstack:brownfield-init` mini-session 5a (extract mode).
+- Standalone via `/hstack:data-architecture [--mode extract|elicit] [--section <name>]` for refresh or single-section edits.
+- Routed-into-from-downstream when `/hstack:app-architecture` finds a state-ownership gap that requires an entity addition (the bidirectional drift recovery path).
+
+## Inputs
+
+- `--mode extract | elicit` — defaults: `extract` if the live schema is reachable via Supabase MCP or migration files exist; `elicit` otherwise.
+- `--section <name>` — one of `tenancy | entities | rls | rag | migrations`. Fast-jumps but re-runs end-of-atom coherence.
+
+## Preconditions
+
+- `hstack/config.yaml` at `init-status: minimal-complete` or later.
+- `hstack/context/product/product-brief.md` at `status: current`. The brief is upstream; entities trace to it. If brief is at `draft` or `needs-refresh`, halt with `HSTACK-HALT: reason=upstream-non-terminal`.
+- `hstack/templates/data-architecture.md` present.
+- In extract mode, the Supabase MCP is reachable OR `supabase/migrations/` exists OR equivalent schema source is reachable; otherwise halt.
+
+## Orchestration steps
+
+1. **Detect mode + entry.** Read disk state. If artifact at `current` and no `--section` and no `--force`: print summary, exit no-op.
+2. **Invoke `data-architect` subagent.** Via the Task tool with `subagent_type: data-architect`. Pass mode, optional section, the canonical session-start context, and (in extract mode) the live-schema introspection results.
+3. **Walk sections.** The subagent walks Section 1 first (Tenancy is gate). For section-targeted entry, jumps directly. Each confirmed section writes to disk + auto-commits.
+4. **Run drift challenge prompts.** Each section ends with a drift challenge before confirmation. A real drift halts with `HSTACK-HALT: reason=upstream-drift` and offers (a) revise this section, (b) re-enter the upstream atom (`/hstack:product-discovery` or `/hstack:configure vision`), (c) log as ADR via `/hstack:adr-new`.
+5. **End-of-atom coherence check.** Even on section-targeted entry, the subagent re-runs all five drift challenges before terminal commit. Any unanswered challenge blocks the commit.
+
+## Outputs
+
+- `hstack/context/data-architecture.md` at `status: current` with `assumes-database: postgres` in frontmatter (or alternative with rationale).
+- `hstack/.session-state/<session-id>.yaml` (transient).
+
+## Auto-commit triggers
+
+- Each confirmed section writes immediately and auto-commits.
+- Artifact reaches `status: current` → final commit with the coherence-check evidence in the body.
+
+## Idempotency contract
+
+- Artifact at `current` + no `--section` + no `--force`: print summary, exit no-op.
+- Artifact at `draft` or partial: read disk + session-state, resume at next non-confirmed section.
+- Artifact at `needs-refresh`: walk all sections in confirm-or-revise mode.
+
+## Stop conditions
+
+- Product-brief at non-terminal status.
+- Section 1 Tenancy answer is vague after one re-ask.
+- A drift challenge surfaces an unresolved contradiction.
+- Extract mode invoked but no schema source reachable.
+- The `assumes-database: postgres` value contradicts an in-flight stack decision.
+
+## Failure modes
+
+- **Subagent unreachable.** Persist session state; retry later.
+- **Supabase MCP unreachable in extract mode.** If migrations or other schema source exist, the subagent falls back to those. Otherwise halt with `HSTACK-HALT: reason=mcp-unreachable` per the kernel's load-bearing-MCP rule.
+
+## Anti-patterns
+
+- Never write migration `.sql` files from this Skill. Sketches only; the implementer writes the files during bootstrap or per-change.
+- Never bypass the Section 1 Tenancy gate.
+- Never let the end-of-atom coherence check be skipped on section-targeted re-entry.
+- Never silently honor a database change that contradicts `assumes-database`. Halt and surface; route through stack-architect or refresh this artifact deliberately.

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

@@ -0,0 +1,138 @@
+---
+name: hstack-flag
+description: |
+  Use this skill when the engineer notices in-the-moment friction in the hstack workflow — a Skill loop that felt off, a subagent output that read wrong, a halt firing for an unexpected reason, a confirmation diff that revealed an unstated assumption — and wants to surface it for kernel-fit review without halting the current work. The Skill is the engineer-triggered side of the kernel-fit closed loop (ADR-0005). It drops a tiny frontmatter-only pin to `hstack/kernel-fit/flags/pending/` carrying session-id + transcript path + branch + HEAD + timestamp, completes in under a second, and exits. No interview, no confirmation, no commit. The next `/hstack:kernel-fit-scan` reads each pin, opens the referenced transcript, classifies the friction, and either folds the signal into an existing finding or emits a new one. Examples:
+
+  <example>
+  Context: Mid-implementation the engineer notices a Skill produced a confirmation diff that revealed an assumption the kernel does not name.
+  user: "/hstack:flag"
+  assistant: "📌 pinned at hstack/kernel-fit/flags/pending/flag-20260523T143208-a3f9.md — kernel-fit will review on next scan."
+  <commentary>
+  Zero-friction is load-bearing. No interview, no confirmation gate, no diff preview. The Skill captures session-id (from most-recently-modified jsonl under ~/.claude/projects/<encoded-cwd>/), branch, HEAD, timestamp, and writes the pin in under a second. The engineer continues working immediately.
+  </commentary>
+  </example>
+
+  <example>
+  Context: The engineer wants to leave a one-word hint so future-them remembers the rough shape of the friction when they re-read the transcript.
+  user: "/hstack:flag halt-loop"
+  assistant: "📌 pinned with hint 'halt-loop' — kernel-fit will review on next scan."
+  <commentary>
+  The optional positional hint argument is a one-word string. Multi-word hints are rejected (the Skill takes argv[0] and ignores the rest with a one-line note). The hint is for the engineer's future audit, not for the analyst — per ADR-0005, the analyst forms its classification from the transcript window, not from engineer-written hints, to preserve the no-contamination contract.
+  </commentary>
+  </example>
+
+  <example>
+  Context: The engineer flags from a workspace where the encoded-path directory under ~/.claude/projects/ does not exist (e.g., the harness is storing transcripts elsewhere or the workspace is brand-new).
+  user: "/hstack:flag"
+  assistant: "📌 pinned with session-id-source: fallback-cwd (no jsonl found under ~/.claude/projects/<encoded>; session-id may not resolve at scan-time). The analyst will classify as transcript-truncated if the transcript cannot be located. Re-flag in a session whose transcript is reachable if the friction is recurring."
+  <commentary>
+  The session-id capture is heuristic in v1 (per ADR-0005). The Skill does not halt when the heuristic fails — it writes the pin with whatever metadata it can capture and a note in `session-transcript-path` indicating the fallback. The analyst's `transcript-truncated` classification is the safety net. v2 substrate will replace the heuristic with a harness-exposed session-id.
+  </commentary>
+  </example>
+tools:
+  - Bash
+  - Read
+  - Write
+  - Glob
+---
+
+## Purpose
+
+`hstack-flag` is the engineer-triggered feeder into the kernel-fit closed loop (ADR-0005). It captures a *pointer to the moment* — session-id, transcript path, branch, HEAD, timestamp — so the `kernel-fit-analyst` can later read the surrounding transcript window and classify whatever friction prompted the flag. The Skill carries no engineer interpretation of the friction; the analyst forms its classification independently to preserve the no-contamination contract.
+
+This Skill is mechanical per ADR-0001. No subagent is invoked. The values to write are determined entirely by the invocation context (git state, working directory, the active Claude Code session-id, current transcript message count) plus the optional one-word hint. There is no interview, no confirmation gate, no proposed-diff preview, and no commit — the pin is additive, immutable, and out-of-band from the lifecycle state machine.
+
+## When to invoke
+
+Invoke when:
+
+- A Skill loop felt off — looped longer than expected, asked a question that revealed a wrong assumption, produced output that read strangely.
+- A subagent's output read wrong — challenge prompts seemed to dodge real risk, evidence rows looked thin, a finding's category felt mis-categorized.
+- A halt fired for an unexpected reason — the halt enum value did not seem to capture what actually happened, or the halt felt like it should have been routine.
+- A confirmation diff revealed an unstated kernel assumption — the proposed write surfaced something the kernel does not name but probably should.
+- Anything else where the engineer wants the transcript window remembered for later review, but cannot stop the current work to write a tech-debt item or an ADR.
+
+Do NOT invoke for:
+
+- Bugs in individual code changes (those are tech-debt items or revisits-change entries).
+- Security gaps in a specific change (those are security-review concerns).
+- Genuine emergencies — if the situation requires halting, halt and address it directly.
+
+## Inputs
+
+- Optional positional `<hint>` (one word, ≤ 32 characters). Multi-word arguments are truncated to the first whitespace-delimited token with a one-line note. The hint is for the engineer's future audit, not for the analyst.
+
+## Preconditions
+
+- Working directory is a git repository (`git rev-parse --git-dir` succeeds). If not, halt with "not in a git repo — flag only works inside hstack-governed code."
+- The consuming repo has at least the `hstack/kernel-fit/flags/pending/` directory writable (the Skill creates it on demand if absent — no halt).
+- No status check on any other artifact. The Skill is intentionally orthogonal to the lifecycle state machine; flagging is permitted in any branch, at any time, regardless of in-flight artifacts.
+
+## Orchestration steps
+
+1. **Capture git state.** Run in parallel:
+   - `git rev-parse HEAD` → `head`
+   - `git rev-parse --abbrev-ref HEAD` → `branch`
+   - `pwd` → `workspace`
+
+2. **Resolve the session-id.** Heuristic per ADR-0005 (v2 substrate will replace this with a harness-exposed mechanism):
+   - Compute the encoded workspace path: replace `/` with `-` in the absolute cwd path, prefix with `-`. Example: `/Users/jane/code/moso` → `-Users-jane-code-moso`.
+   - Glob `~/.claude/projects/<encoded-cwd>/*.jsonl`.
+   - If at least one match: pick the most recently modified (`stat -f %m` on macOS, `stat -c %Y` on Linux) and extract its `session-id` from the filename (basename minus `.jsonl`). Set `session-transcript-path` to its absolute path.
+   - If zero matches: set `session-id` to `fallback-<short-uuid>` (generate a short random hex), set `session-transcript-path` to the literal string `fallback-cwd:<workspace>` so the analyst can detect the fallback at scan time. Do NOT halt — the pin still has audit value (timestamp + branch + HEAD), and the analyst's `transcript-truncated` classification is the safety net.
+
+3. **Capture pre-compaction message count.** Count lines in `session-transcript-path` if it points at a real jsonl file (`wc -l < <path>`); else set to 0. The analyst compares this to the file's line count at scan-time to detect compaction.
+
+4. **Read and normalize the hint.** If the engineer passed an argument: take the first whitespace-delimited token, truncate to 32 characters, store as `hint`. If multi-word was passed, note in stdout "hint truncated to first token: <hint>". If no argument: `hint: null`.
+
+5. **Compose the pin id.** Format: `flag-<YYYYMMDD>T<HHMMSS>-<session-id-short>` where `<session-id-short>` is the first 4 characters of the session-id (or `fallback-<hex>`). Example: `flag-20260523T143208-a3f9`.
+
+6. **Write the pin.** Ensure `hstack/kernel-fit/flags/pending/` exists (`mkdir -p`); write `<pin-id>.md` with the frontmatter-only content per `template/templates/kernel-fit-flag.md`. The body is intentionally empty (a single HTML comment from the template is acceptable, but no prose).
+
+7. **Confirm to stdout.** Print one line: `📌 pinned at hstack/kernel-fit/flags/pending/<pin-id>.md — kernel-fit will review on next scan.` If the hint was set, mention it. If the session-id fell back, mention it. Exit 0.
+
+## Outputs
+
+- One new file at `hstack/kernel-fit/flags/pending/<pin-id>.md`.
+- No git operations. No commits. No subagent invocations. No edits to any other file.
+
+## Auto-commit triggers
+
+None. Pins are gitignored per ADR-0005 (derivative signal, mirroring `.telemetry/` sidecars from ADR-0004). The flag is not a lifecycle event, so the kernel's auto-commit-at-status-transition rule does not apply.
+
+## Idempotency contract
+
+Each invocation produces a new pin with a unique id (timestamp granularity is one second; session-id-short is appended for collision safety across rapid re-flags). Re-running the Skill on the same friction produces a second pin — this is intentional. The analyst processes both and the duplication itself is signal (engineer felt strongly enough to flag twice). The Skill never overwrites or deduplicates.
+
+## Stop conditions
+
+Beyond the kernel's general stop conditions:
+
+- Not inside a git repo. Halt with the explanation above. The Skill is meaningful only inside hstack-governed code where the analyst can correlate the pin to a finding surface.
+
+The Skill explicitly does NOT halt on:
+
+- Missing jsonl under `~/.claude/projects/<encoded-cwd>/` — falls back to `fallback-cwd` and writes the pin anyway.
+- Branch mismatch with an in-flight change-spec — flagging is orthogonal to lifecycle.
+- A `validate-spec.ts` failure on the pin frontmatter — until the validator ships, FL-01 and FL-02 are advisory only; the pin lands.
+- Disk-write failure on the pin file. (If `mkdir -p` or `Write` errors, halt with the OS error — there is nothing useful the Skill can do.)
+
+No halt sentinel is emitted by this Skill in the success path. The success path is a clean exit-0 with the one-line stdout confirmation.
+
+## Failure modes
+
+- **`~/.claude/projects/<encoded-cwd>/` does not exist or is empty.** Fall back as described in step 2; write the pin with `session-transcript-path: fallback-cwd:<workspace>`. The analyst will classify `transcript-truncated` at scan-time.
+- **Multiple `.jsonl` files in the encoded directory.** Pick the most recently modified. This is the v1 heuristic; v2 will replace it with a harness-exposed session-id.
+- **Engineer flags many times in rapid succession.** Each flag produces a distinct pin (timestamp granularity + session-id-short suffix prevents collisions). The high flag-rate itself becomes signal in the next scan's Slack tail summary.
+- **Engineer flags from inside a subagent's session.** The encoded-cwd heuristic resolves to the main-session jsonl (subagents do not get their own jsonl under `~/.claude/projects/`), which is correct — the analyst wants the main session's transcript. No special handling required.
+- **Engineer passes a quoted multi-word hint.** Truncate to the first token, note it in stdout, write the pin. Do not halt.
+
+## Anti-patterns
+
+- Never prompt the engineer for a description of the friction. The Skill is one-shot and silent. Asking for prose re-opens the contamination surface the analyst guards against and defeats the zero-friction goal.
+- Never invoke a subagent. The pin's value is determined by invocation context; no subagent decision-making is needed.
+- Never commit the pin. Pins are gitignored. Committing them would (a) defeat the cadence (every flag becomes a commit), (b) pollute git history with derivative-cache files, and (c) break the gitignore decision recorded in ADR-0005's Decision and Consequences.
+- Never edit an existing pin to add context. Pins are immutable from the engineer's perspective; the only legal post-creation writes are by the analyst at processing time. To add context, re-flag in a follow-up turn.
+- Never invoke a confirmation gate. The proposed-diff preview rule from the kernel's Mechanical operations section does not apply here because the pin is additive (not a state-machine write) and there is no risk to mitigate: the pin is immutable, gitignored, and out-of-band from every lifecycle gate.
+- Never block the conversation on slow operations. The Skill's wall-clock budget is <1s. If `wc -l` against a multi-gigabyte jsonl is too slow, accept an approximate count (the field is for change-detection at scan-time, not exact accounting) — but `wc -l` on jsonl files in practice completes in tens of milliseconds and this concern is theoretical.
+- Never escalate a flag into a tech-debt item, ADR, or research session automatically. Promotion is exclusively the analyst's call at scan-time, gated by the engineer via `/hstack:kernel-fit-triage` and `/hstack:kernel-fit-promote`. The Skill is a feeder, not a router.

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

@@ -0,0 +1,150 @@
+---
+name: hstack-greenfield-init
+description: |
+  Use this skill when an engineer is starting a **new project from an empty repository** and wants hstack discipline baked in from line zero. Greenfield-init is the sibling of `/hstack:brownfield-init`: where brownfield extracts existing context, greenfield elicits it. The Skill composes the discovery atoms in order (product-discovery → data-architecture → app-architecture → stack-decide → threat-model/hardening → scaffold), with hard gates between phases and bidirectional drift recovery for downstream phases that surface upstream gaps. Total elapsed time is 4–8 hours of conversation spread across as many sessions as the engineer wants — every phase ends at a commit point and is interruptible. Until greenfield-init completes through Phase 6 (scaffold), no per-change workflow Skill works; the repo is bootable only after scaffold lands. Examples:
+
+  <example>
+  Context: A founder runs `npx hstack@latest greenfield-init` against an empty repository.
+  user: "/hstack:greenfield-init"
+  assistant: "I'll walk you through 6 phases. Phase 1 (product discovery) opens first — pick a technique: Brainstorm, Forcing-Questions, or Project-Brief. Each phase ends at a commit point; you can park and resume any time. Total elapsed time is founder-paced, typically 4–8 hours of conversation across multiple sessions."
+  <commentary>
+  Greenfield is deliberately slower than brownfield because every layer is being created from elicitation rather than extracted from existing source. The Skill is structured as 6 hard-gated phases; each phase delegates to a standalone atom or subagent.
+  </commentary>
+  </example>
+
+  <example>
+  Context: Greenfield-init was started yesterday; Phases 1–3 are committed; the engineer wants to resume.
+  user: "/hstack:greenfield-init"
+  assistant: "I see Phases 1–3 at `status: current` on disk. Resuming at Phase 4 — stack-decide. Loading product-brief, data-architecture, app-architecture, and the default-stack declaration from hstack/config.yaml."
+  <commentary>
+  Idempotency is the same contract as brownfield-init: read disk state, recognize completed phases, resume at the first incomplete one. No re-interview of committed phases.
+  </commentary>
+  </example>
+tools:
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Bash
+  - Task
+  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — frontmatter validator}}"
+---
+
+## Purpose
+
+`hstack-greenfield-init` is the **empty-repo entry point** for adopting hstack. It composes six phases of work — five discovery atoms plus one scaffold execution — into a single orchestrator. It writes `hstack/config.yaml` and populates the full context layer, then bootstraps the repository from empty to bootable via a generated bootstrap change-spec.
+
+Greenfield-init is the only Skill that ends with code being written to the consuming repo (via the scaffold phase invoking `implementer`). Brownfield-init never writes source code — it only writes `hstack/` content against existing source.
+
+## When to invoke
+
+Invoke when:
+
+- The consuming repo has no source code (or only an `hstack/` install and standard hidden files like `.git/`, `.gitignore`).
+- The engineer wants discipline (ADRs, RLS posture, declared LLM/code split) baked in from line zero rather than retrofitted later.
+
+Do NOT invoke when:
+
+- The repo has existing source code — use `/hstack:brownfield-init` instead.
+- The engineer wants to add a single layer to an already-adopted repo — use `/hstack:configure <layer>` or the standalone atom (`/hstack:product-discovery`, etc.).
+
+## Inputs
+
+- No positional arguments. The Skill drives entirely from on-disk state and conversation.
+- Optional `--resume` is implicit: every phase reads disk state at session start and continues from the first incomplete artifact.
+
+## Preconditions
+
+Before any work:
+
+- Verify the repo is empty (no `src/`, no `app/`, no `package.json`). If non-empty, halt and direct the engineer to `/hstack:brownfield-init`. `--force` is not offered; mixing modes corrupts the artifact taxonomy.
+- Verify `hstack/` exists with `CLAUDE.md`, `templates/`, `.claude/`. If missing, halt and ask the engineer to run `npx hstack@latest init`.
+- Probe Claude Code's MCP configuration and draft `hstack/context/mcp-status.md`.
+- If `hstack/.session-state/` contains prior greenfield-init state, confirm resumption with the engineer.
+
+## Orchestration steps
+
+Six phases, hard-gated. The Skill does not advance past a phase until its artifact is at `status: current`.
+
+### Phase 0 — Config skeleton
+
+Same interview as brownfield-init Mini-session 0: story store, personas store, design system (per-resource), module-to-area mapping (will be populated from app-architecture in Phase 3), adversarial-review floor, agent ledger, active MCP set. Writes `hstack/config.yaml` with `schemaVersion: 1` and `init-status: minimal-complete`. Default-stack declaration is **set to the engineer's preferences** in this phase, so Phase 4 can fast-path. Commit.
+
+### Phase 1 — Product discovery
+
+Invokes `/hstack:product-discovery` in elicit mode (no source documents). The atom:
+
+- Prompts the engineer to pick a technique (Brainstorm / Forcing-Questions / Project-Brief).
+- Runs the technique to completion, producing `hstack/context/product/product-brief.md` at `status: current`.
+- Auto-routes to `product-manager` to refresh `vision.md`, `mvp-scope.md`, `personas/`, `glossary.md` from the brief.
+
+Greenfield-init proceeds to Phase 2 only when the brief AND all four refreshed context docs are at `status: current`.
+
+### Phase 2 — Data architecture
+
+Invokes `/hstack:data-architecture` in elicit mode. The atom walks the five sections (Tenancy, Entities, RLS, RAG, Migrations). Produces `hstack/context/data-architecture.md` at `status: current`. The `assumes-database: postgres` frontmatter is set explicitly so Phase 4 can flag drift if the stack changes the DB choice.
+
+### Phase 3 — App architecture
+
+Invokes `/hstack:app-architecture` in elicit mode. The atom walks the five sections (Module Map, Agent Orchestration, Deterministic-vs-LLM Split, State-Ownership, Surface Boundaries). Produces `hstack/context/app-architecture.md` at `status: current` AND scaffolds `hstack/specs/<module>/spec.md` stubs at `status: draft` for each module from Section 1. Updates `hstack/config.yaml`'s `surfaces` enum to match Section 5.
+
+### Phase 4 — Stack decisions
+
+Invokes `/hstack:stack-decide`. The `stack-architect` reads `hstack/config.yaml`'s default-stack declaration (set in Phase 0) and fast-paths through layers the engineer accepted defaults for. Layers requiring explicit deep-dive get the constraint interview; each layer's choice routes through `spec-author` for ADR authoring. Produces one rollup ADR plus per-layer ADRs for deep-dived layers.
+
+### Phase 5 — Threat model + hardening
+
+Invokes `security-reviewer` in `--mode foundational` (scores against proposed posture, not diff). Walks `threat-model.md` and `hardening-checklist.md` using the now-current product-brief, data-architecture, app-architecture, and stack ADRs as anchors. Also produces `infrastructure.md` (via `spec-author`) and `incident-runbook.md` (via `spec-author`, `git-ignored: true`) per the brownfield-init pattern.
+
+### Phase 6 — Scaffold
+
+Invokes `/hstack:scaffold`. The scaffold Skill generates a bootstrap change-spec from `hstack/templates/bootstrap.md` with `area: bootstrap`, `surfaces: [infra]`, and `in-scope` enumerated from the app-architecture Module Map plus the data-architecture Migration Sketches. Runs `data-review` and `security-review` in `--mode foundational` against the proposed posture, then planner → implementer (phase-by-phase) → verifier. At terminal state the repo is bootable: the build command exits 0, the test command exits 0, the initial migrations have landed with RLS enforced from line zero.
+
+After Phase 6, `hstack/config.yaml`'s `init-status` advances to `complete` and the per-change workflow Skills become available.
+
+## Outputs
+
+- `hstack/config.yaml` at `init-status: complete`.
+- `hstack/context/product/product-brief.md` at `current` (Phase 1).
+- `hstack/context/vision.md`, `mvp-scope.md`, `personas/*`, `glossary.md` at `current` (Phase 1 auto-route).
+- `hstack/context/data-architecture.md` at `current` (Phase 2).
+- `hstack/context/app-architecture.md` at `current` plus module-spec stubs (Phase 3).
+- `hstack/adr/ADR-*` files — rollup + per-layer (Phase 4).
+- `hstack/context/threat-model.md`, `hardening-checklist.md`, `infrastructure.md`, `incident-runbook.md` (Phase 5).
+- The bootstrap change-spec at `shipped` plus the actual source files, migrations, CI config, and module shells in the consuming repo (Phase 6).
+
+## Auto-commit triggers
+
+- `hstack/config.yaml` reaches `init-status: minimal-complete` (end of Phase 0).
+- Each phase's terminal artifact reaches `status: current` (end of Phases 1–5).
+- Each phase of the bootstrap change-spec's plan completes (Phase 6 per-phase commits).
+- The bootstrap change-spec reaches `shipped` (end of Phase 6).
+- `hstack/config.yaml`'s `init-status` advances to `complete` (after Phase 6 ships).
+
+## Idempotency contract
+
+Re-running `hstack-greenfield-init` reads disk state, recognizes completed phases (artifacts at `current`), and resumes at the first incomplete phase. No re-interview of committed phases. If a downstream phase had triggered an upstream drift recovery, the upstream artifact will be at `needs-refresh` rather than `current`; the Skill resumes at the upstream's refresh interview.
+
+## Stop conditions
+
+Beyond the kernel's general stop conditions, this Skill halts when:
+
+- The repo is not empty at session start.
+- A phase's atom halts (e.g., `HSTACK-HALT: reason=upstream-drift`). The Skill surfaces the halt and offers the engineer the recovery paths the atom named.
+- A configured MCP that a downstream phase requires (Supabase MCP for Phase 2 extract-mode references, Notion MCP for persona storage) is unreachable and the phase is load-bearing on it.
+- The engineer signals end-of-session — persist state, exit cleanly.
+
+## Failure modes
+
+- **Phase 6 implementer halts.** Bootstrap is partially scaffolded; the change-spec is at `ready-for-implementation` with some phases of `plan.md` complete. Re-running greenfield-init resumes from the first incomplete plan phase via the standard `/hstack:implement` idempotency.
+- **Bidirectional drift recovery during Phases 2–4.** A downstream phase finds an upstream gap; the Skill routes the engineer through `/hstack:configure <upstream-atom>` and resumes after the upstream artifact returns to `current`.
+- **Stack-architect contradicts data-architecture's Postgres assumption.** Phase 4 halts and surfaces; the engineer either revises data-architecture or revises the stack choice.
+
+## Anti-patterns
+
+- Never invoke greenfield-init against a non-empty repo. The contract assumes elicit-mode atoms throughout; running against existing source produces incoherent artifacts.
+- Never collapse the six phases into one long block. The phase structure is the resumability contract AND the gate-discipline contract.
+- Never skip Phase 5 (threat-model + hardening) to get to Phase 6 faster. Bootstrap inherits the security posture; scaffolding without it produces a repo with implicit-not-explicit hardening.
+- Never bypass the bidirectional drift recovery. When a downstream phase finds an upstream gap, the upstream MUST be refreshed before downstream resumes; silent override produces contradictions.
+- Never advance `init-status: complete` while any phase artifact is below `current` or while the bootstrap change-spec is below `shipped`.

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

@@ -78,13 +78,17 @@ The Skill is opt-in. There is no cron, no automatic invocation, no event-driven
 
 2. **Run detection.** Shell out: `python3 hstack/scripts/telemetry/run_kernel_fit.py --repo <repo-root> --window <N>`. Capture stdout as JSON; capture stderr as the diagnostic log. On non-zero exit, surface the traceback and halt with `HSTACK-HALT: reason=missing-context`.
 
-3. **Decide whether to invoke the subagent.** Parse the JSON. If every pattern has `fired: false`, exit clean: print "kernel-fit-scan: no patterns fired in window — kernel is consistent with shipped practice in current corpus" to stdout, write nothing, do not invoke the subagent, do not nudge Slack, do not commit. This is the most common outcome on a healthy repo.
+3. **Enumerate pending engineer flags.** Glob `hstack/kernel-fit/flags/pending/*.md`. Capture the list (may be empty). The analyst processes these per ADR-0005's Pending Flags Processing loop documented in `template/.claude/agents/kernel-fit-analyst.md`; this Skill is responsible for surfacing the list to the analyst and for the post-analyst pin-file moves at step 5.
 
-4. **Invoke `kernel-fit-analyst`.** When at least one pattern fired, invoke via Task tool with `subagent_type: kernel-fit-analyst`. The prompt includes (a) the JSON evidence blob verbatim, (b) the canonical reminder of session-isolation (no implementer transcripts loaded), (c) the explicit instruction "one file per fired pattern; mandatory two-bullet counter-explanation; never write outside `hstack/kernel-fit/findings/`". The subagent's writes land in the working tree before the subagent returns.
+4. **Decide whether to invoke the subagent.** Parse the detector JSON. If every pattern has `fired: false` **and** no pending flags exist, exit clean: print "kernel-fit-scan: no patterns fired in window, no pending flags — kernel is consistent with shipped practice in current corpus" to stdout, write nothing, do not invoke the subagent, do not nudge Slack, do not commit. If patterns fired OR pending flags exist (or both), proceed to step 5.
 
-5. **Stage and commit findings.** Compute the set of newly-written or modified finding files (analyst may have superseded a prior finding atomically with a new one). Print the proposed diff for engineer confirmation (per the kernel's "AI writes, humans confirm" mechanical-operations adaptation). On Y/n confirmation `Y` (default Yes), `git add` the finding files and commit with message `kernel-fit: <N> finding(s) detected` (or `kernel-fit: <N> finding(s) detected, <M> superseded` when supersession edits also landed). One commit per scan run, atomic across all new/edited findings.
+5. **Invoke `kernel-fit-analyst`.** Invoke via Task tool with `subagent_type: kernel-fit-analyst`. The prompt includes (a) the JSON evidence blob verbatim, (b) the list of pending flag paths from step 3 (or "no pending flags" when empty), (c) the canonical reminder of session-isolation (no implementer transcripts loaded), (d) the explicit instruction "one file per fired pattern; mandatory two-bullet counter-explanation; never write outside `hstack/kernel-fit/findings/`; process pending flags per the Pending Flags Processing section of the analyst prompt". The subagent's writes land in the working tree before the subagent returns. The analyst's response object reports the flag-processing counts (`processed`, `folded`, `emitted`, `not_actionable`, `transcript_truncated`).
 
-6. **Notification — Slack nudge (best-effort).** Compute the notification set:
+6. **Move processed pin files.** For each pin the analyst updated to `status: processed`, `git mv hstack/kernel-fit/flags/pending/<pin>.md hstack/kernel-fit/flags/processed/<pin>.md`. Create the `processed/` directory if missing. This move lands in the same commit as the finding writes at step 7 — the analyst's pin frontmatter updates (classification, classification-rationale, folded-into, emitted-as, status) plus the file move must be atomic from git's perspective. **Note**: pin files are gitignored per ADR-0005, so `git mv` operates only on the filesystem (git will not stage either side). The "atomicity" here is filesystem-only — the analyst's in-place frontmatter update and the directory move complete together before stdout reports flag-processing counts. If the gitignore is later relaxed (would require an ADR amendment), this step's `git mv` becomes a real staged operation.
+
+7. **Stage and commit findings.** Compute the set of newly-written or modified finding files (analyst may have superseded a prior finding atomically with a new one, or appended evidence rows to existing findings via fold). Print the proposed diff for engineer confirmation (per the kernel's "AI writes, humans confirm" mechanical-operations adaptation). On Y/n confirmation `Y` (default Yes), `git add` the finding files and commit with message `kernel-fit: <N> finding(s) detected` (or `kernel-fit: <N> finding(s) detected, <M> superseded` when supersession edits landed; or `kernel-fit: <N> finding(s) detected (<F> from flags), <M> superseded` when flag-emit landed). One commit per scan run, atomic across all new/edited findings. When patterns did not fire and only pending flags were processed, the commit message reads `kernel-fit: <F> flag(s) processed (<E> emit, <FF> fold, <NA> not-actionable, <TT> transcript-truncated)`.
+
+8. **Notification — Slack nudge (best-effort).** Compute the notification set:
 
    ```
    notify = [f for f in newly_written_findings
@@ -97,8 +101,8 @@ The Skill is opt-in. There is no cron, no automatic invocation, no event-driven
    ```
    hstack kernel-fit: <N> new finding(s)
 
-   • KF-NNNN — <title>  [confidence: high|medium]
-     Pattern: <KF-P1|KF-P2|KF-P3>
+   • KF-NNNN — <title>  [confidence: high|medium] [via: detector|flag]
+     Pattern: <KF-P1|KF-P2|KF-P3|KF-FLAG-NNNN>
      Kernel surface: <one-line>
      hstack/kernel-fit/findings/KF-NNNN-<slug>.md
 
@@ -107,29 +111,39 @@ The Skill is opt-in. There is no cron, no automatic invocation, no event-driven
    Promote:  /hstack:kernel-fit-promote KF-NNNN --slug <adr-slug>
    ```
 
-   Bundle multiple findings into a single message when more than one fires in this scan.
+   Bundle multiple findings into a single message when more than one fires in this scan. When flag-processing occurred, append the **flag tail summary** as the last line of the same Slack message:
+
+   ```
+   Flags processed: <P> total — <FF> folded, <E> emitted, <NA> not-actionable, <TT> transcript-truncated.
+   ```
+
+   The tail is included only when at least one pin was processed AND at least one of `folded` or `emitted` is non-zero, OR when `transcript_truncated > 0` (the transcript-truncated count is operationally interesting because it surfaces v1-heuristic edge cases the engineer should know about). When every processed pin was classified `not-actionable` the tail is suppressed — it would otherwise be pure noise. When the scan produces zero detector findings AND only `not-actionable` pin processing, the Slack message is suppressed entirely (no findings, no tail-worthy signal).
 
-7. **Graceful degradation when Slack is unreachable.** If the MCP call raises (tool not configured, network failure, channel-not-found, etc.), log to stderr: `kernel-fit: Slack MCP unreachable; <N> finding(s) written to disk without notification. Triage via /hstack:help to discover open findings.` Exit 0. The disk write from step 5 is the load-bearing action; Slack is a side-channel pointer. This is a deliberate carve-out from the kernel's general MCP-unreachable stop condition — Slack is not load-bearing for kernel-fit (the canonical state lives on disk and is reachable via `/hstack:help`). The carve-out is documented here and in the kernel's `## How hstack improves itself` section.
+9. **Graceful degradation when Slack is unreachable.** If the MCP call raises (tool not configured, network failure, channel-not-found, etc.), log to stderr: `kernel-fit: Slack MCP unreachable; <N> finding(s) written to disk without notification. <P> flag(s) processed; triage via /hstack:help to discover open findings.` Exit 0. The disk write from step 7 is the load-bearing action; Slack is a side-channel pointer. This is a deliberate carve-out from the kernel's general MCP-unreachable stop condition — Slack is not load-bearing for kernel-fit (the canonical state lives on disk and is reachable via `/hstack:help`). The carve-out is documented here and in the kernel's `## How hstack improves itself` section.
 
-8. **Report.** Print to stdout: the count of patterns fired, the count of new findings written, the count of supersessions, the count of Slack notifications fired (or "skipped — Slack unreachable" / "skipped — within dedup window for all findings"). Done.
+10. **Report.** Print to stdout: the count of patterns fired, the count of new findings written, the count of supersessions, the count of flags processed broken down by classification (`folded`, `emitted`, `not-actionable`, `transcript-truncated`), and the count of Slack notifications fired (or "skipped — Slack unreachable" / "skipped — within dedup window for all findings" / "skipped — no signal worth surfacing"). Done.
 
 ## Outputs
 
 - Zero or more files at `hstack/kernel-fit/findings/KF-NNNN-<slug>.md` at `status: open`.
 - Zero or more supersession edits (status flip + `superseded-by` set) on prior finding files.
-- Zero or one git commits.
-- Zero or one Slack messages (bundled when multiple findings notify).
+- Zero or more evidence-row appends to existing findings (from flag fold).
+- Zero or more pin transitions from `hstack/kernel-fit/flags/pending/` to `hstack/kernel-fit/flags/processed/` with `status: processed` and the analyst-owned classification fields populated. Pins are gitignored per ADR-0005, so the moves are filesystem-only — not staged in git.
+- Zero or one git commits (covering finding writes only; pin moves are not staged).
+- Zero or one Slack messages (bundled when multiple findings notify, with the flag tail summary appended when applicable).
 
 ## Auto-commit triggers
 
-- One commit at the writing of finding files (per the kernel's auto-commit-at-status-transition rule applied at the artifact-creation moment). No commit when no patterns fire.
+- One commit at the writing of finding files (per the kernel's auto-commit-at-status-transition rule applied at the artifact-creation moment). No commit when no patterns fire AND no flag-emit or flag-fold landed (i.e., only `not-actionable` / `transcript-truncated` flag processing occurred). Pin file moves are filesystem-only (pins are gitignored) and do not require a commit.
 
 ## Idempotency contract
 
-- Re-running the Skill when no patterns fire: zero new disk artifacts, no commit, no Slack message. Pure no-op.
+- Re-running the Skill when no patterns fire AND no pending flags exist: zero new disk artifacts, no commit, no Slack message. Pure no-op.
+- Re-running when no patterns fire but pending flags exist: the analyst is invoked to process flags only. Outcomes depend on classification — fold/emit may produce finding writes and a commit; not-actionable/transcript-truncated produce only pin moves (no commit).
 - Re-running when patterns fire that already have open findings within the dedup window: the analyst is invoked, sees existing findings, and may skip-write or supersede; Slack notification is suppressed by the dedup gate.
 - Re-running when the same patterns fire with new evidence: the analyst may produce supersession edits; the dedup gate still suppresses Slack (already-notified within the window).
-- Re-running with `--no-slack`: identical to a run with Slack unreachable — findings land on disk, no Slack message.
+- Re-running with `--no-slack`: identical to a run with Slack unreachable — findings land on disk, flags are processed normally, no Slack message.
+- Re-running after pending flags were processed in a prior scan: the prior pins are now in `processed/` and the analyst is forbidden from re-processing them (per the kernel-fit-analyst's discipline rules). Only newly-flagged pins (added to `pending/` since the last scan) are processed this run.
 
 ## Stop conditions
 
@@ -178,3 +192,6 @@ What you do NOT need to do: no code to write, no hook to install. The Skill is p
 - Never write outside `hstack/kernel-fit/findings/` or modify any artifact not produced by the analyst this run. This Skill orchestrates; it does not author.
 - Never claim the analyst's output is measured truth. Frame every finding as LLM-strategized judgment per the kernel's v1 / v2 split rule.
 - Never bundle a Slack notification across scan runs. One scan, one message (or zero, when the dedup gate suppresses or Slack is unreachable).
+- Never re-process a pin already in `hstack/kernel-fit/flags/processed/`. The analyst's discipline rule (no re-processing) is mirrored here: the Skill globs only `pending/`, never `processed/`. If the engineer believes a processed pin was mis-classified, the path is to re-flag (creating a fresh pin), not to move the prior pin back.
+- Never include the flag tail summary in the Slack message when every pin was classified `not-actionable`. The tail's purpose is to surface actionable signal — the all-not-actionable case is pure noise and the suppression is deliberate.
+- Never commit a pin move. Pins are gitignored per ADR-0005; the `git mv` from `pending/` to `processed/` is filesystem-only and produces no staged change.

package/template/.claude/skills/hstack-product-discovery/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: hstack-product-discovery
+description: |
+  Use this skill when the engineer wants to produce or refresh `hstack/context/product/product-brief.md` — the durable thinking artifact that captures the project's product reasoning. The Skill is Phase 1 of `/hstack:greenfield-init` (elicit mode), an optional enrichment phase of `/hstack:brownfield-init` when source docs are thin (extract mode), or a standalone atom for retroactive brief authoring. It invokes the `product-discovery` subagent in one of three engineer-chosen techniques (Brainstorm, Forcing-Questions, Project-Brief), produces a single synthesis at `hstack/context/product/product-brief.md`, and auto-routes to `product-manager` for downstream context-doc refresh. Examples:
+
+  <example>
+  Context: Phase 1 of greenfield-init opens. The engineer types `/hstack:product-discovery` directly.
+  user: "/hstack:product-discovery"
+  assistant: "Pick a technique: [1] Brainstorm — facilitated ideation; [2] Forcing-Questions — reframe-driven probing (Gstack-style); [3] Project-Brief — structured walk. Default mode is elicit (no source docs). The brief lives at hstack/context/product/product-brief.md and is parkable any time."
+  <commentary>
+  The technique choice is the engineer's, not the agent's. Each technique's script is in hstack/templates/discovery/<technique>.md. Mid-technique switching is allowed but halts to confirm — mixing technique outputs produces an incoherent brief.
+  </commentary>
+  </example>
+
+  <example>
+  Context: A brownfield repo's brief never landed during init; /hstack:help flagged the missing artifact.
+  user: "/hstack:product-discovery --mode extract"
+  assistant: "Extract mode. I'll read existing vision.md, README, and any product docs you point me at, propose the brief sections from what I find, and walk you through confirm-or-revise. The three required forcing prompts still run — extract mode does not bypass blind-spot probes."
+  <commentary>
+  Extract+confirm mode is how brownfield enrichment works. The unification of modes is load-bearing: the brief produced is the same artifact whether elicited or extracted, so downstream phases load it identically.
+  </commentary>
+  </example>
+tools:
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Bash
+  - Task
+  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — frontmatter validator}}"
+---
+
+## Purpose
+
+`hstack-product-discovery` is the atom that produces `hstack/context/product/product-brief.md` via the `product-discovery` subagent. It is the canonical authoring path for the brief; the brief never lands via a generic spec-author interview.
+
+## When to invoke
+
+- Phase 1 of `/hstack:greenfield-init` (elicit mode, no source).
+- Optional enrichment within `/hstack:brownfield-init` when existing product docs are thin and the engineer wants the deeper reframe-style brief.
+- Standalone via `/hstack:product-discovery [--mode extract|elicit] [--section <name>]` for retroactive brief authoring on any repo.
+
+## Inputs
+
+- `--mode extract | elicit` — defaults: `elicit` if no source docs are reachable; `extract` if a `product-brief.md` exists or the engineer points at source documents.
+- `--section <name>` — optional, fast-jumps to a specific section for refresh. Re-runs the end-of-atom check across all sections before commit.
+
+## Preconditions
+
+- `hstack/config.yaml` exists and `init-status` is at least `minimal-complete` — the atom does not run standalone until config exists.
+- `hstack/CLAUDE.md` and `hstack/templates/product-brief.md` are present.
+- `hstack/templates/discovery/{brainstorm,forcing-questions,project-brief}.md` are present.
+- In extract mode, at least one source document must be reachable; otherwise halt and ask the engineer to either supply source pointers or fall back to elicit mode.
+
+## Orchestration steps
+
+1. **Detect mode.** Read disk state. If `hstack/context/product/product-brief.md` exists at `status: current` and no `--section` flag, this is a refresh confirmation — print summary and exit unless engineer opts into full re-interview.
+2. **Pick technique** (elicit mode only). Prompt the engineer to choose Brainstorm / Forcing-Questions / Project-Brief. Persist the choice as `technique-used` in the brief frontmatter.
+3. **Invoke `product-discovery` subagent.** Via the Task tool with `subagent_type: product-discovery`. Pass mode, technique, optional section, and the canonical session-start context (kernel, template, technique script, source docs in extract mode).
+4. **Walk sections.** The subagent runs the chosen technique's script and walks the brief sections with confirmation gates. Each confirmed section writes to disk and auto-commits.
+5. **Run forcing prompts.** The three required reframes (Who pays? What's the wedge? What would falsify this?) fire before terminal state regardless of technique.
+6. **Auto-route at terminal state.** When the brief reaches `status: current`, the Skill prints the auto-route message (with alternative-path commands) and hands off to `product-manager` via the Task tool with `subagent_type: product-manager` to refresh `vision.md`, `mvp-scope.md`, `personas/`, `glossary.md`. If the engineer types `skip-routing`, the Skill commits the brief and exits cleanly — downstream Skills will halt on missing context docs.
+
+## Outputs
+
+- `hstack/context/product/product-brief.md` at `status: current`.
+- `hstack/.session-state/<session-id>.yaml` (transient).
+- Via auto-route: `vision.md`, `mvp-scope.md`, `personas/*`, `glossary.md` refreshed (unless skip-routing).
+
+## Auto-commit triggers
+
+- Each confirmed section writes immediately and auto-commits.
+- Brief reaches `status: current` → final commit with the auto-route message in the body.
+- Downstream refreshes by `product-manager` each auto-commit per the product-manager subagent's contract.
+
+## Idempotency contract
+
+- Brief at `current` + no `--section` + no `--force`: print summary, exit no-op.
+- Brief at `draft` or partial: read disk + session-state, resume at next non-confirmed section.
+- Brief at `needs-refresh` (flipped by `/hstack:configure` because upstream changed): walk all sections in confirm-or-revise mode.
+
+## Stop conditions
+
+- A required source document in extract mode is unreachable.
+- Forcing-prompt answer is too vague after one re-ask. The subagent halts with `HSTACK-HALT: reason=ambiguous-spec` or `missing-context`.
+- Mid-technique switch requested.
+- Engineer signals end-of-session.
+- Downstream auto-route fails (e.g., `product-manager` cannot reach the configured personas store). The Skill surfaces the failure; the brief stays at `current`, downstream context docs stay at their prior status until the engineer resolves.
+
+## Failure modes
+
+- **Subagent unreachable.** Persist session state; retry later.
+- **Auto-route partial failure.** If `product-manager` succeeds on vision but fails on personas (e.g., Notion MCP unreachable), the partial state is on disk; re-running auto-route via `/hstack:configure personas --from-brief` recovers.
+
+## Anti-patterns
+
+- Never write to `vision.md`, `mvp-scope.md`, `personas/`, `glossary.md` from this Skill directly. Those refreshes belong to `product-manager` via the auto-route.
+- Never bypass the three required forcing prompts, even in Project-Brief mode (the lightest touch).
+- Never silently switch techniques mid-session.
+- Never advance the brief to `current` while the Explicitly NOT section has fewer than two bullets.