@thebassclef/lite 0.0.1 → 0.1.0

package/substrate/standards/tech-stack-config.md

@@ -0,0 +1,109 @@
+---
+tier: lite
+description: "The tech_stack: block inside .claude/bassclef-configs.jsonc declares the adopter's primary tech stack."
+---
+
+# Tech Stack Configuration
+
+The `tech_stack:` block inside `.claude/bassclef-configs.jsonc` declares the adopter's primary tech stack. Stack-bound rules + standards in bassclef read this block to pick the right per-stack discipline.
+
+Without `tech_stack:`, stack-bound rules fall back to their default (which is operator's stack — TypeScript + Next.js + Prisma + EC2-Tailscale). Non-matching adopters then see false-fires: Prisma rules at SQLAlchemy adopters, Next.js API conventions at FastAPI adopters, etc. The tech_stack block is what stops the bleed.
+
+Schema source: `standards/state-spine/schemas/tech-stack.schema.json`. This file documents the semantics; the schema documents the shape.
+
+## When this block is read
+
+| Surface | What it does with the block |
+|---|---|
+| `.claude/rules/schema-management.md` | Reads `tech_stack.orm:` to load the matching sibling under `standards/migration-discipline/<orm>.md` |
+| `.claude/rules/api-conventions.md` | Frontmatter `tech_stack_match: { frontend: nextjs }`; rule fires only when matched |
+| `.claude/rules/sdlc-gates.md` | Frontmatter `tech_stack_match: { lang: typescript }`; rule fires only when matched |
+| `.claude/rules/new-dependency-check.md` | Reads `tech_stack.pkg_manager:` to load the matching sibling under `standards/dependency-discipline/<pkg_manager>.md` |
+| `standards/frontend-stack.md` (now thin pointer) | Reads `tech_stack.frontend:` to direct adopter to the matching `standards/stack-patterns/<stack>.md` |
+| `standards/deployment-topology.md` (now thin pointer) | Reads `tech_stack.deploy:` to direct adopter to the matching `standards/deployment-topology-patterns/<deploy>.md` |
+| `/onboard-repo` Phase 2.x | Auto-detects + asks; writes the block |
+| `/demo` first dispatch | If block absent, prompts the operator (bassclef#1126 / #1127) |
+| `/launch` Phase -1 Check 7 | Refuses dispatch when block absent — `/launch` needs real stack tokens to produce real decompositions |
+
+## Fields
+
+All fields are optional at the schema level; specific rules fail open (or fall back to operator's default) when their referenced field is absent. Adopters declare what they need.
+
+| Field | Enum | Notes |
+|---|---|---|
+| `lang` | typescript / python / go / ruby / java / rust / none | Primary language family. Drives sdlc-gates Path B. |
+| `frontend` | nextjs / react-vite / sveltekit / vue / svelte / django / rails / fastapi / none | Frontend framework. Drives api-conventions Path B + frontend-stack routing. |
+| `backend` | nodejs / python / ruby / go / rust / deno / none | Backend runtime. Drives sdlc-gates Path B. |
+| `orm` | prisma / sqlalchemy / gorm / alembic / active-record / drizzle / none | ORM. Drives schema-management Path A routing. |
+| `pkg_manager` | npm / pnpm / yarn / pip / poetry / cargo / gem / go-mod | Package manager. Drives new-dependency-check Path A routing. |
+| `deploy` | ec2-tailscale / vercel / netlify / fly / render / gcp-cloud-run / amplify / none | Deploy topology. Drives deployment-topology Path C routing. |
+| `declared_at` | ISO 8601 date | Provenance — last declared. |
+| `declared_via` | onboard-repo / demo-prompt / manual / migrated | Provenance — how declared. |
+| `rationale` | string | Optional operator-narrative; one paragraph why. |
+
+## Auto-detection at `/onboard-repo`
+
+When `/onboard-repo` runs, it inspects the adopter repo for stack signals and pre-fills the block:
+
+| File present | Suggests |
+|---|---|
+| `package.json` with `"next"` dep | `frontend: nextjs`, `lang: typescript` (if tsconfig.json), `pkg_manager: npm/pnpm/yarn` (detect lockfile) |
+| `package.json` with `"prisma"` dep | `orm: prisma` |
+| `package.json` with `"drizzle-orm"` dep | `orm: drizzle` |
+| `requirements.txt` or `pyproject.toml` | `lang: python` |
+| pyproject.toml with `sqlalchemy` | `orm: sqlalchemy` |
+| pyproject.toml with `alembic` | `orm: alembic` |
+| `Gemfile` | `lang: ruby`, `pkg_manager: gem` |
+| `Gemfile` with `rails` | `frontend: rails`, `backend: ruby`, `orm: active-record` |
+| `go.mod` | `lang: go`, `pkg_manager: go-mod` |
+| `Cargo.toml` | `lang: rust`, `pkg_manager: cargo` |
+| `vercel.json` or `.vercelignore` | `deploy: vercel` |
+| `netlify.toml` | `deploy: netlify` |
+| `fly.toml` | `deploy: fly` |
+| `render.yaml` | `deploy: render` |
+| `app.yaml` (App Engine) or `cloudbuild.yaml` | `deploy: gcp-cloud-run` |
+| `amplify.yml` | `deploy: amplify` |
+| `infrastructure/` with terraform + EC2 + Tailscale | `deploy: ec2-tailscale` |
+
+When auto-detection is ambiguous (e.g., monorepo with multiple stacks), the operator picks. When auto-detection finds nothing recognized, the block stays empty and stack-bound rules fall back to operator defaults.
+
+## Recommended defaults
+
+For operators starting fresh (no existing repo), bassclef recommends:
+
+```jsonc
+{
+  "tech_stack": {
+    "lang": "typescript",
+    "frontend": "nextjs",
+    "backend": "nodejs",
+    "orm": "prisma",
+    "pkg_manager": "pnpm",
+    "deploy": "vercel",
+    "declared_at": "2026-06-18",
+    "declared_via": "demo-prompt"
+  }
+}
+```
+
+Rationale: bassclef's most-tested portfolio stack. Cleanest path through `/launch` chain, the existing rule + standard set, and the bassclef-sync ergonomics. Operators on other stacks override at `/onboard-repo` time.
+
+## What this block does NOT carry
+
+- **Queue / cache / auth / email infrastructure** — those are follow-on triggers per bassclef#1127; `/spec` detects need from use-case language and prompts at spec-time.
+- **Build tooling specifics** (webpack vs turbopack, etc.) — too granular; rules don't yet route on this.
+- **Runtime / version pins** (Node 20 vs 22, Python 3.11 vs 3.12) — `package.json engines` and equivalent files hold this.
+
+## Distinct from
+
+- **`substrate.config.md`** — that holds resource references (Google Doc IDs, URLs, env-var names). Tech stack lives in `bassclef-configs.jsonc` because it's an *adoption* setting that controls bassclef's rule routing.
+- **`standards/bassclef-platform.yml`** — org-baseline platform-engineering config (AWS account, IAM roles, etc.). Per-repo tech stack is finer-grained.
+- **`design/object-model.md` Stack object** — that's about the *runtime* (which agents, which deploy target). This block is about *language + framework + ORM* — the discipline-routing dimension.
+
+## Refs
+
+- bassclef#1127 — parent ticket (tech_stack discovery in /onboard-repo + this schema)
+- bassclef#1133 — ARCH-T0 stack-leakage audit (the failure mode this block stops)
+- bassclef#1126 — `/demo` skill split (first-dispatch prompt surface)
+- WU-2 of bet `docs/iteration-bets/2026-06-18a-public-adopter-leverage-longrun.md` — ships this primitive
+- Composes with: standards/bassclef-configs-schema.md (parent config), all WU-5 through WU-10 rewrites in bet 2026-06-18a

package/substrate/standards/tier-dependency-analysis.md

@@ -0,0 +1,167 @@
+---
+tier: lite
+description: Reference doc for the tier-dependency-audit subsystem.
+---
+<!-- andon-allow: operator-private -->
+<!-- andon-allow: bassclef-upstream -->
+
+# Tier dependency analysis
+
+Reference doc for the tier-dependency-audit subsystem. Sister to `standards/tier-tag-schema.md` — that standard names the `tier:` field per file; this standard names the graph walk that audits whether every legitimate `<tier>` dependency carries the tag AND whether every file in the release matches the graph.
+
+## Purpose
+
+The release script (`scripts/release-to-bassclef.sh`) walks `ALLOWED_PATHS` and applies a tier check on `.md` and `.sh` files inside primitive surfaces (L466-505). Two branches ship files without a tier check:
+
+- **L507-513** — non-md/sh files inside primitive surfaces (JSON, TXT, fixtures, subdir READMEs)
+- **L514-518** — non-primitive paths (top-level files, CLAUDE.md, top-level manifests)
+
+These two branches allow accidental leaks. Prior release attempt (release-2026-08-15-83778faf) shipped 61 cache binaries and one `.DS_Store` via one of these branches. Adopter public bassclef now carries 827 tracked orphan files.
+
+This subsystem replaces the exempt-list patch pattern (Parnas information hiding of *what* to exclude) with an inclusion graph (Nygard fail-safe: only what the graph says is legit ships).
+
+## Reusable across tiers
+
+One subsystem serves all tiers. The tier arg picks which root set + adopter-runtime dependency list to use. The walk algorithm is the same. Build it once for `lite`. Add tier-runtime dependency lists for `standard`, `standard-pro`, `ultra`, `upstream` as those tiers mature.
+
+## Input contract
+
+```
+scripts/analyze-tier-dependencies.sh <tier>
+```
+
+- `<tier>` — one of `lite | standard | standard-pro | ultra | upstream`
+- Reads sources from bassclef-upstream working tree
+- Reads adopter-runtime dependency list from `standards/tier-runtime-deps/<tier>.md`
+- Reads release-script include set from `scripts/release-to-bassclef.sh --dry-run`
+- Exits 0 on classification complete; exit 2 on malformed input; exit 3 on missing tier-runtime-deps file
+
+## Output contract
+
+`docs/dependency-audits/<YYYY-MM-DD>-<tier>.md` — markdown table with 5 buckets (Bucket 2 splits into 2a + 2b per ADR-043 D1 + canvas 2026-07-19-bassclef-lite.md L76):
+
+| Bucket | Meaning | Fix action |
+|---|---|---|
+| 1. Tagged | File has `tier: <tier>` frontmatter or header. Ships correctly. | None |
+| 2a. Missing tag | File has NO tier tag at all AND is a legit `<tier>` dep per graph walk. Safe mechanical add. | Add `tier: <tier>` frontmatter or header via helper `scripts/apply-bucket2-tier-tags.sh` |
+| 2b. Chain-snap risk | File has a tier tag for a DIFFERENT tier BUT graph walk says `<tier>` depends on it. This is canvas L76's "chain snaps at every hop" — bassclef-lite fetch would break if this file is missing. | Per-file cure per canvas Q1+Q2: (i) promote the file to `<tier>` standalone, (ii) inline it into the calling `<tier>` file per Ousterhout deep modules, OR (iii) determine the graph walk over-included (reference in doc but not runtime dep). |
+| 3. Accidental leak | File currently ships but is not in the graph. | Remove from bassclef-upstream + extend .gitignore |
+| 4. Missing from release | File is in the graph but not in the release-script include set. | Extend release script `ALLOWED_PATHS` or fix a filter |
+
+Each bucket lists the affected files with one-line reasons. The doc also carries a summary count per bucket and a recommended fix order (bucket 4 first if any, then 2a mechanical, then 2b per-file review, then 3).
+
+### Why the 2a/2b split matters
+
+Before the split, bucket 2 conflated two distinct classes. Files tagged `tier: standard` that are legit `<lite>` deps per graph walk landed in bucket 2 alongside files with no tag. Bulk "add `tier: lite`" would retag `standard` files as `lite` — a maturity signal shift that bloats bassclef-lite (defeats the slimmed-down goal for Sam/Louis/Adam Sharpe per canvas Stage 1).
+
+Per ADR-043 D1:
+- `tier: lite` = explicit inclusion in bassclef-lite npm ship
+- `tier: standard` = deliberate exclusion from bassclef-lite
+
+A file tagged `standard` is deliberately non-lite. When the graph walk from a lite root set discovers such a file as a dep, that's a chain-snap risk that needs per-file operator judgment — not a bulk retag.
+
+## Walk algorithm
+
+Four data sources; union → compare against actual release set.
+
+**Source 1 — root set (tagged).** Files that already carry `tier: <tier>` frontmatter or `# tier: <tier>` header. Seed for the walk.
+
+**Source 2 — reference walk (BFS from root set).** For each file in the queue, extract references to other files. Add each new discovery to the queue. Repeat until queue empty.
+
+Reference shapes to extract:
+
+- `composes_with:` frontmatter — other skills or rules named
+- `source lib/<name>.sh` in hook headers — lib files sourced
+- `additionalDirectories:` in settings.json — paths the adopter loads
+- Cross-file grep `bash scripts/<name>.sh` in hook bodies — scripts invoked
+- `@luminary <slug>` refs — luminary files
+- `see standards/<name>.md` refs — standard files
+- `see .claude/rules/<name>.md` refs — rule files
+
+**Source 3 — adopter-runtime dependencies (tier-specific).** Files the adopter needs at runtime that don't fall out of the reference walk. Lives at `standards/tier-runtime-deps/<tier>.md`. For lite:
+
+- `CLAUDE.md`
+- `bassclef-configs.jsonc`
+- `.bassclef-source.json` template
+- `.claude/settings.json` template
+- `presence/install/*.template.sh`
+- `LICENSE`
+- `README.md`
+- `.github/workflows/bassclef-*.yml`
+- `lite-manifest.json`
+- `bassclef-wiring-manifest.json`
+
+**Source 4 — release-script include set (ACTUAL).** Runs `scripts/release-to-bassclef.sh --dry-run` and parses the `INCLUDE_LIST` output.
+
+## Classification rule
+
+Let `INTENDED = Source 1 ∪ Source 2 ∪ Source 3`.
+
+Let `ACTUAL = Source 4`.
+
+- `INTENDED ∩ ACTUAL, has tag` → Bucket 1 (Tagged)
+- `INTENDED ∩ ACTUAL, no tag` → Bucket 2 (Missing tag)
+- `ACTUAL \ INTENDED` → Bucket 3 (Accidental leak)
+- `INTENDED \ ACTUAL` → Bucket 4 (Missing from release)
+
+## Combined-tier mode
+
+Single-tier audit surfaces one problem: bucket 3 (accidental leak) mixes true leaks with files legit-tagged for OTHER tiers. A `standard` file shipping in the actual release set is not a `lite` leak — it belongs in the release for standard adopters. Single-tier audit calls it bucket 3 anyway because the file is `ACTUAL \ INTENDED_lite`.
+
+Combined-tier mode fixes the class. The script accepts a special arg `all` (or a comma list like `lite,standard,upstream`):
+
+```
+scripts/analyze-tier-dependencies.sh all
+scripts/analyze-tier-dependencies.sh lite,standard
+```
+
+**Classification under combined-tier:**
+
+Let `INTENDED_ALL = INTENDED_lite ∪ INTENDED_standard ∪ INTENDED_standard-pro ∪ INTENDED_ultra ∪ INTENDED_upstream` (or the user-supplied subset).
+
+- `INTENDED_ALL ∩ ACTUAL, has any tier tag` → Bucket 1 (Tagged)
+- `INTENDED_ALL ∩ ACTUAL, no tag` → Bucket 2 (Missing tag; carries per-tier reason for which tier each file belongs to)
+- `ACTUAL \ INTENDED_ALL` → Bucket 3 (True accidental leak — belongs in no tier's graph)
+- `INTENDED_ALL \ ACTUAL` → Bucket 4 (Missing from release; carries per-tier reason)
+
+**When to use which mode:**
+
+| Mode | Use case |
+|---|---|
+| Single-tier | Curate one tier's manifest; find lite deps missing tag; produce bucket 2 for one tier's tagging pass |
+| Combined-tier | Identify true accidental leaks safe to remove from bassclef-upstream; produce bucket 3 for cleanup |
+
+Bucket 2 outputs from single-tier and combined-tier agree for that tier's legit missing tags. Bucket 3 differs — single-tier over-counts leaks; combined-tier gives the honest count.
+
+**Output naming:**
+
+- Single-tier: `docs/dependency-audits/<YYYY-MM-DD>-<tier>.md`
+- Combined-tier: `docs/dependency-audits/<YYYY-MM-DD>-combined-<tier-list>.md` (e.g., `2026-08-17-combined-all.md`)
+
+## Composition
+
+- Sister to `standards/tier-tag-schema.md` — that standard names *what* the tag is; this standard names *how* to audit tag coverage per tier
+- Consumed by `.claude/skills/tier-dependency-audit/SKILL.md` — user-invocable wrapper
+- Composed with `scripts/release-to-bassclef.sh` — the ACTUAL set comes from `--dry-run`
+- Composed with `.claude/rules/we-dont-break-adopters.md` (ADR-031) — the audit surfaces adopter-observable classes for careful handling
+- Composed with `.claude/rules/mechanism-fidelity.md` — the subsystem IS the mechanism paired with tier-tag-schema
+
+## Anchor luminaries
+
+- `@luminary david-parnas` — information hiding: consumers see tier arg + classified manifest, not the walk algorithm
+- `@luminary john-ousterhout` — deep module: one script, many tier callers
+- `@luminary michael-nygard` — fail-safe default: the graph says what's legit; L514 tightening rejects untagged by default after buckets 2+3 clear
+- `@luminary michael-feathers` — characterization tests: fixture graph pins subsystem behavior in Tier 0 test
+
+## Refs
+
+- Goal doc `docs/iteration-bets/2026-08-17a-tier-dependency-audit-subsystem.md`
+- Sister `standards/tier-tag-schema.md`
+- ADR-029 release pipeline
+- ADR-031 we-dont-break-adopters
+- ADR-037 release pipeline integrity check
+- ADR-035 substrate-as-system
+
+## Retirement condition
+
+This standard retires only if the tier system itself retires. Walk sources may extend (new reference shapes as substrate evolves); the four-bucket classification and BFS shape survive any specific source extension.

package/substrate/standards/tier-runtime-deps/lite.md

@@ -0,0 +1,57 @@
+---
+tier: lite
+description: Per standards/tier-dependency-analysis.md Source 3.
+---
+<!-- andon-allow: operator-private -->
+<!-- andon-allow: bassclef-upstream -->
+
+# Tier runtime deps — lite
+
+Per `standards/tier-dependency-analysis.md` Source 3. Files the lite adopter needs at runtime that do not fall out of the reference walk from the root set.
+
+Consumed by `scripts/analyze-tier-dependencies.sh lite` when computing the INTENDED set.
+
+## Files
+
+The subsystem parses the fenced code block below. One relative path per line. Blank lines and lines starting with `#` are comments.
+
+```
+CLAUDE.md
+LICENSE
+README.md
+bassclef-configs.jsonc
+lite-manifest.json
+bassclef-wiring-manifest.json
+substrate.config.md
+.bassclef-source.json.template
+.claude/settings.json.template
+presence/install/bassclef-sync.dispatcher.template.sh
+presence/install/bassclef-sync.template.sh
+.github/workflows/bassclef-pr-ci.yml
+.github/workflows/bassclef-s3-publish.yml
+.github/workflows/bassclef-docs-sync.yml
+```
+
+## Rationale per file
+
+- **CLAUDE.md** — session-start context load for the adopter agent
+- **LICENSE** — Apache 2.0 per ADR-045
+- **README.md** — first-touch doc for cold adopters
+- **bassclef-configs.jsonc** — adopter-editable config surface
+- **lite-manifest.json** — tier snapshot for `bassclef-cli`
+- **bassclef-wiring-manifest.json** — hook wiring reference per ADR-051 rename
+- **substrate.config.md** — external resource references per `standards/substrate-config-schema.md`
+- **.bassclef-source.json.template** — source pointer for consumer repos
+- **.claude/settings.json.template** — hook wiring template
+- **presence/install/*.template.sh** — install and dispatcher templates per ADR-032
+- **.github/workflows/bassclef-*.yml** — CI + publish + docs-sync workflows adopters inherit
+
+## Extending this list
+
+When a new lite runtime dep lands, add the path plus a one-line rationale. The subsystem re-parses on next audit run. No code change needed.
+
+## Refs
+
+- Parent standard `standards/tier-dependency-analysis.md`
+- Goal doc `docs/iteration-bets/2026-08-17a-tier-dependency-audit-subsystem.md`
+- Sister future: `standards/tier-runtime-deps/{standard,standard-pro,ultra,upstream}.md` as those tiers mature

package/substrate/standards/tier-tag-schema.md

@@ -0,0 +1,155 @@
+---
+tier: lite
+description: Per-file maturity-signal field that governs flow from bassclef-upstream (upstream experimental) → bassclef (public hardened release mirror).
+---
+<!-- andon-allow: operator-private -->
+<!-- andon-allow: bassclef-upstream -->
+
+# Tier-tag schema
+
+Per-file maturity-signal field that governs flow from `bassclef-upstream` (upstream experimental) → `bassclef` (public hardened release mirror). The release script (`scripts/release-to-bassclef.sh`) reads this field on every substrate primitive and decides whether to include it in the release.
+
+## Field
+
+- **Name:** `tier`
+- **Location per file type** (extended 2026-08-17 per ADR-052 D6):
+  - `.md` files (skills, luminaries, rules, ADRs, standards): YAML frontmatter, recommended as the first line after the opening `---`
+  - `.sh` files (hooks, scripts): header comment `# tier: <value>` on line 2 (after the shebang)
+  - `.yml`, `.yaml` files: comment `# tier: <value>` on line 1
+  - `.jsonc` files: line comment `// tier: <value>` on line 1
+  - `.json` (pure) files: underscored key `"_tier": "<value>"` in the top object (underscore signals metadata field per common convention)
+  - LICENSE, plain text: external entry in `standards/tier-file-allowlist.json`
+- **Values (extended 2026-08-17 per ADR-043 D1 amendment):** `upstream | archive | unknown | lite | standard | standard-pro | ultra`
+- **Default for untagged legacy files:** untagged .md and .sh files BLOCK release per #1209. Untagged JSON / YAML / LICENSE ship by default via ALLOWED_PATHS (per `scripts/release-to-bassclef.sh:508-513`).
+- **Required on:** skills, rules (enforced by `substrate-clarity-gate.sh`). Luminaries, hooks, ADRs, standards SHOULD carry it; strict enforcement deferred to a follow-on.
+
+## Scope — where the field applies
+
+The `tier:` field applies to substrate building-block surfaces whose maturity governs release-script filtering. It does not apply to documentation surfaces that ship unconditionally.
+
+**Applies to (field required or SHOULD carry):**
+
+| Surface | Path pattern | Enforcement |
+|---|---|---|
+| Skills | `.claude/skills/*/SKILL.md` | `substrate-clarity-gate.sh` BLOCKs if missing |
+| Rules | `.claude/rules/*.md` | `substrate-clarity-gate.sh` BLOCKs if missing |
+| Luminaries | `.claude/luminaries/*.md` | SHOULD carry; strict enforcement deferred |
+| Agents | `.claude/agents/*.md` | SHOULD carry; strict enforcement deferred |
+| Hooks | `.claude/hooks/*.sh` | SHOULD carry; strict enforcement deferred |
+| ADRs | `architecture/decisions/ADR-*.md` | SHOULD carry; strict enforcement deferred |
+| Standards | `standards/*.md` | SHOULD carry; strict enforcement deferred |
+| Strategy | `strategy/*` | SHOULD carry; strict enforcement deferred |
+
+These paths match the building-block list in `scripts/release-to-bassclef.sh:254-263`. The release script reads the field per file and filters accordingly.
+
+**Does NOT apply to (field MUST NOT appear):**
+
+| Surface | Path pattern | Enforcement |
+|---|---|---|
+| Release notes | `docs/release-notes/*.md` | `substrate-clarity-gate.sh` BLOCKs if `tier:` present |
+| Roadmaps | `docs/roadmaps/*.md` | `substrate-clarity-gate.sh` BLOCKs if `tier:` present |
+| Canvases | `docs/canvases/*.md` | `substrate-clarity-gate.sh` BLOCKs if `tier:` present |
+
+These paths ship unconditionally via the release script's fallback branch (`scripts/release-to-bassclef.sh:367-372` — "ship per allowed-path. No per-file tier needed"). Adding `tier:` there signals a distribution filter that does not exist.
+
+**Rationale.** Per /luminary consult 2026-07-31 (Norman signifier discipline + Brooks conceptual integrity + Linus adopter contract): a field with two meanings across the substrate breaks coherence. A field that signals distribution but does not filter distribution misleads readers. Documentation surfaces describe shipped work; they are not themselves substrate building blocks whose maturity gates release.
+
+**Legacy sweep.** Two release-notes shipped with `tier: standard` before this scope was clarified: `docs/release-notes/2026-07-10-v0.2.0.md` and `docs/release-notes/2026-07-10-v0.2.1.md`. Both swept in the same PR that added this Scope subsection.
+
+## Value semantics
+
+| Value | Ships in release? | Meaning to adopter |
+|---|---|---|
+| `private` | **No** | Operator-private even outside `docs/operator-private/`. Belt-and-braces per-file gate. |
+| `lite` | Yes | Early-access; minimal viable; expect rough edges. Signals "use it, file issues, expect change." |
+| `standard` | Yes (bassclef + bassclef-ultra) | Portfolio operator's product; adds atomic skills lite embeds. Ships in bassclef + bassclef-ultra. NOT in bassclef-lite. |
+| `standard-pro` | Conditional (with license key) | Extends `standard` with pre-release content. Ships to adopters whose `.bassclef-source.json` carries `tier_extension: standard-pro` AND `license_key`. Added bet 24b Step 2 (goal 20a Task 3.2). Iteration 3 wires the gate; Iteration 1 accepts the tag only. |
+| `ultra` | Yes (bassclef-ultra only) | Reflective intelligence; Voyage-driven skills. Ships in bassclef-ultra only. |
+| `archive` | **No** | Kept for historical reference or debugging. Not part of active development. Filters out at release. Added 2026-08-17 per ADR-043 D1 amendment. |
+| `unknown` | **No** | Awaiting operator triage. Not yet classified. Filters out at release. Should be resolved. Added 2026-08-17 per ADR-043 D1 amendment. |
+
+## Maturity progression (lite → standard → ultra)
+
+Promotion is **communicative, not mechanical.** A primitive that's ready for the next tier gets the frontmatter edited in a normal commit. The release script ships everything that isn't `private`; the tier name tells adopters how mature the file is.
+
+```
+new primitive  →  lite  →  standard  →  ultra
+                    ↓        ↓           ↓
+              ships, with maturity signal in name
+```
+
+There is no separate `/promote --tier-up` skill; if one is needed it'll be added when the operator notices friction.
+
+## Gating
+
+**Note (2026-08-17):** amended per ADR-052 D1 — concentric inclusion is the model. Each product ships every file tagged at a smaller-tier value plus its own value.
+
+The release script per tier:
+
+1. Reads `tier:` per file per format (see "Tier tag per file format" below)
+2. If `tier ∈ {private, upstream, archive, unknown}` → **exclude from every downstream release**
+3. If `tier == lite` → include in bassclef-lite + bassclef + bassclef-ultra
+4. If `tier == standard` → include in bassclef + bassclef-ultra (NOT bassclef-lite)
+5. If `tier == standard-pro` → include only when adopter carries `tier_extension: standard-pro` + `license_key`
+6. If `tier == ultra` → include in bassclef-ultra only
+7. If `tier == <anything else>` → refuse the release with "INVALID tier" error
+8. If `tier == <empty>` on ANY file inside ALLOWED_PATHS → BLOCK release (add a tier tag per file format)
+
+## Tier tag per file format
+
+Every file format that ships (or could ship) inside ALLOWED_PATHS carries a tier tag in a format the file's parser accepts:
+
+| Format | Tag mechanism | Example |
+|---|---|---|
+| `.md` | YAML frontmatter `tier: X` | `---\ntier: lite\n---` |
+| `.sh`, `.py` | header comment `# tier: X` (line 2 after shebang) | `#!/usr/bin/env bash\n# tier: standard` |
+| `.json` (data files) | top-level `"_tier": "X"` field | `{"_tier": "upstream", "data": ...}` |
+| `.json` (JSON Schema files) | `"$comment": "tier: X"` — because `$comment` is a recognized draft-2020-12 keyword; top-level unknown keys fail ajv strict mode | `{"$comment": "tier: standard", "$schema": ...}` |
+| `.jsonc` | header comment `// tier: X` | `// tier: standard\n{...}` |
+| `.yml`, `.yaml` | frontmatter `tier: X` OR header comment `# tier: X` | `---\ntier: lite\n---` |
+| Other text | header comment appropriate to format | — |
+
+Non-taggable formats (binary files) go into `standards/tier-file-allowlist.json` external allowlist per ADR-052 D6.
+
+Prior default-ship rule for non-md/sh files (superseded by this table 2026-08-20 per Wave 4 Option C Step 4): removed. Every file inside ALLOWED_PATHS now carries an explicit tag per format.
+
+## Defense in depth — path exclusion registry
+
+Files whose path matches an entry in `standards/path-exclusion-registry.json` are excluded from every release regardless of any inner `tier:` value. The path wins. Consumers (release script, audit tools) read the registry as the single source of truth for path-based exclusion classes: `session-runtime`, `operator-private`, `test-only`, `operator-internal-rd`, `prototype`, `config-per-repo`, `ephemeral-transient`.
+
+See `standards/path-exclusion-registry.md` for classes + rationale per entry + how to add a new exclusion.
+
+The path-exclusion registry supersedes the prior inline `case` statement in `scripts/release-to-bassclef.sh` L415-460. The refactor to read the registry ships as a separate PR after this schema amendment.
+
+## Validation
+
+The `substrate-clarity-gate.sh` hook enforces on skill + rule edits:
+1. `tier:` present (BLOCK if missing)
+2. `tier:` value ∈ `{private, lite, standard, standard-pro, ultra}` (BLOCK if other value)
+3. `tier:` accepted as a recognized field (no `UNKNOWN_FIELDS` warning)
+
+The `bassclef-source-config-validate.sh` hook validates `.bassclef-source.json` `tier_extension` field against the same enum (minus `private` — adopters cannot opt into private content).
+
+Override hatches:
+- `SKIP_SUBSTRATE_CLARITY=1` (full hook bypass; logged via trace-helper)
+- Allowlists: `.claude/hooks/substrate-clarity-allowlist.txt`, `.claude/hooks/substrate-frontmatter-allowlist.txt`
+
+## Backfill provenance
+
+- 392 primitives initially backfilled with `tier: public` 2026-06-21 (WU-1 commits 73c8fce + bc00f99 + e28d73f)
+- 36 luminaries added to bassclef-upstream 2026-06-21 with `tier: public` (commit 54a65aa, WU-0 gap fix)
+- 9 presence files added 2026-06-21 with `tier: public` (commit cf53a5f)
+- All `tier: public` → `tier: standard` 2026-06-21 (commit TBD this session) per operator's rename to lite/standard/ultra vocabulary
+
+## Relationship to other tier concepts
+
+- `tiers:` (plural, in skill frontmatter): skill MODES like `[medium, full]` for /launch sizes. Distinct from `tier:` (release maturity).
+- `model_tier:` (in skill frontmatter): which Claude model the skill prefers. Distinct from `tier:`.
+
+## See also
+
+- `architecture/dual-repo-flow.md` — the full architecture this tier field operationalizes
+- `architecture/decisions/ADR-029-release-pipeline.md` — formalizes the release script that consumes this field
+- `architecture/decisions/ADR-030-adopter-inbox-flow.md` — the ingestion direction; doesn't read tier but operates inside the same bounded-context model
+- `scripts/release-to-bassclef.sh` — the consumer
+- `.claude/hooks/substrate-clarity-gate.sh` — the gate that enforces this field on skill + rule