@thebassclef/lite 0.0.1 → 0.1.0

package/substrate/scripts/render-lite-manifest-doc.sh

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+# tier: lite
+# Render human-readable companion doc from lite-manifest.json.
+#
+# Reads lite-manifest.json at repo root by default; writes docs/lite-manifest.md.
+# The companion doc IS the human-readable projection of the machine-readable
+# manifest — same source of truth, two projections per Ousterhout deep-modules.
+#
+# Per bassclef-upstream#1020 Step 4. Session 2026-08-01d option b.
+#
+# Cures per pre-mortem risk ledger docs/risk-ledgers/2026-08-01c-lite-manifest.md:
+#   F3.4 — prominent version banner at top; every regeneration bumps timestamp
+#   F-b.N3 — anchor on schema file (stable path) not manifest file (may move)
+#
+# Usage:
+#   scripts/render-lite-manifest-doc.sh                    # reads root manifest, writes docs/lite-manifest.md
+#   scripts/render-lite-manifest-doc.sh --dry-run          # prints to stdout
+#   scripts/render-lite-manifest-doc.sh --input PATH       # read manifest from PATH
+#   scripts/render-lite-manifest-doc.sh --output PATH      # write to PATH
+#   scripts/render-lite-manifest-doc.sh --root PATH        # override repo root
+
+set -euo pipefail
+
+DRY_RUN=0
+INPUT_PATH=""
+OUTPUT_PATH=""
+REPO_ROOT_OVERRIDE=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run) DRY_RUN=1; shift ;;
+    --input) INPUT_PATH="${2:-}"; shift 2 ;;
+    --output) OUTPUT_PATH="${2:-}"; shift 2 ;;
+    --root) REPO_ROOT_OVERRIDE="${2:-}"; shift 2 ;;
+    -h|--help)
+      grep -E '^# ' "$0" | sed 's/^# \?//'
+      exit 0
+      ;;
+    *) echo "Unknown arg: $1 (use --help)" >&2; exit 1 ;;
+  esac
+done
+
+if [[ -n "$REPO_ROOT_OVERRIDE" ]]; then
+  REPO_ROOT="$REPO_ROOT_OVERRIDE"
+else
+  REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+fi
+
+if [[ -z "$REPO_ROOT" || ! -d "$REPO_ROOT" ]]; then
+  echo "render-lite-manifest-doc: cannot resolve repo root" >&2
+  exit 1
+fi
+
+[[ -z "$INPUT_PATH" ]] && INPUT_PATH="${REPO_ROOT}/lite-manifest.json"
+[[ -z "$OUTPUT_PATH" ]] && OUTPUT_PATH="${REPO_ROOT}/docs/lite-manifest.md"
+
+if [[ ! -f "$INPUT_PATH" ]]; then
+  echo "render-lite-manifest-doc: manifest not found at $INPUT_PATH" >&2
+  echo "Run scripts/generate-lite-manifest.sh first." >&2
+  exit 1
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "render-lite-manifest-doc: missing dependency: jq" >&2
+  exit 1
+fi
+
+VERSION=$(jq -r '.manifest_version' "$INPUT_PATH")
+GENERATED=$(jq -r '.generated_at' "$INPUT_PATH")
+COMMIT=$(jq -r '.upstream_commit' "$INPUT_PATH")
+SHORT_COMMIT="${COMMIT:0:7}"
+TOTAL=$(jq '.entries | length' "$INPUT_PATH")
+
+# Emit doc to stdout via function; caller decides where to redirect.
+render_doc() {
+  echo "# Lite manifest — v${VERSION}"
+  echo ""
+  echo "<!-- Auto-generated by scripts/render-lite-manifest-doc.sh from lite-manifest.json. Do not edit by hand. -->"
+  echo ""
+  echo "**Version:** \`${VERSION}\`  "
+  echo "**Generated:** \`${GENERATED}\`  "
+  echo "**Upstream commit:** \`${SHORT_COMMIT}\`  "
+  echo "**Total entries:** ${TOTAL}  "
+  echo "**Schema:** [\`standards/lite-manifest.schema.json\`](../standards/lite-manifest.schema.json)  "
+  echo "**Machine-readable:** [\`lite-manifest.json\`](../lite-manifest.json) (at repo root)"
+  echo ""
+  echo "> Partners pin against \`manifest_version\`. Membership changes ship as manifest bumps with a changelog entry. Adding an entry is a minor bump; removing is a major bump (breaks partners); description or content-hash change without membership change is a patch bump."
+
+  render_section "skill"    "Skills"
+  render_section "rule"     "Rules"
+  render_section "hook"     "Hooks"
+  render_section "luminary" "Luminaries"
+  render_section "agent"    "Agents"
+  render_section "standard" "Standards"
+  render_section "adr"      "Architecture Decision Records"
+  # Per #1392 Shape 3 (goal 2026-08-27a) — 5 install surfaces bassclef-cli needs
+  render_section "lib"               "Shared Libraries"
+  render_section "script"            "Scripts"
+  render_section "presence-template" "Install Templates"
+  render_section "template"          "Content Templates"
+  render_section "root-doc"          "Root Documentation"
+
+  echo ""
+  echo "---"
+  echo ""
+  echo "## For partners"
+  echo ""
+  echo "- Fetch the manifest from repo root: \`lite-manifest.json\`"
+  echo "- Validate against the schema at \`standards/lite-manifest.schema.json\` (JSON Schema draft 2020-12 strict)"
+  echo "- Pin your build to a specific \`manifest_version\`; upgrade deliberately"
+  echo "- Every \`entries[].path\` is repo-relative; the source file at that path is the authoritative content"
+  echo "- Use \`entries[].content_hash\` to cache-invalidate"
+  echo ""
+  echo "## Semver bump policy"
+  echo ""
+  echo "| Change | Bump |"
+  echo "|---|---|"
+  echo "| Entry added to \`entries[]\` | Minor |"
+  echo "| Entry removed from \`entries[]\` | Major (breaks partners) |"
+  echo "| Description or content_hash change without membership change | Patch |"
+  echo "| Schema shape change (new field added) | Minor |"
+  echo "| Schema shape change (field removed or type changed) | Major |"
+  echo ""
+  echo "Refs — bassclef-upstream#1020 (this manifest) + bassclef-upstream#1030 (root location) + ADR-040 (lite profile) + ADR-031 (we don't break adopters)."
+}
+
+render_section() {
+  local surface_type="$1"
+  local title="$2"
+  local count
+  count=$(jq --arg t "$surface_type" '[.entries[] | select(.type == $t)] | length' "$INPUT_PATH")
+  [[ "$count" -eq "0" ]] && return
+
+  echo ""
+  echo "## ${title} (${count})"
+  echo ""
+  jq -r --arg t "$surface_type" '
+    .entries[] | select(.type == $t) |
+    "- **" + .slug + "** — `" + .path + "`" +
+      (if .description then "  \n  " + .description else "" end)
+  ' "$INPUT_PATH"
+}
+
+if [[ "$DRY_RUN" == "1" ]]; then
+  render_doc
+else
+  mkdir -p "$(dirname "$OUTPUT_PATH")"
+  render_doc > "$OUTPUT_PATH"
+  echo "Wrote $OUTPUT_PATH ($TOTAL entries; commit $SHORT_COMMIT)" >&2
+fi

package/substrate/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/substrate/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)