@thebassclef/lite 1.0.4 → 1.1.0

package/dist/lite/.claude/rules/test-sufficiency.md

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

package/dist/lite/.claude/rules/testing-tier-config.md

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

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

package/dist/lite/.claude/rules/turn-estimate-grounding.md

@@ -0,0 +1,82 @@
+---
+tier: lite
+description: "Plain check: Before I ship a turn estimate to an adopter, I cite a past bet's actuals + write a range + name the shape."
+---
+
+# Turn-Estimate Grounding
+
+**Plain check:** Before I ship a turn estimate to an adopter, I cite a past bet's actuals + write a range + name the shape. Ungrounded numbers do not ship.
+
+---
+
+Every turn estimate that lands in adopter-facing prose (goal docs, PR bodies, canvases, ticket bodies) carries three parts:
+
+1. **Source** — cite a past bet's closeout actuals with comparable scope shape (WU count, test-heavy vs docs-heavy, defect diagnosis interludes)
+2. **Range not point** — write a range (e.g., "40-80 turns") not a point ("60 turns")
+3. **Plain-language framing** — name the shape driving the number in one sentence
+
+Ungrounded turn estimates do not ship to adopter-facing prose. This rule extends the argument shape from `.claude/rules/assert-only-after-verify.md` to numeric claims. It applies at the same reasoning surface — the moment a number gets written down for an adopter to read.
+
+## When this rule fires
+
+Every time budget estimate, turn count, or effort range that lands in prose an adopter will read:
+
+- `docs/iteration-bets/*.md` frontmatter `appetite:` line
+- `docs/iteration-bets/*.md` body when narrative surfaces a number
+- PR body `Test plan` or `Summary` sections when they cite effort
+- `docs/canvases/*.md` sizing sections
+- Ticket body `Estimate` fields (INVEST format uses S/M/L; this rule fires when a turn count appears instead)
+- Chronicle time-budget actuals sections when they cite the filed number
+- Journal drafts when they cite bet actuals for a past bet
+
+Does NOT fire on:
+
+- **Chronicle body actuals** for a past bet (backward-looking; the number IS the source itself)
+- **Operator-only surfaces** — internal chronicles, private strategy docs, session-timing markers
+- **Runtime numbers** at checkpoint or closeout time — those cite what happened, not what will happen
+
+## What the rule requires
+
+Before any turn estimate ships to adopter-facing prose:
+
+1. **Cite a past bet by path** — one or two bets whose closeout actuals inform this estimate. Format: `bet 2026-07-09c (5 WUs; heavy test setup; ~110 turns actual)`. Path optional but preferred when the calibration goal is recent.
+2. **Write a range** — the range spans enough to cover the estimate's uncertainty. A 40-80 turn range signals the shape is well-understood but has natural variance. A 200-600 turn range signals real uncertainty and prompts the operator to consider splitting the goal.
+3. **Name the shape** — one sentence stating what drives the number. Examples: "documentation-heavy; single-file SKILL edit + rule text," "5 WUs riding a shared fixture; each cure ships end-to-end with 10-15 Tier 0 tests," "test-first Beck TDD with 4 substantive WUs sharing a fixture foundation."
+
+## Trivial-fix exception
+
+Fix branches and quick-fix PRs may skip the discipline when the change is under 10 lines AND no goal doc time budget line is being authored. Silence about effort is fine on trivial fixes.
+
+## Adopter-friendly framing
+
+Numbers can be honest AND friendly. Instead of:
+
+> "This goal needs 500-700 turns"
+
+Prefer:
+
+> "This bet groups 5 substantive changes. Past bets of this shape landed around 100-350 turns. The wider top of the range covers defect diagnosis interludes that add 30-50 turns per step when they fire."
+
+The friendly version:
+- Cites a past shape ("bets of this shape landed around 100-350")
+- Names the shape driver ("5 substantive changes")
+- Explains the top-of-range variance ("defect diagnosis interludes")
+
+## Composes with
+
+- `.claude/rules/assert-only-after-verify.md` — parent discipline; this rule extends argument shape to numeric claims
+- `.claude/rules/plain-english-discipline.md` — grade 8 target with grade 10 ceiling; friendly numbers pass the same reading-level test as prose
+- `.claude/rules/pr-body-shape.md` — Test plan and Summary sections that cite effort follow this rule
+- `.claude/rules/pr-title-shape.md` — sister at title surface
+- `.claude/skills/longrun/SKILL.md` Step 1 pre-flight — cites this rule at time budget estimation
+- @luminary stephen-toulmin — argument shape (claim + evidence + why the evidence supports the claim)
+- @luminary karl-popper — falsifiability (grounded estimates check against past actuals; ungrounded ones cannot be checked)
+- Memory `feedback_no_token_estimates.md` — sister at token-estimate surface
+- Memory `feedback_tight_ticket_appetite.md` — calibration for infra tickets
+- Memory `feedback_longrun_appetite_estimates_too_tight.md` — calibration for WU-heavy bets (3-4x off pattern)
+
+## Override
+
+`SKIP_TURN_ESTIMATE_GROUNDING=1` — logged via trace-helper. Use only when quoting an external number verbatim (e.g., citing a Shape Up appetite from Basecamp's book).
+
+INSTEAD of overriding for routine work: cite the past bet. The cost is one sentence; the discipline compounds across every future adopter who reads a goal doc.