@thebassclef/lite 0.1.3 → 1.0.1

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

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

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

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