@thebassclef/lite 0.1.0 → 0.1.2

package/substrate/.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/substrate/.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/substrate/.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/substrate/.claude/luminaries/michael-feathers.md

@@ -113,11 +113,11 @@ The scraper function is 300 lines; it fetches, parses, writes to the database, a
 Feathers's "code without characterization tests is legacy code by definition" became the anchor citation for the bassclef substrate-as-system tenet (ADR-035). The bet 24c architect-review (2026-06-24) anchored on comprehension-side lenses (Brooks + Linus + Ishikawa + Deming) and missed the mechanism-fidelity class — "rule names mechanical enforcement that does not actually fire." The recursive Act phase (`architecture/audits/2026-06-27-audit-method-blind-spot.md`) named the lens-gap; Feathers's verification-side framing supplied the cure.
 
 The bet 27c foundation ships:
-- `standards/mechanism-fidelity.md` — audit method spec; Feathers-style characterization tests pin every rule's mechanism claim
+- `standards/mechanism-fidelity.md` (standard tier) — audit method spec; Feathers-style characterization tests pin every rule's mechanism claim
 - `lib/mechanism-fidelity.sh` — shared scanner that runs the 5-step verification chain
 - `.claude/skills/audit-rule-mechanism-fidelity/SKILL.md` — operator-invocable audit (Feathers + Beck primary luminaries)
 - `scripts/cold-adopter-harness-sync.sh` Shape d — per-PR gate (4 check classes; Feathers + Saltzer-Schroeder + Ousterhout primary)
-- `.claude/rules/substrate-as-system.md` — auto-loaded tenet rule (cites Feathers as primary)
+- `.claude/rules/substrate-as-system.md` (standard tier) — auto-loaded tenet rule (cites Feathers as primary)
 - `.claude/skills/architect-review/SKILL.md` — amendment makes Feathers + Beck + Saltzer-Schroeder verification-side primaries alongside Brooks + Linus comprehension-side primaries
 
 Feathers's brownfield-rescue framing applies recursively at the substrate level: bassclef's own substrate had legacy mechanism-fidelity claims (108 claims classified by WU-6 first audit; 76 non-CLEAN). The cure bet (Bet C-pre-2) drives them to zero via the same Feathers discipline — characterization tests, seam identification, sprout/wrap patterns — applied to substrate hooks rather than application code.

package/substrate/.claude/luminaries/tony-hoare.md

