@thebassclef/lite 0.1.2 → 1.0.0

package/substrate/.claude/rules/stuck-signal-diagnostic.md

@@ -1,140 +0,0 @@
----
-tier: lite
-description: "When a hook emits the same BLOCKED signal across ≥3 consecutive sessions and the underlying state counter hasn't moved, the signal is stuck."
----
-
-# Stuck-Signal Diagnostic
-
-When a hook emits the same BLOCKED signal across ≥3 consecutive sessions
-and the underlying state counter hasn't moved, the signal is stuck.
-A stuck signal is evidence of a **substrate defect**, not operator
-error — the hook is correctly detecting a condition the fix path
-cannot clear. Continuing to fire the same banner without reading the
-mechanism that produces it reproduces the acknowledge-and-skip loop
-`blocked-items.md` was built to close.
-
-## When this rule fires
-
-Any BLOCKED banner whose underlying counter / state has not advanced
-across ≥3 sessions. Observable shapes:
-
-- `BLOCKED: verify-compliance — X%` where X is identical 3 sessions running
-- `BLOCKED: temperance-compliance — X%` where X is identical 3 sessions running
-- `BLOCKED: metrics — DORA stale` with identical staleness counts
-- `BLOCKED: release-notes — last entry N days ago` where N grows but no
-  release is written
-- Any hook-surfaced BLOCKED whose associated counter/timestamp/state
-  is numerically or categorically unchanged across the last 3 chronicles
-
-The operator does not need to flag the staleness. The agent must
-self-detect by comparing current banner text against the prior
-session's banner text (visible in chronicles or `/sprint` output).
-
-## Mandatory mechanism-read
-
-When stuck-signal is detected, the agent MUST:
-
-1. **Stop addressing the symptom.** Do not propose running the usual
-   fix (e.g., "let me run /verify more diligently this session"). The
-   fix has been tried and the counter hasn't moved. That's the signal.
-
-2. **Read the mechanism files named in the banner.** The hook banner
-   names the exact paths. Follow the paths. Read every one.
-
-3. **Trace the counter's update path.** From mechanism-file read,
-   answer:
-   - Where is the counter computed?
-   - What state does the counter consume?
-   - What action updates that state?
-   - Is the update actually landing, or landing to a surface the
-     counter doesn't read?
-
-4. **Fire /diagnose on the mechanism.** Treat the stuck signal as a
-   substrate failure per `diagnosis.md`. Is/Is-Not + Five Whys +
-   Hypothesis applied to the hook + state-file + update path — not to
-   the surface behavior.
-
-5. **Resolve via substrate edit or escalate.** The fix is almost
-   always in the mechanism: wrong path, stale regex, counter reading
-   a location the writer stopped using, `/tmp` marker lost across
-   sandbox teardown. Edit the substrate, commit, verify the counter
-   advances. If substrate-read reveals no defect, escalate — the
-   counter is correct and the work is genuinely undone; `blocked-items.md`
-   default (resolve) applies.
-
-## Post-resolution obligation: mandatory /promote
-
-When mechanism-read reveals a substrate defect (hook path wrong,
-state file rotted, marker format changed, compliance calc broken),
-resolution MUST include firing `/promote` with the `substrate-defect`
-classifier. See `blocked-items.md` §"When resolution reveals a
-substrate defect" for the full protocol and `promote/SKILL.md` for
-the template.
-
-Fixing the local instance without promoting means the same defect
-keeps firing in consumer repos — which is exactly the
-acknowledge-and-skip loop at a different layer.
-
-## Why this rule exists
-
-2026-04-20 session end + 2026-04-21 session start (the loop that
-motivated bet `2026-04-21a-blocked-signal-integrity`): session-rescue
-hook fired 15 times in ≤4 hours, each session acknowledging the
-deferred-actions BLOCKED block, resolving the nominal entry, and
-shipping — only for the next stop to write a fresh rescue entry.
-
-The counter ("15 deferred-action entries resolvable") stayed stuck
-because resolution lived in the local session but the hook's
-detection path rotted during `/tmp` sandbox teardown. The mechanism
-file (`session-end.sh`) had a calendar-date chronicle check that fired
-even when a fresh chronicle existed with a different date pattern —
-a substrate defect that `/verify`-more-carefully could not clear.
-
-Root cause: the agent kept "resolving" the surface while the
-mechanism produced fresh false-positives. Three sessions of identical
-banner text. The signal was stuck. Nobody read `session-end.sh`.
-
-This rule removes the option to "try harder" when the counter hasn't
-moved. If the counter is stuck, the fix is in the mechanism, not in
-the work.
-
-## Relationship to other rules
-
-- `blocked-items.md` — the base BLOCKED-resolve-or-explicit-defer
-  protocol; stuck-signal is a specific escalation branch
-- `diagnosis.md` — Is/Is-Not + Five Whys applies to the mechanism
-  when the signal is stuck
-- `sdlc-gates.md` — observed failure → temperance → diagnose chain;
-  stuck-signal is an observed failure in the meta-signal layer
-- `artifact-ingestion.md` — "read the file before producing" extends
-  to "read the mechanism before resolving"
-- Post-resolution `/promote` obligation: `blocked-items.md` §"When
-  resolution reveals a substrate defect"
-
-## Enforcement
-
-Methodology-level. The compliance-counter hooks
-(`session-reflection.d/40-gate-compliance.sh` and siblings) name
-mechanism paths in their BLOCKED banners so the agent has the
-literal file paths to read — no guessing about what "mechanism"
-means. If stuck-signal recurs without mechanism-read in the next 6
-months, upgrade to hook-enforced: refuse session advance until an
-Edit tool call lands on the named mechanism path.
-
-## Override
-
-There is no override. Stuck-signal is the condition under which
-"proceed and try again" is the failure mode. If the counter is
-stuck, the agent reads the mechanism. Full stop.
-
-Operator may still explicitly defer the underlying BLOCKED item per
-`blocked-items.md` deferral syntax ("skip metrics this session") —
-but the mechanism-read obligation still fires the next session unless
-the operator also defers that (rare, e.g., "mechanism-read next
-week, I'm unblocking you manually this time").
-
-## Retirement condition
-
-If counter-stuck incidents fall to zero for 12 months with no
-operator-flagged false-negatives, this rule has done its job.
-Retirement candidate — the methodology-layer habit is durable.

package/substrate/.claude/rules/substrate-config-schema.md

@@ -1,98 +0,0 @@
----
-tier: lite
-globs: ["substrate.config.md", "substrate.secrets.md", ".claude/skills/**/*.md", ".claude/hooks/**/*", "standards/**/*.md"]
-description: Substrate config + secrets schemas — single source of truth for external resource references and secret lifecycle
----
-
-# Substrate Config + Secrets Schema (rule)
-
-Two paired files; each owns one concern:
-
-| File | Owns | Standard |
-|------|------|----------|
-| `substrate.config.md` | External resource *references* (Google Doc IDs, URLs, repo refs, env-var names) | `standards/substrate-config-schema.md` |
-| `substrate.secrets.md` | Secret *lifecycle* (rotation cadence, expiry, runbooks, health checks) | `standards/secrets-lifecycle.md` |
-
-Both are read at session-start; agents always source from these files.
-
-INSTEAD of memory or hardcoded values: read at session-start from
-`substrate.config.md` (resources) and `substrate.secrets.md` (lifecycle).
-
-## Agent behavior rules
-
-1. **Read resources only from `substrate.config.md`.** When a skill
-   or hook needs a doc ID, URL, or similar reference, the agent
-   reads it from this file at runtime. Don't hardcode. Don't cache.
-
-   INSTEAD: read at runtime from `substrate.config.md`. Field name is
-   the interface; raw value is implementation detail that can change.
-
-2. **Reference by field name, not by raw value.** In project memory,
-   in chronicles, in commit messages: say `brand_corpus_doc_id`, not
-   `1gps7mmEYBCud...`. The raw value is an implementation detail;
-   the field name is the interface.
-
-3. **When a resource is missing**, prompt the operator to add it to
-   `substrate.config.md` with a typed field name. Use the suffix
-   convention: `*_doc_id`, `*_url`, `*_repo`, `*_path`, `*_token_name`,
-   etc. (full list in the standard).
-
-4. **No raw secrets in `substrate.config.md`.** That file is
-   committed to git. Store the *name* of the env var holding the
-   secret (`anthropic_key_name: ANTHROPIC_API_KEY`).
-
-   INSTEAD of inlining the secret value: keep values in their
-   authoritative storage (1Password / GitHub Actions Secrets /
-   AWS Secrets Manager / `.env`); the config file points by name.
-
-5. **Secret *lifecycle* belongs in `substrate.secrets.md`**, not
-   `substrate.config.md`. References go in config; rotation cadence,
-   expiry dates, runbook paths, and health-check commands go in
-   secrets. Each file owns its concern.
-
-   INSTEAD of mixing concerns: lifecycle metadata (last_rotated,
-   expiry_at, rotation_procedure) lives in `substrate.secrets.md`;
-   resource references (doc IDs, URLs, env-var names) live in
-   `substrate.config.md`. Cross-reference between the two files.
-
-6. **No secret VALUES anywhere in the repo.** `substrate.secrets.md`
-   tracks references and metadata only — values stay in their
-   authoritative storage (1Password / GitHub Actions Secrets / `.env`
-   / AWS Secrets Manager). The session-start hook
-   (`.claude/hooks/session-reflection.d/90-secrets-expiry.sh`) surfaces
-   BLOCKED when any secret is within `alert_threshold_days`; resolve
-   per the entry's `rotation_procedure` runbook.
-
-7. **When migrating old code**, replace hardcoded IDs with
-   `substrate.config.md` lookups. Grep for the raw ID value across
-   `.claude/`, `standards/`, `strategy/`, and the raw content of
-   project memory. Replace with field-name reference.
-
-## Why this rule exists
-
-Before this rule (learned 2026-04-12):
-- Brand corpus doc ID lived in project memory
-- Hardcoded in `/journal-export` skill
-- Also referenced indirectly in other places
-- Agent pushed to wrong doc, operator caught the mismatch, hours of
-  confusion and re-pushing followed
-
-After: one place. Typed. Skills read at runtime. Memory points by
-name. Agents can't confuse which doc is which because there's only
-one source.
-
-## Bootstrap path for new repos
-
-When `/autonomous start` scaffolds a new repo's `substrate.config.md`,
-it prompts for every known resource field (per the standard's "Known
-fields" section). Operators can skip (defaults apply), but each known
-field is surfaced once so nothing gets stored in memory or hardcoded
-by accident.
-
-## Related
-
-- `standards/substrate-config-schema.md` — full standard
-- `.claude/skills/autonomous/SKILL.md` — scaffold prompts for
-  each known field
-- `.claude/skills/substrate-check/SKILL.md` — can validate config schema
-  compliance in a repo

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

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

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