@thebassclef/lite 0.1.2 → 1.0.0

package/substrate/.claude/luminaries/gang-of-four.md

@@ -1,157 +0,0 @@
----
-tier: lite
-name: Gang of Four (Gamma, Helm, Johnson, Vlissides)
-slug: gang-of-four
-claimed_by: [builder]
-referenced_by_skills: [pattern-review, decompose, architect-review]
-primary_domain: engineering
-depth: full
-sources:
-  - type: book
-    title: "Design Patterns: Elements of Reusable Object-Oriented Software"
-    authors: ["Erich Gamma", "Richard Helm", "Ralph Johnson", "John Vlissides"]
-    year: 1994
-    url: "https://www.pearson.com/en-us/subject-catalog/p/design-patterns-elements-of-reusable-object-oriented-software/P200000009480"
-    isbn: "9780201633610"
-    methodology_covered:
-      - "23 named patterns across Creational, Structural, Behavioral categories"
-      - "Program to an interface, not an implementation"
-      - "Favor object composition over class inheritance"
-      - "Decorator for cross-cutting concerns; Strategy for algorithm variation; Observer for event propagation"
-      - "Pattern language as shared vocabulary for design discussion"
-verification_status: verified
-description: "\"Program to an interface, not an implementation."
----
-
-# Gang of Four (GoF)
-
-## Signature
-
-*"Program to an interface, not an implementation. Favor object composition over class inheritance."*
-
-Authors of **Design Patterns: Elements of Reusable Object-Oriented
-Software** (1994). The bassclef reference for 23 named OO patterns
-across three categories (Creational, Structural, Behavioral). The
-book every serious engineer has read; the patterns every codebase
-implements, named or not.
-
-## Core methods
-
-### Creational patterns (how objects are made)
-- **Factory Method** — defer instantiation to subclasses
-- **Abstract Factory** — families of related objects
-- **Builder** — step-by-step complex construction
-- **Prototype** — clone existing instances
-- **Singleton** — one shared instance (use sparingly)
-
-### Structural patterns (how objects compose)
-- **Adapter** — translate one interface to another
-- **Bridge** — decouple abstraction from implementation
-- **Composite** — tree structures of uniform objects
-- **Decorator** — add behavior without subclassing (critical for
-  cross-cutting concerns — see `/decompose` Phase 3)
-- **Facade** — simplified interface to subsystem
-- **Flyweight** — share state for many small objects
-- **Proxy** — placeholder controlling access
-
-### Behavioral patterns (how objects collaborate)
-- **Chain of Responsibility** — pass request through handlers
-- **Command** — encapsulate request as object
-- **Interpreter** — language grammar evaluation
-- **Iterator** — sequential access without exposing structure
-- **Mediator** — reduce inter-object coupling
-- **Memento** — capture and restore state
-- **Observer** — notify dependents of state change
-- **State** — behavior varies by internal state
-- **Strategy** — algorithm varies at runtime
-- **Template Method** — skeleton with overridable steps
-- **Visitor** — operations over object structure
-
-## When to channel this luminary
-
-When the primary risk is reinventing solved structural problems badly.
-GoF dominates for Construction pattern selection, code review, and
-decomposition work. Pair with Fowler (enterprise patterns extend GoF),
-Uncle Bob (SOLID shapes how patterns apply), and Cockburn (Hexagonal
-Architecture places patterns in structural context).
-
-Do NOT channel GoF for: trivial code where no pattern applies,
-greenfield work where you should first ask whether the problem is
-really structural, or to justify over-engineering.
-
-## Stack translation
-
-In Next.js + React + TypeScript:
-
-- **Facade** → server actions composing multiple services for a single
-  operation (`app/actions/create-deal.ts`).
-- **Adapter** → `lib/adapters/[vendor].ts` wraps external APIs with
-  consistent interface.
-- **Strategy** → `IScoringStrategy` with multiple implementations;
-  registry selects at runtime.
-- **Decorator** → `ObservedImputer` wraps `IAssociationImputer` for
-  tracing; `CachedRepository` wraps `IRepository` for caching. THE
-  pattern for cross-cutting concerns per `/decompose` Phase 3.
-- **Observer** → React context + useEffect for subscription; Prisma
-  middleware for data-change events.
-- **Factory** → `createClient()` functions that return configured instances.
-- **State** → XState machines for complex UI state (deal-stage wizard).
-- **Template Method** → base classes with abstract steps (rare in
-  modern React; prefer composition).
-- **Proxy** → Next.js middleware for auth; SWR for cached API access.
-
-## Anti-patterns it prevents
-
-- **Pattern invention** — creating novel structural solutions to solved
-  problems. Results are always worse than the pattern.
-- **Pattern without need** — using Observer where a simple callback
-  works; Strategy where an if-statement works. Pattern overhead without
-  variation pressure.
-- **Mis-fit pattern** — applying a pattern whose preconditions don't
-  hold. Factory for simple `new` calls. Decorator for behavior that's
-  intrinsic (not cross-cutting).
-- **Pattern stacking** — using five patterns where two would suffice.
-  Each pattern has cognitive cost.
-- **Inheritance as default structural tool** — GoF's opening principle
-  is "favor composition over inheritance." Deep inheritance hierarchies
-  are usually wrong.
-
-## Worked example
-
-For POA's email-imputation facade (per `/decompose` Phase 3):
-
-GoF pattern selection:
-- **Facade**: `AssociationImputer` exposes simple interface, hides
-  LLM provider complexity
-- **Strategy**: Different providers (Haiku, Gemma) as interchangeable
-  implementations of `IAssociationImputer`
-- **Adapter**: `AnthropicAdapter`, `GeminiAdapter` wrap vendor SDKs
-  behind common interface
-- **Decorator**: `ObservedImputer` wraps any imputer with Langfuse
-  tracing — cross-cutting observability
-- **Proxy**: `CachedImputer` wraps any imputer with recent-result
-  caching — cross-cutting performance
-- **Chain of Responsibility** (future): multiple imputers in fallback
-  chain — Haiku first, Gemma on low confidence, human review on very
-  low confidence
-
-What GoF would NOT produce: one concrete `HaikuImputer` class with
-observability, caching, error handling, and provider logic all
-intertwined. That's the anti-pattern `/decompose` evolution was
-built to prevent.
-
-## Sources
-
-- *Design Patterns: Elements of Reusable Object-Oriented Software* —
-  Gamma, Helm, Johnson, Vlissides, Addison-Wesley (1994)
-- No primary website (the book is the source)
-
-## Related luminaries
-
-- **Robert C. Martin** — SOLID principles guide pattern application.
-- **Martin Fowler** — PoEAA extends GoF patterns to enterprise context.
-- **Erich Gamma** individually — co-author, later led VS Code.
-- **Christopher Alexander** — "A Pattern Language" (architecture, 1977)
-  inspired the software pattern movement.
-- **Head First Design Patterns** (Freeman, Robson) — accessible entry
-  to GoF for learners.

