@thebassclef/lite 1.9.15 → 1.9.18

package/dist/lite/presence/install/bassclef-sync.template.sh

@@ -256,6 +256,64 @@ bassclef_sync_parse_whereami_ts() {
   return 0
 }
 
+# === #2130 — scope-aware install-class resolution + prior-sync check ===
+# Reads a hook source file's `# install-class:` header. Returns one of:
+#   project | operator | dual | unknown
+# Fails soft — missing file, missing header, or invalid value → "unknown".
+#
+# Anchor luminaries — @luminary linus-torvalds (adopter contract; project-class
+# hooks must not report scope=operator), @luminary jerome-saltzer-and-michael-schroeder
+# (every scope mediated per source declaration), @luminary michael-feathers
+# (characterization anchor — pin the install-class header shape before cure).
+_template_resolve_install_class() {
+  local hook_src="$1"
+  if [ ! -f "$hook_src" ]; then
+    echo "unknown"
+    return 0
+  fi
+  local header_val
+  header_val=$(head -10 "$hook_src" 2>/dev/null | grep -E \
+    '^# install-class:[[:space:]]*(operator|project|dual)[[:space:]]*$' \
+    | head -1 | sed -E 's/^# install-class:[[:space:]]*//;s/[[:space:]]*$//')
+  case "$header_val" in
+    project|operator|dual) echo "$header_val" ;;
+    *) echo "unknown" ;;
+  esac
+}
+
+# Returns 0 (true) if the hook is installed at the scope its install-class names.
+# For `dual`, either project or operator location satisfies.
+# For `unknown`, defaults to operator check per ADR-058 C2 grace window.
+#
+# $1 — hook basename (e.g., "pre-commit-gate.sh")
+# $2 — scope value (project | operator | dual | unknown)
+# Reads $CWD and $HOME. $CWD falls back to $(pwd) when unset.
+_template_hook_present_at_scope() {
+  local hook_name="$1"
+  local scope="$2"
+  local cwd="${CWD:-$(pwd)}"
+  case "$scope" in
+    project)
+      [ -f "$cwd/.claude/hooks/$hook_name" ] && return 0
+      return 1
+      ;;
+    operator)
+      [ -f "$HOME/.claude/hooks/$hook_name" ] && return 0
+      return 1
+      ;;
+    dual)
+      [ -f "$cwd/.claude/hooks/$hook_name" ] && return 0
+      [ -f "$HOME/.claude/hooks/$hook_name" ] && return 0
+      return 1
+      ;;
+    *)
+      # unknown — grace-window; check operator per legacy behavior
+      [ -f "$HOME/.claude/hooks/$hook_name" ] && return 0
+      return 1
+      ;;
+  esac
+}
+
 # === #1929 — postcondition emitter (RESTORED/DEGRADED + JSON) ===
 # Mirrors .claude/hooks/bassclef-sync.sh L215-243 (idempotent-complete-or-fail-loud
 # pattern shipped under #1894 Cure 1 of #1691). Reads globals INSTALLED_COUNT,
@@ -1022,9 +1080,16 @@ if [ -d "$BASSCLEF_DIR/.claude/hooks" ]; then
       fi
       if [ -n "$_WALKER_MISS" ]; then
         echo "$(date -u +%FT%TZ) install-fail-missing-dep $HOOK_NAME" >> "$BASSCLEF_TRACE_LOG"
-        FAILED_COUNT=$((FAILED_COUNT + 1))
-        missing_paths+=(".claude/hooks/$HOOK_NAME")
-        missing_scopes+=("operator")
+        # #2130 — resolve install-class scope + check if hook is already present
+        # at scoped target from a prior sync. Prior-sync-present counts as installed.
+        _HOOK_SCOPE=$(_template_resolve_install_class "$HOOK_SRC")
+        if _template_hook_present_at_scope "$HOOK_NAME" "$_HOOK_SCOPE"; then
+          INSTALLED_COUNT=$((INSTALLED_COUNT + 1))
+        else
+          FAILED_COUNT=$((FAILED_COUNT + 1))
+          missing_paths+=(".claude/hooks/$HOOK_NAME")
+          missing_scopes+=("$_HOOK_SCOPE")
+        fi
         continue
       fi
 
