@thebassclef/lite 1.0.4 → 1.1.0

package/dist/lite/.claude/rules/sprint-prep-preset-picker.md

@@ -0,0 +1,76 @@
+---
+tier: lite
+description: /sprint next-work proposals pick one of three presets (converged / exploratory / reversible-small) based on mode signals. Sister rule to longrun-prep-plan-doc-compression at /sprint surface.
+---
+
+# /sprint — pick a preset that fits the mode
+
+Every `/sprint` dispatch picks one of three presets at Step 6.85 of the `/sprint` SKILL. The picker reads mode signals. It writes a marker. It fires the matching shape. The three presets are converged, exploratory, and reversible-small — same set as `/longrun` Step 0.85 per bassclef-upstream#1598.
+
+This rule is the methodology layer. The mechanism is the `/sprint` SKILL body Step 6.85. Both required per bootstrap-pair discipline.
+
+## When this rule fires
+
+Every `/sprint` dispatch. The SKILL body Step 6.85 checks the signals first. When converged fires, prep shows a scan-table plus one card. When exploratory fires, prep shows a scan-table with no cards. When reversible-small fires, prep shows a three-chunk compact block.
+
+## The three presets
+
+Per `.claude/skills/sprint/SKILL.md` Step 6.85. Signals differ from `/longrun` because `/sprint` reads different sources at pre-flight.
+
+| Preset | Fires when | Shape |
+|---|---|---|
+| **converged** | Active goal has open acceptance items OR fresh `docs/next-session-plan-*.md` with `## Recommended` | Recommend at top + scan-table capped at 4 cols + one card for the recommended option only |
+| **exploratory** | Between goals OR `browse` in invocation OR wide open backlog with no clear pick | Scan-table dominant (5-8 rows) + no cards until operator asks `show cards` |
+| **reversible-small** | `quick fix` in invocation OR single-issue candidate under 20 turns | Three-chunk compact — one line per option + one recommend + one action |
+
+Ambiguous cases: picker asks the operator — `Converged / Exploratory / Small? (c/e/s/skip)`.
+
+## What the rule requires
+
+Before shipping `/sprint` Step 7 output:
+
+1. Fire Step 6.85 picker. Read the mode signals. Pick one preset.
+2. Touch the preset marker at `state/markers/sprint-preset/<branch>.marker`. Cite the picked preset name.
+3. Render Step 7 in the shape that fits the picked preset per Step 7c preset-aware rendering block.
+
+Operator override at invocation flips the picker:
+
+- `/sprint browse` → forces exploratory
+- `/sprint quick fix` → forces reversible-small
+- `/sprint full` → forces the classic full menu (3-4 shapes with full cards)
+
+## Anti-patterns
+
+**Skip the picker; ship the full menu every time.** Fails the class this rule closes. Long menus on every call bury the pick.
+INSTEAD: run Step 6.85. Detect the mode. Ship the preset that fits.
+
+**Fire converged when acceptance items are stale.** Fresh plan doc that points at shipped work fires the wrong preset.
+INSTEAD: read the plan doc's `## Recommended` section. Cross-check against `git log`. Reshape to exploratory when the recommendation is stale.
+
+**Ship exploratory with cards.** Defeats the progressive-disclosure discipline.
+INSTEAD: scan-table only. Add signifier: "Ask 'show all cards' to expand."
+
+**Author a new picker mechanism.** Duplicates `/longrun` Step 0.85 discipline.
+INSTEAD: reuse the same agent-executed pattern. Sister mechanism ships once when it lands (goal 12a Step 2 or later).
+
+## Override
+
+`SKIP_SPRINT_PICKER=1 /sprint` — logged via trace-helper. Use only for:
+
+- One-shot testing to verify the full-menu path still renders
+- Migration scripts that dispatch many `/sprint` calls at once
+- Emergency rescue when the picker signal reads wrong
+
+INSTEAD of overriding for routine work: pick the preset. The cost is one check + one marker touch.
+
+## Composes with
+
+- `.claude/skills/sprint/SKILL.md` Step 6.85 — the SKILL body this rule prescribes
+- `.claude/rules/longrun-prep-plan-doc-compression.md` — parent rule at `/longrun` surface (goal 12a)
+- `.claude/rules/operator-facing-prose.md` Rule 3 — three-block opener still fires under compression
+- `.claude/rules/plan-enumeration-needs-value-props.md` — every option carries a value prop
+- `.claude/rules/bootstrap-pair-discipline.md` — this rule + SKILL body ship together
+- `.claude/rules/we-dont-break-adopters.md` — grace window (V1 no-hook default)
+- @luminary don-norman — signifier for mode + reshape path
+- @luminary luke-wroblewski — mobile-first content prioritization
+- @luminary sophia-prater — OOUX + progressive disclosure

