@thebassclef/lite 0.1.3 → 1.0.1

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

@@ -1,244 +0,0 @@
----
-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

@@ -1,96 +0,0 @@
----
-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

@@ -1,228 +0,0 @@
----
-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.