@thebassclef/lite 1.9.16 → 1.9.18

package/dist/lite/lib/install-written-paths.sh

@@ -112,6 +112,100 @@ _iwp_manifest_valid() {
   return 0
 }
 
+# ---- Ajv-runtime schema validator (bassclef-upstream#2157 step 6) ----
+#
+# Wraps the install-written-paths manifest in ajv-based schema validation.
+# Called from install_written_paths_verify (read-side gate) + from
+# install_written_paths_register (post-write gate).
+#
+# Reads via is_install_written_path stay cheap (no ajv — hot path).
+# Writes are rare, so post-write ajv cost is acceptable.
+#
+# Fail-soft on ajv missing (adopter machine without ajv-cli): returns 0.
+# Mirrors the step 2 validator pattern at scripts/validate-cross-repo-contracts.sh:139-144.
+# This keeps lite-tier adopters working when ajv is not installed; the step 3
+# CI gate catches drift at every PR regardless of adopter ajv presence.
+#
+# @pattern patterns/code/ousterhout/deep-module.md  — one wrapper, many callers
+# @pattern patterns/code/vernon/anticorruption-layer.md — ajv at the write boundary
+
+_iwp_schema_path() {
+  local root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+  echo "$root/standards/state-spine/schemas/install-written-paths.schema.json"
+}
+
+# _iwp_ajv_validate <manifest-path>
+# Returns 0 when ajv absent (fail-soft) OR when ajv confirms the manifest
+# conforms to standards/state-spine/schemas/install-written-paths.schema.json.
+# Returns 1 when ajv is present AND the manifest fails schema validation.
+_iwp_ajv_validate() {
+  local manifest_file="${1:-}"
+  [ -n "$manifest_file" ] || return 1
+  [ -f "$manifest_file" ] || return 1
+
+  if ! command -v ajv >/dev/null 2>&1; then
+    _iwp_log "ajv-validate skip reason=ajv-missing manifest=$manifest_file"
+    return 0
+  fi
+
+  local schema
+  schema=$(_iwp_schema_path)
+  if [ ! -f "$schema" ]; then
+    _iwp_log "ajv-validate skip reason=schema-missing path=$schema"
+    return 0
+  fi
+
+  if ajv validate -s "$schema" -d "$manifest_file" --spec=draft2020 -c ajv-formats >/dev/null 2>&1; then
+    _iwp_log "ajv-validate pass manifest=$manifest_file"
+    return 0
+  fi
+
+  _iwp_log "ajv-validate fail manifest=$manifest_file"
+  return 1
+}
+
+# ---- CLI init.manifest.json fallback (bassclef-upstream#2138) ----
+#
+# bassclef-cli's `bassclef init` writes `.bassclef/init.manifest.json`
+# with its own schema (per bassclef-cli/src/lib/manifest-types.ts):
+#   { schema_version: 2|3, entries: [{path, template, outcome, ...}] }
+#
+# When upstream's state/install-written-paths.json doesn't have an
+# entry for a path, fall back to this CLI manifest. Treat outcome in
+# {created, updated, unchanged} as install-written. Treat refused |
+# error as NOT install-written (the write didn't actually land, so
+# discipline should still fire).
+#
+# No hash verification against the CLI manifest. The CLI schema uses
+# `content_hash_sha256` without the `sha256:` prefix; shape-mismatch
+# is tolerated because the fallback is a presence + outcome check,
+# not an integrity check. The upstream manifest keeps strict hash
+# verification per Hoare.
+_iwp_init_manifest_path() {
+  local root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+  echo "$root/.bassclef/init.manifest.json"
+}
+
+# Returns 0 when the path is present in the CLI init manifest with
+# outcome in {created, updated, unchanged}. Returns 1 otherwise
+# (missing file, malformed JSON, path absent, or outcome refused/error).
+_iwp_init_manifest_has_path() {
+  local tgt="${1:-}"
+  [ -n "$tgt" ] || return 1
+  local init_manifest
+  init_manifest=$(_iwp_init_manifest_path)
+  [ -f "$init_manifest" ] || return 1
+  command -v jq >/dev/null 2>&1 || return 1
+  # Guard against malformed JSON: jq -e . exits non-zero on parse failure.
+  jq -e . "$init_manifest" >/dev/null 2>&1 || return 1
+  local outcome
+  outcome=$(jq -r --arg path "$tgt" '.entries[]? | select(.path == $path) | .outcome' "$init_manifest" 2>/dev/null)
+  case "$outcome" in
+    created|updated|unchanged) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
 # ---- Public API ----
 
 # install_written_paths_register <path> <writer>
