hstack 0.4.0 → 0.5.0

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-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.

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

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

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

@@ -0,0 +1,108 @@
+---
+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.md

@@ -1,5 +1,5 @@
 ---
-hstack-version: v0.1.0
+hstack-version: v0.5.0
 authority: kernel
 ---
 
@@ -139,12 +139,13 @@ Naming rules: `id` is kebab-case and immutable once written; dates are ISO 8601;
 
 **Change-spec carries an optional `revisits-change` array.** When a new change-spec is filed to fix a defect, regression, or missed adversarial-review finding from a prior shipped change, the engineer populates `revisits-change: [<predecessor-change-id>]` so post-merge defect correlation is computable (`/hstack:telemetry` § QO-6 when promoted from watch-list to dashboard). Default empty. The field is informational, not gating — no Skill refuses to advance because the array is empty or non-empty.
 
-**Change-spec carries `internal-tooling` (Category A) and `enables` (Category B) as the two no-story carve-outs.** A change-spec with no driving user story must declare one of two categories before status advances past `draft` (SP-09):
+**Change-spec carries `internal-tooling` (Category A), `enables` (Category B), and `area: bootstrap` (Category C) as the three no-story carve-outs.** A change-spec with no driving user story must declare one of three categories before status advances past `draft` (SP-09):
 
 - **Category A — `internal-tooling: true`.** Engineering-only code that never ships on a user path: CI tooling, dev scripts, repo automation, internal dashboards. No `enables` linkage exists because no downstream user-facing change is teed up.
 - **Category B — `enables: [<downstream-change-spec-id>, ...]`.** Production code that ships, but user value is realized by a named downstream change-spec that consumes this one's output. Typical case: schema or plumbing landed ahead of the UI that surfaces it. The reciprocal field `enabled-by: []` on the downstream spec is written atomically with `enables`.
+- **Category C — `area: bootstrap`.** The one-time greenfield scaffold change-spec. The code ships on user paths, but the explicit `enables` list would be degenerate (every future change-spec would be a target) and `internal-tooling: true` would be dishonest. The `area: bootstrap` value satisfies SP-09 as the third carve-out. Bootstrap is produced by `/hstack:scaffold` (Phase 6 of `/hstack:greenfield-init`) and runs at most once per project lifetime; the canonical template is `hstack/templates/bootstrap.md`.
 
-The two flags are mutually exclusive (SP-13): a change is Category A *or* Category B, never both. If neither applies, `user-stories` must be non-empty. The audit query *"what's the user value of this change?"* follows the `enables` chain until it hits a spec with `user-stories` non-empty (the user-value realization point) or a dead end. Forward references are permitted at authoring time — if `enables` names a not-yet-scaffolded id, `/hstack:change-new` reconciles the reciprocal `enabled-by` when the downstream spec is later scaffolded. Reciprocity (`change-spec.enables ↔ change-spec.enabled-by`) is enforced by SP-14 and lands in a single atomic commit, matching the kernel's other reciprocal-pair rules.
+The three flags are mutually exclusive (SP-13): a change is Category A, Category B, or Category C — never two. If none applies, `user-stories` must be non-empty. The audit query *"what's the user value of this change?"* follows the `enables` chain (Category B) until it hits a spec with `user-stories` non-empty, terminates at Category A with "none, it's internal", or terminates at Category C with "it bootstraps the project; all subsequent changes inherit from it." Forward references are permitted at authoring time — if `enables` names a not-yet-scaffolded id, `/hstack:change-new` reconciles the reciprocal `enabled-by` when the downstream spec is later scaffolded. Reciprocity (`change-spec.enables ↔ change-spec.enabled-by`) is enforced by SP-14 and lands in a single atomic commit, matching the kernel's other reciprocal-pair rules.
 
 ---
 
@@ -198,6 +199,8 @@ Subagents are expensive. Each fresh subagent invocation pays the cost of its sys
 
 The kernel rule reading: *"spec-author is the only **subagent** permitted to write under `hstack/specs/`, `hstack/adr/`, and `hstack/tech-debt/`."* The Skill orchestrator running in the main Claude Code session is not a subagent. Skills are therefore permitted to perform mechanical frontmatter writes directly, without invoking a subagent. ADR-0001 documents the decision.
 