package/dist/lite/.claude/rules/state-schema-validation.md

@@ -0,0 +1,156 @@
+---
+tier: lite
+description: State-spine entity writes MUST conform to their JSON Schema.
+---
+
+# State Schema Validation
+
+State-spine entity writes MUST conform to their JSON Schema. The
+`state-validate.sh` PreToolUse hook enforces this mechanically: any
+Edit/Write to a state-spine path is validated against the entity's
+schema; failure BLOCKs the write.
+
+This rule is the methodology layer. The hook is the mechanical layer.
+Both load-bearing.
+
+## When this rule fires
+
+Any Edit/Write/MultiEdit to a path matching a state-spine entity per
+`standards/state-spine.md` §"Storage format — four shapes":
+
+- **Shape A** (singleton JSON authoritative): `docs/whereami.json`,
+  `substrate.config.json`, `docs/preview-state/<slug>.json`
+- **Shape B** (markdown + YAML frontmatter): `docs/iteration-bets/*.md`,
+  `docs/roadmaps/*.md`, `docs/stacks/*.md`, `docs/decompositions/*.md`,
+  `docs/personas/*.md`, `docs/deferred-actions/*.md`, `chronicle/*.md`,
+  `docs/chronicle/*.md`
+- **Shape C** (pure JSON): `state/markers/*/*.json`,
+  `docs/sessions/*.json`, `docs/input-artifacts/*.json`,
+  `state/template-instances/*.json`, `state/inbox/*.json`,
+  `state/stack-templates/*.json`
+- **Shape D** (pure YAML at sibling-repo root): `*/bassclef-platform.yml`
+  (typically `~/src/<github_org>/platform-config/bassclef-platform.yml`)
+
+Non-spine paths pass through (e.g., README, source code, narrative
+markdown without YAML frontmatter, docs that aren't governed by the
+spine).
+
+## What the hook validates
+
+| Storage shape | Extraction | Schema validates |
+|---|---|---|
+| A | reads whole JSON file | the entity object |
+| B | extracts YAML frontmatter, converts to JSON | the frontmatter object |
+| C | reads whole JSON file | the entity object |
+| D | reads whole YAML file, converts to JSON | the entity object |
+
+In all four cases, validator: `ajv-cli` draft-2020-12 with format
+support (per ADR-015 single-format).
+
+## What the hook does NOT validate
+
+- **Markdown body content** of Shape B entities. Body sections (Procedure,
+  Acceptance, Sources read, narrative descriptions) are operator-readable
+  documentation; the schema doesn't constrain them.
+- **Cross-entity reference dangling.** `state_reference_check` (in
+  `lib/state.sh`) is the read-time check; the hook validates that the
+  `references` array's items conform to the reference shape (typed
+  `{type, id, anchor?}`), not that every referenced entity exists. A
+  dangling reference is a read-time concern, not a write-time one.
+- **Hash-as-index integrity.** Deferred to spine v1 per bassclef#316.
+- **Migration scripts** writing to state files during one-shot
+  migrations (e.g., WU-4) — these explicitly bypass via
+  `SKIP_STATE_VALIDATE=1` because they're bootstrapping prior shapes
+  into the spine.
+
+## What happens when validation fails
+
+The hook BLOCKs the write (exit code 3, structured stderr message).
+Output includes:
+
+- Entity type (which schema was applied)
+- Path being written
+- ajv error details (which field, which constraint, which line)
+- Three resolution paths:
+  1. Fix the data to match the schema (preferred)
+  2. Update the schema if it's wrong (requires PR review)
+  3. Override with `SKIP_STATE_VALIDATE=1` (logged; rare; not for normal work)
+
+The agent receiving the BLOCK should treat it as a `BLOCKED:` per
+`.claude/rules/blocked-items.md` — surface to operator, resolve, do
+not silently retry without diagnosis.
+
+## When to override
+
+`SKIP_STATE_VALIDATE=1 <command>` is logged to stderr. Use only:
+
+- **One-shot migration scripts** (WU-4 pattern) — bootstrapping prior
+  shapes into the spine; the data may not yet conform until migration
+  completes
+- **Schema is genuinely wrong** AND a fix-the-schema PR is in flight
+  AND blocking on validation would block the schema fix itself
+- **Emergency rescue** when the hook itself is broken (substrate-defect
+  recovery)
+
+NOT for:
+
+- "I'll fix the data later" — fix it now or document as a deferred
+  action
+- "The schema is too strict" — file an amendment PR, don't bypass
+- Routine work that happens to fail validation — the validation
+  failure is the signal that something's wrong
+
+## When to update the schema
+
+If the hook BLOCKs and the data is genuinely correct (the schema is
+overly restrictive), open a PR amending the schema:
+
+1. Edit `standards/state-spine/schemas/<entity>.schema.json`
+2. Update `standards/state-spine.md` if the entity catalog or
+   storage-shape table changes
+3. Validate the schema itself compiles cleanly under
+   `ajv compile --spec=draft2020 --strict`
+4. Re-run `bash .claude/hooks/tests/state-validate.test.sh` to ensure
+   no regressions
+5. Note the rationale in the PR body (what the schema previously
+   forbade that should be allowed; why)
+
+Schema changes are themselves state changes — review accordingly.
+
+## Relationship to other rules + standards
+
+- `standards/state-spine.md` — entity catalog + storage shapes (defines
+  what gets validated and how)
+- `standards/state-spine/schemas/*.schema.json` — the schemas this
+  rule enforces
+- `standards/state-spine-contract.md` — accessor contract; mutations
+  via `state_<entity>_add/set/update_status` accessors invoke this
+  validator before writing
+- `.claude/rules/accessor-library-discipline.md` — paired with this
+  rule; together they enforce read-side + write-side discipline
+- `.claude/rules/blocked-items.md` — BLOCK protocol the hook fires
+  (resolve or explicitly defer)
+- `.claude/hooks/state-validate.sh` — the mechanical implementation
+- `.claude/hooks/tests/state-validate.test.sh` — test coverage
+- `architecture/decisions/ADR-015-state-schema-format.md` — JSON Schema
+  only for v0; this hook uses ajv-cli per that decision
+- bassclef#298 — chronicle Gate Evidence drops; this hook + Chronicle
+  schema together make that failure class structurally impossible
+- bassclef#295, #296 — other defects from the four-incident set that
+  the spine v0 (incl. this rule) retires
+
+## Enforcement
+
+- **Hook**: `.claude/hooks/state-validate.sh` — fires on PreToolUse
+  with matcher `Edit|Write|MultiEdit`; wired in `.claude/settings.json`
+- **Methodology**: this rule loads in every session; agents
+  self-check before writing state
+- **Test coverage**: `.claude/hooks/tests/state-validate.test.sh` (14
+  tests covering all three shapes, override path, tool-name filter,
+  pass-through for non-state files)
+
+## Override
+
+`SKIP_STATE_VALIDATE=1 <command>` — logged to stderr per existing
+bassclef hook idiom. Use sparingly; document rationale in commit
+message.

package/dist/lite/.claude/rules/stuck-signal-diagnostic.md

@@ -0,0 +1,111 @@
+---
+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.
+
+## 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").

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

@@ -0,0 +1,85 @@
+---
+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.
+
+## 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/dist/lite/.claude/rules/test-list-discipline.md

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