@thebassclef/lite 1.1.1 → 1.2.0

package/dist/lite/standards/prototype-gallery.md

@@ -0,0 +1,251 @@
+---
+tier: lite
+description: - bassclef #252 — ticket prescribing the three-artifact shape (standard + skill + template) - .claude/skills/prototype-variants/SKILL.md — upstream skill producing the variants this standard indexes - ~/src/sunj-labs/quorum/prototypes/ — 23-variant…
+---
+
+## Sources read
+
+- `bassclef #252` — ticket prescribing the three-artifact shape (standard + skill + template)
+- `.claude/skills/prototype-variants/SKILL.md` — upstream skill producing the variants this standard indexes
+- `~/src/sunj-labs/quorum/prototypes/` — 23-variant repo that forced this pattern (variants a–s + synthesis m/mxh/mxj/mxk)
+- `standards/project-directory-layout.md` — `prototypes/` is already a bassclef directory; this standard extends conventions around it
+
+## What I'm NOT reading (with reason)
+
+- Next.js App Router docs — gallery page is plain Next; no framework-specific specialization
+- Static hosting vendor docs (Amplify/Netlify/Vercel) — gallery is a route under the consumer app; no vendor-specific logic
+- Analytics vendors (Plausible, Vercel Analytics) — variant-open tracking is explicitly deferred per `#252` v1
+
+# Prototype Gallery Standard
+
+Convention for how sunj-labs app repos expose their prototype variants
+as a single shareable index page with scannable context.
+
+Operationalized by `/prototype-gallery` (skill) and `templates/gallery-yml.md` (metadata template).
+
+## The problem this standard solves
+
+Repos that run `/prototype-variants` accumulate multiple variants in
+`prototypes/` — often 3-5, sometimes 20+ (quorum has 23). When the
+operator wants to share or compare variants:
+
+- Each variant is its own static HTML with no cross-variant context
+- Collaborators open tabs per variant and switch between them with no
+  value-prop framing — just raw UI
+- The operator's decision-support surface is memory-dependent: "what
+  was variant-k optimizing for again?"
+- Single-URL sharing requires the gallery page to exist; without it,
+  sharing means hunting Amplify URLs per variant or sending file paths
+
+The gallery page is the single shareable URL with all variants listed,
+each with a 2-line value prop and luminary attribution.
+
+## Coupled decisions
+
+### 1. Directory convention
+
+| Source path | Purpose |
+|-------------|---------|
+| `prototypes/<slug>/` | Variant source (HTML, CSS, images) — authored by `/prototype-variants` or by hand |
+| `prototypes/<slug>/gallery.yml` | Variant metadata for the gallery index (this standard's artifact) |
+| `public/prototypes/<slug>/` | Copy of variant HTML served by the consumer app's static pipeline |
+| `src/app/prototypes/page.tsx` | Gallery index page (or `src/app/page.tsx` if prototype-first) |
+
+`prototypes/` is the source of truth. `public/prototypes/` is regenerated by the skill; never hand-edited. `src/app/prototypes/page.tsx` is regenerated but may be hand-edited — the skill refuses to overwrite without confirmation.
+
+### 2. Gallery route
+
+| Scenario | Route | Example |
+|----------|-------|---------|
+| Repo is prototype-first (only variants, no app yet) | `/` | quorum |
+| Repo has its own app and variants live alongside | `/prototypes` | POA (hypothetical — review-queue pre-v5) |
+
+The skill detects which scenario by checking for an existing `src/app/page.tsx` — if present and non-trivially different from a gallery scaffold, route is `/prototypes`; otherwise `/`.
+
+**Per ADR-016**: variant URLs are `<app>.apps.fivepandas.com/prototypes/<dispatch-slug>/<variant-slug>/` — path-based under the existing app subdomain. One subdomain per app regardless of variant count; routing is the consumer app's responsibility (static folder OR Next.js App Router). See `standards/domain-and-dns.md` §4 for the full convention.
+
+**Production exclusion (consumer responsibility):** `/prototypes/*` routes MUST be gated behind a build-time flag so production builds strip prototype galleries. Galleries leaking into production hostnames are a real-user-confusion risk (bassclef#441 R1, addressed in bassclef#458). See §"Production-domain gating" below for the requirement and three reference configs.
+
+### 3. Metadata: `gallery.yml` (primary) or README frontmatter (fallback)
+
+Each variant declares gallery metadata via `prototypes/<slug>/gallery.yml`. Schema:
+
+```yaml
+title: "Variant A — Ive + HIG"
+value_prop: |
+  Restrained surfaces. Operator reads the deal in under 3 seconds.
+  Strong typographic hierarchy; no decorative affordances.
+luminaries:
+  - Jony Ive
+  - Apple HIG
+date: 2026-04-20
+status: active   # active | archived | superseded
+```
+
+**`title`**: Short label shown on the card. Usually `<variant-slug humanized> — <luminary shorthand>`.
+
+**`value_prop`**: Two lines maximum. Tufte-density constraint — the whole point of the gallery is scannable context, not explanatory prose. Longer value props are a spec violation; the skill may truncate or the reviewer may reject.
+
+**`luminaries`**: List of luminary names (matches the `primary_luminaries` shape in iteration goals per `standards/pluggable-luminaries.md`). Rendered as tag pills on the card.
+
+**`date`**: When the variant was produced. Controls sort order (newest first, by default).
+
+**`status`**: `active` = shown in gallery; `archived` = hidden but preserved on disk; `superseded` = hidden with a "superseded by" link to the successor variant (field: `superseded_by: <slug>`).
+
+**Fallback**: if `gallery.yml` is absent, skill reads variant's `README.md` frontmatter for the same fields. If neither exists, skill fails with a clear error naming the variant — does NOT synthesize defaults, because a gallery card without a value prop is worse than no card.
+
+### 4. Card shape
+
+Each variant renders as a card with four zones:
+
+```
+┌─────────────────────────────────────────────┐
+│ Variant A — Ive + HIG                       │  ← title
+│                                             │
+│ Restrained surfaces. Operator reads the     │  ← value_prop (2 lines)
+│ deal in under 3 seconds.                    │
+│                                             │
+│ [Jony Ive] [Apple HIG]                      │  ← luminary pills
+│                                             │
+│                              [  Open  →  ]  │  ← CTA
+└─────────────────────────────────────────────┘
+```
+
+Card styling is the consumer app's concern, not bassclef's. The skill scaffolds a plain CSS-only card with semantic markup; consumer repos can override by editing `page.tsx` directly (the skill respects hand-edits per Decision 1).
+
+### 5. Regeneration discipline
+
+When a new variant is added to `prototypes/`, the skill re-scans and regenerates:
+
+1. Copies updated variant HTML into `public/prototypes/<slug>/`
+2. Re-reads all `gallery.yml` files
+3. Updates `src/app/prototypes/page.tsx` IF it matches the bassclef scaffold shape (hash check against the template)
+4. If `page.tsx` has been hand-edited, skill surfaces a diff and asks operator whether to merge
+
+**Additive regeneration**: archived/superseded variants are NOT deleted from `public/prototypes/` — old URLs continue to resolve for operators who bookmarked them. Gallery index just hides them.
+
+## Production-domain gating
+
+ADR-016 R1 (production-domain pollution): when prototype and production tiers share a hostname (the common case — both deploy under `<app>.apps.fivepandas.com`), real users navigating directly to `<app>.apps.fivepandas.com/prototypes/some-slug/variant-a/` would land on a stale prototype with no production framing. This is real-user confusion, not just operator-facing aesthetics.
+
+**Requirement:** consumer apps that adopt the gallery convention MUST gate `/prototypes/*` routes behind a build-time flag. Production builds MUST strip the prototype routes from the deployed bundle.
+
+The gate is consumer responsibility (no auto-strip — see "What bassclef does not do" below). Below are three reference configs covering the common shapes.
+
+### Reference config 1: Next.js App Router (`app/prototypes/[...slug]/page.tsx`)
+
+The gallery page reads the env var at request time and returns 404 in production builds. The `[...slug]` catch-all matches every variant URL.
+
+```tsx
+// app/prototypes/[...slug]/page.tsx
+import { notFound } from 'next/navigation'
+
+export default function PrototypePage({ params }: { params: { slug: string[] } }) {
+  if (process.env.PREVIEW_TIER !== '1') {
+    notFound()
+  }
+  // Render variant page. In production builds (PREVIEW_TIER unset),
+  // the notFound() above runs and Next.js returns the 404 page.
+  return <iframe src={`/prototypes-static/${params.slug.join('/')}/index.html`} className="w-full h-screen border-0" />
+}
+```
+
+Set `PREVIEW_TIER=1` in dev / preview deploys; leave unset in production. The catch-all approach means one route gates every variant URL.
+
+### Reference config 2: Next.js static folder (`public/prototypes/`)
+
+If your variants live in `public/prototypes/` and are served as static files (no Next.js route), the gate moves to the build script:
+
+```json
+// package.json
+{
+  "scripts": {
+    "build": "if [ \"$PREVIEW_TIER\" = \"1\" ]; then next build; else rm -rf public/prototypes && next build; fi",
+    "build:preview": "PREVIEW_TIER=1 next build",
+    "build:prod": "next build"
+  }
+}
+```
+
+In production builds, the `public/prototypes/` directory is removed before `next build` runs. The static files don't ship in the production bundle. Preview builds keep them.
+
+### Reference config 3: generic framework (Vite, Remix, plain HTML)
+
+For frameworks without first-class app-router gating, gate at the static-asset boundary:
+
+```bash
+# scripts/strip-prototypes.sh — run before production deploy
+#!/bin/bash
+set -e
+if [ "${PREVIEW_TIER:-0}" != "1" ]; then
+  echo "Production build: stripping public/prototypes/"
+  rm -rf public/prototypes
+fi
+```
+
+Hook the script into your build command (`pre-build` in package.json, `build.beforeBuild` in framework config, or CI step) so it runs before the bundler reads the static dir.
+
+### How `/launch-preview` warns about gating
+
+`/launch-preview` Phase 4 reads `bassclef-platform.yml`'s `deploy_tiers.{prototype,production}` and surfaces a warning when prototype and production share a hostname:
+
+```
+⚠️  PRODUCTION-DOMAIN GATING
+
+This gallery is live at <URL>. Production deploys to the same hostname.
+Real users navigating directly to /prototypes/<slug>/ would see this
+gallery in production. Gate /prototypes/* in your consumer build.
+
+See standards/prototype-gallery.md §"Production-domain gating" for
+three reference configs (Next.js App Router, static folder, generic).
+```
+
+The warning is informational — `/launch-preview` does not block. ADR-016 R1 names this as a real-user-confusion risk; the warning surfaces it at the moment a gallery goes live so the operator can verify their consumer's gate is in place.
+
+### What bassclef does not do
+
+- **Auto-inject gating logic** into consumer builds — operator-judgment territory; consumers know their build pipeline
+- **Block `/launch-preview`** when gating is missing — too aggressive; warning + reference config is sufficient
+- **Verify the gate works at runtime** — would require bassclef to fetch the production URL post-deploy, which crosses a runtime boundary the substrate avoids
+
+If a consumer ships ungated `/prototypes/*` and a real user finds them, that's a consumer-side bug — but the warning at `/launch-preview` time means no consumer ships it without seeing the warning first.
+
+## Chain position
+
+```
+/prototype-variants → variants in prototypes/
+/prototype-gallery  → gallery.yml per variant + public/ copies + src/app/prototypes/page.tsx
+deploy              → shareable URL with full variant index
+```
+
+Upstream: `/prototype-variants` (produces the variants).
+Downstream: the consumer app's deploy pipeline (Amplify/Netlify/Vercel), which serves the gallery page at the declared route.
+
+## Out of scope (v1 per #252)
+
+- Variant-to-variant navigation within a variant page (prev/next chrome)
+- Gallery-side search or filter (tag/luminary/date facets)
+- Analytics on variant opens
+- Mobile-specific viewport overrides
+- Multi-repo galleries (e.g., a cross-repo operator dashboard showing every bassclef consumer's variants)
+
+These are feature ideas to file as follow-up tickets if the v1 gallery proves its lovability signal. The `gallery.yml` schema is designed to accept them later (e.g., adding `tags:` field doesn't break existing galleries).
+
+## Relationship to other standards
+
+- `standards/project-directory-layout.md` — declares `prototypes/` as bassclef directory; this standard extends it
+- `standards/pluggable-luminaries.md` — `luminaries:` field shape in `gallery.yml` matches iteration-bet conventions
+- `standards/frontend-stack.md` — gallery page is ordinary Next.js route; no framework deviation
+- `.claude/skills/prototype-variants/SKILL.md` — upstream producer
+- `.claude/skills/prototype-gallery/SKILL.md` — operationalizer of this standard
+- `.claude/skills/visual-review/SKILL.md` — still evaluates individual variants; gallery doesn't replace per-variant review
+
+## Retirement condition
+
+If operators stop running multi-variant bets (e.g., bassclef absorbs
+richer decision-support via `/prototype-variants` bake-off mode and
+operators no longer keep variants around for comparison), the gallery
+becomes vestigial. Retire by removing the skill + standard + template;
+variant HTML stays on disk at `prototypes/` with no public surface.
+
+Closes bassclef #252.

package/dist/lite/standards/pseudonym-key-schema.md

@@ -0,0 +1,109 @@
+---
+tier: lite
+title: Pseudonym key schema — substrate-archaeology scrub mapping
+date: 2026-06-06
+schema_for: pseudonym-key.yml (operator-authored in bassclef-upstream)
+bassclef_authors: schema vocabulary + structural shape only
+operator_authors: source-to-pseudonym mapping (in bassclef-upstream)
+acceptance_per: bassclef#853 Sub-bet 22 pseudonym-key as substrate building block
+status: v0 (schema authoring)
+description: Substrate building block for pre-public-launch substrate-archaeology scrub.
+---
+<!-- andon-allow: docs/operator-private/[a-z-]+/20[0-9][0-9]-[0-9]{2} -->
+
+# Pseudonym key schema
+
+Substrate building block for pre-public-launch substrate-archaeology scrub. The schema maps operator source-vocabulary to category-classified pseudonyms. Bassclef ships the schema and its vocabulary. The authored mapping itself lives in a private repo the operator controls.
+
+## Why two files
+
+The schema and the mapping live apart on purpose. The mapping is reverse-engineerable from an operator's portfolio: if the public schema named both source tokens and their pseudonyms, anyone could collapse the substitution. So the public file ships the shape; the private file holds the substance.
+
+| File | Repo | Role | Sensitivity |
+|---|---|---|---|
+| `standards/pseudonym-key-schema.md` (this file) | bassclef | Schema vocabulary + structural shape | Public |
+| `docs/operator-private/pseudonym-key.yml` | bassclef-upstream | Authored source-to-pseudonym mapping | Tier 1 (operator-private) |
+
+The scrub script that ships in bassclef reads the mapping at execution time only, via the `SUNJ_LABS_ROOT` environment variable. The mapping never appears in any bassclef artifact: not in commit messages, not in chronicles, not in audit findings, not in this schema.
+
+## Category vocabulary
+
+The schema recognises ten categories of operator source-vocabulary. Every entry in the authored mapping carries one of these labels.
+
+| Category | Description | Default sensitivity |
+|---|---|---|
+| consumer-app | Operator's adopter app codenames | structural |
+| tier-1-mechanism | Sensitive IP mechanism names | sensitive-ip |
+| domain-codename | Sensitive IP domain codename | sensitive-ip |
+| cloud-stack | Operator-specific cloud or architecture references | structural |
+| operator-specific | Operator's personal or portfolio names | operator-specific |
+| portfolio-effort | Portfolio acronyms | structural |
+| utility-app | Operator's utility-app codenames | structural |
+| operations-app | Operator's operations-app codenames | structural |
+| internal-pr | Internal-repo PR numbers | structural |
+| ip-classification-family | Operator's IP-classification taxonomy | sensitive-ip |
+
+## Sensitivity classes
+
+Each entry in the mapping is also classified by sensitivity. Sensitivity determines the scrub pattern.
+
+| Class | Scrub pattern | Pseudonym style |
+|---|---|---|
+| structural | Pattern B — pseudonym substitution | `<category>-<n>` (for example `consumer-app-1`) |
+| sensitive-ip | Pattern A — direct scrub, or Pattern B with deeper anonymisation | `null` (Pattern A) or `<category-class>-<n>` (Pattern B) |
+| operator-specific | Pattern A or Pattern B, per operator decision | Per operator |
+
+## Scrub patterns
+
+The schema names three patterns the operator may apply per entry. The audit doc (`docs/operator-private/audits/2026-06-06-sub-goal-22-substrate-archaeology-audit.md`) recommends Pattern C hybrid as the default for the Sub-bet 22 scrub execution.
+
+- **Pattern A — Direct scrub.** Delete the operator reference outright. Substrate-archaeology shape preserved only in bassclef-upstream. Zero source-vocab residue in public substrate.
+- **Pattern B — Pseudonym substitution.** Map the source token to a neutral placeholder. Substrate-archaeology shape preserved in public; specifics anonymised. Consistent pseudonyms across sessions enable continuity.
+- **Pattern C — Hybrid.** Pattern A for sensitive-ip class items; Pattern B for structural class items. The audit doc names which categories fall on which side of the split.
+
+## Mapping file shape
+
+The authored mapping in bassclef-upstream follows this YAML shape.
+
+```yaml
+schema_version: 1
+generated_by: operator-attended write in bassclef-upstream
+generated_at: <ISO timestamp>
+mappings:
+  <source-vocabulary-token-1>:
+    pseudonym: <category>-<n>     # or null for full scrub
+    category: <category-label>    # from vocabulary table above
+    sensitivity: structural | sensitive-ip | operator-specific
+    notes: <optional operator commentary>
+  <source-vocabulary-token-2>:
+    # ...
+```
+
+Source-vocabulary tokens are authored exclusively in bassclef-upstream. Bassclef's schema doc never names them. The example above uses placeholder syntax (`<source-vocabulary-token-N>`) and a placeholder category (`<category-label>`); neither carries a real token.
+
+## Schema authoring discipline
+
+The two-file split lives or dies by discipline at the seam.
+
+- Bassclef authors the schema vocabulary and structural shape. The work happens in bassclef sessions and lands as a public PR.
+- Operator authors the initial mapping in bassclef-upstream via a separate write session. Bassclef never receives the populated mapping in a context-readable surface.
+- Bassclef's scrub script reads the mapping via the `SUNJ_LABS_ROOT` environment variable at execution time. The mapping never enters bassclef's git history.
+- Pseudonym key updates that change the schema vocabulary propagate via the forward-port registry (planned Sub-bet 22 Phase 3). Updates to the mapping itself stay in bassclef-upstream.
+
+## Adopter discipline
+
+Adopter repos that fork bassclef author their own pseudonym key in their own private repo. The schema ships in bassclef for everyone; the per-operator mapping stays operator-private. The pattern scales without forcing operators to share their source-vocabulary with each other or with bassclef.
+
+## Composes with
+
+- Sub-bet 22 substrate-archaeology audit — the substrate building block Sub-bet 22 declares.
+- Forward-port registry v1 (Sub-bet 14) — pseudonym key updates may propagate via registry.
+- Six Tier 1 substrate categories — pseudonym-key is the sixth (cameo engine, ADR pins, operator-narrative, operator-state, operator-portfolio specifics, pseudonym-key).
+- bassclef#811 — operator-private substrate restructure. This schema extends the same discipline.
+
+## Refs
+
+- bassclef#853 — parent ticket (Pre-launch substrate evolution).
+- bassclef#811 — operator-private substrate restructure parent.
+- `docs/operator-private/audits/2026-06-06-sub-goal-22-substrate-archaeology-audit.md` — Sub-bet 22 audit (categories only).
+- bassclef-upstream — host for the authored `pseudonym-key.yml`.

package/dist/lite/standards/sibling-validation-checklist.md

@@ -0,0 +1,181 @@
+---
+tier: lite
+description: Operator-runnable procedure for validating bassclef substrate end-to-end on a real consumer repo.
+---
+
+# Sibling-validation checklist
+
+Operator-runnable procedure for validating bassclef substrate end-to-end on a real consumer repo. Run after substantive substrate-evolution work where the new behavior depends on adopter inheritance.
+
+## When to run
+
+Run this checklist when one of:
+
+1. **New SessionStart hook ships** that should fire in adopter repos (e.g., the orientation gates from bassclef#1275)
+2. **New bassclef-configs.jsonc block ships** that adopters should opt into (e.g., `wiki_sync` from bassclef#1265)
+3. **New adopter-vendored template ships** under `strategy/templates/` (e.g., `bassclef-docs-sync.template.yml`)
+4. **Cold-adopter-inheritance discipline change** that propagates via `additionalDirectories` AND requires a mechanism check in the consumer
+5. **Quarterly substrate audit** — sanity-check that prior shipping still works end-to-end
+
+Skip when: pure bassclef-internal changes (operator narrative, retro chronicles, internal rules that don't propagate to adopters).
+
+## Before you start
+
+Pick the smallest consumer repo as the validation target. Smaller surface area means faster failure-mode isolation. Per the operator's consumer registry at `standards/bassclef-source-consumers.json`, smaller is better for first-pass validation.
+
+You need:
+
+- Local checkout of one consumer repo (e.g., `~/src/<org>/<consumer>/`)
+- `gh` authenticated with read+write access to that consumer
+- Bassclef synced to the consumer's `.bassclef-source.json` per `/onboard-repo` Phase 2.4
+- A scratch feature branch in the consumer (don't validate on main)
+
+## Procedure
+
+### Step 0 — Dispatch from bassclef's full path, not adopter-rooted relative (bassclef#1290)
+
+This checklist file lives in bassclef only — it's NOT vendored into adopter repos. Bassclef's `standards/`, `architecture/`, `design/`, `docs/` directories are accessed via the agent's `additionalDirectories` pointing at bassclef's checkout; they aren't synced into adopters' filesystems.
+
+If you dispatch this checklist from an adopter repo's shell, use bassclef's full path:
+
+```bash
+# Right
+bash $HOME/src/sunj-labs/bassclef/standards/sibling-validation-checklist.md
+# (or wherever your bassclef checkout lives)
+
+# Wrong (file not found — checklist isn't vendored into the adopter)
+bash standards/sibling-validation-checklist.md
+```
+
+The session-start hook (per bassclef#1290) clarifies this in its "Note:" line after the substrate-sync status, so adopters returning to a session see the access-model split before they hit the false "file not found" loop.
+
+When the agent (not the shell) needs to read this checklist, the `additionalDirectories` lookup resolves automatically — no full-path dispatch needed. This Step 0 only applies to operator dispatching the checklist from shell.
+
+### Step 1 — Snapshot current state
+
+In the consumer repo:
+
+```bash
+cd ~/src/<org>/<consumer>
+git checkout main && git pull
+git checkout -b scratch/bassclef-validation-$(date +%Y-%m-%d)
+```
+
+Record what you're validating against:
+
+- Bassclef commit currently in `.bassclef-source.json` `installed_sha` field
+- Date of last bassclef sync (`installed_at`)
+- Which substrate change you're testing
+
+### Step 2 — Force-sync bassclef to latest
+
+```bash
+bash .claude/hooks/bassclef-sync.sh --force
+```
+
+Verify the sync picked up the substrate change you're testing:
+
+```bash
+# For hook changes — verify the hook file is up to date
+diff .claude/hooks/session-reflection.d/<hook>.sh \
+     ~/src/<bassclef-checkout>/.claude/hooks/session-reflection.d/<hook>.sh
+
+# For bassclef-configs.jsonc changes — verify the new block is present
+grep -A3 "<new-block-name>" .claude/bassclef-configs.jsonc
+
+# For template changes — verify the template is present
+ls strategy/templates/<template-name>
+```
+
+### Step 3 — Wire the consumer's substrate.config.md (if needed)
+
+When the substrate change reads new fields from `substrate.config.md`, populate them:
+
+```bash
+# Example for bassclef#1275 orientation hooks parameterization
+grep -E "bassclef_evolution_label|bassclef_evolution_child_repos" substrate.config.md
+# If missing, add:
+echo "bassclef_evolution_label: bassclef-evolution" >> substrate.config.md
+echo "bassclef_evolution_child_repos: <comma-separated-sibling-repos>" >> substrate.config.md
+git add substrate.config.md && git commit -m "test: wire bassclef-evolution scan for sibling-validation"
+```
+
+### Step 4 — Trigger the substrate behavior
+
+For SessionStart hooks, the trigger is opening a new Claude Code session. Simulate by running the hook directly:
+
+```bash
+echo '{}' | bash .claude/hooks/session-reflection.d/<hook>.sh
+```
+
+For session-start-only behavior, exit the current session + start a new one in the consumer repo.
+
+For PreToolUse hooks, fire the relevant tool (Edit / Write / Bash / etc.) and verify the hook fires.
+
+For workflow templates, push the scratch branch (or use `workflow_dispatch` with `force_full_sync=true` if applicable):
+
+```bash
+git push -u origin scratch/bassclef-validation-$(date +%Y-%m-%d)
+gh workflow run <workflow-name>.yml --ref scratch/bassclef-validation-...
+```
+
+### Step 5 — Verify expected behavior
+
+Per the substrate change's acceptance criteria, verify:
+
+- Hook fires when expected (BLOCKED block emits, exit code matches, stderr structure matches `.claude/rules/blocked-items.md`)
+- Hook silent when expected (override path, marker present, etc.)
+- Workflow runs to completion + commits expected output
+- Config block read at runtime + default applied when absent
+- Adopter discipline applies (rule body loads via `additionalDirectories`, agent self-check fires)
+
+Record any mismatch — that's a real defect in the substrate that just shipped.
+
+### Step 6 — Tear down
+
+```bash
+# Restore consumer to pre-validation state
+cd ~/src/<org>/<consumer>
+git checkout main
+git branch -D scratch/bassclef-validation-$(date +%Y-%m-%d)
+git push origin --delete scratch/bassclef-validation-$(date +%Y-%m-%d) 2>/dev/null || true
+
+# Revert substrate.config.md test edits if they shouldn't persist
+git checkout main -- substrate.config.md  # only if test edits weren't merge-worthy
+```
+
+### Step 7 — Report
+
+Outcome:
+
+- **✅ Substrate works end-to-end** → comment on the source ticket(s) closing them with "validated on `<consumer-repo>` <date>". No further action.
+- **⚠️ Substrate works partially** → file follow-on ticket naming the gap; consumer-side workaround if needed.
+- **❌ Substrate broken end-to-end** → revert or hotfix the source PR; substrate-defect /promote per `.claude/rules/blocked-items.md` §"When resolution reveals a substrate defect".
+
+## Acceptance criteria for this checklist itself
+
+This checklist passes its own acceptance when:
+
+- Operator can read it cold and dispatch validation in under 10 minutes
+- Each step has a concrete verification command (no "make sure it works")
+- Three outcomes are explicit (pass / partial / fail)
+- Substrate-defect path cites `blocked-items.md` for mandatory /promote
+- Tear-down is explicit so validation doesn't leave consumer-repo state polluted
+
+## Why this checklist exists
+
+Bet 2026-06-20b shipped two adopter-inheritance changes (orientation gates fire for adopters per bassclef#1275 + wiki-sync adopter mechanism per bassclef#1265) with bassclef-side Tier 0 tests passing — but no end-to-end consumer validation ran. Substrate that hasn't been verified on a real consumer is substrate that ships on faith.
+
+This checklist is the operator-runnable depth-verification path. Future cold-adopter shipping bets can dispatch the checklist for end-to-end confirmation without re-deriving the steps each time.
+
+## Refs
+
+- `standards/bassclef-source-consumers.json` — registry of sibling repos (pick smallest for first validation)
+- `.claude/rules/blocked-items.md` — BLOCKED protocol if validation surfaces a defect
+- `.claude/rules/bassclef-models-discovery.md` — how consumer agents find bassclef's models
+- `.claude/skills/onboard-repo/SKILL.md` — Phase 2.x reads substrate.config.md fields
+- `.claude/hooks/bassclef-sync.sh` — the sync entry-point consumer hooks invoke
+- bassclef#1275 — first substrate change this checklist will retroactively validate
+- bassclef#1265 — second substrate change this checklist will retroactively validate
+- bassclef#1134 — Bassclef-as-Platform umbrella (the discipline this checklist supports)
+- Bet `docs/iteration-bets/2026-06-20c-validate-and-finish-arc.md` — this checklist's filing bet