@thebassclef/lite 1.0.4 → 1.1.0

package/dist/lite/.claude/rules/visual-hierarchy.md

@@ -0,0 +1,427 @@
+---
+tier: lite
+description: Long agent responses that mix summary + analysis + enumeration + action become walls of text.
+---
+
+# Visual Hierarchy in Agent Output
+
+Long agent responses that mix summary + analysis + enumeration + action
+become walls of text. Operators scan on mobile and multi-pane desktop;
+walls of text force re-reading. Use markdown primitives to create
+scannable separation.
+
+## When this rule fires
+
+Fires on any agent response that:
+
+- Is longer than ~5 paragraphs, OR
+- Mixes more than one of: summary, analysis, enumeration, actions, questions
+
+Does NOT fire on:
+
+- Short answers (<3 sentences)
+- Single-action replies
+- Tool-output relays
+- Code diffs or file contents
+
+## The conventions
+
+### 1. TL;DR at the top (when response has conclusions before detail)
+
+Set off as a bold callout or blockquote, not a plain paragraph:
+
+```markdown
+> **TL;DR:** one-line conclusion the operator needs even if they read nothing else.
+```
+
+Not every response needs one. Use when the operator benefits from the
+conclusion before the reasoning.
+
+### 2. Section headers for distinct parts
+
+Use `##` with consistent category labels:
+
+```markdown
+## Summary
+## Analysis
+## Actions
+## Next
+```
+
+Pick the labels that match the response shape.
+
+INSTEAD of forcing all four headers when only two apply: use only the
+ones that match (e.g., just `## Summary` and `## Next` for a status
+update; just `## Analysis` for a diagnostic).
+
+### 3. Horizontal rules between large sections
+
+`---` separates major sections visually. Use when sections are long
+enough that the reader would benefit from a clear break.
+
+### 4. Bold category labels in lists
+
+When enumerating buckets (MUST / SHOULD / COULD, Tier 1 / Tier 2,
+Option A / Option B):
+
+```markdown
+**Tier 1 — Must-fix (N)**
+- #NN — title
+- #NN — title
+
+**Tier 2 — Should-fix (N)**
+- #NN — title
+```
+
+Category labels in bold, content under them.
+
+**Prose enumeration shape.** When a paragraph enumerates 3-5 items
+inline (not as a list), each item opens with a bold lead followed
+by an em-dash and the item's expansion. The bold lead names the
+item; the em-dash separates label from body.
+
+**Anti-pattern:** flat prose enumeration with no scan anchors.
+
+```
+The three findings are that CI is stale which means the pipeline
+hasn't run in 48 hours, tests are flaky which produced 5 false
+positives last week, and the marker check is missing which lets
+regressions slip through.
+```
+
+**Conformant:** bold-lead + em-dash per item, blank line between.
+
+```
+- **CI stale** — pipeline hasn't run in 48 hours.
+- **Tests flaky** — 5 false positives last week.
+- **Marker check missing** — regressions slip through.
+```
+
+Same principle as section 10 (bold inline lead for reasoning
+paragraphs). Prose enumeration is a compact form; the bold-lead +
+em-dash carries the anchor without needing full paragraph breaks.
+
+### 5. Code-fence inline quotes and file refs
+
+```markdown
+`.claude/rules/visual-hierarchy.md` — not plain text
+`git status` — not plain text
+```
+
+Consistent across the whole response.
+
+### 6. Questions / confirmation prompts set off from analysis
+
+When the response ends with a question for the operator, separate it
+visually from preceding analysis — a `---` rule, a bold header
+(`**Confirm to proceed?**`), or a short blockquote.
+
+### 7. Bulleted wraps use hanging indent
+
+When a bullet's text wraps to a second or third line, the wrapped text aligns with the first character after the `- ` marker. Not with column 0. Most markdown renderers do this automatically when the source places the bullet at column 0. Agent output that indents wrapped lines to column 0 breaks the signal. The eye reads the wrapped text as a new paragraph, not as part of the bullet.
+
+**Anti-pattern:** continuation text at column 0 — wrapped text
+reads as a new paragraph, not a continuation.
+
+```
+- This is a long bullet whose text wraps to a second line and the
+continuation lands flush left at column 0 which breaks the visual
+signal that it belongs to the bullet above.
+```
+
+**Conformant:** continuation text stays inside the bullet's
+visual column.
+
+```
+- This is a long bullet whose text wraps to a second line, and the
+  continuation stays indented to align with the first character
+  after the `- ` marker. The eye reads it as one bullet.
+```
+
+The rule is about source shape, not render shape. Write markdown source with `-<space>` at column 0. Let the renderer handle wrapping. Do not manually break lines at fixed column widths in ways that put wrapped text at column 0.
+
+**Alignment is the renderer's job too.** Same principle as line-wrap. Terminals left-align by default. That is the right shape. Do not embed CSS, HTML, or padding to force full-justify or center alignment. The rule scopes source shape, not render shape.
+
+### 8. Headers use `##` and `###` for color signals
+
+Most terminal + web markdown renderers give `##` and `###` headers a color or weight signal. Bold plain text (`**Section**:`) does not get the same signal. The color difference is what lets the operator's eye jump between sections on a long response.
+
+**Anti-pattern:** section labels as bold plain text.
+
+```markdown
+**Analysis:** long paragraph here that runs on and on and the
+reader cannot easily spot where the next section starts.
+
+**Recommendation:** more paragraphs.
+```
+
+**Conformant:** section labels as `##` or `###` headers.
+
+```markdown
+## Analysis
+
+Long paragraph here that runs on and on. The `## Analysis` header
+above renders in the harness's header color, giving the eye an
+anchor.
+
+## Recommendation
+
+More paragraphs.
+```
+
+Use `##` for top-level sections in a response; `###` for
+subsections. Do not use `#` (H1) in agent output — that heading
+level is reserved for document titles.
+
+### 9. Skill names and file paths use inline code
+
+Skill invocations (`/luminary`, `/sprint`, `/kiss`) and file paths
+(`.claude/hooks/foo.sh`, `docs/whereami.md`) render distinctly when
+wrapped in inline code spans (backticks). Prose that names them
+without backticks blends into surrounding text.
+
+**Anti-pattern:** skill names and file paths as plain text.
+
+```
+The /luminary skill reads .claude/luminaries/*.md files at every
+session start. Also see the /sprint output and docs/whereami.md.
+```
+
+**Conformant:** skill names and file paths as inline code.
+
+```
+The `/luminary` skill reads `.claude/luminaries/*.md` files at
+every session start. Also see the `/sprint` output and
+`docs/whereami.md`.
+```
+
+Extend the same treatment to:
+
+- **Environment variables** — `ANTHROPIC_BASE_URL`, `HOME`,
+  `SKIP_TURN_PROSE_GRADE`
+- **CLI commands** — `git status`, `gh pr list`, `bash
+  scripts/foo.sh`
+- **Config keys** — `schema_version`, `tier`, `install-class`
+- **Ticket references in code shape** — `#940`, `bassclef#559`
+  (only when quoted verbatim from a source; plain prose can drop
+  the backticks)
+
+Composes with ### 5. Extend ### 5's principle to every skill
+name (with slash prefix), every file path (relative or absolute),
+every env var, every CLI command, and every config key in
+operator-facing prose.
+
+### 10. Bold inline lead for reasoning paragraphs and lists
+
+When a response has 2 or more paragraphs of reasoning, each
+paragraph opens with a **short bold lead phrase** (2-4 words)
+that names the paragraph's point. Blank line separates
+paragraphs. The bold lead renders in the terminal's accent color
+— bassclef gold (`--bc-gold` per `design-tokens.css`) or the
+renderer's chosen highlight. The exact shade is renderer-controlled;
+the source shape is `**bold**`.
+
+Applies when:
+- Paragraph runs 2+ sentences of reasoning
+- Response has 2+ such paragraphs stacked
+- **Numbered or bulleted list items carry multi-sentence reasoning
+  (not one-line items)** — the bold lead sits at the head of each
+  item, followed by an em-dash or a period + space, then the body
+
+Skips:
+- Single-sentence answers (no anchor needed)
+- Yes/no confirmations
+- One-line list items (they are already their own anchor)
+- Tables (they have their own anchors)
+- Code blocks
+
+**Anti-pattern:** wall of reasoning text with no scan anchors.
+
+```
+The subject matter is already structured which lets the description
+inherit that structure. You asked sharp questions which forced short
+answers. There was no hedging pressure so the writing stayed direct.
+```
+
+**Conformant:** bold inline lead per paragraph, blank line between.
+
+```
+**Subject matter already structured.** Bassclef has explicit layers.
+When the thing being described has clear structure, the description
+inherits it.
+
+**Sharp questions.** You cut to the decision, not the background.
+That forces short answers because the right answer actually is short.
+
+**No hedging pressure.** You pushed back on advice. That established
+that correctness matters more than validation. That removes the padding.
+```
+
+**Conformant for lists carrying reasoning:** bold lead on each item.
+
+```
+1. **Ishikawa fishbone earned its keep.** Going broad across 6M
+   categories before five-whys caught the launchd-dead-file
+   mechanism that direct five-whys would have missed.
+
+2. **Operator pause before kickoff was essential.** The 5-lens
+   luminary consult grounded the plan; would have wasted the whole
+   /longrun otherwise.
+
+3. **Linus lens applied honestly to the cross-OS question.** Forced
+   the ADR frame. Producer pays cost. No adopter left behind.
+```
+
+Composes with ### 8 (colored `##` and `###` headers) and ### 4
+(bold category labels in lists). Bold lead phrases work at the
+paragraph scale the way `##` headers work at the section scale.
+Same principle — give the eye a scan anchor.
+
+### 11. Arrow-indent for call chains and pipelines
+
+When describing a sequence of steps that flow into each other (a
+tool chain, a pipeline, a call graph), use the `→` arrow prefix
+with two-space indent for sub-steps. Plain text — no code fence.
+The arrow renders in the same accent color as bold leads on most
+terminals.
+
+**Anti-pattern:** pipeline as flat prose.
+
+```
+The dispatcher fetches the source config then reads the settings
+then reads the sync template then runs the sync then loads the
+skills.
+```
+
+**Conformant:** arrow-prefixed steps, two-space nest for sub-steps.
+
+```
+→ fetch `.bassclef-source.json`
+→ read `.claude/settings.json`
+  → merge project + operator settings
+→ read `presence/install/bassclef-sync.template.sh`
+→ run the sync
+  → symlink skills
+  → symlink rules
+  → symlink hooks
+```
+
+Applies when:
+- Response describes a call chain, pipeline, or sequence of at
+  least 3 steps
+- Sub-steps nest below a parent step
+- The order matters and the reader needs to trace flow
+
+The arrow prefix is a data glyph (per Tufte). It carries the flow
+direction. Composes with ### 5 (inline code for filenames) and
+### 9 (env vars, CLI commands, config keys in inline code).
+
+### 12. Tables + special characters — prefer card format when in doubt
+
+The Claude Code TUI (and some other markdown renderers) has post-processing after markdown parse that can mangle specific characters inside table cells. Standard GFM parsers (pandoc, cmark-gfm) handle these characters cleanly — verified 2026-08-06 with 6-fixture pandoc test on control + apostrophes + escaped pipes + backticks + HTML entities + quotes + backslash. The break happens downstream of GFM, in the renderer itself.
+
+Suspect character class (per operator observation + #966 comment thread hypothesis + #1144 filing):
+
+- Apostrophe `'` — reported to collapse rows or drop cells in the Claude Code TUI; unconfirmed at markdown-parse layer
+- Raw pipe `|` — will always split a cell unless escaped `\|`; that IS a spec-level defect the author must handle
+- Backtick `` ` `` — starts inline code; if unbalanced across a cell, cascades into neighboring cells
+- HTML entities (`&lt;`, `&gt;`, `&amp;`) — safe at GFM layer but some renderers do double-decode
+- Angle brackets `<>` — some renderers treat as HTML fragments if not entity-encoded
+
+**Defensive stance** — three options in order of preference:
+
+1. **Prefer cards for content with special chars.** Per ### 12 sister-rule sections (#966 wide-table cure + #959 prep density card format), authoring-time card format sidesteps the whole class. Use `**Label** — value.` bullets instead of a table when cells contain apostrophes, quotes, or code.
+2. **If a table is the right shape, escape the suspect chars.** `\|` for pipe, `` `\`` `` for backtick, HTML entities for `<>&`. Apostrophes: try `&#39;` if the TUI break reproduces.
+3. **Keep tables narrow AND alphanumeric-first.** Per ### 12 sister-rule (#966), tables past 4 columns collapse. Combined with special-char break, wide-plus-special-char is the worst case.
+
+**Anti-pattern:** ships a wide table (5+ cols) with cells containing apostrophes.
+
+**Conformant:** narrow (≤4 cols) table with alphanumerics only, OR card format for anything with special chars.
+
+**INSTEAD-block — per-character cure recipes** (per #1144 body step 3):
+
+- Apostrophe `'` in cell text — write as `&#39;` (HTML entity) OR replace with typographic apostrophe `'` (U+2019) OR move content to card
+- Straight double quote `"` in cell text — write as `&quot;` OR replace with typographic quotes `""` (U+201C / U+201D) OR move to card
+- Raw pipe `|` — always write as `\|` inside cells; unescaped pipes split cells at GFM parse time (spec-level)
+- Backslash `\` in cell text — safe when not preceding a pipe; when followed by pipe use `\\|` to keep the backslash literal
+- Angle brackets `<` `>` — write as `&lt;` and `&gt;`; raw brackets sometimes parse as HTML fragments in TUI post-processing
+- Backtick `` ` `` — balance inside cells; unbalanced backticks cascade inline-code state into neighboring cells; when carrying literal backticks use HTML entity `&#96;`
+- Combined `'` + `"` in the same cell — worst case; move to card. Contractions plus quoted phrases collapse rows in the Claude Code TUI per operator screenshots (whereami L30 of 2026-08-13a session)
+
+The reproducer at `#1144` characterizes which classes trigger flatten in the current Claude Code TUI. When operator observation surfaces a new class beyond this list, extend the block via a follow-on PR.
+
+Composes with sister rules — #966 (wide-column threshold), #967 (section-anchor spacing), #959 (prep density card format).
+
+## What NOT to do
+
+- Terminal color codes (renderer-dependent — breaks in different UIs)
+- **Decoration emoji** — do not use emoji for ornament (✨, 🎉, 🚀
+  at the head of sections)
+- Nested bold-inside-header (visual noise, no added signal)
+- More than one `#` heading level per response (start at `##`)
+- **Do not embed CSS, HTML, or padding to force alignment or
+  justification.** Renderers left-align by default; that is the
+  correct shape. Full-justify and center are not source-level
+  markdown signals.
+
+**Data glyph carve-out** (per Tufte). A glyph that carries data is
+allowed, even encouraged. Examples:
+
+- Risk glyphs in tables — `🟢 low` / `🟡 med` / `🔴 high` (encodes
+  data on a shared axis)
+- Gate signals emitted by hooks — `🛑 BLOCKED:`, `⚠ ADVISORY:`
+  (encodes state)
+- Flow arrows — `→` in call chains (encodes direction)
+
+The rule is Tufte's — data-ink is welcome; decoration ink is not.
+A `🎉` at the head of a section is decoration. A `🟢` inside a
+risk column is data.
+
+INSTEAD: use plain markdown primitives (bold, italics, blockquotes,
+code fences) for emphasis; let the operator's renderer decide visual
+treatment. Reserve emojis for gate signals the hook itself emits or
+for data glyphs that encode information the reader needs to scan.
+
+## Applies to
+
+- Session-end summaries
+- PR descriptions generated by the agent
+- `/sprint`, `/whereami`, `/whats-the-plan` outputs
+- `/value-prop`, `/feynman`, `/kiss` outputs
+- `/diagnose`, `/architect-review`, `/pattern-review` reports
+- Any gut-check or status report longer than a few sentences
+
+## Does NOT apply to
+
+- Short answers (<3 sentences) — keep single-line answers single-line
+- Tool-output relays (commit messages, test output) — don't reformat
+- Code content — never decorate diff blocks
+- When the operator explicitly asks for "just the bullet" / "one line"
+
+INSTEAD for the exempt cases: pass the content through verbatim
+(tool output) or match the requested format (operator-specified).
+Visual hierarchy is a tool, not a mandate.
+
+## Relationship to other rules
+
+- `commit-conventions.md` — commit messages have their own format
+  discipline; this rule doesn't override them
+- `session-artifacts.md` — chronicle + journal entries have their own
+  templates; this rule applies to the agent's conversational output
+  around them, not the artifacts themselves
+- `artifact-ingestion.md` — "Sources read" blocks satisfy the
+  structured-output requirement; they're already compliant with this
+  rule
+
+## Enforcement
+
+Methodology-level. No hook today. If agent output consistently ignores
+the rule across sessions, a post-response lint could be added as a
+Stop hook — but the first line of defense is the rule loading into
+every session via `additionalDirectories`.
+
+## Override path
+
+None needed. The rule prescribes a style; operator may request
+alternative formatting per-response ("just give me the bullet list")
+and the agent complies without rule violation.

package/dist/lite/.claude/rules/we-dont-break-adopters.md

@@ -0,0 +1,103 @@
+---
+tier: lite
+description: "Bassclef adopts Linus Torvalds's rule: we do not break adopters."
+---
+
+# We don't break adopters
+
+Bassclef adopts Linus Torvalds's rule: **we do not break adopters**. Every change to a surface adopters see must keep their existing setup working. When a change would break an adopter, bassclef pays the migration cost. Adopters never pay for bassclef's internal cleanup.
+
+**Adopter-count threshold (per ADR-041, added 2026-07-17):** the mechanism for keeping adopters working scales with adopter count.
+
+- **N ≤ 24 active adopters** (current: 5) — substrate renames ship immediate. Old vocabulary in prior artifacts (session logs, past goal docs, chronicles, closed PRs) reads through `standards/vocabulary-migration.json`. No compat-shim SKILL stubs per rename. No 90-day grace window on prose. The operator Slacks each adopter about renames as they ship.
+- **N ≥ 25 active adopters** — the full compat-shim discipline returns: rename ships with compat alias, fixture, migration manifest, 90-day grace window on prose, adopter changelog entry.
+
+Adopter count read from `standards/bassclef-source-consumers.json` and `.claude/rules/sibling-smoke-after-substrate-change.md` (sibling-smoke rule ships at standard tier). A backlog ticket tracks the counter mechanism (see ADR-041 Decision 4).
+
+**Behavior changes stay under full discipline regardless of adopter count.** API contract changes, schema shape changes, and hook filename changes still ship with compat shims — the translation table cannot help there. Only vocabulary renames (word-for-word substitution) qualify for the translation-table path.
+
+This rule is the methodology layer. The mechanical layer (CI test that clones a representative adopter and verifies their sync hook against the proposed bassclef HEAD; pre-rename validation; the bassclef-source-redirect registry) is Phase 2 work tracked under bassclef#1360.
+
+## When this rule fires
+
+Any change to bassclef-upstream or public bassclef that touches an **adopter-observable surface**:
+
+**Filesystem surfaces:**
+- Filesystem paths under `~/src/sunj-labs/` that adopter repos symlink into (`canonical/`, `bassclef/`, etc.)
+- Symlink targets inside `<adopter>/.claude/hooks/` or `<adopter>/.claude/skills/`
+- Filenames referenced by adopter `.claude/settings.json` (e.g., the bassclef-sync filename (renamed from a former canonical name per ADR-031))
+- Schema shape of state-spine files (entity types, required frontmatter fields, marker formats)
+- `settings.json` `additionalDirectories` path conventions
+- Repo names and sync URLs in `.bassclef-source.json`
+- Hook filenames, agent names, skill directory names that adopter automation invokes
+
+**gh API surfaces (per bassclef-upstream#404):**
+- Label names — rename affects `gh issue list --label X`, `gh pr list --label X`, saved filter URLs, and webhook payloads
+- Label descriptions — visible on hover in GitHub UI + in `gh label list` output; carry brand vocabulary adopters quote
+- Repo description — visible on repo home page + in `gh repo view --json description` + at discovery surfaces
+- Repo topics — discovery + search surface
+- Milestone titles + descriptions — adopters filter by these
+- Project descriptions (gh projects v2) — when used for cross-repo coordination
+
+Use `scripts/migrate-gh-surfaces.sh` (sister to `migrate-adopter-references.sh`) to sweep gh API surfaces during a rename event. Defaults to `--dry-run`; operator runs `--apply` after confirming the proposed diff.
+
+Does NOT fire on:
+- Internal bassclef refactors that don't change any of the above (private/methodology docs, operator-private content)
+- Strict additions (new skills/rules/hooks that don't replace existing surfaces)
+- gh API surfaces internal to a repo (issue body content, PR review comments, individual issue numbers — those have their own discipline)
+
+## What the rule requires
+
+When a substrate change touches an adopter-observable surface:
+
+1. **Compatibility shim** — the old surface must keep working. Filesystem rename → leave a symlink at the old path. Filename rename → keep an alias or a one-line forwarding stub at the old name. Schema field rename → continue accepting both during the deprecation window.
+2. **Migration manifest** — file at `docs/operator-private/forward-port-registry/migrations/<date>-<change-slug>.md` documenting: what changed, what the shim is, when adopters can safely remove it, the path forward.
+3. **Adopter changelog entry** — when /release ships the change to public bassclef, the PR body's Summary section names the rename + the shim + when the shim retires.
+4. **Deprecation period** — minimum one /release cycle between "shim in place + old surface deprecated" and "shim removable / breaking change ships." Documented explicitly per change.
+5. **Override path** — if a breaking change is genuinely unavoidable, file an ADR explaining why, AND add a `**BREAKING:**` section to the next /release's PR body, AND set the deprecation period to ≥3 release cycles for any high-blast-radius surface.
+
+## Anti-patterns
+
+These shapes violate the rule:
+
+- **Silent rename** — old name removed, no shim, adopters discover when they `git pull` and something disappears. (Exactly what tonight's `mv canonical bassclef` did before the rescue symlink.)
+- **"It works on my machine" testing** — substrate-renames tested only against the operator's own setup, not against adopter sync paths.
+- **Breaking change disguised as feature work** — a feat: commit that happens to rename a public schema field; adopters' parsers break silently.
+- **One-shot fallback** — the existing `bassclef-sync.sh` line `if [ -d $CWD/../bassclef ]; then ... else $CWD/../canonical` is a one-shot fallback, NOT a compat shim. It papers over the rename for new clones; it doesn't help adopters who already have stale symlinks.
+
+INSTEAD of any of those: leave the old surface in place as a redirect/symlink/alias; deprecate it explicitly with a date; ship the migration manifest; surface the change in the adopter changelog.
+
+## How this composes with existing substrate
+
+- `architecture/decisions/ADR-024-forward-port-registry.md` — Strategy A-clean (replace adopter-facing names, no grace period) was the prior default. **This rule supersedes that for adopter-observable surfaces** — compat shims and grace periods are now required. Operator-internal rewrites (chronicles, ADRs, iteration-bets) keep Strategy A-clean.
+- `architecture/decisions/ADR-019-reference-vs-vendor-distribution.md` — reference-binding adopters (HTTP API, agent-read URLs) need URL-stability; vendor-binding adopters need filesystem-path-stability. This rule covers both.
+- `architecture/decisions/ADR-029-release-pipeline.md` — every /release that touches an adopter-observable surface MUST include a migration-manifest reference in the PR body.
+- `architecture/decisions/ADR-030-adopter-inbox-flow.md` — adopters file issues when something silently breaks; this rule makes those issues a defect signal, not an acceptable channel.
+- `architecture/decisions/ADR-031-non-breaking-changes-adopter-discipline.md` — the architectural decision that adopts this rule as Tier 1.
+- `architecture/dual-repo-flow.md` — contains the "Non-breaking changes to adopters" section that this rule operationalizes.
+
+## Override path
+
+`SKIP_ADOPTER_COMPAT=1 <command>` — for genuinely-exceptional cases. Logged via trace-helper. Use only when:
+
+- The breaking change ships under an explicit ADR with `**BREAKING:**` PR body section
+- Deprecation period ≥3 /release cycles has elapsed since the deprecation announcement
+- A migration manifest exists with documented automated remediation
+
+INSTEAD of overriding for routine work: write the compat shim. The cost is small (one symlink, one alias, one forwarding stub); the adopter trust compounds across every future release.
+
+## Composes with
+
+- `@luminary linus-torvalds` — anchor for the discipline (we don't break userspace)
+- `@luminary hyrum-wright` — theoretical foundation (with enough users, all observable behaviors are depended on)
+- `@luminary michael-nygard` — circuit-breaker / stability-pattern shape
+- `@luminary vaughn-vernon` — anticorruption layer between bassclef-internal renames and adopter-observable state
+- `@luminary frederick-brooks` — conceptual integrity vs migration cost trade-off
+- `.claude/rules/destructive-operations.md` — sister discipline at the local-action layer
+- `.claude/rules/sdlc-gates.md` — temperance gate must fire before any rename touching adopter-observable surfaces
+
+## When the discipline costs more than the rename benefit
+
+Sometimes the migration cost will exceed the rename benefit. That's a signal NOT to do the rename. Adopter compatibility is the constraint that disciplines bassclef-internal refactoring — if a rename can't be made non-breaking, the rename probably isn't worth doing. This is Brooks's conceptual-integrity discipline as a budget, not as a license.
+
+Closes the methodology gap surfaced 2026-06-21. Phase 2 mechanical layer tracked at bassclef#1360.