@thebassclef/lite 1.0.3 → 1.1.0

package/dist/lite/.claude/rules/persona-name-leak-scrub.md

@@ -0,0 +1,90 @@
+---
+tier: lite
+description: Adopter-observable body content across SKILLs plus rules plus luminaries plus docs does not carry bassclef persona names (Sam, Louis, Jamie, Morgan). Persona names are internal orientation words. Adopters have zero context on them.
+---
+
+# Persona-name leak scrub
+
+Adopter-facing content does not carry bassclef persona names. Persona slugs (Sam, Louis, Jamie, Morgan) orient bassclef prose internally. Adopters read SKILL descriptions on `docs.bassclef.dev`, plus SKILL bodies, rule bodies, luminary bodies, and adopter-facing docs. They have no context on who Sam is.
+
+This rule closes bassclef-web#327 (V1 description scope) and bassclef-web#339 (V2 body scope).
+
+## When this rule fires
+
+Every Edit or Write or MultiEdit on any of these adopter-observable path classes:
+
+- `.claude/skills/*/SKILL.md` (description AND body prose)
+- `.claude/rules/*.md` (body prose)
+- `.claude/luminaries/*.md` (body prose)
+- `docs/*.md` (adopter-facing documentation)
+- `docs-site/content/*.{md,mdx}` (docs.bassclef.dev source)
+
+The hook `.claude/hooks/persona-name-scrub-check.sh` scans the full new_string (Edit), content (Write), or joined edits[].new_string (MultiEdit). Fenced code blocks and inline backticked spans strip before the regex to cure false positives.
+
+Skips:
+- Persona files themselves (`docs/personas/*.md` — that IS where personas live)
+- Non-matching paths (source code, README, config)
+- Non-Edit tool calls (Bash, Read, Grep)
+
+## V2 body scope shipped
+
+V1 (bassclef-web#327, shipped 2026-09-12d): description-only scope. Hook scanned the `description:` frontmatter line only.
+
+V2 (bassclef-web#339, shipped 2026-09-13c): body scope. Hook scans the full new_string plus joined MultiEdit edits[]. Covers SKILL bodies, rule bodies, luminary bodies, and adopter-facing `docs/*.md` plus `docs-site/content/*.{md,mdx}`.
+
+V2 stays ADVISORY per ADR-031 grace window through 2026-10-31. V3 BLOCK flip deferred pending one calibration cycle.
+
+## What the rule requires
+
+Adopter-observable content does not carry any of these proper nouns as unquoted words:
+- Sam
+- Louis
+- Jamie
+- Morgan
+
+Substitute per context — writer, picker, reviewer, operator, adopter.
+
+Backtick a persona name when it names a variable or a quoted external reference. Fenced code blocks and inline backtick spans strip before the regex.
+
+## Anti-patterns
+
+**Description says "Sam writes formal use cases."** Adopter has no context on Sam.
+INSTEAD: "The writer produces formal use cases."
+
+**Description says "Louis picks a marketing variant."**
+INSTEAD: "The picker chooses a marketing variant."
+
+**Description says "Written for a Sam-style persona."**
+INSTEAD: drop the phrase or say "Written for a writer-style adopter."
+
+**SKILL body Procedure step says "Sam runs /value-prop first, then Louis reviews the output."** Adopter body reader gets zero context.
+INSTEAD: "The writer runs /value-prop first. The reviewer then reads the output."
+
+**Rule body cites "This composes with Sam's authoring path."** Adopter rule reader gets zero context.
+INSTEAD: "This composes with the writer authoring path."
+
+**Luminary body pin says "Jamie applies this lens on marketing surfaces."** Adopter luminary reader gets zero context.
+INSTEAD: "The picker applies this lens on marketing surfaces."
+
+**docs/*.md guide says "Morgan owns the release pipeline."** Adopter docs reader gets zero context.
+INSTEAD: "The release engineer owns the release pipeline." OR name the actual role.
+
+**docs-site/*.mdx page renders "Sam and Louis are the primary readers."** Adopter docs.bassclef.dev reader gets zero context.
+INSTEAD: "The writer and the picker are the primary readers." OR describe the audience in role terms.
+
+## Override
+
+`SKIP_PERSONA_NAME_SCRUB=1 <command>` — logged via trace-helper. Rare cases:
+- Migration script that intentionally references personas
+- Quoted external text
+- Emergency rescue
+
+## Composes with
+
+- `.claude/rules/plain-english-discipline.md` — master rule; this rule extends to persona proper nouns
+- `.claude/rules/skill-description-clarity.md` — description field discipline
+- `.claude/rules/bootstrap-pair-discipline.md` — rule + hook + tests + wire ship together
+- `.claude/rules/we-dont-break-adopters.md` — V1 ADVISORY default preserves adopter behavior during grace
+- `standards/bassclef-internal-jargon.md` — sister wordlist (generic jargon, not proper nouns)
+- @luminary linus-torvalds — adopter contract
+- @luminary michael-nygard — V1 ADVISORY stability

package/dist/lite/.claude/rules/plain-english-discipline.md

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

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

@@ -0,0 +1,177 @@
+---
+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.
+
+## 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.
+
+## 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.

package/dist/lite/.claude/rules/pr-body-shape.md

@@ -0,0 +1,195 @@
+---
+tier: lite
+description: Every PR body opens with a ## Problem section drafted by /state-a-problem brief + --- + ## Goal.
+---
+
+# PR Body Shape Contract
+
+Every PR body opens with a `## Problem` section drafted by `/state-a-problem brief` + `---` + `## Goal`. Detail comes AFTER. Operators and reviewers scan on mobile and multi-pane desktop. Without a problem-grounded opener, readers re-derive the reason for the PR every time. The skill is the contract. Hand-rolling reproduces the failure pattern bet 25k closed (see `docs/iteration-bets/2026-06-25k-discipline-visibility-and-pr-body-scrub-fix.md` § WU-1 L66 diagnosis).
+
+This rule closes two gaps:
+
+- **Mechanical.** Bassclef enforces what NOT to include in PR bodies (jargon BLOCK list + operator-private paths + strategic framing via `pr-body-scrub-check.sh`). No prior contract said what MUST appear at the opener.
+- **Methodology.** The prior Flash + Tweet pair (bassclef#906) was solution-framed twice — neither stated user pain. bassclef#1178 retires the pair at PR + issue surfaces and replaces both with a single `## Problem` section that centers user pain before solution.
+
+Sister to `.claude/rules/github-issue-flash-tweet.md` at the issue surface.
+
+## Format contract
+
+Every PR body MUST open with:
+
+```markdown
+**Problem (≤500 chars):** <Who + What + When + Why now + Outcome — framework implicit; drafted by /state-a-problem brief>
+
+---
+
+## Goal
+
+<What this PR ships, in one paragraph. Why now.>
+
+## Evidence
+
+- Source: <file path, ticket number, commit SHA — what backs the claim>
+- Warrant: <one sentence tying the source to the claim>
+```
+
+Format rules:
+
+- **Problem label is bold and enclosed in `**`** — a visual scan handle, not body prose
+- **Length limit enforced** — Problem ≤500 chars (matches `/state-a-problem brief` mode cap)
+- **Plain language** — no bassclef jargon in the Problem section. The Problem section is the FIRST place a reader meets the work. Jargon here destroys orientation. `/state-a-problem` runs `/kiss --grade10` inline by default so the rule is hard to violate
+- **Horizontal rule** (`---`) separates Problem from the structured body
+- **`## Goal` is the first section after the rule** — not `## Summary`, not `## What this PR ships`, not `## Why this matters`. Goal is the agreed label
+- **`## Evidence` follows Goal** — cites the source that backs the claim in Goal. Per `.claude/rules/assert-only-after-verify.md` — every operator-facing assertion carries source + warrant. Per `standards/opener-discipline.md` — the three-block opener extends to PR body via Problem + Goal + Evidence
+- **One paragraph per** — Problem is 3-4 sentences; Goal is one paragraph; Evidence is one bullet source + one bullet warrant
+
+## Required sections (in order)
+
+After Problem + `---`:
+
+| Section | Required? | Purpose |
+|---|---|---|
+| `## Goal` | **MUST** | One paragraph. What this PR ships. Why now |
+| `## Evidence` | **MUST** | Source + warrant per `.claude/rules/assert-only-after-verify.md`. Cites what backs the Goal claim |
+| `## Summary` | MUST when scope >1 file | Bullet list of substantive changes |
+| `## Test plan` | MUST | Checklist of how reviewer verifies |
+| `## Out of scope` | SHOULD | What this PR explicitly does NOT do |
+| `## /temperance + /luminary + /loop discipline` | **MUST under /longrun dispatch** | The three-skill cycle this PR ran (see below) |
+| `## Refs` | SHOULD | Issue numbers, related PRs, source chronicles |
+
+Other sections (Bundle justification, Inventory findings, Migration notes) appear between Goal and Test plan as needed. Drop sections that do not apply (e.g., Out of scope on a doc-only PR).
+
+## /temperance + /luminary + /loop discipline section (per bassclef-upstream#366)
+
+Every PR authored under `/longrun` dispatch MUST carry a section with the literal header `## /temperance + /luminary + /loop discipline`. The section makes the per-PR cycle named in `.claude/rules/loop-discipline.md` visible at PR review time.
+
+The header string is fixed and case-sensitive. The hook `pr-body-loop-discipline-check.sh` greps for it exactly. The section body names three things, one per bullet:
+
+- **/temperance** fired at `<surface>`. Scope decision answer in one line. Drift trigger in one line.
+- **/luminary** primary lens `<luminary-slug>` — one line on what the lens caught. Supporting lenses optional.
+- **/loop** iteration count `<N>`. Outcome — RED then GREEN, OR rework cycle if any.
+
+The fixed shape lets the grep check pass cleanly. It also gives readers a scannable three-line surface to verify discipline at PR review.
+
+Why this section exists: bets 25h + 25i + 25j ran the discipline floor. Markers landed under `state/markers/temperance/`, `state/markers/luminary/`, and `state/markers/loop/` per branch. But the PR bodies stayed silent. The operator caught the gap mid-goal 25j: "I'm not seeing /luminary listed for PR review and /loop iteration through to closure." The mechanical floor was correct. The visible bar was missing. This section closes the bar the moment a reader scans the PR.
+
+Forward-only enforcement. Already-merged PRs stay as is. Trivial-fix PRs under 3 files MAY skip the section per the Problem-section exception below.
+
+## What NOT to do
+
+- **Don't open with a section header** before Problem. INSTEAD: Problem is the headline. Section headers come after the `---` rule.
+- **Don't fall back to Flash + Tweet** — the V1 shape was solution-framed twice; neither stated user pain. INSTEAD: draft the Problem section via `/state-a-problem brief` mode. The skill produces the contract. The Who/What/When/Why-now/Outcome framework is implicit in the sentence shape it returns.
+- **Don't replace `## Goal` with synonyms.** INSTEAD: `## Goal` is the bassclef first section label after Problem. Reviewers and substrate-coherence checks grep for it.
+- **Don't bury the claim in `## Why this is needed` or `## Context` before Goal.** INSTEAD: the claim is the Problem + Goal pair. Context goes after.
+- **Don't use bassclef jargon in Problem or Goal.** INSTEAD: substitute plain English per `.claude/rules/plain-english-discipline.md` and `standards/bassclef-internal-jargon.md`. `/state-a-problem` runs `/kiss --grade10` inline by default. Hand-rolled drafts run `/kiss --grade10` separately before push.
+
+## Trivial-fix exception
+
+PRs with scope under 3 files AND no new SKILL.md AND no new rule MAY skip the Problem section. Trivial fixes (typo, env-var, off-by-one, one-line) often have no user-pain framing worth a section. The shape contract still requires `## Goal` as the opener in that case.
+
+The CI shape check skips the Problem requirement when the touched-file count is under 3 AND no SKILL.md or rule file is in the change.
+
+## Ticket-close keyword discipline (bassclef#974)
+
+When PR title carries `feat(#NNN):` or `fix(#NNN):` pattern, the body MUST include a `Closes #NNN` (or `Fixes #NNN` / `Resolves #NNN`) keyword. GitHub auto-closes tickets only when the closing keyword appears in the PR body — title alone does not trigger the close. Without the keyword, tickets stay open even after PRs merge, and the state-spine drifts from shipping reality.
+
+Per whereami#28b diagnose — of the last 20 merged PRs at 2026-07-29, only 4 carried a closing keyword in the body. 16 shipped work but left the ticket open (including #934 and #935 which required manual backfill during Session 28b).
+
+The `Refs` section is a good home for the keyword. Example:
+
+```markdown
+## Vocabulary discipline at authoring time (bassclef#915)
+
+Per bassclef#915 V1: PR body authoring is a `/kiss` surface. Before invoking `gh pr create` (or `gh pr edit --body-file`), the agent runs `/kiss` words discipline against the body. It substitutes BLOCK and ADVISE-PHRASE terms from `standards/bassclef-internal-jargon.md`.
+
+- **BLOCK terms** — substitute per `/kiss --grade10` table; PR-body-scrub Rule 1 catches what slips
+- **ADVISE terms** — substitute per `/kiss --grade10` table; PR-body-scrub does not block on these
+- **ADVISE-PHRASE terms** — substitute or rephrase; PR-body-scrub Rule 5 emits advisory CI annotations on hits (does not block)
+- **ALLOW terms** (reserved per bassclef#763 — substrate, bassclef, cameo, Studio, Band, bandleader) — preserve
+
+V2 pre-push hook for `/kiss`-on-PR-body authoring ships per bassclef#1176 (PR #1179 merged 2026-06-18). Local PreToolUse Bash hook scrubs PR body before `gh pr create` reaches GitHub.
+
+## When this rule fires
+
+Every NEW PR body authored via:
+
+- `gh pr create` — local PreToolUse hook fires (bassclef#1176); CI hook fires as backstop (bassclef#739)
+- `gh pr edit` (body rewrite) — same shape contract applies
+- Manual operator authoring via GitHub web UI — `.github/pull_request_template.md` auto-fills the shape; operator amends
+
+Existing PRs are NOT retroactively backfilled. Forward-only enforcement keeps the discipline visible at the PR-creation surface where it lands.
+
+## Mechanical enforcement
+
+V1 shipped methodology + `.github/pull_request_template.md` template + the rule (bassclef#906). V2 shipped local + CI Bash-matcher hooks for jargon scrub (bassclef#1176 + bassclef#1177). V3 (this bassclef#1178 amendment) ships:
+
+- Shape contract enforces `## Problem` opener at feature-scope PRs
+- `pr-body-scrub-check.sh` extended with a shape check that flags a missing `## Problem` section on feature-scope PRs
+- `/state-a-problem brief` skill drafts the section (runs `/kiss --grade10` inline by default)
+- `.github/pull_request_template.md` template updated to show the Problem-section shape
+
+V4 (bassclef#974) ships Rule 7 — ticket-close keyword advisory. Local + CI hook layers extended:
+
+- `pre-gh-pr-body-scrub.sh` extracts PR title, passes as `$PR_TITLE` env var
+- `pr-body-scrub-check.sh` Rule 7 checks title-vs-body correlation for closing keyword
+- 4 new Tier 0 tests pin behavior (Tests 27-30 in `.claude/hooks/tests/pre-gh-pr-body-scrub.test.sh`)
+- Advisory in V1; V2 may flip to BLOCK after calibration
+
+## Override path
+
+`SKIP_PR_BODY_SHAPE=1 <command>` — for genuinely-not-PR-body cases (e.g., release-tag PRs, automated bot PRs, dependabot updates where the bot controls the body format). Logged via trace-helper.
+
+INSTEAD of overriding for tight scope: write the Problem section. Three sentences carrying the framework cost less than reviewer re-derivation.
+
+## Summary
+
+Add `/longrun` skill for autonomous long-running sessions...
+
+## Why this is needed
+
+Recurring pattern observed over March-April 2026 sessions...
+```
+
+Reviewer reads title → "Summary" header → 3 paragraphs to find the claim. Claim is buried. User pain stays unstated.
+
+### Anti-pattern (V1 Flash + Tweet — superseded by bassclef#1178)
+
+```markdown
+**Flash (≤180 chars):** Add `/longrun` skill — autonomous sessions paced by checkpoints and closeout discipline.
+
+**Tweet (≤280 chars):** Sessions over 50 turns drift without checkpoints. `/longrun` adds prep / checkpoint / closeout modes.
+```
+
+Better than no shape. But solution-framed twice. Reader still does not know WHY this work exists — only WHAT it does.
+
+### Conformant pattern (bassclef#1178 — Problem opener)
+
+```markdown
+**Problem (≤500 chars):** Today autonomous sessions over 50 turns drift without structured checkpoints — operators return mid-session to mid-stream context, no anchor on what shipped, what's blocked, or what's next. The /longrun skill adds prep / checkpoint / closeout modes that pace the session against named phase boundaries. The change we want is sessions over 50 turns that return clean state every time, not a context-archaeology task on every wake.
+
+---
+
+## Goal
+
+Ship `/longrun` skill so autonomous sessions running >50 turns or across compaction boundaries have substrate-enforced pacing.
+
+## Summary
+
+- New `.claude/skills/longrun/SKILL.md` with three modes
+- ...
+```
+
+Reviewer gets user pain → solution → diff in 60 seconds. Detail follows for those who want depth.
+
+## Composes with
+
+- `.claude/skills/state-a-problem/SKILL.md` — drafts the Problem section in brief mode (≤500 chars); runs `/kiss --grade10` inline by default
+- `.claude/rules/github-issue-flash-tweet.md` (bassclef#484 — amended by bassclef#1178) — sister rule at issue-body surface
+- `.claude/rules/plain-english-discipline.md` (bassclef#790) — plain language requirement for Problem and Goal
+- `standards/pr-body-discipline.md` (bassclef#787) — scrub discipline at same surface
+- `.claude/rules/operator-facing-prose.md` (bassclef#790) — operator-facing prose discipline
+- `.claude/hooks/pr-body-scrub-check.sh` — sibling mechanical surface (CI hook); extended in bassclef#1178 with shape check
+- `.claude/hooks/pre-gh-pr-body-scrub.sh` — local pre-push hook (bassclef#1176)
+- `.github/pull_request_template.md` — auto-fill at PR-creation surface; updated for the Problem shape
+- bassclef#915 — phrase-shaped advisory perimeter (sister at vocabulary surface)
+- bassclef#907 — `/kiss` overhaul (single source of truth wordlist)