@thebassclef/lite 0.0.1 → 0.1.0

package/substrate/.claude/rules/identifier-leak-prevention.md

@@ -0,0 +1,104 @@
+---
+tier: lite
+description: Bassclef commits stay free of operator machine identifiers.
+---
+
+<!-- andon-allow: [A-Za-z][A-Za-z0-9]*-MacBook-(Air|Pro) -->
+<!-- andon-allow: /Users/[a-z][a-z0-9._-]+ -->
+<!-- andon-allow: /home/[a-z][a-z0-9._-]+ -->
+
+# Identifier leak prevention
+
+Bassclef commits stay free of operator machine identifiers.
+
+INSTEAD of committing hostname strings (X-MacBook-Air, DESKTOP-XYZ, X-server-N), absolute paths starting with /Users/ or /home/, or any operator-identifying metadata: rewrite the message or content with placeholders (branch name, `<machine>`, `$HOME`) before commit.
+
+This rule is the methodology layer. The mechanical layer is `.claude/hooks/pre-commit-identifier-leak-scrub.sh` (PreToolUse Bash matcher on `git commit`). Both required.
+
+## Why this rule exists
+
+Coverage gap surfaced by outside consult on 2026-09-01 (issue sunj-labs/bassclef#1471). Existing leakage scans (release-script andon + operator-private-path-check) target directory references, not identifier strings. Auto-save-checkpoint commits interpolated hostname into every message — 98 such commits landed on bassclef-upstream main + spread to public bassclef via archive snapshots.
+
+CCF-3 keeps operator config gitignored and out of git history.
+INSTEAD of assuming that discipline holds at the .gitignore layer alone: enforce at the commit boundary via this hook + rule pair. Both layers close the loop between principle and mechanism.
+
+## When this rule fires
+
+Every `git commit` invocation across bassclef and adopter repos. The hook scans:
+
+1. Commit message text (parses `-m "..."` arg)
+2. Staged content (`git diff --cached`)
+
+Fires on PreToolUse Bash matcher when `tool_input.command` starts with `git commit`. Non-git-commit commands pass through cleanly.
+
+## What the rule requires
+
+No commit lands with these patterns in message OR staged content:
+
+- **Hostname shapes**: `[A-Za-z][A-Za-z0-9]*-MacBook-(Air|Pro)`, `DESKTOP-[A-Z0-9]{4,}`, `*-server-*`, `*-desktop-*`
+- **Absolute paths**: `/Users/<name>`, `/home/<name>`
+
+Extension mechanism — future pattern classes added to the hook's `IDENTIFIER_PATTERNS` regex + a corresponding Tier 0 test.
+
+## Anti-patterns
+
+**Auto-save-checkpoint commits with hostname suffix.**
+
+INSTEAD of interpolating `$(hostname -s)` into the commit message per `save-state.sh` historical L222-225 shape: use branch name + file count only. Session identity moves to commit trailer if debug needed locally.
+
+**LAST_SAVE file with `machine:` field.**
+
+INSTEAD of writing machine identifier into `.claude/LAST_SAVE`: either gitignore the file OR drop the `machine:` field. This ticket takes both paths — gitignore the file + drop the field.
+
+**state/markers/ tracked in git.**
+
+INSTEAD of selectively-gitignored marker subdirs (contradicts `session-artifacts.md` L14-25): broad `state/markers/` gitignore + `git rm -r --cached state/markers/` one-time cure. Adopters inheriting the sync run the same cure once.
+
+## Override path
+
+`SKIP_IDENTIFIER_LEAK_SCRUB=1 git commit ...` — logged via trace-helper. Rare use cases:
+
+- Documentation explaining what patterns to avoid (e.g., this rule body cites the pattern class)
+- Migration scripts that intentionally reference historical hostname strings
+- Emergency rescue where the hook itself misbehaves
+
+INSTEAD of routine overrides: rewrite the commit or content. The cost is small; the discipline compounds across every future commit.
+
+## Adopter cure (one-time)
+
+Adopters running bassclef-sync after this rule ships see one-time drift. Existing `state/markers/*` files stay tracked in their index but ignored by the new .gitignore.
+
+Cure:
+
+```bash
+git rm -r --cached state/markers/
+git commit -m "chore: untrack state markers per bassclef identifier-leak-prevention rule"
+```
+
+The working-tree files stay. Only the git index changes.
+
+## Composes with
+
+- `.claude/rules/session-artifacts.md` (L14-25 — state/markers gitignore intent this rule enforces)
+- `.claude/rules/blocked-items.md` (BLOCK protocol the hook fires)
+- `.claude/rules/testing-tier-config.md` (Tier 0 strict TDD on the hook + tests)
+- `.claude/rules/hook-wire-on-author.md` (settings.json wiring discipline)
+- `.claude/rules/bootstrap-pair-discipline.md` (hook + rule + test + wire ship together)
+- `.claude/rules/we-dont-break-adopters.md` (adopter cure documented above)
+- `.claude/hooks/pre-commit-identifier-leak-scrub.sh` (mechanical implementation)
+- `.claude/hooks/tests/pre-commit-identifier-leak-scrub.test.sh` (12-test coverage)
+- @luminary saltzer-schroeder — complete mediation
+- @luminary linus-torvalds — adopter contract (ADR-031)
+- @luminary michael-feathers — characterization tests
+- @luminary michael-nygard — stability pattern (fail-soft on grep missing)
+
+## Refs
+
+- Parent ticket: sunj-labs/bassclef#1471
+- Rule intent source: `.claude/rules/session-artifacts.md` L14-25
+- Mechanism gap: `scripts/release-to-bassclef.sh` L257-289 (andon scan scoped to dirs)
+- Hostname source: `.claude/hooks/save-state.sh` L222 + L247
+
+## Retirement condition
+
+This rule retires only if bassclef stops committing content that could contain identifiers. Every commit is a potential leak surface, so retirement is unlikely. Pattern set may evolve as new operator-identifying shapes surface; the discipline of scanning at commit time persists.

package/substrate/.claude/rules/lite-manifest-schema-change-discipline.md

@@ -0,0 +1,98 @@
+---
+tier: lite
+description: Every lite-manifest schema change ships a migration-note ledger entry in the same PR. Adopters read the ledger before sync.
+---
+
+# Lite-manifest schema-change discipline
+
+Every change to `standards/lite-manifest.schema.json` (schema shape) or to the output shape of `<tier>-manifest.json` (extractor emissions) MUST ship with a matching ledger entry in `standards/lite-manifest-schema-changes.md` in the same PR. The release script blocks the cascade if the ledger has no entry for the outgoing `manifest_version`.
+
+This rule is the methodology layer. The mechanical layer is a pre-flight check in `scripts/release-to-bassclef.sh` (Step 3.6, added in goal 2026-09-07c Step 4). Both required.
+
+Sister discipline to `.claude/rules/file-rename-discipline.md`. Same shape at a different surface — files there, schema fields here.
+
+## Why this exists
+
+`v0.36.0` (2026-09-06) dropped `upstream_commit` from lite-manifest content per sunj-labs/bassclef-upstream#1508. Three bassclef-web scripts crashed at next sync because they read `.upstream_commit` and got `undefined`. No note warned adopters. bassclef-web#269 promoted the pattern.
+
+Every adopter of the lite manifest sits on this class. Without a ledger discipline, every future schema change replays the failure.
+
+## When this rule fires
+
+Any PR that touches:
+
+- `standards/lite-manifest.schema.json` (schema shape)
+- `scripts/generate-lite-manifest.sh` in a way that changes the output shape (adds or removes emitted keys)
+
+Skips:
+
+- Content-only manifest regens (backfill helper adds descriptions to source files; content_hash changes but no schema shift)
+- Comment-only edits to schema or extractor
+
+## What the rule requires
+
+When a PR changes the manifest schema OR output shape:
+
+1. **Ledger entry** — add a new entry to `standards/lite-manifest-schema-changes.md` in the same PR. Format per the ledger's format section. Newest-first ordering.
+2. **Version bump** — pin the entry to a specific `manifest_version` bump. Per the schema title description policy:
+   - Adding an optional field → MINOR bump
+   - Adding a required field → MAJOR bump (breaking)
+   - Removing a field → MAJOR bump
+   - Content-only change → PATCH bump
+3. **Downstream cure named** — the entry names what adopters need to do. If nothing (backward-compatible add), say so explicitly. If code change (like the v0.36.0 `upstream_commit` removal), name the pattern.
+4. **Release script pre-flight** — before every `/release`, the script reads the ledger and confirms an entry exists for the outgoing `manifest_version`. Missing entry BLOCKs the cascade.
+
+## Anti-patterns
+
+**Schema field added but no ledger entry.** Release script pre-flight BLOCKs.
+INSTEAD: add the entry in the same PR.
+
+**Ledger entry written but wrong version bump.** Adopters plan their pin update against the wrong version.
+INSTEAD: correct the bump before merge. AJV validation of the entry format catches inconsistency.
+
+**Downstream cure vague (no name for the class).** Adopters at cold-sync can't reason about which script needs fixing.
+INSTEAD: cite the class + link to a reference cure like bassclef-web c9a9da7.
+
+**Schema change ships without adopter coordination.** Even with a ledger entry, adopters that exact-pin the manifest_version need advance warning.
+INSTEAD: coord comment on bassclef-web#256 + bassclef-cli#51 BEFORE the release cascade per Linus L6 pre-mortem cure.
+
+## Override
+
+`SKIP_LITE_MANIFEST_SCHEMA_LEDGER=1 <command>` — logged via trace-helper. Use only when:
+
+- The schema change is a comment-only edit that keeps the shape stable
+- The change reverses a prior entry (a rollback) and the prior entry names both the change and the rollback
+- One-shot migration script that touches the schema during a migration window
+
+INSTEAD of overriding for routine work: write the entry. The cost is small (one section in the ledger); the discipline compounds across every adopter that syncs.
+
+## Composes with
+
+- `.claude/rules/file-rename-discipline.md` — sister at the file surface
+- `.claude/rules/we-dont-break-adopters.md` — parent discipline (ADR-031)
+- `.claude/rules/cold-adopter-harness-discipline.md` — sibling smoke fires against ledger entries before release
+- `.claude/rules/bootstrap-pair-discipline.md` — this rule + hook + tests + settings wire ship together
+- `.claude/rules/testing-tier-config.md` — Tier 0 strict TDD on ledger format tests
+- `.claude/rules/blocked-items.md` — BLOCK protocol the release-script pre-flight fires
+- `standards/lite-manifest.schema.json` — the schema this ledger tracks
+- `standards/lite-manifest-schema-changes.md` — the ledger this rule enforces
+- `scripts/release-to-bassclef.sh` — release-script pre-flight (Step 3.6)
+- ADR-031 (we-don't-break-adopters)
+- ADR-029 (release pipeline)
+- @luminary linus-torvalds — lead. Adopter contract; the ledger is the operational form of Torvalds's rule at the schema surface
+- @luminary tony-hoare — pre/postcondition contract on schema changes
+- @luminary michael-nygard — stability pattern (block-on-missing-entry)
+- @luminary michael-feathers — characterization test on the ledger format
+
+## Refs
+
+- Parent ticket: sunj-labs/bassclef-web#269 (promote: ship migration notes when lite-manifest schema removes or renames fields)
+- Root cause: v0.36.0 upstream_commit removal broke 3 bassclef-web scripts (commit `c9a9da7` on bassclef-web repaired downstream)
+- Goal: `docs/iteration-bets/2026-09-07c-lite-manifest-schema-plus-extractor-plus-backfill-plus-ledger.md`
+- Risk ledger: `docs/risk-ledgers/2026-09-07c-lite-manifest-schema-extractor-backfill-ledger.md` Linus L6 + Hoare H6
+- Sister rule: `.claude/rules/file-rename-discipline.md`
+- @luminary linus-torvalds — Torvalds's rule at the schema surface
+
+## Retirement condition
+
+This rule retires only if bassclef stops shipping a lite manifest. Adopter count and change cadence may evolve; the discipline of documenting every schema change at the PR that ships it persists.

package/substrate/.claude/rules/oo-ad-entry-point.md

@@ -0,0 +1,117 @@
+---
+tier: lite
+globs: ["src/**/*.ts", "src/**/*.tsx", "src/**/*.js", "src/**/*.py", ".claude/hooks/*.sh", "lib/*.sh", "scripts/*.sh"]
+description: OOA/D entry point — /decompose must fire for all Construction work, not just canvas-driven flow. Extended per bet 24a to cover hook + lib + script code paths per Cockburn ceremony tiering matrix.
+---
+
+# OOA/D Entry Point Rule
+
+Construction work that modifies `src/` source files OR substrate code
+(`.claude/hooks/*.sh`, `lib/*.sh`, `scripts/*.sh`) MUST have `/decompose`
+evidence in the session before the first substantive commit. This applies
+regardless of the starting artifact — canvas, spec, epic, defect ticket,
+or bug report.
+
+Ceremony scales with code class per Alistair Cockburn's use-case tiering
+(skip / casual / brief / fully-dressed). Table amended per canvas
+`docs/canvases/2026-08-25-ooad-chain-as-substrate-offering.md` Axis 1 —
+adds a skip row at the top and lifts new substrate hook/lib to fully-dressed
+with ADR consult per Ousterhout + Beck + Brooks convergence:
+
+| Code class | Ceremony minimum | Artifact path |
+|---|---|---|
+| Typo, comment fix, doc edit | Skip. No chain fires. | — |
+| One-line change inside existing function | Casual use case sentence in commit body | Commit body |
+| Existing code extension (add arg, add case) | Brief use case + /decompose entry-point check | `docs/use-cases/UC-*.md` (brief) |
+| Adopter app code (`src/*.ts`, new module or route) | Fully-dressed use case + /decompose + /spec | `docs/use-cases/UC-*.md` |
+| Substrate hook (new `.claude/hooks/*.sh`) | Fully-dressed use case + /decompose + ADR consult | `docs/use-cases/UC-hook-*.md` |
+| Substrate lib (new `lib/*.sh` module) | Fully-dressed use case + /decompose + ADR consult | `docs/use-cases/UC-lib-*.md` |
+| Adopter-facing script (new `scripts/*.sh`) | Brief use case + Tier 0 tests | `docs/use-cases/UC-script-*.md` |
+
+Cockburn's rule — ceremony scales with the audience for the artifact.
+Fully-dressed reads by future maintainers, testers, product folks. Brief
+reads by devs on the same team. Casual reads by the author six weeks later.
+
+Bet 24a extended the trigger to substrate code paths so hooks + libs +
+scripts get the same design-first discipline that adopter app code gets.
+Per Feathers legacy-code retrofit — characterization tests come first for
+existing code; brief use case follows the tests.
+
+## Why this rule exists
+
+The `/decompose` skill catches the Langfuse-inside-HaikuImputer class
+of mistakes: cross-cutting concerns (observability, testability,
+extensibility, security, cacheability) bolted into implementations
+instead of resolved as Decorators wrapping interfaces.
+
+Recurring pattern: when Construction starts from a canvas, the UX
+translation chain (canvas → spec → ia-model → interaction-design →
+sequence diagrams → /decompose) runs naturally. When it starts from
+an epic or bug, agents jump to implementation and skip /decompose
+entirely — reproducing the exact failure mode the skill was built
+to prevent.
+
+Evidence:
+- POA 2026-04-09: Langfuse tracing bolted into HaikuImputer instead
+  of wrapping AssociationImputer facade
+- POA 2026-04-12: Credit-tracking logic added inline to scraper-api.ts
+  instead of ScraperMetricsDecorator wrapping interface (epic #472)
+
+Both were epic-driven (no canvas). /decompose was skipped.
+
+## What triggers the rule
+
+Creating changes to `src/` files on a Construction branch
+(`feature/*`, `fix/*`) without prior /decompose evidence.
+
+## What satisfies the rule
+
+One of:
+
+1. **Decomposition artifact** at `docs/decompositions/[slug].md` or
+   inline in the spec, produced by running `/decompose`.
+2. **Explicit trivial-work deferral**: "Skipped /decompose — trivial
+   change, no responsibility reassignment" stated in session.
+3. **Bug-hotfix deferral**: "Skipped /decompose — hotfix, diagnosis
+   identified specific failure site, no cross-cutting concerns
+   involved" stated in session.
+
+Silence is not deferral (per blocked-items rule).
+
+## Entry-point variants (per /decompose)
+
+- State 1 (canvas path): sequence diagrams drive decomposition
+- State 2 (epic/defect): reverse-engineer from spec + current code
+- State 3 (bug/hotfix): decompose the failure site, identify missing
+  interface/decorator
+
+All three produce the same artifact format; agents must not skip the
+skill just because the input shape differs from State 1.
+
+## Enforcement
+
+This rule ships at `tier: lite` — every adopter tier loads the discipline as methodology guidance.
+The mechanical BLOCK layer ships at `tier: standard`:
+
+**Methodology layer (all tiers — lite, standard, ultra).**
+Rule loads in session context. Agents self-check at Construction branch creation per the ceremony matrix above.
+
+**Mechanical layer (standard, ultra only).**
+Hook at `.claude/hooks/oo-ad-entry-point-check.sh` (bassclef-upstream#1169) fires on PreToolUse Edit/Write against paths in the frontmatter globs. It BLOCKs new-file writes when the required artifacts are missing.
+
+The hook checks two conditions:
+- Decomposition — marker at `state/markers/decompose/<branch>.marker` OR any file under `docs/decompositions/`
+- Use case — matching `docs/use-cases/UC-*.md` per code class (UC-hook-*, UC-lib-*, UC-script-*, or unprefixed UC-*)
+
+Existing file Edit passes through (Cockburn casual tier — commit body carries the discipline).
+Override: `SKIP_OO_AD_ENTRY_POINT=1` logged via trace-helper.
+
+**Lite adopter behavior.** Rule guides ceremony choice; no BLOCK fires on lite. Canvas Axis 1 (docs/canvases/2026-08-25-ooad-chain-as-substrate-offering.md) applied Ousterhout + Beck + Brooks lens — mechanical enforcement fits standard+ scope. INSTEAD of BLOCK on lite: rule guidance shapes agent behavior at construction branch creation. Methodology guidance benefits all adopters; mechanical BLOCK is standard+ scope.
+
+## Relationship to other rules
+
+- `sdlc-gates.md` Pre-Build section — temperance + diagnosis gates
+  fire before this one
+- `blocked-items.md` — entry-point skip is a BLOCKED condition; resolve
+  or explicitly defer
+- `testing.md` — new interfaces identified via /decompose need tests

package/substrate/.claude/rules/operator-facing-prose.md

@@ -0,0 +1,196 @@
+---
+tier: lite
+description: Any shorthand in operator-facing prose carries a plain-language gloss at first mention per response.
+---
+
+# Operator-facing prose
+
+Any shorthand in operator-facing prose carries a plain-language gloss at first mention per response. When editing any SKILL.md file, apply a /kiss pass to the whole file in the same change.
+
+This rule is the conversation layer of `standards/operator-facing-prose-discipline.md`. The standard names the principle, the format catalog, and the reasoning about who reads the output. This rule loads into every session via `additionalDirectories` and fires at every operator-facing response.
+
+## When this rule fires
+
+Fires on every response the operator reads: skill tool output, turn prose between the agent and the operator, status reports, checkpoint summaries, recommendations.
+
+Skips:
+- Raw tool output relays (git, gh, test output passed through)
+- Code blocks
+- File path quotations
+- Reserved skill names (e.g., `/sprint`, `/longrun`) — operator-invocable; the prefix carries the context
+
+## Rule 1 — Gloss at first mention per response
+
+Any shorthand label carries a brief inline gloss on first mention per response IF a reader coming in cold would need context to know what the label refers to. Subsequent mentions in the same response can drop the gloss.
+
+A shorthand label is any compressed reference — number, letter, category name, path token — that stands in for a longer concept the reader may not carry.
+
+### What an appositive is (Ship 2 amendment 2026-08-20 per bassclef-upstream#1313)
+
+An appositive is a comma plus a noun (or noun phrase) that renames, explains, or gives more information about the shorthand. It can appear at ANY mention that carries meaning-signal to the reader — not only the first. Three shapes all satisfy this rule:
+
+- **Parenthetical** — `<shorthand> (<noun phrase>)` — e.g., `#1312 (in-line 8th-grade steering for sentence-level grade output)`
+- **Comma phrase** — `<shorthand>, <noun phrase>,` — e.g., `PR #1316, the in-line 8th-grade steering merge,`
+- **Em-dash** — `<shorthand> — <noun phrase> —` — e.g., `Bucket B6 — the schema tests bucket —`
+
+**Critical: the appositive text must be understandable to a cold reader.** Using session shorthand INSIDE the appositive (e.g., `#1312 (Ship 1 sentence-level grade output)`) defeats the whole purpose. A cold reader has no idea what "Ship 1" means. The appositive should translate the shorthand into plain concepts the reader already carries — what the ticket delivers, what the merge changes, what the bucket contains.
+
+Session-2026-08-19g operator correction (verbatim): "an appositive is not just first gloss; a common definition is a comma + a noun or noun phrase that renames, explains, or gives more information about the shorthand you use". Follow-up correction (same session) after I shipped examples that used session shorthand inside the appositive: my examples "simply extend the obfuscation" — the appositive must land in plain terms, not another compressed reference.
+
+Rationale: the `first-mention` scope in the original rule was too narrow. Readers benefit from a comma phrase at any mention where the shorthand carries meaning. The appositive is the moment where the shorthand gets translated, so the translation itself must be in plain vocabulary.
+
+Mechanism per bassclef-upstream#1313 Ship 2: `.claude/hooks/turn-prose-kiss-check.sh`, the Stop hook that scans the last message, checks each shorthand match for an adjacent appositive within 40 characters (any of the three shapes above). The hook checks structural presence only — it cannot verify that the appositive text itself is plain. Operator judgment catches shorthand-inside-appositive; the hook catches missing-appositive. Advisory in V1; flips to strict after one calibration cycle with false positive rate under 5%.
+
+### Two shorthand shapes this rule covers
+
+**1. Bassclef substrate shorthand families (fixed catalog).** These families always need a gloss because the reference is substrate-specific:
+
+- Step refs: `WU-N`, `B1-WU4`, `Bet 2 WU-1`
+- Audit finding refs: `F-X.Y`, `F-D9.1`, `F-D11.1`
+- ADR refs: `ADR-NNN`, `ADR-021`, `ADR-022`
+- GitHub issue and PR refs: `#NNN`, `bassclef#NNN`, `PR #NNN`
+- Leap-of-faith and chain-of-beliefs refs: `LF-N`, `LF1`, `LF5`
+- Phase and iteration refs: `Phase XIV`, `Iteration 2026-05-24c`
+
+**2. Session-invented shorthand (open-ended).** Labels that get coined mid-session — audit bucket names, cure path letters, session-position abbreviations, option letters — always need a gloss because the reference exists only in the session that invented it. A reader picking up the response cold has no way to decode the label without help.
+
+Examples of session-invented shorthand this rule extends to:
+
+- `Bucket 2a`, `Bucket 2b`, `Bucket 3` — audit classification labels
+- `Path A`, `Path B`, `Path C` — cure option letters in a matrix
+- `Part A`, `Part B` — commit-split labels
+- `S2`, `S3`, `S4` — session-position abbreviations in a multi-session sequence
+- `Option a`, `Option b`, `Option F` — decision menu letters
+- `LR-1`, `LR-2` — long-run sequence position
+
+Reserved names per bassclef#763 stay as is: `substrate`, `bassclef`, `cameo`, `Studio`, `Band`, `bandleader`.
+
+### Format
+
+INSTEAD of unglossed shorthand: gloss inline at first mention. Format: `<shorthand> (<appositive — 3-8 words naming what the shorthand refers to>)`.
+
+An appositive is a short phrase right after the label that renames or explains it. It carries the meaning-signal the label alone lacks.
+
+### Worked examples
+
+Substrate-family shorthand (unchanged from prior rule):
+
+- `B1-WU4 (Tier 0 pitch draft using canvas UVP)` — gloss inline
+- `#774 (Phase XIV rescope proposal)` — gloss inline
+- `F-D9.1 (README hedges audience — audit HIGH)` — gloss inline
+
+Session-invented shorthand (added per bassclef-upstream#1267):
+
+- `Bucket 2a (audit files with no tier tag at all)` — instead of bare `Bucket 2a`
+- `Path B (inline the skill into its caller)` — instead of bare `Path B`
+- `Part A (reconcile the 20 known missing files)` — instead of bare `Part A`
+- `S2 (Session 2 — Traceability Phase 1 per LR-1 roadmap)` — instead of bare `S2`
+- `Option F (swap bassclef-sync ln -s for cp)` — instead of bare `Option F`
+- `LR-1 (long-run 1 — tier ecosystem sequence)` — instead of bare `LR-1`
+
+### When the gloss adds no signal
+
+Skip the gloss when the label is self-explanatory to a cold reader — a full word already carries the meaning. Examples: `Session 2 Traceability` (no gloss needed; the label IS the description); `Option F: bassclef-sync copy swap` (already glossed inline by the phrase after the colon).
+
+INSTEAD of mechanical inflation when the gloss makes a sentence unreadable: restructure the sentence. The principle is operator readability, not mechanical glossing.
+
+### Forward-only enforcement
+
+Existing prose in chronicles, session logs, and closed PRs stays as is per `.claude/rules/we-dont-break-adopters.md` grace window discipline. Rule applies to new prose from amendment date forward.
+
+## Rule 2 — /kiss pass when editing any SKILL.md
+
+When touching any SKILL.md file for any reason, apply a /kiss pass to the entire file in the same change.
+
+INSTEAD of shipping a discipline change that itself contains bassclef jargon: rewrite the existing dense language in the same change. Otherwise the discipline breaks itself.
+
+Allowlist per bassclef#763 stays: `substrate`, `bassclef`, `cameo`, `Studio`, `Band`, `bandleader`. Everything else: grade-8 English, subject-verb-object, no bassclef compound terms (`load-bearing`, `cross-cutting`, `forcing function`, `substrate-resident`, `operator-locked`, `operating thesis`, `compose-with`, `tier-preset`, `operationalize`, `composer` as a noun).
+
+INSTEAD of shipping the edit with the jargon intact when scope is tight: file a dedicated /kiss-pass PR. The next reader inherits the failure otherwise.
+
+## Rule 3 — Skill dispatch citation on /longrun surfaces
+
+Per bassclef-upstream#374 (V2 of #366) and bassclef-upstream#750 (V3 opener discipline). Every /longrun surface where the agent talks with the operator MUST open with three blocks per `standards/opener-discipline.md`:
+
+- Problem (via `/state-a-problem brief`)
+- Value prop (via `/value-prop tweet`)
+- Evidence (source + warrant per `.claude/rules/assert-only-after-verify.md`)
+
+Every named surface also cites the dispatched skill inline (e.g., "via `/value-prop tweet`", "(per `/temperance`)", "drafted by `/state-a-problem brief`") OR carries a short discipline-marker line ahead of the prose.
+
+Named surfaces this rule covers:
+
+- `longrun_prep_proposal` — `/longrun prep` Step 0 opener + Step 1 pre-flight + Step 1.5/1.6/1.7 shape proposals
+- `longrun_checkpoint` — `/longrun checkpoint` opener + status report
+- `longrun_closeout` — `/longrun closeout` opener + retro lead-in
+- `status_update` — any /longrun status update or progress report between steps
+
+The agent touches `state/markers/turn-prose-surface/<surface>.marker` BEFORE posting the named surface. The Stop hook `turn-prose-kiss-check.sh` reads the marker and scans the latest assistant message for the skill dispatch citation. ADVISORY in V1 (per bassclef-upstream#374 acceptance); BLOCK in V2 after one calibration cycle.
+
+INSTEAD of writing prose without citing the dispatched skill: dispatch the skill (`/state-a-problem brief`, `/value-prop tweet`, `/kiss words`, `/temperance`, `/luminary`) and cite it inline. Touching the marker without dispatching the skill is the failure pattern this rule closes (bet 25k chronicle § "What didn't work — the diagnosis interlude" named 5 surfaces this rule covers).
+
+Surface citation format examples:
+
+- Problem lead: `> **Problem (via `/state-a-problem brief`)**: <who + what + when + why now + outcome>`
+- Value prop: `> **Value prop (via `/value-prop tweet`)**: <claim + sharpener>`
+- Evidence: `> **Evidence**: Source `<path or ticket>`. Warrant: <one sentence tying source to claim>.`
+- Temperance answer: `**/temperance** fired at <surface>. <scope-decision>. <drift-trigger>.`
+- Luminary pick: `**/luminary** primary lens `<slug>` — <one line on what the lens caught>.`
+- Status update: opens with `> **Checkpoint via `/longrun checkpoint`**: <one line>` OR carries a `## /temperance + /luminary + /loop discipline` block per bet 25k.
+
+Grace window per `.claude/rules/we-dont-break-adopters.md` — the prior opener shape (`/value-prop flash` + `/kiss words`) keeps working through 2026-10-31. New sessions open with the three blocks. Sessions from before the rewrite still open with tweet + KISS.
+
+## Why this rule exists
+
+The operator works across gaps between sessions. A morning /sprint response that references `B1-WU4` without a gloss forces the operator to remember the reference from yesterday, reconstruct it from the substrate, or ask the agent to expand it. All three cost operator time.
+
+The /kiss-pass-on-SKILL.md-edits rule closes the second-order gap. When the substrate says "operator-facing output should be plain" and its own body carries dense bassclef jargon, the discipline breaks itself.
+
+INSTEAD of relying on operator vigilance to catch unglossed refs and dense SKILL.md prose: the substrate enforces clarity at authoring time. Operator time saved compounds across every reference in every response.
+
+## Composes with
+
+- `.claude/rules/plain-english-discipline.md` — master plain-English rule; this rule extends with the gloss and the /kiss-pass second-order rule
+- `.claude/rules/skill-description-clarity.md` — narrow case at the skill description field
+- `.claude/rules/github-issue-flash-tweet.md` — flash-tweet-then-detail discipline for GitHub issue bodies
+- `.claude/rules/context-engineering.md` — INSTEAD-block discipline for negations
+- `.claude/rules/visual-hierarchy.md` — formatting discipline for long agent output
+- `standards/operator-facing-prose-discipline.md` — companion standard with the full reasoning and the format catalog
+- `standards/pr-body-discipline.md` — applies the gloss and the /kiss pass to PR bodies (criterion 3 of the scrub)
+
+## 5-layer defense for prose discipline (added bet 27c WU-9)
+
+The prose-discipline rules and mechanisms form 5 layers per ADR-035 (hooks as steering). Each layer fires at a different surface. Together the layers act as belt and suspenders — they cover failure modes that any single layer would miss.
+
+| Layer | Surface | Mechanism | What it catches |
+|---|---|---|---|
+| 1. Per-edit on substrate paths | PreToolUse `Edit\|Write` on `.claude/skills/*/SKILL.md` + `.claude/rules/*.md` + `.claude/luminaries/*.md` | `substrate-clarity-gate.sh` | Skill description over 280 chars, missing INSTEAD-block, jargon BLOCK terms (bassclef#382) |
+| 2. Per-edit on PR body | PreToolUse `Bash` matching `gh pr create` or `gh pr edit --body` | `pre-gh-pr-body-scrub.sh` | BLOCK terms in PR body before push (bassclef#1176) |
+| 3. Per-edit on issue body and commit msg | PreToolUse `Bash` matching `gh issue create` or `git commit` | `pre-gh-issue-body-scrub.sh` + `pre-git-commit-msg-scrub.sh` | BLOCK terms before issue file or commit lands (bassclef#1177) |
+| 4. Per-turn-end (operator prose) | Stop event | `turn-prose-kiss-check.sh` | BLOCK terms in the latest assistant message; surface-marker-driven strict escalation (bassclef#1051 + #1304) — cured via bet 27c PR #427 for path resolution under operator install |
+| 5. Per-PR (CI) | PR body clarity + scrub jobs | `.github/workflows/bassclef-pr-ci.yml` jobs | Backstop for PR body BLOCK terms that bypassed layer 2 |
+
+Together: layers 1-3 catch at write time. Layer 4 catches at turn end. Layer 5 catches at PR review. The kiss path-resolution cure (PR #427) closed the silent fail under operator-install layout that broke layer 4. The substrate-as-system rule (ADR-035) commits to all 5 layers staying operational. Mechanism-fidelity verification (bet 27c WU-4, WU-5, WU-6) audits the operational state.
+
+## Override
+
+`SKIP_OPERATOR_FACING_PROSE=1 <command>` — for genuine cases (quoting an exact phrase from memory or an external doc; mid-debugging session where formality breaks flow). Logged via trace-helper. Use rarely.
+
+INSTEAD of overriding the /kiss pass on SKILL.md edits when scope is tight: file a dedicated /kiss-pass PR per Rule 2 above. The second-order rule holds without exception.
+
+## Surfaced in
+
+- /sprint 2026-05-30 morning session — operator returned after an overnight gap and surfaced that shorthand references in /sprint output need a plain-language gloss for cross-session orientation.
+- Same session — operator surfaced the second-order rule: if we are already authoring SKILL.md updates for the gloss rule, the existing jargon in those files gets rewritten in the same pass.
+
+## Refs
+
+- bassclef#790 — parent ticket (this rule + companion standard)
+- bassclef#785 — tweet-style descriptions in /longrun summary tables
+- bassclef#780 — glossary + substrate-quote discipline (session-start glossary; this rule adds the at-mention gloss)
+- bassclef#763 — /kiss reserved-name allowlist
+- bassclef#767 — /kiss hook coverage at artifact-write surfaces
+- bassclef#779 — /kiss interactive-session anchoring at turn-counter boundaries
+- bassclef#786 — /kiss PR-body hook enforcement decision
+- bassclef#787 — PR-body scrub discipline (this rule's criterion 3 surface)
+- bassclef#739 — substrate-coherence CI (mechanical enforcement target)