@@ -0,0 +1,170 @@
+---
+tier: lite
+name: Tony Hoare
+slug: tony-hoare
+claimed_by: [builder, reviewer, architect]
+referenced_by_skills: [verify, pattern-review, decompose]
+primary_domain: engineering
+depth: full
+sources:
+  - type: paper
+    title: "An Axiomatic Basis for Computer Programming"
+    authors: ["C. A. R. Hoare"]
+    year: 1969
+    venue: "Communications of the ACM, 12(10), 576-580"
+    url: "https://dl.acm.org/doi/10.1145/363235.363259"
+    methodology_covered:
+      - "Hoare logic — the triple {P} S {Q} relating precondition P, statement S, postcondition Q"
+      - "Formal reasoning about program correctness through assertion calculus"
+      - "Axiomatic semantics — meaning of a program is what can be proved about it"
+  - type: paper
+    title: "Hints on Programming Language Design"
+    authors: ["C. A. R. Hoare"]
+    year: 1973
+    venue: "Stanford Computer Science Department, STAN-CS-73-403"
+    url: "https://www.cs.tufts.edu/~nr/cs257/archive/tony-hoare/hints-pl-design.pdf"
+    methodology_covered:
+      - "Simplicity is the unique selling proposition of a programming language"
+      - "Security via construction — design out classes of error rather than detect them"
+      - "Readability primacy — a program is read more often than it is written"
+  - type: paper
+    title: "Communicating Sequential Processes"
+    authors: ["C. A. R. Hoare"]
+    year: 1978
+    venue: "Communications of the ACM, 21(8), 666-677"
+    url: "https://dl.acm.org/doi/10.1145/359576.359585"
+    methodology_covered:
+      - "CSP — concurrency as composition of independent processes communicating via synchronous channels"
+      - "Influenced Go's goroutines + channels, Erlang's actor model, occam"
+  - type: talk
+    title: "Null References: The Billion Dollar Mistake"
+    authors: ["C. A. R. Hoare"]
+    year: 2009
+    venue: "QCon London"
+    url: "https://www.infoq.com/presentations/Null-References-The-Billion-Dollar-Mistake-Tony-Hoare/"
+    methodology_covered:
+      - "Reflection on ALGOL W (1965) decision to allow null references — admits as billion-dollar mistake"
+      - "Design errors out of existence via type system — modern relevance to Option / Result / NonNullable types"
+verification_status: verified
+description: "\"There are two ways of constructing a software design: one is to make it so simple that there are obviously no deficiencies; the other is to make it so complicated that there are…"
+---
+
+# Tony Hoare
+
+## Signature
+
+*"There are two ways of constructing a software design: one is to make it so simple that there are obviously no deficiencies; the other is to make it so complicated that there are no obvious deficiencies. The first method is far more difficult."*
+
+Sir Charles Antony Richard Hoare. Turing Award winner (1980) for "fundamental contributions to the definition and design of programming languages." Author of **Quicksort** (1959), **Hoare logic** (1969), and **Communicating Sequential Processes** (1978). Oxford professor emeritus and Microsoft Research senior researcher. The bassclef voice on contract-driven reasoning, simplicity-as-discipline, and designing errors out of existence.
+
+## Core methods
+
+- **Hoare logic — the `{P} S {Q}` triple** — A program statement `S` is correct with respect to precondition `P` and postcondition `Q` if: when `P` holds before `S` executes, then `Q` holds after `S` terminates. The triple is the formal contract between caller and callee. Test sufficiency for a function is: cover every meaningful `(P, Q)` pair the function commits to.
+- **Precondition discipline** — A function's precondition is what the caller must guarantee. Violations are programmer errors, not runtime errors. Pre-validate at the boundary; trust internally.
+- **Postcondition discipline** — A function's postcondition is what it guarantees on return. The test asserts the postcondition; the implementation establishes it.
+- **Loop invariant** — A condition true before the loop, after every iteration, and on exit. The invariant IS the proof that the loop establishes its postcondition.
+- **Class invariant** (operationalized by Bertrand Meyer in Eiffel's Design by Contract, 1986) — A condition that holds at every observable state of an instance. Constructors must establish it; methods must preserve it.
+- **Communicating Sequential Processes (CSP)** — Concurrency as composition of independent processes that synchronize only through explicit channels. Shared mutable state replaced by message-passing. Direct ancestor of Go's goroutines + channels, Erlang's actor model.
+- **Simplicity as design discipline** — Hoare's most-cited prescription: choose the design where deficiencies are obvious, not the design where there are no obvious deficiencies. The two are not equivalent; the second hides bugs the first surfaces.
+- **Design errors out of existence** — Null references were a 1965 design choice Hoare publicly regrets. The lens: if a class of error CAN be made impossible by construction (type system, API shape, invariant enforcement), make it so. Detection is strictly weaker than prevention.
+
+## When to channel this luminary
+
+When the primary risk is correctness under interaction — multiple callers, multiple states, contracts implicit but unenforced. Hoare dominates for state-spine accessors, hook input/output contracts, concurrent code (locks, queues, event ordering), and API boundaries where the contract has to survive every caller.
+
+Pair with Beck (TDD rhythm), Myers (coverage taxonomy of what to assert), Ousterhout (design judgment for where to draw the boundary). Beck owns the cycle; Myers owns the categories; Ousterhout owns the shape; Hoare owns the contract itself.
+
+Skip Hoare when: the work is exploratory spike code with no caller, the interface is genuinely throwaway, or the relevant risk is design-quality rather than contract-correctness (route to Ousterhout). Hoare's discipline carries overhead; apply where the overhead earns its keep.
+
+INSTEAD of citing Hoare for refactoring tactics, design-pattern selection, or test rhythm: route to Fowler, GoF, and Beck respectively.
+
+## Stack translation
+
+In bassclef's bash hook + state-spine substrate:
+
+- **Hook tests as contract assertions** — Every hook test case is a Hoare triple in disguise. Test name = `(P, Q)` pair; arrange-act-assert is `establish P → run S → check Q`. Example: for `auto-save-idle.sh`, `test('SESSION_LOCK present suppresses auto-save', ...)` is `{LOCK file exists} run hook {no commit happens}`. The test sufficiency rubric's "stdin contract" criterion IS Hoare's precondition discipline.
+- **State-spine accessors as contracts** — `state_whereami_set "key" "value"` has precondition (`key` is a valid Whereami field path; `value` is JSON-serializable + schema-conformant) and postcondition (state stored + queryable via `state_whereami_get "key"`). The `state-validate.sh` PreToolUse hook IS the mechanical enforcement of the precondition; the schema IS the contract.
+- **Pre-build-gate hook as precondition enforcement** — Every gate the hook fires (temperance marker present? diagnose evidence on fix/ branches? state markers in place?) is a precondition the substrate refuses to relax. The hook BLOCKs to prevent the agent from violating a contract that downstream consumers depend on.
+- **Bash strict mode as invariant** — `set -euo pipefail` establishes an invariant: any unhandled error terminates the script. The invariant must hold across every function; `trap EXIT` cleanup respects the invariant by running regardless of exit path.
+- **CSP-style channels in bassclef** — Inter-session coordination via roadmap event_history (bassclef#337) follows CSP shape: each session is a process; the roadmap is the synchronization channel; atomic claim/release primitives are the synchronous message-pass. Direct application of Hoare's 1978 paper to multi-agent SDLC.
+
+In Next.js + TypeScript adopter stacks:
+
+- **Type system as precondition encoder** — `Option<T>` / `Result<T, E>` / branded types make Hoare's "design errors out of existence" mechanical. `NonNullable<T>` is null-as-billion-dollar-mistake corrected at compile time.
+- **Zod schemas as boundary contracts** — Validate at the system boundary (API route handler, message consumer); trust internally. Zod parse failure IS the precondition violation Hoare's framing makes explicit.
+- **Class invariants in domain models** — A `Deal` instance with `status: 'closed' && closingPrice: undefined` violates an invariant. Constructors + factories enforce it; methods preserve it.
+
+## Anti-patterns it prevents
+
+- **Implicit contracts that drift** — A function with no documented precondition has every caller guessing. When one caller's assumption diverges from another's, bugs appear at the seam. Hoare's discipline forces the contract to be explicit (test, type, assertion, or comment).
+- **Defensive coding scattered across callers** — Every caller checking the same precondition is a contract that should have been centralized at the callee's boundary. Pre-validate once at the entry; trust thereafter.
+- **Postcondition-by-vibe** — "It seems to work" is not a contract. Hoare's framing requires the postcondition be statable and testable. If it is not statable, the function's purpose is unclear.
+- **Loop-by-mutation-tracking** — A loop where correctness depends on tracking which variables mutated in which order is harder to reason about than a loop with an explicit invariant. Hoare's invariant discipline asks: what is true at the top of every iteration?
+- **Null-as-default** — Returning `null` (or `undefined`) for "not found" forces every caller to handle the missing case. Returning `Option<T>` (or `NotFound<T>`) encodes the precondition into the type system. Hoare's billion-dollar-mistake talk is the bassclef case against null-as-default.
+- **Shared mutable state for coordination** — Two processes synchronizing through a shared variable hold an implicit lock the language has no visibility into. CSP-style channels make the synchronization explicit; the channel IS the synchronization.
+
+## Worked example
+
+Tightening bassclef's `auto-save-idle.sh` hook under Hoare's discipline:
+
+**Before — implicit contract:**
+
+```bash
+# Pseudocode of pre-#1085 state
+if [ -z "$(git status --porcelain)" ]; then exit 0; fi
+git add -A
+git commit -m "auto-save: $(date -u)"
+```
+
+What is the precondition? Caller assumes: working tree dirty, no SESSION_LOCK, no commit-sequence in flight. None of these are stated. Three different sessions can produce three different definitions of "should this commit?"
+
+**After — Hoare-explicit contract:**
+
+```bash
+# {P}: working tree dirty AND no SESSION_LOCK AND no defer marker for commit-sequence
+[ -n "$(git status --porcelain)" ] || { exit 0; }                    # P-1: dirty
+[ ! -f .claude/SESSION_LOCK ] || { exit 0; }                          # P-2: no lock
+[ ! -f state/markers/auto-save-defer/commit-sequence.marker ] || { exit 0; }  # P-3: no defer
+
+# S: stage + commit
+git add -A
+git commit -m "auto-save: $(date -u)"
+
+# {Q}: HEAD advanced by exactly one commit AND working tree clean
+[ "$(git status --porcelain)" = "" ]                                  # Q-1: clean
+```
+
+What the test owes (Hoare-derived test list):
+
+```bash
+# test-list:
+# [x] {dirty AND no LOCK AND no defer} → commit happens AND tree clean (P all true, Q holds)
+# [x] {LOCK present} → no commit (P-2 false; hook returns early before S)
+# [x] {defer marker present} → no commit (P-3 false; hook returns early before S)
+# [x] {clean tree} → no commit (P-1 false; nothing to commit)
+# [x] {LOCK AND defer present} → no commit, LOCK takes precedence in early-exit order
+```
+
+The test list IS the Hoare triple decomposed. Each line names one `(P, Q)` pair. The hook is the implementation that establishes Q when P holds.
+
+What this discipline catches: PR #1058 (the auto-save-scope-hole that bassclef#1059 closed) shipped without P-2 enforced. A Hoare-explicit contract from day one would have surfaced the missing precondition at write time, not after the failure ran in production substrate.
+
+## Sources
+
+- "An Axiomatic Basis for Computer Programming" — Hoare, *Communications of the ACM* 12(10), 1969
+- "Hints on Programming Language Design" — Hoare, Stanford CS, 1973
+- "Communicating Sequential Processes" — Hoare, *Communications of the ACM* 21(8), 1978; book Prentice Hall, 1985
+- "Null References: The Billion Dollar Mistake" — Hoare, QCon London 2009
+- "Quicksort" — Hoare, *Computer Journal* 5(1), 1962
+- ACM Turing Award citation (1980)
+- Oxford Department of Computer Science emeritus page
+- Microsoft Research Cambridge senior researcher page
+
+## Related luminaries
+
+- **Bertrand Meyer** — Design by Contract operationalized Hoare's logic for Eiffel (1986); same lens with practitioner-grade tooling. Modern type systems (TypeScript, Rust, Scala) carry DBC patterns Meyer named.
+- **Edsger Dijkstra** — Structured programming + weakest-precondition calculus extended Hoare's axiomatic basis. Famously argued "testing shows the presence, not the absence, of bugs" — the counterweight that says even Hoare-explicit contracts do not prove correctness in the formal sense.
+- **Glenford Myers** — Coverage taxonomy supplies the WHICH categories of input exercise a contract; Hoare supplies WHAT the contract is. Both are required for a complete test suite.
+- **Kent Beck** — TDD rhythm produces tests; Hoare contracts decide what those tests must assert. Beck's "make it work" needs Hoare's "what does it commit to" to be testable.
+- **John Ousterhout** — Deep modules with small interfaces are easier to contract-test (small surface area for `(P, Q)` pairs). Ousterhout's design quality lens implicitly rewards Hoare-explicit interfaces.
+- **Tony Hoare's own work on CSP** — direct ancestor of Go (channels + goroutines), Erlang (actor model), occam. Bassclef's event_history + atomic claim/release pattern (bassclef#337) is CSP applied to multi-session SDLC.