@thebassclef/lite 1.1.1 → 1.2.0

package/dist/lite/lib/fresh-install-check.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# tier: lite
+#
+# fresh-install-check.sh — is this a fresh-install repo or an established one?
+# Cures sunj-labs/bassclef-cli#102 + sunj-labs/bassclef-cli#108 where two
+# session-start fragments (55-orientation-gate + 10-abrupt-stop-recovery)
+# false-fire on the first session after `bassclef init` in an empty repo.
+#
+# A repo is fresh-install when BOTH conditions hold:
+#   1. No git commits (git rev-parse HEAD fails), AND
+#   2. No session lock at .claude/SESSION_LOCK
+#
+# The composite catches the cli#108 case (init leaves 379 untracked files
+# but no commits, and no prior session) while preserving the genuine-stop
+# case (a real session stops abruptly and leaves a lock — that lock alone
+# fires the check even before any commit).
+#
+# Contract: exit 0 = fresh, exit 1 = established (or defensive fallback).
+# Silent — no stderr output on any path. Never crashes the parent.
+#
+# Anchor luminaries:
+#   @luminary john-ousterhout — deep module (composite predicate hidden
+#                                behind zero-arg function)
+#   @luminary tony-hoare      — postcondition (exit code contract)
+#   @luminary michael-nygard  — fail-soft (missing git = defensive-1;
+#                                assume not fresh; skip false-silence)
+
+# @pattern patterns/code/gof/strategy.md
+# Composite strategy — two discriminators combined via short-circuit AND.
+is_fresh_install() {
+  # Defensive: if git is not on PATH, assume not-fresh — better a false
+  # BLOCKED banner an operator can dismiss than a silent-skip that hides
+  # a real state.
+  command -v git >/dev/null 2>&1 || return 1
+
+  # Discriminator 1: git HEAD does not resolve → no commits
+  if git rev-parse HEAD >/dev/null 2>&1; then
+    return 1
+  fi
+
+  # Discriminator 2: session lock present → interrupted session
+  if [ -f ".claude/SESSION_LOCK" ]; then
+    return 1
+  fi
+
+  return 0
+}
+
+export -f is_fresh_install 2>/dev/null || true

package/dist/lite/lib/hook-heartbeat.sh

@@ -6,7 +6,6 @@
 # hides the marker path convention, atomic write pattern, format
 # schema, directory creation, and silent-fail behavior.
 #
-# tier: upstream
 # install-class: dual
 #
 # Interface (what callers know):

package/dist/lite/lib/mechanism-fidelity.sh

