hstack 0.16.0 → 0.18.0

package/template/templates/adr.md

@@ -1,26 +1,10 @@
----
-id: ADR-<NNNN>-<slug>
-type: adr
-status: proposed                       # proposed | accepted | deprecated | superseded
-owner: <git-handle>
-decision-date: <YYYY-MM-DD>
-supersedes: null                       # ADR id when this ADR replaces another
-superseded-by: null                    # ADR id when this ADR has been replaced; reciprocal with supersedes
-related-change-specs: []
-related-modules: []
-promoted-from-kernel-fit: []           # KF-NNNN ids that motivated this ADR; reciprocal with kernel-fit-finding.promoted-to (KF-04)
-created: <YYYY-MM-DD>
-updated: <YYYY-MM-DD>
-schema-version: 2
----
-
 ## Title
 
 _Short noun phrase._
 
 ## Status
 
-_Pointer to frontmatter `status`. Note any supersession relationship._
+_Accepted on `<YYYY-MM-DD>`. When this ADR replaces another, one line of prose here: `Supersedes ADR-NNNN`. The superseded ADR is not edited — the grep is the link._
 
 ## Context
 
@@ -32,7 +16,7 @@ _The choice, stated as an active sentence. One paragraph._
 
 ## Consequences
 
-_Positive, negative, and neutral outcomes. Particularly the trade-offs accepted. Challenge prompt: name two consequences that look bad. If you can't, what alternative would have made them visible? 2–4 paragraphs._
+_Positive, negative and neutral outcomes, and particularly the trade-off actually accepted. Challenge prompt, mandatory: name two consequences that look bad. If you can't, what alternative would have made them visible?_
 
 ## Alternatives Considered
 

package/template/templates/app-architecture.md

@@ -1,77 +1,76 @@
 ---
 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._
+_The modules, what each owns, and what reaches them. `Critical: yes` means the kernel's
+mandatory-test rule applies to this module's paths._
 
-**Modules**
+_The **Exposure** column is the exposure map. One line per entry point: `path` · kind (`page`,
+`api`, `action`, `job`, `webhook`) · status (`live`, `routable`, `off` — kernel § Context docs).
+A module owning no entry point of its own names the ones that reach it; a module no live entry
+point reaches is `dormant`, which is derived, not a fourth status. Updated in the PR that changes
+exposure, verified at `/promote`, and checkable by diffing these paths against the real routes._
 
-| Module | Owns | Traces to |
-| --- | --- | --- |
-| <module-name> | <one-line statement of what this module owns> | <persona-action OR entity-cluster> |
+| Module | Owns | Critical | Traces to | Exposure — entry points |
+| --- | --- | --- | --- | --- |
+| <module> | <what it owns, one line> | yes \| no | <user action OR entity cluster> | `app/(app)/<x>/page.tsx` · page · **live**<br>`app/api/<x>/route.ts` · api · **live**<br>`jobs/<x>.ts` · job · **off** |
+| <module> | ... | no | ... | _no entry point of its own — reached by `<module>` (live)_ |
+| <module> | ... | no | ... | _dormant — no live entry point reaches it_ |
+
+_This column grades the **product** severity of a finding, never its security severity. Every
+routable entry point is covered by the kernel's security checklist whatever the status says._
 
 **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?"_
+_"Does any module own something no user ever reaches, or does any user journey cross boundaries
+this map does not 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**
+_How the LLM calls compose: which module calls, what comes back, who consumes it, where the prompts
+live. Named call sites, not "the LLM handles it"._
 
 | 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> |
+| <module>.<function> | <what triggers it> | <model id> | <schema or one line> | <module> |
 
 **Tool boundaries**
 
-_Which tools each call site can invoke, and which are explicitly out-of-bounds. Names the kill switches for LLM-driven actions._
+_Which tools each call site may invoke, which are out of bounds, and where the kill switch is._
 
 **Drift challenge answered**
 
