@thebassclef/lite 0.0.1 → 0.1.2

package/substrate/.claude/rules/blocked-items.md

@@ -0,0 +1,146 @@
+---
+tier: lite
+description: "Session-start hook output may contain lines prefixed with BLOCKED:."
+---
+
+# Blocked Items — Mandatory Resolution
+
+Session-start hook output may contain lines prefixed with `BLOCKED:`.
+These are not suggestions. They are mandatory scope.
+
+## Protocol
+
+1. **Before proposing any new work**, scan session-start output for
+   `BLOCKED:` lines.
+2. Each blocked item MUST be either:
+   - **Resolved** in this session (run the command, write the artifact), OR
+   - **Explicitly deferred** by the operator ("skip metrics this session")
+3. If the operator says nothing about blocked items, the default is
+   **resolve them**. Silence is not deferral.
+4. Propose blocked items as the FIRST items in your session plan.
+   New iteration work comes AFTER blocked items, not instead of them.
+
+## What counts as resolution
+
+- `BLOCKED: release-notes` → run /release-notes, commit the output
+- `BLOCKED: metrics` → run the metrics script, commit the output
+- `BLOCKED: chronicle` → write the missing chronicle, commit
+- `BLOCKED: architect-review` → run /architect-review
+
+## What counts as explicit deferral
+
+The operator must say one of:
+- "skip [item]" / "defer [item]" / "not this session"
+- Acknowledging the item exists is NOT deferral
+- "okay" or "got it" is NOT deferral — it means resolve it
+
+## Friction during chained dispatches (bassclef#400)
+
+The `post-skill-friction-check.sh` hook fires on PostToolUse Skill for
+major composer skills (/stage (formerly /preview), /launch (formerly /preview-build), /build, /shape full,
+/longrun, /decompose, /spec, /architect-review, /interpret-input, etc.).
+It classifies output:
+
+- **Unambiguous friction** (`deferred to Phase X`, `stub return`,
+  `Error:`, `not yet implemented`) → log + recommend `/promote
+  substrate-defect` inline. Don't defer to closeout; file at the
+  boundary.
+- **Borderline friction** (`Lorem ipsum`, `XXX`, `FIXME`, partial
+  output) → log only; operator triages on return.
+- **No friction** → silent.
+
+The friction log lives at `docs/session-friction-log.md`. Operators
+returning from unattended runs read the log first; promote what's
+worth promoting.
+
+Per-skill opt-out: add `disable_friction_check: true` to skill
+frontmatter (rare; for skills whose stub returns are intended).
+Per-call override: `SKIP_FRICTION_CHECK=1 <command>` (logged).
+
+## When resolution reveals a substrate defect
+
+Sometimes resolving a BLOCKED item surfaces the real cause: the hook's
+detection path is wrong, a state file rotted, a marker format changed,
+or the compliance calculation reads a location the writer stopped
+using. The nominal work was done; the signal kept firing because the
+mechanism is broken.
+
+When this happens, resolution MUST include firing `/promote` with the
+`substrate-defect` classifier. Fix the local instance AND promote the
+mechanism fix — otherwise every consumer repo keeps hitting the same
+broken hook.
+
+### Trigger (any of)
+
+1. **Stuck signal resolved** — the signal was stuck per
+   `stuck-signal-diagnostic.md`, mechanism-read found a defect, defect
+   is now fixed. `/promote` fires automatically on this path.
+2. **Hook false-positive** — the banner fired even though the
+   underlying work was already done, and the fix was editing the hook,
+   not doing the work.
+3. **Counter miscount** — the number in the banner was wrong
+   (off-by-one, wrong window, stale cache), and the fix was editing
+   the counting mechanism.
+4. **Marker location rot** — a gate marker was written to a path the
+   reader no longer checks (e.g., `/tmp` sandbox teardown), and the
+   fix was dual-writing or relocating the marker.
+
+### Protocol
+
+1. **Resolve the local instance.** Land the substrate edit (hook fix,
+   rule update, path correction) in the current branch.
+2. **Fire `/promote`** — use the substrate-defect template in
+   `promote/SKILL.md`. The /promote issue cites:
+   - Signal observed (banner text + chronicle dates showing the loop)
+   - Mechanism file read (path + what was wrong)
+   - Fix applied (PR or commit ref)
+   - Propagation requirement (which consumer repos inherit; what
+     breaks if they don't pick up the fix)
+3. **Classify** as `agent-self-proposed` + `substrate-defect` (see
+   `promote/SKILL.md` label table). These don't need operator prompt —
+   agent-discovered defects file automatically because the trigger
+   condition (stuck signal + mechanism fix) is unambiguous.
+4. **Cite in the session's chronicle** with explicit "substrate defect
+   promoted: #NNN" line so retrospectives can audit the promotion
+   path worked.
+
+### Why mandatory (not MUST-try)
+
+`bassclef-evolution.md` already describes /promote as the promotion
+path. The gap being closed: when an agent finds a substrate defect
+mid-session and fixes only the local instance, the decision to
+promote becomes "nice to have" and rots. Three sessions in April 2026
+fixed local substrate drift without firing /promote; the same drift
+resurfaced in consumer repos two weeks later (POA inherited broken
+hook paths).
+
+Making /promote mandatory on the `resolution-revealed-defect` branch
+removes the decision. The agent doesn't choose whether to promote;
+the trigger fires it.
+
+### What doesn't trigger /promote
+
+- BLOCKED items resolved by doing the nominal work (running
+  `/release-notes`, writing the chronicle) — the mechanism was fine,
+  the work just wasn't done. No defect to promote.
+- Operator-overridden deferrals — the operator chose to skip; no
+  mechanism analysis happened.
+- One-off bugs in the agent's session (typo in commit message,
+  missed file) — those aren't substrate.
+
+The trigger is specifically "mechanism was broken, mechanism got
+fixed" — not "work was slow, work got faster."
+
+## Why this rule exists
+
+Agents consistently acknowledge hook warnings and then skip them.
+Three instances in 6 weeks: DORA metrics, metrics dashboard, release
+notes. The hook detects the problem correctly — the agent chooses to
+ignore it. This rule removes that choice.
+
+## Infrastructure note
+
+This is a methodology rule, not a hook. It works regardless of whether
+enforcement comes from bash hooks, Managed Agents outcome preconditions,
+or any other infrastructure. The hook produces the signal; this rule
+defines the response.

