@thebassclef/lite 1.0.4 → 1.1.1

package/dist/lite/.claude/luminaries/glenford-myers.md

@@ -0,0 +1,230 @@
+---
+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/dist/lite/.claude/luminaries/hunt-thomas.md

@@ -0,0 +1,115 @@
+---
+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/dist/lite/.claude/luminaries/hyrum-wright.md

@@ -0,0 +1,94 @@
+---
+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/dist/lite/.claude/luminaries/jason-fried-dhh.md

@@ -0,0 +1,46 @@
+---
+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.

package/dist/lite/.claude/luminaries/jesse-james-garrett.md

@@ -0,0 +1,154 @@
+---
+tier: lite
+name: Jesse James Garrett
+slug: jesse-james-garrett
+claimed_by: [designer]
+referenced_by_skills: [ia-model, canvas, spec]
+primary_domain: ux
+depth: full
+sources:
+  - type: book
+    title: "The Elements of User Experience: User-Centered Design for the Web and Beyond (2nd edition)"
+    authors: ["Jesse James Garrett"]
+    year: 2010
+    url: "https://www.pearson.com/en-us/subject-catalog/p/elements-of-user-experience-the-user-centered-design-for-the-web-and-beyond/P200000009272"
+    isbn: "9780321683687"
+    methodology_covered:
+      - "Five planes of UX — Strategy, Scope, Structure, Skeleton, Surface"
+      - "Decisions sequence from abstract (strategy) to concrete (surface)"
+      - "Each plane constrains the next; clarity at one plane prevents thrashing at others"
+      - "Information architecture as a structural-plane concern, distinct from skeleton (wireframe) or surface (visual)"
+verification_status: verified
+solves_problems_brownfield:
+  - "Project mixes strategy, scope, structure, skeleton, and surface decisions in one conversation"
+  - "Surface decisions are over-determining structural choices in the existing UI"
+  - "Team can't agree on which decisions belong at which level"
+solves_problems_greenfield:
+  - "Starting a multi-surface product where the five planes should sequence design decisions"
+  - "Building a UX strategy that decomposes work into orderable layers from day one"
+  - "Planning a product where strategy precedes scope precedes structure precedes skeleton precedes surface"
+  - "Designing a multi-month product where UX governance needs explicit decision-tier vocabulary"
+anti_patterns:
+  - "Tactical UI fixes where the five planes is overhead"
+  - "Single-page or single-screen work"
+description: "\"Every user experience has five planes: strategy, scope, structure, skeleton, surface."
+---
+
+# Jesse James Garrett
+
+## Signature
+
+*"Every user experience has five planes: strategy, scope, structure, skeleton, surface. Skip one and the next collapses."*
+
+Co-founder of Adaptive Path; author of **The Elements of User Experience**.
+Coiner of **Ajax** (2005). The bassclef framework for thinking about UX
+as a layered set of decisions that must be made in sequence — each plane
+constrains the next.
+
+## Core methods
+
+- **The Five Planes of UX** — From bottom (abstract) to top (concrete):
+  - **Strategy** — user needs + product objectives. What success means.
+  - **Scope** — functional specifications + content requirements. What
+    the product contains.
+  - **Structure** — interaction design + information architecture. How
+    it's organized.
+  - **Skeleton** — interface design, navigation design, information
+    design. Where things are placed.
+  - **Surface** — sensory design (visual, auditory). How it looks and
+    feels.
+- **Bottom-up sequence** — Each plane must be resolved before the plane
+  above it. Surface decisions made before strategy produce pretty
+  products that serve no one.
+- **Plane consistency** — Decisions on one plane must cohere across that
+  plane. An app with two incompatible IAs (one by section, one by
+  feature) has a structure-plane failure.
+- **Abstract-to-concrete progression** — Planes move from invisible
+  decisions (strategy) to visible output (surface). A team skipping
+  straight to surface design has no grounding for why.
+
+## When to channel this luminary
+
+When the biggest risk is getting the layers out of sequence — jumping to
+visual design before structure is resolved, or committing to scope
+before strategy is clear. Garrett dominates in project planning and
+SDLC-flow work: ensuring the right decisions happen in the right order.
+Think: new-product definition, UX audits of existing products, pedagogy
+for designers or teams new to systematic UX.
+
+Do NOT channel Garrett for: tactical interaction design decisions (use
+Norman, Tidwell), object-modeling (use Prater), visual polish (use
+Lupton, Ive).
+
+## Stack translation
+
+Garrett's planes map directly onto the bassclef SDLC:
+
+- **Strategy plane** → `/canvas` (Thesis stage) + iteration bet framing
+- **Scope plane** → `/canvas` (Shape stage) + `/spec` + feature list
+- **Structure plane** → `/ia-model` + `/jtbd-tasks` + `/task-scenarios`
+- **Skeleton plane** → `/interaction-design` + `/decompose` (responsibility)
+- **Surface plane** → `/frontend-design` + `/visual-review` + design tokens
+
+The bassclef UX translation chain (JTBD → HTA → IA → Interaction Design)
+is Garrett's structure plane made operational. `/riff-prototypes`
+skips to skeleton/surface only when the lower planes are resolved.
+
+## Anti-patterns it prevents
+
+- **Surface-first design** — starting with visual mockups before
+  structure or scope is settled. Produces beautiful products that fail
+  strategy tests.
+- **Premature plane commitment** — locking visual design before
+  interaction design is complete. Forces structure decisions to fit
+  pre-made mockups.
+- **Plane-skipping** — jumping from strategy to surface, or scope to
+  skeleton. Missing planes leave load-bearing decisions implicit.
+- **Plane inconsistency** — a strategy plane that says "operator tool"
+  paired with a surface plane that says "consumer SaaS." Reveals
+  uncoordinated decisions.
+- **Deliverable confusion** — treating wireframes (skeleton) as final
+  design, or treating mockups (surface) as structure. Each plane has
+  its own deliverables and can't substitute.
+
+## Worked example
+
+For POA's deal pipeline feature planning, Garrett's five planes produce:
+
+1. **Strategy**: Operator needs efficient pipeline management; product
+   objective is reducing time-to-close. Success = X% faster deal
+   throughput.
+2. **Scope**: Functional = deal CRUD, stage transitions, broker
+   association, note logging, search, export. Content = deal types,
+   stage definitions, standard fields, extension fields.
+3. **Structure**: Interaction = stage-transition flow, note-logging
+   flow, broker-assignment flow. IA = object-first nav (Deals, Brokers,
+   Sellers) with facets (stage, source, age).
+4. **Skeleton**: List-detail pattern for deals; right-rail for
+   secondary info; sticky stage-progress at top of detail view;
+   collapsed sections for enrichment data.
+5. **Surface**: Design tokens (colors, typography, spacing); dense
+   table view; status chips per stage; hover states and transitions.
+
+Each plane's output is input to the next. Skipping directly from
+Strategy to Surface (shopping for a pretty template) would produce a
+product that looks great and serves no specific operator workflow.
+
+## Sources
+
+- *The Elements of User Experience: User-Centered Design for the Web
+  and Beyond* — Garrett, New Riders (1st ed 2002, 2nd ed 2010)
+- *"Ajax: A New Approach to Web Applications"* — Garrett, Adaptive
+  Path essay (2005) that coined the term
+- jjg.net — Garrett's primary site (maintains classic Elements diagram)
+
+## Related luminaries
+
+- **Sophia Prater** — OOUX lives at Garrett's structure plane. Not a
+  replacement; a specific method for that plane.
+- **Alan Cooper** — Goal-Directed Design operates across planes but
+  grounds in strategy (user goals) and scope (task lists).
+- **Peter Morville** — IA work is structure-plane; Morville + Garrett
+  pair naturally.
+- **Ellen Lupton** — Typography is surface-plane; don't invoke until
+  skeleton is resolved.