@rulemetric/hooks 0.7.41 → 0.7.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulemetric/hooks",
-  "version": "0.7.41",
+  "version": "0.7.43",
   "publishConfig": {
     "access": "public"
   },

package/scripts/session-start.sh

@@ -124,35 +124,124 @@ _rulemetric_suggest_instructions() {
   # suggestions arrive with the actual rule body. The body is rendered to
   # stdout, which Claude Code surfaces to the model as session context.
   # Low-confidence suggestions still render as name+reason only.
+  # limit=10 (the API's clamp), not 3. The feed now carries THREE directions
+  # ranked by one score, and a trim scores 0.55 — below every add and every
+  # removal — so a shallow fetch would sort it off the end and the trim
+  # direction would appear to produce nothing. Fetching the maximum and capping
+  # per direction below is what keeps the weakest signal reachable. It is still
+  # possible for a project with >10 pending adds to crowd the trim out; that is
+  # accepted, it is the softest row in the feed.
+  # The feed carries BOTH directions ranked by one score,
+  # and a measured-harmful retirement can score up to 0.95 — so at limit=3 a bad
+  # week of grooming would evict every adoption proposal and the additive feed
+  # would silently go to zero. Over-fetch, then cap each direction separately
+  # below so neither can starve the other.
   response="$(curl -s --noproxy '*' --max-time 4 \
-    "${api_url}/api/instruction-suggestions?projectPath=${encoded_path}&limit=3&includeContent=true" \
+    "${api_url}/api/instruction-suggestions?projectPath=${encoded_path}&limit=10&includeContent=true&groupByKind=true" \
     -H "Authorization: Bearer ${auth_token}" 2>/dev/null)" || return 0
 
   local count
   count="$(printf '%s' "$response" | jq -r '.suggestions | length' 2>/dev/null)" || return 0
   [ "$count" != "0" ] && [ "$count" != "null" ] && [ -n "$count" ] || return 0
 
-  # Count high-confidence rows (those with non-null content) for the header
+  # Per-direction index lists, capped independently. `kind` is absent on an older
+  # API, so an untagged row is an adoption proposal — the historical behaviour.
+  local add_idx rem_idx trim_idx render_idx
+  add_idx="$(printf '%s' "$response" | jq -r \
+    '[.suggestions | to_entries[] | select((.value.kind // "add") == "add") | .key][0:3] | .[]' 2>/dev/null)" || add_idx=""
+  rem_idx="$(printf '%s' "$response" | jq -r \
+    '[.suggestions | to_entries[] | select(.value.kind == "remove") | .key][0:2] | .[]' 2>/dev/null)" || rem_idx=""
+  trim_idx="$(printf '%s' "$response" | jq -r \
+    '[.suggestions | to_entries[] | select(.value.kind == "trim") | .key][0:1] | .[]' 2>/dev/null)" || trim_idx=""
+  render_idx="$(printf '%s\n%s\n%s\n' "$add_idx" "$rem_idx" "$trim_idx" | grep -v '^$' || true)"
+  [ -n "$render_idx" ] || return 0
+
+  # Count high-confidence rows among the ADDS WE WILL ACTUALLY RENDER. Counting
+  # the whole response over-counts now that the fetch pulls 6 to cap 3+2: the
+  # header announced "5 high-confidence instruction(s) included below" with 3
+  # below it. A header that miscounts what follows it is how a reader stops
+  # trusting the block.
   local high_count
-  high_count="$(printf '%s' "$response" | jq -r '[.suggestions[] | select(.content != null)] | length' 2>/dev/null)" || high_count="0"
+  high_count="$(printf '%s' "$response" | jq -r \
+    '[[.suggestions | to_entries[] | select((.value.kind // "add") == "add")][0:3][] | select(.value.content != null)] | length' 2>/dev/null)" || high_count="0"
+  # ONE count for the shared "costing you" header. Counting only removals would
+  # under-report the moment a trim renders beneath the same heading — the same
+  # header-miscounts-its-own-list bug just fixed above, reintroduced by a third
+  # direction.
+  local rem_count trim_count cost_count
+  rem_count="$(printf '%s\n' "$rem_idx" | grep -c '[0-9]' 2>/dev/null)" || rem_count=0
+  trim_count="$(printf '%s\n' "$trim_idx" | grep -c '[0-9]' 2>/dev/null)" || trim_count=0
+  cost_count=$((rem_count + trim_count))
+
+  # The header describes the ADDITIVE rows only. `count` is now a mixed total, so
+  # using it here would announce "N instructions may help with this project" and
+  # then list retirements underneath it.
+  local add_count
+  add_count="$(printf '%s\n' "$add_idx" | grep -c '[0-9]' 2>/dev/null)" || add_count=0
 
   printf '\n---\n'
   if [ "$high_count" != "0" ] && [ -n "$high_count" ]; then
     printf '[rulemetric] %s high-confidence instruction(s) included below as session context.\n' "$high_count"
     printf 'Accept any of them permanently with the command shown under each one.\n'
-  else
-    printf '[rulemetric] %s instruction(s) may help with this project:\n' "$count"
+  elif [ "$add_count" != "0" ]; then
+    printf '[rulemetric] %s instruction(s) may help with this project:\n' "$add_count"
   fi
 
-  local i=0
-  while [ "$i" -lt "$count" ]; do
-    local name reason score scope content sid
+  local rendered_removal_header=0
+  local i
+  for i in $render_idx; do
+    local name reason score scope content sid kind tokens
     name="$(printf '%s' "$response"  | jq -r ".suggestions[$i].name"             2>/dev/null)" || break
     reason="$(printf '%s' "$response" | jq -r ".suggestions[$i].reason"          2>/dev/null)" || break
     score="$(printf '%s' "$response"  | jq -r ".suggestions[$i].score"           2>/dev/null)" || break
     scope="$(printf '%s' "$response"  | jq -r ".suggestions[$i].instructionScope" 2>/dev/null)" || break
     content="$(printf '%s' "$response" | jq -r ".suggestions[$i].content // empty" 2>/dev/null)" || content=""
     sid="$(printf '%s' "$response"    | jq -r ".suggestions[$i].id"             2>/dev/null)" || break
+    kind="$(printf '%s' "$response"   | jq -r ".suggestions[$i].kind // \"add\"" 2>/dev/null)" || kind="add"
+    tokens="$(printf '%s' "$response" | jq -r ".suggestions[$i].estimatedTokens // empty" 2>/dev/null)" || tokens=""
+
+    if [ "$kind" = "trim" ]; then
+      # Shares the cost heading with retirements — both are "this is charging
+      # you context" — but never the verb. Neutral means no effect was
+      # DETECTED, which is not evidence the rule is worthless, so the ask is
+      # "shorten", never "delete".
+      if [ "$rendered_removal_header" = "0" ]; then
+        printf '\n[rulemetric] %s instruction(s) look like they are costing you more than they return:\n' "$cost_count"
+        rendered_removal_header=1
+      fi
+      if [ -n "$tokens" ] && [ "$tokens" != "null" ]; then
+        printf '  - TRIM   [%s] %s (~%s tokens/session, measures neutral)\n    %s\n' "$scope" "$name" "$tokens" "$reason"
+      else
+        printf '  - TRIM   [%s] %s (measures neutral)\n    %s\n' "$scope" "$name" "$reason"
+      fi
+      if [ -n "$sid" ] && [ "$sid" != "null" ]; then
+        printf '    Acknowledge: rulemetric suggestions accept %s   (no automatic change; shorten it yourself)\n' "$sid"
+      fi
+      continue
+    fi
+
+    if [ "$kind" = "remove" ]; then
+      # Retirements get their own labelled section and their own verb. Rendered
+      # in the additive shape they would read as "adopt this" to both the human
+      # and the model — the same text that has always meant "add" would now
+      # sometimes mean "delete", which is how someone archives a rule they meant
+      # to keep. The body is deliberately NOT here: the API withholds content for
+      # this direction, so proposing a retirement never pays the cost of the rule
+      # it is proposing to retire.
+      if [ "$rendered_removal_header" = "0" ]; then
+        printf '\n[rulemetric] %s instruction(s) look like they are costing you more than they return:\n' "$cost_count"
+        rendered_removal_header=1
+      fi
+      if [ -n "$tokens" ] && [ "$tokens" != "null" ]; then
+        printf '  - RETIRE [%s] %s (~%s tokens/session)\n    %s\n' "$scope" "$name" "$tokens" "$reason"
+      else
+        printf '  - RETIRE [%s] %s\n    %s\n' "$scope" "$name" "$reason"
+      fi
+      if [ -n "$sid" ] && [ "$sid" != "null" ]; then
+        printf '    Retire it: rulemetric suggestions accept %s   (archives it; undo: rulemetric instructions restore <instruction-id>)\n' "$sid"
+      fi
+      continue
+    fi
 
     if [ -n "$content" ]; then
       printf '\n## Skill: %s (%s, score: %s)\n%s\n\n%s\n' "$name" "$scope" "$score" "$reason" "$content"
@@ -167,16 +256,18 @@ _rulemetric_suggest_instructions() {
     if [ -n "$sid" ] && [ "$sid" != "null" ]; then
       printf '    Accept: rulemetric suggestions accept %s\n' "$sid"
     fi
-    i=$((i + 1))
   done
 
   printf '\n---\n'
 
   # Log surfaced events fire-and-forget. Event type differs based on whether
   # the full content was included so we can later measure outcome differences.
-  i=0
+  # Only the rows actually rendered. Iterating 0..count would log a `surfaced`
+  # event for suggestions the over-fetch pulled but the per-direction caps never
+  # showed — inflating the denominator of the exact acceptance rate this feed
+  # exists to measure.
   local tool="${HOOK_TOOL:-unknown}"
-  while [ "$i" -lt "$count" ]; do
+  for i in $render_idx; do
     local sid has_content event_type
     sid="$(printf '%s' "$response" | jq -r ".suggestions[$i].id" 2>/dev/null)" || break
     has_content="$(printf '%s' "$response" | jq -r ".suggestions[$i].content // \"null\"" 2>/dev/null)" || has_content="null"
@@ -200,7 +291,6 @@ _rulemetric_suggest_instructions() {
         '{eventType: $eventType, tool: $tool, projectPath: $projectPath, sessionId: $sessionId}')" \
       >/dev/null 2>&1 &
     disown 2>/dev/null || true
-    i=$((i + 1))
   done
 }