@thebassclef/lite 0.0.1 → 0.1.2

package/substrate/.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)

package/substrate/.claude/luminaries/martin-fowler.md

@@ -0,0 +1,164 @@
+---
+tier: lite
+name: Martin Fowler
+slug: martin-fowler
+claimed_by: [builder, reviewer]
+referenced_by_skills: [pattern-review, decompose, architect-review]
+primary_domain: engineering
+depth: full
+sources:
+  - type: book
+    title: "Refactoring: Improving the Design of Existing Code (2nd edition)"
+    authors: ["Martin Fowler"]
+    year: 2018
+    url: "https://martinfowler.com/books/refactoring.html"
+    isbn: "9780134757599"
+    methodology_covered:
+      - "Refactoring catalog with named transformations"
+      - "When a change is hard, first refactor to make the change easy — then make the easy change"
+      - "Code smells: Long Method, Feature Envy, Shotgun Surgery, Primitive Obsession, Data Clumps"
+  - type: book
+    title: "Patterns of Enterprise Application Architecture"
+    authors: ["Martin Fowler"]
+    year: 2002
+    url: "https://martinfowler.com/books/eaa.html"
+    isbn: "9780321127426"
+    methodology_covered:
+      - "Repository pattern — domain object persistence behind a collection-like interface"
+      - "Service Layer — defines an application's boundary and its set of available operations"
+      - "Domain Model + Active Record + Data Mapper — three approaches to domain logic and data access"
+      - "Unit of Work — maintain a list of objects affected by a business transaction"
+  - type: book
+    title: "Domain-Specific Languages"
+    authors: ["Martin Fowler", "Rebecca Parsons"]
+    year: 2010
+    url: "https://martinfowler.com/books/dsl.html"
+    isbn: "9780321712943"
+    methodology_covered:
+      - "Internal vs external DSL design choices"
+      - "DSL design patterns — when to build, when to embed, when to skip"
+  - type: blog_post
+    title: "martinfowler.com (primary methodology venue)"
+    authors: ["Martin Fowler"]
+    year: 2025
+    url: "https://martinfowler.com/"
+    methodology_covered:
+      - "Continuous refactoring as engineering discipline, not a scheduled event"
+      - "Microservices framing + architectural design notes"
+      - "Patterns evolve through the blog before landing in books"
+verification_status: verified
+description: "\"Any fool can write code that a computer can understand."
+---
+
+# Martin Fowler
+
+## Signature
+
+*"Any fool can write code that a computer can understand. Good programmers write code that humans can understand. Is the code in the right place?"*
+
+ThoughtWorks Chief Scientist. Author of **Refactoring**, **Patterns of
+Enterprise Application Architecture**, **Domain-Specific Languages**,
+and countless seminal essays. The bassclef voice on code smells,
+refactoring, and enterprise patterns.
+
+## Core methods
+
+- **Code smells catalog** — Long Method, Large Class, Feature Envy,
+  Shotgun Surgery, Primitive Obsession, Data Clumps, and dozens more.
+  Named patterns make smells recognizable on sight.
+- **Refactoring catalog** — Extract Method, Move Method, Replace
+  Conditional with Polymorphism, Introduce Parameter Object, and ~70
+  others. Each is a mechanical transformation that preserves behavior.
+- **Enterprise patterns (PoEAA)** — Repository, Unit of Work, Service
+  Layer, Domain Model, Table Data Gateway, Data Mapper. Vocabulary for
+  how business logic meets persistence.
+- **Strangler Fig pattern** — migrate legacy by routing calls through
+  a new layer while old shrinks. Reversible at every step.
+- **Expand-and-contract schema migrations** — add new column → backfill
+  → switch reads → remove old column. Zero-downtime migration pattern.
+
+## When to channel this luminary
+
+When the primary risk is that existing code will become unworkable
+under change. Fowler dominates for refactoring work, legacy migration,
+pattern selection in Construction, and code review. Pair with Uncle Bob
+(SOLID principles), Beck (TDD), and Feathers (legacy code) for the
+engineering quality stack.
+
+Do NOT channel Fowler as primary for: greenfield architecture (use
+Simon Brown or Evans), pure language design, or brand-new frameworks
+where patterns haven't settled.
+
+## Stack translation
+
+In Next.js + Prisma + TypeScript:
+
+- **Repository pattern** → `lib/repositories/deal.ts` wraps Prisma
+  queries; routes and services call the repository, not Prisma
+  directly. Decouples storage from business logic.
+- **Service Layer** → `lib/services/ScoringService.ts` orchestrates
+  multiple repositories + policies for a single business operation.
+- **Refactoring before feature** — when a change is hard, first refactor
+  to make the change easy, then make the easy change.
+- **Strangler Fig** → route old API calls through a facade that
+  progressively delegates to new implementation; remove old route
+  only when all traffic has shifted.
+- **Expand-and-contract migrations** → Prisma migrations add nullable
+  column first, backfill via job, then add NOT NULL constraint, then
+  remove old column in subsequent migration.
+
+## Anti-patterns it prevents
+
+- **Shotgun Surgery** — one logical change touches many unrelated files.
+  Signal that abstraction is missing; responsibility is smeared.
+- **Feature Envy** — a method/component uses more of another's data
+  than its own. The logic belongs there, not here.
+- **Primitive Obsession** — using primitive types (string, number) when
+  a domain concept (DealId, Money, EmailAddress) would clarify intent.
+- **Long Parameter List** — functions with 6+ params. Extract Parameter
+  Object.
+- **Data Clumps** — the same group of fields appearing together across
+  many places. Extract a class/type for the clump.
+- **Inappropriate Intimacy** — class A peering into class B's privates.
+  Violates encapsulation; signals poor boundary placement.
+
+## Worked example
+
+For POA's deal-enrichment pipeline:
+
+Fowler's approach:
+- Identify **code smells** in current implementation: `enrichmentService.ts`
+  has 300 lines (Large Class), nested callbacks (Complex Method), and
+  direct Prisma + vendor-API calls (Feature Envy + Inappropriate Intimacy).
+- Apply **Extract Class**: split into `EnrichmentOrchestrator`,
+  `EnrichmentRepository`, and `EnrichmentVendorAdapter`.
+- Apply **Replace Conditional with Polymorphism**: if-else over enrichment
+  provider types becomes a Strategy with `IEnrichmentProvider` interface.
+- Apply **Repository pattern** to the Prisma access.
+- **Strangler Fig** the migration: new code runs behind feature flag,
+  old code runs in parallel with comparison logging, switch cutover
+  once comparison shows parity.
+
+What Fowler would NOT produce: a rewrite from scratch. Fowler's
+discipline is incremental, behavior-preserving refactoring — not
+greenfield redos.
+
+## Sources
+
+- *Refactoring: Improving the Design of Existing Code* — Fowler,
+  Addison-Wesley (2nd ed 2018)
+- *Patterns of Enterprise Application Architecture* — Fowler (2002)
+- *Domain-Specific Languages* — Fowler (2010)
+- *NoSQL Distilled* — Fowler, Sadalage (2012)
+- martinfowler.com — primary site with decades of essays, bliki entries
+
+## Related luminaries
+
+- **Robert C. Martin** — SOLID + Clean Code; pair with Fowler's refactoring
+  catalog for complete engineering-quality practice.
+- **Kent Beck** — TDD + Extreme Programming; Fowler credits Beck for
+  much of the refactoring discipline.
+- **Michael Feathers** — Working with Legacy Code extends Fowler's
+  refactoring to the before-state (no tests exist yet).
+- **Eric Evans** — DDD complements Fowler's Service Layer + Repository
+  at the strategic domain-modeling level.