-_"Does any LLM call site bypass the tool boundaries declared, or have an unnamed retry / fallback path?"_
+_"Does any LLM call site bypass its declared tool boundaries, or have an unnamed retry or 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:
+_Per flow, per step: code or prompt, and why. A flow that genuinely is one model call is one row
+with its schema and its rationale — the rule is against the undeclared boundary, not against short
+tables._
 
 ### Flow: <flow-name>
 
-_From <persona>'s Tuesday-morning workflow._
-
-| Step | Mechanism | Rationale (ties to measurable property) |
+| Step | Mechanism | Rationale (names a property) |
 | --- | --- | --- |
-| 1. <step description> | deterministic \| llm | <one sentence — property: determinism \| cost \| latency \| capability> |
-| 2. ... | ... | ... |
+| 1. <step> | deterministic \| llm | <one sentence — determinism \| cost \| latency \| capability> |
 
 **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?"_
+_"Does any flow have a step whose mechanism is undeclared, or a rationale tied to no 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**
+_Where conversation state, workspace state and ephemeral state live. Each names its owning module
+from Section 1 and its persistence layer from `data-architecture.md`._
 
 | State class | Owning module | Persistence layer | Lifetime |
 | --- | --- | --- | --- |
-| <e.g., conversation history> | <module from §1> | <entity from data-architecture OR "ephemeral"> | <durable \| session \| request> |
+| <e.g. conversation history> | <module> | <entity OR "ephemeral"> | durable \| session \| request |
 
 **Drift challenge answered**
 
@@ -79,24 +78,13 @@ _"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**
+_Which surfaces this application has, and which module carries each. The usual set is `ui`, `api`,
+`agent`, `db`, `auth`, `infra`; add or omit as the product requires._
 
-| Surface | In v1? | Modules carrying this surface | Deferred to |
-| --- | --- | --- | --- |
-| ui | yes/no | <module names> | <v2 \| later \| N/A> |
-| api | ... | ... | ... |
-| agent | ... | ... | ... |
-| db | ... | ... | ... |
-| auth | ... | ... | ... |
-| infra | ... | ... | ... |
-| <custom> | ... | ... | ... |
+| Surface | Present? | Modules carrying it |
+| --- | --- | --- |
+| <surface> | yes \| no | <modules> |
 
 **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._
+_"Does any surface have no module mapped to it?"_

package/template/templates/code-standards.md

