@thebassclef/lite 0.0.1 → 0.1.2

package/substrate/standards/deployment-topology/ec2-tailscale.md

@@ -0,0 +1,225 @@
+---
+tier: lite
+description: "The operator's reference deployment. Stack-specific instantiation of standards/deployment-topology.md for adopters who pick the same target."
+---
+
+# Deployment Topology — EC2 + Docker Compose + Tailscale + GHA-SSH
+
+The operator's reference deployment. Stack-specific instantiation of `standards/deployment-topology.md` for adopters who pick the same target.
+
+## When this sibling fires
+
+When adopter's `.claude/bassclef-configs.jsonc` has `tech_stack.deploy: ec2-tailscale`. The loader (future ticket) reads this sibling and applies the platform-specific guidance below in addition to the universal principles in the parent standard.
+
+---
+
+
+**Single EC2 instance + Docker Compose + Tailscale mesh + GHA-SSH deploy.**
+
+```
+┌────────────────────────────────────────────────────────┐
+│ EC2 Instance (on Tailscale)                            │
+│ ┌──────────────────────────────────────────────────┐  │
+│ │ docker-compose.prod.yml                           │  │
+│ │   • app      (Next.js / API)                      │  │
+│ │   • worker   (queue processor)                    │  │
+│ │   • postgres (local volume)                       │  │
+│ │   • redis    (local volume)                       │  │
+│ └──────────────────────────────────────────────────┘  │
+│ ┌──────────────────────────────────────────────────┐  │
+│ │ docker-compose.staging.yml    (optional, same box)│  │
+│ │   • app      on different port                    │  │
+│ │   • worker                                        │  │
+│ │   • SHARES postgres (different DB)                │  │
+│ │   • SHARES redis    (different namespace)         │  │
+│ └──────────────────────────────────────────────────┘  │
+│ /opt/backups/  (pg_dump on every deploy)              │
+│ .env.production, .env.staging  (on-box, gitignored)   │
+└────────────────────────────────────────────────────────┘
+            ↑                              ↑
+            │ Tailscale SSH                │ Tailscale HTTPS
+    GitHub Actions (CI)              Users + operator phone
+```
+
+## When this pattern fits
+
+- Small team (≤10 users)
+- Trusted user set (all known, on Tailscale)
+- Cost-sensitive (~$15-30/mo infra per environment)
+- Low-to-moderate traffic (< ~50 concurrent users)
+- Solo or small-team ops (no dedicated SRE)
+- Private / internal tool (not public-facing)
+
+## When to graduate beyond
+
+| Signal | Graduate to |
+|--------|-------------|
+| Public-facing with >100 concurrent users | ALB + auto-scaling group, or managed Platform-as-Service |
+| Multi-region / geo-redundancy required | Terraform-defined multi-region; managed DB |
+| Compliance requires isolation (SOC2, HIPAA) | Dedicated network / VPC + managed services |
+| >1 developer pushing concurrently | Per-PR preview environments |
+| Data loss intolerant (RPO < 1 hour) | Managed DB with PITR (RDS, Aurora) + offsite backups |
+
+**Graduation is a conscious choice, not default.** Most products never
+need it. Starting simple and graduating under pressure is cheaper than
+over-architecting up front.
+
+## Environment separation rules
+
+### Topology choices
+
+**Option A — Same box, multiple Compose stacks** (cheapest, default)
+
+- Prod stack on `docker-compose.prod.yml` at port 3001
+- Staging stack on `docker-compose.staging.yml` at port 3002
+- Shared Postgres, different DBs (`{app}_prod`, `{app}_staging`)
+- Shared Redis, different namespaces (`prod:*`, `staging:*`)
+- Shared box = resource contention risk; monitor
+
+**Option B — Separate boxes, same pattern** (isolation, ~$15-20/mo more)
+
+- Prod box + staging box, both on Tailscale mesh
+- Separate Postgres + Redis per box
+- Clean isolation at cost of second instance
+
+Default is Option A. Upgrade to B if contention manifests.
+
+### Required separation
+
+Regardless of topology choice:
+- **Separate `.env.{environment}` files** — never share credentials
+- **Separate DBs / namespaces** — never share data
+- **Separate backup paths** — `/opt/backups/prod/`, `/opt/backups/staging/`
+- **Separate API keys** — staging uses test-tier keys where providers
+  support (Anthropic, Resend, etc.)
+- **No PII in staging** — synthetic fixtures or anonymized seed,
+  never a raw prod copy
+
+## Deploy workflow shape (bassclef)
+
+Every deploy workflow (`.github/workflows/deploy.yml`) follows this sequence:
+
+1. **Test** — unit + integration tests must pass
+2. **Build** — Docker image → push to GHCR with SHA tag
+3. **Pre-deploy backup** — SSH to box, `pg_dump` current DB to
+   `/opt/backups/{env}/`
+4. **Deploy** — pull image, run migrations in temporary container,
+   `docker compose up -d` with maintenance-mode flag during restart
+5. **Smoke test** — curl health endpoint + one critical path; fail
+   the job if anything breaks
+6. **Alert on failure** — auto-create GitHub issue labeled priority:high
+
+Staging runs this sequence on PR open/push. Prod runs on merge to main
+**with manual approval gate** (see Manual approval rule below).
+
+## Manual approval gate (MUST)
+
+Prod deploys always require manual human approval. Mechanism: GitHub
+Environments with `required_reviewers`.
+
+```yaml
+# In deploy.yml
+jobs:
+  deploy-prod:
+    environment:
+      name: prod   # configured with required_reviewers in repo settings
+    ...
+```
+
+No app repo may skip this gate. Per `.claude/rules/manual-prod-approval.md`,
+absence of this configuration is a rule violation.
+
+## Backup protocol
+
+- `pg_dump` before every deploy, compressed, timestamped
+- Stored locally on the box at `/opt/backups/{env}/`
+- Retention: 30 days on-box, longer offsite if compliance requires
+- Weekly rotation to offsite (S3, separate account) if data is
+  business-critical
+
+## Rollback
+
+- Docker image tagged by SHA at every push to GHCR
+- Rollback = redeploy previous SHA: `docker compose -f docker-compose.prod.yml`
+  with image tag swapped
+- Database rollback via `pg_restore` from pre-deploy backup (last resort;
+  most migrations should be expand-and-contract so rollback ≠ restore)
+- Runbook lives at `docs/runbooks/rollback.md` per app repo
+
+## Maintenance mode
+
+During restart, users should see a holding page, not a broken UI.
+Implementation: env flag `MAINTENANCE_MODE=1` set in `.env.{env}`
+during the deploy window, read by the app's request handler, renders
+a simple HTML holding page for all paths.
+
+Deploy sequence:
+1. Set `MAINTENANCE_MODE=1` in env
+2. Run migrations (in temporary container)
+3. Restart app + worker containers
+4. Health-check loop: up to N retries
+5. Unset `MAINTENANCE_MODE`, restart to pick up env change
+
+## Mobile / ephemeral safety
+
+Deploy flows NEVER run from an ephemeral session (mobile, CI-nested
+agent, etc.). Ephemeral sessions open PRs; CI handles the deploy on
+merge after approval gate. See `standards/mobile-ephemeral-session.md`.
+
+## Templates
+
+Working templates for instantiation into new app repos:
+
+```
+presence/install/deployment/
+  docker-compose.prod.template.yml
+  docker-compose.staging.template.yml
+  env.prod.template
+  env.staging.template
+  github-workflows-deploy.template.yml
+```
+
+Parameterized on: `{{APP_NAME}}`, `{{APP_PORT_PROD}}`, `{{APP_PORT_STAGING}}`,
+`{{DB_NAME_PROD}}`, `{{DB_NAME_STAGING}}`, `{{GHCR_IMAGE}}`,
+`{{DEPLOY_HOST}}`, `{{DEPLOY_USER}}`, `{{DEPLOY_PATH}}`, `{{TAILSCALE_TAG}}`.
+
+Values come from `substrate.config.md` fields (per
+`standards/substrate-config-schema.md`).
+
+## Substrate config fields required for deployment
+
+```yaml
+deploy_host: [Tailscale hostname]
+deploy_user: [SSH user]
+deploy_path: [absolute path on box]
+staging_deploy_host: [optional; same or different]
+staging_deploy_path: [optional]
+tailscale_tag: [e.g., tag:ci]
+backup_path: [absolute path]
+prod_approval_reviewers: [comma-separated GitHub usernames]
+```
+
+## Anti-patterns
+
+- **Hardcoded host/user/path in deploy.yml** — always pull from
+  `substrate.config.md` via GHA secrets or variables
+- **Same `.env.production` on staging** — never. Separate files,
+  always.
+- **Prod data copied to staging** — PII leak + violates substrate
+  separation rule
+- **Auto-deploy to prod without approval gate** — violates guardrails
+- **Deploy from ephemeral session** — violates mobile-ephemeral rules
+- **Skipping pre-deploy backup** — no recovery path if deploy breaks
+
+## Related
+
+- `standards/mobile-ephemeral-session.md` — ephemeral constraints
+- `standards/substrate-config-schema.md` — resource reference schema
+- `.claude/rules/manual-prod-approval.md` — prod gate enforcement
+- `.claude/rules/guardrails.md` — prod deploy always human-approved
+
+## Refs
+
+- Parent standard: `standards/deployment-topology.md`
+- ARCH-T0 #1133 — operator-stack-leakage audit + remediation
+- bassclef#1315 — this sibling (deployment-topology Path A WU-9 of bet 2026-06-20e)

