@thebassclef/lite 1.0.3 → 1.1.0

package/dist/lite/standards/substrate-config-schema.md

@@ -0,0 +1,267 @@
+---
+tier: lite
+description: substrate.config.md is the single source of truth for external resource references in any bassclef-substrate repo.
+---
+
+# Substrate Config Schema
+
+`substrate.config.md` is the **single source of truth** for external
+resource references in any bassclef-substrate repo. Functionally, it
+is to bassclef what `.env` is to runtime code — the one place agents
+look for "where is X" without guessing, without consulting memory, and
+without hardcoding.
+
+## Why this exists
+
+Before this standard: resource references lived in three places —
+`substrate.config.md`, project memory, and hardcoded in skills. Agents
+had to check all three, confused them routinely, and produced wrong
+pushes (drafts pushed to corpus doc, etc.).
+
+Single-source-of-truth eliminates the ambiguity. Skills read only from
+`substrate.config.md`. Memory references resources only by field name,
+never by raw ID.
+
+## Typed suffix convention
+
+Every resource field in `substrate.config.md` uses a typed suffix so
+the agent never has to interpret the value:
+
+| Suffix | Meaning | Examples |
+|--------|---------|----------|
+| `*_doc_id` | Google Doc ID (a string that goes after `/document/d/`) | `journal_doc_id`, `changelog_doc_id`, `brand_corpus_doc_id` |
+| `*_sheet_id` | Google Sheets ID | `metrics_sheet_id` |
+| `*_url` | Full URL (http/https) | `staging_url`, `grafana_url`, `langfuse_url` |
+| `*_host` | Host without scheme | `db_host`, `redis_host` |
+| `*_repo` | GitHub repo reference (`owner/name`) | `parent_repo`, `deploy_repo` |
+| `*_repos` | Comma-separated list of GitHub repo references | `bassclef_evolution_child_repos` |
+| `*_path` | Filesystem path (absolute preferred) | `shared_artifacts_path` |
+| `*_channel_id` | Slack/Discord channel | `alerts_channel_id` |
+| `*_project_id` | Linear/Jira/Asana project | `linear_project_id` |
+| `*_token_name` | **Name of env var** holding a secret (never the secret itself) | `gh_token_name`, `anthropic_key_name` |
+| `*_reviewers` | GitHub usernames (comma-separated) for approval gates | `prod_approval_reviewers` |
+| `*_topology` | Architectural choice per `deployment-topology.md` | `staging_topology` |
+
+**Secrets NEVER in `substrate.config.md`.** That file is committed to
+git. Secrets live in `.env` (gitignored) or a secret manager. The
+convention stores the *name* of the env var (e.g.,
+`gh_token_name: GH_TOKEN`) so agents know which variable to read at
+runtime.
+
+**Secret lifecycle is tracked separately** in `substrate.secrets.md`
+(schema: `standards/state-spine/schemas/substrate-secrets.schema.json`;
+purpose: `standards/secrets-lifecycle.md`). That file holds rotation
+cadence, expiry dates, runbook paths, and health-check commands —
+references and metadata only, never values. The two files cross-reference
+each other; `substrate.config.md` answers *where* a resource lives,
+`substrate.secrets.md` answers *when* a credential expires and *how* to
+rotate it.
+
+## Single-source-of-truth rule
+
+1. **External resource IDs live ONLY in `substrate.config.md`.** Any
+   Google Doc ID, URL, repo reference, or similar pointer is a field
+   in this file.
+2. **Project memory references resources ONLY by field name**, never
+   by raw value. `brand_corpus_doc_id` is a valid memory reference;
+   `1gps7mmEYBCud...` is not.
+3. **Skills and hooks read ONLY from `substrate.config.md`** for
+   resource lookups. No hardcoded IDs in skill files, hook scripts,
+   or agent definitions.
+4. **If an agent needs a resource that isn't in
+   `substrate.config.md`**, the agent prompts the operator to add it
+   with a typed field name. Do not hardcode. Do not cache in memory.
+5. **Scaffolding on new repos prompts for each known field** during
+   `/autonomous start` setup.
+
+## Known fields (extensible)
+
+These fields are recognized by bassclef skills. Not all are required;
+uncommented defaults shown.
+
+```yaml
+# === Artifacts ===
+journal_doc_id: [per-repo draft Google Doc — pushes from /journal + session-end]
+changelog_doc_id: [per-repo weekly changelog Google Doc — pushes from /release-notes]
+brand_corpus_doc_id: [cross-repo brand team corpus — pushes from /journal-export]
+
+# === Environments ===
+deploy_targets:
+  local: true                  # always available
+  staging: false               # URL when configured
+  prod: false                  # URL when configured (hard gate — human-approved)
+
+# === Integrations (optional, per-project) ===
+langfuse_url: [tracing dashboard URL, if used]
+grafana_url: [metrics dashboard URL, if used]
+linear_project_id: [Linear project for ticket sync, if used]
+
+# === Bassclef substrate (bassclef repo only) ===
+# Consumer repos scanned by session-reflection for bassclef-evolution
+# issues. Keep in sync with .github/workflows/bassclef-template-sync.yml
+# matrix. Fallback when field absent: poa only.
+bassclef_evolution_child_repos: [comma-separated list of owner/name]
+
+# === Budget ===
+budget:
+  session_ceiling: [API burst $/session]
+  iteration_ceiling: [API burst $/iteration]
+  warning_threshold: 75%
+
+# === Secret references (names only, not values) ===
+anthropic_key_name: ANTHROPIC_API_KEY   # env var name, not the key
+gh_token_name: GH_TOKEN                  # env var name, not the token
+
+# === Hosting platform (REQUIRED in any consumer that ships a UI) ===
+#
+# Drives which deploy_* fields apply AND which adapter `/bind-subdomain`
+# loads. Every consumer running `/preview-build` or shipping production
+# UI MUST set this — the bassclef default is `amplify` per ADR-008
+# (frontend-stack) + POA + quorum precedent (single-provider portfolio
+# reduces operator cognitive load; AWS-native; cheap port to existing
+# AWS auth).
+#
+# Enum values (all five are valid; not all have shipped adapters yet):
+# - amplify:         use amplify_app_id + amplify_region + amplify_branch
+#                    (bassclef-recommended default; adapters live)
+# - ec2-tailscale:   use deploy_host + deploy_user + deploy_path (POA pattern)
+# - vercel:          adapter not yet shipped — schema reserves the slot
+# - netlify:         adapter not yet shipped — schema reserves the slot
+# - cloudflare-pages: adapter not yet shipped — schema reserves the slot
+# - none:            consumer explicitly opts out of preview/prototype
+#                    deployment. `/bind-subdomain` and `/launch-preview`
+#                    refuse on `none` unless --override given. Use for
+#                    docs-only repos (e.g., bassclef itself) or repos
+#                    that ship no UI surface.
+hosting_platform: amplify   # bassclef default; pick from enum above
+
+# --- Production tier (optional; declare when production differs from prototype) ---
+#
+# Per-tier hosting was added in bassclef#458 to resolve the POA case:
+# POA's prototypes deploy to amplify, but POA's production runs on
+# ec2-tailscale (per ADR-009) and predates the prototype pipeline.
+# Without `production_hosting_platform`, hosting_platform=amplify
+# implies POA's whole app is on amplify — wrong.
+#
+# `production_hosting_platform` is DECLARATIVE. /launch-preview and
+# /bind-subdomain operate on the prototype tier only and do not read
+# this field. It documents the production tier so operators (and
+# future tooling) know the production deploy is a separate concern.
+#
+# When unset, production tier inherits hosting_platform.
+production_hosting_platform: ec2-tailscale   # only set when production differs from prototype
+
+# --- Amplify-specific (when hosting_platform=amplify) ---
+#
+# `amplify_app_id` is the provisioning-indicator field (bassclef#523).
+# Set by `/provision-deploy-host` on success when the Amplify app is
+# created. Composer pre-flight (lib/composer-preflight.sh Check 6) reads
+# this field to verify provisioning happened — when missing or set to a
+# bracketed placeholder shape, /preview-build is BLOCKED with three-path
+# remediation (run /provision-deploy-host inline / re-dispatch with
+# --no-launch / explicit defer). Replaces the silent-defer-bind class
+# that caused POA's 2026-05-05 mobile session to merge variants but
+# never bind a subdomain.
+amplify_app_id: [e.g., d154l5usyc80nk]
+amplify_region: [e.g., eu-north-1]
+amplify_branch: [branch bound to domain, default: main]
+
+# --- EC2 + Tailscale-specific (when hosting_platform=ec2-tailscale) ---
+# See standards/deployment-topology.md for the SENTINEL_bassclef_pattern.
+#
+# `deploy_host` is the provisioning-indicator field (bassclef#523) —
+# Composer pre-flight Check 6 reads it to verify provisioning happened
+# (parallel to amplify_app_id for amplify). Same three-path remediation
+# applies when missing.
+deploy_host: [Tailscale hostname of prod box]
+deploy_user: [SSH user on prod box]
+deploy_path: [absolute path on box, e.g., /opt/poa]
+staging_deploy_host: [same or different Tailscale host]
+staging_deploy_path: [absolute path, e.g., /opt/poa-staging]
+staging_topology: same-box | separate-box    # Option A or B
+tailscale_tag: [CI tag, e.g., tag:ci]
+backup_path: [absolute path, e.g., /opt/backups]
+prod_approval_reviewers: [GitHub usernames comma-separated]
+
+# === Domain + DNS (when app binds a friendly URL) ===
+# See standards/domain-and-dns.md. Optional — skip if using platform
+# default URL (e.g., *.amplifyapp.com). Binding is automated via the
+# /bind-subdomain skill.
+subdomain: [e.g., myapp.apps.example.com]
+dns_provider: [cloudflare | route53]      # v1 supports cloudflare
+dns_zone: [e.g., example.com]
+cloudflare_token_env: [env var name holding CF API token, e.g., CLOUDFLARE_API_TOKEN]
+```
+
+## Migration from anti-patterns
+
+### Anti-pattern 1: raw IDs in project memory
+
+**Before**:
+```markdown
+# memory/reference_brand_corpus.md
+The brand team corpus lives at 1gps7mmEYBCud462Pn_DNf2mXa5Bj58NMjXUUDqWGIh0.
+```
+
+**After**:
+```markdown
+# memory/reference_brand_corpus.md
+The brand team corpus is configured as `brand_corpus_doc_id` in
+substrate.config.md. Agents should always read from there, never
+reference the raw ID directly.
+```
+
+### Anti-pattern 2: hardcoded IDs in skills
+
+**Before** (in `.claude/skills/journal-export/SKILL.md`):
+```bash
+npx tsx scripts/push-to-gdoc.ts \
+  --file docs/journal-corpus/corpus.md \
+  --doc-id 1gps7mmEYBCud462Pn_DNf2mXa5Bj58NMjXUUDqWGIh0
+```
+
+**After**:
+```bash
+DOC_ID=$(grep "^brand_corpus_doc_id:" substrate.config.md | awk '{print $2}')
+npx tsx scripts/push-to-gdoc.ts \
+  --file docs/journal-corpus/corpus.md \
+  --doc-id "$DOC_ID"
+```
+
+Or equivalently, skills document the field name in prose and require
+the agent to look it up at runtime:
+
+```markdown
+## Step 7: Push to Google Docs
+
+Push to `brand_corpus_doc_id` from `substrate.config.md`:
+
+\`\`\`bash
+npx tsx scripts/push-to-gdoc.ts --file docs/journal-corpus/corpus.md \
+  --doc-id $(grep "^brand_corpus_doc_id:" substrate.config.md | awk '{print $2}')
+\`\`\`
+```
+
+### Anti-pattern 3: scattered fields
+
+If an app repo adds a new resource (e.g., a Retool dashboard URL)
+and stores it in a README comment, an inline skill comment, or a
+hook variable — that's the anti-pattern. All such values go in
+`substrate.config.md` with the typed suffix.
+
+## Related rules
+
+- `.claude/rules/substrate-config-schema.md` — enforces this standard
+  at agent behavior level (read from config, don't hardcode, don't
+  cache in memory)
+- `.claude/skills/autonomous/SKILL.md` — prompts for each known field
+  during scaffold
+- `.claude/skills/substrate-check/SKILL.md` — validates substrate.config.md
+  has required fields for the repo type
+
+## Versioning
+
+When bassclef adds a new known field type, the schema here is the
+authoritative list. App repos update their `substrate.config.md` to
+add the new field during next `/autonomous start` scaffold pass (the
+skill surfaces missing fields and prompts for values).

package/dist/lite/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/dist/lite/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` (standard tier) — 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/dist/lite/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