@thebassclef/lite 0.0.1 → 0.1.0

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

@@ -0,0 +1,154 @@
+---
+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…
+---
+
+# 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.
+
+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 | 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) |
+| 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) |
+| 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. |
+
+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.

package/substrate/.claude/rules/pr-body-shape.md

@@ -0,0 +1,317 @@
+---
+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.
+
+## Why this rule exists
+
+`/diagnose` on 2026-06-10 surfaced two root causes for PR body drift:
+
+- **Root cause A** — no PR body shape contract. Authors improvised the first section name ("Goal", "What this PR ships", "What this PR delivers"). Sample drift across 12 recent PRs: 5 with explicit `## Goal`; 7 in other shapes.
+- **Root cause B** — the `/kiss` substitution table and the PR-body-scrub hook JARGON_TERMS list used different word sets. Closed by bassclef#907 (single source of truth in `standards/bassclef-internal-jargon.md`).
+
+V1 of this rule (bassclef#906) addressed Root cause A with Flash + Tweet + Goal. Operator observation on 2026-06-18 surfaced the gap. Flash and Tweet were both solution-framed. Neither stated user pain. Three UX research frameworks (NN/g, UX Design Institute, OpinionX) converge on a stable problem statement template (Who / What / When / Why-now / Outcome). bassclef#1178 retires Flash + Tweet at PR + issue surfaces and replaces both with a single `## Problem` section drafted by `/state-a-problem brief`.
+
+The shape contract still does what V1 did — gives readers a clean entry. The entry is now grounded in the problem, not in the solution claim.
+
+## 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
+## Refs
+
+- Closes bassclef#123 (parent ticket — this PR ships the acceptance)
+- Refs bassclef#456 (related context — not closed by this PR)
+```
+
+Use `Refs` for context-only tickets that survive this PR. Use `Closes` / `Fixes` / `Resolves` for tickets whose acceptance criteria this PR satisfies fully.
+
+When a PR intentionally does NOT close its referenced ticket — for example, when the title cites a parent umbrella ticket but only ships one step — use `Refs #NNN` in the body and add a line explaining scope. Do NOT drop the closing keyword silently; document the choice.
+
+**Mechanical layer.** `pr-body-scrub-check.sh` Rule 7 fires as ADVISORY in V1. Reads `$PR_TITLE` env var passed by `pre-gh-pr-body-scrub.sh` wrapper. Extracts `feat|fix(#NNN)` pattern from title. Checks body for `(Closes|Fixes|Resolves)\s+#NNN`. Emits stderr note when missing. Exit 0 (does not block). Advisory in V1 while adopters get used to the discipline; may flip to blocking after calibration.
+
+## 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.
+
+## Worked examples
+
+### Anti-pattern (Root cause A — what NOT to do)
+
+```markdown
+## 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)
+
+## Distinct from
+
+- `commit-conventions.md` — commit messages have a separate format; this rule applies to PR BODIES, not commits
+- `iteration-bet-brief-completeness.md` — that's about delegation briefs (handoff content); this is about the PR-creation surface
+- `pattern-annotation.md` — that's source-code annotation discipline; orthogonal
+
+## Sources read
+
+- bassclef#906 — V1 parent ticket (Flash + Tweet + Goal shape; superseded at the opener)
+- bassclef#1178 — V3 amendment (Problem section + `/state-a-problem` skill)
+- bassclef#484 (`.claude/rules/github-issue-flash-tweet.md`) — sister discipline at issue surface
+- bassclef#787 (`standards/pr-body-discipline.md`) — sister discipline at scrub surface
+- bassclef#907 — `/kiss` overhaul (closes Root cause B)
+- bassclef#915 — phrase-shaped advisory perimeter
+- bassclef#1176 — V2 local PR-body scrub hook (PR #1179 merged 2026-06-18)
+- bassclef#1177 — V2 extends to gh issue + commit messages (PR #1180 merged 2026-06-18)
+- 2026-06-10 chronicle — V1 /diagnose finding
+- 2026-06-18 chronicle `chronicle/2026-06-18-v2-issue-and-commit-scrub.md` — V3 operator observation
+- NN/g, UX Design Institute, OpinionX problem-statement frameworks — the templates `/state-a-problem` synthesizes
+
+## Closes
+
+- V1 of bassclef#906 — Flash + Tweet + Goal shape
+- V2 of bassclef#906 — local + CI scrub at the opener (bassclef#1176 + bassclef#1177)
+- V3 of bassclef#906 — Problem section opener replacing Flash + Tweet (bassclef#1178 — this amendment)
+
+## Section-level DON'T / INSTEAD catalog (bassclef#1241)
+
+The catalog rows below encode authoring-time discipline per section. The wordlist scrub hook is the FLOOR. This catalog is the BAR. Apply the per-section catalog before the body ships rather than relying on the hook to catch what slipped past you.
+
+The catalog was drafted from two PR-authoring failures on 2026-06-19 (one wordlist-bypass via curl, one wordlist-as-bar drift). See bassclef#1241 for the source incidents.
+
+### Problem section
+
+Composes with `/state-a-problem brief`. Catalog rows below apply per-sentence inside the Problem block.
+
+| Don't | INSTEAD |
+|---|---|
+| Name script line numbers for internal mechanics ("L17 structural --execute gate") | Name the user-visible behavior ("the --execute flag is what makes it run") |
+| Third-person self-reference ("the operator can...", "the agent has no...") | Address the operator directly ("you can...", "I do not know your...") |
+| Bassclef-invented compounds (`discovery surface`, `registry shape`, `local-only discipline`, `Pattern-B'd`, `wiki-as-we-go discipline`, `source-of-truth`, `narrative moment`) | Plain restatement of what the compound names ("the screens the operator sees", "the file structure", "this rule that keeps chronicles local", "moved", "this rule that says check the wiki at every closeout", "the authoritative answer", "story worth telling") |
+| Buzz adjectives (`substantive`, `comprehensive`, `robust`, `leverage`) | Concrete data ("25-line block", "13/13 tests pass") |
+| Bassclef-internal nouns without gloss (`deferred-action`, `INFORM`, `Pattern B`) at first mention | First-mention gloss ("deferred-action file (the next session sees it as a TODO)") |
+| Nested parentheticals (`X (which is Y (per Z))`) | Split into separate sentences |
+
+### Goal section
+
+| Don't | INSTEAD |
+|---|---|
+| Methodology references the reader doesn't carry ("Phase 14 of the chain") | Name what ships and why now |
+| Multi-clause noun-piles ("substantive N-line block documenting A, B, C, D, and E") | Split into a bullet list |
+| Quote the rule's title as if it were the goal ("Apply bassclef#790 Rule 2 meta-discipline") | Name what the operator sees after merge ("/longrun's skill body reads in plain English") |
+
+### Summary section
+
+| Don't | INSTEAD |
+|---|---|
+| Invented compound verbs (`Pattern-B'd`, `scrubbed-and-shipped`) | Plain English ("moved to completed/", "rewrote and pushed") |
+| Code-fenced literals used as if prose (`` `_comment` replaced with substantive block ``) | Plain restatement ("Added a 25-line comment header that documents...") |
+| Restate the goal doc verbatim | Pick the 3-5 changes that matter to a reviewer |
+
+### Test plan section
+
+| Don't | INSTEAD |
+|---|---|
+| Assertions in bassclef-internal idiom ("Deferred-action surfaces at next session-start as INFORM") | Observable behavior ("Next session-start banner shows this under 'Info' (not 'Blocked')") |
+| Tense the reviewer can't verify without running ("hook fires clean") | What the reviewer can grep / run (`jq .pseudonyms[].pseudonym` returns `Falcon`) |
+
+### Out of scope section
+
+| Don't | INSTEAD |
+|---|---|
+| Third-person reference ("the agent cannot author...") | Direct ("I can't author entries — only you know your codenames") |
+| Defer-and-justify in the same line | Split: "X — not in this PR. Y — already tracked at #N" |
+
+### Refs section
+
+| Don't | INSTEAD |
+|---|---|
+| Long bassclef-internal qualifiers in parentheses | One-line ref per line, plain |
+
+### Section-cross-cutting rules
+
+| Don't | INSTEAD |
+|---|---|
+| Repeat literal filenames in title and body Summary together | Plain title; filenames in body where they're grep-anchored |
+| Mix `skillname` and `/skillname` for the same skill | Use `/skillname` consistently when referencing the skill; plain filename when referencing the file |
+| Use bassclef-internal verbs (`flip`, `Pattern-B'd`, `seed` as noun) | Plain verbs (`update`, `move`, `set up`) |
+| Drop session-invented shorthand (`Bucket 2a`, `Path B`, `S2`, `Option F`, `LR-1`) without an appositive on first mention per section | Gloss inline: `Bucket 2a (audit files with no tier tag at all)`; `S2 (Session 2 — Traceability Phase 1)`; per `.claude/rules/operator-facing-prose.md` Rule 1 extended per bassclef-upstream#1267 |
+
+## Retirement condition
+
+If observed across 6 months with zero operator-flagged shape drift on the Problem section, this rule is correctly calibrated. If `## Problem` first-section drift returns above 10% of sampled feature-scope PRs, the V3 CI shape check escalates from advisory to blocking. The catalog rows ship without an a-priori retirement condition — they encode discipline that survives any future skill or hook build.

package/substrate/.claude/rules/pr-strategy.md

@@ -0,0 +1,167 @@
+---
+tier: lite
+description: "The default PR strategy for any multi-issue iteration is stacked atomic branches: one branch per issue, one PR per branch, each independently reviewable and revertable."
+---
+
+# PR Strategy — Stacked Default (Mechanically Enforced)
+
+The default PR strategy for any multi-issue iteration is **stacked atomic
+branches**: one branch per issue, one PR per branch, each independently
+reviewable and revertable. Bundling multiple issues into a single PR is
+the **explicit override**, requested via `bundle: true` in the iteration
+goal's frontmatter (or operator statement) at iteration scaffold time.
+
+This rule was methodology-only in v0. **As of Phase II Trim the Fat
+(2026-05-07), it is mechanically enforced** by the `atomic-pr-check.sh`
+hook, which fires on `git push` and BLOCKs branches with multiple WU-N
+tags in commit messages unless a matching iteration goal declares
+`bundle: true` in frontmatter.
+
+INSTEAD of relying on agent self-discipline: the hook reads the branch's
+commits, counts distinct WU-N tags, and either passes (≤1 distinct tag)
+or BLOCKs with a structured remediation message (multi-step without
+`bundle: true`).
+
+## Default behavior
+
+When `/autonomous start` enters Construction with N≥2 issues in scope:
+
+- Each issue → its own branch (`feature/ISSUE-NNN-stack-N-slug`)
+- Each branch → its own PR
+- Per `standards/branch-stacking.md`: independence is designed in,
+  graceful unwind is mechanical, manifest declares dependencies
+- Boot sequence does NOT ask "stacked or bundled?" — assumes stacked
+
+## Override: `bundle` flag
+
+To collapse a multi-issue iteration into a single PR, the operator
+supplies `bundle` at boot:
+
+```
+/autonomous start orchestrator-gated bundle
+/autonomous start operator-gated sequential bundle
+```
+
+Or states it conversationally during scope confirmation. The default
+short-circuits unless the override is present.
+
+## When bundling IS acceptable
+
+Use `bundle` when ALL of these hold:
+
+1. **Single logical concern** — all changes serve one decision; splitting
+   would be artificial (e.g., a tightly-coupled rename across N files
+   that doesn't compile in isolation).
+2. **Tight coupling that breaks atomic verification** — branch N can't
+   pass `/verify` without branch M's changes (decomposition gap, not a
+   feature).
+3. **Emergency hotfix** — staging delay between PRs would compound the
+   incident; one PR + one merge gets fixes to prod faster.
+4. **Operator explicitly requests** — `bundle` flag or verbatim
+   instruction.
+
+If only #4 holds without #1-3, push back: "stacked is default; what
+about this scope makes bundling correct?"
+
+## When stacking is mandatory
+
+Stack regardless of operator preference when:
+
+- **Mix of skill + rule + hook changes** — different review surfaces;
+  reviewer needs to evaluate each independently
+- **Mix of new files + existing-file edits** — independent revert paths
+- **Different blast radii** — high-radius changes (hooks, schemas)
+  shouldn't ride with low-radius (doc edits) in one PR
+- **Multi-WS iteration goal** — workstreams are separate intents by
+  definition
+
+## Why this rule exists
+
+Every autonomous session before this rule asked "stacked or bundled?"
+Operator answered "stacked" 100% of the time, with `bundle` as a rare
+tactical override (~1 in 20 sessions). Codifying the default eliminates
+the round-trip per bet × bet count × consumer count.
+
+Source: operator feedback 2026-04-18 — "default is 'stacked', override
+is 'bundle', so '/pr bundle'." Filed bassclef #177.
+
+## Eat-our-own-dogfood note
+
+The PR that ships this rule is itself stacked (with #173) — proves the
+default in the same iteration that codifies it.
+
+## Enforcement
+
+- **Hook (mechanical)**: `.claude/hooks/atomic-pr-check.sh` fires on
+  Bash tool calls matching `git push`. Counts distinct WU-N tags in
+  branch commits. BLOCKs multi-step branches without `bundle: true` in
+  a matching iteration goal's frontmatter. Phase II Trim the Fat
+  shipped this as the v1 mechanical-enforcement layer.
+- **Boot sequence** (`strategy/autonomous-boot-sequence.md` Step 4):
+  scaffold prompt skips PR-strategy question unless `bundle: true`
+  supplied
+- **Skill args** (`.claude/skills/autonomous/SKILL.md`): `bundle` listed
+  in args reference table
+- **Standard** (`standards/branch-stacking.md`): declares stacked as
+  default at the top
+- **Methodology**: agent self-checks before pushing; the hook is the
+  backstop, not the only line of defense
+
+INSTEAD of methodology-only enforcement: the hook fires automatically
+on every `git push`. Bypass with `SKIP_ATOMIC_PR_CHECK=1` (logged via
+trace-helper) only for genuine bypass cases.
+
+## Override path
+
+`bundle` at boot. No mid-session switch — once a stack manifest is
+written, the strategy is locked for that bet (changing mid-flight would
+require re-decomposing scope).
+
+## Merge protocol — MUST read before merging any stacked PR
+
+When merging stacked PRs with declared dependencies (Graphite-style:
+dependent PR's `baseRefName` is another feature branch, not `main`),
+**read `standards/branch-stacking.md` §"Squash merge — two protocols"
+BEFORE the first merge in the stack**.
+
+Two protocols exist; picking one is mandatory:
+
+1. **Retarget-before-merge** (preferred) — retarget dependents to
+   `main` via `gh pr edit <PR> --base main` before merging the parent.
+   Dependents survive the cascade.
+2. **Rebase-after-merge** (fallback) — only if auto-close already
+   fired. Per-PR rebase + re-create. Costs 3-8 turns per stack.
+
+Helper: `scripts/check-stack-dependents.sh <PR-N>` lists PRs that
+will auto-close when PR N merges with `--delete-branch`.
+
+**Why this rule repeats what the standard says**: agents load the
+`.claude/rules/` directory automatically. Standards live in
+`standards/` and are referenced by path. Moving the ceremony-layer
+pointer into the rule means an agent that reads `pr-strategy.md`
+at merge-time is told to go read the protocol — closes the
+"standard exists but agent didn't read it before acting" gap
+observed 2026-04-22 (#245 auto-closed on #244 merge because the
+retarget protocol wasn't consulted).
+
+## Relationship to other rules
+
+- `branching.md` — trunk-based + squash merge (governs all branches)
+- `iteration-bet-brief-completeness.md` — Orchestrator transmits
+  manifest to Builder; manifest carries the strategy decision
+- `commit-conventions.md` — PR titles per format regardless of strategy
+- `bassclef-workflow-parity.md` — sibling-grep discipline applies per
+  PR, not per strategy
+- `standards/branch-stacking.md` §"Squash merge — two protocols" —
+  merge-time recovery protocols; MUST read before first merge in any
+  stack
+
+## Retirement condition
+
+If observed over 6 months and `bundle` ratio stays below 5% with zero
+operator corrections of the default, this rule is correctly calibrated.
+If `bundle` ratio rises above 25%, re-shape — the default may have
+drifted from operator intent. If 0% bundle for 12 months, consider
+removing the override entirely.
+
+Closes bassclef #177.