@thebassclef/lite 1.0.4 → 1.1.1

package/dist/lite/.claude/luminaries/john-ousterhout.md

@@ -0,0 +1,94 @@
+---
+tier: lite
+name: John Ousterhout
+slug: john-ousterhout
+claimed_by: [architect, reviewer, builder]
+referenced_by_skills: [pattern-review, decompose]
+primary_domain: engineering
+depth: stub
+sources:
+  - type: book
+    title: "A Philosophy of Software Design"
+    authors: ["John Ousterhout"]
+    year: 2021
+    edition: "2nd"
+    url: "https://web.stanford.edu/~ouster/cgi-bin/aposd.php"
+    isbn: "9781732102217"
+    methodology_covered:
+      - "Deep modules — small interface hiding complex implementation"
+      - "Complexity is incremental — small drips add up; resist each one"
+      - "Define errors out of existence — design APIs so error conditions cannot occur"
+      - "Comments encode design decisions the code itself cannot"
+      - "Strategic vs tactical programming — invest in design over short-term wins"
+      - "Information hiding — modules expose only what callers need; the rest stays internal"
+  - type: course
+    title: "Stanford CS 190 — Software Design Studio"
+    authors: ["John Ousterhout"]
+    year: 2018
+    url: "https://web.stanford.edu/class/cs190/"
+    methodology_covered:
+      - "Source course where the principles in A Philosophy of Software Design were developed and tested"
+verification_status: verified
+description: "\"Complexity is anything that makes software hard to understand or modify."
+---
+
+# John Ousterhout
+
+## Signature
+
+*"Complexity is anything that makes software hard to understand or modify. The goal of software design is to reduce complexity."*
+
+Stanford professor. Creator of the Tcl scripting language and Raft consensus protocol. Author of **A Philosophy of Software Design** (2018, 2nd ed 2021), the modern SENTINEL_bassclef_text on simplicity, deep modules, and complexity-as-incremental-drift. Pairs with Beck (TDD) and Fowler (refactoring tactics): Beck asks "is it tested?", Fowler asks "how do I restructure it?", Ousterhout asks "is it the right shape in the first place?"
+
+## Discipline anchor
+
+**Design judgment + complexity-as-enemy.** Ousterhout supplies the WHY-to-refactor framing that Beck and Fowler leave to the engineer's judgment.
+INSTEAD: Beck owns the red-green-refactor cycle; Fowler owns the catalog of refactorings; Ousterhout owns the design-quality lens that tells you whether the shape you're refactoring toward is actually better. Without this lens, refactors can shuffle complexity without reducing it.
+
+This luminary fires on architectural-judgment moments — picking module boundaries, naming interfaces, deciding whether to split a class, evaluating whether a comment is doing real work or restating the code.
+INSTEAD of citing Ousterhout for test mechanics, refactoring tactics, or pattern catalog selection: route those concerns to Beck, Fowler, and GoF respectively.
+
+## Key principles
+
+- **Deep modules** — A module is deep when it has a small interface and a large, complex implementation hidden behind it. Shallow modules push knowledge to callers and produce a system where understanding the whole requires understanding every part. When tempted to split a class for "smaller files," ask: does the split produce TWO deep modules, or TWO shallow ones?
+  INSTEAD of defaulting to file-size as the splitting metric: use interface-shape as the metric. Two deep modules from a split is a win; two shallow modules from a split is a regression even if the line count drops.
+
+- **Complexity is incremental** — Complexity accumulates one small decision at a time. A single special case, a single dependency, a single inconsistency feels harmless. Sum across a session, a release, a year — that's how systems become unmaintainable. The discipline is to resist each small drip rather than promise to clean up the puddle later.
+  INSTEAD of deferring cleanup to a future refactor: refuse the small drip at the moment it appears. Future-refactor cleanups almost never happen; the cost of resisting at write-time is the cheapest moment.
+
+- **Define errors out of existence** — Design APIs so error conditions cannot occur, rather than designing APIs that throw errors and asking every caller to handle them. The classic example: `unset` on a variable that does not exist is an error in older shells.
+  INSTEAD: the right shape is for `unset` to be idempotent. Applied to bassclef: hooks that BLOCK on missing artifacts are weaker than hooks that bootstrap the artifact when absent, where bootstrapping is safe.
+
+- **Comments encode design decisions code cannot** — Code says what it does. Comments must say what the code cannot — the WHY (invariant), the WHAT-IF (alternative considered and rejected), the WATCH-OUT (subtle constraint a future reader will miss).
+  INSTEAD of comments that restate code: write comments that record decisions. This principle is load-bearing for bassclef's `bassclef-configs.jsonc` discipline: inline comments are the adopter-discovery surface, not exhaust.
+
+## When to cite this luminary
+
+Cite `@luminary john-ousterhout` when:
+
+- **Reviewing module boundaries** (`/pattern-review`) — is this class deep or shallow? Would splitting it make two deep modules or two shallow ones?
+- **Decomposing responsibilities** (`/decompose` GRASP audit) — does each responsibility assignment produce a deep module, or push complexity to callers?
+- **Designing bassclef-configs.jsonc or other adopter-edit surfaces** — inline comments must encode WHY-to-pick and WHEN-to-pick, not restate the field name. This is "comments-as-design" applied to substrate configuration.
+- **Evaluating whether complexity is essential or accidental** — when a feature feels harder to ship than it should, ask whether the difficulty is in the problem domain (essential) or in how earlier decisions shaped the code (accidental). Accidental complexity is the refactor signal.
+
+When the question is test mechanics, refactoring step-by-step, design-pattern selection, distributed-systems scalability, or algorithmic complexity, route elsewhere.
+INSTEAD: cite Beck (test mechanics), Fowler (refactoring tactics), GoF (pattern selection), Kleppmann (Phase C, scalability anchor), Bentley (Phase C, Big-O practical discipline).
+
+## Composes with
+
+- **Kent Beck** — TDD makes deep modules testable. Tests verify that the interface is actually small; without tests, deep modules look the same as shallow ones from outside.
+- **Martin Fowler** — Refactoring tactics serve Ousterhout's design judgment. Fowler tells you HOW to extract a method; Ousterhout tells you WHETHER the extraction produces a deeper module or shuffles complexity.
+- **Gang of Four** — Design patterns are deep-module exemplars when applied well. The Decorator pattern is a deep module; the over-applied Visitor pattern is often shallow because it pushes traversal logic to callers.
+- **Michael Feathers** (bassclef luminary catalog) — Characterization testing makes it safe to refactor toward deeper modules in legacy code where the original boundaries are unclear.
+
+## Refs
+
+- bassclef#1036 — this luminary's filing ticket
+- bassclef#867 — anchor-luminary verification pattern (stub-tier shape this entry follows)
+- bassclef#1037 — sibling ticket; testing-tier-config primitive (Ousterhout's comments-as-design framing anchors the Tier 0 vs Tier 3 comment rules)
+- bassclef#478 — `@pattern` annotation discipline (analog for `@luminary` citation discipline)
+
+## Stub-to-full
+
+This is a stub entry per bassclef#867 verification pattern — frontmatter plus 4-section body grounded in primary source. Full body (worked examples in bassclef's own substrate, anti-patterns catalog, signature stack-translation paragraph) is deferred to a luminary-authoring follow-on bet.
+INSTEAD of blocking citation on full-body completion: the stub is sufficient for `/pattern-review` and `/decompose` to invoke the lens today; the full entry deepens worked examples in a later pass.

