@thebassclef/lite 0.1.0 → 0.1.2

package/substrate/.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/substrate/.claude/rules/new-dependency-check.md

@@ -0,0 +1,51 @@
+---
+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.
+
+## Refs
+
+- Path A pattern from bassclef#1133 (ARCH-T0 stack-leakage audit).
+- WU-10 of bet `docs/iteration-bets/2026-06-18a-public-adopter-leverage-longrun.md` ships this catalog split.
+- Sister Path A: bassclef#1133 WU-5 (schema-management → migration-discipline catalog).
+- Reads from bassclef#1127 (tech_stack vocabulary).

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

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

@@ -0,0 +1,100 @@
+---
+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,11 +1,13 @@
 ---
 tier: lite
-description: All bassclef writing — skills, rules, luminaries, PR bodies, commit messages, chronicles, journal entries, iteration goals — should be plain digestible English at a grade-10…
+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 digestible English at a grade-10 reading level. Keep standard technical vocabulary that any digital team would understand. Drop bassclef-internal jargon. Drive for extreme simplicity.
+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:
 
@@ -91,15 +93,15 @@ INSTEAD of trying to scrub every word: focus on the highest-leverage substitutio
 | Surface | Bar | Enforcement |
 |---|---|---|
 | Skill description field (frontmatter) | strict (≤280 chars, no jargon, verb-first) | substrate-clarity-gate hook BLOCKs (file-write) |
-| Skill body | grade-10 plain English; 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 | grade-10 plain English; INSTEAD-block discipline on negations | substrate-clarity-gate + compound-noun-scrub BLOCK at PreToolUse Edit/Write |
-| Luminary body | grade-10 plain English; INSTEAD-block discipline on negations | substrate-clarity-gate hook BLOCKs (file-write) |
-| PR body | grade-10 plain English; no bassclef jargon | bassclef-pr-ci body-clarity advisory job (comments suggestions) |
+| 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 grade-10 plain English | substrate-clarity-gate hook (advisory; new path matcher in WU-7b) |
+| 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 | grade-10 plain English | substrate-clarity-gate hook (advisory) |
-| Agent turn prose to operator | grade-10 plain English; 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. |
+| 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.
 

package/substrate/.claude/rules/plan-enumeration-needs-value-props.md

