@thebassclef/lite 1.0.4 → 1.1.0

package/dist/lite/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/dist/lite/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
+}

package/dist/lite/lib/rewrite-check.sh

@@ -0,0 +1,214 @@
+#!/bin/bash
+# tier: lite
+# rewrite-check.sh — six heuristic checks for /kiss REWRITE mode (goal 25d Step 5).
+#
+# Grounded in four public sources:
+#   - UK ONS Style Guide — Plain English section
+#   - Nielsen Norman Group — Plain Language for Experts (2018)
+#   - US Federal Plain Language Guidelines (plainlanguage.gov)
+#   - Hemingway Editor heuristics (public rules — passive, adverbs, long sentences)
+#
+# The six checks are HEURISTIC not perfect NLP. They surface CANDIDATES for
+# human review. Not a gate. Not a blocking check. Exit 0 always.
+#
+# Sister to lib/output-discipline.sh (classifier for /kiss dispatch presence)
+# and lib/code-comment-discipline.sh (classifier for header comment jargon).
+# Same Ousterhout deep-module shape — small interface, shared implementation.
+#
+# Per bassclef-upstream#859 Iteration D + goal 25d Step 5.
+# Bash 3.2+ compatible.
+#
+# Usage — sourced by /kiss words --rewrite mode:
+#   source lib/rewrite-check.sh
+#   check_passive_voice <file>       # prints lines with passive-voice patterns
+#   check_hyphen_words <file>        # prints hyphenated compound words flagged
+#   check_sentence_length <file> [N] # prints sentences over N words (default 25)
+#   check_svo <file>                 # prints sentences NOT starting with subject
+#   check_noun_stack <file>          # prints 3+ noun runs without verb
+#   check_adverb_density <file>      # prints density note if >5% -ly adverbs
+#   run_rewrite_checks <file>        # runs all six; prints findings table
+
+set -o pipefail
+
+# === Standard tech hyphens allow-list ===
+# Common tech compound words that should NOT be flagged as jargon.
+# Grep-alternation shape (pipe-separated).
+REWRITE_TECH_HYPHENS='pre-commit|pre-push|post-commit|post-push|real-time|data-driven|end-to-end|non-blocking|read-only|copy-on-write|test-driven|type-safe|open-source|self-hosted|cross-platform|multi-tenant|single-tenant|full-stack|front-end|back-end|no-op|no-code|low-code|check-in|check-out|log-in|log-out|sign-in|sign-out|drop-down|pop-up|pull-request|merge-request|feature-branch|main-branch|no-fast-forward|off-the-shelf|out-of-the-box'
+
+# === Passive voice check ===
+# Pattern per Hemingway Editor: "to be" + past participle + optional "by".
+# Common shapes:
+#   was <verb-ed> by
+#   were <verb-ed> by
+#   has been <verb-ed>
+#   have been <verb-ed>
+#   had been <verb-ed>
+#   is being <verb-ed>
+#   was <verb-ed>
+# Returns matching lines. Exit 0 always.
+check_passive_voice() {
+  local file="$1"
+  [ -f "$file" ] || return 0
+  grep -niE '\b(was|were|has been|have been|had been|is being|are being|will be) [a-z]+(ed|en) (by|to)\b|\b(was|were|has been|have been|had been) [a-z]+(ed|en)\b' "$file" 2>/dev/null
+  return 0
+}
+
+# === Hyphen-word check ===
+# Flag hyphenated compounds that are NOT in the standard tech allow-list.
+# Per operator-facing-prose.md — hyphen words like X-side, N-layer X, X-as-Y
+# should be rewritten to plain description.
+check_hyphen_words() {
+  local file="$1"
+  [ -f "$file" ] || return 0
+  # Extract hyphenated words (letters-letters); filter to those NOT in the allow-list
+  # AND that look like adjective compounds (letters-letters where both parts are 2+ chars).
+  grep -oE '\b[a-z]{2,}-[a-z]{2,}\b' "$file" 2>/dev/null \
+    | sort -u \
+    | grep -vwE "$REWRITE_TECH_HYPHENS" \
+    | head -20
+  return 0
+}
+
+# === Sentence length check ===
+# Flag sentences over N words (default 25 per Hemingway + Federal Plain
+# Language recommendation). Very-long sentences (>30) get the strong flag.
+check_sentence_length() {
+  local file="$1"
+  local ceiling="${2:-25}"
+  [ -f "$file" ] || return 0
+  # Split on sentence-ending punctuation, count words per sentence.
+  # awk splits, counts words, flags any over ceiling.
+  awk -v CEIL="$ceiling" '
+    BEGIN { RS = "[.!?][[:space:]]+" }
+    {
+      # Count words (whitespace-separated tokens)
+      n = split($0, words, /[[:space:]]+/)
+      if (n > CEIL) {
+        # Trim + print first 60 chars for context
+        sample = substr($0, 1, 60)
+        gsub(/\n/, " ", sample)
+        printf "SENTENCE: %d words — %s...\n", n, sample
+      }
+    }
+  ' "$file" 2>/dev/null
+  return 0
+}
+
+# === SVO check ===
+# Heuristic: flag sentences that START with a preposition or subordinating
+# conjunction rather than a subject. Common non-SVO openers:
+#   Because, Although, While, When, If, Since, Unless, Whereas, After, Before
+#   In X, On X, At X, With X, Under X, Without X, Despite X, Given X
+# This catches the most common non-SVO shapes. False positives happen on
+# legitimate variety; the check surfaces candidates for review.
+check_svo() {
+  local file="$1"
+  [ -f "$file" ] || return 0
+  # Grep for lines starting with (after optional whitespace/quote) a non-SVO opener.
+  grep -niE '^[[:space:]]*(Because|Although|While|When|If|Since|Unless|Whereas|After|Before|In [A-Z]|On [A-Z]|At [A-Z]|With [A-Z]|Under [A-Z]|Without [A-Z]|Despite|Given)\b' "$file" 2>/dev/null
+  return 0
+}
+
+# === Noun-stack check ===
+# Per operator-facing-prose.md: no more than 2 nouns in a row without a verb.
+# Heuristic: look for 3+ consecutive words that end in common noun suffixes
+# OR that are capitalized (proper nouns). Approximate.
+#
+# The heuristic flags runs of 3+ words that look like nouns (no verb-form
+# suffix like -ed, -ing, -es, -s at verb pattern). Bash regex is limited;
+# we use a simple approximation:
+#   - 3+ consecutive words each 4+ chars long
+#   - none ending in -ed, -ing, -ly, -s (verb / adverb / plural marker)
+#   - separated by single space (not by "the", "a", "an", "and", "or", "of")
+# Approximation: words separated only by spaces (no articles/verbs between).
+check_noun_stack() {
+  local file="$1"
+  [ -f "$file" ] || return 0
+  # Simple heuristic: match "word word word word" with no small connector.
+  # Look for runs of 4+ non-tiny words in a row.
+  awk '
+    {
+      # Split into words, find runs of 3+ nouny-looking tokens
+      n = split($0, w, /[[:space:]]+/)
+      run = 0
+      run_words = ""
+      for (i = 1; i <= n; i++) {
+        word = w[i]
+        # Strip punctuation for the check
+        clean = word
+        gsub(/[^A-Za-z]/, "", clean)
+        # Nouny heuristic: 4+ chars, not a verb/adverb marker, not a small word
+        if (length(clean) >= 4 \
+            && clean !~ /^(the|and|for|with|from|that|this|when|where|which|been|were|have|will|would|could|should|about|because|through|these|those)$/ \
+            && clean !~ /(ing|ed|ly)$/) {
+          run++
+          run_words = run_words " " clean
+        } else {
+          if (run >= 3) {
+            printf "NOUN-STACK: %d nouns —%s\n", run, run_words
+          }
+          run = 0
+          run_words = ""
+        }
+      }
+      if (run >= 3) {
+        printf "NOUN-STACK: %d nouns —%s\n", run, run_words
+      }
+    }
+  ' "$file" 2>/dev/null
+  return 0
+}
+
+# === Adverb density check ===
+# Per Hemingway Editor: -ly adverbs above 1 per 20 words signal weak verbs.
+# Federal Plain Language: prefer strong verbs over adverbs.
+# Threshold: >5% (equivalent to 1 per 20 words).
+check_adverb_density() {
+  local file="$1"
+  [ -f "$file" ] || return 0
+  local total_words adverb_count percent
+  # Count total words
+  total_words=$(tr -s '[:space:]' '\n' < "$file" | grep -cE '^[A-Za-z]+' 2>/dev/null || echo 0)
+  # Count -ly adverbs (word ending -ly, excluding common -ly words that aren't adverbs)
+  adverb_count=$(grep -oiE '\b[a-z]{3,}ly\b' "$file" 2>/dev/null \
+    | grep -viwE 'only|early|ally|belly|silly|fully|jolly|holy|really|apply|comply|imply|reply|supply|family|reply' \
+    | wc -l | tr -d ' ')
+  if [ "$total_words" -eq 0 ]; then
+    return 0
+  fi
+  # Compute percent (integer math * 1000 for one decimal)
+  percent=$((adverb_count * 1000 / total_words))
+  # Threshold: 50 = 5.0%
+  if [ "$percent" -gt 50 ]; then
+    printf "ADVERB density: %d/%d words = %d.%d%%\n" \
+      "$adverb_count" "$total_words" "$((percent / 10))" "$((percent % 10))"
+  fi
+  return 0
+}
+
+# === Composite check ===
+# Runs all six checks against a file. Prints a findings table.
+# Exit 0 always (informational, not a gate).
+run_rewrite_checks() {
+  local file="$1"
+  [ -f "$file" ] || return 0
+  local passive hyphens length svo nouns adverbs
+  passive=$(check_passive_voice "$file")
+  hyphens=$(check_hyphen_words "$file")
+  length=$(check_sentence_length "$file")
+  svo=$(check_svo "$file")
+  nouns=$(check_noun_stack "$file")
+  adverbs=$(check_adverb_density "$file")
+
+  echo "=== REWRITE check findings: $file ==="
+  [ -n "$passive" ] && { echo "-- passive voice --"; echo "$passive"; }
+  [ -n "$hyphens" ] && { echo "-- hyphen compounds --"; echo "$hyphens"; }
+  [ -n "$length"  ] && { echo "-- long sentences --"; echo "$length"; }
+  [ -n "$svo"     ] && { echo "-- non-SVO openers --"; echo "$svo"; }
+  [ -n "$nouns"   ] && { echo "-- noun stacks --"; echo "$nouns"; }
+  [ -n "$adverbs" ] && { echo "-- adverb density --"; echo "$adverbs"; }
+  if [ -z "$passive$hyphens$length$svo$nouns$adverbs" ]; then
+    echo "CLEAN — no rewrite findings"
+  fi
+  return 0
+}

