@thebassclef/lite 1.1.1 → 1.2.0-alpha.1

package/dist/lite/.claude/rules/file-rename-discipline.md

@@ -0,0 +1,95 @@
+---
+tier: lite
+description: Every file rename in bassclef registers an entry in standards/file-renames.json AND ships a fixture test that asserts the migrate script cures adopters carrying the old name.
+---
+
+# File-rename discipline
+
+Every file rename in bassclef registers an entry in `standards/file-renames.json` AND ships a fixture test that asserts the migrate script cures adopters carrying the old name. No exception. The pre-commit hook at `.claude/hooks/file-rename-discipline-check.sh` blocks commits that delete a file under the discipline's scope unless the rename is registered.
+
+This rule exists because a file rename shipped on 2026-06-21 without a migration path that reached every adopter. POA's session on 2026-06-29 surfaced the gap — broken symlinks at the old name, settings.json hooks pointing at files that no longer existed in bassclef. The first rename map entry (shipped in WU-9 of this goal) documents the case:
+
+```
+{
+  "old_name": "canonical-source-config-validate.sh",
+  "new_name": "bassclef-source-config-validate.sh",
+  "renamed_at": "2026-06-21"
+}
+```
+
+The cure shipped in bet 29e WU-9; this rule prevents the next rename from repeating the failure.
+
+## When this rule fires
+
+Any commit that deletes a file under any of these paths:
+
+- `.claude/hooks/`
+- `.claude/skills/`
+- `.claude/rules/`
+- `.claude/luminaries/`
+- `.claude/agents/`
+- `scripts/`
+- `lib/`
+- `standards/`
+- `presence/`
+- `architecture/decisions/` (ADR renames need migration too)
+
+The hook scans the commit's deletions against the rename map's `old_name` column. If a deletion is in the map, the commit proceeds. If a deletion is missing from the map, the hook BLOCKs with a structured remediation message naming the three required moves.
+
+## What the rule requires
+
+When a file in the scoped paths is renamed (deleted at the old path + created at the new path, OR moved via `git mv`), the same commit MUST include:
+
+1. **A new entry in `standards/file-renames.json`** under the `renames` array — pairs the old filename with the new one, the date the rename ships, and a category tag.
+
+2. **A fixture test under `.claude/hooks/tests/fixtures/adopter-<YYYY-MM-DD>-rename/`** (one fixture per rename event). The fixture mirrors the adopter state that will exist after the rename ships — broken symlinks at the old name, settings.json references that need rewriting, working symlinks at the new name. The migrate script's test suite runs against the fixture; assertions pin the cure.
+
+3. **An entry in the goal doc or chronicle** that names the rename + the migration path. Renames are deliberate filings; passing renames have no place under this rule.
+
+INSTEAD of treating a rename as a quick cleanup: file the entry, ship the fixture, name the event in a chronicle. The discipline takes minutes; the compound cost of skipping it shows up across every adopter.
+
+When a file is being deleted without a successor (decommissioned, retired), the same commit MUST include:
+
+- `# BREAKING: <reason>` comment in the deletion's PR body, OR
+- An entry in a separate `compat_shims_preserved` section of `standards/file-renames.json` explaining why the old name continues to work via a different mechanism
+
+INSTEAD of a bare deletion: pair the deletion with either the breaking-change declaration or the compat-shim entry. The adopter sees the change explicitly; the substrate carries the migration cost.
+
+## Compat-shim case
+
+Some renames preserve the old name as a compat shim per ADR-031. The dispatcher's legacy filename is the documented example — it works via the two-stage rocket per ADR-032, so adopters with the old name continue to load substrate cleanly without rewriting their settings.json. The rename map's `compat_shims_preserved` section records the case:
+
+```
+{
+  "old_name": "canonical-sync.sh",
+  "reason": "ADR-031 compat-shim discipline kept alive",
+  "added": "2026-06-29"
+}
+```
+
+For compat-shim renames, the rename map's `compat_shims_preserved` list documents the case. The pre-commit hook treats the old name as still-living; the new name + old name coexist for the documented deprecation window.
+
+INSTEAD of removing the old name silently when a compat shim is in place: keep the old name alive, document the shim, set a deprecation window. The adopter migrates on their own cadence; bassclef carries the cost in the meantime.
+
+## Override path
+
+`SKIP_FILE_RENAME_DISCIPLINE=1 <command>` — bypass logged via trace-helper. Two genuine cases:
+
+- Migrating bulk content where the rename map cannot capture every entry within the commit window (operator-approved exception)
+- Emergency rescue where the hook itself misbehaves and blocks legitimate work (file substrate-defect)
+
+INSTEAD of using the override as a regular practice: register the rename. The map entry takes seconds; the override exists for genuine edge cases.
+
+## Composes with
+
+- `standards/file-renames.json` — the single source of truth for renames; this rule cites it as authoritative
+- `scripts/migrate-adopter-references.sh` — Surface 5 + Surface 6 read the map
+- `.claude/hooks/file-rename-discipline-check.sh` — the mechanical layer (added in this step)
+- `.claude/rules/we-dont-break-adopters.md` — sister discipline (ADR-031); this rule operationalizes the "every rename ships with a migration path" requirement
+- `.claude/rules/testing-tier-config.md` — Tier 0 strict-TDD on the hook + tests
+- `.claude/rules/blocked-items.md` — BLOCK protocol the hook fires
+- `.claude/rules/bootstrap-pair-discipline.md` — sister discipline at the "every primitive ships with its paired bootstrap" surface; this rule extends to rename events specifically
+- @luminary linus-torvalds — adopter contract; the kernel preserves userspace through every rename; bassclef preserves adopter contracts the same way
+- @luminary michael-feathers — characterization tests pin the actual adopter state before the cure ships
+- @luminary kent-beck — mechanical enforcement at the commit boundary
+- @luminary hyrum-wright — every observable filename becomes a contract with enough adopters

