@thebassclef/lite 0.1.0 → 0.1.3

package/substrate/.claude/rules/test-list-discipline.md

@@ -0,0 +1,175 @@
+---
+tier: lite
+description: "Every test file opens with a # test-list: commented block enumerating the assertions the step owes."
+---
+
+# Test-List Discipline
+
+Every test file opens with a `# test-list:` commented block enumerating
+the assertions the step owes. Each line is one intended assertion,
+written before any source is edited. Implemented assertions get `[x]`;
+pending stay `[ ]`. Remaining `[ ]` lines visible at commit time are
+honest in-flight signal — truth about what is still owed.
+
+This rule is the **planning layer** of TDD discipline. The Tier 0 hook
+(bassclef#1037) enforces test presence + recency: test file exists, test
+mtime ≤ source mtime. That catches tests written after source. It does
+not catch tests written before source that miss intended assertions.
+
+INSTEAD: Beck's test list surfaces intent as a tangible artifact at the
+top of the test file, where reviewer and future-reader can see what was
+considered AND deferred vs what was missed entirely.
+
+## Why this rule exists
+
+Bassclef adopts Kent Beck as the TDD anchor — Tier 0 enforces his
+red-green-refactor cycle mechanically. The Tier 0 framing came from
+*Test-Driven Development By Example* chapter on cycle discipline.
+Beck's same book opens (chapters 1-3) with the test list as a separate
+discipline: write the list of tests you intend to write BEFORE you
+start; cross off as you go; add new tests to the list as they surface.
+
+Bassclef imported the cycle without importing the planning artifact.
+Result: agents (and operators) write a test, see it pass, ship — and
+the next reader has no record of which assertions were considered AND
+deferred vs which were missed entirely. The two collapse into silence.
+
+INSTEAD: the test-list block at the top of every test file makes the
+record visible. Considered-and-deferred assertions live as `[~]` lines
+with one-line reasons; missed assertions get added as `[ ]` lines as
+soon as a reviewer or later reader notices them.
+
+Surfaced 2026-06-17 during /longrun prep when operator pushed twice on
+"feels incomplete" sufficiency framing. The mechanical sufficiency
+criteria (sister test-sufficiency rule) IS the answer to what to assert;
+the test list IS the answer to whether you covered the intent. Both are
+required.
+
+## Format contract
+
+Every test file (any file matching `*test*.sh`, `*.test.*`, `test_*.py`,
+`*_test.go`, etc. depending on stack) opens with this block before any
+test code:
+
+```bash
+# test-list:
+# [x] Skip case: empty stdin returns exit 0
+# [x] Skip case: non-matching tool_name returns exit 0
+# [ ] Behavior: matched tool with valid input writes marker
+# [ ] Behavior: matched tool with invalid input returns exit 3 with stderr
+# [ ] Override: SKIP_FOO=1 bypasses and logs to trace
+# [ ] Edge: missing external binary (jq) returns exit 0 with warning
+```
+
+Rules:
+
+- `# test-list:` is the literal marker (greppable; future hook reads it)
+- One assertion per line; `[ ]` pending, `[x]` implemented
+- Each line is one sentence in plain English describing the assertion
+- Lines added as new assertions surface during implementation (the list grows)
+- Lines stay in place when an assertion turns out not to apply — mark `[~]` with one-line reason inline.
+
+  INSTEAD of removing the line: keep the `[~]` record so future-reader sees the assertion was considered and judged not-applicable, with the reason. Removal loses the consideration history.
+
+- The block lives at the top of the test file, before any source code
+
+## What this rule requires
+
+When authoring or extending a test file:
+
+1. **Before writing any test code**, write the `# test-list:` block enumerating intended assertions. Use the test-sufficiency rubric (sister rule) as the source for what categories of assertion a hook test needs.
+2. **As each assertion is implemented**, change its `[ ]` to `[x]` in the same commit that ships the test.
+3. **If new assertions surface during implementation**, add them to the list as `[ ]` lines. The list grows; that is honest signal.
+4. **Before commit**, scan remaining `[ ]` lines. Each is either:
+   - Implemented in this commit (mark `[x]`)
+   - Genuinely deferred (mark `[~]` with one-line reason; commit that reason as the file's record)
+   - Required but missed — write the assertion now and mark `[x]`.
+
+     INSTEAD of committing with the line as `[ ]` when the assertion is owed by THIS commit: write the assertion, mark `[x]`, then commit. Pending lines are for genuinely-next-commit work.
+
+## What satisfies the rule
+
+A test file is conformant when:
+
+- Top of file has `# test-list:` block
+- Every line in the block has `[x]`, `[ ]`, or `[~]` prefix
+- Every `[x]` line maps to at least one test function in the file
+- Every `[~]` line has a one-line reason inline
+- Pending `[ ]` lines at commit time are intentional (operator-visible signal that work continues)
+
+## Anti-shapes (what fails the rule)
+
+The hook-future-extension will BLOCK at these shapes. For now, reviewer + agent self-check.
+
+- A test file with no `# test-list:` block at all.
+
+  INSTEAD: add the block before committing; even retrofitting a list from an existing test file's contents is better than missing one, because the act of writing the list surfaces assertions the existing tests missed.
+
+- A test file with a block that contains only `[x]` lines while obvious assertions are missing.
+
+  INSTEAD: surface the gap by adding `[ ]` lines for the missing assertions; the visible gap is the call-to-action for the next commit.
+
+- A `[~]` line without inline reason.
+
+  INSTEAD: add the one-line reason in the same commit that marks the line `[~]`; the reason IS the audit trail.
+
+- A `[x]` line with no matching test function.
+
+  INSTEAD: either implement the test function (if the assertion was meant to ship) OR change `[x]` to `[~]` with reason (if the assertion turned out not to apply).
+
+## When this rule fires
+
+Auto-loaded into every session via `additionalDirectories`. Agents
+self-check before committing any test file. The Tier 0 hook
+(`testing-tier-enforce.sh`) does not currently enforce this block.
+
+INSTEAD: methodology-level enforcement via agent + reviewer attention.
+Mechanical extension deferred to follow-on ticket; see V2 section below.
+
+## V2 — mechanical extension (deferred)
+
+When operator observes recurring drift from manual self-check, file a
+follow-on ticket extending Tier 0 hook with a grep for `# test-list:`
+block in any test file being committed. BLOCK when missing. Allowlist
+existing test files in a sister `.claude/hooks/test-list-allowlist.txt`
+with grace window (same pattern as Phase A shellcheck-allowlist).
+
+For now: methodology layer. Reviewer + agent self-check.
+
+## Override
+
+`SKIP_TEST_LIST=1` — logged via trace-helper per bassclef hook
+override idiom. Use only for migration commits backfilling old test
+files OR for emergency rescue when the rule itself appears wrong.
+
+INSTEAD of overriding for routine work: write the test-list block. The
+block costs ~30 seconds of typing; the override cost compounds across
+every consumer repo's reviewer attention.
+
+## Composes with
+
+- `.claude/rules/testing-tier-config.md` — Tier 0 enforces presence + recency; this adds intent transparency
+- `.claude/rules/test-sufficiency.md` — 10-criterion mechanical sufficiency rubric; supplies WHAT to assert; this supplies HOW to track
+- `.claude/rules/testing.md` — what makes a good test (test-content guidance); this adds the planning artifact
+- `@luminary kent-beck` — TDD anchor; chapters 1-3 of TDD By Example are the bassclef source
+
+## Distinct from
+
+- `testing-tier-config.md` — about WHICH paths require which tier of enforcement
+- `testing.md` — about what makes a test good once you write it
+- `test-sufficiency.md` — about what categories of assertion to consider
+- `iteration-bet-brief-completeness.md` — about handoff brief completeness; different scope
+
+## Refs
+
+- bassclef#1090 — this rule's filing ticket
+- bassclef#1037 — Tier 0 strict-TDD discipline (Phase A); this extends with intent transparency
+- bassclef#867 — anchor-luminary verification pattern (Beck as TDD anchor)
+- Beck — Test-Driven Development By Example (Addison-Wesley, 2002), chapters 1-3
+- `docs/iteration-bets/2026-06-17b-sufficiency-rubric-plus-hardening-longrun.md` — goal authoring this rule
+
+## Retirement condition
+
+This rule retires only if bassclef migrates off TDD as a primary
+discipline. The test list as a planning artifact survives any specific
+test-framework or tier-config evolution.

package/substrate/.claude/rules/test-sufficiency.md

@@ -0,0 +1,210 @@
+---
+tier: lite
+description: The Tier 0 hook (bassclef#1037) enforces test PRESENCE + RECENCY.
+---
+
+# Test Sufficiency Rubric
+
+The Tier 0 hook (bassclef#1037) enforces test PRESENCE + RECENCY. The test file exists. Its mtime is at least as new as the source file's. That catches tests written after source. It catches zero things about whether the test ASSERTS ENOUGH.
+
+This rule codifies the 12 mechanical criteria the agent applies before committing any test file. Each criterion is greppable, countable, and verifiable against the source it tests. Together they form the sufficiency contract for bassclef's Tier 0 hooks, state-spine accessors, and adopter-stack code where systematic discipline earns its keep.
+
+INSTEAD of relying on "feels complete" — the squishy framing that surfaced this gap during /longrun prep 2026-06-17 — the agent applies the 12 criteria mechanically. The agent marks each as covered or deferred with reason in the test-list block (bassclef#1090) and ships the result.
+
+## Anchor luminaries
+
+- `@luminary kent-beck` — TDD rhythm anchor; test list is the planning artifact this rubric assumes
+- `@luminary glenford-myers` — Coverage taxonomy anchor; criteria 1-4 are direct applications of Myers's 1979 categories
+- `@luminary tony-hoare` — Contract testing anchor; criteria 5-10 are precondition / postcondition / invariant assertions in disguise
+
+The rubric is what each luminary's lens produces when applied to a bassclef bash hook or state-spine accessor. The substrate operationalizes the discipline; the luminaries supply the why.
+
+## The 12 criteria
+
+### 1. Branch coverage (Myers — decision coverage)
+
+Every branch in the source has at least one test that exercises it. Mechanically: `grep -cE '^\s*(if|elif|else|case|\|\|)' <source>` counts decision points; the test file owes that many `[x]` lines minimum.
+
+Example for `auto-save-idle.sh` with 4 branches (no-changes / lock-present / defer-present / proceed): the test file owes 4 tests minimum to satisfy decision coverage alone.
+
+INSTEAD of one test that covers the happy path: one test per branch. The marginal cost per test is small at write-time and compounds across every consumer adopting the hook.
+
+### 2. Exit code matrix (Hoare — postcondition)
+
+Every distinct `exit N` in the source has at least one test that triggers that exit and asserts the code matches. Mechanically: `grep -oE 'exit [0-9]+' <source> | sort -u` enumerates the codes; the test file owes one assertion per code.
+
+Example: `pre-commit-gate.sh` has `exit 0` (pass), `exit 2` (BLOCK), `exit 3` (validation fail). Test file asserts each appears under the input that triggers it.
+
+INSTEAD of asserting only success exit: one assertion per distinct exit code. Exit codes ARE the hook's postcondition contract with the harness; the test list owes one Hoare-style `{P} S {Q-exit-N}` triple per code.
+
+### 3. Tool-name matcher (Myers — equivalence partitioning)
+
+For hooks matching on `tool_name`, the test file has one test per matched tool AND at least one non-matched tool asserting pass-through. Each matched tool is one equivalence class; the non-matched set is another class with one representative.
+
+Example: `pre-commit-gate.sh` matches `Edit|Write|MultiEdit`. Test file owes: Edit-fires test, Write-fires test, MultiEdit-fires test, Bash-pass-through test, NotebookEdit-pass-through test.
+
+INSTEAD of asserting only the matched class: cover both halves of the discriminator. Pass-through tests catch matcher regressions that would silently expand the hook's surface.
+
+### 4. Path-matcher coverage (Myers — boundary value)
+
+For hooks matching on file paths or globs, the test file has a positive test (path matches) AND a near-miss negative test (similar path doesn't match) per glob. Boundary value applied to string-shape inputs.
+
+Example: hook matches `state/markers/temperance/*.marker`. Positive test: `state/markers/temperance/foo.marker`. Near-miss tests: `state/markers/temperance/foo` (no extension), `state/markers/temperance-x/foo.marker` (similar dir name), `state/temperance/foo.marker` (missing markers segment).
+
+INSTEAD of asserting only the matched path: near-miss tests catch glob bugs that would either widen or narrow the matcher unexpectedly.
+
+### 5. Override path (Hoare — alternative precondition)
+
+Every `SKIP_*` env var bypass in the source has one test that exercises the override AND asserts the override path fires (logged via trace-helper, hook exits with pass code, side effects suppressed).
+
+Example: `auto-save-idle.sh` honors `SKIP_AUTO_SAVE=1`. Test file owes: with-flag-set test (asserts no-commit + trace log emission), without-flag test (asserts normal path).
+
+INSTEAD of treating override paths as unused: they are alternative preconditions in Hoare's framing. Each override is a `{P-skip-set} S {Q-bypass}` triple the test list owes one entry for.
+
+### 6. stdin contract (Hoare — precondition discipline)
+
+The hook reads JSON from the harness via stdin. Each discriminated input shape (different `tool_input` fields, different content shapes) has one test that exercises it.
+
+Example: `pre-commit-gate.sh` discriminates on `tool_input.file_path` (string) and absent (some Edit calls omit it). Test file owes: file_path-present test, file_path-absent test, malformed-JSON test (graceful error path).
+
+INSTEAD of asserting only the well-formed input: malformed JSON is a precondition violation the hook must handle without crashing. Tests assert the hook reports the violation rather than crashing the harness.
+
+### 7. External-binary handling (Hoare — invariant under environment variation)
+
+For every external call (`jq`, `gh`, `git`, `flock`, `python3`, etc.), tests either mock the binary OR exercise a graceful-missing test asserting the hook handles binary-absent without crashing.
+
+Example: hook calls `jq` to parse JSON. Test file owes: jq-present happy-path test, jq-missing test (asserts hook detects and exits with informative stderr OR falls back to bash-native parsing).
+
+INSTEAD of assuming every adopter environment has every binary: external binaries are an environmental precondition the hook should fail soft against. Bassclef-internal hooks may assume `jq` (Tier 0). Adopter-distributed hooks should not.
+
+### 8. Trap / cleanup (Hoare — class invariant via `trap EXIT`)
+
+Sources that use `trap '...' EXIT` (per defensive-bash.md) need two tests: one exercises the success path (verify cleanup ran) AND one exercises a failure path (verify cleanup still ran).
+
+Example: hook acquires `flock` and uses `trap "flock -u" EXIT`. Test file owes: success-path test (verify lock released on normal exit), failure-path test (verify lock released when hook fails mid-execution).
+
+INSTEAD of trusting `trap` works by inspection: the trap IS the class invariant; the test verifies the invariant holds across both observable paths. Trap regressions silently leak resources.
+
+### 9. stderr format (Hoare — postcondition contract for BLOCK exits)
+
+For BLOCK exits (code 2 or 3), the test asserts the stderr message contains the required structured fields per `.claude/rules/blocked-items.md`: entity type, path being acted on, ajv error details (when applicable), three resolution paths.
+
+Example: `state-validate.sh` BLOCKs on schema failure. Test file owes: BLOCK-exit test asserts stderr contains "Entity type:", "Path:", "ajv:", and the three resolution-path lines.
+
+INSTEAD of asserting only exit code on BLOCK: the stderr message IS the contract with the agent. A BLOCK with empty stderr is a worse failure than no BLOCK at all — the agent loses the remediation path.
+
+### 10. State-file interactions (Hoare — postcondition on side effects)
+
+For hooks that read or write markers in `state/markers/` (or any state file), tests cover both read paths and write paths. Read-path test: state file present in expected shape → hook reads correctly. Write-path test: hook write completes → file content matches the expected shape.
+
+Example: `pre-commit-gate.sh` reads `state/markers/temperance/<branch-slug>.marker`. Test file owes: marker-present test (verify hook reads + passes), marker-absent test (verify hook BLOCKs + writes BLOCKED stderr), marker-malformed test (verify hook fails-soft with informative error).
+
+INSTEAD of testing only the read OR only the write: state-file interactions are bidirectional contracts. Skipping the write-path test means schema drift between writer and reader goes unnoticed until production.
+
+### 11. Path resolution under both install classes (Hoare — invariant under install layout; added bet 27c WU-9)
+
+For hooks that read project resources (standards files, configs, libs) AND declare `# install-class: dual` per `standards/hook-install-class.md`, tests pin behavior under both install layouts. Project class (CLAUDE_PROJECT_DIR set). Operator class (HOME_OVERRIDE pointing at fixture user-install layout). Mechanically: at least one test per resource read that fires under each layout.
+
+Example: `turn-prose-kiss-check.sh` reads `standards/bassclef-internal-jargon.md` via `resolve_standards_path` from `lib/hook-inject.sh`. The test file owes four tests — Test 54 (CLAUDE_PROJECT_DIR layer 1), Test 55 (KISS_STANDARDS_FILE env layer 2), Test 56 (HOME_OVERRIDE layer 3), Test 57 (all layers fail; defensive fallback). PR #427 ships exactly those four tests.
+
+INSTEAD of testing only project install: install class is an environmental precondition the hook MUST honor under both layouts. Skipping the operator install test produces the silent fail pattern that surfaced 2026-06-27 (kiss path resolution defect; chronicle Gate Evidence row 1). The cure pattern (HOME_OVERRIDE fixture + Tests 54-57 shape) is reusable across every dual-class hook.
+
+This criterion fires when the source under test declares `install-class: dual` (most steering hooks; some adopter-distributed project hooks). Source declares `install-class: project` only → criterion does not fire. Project resources always resolve cleanly under project install.
+
+### 12. Invocation-mode variation for coordinated fragments (Feathers + Hoare — invariant under invocation mode; added bet 2026-07-30c WU-3)
+
+For modules invoked by a coordinator (fragments under `session-reflection.d/`, `pre-commit-hooks.d/`, or any `*.d/` directory that a parent hook sources), tests pin behavior under BOTH invocation modes:
+
+- **Standalone**: `bash "$module"` — exit codes propagate normally; the module runs as its own process
+- **Sourced**: coordinator sources the module under `set -e`; the module MUST use `return` (or safe dual form) not `exit`, else the coordinator dies with the module's exit code
+
+Mechanically: at least one test per fragment that (a) sources it under a set -e wrapper and asserts a canary after the source fires, and (b) invokes it standalone via bash and asserts no "return: can only" error appears in stderr.
+
+Example: `.claude/hooks/session-reflection.d/*.sh` fragments. Test file `.claude/hooks/tests/session-reflection-coordinator-full.test.sh` (bet 2026-07-30c WU-1) runs Class A (sourced-parent-survives) plus Class B (standalone-no-return-error) for every fragment. The wrapper injects the coordinator-side helpers (`blocked_banner`, `trace_log`, `BASSCLEF_DIR`) as stubs so the fragment's contract with the parent scope is honored during the test.
+
+INSTEAD of trusting that `exit` in a sourced file is fine: sourced `exit` kills the parent process silently. The class shipped in PR #542 (2026-06-30 — `05-active-bet.sh`) and cost 36 days of silent session-start check skips in every adopter session until PR #992 cured 2026-07-30. Criterion 12 exists so the class cannot recur — every new fragment PR ships with sourced-parent-survives AND standalone-no-return-error assertions.
+
+This criterion fires when the source lives under a `*.d/` directory whose parent hook sources fragments in a loop. Detection: the source directory name ends in `.d/` AND at least one sibling `.sh` file in the parent directory sources files from that directory. Adopter-authored fragments that plug into bassclef coordinators inherit this criterion at PR time.
+
+Coordinator-side coupling note: fragments frequently call helper functions the coordinator defines (e.g., `blocked_banner`, `trace_log`) and read environment variables the coordinator exports (e.g., `BASSCLEF_DIR`). The invocation-mode test wrapper MUST inject these helpers as stubs so the test characterizes the fragment under conditions matching real coordinator invocation. Skipping the stubs produces false-red on any fragment that calls a coordinator helper.
+
+## How to apply the rubric
+
+1. **Before writing any test**, list applicable criteria for the source under test. Some hooks have all 10; some (pure-function libraries) have fewer (no stdin contract, no override path).
+2. **Open the test file with the test-list block** (bassclef#1090). Use one `[ ]` line per criterion-derived assertion.
+3. **Implement each assertion**, marking `[x]` as each ships. Add new `[ ]` lines as additional cases surface during implementation.
+4. **Before commit**, scan the test-list for `[ ]` lines. Each is either:
+   - Implemented in this commit (mark `[x]`)
+   - Genuinely deferred (mark `[~]` with one-line reason per test-list-discipline.md)
+   - Required but missed (write the assertion now; do not commit with the line as `[ ]` when it should be `[x]`)
+5. **Verify mechanical counts** for criteria 1, 2, 7: branch count, exit count, external-binary count. The test count must equal or exceed each source count.
+
+INSTEAD of relying on "feels complete": each criterion has a greppable verification. If the test file has fewer `[x]` lines than the source has branches, the rubric is not satisfied. Concrete, mechanical, auditable.
+
+## What the rubric does NOT cover
+
+- **Test rhythm** — when to write tests (route to Beck via `testing-tier-config.md` Tier 0)
+- **Test quality** — what makes a test well-written (route to `.claude/rules/testing.md`)
+- **Test design** — whether the source's shape makes testing easy or hard (route to Ousterhout via `john-ousterhout.md`)
+- **Property-based testing** — coverage of input space via QuickCheck-style generators (future addition if a stack adopts it; not in bassclef's bash substrate today)
+- **Multi-fragment coordinator interactions** — how fragment N's side effects change fragment N+1's behavior (route to integration tests at the coordinator level, e.g., `session-reflection-coordinator.test.sh` per PR #992; criterion 12 covers per-fragment invocation-mode contract only)
+
+INSTEAD of folding these into the rubric: each routes to a sister discipline. The rubric is sufficiency at the assertion-category layer; quality and rhythm and design are different surfaces.
+
+## Override
+
+`SKIP_TEST_SUFFICIENCY=1 <command>` — logged via trace-helper. Use only for one-shot migration scripts, emergency rescue, or when adding the assertion would require infrastructure not yet in place (file follow-on ticket).
+
+INSTEAD of overriding for routine work: write the assertion. Each criterion costs minutes at write-time; each missed assertion costs hours of debugging when it ships.
+
+## When this rule fires
+
+Auto-loaded into every session via `additionalDirectories`. Agents self-check before committing any test file. The Tier 0 hook (`testing-tier-enforce.sh`) does not currently enforce the rubric mechanically.
+
+INSTEAD: methodology layer with reviewer + agent self-check. V2 mechanical extension deferred to follow-on ticket. Count-based criteria (1, 2, 7) are auto-verifiable via the existing Tier 0 hook with a grep extension.
+
+## V2 — mechanical extension (deferred)
+
+The operator files a follow-on ticket to extend the Tier 0 hook when recurring drift shows up in manual self-check. The follow-on covers:
+
+- Branch count: grep source for decision points; count test `[x]` lines; BLOCK when test count < branch count
+- Exit code matrix: grep source for `exit N`; verify test asserts each
+- External binary handling: grep source for external calls; verify test mocks or graceful-missing path exists per call
+
+Subjective criteria (3-6, 8-10) stay methodology-only. Beck + Myers + Hoare's disciplines pair best with reviewer judgment for those; mechanical enforcement at the subjective layer produces gaming, not quality.
+
+## Composes with
+
+- `.claude/rules/test-list-discipline.md` (bassclef#1090) — Beck's planning artifact; the test-list IS the rubric tracking surface
+- `.claude/rules/testing-tier-config.md` (bassclef#1037) — Tier 0 presence + recency; this rule layers sufficiency on top
+- `.claude/rules/testing.md` — what makes a good test once you write it
+- `.claude/rules/defensive-bash.md` — 7 bash disciplines; criteria 7-8 verify defensive-bash compliance in tests
+- `.claude/rules/state-schema-validation.md` — state-spine accessor tests use criterion 10 (state-file interactions)
+- `.claude/rules/blocked-items.md` — criterion 9 (stderr format) cites this rule's structured-field requirements
+- `@luminary kent-beck` — TDD rhythm + test-list anchor
+- `@luminary glenford-myers` — coverage taxonomy anchor (criteria 1-4)
+- `@luminary tony-hoare` — contract testing anchor (criteria 5-10)
+
+## Distinct from
+
+- `testing-tier-config.md` — WHICH paths require WHICH tier of enforcement; this is WHAT assertions a tier 0/1 test owes
+- `testing.md` — WHAT makes a test well-written once you write it
+- `test-list-discipline.md` — HOW to track which assertions are owed/done/deferred
+- `iteration-bet-brief-completeness.md` — separate scope (delegation briefs, not test code)
+
+## Refs
+
+- bassclef#1098 — this rule's filing ticket
+- bassclef#1037 — Tier 0 strict-TDD discipline (Phase A); this extends with sufficiency layer
+- bassclef#1090 — Beck test-list discipline (sister rule; planning artifact for this rubric)
+- bassclef#1092 — Glenford Myers full luminary (anchor for criteria 1-4)
+- bassclef#1094 — Tony Hoare full luminary (anchor for criteria 5-10)
+- bassclef#1095 — full-from-filing policy (the luminaries cited here ship full)
+- `docs/iteration-bets/2026-06-17b-sufficiency-rubric-plus-hardening-longrun.md` — goal authoring this rule (eat-own-dogfood: WU-2a/b/c hardening uses this rubric)
+- Beck — *Test-Driven Development By Example* (Addison-Wesley, 2002)
+- Myers — *The Art of Software Testing* (Wiley, 1979)
+- Hoare — *Communications of the ACM* 12(10), 1969
+
+## Retirement condition
+
+This rule retires only if bassclef migrates off systematic testing as a primary discipline. Specific criteria may evolve (V2 mechanical extension may absorb criteria 1, 2, 7; property-based testing may add criterion 11 if a stack adopts it) but the discipline of mechanical sufficiency-at-write-time survives.

package/substrate/.claude/rules/testing-tier-config.md

@@ -0,0 +1,145 @@
+---
+tier: lite
+description: "Bassclef's testing discipline is configured per path-matcher in .claude/bassclef-configs.jsonc under the testing section."
+---
+
+# Testing-Tier Config
+
+Bassclef's testing discipline is configured per path-matcher in `.claude/bassclef-configs.jsonc` under the `testing` section. Four tiers — 0 strict TDD / 1 test-with / 2 smoke / 3 manual-verify — pick by blast radius. Most-specific path-matcher wins. The mtime-checking hook (`testing-tier-enforce.sh`) enforces Tier 0 mechanically; Tier 1 WARNs; Tier 2 + Tier 3 stay silent.
+
+This rule supersedes the honor-system framing of `.claude/rules/testing.md`. That rule remains the test-content guidance (what makes a good test); this rule governs which paths require tests and what enforcement fires.
+
+## Why this rule exists
+
+Bassclef shipped `.claude/rules/testing.md` with three layers — unit + integration + smoke — and a "skip glue code, trivial getters" exemption. That exemption ran on the honor system. No check fires when a new exported function ships without a test. No check fires when someone edits source without touching the test. No check fires when a hook update skips its test.
+
+The 2026-06-15 substrate-archaeology session named the pattern. TDD-everywhere runs too verbose for adopter surfaces like chronicles and one-off scripts. TDD-nowhere runs too lax for bassclef's own hooks and schemas, where a silent bug hits every adopter. The tier framework lets impact pick the enforcement level.
+
+The Tier 0 mtime hook does the actual work. INSTEAD of asking the agent to run tests from memory: the hook BLOCKs the commit when the test mtime did not advance with the source. A gate at the moment of failure beats a rule that fires after.
+
+## The four tiers
+
+| Tier | Name | What it means | Enforcement |
+|---|---|---|---|
+| **0** | Strict TDD | Test mtime ≤ source mtime AND test file present | BLOCK at pre-commit |
+| **1** | Test-with | New test expected when new source ships | WARN at pre-commit |
+| **2** | Smoke | Smoke test exists somewhere for this surface | Silent (advisory only) |
+| **3** | Manual verify | Operator eyeballs the change | Silent (no enforcement) |
+
+**Tier 0** is for surfaces where silent bugs compound across every adopter. Bassclef hooks, state-spine schemas, lib/state.sh accessors, and the substrate's own pre-commit gates live here.
+
+**Tier 1** is for bassclef's own glue scripts (`scripts/*.sh`) and adopter-app source files where TDD is expected but the WARN gives leeway for in-progress work.
+
+**Tier 2** is for adopter-app routes and components where end-to-end smoke tests cover the surface without per-file unit tests. The path-matcher does not look for a sibling test file; the operator confirms a smoke test exists.
+
+**Tier 3** is the silent default for narrative content. Chronicles, journal entries, iteration-goal docs, decompositions, and operator-private narrative all live here. INSTEAD of testing narrative: the operator reads it.
+
+## Path-matcher precedence
+
+Two categories of path matchers, with different ownership:
+
+1. **Substrate-internal paths** — bassclef's own infrastructure. **Hard-coded in this rule body.** NOT adopter-configurable. Adopters read the discipline; they cannot edit it.
+2. **Adopter-app paths** — adopter's own code paths. Configured in adopter's `bassclef-configs.jsonc` `testing.path_matchers`. Per-adopter.
+
+The hook walks both lists. Substrate paths take precedence; adopter overrides on substrate paths are silently ignored. When no entry matches, `testing.global_floor` applies. The default global floor is Tier 1 (WARN on missing test).
+
+### Substrate-internal path-matchers (HARD-CODED — not adopter-configurable)
+
+| Path | Tier | Why this is Tier 0 / fixed |
+|---|---|---|
+| `.claude/hooks/*.sh` | 0 | Silent bugs compound across every adopter using bassclef |
+| `scripts/migrate-adopter-references.sh` | 0 | Adopter-facing migration tool; Tier 0 hooks call it at session-start (per ADR-031); a defect hits every adopter machine. (Moved from `strategy/templates/` per bassclef-upstream#317 Phase 1b.) |
+| `scripts/bassclef-orphan-parking.sh` | 0 | Adopter-facing migration tooling — same reason as above |
+| `scripts/bassclef-migrate-summary.sh` | 0 | Adopter-facing migration tooling — same reason as above |
+| `presence/install/*.sh` | 0 | Adopter-facing distribution dispatcher + sync + install bootstrap; a defect hits every adopter machine. (Moved from `strategy/templates/` per bassclef-upstream#317 Phase 1a.) |
+| `standards/state-spine/schemas/*.json` | 0 | Schema defects corrupt the state spine universally |
+| `lib/state.sh` | 0 | Accessor library central to all state reads; one defect breaks every consumer |
+| `lib/intent-matcher.sh` | 0 | Intent dispatch — a defect breaks every chain |
+| `scripts/*.sh` | 1 | Other operator-class scripts not listed above; WARN if missing test |
+| `chronicle/*.md` | 3 | Narrative content; operator-read, no test |
+| `docs/iteration-bets/*.md` | 3 | Narrative; operator-read |
+| `docs/decompositions/*.md` | 3 | Narrative; operator-read |
+| `docs/operator-private/journals/*.md` | 3 | Narrative; operator-read |
+
+These are bassclef's substrate. Per ADR-031 and Linus's rule that bassclef keeps adopters working — discipline is a contract, not a preference. INSTEAD of letting adopters lower their tier: bassclef holds the discipline for its own substrate. Adopters read this rule; they cannot lower it themselves.
+
+Why not adopter-configurable:
+- **Substrate integrity is a contract.** Adopters rely on bassclef's reliability guarantee; lowering bassclef's own tier would undermine the contract while still depending on it.
+- **Hyrum's Law applied to discipline.** Configurable tier means some adopter lowers it; their substrate degrades silently; bassclef's future fixes that assumed the discipline break their setup.
+- **Linus's kernel/userspace boundary.** Linux exposes kernel state as READ surfaces, not WRITE permission over kernel correctness machinery. bassclef's tier discipline is the same shape.
+- **Brooks's conceptual integrity.** Discipline is bassclef's coherent vision; configurability creates per-adopter drift.
+
+### Adopter-app path-matchers (configurable per adopter)
+
+Adopters edit `testing.path_matchers` in their own `.claude/bassclef-configs.jsonc` for THEIR code:
+
+```jsonc
+"testing": {
+  "global_floor": 1,
+  "path_matchers": [
+    { "match": "src/middleware.ts",                     "tier": 0 },
+    { "match": "src/lib/auth/**",                       "tier": 0 },
+    { "match": "src/app/**/route.ts",                   "tier": 2 },
+    { "match": "src/components/**/*.tsx",               "tier": 2 }
+  ]
+}
+```
+
+The substrate entry wins when an adopter's `path_matchers` entry matches a substrate path (above). The hook ignores adopter attempts to lower substrate tiers — by design.
+
+## Test-file sibling mapping (Tier 0 only)
+
+For Tier 0 paths, the hook expects a sibling test file:
+
+| Source path | Expected test path |
+|---|---|
+| `.claude/hooks/<name>.sh` | `.claude/hooks/tests/<name>.test.sh` |
+| `standards/state-spine/schemas/<name>.schema.json` | `standards/state-spine/schemas/tests/<name>.test.sh` |
+| `lib/<name>.sh` | `lib/tests/<name>.test.sh` |
+
+The hook BLOCKs when the source is edited and the test mtime did not advance. The BLOCK message names three things: the source path, the expected test path, and the mtime gap. INSTEAD of failing silently: the message tells the agent which test file to touch.
+
+## Override discipline
+
+`SKIP_TESTING_TIER_ENFORCE=1 <command>` bypasses the hook for one command. The bypass is logged via `trace-helper.sh` per bassclef's existing override idiom.
+
+Use it sparingly. Three cases warrant the override. One-shot migration scripts that bootstrap state. Emergency rescues when the hook itself is broken. Documentation changes where the agent has clear evidence the source change carries no behavior.
+
+INSTEAD of overriding for routine work that fails the check: write the test. The hook fires at the cheapest moment to add one. Deferred test-writing almost never happens.
+
+## Allowlist baseline (grace window)
+
+`.claude/hooks/testing-tier-enforce-allowlist.txt` lists existing Tier 0 sources that ship without tests as of the hook's land date. Each entry carries a dated grace window. The hook BLOCKs on listed paths in two cases. First — the grace window expires. Second — the source gets edited (new edits during grace still BLOCK). The allowlist covers pre-existing unedited state only.
+
+The grace window is set per-adopter at `/onboard-repo` (default 60 days). Operator decides whether to backfill tests for grandfathered hooks or to remove them from the allowlist as they are next touched.
+
+INSTEAD of forcing retroactive backfill at hook-land: the grace window covers existing untested bassclef hooks while new edits trigger enforcement. Per-hook backfill happens as those hooks are next touched.
+
+## When this rule fires
+
+This rule is methodology — it loads in every session via `additionalDirectories`. Agents self-check before writing source files in Tier 0 paths. The `testing-tier-enforce.sh` hook is the mechanical layer (bassclef#1037 WU-3).
+
+Together: rule supplies the why; hook fires at the moment of failure.
+
+## Composes with
+
+- **@luminary kent-beck** — TDD anchor. Beck's red-green-refactor cycle is the discipline this rule does for Tier 0. A test written before source naturally satisfies "test mtime ≤ source mtime" — the test came first.
+- **@luminary john-ousterhout** — Design-judgment anchor. The tier choice IS a design decision. Push every path to Tier 0 and you get shallow modules where tests just mirror source. Push every path to Tier 3 and you get silent regressions. The tier slider applies Ousterhout's "complexity is incremental" — pick the right tier per surface. Do not flatten the answer.
+- `.claude/rules/testing.md` — the existing rule on test content (what makes a good test). This rule does not replace it; it adds the per-path tier decision that testing.md left implicit.
+- `.claude/rules/state-schema-validation.md` — sister mechanical-enforcement rule at the state-spine write surface.
+- `.claude/rules/blocked-items.md` — the BLOCK protocol the hook fires.
+- `.claude/hooks/pre-commit-gate.sh` — the chain the new hook joins.
+- `.claude/hooks/testing-tier-enforce.sh` — the mechanical implementation (bassclef#1037 WU-3).
+- `.claude/bassclef-configs.jsonc` — the adopter-edit surface with inline comments.
+
+## Refs
+
+- bassclef#1037 — this rule's filing ticket (testing-tier-config primitive)
+- bassclef#1036 — sister ticket; Ousterhout luminary stub
+- bassclef#867 — anchor-luminary verification pattern
+- `docs/iteration-bets/2026-06-15a-discipline-and-versioning-foundations.md` — Phase A bet
+- `docs/roadmaps/2026-06-15-engineering-discipline-and-versioning.md` — parent roadmap
+
+## Retirement condition
+
+This rule retires only if the testing-tier framework itself is replaced by a different enforcement model (for example, vitest coverage gates per tier — Phase E). The discipline of per-path tier choice survives any future enforcement-mechanism swap.

package/substrate/.claude/rules/testing.md

@@ -0,0 +1,38 @@
+---
+tier: lite
+globs: ["**/*.ts", "**/*.tsx", "**/*.test.*", "**/*.spec.*"]
+description: Three-layer test strategy — loads when touching source or test files
+---
+
+> **Companion rule (bassclef#1037):** `.claude/rules/testing-tier-config.md` governs WHICH paths require which level of test enforcement (Tier 0 strict TDD / 1 test-with / 2 smoke / 3 manual verify). This rule (testing.md) governs WHAT makes a good test once a tier requires one. The tier-config rule supersedes the honor-system framing implicit in "skip glue code, trivial getters" below — tier choice is now configured per path-matcher in `.claude/bassclef-configs.jsonc`, and the `testing-tier-enforce.sh` hook fires mechanically.
+
+Three layers, all required. Skipping shifts cost to production debugging.
+
+Layer 1 — Unit (vitest):
+  Pure function logic. New pure function = new test, no exceptions.
+  Pre-commit WARNs if new source file has no matching test.
+  CI BLOCKs on failure.
+
+Layer 2 — Integration:
+  Pipeline wiring. Real DB + real Redis, mock only external APIs at HTTP level.
+  CI BLOCKs on failure.
+
+Layer 3 — E2E/Smoke:
+  Post-deploy. Curl-based minimum (health, API, auth redirect).
+  Playwright for critical user paths when needed.
+
+Coverage policy:
+  100% branch for safety rules. ≥80% line for business logic.
+  Skip glue code, trivial getters, third-party internals, LLM output content.
+
+Naming: `test_{what}_{scenario}_{expected_outcome}`
+Fixtures: factories not hardcoded data.
+
+Change matrix:
+  Pure function → unit. Agent/worker → integration. API route → integration + smoke.
+  Schema migration → integration. Middleware/auth → E2E. UI component → smoke.
+
+Order:
+  For pure functions and non-trivial logic, write the test before or
+  alongside the implementation — not after. If you wrote the test after,
+  state so in the verify summary so the reviewer can audit for tautology.