package/dist/lite/.claude/luminaries/karl-popper.md

@@ -0,0 +1,132 @@
+---
+tier: lite
+name: Karl Popper
+slug: karl-popper
+claimed_by: [architect, reviewer, closer]
+referenced_by_skills: [diagnose, architect-review, promote, state-a-problem]
+primary_domain: philosophy
+depth: full
+sources:
+  - type: book
+    title: "The Logic of Scientific Discovery"
+    authors: ["Karl R. Popper"]
+    year: 1959
+    original_year: 1935
+    url: "https://www.routledge.com/The-Logic-of-Scientific-Discovery/Popper/p/book/9780415278447"
+    isbn: "9780415278447"
+    methodology_covered:
+      - "Falsifiability as demarcation criterion for scientific claims"
+      - "Bold conjectures + severe tests as the actual method"
+      - "Verification is impossible; falsification is decisive"
+  - type: book
+    title: "Conjectures and Refutations: The Growth of Scientific Knowledge"
+    authors: ["Karl R. Popper"]
+    year: 1963
+    url: "https://www.routledge.com/Conjectures-and-Refutations-The-Growth-of-Scientific-Knowledge/Popper/p/book/9780415285940"
+    isbn: "9780415285940"
+    methodology_covered:
+      - "Knowledge grows by refutation, not confirmation"
+      - "Better theories forbid more; the more a theory forbids the better"
+      - "All observation is theory-laden; there is no view from nowhere"
+  - type: book
+    title: "The Open Society and Its Enemies"
+    authors: ["Karl R. Popper"]
+    year: 1945
+    url: "https://press.princeton.edu/books/paperback/9780691158136/the-open-society-and-its-enemies"
+    isbn: "9780691158136"
+    methodology_covered:
+      - "Piecemeal social engineering over utopian planning"
+      - "Institutions that expose leaders to falsification"
+      - "Critical rationalism as social discipline"
+verification_status: verified
+description: "\"Good tests kill flawed theories; we remain alive to guess again.\""
+---
+
+# Karl Popper
+
+## Signature
+
+*"Good tests kill flawed theories; we remain alive to guess again."*
+
+Austrian-British philosopher (1902-1994). Author of *The Logic of Scientific Discovery* (Hutchinson, 1935 German / 1959 English) and *Conjectures and Refutations* (1963). The bassclef voice on falsifiability, hypothesis testing, and the discipline that a claim which cannot be falsified is steering language, not truth.
+
+## Core methods
+
+- **Falsifiability as demarcation** — a claim is scientific to the extent that it can be shown wrong. Unfalsifiable claims may be inspiring; they are not knowledge. In substrate work: an assertion with no rebuttal cell is either a definition or an act of faith.
+- **Conjectures and refutations** — knowledge grows by making bold conjectures and then trying hard to break them. The bolder the claim, the more the world it forbids, the more informative it is when it survives testing.
+- **The severity of tests** — a test that could have refuted the claim but did not is severe. A test the claim was designed to pass is weak. Testing is not a formality; it is the entire epistemic engine.
+- **Piecemeal engineering** — for social + technical systems, small changes that can be reverted are better than sweeping redesigns that cannot. The value is not the change itself; it is the reversibility.
+- **All observation is theory-laden** — there is no raw data. Every observation runs through the framework the observer brings. This is why the warrant matters, not just the data.
+
+## When to channel this luminary
+
+When the primary risk is root-cause claims, cure recommendations, or diagnostic assertions shipping without stated conditions for being wrong. Popper dominates for `/diagnose` output (root-cause hypotheses), audit findings (severity claims), cure recommendations (why THIS cure, not another), and any assertion the operator will act on. Pair with Toulmin (Popper's rebuttal cell IS Toulmin's rebuttal cell) and Peirce (Peirce names the alternatives; Popper says test each).
+
+Pass-through cases (Popper adds no value):
+
+- Pure definition claims ("this is what we call X"). INSTEAD of falsification testing: preserve the definition; it is a naming act, not a knowledge claim.
+- Aesthetic preference statements. INSTEAD of falsification testing: preserve the preference; it is Peirce's pragmatic-maxim category, not Popper's.
+- Operator-authored directives. INSTEAD of falsification testing: honor the directive; operator preference is a starting point for inquiry, not a hypothesis to be falsified.
+
+## Stack translation
+
+In bassclef substrate work:
+
+- **`/diagnose` output** → hypothesis + falsification test. What repro would show the hypothesis is wrong? Write it before writing the fix.
+- **Audit finding severity** → what evidence would demote HIGH to MEDIUM? Name it. If nothing would demote it, the severity is either a definition or a decree.
+- **Cure recommendation** → what evidence would show this cure does not close the class? Name the test. If no test would falsify, the cure is faith not analysis.
+- **Turn estimate** → the estimate is a prediction. What actuals would falsify it? Grounding estimates in prior WU turn counts is Popper's discipline — the prior WUs are the tests the estimate survives.
+- **Root-cause claim** → the cause is the hypothesis. Removing it should remove the symptom. If removal does not remove the symptom, the cause was wrong. Test before shipping.
+
+## Anti-patterns it prevents
+
+- **Unfalsifiable severity** — "This is HIGH-severity because it matters." No evidence would demote it. Not a claim.
+
+  INSTEAD: state the criteria that would demote the finding. If none exist, the finding is a decree, not evidence.
+
+- **Root-cause attribution without repro** — "The cause is X" with no test that would show removing X does not remove the symptom.
+
+  INSTEAD: state the repro that would falsify. Run it. Ship the fix only after the test discriminates.
+
+- **Cure recommendation without a losing condition** — "This cure closes the class" with no criterion that would show it does not.
+
+  INSTEAD: state the observation that would show the class still reproduces after the cure. That IS the acceptance test.
+
+- **Confirmation-only diagnosis** — running only the test the hypothesis passes.
+
+  INSTEAD: run the severest test the hypothesis could survive. If it survives that, it is stronger than a test that was designed to pass.
+
+- **Sweeping redesign** — replacing a hook, a rule, or a substrate primitive with a cleaner version, all at once, no reversibility path.
+
+  INSTEAD: ship the smallest reversible change. Piecemeal engineering ships smaller changes with revert paths.
+
+## Worked example
+
+For a claim that a hook is dead-letter:
+
+Popper's discipline:
+
+- **Conjecture**: The hook `X.sh` is dead-letter — it exists on disk but is not wired in `.claude/settings.json`. Its checks do not fire.
+- **Severe test**: Deliberately trigger the condition the hook is supposed to catch. Author a file that violates the hook's stated rule; attempt to write it. If the write succeeds without the hook firing, the conjecture is confirmed. If the hook fires and blocks the write, the conjecture is falsified.
+- **Result**: Wrote the violating file. Write succeeded. No BLOCK message. The hook did not fire. Conjecture survives; hook is dead-letter.
+- **What would falsify**: A BLOCK message appearing in the write attempt. It did not appear.
+
+Without Popper's discipline the diagnosis would read "the hook seems broken" — no test, no falsification criterion, no way to distinguish "actually broken" from "I did not trigger it right." INSTEAD: state the conjecture, name the severe test, run it, report the result.
+
+## Sources
+
+- *The Logic of Scientific Discovery* — Popper, Hutchinson (1935 German original; 1959 English translation; Routledge reprint)
+- *Conjectures and Refutations: The Growth of Scientific Knowledge* — Popper, Routledge (1963)
+- *The Open Society and Its Enemies* — Popper, Routledge (1945; Princeton reissue 2020)
+- *Objective Knowledge: An Evolutionary Approach* — Popper, Oxford University Press (1972)
+- Stanford Encyclopedia of Philosophy: entry on Popper — plato.stanford.edu/entries/popper/
+
+## Related luminaries
+
+- **Stephen Toulmin** — Toulmin's argument model gives the shape (claim/data/warrant); Popper sharpens the rebuttal cell. A Toulmin argument without the rebuttal cell is a Popperian pseudo-claim. Both ship in bet 2026-07-01b WU-2.
+- **Charles Sanders Peirce** — Peirce's abductive reasoning names multiple hypotheses; Popper says test each one severely. Peirce fills the alternatives; Popper says which alternative survives. Both ship in bet 2026-07-01b WU-2.
+- **W. Edwards Deming** — Deming's PDCA cycle is Popper's conjecture-and-refutation applied to management. Plan (conjecture), Do (test), Check (see if the test broke the plan), Act (revise).
+- **Michael Feathers** — Feathers' characterization tests are severe tests for legacy code. Without characterization tests, refactoring is unfalsifiable — no test would show the refactor broke behavior.
+- **Kent Beck** — Beck's TDD is Popper at the code layer. The red test is the severe test the claim must survive to become green. TDD without a red step is unfalsifiable design.
+
+Anchors `.claude/rules/assert-only-after-verify.md` alongside Toulmin + Peirce. Primary luminary for `/diagnose` skill in root-cause hypothesis testing.

