hstack 0.1.0

package/template/templates/adversarial-review.md

@@ -0,0 +1,54 @@
+---
+id: <parent-change-id>-adversarial-review
+type: adversarial-review
+status: draft                          # draft | in-progress | findings-open | findings-resolved | superseded
+owner: <git-handle>
+parent-change: <change-spec-id>
+findings-floor: 3                      # 3 default; 5 when change-spec.area in {agent, auth, billing}
+findings: []                           # array of finding records; see below
+findings-fewer-than-floor: false
+justification-when-fewer: null         # required when findings-fewer-than-floor: true
+fresh-session-attestation: <session-id; opened <ISO-8601>; no implementer transcript loaded>
+created: <YYYY-MM-DD>
+updated: <YYYY-MM-DD>
+schema-version: 1
+---
+
+<!--
+Finding record shape:
+  - id: F-NN
+    category: security | scope-drift | invariant-breach | spec-compliance | data-integrity | code-quality
+    severity: critical | high | medium | low
+    status: open | resolved
+    resolution: commit:<hash> | tech-debt:<id> | justified-in-prose
+-->
+
+## Methodology
+
+_Fresh-session attestation; what artifacts were loaded; how findings were generated. v1 honor system; v2 verifies via session-id._
+
+## Findings
+
+_One subsection per finding (F-01..F-N). Mandate: at least `findings-floor` findings across categories, or `findings-fewer-than-floor: true` with justification._
+
+### F-01
+
+**Category.**
+
+**What.** _The observation. 1–3 sentences._
+
+**Why it matters.** _The consequence if left unaddressed._
+
+**Severity rationale.**
+
+**Recommendation.**
+
+**Resolution.** _Commit hash, tech-debt id, or in-prose justification — must mirror the `resolution` value in frontmatter._
+
+## Resolution Log
+
+_Append-only record of how each finding was resolved. Written by `owner` in response to findings._
+
+## Findings Floor Justification
+
+_Populated only when `findings-fewer-than-floor: true`. Explain why fewer than the floor is the honest answer._

package/template/templates/change-spec.md

@@ -0,0 +1,80 @@
+---
+id: <YYYY-MM-area-slug>
+type: change-spec
+status: draft
+owner: <git-handle>
+area: <module-spec-id>
+surfaces: []                           # subset of [ui, api, db, infra, agent]
+user-stories: []
+related-spec: <module-spec-id>         # must equal `area`
+related-adrs: []
+creates-tech-debt: []
+resolves-tech-debt: []                 # tech-debt ids this change is intended to fully resolve; reciprocal with tech-debt.resolved-by
+parent-change: null
+children: []
+revisits-change: []                    # change-spec ids this change is filed to repair (defects, regressions, missed findings). Informational, not gating.
+internal-tooling: false
+trivial: false
+in-scope: []                           # repo-relative globs; must be non-empty
+out-of-scope: []                       # required, may be empty
+threat-model-delta: false              # set true when surfaces touches agent | auth | api | db
+created: <YYYY-MM-DD>
+updated: <YYYY-MM-DD>
+schema-version: 1
+---
+
+## Problem
+
+_What is broken or missing today, in user terms. One paragraph, 4–6 sentences._
+
+## Current Behavior
+
+_Observable behavior as it stands, including known gotchas. You may grep the In-Scope files to verify. 2–4 bullets._
+
+-
+
+## Target Behavior
+
+_What shipping looks like, observably. 2–4 bullets._
+
+-
+
+## Acceptance Criteria
+
+_GIVEN / WHEN / THEN form. At least one block per surface declared. Reviewed by product-manager when `surfaces` includes `ui`._
+
+GIVEN
+WHEN
+THEN
+
+## Invariants
+
+_Name at least three things that look like they could change but must not. If you cannot name three, why is the change so narrow? (Validator rule SP-04.)_
+
+-
+-
+-
+
+## Scope Boundaries
+
+_Pointer to `in-scope` and `out-of-scope` frontmatter arrays. One-sentence justification per excluded sibling directory._
+
+## Surfaces
+
+_Pointer to `surfaces` frontmatter. One sentence per surface explaining what is touched._
+
+## Linked Stories and Personas
+
+_Pointers, not duplicated content._
+
+## Related ADRs and Tech-Debt
+
+_Pointers with one-sentence justification each._
+
+## Resolves Tech-Debt
+
+_Required and non-empty when `resolves-tech-debt` frontmatter is non-empty. For each TD-NNNN referenced: a pointer to the tech-debt artifact and a verbatim quote of its Acceptance section. The change-spec's Target Behavior must be a superset of (or exactly) the quoted Acceptance — the adversarial-reviewer checks that the diff actually satisfies it. Partial resolution is not supported in v1: list a TD here only when this change fully closes it; otherwise leave it off and let the next change pick it up._
+
+## Open Questions
+
+_Populated when status moves from draft to ready-to-plan. Every question must be resolved or explicitly punted before ready-for-implementation._