@@ -0,0 +1,211 @@
+---
+tier: lite
+description: When the agent presents options the operator must pick from or evaluate, the whole proposal opens with a full pitch (claim + 3 reasons) and each option lands as a tweet (claim +…
+---
+
+# Plan Enumeration Needs Value-Props
+
+When the agent presents options the operator must pick from or evaluate,
+the whole proposal opens with a full pitch (claim + 3 reasons) and each
+option lands as a tweet (claim + sharpener). **Bare names aren't options.**
+Names are labels; each label needs a value-prop attached.
+
+## Why this rule exists
+
+Operator scans on mobile + multi-pane desktop. Bare-name enumeration
+("Option A. WU-2", "Option B. #334", "Option C. WU-5") forces the
+operator to ask "what's WU-2?" — a follow-up turn that wouldn't be
+needed if the value-prop sat next to the name.
+
+Caught 2026-04-27e during /longrun prep — operator: "you need to land
+value props for each scope choice you propose going forward...we
+probably need to constrain/hook that in some way."
+
+The /value-prop skill already provides four compression modes (flash,
+tweet, brief, verbose). This rule wires them into how the agent
+presents enumerations, so plan output is scannable in one read.
+
+## When this rule fires
+
+Any agent output that enumerates options for the operator — "Pick A or
+B," "scope choices for this /longrun," "which approach do you want,"
+"three sizes:" — fires this rule.
+
+Specific surfaces:
+
+- `/longrun` (prep + checkpoint) — scope choices for the session
+- `/sprint` — next-work options
+- `/whats-the-plan` — chains of skills the agent intends to run
+- `/shape` — tier alternatives (quick / light / medium / full)
+- `/kiss` — bucket enumerations (MUST / SHOULD / COULD)
+- `/stage` — variant alternatives presented to operator
+- Any ad-hoc agent output where the operator picks among options
+
+Does NOT fire on:
+
+- Single-action replies (no options to pick from)
+- Tool-output relays (commit messages, test output)
+- Status reports without choice points (e.g., "shipped X")
+- Code content (diffs, file contents)
+
+## What the rule requires
+
+### The whole proposal opens with a full pitch
+
+Per `/value-prop` verbose mode: **claim + 3 reasons (why-it-matters)**.
+
+```markdown
+**The /longrun (full pitch):**
+
+Make bassclef's roadmap state machine-readable so /sprint and /longrun
+stop reconstructing scope from chronicles + git log.
+
+**Why it matters:**
+
+1. First-turn orientation drops from "read three chronicles + git log
+   + open PRs + guess" to one read.
+2. Two parallel sessions can't double-claim work — atomic claim/release
+   lands as a primitive.
+3. Operator stops manually clearing rescue files every session.
+```
+
+Three reasons, plain language, scannable.
+
+### Each option lands as a tweet
+
+Per `/value-prop` tweet mode: **claim + sharpener, ≤280 chars**.
+
+```markdown
+**Pick one:**
+
+- **A. WU-2 + WU-3 (~50t)** — Roadmap state becomes machine-readable.
+  Two parallel sessions can't pick the same work by accident. Claim/
+  release primitives ship.
+
+- **B. A + #334 (~70t)** — Plus a save-time check that catches agents
+  skipping the roadmap. Read-side and write-side determinism in one shot.
+
+- **C. Through WU-5 (~100t)** — Plus /sprint and /longrun actually use
+  the new reading. End-to-end this session.
+```
+
+Each option's value-prop sits next to its name. Operator reads, picks.
+
+### Bare names aren't options
+
+These are NOT acceptable enumeration shapes:
+
+```markdown
+Pick:
+- A
+- B
+- C
+```
+
+```markdown
+Pick:
+- WU-2
+- #334
+- WU-5
+```
+
+```markdown
+Three options: WU-A, WU-B, WU-C.
+```
+
+Each option needs a value-prop. If the value-prop is so obvious it
+doesn't need stating, the option probably isn't worth enumerating.
+
+## What the rule allows
+
+- **Plain language preferred** (composes with `/kiss words` — folds in what was the standalone `/grade10words` skill per bassclef#340).
+- **Tables when the options share a comparable axis** — e.g., "Tier / Estimate / Buys you" — but each row still needs the value-prop column populated.
+- **Skipping the full pitch when the options are presented in passing** — e.g., "Want me to ship A, B, or C?" mid-conversation. The full pitch is for proposal moments; the tweet-per-option discipline still applies.
+- **Inline alternatives** — "I'll ship X (or Y if you'd rather; Y trades speed for safety)" is fine; the alternative carries its sharpener inline.
+
+## Anti-patterns
+
+Direct quotes from sessions where this rule was missing:
+
+- "Pick one: A, B, or C" — three letters, no content
+- "WU-2 + WU-3 (~50t)" alone in a list — bare cost without value
+- "We could do this or that" without naming what each buys
+- "Three sizes — pick by how much determinism you want" without saying which size buys what
+
+## How the rule composes with existing skills
+
+- `/value-prop` is the primitive — flash/tweet/brief/verbose modes the
+  rule references directly.
+
+  INSTEAD of reinventing the format inline: call the skill. The four
+  compression modes already exist; reuse them.
+- `/kiss words` (bassclef#340 folded the planned `/grade10words` into `/kiss`) — substitutes plain language for jargon. Composes orthogonally; an option's tweet should already be in plain language by default.
+- `/feynman` — explanation skill. NOT a substitute for tweet-per-
+  option; /feynman is for "explain this concept," not "present these
+  choices."
+
+## Verification cue (self-check before output)
+
+Before presenting an enumeration, ask:
+
+1. Did I open with a claim + 3 reasons (full pitch)?
+2. Does each option carry a tweet (claim + sharpener)?
+3. Are any options just labels / IDs / bare names?
+4. Plain language? Or am I using "atomic" / "load-bearing" / "blast radius" without justifying?
+
+If any answer is wrong, rewrite before posting.
+
+## Eat-our-own-dogfood
+
+Every PR body that ships a bassclef-evolution change uses this format
+when it presents alternatives ("Out of scope," "Acceptance," "Test
+plan"). Each line earns its place; bare bullet enumerations get
+upgraded to tweets.
+
+Iteration-goal docs follow the same discipline in their "Steps
+enumerated" section.
+
+## Relationship to other rules
+
+- `feedback_lead_with_flash.md` (memory) — the operator-feedback
+  precedent; this rule codifies it as substrate
+- `visual-hierarchy.md` — long agent output uses tables/headers/HRs;
+  this rule adds the value-prop content discipline that makes the
+  hierarchy useful
+- `artifact-ingestion.md` — "Sources read" block discipline; this rule
+  is the analogous "options presented" discipline
+- `commit-conventions.md` — commit message format; this rule applies
+  to PR bodies, agent dialogue, and skill outputs (not commits — those
+  have their own format)
+- `sdlc-gates.md` — methodology-level gates; this rule fires before
+  any plan-presentation moment
+
+## Enforcement
+
+Methodology-level. The rule loads into every session via
+`additionalDirectories`. Agents self-check before posting an enumeration.
+
+If post-observation shows agents repeatedly presenting bare-name
+enumerations, a future hook could grep agent output for option-list
+shapes and BLOCK if value-prop content is missing — but the first line
+of defense is the rule loading into every session.
+
+## Override path
+
+`SKIP_PLAN_ENUMERATION_RULE=1 <command>` — logged to trace per existing
+bassclef hook idiom. Use only when the enumeration is genuinely
+stylistic / casual ("want coffee or tea?") and the value-prop discipline
+would be ceremony.
+
+INSTEAD of using the override for production decisions: write the
+value-prop. Production scope choices always carry weight worth
+articulating.
+
+## Retirement condition
+
+If observed across 6 months with zero operator corrections of
+enumeration formatting, this rule is correctly calibrated. If the
+operator stops asking "what does X buy me?" entirely, the rule has
+done its job.
+
+Closes bassclef#339.