hstack 0.4.0 → 0.5.1

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

@@ -20,6 +20,15 @@ description: |
   Discrepancies between predicted and observed behavior are exactly what section 4 exists to capture. Marking `passed` over a discrepancy would defeat the purpose of the gate.
   </commentary>
   </example>
+
+  <example>
+  Context: The integration suite is gated by `RUN_INTEGRATION=1` and the engineer ran `npm test` without setting it; the runner reported `Tests: 0 passed, 0 failed`.
+  user: "/hstack:verify 2026-06-knowledge-citations"
+  assistant: "I'll invoke verifier. Per V-05, an integration suite that executed zero tests is recorded as `not-run`, not `pass` — zero failures is not evidence of correctness when there were zero assertions to fail. The Skill halts at `status: ran` with a high-severity Discrepancy naming the suspected reason (env-gated, all-skipped, empty-collection, or filter-collapse)."
+  <commentary>
+  V-05 closes the verifier false-positive where a suite gated by an unset env var would silently pass on the absence of failures. The remediation is either supplying the missing env / fixture and re-running, or amending the plan's Verifier Expectations via scope amendment so the zero-test state is intentional and recorded.
+  </commentary>
+  </example>
 tools:
   - Read
   - Write
@@ -28,8 +37,8 @@ tools:
   - Glob
   - Bash
   - Task
-  - "{{TODO-SCRIPT: hstack/scripts/run-gates.sh — runs the consuming repo's test/lint/typecheck suite and captures output}}"
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — validates verification.md frontmatter and V-01/V-02}}"
+  - "{{TODO-SCRIPT: hstack/scripts/run-gates.sh — runs the consuming repo's test/lint/typecheck suite and captures output, including an observed-test-count per suite for V-05}}"
+  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — validates verification.md frontmatter and V-01/V-02/V-05}}"
 ---
 
 ## Purpose
@@ -62,7 +71,7 @@ Before any work:
 
 3. **Phase coverage mapping.** For each phase in `plan.steps-completed`, the subagent emits an entry in `phase-coverage` with a PASS / FAIL value computed from whether the phase's Verifier Expectations are met. Per V-01, `phase-coverage` keys must equal `plan.steps-completed`.
 
-4. **Test-results map.** The subagent writes the top-level `test-results` map covering `unit`, `integration`, `e2e`, `lint`, `typecheck`. Per V-02, any `failed` value blocks `status: passed`.
+4. **Test-results map.** The subagent writes the top-level `test-results` map covering `unit`, `integration`, `e2e`, `lint`, `typecheck`. Per V-02, any `failed` value blocks `status: passed`. Per V-05, before mapping `unit`, `integration`, or `e2e` to `pass`, the subagent confirms the runner's observed-test-count for that suite is greater than zero — a suite gated by an unset env var, all-skipped, empty-collection, or filter-collapsed to zero tests is recorded as `not-run` with a high-severity Discrepancy, not as `pass` on the absence of failures.
 
 5. **Test-plan coverage check.** The subagent walks the test-plan's Edge Cases bullets, Tenant Isolation Tests array, and Performance Budgets table, and confirms each observed in the test run. `test-plan-coverage` frontmatter map captures the three subsections. Per V-03, any tenant-isolation test absent or skipped blocks `status: passed` and is escalated to adversarial-review via Discrepancies. Per V-04, any performance-budget assertion that did not execute or that observed values outside the declared budget blocks `status: passed`.
 
@@ -72,7 +81,7 @@ Before any work:
 
 8. **Change-spec advance (mechanical, only on `passed`, Skill-orchestrator write per ADR-0002).** When and only when the subagent returned with `verification.md` at `status: passed`, read `hstack/specs/changes/<change-id>/spec.md` and inspect its `status` frontmatter. If `status: ready-for-implementation`, print a proposed-diff preview of the change-spec edit (`status: ready-for-implementation → ready-for-review`; `updated: <today>`) and prompt "Proceed with this change-spec advance? (Y/n)". Default Yes. On confirmation, perform the edit via the `Edit` tool, run `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` against the change-spec, then `git add` and commit with message `change-spec(<change-id>): ready-for-review`. This is a separate commit from the `verification(<change-id>): passed` commit — one commit per status transition, matching the finalize precedent. If the change-spec is already at `ready-for-review` or any downstream status, this step is a no-op (idempotent on re-runs). When verification status is `ran` or `failed`, this step does not run — the change-spec remains at `ready-for-implementation` until a subsequent re-run lands `passed`. Do NOT invoke `spec-author` for this write; per the kernel's Mechanical operations section, the value to write is fully determined by the verification postcondition and the change-spec's current status, so the Skill writes directly.
 
