@thebassclef/lite 1.0.4 → 1.1.0

package/dist/lite/scripts/intent-drift-check.sh

@@ -0,0 +1,456 @@
+#!/usr/bin/env bash
+# tier: lite
+# intent-drift-check.sh — measure intent drift after an artifact body rewrite.
+#
+# Reads a saved embedding from .claude/embeddings/<type>/<slug>.json where
+# <type> is one of skills/rules/standards/hooks. Re-embeds the current source
+# body via Voyage. Computes cosine similarity. Compares against a threshold.
+# Reports PASS/FAIL.
+#
+# The threshold varies per change class. The class captures author intent —
+# preserve, simplify, extend, restructure, or material. Different classes
+# expect different natural cosine drops per Mikolov 2013 embedding-space
+# behavior. See bet 24a Path 1 fold-in for the threshold table.
+#
+# Closes bassclef-upstream#783 — makes /loop step 5 (INTENT CHECK) measurable
+# rather than subjective. Per Feathers characterization + Beck TDD rhythm.
+# Bet 24a Path 1 extends coverage from skills to rules + standards + hooks
+# with change-class-aware thresholds.
+#
+# Usage:
+#   scripts/intent-drift-check.sh --skill <slug> [--change-class <c>] [--threshold <f>] [--json]
+#   scripts/intent-drift-check.sh --rule <slug> [--change-class <c>] [--threshold <f>] [--json]
+#   scripts/intent-drift-check.sh --standard <slug> [--change-class <c>] [--threshold <f>] [--json]
+#   scripts/intent-drift-check.sh --hook <slug> [--change-class <c>] [--threshold <f>] [--json]
+#   scripts/intent-drift-check.sh --luminary <slug> [--change-class <c>] [--threshold <f>] [--json]
+#   scripts/intent-drift-check.sh --adr <slug> [--change-class <c>] [--threshold <f>] [--json]
+#   scripts/intent-drift-check.sh --persona <slug> [--change-class <c>] [--threshold <f>] [--json]
+#   scripts/intent-drift-check.sh --template <slug> [--change-class <c>] [--threshold <f>] [--json]
+#   scripts/intent-drift-check.sh --help
+#
+# Change classes (drives default threshold):
+#   preserve     — typo, style, formatting; threshold 0.95
+#   simplify     — /kiss rewrite, grade lift; threshold 0.90 (default)
+#   extend       — new subsection, added content; threshold 0.70
+#   restructure  — reorder, section merge; threshold 0.65
+#   material     — rescope, breaking change; no threshold (always PASS-LOGGED)
+#
+# Exits:
+#   0 — cosine at or above threshold (intent preserved) OR material class
+#   1 — cosine below threshold (intent drift detected; rewrite failed)
+#   2 — precondition failure (missing artifact, missing vector, missing keys,
+#                            or mutually exclusive artifact flags supplied)
+#
+# Env:
+#   VOYAGE_API_KEY — required for live mode
+#   ANTHROPIC_API_KEY — checked via intent-matcher.sh (required for live mode)
+#   INTENT_DRIFT_STUB=1 — skip Voyage call; return cosine 1.0 (for tests)
+#
+# Per @luminary michael-feathers + @luminary kent-beck + @luminary tomas-mikolov + ADR-042
+
+set -o pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  intent-drift-check.sh --skill <slug>    [--change-class <c>] [--threshold <f>] [--json]
+  intent-drift-check.sh --rule <slug>     [--change-class <c>] [--threshold <f>] [--json]
+  intent-drift-check.sh --standard <slug> [--change-class <c>] [--threshold <f>] [--json]
+  intent-drift-check.sh --hook <slug>     [--change-class <c>] [--threshold <f>] [--json]
+  intent-drift-check.sh --luminary <slug> [--change-class <c>] [--threshold <f>] [--json]
+  intent-drift-check.sh --adr <slug>      [--change-class <c>] [--threshold <f>] [--json]
+  intent-drift-check.sh --persona <slug>  [--change-class <c>] [--threshold <f>] [--json]
+  intent-drift-check.sh --template <slug> [--change-class <c>] [--threshold <f>] [--json]
+
+Only one artifact flag at a time. Combining them fails with exit 2.
+
+Measures intent drift after an artifact body rewrite. Reads saved vector from
+.claude/embeddings/<type>/<slug>.json, re-embeds the current source body, and
+computes cosine similarity against a change-class-aware threshold.
+
+Change classes (drives default threshold when --threshold is omitted):
+  preserve     Threshold 0.95  Typo/style/formatting; meaning identical
+  simplify     Threshold 0.90  Grade lift, /kiss rewrite; meaning held (default)
+  extend       Threshold 0.70  New subsection/content added
+  restructure  Threshold 0.65  Reorder/merge; same meaning, new shape
+  material     Log only        Rescope/breaking; always PASS-LOGGED
+
+Options:
+  --skill <slug>        Skill slug (e.g., state-a-problem)
+  --rule <slug>         Rule slug (e.g., loop-discipline)
+  --standard <slug>     Standard slug (e.g., loop-discipline)
+  --hook <slug>         Hook slug without .sh extension (e.g., pre-commit-gate)
+  --luminary <slug>     Luminary slug (e.g., alan-cooper); source at .claude/luminaries/<slug>.md
+  --adr <slug>          ADR slug (e.g., ADR-044-unified-skill-body-template); source at architecture/decisions/<slug>.md
+  --persona <slug>      Persona slug (e.g., sam); source at docs/personas/<slug>.md
+  --template <slug>     Template slug (e.g., chronicle-template); source at templates/<slug>.md
+  --change-class <c>    One of: preserve, simplify, extend, restructure, material
+  --threshold <f>       Override the class-derived threshold
+  --json                Emit JSON output with cosine + verdict + change_class fields
+  --help                Show this usage
+
+Exit codes:
+  0  cosine >= threshold (intent preserved) OR material class
+  1  cosine <  threshold (intent drift detected)
+  2  precondition failure (missing artifact, missing vector, mutually exclusive flags)
+
+Examples:
+  scripts/intent-drift-check.sh --skill state-a-problem
+  scripts/intent-drift-check.sh --rule loop-discipline --change-class extend
+  scripts/intent-drift-check.sh --standard loop-discipline --change-class extend --json
+EOF
+}
+
+# === Arg parse ===
+SKILL=""
+RULE=""
+STANDARD=""
+HOOK=""
+LUMINARY=""
+ADR=""
+PERSONA=""
+TEMPLATE=""
+CHANGE_CLASS=""
+THRESHOLD=""
+JSON_OUT=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --skill)        SKILL="$2"; shift 2 ;;
+    --rule)         RULE="$2"; shift 2 ;;
+    --standard)     STANDARD="$2"; shift 2 ;;
+    --hook)         HOOK="$2"; shift 2 ;;
+    --luminary)     LUMINARY="$2"; shift 2 ;;
+    --adr)          ADR="$2"; shift 2 ;;
+    --persona)      PERSONA="$2"; shift 2 ;;
+    --template)     TEMPLATE="$2"; shift 2 ;;
+    --change-class) CHANGE_CLASS="$2"; shift 2 ;;
+    --threshold)    THRESHOLD="$2"; shift 2 ;;
+    --json)         JSON_OUT=1; shift ;;
+    --help|-h)      usage; exit 0 ;;
+    *) echo "Unknown arg: $1" >&2; usage >&2; exit 2 ;;
+  esac
+done
+
+# === Mutual exclusion — only one artifact flag at a time ===
+FLAG_COUNT=0
+[ -n "$SKILL" ]    && FLAG_COUNT=$((FLAG_COUNT + 1))
+[ -n "$RULE" ]     && FLAG_COUNT=$((FLAG_COUNT + 1))
+[ -n "$STANDARD" ] && FLAG_COUNT=$((FLAG_COUNT + 1))
+[ -n "$HOOK" ]     && FLAG_COUNT=$((FLAG_COUNT + 1))
+[ -n "$LUMINARY" ] && FLAG_COUNT=$((FLAG_COUNT + 1))
+[ -n "$ADR" ]      && FLAG_COUNT=$((FLAG_COUNT + 1))
+[ -n "$PERSONA" ]  && FLAG_COUNT=$((FLAG_COUNT + 1))
+[ -n "$TEMPLATE" ] && FLAG_COUNT=$((FLAG_COUNT + 1))
+
+if [ "$FLAG_COUNT" -eq 0 ]; then
+  usage >&2
+  exit 2
+fi
+
+if [ "$FLAG_COUNT" -gt 1 ]; then
+  echo "ERROR: --skill, --rule, --standard, --hook, --luminary, --adr, --persona, --template are mutually exclusive; only one at a time" >&2
+  usage >&2
+  exit 2
+fi
+
+# === Change-class routing ===
+# Default class is simplify (matches pre-fold-in behavior for skill body rewrites).
+# Explicit --threshold overrides the class-derived value.
+if [ -z "$CHANGE_CLASS" ]; then
+  CHANGE_CLASS="simplify"
+fi
+
+# Validate class + set default threshold per bet 24a Path 1 table.
+CLASS_DEFAULT_THRESHOLD=""
+IS_MATERIAL=0
+case "$CHANGE_CLASS" in
+  preserve)    CLASS_DEFAULT_THRESHOLD="0.95" ;;
+  simplify)    CLASS_DEFAULT_THRESHOLD="0.90" ;;
+  extend)      CLASS_DEFAULT_THRESHOLD="0.70" ;;
+  restructure) CLASS_DEFAULT_THRESHOLD="0.65" ;;
+  material)    IS_MATERIAL=1; CLASS_DEFAULT_THRESHOLD="0.00" ;;
+  *) echo "ERROR: unknown --change-class: '$CHANGE_CLASS'" >&2
+     echo "  Valid values: preserve, simplify, extend, restructure, material" >&2
+     exit 2 ;;
+esac
+
+# Explicit --threshold overrides the class default.
+if [ -z "$THRESHOLD" ]; then
+  THRESHOLD="$CLASS_DEFAULT_THRESHOLD"
+fi
+
+# === Locate repo root ===
+if [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "$CLAUDE_PROJECT_DIR/.claude" ]; then
+  REPO_ROOT="$CLAUDE_PROJECT_DIR"
+else
+  REPO_ROOT="$(pwd)"
+fi
+
+# === Route to artifact type ===
+ARTIFACT_TYPE=""
+ARTIFACT_SLUG=""
+VECTOR_PATH=""
+SOURCE_PATH=""
+
+if [ -n "$SKILL" ]; then
+  ARTIFACT_TYPE="skill"
+  ARTIFACT_SLUG="$SKILL"
+  VECTOR_PATH="$REPO_ROOT/.claude/embeddings/skills/${SKILL}.json"
+  SOURCE_PATH="$REPO_ROOT/.claude/skills/${SKILL}/SKILL.md"
+elif [ -n "$RULE" ]; then
+  ARTIFACT_TYPE="rule"
+  ARTIFACT_SLUG="$RULE"
+  VECTOR_PATH="$REPO_ROOT/.claude/embeddings/rules/${RULE}.json"
+  SOURCE_PATH="$REPO_ROOT/.claude/rules/${RULE}.md"
+elif [ -n "$STANDARD" ]; then
+  ARTIFACT_TYPE="standard"
+  ARTIFACT_SLUG="$STANDARD"
+  VECTOR_PATH="$REPO_ROOT/.claude/embeddings/standards/${STANDARD}.json"
+  SOURCE_PATH="$REPO_ROOT/standards/${STANDARD}.md"
+elif [ -n "$HOOK" ]; then
+  ARTIFACT_TYPE="hook"
+  ARTIFACT_SLUG="$HOOK"
+  VECTOR_PATH="$REPO_ROOT/.claude/embeddings/hooks/${HOOK}.json"
+  SOURCE_PATH="$REPO_ROOT/.claude/hooks/${HOOK}.sh"
+elif [ -n "$LUMINARY" ]; then
+  ARTIFACT_TYPE="luminary"
+  ARTIFACT_SLUG="$LUMINARY"
+  VECTOR_PATH="$REPO_ROOT/.claude/embeddings/luminaries/${LUMINARY}.json"
+  SOURCE_PATH="$REPO_ROOT/.claude/luminaries/${LUMINARY}.md"
+elif [ -n "$ADR" ]; then
+  ARTIFACT_TYPE="adr"
+  ARTIFACT_SLUG="$ADR"
+  VECTOR_PATH="$REPO_ROOT/.claude/embeddings/adrs/${ADR}.json"
+  SOURCE_PATH="$REPO_ROOT/architecture/decisions/${ADR}.md"
+elif [ -n "$PERSONA" ]; then
+  ARTIFACT_TYPE="persona"
+  ARTIFACT_SLUG="$PERSONA"
+  VECTOR_PATH="$REPO_ROOT/.claude/embeddings/personas/${PERSONA}.json"
+  SOURCE_PATH="$REPO_ROOT/docs/personas/${PERSONA}.md"
+elif [ -n "$TEMPLATE" ]; then
+  ARTIFACT_TYPE="template"
+  ARTIFACT_SLUG="$TEMPLATE"
+  VECTOR_PATH="$REPO_ROOT/.claude/embeddings/templates/${TEMPLATE}.json"
+  SOURCE_PATH="$REPO_ROOT/templates/${TEMPLATE}.md"
+fi
+
+# === Preconditions ===
+if [ ! -f "$VECTOR_PATH" ]; then
+  echo "ERROR: saved vector not found at $VECTOR_PATH" >&2
+  echo "  Run scripts/embed-lite-corpus.sh to generate baseline vectors first." >&2
+  exit 2
+fi
+
+if [ ! -f "$SOURCE_PATH" ]; then
+  echo "ERROR: source file not found at $SOURCE_PATH" >&2
+  exit 2
+fi
+
+# === Extract current body — one function per artifact shape ===
+#
+# EXTRACT_SAMPLE_BYTES is the byte window sampled from each artifact body.
+# Voyage-3-lite context window is 32K tokens (~128KB in ASCII). 30000 chars
+# ≈ 7500 tokens fits well under limit and covers 99% of SKILL bodies.
+# MUST stay in sync with embed-lite-corpus.sh + embed-substrate-corpus.sh —
+# cosine comparison only means anything when the drift-check samples the
+# same text shape the baseline was embedded on. Per goal 2026-08-16g cure
+# of chunk 2 coverage gap where L321 edit was invisible to 1500-char window.
+EXTRACT_SAMPLE_BYTES="${EXTRACT_SAMPLE_BYTES:-30000}"
+
+# === Extractors aligned with baseline generators per #1244 cure ===
+# The functions below MUST emit byte-for-byte identical text to the baseline
+# generator for the same file. Sources of truth:
+#   skill    → scripts/embed-lite-corpus.sh:_extract_skill_text
+#   persona  → scripts/embed-lite-corpus.sh:_extract_persona_text
+#   hook     → scripts/embed-substrate-corpus.sh:_extract_hook_text
+#   rule     → scripts/embed-substrate-corpus.sh:_extract_rule_text
+#   standard → scripts/embed-substrate-corpus.sh:_extract_standard_text (= rule shape)
+#   adr      → scripts/embed-substrate-corpus.sh:_extract_adr_text
+#   template → scripts/embed-substrate-corpus.sh:_extract_template_text
+#   luminary → scripts/intent-matcher.sh:_intent_matcher_extract_luminary_text (deferred; falls back to rule shape)
+# Tier 0 test at .claude/hooks/tests/intent-drift-extractor-alignment.test.sh
+# pins baseline_extractor(fixture) == checker_extractor(fixture) per type.
+
+extract_skill_text() {
+  # ALIGNED with embed-lite-corpus.sh:_extract_skill_text
+  local file="$1"
+  local desc body
+  desc=$(awk '/^description:/ { sub("^description:[[:space:]]*",""); gsub(/^"/,""); gsub(/"$/,""); print; exit }' "$file")
+  body=$(awk 'BEGIN { count=0 } /^---$/ { count++; next } count >= 2 { print }' "$file" | head -c "$EXTRACT_SAMPLE_BYTES")
+  printf 'Description: %s\n\n%s\n' "$desc" "$body" | LC_ALL=C tr -d '\000-\010\013\014\016-\037'
+}
+
+extract_hook_text() {
+  # ALIGNED with embed-substrate-corpus.sh:_extract_hook_text (per #1244)
+  # Baseline emits: Docstring: <stripped-#-header-first-20>\n\n<body-without-#-lines>
+  local file="$1"
+  local docstring body
+  docstring=$(awk '/^#/ { sub("^#[[:space:]]*",""); print } !/^#/ { exit }' "$file" | head -20)
+  body=$(awk '!/^#/ { print }' "$file" | head -c "$EXTRACT_SAMPLE_BYTES")
+  printf 'Docstring: %s\n\n%s\n' "$docstring" "$body" | LC_ALL=C tr -d '\000-\010\013\014\016-\037'
+}
+
+extract_rule_text() {
+  # ALIGNED with embed-substrate-corpus.sh:_extract_rule_text (per #1244)
+  # Baseline emits: Title: <first-H1>\n\n<body-after-2nd----->
+  local file="$1"
+  local title body
+  title=$(grep -m1 '^# ' "$file" | sed 's/^# //')
+  body=$(awk 'BEGIN { count=0 } /^---$/ { count++; next } count >= 2 { print }' "$file" | head -c "$EXTRACT_SAMPLE_BYTES")
+  # Rules may not have frontmatter — fall back to whole file
+  if [ -z "$body" ]; then
+    body=$(head -c "$EXTRACT_SAMPLE_BYTES" "$file")
+  fi
+  printf 'Title: %s\n\n%s\n' "$title" "$body" | LC_ALL=C tr -d '\000-\010\013\014\016-\037'
+}
+
+extract_standard_text() {
+  # ALIGNED with embed-substrate-corpus.sh:_extract_standard_text (= rule shape)
+  extract_rule_text "$1"
+}
+
+extract_adr_text() {
+  # ALIGNED with embed-substrate-corpus.sh:_extract_adr_text (per #1244)
+  # Baseline emits: ADR Title: <from-frontmatter>\n\n<body-after-2nd----->
+  local file="$1"
+  local title body
+  title=$(awk '/^title:/ { sub("^title:[[:space:]]*",""); gsub(/^"/,""); gsub(/"$/,""); print; exit }' "$file")
+  body=$(awk 'BEGIN { count=0 } /^---$/ { count++; next } count >= 2 { print }' "$file" | head -c "$EXTRACT_SAMPLE_BYTES")
+  printf 'ADR Title: %s\n\n%s\n' "$title" "$body" | LC_ALL=C tr -d '\000-\010\013\014\016-\037'
+}
+
+extract_persona_text() {
+  # ALIGNED with embed-lite-corpus.sh:_extract_persona_text (per #1244)
+  # Baseline emits: Role: <from-frontmatter>\n\n<body-after-2nd----->
+  local file="$1"
+  local role body
+  role=$(awk '/^role:/ { sub("^role:[[:space:]]*",""); print; exit }' "$file")
+  body=$(awk 'BEGIN { count=0 } /^---$/ { count++; next } count >= 2 { print }' "$file" | head -c "$EXTRACT_SAMPLE_BYTES")
+  printf 'Role: %s\n\n%s\n' "$role" "$body" | LC_ALL=C tr -d '\000-\010\013\014\016-\037'
+}
+
+extract_template_text() {
+  # ALIGNED with embed-substrate-corpus.sh:_extract_template_text (per #1244)
+  # Baseline emits: Template: <basename>\n\n<body-raw>
+  local file="$1"
+  local name body
+  name=$(basename "$file")
+  body=$(head -c "$EXTRACT_SAMPLE_BYTES" "$file")
+  printf 'Template: %s\n\n%s\n' "$name" "$body" | LC_ALL=C tr -d '\000-\010\013\014\016-\037'
+}
+
+extract_luminary_text() {
+  # NOT YET ALIGNED — deferred per #1244 out-of-scope note. Luminary baseline
+  # generator is intent-matcher.sh:_intent_matcher_extract_luminary_text which
+  # uses a complex frontmatter extractor (name + primary_domain + signature +
+  # solves_problems + anti_patterns). No luminaries in chunks 1a/1b/2/3 swept
+  # scope so false-positives here have not surfaced. Follow-on ticket owed if
+  # luminary intent-drift becomes load-bearing.
+  # For now, keep prior rule-shape fallback so calls do not fail.
+  local file="$1"
+  local body
+  if head -n 1 "$file" | grep -q '^---$'; then
+    body=$(awk 'BEGIN { count=0 } /^---$/ { count++; next } count >= 2 { print }' "$file" | head -c "$EXTRACT_SAMPLE_BYTES")
+  else
+    body=$(head -c "$EXTRACT_SAMPLE_BYTES" "$file")
+  fi
+  printf '%s\n' "$body" | LC_ALL=C tr -d '\000-\010\013\014\016-\037'
+}
+
+case "$ARTIFACT_TYPE" in
+  skill)     CURRENT_TEXT=$(extract_skill_text "$SOURCE_PATH") ;;
+  hook)      CURRENT_TEXT=$(extract_hook_text "$SOURCE_PATH") ;;
+  rule)      CURRENT_TEXT=$(extract_rule_text "$SOURCE_PATH") ;;
+  standard)  CURRENT_TEXT=$(extract_standard_text "$SOURCE_PATH") ;;
+  adr)       CURRENT_TEXT=$(extract_adr_text "$SOURCE_PATH") ;;
+  persona)   CURRENT_TEXT=$(extract_persona_text "$SOURCE_PATH") ;;
+  template)  CURRENT_TEXT=$(extract_template_text "$SOURCE_PATH") ;;
+  luminary)  CURRENT_TEXT=$(extract_luminary_text "$SOURCE_PATH") ;;
+esac
+
+# === Read saved vector ===
+SAVED_EMB=$(jq -c '.embedding' "$VECTOR_PATH" 2>/dev/null)
+if [ -z "$SAVED_EMB" ] || [ "$SAVED_EMB" = "null" ]; then
+  echo "ERROR: saved vector at $VECTOR_PATH has no .embedding field" >&2
+  exit 2
+fi
+
+# === STUB mode — skip Voyage, return cosine 1.0 ===
+if [ "${INTENT_DRIFT_STUB:-0}" = "1" ]; then
+  COSINE="1.0"
+  MODE="STUB"
+else
+  # === Live mode — re-embed via intent-matcher.sh ===
+  # shellcheck source=scripts/intent-matcher.sh
+  source "$REPO_ROOT/scripts/intent-matcher.sh"
+
+  if ! intent_matcher_is_live; then
+    echo "ERROR: intent-matcher.sh reports STUB (missing VOYAGE_API_KEY or ANTHROPIC_API_KEY)" >&2
+    echo "  Set INTENT_DRIFT_STUB=1 to skip Voyage call for testing." >&2
+    exit 2
+  fi
+
+  TMP_EMB=$(mktemp)
+  trap "rm -f '$TMP_EMB'" EXIT
+
+  if ! _intent_matcher_live_embed "$CURRENT_TEXT" "$TMP_EMB"; then
+    echo "ERROR: Voyage embed call failed" >&2
+    exit 2
+  fi
+
+  CURRENT_EMB=$(jq -c '.embedding' "$TMP_EMB")
+  COSINE=$(intent_matcher_cosine "$SAVED_EMB" "$CURRENT_EMB")
+  MODE="LIVE"
+fi
+
+# === Compare against threshold ===
+# Material class always passes (log only). Other classes compare cosine.
+if [ "$IS_MATERIAL" -eq 1 ]; then
+  VERDICT="PASS-LOGGED"
+else
+  # jq for numeric compare (bash arithmetic is int-only)
+  VERDICT=$(jq -n --argjson cos "$COSINE" --argjson thr "$THRESHOLD" \
+    'if $cos >= $thr then "PASS" else "FAIL" end')
+  VERDICT=$(echo "$VERDICT" | tr -d '"')
+fi
+
+# === Output ===
+if [ "$JSON_OUT" -eq 1 ]; then
+  jq -n \
+    --arg artifact_type "$ARTIFACT_TYPE" \
+    --arg artifact_slug "$ARTIFACT_SLUG" \
+    --arg change_class "$CHANGE_CLASS" \
+    --argjson cosine "$COSINE" \
+    --argjson threshold "$THRESHOLD" \
+    --arg verdict "$VERDICT" \
+    --arg mode "$MODE" \
+    '{
+      artifact_type: $artifact_type,
+      artifact_slug: $artifact_slug,
+      change_class: $change_class,
+      cosine: $cosine,
+      threshold: $threshold,
+      verdict: $verdict,
+      mode: $mode
+    }'
+else
+  echo "Artifact: $ARTIFACT_TYPE/$ARTIFACT_SLUG"
+  echo "Change class: $CHANGE_CLASS"
+  if [ "$IS_MATERIAL" -eq 1 ]; then
+    echo "Cosine: $COSINE (material class — log only, no threshold)"
+  else
+    echo "Cosine: $COSINE (threshold $THRESHOLD)"
+  fi
+  echo "Verdict: $VERDICT ($MODE)"
+fi
+
+# === Exit code ===
+# Material class always exits 0 regardless of cosine.
+if [ "$IS_MATERIAL" -eq 1 ]; then
+  exit 0
+elif [ "$VERDICT" = "PASS" ]; then
+  exit 0
+else
+  exit 1
+fi

