@thebassclef/lite 1.0.3 → 1.1.0

package/dist/lite/standards/bash-hook-safety.md

@@ -0,0 +1,246 @@
+---
+tier: lite
+description: "This standard codifies the defensive coding discipline for bassclef's bash hooks (.claude/hooks/.sh) + supporting bash scripts (scripts/.sh, lib/*.sh)."
+---
+
+# Bash Hook Safety Standard
+
+This standard codifies the defensive coding discipline for bassclef's bash hooks (`.claude/hooks/*.sh`) + supporting bash scripts (`scripts/*.sh`, `lib/*.sh`). It is the bash-specific instantiation of `standards/code-safety-principles.md`.
+
+## Why this standard exists
+
+Bassclef's hooks are bash scripts that fire on every tool call. They sit between the operator's intent and every Edit / Write / Bash invocation. A bug in a hook is amplified: every session in every consumer repo runs the hook on every tool call. Three months of substrate-evolution surfaced four same-shape failures (bassclef#1027, #1054, #1058, #1060) — all in bash code, all caught after PR open, all preventable by hooks at the moment of failure.
+
+The existing `.claude/rules/security.md` is scoped to web-application source files (`.ts`, `.tsx`, `.json`, `.env`, `Dockerfile`). It does not cover `.sh`. This standard closes that gap with hook-specific discipline anchored to Saltzer & Schroeder's 8 principles per `@luminary saltzer-schroeder`.
+
+## Anchors
+
+- `@luminary saltzer-schroeder` — the 8 protection-mechanism principles this standard instantiates
+- `@luminary john-ousterhout` — Deep modules + define-errors-out-of-existence framing for hook interface design
+- `@luminary kent-beck` — TDD discipline for hooks (Tier 0 per `.claude/rules/testing-tier-config.md`)
+- `standards/code-safety-principles.md` — language-agnostic principles this standard instantiates for bash
+
+## The seven disciplines
+
+### 1. Strict mode at the top
+
+Every bash hook + script starts with:
+
+```bash
+#!/bin/bash
+set -euo pipefail
+```
+
+- `-e` exits on any command failure
+- `-u` exits on undefined variable use
+- `-o pipefail` makes pipelines fail if any stage fails (default is "last stage's exit code only")
+
+INSTEAD of "I'll handle errors explicitly where they matter": strict mode makes errors loud by default. Explicit error handling overrides apply per-command via `command || true` or `command 2>/dev/null` with intent.
+
+**Why mandatory**: bash's default behavior is "continue on error, use the empty string for undefined variables." Bassclef's hooks run in environments where silent failure causes incorrect downstream state. PR #1054 demonstrated this: `log()` function's quiet-mode toggle behavior depended on an unset variable being treated as false; strict mode would have surfaced the bug at write-time.
+
+### 2. Quote every variable expansion
+
+Every `$var` or `${var}` reference inside a string context gets double-quoted:
+
+```bash
+# Correct
+file_path="$1"
+if [[ -f "$file_path" ]]; then
+  cat "$file_path"
+fi
+
+# Wrong — word-splits on spaces; glob-expands; breaks on empty
+if [[ -f $1 ]]; then
+  cat $1
+fi
+```
+
+INSTEAD of "I know this variable will never contain a space": quote universally. The cost of consistent quoting is zero; the cost of one missed quote in a path with a space is silent corruption.
+
+**Exception**: `local` declarations of arrays + variables that intentionally word-split (rare; document with an inline comment).
+
+### 3. `local` in functions
+
+Every variable declared inside a function uses `local`:
+
+```bash
+parse_config() {
+  local config_path="$1"
+  local mode="${2:-default}"
+  # ...
+}
+```
+
+INSTEAD of relying on bash's default of global scope: `local` keeps function-internal state inside the function. A function that pollutes parent scope is a defect waiting to surface — the bug appears when a different caller reuses the same variable name.
+
+### 4. Trap EXIT for cleanup
+
+Hooks that create temporary files, lock files, or background processes register a trap for cleanup:
+
+```bash
+TMP_DIR=$(mktemp -d)
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+# ... use $TMP_DIR ...
+# Cleanup happens automatically on any exit path
+```
+
+INSTEAD of "I'll clean up at the end of the happy path": cleanup at every exit path including error paths and SIGINT. `trap '...' EXIT` runs the cleanup regardless of how the script exits.
+
+For hooks specifically: clean up `/tmp` markers, release `flock`s, kill background `tee`s.
+
+### 5. Explicit return codes
+
+Hook exit codes carry meaning. Bassclef's hook protocol:
+
+- `0` — allow the tool call (default)
+- `1` — generic non-blocking failure (usually a bug in the hook itself; logged but doesn't block)
+- `2` — BLOCK the tool call (the operator-facing surface)
+- `>2` — reserved; treat as `1`
+
+Every hook ends with explicit `exit 0` (or `exit 2` on block). Relying on bash's "exit code of last command" default produces silent breakage when refactors reorder statements.
+INSTEAD of implicit "last-command exit code": explicit `exit N` at every termination point. Hook readers should see the exit value next to the BLOCK decision.
+
+### 6. Glob-tolerance via fallthrough
+
+Bash's `for f in pattern/*` fails silently when the pattern matches nothing — the loop body runs once with the literal pattern string. The shape that tolerates empty match:
+
+```bash
+shopt -s nullglob   # empty match = empty loop, not literal pattern
+
+for f in "$dir"/*.json; do
+  process "$f"
+done
+
+shopt -u nullglob   # restore default
+```
+
+INSTEAD of assuming a glob always matches: `nullglob` makes empty-match an empty loop. The hook handles "no files" naturally.
+
+For one-off patterns: `[[ ${#files[@]} -gt 0 ]]` after assigning to an array via `files=("$dir"/*.json)`.
+
+### 7. Audit emission at every exit path
+
+Every hook emits a trace record before exit:
+
+```bash
+source "$(dirname "$0")/../lib/trace-helper.sh"
+
+# ... hook body ...
+
+trace_record "hook-name" "decision" "context"
+exit 0
+```
+
+INSTEAD of audit-only-on-block: audit on allow + block + override usage + skip path. Post-incident reconstruction needs the full trace.
+
+## Common idioms
+
+### `find | head` under `set -euo pipefail` — SIGPIPE kills the script
+
+Under `set -euo pipefail`, piping `find` into `head -N` can silently kill the script when `find` produces more than N results. `head` closes stdin after N lines, `find` receives SIGPIPE from the closed pipe, `find` exits 141, and `pipefail` promotes 141 to the pipeline exit code. `set -e` then kills the script silently.
+
+Anti-pattern:
+
+```bash
+set -euo pipefail
+broken=$(find . -type l \! -exec test -e {} \; -print 2>/dev/null | head -10)
+# ^ script may exit here with no error output when find produces >10 results
+```
+
+INSTEAD — Option 5d (preferred): bash-native array truncation. No pipe means no SIGPIPE.
+
+```bash
+set -euo pipefail
+readarray -t all_broken < <(find . -type l \! -exec test -e {} \; -print 2>/dev/null)
+broken="$(printf '%s\n' "${all_broken[@]:0:10}")"
+```
+
+Three alternatives, each with tradeoffs:
+
+- **SIGPIPE catch** — `find ... 2>/dev/null | head -10 || true`. Swallows all pipeline errors including real ones; less specific than the SIGPIPE-only class.
+- **No-pipe restructure** — `find ... -print | while read; do ... done` with an explicit counter break. More lines; keeps structural-code style.
+- **Fallthrough with `|| true`** — cheapest to write; hides every non-zero pipeline exit; least safe under production loads.
+
+Option 5d preserves the structural read shape AND removes the SIGPIPE vector at the source. Strictly stronger error propagation than SIGPIPE catch — the pipe never exists, so no pipe error class can fire.
+
+Anchors:
+
+- `@luminary linus-torvalds` — adopter contract on observable script behavior; silent-exit is worse than loud-fail
+- `@luminary michael-feathers` — characterization test pins the FAIL contract (find-produces-N-plus-1 case) before the fix ships
+
+Per sunj-labs/bassclef-upstream#912. Cure 4 shipped inside the #901 install-corrupts-tree epic; PR #892 carries the exemplar. See the ticket body for the second-AI consultation write-up + the linus lens shift from Option 1 (SIGPIPE catch) to Option 5d.
+
+## The Saltzer & Schroeder stack-translation
+
+This standard's seven disciplines instantiate Saltzer & Schroeder's 8 principles (per `@luminary saltzer-schroeder` stack-translation table):
+
+| Saltzer & Schroeder principle | Bash discipline |
+|---|---|
+| Economy of mechanism | Hook body ≤200 lines; helpers in `lib/*.sh` |
+| Fail-safe defaults | Strict mode `set -euo pipefail`; default `exit 2` on uncertainty |
+| Complete mediation | PreToolUse fires on every matching call |
+| Open design | Triggers documented in `docs/hooks-index.md`; BLOCK banners name the read path |
+| Separation of privilege | Destructive hooks require multiple independent signals |
+| Least privilege | `cd` only when needed; scope git/file ops to specific paths |
+| Least common mechanism | Per-hook trace; per-hook test; no global state between hooks |
+| Psychological acceptability | `SKIP_<HOOK>=1` per-call override; logged via trace-helper |
+
+## Shellcheck
+
+Every bash hook + script passes `shellcheck` (current version). Tier 0 strict-TDD discipline per `.claude/rules/testing-tier-config.md` extends to shellcheck: an edit that introduces a shellcheck finding fails CI per Phase X-4's shellcheck workflow.
+
+**Local install**:
+
+| OS | Command |
+|---|---|
+| macOS | `brew install shellcheck` |
+| Ubuntu/Debian | `apt install shellcheck` |
+| Fedora | `dnf install ShellCheck` |
+| Arch | `pacman -S shellcheck` |
+| Container builds | Add `shellcheck` to the base image |
+
+**Local run**:
+
+```bash
+shellcheck .claude/hooks/*.sh scripts/*.sh lib/*.sh
+```
+
+**Phase X-4** ships the CI workflow that runs shellcheck on every PR + a baseline allowlist (`.claude/hooks/shellcheck-allowlist.txt`) with 60-day grace through 2026-08-17 for existing findings.
+
+## What this standard does NOT do
+
+- Does not cover language interop (bash calling Python, Python calling bash) — handle at the boundary
+- Does not specify which utilities to use (`gh` vs `curl` vs `jq` vs `yq`) — that is a stack-choice question
+- Does not cover bash 4+ features absent from macOS's default install (`${var^^}` uppercase conversion, associative arrays) — bash 3.2 compatibility is the baseline.
+  INSTEAD of using a bash 4+ feature implicitly: opt in via explicit shebang line (`#!/usr/bin/env bash` with version check) or fallback shape.
+
+## When this standard fires
+
+| Surface | Check |
+|---|---|
+| New hook in `.claude/hooks/` | All 7 disciplines + shellcheck-clean + sibling test (Tier 0) |
+| New script in `scripts/` | All 7 disciplines + shellcheck-clean (Tier 1) |
+| Edit to existing hook | Same — Phase A's testing-tier hook BLOCKs without test mtime ≤ source mtime |
+| Code review on PR touching `.sh` | Reviewer applies the 7 disciplines |
+| `/security-review` skill invocation | Skill cites this standard for any `.sh` change |
+
+## Refs
+
+- `@luminary saltzer-schroeder` — anchor
+- `@luminary john-ousterhout` — Deep modules framing for hook interface design
+- `@luminary kent-beck` — TDD anchor; Tier 0 strict-TDD discipline applies
+- `standards/code-safety-principles.md` — language-agnostic principles this standard instantiates
+- `.claude/rules/destructive-operations.md` — agent self-assessment companion
+- `.claude/rules/security.md` — web-layer rule (`.ts/.tsx/.json/.env/Dockerfile` scope); this standard extends to bash
+- `.claude/rules/testing-tier-config.md` — Tier 0 strict-TDD discipline for hooks
+- `.claude/rules/defensive-bash.md` — companion methodology rule (auto-loaded; points here)
+- `.github/workflows/shellcheck.yml` (Phase X-4) — CI enforcement
+- bassclef#1054 — `log()` quiet-mode bug (strict-mode would have caught at write-time)
+- bassclef#1058 — auto-save scope hole (fail-safe-defaults + least-privilege violation)
+- docs/iteration-bets/2026-06-17a-secure-coding-foundations-longrun.md — goal authoring this standard
+
+## Retirement
+
+This standard retires only if bassclef migrates off bash for its hook implementation language (e.g., adopting Python or Go for hooks). The 7 disciplines themselves remain valid; the language-specific instantiation changes.

package/dist/lite/standards/bassclef-configs-schema.md

@@ -0,0 +1,232 @@
+---
+tier: lite
+description: .claude/bassclef-configs.jsonc is the unified configuration discovery surface for bassclef adoption.
+---
+
+# bassclef-configs Schema
+
+`.claude/bassclef-configs.jsonc` is the **unified configuration discovery surface** for bassclef adoption. One file. Read the inline comments. Edit the values.
+
+## Why this exists
+
+Before this standard, adopter configuration lived in four places:
+
+| Surface | What it holds | Adopter discovery cost |
+|---|---|---|
+| `.claude/settings.json` | hooks, permissions, environment | high (Claude Code platform format) |
+| `substrate.config.md` | resource references (Doc IDs, URLs) | medium (markdown frontmatter) |
+| `.claude/agents/<role>.md` frontmatter | per-agent `model_tier` | low (already structured) |
+| Hook env vars | per-session disables | high (no central registry) |
+
+The new file consolidates substrate-level configuration into one surface. `substrate.config.md` keeps resource references (its existing job). `.claude/bassclef-configs.jsonc` holds the bassclef-adoption settings.
+
+## File format — JSONC
+
+JSON with comments. Standard tooling supports it directly (VS Code, IntelliJ, most editors). Strict JSON parsers strip comments first:
+
+```bash
+perl -pe 's,^\s*//.*$,,; s,/\*.*?\*/,,g' .claude/bassclef-configs.jsonc | jq .
+```
+
+The hook layer (`bassclef-sync.sh` and others reading the file) handles the comment strip before passing to `jq`.
+
+## Three-question comment discipline
+
+Every setting carries a comment block answering three questions:
+
+1. **What does this setting do** — plain English, /kiss-passed for grade-11 readability. One paragraph max.
+2. **What's the default + why** — adopter vs operator distinction where audiences diverge. State both defaults inline.
+3. **Which substrate component does this control** — file path or skill name or ADR reference. Adopter can read deeper.
+
+Optional fourth line:
+
+4. **Schema reference** — bassclef ticket or ADR governing the setting.
+
+## Concrete shape
+
+```jsonc
+{
+  // Whether bassclef's substrate (skills, rules, hooks, agents) syncs from
+  // the upstream bassclef repo to your local .claude/ directory at session start.
+  // Adopter default: false (opt-in trust posture; you control when updates land).
+  // Operator default: true (substrate maintainers want always-latest).
+  // Pairs with: .claude/hooks/bassclef-sync.sh
+  // Schema reference: bassclef#900 sync opt-in default
+  "sync": { "enabled": true },
+
+  // Per-agent LLM model routing. Maps agent role to capability tier.
+  // Pairs with: .claude/agents/<role>.md frontmatter (model_tier field)
+  // Schema reference: bassclef#873 model_tier dogfood
+  "model_tier": { "Builder": "balanced" },
+
+  // Adopter plan tier. Caps concurrent parallel agent dispatch per Anthropic plan limits.
+  // Pairs with: .claude/skills/longrun/SKILL.md parallel-dispatch logic
+  // Schema reference: bassclef#877 parallel-dispatch ceiling per adopter plan tier
+  "plan_tier": "tier-1"
+}
+```
+
+## Adopter vs operator default distinction
+
+Two roles, two defaults. The mechanism for runtime resolution:
+
+| Context | File state | Defaults applied |
+|---|---|---|
+| Operator (bassclef's own repo) | file present with operator-default values | `sync.enabled: true`, etc. |
+| Adopter clone | file absent OR present with adopter defaults | `sync.enabled: false`, etc. |
+| Adopter clone after `/onboard-repo` | file written by skill with adopter defaults | adopter defaults applied |
+
+Adopter-mode detection (basic version): hook checks if current repo's `origin` remote URL is `sunj-labs/bassclef`. If yes → operator. If no → adopter.
+
+Per-setting runtime resolution detail in each setting's comment block. Hook layer (`bassclef-sync.sh` and others) implements the resolution.
+
+## What this is NOT
+
+- **Not a replacement for `settings.json`** — `.claude/settings.json` stays as the Claude Code platform format (hooks array, permissions, environment). This new file is bassclef's adoption layer above it.
+- **Not a replacement for `substrate.config.md`** — `substrate.config.md` stays as the resource-reference single source (Doc IDs, URLs, env-var names). This new file holds bassclef-adoption settings.
+- **JSON-Schema-validated as of bassclef#1135** — Shape contract at `standards/state-spine/schemas/bassclef-configs.schema.json`. Tier 0 strict-TDD tests under `standards/state-spine/schemas/tests/bassclef-configs.test.sh`. Per-block `additionalProperties:false` catches typos; root-level `additionalProperties:true` keeps the file forward-compat for downstream T3-T24 work.
+
+## Adopter-default vs operator-default per field
+
+Adopters and operators get different defaults from the same surface. `/onboard-repo` writes the adopter-default seed; bassclef's own repo ships operator-default values. Per-field summary:
+
+| Block / field | Adopter default | Operator default | Why the difference |
+|---|---|---|---|
+| `sync.enabled` | `false` | `true` | Adopters control update cadence; operators want always-latest |
+| `model_tier.Builder` | `balanced` | `balanced` | Code quality matters everywhere |
+| `model_tier.<reviewer-class>` | `cheap-fast` | `cheap-fast` | Checklist work; Haiku handles it cleanly |
+| `model_tier.Shaper` | `capable` | `capable` | Problem framing is highest-leverage; Opus earns its keep |
+| `plan_tier` | `tier-1` | `tier-1` | Single-agent serial is the safe default for both |
+| `prose_discipline.kiss_words_turn_prose` | `true` | `true` | Plain prose helps everyone reading agent output |
+| `testing.global_floor` | `1` (WARN) | `1` (WARN) | Both audiences want the test-with prompt by default |
+| `testing.path_matchers` | `[]` | seed list (hooks Tier 0, etc.) | Operators carry bassclef's substrate-internal matchers; adopters add their own at `/onboard-repo` Phase 2.x |
+| `tech_stack` | declared at onboarding | reference operator stack | Per-adopter; bassclef declares its own as reference |
+| `longrun.orchestrator_merge.mode` | `operator-gated` | `operator-gated` | Safest mode wins by default for both |
+| `hook_chain.<hook>` | `true` for foundation hooks; explicit opt-in for new layers | `true` for everything substrate ships | Adopters layer in disciplines; operators run the full chain |
+| `discipline_layers.<layer>` | `"advisory"` for new disciplines | `true` / strict for shipped disciplines | Adopters get the easier on-ramp; operators dogfood the strict path |
+| `security_scanning.stack` | auto-detected at `/onboard-repo` Phase 2.5 | per repo | Both pick a stack; off by default until adopter confirms |
+| `security_scanning.block_on_high_severity` | `true` | `true` | Production-bound work blocks on highs; early exploratory opts down |
+
+Adopter-mode detection (basic version): hook checks if the current repo's `origin` remote URL points at `sunj-labs/bassclef`. If yes → operator. If no → adopter. Per-setting comments in the JSONC file restate the distinction inline for adopter discoverability.
+
+## When to add a setting
+
+A new setting belongs in `bassclef-configs.jsonc` when:
+
+1. It controls bassclef's adoption behavior (not Claude Code platform behavior — that's `settings.json`)
+2. Multiple hooks or skills read it (not just one — single-hook settings stay in hook env vars)
+3. It has a clear three-question comment block answer
+4. It pairs with a substrate component the adopter can read
+
+If the setting fails any of those, file an issue first and discuss before adding.
+
+## Migration path
+
+Settings currently scattered across other surfaces migrate into `bassclef-configs.jsonc` over time:
+
+| Setting | Current home | Migration target | Tracking |
+|---|---|---|---|
+| Per-agent `model_tier` | `.claude/agents/<role>.md` frontmatter | `model_tier` block in bassclef-configs | bassclef#873 → afternoon work |
+| Sync enabled / disabled | `.no-bassclef-sync` sentinel + env vars | `sync.enabled` block | bassclef#900 |
+| Parallel-dispatch ceiling | not yet implemented | `plan_tier` block | bassclef#877 |
+| Testing tier per path | not yet implemented (honor-system `.claude/rules/testing.md`) | `testing` block (global_floor + path_matchers) | bassclef#1037 |
+| Hook enable flags | scattered across per-hook env vars | `hook_chain` block (named boolean fields, forward-compat) | bassclef#1135 (T2 seed; T3-T24 wire individual hooks to read) |
+| Discipline enable / mode | scattered across per-rule env vars | `discipline_layers` block (bool or "advisory"/"strict"/"off" mode) | bassclef#1135 (T2 seed) |
+| Security scanner adapter | inline at `/onboard-repo` Phase 2.5 | `security_scanning` block (stack + additional_scanners + block_on_high_severity) | bet 2026-06-17a Phase Y + bassclef#1135 |
+
+Migration preserves backward compatibility — old surfaces continue working during the migration window; the new file becomes the source of truth as each setting migrates.
+
+## Composes with
+
+- `standards/substrate-config-schema.md` — sibling for resource references (Doc IDs, URLs)
+- `.claude/bassclef-configs.jsonc` — the file itself (this standard's primary subject)
+- `standards/state-spine/schemas/bassclef-configs.schema.json` — JSON Schema shape contract (bassclef#1135 WU-4)
+- `.claude/skills/onboard-repo/SKILL.md` — writes adopter-default file on first install
+- `.claude/hooks/bassclef-sync.sh` — first consumer (per bassclef#900)
+- `.claude/rules/testing-tier-config.md` — owns the `testing` section reasoning (bassclef#1037)
+- `.claude/hooks/testing-tier-enforce.sh` — testing-section consumer (bassclef#1037 WU-3)
+- `standards/state-spine/schemas/testing-tier-overrides.schema.json` — per-file override entries that take precedence over the testing.path_matchers array (bassclef#1037)
+- `standards/security-scanner-adapter.md` — owns the `security_scanning` section reasoning (bet 2026-06-17a Phase Y); supplies per-stack scanner default sets
+- `config/security-scanners/<stack>.yml` — per-stack reference workflows (Phase Y-3); adopter copies + customizes
+
+## Settings reference
+
+### `testing` (bassclef#1037)
+
+Per-path testing-tier enforcement. Four tiers — 0 strict TDD / 1 test-with / 2 smoke / 3 manual verify — pick by blast radius. Most-specific path-matcher wins; `global_floor` applies when no entry matches.
+
+| Field | Type | Default (adopter) | Default (operator) | What it does |
+|---|---|---|---|---|
+| `global_floor` | integer 0-3 | 1 | 1 | Tier applied when no path_matcher matches. Tier 1 (WARN on missing test) is the cautious default — adopters add stricter tiers per surface as discipline matures. |
+| `path_matchers` | array of `{match, tier}` | `[]` | seeded list (hooks Tier 0, schemas Tier 0, scripts Tier 1, narrative Tier 3) | Per-path tier overrides. Array order is most-specific to least-specific; first match wins. Glob patterns supported via shell-glob matching. |
+
+Per-file overrides live in `state/testing-tier-overrides.jsonl` (append-only JSONL; schema at `standards/state-spine/schemas/testing-tier-overrides.schema.json`). The hook walks overrides first, then path_matchers, then global_floor. Overrides carry a timestamp and optional expiry to time-bound relief.
+
+The rule `.claude/rules/testing-tier-config.md` carries the full reasoning, per-tier semantics, and override discipline. The hook `.claude/hooks/testing-tier-enforce.sh` (WU-3) is the mechanical enforcement layer.
+
+### `security_scanning` (bassclef bet 2026-06-17a Phase Y)
+
+Per-stack security scanner adapter configuration. Adopter declares the stack; bassclef-supplied reference workflows use the default scanner set from `standards/security-scanner-adapter.md` stack reference matrix.
+
+| Field | Type | Default (adopter) | Default (operator) | What it does |
+|---|---|---|---|---|
+| `stack` | string OR null | `null` | adopter-set when bassclef onboards | Stack name from the matrix in `standards/security-scanner-adapter.md` — one of `node-typescript`, `python`, `ruby`, `java`, `go`, `custom`, or `null` (OFF). `null` = no scanners configured; `/onboard-repo` prompts at next session. |
+| `additional_scanners` | array of strings | `[]` | `[]` | Names of additional scanners beyond the stack defaults (e.g., commercial tools like `snyk`, `veracode`). Names are advisory; adopter writes their own workflow steps. |
+| `block_on_high_severity` | boolean | `true` | `true` | Block CI on high-severity findings (workflow exits non-zero). When `false`, findings post as advisory comments only. Recommended `true` for production-bound work. |
+
+Stack-gated opt-in: the reference workflow's `if: hashFiles('.claude/bassclef-configs.jsonc') == '' || fromJSON(...).security_scanning.stack == null` skips the entire job when `stack` is null. New adopters get OFF-by-default; explicit stack choice activates scanners.
+
+The block name `security_scanning` is intentionally independent of `.claude/bassclef-configs.jsonc`'s file name. If the file is later renamed (per the deferred bassclef rename event under ADR-022), this block's semantics persist; only the file path changes.
+
+The standard `standards/security-scanner-adapter.md` carries the per-stack default scanner set + adapter pattern. The skill `/onboard-repo` (Phase Y-4) writes the stack value at install time.
+
+### `longrun` (bassclef#1064)
+
+Configures /longrun's autonomous PR merge cadence. Two modes, with hard ceilings the mode cannot relax. Pairs with `.claude/skills/longrun/SKILL.md` (procedure reads this block) and `.claude/rules/guardrails.md` (hard ceilings).
+
+| Field | Type | Default (adopter) | Default (operator) | What it does |
+|---|---|---|---|---|
+| `orchestrator_merge.mode` | string enum | `operator-gated` | `operator-gated` | `operator-gated` — every PR opened during /longrun pauses for operator review + merge (safest; default for adopters learning bassclef). `agent-merges-within-scope` — orchestrator merges PRs autonomously when the change is within the goal's declared scope AND does not hit a hard ceiling (operator-sleep mode; for solo operators with full-time jobs running /longrun overnight). |
+| `orchestrator_merge.hard_ceilings` | array of strings | `[auth, schema, security, prod-deploy, blast-radius-floor]` | `[auth, schema, security, prod-deploy, blast-radius-floor]` | Non-overridable list of change categories that ALWAYS pause for operator regardless of mode. Operators can ADD entries; the SKILL refuses removals. Hard ceilings are the guardrails bassclef#1064 made explicit so adopters see the trade-off. |
+
+Three motivations baked into the schema:
+
+1. **Operator-sleep mode** — solo operators with full-time jobs run /longrun overnight; orchestrator-merge mode keeps the queue moving while they sleep. Validated 2026-06-17 (17 PRs / 64 min via verbal authorization during Phase B); bassclef#1064 codifies the configuration surface so adopters opt in per-/longrun.
+2. **Discipline-teaching surface** — the toggle exposes WHY orchestrator-merge is constrained. Pair the surface with a teaching panel mapping hard ceilings to bassclef's discipline principles. Adopters learn what bassclef considers safe-to-automate vs requires-human.
+3. **Trust gradient** — adopters new to bassclef pick `operator-gated` while learning the substrate; adopters deep in bassclef pick `agent-merges-within-scope` for velocity. Same primitive serves both.
+
+Backwards-compatible: missing `longrun` block defaults to `operator-gated` (per /longrun SKILL.md procedure). Existing /longrun invocations continue working without config changes.
+
+Per-PR override syntax (a single PR pauses regardless of mode) is out of scope for V1; the hard-ceiling list covers the safety case. Operator can name a one-off pause via verbal interjection ("pause on this one").
+
+### `wiki_sync` (bassclef#1265)
+
+Configures whether the adopter's repo runs the bassclef-docs-sync workflow that syncs allowlisted docs to the GitHub Wiki on push-to-main. Pairs with `.claude/skills/docs-sync/SKILL.md` (reads this block at runtime), `.claude/rules/session-artifacts.md` § Wiki-as-we-go discipline (methodology rule), `presence/install/bassclef-docs-sync.template.yml` (the workflow adopters vendor), `presence/install/docs-sync-allowlist.template.md` (the allowlist seed).
+
+| Field | Type | Default (adopter) | Default (operator) | What it does |
+|---|---|---|---|---|
+| `enabled` | boolean | `false` | `false` | When `true`, /onboard-repo Phase 2.3.8 surfaces the vendoring stub. Phase 2 of bet 2026-06-20b ships full auto-vendoring of the workflow + allowlist templates. Bassclef itself runs the workflow directly (not via template) because it's the bassclef source; the operator-default `false` is correct for bassclef's own repo. |
+| `target_wiki_repo` | string | `""` | `""` | Override target — owner/repo of the GitHub wiki to sync to. Empty string defaults to current repo's wiki (the `.wiki` suffix on the repo URL). Most adopters leave empty. |
+| `allowlist_path` | string | `standards/docs-sync-allowlist.md` | `standards/docs-sync-allowlist.md` | Adopter-side path to the docs-sync allowlist. Used by /docs-sync skill to locate the operator-readable contract. |
+
+Three motivations:
+
+1. **Discipline-mechanism pairing** — `wiki-as-we-go` rule (bassclef#1208) propagates to adopters via `additionalDirectories` but the workflow that enforces it does not — it lives in bassclef's own `.github/` and its allowlist names bassclef paths. Adopters answering "yes" to the closeout question have nowhere for the mechanism to fire. This block lets them opt in.
+2. **Cold-adopter friction** — without this toggle + template, adopters who want wiki-sync have to hand-author the workflow + allowlist, multiplying the cost of adopting bassclef's documentation discipline.
+3. **Discoverability** — the toggle appears at /onboard-repo Phase 2.3.8 (Phase 1 stub today; full vendoring in Phase 2 of bet 2026-06-20b). Adopters see the option exists; they decide when to flip it.
+
+Backwards-compatible: missing `wiki_sync` block defaults to `enabled: false`; bassclef's existing workflow keeps running for bassclef-public docs.
+
+## Refs
+
+- bassclef#898 — adopter configuration discovery parent
+- bassclef#899 — this standard's parent ticket
+- bassclef#900 — sync opt-in default (first consumer)
+- bassclef#873 — model_tier dogfood (migrating into schema)
+- bassclef#877 — parallel-dispatch ceiling per plan tier
+- bassclef#643 — substrate.config.md → YAML schema (sibling discipline)
+- bassclef#1037 — testing-tier-config primitive (testing section + rule + hook)
+- bassclef#1064 — /longrun orchestrator-merge toggle (longrun section)
+- bassclef#1036 — Ousterhout luminary stub (sibling rule citation source)
+- bassclef#1265 — wiki-sync mechanism adopter inheritance (wiki_sync section)
+- bassclef#1208 — wiki-as-we-go discipline rule (methodology layer wiki_sync mechanizes)

package/dist/lite/standards/bassclef-evolution.md

@@ -0,0 +1,143 @@
+---
+tier: lite
+description: Bassclef evolves from three sources. Each source has a defined path to promotion. No standard enters bassclef without review.
+---
+
+# Bassclef Evolution Standard
+
+## Principle
+
+Bassclef evolves from three sources. Each source has a defined path
+to promotion. No standard enters bassclef without review.
+
+## Three Sources
+
+### 1. User-proposed (explicit)
+
+The operator identifies a pattern worth standardizing and invokes
+`/promote` in an app repo.
+
+**Path**: User runs `/promote` → issue created in app repo with
+`bassclef-evolution` label → bassclef session reviews → accept/defer/reject.
+
+**Examples**:
+- "This hook pattern solved a real problem, other repos should have it"
+- "I wrote a better diagnosis workflow, promote it"
+- "This skill works, make it bassclef"
+
+**Signal quality**: Highest. The operator saw the value firsthand.
+
+### 2. Hook-driven (automated detection)
+
+Hooks detect patterns that suggest bassclef should evolve:
+- Pre-build gate fires on a file type with no matching diagram check
+- Session-end finds a new artifact type being written consistently
+- Self-test discovers a skill requirement pattern across repos
+
+**Path**: Hook logs the observation to `docs/sdlc-traces/` → bassclef
+session-start hook aggregates traces → patterns with ≥3 occurrences
+surface as promotion candidates.
+
+**Examples**:
+- "pre-build-gate triggered for .py files but has no Python-specific
+  diagram loading — should bassclef support Python projects?"
+- "session-end wrote a new artifact type (design-token.json) in 3
+  consecutive sessions — should this be in the artifact chain?"
+
+**Signal quality**: Medium. Frequency ≠ importance, but repeated
+patterns are worth investigating.
+
+### 3. Agent-proposed (discovered during work)
+
+An agent working in an app repo discovers that a local pattern should
+be general. This happens during Construction when the Builder writes
+something that the sdlc-gates checkpoint flags.
+
+**Path**: Agent runs `/promote` (same as user-proposed, but agent-initiated)
+→ issue created with `bassclef-evolution` label + `agent-proposed` tag
+→ bassclef session reviews with extra scrutiny (agents over-promote).
+
+**Examples**:
+- Builder writes a hook in POA, sdlc-gates asks "Is this general?"
+- Architect writes an ADR pattern that could be a template
+- Reviewer flags a testing pattern that should be a standard
+
+**Signal quality**: Variable. Agents tend to over-generalize. Review
+with skepticism: "Would this actually help in a DIFFERENT repo?"
+
+## Ingestion Protocol (bassclef sessions)
+
+The bassclef session-start hook scans for `bassclef-evolution` issues
+across all child repos. During a bassclef session:
+
+### Triage
+
+For each promotion candidate:
+
+1. **Is it general?** Would it help in a repo we haven't built yet?
+   If it only makes sense for POA's domain, reject.
+
+2. **Does it conflict?** Does it contradict an existing standard, ADR,
+   or design principle? If yes, the conflict must be resolved — either
+   the new pattern supersedes the old (update the ADR) or it's rejected.
+
+3. **Is it bassclef-shaped?** Does it fit as a skill, rule, standard,
+   hook, or agent definition? Or is it application logic wearing a
+   governance hat?
+
+### Actions
+
+| Decision | Action | Issue |
+|----------|--------|-------|
+| Accept | Promote content to bassclef. Commit with `feat:` or `docs:`. | Close source issue |
+| Defer | Not ready — needs more evidence or refinement | Keep open, add rationale |
+| Reject | Not general enough, conflicts with existing standards, or app-specific | Close with explanation |
+
+### After acceptance
+
+1. Add the new content to bassclef (skill, rule, standard, etc.)
+2. Update CLAUDE.md counts if a new skill/standard was added
+3. Run `/substrate-check` to verify the substrate is still consistent
+4. Child repos pick up the change on next `boot-bassclef.sh` sync
+
+## Tracking
+
+The bassclef session-start hook outputs a "BASSCLEF EVOLUTION — PENDING
+PROMOTIONS" section showing all open `bassclef-evolution` issues across
+child repos. This ensures promotions are never silently ignored.
+
+Each child repo is registered in the session-start hook:
+```bash
+CHILD_REPOS="sunj-labs/poa"  # add new repos here
+```
+
+## What Triggers a Promotion Check
+
+Not just `.claude/` changes — any change that establishes a pattern
+other repos might need. The pre-commit hook flags these automatically.
+
+| Change type | Examples | Hook detects |
+|-------------|----------|-------------|
+| Substrate files | skills, rules, hooks, agents in `.claude/` | yes |
+| Settings | `settings.json`, model routing, hook config | yes |
+| Package scripts | `package.json` script additions or changes | yes |
+| Tooling config | `.eslintrc`, `tsconfig`, `.prettierrc`, `.env.example` | yes |
+| Workflow patterns | testing approaches, deployment scripts, seed patterns | no — agent judgment |
+
+Settings changes are the most commonly missed. When an app repo modifies
+agent behavior or hook configuration in `settings.json`, that's almost
+always a global decision. The hook flags it — don't dismiss the warning.
+
+When unsure: promote. It's cheaper to reject a promotion in bassclef
+than to rediscover the same pattern in a second repo.
+
+## Rules
+
+- Promotions always originate in the SOURCE repo, never directly on bassclef
+- App repos never need write access to bassclef
+- The `bassclef-evolution` label is the signal — use it consistently
+- Don't block app work on promotion decisions — log and move on
+- Agent-proposed promotions get extra scrutiny (agents over-generalize)
+- Hook-driven patterns need ≥3 occurrences before surfacing
+- User-proposed patterns can be promoted immediately if clearly general
+- When unsure whether a change is local or global → promote (default to global)