@thebassclef/lite 1.0.3 → 1.1.0

package/dist/lite/.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/dist/lite/.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/dist/lite/.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.

package/dist/lite/.claude/luminaries/robert-c-martin.md

@@ -0,0 +1,164 @@
+---
+tier: lite
+name: Robert C. Martin (Uncle Bob)
+slug: robert-c-martin
+claimed_by: [architect, builder, reviewer]
+referenced_by_skills: [pattern-review, decompose, architect-review]
+primary_domain: engineering
+depth: full
+sources:
+  - type: book
+    title: "Clean Code: A Handbook of Agile Software Craftsmanship"
+    authors: ["Robert C. Martin"]
+    year: 2008
+    url: "https://www.pearson.com/en-us/subject-catalog/p/clean-code-a-handbook-of-agile-software-craftsmanship/P200000009044"
+    isbn: "9780132350884"
+    methodology_covered:
+      - "Functions should do one thing and do it well"
+      - "Meaningful names + small functions + no comments needed"
+      - "Code smells inventory + remediation patterns"
+      - "Boy Scout rule — leave the code cleaner than you found it"
+  - type: book
+    title: "Clean Architecture: A Craftsman's Guide to Software Structure and Design"
+    authors: ["Robert C. Martin"]
+    year: 2017
+    url: "https://www.pearson.com/en-us/subject-catalog/p/clean-architecture-a-craftsmans-guide-to-software-structure-and-design/P200000009454"
+    isbn: "9780134494166"
+    methodology_covered:
+      - "The Dependency Rule — source code dependencies always point inward"
+      - "Business rules never import frameworks, UI, or databases"
+      - "Boundaries between layers minimize ripple effects from external changes"
+  - type: book
+    title: "Agile Software Development: Principles, Patterns, and Practices"
+    authors: ["Robert C. Martin"]
+    year: 2002
+    url: "https://www.pearson.com/en-us/subject-catalog/p/agile-software-development-principles-patterns-and-practices/P200000009250"
+    isbn: "9780135974445"
+    methodology_covered:
+      - "SOLID principles — Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion"
+      - "Original codification of the SOLID acronym and each principle"
+  - type: book
+    title: "The Clean Coder: A Code of Conduct for Professional Programmers"
+    authors: ["Robert C. Martin"]
+    year: 2011
+    url: "https://www.pearson.com/en-us/subject-catalog/p/clean-coder-the-a-code-of-conduct-for-professional-programmers/P200000009422"
+    isbn: "9780137081073"
+    methodology_covered:
+      - "Professional discipline — saying no, estimating honestly, practicing"
+      - "Programming as profession with codes of conduct"
+verification_status: verified
+description: "\"Architecture is about intent, not frameworks."
+---
+
+# Robert C. Martin (Uncle Bob)
+
+## Signature
+
+*"Architecture is about intent, not frameworks. The only way to go fast is to go well."*
+
+Author of **Clean Code**, **Clean Architecture**, and **Clean Coder**.
+Coined SOLID. The bassclef voice on code quality as a continuous
+practice, not an end-of-project polish. We invoke Martin for SOLID,
+boundaries, testability, and functions that do one thing.
+
+## Core methods
+
+- **SOLID principles** — Single Responsibility, Open/Closed, Liskov
+  Substitution, Interface Segregation, Dependency Inversion. Five
+  rules for OO design that survive decades of reapplication.
+- **Clean Architecture / Dependency Rule** — Source-code dependencies
+  always point inward toward higher-level policy. Business rules don't
+  know about frameworks, UI, or databases. Frameworks are plugins.
+- **Boundaries as architecture** — Architecture's job is defining which
+  parts of the system are volatile and which are stable, and drawing
+  boundaries between them. Boundaries allow deferral of decisions.
+- **Functions do one thing** — Small, single-purpose functions with
+  descriptive names. Longest function should fit on a screen.
+- **Tests as first-class design constraint** — Code not written for
+  testability produces code that can't be tested. TDD is the practice
+  that enforces this discipline from the start.
+
+## When to channel this luminary
+
+When the primary risk is code entropy — the product works today but
+becomes unmaintainable tomorrow. Martin dominates for long-lived
+codebases, teams that rotate, and systems that will be extended over
+years. Pair with Fowler (refactoring, patterns) and Beck (TDD,
+XP practices) for the engineering-quality triad.
+
+Do NOT channel Martin for: throwaway prototypes, one-off scripts,
+pure research code where cleanup isn't the point.
+
+## Stack translation
+
+In Next.js + Prisma + TypeScript:
+
+- **Single Responsibility** → one component per concern; extract
+  `useXHook` when a component has multiple reasons to change.
+- **Open/Closed** → extend via props/config, not by modifying existing
+  components. Strategy pattern for varying behavior.
+- **Liskov** → interface contracts respected across implementations.
+  React component prop types that subtypes must honor.
+- **Interface Segregation** → component prop types that don't force
+  consumers to provide unneeded props. Split large prop types into
+  focused ones.
+- **Dependency Inversion** → depend on interfaces, not concrete
+  services. Facade pattern + interface → enables test stubs and
+  provider swaps (see `/decompose` Phase 1 Interface Registry).
+- **Clean Architecture** → business logic in `lib/services/`;
+  adapters in `lib/adapters/`; controllers in `app/api/` + `app/actions/`;
+  frameworks stay at the edges.
+
+## Anti-patterns it prevents
+
+- **God components** — one component doing validation + business logic
+  + DB call + side effects. Violates Single Responsibility.
+- **Framework coupling in business logic** — Prisma imports in
+  domain-logic files, React hooks in pure computation. Violates
+  Dependency Rule.
+- **Feature envy** — a class/component that reaches into another's
+  internals. Signal the responsibility is mis-assigned.
+- **Untested code** — if it's not covered, it's broken by default.
+  Covered code is the minimum bar.
+- **Clever code** — concise-but-unreadable constructs. Clean Code
+  requires clarity over brevity.
+
+## Worked example
+
+For POA's deal-scoring system:
+
+Martin's approach:
+- `ScoringService` (Pure Fabrication per GRASP + SRP per SOLID) —
+  orchestrates scoring, doesn't own score data
+- `IScoringStrategy` interface — Open/Closed: new scoring rules as
+  new classes, not edits to existing code
+- `WeightedScorer` / `BooleanScorer` / `MLScorer` — concrete strategies
+- `ScoringController` as a thin server action — no business logic,
+  just wires strategy + service + response
+- All of the above: unit tested. The service mocks the strategy; the
+  strategy is tested in isolation; the controller is tested with
+  service stub.
+
+What Martin would NOT produce: a 400-line server action that directly
+queries Prisma, applies scoring math inline, sends notifications, and
+logs telemetry. That's every SOLID principle violated in one route.
+
+## Sources
+
+- *Clean Code* — Martin, Prentice Hall (2008)
+- *Clean Architecture* — Martin, Prentice Hall (2017)
+- *The Clean Coder* — Martin (2011)
+- *Agile Software Development: Principles, Patterns, and Practices* — Martin (2002)
+- cleancoders.com — video series
+- blog.cleancoder.com
+
+## Related luminaries
+
+- **Martin Fowler** — Shared rigor; Fowler provides patterns + refactoring,
+  Martin provides principles. Pair always.
+- **Kent Beck** — TDD discipline Martin endorses; Beck operational,
+  Martin principles.
+- **Alistair Cockburn** — Hexagonal Architecture is a specific
+  implementation of Clean Architecture's boundary rule.
+- **Gang of Four** — Martin recommends GoF patterns as implementation
+  vocabulary for SOLID principles.