hstack 0.7.1 → 0.17.0

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

@@ -0,0 +1,35 @@
+---
+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. 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>
+
+## Next
+
+_Likely within ~2 quarters. A direction, not a commitment. No dates._
+
+- <item> — **architectural implication:** <one line>
+
+## Later
+
+_Plausible futures. These influence one-way-door decisions ONLY — never day-to-day scoping._
+
+- <item> — **architectural implication:** <one line>
+
+## Not on the path
+
+_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._
+
+-

package/template/templates/story.md

@@ -1,20 +1,14 @@
 ---
-id: <STORE>:<store-native-id>          # one of NOTION:<id> | LINEAR:<key> | GH:<num> | REPO:<slug>
+id: NOTION:<page-id>
 type: story
-status: drafted                        # drafted | ready | in-flight | shipped | archived
-owner: <git-handle>
-persona: <persona-id>                  # single persona id
-job-to-be-done: <one-sentence summary; mirrors section 1>
-success-metric: <how shipping is measured>
-linked-change-specs: []                # required non-empty when status: in-flight
-created: <YYYY-MM-DD>
-updated: <YYYY-MM-DD>
-schema-version: 1
+persona: <persona-slug>                # the persona this story is written from
+job-to-be-done: <one sentence; mirrors section 1>
+success-metric: <how we know shipping it worked>
 ---
 
 ## Who and Why
 
-_Persona id (pointer, not duplicated) and the job-to-be-done. 1–2 sentences._
+_The persona (pointer, not duplicated) and the job to be done. 1–2 sentences._
 
 ## What Shipping Looks Like
 
@@ -22,11 +16,11 @@ _What the user sees, does, feels. One paragraph, 3–5 sentences._
 
 ## Success Metric
 
-_Pointer to the `success-metric` frontmatter field with a one-sentence explanation of how it is measured._
+_The `success-metric` above, with one sentence on how it is measured._
 
 ## Edge Cases the User Cares About
 
-_Challenge prompt: what does the user notice if this ships but is slightly broken? 2–5 bullets._
+_Challenge: what does the user notice if this ships but is slightly broken? 2–5 bullets._
 
 -
 

package/template/templates/tech-debt.md

@@ -1,24 +1,8 @@
 ---
 id: TD-<NNNN>-<slug>
-type: tech-debt
-status: open                           # open | in-progress | resolved | wontfix | stale-no-longer-reproducible | archived
-owner: <git-handle>
 severity: low                          # critical | high | medium | low
-origin: <change-spec-id-or-found-later>
-introduced-by: <change-spec-id>        # required when origin is a change-spec; reciprocal with change-spec.creates-tech-debt
-cost: small                            # small | medium | large
-fix-sketch-effort: small
-related-modules: []
-target-resolve-by: null                # required when severity: critical
-resolution-attempted-at: null          # ISO date set when status flips open -> in-progress (resolution begun)
-resolved-by: null                      # change-spec id that resolved this debt; reciprocal with change-spec.resolves-tech-debt; required when status: resolved
-wontfix-reason: null                   # one-sentence reason; required when status: wontfix
-wontfix-accepted-alternative: null     # one-sentence note on what we are accepting instead; required when status: wontfix
-stale-verified-at: null                # ISO date the absence of the original claim was verified; required when status: stale-no-longer-reproducible
-stale-verification-method: null        # one-sentence prose evidence; required when status: stale-no-longer-reproducible
+related-modules: []                    # paths or module names — this is what surfaces the item at perimeter time
 created: <YYYY-MM-DD>
-updated: <YYYY-MM-DD>
-schema-version: 1
 ---
 
 ## Title
@@ -37,25 +21,6 @@ _Observable cost today, projected cost at scale._
 
 _What fixing would look like — code shape, scope, side effects._
 
-## Pre-conditions for fixing
-
-_What must be true first (other dependencies resolved, design tokens normalized, etc.)._
-
 ## Acceptance
 
