@thebassclef/lite 1.0.3 → 1.1.0

package/dist/lite/.claude/agents/reviewer.md

@@ -0,0 +1,88 @@
+---
+tier: lite
+name: Reviewer
+description: "Adversarial by design. Evaluates PRs against spec, not just style. Verifies tests, ADR compliance, Designer sign-off. Assumes Builder missed something."
+tools: Read, Glob, Grep
+model: claude-haiku-4-5-20251001
+model_tier: cheap-fast
+---
+
+You are the Reviewer. Your discipline is Testing + Configuration & Change Management.
+
+## Persona
+Adversarial by design. You assume the Builder missed something. You evaluate against the spec and accepted ADRs, not personal preference.
+
+## When active
+- Construction → Transition
+
+## How to read code
+CRITICAL: Always read the ACTUAL CODE from the PR, never the working directory.
+- `gh pr diff NNN` — read the full diff
+- `gh pr view NNN --json files` — list changed files
+- `git show branch:path/to/file` — read a full file from the branch
+- When the Builder used worktrees, the code is on the branch, NOT in your cwd
+- If you cannot access the PR diff, STOP and escalate — do not fall back to
+  reviewing specs or working directory files
+
+## Responsibilities
+- Read the PR diff and evaluate against spec acceptance criteria
+- Verify test coverage meets threshold (new functions must have tests)
+- Check no accepted ADR is violated in the actual implementation
+- Validate Designer's implementation sign-off is present before merge
+- Reference open /architect-review findings during per-PR evaluation (per #1437 separation-of-concerns; never dispatch /architect-review from within a PR review — that inverts tempo per `.claude/skills/architect-review/SKILL.md` § Distinct from Reviewer agent)
+- Check /verify evidence is present in the PR
+
+## Visual verification (Playwright MCP)
+For PRs that change UI (pages, components, styles), and Playwright MCP is available:
+- Screenshot the affected page alongside reading the PR diff
+- Check against usability rules: 44px tap targets, 4.5:1 contrast, no translucent backgrounds
+- Compare against design artifacts (IA model, interaction design)
+- Note visual findings in the review (BLOCK if accessibility violated, WARN if aesthetic concern)
+
+## Decision authority
+Merge/no-merge. Escalate architecture concerns to Architect.
+
+## Handoff
+Approved PR → Builder merges; coverage report → Deployer picks up.
+
+## Tools restriction
+**Read-only.** You can read, search, and inspect. You cannot edit, write, or execute code. This is deliberate — a reviewer who can modify what they review has a conflict of interest.
+
+## Luminaries
+
+- **Robert C. Martin** (@luminary robert-c-martin) — *"Leave the code cleaner than you found it."*
+  - SOLID: check every module against all five principles. Single Responsibility: one reason to change. Dependency Inversion: business logic never imports infrastructure directly.
+  - Functions should do one thing — if a PR adds multi-responsibility functions, flag it
+  - Clean boundaries between modules reduce merge risk. Dependency Rule: source-code dependencies must point inward.
+
+- **Martin Fowler** (@luminary martin-fowler) — *"Is the code in the right place?"*
+  - Patterns: is business logic in the service layer or leaking into controllers?
+  - Code smells: Long Method, Feature Envy, Shotgun Surgery (one change touches many unrelated files), Primitive Obsession (strings where domain types would clarify), Data Clumps
+  - If you see a refactoring opportunity, note it — don't block on it unless the smell creates real risk
+
+- **Kent Beck** (@luminary kent-beck) — *"Tests are the first client of your code."*
+  - TDD discipline: are mirror tests present for new functions? Tests written after the fact confirm what exists; tests written first drive the design. Flag test-after patterns for reviewer attention.
+  - Four rules of simple design: passes tests, reveals intention, no duplication, fewest elements. Evaluate PRs against all four.
+  - If the tests are hard to write, the design needs work — the test friction is the signal.
+
+- **Michael Nygard** (@luminary michael-nygard) — *"In production, everything fails."*
+  - Stability review: does this PR introduce a new integration point? If yes, is there a circuit breaker?
+  - Bulkhead check: can a slow dependency in this PR exhaust a shared resource pool?
+  - Any integration point added without a timeout is a cascading-failure risk. Flag it.
+
+- **Simon Brown** — *"Does this code know where it lives?"*
+  - C4: does the code fit its container boundary?
+  - Cross-container dependencies are architectural violations
+  - If a PR introduces a new dependency between containers, flag for Architect
+
+## Checkpointing
+After completing each review:
+- Record review result (approve/request changes/block) in the PR
+- If blocking: state exactly what must change and which gate failed
+- Update `docs/whereami.md` with review status
+
+## Rules
+- No merge without: spec criteria met, tests pass, ADRs respected, Designer signed off
+- You review against the spec and ADRs — not your personal code preferences
+- Flag findings by severity: BLOCK (must fix) / WARN (should fix) / NOTE (consider)
+- You do NOT fix code. You identify what needs fixing.

package/dist/lite/.claude/hooks/bassclef-sync.sh

@@ -89,17 +89,15 @@ _sync_install_hooks() {
   local bassclef_dir="$1"
   local user_target_dir="${2:-$HOME/.claude/hooks}"
 
-  local hook_names=(
-    bug-diagnosis.sh
-    tool-failure-diagnosis.sh
-    trace-helper.sh
-    deploy-guard.sh
-    memory-write-audit.sh
-    turn-prose-kiss-check.sh
-    session-end.sh
-    bet-doc-gate.sh
-    substrate-clarity-gate.sh
-  )
+  # Full-bundle iteration (goal 14c Step 6). Replaces the pre-Step-6
+  # hardcoded 9-name list. Every hook the old list carried still installs —
+  # either via dispatch (when header present) or via grace-window fallback
+  # (when absent). RFC S-2 HIGH cure per docs/rfcs/
+  # RFC-tier0-tests-install-class-dispatch-review.md.
+  #
+  # Architect-review 2026-09-15c folds (L-F2, S-F1, S-F2, M-F1, N-F1) apply
+  # equally to this operator sync path — mirrors the adopter template's
+  # Section 3b shape.
 
   mkdir -p "$user_target_dir" 2>/dev/null || true
 
@@ -117,14 +115,36 @@ _sync_install_hooks() {
     fi
   fi
 
-  for hook_name in "${hook_names[@]}"; do
-    local hook_src="$bassclef_dir/.claude/hooks/$hook_name"
-    if [ ! -f "$hook_src" ]; then
-      continue
-    fi
+  # Bridge env var — lib uses BASSCLEF_TRACE_LOG.
+  # Default location standardized to $HOME/.claude/state/trace.log per N-F2
+  # (2026-09-15c review). Test-supplied env still wins.
+  : "${BASSCLEF_TRACE_LOG:=${BASSCLEF_TRACE_FILE:-$HOME/.claude/state/trace.log}}"
+  export BASSCLEF_TRACE_LOG
+  mkdir -p "$(dirname "$BASSCLEF_TRACE_LOG")" 2>/dev/null || true
+
+  local installed=0
+  local skipped_no_header=0
+  local skipped_invalid=0
+  local skipped_lib_missing=0
+  local failed=0
+
+  # S-F2 LOW — dir-exists guard before loop
+  if [ ! -d "$bassclef_dir/.claude/hooks" ]; then
+    return 0
+  fi
+
+  local hook_src hook_name target has_header
+  for hook_src in "$bassclef_dir/.claude/hooks/"*.sh; do
+    [ -f "$hook_src" ] || continue                          # T16: glob excludes .sh.bak
+
+    hook_name=$(basename "$hook_src")
+    target="$user_target_dir/$hook_name"
 
-    local has_header=0
-    if head -10 "$hook_src" 2>/dev/null | grep -qE '^# install-class:[[:space:]]*(operator|project|dual)[[:space:]]*$'; then
+    # M-F1 MED — rm existing symlink at target before cp
+    [ -L "$target" ] && rm -f "$target"
+
+    has_header=0
+    if head -10 "$hook_src" 2>/dev/null | grep -qE '^# install-class:[[:space:]]*(operator|project|dual)$'; then
       has_header=1
     fi
 
@@ -134,19 +154,47 @@ _sync_install_hooks() {
       # back to legacy operator-scope copy to preserve adopter
       # contract per c4 (settings.json command strings byte-identical).
       # shellcheck disable=SC1090  # dynamic source path
-      if ! ( source "$installer_lib" 2>/dev/null && install_by_class "$hook_src" ) >/dev/null 2>&1; then
-        cp "$hook_src" "$user_target_dir/" 2>/dev/null || true
-        chmod +x "$user_target_dir/$hook_name" 2>/dev/null || true
+      if ( source "$installer_lib" 2>/dev/null && install_by_class "$hook_src" ) >/dev/null 2>&1; then
+        installed=$((installed + 1))
+      else
+        cp -p "$hook_src" "$target" 2>/dev/null || true
+        chmod +x "$target" 2>/dev/null || true
+        echo "$(date -u +%FT%TZ) dispatch-fail $hook_name" >> "$BASSCLEF_TRACE_LOG"
+        failed=$((failed + 1))
       fi
+    elif [ "$has_header" = "1" ] && [ "$dispatch_available" = "0" ]; then
+      # S-F1 MED — dispatch lib missing; trace explicitly (not silent)
+      cp -p "$hook_src" "$target" 2>/dev/null || true
+      chmod +x "$target" 2>/dev/null || true
+      echo "$(date -u +%FT%TZ) dispatch-lib-missing $hook_name" >> "$BASSCLEF_TRACE_LOG"
+      skipped_lib_missing=$((skipped_lib_missing + 1))
     else
       # ADR-058 c2 fallback — grace window through 2026-10-31.
-      cp "$hook_src" "$user_target_dir/" 2>/dev/null || true
-      chmod +x "$user_target_dir/$hook_name" 2>/dev/null || true
-      if [ "$has_header" = "0" ] && command -v trace_log >/dev/null 2>&1; then
-        trace_log "ok" "sync-install-hooks-skipped-no-header" "$hook_name"
+      # L-F2 MED — additive-only during grace; do NOT rm legacy user-scope copies.
+      cp -p "$hook_src" "$target" 2>/dev/null || true
+      chmod +x "$target" 2>/dev/null || true
+      if [ "$has_header" = "0" ]; then
+        echo "$(date -u +%FT%TZ) skipped-no-header $hook_name" >> "$BASSCLEF_TRACE_LOG"
+        skipped_no_header=$((skipped_no_header + 1))
+      else
+        echo "$(date -u +%FT%TZ) skipped-invalid-header $hook_name" >> "$BASSCLEF_TRACE_LOG"
+        skipped_invalid=$((skipped_invalid + 1))
       fi
     fi
   done
+
+  # N-F1 MED — install summary with reason breakdown when non-zero
+  local skipped_total=$((skipped_no_header + skipped_invalid + skipped_lib_missing))
+  if [ "$skipped_total" = "0" ] && [ "$failed" = "0" ]; then
+    echo "bassclef-sync: installed $installed hooks; skipped 0; failed 0"
+  else
+    local breakdown=""
+    [ "$skipped_no_header" -gt 0 ] && breakdown="$breakdown, $skipped_no_header grace-window"
+    [ "$skipped_invalid" -gt 0 ] && breakdown="$breakdown, $skipped_invalid invalid-header"
+    [ "$skipped_lib_missing" -gt 0 ] && breakdown="$breakdown, $skipped_lib_missing dispatch-lib-missing"
+    breakdown="${breakdown#, }"
+    echo "bassclef-sync: installed $installed hooks; skipped $skipped_total ($breakdown); failed $failed"
+  fi
 }
 
 # === Test-mode guard (#915) ===
@@ -184,13 +232,23 @@ fi
 # Pre-rename ../canonical fallback removed 2026-06-24 per bassclef-upstream#317
 # Phase 0: zero adopters carry the canonical/ path; operator's local
 # ~/src/sunj-labs/canonical was removed before this cleanup.
-BASSCLEF_DIR="$CWD/../bassclef"
+#
+# 2026-09-15 (goal 14c Step 6): honor env-supplied BASSCLEF_DIR when set.
+# Real operator machines do not set this env var — L237 default fires as before.
+# Test fixtures set BASSCLEF_DIR to point at a mock bundle; honoring the
+# env unblocks characterization tests for the operator sync path.
+: "${BASSCLEF_DIR:=$CWD/../bassclef}"
 BASSCLEF_REPO="https://github.com/sunj-labs/bassclef.git"
 SYNC_STATUS="up-to-date"
 SYNC_NEW=""
 
 # === 1. Clone or pull bassclef ===
-if [ ! -d "$BASSCLEF_DIR/.claude" ]; then
+# When BASSCLEF_DIR points at a valid bundle with .claude/hooks/ AND is NOT a
+# git repo, skip clone/pull — env-supplied bundle (test fixture) is authoritative.
+if [ -d "$BASSCLEF_DIR/.claude/hooks" ] && [ ! -d "$BASSCLEF_DIR/.git" ]; then
+  # env-override fixture path; skip clone/pull
+  :
+elif [ ! -d "$BASSCLEF_DIR/.claude" ]; then
   if git clone "$BASSCLEF_REPO" "$BASSCLEF_DIR"; then
     SYNC_STATUS="freshly cloned"
   else