@thebassclef/lite 0.0.1 → 0.1.0

package/substrate/.claude/luminaries/michael-feathers.md

@@ -0,0 +1,125 @@
+---
+tier: lite
+name: Michael Feathers
+slug: michael-feathers
+claimed_by: [builder, reviewer]
+referenced_by_skills: [verify, pattern-review]
+primary_domain: engineering
+depth: full
+solves_problems_brownfield:
+  - "Codebase has no tests; any change risks unknown breakage across the system"
+  - "A class or function can't be tested without instantiating half the application"
+  - "New behavior needs to be added adjacent to legacy code that can't be safely changed"
+  - "A module is deeply coupled to its dependencies (database, filesystem, clock); tests require real infrastructure"
+solves_problems_greenfield:
+  - "Designing a new module that will be introduced to a legacy system; seams must be planned from the start"
+  - "Building a service layer that wraps a third-party system; the wrap method must stay testable as the third-party evolves"
+  - "Planning a brownfield rescue effort; need a staged safety-net strategy before any refactoring begins"
+  - "Establishing the testing discipline a team will use as a system ages"
+anti_patterns:
+  - "Greenfield systems with modern tooling and existing test culture — Feathers is the brownfield specialist"
+  - "Systems where a full rewrite is genuinely the right call and incremental safety-net building would slow the work"
+  - "Pure architectural redesigns where the code isn't the constraint"
+sources:
+  - type: book
+    title: "Working Effectively with Legacy Code"
+    authors: ["Michael C. Feathers"]
+    year: 2004
+    url: "https://www.amazon.com/Working-Effectively-Legacy-Michael-Feathers/dp/0131177052"
+    isbn: "9780131177055"
+    methodology_covered:
+      - "Characterization tests — pin current behavior before touching legacy code"
+      - "Seam identification — find places where behavior can change without editing in place (preprocessor, link, object seams)"
+      - "Sprout method / sprout class — add new testable behavior adjacent to legacy code"
+      - "Wrap method / wrap class — change behavior by wrapping; original is untouched"
+      - "Legacy code definition — code without tests"
+  - type: website
+    title: "Michael Feathers blog"
+    authors: ["Michael Feathers"]
+    year: 2008
+    url: "https://michaelfeathers.silvrback.com/"
+    methodology_covered:
+      - "Ongoing writing on software design, legacy systems, and refactoring discipline"
+verification_status: verified
+description: "\"Legacy code is code without tests. Everything else is detail.\" [ref:1]"
+---
+
+# Michael Feathers
+
+## Signature
+
+*"Legacy code is code without tests. Everything else is detail."* [ref:1]
+
+Author of **Working Effectively with Legacy Code** (2004) [ref:1]. The bassclef voice on bringing old, test-less, or tightly-coupled code under control without a rewrite. Where Beck starts with TDD on a clean slate, Feathers starts with the code that actually exists in production today.
+
+## Core methods
+
+- **Characterization tests** — Write tests that describe what the code currently does, not what it should do. Before touching anything, pin the current behavior. These tests are the safety net that makes refactoring safe. Only after pinning do you change behavior — and changing behavior means writing a failing test first. [ref:1]
+- **Seam identification** — A seam is a place where you can change the program's behavior without editing in place. Seams come in three types: preprocessor seams (build-time), link seams (object-file substitution), and object seams (subclassing or interface injection). Finding seams is finding where you can insert a test double without rewriting the production code. [ref:1]
+- **Sprout method / sprout class** — When you need to add new behavior to a function that is too risky to touch, add the new behavior in a new method or class that you CAN test. Wire the new code into the legacy code with minimal contact. The sprout is independently testable; the legacy code is preserved. [ref:1]
+- **Wrap method / wrap class** — When you need to change a method's behavior, wrap it: create a new method (or class) that calls the original and adds or modifies behavior around it. The wrap is testable; the original is untouched. Like Decorator, but driven by safety rather than design. [ref:1]
+
+## When to channel this luminary
+
+When the codebase has real production code that lacks tests, or where tests exist but the dependencies are so tangled that changing anything is risky. Feathers dominates legacy system rescue: adding a feature to a 10-year-old module, extracting a service from a monolith, or incrementally stabilizing a system before a modernization effort begins. Pair with Fowler (refactoring catalog) once the safety net is in place.
+
+INSTEAD of channeling Feathers when the team is starting fresh: use Beck's TDD from the first line of production code. Feathers handles the before-state that TDD assumes away.
+
+## Stack translation
+
+In Next.js + Prisma + TypeScript:
+
+- **Characterization tests** — for a legacy API route, write integration tests against its actual behavior (inputs, outputs, side effects) before touching it. Use vitest + supertest or a test client. Pin the response shapes that downstream code depends on.
+- **Seam identification** — TypeScript interfaces are the primary seam type. A service function that imports Prisma directly has no seam; extract an interface and inject via constructor or parameter. The seam enables swapping a real DB client for a test double.
+- **Sprout method** — a 200-line server action that handles validation + database + notification: sprout the new validation logic into a standalone function tested in isolation. Wire it into the existing action with a single call. Ship both together.
+- **Wrap class** — a third-party SDK (BizBuySell, an email provider) with no seam: create a thin wrapper class that implements your own interface and delegates to the SDK. Tests use a test double; production uses the wrapper. Swap SDKs later without touching callers.
+
+## Anti-patterns it prevents
+
+- **Edit and pray** — making a change to legacy code without tests and hoping nothing breaks. Feathers's characterization tests create the safety net before any edit, making each change verifiable rather than hopeful.
+- **The big refactor** — attempting to redesign a legacy system comprehensively before adding tests. Feathers insists: tests come first, then refactoring. The comprehensive redesign without tests is just a different legacy system that happens to be new. [ref:1]
+- **Dependency grabbing** — adding a new dependency to a legacy class because it was "easier." Each new dependency reduces the seam surface and makes future testing harder. Feathers's discipline: find the seam, inject the dependency, preserve optionality.
+- **Sprout regression** — the new behavior works; the old behavior was accidentally changed. Characterization tests catch this: the old behavior is pinned; if any characterization test fails, something changed that was not intended to change.
+
+## Worked example
+
+For POA's legacy BizBuySell scraper module:
+
+The scraper function is 300 lines; it fetches, parses, writes to the database, and sends a Slack notification. No tests. Before any change:
+
+1. **Characterization test**: run the scraper against a recorded HTTP fixture; capture the database rows it writes and the Slack payload it sends. These are the characterization tests. Any change that alters these outputs is a signal, not a surprise.
+
+2. **Seam identification**: the database write is not injectable — it calls Prisma directly. INSTEAD: extract a `ScrapeResultWriter` interface; pass it as a parameter in tests. The seam now exists.
+
+3. **Sprout method**: the new requirement is deduplication before writing. INSTEAD of editing the 300-line function: sprout `deduplicateResults(incoming: ScrapeResult[], existing: ScrapeResult[]): ScrapeResult[]` — pure function, fully testable. Wire it into the legacy function with one line.
+
+4. **Verify**: characterization tests still pass (old behavior preserved). New unit tests cover the deduplication logic independently.
+
+## Sources
+
+- *Working Effectively with Legacy Code* — Feathers, Prentice Hall (2004) [ref:1]
+- michaelfeathers.silvrback.com — primary blog [ref:2]
+- "Getting Empirical About Refactoring" — Feathers, various conference talks
+
+## Related luminaries
+
+- **Martin Fowler** — Refactoring is the next step after Feathers's safety net is in place; Fowler's catalog assumes tests exist, Feathers builds the before-state.
+- **Kent Beck** — TDD is the end state Feathers helps teams reach incrementally.
+- **Robert C. Martin** — Clean Code principles are the target; Feathers handles the path from legacy reality to that target.
+- **Hunt & Thomas** — DRY and orthogonality are easier to maintain from the start; Feathers is the recovery discipline when they were not.
+
+## Substrate-as-system anchor (bassclef bet 27c, 2026-06-27)
+
+Feathers's "code without characterization tests is legacy code by definition" became the anchor citation for the bassclef substrate-as-system tenet (ADR-035). The bet 24c architect-review (2026-06-24) anchored on comprehension-side lenses (Brooks + Linus + Ishikawa + Deming) and missed the mechanism-fidelity class — "rule names mechanical enforcement that does not actually fire." The recursive Act phase (`architecture/audits/2026-06-27-audit-method-blind-spot.md`) named the lens-gap; Feathers's verification-side framing supplied the cure.
+
+The bet 27c foundation ships:
+- `standards/mechanism-fidelity.md` — 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/skills/architect-review/SKILL.md` — amendment makes Feathers + Beck + Saltzer-Schroeder verification-side primaries alongside Brooks + Linus comprehension-side primaries
+
+Feathers's brownfield-rescue framing applies recursively at the substrate level: bassclef's own substrate had legacy mechanism-fidelity claims (108 claims classified by WU-6 first audit; 76 non-CLEAN). The cure bet (Bet C-pre-2) drives them to zero via the same Feathers discipline — characterization tests, seam identification, sprout/wrap patterns — applied to substrate hooks rather than application code.
+
+The substrate as a system needs Feathers as much as application code does. This anchor citation reflects that.

package/substrate/.claude/luminaries/michael-nygard.md

@@ -0,0 +1,118 @@
+---
+tier: lite
+name: Michael Nygard
+slug: michael-nygard
+claimed_by: [architect]
+referenced_by_skills: [architect-review, decompose]
+primary_domain: architecture
+depth: full
+solves_problems_brownfield:
+  - "A single slow external API call hangs the entire application because the thread pool exhausts"
+  - "One failing service causes a cascade that takes down services with no direct dependency on it"
+  - "The application works fine locally and in staging but fails in production under real load patterns"
+  - "There is no defined behavior when an external integration is unavailable"
+solves_problems_greenfield:
+  - "Designing a service that will integrate with external systems of unknown reliability"
+  - "Planning the failure modes of a distributed system before any code is written"
+  - "Building a system that continues operating (in degraded mode) when individual integrations fail"
+  - "Establishing the production-readiness criteria a system must meet before going live"
+anti_patterns:
+  - "Single-process applications with no external integrations — stability patterns add overhead without value"
+  - "Batch systems that run to completion and exit — patterns designed for long-lived services"
+  - "Early-stage prototypes where production reliability is deliberately out of scope"
+sources:
+  - type: book
+    title: "Release It! Design and Deploy Production-Ready Software"
+    authors: ["Michael T. Nygard"]
+    year: 2018
+    url: "https://pragprog.com/titles/mnee2/release-it-second-edition/"
+    isbn: "9781680502398"
+    methodology_covered:
+      - "Circuit breaker — stateful wrapper with Closed/Open/Half-Open states; prevents cascading failure"
+      - "Bulkhead — partition resources by concern; failure in one partition cannot exhaust shared resources"
+      - "Timeout — every remote call must have connect + read timeout values"
+      - "Fail fast — reject requests immediately when a known failure condition exists"
+      - "Stability anti-patterns — cascading failure, blocked threads, self-denial, integration point failures"
+  - type: book
+    title: "Release It! Design and Deploy Production-Ready Software (1st edition)"
+    authors: ["Michael T. Nygard"]
+    year: 2007
+    url: "https://pragprog.com/titles/mnee/release-it/"
+    methodology_covered:
+      - "Original stability patterns catalog"
+  - type: blog_post
+    title: "Documenting Architecture Decisions"
+    authors: ["Michael Nygard"]
+    year: 2011
+    url: "https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions"
+    methodology_covered:
+      - "ADR (Architecture Decision Record) format — Title, Status, Context, Decision, Consequences"
+      - "Originated the ADR format; widely adopted across software organizations"
+verification_status: verified
+description: "\"Everything fails. Every remote call can hang. Every integration point is a liability. Design your system to be stable in the presence of failure, not to assume failure away.\"…"
+---
+
+# Michael Nygard
+
+## Signature
+
+*"Everything fails. Every remote call can hang. Every integration point is a liability. Design your system to be stable in the presence of failure, not to assume failure away."* [ref:1]
+
+Author of **Release It! Design and Deploy Production-Ready Software** (2nd ed 2018) [ref:1]. Coined the ADR (Architecture Decision Record) format in his 2011 blog post [ref:3]. The bassclef voice on production-grade software: the stability patterns that prevent cascading failures and the anti-patterns that cause them.
+
+## Core methods
+
+- **Circuit breaker** — A stateful wrapper around an integration point (external API, database, downstream service). Three states: Closed (normal operation), Open (fast-fail all calls without attempting contact), Half-Open (probe with one call to test recovery). When the failure rate exceeds a threshold, the circuit opens. Callers fail fast rather than hanging. After a timeout, one call is allowed through; if it succeeds, the circuit closes. [ref:1]
+- **Bulkhead** — Partition resources by concern so that failure in one partition cannot exhaust resources needed by another. Named after the ship bulkhead that prevents water ingress in one compartment from sinking the ship. In software: separate thread pools for different integrations, separate connection pools for different databases, separate queue workers for different job types. [ref:1]
+- **Timeout** — Every remote call must have a timeout. A call with no timeout can block a thread indefinitely. Two values needed: connect timeout (how long to wait for connection), read timeout (how long to wait for response). Timeouts must be tuned: too short creates unnecessary failures; too long creates unacceptable UX. [ref:1]
+- **Fail fast** — When a system knows it cannot fulfill a request (circuit open, connection pool exhausted, downstream service unavailable), it should fail immediately with a clear error rather than accepting the request and failing slowly. Fail fast enables callers to retry or redirect; slow failure degrades the entire system. [ref:1]
+
+## When to channel this luminary
+
+When the system will integrate with any external dependency (databases, third-party APIs, downstream services, message queues) and failure modes of those integrations need explicit design. Nygard dominates production readiness reviews, architecture reviews before launch, and any system that must remain partially operational when integrations fail. Pair with Newman (service decomposition that creates the integration boundaries Nygard's patterns protect), Hohpe (integration patterns at the messaging layer), and Brown (ADRs for recording stability-pattern decisions).
+
+INSTEAD of channeling Nygard for internal application logic: stability patterns are for integration points and external boundaries. Business logic, UI composition, and domain modeling are governed by Evans, Cockburn, and Cooper. Nygard's scope is the edges where your system meets systems you cannot control.
+
+## Stack translation
+
+In Next.js + Prisma + external APIs (BizBuySell, Anthropic, email providers):
+
+- **Circuit breaker** — wrap each external API client (BizBuySell scraper, Anthropic enrichment, email delivery) in a circuit breaker. When the API is unavailable or slow, the circuit opens; callers receive a fast failure and can queue the work for retry. Libraries: `opossum` (Node.js) or a simple state machine per integration.
+- **Bulkhead** — BullMQ workers for enrichment, for email, and for scraping use separate queues with separate concurrency limits. A spike in enrichment work cannot starve the email workers.
+- **Timeout** — every `fetch()` call to an external API uses `AbortSignal.timeout()`. Anthropic API calls that exceed 30s abort; enrichment jobs that exceed 60s fail and are retried. Prisma connection pool has an explicit pool timeout.
+- **Fail fast** — server actions that depend on an unavailable service return a clear `503` rather than hanging. The UI shows a retry state rather than a spinner.
+- **ADRs** — every stability-pattern decision is recorded in `architecture/decisions/`: "ADR-009: circuit breaker for BizBuySell API — context, decision, consequences." [ref:3]
+
+## Anti-patterns it prevents
+
+- **Cascading failure** — a slow external API causes thread pool exhaustion, which causes queue buildup, which causes memory pressure, which causes the entire application to fail. Circuit breaker and bulkhead prevent this: failures stay contained within their integration boundary. [ref:1]
+- **Blocked threads** — a database query or HTTP call with no timeout holds a thread indefinitely. Ten such calls block ten threads. The system accepts new requests it cannot service.
+  INSTEAD: set connect + read timeouts on every remote call; set a maximum wait in every queue consumer. Threads that time out release and become available for other work.
+- **Self-denial** — the application triggers its own overload: a scheduled job fans out thousands of API calls simultaneously, the API rate-limits, all calls fail, the job retries them immediately, the rate-limit worsens. Circuit breaker + exponential backoff prevent the retry cascade. [ref:1]
+- **Test harness gap** — the system was tested with a fast, reliable test double for every integration; production uses real integrations that are sometimes slow or unavailable. The failure paths were tested with mocks that never fail.
+  INSTEAD: include chaos tests (slow responses, connection drops, partial failures) in the integration test suite. The failure behavior must be verified, not assumed.
+
+## Worked example
+
+For POA's BizBuySell scraper integration:
+
+**The failure mode without patterns**: BizBuySell returns 503 for 5-10 minutes. The scraper worker holds ten open HTTP connections waiting for responses that will not arrive; the BullMQ queue backs up; the worker crashes; manual intervention is required.
+
+**With stability patterns**:
+1. **Timeout**: every BizBuySell fetch has a 10-second timeout. After 10 seconds, the call fails with a timeout error.
+2. **Circuit breaker**: after five consecutive timeouts within 60 seconds, the circuit opens. All subsequent scrape attempts fail fast. The circuit enters Half-Open after 60 seconds and allows one probe call through.
+3. **Bulkhead**: the scraper uses a separate BullMQ queue (max 5 concurrent workers) from the enrichment queue (max 10 workers). A BizBuySell outage fills the scraper queue but cannot starve enrichment workers.
+4. **ADR**: "ADR-010: BizBuySell API stability patterns — context: BizBuySell has 99.5% SLA (~43 hours downtime/year). We need scraping to be non-blocking during outages. Decision: circuit breaker with 5-failure threshold, 60s recovery. Consequences: scrape jobs may lag 60s during recovery; acceptable given the non-real-time nature of scrape data."
+
+## Sources
+
+- *Release It! Design and Deploy Production-Ready Software* — Nygard, Pragmatic Bookshelf (1st ed 2007, 2nd ed 2018) [ref:1][ref:2]
+- "Documenting Architecture Decisions" — Nygard, cognitect.com blog (2011) — original ADR proposal [ref:3]
+- thinkrelevance.com / cognitect.com — Nygard's primary writing venues (thinkrelevance.com was the predecessor domain to cognitect.com)
+
+## Related luminaries
+
+- **Sam Newman** — Microservices create the service boundaries where Nygard's stability patterns apply. Newman decomposes; Nygard hardens the resulting integration points.
+- **Gregor Hohpe** — EIP messaging patterns operate at the same integration boundaries. Hohpe's dead letter channels and Nygard's circuit breakers are complementary: messaging + stability.
+- **Simon Brown** — ADR format (Nygard's invention) is central to Brown's architecture communication approach. C4 documents the structure; ADRs record the stability decisions.
+- **Alistair Cockburn** — Hexagonal architecture creates explicit integration ports; Nygard's stability patterns wrap those ports.

package/substrate/.claude/luminaries/robert-c-martin.md

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

package/substrate/.claude/luminaries/saltzer-schroeder.md

@@ -0,0 +1,194 @@
+---
+tier: lite
+name: Jerome Saltzer & Michael Schroeder
+slug: saltzer-schroeder
+claimed_by: [architect, reviewer, builder, security-auditor]
+referenced_by_skills: [security-review, architect-review, pattern-review, diagnose]
+primary_domain: security
+depth: full
+sources:
+  - type: paper
+    title: "The Protection of Information in Computer Systems"
+    authors: ["Jerome H. Saltzer", "Michael D. Schroeder"]
+    year: 1975
+    edition: "Proceedings of the IEEE, vol. 63, no. 9, pp. 1278-1308"
+    url: "https://www.cs.virginia.edu/~evans/cs551/saltzer/"
+    methodology_covered:
+      - "Eight design principles for secure systems — economy of mechanism, fail-safe defaults, complete mediation, open design, separation of privilege, least privilege, least common mechanism, psychological acceptability"
+      - "The model of protected objects and authorized subjects; access matrix as the conceptual base"
+      - "Capability and ACL implementations of the access matrix"
+      - "Authentication vs authorization as separate concerns"
+  - type: paper
+    title: "Computer Security in the Real World"
+    authors: ["Butler W. Lampson"]
+    year: 2004
+    url: "https://www.microsoft.com/en-us/research/publication/computer-security-in-the-real-world/"
+    methodology_covered:
+      - "Modern reframing of the 1975 principles for distributed systems"
+      - "Gold standard — authenticate, authorize, audit — three legs every protection scheme requires"
+verification_status: verified
+description: "\"The principles are intended to guide the design of protection mechanisms..."
+---
+
+# Jerome Saltzer & Michael Schroeder
+
+## Signature
+
+*"The principles are intended to guide the design of protection mechanisms... they do not by themselves guarantee security, but they make insecurity easier to spot."*
+
+MIT computer scientists. Their 1975 paper articulated eight design principles for secure systems that remain SENTINEL_the_bassclef_reference fifty years later. The principles predate the public internet, predate the web, predate every modern threat model — and still hold because they are about the *shape* of protection mechanisms, not the threats they defend against. When a new attack class lands, the analysis tool that maps it back to which principle was violated is almost always Saltzer & Schroeder.
+
+The principles pair with later work: Lampson's "gold standard" (authenticate, authorize, audit) extends complete mediation; Anderson's *Security Engineering* puts every principle through industrial worked examples; OWASP's top-10 is a downstream symptom catalog whose root causes the principles name.
+
+## Discipline anchor
+
+**Designing protection mechanisms whose failure modes are visible at write-time.**
+
+Saltzer & Schroeder fire on every moment a substrate component touches access, authority, scope, default behavior, or trust boundaries.
+INSTEAD of waiting for an exploit to surface a missing check: the principles ask, at write-time, whether the mechanism's shape *makes* insecurity possible. Code that violates a principle is a defect even if no exploit has yet been demonstrated; code that conforms is a defense against threats the author did not foresee.
+
+This luminary anchors the security lens for:
+- `/security-review` — checks PRs against the 8 principles
+- `/architect-review` — system-level design reviews look for principle violations at architectural boundaries
+- `/pattern-review` — pattern selection (e.g., Decorator for logging, Strategy for auth) gets the principle lens
+
+For usability-first questions, route to `@luminary don-norman` (cognitive load of mode prompts).
+INSTEAD of citing Saltzer & Schroeder there: cite Norman. For API ergonomics, route to `@luminary john-ousterhout` (deep modules); for test mechanics, route to `@luminary kent-beck`.
+
+## The eight principles
+
+### 1. Economy of mechanism
+
+Keep the design as small and simple as possible. Protection mechanisms are inspected for correctness by reasoning about their behavior; the smaller and simpler the mechanism, the more reliable the inspection.
+
+Clever checks that require careful reasoning to verify carry inspection cost forever.
+INSTEAD of building one: build a check that any reviewer can read once and accept.
+
+**Bassclef example.** `.claude/rules/destructive-operations.md` instructs agents to pause before any state-modifying command. The rule is one page. A sophisticated heuristic engine would carry hidden states.
+INSTEAD: a short rule + a hard list of trigger verbs. Small mechanism; correctness inspectable in a single read.
+
+### 2. Fail-safe defaults
+
+Base access decisions on permission rather than exclusion. The default situation is *lack of access*; the protection scheme identifies conditions under which access is permitted.
+
+The shape "permit by default, deny on explicit refusal" produces a permanent risk surface — every new code path or branch type opens an unintended hole.
+INSTEAD: deny by default, permit on explicit authorization.
+
+**Bassclef example — the failure that motivated this luminary.** PR #1058's original auto-save design committed to whatever branch was active by default; the safety check was a list of refused branches (main, master, spike). Adding a new branch type (e.g., release/, hotfix/) silently worked — auto-save would commit there too. The default was "save" and the exceptions were "refuse." That violates fail-safe defaults.
+INSTEAD: auto-save should DENY by default; an explicit allowlist (chore/, scratch/, feature/, fix/) permits. A new branch type is denied until explicitly added. The author of the new branch is forced to make the decision visible.
+
+### 3. Complete mediation
+
+Every access to every object must be checked for authority. The mechanism must intercept every attempt without exception.
+
+A "check at the boundary and trust internal callers" shape produces a permanent silent-bypass surface — any internal path that skips the boundary skips the check.
+INSTEAD: check at every access. The cost of one extra check is small; the cost of one missed check can be the whole system.
+
+**Bassclef example.** `.claude/hooks/state-validate.sh` fires on every Edit / Write / MultiEdit to a state-spine path. Validating only at "official" entry points leaves alternative tool paths unmediated.
+INSTEAD: the hook intercepts every write regardless of which tool made it. An agent that writes via a less-common tool path does not slip past the validator.
+
+### 4. Open design
+
+The protection mechanism's design should not depend on attacker ignorance of mechanism. Security through obscurity is weak; security through inspectable, public, well-reasoned design is strong.
+
+"They will not know about this hidden flag" is a fragile assumption that erodes on the first leak.
+INSTEAD: publish the flag, document the threat model, and rely on the mechanism (e.g., cryptographic key separation) for the actual protection.
+
+**Bassclef example.** Bassclef's hooks, rules, and skills are all readable in the repo. Hiding which checks fire when would produce ambiguity about safety state.
+INSTEAD: hooks announce themselves in chronicle, in BLOCKED banners, in trace logs. An agent that knows every hook's trigger condition cannot evade them by accident; the safety is in the hook firing on the trigger, not in the trigger being secret.
+
+### 5. Separation of privilege
+
+A protection mechanism that requires two independent checks is stronger than one that requires a single check. (The classic two-key safe analog.)
+
+A single-signature unlock shape produces a single point of compromise.
+INSTEAD: require operator confirmation AND a CI passing AND a manual approval gate.
+
+**Bassclef example.** Production deploys require GitHub Environment with `required_reviewers` (per `.claude/rules/manual-prod-approval.md`) AND the deploy-guard.sh hook firing AND `gh pr merge` from an operator account. Three independent checks. A single compromise (e.g., agent's GitHub token) cannot deploy to production by itself.
+
+### 6. Least privilege
+
+Every program and every user of the system should operate using the least set of privileges necessary to complete the job.
+
+Granting "read + write + delete + admin" because it is easier produces a permanent blast-radius surface.
+INSTEAD: grant only what the specific operation requires. A read-only operation gets a read-only credential. A write to one path gets write access to that path only.
+
+**Bassclef example — the failure that motivated this luminary.** PR #1058's original auto-save design granted auto-save the privilege to commit to *every* branch the agent visited. Auto-save needs the privilege to checkpoint work-in-progress on chore + scratch branches.
+INSTEAD: scope auto-save to the branches that actually need it; deny everywhere else.
+
+Bassclef token discipline (per memory `feedback_never_paste_tokens_in_chat`) applies the same principle.
+INSTEAD of granting broad-scope tokens for narrow-scope work: use fine-grained PATs with minimal target-repo scope rather than full-org admin tokens.
+
+### 7. Least common mechanism
+
+Minimize the amount of mechanism shared by multiple users (or programs). Shared mechanisms are potential information paths and attack surfaces.
+
+"One big config file for all secrets" produces cross-purpose attack surface.
+INSTEAD: separate per-purpose stores. For multi-tenant systems: isolate per-tenant where the cost is reasonable rather than running one daemon for every tenant.
+
+**Bassclef example.** `state/markers/temperance/` writes per-branch marker files instead of a single shared marker. A single global "temperance fired this session" flag would carry cross-scope trust.
+INSTEAD: per-branch markers isolate the trust decision to its scope. A marker on branch A cannot grant temperance approval to branch B.
+
+### 8. Psychological acceptability
+
+Human interface to the protection mechanism must be designed for ease of use. If users find the mechanism annoying or confusing, they will work around it.
+
+"Secure but unusable" produces operator workarounds — the most cryptographically perfect protection scheme is worthless if operators bypass it.
+INSTEAD: secure AND usable.
+
+**Bassclef example.** The `SKIP_*=1` override pattern across bassclef's hooks (e.g., `SKIP_TEMPERANCE=1`, `SKIP_DIAGNOSE=1`) provides an escape valve for cases where the gate is wrong. "Hard block with no override" produces operators who disable hooks entirely.
+INSTEAD: hard block with a logged override. Operators bypass per-call when they understand the trade-off, and the trace surfaces the bypass.
+
+Override usage is signal, not failure.
+INSTEAD of treating override usage as failure: track override frequency. If a hook is overridden >10% of the time, the hook is mistargeted — psychological acceptability is failing and the hook needs redesign.
+
+## Stack translation — applying the principles to bassclef's bash hooks
+
+Bassclef's hooks are bash scripts under `.claude/hooks/*.sh`. The eight principles map directly to bash hook authoring:
+
+| Principle | Bash hook discipline |
+|---|---|
+| **Economy of mechanism** | Hook body ≤200 lines for inspectability; helpers in `lib/*.sh` so the hook reads top-to-bottom |
+| **Fail-safe defaults** | `set -euo pipefail` at top of every hook — undefined variables and pipe failures FAIL rather than passing silently |
+| **Complete mediation** | PreToolUse hooks fire on every matching tool call, not "first call per session" |
+| **Open design** | Hook trigger conditions documented in `docs/hooks-index.md`; BLOCKED banners name the path the hook reads |
+| **Separation of privilege** | Destructive hooks (e.g., deploy-guard.sh) check operator confirmation AND state-spine signal AND env var — three independent conditions |
+| **Least privilege** | Hooks `cd` to repo root only when needed; `git` commands scope to specific paths; file modes scoped to minimum-needed (644 for data, 755 for executables) |
+| **Least common mechanism** | Per-hook test files (`.claude/hooks/tests/<name>.test.sh`); per-hook trace context; no shared global state between hooks |
+| **Psychological acceptability** | `SKIP_<HOOK>=1` per-call override; logged via trace-helper; operator-bypass is per-call, surface-visible |
+
+This translation block is the substrate-internal reference for Phase X-3 (`standards/bash-hook-safety.md` + `.claude/rules/defensive-bash.md`). The standard codifies the discipline; this luminary names the principles the discipline implements.
+
+## When to cite this luminary
+
+Cite `@luminary saltzer-schroeder` when:
+
+- **Reviewing protection mechanisms** (`/security-review`, `/architect-review`) — does this default deny or permit? Is mediation complete? Is privilege minimal?
+- **Designing default behaviors** — particularly when a default determines whether dangerous-by-default or safe-by-default applies (the auto-save case is the SENTINEL_bassclef_example)
+- **Adding override paths** — does the override get logged? Is the trade-off named? Is the override scope per-call or per-session?
+- **Authoring hooks** — bash hook safety (Phase X-3) instantiates the principles; the luminary names what the hook discipline is implementing
+- **Diagnosing security regressions** — `/diagnose` reaches for this luminary when the failure surface involves trust boundaries, default behavior, scope creep, or missed checks
+- **Designing tenant isolation** — least common mechanism + least privilege apply to multi-tenant systems directly
+
+For threat-model authoring (analyzing what attackers can do given the protection mechanisms), route to Schneier — separate luminary candidate; Phase X+ follow-on.
+INSTEAD of stretching Saltzer & Schroeder into threat modeling: cite Schneier when the catalog lands.
+
+For cryptographic primitive selection — out of bassclef's anchor catalog today.
+
+## Composes with
+
+- **John Ousterhout** — Deep modules + define errors out of existence overlap with economy-of-mechanism + complete-mediation. Ousterhout's design judgment frames WHEN to apply Saltzer & Schroeder.
+- **Kent Beck** — Tests for protection mechanisms verify the default behavior matches the design intent. A test that asserts "auto-save refuses main" is the mechanical guarantee fail-safe-defaults specifies.
+- **Don Norman** — Psychological acceptability is the same surface as Norman's cognitive-load principle for system design. The operator-facing behavior of a security mechanism IS its UX.
+  INSTEAD of treating them as separate concerns: Norman's lens applies directly to override design + BLOCKED banner phrasing + hook-error message clarity.
+- **Edward Tufte** — When protection mechanisms produce telemetry (e.g., trace logs of overrides), Tufte's information-design discipline anchors how that telemetry surfaces to operators.
+
+## Refs
+
+- bassclef#1058 — concrete failure (auto-save scope hole) that surfaced the need for this luminary at the substrate
+- bassclef#1060 / PR #1061 — temperance mechanical block (sibling discipline-becomes-mechanical pattern; complete-mediation in action)
+- `.claude/rules/destructive-operations.md` — agent self-assessment rule that this luminary anchors
+- `.claude/rules/security.md` — existing rule scoped to `.ts/.tsx/.json/.env/Dockerfile`; bash extension is Phase X-3
+- `docs/iteration-bets/2026-06-17a-secure-coding-foundations-longrun.md` Phase X scope
+- `standards/code-safety-principles.md` (Phase X-2) — language-agnostic principles document this luminary anchors
+- `standards/bash-hook-safety.md` (Phase X-3) — bash-specific instantiation of the stack-translation table above