@thebassclef/lite 0.1.3 → 1.0.1

package/substrate/lib/state.sh

@@ -1,1372 +0,0 @@
-#!/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}'
-}