@thebassclef/lite 1.1.1 → 1.2.0

package/dist/lite/.claude/skills/value-prop-canvas/SKILL.md

@@ -0,0 +1,297 @@
+---
+tier: lite
+name: value-prop-canvas
+description: "Produce a Strategyzer Value Proposition Canvas per persona \u2014 Customer Profile (Jobs/Pains/Gains) plus Value Map (Products/Pain-relievers/Gain-creators) plus fit-validation. The diagnostic lens over /personas."
+problem: "Value propositions get stated without persona anchoring. Jobs and pains and gains float free."
+value: "Strategyzer Value Proposition Canvas per persona. Customer profile plus value map."
+inputs: [Persona name from personas file]
+outputs: [Customer profile — Jobs plus Pains plus Gains, Value map, Fit gap]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# /value-prop-canvas — Strategyzer VPC
+
+Produce a Value Proposition Canvas (Strategyzer) per persona. Reads
+`/personas` output; emits one canvas per persona; validates fit — every
+Pain Reliever addresses a named Pain, every Gain Creator addresses a
+named Gain. Orphan entries (relievers/creators without a target)
+surface as validation failures.
+
+## Distinction from `/value-prop`
+
+Two adjacent but non-overlapping skills; both keep their slots.
+
+| Skill | Output shape | Purpose | When to use |
+|-------|-------------|---------|-------------|
+| `/value-prop` | Positioning statement (Moore) + 3 RTBs (Dunford Proof) | Compressed sales-ready framing | Decks, landing pages, pitch prep |
+| `/value-prop-canvas` | Two-sided canvas (Customer Profile + Value Map) per persona | Diagnostic mapping — do our relievers/creators actually address named pains/gains? | Before committing to positioning; during product shaping; validating fit |
+
+If you're trying to *say* something, `/value-prop`. If you're trying to
+*check* something, `/value-prop-canvas`. Most iterations benefit from
+running VPC first (to find the fit) then `/value-prop` (to phrase it).
+
+## Sources read
+
+- Alexander Osterwalder et al. — Strategyzer *Value Proposition Design* (2014). Bassclef VPC source. https://www.strategyzer.com/library/the-value-proposition-canvas
+- IxDF — *Value Proposition Canvas* overview. https://ixdf.org/literature/topics/value-proposition-canvas
+- IxDF + Medium — *JTBD + VPC relationship* (Customer Jobs connection). https://medium.com/@pminanutshell/npd-phase-1-5-introducing-value-proposition-canvas-jobs-to-be-done-f5036ea6ff9
+- `.claude/skills/personas/SKILL.md` — upstream read contract (file-system convention `docs/personas/*.md`)
+- `standards/persona-schema.md` — persona shape this skill reads
+- `standards/vpc-fit-validation.md` — companion standard (this skill's Stack-2 artifact) codifying the fit rules
+- `templates/value-prop-canvas.md` — bassclef template (this skill's Stack-2 artifact)
+- `.claude/skills/value-prop/SKILL.md` — adjacent skill; cross-linked in output but not reshaped
+- `.claude/skills/jtbd-tasks/SKILL.md` — JTBD feeds Customer Jobs (functional jobs especially)
+
+## What I'm NOT reading
+
+- `/lean-canvas` or `/business-model-canvas` — those are broader strategic canvases at the organization level; VPC is product-market-fit specific. If a consumer wants lean canvas or BMC, those are separate skills for future promotion
+- Cross-persona aggregation (one VPC for "all customers") — explicitly out of scope per ticket; VPC is 1:1 with persona
+
+## When to invoke
+
+- After `/personas` has produced at least one persona file (operator-default counts but produces a thin canvas — warn surfaced)
+- During Elaboration or early Construction when fit between product decisions and customer needs is still being settled
+- Before `/value-prop` if positioning feels ungrounded — VPC produces the evidence `/value-prop` needs
+- When a `/risk-test-synthetic` matrix (future promotion) needs per-persona fit signal
+
+## Usage
+
+```
+/value-prop-canvas                      → produce VPC for every persona in the repo
+/value-prop-canvas [slug]               → VPC for one persona
+/value-prop-canvas validate             → re-check fit on existing canvases at docs/value-prop-canvas/
+```
+
+## Procedure
+
+### Step 1: Load personas
+
+Read personas via the `/personas` contract:
+
+1. Check `docs/personas/*.md` (preferred)
+2. Check `docs/design/personas/*.md` (legacy)
+3. If neither has files → emit operator-default warning and halt with:
+   "No personas found. Run `/personas default` to see the fallback, or
+   create real persona files in `docs/personas/` before producing VPC."
+
+For a specific slug (`/value-prop-canvas couple-founders`), load only
+that file. For the default invocation, enumerate all.
+
+### Step 2: Extract Customer Profile signals
+
+For each persona, derive the three Customer Profile quadrants from its
+content:
+
+| VPC field | Persona source |
+|-----------|---------------|
+| **Customer Jobs** | Persona's `goal`, `tasks`, JTBD statements (if present), workflow descriptions. Split into functional / social / emotional |
+| **Pains** | Persona's "Pain points" section (with evidence traces). Each pain is a named Pain with severity signal if traceable |
+| **Gains** | Persona's "Motivators" section + "What would make them switch" + implicit gains inferable from pain inversions |
+
+**Do not invent.** If the persona doesn't have the data, the VPC
+quadrant stays thin and surfaces as WARN in fit-validation. Inventing
+entries produces false-positive fit signals downstream — the whole
+point of VPC is that the fit must be defensible.
+
+### Step 3: Build Value Map
+
+For the product / iteration / feature being reasoned about:
+
+| VPC field | Source |
+|-----------|--------|
+| **Products / Services** | What we ship — features, capabilities, affordances |
+| **Pain Relievers** | Specific product behaviors that address specific Pains |
+| **Gain Creators** | Specific product behaviors that produce specific Gains |
+
+Each Pain Reliever is annotated with the Pain it addresses (by Pain ID
+from Step 2). Each Gain Creator is annotated with the Gain.
+
+Example format:
+
+```markdown
+## Pain Relievers
+
+### PR1 — Shared context digest
+**Addresses:** P1 (Duplicate context rebuilding), P3 ("What did AI say
+about X?" side-channel)
+Description: auto-digest of both partners' AI conversations into a
+shared daily read.
+
+### PR2 — Per-member session continuity
+**Addresses:** P2 (Account-sharing workaround) — each member has their
+own memory, shared context is opt-in not default.
+```
+
+### Step 4: Fit validation
+
+Walk every Pain Reliever and Gain Creator. Check:
+
+- [ ] Each Pain Reliever names ≥1 Pain it addresses (by ID or exact label)
+- [ ] Each Gain Creator names ≥1 Gain it produces (by ID or exact label)
+- [ ] No Pain has zero Relievers (WARN — unaddressed Pain is a scope signal, not a fit failure per se)
+- [ ] No Gain has zero Creators (WARN — same)
+
+**Orphan entries fail validation.** A Pain Reliever without a named
+Pain is either (a) a feature looking for a problem, or (b) addressing
+a pain that should be named but isn't yet. Both are signals — write
+them down in the canvas's "Orphans surfaced" section with operator-
+facing next steps ("Add P6: [inferred pain], or drop PR3 from the
+value map").
+
+Unaddressed Pains/Gains (coverage gaps) are WARN, not FAIL — they
+might be deliberately out of scope, and the canvas surfaces them for
+operator decision rather than blocking.
+
+### Step 5: Emit canvas
+
+Write to `docs/value-prop-canvas/{persona-slug}.md`. One file per
+persona. Never merge multiple personas into one canvas.
+
+Template: `templates/value-prop-canvas.md`. Structure:
+
+```markdown
+# Value Proposition Canvas — [Persona Name]
+
+**Persona:** [slug] ([path to persona file])
+**Iteration / feature:** [goal path or feature name]
+**Generated:** [YYYY-MM-DD]
+**Fit validation:** PASS | WARN (coverage gaps) | FAIL (orphans)
+
+## Customer Profile
+
+### Customer Jobs
+- [J1] Functional: [label] — [one line]
+- [J2] Social: [label] — [one line]
+- [J3] Emotional: [label] — [one line]
+
+### Pains
+- [P1] [label] — [one line; source-trace if present in persona]
+- [P2] ...
+
+### Gains
+- [G1] [label] — [one line]
+- [G2] ...
+
+## Value Map
+
+### Products / Services
+- [Feature A]
+- [Feature B]
+
+### Pain Relievers
+- [PR1] [label] — addresses: [Pain IDs]. Description.
+- [PR2] ...
+
+### Gain Creators
+- [GC1] [label] — produces: [Gain IDs]. Description.
+- [GC2] ...
+
+## Fit summary
+
+| Element | Count | Addressed | Unaddressed |
+|---------|-------|-----------|-------------|
+| Pains | N | M | K |
+| Gains | N | M | K |
+
+## Orphans surfaced
+
+[Each orphan: the entry, why it has no target, operator decision needed]
+
+## Notes
+[Optional: edge cases, deferred decisions, open questions]
+```
+
+### Step 6: Output summary
+
+Print a compact summary to the conversation:
+
+```markdown
+## VPC produced: [N] canvases
+
+| Persona | Status | Orphans | Coverage gaps |
+|---------|--------|---------|---------------|
+| couple-founders | PASS | 0 | 1 gain unaddressed |
+| cofounder-pair | WARN | 0 | 2 pains unaddressed |
+| operator-advisor | FAIL | 1 orphan PR | — |
+```
+
+## Worked example — inline fit-validation demo
+
+To make the fit rule concrete, here's a deliberate orphan that
+validation should catch:
+
+**Persona P1 (hypothetical):** "cofounder-pair" — two technical
+co-founders frustrated by ChatGPT Business gaps.
+
+**Pains:**
+- P1: Chat history siloed between accounts
+- P2: Can't share project context with teammates
+- P3: Monthly cost scales badly (2 seats = $50/mo)
+
+**Pain Relievers drafted:**
+- PR1: Shared workspace with cross-account memory → **addresses P1, P2**
+- PR2: Per-project billing pool → **addresses P3**
+- PR3: AI-powered meeting notes → **addresses — (no Pain named)**
+
+Running fit-validation catches PR3: orphan. Either a P4 ("meeting
+context lost between sessions") should be added, or PR3 should drop
+from the Value Map. Operator decides. `/value-prop-canvas validate`
+fails this canvas until the orphan resolves.
+
+Without the explicit Pain-addressing rule, PR3 would sneak into the
+value map as a feature-looking-for-a-problem. Classic failure mode.
+
+## Common pitfalls
+
+- **Inventing customer jobs** — VPC Customer Profile MUST derive from the persona. If the persona doesn't have the job, the job isn't there yet. Fix by enriching the persona (via research), not by padding the VPC.
+- **"General" VPC** — one canvas that covers "all customers" destroys the fit signal. If you have three personas, you have three canvases. Compressing them hides which fit is strong and which is weak.
+- **Aspirational Pain Relievers** — "We'll solve X better than anyone" is not a reliever. Relievers are specific product behaviors tied to specific pains.
+- **Pattern-matching Gains from Pains (lazy inversion)** — "Pain: context lost" → "Gain: context preserved" is a low-value inversion. Real gains are desired outcomes the customer would articulate independently — often motivational rather than problem-solving.
+- **Skipping fit validation** — emitting a canvas without running the fit walk defeats the entire point. `/value-prop-canvas validate` MUST run before any canvas is considered complete.
+
+## Relationship to other skills
+
+| Skill | Relationship |
+|-------|-------------|
+| `/personas` | Upstream read. This skill halts without personas. |
+| `/value-prop` | Sibling. VPC is diagnostic (check fit); `/value-prop` is generative (compose positioning). Run VPC first, then `/value-prop`. |
+| `/jtbd-tasks` | JTBD statements → Customer Jobs (especially functional jobs) |
+| `/risk-test-synthetic` | Reads VPC per persona to build risk × persona × artifact matrix |
+| `/user-stories` | Pain Relievers + Gain Creators inform the `<benefit>` clause in INVEST stories |
+| `/spec` | VPC Value Map maps to spec "success criteria" |
+| `/riff-prototypes` | VPC fit-validation per variant surfaces which variant addresses the most pains — selection input |
+
+## Chain position
+
+```
+/personas (WHO)
+    ↓
+/jtbd-tasks (WHY — what they're hiring for)
+    ↓
+/value-prop-canvas (WHAT TO SAY / HOW TO HELP)   ← this skill
+    ↓
+/value-prop (COMPRESSED POSITIONING — uses VPC as evidence)
+    ↓
+/user-stories (HOW WE BUILD IT — INVEST)
+    ↓
+/ia-model + /interaction-design (HOW IT RENDERS)
+    ↓
+/decompose + /spec (HOW IT IMPLEMENTS)
+```
+
+## Provenance & evolution
+
+- Drafted in an operator project during user-centric chain shaping
+- Promoted to bassclef via issue #201
+- Stack-2 of iteration `docs/iteration-bets/2026-04-19e-persona-vpc-promotions.md` (Stack-1 shipped `/personas`)
+
+Future promotions in the same family (separate goals):
+- `/user-stories` — downstream consumer
+- `/risk-test-synthetic` — downstream consumer
+- `/psychographic-mine` — upstream persona generator
+- `/auto-user-research` — persona generator pipeline
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.

package/dist/lite/README.md

@@ -11,7 +11,11 @@ description: A shared substrate for working with AI coding agents.
 >
 > Then read the rest of this README as background. About 10 minutes total.
 
-**A shared substrate for working with AI coding agents.** Install it once into your repo, and every Claude Code session starts loaded: 76 skills, 53 rules, 16 agents, 32 practitioner profiles, 27 hooks, 67 standards, and 27 ADRs that wire them together. The agent reads your rules, knows the catalog, handles failure cleanly, and ships with discipline. You stop re-explaining your conventions every session — the difference between an assistant you brief and a band that already knows the set.
+**A shared substrate for working with AI coding agents.** Install it once into your repo, and every Claude Code session starts loaded: skills you invoke, rules the agent reads, specialist agents you dispatch, practitioner profiles it designs against, hooks that catch mistakes, plus the standards and decision records that wire them together.
+
+Run `/skills` or `/luminary` in any session to see exactly what your install carries. The counts differ by tier, so this README does not print them.
+
+The agent reads your rules, knows the catalog, handles failure cleanly, and ships with discipline. You stop re-explaining your conventions every session — the difference between an assistant you brief and a band that already knows the set.
 
 It is not a product. It is not a SaaS. It's a public framework, Apache 2.0: clone the repo, run the install script, own your stack.
 

package/dist/lite/gitignore

@@ -56,3 +56,9 @@ substrate.secrets.md
 
 # Adopter-specific ignores below
 # <adopter-content-below>
+
+# Bassclef synced substrate — vendored via `bassclef init` + `bassclef sync`.
+# Ignore by default so `git add -A` does not sweep hundreds of files.
+# Adopters who want to pin substrate: remove these lines OR add `!path/to/track`.
+.claude/
+.bassclef/

package/dist/lite/lib/bassclef-dir-resolver.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+# tier: lite
+#
+# bassclef-dir-resolver.sh — resolve BASSCLEF_DIR across install layouts.
+# Cures sunj-labs/bassclef-cli#105 root cause where session-reflection.sh:43
+# derived BASSCLEF_DIR by walking up two levels from the dispatcher's own
+# path, resolving to $HOME under operator install (dispatcher is a real
+# file at $HOME/.claude/hooks/, not a symlink to a checkout).
+#
+# The resolver probes four paths in order per Chain-of-Responsibility:
+#   1. Peer-checkout — $CWD/../bassclef with sentinel file present
+#   2. $HOME/bassclef — tarball adopter path with sentinel file present
+#   3. Bundled path — walk up from $HOOK_REAL_PATH with sentinel present
+#   4. Fallback — $CWD (adopter repo); safer than $HOME because the files
+#      fragments want ship into the repo via bassclef init
+#
+# The sentinel file is presence/install/bassclef-hook-connect.sh. Every
+# probe requires it — an empty peer dir or empty $HOME/bassclef does NOT win.
+#
+# Silent contract: never crashes, never writes to stderr on the resolve path.
+# Consumers (13 fragments plus session-reflection.sh coordinator) treat the
+# result as authoritative.
+#
+# Anchor luminaries:
+#   @luminary john-ousterhout — deep module (narrow interface hides 4-path probe)
+#   @luminary linus-torvalds  — adopter contract (fallback preserves the case
+#                                where an adopter's checkout is not in a
+#                                well-known place)
+#   @luminary tony-hoare      — postcondition (returns an existing path OR $CWD;
+#                                never returns $HOME under operator install)
+#   @luminary michael-nygard  — stability pattern (silent-return; no crash path)
+#
+# Companion audible-fail helper: emit_missing_dep_notice — used by fragments
+# whose dependencies still cannot resolve after the coordinator sets
+# $BASSCLEF_DIR. Cures the two silent-fail fragments named in cli#105 body.
+
+# @pattern patterns/code/gof/chain-of-responsibility.md
+# Four probe paths in order; first hit wins; fallback covers the null case.
+resolve_bassclef_dir() {
+  local hook_path="${HOOK_REAL_PATH:-}"
+  local cwd="${CWD:-.}"
+  local home_dir="${HOME_OVERRIDE:-${HOME:-/nonexistent}}"
+  local sentinel="presence/install/bassclef-hook-connect.sh"
+
+  # 1. Peer-checkout — sibling bassclef dir next to $CWD
+  if [ -d "$cwd/../bassclef" ] && [ -f "$cwd/../bassclef/$sentinel" ]; then
+    ( cd "$cwd/../bassclef" 2>/dev/null && pwd ) && return 0
+  fi
+
+  # 2. $HOME/bassclef — tarball adopter path
+  if [ -d "$home_dir/bassclef" ] && [ -f "$home_dir/bassclef/$sentinel" ]; then
+    printf '%s\n' "$home_dir/bassclef" && return 0
+  fi
+
+  # 3. Bundled path — walk up two levels from dispatcher
+  if [ -n "$hook_path" ]; then
+    local candidate
+    candidate="$( cd "$(dirname "$hook_path")/../.." 2>/dev/null && pwd )" || candidate=""
+    if [ -n "$candidate" ] && [ -f "$candidate/$sentinel" ]; then
+      printf '%s\n' "$candidate" && return 0
+    fi
+  fi
+
+  # 4. Fallback — $CWD (adopter repo). Safer than $HOME because the files
+  #    fragments want (init manifest, presence/install/*) ship into the repo.
+  ( cd "$cwd" 2>/dev/null && pwd ) || printf '%s\n' "$cwd"
+  return 0
+}
+
+# emit_missing_dep_notice — companion audible-fail helper.
+# Fragments call this when their dependency still cannot resolve after
+# $BASSCLEF_DIR is set. Prints ONE plain line to stderr naming the
+# fragment and the expected path. Silent-safe — never crashes the caller.
+#
+# Usage: emit_missing_dep_notice <fragment-name> <expected-path>
+emit_missing_dep_notice() {
+  local fragment="${1:-unknown-fragment}"
+  local expected="${2:-<unknown-path>}"
+  printf '%s: skip — dependency not at %s. Sync bassclef or set BASSCLEF_DIR.\n' \
+    "$fragment" "$expected" >&2
+}
+
+# Export for consumers that source this lib.
+export -f resolve_bassclef_dir 2>/dev/null || true
+export -f emit_missing_dep_notice 2>/dev/null || true

package/dist/lite/lib/clone-failure-classifier.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+# tier: lite
+#
+# clone-failure-classifier.sh — classify a git clone failure by its stderr.
+# Cures sunj-labs/bassclef-cli#106 where bassclef-sync.sh printed
+# "set up GitHub auth" even when authentication was fine and the cause
+# was repo visibility (private repo, adopter cannot see it).
+#
+# Contract: takes git stderr as $1. Prints a multi-line message to stdout
+# naming the cause (auth / visibility / network / unknown) and a hint the
+# adopter can act on. Includes the raw stderr in the message. Exit 0.
+#
+# Anchor luminaries:
+#   @luminary donald-norman   — visibility of system status (adopter hears
+#                                the real cause, not a wrong guess)
+#   @luminary michael-nygard  — the case statement is a strategy per cause
+#                                class; each cause gets its own hint
+#   @luminary michael-feathers — 3 canonical error shapes fixture-tested
+
+# @pattern patterns/code/gof/strategy.md
+# One strategy per error shape; unknown falls through to verbatim passthrough.
+classify_clone_failure() {
+  local git_stderr="${1:-}"
+  local cause hint
+
+  case "$git_stderr" in
+    *"Authentication failed"*|*"could not read Username"*|*"Permission denied (publickey)"*)
+      cause="auth"
+      hint="Optional: set up GitHub auth to unlock full-tier sync — run: gh auth login"
+      ;;
+    *"Repository not found"*|*"repository "*"not found"*)
+      cause="visibility"
+      hint="Repository sunj-labs/bassclef may be private and your account cannot see it. Confirm access or continue on lite tier only."
+      ;;
+    *"Could not resolve host"*|*"Connection timed out"*|*"Failed to connect"*)
+      cause="network"
+      hint="Network unavailable. Lite tier works without it."
+      ;;
+    *)
+      cause="unknown"
+      hint="Unknown git failure. See the raw error above."
+      ;;
+  esac
+
+  cat <<MSG
+### Bassclef sync — full-tier not synced (${cause})
+
+Git said:
+${git_stderr}
+
+${hint}
+
+Lite tier works without it — your session is fine.
+Skills / rules / agents beyond lite become available once sync succeeds.
+MSG
+  return 0
+}
+
+export -f classify_clone_failure 2>/dev/null || true

