@thebassclef/lite 0.0.1 → 0.1.2

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.

package/substrate/.claude/rules/turn-estimate-grounding.md

@@ -0,0 +1,134 @@
+---
+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."
+
+## Worked examples
+
+### Anti-pattern (what NOT to do)
+
+```yaml
+appetite: 500-700 turns
+```
+
+Ungrounded. Range too wide. No shape named. Adopter reads this and either dismisses the goal as heavyweight or trusts an ungrounded number.
+
+### Anti-pattern (point estimate)
+
+```yaml
+appetite: 250 turns
+```
+
+Point not range. False precision. No source cited.
+
+### Anti-pattern (source-free range)
+
+```yaml
+appetite: 40-80 turns
+```
+
+Range is fine but ungrounded. Adopter has no way to check if 40-80 is realistic.
+
+### Conformant pattern
+
+```yaml
+appetite: 40-80 turns
+appetite_source: "bet 2026-07-09d (documentation-heavy adopter polish; 2 substantive WUs; ~30 turns actual). Similar shape — single-file SKILL edit + rule text; no new test infrastructure."
+```
+
+Or in narrative form:
+
+> **Appetite:** 40-80 turns. Similar shape to bet 09d (~30 turns actual for 2 WUs of single-file SKILL edits + rule text). This bet adds one more WU so the top of the range widens.
+
+Both forms carry source + range + shape.
+
+## 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.
+
+## Refs
+
+- sunj-labs/bassclef-upstream#670 — this rule's filing ticket
+- sunj-labs/bassclef-upstream#559 — R8 mechanization umbrella (parent argument-shape work)
+- sunj-labs/bassclef-upstream#582 — assert-verify-steering hook (sister at prose-scan surface)
+- Bet 2026-07-09e — this rule's ship vehicle (eats own dogfood on the time budget line)
+- Toulmin — *The Uses of Argument* (Cambridge, 1958)
+- Popper — *The Logic of Scientific Discovery* (Hutchinson, 1959)
+
+## Retirement condition
+
+This rule retires only if goal docs stop surfacing turn estimates in adopter-facing prose. A mechanical layer (Stop hook that scans goal doc frontmatter for ungrounded time budget lines) may ship as a follow-on when methodology drift is observed. Until then, this rule is methodology; the discipline holds at reasoning origin per ADR-035 substrate-as-system tenet.