@@ -0,0 +1,107 @@
+---
+id: code-standards
+type: code-standards
+updated: <YYYY-MM-DD>
+---
+
+_The rules that need judgment. Size, typing, unread errors, console and `process.env` are the
+linter's job (`hstack/templates/eslint-clean-code.mjs`, at `error`, with a suppressions ratchet);
+nothing here repeats what it already fails. Read this file before writing application code;
+`/hstack-wrap` reads the diff against it before the PR. Each rule carries one example from this
+repo — the observed failure it exists for — so a reader knows the rule is about here, not about a
+book. Fill the `Seen here` lines from the codebase; leave a rule's line empty when it has not
+happened yet, and add the example in the PR where it does._
+
+## 1. Where things live
+
+_The one sanctioned path for each cross-cutting concern. A second one is a finding._
+
+| Concern | Module | What it gives you |
+| --- | --- | --- |
+| Logging | `<lib/observability/logger>` | structured, redacted, tenant-tagged |
+| Configuration | `<lib/env>` | every variable validated once at boot |
+| Database client | `<lib/supabase/{server,client,admin}>` | the RLS posture chosen for you |
+| Errors | `<lib/errors>` | `AppError` with `code` and `cause`; the boundary handler |
+| Retry / sleep / chunk | `<lib/retry>` | abort-aware, already tested |
+| Shared UI primitives | `<components/ui>` | — |
+
+## 2. Before writing, search
+
+Before adding a helper, a client, a wrapper, a parser or a formatter, grep for one that exists.
+If it exists, use it. If it is almost right, fix it in place and move the callers. Never write a
+second one beside the first — the copies drift, and the drift is a bug nobody planned.
+
+Seen here: _<e.g. seven `sleep` definitions; three copies of the same vendor client, one with
+retry and two without>_
+
+## 3. One function, one responsibility, one level of abstraction
+
+A function either orchestrates — calls named steps in order — or is one step. When a reader needs
+a comment to find where the next phase starts, the function is two functions and the comment is
+the name of the second. Extract until each name says what its body does.
+
+Seen here: _<e.g. a stream handler that gates, fetches, builds the prompt, persists, retries and
+reports cost, in one body>_
+
+## 4. A React component does not talk to the network
+
+Fetching, streaming, protocol decoding and retry live in a hook or a service module. The
+component receives data and callbacks, and renders. A component that parses a response body is
+a service wearing a template.
+
+Seen here: _<e.g. a chat component parsing server-sent events by hand inside a mutation>_
+
+## 5. A file's name says what it contains, and it contains one thing
+
+If the folder or the file cannot be named after its single responsibility, it has more than one.
+One vendor client per file. No `helpers.ts` past two hundred lines. No file that is a barrel
+(`index.ts`) and an implementation at the same time.
+
+Seen here: _<e.g. a file named after one OAuth broker holding six vendor APIs>_
+
+## 6. Names describe behaviour, not category
+
+`get*` reads and has no side effect. `is*` / `has*` return a boolean. A name that needs its
+docblock to be understood is the wrong name. One word per concept across the codebase — pick one
+of the synonyms and use it everywhere. No `v2`, `new`, `old`, `legacy` in a name: the name says
+what it is, git says how old.
+
+Seen here: _<e.g. `getX` that creates and connects; card / job / task for one entity>_
+
+## 7. A returned error is a handled error
+
+Errors travel one way: thrown (with `cause`) from where they happen, caught once at the boundary
+— the route, the job, the server action — where a single handler logs them and shapes the
+response. In between, code neither logs-and-rethrows nor catches-and-continues. A `catch` either
+handles, rethrows with `cause`, or carries a one-line justification for swallowing. A client
+that returns `{ data, error }` instead of throwing has `error` read on every call. A write is
+never followed by `ok: true` without its result being checked.
+
+Seen here: _<e.g. an update whose result was never read, answered with `{ ok: true }`>_
+
+## 8. Replace, do not add beside
+
+A new implementation of an existing thing ships in the PR that deletes the old one, with every
+import moved. No parallel folder, no second system left wired "for now", no legacy path still
+reachable from a live route.
+
+Seen here: _<e.g. two component trees for one screen; three agent loops each with its own cost
+tracker>_
+
+## 9. Delete what nothing imports
+
+An unused file, export or dependency is removed in the PR that orphaned it, not recorded as
+debt. Dead code is read by the next agent as live.
+
+Seen here: _<e.g. whole component folders no route reaches>_
+
+## 10. Constants live in one place
+
+Table names, status strings, limits, timeouts and model ids are imported from a constants module,
+never retyped as literals at the call site. A rename is one edit.
+
+Seen here: _<e.g. one table name typed by hand in a hundred places>_
+
+**Drift challenge answered**
+
+_"Which rule above has the repo violated since this file was last updated, and where?"_

package/template/templates/data-architecture.md

@@ -1,127 +1,103 @@
 ---
 id: data-architecture
 type: data-architecture
-status: draft                          # draft | current | needs-refresh | archived
-owner: <git-handle>
-assumes-database: postgres             # explicit so Phase 4 stack-decide can flag drift
+assumes-database: postgres             # explicit, so a database change surfaces as a contradiction
 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
 ---
 
 ## 1. Tenancy Model
 
-_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._
+_The load-bearing question. Nothing downstream stabilizes until this one is concrete._
 
 **A tenant is a ...**
 
-_One concrete noun from this product's own vocabulary, plus the rule for who is inside one and who is not. Common shapes, offered as examples rather than as a menu: the customer organization (one workspace per paying customer, users inside share visibility); a sub-team within that organization (multi-workspace per customer); the individual user (workspace-per-user). Products whose tenant is a project, a device, a contract, a site, a case or a season are ordinary and none of those three fit them — name yours._
+_One concrete noun from this product's own vocabulary, plus the rule for who is inside one and who
+is not. Common shapes, offered as examples rather than as a menu: the customer organization (users
+inside share visibility); a sub-team within it; the individual user. Products whose tenant is a
+project, a device, a contract, a site or a case are ordinary and none of those three fit them —
+name yours._
 
 **Rationale**
 