@@ -0,0 +1,569 @@
+#!/usr/bin/env bash
+# tier: lite
+# install-class: dual
+# lib/mechanism-fidelity.sh — shared scanner for the mechanism-fidelity
+# audit per standards/mechanism-fidelity.md.
+#
+# This library is SOURCED by the audit skill (.claude/skills/audit-rule-
+# mechanism-fidelity/SKILL.md — lands in WU-4) AND by the cold-adopter
+# harness check classes (scripts/cold-adopter-harness-sync.sh extension —
+# lands in WU-5). Single source of truth per @luminary john-ousterhout
+# (deep modules).
+#
+# Authority: ADR-035 (substrate-as-system tenet)
+# Tier 0 strict TDD: lib/tests/mechanism-fidelity.test.sh
+# Anchors: @luminary michael-feathers (legacy code = code without tests),
+#          @luminary kent-beck (TDD), @luminary tony-hoare (pre/post).
+#
+# Exposed functions:
+#   scan_rule_for_mechanism_claims <rule-path>       # extracts mechanism refs
+#   verify_hook_exists <hook-path>                   # step 1 of verification chain
+#   verify_hook_wired <hook-name>                    # step 2 (settings.json wiring)
+#   verify_path_resolution <hook-path>               # step 4 (Class A check)
+#   verify_hook_test_pins_contract <hook-or-lib>     # step 3 (Tier 0 test present)
+#   classify_hook_install_pattern <hook-name> [root] # detects ci|launchd|lib|standard
+#   classify_finding [--flags]                       # returns 1 of 10 labels
+#
+# Env vars consumed:
+#   CLAUDE_PROJECT_DIR           — project root
+#   HOME_OVERRIDE                — test-only $HOME replacement
+#   USER_SETTINGS_OVERRIDE       — test-only user settings.json replacement
+#   CANONICAL_MANIFEST_OVERRIDE  — test-only canonical wiring manifest path override
+#                                  (per bet 2026-08-05c: verify_hook_wired reads
+#                                   standards/bassclef-wiring-manifest.json as an
+#                                   added source of hook wiring; shipped 2026-08-04h)
+
+# === Resolve $HOME with test-override support ===
+__mech_fidelity_home() {
+  echo "${HOME_OVERRIDE:-$HOME}"
+}
+
+# === Resolve user settings.json with test-override support ===
+__mech_fidelity_user_settings() {
+  if [ -n "${USER_SETTINGS_OVERRIDE:-}" ]; then
+    echo "$USER_SETTINGS_OVERRIDE"
+  else
+    echo "$(__mech_fidelity_home)/.claude/settings.json"
+  fi
+}
+
+# === Resolve canonical wiring manifest path with test-override support ===
+# Per bet 2026-08-05c: verify_hook_wired reads this file as an added source
+# of hook wiring alongside project + user settings.json. The manifest shipped
+# 2026-08-04h per design/discoveries/2026-08-04-managed-settings-d-as-bassclef-wiring-channel.md.
+__mech_fidelity_canonical_manifest() {
+  if [ -n "${CANONICAL_MANIFEST_OVERRIDE:-}" ]; then
+    echo "$CANONICAL_MANIFEST_OVERRIDE"
+  else
+    echo "${CLAUDE_PROJECT_DIR:-}/standards/bassclef-wiring-manifest.json"
+  fi
+}
+
+# === _is_placeholder_hook_name ===
+# Match candidate hook names against conventional example / placeholder
+# names that rule bodies use as illustrations. Real hook names are
+# descriptive (verb-object shape). Bare placeholders leak as UNWIRED
+# audit noise per sunj-labs/bassclef-upstream#1164.
+#
+# Kept STRICT (exact bare names only) to avoid false negatives on real
+# hooks that happen to prefix/suffix with a placeholder root (e.g.,
+# foo-hook.sh, install-test.sh). Add new entries as new noise leaks
+# into future audits.
+#
+# Returns 0 (true) when candidate is a bare placeholder name.
+_is_placeholder_hook_name() {
+  local name="${1:-}"
+  case "$name" in
+    foo.sh|bar.sh|baz.sh|test.sh) return 0 ;;
+    example.sh|template.sh|sample.sh) return 0 ;;
+    whatever.sh|myhook.sh) return 0 ;;
+  esac
+  return 1
+}
+
+# === scan_rule_for_mechanism_claims ===
+# Greps a rule body for mechanism claims (hook references, event names,
+# matchers). Returns one claim per line (compact form: hook-name + optional
+# event/matcher hint).
+#
+# Args: $1 — rule file path
+# Stdout: claims, one per line (empty if no claims)
+# Exit: 0 success (even if zero claims); 1 file missing; 2 missing arg
+scan_rule_for_mechanism_claims() {
+  local rule="${1:-}"
+  local project_root="${2:-${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}}"
+  if [ -z "$rule" ]; then
+    echo "scan_rule_for_mechanism_claims: missing rule arg" >&2
+    return 2
+  fi
+  if [ ! -f "$rule" ]; then
+    echo "scan_rule_for_mechanism_claims: file not found: $rule" >&2
+    return 1
+  fi
+
+  # Pattern 1: "<name>-hook.sh" or "<name>.sh" anywhere in body (most direct)
+  # Pattern 2: "Mechanical enforcement" section header (formal claim)
+  # Pattern 3: "fires at PreToolUse|PostToolUse|Stop|SessionStart|UserPromptSubmit"
+
+  # Extract candidate .sh references
+  # Regex accepts capital letters at match start + inside the name (bassclef-upstream#1423).
+  # Prior lowercase-only pattern silently dropped leading capital letters — e.g.,
+  # `Bassclef-sync.sh` at sentence start extracted as phantom `assclef-sync.sh`.
+  # Normalize to lowercase before dedup so the file lookup below finds the real file.
+  local candidates
+  candidates=$(grep -oE '[A-Za-z0-9][a-zA-Z0-9-]*-?[a-zA-Z0-9]*\.sh' "$rule" 2>/dev/null \
+    | tr '[:upper:]' '[:lower:]' \
+    | sort -u)
+  [ -z "$candidates" ] && return 0
+
+  # Filter to reduce false positives (bet 28a WU-4):
+  #   - Emit candidate IF .sh exists in .claude/hooks/ (true positive — real hook)
+  #   - Skip candidate IF .sh exists elsewhere in repo (lib/script/test/fixture; not a hook claim)
+  #   - Emit candidate IF .sh does not exist anywhere AND has hook-context proximity
+  #     ("hook", "fires at", "wired", "enforced by", "mechanism", "matcher") within ±2 lines
+  while IFS= read -r candidate; do
+    [ -z "$candidate" ] && continue
+    # True positive: real hook file
+    if [ -f "$project_root/.claude/hooks/$candidate" ]; then
+      echo "$candidate"
+      continue
+    fi
+    # Check if file exists elsewhere in repo (excluding .git/)
+    local found_elsewhere=0
+    if [ -d "$project_root" ]; then
+      if find "$project_root" -name .git -prune -o -type f -name "$candidate" -print 2>/dev/null | grep -q .; then
+        found_elsewhere=1
+      fi
+    fi
+    if [ "$found_elsewhere" -eq 1 ]; then
+      # File exists but not in .claude/hooks/ — not a hook claim, skip
+      continue
+    fi
+    # (bassclef-upstream#1164) Placeholder-name filter — skip conventional
+    # example filenames (foo.sh, test.sh, template.sh, bar.sh, etc.) that
+    # rule bodies use as illustrations. Real hook names are descriptive;
+    # placeholders leak as UNWIRED audit noise.
+    if _is_placeholder_hook_name "$candidate"; then
+      continue
+    fi
+    # File doesn't exist anywhere. Check negative-context patterns first
+    # (sibling/example/renamed/library references; bet 28a WU-6 + bet 2026-08-05c WU-4).
+    # Skip when candidate appears within ±2 lines of:
+    #   "sibling of"  "alias of"  "renamed from/to"  "former name"
+    #   "Example for/of"  "e.g.,"  "such as"
+    #   "sourced by"  "library"  "CI hook"  "GitHub Actions"  "workflow"
+    #   "launchd"  "cron"  "scheduled job"
+    # Deferred-future patterns (bet 2026-08-05c WU-4 CI cure) — rules that
+    # cite hooks planned for later ship are not active claims:
+    #   "deferred (follow-on|to|until)"
+    #   "will (add|ship|introduce|land)"
+    #   "planned (hook|for|to)"
+    #   "not yet"
+    # Dropped "V[0-9]+ (mechanical|...)" — too broad; matches "V2 mechanical
+    # layer" heading even when adjacent to an unrelated active claim.
+    local nearby
+    nearby=$(grep -B2 -A2 -F "$candidate" "$rule" 2>/dev/null)
+    if echo "$nearby" | grep -qiE "(sibling of|alias of|renamed (from|to)|former name|Example (for|of)|e\.g\.,|such as|sourced by|library|CI hook|GitHub Actions|workflow|launchd|cron|scheduled job|deferred (follow-on|to|until)|will (add|ship|introduce|land)|planned (hook|for|to)|not yet)"; then
+      continue
+    fi
+    # Check hook-context proximity (within ±2 lines).
+    if echo "$nearby" | grep -qiE "(hook|fires at|wired|enforced by|mechanism|matcher)"; then
+      echo "$candidate"
+    fi
+  done <<< "$candidates"
+  return 0
+}
+
+# === verify_hook_exists ===
+# Step 1 of the 5-step verification chain.
+# Args: $1 — hook file path (absolute or relative to repo)
+# Exit: 0 file exists; 1 file missing; 2 missing arg
+verify_hook_exists() {
+  local hook="${1:-}"
+  if [ -z "$hook" ]; then
+    echo "verify_hook_exists: missing arg" >&2
+    return 2
+  fi
+  if [ -f "$hook" ]; then
+    return 0
+  fi
+  echo "verify_hook_exists: not found: $hook" >&2
+  return 1
+}
+
+# === verify_hook_wired ===
+# Step 2 of the 5-step chain. Greps project settings, user settings, AND
+# the canonical wiring manifest for the hook name appearing in any command
+# path. Returns 0 on FIRST match (short-circuits per R1 pre-mortem).
+# Args: $1 — hook base name (e.g., "wired-hook.sh")
+# Exit: 0 wired in at least one source; 1 wired nowhere; 2 missing arg
+# Sources checked (in order): project settings.json, user settings.json,
+#                             bassclef-wiring-manifest.json
+# Per bet 2026-08-05c: added the canonical manifest source. Prior versions
+# missed hooks wired only in the manifest → classified them DEAD-LETTER.
+verify_hook_wired() {
+  local hook_name="${1:-}"
+  if [ -z "$hook_name" ]; then
+    echo "verify_hook_wired: missing arg" >&2
+    return 2
+  fi
+
+  local project_settings="${CLAUDE_PROJECT_DIR:-}/.claude/settings.json"
+  local user_settings
+  user_settings="$(__mech_fidelity_user_settings)"
+  local canonical_manifest
+  canonical_manifest="$(__mech_fidelity_canonical_manifest)"
+
+  if [ -f "$project_settings" ] && grep -qF "$hook_name" "$project_settings" 2>/dev/null; then
+    return 0
+  fi
+  if [ -f "$user_settings" ] && grep -qF "$hook_name" "$user_settings" 2>/dev/null; then
+    return 0
+  fi
+  if [ -f "$canonical_manifest" ] && grep -qF "$hook_name" "$canonical_manifest" 2>/dev/null; then
+    return 0
+  fi
+
+  echo "verify_hook_wired: '$hook_name' not in project settings, user settings, or canonical manifest" >&2
+  return 1
+}
+
+# === verify_path_resolution ===
+# Step 4 of the 5-step chain. Checks for Class A pattern: hook uses
+# SCRIPT_DIR/../../ to reach project resources but is declared install-class
+# operator (mismatch). Reads the install-class header.
+# Args: $1 — hook file path
+# Exit: 0 safe; 1 unsafe (Class A) or no install-class declared with risky pattern
+verify_path_resolution() {
+  local hook="${1:-}"
+  if [ -z "$hook" ] || [ ! -f "$hook" ]; then
+    echo "verify_path_resolution: hook missing: $hook" >&2
+    return 2
+  fi
+
+  # Check if hook uses SCRIPT_DIR/../../ pattern (the Class A risk pattern)
+  local uses_risky_pattern=0
+  if grep -qE 'SCRIPT_DIR.*\.\./\.\.' "$hook"; then
+    uses_risky_pattern=1
+  fi
+
+  # No risky pattern → safe regardless of install-class
+  if [ $uses_risky_pattern -eq 0 ]; then
+    return 0
+  fi
+
+  # Risky pattern present — install-class header decides
+  local install_class
+  install_class=$(grep -m1 '^# install-class:' "$hook" | sed 's/^# install-class:[[:space:]]*//' | tr -d '[:space:]')
+
+  case "$install_class" in
+    dual)
+      # Author declared lib/hook-inject.sh resolve-helpers handle both layouts
+      return 0
+      ;;
+    project)
+      # Project-class wiring + project-relative reads = safe
+      return 0
+      ;;
+    operator)
+      # Class A failure — operator-class wiring + project-relative reads
+      echo "verify_path_resolution: Class A failure — '$hook' uses SCRIPT_DIR/../../ but declares install-class: operator" >&2
+      echo "  Under \$HOME wiring, SCRIPT_DIR/../../<resource> resolves to nonexistent path" >&2
+      echo "  Fix: declare install-class: dual + use lib/hook-inject.sh resolve-helpers" >&2
+      return 1
+      ;;
+    "")
+      # No header — defaults to project; but risky pattern with no declaration warns
+      echo "verify_path_resolution: '$hook' uses SCRIPT_DIR/../../ with no install-class header" >&2
+      echo "  Default is 'project' but the declaration should be explicit per standards/hook-install-class.md" >&2
+      return 1
+      ;;
+    *)
+      echo "verify_path_resolution: '$hook' declares unknown install-class: '$install_class'" >&2
+      return 1
+      ;;
+  esac
+}
+
+# === verify_hook_test_pins_contract ===
+# Step 3 of the 5-step chain. Checks for sibling Tier 0 test file.
+# Convention: <dir>/<name>.sh has test at <dir>/tests/<name>.test.sh
+# Args: $1 — hook or lib path
+# Exit: 0 sibling test exists; 1 no sibling test; 2 missing arg
+verify_hook_test_pins_contract() {
+  local source="${1:-}"
+  if [ -z "$source" ]; then
+    echo "verify_hook_test_pins_contract: missing arg" >&2
+    return 2
+  fi
+
+  local dir base
+  dir="$(dirname "$source")"
+  base="$(basename "$source" .sh)"
+
+  if [ -f "$dir/tests/$base.test.sh" ]; then
+    return 0
+  fi
+
+  echo "verify_hook_test_pins_contract: no test at $dir/tests/$base.test.sh" >&2
+  return 1
+}
+
+# === classify_hook_install_pattern ===
+# Determines how a hook is meant to be installed. Some hooks live in
+# .github/workflows/*.yml (CI hooks), some are scheduled by launchd, some
+# are sourced as libraries by other hooks — none of these belong in
+# .claude/settings.json. The audit needs this signal so it does not flag
+# them as DEAD-LETTER when they correctly do not appear in settings.json.
+#
+# Detection priority:
+#   1. CI — hook name appears in any .github/workflows/*.yml
+#   2. launchd — first 10 lines of the hook header mention launchd / cron / scheduled
+#   3. lib — first 10 lines mention "sourced by" (library used by other hooks)
+#   4. standard — default; hook is meant to live in settings.json
+#
+# CI takes precedence over launchd: a hook can be both scheduled locally
+# AND fire in CI; the CI presence is the dominant signal because the
+# workflow IS the wiring.
+#
+# Args: $1 — hook base name (e.g., "pr-scrub.sh")
+#       $2 — project root (default: $CLAUDE_PROJECT_DIR or lib parent dir)
+# Stdout: one of "ci", "launchd", "lib", "standard"
+# Exit: 0 always (default "standard" is safe); 2 missing arg
+classify_hook_install_pattern() {
+  local hook_name="${1:-}"
+  local project_root="${2:-${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}}"
+
+  if [ -z "$hook_name" ]; then
+    echo "classify_hook_install_pattern: missing arg" >&2
+    return 2
+  fi
+
+  # Layer 2 — read pattern list from standards/hook-invocation-patterns.json
+  # when available (sunj-labs/bassclef-upstream#1163). Falls back to
+  # hardcoded case cascade if JSON missing OR jq unavailable — keeps
+  # existing tests passing per @luminary michael-feathers characterization.
+  local patterns_json="$project_root/standards/hook-invocation-patterns.json"
+  if [ -f "$patterns_json" ] && command -v jq >/dev/null 2>&1; then
+    local result
+    result=$(_classify_via_patterns_json "$hook_name" "$project_root" "$patterns_json") || result=""
+    if [ -n "$result" ]; then
+      echo "$result"
+      return 0
+    fi
+  fi
+
+  # Fallback — hardcoded cascade (identical to pre-Layer-2 behavior)
+  # 1. CI — workflow reference wins
+  if [ -d "$project_root/.github/workflows" ]; then
+    if grep -qrlF "$hook_name" "$project_root/.github/workflows/" 2>/dev/null; then
+      echo "ci"
+      return 0
+    fi
+  fi
+
+  # 1.5 Release
+  local release_script="$project_root/scripts/release-to-bassclef.sh"
+  if [ -f "$release_script" ]; then
+    if grep -qF "$hook_name" "$release_script" 2>/dev/null; then
+      echo "release"
+      return 0
+    fi
+  fi
+
+  # 2/3 — header inspection
+  local hook_path="$project_root/.claude/hooks/$hook_name"
+  if [ -f "$hook_path" ]; then
+    local header
+    header=$(head -10 "$hook_path" 2>/dev/null)
+    if echo "$header" | grep -qiE "(launchd|launch agent|scheduled job|via cron|cron job)"; then
+      echo "launchd"
+      return 0
+    fi
+    if echo "$header" | grep -qiE "(sourced by|sourced into|sourced from)"; then
+      echo "lib"
+      return 0
+    fi
+  fi
+
+  # 4 — default
+  echo "standard"
+  return 0
+}
+
+# === _classify_via_patterns_json (private helper for Layer 2) ===
+# Reads standards/hook-invocation-patterns.json + iterates entries
+# in precedence order. First match wins. Returns pattern name on
+# stdout OR empty string when nothing matches (fallback to hardcoded).
+#
+# Args: $1 hook_name, $2 project_root, $3 patterns_json_path
+_classify_via_patterns_json() {
+  local hook_name="$1"
+  local project_root="$2"
+  local patterns_json="$3"
+
+  # Extract patterns sorted by precedence ASC — each line is TSV:
+  # name<TAB>detect.kind<TAB>detect.arg
+  local pattern_rows
+  pattern_rows=$(jq -r '.patterns | sort_by(.precedence)[] | [.name, .detect.kind, (.detect.arg // "")] | @tsv' "$patterns_json" 2>/dev/null) || return 1
+  [ -z "$pattern_rows" ] && return 1
+
+  local IFS=$'\n'
+  local row
+  for row in $pattern_rows; do
+    local name kind arg
+    name=$(echo "$row" | cut -f1)
+    kind=$(echo "$row" | cut -f2)
+    arg=$(echo "$row" | cut -f3)
+
+    case "$kind" in
+      workflow_grep)
+        if [ -d "$project_root/$arg" ]; then
+          if grep -qrlF "$hook_name" "$project_root/$arg/" 2>/dev/null; then
+            echo "$name"
+            return 0
+          fi
+        fi
+        ;;
+      script_grep)
+        if [ -f "$project_root/$arg" ]; then
+          if grep -qF "$hook_name" "$project_root/$arg" 2>/dev/null; then
+            echo "$name"
+            return 0
+          fi
+        fi
+        ;;
+      header_regex)
+        local hook_path="$project_root/.claude/hooks/$hook_name"
+        if [ -f "$hook_path" ]; then
+          local header
+          header=$(head -10 "$hook_path" 2>/dev/null)
+          if echo "$header" | grep -qiE "$arg"; then
+            echo "$name"
+            return 0
+          fi
+        fi
+        ;;
+      default)
+        echo "$name"
+        return 0
+        ;;
+    esac
+  done
+
+  # No match — signal fallback
+  return 1
+}
+
+# === _install_pattern_is_valid (private helper for Layer 2) ===
+# Returns 0 if pattern is in the JSON pattern list OR in the hardcoded
+# fallback list (ci|launchd|lib|release|standard). Returns 1 otherwise.
+_install_pattern_is_valid() {
+  local candidate="${1:-}"
+  [ -z "$candidate" ] && return 1
+
+  # Try JSON first
+  local project_root="${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+  local patterns_json="$project_root/standards/hook-invocation-patterns.json"
+  if [ -f "$patterns_json" ] && command -v jq >/dev/null 2>&1; then
+    local names
+    names=$(jq -r '.patterns[].name' "$patterns_json" 2>/dev/null) || names=""
+    if [ -n "$names" ]; then
+      local n
+      while IFS= read -r n; do
+        [ "$n" = "$candidate" ] && return 0
+      done <<< "$names"
+      return 1
+    fi
+  fi
+
+  # Fallback — hardcoded list
+  case "$candidate" in
+    ci|launchd|lib|release|standard) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# === classify_finding ===
+# Returns 1 of 10 classification labels per standards/mechanism-fidelity.md.
+# Flags (exit codes from each verification step):
+#   --exists=N         step 1: verify_hook_exists exit code (0 OK, 1 missing)
+#   --wired=N          step 2: verify_hook_wired exit code (0 OK, 1 unwired)
+#   --path-ok=N        step 4: verify_path_resolution exit code (0 OK, 1 broken)
+#   --test=N           step 3: verify_hook_test_pins_contract exit code (0 OK, 1 missing)
+#   --install-pattern=V install pattern (ci|launchd|lib|standard) — bet 29a WU-1
+#                      Overrides DEAD-LETTER → NOT-WIRED-BY-DESIGN-{CI|LAUNCHD|LIB}
+#                      when the hook correctly lives outside settings.json
+#   --methodology-only short-circuit when the rule names no mechanism
+#
+# Stdout: one of CLEAN / DEAD-LETTER / UNWIRED / PATH-BROKEN / TEST-MISSING /
+#         METHODOLOGY-ONLY / SILENT-PASS / NOT-WIRED-BY-DESIGN-CI /
+#         NOT-WIRED-BY-DESIGN-LAUNCHD / NOT-WIRED-BY-DESIGN-LIB
+# Exit: 0 success; 2 no args OR unknown --install-pattern value
+classify_finding() {
+  if [ $# -eq 0 ]; then
+    echo "classify_finding: no args" >&2
+    return 2
+  fi
+
+  local exists wired path_ok test_present methodology_only=0 install_pattern="standard"
+  for arg in "$@"; do
+    case "$arg" in
+      --exists=*) exists="${arg#*=}" ;;
+      --wired=*) wired="${arg#*=}" ;;
+      --path-ok=*) path_ok="${arg#*=}" ;;
+      --test=*) test_present="${arg#*=}" ;;
+      --install-pattern=*)
+        install_pattern="${arg#*=}"
+        # Layer 2 (bassclef-upstream#1163) — validate against JSON
+        # pattern list when available; fall back to hardcoded enum.
+        if ! _install_pattern_is_valid "$install_pattern"; then
+          echo "classify_finding: unknown install-pattern value: $install_pattern" >&2
+          return 2
+        fi
+        ;;
+      --methodology-only) methodology_only=1 ;;
+      *) echo "classify_finding: unknown arg: $arg" >&2; return 2 ;;
+    esac
+  done
+
+  # Short-circuit on methodology-only
+  if [ "$methodology_only" -eq 1 ]; then
+    echo "METHODOLOGY-ONLY"
+    return 0
+  fi
+
+  # Classification cascade
+  if [ "$exists" = "1" ]; then
+    echo "UNWIRED"
+    return 0
+  fi
+  if [ "$wired" = "1" ]; then
+    # Hook lives on disk but settings.json wiring absent.
+    # If the hook is meant to live elsewhere (CI / launchd / sourced lib),
+    # this is by design, not a failure.
+    # Layer 2 (bassclef-upstream#1163) — algorithmic label derivation:
+    # "standard" → DEAD-LETTER; anything else → NOT-WIRED-BY-DESIGN-<UPPER>.
+    # New patterns land in standards/hook-invocation-patterns.json; their
+    # classification label flows through this branch without cascade edits.
+    if [ "$install_pattern" = "standard" ]; then
+      echo "DEAD-LETTER"
+      return 0
+    fi
+    local upper
+    upper=$(echo "$install_pattern" | tr '[:lower:]' '[:upper:]')
+    echo "NOT-WIRED-BY-DESIGN-${upper}"
+    return 0
+  fi
+  if [ "$path_ok" = "1" ]; then
+    echo "PATH-BROKEN"
+    return 0
+  fi
+  if [ "$test_present" = "1" ]; then
+    echo "TEST-MISSING"
+    return 0
+  fi
+
+  echo "CLEAN"
+  return 0
+}