-9. **Validate.** Run `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` — V-01, V-02, V-03, V-04.
+9. **Validate.** Run `{{TODO-SCRIPT: hstack/scripts/validate-spec.ts}}` — V-01, V-02, V-03, V-04, V-05.
 
 ## Outputs
 
@@ -121,6 +130,7 @@ Beyond the kernel's general stop conditions:
 - A canonical command in `ci-cd.md` is missing or cannot execute (missing dependency, missing env var).
 - A phase's Verifier Expectations cannot be evaluated because the relevant test file is missing.
 - A test failure blocks `status: passed`. The Skill halts at `status: ran` (or `failed`) until the implementer fixes the failing test via a new `hstack-implement` invocation.
+- A `unit`, `integration`, or `e2e` suite executed zero tests (V-05). The Skill halts at `status: ran`; the subagent records the suite as `not-run` and logs the Discrepancy. Remediation is either (a) the implementer supplies the missing env / fixture so the suite collects and runs, or (b) a scope amendment removes the suite from the plan's Verifier Expectations so the zero-test state is intentional and recorded.
 
 ## Failure modes
 
@@ -131,6 +141,7 @@ Beyond the kernel's general stop conditions:
 ## Anti-patterns
 
 - Never invent a PASS. If tests are not green, status is `ran` or `failed`, not `passed`.
+- Never record a suite as `pass` on the absence of failures alone (V-05). A suite that ran zero tests — gated by an unset env var, all `.skip` / `.todo`, empty collection, or filter-collapsed — is `not-run`, not `pass`. The Skill propagates the zero-tests-ran signal from the runner output into the subagent context so the rule is enforceable rather than inferred.
 - Never skip a canonical command. The consuming repo's commands in `ci-cd.md` are mandatory.
 - Never silently drop a discrepancy. Even benign discrepancies get a one-line note.
 - Never score security or data. Stay in the mechanical-verification lane.

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.
 

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?"_

package/template/templates/data-architecture.md

@@ -1,35 +1,169 @@
 ---
 id: data-architecture
 type: data-architecture
-status: drafted                        # drafted | current | needs-refresh | archived
+status: draft                          # draft | current | needs-refresh | archived
 owner: <git-handle>
+assumes-database: postgres             # explicit so Phase 4 stack-decide can flag drift
 schema-snapshot-date: <YYYY-MM-DD>
 rag-architecture-version: 1