+**Narrow carve-out for `app-architect`.** The `app-architect` subagent may scaffold `hstack/specs/<module>/spec.md` **stubs** (headers only, `status: draft`, body note pointing to `/hstack:module-spec`) at the terminal state of its own atom, as pre-allocation for downstream `spec-author` work. The carve-out is scoped narrowly: stubs are not authored content (no body prose, no filled sections), they land in one atomic commit alongside `app-architecture.md` advancing to `current`, and the engineer's first invocation of `/hstack:module-spec <module>` reverse-engineers the stub into authored content via the normal `spec-author` interview. Any other subagent attempting to write under `hstack/specs/` is rejected per the original rule.
+
 **What counts as a mechanical operation.** Operations where no open-ended interview is required — values are determined by the Skill's preconditions, the engineer's invocation arguments, or a structured-elicitation loop with a fixed question set and bounded answer shape:
 
 - **Status flips** — advancing an artifact's `status` field along the lifecycle. The engineer's invocation of the Skill (and any acknowledgement gate the Skill carries) is the confirmation.
@@ -216,6 +219,9 @@ The kernel rule reading: *"spec-author is the only **subagent** permitted to wri
 - `/hstack:tech-debt-wontfix` — TD `open → wontfix`; `wontfix-reason` and `wontfix-accepted-alternative` writes; Resolution Log append.
 - `/hstack:tech-debt-stale` — TD `open → stale-no-longer-reproducible`; `stale-verified-at` and `stale-verification-method` writes; Resolution Log append.
 - `/hstack:tech-debt-new` — reciprocal `creates-tech-debt` write on the originating change-spec after `spec-author` finishes the TD authoring interview.
+- `/hstack:app-architecture` — at terminal state, three-file atomic commit: `app-architecture.md` advances to `status: current`; one `hstack/specs/<module>/spec.md` stub per module from Section 1 (under the `app-architect` carve-out above); `hstack/config.yaml`'s `surfaces` enum updated to match Section 5. All three writes land in one git commit; the proposed-diff preview runs before commit per the standard mechanical-operations contract.
+- `/hstack:stack-decide` — optional `hstack/config.yaml` default-stack update after per-layer ADRs land, when the engineer wants a layer's choice to become the project-wide default. Mechanical write, proposed-diff preview, single commit.
+- `/hstack:scaffold` — generates the bootstrap change-spec's `in-scope` enumeration (from app-architecture Module Map + data-architecture Migration Sketches + standard infra files) and pre-populates `related-adrs` from Phase 4 ADRs. The change-spec lands at `status: draft`; `spec-author` walks the engineer through confirm-or-revise to reach `ready-to-plan`. After that, the standard per-change workflow Skills run unchanged.
 
 **Discipline preserved.** Skills doing direct writes still honor:
 
