@thebassclef/lite 0.0.1 → 0.1.2

package/substrate/standards/state-spine.md

@@ -0,0 +1,511 @@
+---
+tier: lite
+description: "Schema'd JSON state spine for bassclef's substrate."
+---
+
+# State Spine
+
+Schema'd JSON state spine for bassclef's substrate. Replaces the current
+files-and-text-scraping substrate with typed entities, validated at write
+time, queryable via accessor library. Foundation for the cameo
+fanout pipeline's Phase B+ work.
+
+## Sources read
+
+- `docs/iteration-bets/2026-04-27-state-spine-v0.md` — bet spec (WU-1 acceptance)
+- `strategy/canvases/2026-04-26-state-spine.md` v4 — load-bearing canvas (entity model, ubiquitous language, accessor discipline, replay-determinism + write-once-immutable rules)
+- `architecture/decisions/ADR-015-state-schema-format.md` — JSON Schema only for v0
+- `standards/whereami-schema.md`, `standards/deferred-actions-schema.md`, `standards/preview-state-schema.md`, `standards/substrate-config-schema.md`, `standards/persona-schema.md` — five existing schema standards being formalized as JSON Schema files
+- `.claude/luminaries/martin-fowler.md` — Repository pattern (informs accessor surface), expand-and-contract migration
+- `.claude/luminaries/gang-of-four.md` — six selected patterns per canvas Stage 2
+
+## What I'm NOT reading (with reason)
+
+- Specific JSON Schema implementation libraries — schema author chooses; ajv (bash-side) and any TS validator (when v1 lands) both consume draft-2020-12
+- Existing markers' on-disk format — WU-4's pre-read; this standard defines target shape, not migration mechanics
+
+## Why this exists
+
+Before the spine, bassclef state lived in six storage substrates with
+no schema, no atomic operations, no validation, no concurrent-write
+safety: loose markers, markdown chronicles, YAML-ish frontmatter, the
+whereami structured-text artifact, git reflog, `/tmp/*` scratch markers.
+Every consumer wrote its own bash text-scraper. Four substrate-defects
+on 2026-04-26 (#293, #295, #296, #298) traced to the same root: state
+was not a first-class noun.
+
+The spine establishes state as the noun. Schema'd JSON files in git
+form the foundation for every adopter — portable, mobile-friendly, no
+infrastructure required. cxdb upgrade (bassclef#300) is an OPTIONAL
+upgrade for adopters running concurrent multi-agent fanout; most never
+need it.
+
+## Conceptual model — four categories
+
+Bassclef's state, runtime, and rulebook fit into four MECE categories.
+Each has a primary verb. Knowing which category a thing belongs to
+tells you where it lives, who writes it, and how it changes.
+
+| Category | What it is | Primary verb | Where it lives |
+|---|---|---|---|
+| **Content** | Durable code — the rulebook | EDIT (rarely; reviewed) | `.claude/skills/`, `.claude/rules/`, `.claude/hooks/`, `.claude/agents/`, `standards/`, `architecture/` |
+| **Entities** | Mutable state with identity | UPDATE (driven by Events) | `docs/`, `state/`, root singletons (`docs/whereami.md`, `substrate.config.md`) |
+| **Events** | Things that happened (immutable, instantaneous) | FIRE (once) | No primary on-disk form; manifest as Entity field updates + Records |
+| **Records** | Written artifacts documenting Events | APPEND (write-once) | `chronicle/`, `state/markers/`, `docs/deferred-actions/`, `last_event` field on Roadmap |
+
+This frame connects to bassclef#342's drawer separation:
+**Content lives in `.claude/` + `standards/` (rulebook). Entities + Events + Records live in `docs/` + `state/` + `chronicle/` (runtime).**
+
+### The trinity (passive vs. active vs. checkpoint)
+
+Three role-types interact across the categories:
+
+| Role | What it is | Verb | Example |
+|---|---|---|---|
+| **Task** | Active driver — work to be done | DO | A WorkUnit row in `next_work_units`; workers claim, execute, release |
+| **Gate** | Checkpoint asking "ready to proceed?" | GUARD | `/temperance`, `/verify`, `/diagnose`, citation gate |
+| **Marker** | Passive recording of a Gate firing | DOCUMENT | The `.marker` file recording temperance fired on this branch |
+
+**Tasks DO. Gates GUARD. Markers DOCUMENT what happened.**
+
+A Task can't start until its Gate passes; once it passes, the Marker is
+the proof. Tasks are Entities (have lifecycle: created → claimed →
+released). Gates are Events (fire once). Markers are Records (written
+once, read many).
+
+### Verbs across the model
+
+| Operating on | Verbs |
+|---|---|
+| Entity | create / add → update (state transitions driven by Events) → archive / close / abandon |
+| Event | fire (an Event happens — instantaneous) → trigger Records (write the audit trail) |
+| Record | append (write-once, immutable per Helland) — never mutated, only superseded by new records |
+| Content | edit (operator-managed; reviewed via PR; bassclef-evolution gate) |
+
+### Where current bassclef entities fit
+
+| Bassclef entity | Category | Notes |
+|---|---|---|
+| Roadmap | Entity | Has identity (slug); state mutates via append to `last_event` + `next_work_units[*].status` projections |
+| IterationBet | Entity | Lifecycle: active → closed/abandoned |
+| Stack | Entity | Lifecycle: created → branches-resolved → merged |
+| `Step` (formerly `Workunit`, Task) | Entity (and the active driver per the trinity) | Lifecycle: pending → in_progress → completed/abandoned |
+| Decomposition | Entity | Snapshot at moment of design |
+| InputArtifact | Entity | Lifecycle: created → consumed |
+| Session | Entity | Lifecycle: started → compacted/continued/ended |
+| DeferredAction | Entity AND Record | Command pattern — written once with payload, has lifecycle (claim → resolve) |
+| InboxWorkItem | Entity AND Record | Same — Command pattern |
+| Persona | Entity | Mutable definition; v0 schema only |
+| Whereami | Entity (singleton) | Snapshot mutated by `state_whereami_set` |
+| SubstrateConfig | Entity (singleton) | Per-repo external resource manifest |
+| BassclefPlatform | Entity (singleton, sibling-repo) | Org-baseline platform manifest — sibling-repo placement (e.g., `sunj-labs/platform-config`) sets the enterprise-adoption seam |
+| PreviewState | Entity (per-slug) | Per-product preview-cycle state |
+| StackTemplate | Content (durable code, parameterizable) | Treated like a skill — versioned, reusable |
+| TemplateInstance | Record | Audit "StackTemplate X instantiated as Stack Y at time Z" |
+| Marker | Record | Persistence of a Gate firing |
+| Chronicle | Record | Narrative session retrospective |
+| Gate | Event | Has no on-disk form — manifests as Marker (recorded form) |
+
+### Event types bassclef recognizes
+
+Events fire constantly in an active session. Most leave Records (Markers
+or chronicle entries); some only mutate Entity state.
+
+| Event class | Examples | Recorded as |
+|---|---|---|
+| Gate firings | temperance fired (pass/fail/skip), verify fired, diagnose fired, citation-gate fired | Marker |
+| Task lifecycle | task-created, task-claimed, task-released, task-abandoned, task-blocked | `last_event` field + `next_work_units[*].status` projection |
+| Bet lifecycle | bet-opened, bet-closed, bet-abandoned, scope-changed | Iteration-bet `status` field; chronicle |
+| Roadmap lifecycle | roadmap-created, milestone-passed, phase-boundary-crossed | Roadmap `last_event` field |
+| Session lifecycle | session-started, session-compacted, continued-as, session-ended | Session entity `continued_as` field; chronicle |
+| Operator decision | scope-confirmed, audit-caught-issue, defer-accepted | Chronicle decision-log; ad-hoc |
+| Discovery | discovery-captured (operator/agent insight worth preserving) | `design/discoveries/<slug>.md` (Record); see bassclef#349 for first-class entity status |
+
+### Read this section before extending the spine
+
+When you propose a new entity for the spine, decide first:
+
+1. **Is it Content, Entity, Event, or Record?**
+2. **What verbs operate on it?** (the answer tells you what accessors to write)
+3. **If Entity: what events drive its state transitions?** (those events should be recorded somewhere)
+4. **If Record: what events does it document?** (and is the schema strict enough to validate the recording shape?)
+
+Misclassifying — e.g., proposing a "Risk Entity" but only providing
+narrative without lifecycle accessors, or proposing a "Gate Record"
+that's actually an Event — leads to the kind of substrate drift the
+spine v0 retired (#293, #295, #296, #298).
+
+## Entity catalog (17 v0)
+
+Four layers per canvas v3 entity audit. Each entity has a JSON Schema
+file at `standards/state-spine/schemas/<entity>.schema.json`.
+
+### Work composition (durable data, collection — 6 entities)
+
+| Entity | Role | DDD framing |
+|---|---|---|
+| Roadmap | Top-level multi-bet plan | Aggregate root over IterationBets |
+| `IterationBet` | Scoped commitment with time budget (Shape Up: `appetite`; Yegge: Epic) | Aggregate root over Stacks |
+| Stack | Branch-stacking dependency manifest for parallel work (Yegge: Molecule) | Aggregate root over Workunits |
+| `Step` (formerly `Workunit`, aka `WU`) | Atomic deliverable, becomes one PR (Yegge: Bead) | Entity (1 PR + 1 issue + 1 branch identity) |
+| Decomposition | Pre-build entity-responsibility map for a step (formerly `workunit`) | Value object (snapshot at moment of design) |
+| InputArtifact | Normalized intermediate from operator input (text/URL/image/repo/transcript) — see PR #304 | Entity (own identity per input session); produces value-object payload |
+
+### Templates (durable code, sibling to composition — 1 v0 entity)
+
+| Entity | Instantiates as | Notes |
+|---|---|---|
+| StackTemplate | Stack | LOAD-BEARING for cameo fanout (N parallel workunits from one template) |
+
+BetTemplate, WorkunitTemplate, RoadmapTemplate defer to v2+ per canvas.
+
+### Execution events (durable history, collection — 7 entities)
+
+| Entity | Role | Sourcing framing |
+|---|---|---|
+| Session | Single execution context (one chat). Includes `continued_as: <next-session-id>` field (SWF `continue_as_new` analog) | Aggregate root over Gates + Markers within session |
+| Gate | Compliance event (Marker is its persistence form) | Domain event (Greg Young: write-once event in the log) |
+| Marker | Gate's persistence form (filename = stable id; payload = event body) | Value object (Helland: data on the outside) |
+| Chronicle | Session retrospective narrative + sidecar JSON `gates_fired` | Read-side projection of Gates (CQRS read model) |
+| InboxWorkItem | GoF Command — encapsulated work request routed between agents | Command (Greg Young: command bus) |
+| TemplateInstance | Audit record: "StackTemplate X instantiated as Stack Y at time Z with parameters P" | Domain event |
+| DeferredAction | Capability-routed handoff entry (per bassclef#226) — read by `60-deferred-actions.sh` at session-start | Command (deferred to capable session) |
+
+### Singletons (one-per-repo — 3 entities)
+
+| Entity | Role |
+|---|---|
+| Whereami | Project state snapshot — phase, active iteration, active agents, subsystem phases |
+| SubstrateConfig | Repo manifest (gating, agents, deploy targets, external resource refs) |
+| PreviewState | Per-product preview chain state (slug, current_tier, status, selected_variant, escalation history) |
+
+### Persona — v1 deferral (separate entity)
+
+Persona is schema'd via `standards/persona-schema.md` and consumed by
+`/personas`, `/value-prop-canvas`, `/jtbd-tasks`, `/synthetic-user`,
+`/risk-test-synthetic`, `/user-stories`. Not hot-path-read at
+session-start; schema file ships in WU-1 for completeness, but
+accessor methods defer to spine v1 (no spine v0 hot-path consumer
+needs Persona reads).
+
+**v0 entity count = 17** (with Persona ported as an v0 schema file but
+its accessor methods deferred to v1; matches canvas v3 audit).
+
+## Ubiquitous language (Evans DDD)
+
+Bassclef lexicon. One name per concept, used consistently across
+schemas, accessor methods, hooks, skills, and operator-facing surfaces.
+
+| Term | Definition | Avoid |
+|---|---|---|
+| `Step` (formerly `Workunit`, aka `WU`) | Atomic deliverable becoming one PR | "WS" (legacy), "workpackage" (PMBOK term, ported in PR #304), "task" (too generic) |
+| `Iteration Goal` (formerly `Iteration Bet`) | Scoped commitment with time budget (Shape Up: `appetite`); Yegge analog is Epic | "story" (too small), "feature" (too vague) |
+| Stack | Multi-step (formerly multi-`WU`) dependency manifest for parallel work; Yegge analog is Molecule | "branch group" (loses dependency semantics) |
+| Gate | Compliance event triggered by methodology rule | "check" (too vague), "verification" (too narrow) |
+| Marker | Persisted form of a Gate (filename = stable id) | "log entry" (loses gate semantics) |
+| Chronicle | Session retrospective narrative + sidecar JSON | "log", "diary" |
+| Roadmap | Multi-bet plan over weeks-to-months horizon | "plan" (too generic), "spec" (different concern) |
+| Decomposition | Pre-build entity-responsibility map (output of `/decompose`) | "design" (too broad) |
+| InputArtifact | Normalized intermediate from operator input (text/URL/image/repo/transcript) | "input", "spec source" |
+| StackTemplate | Parameterizable Stack definition that instantiates concrete Stacks | "template" (too generic) |
+| Whereami | Project-state snapshot artifact (one per repo) | "status", "state file" |
+| SubstrateConfig | Repo manifest of external resource references | "config" (too generic) |
+| PreviewState | Per-slug preview-cycle state | "preview status" |
+| DeferredAction | Capability-routed cross-modality handoff entry | "TODO", "deferred work" |
+
+## Storage format — four shapes among v0 entities
+
+Not every entity is stored as pure JSON. The schema defines the
+contract; the on-disk shape varies by entity-type ergonomics. WU-3's
+validator hook (`state-validate.sh`) detects entity type from path
+and applies the appropriate extractor + validator.
+
+### Shape A — JSON authoritative + markdown rendered (singletons)
+
+| Entity | On-disk | Schema validates |
+|---|---|---|
+| Whereami | `docs/whereami.json` (auth) + `docs/whereami.md` (rendered, auto-generated banner) | whole JSON file |
+| SubstrateConfig | `substrate.config.json` (auth) + `substrate.config.md` (rendered) | whole JSON file |
+| PreviewState | `docs/preview-state/<slug>.json` (auth) + `<slug>.md` (rendered) | whole JSON file |
+
+Operator never edits the markdown. Mutations go through accessor
+(`state_<entity>_set`); markdown re-renders on demand. Per-field
+narrative migrates to chronicles (typed `references` array).
+
+### Shape B — Markdown + YAML frontmatter + narrative body (collection entities with operator-readable bodies)
+
+| Entity | On-disk | Schema validates |
+|---|---|---|
+| DeferredAction | `docs/deferred-actions/<id>.md` (frontmatter + body) | YAML frontmatter only |
+| Chronicle | `chronicle/<id>.md` (frontmatter + narrative) + optional `chronicle/<id>.json` sidecar for gates_fired | frontmatter + sidecar |
+| IterationBet | `docs/iteration-bets/<slug>.md` (frontmatter + body) | YAML frontmatter only |
+| Roadmap | `docs/roadmaps/<slug>.md` (frontmatter + body) | YAML frontmatter only |
+| Stack | `docs/stacks/<slug>.md` (frontmatter + body) | YAML frontmatter only |
+| Decomposition | `docs/decompositions/<slug>.md` (frontmatter + body) | YAML frontmatter only |
+| `Step` (formerly `Workunit`) | inline within Stack body OR `docs/workunits/<slug>.md` | YAML frontmatter only |
+| Persona | `docs/personas/<slug>.md` (frontmatter + body, per persona-schema.md) | YAML frontmatter only |
+
+Validator extracts YAML frontmatter from `*.md` files and validates
+against `<entity>.schema.json`. Body sections (Procedure, Acceptance,
+Sources read, Notes, etc.) stay markdown for operator readability —
+the schema doesn't constrain them.
+
+### Shape C — Pure JSON (machine-only, no narrative needed)
+
+| Entity | On-disk | Schema validates |
+|---|---|---|
+| Marker | `state/markers/<category>/<uuid>.json` (relocated from `.claude/gate-markers/` per bassclef#342 — markers are runtime workflow events, belong in `state/` runtime drawer not `.claude/` rulebook drawer) | whole file |
+| Gate | derived from Marker via accessor; no on-disk file (Gate is the abstract event; Marker is the persistence) | n/a |
+| TemplateInstance | `state/template-instances/<uuid>.json` | whole file |
+| InboxWorkItem | `state/inbox/<uuid>.json` | whole file |
+| Session | `docs/sessions/<id>.json` (sidecar to existing `docs/sessions/<id>.md` session-board) | JSON file |
+| InputArtifact | `docs/input-artifacts/<slug>.json` | whole file |
+| StackTemplate | `state/stack-templates/<slug>.json` | whole file |
+| SubstrateHardening | `state/substrate-hardening/inventory.json` (per bassclef bet 2026-06-17a Phase Z) | whole file |
+
+These entities are machine-consumed; operator-readability isn't
+load-bearing. Pure JSON; schema validates the whole file.
+
+### Shape D — Pure YAML (operator-edited, sibling-repo) — added bassclef#462
+
+| Entity | On-disk | Schema validates |
+|---|---|---|
+| BassclefPlatform | `<sibling-repo-root>/bassclef-platform.yml` (e.g., `~/src/sunj-labs/platform-config/bassclef-platform.yml`) | whole file |
+
+One entity, one shape. Pure YAML because:
+- The file is operator-edited by hand on first adoption — flat YAML is
+  the lowest-ceremony format that survives mobile editing.
+- The file lives in a SIBLING repo (not bassclef) so that adopters can
+  fork and edit per-org without forking bassclef itself.
+- Validator extracts whole-file as YAML → JSON; same ajv-cli draft-2020
+  validation as Shape A/C.
+
+Distinct from Shape A: no markdown rendered companion, no JSON
+authoritative form. The YAML IS the source of truth.
+
+### Why four shapes, not one
+
+Forcing every entity into pure JSON would lose operator-readability
+where it matters (DeferredAction body explains how to resolve;
+Chronicle narrative is the retrospective; IterationBet body is
+substantive scope). Forcing every entity into markdown would lose
+machine-consumability where it matters (Marker payload is small,
+structured, machine-only).
+
+Three shapes match three concerns. The schema validates the structured
+part regardless of shape. WU-3's validator handles all three via
+entity-type detection from path.
+
+## Schema format
+
+**Single format: JSON Schema (draft-2020-12)** per ADR-015. Zod deferred
+to v1 paired with the first TS consumer that reads state from TS code.
+
+Each entity:
+
+- Schema file: `standards/state-spine/schemas/<entity>.schema.json`
+  (filename uses kebab-case derived from the entity's SENTINEL_bassclef_name —
+  e.g., `DeferredAction` → `deferred-action.schema.json`)
+- `$id`: `https://bassclef.sunj-labs/state-spine/schemas/<entity>.schema.json`
+  (semantic identifier; not network-resolved)
+- `$schema`: `https://json-schema.org/draft/2020-12/schema`
+
+## Replay-determinism rule (canvas v4, from SWF mining)
+
+The accessor library `lib/state.sh` (WU-2) MUST derive counters and
+computed state from history on every call. **Never cache derived
+values as side state.** Same input history → same output value,
+deterministically.
+
+This is what failed in #296 (compliance-counter floor-lift): the
+counter logic had cached state that drifted from the source. Fixing
+the math without fixing the discipline left the failure-class open.
+SWF's decider replay model is the precedent — deciders re-derive
+their decisions on every poll; same history → same decisions.
+
+| Rule | Concrete shape |
+|---|---|
+| Counters re-compute on every call | `state_gate_compliance_recent N` reads markers + chronicles + computes; no `latest_compliance` field stored anywhere |
+| Markers are write-once-immutable (Helland) | Once written, marker filename + payload never updates. Updates produce NEW markers; readers consider the latest non-superseded one. |
+| Chronicles are append-only, derive-from-events | Chronicle's `gates_fired` field is computed from session's marker history at write time, not maintained out-of-band |
+| Singletons (Whereami, PreviewState) are derived snapshots | Computable from collection state. Exist as performance shortcuts + operator-readable artifacts; `state_whereami_recompute` regenerates them from source |
+
+Enforced at WU-3 by `state-validate.sh` hook (any JSON file with a
+`derived_from:` annotation gets recomputed + diff-checked at commit;
+mismatch BLOCKs).
+
+## Write-once-immutability rule (Helland — *"Immutability Changes Everything"*)
+
+Markers, Chronicles, Discoveries, Sessions are write-once. Once
+committed, the record is immutable. Updates require new records that
+supersede prior ones; readers consider the latest non-superseded
+record per business-key.
+
+This makes auditability free: every state mutation is in git history;
+no record is silently overwritten.
+
+## Relationship to existing schema standards
+
+The five existing markdown schema standards become the source-of-truth
+for their corresponding JSON Schema files:
+
+| Markdown standard | JSON Schema file |
+|---|---|
+| `standards/whereami-schema.md` | `standards/state-spine/schemas/whereami.schema.json` |
+| `standards/deferred-actions-schema.md` | `standards/state-spine/schemas/deferred-action.schema.json` |
+| `standards/preview-state-schema.md` | `standards/state-spine/schemas/preview-state.schema.json` |
+| `standards/substrate-config-schema.md` | `standards/state-spine/schemas/substrate-config.schema.json` |
+| `standards/persona-schema.md` | `standards/state-spine/schemas/persona.schema.json` |
+
+The markdown standards remain as human-readable references describing
+each entity's role + business rules. The JSON Schema files are the
+machine-readable contract enforced at write-time by `state-validate.sh`
+(WU-3).
+
+## Singleton authority — JSON authoritative; markdown rendered
+
+For singletons (Whereami, SubstrateConfig, PreviewState):
+
+- **JSON file is authoritative** (`docs/whereami.json`, `substrate.config.json`,
+  `docs/preview-state/<slug>.json`). Schema-validated at write by
+  `state-validate.sh` (WU-3).
+- **Markdown view is rendered on demand** from the JSON by the consuming
+  skill (`/whereami`, etc.). Carries `<!-- AUTO-GENERATED — edit JSON, not this file -->`
+  banner at the top.
+- **Operator never `vim`s the markdown** — edits go through accessor
+  surface (`state_whereami_set <field> <value>`, etc., per WU-2).
+- **Per-field narrative in today's whereami** (long `iteration_phase`
+  descriptions, append-only "Last updated" history block) **migrates
+  to chronicles** during WU-4. Whereami's `last_updated` field becomes
+  a single object per the schema, not a list.
+
+Why JSON-authoritative not "JSON + markdown both git-tracked":
+
+The "ship both, sync them" shape preserves operator's `vim
+docs/whereami.md` workflow but reproduces the failure mode the spine
+retires — operator-text-edits cause schema drift, consumers parse
+markdown freehand, ambiguity about which file is the source. JSON-only
+forces the discipline cleanly: state is typed, narrative is in
+chronicles (a first-class entity), markdown is a view.
+
+Authority hierarchy reminder (per accessor discipline §):
+
+| Layer | Role | Format |
+|---|---|---|
+| Collection entities (Session, Gate, IterationBet, Chronicle, ...) | Authoritative source | individual JSON files |
+| Singleton snapshot (Whereami) | Derived cache, schema-validated | JSON file |
+| Singleton view (whereami.md) | Rendered for operator | markdown (auto-generated) |
+
+`state_whereami_recompute` regenerates the singleton from collection
+state per the replay-determinism rule.
+
+## Cross-entity references — typed `references` array (v0)
+
+Entities that benefit from linking to context (chronicles, discoveries,
+ADRs, decompositions, specs) carry an optional `references: [reference]`
+array. Each reference is a typed lookup, not a path or freeform string:
+
+```json
+"references": [
+  {"type": "chronicle", "id": "2026-04-27b-spine-v0-WU-1"},
+  {"type": "adr", "id": "ADR-015", "anchor": "Decision"}
+]
+```
+
+Resolver `state_reference_get <type> <id>` returns the entity. WU-3
+validator catches dangling references (no entity at `<type>/<id>`) at
+write.
+
+### Reference type vocabulary
+
+Stable set; extend via this standard.
+
+| `type` | Looked up in |
+|---|---|
+| `chronicle` | `chronicle/<id>.md` (bassclef) or `docs/chronicle/<id>.md` (consumer repos) |
+| `discovery` | `design/discoveries/<id>.md` |
+| `adr` | `architecture/decisions/<id>.md` (e.g., id=`ADR-015-state-schema-format`) |
+| `decomposition` | `docs/decompositions/<id>.md` |
+| `spec` | `docs/specs/<id>.md` |
+| `session` | `docs/sessions/<id>.md` |
+| `iteration-bet` | `docs/iteration-bets/<id>.md` |
+| `roadmap` | `docs/roadmaps/<id>.md` |
+
+### Why typed-id, not hash-as-index
+
+Hash-as-index (content-addressed `context: "blake3:abc..."` opaque
+string with object store + reverse-index + drift detection) is the
+architecturally elegant pattern (Helland write-once-immutable,
+cxdb Blob CAS-aligned, git-tree analog). Deferred to spine v1 per
+bassclef#316 — gated on first observed context-drift incident.
+
+Same "extend on real signal" discipline as ADR-015 (single-format
+schemas; Zod deferred to v1).
+
+v0 simple typed-references suffice for the dominant case: state needs
+to point at chronicles/ADRs/decompositions for traceability, not for
+versioned integrity.
+
+## Migration bootstrap discipline
+
+Every Shape A (singleton JSON authoritative) entity ships with a migration script that bootstraps its `.json` file from the prior `.md` frontmatter representation. Adopters mid-migration keep both files; the accessor reads Tier 0 JSON when present and falls back to Tier 1 md frontmatter otherwise (per ADR-054 D3).
+
+Contract for every migration script:
+
+- Path: `scripts/migrate-<entity>-to-json.sh`
+- Idempotent: no-op when target `.json` already exists
+- Atomic write: temp file + rename per @luminary michael-nygard
+- Marker at `state/markers/migration/<entity>-json-bootstrap-<ts>.marker` per Helland write-once
+- Exit codes: 0 success / no-op; 1 both missing; 3 md malformed; 4 write failed
+- Tier 0 test coverage at `.claude/hooks/tests/migrate-<entity>-to-json.test.sh` — 5 tests: creates, idempotent, marker, both-missing, malformed
+
+Shipped for Whereami — `scripts/migrate-whereami-to-json.sh` per goal 2026-09-06d Step 3 + UC-4. Pattern reusable for SubstrateConfig + PreviewState + future Shape A entities.
+
+Extension of Cure 2 fallback to those entities is out of scope for this goal (own UC extension work per spec § Out of scope).
+
+## Relationship to other standards
+
+- `standards/whereami-schema.md`, `standards/deferred-actions-schema.md`,
+  `standards/preview-state-schema.md`, `standards/substrate-config-schema.md`,
+  `standards/persona-schema.md` — markdown specs ported into JSON Schema
+  here; markdown remains the human-readable reference
+- `standards/branch-stacking.md` — Stack entity reads stack manifests
+  per this standard
+- `standards/session-board.md` — Session entity references session
+  boards per this standard
+- `standards/artifact-composition.md` — typed cross-refs across
+  entities (parent_roadmap, parent_canvas, stack_manifest, session_board)
+  enforced via JSON Schema `$ref` where structural; verified by
+  `state-validate.sh` (WU-3)
+
+## Relationship to ADRs
+
+- **ADR-015** (this bet) — JSON Schema only for v0; Zod v1
+- **ADR-013** (substrate runtime portfolio) — orthogonal (storage
+  backend; spine v0 is filesystem-on-git; cxdb deferred to bassclef#300)
+- **ADR-014** (substrate sync strategy) — orthogonal (distribution)
+
+## Versioning
+
+Schema files versioned via `$id` URL path (e.g.,
+`/state-spine/v0/schemas/deferred-action.schema.json` for v0,
+`/state-spine/v1/schemas/...` for v1+ if breaking changes land).
+
+v0 schemas are stable through the spine v0 deprecation window. Breaking
+changes ship as v1 schemas with migration guidance per Fowler's
+expand-and-contract.
+
+## Scrutiny
+
+This standard meets the bar for bassclef inclusion because:
+
+1. WU-2 accessor library reads schemas as its contract (load-bearing)
+2. WU-3 validator hook validates writes against these schemas (load-bearing)
+3. WU-4 migration script writes data conforming to these schemas (load-bearing)
+4. WU-5 telemetry rewrite reads via accessor → ultimately reads these schemas (load-bearing)
+5. WU-6 hook updates read via accessor (load-bearing)
+6. WU-7 skill updates read via accessor (load-bearing)
+7. WU-8 `/state` skill exposes schema-typed surface to operator (load-bearing)
+
+Without these seven WU consumers, this standard would be premature
+documentation. Spine v0's full WU sequence ships them.

package/substrate/standards/steering-hints/kiss-words.md

@@ -0,0 +1,11 @@
+---
+tier: lite
+hint_id: kiss-words
+priority: high
+boundaries: [prompt-submit, skill-end, state-write]
+token_budget: 50
+refresh_interval_turns: 5
+description: Write at grade 8. Cap grade 10. Short sentences. Subject-verb-object. Drop bassclef-only words per standards/bassclef-internal-jargon.md. Keep standard tech words (API, hook, PR, schema).
+---
+
+Write at grade 8. Cap grade 10. Short sentences. Subject-verb-object. Drop bassclef-only words per standards/bassclef-internal-jargon.md. Keep standard tech words (API, hook, PR, schema).