@thebassclef/lite 1.0.0 → 1.0.1

package/dist/lite/.claude/hooks/longrun-prep-compounding-sequence-check.sh

@@ -0,0 +1,492 @@
+#!/bin/bash
+# tier: lite
+# install-class: dual
+# longrun-prep-compounding-sequence-check.sh — Stop hook that fires when
+# state/markers/turn-prose-surface/longrun_prep_proposal.marker is
+# present. Scans the latest assistant message for the 5 prescribed
+# column headers from /longrun SKILL Step 1.5 (compounding-sequence
+# analysis). Default V2 = strict (exit 2 on missing axes); explicit
+# advisory toggle preserved for backward compat.
+#
+# Per bassclef-upstream#426 V2 flip. Calibration cycle (one /longrun
+# prep after V1 ship) demonstrated the visibility gap: V1 advisory
+# emitted to stderr; agent could not see its own advisory, missed
+# 2-of-5 column at next prep. Flip closes the loop per ADR-035
+# substrate-as-system.
+#
+# Per bet 28a WU-5d (V1 ship) + bet 30b extension (V2 flip with
+# tonight's prep as eat-own-dogfood evidence).
+#
+# Sister hook pattern to turn-prose-kiss-check.sh (Stop hook scanning
+# marker-gated transcript).
+#
+# Override per-call: SKIP_COMPOUNDING_AXIS_CHECK=1
+# Backward compat: COMPOUNDING_AXIS_TOGGLE=advisory — exit 0 + finding
+#                  COMPOUNDING_AXIS_TOGGLE=strict — exit 2 (default; explicit opt-in)
+#
+# Frozen stderr contract (per bassclef-upstream#1536 Hyrum finding):
+#   SECTION-EMPTY guard emits exactly:
+#     "🛑 COMPOUNDING-AXIS — BLOCKED (SECTION-EMPTY per-shape parse boundary; V2 strict default)"
+#     "🛑 COMPOUNDING-AXIS — ADVISORY (SECTION-EMPTY per-shape parse boundary; backward-compat opt-out)"
+#   Per-shape line prefix: "    🔍 <shape>"
+#   Any change to these strings updates this header comment as the observable contract.
+#
+# Tier 0 strict TDD: .claude/hooks/tests/longrun-prep-compounding-sequence-check.test.sh
+
+set +e
+
+INPUT=$(cat)
+TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null || echo "")
+CWD=$(echo "$INPUT" | jq -r '.cwd // "."' 2>/dev/null || echo ".")
+
+# Override
+if [ "${SKIP_COMPOUNDING_AXIS_CHECK:-0}" = "1" ]; then
+  exit 0
+fi
+
+# Marker gate — only fire when /longrun prep proposal is being authored
+MARKER_PATH="$CWD/state/markers/turn-prose-surface/longrun_prep_proposal.marker"
+if [ ! -f "$MARKER_PATH" ]; then
+  exit 0
+fi
+
+# Auto-clean gate (Cure A per ticket #1555) — if a prior Stop event already
+# fired this hook cleanly (exit 0) during this prep session, skip subsequent
+# firings. The consumed sibling marker signals "primary marker's job is done".
+# Operator manually re-touches the primary marker for the next prep proposal.
+# Closes the doom loop where post-prep status turns kept tripping this hook.
+CONSUMED_MARKER="$CWD/state/markers/turn-prose-surface/longrun_prep_proposal.marker.consumed"
+if [ -f "$CONSUMED_MARKER" ]; then
+  exit 0
+fi
+
+# Need transcript to scan
+if [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+  exit 0
+fi
+
+# Extract last assistant message text (per turn-prose-kiss-check pattern)
+LAST_ASSISTANT_LINE=$(grep '"type":"assistant"' "$TRANSCRIPT_PATH" 2>/dev/null | tail -1)
+[ -z "$LAST_ASSISTANT_LINE" ] && exit 0
+
+MESSAGE_TEXT=$(echo "$LAST_ASSISTANT_LINE" | jq -r '.message.content[]? | select(.type == "text") | .text' 2>/dev/null)
+[ -z "$MESSAGE_TEXT" ] && exit 0
+
+# === Check compounding-sequence column headers ===
+# Per /longrun SKILL Step 1.5: option table must include columns for the
+# axis set. Hook accepts EITHER of two shapes during the ADR-031 grace
+# window through 2026-10-31 (bassclef#1555 PR-1):
+#
+# 5-axis LEGACY (original, per bet 28a WU-5d):
+#   Compounding surface | Compounding rate | Foundation prereq |
+#   Inverse-dependency | Risk class
+#
+# 6-axis NEW (per plan doc 2026-09-09-compounding-axis-refactor):
+#   Deliverable | Problem | Value prop | Turns | Risk | Shipping priority
+#
+# Try each axis set. The hook passes if EITHER set matches. If neither
+# matches, BLOCK naming the axes missing from the closest shape (fewest
+# missing entries).
+
+check_axis_any() {
+  # Returns 0 if any variant appears in MESSAGE_TEXT; else 1
+  local variant
+  for variant in "$@"; do
+    if echo "$MESSAGE_TEXT" | grep -qi "$variant"; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+# --- 5-axis LEGACY set ---
+FIVE_MISSING=()
+check_axis_any "Compounding surface" "Compounds at" "Where the payoff shows up" \
+  || FIVE_MISSING+=("Compounding surface")
+check_axis_any "Compounding rate" "| *Rate" "How often it fires" \
+  || FIVE_MISSING+=("Compounding rate")
+check_axis_any "Foundation prereq" "What must be true first" \
+  || FIVE_MISSING+=("Foundation prereq")
+check_axis_any "Inverse-dependency" "Does this teach" \
+  || FIVE_MISSING+=("Inverse-dependency")
+check_axis_any "Risk class" "| *Risk" "What breaks if" \
+  || FIVE_MISSING+=("Risk class")
+
+# --- 6-axis NEW set (bassclef#1555 PR-1) ---
+SIX_MISSING=()
+check_axis_any "Deliverable" "Ships when" \
+  || SIX_MISSING+=("Deliverable")
+check_axis_any "Problem" "Pain" \
+  || SIX_MISSING+=("Problem")
+check_axis_any "Value prop" "value proposition" \
+  || SIX_MISSING+=("Value prop")
+check_axis_any "Turns" "Turn count" "Turn range" "Turn estimate" \
+  || SIX_MISSING+=("Turns")
+check_axis_any "Risk" "| *Risk" "🟢" "🟡" "🔴" \
+  || SIX_MISSING+=("Risk")
+check_axis_any "Shipping priority" "Priority:" "\bQ1\b" "\bQ2\b" "\bQ3\b" "\bQ4\b" \
+  || SIX_MISSING+=("Shipping priority")
+
+# Pick the shape with fewer missing axes; if neither set is complete, that
+# shape is what MISSING reports. If either set is complete (empty missing
+# array), the message passes the header check.
+if [ "${#FIVE_MISSING[@]}" -eq 0 ] || [ "${#SIX_MISSING[@]}" -eq 0 ]; then
+  MISSING=()
+elif [ "${#FIVE_MISSING[@]}" -le "${#SIX_MISSING[@]}" ]; then
+  MISSING=("${FIVE_MISSING[@]}")
+else
+  MISSING=("${SIX_MISSING[@]}")
+fi
+
+# === Per-shape distinct-value check (bassclef-upstream#564) ===
+# When 2+ shape section headers appear (**Shape a**, ### Shape a, etc.),
+# the rule postcondition per Hoare requires each shape section to render
+# all 5 axes with distinct values. A single header row with axis names
+# but no per-shape values is R8 pattern — label without work.
+#
+# Per luminary consultation: Ousterhout (deep modules; SKILL + rule +
+# hook = one contract with matching depth), Hoare (strong postcondition),
+# Feathers (characterization tests use tonight's prep messages), Saltzer
+# & Schroeder (complete mediation; every axis cell mediates), Beck (TDD).
+#
+# Falsifies R8 flavor A (aggregate cells collapse axes into one).
+# This check only fires when message-level axis names ARE present
+# (avoids double-firing on pure message-level miss).
+
+# === Per-WU compounding-sequence check (bassclef-upstream#597) ===
+# When prep proposal contains a produces/consumes WU table with 2+ WU
+# rows (multi-step bet), the message must also render per-step compounding
+# axes — either via "Compounding value per step" heading OR per-step axis
+# rendering that names each step with its 5 axes.
+#
+# Convention worked for weeks (bet-doc convention). Tonight's PR #567
+# tightened Step 1.5 to require 5 distinct axes per shape and the
+# attention shift crowded the per-step habit out. Per ADR-035
+# substrate-as-system tenet, mechanize the convention so it survives
+# sibling-discipline tightening.
+#
+# Fires only when the message passes the shape-level checks first —
+# avoids double-firing when the message-level column check already
+# BLOCKED.
+
+if [ "${#MISSING[@]}" -eq 0 ]; then
+  # Count WU rows in produces/consumes tables. WU row markers include:
+  # | **1** | ...  or  | **WU-1** | ...  or  **WU-1** in bullets.
+  # Use a permissive regex to catch canonical bet-doc formats.
+  WU_ROW_COUNT=$(echo "$MESSAGE_TEXT" | grep -cE '^\|[[:space:]]*\*\*(WU-)?[0-9]+\*\*' 2>/dev/null || echo 0)
+  # Sanitize (grep -c can print trailing content on some macOS bash)
+  WU_ROW_COUNT=$(echo "$WU_ROW_COUNT" | tr -cd '0-9')
+  [ -z "$WU_ROW_COUNT" ] && WU_ROW_COUNT=0
+
+  if [ "$WU_ROW_COUNT" -ge 2 ]; then
+    # Look for either the canonical section heading OR per-step axis rendering.
+    HAS_PER_WU_HEADING=$(echo "$MESSAGE_TEXT" | grep -ciE '(compounding value per step|per-step compounding|compounding sequence per step|compounding.axis.*wu)' 2>/dev/null | tr -cd '0-9')
+    [ -z "$HAS_PER_WU_HEADING" ] && HAS_PER_WU_HEADING=0
+
+    if [ "$HAS_PER_WU_HEADING" -eq 0 ]; then
+      TOGGLE="${COMPOUNDING_AXIS_TOGGLE:-strict}"
+      if [ "$TOGGLE" = "advisory" ]; then
+        LABEL="ADVISORY (per-step; backward-compat opt-out)"
+      else
+        LABEL="BLOCKED (per-step compounding columns missing; V1 strict default)"
+      fi
+
+      echo "" >&2
+      echo "🛑 COMPOUNDING-AXIS — $LABEL" >&2
+      echo "" >&2
+      echo "  /longrun prep proposal has $WU_ROW_COUNT WU rows in the" >&2
+      echo "  produces/consumes table but no per-step compounding-sequence" >&2
+      echo "  rendering (R8 pattern — convention displaced by sibling" >&2
+      echo "  tightening in PR #567)." >&2
+      echo "" >&2
+      echo "  Per bassclef-upstream#597 + ADR-035 substrate-as-system:" >&2
+      echo "  each step section must carry the 5 axes (plain-English preferred):" >&2
+      echo "    - Where the payoff shows up (was: Compounding surface)" >&2
+      echo "    - How often it fires (was: Compounding rate)" >&2
+      echo "    - What must be true first (was: Foundation prereq)" >&2
+      echo "    - Does this teach a shape later work reuses (was: Inverse-dependency)" >&2
+      echo "    - What breaks if we ship this half-done (was: Risk class)" >&2
+      echo "  Both label forms accepted through 2026-10-31 per ADR-040 D4." >&2
+      echo "" >&2
+      echo "  Cure: add a '## Compounding value per step' section OR render" >&2
+      echo "  each step with its 5 axes as bullets. See" >&2
+      echo "  .claude/rules/compounding-sequence-fresh-analysis.md for shape." >&2
+      echo "" >&2
+      echo "  Override: SKIP_COMPOUNDING_AXIS_CHECK=1 (logged)" >&2
+      echo "  Backward compat: COMPOUNDING_AXIS_TOGGLE=advisory (exit 0)" >&2
+      echo "" >&2
+
+      SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+      if [ -f "$SCRIPT_DIR/trace-helper.sh" ]; then
+        # shellcheck disable=SC1091
+        source "$SCRIPT_DIR/trace-helper.sh"
+        trace_log "compounding-sequence-check" "$LABEL per-step-missing count=$WU_ROW_COUNT"
+      fi
+
+      [ "$TOGGLE" = "advisory" ] && exit 0
+      exit 2
+    fi
+  fi
+
+  # Per bassclef-upstream#1193 — SKILL rename #830 replaced "Shape a-c"
+  # with "Option a-e". Regex accepts both during the grace window
+  # through 2026-10-31 per .claude/rules/we-dont-break-adopters.md.
+  # After that date, only "Option [a-z]" matches.
+  SHAPES=$(echo "$MESSAGE_TEXT" | grep -Eo '(Shape [a-c]|Option [a-z])\b' | sort -u)
+
+  # Per bassclef-upstream#1376 — accept per-recommended-only shape.
+  # When the message opens with `**Recommend:** Option X` (or Shape X),
+  # the reader lands the pick in the first 15 lines. Non-recommended
+  # options carry their axes as one-liner cells in the scan-table row,
+  # not as full sections. The hook trusts the Recommend line: it treats
+  # the labeled option as REQUIRED (section + 5 axes) and treats every
+  # other option as OPTIONAL (a missing section stops SECTION-EMPTY from
+  # firing on that option).
+  #
+  # Per Tufte data-ink (drop fields that do not change the pick) +
+  # Prater progressive disclosure (default minimum; expand on ask).
+  # Sister #959 lands the SKILL body trim; this hook amend unblocks it.
+  RECOMMENDED_OPTION=$(echo "$MESSAGE_TEXT" | grep -Eo '\*\*Recommend[^*]*\*\*[[:space:]]*(Shape [a-c]|Option [a-z])' | head -1 | grep -Eo '(Shape [a-c]|Option [a-z])' | head -1)
+  if [ -z "$SHAPES" ]; then
+    SHAPE_COUNT=0
+  else
+    SHAPE_COUNT=$(echo "$SHAPES" | wc -l | tr -d ' ')
+  fi
+
+  # Per-shape check fires when 2+ options AND for recommended-only shape
+  # even with 1 option (bassclef-upstream#1376) — the recommended option's
+  # section must carry all 5 axes with distinct values.
+  if [ "$SHAPE_COUNT" -ge 2 ] || [ -n "$RECOMMENDED_OPTION" ]; then
+    PER_SHAPE_MISSING=""
+    SECTION_EMPTY_SHAPES=""
+    while IFS= read -r shape; do
+      [ -z "$shape" ] && continue
+      # Section boundaries require a heading anchor at line start
+      # (H2+ heading like `## Option a`, `### Option a`, `#### Option a`,
+      # or bold prefix `**Option a`) so mid-body cross-references like
+      # "same end-state as Option b" do not trigger a false section
+      # boundary. Cure per bassclef-upstream#1421 Option (a). H2+ range
+      # per bassclef-upstream#1532 — options nested under a container H3
+      # anchor (e.g., `### Compounding value per option`) resolve cleanly
+      # regardless of nesting depth. H1 excluded by design.
+      SECTION=$(echo "$MESSAGE_TEXT" | awk -v want="$shape" '
+        BEGIN { in_section=0 }
+        /^(##+ |\*\*)(Shape [a-c]|Option [a-z])/ {
+          if ($0 ~ want) { in_section=1; print; next }
+          else if (in_section) { in_section=0 }
+        }
+        in_section { print }
+      ')
+
+      # Hoare precondition guard (bassclef-upstream#1536) — when shape name
+      # matches via grep-Eo but SECTION returns empty, the heading boundary
+      # is missing. Fail-safe per Saltzer-Schroeder: capture + emit distinct
+      # diagnostic under the existing banner + exit 2. Advisory toggle preserved.
+      #
+      # Recommended-only shape carve-out (bassclef-upstream#1376) — when the
+      # message declares a recommended option via **Recommend:** ..., non-
+      # recommended options may legitimately lack a section (they carry axes
+      # as scan-table cells only). Skip SECTION-EMPTY for those; still fire
+      # SECTION-EMPTY if the RECOMMENDED option has no section.
+      if [ -z "$SECTION" ]; then
+        if [ -n "$RECOMMENDED_OPTION" ] && [ "$shape" != "$RECOMMENDED_OPTION" ]; then
+          continue
+        fi
+        SECTION_EMPTY_SHAPES="${SECTION_EMPTY_SHAPES}    🔍 ${shape}\n"
+        continue
+      fi
+
+      # Recommended-only shape carve-out (bassclef-upstream#1376) —
+      # only the recommended option must carry all 5 axes distinctly in
+      # per-recommended-only mode. Non-recommended options with a partial
+      # section skip the per-axis check.
+      if [ -n "$RECOMMENDED_OPTION" ] && [ "$shape" != "$RECOMMENDED_OPTION" ]; then
+        continue
+      fi
+
+      # Grace window per bet 2026-07-16b WU-2 (#734) + bassclef#1555 PR-1 —
+      # per-shape check accepts EITHER 5-axis LEGACY or 6-axis NEW shape.
+      # Determine which axis set the section uses, then verify all axes of
+      # that set are present. If neither set is complete for this section,
+      # report the set with fewer missing axes.
+
+      # Try 5-axis set on this section
+      FIVE_SECTION_MISSING=()
+      echo "$SECTION" | grep -qiE "Compounding surface|Compounds at|Where the payoff shows up" \
+        || FIVE_SECTION_MISSING+=("Compounding surface")
+      echo "$SECTION" | grep -qiE "Compounding rate|\| *Rate|How often it fires" \
+        || FIVE_SECTION_MISSING+=("Compounding rate")
+      echo "$SECTION" | grep -qiE "Foundation prereq|What must be true first" \
+        || FIVE_SECTION_MISSING+=("Foundation prereq")
+      echo "$SECTION" | grep -qiE "Inverse-dependency|Does this teach" \
+        || FIVE_SECTION_MISSING+=("Inverse-dependency")
+      echo "$SECTION" | grep -qiE "Risk class|\| *Risk|What breaks if" \
+        || FIVE_SECTION_MISSING+=("Risk class")
+
+      # Try 6-axis set on this section
+      SIX_SECTION_MISSING=()
+      echo "$SECTION" | grep -qiE "Deliverable|Ships when" \
+        || SIX_SECTION_MISSING+=("Deliverable")
+      echo "$SECTION" | grep -qiE "Problem|Pain" \
+        || SIX_SECTION_MISSING+=("Problem")
+      echo "$SECTION" | grep -qiE "Value prop|value proposition" \
+        || SIX_SECTION_MISSING+=("Value prop")
+      echo "$SECTION" | grep -qiE "Turns|Turn count|Turn range|Turn estimate" \
+        || SIX_SECTION_MISSING+=("Turns")
+      echo "$SECTION" | grep -qiE "Risk|🟢|🟡|🔴" \
+        || SIX_SECTION_MISSING+=("Risk")
+      echo "$SECTION" | grep -qiE "Shipping priority|Priority:|\bQ1\b|\bQ2\b|\bQ3\b|\bQ4\b" \
+        || SIX_SECTION_MISSING+=("Shipping priority")
+
+      # Pick the shape with fewer missing per this section. If either set is
+      # complete for this section, that section passes.
+      if [ "${#FIVE_SECTION_MISSING[@]}" -eq 0 ] || [ "${#SIX_SECTION_MISSING[@]}" -eq 0 ]; then
+        : # section passes — one of the two shapes is complete
+      elif [ "${#FIVE_SECTION_MISSING[@]}" -le "${#SIX_SECTION_MISSING[@]}" ]; then
+        for axis_name in "${FIVE_SECTION_MISSING[@]}"; do
+          PER_SHAPE_MISSING="${PER_SHAPE_MISSING}    - ${shape}: missing '${axis_name}'\n"
+        done
+      else
+        for axis_name in "${SIX_SECTION_MISSING[@]}"; do
+          PER_SHAPE_MISSING="${PER_SHAPE_MISSING}    - ${shape}: missing '${axis_name}'\n"
+        done
+      fi
+    done <<< "$SHAPES"
+
+    # Hoare precondition guard emit — SECTION-EMPTY takes precedence over
+    # "distinct values missing" because a failed parse is a different
+    # failure class than missing content. Per bassclef-upstream#1536.
+    if [ -n "$SECTION_EMPTY_SHAPES" ]; then
+      TOGGLE="${COMPOUNDING_AXIS_TOGGLE:-strict}"
+      if [ "$TOGGLE" = "advisory" ]; then
+        LABEL="ADVISORY (SECTION-EMPTY per-shape parse boundary; backward-compat opt-out)"
+      else
+        LABEL="BLOCKED (SECTION-EMPTY per-shape parse boundary; V2 strict default)"
+      fi
+      echo "" >&2
+      echo "🛑 COMPOUNDING-AXIS — $LABEL" >&2
+      echo "" >&2
+      echo "  /longrun prep proposal references shapes but SECTION extraction" >&2
+      echo "  returned empty. Precondition failure — heading boundary not found." >&2
+      echo "  Per Hoare precondition contract (bassclef-upstream#1536)." >&2
+      echo "" >&2
+      echo "  SECTION-EMPTY shapes:" >&2
+      printf "$SECTION_EMPTY_SHAPES" >&2
+      echo "" >&2
+      echo "  Cure: give each shape a heading anchor at H2 through H6" >&2
+      echo "  (e.g., '#### Option a') or bold prefix ('**Option a')." >&2
+      echo "  See fixture 2026-09-08-step-1-4c-worked-example/ for the shape." >&2
+      echo "" >&2
+      echo "  Override: SKIP_COMPOUNDING_AXIS_CHECK=1 (logged)" >&2
+      echo "  Backward compat: COMPOUNDING_AXIS_TOGGLE=advisory (exit 0)" >&2
+      echo "" >&2
+
+      SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+      if [ -f "$SCRIPT_DIR/trace-helper.sh" ]; then
+        # shellcheck disable=SC1091
+        source "$SCRIPT_DIR/trace-helper.sh"
+        trace_log "compounding-sequence-check" "$LABEL section-empty"
+      fi
+
+      [ "$TOGGLE" = "advisory" ] && exit 0
+      exit 2
+    fi
+
+    if [ -n "$PER_SHAPE_MISSING" ]; then
+      TOGGLE="${COMPOUNDING_AXIS_TOGGLE:-strict}"
+      if [ "$TOGGLE" = "advisory" ]; then
+        LABEL="ADVISORY (per-shape; backward-compat opt-out)"
+      else
+        LABEL="BLOCKED (per-shape distinct values missing; V2 strict default)"
+      fi
+
+      echo "" >&2
+      echo "🛑 COMPOUNDING-AXIS — $LABEL" >&2
+      echo "" >&2
+      echo "  /longrun prep proposal has $SHAPE_COUNT shape sections but" >&2
+      echo "  the axes do not render distinctly per shape (R8 pattern)." >&2
+      echo "" >&2
+      echo "  Per bassclef-upstream#564 + luminary consultation" >&2
+      echo "  (Ousterhout/Hoare/Feathers/Saltzer-Schroeder/Beck):" >&2
+      echo "  each shape section must carry all 5 axes as distinct values." >&2
+      echo "" >&2
+      echo "  Missing per-shape values:" >&2
+      printf "$PER_SHAPE_MISSING" >&2
+      echo "" >&2
+      echo "  Cure: for each shape (a, b, c...), render all 5 axes with" >&2
+      echo "  their distinct values under that shape's section." >&2
+      echo "" >&2
+      echo "  Override: SKIP_COMPOUNDING_AXIS_CHECK=1 (logged)" >&2
+      echo "  Backward compat: COMPOUNDING_AXIS_TOGGLE=advisory (exit 0)" >&2
+      echo "" >&2
+
+      SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+      if [ -f "$SCRIPT_DIR/trace-helper.sh" ]; then
+        # shellcheck disable=SC1091
+        source "$SCRIPT_DIR/trace-helper.sh"
+        trace_log "compounding-sequence-check" "$LABEL per-shape-missing"
+      fi
+
+      [ "$TOGGLE" = "advisory" ] && exit 0
+      exit 2
+    fi
+  fi
+  # True-clean pass — all message-level axes present, per-WU + per-shape
+  # checks passed. Write consumed sibling marker per Cure A (ticket #1555)
+  # so subsequent Stop events skip the scan for this prep session.
+  touch "$CONSUMED_MARKER" 2>/dev/null || true
+  exit 0
+fi
+
+# === Emit finding ===
+# Default V2 = strict. Explicit "advisory" toggle preserves backward compat.
+TOGGLE="${COMPOUNDING_AXIS_TOGGLE:-strict}"
+
+if [ "$TOGGLE" = "advisory" ]; then
+  LABEL="ADVISORY (backward-compat opt-out)"
+else
+  LABEL="BLOCKED (V2 strict default)"
+fi
+
+echo "" >&2
+echo "🛑 COMPOUNDING-AXIS — $LABEL" >&2
+echo "" >&2
+echo "  /longrun prep proposal detected (marker present)." >&2
+echo "  Per /longrun SKILL Step 1.5 + bet 28a WU-5d:" >&2
+echo "  shape proposal table must include compounding-sequence columns." >&2
+echo "" >&2
+echo "  Missing axes in latest assistant message (plain-English preferred):" >&2
+for col in "${MISSING[@]}"; do
+  case "$col" in
+    "Compounding surface")   echo "    - Where the payoff shows up (was: Compounding surface)" >&2 ;;
+    "Compounding rate")      echo "    - How often it fires (was: Compounding rate)" >&2 ;;
+    "Foundation prereq")     echo "    - What must be true first (was: Foundation prereq)" >&2 ;;
+    "Inverse-dependency")    echo "    - Does this teach a shape later work reuses (was: Inverse-dependency)" >&2 ;;
+    "Risk class")            echo "    - What breaks if we ship this half-done (was: Risk class)" >&2 ;;
+    *)                       echo "    - $col" >&2 ;;
+  esac
+done
+echo "" >&2
+echo "  Cure: add these axes to the option table before operator picks." >&2
+echo "  Each option row carries a value per axis. Both label forms accepted" >&2
+echo "  through 2026-10-31 per ADR-040 D4." >&2
+echo "" >&2
+echo "  Override: SKIP_COMPOUNDING_AXIS_CHECK=1 (logged via trace)" >&2
+echo "  Backward compat: COMPOUNDING_AXIS_TOGGLE=advisory (exit 0)" >&2
+echo "" >&2
+
+# Trace log
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [ -f "$SCRIPT_DIR/trace-helper.sh" ]; then
+  # shellcheck disable=SC1091
+  source "$SCRIPT_DIR/trace-helper.sh"
+  trace_log "compounding-sequence-check" "$LABEL missing=${MISSING[*]}"
+fi
+
+# Advisory mode (backward compat): exit 0
+if [ "$TOGGLE" = "advisory" ]; then
+  exit 0
+fi
+
+# Strict mode (default V2): exit 2 to block the stop
+exit 2