@@ -182,7 +276,19 @@ install_written_paths_register() {
   fi
 
   rm -f "$tmp" 2>/dev/null || true
-  _iwp_log "register path=$tgt writer=$writer"
+
+  # Post-write ajv check (step 6 — bassclef-upstream#2157). On fail, surface
+  # a warning but keep the write — fail-soft so adopters never lose data
+  # over schema drift. The step 2 validator + step 3 CI gate + step 5 release
+  # gate catch drift at later layers; this layer is advisory at write-time.
+  if ! _iwp_ajv_validate "$mpath"; then
+    echo "install-written-paths: WARNING — manifest at $mpath fails ajv schema validation after register" >&2
+    echo "install-written-paths: entry kept; run 'install_written_paths_verify' for details" >&2
+    _iwp_log "register path=$tgt writer=$writer post-write-ajv=fail"
+  else
+    _iwp_log "register path=$tgt writer=$writer post-write-ajv=pass"
+  fi
+
   return 0
 }
 
@@ -204,10 +310,17 @@ is_install_written_path() {
   local mpath
   mpath=$(_iwp_manifest_path)
 
-  # Fail-soft: manifest missing or malformed → not install-written
+  # Fail-soft: upstream manifest missing or malformed. Before giving
+  # up, consult the CLI init manifest (bassclef-upstream#2138). Cold
+  # adopters that ran only `bassclef init` have no upstream manifest
+  # yet; the CLI manifest is their only install-written source.
   if ! _iwp_manifest_valid; then
-    _iwp_log "check path=$tgt result=false reason=no-manifest-or-malformed"
     [ -f "$mpath" ] && echo "install-written-paths: manifest malformed; treating as not-install-written" >&2
+    if _iwp_init_manifest_has_path "$tgt"; then
+      _iwp_log "check path=$tgt result=true reason=cli-init-manifest-fallback-no-upstream-manifest"
+      return 0
+    fi
+    _iwp_log "check path=$tgt result=false reason=no-manifest-or-malformed"
     return 1
   fi
 
@@ -220,6 +333,14 @@ is_install_written_path() {
   local recorded_hash
   recorded_hash=$(jq -r --arg path "$tgt" '.entries[] | select(.path == $path) | .content_hash' "$mpath" 2>/dev/null)
   if [ -z "$recorded_hash" ] || [ "$recorded_hash" = "null" ]; then
+    # Fallback per bassclef-upstream#2138 — the CLI's `bassclef init`
+    # writes `.bassclef/init.manifest.json` with its own shape. Lite
+    # adopters hit the lead-lens 3-marker gate because the two manifests
+    # never agreed. Consult the CLI manifest before giving up.
+    if _iwp_init_manifest_has_path "$tgt"; then
+      _iwp_log "check path=$tgt result=true reason=cli-init-manifest-fallback"
+      return 0
+    fi
     _iwp_log "check path=$tgt result=false reason=not-in-manifest"
     return 1
   fi
@@ -335,6 +456,125 @@ install_written_paths_rebuild() {
   return 0
 }
 
+# install_written_paths_rebuild_from_lite_manifest <lite-manifest-path>
+#
+# Bulk-rebuild cure per bassclef-upstream#2200.
+#
+# Replaces the fragment's 451 serial `install_written_paths_register` loop
+# with one atomic rebuild. Reads lite-manifest.json, computes SHA256 per
+# path that exists on disk, writes the full entries array in one jq pass
+# to a tmp file, runs ajv once, then atomically moves tmp over manifest.
+#
+# Deep module per @luminary john-ousterhout — one verb hides the whole
+# rebuild path. Caller stays dumb. Register's per-path semantics stay
+# untouched for ad-hoc callers (hook-connect, migrations) that need
+# per-call ajv (PR #2174 intent preserved).
+#
+# Postcondition (per @luminary tony-hoare):
+#   On return 0: manifest at _iwp_manifest_path() carries one entry per
+#   lite-manifest.json path that passes _iwp_validate_path AND exists on
+#   disk; writer=bassclef-sync-template; content_hash=sha256:<hex>;
+#   written_at=current UTC timestamp. Schema-valid per ajv when ajv present.
+#   On return 1: lite-manifest missing OR malformed; existing manifest
+#   untouched (atomic mv never ran).
+#
+# Returns:
+#   0  success (manifest written)
+#   1  lite-manifest missing | malformed | jq missing
+install_written_paths_rebuild_from_lite_manifest() {
+  local lite_manifest="${1:-}"
+
+  if [ -z "$lite_manifest" ] || [ ! -f "$lite_manifest" ]; then
+    _iwp_log "bulk-rebuild fail reason=lite-manifest-missing path=$lite_manifest"
+    return 1
+  fi
+
+  if ! command -v jq >/dev/null 2>&1; then
+    echo "install-written-paths: jq not available; cannot bulk-rebuild" >&2
+    return 1
+  fi
+
+  # Precondition: lite-manifest.json is valid JSON
+  if ! jq -e . "$lite_manifest" >/dev/null 2>&1; then
+    _iwp_log "bulk-rebuild fail reason=lite-manifest-malformed path=$lite_manifest"
+    return 1
+  fi
+
+  local mpath
+  mpath=$(_iwp_manifest_path)
+  mkdir -p "$(dirname "$mpath")"
+
+  local root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+  local now
+  now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  # Build entries array in a tmp jq-input file: one JSON object per line.
+  # Each line is a {path, writer, written_at, content_hash} record.
+  # Skip entries that fail path validation OR have no file on disk.
+  local jq_input
+  jq_input=$(mktemp)
+  # shellcheck disable=SC2064
+  trap "rm -f \"$jq_input\"" RETURN
+
+  local registered=0
+  local skipped=0
+  while IFS= read -r rel_path; do
+    [ -z "$rel_path" ] && continue
+    if ! _iwp_validate_path "$rel_path"; then
+      skipped=$((skipped + 1))
+      continue
+    fi
+    local full_path
+    case "$rel_path" in
+      /*) full_path="$rel_path" ;;
+      *) full_path="$root/$rel_path" ;;
+    esac
+    if [ ! -f "$full_path" ]; then
+      skipped=$((skipped + 1))
+      continue
+    fi
+    local hash
+    hash=$(_iwp_sha256 "$full_path")
+    if [ -z "$hash" ]; then
+      skipped=$((skipped + 1))
+      continue
+    fi
+    jq -cn --arg p "$rel_path" --arg w "bassclef-sync-template" --arg ts "$now" --arg h "$hash" \
+      '{path:$p, writer:$w, written_at:$ts, content_hash:$h}' >> "$jq_input"
+    registered=$((registered + 1))
+  done < <(jq -r '.entries[]?.path // empty' "$lite_manifest")
+
+  # Build the manifest from the per-line records using jq --slurp.
+  # Tmp filename MUST end in .json so ajv's auto-detect reads it as JSON
+  # instead of trying to require() it as a module (macOS mktemp without
+  # --suffix produces extensionless files that fail ajv's parse).
+  local tmp
+  tmp="$mpath.rebuild.$$.json"
+  if ! jq -s --arg sv "$_IWP_SCHEMA_VERSION" \
+    '{schema_version:$sv, entries:.}' "$jq_input" > "$tmp"; then
+    rm -f "$tmp" 2>/dev/null || true
+    _iwp_log "bulk-rebuild fail reason=jq-slurp-failed registered=$registered"
+    return 1
+  fi
+
+  # Post-write ajv validate; on fail, keep old manifest (atomic safety per Nygard)
+  if ! _iwp_ajv_validate "$tmp"; then
+    echo "install-written-paths: WARNING — bulk-rebuild output fails ajv; keeping prior manifest" >&2
+    rm -f "$tmp" 2>/dev/null || true
+    _iwp_log "bulk-rebuild fail reason=ajv-validate registered=$registered"
+    return 1
+  fi
+
+  if ! mv "$tmp" "$mpath"; then
+    rm -f "$tmp" 2>/dev/null || true
+    _iwp_log "bulk-rebuild fail reason=mv-failed registered=$registered"
+    return 1
+  fi
+
+  _iwp_log "bulk-rebuild ok registered=$registered skipped=$skipped mpath=$mpath"
+  return 0
+}
+
 # install_written_paths_verify
 # Returns 0 on well-formed manifest, 1 on schema violation.
 install_written_paths_verify() {
@@ -365,5 +605,12 @@ install_written_paths_verify() {
     return 1
   fi
 
+  # Ajv-runtime schema check (step 6 — bassclef-upstream#2157).
+  # Fail-soft on ajv missing (returns 0); strict reject on schema failure.
+  if ! _iwp_ajv_validate "$mpath"; then
+    echo "install-written-paths: manifest fails ajv schema validation" >&2
+    return 1
+  fi
+
   return 0
 }

package/dist/lite/lib/prose-marker.sh

@@ -0,0 +1,203 @@
+#!/bin/bash
+# tier: lite
+#
+# lib/prose-marker.sh — shared marker write + read helpers for the bassclef
+# prose scorer stack. Pins the marker format from
+# standards/prose-marker-format.md v1.0.
+#
+# Producers (Stop hooks that score prose dimensions):
+#   - turn-prose-density-measure.sh (Step 2b of Longrun 2)
+#   - turn-prose-kiss-check.sh      (Step 2c extension)
+#   - turn-prose-grade-measure.sh   (future retrofit; writes raw today)
+#
+# Consumer (UserPromptSubmit hook that reads markers + injects numbers):
+#   - plain-english-steering.sh     (Step 2d extension)
+#
+# Per @luminary john-ousterhout — deep module hides JSON shape + atomic
+# write + expiry logic behind a narrow two-function interface.
+# Per @luminary tony-hoare — pre/postcondition contract per
+# standards/prose-marker-format.md §Hoare.
+# Per @luminary michael-nygard — fail-soft on write permission denied.
+
+set +e
+
+# === BASSCLEF_STATE_ROOT resolution ===
+# When tests isolate state via BASSCLEF_STATE_ROOT env var, honor it.
+# Otherwise resolve to the repo root (walk up from this file's location).
+_prose_marker_resolve_state_root() {
+  if [ -n "${BASSCLEF_STATE_ROOT:-}" ]; then
+    echo "$BASSCLEF_STATE_ROOT"
+    return
+  fi
+  local script_dir
+  script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  echo "$(cd "$script_dir/.." && pwd)"
+}
+
+# === write_prose_marker <scorer-name> <value> [notes] ===
+# Preconditions:
+#   - scorer-name is non-empty and matches [a-z0-9-]+
+#   - value is non-empty
+# Postconditions:
+#   - file at state/markers/<scorer-name>/last-turn.json exists
+#   - JSON matches standards/prose-marker-format.md shape
+#   - atomic write (temp file + mv)
+# Returns: 0 on success; 1 on invalid input; 2 on write failure (fail-soft).
+write_prose_marker() {
+  local scorer="$1"
+  local value="$2"
+  local notes="${3:-}"
+
+  # Validate scorer-name
+  if [ -z "$scorer" ]; then
+    return 1
+  fi
+  if ! echo "$scorer" | grep -qE '^[a-z0-9-]+$'; then
+    return 1
+  fi
+
+  # Validate value
+  if [ -z "$value" ]; then
+    return 1
+  fi
+
+  local state_root
+  state_root="$(_prose_marker_resolve_state_root)"
+  local marker_dir="${state_root}/state/markers/${scorer}"
+  local marker_path="${marker_dir}/last-turn.json"
+
+  if ! mkdir -p "$marker_dir" 2>/dev/null; then
+    return 2
+  fi
+
+  local timestamp
+  timestamp="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+  local tmp
+  tmp="$(mktemp "${marker_dir}/last-turn.XXXXXX.tmp" 2>/dev/null)" || return 2
+
+  # Build JSON. Use jq when available for proper escaping; fall back to raw.
+  if command -v jq >/dev/null 2>&1; then
+    if [ -n "$notes" ]; then
+      jq -n \
+        --arg metric "$scorer" \
+        --argjson value "$value" \
+        --arg measured_at "$timestamp" \
+        --arg source "lib/prose-marker.sh" \
+        --arg notes "$notes" \
+        '{metric: $metric, value: $value, measured_at: $measured_at, source: $source, notes: $notes}' \
+        > "$tmp" 2>/dev/null
+    else
+      jq -n \
+        --arg metric "$scorer" \
+        --argjson value "$value" \
+        --arg measured_at "$timestamp" \
+        --arg source "lib/prose-marker.sh" \
+        '{metric: $metric, value: $value, measured_at: $measured_at, source: $source}' \
+        > "$tmp" 2>/dev/null
+    fi
+    local rc=$?
+    if [ "$rc" -ne 0 ]; then
+      rm -f "$tmp" 2>/dev/null
+      return 2
+    fi
+  else
+    # Fallback: raw JSON. Scorer + notes get basic escaping (no quotes in input).
+    if [ -n "$notes" ]; then
+      printf '{"metric":"%s","value":%s,"measured_at":"%s","source":"lib/prose-marker.sh","notes":"%s"}\n' \
+        "$scorer" "$value" "$timestamp" "$notes" > "$tmp" 2>/dev/null
+    else
+      printf '{"metric":"%s","value":%s,"measured_at":"%s","source":"lib/prose-marker.sh"}\n' \
+        "$scorer" "$value" "$timestamp" > "$tmp" 2>/dev/null
+    fi
+  fi
+
+  # Atomic rename
+  if ! mv -f "$tmp" "$marker_path" 2>/dev/null; then
+    rm -f "$tmp" 2>/dev/null
+    return 2
+  fi
+  return 0
+}
+
+# === read_prose_markers [--max-age-minutes N] <scorer-name> [<scorer-name> ...] ===
+# Preconditions:
+#   - zero or more scorer-name arguments
+#   - optional --max-age-minutes N (default 10)
+# Postconditions:
+#   - stdout emits one JSON object mapping scorer-name → marker object OR null
+#   - null when: marker missing, older than max-age, or malformed JSON
+#   - fail-soft: never crashes on bad input
+# Returns: 0 always (fail-soft).
+read_prose_markers() {
+  local max_age_min=10
+  local scorers=()
+
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --max-age-minutes)
+        shift
+        max_age_min="${1:-10}"
+        shift
+        ;;
+      *)
+        scorers+=("$1")
+        shift
+        ;;
+    esac
+  done
+
+  local state_root
+  state_root="$(_prose_marker_resolve_state_root)"
+
+  # Build JSON object. If jq missing, emit raw.
+  if command -v jq >/dev/null 2>&1; then
+    # Start with empty object
+    local result='{}'
+    local scorer
+    for scorer in "${scorers[@]}"; do
+      local marker_path="${state_root}/state/markers/${scorer}/last-turn.json"
+      local marker_json="null"
+      if [ -f "$marker_path" ]; then
+        # Age check
+        local file_age_sec
+        if stat -f %m "$marker_path" >/dev/null 2>&1; then
+          # BSD stat (macOS)
+          file_age_sec=$(( $(date +%s) - $(stat -f %m "$marker_path") ))
+        else
+          # GNU stat (Linux)
+          file_age_sec=$(( $(date +%s) - $(stat -c %Y "$marker_path") ))
+        fi
+        local max_age_sec=$(( max_age_min * 60 ))
+        if [ "$file_age_sec" -le "$max_age_sec" ]; then
+          # Parse marker — null on malformed JSON
+          marker_json=$(jq -c '.' "$marker_path" 2>/dev/null)
+          if [ -z "$marker_json" ]; then
+            marker_json="null"
+          fi
+        fi
+      fi
+      result=$(echo "$result" | jq --arg k "$scorer" --argjson v "$marker_json" '. + {($k): $v}' 2>/dev/null)
+    done
+    echo "$result"
+  else
+    # Fallback without jq — emit a flat null map
+    printf '{'
+    local first=1
+    local scorer
+    for scorer in "${scorers[@]}"; do
+      if [ "$first" -eq 0 ]; then
+        printf ','
+      fi
+      printf '"%s":null' "$scorer"
+      first=0
+    done
+    printf '}\n'
+  fi
+  return 0
+}
+
+# Export functions when sourced
+export -f write_prose_marker 2>/dev/null
+export -f read_prose_markers 2>/dev/null
+export -f _prose_marker_resolve_state_root 2>/dev/null

package/dist/lite/lib/tier-dependency-audit.sh

@@ -814,37 +814,64 @@ build_reverse_index() {
 walk_graph_bfs_inbound() {
   local seeds_file="$1"
   local rev_index="$2"
-  local visited_file="" queue_file=""
-  visited_file="$(mktemp)"
-  queue_file="$(mktemp)"
-  # shellcheck disable=SC2064
-  trap "rm -f '$visited_file' '$queue_file'" RETURN
 
   if [ ! -s "$seeds_file" ]; then
-    : > "$visited_file"
-    sort -u "$visited_file"
     return 0
   fi
-  cp "$seeds_file" "$queue_file"
 
-  local max_iter=1000 iter=0
-  while [ -s "$queue_file" ] && [ "$iter" -lt "$max_iter" ]; do
-    iter=$((iter + 1))
-    local next_file; next_file="$(mktemp)"
-    while IFS= read -r p; do
-      [ -z "$p" ] && continue
-      if grep -Fxq "$p" "$visited_file" 2>/dev/null; then continue; fi
-      echo "$p" >> "$visited_file"
-      # Look up callers of $p in the reverse index (path is column 1; caller is column 2)
-      awk -F'\t' -v p="$p" '$1 == p { print $2 }' "$rev_index" | while IFS= read -r caller; do
-        [ -n "$caller" ] && echo "$caller" >> "$next_file"
-      done
-    done < "$queue_file"
-    mv "$next_file" "$queue_file"
-    sort -u -o "$queue_file" "$queue_file"
-  done
+  if [ ! -s "$rev_index" ]; then
+    # No edges — output just the seeds, deduped
+    sort -u "$seeds_file"
+    return 0
+  fi
 
-  sort -u "$visited_file"
+  # Single-pass awk: build reverse-index hash during Phase 1 (reading
+  # rev_index), then run BFS entirely in-memory during Phase 2 (reading
+  # seeds_file via END block). Visited set prevents re-visiting; queue
+  # grows as new callers are found.
+  #
+  # Complexity: O(N + M) where N = seeds + M = edges in rev_index.
+  # Prior per-item awk was O(N × M) — unusable at 1.1MB index (ticket
+  # bassclef-upstream#2109 observed 15+ min hang during /release).
+  #
+  # Per @luminary john-ousterhout — deep module: one awk hides BFS.
+  # Per @luminary michael-feathers — behavior pinned by Tier 0 tests
+  # at lib/tests/tier-dependency-audit-inbound.test.sh.
+  awk -F'\t' '
+    # Phase 1: load reverse index into callers map
+    # Each line: <path>\t<caller>; multiple callers per path concatenated
+    # with SUBSEP as the separator (safe since SUBSEP is non-printable).
+    NR == FNR {
+      if (NF >= 2 && $1 != "") {
+        callers[$1] = (callers[$1] == "" ? $2 : callers[$1] SUBSEP $2)
+      }
+      next
+    }
+    # Phase 2: enqueue seeds (file 2)
+    {
+      if ($0 != "" && !($0 in visited)) {
+        queue[++qlen] = $0
+        visited[$0] = 1
+      }
+    }
+    # Phase 3: BFS, draining the queue
+    END {
+      head = 1
+      while (head <= qlen) {
+        p = queue[head++]
+        if (p in callers) {
+          n = split(callers[p], c, SUBSEP)
+          for (i = 1; i <= n; i++) {
+            if (c[i] != "" && !(c[i] in visited)) {
+              visited[c[i]] = 1
+              queue[++qlen] = c[i]
+            }
+          }
+        }
+      }
+      for (p in visited) print p
+    }
+  ' "$rev_index" "$seeds_file" | sort -u
   return 0
 }