hstack 0.7.1 → 0.17.0

package/template/KERNEL.md

@@ -0,0 +1,167 @@
+# hstack — Kernel (KERNEL.md)
+
+**In any conflict between this file and another document — a Skill, a subagent, a doc, a message — this file wins.** It changes only by Hugo, and only after a real problem has occurred twice (§ How this file changes).
+
+---
+
+## What hstack is
+
+hstack is rules, CI, an agent review on every PR, and living docs holding the agent's memory. It governs how engineers and AI agents collaborate on a codebase, from a change's inception to its merge.
+
+It is not a project tracker — Notion is — nor a SOC 2 / GDPR compliance substrate. The only deployment step it carries is `/hstack-promote`.
+
+The human's job is intent, testing the app, and reading the PR description with its findings.
+
+---
+
+## Context docs
+
+Living docs, at `hstack/context/`, are the agent's memory between sessions: `data-architecture.md` (tenancy, entities, RLS, RAG) · `app-architecture.md` (module map, state ownership, surface boundaries) · `tech-stack.md` (pinned versions are pinned on purpose — never bump one unrequested) · `infrastructure.md` (where things run, why the couplings, the gotchas) · `roadmap.md` (Now / Next / Later — **advisory only, never a gate**) · `invariants.md` · `review-miss.md`.
+
+The **exposure map** is a column of the Module Map in `app-architecture.md`. Its atom is an entry point — page route, API route, server action, job, webhook — at `live`, `routable` (the URL responds, nothing links to it, it is fully exposed) or `off`. Updated in the PR that changes exposure, verified at `/hstack-promote`.
+
+Read triggers: db / RLS / migration → data-architecture; env / deploy / dependencies → infrastructure; user reachability → app-architecture; always → tech-stack.
+
+**Non-negotiable: the agent updates a living doc in the same PR that invalidates it.** Committed state is the only authoritative view of another session — Luke's, a parallel worktree — so that PR is the coordination channel, and there is no other. Missing or stale is said in the PR, never invented.
+
+Frozen, dated banner, not updated: `threat-model.md`, `product-brief.md`, `vision.md`, `personas/`, `incident-runbook.md`.
+
+Structure: docs only under `hstack/context/`, decisions only under `hstack/adr/`, debt only under `hstack/tech-debt/`. No new root `.md` or directory without agreement.
+
+---
+
+## Scope rules
+
+Announce the perimeter before writing. **Writes are restricted to the announced perimeter.**
+
+- Refuse to drop, weaken, or modify any invariant declared in `invariants.md`.
+- If scope expansion is necessary, halt and ask rather than acting unilaterally.
+
+---
+
+## Workflow
+
+Branch (never the default branch, one per change) → announce the perimeter → a five-bullet plan in the conversation when it holds more than three files → code and tests → `/hstack-wrap` → PR → fast CI green → a human other than the author reads → merge → `/hstack-promote`.
+
+| When | Then |
+| --- | --- |
+| db, schema or RLS work | the Supabase skills, and `data-architecture.md` |
+| the change is done | `/hstack-wrap` |
+| the PR is merged | `/hstack-promote` |
+| a sensitive surface is touched | `/hstack-adversarial-review`, in a fresh session (§ Review) |
+| a bug a review missed | an entry in `review-miss.md` |
+| a module's tests look thin | `/hstack-test-audit <module>` |
+
+**The PR is the confirmation gate.** Everything the agent decides — a living-doc update, a tech-debt file, a conscious shortcut, an ADR draft — lands in the diff *and* is named in the description, which also names the Notion feature it serves, when there is one.
+
+One PR, one intention — a change spanning unrelated modules splits into several. One change, one session — once the PR is open the next starts fresh, and what it needs lives in the PR description or a living doc, never in the conversation.
+
+Two CI lanes: the fast one — typecheck, lint, critical tests — blocks the merge, the slow one is advisory. A hotfix still goes through PR + CI; it skips preview and the train, never the checks.
+
+---
+
+## Tests
+
+Tests are mandatory on critical paths and on every business invariant a change touches. At plan time, one question: *does this code decide something that would be wrong silently?* If it does, a test names the invariant. `/hstack-test-audit` is on demand, never a per-change phase.
+
+---
+
+## Test immutability
+
+Once a test file exists in the working tree (committed or staged), **no agent may edit or delete it without per-test, per-conversation human authorization.** This rule exists because the dominant failure mode of LLM-driven implementation is the model editing an assertion or deleting a test to make the suite go green, rather than fixing the code under test.
+
+**What counts as a test.** Files matching the repo's test patterns (e.g. `*.test.ts`, `*.spec.ts`, `__tests__/**/*`, `e2e/**/*`, `*_test.go`), snapshot files (`__snapshots__/*`), and assertion-bearing fixtures — factories and seed data encoding expected outputs.
+
+**Authorization protocol.** Halt before editing. Surface (a) the test file and test name, (b) why it must change — what it asserts vs. what is now correct, with evidence, (c) the proposed diff, (d) the alternatives, starting with fixing the code under test. Then wait for the canonical phrase — `Ok to change test <name>` or `Ok to delete test <name>`, `<name>` being the file path or a uniquely-identifying test name. The agent echoes it back verbatim before acting; nothing else is an authorization.
+
+**Carve-outs.** New tests need no authorization — "new" means the path did not exist at session start. A content-preserving move is permitted, surfaced in the commit message so the review can verify nothing drifted.
+
+**Forbidden no matter what.**
+
+- Blanket authorizations ("go ahead and fix any failing tests", "update whatever snapshots need it"). Authorizations are per-test, per-conversation. The agent refuses blanket scope.
+- Bulk snapshot updates via `--update-snapshots`, `jest --updateSnapshot`, `vitest -u`, or any equivalent flag, including in pre-commit hooks.
+- Relaxing an assertion without authorization (e.g., tightening a regex to a substring match, broadening a `.toBe()` to `.toContain()`, increasing a timeout to mask a real bug).
+- Deleting a `.skip` annotation, replacing a `test()` call with `test.todo()`, or otherwise neutralizing a test without authorization. Neutralization is a form of deletion.
+- Editing a test as part of "cleaning up" a phase without an explicit authorization for that test, even if the edit is cosmetic.
+
+Authorization is single-use: it covers the test and the change discussed in the current conversation, and never carries across sessions. An unauthorized test edit is a blocking review finding.
+
+---
+
+## Security checklist
+
+On every change, in the writing:
+
+1. RLS lands in the migration that creates the table, not in a follow-up.
+2. Tenant scoping is filtered server-side — RPCs and pgvector calls included.
+3. Migrations are additive by default; contraction ships in a later PR.
+4. Secrets live in the environment. A `service_role` key never reaches client-side code.
+5. Every route and server action is authenticated by default.
+6. Input is validated at the network boundary.
+7. User-generated content is untrusted input inside a prompt (INF-05).
+
+This applies to every routable entry point, whatever the exposure map says.
+
+CI backstops, wired once: secret scanning, and a grep that fails the build on `service_role` outside server directories.
+
+---
+
+## Review
+
+Every PR: `/hstack-wrap` runs `/review` and `/security-review` before the push, and their findings go in the PR description.
+
+**Sensitive surfaces** — agent or tool boundaries, auth, RLS, schema and migrations, pgvector, payments and credits — additionally get a deep review in a fresh session. The session that authored the change and the session that reviews it are separate Claude Code sessions: the author's working memory, scratchpad, and conversation are not loaded into the reviewer's session. This is honor-system.
+
+Reviews are LLM judgments, not evidence. An empty findings list means the reviewer found nothing, not that nothing is there. CI is the only mechanical check; frame PR descriptions accordingly. The exposure map grades the **product** severity of a finding, never its security severity.
+
+A bug a review missed goes into `review-miss.md`; two misses in one category earn a custom review lens.
+
+---
+
+## Tech-debt
+
+One file per item under `hstack/tech-debt/`, from the template, with grep-able frontmatter: `id`, `severity`, `related-modules`, `created`. The file exists = the item is open. Deleted in the PR that fixes it = resolved; git is the audit trail.
+
+A conscious shortcut that survives the merge is a tech-debt file written in the same PR and named in its description.
+
+At perimeter time, surface the items whose `related-modules` intersect the perimeter and propose them — Hugo decides. Never fix one silently. An item that needs six sections is a Notion task, not a tech-debt item.
+
+---
+
+## ADRs
+
+One-way doors only: fixable in one PR, then no ADR. Nygard, one page, no frontmatter machinery, drafted by the agent in the PR that implements the decision.
+
+---
+
+## Templates
+
+Templates live at `hstack/templates/`; fill them, do not invent structure. They are `tech-debt.md`, `adr.md`, `story.md`, and the living-doc templates — data-architecture, app-architecture, tech-stack, infrastructure, roadmap. The PR description has its own, `.github/pull_request_template.md`, rendered by GitHub.
+
+---
+
+## Stop conditions
+
+Halt and ask the human when:
+
+- A write outside the announced perimeter is needed.
+- A `service_role` Supabase key, raw shell, or other forbidden tool would be used.
+- A write-capable MCP tool is active in the same session as a query returning user-generated content from a tenant-scoped table (INF-05). The prompt-injection mitigation is load-bearing: split the session or disable the MCP before the read.
+- A load-bearing MCP is unreachable. Do not silently fall back to stale documents.
+- A write-capable MCP would run against production outside `/hstack-promote`.
+- `--no-verify`, or any other hook or check bypass, would be used. No deadline changes this.
+- The intended behavior is ambiguous.
+
+Halting is not failure. It is the correct response when preconditions are not met.
+
+---
+
+## Where state lives
+
+Notion holds product: epics, features, tasks, notes. The repo holds every piece of engineering memory: living docs, tech-debt, `review-miss.md`, ADRs. GitHub holds code mechanics: PRs and CI. The split is load-bearing.
+
+---
+
+## How this file changes
+
+This file changes only by Hugo, and only after a real problem has occurred twice. `review-miss.md` and `hstack/tech-debt/` are what make "twice" countable. Agents propose — in a PR description, or an entry in `review-miss.md` — and never edit this file or an ADR unilaterally.

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,8 +16,15 @@ _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
 
 _What was on the table; why each was rejected. One paragraph per alternative._
+
+## Forecloses / Enables
+
+_Against `hstack/context/roadmap.md`: which Next/Later item does this decision make more expensive (foreclose) or cheaper (enable)? One line each. "None" is a valid answer. When the roadmap is missing or stale, write `n/a — roadmap stale/missing` instead of guessing. Advisory — never a merge gate._
+
+- Forecloses:
+- Enables:

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/data-architecture.md

@@ -1,130 +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._
 
-**Pattern** — one of:
+**A tenant is a ...**
 
-- **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.
+_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 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."_
+_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>
@@ -132,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."_