package/dist/lite/.claude/luminaries/kent-beck.md

@@ -0,0 +1,168 @@
+---
+tier: lite
+name: Kent Beck
+slug: kent-beck
+claimed_by: [builder, reviewer]
+referenced_by_skills: [verify, pattern-review]
+primary_domain: engineering
+depth: full
+sources:
+  - type: book
+    title: "Test-Driven Development: By Example"
+    authors: ["Kent Beck"]
+    year: 2002
+    url: "https://www.pearson.com/en-us/subject-catalog/p/test-driven-development-by-example/P200000009450"
+    isbn: "9780321146533"
+    methodology_covered:
+      - "TDD red/green/refactor cycle"
+      - "Test-first as design discipline, not verification afterthought"
+      - "Tests as the first client of your code"
+  - type: book
+    title: "Extreme Programming Explained: Embrace Change"
+    authors: ["Kent Beck", "Cynthia Andres"]
+    year: 2004
+    url: "https://www.pearson.com/en-us/subject-catalog/p/extreme-programming-explained-embrace-change/P200000009290"
+    isbn: "9780321278654"
+    methodology_covered:
+      - "XP practices: TDD, pair programming, continuous integration, simple design"
+      - "Embrace change as a competitive advantage"
+      - "Four rules of simple design — passes tests, reveals intention, no duplication, fewest elements"
+  - type: book
+    title: "Tidy First? A Personal Exercise in Empirical Software Design"
+    authors: ["Kent Beck"]
+    year: 2023
+    url: "https://www.oreilly.com/library/view/tidy-first/9781098151232/"
+    isbn: "9781098151249"
+    methodology_covered:
+      - "Tidy First — structural changes commit separately from behavioral changes"
+      - "Don't bundle refactor and feature in one PR"
+      - "Empirical software design — measure what works, adjust accordingly"
+verification_status: verified
+description: "\"Make it work. Make it right. Make it fast. Tests are the first client of your code.\""
+---
+
+# Kent Beck
+
+## Signature
+
+*"Make it work. Make it right. Make it fast. Tests are the first client of your code."*
+
+Extreme Programming (XP) creator. Co-author of **the JUnit framework**.
+Author of **Test-Driven Development: By Example** and **Extreme Programming
+Explained**. The bassclef voice on TDD, simple design, and iterative
+engineering practice.
+
+## Core methods
+
+- **TDD red/green/refactor** — write failing test, write minimum code
+  to pass, refactor with tests passing. Not "write tests after" — the
+  test comes first and drives the design.
+- **Four rules of simple design** — (1) passes all tests, (2) reveals
+  intention, (3) no duplication, (4) fewest elements. Apply in order
+  during refactoring.
+- **Three phases of development** — Make it work (get the feature
+  functional), make it right (clean it up with tests protecting),
+  make it fast (optimize, measured).
+- **Patterns for testability** — Fake It ('Til You Make It, Obvious
+  Implementation, Triangulation. Techniques for moving from red to
+  green without skipping steps.
+- **XP practices** — pair programming, continuous integration, small
+  releases, simple design, refactoring, collective ownership.
+  Practices reinforce each other; removing any degrades the rest.
+- **Tidy First** — distinguishing between structural changes (tidying,
+  no behavior change) and behavioral changes. Commit them separately.
+
+## When to channel this luminary
+
+When the primary risk is code quality degrading under change pressure.
+Beck dominates for teams new to TDD, Construction work where tests
+aren't yet a reflex, and refactoring-heavy iterations. Pair with Fowler
+(refactoring catalog) and Uncle Bob (SOLID principles) for the
+engineering-quality triad.
+
+Do NOT channel Beck for: research code that will be thrown away,
+spike work where discovery matters more than sustainability, or work
+on systems where the test infrastructure doesn't yet exist (wrong
+layer — infrastructure first).
+
+## Stack translation
+
+In Next.js + vitest + Playwright:
+
+- **TDD for pure functions** → write failing unit test in
+  `src/__tests__/`, write function to pass, refactor. Scoring logic,
+  parsing, validation all belong here.
+- **TDD for components** → failing React Testing Library assertion,
+  minimum component to pass, refactor for structure.
+- **TDD for API routes** → failing integration test against real DB +
+  Redis, minimum route implementation to pass.
+- **Tidy First** → structural refactor commits separate from feature
+  commits. "refactor: extract ScoringStrategy interface" + "feat: add
+  ML scorer" as two PRs, not one.
+- **Three phases** → first PR makes feature work, subsequent PRs
+  right/fast. Don't bundle all three.
+
+## Anti-patterns it prevents
+
+- **Test-after** — writing tests once the code "works" produces tests
+  that confirm what exists, not tests that drive design. Beck rejects
+  this as TDD.
+- **Batched refactoring** — saving all cleanup for a quarterly "tech
+  debt sprint." Refactoring is continuous, inside the red/green/refactor
+  loop.
+- **Premature optimization** — making it fast before making it work.
+  The order matters.
+- **Pristine-never-commits** — holding a branch to "get it perfect"
+  before merging. Beck's XP favors small, frequent merges.
+- **Test-less refactors** — rearranging code without tests is just
+  changing code. Can't claim refactor without behavior preservation,
+  and you can't prove preservation without tests.
+- **Tidy mixed with feature** — commit that both refactors and adds
+  behavior makes review and revert harder.
+
+## Worked example
+
+For adding POA deal-stage validation:
+
+Beck's approach:
+1. **Red**: write failing test
+   `test('deal cannot advance past LOI without signed NDA', ...)`
+2. **Green**: add minimum code to pass — if-check in the stage-advance
+   controller
+3. **Refactor**: extract `IStageTransitionPolicy` interface,
+   `NdaSignedPolicy` implementation, `StagePolicyRegistry`
+4. **Tidy commit** separate from feature: "refactor: extract stage
+   transition policy interface" → PR merged first
+5. **Feature commit**: "feat: enforce NDA-signed requirement for LOI
+   advance" → PR merged second
+
+What Beck would NOT produce: a single 400-line PR that adds the
+feature, refactors the policy structure, adds telemetry, and fixes
+three unrelated smells. That's everything bundled.
+
+## Sources
+
+- *Test-Driven Development: By Example* — Beck, Addison-Wesley (2002)
+- *Extreme Programming Explained: Embrace Change* — Beck, Addison-Wesley
+  (2nd ed 2004)
+- *Tidy First?* — Beck, O'Reilly (2023)
+- *Implementation Patterns* — Beck (2007)
+- kentbeck.com + kent-beck.com — primary sites
+- JUnit — software itself is bassclef reference
+
+## Related luminaries
+
+- **Martin Fowler** — Refactoring catalog operationalizes Beck's
+  red/green/refactor loop. Beck credited Fowler's work as foundational.
+- **Robert C. Martin** — SOLID principles frame what "right" looks
+  like in Beck's make-it-right step.
+- **Ward Cunningham** — XP co-creator, Wiki inventor. Historically
+  inseparable from Beck.
+- **Michael Feathers** — Working with Legacy Code handles the
+  before-state (no tests exist) that TDD assumes away. Both
+  luminaries became verification-side primaries on bassclef's
+  `/architect-review` SKILL per bet 27c WU-9.5 (2026-06-27); per
+  ADR-035 substrate-as-system tenet, every rule's mechanism claim
+  is a contract Beck's TDD pins + Feathers's characterization
+  tests verify. See `architecture/audits/2026-06-27-audit-method-blind-spot.md`
+  for the recursive Act phase that named the lens-gap.

