@thebassclef/lite 0.1.3 → 1.0.1

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

@@ -1,196 +0,0 @@
----
-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)

package/substrate/.claude/rules/option-label-discipline.md

@@ -1,108 +0,0 @@
----
-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.
-
-## Why this rule exists
-
-Memory `feedback_keyboard_typeable_options.md` (filed 2026-05-03) documented this discipline. The memory body literally warned about its own failure mode: "I used α/β/γ because a/b/c had been 'burned' on an earlier decision in the same session. Operator: 'how am i supposed to type alpha or beta?'"
-
-The memory existed for ~7 weeks. On 2026-06-20, the agent violated it during /longrun prep — labeled the second shape proposal α/β/γ/δ after the first used A/B/C/D. Three-layer failure documented in chronicle 2026-06-20c-validate-and-finish-arc.md:
-
-1. Memory loaded into context but a competing local heuristic ("differentiate labels from earlier") won attention at label-pick time
-2. No mechanism — no rule, no wordlist, no hook check
-3. Memory-write didn't audit for mechanization opportunity in 2026-05-03 (the meta-discipline `feedback_memory_save_audit_for_adopter_mechanization` was filed 2026-06-20, propagated backward in time)
-
-This rule + the mechanical layer (turn-prose-kiss-check hook scan) close the gap.
-
-## 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
-
-## Refs
-
-- bassclef#1286 — this rule's filing ticket
-- Memory `feedback_keyboard_typeable_options.md` — the 7-week-old discipline this rule mechanizes
-- Memory `feedback_hooks_beat_methodology_for_substrate_quality.md` — the pattern this rule's filing instantiates
-- Memory `feedback_methodology_holds_before_mechanical.md` — why the methodology-only state was not enough
-- chronicle 2026-06-20c-validate-and-finish-arc.md — three-layer failure documentation
-
-## Retirement condition
-
-This rule retires only if bassclef migrates off shell-typeable option labels entirely (e.g., a GUI picker replaces the typed selection). Until then, the discipline of typeable labels persists across every operator-facing surface.
-
-Closes bassclef#1286.

package/substrate/.claude/rules/pattern-annotation.md

@@ -1,100 +0,0 @@
----
-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.
-
-## Why this rule exists
-
-Yesterday's POA UX refactor synthesis revealed that bassclef's substrate produces patterns at design time but doesn't know which patterns landed in implementation. The cameo pattern (luminary-as-design-active) only works if the catalog → spec → code → operator-visible chain is intact. Without annotations:
-
-- `/pattern-review` operates on grep-against-implementation guesswork
-- The future `/pattern-trace` skill has no source of truth
-- When a luminary "uses Strategy" in a variant, no audit trail confirms the strategy actually shipped
-- Reverse-lookup ("show me everywhere we use Decorator") requires re-reading the codebase
-
-The annotation is the inexpensive primitive that makes all of those mechanical.
-
-## 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.
-
-## Retirement
-
-This rule retires only if the catalog substrate itself retires. Annotation format may evolve (e.g., to include version numbers when patterns mature) but the discipline of marking conscious pattern choices in code persists.
-
-Closes Layer 1 of bassclef#478.

package/substrate/.claude/rules/plain-english-discipline.md

