@thebassclef/lite 0.0.1 → 0.1.2

package/substrate/lib/hook-inject.sh

@@ -0,0 +1,255 @@
+#!/usr/bin/env bash
+# tier: lite
+# install-class: dual
+# lib/hook-inject.sh — shared helper for hooks that inject additionalContext
+# per standards/hook-injection-discipline.md and resolve project resources
+# per standards/hook-install-class.md.
+#
+# This library is SOURCED by hooks, not executed. It does not set -e/-u
+# globally (would affect callers); functions enforce their own contracts.
+#
+# Authority: ADR-035 (substrate-as-system + hooks-as-steering-surfaces)
+# Tier 0 strict TDD: lib/tests/hook-inject.test.sh
+# Anchors: @luminary john-ousterhout (deep modules) + @luminary michael-nygard
+# (fail-soft fallback chain) + @luminary tony-hoare (pre/post contracts)
+#
+# Exposed functions:
+#   emit_additional_context <event> <content>       # JSON envelope to stdout
+#   emit_base_pair_reminders                         # plain-English + assert-verify reminder text
+#   resolve_standards_path <filename>                # CLAUDE_PROJECT_DIR → env → HOME → fail
+#   resolve_config_path                              # same chain for bassclef-configs.jsonc
+#   extract_block_terms <jargon-file>                # BLOCK-tier rows from wordlist
+#
+# Env vars consumed:
+#   CLAUDE_PROJECT_DIR    — project root (Claude Code sets this)
+#   KISS_STANDARDS_FILE   — override for standards path resolution
+#   BASSCLEF_CONFIG_FILE  — override for config path resolution
+#   HOME_OVERRIDE         — test-only; replaces $HOME for fixture isolation
+#
+# Per standards/hook-injection-discipline.md:
+#   - additionalContext capped at 10,000 chars (Anthropic limit)
+#   - JSON envelope shape: {"hookSpecificOutput": {"hookEventName": "...", "additionalContext": "..."}}
+#   - Fail-soft: all resolution helpers return non-zero with structured stderr; never silently pass
+
+# === Constants ===
+HOOK_INJECT_MAX_CONTENT=10000
+
+# === Resolve $HOME with test-override support ===
+__hook_inject_home() {
+  echo "${HOME_OVERRIDE:-$HOME}"
+}
+
+# === emit_additional_context ===
+# Args:
+#   $1 — event name (e.g., UserPromptSubmit, Stop)
+#   $2 — content (the additionalContext string)
+# Stdout: JSON envelope per Anthropic's hookSpecificOutput shape
+# Exit: 0 success; 2 missing/invalid args
+emit_additional_context() {
+  local event="${1:-}"
+  local content="${2-}"  # NOT :- so explicit empty string is allowed (test case)
+
+  # Validate event arg
+  if [ -z "$event" ]; then
+    echo "emit_additional_context: missing event arg" >&2
+    echo "  Usage: emit_additional_context <event-name> <content>" >&2
+    return 2
+  fi
+
+  # Reject event names with spaces (Anthropic events are single tokens)
+  if echo "$event" | grep -q ' '; then
+    echo "emit_additional_context: invalid event name '$event' (spaces not allowed)" >&2
+    echo "  Anthropic hook events are single tokens like UserPromptSubmit, Stop, PostToolUse" >&2
+    return 2
+  fi
+
+  # Validate content arg presence (allow empty string but require the arg)
+  if [ $# -lt 2 ]; then
+    echo "emit_additional_context: missing content arg" >&2
+    echo "  Usage: emit_additional_context <event-name> <content>" >&2
+    return 2
+  fi
+
+  # Truncate if exceeds Anthropic 10K cap
+  local truncated=0
+  if [ ${#content} -gt $HOOK_INJECT_MAX_CONTENT ]; then
+    content="${content:0:$HOOK_INJECT_MAX_CONTENT}"
+    truncated=1
+  fi
+
+  # Emit JSON envelope via jq for proper escaping
+  if command -v jq >/dev/null 2>&1; then
+    jq -n \
+      --arg event "$event" \
+      --arg content "$content" \
+      '{hookSpecificOutput: {hookEventName: $event, additionalContext: $content}}'
+  else
+    # jq-missing fallback: emit minimally-escaped JSON
+    # (lib design assumes jq present per standards/bash-hook-safety.md;
+    # this fallback exists so a jq-missing system still produces parseable output)
+    local esc_event="${event//\"/\\\"}"
+    local esc_content="${content//\"/\\\"}"
+    esc_content="${esc_content//$'\n'/\\n}"
+    printf '{"hookSpecificOutput":{"hookEventName":"%s","additionalContext":"%s"}}\n' \
+      "$esc_event" "$esc_content"
+  fi
+
+  if [ $truncated -eq 1 ]; then
+    echo "emit_additional_context: content truncated to $HOOK_INJECT_MAX_CONTENT chars (Anthropic limit)" >&2
+  fi
+
+  return 0
+}
+
+# === emit_base_pair_reminders ===
+# Emits the shared base-pair reminder text for the 5 UserPromptExpansion
+# hooks per bet 2026-07-01e. Content covers both R8 cures:
+#   1. Plain-English discipline (per .claude/rules/operator-facing-prose.md)
+#   2. Assert-verify discipline (per .claude/rules/assert-only-after-verify.md)
+#
+# Callers prepend this to their skill-specific content, then pass the
+# combined string to emit_additional_context.
+#
+# Stdout: reminder text (no envelope; caller wraps)
+# Exit: 0 always
+emit_base_pair_reminders() {
+  cat <<'EOF'
+**Plain check:** Before I make a claim in this turn, I read the source first and cite it. If I cannot cite the source, I do not ship the claim.
+
+**Base-pair reminders — plain-English + assert-verify:**
+
+Plain-English (per .claude/rules/operator-facing-prose.md):
+- Grade-10 reading level. Subject-verb-object. Short sentences.
+- Drop bassclef-internal jargon (composer, primitive, load-bearing, blast radius, tier-preset, operationalize, wirings). See standards/bassclef-internal-jargon.md for the substitution table.
+- Keep standard tech vocab: API, hook, PR, schema, ORM.
+
+Assert-verify (per .claude/rules/assert-only-after-verify.md):
+- Every operator-facing assertion carries three parts: My claim + Evidence + Why the evidence supports the claim.
+- Evidence means the source read inline (file path, ticket #, git SHA).
+- Why the evidence supports the claim means one sentence tying the source to the claim.
+- Optional sharpeners: Qualifier (Toulmin), Rebuttal (Popper), Alternatives (Peirce).
+- If you cannot fill all three, do not ship the assertion. Read the source first.
+- Toulmin's original vocabulary (claim / data / warrant) stays as the research citation in .claude/luminaries/stephen-toulmin.md.
+EOF
+  return 0
+}
+
+# === resolve_standards_path ===
+# Resolves a standards/ file via project → env → user → fail fallback.
+# Args:
+#   $1 — relative filename under standards/ (e.g., "bassclef-internal-jargon.md")
+# Stdout: resolved absolute path
+# Exit: 0 success; 1 all layers fail; 2 missing arg
+resolve_standards_path() {
+  local filename="${1:-}"
+  if [ -z "$filename" ]; then
+    echo "resolve_standards_path: missing filename arg" >&2
+    return 2
+  fi
+
+  local project_dir="${CLAUDE_PROJECT_DIR:-}"
+  local env_override="${KISS_STANDARDS_FILE:-}"
+  local home_dir
+  home_dir="$(__hook_inject_home)"
+
+  # Layer 1: project
+  if [ -n "$project_dir" ] && [ -f "$project_dir/standards/$filename" ]; then
+    echo "$project_dir/standards/$filename"
+    return 0
+  fi
+
+  # Layer 2: env override (only if env file actually exists; otherwise fall through)
+  if [ -n "$env_override" ] && [ -f "$env_override" ]; then
+    echo "$env_override"
+    return 0
+  fi
+
+  # Layer 3: user-level
+  if [ -f "$home_dir/standards/$filename" ]; then
+    echo "$home_dir/standards/$filename"
+    return 0
+  fi
+
+  # All layers failed — structured stderr with the fallback chain attempted
+  cat >&2 <<EOF
+resolve_standards_path: '$filename' not found in any fallback layer
+  Layer 1 (project): ${project_dir:-<CLAUDE_PROJECT_DIR unset>}/standards/$filename
+  Layer 2 (env KISS_STANDARDS_FILE): ${env_override:-<unset>}
+  Layer 3 (user): $home_dir/standards/$filename
+  Per standards/hook-injection-discipline.md fail-soft contract.
+EOF
+  return 1
+}
+
+# === resolve_config_path ===
+# Resolves bassclef-configs.jsonc via project → env → user → fail.
+# Stdout: resolved absolute path
+# Exit: 0 success; 1 all layers fail
+resolve_config_path() {
+  local project_dir="${CLAUDE_PROJECT_DIR:-}"
+  local env_override="${BASSCLEF_CONFIG_FILE:-}"
+  local home_dir
+  home_dir="$(__hook_inject_home)"
+
+  # Layer 1: project
+  if [ -n "$project_dir" ] && [ -f "$project_dir/.claude/bassclef-configs.jsonc" ]; then
+    echo "$project_dir/.claude/bassclef-configs.jsonc"
+    return 0
+  fi
+
+  # Layer 2: env override
+  if [ -n "$env_override" ] && [ -f "$env_override" ]; then
+    echo "$env_override"
+    return 0
+  fi
+
+  # Layer 3: user-level
+  if [ -f "$home_dir/.claude/bassclef-configs.jsonc" ]; then
+    echo "$home_dir/.claude/bassclef-configs.jsonc"
+    return 0
+  fi
+
+  cat >&2 <<EOF
+resolve_config_path: bassclef-configs.jsonc not found in any fallback layer
+  Layer 1 (project): ${project_dir:-<CLAUDE_PROJECT_DIR unset>}/.claude/bassclef-configs.jsonc
+  Layer 2 (env BASSCLEF_CONFIG_FILE): ${env_override:-<unset>}
+  Layer 3 (user): $home_dir/.claude/bassclef-configs.jsonc
+  Per standards/hook-injection-discipline.md fail-soft contract.
+EOF
+  return 1
+}
+
+# === extract_block_terms ===
+# Parses a bassclef-internal-jargon.md style file + returns BLOCK-tier terms.
+# Args:
+#   $1 — path to the jargon file
+# Stdout: one term per line (BLOCK rows only)
+# Exit: 0 success (even if zero terms found); 1 file missing; 2 missing arg
+extract_block_terms() {
+  local file="${1:-}"
+  if [ -z "$file" ]; then
+    echo "extract_block_terms: missing file arg" >&2
+    return 2
+  fi
+  if [ ! -f "$file" ]; then
+    echo "extract_block_terms: file not found: $file" >&2
+    return 1
+  fi
+
+  # Parse markdown table rows: extract column 2 (term) where column 3 (tier) == BLOCK
+  # Format: | term | TIER | replacement |
+  awk -F'|' '
+    /BLOCK *\|/ {
+      # Get tier column (3rd field after split — col 1 is leading empty)
+      tier = $3
+      gsub(/^ +| +$/, "", tier)
+      if (tier == "BLOCK") {
+        term = $2
+        gsub(/^ +| +$/, "", term)
+        # Skip header rows (term column says "term" literally)
+        if (term != "term" && term != "") print term
+      }
+    }
+  ' "$file"
+  return 0
+}

package/substrate/lib/luminary-pick.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# tier: lite
+# andon-allow: docs/operator-private/[a-z-]+/20[0-9][0-9]-[0-9]{2}
+#
+# lib/luminary-pick.sh — bassclef catalog helper for the in-turn luminary picker.
+#
+# Shape A per docs/decompositions/2026-09-03-picker-harness-llm.md.
+# Consult at docs/operator-private/consultations/2026-09-03-picker-shape.md
+# picked Shape A 5-0 (Cooper, Linus, Ousterhout, Nygard, Feathers).
+#
+# The pick itself lives in each caller SKILL body:
+#   .claude/skills/pick-luminaries/SKILL.md
+#   .claude/skills/launch/SKILL.md
+#   .claude/skills/stage/SKILL.md
+#
+# Claude reads the catalog list from luminary_pick_catalog() below,
+# reasons over the intent inside the current turn, writes the JSON.
+# No shell-out. No separate API key required.
+#
+# This lib provides:
+#   - luminary_pick_catalog() — read catalog dir; emit sorted slug list
+#   - luminary_pick() — grace-window stub preserving signature through
+#                       2026-10-31 per ADR-031 we-dont-break-adopters
+#   - luminary_pick_status() — mode report for adopter debugging
+#
+# Usage from a caller SKILL body:
+#
+#   source "${BASSCLEF_DIR:-$HOME/src/sunj-labs/bassclef}/lib/luminary-pick.sh"
+#   CATALOG=$(luminary_pick_catalog)
+#   # then Claude reasons over $CATALOG + intent, writes JSON in-turn
+#
+# Output JSON shape (produced by SKILL body prose, not by this lib):
+#   {
+#     "matched_luminaries": ["slug1", "slug2", ...],
+#     "rationale": "One short sentence per pick",
+#     "picker_version": "bassclef-harness-pick-2.0",
+#     "provider": "claude-code-harness"
+#   }
+
+set -euo pipefail
+
+# Read catalog dir and emit one line per luminary.
+# Format: "<slug> (<domain>) — <name>"
+# Sort: alphabetical by slug.
+# Return: 0 on success (including empty catalog); non-zero if dir missing.
+luminary_pick_catalog() {
+  local basedir="${BASSCLEF_DIR:-$HOME/src/sunj-labs/bassclef}"
+  local catalog_dir="${basedir}/state/luminary-implementations"
+
+  if [ ! -d "$catalog_dir" ]; then
+    echo "[luminary-pick-catalog] catalog dir missing: $catalog_dir" >&2
+    return 2
+  fi
+
+  (
+    shopt -s nullglob
+    set +e
+    for f in "$catalog_dir"/*.json; do
+      jq -r '"\(.luminary_slug) (\(.primary_domain // "unknown")) — \(.name // .luminary_slug)"' "$f" 2>/dev/null || true
+    done | sort -u
+  )
+  return 0
+}
+
+# Grace-window stub preserving the old function signature.
+# Adopter scripts that source this lib and call luminary_pick continue
+# to run. They see a stderr note pointing at the new home. Exit 0 so
+# scripts checking exit code do not error.
+# Retires 2026-10-31 per ADR-031.
+luminary_pick() {
+  echo "[luminary-pick] moved to caller SKILL body prose per web#193." >&2
+  echo "[luminary-pick] adopters: see .claude/skills/pick-luminaries/SKILL.md" >&2
+  echo "[luminary-pick] grace-window stub retires 2026-10-31 per ADR-031." >&2
+  return 0
+}
+
+# Report picker mode. Kept for adopter debugging.
+luminary_pick_status() {
+  echo "LIVE — in-turn picker per SKILL body prose (Shape A, web#193)"
+  return 0
+}
+
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  case "${1:-}" in
+    catalog) luminary_pick_catalog ;;
+    status)  luminary_pick_status ;;
+    *)
+      echo "Usage: $0 catalog    # emit luminary catalog list"
+      echo "       $0 status     # report picker mode"
+      echo ""
+      echo "The pick itself moved to caller SKILL body prose per web#193."
+      echo "See .claude/skills/pick-luminaries/SKILL.md."
+      exit 0
+      ;;
+  esac
+fi

package/substrate/lib/output-discipline.sh

@@ -0,0 +1,143 @@
+#!/bin/bash
+# tier: lite
+# output-discipline.sh — classifier library for substrate output discipline audit.
+#
+# Answers per artifact: does this substrate file dispatch /kiss words on its
+# operator-facing output? Returns one of four labels:
+#
+#   PRESENT       — body has /kiss dispatch pattern (dispatches /kiss words on output)
+#   ABSENT        — body emits operator-facing prose but no /kiss dispatch found
+#   OPT_OUT       — SKILL frontmatter declares no_operator_output: true
+#   NOT_APPLICABLE — artifact type does not emit operator-facing prose (rare;
+#                    reserved for future opt-outs at type layer)
+#
+# The classifier reads the artifact body and checks for one of these patterns:
+#   - /kiss words --grade10 (canonical form per bassclef-upstream#858)
+#   - Dispatch .*kiss words (per audit-substrate-output-discipline SKILL Test 33)
+#   - /kiss dispatch (loose form)
+#
+# Per canvas docs/canvases/2026-07-25-substrate-output-discipline.md Stage 2.
+# Ships as bet 2026-07-25a WU-A3 (bassclef-upstream#859 Iteration A).
+#
+# Usage — sourced by /audit-substrate-output-discipline skill + scripts/sweep-kiss-dispatch.sh.
+#   source lib/output-discipline.sh
+#   classify_artifact <artifact-type> <path>   # prints label to stdout; exit 0 always
+#   has_kiss_dispatch <path>                    # exit 0 if present; exit 1 if absent
+#   has_opt_out <path>                          # exit 0 if opt-out declared; exit 1 if not
+#
+# Sister modules:
+#   - lib/mechanism-fidelity.sh (bet 27c WU-3) — sister audit classifier for rule-mechanism claims
+#   - scripts/intent-drift-check.sh — used by sweep script for cosine gate per edit
+
+set -o pipefail
+
+# === has_kiss_dispatch — bool ===
+# Exit 0 if body contains a /kiss dispatch pattern; exit 1 otherwise.
+#
+# Per bassclef-upstream#1246 — the first alternative `/kiss words( --[a-z0-9]+)+`
+# recognizes both single-flag (`/kiss words --grade10`) AND two-flag
+# (`/kiss words --rewrite`, `/kiss words --grade8`, `/kiss words --rewrite --grade8`)
+# forms explicitly. The Dispatch/dispatch alternatives remain as loose
+# fallbacks for prose that mentions the dispatch verb without a bare invocation.
+# Grace window per ADR-031 — the old single-flag form keeps passing while
+# 91 skills sweep to the two-flag pointer.
+has_kiss_dispatch() {
+  local file="$1"
+  [ -f "$file" ] || return 1
+  # Match any of the four canonical /kiss dispatch patterns
+  grep -qE '/kiss words( --[a-z0-9]+)+|Dispatch .{0,30}kiss words|dispatches /kiss on|dispatch .{0,30}/kiss' "$file" 2>/dev/null
+}
+
+# === has_opt_out — bool ===
+# Exit 0 if SKILL frontmatter declares no_operator_output: true; exit 1 otherwise.
+has_opt_out() {
+  local file="$1"
+  [ -f "$file" ] || return 1
+  # Extract frontmatter (between leading --- ... ---) and check for opt-out field
+  awk '/^---$/ { c++; if(c==2) exit; next } c==1' "$file" 2>/dev/null | grep -qE '^no_operator_output:[[:space:]]*true'
+}
+
+# === classify_artifact — return label ===
+# Prints one of: PRESENT | ABSENT | OPT_OUT | NOT_APPLICABLE
+# Exit 0 always (informational; not a gate).
+classify_artifact() {
+  local artifact_type="$1"
+  local file="$2"
+
+  if [ ! -f "$file" ]; then
+    echo "NOT_APPLICABLE"
+    return 0
+  fi
+
+  # Opt-out declared in frontmatter (skills only today; extensible)
+  if has_opt_out "$file"; then
+    echo "OPT_OUT"
+    return 0
+  fi
+
+  # Check for /kiss dispatch pattern in body
+  if has_kiss_dispatch "$file"; then
+    echo "PRESENT"
+  else
+    echo "ABSENT"
+  fi
+  return 0
+}
+
+# === walk_type — enumerate all files of a given artifact type ===
+# Prints one path per line. Used by audit skill to iterate.
+# Usage: walk_type <artifact-type> [repo-root]
+walk_type() {
+  local artifact_type="$1"
+  local repo_root="${2:-$(pwd)}"
+
+  case "$artifact_type" in
+    skill|skills)
+      find "$repo_root/.claude/skills" -maxdepth 2 -name "SKILL.md" -type f 2>/dev/null | sort
+      ;;
+    rule|rules)
+      find "$repo_root/.claude/rules" -maxdepth 1 -name "*.md" -type f 2>/dev/null | sort
+      ;;
+    standard|standards)
+      find "$repo_root/standards" -maxdepth 2 -name "*.md" -type f 2>/dev/null | sort
+      ;;
+    hook|hooks)
+      find "$repo_root/.claude/hooks" -maxdepth 1 -name "*.sh" -type f 2>/dev/null | sort
+      ;;
+    luminary|luminaries)
+      find "$repo_root/.claude/luminaries" -maxdepth 1 -name "*.md" -type f 2>/dev/null | sort
+      ;;
+    adr|adrs)
+      find "$repo_root/architecture/decisions" -maxdepth 1 -name "ADR-*.md" -type f 2>/dev/null | sort
+      ;;
+    persona|personas)
+      find "$repo_root/docs/personas" -maxdepth 1 -name "*.md" -type f 2>/dev/null | sort
+      ;;
+    template|templates)
+      find "$repo_root/templates" -maxdepth 1 -name "*.md" -type f 2>/dev/null | sort
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+  return 0
+}
+
+# === slug_from_path — extract slug from a file path ===
+# Usage: slug_from_path <artifact-type> <path>
+slug_from_path() {
+  local artifact_type="$1"
+  local file="$2"
+
+  case "$artifact_type" in
+    skill|skills)
+      basename "$(dirname "$file")"
+      ;;
+    hook|hooks)
+      basename "$file" .sh
+      ;;
+    *)
+      basename "$file" .md
+      ;;
+  esac
+}

package/substrate/lib/prose-scan-boundary.sh

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+# tier: lite
+# install-class: dual
+# lib/prose-scan-boundary.sh
+#
+# Deep module per @luminary john-ousterhout — narrow interface hides
+# the boundary detection and counter file work behind 3 functions.
+#
+# Purpose — every prose scan hook (kiss, appositive, citation)
+# strips fenced or echoed content BEFORE it scans, and writes counter
+# state that plain-english-steering.sh injects into the next prompt.
+#
+# This closes #1443 canonical case — Stop side prose hooks that fire
+# on verbatim BLOCKED banner echoes at session start plus operator
+# picked shorthand labels. 5 rewrite cycles in 20 turns documented
+# the cost during 2026-09-09b prep.
+#
+# Anchor luminaries:
+#   @luminary john-ousterhout — deep module hiding the boundary work
+#   @luminary donald-norman — feedback loop through the counter markers
+#   @luminary tony-hoare — pre and postcondition on each function
+#   @luminary michael-feathers — characterization tests pin behavior
+#
+# Consumers source this lib:
+#   source lib/prose-scan-boundary.sh
+#
+# Tests: lib/tests/prose-scan-boundary.test.sh (Tier 0 strict TDD)
+
+# =========================================================================
+# strip_scan_boundaries — remove content the scan should not read
+# =========================================================================
+# Interface: IProseScanBoundary (Larman)
+# Inputs:  $1 = message text
+# Outputs: stdout — message with fenced or echoed content removed
+# Exit:    0 always
+#
+# Removes:
+#   1. BLOCKED banner blocks (session-start hook echoes; agent cannot rewrite)
+#   2. <!--SCAN_SKIP-->...<!--/SCAN_SKIP--> explicit fence markers
+#   3. Fenced code blocks (``` ... ```)
+#   4. Inline code (`...`)
+strip_scan_boundaries() {
+  local message_text="$1"
+  [ -z "$message_text" ] && return 0
+  # Python does the heavy lifting for regex-safe multiline strip.
+  # Fall back to raw text when python3 missing (fail-soft per Nygard).
+  if command -v python3 >/dev/null 2>&1; then
+    printf '%s' "$message_text" | python3 -c '
+import sys
+import re
+
+text = sys.stdin.read()
+
+# 1. Strip BLOCKED banner blocks. Banner shape:
+#    🛑🛑🛑 BLOCKED 🛑🛑🛑
+#    ────────────
+#    content
+#    ────────────
+#    ACTION: resolve OR ...
+#    Silence is not deferral. ...
+#
+# Match the banner line and content until one of:
+#   - "Silence is not deferral" line followed by newline (canonical end)
+#   - Two consecutive newlines (paragraph break)
+#   - Next banner line
+#   - End of string
+text = re.sub(
+    r"\U0001F6D1\U0001F6D1\U0001F6D1 BLOCKED \U0001F6D1\U0001F6D1\U0001F6D1"
+    r".*?"
+    r"(?:Silence is not deferral\.[^\n]*\n"
+    r"|\n\n(?=\S|\n|$)"
+    r"|(?=\U0001F6D1\U0001F6D1\U0001F6D1)"
+    r"|$)",
+    "",
+    text,
+    flags=re.DOTALL,
+)
+
+# 2. Strip explicit SCAN_SKIP fences
+text = re.sub(
+    r"<!--SCAN_SKIP-->.*?<!--/SCAN_SKIP-->",
+    "",
+    text,
+    flags=re.DOTALL,
+)
+
+# 3. Strip fenced code blocks
+text = re.sub(r"```.*?```", "", text, flags=re.DOTALL)
+
+# 4. Strip inline code
+text = re.sub(r"`[^`]+`", "", text)
+
+sys.stdout.write(text)
+'
+  else
+    # No python — return raw text so consumers still work
+    printf '%s' "$message_text"
+  fi
+  return 0
+}
+
+# =========================================================================
+# write_prose_counter — persist a per-turn counter for the steering hook
+# =========================================================================
+# Interface: IProseCounterWriter (Larman)
+# Inputs:  $1 = counter name (e.g. "kiss_hits", "appositive_hits")
+#          $2 = numeric count
+#          $3 = optional JSON payload (findings, offenders, etc.)
+# Outputs: writes state/markers/turn-prose-counters/<name>.json atomically
+# Exit:    0 always (fail-soft on write error per Nygard)
+write_prose_counter() {
+  local name="$1"
+  local count="$2"
+  local payload="${3:-{\}}"
+  [ -z "$name" ] && return 0
+  [ -z "$count" ] && count=0
+  local repo_root
+  repo_root="$(_prose_scan_repo_root)"
+  local dir="${repo_root}/state/markers/turn-prose-counters"
+  local out_file="${dir}/${name}.json"
+  mkdir -p "$dir" 2>/dev/null || return 0
+  local ts
+  ts="$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || echo "unknown")"
+  # Atomic write via tmp + mv
+  local tmp
+  tmp="$(mktemp "${dir}/.${name}.XXXXXX")" || return 0
+  cat > "$tmp" <<JSON
+{
+  "counter": "${name}",
+  "count": ${count},
+  "updated_at": "${ts}",
+  "payload": ${payload}
+}
+JSON
+  mv "$tmp" "$out_file" 2>/dev/null || rm -f "$tmp"
+  return 0
+}
+
+# =========================================================================
+# read_prose_counter — read a per-turn counter for prompt injection
+# =========================================================================
+# Interface: IProseCounterReader (Larman)
+# Inputs:  $1 = counter name
+# Outputs: stdout — JSON content, or empty when marker missing
+# Exit:    0 always (fail-soft per Nygard)
+read_prose_counter() {
+  local name="$1"
+  [ -z "$name" ] && return 0
+  local repo_root
+  repo_root="$(_prose_scan_repo_root)"
+  local marker="${repo_root}/state/markers/turn-prose-counters/${name}.json"
+  [ -f "$marker" ] || return 0
+  cat "$marker" 2>/dev/null || true
+  return 0
+}
+
+# =========================================================================
+# _prose_scan_repo_root — resolve repo root under both install classes
+# =========================================================================
+# Internal helper. Prefer $CLAUDE_PROJECT_DIR (project install), fall
+# back to lib file's parent (operator install). Per install-class: dual
+# discipline from ADR-035 substrate-as-system tenet.
+_prose_scan_repo_root() {
+  if [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}" ]; then
+    echo "${CLAUDE_PROJECT_DIR}"
+    return 0
+  fi
+  local script_dir
+  script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  cd "${script_dir}/.." && pwd
+}