hstack 0.3.0 → 0.5.0

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.
 
@@ -405,7 +419,9 @@ hstack ships a closed-loop system for detecting when the kernel itself — this
 
 - **The analyst never writes ADRs, change-specs, or edits existing findings** (one carve-out: it may set `status: superseded` on a prior finding when restating it more cleanly). Promotion is engineer-initiated and routes through the established authoring Skills. Auto-creation of ADRs is forbidden — the kernel's "AI writes, humans confirm" contract applies most forcefully at the kernel-modification layer, where the cost of a bad ADR cascades through every subsequent change.
 
-The loop is the smallest expression of the kernel reasoning about itself without auto-modifying itself. v1 honesty: the analyst's output is an LLM-strategized judgment, not measured truth; the counter-explanation challenge is the false-positive mitigation. Same framing rule as `test-strategist` and `security-reviewer`. See ADR-0004 for the rationale; see `template/templates/kernel-fit-finding.md` for the artifact schema.
+- **Engineer-triggered flags feed the loop with in-the-moment friction signal.** `/hstack:flag [hint]` is a one-shot Skill that drops a tiny frontmatter-only pin to `hstack/kernel-fit/flags/pending/` carrying session-id, transcript path, branch, HEAD, and timestamp. No interview, no confirmation, no commit, sub-second wall-clock. The next `/hstack:kernel-fit-scan` reads each pin, opens the referenced Claude Code session transcript, classifies the friction (`friction | missing-guardrail | kernel-vs-practice-mismatch | not-actionable | transcript-truncated`), then folds the signal into an existing finding or emits a new one with `detected-via: flag`. The pin carries no engineer interpretation of the friction — the analyst forms its classification from the transcript window, preserving the no-contamination contract. Pins are gitignored in the consuming repo (derivative signal, mirroring `.telemetry/` sidecars); the audit trail lives at the finding layer once the analyst processes them. Phase-1 of ADR-0005 ships the Skill and pin template; phase-2 ships the analyst processing extension — until phase-2 lands, pins accumulate harmlessly on disk. See ADR-0005 for the rationale and the trade-offs.
+
+The loop is the smallest expression of the kernel reasoning about itself without auto-modifying itself. v1 honesty: the analyst's output is an LLM-strategized judgment, not measured truth; the counter-explanation challenge is the false-positive mitigation. Same framing rule as `test-strategist` and `security-reviewer`. See ADR-0004 for the detector-side rationale, ADR-0005 for the engineer-trigger side; see `template/templates/kernel-fit-finding.md` and `template/templates/kernel-fit-flag.md` for the artifact schemas.
 
 ---
 

package/template/templates/app-architecture.md