@@ -297,11 +303,13 @@ Subagents and Skills in v1 must not falsely assert v2 guarantees. The `security-
 
 The product context layer lives at `hstack/context/`:
 
+- `product/product-brief.md` — the durable thinking artifact capturing the project's product reasoning. Produced by `product-discovery` via one of three techniques (Brainstorm, Forcing-Questions, Project-Brief). Upstream of `vision.md`, `mvp-scope.md`, `personas/`, `glossary.md` — those are refreshed from the brief by `product-manager` via auto-route.
 - `vision.md` — what the product is, what it does, what it is not.
 - `glossary.md` — terms with non-obvious meaning.
 - `mvp-scope.md` — in MVP, in v2, deferred.
 - `personas/` — one file per persona, or one row per persona in the configured store.
-- `data-architecture.md` — data model, schema, RAG architecture, embedding strategy.
+- `data-architecture.md` — five-section foundational design (Tenancy, Entities, RLS, RAG, Migration Sketches). Produced by `data-architect`. Carries `assumes-database: postgres` in frontmatter (or alternative with explicit rationale).
+- `app-architecture.md` — five-section internal-architecture design (Module Map, Agent Orchestration, Deterministic-vs-LLM Split, State-Ownership, Surface Boundaries). Produced by `app-architect`. Stack-agnostic by design; does not name frameworks.
 - `tech-stack.md` — canonical languages, frameworks, libraries.
 - `ci-cd.md` — CI/CD setup of the consuming repo.
 - `infrastructure.md` — operational truth: hosting, networking, secrets, environments, deploy pipeline, observability, cost, disaster recovery, blast-radius matrix, access control, compliance posture, third-party dependencies. Truth-gathering, not policy — `threat-model.md` and `hardening-checklist.md` carry the policy and score against this file.
@@ -311,7 +319,11 @@ The product context layer lives at `hstack/context/`:
 
 Load-at-session-start rules by subagent:
 
-- `product-manager`: vision, personas, mvp-scope, glossary.
+- `product-discovery`: kernel, the chosen technique script (`hstack/templates/discovery/<technique>.md`), `product-brief.md` if it exists (resume mode), and in extract mode any source documents the engineer points at.
+- `product-manager`: vision, personas, mvp-scope, glossary. In auto-route from `product-discovery`: also the brief.
+- `data-architect`: kernel, product-brief, vision, mvp-scope, personas, glossary, data-architecture if it exists. In extract mode: live schema via Supabase MCP and `supabase/migrations/`.
+- `app-architect`: kernel, product-brief, data-architecture, vision, mvp-scope, personas, glossary, app-architecture if it exists. Explicitly NOT `tech-stack.md` — app-architecture is stack-agnostic by design. In extract mode: consuming-repo source tree.
+- `stack-architect`: kernel, product-brief, data-architecture, app-architecture, `hstack/config.yaml`'s default-stack declaration, all existing ADRs, threat-model and hardening-checklist if they exist. In standalone mode (`--layer <name>`): additionally `infrastructure.md`.
 - `spec-author`: glossary, tech-stack, the relevant module-spec.
 - `test-strategist`: change-spec, module-spec, tech-stack, ci-cd, data-architecture (when surfaces includes db), existing test files within in-scope.
 - `planner`: change-spec, test-plan, ui-brief, figma-handoff, data-review (when present).
@@ -362,7 +374,9 @@ When a Skill or subagent halts at any of the stop conditions above, it emits one
 HSTACK-HALT: reason=<enum>
 ```
 
-Where `<enum>` is one of: `scope-amendment | upstream-non-terminal | mcp-unreachable | forbidden-tool | test-immutability-protocol | missing-context | ambiguous-spec | environment-misconfig | branch-mismatch | other`.
+Where `<enum>` is one of: `scope-amendment | upstream-non-terminal | mcp-unreachable | forbidden-tool | test-immutability-protocol | missing-context | ambiguous-spec | environment-misconfig | branch-mismatch | upstream-drift | other`.
+
+The `upstream-drift` value is emitted by discovery atoms (`product-discovery`, `data-architect`, `app-architect`, `stack-architect`) when a section's drift challenge surfaces a contradiction with an upstream artifact (e.g., a data-architecture entity that has no trace to a persona in the product-brief, or an app-architecture flow whose state-ownership requires an entity the data-architecture doesn't have). Distinct from `upstream-non-terminal` (which means an upstream artifact is still at `draft`) and from `scope-amendment` (which means an in-scope file is missing). Drift is bidirectional: a downstream atom finding an upstream gap reroutes through `/hstack:configure <upstream-atom>`, the upstream refreshes, the downstream resumes.
 
 The sentinel is a single line, costs zero LLM tokens to emit, and makes post-hoc halt-frequency analysis cheap (see `/hstack:telemetry` § WS-6). The sentinel is appended to the auto-commit body when a halt coincides with a status-flip commit; otherwise it appears in the conversation alone (the telemetry parser reads both transcript text and commit bodies). Halting still includes the prose explanation of the situation — the sentinel does not replace the human-readable reason, it complements it.