hstack 0.4.0 → 0.5.0

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.

package/template/templates/discovery/forcing-questions.md

@@ -0,0 +1,76 @@
+---
+id: discovery-forcing-questions
+type: discovery-technique
+technique: forcing-questions
+applies-to: product-brief
+schema-version: 1
+---
+
+# Forcing-questions — technique script
+
+This is the prompt sequence `product-discovery` runs in Forcing-Questions mode. Use this when the engineer has a concept but it's vague or oversold — the technique probes claims and reframes the underlying pain. Pattern derived from YC-partner forcing questions and the Gstack approach.
+
+The agent's operating mode in this technique is **reframe-driven probing**: every claim the engineer makes triggers a reframe. The engineer's job is to defend the claim or accept the reframe. The brief converges only when the claims survive the probes.
+
+## Pre-flight check
+
+Before entering the script, the agent confirms:
+
+- The engineer has a concept they can state in one or two sentences.
+- The engineer is open to being wrong about their concept. The technique surfaces reframes that may invalidate the founder's first articulation; founders who can't tolerate that should pick Project-Brief mode instead.
+
+## Probe 1 — The 10-star reframe
+
+Ask: "What's the 10-star product hiding inside this request? What you described is 5-star; what's the 10-star version that solves the actual underlying pain?"
+
+The engineer's first answer is often a feature embellishment ("...with AI"). Re-ask: "That's a feature. What's the **underlying** pain — what does the user fail to do today that the 10-star product would make trivial?"
+
+The reframe sticks when the engineer names a pain that is one level deeper than the original concept. The brief's **Underlying Pain** section seeds from this answer.
+
+## Probe 2 — The smallest useful wedge
+
+Ask: "What's the smallest useful wedge? If you shipped one slice of the 10-star product and nothing else, what's the one slice that would still get a real user to pay?"
+
+The engineer's first answer is usually too large. Re-ask: "Cut it in half. What's left when you remove every feature that isn't load-bearing for the slice you just described?"
+
+The reframe sticks when the engineer names a wedge that can be built by one engineer in a quarter and that, alone, would justify a real user's payment. The brief's **Smallest Useful Wedge** section seeds from this answer.
+
+## Probe 3 — The named user
+
+Ask: "Who specifically pays for this? Name a real person — first name, role, company-size band, and the workflow this product enters on a Tuesday morning."
+
+The engineer's first answer is often a role abstraction ("Directors of CS"). Re-ask: "Pick one specific Director of CS you've talked to. What's her name, what's her company's name, and what does she do on a Tuesday morning that this product changes?"
+
+If the engineer cannot name a specific person, halt and surface: "The named-user constraint isn't met. We can either (a) park here and you go talk to three real users this week, or (b) acknowledge in the brief that this is anchored on a hypothetical user, which makes everything downstream a gamble." Founders sometimes choose (b); the brief records the choice in **Open Risks**.
+
+The brief's **Target User** section seeds from this answer.
+
+## Probe 4 — The falsification probe
+
+Ask: "What would you have to believe to be wrong about this concept? Name the belief and the evidence that would falsify it."
+
+The engineer's first answer is often "users won't like it" — too vague. Re-ask: "Be specific. What's a load-bearing assumption about the user, the market, or the technology that, if wrong, kills the product? And what experiment would tell you if it's wrong?"
+
+The reframe sticks when the engineer names a falsifiable belief plus an experiment that would resolve it within weeks. The brief's **Open Risks** section seeds from this answer.
+
+## Probe 5 — The scope-reduction question
+
+Ask: "If you had to ship in 8 weeks with one engineer, what would you cut? Walk me through the cut list."
+
+The engineer's cuts reveal what they think is load-bearing vs. embellishment. The brief's **Explicitly NOT** section seeds from the cut list — the things the engineer would cut are exactly the things v1 explicitly does NOT do.
+
+## Probe 6 — The reframe-staleness check
+
+After Probes 1–5, the agent surfaces: "The brief is converging on [X]. Your starting concept was [Y]. Any external documents (Notion pages, pitch deck, README) still naming [Y]? Those are now stale. Cleanup checklist:"
+
+The engineer either confirms the docs are stale and lists them for cleanup, or pushes back ("no, Y is still the framing") — in which case the agent re-runs Probe 1 to reconcile.
+
+## Synthesis
+
+After all six probes, the agent proposes a one-paragraph synthesis: "Here is what survived the probes. Concept: [refined X]. Underlying pain: [Probe 1 answer]. Smallest wedge: [Probe 2 answer]. Named user: [Probe 3 answer]. Falsification: [Probe 4 answer]." The engineer confirms or revises.
+
+On confirmation, the agent transitions to the **product-brief.md** template and walks the sections. The probe answers seed the corresponding brief sections; the Forcing-Prompt Answers section records the probes verbatim as evidence the technique ran.
+
+## Park-and-resume
+
+The agent surfaces a parking offer after each probe commits. If the engineer parks, the probe's output is persisted in `hstack/.session-state/<session-id>.yaml`. Resume picks up at the next probe.

package/template/templates/discovery/project-brief.md

