@thebassclef/lite 1.0.3 → 1.1.0

package/dist/lite/.claude/luminaries/tony-hoare.md

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

package/dist/lite/.claude/luminaries/vaughn-vernon.md

@@ -0,0 +1,50 @@
+---
+tier: lite
+name: Vaughn Vernon
+slug: vaughn-vernon
+claimed_by: [architect]
+referenced_by_skills: [decompose, architect-review]
+primary_domain: architecture
+depth: stub
+description: "\"DDD is implementable. Here's how.\""
+---
+
+# Vaughn Vernon
+
+## Signature
+
+*"DDD is implementable. Here's how."*
+
+Author of **Implementing Domain-Driven Design** (the "red book") and
+**Domain-Driven Design Distilled**. The canonical operational voice for
+DDD — where Evans provides the philosophy, Vernon provides the code.
+
+## Core methods
+
+- **Bounded Context Canvas** — Structured workshop output that defines a
+  bounded context's purpose, strategic classification, domain roles,
+  ubiquitous language, and inbound/outbound communication.
+- **Context mapping patterns** — Partnership, Shared Kernel,
+  Customer/Supplier, Conformist, Anticorruption Layer, Open Host Service,
+  Published Language, Separate Ways, Big Ball of Mud. Vocabulary for how
+  bounded contexts relate.
+- **Aggregate design rules** — Small aggregates; reference other
+  aggregates by ID only; update one aggregate per transaction; use
+  eventual consistency between aggregates.
+- **Event Storming (via Alberto Brandolini)** — Vernon popularized this
+  modeling method as the pragmatic entry point to DDD for teams new to it.
+
+## Sources
+
+- *Implementing Domain-Driven Design* — Vernon, Addison-Wesley (2013)
+- *Domain-Driven Design Distilled* — Vernon, Addison-Wesley (2016)
+- *Strategic Monoliths and Microservices* — Vernon, Jaskuła (2021)
+- kalele.io — Vernon's consultancy and ongoing DDD content
+
+## Related luminaries
+
+- **Eric Evans** — Vernon operationalizes Evans; pair them always.
+- **Alistair Cockburn** — Hexagonal Architecture pairs naturally with
+  bounded contexts; aggregates live inside hexagons.
+- **Gregor Hohpe** — EIP's anticorruption-layer aligns with Vernon's
+  context mapping.

package/dist/lite/.claude/luminaries/w-edwards-deming.md

