@hivehub/rulebook 5.7.0 → 5.8.0

package/templates/hooks/check-context-and-handoff.sh

@@ -3,8 +3,10 @@
 #
 # Runs after every model turn. Estimates the current context usage
 # from the JSONL transcript and, when it exceeds the configured
-# threshold, emits additionalContext instructing the model to invoke
-# the /handoff skill and tell the user to type /clear.
+# threshold, instructs the model to invoke the /handoff skill and tell
+# the user to type /clear. The Stop event has no `additionalContext`
+# field, so force mode uses `decision:"block"`+`reason` (fed to the
+# model) and warn mode uses `systemMessage` (surfaced to the user).
 #
 # Thresholds are read from .rulebook/rulebook.json `handoff` section.
 # Defaults: warn=75, force=90 (percentage of estimated max context).
@@ -62,11 +64,19 @@ if [[ "$pct" -ge "$FORCE_PCT" ]]; then
   # Force mode: write urgent sentinel + emit strong instruction
   mkdir -p "$HANDOFF_DIR"
   touch "${HANDOFF_DIR}/.urgent"
-  msg="⚠️ CONTEXT AT ${pct}% (FORCE THRESHOLD). You MUST invoke /handoff NOW to save session state to .rulebook/handoff/_pending.md. After it succeeds, tell the user: '>>> TYPE /clear NOW — your context will be auto-restored in the next session <<<'. Do NOT continue working until the user has typed /clear."
-  jq -nc --arg msg "$msg" '{ hookSpecificOutput: { hookEventName: "Stop", additionalContext: $msg } }'
+  # Block exactly once: drive the model to invoke /handoff. After the handoff
+  # file exists, switch to a non-blocking systemMessage so we don't trap the
+  # model in a stop-loop that burns context at the worst possible moment.
+  if [[ -f "${HANDOFF_DIR}/_pending.md" ]]; then
+    msg="⚠️ CONTEXT AT ${pct}% — handoff already saved to .rulebook/handoff/_pending.md. >>> TYPE /clear NOW — your context will be auto-restored in the next session <<<"
+    jq -nc --arg msg "$msg" '{ systemMessage: $msg }'
+  else
+    msg="⚠️ CONTEXT AT ${pct}% (FORCE THRESHOLD). You MUST invoke /handoff NOW to save session state to .rulebook/handoff/_pending.md. After it succeeds, tell the user: '>>> TYPE /clear NOW — your context will be auto-restored in the next session <<<'. Do NOT continue working until the user has typed /clear."
+    jq -nc --arg msg "$msg" '{ decision: "block", reason: $msg }'
+  fi
 elif [[ "$pct" -ge "$WARN_PCT" ]]; then
-  msg="⚠️ Context at ${pct}%. Recommended: invoke /handoff to save session state. After it succeeds, tell the user to type /clear for a fresh session."
-  jq -nc --arg msg "$msg" '{ hookSpecificOutput: { hookEventName: "Stop", additionalContext: $msg } }'
+  msg="⚠️ Context at ${pct}%. Recommended: invoke /handoff to save session state, then type /clear for a fresh session."
+  jq -nc --arg msg "$msg" '{ systemMessage: $msg }'
 else
   # Below threshold — no-op
   printf '%s' '{}'

package/templates/hooks/update-check.ps1

