@thebassclef/lite 1.1.0 → 1.2.0-alpha.1

package/dist/lite/.claude/hooks/operator-private-path-check.sh

@@ -0,0 +1,203 @@
+#!/bin/bash
+# tier: lite
+# Operator-private path enforcement — Rule 3 of bassclef#739
+# Per bassclef#769 (canvas-path discipline) + bassclef#803 (persona-review extension).
+#
+# Checks: persona-review-shaped + canvas-shaped artifacts must live under
+# docs/operator-private/<artifact-type>/. Public-tree placement is explicit
+# operator request via PR label `bassclef-internal-prose-ok` (shared with
+# Rule 1 + Rule 4) OR commit footer `SKIP_OPERATOR_PRIVATE_PATH=1`.
+#
+# Shape patterns flagged outside docs/operator-private/:
+#
+#   1. Persona-review-shaped (any of):
+#      - Path matches docs/persona-reviews/**
+#      - Filename matches *-review*.md OR *-persona-review*.md
+#        AND located outside docs/operator-private/persona-reviews/
+#
+#   2. Canvas-shaped (any of):
+#      - Path matches docs/strategy/canvases/** AND filename contains canvas-related
+#        keywords (lean-canvas, value-prop-canvas, chain-of-beliefs)
+#      - Filename matches *-canvas.md OR *-chain-of-beliefs.md
+#        AND located outside docs/operator-private/canvases/
+#        AND not under templates/ or presence/install/ (scaffolds + adopter assets are public)
+#
+# Usage:
+#   bash operator-private-path-check.sh <changed-files-list>
+#
+#   <changed-files-list> is a newline-separated file of changed paths
+#   (from `git diff --name-only`).
+#
+# Optional env:
+#   PR_LABELS=label1,label2,...    — labels on the PR
+#   STRICT_MODE=1                  — force blocking even with override label
+#
+# Exit codes:
+#   0 — pass (no violations, OR violations + override label present)
+#   1 — block (violations + no override)
+#   2 — usage error
+
+set +e
+
+CHANGED_FILES="${1:-}"
+if [ -z "$CHANGED_FILES" ] || [ ! -f "$CHANGED_FILES" ]; then
+  echo "usage: $0 <changed-files-list>" >&2
+  exit 2
+fi
+
+PR_LABELS="${PR_LABELS:-}"
+STRICT_MODE="${STRICT_MODE:-0}"
+
+LABELS_NORMALIZED=$(echo "$PR_LABELS" | tr ',' '\n' | sed 's/^ *//;s/ *$//' | grep -v '^$' || true)
+
+HAS_OVERRIDE=0
+if [ "$STRICT_MODE" != "1" ]; then
+  if echo "$LABELS_NORMALIZED" | grep -qx "bassclef-internal-prose-ok"; then
+    HAS_OVERRIDE=1
+  fi
+fi
+
+PERSONA_REVIEW_VIOLATIONS=""
+CANVAS_VIOLATIONS=""
+PR_COUNT=0
+CV_COUNT=0
+
+while IFS= read -r path; do
+  [ -z "$path" ] && continue
+
+  # Skip files inside the bassclef operator-private tree
+  case "$path" in
+    docs/operator-private/*) continue ;;
+  esac
+
+  # Skip templates + distribution assets (public; used as scaffolding sources)
+  # Per bassclef-upstream#317 reorg: templates/ + presence/install/ replaced
+  # strategy/templates/ as public-scaffold homes.
+  case "$path" in
+    templates/*) continue ;;
+    presence/install/*) continue ;;
+  esac
+
+  # Skip itself + the hook test fixtures
+  case "$path" in
+    .claude/hooks/operator-private-path-check.sh) continue ;;
+    .claude/hooks/tests/operator-private-path-check.test.sh) continue ;;
+  esac
+
+  # Skip Feathers rollback snapshots of rule bodies under docs/rule-history/
+  # These are byte-identical copies of rule files; filenames match source
+  # rule names (e.g., architect-review-discipline.md) which false-positive
+  # on the persona-review regex. Landed via bassclef-upstream PR #1649.
+  case "$path" in
+    docs/rule-history/*) continue ;;
+  esac
+
+  # Skip substrate definition directories (#1700 sister). A persona review or
+  # a canvas never lives in one of these — they hold rules, luminaries, skills,
+  # agents, hooks, standards, libs and scripts, each with its own naming and
+  # tier gates. Before this narrowing the check flagged
+  # `.claude/rules/architect-review-discipline.md` (matched `-review-[a-z]+`)
+  # and `.claude/luminaries/lean-product-canvas.md` (matched `-canvas.md`),
+  # neither of which is an operator-private artifact. Named as a deferred
+  # follow-on in .claude/rules/bootstrap-pair-discipline.md.
+  #
+  # The narrowing does not weaken the rule: docs/ and strategy/ paths, where
+  # these artifacts actually live, still fire. Pinned by the negative test in
+  # .claude/hooks/tests/operator-private-path-check.test.sh.
+  case "$path" in
+    .claude/rules/*|.claude/luminaries/*|.claude/skills/*|.claude/agents/*|.claude/hooks/*) continue ;;
+    standards/*|lib/*|scripts/*) continue ;;
+  esac
+
+  filename=$(basename "$path")
+
+  # === Rule 3 Shape 1 — persona-review-shaped ===
+  case "$path" in
+    docs/persona-reviews/*)
+      PERSONA_REVIEW_VIOLATIONS="${PERSONA_REVIEW_VIOLATIONS}- \`${path}\` — under \`docs/persona-reviews/\` (legacy path; relocate to \`docs/operator-private/persona-reviews/\`)"$'\n'
+      PR_COUNT=$((PR_COUNT + 1))
+      continue
+      ;;
+  esac
+
+  # Filename pattern check for persona-review (case-insensitive)
+  if echo "$filename" | grep -qiE '(^|[-_])(persona-review|persona_review)|.*-review-[a-z]+\.md$|persona-review.*\.md$'; then
+    PERSONA_REVIEW_VIOLATIONS="${PERSONA_REVIEW_VIOLATIONS}- \`${path}\` — filename pattern matches persona-review (relocate to \`docs/operator-private/persona-reviews/\`)"$'\n'
+    PR_COUNT=$((PR_COUNT + 1))
+    continue
+  fi
+
+  # === Rule 3 Shape 2 — canvas-shaped ===
+  # Filename pattern check for canvas
+  if echo "$filename" | grep -qiE '\-lean\-canvas\.md$|\-value\-prop\-canvas\.md$|\-chain\-of\-beliefs\.md$|\-canvas\.md$'; then
+    CANVAS_VIOLATIONS="${CANVAS_VIOLATIONS}- \`${path}\` — filename pattern matches canvas-shaped (relocate to \`docs/operator-private/canvases/\`)"$'\n'
+    CV_COUNT=$((CV_COUNT + 1))
+    continue
+  fi
+
+  # Path-based: under strategy/canvases/ but not template/example
+  case "$path" in
+    strategy/canvases/*.md)
+      # Allow strategy/canvases/* only if it's the public-tree exception
+      # (verified by operator request via override label). Without override,
+      # this is a violation.
+      CANVAS_VIOLATIONS="${CANVAS_VIOLATIONS}- \`${path}\` — under \`strategy/canvases/\` (relocate to \`docs/operator-private/canvases/\` unless explicit public-tree placement)"$'\n'
+      CV_COUNT=$((CV_COUNT + 1))
+      ;;
+  esac
+
+done < "$CHANGED_FILES"
+
+TOTAL=$((PR_COUNT + CV_COUNT))
+
+if [ "$TOTAL" -eq 0 ]; then
+  echo "PASS — no operator-private path violations"
+  exit 0
+fi
+
+echo "==============================================="
+echo "Operator-private path violations (bassclef#739 Rule 3)"
+echo "==============================================="
+echo ""
+
+if [ -n "$PERSONA_REVIEW_VIOLATIONS" ]; then
+  echo "## Persona-review-shaped artifacts outside operator-private (${PR_COUNT})"
+  echo ""
+  echo "$PERSONA_REVIEW_VIOLATIONS"
+  echo ""
+fi
+
+if [ -n "$CANVAS_VIOLATIONS" ]; then
+  echo "## Canvas-shaped artifacts outside operator-private (${CV_COUNT})"
+  echo ""
+  echo "$CANVAS_VIOLATIONS"
+  echo ""
+fi
+
+echo "==============================================="
+echo "Why this rule fires:"
+echo ""
+echo "Persona-review-shaped + canvas-shaped artifacts default to"
+echo "  docs/operator-private/<artifact-type>/"
+echo "Public-tree placement is explicit operator request, not default."
+echo ""
+echo "Per bassclef#769 (canvas-path discipline) + bassclef#803 (persona-review extension):"
+echo "- Canvases live at: docs/operator-private/canvases/"
+echo "- Persona reviews live at: docs/operator-private/persona-reviews/"
+echo ""
+echo "Resolution paths:"
+echo ""
+echo "1. Relocate the file to docs/operator-private/<artifact-type>/"
+echo "   (use git mv to preserve history)"
+echo ""
+echo "2. Add label \`bassclef-internal-prose-ok\` to the PR if public-tree"
+echo "   placement is intentional (e.g., template, example, public-facing reference)."
+echo "==============================================="
+
+if [ "$HAS_OVERRIDE" -eq 1 ]; then
+  echo ""
+  echo "ADVISORY — \`bassclef-internal-prose-ok\` label present; downgraded from blocking."
+  exit 0
+fi
+
+exit 1

package/dist/lite/.claude/hooks/pattern-annotation-validate.sh

@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+# tier: lite
+# pattern-annotation-validate.sh — Layer 3 of bassclef#478 traceability.
+#
+# Fires on PreToolUse for Edit/Write/MultiEdit. When the file being written
+# is source code (src/**, scripts/**, lib/**, .claude/**) and contains
+# @pattern annotations, validate that each annotation points to an existing
+# catalog entry under patterns/<shelf>/<source>/<slug>.md. BLOCK on missing
+# catalog paths.
+#
+# Also auto-populates state/pattern-implementations/*.json manifest entries
+# via state_pattern_implementation_set accessor (post-validation).
+#
+# Override: SKIP_PATTERN_ANNOTATION=1 <command> — logged.
+
+set -euo pipefail
+
+# Read tool input from stdin (Claude Code hook protocol).
+INPUT="${1:-$(cat)}"
+
+# Skip when override is set.
+if [ "${SKIP_PATTERN_ANNOTATION:-0}" = "1" ]; then
+  echo "[pattern-annotation-validate: SKIP_PATTERN_ANNOTATION=1; bypassing]" >&2
+  exit 0
+fi
+
+# Extract tool name + file path from JSON input.
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || echo "")
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || echo "")
+NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // empty' 2>/dev/null || echo "")
+
+# Only fire on Edit/Write/MultiEdit.
+case "$TOOL_NAME" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+# Only fire on source-code paths.
+case "$FILE_PATH" in
+  */src/*|*/scripts/*|*/lib/*|*/.claude/skills/*|*/.claude/hooks/*) ;;
+  *) exit 0 ;;
+esac
+
+# Skip if file doesn't currently exist (Write of new file) AND new content
+# has no @pattern annotation — no validation needed.
+EXISTING_CONTENT=""
+if [ -f "$FILE_PATH" ]; then
+  EXISTING_CONTENT=$(cat "$FILE_PATH")
+fi
+
+# Combine existing + new content for annotation extraction (covers both
+# Write of new files and Edit of existing).
+COMBINED="${EXISTING_CONTENT}
+${NEW_CONTENT}"
+
+# Extract @pattern annotations: match `@pattern\s+(patterns/...)`.
+ANNOTATIONS=$(echo "$COMBINED" | grep -oE '@pattern[[:space:]]+patterns/[a-z0-9_-]+/[a-z0-9_-]+/[a-z0-9_-]+\.md' || true)
+
+if [ -z "$ANNOTATIONS" ]; then
+  exit 0  # No annotations; nothing to validate.
+fi
+
+# Get repo root.
+REPO_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+# For each annotation, check the catalog path exists.
+INVALID=""
+while IFS= read -r line; do
+  # Extract the catalog path from `@pattern patterns/...`
+  pattern_path=$(echo "$line" | sed -E 's/.*@pattern[[:space:]]+(patterns\/[a-z0-9_-]+\/[a-z0-9_-]+\/[a-z0-9_-]+\.md).*/\1/')
+  if [ ! -f "$REPO_ROOT/$pattern_path" ]; then
+    INVALID="${INVALID}${pattern_path}\n"
+  fi
+done <<< "$ANNOTATIONS"
+
+if [ -n "$INVALID" ]; then
+  cat >&2 <<EOF
+============================================
+🛑 PATTERN-ANNOTATION GATE — BLOCKED 🛑
+============================================
+
+File:  $FILE_PATH
+Tool:  $TOOL_NAME
+
+Violation:  @pattern annotation references catalog path that doesn't exist.
+
+Missing catalog entries:
+$(echo -e "$INVALID")
+
+Resolution paths:
+  1. Fix the annotation to point at an existing catalog entry (preferred).
+  2. Run /agent-research-spawn to add the missing entry, then write.
+  3. Override (logged):  SKIP_PATTERN_ANNOTATION=1 <command>
+
+Per rule:    .claude/rules/pattern-annotation.md
+Per ticket:  bassclef#478 Layer 3
+============================================
+EOF
+  exit 3  # Hook BLOCK exit code.
+fi
+
+# Validation passed; auto-populate manifest entries.
+# (Best-effort; failures here are non-blocking.)
+#
+# Filter ephemeral paths before writing to manifest. The auto-populate path
+# uses ${FILE_PATH#$REPO_ROOT/} to compute a relative path; if FILE_PATH is
+# outside REPO_ROOT (e.g., test fixtures under /tmp or /var/folders), the
+# substitution doesn't strip and the absolute path becomes the manifest key.
+# That leaks ephemeral paths into git-tracked state. Skip these.
+# Override: SKIP_PATTERN_ANNOTATION=1 (already handled above).
+case "$FILE_PATH" in
+  /tmp/*|/var/folders/*)
+    # Test fixture path; skip manifest write.
+    exit 0
+    ;;
+esac
+case "$FILE_PATH" in
+  "$REPO_ROOT"/*) ;;  # Inside repo — proceed.
+  *)
+    # File is outside REPO_ROOT (no leading match). Skip manifest write.
+    exit 0
+    ;;
+esac
+
+if command -v jq >/dev/null 2>&1; then
+  cd "$REPO_ROOT"
+  if [ -f "lib/state.sh" ]; then
+    # shellcheck disable=SC1091
+    source lib/state.sh 2>/dev/null || exit 0
+
+    # Re-extract annotations with line numbers from the COMBINED content.
+    while IFS= read -r line; do
+      pattern_path=$(echo "$line" | sed -E 's/.*@pattern[[:space:]]+(patterns\/[a-z0-9_-]+\/[a-z0-9_-]+\/[a-z0-9_-]+\.md).*/\1/')
+      # Find line number in the file (best-effort).
+      line_num=$(grep -nF "@pattern $pattern_path" "$FILE_PATH" 2>/dev/null | head -1 | cut -d: -f1 || echo "1")
+      relative_path="${FILE_PATH#$REPO_ROOT/}"
+      state_pattern_implementation_set "$relative_path" "$pattern_path" "$line_num" 2>/dev/null || true
+    done <<< "$ANNOTATIONS"
+  fi
+fi
+
+exit 0