@@ -0,0 +1,102 @@
+---
+id: app-architecture
+type: app-architecture
+status: draft                          # draft | current | needs-refresh | archived
+owner: <git-handle>
+derived-from: [product-brief, data-architecture]
+downstream: [threat-model, hardening-checklist, tech-stack, module-spec/*]
+created: <YYYY-MM-DD>
+updated: <YYYY-MM-DD>
+schema-version: 1
+---
+
+## 1. Module Map
+
+_The set of modules and what each owns. Each module must trace to either a persona-named action in `product-brief.md` or to a logical clustering of entities from `data-architecture.md`. Orphan modules (no trace) halt the section with the drift challenge._
+
+**Modules**
+
+| Module | Owns | Traces to |
+| --- | --- | --- |
+| <module-name> | <one-line statement of what this module owns> | <persona-action OR entity-cluster> |
+
+**Drift challenge answered**
+
+_"Does any module here own state a persona never interacts with, OR does any persona's journey traverse modules in a way the boundaries don't support?"_
+
+## 2. Agent Orchestration Model
+
+_How LLM calls compose. Which modules call the LLM, what each call returns, how downstream modules consume the output. Tool boundaries. Where prompts live. For an AI-native SaaS, this is the meaty section — implicit "the LLM handles it" answers are rejected; named call sites and downstream consumers are required._
+
+**LLM call sites**
+
+| Call site (module.fn) | Trigger | Model | Returns | Downstream consumer |
+| --- | --- | --- | --- | --- |
+| <module>.<function> | <what triggers this call> | <model identifier> | <structured-output schema or one-line description> | <module that consumes> |
+
+**Tool boundaries**
+
+_Which tools each call site can invoke, and which are explicitly out-of-bounds. Names the kill switches for LLM-driven actions._
+
+**Drift challenge answered**
+
+_"Does any LLM call site bypass the tool boundaries declared, or have an unnamed retry / fallback path?"_
+
+## 3. Deterministic-vs-LLM Split
+
+_Per user-facing flow, the per-step decision: code or prompt, with a rationale that ties to a measurable property (determinism, cost, latency, capability). Implicit "AI handles it end-to-end" answers are rejected; per-step declaration is mandatory._
+
+**Flow tables**
+
+For each flow named in the brief's persona vignettes:
+
+### Flow: <flow-name>
+
+_From <persona>'s Tuesday-morning workflow._
+
+| Step | Mechanism | Rationale (ties to measurable property) |
+| --- | --- | --- |
+| 1. <step description> | deterministic \| llm | <one sentence — property: determinism \| cost \| latency \| capability> |
+| 2. ... | ... | ... |
+
+**Drift challenge answered**
+
+_"Does any flow have a step where the mechanism is undeclared, or a rationale that doesn't tie to a measurable property?"_
+
+## 4. State-Ownership Map
+
+_Where conversation state lives, workspace state lives, ephemeral / browser-session state lives. Each state class names its owning module from Section 1 and its persistence layer from `data-architecture.md`. State without an owning module triggers the drift challenge._
+
+**State classes**
+
+| State class | Owning module | Persistence layer | Lifetime |
+| --- | --- | --- | --- |
+| <e.g., conversation history> | <module from §1> | <entity from data-architecture OR "ephemeral"> | <durable \| session \| request> |
+
+**Drift challenge answered**
+
+_"Does any state class lack an owning module from Section 1?"_
+
+## 5. Surface Boundaries
+
+_What the project's `surfaces` enum contains. The canonical floor is `[ui, api, agent, db, auth, infra]`; projects may add (e.g., `payments`) or omit (e.g., no `auth` if relying on a host system). Each declared surface is mapped to at least one module from Section 1._
+
+**Surface declaration**
+
+| Surface | In v1? | Modules carrying this surface | Deferred to |
+| --- | --- | --- | --- |
+| ui | yes/no | <module names> | <v2 \| later \| N/A> |
+| api | ... | ... | ... |
+| agent | ... | ... | ... |
+| db | ... | ... | ... |
+| auth | ... | ... | ... |
+| infra | ... | ... | ... |
+| <custom> | ... | ... | ... |
+
+**Drift challenge answered**
+
+_"Does any surface in the enum have no module from Section 1 mapped to it?"_
+
+## Coherence check (end-of-atom)
+
+_When the atom reaches terminal state, the agent re-runs all five drift challenges to ensure section-targeted edits did not silently break other sections. The coherence check is fatal — any unanswered challenge halts the commit._

package/template/templates/bootstrap.md

@@ -0,0 +1,105 @@
+---
+id: <YYYY-MM-bootstrap>                # canonical bootstrap change-id; one per project
+type: change-spec                      # bootstrap is a change-spec variant, not a new type
+status: draft
+owner: <git-handle>
+area: bootstrap                        # the no-story carve-out for the bootstrap variant; SP-09 satisfied via this
+surfaces: [infra]                      # bootstrap is infra-only; UI / agent / api work begins post-bootstrap
+user-stories: []                       # bootstrap has no user-story; the area: bootstrap field satisfies SP-09 as a third carve-out alongside internal-tooling and enables
+related-spec: bootstrap                # equals area
+related-adrs: []                       # populated with every stack ADR from Phase 4
+creates-tech-debt: []
+resolves-tech-debt: []
+parent-change: null
+children: []
+revisits-change: []
+internal-tooling: false                # bootstrap is NOT internal-tooling — the code ships on the user path
+enables: []                            # bootstrap implicitly enables every downstream change-spec; the explicit list would be degenerate, so we leave it empty and rely on area: bootstrap as the SP-09 carve-out
+enabled-by: []
+trivial: false
+in-scope: []                           # explicit file enumeration — NOT ["."]
+out-of-scope: []                       # required, may be empty
+threat-model-delta: true               # bootstrap always touches threat-model (auth posture, RLS defaults, secret handling)
+created: <YYYY-MM-DD>
+updated: <YYYY-MM-DD>
+schema-version: 1
+---
+
+## Problem
+
+_What this change is doing: standing up the repo from empty. One paragraph._
+
+This change scaffolds the project from an empty repository to a bootable, tested, and ready-to-ship state. It is the only change in the project's history with `area: bootstrap`; subsequent changes target real modules.
+
+## Current Behavior
+
+_N/A for bootstrap — there is no current state. Repository is empty (or contains only `hstack/` after greenfield-init Phases 1–5)._
+
+- N/A.
+
+## Target Behavior
+
+_What shipping looks like, observably. Bootstrap's targets are bootability and gate-passing, not feature behavior._
+
+- The repository builds: `<configured-build-command>` exits 0.
+- The repository's test suite runs and passes: `<configured-test-command>` exits 0.
+- Every module declared in `app-architecture.md` Section 1 has a corresponding source directory with the minimal shell required for the module-spec to be reverse-engineered post-merge.
+- The initial migration sequence sketched in `data-architecture.md` Section 5 lands as actual `.sql` files under `supabase/migrations/` (or the chosen DB's migration directory) in the order: schema → RLS → pgvector → seeds.
+- CI runs the canonical commands from `ci-cd.md` and the gates pass.
+
+## Acceptance Criteria
+
+_GIVEN / WHEN / THEN. Bootstrap's acceptance is gate-based, not user-flow-based._
+
+GIVEN the repository at HEAD
+WHEN the engineer runs `<configured-build-command>` and `<configured-test-command>`
+THEN both exit 0 and no test is skipped.
+
+GIVEN the database after `m_0002_rls_policies.sql` has run
+WHEN any tenant-scoped table is queried without setting `app.<tenant-column>`
+THEN the query returns zero rows (RLS enforced from line zero).
+
+GIVEN the repository at HEAD
+WHEN a downstream engineer runs `/hstack:module-spec <module>` for any module from `app-architecture.md` Section 1
+THEN the Skill finds a target directory to reverse-engineer against and does not halt on missing source.
+
+## Invariants
+
+_Three or more bullets per SP-04. Bootstrap's invariants name the foundational guarantees that must survive every future change._
+
+- **RLS-enforced from line zero.** Every tenant-scoped table created by `m_0001_initial_schema.sql` has its RLS policy applied in `m_0002_rls_policies.sql` BEFORE any data lands. The migration ordering is a contract, not a convenience.
+- **Module boundaries match the declaration.** Every module in `app-architecture.md` Section 1 has a corresponding source directory; no module is silently dropped or renamed during scaffold. Future changes cannot add modules without updating the declaration first.
+- **Stack ADRs are authoritative.** Every choice in this scaffold (framework, DB client, auth integration, hosting deploy file, observability wiring) traces to an ADR from Phase 4. No silent stack divergence.
+
+## Scope Boundaries
+
+_Pointer to `in-scope` and `out-of-scope` frontmatter arrays. Bootstrap's `in-scope` is an explicit enumeration of every file being created. Wildcards are permitted but the engineer must list every top-level destination explicitly so the implementer's scope-lock does meaningful work._
+
+The `in-scope` enumeration is the contract: the implementer creates exactly the listed files and no others. Files appearing in the final scaffold but not in `in-scope` indicate a scaffold-spec gap and require a scope amendment.
+
+## Surfaces
+
+_Pointer to `surfaces` frontmatter. Bootstrap is `[infra]` only — UI / agent / api / db / auth surface work begins with the first feature change-spec after bootstrap merges._
+
+- **infra**: build configuration, dependency manifest, CI workflow, DB migration tooling setup, deployment configuration, observability wiring.
+
+UI work begins post-bootstrap; the scaffold ships only the minimum shell (layout, theme tokens) needed for the build to pass.
+
+## Linked Stories and Personas
+
+_N/A — bootstrap has `user-stories: []` and satisfies SP-09 via `area: bootstrap`. The bootstrap variant is a third carve-out alongside `internal-tooling: true` (Category A) and `enables: [...]` (Category B); `area: bootstrap` is mutually exclusive with both. See kernel addendum for the rule._
+
+## Related ADRs and Tech-Debt
+
+_Every stack ADR from Phase 4 (greenfield-init) goes here as a pointer with one-sentence justification. Examples:_
+
+- ADR-NNNN — Stack defaults adopted: <list>. Adopted as the project foundation.
+- ADR-NNNN+1 — Observability stack: PostHog + Sentry. Configured in this scaffold.
+
+## Resolves Tech-Debt
+
+_N/A — bootstrap creates the project; it does not resolve prior tech-debt._
+
+## Open Questions
+
+_Populated when status moves from draft to ready-to-plan. Bootstrap-specific examples: "Do we lint the migration SQL via sqlfluff or via Supabase's built-in lint?" "Do we vendor a UI component library in the initial commit or wait for the first UI feature?"_