State spine

bassclef's authoritative state layer — JSON-on-git with typed accessors so consumers do not reach into raw files.

Use this when

You are writing a skill or hook that needs to read or write bassclef state (whereami, iteration goals, deferred actions, markers). Or you are debugging why a state write did not appear where you expected.

Skip this when

You are writing code that does not touch bassclef state — your application code, your tests, your feature branch. State-spine discipline applies to the substrate, not to your product.

What it is

Every piece of bassclef's state lives in a well-known place on disk, with a well-known JSON schema. Consumers (skills, hooks, rules) read and write through typed accessors in lib/state.sh, never by direct cat or jq on the raw files.

lib/state.sh standards/state-spine.md — the entity catalog standards/state-spine/schemas/ — per-entity JSON Schema

Why it exists

Before the spine, bassclef state was scattered across /tmp files, per-hook markers, ad-hoc JSON blobs, and undocumented conventions. Session-rescue markers rotted between sandbox teardowns. Compliance counters read from different paths than the writers used. Every skill re-implemented its own read-write shape.

The spine fixes this by:

Naming every state entity in standards/state-spine.md — the catalog is the contract
Enforcing a JSON schema per entity — state-validate.sh PreToolUse hook BLOCKs writes that violate schema
Providing typed accessors — state_whereami_get, state_whereami_set, state_marker_count, etc. — that every consumer goes through

The four storage shapes

Per standards/state-spine.md § Storage format:

Shape A (singleton JSON authoritative) — e.g., docs/whereami.json
Shape B (markdown + YAML frontmatter) — e.g., docs/iteration-bets/*.md
Shape C (pure JSON per-item) — e.g., state/markers/*/*.json
Shape D (pure YAML at sibling-repo root) — e.g., */bassclef-platform.yml

Accessors abstract the shape from consumers. The consumer says "give me the current iteration bet"; the accessor knows to read Shape B frontmatter and return the fields.

Failure mode

When a skill writes to state without going through an accessor, three things break:

Schema validation is bypassed (the write may produce invalid state)
Other consumers looking through the accessor may not see the write if the accessor caches
Migrations that update the accessor forget to update the direct- writer

The state-schema-validation rule catches this at write time. The accessor-library-discipline rule catches it at code review.

.claude/rules/accessor-library-discipline.md .claude/rules/state-schema-validation.md

Accessor library — the API every consumer uses
Session log — Shape B entity for session narrative
Whereami primitive — Shape A entity for project state

State spine

On this page