@@ -1038,9 +1103,15 @@ if [ -d "$BASSCLEF_DIR/.claude/hooks" ]; then
         cp -p "$HOOK_SRC" "$TARGET_USER" 2>/dev/null || true
         chmod +x "$TARGET_USER" 2>/dev/null || true
         echo "$(date -u +%FT%TZ) dispatch-fail $HOOK_NAME" >> "$BASSCLEF_TRACE_LOG"
-        FAILED_COUNT=$((FAILED_COUNT + 1))
-        missing_paths+=(".claude/hooks/$HOOK_NAME")
-        missing_scopes+=("operator")
+        # #2130 — scope-aware missing[] + prior-sync pass-through
+        _HOOK_SCOPE=$(_template_resolve_install_class "$HOOK_SRC")
+        if _template_hook_present_at_scope "$HOOK_NAME" "$_HOOK_SCOPE"; then
+          INSTALLED_COUNT=$((INSTALLED_COUNT + 1))
+        else
+          FAILED_COUNT=$((FAILED_COUNT + 1))
+          missing_paths+=(".claude/hooks/$HOOK_NAME")
+          missing_scopes+=("$_HOOK_SCOPE")
+        fi
       fi
     elif [ "$HAS_HEADER" = "1" ] && [ "$DISPATCH_AVAILABLE" = "0" ]; then
       # S-F1 MED — dispatch lib missing; trace explicitly (not silent)
@@ -1059,8 +1130,15 @@ if [ -d "$BASSCLEF_DIR/.claude/hooks" ]; then
       else
         echo "$(date -u +%FT%TZ) skipped-invalid-header $HOOK_NAME" >> "$BASSCLEF_TRACE_LOG"
         SKIPPED_INVALID=$((SKIPPED_INVALID + 1))
-        missing_paths+=(".claude/hooks/$HOOK_NAME")
-        missing_scopes+=("operator")
+        # #2130 — invalid header → scope resolves to "unknown"; prior-sync still passes
+        if _template_hook_present_at_scope "$HOOK_NAME" "unknown"; then
+          # Operator-scope fallback cp above landed; treat as installed under grace
+          INSTALLED_COUNT=$((INSTALLED_COUNT + 1))
+          SKIPPED_INVALID=$((SKIPPED_INVALID - 1))
+        else
+          missing_paths+=(".claude/hooks/$HOOK_NAME")
+          missing_scopes+=("unknown")
+        fi
       fi
     fi
   done

package/dist/lite/scripts/generate-lite-manifest.sh

@@ -497,6 +497,18 @@ while IFS= read -r f; do
 done < <(find "$REPO_ROOT/.claude/hooks" -mindepth 2 -type f -name '*.sh' \
            -not -path '*/tests/*' -not -path '*/fixtures/*' 2>/dev/null | sort)
 
+# Skill-helper scripts (bash) — per bassclef-upstream#2140. Skills (e.g.,
+# onboard-repo) dispatch helper .sh files from their SKILL.md Procedure
+# steps. Lite adopters that run those skills need the helpers to land
+# in their bundle. Shipped as type=script (reuses existing enum; no
+# schema shape change). Only lite-tagged helpers end up in lite-manifest;
+# standard-tagged helpers inherit into standard-manifest + above.
+SKILL_HELPER_FILES=()
+while IFS= read -r f; do
+  SKILL_HELPER_FILES+=("$f")
+done < <(find "$REPO_ROOT/.claude/skills" -mindepth 2 -type f -name '*.sh' \
+           -not -path '*/tests/*' -not -path '*/fixtures/*' 2>/dev/null | sort)
+
 # Top-level .claude/*.md (bassclef-orientation.md) — vendored via @import from adopter
 # CLAUDE.md; ships as root-doc. Per goal 2026-09-16a.
 CLAUDE_DOC_FILES=()
