@thebassclef/lite 1.0.4 → 1.1.0

package/dist/lite/.claude/skills/pattern-review/SKILL.md

@@ -0,0 +1,99 @@
+---
+tier: lite
+name: pattern-review
+description: "Review code through the lens of world-class engineering patterns \u2014 GoF, Fowler, SOLID, DDD. Flag violations and suggest improvements. Complements /architect-review which is system-level."
+problem: "Code review catches style but misses architecture. A wrong pattern ships and blocks future work."
+value: "Review through the lens of GoF and Fowler and SOLID and DDD. Names the pattern gap or misuse."
+inputs: [A file path or PR ref or code block]
+outputs: [Pattern gap list, Misuse findings, Suggested pattern per finding]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# Principal Engineer Review
+
+Apply time-tested software engineering patterns as a review lens.
+
+## Patterns to Apply
+
+### Design judgment — per @luminary john-ousterhout
+
+The lens that asks whether the shape is right in the first place. Beck (TDD) and Fowler (refactoring tactics) presume a target shape; Ousterhout supplies the criteria for choosing the target.
+
+- **Deep modules** — a module is deep when it has a small interface and a large, complex implementation hidden behind it. When a class is being split for "smaller files," check: does the split produce TWO deep modules, or TWO shallow ones?
+  INSTEAD of accepting file-size as the splitting metric: use interface-shape as the metric. Two shallow modules from a split is a regression even if the line count drops.
+- **Comments encode design decisions code cannot** — every non-obvious comment must say WHY (invariant), WHAT-IF (alternative considered and rejected), or WATCH-OUT (subtle constraint). Comments that restate code are noise; comments that record design decisions are essential. Flag the noise; preserve the design comments.
+- **Complexity is incremental** — flag the small drips at review time, not the large refactor later. A single special case, a single dependency, a single inconsistency adds nothing visible today and compounds across releases.
+- **Define errors out of existence** — when a review surfaces an API that throws errors callers must handle, ask whether the API can be redesigned so the error condition cannot occur. Idempotent operations and bootstrapping-on-missing are stronger than BLOCK-on-missing.
+
+When you cite `@luminary john-ousterhout`, you are citing the design-judgment lens. Pair it with Beck (test mechanics), Fowler (refactoring tactics), or GoF (pattern selection) when the review needs those lenses too.
+
+### SOLID Principles — per @luminary robert-c-martin
+- **SRP** — Does this module do one thing? Would you change it for more than one reason?
+- **OCP** — Can you extend behavior without modifying existing code?
+- **LSP** — Can subtypes replace their parents without breaking callers?
+- **ISP** — Are interfaces lean? Do implementers stub methods they don't use?
+- **DIP** — Do high-level modules depend on abstractions, not concretions?
+
+Check: does business logic import framework or persistence code? That violates the Dependency Rule per @luminary robert-c-martin (Clean Architecture). Functions that do more than one thing, and modules with multiple reasons to change, are SOLID red flags. Boy Scout rule applies — leave the code cleaner than you found it.
+
+### Gang of Four (GoF) patterns — per @luminary gang-of-four — Apply When Relevant
+- **Strategy** — scoring dimensions, data sources (each implements same interface)
+- **Observer** — job completion events, webhook callbacks
+- **Factory** — creating agents/workers by type
+- **Template Method** — base class with customizable steps
+- **Adapter** — wrapping external APIs with consistent interface
+- **Decorator** — cross-cutting concerns (observability, caching, auth) wrapping interfaces
+
+Per @luminary gang-of-four — the two opening principles of *Design Patterns*: program to an interface, not an implementation; favor object composition over class inheritance. Apply patterns when variation pressure or structural friction exists — not for aesthetics. Pattern stacking (five patterns where two would do) carries cognitive cost; each pattern earns its place.
+
+### Fowler patterns — per @luminary martin-fowler
+- **Repository** — data access abstraction (are queries leaking business logic?)
+- **Service Layer** — is business logic in the right layer?
+- **Domain Events** — should actions trigger other actions?
+- **Value Objects** — are primitives used where domain types would be clearer?
+- **Specification** — complex query filters should be composable
+
+Code smells per @luminary martin-fowler (*Refactoring*): Long Method, Feature Envy, Shotgun Surgery (one change touches many unrelated files), Primitive Obsession (strings where domain types would clarify), Data Clumps, Inappropriate Intimacy. Name the smell, then name the refactoring that addresses it. When a change is hard, first refactor to make the change easy — then make the easy change.
+
+### Stability patterns — per @luminary michael-nygard (*Release It!*)
+- **Circuit Breaker** — external service calls guarded; the three states (Closed / Open / Half-Open) prevent cascading failure
+- **Bulkhead** — thread pools / queue slots bounded per integration; one slow dependency can't starve others
+- **Timeout** — every integration point has explicit connect + read timeouts; no unbounded blocking calls
+- **Fail Fast** — validate at system boundaries; reject requests immediately when a known failure condition exists
+
+Check: any integration point without a circuit breaker is a cascading-failure risk per @luminary michael-nygard. Any call chain where one slow dependency can exhaust shared resources needs a bulkhead. Stability patterns are for integration points and external boundaries — not internal application logic.
+
+### Domain-Driven Design — per @luminary eric-evans
+- **Bounded Contexts** — are domains properly separated? Does each module use one consistent model?
+- **Aggregates** — are entity boundaries correct? Does one root control access?
+- **Ubiquitous Language** — do code terms match business terms? "DealRecord" for what the business calls "Deal" is a vocabulary leak.
+
+Per @luminary eric-evans (DDD blue book): the model is the backbone of the design; bounded contexts let multiple models coexist without collapsing into mud. Watch for anemic domain models — objects that hold data without behavior, with business logic scattered across services.
+
+### Pragmatic Rules
+- **YAGNI** — Don't build what you don't need. DO build the boundary so it's easy to add later.
+- **Tell, Don't Ask** — Objects should do things, not be interrogated for state
+- **Law of Demeter** — Don't reach through objects
+- **Composition over Inheritance** — Prefer composing behaviors (per @luminary gang-of-four opening principle)
+- **Fail Fast** — Validate at boundaries, throw early (per @luminary michael-nygard)
+
+## Review Procedure
+
+1. Read the code being reviewed
+2. For each file/module, check against the patterns above
+3. Flag violations with: pattern violated, current code, suggested improvement, severity
+4. Acknowledge good patterns already in place
+5. Produce summary: N critical, N improvement, N nitpick
+
+## When NOT to Apply
+
+- Don't over-engineer simple CRUD
+- Don't add abstractions for one-time operations
+- Don't refactor working code just because it could be "more OOP"
+- Three similar lines is better than a premature abstraction
+- Apply patterns when they solve a real problem, not for aesthetics
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.

