hstack 0.16.0 → 0.17.0

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,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."_

package/template/templates/infrastructure.md

@@ -1,190 +1,96 @@
----
-id: infrastructure
-type: infrastructure
-status: drafted                        # drafted | current | needs-refresh | archived
-owner: <git-handle>
-last-quarterly-review: <YYYY-MM-DD>
-created: <YYYY-MM-DD>
-updated: <YYYY-MM-DD>
-schema-version: 1
----
+_Where things run, why the couplings are what they are, and the traps. Operational truth, not policy — read it before touching env, deploy or dependencies (kernel § Context docs), and update it in the PR that makes it wrong. An honest "we don't have this yet" is the right answer whenever it is the true one._
 
-_Operational truth about how the consuming repo's product runs. Truth-gathering, not policy — `threat-model.md` and `hardening-checklist.md` carry the policy. This file is what `security-reviewer`, `data-specialist`, and any future `infra-specialist` read to ground change-time review in the system's actual shape. Length norm: 600–1500 lines once filled; shorter is honest for pre-prod, longer is a smell. Every H2 below must be present (validator rule INF-01); the Unknowns section must be present even when empty (INF-02); the Blast-Radius Matrix must list at least one row when status moves to `current` (INF-03); no MCP server may be wired with always-on write capability against prod (INF-04); LLM-driven sessions with a write-capable MCP active must not read user-generated content in the same session (INF-05)._
+## Where things run
 
-## Hosting & Compute
+_One row per distinct runtime — app, edge functions, workers, cron, queue consumers. Names copied from the provider console, not paraphrased._
 
-_Where each runtime lives. Provider, region(s), service tier/plan, instance class or function memory. Names must match the cloud console exactly — copy them, do not paraphrase. One row per distinct runtime (app, edge functions, workers, cron, queue consumers)._
-
-| Runtime | Provider | Region(s) | Tier / Plan | Notes |
+| Runtime | Provider | Region(s) | Plan / tier | Notes |
 |---|---|---|---|---|
 | | | | | |
 
-## Networking
-
-_DNS provider and zone, custom domains, TLS/SSL provisioning, CDN / edge cache, load balancing, ingress rules. Note which records are managed in code (IaC) vs the provider console._
-
-- **DNS provider.**
-- **Domains in use.**
-- **TLS provisioning.**
-- **CDN / edge.**
-- **Load balancing.**
-- **Egress controls.**
+- **Domains, DNS, TLS, CDN.**
+- **Declared in code vs clicked in a console.** List the clicked resources explicitly — each one is a load-bearing piece of tribal knowledge.
 
-## Data Layer
+## Data & storage
 
-_Database hosting, connection pooling, backup cadence, point-in-time recovery window, read replicas, retention policy. Defers schema and RLS to `data-architecture.md`; this section is operational (where and how, not what)._
+_Operational only. Schema, tenancy and RLS live in `data-architecture.md`._
 
-- **Primary database.**
-- **Connection pooling.**
-- **Backups.**
-- **Point-in-time recovery.**
+- **Primary database** — host, plan, connection pooling.
+- **Backups** — cadence, retention, point-in-time-recovery window.
+- **Last restore drill** — date, and what it proved. An untested backup is a wish.
 - **Replicas / failover.**
