@thebassclef/lite 0.0.1 → 0.1.0

package/substrate/lib/state.sh

@@ -0,0 +1,1372 @@
+#!/usr/bin/env bash
+# tier: lite
+# lib/state.sh — typed accessor library over bassclef's state spine.
+#
+# Repository pattern (Fowler PoEAA): hides storage backend (JSON-on-git
+# for v0; cxdb for opt-in adopters per bassclef#300) from consumers.
+# Adapter discipline preserves the swap surface — see exit criteria in
+# standards/state-spine-contract.md §"Adapter discipline".
+#
+# Source via: source /path/to/lib/state.sh
+#
+# Naming convention: state_<entity>_<verb>[_<modifier>]
+# Return semantics per state-spine-contract.md §"Return semantics":
+#   exit 0 = success, JSON/scalar to stdout
+#   exit 1 = not found (empty stdout)
+#   exit 2 = invalid input (stderr message)
+#   exit 3 = schema validation failed (stderr ajv error)
+#   exit 4 = filesystem error (stderr message)
+#   exit 5 = unsupported entity / verb (stderr message)
+#
+# Replay-determinism rule: counters/state derived from history on every
+# call; never cache derived values as side state. Same input history →
+# same output. (Per canvas v4 SWF mining.)
+#
+# Write-once-immutability rule (Helland): Markers, Chronicles, Sessions
+# write-once. Updates produce NEW records via supersession; no in-place
+# mutation. Forbidden verbs documented in contract.
+
+# === Internal helpers ===
+
+# __state_check_binary_deps — fail loud + early when required binaries
+# are missing from $PATH. Per bassclef#598: previously, accessor calls
+# emitted cryptic "command not found: awk / python3" errors with no
+# resolution hint. Now they emit a structured error pointing at the
+# install command.
+#
+# Idempotent: caches result in __STATE_DEPS_CHECKED so we don't grep
+# PATH on every accessor call.
+__state_check_binary_deps() {
+  if [ "${__STATE_DEPS_CHECKED:-}" = "1" ]; then
+    return 0
+  fi
+  local missing=""
+  for bin in awk python3 jq; do
+    command -v "$bin" >/dev/null 2>&1 || missing="$missing $bin"
+  done
+  if [ -n "$missing" ]; then
+    cat >&2 <<EOF
+STATE ACCESSOR FAILURE
+Required binary missing from PATH:$missing
+
+These binaries are load-bearing for lib/state.sh accessors (Shape B
+YAML frontmatter extraction + JSON tooling).
+
+Resolution:
+  macOS: brew install gawk python3 jq
+  Debian: sudo apt-get install gawk python3 jq
+
+Closes the bassclef#598 silent-failure class.
+EOF
+    return 4
+  fi
+  export __STATE_DEPS_CHECKED=1
+  return 0
+}
+
+# yq2json — extract YAML frontmatter from markdown file, emit JSON.
+# Used by Shape B (markdown + YAML frontmatter + body) entity accessors.
+#
+# Hoare postcondition (per #1497 silent-empty class cure):
+#   stdout is a valid JSON object with at least one field, OR
+#   exit code names the reason (1 file missing / 3 parse error /
+#   4 deps missing / 5 empty parse).
+#
+# Exit 5 fires when parse succeeds but the result is empty — either no
+# `---` fences in the file OR fences present with empty body between.
+# The `or {}` coerce that used to mask this class is now explicit in the
+# postcondition check.
+#
+# Adopter opt-in: STATE_ALLOW_EMPTY_PARSE=1 skips the postcondition,
+# returns `{}` exit 0 (legacy behavior). Use during migration window.
+#
+# Anchor: @luminary tony-hoare (postcondition contract) +
+# @luminary john-ousterhout (deep module — fix at helper covers all
+# 3 accessors + migration script) + @luminary michael-nygard (fail-fast
+# on invalid input) + @luminary michael-feathers (characterization
+# tests RED-first via fixtures/2026-09-06-silent-empty/).
+__state_yq2json() {
+  __state_check_binary_deps || return 4
+  local file="$1"
+  if [ ! -f "$file" ]; then
+    return 1
+  fi
+
+  # Parse cache per bassclef-upstream#1519 (Option D). Cache the JSON
+  # output per file+mtime+size within one shell process. Session-end
+  # fires N Edit calls to whereami; each triggers state-validate.sh
+  # which calls this helper. Parse cost dominates on dense frontmatter.
+  # Uses parallel indexed arrays for bash 3+ compat (macOS default is
+  # bash 3.2; no associative-array assumption).
+  # Opt-out env: STATE_DISABLE_PARSE_CACHE=1 skips cache lookup + store.
+  # Fail-safe: any stat error falls through to parse path.
+  local cache_key=""
+  if [ "${STATE_DISABLE_PARSE_CACHE:-0}" != "1" ]; then
+    # Lazy-init arrays. Caller may run under `set -u` (nounset), which
+    # trips on `${#unset_array[@]}` — initialize first if not declared.
+    if [ -z "${__STATE_YQ2JSON_CACHE_KEYS+x}" ]; then
+      __STATE_YQ2JSON_CACHE_KEYS=()
+      __STATE_YQ2JSON_CACHE_VALS=()
+    fi
+    local mtime_size
+    mtime_size=$(stat -c '%Y|%s' "$file" 2>/dev/null || stat -f '%m|%z' "$file" 2>/dev/null || echo "")
+    if [ -n "$mtime_size" ]; then
+      cache_key="${file}|${mtime_size}"
+      # Linear scan of parallel arrays. N is small per session-end (< 10).
+      local __c_i=0
+      local __c_n=${#__STATE_YQ2JSON_CACHE_KEYS[@]}
+      while [ $__c_i -lt $__c_n ]; do
+        if [ "${__STATE_YQ2JSON_CACHE_KEYS[$__c_i]}" = "$cache_key" ]; then
+          printf '%s\n' "${__STATE_YQ2JSON_CACHE_VALS[$__c_i]}"
+          return 0
+        fi
+        __c_i=$((__c_i + 1))
+      done
+    fi
+  fi
+
+  local out
+  local ec
+  out=$(awk '/^---$/{c++; next} c==1' "$file" | python3 -c "
+import sys, yaml, json
+try:
+    data = yaml.safe_load(sys.stdin) or {}
+    print(json.dumps(data, default=str))
+except Exception as e:
+    print(f'yaml parse failed: {e}', file=sys.stderr)
+    sys.exit(3)
+")
+  ec=$?
+  # Instrument real-parse count for #1519 tests + observability.
+  __STATE_YQ2JSON_PARSE_COUNT=$(( ${__STATE_YQ2JSON_PARSE_COUNT:-0} + 1 ))
+  if [ "$ec" -ne 0 ]; then
+    printf '%s\n' "$out" >&2
+    return "$ec"
+  fi
+  # Hoare postcondition — stdout must be a non-empty JSON object.
+  # Empty parse means: no frontmatter fences OR fences with empty body.
+  # Both shapes silently coerced to `{}` before this cure (per #1497).
+  if [ "$out" = "{}" ]; then
+    if [ "${STATE_ALLOW_EMPTY_PARSE:-0}" = "1" ]; then
+      # Adopter opt-in — legacy behavior, no signal.
+      printf '%s\n' "$out"
+      return 0
+    fi
+    echo "state accessor: no YAML frontmatter fences OR empty payload in $file (expected Shape A JSON OR Shape B markdown+frontmatter with fields)" >&2
+    return 5
+  fi
+  # Store in parse cache on successful parse (bassclef-upstream#1519).
+  # Empty cache_key means STATE_DISABLE_PARSE_CACHE=1 OR stat failed —
+  # skip store. Parallel arrays; append via +=.
+  if [ -n "$cache_key" ]; then
+    __STATE_YQ2JSON_CACHE_KEYS+=("$cache_key")
+    __STATE_YQ2JSON_CACHE_VALS+=("$out")
+  fi
+  printf '%s\n' "$out"
+  return 0
+}
+
+# Atomic JSON write: temp file + rename.
+__state_atomic_write() {
+  local target="$1"
+  local content="$2"
+  local tmp="${target}.tmp.$$"
+  echo "$content" > "$tmp" || return 4
+  mv "$tmp" "$target" || { rm -f "$tmp"; return 4; }
+}
+
+# yaml_write — write a single {field: value} document as safe YAML.
+# Value strings containing YAML-unsafe chars (`:`, `#`, `"`, `'`, newlines)
+# get quoted or emitted as block scalars via python yaml.safe_dump.
+# Round-trips cleanly through yaml.safe_load.
+# Sister to __state_yq2json (read side); used by session-end.sh write path
+# for the operator_recap block per goal 2026-09-06d Cure 6.
+# Anchor: @luminary tony-hoare (postcondition — yaml.safe_load succeeds on
+# output) + @luminary michael-nygard (silent-fail wrap; write does not
+# crash caller).
+__state_yaml_write() {
+  __state_check_binary_deps || return 4
+  local path="$1"
+  local field="$2"
+  local value="$3"
+  if [ -z "$path" ] || [ -z "$field" ]; then
+    echo "__state_yaml_write: requires <path> <field> <value>" >&2
+    return 2
+  fi
+  local dir
+  dir="$(dirname "$path")"
+  [ -d "$dir" ] || mkdir -p "$dir" || return 4
+  local tmp="${path}.tmp.$$"
+  BASSCLEF_YAML_FIELD="$field" \
+  BASSCLEF_YAML_VALUE="$value" \
+  BASSCLEF_YAML_TMP="$tmp" \
+  python3 -c '
+import os, yaml, sys
+field = os.environ["BASSCLEF_YAML_FIELD"]
+value = os.environ["BASSCLEF_YAML_VALUE"]
+tmp = os.environ["BASSCLEF_YAML_TMP"]
+data = {field: value}
+try:
+    with open(tmp, "w") as f:
+        yaml.safe_dump(data, f, allow_unicode=True, default_flow_style=False, width=10000)
+except Exception as e:
+    print(f"__state_yaml_write: safe_dump failed: {e}", file=sys.stderr)
+    sys.exit(3)
+' 2>&1 || { rm -f "$tmp"; return 3; }
+  mv "$tmp" "$path" || { rm -f "$tmp"; return 4; }
+}
+
+# === Whereami (Shape A — JSON authoritative + markdown rendered) ===
+
+state_whereami_get() {
+  # Cure 2 (per ADR-054 D3 fallback discipline): three-tier read.
+  # Tier 0 — docs/whereami.json (authoritative when present)
+  # Tier 1 — docs/whereami.md YAML frontmatter (fallback via __state_yq2json)
+  # Tier 2 — return 1 only when both files missing
+  local json_path="docs/whereami.json"
+  local md_path="docs/whereami.md"
+  if [ -f "$json_path" ]; then
+    cat "$json_path"
+    return 0
+  fi
+  if [ -f "$md_path" ]; then
+    __state_yq2json "$md_path"
+    return $?
+  fi
+  return 1
+}
+
+state_whereami_set() {
+  local field="$1"
+  local value="$2"
+  local path="docs/whereami.json"
+  if [ -z "$field" ] || [ -z "$value" ]; then
+    echo "state_whereami_set: requires <field> <value>" >&2
+    return 2
+  fi
+  if [ ! -f "$path" ]; then
+    echo "state_whereami_set: docs/whereami.json does not exist" >&2
+    return 4
+  fi
+  local updated
+  # Use jq's setpath for nested field paths (e.g., 'phase.value')
+  updated="$(jq --arg path "$field" --arg val "$value" '
+    setpath($path | split("."); $val)
+  ' "$path")" || return 3
+  __state_atomic_write "$path" "$updated"
+}
+
+# === IterationBet (Shape B — markdown + YAML frontmatter + body) ===
+
+state_iteration_bet_get() {
+  local slug="$1"
+  if [ -z "$slug" ]; then
+    echo "state_iteration_bet_get: requires <slug>" >&2
+    return 2
+  fi
+  local path="docs/iteration-bets/${slug}.md"
+  if [ ! -f "$path" ]; then
+    return 1
+  fi
+  __state_yq2json "$path"
+}
+
+# Special-purpose: returns the single active iteration bet (status=active),
+# or exit 1 if none. If multiple are active (parallel mode), returns the
+# first by filename order (stable, sorted lexicographically).
+state_iteration_bet_active() {
+  local found=""
+  if [ ! -d docs/iteration-bets ]; then
+    return 1
+  fi
+  for f in docs/iteration-bets/*.md; do
+    [ -f "$f" ] || continue
+    local status
+    status="$(__state_yq2json "$f" 2>/dev/null | jq -r '.status // empty')"
+    if [ "$status" = "active" ]; then
+      __state_yq2json "$f"
+      return 0
+    fi
+  done
+  return 1
+}
+
+# List all iteration bets. Returns JSON array of frontmatter objects to
+# stdout; empty array `[]` if directory absent or empty. Stable order
+# (lexicographic by filename — chronologically earliest first since slugs
+# carry dates).
+state_iteration_bet_list() {
+  if [ ! -d docs/iteration-bets ]; then
+    echo "[]"
+    return 0
+  fi
+  local result="["
+  local first=1
+  for f in docs/iteration-bets/*.md; do
+    [ -f "$f" ] || continue
+    local entry_json
+    entry_json="$(__state_yq2json "$f" 2>/dev/null)" || continue
+    [ -z "$entry_json" ] && continue
+    [ "$entry_json" = "{}" ] && continue
+    [ "$entry_json" = "null" ] && continue
+    if [ "$first" -eq 1 ]; then
+      first=0
+    else
+      result="${result},"
+    fi
+    result="${result}${entry_json}"
+  done
+  result="${result}]"
+  echo "$result" | jq -c .
+}
+
+# === Roadmap (Shape B — markdown + YAML frontmatter + body) ===
+#
+# Per bassclef#337: distributed agents coordinate on roadmap work via
+# state management. Two primitives: last_event (singular — "where were we")
+# + next_work_units (task list — "what's queued"). Workers claim atomically
+# via state_roadmap_claim_wu, release on completion via state_roadmap_release_wu.
+
+state_roadmap_get() {
+  local slug="$1"
+  if [ -z "$slug" ]; then
+    echo "state_roadmap_get: requires <slug>" >&2
+    return 2
+  fi
+  local path="docs/roadmaps/${slug}.md"
+  if [ ! -f "$path" ]; then
+    return 1
+  fi
+  __state_yq2json "$path"
+}
+
+# Internal: rewrite a roadmap's frontmatter from JSON, preserving the body.
+__state_roadmap_write_frontmatter() {
+  local slug="$1"
+  local frontmatter_json="$2"
+  local path="docs/roadmaps/${slug}.md"
+  if [ ! -f "$path" ]; then
+    echo "__state_roadmap_write_frontmatter: roadmap $path not found" >&2
+    return 1
+  fi
+  python3 -c "
+import sys, yaml, json
+path = '$path'
+fm = json.loads('''$frontmatter_json''')
+with open(path, 'r') as f:
+    content = f.read()
+# Split off the frontmatter block (between the two leading '---' lines)
+parts = content.split('---', 2)
+if len(parts) < 3:
+    print('roadmap missing frontmatter delimiter', file=sys.stderr)
+    sys.exit(2)
+body = parts[2]
+new_fm = yaml.safe_dump(fm, default_flow_style=False, sort_keys=False, allow_unicode=True)
+new_content = '---\n' + new_fm + '---' + body
+with open(path, 'w') as f:
+    f.write(new_content)
+" 2>&1
+}
+
+# Returns the next pending work unit whose depends_on are all completed
+# (status=completed in next_work_units), as JSON. Returns exit 1 if none.
+state_roadmap_next_pending() {
+  local slug="$1"
+  if [ -z "$slug" ]; then
+    echo "state_roadmap_next_pending: requires <slug>" >&2
+    return 2
+  fi
+  local roadmap_json
+  roadmap_json="$(state_roadmap_get "$slug")" || return $?
+  local result
+  result="$(echo "$roadmap_json" | jq -c '
+    .next_work_units as $wus |
+    [$wus[]? | select(.status == "completed") | .slug] as $done |
+    [$wus[]? | select(.status == "pending")] |
+    map(select(
+      ((.depends_on // []) | length == 0) or
+      ((.depends_on // []) | all(IN($done[])))
+    )) |
+    first // empty
+  ' 2>/dev/null)"
+  if [ -z "$result" ] || [ "$result" = "null" ]; then
+    return 1
+  fi
+  echo "$result"
+}
+
+# Atomically claim the next pending WU (or a specific WU by slug).
+# Args: <roadmap-slug> [wu-slug] [session-id]
+# - wu-slug omitted → claim next_pending result
+# - session-id defaults to ${CLAUDE_SESSION_ID:-unknown}
+# Output: the claimed WU as JSON, or exit 1 if none claimable.
+state_roadmap_claim_wu() {
+  local roadmap_slug="$1"
+  local wu_slug="${2:-}"
+  local session_id="${3:-${CLAUDE_SESSION_ID:-unknown}}"
+  if [ -z "$roadmap_slug" ]; then
+    echo "state_roadmap_claim_wu: requires <roadmap-slug> [wu-slug] [session-id]" >&2
+    return 2
+  fi
+  local lockfile=".state-roadmap-${roadmap_slug}.lock"
+  (
+    flock -x 9 2>/dev/null || true
+    local roadmap_json
+    roadmap_json="$(state_roadmap_get "$roadmap_slug")" || exit 1
+
+    # If wu_slug not given, compute next_pending
+    if [ -z "$wu_slug" ]; then
+      wu_slug="$(state_roadmap_next_pending "$roadmap_slug" | jq -r '.slug // empty')"
+      if [ -z "$wu_slug" ]; then
+        exit 1
+      fi
+    fi
+
+    # Check current status — only claim if pending
+    local current_status
+    current_status="$(echo "$roadmap_json" | jq -r --arg slug "$wu_slug" '.next_work_units[]? | select(.slug == $slug) | .status // empty')"
+    if [ "$current_status" != "pending" ]; then
+      # Already claimed or completed — return empty (atomicity boundary)
+      exit 1
+    fi
+
+    local now
+    now="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    # Advance last_event AND mutate WU status atomically (bassclef#349
+    # tail-1: claim is a real Event in workflow history, not just a
+    # status mutation — recording it in last_event means polling sessions
+    # can tell when work is in progress, not just completed).
+    local updated
+    updated="$(echo "$roadmap_json" | jq --arg slug "$wu_slug" --arg sid "$session_id" --arg ts "$now" '
+      .next_work_units = ((.next_work_units // []) | map(
+        if .slug == $slug and .status == "pending" then
+          . + {status: "in_progress", claimed_by: $sid, claimed_at: $ts}
+        else . end
+      )) |
+      .last_event = {ts: $ts, event: "task-claimed", refs: [$slug], actor: $sid}
+    ')" || exit 4
+
+    # Write back
+    __state_roadmap_write_frontmatter "$roadmap_slug" "$updated" || exit 4
+
+    # Echo the claimed WU
+    echo "$updated" | jq --arg slug "$wu_slug" '.next_work_units[] | select(.slug == $slug)' -c
+  ) 9>"$lockfile"
+}
+
+# Release a WU on completion. Updates the WU's status to completed AND
+# advances last_event to record the completion.
+# Args: <roadmap-slug> <wu-slug> [event-name] [refs-json-array]
+state_roadmap_release_wu() {
+  local roadmap_slug="$1"
+  local wu_slug="$2"
+  local event_name="${3:-}"
+  local refs_json="${4:-[]}"
+  if [ -z "$roadmap_slug" ] || [ -z "$wu_slug" ]; then
+    echo "state_roadmap_release_wu: requires <roadmap-slug> <wu-slug> [event-name] [refs-json]" >&2
+    return 2
+  fi
+  local lockfile=".state-roadmap-${roadmap_slug}.lock"
+  (
+    flock -x 9 2>/dev/null || true
+    local roadmap_json
+    roadmap_json="$(state_roadmap_get "$roadmap_slug")" || exit 1
+
+    if [ -z "$event_name" ]; then
+      event_name="${wu_slug}_completed"
+    fi
+
+    local now
+    now="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+    local updated
+    updated="$(echo "$roadmap_json" | \
+      jq --arg slug "$wu_slug" --arg ts "$now" --arg ev "$event_name" --argjson refs "$refs_json" '
+        .next_work_units = ((.next_work_units // []) | map(
+          if .slug == $slug then . + {status: "completed", completed_at: $ts}
+          else . end
+        )) |
+        .last_event = {ts: $ts, event: $ev, refs: $refs, actor: ((env.CLAUDE_SESSION_ID // "unknown")|tostring)}
+      ')" || exit 4
+
+    __state_roadmap_write_frontmatter "$roadmap_slug" "$updated" || exit 4
+
+    # Echo the new last_event
+    echo "$updated" | jq -c '.last_event'
+  ) 9>"$lockfile"
+}
+
+# Add a new task to a roadmap's next_work_units (bassclef#349 tail-3).
+# Validates slug uniqueness within roadmap and that any depends_on slugs
+# already exist in next_work_units. Advances last_event with task-added.
+# Args: <roadmap-slug> <wu-slug> <issue> <wu-id> <title> [depends_on-json]
+# - issue: GitHub-style ref like "bassclef#354"
+# - wu-id: WU identifier like "WU-A" or "tail-3"
+# - depends_on-json: JSON array of dependency slugs; defaults to []
+# Output: the new task as JSON, or exits 4 on validation failure.
+state_roadmap_add_task() {
+  local roadmap_slug="${1:-}"
+  local wu_slug="${2:-}"
+  local issue="${3:-}"
+  local wu_id="${4:-}"
+  local title="${5:-}"
+  local depends_on_json="${6:-[]}"
+  if [ -z "$roadmap_slug" ] || [ -z "$wu_slug" ] || [ -z "$issue" ] || [ -z "$wu_id" ] || [ -z "$title" ]; then
+    echo "state_roadmap_add_task: requires <roadmap-slug> <wu-slug> <issue> <wu-id> <title> [depends_on-json]" >&2
+    return 2
+  fi
+  # Validate depends_on is a JSON array
+  if ! echo "$depends_on_json" | jq -e 'type == "array"' >/dev/null 2>&1; then
+    echo "state_roadmap_add_task: depends_on must be a JSON array (got: $depends_on_json)" >&2
+    return 2
+  fi
+  local lockfile=".state-roadmap-${roadmap_slug}.lock"
+  (
+    flock -x 9 2>/dev/null || true
+    local roadmap_json
+    roadmap_json="$(state_roadmap_get "$roadmap_slug")" || exit 1
+
+    # Slug uniqueness check
+    local existing
+    existing="$(echo "$roadmap_json" | jq -r --arg slug "$wu_slug" '.next_work_units[]? | select(.slug == $slug) | .slug // empty')"
+    if [ -n "$existing" ]; then
+      echo "state_roadmap_add_task: WU '$wu_slug' already exists in roadmap '$roadmap_slug'" >&2
+      exit 4
+    fi
+
+    # depends_on slugs must already exist in roadmap
+    local depends_on_count
+    depends_on_count="$(echo "$depends_on_json" | jq 'length')"
+    if [ "$depends_on_count" -gt 0 ]; then
+      local missing
+      missing="$(echo "$roadmap_json" | jq -c --argjson dep "$depends_on_json" '
+        ([.next_work_units[]?.slug] // []) as $existing |
+        $dep | map(select(. as $d | ($existing | index($d)) == null))
+      ')"
+      if [ "$(echo "$missing" | jq 'length')" != "0" ]; then
+        echo "state_roadmap_add_task: depends_on contains slugs not in roadmap: $missing" >&2
+        exit 4
+      fi
+    fi
+
+    local now
+    now="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    local updated
+    updated="$(echo "$roadmap_json" | \
+      jq --arg slug "$wu_slug" --arg issue "$issue" --arg wu_id "$wu_id" \
+         --arg title "$title" --arg ts "$now" --argjson dep "$depends_on_json" '
+        .next_work_units = ((.next_work_units // []) + [{
+          slug: $slug,
+          issue: $issue,
+          wu: $wu_id,
+          title: $title,
+          status: "pending",
+          depends_on: $dep
+        }]) |
+        .last_event = {ts: $ts, event: "task-added", refs: [$slug], actor: ((env.CLAUDE_SESSION_ID // "unknown")|tostring)}
+      ')" || exit 4
+
+    __state_roadmap_write_frontmatter "$roadmap_slug" "$updated" || exit 4
+
+    # Echo the new task as JSON
+    echo "$updated" | jq -c --arg slug "$wu_slug" '.next_work_units[] | select(.slug == $slug)'
+  ) 9>"$lockfile"
+}
+
+# Abandon a claimed WU (bassclef#349 tail-2). Two modes:
+# - Default (return-to-queue): in_progress → pending; clears claimed_by/claimed_at
+# - Terminal (--terminal flag): in_progress → abandoned; clears claimed_by/claimed_at
+# In both modes, advances last_event with event="task-abandoned" and reason in note.
+# Args: <roadmap-slug> <wu-slug> [reason] [--terminal]
+state_roadmap_abandon_wu() {
+  local roadmap_slug="$1"
+  local wu_slug="$2"
+  local reason="${3:-}"
+  local mode="pending"  # default: return to queue
+  if [ "${4:-}" = "--terminal" ] || [ "${3:-}" = "--terminal" ]; then
+    mode="abandoned"
+    [ "${3:-}" = "--terminal" ] && reason=""  # if --terminal was 3rd arg, no reason
+  fi
+  if [ -z "$roadmap_slug" ] || [ -z "$wu_slug" ]; then
+    echo "state_roadmap_abandon_wu: requires <roadmap-slug> <wu-slug> [reason] [--terminal]" >&2
+    return 2
+  fi
+  local lockfile=".state-roadmap-${roadmap_slug}.lock"
+  (
+    flock -x 9 2>/dev/null || true
+    local roadmap_json
+    roadmap_json="$(state_roadmap_get "$roadmap_slug")" || exit 1
+
+    # Verify WU exists and is in_progress; only abandon active claims
+    local current_status
+    current_status="$(echo "$roadmap_json" | jq -r --arg slug "$wu_slug" '.next_work_units[]? | select(.slug == $slug) | .status // empty')"
+    if [ -z "$current_status" ]; then
+      echo "state_roadmap_abandon_wu: WU '$wu_slug' not found in roadmap '$roadmap_slug'" >&2
+      exit 1
+    fi
+    if [ "$current_status" != "in_progress" ]; then
+      echo "state_roadmap_abandon_wu: WU '$wu_slug' is '$current_status', not in_progress; cannot abandon" >&2
+      exit 1
+    fi
+
+    local now
+    now="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    local updated
+    updated="$(echo "$roadmap_json" | \
+      jq --arg slug "$wu_slug" --arg ts "$now" --arg mode "$mode" --arg reason "$reason" '
+        .next_work_units = ((.next_work_units // []) | map(
+          if .slug == $slug then
+            (. | del(.claimed_by) | del(.claimed_at)) +
+            (if $mode == "abandoned" then {status: "abandoned", abandoned_at: $ts, abandoned_reason: $reason}
+             else {status: "pending"} end)
+          else . end
+        )) |
+        .last_event = {ts: $ts, event: "task-abandoned", refs: [$slug], actor: ((env.CLAUDE_SESSION_ID // "unknown")|tostring), note: $reason}
+      ')" || exit 4
+
+    __state_roadmap_write_frontmatter "$roadmap_slug" "$updated" || exit 4
+
+    # Echo the new last_event
+    echo "$updated" | jq -c '.last_event'
+  ) 9>"$lockfile"
+}
+
+# === Marker (Shape C — pure JSON) ===
+
+state_marker_get() {
+  local uuid="$1"
+  if [ -z "$uuid" ]; then
+    echo "state_marker_get: requires <uuid>" >&2
+    return 2
+  fi
+  if [ ! -d state/markers ]; then
+    return 1
+  fi
+  local file
+  file="$(find state/markers -name "${uuid}.json" -type f -print -quit 2>/dev/null)"
+  if [ -z "$file" ]; then
+    return 1
+  fi
+  cat "$file"
+}
+
+# Counter: derived from history on every call (replay-determinism).
+# Args: [category] [since-days]
+# Returns integer to stdout (0 if none).
+#
+# Per state-spine-contract.md: "since-N-sessions" semantics deferred to
+# spine v1 (requires session-boundary mapping from chronicle history).
+# v0 implements `since-days` (mtime-based) — sufficient for the
+# bassclef#296 floor-lift fix (window-bounded marker count). Override
+# the implementation in spine v1 to use session boundaries; consumers
+# don't change.
+#
+# Also accepts both .json (spine v0) and .marker (legacy) extensions —
+# legacy markers from .claude/verify-markers/ and pre-spine
+# state/markers/ retain .marker extension; this accessor unions
+# both per pre-spine + post-spine reads.
+state_marker_count() {
+  local category="${1:-}"
+  local since_days="${2:-}"
+  if [ ! -d state/markers ]; then
+    echo "0"
+    return 0
+  fi
+  local search_dir="state/markers"
+  if [ -n "$category" ]; then
+    if [ ! -d "state/markers/$category" ]; then
+      echo "0"
+      return 0
+    fi
+    search_dir="state/markers/$category"
+  fi
+  if [ -n "$since_days" ]; then
+    if ! [[ "$since_days" =~ ^[0-9]+$ ]]; then
+      echo "state_marker_count: since-days must be integer (got: $since_days)" >&2
+      return 2
+    fi
+    find "$search_dir" -type f \( -name "*.json" -o -name "*.marker" \) -mtime "-${since_days}" 2>/dev/null | wc -l | tr -d ' '
+  else
+    find "$search_dir" -type f \( -name "*.json" -o -name "*.marker" \) 2>/dev/null | wc -l | tr -d ' '
+  fi
+}
+
+# Append a new marker. Reads marker JSON on stdin; extracts id + category;
+# writes to state/markers/<category>/<id>.json. Returns id to stdout.
+state_marker_add() {
+  local marker_json
+  marker_json="$(cat)"
+  if [ -z "$marker_json" ]; then
+    echo "state_marker_add: requires marker JSON on stdin" >&2
+    return 2
+  fi
+  local id category
+  id="$(echo "$marker_json" | jq -r '.id // empty')"
+  category="$(echo "$marker_json" | jq -r '.category // empty')"
+  if [ -z "$id" ] || [ -z "$category" ]; then
+    echo "state_marker_add: marker missing id or category" >&2
+    return 2
+  fi
+  local dir="state/markers/$category"
+  mkdir -p "$dir" || return 4
+  __state_atomic_write "${dir}/${id}.json" "$marker_json" || return 4
+  echo "$id"
+}
+
+# === Chronicle (Shape B/hybrid — markdown + YAML frontmatter; gates_fired
+# in frontmatter for v0; sidecar JSON ships in WU-4) ===
+
+# Special-purpose: extract gates_fired array from a chronicle.
+# Returns JSON array of gate objects to stdout (empty array `[]` if no gates).
+# Per bassclef#298 fix — schema-required field; this accessor reads it deterministically.
+state_chronicle_gate_evidence() {
+  local id="$1"
+  if [ -z "$id" ]; then
+    echo "state_chronicle_gate_evidence: requires <id>" >&2
+    return 2
+  fi
+  # Try bassclef (chronicle/) and consumer-repo (docs/chronicle/) paths
+  local path=""
+  if [ -f "chronicle/${id}.md" ]; then
+    path="chronicle/${id}.md"
+  elif [ -f "docs/chronicle/${id}.md" ]; then
+    path="docs/chronicle/${id}.md"
+  else
+    return 1
+  fi
+  __state_yq2json "$path" | jq -c '.gates_fired // []'
+}
+
+# List chronicle IDs (filename without .md extension), optionally limited
+# to the most-recent N entries. Returns one ID per line on stdout (NOT
+# JSON array — chronicles are typically iterated, and bash-friendly
+# output keeps the consumer simple).
+#
+# Args: [--recent N]
+#
+# Tries bassclef (chronicle/) first, then consumer-repo
+# (docs/chronicle/) per the same path convention as
+# state_chronicle_gate_evidence. Sorts lexicographically (chronicles
+# carry YYYY-MM-DD prefix, so this is chronological).
+state_chronicle_list() {
+  local limit=""
+  if [ "${1:-}" = "--recent" ]; then
+    limit="${2:-}"
+    if ! [[ "$limit" =~ ^[0-9]+$ ]]; then
+      echo "state_chronicle_list: --recent requires integer (got: $limit)" >&2
+      return 2
+    fi
+  elif [ -n "${1:-}" ]; then
+    echo "state_chronicle_list: unknown arg '$1' (expected --recent N)" >&2
+    return 2
+  fi
+  local dir=""
+  if [ -d chronicle ]; then
+    dir="chronicle"
+  elif [ -d docs/chronicle ]; then
+    dir="docs/chronicle"
+  else
+    return 0
+  fi
+  local files
+  files="$(find "$dir" -maxdepth 1 -name "*.md" -type f 2>/dev/null | sort)"
+  [ -z "$files" ] && return 0
+  if [ -n "$limit" ]; then
+    files="$(echo "$files" | tail -n "$limit")"
+  fi
+  while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    local base
+    base="$(basename "$f" .md)"
+    echo "$base"
+  done <<< "$files"
+}
+
+# === DeferredAction (Shape B — markdown + YAML frontmatter) ===
+
+# Special-purpose: list pending deferred actions, optionally filtered by
+# capability. Pending = files in docs/deferred-actions/ (NOT in completed/).
+# Filter args: zero or more capability tokens; entry matches if its
+# requires_capability set is a SUBSET of the supplied capabilities.
+state_deferred_action_pending() {
+  local -a caps=("$@")
+  local -a entries=()
+  if [ ! -d docs/deferred-actions ]; then
+    echo "[]"
+    return 0
+  fi
+  for f in docs/deferred-actions/*.md; do
+    [ -f "$f" ] || continue
+    [ "$(basename "$f")" = "README.md" ] && continue
+    [ "$(basename "$f")" = "template.md" ] && continue
+    entries+=("$f")
+  done
+  if [ "${#entries[@]}" -eq 0 ]; then
+    echo "[]"
+    return 0
+  fi
+  # Build JSON array
+  local result="["
+  local first=1
+  for f in "${entries[@]}"; do
+    local entry_json
+    entry_json="$(__state_yq2json "$f" 2>/dev/null)" || continue
+    # Apply capability filter if any caps supplied
+    if [ "${#caps[@]}" -gt 0 ]; then
+      local match=1
+      local entry_caps
+      entry_caps="$(echo "$entry_json" | jq -r '.requires_capability // [] | .[]')"
+      for needed in $entry_caps; do
+        local found=0
+        for supplied in "${caps[@]}"; do
+          if [ "$needed" = "$supplied" ]; then
+            found=1
+            break
+          fi
+        done
+        if [ "$found" -eq 0 ]; then
+          match=0
+          break
+        fi
+      done
+      if [ "$match" -eq 0 ]; then
+        continue
+      fi
+    fi
+    if [ "$first" -eq 1 ]; then
+      first=0
+    else
+      result="${result},"
+    fi
+    result="${result}${entry_json}"
+  done
+  result="${result}]"
+  echo "$result" | jq -c .
+}
+
+# List deferred actions. Optional first arg selects scope:
+#   pending   (default) → docs/deferred-actions/*.md (NOT completed/)
+#   completed             → docs/deferred-actions/completed/*.md
+#   all                   → both
+# Returns JSON array of frontmatter objects to stdout; empty `[]` if none.
+state_deferred_action_list() {
+  local scope="${1:-pending}"
+  case "$scope" in
+    pending|completed|all) ;;
+    *)
+      echo "state_deferred_action_list: scope must be pending|completed|all (got: $scope)" >&2
+      return 2
+      ;;
+  esac
+  local -a paths=()
+  if [ "$scope" = "pending" ] || [ "$scope" = "all" ]; then
+    if [ -d docs/deferred-actions ]; then
+      for f in docs/deferred-actions/*.md; do
+        [ -f "$f" ] || continue
+        local base="$(basename "$f")"
+        [ "$base" = "README.md" ] && continue
+        [ "$base" = "template.md" ] && continue
+        paths+=("$f")
+      done
+    fi
+  fi
+  if [ "$scope" = "completed" ] || [ "$scope" = "all" ]; then
+    if [ -d docs/deferred-actions/completed ]; then
+      for f in docs/deferred-actions/completed/*.md; do
+        [ -f "$f" ] || continue
+        local base="$(basename "$f")"
+        [ "$base" = "README.md" ] && continue
+        paths+=("$f")
+      done
+    fi
+  fi
+  if [ "${#paths[@]}" -eq 0 ]; then
+    echo "[]"
+    return 0
+  fi
+  local result="["
+  local first=1
+  for f in "${paths[@]}"; do
+    local entry_json
+    entry_json="$(__state_yq2json "$f" 2>/dev/null)" || continue
+    [ -z "$entry_json" ] && continue
+    if [ "$first" -eq 1 ]; then
+      first=0
+    else
+      result="${result},"
+    fi
+    result="${result}${entry_json}"
+  done
+  result="${result}]"
+  echo "$result" | jq -c .
+}
+
+# === Validation accessor (special-purpose; wraps state-validate.sh) ===
+
+# Validates an arbitrary file at <path> against its entity schema by
+# invoking the state-validate.sh PreToolUse hook with a synthesized
+# event. Useful for ad-hoc /state validate <path> from operators or
+# scripts.
+#
+# Returns:
+#   0 — file is a state-spine entity AND validates clean (or hook chose
+#       legacy pass-through)
+#   2 — invalid input (no path, missing arg)
+#   3 — schema validation failed (BLOCK message on stderr)
+#   4 — filesystem error (file or hook missing)
+#
+# stdout: empty on success; ajv-cli BLOCK output on failure
+# stderr: structured BLOCK message (forwarded from state-validate.sh)
+state_validate() {
+  local target="${1:-}"
+  if [ -z "$target" ]; then
+    echo "state_validate: requires <path>" >&2
+    return 2
+  fi
+  if [ ! -f "$target" ]; then
+    echo "state_validate: file not found: $target" >&2
+    return 4
+  fi
+  local hook=".claude/hooks/state-validate.sh"
+  if [ ! -x "$hook" ]; then
+    echo "state_validate: hook not executable at $hook" >&2
+    return 4
+  fi
+  # Synthesize PreToolUse event JSON; the hook only reads tool_name + file_path.
+  printf '{"tool_name":"Edit","tool_input":{"file_path":"%s"}}\n' "$target" | "$hook"
+  local hook_exit=$?
+  case "$hook_exit" in
+    0) return 0 ;;
+    2|4|5) return "$hook_exit" ;;
+    *) return 3 ;;  # any non-zero non-input-error = validation block
+  esac
+}
+
+# === Reference resolver (typed cross-entity refs) ===
+
+# Resolves a typed reference to its entity. Returns JSON of the entity to
+# stdout; exit 1 if dangling; exit 5 if entity type unknown.
+# Args: <type> <id>
+state_reference_get() {
+  local type="$1"
+  local id="$2"
+  if [ -z "$type" ] || [ -z "$id" ]; then
+    echo "state_reference_get: requires <type> <id>" >&2
+    return 2
+  fi
+  case "$type" in
+    chronicle)
+      if [ -f "chronicle/${id}.md" ]; then
+        __state_yq2json "chronicle/${id}.md"
+      elif [ -f "docs/chronicle/${id}.md" ]; then
+        __state_yq2json "docs/chronicle/${id}.md"
+      else
+        return 1
+      fi
+      ;;
+    discovery)
+      if [ -f "design/discoveries/${id}.md" ]; then
+        __state_yq2json "design/discoveries/${id}.md"
+      else
+        return 1
+      fi
+      ;;
+    adr)
+      # ADRs are markdown without YAML frontmatter; return path as JSON
+      if [ -f "architecture/decisions/${id}.md" ]; then
+        printf '{"path":"architecture/decisions/%s.md","type":"adr","id":"%s"}\n' "$id" "$id"
+      else
+        return 1
+      fi
+      ;;
+    decomposition)
+      if [ -f "docs/decompositions/${id}.md" ]; then
+        __state_yq2json "docs/decompositions/${id}.md"
+      else
+        return 1
+      fi
+      ;;
+    spec)
+      if [ -f "docs/specs/${id}.md" ]; then
+        __state_yq2json "docs/specs/${id}.md"
+      else
+        return 1
+      fi
+      ;;
+    session)
+      if [ -f "docs/sessions/${id}.md" ]; then
+        __state_yq2json "docs/sessions/${id}.md"
+      elif [ -f "docs/sessions/${id}.json" ]; then
+        cat "docs/sessions/${id}.json"
+      else
+        return 1
+      fi
+      ;;
+    iteration-bet)
+      state_iteration_bet_get "$id"
+      ;;
+    roadmap)
+      if [ -f "docs/roadmaps/${id}.md" ]; then
+        __state_yq2json "docs/roadmaps/${id}.md"
+      else
+        return 1
+      fi
+      ;;
+    workunit)
+      # Workunits live inline in stack manifests; not directly addressable in v0
+      echo "state_reference_get: workunit type requires Stack lookup; not implemented in v0" >&2
+      return 5
+      ;;
+    stack)
+      if [ -f "docs/stacks/${id}.md" ]; then
+        __state_yq2json "docs/stacks/${id}.md"
+      else
+        return 1
+      fi
+      ;;
+    marker)
+      state_marker_get "$id"
+      ;;
+    gate)
+      # Gates derive from Markers; not addressable directly in v0
+      echo "state_reference_get: gate type derives from Marker; not directly addressable in v0" >&2
+      return 5
+      ;;
+    *)
+      echo "state_reference_get: unknown entity type '$type'" >&2
+      return 5
+      ;;
+  esac
+}
+
+# Returns 0 if reference exists, 1 if dangling, 5 if type unknown.
+# No JSON output (silent on success and not-found; stderr on type error).
+state_reference_check() {
+  local type="$1"
+  local id="$2"
+  state_reference_get "$type" "$id" >/dev/null 2>&1
+  local exit_code=$?
+  # Translate: success → 0; not-found → 1; unknown-type → 5; other → 1
+  case "$exit_code" in
+    0) return 0 ;;
+    5) return 5 ;;
+    *) return 1 ;;
+  esac
+}
+
+# === BassclefPlatform (Shape D — pure YAML at sibling-repo root) ===
+#
+# Org-baseline platform-engineering primitive. Lives at the root of a
+# sibling repo (e.g., sunj-labs/platform-config) so it can be forked
+# and edited per adopter without forking bassclef itself.
+#
+# Resolution order for the file path:
+#   1. BASSCLEF_PLATFORM_CONFIG_PATH env var (explicit override)
+#   2. ~/src/<github_org>/platform-config/bassclef-platform.yml
+#      (default sunj-labs convention; <github_org> from substrate.config.md)
+#   3. Sibling-repo path declared in .bassclef-source.json
+#      (`platform_config_source` field — V2 thin-pointer extension)
+#
+# v0 implementation honors options 1 + 2. Option 3 lands when
+# .bassclef-source.json schema gains the field (bassclef#418-style
+# follow-up).
+
+__state_platform_resolve_path() {
+  if [ -n "${BASSCLEF_PLATFORM_CONFIG_PATH:-}" ]; then
+    echo "$BASSCLEF_PLATFORM_CONFIG_PATH"
+    return 0
+  fi
+  echo "${HOME}/src/sunj-labs/platform-config/bassclef-platform.yml"
+}
+
+state_platform_get() {
+  local key="${1:-}"
+  local path
+  path="$(__state_platform_resolve_path)"
+  if [ ! -f "$path" ]; then
+    return 1
+  fi
+  local json
+  json="$(python3 -c "
+import sys, yaml, json
+try:
+    with open('$path') as f:
+        data = yaml.safe_load(f) or {}
+    print(json.dumps(data, default=str))
+except Exception as e:
+    print(f'yaml parse failed: {e}', file=sys.stderr)
+    sys.exit(3)
+")" || return 3
+
+  if [ -z "$key" ]; then
+    echo "$json"
+    return 0
+  fi
+  # Dot-path key (e.g., "org.github_org", "deploy_tiers.prototype.hosting_platform")
+  echo "$json" | jq -r --arg key "$key" '
+    getpath($key | split(".")) // empty
+  '
+}
+
+# Returns the resolved file path (for tooling that needs to display
+# where state_platform_get is reading from, without reading the file).
+state_platform_path() {
+  __state_platform_resolve_path
+}
+
+# === Pattern Implementation accessors (bassclef#478 Layer 3) ===
+#
+# Maps source files to the @pattern catalog entries they consciously
+# instantiate. Manifest at state/pattern-implementations/<sanitized-path>.json.
+# Auto-populated by .claude/hooks/pattern-annotation-validate.sh on Edit/Write.
+# Consumed by /pattern-trace skill for forward (which file uses pattern X)
+# and reverse (which patterns does file Y use) lookups.
+
+__state_pattern_implementation_path() {
+  # Sanitize a file path to a manifest filename: replace / with _.
+  local file="$1"
+  local sanitized
+  sanitized=$(echo "$file" | tr '/' '_')
+  echo "state/pattern-implementations/${sanitized}.json"
+}
+
+# state_pattern_implementation_get <file_path>
+# Read the manifest entry for a source file. Returns JSON or empty (not found).
+state_pattern_implementation_get() {
+  local file="$1"
+  if [ -z "$file" ]; then
+    echo "state_pattern_implementation_get: requires <file>" >&2
+    return 2
+  fi
+  local manifest_path
+  manifest_path="$(__state_pattern_implementation_path "$file")"
+  if [ ! -f "$manifest_path" ]; then
+    return 1
+  fi
+  cat "$manifest_path"
+}
+
+# state_pattern_implementation_index_pattern <pattern_path>
+# Reverse lookup: list all source files that have a @pattern annotation
+# pointing to <pattern_path>. Returns one file path per line.
+state_pattern_implementation_index_pattern() {
+  local pattern_path="$1"
+  if [ -z "$pattern_path" ]; then
+    echo "state_pattern_implementation_index_pattern: requires <pattern_path>" >&2
+    return 2
+  fi
+  if [ ! -d "state/pattern-implementations" ]; then
+    return 1
+  fi
+  for manifest in state/pattern-implementations/*.json; do
+    [ -f "$manifest" ] || continue
+    if jq -e --arg p "$pattern_path" '.annotations[] | select(.pattern_path == $p)' "$manifest" >/dev/null 2>&1; then
+      jq -r '.file' "$manifest"
+    fi
+  done
+}
+
+# state_pattern_implementation_list
+# List all manifest entries (one file path per line).
+state_pattern_implementation_list() {
+  if [ ! -d "state/pattern-implementations" ]; then
+    return 1
+  fi
+  for manifest in state/pattern-implementations/*.json; do
+    [ -f "$manifest" ] || continue
+    jq -r '.file' "$manifest"
+  done
+}
+
+# state_pattern_implementation_set <file_path> <pattern_path> <line> [context]
+# Write/upsert a single @pattern annotation entry. Used by the validate hook
+# during Write/Edit operations on source files that contain @pattern annotations.
+# This is the only WRITE accessor for this entity; reads use the get/index/list
+# methods above.
+state_pattern_implementation_set() {
+  local file="$1"
+  local pattern_path="$2"
+  local line="$3"
+  local context="${4:-}"
+  if [ -z "$file" ] || [ -z "$pattern_path" ] || [ -z "$line" ]; then
+    echo "state_pattern_implementation_set: requires <file> <pattern_path> <line> [context]" >&2
+    return 2
+  fi
+  local manifest_path
+  manifest_path="$(__state_pattern_implementation_path "$file")"
+  mkdir -p "$(dirname "$manifest_path")"
+  local timestamp
+  timestamp="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  if [ -f "$manifest_path" ]; then
+    # Upsert: replace any existing annotation with same pattern_path+line.
+    jq --arg p "$pattern_path" --argjson l "$line" --arg c "$context" --arg ts "$timestamp" '
+      .last_scanned = $ts |
+      .annotations |= (map(select(.pattern_path != $p or .line != $l)) + [{pattern_path: $p, line: $l} + (if $c != "" then {context: $c} else {} end)])
+    ' "$manifest_path" > "${manifest_path}.tmp" && mv "${manifest_path}.tmp" "$manifest_path"
+  else
+    # Create fresh.
+    local entry
+    if [ -n "$context" ]; then
+      entry=$(jq -n --arg p "$pattern_path" --argjson l "$line" --arg c "$context" '{pattern_path: $p, line: $l, context: $c}')
+    else
+      entry=$(jq -n --arg p "$pattern_path" --argjson l "$line" '{pattern_path: $p, line: $l}')
+    fi
+    jq -n --arg f "$file" --argjson a "[$entry]" --arg ts "$timestamp" '{file: $f, annotations: $a, last_scanned: $ts, scanner_version: "1.0"}' > "$manifest_path"
+  fi
+}
+
+# === SubstrateHardening (Shape C — pure JSON; per bassclef bet 2026-06-17a Phase Z) ===
+
+# state_substrate_hardening_get
+# Read the substrate-hardening inventory. Returns the full inventory JSON
+# on stdout. Returns empty object `{}` if file does not exist.
+state_substrate_hardening_get() {
+  local inventory="state/substrate-hardening/inventory.json"
+  if [ ! -f "$inventory" ]; then
+    echo "{}"
+    return 0
+  fi
+  cat "$inventory"
+}
+
+# state_substrate_hardening_update_hook <path> <field-json>
+# Upsert a single hook entry in the inventory. <field-json> is a JSON object
+# of fields to set (e.g., '{"tier": 0, "has_test": true, "hardened_at": "..."}').
+# Fields not in the JSON keep their existing values; new fields are added.
+# If the inventory does not exist, creates it with schema_version=v0 + this entry.
+state_substrate_hardening_update_hook() {
+  local hook_path="$1"
+  local field_json="$2"
+  if [ -z "$hook_path" ] || [ -z "$field_json" ]; then
+    echo "state_substrate_hardening_update_hook: requires <path> <field-json>" >&2
+    return 2
+  fi
+  local inventory="state/substrate-hardening/inventory.json"
+  mkdir -p "$(dirname "$inventory")"
+  local timestamp
+  timestamp="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  if [ ! -f "$inventory" ]; then
+    jq -n \
+      --arg ts "$timestamp" \
+      --arg path "$hook_path" \
+      --argjson fields "$field_json" \
+      '{schema_version: "v0", generated_at: $ts, hooks: [({path: $path} + $fields)]}' \
+      > "$inventory"
+    return 0
+  fi
+  jq \
+    --arg ts "$timestamp" \
+    --arg path "$hook_path" \
+    --argjson fields "$field_json" \
+    '
+      .generated_at = $ts |
+      .hooks = (
+        if (.hooks | map(select(.path == $path)) | length) > 0 then
+          .hooks | map(if .path == $path then (. + $fields) else . end)
+        else
+          .hooks + [({path: $path} + $fields)]
+        end
+      )
+    ' "$inventory" > "${inventory}.tmp" && mv "${inventory}.tmp" "$inventory"
+}
+
+# === Release status accessor (per bet 2026-06-29c WU-2) ===
+#
+# state_whereami_release_status — returns JSON of release pipeline state.
+# Live (not cached). Composes data from:
+#   - public bassclef HEAD sha (via bassclef-version.json on public bassclef)
+#   - commits-ahead-of-public (local git rev-list)
+#   - open release PR if any (number, age in hours, CI status)
+#
+# Shape:
+#   {
+#     "public_bassclef_head_sha": "<sha>" or null,
+#     "commits_ahead_of_public": <int>,
+#     "open_release_pr": null OR {
+#       "number": <int>,
+#       "age_hours": <int>,
+#       "ci_status": "pass" | "fail" | "pending" | "unknown",
+#       "title": "<str>",
+#       "url": "<str>"
+#     }
+#   }
+#
+# Test-only overrides:
+#   COMMITS_AHEAD_OVERRIDE  — skip git computation; use this value
+#   PUBLIC_SHA_OVERRIDE      — skip gh api call for sha; use this value
+#
+# Returns empty when gh missing or fails (graceful).
+state_whereami_release_status() {
+  if ! command -v gh >/dev/null 2>&1 || ! command -v jq >/dev/null 2>&1; then
+    return 0
+  fi
+
+  # Resolve public_bassclef_head_sha
+  local sha
+  if [ -n "${PUBLIC_SHA_OVERRIDE:-}" ]; then
+    sha="$PUBLIC_SHA_OVERRIDE"
+  else
+    sha=$(gh api repos/sunj-labs/bassclef/contents/bassclef-version.json --jq '.content' 2>/dev/null | base64 -d 2>/dev/null | jq -r '.release_sha // empty' 2>/dev/null)
+    [ -z "$sha" ] && sha=""
+  fi
+
+  # Resolve commits_ahead_of_public
+  local commits_ahead
+  if [ -n "${COMMITS_AHEAD_OVERRIDE:-}" ]; then
+    commits_ahead="$COMMITS_AHEAD_OVERRIDE"
+  elif [ -n "$sha" ]; then
+    commits_ahead=$(git rev-list --count "${sha}..HEAD" 2>/dev/null || echo "0")
+  else
+    commits_ahead=0
+  fi
+
+  # Resolve open_release_pr
+  local pr_json="null"
+  local pr_list
+  pr_list=$(gh pr list -R sunj-labs/bassclef --state open --json number,title,createdAt,headRefName,statusCheckRollup,url 2>/dev/null || echo "[]")
+  local release_pr_entry
+  release_pr_entry=$(echo "$pr_list" | jq -c '
+    [.[] | select(.headRefName | startswith("release-"))][0] // null
+  ' 2>/dev/null)
+  if [ -n "$release_pr_entry" ] && [ "$release_pr_entry" != "null" ]; then
+    local pr_date pr_epoch now_epoch age_hours pr_num pr_title pr_url ci_status
+    pr_date=$(echo "$release_pr_entry" | jq -r '.createdAt')
+    pr_num=$(echo "$release_pr_entry" | jq -r '.number')
+    pr_title=$(echo "$release_pr_entry" | jq -r '.title')
+    pr_url=$(echo "$release_pr_entry" | jq -r '.url')
+    pr_epoch=$(date -u -j -f "%Y-%m-%dT%H:%M:%SZ" "$pr_date" +%s 2>/dev/null || date -u -d "$pr_date" +%s 2>/dev/null || echo "0")
+    now_epoch=$(date -u +%s)
+    age_hours=$(( (now_epoch - pr_epoch) / 3600 ))
+
+    # CI status: derive from statusCheckRollup
+    local rollup_states
+    rollup_states=$(echo "$release_pr_entry" | jq -r '.statusCheckRollup[]?.conclusion // empty' 2>/dev/null | sort -u)
+    if echo "$rollup_states" | grep -qiE "FAILURE|CANCELLED"; then
+      ci_status="fail"
+    elif echo "$rollup_states" | grep -qi "SUCCESS"; then
+      ci_status="pass"
+    elif [ -z "$rollup_states" ]; then
+      ci_status="pending"
+    else
+      ci_status="unknown"
+    fi
+
+    pr_json=$(jq -n \
+      --argjson num "$pr_num" \
+      --argjson age "$age_hours" \
+      --arg ci "$ci_status" \
+      --arg title "$pr_title" \
+      --arg url "$pr_url" \
+      '{number: $num, age_hours: $age, ci_status: $ci, title: $title, url: $url}')
+  fi
+
+  # Compose final JSON
+  local sha_json="null"
+  [ -n "$sha" ] && sha_json=$(jq -n --arg s "$sha" '$s')
+
+  jq -n \
+    --argjson sha "$sha_json" \
+    --argjson commits "$commits_ahead" \
+    --argjson pr "$pr_json" \
+    '{public_bassclef_head_sha: $sha, commits_ahead_of_public: $commits, open_release_pr: $pr}'
+}