@thebassclef/lite 0.0.1 → 0.1.2

package/substrate/standards/bassclef-internal-jargon.md

@@ -0,0 +1,244 @@
+---
+tier: lite
+description: This is the one list of bassclef-internal jargon terms with plain-English alternatives.
+---
+
+# Bassclef-internal jargon — single source of truth
+
+This is the one list of bassclef-internal jargon terms with plain-English alternatives. The `/kiss` skill reads from it. The PR-body-scrub hook reads from it. The pre-push `/kiss` hook reads from it. Drift between surfaces becomes structurally impossible.
+
+## Why this exists
+
+Before this list, two surfaces stripped bassclef-internal jargon with different lists:
+
+- `/kiss` substitution table at `.claude/skills/kiss/SKILL.md` — 47 entries; mostly advisory substitution
+- PR-body-scrub hook `JARGON_TERMS` at `.claude/hooks/pr-body-scrub-check.sh` — 8 entries; mechanical block at CI
+
+The lists did not match. PR #903 leaked "load-bearing" through `/kiss --grade11` (which does not substitute it) and got caught at CI (which does block it).
+
+Single source of truth closes the gap.
+
+## The list
+
+Each term has a plain-English alternative + a tier:
+
+- **BLOCK** — adopter-facing surfaces; hook BLOCKs at pre-push and CI on all surfaces
+- **BLOCK-title** — title + commit-message surfaces only; hook BLOCKs when `SCRUB_SURFACE=title` or `SCRUB_SURFACE=commit`. Body-surface scrub passes through. Use when a term is wrong at the title surface but acceptable in body prose (e.g., `substrate-defect:` as title prefix vs `substrate-defect` mentioned in body discussion)
+- **ADVISE** — adopter-facing surfaces; `/kiss` substitutes; hook does not block
+- **ALLOW** — bassclef-internal allowlist per bassclef#763; both surfaces preserve
+
+| Term | Plain English | Tier |
+|---|---|---|
+| composer | runs / chains / combines | BLOCK |
+| primitive | building block | BLOCK |
+| tier-preset | preset / size | BLOCK |
+| load-bearing | actually used / counted on | BLOCK |
+| blast radius | how much breaks if this goes wrong | BLOCK |
+| compose-with | uses / builds on | BLOCK |
+| scope-bounded | bounded by what we said we'd ship | BLOCK |
+| operationalize | do / ship | BLOCK |
+| wirings | hooks that fire / connections | BLOCK |
+| operator-eyes | needs your review / review by you | BLOCK |
+| seed (verb) | fill in / populate / set up | BLOCK |
+| seed (noun, defaults) | starter defaults / default config | BLOCK |
+| seed catalog | defaults catalog / stack defaults | BLOCK |
+| Greek letters as option labels (α, β, γ, δ in "Shape α", "Option β", "pick γ", "tier δ" patterns — per bassclef#1286) | a, b, c, d or 1, 2, 3, 4 — keyboard-typeable; never escalate to Greek to "differentiate" labels | BLOCK |
+| shape (as label for operator choices — "shape a", "shape b", "pick shape") | option (as label — "option a", "option b", "pick option"). Rename applies ONLY to option-label context; generic uses ("the shape of the problem", "wrong shape") stay as-is. Per ADR-040 D1 amendment 2026-07-18 | ADVISE |
+| discipline-debt | unfinished discipline work / what we still owe | BLOCK |
+| carved out | took out / removed / set aside | BLOCK |
+| discipline-shipping rhythm | how often we ship discipline / shipping cadence | BLOCK |
+| meta-pattern | the bigger pattern / the pattern across patterns | BLOCK |
+| meta-loop | the loop happening to the loop / the recursive case | BLOCK |
+| complete mediation triangle | three-layer coverage / three-layer defence | BLOCK |
+| 12-pattern matcher | the path list / the substrate-affecting path check | BLOCK |
+| compounding axis | compounding sequence (per bet 2026-07-03b WU-2 rename #611) | BLOCK |
+| OR hand-roll (soft-INSTEAD escape per bassclef-upstream#375) | dispatch the skill; no fallback | BLOCK |
+| OR write inline (soft-INSTEAD escape) | dispatch the skill; no fallback | BLOCK |
+| OR compose by hand (soft-INSTEAD escape) | dispatch the skill; no fallback | BLOCK |
+| if available (in MUST-tier procedure) | name the prereq; BLOCK with INSTEAD when missing | BLOCK |
+| if at hand (in MUST-tier procedure) | name the prereq; BLOCK with INSTEAD when missing | BLOCK |
+| when at hand (in MUST-tier procedure) | name the prereq; BLOCK with INSTEAD when missing | BLOCK |
+| when available (in MUST-tier procedure) | name the prereq; BLOCK with INSTEAD when missing | BLOCK |
+| if the skill is not (soft-INSTEAD escape) | dispatch the skill; no fallback | BLOCK |
+| when the skill is not (soft-INSTEAD escape) | dispatch the skill; no fallback | BLOCK |
+| leverage (as verb — Ogilvy §Rule 3) | use / take advantage of / build on | BLOCK |
+| synergies (Ogilvy §Rule 3) | what they do well together / how the teams help each other | BLOCK |
+| verticals (Ogilvy §Rule 3) | product lines / markets / categories | BLOCK |
+| circle back (Ogilvy §Rule 3) | follow up / come back to this | BLOCK |
+| deep dive (Ogilvy §Rule 3) | look closely / study | BLOCK |
+| low-hanging fruit (Ogilvy §Rule 3) | the easy wins / what we can ship first | BLOCK |
+| ideate (Ogilvy §Rule 3) | come up with ideas / brainstorm | BLOCK |
+| value-add (Ogilvy §Rule 3) | what makes it worth it / the benefit | BLOCK |
+| move the needle (Ogilvy §Rule 3) | make a real difference / change the outcome | BLOCK |
+| boil the ocean (Ogilvy §Rule 3) | try to do everything / scope too broadly | BLOCK |
+| holistic (Ogilvy §Rule 3 — outside biology) | complete / covers everything / end-to-end | BLOCK |
+| robust (Ogilvy §Rule 3 — vague usage) | reliable / handles the edge cases | BLOCK |
+| scalable (Ogilvy §Rule 3 — vague usage) | works when volume grows / handles more load | BLOCK |
+| ecosystem (Ogilvy §Rule 3 — outside biology) | the set of related tools / the community | BLOCK |
+| stakeholder (Ogilvy §Rule 3 — no referent) | the specific person or team; name them | BLOCK |
+| incentivize (Ogilvy §Rule 3) | give a reason / reward | BLOCK |
+| strategize (Ogilvy §Rule 3) | plan / decide the approach | BLOCK |
+| socialize (Ogilvy §Rule 3 — metaphorical) | share with the team / discuss | BLOCK |
+| pursuant to (Ogilvy §Rule 1) | following / as we discussed | BLOCK |
+| please be advised (Ogilvy §Rule 1) | drop entirely — just state the point | BLOCK |
+| it has come to my attention (Ogilvy §Rule 1) | I noticed / I saw | BLOCK |
+| right-sizing (Ogilvy §Rule 9 — euphemism for layoffs) | layoffs / we're cutting jobs | BLOCK |
+| reached out (Ogilvy §Rule 9 — vague euphemism) | called / emailed / messaged (pick one) | BLOCK |
+| going in a different direction (Ogilvy §Rule 9 — euphemism for rejection) | we're rejecting / we're not doing this | BLOCK |
+| opportunity for improvement (Ogilvy §Rule 9 — euphemism for problem) | problem / what's wrong | BLOCK |
+| challenging (Ogilvy §Rule 9 — euphemism for bad/failing) | bad / failing / broken (be specific) | BLOCK |
+| atomic | all-or-nothing | ADVISE |
+| determinism | same answer every time | ADVISE |
+| replay-deterministic | gives the same answer when re-run | ADVISE |
+| machine-readable | the system can read it directly | ADVISE |
+| compose / composes | combine / works with | ADVISE |
+| ingest / ingestion | read in / reading | ADVISE |
+| enforcement | the rule that catches it | ADVISE |
+| enforce | catch it / make it stick | ADVISE |
+| instrumentation | what we measure | ADVISE |
+| idempotent | safe to run twice | ADVISE |
+| canonical (as adjective; legacy reference to prior brand pre-2026-06-20 rename) | bassclef (as brand) / shared / official (as English) | ADVISE |
+| orthogonal | unrelated / separate concern | ADVISE |
+| obviate | make unnecessary | ADVISE |
+| supersede / supersedes | replaces | ADVISE |
+| coherent | consistent / it fits together | ADVISE |
+| heterogeneous | mixed / not the same kind | ADVISE |
+| homogeneous | same kind / consistent | ADVISE |
+| nominal | the expected case | ADVISE |
+| pathological | the bad case | ADVISE |
+| degenerate | broken / not the normal shape | ADVISE |
+| MECE | clean buckets, nothing overlaps, nothing missed | ADVISE |
+| appetite | time budget (per ADR-040 D1 rename 2026-07-17). First-mention gloss: '(steps you'll spend at your current pace before cutting scope)' | BLOCK |
+| iteration / iteration bet | goal (per ADR-040 D1 rename 2026-07-17) — a chunk of work we commit to | BLOCK |
+| stack / stacked | a chain of small PRs | ADVISE |
+| retro | look-back / what we learned | ADVISE |
+| stopping criteria | when we know we're done | ADVISE |
+| surface | the thing the user sees | ADVISE |
+| projection | computed view | ADVISE |
+| invariant | thing that's always true | ADVISE |
+| anti-pattern | the wrong way that looks right | ADVISE |
+| harness | the system Claude Code runs in | ADVISE |
+| hook | code that fires automatically | ADVISE |
+| cardinality | how many of them | ADVISE |
+| latency | wait time | ADVISE |
+| throughput | how many per second | ADVISE |
+| backpressure | when to slow down | ADVISE |
+| stuck-signal | repeated warning | ADVISE |
+| substrate-defect | bug in the rules / rule bug | ADVISE |
+| substrate-defect: | fix: (per commit-conventions.md — use the 8 standard types) | BLOCK-title |
+| INSTEAD-block discipline | the pairing rule | ADVISE |
+| arc (as multi-goal continuation — 'arc walk', 'arc-level', 'the arc', 'arc-orientation') | thread (as in 'thread walk', 'thread-level'). Per ADR-040 D1 rename 2026-07-17. Prose only; not filenames or historical git | BLOCK |
+| workunit | step. Per ADR-040 D1 rename 2026-07-17. Prose only; commit tags stay | BLOCK |
+| WU (short form of workunit) | step. Same rename as workunit per ADR-040 D1. Commit tags stay | BLOCK |
+| parent bet | parent goal. Per ADR-040 D1 rename 2026-07-17 | BLOCK |
+| circuit breaker (Shape Up term) | hard stop and re-decide. Per ADR-040 D1 rename 2026-07-17 | ADVISE |
+| substrate | shared toolkit | ALLOW |
+| bassclef | bassclef | ALLOW |
+| cameo | cameo | ALLOW |
+| Studio | Studio | ALLOW |
+| Band | Band | ALLOW |
+| bandleader | bandleader | ALLOW |
+| chronicle | chronicle | ALLOW (added 2026-08-16 per goal 2026-08-16a Louis-lens consult; retracts ADR-040 D1 chronicle → session log word rename; directory `chronicle/` stays; `/chronicle` and `/session-log` SKILL names both work) |
+
+## Phrase compounds (ADVISE-PHRASE tier — V1 advisory)
+
+Per bassclef#915. The word-shaped table above catches individual words. Substrate-internal compounds use plain individual words combined into substrate-internal phrases that pass every gate. Adopters reading post-launch encounter dense phrasing even when no single word violates Rule 1.
+
+Format: `Phrase | Plain alternative | Tier`. Tier ADVISE-PHRASE fires the PR-body-scrub hook Rule 5 (advisory) — emits a CI comment, does not block.
+
+| Phrase | Plain alternative | Tier |
+|---|---|---|
+| pipeline altitude | pipeline | ADVISE-PHRASE |
+| atomic discipline | one-PR-per-concern (or one concern per PR) | ADVISE-PHRASE |
+| operator-attention | operator review | ADVISE-PHRASE |
+| operator-attended | operator-reviewed | ADVISE-PHRASE |
+| honest case | valid case (or omit) | ADVISE-PHRASE |
+| forcing function | what forces the answer | ADVISE-PHRASE |
+| surface scrub | surface cleanup | ADVISE-PHRASE |
+| serial work | sequenced work (or in series) | ADVISE-PHRASE |
+| pipeline shape | pipeline (when used as noun in prose) | ADVISE-PHRASE |
+| hook wirings | hooks that fire / hook connections | ADVISE-PHRASE |
+| discipline propagation | rolling the rule out / making the rule stick | ADVISE-PHRASE |
+| phase N vocabulary | the word-list piece of phase N | ADVISE-PHRASE |
+| next pickup | what to do next | ADVISE-PHRASE |
+| promotable patterns | patterns worth promoting | ADVISE-PHRASE |
+| discoveries extraction | things worth keeping | ADVISE-PHRASE |
+| sister shape | same shape | ADVISE-PHRASE |
+| ungated | the gate cleared / no longer blocked | ADVISE-PHRASE |
+| atomic PR | one issue per PR | ADVISE-PHRASE |
+| forward-compat | safe for later versions | ADVISE-PHRASE |
+| discovery surface | discovery / where you find it | ADVISE-PHRASE |
+| compounding axis | compounding sequence (per bet 2026-07-03b WU-2 rename #611) | ADVISE-PHRASE |
+| luminary design ceremony | proper design with a named author / design review with named perspectives | ADVISE-PHRASE |
+| validator-registry | the list of checks / set of validators | ADVISE-PHRASE |
+| per-substrate-evolution-shipping-window | each time we ship a new rule / each substrate shipping window | ADVISE-PHRASE |
+| compounds tightly | each builds on the prior / one supports the next | ADVISE-PHRASE |
+
+Additions to this section follow the same lifecycle as the word-shaped table: file an issue → propose addition → both surfaces (/kiss + PR-body-scrub Rule 5) pick up at next session-start sync.
+
+## How surfaces read the list
+
+### `/kiss` skill
+
+`/kiss --grade10` substitutes BLOCK + ADVISE terms; preserves ALLOW.
+`/kiss --grade11` substitutes BLOCK terms; preserves ADVISE + ALLOW.
+`/kiss --grade8` substitutes BLOCK + ADVISE + a stricter prose pass; preserves ALLOW.
+
+### PR-body-scrub hook
+
+The CI hook reads BLOCK terms only and fires on match. ADVISE and ALLOW terms pass through.
+
+### Pre-push `/kiss` hook (bassclef#907 Part 4)
+
+Reads BLOCK terms; fires at `gh pr create` and `gh issue create` time. ADVISE and ALLOW terms pass through.
+
+## Term lifecycle
+
+Three states for a term:
+
+1. **New jargon caught at /diagnose or operator review** → file an issue, propose adding to the table at a tier
+2. **Added to the table at a tier** → both surfaces pick it up at next session-start sync
+3. **Promoted from ADVISE to BLOCK** → when a term shows up in 3+ leaked PR bodies despite advisory pass
+
+ALLOW promotions require a separate bassclef-evolution issue per bassclef#763 reserved-name discipline.
+
+## Standard technical vocabulary — preserved across all tiers
+
+These terms stay as-is at every tier. They are not jargon; they are standard tech vocabulary every digital team understands:
+
+```
+API, SDK, CLI, GUI, HTTP, REST, JSON, YAML, schema, regex, hook,
+repo, branch, commit, PR, MR, CI, CD, workflow, action, artifact,
+function, class, method, property, field, constant, variable, enum,
+database, query, index, migration, transaction, cache, queue, lock,
+container, image, pod, cluster, node, runner, build, deploy, rollback,
+test, assert, mock, stub, fixture, snapshot, regression,
+auth, token, secret, credential, scope, permission, role,
+file, directory, path, glob, pattern, prefix, suffix
+```
+
+Do not substitute these. Do not expand them into multi-sentence explanations.
+
+## Operator opt-out
+
+Two paths to skip substitution for operator-internal work (canvases, audits, internal strategy docs):
+
+- PR label `bassclef-internal-prose-ok` — downgrades hook firings to advisory at both pre-push and CI
+- Environment variable `SKIP_KISS=1` — bypasses the pre-push `/kiss` hook for one invocation; logged via trace-helper
+
+Operator-private files under `docs/operator-private/*` are out of scope for this list — they are private substrate; the discipline applies to adopter-facing output.
+
+## Composes with
+
+- `.claude/skills/kiss/SKILL.md` — reads BLOCK + ADVISE from this list per mode
+- `.claude/hooks/pr-body-scrub-check.sh` — reads BLOCK from this list
+- `.claude/hooks/kiss-default-check.sh` — reads BLOCK from this list (bassclef#907 Part 4)
+- `.claude/rules/plain-english-discipline.md` — methodology layer; references this list as authoritative
+- bassclef#763 — `/kiss` reserved-name allowlist (the ALLOW tier traces to this discipline)
+- bassclef#906 — PR-body shape contract (sister discipline; shape + vocabulary together close the drift)
+
+## Refs
+
+- bassclef#907 — `/kiss` overhaul (this standard's parent ticket)
+- bassclef#908 — asymmetric-gate pattern (this standard is one positive fix)
+- PR #903 — surfaced the drift (leaked "load-bearing")

package/substrate/standards/bassclef-managed-sentinel.md

@@ -0,0 +1,96 @@
+---
+tier: lite
+title: bassclef-managed sentinel — file semantic
+status: adopted
+date: 2026-08-30
+introduced_by: PR #1428 (Option F cp swap)
+frozen_by: RFC-0001 H2
+description: The .bassclef-managed sentinel marks a directory as bassclef-managed content.
+---
+
+# Standard — `.bassclef-managed` sentinel
+
+## Purpose
+
+The `.bassclef-managed` sentinel marks a directory as bassclef-managed content. Adopter tooling reads it to distinguish bassclef-shipped skill directories from adopter-authored skill directories that happen to share a name.
+
+Introduced in PR #1428 for `.claude/skills/*/` (both project-level and user-level). Extends to `.claude/luminaries/`, `.claude/agents/`, and `lib/` when #1429 ships.
+
+## Sources read
+
+- PR #1428 body — first introduction of the sentinel at `presence/install/bassclef-sync.template.sh` Sections 2 and 3b-skills
+- `docs/rfcs/RFC-0001-option-f-cp-swap-review.md` H2 finding — Hyrum lens flagged the sentinel as an observable contract
+- `.claude/rules/we-dont-break-adopters.md` — ADR-031 discipline that governs any change to this semantic
+
+## Sentinel semantic — frozen
+
+The sentinel is an **empty file** at the root of a bassclef-managed directory. Nothing more. Adopters MAY bind to its presence or absence. Adopters MUST NOT bind to its content, its size, or its modification time.
+
+```
+.claude/skills/longrun/
+├── SKILL.md
+├── scripts/
+└── .bassclef-managed          ← empty file; adopter reads presence only
+```
+
+**What the sentinel means:**
+
+- **Present** — directory is managed by bassclef sync. Contents get refreshed on next sync. Adopter edits inside the directory get overwritten. Adopter override should live in a differently-named directory OR (for future migration) a `.bassclef-override` flag.
+- **Absent** — directory is adopter-authored. Sync leaves it alone even if a bassclef skill of the same name exists upstream.
+
+**What the sentinel does NOT mean:**
+
+- The sentinel does NOT carry a version, checksum, or bassclef commit reference.
+- The sentinel does NOT change size across bassclef versions.
+- The sentinel does NOT get mtime-refreshed on every sync (empty file writes are idempotent).
+
+## Why the semantic is frozen
+
+Hyrum's law — with enough adopters, every observable becomes a load-bearing contract. First release binds the sentinel semantic forever. Adding a field, changing size, or renaming the file breaks adopter tools that already bind to the shape.
+
+Freezing early prevents the drift class. Any future extension owes a new sentinel filename (e.g., `.bassclef-metadata-v2`) plus a compat shim per ADR-031.
+
+## Adopter usage patterns
+
+**Check whether a skill directory is bassclef-managed:**
+
+```bash
+if [ -f "$CWD/.claude/skills/$SKILL_NAME/.bassclef-managed" ]; then
+  echo "bassclef manages $SKILL_NAME"
+else
+  echo "adopter authors $SKILL_NAME"
+fi
+```
+
+**Skip bassclef-managed directories in adopter scripts:**
+
+```bash
+find "$CWD/.claude/skills" -mindepth 1 -maxdepth 1 -type d ! -exec test -f {}/.bassclef-managed \; -print
+```
+
+## Migration path from prior symlink shape
+
+Before PR #1428, `.claude/skills/*/` were symlinks to the bassclef sibling. Adopter tools that used `test -L` or `readlink` to detect bassclef-shipped skills need to switch to the sentinel check.
+
+See `docs/adopters/option-f-migration-note.md` for the full migration guide.
+
+## Change control
+
+Amendments to this semantic require:
+
+1. An ADR proposing the change (references ADR-031 grace window discipline)
+2. A `/rfc` outside-lens council review (per `.claude/skills/rfc/SKILL.md`)
+3. A compat shim keeping the prior semantic working for one release cycle
+4. A migration manifest in `docs/operator-private/forward-port-registry/migrations/`
+5. An adopter changelog entry at `/release` time
+
+## Refs
+
+- PR #1428 (introduced sentinel)
+- Ticket #1429 (extends sentinel to remaining 4 sections)
+- RFC-0001 H2 (freeze motivated by Hyrum lens finding)
+- ADR-031 (we-dont-break-adopters)
+- `docs/adopters/option-f-migration-note.md` (adopter-facing migration guide)
+- `presence/install/bassclef-sync.template.sh` (writes the sentinel at cp time)
+- `@luminary hyrum-wright` (H2 finding source)
+- `@luminary linus-torvalds` (adopter-compat anchor for the freeze)

package/substrate/standards/bassclef-source-config.md

@@ -0,0 +1,228 @@
+---
+tier: lite
+description: "The thin-pointer bassclef-sync hook (presence/install/bassclef-sync.template.sh and consumer-vendored bassclef-sync.sh) has two paths to load bassclef's substrate:"
+---
+
+# `.bassclef-source.json` — schema for thin-pointer curl-fallback
+
+The thin-pointer bassclef-sync hook (`presence/install/bassclef-sync.template.sh`
+and consumer-vendored `bassclef-sync.sh`) has two paths to load
+bassclef's substrate:
+
+1. **Sibling fast-path**: if `$CWD/../bassclef/` exists on the local
+   filesystem, the hook execs the bassclef-sync template directly.
+2. **Curl fallback**: if no sibling, the hook reads
+   `.bassclef-source.json` from the consumer repo root, fetches the
+   tarball at `source_url`, extracts it, and execs the bassclef-sync
+   template from the extracted tree.
+
+This standard defines the schema of `.bassclef-source.json` so all
+five provider patterns (GitHub public, GitHub private repo, GitHub
+private release, Azure DevOps Repos, GitLab) can be authored against
+a single contract. Onboarding tooling (`/onboard-repo`), validation
+hooks, and consumer adapters compose against this contract.
+
+Closes bassclef#419.
+
+## Sources read
+
+- bassclef#419 — schema + provider examples specification
+- TwoDo PR #258 — thin-pointer hook implementation that defines the contract
+- TwoDo `.bassclef-source.json` (live config that proved the schema in PR #268)
+- `presence/install/bassclef-sync.template.sh` — sibling fast-path target
+- `architecture/decisions/ADR-015-state-schema-format.md` — JSON Schema draft-2020-12 standard
+- `standards/state-spine/schemas/*.schema.json` — schema-format precedent
+
+## Why this schema is small (and stays small)
+
+Five fields, three required, one optional. The thin-pointer hook is
+the only consumer; provider differences resolve at the URL level
+(provider-specific tarball endpoints) and at the auth-header level
+(Bearer vs Basic vs none). Adding fields would couple the schema to
+provider-specific concerns the hook doesn't need.
+
+If a provider requires a header the schema doesn't model (e.g., an
+extra X-API-Version), wrap it in the URL or add a pre-fetch shim in
+the hook — don't grow the schema.
+
+## Schema
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "required": ["source_url", "auth_method", "token_env"],
+  "additionalProperties": false,
+  "properties": {
+    "source_url":  { "type": "string", "format": "uri" },
+    "auth_method": { "type": "string", "enum": ["Bearer", "Basic", "none"] },
+    "token_env":   { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]*$" },
+    "comment":     { "type": "string" },
+    "auto_sync":   { "type": "boolean" }
+  }
+}
+```
+
+Authoritative copy lives at `standards/bassclef-source/schemas/bassclef-source.schema.json`
+and is enforced by the validation hook (see § Validation below).
+
+### Field reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `source_url` | string (URI) | yes | Tarball-download URL on the upstream provider. The hook curls this and pipes through `tar -xzf -`. Must return a gzipped tarball when fetched with the appropriate auth header. |
+| `auth_method` | enum | yes | `"Bearer"` (Authorization: Bearer `$TOKEN`), `"Basic"` (Authorization: Basic `$TOKEN`), or `"none"` (no auth header — public URL). |
+| `token_env` | string | yes | Name of the environment variable holding the auth token. Must be a valid env-var identifier (uppercase letters, digits, underscores; cannot start with a digit). For `auth_method: none`, set to empty string `""` (the field is required but unused). |
+| `comment` | string | no | Human-readable description. Recommended: name the provider, name the token, link to the bassclef issue or bet that motivated the config. |
+| `auto_sync` | boolean | no | When `true`, the bassclef-sync dispatcher fetches bassclef's latest substrate at every SessionStart. When `false` or absent, the dispatcher short-circuits with a one-line note + opt-in path. **Default behavior on absence is `false`** — a cold-adopter safe default per bassclef#939. Existing bassclef operator-side consumers (poa / twodo / quorum / ops / pruneguice) set this to `true` explicitly to preserve auto-sync behavior. |
+
+### Why all three are required
+
+The hook reads all three fields at fire-time. Making `token_env`
+optional with a default would hide the no-auth case behind a default
+and produce silent failure modes when an operator forgets to set the
+env var. Explicit-or-empty is clearer than implicit-default.
+
+## Provider examples
+
+### Public GitHub release (no auth)
+
+```json
+{
+  "source_url":  "https://github.com/sunj-labs/bassclef/releases/latest/download/substrate.tar.gz",
+  "auth_method": "none",
+  "token_env":   "",
+  "comment":     "Public bassclef substrate release; no auth needed. Suitable for public consumer repos and demos."
+}
+```
+
+### Private GitHub repo (via fine-grained PAT)
+
+```json
+{
+  "source_url":  "https://api.github.com/repos/sunj-labs/bassclef/tarball/main",
+  "auth_method": "Bearer",
+  "token_env":   "BASSCLEF_TOKEN",
+  "comment":     "GitHub repo tarball API. Auth: fine-grained PAT 'bassclef-substrate-read' (Contents:read on sunj-labs/bassclef), stored as BASSCLEF_TOKEN in the consumer's Cloud Code environment."
+}
+```
+
+This is the pattern used by all five sunj-labs consumer repos
+(TwoDo, POA, quorum, ops, pruneguice) when running against
+bassclef's private repo from Cloud Code.
+
+### Private GitHub release (via fine-grained PAT)
+
+```json
+{
+  "source_url":  "https://api.github.com/repos/sunj-labs/bassclef/releases/latest",
+  "auth_method": "Bearer",
+  "token_env":   "BASSCLEF_GH_TOKEN",
+  "comment":     "GitHub release API. Returns release JSON; the hook follows assets[].browser_download_url for the tarball asset. Auth: fine-grained PAT with Contents:read."
+}
+```
+
+Use for environments where releases are gated more strictly than the
+repo (e.g., preview vs. stable channels).
+
+### Azure DevOps Repos (via ADO PAT)
+
+```json
+{
+  "source_url":  "https://dev.azure.com/<ORG>/<PROJECT>/_apis/git/repositories/bassclef/items?path=/&versionDescriptor.version=main&$format=zip&download=true&api-version=7.0",
+  "auth_method": "Basic",
+  "token_env":   "BASSCLEF_ADO_PAT",
+  "comment":     "Azure DevOps Repos zip-archive API. Auth: ADO PAT base64-encoded as ':<PAT>' (empty username + colon + PAT) when set in BASSCLEF_ADO_PAT — the hook sends it as Authorization: Basic <env>."
+}
+```
+
+ADO returns a zip, not a tarball. The hook handles the conversion
+(unzip → tar) when the URL ends in `.zip` or contains `$format=zip`.
+
+### GitLab (via GitLab PAT)
+
+```json
+{
+  "source_url":  "https://gitlab.com/api/v4/projects/<PROJECT_ID>/repository/archive.tar.gz?sha=main",
+  "auth_method": "Bearer",
+  "token_env":   "BASSCLEF_GITLAB_TOKEN",
+  "comment":     "GitLab repo archive API. Auth: GitLab PAT with read_repository scope. PROJECT_ID is the numeric project ID from GitLab settings."
+}
+```
+
+## Validation
+
+### At write time (hook-enforced)
+
+`.claude/hooks/bassclef-source-config-validate.sh` (PreToolUse on
+Edit/Write to `.bassclef-source.json`) validates the file against
+the schema using `ajv-cli` draft-2020-12. Same pattern as
+`state-validate.sh` per `.claude/rules/state-schema-validation.md`.
+
+On validation failure, the hook BLOCKs the write with structured
+stderr message naming the field + ajv error.
+
+### At hook fire time (runtime)
+
+The thin-pointer hook itself reads `source_url` / `auth_method` /
+`token_env` and surfaces a clear error if any are missing or malformed
+when the curl-fallback path fires. Schema validation at write time
+catches most issues before runtime.
+
+### At session start (drift check)
+
+Future hardening: `bassclef-sync.sh` could validate
+`.bassclef-source.json` exists + parses cleanly at session start,
+emitting a BLOCKED if the file is corrupt. Deferred — write-time
+validation covers the common case.
+
+## Test fixtures
+
+Five fixtures, one per provider pattern:
+
+- `scripts/tests/fixtures/bassclef-source/github-public-release.json`
+- `scripts/tests/fixtures/bassclef-source/github-private-repo.json`
+- `scripts/tests/fixtures/bassclef-source/github-private-release.json`
+- `scripts/tests/fixtures/bassclef-source/azure-devops-repos.json`
+- `scripts/tests/fixtures/bassclef-source/gitlab.json`
+
+Test runner: `scripts/tests/bassclef-source.test.sh` validates every
+fixture against the schema; CI fails if any fixture diverges.
+
+Plus negative-case fixtures (each in its own file under
+`scripts/tests/fixtures/bassclef-source/invalid/`) to verify the
+schema rejects malformed configs.
+
+## Operator workflow per consumer repo
+
+1. Operator creates fine-grained PAT for bassclef (read-only,
+   90-day expiry). Track in `substrate.secrets.md` per
+   `standards/secrets-lifecycle.md`.
+2. Operator pastes PAT into consumer's Cloud Code environment as
+   `BASSCLEF_TOKEN` (or per-consumer name if scoped tokens are used).
+3. `/onboard-repo` writes `.bassclef-source.json` to consumer repo
+   root using the GitHub-private-repo template.
+4. Operator commits + pushes; next session-start fires the
+   thin-pointer hook → curl fallback → bassclef substrate loaded.
+
+## Relationship to other standards + rules
+
+- `standards/secrets-lifecycle.md` — `token_env` references a secret
+  whose lifecycle is governed by this standard
+- `.claude/rules/state-schema-validation.md` — write-time validation
+  pattern this standard composes
+- `architecture/decisions/ADR-015-state-schema-format.md` — JSON
+  Schema draft-2020-12 with format support; this schema follows
+- `.claude/skills/onboard-repo/SKILL.md` — installer that creates
+  `.bassclef-source.json` per the schema
+- bassclef#418 — drift-check thin-pointer-aware (related; ships
+  alongside)
+- bassclef#420 — secrets-primitive gap on Cloud Env (related; the
+  PAT lifecycle question this schema reveals)
+
+## Retirement condition
+
+This standard retires only if the thin-pointer hook architecture
+retires. Provider examples may grow (BitBucket, codecommit, etc.) as
+new providers are exercised; the schema itself is intentionally
+minimal and should resist field additions.