@thebassclef/lite 0.0.1 → 0.1.0

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