@thebassclef/lite 0.0.1 → 0.1.0

package/substrate/.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/substrate/.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.

package/substrate/.claude/rules/artifact-ingestion.md

@@ -0,0 +1,179 @@
+---
+tier: lite
+description: Before producing any substantive generative output (canvas, prototype, spec, proposal, rubric, ADR, variant), the agent MUST read the referenced artifacts and enumerate them in…
+---
+
+# Artifact Ingestion — Read Before You Produce
+
+Before producing any substantive generative output (canvas, prototype,
+spec, proposal, rubric, ADR, variant), the agent MUST read the
+referenced artifacts and enumerate them in the output.
+
+"Pattern-matched on generic X" is a failure, not a shortcut.
+
+## When this rule fires
+
+Fires on any of the following output types when they reference an
+existing artifact the agent could have read:
+
+- **Canvas / spec / ADR** drafts referencing issues, prior canvases,
+  chronicles, or memory entries
+- **Prototype or variant** builds referencing prior prototypes,
+  design tokens, or luminary files
+- **Iteration proposals** referencing active iteration goals (must
+  enumerate every workstream — see `blocked-items.md` for same
+  anti-skim shape)
+- **Gate evaluations** (`/verify`, `/architect-review`) referencing
+  spec or ADR acceptance criteria
+- **Skills producing derivative content** (`/value-prop` from a ticket,
+  `/decompose` from a spec) — must read source, not just the title
+
+## Required format: "Sources read" block
+
+Every output subject to this rule MUST begin with (or include) a
+block like:
+
+```
+## Sources read
+
+- [path or reference]:[line range if applicable] — [what I took from it]
+- …
+
+## What I'm NOT reading (with reason)
+
+- [path] — [deliberate exclusion reason, e.g. out of scope, stale]
+```
+
+If no artifacts were read: state "No prior artifacts; producing from
+scratch because [reason]." Silence is not exemption.
+
+## Anti-patterns that fire this rule
+
+Direct quotes from recent failures:
+
+- "I pattern-matched on generic card UI" — built prototype without
+  reading existing Norman/Prater variant files (2026-04-13)
+- "I didn't study the existing variants before building" — same
+  incident
+- Producing a canvas recommending vendor X without reading memory
+  that flagged vendor Y for evaluation (2026-04-13)
+- Proposing iteration scope covering 1 of 4 workstreams without
+  enumerating the ones being dropped (2026-04-12)
+- Skipping BLOCKED hook output in favor of answering the user's
+  direct question (2026-04-12; third instance in six weeks)
+
+Shape across all four: **training priors substituted for explicit
+artifacts the operator had already staged.**
+
+## Verification cue for the agent (self-check before output)
+
+Before producing the output, ask:
+
+1. Did I Read every file path referenced in the prompt or parent
+   artifact?
+2. Did I enumerate every workstream / variant / section of the parent
+   artifact, including the ones I'm deferring?
+3. Did I check memory for prior evaluations, flagged alternatives, or
+   deferred decisions relevant to this output?
+4. Did I consult the active luminary files for guidance (where the
+   skill or agent definition lists luminaries)?
+
+If any answer is "no," stop. Read first. Then produce.
+
+## Session-start branch — read recent strategic artifacts before substantive work
+
+Before any branch creation OR substantive PR work in a session, the
+agent MUST Read every strategic artifact (canvas / spec / iteration-bet
+/ ADR / decomposition / roadmap) authored OR substantively modified
+within the last 7 days.
+
+**Why this branch exists.** The production-time gate (PreToolUse on
+Write/Edit per `artifact-ingestion-gate.sh`) catches artifact-ingestion
+failures at WRITE time. It does NOT catch the case where an agent runs
+`/sprint`, sees a recently-merged commit in `git log`, treats it as
+background context, and proceeds with substantive work for hours
+before reading the artifact itself. That failure mode was demonstrated
+2026-04-26: 5h triage session opened against canvas-v3 commit listed
+in `/sprint` output without anyone reading the canvas; the canvas
+explicitly named the triage fixes as transition methodology being
+superseded by spine v0. Operator caught it; the cost was 4 PRs of
+short-lifetime work.
+
+**Mechanism.** `.claude/hooks/session-reflection.d/70-recent-strategic-artifacts.sh`
+fires at SessionStart, runs `git log --since=7-days --diff-filter=AM`
+restricted to the strategic-artifact path matcher, emits a `🛑 BLOCKED`
+block listing each path + commit date when results are non-empty.
+Window is configurable via `RECENT_STRATEGIC_DAYS` env (default 7);
+0 disables for that session.
+
+**Resolution per `.claude/rules/blocked-items.md`.** The agent MUST
+either Read each listed artifact this session OR explicitly defer
+("skip recent-artifacts this session"). Silence is not deferral. The
+default is Read. The marker pattern from sibling production gates is
+NOT used here because session-reflection.d/* fragments only fire once
+per SessionStart by design — re-fire suppression is unnecessary.
+
+**Override.** `SKIP_RECENT_ARTIFACTS=1 <command>` (logged to trace) or
+operator-explicit deferral statement.
+
+**Strategic-artifact path matcher** (mirrors production-gate matcher
+minus prototypes which have their own approval workflow):
+
+- `strategy/canvases/*.md`
+- `docs/specs/*.md`
+- `docs/iteration-bets/*.md`
+- `architecture/decisions/ADR-*.md`
+- `docs/decompositions/*.md`
+- `docs/roadmaps/*.md`
+
+Prototypes are deliberately excluded — `prototype-workflow.md` and
+`prototype-production-coupling.md` cover that surface separately.
+
+## Why this rule exists
+
+Operator was QA-ing agent laziness four times in six hours on
+2026-04-12/13 across two agents. Substrate credibility depends on
+agents doing the homework before producing the output. Without this
+rule, every generated artifact requires operator spot-check against
+sources — which defeats the automation thesis.
+
+This rule is enforced by `.claude/hooks/artifact-ingestion-gate.sh`
+(bassclef, 2026-04-13). The hook fires on PreToolUse for Write/Edit
+to matcher paths (canvas, spec, ADR, iteration-bet, prototype html,
+decomposition) and blocks when no "## Sources read" block exists.
+
+The rule stands regardless of hook availability — it belongs in every
+session's loaded context, not in an optional gate. The hook is the
+mechanical backstop; the rule is the reasoning.
+
+## Consumer-repo installation
+
+Bassclef-sync symlinks the hook file into consumer repos automatically.
+To wire it as a gate, add to the consumer repo's `.claude/settings.json`
+under `hooks.PreToolUse`:
+
+```json
+{
+  "matcher": "Edit|Write",
+  "hooks": [
+    { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/artifact-ingestion-gate.sh" }
+  ]
+}
+```
+
+(If `Edit|Write` matcher already exists with other hooks, append this
+command to its `hooks` array — don't duplicate the matcher entry.)
+
+Override: `SKIP_ARTIFACT_INGESTION=1 <tool-call>` (logged to trace).
+
+## Relationship to other rules
+
+- `blocked-items.md` — same anti-skim shape; blocked items are a
+  specific case of artifact-ingestion failure (skipping hook-surfaced
+  artifacts)
+- `oo-ad-entry-point.md` — analogous pattern for /decompose
+  (evidence required before Construction)
+- `sdlc-gates.md` — pre-build gates; artifact ingestion is the gate
+  *before* temperance and diagnosis
+- `substrate-config-schema.md` — reading `substrate.config.md` is
+  itself an artifact-ingestion obligation

package/substrate/.claude/rules/assert-only-after-verify.md

@@ -0,0 +1,137 @@
+---
+tier: lite
+description: "Plain check: Before I make a claim in this turn, I read the source first and cite it."
+---
+
+# Assert Only After Verify
+
+**Plain check:** Before I make a claim in this turn, I read the source first and cite it. If I cannot cite the source, I do not ship the claim.
+
+---
+
+Every operator-facing assertion carries at minimum three parts: **My claim** (what you are saying), **Evidence** (the source you read, cited inline), and **Why the evidence supports the claim** (one sentence on why the source supports the claim). Two optional parts sharpen the shape: **Qualifier** (confidence + N observations) and **Rebuttal** (what would falsify the claim). Without My claim + Evidence + Why the evidence supports the claim, the assertion does not ship. This rule closes #559 at the class layer — pairs with the UserPromptSubmit hook at `.claude/hooks/assert-verify-steering.sh` per ADR-035 substrate-as-system tenet.
+
+**Vocabulary note (per bet 2026-07-03b WU-4 rename #613):** The working labels are **My claim / Evidence / Why the evidence supports the claim**. Toulmin's original vocabulary (claim / data / warrant) stays as the research citation in `.claude/luminaries/stephen-toulmin.md` — the working vocabulary reads plainer at the moment the operator scans the injected reminder.
+
+## When this rule fires
+
+Every operator-facing assertion the agent authors:
+
+- Audit findings and severity ranks
+- Cure recommendations and root-cause attributions
+- Turn estimates and time budget claims
+- Modal claims (words like "wrong," "broken," "should," "must," "always")
+- Class-level diagnoses ("this is an instance of...")
+- Ticket bodies, PR bodies, commit messages
+- Chronicle entries and journal drafts
+- Scope enumeration from queued tickets (/longrun option composition; /sprint next-work proposals)
+
+Pass-through cases (rule does not add ceremony):
+
+- Direct tool output relayed to the operator (test output, git output). INSTEAD of citing sources for tool relays: preserve the raw output; the tool IS the source.
+- Operator-quoted text preserved verbatim. INSTEAD of citing external sources for quoted operator text: attribution to the operator IS the citation.
+- Small conversational asides that carry no claim ("switching to main now"). INSTEAD of applying the shape to asides: reserve the discipline for assertions carrying a claim.
+
+## What the rule requires
+
+Before shipping any operator-facing assertion:
+
+1. **My claim** — state the assertion in one sentence
+2. **Evidence** — cite the source read inline. Files by path, tickets by number, git commits by SHA, chronicles by filename, standards by section
+3. **Why the evidence supports the claim** — one sentence on why the cited source supports the claim
+
+Optional (sharpen the shape):
+
+4. **Qualifier** — confidence + how many observations back the claim (e.g., "3 catches in one session"; "1 chronicle line"; "grep across 62 rules")
+5. **Rebuttal** — what would falsify the claim (per Popper). A claim that cannot be falsified is steering, not truth
+
+## Anti-patterns
+
+These shapes fail the rule.
+
+**Assertion without cited source.** "The hook is broken." No path, no evidence.
+
+INSTEAD: "The hook at the named path exits 2 when stdin contains no JSON — reproduced with `echo '' | bash <that-hook-path>`." My claim + Evidence + Why the evidence supports the claim.
+
+**Assertion pointing at a source but no warrant.** "Per chronicle 2026-06-30." What in the chronicle? Which line?
+
+INSTEAD: "Per chronicle 2026-06-30d L47 — three catches in one session, all naming R8 pattern." The warrant tells the reader what the source says.
+
+**Severity rank without observation criteria.** "This is a HIGH-severity finding." What was measured? Against what threshold?
+
+INSTEAD: "This is HIGH — audit finding blocks Phase XI Batten Down HIGH-severity discipline per architecture/audits/2026-06-28-adopter-experience.md L23; 2 sibling instances." Evidence + Why the evidence supports the claim.
+
+**Root cause attribution without falsifiability.** "The cause is X."
+
+INSTEAD: "The cause is X — falsified if removing X does not remove the symptom. Test: [name the test]." Rebuttal is Popper's contribution.
+
+**One explanation without alternatives.** "The bug is caused by Y."
+
+INSTEAD: "The bug fits Y (my current explanation), Z (alternative — same symptom, different mechanism), and W (third alternative). Reading source [path] to discriminate." Peirce's contribution — abductive reasoning names multiple candidates before committing.
+
+**Trusting `gh issue view state` as evidence work is undone.** Scope enumeration surfaces (/longrun option tables, /sprint next-work proposals) that read ticket state alone recommend already-done work. Ticket state and shipped state can diverge — work sometimes lands without the ticket getting closed; tickets sometimes stay OPEN as trackers after cures ship.
+
+INSTEAD apply the discipline shape per row of the option table:
+
+1. Read the ticket's acceptance criteria (via `gh issue view <N> --json body`)
+2. Grep or read the source the ticket measures against (the file, the counter, the audit output)
+3. If acceptance criteria are met by the current source — close the ticket in the enumeration itself (do not recommend it as scope)
+4. If not met — proceed with a specific measurement in the option row (what's missing, what's the delta, what's the actual turn cost)
+
+The catch: bet 2026-07-26d /longrun prep surfaced #884 (MEMORY.md prune) as a 20-40 turn scope option; the ticket's acceptance thresholds were already met by the file on disk. Reading `gh issue view state` returned `OPEN`; reading the file measured against the ticket criteria showed all three thresholds already passed. Operator caught the miss. See `feedback_verify_ticket_source_not_just_state.md`.
+
+## The three luminaries anchoring this rule
+
+- **Stephen Toulmin** — argument model. Claim + data + warrant is the minimum shape; qualifier + rebuttal sharpen it. From *The Uses of Argument* (1958)
+- **Karl Popper** — falsifiability. A claim that cannot be falsified is not a scientific claim; it is steering language. From *The Logic of Scientific Discovery* (1959)
+- **Charles Sanders Peirce** — abductive reasoning. Multiple explanations fit the same evidence; naming alternatives before committing catches confirmation bias. From "Deduction, Induction, and Hypothesis" (1878)
+
+Full luminary files ship in bet 2026-07-01b WU-2 at `.claude/luminaries/{stephen-toulmin,karl-popper,charles-sanders-peirce}.md`.
+
+## Why this rule exists
+
+Tonight's session surfaced R8 (assertion without verification) five times in ~5 hours (chronicle `2026-07-01c-r8-cascade-audit-retraction-and-cure-prep.md` names catches 16-20). My audit of `/longrun` was itself R8. I filed 5 tickets on unvalidated claims. I inflated turn estimates 3-4x above WU-2 grounding evidence. I attributed a false root cause during `/diagnose`. Operator caught each instance.
+
+`#559` named the R8 class in June. `#564` shipped one narrow surface cure (compounding-axis columns) but does not steer reasoning at the origin. Anthropic's UserPromptSubmit hook surface enables reasoning-boundary steering — the plain-English steering (per bassclef#790) proves the mechanism works. Every prompt this session carried the grade-10 reminder; my prose landed at grade 10 without conscious effort. Same physics applies to assertion discipline.
+
+The paired hook injects Toulmin's argument shape (labeled in bassclef as My claim + Evidence + Why the evidence supports the claim; Toulmin's original terms are claim + data + warrant per `.claude/luminaries/stephen-toulmin.md`) into every prompt. This rule is the methodology; the hook is the mechanism per ADR-035.
+
+## Composes with
+
+- `.claude/hooks/assert-verify-steering.sh` — the paired UserPromptSubmit hook this rule commits to
+- `.claude/rules/context-engineering.md` — foundational rule; this rule extends context engineering with argument shape
+- `.claude/rules/plain-english-discipline.md` — sister rule at prose surface; both fire per prompt
+- `.claude/rules/artifact-ingestion.md` — "read before produce" is the data-source discipline this rule extends to assertions
+- `.claude/rules/blocked-items.md` — assertions calling something BLOCKED must cite the block-source
+- `.claude/rules/stuck-signal-diagnostic.md` — assertion of "stuck" requires 3-session data
+- `.claude/luminaries/stephen-toulmin.md` — primary anchor (bet 2026-07-01b WU-2)
+- `.claude/luminaries/karl-popper.md` — supporting anchor (bet 2026-07-01b WU-2)
+- `.claude/luminaries/charles-sanders-peirce.md` — supporting anchor (bet 2026-07-01b WU-2)
+- Memory `feedback_verify_ticket_source_not_just_state.md` — the discipline the scope-enumeration anti-pattern encodes; verify tickets against source before scoping, not `gh` state alone
+- `.claude/skills/longrun/SKILL.md` prep — the surface where the scope-enumeration extension fires (Step 1 pre-flight through Step 1.7)
+- `.claude/skills/sprint/SKILL.md` — sister surface (next-work proposals)
+- ADR-035 substrate-as-system — the tenet this rule operationalizes at reasoning boundary
+
+## Override
+
+`SKIP_ASSERT_VERIFY_STEERING=1 <command>` on the hook — logged via trace-helper. The rule itself has no per-call override; the shape is minimum baseline. Use only when quoting verbatim external content that contains an unverified claim.
+
+INSTEAD of overriding for routine work: cite the source. The cost is a filename + one warrant sentence; the discipline compounds across every future assertion in every consumer repo.
+
+## Refs
+
+- bassclef-upstream#559 — R8 mechanization umbrella (this rule closes at class level)
+- bassclef-upstream#582 — parent ticket for this rule + hook
+- bassclef-upstream#564 — narrow-surface precedent (compounding-axis columns)
+- ADR-035 substrate-as-system tenet — rule + mechanism paired
+- `chronicle/2026-07-01c-r8-cascade-audit-retraction-and-cure-prep.md` — 5+ R8 catches this session; audit retraction pattern named
+- `chronicle/2026-06-30d-post-session-end-appendix.md` — 5 prior R8 catches
+- `chronicle/2026-07-26d-cures-2-3-5-shipped.md` — surfaced the scope-enumeration miss (#884 already-done recommended as 20-40 turn work); motivates the extension shipped in bet 2026-07-26g
+- bassclef-upstream#916 — this rule's scope-enumeration extension ticket
+- Toulmin — *The Uses of Argument* (Cambridge, 1958)
+- Popper — *The Logic of Scientific Discovery* (Hutchinson, 1959)
+- Peirce — "Deduction, Induction, and Hypothesis" (*Popular Science Monthly*, 1878)
+
+## Retirement condition
+
+This rule retires only if R8 (assertion without verification) stops reproducing across sessions. The mechanical layer (UserPromptSubmit hook) may evolve — additional detection heuristics, PR-body scan extensions, retroactive audit sweeps — but the discipline of My claim + Evidence + Why the evidence supports the claim (Toulmin's shape) at reasoning origin persists.