@@ -0,0 +1,84 @@
+# Claude Code SessionStart hook — rulebook update check (Windows).
+#
+# Mirrors templates/hooks/update-check.sh: compares the project's installed
+# rulebook version (.rulebook/rulebook.json -> version) against the latest
+# @hivehub/rulebook on npm, cached 24h in .rulebook/.update-check. Emits an
+# additionalContext advisory when a newer version exists, else `{}`.
+
+$ErrorActionPreference = 'SilentlyContinue'
+
+function Emit-None { Write-Output '{}'; exit 0 }
+
+# Resolve project root from stdin JSON cwd, else env, else pwd.
+$inputRaw = $null
+if ([Console]::IsInputRedirected) { try { $inputRaw = [Console]::In.ReadToEnd() } catch { } }
+$projectRoot = $null
+if ($inputRaw) { try { $projectRoot = (ConvertFrom-Json $inputRaw).cwd } catch { } }
+if (-not $projectRoot) {
+  if ($env:CLAUDE_PROJECT_DIR) { $projectRoot = $env:CLAUDE_PROJECT_DIR }
+  else { $projectRoot = (Get-Location).Path }
+}
+
+$configFile = Join-Path $projectRoot '.rulebook/rulebook.json'
+$cacheFile  = Join-Path $projectRoot '.rulebook/.update-check'
+$pkg = '@hivehub/rulebook'
+$cacheTtl = 86400
+
+if (-not (Test-Path $configFile)) { Emit-None }
+
+$config = $null
+try { $config = Get-Content -Raw $configFile | ConvertFrom-Json } catch { Emit-None }
+$installed = $config.version
+if (-not $installed) { Emit-None }
+if ($config.updateCheck -and $config.updateCheck.enabled -eq $false) { Emit-None }
+
+$now = [int][double]::Parse((Get-Date -UFormat %s))
+$latest = $null
+$cacheTs = 0
+if (Test-Path $cacheFile) {
+  try {
+    $cache = Get-Content -Raw $cacheFile | ConvertFrom-Json
+    $cacheTs = [int]$cache.checkedAt
+    $latest = $cache.latest
+  } catch { }
+}
+
+$age = $now - $cacheTs
+if (-not $latest -or $age -ge $cacheTtl) {
+  $fetched = $null
+  try {
+    $job = Start-Job { param($p) npm view $p version 2>$null } -ArgumentList $pkg
+    if (Wait-Job $job -Timeout 5) { $fetched = (Receive-Job $job) }
+    Remove-Job $job -Force
+  } catch { }
+  if ($fetched) {
+    $latest = ("$fetched").Trim()
+    try {
+      [IO.File]::WriteAllText($cacheFile, (@{ latest = $latest; checkedAt = $now } | ConvertTo-Json -Compress))
+    } catch { }
+  }
+}
+
+if (-not $latest) { Emit-None }
+
+function Ver-Gt([string]$a, [string]$b) {
+  $aa = ($a -split '-')[0]; $bb = ($b -split '-')[0]
+  $A = $aa -split '\.'; $B = $bb -split '\.'
+  for ($i = 0; $i -lt 3; $i++) {
+    $ai = 0; $bi = 0
+    if ($A[$i]) { [int]::TryParse(($A[$i] -replace '[^0-9]', ''), [ref]$ai) | Out-Null }
+    if ($B[$i]) { [int]::TryParse(($B[$i] -replace '[^0-9]', ''), [ref]$bi) | Out-Null }
+    if ($ai -gt $bi) { return $true }
+    if ($ai -lt $bi) { return $false }
+  }
+  return $false
+}
+
+if (Ver-Gt $latest $installed) {
+  $ctx = "## Rulebook update available`n`nThis project is on rulebook **$installed**, but **$latest** is published on npm.`n`nAsk the user whether they want to update. If they agree, run ``rulebook update`` (or ``npx $pkg@latest update``) to regenerate the rules to the latest version, then review the diff before committing. Do not update without the user's confirmation."
+  $out = @{ hookSpecificOutput = @{ hookEventName = 'SessionStart'; additionalContext = $ctx } }
+  Write-Output ($out | ConvertTo-Json -Compress -Depth 4)
+  exit 0
+}
+
+Emit-None