package/dist/lite/scripts/lite-manifest-drift-check.sh

@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+# tier: lite
+# Detect drift between committed lite-manifest.json and current substrate state.
+#
+# Runs the generator against current source; compares entries[] against
+# the committed manifest. If they differ, exit 1 with a diff and cure
+# instructions. Called by CI workflow .github/workflows/lite-manifest-drift-check.yml
+# on every PR touching lite frontmatter or the manifest itself.
+#
+# Per bassclef-upstream#1020 Step 5. Session 2026-08-01d option b.
+#
+# Cures per pre-mortem risk ledger docs/risk-ledgers/2026-08-01c-lite-manifest.md:
+#   F2.4 + F2.5 — catches tier: lite edit without manifest bump
+#   F-b.N1 — generator + drift-check bump together (same PR); no false-fail
+#   F-b.N2 — 60s workflow timeout enforced at CI layer (this script itself is fast)
+#
+# Compares .entries[] only. Does NOT compare .generated_at or .upstream_commit
+# — those always differ between runs; comparing them would fire on every PR.
+#
+# Usage:
+#   scripts/lite-manifest-drift-check.sh                # check against ./lite-manifest.json
+#   scripts/lite-manifest-drift-check.sh --root PATH    # override repo root (test harness)
+#   scripts/lite-manifest-drift-check.sh --manifest P   # check against alternative manifest
+#
+# Exit codes:
+#   0 — no drift; manifest matches current substrate
+#   1 — drift detected OR missing dependency
+#   2 — manifest file missing
+
+set -euo pipefail
+
+REPO_ROOT_OVERRIDE=""
+MANIFEST_OVERRIDE=""
+TARGET_TIER="lite"  # per #1295 — extended to check lite/standard/ultra manifests
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --root) REPO_ROOT_OVERRIDE="${2:-}"; shift 2 ;;
+    --manifest) MANIFEST_OVERRIDE="${2:-}"; shift 2 ;;
+    --tier) TARGET_TIER="${2:-}"; shift 2 ;;
+    -h|--help)
+      grep -E '^# ' "$0" | sed 's/^# \?//'
+      exit 0
+      ;;
+    *) echo "Unknown arg: $1 (use --help)" >&2; exit 1 ;;
+  esac
+done
+
+case "$TARGET_TIER" in
+  lite|standard|ultra|standard-pro) ;;
+  *) echo "tier-manifest-drift-check: invalid --tier '$TARGET_TIER' (allowed: lite, standard, ultra, standard-pro)" >&2; exit 1 ;;
+esac
+
+if [[ -n "$REPO_ROOT_OVERRIDE" ]]; then
+  REPO_ROOT="$REPO_ROOT_OVERRIDE"
+else
+  REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+fi
+
+if [[ -z "$REPO_ROOT" || ! -d "$REPO_ROOT" ]]; then
+  echo "lite-manifest-drift-check: cannot resolve repo root" >&2
+  exit 1
+fi
+
+MANIFEST_FILE="${MANIFEST_OVERRIDE:-${REPO_ROOT}/${TARGET_TIER}-manifest.json}"
+
+if [[ ! -f "$MANIFEST_FILE" ]]; then
+  echo "lite-manifest-drift-check: manifest file not found at $MANIFEST_FILE" >&2
+  echo "Run scripts/generate-lite-manifest.sh to create it." >&2
+  exit 2
+fi
+
+for cmd in jq bash; do
+  if ! command -v "$cmd" >/dev/null 2>&1; then
+    echo "lite-manifest-drift-check: missing dependency: $cmd" >&2
+    exit 1
+  fi
+done
+
+TMP_CANDIDATE=$(mktemp)
+trap 'rm -f "$TMP_CANDIDATE"' EXIT
+
+bash "${REPO_ROOT}/scripts/generate-lite-manifest.sh" --tier "$TARGET_TIER" --root "$REPO_ROOT" --output "$TMP_CANDIDATE" 2>/dev/null
+
+# Compare entries[] arrays (sorted; ignoring generated_at + upstream_commit)
+COMMITTED_ENTRIES=$(jq -S '.entries' "$MANIFEST_FILE")
+CANDIDATE_ENTRIES=$(jq -S '.entries' "$TMP_CANDIDATE")
+
+if [[ "$COMMITTED_ENTRIES" == "$CANDIDATE_ENTRIES" ]]; then
+  echo "${TARGET_TIER}-manifest is up to date ($(jq '.entries | length' "$MANIFEST_FILE") entries)"
+  exit 0
+fi
+
+# Drift detected — surface concrete diff
+echo "" >&2
+echo "============================================================" >&2
+echo "DRIFT DETECTED: lite-manifest.json does not match substrate" >&2
+echo "============================================================" >&2
+echo "" >&2
+
+COMMITTED_COUNT=$(jq '.entries | length' "$MANIFEST_FILE")
+CANDIDATE_COUNT=$(jq '.entries | length' "$TMP_CANDIDATE")
+echo "Committed manifest: $COMMITTED_COUNT entries" >&2
+echo "Current substrate:  $CANDIDATE_COUNT entries" >&2
+echo "" >&2
+
+# Show added / removed slugs by type for readability
+COMMITTED_KEYS=$(echo "$COMMITTED_ENTRIES" | jq -r '.[] | .type + "/" + .slug' | sort)
+CANDIDATE_KEYS=$(echo "$CANDIDATE_ENTRIES" | jq -r '.[] | .type + "/" + .slug' | sort)
+
+ADDED=$(comm -23 <(echo "$CANDIDATE_KEYS") <(echo "$COMMITTED_KEYS"))
+REMOVED=$(comm -13 <(echo "$CANDIDATE_KEYS") <(echo "$COMMITTED_KEYS"))
+
+if [[ -n "$ADDED" ]]; then
+  echo "Entries ADDED to substrate but missing from manifest:" >&2
+  echo "$ADDED" | sed 's/^/  + /' >&2
+  echo "" >&2
+fi
+
+if [[ -n "$REMOVED" ]]; then
+  echo "Entries in manifest but REMOVED from substrate:" >&2
+  echo "$REMOVED" | sed 's/^/  - /' >&2
+  echo "" >&2
+fi
+
+# Content hash changes (same slug, different content)
+CONTENT_CHANGES=$(diff <(echo "$COMMITTED_ENTRIES" | jq -c '.[] | {type,slug,content_hash}' | sort) \
+                       <(echo "$CANDIDATE_ENTRIES" | jq -c '.[] | {type,slug,content_hash}' | sort) \
+                  | grep -E '^[<>]' | head -20 || true)
+if [[ -n "$CONTENT_CHANGES" ]]; then
+  echo "Content-hash changes (same slug, different content):" >&2
+  echo "$CONTENT_CHANGES" | sed 's/^/  /' >&2
+  echo "" >&2
+fi
+
+echo "----- Cure -----" >&2
+echo "  bash scripts/generate-lite-manifest.sh" >&2
+echo "  # then edit lite-manifest.json manifest_version per semver bump policy:" >&2
+echo "  #   entry added → minor bump   (e.g., 1.0.0 → 1.1.0)" >&2
+echo "  #   entry removed → major bump (e.g., 1.1.0 → 2.0.0; breaks partners)" >&2
+echo "  #   content_hash change only → patch bump (e.g., 1.1.0 → 1.1.1)" >&2
+echo "  bash scripts/render-lite-manifest-doc.sh" >&2
+echo "  git add lite-manifest.json docs/lite-manifest.md" >&2
+echo "" >&2
+
+exit 1