package/substrate/.claude/rules/bootstrap-pair-discipline.md

@@ -0,0 +1,141 @@
+---
+tier: lite
+description: Every substrate primitive ships with its paired bootstrap discipline.
+---
+
+# Bootstrap-Pair Discipline
+
+Every substrate primitive ships with its paired bootstrap discipline. A primitive without its pair is half-shipped — the substrate appears to ship the feature, but adopters hit the missing half as silent breakage at runtime.
+
+This rule names the failure class, enumerates 5 known instances, and gives the discipline a name so future PRs catch the failure at authoring time instead of at adopter-runtime time.
+
+## When this rule fires
+
+Any PR that adds a substrate primitive to bassclef. "Substrate primitive" means any of these surfaces:
+
+- **Hook** — a new file under `.claude/hooks/*.sh`
+- **Rule** — a new file under `.claude/rules/*.md`
+- **Skill** — a new directory under `.claude/skills/<name>/SKILL.md`
+- **Validator / accessor / library** — a new shell library under `lib/*.sh` or a new validator under `scripts/`
+- **Schema** — a new JSON Schema under `standards/state-spine/schemas/*.schema.json`
+- **Standard** — a new standard under `standards/*.md`
+- **ADR** — a new file under `architecture/decisions/ADR-*.md`
+
+The rule passes through (does not fire) on:
+
+- Operator content (chronicles, journals, deferred-actions)
+- Documentation edits without behavior change
+- Bug fixes that touch existing primitives without adding new ones
+- Test edits (covered by sister rules — `.claude/rules/testing-tier-config.md`, `test-list-discipline.md`)
+
+## The 7 known instances
+
+Each row names the primitive being added, the pair it owes, and the failure mode when the pair is missing.
+
+| Building block added | Bootstrap pair owed | Failure mode when missing |
+|---|---|---|
+| **Hook** under `.claude/hooks/*.sh` | The hook is wired in `.claude/settings.json` OR `presence/install/bassclef-sync.template.sh` for adopters | Hook exists on disk but stays silent (dead-letter) — surfaced 5 times during the 2026-04 substrate audit |
+| **Rule** citing a mechanical hook in `## Mechanical Enforcement` | The cited hook exists on disk AND is wired | Rule promises mechanical layer that stays silent; methodology only — surfaced 11 times in WU-5 of bet 2026-06-24c |
+| **Skill** declaring `modes:` / `tiers:` / `sizes:` in frontmatter | The `description:` field names each declared mode inline (per `.claude/rules/skill-description-clarity.md` description-mirrors-modes) | Type-ahead operator menu shows nothing distinguishing — surfaced 3 times in WU-6 of bet 2026-06-24c |
+| **Accessor library** named in a rule (`lib/state.sh`) | The file exists at the named path | Rule's `accessor-library-discipline.md` references a path that 404s — surfaced via #324 (closed via bet 2026-06-25a) |
+| **Schema** under `standards/state-spine/schemas/*.schema.json` | The write-time validation hook is wired (`state-validate.sh` PreToolUse) AND the entity has a storage-shape entry in `standards/state-spine.md` | Schema ships but the spine permits writes that violate it — surfaced via #319 (partial-close via bet 2026-06-25a WU-3) |
+| **Adopter-observable surface change** — new hook / skill / rule / agent / luminary / standard / ADR / schema / sync-template OR edit to an existing one matching `.claude/rules/cold-adopter-harness-discipline.md` § "When this rule fires" | The cold-adopter harness check class covering the new surface exists in `scripts/cold-adopter-harness-sync.sh` AND the CI job `cold-adopter-harness` in `.github/workflows/bassclef-pr-ci.yml` fires on the PR | Substrate ships a change that breaks adopter-observable surface; harness passes with stale coverage OR harness fails with no CI gate to catch it before merge — surfaced via 2026-06-25 /longrun prep audit (Gap 1 + Gap 2 + Gap 3 of 5; closed via bet 25g) |
+| **Release pipeline path change** (added bet 2026-06-29c WU-5) — any PR that adds a new top-level directory (e.g., new `lib/`, `templates/`, `presence/`) OR moves files between substrate directories (`scripts/`, `presence/`, `lib/`, `standards/`) OR adds a new operator-template at `presence/install/` | The release script's `ALLOWED_PATHS` in `scripts/release-to-bassclef.sh` covers the new top-level directory AND any new template at `presence/install/<name>.template.sh` is handled by the release step that ships templates (e.g., `public-bassclef-settings.template.json` copy step) | Release ships everything except the new directory; adopters get partial substrate; hooks reference files that aren't on the public tree — surfaced 4 release iterations in a row on 2026-06-29 (PRs #1372/#1373/#1374/#1375): PR #318 missed `scripts/`; later PRs missed `lib/` + `templates/`; settings template needed its own release-script step. Three sister cures: (a) extending the cold-adopter harness rule-mechanism-claim scanner to recognize `<name>.template.sh` as evidence the hook ships via install template; (b) refining the operator-private-path check filename pattern so it doesn't false-positive on bassclef's own `-review` rule names (out of scope tonight; tracked as follow-on); (c) auto-applying the `bassclef-internal-prose-ok` label on release PRs so the operator-private-path check passes first time (out of scope tonight; tracked as follow-on). |
+
+## What this rule requires
+
+When a PR adds a substrate primitive, the PR body MUST include a `Bootstrap pair shipped` block in the Summary section naming the pair:
+
+```markdown
+## Bootstrap pair shipped
+
+- Building block: `<path>` (e.g., `.claude/hooks/foo.sh`)
+- Pair: `<wiring location>` (e.g., `.claude/settings.json` PreToolUse Edit|Write|MultiEdit) OR `<rationale for no pair>`
+```
+
+If the primitive type is not in the 5-instance table, the author names the pair in plain English ("the pair this primitive owes is X because Y"). The reviewer's job is to verify the pair actually exists in the PR — not just that the author named it.
+
+## Anti-patterns
+
+These shapes fail this rule.
+
+**Ship hook without wiring** — the hook lives on disk but no settings.json registers it. The hook is dead-letter; the failure surfaces silently in adopter sessions.
+
+INSTEAD: ship the wiring in the same PR.
+
+**Cite an unwired hook in a rule's Mechanical Enforcement section** — the rule promises mechanical enforcement but the hook is not wired. The rule operates as methodology-only with no agent-side awareness of the gap.
+
+INSTEAD: either wire the hook in the same PR or rephrase the rule to claim methodology-only enforcement.
+
+**Declare skill modes in frontmatter without naming them inline in the description** — the harness type-ahead shows the skill name but no mode disambiguation; operator has to invoke and discover.
+
+INSTEAD: include each declared mode in the description's 280-character budget.
+
+**Name a file path in a rule that does not exist on the substrate** — adopters reading the rule follow the path and 404.
+
+INSTEAD: verify the path resolves on bassclef-upstream before the PR opens.
+
+**Ship a schema without wiring the write-time validator** — writes that violate the schema land in the spine and corrupt state silently.
+
+INSTEAD: wire `state-validate.sh` in `.claude/settings.json` in the same PR as the schema.
+
+## Override path
+
+`SKIP_BOOTSTRAP_PAIR=1 <command>` — for genuine cases where the pair lands in a separate PR by design AND the separate PR is filed AND the current PR's body cites the follow-on. Logged via trace-helper.
+
+INSTEAD of overriding for routine work: ship the pair in the same PR. The cost is small (one hook line, one settings.json entry, one rule citation) and the discipline compounds across every future primitive.
+
+## Why this rule exists
+
+Five instances of "ship A without paired B" surfaced during the 2026-04 to 2026-06 substrate audit period (WU-10 of bet 2026-06-24c). Each instance was diagnosed individually before the class was named. Diagnosing the class lets future PRs catch the failure at authoring time instead of accumulating as silent debt the next architect-review sweeps surface.
+
+Per `@luminary john-ousterhout` (deep modules): a substrate module is "deep" when its API matches its internal complexity. A bootstrap-paired ship matches the API surface (rule says X exists, hook does Y) with the internal commitment (X is on disk, Y is wired). Half-shipped primitives have shallow APIs that lie about internal state.
+
+Per `@luminary michael-nygard` (stability patterns): bootstrap-pair is the circuit-breaker against incomplete substrate ships. The rule fires at the PR-author boundary; the optional V2 mechanical layer would fire at the pre-commit boundary; both prevent the half-shipped class from reaching adopter machines.
+
+Per `@luminary kent-beck` (test-first): the test for a substrate primitive often IS its bootstrap pair. The hook test ships when the hook ships; the test running confirms the hook fires; the wiring is the bootstrap pair that makes the test reachable from adopter sessions.
+
+Per `@luminary linus-torvalds` (adopter compatibility stance): when bassclef ships an incomplete substrate primitive, the failure is invisible to bassclef-internal tests (which assume bassclef's own environment is intact) but catastrophic at first adopter run (which catches the missing pair). The bootstrap-pair discipline is the bassclef-internal analog of the kernel-compatibility-stance Linus articulated — applied to substrate-internal completeness.
+
+## Mechanical layer (V2 deferred)
+
+V1 of this rule is methodology only. V2 deferred extension: a pre-commit hook that:
+
+1. Detects PRs adding substrate primitives (path matchers per the "When this rule fires" section)
+2. Greps the staged content for the pair (e.g., new hook → grep settings.json staged diff for the hook's path)
+3. BLOCKs when the pair is absent AND the override is absent
+
+Defer to a separate goal when the methodology layer has shipped through enough PRs that the failure modes are stable and the pre-commit logic can mechanize against them confidently.
+
+## Composes with
+
+- `.claude/rules/pr-body-shape.md` — the `Bootstrap pair shipped` block lives in the Summary section per this rule
+- `.claude/rules/we-dont-break-adopters.md` — sister discipline at the adopter-observable surface; this rule extends the discipline to bassclef-internal substrate completeness
+- `.claude/rules/blocked-items.md` — the BLOCK protocol the V2 mechanical layer would fire
+- `.claude/rules/loop-discipline.md` — sister at the construction-cycle level; bootstrap-pair check fires in the per-PR loop discipline
+- `.claude/rules/accessor-library-discipline.md` — the rule that surfaced one instance (#324)
+- `.claude/rules/testing-tier-config.md` — the Tier 0 strict-TDD pattern; the bootstrap pair often IS the test that locks the primitive
+- `architecture/audits/2026-06-24-validator-bootstrap.md` — WU-10 surfaced the 5-instance enumeration
+
+## Distinct from
+
+- `we-dont-break-adopters.md` — that rule covers adopter-observable surfaces. This rule covers substrate-internal completeness. The two compose; both required.
+- `loop-discipline.md` — that rule covers the per-PR construction cycle. This rule covers the per-primitive completeness check WITHIN that cycle.
+- `testing-tier-config.md` — that rule covers WHICH paths require which tier of test enforcement. This rule covers whether the primitive's PAIR ships at all.
+
+## Refs
+
+- bassclef-upstream#328 (this rule's filing ticket)
+- bassclef-upstream#322 (single-instance case that seeded the generalization)
+- bassclef-upstream#319 (hook wiring instance — partial-close via bet 25a WU-3)
+- bassclef-upstream#324 (lib accessor library instance — closed via bet 25a)
+- bassclef-upstream#325 (workflows instance — closed via bet 25b)
+- bassclef-upstream#326 (design + patterns instance — closed via bet 25c)
+- `architecture/audits/2026-06-24-validator-bootstrap.md` (WU-10 of bet 24c)
+- bet 2026-06-25d — this rule's ship vehicle
+
+## Retirement condition
+
+This rule retires only if substrate primitives cease to require paired bootstrap (very unlikely — the half-shipped failure class is inherent to any modular substrate that crosses the bassclef → adopter boundary). The 5-instance enumeration may grow as new primitive types surface (e.g., agent definitions, luminary catalog entries) — extend the table per amendment.
+
+Closes bassclef-upstream#328.

package/substrate/.claude/rules/branching.md

@@ -0,0 +1,28 @@
+---
+tier: lite
+globs: ["*"]
+description: Trunk-based development — branch naming and flow
+---
+
+Model: trunk-based development (solo variant). `main` is always deployable.
+
+Branch naming:
+- `feature/ISSUE-NNN-short-description`
+- `fix/ISSUE-NNN-short-description`
+- `spike/ISSUE-NNN-short-description`
+
+Every branch ties to a GitHub Issue. No branch without an issue.
+
+Flow: issue → branch from main → work → PR → CI passes → squash merge → delete branch
+
+Rules:
+- Broken main = drop everything
+- No branches older than 5 days — break it up
+- Force push on feature branches is fine, never on main
+- Semantic versioning tags for releases: v0.1.0, v0.2.0
+
+Multi-branch work (autonomous/multi-step sessions):
+- See `standards/branch-stacking.md` for stacked atomic branches
+- Stack manifest declares branches, dependencies, parallel-safety
+- Naming: `feature/ISSUE-NNN-stack-N-short-description`
+- Each branch is independently reviewable and revertable

package/substrate/.claude/rules/cold-adopter-harness-discipline.md

@@ -0,0 +1,129 @@
+---
+tier: lite
+description: Substrate changes that touch any adopter-observable surface MUST pass the cold-adopter harness before merge.
+---
+
+# Cold-Adopter Harness Discipline
+
+Substrate changes that touch any adopter-observable surface MUST pass the cold-adopter harness before merge. The harness lives at `scripts/cold-adopter-harness-sync.sh` and runs as a PR-blocking job in `.github/workflows/bassclef-pr-ci.yml`. This rule is the methodology layer; the CI job is the mechanical layer; both load-bearing together close the audit gap that surfaced 2026-06-25 (harness existed but no rule required substrate evolution to drive a check).
+
+## When this rule fires
+
+Any PR that touches a path in the adopter-observable surface set:
+
+- `.claude/hooks/*.sh` — hook scripts adopters symlink into their `.claude/` dirs
+- `.claude/skills/*/SKILL.md` — skill definitions adopters discover by name
+- `.claude/rules/*.md` — rules adopters inherit via `additionalDirectories`
+- `.claude/agents/*.md` — agent definitions adopters dispatch by role
+- `.claude/luminaries/*.md` — luminaries adopters reference in goal docs
+- `lib/*.sh` — shared accessor libraries adopters source from
+- `standards/*.md` — standards adopters cite as reference
+- `standards/state-spine/schemas/*.json` — schemas adopters validate against
+- `presence/install/bassclef-sync.*.sh` — sync templates adopters vendor
+- `architecture/decisions/ADR-*.md` — ADRs adopters read for architecture context
+- `.github/workflows/bassclef-*.yml` — workflows adopters extend (when the change affects shared workflow shape)
+- `scripts/*.sh` — scripts adopters invoke (when classified as adopter-facing per `.claude/rules/testing-tier-config.md`)
+- Any other path under `~/src/sunj-labs/` that adopter sync hooks resolve through
+
+The rule passes through (does not fire) on:
+
+- Operator content (chronicles, journals, deferred-actions, `docs/operator-private/**`)
+- Documentation edits that stay clear of adopter-observable surface (typo in a chronicle)
+- Test edits where the source under test is not adopter-observable
+- Bug fixes where the harness already covers the change class (the harness IS the regression test in that case)
+
+## What the rule requires
+
+When a PR touches an adopter-observable path, the agent OR operator MUST:
+
+1. **Local pre-push run** — execute `bash scripts/cold-adopter-harness-sync.sh --mode sync --target .` from the bassclef-upstream root. Confirm exit 0 (all checks pass) OR explicitly document why a check failure is acceptable.
+2. **CI confirmation** — the `cold-adopter-harness` PR-blocking job in `.github/workflows/bassclef-pr-ci.yml` runs the same command on the PR head. Job must pass before merge.
+3. **PR body acknowledgement** — when the PR body's `Test plan` section is authored, include a line confirming the harness was run locally OR cite the CI job that runs it.
+
+The mechanical layer (CI job) is the load-bearing enforcement. The methodology layer (this rule + the local pre-push step) closes the gap between commit time and CI-fire time.
+
+## What this rule does NOT require
+
+- Running the harness on every commit (only on substrate-affecting paths; the path matcher above is the trigger)
+- Running the harness on operator content (chronicles, journals — pass-through)
+- Re-running the harness when CI already ran it cleanly and no substrate-affecting paths changed in a follow-up commit
+- A separate harness for adopter-facing scripts (the same `scripts/cold-adopter-harness-sync.sh` covers all surfaces)
+- Pre-commit-time enforcement (deferred to follow-on; bet 25g closes the CI + methodology layers; pre-commit hook is Gap 4 follow-on)
+
+## Anti-patterns
+
+These shapes fail this rule.
+
+**Substrate change shipped without running the harness locally.** Author edited `.claude/hooks/<name>.sh`, ran the test suite, pushed. CI catches it but the round-trip cost is one PR cycle wasted.
+
+INSTEAD: run `bash scripts/cold-adopter-harness-sync.sh --mode sync --target .` before pushing. Catches the same class of failure locally; saves the CI round-trip.
+
+**Substrate change shipped + CI green + harness still fails.** The CI job ran but produced a stale result because the harness was not extended to cover the new check class. The author's PR ships; an adopter cloning fresh hits the failure.
+
+INSTEAD: extend the harness check classes in the same PR that introduces the new surface. Per `.claude/rules/bootstrap-pair-discipline.md` — when a new substrate primitive ships, its bootstrap pair includes the harness check class that validates it.
+
+**Author overrides the harness CI job to merge faster.** Operator-merge mode with `SKIP_COLD_ADOPTER_HARNESS=1` set in the workflow environment.
+
+INSTEAD: fix the harness failure OR document the explicit deferral in the PR body's `Out of scope` section with a follow-on ticket reference. Silence is not deferral.
+
+**Adopter-observable change disguised as operator-internal change.** Author edits `presence/install/bassclef-sync.template.sh` (adopter-observable) but commits it as a `chore:` claiming it is internal-only.
+
+INSTEAD: the path-matcher determines adopter-observable status, not the commit message. `presence/install/*` IS adopter-observable; the harness fires.
+
+## Override path
+
+`SKIP_COLD_ADOPTER_HARNESS=1` env var — logged via trace-helper per existing bassclef hook idiom. Use only for:
+
+- One-shot migration scripts that bootstrap state and intentionally produce a harness failure during the migration window (the migration itself fixes the failure)
+- Emergency rescue when the harness itself is broken (substrate-defect recovery; harness must be fixed before next PR)
+- Explicitly-deferred work where the PR body documents the override + cites a follow-on ticket that closes the deferred check
+
+For routine work, run the harness. The cost is ~30 seconds on `--target .` (no live network fetch). The discipline holds across every PR.
+
+## How bassclef channels this discipline
+
+The discipline lives in three layers — pre-commit (operator-side fast-fail), PR-CI (PR-side enforcement), and /verify (operator-side audit) — all firing the same 12-pattern matcher per Saltzer-Schroeder complete mediation:
+
+- `.claude/rules/cold-adopter-harness-discipline.md` — this rule (methodology layer)
+- `.claude/hooks/pre-commit-gate.sh` § "Cold-adopter harness fast-path" — pre-commit layer (operator-side fast-fail; ships via bet 25h WU-2). Detects substrate-affecting staged paths, runs harness in `--mode structural` for fast feedback, BLOCKs the commit on harness failure. Override: `SKIP_COLD_ADOPTER_HARNESS=1 git commit`.
+- `.github/workflows/bassclef-pr-ci.yml` — `cold-adopter-harness` PR-blocking job (PR-CI mechanical layer; ships via bet 25g WU-2)
+- `.claude/skills/verify/SKILL.md` — operator-side audit composition (ships via bet 25h WU-3)
+- `scripts/cold-adopter-harness-sync.sh` — the shape b harness all three layers invoke; extended with workflow-loop checks via bet 25g WU-3; FURTHER extended with Shape d mechanism-fidelity check classes via bet 27c WU-5 (4 new classes: `hook-wiring-presence`, `hook-path-resolution-under-install-class`, `hook-end-to-end-smoke`, `rule-mechanism-claim-fidelity`; V1 ADVISORY → V2 BLOCK after Bet C-pre-2 cures land)
+- `standards/cold-adopter-harness.md` (standard tier — operator + standard adopter reachable) — operational reference for invocation + check semantics; documents Shape d V1 ADVISORY mode per bet 27c WU-5
+- `.claude/rules/bootstrap-pair-discipline.md` — sister rule; amended in bet 25g WU-1 to list cold-adopter validation as a paired bootstrap class
+
+## Composes with
+
+- `@luminary saltzer-schroeder` — complete-mediation principle (every adopter-observable surface validated by the harness; the rule names which surfaces are observable)
+- `@luminary hyrum-wright` — observable behavior becomes load-bearing (the harness pins the observable contract; this rule formalizes that pinning)
+- `@luminary linus-torvalds` — adopter-trust ceiling (CI gate IS the operational form of the adopter-compatibility stance; rule names the discipline)
+- `@luminary michael-feathers` — characterization tests at the adopter boundary (the harness IS the characterization test; this rule mandates the test fires)
+- `.claude/rules/we-dont-break-adopters.md` — sister discipline; this rule is the test-side of the discipline that rule defines
+- `.claude/rules/bootstrap-pair-discipline.md` — sister rule; this rule's "harness check class" IS one of bootstrap-pair's required pairs for adopter-observable primitives
+- `.claude/rules/testing-tier-config.md` — Tier 0 paths the harness validates; sister rule for per-path test enforcement
+- `.claude/rules/loop-discipline.md` — the per-PR cycle this rule fires within (loop's final-validation step composes the harness check)
+- `.claude/rules/blocked-items.md` — BLOCK protocol the CI job fires when the harness fails
+
+## Distinct from
+
+- `.claude/rules/we-dont-break-adopters.md` — that rule names the operator-side discipline (ship within the adopter contract); this rule names the mechanical enforcement (the harness fires on every PR)
+- `.claude/rules/bootstrap-pair-discipline.md` — that rule lists 5 substrate-primitive classes that need paired bootstrap; this rule extends with the adopter-validation pair as a 6th class
+- `.claude/rules/testing-tier-config.md` — that rule names per-path test enforcement tier; this rule names harness-level enforcement that composes with per-path tiers
+- `scripts/release-to-bassclef.sh` — that script publishes substrate downstream; this rule's harness is a pre-publish gate (CI fires before release pipeline runs)
+
+## Refs
+
+- bassclef-upstream#341 — shape c (this rule + the CI job ship together via bet 25g)
+- bassclef-upstream#333 — shape a (harness foundation; closed via 25e)
+- bassclef-upstream#320 — substrate architect-review epic (closed; 24c umbrella still in_flight)
+- bet `docs/iteration-bets/2026-06-25g-cold-adopter-ci-and-discipline.md` — ship vehicle
+- bet `docs/iteration-bets/2026-06-25f-fixes-then-harness.md` — shape b parent
+- ADR-029 release pipeline (CI harness fires before release)
+- ADR-031 (`we-dont-break-adopters` decision) — this rule is the test-side enforcement
+- 2026-06-25 /longrun prep audit — surfaced the 5 wiring gaps this rule + bet 25g close (3 of 5)
+
+## Retirement condition
+
+This rule retires only if bassclef stops having adopters OR the cold-adopter harness retires. The CI mechanical layer may evolve (separate workflow, runner profile change, harness extension) but the discipline of validating adopter-observable surface before merge persists.
+
+Closes audit Gap 2 surfaced at /longrun prep 2026-06-25. Sister gaps 4 + 5 (pre-commit hook, /verify composition) filed as follow-ons during bet 25g closeout.

package/substrate/.claude/rules/commit-conventions.md

@@ -0,0 +1,22 @@
+---
+tier: lite
+globs: ["*"]
+description: Commit message format — Conventional Commits
+---
+
+Format: `<type>: <description>`
+
+Types: feat, fix, docs, refactor, test, ci, chore, security
+
+Rules:
+- Imperative mood, lowercase, no period, max 72 chars
+- Body: explain WHY not what — the diff shows what
+- Footer: `Closes #NNN` or `Ref #NNN`
+- PR titles become squash commit messages — make them clean
+- One commit per PR on main (squash merge)
+
+## Forbidden prefixes
+
+Don't use `substrate-defect:` as a prefix. INSTEAD: use `fix:` per the type list above. Substrate bugs are bugs — the bassclef-internal `substrate-defect:` prefix duplicates the conventional `fix:` category without adding signal. See bassclef#1241 § "Wordlist amendment from 2026-06-19 dispatch session" for the decision.
+
+Don't invent one-off prefixes outside the 8 types listed above. INSTEAD: request additions via `/promote bassclef-evolution` so the type list grows by amendment rather than drift.