package/templates/hooks/update-check.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# Claude Code SessionStart hook — rulebook update check.
+#
+# Compares the project's installed rulebook version (.rulebook/rulebook.json
+# → version) against the latest published @hivehub/rulebook on npm. When a
+# newer version exists, emits an additionalContext advisory so Claude can
+# offer to run `rulebook update`. The npm lookup is cached for 24h in
+# .rulebook/.update-check to keep session start fast and offline-friendly.
+#
+# Emits `{}` (no-op) on any of: no config, no network/npm, already current,
+# cache still fresh with no known update, or any error. Never blocks startup.
+
+set -euo pipefail
+
+# --- Resolve project root (from stdin JSON cwd, else env, else pwd) ----------
+input="$(cat || true)"
+PROJECT_ROOT=""
+if [[ -n "$input" ]] && command -v jq &>/dev/null; then
+  PROJECT_ROOT="$(printf '%s' "$input" | jq -r '.cwd // empty' 2>/dev/null || true)"
+fi
+[[ -z "$PROJECT_ROOT" ]] && PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+CONFIG_FILE="${PROJECT_ROOT}/.rulebook/rulebook.json"
+CACHE_FILE="${PROJECT_ROOT}/.rulebook/.update-check"
+PKG="@hivehub/rulebook"
+CACHE_TTL=86400 # 24h in seconds
+
+emit_none() { printf '%s' '{}'; exit 0; }
+
+# Need jq + a config to do anything useful.
+command -v jq &>/dev/null || emit_none
+[[ -f "$CONFIG_FILE" ]] || emit_none
+
+installed="$(jq -r '.version // empty' "$CONFIG_FILE" 2>/dev/null || true)"
+[[ -z "$installed" ]] && emit_none
+
+# Allow opt-out via config: { "updateCheck": { "enabled": false } }.
+# Note: jq's `//` treats `false` as empty, so `.updateCheck.enabled // true`
+# would wrongly yield true when explicitly disabled — test the value directly.
+enabled="$(jq -r 'if .updateCheck.enabled == false then "false" else "true" end' "$CONFIG_FILE" 2>/dev/null || echo true)"
+[[ "$enabled" == "false" ]] && emit_none
+
+# --- Determine latest version (cache-first) ---------------------------------
+now="$(date -u +%s)"
+latest=""
+cache_ts=0
+if [[ -f "$CACHE_FILE" ]]; then
+  cache_ts="$(jq -r '.checkedAt // 0' "$CACHE_FILE" 2>/dev/null || echo 0)"
+  latest="$(jq -r '.latest // empty' "$CACHE_FILE" 2>/dev/null || true)"
+fi
+
+age=$(( now - cache_ts ))
+if [[ -z "$latest" || "$age" -ge "$CACHE_TTL" ]]; then
+  # Cache miss or stale — query npm with a hard timeout so startup never hangs.
+  fetched=""
+  if command -v npm &>/dev/null; then
+    if command -v timeout &>/dev/null; then
+      fetched="$(timeout 5 npm view "$PKG" version 2>/dev/null || true)"
+    else
+      fetched="$(npm view "$PKG" version 2>/dev/null || true)"
+    fi
+  fi
+  if [[ -n "$fetched" ]]; then
+    latest="$fetched"
+    # Refresh cache (best-effort; ignore write failures).
+    jq -nc --arg l "$latest" --argjson t "$now" \
+      '{latest: $l, checkedAt: $t}' > "$CACHE_FILE" 2>/dev/null || true
+  fi
+fi
+
+# No latest resolved (offline / first run with no network) — no-op.
+[[ -z "$latest" ]] && emit_none
+
+# --- Compare semver (numeric major.minor.patch, ignoring pre-release) -------
+ver_gt() {
+  # returns 0 (true) if $1 > $2
+  local a="${1%%-*}" b="${2%%-*}"
+  local IFS=.
+  # shellcheck disable=SC2206
+  local A=($a) B=($b)
+  for i in 0 1 2; do
+    local ai="${A[i]:-0}" bi="${B[i]:-0}"
+    # Strip non-numeric just in case.
+    ai="${ai//[!0-9]/}"; bi="${bi//[!0-9]/}"
+    ai="${ai:-0}"; bi="${bi:-0}"
+    if (( ai > bi )); then return 0; fi
+    if (( ai < bi )); then return 1; fi
+  done
+  return 1
+}
+
+if ver_gt "$latest" "$installed"; then
+  ctx="## Rulebook update available\n\nThis project is on rulebook **${installed}**, but **${latest}** is published on npm.\n\nAsk the user whether they want to update. If they agree, run \`rulebook update\` (or \`npx ${PKG}@latest update\`) to regenerate the rules to the latest version, then review the diff before committing. Do not update without the user's confirmation."
+  jq -nc --arg ctx "$ctx" '{
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: $ctx
+    }
+  }'
+  exit 0
+fi
+
+emit_none

package/templates/ides/CONTINUE_RULES.md

@@ -1,16 +1,16 @@
-<!-- RULEBOOK:START -->
-# Continue.dev — Code Assistant Rules
-
-## Context Loading
-- Always read AGENTS.md before making changes
-- Check `.rulebook/specs/` for relevant spec files
-
-## Code Standards
-- Match existing code style and conventions
-- Prefer editing existing files over creating new ones
-- Add types for all new parameters and return values
-
-## Testing
-- Write tests for every new function
-- Run existing tests after changes to verify no regressions
-<!-- RULEBOOK:END -->
+<!-- RULEBOOK:START -->
+# Continue.dev — Code Assistant Rules
+
+## Context Loading
+- Always read AGENTS.md before making changes
+- Check `.rulebook/specs/` for relevant spec files
+
+## Code Standards
+- Match existing code style and conventions
+- Prefer editing existing files over creating new ones
+- Add types for all new parameters and return values
+
+## Testing
+- Write tests for every new function
+- Run existing tests after changes to verify no regressions
+<!-- RULEBOOK:END -->