-_One sentence tying the tenant to a persona in `product-brief.md`. Example: "The tenant is the customer organization, because Maya (Director of CS) shares visibility with her 6 reps and no v1 persona asks for sub-team isolation."_
+_One sentence tying the tenant to a real user. Example: "The tenant is the customer organization,
+because Maya shares visibility with her 6 reps and nobody has asked for sub-team isolation."_
 
 **Tenant identifier**
 
-_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._
+_The column name and type scoping every tenant-scoped table (`workspace_id uuid`, `org_id text`).
+Every RLS predicate below references this column._
 
 ## 2. Entity Graph
 
-_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._
-
-**Entities**
+_The entities and their relationships. Each entity traces to something a user does, or to the
+tenancy model above._
 
 | Entity | Owns | Traces to | Relationships |
 | --- | --- | --- | --- |
-| <entity-name> | <one-line statement> | <persona-action OR tenancy-derived> | <FK refs> |
+| <entity-name> | <one-line statement> | <user action OR tenancy-derived> | <FK refs> |
 
-**Conventions** (subsumed from prior template)
+**Conventions**
 
-_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._
+_Naming (snake_case, plural tables), timestamps (`created_at`, `updated_at`, ISO 8601), soft- vs
+hard-deletes per entity, UUID vs serial 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."_
+_"Does any entity here trace to nothing a user does? Name it."_
 
 ## 3. RLS Posture
 
-_Per-table policy sketch. Every entity from Section 2 falls into one of two categories — no third._
+_Every entity from Section 2 falls into one of two categories — there is 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> |
+| <table> | `<tenant-column> = current_setting('app.<tenant-column>')::uuid` | <e.g. RPC-only writes> |
 
 **Intentionally global tables**
 
 | Table | Why no RLS | Rationale |
 | --- | --- | --- |
-| <table> | <lookup data \| public reference \| ...> | <one sentence> |
+| <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."_
+_"Does any tenant-scoped entity have a policy the tenancy model would not 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**
+_Whether embeddings are in use, what carries them, which model, and the tenant-scoped retrieval
+RPC. If they are not in use, say so in one sentence and skip ahead._
 
 | 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**
+| <entity> | <column> | <e.g. openai:text-embedding-3-small> | <e.g. 1536> | <RPC signature with the tenant predicate> |
 
-_Every retrieval RPC MUST filter by the Section 1 tenant identifier. The drift challenge verifies this._
+_Every retrieval RPC filters by the Section 1 tenant identifier, inside the similarity search and
+not after it._
 
 **Drift challenge answered**
 
-_"Does any embedding-bearing entity have a retrieval RPC that bypasses tenant scoping? Name it."_
+_"Does any embedding-bearing entity have a retrieval path that bypasses tenant scoping?"_
 
 ## 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**
+_Postgres-dialect sketches with `-- TODO: confirm` markers. The migration that ships is written by
+the change that needs it; these are intent, not executable. Ordering: schema → RLS → pgvector. Data
+never lands before its policy._
 
 ```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
+-- schema
 create table <entity> (
-  id uuid primary key default uuid_generate_v4(),
+  id uuid primary key default gen_random_uuid(),
   <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
+-- policy, in the same migration as the table (kernel § Security checklist)
 alter table <entity> enable row level security;
 
 create policy <entity>_tenant_isolation on <entity>
@@ -129,38 +105,11 @@ create policy <entity>_tenant_isolation on <entity>
   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)
+**Data lifecycle**
 
-_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._
+_Retention per entity, archival path, deletion guarantees (hard-delete, soft-delete, or
+anonymize-and-retain)._
 
 **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._
+_"Does any migration in this sequence land data before its policy? Name it."_