@@ -0,0 +1,53 @@
+---
+id: discovery-project-brief
+type: discovery-technique
+technique: project-brief
+applies-to: product-brief
+schema-version: 1
+---
+
+# Project-brief — technique script
+
+This is the prompt sequence `product-discovery` runs in Project-Brief mode. Use this when the engineer is already concrete about the product and just needs structure to land the brief artifact. This is the **lightest-touch** technique — collaborative, structured, no heavy reframes — but the three required forcing prompts still fire.
+
+The agent's operating mode in this technique is **structured walk**: the engineer's existing thinking is the proposal layer; the agent prompts section by section, confirms or revises, lands the brief.
+
+## Pre-flight check
+
+Before entering the script, the agent confirms:
+
+- The engineer can state the concept in two or three sentences without hedging.
+- The engineer can name a specific real user (not a role abstraction).
+- The engineer can name a concrete success metric.
+
+If any of the three fails the concreteness floor, the agent halts and suggests switching to Forcing-Questions mode — the engineer's thinking is too vague for Project-Brief mode, which assumes concreteness.
+
+## Section walk
+
+The agent walks `product-brief.md` section by section. For each section, the agent asks one open question, accepts the engineer's answer, surfaces one clarifying re-ask if the answer is vague, then commits the section.
+
+1. **Underlying Pain** — "Describe what the user struggles with today, in concrete terms. A Tuesday-morning workflow vignette is the unit of clarity."
+2. **Target User** — "Name a specific real user. First name, role, company-size band, the tools they use, the workflow this product enters."
+3. **Value Proposition** — "What outcome does this product deliver to the named user? Outcome, not features."
+4. **Smallest Useful Wedge** — "What's the minimum shippable surface that delivers real value? Would the named user still pay for the wedge alone?"
+5. **Success Criteria** — "What measurable, time-bound outcome tells you v1 worked? Concrete number, concrete window."
+6. **Explicitly NOT** — "What is this product NOT? Two bullets minimum. What population it does NOT serve, what workflows it does NOT enter, what features it does NOT include."
+7. **Open Risks** — "What could make this product fail? Name at least one belief that, if wrong, kills the product."
+
+## Required forcing prompts
+
+Even in this lightest-touch mode, the three required forcing prompts MUST run before the brief can land. They run after the section walk completes:
+
+- "Who specifically pays for this?" — re-prompt the engineer to defend the Target User against the buyer question. The Target User and the buyer may be different (Maya the Director of CS uses it; her CFO pays for it). Both must be named.
+- "What's the smallest useful wedge?" — re-prompt the engineer to defend the wedge against the "would the user pay for the wedge alone?" question. Yes required.
+- "What would you have to believe to be wrong about this?" — re-prompt for a falsifiable belief + experiment to resolve it. Names the load-bearing risk.
+
+These three answers are logged in the brief's **Forcing-Prompt Answers** section as evidence the probes ran. The engineer cannot skip them; the technique downgrades to Forcing-Questions mode mid-session if the engineer refuses any of the three.
+
+## Synthesis
+
+There is no explicit synthesis step in Project-Brief mode — the section walk IS the synthesis. The brief lands at `status: current` when the last section commits and the three forcing prompts are answered.
+
+## Park-and-resume
+
+The agent surfaces a parking offer after each section commits. If the engineer parks, the section's output is on disk and `hstack/.session-state/<session-id>.yaml` records the next-section pointer. Resume picks up at the next section.

package/template/templates/product-brief.md

@@ -0,0 +1,56 @@
+---
+id: product-brief
+type: product-brief
+status: draft                          # draft | current | needs-refresh | archived
+owner: <git-handle>
+technique-used: <brainstorm | forcing-questions | project-brief>
+derived-from: []                       # always empty — product-brief is Phase 1, no upstream
+downstream: [vision, mvp-scope, personas, glossary]
+created: <YYYY-MM-DD>
+updated: <YYYY-MM-DD>
+schema-version: 1
+---
+
+## Underlying Pain
+
+_What the user actually struggles with on a Tuesday morning, in concrete terms. Not "users want X" — "this specific person spends 20 minutes doing Y and misses Z." One paragraph, 4–8 sentences. The forcing-prompt reframes should have moved this away from the founder's first articulation; the result lands here._
+
+## Target User
+
+_A named, specific user (not "users", not "customers") with a workday vignette. Includes role, company-size band, tools they use today, the workflow this product enters. If multiple personas matter for v1, name them all — but each must pass the concreteness floor._
+
+## Value Proposition
+
+_What this product delivers to the named user, in their language. One paragraph. Distinct from features — this is the outcome they buy._
+
+## Smallest Useful Wedge
+
+_The minimum shippable surface that delivers real value to the named user. Forcing-prompt answer: "Would the named user still pay for this if you shipped only the wedge and nothing else?" Yes required; if no, the wedge is too large or the user is wrong._
+
+## Success Criteria
+
+_Concrete, measurable, time-bound. "Maya saves 10 minutes per QBR prep within 4 weeks of activation" not "users love it." At least one criterion; more is better._
+
+## Explicitly NOT
+
+_Two-bullet minimum. The boundaries of the product. What this is NOT, what it does NOT do, what populations it does NOT serve. Required, never optional — over-broad scoping is the #1 product failure mode._
+
+-
+-
+
+## Open Risks
+
+_The things that could make this product fail. The forcing-prompt "What would you have to believe to be wrong about this?" answer lands here. At least one risk; more is better._
+
+## Forcing-Prompt Answers
+
+_Evidence that the three required reframes ran. Logged inline as confirmation the probes were not skipped._
+
+**Who specifically pays for this?**
+_The named user / buyer plus the rationale ("Director of CS, because retention is their KPI")._
+
+**What's the smallest useful wedge?**
+_The wedge plus the rationale ("Change-awareness alone, because the rest of the workflow is downstream of it")._
+
+**What would you have to believe to be wrong about this?**
+_The belief plus the falsifiability angle ("That CS reps will trust LLM-generated summaries — wrong if they require human-curated context")._