@thebassclef/lite 0.0.1 → 0.1.0

package/substrate/.claude/skills/onboard-repo/SKILL.md

@@ -0,0 +1,2190 @@
+---
+tier: lite
+name: onboard-repo
+description: "Bootstrap bassclef framework in a new repo. Installs sync hook + scaffolds config + whereami + CLAUDE.md. Modes: default / --with-deploy-host / --with-secrets / --full / --greenfield-from-intent (cold-adopter magic demo from a paragraph — uses /launch --local)."
+problem: "Setting up bassclef in a new repo takes an hour of trial. Missing directories and wrong hook wiring."
+value: "One command bootstraps everything \u2014 sync hook and config file and whereami scaffold."
+inputs: [Optional flags — --with-deploy-host or --with-secrets or --full]
+outputs: [Installed bassclef-sync hook, Config scaffold, Whereami stub]
+user_invocable: true
+disable_model_invocation: false
+requires:
+  cli: [git, gh]
+  network: true
+modes: [default, --with-deploy-host, --with-secrets, --full, --greenfield-from-intent]
+---
+
+# /onboard-repo — bassclef substrate adoption for a new repo
+
+Brings a repo from "zero bassclef wiring" to "inherits full substrate
+on desktop + mobile" in a single operator-gated session. Distinct from:
+
+- `scripts/boot-bassclef.sh` — **machine-level** one-time setup (gh
+  auth, service account, launchd). Run once per machine.
+- `/autonomous start` — **session-level** scaffolding (iteration goal,
+  phase state, risk register) for a repo that's ALREADY wired into
+  bassclef.
+
+This skill sits between them: it's **repo-level** substrate adoption.
+Run once per new consumer repo.
+
+## When to invoke
+
+- Adding a new repo that will use bassclef
+- Re-onboarding a repo that pre-dates the bassclef substrate
+- Refreshing substrate wiring in an existing consumer (idempotent)
+
+## Prerequisites (fail fast if missing)
+
+Different prereqs apply to Path A (standard onboarding) vs Path B
+(`--greenfield-from-intent` cold-adopter magic demo). Check the path
+the operator picked before validating.
+
+### Path A — standard onboarding
+
+- `gh` authenticated (`gh auth status`)
+- `claude` resolvable in PATH (`command -v claude`) — required for the
+  acceptance test at the end. If missing from a Zellij/tmux subpane,
+  move `eval "$(/opt/homebrew/bin/brew shellenv)"` from `~/.zprofile`
+  to `~/.zshenv` so non-login shells pick up homebrew's PATH.
+- Target repo exists on GitHub under your org
+- Target repo has a default branch (`main` preferred)
+- Bassclef is cloned as a peer at `$BASSCLEF_DIR` (default `~/src/<your-org>/bassclef`, for
+  desktop `additionalDirectories` resolution)
+- You are currently `cd`'d into the target repo's working directory
+- Claude Code session was started with `--add-dir ~/src/sunj-labs/bassclef`
+  so this skill file is accessible
+
+### Path B — `--greenfield-from-intent` (cold-adopter magic demo)
+
+- `claude` resolvable in PATH
+- `git` available
+- `python3` available (for the localhost gallery server)
+- `jq` available (JSON parsing for bassclef-sync + LLM-pick adapter)
+- `curl` available (bassclef-sync fallback + LLM-pick API calls)
+- No separate API key needed. The skill uses whichever LLM your Claude Code session provides. Per the tier reframe (bassclef-web#190 + #193), tier is about catalog size, not credentials.
+- You are currently `cd`'d into an **empty target directory** (or one
+  with only files Path B is allowed to overwrite — see "Working
+  directory convention" below)
+- `gh` is NOT required (no GitHub repo gets created)
+- A peer bassclef checkout at `~/src/sunj-labs/bassclef` is preferred
+  but not required (the thin-pointer dispatcher falls back to the
+  GitHub tarball when the sibling is absent — Path B's `Phase B.3`
+  installs it)
+
+### When prereqs are missing — operator menu
+
+If a prereq fails, surface it to the operator and present this menu
+verbatim before stopping:
+
+```
+Prerequisite missing for standard onboarding: <name of failed check>.
+
+Pick one:
+
+  1. Cold-adopter magic demo — runs /launch --local, no GitHub repo
+     created, no vendor accounts needed. Switches this dispatch to
+     --greenfield-from-intent (Path B below). No separate API key
+     needed — uses the LLM your Claude Code session provides.
+  2. Fix the prereq and re-run standard onboarding (Path A).
+  3. Cancel.
+```
+
+Operator picks `1` → continue under Path B. Picks `2` → stop and wait
+for the operator to fix + re-dispatch. Picks `3` → stop.
+
+Silence is not deferral. Wait for an explicit choice.
+
+## Working directory convention
+
+| Path | Working directory |
+|---|---|
+| Path A — Phases 1–3 | **target repo** (existing GitHub repo) |
+| Path A — Phase 4 | retired (see Phase 4 note below) |
+| Path B — all phases | **target directory** (typically empty; never leaves it) |
+
+For Path A the `pwd` check at the start of each phase exists for a
+reason — don't lose track. Path B runs entirely inside one directory
+and never reaches out to GitHub.
+
+## Procedure
+
+The Procedure branches at the top into **Path A** (standard
+onboarding) or **Path B** (`--greenfield-from-intent` cold-adopter
+magic demo). Decide first, then walk only the phases under the chosen
+path. Do not mix.
+
+### Choosing the path
+
+| Signal | Path |
+|---|---|
+| Operator dispatched `/onboard-repo --greenfield-from-intent ...` | B |
+| Operator picked option `1` from the prereqs-missing menu | B |
+| All Path A prereqs pass + no `--greenfield-from-intent` flag | A |
+| Operator dispatched `/onboard-repo --with-deploy-host` / `--with-secrets` / `--full` | A (with Phase 3.5 chained) |
+
+When in doubt, ask the operator which path; don't infer.
+
+---
+
+### Path B — `--greenfield-from-intent` (cold-adopter magic demo)
+
+**Working directory: empty.** Never leaves it. No GitHub repo. No vendor accounts touched. The path runs in ≤5 steps using the LLM your Claude Code session provides.
+
+The task list the agent generates for Path B MUST be exactly these
+five tasks, in this order. Do not add Phase 1 GitHub work, Phase 1.3
+prod environment, Phase 3.5 follow-on prompts, or Phase 4 matrix PRs.
+Those belong to Path A.
+
+#### Phase B.1 — Confirm intent
+
+Operator pastes a paragraph or voice transcript describing what they
+want to build (the recipe-test example: "a wiki app for sharing
+recipes with family"). Agent echoes the intent back and asks for
+operator confirmation before continuing. No edits hit disk yet.
+
+#### Phase B.2 — Init local git
+
+```bash
+git init
+git commit --allow-empty -m "chore: init repo"
+```
+
+First empty commit so subsequent file writes have a baseline.
+
+#### Phase B.3 — Scaffold the bassclef wiring
+
+Subset of Path A Phase 2 — only the files `/launch --local` actually
+reads. Skip everything that needs a remote.
+
+```bash
+mkdir -p .claude/hooks docs
+
+# Install the thin-pointer dispatcher (same source as Path A Phase 2.1).
+# Sibling-fast-path preferred; the curl fallback works for cold adopters.
+cp ~/src/sunj-labs/bassclef/presence/install/bassclef-sync.dispatcher.template.sh \
+   .claude/hooks/bassclef-sync.sh 2>/dev/null \
+   || curl -sL https://raw.githubusercontent.com/sunj-labs/bassclef/main/presence/install/bassclef-sync.dispatcher.template.sh \
+        -o .claude/hooks/bassclef-sync.sh
+chmod +x .claude/hooks/bassclef-sync.sh
+
+# Minimal settings.json — only the SessionStart hook
+cat > .claude/settings.json <<'JSON'
+{
+  "permissions": {
+    "additionalDirectories": ["../bassclef"]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/bassclef-sync.sh", "timeout": 30 }
+        ]
+      }
+    ]
+  }
+}
+JSON
+
+# Minimal substrate.config.md
+cat > substrate.config.md <<'MD'
+# substrate.config.md
+
+hosting_platform: none
+deploy_targets:
+  prod: false
+budget:
+  session_ceiling: $0
+  iteration_ceiling: $0
+MD
+
+# Minimal .claude/bassclef-configs.jsonc — adopter-default seed (bassclef#1135 WU-4)
+cat > .claude/bassclef-configs.jsonc <<'JSONC'
+// bassclef-configs.jsonc — unified adopter configuration discovery surface.
+// JSON Schema: standards/state-spine/schemas/bassclef-configs.schema.json
+{
+  "sync": { "enabled": false },
+  "model_tier": {
+    "Builder": "balanced",
+    "Closer": "cheap-fast",
+    "Deployer": "cheap-fast",
+    "DocsWriter": "cheap-fast",
+    "Explorer": "cheap-fast",
+    "Orchestrator": "cheap-fast",
+    "Reviewer": "cheap-fast",
+    "Shaper": "capable"
+  },
+  "plan_tier": "tier-1",
+  "prose_discipline": { "kiss_words_turn_prose": true },
+  "testing": { "global_floor": 1, "path_matchers": [] }
+}
+JSONC
+
+# Minimal CLAUDE.md — operator owns this going forward
+cat > CLAUDE.md <<'MD'
+# <repo-name>
+
+## What this repo is
+
+Cold-adopter magic demo from a stated intent. Substrate inherited from
+bassclef via `--add-dir ../bassclef` or thin-pointer fetch.
+
+## Stack
+
+To be determined by `/launch --local` output.
+MD
+```
+
+Skip in Path B:
+
+- `gh repo create` (no remote)
+- Phase 1.1 standard labels (no remote to apply them to)
+- Phase 1.2 branch protection (same)
+- Phase 1.3 prod environment (same)
+- `.bassclef-source.json` (only needed for cloud/mobile sessions
+  where the sibling sync isn't available; cold adopters running
+  locally don't need it for the magic demo)
+- Phase 3.5 interactive follow-on prompts (no `/provision-deploy-host`,
+  no `/secrets-bootstrap` — Path B has no vendor surfaces to bind)
+
+#### Phase B.4 — Dispatch `/launch --local --voice-input`
+
+Hand the intent paragraph straight to `/launch`:
+
+```
+/launch medium --local --voice-input "<intent paragraph from Phase B.1>"
+```
+
+Path B's last action is this dispatch. Do not chain `/build` or
+`/launch-preview` afterward — those belong to the extended path for
+operators with vendor bindings.
+
+#### Phase B.5 — `/launch --local` runs
+
+`/launch` writes the full artifact chain to disk (input-artifact, spec,
+prototypes gallery, user stories, decomposition, migration plan) and
+serves the gallery on `localhost:8000+`. The localhost URL is the
+deliverable. Operator inspects, picks a direction, and either keeps
+iterating locally or moves to standard onboarding (Path A) when they're
+ready to push to a GitHub repo.
+
+When `/launch --local` returns, Path B is done. Skip everything below
+this divider.
+
+---
+
+### Path A — standard onboarding
+
+Run each phase in order. Operator confirms before destructive or
+cross-repo actions. Each phase is independently re-runnable.
+
+#### Phase 0 — Refuse to run from main (bassclef#956 V0.5)
+
+Substrate changes go through PRs, same as feature work. If `/onboard-repo`
+runs from `main`, every scaffold (`.claude/`, `CLAUDE.md`,
+`docs/whereami.md`, `substrate.config.md`, `.bassclef-source.json`,
+`.gitignore`) lands as a direct-to-main commit by surprise. Path A
+refuses that shape and prints the remediation:
+
+```bash
+CURRENT_BRANCH=$(git branch --show-current 2>/dev/null || echo "")
+
+case "$CURRENT_BRANCH" in
+  main|master)
+    cat >&2 <<'EOF'
+
+🛑 /onboard-repo refuses to run from main.
+
+Why: substrate scaffolding (`.claude/`, `CLAUDE.md`, `docs/whereami.md`,
+`substrate.config.md`, `.bassclef-source.json`, `.gitignore`) is a
+substrate change — it goes through a PR, not a direct commit to main.
+
+Remediation:
+
+    git checkout -b chore/bassclef-bootstrap
+    # re-run /onboard-repo
+
+When you reach the end of Phase 3, /onboard-repo will guide you to
+open the bootstrap PR; merging it lands the substrate on main with
+audit history (this is flywheel turn 1 from the first-use sequence —
+see docs/first-use-sequence.md).
+
+V1 (bassclef#956 follow-up) will auto-create the branch + PR. V0.5
+keeps the operator in the loop on the branching decision.
+
+EOF
+    exit 1
+    ;;
+  "")
+    cat >&2 <<'EOF'
+
+🛑 /onboard-repo cannot detect the current git branch.
+
+The cwd may not be a git repository, OR git is in a detached-HEAD state.
+
+Remediation:
+
+    git init                                  # if not a git repo
+    git checkout -b chore/bassclef-bootstrap # from a fresh branch
+    # re-run /onboard-repo
+
+EOF
+    exit 1
+    ;;
+  *)
+    # Any other branch — proceed
+    ;;
+esac
+```
+
+The remediation message is the contract. If a cold adopter dispatches
+`/onboard-repo` from `main`, they see exactly what to do — no operator
+coaching, no second-guess. V0.5 ships in bassclef#956; V1
+(auto-create branch + PR) is post-launch hardening per the goal's
+operator-decision items.
+
+#### Phase 1 — Set up the GitHub repo (labels, branch protection)
+
+**Working directory: target repo** (`pwd` should match `gh repo view --json name -q .name`).
+
+Idempotent API calls against the target repo via `gh`.
+
+##### 1.1 Create the 11 standard labels
+
+```bash
+# Read from git remote — don't infer from cwd basename (cwd can be renamed)
+REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
+
+declare -A LABELS=(
+  [bassclef-evolution]="A6E0F2:Candidate for promotion to bassclef"
+  [agent-user-proposed]="D4A5F5:Proposed by agent in an app repo"
+  [bassclef-sync]="8FD4A4:Related to bassclef substrate syncing"
+  [review-required]="F5B94A:Blocks — human review required"
+  [bug]="E4443A:Defect"
+  [enhancement]="A2EEEF:New or improved functionality"
+  [security]="FF0000:Security-relevant"
+  [infra]="C9D1D9:Infrastructure / workflows / tooling"
+  [priority-high]="E4443A:High priority"
+  [priority-medium]="F5B94A:Medium priority"
+  [question]="D876E3:Needs operator input or design discussion"
+)
+
+for NAME in "${!LABELS[@]}"; do
+  COLOR="${LABELS[$NAME]%%:*}"
+  DESC="${LABELS[$NAME]#*:}"
+  gh label create "$NAME" --repo "$REPO" --color "$COLOR" --description "$DESC" --force >/dev/null
+done
+```
+
+Uses `--force` so the call is idempotent (updates existing label or
+creates new). This matches the bootstrap logic shipped in bassclef
+#160 (sync hook does the same for `bassclef-evolution` + `agent-user-proposed`);
+this phase adds the broader set up-front so the operator can label issues
+immediately without waiting for a sync cycle.
+
+##### 1.2 Protect main from force-push and deletion
+
+```bash
+DEFAULT_BRANCH=$(gh repo view "$REPO" --json defaultBranchRef -q '.defaultBranchRef.name')
+
+gh api "repos/$REPO/branches/$DEFAULT_BRANCH/protection" \
+  --method PUT \
+  --input - <<EOF
+{
+  "required_status_checks": null,
+  "enforce_admins": false,
+  "required_pull_request_reviews": null,
+  "restrictions": null,
+  "allow_force_pushes": false,
+  "allow_deletions": false
+}
+EOF
+```
+
+Minimum defense: no force-push or deletion of main. PR reviews NOT
+required here — agent-created PRs (bassclef-sync) need to merge
+without human intervention for the mobile-sync story. Add stricter
+rules per-repo in `.github/branch-protection.yml` if the repo warrants.
+
+##### 1.3 Add the production approval gate (if this repo deploys to prod)
+
+If the repo will deploy to production, per `manual-prod-approval.md`:
+
+```bash
+# Prompt operator: "Does this repo deploy to prod? [y/N]"
+# If yes:
+USER_ID=$(gh api user --jq '.id')
+gh api "repos/$REPO/environments/prod" --method PUT \
+  -f "wait_timer=0" \
+  -f "deployment_branch_policy[protected_branches]=false" \
+  -f "deployment_branch_policy[custom_branch_policies]=true"
+
+gh api "repos/$REPO/environments/prod" --method PUT \
+  -F "reviewers[][type]=User" \
+  -F "reviewers[][id]=$USER_ID"
+```
+
+Skip if repo is docs-only (like bassclef itself) or doesn't have a
+production deploy target.
+
+#### Phase 2 — Install bassclef wiring (settings, sync script, config)
+
+**Working directory: target repo.** All file writes happen here.
+
+##### 2.1 Install the auto-update script (off by default per bassclef#939)
+
+```bash
+mkdir -p .claude/hooks
+
+# Install thin-pointer dispatcher from bassclef's own template directory.
+# This is the source-of-truth file consumers vendor.
+cp ~/src/sunj-labs/bassclef/presence/install/bassclef-sync.dispatcher.template.sh \
+   .claude/hooks/bassclef-sync.sh
+
+# OR — if bassclef isn't checked out alongside this repo, fetch from
+# bassclef's main branch on GitHub (public tarball release works too
+# once bassclef itself goes public):
+# curl -sL https://raw.githubusercontent.com/sunj-labs/bassclef/main/presence/install/bassclef-sync.dispatcher.template.sh \
+#   -o .claude/hooks/bassclef-sync.sh
+
+chmod +x .claude/hooks/bassclef-sync.sh
+
+# Verify the version header reads `thin-pointer-2026-05-15` or later:
+head -2 .claude/hooks/bassclef-sync.sh
+```
+
+The thin-pointer dispatcher does NOT vendor bassclef's sync logic.
+It reads `.bassclef-source.json` (Phase 2.4) for the upstream tarball
+URL + auth, fetches it, and execs the included template — always-current.
+Eliminates two prior patching layers: hook content drift (vendored
+template diverging from bassclef's) and URL refresh ceremony.
+
+When the dispatcher can't load the substrate (sibling missing AND curl
+fallback unconfigured / unauthenticated), it prints a plain-language
+explanation with three resolution paths (public adopter, local dev,
+private fork). External adopters get actionable guidance instead of
+internal-vocabulary errors. Closes the adoption-friendliness gap noted
+in bassclef#715.
+
+##### 2.2 Configure Claude Code for this repo
+
+Standard bassclef settings — SessionStart → `bassclef-sync.sh`, +
+other hooks per-agent configuration. Copy from a reference consumer
+(POA or ops) and scrub for repo-specific paths:
+
+```bash
+cat > .claude/settings.json <<'JSON'
+{
+  "permissions": {
+    "additionalDirectories": ["../bassclef"]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/bassclef-sync.sh", "timeout": 30 }
+        ]
+      }
+    ]
+  }
+}
+JSON
+```
+
+Operator confirms — may want to add app-specific hooks (pre-build-gate,
+pre-commit-gate) if the repo has source code.
+
+##### 2.2.1 Wire turn-prose-kiss-check Stop hook (bassclef#1138 T5)
+
+Symlink the bassclef Stop hook that scans the most recent assistant
+message for bassclef-internal jargon (the `/kiss words` BLOCK list
+from `standards/bassclef-internal-jargon.md`). When
+`prose_discipline.kiss_words_turn_prose` is `true` in
+`.claude/bassclef-configs.jsonc` (the adopter-default Phase 2.3.5
+writes), the hook fires after every assistant turn and surfaces
+findings; when `false`, the hook short-circuits silently.
+
+Symlink the hook (bassclef lives one directory up per the
+`additionalDirectories` convention):
+
+```bash
+mkdir -p .claude/hooks
+ln -sf "../../../bassclef/.claude/hooks/turn-prose-kiss-check.sh" \
+       ".claude/hooks/turn-prose-kiss-check.sh"
+```
+
+Add the Stop hook block to `.claude/settings.json`. If the file already
+has a Stop block (for example, `session-end.sh`), append this hook
+alongside — both run, turn-prose-kiss-check first, session-end second:
+
+```jsonc
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/turn-prose-kiss-check.sh", "timeout": 10 }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Composition rule** — when an existing Stop hook is present, leave it
+in place and append this one. The turn-prose-kiss-check hook exits 0
+even when findings surface (default toggle: advisory), so a downstream
+session-end hook still runs. When the adopter opts in to strict mode
+(`prose_discipline.kiss_words_turn_prose: "strict"` in
+bassclef-configs.jsonc), the hook exits 2 and blocks the stop — that's
+the conscious-strict trade-off.
+
+**Conditional fire** — the hook reads
+`.claude/bassclef-configs.jsonc` `prose_discipline.kiss_words_turn_prose`
+at runtime and short-circuits when `false`. Adopters who never want the
+check can flip the toggle without unwiring the hook.
+
+**Verify the wiring:**
+
+```bash
+# Sanity: hook is executable + reachable
+ls -l .claude/hooks/turn-prose-kiss-check.sh
+
+# Sanity: settings.json parses
+python3 -c "import json; json.load(open('.claude/settings.json'))"
+```
+
+**Composes with downstream Phase 2.x steps:**
+
+- Phase 2.3.5 writes `prose_discipline.kiss_words_turn_prose: true` to
+  `.claude/bassclef-configs.jsonc` as the adopter default — this hook
+  fires when that toggle is true.
+- Phase 2.5 (security scanning) is a separate hook wiring path; both
+  hooks can co-exist in the Stop block.
+
+Source: bassclef#1051 (hook origin), bassclef#1138 (this wiring step).
+
+##### 2.2.2 Wire substrate-clarity-gate PreToolUse hook (bassclef#1137 T4)
+
+Symlink the bassclef PreToolUse hook that BLOCKs writes to
+`.claude/skills/`, `.claude/rules/`, and `.claude/luminaries/` when
+they violate the clarity discipline bassclef applies to its own
+substrate — skill descriptions over 280 chars, rule + luminary
+"NEVER" without paired "INSTEAD:" block, jargon usage where plain
+language exists. Adopter writes to substrate paths trigger the same
+gate bassclef does.
+
+Symlink the hook + the bassclef baseline allowlist (the file that
+grandfathers pre-existing violators during a grace window):
+
+```bash
+mkdir -p .claude/hooks
+ln -sf "../../../bassclef/.claude/hooks/substrate-clarity-gate.sh" \
+       ".claude/hooks/substrate-clarity-gate.sh"
+ln -sf "../../../bassclef/.claude/hooks/substrate-clarity-allowlist.txt" \
+       ".claude/hooks/substrate-clarity-allowlist.txt"
+```
+
+Add the PreToolUse Edit|Write block to `.claude/settings.json`. If an
+`Edit|Write` matcher already exists from a prior phase, append this
+hook to its `hooks` array instead of duplicating the matcher entry:
+
+```jsonc
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/substrate-clarity-gate.sh" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Adopter allowlist convention** — the symlinked
+`substrate-clarity-allowlist.txt` carries bassclef's baseline
+grandfather list (pre-existing violators with a documented grace
+window). When the adopter has their own pre-existing substrate
+violations they want to grandfather during their own migration,
+they create a sibling file:
+
+```bash
+touch .claude/hooks/substrate-clarity-allowlist-adopter.txt
+```
+
+The hook reads BOTH files in series — bassclef's baseline first,
+then the adopter-side append. Entries in the adopter file follow
+the same one-path-per-line format as bassclef's baseline. The
+adopter file is git-tracked in the adopter repo (not symlinked
+into bassclef), so each adopter manages their own grandfather
+list independently.
+
+**Composition rule** — when an existing PreToolUse Edit|Write
+matcher block is present (for example, `artifact-ingestion-gate.sh`
+from Phase 2.x), append this hook's command entry to the same
+matcher's `hooks` array. The matcher entry must not be duplicated;
+the array of hooks under one matcher can hold multiple commands
+that fire in series.
+
+**Override path** — adopter can bypass per-call with
+`SKIP_SUBSTRATE_CLARITY=1 <command>` (logged via trace-helper per
+bassclef override idiom). The override is for migration scripts
+and emergency rescue; routine use should fix the violation, not
+bypass.
+
+**Verify the wiring:**
+
+```bash
+# Sanity: hook executable + reachable
+ls -l .claude/hooks/substrate-clarity-gate.sh
+ls -l .claude/hooks/substrate-clarity-allowlist.txt
+
+# Sanity: settings.json parses + has the matcher
+python3 -c "import json; d=json.load(open('.claude/settings.json')); \
+  print('substrate-clarity-gate wired' if any( \
+    'substrate-clarity-gate' in h.get('command','') \
+    for entry in d.get('hooks',{}).get('PreToolUse',[]) \
+    for h in entry.get('hooks',[])) else 'NOT wired')"
+```
+
+Source: bassclef#382 (hook origin), bassclef#1137 (this wiring step), bassclef#1135 (T2 config default — separate concern).
+
+##### 2.2.3 Wire artifact-ingestion-gate PreToolUse hook (bassclef#1140 T7)
+
+Symlink the bassclef PreToolUse hook that BLOCKs writes to adopter
+substantive artifacts (specs, decompositions, prototypes, ADRs,
+proposals, iteration goals) when the artifact body lacks a
+`## Sources read` section. The discipline catches the
+"pattern-matched on generic X" failure mode that
+`.claude/rules/artifact-ingestion.md` was built to close — applied at
+adopter writes, not just at bassclef's own writes.
+
+Symlink the hook:
+
+```bash
+mkdir -p .claude/hooks
+ln -sf "../../../bassclef/.claude/hooks/artifact-ingestion-gate.sh" \
+       ".claude/hooks/artifact-ingestion-gate.sh"
+```
+
+Add the PreToolUse Write block to `.claude/settings.json`. The hook
+matches on `Write` (not `Edit`) — edits to existing artifacts pass
+through; only new artifact writes trigger the gate. If a Write
+matcher already exists from a prior phase, append this hook to its
+`hooks` array:
+
+```jsonc
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/artifact-ingestion-gate.sh" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Adopter-default path matchers** — the hook reads
+`.claude/bassclef-configs.jsonc` `artifact_ingestion.paths` to
+decide which paths fire the gate. Phase 2.3.5 (bassclef-configs
+adopter-default seed) appends this block with the bassclef default
+list. Adopters edit the list per repo — adding paths their substrate
+considers substantive, or removing paths that do not apply:
+
+```jsonc
+"artifact_ingestion": {
+  "paths": [
+    "docs/specs/**/*.md",
+    "docs/decompositions/**/*.md",
+    "docs/prototypes/**/*.html",
+    "docs/proposals/**/*.md",
+    "docs/adrs/**/*.md",
+    "docs/use-cases/**/*.md",
+    "docs/user-stories/**/*.md",
+    "docs/ia-models/**/*.md",
+    "docs/interaction-design/**/*",
+    "docs/personas/**/*.md",
+    "docs/jtbd-tasks/**/*.md",
+    "docs/value-props/**/*.md",
+    "docs/iteration-bets/**/*.md"
+  ]
+}
+```
+
+When the `artifact_ingestion.paths` field is absent (older adopters
+predating this Phase), the hook falls back to its built-in default
+matcher list — the wiring stays safe and quiet.
+
+**Composition rule** — when an existing PreToolUse Write matcher is
+present (for example, from a sibling hook in another Phase 2.x step),
+append this hook's command entry to the same matcher's `hooks` array.
+The matcher entry must not be duplicated.
+
+**Override path** — adopter can bypass per-call with
+`SKIP_ARTIFACT_INGESTION=1 <command>` (logged via trace-helper). Use
+for migration scripts and emergency rescue.
+
+**Verify the wiring:**
+
+```bash
+# Sanity: hook executable + reachable
+ls -l .claude/hooks/artifact-ingestion-gate.sh
+
+# Sanity: settings.json has the matcher
+python3 -c "import json; d=json.load(open('.claude/settings.json')); \
+  print('artifact-ingestion-gate wired' if any( \
+    'artifact-ingestion-gate' in h.get('command','') \
+    for entry in d.get('hooks',{}).get('PreToolUse',[]) \
+    for h in entry.get('hooks',[])) else 'NOT wired')"
+```
+
+Source: bassclef#116 (hook origin), bassclef#1140 (this wiring step).
+
+##### 2.2.4 Wire pattern-annotation-validate PreToolUse hook (bassclef#1139 T6)
+
+**Lite adopter note (bassclef#740 Task 1.2).** This hook ships at `tier: standard`. If your adopter tier is lite (resolved via `lib/tier-check.sh`), skip this Phase step and continue with 2.2.5. The bassclef-lite tarball does not carry this hook.
+
+Symlink the bassclef PreToolUse hook that validates `@pattern <catalog-path>` annotations in adopter source code. Layer 3 of bassclef#478 traceability — code that instantiates a named pattern from bassclef's catalog (`patterns/<shelf>/<source>/<slug>.md`) must mark itself with the annotation so forward (which code uses this pattern) and reverse (which patterns is this code using) lookups work across the adopter portfolio.
+
+Symlink the hook:
+
+```bash
+mkdir -p .claude/hooks
+ln -sf "../../../bassclef/.claude/hooks/pattern-annotation-validate.sh" \
+       ".claude/hooks/pattern-annotation-validate.sh"
+```
+
+Add the PreToolUse Edit|Write|MultiEdit block to `.claude/settings.json`. If an `Edit|Write` matcher already exists from a prior phase, append this hook to its `hooks` array (the bassclef settings.json convention is to widen matchers when adding new hooks that share a tool set):
+
+```jsonc
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/pattern-annotation-validate.sh" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Rule propagation** — the `pattern-annotation` rule lives at bassclef's `.claude/rules/pattern-annotation.md` and loads into adopter agent context via the `additionalDirectories: ["../bassclef"]` entry Phase 2.2 wrote. No copy needed; bassclef's rule body is the source of truth.
+
+**Tech-stack-aware scoping** — the hook reads adopter's `.claude/bassclef-configs.jsonc` `tech_stack.lang` (Phase 2.3.6 writes) and fires only on source files matching the declared language: `.ts/.tsx` for `typescript`, `.py` for `python`, `.rb` for `ruby`, `.go` for `go`, `.rs` for `rust`. Non-source files silent. When `tech_stack.lang` is absent (older adopters or skip path), the hook fires on the union of language matchers (safe default).
+
+**Composition rule** — when an existing PreToolUse Edit|Write matcher block is present (substrate-clarity-gate from 2.2.2 uses `Edit|Write`), the matcher set widens to `Edit|Write|MultiEdit` to cover both hooks. Adopters can keep the matchers separate if they prefer narrower scoping per hook.
+
+**Override path** — `SKIP_PATTERN_ANNOTATION=1 <command>` (logged via trace-helper). Use for migration scripts when annotating retroactively is in flight.
+
+**Verify the wiring:**
+
+```bash
+# Sanity: hook executable + reachable
+ls -l .claude/hooks/pattern-annotation-validate.sh
+
+# Sanity: rule loads via additionalDirectories
+test -f ../bassclef/.claude/rules/pattern-annotation.md && echo "rule reachable" || echo "rule NOT reachable"
+
+# Sanity: settings.json has the matcher
+python3 -c "import json; d=json.load(open('.claude/settings.json')); \
+  print('pattern-annotation-validate wired' if any( \
+    'pattern-annotation-validate' in h.get('command','') \
+    for entry in d.get('hooks',{}).get('PreToolUse',[]) \
+    for h in entry.get('hooks',[])) else 'NOT wired')"
+```
+
+Source: bassclef#478 (parent traceability goal), bassclef#1139 (this wiring step), bassclef#1127 (tech_stack vocabulary the scoping reads).
+
+##### 2.2.5 Wire pre-commit-gate + state-validate PreToolUse hooks (bassclef#1136 T3)
+
+Symlink the two bassclef PreToolUse hooks that gate adopter writes.
+
+`pre-commit-gate.sh` runs the SDLC pre-build checks per `.claude/rules/sdlc-gates.md`. Those checks are temperance + diagnosis + scope drift.
+
+`state-validate.sh` validates state-spine entity writes against JSON Schema per `.claude/rules/state-schema-validation.md`.
+
+Together the hooks catch two failure classes before any source edit lands: skipped gates (silent SDLC bypass) and malformed state writes (silent schema drift).
+
+Symlink both hooks:
+
+```bash
+mkdir -p .claude/hooks
+ln -sf "../../../bassclef/.claude/hooks/pre-commit-gate.sh" \
+       ".claude/hooks/pre-commit-gate.sh"
+ln -sf "../../../bassclef/.claude/hooks/state-validate.sh" \
+       ".claude/hooks/state-validate.sh"
+```
+
+Add the PreToolUse Edit|Write|MultiEdit block to `.claude/settings.json`. If an `Edit|Write` or `Edit|Write|MultiEdit` matcher already exists from a prior phase (substrate-clarity-gate from 2.2.2, pattern-annotation-validate from 2.2.4), append both hooks to its `hooks` array — the matcher set widens to `Edit|Write|MultiEdit` when MultiEdit is not already covered:
+
+```jsonc
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/pre-commit-gate.sh" },
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/state-validate.sh" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Order matters** — `pre-commit-gate.sh` runs first (cheap SDLC checks), `state-validate.sh` runs second (heavier ajv-cli schema validation). The matcher block lists them in that order; a BLOCK from the first stops the chain before the second fires.
+
+**Rule propagation** — both rules (`sdlc-gates.md` + `state-schema-validation.md`) live at bassclef's `.claude/rules/` and load into adopter agent context via the `additionalDirectories: ["../bassclef"]` entry Phase 2.2 wrote. No copy needed; bassclef's rule body is the source of truth.
+
+**Composition rule** — when an existing PreToolUse Edit|Write matcher block is present from earlier Phase 2.x steps, append these two hooks to its `hooks` array (do not duplicate the matcher entry). Hook order within the array determines execution order; place `pre-commit-gate.sh` before `state-validate.sh` per the order rule above.
+
+**Override paths** — `SKIP_PRE_COMMIT_GATE=1 <command>` and `SKIP_STATE_VALIDATE=1 <command>` (both logged via trace-helper). Use only for one-shot migration scripts (state bootstrapping) or emergency rescue when the hook itself is broken.
+
+**Verify the wiring:**
+
+```bash
+# Sanity: both hooks executable + reachable
+ls -l .claude/hooks/pre-commit-gate.sh .claude/hooks/state-validate.sh
+
+# Sanity: both rules reachable via additionalDirectories
+test -f ../bassclef/.claude/rules/sdlc-gates.md && echo "sdlc-gates reachable" || echo "sdlc-gates NOT reachable"
+test -f ../bassclef/.claude/rules/state-schema-validation.md && echo "state-schema-validation reachable" || echo "state-schema-validation NOT reachable"
+
+# Sanity: settings.json has both hooks wired in matcher block
+python3 -c "import json; d=json.load(open('.claude/settings.json')); \
+  hooks=[h.get('command','') for entry in d.get('hooks',{}).get('PreToolUse',[]) for h in entry.get('hooks',[])]; \
+  print('pre-commit-gate wired' if any('pre-commit-gate' in c for c in hooks) else 'NOT wired'); \
+  print('state-validate wired' if any('state-validate' in c for c in hooks) else 'NOT wired')"
+```
+
+Source: bassclef#1136 (this wiring step — T3, iteration-2 BLOCKER). Sister rules: `.claude/rules/sdlc-gates.md` + `.claude/rules/state-schema-validation.md`.
+
+##### 2.2.6 Wire destructive-command-guard + multi-tenancy-check PreToolUse hooks (bassclef#1141 T8 — partial)
+
+**Lite adopter note (bassclef#740 Task 1.2).** Both hooks ship at `tier: standard`. Skip this step if your tier is lite. Resolve tier via `lib/tier-check.sh`. Continue with 2.2.7.
+
+Symlink two bassclef PreToolUse hooks that catch runtime-safety problems before they reach the operator's filesystem or database. `destructive-command-guard.sh` fires on Bash and detects destructive verbs + force flags + amplifiers (catches "prisma migrate reset", "rm -rf", "FLUSHALL" patterns). `multi-tenancy-check.sh` fires on Edit/Write of source files and warns when tenant-scoped patterns are missing (queries without tenant context).
+
+Bet 2026-06-18b scopes T8 to these two hooks; the ticket's other two (`operator-private-path-check.sh` + `type-check.sh`) are deferred to a follow-on per goal narrowing.
+
+Symlink both hooks:
+
+```bash
+mkdir -p .claude/hooks
+ln -sf "../../../bassclef/.claude/hooks/destructive-command-guard.sh" \
+       ".claude/hooks/destructive-command-guard.sh"
+ln -sf "../../../bassclef/.claude/hooks/multi-tenancy-check.sh" \
+       ".claude/hooks/multi-tenancy-check.sh"
+```
+
+Add both PreToolUse blocks to `.claude/settings.json`. The matchers differ — `destructive-command-guard` watches Bash; `multi-tenancy-check` watches Edit|Write|MultiEdit. The Edit|Write|MultiEdit block likely already exists from Phase 2.2.2 / 2.2.3 / 2.2.4 / 2.2.5 — append `multi-tenancy-check` to its `hooks` array (do not duplicate the matcher entry). The Bash block is new for most adopters; create it if absent.
+
+```jsonc
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/destructive-command-guard.sh" }
+        ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/multi-tenancy-check.sh" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Customization** — `multi-tenancy-check.sh` is a template. Adopters with multi-tenant codebases override `TENANT_MODELS` + `TENANT_CONTEXT_FN` + `TENANT_PARAMS_FN` via env vars OR drop a custom `multi-tenancy-check.sh` in `.claude/hooks/` (which wins over the symlink). Single-tenant adopters can disable per-call with `SKIP_MULTI_TENANCY_CHECK=1`.
+
+**Rule propagation** — `.claude/rules/destructive-operations.md` loads into adopter agent context via the `additionalDirectories: ["../bassclef"]` entry Phase 2.2 wrote. No copy needed.
+
+**Composition rule** — Bash and Edit|Write|MultiEdit matchers stay separate; never collapse them. When other Phase 2.x steps add Bash hooks (Phase 2.2.7 ships atomic-pr-check on Bash; type-check on Bash if T8 follow-on ships), append to the Bash matcher's `hooks` array — do not duplicate the matcher entry.
+
+**Override paths** — `SKIP_DESTRUCTIVE_GUARD=1 <command>` (logged) and `SKIP_MULTI_TENANCY_CHECK=1 <command>` (logged). Both bypass logged via trace-helper. Use only for genuine cases (one-shot migrations, single-tenant repos where the check is noise).
+
+**Verify the wiring:**
+
+```bash
+# Sanity: both hooks executable + reachable
+ls -l .claude/hooks/destructive-command-guard.sh .claude/hooks/multi-tenancy-check.sh
+
+# Sanity: destructive-operations rule reachable via additionalDirectories
+test -f ../bassclef/.claude/rules/destructive-operations.md && echo "destructive-operations reachable" || echo "NOT reachable"
+
+# Sanity: settings.json has both hooks wired with correct matchers
+python3 -c "import json; d=json.load(open('.claude/settings.json')); \
+  bash_hooks=[h.get('command','') for entry in d.get('hooks',{}).get('PreToolUse',[]) if entry.get('matcher')=='Bash' for h in entry.get('hooks',[])]; \
+  edit_hooks=[h.get('command','') for entry in d.get('hooks',{}).get('PreToolUse',[]) if 'Edit' in entry.get('matcher','') for h in entry.get('hooks',[])]; \
+  print('destructive-command-guard wired (Bash)' if any('destructive-command-guard' in c for c in bash_hooks) else 'NOT wired (Bash)'); \
+  print('multi-tenancy-check wired (Edit|Write|MultiEdit)' if any('multi-tenancy-check' in c for c in edit_hooks) else 'NOT wired (Edit|Write|MultiEdit)')"
+```
+
+Source: bassclef#1141 (this wiring step — T8, runtime-safety chain). Sister rule: `.claude/rules/destructive-operations.md`. Follow-on: `operator-private-path-check.sh` + `type-check.sh` wires deferred from T8 goal scope.
+
+##### 2.2.7 Wire atomic-pr-check + post-write-trace workflow hooks (bassclef#1142 T9)
+
+**Lite adopter note (bassclef#740 Task 1.2).** Both hooks ship at `tier: standard`. Skip this step if your tier is lite. Resolve tier via `lib/tier-check.sh`. Continue with the next step.
+
+Symlink two bassclef workflow hooks. `atomic-pr-check.sh` fires on Bash calls matching `git push` patterns and BLOCKs multi-step branches that lack `bundle: true` in the iteration goal's frontmatter — closes the silent atomic-PR-discipline gap that `.claude/rules/pr-strategy.md` describes. `post-write-trace.sh` fires on PostToolUse Write/Edit and records traceability rows so the agent can audit what wrote what.
+
+Symlink both hooks:
+
+```bash
+mkdir -p .claude/hooks
+ln -sf "../../../bassclef/.claude/hooks/atomic-pr-check.sh" \
+       ".claude/hooks/atomic-pr-check.sh"
+ln -sf "../../../bassclef/.claude/hooks/post-write-trace.sh" \
+       ".claude/hooks/post-write-trace.sh"
+```
+
+Add a PreToolUse Bash block + a PostToolUse Write|Edit block to `.claude/settings.json`. The Bash matcher likely already exists from Phase 2.2.6 (destructive-command-guard) — append `atomic-pr-check` to its `hooks` array. The PostToolUse block is new for most adopters.
+
+```jsonc
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/atomic-pr-check.sh" }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/post-write-trace.sh" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Bet narrowing** — ticket #1142 (T9) also lists `post-skill-friction-check.sh`. The goal scopes this step to two hooks; the third deferred to a follow-on per goal shape.
+
+**Composition rule** — when the Bash matcher already exists (Phase 2.2.6 wires destructive-command-guard on the same matcher), append `atomic-pr-check` to its `hooks` array; do not duplicate the matcher entry. Hook order within the Bash array does not matter for these two — destructive-command-guard and atomic-pr-check check different signals (destructive verbs vs git-push patterns) and never conflict on the same command.
+
+**Rule propagation** — `.claude/rules/pr-strategy.md` (the methodology atomic-pr-check enforces) loads via `additionalDirectories`. No copy needed.
+
+**Override paths** — `SKIP_ATOMIC_PR_CHECK=1 <command>` (logged via trace-helper) bypasses the atomic-PR gate for genuine bundle cases that the goal's `bundle: true` flag did not capture. `post-write-trace.sh` has no override — the trace is append-only and never blocks.
+
+**Verify the wiring:**
+
+```bash
+# Sanity: both hooks executable + reachable
+ls -l .claude/hooks/atomic-pr-check.sh .claude/hooks/post-write-trace.sh
+
+# Sanity: pr-strategy rule reachable via additionalDirectories
+test -f ../bassclef/.claude/rules/pr-strategy.md && echo "pr-strategy reachable" || echo "NOT reachable"
+
+# Sanity: settings.json has both hooks wired with correct matchers
+python3 -c "import json; d=json.load(open('.claude/settings.json')); \
+  bash_hooks=[h.get('command','') for entry in d.get('hooks',{}).get('PreToolUse',[]) if entry.get('matcher')=='Bash' for h in entry.get('hooks',[])]; \
+  post_hooks=[h.get('command','') for entry in d.get('hooks',{}).get('PostToolUse',[]) if 'Write' in entry.get('matcher','') or 'Edit' in entry.get('matcher','') for h in entry.get('hooks',[])]; \
+  print('atomic-pr-check wired (PreToolUse Bash)' if any('atomic-pr-check' in c for c in bash_hooks) else 'NOT wired'); \
+  print('post-write-trace wired (PostToolUse Write|Edit)' if any('post-write-trace' in c for c in post_hooks) else 'NOT wired')"
+```
+
+Source: bassclef#1142 (this wiring step — T9, workflow chain). Sister rule: `.claude/rules/pr-strategy.md`. Follow-on: `post-skill-friction-check.sh` wire deferred from T9 goal scope.
+
+##### 2.2.8 Wire testing-tier-enforce + allowlist (bassclef#1143 T10)
+
+Symlink the bassclef testing-tier enforcer into adopter's `.claude/hooks/`. The hook covers Tier 0 through Tier 3. It does not register as its own PreToolUse entry. Instead it runs inside `pre-commit-gate.sh` from Phase 2.2.5. When an adopter edits a Tier 0 source file without touching its matching test file, `pre-commit-gate.sh` calls `testing-tier-enforce.sh`. The commit BLOCKs with a structured stderr message.
+
+Symlink both the hook and the allowlist baseline:
+
+```bash
+mkdir -p .claude/hooks
+ln -sf "../../../bassclef/.claude/hooks/testing-tier-enforce.sh" \
+       ".claude/hooks/testing-tier-enforce.sh"
+ln -sf "../../../bassclef/.claude/hooks/testing-tier-enforce-allowlist.txt" \
+       ".claude/hooks/testing-tier-enforce-allowlist.txt"
+```
+
+The allowlist baseline grandfathers existing untested adopter source files for 60 days (the default grace window). Adopter operators can backfill tests as files are next touched, OR adjust the grace window per `testing-tier-config.md` § Allowlist.
+
+**Composition chain** — `pre-commit-gate.sh` (Phase 2.2.5) calls `testing-tier-enforce.sh` as one of its check steps. No new PreToolUse settings.json entry is needed; the hook fires whenever pre-commit-gate fires (PreToolUse Edit|Write|MultiEdit). This is the chained-composition pattern: Phase 2.2.5 wired the parent gate; Phase 2.2.8 plugs the tier-enforce check into the existing chain.
+
+**Goal-vs-implementation note** — the goal 2026-06-18b WU-4 acceptance describes `testing-tier-enforce.sh` as "PreToolUse Edit|Write" wiring. The actual wiring is via pre-commit-gate composition (no separate matcher entry). Documented per the actual implementation.
+
+**Rule propagation** — `.claude/rules/testing-tier-config.md` + `.claude/rules/test-list-discipline.md` + `.claude/rules/test-sufficiency.md` load via `additionalDirectories`. No copy needed.
+
+**Override path** — `SKIP_TESTING_TIER_ENFORCE=1 <command>` (logged via trace-helper). Use only for one-shot migration scripts that bootstrap test files into the spine.
+
+**Verify the wiring:**
+
+```bash
+# Sanity: hook + allowlist reachable
+ls -l .claude/hooks/testing-tier-enforce.sh .claude/hooks/testing-tier-enforce-allowlist.txt
+
+# Sanity: pre-commit-gate composes testing-tier-enforce
+grep -q "testing-tier-enforce.sh" .claude/hooks/pre-commit-gate.sh \
+  && echo "tier-enforce composed in pre-commit-gate" \
+  || echo "NOT composed (pre-commit-gate may be stale; resync bassclef)"
+
+# Sanity: testing-tier-config rule reachable
+test -f ../bassclef/.claude/rules/testing-tier-config.md && echo "tier-config rule reachable" || echo "NOT reachable"
+```
+
+The `testing.path_matchers` seed (per-tech-stack defaults) lands in Phase 2.3.7 below — that is the step the goal flagged for operator-eyes design choices.
+
+Source: bassclef#1143 (this wiring step — T10, iteration-2 BLOCKER). Sister rules: `.claude/rules/testing-tier-config.md` + `.claude/rules/test-list-discipline.md` + `.claude/rules/test-sufficiency.md`. Pairs with Phase 2.2.5 (pre-commit-gate parent chain).
+
+##### 2.2.9 Verify test-discipline rules propagate to the adopter session (bassclef#1144 T11)
+
+The two test-discipline rules propagate to the adopter session on their own. Those rules are `.claude/rules/test-list-discipline.md` (Beck's test list as planning artifact) and `.claude/rules/test-sufficiency.md` (10-criterion rubric per Myers + Hoare).
+
+The `additionalDirectories: ["../bassclef"]` entry that Phase 2.2 wrote does the work. It tells Claude Code to load every file under bassclef's `.claude/rules/` into the adopter's session context at session-start.
+
+No copy needed. No per-rule symlink needed.
+
+This step is the explicit verification — without it, the install is silent and the adopter does not know the rules are live.
+
+Verify the rules are reachable + loaded:
+
+```bash
+# Sanity: both rule files reachable via additionalDirectories
+test -f ../bassclef/.claude/rules/test-list-discipline.md \
+  && echo "test-list-discipline reachable" \
+  || echo "test-list-discipline NOT reachable"
+test -f ../bassclef/.claude/rules/test-sufficiency.md \
+  && echo "test-sufficiency reachable" \
+  || echo "test-sufficiency NOT reachable"
+
+# Sanity: settings.json carries the additionalDirectories entry
+python3 -c "import json; d=json.load(open('.claude/settings.json')); \
+  dirs=d.get('permissions',{}).get('additionalDirectories',[]); \
+  print('bassclef loaded via additionalDirectories' if '../bassclef' in dirs else 'NOT loaded — check Phase 2.2 wiring')"
+```
+
+**What this gives the adopter** — every adopter session that touches a test file gets the Beck test-list discipline (open with `# test-list:` block; mark `[x]` as each assertion ships; pending `[ ]` lines are honest in-flight signal) AND the 10-criterion sufficiency rubric (branch coverage / exit-code matrix / matcher coverage / override paths / stdin contract / external-binary handling / trap cleanup / stderr format / state-file interactions). Together they catch tests that pass but miss the intended assertion — the failure class eugene-supplements hit when 26 tests landed after source with zero asserted intent visible.
+
+**Composition** — the rules pair with Phase 2.2.5 (`pre-commit-gate.sh` parent chain) + Phase 2.2.8 (`testing-tier-enforce.sh` Tier 0/1/2/3 mechanical enforcer). Methodology layer (rules) supplies the why; mechanical layer (hooks) fires at the moment of failure.
+
+**No override needed** — rules are read-only context; they neither block writes nor produce stderr. Adopters can choose to ignore the rules per session, but the agent's own self-check during artifact-write keeps them honest.
+
+Source: bassclef#1144 (this propagation step — T11, iteration-2 BLOCKER). Sister rules: `.claude/rules/test-list-discipline.md` + `.claude/rules/test-sufficiency.md`. Pairs with Phase 2.2.8 (the enforcer the rules guide).
+
+##### 2.2.10 Wire role-entry-gate PreToolUse hook (bassclef#1145 T13)
+
+**Lite adopter note (bassclef#740 Task 1.2).** This hook ships at `tier: standard`. Skip this step if your tier is lite. Resolve tier via `lib/tier-check.sh`.
+
+Symlink the bassclef PreToolUse hook that catches source-code edits when the matching agent role has not been entered for the current session. MVP scope: Builder role only (matches source files in common languages). Other roles (Architect, Reviewer, Designer) deferred to a follow-on per goal narrowing — the multi-role matching matrix deserves its own design pass.
+
+The hook reads `$CWD/state/markers/role/<role>/<session_id>.marker`. The marker is written by the agent once the role's persona has been loaded (sequential mode: Claude reads `~/.claude/agents/builder.md`, writes the marker, proceeds with the role's discipline loaded; orchestrator-gated mode: Orchestrator routes the dispatch to the Builder agent which writes its own marker before proceeding).
+
+Symlink the hook:
+
+```bash
+mkdir -p .claude/hooks
+ln -sf "../../../bassclef/.claude/hooks/role-entry-gate.sh" \
+       ".claude/hooks/role-entry-gate.sh"
+```
+
+Add to the PreToolUse Edit|Write|MultiEdit matcher block in `.claude/settings.json`. The matcher likely exists from earlier Phase 2.x steps (substrate-clarity-gate from 2.2.2, pattern-annotation-validate from 2.2.4, the parent gate chain from 2.2.5) — append `role-entry-gate` to its `hooks` array; do not duplicate the matcher entry.
+
+```jsonc
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/role-entry-gate.sh" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**MVP scope** — the hook fires on source-code file extensions only (`.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.rb`, `.go`, `.rs`, `.java`, `.kt`, `.swift`, `.cs`, `.cpp`, `.c`, `.h`). Non-source paths pass through. Tightening per `tech_stack.lang` reading (so a Python adopter only fires on `.py`) is a follow-on; the safe default union catches the common cases.
+
+**Marker writing** — the agent writes the marker once it enters the role. Marker shape:
+
+```json
+{
+  "role": "builder",
+  "session_id": "<uuid from harness>",
+  "entered_at": "<ISO 8601 UTC>"
+}
+```
+
+A future `/role-entry` skill automates the marker write + persona load; until then, the agent writes the marker by hand after reading the persona file. The BLOCK message documents the exact one-liner.
+
+**Composition rule** — when the Edit|Write|MultiEdit matcher block already exists, append `role-entry-gate` to its `hooks` array. Order within the array: place `role-entry-gate` AFTER substrate-clarity-gate + artifact-ingestion-gate + pattern-annotation-validate + pre-commit-gate + state-validate + multi-tenancy-check, so structural / format / state validation fires first; role-discipline check fires last. Role-entry is the methodology gate, not the structural gate — it should not run before the cheap structural checks pass.
+
+**Override path** — `SKIP_ROLE_ENTRY=1 <command>` (logged via trace-helper). Use for one-shot scripts the operator runs without entering an agent role, OR when the adopter is on a workflow that does not map to bassclef's role taxonomy.
+
+**Verify the wiring:**
+
+```bash
+# Sanity: hook executable + reachable
+ls -l .claude/hooks/role-entry-gate.sh
+
+# Sanity: agent personas reachable via additionalDirectories (the BLOCK message refers to them)
+test -f ~/.claude/agents/builder.md && echo "builder persona reachable" || echo "builder persona NOT reachable (user-level agents missing)"
+
+# Sanity: settings.json has the hook wired under the Edit matcher
+python3 -c "import json; d=json.load(open('.claude/settings.json')); \
+  hooks=[h.get('command','') for entry in d.get('hooks',{}).get('PreToolUse',[]) if 'Edit' in entry.get('matcher','') for h in entry.get('hooks',[])]; \
+  print('role-entry-gate wired' if any('role-entry-gate' in c for c in hooks) else 'NOT wired')"
+```
+
+**Not yet wired in bassclef** — this hook ships to the adopter via `/onboard-repo` first. Bassclef's own settings.json adds the hook in a follow-on once the marker convention has run in the wild for a few sessions and the multi-role matching follow-on lands.
+
+Source: bassclef#1145 (this hook step — T13). Sister agent personas: `~/.claude/agents/builder.md` (MVP target) + `~/.claude/agents/architect.md` + `~/.claude/agents/reviewer.md` + `~/.claude/agents/designer.md` (follow-on coverage). Follow-on tickets: multi-role matching matrix + `/role-entry` skill + `state/markers/role/` schema authoring under `standards/state-spine.md`.
+
+##### 2.2.11 Wire temperance-gate PreToolUse hook (bassclef#1147 T15)
+
+Symlink the bassclef hook that fires the /temperance question at decision boundaries. MVP scope: one active trigger — "high-impact path edit". It catches edits to `.claude/`, `standards/`, `lib/state.sh`, and SKILL.md files when the session has no fresh temperance marker. Other triggers stay as stubs. Follow-on tickets will design them.
+
+<!-- FKGL-EXEMPT: source ticket enumeration -->
+Sources: `2026-06-18b` WU-7 goal (explain-mode entry, chain-anchor entry, non-stacked-branch first edit, post-compaction recovery); ticket #1147 (N consecutive edits, substrate proposal without catalog browse, diagnose-repro marker absence).
+<!-- /FKGL-EXEMPT -->
+
+The hook pairs with `pre-commit-gate.sh` from Phase 2.2.5. That hook handles the first edit on a branch that stands alone. This hook adds one more check. It catches edits to high-impact paths that the other hook misses.
+
+Symlink the hook:
+
+```bash
+mkdir -p .claude/hooks
+ln -sf "../../../bassclef/.claude/hooks/temperance-gate.sh" \
+       ".claude/hooks/temperance-gate.sh"
+```
+
+Add to the PreToolUse Edit|Write|MultiEdit matcher block in `.claude/settings.json`. The matcher likely already exists; append `temperance-gate` to its `hooks` array. Order: place `temperance-gate` AFTER structural checks (substrate-clarity-gate, artifact-ingestion-gate, pattern-annotation-validate, pre-commit-gate, state-validate, multi-tenancy-check) and AFTER role-entry-gate. Methodology gate fires last; structural + role checks fire first.
+
+```jsonc
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/temperance-gate.sh" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Marker convention** — the hook reads `$CWD/state/markers/temperance/<session_id>.marker` (session-scoped) AND falls back to any existing marker under `state/markers/temperance/` (loose branch-scoped check; tighter matching-branch check is a follow-on). The temperance marker is written by the agent (or by `/temperance` skill invocation) once the right-thing / right-way questions have been answered.
+
+**Marker shape:**
+
+```json
+{
+  "session_id": "<uuid from harness>",
+  "entered_at": "<ISO 8601 UTC>",
+  "question_answered": "yes"
+}
+```
+
+**Override path** — `SKIP_TEMPERANCE_GATE=1 <command>` (logged via trace-helper). Use sparingly; the trigger is the point of the discipline.
+
+**Verify the wiring:**
+
+```bash
+# Sanity: hook executable + reachable
+ls -l .claude/hooks/temperance-gate.sh
+
+# Sanity: temperance skill reachable via additionalDirectories
+test -f ../bassclef/.claude/skills/temperance/SKILL.md && echo "temperance skill reachable" || echo "NOT reachable"
+
+# Sanity: settings.json has the hook wired under the Edit matcher
+python3 -c "import json; d=json.load(open('.claude/settings.json')); \
+  hooks=[h.get('command','') for entry in d.get('hooks',{}).get('PreToolUse',[]) if 'Edit' in entry.get('matcher','') for h in entry.get('hooks',[])]; \
+  print('temperance-gate wired' if any('temperance-gate' in c for c in hooks) else 'NOT wired')"
+```
+
+**Not yet wired in bassclef** — adopters first; bassclef's own settings.json adds the hook in a follow-on once the MVP trigger has run in the wild for a few sessions and the trigger-taxonomy follow-on lands.
+
+Source: bassclef#1147 (this hook step — T15). Sister skill: `.claude/skills/temperance/SKILL.md` (the methodology this gate enforces mechanically). Follow-on tickets: explain-mode + chain-anchor + post-compaction + non-stacked first edit + N consecutive edits + substrate proposal + diagnose-repro triggers + `standards/temperance-discipline.md` documenting the full trigger taxonomy.
+
+##### 2.3 Create the project config file
+
+Copy from `presence/install/substrate-config.md`, then prompt operator
+for:
+
+- `journal_doc_id` (optional — create Google Doc now or later)
+- `changelog_doc_id` (optional)
+- `deploy_targets` (local/staging/prod booleans)
+- `budget.session_ceiling` / `iteration_ceiling` (sequential mode → `$0`)
+- `hosting_platform` (REQUIRED for any consumer that ships a UI). Default
+  to `amplify` per ADR-008 + app-consumer precedent. Set `none` for
+  docs-only / no-UI repos. Enum:
+  `amplify | ec2-tailscale | vercel | netlify | cloudflare-pages | none`.
+  `/bind-subdomain` + `/launch-preview` refuse on `none` unless
+  `BIND_SUBDOMAIN_OVERRIDE=1` is set. Closes bassclef#449.
+
+If operator says "defer", scaffold with placeholders and `TODO:` markers
+so next session surfaces them.
+
+##### 2.3.5 Write the bassclef-configs adopter-default seed (bassclef#1135 WU-4)
+
+Write `.claude/bassclef-configs.jsonc` with the adopter-default seed.
+Every downstream hook + skill reads from this file; without it, defaults
+are invisible to the adopter. Phase 2.5 (security_scanning) appends to
+this file later in the same Procedure run, so the foundation MUST land
+first.
+
+```bash
+cat > .claude/bassclef-configs.jsonc <<'JSONC'
+// bassclef-configs.jsonc — unified adopter configuration discovery surface
+//
+// Edit the values below. Each block has a comment explaining what it does,
+// what the default is, and which bassclef substrate component reads it.
+//
+// JSON Schema: standards/state-spine/schemas/bassclef-configs.schema.json
+// Full reference: standards/bassclef-configs-schema.md
+{
+  // Whether bassclef's substrate syncs from upstream at SessionStart.
+  // Adopter default: false (opt-in trust posture). Turn on when you want
+  // bassclef to keep itself current automatically.
+  // Pairs with: .claude/hooks/bassclef-sync.sh
+  "sync": { "enabled": false },
+
+  // Per-agent LLM model routing. Most agents stay cheap-fast; Builder
+  // gets balanced for code quality; Shaper gets capable for problem framing.
+  // Pairs with: .claude/agents/<role>.md frontmatter
+  "model_tier": {
+    "Builder": "balanced",
+    "Closer": "cheap-fast",
+    "Deployer": "cheap-fast",
+    "DocsWriter": "cheap-fast",
+    "Explorer": "cheap-fast",
+    "Orchestrator": "cheap-fast",
+    "Reviewer": "cheap-fast",
+    "Shaper": "capable"
+  },
+
+  // Adopter plan tier. Caps parallel agent dispatch per Anthropic plan limits.
+  // tier-1 = single-agent serial (safest); tier-2 = 2-3 parallel after upgrade;
+  // tier-4 = 5+ parallel for operator-scale workflows.
+  // Pairs with: .claude/skills/longrun/SKILL.md parallel-dispatch logic
+  "plan_tier": "tier-1",
+
+  // Plain-English discipline for agent reply prose to operator. When true,
+  // the Stop hook scans the agent's last message for bassclef-internal
+  // jargon and surfaces findings to stderr (advisory). 'strict' makes the
+  // hook block the stop until prose is clean. false disables the scan.
+  //
+  // Optional: kiss_words_strict_places escalates specific places to strict
+  // even when the global toggle stays advisory. V1 places (bassclef#1171):
+  //   - closeout_blocks  — matches a "## Closeout audit" heading
+  //   - summary_tables   — matches a "## Status" heading
+  //   - next_pickup      — matches a "## Next pickup" heading
+  // Adopter default: advisory everywhere; no strict places. Flip to strict
+  // or add places when you want the rule to actually catch you.
+  //
+  // Pairs with: .claude/rules/plain-english-discipline.md
+  //             .claude/hooks/turn-prose-kiss-check.sh
+  "prose_discipline": {
+    "kiss_words_turn_prose": true
+    // "kiss_words_strict_places": ["closeout_blocks"]  // uncomment when ready
+  },
+
+  // Per-path testing-tier enforcement (4 tiers: 0 strict TDD / 1 test-with /
+  // 2 smoke / 3 manual verify). global_floor applies when no path_matcher matches.
+  // Adopter default: floor=1 (WARN on missing test); empty matchers (add your own).
+  // Pairs with: .claude/rules/testing-tier-config.md
+  "testing": {
+    "global_floor": 1,
+    "path_matchers": []
+  }
+
+  // Phase 2.5 below appends "security_scanning" here.
+  // /onboard-repo Phase 2.x or future tickets append "tech_stack", "hook_chain",
+  // "discipline_layers" as those vocabularies stabilize. Per bassclef#1135.
+}
+JSONC
+```
+
+Validate the written file against the schema:
+
+```bash
+perl -pe 's,^\s*//.*$,,; s,/\*.*?\*/,,g' .claude/bassclef-configs.jsonc \
+  | ajv validate -s ~/src/sunj-labs/bassclef/standards/state-spine/schemas/bassclef-configs.schema.json \
+                 -d - --spec=draft2020 -c ajv-formats
+```
+
+Expect a single `valid` line. The file is now the single source of truth for adopter configuration; subsequent Phase 2.x steps APPEND to it (Phase 2.3.6 tech_stack, Phase 2.5 security_scanning, future T-tickets for hook_chain etc.) rather than rewriting from empty.
+
+If the adopter has a pre-existing `.claude/bassclef-configs.jsonc` from a prior SENTINEL_bassclef_version, prompt before overwriting; offer a `--merge` flow (operator-driven; not automated in V1).
+
+##### 2.3.6 Discover and write the tech_stack block (bassclef#1127 WU-2)
+
+Stack-bound rules + standards in bassclef (`api-conventions.md`, `sdlc-gates.md`, `schema-management.md`, `new-dependency-check.md`, `frontend-stack.md`, `deployment-topology.md`) read `tech_stack:` from `.claude/bassclef-configs.jsonc` to route per-stack discipline. Without the block, non-matching adopters see false-fires (Prisma rules at SQLAlchemy adopters, Next.js API conventions at FastAPI adopters, etc.). This step writes the block so the bleed stops at install time.
+
+Schema reference: `standards/state-spine/schemas/tech-stack.schema.json`. Standard: `standards/tech-stack-config.md`.
+
+**Auto-detection signals** (per `standards/tech-stack-config.md` § Auto-detection at `/onboard-repo`):
+
+| Build file present | Suggests |
+|---|---|
+| `package.json` with `"next"` dep | `frontend: nextjs`, `lang: typescript` (if `tsconfig.json` also present) |
+| `package.json` with `"react"` dep (no `next`) | `frontend: react-vite` (if `vite.config.*` present) |
+| `package.json` with `"prisma"` dep | `orm: prisma` |
+| `package.json` with `"drizzle-orm"` dep | `orm: drizzle` |
+| `package.json` + `pnpm-lock.yaml` | `pkg_manager: pnpm` |
+| `package.json` + `yarn.lock` | `pkg_manager: yarn` |
+| `package.json` + `package-lock.json` | `pkg_manager: npm` |
+| `pyproject.toml` or `requirements.txt` | `lang: python` |
+| `pyproject.toml` with `sqlalchemy` | `orm: sqlalchemy` |
+| `pyproject.toml` with `alembic` | `orm: alembic` |
+| `pyproject.toml` with `fastapi` | `frontend: fastapi`, `backend: python` |
+| `pyproject.toml` with `django` | `frontend: django`, `backend: python` |
+| `Gemfile` | `lang: ruby`, `pkg_manager: gem` |
+| `Gemfile` with `rails` | `frontend: rails`, `backend: ruby` |
+| `go.mod` | `lang: go`, `pkg_manager: go-mod`, `backend: go` |
+| `Cargo.toml` | `lang: rust`, `pkg_manager: cargo`, `backend: rust` |
+| `vercel.json` or `.vercelrc` | `deploy: vercel` |
+| `fly.toml` | `deploy: fly` |
+| `netlify.toml` | `deploy: netlify` |
+| `render.yaml` | `deploy: render` |
+
+No signal → field stays `none` and waits for operator override.
+
+**Operator prompt** (surface this exact text):
+
+```
+Detected stack signals:
+
+  lang:         <detected or "(no signal)">
+  frontend:     <detected or "(no signal)">
+  backend:      <detected or "(no signal)">
+  orm:          <detected or "(no signal)">
+  pkg_manager:  <detected or "(no signal)">
+  deploy:       <detected or "(no signal)">
+
+Stack-bound rules route per-adopter from this block. Without it,
+non-matching adopters see false-fires from rules written for the
+default stack (TypeScript + Next.js + Prisma + EC2-Tailscale).
+
+Three paths:
+
+  [a] Accept detected values
+  [b] Override per field (5-7 short prompts)
+  [c] Skip — write declared_via: deferred and revisit later
+      (rules fall back to operator defaults; expect some false-fires
+      until you set the block)
+
+Pick a/b/c:
+```
+
+**On accept (a):** write the block with detected values + `declared_via: onboard-repo` + `declared_at: <ISO date>`.
+
+**On per-field override (b):** prompt each field in order with detected value as the default. Field-level enums per `standards/tech-stack-config.md` § Fields.
+
+**On skip (c):** write `tech_stack: { declared_via: "deferred", declared_at: <ISO date> }` only. The schema admits all fields as optional; rules fall back gracefully. Operator can revisit by re-running `/onboard-repo` or editing the block directly.
+
+**Append to `.claude/bassclef-configs.jsonc`** using `jq` or in-place edit; the block goes immediately before the closing brace + after `testing`:
+
+```bash
+# Pseudo-procedure; actual implementation reads the operator's path choice
+# and constructs the block from detected + override values.
+cat >> .claude/bassclef-configs.jsonc <<TECH_STACK
+,
+
+  // Tech stack vocabulary. Stack-bound rules read this to route per-
+  // stack discipline (schema-management.md ORM routing, api-conventions
+  // frontend routing, sdlc-gates lang routing, etc.).
+  // Auto-detected at /onboard-repo Phase 2.3.6; operator confirms or
+  // overrides per field.
+  // Pairs with: standards/tech-stack-config.md (schema + semantics),
+  //             standards/state-spine/schemas/tech-stack.schema.json
+  // Schema reference: bassclef#1127 tech_stack discovery
+  "tech_stack": {
+    "lang": "<value>",
+    "frontend": "<value>",
+    "backend": "<value>",
+    "orm": "<value>",
+    "pkg_manager": "<value>",
+    "deploy": "<value>",
+    "declared_at": "<ISO date>",
+    "declared_via": "onboard-repo"
+  }
+TECH_STACK
+```
+
+(In practice the writer holds the file open as JSON-with-comments, mutates the parsed object, re-emits with comments preserved per the comment-aware JSONC editor pattern; the heredoc above is illustrative.)
+
+**Validate after append:**
+
+```bash
+perl -pe 's,^\s*//.*$,,; s,/\*.*?\*/,,g' .claude/bassclef-configs.jsonc \
+  | ajv validate -s ~/src/sunj-labs/bassclef/standards/state-spine/schemas/bassclef-configs.schema.json \
+                 -d - --spec=draft2020 -c ajv-formats
+```
+
+Expect `valid`. If the file fails to validate, revert the append, surface the schema error, and re-prompt.
+
+**Acceptance:**
+
+- After Phase 2.3.6 completes, `.claude/bassclef-configs.jsonc` contains a `tech_stack:` block.
+- Block validates against `tech-stack.schema.json`.
+- `declared_via` is one of `onboard-repo` (path a or b) or `deferred` (path c); `migrated` and `demo-prompt` reserved for other callers.
+- Operator can re-run `/onboard-repo` and the existing block is detected; prompt asks whether to keep, re-detect, or edit per-field.
+
+**Composes with downstream Phase 2.x steps:**
+
+- Phase 2.3.7 (testing-tier path_matchers seed) reads `tech_stack.lang` to pick the per-stack default tier matchers.
+- Phase 2.5 (security scanning) reads `tech_stack.lang` to seed the scanner adapter.
+- Future Phase 2.x for `hook_chain` reads stack signals to pick per-stack hook defaults.
+
+##### 2.3.7 Seed testing.path_matchers per declared tech_stack (bassclef#1143 T10)
+
+Phase 2.3.5 wrote the `testing` block with `global_floor: 1` + empty `path_matchers`. Phase 2.3.6 just discovered + wrote `tech_stack`. This step reads `tech_stack.lang` and seeds `testing.path_matchers` with sensible per-stack defaults so the Tier 0 / Tier 1 enforcer (Phase 2.2.8) fires on the right paths from day one.
+
+**Per-stack default seeds** (operator-eyes design choices):
+
+For `tech_stack.lang: typescript` + `tech_stack.frontend: nextjs` (bassclef default):
+
+```jsonc
+"testing": {
+  "global_floor": 1,
+  "path_matchers": [
+    { "match": "lib/domain/**/*.ts",          "tier": 0 },
+    { "match": "lib/infra/**/*.ts",           "tier": 0 },
+    { "match": "app/api/**/*.ts",             "tier": 1 },
+    { "match": "app/actions/**/*.ts",         "tier": 1 },
+    { "match": "app/_components/**/*.tsx",    "tier": 2 },
+    { "match": "app/**/*.tsx",                "tier": 2 },
+    { "match": "docs/**/*.md",                "tier": 3 }
+  ]
+}
+```
+
+For `tech_stack.lang: python` + `tech_stack.frontend: fastapi`:
+
+```jsonc
+"testing": {
+  "global_floor": 1,
+  "path_matchers": [
+    { "match": "domain/**/*.py",              "tier": 0 },
+    { "match": "infrastructure/**/*.py",      "tier": 0 },
+    { "match": "api/**/*.py",                 "tier": 1 },
+    { "match": "templates/**/*",              "tier": 2 },
+    { "match": "docs/**/*.md",                "tier": 3 }
+  ]
+}
+```
+
+Other stacks (ruby-rails, go-gin, java-spring) ship default seeds as per-stack siblings under `standards/testing-tier-seeds/<stack>.md` — deferred to a follow-on ticket when an adopter on that stack files for them. The pattern is the same: Tier 0 on the essential pure-domain layer; Tier 1 on the API + actions layer; Tier 2 on UI + template surfaces; Tier 3 on docs.
+
+**On `tech_stack.lang: none` or `deferred`** — skip the seed; leave `path_matchers: []` empty. The `global_floor: 1` keeps the WARN posture; adopter can hand-edit later.
+
+**Operator prompt** (surface this exact text after Phase 2.3.6 completes):
+
+```
+Tech stack: <detected lang + frontend>
+
+Seed testing.path_matchers with the per-stack default for <stack>?
+
+  [a] Yes, accept default seed (recommended)
+  [b] Show me the seed first
+  [c] Skip — keep path_matchers empty (manual seed later)
+
+Pick a/b/c:
+```
+
+**On accept (a)** — write the matching per-stack seed into `testing.path_matchers` in `bassclef-configs.jsonc`. Use the comment-aware JSONC editor pattern so the existing comments + `global_floor` survive.
+
+**On show first (b)** — print the seed inline; ask for accept/edit/skip.
+
+**On skip (c)** — leave empty; print "Adopter chose to skip — `testing.path_matchers` stays empty. Set with `/onboard-repo` re-run or hand-edit later."
+
+**Validate after write:**
+
+```bash
+perl -pe 's,^\s*//.*$,,; s,/\*.*?\*/,,g' .claude/bassclef-configs.jsonc \
+  | ajv validate -s ~/src/sunj-labs/bassclef/standards/state-spine/schemas/bassclef-configs.schema.json \
+                 -d - --spec=draft2020 -c ajv-formats
+```
+
+Expect a single `valid` line. The `testing.path_matchers` items must validate against the bassclef-configs schema.
+
+**Stack siblings deferred** — only typescript-nextjs + python-fastapi ship in this step. Adopters on ruby-rails / go-gin / java-spring / rust-axum etc. get `global_floor: 1` + empty matchers (the safe default WARN posture) and can hand-seed per their layout. A follow-on ticket adds per-stack seed siblings under `standards/testing-tier-seeds/<stack>.md` as adopters request them.
+
+Source: bassclef#1143 (this seed step — T10, iteration-2 BLOCKER). Sister rule: `.claude/rules/testing-tier-config.md`. Pairs with Phase 2.2.8 (the enforcer that reads this seed).
+
+##### 2.3.8 Surface the wiki_sync toggle (bassclef#1265 — Phase 1 stub)
+
+The `wiki_sync` block in `.claude/bassclef-configs.jsonc` controls whether the adopter's repo gets the bassclef-docs-sync workflow vendored from `presence/install/bassclef-docs-sync.template.yml`. This step surfaces the toggle so adopters see the option exists.
+
+**Phase 1 (this step — bet 2026-06-20b) — minimal stub:**
+
+Read the adopter's `wiki_sync.enabled` value from the bassclef-configs file just written. Print one of the following:
+
+- **`enabled: false`** (default — universal): print
+  > Wiki-sync is OFF. The wiki-as-we-go discipline rule still loads at session-start, but no workflow fires. To enable later: edit `.claude/bassclef-configs.jsonc` `wiki_sync.enabled` to `true` and re-run `/onboard-repo` for the vendoring step (full vendoring lands in Phase 2 of bet 2026-06-20b — see `docs/iteration-bets/2026-06-20b-cold-adopter-mechanism-inheritance.md`).
+- **`enabled: true`**: print
+  > Wiki-sync is ON. Full vendoring of `presence/install/bassclef-docs-sync.template.yml` → `.github/workflows/bassclef-docs-sync.yml` + `presence/install/docs-sync-allowlist.template.md` → `standards/docs-sync-allowlist.md` is **deferred to Phase 2 of bet 2026-06-20b**. For now, copy both templates manually if you need the wiki to update from main pushes today.
+
+**Phase 2 (next session) — full vendoring (deferred):**
+
+- Auto-copy both templates into the adopter's repo
+- Open a follow-up PR for GHA secrets if `target_wiki_repo` requires non-default auth
+- Walk the adopter through the three workflow-edit surfaces (the `on.push.paths` glob, the Filter step's case-glob, the Sync step's source-path → wiki-page mapping)
+- Smoke-test by pushing a docs change and verifying the wiki updates
+
+The Phase 1 stub keeps this step minimal so the goal stays bounded. Adopters who want wiki-sync today can copy the templates by hand from bassclef's `presence/install/` (workflows + cold-adopter assets).
+
+**Composes with:**
+
+- `.claude/skills/docs-sync/SKILL.md` § Adopter mode (read at runtime; surfaces BLOCK if templates not vendored)
+- `.claude/rules/session-artifacts.md` § Wiki-as-we-go discipline (methodology rule that triggers the closeout question)
+
+Source: bassclef#1265 (this surfacing step — wiki-sync mechanism adopter inheritance). Sister bet: `docs/iteration-bets/2026-06-20b-cold-adopter-mechanism-inheritance.md` WU-2.
+
+##### 2.3.9 Write the onboard-repo state marker (bassclef-upstream#664)
+
+Write `.claude/state/onboard-repo.state.json` after Phase 2.3 has
+populated the config file(s). The marker captures which mode was used,
+the ISO timestamp, and which files were written. The configs UI reads
+this marker to render the first-run overlay (per canvas 2026-07-08
+Appendix C). Future audits trace how a repo got wired.
+
+Re-runs append a history entry — the marker keeps prior runs, not
+clobber them.
+
+Invoke the helper script that ships alongside this SKILL:
+
+```bash
+# ONBOARD_MODE is set earlier in Procedure —
+#   default / --with-deploy-host / --with-secrets / --full / --greenfield-from-intent
+bash .claude/skills/onboard-repo/write-state-marker.sh "${ONBOARD_MODE:-default}"
+```
+
+The script writes / updates `.claude/state/onboard-repo.state.json`
+with shape `{mode, timestamp_iso, paths_written[], history[], skill_version}`.
+Tier 0 tests at `.claude/skills/onboard-repo/tests/write-state-marker.test.sh`
+pin all behavior including re-run history append.
+
+**Composes with:**
+
+- Configs UI first-run overlay (`bassclef/configs/`, bet 2026-07-08a WU-7)
+- Future audits reading `.claude/state/onboard-repo.state.json`
+
+Source: bassclef-upstream#664 (state marker for onboard-repo). Part of goal
+`docs/iteration-bets/2026-07-08a-configs-ui-iteration-1.md` WU-4.
+
+##### 2.3.10 Wire the cron installer for auto-save (bassclef-upstream#941)
+
+Goal 27b (PR #937) shipped `presence/install/schedule-auto-save.cron.sh` at
+`tier: lite`. The installer writes a cron entry that fires
+`save-state.sh --auto --quiet` on idle. Sam's magic demo per canvas
+`docs/canvases/2026-07-19-bassclef-lite.md` L67-71 promises session-state
+continuity as part of onboarding. This step wires the installer in.
+
+Behavior per OS:
+
+- **macOS + Linux + WSL** — run the installer directly. It appends one
+  crontab entry and is idempotent (re-running is safe per PR #937 Test 4).
+- **Native Windows (no WSL)** — cron is not available. Point the adopter at
+  `presence/install/schedule-auto-save.taskscheduler.md` for the manual
+  Task Scheduler setup.
+
+```bash
+OS_KIND="$(uname -s)"
+case "$OS_KIND" in
+  Darwin|Linux)
+    if [ -x "$BASSCLEF_DIR/presence/install/schedule-auto-save.cron.sh" ]; then
+      bash "$BASSCLEF_DIR/presence/install/schedule-auto-save.cron.sh" \
+        || echo "WARNING: cron installer failed; run manually to enable auto-save" >&2
+    else
+      echo "WARNING: schedule-auto-save.cron.sh not found; skip auto-save wire" >&2
+    fi
+    ;;
+  MINGW*|CYGWIN*|MSYS*)
+    echo "Native Windows detected. Cron is not available."
+    echo "See presence/install/schedule-auto-save.taskscheduler.md for the"
+    echo "manual Task Scheduler setup that wires auto-save on Windows."
+    ;;
+  *)
+    echo "Unknown OS '$OS_KIND'; skip auto-save wire"
+    ;;
+esac
+```
+
+The installer prints its own progress. Failures do not stop onboarding —
+auto-save is a nice-to-have on first install, and adopters can re-run
+the installer any time via `bash $BASSCLEF_DIR/presence/install/schedule-auto-save.cron.sh`.
+
+**Composes with:**
+
+- `presence/install/schedule-auto-save.cron.sh` (PR #937 — the cron installer)
+- `presence/install/schedule-auto-save.taskscheduler.md` (PR #937 — Windows guide)
+- ADR-046 cross-OS scheduling (accepted; Option C picked)
+
+Source: bassclef-upstream#941 (wire cron into onboard for Sam's magic demo).
+
+##### 2.4 Point at bassclef's source (URL + auth)
+
+The thin-pointer dispatcher installed in 2.1 reads `.bassclef-source.json`
+for the upstream tarball URL + auth metadata when the curl fallback
+fires (Cloud Env / mobile / fresh sandboxes / CI). Schema codified at
+`standards/bassclef-source-config.md`; validation hook at
+`.claude/hooks/bassclef-source-config-validate.sh`.
+
+Before writing the file, prompt the adopter explicitly (per bassclef#939):
+
+```
+Bassclef can auto-pull the latest skills, rules, and agents into this
+repo at every Claude Code session start. Keeps you current with bassclef's
+evolution; you never manually update.
+
+Off by default. Turn on now? [y/N]
+```
+
+Persist the adopter's answer to the `auto_sync` field. Default is `false` when in doubt.
+
+```bash
+cat > .bassclef-source.json <<JSON
+{
+  "source_url": "https://api.github.com/repos/sunj-labs/bassclef/tarball/main",
+  "auth_method": "Bearer",
+  "token_env": "BASSCLEF_TOKEN",
+  "auto_sync": false,
+  "comment": "Provider: GitHub repo tarball API. Auth: fine-grained PAT 'bassclef-substrate-read' (Contents:read on sunj-labs/bassclef), stored as BASSCLEF_TOKEN in the consumer's Cloud Code environment. Schema: standards/bassclef-source-config.md. auto_sync controls whether SessionStart fetches bassclef's latest substrate; off by default per bassclef#939."
+}
+JSON
+```
+
+**Operator action — out of band, one-time per consumer:**
+
+1. Create fine-grained GitHub PAT scoped to `sunj-labs/bassclef`
+   - Permission: Contents: read
+   - Expiry: 90 days
+   - Name: `bassclef-read-{REPO_SHORT}-{YYYYMMDD}`
+2. Paste into the consumer's Cloud Code environment as `BASSCLEF_TOKEN`.
+3. Track the PAT lifecycle in operator's `substrate.secrets.md` per
+   `standards/secrets-lifecycle.md`.
+
+Provider alternatives (see `standards/bassclef-source-config.md` for
+GitHub public, GitHub private release, ADO Repos, GitLab examples).
+
+After writing the file, run the hook once locally to validate via
+sibling fast-path (no PAT needed for desktop):
+
+```bash
+echo "{\"cwd\":\"$PWD\"}" | bash .claude/hooks/bassclef-sync.sh
+```
+
+Expect: `### BASSCLEF SUBSTRATE — SYNCED` banner; skills/rules/hooks/
+luminaries symlinked into `.claude/`; no errors surfaced.
+
+##### 2.5 Configure security scanning (per bassclef goal 2026-06-17a Phase Y)
+
+Auto-detect the adopter's stack from build files, confirm with the operator, and write the `security_scanning` block to `.claude/bassclef-configs.jsonc`. Adopter copies the matching reference workflow next.
+
+Auto-detection signals (per `standards/security-scanner-adapter.md` § Stack auto-detection):
+
+```bash
+# Detect stack by build-file signal.
+STACK_GUESS="custom"
+if [ -f "package.json" ]; then
+  if grep -q '"typescript"\|"@types/' package.json; then
+    STACK_GUESS="node-typescript"
+  else
+    STACK_GUESS="node-typescript"  # TS opt-out can happen later
+  fi
+elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ] || [ -f "setup.py" ]; then
+  STACK_GUESS="python"
+elif [ -f "Gemfile" ] || ls *.gemspec >/dev/null 2>&1; then
+  STACK_GUESS="ruby"
+elif [ -f "pom.xml" ] || [ -f "build.gradle" ] || ls **/*.java >/dev/null 2>&1; then
+  STACK_GUESS="java"
+elif [ -f "go.mod" ] || ls **/*.go >/dev/null 2>&1; then
+  STACK_GUESS="go"
+fi
+```
+
+Prompt the operator (sample):
+
+```
+Bassclef security scanner adapter detected stack: <STACK_GUESS>
+
+Default scanners for this stack (per standards/security-scanner-adapter.md):
+- node-typescript: eslint-plugin-security + audit-ci + gitleaks
+- python: bandit + safety + gitleaks
+- ruby: brakeman + bundler-audit + gitleaks
+- java: spotbugs-security + dependency-check + gitleaks
+- go: gosec + govulncheck + gitleaks
+- custom: adopter-supplied list
+
+Activate scanners with stack=<STACK_GUESS>? [Y/n/custom/skip]
+```
+
+Persist the answer to the bassclef-configs block. Phase 2.3.5 (bassclef#1135 WU-4) wrote the seed file; this step adds the `security_scanning` block to it via a Python merge to keep the JSONC valid.
+
+```bash
+# Add security_scanning block to .claude/bassclef-configs.jsonc (bassclef#1135).
+# Phase 2.3.5 already wrote the seed; we add a block via JSONC-aware Python merge.
+python3 - "$STACK_GUESS" <<'PY'
+import json, re, sys, pathlib
+path = pathlib.Path('.claude/bassclef-configs.jsonc')
+raw = path.read_text()
+# Strip line + block comments before parsing
+stripped = re.sub(r'/\*.*?\*/', '', re.sub(r'//.*$', '', raw, flags=re.M), flags=re.S)
+data = json.loads(stripped)
+stack = sys.argv[1]
+data['security_scanning'] = {
+    'stack': None if stack in ('null', 'skip', '') else stack,
+    'additional_scanners': [],
+    'block_on_high_severity': True,
+}
+path.write_text(json.dumps(data, indent=2) + '\n')
+PY
+```
+
+Note: the Python merge re-serializes the file without comments. Operators
+keep the schema-doc reference (`standards/bassclef-configs-schema.md`)
+as the bassclef comment-bearing source; the on-disk file is the values.
+A follow-on (bassclef#1135 V2) may add a comment-preserving JSONC writer.
+
+INSTEAD of asking the operator to know the scanner names: the standard supplies the per-stack defaults; the operator confirms the stack choice only.
+
+If the operator answers `skip`, write `"stack": null` — scanners stay off until the next session re-runs the question.
+
+**Operator follow-up — copy the reference workflow:**
+
+After the bassclef-configs block is written, point the operator at the matching reference workflow:
+
+```
+Next step: copy the per-stack reference workflow into your repo's CI.
+
+  cp ~/src/sunj-labs/bassclef/config/security-scanners/<STACK_GUESS>.yml \
+     .github/workflows/security-scan.yml
+
+The workflow auto-skips when the bassclef-configs stack value is null,
+so copying is harmless if you're not ready to activate yet.
+```
+
+For stacks beyond node-typescript + python (which ship reference workflows), the operator authors their own workflow guided by `standards/security-scanner-adapter.md` § Stack reference matrix.
+
+##### 2.6 Set up .gitignore for bassclef's runtime files
+
+If `.gitignore` doesn't exist, create with bassclef runtime markers:
+
+```bash
+[ -f .gitignore ] || cat > .gitignore <<'EOF'
+# Bassclef runtime artifacts (per-machine, not content)
+.claude/LAST_SAVE
+.claude/SESSION_LOCK
+.claude/CHECKPOINT.md
+.claude/settings.local.json
+state/markers/verify/
+EOF
+```
+
+The sync hook will add its managed symlink block on next run; this
+seeds the file with everything else.
+
+#### Phase 3 — Create starter docs (CLAUDE.md, whereami)
+
+**Working directory: target repo.**
+
+##### 3.1 Create the starter CLAUDE.md
+
+Minimal starter. Operator owns this file going forward.
+
+The first non-title line reads `@.claude/bassclef-orientation.md` (per
+ADR-032 + Anthropic's `@filename` convention). This import loads bassclef's
+orientation into every session. The orientation names the gates, the
+luminaries, the tier ladder, and the rules the agent should not break.
+
+The orientation file lands in the adopter repo as a symlink into bassclef.
+The sync template Section 3d-bis writes the symlink (per bassclef-upstream#925).
+Without this symlink, the import resolves only through `additionalDirectories`.
+If that path breaks — rename, delete, corporate laptop with no sibling — the
+import silently no-ops. The symlink closes that gap.
+
+Bassclef updates the file via release. The adopter's CLAUDE.md stays
+adopter-owned outside the import line.
+
+```markdown
+# [repo-name]
+
+@.claude/bassclef-orientation.md
+
+## What this repo is
+
+[One-paragraph description]
+
+## Substrate
+
+Inherits bassclef substrate via `--add-dir ../bassclef` (desktop) and
+S3 tarball sync (mobile). The `@.claude/bassclef-orientation.md` import
+above auto-loads the substrate discipline (gates, luminaries, tier ladder,
+what-NOT-to-do). For the upstream role declaration, see
+`~/src/sunj-labs/bassclef/CLAUDE.md`.
+
+## Stack
+
+[Framework, language, key dependencies — or "documentation only"]
+
+## Current state
+
+[Phase, active iteration, any context a fresh session needs]
+```
+
+##### 3.2 Create the starter docs/whereami.md
+
+```bash
+mkdir -p docs
+cp ~/src/sunj-labs/bassclef/templates/whereami-template.md \
+   docs/whereami.md
+```
+
+Operator fills in phase + iteration section. If repo is fresh,
+`phase: Inception` with `iteration_bet: none — new repo` is fine.
+
+#### Phase 3.5 — Optional: provision the deploy host + bootstrap secrets (bassclef#522)
+
+**Working directory: target repo.**
+
+After Phase 3 (docs stubs) lands the substrate config files, three opt-in
+flags chain follow-on skills inline so every new sunj-labs repo bootstraps
+in one dispatch instead of four manual steps. Without these flags, the
+operator runs the follow-on skills separately afterward (older pattern,
+still supported).
+
+##### Flag reference
+
+| Invocation | Behavior |
+|---|---|
+| `/onboard-repo` (no flag) | Phases 1–3 only. Interactive prompt at end: "Run /provision-deploy-host now? [Y/n/skip]" + same for /secrets-bootstrap. Skip-state persists per below. |
+| `/onboard-repo --with-deploy-host` | Phases 1–3, then dispatches `/provision-deploy-host` inline (operator-confirms before AWS calls). Skips the interactive prompt for deploy-host. |
+| `/onboard-repo --with-secrets` | Phases 1–3, then dispatches `/secrets-bootstrap` inline (audits + bootstraps env per substrate.secrets.md). Skips the interactive prompt for secrets. |
+| `/onboard-repo --full` | All of the above — substrate scaffolded + Amplify host provisioned + secrets audited in one dispatch. Recommended for new sunj-labs repos. |
+| `/onboard-repo --greenfield-from-intent "<intent>"` | Cold-adopter demo path. Skips Path A entirely and runs Path B — empty directory in, full artifact chain on disk plus localhost gallery URL out. No GitHub repo gets created. No vendor accounts needed. Uses the LLM your Claude Code session provides. For the extended path (deploy mocks to a configured subdomain plus chain to `/build` plus `/launch-preview`), finish Path A first to wire vendor bindings, then dispatch `/launch --voice-input` without `--local`. See `docs/iteration-bets/2026-05-12-phase-v-hey-alexa-mvd.md` and bassclef#923 / PR #924 for the local-mode building block. |
+
+##### Tier gate (bassclef#740 Task 1.2)
+
+Three of the flags above dispatch skills that ship at `tier: standard`.
+Lite adopters running the bassclef-lite tarball do not carry
+`/provision-deploy-host` or `/secrets-bootstrap`. Before dispatching
+`--with-deploy-host`, `--with-secrets`, or `--full`, resolve the
+adopter tier through `lib/tier-check.sh`:
+
+```bash
+source lib/tier-check.sh
+tier=$(resolve_adopter_tier)
+```
+
+The check reads `.claude/bassclef-configs.jsonc` `adopter.tier` field
+first. Falls back to skill probe — presence of `/provision-deploy-host`
+skill returns `standard`. Safe default is `standard`.
+
+Behavior per tier:
+
+| Invocation | tier=lite | tier=standard or pro |
+|---|---|---|
+| `/onboard-repo` (no flag) | Phases 1–3 run. Skip interactive prompts for /provision-deploy-host and /secrets-bootstrap. | Phases 1–3 + interactive prompts. |
+| `/onboard-repo --with-deploy-host` (lite adopter) | Print graceful upgrade message: "--with-deploy-host requires bassclef standard. Reason: /provision-deploy-host is a standard-tier skill. Upgrade path: install bassclef standard, or run Phases 1–3 without the flag and provision the deploy host manually later." Continue Phases 1–3 as if no flag was passed. | Phases 1–3 + `/provision-deploy-host` dispatched inline. |
+| `/onboard-repo --with-secrets` (lite adopter) | Print graceful upgrade message: "--with-secrets requires bassclef standard. Reason: /secrets-bootstrap is a standard-tier skill. Upgrade path: install bassclef standard, or run Phases 1–3 without the flag and manage secrets manually via substrate.secrets.md." Continue Phases 1–3. | Phases 1–3 + `/secrets-bootstrap` dispatched inline. |
+| `/onboard-repo --full` (lite adopter) | Print graceful upgrade message: "--full requires bassclef standard. Reason: /provision-deploy-host and /secrets-bootstrap are both standard-tier skills. Upgrade path: install bassclef standard." Continue Phases 1–3. | Phases 1–3 + both skills dispatched inline. |
+| `/onboard-repo --greenfield-from-intent` | Runs Path B via `/launch --local`. Lite-safe by design. | Same. |
+
+Per canvas 2026-07-19-bassclef-lite Q6 Option E — one SKILL.md file,
+same name in both tiers, body carries runtime tier awareness with
+graceful degrade.
+
+##### Interactive prompt (when no flag)
+
+After Phase 3 completes, agent surfaces follow-on prompts. Prompts are
+gated on artifact existence (bassclef#961) and the deploy-host prompt
+uses honest platform framing (bassclef#962):
+
+```bash
+# Check for substrate.secrets.md (bassclef#961) — silently skip the
+# secrets prompt if the manifest doesn't exist. No point prompting an
+# adopter to bootstrap secrets when they haven't declared any.
+HAS_SECRETS_MANIFEST=0
+if [ -f substrate.secrets.md ]; then
+  HAS_SECRETS_MANIFEST=1
+fi
+```
+
+Then surface (deploy-host always; secrets only when manifest present):
+
+```
+Substrate scaffolded. One or two follow-on steps remain before /launch
+runs cleanly end-to-end:
+
+1. /provision-deploy-host — provisions a preview deploy host. Tested
+   today with AWS Amplify; other platforms (Vercel, Netlify, Cloudflare
+   Pages, GCP, Azure) ship via adapter PRs. If you want a platform that
+   doesn't ship yet, file a ticket — or build the adapter (it's a single
+   shell script following `scripts/adapters/deploy/amplify.sh` as the
+   reference). The provision takes ~1-2h, mostly waiting. Required
+   before /launch can bind a subdomain on the chosen host. Skip if this
+   repo opts out of preview deployment (hosting_platform: none) or if
+   you want to provision later.
+
+2. /secrets-bootstrap — audits + bootstraps env credentials per
+   substrate.secrets.md. Required before /launch, /deploy-prod, or
+   /journal push. Skip if creds are already known-good.
+
+Run /provision-deploy-host now? [Y/n/skip]
+Run /secrets-bootstrap now? [Y/n/skip]
+```
+
+When `HAS_SECRETS_MANIFEST=0` (no substrate.secrets.md on disk), the
+agent OMITS step 2 entirely + the second prompt — no "(likely no-op)"
+hedge, no prompt asking the adopter to bootstrap secrets they haven't
+declared. The numbered list collapses to "One follow-on step remains".
+
+Each `Y` triggers the inline dispatch (operator-confirms any destructive
+substep — AWS calls, env writes). Each `n` defers to a later session.
+Each `skip` persists in `substrate.config.md` so re-running /onboard-repo
+on this repo doesn't re-prompt for that step.
+
+The deploy-host prompt wording matters: cold adopters reading it should
+understand bassclef's posture on multi-platform support without
+operator coaching. "Tested with AWS Amplify; other platforms via
+adapter PRs" reads as honest (we have one tested path + a clear
+contribution route) instead of overpromising. Filing a ticket for an
+unsupported platform is invited, not gated.
+
+##### Skip-state persistence
+
+When operator chooses `skip` (not `n`) for a follow-on step, the agent
+writes one of these fields to `substrate.config.md`:
+
+```yaml
+# === Onboarding follow-on skip state (bassclef#522) ===
+#
+# Set by /onboard-repo when the operator explicitly skips a follow-on
+# step. Re-runs of /onboard-repo do NOT re-prompt for skipped steps;
+# operator can dispatch the underlying skill directly when ready, or
+# unset the field to re-enable the prompt.
+onboarding_deploy_host_skipped: true   # set when operator answers 'skip'
+onboarding_secrets_skipped: true       # set when operator answers 'skip'
+```
+
+`n` (decline-this-time) does NOT persist — re-runs re-prompt because the
+operator didn't say skip-permanently.
+
+`Y` sets the per-platform provisioning indicator (e.g., `amplify_app_id`) on success. Chain pre-flight Check 6 (bassclef#523) reads that indicator when /launch dispatches. Without it, /launch BLOCKs with three-path remediation. The two flags pair well. `--with-deploy-host` pre-empts the BLOCK. The default flow lets the BLOCK surface the missing setup.
+
+##### Composes with
+
+| Skill | Role |
+|---|---|
+| `/provision-deploy-host` | Inline dispatch when `--with-deploy-host` or interactive `Y`. Populates `amplify_app_id` (or platform-equivalent indicator). |
+| `/secrets-bootstrap` | Inline dispatch when `--with-secrets` or interactive `Y`. Audits creds against `substrate.secrets.md`. |
+| `/bind-subdomain <subdomain>` | Separate dispatch — not chained from /onboard-repo (subdomain choice is repo-specific; no good default). Run after deploy host provisioned. |
+| `/launch` | First substantive dispatch after onboarding completes. Chain pre-flight Check 6 verifies the provisioning indicator before variant generation runs. |
+
+#### Phase 3.6 — Closing handoff (bassclef#964)
+
+After Phase 3 (and Phase 3.5 if any flag fired), Path A surfaces a
+closing handoff. Two templates — adopter-mode and operator-mode —
+mirror the same split documented at `.claude/skills/launch/SKILL.md`
+Phase 14b.
+
+##### Adopter-mode auto-chain (default when context signals cold-adopter)
+
+Cold-adopter signals: `/onboard-repo` was invoked from a fresh
+directory (no prior chronicle / no whereami / no iteration-goal), OR
+the `--greenfield-from-intent "<paragraph>"` flag was used. In either
+shape, the agent has a paragraph in hand (either from the flag or
+asked at Phase 1 as part of the "what is this repo for?" prompt).
+
+The adopter-mode handoff template re-uses that paragraph and offers
+the build:
+
+```
+Your repo is wired. Two things you can do next — pick one:
+
+1. Build something now. I'll take the paragraph you gave me earlier
+   ("<INTENT_PARAGRAPH>") and run /launch --local. About 4 minutes
+   later you'll have four clickable mock directions to pick from on
+   your phone or laptop. After you pick a direction, I'll write the
+   formal artifacts + the app code for that direction only (~15 min
+   total). You'll have a working local version to play with.
+
+2. Stop here and come back later. I'll save your spot. When you come
+   back, just open Claude Code in this repo and say "/launch --local"
+   to pick up where we left off.
+
+Build now? [Y/n]
+```
+
+`Y` triggers `/launch --local "<INTENT_PARAGRAPH>"` inline in the
+same session — no context switch, no second dispatch. `n` writes
+the paragraph to `docs/whereami.md` under "Pending intent" so the
+next session's `/sprint` surfaces it.
+
+Substitute `<INTENT_PARAGRAPH>` with the actual paragraph (from
+`--greenfield-from-intent` flag value OR from the Phase 1 "what is
+this repo for?" prompt — operator confirms it's still accurate before
+the auto-chain fires).
+
+The adopter-mode handoff **skips entirely**:
+- "Run /sprint to orient" — adopter has no work in flight to orient
+  to
+- "Run /whereami" — same
+- Bare command names (`/launch`) without the plain-English explanation
+  of what /launch produces
+
+##### Operator-mode handoff (non-cold-adopter context)
+
+This mode fires when cold-adopter signals are absent. Signals absent means: the repo has prior chronicles, whereami is populated, OR the operator passed `--no-auto-chain`. The agent uses this wording:
+
+```
+Your bassclef is ready.
+
+What landed this session:
+- Skills, rules, and hooks synced from bassclef
+- GitHub labels + branch protection set up
+- Session-start wiring wired
+
+Best single next move — try /sprint in a fresh session. It reads
+your current state and proposes the next work.
+
+Other useful next moves:
+- /whereami — current state in one glance
+- /launch <tier> "<paragraph>" — start a new feature; see /launch
+  SKILL.md for sizes + flags
+- /launch --local "<paragraph>" — same as above but writes artifacts
+  to disk + serves the gallery on localhost (no vendor accounts
+  needed)
+
+Run any of those in a fresh session.
+```
+
+Operator-mode keeps a hard break between onboard and build. Operators often onboard a repo as one task. They pick up build work later in a fresh session.
+
+##### Composes with
+
+| Skill | How it composes |
+|---|---|
+| `/launch --local` | Adopter-mode auto-chain dispatch. Inline in same session. |
+| `/sprint` | Operator-mode orientation skill. Surfaces "Pending intent" if `n` was chosen for the build-now prompt. |
+| `/whereami` | Same. |
+
+#### Phase 4 — Bassclef-side matrix PRs
+
+**Phase 4 retired under bassclef goal 2026-05-03-consumer-bassclef-sync-rollout WU-7.**
+
+Under thin-pointer architecture (Phase 2.1 + 2.4 above), the `bassclef-template-sync.yml` workflow is deleted (no more auto-PRs). The `bassclef-s3-publish.yml` URL-refresh matrix is unused by thin-pointer (no `.bassclef-url`); a follow-on issue tracks its retirement separately.
+
+**No matrix-PR step is needed for new consumers.** The thin-pointer dispatcher reads from `.bassclef-source.json` directly; bassclef's matrix list is no longer the source of truth for which consumers receive substrate updates — every consumer fetches HEAD on every session-start.
+
+Skip this phase entirely. Phase 5 (Verify) below validates that the consumer is correctly wired without any bassclef-side matrix change.
+
+#### Historical note
+
+Pre-2026-05-03, this phase added the new consumer to BOTH `bassclef-s3-publish.yml` and `bassclef-template-sync.yml` matrices. The 2026-04-18 lesson (#166 caught a one-of-two miss after #158) drove the bassclef-workflow-parity rule. With both workflows retired/unused under thin-pointer, the parity rule no longer applies to this surface.
+
+## Verify (acceptance)
+
+Acceptance differs per path.
+
+### Path A — verify everything's wired correctly (after Phases 1–3 + 3.5 if flagged)
+
+- [ ] `gh label list --repo "$REPO"` shows all 11 standard labels
+- [ ] `gh api repos/$REPO/branches/$DEFAULT_BRANCH/protection` returns 200
+- [ ] (If applicable) `gh api repos/$REPO/environments/prod` shows required_reviewers
+- [ ] `.claude/hooks/bassclef-sync.sh` is executable
+- [ ] `.claude/settings.json` validates as JSON
+- [ ] `substrate.config.md` has no `TODO:` markers (or operator approved deferring them)
+- [ ] `.bassclef-source.json` exists, validates against bassclef schema (`standards/bassclef-source/schemas/bassclef-source.schema.json`), references a valid `BASSCLEF_TOKEN` env var, and has an explicit `auto_sync` value (true OR false) set by the adopter at Phase 2.4 — silence is not deferral here
+- [ ] Running the sync hook produces no errors; banner shows `### BASSCLEF SUBSTRATE — SYNCED`; symlinks resolve
+- [ ] `CLAUDE.md` exists with at least a one-paragraph description
+- [ ] `docs/whereami.md` exists with phase + iteration filled in
+- [ ] **(Retired)** ~~Bassclef PR opened with both workflow matrices updated~~ — Phase 4 retired under bassclef goal 2026-05-03 WU-7
+- [ ] Test session in target repo: `claude` → SessionStart hook fires → no BLOCKED items from missing substrate
+
+### Path B acceptance — after Phases B.1–B.5
+
+- [ ] Generated task list had at most 5 tasks (Phase B.1–B.5); no Path A phases queued
+- [ ] No `gh` calls fired during the dispatch
+- [ ] No `gh repo create`, no `gh api .../environments/prod`, no branch-protection writes
+- [ ] `.git/` exists with at least one commit
+- [ ] `.claude/hooks/bassclef-sync.sh` is executable
+- [ ] `.claude/settings.json` validates as JSON
+- [ ] `substrate.config.md` exists with `hosting_platform: none`
+- [ ] `CLAUDE.md` exists
+- [ ] `/launch --local --voice-input` was the final dispatch (not extended `/launch` and not `/build` and not `/launch-preview`)
+- [ ] `/launch` emitted a `localhost:80xx` URL pointing at the generated gallery
+- [ ] Operator opened the URL and saw the variants gallery
+
+## What NOT to do
+
+- **Do not** restore Phase 4 — the bassclef-template-sync.yml workflow is retired. Adding new consumers to a deleted matrix produces nothing.
+- **Do not** vendor `bassclef-sync.template.sh` directly — that was the pre-2026-05-03 pattern. The thin-pointer dispatcher reads `.bassclef-source.json` and fetches bassclef's CURRENT logic at fire-time. Vendoring reproduces the drift problem WU-7 retires.
+- **Do not** auto-merge the bassclef-side PR. Bassclef is the trust
+  root; every matrix change needs operator review.
+- **Do not** hardcode the presigned URL anywhere — read from
+  `.bassclef-url` at runtime.
+- **Do not** copy `.claude/settings.local.json` from another repo — it's
+  machine-local per-operator permission grants.
+- **Do not** commit secrets. The sync URL expires in ~7 days; don't
+  treat it as a secret, but don't commit long-lived tokens either.
+- **Do not** mix Path A and Path B in one dispatch. If the operator picked
+  Path B at the prereqs-missing menu, skip every Path A phase — don't
+  generate a task list that walks Phase 1.1 / 1.2 / 1.3 / 2.4 / 3.5 /
+  Phase 4. The whole point of Path B is the ≤5-step task list ending
+  in `/launch --local --voice-input`. Any Path A task that leaks into a
+  Path B run is the bassclef#934 regression.
+- **Do not** chain `/build` or `/launch-preview` after Path B's final
+  dispatch. Path B's deliverable is the localhost URL `/launch --local`
+  emits; the extended chain belongs to operators with vendor bindings.
+
+## Relationship to other skills
+
+- **`/autonomous start`** — runs AFTER `/onboard-repo` to set up iteration
+  scaffolding. `/onboard-repo` does the one-time wiring; `/autonomous
+  start` does the per-iteration setup.
+- **`/substrate-check`** — validates substrate wiring AFTER onboarding.
+  Run it as a post-flight check.
+- **`/promote`** — once onboarded, the new repo can file
+  `bassclef-evolution` issues. The labels bootstrapped in Phase 1.1
+  make them scannable.
+
+## Source
+
+Ritual observed 4x on 2026-04-17: four consumer repos (refresh). Each took ~15 minutes by hand.
+Codified here so the fifth, sixth, and nth take ~3 minutes.
+
+Closes bassclef #164.
+
+Path B added 2026-06-13. Cold-adopter smoke test on `new-recipe-test`
+2026-06-13 01:30am showed PR #931's edit to the flag-row description
+was cosmetic — `--greenfield-from-intent` still queued 12 standard
+onboarding tasks because the Procedure was monolithic. Refactor splits
+Procedure into Path A (standard, unchanged) and Path B (≤5 steps, no
+GitHub-remote operations, ends in `/launch --local --voice-input`).
+Closes bassclef#934.
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.