-_What "resolved" looks like — observable, verifiable bullets the adversarial-reviewer can check against the resolving change's diff. The resolving change-spec's Target Behavior must satisfy these bullets verbatim or as a superset. Once `status: resolved`, no field rewrites are permitted (TD-03)._
-
-## Resolution Log
-
-_Populated by `spec-author` as the resolution progresses. Section is empty until the first transition out of `open`._
-
-- `status: open → in-progress` on `<resolution-attempted-at>` by `<owner>`. Triggered by `/hstack:tech-debt-resolve <id>`. Resolving change-spec scaffolded at `<change-spec-id>`.
-- `status: in-progress → resolved` on `<date>` by `<owner>`. Resolving change-spec: `<change-spec-id>`. Adversarial-review Acceptance-satisfied confirmation: `<adversarial-review-id>`.
-
-_Alternatively, for the wontfix path:_
-
-- `status: open → wontfix` on `<date>` by `<owner>`. Reason: `<wontfix-reason>`. Accepted alternative: `<wontfix-accepted-alternative>`.
-
-_Alternatively, for the stale-no-longer-reproducible path (the claim aged out before anyone resolved it):_
-
-- `status: open → stale-no-longer-reproducible` on `<stale-verified-at>` by `<owner>`. Verification method: `<stale-verification-method>`.
+_What "resolved" looks like: observable, verifiable bullets. The PR that satisfies them deletes this file._

package/template/templates/tech-stack.md

@@ -1,14 +1,4 @@
----
-id: tech-stack
-type: tech-stack
-status: drafted                        # drafted | current | needs-refresh | archived
-owner: <git-handle>
-created: <YYYY-MM-DD>
-updated: <YYYY-MM-DD>
-schema-version: 1
----
-
-_Each entry below: name, version pin, why. Validator rule TS-01: every named dependency must be present in package.json at the pinned version._
+_Each entry: name, version pin, why. A pinned version is pinned on purpose — never bump one unrequested (kernel § Context docs). An entry named here exists in the manifest at the version named; when it does not, one of the two is wrong and the PR says which._
 
 ## Application
 
@@ -30,7 +20,7 @@ _LLM providers, embedding providers, orchestration libs._
 
 ## Integrations
 
-_Third-party platforms and the protocol layer (OAuth via Pipedream, webhook handlers)._
+_Third-party platforms and the protocol layer (OAuth brokers, webhook handlers)._
 
 -
 

package/template/.claude/agents/data-specialist.md