@@ -0,0 +1,158 @@
+---
+tier: lite
+name: W. Edwards Deming
+slug: w-edwards-deming
+claimed_by: [builder, architect, closer, shaper]
+primary_domain: engineering
+depth: full
+description: "\"A bad system will beat a good person every time.\""
+---
+
+# W. Edwards Deming
+
+## Signature
+
+*"A bad system will beat a good person every time."*
+
+W. Edwards Deming (1900–1993) was a statistician who taught Japanese
+industry to read the system, not the person, when results disappoint.
+His finding from decades of plant data: roughly **94% of variation in
+outcomes traces to the system**, and roughly **6% traces to people**.
+The implication was strict — every time results land badly and the
+default reaction is "the person should have been more careful," the
+default is wrong 94% of the time. Deming's full discipline ran from the
+ground up: a cycle for improvement (**PDSA / PDCA**), a framing for
+what management owed the system (**14 Points**), and a system view
+called the **System of Profound Knowledge** that tied it all together.
+
+## Core methods
+
+- **PDCA / PDSA cycle (Plan-Do-Check-Act, later Plan-Do-Study-Act)** —
+  the discipline of substrate improvement. Plan a change. Do it small
+  first. Study what actually happened. Act on the finding (standardize
+  or revise). Loop. Use when the change is non-trivial AND the team is
+  about to ship without a structured way to learn from the result.
+- **14 Points for Management** — the duties of leadership in a system
+  that produces variation. Headline points: drive out fear; break down
+  barriers between departments; cease dependence on inspection (build
+  quality in); institute leadership; remove arbitrary numerical quotas.
+  Read the full 14 when shaping team structure or substrate-discipline
+  rules — many bassclef rules are 14-Points applied to agents.
+- **System of Profound Knowledge** — four lenses applied together:
+  appreciation for a system (the whole, not the parts); theory of
+  variation (special vs common causes); theory of knowledge (no
+  knowledge without prediction); psychology (people respond to
+  systems). Use when the question is "what kind of fix is this" —
+  process-level, structural, learning, or human.
+- **Common cause vs special cause** — variation has two flavors. Common
+  cause is built into the system (every run produces it). Special
+  cause is a specific event (a one-time trigger). The diagnosis path is
+  different for each. Use when picking remediation: common cause needs
+  a system change; special cause needs a single intervention.
+
+## When to channel this luminary
+
+Channel Deming whenever the default explanation reaches for
+operator-forgetfulness, agent-laziness, adopter-skill-gaps, or any
+"person should have been more careful" framing. Deming forces the
+question: is the system designed to make the right behavior easy? If
+not, the system is the defect.
+
+Also channel when shaping a hardening pass. The four lenses of the
+System of Profound Knowledge are the architect-review lenses Deming
+would apply in order. Specifically:
+
+- Appreciation for a system → C4 Context + Container diagrams; see the
+  whole substrate before zooming into hooks
+- Theory of variation → distinguish substrate-wide failure classes
+  (common cause) from one-off PR breakage (special cause)
+- Theory of knowledge → every hardening proposal predicts an outcome;
+  no prediction means no learning when the result lands
+- Psychology → adopters respond to substrate friction; reduce the
+  friction rather than asking adopters to push through it
+
+## Stack translation
+
+Bassclef's hooks, rules, validators, and skills are the **system**
+Deming describes. Operators and Claude Code agents are the **people**.
+When a defect surfaces:
+
+- If the same defect surfaces across three sessions, that is common
+  cause — patch the system (hook, validator, rule)
+- If the defect is a one-time slip (a typo, a missed paste), that is
+  special cause — fix the instance; do not change the substrate
+- If the defect surfaces because the discipline is methodology-only
+  (no mechanical gate), the system is the defect — escalate to hook
+
+PDCA maps onto substrate evolution: a /promote ticket is the **Plan**.
+Shipping the rule + hook is the **Do**. Watching for stuck-signal
+diagnostics across the next month is the **Study**. Closing or revising
+the rule based on usage data is the **Act**. Bassclef's
+`stuck-signal-diagnostic.md` rule is Deming's Study phase made
+mechanical.
+
+## Anti-patterns it prevents
+
+- **Operator-forgetfulness framing** — When a SessionStart hook fires
+  on a missing field, the first instinct can be "the operator forgot
+  to add it." Deming asks: is the hook design such that the field is
+  obvious? Is the bootstrap row shipped with the validator? If the
+  answer to either is no, the system is the defect — not the operator.
+- **Inspection-as-quality** — When a substrate gate fires repeatedly
+  and the answer is "more vigilance," that is inspection-instead-of-
+  quality-built-in. Deming Point #3: cease dependence on inspection.
+  Instead, build the validation INTO the surface that produces the
+  artifact (template that includes the required field; schema
+  validation at write time; pre-commit gate that emits the missing
+  row).
+- **Quota-driven scope-cutting** — When a session's appetite framing
+  drives toward (a) narrow fix because (c) full audit feels too big,
+  Deming Point #11 fires: remove arbitrary numerical quotas. Appetite
+  is a budget for shape-picking, not a quota for cause-categorization.
+  Run fishbone first; THEN pick the scope that fits the cause.
+
+## Worked example
+
+2026-06-24 chronicle reads: "Operator-side rot has structural cause,
+not operator forgetfulness." That single sentence is Deming applied.
+The 51-hour-stale `~/.claude/hooks/bassclef-sync.sh` did not happen
+because the operator forgot to update; it happened because the cp-list
+in §3 of the sync script omitted the script itself — the hook could
+not update itself. ADR-034 closed the gap with the two-stage rocket
+pattern — a SYSTEM change, not a person change.
+
+The four 2026-06-24 substrate defects all share the same Deming class:
+
+| Defect | System fix shipped | If Deming had been ignored |
+|---|---|---|
+| Operator-side rot | ADR-034 two-stage bootstrap | Tell operator to remember to sync |
+| 32 unwired hooks | #319 + #320 audit | Tell agent to remember to wire |
+| /kiss skip on PRs | bassclef#915 → hook | Tell agent to remember /kiss |
+| Public-scripts origin | #320 audit + WU-2 C4 Container | Tell operator to remember |
+
+The right-column reactions are the 6% framing. The left-column fixes
+are the 94% framing. Bassclef ships the 94% reactions by default; this
+luminary names the discipline.
+
+## Sources
+
+- *Out of the Crisis* — Deming (1986)
+- *The New Economics for Industry, Government, Education* — Deming (1993)
+- *Statistical Quality Control* — Deming (1939)
+
+## Related luminaries
+
+- **Walter Shewhart** — Deming's mentor; originator of PDCA (then
+  PDSA). Bassclef does not yet ship a Shewhart entry; the discipline
+  comes through Deming.
+- **Kaoru Ishikawa** — fishbone categorizes; PDCA improves. Use
+  Ishikawa to see the categories; use Deming to run the improvement
+  cycle.
+- **Taiichi Ohno** — Five Whys traces one chain; Deming asks whether
+  the chain is common-cause or special-cause variation.
+- **Linus Torvalds** — "we do not break userspace" is Deming Point #1
+  (constancy of purpose) applied to kernel stability. Bassclef's
+  adopter-respect rule is the same shape.
+- **John Ousterhout** — deep modules hide complexity; Deming would
+  call this designing the system so the surface is easy to use
+  correctly.