+derived-from: [product-brief]
+downstream: [app-architecture, threat-model, hardening-checklist, module-spec/*]
 created: <YYYY-MM-DD>
 updated: <YYYY-MM-DD>
 schema-version: 1
 ---
 
-## Tables and relationships
+## 1. Tenancy Model
 
-_ER diagram in mermaid or prose. The canonical tables, columns of interest, and foreign-key relationships._
+_The load-bearing question. The data-architect refuses to advance past this section until the tenant definition is concrete and ties to a persona in the brief._
 
-## RLS model
+**Pattern** — one of:
 
-_The universal pattern + per-table deviations. Validator rule DA-01: this section must contain the word "RLS" in a heading._
+- **A. Tenant = the customer organization** — single workspace per paying customer; users inside share visibility.
+- **B. Tenant = a sub-team within the customer organization** — multi-workspace per customer.
+- **C. Tenant = the individual user** — workspace-per-user.
+- **D. Custom** — document the pattern explicitly and explain why none of A/B/C fit.
 
-## RAG and embeddings
+**Rationale**
 
-_Where embeddings live, how retrieval is scoped, what the cache looks like, how tenant_id is enforced on every RPC._
+_One sentence tying the chosen pattern to the persona in `product-brief.md`. Example: "Pattern A because Maya (Director of CS) shares visibility with her 6 reps; sub-team isolation isn't requested by any v1 persona."_
 
-## Data lifecycle
+**Tenant identifier**
 
-_Retention, archival, deletion. Per-table policies._
+_The column name and type used to scope every tenant-scoped table (`workspace_id uuid`, `org_id text`, etc.). All downstream RLS predicates reference this column._
 
-## External data sources
+## 2. Entity Graph
 
-_Third-party integrations that write to our store. Webhook signature verification posture._
+_The set of entities and their relationships. Each entity must trace to either a persona-named action in `product-brief.md` or to the tenancy model from Section 1. Orphan entities halt with the drift challenge._
 
-## Conventions
+**Entities**
 
-_Naming, soft-deletes vs hard-deletes, audit fields, timestamp conventions, UUID vs serial._
+| Entity | Owns | Traces to | Relationships |
+| --- | --- | --- | --- |
+| <entity-name> | <one-line statement> | <persona-action OR tenancy-derived> | <FK refs> |
+
+**Conventions** (subsumed from prior template)
+
+_Naming (snake_case, plural tables), timestamps (`created_at`, `updated_at` on every table, ISO 8601), soft-deletes vs hard-deletes per entity, UUID vs serial choice with rationale, audit fields if any._
+
+**Drift challenge answered**
+
+_"Does any entity here have no trace to a persona or feature in the brief? Name it."_
+
+## 3. RLS Posture
+
+_Per-table policy sketch. Every entity from Section 2 falls into one of two categories — no third._
+
+**Tenant-scoped tables**
+
+| Table | Policy predicate sketch | Notes |
+| --- | --- | --- |
+| <table> | `<tenant-column> = current_setting('app.<tenant-column>')::uuid` | <e.g., RPC-only writes, no direct INSERT> |
+
+**Intentionally global tables**
+
+| Table | Why no RLS | Rationale |
+| --- | --- | --- |
+| <table> | <lookup data \| public reference \| ...> | <one sentence> |
+
+**Drift challenge answered**
+
+_"Does any tenant-scoped entity have an RLS policy that the chosen tenancy model wouldn't enforce? Name it."_
+
+## 4. RAG / pgvector
+
+_Whether v1 uses embeddings, what entity carries them, which embedding model, the tenant-scoped retrieval RPC signature. If v1 does not use RAG, mark this section `not-in-v1` with rationale and skip ahead._
+
+**Use in v1**
+
+_`yes` or `not-in-v1`. If not-in-v1, justify in one sentence (e.g., "v1 ships change-awareness without semantic retrieval; pgvector is a v2 layer")._
+
+**Embedding-bearing entities**
+
+| Entity | Embedding column | Model | Dimensions | Tenant-scoped retrieval RPC |
+| --- | --- | --- | --- | --- |
+| <entity> | <column name> | <e.g., openai:text-embedding-3-small> | <e.g., 1536> | <RPC signature with tenant predicate> |
+
+**Tenant-scoping requirement**
+
+_Every retrieval RPC MUST filter by the Section 1 tenant identifier. The drift challenge verifies this._
+
+**Drift challenge answered**
+
+_"Does any embedding-bearing entity have a retrieval RPC that bypasses tenant scoping? Name it."_
+
+## 5. Migration Sketches
+
+_Postgres-dialect DDL sketches for the initial migrations, with `-- TODO: confirm` markers on uncertain parts. The implementer reads these during bootstrap and writes the actual `.sql` files; the sketches are intent, not executable. Typical ordering: schema → RLS → pgvector. Data must never land before RLS._
+
+**Migration sequence**
+
+```
+m_0001_initial_schema.sql      -- Section 2 entities, tables + FKs, no policies yet
+m_0002_rls_policies.sql        -- Section 3 policies, applied per tenant-scoped table
+m_0003_pgvector_setup.sql      -- Section 4 RPCs and indexes (skip if not-in-v1)
+m_0004_seed_global_data.sql    -- Section 3 intentionally-global table seeds (optional)
+```
+
+**Sketch — m_0001_initial_schema.sql**
+
+```sql
+-- TODO: confirm UUID extension is enabled
+create extension if not exists "uuid-ossp";
+
+-- TODO: confirm column types and FK ON DELETE behaviors per entity
+create table <entity> (
+  id uuid primary key default uuid_generate_v4(),
+  <tenant-column> uuid not null references <tenant-table>(id) on delete cascade,
+  -- entity-specific columns
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now()
+);
+```
+
+**Sketch — m_0002_rls_policies.sql**
+
+```sql
+-- TODO: confirm session-variable name matches app convention
+alter table <entity> enable row level security;
+
+create policy <entity>_tenant_isolation on <entity>
+  for all
+  using (<tenant-column> = current_setting('app.<tenant-column>')::uuid);
+```
+
+**Sketch — m_0003_pgvector_setup.sql** (skip if Section 4 is `not-in-v1`)
+
+```sql
+-- TODO: confirm pgvector version compatible with embedding model dimensions
+create extension if not exists vector;
+
+alter table <embedding-bearing-entity>
+  add column embedding vector(<dimensions>);
+
+create index on <embedding-bearing-entity> using ivfflat (embedding vector_cosine_ops);
+
+-- TODO: confirm RPC signature and tenant predicate
+create or replace function nearest_<entity>(query_embedding vector, k int, p_<tenant-column> uuid)
+  returns table (id uuid, score float4)
+  language sql stable
+as $$
+  select id, embedding <=> query_embedding as score
+  from <embedding-bearing-entity>
+  where <tenant-column> = p_<tenant-column>
+  order by score
+  limit k;
+$$;
+```
+
+**Data lifecycle** (subsumed from prior template)
+
+_Retention windows per entity (e.g., "interactions: 18 months hot, archived after"), archival path, deletion guarantees (hard-delete vs soft-delete vs anonymize-and-retain). Lifecycle differences per tenant tier (free vs paid) noted here._
+
+**Drift challenge answered**
+
+_"Does any migration in the sketch sequence land data before its RLS policy? Name it."_
+
+## Coherence check (end-of-atom)
+
+_When the atom reaches terminal state, the agent re-runs all five drift challenges. Any unanswered challenge halts the commit._

package/template/templates/discovery/brainstorm.md

@@ -0,0 +1,69 @@
+---
+id: discovery-brainstorm
+type: discovery-technique
+technique: brainstorm
+applies-to: product-brief
+schema-version: 1
+---
+
+# Brainstorm — technique script
+
+This is the prompt sequence `product-discovery` runs in Brainstorm mode. Use this when the engineer has a problem domain but no concrete concept. The mode is **facilitated ideation** — the agent acts as coach pulling ideas out via structured exercises, not generating ideas for the engineer.
+
+## Pre-flight check
+
+Before entering the script, the agent confirms:
+
+- The engineer can name the problem domain in one sentence ("CS teams losing follow-up context") even if the solution is undefined.
+- The engineer has 60+ minutes available. Brainstorm runs multi-round; cutting it short produces shallow output.
+
+## Round 1 — SCAMPER pass on the problem statement
+
+For each SCAMPER lens, ask the engineer one question and write their answer:
+
+- **Substitute** — "What current workflow could be substituted away?"
+- **Combine** — "What two things, combined, would create new value here?"
+- **Adapt** — "What other industry has solved a similar pain — what did they do?"
+- **Modify** — "What single behavior, if amplified, would solve most of the pain?"
+- **Put to another use** — "What's a non-obvious user who has this same pain?"
+- **Eliminate** — "What part of the current workflow could disappear entirely?"
+- **Reverse** — "What if the user did the opposite of what they do today?"
+
+Answers land as raw text in a scratch section. Do NOT synthesize yet.
+
+## Round 2 — Reverse brainstorming
+
+Ask: "How would you make this problem **worse** for the user? List five ways."
+
+The engineer's answers reveal the load-bearing failure modes — the things the product must NOT do. These directly seed the **Explicitly NOT** section of the brief.
+
+## Round 3 — Six Thinking Hats on the strongest thread
+
+The agent picks the strongest 1–2 threads from Rounds 1 and 2 (the threads with the most concrete user actions named) and proposes them back. For each thread, walk the hats:
+
+- **White hat (facts)** — "What do we observably know about this user's workflow today?"
+- **Red hat (intuition)** — "What feels right or wrong about this thread, gut-check?"
+- **Black hat (caution)** — "What's the strongest case against this thread?"
+- **Yellow hat (optimism)** — "What's the strongest case for this thread?"
+- **Green hat (creativity)** — "What's the wildest version of this thread?"
+- **Blue hat (process)** — "Is this the right thread to deepen, or should we drop it?"
+
+After the Six Hats run, the engineer either commits to a thread or returns to Round 1 with a sharper problem statement.
+
+## Round 4 — Synthesis
+
+The agent proposes a one-paragraph synthesis of the strongest thread, framed as: "Here is what I heard you converge on. Concept: X. Underlying pain: Y. Target user: Z." The engineer confirms or revises.
+
+On confirmation, the agent transitions to the **product-brief.md** template and walks the sections, using the synthesis as the seed for Underlying Pain, Target User, and Value Proposition.
+
+## Required reframes (mandatory before brief lands)
+
+These run during the section walk of `product-brief.md`, regardless of which Brainstorm round produced the synthesis:
+
+- "Who specifically pays for this?" — concrete persona required.
+- "What's the smallest useful wedge?" — minimum shippable surface required.
+- "What would you have to believe to be wrong about this?" — falsifiability required.
+
+## Park-and-resume
+
+The agent surfaces a parking offer after each Round commits. If the engineer parks, the round's output is persisted in `hstack/.session-state/<session-id>.yaml`. Resume picks up at the next round.