package/dist/lite/.claude/hooks/plain-english-steering.sh

@@ -83,10 +83,24 @@ ${OFFENDERS_BULLETS}"
     GRADE_LINE="
 
 **From your LAST turn (not this one): grade ${LAST_GRADE} (${LAST_WORDS} words). Target: grade 8 for 80%+ of prose. Ceiling: 10 for simple technical sentences. ${GRADE_STATUS}. THIS turn is not measured yet — self-check each sentence before I ship it.** (Per #1044 Option B: post-turn measurement + pre-turn injection means the number I see is one turn old by design.)${OFFENDERS_LINE}"
+    # cli#107 cure — fire the textstat-missing warning at most once per session.
+    # Prior version emitted this on every UserPromptSubmit fire, training the
+    # reader to skim the steering block it sits in. Marker under
+    # $HOME/.claude/state/sessions/<session-id>/ scopes the check to one
+    # session; fresh sessions get the warning once. Marker write failure is
+    # silent (never crashes the hook) per bassclef defensive-bash pattern.
     if [ "$SOURCE" = "FALLBACK" ]; then
-      FALLBACK_WARNING="
+      __ts_session_id="${CLAUDE_SESSION_ID:-${PPID:-$$}}"
+      __ts_marker_dir="${CLAUDE_SESSION_STATE_DIR:-$HOME/.claude/state/sessions}/${__ts_session_id}"
+      __ts_marker="${__ts_marker_dir}/textstat-warned"
+      if [ ! -f "$__ts_marker" ]; then
+        FALLBACK_WARNING="
 
 **textstat not installed; grade uses the hand-rolled fallback. Numbers are approximate. Run \`pip install textstat\` for the sharper score.**"
+        mkdir -p "$__ts_marker_dir" 2>/dev/null || true
+        touch "$__ts_marker" 2>/dev/null || true
+      fi
+      unset __ts_session_id __ts_marker_dir __ts_marker
     fi
   fi
 fi

package/dist/lite/.claude/hooks/post-write-trace.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+# tier: lite
+set -e
+
+# Post-Write Traceability — fires on PostToolUse for Write/Edit.
+# Checks that artifacts maintain traceability to their source.
+
+INPUT=$(cat)
+# Fail-soft on malformed JSON — match bassclef#1101 pre-commit-gate.sh
+# pattern. Without the 2>/dev/null fallback, jq exit 5 + set -e crashes
+# the hook on malformed harness payloads. Caught WU-5 of bet 2026-06-17c.
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null || echo "")
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null || echo "")
+
+# Only check Write and Edit operations
+if [ "$TOOL_NAME" != "Write" ] && [ "$TOOL_NAME" != "Edit" ]; then
+  exit 0
+fi
+
+# Skip non-markdown files (traceability is for documentation artifacts)
+if ! echo "$FILE_PATH" | grep -qE '\.md$'; then
+  exit 0
+fi
+
+# Skip memory, config, and template files
+if echo "$FILE_PATH" | grep -qE 'memory/|MEMORY\.md|CLAUDE\.md|AGENTS\.md|template|settings'; then
+  exit 0
+fi
+
+# === Spec traceability ===
+if echo "$FILE_PATH" | grep -qiE 'specs?/'; then
+  echo ""
+  echo "TRACE CHECK: Spec written to $FILE_PATH"
+  echo "  → Does this spec reference its source canvas or issue?"
+  echo "  → Format: 'Source: [canvas path or issue #NNN]'"
+  echo ""
+fi
+
+# === Chronicle traceability ===
+if echo "$FILE_PATH" | grep -qiE 'chronicle/'; then
+  echo ""
+  echo "TRACE CHECK: Chronicle written to $FILE_PATH"
+  echo "  → Does it include commit refs in 'Work done' section?"
+  echo "  → Does it have 'Open threads' for next session?"
+  echo ""
+fi
+
+# === ADR traceability ===
+if echo "$FILE_PATH" | grep -qiE 'decisions/|adrs?/'; then
+  echo ""
+  echo "TRACE CHECK: ADR written to $FILE_PATH"
+  echo "  → Does it reference the risk or issue that prompted it?"
+  echo "  → Status set? (proposed/accepted/deprecated/superseded)"
+  echo ""
+fi
+
+# === Iteration bet traceability ===
+if echo "$FILE_PATH" | grep -qiE 'iteration-bets?/'; then
+  echo ""
+  echo "TRACE CHECK: Iteration bet written to $FILE_PATH"
+  echo "  → Does it reference specific issue numbers in scope?"
+  echo "  → Does it declare the risk being retired?"
+  echo ""
+fi
+
+exit 0