-- **Retention.**
-- **Vector / search infrastructure.**
-
-## Storage
-
-_Object storage, file uploads, presigned-URL flows, lifecycle and retention. One row per bucket / container._
-
-| Bucket | Provider | Purpose | Public? | Lifecycle | Notes |
-|---|---|---|---|---|---|
-| | | | | | |
-
-## Secrets & Configuration
-
-_Where secrets live, how they are injected at runtime, rotation cadence, who has access. **The runbook for rotation lives in `incident-runbook.md`; this section names the system, not the steps.**_
-
-- **Secret store.**
-- **Injection mechanism.**
-- **Rotation cadence.**
-- **Access control.**
-- **Audit trail.**
-
-## Environment Separation
-
-_What dev, staging (if present), and production look like, and what differs between them. Data-promotion rules (does prod data ever flow downstream? if so, with what redaction?). Connection-string isolation. **Test-against-prod is a kernel-level forbidden tool; flag any violation here as tech-debt.**_
-
-- **Dev.**
-- **Staging.**
-- **Production.**
-- **Data-promotion rules.**
-- **Cross-environment guardrails.**
-
-## IaC Inventory
-
-_What infrastructure is declared in code vs configured by click in a console. Path to IaC files. Tool (Terraform, Pulumi, CDK, OpenTofu, Supabase migrations, GitHub Actions YAML, Dockerfile). Who can apply. **Click-configured infra is not forbidden, but every clicked resource is a load-bearing tribal-knowledge item; list each one explicitly so it can be promoted to IaC over time.**_
-
-| Resource | Source-of-truth | Path / location | Applier(s) | Notes |
-|---|---|---|---|---|
-| | | | | |
-
-## Deploy Pipeline
-
-_How code reaches each environment. References `ci-cd.md` for the build pipeline; this section captures the deploy half — promotion mechanics, rollout strategy (instant cutover, canary, blue/green), rollback procedure, who can trigger a deploy._
-
-- **Build → deploy handoff.**
-- **Promotion path.**
-- **Rollout strategy.**
-- **Rollback procedure.**
-- **Deploy authorization.**
-
-## Observability
+- **Vector or search infrastructure.**
+- **Buckets** — one line each: purpose, public or not, lifecycle.
 
-_Logs, metrics, traces, error tracking, uptime monitoring. Where each lives, retention window, who reads them. Alert routing — which alerts wake whom, on which channel. **An observability gap is a production-readiness gap; an honest "we don't have this yet" entry is the right answer when true.**_
+## Environments
 
-- **Logs.**
-- **Metrics.**
-- **Traces.**
-- **Error tracking.**
-- **Uptime monitoring.**
-- **Alert routing.**
-
-## Cost & Capacity
-
-_Current monthly spend per service (approximate is fine). Budget alerts. Scaling triggers and ceilings. Rate-limiting posture (per-route, per-tenant). **Cost is a security and reliability concern, not just a finance concern: an unbounded scale ceiling is a billing-DoS vector.**_
+_What dev, preview and production are, and what actually differs between them._
 
-| Service | Monthly spend (approx) | Budget alert at | Scale ceiling | Notes |
+| Environment | App URL | Database it points at | Seed data | Notes |
 |---|---|---|---|---|
 | | | | | |
 
-- **Rate limits.**
-- **Per-tenant quotas.**
+- **Source of truth for environment variables**, and how they are scoped per environment.
+- **Does production data ever flow downstream?** If so, with what redaction.
+- **Cross-environment guardrails.** Testing against production is a kernel-forbidden path; a violation found here is a tech-debt file, not a footnote.
 
-## Disaster Recovery
-
-_Recovery Point Objective (RPO) and Recovery Time Objective (RTO) targets per critical resource. Backup restore procedure (high level — full steps live in `incident-runbook.md`). Drill cadence — when was the last successful restore test, and when is the next scheduled. **An untested backup is a wish, not a recovery plan.**_
-
-| Resource | RPO target | RTO target | Last drill | Next drill |
-|---|---|---|---|---|
-| | | | | |
+## Secrets
 
-## Blast-Radius Matrix
+- **Where they live.** The one store that is authoritative.
+- **How they reach the runtime.**
+- **Who has access**, and how that is reviewed.
+- **Rotation** — cadence, and where the steps are written down.
 
-_Per critical resource: what depends on it, what dies if it dies, and who is notified. This is the table that `security-reviewer` reads when scoring an infra-surface change; it must list at least one row when status moves to `current` (INF-03)._
+## Deploy Pipeline
 
-| Resource | Depends on | What dies if this dies | Notification path | Mitigation |
-|---|---|---|---|---|
-| | | | | |
+_How code reaches production, and the exact commands `/hstack-promote` will look for here. A command left blank halts the promotion — which is the correct outcome, because guessing a production command is how the wrong project gets migrated._
 