package/dist/lite/.claude/rules/mechanism-fidelity.md

@@ -0,0 +1,88 @@
+---
+tier: lite
+description: "Every rule that names a mechanical enforcement makes a contract: the mechanism exists, is wired, resolves paths under both install classes, has a Tier 0 test pinning behavior."
+---
+
+# Mechanism Fidelity
+
+Every rule that names a mechanical enforcement makes a contract: the mechanism exists, is wired, resolves paths under both install classes, has a Tier 0 test pinning behavior. The mechanism-fidelity discipline verifies this contract end-to-end. Audit skill + harness check classes + (proposed) per-edit hook + this auto-loaded rule together form a 4-layer defense.
+
+This rule is the methodology layer. The mechanical layers are `/audit-rule-mechanism-fidelity` skill (operator-invocable) + cold-adopter harness Shape d (per-PR) + bassclef-upstream#433 per-edit hook (proposed for cure bet). All 3 mechanical layers compose `lib/mechanism-fidelity.sh` — the shared deep module.
+
+## When this rule fires
+
+Every session. Auto-loaded via `additionalDirectories`. Cross-references the substrate-as-system tenet rule + cites the 4 verification layers.
+
+The mechanical layers fire at:
+- Per-edit: `bassclef-upstream#433` proposed hook (PreToolUse `Edit|Write` on `.claude/rules/*.md`) — V1 ADVISORY in cure bet
+- Per-PR: cold-adopter harness Shape d 4 check classes (V1 ADVISORY in bet 27c WU-5)
+- Per-architect-review: audit skill auto-fired (bet 27c WU-9.5 SKILL amendment)
+- Per-operator-demand: audit skill operator-invocable (bet 27c WU-4)
+
+## What this rule requires
+
+For any rule body that names a mechanical enforcement:
+
+1. **Cite the hook by filename** — `.claude/hooks/<name>.sh` reference in rule body
+2. **Cite the wiring** — note that the hook is wired in `.claude/settings.json` (or operator settings under user install class)
+3. **Cite the test** — note that Tier 0 test exists at `.claude/hooks/tests/<name>.test.sh` per `.claude/rules/testing-tier-config.md`
+4. **Cite the install-class declaration** — note that the hook declares `# install-class: dual` (or operator/project as appropriate) per `standards/hook-install-class.md`
+5. **Verify before commit** — at least one of the 4 mechanical layers MUST have run on the rule change (at minimum, `bash scripts/cold-adopter-harness-sync.sh --mode sync --target .` Shape d before push)
+
+## Classification labels (per `standards/mechanism-fidelity.md`)
+
+`lib/mechanism-fidelity.sh` `classify_finding` returns one of 10 labels for each rule claim:
+
+| Label | Meaning | Cure |
+|---|---|---|
+| `CLEAN` | exists + wired + path-ok + test present | no action |
+| `DEAD-LETTER` | hook exists but not wired in settings.json | wire in settings.json (per `.claude/rules/hook-wire-on-author.md`) |
+| `UNWIRED` | claimed hook does not exist anywhere | author the hook OR remove the rule's claim OR reword to methodology-only |
+| `PATH-BROKEN` | hook uses SCRIPT_DIR/../../<project-resource> + declares install-class: operator | refactor to `install-class: dual` + source `lib/hook-inject.sh` (kiss cure PR #427 pattern) |
+| `TEST-MISSING` | hook exists + wired + path-ok but no Tier 0 test | author Tier 0 test per `.claude/rules/test-sufficiency.md` |
+| `METHODOLOGY-ONLY` | rule names no mechanism (intentional self-discipline) | no action; rule loads as steering only |
+| `SILENT-PASS` | hook fires but exits 0 without enforcing (runtime-only finding) | surface via smoke step 5; cure per defect class |
+| `NOT-WIRED-BY-DESIGN-CI` | hook lives on disk; referenced from `.github/workflows/*.yml`; settings.json is not the right home | no action — workflow IS the wiring (bet 29a WU-1) |
+| `NOT-WIRED-BY-DESIGN-LAUNCHD` | hook is scheduled by macOS launchd or cron; header comment names the scheduler; settings.json is not the right home | no action — scheduler IS the wiring (bet 29a WU-1) |
+| `NOT-WIRED-BY-DESIGN-LIB` | file is sourced by other hooks (library role); settings.json is not the right home | no action — sourcing IS the use pattern (bet 29a WU-1) |
+
+## Anti-patterns
+
+These shapes fail this rule.
+
+**Rule cites a non-existent hook.** UNWIRED classification. Cure: author the hook OR remove the claim.
+
+**Rule cites a hook that exists but is not in settings.json.** DEAD-LETTER classification. Cure: add the settings.json entry (per `.claude/rules/hook-wire-on-author.md`).
+
+**Rule cites a hook that exists + is wired but uses SCRIPT_DIR/../../ pattern + declares install-class: operator.** PATH-BROKEN classification. Cure: refactor via `lib/hook-inject.sh` resolve_* helpers; declare `install-class: dual` (kiss cure PR #427 is the exemplar).
+
+**Rule cites a hook that has no Tier 0 test.** TEST-MISSING classification. Cure: author the test per `.claude/rules/test-sufficiency.md` criterion 11 (path-resolution under both install classes).
+
+**Rule body has no Sources read block citing the parent_goal path.** Different defect class (handled by `.claude/hooks/artifact-ingestion-gate.sh`); orthogonal but related.
+
+## Composes with
+
+- `.claude/rules/substrate-as-system.md` — sister tenet rule (per ADR-035 substrate-as-system tenet)
+- `.claude/rules/bootstrap-pair-discipline.md` — instance 2 of the pair table covers rule + cited hook
+- `.claude/rules/hook-wire-on-author.md` — settings.json wiring discipline (cure path for DEAD-LETTER findings)
+- `.claude/rules/testing-tier-config.md` — Tier 0 strict-TDD on substrate paths (cure for TEST-MISSING)
+- `.claude/rules/test-sufficiency.md` criterion 11 (added bet 27c WU-9) — path-resolution under both install classes
+- `.claude/rules/cold-adopter-harness-discipline.md` — sister per-PR enforcement (lists Shape d check classes from WU-5)
+- ADR-035 — substrate-as-system tenet + 9-surface hook taxonomy
+- `standards/mechanism-fidelity.md` (bet 27c WU-2; extended bet 29a WU-1) — full reference; 10 classification labels; 5-step verification chain
+- `standards/hook-install-class.md` (bet 27c WU-2) — install-class declarations
+- `lib/mechanism-fidelity.sh` (bet 27c WU-3) — shared deep module for verification chain
+- `lib/hook-inject.sh` (bet 27c WU-3) — path-resolution lib (cure for PATH-BROKEN)
+- `.claude/skills/audit-rule-mechanism-fidelity/SKILL.md` (bet 27c WU-4) — operator-invocable audit
+- `scripts/cold-adopter-harness-sync.sh` Shape d (bet 27c WU-5) — per-PR gate
+- bassclef-upstream#433 — proposed per-edit enforcement hook (4th layer in defense stack)
+- @luminary saltzer-schroeder — complete mediation (every previously-blind path closed)
+- @luminary michael-feathers — characterization tests as cure (code without tests is legacy code by definition)
+- @luminary tony-hoare — pre/postcondition contracts (rule body claims become observable contracts)
+- @luminary john-ousterhout — deep modules (one impl, many consumers)
+
+## Override
+
+`SKIP_MECHANISM_FIDELITY=1 <command>` — for genuine one-shot scripts that intentionally skip verification. Logged via trace-helper.
+
+INSTEAD of overriding for routine rule edits: run `bash scripts/cold-adopter-harness-sync.sh --mode sync --target .` Shape d before push. Catches V1 ADVISORY findings; cures defer to Bet C-pre-2.

package/dist/lite/.claude/rules/prototype-production-coupling.md

@@ -0,0 +1,125 @@
+---
+tier: lite
+description: Design prototypes are load-bearing artifacts, not sketches.
+---
+
+# Prototype–Production Coupling
+
+Design prototypes are load-bearing artifacts, not sketches. Once a prototype
+is approved and merged to `docs/prototypes/`, it becomes the reference the
+production UI is measured against — and the gate that keeps backend
+plumbing from outrunning its consuming surface.
+
+Four obligations, all MUST:
+
+## 1. Tokens extracted from prototype precede Construction
+
+Design tokens (colors, spacing, typography, motion) extracted from the
+approved prototype MUST land in `design/tokens/` (or equivalent
+repo-level location) BEFORE any Construction branch builds the production
+UI for that surface.
+
+**Why**: building the production surface against ad-hoc values and then
+"reconciling with tokens later" produces drift that visual review
+catches after the fact, forcing rework. Tokens-first means production
+inherits the prototype's visual contract from the first commit.
+
+**How to apply**: when `/riff-prototypes` selects a direction and
+the operator approves a variant, the next skill in the chain is token
+extraction, not feature work. `/ux-migration` or `/frontend-design`
+reads tokens from `design/tokens/`, not from the prototype HTML.
+
+Closes #527 (POA).
+
+## 2. Coupled-PR rule — backend doesn't ship without consuming surface
+
+A backend PR that exposes or modifies a user-visible surface MUST NOT
+merge to main until the consuming surface has **at least a merged
+prototype** in `docs/prototypes/`. The prototype may be static, behind
+a flag, or mock-data-driven — but it MUST be merged and discoverable.
+
+**Why**: backend plumbing merged before the UX surface exists creates
+orphaned work. Sequencing pressure moves to whatever's next, the
+consuming UI ages, and the surface stays unchanged until someone
+notices. Two POA sessions in April 2026 shipped this exact failure.
+
+**How to apply**:
+- "Consuming surface" = any API route, data model change, or schema
+  migration whose values land in a UI a user sees.
+- Internal-only / operator-facing / tooling changes are exempt but
+  MUST be labeled as such in the PR description.
+- Iteration proposals that sequence backend-before-UX MUST declare
+  the prototype commitment explicitly. A plumbing-first proposal
+  without a prototype-first predecessor is incomplete scope.
+- Reviewer checklist item: "consuming UX has merged prototype" —
+  not self-reported, evidence required (link to prototype file).
+
+Closes #114 (bassclef).
+
+## 3. Visual-review-per-UI-PR is a MUST gate
+
+Any PR that modifies production UI MUST run `/visual-review` before
+merge. The review compares rendered output against design tokens,
+usability standard, and luminary guidance.
+
+**Why**: code review catches logic drift. Only visual review catches
+visual drift. A UI PR that passes CI but hasn't been rendered and
+inspected is unverified on the dimension that matters most for users.
+
+**How to apply**:
+- `/visual-review` output (screenshots + findings) attached to the PR
+  before merge approval
+- Failure modes from visual review (token violations, usability gaps,
+  luminary mismatch) block merge the same way a failing test does
+- Exempt: non-visual UI changes (data-only refactors, type changes,
+  pure accessibility labels). Must be declared in PR.
+
+Closes #528 (POA).
+
+## 4. Prototype-to-production drift test on each UI PR
+
+`/visual-review` MUST include a step that diffs the rendered production
+surface against the approved prototype for that surface. Structural
+divergence (layout, hierarchy, affordances) from the prototype is a
+finding, not an acceptable variance.
+
+**Why**: prototypes encode design decisions that survive translation
+into tokens + components. Production drift from prototype is either
+(a) a bug in the build, or (b) an undocumented design change. Both
+require surfacing, not silent acceptance.
+
+**How to apply**:
+- `/visual-review` procedure includes: "locate the approved prototype
+  referenced by the iteration goal or canvas; render both; diff
+  structurally"
+- Acceptable variances: responsive adaptation, real-data density
+  shifts, performance-driven simplifications — all MUST be called out
+  in the review with rationale
+- Unacceptable: layout restructure, affordance changes, hierarchy
+  inversions, token substitutions not documented in an ADR
+
+Closes #575 (POA).
+
+## Relationship to other rules
+
+- `prototype-workflow.md` — protects operator approval of prototype
+  BEFORE commit; this rule enforces what happens AFTER approval
+- `design-direction.md` — approvals are load-bearing; this rule
+  operationalizes "load-bearing" into four specific gates
+- `usability.md` #7 — visual verification; #3 here is the stronger
+  MUST formulation
+- `sdlc-gates.md` post-build — `/verify` on UI change runs
+  `/visual-review`; this rule defines what `/visual-review` must check
+
+## Enforcement
+
+- **#1 (tokens-first)**: methodology-level; `/ux-migration` and
+  `/frontend-design` SKILL.md reference `design/tokens/` as
+  prerequisite input
+- **#2 (coupled-PR)**: reviewer checklist + pre-merge hook (future)
+  that checks whether PR touches user-surfacing paths and greps
+  `docs/prototypes/` for a matching merged prototype
+- **#3 (visual-review MUST)**: `/verify` skill matches UI change type
+  to `/visual-review`; blocks commit without review artifact
+- **#4 (drift test)**: `/visual-review` SKILL.md procedure includes
+  prototype-diff step

package/dist/lite/.claude/rules/quick-fix-criteria.md

@@ -0,0 +1,90 @@
+---
+tier: lite
+description: /quick-fix is the compressed fix workflow for trivial bugs.
+---
+
+# Quick-Fix Entry Criteria
+
+`/quick-fix` is the compressed fix workflow for trivial bugs. Entry is
+gated by STRICT criteria — all five must hold. This rule codifies them
+so agents can't soften "mostly obvious" into "obvious."
+
+## Criteria (ALL must hold)
+
+1. **Localized** — defect lives in a single file (or two for rename /
+   type propagation). Cross-cutting concerns disqualify.
+2. **Obvious cause** — root cause expressible in one sentence without
+   reading logs or drawing resolution chains.
+3. **Obvious fix** — ≤10 lines of change, no new interfaces, no new
+   abstractions, no schema changes.
+4. **Low blast radius** — NOT auth, NOT middleware, NOT schema, NOT
+   security, NOT tenant boundary. Any of those = full /diagnose.
+5. **Reproducible OR trivially verifiable** — Step 0 repro is either
+   explicitly skippable (typo / env var / off-by-one) or one-line.
+
+Any failure → escalate to /diagnose (full) or /auto-fix.
+
+## Why strict
+
+Observed across prior sessions: agents rationalize "mostly localized"
+and "mostly obvious" into /quick-fix eligibility. Soft criteria collapse
+into default. Hard five-out-of-five discipline is the only shape that
+holds.
+
+## Audit discipline
+
+Every /quick-fix commit carries `[quick-fix]` footer. Monthly ratio:
+
+```bash
+FIX_COUNT=$(git log --all --oneline --since='30 days ago' --grep='^fix:' | wc -l)
+QF_COUNT=$(git log --all --oneline --since='30 days ago' --grep='\[quick-fix\]' | wc -l)
+```
+
+Target: ≤30% of fix branches use /quick-fix. Higher ratio = criteria
+too loose OR defect mix over-represents trivial. Either shape is
+actionable; silent drift is not.
+
+## Blast-radius floor (hard)
+
+These paths ALWAYS require full /diagnose regardless of other criteria:
+
+- `src/middleware.ts` / `src/app/**/middleware.ts`
+- `src/lib/auth/**` / `src/app/api/auth/**`
+- `prisma/schema.prisma` / `prisma/migrations/**`
+- `src/lib/security/**`
+- Any tenant-scoped query or tenant-context resolution
+- `.github/workflows/deploy*.yml`
+- Production environment variables
+- Database seed data
+
+If the fix touches any of these → not eligible for /quick-fix,
+regardless of size.
+
+## Enforcement
+
+- Skill: `.claude/skills/quick-fix/SKILL.md` requires explicit
+  criteria-check output before proceeding
+- Methodology: agent self-checks every criterion; silence is not skip
+- Future: pre-commit hook could check `[quick-fix]` footer presence on
+  any commit authored with /quick-fix; currently methodology-level
+
+## Override
+
+There is no override path for criteria. Either all five hold (quick-fix)
+or they don't (full diagnose). Softening the criteria softens the rule.
+
+## Relationship
+
+- `.claude/skills/quick-fix/SKILL.md` — the skill that cites this rule
+- `.claude/rules/diagnosis.md` — the full-ceremony rule
+- `.claude/rules/auto-fix-criteria.md` — sibling for the autonomous lane
+- `blocked-items.md` — if criteria fail, escalation is not optional
+
+## When this rule retires
+
+If observed over 6 months with audit ratio consistently ≤20% and zero
+operator corrections, the criteria may be too strict. Loosen criterion
+3 (lines) or criterion 1 (files) — not criterion 4 (blast radius).
+Criterion 4 is load-bearing.
+
+Closes bassclef #151 (paired with skill).

package/dist/lite/.claude/rules/session-artifacts.md

@@ -26,6 +26,36 @@ to specific adopter sessions.
 This applies to bassclef's own repo only; adopter repos keep
 chronicles + markers tracked per their own configuration.
 
+### Known contradiction — this rule is authoritative, the shipped config is not yet
+
+`presence/dist-templates/.gitignore` is the file adopters install. It
+ignores `state/markers/`. That contradicts the sentence above, so an
+adopter who runs `/temperance` watches the skill run `git add` and watches
+git refuse it. Reported as bassclef-upstream#1694.
+
+This rule wins. Adopters are meant to track their markers. The shipped
+config has not caught up.
+
+**Why it has not changed yet, and the order it must change in.** Per
+RFC-0009: 31 of 899 markers measured 2026-09-17 carry an absolute path or
+a machine name. Today the ignore fails safe — nothing leaks. Untracking
+before those paths are scrubbed opens a window where 3.4% of markers can
+be committed and pushed, and a path in git history is not removable
+without rewriting someone else's repo.
+
+So the order is: scrub the paths at write time, verify on a real install
+per bassclef-upstream#1706, then stop ignoring. Not the other way round.
+
+**Why adopters track them.** Not an audit trail — state transfer. A marker
+that only exists on the machine that wrote it cannot reach a second machine
+or a teammate. Every gate re-fires on the other side, and work does not pick
+up where it left off. Tracking markers is what makes a session resumable by
+someone else, or by the same person on different hardware.
+
+Measured: 78 files reference `state/markers`, three read a marker's content,
+and nothing reads marker history from git. That absence is a symptom of the
+ignore, not an argument for it. Nothing reads what never survives.
+
 ## Backfill before current (MUST — applies to all artifacts below)
 
 Before writing ANY session artifact (chronicle, journal entry, release notes):

package/dist/lite/.claude/rules/sibling-smoke-after-substrate-change.md

@@ -0,0 +1,107 @@
+---
+tier: lite
+description: When a PR touches an adopter-observable substrate path (.claude/hooks/.sh, .claude/rules/.md, .claude/skills//SKILL.md, .claude/agents/.md, lib/.sh, or…
+---
+
+# Sibling Smoke After Substrate Change
+
+When a PR touches an adopter-observable substrate path (`.claude/hooks/*.sh`, `.claude/rules/*.md`, `.claude/skills/*/SKILL.md`, `.claude/agents/*.md`, `lib/*.sh`, or `standards/state-spine/schemas/*.json`), a sibling smoke obligation is owed before the next `/release` ships the change downstream. The harness verifies structure; the smoke test verifies behavior in a real adopter session.
+
+This rule is the methodology layer. The mechanism (advisory prompt in `/release` dry-run output) ships under sunj-labs/bassclef-upstream#545 V2.
+
+## When this rule fires
+
+Any PR that touches adopter-observable substrate paths (matcher above). The cold-adopter harness rule at `.claude/rules/cold-adopter-harness-discipline.md` names the same matcher; this rule extends it with the sibling-smoke obligation.
+
+The rule passes through on:
+
+- PRs touching only operator content (chronicles, journals, deferred-actions)
+- PRs touching only documentation that does not change adopter-observable behavior
+- Bug fixes where the harness already covers the change class via fixture-driven tests
+
+## What the rule requires
+
+Between PR merge and the next `/release` dispatch, the operator runs a smoke test in a sibling adopter repo:
+
+1. Pick a sibling — POA, twoDo, eugene-supplements, family-recipe-2, or quorum
+2. Run `bash .claude/hooks/bassclef-sync.sh` in the sibling (pulls from current public bassclef OR from a temporary upstream pointer for pre-release verification)
+3. Start a fresh Claude Code session in the sibling
+4. Verify SessionStart output:
+   - No errors from new or modified hooks
+   - In-flight bet surfaces correctly (cure 1 from session-orientation audit)
+   - Orientation gate behaves correctly on main + feature branches (cure 2)
+   - No broken symlinks
+   - The cure's intended behavior visible (e.g., the new `### ACTIVE BET` block appears at SessionStart)
+5. Record the smoke result with a one-line note in the next `/release` dry-run output:
+   - PASS: `Sibling smoke: ran <sibling-repo> SessionStart at <ISO timestamp>; clean — <one-line observation>`
+   - FAIL: `Sibling smoke: ran <sibling-repo> SessionStart at <ISO timestamp>; FAIL — <one-line observation>`. PR holds until cured.
+
+The smoke is operator-driven. The mechanism extension under #545 V2 puts the prompt in `/release` dry-run output. Until V2 ships, the rule loads at session start and the operator runs the smoke before invoking `/release`.
+
+## Sibling pick guidance
+
+| Sibling | Best for | Why |
+|---|---|---|
+| POA | Highest-cure-impact changes | Largest adopter footprint; surfaced bet 30a's F7 cure validation |
+| twoDo | UI-adjacent cures | Front-of-shop adopter; visible Stuff |
+| eugene-supplements | apps/web Tier 1 / ORM-adjacent cures | Active development; runs frequent sessions |
+| family-recipe-2 | Lower-traffic adopter | Catches edge cases the high-traffic siblings miss |
+| quorum | Substrate-discipline cures | Heavy use of `/longrun`, `/temperance`, `/luminary`; surfaces SKILL.md drift |
+
+Operator picks based on which sibling exercises the cure's surface most directly.
+
+## Anti-patterns
+
+These shapes fail the rule. Each pairs with the INSTEAD shape that satisfies it.
+
+**Skipping the sibling smoke before `/release`** — cure rides to public bassclef; first adopter `bassclef-sync` pull verifies it in production. Cost compounds: if the cure is broken, every adopter pulls the broken version before the gap is noticed.
+INSTEAD: smoke test BEFORE `/release` dry-run; surface the result in dry-run output.
+
+**Running the smoke via temporary symlink swap (pointing the sibling at `bassclef-upstream` instead of `bassclef`)** — verifies the cure in a non-adopter shape. Adopters get the cure via `bassclef-sync` from public bassclef, not from `bassclef-upstream` directly. The symlink swap simulates an environment no real adopter runs in.
+INSTEAD: ship the cure via `/release` to public bassclef first AND smoke against the public-pulled state, OR smoke against the fixture harness (`run-with-fixtures.sh`) which simulates adopter shape without the symlink swap.
+
+**Treating CI "all green" as sufficient** — CI verifies structure + harness-level smoke. Real-session behavior in an adopter shape is unverified. Tonight's WU-B + WU-E shipped 9 GREEN CI checks and zero fixture-driven coverage.
+INSTEAD: CI is necessary but not sufficient. Sibling smoke closes the behavior-verification gap.
+
+**Shipping cure tests with no fixture header** — test rides CI's vanilla environment only. Cure's fixture coverage is zero. Per #545 fixture-header BLOCK (V2), this becomes a Tier 0 enforcement.
+INSTEAD: every cure test on substrate-affecting paths declares `# fixtures: <name>` in its top-of-file header and uses `FIXTURE_DIR` in at least one assertion. The `run-with-fixtures.sh` wrapper runs the test per fixture; the cure rides every declared adopter shape.
+
+## Override
+
+`SKIP_SIBLING_SMOKE=1 <command>` — bypass for one `/release` call. Logged via trace-helper. Use only when:
+
+- The cure is a pure no-behavior rename (no symlink target change, no hook semantics change)
+- Emergency rescue where the smoke step itself is broken
+- Operator-confirmed explicit defer naming a follow-on ticket that closes the smoke check
+
+INSTEAD of overriding for routine `/release`: run the smoke. The cost is a few minutes; the discipline compounds across every adopter machine pulling the release.
+
+## V2 mechanism (deferred to follow-on)
+
+Extend `/release` skill dry-run output with a "Sibling smoke evidence" section:
+
+```
+## Sibling smoke evidence
+
+Required (paste one-line confirmation OR explicit defer):
+> Sibling smoke: ran <sibling> SessionStart at <timestamp>; <PASS / FAIL or DEFERRED with reason>
+
+Silence is not deferral. Default is run the smoke.
+```
+
+The `/release` dispatch refuses to fire live until the operator pastes a confirmation OR sets `SKIP_SIBLING_SMOKE=1` with rationale.
+
+V2 also extends `cold-adopter-harness-sync.sh` Shape d with Check 13 (fixture-header-presence): BLOCK on tests in `.claude/hooks/session-reflection.d/tests/` + `.claude/hooks/tests/` that exercise substrate-affecting paths AND lack a `# fixtures: <name>` header. Allowlist baseline for existing untagged tests at write time; grace window per `.claude/hooks/testing-tier-enforce-allowlist.txt` pattern.
+
+## Composes with
+
+- `.claude/rules/cold-adopter-harness-discipline.md` — sister rule; this rule extends with behavioral verification beyond the four Shape d structural checks
+- `.claude/rules/we-dont-break-adopters.md` — sister ADR-031 discipline; sibling smoke is the operational form of "the cure works for adopters"
+- `.claude/rules/testing-tier-config.md` — Tier 0 strict TDD on hooks; this rule extends to per-fixture coverage
+- `.claude/rules/blocked-items.md` — BLOCKED protocol the V2 mechanism fires
+- The fixture-tests wrapper (operator substrate) — runs each test per declared fixture
+- `lib/fixture-builder.sh` — the deep module the fixtures use
+- ADR-031 we-dont-break-adopters
+- ADR-035 substrate-as-system (behavioral verification extends complete-mediation to the runtime layer)
+- ADR-038 adopter testing harness redesign
+- memory `feedback_smoke_test_after_cure_pattern` — the discipline this rule codifies

package/dist/lite/.claude/rules/substrate-as-system.md

@@ -0,0 +1,67 @@
+---
+tier: lite
+description: "Per ADR-035: bassclef's substrate is a system, not a bag of files."
+---
+
+# Substrate as System
+
+Per ADR-035: bassclef's substrate is a system, not a bag of files. Every rule that names a mechanical enforcement makes an end-to-end commitment — the mechanism exists, is wired, resolves paths under both install classes, and has a Tier 0 test that pins behavior. If any link in that chain fails, the rule's claim is unhonored and adopters inherit a contract the substrate cannot keep.
+
+This rule is the auto-loaded reminder. The mechanical layer is `lib/mechanism-fidelity.sh` + `.claude/skills/audit-rule-mechanism-fidelity/SKILL.md` + cold-adopter harness Shape d (4 check classes). Both required.
+
+## When this rule fires
+
+Every session. Auto-loaded via `additionalDirectories`. The reminder steers authoring at every surface where a rule names a mechanism — goal docs, new rules, amended rules, new hooks, new skills.
+
+## What this rule requires
+
+When authoring or amending any rule that names a mechanical enforcement (a hook by filename, an event matcher, a settings.json entry, a Tier 0 test):
+
+1. **End-to-end commitment** — the mechanism must exist on disk + be wired in settings.json + resolve paths under both install classes (project + operator) + have a Tier 0 test pinning behavior
+2. **Path resolution under install class** — if the hook reads project resources, source `lib/hook-inject.sh` and use `resolve_standards_path` + `resolve_config_path` per `standards/hook-install-class.md`. Declare `# install-class: dual` in the hook header.
+3. **Tier 0 test sufficient** — test pins behavior under both install classes via `HOME_OVERRIDE` fixture per `.claude/rules/test-sufficiency.md` (criterion 11 added in bet 27c WU-9). The kiss cure (PR #427) is the exemplar pattern.
+4. **Per-PR verification** — cold-adopter harness Shape d (4 check classes) fires on every PR; ADVISORY V1 (lands in bet 27c WU-5), BLOCK V2 (lands in Bet C-pre-2 cure bet). Verification happens at adopter-PR time, not just at substrate-author time.
+
+## Anti-patterns
+
+These shapes fail this rule.
+
+**Rule says X enforces but no hook exists at the named path.** Per ADR-035 substrate-as-system — claim without referent. Cure: author the hook OR remove the claim OR reword to methodology-only.
+
+**Hook exists but settings.json doesn't wire it.** DEAD-LETTER per `lib/mechanism-fidelity.sh` classification. Cure: add settings.json entry.
+
+**Hook is wired but reads project resources via SCRIPT_DIR/../../ and declares install-class: operator.** Class A failure. The kiss path-resolution defect (PR #427) was the live exemplar. Cure: declare `install-class: dual` + source `lib/hook-inject.sh` + use `resolve_standards_path` per the kiss cure pattern.
+
+**Hook works under project install but Tier 0 test only verifies project-class behavior.** TEST-MISSING per `lib/mechanism-fidelity.sh` classification. Cure: add HOME_OVERRIDE fixture test per kiss cure Tests 54+56 pattern.
+
+INSTEAD of any of these: check the claim before you author it, amend rule bodies to drop claims the substrate does not honor, and ship the fixes.
+
+Operators on the standard or ultra tier can run `/audit-rule-mechanism-fidelity` to do the check in one pass. That skill ships at `tier: upstream`, so lite adopters do not have it. At lite, do the check by hand: open the hook the rule names, confirm it exists, confirm `.claude/settings.json` wires it, and confirm a test sits beside it.
+
+## Composes with
+
+- `.claude/rules/mechanism-fidelity.md` — sister rule that names the audit skill + harness check classes
+- `.claude/rules/bootstrap-pair-discipline.md` — sister discipline (every primitive ships with its paired bootstrap; this rule extends to mechanism-fidelity verification)
+- `.claude/rules/hook-wire-on-author.md` — sister discipline at the settings.json wiring surface
+- `.claude/rules/testing-tier-config.md` — Tier 0 strict-TDD per substrate-internal path
+- `.claude/rules/test-sufficiency.md` — criterion 11 (path-resolution under both install classes) added in bet 27c WU-9
+- `.claude/rules/cold-adopter-harness-discipline.md` — per-PR gate this rule's verification rides
+- ADR-035 — the authority this rule operationalizes at the methodology layer
+- `standards/mechanism-fidelity.md` (WU-2 of bet 27c) — full reference for the verification chain
+- `standards/hook-install-class.md` (WU-2) — `install-class: dual` declaration this rule cites
+- `lib/hook-inject.sh` (WU-3) — path-resolution lib the cure pattern uses
+- `lib/mechanism-fidelity.sh` (WU-3) — verification chain scanner
+- `.claude/skills/audit-rule-mechanism-fidelity/SKILL.md` (WU-4) — operator-invocable audit
+- `scripts/cold-adopter-harness-sync.sh` Shape d (WU-5) — per-PR gate
+- `architecture/audits/2026-06-27-mechanism-fidelity.md` (WU-6) — first findings table
+- `architecture/audits/2026-06-27-audit-method-blind-spot.md` (WU-7.5) — recursive Act phase
+- bassclef-upstream#433 — proposed per-edit enforcement hook (PreToolUse Edit|Write on `.claude/rules/*.md` calls lib's verify chain at agent-author time); fourth layer in the defense stack alongside harness Shape d (per-PR) + audit skill (operator-invocable) + this rule (per-session steering)
+- @luminary saltzer-schroeder — complete mediation
+- @luminary michael-feathers — characterization tests as cure for legacy code
+- @luminary john-ousterhout — deep modules (shared lib reuse across audit + harness)
+
+## Override
+
+`SKIP_SUBSTRATE_AS_SYSTEM=1 <command>` — for genuine one-shot scripts that intentionally skip the discipline (e.g., migration tooling). Logged via trace-helper.
+
+INSTEAD of overriding for routine work: honor the end-to-end commitment. The cost is small (one settings.json line, one install-class declaration, one Tier 0 test); the discipline compounds across every adopter inheritance.

package/dist/lite/.claude/rules/usability.md

@@ -0,0 +1,22 @@
+---
+tier: lite
+globs: ["src/app/**/page.tsx", "src/components/**/*.tsx", "**/*.css"]
+description: Usability check — loads only when touching UI files
+---
+
+Post-build gate for UI changes. Run before merge.
+
+1. Role check — sign in as least-privileged role (VIEWER/COLLABORATOR). No operator jargon visible.
+2. Scanning distance — no label...value patterns wider than ~150px. Use labels-above-values for financial data.
+3. Typography hierarchy — key numbers 14px+ bold, labels smaller + muted, no text <11px.
+4. Jargon & copy — no database enums (BIZBUYSELL → BizBuySell), externalized labels, multi-tenant ready.
+5. Attribution — show WHO performed actions, not just aggregate counts.
+6. Accessibility — 44px tap targets, 4.5:1 contrast, no translucent text backgrounds.
+7. Consistency — same badge treatment for same status everywhere.
+
+For significant UI changes: screenshot each surface and attach to PR.
+
+8. Visual verification — when Playwright MCP is available, screenshot the
+   page and verify programmatically: tap target sizes via DOM inspection,
+   contrast ratios, text sizes, badge consistency. Don't rely on code review
+   alone for visual correctness — see what the user sees.