@thebassclef/lite 1.1.0 → 1.2.0-alpha.1

package/dist/lite/.claude/hooks/pre-gh-pr-body-scrub.sh

@@ -0,0 +1,192 @@
+#!/bin/bash
+# tier: lite
+# pre-gh-pr-body-scrub — PreToolUse hook that runs the body scrub logic
+# LOCALLY before a `gh pr create`, `gh pr edit --body`, `gh issue create`,
+# or `gh issue edit --body` Bash invocation reaches GitHub. Sister to
+# atomic-pr-check.sh (Bash-matcher pattern); reuses pr-body-scrub-check.sh
+# (the CI scan logic) for shared rule semantics.
+#
+# bassclef#1176 (V1) — closed the gap PR #1172 demonstrated for PR bodies.
+# bassclef#1177 (V2) — extends the same hook to gh issue bodies. The
+# filename keeps the V1 name for git-history continuity; the matcher covers
+# both surfaces. Commit-message bodies are covered by the sibling hook
+# pre-git-commit-msg-scrub.sh.
+#
+# Exit codes:
+#   0 — allow (non-matching Bash, no body extractable, clean body, or override)
+#   2 — block (Rule 1 findings present in the extracted body)
+#
+# Override: SKIP_PRE_GH_PR_BODY_SCRUB=1 (logged via trace-helper)
+
+set +e  # never crash the tool call; fall through to allow on any unexpected error
+
+INPUT=$(cat 2>/dev/null)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""' 2>/dev/null)
+
+# Only fire on Bash
+if [ "$TOOL_NAME" != "Bash" ]; then
+  exit 0
+fi
+
+# Match the surfaces this hook covers: gh pr create + gh pr edit (V1) and
+# gh issue create + gh issue edit (V2 per bassclef#1177) and curl REST
+# equivalents (V3 per bassclef#1239 — closes the curl REST bypass gap).
+IS_CURL=0
+case "$COMMAND" in
+  *"gh pr create"*|*"gh pr edit"*|*"gh issue create"*|*"gh issue edit"*)
+    : # match — continue to body extraction
+    ;;
+  *curl*api.github.com*/pulls*|*curl*api.github.com*/issues*)
+    case "$COMMAND" in
+      *"-X POST"*|*"-X PATCH"*|*"--request POST"*|*"--request PATCH"*)
+        IS_CURL=1
+        ;;
+      *)
+        exit 0  # read-only curl
+        ;;
+    esac
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+# Override hatch
+SCRIPT_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
+if [ "${SKIP_PRE_GH_PR_BODY_SCRUB:-0}" = "1" ]; then
+  if [ -n "$SCRIPT_DIR" ] && [ -f "$SCRIPT_DIR/trace-helper.sh" ]; then
+    source "$SCRIPT_DIR/trace-helper.sh" 2>/dev/null || true
+    trace_log "pre-gh-pr-body-scrub" "OVERRIDE gh pr create|edit" 2>/dev/null || true
+  fi
+  exit 0
+fi
+
+# Locate the shared scrub script
+SCRUB_SCRIPT="${SCRIPT_DIR}/pr-body-scrub-check.sh"
+if [ ! -f "$SCRUB_SCRIPT" ]; then
+  # Shared scrub missing — degrade to advisory (allow)
+  exit 0
+fi
+
+# Extract body content from the command. Three forms in order of precedence:
+#   1. Heredoc:    --body "$(cat <<EOF ... EOF)"  or  <<'EOF' ... EOF
+#   2. --body-file <path>
+#   3. Inline:     --body "..."  or  --body '...'
+TMP_BODY=$(mktemp 2>/dev/null) || exit 0
+trap 'rm -f "$TMP_BODY"' EXIT
+
+EXTRACTED=$(COMMAND="$COMMAND" IS_CURL="$IS_CURL" python3 -c '
+import os, re, sys, json
+cmd = os.environ.get("COMMAND", "")
+is_curl = os.environ.get("IS_CURL", "0") == "1"
+
+if is_curl:
+    # curl REST shape — extract body from --data @<file> or -d "<inline>"
+    # bassclef#1239
+    m = re.search(r"(?:--data|-d)\s+@(\S+)", cmd)
+    if m:
+        path = m.group(1)
+        try:
+            with open(path) as f:
+                payload = json.load(f)
+            body = payload.get("body", "")
+            if body:
+                sys.stdout.write(body)
+                sys.exit(0)
+        except (OSError, json.JSONDecodeError):
+            pass
+    m = re.search(r"(?:--data|-d)\s+\x27([^\x27]*)\x27", cmd, re.DOTALL)
+    if m:
+        try:
+            payload = json.loads(m.group(1))
+            body = payload.get("body", "")
+            if body:
+                sys.stdout.write(body)
+                sys.exit(0)
+        except json.JSONDecodeError:
+            pass
+    m = re.search(r"(?:--data|-d)\s+\"((?:[^\"\\\\]|\\\\.)*)\"", cmd, re.DOTALL)
+    if m:
+        try:
+            payload = json.loads(m.group(1).replace("\\\"", "\""))
+            body = payload.get("body", "")
+            if body:
+                sys.stdout.write(body)
+                sys.exit(0)
+        except json.JSONDecodeError:
+            pass
+    # No body extractable from curl payload — nothing to scan
+    sys.exit(0)
+
+# gh shape: existing extraction paths
+# 1. Heredoc body (handles quoted or unquoted marker)
+m = re.search(r"cat\s*<<\s*[\x27\"]?(\w+)[\x27\"]?\s*\n(.*?)\n\1", cmd, re.DOTALL)
+if m:
+    sys.stdout.write(m.group(2))
+    sys.exit(0)
+# 2. --body-file <path>
+m = re.search(r"--body-file\s+(\S+)", cmd)
+if m:
+    path = m.group(1).strip("\x27\"")
+    try:
+        with open(path) as f:
+            sys.stdout.write(f.read())
+    except Exception:
+        pass
+    sys.exit(0)
+# 3. Inline --body "..." (handle escaped quotes)
+m = re.search(r"--body\s+\"((?:[^\"\\\\]|\\\\.)*)\"", cmd, re.DOTALL)
+if m:
+    sys.stdout.write(m.group(1))
+    sys.exit(0)
+m = re.search(r"--body\s+\x27((?:[^\x27\\\\]|\\\\.)*)\x27", cmd, re.DOTALL)
+if m:
+    sys.stdout.write(m.group(1))
+    sys.exit(0)
+# Parse failure — emit nothing; caller treats as advisory pass
+' 2>/dev/null)
+
+if [ -z "$EXTRACTED" ]; then
+  # Parse failure — fall back to advisory (allow). The CI hook is the backstop.
+  exit 0
+fi
+
+printf '%s' "$EXTRACTED" > "$TMP_BODY"
+
+# Extract PR title for Rule 7 (bassclef#974) — check for Closes-keyword when
+# title carries feat(#NNN) or fix(#NNN). Advisory only in V1.
+PR_TITLE=$(COMMAND="$COMMAND" python3 -c '
+import os, re, sys
+cmd = os.environ.get("COMMAND", "")
+m = re.search(r"--title\s+\"([^\"]+)\"", cmd) or re.search(r"--title\s+\x27([^\x27]+)\x27", cmd)
+if m:
+    sys.stdout.write(m.group(1))
+' 2>/dev/null)
+
+# Run the shared scrub — exit 1 means Rule 1 findings (CI's blocking semantic)
+PR_TITLE="$PR_TITLE" bash "$SCRUB_SCRIPT" "$TMP_BODY" >&2 2>&1
+SCRUB_RC=$?
+
+if [ "$SCRUB_RC" = "1" ]; then
+  cat >&2 <<MSG
+
+============================================
+🛑 pre-gh-pr-body-scrub — BLOCKED LOCALLY
+============================================
+
+The PR body extracted from the gh command contains bassclef-internal
+jargon (Rule 1). The CI hook would have caught this after push; this
+local hook catches it before the call reaches GitHub.
+
+Rewrite the body using plain-English alternatives from
+standards/bassclef-internal-jargon.md.
+
+Override (logged): SKIP_PRE_GH_PR_BODY_SCRUB=1 <command>
+Per bassclef#1176.
+
+MSG
+  exit 2
+fi
+
+exit 0

package/dist/lite/.claude/hooks/pre-gh-pr-title-scrub.sh

@@ -0,0 +1,172 @@
+#!/bin/bash
+# tier: lite
+# pre-gh-pr-title-scrub — PreToolUse hook that runs the body scrub logic
+# LOCALLY against the --title argument of a `gh pr create` or
+# `gh pr edit --title` Bash invocation. Sister to pre-gh-pr-body-scrub.sh
+# (bassclef#1176) and pre-git-commit-msg-scrub.sh (bassclef#1177);
+# extends the same Bash-matcher + shared-scrub pattern to the title surface.
+#
+# bassclef#1201 — closes the gap that PR body + commit message had covered
+# but PR title had not. Titles are the most-scanned text in any PR list;
+# jargon there compounds across every operator who scrolls.
+#
+# Exit codes:
+#   0 — allow (non-matching Bash, no --title in command, clean title, or override)
+#   2 — block (Rule 1 findings present in the extracted title)
+#
+# Override: SKIP_PRE_GH_PR_TITLE_SCRUB=1 (logged via trace-helper)
+
+set +e  # never crash the tool call; fall through to allow on any unexpected error
+
+INPUT=$(cat 2>/dev/null)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""' 2>/dev/null)
+
+# Only fire on Bash
+if [ "$TOOL_NAME" != "Bash" ]; then
+  exit 0
+fi
+
+# Match the surfaces this hook covers: gh pr create, gh pr edit, and
+# curl REST equivalents (POST/PATCH against /pulls or /issues).
+# bassclef#1239 — curl REST fallback used to bypass every scrub hook when
+# GraphQL rate-limit exhausted gh CLI.
+IS_CURL=0
+case "$COMMAND" in
+  *"gh pr create"*|*"gh pr edit"*)
+    : # match — continue to title extraction
+    ;;
+  *curl*api.github.com*/pulls*|*curl*api.github.com*/issues*)
+    # curl REST shape — verify it's a write (POST or PATCH), not GET
+    case "$COMMAND" in
+      *"-X POST"*|*"-X PATCH"*|*"--request POST"*|*"--request PATCH"*)
+        IS_CURL=1
+        ;;
+      *)
+        exit 0  # read-only curl (GET / HEAD) — nothing to scan
+        ;;
+    esac
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+# Override hatch
+SCRIPT_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
+if [ "${SKIP_PRE_GH_PR_TITLE_SCRUB:-0}" = "1" ]; then
+  if [ -n "$SCRIPT_DIR" ] && [ -f "$SCRIPT_DIR/trace-helper.sh" ]; then
+    source "$SCRIPT_DIR/trace-helper.sh" 2>/dev/null || true
+    trace_log "pre-gh-pr-title-scrub" "OVERRIDE gh pr create|edit" 2>/dev/null || true
+  fi
+  exit 0
+fi
+
+# Locate the shared scrub script
+SCRUB_SCRIPT="${SCRIPT_DIR}/pr-body-scrub-check.sh"
+if [ ! -f "$SCRUB_SCRIPT" ]; then
+  # Shared scrub missing — degrade to advisory (allow)
+  exit 0
+fi
+
+# Extract title content from the command. Two quote forms:
+#   1. Double-quoted:  --title "..."
+#   2. Single-quoted:  --title '...'
+# If no --title flag present, exit 0 (interactive title flow; nothing to scan).
+TMP_TITLE=$(mktemp -t title-scrub.XXXXXX 2>/dev/null) || exit 0
+trap 'rm -f "$TMP_TITLE"' EXIT
+
+EXTRACTED=$(COMMAND="$COMMAND" IS_CURL="$IS_CURL" python3 -c '
+import os, re, sys, json
+cmd = os.environ.get("COMMAND", "")
+is_curl = os.environ.get("IS_CURL", "0") == "1"
+
+if is_curl:
+    # curl REST shape — extract title from --data @<file> or -d "<inline>"
+    # bassclef#1239
+    # First try: --data @<path>
+    m = re.search(r"(?:--data|-d)\s+@(\S+)", cmd)
+    if m:
+        path = m.group(1)
+        try:
+            with open(path) as f:
+                payload = json.load(f)
+            title = payload.get("title", "")
+            if title:
+                sys.stdout.write(title)
+                sys.exit(0)
+        except (OSError, json.JSONDecodeError):
+            pass
+    # Try inline -d single-quoted JSON
+    m = re.search(r"(?:--data|-d)\s+\x27([^\x27]*)\x27", cmd, re.DOTALL)
+    if m:
+        try:
+            payload = json.loads(m.group(1))
+            title = payload.get("title", "")
+            if title:
+                sys.stdout.write(title)
+                sys.exit(0)
+        except json.JSONDecodeError:
+            pass
+    # Try inline -d double-quoted JSON
+    m = re.search(r"(?:--data|-d)\s+\"((?:[^\"\\\\]|\\\\.)*)\"", cmd, re.DOTALL)
+    if m:
+        try:
+            payload = json.loads(m.group(1).replace("\\\"", "\""))
+            title = payload.get("title", "")
+            if title:
+                sys.stdout.write(title)
+                sys.exit(0)
+        except json.JSONDecodeError:
+            pass
+    # No title extractable from curl payload — nothing to scan
+    sys.exit(0)
+
+# gh shape: extract --title argument
+# Double-quoted --title "..."
+m = re.search(r"--title\s+\"((?:[^\"\\\\]|\\\\.)*)\"", cmd, re.DOTALL)
+if m:
+    sys.stdout.write(m.group(1))
+    sys.exit(0)
+# Single-quoted --title '"'"'...'"'"'
+m = re.search(r"--title\s+\x27((?:[^\x27\\\\]|\\\\.)*)\x27", cmd, re.DOTALL)
+if m:
+    sys.stdout.write(m.group(1))
+    sys.exit(0)
+# No --title flag — nothing to scan
+' 2>/dev/null)
+
+if [ -z "$EXTRACTED" ]; then
+  # No title to scan (interactive flow, or --title absent) — allow
+  exit 0
+fi
+
+printf '%s' "$EXTRACTED" > "$TMP_TITLE"
+
+# Run the shared scrub with SCRUB_SURFACE=title so BLOCK-title terms fire
+# (bassclef#1241 WU-2 — substrate-defect: blocks title surface, not body).
+SCRUB_SURFACE=title bash "$SCRUB_SCRIPT" "$TMP_TITLE" >&2 2>&1
+SCRUB_RC=$?
+
+if [ "$SCRUB_RC" = "1" ]; then
+  cat >&2 <<MSG
+
+============================================
+🛑 pre-gh-pr-title-scrub — BLOCKED LOCALLY
+============================================
+
+The PR title extracted from the gh command contains bassclef-internal
+jargon (Rule 1). Titles are the most-scanned text in any PR list;
+jargon there compounds across every operator who scrolls.
+
+Rewrite the title using plain-English alternatives from
+standards/bassclef-internal-jargon.md.
+
+Override (logged): SKIP_PRE_GH_PR_TITLE_SCRUB=1 <command>
+Per bassclef#1201.
+
+MSG
+  exit 2
+fi
+
+exit 0

package/dist/lite/.claude/hooks/role-entry-gate.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# tier: lite
+# role-entry-gate.sh — mode-agnostic role-entry discipline (bassclef#1145 T13)
+#
+# Fires on PreToolUse Edit|Write|MultiEdit. Detects work-shape from file_path
+# and BLOCKs when the matching agent role marker is absent for the current
+# session.
+#
+# MVP scope: Builder role only (source code matching). Architect / Reviewer /
+# Designer role detection deferred to a follow-on ticket — the design choices
+# on multi-role matching deserve their own pass.
+#
+# Marker convention:
+#   $CWD/state/markers/role/<role>/<session_id>.marker
+#
+# The marker is written by the agent (or the operator-invoked /role-entry
+# skill, deferred to follow-on) once the role's persona has been loaded.
+# This hook reads the marker; it does not write.
+#
+# Mode-agnostic behavior:
+#   - sequential mode: BLOCK message tells Claude to read the agent persona
+#     itself, write the marker, then proceed
+#   - orchestrator-gated mode: BLOCK message tells Orchestrator to route the
+#     next-step dispatch to the matching role agent
+#
+# Exit codes:
+#   0 — pass (override, skip, marker present)
+#   3 — BLOCK (source-code edit without Builder marker)
+#
+# Override: SKIP_ROLE_ENTRY=1 — logged via trace-helper (bassclef idiom).
+
+set -u
+
+# --- Override path ---
+if [ "${SKIP_ROLE_ENTRY:-0}" = "1" ]; then
+  echo "SKIP_ROLE_ENTRY=1 — role-entry gate bypassed" >&2
+  exit 0
+fi
+
+# --- Read stdin (fail-soft on malformed JSON per bassclef#1101 pattern) ---
+INPUT=$(cat)
+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 "")
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"' 2>/dev/null || echo "unknown")
+CWD=$(echo "$INPUT" | jq -r '.cwd // "."' 2>/dev/null || echo ".")
+
+# Malformed JSON or missing tool_name → pass silently (no work-shape signal)
+if [ -z "$TOOL_NAME" ]; then
+  exit 0
+fi
+
+# --- Tool-name matcher ---
+case "$TOOL_NAME" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+# --- Path matcher: source code per common languages ---
+# MVP language list per bassclef tech_stack vocabulary. Stack-bound matchers
+# can be tightened later by reading tech_stack.lang from bassclef-configs.jsonc.
+case "$FILE_PATH" in
+  *.ts|*.tsx|*.js|*.jsx|*.py|*.rb|*.go|*.rs|*.java|*.kt|*.swift|*.cs|*.cpp|*.c|*.h)
+    EXPECTED_ROLE="builder"
+    ;;
+  *)
+    # Not a source file → no role discipline applies in MVP
+    exit 0
+    ;;
+esac
+
+# --- Marker check ---
+MARKER_PATH="${CWD}/state/markers/role/${EXPECTED_ROLE}/${SESSION_ID}.marker"
+
+if [ -f "$MARKER_PATH" ]; then
+  # Marker present → pass. Freshness window check deferred to follow-on.
+  exit 0
+fi
+
+# --- BLOCK ---
+cat >&2 <<BLOCK
+============================================
+🛑 role-entry-gate — BLOCKED
+============================================
+
+About to do ${EXPECTED_ROLE}-shaped work (editing ${FILE_PATH}) but the
+${EXPECTED_ROLE} agent role has not been entered for this session.
+
+Expected marker (absent):
+  ${MARKER_PATH}
+
+Two paths forward depending on session mode:
+
+  Sequential mode (default):
+    1. Read ~/.claude/agents/${EXPECTED_ROLE}.md to load luminaries + responsibilities
+    2. Write the marker:
+         mkdir -p $(dirname "$MARKER_PATH")
+         cat > "$MARKER_PATH" <<EOF
+         {"role":"${EXPECTED_ROLE}","session_id":"${SESSION_ID}","entered_at":"\$(date -u +%Y-%m-%dT%H:%M:%SZ)"}
+         EOF
+    3. Re-run the edit — the marker now satisfies the gate.
+
+  Orchestrator-gated mode:
+    Orchestrator routes this edit to the ${EXPECTED_ROLE} agent for
+    sandbox execution. The role agent writes its own marker before
+    proceeding.
+
+Override (logged):
+  SKIP_ROLE_ENTRY=1 <command>
+
+Per bassclef#1145 T13 (this hook) and .claude/agents/${EXPECTED_ROLE}.md (the
+role persona this gate routes to).
+============================================
+BLOCK
+
+exit 3