package/substrate/.claude/luminaries/glenford-myers.md

@@ -1,230 +0,0 @@
----
-tier: lite
-name: Glenford J. Myers
-slug: glenford-myers
-claimed_by: [reviewer, builder]
-referenced_by_skills: [verify, pattern-review]
-primary_domain: testing
-depth: full
-sources:
-  - type: book
-    title: "The Art of Software Testing"
-    authors: ["Glenford J. Myers"]
-    year: 1979
-    edition: "1st (3rd ed 2011 with Sandler & Badgett)"
-    isbn: "9780471043287"
-    methodology_covered:
-      - "Decision coverage — every branch (if/else) is exercised by at least one test"
-      - "Condition coverage — every boolean sub-expression is independently exercised true and false"
-      - "Boundary value analysis — tests target the edges of input domains (min, max, off-by-one)"
-      - "Equivalence partitioning — divide input space into classes where one representative tests the whole class"
-      - "Error guessing — heuristic enumeration of likely failure modes"
-  - type: book
-    title: "Reliable Software through Composite Design"
-    authors: ["Glenford J. Myers"]
-    year: 1975
-    methodology_covered:
-      - "Cohesion / coupling — module-design quality metrics that pre-date Constantine + Yourdon's structured-design framing"
-verification_status: verified
-description: "\"The purpose of testing is to find errors, not to demonstrate the absence of errors.\""
----
-
-# Glenford J. Myers
-
-## Signature
-
-*"The purpose of testing is to find errors, not to demonstrate the absence of errors."*
-
-IBM systems researcher (1960s-80s). Author of **The Art of Software Testing** (1979) — the foundational text that named decision coverage, condition coverage, boundary value analysis, and equivalence partitioning as systematic disciplines. Pairs with Beck (TDD cycle), Hoare (contract testing), and Ousterhout (design judgment): Beck owns the rhythm, Hoare owns the contract semantics, Ousterhout owns the shape, Myers owns the taxonomy of what-to-cover.
-
-## Core methods
-
-- **Decision coverage** — Every branch in the source has at least one test that exercises it. A function with three if/else paths needs at least three tests. The discipline maps directly to grep-count: count branches in source; count test cases; the second number is at least the first.
-
-  INSTEAD of one test that "covers the happy path": one test per branch. The cost is small at write-time and compounds as the source grows.
-
-- **Condition coverage** — Every boolean sub-expression in a compound condition is independently exercised true AND false. A condition `(a && b) || c` has three sub-expressions; sufficient coverage exercises each one in both states. Decision coverage alone misses this: `(a && b)` can be false because `a` is false OR because `b` is false; the two cases hit different bugs.
-
-  INSTEAD of one true/false pair per compound condition: one true/false pair per sub-expression. Especially important for hook tool-matchers that combine path-globs with environment checks.
-
-- **Boundary value analysis** — Tests target the edges of input domains, not the middles. A function accepting integers `1..100` is tested at 1, 100, 0, 101, and one mid-range value. The bugs that ship are almost always at edges: off-by-one, empty input, max input, just-past-max input.
-
-  INSTEAD of one test at a representative middle value: at least four tests at min, max, just-below-min, just-above-max. Middle values catch zero bugs that boundary values miss; boundary values catch many bugs that middle values miss.
-
-- **Equivalence partitioning** — Divide input space into classes where one representative tests the whole class. Inputs `2, 5, 17, 42` are in the same "positive small integer" class; one test of them tests the class. Inputs `-1, 0, 1.5, "abc"` represent different classes (negative, zero, non-integer, non-numeric); each class owes a test.
-
-  INSTEAD of testing one input per literal value: identify the classes; test one representative per class plus the boundaries between classes. Reduces redundant tests; surfaces unconsidered classes.
-
-- **Error guessing** — Heuristic enumeration of likely failure modes based on the function's shape and history. Not algorithmic; expert-judgment-driven. Augments the systematic categories with experience-based pattern recognition.
-
-  INSTEAD of treating error guessing as inferior to systematic categories: use it as the additive layer that catches what taxonomy misses. The systematic categories are the floor; error guessing is the ceiling.
-
-## When to channel this luminary
-
-When the primary risk is sufficiency rather than rhythm. Myers dominates at test-authoring moments where the question is "I have a test that passes — is the test enough?" Specifically: per-hook test suites, state-spine accessor tests, API route validation tests, anywhere the function takes structured input and produces structured output with branches.
-
-Pair with Beck (TDD rhythm — Myers tells you what to write tests for; Beck tells you when to write them), Hoare (contract semantics — Myers categories operationalize Hoare's `(P, Q)` pair enumeration), Ousterhout (deep modules earn easier Myers coverage; shallow modules decay it).
-
-Skip Myers when: the test is a smoke test (bassclef/'smoke-test' skill scope), the work is a one-off script with no caller, or the relevant risk is design-quality rather than test-completeness (route to Ousterhout). Myers's discipline costs ~3x the write-time of a single happy-path test; apply where the function's correctness has compounding downstream impact.
-
-INSTEAD of citing Myers for test rhythm, refactoring tactics, or design quality: route to Beck, Fowler, and Ousterhout respectively.
-
-## Stack translation
-
-In bassclef's bash hook + state-spine substrate:
-
-- **Decision coverage applied to hook source** — Run `grep -cE '^\s*(if|elif|else|case)' <hook>.sh` to count branches. The test file's test-list owes at least that many `[x]` lines. For `auto-save-idle.sh` with 4 branches (no-changes / lock-present / defer-present / proceed), the test file owes 4 tests minimum.
-- **Condition coverage applied to compound `[ ... ]` tests** — A bash condition `[ -f LOCK -a AGE -lt TTL ]` has two sub-conditions. Tests must exercise: LOCK absent + AGE doesn't matter; LOCK present + AGE within TTL; LOCK present + AGE beyond TTL. Three cases for two sub-conditions; the `[ -a ... -a ... ]` compound earns the multi-case treatment.
-- **Boundary value analysis applied to numeric inputs** — For hooks with TTL / age / count thresholds: test exact threshold, one-below, one-above. For `auto-save-idle.sh` with `IDLE_THRESHOLD=300` (seconds): test AGE=299, AGE=300, AGE=301. Off-by-one bugs surface here.
-- **Equivalence partitioning applied to stdin / env-var shapes** — Hooks discriminate on `tool_name` (Bash | Edit | Write | etc), `file_path` glob matches, env-var presence. Each discriminator's value space partitions into classes; one test per class is the Myers minimum.
-- **Error guessing applied to bassclef-specific failure modes** — Experience accumulated from prior incidents: marker file unwritable (sandbox teardown); jq missing on alpine container; trace-helper.sh permission denied; concurrent hook invocations racing on the same marker. Each becomes one additional test that taxonomy alone would miss.
-
-In Next.js + TypeScript + vitest adopter stacks:
-
-- **Decision coverage in vitest** — `it.each` table-driven tests; one row per source branch
-- **Condition coverage for compound predicates** — `if (user.isAdmin && tenant.active)` owes both true/false variants for each sub-predicate
-- **Boundary value for pagination / limits** — page=0, page=1, page=MAX_PAGE, page=MAX_PAGE+1
-- **Equivalence partitioning for Zod input parsing** — one representative valid input per schema variant; one representative invalid per error class
-- **Error guessing for adopter-stack failures** — token-expired mid-request; rate-limit hit at the wrong tenant boundary; cache stampede on cold start
-
-## Anti-patterns it prevents
-
-- **"Happy path only"** — A single test that exercises the success case while every error branch is untested. Tier 0 hook (bassclef#1037) passes because a test exists; Myers's discipline fails because decision coverage is 1/N where N > 1.
-
-  INSTEAD: count branches; write one test per branch in the same commit. The marginal cost per test is small; the marginal cost of a shipped error-branch bug is large.
-
-- **"All branches but no boundary"** — Decision coverage achieved (each branch has a test) but every test uses mid-range input. Off-by-one bugs at branch boundaries ship to production.
-
-  INSTEAD: for any test with a numeric / string-length / count input, add the off-by-one neighbors as additional test cases. Three cases (mid, edge, just-past-edge) per branch is the floor.
-
-- **"Boundary but no equivalence"** — Tests at edges but redundant testing of mid-range values from the same class (e.g., 50 different positive-integer tests; zero negative-integer tests).
-
-  INSTEAD: partition the input space into classes before writing tests; pick one representative per class; the redundancy savings fund the edge-case coverage.
-
-- **"Equivalence but no error guessing"** — Formal Myers categories covered but experience-based failure modes ignored. The test suite is taxonomy-complete but production-incomplete.
-
-  INSTEAD: after applying the four systematic categories, ask "what could go wrong that taxonomy missed?" and add tests for each. The answer comes from incident history (chronicles), monitoring (alerts), and operator pattern recognition.
-
-- **"Tautological tests"** — Assertions that mirror the implementation rather than the intent. `assert(x === f(x))` where f is the function under test asserts implementation, not behavior. The test passes regardless of whether `f` is correct.
-
-  INSTEAD: assert the behavior the caller depends on, expressed in terms the caller would use. For a sorter, assert "result is sorted ascending" not "result equals sort(input)". The first is a property; the second is implementation-shaped.
-
-- **"Coverage-percentage gaming"** — Driving the coverage tool's percentage up by adding tests that exercise lines without exercising decisions. Myers's discipline rejects line coverage as the metric.
-
-  INSTEAD: decision coverage (every branch taken) + condition coverage (every sub-expression true and false) + boundary value (edges of input domains) are the essential metrics. Line coverage is a lagging indicator at best.
-
-## Worked example
-
-Tightening bassclef's `pre-commit-gate.sh` test under Myers's discipline:
-
-Step 1 — Decision coverage analysis (grep + count):
-
-```bash
-$ grep -cE '^\s*(if|elif|else|case|\|\|)' .claude/hooks/pre-commit-gate.sh
-14
-```
-
-14 decision points. Minimum 14 tests for decision coverage. Existing test file (allowlisted-pre-hardening) has 3 tests. Coverage = 3/14 = 21%. Failing.
-
-Step 2 — Condition coverage analysis:
-
-Find compound conditions:
-
-```bash
-$ grep -nE '\[\s+.*-(a|o)\s+.*\]|&&|\|\|' .claude/hooks/pre-commit-gate.sh
-```
-
-Each compound condition with `-a` / `-o` / `&&` / `||` owes one true/false per sub-expression. If 4 compound conditions average 2 sub-expressions each, that's 8 additional test variants beyond decision coverage.
-
-Step 3 — Boundary value analysis:
-
-Identify numeric / string-length thresholds in the hook:
-- Marker file age: write age=now, age=24h-1s, age=24h+1s tests
-- Branch-name length: 0 chars, 1 char, max-githook-supports, max+1
-- Diff line count if any: 0, 1, MAX, MAX+1
-
-Each threshold = 4 test variants.
-
-Step 4 — Equivalence partitioning:
-
-Discriminator: `tool_name` matcher
-- Class 1: Edit (matched, fires)
-- Class 2: Write (matched, fires)
-- Class 3: MultiEdit (matched, fires)
-- Class 4: Bash (not matched, pass-through)
-- Class 5: NotebookEdit (not matched, pass-through)
-- Class 6: malformed JSON stdin (error path)
-
-6 representatives = 6 test cases for this discriminator alone.
-
-Step 5 — Error guessing:
-
-From bassclef incident history (chronicles + memory):
-- marker directory missing entirely (fresh-clone scenario)
-- trace-helper.sh exits non-zero (broken log endpoint)
-- git binary version skew (BSD vs GNU date — caught bassclef#1085 yesterday)
-- Concurrent hook invocations (two PreToolUse fires on overlapping Edit calls)
-
-4 additional test cases from experience.
-
-Step 6 — Test list assembled:
-
-```bash
-# test-list:
-# Decision coverage (14 tests)
-# [x] Branch 1: no marker file, fix/ branch → BLOCKED
-# [x] Branch 2: temperance marker present, feature/ branch → pass
-# [ ] Branch 3: stacked manifest declares branch → suppress
-# ... (11 more decision-coverage entries)
-# Condition coverage (8 additional)
-# [ ] Compound: marker present AND mtime within 24h
-# [ ] Compound: marker present AND mtime older than 24h
-# ... (6 more)
-# Boundary value (12 additional)
-# [ ] Marker mtime = now
-# [ ] Marker mtime = exactly 24h ago
-# [ ] Marker mtime = 24h - 1s ago
-# [ ] Marker mtime = 24h + 1s ago
-# ... (8 more)
-# Equivalence partitioning (6)
-# [ ] tool_name = Edit
-# [ ] tool_name = Write
-# [ ] tool_name = MultiEdit
-# [ ] tool_name = Bash (pass-through)
-# [ ] tool_name = NotebookEdit (pass-through)
-# [ ] stdin malformed JSON
-# Error guessing (4)
-# [ ] marker directory missing entirely
-# [ ] trace-helper.sh exits non-zero
-# [ ] git binary BSD vs GNU date skew
-# [ ] concurrent PreToolUse fires
-```
-
-44 test cases for one hook. That sounds like a lot — until you remember pre-commit-gate.sh is essential for every commit in every consumer repo. The marginal cost of one hidden bug at this layer is multiplied by every adopter session.
-
-What this discipline catches that lazy testing misses: the BSD-vs-GNU date skew that bit bassclef#1085 yesterday morning. Decision coverage alone would miss it because both code paths use the same date-formatting function. Error-guessing from prior incidents (the "what's bit us before" lens) IS the category that catches it.
-
-## Sources
-
-- *The Art of Software Testing* — Myers, Wiley (1979); 3rd ed 2011 with Sandler & Badgett, ISBN 9780471043287
-- *Reliable Software through Composite Design* — Myers (1975)
-- ACM Digital Library entry for 1979 first edition
-- Cross-citation in Kaner, C. — *Testing Computer Software* (Wiley, 1993) crediting Myers as the systematic-testing forebear
-
-## Related luminaries
-
-- **Kent Beck** — TDD rhythm produces tests; Myers categories tell you whether the tests are enough. Tier 0 mtime enforcement (bassclef#1037) plus test-list discipline (bassclef#1090) plus Myers coverage taxonomy = the full TDD discipline bassclef operationalizes.
-- **Tony Hoare / Bertrand Meyer** — Contract-driven testing (precondition/postcondition/invariant) is a sub-shape of Myers's taxonomy applied at the API boundary. Hoare asks WHAT the contract is; Myers asks WHICH categories of input exercise the contract.
-- **John Ousterhout** — Deep modules with small interfaces are easier to fully cover under Myers categories; shallow modules expose so much surface that coverage decays. Myers's discipline implicitly rewards Ousterhout's design quality.
-- **Edsger Dijkstra** — Famously argued "testing shows the presence, not the absence, of bugs" — the counterweight that says even Myers-complete suites do not prove correctness in the formal sense. Read together: Myers operationalizes test-as-bug-discovery; Dijkstra reminds us proof is a different discipline.
-- **James Bach / Cem Kaner** (exploratory testing successors) — Modern testing heuristics built on Myers's foundation. Bassclef may add their luminaries in a future wave if exploratory testing earns a skill citation.
-
-## Verification
-
-Myers's authorship of *The Art of Software Testing* (1979) and his coining of the coverage taxonomy is verified via:
-
-1. ACM Digital Library entry for the 1979 first edition (ISBN 9780471043287)
-2. Wiley's listing of the 3rd edition (2011) with Sandler & Badgett
-3. Cross-citation in Kaner's *Testing Computer Software* (1993) crediting Myers as the systematic-testing forebear
-
-Per bassclef#867 anchor-luminary verification: name + dates + text title + taxonomy attribution confirmed from authoritative sources.

package/substrate/.claude/luminaries/hunt-thomas.md

@@ -1,115 +0,0 @@
----
-tier: lite
-name: Hunt & Thomas (Pragmatic Programmers)
-slug: hunt-thomas
-claimed_by: [builder, reviewer]
-referenced_by_skills: []
-primary_domain: engineering
-depth: full
-solves_problems_brownfield:
-  - "Same logic duplicated in three places; any fix requires finding all three"
-  - "A change in one module causes unexpected breakage in an unrelated module — tight coupling masked as shared code"
-  - "Code written by trial-and-error with no clear intent; passing tests but nobody knows why"
-  - "Developers fear changing old code because they can't tell what will break"
-solves_problems_greenfield:
-  - "Building a system where every piece of knowledge lives in exactly one place"
-  - "Designing modules that can be changed independently without ripple effects"
-  - "Starting a new codebase where developer discipline must prevent rot from day one"
-  - "Choosing which parts of a feature to prototype as throwaway vs which to keep as tracer bullets"
-anti_patterns:
-  - "Large deployed monoliths where DRY and orthogonality would require full rewrites — Feathers seam-first applies before this"
-  - "Spec-driven contexts requiring precise fidelity to a fixed requirement"
-  - "Teams in regulatory environments where prototype-vs-production distinction must be documented formally"
-sources:
-  - type: book
-    title: "The Pragmatic Programmer: From Journeyman to Master"
-    authors: ["Andrew Hunt", "David Thomas"]
-    year: 1999
-    url: "https://pragprog.com/titles/tpp20/the-pragmatic-programmer-20th-anniversary-edition/"
-    isbn: "9780135957059"
-    methodology_covered:
-      - "DRY (single knowledge source) — Every piece of knowledge must have one, unambiguous, authoritative representation"
-      - "Orthogonality — Two components are orthogonal if changing one requires no change in the other"
-      - "Tracer bullets — build a thin, working end-to-end path first"
-      - "Broken windows — small decay normalizes fast"
-  - type: book
-    title: "The Pragmatic Programmer: 20th Anniversary Edition"
-    authors: ["Andrew Hunt", "David Thomas"]
-    year: 2019
-    url: "https://pragprog.com/titles/tpp20/the-pragmatic-programmer-20th-anniversary-edition/"
-    isbn: "9780135957059"
-    methodology_covered:
-      - "DRY (single knowledge source)"
-      - "Orthogonality"
-      - "Tracer bullets"
-      - "Broken windows"
-  - type: blog_post
-    title: "Pragmatic Bookshelf publisher site"
-    authors: ["David Thomas"]
-    year: 1999
-    url: "https://pragprog.com/"
-    methodology_covered:
-      - "Primary publisher site for all Pragmatic Programmer editions; co-founded by Thomas"
-verification_status: verified
-description: "\"Every piece of knowledge must have a single, unambiguous, authoritative representation in a system."
----
-
-# Hunt & Thomas (Pragmatic Programmers)
-
-## Signature
-
-*"Every piece of knowledge must have a single, unambiguous, authoritative representation in a system. Duplication is the root of all software evil."* [ref:1]
-
-Andrew Hunt and David Thomas; authors of **The Pragmatic Programmer** (1999 [ref:1], 20th anniversary edition 2019 [ref:2]). The bassclef voice on day-to-day development discipline — the habits, heuristics, and mental models that separate journeymen from craftspeople. Where Uncle Bob covers SOLID principles and Clean Code covers naming, Hunt & Thomas cover the practical engineering ethos that holds it all together.
-
-## Core methods
-
-- **DRY (single knowledge source)** — Every piece of knowledge must have one, unambiguous, authoritative representation [ref:1]. Not just code duplication — DRY applies to data schemas, documentation, tests, configuration. When knowledge is duplicated, changes require parallel updates; one update will eventually be missed.
-- **Orthogonality** — Two components are orthogonal if changing one requires no change in the other [ref:1]. Build systems where responsibilities are independent. Orthogonality enables testing in isolation, deployment of parts independently, and fearless refactoring. Ask: "If I change this component, how many other things must change?" More than one means non-orthogonal design.
-- **Tracer bullets** — When starting a new feature or system, build a thin, working end-to-end path first [ref:1]. Unlike a prototype (thrown away after learning), a tracer bullet is production code; it proves the architectural path works with real infrastructure. Flesh out the path once the tracer lands.
-- **Broken windows** — A single unaddressed TODO, a failing test ignored, a function that clearly misrepresents what it does — these signal that quality is not a priority [ref:1]. Teams that tolerate one broken window soon tolerate ten. Small decay normalizes fast.
-
-## When to channel this luminary
-
-When the primary risk is accumulated developer slop: duplication creeping in across a growing codebase, modules coupling accidentally because it was easier, or a team building by coincidence rather than by intent. Hunt & Thomas dominate code review and initial architecture sessions where discipline habits are being established. Channel them when the team is growing and shared engineering standards need grounding.
-
-INSTEAD of channeling Hunt & Thomas for systems under acute failure: use Nygard for production stability, Newman or Hohpe for large-scale distributed architecture. Hunt & Thomas are everyday discipline, not the crisis response.
-
-## Stack translation
-
-In Next.js + Prisma + TypeScript:
-
-- **DRY** — schema types derived from Prisma output (single source of truth); API response shapes defined once as Zod schemas, reused for both server-side validation and client-side type inference; environment variables loaded and typed in a single `env.ts`, imported everywhere else.
-- **Orthogonality** — service layer functions that do not import from UI components; Prisma models that contain no business rules; server actions that contain no formatting logic. If a test for deal enrichment requires importing a React component, the design is non-orthogonal.
-- **Tracer bullets** — first commit on a new feature: end-to-end slice touching DB → server action → component → route — with minimal data but fully wired. Real code that runs, not a mock. The tracer confirms the path works. Then add fields, edge cases, and polish.
-- **Broken windows** — failing tests in CI block the pipeline (no exceptions); TypeScript strict mode enforced from day one; no `any` types in production code without a comment explaining why.
-
-## Anti-patterns it prevents
-
-- **Knowledge duplication** — the same business rule encoded in the Prisma schema, a Zod schema, a TypeScript type, AND inline validation. When the rule changes, three of four are updated; one is not. DRY discipline collapses these to one source.
-- **Programming by coincidence** — code that "happens to work" without the developer understanding why. Characterized by careful arrangement of boilerplate without testing the assumptions. If you cannot explain why it works, it will stop working in a condition you have not tested.
-- **Accidental coupling** — two modules share a utility or helper that grows to carry business logic for both. Changing the helper to serve one module breaks the other. Orthogonality discipline prevents this: ask whether the helper carries knowledge that belongs to only one module. If yes, extract.
-- **Prototype rot** — throwaway prototypes that become production because "it mostly works." Prototypes are discarded after learning; tracer bullets are production code from the start. Calling something a prototype does not justify shipping it.
-
-## Worked example
-
-For POA's deal enrichment pipeline, Hunt & Thomas's approach:
-
-**DRY check**: the definition of "enrichment fields" (company name, headcount, industry) appears in the Prisma schema, an enrichment TypeScript type, an API response shape, AND a table column list in the UI. Four representations of one piece of knowledge. DRY says: Prisma is the single source; derive the TypeScript type from Prisma's generated types; derive the API response from the same type; derive the table columns from a central field registry. Adding a new field changes one file.
-
-**Orthogonality check**: the enrichment worker imports from the email module because a previous developer wanted to send a notification when enrichment completes. Extract the notification logic: enrichment worker emits an event or calls a notification interface; the email module listens. The enrichment worker no longer depends on email infrastructure.
-
-**Tracer bullet**: first day on "bulk enrichment" — wire a single deal through the new batch endpoint, job queue, and enrichment function. No retry logic, no bulk UI, no progress tracking. But it runs end-to-end with real data. The tracer confirms the queue can dispatch enrichment jobs. Then add batch size, retries, and UI.
-
-## Sources
-
-- *The Pragmatic Programmer: From Journeyman to Master* — Hunt, Thomas, Addison-Wesley (1999) [ref:1]
-- *The Pragmatic Programmer: 20th Anniversary Edition* — Hunt, Thomas, Addison-Wesley (2019) — substantially revised [ref:2]
-- pragprog.com — Pragmatic Bookshelf (co-founded by Thomas) [ref:3]
-
-## Related luminaries
-
-- **Robert C. Martin** — SOLID principles and Clean Code operate at the same altitude. Uncle Bob's Single Responsibility complements Hunt & Thomas's orthogonality; both reject coupling from different starting points.
-- **Martin Fowler** — Refactoring is where you fix the broken windows and eliminate DRY violations that accumulated. Fowler's catalog operationalizes what Hunt & Thomas prescribe.
-- **Kent Beck** — TDD is how you prove the tracer bullet works and keep the broken windows visible as failing tests.
-- **Michael Feathers** — When the codebase is already non-orthogonal with high duplication, Feathers's seam-based approach is the path back before Hunt & Thomas's discipline can hold.

package/substrate/.claude/luminaries/hyrum-wright.md

@@ -1,94 +0,0 @@
----
-tier: lite
-name: Hyrum Wright
-slug: hyrum-wright
-claimed_by: [architect]
-referenced_by_skills: [release, decompose, architect-review]
-primary_domain: api-stability
-depth: stub
-description: "\"With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody.\""
----
-
-# Hyrum Wright
-
-## Signature
-
-*"With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody."*
-
-This is **Hyrum's Law**. Wright is a Google software engineer who codified what kernel hackers, library maintainers, and protocol designers had been learning for decades. The law is the theoretical foundation for why "we don't break adopters" is a Tier 1 discipline.
-
-## Core principle
-
-**Observability creates dependency.** Hyrum's Law extends API stability beyond declared contracts to every observable behavior. The signature, the return type, the timing, the side effects, the order of error messages, the filename of an internal file — every observable surface accumulates dependencies once enough users exist.
-
-The law has three implications:
-
-1. **You cannot fully specify behavior.** Whatever you document as "the contract," some adopter will be depending on something you didn't document.
-2. **Refactor risk grows with adoption.** A change "safe under the contract" can break adopters who depend on observable side effects.
-3. **The cost of cleanup is asymmetric.** Producers want to clean up. Adopters want stability. Once N adopters depend on observed behavior, the producer's cleanup cost is N × (each adopter's migration effort).
-
-## How this applies to bassclef
-
-Tonight's example: bassclef never declared `~/src/sunj-labs/canonical/` as a stable filesystem path. The directory name was an internal convention, not a contract. But every adopter on the operator's machine had observed that path — through their symlinks, through their `settings.json`, through their `additionalDirectories` references. The rename `mv canonical bassclef` broke an undeclared but heavily-observed surface.
-
-Hyrum's Law says: that path was a contract whether bassclef declared it or not. With enough adopters (10+ siblings on this one machine), every observable surface becomes load-bearing.
-
-The discipline answer:
-
-- Treat **every** adopter-observable surface as part of the contract, not just declared ones.
-- When unsure if a surface is observable, **assume it is** and ship the compat shim.
-- Use Hyrum's Law as the budget against premature refactoring — "would I want to maintain this surface forever?" If no, don't ship it as observable.
-
-## Key insight: the contract is what users observe, not what you wrote
-
-This reframes substrate evolution:
-
-| You wrote | Adopters observe | What's actually the contract |
-|---|---|---|
-| "Sync from `bassclef-source.json`" | `~/src/sunj-labs/canonical/` path | The path |
-| "Hook X fires on PreToolUse" | Hook X's filename and location | The filename + location |
-| "Skills load from `.claude/skills/`" | Symlink targets, agent names, directory structure | All three |
-| "State spine entities follow schema S" | Every field name, every default value, every error message | All of it |
-
-The substrate's "contract" is much bigger than what's written down. Every change must respect the observable surface.
-
-## How to apply
-
-1. **Enumerate observable surfaces before changing them.** Run `grep -rn` across known adopter repos for any reference to the surface you're about to change.
-2. **When in doubt, assume it's observed.** The cost of an unnecessary compat shim is small. The cost of a broken adopter is large.
-3. **Test against real adopter consumption.** Not unit tests on the substrate side; integration tests that clone a representative adopter and exercise their consumption paths.
-4. **Account for the multiplier.** A surface used by 10 adopters has 10× the migration cost. The math: "is the rename benefit > 10 × (migration cost per adopter)?" usually says no.
-
-## Anti-patterns
-
-- **"It's not in the public API"** — Hyrum's Law doesn't care. Adopters depend on whatever they can observe.
-- **"We never documented that"** — same response. Documentation isn't the contract; observability is.
-- **"Only one adopter uses it"** — that's still one broken adopter. And tomorrow there will be more.
-- **"We can deprecate and migrate"** — Hyrum's Law warns that deprecation periods are always shorter than the actual migration tail. Plan for permanent shims, not eventual cleanup.
-
-## How bassclef channels Hyrum
-
-The discipline lives in:
-
-- `.claude/rules/we-dont-break-adopters.md` — methodology layer; cites Hyrum's Law as the why
-- `architecture/dual-repo-flow.md` "Non-breaking changes to adopters" section — enumerates adopter-observable surfaces
-- Phase 2 mechanical layer (bassclef#1360) — pre-rename CI test surfaces every observable adopter dependency before a substrate change ships
-
-## Sources
-
-- Hyrum Wright, "Hyrum's Law" — https://www.hyrumslaw.com/
-- *Software Engineering at Google* — Wright, Winters, Manshreck; O'Reilly (2020)
-- Titus Winters talks on long-term codebase maintenance (Google C++ committee chair); CppCon
-- XKCD 1172 ("Workflow") — the cultural reference Wright codified into a law
-
-## Distinct from
-
-- @luminary linus-torvalds — applies Hyrum's Law to operating system kernels; provides the discipline answer (we just don't break userspace, ever)
-- @luminary michael-nygard — stability patterns at runtime; complements but doesn't anchor the design-time discipline
-- @luminary frederick-brooks — provides the cost framing (cumulative cleanup cost vs single-rename benefit); Hyrum provides the why (observability multiplies the cost across adopters)
-
-## Refs
-
-- bassclef#1360 — Phase 2 mechanical layer
-- 2026-06-21 chronicle — first documented Hyrum's-Law cascade in bassclef's history
-- ADR-031 — non-breaking-change adopter discipline (decision layer)

package/substrate/.claude/luminaries/jason-fried-dhh.md

@@ -1,46 +0,0 @@
----
-tier: lite
-name: Jason Fried / DHH (David Heinemeier Hansson)
-slug: jason-fried-dhh
-claimed_by: [shaper]
-referenced_by_skills: [canvas, sprint]
-primary_domain: shaping
-depth: stub
-description: "\"It doesn't have to be crazy at work.\""
----
-
-# Jason Fried / DHH
-
-## Signature
-
-*"It doesn't have to be crazy at work."*
-
-Basecamp founders; the philosophical foundation behind Shape Up. Canonical
-voices on **calm, independent, opinionated product work** — small teams
-shipping polished software on a rhythm, without the manufactured urgency
-of startup culture.
-
-## Core methods
-
-- **Appetite over estimation** (later operationalized by Singer as Shape Up) —
-  Fixed time, variable scope. Don't estimate; bet.
-- **Six-week cycles + two-week cool-down** — Deliberately slow cadence.
-  Reject agile theater of weekly sprints.
-- **Interruption is the enemy** — Long uninterrupted time is the actual
-  productivity multiplier. Meetings, chat, "quick syncs" destroy it.
-- **Opinionated software** — Products that make choices for users reduce
-  decision fatigue. Neutrality is a design failure.
-
-## Sources
-
-- *Rework* — Fried, Hansson, Crown Business (2010)
-- *It Doesn't Have to Be Crazy at Work* — Fried, Hansson, Harper Business (2018)
-- *Getting Real* — 37signals (2006), free online at gettingreal.37signals.com
-- basecamp.com/books — all 37signals/Basecamp books free
-
-## Related luminaries
-
-- **Ryan Singer** — Singer operationalized Fried/DHH's philosophy into
-  Shape Up; they are the underlying philosophy, he is the method.
-- **Catherine Wu (Anthropic)** — "Underfund on purpose" echoes Fried/DHH's
-  appetite discipline.