@thebassclef/lite 0.1.3 → 1.0.0

package/substrate/.claude/rules/visual-hierarchy.md

@@ -1,437 +0,0 @@
----
-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.
-
-## Why this rule exists
-
-Captured from operator feedback across multiple sessions (memory entry `feedback_visual_hierarchy.md`). Agent responses with headers like "Key design choices worth calling out" and "Skill summary" blended into surrounding text. On mobile screenshots the eye could not jump to sections. The operator re-read the whole response to find the one they wanted.
-
-Visual hierarchy is not cosmetic. It is what makes long responses usable on the surfaces operators actually work on.
-
-Sections 7-9 landed 2026-07-26 per ticket #914. Two mobile screenshots the operator shared in session `chronicle/2026-07-26d-cures-2-3-5-shipped.md` motivated the extension. The reference output showed hanging-indent bullets, colored `##` headers, and inline-code skill names as scannable anchors. Bassclef's agent output was missing those three signals. The extension prescribes them at the source shape so any conforming renderer produces the same scannability.
-
-Section 10 (bold inline lead) landed 2026-07-27 per ticket #936. Sections 4 (prose enumeration shape), 9 (env vars + CLI + config keys), 10 (numbered and bulleted list reasoning), 11 (arrow-indent pipelines), and the "What NOT to do" data-glyph carve-out landed the same day. Six operator-shared screenshots showed the target output shape — bold leads at paragraph heads, arrow-indent pipelines, inline code for env vars and paths. Bassclef renderers use the accent color from `design-tokens.css` — `--bc-gold` (#F5B83D) for warm highlight, `--bc-orange` (#E85D04) for the master burnt orange. The exact shade is the renderer's choice. The source shape is `**bold**` and inline code fences.
-
-## 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/substrate/.claude/rules/we-dont-break-adopters.md

@@ -1,126 +0,0 @@
----
-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.
-
-## Why this rule exists
-
-2026-06-21 evening. Operator renamed `~/src/sunj-labs/canonical` → `~/src/sunj-labs/bassclef` on their machine. Every adopter repo on the machine broke. The list: poa, twoDo, family-recipe-2, eugene-supplements, quorum. Each had 30+ broken symlinks pointing through `../canonical/.claude/hooks/<name>.sh`. poa's `/longrun` start emitted 6+ PreToolUse hook errors per Bash tool call. Non-blocking but noisy. Real failures got masked.
-
-The rename was reasonable (the GitHub repo had been renamed canonical → bassclef weeks earlier; the local folder was finally catching up). The lack of compatibility-shim discipline made it cascade.
-
-This is Hyrum's Law in action. Every adopter depended on the observable path `~/src/sunj-labs/canonical/`. Bassclef never named that path in any contract. With enough adopters, every observable behavior becomes essential.
-
-Linus's 30-year rule applies directly. The Linux kernel does not break userspace. Even when userspace depends on something the kernel never promised. The kernel team pays the cost. Bassclef takes the same stance.
-
-## 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
-
-## Refs
-
-- bassclef#1360 — substrate-rename adopter-migration discipline gap (mechanical layer Phase 2)
-- poa#1251 — poa-specific migration sister ticket
-- ADR-031 — non-breaking-change adopter discipline decision
-- ADR-024 — forward-port-registry (this rule extends/supersedes for adopter-observable surfaces)
-- ADR-019 — reference vs vendor distribution
-- 2026-06-21 chronicle — the rename + cascade + rescue
-
-## Retirement condition
-
-This rule retires only if bassclef stops having adopters. The mechanical-layer Phase 2 work may reduce the methodology cost but does not retire the discipline. Every release continues to carry adopter compatibility as Tier 1.
-
-## 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.