@thebassclef/lite 1.0.4 → 1.1.1

package/dist/lite/standards/persona-schema.md

@@ -0,0 +1,229 @@
+---
+tier: lite
+description: Bassclef schema for user personas in sunj-labs repos.
+---
+
+# Persona Schema
+
+Bassclef schema for user personas in sunj-labs repos. The contract the
+`/personas` skill reads and every downstream consumer (`/value-prop-canvas`,
+`/synthetic-user`, `/risk-test-synthetic`, `/user-stories`, `/jtbd-tasks`,
+`/spec`, `/prototype-variants`) composes against.
+
+Template: `templates/persona-template.md`.
+Skill: `.claude/skills/personas/SKILL.md`.
+
+## Why this standard exists
+
+Before this schema, persona shape was implicit and scattered:
+
+- `.claude/skills/jtbd-tasks/SKILL.md` Step 0 defined a "minimum viable
+  persona" with 5 fields (Age, Role, Device, Goal, Jargon comfort)
+- `.claude/skills/synthetic-user/SKILL.md` read personas from
+  `docs/design/personas/` with no schema validation
+- sunj-labs/quorum invented its own richer shape (Pichler + evidence-
+  traceability) for psychographic-mining output — not reflected anywhere
+  in bassclef
+
+Three consumers, three schemas, zero validation. Adding `/value-prop-canvas`
+and `/risk-test-synthetic` without standardizing would have made four.
+
+This standard consolidates around Pichler's template shape, adds evidence-
+traceability as a distinguishing rule, and preserves both prior path
+conventions for backward compat.
+
+## File convention
+
+### Preferred path
+
+`docs/personas/{slug}.md` — one file per persona.
+
+Filename basename MUST match the `slug` field in the file's body. The
+slug is URL-safe: lowercase, hyphens, no spaces.
+
+### Legacy path (accepted)
+
+`docs/design/personas/{slug}.md` — read by `/jtbd-tasks` and `/synthetic-user`
+before this standard existed. Still valid. Consumers read both paths,
+preferring `docs/personas/` when both exist.
+
+New repos SHOULD use `docs/personas/`. Existing repos MAY migrate or
+leave legacy files in place; consolidating bet may follow.
+
+## Required fields
+
+Every persona file MUST have:
+
+| Field | Shape | Example |
+|-------|-------|---------|
+| `slug` | URL-safe identifier, matches filename | `couple-founders` |
+| `name` | Human-readable display name (H1 satisfies) | `Couple Founders` |
+
+Absent any required field → `/personas validate` reports FAIL. Downstream
+skills SHOULD refuse to operate on invalid personas.
+
+The required set is intentionally minimal. `slug` + `name` is enough to
+reference a persona unambiguously; everything else is quality-of-output
+for downstream skills, not a load-bearing contract at the identity level.
+
+## Recommended fields (Pichler shape + outcome framing)
+
+High-value personas carry the full Pichler template plus an explicit
+goal line:
+
+| Field | Purpose |
+|-------|---------|
+| `goal` | One-line "what this persona is trying to accomplish" — verb-first, outcome-oriented |
+| `tasks` | Recurring tasks in pursuit of the goal |
+| `approach` | How they go about it (habits, tools, rhythm) |
+| `context` | Life / business / organizational grounding |
+| `knowledge` | Domain expertise, jargon comfort, technical fluency |
+| `biography` | Background, archetype, formative influences |
+
+Absence produces WARN (not FAIL) in validation. A persona with only the
+required fields is valid but thin — downstream skills will produce
+thinner outputs against it.
+
+**Goal inference fallback:** if a persona omits `goal` but has a
+`## JTBD statements` section, `/personas validate` prints an INFER line
+suggesting a goal derivable from the first JTBD. This is advisory, not
+auto-applied — the operator reviews and edits the file. The rationale:
+downstream skills like `/value-prop-canvas` and `/user-stories` need an
+unambiguous goal, and silent inference produces inconsistent results
+across consumers. Surface the gap once, let the operator resolve it, and
+every downstream read is consistent.
+
+## Evidence-traceability rule
+
+A persona that claims pain points, workflows, or behavior patterns MUST
+cite sources. Claims without source traces are **orphan claims** and
+surface as WARN in `/personas validate`.
+
+### Bassclef citation format
+
+```markdown
+### P1 — Concise pain label
+
+[Paragraph describing the pain.]
+
+> *Source trace: [source-N reference] — "[direct quote or close paraphrase]"*
+```
+
+Acceptable source types:
+
+- Repo-local research document (e.g., `docs/research/reddit-synthesis.md §3`)
+- External URL (articles, interviews, public forum posts)
+- Attributed interview note (`interview/YYYY-MM-DD-name.md §4`)
+- Analytics dashboard reference (product metric + timeframe)
+
+Not acceptable: "common knowledge," "I've seen this before," unattributed
+assertions, operator intuition.
+
+### Why this rule exists
+
+Personas without source traces fail silently. They look plausible, their
+synthesized behaviors read naturally, and downstream skills (VPC,
+synthetic-user) produce plausible-looking artifacts against them. The
+artifacts fail on contact with actual users because the foundational
+persona was a pattern-match on training priors, not evidence.
+
+Parallel to `.claude/rules/artifact-ingestion.md`: read before you
+produce. Cite before you claim.
+
+## Operator-default fallback
+
+Repos without persona files are common — new repos, internal tooling,
+early spikes. `/personas default` emits a minimal operator persona
+derived from:
+
+- `CLAUDE.md` (for goal / context)
+- `substrate.config.md` (for agents / deploy targets)
+- `docs/whereami.md` (for active iteration context)
+- Git `user.email` (for slug derivation)
+
+### 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
+
+Operator-default leaking into these situations means the product is
+being validated against the operator's self-assessment, which is not
+user validation:
+
+- `/synthetic-user` running Tier 3 journeys against operator-default
+- `/value-prop-canvas` built from operator-default (value prop for
+  "you" tells you nothing about fit for real customers)
+- Iteration goal lovability/viability signals tied to operator-default
+
+`/personas validate` surfaces these with a note:
+"Only operator-default persona found; consider adding real personas
+before [downstream skill]."
+
+## Multiple personas — no compression
+
+If three real customer segments exist, three persona files exist. Do NOT
+collapse into a "composite customer" or "typical user" — compression
+loses the fit signal that `/value-prop-canvas` and `/risk-test-synthetic`
+depend on.
+
+VPC is 1:1 with persona. Risk-test matrices are persona × risk × artifact.
+A single merged persona flattens the matrix.
+
+## Validation checklist
+
+`/personas validate` walks every persona file under both bassclef and
+legacy paths and reports:
+
+- [ ] Required fields (slug, name) present — FAIL on absence
+- [ ] Slug matches filename basename — FAIL on mismatch
+- [ ] Pichler recommended fields (goal, tasks, approach, context, knowledge, biography) — WARN on absence
+  - If `goal` is absent but a `## JTBD statements` section exists, emit INFER line with suggested goal derived from first JTBD
+- [ ] Evidence traces present for behavior/pain claims — WARN on orphans
+- [ ] No duplicate slugs across files — FAIL on duplicate
+- [ ] File is readable markdown (parses without error) — FAIL otherwise
+
+Output format:
+
+```markdown
+## Persona validation
+
+**Files scanned**: N in docs/personas/, M in docs/design/personas/
+
+| File | Required | Pichler | Evidence | Slug-match | Status |
+|------|----------|---------|----------|-----------|--------|
+| [file] | ✅/❌ | ✅/⚠️ | ✅/⚠️ | ✅/❌ | PASS/WARN/FAIL |
+
+**Pass**: N | **Warn**: M | **Fail**: K
+```
+
+## Relationship to other standards
+
+| Standard / rule | Connection |
+|-----------------|-----------|
+| `.claude/rules/artifact-ingestion.md` | Evidence-traceability is artifact-ingestion applied to personas specifically |
+| `standards/whereami-schema.md` | Same "schema + template + skill + rule" pattern; different domain |
+| `standards/substrate-config-schema.md` | Operator-default fallback reads substrate.config fields |
+| `.claude/skills/jtbd-tasks/SKILL.md` | Step 0 "minimum viable persona" is a subset view of this schema; valid but thin |
+| `.claude/skills/synthetic-user/SKILL.md` | Existing consumer; reads legacy path; continues to work |
+
+## Future evolution
+
+When `/psychographic-mine` (quorum #54) and `/auto-user-research`
+(quorum #53) promote to bassclef, they produce files conforming to
+this schema with High evidence-quality ratings by construction.
+
+When `/jtbd-tasks` consolidates its Step 0 to delegate to `/personas
+default` or `/personas get`, the "minimum viable persona" variant
+becomes a template preset rather than a parallel shape.
+
+Neither consolidation happens in this bet's scope — both deferred to
+follow-up iterations so this standard ships with a stable contract
+first.
+
+## Closes
+
+- bassclef #200 (companion to quorum #50)
+- Part of iteration `docs/iteration-bets/2026-04-19e-persona-vpc-promotions.md` Stack-1

package/dist/lite/standards/pluggable-luminaries.md

@@ -0,0 +1,323 @@
+---
+tier: lite
+description: Each agent in bassclef has a default set of luminaries — thinkers whose principles guide its decisions.
+---
+
+# Pluggable Luminaries
+
+Each agent in bassclef has a default set of luminaries — thinkers whose
+principles guide its decisions. App repos that inherit bassclef can
+customize which luminaries are active per agent, per phase, without editing
+bassclef agent definitions directly.
+
+Customization lives in `substrate.config.md`. Bassclef defaults are never
+modified. The merge is computed at runtime by the Orchestrator during boot.
+
+---
+
+## File architecture (as of 2026-04-12)
+
+Luminary content lives in **per-luminary files** at `.claude/luminaries/[slug].md`,
+one file per thinker. Agent definitions (`.claude/agents/*.md`) reference
+luminaries by slug and keep a one-line signature; they do NOT duplicate the
+luminary's full content inline.
+
+**Why per-file**: Previously luminary content lived inline inside agent
+definitions, squeezed into whatever space the agent file could spare. This
+produced structural sparsity — Designer at 17 luminaries × 4 lines each
+meant every luminary was a name-drop. Three "data-heavy" prototype variants
+(Prater, Norman, Tufte dominants) blurred together because the luminaries
+themselves blurred. Per-file gives each thinker its own budget (40–80 lines),
+lets multiple agents share a single source of truth (Cockburn spans
+Architect, Builder, Shaper), and makes depth structurally enforceable via
+schema.
+
+**Depth bar** (see `.claude/luminaries/TEMPLATE.md` for full schema):
+
+| Depth | Requirements |
+|-------|-------------|
+| `full` | All schema sections populated — signature, 2–4 named methods, when to channel, stack translation, anti-patterns, worked example, sources, related luminaries. 40–80 lines. |
+| `stub` | Frontmatter + signature + core methods + sources minimum. Lighter entries for luminaries that are legitimate references but don't dominate iteration decisions. |
+
+**Signature distinctiveness test**: If you could swap a luminary's signature
+line for another luminary's and nothing would break, the signature is too
+generic. Rewrite. Garrett's "UX is about people" fails this; "Strategy →
+scope → structure → skeleton → surface — every UX has five planes, skip one
+and the next collapses" passes.
+
+**New luminary protocol**: Copy `TEMPLATE.md` → `[slug].md`. Populate to
+`full` depth if the luminary will dominate iteration decisions; `stub`
+otherwise. Add a one-line reference in each claiming agent's definition
+pointing at the slug.
+
+---
+
+## Depth standard (as of 2026-04-12b)
+
+Every luminary file MUST satisfy:
+
+### Required for all depths (full + stub)
+
+1. **Frontmatter** — name, slug (kebab-case matching filename),
+   claimed_by (list of agents), primary_domain, depth.
+2. **Signature** — one to two sentences capturing the distinctive POV.
+   Must pass the **swap test**: if you substituted another luminary's
+   signature, would anything meaningfully change? If no, the signature
+   is too generic. Rewrite.
+3. **Core methods** — 2–4 named, operational methods. Each must be
+   a phrase the agent can invoke by name ("Apply ORCA", "Draw Walking
+   Skeleton"). Vague principles without names ("user-centered thinking")
+   don't count.
+4. **Sources** — primary sources only. Books, seminal talks, bassclef
+   articles by the luminary themselves. No third-party summaries or
+   Medium round-ups.
+
+### Additional for `full` depth
+
+5. **When to channel this luminary** — paragraph-level trigger
+   describing concrete conditions (domain, problem type, stakes) where
+   this POV dominates. Include "Do NOT channel for:" clause with
+   counter-cases.
+6. **Stack translation** — how the POV maps concretely to Next.js +
+   Prisma + React + TypeScript + Tailwind + our SDLC.
+7. **Anti-patterns it prevents** — 3–5 specific failure modes this
+   POV catches. Each must be concrete (not "bad design") and testable.
+8. **Worked example** — paragraph showing the POV applied to a
+   representative problem using our domain entities (Deal, Broker,
+   Seller, etc.).
+9. **Related luminaries** — 3–5 named relationships (complements,
+   contrasts, builds-on).
+
+### Distinctiveness enforcement
+
+When signatures fail the swap test, reject and rewrite. Common
+failures:
+
+| Generic signature (fails swap) | Distinctive signature (passes) |
+|---|---|
+| "UX is about people, not technology." | "Every user experience has five planes: strategy → scope → structure → skeleton → surface. Skip one and the next collapses." (Garrett) |
+| "Good design is simple." | "Material honesty. Resolve every seam. A product is finished when nothing can be removed without breaking it." (Ive) |
+| "Start with the user." | "Personas are precision tools — each a research-grounded behavioral archetype, not a fictional user." (Cooper) |
+
+### Who needs full vs stub
+
+**Full** — luminaries that regularly dominate iteration decisions or
+prototype variants. Priority list evolves with use; current full-depth
+list includes: Prater, Norman, Cooper, Garrett, Lupton, Walter, Tidwell,
+Ive, Rams, Tufte, Morville, Fowler, Evans, Beck, Gang of Four, Robert
+C. Martin, Simon Brown, plus 5–15 others who qualify.
+
+**Stub** — legitimate references that inform but rarely dominate:
+historical figures, field-specific specialists, tool/system-level
+references (Apple HIG, Conventional Commits, DORA Team, etc.).
+Frontmatter + signature + core methods + sources is the minimum bar.
+
+### Review cadence
+
+Luminary files should be reviewed when:
+- A new iteration selects them as primary_luminary (opportunity to
+  upgrade stub → full if used in anger)
+- A POA prototype sprint uses them and the decomposition reveals gaps
+- bassclef/standards changes affect how we describe stack translation
+
+No fixed review cadence; review is event-driven.
+
+---
+
+---
+
+## Schema
+
+Add a `luminaries` block to `substrate.config.md`:
+
+```markdown
+## Luminaries
+luminaries:
+  add:
+    designer: [Dieter Rams, Massimo Vignelli]
+    builder: [Kent Beck]
+  remove:
+    builder: [Gang of Four]
+  replace:
+    creative-director: [Apple HIG, Dieter Rams]
+```
+
+Agent names match the lowercase agent role: `designer`, `builder`,
+`architect`, `pm`, `shaper`, `reviewer`, `creative-director`, `deployer`,
+`closer`, `orchestrator`.
+
+### Operations
+
+| Operation | Meaning |
+|-----------|---------|
+| `add` | Bassclef defaults + these additional luminaries |
+| `remove` | Bassclef defaults minus these luminaries |
+| `replace` | Ignore bassclef defaults — use only these luminaries |
+
+Operations compose in order: `replace` wins if present, otherwise
+`add` and `remove` both apply to the bassclef defaults. A single
+agent can appear in `add` and `remove` simultaneously — the result is
+`(defaults + add) - remove`.
+
+If no `luminaries` section exists in `substrate.config.md`, bassclef
+defaults are used unchanged.
+
+---
+
+## Per-phase overrides (advanced)
+
+An agent's luminary set can differ by phase:
+
+```markdown
+luminaries:
+  add:
+    designer:
+      elaboration: [Sophia Prater]
+      construction: [Apple HIG]
+```
+
+When phase-keyed entries are present, the flat form is not valid for that
+agent — use phase keys consistently for clarity. If an entry for a phase
+is not provided, bassclef defaults apply for that phase.
+
+Per-phase overrides support `add`, `remove`, and `replace` for each phase
+key. The top-level agent name cannot mix flat and phase-keyed forms in the
+same operation:
+
+```markdown
+# Valid — consistent phase keys
+luminaries:
+  add:
+    designer:
+      elaboration: [Sophia Prater]
+      construction: [Apple HIG]
+
+# Invalid — do not mix flat and phase-keyed
+luminaries:
+  add:
+    designer: [Sophia Prater]          # flat
+    designer.construction: [Apple HIG] # phase-keyed — not supported
+```
+
+---
+
+## Merge algorithm
+
+The Orchestrator resolves the active luminary set for each agent during
+boot (step 1 of the boot sequence in `strategy/agent-choreography.md`).
+
+```
+function resolve_luminaries(agent, phase, config, bassclef_defaults):
+
+  if config.luminaries is empty:
+    return bassclef_defaults[agent]
+
+  base = bassclef_defaults[agent]
+
+  # Step 1: replace wins
+  if agent in config.luminaries.replace:
+    entries = config.luminaries.replace[agent]
+    if is_phase_keyed(entries):
+      base = entries[phase] if phase in entries else bassclef_defaults[agent]
+    else:
+      base = entries
+    # add/remove do not apply after replace
+    return base
+
+  # Step 2: add
+  if agent in config.luminaries.add:
+    entries = config.luminaries.add[agent]
+    additions = entries[phase] if is_phase_keyed(entries) else entries
+    base = base + additions
+
+  # Step 3: remove
+  if agent in config.luminaries.remove:
+    entries = config.luminaries.remove[agent]
+    removals = entries[phase] if is_phase_keyed(entries) else entries
+    base = [l for l in base if l not in removals]
+
+  return base
+```
+
+The bassclef defaults are the luminary lists defined in each agent
+definition file (`.claude/agents/{role}.md`). These are never modified by
+app-level config.
+
+---
+
+## Validation
+
+The Orchestrator warns (does not block) on these conditions:
+
+| Condition | Warning |
+|-----------|---------|
+| A name in `remove` does not match any bassclef default for that agent | `WARN: remove lists "[Name]" for [agent] but it is not in bassclef defaults` |
+| A `replace` set is empty | `WARN: replace for [agent] is empty — agent will have no luminaries` |
+| A phase key in a per-phase override does not match a known phase | `WARN: phase key "[phase]" in luminaries config is not a recognized phase` |
+
+Warnings surface in the boot report. They do not block execution.
+
+---
+
+## Boot report surface
+
+At boot (step 8 of `/autonomous start`), the Orchestrator reports the
+resolved luminary set per agent. See `strategy/agent-choreography.md`
+Section 1 for the boot report format.
+
+Format:
+
+```
+Active luminaries:
+  Designer:          Don Norman, Sophia Prater, Apple HIG (+2 from config)
+  Builder:           Martin Fowler, SOLID (-GoF, +Kent Beck from config)
+  Creative Director: Apple HIG, Dieter Rams (replaced from config)
+  Architect:         [bassclef defaults]
+```
+
+Agents using bassclef defaults without modification are shown with
+`[bassclef defaults]` — do not list every luminary for every agent at
+boot. Only show the delta annotation for agents that have overrides.
+
+---
+
+## Rationale
+
+Luminaries are not decorative. They determine which principles the agent
+applies when faced with trade-offs. A CRUD-heavy app repo may find GoF
+patterns too heavy for the Builder. A brand-focused creative sprint may
+want Dieter Rams over whatever bassclef defaults. A regulated industry
+repo may want explicit risk-oriented luminaries in the Architect slot.
+
+Bassclef cannot anticipate every project's aesthetic, technical, and
+domain needs. This standard makes the luminary layer composable — app
+repos add their perspective without forking agent definitions.
+
+The merge model (add/remove/replace) was chosen over a full override
+because:
+- Most repos want to tune, not replace, bassclef judgment
+- `replace` exists as an escape hatch for radically different contexts
+- Bassclef defaults remain the stable base — upgrades propagate to all
+  repos that don't override the changed luminary
+
+---
+
+## Example: app repo configuration
+
+```markdown
+## Luminaries
+luminaries:
+  add:
+    designer: [Dieter Rams, Massimo Vignelli]
+    builder: [Kent Beck]
+  remove:
+    builder: [Gang of Four]
+  replace:
+    creative-director: [Apple HIG, Dieter Rams]
+```
+
+This configuration:
+- Adds two visual-system thinkers to the Designer for a brand-heavy product
+- Adds Kent Beck's TDD emphasis to the Builder
+- Removes GoF from the Builder (this is a simple CRUD app — patterns overhead is not worth it)
+- Replaces Creative Director's entire luminary set with Apple HIG + Dieter Rams (full override for a minimalist product direction)

package/dist/lite/standards/pr-body-discipline.md

@@ -0,0 +1,115 @@
+---
+tier: lite
+description: PR bodies are public substrate. When bassclef (and bassclef) ship public, PR bodies become permanent public history visible to every adopter, contributor, and reader who follows a commit back to its PR. This standard documents the scrub discipline…
+---
+<!-- andon-allow: docs/operator-private/[a-z-]+/20[0-9][0-9]-[0-9]{2} -->
+
+# PR-body discipline — scrub before push
+
+PR bodies are public substrate. When bassclef (and bassclef) ship public, PR bodies become permanent public history visible to every adopter, contributor, and reader who follows a commit back to its PR. This standard documents the scrub discipline that applies to every PR body before push.
+
+## Scope
+
+Every PR opened against bassclef's main branch, regardless of authoring path:
+
+- Operator-direct authoring via `gh pr create`
+- Skill-authored PRs from /longrun, /sprint, /autonomous, /build, /promote, and any future PR-authoring skill
+- Agent-authored PRs in interactive sessions
+
+The discipline applies BEFORE push, not after merge. A PR body that lands public is harder to scrub than a PR body that gets revised before push.
+
+## Three scrub criteria
+
+### Criterion 1 — No operator-private path citations
+
+PR body refs and inline citations must not reference paths under `docs/operator-private/*`. Those paths are gitignored; citations point at files invisible to public readers. The citation tells the reader to consult evidence they cannot access — worse than not citing at all.
+
+Where the PR genuinely needs to cite a private path for completeness, use stub framing:
+
+| Avoid | Use |
+|---|---|
+| `per docs/operator-private/strategy/2026-05-25-locked-decisions.md` | `per internal strategic decision` |
+| `canvas at docs/operator-private/canvases/bassclef-public-launch-lean-canvas.md surfaced X` | `internal canvas walk surfaced X` |
+| `audit finding F-D9.1 at docs/operator-private/audits/2026-05-25-...md` | `audit finding F-D9.1 (audit HIGH)` |
+
+The stub preserves the substantive claim (an internal decision happened; a canvas walk surfaced something; an audit produced a finding) without exposing the specific operator-private path.
+
+### Criterion 2 — No operator-strategic deliberation as PR justification
+
+PR body justification frames mechanically: what the PR does + which acceptance criterion it closes + which downstream work it unblocks. Not: why the operator decided what they decided + the strategic-pivot reasoning + the alternatives considered.
+
+Specifically scrub:
+
+- Strategic pivot reasoning (e.g., "IP-protection-vs-growth-loop", "Tier 1 selection trade-offs")
+- Leap-of-faith framing (e.g., "LF1 Morgan-as-gatekeeper riskiest assumption analysis")
+- Canvas-walk findings exposition (the canvas surfaces what was found; the PR ships the mechanical change, not the canvas analysis)
+- Audit-finding internal reasoning (cite the finding number + the mechanical fix; don't re-expose the audit analysis)
+- Persona-divergence analysis (operator-strategic reasoning belongs in canvas/audit, not PR)
+
+Mechanical framing examples:
+
+| Avoid | Use |
+|---|---|
+| "Why now: the canvas-walk surfaced that ADR-021's framing contradicts the operator's locked growth-loop pivot. The canvas Revenue Streams box names HashiCorp-pattern downstream commercialization paths as option preserved, not roadmap committed — explicitly NOT an IP-protection play." | "Why now: amends language to reflect locked decision per 2026-05-25 strategic call." |
+| "Closes F-D9.1 (audit HIGH from /lean-canvas walk; Jamie reads the README hedge in 'Why this exists' as load-bearing weak signal; Sam adopts 'personal project that grew' mental model)" | "Closes audit finding F-D9.1 (README hedges audience)." |
+
+The reader of the public PR sees what changed + which acceptance criterion it closes. They don't see the operator's strategic deliberation; that deliberation lives in operator-private substrate where it belongs.
+
+### Criterion 3 — Plain-language gloss + /kiss pass per bassclef#790
+
+Apply the gloss-at-first-mention rule per `standards/operator-facing-prose-discipline.md` to all shorthand referenced in the PR body. Apply /kiss vocabulary substitution per `.claude/rules/plain-english-discipline.md` to remove bassclef-internal compound terms.
+
+This criterion composes with criteria 1 and 2: the scrub passes BOTH the operator-private check AND the plain-language check.
+
+## Scrub workflow
+
+Before `gh pr create` or `gh pr edit`:
+
+1. **Read the drafted PR body** as if reading it for the first time as a public adopter
+2. **Apply Criterion 1** — search for `docs/operator-private/` substrings; replace with stub framing or remove
+3. **Apply Criterion 2** — identify strategic-deliberation paragraphs; replace with mechanical framing
+4. **Apply Criterion 3** — gloss + /kiss pass per bassclef#790
+5. **Push the scrubbed body**
+
+The scrub is part of the same authoring cycle, not a separate review pass.
+
+## What this discipline does NOT require
+
+- **Scrubbing commit messages.** Commit messages are also public history but follow `commit-conventions.md` separately. Operator-private path citations in commit messages should also be avoided, but PR-body scrub is the primary surface this standard covers.
+- **Scrubbing operator-private files themselves.** Files under `docs/operator-private/*` stay as-is; they're gitignored. The scrub applies to PR bodies that reference them.
+- **Hiding the existence of operator-private work.** PR bodies can say "internal canvas walk produced this change" — what they can't do is cite the specific path.
+
+## Enforcement layers
+
+| Layer | Mechanism | Status |
+|---|---|---|
+| Methodology | This standard + `.claude/rules/operator-facing-prose.md` (bassclef#790 sibling rule) | Loaded into every session via `additionalDirectories` |
+| Skill-level | /longrun, /sprint, /autonomous SKILL.md cite this standard + run scrub before PR push | Lands in WU-4 + WU-5 of /longrun discipline-as-substrate (2026-05-30) |
+| Authoring discipline | Operator + agent self-scrub before push | Methodology-level |
+| Mechanical | bassclef#739 (substrate-coherence CI) extension lints PR bodies for `docs/operator-private/*` citations | Deferred — methodology-first |
+| /kiss PR-body hook | Advisory today; bassclef#786 decides hard-block vs advisory-with-skill-discipline | Pending operator decision |
+
+## Why this discipline matters
+
+The bassclef launch promise: "operators get a working methodology they can apply to their own products." PR bodies are part of the public substrate adopters read. If PRs cite operator-private paths and expose operator-strategic deliberation, three failure modes:
+
+1. **Adopter encounters broken citations.** "Per docs/operator-private/strategy/..." — adopter clicks through, finds nothing, loses trust in citation discipline elsewhere
+2. **Operator-private strategic context becomes public via PR-body archaeology.** Strategic pivots, leap-of-faith assumptions, alternative scenarios all leak via PR body history even though the source canvas is operator-private
+3. **PR review noise.** Reviewers read multi-paragraph strategic exposition when they need to evaluate a 3-line mechanical change
+
+Scrub discipline at push closes all three.
+
+## Surfaced in
+
+- PR #773 (ADR-021 amendment) — operator caught operator-private path citations + multi-paragraph strategic-pivot exposition in public PR body before merge. Operator manually scrubbed before merging.
+- Pattern recurs across /longrun-authored PRs from 2026-05-29 session; backlog: review prior PR bodies on bassclef for similar leakage.
+
+## Refs
+
+- bassclef#787 — parent ticket
+- bassclef#769 — canvas-path discipline (same principle for canvas file location)
+- bassclef#790 — operator-facing-prose discipline (gloss + /kiss pass; composes with this standard)
+- bassclef#786 — /kiss PR-body hook enforcement decision (mechanical layer for criterion 3)
+- bassclef#739 — substrate-coherence CI (extension surface for mechanical lint)
+- `.claude/rules/plain-english-discipline.md` — master plain-English rule
+- `standards/operator-facing-prose-discipline.md` — gloss rule + /kiss pass on SKILL.md edits