package/dist/lite/.claude/skills/personas/SKILL.md

@@ -0,0 +1,207 @@
+---
+tier: lite
+name: personas
+description: "Load, list, and manage user personas \u2014 the bassclef WHO record. Downstream skills (value-prop-canvas, synthetic-user, user-stories, jtbd-tasks) read from its output. Defaults to operator when no personas exist."
+problem: "Product decisions get made for a nameless user. Downstream skills invent personas per session."
+value: "One record of the WHO the product serves. Every skill reads the same personas."
+inputs: [Manage command — list or add or edit or delete]
+outputs: [Persona list with names and jobs, Loaded into session for downstream skills]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# /personas — Bassclef Persona Primitive
+
+The WHO building block for bassclef. Load personas from a repo's persona
+directory, list them with summary, get one by slug, or fall back to a
+minimal operator-default when no personas exist.
+
+Downstream skills read personas via the file-system convention below —
+not via an in-memory API. The "interface" is a directory shape + a
+schema, not a function signature. That keeps the primitive compatible
+with every agent session regardless of runtime.
+
+## Sources read
+
+- Roman Pichler — *The Persona Template* (goal + tasks + approach + context + knowledge + biography). https://www.romanpichler.com/the-persona-template/ — .
+- Agile Alliance — *Personas* glossary entry. https://agilealliance.org/glossary/personas/
+- Atlassian — *User Stories + Personas* overview. https://www.atlassian.com/agile/project-management/user-stories
+- `standards/persona-schema.md` — bassclef schema (this skill's companion standard; Stack-1 artifact)
+- `templates/persona-template.md` — bassclef template (this skill's companion template; Stack-1 artifact)
+- `.claude/skills/jtbd-tasks/SKILL.md` Step 0 — existing "minimum viable persona" (5 fields). Subset of Pichler; remains valid. Path `docs/design/personas/` supported as legacy.
+- `.claude/skills/synthetic-user/SKILL.md` — existing consumer; reads `docs/design/personas/`. This skill keeps that read-path working.
+- Quorum's `docs/personas/*.md` (3 files: couple-founders, cofounder-pair, operator-advisor) — evidence format reference. Schema validates them without forcing edits.
+
+## What I'm NOT reading
+
+- Alan Cooper *Inmates* archetype-persona framework — adjacent theory; schema is Pichler-shaped per ticket, Cooper referenced in the template as further reading
+- Upstream persona generators (`/psychographic-mine`, `/auto-user-research`) — deferred to later bassclef promotion bet; this skill ships the consumer contract only
+
+## When to invoke
+
+- Before running `/value-prop-canvas`, `/synthetic-user`, `/risk-test-synthetic`, `/jtbd-tasks`, `/user-stories`, `/spec`, `/riff-prototypes` — those skills read persona output
+- When onboarding a new repo that needs persona definitions
+- When the operator asks "who are our users?"
+
+## Usage
+
+```
+/personas                            → list all personas in the repo (summary table)
+/personas list                       → same as default
+/personas get [slug]                 → print full persona file
+/personas default                    → emit operator-default (when no personas exist)
+/personas validate                   → walk every persona file against the schema, report findings
+```
+
+## Procedure
+
+### Step 1: Locate persona files
+
+Search for persona files in this order:
+
+1. `docs/personas/*.md` — **preferred bassclef path**
+2. `docs/design/personas/*.md` — legacy path (supported for backward compat with `/jtbd-tasks` + `/synthetic-user`)
+3. If neither directory exists: proceed to operator-default fallback (Step 4)
+
+Both paths are valid. When both exist, prefer `docs/personas/` and warn the operator that legacy path files are being ignored (offer to migrate).
+
+### Step 2: List mode (default)
+
+Emit a summary table:
+
+```markdown
+| Slug | Name | Goal (1-line) | Evidence quality | Location |
+|------|------|---------------|-----------------|----------|
+| ... | ... | ... | High/Medium/Low/— | docs/personas/... |
+```
+
+If a persona omits an evidence-quality field, render `—` (don't invent a rating).
+
+### Step 3: Get mode
+
+Print the full persona file content. Verify required fields (see schema) before emitting; if any required field is missing, print the file AND a WARN block listing gaps.
+
+### Step 4: Operator-default fallback
+
+When no persona files exist in the repo, auto-populate a minimal persona file for "you" (the operator) from:
+
+- `CLAUDE.md` — read the "What this repo is" / "Active initiative" sections for goal context
+- `substrate.config.md` — read `agents:` and `deploy_targets:` for role context
+- If a git `user.email` exists, use it to derive a rough slug (`operator-[local-part]`), otherwise `operator`
+
+Emit the operator default to the conversation (not to disk — operator decides whether to persist it):
+
+```markdown
+# Persona — Operator (you)
+
+**Slug:** operator
+**Name:** you
+**Goal:** [inferred from CLAUDE.md "Active initiative" or similar section, one line]
+**Context:** [repo name + project_level + active iteration from whereami if present]
+**Knowledge:** [domain cues from CLAUDE.md — frameworks, subsystems]
+**Evidence quality:** — (auto-populated default; no source-trace)
+```
+
+Tell the operator: "No personas found. Emitted operator-default for `you`. Run `/personas validate` after adding real persona files to `docs/personas/`."
+
+### Step 5: Validate mode
+
+For each file under `docs/personas/*.md` (and legacy path), check:
+
+- [ ] Required fields present (slug, name) — FAIL if absent
+- [ ] Slug matches filename basename (`couple-founders.md` → slug: couple-founders) — FAIL on mismatch
+- [ ] Pichler recommended fields (goal, tasks, approach, context, knowledge, biography) present — WARN (not FAIL) on absence; small personas are valid, just thin. If `goal` is missing but the file has a `## JTBD statements` section, print an INFER line suggesting a goal line derived from the first JTBD — operator reviews, not auto-write.
+- [ ] Evidence-traceability: if persona contains claims about pain points, workflows, or behavior, at least one claim is cited to a source (internal research doc OR external URL). WARN on orphan claims.
+- [ ] No duplicate slugs across files — FAIL on duplicate
+
+Output format:
+
+```markdown
+## Persona validation
+
+**Files scanned**: N in docs/personas/, M in docs/design/personas/
+
+| File | Required | Pichler | Evidence | Slug-match | Status |
+|------|----------|---------|----------|-----------|--------|
+| couple-founders.md | ✅ | ✅ (all 6) | ✅ (5 citations) | ✅ | PASS |
+| minimal.md | ✅ | ⚠️ (goal + context only) | ⚠️ (1 orphan claim) | ✅ | WARN |
+| ...
+
+**Pass**: N | **Warn**: M | **Fail**: K
+```
+
+Fail means a required field is missing — the persona can't be safely consumed. Warn means the persona works but would benefit from enrichment.
+
+## Schema (summary)
+
+Required (every persona — FAIL if absent):
+- `slug` — URL-safe identifier; filename basename
+- `name` — human-readable display name (H1 counts)
+
+Recommended (Pichler — WARN if absent):
+- `goal` — one-line "what this persona is trying to accomplish" (downstream skills infer from Role/Context/JTBD sections when missing, but the inference is lossy)
+- `tasks` — recurring tasks in pursuit of the goal
+- `approach` — how they go about it (habits, tools, rhythm)
+- `context` — life / business / organizational context
+- `knowledge` — domain expertise, jargon comfort, technical fluency
+- `biography` — background, archetype, formative influences
+
+Recommended (evidence-traceability):
+- `provenance` section — where the persona comes from (research doc, interviews, analytics, external article URLs)
+- Every claim about pain/behavior/workflow traces to a source
+
+Full schema: `standards/persona-schema.md`. Template: `templates/persona-template.md`.
+
+## Operator-default: when it's OK, when it isn't
+
+The operator-default fallback prevents skills from crashing in repos without personas. **Use it to bootstrap, not to replace real personas.**
+
+When operator-default is appropriate:
+- New repo, first iteration, no user research yet
+- Internal tooling where the operator IS the user
+- Spike / prototype sessions where user identity is deliberately deferred
+
+When it's a red flag:
+- `/synthetic-user` running against operator-default at Tier 3 — you're testing whether the operator can use their own tool, which is not the same as user testing
+- `/value-prop-canvas` built from operator-default — value props for "you" tell you nothing about fit for real customers
+- Iteration bet's "lovability signal" tied to operator-default — that's the operator proxy-hypothesizing, not evidence
+
+`/personas validate` surfaces these cases with a note: "Only operator-default persona found; consider adding real personas before [downstream skill]."
+
+## Relationship to other skills
+
+| Skill | How it composes with `/personas` |
+|-------|---------------------------------|
+| `/value-prop-canvas` | Reads `/personas list` → produces one canvas per persona. 1:1 with persona, never "one for all." |
+| `/synthetic-user` | Reads personas; runs Tier 3 journeys per persona. Replaces the implicit "operator as user" assumption. |
+| `/risk-test-synthetic` | Reads personas; produces risk × persona × artifact matrix. |
+| `/jtbd-tasks` | Current Step 0 bootstraps a "minimum viable persona" (5 fields). That remains valid as a subset; consolidation to `/personas` tracked as follow-up. |
+| `/user-stories` | Reads persona.name for the `As a [persona]` clause in INVEST stories. |
+| `/spec` | Spec actors resolve to persona slugs when personas exist. |
+| `/riff-prototypes` | Prototype evaluation references personas for fit checks. |
+| `/psychographic-mine`, `/auto-user-research` | Upstream generators. Produce files that this skill reads. |
+
+## Common pitfalls
+
+- **Inventing personas from domain intuition** — personas without source traces fail silently. They look plausible, Synthesize plausibly in test journeys, but don't survive contact with actual users. If you don't have evidence, emit operator-default and flag the research gap.
+- **One persona for all consumers** — if three real customer segments exist, three persona files exist. Compressing them into one loses the fit signal VPC depends on.
+- **Persona file as a wall of text** — the schema is designed for skim. Put the goal + context in the first ~10 lines so downstream skills (and humans) can skim-read before deciding to dive deep.
+- **Path confusion** — preferred path is `docs/personas/`. `docs/design/personas/` works but will eventually be deprecated. New repos should use the preferred path.
+- **Silent schema drift** — running `/personas validate` regularly catches when persona files have been edited in ways that violate required-field invariants. Do this at the start of any iteration that reasons about users.
+
+## Provenance & evolution
+
+- Started as adopter work on user personas. Notes traced to real sources.
+- Later shipped upstream to bassclef.
+- Eight downstream skills read from `docs/personas/*.md`.
+
+Future promotions referenced (separate goals):
+- `/psychographic-mine` — upstream generator
+- `/auto-user-research` — orchestrated research → personas pipeline
+- `/user-stories` — downstream consumer
+- `/risk-test-synthetic` — downstream consumer
+- `/value-prop-canvas` — downstream consumer, shipping in Stack-2 of the same iteration as this skill
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.

package/dist/lite/.claude/skills/promote/SKILL.md

@@ -0,0 +1,283 @@
+---
+tier: lite
+name: promote
+description: "Propose promoting a pattern to bassclef. Creates an issue in the current repo (not bassclef) with the bassclef-evolution label. Three modes cover default, luminary upgrade, and substrate defect."
+problem: "Good patterns in one adopter repo stay stuck there. Every other adopter reinvents the same wheel."
+value: "Files a promote ticket in the current repo plus bassclef-upstream. Substrate evolves with real usage."
+inputs: [A pattern description or code snippet or discipline learned]
+outputs: [Promote ticket filed in current repo, Cross-repo mirror in bassclef-upstream]
+user_invocable: true
+disable_model_invocation: false
+composes_with: [state-a-problem, kiss, value-prop]
+requires:
+  cli: [gh]
+  network: true
+---
+
+# /promote
+
+## What you get
+
+An issue filed in the current app repo with the `bassclef-evolution` label, proposing that bassclef adopt a skill / rule / hook / workflow pattern you built locally. Three modes cover different promotion classes — the default files a general promotion issue; `--type luminary` files a full-depth upgrade for a stub luminary; `--type substrate-defect` files a mandatory promotion after fixing a bug in bassclef's own mechanism. Every issue body opens with a Problem section drafted by `/state-a-problem brief` and runs through `/kiss --grade10` inline.
+
+The issue stays in your current repo. Bassclef's session-reflection hook scans for `bassclef-evolution` labeled issues across child repos and ingests during a bassclef session — accept, defer, or reject.
+
+## When to use it
+
+Any time you discover a skill, rule, hook, or workflow pattern in an app repo that would help other repos too. The SDLC checkpoint flags this ("Is this general or app-specific?"). Also fires automatically after resolving a BLOCKED item where the fix landed in bassclef's substrate itself (that path is mandatory, not optional — see FAQ).
+
+Skip promotion for genuinely app-specific work (tenant-scoped logic, business rules, deploy details). Bassclef ingests general patterns; app-specific work stays local.
+
+## FAQ
+
+### What are the three modes?
+
+- **Default** — the general path. File a promotion issue for a new skill / rule / hook you built, an extension to an existing bassclef standard, or a workflow pattern insight.
+- **`--type luminary [slug]`** — upgrade a stub luminary you used as primary in an iteration. The issue body carries a full drop-in replacement for the luminary file, not just a description.
+- **`--type substrate-defect [ref]`** — mandatory after fixing a bug in bassclef's own mechanism (hook, rule, counter, marker). The issue documents what was broken, what shipped locally, and why every consumer repo needs the fix. Trigger conditions in `.claude/rules/blocked-items.md` §"When resolution reveals a substrate defect".
+
+### How do I know if I should use agent-self-proposed or agent-user-proposed?
+
+Scan the current user message for explicit promotion imperatives — "file a bassclef", "promote this", "run /promote", "push to bassclef". If any imperative is present, use `agent-user-proposed`. Otherwise use `agent-self-proposed`.
+
+Review requests like "check for /promote" are NOT imperatives to file. Read the intent and default to `agent-self-proposed` on review requests. When genuinely ambiguous, default `agent-self-proposed` and let bassclef triage flag if wrong.
+
+The distinction matters — `agent-self-proposed` means the agent's self-awareness caught a gap (evidence of maturing agent). `agent-user-proposed` means the operator caught a gap the agent missed (evidence of a weak trigger condition — bassclef triage asks why the agent missed it).
+
+### Why does the issue open with a Problem section?
+
+Per `.claude/rules/github-issue-flash-tweet.md` V3 (bassclef#1178 retired Flash + Tweet at PR + issue surfaces). Every issue body opens with `**Problem (≤500 chars):**` drafted by `/state-a-problem brief` — 3-4 sentences carrying Who / What / When / Why-now / Outcome implicit. The Problem section is the headline; readers on mobile decide from it whether to scroll.
+
+Then `---` (horizontal rule) then technical detail (`## Summary`, `## Why`, `## Acceptance`).
+
+### Why is /kiss --grade10 the default?
+
+Bassclef ships plain-English discipline per `.claude/rules/plain-english-discipline.md`. Issue bodies land in adopter-facing surfaces. The `/state-a-problem brief` skill runs `/kiss --grade10` inline by default so the Problem section is plain English without a separate pass. Body content after the Problem section runs through `/kiss words` as a second pass before submission.
+
+The PR-CI body-clarity job catches jargon at PR-open time as a backstop, but pre-submission cleanup is faster and produces no comment noise.
+
+### Why is substrate-defect mode mandatory?
+
+Because silence about the mechanism defect keeps the bug local. Three sessions in April 2026 fixed local hook drift without firing /promote; the same drift re-surfaced in POA two weeks later. Bet `2026-04-21a-blocked-signal-integrity` filed this mode as the closing obligation — the agent doesn't choose whether to promote; the trigger fires it.
+
+If you fix a hook, rule, or counter mechanism in the app repo but skip the bassclef promotion, every other consumer repo inherits the broken version until they hit the same failure and re-diagnose it.
+
+### How does bassclef ingest these?
+
+The bassclef session-reflection hook scans for `bassclef-evolution` labeled issues across all child repos. During a bassclef session, issues are reviewed for general applicability. Accepted issues result in content promoted to bassclef and the source issue closed. Deferred issues stay open with a rationale. Rejected issues close with an explanation.
+
+App repos never need write access to bassclef. The pull-side ingestion is how promotions land.
+
+## Details below the fold
+
+### Label creation (one-time per app repo)
+
+These labels don't exist by default. First time using `/promote` in a new repo, create them:
+
+```bash
+gh label create agent-self-proposed \
+  --color 0E8A16 \
+  --description "Agent proactively identified this gap during reflection"
+gh label create agent-user-proposed \
+  --color D93F0B \
+  --description "Operator caught this gap; agent's trigger needs review"
+```
+
+Bassclef provides the convention; each repo creates the labels locally.
+
+### Procedure — target resolution (all modes)
+
+Before filing, resolve where the issue lands. Reads `promote_target` from `.claude/bassclef-configs.jsonc`. Two shapes accepted plus a fallback:
+
+```bash
+# Read promote_target from bassclef-configs.jsonc (strip JSONC comments first)
+TARGET=$(sed 's|//.*||' .claude/bassclef-configs.jsonc 2>/dev/null | jq -r '.promote_target // empty' 2>/dev/null)
+
+if [ -z "$TARGET" ]; then
+  # Backward-compat — file in current repo (skill's prior behavior)
+  GH_REPO_ARG=""
+  DISPATCH="gh"
+elif [ "${TARGET#email:}" != "$TARGET" ]; then
+  # email:<address> — print mailto: URL, adopter sends
+  EMAIL_ADDR="${TARGET#email:}"
+  DISPATCH="mailto"
+else
+  # <owner>/<repo> — gh issue create --repo <TARGET>
+  GH_REPO_ARG="--repo $TARGET"
+  DISPATCH="gh"
+fi
+```
+
+When `$DISPATCH == "mailto"`, the procedure prints a ready-to-use `mailto:` URL instead of running `gh issue create`. The adopter sends. Nothing auto-sends.
+
+When `$DISPATCH == "gh"`, all three procedure modes below run their `gh issue create` command as documented, with `$GH_REPO_ARG` inserted right after `gh issue create`.
+
+Explicit env override — `PROMOTE_TARGET=<value> /promote ...` — beats the config field for one call.
+
+Defaults per adopter tier (advisory):
+
+| Adopter tier | Recommended `promote_target` |
+|---|---|
+| lite (npm-shipped) | `email:hello@bassclef.dev` (or your address) |
+| standard (this repo, other operator repos) | `sunj-labs/bassclef-upstream` |
+
+Adopter sets the value in `.claude/bassclef-configs.jsonc` once. `/promote` picks it up every call. Closes bassclef-upstream#1028.
+
+### Procedure — default mode
+
+1. Identify what to promote — which file(s) and why they're general
+2. Classify — New (skill / rule / hook not in bassclef), Extension (improvement to an existing standard), Pattern (workflow insight, not a specific file)
+3. Draft the Problem opener via `/state-a-problem brief` — Who benefits (bassclef adopters + future agents), what gap the local pattern fills, when adopters hit it, why now (concrete iteration evidence), what outcome promotion produces
+4. Create the issue in THIS repo (not bassclef):
+
+```bash
+gh issue create $GH_REPO_ARG \
+  --label "bassclef-evolution,agent-self-proposed" \
+  --title "Promote to bassclef: [brief description]" \
+  --body "**Problem (≤500 chars):** [output from /state-a-problem brief]
+
+---
+
+## What
+[What should be promoted — file name, content summary]
+
+## Why general
+[What makes it reusable — not app-specific]
+
+## Type
+[New | Extension | Pattern]
+
+## Content
+[Paste the relevant content or reference the file]"
+```
+
+5. Note in the session's session log: "Proposed promotion: [description] → #NNN"
+
+### Procedure — luminary upgrade mode
+
+Fires when a stub-depth luminary was used as primary in an iteration and the iterating repo has concrete context to upgrade it.
+
+App repos can't edit bassclef files directly (symlinks). This mode files a drop-in replacement so bassclef's agent gets a ready diff instead of having to reconstruct what the app repo's agent already figured out.
+
+1. Read the current stub at `.claude/luminaries/[slug].md` (inherited from bassclef via symlinks)
+2. Identify what's missing to reach full depth:
+   - When to channel this luminary (concrete conditions)
+   - Stack translation (specific to your stack)
+   - Anti-patterns it prevents (3-5 concrete failure modes)
+   - Worked example (using real entities from your domain)
+   - Related luminaries (3-5 named relationships)
+3. Draft each section with evidence from the iteration that triggered the upgrade
+4. Draft the Problem opener via `/state-a-problem brief`
+5. Create the issue with the full-depth content pre-filled:
+
+```bash
+gh issue create $GH_REPO_ARG \
+  --label "bassclef-evolution,luminary-upgrade" \
+  --title "Promote to bassclef: upgrade [luminary name] stub → full" \
+  --body "**Problem (≤500 chars):** [output from /state-a-problem brief]
+
+---
+
+## Context
+Used [luminary] as primary in iteration [goal path]. Evidence reveals content the current stub doesn't capture.
+
+## Proposed upgrade (drop-in replacement)
+
+\`\`\`markdown
+[full drafted content for .claude/luminaries/[slug].md]
+\`\`\`
+
+## Evidence from this iteration
+
+- [concrete usage that informed the draft]
+- [what was missing from the stub]
+- [patterns and anti-patterns that emerged]
+
+## Source references to verify
+
+- [primary sources to check before merging]"
+```
+
+### Procedure — substrate-defect mode
+
+Fires when resolution of a BLOCKED item reveals that the hook / rule / counter mechanism itself was broken — not the work. Trigger conditions in `blocked-items.md` §"When resolution reveals a substrate defect".
+
+**Trigger patterns:**
+
+- Stuck signal resolved via mechanism-read + substrate edit
+- Hook false-positive was the root cause (banner fired without real work being undone)
+- Counter miscount / marker rot / path drift in the substrate
+- Reviewer rejection that traces to a rule / hook producing wrong guidance
+
+**Procedure:**
+
+1. Identify the defect — which substrate file (hook, rule, skill, standard) was wrong, and what specifically broke
+2. Confirm the fix landed — the PR / commit that fixes the local instance is in-flight or merged
+3. Draft the Problem opener via `/state-a-problem brief`
+4. Create the issue with the substrate-defect template:
+
+```bash
+gh issue create $GH_REPO_ARG \
+  --label "bassclef-evolution,agent-self-proposed,substrate-defect" \
+  --title "Promote to bassclef: substrate defect — [one-line description]" \
+  --body "**Problem (≤500 chars):** [output from /state-a-problem brief]
+
+---
+
+## Signal observed
+[Banner text, chronicle dates showing the loop, or reviewer comment.
+Include counter values across sessions if stuck-signal path applies.]
+
+## Mechanism file read
+- Path: [e.g., .claude/hooks/session-end.sh]
+- Defect: [wrong path, stale regex, counter reading location the writer stopped using, calendar-date check in ephemeral env, etc.]
+
+## Fix applied
+- PR / commit: [ref]
+- Change shape: [1-2 sentences — what the substrate now does differently]
+
+## Propagation requirement
+- Consumer repos that inherit this substrate: [list, or 'all per bassclef-sync.sh']
+- What breaks in consumer repos without this fix: [concrete failure mode, with at least one observable signal]
+- Urgency: [high if silent wrong signals; medium if noisy false positives; low if cosmetic]
+
+## Source references
+- Rule / standard governing this mechanism: [path]
+- Related issues / prior drift: [issue refs if any]"
+```
+
+5. Cite in session log: `substrate defect promoted: #NNN`
+
+**Label discipline:** substrate-defect promotions carry THREE labels — `bassclef-evolution` + `agent-self-proposed` (or `agent-user-proposed` if operator flagged) + `substrate-defect`. The third label routes bassclef triage to treat these at higher priority.
+
+### Composes with
+
+- `/state-a-problem brief` — drafts the Problem opener (≤500 chars) for every issue body; runs `/kiss --grade10` inline
+- `/kiss words` — applied to body content after the Problem section before filing
+- `/value-prop` — retained for non-issue surfaces (session log entries, journal openers, retro lines) where the tweet + brief sizes still apply
+
+### Rules
+
+- Issue goes in the CURRENT repo. App repos file in their own repo with `bassclef-evolution` label; bassclef's session-reflection hook scans and ingests.
+- App repos never need write access to bassclef. The label routes promotion through pull-side ingestion.
+- Use the `bassclef-evolution` label consistently. The ingestion hook reads this exact label across all child repos.
+- Agent-proposed promotions get the `agent-self-proposed` or `agent-user-proposed` label for scrutiny routing.
+- Bassclef sessions make the accept / defer / reject decision. App repos file and continue with current work; bassclef lands on its own cadence.
+
+### Refs
+
+- bassclef#1256 — this skill's V2 rewrite parent (Problem section opener replaces Flash + Tweet)
+- bassclef#1178 — parent rule update (Problem section at PR + issue body surfaces)
+- bassclef#559 — Phase II Trim the Fat plain-English discipline parent
+- `.claude/skills/state-a-problem/SKILL.md` — drafts the Problem opener
+- `.claude/skills/kiss/SKILL.md` — grade-10 substitution
+- `.claude/rules/github-issue-flash-tweet.md` — V3 rule this skill aligns with
+- `.claude/rules/plain-english-discipline.md` — master plain-English rule
+- `.claude/rules/blocked-items.md` — substrate-defect mode mandatory trigger
+- `.claude/rules/stuck-signal-diagnostic.md` — stuck-counter path that most often surfaces substrate defects
+- `standards/bassclef-evolution.md` — full ingestion protocol + three-source model
+- `standards/opener-discipline.md` — the three-block opener shape the Problem section fits into
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.