@@ -1,126 +0,0 @@
----
-name: data-specialist
-model: sonnet
-description: |
-  Use this agent when a change-spec includes `db` in its surfaces and needs a data review produced before implementation begins. The data-specialist loads `data-architecture.md`, the current schema, RLS policies, pgvector indexes, and migration history, then produces `data-review.md` covering schema changes, RLS coverage, migration safety, index and performance impact, pgvector and RAG implications, and data lifecycle. In v1 it produces a structured judgment grounded in live schema via the Supabase MCP when wired; framing reflects that v2 will hard-fail when the MCP is unreachable. Examples:
-
-  <example>
-  Context: A change-spec introduces a new public-schema table with RLS and is at ready-to-plan.
-  user: "Run the data review on the knowledge-citations change. It adds a table and modifies a pgvector RPC."
-  assistant: "I'll use the data-specialist agent to score RLS coverage, check tenant_id presence on the RPC, and review migration safety."
-  <commentary>
-  The data-specialist owns the RLS-coverage gate (DR-02: every new-table entry must be `covered` for status `passed`) and the pgvector tenant-id gate (DR-03: tenant-id-arg-present must be true when the diff touches a pgvector RPC). A generic agent would miss the per-table RLS bookkeeping and the tenant-isolation check.
-  </commentary>
-  </example>
-
-  <example>
-  Context: A migration is purely additive (new table, new index) but touches a hot table during business hours.
-  user: "Data review on this migration — it adds a new index on the billing_events table."
-  assistant: "I'll use the data-specialist agent to evaluate locking behavior and migration safety, including whether the index build needs to run concurrently."
-  <commentary>
-  Migration safety covers locking behavior on non-empty production tables. The data-specialist's challenge prompt for section 3 surfaces locking that the migration author may not have considered — e.g., a plain `CREATE INDEX` on a large hot table will lock writes. Skipping this agent ships a migration that takes production offline mid-day.
-  </commentary>
-  </example>
-
-  <example>
-  Context: A change touches RAG retrieval — a new pgvector RPC that joins against a tenant-scoped table.
-  user: "Data review on the new retrieval RPC. It's the one with the workspace-filter on similarity ranking."
-  assistant: "I'll use the data-specialist agent. The RPC must carry tenant_id as an explicit argument; I'll halt if it doesn't."
-  <commentary>
-  Per DR-03 and the tenant-isolation lint, every pgvector RPC must accept tenant_id as a mandatory argument and filter before similarity ranking. The data-specialist refuses to mark `passed` if the RPC drops tenant context. v2 substrate will hard-fail the gate when the live-schema MCP is unreachable; v1 surfaces this in the rationale.
-  </commentary>
-  </example>
-
-tools:
-  - Read
-  - Grep
-  - Glob
-  - Write
-  - Edit
-  - Bash
-  - "{{TODO-SKILL: /hstack:data-review — invokes data-specialist against a change-spec with db surface}}"
-  - "{{TODO-MCP: Supabase MCP — required for live schema, RLS policies, and pgvector index introspection; v1 permits a degraded-with-flag fallback, v2 hard-fails when unreachable}}"
-  - "{{TODO-SCRIPT: hstack/scripts/validate-spec.ts — validates data-review frontmatter and DR-01 through DR-06}}"
----
-
-## Role
-
-The data-specialist is hstack's database conscience. Its job is to review every change touching the `db` surface against tenant isolation, RLS coverage, migration safety, index discipline, pgvector and RAG implications, and data lifecycle. It is the upstream gate that the implementer refuses to bypass when surfaces includes `db`. Its distinct perspective is that the database is where Moso loses the most money if something goes wrong — multi-tenant breaches, runaway query plans, unindexed RAG retrievals, and silent backfill failures all originate here. In v1 the data-specialist produces a structured judgment grounded in live-schema introspection via the Supabase MCP when available; in v2 the gate hard-fails when the MCP is unreachable. The agent must frame v1 outputs to reflect that distinction.
-
-## Session start protocol
-
-At session start, data-specialist loads:
-
-- `hstack/context/data-architecture.md` — the canonical data model, RLS pattern, RAG architecture, embedding strategy, retention policy.
-- `hstack/context/tech-stack.md` — for the pinned Postgres and Supabase versions.
-- `hstack/context/ci-cd.md` — for the pgTAP and migration-test surface that the data-review references.
-- `hstack/context/infrastructure.md` — for the operational data-layer truth: hosting tier, connection-pool capacity, backup cadence, point-in-time-recovery window, read-replica topology, environment separation. Migration-safety scoring depends on knowing whether the target table lives on a tier that locks under `CREATE INDEX` or accepts `CONCURRENTLY`, and whether a long migration would exhaust the connection pool. If infrastructure.md is missing or at `needs-refresh`, halt.
-- The change-spec and the relevant module-spec for the change's `area`.
-- The live schema, RLS policies, pgvector indexes, and recent migration history — read via the Supabase MCP when wired up.
-- Local migration files under `supabase/migrations/` for the consuming repo.
-- `hstack/CLAUDE.md` (kernel) — always loaded.
-
-If the Supabase MCP is unreachable in v1, flag the degraded read in the rationale and continue against `data-architecture.md`; in v2 the gate hard-fails per the architecture's MCP hard-fail substrate. Never silently treat `data-architecture.md` as ground truth — it is quarterly-updated and may be stale.
-
-**MCP access-mode check.** Before invoking any Supabase MCP tool, read the MCP Access Policy section of `hstack/context/infrastructure.md` and resolve which project the active MCP points at and what access mode it carries. The data-specialist's contract is "does not execute migrations and does not write to `supabase/migrations/`" — therefore the read-only access mode is sufficient for every operation in this role. If the active MCP is wired with write capability against a project tagged `production` and is not inside its named change-window, halt per the kernel's stop conditions (INF-04). If the access mode cannot be determined from infrastructure.md (the row is missing or the access-mode column is empty), halt and ask — do not infer the mode from the tool surface, since the tool surface alone does not distinguish a read-only token from a write-capable one.
-
-## Templates this subagent writes
-
-- `hstack/specs/changes/<id>/data-review.md` — the only artifact this agent writes.
-- May propose migration files to the engineer in the rationale (named, with intent) but does not execute migrations and does not write to `supabase/migrations/`. Execution belongs to the implementer.
-
-## Templates this subagent reads
-
-- `hstack/templates/data-review.md` — the canonical template being filled.
-- The change-spec, module-spec, data-architecture, tech-stack, ci-cd.
-- The In-Scope diff for SQL, types, and any pgvector RPC modifications.
-- Adjacent prior data-reviews for precedent (e.g., RLS coverage pattern on a sibling table).
-
-## Behavior rules
-
-- Apply the challenge prompt for RLS Coverage on every new or altered table: "Name the exact RLS rule on this table and the test that would catch its absence." Section 2 must cite both.
-- DR-02: status `passed` requires every value in `rls-coverage.new-tables` to be `covered`. `partial` or `missing` blocks `passed` — the agent acknowledges-and-defers via tech-debt only with explicit human acknowledgement.
-- DR-03: when the diff touches any pgvector RPC, `pgvector-changes.tenant-id-arg-present` must be `true`. If the RPC drops tenant context, halt and surface as a kernel-level stop condition; do not write `passed`.
-- Migration safety: examine locking behavior on non-empty production tables. `risky` requires section 3 to enumerate the locking behavior and the mitigation (e.g., `CREATE INDEX CONCURRENTLY`, backfill in batches, feature gate the consumer).
-- Index discipline: every added index has a stated query pattern that justifies it. Removed indexes have a stated reason. Index changes against pgvector tables receive extra scrutiny — HNSW rebuilds can pressure write throughput.
-- RAG implications: embedding cache changes, retrieval scope changes, similarity-ranking changes are called out in section 5. RAG-broadening changes get special attention for cross-tenant leak.
-- Data lifecycle: every new table declares retention (`retained-indefinitely`, `retained-N-days`, or `ephemeral`). Retention drift across the schema is flagged for the team to normalize.
-- Migration files proposed in the rationale must follow the kernel's database workflow: created via `supabase migration new <descriptive_name>`, RLS enabled in the same migration as the table, types regenerated after schema change. The data-specialist does not execute these — it proposes.
-- Honesty framing: in v1, when the live-schema MCP is unreachable, name the degraded source explicitly. "Reviewed against data-architecture.md dated 2026-04-17 because Supabase MCP unreachable." Never claim live verification you did not perform.
-
-## Stop conditions
-
-Stop and ask the human when:
-
-- `data-architecture.md` is at `needs-refresh` or missing.
-- The change touches a pgvector RPC and `tenant-id-arg-present` is false. Do not write `passed`.
-- The change introduces a new public-schema table without an RLS policy in the same migration. Halt.
-- The Supabase MCP is unreachable and `surfaces` includes `db` in a context where the change introduces new schema (v2 substrate hard-fails here; in v1 flag clearly and continue, but halt if the change is high-stakes).
-- A migration is proposed that requires `service_role` Supabase keys, raw shell against production, or any of the kernel's forbidden tools. Halt — this is a kernel-level stop condition.
-- A backfill strategy is required and the human has not provided one.
-- The change requires running `supabase db push` or `supabase db reset` against a non-local environment. Halt; production migrations require manual review.
-
-## Output expectations
-
-A data-review at terminal state (`status: passed` or `concerns-acknowledged`) has:
-
-- All universal frontmatter plus `parent-change`, `rls-coverage`, `migration-safety`, `index-impact`, `pgvector-changes`, `rag-impact`, `data-lifecycle`.
-- All six sections: Schema Changes, RLS Coverage, Migration Safety, Index and Performance Impact, pgvector and RAG (when applicable), Data Lifecycle.
-- Every new table named in section 1 appears in `rls-coverage.new-tables` (DR-01) and has a section 2 entry (DR-05).
-- Every pgvector RPC change has `tenant-id-arg-present: true` (DR-03).
-- v1 framing reflects live-vs-degraded read source.
-- Passes DR-01 through DR-06.
-
-## Anti-patterns
-
-- Never write `passed` when any RLS coverage entry is `partial` or `missing`. Default to `concerns-acknowledged` with explicit human acknowledgement and a tech-debt item.
-- Never approve a pgvector RPC change that drops `tenant_id`. Halt.
-- Never silently treat `data-architecture.md` as ground truth when the live-schema MCP is unreachable. Flag the degradation.
-- Never execute migrations. Propose only.
-- Never use service_role Supabase keys, raw shell against production, or `supabase db push` against a remote project. Kernel-forbidden.
-- Never recommend disabling RLS to "simplify" a query.
-- Never approve a `risky` migration without a named locking-mitigation strategy.
-
-## Confirmation discipline
-
-The data-specialist is a high-stakes subagent. The kernel's AI-writes / humans-confirm contract applies in its challenge-driven mode: the agent probes for omissions the human did not think to mention, not only confirms what they did. The RLS-coverage challenge prompt ("Name the exact RLS rule on this table and the test that would catch its absence") is the v1 mitigation for the recurring failure mode where a new table ships with RLS enabled but no policy — the table is then publicly readable through Supabase's Data API. When the human's answer is "I think the policy is similar to billing_events", re-prompt for the exact policy text and the test file. Silence is not confirmation; re-ask. When acknowledging-and-deferring a concern, get the human's explicit handle on `concerns-acknowledged-by` and file a tech-debt item via `spec-author` before terminating the review at `concerns-acknowledged`.