package/substrate/standards/deployment-topology.md

@@ -0,0 +1,69 @@
+---
+tier: lite
+description: Document the deployment target your project actually uses, so substrate-side hooks + rules + skills load the right per-platform siblings via the loader (future ticket) reading tech_stack.deploy from .claude/bassclef-configs.jsonc.
+---
+
+# Deployment Topology Standard
+
+## Purpose
+
+Document the deployment target your project actually uses, so substrate-side hooks + rules + skills load the right per-platform siblings via the loader (future ticket) reading `tech_stack.deploy` from `.claude/bassclef-configs.jsonc`.
+
+This standard is universal — it instructs you to declare your deployment target, not which platform to adopt. The operator's deployment (single EC2 + Docker Compose + Tailscale + GHA-SSH) is documented as one example under `standards/deployment-topology/ec2-tailscale.md`; adopters on Vercel, Netlify, Fly, Render, Cloud Run, Amplify add their own siblings.
+
+## Why declare your deployment
+
+Bassclef's deploy-side discipline (prod approval gates, environment isolation, secret handling, observability hooks, rollback procedures) ships as universal principles with per-platform siblings. The loader matches your declared deploy target to the relevant sibling; without one, the universal principles still apply but platform-specific specifics are skipped.
+
+Declare your deployment in `.claude/bassclef-configs.jsonc` `tech_stack.deploy`:
+
+```jsonc
+"tech_stack": {
+  "deploy": "ec2-tailscale" | "vercel" | "netlify" | "fly" | "render" | "gcp-cloud-run" | "amplify" | "none"
+}
+```
+
+## Per-platform siblings
+
+| Adopter's `tech_stack.deploy` | Sibling location |
+|---|---|
+| `ec2-tailscale` (operator's deployment) | `standards/deployment-topology/ec2-tailscale.md` |
+| `vercel` | `standards/deployment-topology/vercel.md` *(future — file `/promote` to author)* |
+| `netlify` | `standards/deployment-topology/netlify.md` *(future)* |
+| `fly` | `standards/deployment-topology/fly.md` *(future)* |
+| `render` | `standards/deployment-topology/render.md` *(future)* |
+| `gcp-cloud-run` | `standards/deployment-topology/gcp-cloud-run.md` *(future)* |
+| `amplify` | `standards/deployment-topology/amplify.md` *(future)* |
+| `none` or unset | universal principles only; no platform-specific guidance |
+
+## Universal principles
+
+Whichever deployment target you pick:
+
+- **Production deploys require human approval** — never auto-deploy to prod without explicit gate per `.claude/rules/manual-prod-approval.md`. Hard ceiling regardless of platform.
+- **Environment isolation** — local / staging / prod are distinct; secrets, data, and config never cross boundaries
+- **ENV vars and secrets** — never committed; live in your platform's secret-management mechanism (GitHub Actions Secrets, Vercel env vars, AWS Secrets Manager, 1Password, etc.). Reference by name in code; never inline values.
+- **Backups before destructive operations** — DB backup before any migration that drops columns / changes types / renames tables. Backup retention policy declared in your sibling.
+- **Rollback procedure** — documented per platform. Know your N-1 deployable artifact at all times.
+- **Observability** — health endpoint + error reporting + log aggregation. Platform-specific tooling varies; the obligation is universal.
+- **Secret rotation** — declared cadence per secret type. Per `standards/secrets-lifecycle.md`.
+
+## Operator's deployment reference
+
+The operator's reference deployment is single EC2 + Docker Compose + Tailscale mesh + GHA-SSH deploy. Full architecture diagram + capacity bounds + when to graduate + setup walkthrough + key commands live in `standards/deployment-topology/ec2-tailscale.md`.
+
+This is one example among many valid patterns. Adopters on cloud-platform deployments (Vercel, Netlify, Fly, Render, Cloud Run, Amplify) read their own sibling once it exists; until then, the universal principles above apply.
+
+## When to graduate from your declared deployment
+
+Each platform sibling documents capacity bounds + graduation triggers (when single-instance bottlenecks force migration to multi-region / managed services / Kubernetes / etc.). The operator's EC2-Tailscale sibling carries the original graduation triggers for that pattern; adopters on cloud platforms document their own.
+
+## Refs
+
+- ARCH-T0 #1133 — operator-stack-leakage audit + remediation (parent)
+- bassclef#1315 — this Path A WU-9 of bet 2026-06-20e
+- bassclef#1309 + bassclef#1311 + bassclef#1313 — sister Path A passes
+- bassclef#1127 — tech_stack vocabulary
+- `.claude/rules/manual-prod-approval.md` — prod approval gate (universal)
+- `standards/secrets-lifecycle.md` — secret rotation discipline
+- `standards/deployment-topology/ec2-tailscale.md` — operator's deployment reference

package/substrate/standards/docs-sync-allowlist.md

@@ -0,0 +1,76 @@
+---
+tier: lite
+description: Files whose change triggers bassclef-docs-sync.yml.
+---
+
+# Docs Sync Allowlist
+
+Files whose change triggers `bassclef-docs-sync.yml`. The workflow syncs bassclef's adopter-facing docs into a discoverable surface (GitHub Wiki + cross-reference verification) so substrate-vs-docs drift can't accumulate silently between sessions.
+
+Tracked under c-package iteration goal 2026-05-13. Closes the discipline gap surfaced when `.bassclef-source.json` was described as pointing at S3 (it points at GitHub) one turn after the description shipped.
+
+## Files
+
+When any of these paths change in a push to `main`, the docs-sync workflow fires:
+
+- `standards/project-directory-layout.md`
+- `docs/bassclef-mental-model.md`
+- `docs/bassclef-overview.md`
+- `docs/getting-started.md` (added 2026-05-14 — dedicated Getting Started walkthrough)
+- `docs/first-use-sequence.md` (added 2026-06-13 — bassclef#965 first-use sequence diagram)
+- `docs/how-skills-work.md` (added 2026-06-13 — adopter guidance on discovery + composition + autonomy modes)
+- `README.md`
+- `docs/hooks-index.md`
+- `docs/glossary.md` (added 2026-05-14 — exhaustive-docs stack)
+- `docs/philosophy.md` (added 2026-05-14)
+- `docs/skills-catalog.md` (added 2026-05-14)
+- `docs/hooks-catalog.md` (added 2026-05-14)
+- `docs/rules-catalog.md` (added 2026-05-14)
+- `architecture/decisions/ADR-*.md` (any new file matching this glob)
+- `.claude/skills/*/SKILL.md` (any new file OR `deprecated: true` flip in frontmatter)
+- `.claude/rules/*.md` (any new file)
+- `standards/bassclef-source-config.md`
+- `standards/vendor-bindings.md` (standard tier — substrate reference)
+- `standards/bassclef-configs-schema.md` (added 2026-06-20 — bassclef#1284 closeout; covers the schema doc updated when new bassclef-configs blocks ship)
+- `standards/sibling-validation-checklist.md` (standard tier; added 2026-06-20 — bassclef#1284 closeout; operator-runnable end-to-end validation procedure for adopter inheritance)
+- `standards/bassclef-internal-jargon.md` → `Bassclef-Internal-Jargon.md` (added 2026-06-20 — bassclef#1298 / WU-13 of bet 2026-06-20e; the BLOCK / ADVISE / ALLOW wordlist read by turn-prose-kiss-check.sh + pr-body-scrub-check.sh; amended frequently — every wordlist addition should sync to wiki so adopters see current catalog)
+- `standards/adr-template.md` → `ADR-Template.md` (added 2026-06-20 — bassclef#1208 / WU-14 of bet 2026-06-20e; 14-day wiki-as-we-go sweep — ADR template for adopter architecture-record discipline)
+- `standards/bash-hook-safety.md` → `Bash-Hook-Safety.md` (added 2026-06-20 — same; 7 defensive-bash disciplines)
+- `standards/code-safety-principles.md` → `Code-Safety-Principles.md` (added 2026-06-20 — same; language-agnostic safety principles)
+- `standards/frontmatter-schema.md` → `Frontmatter-Schema.md` (added 2026-06-20 — same; required/optional fields for rules + skills)
+- `standards/model-routing-discipline.md` → `Model-Routing-Discipline.md` (added 2026-06-20 — same; per-agent model_tier discipline)
+- `standards/pseudonym-key-schema.md` → `Pseudonym-Key-Schema.md` (standard tier; added 2026-06-20 — same; operator-private pseudonym registry schema)
+- `standards/security-scanner-adapter.md` → `Security-Scanner-Adapter.md` (added 2026-06-20 — same; per-stack security scanner integration)
+- `standards/tech-stack-config.md` → `Tech-Stack-Config.md` (added 2026-06-20 — same; tech_stack vocabulary bassclef#1127 drives)
+
+## What the workflow does
+
+For each changed allowlisted path:
+
+1. **Identify the artifact class.** Standard / mental-model / overview / README / ADR / skill / rule / hooks-index.
+2. **If a wiki page exists for this artifact**, update it with the new content (light header transform — strip frontmatter, add wiki-style title).
+3. **If no wiki page exists yet**, create one + add to `_Sidebar.md`.
+4. **Cross-reference check.** Grep bassclef-overview + README + mental-model for stale links to the changed file. Surface mismatches as warnings on the PR.
+5. **Step summary.** GitHub Actions step summary names what was synced.
+
+## What does NOT trigger sync
+
+Changes to files NOT on the allowlist. The allowlist is intentionally narrow — internal-decomposition docs, chronicles, iteration goals, LinkedIn drafts, sibling-validations, and audits all stay non-synced. Wiki is for adopter-facing reference, not operator-internal records.
+
+## Adding a new path
+
+When a new file should be synced, edit this allowlist + the workflow's `paths:` filter in the same PR. Per `standards/project-directory-layout.md` anti-drift rule: substrate change + standard update in same change.
+
+## Override
+
+`SKIP_DOCS_SYNC=1` in a commit body skips the workflow for that commit. Logged via trace-helper. Use rarely; prefer narrowing the allowlist if a path shouldn't be synced.
+
+## Sources read
+
+- `docs/iteration-bets/2026-05-13-s3-retirement-docs-sync-hooks-index.md` — parent bet
+- `docs/roadmaps/2026-05-07-7-phase-staircase.md` — current `last_event` = `phase_v_mvd_substrate_shipped` at `2026-05-12T01:30:00Z`
+- `.claude/rules/bassclef-workflow-parity.md` (standard tier) — sibling-grep discipline when adding workflows
+
+## Closes
+
+WU-4 of c-package bet — the standard half. WU-5 ships the `/docs-sync` skill that runs the same logic locally. The workflow YAML itself ships in this same WU.

package/substrate/standards/domain-and-dns.md

@@ -0,0 +1,145 @@
+---
+tier: lite
+description: - .claude/skills/bind-subdomain/SKILL.md — operationalizes this standard - scripts/bind-subdomain.sh + scripts/adapters/* — the implementation - standards/substrate-config-schema.md — field conventions used by the script -…
+---
+
+## Sources read
+
+- `.claude/skills/bind-subdomain/SKILL.md` — operationalizes this standard
+- `scripts/bind-subdomain.sh` + `scripts/adapters/*` — the implementation
+- `standards/substrate-config-schema.md` — field conventions used by the script
+- bassclef #254 — shaping ticket this standard closes
+- `docs/learnings/2026-04-19-mobile-to-preview.md` — source of the manual pattern now automated
+
+## What I'm NOT reading (with reason)
+
+- `standards/deployment-topology.md` — orthogonal (that's EC2 + Docker Compose; this is DNS/TLS for any managed platform)
+- Route 53-specific DNS management — out of scope v1; Phase 2 of automation path
+
+# Domain + DNS Standard
+
+Bassclef decision for how sunj-labs apps get friendly URLs:
+subdomain convention, TLS ownership, and DNS automation.
+
+## The four coupled decisions
+
+### 1. Subdomain convention: `<app>.apps.fivepandas.com`
+
+- **Apex (`fivepandas.com`)** — reserved for marketing/brand
+- **`apps.fivepandas.com`** — bassclef subtree for sunj-labs apps
+- **`<app>.apps.fivepandas.com`** — one per app
+
+Per-environment subdomains (e.g., `quorum.preview.apps.fivepandas.com`) are **deferred**. Single binding per app until multi-environment needs emerge. When they do, the pattern extends to `<app>.<env>.apps.fivepandas.com`.
+
+**Why `apps.` bucket:** leaves apex + first-level untouched for brand; centralizes app surfaces under one predictable subtree; matches the bassclef-as-operating-system frame.
+
+### 2. TLS / cert ownership: Amplify-managed (Phase 1) → Route 53 delegation (Phase 2)
+
+| Phase | Approach | Trigger |
+|-------|----------|---------|
+| **Phase 1 (current)** | Amplify-managed cert (ACM); validation records live in Cloudflare | First 1-2 apps; before IaC lands |
+| **Phase 2 (future)** | Route 53 delegation — delegate `apps.fivepandas.com` NS to Route 53; Amplify manages DNS + cert end-to-end | Triggered by #250 (IaC: CDK vs Gen 2) |
+
+Phase 2 is the target because only Route 53 composes cleanly with AWS-native IaC. But Phase 1 is correct today — the cost of Route 53 delegation isn't justified for 1-2 apps.
+
+### 3. DNS automation: `/bind-subdomain` skill
+
+All DNS binding goes through `/bind-subdomain` — no manual clickops. The skill:
+
+- Reads `substrate.config.md` for the consumer repo
+- Dispatches to deploy-host adapter (Amplify v1; Netlify/Vercel/CF-Pages future)
+- Dispatches to DNS-provider adapter (Cloudflare v1; Route 53 future)
+- Creates domain association + validation records idempotently
+- Polls cert validation (up to 20 min)
+- Enables auto-build on the bound branch
+
+**Idempotency** is mandatory. Re-running the skill against an already-bound app returns the current binding without modification. Script failure mid-way is recoverable by re-run.
+
+### 4. Prototype gallery URL pattern: path-based, under the app subdomain
+
+Per ADR-016 (bassclef#441 resolution): `/preview-build` and `/prototype-variants` dispatches expose variants under the app's existing subdomain at:
+
+```
+https://<app>.apps.fivepandas.com/prototypes/<dispatch-slug>/<variant-slug>/
+```
+
+Examples (live):
+
+- `https://quorum.apps.fivepandas.com/prototypes/<historical-example-bet>/variant-tufte/` — Quorum's 22-variant gallery
+- `https://twodo.apps.fivepandas.com/prototypes/2026-05-02-twodo/variant-a-tufte/` — TwoDo PR #269 (pending bind)
+
+**Per-variant routing is the consumer app's responsibility**, not bassclef's `/bind-subdomain` skill. Static folder under `public/prototypes/` works on every supported deploy host (Amplify, Vercel, Netlify); Next.js App Router with `app/prototypes/[...slug]/page.tsx` works for dynamic galleries.
+
+**One subdomain per app, regardless of variant count.** A 22-variant gallery binds the same way a single page does — one cert validation cycle, one DNS record. The path-based pattern preserves §1's "one subdomain per app" rule without amendment.
+
+**`/launch-preview` (bassclef#448) operationalizes this convention.** The composer provisions exactly one subdomain per app via `/bind-subdomain`; variants ride along under `/prototypes/`.
+
+**Production exclusion is the consumer's responsibility.** `/prototypes/*` routes should be gated behind a build-time flag (`NODE_ENV === 'development'`, `PREVIEW_TIER === '1'`, etc.) so production builds strip them. `standards/prototype-gallery.md` codifies the exclusion expectation.
+
+Alternatives considered + rejected (subdomain-prefix, sub-subdomain) and full rationale: see ADR-016.
+
+## Required config fields
+
+Consumer repo's `substrate.config.md` declares:
+
+```yaml
+hosting_platform: amplify               # amplify (bassclef default) | ec2-tailscale | vercel | netlify | cloudflare-pages | none
+amplify_app_id: d154l5usyc80nk
+amplify_region: eu-north-1
+amplify_branch: main                    # optional, defaults to main
+subdomain: quorum.apps.fivepandas.com
+dns_provider: cloudflare                # cloudflare | route53
+dns_zone: fivepandas.com
+cloudflare_token_env: CLOUDFLARE_API_TOKEN
+```
+
+Secret values NEVER live in `substrate.config.md`. The field
+`cloudflare_token_env` names an environment variable; the value is
+set in the operator's shell (`~/.zshrc`, `~/.bashrc`, 1Password CLI
+integration, etc.).
+
+## Zone ownership + account topology
+
+- `fivepandas.com` zone lives in Cloudflare (operator-owned)
+- AWS Amplify apps live in AWS account `515820372344` (sunj-labs)
+- TLS cert issuance happens in AWS (ACM); validation happens in CF
+- No AWS-side DNS today (Phase 2 changes this for the `apps.` subtree)
+
+## Security posture
+
+- Cloudflare API token: least-privilege — Zone:Read + DNS:Edit, scoped to `fivepandas.com` zone only
+- TTL on CF token: 90-day rotation recommended (forces rotation discipline early)
+- AWS CLI: existing operator creds; narrowing IAM to Amplify-only is future hardening
+- No tokens in source control, ever
+
+## When to graduate beyond this standard
+
+- **Multi-environment per app** (preview/staging/prod) → extend subdomain pattern to `<app>.<env>.apps.fivepandas.com`; `/bind-subdomain` learns a new optional arg
+- **Non-Amplify hosting target** → add adapter at `scripts/adapters/deploy/<host>.sh`; no changes to main script
+- **Non-Cloudflare DNS** → add adapter at `scripts/adapters/dns/<provider>.sh`; migrate to Route 53 per Phase 2
+- **Per-PR preview URLs** → couples to IaC work (#250); likely Amplify-native feature set + new subdomain pattern
+
+## Relationship to adjacent standards
+
+- `substrate-config-schema.md` — field definitions the script reads
+- `deployment-topology.md` — orthogonal (that's the POA EC2 pattern; this is DNS/TLS for any managed platform)
+- `bassclef-evolution.md` — this standard shipped as the resolution of #254
+
+## Relationship to adjacent skills
+
+| Skill | Role |
+|-------|------|
+| `/bind-subdomain` | Implements this standard |
+| `/onboard-repo` | Peer — provisions bassclef substrate for a new repo; binding happens after deploy host exists |
+| `/deploy-prod` | Peer — POA's EC2+Tailscale deploy pattern; doesn't use this skill |
+| `/substrate-check` | Validates `substrate.config.md` schema coverage |
+
+## Evolution
+
+- **v1.0 (2026-04-23)** — initial standard + skill + scripts + adapter
+  pattern. Amplify + Cloudflare v1 only. First consumer: quorum.
+
+## Closes
+
+- bassclef #254 (shaping)
+- bassclef iteration goal 2026-04-23a-bind-subdomain (this ship)

package/substrate/standards/frontend-stack.md

@@ -0,0 +1,67 @@
+---
+tier: lite
+description: Document the stack your project actually uses, so substrate-side hooks + rules + skills load the right per-stack siblings via the loader (future ticket) reading tech_stack from .claude/bassclef-configs.jsonc.
+---
+
+# Application Stack Standard
+
+## Purpose
+
+Document the stack your project actually uses, so substrate-side hooks + rules + skills load the right per-stack siblings via the loader (future ticket) reading `tech_stack` from `.claude/bassclef-configs.jsonc`.
+
+This standard is universal — it instructs you to declare your stack, not which stack to adopt. The operator's stack is documented as one example under `standards/frontend-stack/nextjs-prisma.md`; adopters on other stacks add their own sibling.
+
+## Why declare your stack
+
+Bassclef's substrate carries cross-cutting discipline (testing tiers, SDLC gates, API conventions, schema management, dependency discipline, deployment topology). Each ships a universal rule with per-stack siblings. The loader matches your declared stack to the relevant siblings; without a declared stack, the universal principles still apply but the stack-specific specifics are skipped.
+
+Declare your stack in `.claude/bassclef-configs.jsonc` `tech_stack` block:
+
+```jsonc
+"tech_stack": {
+  "frontend": "nextjs" | "react-vite" | "vue" | "svelte" | "fastapi" | "django" | "rails" | "none",
+  "backend": "nodejs" | "python" | "ruby" | "go" | "rust" | "deno",
+  "orm": "prisma" | "sqlalchemy" | "active-record" | "gorm" | "alembic" | "none",
+  "pkg_manager": "npm" | "pip" | "cargo" | "gem" | "go-mod",
+  "deploy": "ec2-tailscale" | "vercel" | "netlify" | "fly" | "render" | "gcp-cloud-run" | "amplify" | "none"
+}
+```
+
+## Per-stack siblings
+
+| Adopter's stack | Sibling location |
+|---|---|
+| Next.js + Prisma + Postgres + EC2-Tailscale (operator's stack) | `standards/frontend-stack/nextjs-prisma.md` |
+| FastAPI + SQLAlchemy + Postgres | `standards/frontend-stack/fastapi-sqlalchemy.md` *(future — file `/promote` to author)* |
+| Rails + ActiveRecord | `standards/frontend-stack/rails.md` *(future)* |
+| Other | document yours under `standards/frontend-stack/<name>.md` |
+
+When no sibling matches your declared stack, the universal principle below applies; sibling-specific guidance is skipped.
+
+## Universal principle
+
+Whichever stack you pick:
+
+- One declared stack per project — mixing N stacks for parts of one app produces drift; pick one and document it
+- Type safety from boundary to boundary where the language supports it (TypeScript strict, Python type hints + mypy, etc.)
+- Single source of truth for DB schema (an ORM schema file, a migration history, or a generated artifact — your call, but ONE source)
+- ENV vars never committed; live in `.env.local` (local) and your deployment platform's env mechanism (production)
+- Testing tiers per `.claude/rules/testing-tier-config.md` (Tier 0 strict TDD for substrate; Tier 1/2/3 by blast radius)
+- Migrations per `.claude/rules/schema-management.md` (never auto-apply; never use `db push`-style tools that bypass migration files)
+
+## Operator's stack reference
+
+The operator's reference stack is Next.js + TypeScript + Prisma + Postgres + EC2-Tailscale. Full details + project structure + conventions + key commands live in `standards/frontend-stack/nextjs-prisma.md`.
+
+See [ADR-008](../architecture/decisions/ADR-008-full-typescript-stack.md) for the original operator-side rationale. ADR-008 is operator-specific by nature (it documents one project's architecture decision); adopters on other stacks make their own ADRs.
+
+## Refs
+
+- ARCH-T0 #1133 — operator-stack-leakage audit + remediation (parent)
+- bassclef#1313 — this Path A WU-8 of bet 2026-06-20e
+- bassclef#1309 + bassclef#1311 — sister Path A passes
+- bassclef#1127 — tech_stack vocabulary
+- `.claude/rules/testing-tier-config.md` — testing tier discipline
+- `.claude/rules/schema-management.md` — migration discipline (Path A precedent)
+- `.claude/rules/new-dependency-check.md` — dependency discipline (Path A precedent)
+- `standards/frontend-stack/nextjs-prisma.md` — operator's stack reference