@@ -635,6 +647,9 @@ ENTRIES_JSON=$(
     if [[ ${#SCRIPT_FILES[@]} -gt 0 ]]; then
       emit_entries "script"  extract_hook_tier extract_hook_description basename "${SCRIPT_FILES[@]}"
     fi
+    if [[ ${#SKILL_HELPER_FILES[@]} -gt 0 ]]; then
+      emit_entries "script"  extract_hook_tier extract_hook_description basename "${SKILL_HELPER_FILES[@]}"
+    fi
     if [[ ${#PRESENCE_TEMPLATE_SH_FILES[@]} -gt 0 ]]; then
       emit_entries "presence-template" extract_hook_tier extract_hook_description basename "${PRESENCE_TEMPLATE_SH_FILES[@]}"
     fi

package/dist/lite/scripts/launch/local-serve.sh

@@ -30,16 +30,157 @@
 # Cleanup: rely on the operator running scripts/launch/local-serve-stop.sh
 # or just killing the PID. State file lists the PID for reference.
 
-set -e
+# === #2131 — testable helpers for arg parsing + usage ===
+# Anchor luminaries — @luminary linus-torvalds (default bind unchanged;
+# --lan is opt-in; no silent regression), @luminary alan-cooper (honesty
+# default — handoff text matches bind reality), @luminary michael-feathers
+# (characterization anchor via LOCAL_SERVE_TEST_MODE guard).
+
+_local_serve_print_usage() {
+  cat <<'USAGE'
+usage: local-serve.sh [--lan] <gallery-dir> [port-hint]
+
+Serves a /launch local-mode prototype gallery via python http.server.
+
+Positional:
+  gallery-dir   path to the gallery directory (must contain index.html)
+  port-hint     optional starting port (default 8000)
+
+Flags:
+  --lan         bind to 0.0.0.0 (all interfaces) and PRINT the detected
+                LAN IP so phones/iPads on the same Wi-Fi can reach the
+                URL directly. Default is 127.0.0.1 (this computer only).
+                Prints a warning: any device on this Wi-Fi can open the URL.
+                Firewall note: macOS firewall may need to be off for the
+                port, or the OS will prompt on first bind.
+  --help        print this usage
+
+Exit codes:
+  0  — server started OR idempotent re-run returns existing URL
+  1  — python3 missing, gallery dir missing, port exhaustion, server crash
+  2  — bad args (missing gallery-dir, unknown flag)
+USAGE
+}
+
+# Detects the machine's LAN IP so --lan mode can print a dialable URL
+# instead of literal "0.0.0.0". Tries mac first (ipconfig getifaddr en0),
+# then linux (hostname -I | awk '{print $1}'). Returns empty on both
+# failures — the caller falls back to 127.0.0.1 so the --lan path
+# degrades to "this computer only" rather than crashing.
+# Per bassclef-upstream#2143 — the prior shape printed 0.0.0.0 which
+# phones cannot dial.
+_local_serve_detect_lan_ip() {
+  local ip
+  # macOS primary: en0 is the typical Wi-Fi interface
+  if command -v ipconfig >/dev/null 2>&1; then
+    ip=$(ipconfig getifaddr en0 2>/dev/null || true)
+    if [ -n "$ip" ]; then
+      echo "$ip"
+      return 0
+    fi
+    # macOS fallback: try en1 (secondary Wi-Fi on some models)
+    ip=$(ipconfig getifaddr en1 2>/dev/null || true)
+    if [ -n "$ip" ]; then
+      echo "$ip"
+      return 0
+    fi
+  fi
+  # Linux: hostname -I returns space-separated IPs; first is usually primary LAN
+  if command -v hostname >/dev/null 2>&1; then
+    ip=$(hostname -I 2>/dev/null | awk '{print $1}' || true)
+    if [ -n "$ip" ]; then
+      echo "$ip"
+      return 0
+    fi
+  fi
+  # Fallback: empty — caller uses 127.0.0.1
+  return 0
+}
+
+# Parses CLI args. Sets globals BIND_ADDR, DISPLAY_HOST, LAN_WARNING,
+# GALLERY_DIR_PARSED, PORT_HINT_PARSED. Returns 0 on success. Returns
+# non-zero on --help, unknown flag, or missing gallery-dir.
+#
+# BIND_ADDR is what python's http.server --bind sees (127.0.0.1 default,
+# 0.0.0.0 under --lan so it listens on all interfaces).
+# DISPLAY_HOST is what the printed URL + state file carries (127.0.0.1
+# default, detected LAN IP under --lan). Separate so the printed URL is
+# always dialable: 127.0.0.1 for the host, LAN IP for a phone on the
+# same Wi-Fi. Per bassclef-upstream#2143.
+_local_serve_parse_args() {
+  BIND_ADDR="127.0.0.1"
+  DISPLAY_HOST="127.0.0.1"
+  LAN_WARNING=""
+  GALLERY_DIR_PARSED=""
+  PORT_HINT_PARSED="8000"
+  local positional=()
+  local arg
+  local lan_mode=0
+  for arg in "$@"; do
+    case "$arg" in
+      --lan)
+        lan_mode=1
+        BIND_ADDR="0.0.0.0"
+        LAN_WARNING="WARN: --lan set; any device on this Wi-Fi can open this URL. Unset --lan to bind 127.0.0.1 only."
+        ;;
+      --help|-h)
+        _local_serve_print_usage
+        return 1
+        ;;
+      --*)
+        echo "ERROR: unknown flag: $arg" >&2
+        _local_serve_print_usage >&2
+        return 2
+        ;;
+      *)
+        positional+=("$arg")
+        ;;
+    esac
+  done
+  if [ "$lan_mode" -eq 1 ]; then
+    local detected
+    detected=$(_local_serve_detect_lan_ip)
+    if [ -n "$detected" ]; then
+      DISPLAY_HOST="$detected"
+    else
+      # Detection failed; fall back to 127.0.0.1 so the printed URL is still
+      # dialable from the host at least. Warn so the operator knows the
+      # phone-preview path won't work.
+      DISPLAY_HOST="127.0.0.1"
+      LAN_WARNING="${LAN_WARNING}
+WARN: --lan set but LAN IP detection failed (ipconfig / hostname). Printed URL falls back to 127.0.0.1; phone preview will not work."
+    fi
+  fi
+  if [ "${#positional[@]}" -ge 1 ]; then
+    GALLERY_DIR_PARSED="${positional[0]}"
+  fi
+  if [ "${#positional[@]}" -ge 2 ]; then
+    PORT_HINT_PARSED="${positional[1]}"
+  fi
+  if [ -z "$GALLERY_DIR_PARSED" ]; then
+    echo "ERROR: gallery-dir required" >&2
+    _local_serve_print_usage >&2
+    return 2
+  fi
+  return 0
+}
 
-GALLERY_DIR="${1:-}"
-PORT_HINT="${2:-8000}"
+# === Test-mode guard — tests source + exercise helpers without running main ===
+if [ "${LOCAL_SERVE_TEST_MODE:-}" = "1" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+set -e
 
-if [ -z "$GALLERY_DIR" ]; then
-  echo "ERROR: gallery-dir required" >&2
-  echo "usage: $0 <gallery-dir> [port-hint]" >&2
+if ! _local_serve_parse_args "$@"; then
   exit 2
 fi
+GALLERY_DIR="$GALLERY_DIR_PARSED"
+PORT_HINT="$PORT_HINT_PARSED"
+
+if [ -n "$LAN_WARNING" ]; then
+  echo "$LAN_WARNING" >&2
+fi
 
 if ! command -v python3 >/dev/null 2>&1; then
   echo "ERROR: python3 not on PATH. Install python3 first." >&2
@@ -92,7 +233,7 @@ fi
 
 # Start http.server in background, bound to 127.0.0.1 only (no external exposure)
 LOG_FILE="$STATE_DIR/${GALLERY_SLUG}.log"
-nohup python3 -m http.server "$PORT" --bind 127.0.0.1 --directory "$GALLERY_DIR" \
+nohup python3 -m http.server "$PORT" --bind "$BIND_ADDR" --directory "$GALLERY_DIR" \
   > "$LOG_FILE" 2>&1 &
 SERVER_PID=$!
 
@@ -103,7 +244,7 @@ if ! kill -0 "$SERVER_PID" 2>/dev/null; then
   exit 1
 fi
 
-URL="http://127.0.0.1:${PORT}/"
+URL="http://${DISPLAY_HOST}:${PORT}/"
 
 # Write state file
 cat > "$STATE_FILE" <<EOF

package/dist/lite/standards/bassclef-wiring-manifest.json

@@ -171,6 +171,12 @@
             "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/git-stash-u-guard.sh",
             "timeout": 5,
             "tier": "lite"
+          },
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/pre-push-shellcheck.sh",
+            "timeout": 60,
+            "tier": "lite"
           }
         ]
       },
@@ -392,6 +398,12 @@
             "timeout": 10,
             "tier": "lite"
           },
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/turn-prose-density-measure.sh",
+            "timeout": 10,
+            "tier": "lite"
+          },
           {
             "type": "command",
             "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/reviewer-dispatch-check.sh",

package/dist/lite/standards/lite-manifest-schema-changes.md

@@ -34,6 +34,55 @@ Every entry stays in this file for the life of the manifest. Never pruned. When
 
 ## Entries (newest first)
 
+### bassclef-upstream#2096 amendment 3 — pin hard stack rank in /eisenhower output (PATCH, 2026-10-13)
+
+- **Change type:** content-change (`.claude/skills/eisenhower/SKILL.md` content_hash shift; new Step 4b section added)
+- **Contracts affected:** `/eisenhower` SKILL body — adds Step 4b emitting cross-repo stack-rank table after per-quadrant tables
+- **Version bump:** PATCH per content-only policy
+- **Rationale:** bassclef-upstream#2096 amendment 3. The operator asked twice in-session for the hard stack rank with a repo column. The amendment pins the four-column shape (Rank · Ticket · Repo · Why this rank) and the Q1 → Q4 row order.
+- **Downstream cure:** nothing required; adopters that invoke `/eisenhower` see the new table automatically next run.
+- **Old shape retired:** nothing retired; this is a pure add.
+
+### bassclef-upstream#2110 step 1 — add scripts/update-lite-manifest.sh wrapper + rule amendment (PATCH, 2026-10-13)
+
+- **Change type:** content-change (two tier:lite files edited; one new tier:upstream script + test added)
+- **Contracts affected:** `.claude/rules/lite-manifest-schema-change-discipline.md` entry — content_hash shift (added "Ledger-edit-then-regen order" section)
+- **Version bump:** PATCH per content-only policy
+- **Rationale:** bassclef-upstream#2110 — the natural authoring instinct is "regen first, then write ledger explaining the change." That order ships a stale ledger hash in the manifest because the ledger file is itself in the manifest. The wrapper `scripts/update-lite-manifest.sh` forces ledger-edit-then-regen order. Tier 0 tests at `scripts/tests/update-lite-manifest.test.sh` pin 10 cases.
+- **Downstream cure:** nothing required; the wrapper is operator-side authoring convenience. Adopters do not run it. The rule amendment documents the preferred authoring path.
+- **Old shape retired:** nothing retired; this is a pure add.
+
+### bassclef-upstream#2157 step 6 — install-written-paths ajv-runtime content shift (v1.17.1 → v1.17.2, 2026-10-10)
+
+- **Change type:** content-change (lib/install-written-paths.sh content_hash shift; no entry add/remove)
+- **Contracts affected:** `lib/install-written-paths` entry — content_hash sha256 old `504f4f73...` → new `3c029eb9...`
+- **Version bump:** v1.17.1 → v1.17.2 (PATCH per policy — content_hash change only)
+- **Rationale:** bassclef-upstream#2157 step 6 adds `_iwp_ajv_validate` + `_iwp_schema_path` helpers (73 lines) in `lib/install-written-paths.sh` + extends `install_written_paths_verify` with strict ajv reject + `install_written_paths_register` with post-write advisory warning. All 5 public verbs retain signatures (Parnas information hiding). Reads via `is_install_written_path` stay cheap. Fail-soft when ajv missing.
+- **Downstream cure:** no action for lite adopters. The lib stays backward-compatible — ajv-missing fail-soft keeps adopter machines working without ajv-cli. New verify-side strict reject only fires on explicit `install_written_paths_verify` calls, not on hot-path `is_install_written_path`.
+- **Old shape retired:** nothing retired. PR #2149 CLI init.manifest.json fallback at L250-282 preserved per ADR-031 three-release-cycle rule — the cross-repo contracts registry ledger v1.0.1 entry names the retire schedule.
+- **Refs:** `architecture/decisions/ADR-059-cross-repo-contract-drift-prevention.md`, bassclef-upstream#2157, bassclef-cli#415 (CLOSED via PR #416 SHA 9cf9014). See cross-repo contracts registry ledger v1.0.1 entry for the paired stage flip.
+
+### bassclef-upstream v1.9.3 hotfix — manifest_version regression cure (v1.17.0 → v1.17.1, 2026-10-08)
+
+- **Change type:** version-field-correction (0 content shift, 0 schema shape change). Prior v1.9.2 release shipped `manifest_version: "0.0.0"` due to a generator fallback bug — chained rebase regens compounded a null read into 0.0.0. cli bundler strict major=1 check rejected the shipped manifest.
+- **Fields:** 449 entries (unchanged). manifest_version field only.
+- **Version bump:** v1.17.0 → v1.17.1 (patch — version-field correction with no content shift; per policy f).
+- **Rationale:** bassclef-cli-63 peer blocker report 2026-10-08 — v1.9.2 shipped `manifest_version: "0.0.0"`; `@thebassclef/lite@1.9.11` (2026-09-15) shipped `manifest_version: "1.6.1"`. Regression traced to commit `d59a3dfe` (PR #2135 prior session). cli bundler at `scripts/prepublish-bundle-substrate.mjs:69` enforces EXPECTED_LITE_MANIFEST_MAJOR=1; rejects v1.9.2.
+- **Downstream cure:** no action for adopters at non-pin. cli bundler now reads a valid major digit; downstream readers that keyed on `manifest_version` get a non-zero value again.
+- **Old shape retired:** nothing retired. v1.9.2's broken shape stays on tag v1.9.2; v1.9.3 supersedes.
+- **Follow-on filed:** regression class caught by Tier 0 Test 50 in `.claude/hooks/tests/generate-lite-manifest.test.sh`. Generator fallback safety guard filed as sister ticket (prevents 0.0.0 from compounding across chained regens again).
+
+
+### bassclef-upstream#2140 — generator scans skill-helper subscripts (v1.16.10 → v1.17.0, 2026-10-08)
+
+- **Change type:** content-add (1 new lite entry: `.claude/skills/onboard-repo/write-state-marker.sh` as type=script). Generator extended to scan `.claude/skills/*/*.sh` for skill-helper subscripts; emits them as existing type=script (no schema enum change).
+- **Fields:** 448 → 449 entries (+1 at lite tier). Schema shape unchanged. The 2 sibling helpers at `.claude/skills/onboard-repo/` stay at `# tier: standard` so they don't ride into lite.
+- **Version bump:** v1.16.10 → v1.17.0 (minor — adds an entry to entries[] per policy a).
+- **Rationale:** bassclef-upstream#2140 — cold adopter 2026-10-07 ran /onboard-repo at lite tier; Phase 2.3.9 saw `cat: write-state-marker.sh: No such file` because the file was tagged standard and absent from lite manifest. Retag to lite + generator extension so lite adopters receive the helper.
+- **Downstream cure:** no action for adopters at exact-pin. Downstream readers see one additional lite-tier entry under type=script. Adopters that iterate entries[] get the extra entry without any code change.
+- **Old shape retired:** nothing retired. Content addition is additive.
+
+
 ### cli#319 — interpret-input writes intent field (v1.16.9 → v1.16.10, 2026-10-07)
 
 - **Change type:** content-change (1 file: `scripts/interpret-input.sh`). Script now emits `intent` field in input-artifact JSON. Prior shape omitted it.