package/dist/lite/lib/fixture-builder.sh

@@ -0,0 +1,190 @@
+#!/usr/bin/env bash
+# tier: lite
+# Deep module for adopter-environment fixtures used by bassclef Tier 0 tests.
+# Per ADR-038 (adopter testing harness redesign) + R5 amendment to bet 30a
+# (@luminary john-ousterhout deep modules — the 5 fixture builders are thin
+# orchestrators on top of this library).
+#
+# Public API (functions tests source + call):
+#   fixture_init(name, tmproot)            → echo path; returns 0
+#   fixture_cleanup(path)                  → safe rm; refuses paths without sentinel
+#   fixture_cleanup_all()                  → cleanup every fixture this process created
+#   fixture_setup_substrate_sibling(fixture_dir, substrate_name)
+#   fixture_inject_pre_rename_refs(adopter_dir, canonical_substrate_dir)
+#
+# Override: SKIP_FIXTURE_BUILDER=1 — every public function exits 0 silently
+#                                    (fixture_init echoes empty path).
+# Logged via trace-helper per bassclef hook idiom.
+#
+# Per .claude/rules/defensive-bash.md — strict mode, quoted vars, local-safe,
+# trap-safe (composes with caller's trap via fixture_cleanup_all).
+
+set -u
+
+# Sentinel filename written into every fixture root by fixture_init.
+# fixture_cleanup refuses to remove a path that lacks this file — safe by default.
+# Prefixed underscore is convention for "do not depend on this name from outside"
+# but the symbol stays in scope so functions can reference it. The test for
+# global-var pollution (T14) checks specifically for `FIXTURE_TMP_INTERNAL` which
+# this lib never declares.
+_FIXTURE_SENTINEL=".fixture-builder-marker"
+
+# Track every fixture created in this shell so fixture_cleanup_all sweeps them.
+# Bash 3.2 compatible — newline-separated list of paths in one string.
+_FIXTURE_REGISTRY=""
+
+# -----------------------------------------------------------------------------
+# fixture_init <name> <tmproot>
+# Create a fresh fixture dir under tmproot, write the sentinel, register the
+# path, and echo it to stdout.
+# Override SKIP_FIXTURE_BUILDER=1 — echo nothing, return 0.
+# -----------------------------------------------------------------------------
+fixture_init() {
+  if [ "${SKIP_FIXTURE_BUILDER:-0}" = "1" ]; then
+    return 0
+  fi
+  local name="${1:?fixture_init requires name}"
+  local tmproot="${2:?fixture_init requires tmproot}"
+  if [ ! -d "$tmproot" ]; then
+    echo "fixture_init: tmproot does not exist: $tmproot" >&2
+    return 1
+  fi
+  local d
+  d=$(mktemp -d "$tmproot/${name}.XXXXXX")
+  touch "$d/$_FIXTURE_SENTINEL"
+  _FIXTURE_REGISTRY="${_FIXTURE_REGISTRY}${d}
+"
+  echo "$d"
+}
+
+# -----------------------------------------------------------------------------
+# fixture_cleanup <path>
+# Remove the fixture dir. Refuses unless the sentinel file is present at the
+# path — prevents accidental rm of system dirs even when caller passes
+# an unexpected argument.
+# Idempotent — missing dirs return 0 silently.
+# -----------------------------------------------------------------------------
+fixture_cleanup() {
+  if [ "${SKIP_FIXTURE_BUILDER:-0}" = "1" ]; then
+    return 0
+  fi
+  local path="${1:?fixture_cleanup requires path}"
+  if [ ! -e "$path" ]; then
+    # Idempotent — nothing to do
+    return 0
+  fi
+  if [ ! -f "$path/$_FIXTURE_SENTINEL" ]; then
+    echo "fixture_cleanup: refusing to remove path without sentinel: $path" >&2
+    return 1
+  fi
+  rm -rf "$path"
+  return 0
+}
+
+# -----------------------------------------------------------------------------
+# fixture_cleanup_all
+# Sweep every fixture this shell created. Caller wires this into their trap:
+#   trap fixture_cleanup_all EXIT
+# -----------------------------------------------------------------------------
+fixture_cleanup_all() {
+  if [ "${SKIP_FIXTURE_BUILDER:-0}" = "1" ]; then
+    return 0
+  fi
+  local IFS=$'\n'
+  local path
+  for path in $_FIXTURE_REGISTRY; do
+    [ -n "$path" ] || continue
+    fixture_cleanup "$path" 2>/dev/null || true
+  done
+  _FIXTURE_REGISTRY=""
+}
+
+# -----------------------------------------------------------------------------
+# fixture_setup_substrate_sibling <fixture_dir> <substrate_name>
+# Create the .claude tree under <fixture_dir>/<substrate_name>/, stocked with
+# stub hook files that adopter symlinks point into. Used by every fixture
+# that needs a sibling-substrate layout.
+# -----------------------------------------------------------------------------
+fixture_setup_substrate_sibling() {
+  if [ "${SKIP_FIXTURE_BUILDER:-0}" = "1" ]; then
+    return 0
+  fi
+  local fixture_dir="${1:?fixture_setup_substrate_sibling requires fixture_dir}"
+  local substrate_name="${2:?fixture_setup_substrate_sibling requires substrate_name}"
+  local substrate="$fixture_dir/$substrate_name"
+  mkdir -p "$substrate/.claude/hooks"
+  mkdir -p "$substrate/.claude/skills"
+  mkdir -p "$substrate/.claude/rules"
+  mkdir -p "$substrate/.claude/agents"
+  mkdir -p "$substrate/scripts"
+  # Stock the substrate with the hook files the existing tests reference
+  local hook
+  for hook in pre-commit-gate.sh type-check.sh artifact-ingestion-gate.sh bassclef-sync.sh; do
+    cat > "$substrate/.claude/hooks/$hook" <<EOF
+#!/bin/bash
+# Stub hook for fixture testing — emits no-op exit 0
+exit 0
+EOF
+    chmod +x "$substrate/.claude/hooks/$hook"
+  done
+  # Stock a representative script the migrate workflow references
+  cat > "$substrate/scripts/migrate-adopter-references.sh" <<'EOF'
+#!/bin/bash
+# Stub for fixture testing — emits no-op exit 0
+exit 0
+EOF
+  chmod +x "$substrate/scripts/migrate-adopter-references.sh"
+}
+
+# -----------------------------------------------------------------------------
+# fixture_inject_pre_rename_refs <adopter_dir> <canonical_substrate_dir>
+# Drop canonical-* references into an adopter setup — symlinks under
+# .claude/hooks/ pointing at the sibling canonical substrate, plus a
+# settings.json that references canonical paths. Simulates an adopter who
+# synced BEFORE the canonical → bassclef rename.
+#
+# No-op if adopter_dir does not exist (returns 0).
+# -----------------------------------------------------------------------------
+fixture_inject_pre_rename_refs() {
+  if [ "${SKIP_FIXTURE_BUILDER:-0}" = "1" ]; then
+    return 0
+  fi
+  local adopter_dir="${1:?fixture_inject_pre_rename_refs requires adopter_dir}"
+  local canonical_dir="${2:?fixture_inject_pre_rename_refs requires canonical_dir}"
+  if [ ! -d "$adopter_dir" ]; then
+    # Caller will see no side effects — adopter dir absent, nothing to do
+    return 0
+  fi
+  mkdir -p "$adopter_dir/.claude/hooks"
+  # Create canonical-targeted symlinks for each hook in the sibling
+  local hook
+  for hook in pre-commit-gate.sh type-check.sh artifact-ingestion-gate.sh bassclef-sync.sh; do
+    # Symlink relative path so the fixture is portable; target uses "canonical"
+    # literal name so the fixture exposes pre-rename state.
+    ln -sf "../../canonical/.claude/hooks/$hook" "$adopter_dir/.claude/hooks/$hook" 2>/dev/null || true
+  done
+  # Drop a settings.json that references canonical hook paths (matches how an
+  # adopter who synced pre-rename would have wired things).
+  cat > "$adopter_dir/.claude/settings.json" <<'EOF'
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/pre-commit-gate.sh" }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          { "type": "command", "command": "bash ../canonical/.claude/hooks/bassclef-sync.sh" }
+        ]
+      }
+    ]
+  }
+}
+EOF
+  return 0
+}