package/dist/lite/lib/session-rescue.sh

@@ -0,0 +1,151 @@
+#!/usr/bin/env bash
+# tier: lite
+# lib/session-rescue.sh — sweep resolved session-rescue entries to completed/.
+#
+# Deep module per @luminary john-ousterhout. Single-function interface hides
+# the tracked-only check, soft cap, git-mv preference, banner emission, and
+# silent-fail behavior.
+#
+# tier: upstream
+# install-class: dual
+#
+# Interface (what callers know):
+#   sweep_resolved_rescue_entries <repo-root>
+#     — call from session-end.sh after MUST-tier checks pass
+#     — moves every docs/deferred-actions/*-session-rescue.md file to completed/
+#     — returns 0 on success (including no-op)
+#     — silent-fails on I/O errors (never crashes the caller)
+#
+# Hidden (what the module encapsulates):
+#   - Soft cap: 20 entries per call (Nygard fuse against runaway sweep)
+#   - Move mechanism per source state:
+#       tracked source   → git mv (audit trail preserved)
+#       untracked source → plain mv (rescue class is gitignored per
+#         .gitignore L40 by design; save-state.sh L214 rationale — runtime
+#         markers should not commit)
+#   - Banner: prints "swept N entries" plus one line per file
+#   - Directory creation: mkdir -p completed/ on first call
+#   - Silent-fail: any I/O failure returns 0 (never crash caller)
+#
+# Postcondition (@luminary tony-hoare):
+#   - When rc=0 AND the pre-sweep count was ≤20, zero *-session-rescue.md
+#     files remain in docs/deferred-actions/ (both tracked and untracked
+#     sources move; tracked via git mv, untracked via plain mv).
+#
+# Consumers:
+#   - .claude/hooks/session-end.sh — calls after L207 (whereami check)
+#     when NEEDS_RESCUE=0 (all MUST-tier obligations satisfied)
+#
+# Rules governed by:
+#   - .claude/rules/testing-tier-config.md (Tier 0 strict TDD; lib/*.sh)
+#   - .claude/rules/bootstrap-pair-discipline.md (write path at
+#     session-end.sh L318 pairs with this sweep path)
+#   - .claude/rules/deferred-actions.md (Pattern B — work done, mv to completed)
+#
+# Anchor luminaries:
+#   - @luminary john-ousterhout — deep module
+#   - @luminary michael-feathers — characterization lead; tests pin observed shape
+#   - @luminary tony-hoare — postcondition contract
+#   - @luminary michael-nygard — soft cap = circuit-breaker
+#   - @luminary linus-torvalds — tracked-only = reversibility
+#   - @luminary jerome-saltzer-and-michael-schroeder — fail-safe defaults
+#     (deny sweep unless positive proof of clean state; caller supplies it)
+
+# Soft cap — if more than this many rescue entries exist, warn and skip.
+# Signals that something is wrong; operator should intervene manually.
+_SESSION_RESCUE_SOFT_CAP=20
+
+# sweep_resolved_rescue_entries <repo-root>
+#
+# Moves every tracked *-session-rescue.md file from
+# <repo-root>/docs/deferred-actions/ to <repo-root>/docs/deferred-actions/completed/.
+# Emits a banner with count + per-file list.
+sweep_resolved_rescue_entries() {
+  local repo_root="${1:-}"
+  if [ -z "$repo_root" ] || [ ! -d "$repo_root" ]; then
+    return 0
+  fi
+
+  local active_dir="$repo_root/docs/deferred-actions"
+  if [ ! -d "$active_dir" ]; then
+    return 0
+  fi
+
+  # Enumerate rescue entries — nullglob-safe via find.
+  local entries
+  entries=$(find "$active_dir" -maxdepth 1 -name '*-session-rescue.md' -type f 2>/dev/null)
+  if [ -z "$entries" ]; then
+    return 0
+  fi
+
+  local count
+  count=$(printf '%s\n' "$entries" | wc -l | tr -d ' ')
+
+  # Nygard soft cap — refuse runaway sweep, print warning.
+  if [ "$count" -gt "$_SESSION_RESCUE_SOFT_CAP" ]; then
+    echo ""
+    echo "============================================"
+    echo "SESSION-RESCUE SWEEP SKIPPED (soft cap $_SESSION_RESCUE_SOFT_CAP)"
+    echo "============================================"
+    echo ""
+    echo "Found $count rescue entries in $active_dir."
+    echo "Soft cap prevents sweeping more than $_SESSION_RESCUE_SOFT_CAP at once."
+    echo "This many stale entries signal something is off — operator should"
+    echo "review and mv manually via: git mv docs/deferred-actions/*-session-rescue.md \\"
+    echo "                                    docs/deferred-actions/completed/"
+    echo "============================================"
+    echo ""
+    return 0
+  fi
+
+  # Ensure completed/ subdir exists — silent-fail on error.
+  mkdir -p "$active_dir/completed" 2>/dev/null || return 0
+
+  local moved=0
+  local moved_paths=""
+
+  # Iterate — one file per line from find output.
+  # Rescue class matches .gitignore L40 by design. Typical file is
+  # untracked. Sweep tries git mv when tracked (rare); plain mv otherwise.
+  # Destination lives in completed/ which is NOT gitignored — operator
+  # can git add later to preserve the archive in history.
+  while IFS= read -r entry; do
+    [ -z "$entry" ] && continue
+    local base
+    base=$(basename "$entry")
+    local rel_active="docs/deferred-actions/$base"
+    local rel_done="docs/deferred-actions/completed/$base"
+
+    local tracked
+    tracked=$(git -C "$repo_root" ls-files --error-unmatch "$rel_active" 2>/dev/null)
+
+    if [ -n "$tracked" ]; then
+      # Tracked source — prefer git mv for audit-trail preservation.
+      if git -C "$repo_root" mv "$rel_active" "$rel_done" 2>/dev/null; then
+        moved=$((moved + 1))
+        moved_paths="${moved_paths}  ${rel_active} → completed/ (git mv)\n"
+      fi
+    else
+      # Untracked source (gitignored per .gitignore L40) — plain mv.
+      if mv "$repo_root/$rel_active" "$repo_root/$rel_done" 2>/dev/null; then
+        moved=$((moved + 1))
+        moved_paths="${moved_paths}  ${rel_active} → completed/ (plain mv; source gitignored)\n"
+      fi
+    fi
+  done <<< "$entries"
+
+  # Norman feedback — banner names count + each moved file.
+  if [ "$moved" -gt 0 ]; then
+    echo ""
+    echo "============================================"
+    echo "SESSION-RESCUE SWEEP"
+    echo "============================================"
+    echo ""
+    echo "Moved $moved resolved session-rescue entries to completed/:"
+    printf "$moved_paths"
+    echo "============================================"
+    echo ""
+  fi
+
+  return 0
+}