@@ -1,156 +0,0 @@
----
-tier: lite
-description: All bassclef writing should be plain English at grade 8 with grade 10 as the ceiling for simple technical sentences. Drop bassclef-internal jargon. Keep standard tech vocabulary like API, hook, PR, schema.
----
-
-# Plain-English Discipline
-
-All bassclef writing — skills, rules, luminaries, PR bodies, commit messages, chronicles, journal entries, iteration goals — should be plain English at grade 8. Grade 10 is the ceiling for simple technical sentences. Above grade 10 needs a clear reason grades 8-10 could not carry the point. Keep standard technical vocabulary that any digital team would understand. Drop bassclef-internal jargon. Drive for extreme simplicity.
-
-Per ticket #935 target shift — the aim moved from grade 10 to grade 8 with grade 10 as ceiling. Steering hook + `standards/steering-hints/kiss-words.md` already carry the new bar. This rule body now matches.
-
-This rule is the master discipline. Other rules cover narrow surfaces:
-
-- `skill-description-clarity.md` — skill description field (≤280 chars, verb-first, no jargon)
-- `github-issue-flash-tweet.md` — GitHub issue body shape (flash + tweet + detail)
-- `visual-hierarchy.md` — long agent output formatting
-- `context-engineering.md` — INSTEAD-block discipline (the pairing rule for negations)
-
-This rule extends those into a unified bar across every writing surface in bassclef.
-
-## Why this matters
-
-Agent volume keeps climbing. Skills produce more PRs, more chronicles, more draft text. Humans review the output to figure out what's happening with the code. If the writing isn't simple, review collapses. The operator stops trusting the output. The substrate's value compounds in the wrong direction.
-
-INSTEAD of writing for "people who know bassclef": write for a senior engineer with no bassclef context. They should grok every PR body, chronicle, and skill description in 60 seconds.
-
-## Keep standard technical vocabulary
-
-These are common digital-team words. They stay as-is.
-
-INSTEAD of expanding them into multi-sentence explanations: use them directly. The reader already knows what an API or schema is.
-
-```
-API, SDK, CLI, GUI, HTTP, REST, JSON, YAML, schema, regex, hook,
-repo, branch, commit, PR, MR, CI, CD, workflow, action, artifact,
-function, class, method, property, field, constant, variable, enum,
-database, query, index, migration, transaction, cache, queue, lock,
-container, image, pod, cluster, node, runner, build, deploy, rollback,
-test, assert, mock, stub, fixture, snapshot, regression,
-auth, token, secret, credential, scope, permission, role,
-file, directory, path, glob, pattern, prefix, suffix
-```
-
-If a term is in this list, it's fine to use directly. Operator can extend the list when more standard vocabulary surfaces.
-
-## Drop bassclef-internal jargon
-
-These need substitution because they require bassclef context to parse:
-
-| Bassclef jargon | Plain English alternatives |
-|---|---|
-| substrate | the framework / bassclef / the rules |
-| primitive | building block |
-| load-bearing | required / essential |
-| composer | runs / chains / combines |
-| tier-preset | preset / size |
-| compose-with | uses / builds on |
-| scope-bounded | small / tight |
-| operationalize | do / ship |
-| blast radius | impact / what it can break |
-| INSTEAD-block discipline | the pairing rule |
-| stuck-signal | repeated warning |
-| substrate-defect | bug in the rules |
-
-These words exist for a reason inside bassclef's design discussions. They belong in design docs, not in PR bodies, chronicles, or any writing aimed at humans without bassclef context.
-
-## Drive for extreme simplicity
-
-INSTEAD of long sentences and qualifying clauses: short sentences, active voice, concrete examples.
-
-| Anti-pattern | INSTEAD |
-|---|---|
-| Long sentences (>30 words) | Break into 2-3 short sentences. Each carries one idea. |
-| Passive voice ("the file was created by the agent") | Active voice ("the agent created the file") |
-| Hedging words ("perhaps", "could potentially", "in some cases") | Direct statement. Either it does or it doesn't. |
-| Buzz adjectives ("comprehensive", "robust", "leverages") | Drop them. Or replace with concrete data. |
-| Methodology references ("Phase 14 of buildable-spec chain") | Either explain the term inline OR drop the reference |
-| Multi-clause noun phrases ("the per-tier deploy-host adapter schema split") | Full plain sentence ("we split the deploy-host adapter schema by tier") |
-
-Extreme simplicity is not the same as dumbing down. It means saying the thing once, in the shortest sentence that carries the point.
-
-## What this rule does NOT require
-
-- Replacing every instance of a banned word — only when context allows. If a word is unavoidable (e.g., quoting a memory file's name), it stays.
-- Hand-paraphrasing technical terms — API stays API. Schema stays schema. Hook stays hook.
-- Grade-school reading level — grade 8 is the aim (per ticket #935; grade 10 stays as the ceiling for simple technical sentences). Operator-readable, not dumbed down.
-- Multi-paragraph expansion of every term — that is contortion, the opposite of what this rule asks for.
-
-INSTEAD of trying to scrub every word: focus on the highest-leverage substitutions (bassclef jargon, long sentences, passive voice).
-
-## When this rule fires
-
-| Surface | Bar | Enforcement |
-|---|---|---|
-| Skill description field (frontmatter) | strict (≤280 chars, no jargon, verb-first) | substrate-clarity-gate hook BLOCKs (file-write) |
-| Skill body | plain English (grade 8 target, ceiling 10); no bassclef jargon | substrate-clarity-gate + skill-body-grade-gate (FKGL 80% at 8-9, ceiling 10) + compound-noun-scrub (blocklist from standards/bassclef-internal-jargon.md per bassclef-upstream#782) — all BLOCK at PreToolUse Edit/Write |
-| Rule body | plain English (grade 8 target, ceiling 10); INSTEAD-block discipline on negations | substrate-clarity-gate + compound-noun-scrub BLOCK at PreToolUse Edit/Write |
-| Luminary body | plain English (grade 8 target, ceiling 10); INSTEAD-block discipline on negations | substrate-clarity-gate hook BLOCKs (file-write) |
-| PR body | plain English (grade 8 target, ceiling 10); no bassclef jargon | bassclef-pr-ci body-clarity advisory job (comments suggestions) |
-| Commit message | conventional-commits format; plain English in body | commit-conventions rule (methodology) |
-| Chronicle | narrative plain English (grade 8 target, ceiling 10) | substrate-clarity-gate hook (advisory; new path matcher in WU-7b) |
-| journal entry | personal/sensory/story-driven voice (per writing voice memory) | advisory only; voice trumps strict rule |
-| Iteration goal body | plain English (grade 8 target, ceiling 10) | substrate-clarity-gate hook (advisory) |
-| Agent turn prose to operator | plain English (grade 8 target, ceiling 10); no bassclef jargon (banned-word list per "Drop bassclef-internal jargon" table above) | Stop hook `turn-prose-kiss-check.sh` scans the most recent assistant message (bassclef#1051). Toggle in `.claude/bassclef-configs.jsonc` (`prose_discipline.kiss_words_turn_prose`): `true` advisory (default), `"strict"` blocks stop, `false` disables. |
-
-The hook is the primary backstop. The rule is the reasoning. Skills (`/promote`, `/longrun closeout`, `/chronicle`, `/journal`, `/kiss words`) compose the prevention.
-
-**Compound-noun blocklist architecture (V2, bassclef-upstream#782 shipped 2026-07-20 goal 20a Session 2).** The `compound-noun-scrub.sh` hook reads a blocklist from `standards/bassclef-internal-jargon.md` at fire time. Only BLOCK-tier hyphenated compounds trigger. Standard tech compounds (`pre-commit`, `real-time`, `data-driven`) pass automatically because they are not in the blocklist. New invented compounds pass by default until the operator adds a row to the wordlist file. The wordlist is the single operator-editable source of truth. Both `compound-noun-scrub.sh` and `turn-prose-kiss-check.sh` read from the same file — one source of truth, two hook surfaces. Override at hook: `SKIP_COMPOUND_NOUN_SCRUB=1`. Override path at wordlist: `BASSCLEF_JARGON_WORDLIST=<path>` (test-only). Missing wordlist file fails safe (exit 0 with stderr warning).
-
-**Turn prose IS hook-reachable via the Stop event** (bassclef#1051 closed bassclef#1027's wrong-premise reading). Claude Code's Stop hook receives `transcript_path` in stdin and can read the most recent assistant message. The `turn-prose-kiss-check.sh` hook fires after every assistant turn, scans the last message against BLOCK terms from `standards/bassclef-internal-jargon.md`, and surfaces findings per the toggle. The per-adopter toggle (`prose_discipline.kiss_words_turn_prose` in `.claude/bassclef-configs.jsonc`): `true` (default) advisory — exit 0, findings to stderr surface at next turn; `"strict"` — exit 2, block stop, force a rewrite turn; `false` disables. The discipline applies to every substantive reply, every status update, every summary — anywhere the agent writes to the operator between tool calls.
-
-## Override path
-
-`SKIP_PLAIN_ENGLISH=1 <command>` — logged via trace-helper. Use rarely. Examples of legitimate overrides:
-
-- Quoting an exact phrase from a memory file or external doc
-- Migrating legacy text where rewriting would lose the audit trail
-- Code blocks where the bassclef jargon IS the variable name
-
-Override discipline: silence is not deferral. If you can't pair the override with a one-line reason, the rule probably applies.
-
-For turn prose specifically, the override is the per-adopter toggle in `.claude/bassclef-configs.jsonc` — `prose_discipline.kiss_words_turn_prose: false` — not a per-command flag. Turn prose has no command to wrap, so the bypass lives at the configuration layer instead.
-
-## Composes with
-
-- `skill-description-clarity.md` — narrow case at description surface
-- `github-issue-flash-tweet.md` — narrow case at issue-body surface
-- `context-engineering.md` — INSTEAD-block discipline (foundational)
-- `visual-hierarchy.md` — formatting discipline for long output
-- `commit-conventions.md` — commit message format (separate concern)
-- `pr-strategy.md` — atomic PR rule (separate concern; both ship in Phase II Trim the Fat)
-- `.claude/bassclef-configs.jsonc` — `prose_discipline.kiss_words_turn_prose` toggle backs the turn-prose row in the surfaces table (bassclef#1027)
-
-## Distinct from
-
-- Code comment style (separate; not a top priority)
-- API documentation (separate; OpenAPI/JSDoc conventions govern)
-- Marketing copy (different audience; brand voice may override)
-
-## Sources read
-
-- 2026-05-07 session — operator framing: "all writing must be in plain digestible english while not inventing words for common technical terms... drive for extreme simplicity. With so much agentic code and work to review, PRs and markdowns become the key areas where humans will interact"
-- bassclef#557 PR body (rewritten in same session) — exemplar of obtuse-then-fixed prose
-- bassclef#559 — broader plain-English discipline ticket
-- `.claude/rules/skill-description-clarity.md` — narrow precedent at description surface
-- `.claude/rules/context-engineering.md` — foundational INSTEAD-block rule
-- `.claude/rules/github-issue-flash-tweet.md` — narrow precedent at issue surface
-- Memory: `feedback_amazon_writing_style`, `feedback_plain_english_no_pseudo_intellectual`, `feedback_writing_voice`, `feedback_kiss_must_be_hook_enforced_on_skill_writes`, `feedback_kiss_prose_discipline_interactive`
-- bassclef#1027 — turn-prose row + `prose_discipline.kiss_words_turn_prose` toggle (this rule's extension; original wrong-premise claim that turn prose was hook-unreachable corrected by bassclef#1051)
-- bassclef#1051 — Stop hook `turn-prose-kiss-check.sh` (mechanical enforcement at the surface bassclef#1027 marked unreachable; sibling of `pr-body-scrub-check.sh`)
-- bassclef#1026 — auto-save commit-sequence batch defect (today's session; sister discipline-application gap)
-- bassclef#382 — substrate-clarity-gate hook (file-write enforcement at write surfaces; this row covers the gap that hook structurally can't reach)
-
-## Closes
-
-Phase II WU-7a of Trim the Fat. Sister to WU-7b (hook extension) and WU-7c (skill updates). Master rule for all bassclef writing surfaces.