package/substrate/.claude/luminaries/michael-feathers.md

@@ -0,0 +1,125 @@
+---
+tier: lite
+name: Michael Feathers
+slug: michael-feathers
+claimed_by: [builder, reviewer]
+referenced_by_skills: [verify, pattern-review]
+primary_domain: engineering
+depth: full
+solves_problems_brownfield:
+  - "Codebase has no tests; any change risks unknown breakage across the system"
+  - "A class or function can't be tested without instantiating half the application"
+  - "New behavior needs to be added adjacent to legacy code that can't be safely changed"
+  - "A module is deeply coupled to its dependencies (database, filesystem, clock); tests require real infrastructure"
+solves_problems_greenfield:
+  - "Designing a new module that will be introduced to a legacy system; seams must be planned from the start"
+  - "Building a service layer that wraps a third-party system; the wrap method must stay testable as the third-party evolves"
+  - "Planning a brownfield rescue effort; need a staged safety-net strategy before any refactoring begins"
+  - "Establishing the testing discipline a team will use as a system ages"
+anti_patterns:
+  - "Greenfield systems with modern tooling and existing test culture — Feathers is the brownfield specialist"
+  - "Systems where a full rewrite is genuinely the right call and incremental safety-net building would slow the work"
+  - "Pure architectural redesigns where the code isn't the constraint"
+sources:
+  - type: book
+    title: "Working Effectively with Legacy Code"
+    authors: ["Michael C. Feathers"]
+    year: 2004
+    url: "https://www.amazon.com/Working-Effectively-Legacy-Michael-Feathers/dp/0131177052"
+    isbn: "9780131177055"
+    methodology_covered:
+      - "Characterization tests — pin current behavior before touching legacy code"
+      - "Seam identification — find places where behavior can change without editing in place (preprocessor, link, object seams)"
+      - "Sprout method / sprout class — add new testable behavior adjacent to legacy code"
+      - "Wrap method / wrap class — change behavior by wrapping; original is untouched"
+      - "Legacy code definition — code without tests"
+  - type: website
+    title: "Michael Feathers blog"
+    authors: ["Michael Feathers"]
+    year: 2008
+    url: "https://michaelfeathers.silvrback.com/"
+    methodology_covered:
+      - "Ongoing writing on software design, legacy systems, and refactoring discipline"
+verification_status: verified
+description: "\"Legacy code is code without tests. Everything else is detail.\" [ref:1]"
+---
+
+# Michael Feathers
+
+## Signature
+
+*"Legacy code is code without tests. Everything else is detail."* [ref:1]
+
+Author of **Working Effectively with Legacy Code** (2004) [ref:1]. The bassclef voice on bringing old, test-less, or tightly-coupled code under control without a rewrite. Where Beck starts with TDD on a clean slate, Feathers starts with the code that actually exists in production today.
+
+## Core methods
+
+- **Characterization tests** — Write tests that describe what the code currently does, not what it should do. Before touching anything, pin the current behavior. These tests are the safety net that makes refactoring safe. Only after pinning do you change behavior — and changing behavior means writing a failing test first. [ref:1]
+- **Seam identification** — A seam is a place where you can change the program's behavior without editing in place. Seams come in three types: preprocessor seams (build-time), link seams (object-file substitution), and object seams (subclassing or interface injection). Finding seams is finding where you can insert a test double without rewriting the production code. [ref:1]
+- **Sprout method / sprout class** — When you need to add new behavior to a function that is too risky to touch, add the new behavior in a new method or class that you CAN test. Wire the new code into the legacy code with minimal contact. The sprout is independently testable; the legacy code is preserved. [ref:1]
+- **Wrap method / wrap class** — When you need to change a method's behavior, wrap it: create a new method (or class) that calls the original and adds or modifies behavior around it. The wrap is testable; the original is untouched. Like Decorator, but driven by safety rather than design. [ref:1]
+
+## When to channel this luminary
+
+When the codebase has real production code that lacks tests, or where tests exist but the dependencies are so tangled that changing anything is risky. Feathers dominates legacy system rescue: adding a feature to a 10-year-old module, extracting a service from a monolith, or incrementally stabilizing a system before a modernization effort begins. Pair with Fowler (refactoring catalog) once the safety net is in place.
+
+INSTEAD of channeling Feathers when the team is starting fresh: use Beck's TDD from the first line of production code. Feathers handles the before-state that TDD assumes away.
+
+## Stack translation
+
+In Next.js + Prisma + TypeScript:
+
+- **Characterization tests** — for a legacy API route, write integration tests against its actual behavior (inputs, outputs, side effects) before touching it. Use vitest + supertest or a test client. Pin the response shapes that downstream code depends on.
+- **Seam identification** — TypeScript interfaces are the primary seam type. A service function that imports Prisma directly has no seam; extract an interface and inject via constructor or parameter. The seam enables swapping a real DB client for a test double.
+- **Sprout method** — a 200-line server action that handles validation + database + notification: sprout the new validation logic into a standalone function tested in isolation. Wire it into the existing action with a single call. Ship both together.
+- **Wrap class** — a third-party SDK (BizBuySell, an email provider) with no seam: create a thin wrapper class that implements your own interface and delegates to the SDK. Tests use a test double; production uses the wrapper. Swap SDKs later without touching callers.
+
+## Anti-patterns it prevents
+
+- **Edit and pray** — making a change to legacy code without tests and hoping nothing breaks. Feathers's characterization tests create the safety net before any edit, making each change verifiable rather than hopeful.
+- **The big refactor** — attempting to redesign a legacy system comprehensively before adding tests. Feathers insists: tests come first, then refactoring. The comprehensive redesign without tests is just a different legacy system that happens to be new. [ref:1]
+- **Dependency grabbing** — adding a new dependency to a legacy class because it was "easier." Each new dependency reduces the seam surface and makes future testing harder. Feathers's discipline: find the seam, inject the dependency, preserve optionality.
+- **Sprout regression** — the new behavior works; the old behavior was accidentally changed. Characterization tests catch this: the old behavior is pinned; if any characterization test fails, something changed that was not intended to change.
+
+## Worked example
+
+For POA's legacy BizBuySell scraper module:
+
+The scraper function is 300 lines; it fetches, parses, writes to the database, and sends a Slack notification. No tests. Before any change:
+
+1. **Characterization test**: run the scraper against a recorded HTTP fixture; capture the database rows it writes and the Slack payload it sends. These are the characterization tests. Any change that alters these outputs is a signal, not a surprise.
+
+2. **Seam identification**: the database write is not injectable — it calls Prisma directly. INSTEAD: extract a `ScrapeResultWriter` interface; pass it as a parameter in tests. The seam now exists.
+
+3. **Sprout method**: the new requirement is deduplication before writing. INSTEAD of editing the 300-line function: sprout `deduplicateResults(incoming: ScrapeResult[], existing: ScrapeResult[]): ScrapeResult[]` — pure function, fully testable. Wire it into the legacy function with one line.
+
+4. **Verify**: characterization tests still pass (old behavior preserved). New unit tests cover the deduplication logic independently.
+
+## Sources
+
+- *Working Effectively with Legacy Code* — Feathers, Prentice Hall (2004) [ref:1]
+- michaelfeathers.silvrback.com — primary blog [ref:2]
+- "Getting Empirical About Refactoring" — Feathers, various conference talks
+
+## Related luminaries
+
+- **Martin Fowler** — Refactoring is the next step after Feathers's safety net is in place; Fowler's catalog assumes tests exist, Feathers builds the before-state.
+- **Kent Beck** — TDD is the end state Feathers helps teams reach incrementally.
+- **Robert C. Martin** — Clean Code principles are the target; Feathers handles the path from legacy reality to that target.
+- **Hunt & Thomas** — DRY and orthogonality are easier to maintain from the start; Feathers is the recovery discipline when they were not.
+
+## Substrate-as-system anchor (bassclef bet 27c, 2026-06-27)
+
+Feathers's "code without characterization tests is legacy code by definition" became the anchor citation for the bassclef substrate-as-system tenet (ADR-035). The bet 24c architect-review (2026-06-24) anchored on comprehension-side lenses (Brooks + Linus + Ishikawa + Deming) and missed the mechanism-fidelity class — "rule names mechanical enforcement that does not actually fire." The recursive Act phase (`architecture/audits/2026-06-27-audit-method-blind-spot.md`) named the lens-gap; Feathers's verification-side framing supplied the cure.
+
+The bet 27c foundation ships:
+- `standards/mechanism-fidelity.md` (standard tier) — audit method spec; Feathers-style characterization tests pin every rule's mechanism claim
+- `lib/mechanism-fidelity.sh` — shared scanner that runs the 5-step verification chain
+- `.claude/skills/audit-rule-mechanism-fidelity/SKILL.md` — operator-invocable audit (Feathers + Beck primary luminaries)
+- `scripts/cold-adopter-harness-sync.sh` Shape d — per-PR gate (4 check classes; Feathers + Saltzer-Schroeder + Ousterhout primary)
+- `.claude/rules/substrate-as-system.md` (standard tier) — auto-loaded tenet rule (cites Feathers as primary)
+- `.claude/skills/architect-review/SKILL.md` — amendment makes Feathers + Beck + Saltzer-Schroeder verification-side primaries alongside Brooks + Linus comprehension-side primaries
+
+Feathers's brownfield-rescue framing applies recursively at the substrate level: bassclef's own substrate had legacy mechanism-fidelity claims (108 claims classified by WU-6 first audit; 76 non-CLEAN). The cure bet (Bet C-pre-2) drives them to zero via the same Feathers discipline — characterization tests, seam identification, sprout/wrap patterns — applied to substrate hooks rather than application code.
+
+The substrate as a system needs Feathers as much as application code does. This anchor citation reflects that.