package/templates/ides/COPILOT_INSTRUCTIONS.md

@@ -1,23 +1,23 @@
-<!-- RULEBOOK:START -->
-# GitHub Copilot — Project Instructions
-
-## Code Style
-- Use TypeScript with strict mode
-- Follow existing naming conventions (camelCase functions, PascalCase classes)
-- Prefer `async/await` over callbacks or raw Promises
-
-## Architecture
-- Follow the module structure described in AGENTS.md
-- Keep functions small and focused (single responsibility)
-- Use dependency injection over direct imports where possible
-
-## Testing
-- Write Vitest tests for all new functions
-- Place tests in `tests/` directory, not alongside source files
-- Mock external dependencies in unit tests
-
-## Security
-- Never commit credentials or API keys
-- Validate all external input at system boundaries
-- Follow OWASP top 10 guidelines
-<!-- RULEBOOK:END -->
+<!-- RULEBOOK:START -->
+# GitHub Copilot — Project Instructions
+
+## Code Style
+- Use TypeScript with strict mode
+- Follow existing naming conventions (camelCase functions, PascalCase classes)
+- Prefer `async/await` over callbacks or raw Promises
+
+## Architecture
+- Follow the module structure described in AGENTS.md
+- Keep functions small and focused (single responsibility)
+- Use dependency injection over direct imports where possible
+
+## Testing
+- Write Vitest tests for all new functions
+- Place tests in `tests/` directory, not alongside source files
+- Mock external dependencies in unit tests
+
+## Security
+- Never commit credentials or API keys
+- Validate all external input at system boundaries
+- Follow OWASP top 10 guidelines
+<!-- RULEBOOK:END -->

package/templates/ides/GEMINI_RULES.md

@@ -1,17 +1,17 @@
-<!-- RULEBOOK:START -->
-# Gemini CLI — Project Directives
-
-## Code Generation Rules
-- Generate TypeScript with strict mode enabled
-- Follow existing file and function naming conventions
-- Always add error handling for async operations
-- Generate tests alongside implementation code
-
-## Quality Standards
-- All code must pass TypeScript type-check
-- All code must pass ESLint without warnings
-- Test coverage must meet project thresholds
-
-## Project Context
-See AGENTS.md for full project architecture and team conventions.
-<!-- RULEBOOK:END -->
+<!-- RULEBOOK:START -->
+# Gemini CLI — Project Directives
+
+## Code Generation Rules
+- Generate TypeScript with strict mode enabled
+- Follow existing file and function naming conventions
+- Always add error handling for async operations
+- Generate tests alongside implementation code
+
+## Quality Standards
+- All code must pass TypeScript type-check
+- All code must pass ESLint without warnings
+- Test coverage must meet project thresholds
+
+## Project Context
+See AGENTS.md for full project architecture and team conventions.
+<!-- RULEBOOK:END -->

package/templates/ides/WINDSURF_RULES.md

@@ -1,14 +1,14 @@
-<!-- RULEBOOK:START -->
-# Windsurf — Project Rules
-
-You are an AI assistant for this project. Follow these rules:
-
-1. Read AGENTS.md for full project context before starting any task
-2. Never create files in the root unless explicitly asked
-3. All TypeScript must be strict-mode compatible
-4. Write tests for new functionality
-5. Run quality checks before marking work complete
-
-## Project Structure
-Follow the existing directory structure. See AGENTS.md for details.
-<!-- RULEBOOK:END -->
+<!-- RULEBOOK:START -->
+# Windsurf — Project Rules
+
+You are an AI assistant for this project. Follow these rules:
+
+1. Read AGENTS.md for full project context before starting any task
+2. Never create files in the root unless explicitly asked
+3. All TypeScript must be strict-mode compatible
+4. Write tests for new functionality
+5. Run quality checks before marking work complete
+
+## Project Structure
+Follow the existing directory structure. See AGENTS.md for details.
+<!-- RULEBOOK:END -->