@thebassclef/lite 1.0.3 → 1.1.0

package/dist/lite/.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

package/dist/lite/.claude/luminaries/sophia-prater.md

@@ -0,0 +1,193 @@
+---
+tier: lite
+name: Sophia V. Prater
+slug: sophia-prater
+claimed_by: [designer]
+referenced_by_skills: [ia-model, prototype-variants, interaction-design]
+primary_domain: ux
+depth: full
+verification_status: verified
+sources:
+  - type: article
+    title: "Object-Oriented UX"
+    authors: ["Sophia V. Prater"]
+    year: 2016
+    url: "https://alistapart.com/article/object-oriented-ux/"
+    methodology_covered: ["OOUX methodology introduction", "objects vs tasks framing", "object-first IA"]
+  - type: website
+    title: "ooux.com — Object-Oriented UX"
+    authors: ["Sophia V. Prater"]
+    url: "https://ooux.com"
+    methodology_covered: ["ORCA process (Objects/Relationships/CTAs/Attributes)", "OOUX certification and training"]
+  - type: course
+    title: "OOUX Certified Course"
+    authors: ["Sophia V. Prater"]
+    url: "https://ooux.com/learn"
+    methodology_covered: ["Full ORCA process methodology", "object inventory technique", "system model alignment"]
+solves_problems_brownfield:
+  - "Existing multi-entity app where users mentally model objects but UI exposes screens or processes"
+  - "Same entity appears in many flows but isn't unified as a concept"
+  - "Navigation doesn't reflect the domain's noun structure"
+solves_problems_greenfield:
+  - "Designing a CRUD-heavy or domain-rich product where entity relationships should drive the UI"
+  - "Planning IA from the domain model first, not from process flows"
+  - "Building an app where users will mentally manipulate objects and the UI should match from day one"
+  - "Designing a multi-entity product where consistent entity expression matters across surfaces"
+anti_patterns:
+  - "Process-driven workflows where actions matter more than objects"
+  - "Single-entity tools or marketing surfaces"
+description: "\"Objects first, then actions. Never the reverse.\""
+---
+
+# Sophia V. Prater
+
+## Signature
+
+*"Objects first, then actions. Never the reverse."*
+
+The interface should mirror the user's mental model of the domain — not
+the database schema that powers it. Complexity in data-heavy products is
+a symptom of letting system structure leak into the UI. Structure the
+content first, rigorously, and the interface follows.
+
+## Core methods
+
+- **ORCA process** — Objects, Relationships, CTAs, Attributes. The four-step
+  method for structuring messy domains before any wireframe. Apply when a
+  spec has 5+ entities with non-trivial relationships or when a domain
+  has regulatory/data-density pressure. [ref:2]
+
+- **Mental model vs system model** — Before accepting any information
+  architecture, ask: "Does this match how the *user* thinks about this
+  domain, or how the *database* stores it?" They are rarely the same.
+  Schema-mirror UIs pass code review but fail in the wild. [ref:1]
+
+- **Progressive disclosure for data density** — Stratify information by
+  user journey stage. Data novices should see the core "heavy" nouns at
+  first glance; power users get the full attribute surface on demand.
+  Visual weight encodes priority; collapsed sections encode optionality.
+
+- **Componentized content** — Build a structured object model first, then
+  derive UI components from objects (not from feature lists). Each object
+  gets a detail view; relationships drive navigation; attributes map to
+  field-level components. This is what makes OOUX modular under scale.
+
+## When to channel this luminary
+
+When the domain is **data-heavy and relationally complex** — multiple
+entities with non-trivial relationships, regulatory or compliance density,
+or a user population that spans novice-to-power-user ranges. Prater
+dominates when the biggest risk is that the interface will mirror the
+schema instead of the user's mental model. Think: deal pipelines,
+compliance dashboards, clinical records, logistics systems, financial
+portfolios.
+
+Do NOT channel Prater for simple CRUD apps, single-entity workflows, or
+consumer-facing surfaces where entity structure is irrelevant to the user.
+
+## Stack translation
+
+In our Next.js + Prisma + React stack, ORCA maps concretely:
+
+- **Objects** → Prisma models (Deal, Broker, Seller, Buyer, Listing).
+  Prater's object inventory is essentially the domain-driven subset of
+  the Prisma schema.
+- **Relationships** → Prisma relations (`@relation`) and `/ia-model`
+  entity diagrams. Every relation is a potential navigation path.
+- **CTAs** → server actions (`src/app/actions/`) + route handlers
+  (`src/app/api/`). Each CTA is an action the user can take on an object.
+- **Attributes** → field-level visibility rules. Not every attribute
+  belongs on every screen — progressive disclosure means the detail view
+  shows priority attributes first, secondary attributes behind expansion.
+
+The IA step in `/ia-model` IS Prater's ORCA. When we say "entity inventory
++ task flows," we're describing ORCA without naming it. The `/decompose`
+skill inherits this: its Responsibility Matrix is downstream of ORCA's
+object inventory.
+
+## Anti-patterns it prevents
+
+- **Schema-mirror UI** — The biggest data-heavy failure: the UI exposes
+  join tables, foreign keys, and normalization artifacts as navigation.
+  Users see "Deal-Broker Junction Records" instead of "Deals this broker
+  touched." Prater's mental-vs-system-model check catches this.
+
+- **Attribute flood** — Detail views that dump every field without
+  hierarchy. 47 fields in a grid, no prioritization, no progressive
+  disclosure. Users scan and bounce. Prater's visual-weight layering
+  forces a priority decision per field.
+
+- **Feature-first navigation** — Primary nav organized by feature ("Deals,"
+  "Search," "Import," "Reports") instead of by object ("Deals, Brokers,
+  Sellers"). Features multiply and the nav collapses under its own
+  weight. Object-first nav scales with the domain, not the feature set.
+
+- **Task-flow-only IA** — Designing only for the happy path, ignoring
+  that users need to browse, compare, and navigate across objects. Prater
+  insists on both: task flows AND object structure. Task flows without
+  object structure produce funnel interfaces that break on sideways use.
+
+- **Monolithic list-detail pattern** — Every entity gets the same "list
+  → detail → edit" treatment regardless of its role in the mental model.
+  Prater's componentized content says: the list-detail pattern is one of
+  several, not the default. Some objects are better as graphs, timelines,
+  or maps.
+
+## Worked example
+
+For a POA deal pipeline (our primary Five Pandas surface), applying Prater
+looks like this:
+
+1. **Objects inventory**: Deal, Broker, Seller, Buyer, Listing Source
+   (BizBuySell, LoopNet, direct), Stage (Discovery, Valuation, LOI, etc.),
+   Note, Attachment. Not tables. Not features. Nouns.
+
+2. **Relationships**: A Deal has one Seller, zero-or-more Brokers, one
+   Source, passes through ordered Stages, accumulates Notes and
+   Attachments. Each relation is a potential nav path the user might
+   traverse: "show me everything this broker touched," "show me all deals
+   in LOI stage," "show me all deals from BizBuySell this month."
+
+3. **CTAs per object**: Deal has Advance-Stage, Log-Note, Attach-Document,
+   Reassign-Broker, Archive. Broker has Log-Interaction, Flag-Inactive.
+   These become server actions, not buttons-on-a-page.
+
+4. **Attributes with priority**: Deal's detail view shows Stage, Seller,
+   Source, Score above the fold. Financial attributes (asking price, SDE
+   multiple, cash required) in the next tier. Enrichment data (real
+   estate, relocatability, expansion potential) collapsed until the user
+   expands it. Audit fields (created_at, updated_at, last_touched_by)
+   footer-level.
+
+What Prater would NOT produce: a left-nav with "Database / Deal-Broker
+Relationships" exposed. A detail view dumping all 47 fields in a grid.
+A "features" top-level nav. These are all schema-mirror tells.
+
+## Sources
+
+- **ooux.com** — primary site, ORCA method articulated
+- **"Object-Oriented UX"** — A List Apart article (2016) introducing OOUX
+  to a mainstream UX audience
+- **"A UX Designer's Guide to OOUX"** — Medium essay series by Prater
+- **OOUX Strategist certification course** — Prater's structured
+  curriculum; the most complete treatment of ORCA as a teachable method
+- **Rosenfeld Media OOUX book** — forthcoming; will be canonical reference
+  when published
+
+## Related luminaries
+
+- **Peter Morville & Louis Rosenfeld** — Findability and IA foundations;
+  Prater's work builds on their "Information Architecture for the Web"
+  tradition with a sharper object-orientation focus.
+- **Alan Cooper** — Goal-Directed Design shares Prater's "start from
+  user, not system" orientation; Cooper frames it as goals, Prater as
+  objects. Complementary, not conflicting.
+- **Don Norman** — Affordances and signifiers operate at the interaction
+  level; Prater operates at the structural level above. Use both: Prater
+  for IA, Norman for the interaction patterns within each screen.
+- **Richard Saul Wurman** — LATCH (Location, Alphabet, Time, Category,
+  Hierarchy) is a pre-OOUX attempt at content structuring. Prater's ORCA
+  is a sharper descendant for relational domains.
+- **Jenifer Tidwell** — Pattern library sits downstream of OOUX: once
+  objects are identified, Tidwell's patterns inform how each object's
+  views are composed.

package/dist/lite/.claude/luminaries/stephen-toulmin.md

@@ -0,0 +1,131 @@
+---
+tier: lite
+name: Stephen Toulmin
+slug: stephen-toulmin
+claimed_by: [architect, reviewer, closer]
+referenced_by_skills: [state-a-problem, diagnose, architect-review, promote]
+primary_domain: philosophy
+depth: full
+sources:
+  - type: book
+    title: "The Uses of Argument"
+    authors: ["Stephen E. Toulmin"]
+    year: 1958
+    url: "https://www.cambridge.org/core/books/uses-of-argument/26CF801BC12004587B66778297D5567C"
+    isbn: "9780521534833"
+    methodology_covered:
+      - "Six-part argument model — claim, data, warrant, backing, qualifier, rebuttal"
+      - "Field-invariant logical shape distinct from field-dependent standards"
+      - "Practical reasoning over formal deduction as the actual shape of argument"
+  - type: book
+    title: "An Introduction to Reasoning"
+    authors: ["Stephen Toulmin", "Richard Rieke", "Allan Janik"]
+    year: 1984
+    url: "https://www.routledge.com/An-Introduction-to-Reasoning/Toulmin-Rieke-Janik/p/book/9780024211606"
+    isbn: "9780024211606"
+    methodology_covered:
+      - "Applied Toulmin model across disciplines (law, science, ethics, management)"
+      - "Argument analysis as diagnostic tool for weak reasoning"
+      - "Field-invariant discipline extended with field-dependent examples"
+  - type: book
+    title: "Human Understanding: The Collective Use and Evolution of Concepts"
+    authors: ["Stephen Toulmin"]
+    year: 1972
+    url: "https://press.princeton.edu/books/paperback/9780691019963/human-understanding"
+    isbn: "9780691019963"
+    methodology_covered:
+      - "Rationality as historical practice, not fixed standard"
+      - "Concepts evolve inside disciplines that judge their fitness"
+      - "Substrate discipline as living evolving practice"
+verification_status: verified
+description: "\"An argument is a whole organism. Take out one part and the rest collapses.\""
+---
+
+# Stephen Toulmin
+
+## Signature
+
+*"An argument is a whole organism. Take out one part and the rest collapses."*
+
+British philosopher (1922-2009). Author of *The Uses of Argument* (Cambridge, 1958) — the book that gave rhetoric, law, science, and now agent substrate a shared vocabulary for what an argument actually IS. The bassclef voice on assertion discipline, claim shape, and argument structure at the reasoning boundary.
+
+## Core methods
+
+- **The six-part argument** — every real argument has: **claim** (what you assert), **data** (the source that grounds it), **warrant** (the bridge from data to claim), **backing** (why the warrant holds in this field), **qualifier** (how strong the claim is — "usually," "in most cases," "with 95% confidence"), and **rebuttal** (the conditions under which the claim would fail).
+- **Field-invariant vs field-dependent** — the shape (claim/data/warrant) holds across every field. The evidence standards inside each cell vary by field. Physics accepts different data than law; the shape is the same.
+- **Practical reasoning over formal deduction** — real reasoning is about warrant-quality, not syllogism-completeness. A proof from clean premises rarely captures the actual work of a claim.
+- **Argument as diagnostic** — when a claim feels wrong, decompose it into the six parts. The weak part surfaces immediately. Usually it is the warrant.
+
+## When to channel this luminary
+
+When the primary risk is unverified assertions shipping to operator or adopters. Toulmin dominates for audit authoring, cure recommendations, root-cause diagnoses, ADR bodies, and any operator-facing prose where the agent makes a claim. Pair with Popper (falsifiability sharpens the rebuttal cell) and Peirce (abductive reasoning fills the alternative-consideration gap Toulmin leaves implicit).
+
+Pass-through cases (Toulmin adds no value):
+
+- Single-sentence status updates. INSTEAD of applying the six-part shape: preserve the update; it carries no claim to decompose.
+- Tool-output relay (test output, git output). INSTEAD of applying the six-part shape: preserve the raw output; the tool IS the source.
+- Operator-quoted text preserved verbatim. INSTEAD of applying the six-part shape: preserve the quote; attribution IS the citation.
+
+## Stack translation
+
+In bassclef substrate work:
+
+- **Audit finding** → claim (the finding) + data (source path with line reference) + warrant (why the source proves the finding) + qualifier (severity + observation count) + rebuttal (what would falsify).
+- **Cure recommendation** → claim (the cure) + data (source chronicle + line) + warrant (why the source shows the class needs this cure) + rebuttal (alternative cures that fit the same data).
+- **Root-cause diagnosis** → claim (the cause) + data (repro + logs) + warrant (why the repro proves causation, not correlation) + qualifier (confidence + N repros).
+- **Turn estimate** → claim (N turns) + data (prior WU turn counts) + warrant (why those WUs match this scope) + qualifier (range not point).
+- **Severity rank** → claim (HIGH/MEDIUM/LOW) + data (audit criteria the rank comes from) + warrant (why this instance meets those criteria).
+
+## Anti-patterns it prevents
+
+- **Assertion without cited source** — "The hook is broken." No data cell. Falls apart on inspection.
+
+  INSTEAD: state the hook's file path + the observation that shows it breaks + why the observation supports the claim.
+
+- **Assertion pointing at a source but no warrant** — "Per chronicle 2026-06-30." What in the chronicle? Which line? Which claim does it support?
+
+  INSTEAD: quote the chronicle line + state why the line supports the claim.
+
+- **Severity without observation criteria** — "This is HIGH-severity" with no data cell naming the threshold and no warrant naming the measurement.
+
+  INSTEAD: state the threshold (from an audit doc or standard) + the measurement (from the repro) + why the measurement exceeds the threshold.
+
+- **Root cause attribution without qualifier** — "The cause is X" as absolute, when the actual claim is "X fits the data best but two alternatives remain unfalsified."
+
+  INSTEAD: state the qualifier (confidence + N observations) + name the remaining alternatives.
+
+- **Turn estimate without data cell** — a bare number, no prior evidence, no warrant. This is the R8 pattern named at bassclef#559.
+
+  INSTEAD: state the prior WU turn counts the estimate anchors on + why those WUs match this scope's shape.
+
+## Worked example
+
+For an audit finding about a hook that appears broken:
+
+Toulmin's shape:
+
+- **Claim**: The hook `turn-prose-kiss-check.sh` silent-fails under operator install.
+- **Data**: Chronicle `2026-06-27-operator-install-kiss-defect.md` L23; reproduced with `HOME_OVERRIDE=/nowhere echo '{}' | bash .claude/hooks/turn-prose-kiss-check.sh` → exits 0 with no stderr.
+- **Warrant**: The hook sources `standards/bassclef-internal-jargon.md` via SCRIPT_DIR/../../ path. Under operator install, that path does not exist. The hook's `if` check for path existence exits silent.
+- **Qualifier**: HIGH severity. Reproduced across 3 sessions.
+- **Rebuttal**: Falsified if the hook is expected to silent-fail under operator install by design. Checked ADR-035 — install-class: dual commits to firing under both layouts. Falsification test fails; claim holds.
+
+Without Toulmin: "The kiss hook is broken." Six words, no evidence, easy to dismiss or accept without inspection. INSTEAD: state the six cells; each cell earns its place.
+
+## Sources
+
+- *The Uses of Argument* — Toulmin, Cambridge University Press (1958; 2nd ed 2003)
+- *An Introduction to Reasoning* — Toulmin, Rieke, Janik, Macmillan (1979; 2nd ed 1984)
+- *Human Understanding: The Collective Use and Evolution of Concepts* — Toulmin, Princeton University Press (1972)
+- *Return to Reason* — Toulmin, Harvard University Press (2001)
+- Stanford Encyclopedia of Philosophy: entry on Toulmin — plato.stanford.edu/entries/toulmin/
+
+## Related luminaries
+
+- **Karl Popper** — Popper's falsifiability sharpens the rebuttal cell of Toulmin's model. Toulmin gives the shape; Popper names what would break the claim. Both ship in bet 2026-07-01b WU-2.
+- **Charles Sanders Peirce** — Peirce's abductive reasoning fills the alternative-consideration gap Toulmin leaves implicit. A well-shaped Toulmin argument names ONE claim; Peirce insists on naming multiple candidates before committing. Both ship in bet 2026-07-01b WU-2.
+- **Andrej Karpathy** — Karpathy's context engineering treats the model's context window as finite RAM. Toulmin's argument model is what fills that RAM with claim shape when the operator asks the agent to reason. Together they close the reasoning-boundary discipline surface.
+- **Michael Feathers** — Feathers' characterization tests are the data cell for the substrate-as-system tenet. Toulmin's warrant becomes "the characterization test proves the mechanism ships the claim."
+- **Kent Beck** — Beck's red-green-refactor cycle IS a Toulmin argument at the code layer. Red is the falsifiable claim; green is the passing data; refactor sharpens the warrant.
+
+Anchors `.claude/rules/assert-only-after-verify.md` alongside Popper + Peirce. Primary luminary for `/state-a-problem` skill in Problem-section drafting.