@thebassclef/lite 0.1.3 → 1.0.0

package/substrate/standards/state-spine.md

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

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