@thebassclef/lite 0.0.1 → 0.1.2

package/substrate/.claude/rules/skill-description-clarity.md

@@ -0,0 +1,247 @@
+---
+tier: lite
+description: "Every skill's frontmatter description field must be parseable by an engineer with no bassclef context in under 60 seconds."
+---
+
+# Skill-Description Clarity
+
+Every skill's frontmatter `description` field must be parseable by an
+engineer with no bassclef context in under 60 seconds. Outcome-first.
+≤280 chars. Plain language. INSTEAD-block discipline.
+
+This rule sits at the entry surface. It parallels bassclef#357 (which governs autonomous-run output). It applies `.claude/rules/context-engineering.md` at the description field: write for what the model can access. For this rule, that means write what a fresh engineer can read in 60 seconds.
+
+**Mechanical enforcement**: `.claude/hooks/substrate-clarity-gate.sh` fires at PreToolUse Edit|Write on substrate paths. It BLOCKs skill descriptions past 280 chars or without verb-first openers. The rule + luminary INSTEAD-block check runs ADVISORY today. It flips to BLOCK once the rule + luminary audits ship (tracked under bassclef-upstream#303). The allowlist at `.claude/hooks/substrate-clarity-allowlist.txt` grandfathers existing violators during the grace window. Per bassclef#382.
+
+## The bar
+
+Anthropic's frontend-design description (per Welch's revision):
+
+> "Create distinctive, production-grade frontend interfaces with
+> high design quality. Avoids generic AI aesthetics."
+
+That's the bar. Outcome ("create distinctive interfaces"), one-line
+how ("with high design quality"), one-line why-distinct ("avoids
+generic AI aesthetics"). 117 chars. Engineer reads it; knows what
+the skill produces; knows when to use it.
+
+Compare to bassclef's pre-rule descriptions (representative):
+
+> "BUILD-tier composer (Construction transition). Chains the
+> prototype pipeline (input → variants → gallery → bind-subdomain)
+> PLUS the buildable-spec pipeline (use-case → user-stories →
+> ia-model → interaction-design → decompose → spec → ux-migration)."
+
+571 chars. Methodology-laden. Requires knowing what every named
+component is. Engineer can't grok in 60 seconds.
+
+## Format
+
+Every skill's frontmatter `description` field follows:
+
+```
+<verb> <outcome>. <one-line how>. <one-line why-distinct>.
+```
+
+- **Verb**: imperative — "Create," "Generate," "Run," "Compose," "Audit"
+- **Outcome**: what the skill PRODUCES (not how it works internally)
+- **One-line how**: the most distinguishing mechanism, in plain language
+- **One-line why-distinct**: what makes it different from adjacent skills (or what it specifically AVOIDS)
+
+Total ≤280 chars including spaces.
+
+## INSTEAD-block discipline
+
+Every "DON'T" / "AVOID" / "NEVER" in the description gets paired with
+the actionable substitute, per `.claude/rules/context-engineering.md`.
+
+INSTEAD of bare negation: state the actionable substitute the engineer
+or model can verify in their current context. Bare "DON'T X" without
+"INSTEAD: Y" is a no-op for a stateless reader.
+
+In a description, this shows up in the why-distinct clause:
+
+- **Anti**: "Don't use this for short prompts."
+- **INSTEAD**: "Use for prompts ≥3 sentences; for one-liners, see /value-prop flash."
+
+The negation lives in context (when not to use). The substitute names the actionable path (which skill to use instead).
+
+## Plain language (per /kiss words)
+
+Grade-10 reading level. Common substitutions bassclef-substrate writers should make:
+
+| Replace | With |
+|---|---|
+| "composer" | "runs" / "chains" / "combines" |
+| "primitive" | "building block" |
+| "tier-preset" | "preset" / "size" |
+| "operationalize" | "do" / "ship" |
+| "load-bearing" | "required" / "must work" |
+| "blast radius" | "impact" / "what it can break" |
+| "substrate" | "system" / "framework" |
+| "bassclef" (in description body) | use sparingly; prefer "the framework" |
+| "compose-with" | "uses" / "builds on" |
+| "scope-bounded" | "small" / "tight" |
+
+If the description still uses bassclef jargon after substitution,
+the description was assuming context the engineer doesn't have.
+Rewrite further.
+
+## What MUST NOT appear in a description
+
+- References to other skills the engineer hasn't read yet (skill names OK; methodology references aren't)
+- Methodology chains ("X → Y → Z → ...")
+- Tier specifications without explaining what the tier does
+- Citations to bassclef issues (those go in the body)
+- Dates / versions / "renamed from X on Y" (those go in the body)
+- Assumed pipeline knowledge ("Phase 14 of the buildable-spec chain")
+
+## What MUST appear in a description
+
+- The verb-outcome opener
+- A concrete sense of what the user gets back
+- A distinguishing characteristic vs. adjacent skills
+- **Modes / tiers / sizes named inline when frontmatter declares them** (bassclef#535) — see next section
+
+## Description-mirrors-modes (bassclef#535)
+
+When a skill's frontmatter declares structured `modes:` / `tiers:` / `sizes:` (per bassclef#515), the description **text** MUST name each declared value inline. Operators see Claude Code's type-ahead BEFORE invoking `/skills`; type-ahead reads only the `description` field. Frontmatter `modes:` is machine-readable for bassclef's audit + render pipeline but invisible to type-ahead.
+
+**The discipline:**
+
+- If frontmatter has `modes: [scope, words]`, description must contain "scope" AND "words" (typically as "Two modes — scope ... and words ..." or similar)
+- If frontmatter has `tiers: [quick, light, medium, full]`, description must name all four
+- If frontmatter has `sizes: [flash, tweet, brief, verbose]`, description must name all four
+- Skills with `no_user_modes: true` (opt-out) are exempt
+- The 280-char ceiling still applies — naming N modes that won't fit means the description is over-claiming; collapse the verbiage around them
+
+**Why mirror, not auto-render?**
+
+Type-ahead reads `description`. bassclef doesn't control the harness; we control the data we put in `description`. Mirroring is the cheap fix that makes type-ahead useful for mode-bearing skills today. Frontmatter `modes:` stays machine-readable for `/skills` catalog rendering + audit + future structured uses; description text stays human-readable for type-ahead.
+
+**Conformance examples (all 7 skills with modes today):**
+
+| Skill | Frontmatter | Description names them? |
+|---|---|---|
+| `/value-prop` | `sizes: [flash, tweet, brief, verbose]` | ✓ "Four sizes — flash ... tweet ... brief ... verbose" |
+| `/kiss` | `modes: [scope, words]` | ✓ "Two modes — scope ... and words ..." |
+| `/stage` | `sizes: [quick, light]` | ✓ "Two sizes: quick ... and light ..." |
+| `/launch` | `sizes: [medium, full]` | ✓ "Two sizes: medium ... and full ..." |
+| `/shape` | `tiers: [quick, light, medium, full]` | ✓ "four sizes — quick, light, medium, full" |
+| `/longrun` | `modes: [prep, checkpoint, closeout]` | ✓ "three modes — prep, checkpoint, closeout" (after bassclef#535) |
+| `/interpret-input` | `modes: [text, url, image, repo, transcript, napkin, mixed]` | ✓ types listed in parens |
+| `/onboard-repo` | `modes: [default, --with-deploy-host, --with-secrets, --full]` | ❌ pending — fold into LR8.6 PR #526 amendment |
+
+**Mechanical enforcement (deferred follow-on):**
+
+- `scripts/audit-skills-modes.sh` (bassclef#515 PR #519) extends with `description-doesnt-mirror-modes` finding type
+- `.claude/hooks/substrate-clarity-gate.sh` extends with the same check at PreToolUse Edit/Write time
+- Both gated behind bassclef#515 + bassclef#382 landing first; until then, this rule is methodology-level + the operator runs the audit manually
+
+**Override:**
+
+`SKIP_DESCRIPTION_MIRRORS_MODES=1` per-call override (logged via trace-helper). Use only when the frontmatter declares modes that are too numerous to mention inline (>5) AND a higher-level grouping description suffices.
+
+## Worked examples — applying the rule
+
+### /sprint (before)
+
+> "Show current iteration goal, open issues by priority, and proposed next sprint. Quick orientation for any session."
+
+132 chars. Decent — verb opener, outcome named. Could be tighter on
+why-distinct. **Score: B+. Acceptable.**
+
+### /sprint (after)
+
+> "Show what's in flight and what's next. Reads project state, open issues, and the active iteration goal; proposes the next sprint. Run at session start to orient."
+
+161 chars. Verb-outcome stronger. Why-distinct (when to use) explicit. **Score: A.**
+
+### /longrun (before)
+
+> "Self-checkpointing long-session lifecycle (prep / checkpoint / closeout). Orchestrator-gated sequential by default. Use when ≥2 active goals OR estimated >50 turns OR session crosses compaction. Composes /temperance, /retro, /promote, /session-end. Replaces manual mid-session reflection that defeats fire-and-forget intent."
+
+322 chars. Methodology-laden. "Orchestrator-gated sequential" is jargon. Composes-list dumps internal references. **Score: D.**
+
+### /longrun (after)
+
+> "Run a long autonomous session that paces itself — prepares scope, checkpoints at phase boundaries, closes with chronicle + journal entry + retro. Use for sessions over 50 turns or with multiple bets. Replaces mid-session manual reflection."
+
+249 chars. Outcome-first. Plain language. When-to-use explicit. **Score: A-.**
+
+### /launch (formerly /preview-build) (before)
+
+> "BUILD-tier composer (Construction transition). Chains the prototype pipeline (input → variants → gallery → bind-subdomain) PLUS the buildable-spec pipeline (use-case → user-stories → ia-model → interaction-design → decompose → spec → ux-migration). Tiers: medium (~1 day, 3 variants + buildable spec + INVEST stories + GRASP matrix) and full..."
+
+571 chars (truncated). Methodology dump. Tier specs without context.
+**Score: F.**
+
+### /launch (after)
+
+> "Turn an idea into a buildable plan. Produces a clickable mock gallery PLUS the spec, decomposition, and migration plan needed to actually build the chosen direction. Two sizes: medium (~1 day) and full (~audit-grade). Operator dispatches when ready to ship."
+
+275 chars. Outcome-first. The "PLUS" makes the differentiator vs.
+/stage (formerly /preview) clear. Tiers framed by time budget, not internal methodology.
+**Score: A.**
+
+## Application
+
+### Per skill (rewrites)
+
+1. Read existing description
+2. Score against rule (Verb? Outcome? ≤280 chars? Jargon? Plain language?)
+3. Rewrite if score < B
+4. Test the rewrite: would a senior engineer with no bassclef context understand it in 60 seconds?
+
+### Per longrun (audit)
+
+The audit issue (bassclef#375 + sister WU-3 issues) tracks
+per-skill rewrites. WU-6 of this longrun ships top-7 (data + judgment
+based) as in-scope examples; rest filed as follow-up.
+
+### Per new skill
+
+Every new skill's description goes through this rule before merge.
+Test: paste the description into a Slack DM to a senior engineer
+without bassclef context. If they ask "what does this DO?" you
+violated the rule.
+
+INSTEAD of testing against a bassclef-savvy reader: test against
+a fresh reader who carries no internal vocabulary. That's the
+audience the description has to serve.
+
+## Relationship to other rules
+
+- `.claude/rules/context-engineering.md` — the foundational rule; this is one application
+- bassclef#357 (autonomous-run flash + kiss) — sibling discipline at output surface; this rule is at description surface
+- bassclef#367 (section-heading standardization) — sibling specificity discipline
+- bassclef#339 (plan-enumeration-needs-value-props) — sibling at choice-presentation surface
+
+## Override
+
+There is no override. Skill descriptions are an entry surface for
+engineers and operators. Violating the rule means engineers won't
+adopt the skill, regardless of how good the skill itself is.
+
+If you can't write the description per the rule, the skill's job
+isn't clear enough — clarify the skill before clarifying the
+description.
+
+## Audit pattern
+
+```bash
+# Find skills whose descriptions exceed 280 chars
+grep -r "^description:" .claude/skills/*/SKILL.md | awk -F: '{ if (length($0) > 280) print $0 }'
+
+# Find skills whose descriptions use bassclef jargon
+git grep -niE 'composer|primitive|tier-preset|operationalize|load-bearing|blast radius|compose-with' .claude/skills/*/SKILL.md | grep -E '^.*:description:'
+```
+
+## Sources read
+
+- `.claude/rules/context-engineering.md` (bassclef#371) — foundational rule
+- bassclef#357 — sibling output-surface rule
+- bassclef#367 — sibling specificity rule
+- `.claude/skills/value-prop/SKILL.md` — flash mode (≤180 chars analog)
+- `.claude/skills/kiss/SKILL.md` — words mode (plain-language analog)
+- Anthropic `frontend-design` skill description — direct exemplar; bassclef declares this as baseline-composes-with in `/frontend-design`, `/riff-prototypes`, `/launch`, `/visual-review` skill frontmatter rather than carrying it as a luminary entry

package/substrate/.claude/rules/skill-procedure-step-list.md

@@ -0,0 +1,137 @@
+---
+tier: lite
+description: Before executing any SKILL procedure, I write the numbered step list into the response.
+---
+
+# Skill-procedure step-list
+
+Before executing any SKILL procedure, I write the numbered step list into the response. Each step is marked `[x]` executed with source cited OR `[~]` explicitly deferred with reason. No `[ ]` unchecked lines ship at output time. Silence is not deferral.
+
+This rule extends `.claude/rules/assert-only-after-verify.md` from the assertion surface to the SKILL-procedure surface. It is the methodology layer. The mechanical layer is `.claude/hooks/skill-step-list-check.sh` — Stop hook that scans the transcript for a Skill dispatch followed by an assistant response without a step-list block.
+
+## Why this rule exists
+
+Session 2026-08-05a dispatched `/roadmap-reconcile --dry-run` during `/longrun` prep. The SKILL procedure names 5 steps. I ran Step 1 (enumerate surfaces), skipped Step 2 (read shipping reality), and jumped to Step 3 (build a diff). I substituted whereami queue narrative for the actual `gh pr view` + `gh issue view` cross-check Step 2 requires. Four stale drift rows shipped. Operator caught the class in one turn — three closed tickets (#1050, #1051, #1054) shown as pending because whereami queue said so and no cross-check verified.
+
+Memory alone catches nothing at write time. Two existing rule + hook pairs prove the pattern holds at scale — `.claude/rules/assert-only-after-verify.md` + `.claude/hooks/assert-verify-steering.sh`, and `.claude/rules/plain-english-discipline.md` + `.claude/hooks/turn-prose-kiss-check.sh`. This rule is the third pair, at the SKILL-procedure surface.
+
+## When this rule fires
+
+Every SKILL dispatch. Agents self-check before writing the response. Hook fires at Stop event as the write-time backstop.
+
+Fires on:
+
+- Any Skill tool dispatch in the current turn
+- Any SKILL body whose procedure names 2+ steps
+
+Passes through on:
+
+- Non-Skill tool calls (Bash, Read, Edit, Write, Grep, etc.) — those follow their own discipline rules
+- SKILL body procedures with 0 or 1 step (no list needed)
+- Tool-output relays (test output, git output) that carry no assertions of their own
+
+## What the rule requires
+
+Before shipping any response following a SKILL dispatch:
+
+1. **Read the SKILL body Procedure section.** Enumerate the numbered steps.
+2. **Write the step list at the top of the response.** Format: `Step N — <name>` followed by a status marker.
+3. **Execute each step.** Cite the source inline as it runs.
+4. **Mark each step's status:**
+   - `[x]` executed with source cited
+   - `[~]` explicitly deferred with reason (silence is not deferral)
+   - Do not ship `[ ]` unchecked at output time.
+     INSTEAD: mark every step `[x]` or `[~]` before the response ships. Unchecked shipped equals silent skip.
+5. **Loaded context is a hint, not a substitute for a source read named by a step.** The context feels full. That is when the skip is easiest and the drift is worst.
+   INSTEAD: cite the source per the SKILL step. Loaded context is a hint, not a substitute.
+
+## Format contract
+
+Each step line matches one of these shapes:
+
+- `Step N — <name> — [x] <source cited>`
+- `Step N — <name> — [~] <deferral reason>`
+
+Or a block header + list format:
+
+```
+Steps:
+- Step 1 — <name> — [x] <source>
+- Step 2 — <name> — [~] <reason>
+```
+
+The hook scans for two markers together: the token `Step\s+\d+` AND either `[x]` or `[~]` bracketed. Both must appear in the assistant text following a Skill dispatch.
+
+## Anti-patterns
+
+These shapes fail this rule.
+
+**Dispatch skill; write results with no step list.** The response ships without any `Step N` markers. Hook fires ADVISORY (or BLOCK under strict toggle).
+INSTEAD: enumerate the SKILL procedure steps at the top of the response before running them.
+
+**Silent skip.** A step gets no `[x]` and no `[~]` line — the response simply omits it.
+INSTEAD: every step from the SKILL procedure appears in the response, either done or explicitly deferred with reason.
+
+**Context as substitute.** Loaded context carries a plausible answer. Skip the SKILL step; use the context.
+INSTEAD: cite the source per the SKILL step. Loaded context is a hint, not a substitute for the read the step names.
+
+**Half-written list.** Some steps carry markers; others do not.
+INSTEAD: every step marked before response ships. Half-written lists cause reviewer confusion + trigger the hook.
+
+## When this rule does NOT fire
+
+- Tool-output relays (test output, git output) — no assertion of the agent's own
+- SKILL body with 0 or 1 step — no list needed
+- Skill invoked purely for its output display (e.g., `/whereami` for a status snapshot)
+- Chat responses that do not follow a Skill dispatch
+
+## Override
+
+`SKIP_SKILL_STEP_LIST=1 <command>` — per-call bypass, logged via trace-helper. Use rarely:
+
+- One-shot migration scripts that dispatch many SKILLs at once
+- Emergency rescue when the hook itself misbehaves
+- Explicitly-deferred rework where the step list ships in a follow-up response
+
+For routine SKILL dispatches, write the step list. The cost is small; the audit trail compounds.
+
+## Toggle
+
+The hook reads `SKILL_STEP_LIST_TOGGLE` from env OR `skill_step_list.toggle` from `.claude/bassclef-configs.jsonc`:
+
+- `true` (default) — advisory (exit 0, findings to stderr)
+- `strict` — strict (exit 2, blocks the stop event, forces a rewrite)
+- `false` — silent (exit 0, no scan)
+
+V1 ships advisory. V2 may flip to strict after a calibration cycle observes drift stays under 10%.
+
+## Anchor luminaries
+
+- `.claude/luminaries/saltzer-schroeder.md` (Saltzer & Schroeder 1975, IEEE 63(9)) — complete mediation. Every access to protected state is checked. Whereami narrative was a cached authorization. Rule + hook forces mediation at every SKILL dispatch.
+- `.claude/luminaries/tony-hoare.md` (Hoare 1969, CACM 12(10)) — pre/postcondition triple. Each step's postcondition is the next step's precondition. Skip breaks the chain.
+- `.claude/luminaries/michael-feathers.md` (Feathers 2004) — characterization tests. Pin actual behavior via source of record before naming it.
+- `.claude/luminaries/kent-beck.md` (Beck 2002) — list-before-execute. Sister discipline at test surface applied to SKILL surface.
+
+## Composes with
+
+- `.claude/rules/assert-only-after-verify.md` — parent discipline at claim surface; this rule extends to SKILL-procedure surface
+- `.claude/rules/bootstrap-pair-discipline.md` — pair-shape pattern (rule + hook + Tier 0 test)
+- `.claude/rules/substrate-as-system.md` — ADR-035 tenet
+- `.claude/rules/test-list-discipline.md` — Beck's list-before-execute sister rule at test surface
+- `.claude/rules/testing-tier-config.md` — Tier 0 strict TDD on hook + tests
+- `.claude/rules/we-dont-break-adopters.md` — V1 ADVISORY default preserves adopter behavior
+- `.claude/rules/blocked-items.md` — BLOCK protocol the hook fires under strict toggle
+- `.claude/hooks/skill-step-list-check.sh` — mechanical implementation
+- `.claude/hooks/tests/skill-step-list-check.test.sh` — Tier 0 test coverage (10 tests)
+
+## Refs
+
+- sunj-labs/bassclef-upstream#1119 — parent ticket
+- Session 2026-08-05a `/diagnose` output — root cause named (SKILL step skip + context-as-substitute)
+- Memory `feedback_skill_procedure_step_list_before_execute` — evidence anchor
+- Goal doc `docs/iteration-bets/2026-08-05a-skill-step-list-plus-whereami-hygiene.md` — bet frame
+- Sister ticket sunj-labs/bassclef-upstream#1121 — in-turn error stream subsystem (broader observability)
+
+## Retirement condition
+
+This rule retires only if SKILL dispatch stops being the primary agent-to-substrate composition path. The mechanical layer may evolve (additional detection heuristics, integration with error-stream subsystem #1121). The discipline of write-time step verification persists.

package/substrate/.claude/rules/state-schema-validation.md

@@ -0,0 +1,162 @@
+---
+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.
+
+## Retirement condition
+
+This rule retires only if the state spine retires. The schemas may
+evolve (v1 adds Persona accessor methods; v2+ adds template entities)
+but the discipline of write-time validation persists.