package/dist/lite/.claude/hooks/plain-english-steering.sh

@@ -0,0 +1,156 @@
+#!/bin/bash
+# tier: lite
+# install-class: dual
+# plain-english-steering.sh — UserPromptSubmit hook that injects
+# additionalContext steering the agent toward grade-10 plain English
+# at source. Per bassclef-upstream#443 + bet 28a WU-5c.
+#
+# Adds Layer 0 to the 5-layer prose-discipline defense
+# (per .claude/rules/operator-facing-prose.md):
+#
+#   Layer 0 (this hook, UserPromptSubmit) — steer at source
+#   Layer 1 (substrate-clarity-gate, PreToolUse Edit on substrate paths)
+#   Layer 2 (pre-gh-pr-body-scrub, PreToolUse Bash for gh pr create/edit)
+#   Layer 3 (pre-gh-issue-body-scrub + pre-git-commit-msg-scrub)
+#   Layer 4 (turn-prose-kiss-check, Stop hook scanning assistant message)
+#   Layer 5 (CI bassclef-pr-ci.yml jobs as backstop)
+#
+# Override per-call: SKIP_PLAIN_ENGLISH_STEERING=1
+#
+# Tier 0 strict TDD: .claude/hooks/tests/plain-english-steering.test.sh
+
+set +e
+
+# === Source install-class-aware lib (per kiss cure pattern) ===
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+for _candidate in \
+  "${SCRIPT_DIR}/../../lib/hook-inject.sh" \
+  "${HOME_OVERRIDE:-${HOME:-/}}/lib/hook-inject.sh"; do
+  if [ -f "$_candidate" ]; then
+    # shellcheck disable=SC1090
+    source "$_candidate"
+    break
+  fi
+done
+
+# Defensive: if lib not loaded, exit silent
+if ! declare -f emit_additional_context >/dev/null 2>&1; then
+  exit 0
+fi
+
+# Override
+if [ "${SKIP_PLAIN_ENGLISH_STEERING:-0}" = "1" ]; then
+  exit 0
+fi
+
+# === Read last-turn grade marker (if present) ===
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+GRADE_MARKER="${REPO_ROOT}/state/markers/turn-grade/last-turn.json"
+FLAGS_MARKER="${REPO_ROOT}/state/markers/turn-prose-flags/last-turn.json"
+GRADE_LINE=""
+FALLBACK_WARNING=""
+FLAGS_LINE=""
+
+if [ -f "$GRADE_MARKER" ]; then
+  LAST_GRADE=$(jq -r '.grade // ""' "$GRADE_MARKER" 2>/dev/null)
+  LAST_WORDS=$(jq -r '.words // ""' "$GRADE_MARKER" 2>/dev/null)
+  SOURCE=$(jq -r '.source // "UNKNOWN"' "$GRADE_MARKER" 2>/dev/null)
+  if [ -n "$LAST_GRADE" ] && [ "$LAST_GRADE" != "null" ]; then
+    # Classify per Norman + Ogilvy guidance (ticket #935 target shift):
+    # - Aim grade 8 for 80%+ of prose (was grade 8-9 pre-#935)
+    # - Grade 10 is the ceiling for simple technical sentences
+    # - Sentences above 10 need EXPLICIT justification
+    GRADE_STATUS=$(python3 -c "
+g = float('$LAST_GRADE')
+if g <= 8: print('ON TARGET (grade 8 or below)')
+elif g <= 9: print('SLIGHTLY ABOVE (target grade 8; ceiling 10) — trim one clause or drop a compound noun')
+elif g <= 10: print('AT THE GRADE-10 CEILING — tighten sentences and drop compound nouns to land at 8')
+else: print('ABOVE THE GRADE-10 CEILING — rewrite in short SVO. Any sentence above 10 needs a clear reason grades 8-10 could not say it')
+" 2>/dev/null)
+
+    # Ship 1 #1312: extract top 3 offender sentences that broke grade 10.
+    # Named offenders replace aggregate score as actionable signal.
+    OFFENDERS_LINE=""
+    OFFENDERS_COUNT=$(jq -r '.top_offenders | length' "$GRADE_MARKER" 2>/dev/null)
+    if [ -n "$OFFENDERS_COUNT" ] && [ "$OFFENDERS_COUNT" != "null" ] && [ "$OFFENDERS_COUNT" -gt 0 ] 2>/dev/null; then
+      OFFENDERS_BULLETS=$(jq -r '.top_offenders[] | "- Grade \(.grade), \(.words) words: \"\(.preview)\""' "$GRADE_MARKER" 2>/dev/null)
+      OFFENDERS_LINE="
+
+**Top ${OFFENDERS_COUNT} sentence(s) from LAST turn above grade 10 — rewrite these first this turn:**
+${OFFENDERS_BULLETS}"
+    fi
+
+    GRADE_LINE="
+
+**From your LAST turn (not this one): grade ${LAST_GRADE} (${LAST_WORDS} words). Target: grade 8 for 80%+ of prose. Ceiling: 10 for simple technical sentences. ${GRADE_STATUS}. THIS turn is not measured yet — self-check each sentence before I ship it.** (Per #1044 Option B: post-turn measurement + pre-turn injection means the number I see is one turn old by design.)${OFFENDERS_LINE}"
+    if [ "$SOURCE" = "FALLBACK" ]; then
+      FALLBACK_WARNING="
+
+**textstat not installed; grade uses the hand-rolled fallback. Numbers are approximate. Run \`pip install textstat\` for the sharper score.**"
+    fi
+  fi
+fi
+
+# === Read rewrite-check flags marker (ticket #935 extension) ===
+if [ -f "$FLAGS_MARKER" ]; then
+  FL_WORDS=$(jq -r '.total_words // 0' "$FLAGS_MARKER" 2>/dev/null)
+  FL_LONG=$(jq -r '.long_sentences // 0' "$FLAGS_MARKER" 2>/dev/null)
+  FL_PASSIVE=$(jq -r '.passive_voice // 0' "$FLAGS_MARKER" 2>/dev/null)
+  FL_HYPHEN=$(jq -r '.hyphen_words // 0' "$FLAGS_MARKER" 2>/dev/null)
+  # Only inject the flags line when something caught the writer's attention
+  if [ "$FL_LONG" != "0" ] || [ "$FL_PASSIVE" != "0" ] || [ "$FL_HYPHEN" != "0" ]; then
+    FLAGS_LINE="
+
+**From your LAST turn (not this one) — hit counts.** Long sentences past 25 words: ${FL_LONG}. Passive voice: ${FL_PASSIVE}. Hyphen words: ${FL_HYPHEN}. THIS turn is not measured yet — I check each sentence before I ship it."
+  fi
+fi
+
+# === Emit steering content ===
+# Extension per ticket #935 — first-person Ogilvy compose tests
+# grounded in standards/ogilvy-writing-rules.md (from #934 PR #938)
+STEERING_CONTENT="**Plain English for anything the operator or an adopter reads:**
+
+For turn output, PR body, issue body, session log, journal entry, and skill output:
+
+- Bassclef aims for grade 8 in most prose. Grade 10 is the top limit for simple technical sentences.
+- Above grade 10, give a clear reason grades 8-10 could not say it. A technical topic on its own is not a reason.
+- Short sentences. Subject-verb-object.
+- If I want to use a hyphen word (X-side, X-as-Y, N-layer X, X gate), I write what it does instead.
+- No more than two nouns in a row without a verb between them.
+- Drop words that only bassclef readers know — see standards/bassclef-internal-jargon.md.
+- Keep standard tech words: API, hook, PR, schema, ORM.
+
+**Vocabulary rename active (per ADR-040 D1; grace window through 2026-10-31):**
+
+When I author NEW prose for the operator or an adopter, I use the new terms:
+
+- Say **goal** not **bet**. (Historical goal IDs like \`bet 08-11a\` stay as-is.)
+- Say **step** not **WU** or **workunit**. (Historical \`WU-2\` refs stay.)
+- Say **in_flight_goal** not **in_flight_bet** for new whereami updates.
+- Say **time budget** not **appetite** for new prose.
+- Say **parent goal** and **thread** not **parent bet** and **arc** for new prose.
+
+**Discrimination cue.** Two situations, two different rules:
+
+1. When I AUTHOR — writing my own sentence about work in flight or scope decisions — I use the new terms (Step-N, goal, time budget). Never introduce \`WU-N\` or \`bet\` or \`appetite\` in new prose.
+2. When I QUOTE a past goal ID or reference (\`bet 27c WU-5\`, \`bet 2026-06-20a WU-1\`) — I preserve the exact historical string verbatim inside backticks. The backticks mark the historical boundary. The reader sees \"quote\" not \"active vocabulary.\"
+
+Rule of thumb: if I am about to type \`WU-\` in a sentence, ask — am I quoting a historical goal ID? If yes, wrap in backticks. If no, use Step-N instead.
+
+Historical mentions (past goal IDs, closed PR bodies, archived session logs) keep the old words — read-through via \`standards/vocabulary-migration.json\`.
+
+**Compose check this turn (per Ogilvy + Roman-Raphaelson via standards/ogilvy-writing-rules.md).**
+Before I write each sentence, I ask:
+
+- Natural voice — would a real person say this to a peer? If it sounds like corporate throat-clearing, rewrite.
+- Short units — is this sentence past 25 words? If yes, split.
+- Read-aloud — when I read this in my head, does it stumble? If yes, rewrite until it flows.
+- Completeness — is the ONE thing the reader needs to take from this actually written down in plain language?
+- Honesty — am I saying what I mean or hiding behind hedge words and euphemisms? Say it straight.
+- Facts with context — for each number or fact, did I say why it matters?
+
+Per bassclef#790 + .claude/rules/operator-facing-prose.md + .claude/rules/writing-craft-discipline.md.${GRADE_LINE}${FLAGS_LINE}${FALLBACK_WARNING}"
+
+# Use emit_additional_context to wrap as JSON envelope
+emit_additional_context "UserPromptSubmit" "$STEERING_CONTENT"
+exit 0