package/substrate/.claude/luminaries/michael-nygard.md

@@ -0,0 +1,118 @@
+---
+tier: lite
+name: Michael Nygard
+slug: michael-nygard
+claimed_by: [architect]
+referenced_by_skills: [architect-review, decompose]
+primary_domain: architecture
+depth: full
+solves_problems_brownfield:
+  - "A single slow external API call hangs the entire application because the thread pool exhausts"
+  - "One failing service causes a cascade that takes down services with no direct dependency on it"
+  - "The application works fine locally and in staging but fails in production under real load patterns"
+  - "There is no defined behavior when an external integration is unavailable"
+solves_problems_greenfield:
+  - "Designing a service that will integrate with external systems of unknown reliability"
+  - "Planning the failure modes of a distributed system before any code is written"
+  - "Building a system that continues operating (in degraded mode) when individual integrations fail"
+  - "Establishing the production-readiness criteria a system must meet before going live"
+anti_patterns:
+  - "Single-process applications with no external integrations — stability patterns add overhead without value"
+  - "Batch systems that run to completion and exit — patterns designed for long-lived services"
+  - "Early-stage prototypes where production reliability is deliberately out of scope"
+sources:
+  - type: book
+    title: "Release It! Design and Deploy Production-Ready Software"
+    authors: ["Michael T. Nygard"]
+    year: 2018
+    url: "https://pragprog.com/titles/mnee2/release-it-second-edition/"
+    isbn: "9781680502398"
+    methodology_covered:
+      - "Circuit breaker — stateful wrapper with Closed/Open/Half-Open states; prevents cascading failure"
+      - "Bulkhead — partition resources by concern; failure in one partition cannot exhaust shared resources"
+      - "Timeout — every remote call must have connect + read timeout values"
+      - "Fail fast — reject requests immediately when a known failure condition exists"
+      - "Stability anti-patterns — cascading failure, blocked threads, self-denial, integration point failures"
+  - type: book
+    title: "Release It! Design and Deploy Production-Ready Software (1st edition)"
+    authors: ["Michael T. Nygard"]
+    year: 2007
+    url: "https://pragprog.com/titles/mnee/release-it/"
+    methodology_covered:
+      - "Original stability patterns catalog"
+  - type: blog_post
+    title: "Documenting Architecture Decisions"
+    authors: ["Michael Nygard"]
+    year: 2011
+    url: "https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions"
+    methodology_covered:
+      - "ADR (Architecture Decision Record) format — Title, Status, Context, Decision, Consequences"
+      - "Originated the ADR format; widely adopted across software organizations"
+verification_status: verified
+description: "\"Everything fails. Every remote call can hang. Every integration point is a liability. Design your system to be stable in the presence of failure, not to assume failure away.\"…"
+---
+
+# Michael Nygard
+
+## Signature
+
+*"Everything fails. Every remote call can hang. Every integration point is a liability. Design your system to be stable in the presence of failure, not to assume failure away."* [ref:1]
+
+Author of **Release It! Design and Deploy Production-Ready Software** (2nd ed 2018) [ref:1]. Coined the ADR (Architecture Decision Record) format in his 2011 blog post [ref:3]. The bassclef voice on production-grade software: the stability patterns that prevent cascading failures and the anti-patterns that cause them.
+
+## Core methods
+
+- **Circuit breaker** — A stateful wrapper around an integration point (external API, database, downstream service). Three states: Closed (normal operation), Open (fast-fail all calls without attempting contact), Half-Open (probe with one call to test recovery). When the failure rate exceeds a threshold, the circuit opens. Callers fail fast rather than hanging. After a timeout, one call is allowed through; if it succeeds, the circuit closes. [ref:1]
+- **Bulkhead** — Partition resources by concern so that failure in one partition cannot exhaust resources needed by another. Named after the ship bulkhead that prevents water ingress in one compartment from sinking the ship. In software: separate thread pools for different integrations, separate connection pools for different databases, separate queue workers for different job types. [ref:1]
+- **Timeout** — Every remote call must have a timeout. A call with no timeout can block a thread indefinitely. Two values needed: connect timeout (how long to wait for connection), read timeout (how long to wait for response). Timeouts must be tuned: too short creates unnecessary failures; too long creates unacceptable UX. [ref:1]
+- **Fail fast** — When a system knows it cannot fulfill a request (circuit open, connection pool exhausted, downstream service unavailable), it should fail immediately with a clear error rather than accepting the request and failing slowly. Fail fast enables callers to retry or redirect; slow failure degrades the entire system. [ref:1]
+
+## When to channel this luminary
+
+When the system will integrate with any external dependency (databases, third-party APIs, downstream services, message queues) and failure modes of those integrations need explicit design. Nygard dominates production readiness reviews, architecture reviews before launch, and any system that must remain partially operational when integrations fail. Pair with Newman (service decomposition that creates the integration boundaries Nygard's patterns protect), Hohpe (integration patterns at the messaging layer), and Brown (ADRs for recording stability-pattern decisions).
+
+INSTEAD of channeling Nygard for internal application logic: stability patterns are for integration points and external boundaries. Business logic, UI composition, and domain modeling are governed by Evans, Cockburn, and Cooper. Nygard's scope is the edges where your system meets systems you cannot control.
+
+## Stack translation
+
+In Next.js + Prisma + external APIs (BizBuySell, Anthropic, email providers):
+
+- **Circuit breaker** — wrap each external API client (BizBuySell scraper, Anthropic enrichment, email delivery) in a circuit breaker. When the API is unavailable or slow, the circuit opens; callers receive a fast failure and can queue the work for retry. Libraries: `opossum` (Node.js) or a simple state machine per integration.
+- **Bulkhead** — BullMQ workers for enrichment, for email, and for scraping use separate queues with separate concurrency limits. A spike in enrichment work cannot starve the email workers.
+- **Timeout** — every `fetch()` call to an external API uses `AbortSignal.timeout()`. Anthropic API calls that exceed 30s abort; enrichment jobs that exceed 60s fail and are retried. Prisma connection pool has an explicit pool timeout.
+- **Fail fast** — server actions that depend on an unavailable service return a clear `503` rather than hanging. The UI shows a retry state rather than a spinner.
+- **ADRs** — every stability-pattern decision is recorded in `architecture/decisions/`: "ADR-009: circuit breaker for BizBuySell API — context, decision, consequences." [ref:3]
+
+## Anti-patterns it prevents
+
+- **Cascading failure** — a slow external API causes thread pool exhaustion, which causes queue buildup, which causes memory pressure, which causes the entire application to fail. Circuit breaker and bulkhead prevent this: failures stay contained within their integration boundary. [ref:1]
+- **Blocked threads** — a database query or HTTP call with no timeout holds a thread indefinitely. Ten such calls block ten threads. The system accepts new requests it cannot service.
+  INSTEAD: set connect + read timeouts on every remote call; set a maximum wait in every queue consumer. Threads that time out release and become available for other work.
+- **Self-denial** — the application triggers its own overload: a scheduled job fans out thousands of API calls simultaneously, the API rate-limits, all calls fail, the job retries them immediately, the rate-limit worsens. Circuit breaker + exponential backoff prevent the retry cascade. [ref:1]
+- **Test harness gap** — the system was tested with a fast, reliable test double for every integration; production uses real integrations that are sometimes slow or unavailable. The failure paths were tested with mocks that never fail.
+  INSTEAD: include chaos tests (slow responses, connection drops, partial failures) in the integration test suite. The failure behavior must be verified, not assumed.
+
+## Worked example
+
+For POA's BizBuySell scraper integration:
+
+**The failure mode without patterns**: BizBuySell returns 503 for 5-10 minutes. The scraper worker holds ten open HTTP connections waiting for responses that will not arrive; the BullMQ queue backs up; the worker crashes; manual intervention is required.
+
+**With stability patterns**:
+1. **Timeout**: every BizBuySell fetch has a 10-second timeout. After 10 seconds, the call fails with a timeout error.
+2. **Circuit breaker**: after five consecutive timeouts within 60 seconds, the circuit opens. All subsequent scrape attempts fail fast. The circuit enters Half-Open after 60 seconds and allows one probe call through.
+3. **Bulkhead**: the scraper uses a separate BullMQ queue (max 5 concurrent workers) from the enrichment queue (max 10 workers). A BizBuySell outage fills the scraper queue but cannot starve enrichment workers.
+4. **ADR**: "ADR-010: BizBuySell API stability patterns — context: BizBuySell has 99.5% SLA (~43 hours downtime/year). We need scraping to be non-blocking during outages. Decision: circuit breaker with 5-failure threshold, 60s recovery. Consequences: scrape jobs may lag 60s during recovery; acceptable given the non-real-time nature of scrape data."
+
+## Sources
+
+- *Release It! Design and Deploy Production-Ready Software* — Nygard, Pragmatic Bookshelf (1st ed 2007, 2nd ed 2018) [ref:1][ref:2]
+- "Documenting Architecture Decisions" — Nygard, cognitect.com blog (2011) — original ADR proposal [ref:3]
+- thinkrelevance.com / cognitect.com — Nygard's primary writing venues (thinkrelevance.com was the predecessor domain to cognitect.com)
+
+## Related luminaries
+
+- **Sam Newman** — Microservices create the service boundaries where Nygard's stability patterns apply. Newman decomposes; Nygard hardens the resulting integration points.
+- **Gregor Hohpe** — EIP messaging patterns operate at the same integration boundaries. Hohpe's dead letter channels and Nygard's circuit breakers are complementary: messaging + stability.
+- **Simon Brown** — ADR format (Nygard's invention) is central to Brown's architecture communication approach. C4 documents the structure; ADRs record the stability decisions.
+- **Alistair Cockburn** — Hexagonal architecture creates explicit integration ports; Nygard's stability patterns wrap those ports.