@thebassclef/lite 0.1.3 → 1.0.1

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

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

@@ -1,194 +0,0 @@
----
-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/substrate/.claude/luminaries/sophia-prater.md

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