@thebassclef/lite 1.0.4 → 1.1.0

package/dist/lite/.claude/rules/mobile-ephemeral-session.md

@@ -0,0 +1,109 @@
+---
+tier: lite
+globs: ["**/*"]
+description: Mobile/ephemeral session rules — state round-trips through git, no filesystem-only markers, explicit session-end
+---
+
+# Mobile / Ephemeral Session Rule
+
+Fires whenever the session is running in an ephemeral environment
+(claude.ai/code mobile sandbox, CI runner, temporary container). See
+`standards/mobile-ephemeral-session.md` for the full standard.
+
+## Detection
+
+**Primary signal (required for certainty):**
+
+```bash
+[ "$CLAUDE_EPHEMERAL" = "1" ]
+```
+
+Operator sets this as the first command in mobile / CI / ephemeral
+sessions. Explicit opt-in removes guessing. Put it in a bookmarklet,
+shell init, or session template.
+
+**Fallback heuristics** (if primary not set, OR of these):
+
+| Check | Signal strength |
+|-------|----------------|
+| `pwd` doesn't start with `/Users/` (macOS operator path) | High |
+| `hostname` doesn't match known operator machines | High |
+| `$HOME` isn't operator's real home | High |
+| `/Applications/Tailscale.app/Contents/MacOS/Tailscale` missing | Medium |
+| `git reflog \| wc -l` is very small (fresh clone) | Medium |
+
+If ≥2 fallback signals fire, treat as ephemeral with a surfaced
+warning: "Detected ephemeral mode via heuristics — explicit
+`CLAUDE_EPHEMERAL=1` recommended."
+
+**First-session bootstrap**: on the very first mobile session, run
+with heuristics OR explicit flag — observe which signals fire —
+refine this list based on actual claude.ai/code sandbox environment.
+Update this rule after empirical data.
+
+## Rules when ephemeral
+
+1. **All artifacts push immediately.** Auto-save hook does
+   `git commit` AND `git push` — not deferred. If push fails, retry
+   once with backoff, then surface failure visibly.
+
+2. **Markers go git-tracked, not /tmp.** Any skill or hook that writes
+   `/tmp/*` markers MUST also write a git-tracked equivalent. The
+   bassclef durable surface is `state/markers/<gate>/...`
+   (temperance, diagnose, edit-count, session-timing); `/verify` keeps
+   its own pre-existing surface at `state/markers/verify/<branch>.marker`
+   for backward-compat with `pre-commit-gate.sh`. In ephemeral mode,
+   the git-tracked form is authoritative. Consumers of gate evidence
+   (pre-build-gate hook, compliance counter, `/chronicle` gate-evidence
+   auto-populate) read whichever form exists; dual-write ensures mobile
+   firings survive sandbox teardown.
+
+3. **Session lock has TTL.** Lock at `.claude/SESSION_LOCK` includes
+   ISO 8601 timestamp. Locks older than 30 minutes are cleared with
+   an announcement ("Clearing stale lock from [timestamp]"). No
+   indefinite holds.
+
+4. **Explicit session-end MUST fire.** Stop hook is unreliable in
+   ephemeral. Agent must invoke `/session-end` at natural stopping
+   points — task complete, context pressure, operator cue.
+
+5. **No credential-bearing tools.** Ephemeral sessions do not hold
+   SSH keys, AWS access keys, Tailscale tokens, or long-lived PATs.
+   Only fine-grained PATs or GitHub App installation tokens with
+   short TTL. Deploy work happens in CI after PR merge, never from
+   ephemeral.
+
+6. **Chronicle read at session start.** If project memory isn't
+   available (no MCP memory server), read the last 2-3 chronicles
+   at session start as context substitute. This is how ephemeral
+   sessions recover "what we were working on."
+
+7. **Conservative gating default.** Orchestrator-gated mode requires
+   explicit `--ephemeral-ok` flag in ephemeral. Default is operator-
+   gated even if orchestrator was requested — ephemeral adds risk
+   that deserves confirmation at decision points.
+
+## Failures to surface
+
+When any of the following happen, session output must prominently
+report it:
+
+- Push failure on auto-save (state loss risk)
+- Stale lock cleared (possible other session running)
+- Chronicle read failed at start (no context recovery)
+- Credential-bearing tool invoked (should not happen; rule violation)
+
+## Rationale
+
+Desktop sessions assume the filesystem survives between steps. Mobile
+sessions don't. A rule that lets agents keep working with the same
+skills and hooks — but with ephemeral-safe behavior — is how
+continuity holds.
+
+## Relationship
+
+- `standards/mobile-ephemeral-session.md` — full standard with
+  all MUST/SHOULD items
+- `.claude/rules/blocked-items.md` — BLOCKED: protocol still applies
+- `.claude/rules/guardrails.md` — "deploy prod requires human approval"
+  is reinforced by this rule (ephemeral can't deploy anyway)

package/dist/lite/.claude/rules/new-dependency-check.md

@@ -0,0 +1,44 @@
+---
+tier: lite
+globs: ["package.json", "package-lock.json", "pnpm-lock.yaml", "yarn.lock", "requirements.txt", "pyproject.toml", "poetry.lock", "Gemfile", "Gemfile.lock", "Cargo.toml", "Cargo.lock", "go.mod", "go.sum"]
+description: New dependency check — verify before adding any package; loads per-pkg-manager sibling
+---
+
+# New Dependency Check
+
+Before adding any new dependency to the project, verify five universal concerns. Then load the per-package-manager sibling under `standards/dependency-discipline/<pkg_manager>.md` for stack-specific specifics.
+
+## Universal concerns (every package manager)
+
+1. **Stack compatibility** — does it work with the project's framework, language version, build system, and runtime constraints?
+2. **Bundle / install impact** — what does it add to your build artifact, install footprint, or runtime memory?
+3. **Runtime compatibility** — does the package make assumptions about the runtime environment (SSR vs CSR, threaded vs async, target architecture)?
+4. **Maintenance risk** — last publish date, open issues, bus factor. Prefer packages from known maintainers or organizations.
+5. **Alternatives** — can the need be met without a dependency? Built-in standard library? CSS-only? Native HTML? Small inline helper?
+
+## Per-package-manager siblings
+
+Bassclef's loader logic reads `tech_stack.pkg_manager:` from `.claude/bassclef-configs.jsonc` and loads the matching sibling for stack-specific specifics:
+
+| Adopter's `pkg_manager` | Sibling loaded |
+|---|---|
+| `npm` / `pnpm` / `yarn` | `standards/dependency-discipline/npm.md` |
+| `pip` / `poetry` | `standards/dependency-discipline/pip.md` |
+| `cargo` | `standards/dependency-discipline/cargo.md` |
+| `gem` | `standards/dependency-discipline/gem.md` |
+| `go-mod` | `standards/dependency-discipline/go-mod.md` |
+| `none` or unset | Universal concerns only |
+
+When the matching sibling does not exist (e.g., a stack bassclef has not yet adopted), the rule fires the universal concerns only and surfaces a `/promote` candidate for the missing sibling.
+
+## Process
+
+1. State the package name and what it is for.
+2. Run the five universal checks above.
+3. Run the per-PM checks from the matching sibling.
+4. If red flags surface in any check, propose an alternative.
+5. If clear, install and add to the project's Approved Dependencies list (or equivalent — see sibling for the exact list name and location).
+
+## Tech stack vocabulary
+
+The loader reads `tech_stack.pkg_manager` shipped in bassclef#1127 (WU-2 of bet 2026-06-18a). Adopters set the value at `/onboard-repo` Phase 2.x. When `tech_stack:` block is absent, the universal concerns still apply; sibling-specific guidance is skipped until the operator declares the stack.

package/dist/lite/.claude/rules/oo-ad-entry-point.md

@@ -0,0 +1,95 @@
+---
+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.
+
+## 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/dist/lite/.claude/rules/operator-facing-prose.md

@@ -0,0 +1,177 @@
+---
+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 in ONE of three positions:
+
+- **Inline** — e.g., "via `/value-prop tweet`", "(per `/temperance`)", "drafted by `/state-a-problem brief`"
+- **Head marker** — a short discipline-marker line ahead of the prose
+- **Footer line** — a `*Skills fired: ...*` line below the prose (added per bassclef-upstream#1598 for adopter-clarity)
+
+The footer position keeps the sales pitch clean at the top while preserving the audit trail. Reader who wants the citation scans the footer. Reader who wants the pitch reads the top.
+
+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.
+
+## 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.

package/dist/lite/.claude/rules/option-label-discipline.md

@@ -0,0 +1,82 @@
+---
+tier: lite
+description: When presenting choices for the operator to pick from (shape A vs shape B; option 1 vs option 2; pick a/b/c; tier 1/2/3), labels MUST be characters the operator can easily type…
+---
+
+# Option-label discipline
+
+When presenting choices for the operator to pick from (shape A vs shape B; option 1 vs option 2; pick a/b/c; tier 1/2/3), labels MUST be characters the operator can easily type back. Greek letters, special characters, and emoji-as-labels are forbidden because they can't be typed on a standard keyboard — operator has to copy-paste from screen, which wastes turns and disrupts operator-flow at exactly the decision point.
+
+## Allowed
+
+- **Lowercase Latin letters** — `a`, `b`, `c`, `d`, `e`, `f` (default for ≤6 choices)
+- **Uppercase Latin letters** — `A`, `B`, `C`, `D` (when distinguishing from inline text matters; default to lowercase otherwise)
+- **Numbers** — `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9` (default for 7+ choices)
+
+## Forbidden — and what to use instead
+
+- Greek letters as labels (`α`, `β`, `γ`, `δ`, `ε`, `ζ`, `η`, `θ`).
+  INSTEAD: use `a`, `b`, `c`, `d`, `e`, `f`, `g`, `h` — same ordinal, typeable.
+- Uppercase Greek letters as labels (`Α`, `Β`, `Γ`, `Δ`).
+  INSTEAD: use `A`, `B`, `C`, `D` — visually similar on most fonts, typeable.
+- Special characters as labels (`①`, `❶`, `⓵` circled numbers).
+  INSTEAD: use plain `1`, `2`, `3`.
+- Emoji as labels (`🅰`, `🅱`).
+  INSTEAD: use plain `a`, `b`.
+- Decorative Unicode boxes as labels (`□`, `■`, `▲`, `▼`).
+  INSTEAD: use plain `a`/`b`/`1`/`2` — boxes are decoration, not labels.
+
+## Reuse is fine
+
+When `a/b/c` was used recently for an earlier decision in the same session, REUSE it for the next decision. Each decision is its own context; operator types `a` referring to the current choice, not the earlier one. The earlier choice's labels do not reserve those letters for the rest of the session.
+
+The bad shape: agent feels labels must "differ from earlier" and escalates to Greek/special characters.
+INSTEAD: reuse `a/b/c` freely; if labels MUST differ from a very recent decision (e.g., active comparison still on screen), use uppercase Latin or numbers — never Greek.
+
+## When this rule fires
+
+Any operator-facing surface where the agent presents N options for the operator to pick:
+
+- `/longrun prep` shape proposal tables (per `.claude/skills/longrun/SKILL.md`)
+- `/sprint` next-work proposals (per `.claude/skills/sprint/SKILL.md`)
+- `AskUserQuestion` menus dispatched from any skill
+- Inline operator prompts in agent turn prose ("Want me to do a, b, or c?")
+- Bet-doc scope-shape enumerations
+- Decision-point menus at /longrun checkpoint or closeout
+
+This rule does NOT fire on:
+
+- Mathematical / physics / chemistry technical content (Greek letters carry domain semantics).
+  INSTEAD of forbidding Greek there: the rule pattern matches `(option|shape|pick|tier|approach|step|item|path|alternative)\s+[α-ωΑ-Ω]` — Greek used as label triggers; Greek used in formulas like `α-decay` or `λ = 600 nm` passes.
+- Quoted strings from external sources (verbatim quotes; Greek letters preserved).
+  INSTEAD of stripping: quote markers (backticks + code blocks) are stripped from the scan input before the regex runs.
+- Skill / rule / file names that happen to contain Greek letters (e.g., a luminary file `alpha-design.md`).
+  INSTEAD of false-positives on filenames: filename references are inside code spans / backticks and get stripped before scan.
+
+## Mechanical enforcement
+
+`.claude/hooks/turn-prose-kiss-check.sh` Stop hook scans every assistant turn prose for option-label Greek patterns:
+
+```
+(option|shape|pick|tier|approach|step|item|path|alternative)[[:space:]]+[α-ωΑ-Ω]
+```
+
+When matched, the hook emits a BLOCK finding with the offending phrase. Per the per-place strict escalation rule (bassclef#1171), option-label findings can be configured strict via `.claude/bassclef-configs.jsonc` `prose_discipline.kiss_words_strict_places` (add `option_labels` to the array). Default is advisory.
+
+The hook ALSO reads `standards/bassclef-internal-jargon.md` BLOCK terms; the wordlist entry for option-label Greek is operator-readable documentation — the regex scan in the hook is the actual mechanical check.
+
+## Override
+
+`SKIP_TURN_PROSE_KISS=1 <command>` — per-call (logged via trace-helper). Use only when quoting verbatim text that contains the offending pattern (e.g., quoting a memory file body that includes the literal α/β/γ).
+
+INSTEAD of overriding for routine work: rewrite the option labels. The discipline is one of the lowest-cost rules to follow — relabeling takes seconds.
+
+## Composes with
+
+- `.claude/rules/plain-english-discipline.md` — master plain-English rule; this is one application at the option-label surface
+- `.claude/rules/operator-facing-prose.md` — gloss + /kiss meta-discipline; sister at adjacent surfaces
+- `.claude/hooks/turn-prose-kiss-check.sh` — mechanical enforcement
+- `standards/bassclef-internal-jargon.md` — wordlist (option-label Greek documented as BLOCK)
+- Memory `feedback_keyboard_typeable_options.md` — the original discipline this rule promotes
+- bassclef#1171 — per-place strict escalation pattern
+- bassclef#1027 — turn-prose discipline parent

package/dist/lite/.claude/rules/pattern-annotation.md

@@ -0,0 +1,83 @@
+---
+tier: lite
+description: "Code that instantiates a named pattern from bassclef's catalog (patterns/<shelf>/<source>/<slug>.md) MUST mark itself with an @pattern <catalog-path> annotation."
+---
+
+# Pattern Annotation — `@pattern` directive
+
+Code that instantiates a named pattern from bassclef's catalog (`patterns/<shelf>/<source>/<slug>.md`) MUST mark itself with an `@pattern <catalog-path>` annotation. This is **Layer 1** of pattern-implementation traceability per bassclef#478.
+
+Forward (this code uses this pattern) and reverse (this pattern is used here, here, here) lookups become greppable. Operator surfaces — including the future `/pattern-trace` skill (LR5 Layer 3) — read the annotation as the source of truth.
+
+## When this rule fires
+
+When writing or editing source code that:
+
+- Implements a recognized GoF / Fowler / EIP / POSA / Nygard / Richardson / Vernon DDD pattern, OR
+- Implements a Smarter Patterns AI UX pattern (e.g., Algorithm Effectiveness Rating in a button + tooltip surface), OR
+- Implements any pattern that has a catalog entry under `patterns/<shelf>/<source>/<slug>.md`
+
+The annotation goes at the entry-point of the pattern instance: the class declaration for code patterns; the component file's top-level for UX patterns.
+
+## Annotation format
+
+```typescript
+/**
+ * @pattern patterns/code/gof/strategy.md
+ *
+ * Picks among sort algorithms based on user-selected order.
+ */
+class SortStrategySelector implements SortStrategy { ... }
+```
+
+```typescript
+/**
+ * @pattern patterns/ux-ai/smarterpatterns/algorithm-effectiveness-rating.md
+ *
+ * Shows quality prediction next to the Generate Variants button.
+ */
+function VariantQualityRating({ inputArtifact }) { ... }
+```
+
+Format rules:
+
+- **Always in a comment block** at the top of the function/class/component definition (not in a separate doc, not as a runtime decorator)
+- **Path relative to the repo root**, with full extension (`.md`)
+- **One annotation per pattern instance** — if a class implements two patterns, two annotations
+- **Optional one-line description** below the annotation explaining the local application
+
+## What NOT to do
+
+- **Don't annotate without a catalog entry existing.** INSTEAD: dispatch `/agent-research-spawn "<Pattern Name>" patterns/<shelf>/<source>/` to fill the gap, then annotate.
+- **Don't fabricate catalog paths.** INSTEAD: grep the annotation against existing entries; if the path doesn't exist, the annotation is wrong (CI hook in LR5 will catch this; until then, it's a methodology check).
+- **Don't annotate trivial uses.** INSTEAD: annotate the class/function that EMBODIES the pattern, not every place that calls it. A single Strategy implementation gets annotated; every caller that picks a Strategy doesn't.
+- **Don't annotate framework patterns** (e.g., a React component isn't "a Composite pattern instance" just because React uses Composite internally). INSTEAD: annotate when YOUR code is consciously instantiating the pattern as a design choice.
+
+## Layer 2 — `/spec` "Patterns Used" table
+
+Specs that drive Construction work (per `.claude/rules/oo-ad-entry-point.md` requiring `/decompose` evidence) include a "Patterns Used" table mapping each named pattern to its catalog path AND to the file/class that will carry the annotation. This is the spec-side mirror of the code annotation — together they form the bidirectional contract.
+
+See `templates/spec-template.md` (this PR also amends it).
+
+## Layer 3 — deferred to LR5
+
+Layer 3 ships in bassclef#478 LR5 work:
+
+- `state/pattern-implementations/*.json` — state-spine manifest entries auto-populated from grep over annotations
+- Validation hook — fires on Edit/Write of source files; verifies annotated catalog paths exist
+- `/pattern-trace` skill — operator-callable lookup (forward + reverse + audit)
+
+Until Layer 3 ships, this rule is methodology-level. Manual grep is the audit path: `git grep -E '@pattern\s+patterns/' src/`.
+
+## Relationship to other rules
+
+- `.claude/rules/oo-ad-entry-point.md` — `/decompose` evidence required before Construction; the decomposition output should call out which patterns will be used (feeds Layer 2 table)
+- `.claude/rules/artifact-ingestion.md` — annotations are themselves a "Sources read" surface; the catalog path is a reference the implementation cites
+- `.claude/skills/agent-research-spawn/SKILL.md` — fills catalog gaps when an annotation references a missing entry
+- `.claude/skills/pattern-review/SKILL.md` — reads annotations to focus review on conscious pattern choices
+
+## Override
+
+`SKIP_PATTERN_ANNOTATION=1` env var (when Layer 3 hook ships) — for migrations and cases where a pattern is implemented but the catalog hasn't yet caught up. Logged to trace per existing bassclef idiom.
+
+Until Layer 3, no mechanical override is needed; this is methodology-level enforcement.