-## Access & Change Control
+| What `/hstack-promote` needs | Command |
+|---|---|
+| Apply a pending migration to production | |
+| List deployments and their state | |
+| Smoke-test a specific deployment URL | |
+| Read production logs | |
+| Promote a deployment | |
+| Roll back to the previous deployment | |
 
-_Who has production console access per provider. MFA enforcement. Audit log location and retention. Deploy authorization — who can push to prod, who can apply IaC, who can rotate secrets. **The principle of least privilege applies here; list humans by name and access scope, not role abstractions.**_
+- **Promotion path.** How a merge becomes an unpromoted production build, and what promotes it. Auto-assignment of the production domain must be off for the staged flow to exist at all.
+- **Who may promote.**
+- **Rollback.** What re-promoting the previous deployment does and does not undo — migrations are additive, so they stay.
 
-| Human | Provider | Scope | MFA enforced | Last access review |
-|---|---|---|---|---|
-| | | | | |
+## Observability
 
-- **Audit log location.**
-- **Audit log retention.**
-- **Access review cadence.**
+_Where `/hstack-promote` looks in its post-promotion window, and where a daily glance happens._
 
-## MCP Access Policy
+- **Logs** — where, retention.
+- **Error tracking** — tool, project, who watches it.
+- **Uptime monitoring.**
+- **Alert routing** — which alert reaches whom, on which channel. "Nobody is paged" is an answer; write it down rather than implying one.
 
-_Which MCP servers are wired, where they point, what they can do. MCP access is a security boundary equivalent to the access token it carries — an LLM-driven session with tool access to a project-scoped token has the project's full blast radius. The kernel already forbids `service_role` Supabase keys and `supabase db push` / `db reset` against remote environments; MCP write access against prod is the analogous capability and follows the same rule. One row per MCP server per project it points at._
+## Couplings & gotchas
 
-| MCP server | Wired at | Points at | Access mode | Token storage | Rotation cadence | Notes |
-|---|---|---|---|---|---|---|
-| | | | | | | |
+_The section that earns this file. Everything a newcomer — human or agent — would otherwise learn by breaking production: a region that must match another region, a version pinned because the next one broke us, a service that must be deployed before another, a quota that bites at a specific hour._
 