package/dist/lite/.claude/rules/accessor-library-discipline.md

@@ -0,0 +1,110 @@
+---
+tier: lite
+description: State spine consumers (skills, hooks, rules, scripts) MUST go through the typed accessor library lib/state.sh to read or write bassclef state.
+---
+
+# Accessor Library Discipline
+
+State spine consumers (skills, hooks, rules, scripts) MUST go through
+the typed accessor library `lib/state.sh` to read or write bassclef
+state. Direct filesystem access (cat, jq, awk, grep over JSON state
+files) is forbidden when an accessor exists.
+
+This rule is the Adapter discipline that preserves cxdb portability —
+exit criterion 1 of the 7 in canvas v4 §"Adapter discipline":
+
+> **Accessor library is the ONLY consumer of cxdb APIs.** No skill,
+> hook, rule, or script invokes cxdb directly. All access goes through
+> `lib/state.sh`.
+
+Same principle applied at v0 (where the storage backend IS the
+filesystem): no consumer reaches around the accessor to the raw files.
+
+## What this rule forbids
+
+In any skill, hook, rule, or script:
+
+- `cat docs/whereami.json` → use `state_whereami_get`
+- `jq '.field' docs/whereami.json` → use `state_whereami_get | jq '.field'`
+- `find state/markers -name '*.json' | wc -l` → use `state_marker_count`
+- `awk '/gates_fired:/' chronicle/*.md` → use `state_chronicle_gate_evidence`
+- `ls docs/deferred-actions/*.md | grep -v completed` → use `state_deferred_action_pending`
+- `cat docs/iteration-bets/<slug>.md | yq frontmatter` → use `state_iteration_bet_get`
+
+In general: any pattern that reaches into a state file (JSON or
+markdown frontmatter) is the violation. Read the contract at
+`standards/state-spine-contract.md` for the bassclef accessor surface.
+
+## What this rule allows
+
+- **Reading the accessor library itself** — `source lib/state.sh` and
+  call its functions. That's the entire point.
+- **Reading non-state markdown content** — body sections of Shape B
+  entities (the narrative parts, not the YAML frontmatter) can be
+  read directly. Example: `awk '/## Procedure/,/^## /' docs/iteration-bets/<slug>.md`
+  to extract the Procedure section is fine; that's narrative content,
+  not state.
+- **Reading non-spine files** — `cat .claude/skills/<skill>/SKILL.md`,
+  `cat README.md`, etc. State spine entities are enumerated in
+  `standards/state-spine.md`; other files aren't governed.
+- **Direct JSON writes during one-shot migrations** (e.g., WU-4
+  migration script). Migration scripts are explicitly out-of-band —
+  they bootstrap state into the spine from prior shapes.
+
+## What about new accessors that don't exist yet?
+
+If a consumer needs an accessor not yet in `lib/state.sh`:
+
+1. **Check if a generic verb suffices** — `state_<entity>_get`,
+   `state_<entity>_list`, `state_<entity>_count` cover most reads.
+2. **If a special-purpose accessor is needed**, propose it to the
+   contract first (`standards/state-spine-contract.md` §"Special-purpose
+   accessors"), then implement in `lib/state.sh`, then consume.
+3. **Do NOT bypass with direct file access** "just for now." That's
+   the path that produced bassclef#296.
+
+The cost of adding a new accessor is small (~5-10 lines + tests). The
+cost of accumulating ad-hoc bypass patterns is large and compounds
+(every consumer needs a fix when the storage backend changes).
+
+## Enforcement
+
+### Methodology level
+
+This rule loads into every session via `additionalDirectories`. Agents
+self-check against it before reading or writing state. Code review
+flags any direct state-file access in PRs.
+
+### Mechanical level (paired with WU-3)
+
+The `state-validate.sh` PreToolUse hook (WU-3) detects direct writes
+to state files and BLOCKs unless the change is going through an
+accessor. Read-side enforcement is harder to mechanize but the
+write-side gate covers the most damaging case.
+
+### Future mechanical level (post-v0)
+
+A pre-commit hook could grep for forbidden patterns (`cat docs/whereami.json`,
+`jq.*docs/whereami.json`, etc.) in staged changes and BLOCK unless an
+override comment is present. Defer to v1 once empirical violation rate
+is observable.
+
+## Override
+
+`SKIP_ACCESSOR_DISCIPLINE=1 <command>` — logged to trace per existing
+bassclef hook idiom. Use only for genuinely-not-yet-covered cases
+where adding the accessor is in flight; not as a habitual workaround.
+
+## Relationship to other rules + standards
+
+- `standards/state-spine.md` — entity catalog + storage shapes
+- `standards/state-spine-contract.md` — the accessor surface this rule
+  enforces consumption through
+- `lib/state.sh` — the implementation
+- `.claude/rules/state-schema-validation.md` (paired with WU-3) —
+  write-time validation; the accessor's `add`/`set`/`update_status`
+  methods invoke this validator before writing
+- canvas v4 §"Adapter discipline" — the source of this discipline; one
+  of 7 exit criteria for cxdb portability
+- bassclef#296 — the compliance-counter floor-lift incident that
+  motivates pure-derivation discipline (this rule + replay-determinism)

package/dist/lite/.claude/rules/adr-discipline.md

@@ -0,0 +1,96 @@
+---
+tier: lite
+description: "Every load-bearing architectural decision MUST be recorded as an ADR (Architecture Decision Record) per Michael Nygard's lifecycle: proposed → accepted → deprecated → superseded."
+---
+
+# ADR Discipline
+
+Every load-bearing architectural decision MUST be recorded as an ADR (Architecture Decision Record) per Michael Nygard's lifecycle: `proposed` → `accepted` → `deprecated` → `superseded`.
+
+ADR discipline lives at the rule layer (this file) plus the mechanical layer (`.claude/hooks/adr-discipline-check.sh` — PreToolUse hook on architectural-decision paths). Both load-bearing for adopter architecture quality.
+
+## When this rule fires
+
+Any session writing or editing a file matching architectural-decision shape:
+
+- `prisma/schema.prisma` or per-ORM schema equivalent (schema-change)
+- `docker-compose*.yml` or `docker-compose*.yaml` (deployment-topology-change)
+- `src/middleware.ts` or per-stack middleware equivalent (middleware-change)
+- `*/alembic/versions/*.py` / `*/db/migrate/*.rb` / `*/migrations/*.go` (schema-migration)
+- `package.json` / `pyproject.toml` / `Gemfile` / `go.mod` / `Cargo.toml` on Write only (dependency-manifest-change)
+
+When match fires, the hook checks for an ADR marker at `state/markers/adr/<decision-slug>-*.md`. The marker is required — generic ADRs in `docs/adrs/` or `architecture/decisions/` are not sufficient because they may be unrelated to the current decision class. When the marker is absent, the hook BLOCKs with template + writeup prompt.
+
+## Load-bearing definition
+
+A decision is load-bearing when:
+
+- It establishes an invariant future decisions must respect
+- Reversing it would require substantial migration work (>1 day operator time)
+- Multiple parts of the codebase depend on it
+- It crosses a bounded context boundary (per Evans DDD)
+- It changes a cross-cutting concern (auth, logging, multi-tenancy, observability stack)
+
+Non-load-bearing (skip ADR):
+
+- Bug fixes within existing patterns
+- Component-level library choices (icon library, date-picker)
+- Cosmetic refactors (renames, file reorganizations without behavior change)
+- Test additions
+- Documentation edits
+
+When in doubt, write the ADR. Ten-minute cost; high-value record.
+
+## ADR format
+
+Use `standards/adr-template.md`. Required sections:
+
+- Frontmatter: id, title, status, date, supersedes, superseded_by
+- Context — what motivated the decision
+- Decision — the choice + rationale
+- Status — proposed / accepted / deprecated / superseded
+- Consequences — what becomes easier / harder / enables / blocks
+- References — related ADRs, external sources, source incidents
+
+## Marker convention
+
+After writing the ADR, touch the marker:
+
+```bash
+mkdir -p state/markers/adr
+touch state/markers/adr/<decision-slug>-ADR-NNN.md
+```
+
+The marker is the audit trail: the hook reads it; reviewers can grep for it; chronicle Gate Evidence sections can cite it.
+
+## Override path
+
+`SKIP_ADR_CHECK=1 <command>` — logged via trace-helper. Use rarely:
+
+- Trivial revert of a previously-decided architectural change (the revert is reversing the prior decision per its `superseded_by` field)
+- Emergency rescue when the hook itself misclassifies (file substrate-defect)
+- One-shot migration script that touches many architectural files (operator has reviewed externally)
+- Bulk dependency-manifest regen where every dep was already declared in a prior ADR
+
+INSTEAD of overriding for routine work: write the ADR. The ten-minute cost is one of the cheapest substrate disciplines to follow.
+
+## Tech-stack-aware composition
+
+ADR discipline is stack-agnostic. The same template applies across stacks. Per-stack ADR examples may ship as siblings under `standards/adr-examples/<stack>.md` over time, with the discipline itself staying the same across stacks.
+
+## What the rule does NOT cover
+
+- ADR review process (operator + Architect agent collaboration)
+- ADR retirement (status change to `deprecated` or `superseded`; the file stays in place)
+- Cross-project ADR sharing (bassclef's ADRs and adopter's ADRs stay in separate directories)
+- ADR templates for non-software architecture (deployment-process ADRs, team-structure ADRs — out of scope for this rule)
+
+INSTEAD: each of the above lives in a sibling rule or template if it becomes relevant.
+
+## Composition with other rules
+
+- `.claude/rules/testing-tier-config.md` — Tier 0 strict-TDD on hook + tests (this hook + its test file land Tier 0)
+- `.claude/rules/blocked-items.md` — BLOCK protocol the hook fires
+- `.claude/rules/oo-ad-entry-point.md` — `/decompose` evidence is sister discipline at Construction boundary
+- `.claude/rules/schema-management.md` — schema-change ADR aligns with migration-discipline
+- `standards/adr-template.md` — the template the rule references