package/dist/lite/.claude/luminaries/linus-torvalds.md

@@ -0,0 +1,218 @@
+---
+tier: lite
+name: Linus Torvalds
+slug: linus-torvalds
+claimed_by: [architect, reviewer]
+referenced_by_skills: [release, decompose, architect-review]
+primary_domain: distribution-stability
+depth: full
+solves_problems_brownfield:
+  - "Substrate rename / refactor / path-change broke adopter sessions silently after merge"
+  - "Adopter following a citation in shipped substrate hit a 404 because the referenced path was renamed"
+  - "Hook filename change in bassclef caused adopter's session-start hook to fire stale logic"
+  - "PR ships a cleaner name for a hook / skill / rule and breaks every adopter inheriting through additionalDirectories"
+  - "Sync template version bumped without compat shim — adopter on prior version is in undefined behavior"
+solves_problems_greenfield:
+  - "Designing a new adopter-observable surface where future renames must stay non-breaking"
+  - "Planning a release pipeline that catches adopter-breaking changes before they ship"
+  - "Authoring the first version of an adopter-facing manifest schema where every field becomes load-bearing once used"
+  - "Designing a compat-shim layer ahead of a planned rename so the deprecation window drains cleanly"
+  - "Building a representative-adopter integration test that runs against every substrate change"
+anti_patterns:
+  - "Dev-machine-only test — works for the author, breaks at sync time for adopters"
+  - "Clean-break rename motivated by conceptual integrity — costs more than it saves once observers exist"
+  - "Announcement-as-shim — written notice that the old name has gone away, with no surviving artifact"
+  - "Deprecation window without a real-adopter migration test — the deprecation tail outlasts the window"
+sources:
+  - type: archive
+    title: "LKML 2012-12-23: 'We do not break userspace'"
+    authors: ["Linus Torvalds"]
+    year: 2012
+    url: "https://lkml.org/lkml/2012/12/23/75"
+    methodology_covered:
+      - "Userspace stability as non-negotiable kernel discipline"
+      - "Regressions are bugs even when prior behavior was buggy"
+  - type: book
+    title: "Linux Kernel Development (3rd ed.)"
+    authors: ["Robert Love"]
+    year: 2010
+    url: ""
+    methodology_covered:
+      - "Kernel ABI stability discipline across versions"
+      - "Syscall number preservation; new behavior gets new syscall"
+  - type: archive
+    title: "Stability of the Linux ABI — Linux Foundation TAB"
+    authors: ["Linux Foundation Technical Advisory Board"]
+    year: 2014
+    url: "https://www.linuxfoundation.org/"
+    methodology_covered:
+      - "Module ABI stability commitments"
+      - "Internal API churn vs external ABI freeze"
+  - type: talk
+    title: "Driver ABI Stability"
+    authors: ["Greg Kroah-Hartman"]
+    year: 2015
+    url: "https://elinux.org/ELC_2015_Presentations"
+    methodology_covered:
+      - "Why kernel internals stay unstable on purpose; why exported ABI stays frozen"
+  - type: archive
+    title: "LKML 'regressions are bugs' thread (multiple instances 2008–2021)"
+    authors: ["Linus Torvalds", "LKML community"]
+    year: 2008
+    url: "https://lkml.org/"
+    methodology_covered:
+      - "Revert-on-regression default"
+      - "Producer pays migration cost, adopter pays nothing"
+verification_status: verified
+description: "\"We do not break userspace.\" — INSTEAD: the kernel team pays the migration cost so every program that ran yesterday keeps running today."
+---
+
+# Linus Torvalds
+
+## Signature
+
+*"We do not break userspace."* — INSTEAD: the kernel team pays the migration cost so every program that ran yesterday keeps running today.
+
+Principal architect of Linux. The kernel's single most-cited rule across 30+ years of evolution is the userspace stability commitment. The cost of evolution rides with the kernel team. Adopters carry zero migration burden. This is the discipline bassclef applies at the substrate → adopter boundary.
+
+## Core principle
+
+Userspace stability is the ceiling, not a tradeoff. Linus's framing (LKML 2012, restated dozens of times since): a change that breaks user programs is a kernel bug, regardless of whether the user program was relying on documented or undocumented behavior. The kernel team has rejected technically-better designs because the migration cost to userspace was too high. Shipped compatibility shims have outlived the original feature by a decade. Permanent code complexity is accepted as the price of adopter trust.
+
+Three operational consequences flow from this:
+
+1. **Regressions are bugs even when prior behavior was buggy.** INSTEAD of fixing forward into a cleaner state: revert, fix the underlying problem from a different angle, ship the fix without changing the observable surface adopters depend on.
+2. **The producer pays the cost.** INSTEAD of telling adopters to migrate: ship the compat shim, keep the old surface alive, document the retirement condition as "when the last known adopter migrates."
+3. **Conceptual integrity has a budget.** INSTEAD of treating rename-for-cleanliness as free: weigh the rename benefit against migration cost × adopter count. When the cost exceeds the benefit, hold the rename.
+
+## What this looks like in Linux
+
+- **Syscall ABI is permanent.** Once a syscall ships, the signature stays. INSTEAD of changing an existing syscall: a new behavior gets a new syscall number; the old one keeps working forever.
+- **Struct layouts grow but stay backward-compatible.** Removed fields stay as reserved holes. INSTEAD of rearranging fields: a new struct gets introduced; the old one stays usable.
+- **/proc and /sys accumulate compatibility commitments.** Even ad-hoc debug surfaces become quasi-stable once tools parse them.
+- **Compatibility shims live forever.** The kernel still supports 32-bit syscalls on 64-bit kernels for old binaries — INSTEAD of forcing a migration to 64-bit.
+- **Regressions revert by default.** When a feature change breaks any adopter, the change reverts. INSTEAD of asking the adopter to adapt: the kernel team re-engineers from a different angle.
+
+## Core methods
+
+Five named methods an agent can invoke by name during review or design:
+
+- **Adopter-observable surface enumeration** — Before any substrate change, list every surface adopters can observe (filesystem paths, hook filenames, schema field names, skill names referenced by settings.json, symlink targets, sync-template version markers). When the enumeration is missing from the PR body, the change is not yet reviewable. INSTEAD of reviewing on faith: send the PR back with a request for the surface list.
+
+- **Compat-shim-first ship discipline** — Build the shim in the same release as the change. Symlink at the old path, alias at the old name, forwarding stub at the old hook filename, schema accommodation that accepts both names during transition. INSTEAD of "ship the rename now, add the shim later": ship both together; the gap between them is the window where adopters break.
+
+- **Real-adopter integration test** — Test the change against a clone of a representative adopter. Run the adopter's actual sync hook against proposed substrate HEAD. Confirm zero observable change. INSTEAD of dev-machine validation: the cold-adopter harness IS the real-adopter test surface; the change waits for the harness when it isn't yet built.
+
+- **Revert-on-regression default** — When a feature change breaks any adopter, revert by default and fix from a different angle. INSTEAD of trading adopter trust for the partial win: adopter trust is the ceiling; the feature is re-engineered.
+
+- **Permanent-shim acceptance** — Accept that some compat shims live forever. The kernel still supports 32-bit syscalls for old binaries. INSTEAD of cycling shims through deprecation: document the retirement condition honestly ("when all known adopters migrate") and expect the answer is "forever."
+
+## When to channel this luminary
+
+When the primary risk is **adopter-observable surface change**. Linus dominates the review lens any time a PR touches:
+
+- Filesystem paths under `~/src/sunj-labs/` that adopter symlinks resolve through
+- Filenames inside `.claude/hooks/`, `.claude/skills/`, `.claude/rules/`, `.claude/agents/` (adopter settings.json + symlinks reference them by name)
+- Schema shapes in `standards/state-spine/schemas/`
+- Sync-template version markers in `presence/install/`
+- `.bassclef-source.json` schema
+- Adopter migration tooling under `scripts/migrate-*`
+- Release pipeline andon decisions (per ADR-029)
+- Rename / move / refactor of any of the above
+
+Pair with Hyrum Wright (provides the theoretical why — observability creates dependency), Michael Nygard (ADR lifecycle for the breaking-change decision), and Vaughn Vernon (anticorruption layer is the structural shape Linus's discipline produces).
+
+Outside this scope, route elsewhere. INSTEAD of channeling Linus for bassclef-internal refactors that touch zero adopter-observable surface: channel John Ousterhout (deep modules) or Kent Beck (TDD cycle). INSTEAD of channeling Linus for operator-private content under `docs/operator-private/`: that content stays in bassclef-upstream and doesn't ship to adopters; Linus's discipline is silent there. INSTEAD of channeling Linus for chronicles and journal entries: those are operator narrative, not contract; voice luminaries apply.
+
+## Stack translation
+
+bassclef is a substrate. Adopters are the userspace. Every adopter-observable surface is a syscall: once shipped, the surface keeps working forever unless an explicit multi-cycle deprecation runs.
+
+Map:
+
+| Linux kernel | bassclef substrate |
+|---|---|
+| Syscall ABI | hook filenames, skill names, agent names referenced by adopter settings.json |
+| `/proc` + `/sys` | filesystem paths under `~/src/sunj-labs/` that adopter symlinks resolve through |
+| Struct layouts | state-spine schema shapes |
+| Module ABI | sync-template version markers in `presence/install/bassclef-sync.template.sh` |
+| Boot interface | `.bassclef-source.json` schema fields |
+| LKML release announcements | `/release` PR body Summary section + adopter changelog entry |
+| Kernel-internal refactors | bassclef-internal refactors touching only `docs/operator-private/`, chronicles, internal scripts unexposed to adopters |
+
+When bassclef renames `canonical → bassclef`, that is the equivalent of removing a syscall. The discipline answer: leave a compatibility shim (symlink, alias, forwarding stub) at the old name. Deprecate explicitly. Give adopters a grace period measured in `/release` cycles. INSTEAD of removing the shim once a deadline passes: remove only with an explicit ADR documenting the breaking change and citing the migration test that proves zero adopter remains on the old name.
+
+## Anti-patterns it prevents
+
+- **Dev-machine-only test.** "It works on my machine." INSTEAD: clone a representative adopter; run their sync hook; confirm zero observable change. The dev machine is one environment among many.
+
+- **Clean-break rename motivated by conceptual integrity.** "The new name is clearer." INSTEAD: weigh the rename benefit against migration cost × adopter count. Hold the rename when the math tips against it. Brooks's conceptual-integrity is a budget, not a license.
+
+- **Announcement-as-shim.** "We told them in advance." INSTEAD: ship the technical artifact (symlink, alias, forwarding stub) that keeps the old name working. Communication is necessary AND insufficient on its own.
+
+- **Single-adopter dismissal.** "Only one adopter uses this surface." INSTEAD: ship the shim anyway. Hyrum's Law applies the moment any adopter observes the surface; declared user count fails as the metric.
+
+- **Deprecation window without a real-adopter migration test.** "We gave them three release cycles." INSTEAD: the migration test verifies adopters actually moved; the calendar window verifies only that time passed.
+
+## Worked example
+
+**Scenario:** Tonight's bet 25e shipped a structural cold-adopter harness. The next bet ships shape b — a sync round-trip harness that runs against a fresh clone. The harness will catch regressions like #336 (bassclef-sync.sh §4 missing PreToolUse template embedding).
+
+**The Linus lens applied at PR-review time for #336 fix:**
+
+1. **Adopter-observable surface enumeration** — the agent reviewing the #336 PR lists every adopter-observable surface the fix touches: the PreToolUse hook matcher, the settings.json template merged into adopter sessions, the hook firing order, and the stderr contract on BLOCK exits. All four are observable; all four must stay stable across the fix. INSTEAD of accepting a PR body that lists only the bug fix: send back for the surface enumeration.
+
+2. **Compat-shim-first** — the fix ships the embedding template AND the test that catches it in the same PR. INSTEAD of "add the embedding now, add the test next bet": same release, or the gap between fix and verification is the window where adopters silently inherit the buggy state.
+
+3. **Real-adopter integration test** — the new shape b harness IS the real-adopter test. Once the harness ships (next bet), the #336 fix gets re-run against the cold-adopter clone and the PreToolUse path fires correctly post-sync. INSTEAD of trusting unit tests alone: the harness validates the adopter-observable surface end-to-end.
+
+4. **Revert-on-regression default** — if the #336 fix causes any adopter-observable regression (a different hook stops firing, a stderr message changes, the merge logic drops an operator key like #340 did), the fix reverts. INSTEAD of trading adopter trust for the partial win: revert, re-engineer from a different angle, ship without changing the observable surface.
+
+5. **Permanent-shim acceptance** — the cp-fallback in additive_merge_settings (the surface #340 patches) is exactly the kind of shim that lives forever. Adopters on older `jq` versions, adopters without `jq` at all, adopters whose settings.json predates the new schema — the cp-fallback covers them all. INSTEAD of removing the fallback once a new merger ships: keep both paths alive; the cost is permanent merge-logic complexity; the benefit is permanent adopter compatibility.
+
+The shape-b harness shipping as a methodology-only document with a deferred mechanical layer fails this lens. INSTEAD: the mechanical layer IS the discipline — without the harness running against every PR, the adopter-observable surface stays untested and the next #336-class regression ships silently.
+
+## How to apply
+
+When designing or reviewing a substrate change:
+
+1. **Identify every adopter-observable surface the change touches.** When the surface list is missing from the PR body, the change is not yet ready. INSTEAD of guessing: enumerate explicitly.
+2. **Ask "would an adopter's existing program break?"** INSTEAD of "should it" — would it. Think about every adopter shape: vendored snapshot, thin-pointer, cold-onboarding, partial-sync.
+3. **When the answer is yes, build the shim first.** Symlink, alias, forwarding stub, schema accommodation. Whatever makes the old name keep working.
+4. **Document the shim's retirement condition.** "When all known adopters migrate" or "after N release cycles." INSTEAD of "forever": match Linus's commitment to permanent code when the data demands it.
+5. **Test the shim against a real adopter.** The cold-adopter harness is the substrate's vehicle for this. INSTEAD of dev-machine validation: clone a representative adopter, run their sync hook, confirm zero observable change.
+6. **Ship the shim in the SAME release as the rename.** INSTEAD of "we'll add a shim later": same PR, same release; the gap between rename and shim is the breakage window.
+
+## How bassclef channels Linus
+
+The discipline lives in:
+
+- `.claude/rules/we-dont-break-adopters.md` — methodology layer; cites Hyrum's Law as the theoretical why and Linus's discipline as the operational answer
+- `architecture/decisions/ADR-031-non-breaking-changes-adopter-discipline.md` — decision layer; adopts the discipline as Tier 1
+- `architecture/dual-repo-flow.md` "Non-breaking changes to adopters" section — architectural layer
+- `scripts/migrate-adopter-references.sh` — adopter self-healing tool for the canonical → bassclef cascade
+- `presence/install/bassclef-sync.template.sh` — the sync surface that adopters depend on; load-bearing per this discipline
+- `scripts/cold-adopter-harness.sh` (bet 25e) + planned shape b sync round-trip (#341) — the real-adopter integration test surface
+- bassclef-upstream#1360 — Phase 2 mechanical layer (pre-rename CI test against representative adopter, redirect registry, versioned sync protocol)
+
+## Sources
+
+- LKML 2012-12-23 — "We do not break userspace" thread (Linus Torvalds, re: PowerPC syscall change)
+- *Linux Kernel Development* — Robert Love, Addison-Wesley (3rd ed. 2010)
+- *Stability of the Linux ABI* — Linux Foundation Technical Advisory Board (2014)
+- ELC 2015 — Greg Kroah-Hartman, "Driver ABI Stability"
+- LKML "regressions are bugs" thread — multiple instances 2008, 2011, 2014, 2017, 2021
+
+## Related luminaries
+
+- **Hyrum Wright** — provides the theoretical why (observability creates dependency); Linus provides the operational answer (we just keep userspace working). They pair as why + how.
+- **Michael Nygard** — stability patterns at runtime; ADR lifecycle for the breaking-change decision. Operates at runtime-failure layer where Linus operates at API-surface layer; complementary.
+- **Vaughn Vernon** — anticorruption layer is the structural pattern Linus's discipline produces in practice. When the substrate must do an internal rename, the anticorruption layer between substrate-internal and adopter-observable preserves stability.
+- **Frederick Brooks** — frames the conceptual-integrity-vs-migration-cost tradeoff. Linus picks adopter stability every time; Brooks gives the language to reason about when the tradeoff actually costs more than it saves.
+- **Kent Beck** — adjacent at the test-first layer. Linus's real-adopter integration test IS Beck's red-first discipline applied at the adopter boundary.
+
+## Refs
+
+- bassclef-upstream#1360 — Phase 2 mechanical layer
+- 2026-06-21 chronicle — the canonical → bassclef cascade + recovery + rule authoring
+- ADR-031 — non-breaking-change adopter discipline (decision layer)