-**Rule (INF-04).** No MCP server may be wired with write capability against the production project. Read-only mode (the server's `--read-only` flag or equivalent) is the floor for any MCP that points at prod. When a write-capable MCP must exist against prod for an operational reason (one-off migration applied through the MCP, e.g.), the row above carries a `--write-justified-by: <change-spec-id or ADR id>` note and the MCP is disabled by default — enabled only inside the named change window, then immediately disabled. Always-on write-capable prod MCPs are forbidden.
+-
 
-**Rule (INF-05).** Any LLM-driven session that has a write-capable MCP tool active must not, in the same session, read user-generated content from a tenant-scoped table. This is the prompt-injection mitigation: prevents stored content (customer support rows, webhook payloads, user-submitted fields) from steering the LLM into destructive tool calls. List each session pattern below — subagent name, Skill, or ad-hoc — and which side of this boundary it sits on.
+_External services this depends on at runtime. Criticality: `hard` = the product is down, `soft` = degraded, `optional` = no user impact._
 
-| Session pattern | Write-capable MCP tools active? | Reads tenant-scoped content? | Compliant? |
+| Provider | Purpose | Criticality | What happens when it is down |
 |---|---|---|---|
 | | | | |
 
-**Per-MCP detail.**
-
-- **Supabase MCP.** Dev project, staging project, production project — each on its own row. "Not wired" is an acceptable and often preferred value, especially for production.
-- **Other MCPs** (Notion, GitHub, Linear, Figma, Slack, etc.). Each with its own access scope, token location, rotation. Notion and Slack MCPs in particular often surface external user-generated content into the session — flag them explicitly under INF-05.
-
-## Compliance & Data Residency
-
-_Regions where customer data lives at rest. GDPR-relevant flows (subject-access, deletion, export). Encryption at rest and in transit per data class. SOC 2 readiness gaps (this is honest enumeration, not a claim of posture). **v1 hstack does not by itself deliver SOC 2 or GDPR posture; the kernel says so explicitly. This section catalogs the gap, it does not close it.**_
+## MCP access
 
-- **Data residency.**
-- **GDPR flows.**
-- **Encryption at rest.**
-- **Encryption in transit.**
-- **Known compliance gaps.**
+_Which MCP servers are wired, where they point, what they can do. An MCP is a security boundary equivalent to the token it carries: a session with a project-scoped token has that project's full blast radius. The rules — no write-capable MCP against production outside `/hstack-promote`, and no write-capable MCP active in a session that reads user-generated tenant-scoped content — belong to the kernel § Stop conditions. This table is the inventory those rules are applied to._
 
-## Third-party Dependencies
-
-_External SaaS the system depends on at runtime. One row per provider. Criticality reflects what happens if the provider is unavailable: `hard` = product is down, `soft` = degraded, `optional` = no user impact._
-
-| Provider | Purpose | Criticality | Contractual SLO | Failure-mode behavior |
+| MCP server | Points at | Access mode | Token storage | Notes |
 |---|---|---|---|---|
 | | | | | |
 
-## Known Gaps
-
-_Open tech-debt items pointing to infrastructure shortcomings. Each entry is a link to a `hstack/tech-debt/TD-NNNN-<slug>.md` file. This section is the bridge between the operational truth captured above and the workflow's tech-debt machinery — every honest gap surfaced during the interview should land as a TD via `/hstack:tech-debt-new --origin <change-id>`._
-
--
+_"Not wired" is an acceptable value, and often the preferred one for production._
 
-## Unknowns
+## Known gaps
 
-_Challenge prompt: what infrastructure dependency does the team not yet have a documented mitigation for? Name the dependency, name the failure mode, name the gap. This section must be present even when empty, to make the absence explicit (validator rule INF-02)._
+_What is missing or unknown, named rather than implied. A gap with a shape is a file under `hstack/tech-debt/`; link it here. A gap without one — a dependency whose failure mode nobody has thought through — is a line here until someone does._
 
 -

package/template/templates/roadmap.md

@@ -1,18 +1,12 @@
 ---
-id: roadmap
-type: roadmap
-status: drafted                        # drafted | current | needs-refresh | archived
-owner: <git-handle>
-source: local                          # local | rhizome — who owns the truth; when rhizome, local edits are refused and the sync is authoritative
-reviewed-on: <YYYY-MM-DD>              # planner treats the roadmap as stale beyond 90 days
-created: <YYYY-MM-DD>
-updated: <YYYY-MM-DD>
-schema-version: 1
+reviewed-on: <YYYY-MM-DD>              # past 90 days, treat this roadmap as stale rather than current
 ---
 
+_Advisory only, never a gate (kernel § Context docs). It informs one-way-door decisions and the Forecloses / Enables section of an ADR; it never decides whether a change ships._
+
 ## Now
 
-_What we are committed to shipping. During the MVP phase, Now IS the MVP scope. Each item: one product line, one architectural-implication line. Implications are proposed by app-architect / data-architect and confirmed by the engineer — vague fortune-telling ("might need to scale") is worse than absence._
+_What we are committed to shipping. Each item: one product line, one architectural-implication line. Vague fortune-telling ("might need to scale") is worse than absence._
 
 - <item> — **architectural implication:** <one line>
 
@@ -30,12 +24,12 @@ _Plausible futures. These influence one-way-door decisions ONLY — never day-to
 
 ## Not on the path
 
-_Explicit renouncements, with the reason. Absorbs the old "Deferred" list._
+_Explicit renouncements, with the reason._
 
 - <item> — <why not>
 
 ## Success criteria for the current horizon
 
-_Concrete observable indicators that Now is done and Next gets promoted. Bullets._
+_Concrete observable indicators that Now is done and Next gets promoted._
 
 -