@thebassclef/lite 1.0.0 → 1.0.2

package/dist/lite/.claude/hooks/substrate-clarity-gate.sh

@@ -0,0 +1,1110 @@
+#!/bin/bash
+# tier: lite
+# Substrate Clarity Gate — fires on Write/Edit to substrate paths
+# (.claude/skills/, .claude/rules/, .claude/luminaries/). Enforces the
+# clarity + context-engineering discipline from bassclef#371 + #377.
+#
+# v1 (2026-05-07 Phase I — Plain English Sweep) — ALL THREE SURFACES BLOCK:
+# - Skill descriptions ≤280 chars, verb-first opener, no jargon ladder
+# - Rule INSTEAD-block discipline (every don't/never/avoid paired
+#   with INSTEAD within 5 lines) — flipped from ADVISORY to BLOCK
+# - Luminary INSTEAD-block discipline — flipped from ADVISORY to BLOCK
+# - Luminary required-sections check stays ADVISORY (documentation
+#   discipline, not blocking concern)
+#
+# Allowlist grandfathers ~94 existing violators per bassclef#373/#374/#375
+# audits. Each audit shrinks its section as files get fixed individually.
+#
+# Exit codes:
+#   0 — allow (path doesn't match, or all checks pass, or override,
+#       or path on allowlist)
+#   2 — block (matcher hit, violation found, no override)
+#
+# Override: SKIP_SUBSTRATE_CLARITY=1 to bypass (logged via trace-helper)
+#
+# Allowlist: .claude/hooks/substrate-clarity-allowlist.txt
+#
+# Rule:  .claude/rules/skill-description-clarity.md
+# Issue: bassclef#382 (v0); Phase I bet (v1 flip)
+
+set +e  # never crash the tool call; fall through to allow on any unexpected error
+
+# === Hook liveness heartbeat (WU-3 of bet 2026-07-31d; closes #1002) ===
+# Silent-fail — a missing lib never crashes the hook.
+{
+  _hb_sd="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _hb_c in "${_hb_sd}/../../lib/hook-heartbeat.sh" "${HOME:-/}/lib/hook-heartbeat.sh"; do
+    [ -f "$_hb_c" ] && source "$_hb_c" && heartbeat_mark "substrate-clarity-gate" && break
+  done
+  unset _hb_sd _hb_c
+} 2>/dev/null || true
+
+INPUT=$(cat)
+TOOL_NAME=$(jq <<< "$INPUT" -r '.tool_name // ""' 2>/dev/null)
+FILE_PATH=$(jq <<< "$INPUT" -r '.tool_input.file_path // ""' 2>/dev/null)
+
+# Only fire on Write / Edit
+if [ "$TOOL_NAME" != "Write" ] && [ "$TOOL_NAME" != "Edit" ]; then
+  exit 0
+fi
+
+# No file path → allow (defensive)
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Determine surface type from path.
+# v0 scope: skill SKILL.md (length + verb-first + jargon — strict)
+# v1 scope: rule + luminary (INSTEAD-block — strict; flipped from advisory in Phase I)
+# v2 scope (Phase II WU-7b): chronicle + iteration_bet + journal_entry + decomposition
+#   Advisory only — sentence-length, passive-voice, expanded jargon list.
+#   These surfaces are operator-narrative; voice trumps strict rule.
+SURFACE=""
+case "$FILE_PATH" in
+  */.claude/skills/*/SKILL.md)              SURFACE="skill" ;;
+  */.claude/rules/*.md)                     SURFACE="rule" ;;
+  */.claude/luminaries/*.md)                SURFACE="luminary" ;;
+  */.claude/agents/*.md)                    SURFACE="agent" ;;
+  */.claude/hooks/*.sh)                     SURFACE="hook" ;;
+  */architecture/decisions/ADR-*.md)        SURFACE="adr" ;;
+  */chronicle/*.md|*/docs/chronicle/*.md)   SURFACE="chronicle" ;;
+  */docs/iteration-bets/*.md)               SURFACE="iteration_bet" ;;
+  */docs/operator-private/journals/*.md)              SURFACE="journal_entry" ;;
+  */docs/decompositions/*.md)               SURFACE="decomposition" ;;
+  */docs/whereami.md)                       SURFACE="whereami" ;;
+  # Surfaces added per goal 25e Path A — 15 SDLC artifact classes newly covered
+  */docs/canvases/*.md)                     SURFACE="canvas" ;;
+  */docs/use-cases/*.md)                    SURFACE="use_case" ;;
+  */docs/personas/*.md)                     SURFACE="persona" ;;
+  */docs/roadmaps/*.md)                     SURFACE="roadmap" ;;
+  */docs/risk-ledgers/*.md)                 SURFACE="risk_ledger" ;;
+  */docs/empathy-maps/*.md)                 SURFACE="empathy_map" ;;
+  */docs/interaction-design/*.md)           SURFACE="interaction_design" ;;
+  */docs/handoffs/*.md)                     SURFACE="handoff" ;;
+  */docs/audits/*.md|*/architecture/audits/*.md) SURFACE="audit" ;;
+  */docs/reflections/*.md)                  SURFACE="reflection" ;;
+  */docs/regressions/*.md)                  SURFACE="regression" ;;
+  */docs/release-notes/*.md)                SURFACE="release_notes" ;;
+  */docs/analysis/*.md)                     SURFACE="analysis" ;;
+  */docs/curation/*.md)                     SURFACE="curation" ;;
+  */standards/*.md)                         SURFACE="standard" ;;
+  */templates/*.md)                         SURFACE="template" ;;
+esac
+
+if [ -z "$SURFACE" ]; then
+  exit 0
+fi
+
+# Surface tier — strict surfaces BLOCK; advisory surfaces only emit notices.
+# chronicle + iteration_bet + decomposition FLIPPED from advisory to strict
+# after the bassclef-upstream#303 audit emptied the grandfathered allowlist
+# (38 files scrubbed via bet 2026-06-25j). journal_entry remains advisory
+# per memory feedback_writing_voice — personal-narrative voice trumps strict
+# rule.
+case "$SURFACE" in
+  skill|rule|luminary|adr|chronicle|iteration_bet|decomposition)
+    SURFACE_TIER="strict"
+    ;;
+  journal_entry|whereami)
+    # journal_entry — personal-narrative voice trumps strict rule per memory
+    # feedback_writing_voice.
+    # whereami — V1 advisory per bassclef-upstream bet 2026-07-04a WU-1.
+    # Advisory tier lets us ship coverage without retroactively scrubbing
+    # today's whereami frontmatter (which carries historical terms).
+    SURFACE_TIER="advisory"
+    ;;
+  canvas|use_case|persona|roadmap|risk_ledger|empathy_map|interaction_design|handoff|audit|reflection|regression|release_notes|analysis|curation|standard|template)
+    # New surfaces per goal 25e Path A — V1 ADVISORY only.
+    # These surfaces get the rewrite-check heuristics layer below.
+    # They do NOT run strict INSTEAD-block checks (those apply only to
+    # rules + luminaries + skills). V2 may tier strict/medium after
+    # calibration cycle.
+    SURFACE_TIER="advisory"
+    ;;
+  *)
+    SURFACE_TIER="strict"
+    ;;
+esac
+
+# Surface-level allowlist for flip-from-advisory grandfathered content.
+# Bypasses strict checks until the file is scrubbed (per bassclef-upstream#303 audit).
+# After scrub, remove the file's path from the allowlist file.
+ALLOWLIST_FILE="$(dirname "$0")/substrate-clarity-gate-allowlist.txt"
+if [ -f "$ALLOWLIST_FILE" ]; then
+  # Match by basename relative to repo root (path may be absolute or relative)
+  REL_PATH="${FILE_PATH#*$PWD/}"
+  REL_PATH="${REL_PATH#$PWD/}"
+  if grep -Fxq "$REL_PATH" "$ALLOWLIST_FILE" 2>/dev/null \
+     || grep -Fxq "$FILE_PATH" "$ALLOWLIST_FILE" 2>/dev/null; then
+    exit 0
+  fi
+fi
+
+# Override hatch — log and allow
+if [ "${SKIP_SUBSTRATE_CLARITY:-0}" = "1" ]; then
+  SCRIPT_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
+  if [ -n "$SCRIPT_DIR" ] && [ -f "$SCRIPT_DIR/trace-helper.sh" ]; then
+    source "$SCRIPT_DIR/trace-helper.sh" 2>/dev/null || true
+    trace_log "substrate-clarity-gate" "OVERRIDE $TOOL_NAME $FILE_PATH ($SURFACE)" 2>/dev/null || true
+  fi
+  exit 0
+fi
+
+# Allowlist check (WU-4 ships the file; pre-WU-4 the file may not exist)
+SCRIPT_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
+ALLOWLIST_FILE="${SCRIPT_DIR}/substrate-clarity-allowlist.txt"
+# Match against repo-relative path (strip leading /Users/.../bassclef/ etc.)
+REPO_REL=$(echo "$FILE_PATH" | sed -E 's|^.*/(\.claude/.*)$|\1|')
+if [ -f "$ALLOWLIST_FILE" ]; then
+  if grep -Fxq "$REPO_REL" "$ALLOWLIST_FILE" 2>/dev/null; then
+    exit 0  # allowlisted (SCRIPT_DIR match); check skipped
+  fi
+fi
+
+# Repo-allowlist fallback (bassclef-upstream#358).
+# When hook is installed at user level (~/.claude/hooks/) and SCRIPT_DIR
+# allowlist doesn't match, also check the consumer repo's allowlist via
+# CLAUDE_PROJECT_DIR. Closes the propagation gap surfaced during bet 25h WU-3.
+if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
+  REPO_ALLOWLIST_FILE="${CLAUDE_PROJECT_DIR}/.claude/hooks/substrate-clarity-allowlist.txt"
+  if [ -f "$REPO_ALLOWLIST_FILE" ] && [ "$REPO_ALLOWLIST_FILE" != "$ALLOWLIST_FILE" ]; then
+    if grep -Fxq "$REPO_REL" "$REPO_ALLOWLIST_FILE" 2>/dev/null; then
+      exit 0  # allowlisted (repo-fallback match); check skipped
+    fi
+  fi
+fi
+
+# Assemble the content that WILL exist after this operation.
+FUTURE_CONTENT=""
+if [ "$TOOL_NAME" = "Write" ]; then
+  FUTURE_CONTENT=$(jq <<< "$INPUT" -r '.tool_input.content // ""' 2>/dev/null)
+elif [ "$TOOL_NAME" = "Edit" ]; then
+  NEW_STRING=$(jq <<< "$INPUT" -r '.tool_input.new_string // ""' 2>/dev/null)
+  EXISTING=""
+  if [ -f "$FILE_PATH" ]; then
+    EXISTING=$(cat "$FILE_PATH" 2>/dev/null)
+  fi
+  # Apply the edit: replace OLD with NEW within EXISTING. For check purposes
+  # we use full FUTURE_CONTENT — concat is rough but covers both surface text.
+  OLD_STRING=$(jq <<< "$INPUT" -r '.tool_input.old_string // ""' 2>/dev/null)
+  if [ -n "$EXISTING" ] && [ -n "$OLD_STRING" ]; then
+    # Use python3 for safe string substitution (env vars avoid bash 4+ ${var@Q})
+    FUTURE_CONTENT=$(OLD="$OLD_STRING" NEW="$NEW_STRING" python3 -c "
+import os, sys
+existing = sys.stdin.read()
+print(existing.replace(os.environ['OLD'], os.environ['NEW'], 1), end='')
+" <<< "$EXISTING" 2>/dev/null || echo "${EXISTING}
+${NEW_STRING}")
+  else
+    FUTURE_CONTENT="${EXISTING}
+${NEW_STRING}"
+  fi
+fi
+
+# === Check dispatch ===
+VIOLATION=""
+LINE_REF=""
+SUGGESTED_FIX=""
+
+# ---------------------------------------------------------------------------
+# Documentation-surface tier check (bassclef-upstream#1012)
+#
+# The tier: field applies to substrate building blocks (skills, rules,
+# luminaries, agents, hooks, ADRs, standards) whose maturity governs
+# release-script filtering. Documentation surfaces — release-notes,
+# roadmaps, canvases — ship unconditionally via the release script's
+# fallback branch (scripts/release-to-bassclef.sh:367-372). The tier:
+# field there is cosmetic and misleads adopters.
+#
+# Per /luminary consult 2026-07-31: Norman (signifier discipline),
+# Brooks (conceptual integrity), Linus (adopter contract) — all
+# endorsed removing the field from documentation surfaces.
+# ---------------------------------------------------------------------------
+case "$SURFACE" in
+  release_notes|roadmap|canvas)
+    # Extract frontmatter block from FUTURE_CONTENT and grep for tier: line.
+    # Frontmatter opens with --- on line 1 and closes with --- on a later line.
+    TIER_LINE=$(echo "$FUTURE_CONTENT" | awk '
+      BEGIN { in_fm = 0 }
+      NR == 1 && /^---[[:space:]]*$/ { in_fm = 1; next }
+      in_fm && /^---[[:space:]]*$/ { exit }
+      in_fm && /^tier:[[:space:]]/ { print; exit }
+    ')
+    if [ -n "$TIER_LINE" ]; then
+      VIOLATION="tier: field on ${SURFACE} surface is cosmetic (release script does not read it here) — remove per bassclef-upstream#1012."
+      LINE_REF="frontmatter tier: line"
+      SUGGESTED_FIX="Delete the tier: line from frontmatter. The field applies to substrate building-block surfaces (skills, rules, luminaries, agents, hooks, ADRs, standards) — not documentation surfaces (release-notes, roadmaps, canvases). See standards/tier-tag-schema.md § Scope."
+    fi
+    ;;
+esac
+
+# ---------------------------------------------------------------------------
+# Frontmatter schema validation (bassclef#862 Gap 1, WU-3 of bet 2026-06-18a)
+# Fires for skill + rule surfaces only. Validates:
+#   1. Required fields present and non-empty
+#   2. YAML parses cleanly (malformed → BLOCK)
+#   3. Field names are recognized (unknown → WARN, no block)
+# Schema source: standards/frontmatter-schema.md
+# Allowlist: .claude/hooks/substrate-frontmatter-allowlist.txt (60-day grace)
+# ---------------------------------------------------------------------------
+# Hook (.sh) tier validation — separate path from YAML frontmatter.
+# Hooks carry `# tier: <value>` as a header comment on line 2 (after shebang).
+# Per goal 2026-08-13d Piece 2 (bassclef-upstream#1200):
+# missing `# tier:` header → BLOCK; invalid value → BLOCK.
+if [ "$SURFACE" = "hook" ]; then
+  HOOK_TIER=$(echo "$FUTURE_CONTENT" | head -5 | awk '/^# tier:[[:space:]]/ {sub(/^# tier:[[:space:]]*/,""); gsub(/[[:space:]]/,""); print; exit}')
+  if [ -z "$HOOK_TIER" ]; then
+    echo "" >&2
+    echo "============================================" >&2
+    echo "🛑 SUBSTRATE-CLARITY GATE — BLOCKED 🛑" >&2
+    echo "============================================" >&2
+    echo "" >&2
+    echo "File:  $FILE_PATH" >&2
+    echo "Tool:  $TOOL_NAME" >&2
+    echo "" >&2
+    echo "Violation:  missing required '# tier:' header for hook (.sh)" >&2
+    echo "Line:       header comment on line 2 (after shebang)" >&2
+    echo "" >&2
+    echo "Suggested fix:" >&2
+    echo "  Add '# tier: <value>' as the second line, e.g.:" >&2
+    echo "    #!/usr/bin/env bash" >&2
+    echo "    # tier: standard" >&2
+    echo "" >&2
+    echo "Valid values: upstream | lite | standard | standard-pro | ultra" >&2
+    echo "  (private accepted as deprecated alias for upstream)" >&2
+    echo "" >&2
+    echo "Per rule:   standards/tier-tag-schema.md" >&2
+    echo "Per goal:   bassclef-upstream#1200 Piece 2" >&2
+    echo "" >&2
+    echo "Override (logged):  SKIP_SUBSTRATE_CLARITY=1 <command>" >&2
+    echo "============================================" >&2
+    exit 2
+  fi
+  case "$HOOK_TIER" in
+    upstream|private|lite|standard|standard-pro|ultra) : ;;
+    *)
+      echo "" >&2
+      echo "============================================" >&2
+      echo "🛑 SUBSTRATE-CLARITY GATE — BLOCKED 🛑" >&2
+      echo "============================================" >&2
+      echo "" >&2
+      echo "File:  $FILE_PATH" >&2
+      echo "Tool:  $TOOL_NAME" >&2
+      echo "" >&2
+      echo "Violation:  invalid '# tier:' value '$HOOK_TIER' on hook" >&2
+      echo "Valid values: upstream | lite | standard | standard-pro | ultra" >&2
+      echo "  (private accepted as deprecated alias for upstream)" >&2
+      echo "" >&2
+      echo "Per rule:   standards/tier-tag-schema.md" >&2
+      echo "Override (logged):  SKIP_SUBSTRATE_CLARITY=1 <command>" >&2
+      echo "============================================" >&2
+      exit 2
+      ;;
+  esac
+fi
+
+if [ "$SURFACE" = "skill" ] || [ "$SURFACE" = "rule" ] || \
+   [ "$SURFACE" = "luminary" ] || [ "$SURFACE" = "agent" ] || \
+   [ "$SURFACE" = "adr" ] || [ "$SURFACE" = "standard" ]; then
+  FRONTMATTER_ALLOWLIST="${SCRIPT_DIR}/substrate-frontmatter-allowlist.txt"
+  FM_SKIP=0
+  if [ -f "$FRONTMATTER_ALLOWLIST" ]; then
+    REPO_REL=$(echo "$FILE_PATH" | sed -E 's|^.*/(\.claude/.*)$|\1|')
+    # Allowlist line shape: <repo-rel-path>|<grace-until ISO 8601>. Allow either
+    # plain path (legacy) or path|date (matches testing-tier-enforce-allowlist).
+    while IFS= read -r LINE; do
+      # Strip comments and blank lines
+      LINE_TRIM=$(echo "$LINE" | sed -E 's/[[:space:]]*#.*$//' | xargs)
+      [ -z "$LINE_TRIM" ] && continue
+      LINE_PATH=$(echo "$LINE_TRIM" | cut -d'|' -f1 | xargs)
+      LINE_DATE=$(echo "$LINE_TRIM" | cut -d'|' -f2 -s | xargs)
+      if [ "$LINE_PATH" = "$REPO_REL" ]; then
+        # Grace window check: if a date is supplied, only honor while current
+        if [ -n "$LINE_DATE" ]; then
+          NOW_ISO=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+          if [ "$NOW_ISO" \< "$LINE_DATE" ] || [ "$NOW_ISO" = "$LINE_DATE" ]; then
+            FM_SKIP=1
+          fi
+        else
+          FM_SKIP=1
+        fi
+        break
+      fi
+    done < "$FRONTMATTER_ALLOWLIST"
+  fi
+
+  if [ "$FM_SKIP" = "0" ]; then
+    # Run frontmatter validation via python3 yaml
+    FM_RESULT=$(echo "$FUTURE_CONTENT" | SURFACE_NAME="$SURFACE" FILE_PATH_ENV="$FILE_PATH" python3 -c "
+import os, sys, re
+try:
+    import yaml
+except ImportError:
+    # python yaml not available; pass without validation
+    print('OK')
+    sys.exit(0)
+
+content = sys.stdin.read()
+surface = os.environ.get('SURFACE_NAME', '')
+
+# Find frontmatter — opens with --- on line 1, closes with --- on a later line.
+m = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
+if not m:
+    # No frontmatter.
+    # Per goal 2026-08-13d Piece 2 (bassclef-upstream#1200):
+    # substrate primitive classes require tier tag; missing frontmatter
+    # means the tier tag cannot be present, so BLOCK. Backfill via prior
+    # commits brought all 488 primitives to 100% tier coverage.
+    if surface in ('skill', 'rule', 'luminary', 'agent', 'adr', 'standard'):
+        print('MISSING_FRONTMATTER')
+    else:
+        # Non-primitive surfaces with no frontmatter — pass through.
+        print('OK')
+    sys.exit(0)
+
+fm_text = m.group(1)
+try:
+    fm = yaml.safe_load(fm_text)
+except yaml.YAMLError as e:
+    print(f'MALFORMED_YAML:{str(e).splitlines()[0]}')
+    sys.exit(0)
+
+if not isinstance(fm, dict):
+    print('MALFORMED_YAML:frontmatter is not a mapping')
+    sys.exit(0)
+
+# Required fields per surface
+# Per goal 2026-08-13d Piece 2 — tier extended to all 6 .md primitive classes.
+# hook (.sh) is handled in a separate bash pre-check above (different extraction path).
+required = {
+    'skill': ['name', 'description', 'tier'],
+    'rule': ['tier'],
+    'luminary': ['tier'],
+    'agent': ['tier'],
+    'adr': ['tier'],
+    'standard': ['tier'],
+}.get(surface, [])
+
+for field in required:
+    if field not in fm:
+        print(f'MISSING_REQUIRED:{field}')
+        sys.exit(0)
+    val = fm[field]
+    if val is None or (isinstance(val, str) and not val.strip()):
+        print(f'MISSING_REQUIRED:{field}')
+        sys.exit(0)
+
+# tier value validation (WU-1: bassclef-upstream→bassclef export gate)
+# Values per standards/tier-tag-schema.md.
+# 'private' kept accepted as deprecated alias for 'upstream' per ADR-031
+# we-dont-break-adopters compat-shim discipline.
+if 'tier' in fm:
+    tier_val = fm['tier']
+    if tier_val not in ('upstream', 'private', 'lite', 'standard', 'standard-pro', 'ultra'):
+        print(f'INVALID_TIER:{tier_val} (expected upstream|lite|standard|standard-pro|ultra; private accepted as deprecated alias)')
+        sys.exit(0)
+
+# Recognized optional fields per surface
+recognized = {
+    'skill': {
+        'name', 'description', 'args', 'composes_baseline', 'composes_with',
+        'depends_on', 'deprecated', 'deprecated_decision', 'deprecated_in_favor_of',
+        'disable_friction_check', 'disable_model_invocation', 'model_tier',
+        'modes', 'no_user_modes', 'requires', 'reserved_name_override',
+        'sizes', 'tech_stack_match', 'tier', 'tiers', 'user_invocable',
+    },
+    'rule': {
+        'description', 'composes_with', 'depends_on', 'globs', 'model_tier',
+        'tech_stack_match', 'tier',
+    },
+}.get(surface, set())
+
+unknown = [k for k in fm.keys() if k not in recognized]
+if unknown:
+    print(f'UNKNOWN_FIELDS:{\",\".join(unknown)}')
+    sys.exit(0)
+
+# bassclef#862 Gap 3 (WU-15): composes_with + depends_on targets-exist validation
+# composes_with → STRICT (BLOCK if target skill missing)
+# depends_on   → ADVISORY (warn if target missing; pass for V1)
+file_path = os.environ.get('FILE_PATH_ENV', '')
+substrate_root = ''
+if '/.claude/' in file_path:
+    substrate_root = file_path.split('/.claude/')[0]
+
+def target_resolved(name, substrate_root):
+    skill_path = f'{substrate_root}/.claude/skills/{name}/SKILL.md'
+    rule_path = f'{substrate_root}/.claude/rules/{name}.md'
+    known_config_blocks = {
+        'tech_stack', 'adopter_defaults', 'plan_tier',
+        'prose_discipline', 'longrun', 'testing',
+    }
+    return (os.path.isfile(skill_path)
+            or os.path.isfile(rule_path)
+            or name in known_config_blocks)
+
+if substrate_root and 'composes_with' in fm:
+    cw = fm['composes_with']
+    if not isinstance(cw, list):
+        print(f'COMPOSES_WITH_TYPE_ERROR:got {type(cw).__name__}, expected list')
+        sys.exit(0)
+    missing = []
+    for name in cw:
+        if not isinstance(name, str):
+            print(f'COMPOSES_WITH_TYPE_ERROR:list item is {type(name).__name__}, expected string')
+            sys.exit(0)
+        skill_path = f'{substrate_root}/.claude/skills/{name}/SKILL.md'
+        if not os.path.isfile(skill_path):
+            missing.append(name)
+    if missing:
+        print(f'COMPOSES_WITH_MISSING:{\",\".join(missing)}')
+        sys.exit(0)
+
+if substrate_root and 'depends_on' in fm:
+    do = fm['depends_on']
+    if isinstance(do, list):
+        missing = [n for n in do
+                   if isinstance(n, str) and not target_resolved(n, substrate_root)]
+        if missing:
+            print(f'DEPENDS_ON_MISSING:{\",\".join(missing)}')
+            sys.exit(0)
+
+print('OK')
+" 2>/dev/null)
+
+    case "$FM_RESULT" in
+      OK|"")
+        # Pass — no violation
+        ;;
+      MISSING_FRONTMATTER)
+        VIOLATION="Frontmatter required for $SURFACE files but none found."
+        LINE_REF="top of file"
+        SUGGESTED_FIX="Add a YAML frontmatter block opening with --- on line 1. See standards/frontmatter-schema.md for required + recognized fields."
+        ;;
+      MALFORMED_YAML:*)
+        REASON=$(echo "$FM_RESULT" | sed 's/^MALFORMED_YAML://')
+        VIOLATION="Frontmatter YAML is malformed: $REASON"
+        LINE_REF="frontmatter block"
+        SUGGESTED_FIX="Fix YAML syntax. Common causes: unquoted colons in values, mismatched indentation, trailing tabs. See standards/frontmatter-schema.md."
+        ;;
+      MISSING_REQUIRED:*)
+        FIELD=$(echo "$FM_RESULT" | sed 's/^MISSING_REQUIRED://')
+        VIOLATION="Frontmatter missing required field for $SURFACE: \`$FIELD\`"
+        LINE_REF="frontmatter $FIELD: field"
+        if [ "$FIELD" = "tier" ]; then
+          SUGGESTED_FIX="Add \`tier: standard\` to the frontmatter. Values: upstream | lite | standard | standard-pro | ultra. See standards/tier-tag-schema.md."
+        else
+          SUGGESTED_FIX="Add \`$FIELD:\` with a non-empty value to the frontmatter. See standards/frontmatter-schema.md for the full schema."
+        fi
+        ;;
+      INVALID_TIER:*)
+        REASON=$(echo "$FM_RESULT" | sed 's/^INVALID_TIER://')
+        VIOLATION="Frontmatter \`tier:\` has invalid value — $REASON"
+        LINE_REF="frontmatter tier: field"
+        SUGGESTED_FIX="Use one of: private (never ships) | basic (ships first release) | premium (ships after promotion) | public (legacy/already-shipped). See standards/tier-tag-schema.md (WU-1)."
+        ;;
+      UNKNOWN_FIELDS:*)
+        # WARN only — not a block. Surface to stderr but exit 0.
+        FIELDS=$(echo "$FM_RESULT" | sed 's/^UNKNOWN_FIELDS://')
+        echo "substrate-clarity-gate: WARN — unknown frontmatter field(s) in $SURFACE [$REPO_REL]: $FIELDS" >&2
+        echo "  Recognized fields documented in standards/frontmatter-schema.md." >&2
+        echo "  If this is a new substrate field, propose it via /promote substrate-evolution." >&2
+        ;;
+      COMPOSES_WITH_TYPE_ERROR:*)
+        REASON=$(echo "$FM_RESULT" | sed 's/^COMPOSES_WITH_TYPE_ERROR://')
+        VIOLATION="composes_with must be a YAML list of skill names ($REASON)."
+        LINE_REF="frontmatter composes_with: field"
+        SUGGESTED_FIX="Format: composes_with: [skill-name-1, skill-name-2]. See .claude/rules/skill-composition-declarations.md for semantics."
+        ;;
+      COMPOSES_WITH_MISSING:*)
+        NAMES=$(echo "$FM_RESULT" | sed 's/^COMPOSES_WITH_MISSING://')
+        VIOLATION="composes_with names skills that don't exist: $NAMES"
+        LINE_REF="frontmatter composes_with: field"
+        SUGGESTED_FIX="Each name must match a .claude/skills/<name>/SKILL.md file. Likely a typo. List available skills: ls .claude/skills/. See .claude/rules/skill-composition-declarations.md."
+        ;;
+      DEPENDS_ON_MISSING:*)
+        # ADVISORY — pass with warning to stderr.
+        NAMES=$(echo "$FM_RESULT" | sed 's/^DEPENDS_ON_MISSING://')
+        echo "substrate-clarity-gate: ADVISORY — depends_on names targets without a matching skill, rule, or known config-block: $NAMES" >&2
+        echo "  Recognized config blocks: tech_stack, adopter_defaults, plan_tier, prose_discipline, longrun, testing." >&2
+        echo "  Per .claude/rules/skill-composition-declarations.md — V1 advisory tier; strict enforcement deferred." >&2
+        ;;
+    esac
+  fi
+fi
+
+# If frontmatter check fired a violation, skip the per-surface dispatch — fix
+# the frontmatter first.
+if [ -z "$VIOLATION" ]; then
+
+case "$SURFACE" in
+  skill)
+    # Extract description from frontmatter
+    DESCRIPTION=$(echo "$FUTURE_CONTENT" | awk '
+      /^---$/{c++; next}
+      c==1 && /^description:/ {
+        sub(/^description:[[:space:]]*/, "")
+        # Handle quoted descriptions (single or double quotes)
+        if (/^".*"$/) { gsub(/^"|"$/, "") }
+        else if (/^'\''.*'\''$/) { gsub(/^'\''|'\''$/, "") }
+        print
+        exit
+      }
+    ')
+
+    if [ -z "$DESCRIPTION" ]; then
+      # No description field at all — not a violation per this rule (other
+      # rules cover required-field). Pass.
+      exit 0
+    fi
+
+    DESC_LEN=${#DESCRIPTION}
+
+    # Check 1: length
+    if [ "$DESC_LEN" -gt 280 ]; then
+      VIOLATION="Description exceeds 280 chars (got $DESC_LEN)."
+      LINE_REF="frontmatter description: field"
+      SUGGESTED_FIX="Use verb + outcome + how + why-distinct ≤280 chars total. See worked examples in .claude/rules/skill-description-clarity.md"
+    fi
+
+    # Check 2: verb-first opener (skip if check 1 already fired)
+    if [ -z "$VIOLATION" ]; then
+      FIRST_WORD=$(echo "$DESCRIPTION" | awk '{print $1}' | tr -d '[:punct:]' | tr '[:upper:]' '[:lower:]')
+      # Whitelist of imperative starters (extensible)
+      VERB_FIRST=0
+      for verb in show run turn create build take write reads generate compose audit launch render fire propose make produce dispatch read scan check verify validate enforce bootstrap install update extend extract ship pause start stop print emit publish capture flag detect orchestrate manage track surface route plan diagnose decompose review compose-with frame mock preview retrieve sync configure deploy invoke kill enumerate filter inspect sweep explain browse scaffold load draft convert declare get set pick choose name handle manage rename pull push kick fetch list count parse format save store post send drop add remove submit accept reject pass fail open close reopen claim release commit log copy move; do
+        if [ "$FIRST_WORD" = "$verb" ]; then
+          VERB_FIRST=1
+          break
+        fi
+      done
+      if [ "$VERB_FIRST" -eq 0 ]; then
+        VIOLATION="Description doesn't open with a verb. First word: '$FIRST_WORD'."
+        LINE_REF="frontmatter description: field"
+        SUGGESTED_FIX="Open with imperative: Show, Run, Turn, Create, Build, Compose, etc. Avoid noun-first openers like 'Composer for...' or 'Tier-preset...'."
+      fi
+    fi
+
+    # Check 3: jargon detection (BLOCK — flipped from ADVISORY in bassclef#496
+    # LR6.5). Description must use plain language; bassclef jargon names
+    # internal substrate concepts that engineers + boss audiences don't have
+    # context for. Per `.claude/rules/skill-description-clarity.md`
+    # substitution table.
+    #
+    # Single-word terms checked with word-boundary regex. The "compose"
+    # family also catches the verb-form "Composes into" / "composes with"
+    # that triggered bassclef#496 (/roadmap-reconcile shipped under 280c
+    # but with "Composes into /longrun prep Step 0.5").
+    if [ -z "$VIOLATION" ]; then
+      JARGON=""
+      for term in 'composer' 'primitive' 'tier-preset' 'load-bearing' 'blast radius' 'compose-with' 'scope-bounded' 'operationalize' 'substrate'; do
+        if echo "$DESCRIPTION" | grep -qiE "\\b$term\\b"; then
+          JARGON="${JARGON}${term} "
+        fi
+      done
+      # Compose-verb forms used as methodology references ("Composes into",
+      # "composes with", "Composing the X chain"). The plain "compose" verb
+      # by itself (e.g., "compose a chronicle") isn't flagged.
+      if echo "$DESCRIPTION" | grep -qiE '\bcomposes? (into|with|across|over)\b'; then
+        JARGON="${JARGON}composes-into-or-with "
+      fi
+      if [ -n "$JARGON" ]; then
+        VIOLATION="Description contains bassclef jargon: $JARGON"
+        LINE_REF="frontmatter description: field"
+        SUGGESTED_FIX="Substitute plain English per .claude/rules/skill-description-clarity.md table. Examples: 'composer' → 'runs' / 'chains' / 'combines'; 'primitive' → 'building block'; 'load-bearing' → 'required'; 'substrate' → 'system' / 'framework'; 'Composes into X' → name what the skill produces and where it slots in (e.g., 'used by /longrun prep' or just drop the methodology reference)."
+      fi
+    fi
+
+    # Check 4 (bassclef#1249): Skill-body INSTEAD-block discipline.
+    # Same shape as rule + luminary blocks below: every \b(don't|never|avoid)\b
+    # (case-insensitive, word-boundary) requires INSTEAD/Instead within 5 lines
+    # AFTER the trigger. Code blocks are exempt. Inline pairing passes.
+    # Allowlist (.claude/hooks/substrate-clarity-allowlist.txt) grandfathers
+    # existing skill bodies with a 60-day grace window.
+    if [ -z "$VIOLATION" ]; then
+      UNPAIRED=$(echo "$FUTURE_CONTENT" | awk '
+        BEGIN { trigger_line = 0; trigger_text = ""; }
+        {
+          line_num++
+          line = $0
+          if (line ~ /^```/) { in_code = !in_code; next }
+          if (in_code) next
+
+          if (trigger_line > 0) {
+            if (line_num - trigger_line <= 5) {
+              if (line ~ /INSTEAD/ || line ~ /^Instead[ ,:]/) {
+                trigger_line = 0
+                trigger_text = ""
+              }
+            } else {
+              print "L" trigger_line ": " trigger_text
+              trigger_line = 0
+              trigger_text = ""
+            }
+          }
+
+          if (trigger_line == 0) {
+            if (line ~ /INSTEAD/ || line ~ /^Instead[ ,:]/) next
+            lower = tolower(line)
+            if (lower ~ /(^|[^a-z])(don.t|never|avoid)([^a-z]|$)/) {
+              trigger_line = line_num
+              trigger_text = substr(line, 1, 80)
+            }
+          }
+        }
+        END {
+          if (trigger_line > 0) {
+            print "L" trigger_line ": " trigger_text
+          }
+        }
+      ')
+
+      if [ -n "$UNPAIRED" ]; then
+        COUNT=$(echo "$UNPAIRED" | wc -l | tr -d ' ')
+        VIOLATION="Skill body has $COUNT unpaired don't/never/avoid (no literal INSTEAD within 5 lines)."
+        LINE_REF=$(echo "$UNPAIRED" | head -1 | cut -d: -f1)
+        SUGGESTED_FIX="Pair each negation with a literal INSTEAD block within 5 lines. Example: 'Don't X.' followed by 'INSTEAD: do Y.' Per rule .claude/rules/context-engineering.md §INSTEAD-block pattern. To grandfather a legacy file: add path to .claude/hooks/substrate-clarity-allowlist.txt with bassclef#1249 reference."
+      fi
+    fi
+
+    # Check 5 (bassclef-upstream#799): ADR-044 section-presence — V1 ADVISORY.
+    # Scans SKILL body for the 13 required ## section headers named at
+    # ADR-044 L55-L82. V1 emits ADVISORY to stderr; exit 0 (does not
+    # block). V2 BLOCK flip deferred past 2026-10-31 per
+    # we-dont-break-adopters grace window (separate follow-on ticket).
+    if [ -z "$VIOLATION" ]; then
+      MISSING_SECTIONS=""
+      for SECTION in \
+        "What you get" \
+        "When to use it" \
+        "When NOT to use" \
+        "FAQ" \
+        "Details below the fold" \
+        "Examples" \
+        "Anti-patterns and INSTEAD" \
+        "Composes with" \
+        "Distinct from" \
+        "Rules" \
+        "Test cases" \
+        "Sources read" \
+        "Why this skill exists"
+      do
+        if ! echo "$FUTURE_CONTENT" | grep -qE "^## ${SECTION}"; then
+          MISSING_SECTIONS="${MISSING_SECTIONS}${SECTION}|"
+        fi
+      done
+      if [ -n "$MISSING_SECTIONS" ]; then
+        echo "[substrate-clarity-gate: ADVISORY (ADR-044 section-presence) — $FILE_PATH]" >&2
+        echo "  Missing required section(s) per ADR-044 L53-L82:" >&2
+        echo "$MISSING_SECTIONS" | tr '|' '\n' | sed '/^$/d' | sed 's/^/    - ## /' >&2
+        echo "  V1 advisory; V2 BLOCK flip deferred past 2026-10-31 per .claude/rules/we-dont-break-adopters.md grace window." >&2
+      fi
+    fi
+    ;;
+
+  rule)
+    # Rule INSTEAD-block discipline: every \b(don't|never|avoid)\b
+    # (case-insensitive, word-boundary) requires INSTEAD/Instead within
+    # 5 lines AFTER the trigger. Multi-line scan via awk.
+    UNPAIRED=$(echo "$FUTURE_CONTENT" | awk '
+      BEGIN { trigger_line = 0; trigger_text = ""; }
+      {
+        line_num++
+        line = $0
+        # Skip code blocks (between ``` markers) — quoted prose is exempt
+        if (line ~ /^```/) {
+          in_code = !in_code
+          next
+        }
+        if (in_code) next
+
+        # If we are tracking a trigger and find INSTEAD within window: clear
+        # Require INSTEAD (all caps) OR line-start Instead — strict bassclef
+        # pattern. Mid-prose "instead" doesnt qualify (the rule discipline
+        # is to put a deliberate INSTEAD: substitute, not natural language).
+        if (trigger_line > 0) {
+          if (line_num - trigger_line <= 5) {
+            if (line ~ /INSTEAD/ || line ~ /^Instead[ ,:]/) {
+              trigger_line = 0
+              trigger_text = ""
+            }
+          } else {
+            # Window expired without INSTEAD — emit unpaired
+            print "L" trigger_line ": " trigger_text
+            trigger_line = 0
+            trigger_text = ""
+          }
+        }
+
+        # Detect new trigger (only if not already tracking)
+        if (trigger_line == 0) {
+          # Skip lines that already contain INSTEAD/line-start Instead on the
+          # same line (paired inline)
+          if (line ~ /INSTEAD/ || line ~ /^Instead[ ,:]/) next
+
+          # Check for trigger words. Use lowercased copy for matching.
+          lower = tolower(line)
+          if (lower ~ /(^|[^a-z])(don.t|never|avoid)([^a-z]|$)/) {
+            trigger_line = line_num
+            trigger_text = substr(line, 1, 80)
+          }
+        }
+      }
+      END {
+        # Final pending trigger at EOF
+        if (trigger_line > 0) {
+          print "L" trigger_line ": " trigger_text
+        }
+      }
+    ')
+
+    if [ -n "$UNPAIRED" ]; then
+      # v1 BLOCK (flipped 2026-05-07 in Phase I — Plain English Sweep).
+      # Allowlist grandfathers existing violators per bassclef#374
+      # audit; net-new edits to non-allowlisted rules MUST pair every
+      # don't/never/avoid with a literal INSTEAD within 5 lines.
+      COUNT=$(echo "$UNPAIRED" | wc -l | tr -d ' ')
+      VIOLATION="Rule has $COUNT unpaired don't/never/avoid (no literal INSTEAD within 5 lines)."
+      LINE_REF=$(echo "$UNPAIRED" | head -1 | cut -d: -f1)
+      SUGGESTED_FIX="Pair each negation with a literal INSTEAD block within 5 lines. Example: 'Don't X.' followed by 'INSTEAD: do Y.' Per rule .claude/rules/context-engineering.md §INSTEAD-block pattern. To grandfather a legacy file: add path to .claude/hooks/substrate-clarity-allowlist.txt with bassclef#374 reference."
+    fi
+    ;;
+
+  luminary)
+    # Luminary INSTEAD-block discipline: same as rule check (v0 ADVISORY).
+    # Plus required-sections check: every luminary should declare when to
+    # channel it + what anti-patterns mark drift.
+    UNPAIRED=$(echo "$FUTURE_CONTENT" | awk '
+      BEGIN { trigger_line = 0; trigger_text = ""; }
+      {
+        line_num++
+        line = $0
+        if (line ~ /^```/) { in_code = !in_code; next }
+        if (in_code) next
+
+        if (trigger_line > 0) {
+          if (line_num - trigger_line <= 5) {
+            if (line ~ /INSTEAD/ || line ~ /^Instead[ ,:]/) {
+              trigger_line = 0
+              trigger_text = ""
+            }
+          } else {
+            print "L" trigger_line ": " trigger_text
+            trigger_line = 0
+            trigger_text = ""
+          }
+        }
+
+        if (trigger_line == 0) {
+          if (line ~ /INSTEAD/ || line ~ /^Instead[ ,:]/) next
+          lower = tolower(line)
+          if (lower ~ /(^|[^a-z])(don.t|never|avoid)([^a-z]|$)/) {
+            trigger_line = line_num
+            trigger_text = substr(line, 1, 80)
+          }
+        }
+      }
+      END {
+        if (trigger_line > 0) {
+          print "L" trigger_line ": " trigger_text
+        }
+      }
+    ')
+
+    if [ -n "$UNPAIRED" ]; then
+      # v1 BLOCK (flipped 2026-05-07 in Phase I — Plain English Sweep).
+      # Allowlist grandfathers existing violators per bassclef#373
+      # audit; net-new edits to non-allowlisted luminaries MUST pair
+      # every don't/never/avoid with a literal INSTEAD within 5 lines.
+      COUNT=$(echo "$UNPAIRED" | wc -l | tr -d ' ')
+      VIOLATION="Luminary has $COUNT unpaired don't/never/avoid (no literal INSTEAD within 5 lines)."
+      LINE_REF=$(echo "$UNPAIRED" | head -1 | cut -d: -f1)
+      SUGGESTED_FIX="Pair each negation with a literal INSTEAD block within 5 lines. Example: 'Don't X.' followed by 'INSTEAD: do Y.' Per rule .claude/rules/context-engineering.md §INSTEAD-block pattern. To grandfather a legacy file: add path to .claude/hooks/substrate-clarity-allowlist.txt with bassclef#373 reference. Brand-negation luminaries (whose signature IS negation) get per-luminary treatment in the audit."
+    fi
+
+    # Required sections check (kept as ADVISORY — section presence is
+    # documentation discipline, not a blocking concern. bassclef#373
+    # audit decides whether to promote this to BLOCK separately).
+    if [ -z "$VIOLATION" ]; then
+      MISSING_SECTIONS=""
+      if ! echo "$FUTURE_CONTENT" | grep -qiE "^#{1,6}[[:space:]]+when[[:space:]]+to[[:space:]]+channel"; then
+        MISSING_SECTIONS="${MISSING_SECTIONS}'When to channel this luminary' section, "
+      fi
+      if ! echo "$FUTURE_CONTENT" | grep -qiE "^#{1,6}[[:space:]]+anti-patterns?\\b"; then
+        MISSING_SECTIONS="${MISSING_SECTIONS}'Anti-patterns' section, "
+      fi
+      if [ -n "$MISSING_SECTIONS" ]; then
+        MISSING_SECTIONS="${MISSING_SECTIONS%, }"
+        echo "[substrate-clarity-gate: ADVISORY — $FILE_PATH missing $MISSING_SECTIONS]" >&2
+        echo "[advisory only; documentation discipline, not blocking]" >&2
+      fi
+    fi
+    ;;
+
+  chronicle|iteration_bet|journal_entry|decomposition|whereami)
+    # Phase II WU-7b — broader plain-English discipline. Jargon check
+    # honors SURFACE_TIER:
+    # - chronicle / iteration_bet / decomposition → strict (BLOCK on jargon)
+    #   after the #303 audit emptied the grandfathered allowlist.
+    # - journal_entry → advisory (voice trumps rule on personal narrative).
+    # - whereami → advisory V1 (bassclef-upstream bet 2026-07-04a WU-1).
+    # Long-sentence + passive-voice stay advisory on all surfaces; those
+    # are soft signals, not BLOCK-worthy.
+    NOTICES=""
+
+    # Check 1 — bassclef-internal jargon
+    # 'substrate' is on the allowlist per bassclef#763 — keep it OUT of
+    # the BLOCK list here so historical narrative referencing the framework
+    # by name does not trip the gate.
+    JARGON=""
+    for term in 'composer' 'primitive' 'tier-preset' 'load-bearing' 'blast radius' 'compose-with' 'scope-bounded' 'operationalize' 'stuck-signal' 'substrate-defect'; do
+      if echo "$FUTURE_CONTENT" | grep -qiE "\\b$term\\b"; then
+        JARGON="${JARGON}${term} "
+      fi
+    done
+    if [ -n "$JARGON" ]; then
+      if [ "$SURFACE_TIER" = "strict" ]; then
+        VIOLATION="bassclef-internal jargon found in ${SURFACE}: ${JARGON}— rewrite in plain English per standards/bassclef-internal-jargon.md"
+      else
+        NOTICES="${NOTICES}bassclef-internal jargon found: ${JARGON}\\n"
+      fi
+    fi
+
+    # Check 2 — long sentences (>50 words) — advisory only on these surfaces
+    # Strip frontmatter, strip code blocks, then count words per sentence.
+    LONG_SENTENCES=$(echo "$FUTURE_CONTENT" | awk '
+      BEGIN { in_frontmatter = 0; in_code = 0; long_count = 0 }
+      /^---$/ {
+        if (NR == 1) { in_frontmatter = 1; next }
+        if (in_frontmatter) { in_frontmatter = 0; next }
+      }
+      in_frontmatter { next }
+      /^```/ { in_code = !in_code; next }
+      in_code { next }
+      {
+        # Skip table rows + headers (markdown noise that fragments sentences)
+        if ($0 ~ /^[[:space:]]*\|/) next
+        if ($0 ~ /^[[:space:]]*#/) next
+        # Split on sentence terminators
+        n = split($0, parts, /[.!?]+[[:space:]]+/)
+        for (i = 1; i <= n; i++) {
+          part = parts[i]
+          gsub(/`[^`]*`/, "", part)  # strip inline code
+          gsub(/^[[:space:]]+|[[:space:]]+$/, "", part)
+          if (length(part) == 0) continue
+          word_count = split(part, words, /[[:space:]]+/)
+          if (word_count > 50) long_count++
+        }
+      }
+      END { print long_count }
+    ')
+    if [ "$LONG_SENTENCES" -gt 0 ]; then
+      NOTICES="${NOTICES}${LONG_SENTENCES} sentence(s) over 50 words — break into shorter sentences\\n"
+    fi
+
+    # Check 3 — passive voice (advisory) — simple regex; conservative
+    PASSIVE=$(echo "$FUTURE_CONTENT" | grep -ciE '\b(was|were|been|being)[[:space:]]+[a-z]+ed[[:space:]]+by\b' || true)
+    if [ "$PASSIVE" -gt 0 ]; then
+      NOTICES="${NOTICES}${PASSIVE} passive-voice construction(s) detected (e.g., 'X was Y-ed by Z') — prefer active voice\\n"
+    fi
+
+    if [ -n "$NOTICES" ]; then
+      echo "[substrate-clarity-gate: ADVISORY ($SURFACE) — $FILE_PATH]" >&2
+      echo -e "$NOTICES" >&2
+      echo "[advisory only; per .claude/rules/plain-english-discipline.md — voice trumps strict rule on narrative surfaces]" >&2
+    fi
+    # Do not set VIOLATION
+    ;;
+esac
+
+# === Soft-INSTEAD audit (V1 ADVISORY — bassclef-upstream#375) ===
+# Per @luminary alistair-cockburn (MUST/SHALL precision) + @luminary tony-hoare
+# (preconditions absolute). Scans rule/skill/luminary surfaces for soft escape
+# clauses that hand the agent an out from a hard MUST contract.
+# V1: ADVISORY stderr notice. V2 (deferred, after calibration cycle): BLOCK on
+# net-new violations; allowlist for existing.
+# Surfaces scanned: skill, rule, luminary, adr (strict surfaces).
+case "$SURFACE" in
+  skill|rule|luminary|adr)
+    # Strip code blocks + inline backticks from FUTURE_CONTENT before scan
+    # (matches scripts/soft-instead-audit.sh behavior — false-positive guard
+    # on quoted examples + pattern mentions).
+    SOFT_INSTEAD_STRIPPED=$(echo "$FUTURE_CONTENT" | awk '
+      BEGIN { in_code = 0 }
+      /^```/ { in_code = !in_code; next }
+      !in_code {
+        gsub(/`[^`]*`/, "")
+        print
+      }
+    ')
+    SOFT_HITS=""
+    for pattern in 'OR hand-roll' 'OR write inline' 'OR compose by hand' 'if available' 'if at hand' 'when at hand' 'when available' 'if the skill is not' 'when the skill is not'; do
+      if echo "$SOFT_INSTEAD_STRIPPED" | grep -qiF "$pattern"; then
+        SOFT_HITS="${SOFT_HITS}${pattern} "
+      fi
+    done
+    if [ -n "$SOFT_HITS" ]; then
+      echo "[substrate-clarity-gate: ADVISORY (soft-INSTEAD) — $FILE_PATH]" >&2
+      echo "  Soft-INSTEAD patterns found: $SOFT_HITS" >&2
+      echo "  Per @luminary alistair-cockburn: INSTEAD names a MUST contract, not a soft alternative." >&2
+      echo "  Cure: rewrite as MUST + explicit alternative-path (BLOCK when prereq missing)." >&2
+      echo "  See: scripts/soft-instead-audit.sh + architecture/audits/2026-06-26-soft-instead-clauses.md" >&2
+      echo "  V1 advisory; V2 (deferred) BLOCKs net-new violations." >&2
+    fi
+    ;;
+esac
+
+# === Claim-shape scan (V1 ADVISORY — bet 2026-07-01e WU-4) ===
+# Per bassclef-upstream#582 (R8 class extension to file-write surface) +
+# .claude/rules/assert-only-after-verify.md. Fires on rule / chronicle /
+# iteration_bet / adr surfaces. Detects paragraphs that read as claims
+# (multiple modal words: must, should, always, never, wrong, broken, will)
+# without a nearby citation pattern (file path, ticket #, git SHA,
+# @luminary slug). Skips journal_entry (personal voice) + skill (WU-4 out
+# of scope) + luminary + decomposition.
+#
+# V1 ADVISORY: emits stderr notice; does not block. V2 (deferred, after
+# calibration cycle): flip specific paragraph patterns to BLOCK.
+case "$SURFACE" in
+  rule|chronicle|iteration_bet|adr)
+    CLAIM_HITS=$(echo "$FUTURE_CONTENT" | python3 -c "
+import sys, re
+
+content = sys.stdin.read()
+
+# Strip frontmatter
+m = re.match(r'^---\n.*?\n---\n', content, re.DOTALL)
+if m:
+    content = content[m.end():]
+
+# Strip fenced code blocks
+content = re.sub(r'\`\`\`.*?\`\`\`', '', content, flags=re.DOTALL)
+
+# Split into paragraphs (blank-line separated)
+paragraphs = re.split(r'\n\s*\n', content)
+
+modal_re = re.compile(r'\b(must|should|always|never|wrong|broken|will)\b', re.IGNORECASE)
+# Citation patterns:
+#   file paths: .md .sh .json .yml .yaml .py .ts .tsx
+#   ticket refs: #NNN, bassclef#NNN, sunj-labs/, poa#NNN, GH#NNN
+#   luminary slugs: @luminary <slug>
+#   inline backtick paths or accessors: '\`.*\`'
+#   'per ' or 'see ' followed by any word
+#   git SHA (7+ hex)
+citation_re = re.compile(
+    r'\b(?:'
+    r'[\w./-]+\.(?:md|sh|json|yml|yaml|py|ts|tsx)'
+    r'|[a-zA-Z-]*#\d{2,}'
+    r'|@luminary\s+[a-z-]+'
+    r'|per\s+[\`\w./-]+'
+    r'|see\s+[\`\w./-]+'
+    r'|sunj-labs/'
+    r'|[0-9a-f]{7,40}'
+    r')',
+    re.IGNORECASE
+)
+# Inline backtick content also counts as citation
+inline_backtick_re = re.compile(r'\`[^\`]+\`')
+
+count = 0
+for p in paragraphs:
+    p_stripped = p.strip()
+    if not p_stripped:
+        continue
+    # Skip headings and lists and blockquotes and tables
+    first_non_ws = p_stripped[0]
+    if first_non_ws in ('#', '-', '*', '|', '>'):
+        continue
+    # Numbered list
+    if re.match(r'^\d+\.\s', p_stripped):
+        continue
+    modal_count = len(modal_re.findall(p_stripped))
+    if modal_count < 2:
+        continue
+    has_citation = bool(citation_re.search(p_stripped)) or bool(inline_backtick_re.search(p_stripped))
+    if not has_citation:
+        count += 1
+
+print(count)
+" 2>/dev/null)
+    if [ -n "$CLAIM_HITS" ] && [ "$CLAIM_HITS" -gt 0 ]; then
+      echo "[substrate-clarity-gate: ADVISORY (claim-shape) — $FILE_PATH]" >&2
+      echo "  $CLAIM_HITS paragraph(s) read as claims without cited source (2+ modal words, zero citation patterns nearby)." >&2
+      echo "  Per .claude/rules/assert-only-after-verify.md + bassclef-upstream#582 (R8 at file-write surface)." >&2
+      echo "  V1 advisory; V2 deferred after calibration cycle." >&2
+    fi
+    ;;
+esac
+
+fi  # close the "skip per-surface dispatch if frontmatter check fired"
+
+# === Rewrite-check heuristics (V1 ADVISORY — goal 25e Path A) ===
+# Sources lib/rewrite-check.sh and runs 6 heuristics on the future content:
+# passive voice, hyphen compounds, sentence length, non-SVO openers,
+# noun stacks, adverb density. Grounded in UK ONS + NN/g + US Federal
+# Plain Language + Hemingway.
+#
+# V1 ADVISORY: emits stderr notice; does not block. Fires on 17 surfaces
+# (rule + luminary + adr + skill + iteration_bet + decomposition + chronicle
+# from existing scope + 15 new SDLC artifact surfaces per Path A). Skips
+# journal_entry (personal voice) + whereami (frontmatter-heavy).
+# V2 flip after calibration cycle.
+case "$SURFACE" in
+  journal_entry|whereami)
+    # Skip — narrative voice / frontmatter-heavy content
+    ;;
+  *)
+    REWRITE_LIB="$(dirname "$0")/../../lib/rewrite-check.sh"
+    if [ -f "$REWRITE_LIB" ]; then
+      # Write FUTURE_CONTENT to temp file for heuristic
+      REWRITE_TMP=$(mktemp 2>/dev/null)
+      if [ -n "$REWRITE_TMP" ]; then
+        echo "$FUTURE_CONTENT" > "$REWRITE_TMP"
+        # Source in subshell so functions don't pollute parent scope
+        HITS=$(
+          source "$REWRITE_LIB" 2>/dev/null
+          run_rewrite_checks "$REWRITE_TMP" 2>/dev/null | grep -cE "^-- "
+        )
+        if [ -n "$HITS" ] && [ "$HITS" -gt 0 ]; then
+          echo "[substrate-clarity-gate: ADVISORY (rewrite-check) — $FILE_PATH]" >&2
+          echo "  $HITS finding category/ies from lib/rewrite-check.sh — passive voice / hyphen compounds / sentence length / non-SVO openers / noun stacks / adverb density." >&2
+          echo "  For details: bash scripts/sweep-kiss-dispatch.sh --dry-run --input <(echo $FILE_PATH)" >&2
+          echo "  Per goal 25e Path A. V1 advisory; V2 BLOCK deferred until calibration." >&2
+        fi
+        rm -f "$REWRITE_TMP"
+      fi
+    fi
+    ;;
+esac
+
+# === Emit BLOCK if violation found ===
+if [ -n "$VIOLATION" ]; then
+  cat >&2 <<EOF
+
+============================================
+🛑 SUBSTRATE-CLARITY GATE — BLOCKED 🛑
+============================================
+
+File:  $FILE_PATH
+Tool:  $TOOL_NAME
+
+Violation:  $VIOLATION
+Line:       $LINE_REF
+
+Suggested fix:
+  $SUGGESTED_FIX
+
+Per rule:   .claude/rules/skill-description-clarity.md (bassclef#377)
+Per meta:   .claude/rules/context-engineering.md (bassclef#371)
+
+Override (logged):  SKIP_SUBSTRATE_CLARITY=1 <command>
+
+Allowlist (existing-violations grace):
+  .claude/hooks/substrate-clarity-allowlist.txt
+============================================
+
+EOF
+  exit 2
+fi
+
+exit 0