package/template/templates/ci-cd.md

@@ -0,0 +1,27 @@
+---
+id: ci-cd
+type: ci-cd
+status: drafted                        # drafted | current | needs-refresh | archived
+owner: <git-handle>
+created: <YYYY-MM-DD>
+updated: <YYYY-MM-DD>
+schema-version: 1
+---
+
+## Branch model
+
+_main, integrations, change/* — what each branch is for. Branch naming convention mirrors change-spec id._
+
+## Gates
+
+_Every check in `.github/workflows/hstack-gates.yml` plus pre-existing CI checks. Validator rule CI-01: every gate named in the workflow file must appear here._
+
+-
+
+## Deploy targets
+
+_Preview, staging, production. What promotes to what. Manual vs automatic._
+
+## Rollback
+
+_How to revert a bad deploy. Feature flags vs git revert vs DB migration rollback. Reference incident-runbook for production paths._

package/template/templates/data-architecture.md

@@ -0,0 +1,35 @@
+---
+id: data-architecture
+type: data-architecture
+status: drafted                        # drafted | current | needs-refresh | archived
+owner: <git-handle>
+schema-snapshot-date: <YYYY-MM-DD>
+rag-architecture-version: 1
+created: <YYYY-MM-DD>
+updated: <YYYY-MM-DD>
+schema-version: 1
+---
+
+## Tables and relationships
+
+_ER diagram in mermaid or prose. The canonical tables, columns of interest, and foreign-key relationships._
+
+## RLS model
+
+_The universal pattern + per-table deviations. Validator rule DA-01: this section must contain the word "RLS" in a heading._
+
+## RAG and embeddings
+
+_Where embeddings live, how retrieval is scoped, what the cache looks like, how tenant_id is enforced on every RPC._
+
+## Data lifecycle
+
+_Retention, archival, deletion. Per-table policies._
+
+## External data sources
+
+_Third-party integrations that write to our store. Webhook signature verification posture._
+
+## Conventions
+
+_Naming, soft-deletes vs hard-deletes, audit fields, timestamp conventions, UUID vs serial._

package/template/templates/data-review.md

@@ -0,0 +1,54 @@
+---
+id: <parent-change-id>-data-review
+type: data-review
+status: draft                          # draft | in-progress | passed | concerns-acknowledged | failed | superseded
+owner: <git-handle>
+parent-change: <change-spec-id>
+rls-coverage:
+  new-tables: {}                       # { <table_name>: covered | partial | missing }
+migration-safety: safe                 # safe | needs-backfill | risky
+index-impact:
+  added: []
+  removed: []
+pgvector-changes:
+  rpcs-modified: []
+  tenant-id-arg-present: true          # required true when any pgvector RPC is in the diff
+rag-impact: none                       # scoped | broadened | narrowed | none
+data-lifecycle: retained-indefinitely  # retained-indefinitely | retained-N-days | ephemeral
+created: <YYYY-MM-DD>
+updated: <YYYY-MM-DD>
+schema-version: 1
+---
+
+## Schema Changes
+
+_Every table created, altered, or dropped; every column added, renamed, or dropped._
+
+## RLS Coverage
+
+_For every new or altered table: the policy and the test that verifies it. Challenge prompt: name the exact RLS rule on this table and the test that would catch its absence._
+
+### <table-name>
+
+**Policy.**
+
+```sql
+```
+
+**Test.**
+
+## Migration Safety
+
+_What the migration does on a non-empty production table. Locking behavior. Backfill plan if any. When `migration-safety: risky`, this section must enumerate locking and mitigation (DR-04)._
+
+## Index and Performance Impact
+
+_Indexes added or removed. Expected query patterns. Expected row counts at 1 month, 1 year._
+
+## pgvector and RAG
+
+_Required when any pgvector RPC is in the diff. RPCs touched, tenant_id presence, embedding cache implications._
+
+## Data Lifecycle
+
+_Retention, expiry, archival. Pointer to `data-lifecycle` frontmatter with rationale._

package/template/templates/figma-handoff.md

@@ -0,0 +1,38 @@
+---
+id: <parent-change-id>-figma
+type: figma-handoff
+status: draft                          # draft | ready | superseded
+owner: <cofounder-handle>
+parent-change: <change-spec-id>
+figma-frame-urls: []                   # list of Figma frame URLs
+design-system-version: <version>       # must match parent ui-brief.design-system-version
+created: <YYYY-MM-DD>
+updated: <YYYY-MM-DD>
+schema-version: 1
+---
+
+## Frame Index
+
+_Table of frame URLs with state descriptions. Three columns max._
+
+| state | frame URL | notes |
+| --- | --- | --- |
+|  |  |  |
+
+## Implementation Notes
+
+_Anything the engineer needs to know that Figma cannot encode: animation timings, conditional rendering, copy fallbacks._
+
+## Open Questions
+
+_Anything the cofounder is uncertain about. Resolve before status: ready._
+
+## Tokens Used
+
+_Design tokens consumed. Flag any new tokens introduced — they belong in the design system, not in this change._
+
+-
+
+## Sign-off
+
+_Cofounder confirms screens are final. Initials + date._

package/template/templates/glossary.md

@@ -0,0 +1,20 @@
+---
+id: glossary
+type: glossary
+status: drafted                        # drafted | current | needs-refresh | archived
+owner: <git-handle>
+term-count: 0                          # must match the number of term subsections in the body
+created: <YYYY-MM-DD>
+updated: <YYYY-MM-DD>
+schema-version: 1
+---
+
+_Terms with non-obvious meaning in the product. One subsection per term, alphabetical order. Each term: one-paragraph definition, one or more examples, cross-references to other terms or modules. Length cap: two paragraphs per term. Update `term-count` whenever a term is added or removed (validator rule GL-01)._
+
+## <Term>
+
+**Definition.**
+
+**Example.**
+
+**See also.**

package/template/templates/hardening-checklist.md

@@ -0,0 +1,73 @@
+---
+id: hardening-checklist
+type: hardening-checklist
+status: drafted                        # drafted | current | needs-refresh | archived
+owner: <git-handle>
+last-quarterly-review: <YYYY-MM-DD>
+layer-count: 10
+created: <YYYY-MM-DD>
+updated: <YYYY-MM-DD>
+schema-version: 1
+---
+
+_One section per layer. Each layer enumerates items with: item id, what it asserts, evidence required, not-applicable conditions. This is the artifact `security-review.md` scores against item-by-item. Validator rule HC-01: every layer that appears in a security-review `scores` map must exist as a section here._
+
+## data-at-rest
+
+### Item HC-DAR-01: <assertion>
+**Evidence required.**
+**Not-applicable when.**
+
+## data-in-transit
+
+### Item HC-DIT-01: <assertion>
+**Evidence required.**
+**Not-applicable when.**
+
+## authn
+
+### Item HC-AN-01: <assertion>
+**Evidence required.**
+**Not-applicable when.**
+
+## authz-rls
+
+### Item HC-AZ-01: <assertion>
+**Evidence required.**
+**Not-applicable when.**
+
+## tenant-isolation
+
+### Item HC-TI-01: <assertion>
+**Evidence required.**
+**Not-applicable when.**
+
+## input-validation
+
+### Item HC-IV-01: <assertion>
+**Evidence required.**
+**Not-applicable when.**
+
+## output-encoding
+
+### Item HC-OE-01: <assertion>
+**Evidence required.**
+**Not-applicable when.**
+
+## secrets-handling
+
+### Item HC-SH-01: <assertion>
+**Evidence required.**
+**Not-applicable when.**
+
+## agent-prompt-injection
+
+### Item HC-API-01: <assertion>
+**Evidence required.**
+**Not-applicable when.**
+
+## audit-logging
+
+### Item HC-AL-01: <assertion>
+**Evidence required.**
+**Not-applicable when.**

package/template/templates/incident-runbook.md

@@ -0,0 +1,57 @@
+---
+id: incident-runbook
+type: incident-runbook
+status: drafted                        # drafted | current | needs-refresh | archived
+owner: <git-handle>
+git-ignored: true                      # this file MUST be gitignored; sensitive content
+last-quarterly-review: <YYYY-MM-DD>
+created: <YYYY-MM-DD>
+updated: <YYYY-MM-DD>
+schema-version: 1
+---
+
+<!--
+WARNING: This file contains sensitive operational content (auth provider details, revocation endpoints,
+customer communication templates, phone tree). It MUST be gitignored. Per architecture amendment A7,
+the file lives locally and is synced to an out-of-band destination configured in hstack/config.yaml as
+`incident-runbook.sync-target`. Auto-commit does not apply to this file. The init Skill must add the
+entry to .gitignore as part of bootstrap.
+-->
+
+## Kill switches
+
+_Feature flags and how to flip them, ordered by blast radius. Most-dangerous-first._
+
+-
+
+## Revocation flows
+
+_Per third-party: Stripe, Supabase, Pipedream, MCPs. Steps to revoke a session, an OAuth token, an API key._
+
+### Stripe
+
+### Supabase
+
+### Pipedream
+
+### MCPs
+
+## Customer communication
+
+_Copy templates per severity (P0 / P1 / P2). Channels (in-app, email, status page)._
+
+### P0 template
+
+### P1 template
+
+### P2 template
+
+## Escalation contacts
+
+_Owner phone tree. Mark each entry with privacy boundary (work-hours OK / 24-7 OK)._
+
+-
+
+## Post-incident
+
+_Runbook for the followup ADR or tech-debt write-up. Pointer to ADR template._

package/template/templates/infrastructure.md

@@ -0,0 +1,190 @@
+---
+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
+---
+
+_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)._
+
+## Hosting & Compute
+
+_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 |
+|---|---|---|---|---|
+| | | | | |
+
+## 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.**
+
+## Data Layer
+
+_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)._
+
+- **Primary database.**
+- **Connection pooling.**
+- **Backups.**
+- **Point-in-time recovery.**
+- **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
+
+_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.**_
+
+- **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.**_
+
+| Service | Monthly spend (approx) | Budget alert at | Scale ceiling | Notes |
+|---|---|---|---|---|
+| | | | | |
+
+- **Rate limits.**
+- **Per-tenant quotas.**
+
+## 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 |
+|---|---|---|---|---|
+| | | | | |
+
+## Blast-Radius Matrix
+
+_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)._
+
+| Resource | Depends on | What dies if this dies | Notification path | Mitigation |
+|---|---|---|---|---|
+| | | | | |
+
+## Access & Change Control
+
+_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.**_
+
+| Human | Provider | Scope | MFA enforced | Last access review |
+|---|---|---|---|---|
+| | | | | |
+
+- **Audit log location.**
+- **Audit log retention.**
+- **Access review cadence.**
+
+## MCP Access Policy
+
+_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._
+
+| MCP server | Wired at | Points at | Access mode | Token storage | Rotation cadence | Notes |
+|---|---|---|---|---|---|---|
+| | | | | | | |
+
+**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.
+
+| Session pattern | Write-capable MCP tools active? | Reads tenant-scoped content? | Compliant? |
+|---|---|---|---|
+| | | | |
+
+**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.**_
+
+- **Data residency.**
+- **GDPR flows.**
+- **Encryption at rest.**
+- **Encryption in transit.**
+- **Known compliance gaps.**
+
+## 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 |
+|---|---|---|---|---|
+| | | | | |
+
+## 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>`._
+
+-
+
+## Unknowns
+
+_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)._
+
+-

package/template/templates/module-spec.md

@@ -0,0 +1,49 @@
+---
+id: <module-key>                       # equals the module key in hstack/config.yaml
+type: module-spec
+status: drafted                        # drafted | current | needs-refresh | archived
+owner: <git-handle>
+paths: []                              # required; canonical module-to-paths mapping (globs)
+last-refreshed: <YYYY-MM-DD>
+created: <YYYY-MM-DD>
+updated: <YYYY-MM-DD>
+schema-version: 1
+---
+
+## Purpose
+
+_What this module is responsible for. 2–4 sentences. Author may grep `paths` to verify._
+
+## Public Surface
+
+_Exports, routes, RPCs the module exposes outward. Bullets._
+
+-
+
+## Data Owned
+
+_Tables, columns, and indexes this module is the canonical owner of. Bullets._
+
+-
+
+## External Dependencies
+
+_Other modules, third-party services, MCPs this module depends on. Bullets._
+
+-
+
+## Invariants
+
+_Challenge prompt: what would a careless refactor in this module break that the tests would not catch? Minimum 3 bullets (validator rule MS-03)._
+
+-
+-
+-
+
+## Known Tech-Debt and ADRs
+
+_Pointers._
+
+## Refresh Policy
+
+_What triggers a refresh and what the refresh entails. One paragraph. The 60-day `needs-refresh` cron flags this spec if untouched._