@hivehub/rulebook 5.2.1 → 5.3.0

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

@@ -0,0 +1,50 @@
+# Claude Code Stop hook — context freshness monitor (PowerShell).
+# See check-context-and-handoff.sh for the full design rationale.
+
+$ErrorActionPreference = 'Stop'
+
+$ProjectRoot = Get-Location
+$ConfigFile = Join-Path $ProjectRoot '.rulebook/rulebook.json'
+$HandoffDir = Join-Path $ProjectRoot '.rulebook/handoff'
+
+$WarnPct = 75
+$ForcePct = 90
+$MaxContextChars = 800000
+
+if (Test-Path $ConfigFile) {
+    try {
+        $cfg = Get-Content $ConfigFile -Raw | ConvertFrom-Json
+        if ($cfg.handoff.warnThresholdPct) { $WarnPct = $cfg.handoff.warnThresholdPct }
+        if ($cfg.handoff.forceThresholdPct) { $ForcePct = $cfg.handoff.forceThresholdPct }
+    } catch {}
+}
+
+$TranscriptSize = 0
+$ClaudeDir = Join-Path $env:USERPROFILE '.claude/projects'
+if (Test-Path $ClaudeDir) {
+    $latest = Get-ChildItem $ClaudeDir -Recurse -Filter '*.jsonl' -File |
+        Sort-Object LastWriteTime -Descending | Select-Object -First 1
+    if ($latest) { $TranscriptSize = $latest.Length }
+}
+
+if ($TranscriptSize -eq 0) {
+    Write-Output '{}'
+    exit 0
+}
+
+$Pct = [math]::Floor($TranscriptSize * 100 / $MaxContextChars)
+
+if ($Pct -ge $ForcePct) {
+    if (-not (Test-Path $HandoffDir)) { New-Item -ItemType Directory -Path $HandoffDir -Force | Out-Null }
+    New-Item -ItemType File -Path (Join-Path $HandoffDir '.urgent') -Force | Out-Null
+    $msg = "CONTEXT AT ${Pct}% (FORCE THRESHOLD). You MUST invoke /handoff NOW."
+    $out = @{ hookSpecificOutput = @{ hookEventName = 'Stop'; additionalContext = $msg } } | ConvertTo-Json -Compress -Depth 4
+    Write-Output $out
+} elseif ($Pct -ge $WarnPct) {
+    $msg = "Context at ${Pct}%. Recommended: invoke /handoff to save session state."
+    $out = @{ hookSpecificOutput = @{ hookEventName = 'Stop'; additionalContext = $msg } } | ConvertTo-Json -Compress -Depth 4
+    Write-Output $out
+} else {
+    Write-Output '{}'
+}
+exit 0

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

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# Claude Code Stop hook — context freshness monitor.
+#
+# 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.
+#
+# Thresholds are read from .rulebook/rulebook.json `handoff` section.
+# Defaults: warn=75, force=90 (percentage of estimated max context).
+
+set -euo pipefail
+
+PROJECT_ROOT="$(pwd)"
+CONFIG_FILE="${PROJECT_ROOT}/.rulebook/rulebook.json"
+HANDOFF_DIR="${PROJECT_ROOT}/.rulebook/handoff"
+
+# Defaults
+WARN_PCT=75
+FORCE_PCT=90
+MAX_CONTEXT_CHARS=800000  # ~200k tokens ≈ 800k chars (rough 1:4 ratio)
+
+# Override from config if available
+if [[ -f "$CONFIG_FILE" ]] && command -v jq &>/dev/null; then
+  WARN_PCT=$(jq -r '.handoff.warnThresholdPct // 75' "$CONFIG_FILE" 2>/dev/null || echo 75)
+  FORCE_PCT=$(jq -r '.handoff.forceThresholdPct // 90' "$CONFIG_FILE" 2>/dev/null || echo 90)
+fi
+
+# Read the hook input from stdin (Claude Code passes it as JSON)
+input="$(cat)"
+
+# Try to find the transcript path from the session
+# Claude Code stores transcripts as JSONL in ~/.claude/projects/<hash>/
+# The hook input may or may not contain session info; we fall back to
+# estimating from the input itself.
+transcript_size=0
+
+# Strategy 1: check the most recent JSONL in the project-specific Claude dir
+CLAUDE_PROJECTS_DIR="${HOME}/.claude/projects"
+if [[ -d "$CLAUDE_PROJECTS_DIR" ]]; then
+  latest_jsonl=$(find "$CLAUDE_PROJECTS_DIR" -name "*.jsonl" -type f -printf '%T@ %p\n' 2>/dev/null | sort -rn | head -1 | awk '{print $2}' || true)
+  if [[ -n "$latest_jsonl" && -f "$latest_jsonl" ]]; then
+    transcript_size=$(stat -c%s "$latest_jsonl" 2>/dev/null || stat -f%z "$latest_jsonl" 2>/dev/null || echo 0)
+  fi
+fi
+
+# If we couldn't get transcript size, emit nothing (no-op)
+if [[ "$transcript_size" -eq 0 ]]; then
+  printf '%s' '{}'
+  exit 0
+fi
+
+# Estimate context percentage
+pct=$(( transcript_size * 100 / MAX_CONTEXT_CHARS ))
+
+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 } }'
+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 } }'
+else
+  # Below threshold — no-op
+  printf '%s' '{}'
+fi
+exit 0

package/templates/hooks/enforce-mcp-for-tasks.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# PreToolUse hook: deny manual task file creation — must use MCP tools
+set -euo pipefail
+input="$(cat)"
+
+result="$(node -e "
+const input = JSON.parse(process.argv[1]);
+const tool = input.tool_name || '';
+if (tool === 'Write' || tool === 'Edit') {
+  const file = input.tool_input?.file_path || input.tool_input?.filePath || '';
+  // Block creating new proposal.md or .metadata.json in tasks/
+  if (/\.rulebook\/tasks\/[^/]+\/(proposal\.md|\.metadata\.json)$/.test(file.replace(/\\\\/g,'/'))) {
+    // Allow if editing existing file
+    try { require('fs').accessSync(file); console.log('ALLOW'); } catch { console.log('DENY'); }
+    process.exit(0);
+  }
+} else if (tool === 'Bash') {
+  const cmd = input.tool_input?.command || '';
+  if (/mkdir.*\.rulebook\/tasks\//.test(cmd) || /mkdir.*\.rulebook\\\\tasks\\\\/.test(cmd)) {
+    console.log('DENY');
+    process.exit(0);
+  }
+}
+console.log('ALLOW');
+" "$input" 2>/dev/null || echo "ALLOW")"
+
+if [[ "$result" == "DENY" ]]; then
+  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"DENIED: task files must be created via rulebook_task_create MCP tool, not manually. Use: rulebook_task_create({ taskId: phase1_your-task-name })"}}'
+else
+  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
+fi

package/templates/hooks/enforce-no-deferred.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# PreToolUse hook: deny deferred/TODO/skip items in tasks.md
+set -euo pipefail
+input="$(cat)"
+
+# Parse JSON with node (jq may not be available on Windows)
+result="$(node -e "
+const input = JSON.parse(process.argv[1]);
+const tool = input.tool_name || '';
+if (tool !== 'Edit' && tool !== 'Write') { console.log('ALLOW'); process.exit(0); }
+const file = input.tool_input?.file_path || input.tool_input?.filePath || '';
+if (!file.endsWith('tasks.md')) { console.log('ALLOW'); process.exit(0); }
+const content = input.tool_input?.new_string || input.tool_input?.content || '';
+if (/\b(deferred|skip(ped)?|later|todo)\b/i.test(content)) { console.log('DENY'); } else { console.log('ALLOW'); }
+" "$input" 2>/dev/null || echo "ALLOW")"
+
+if [[ "$result" == "DENY" ]]; then
+  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"DENIED: tasks.md cannot contain deferred, skip, later, or TODO. Implement the item now or explain why impossible. See .claude/rules/no-deferred.md"}}'
+else
+  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
+fi

package/templates/hooks/enforce-no-shortcuts.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# PreToolUse hook: deny stubs, TODOs, placeholders in source code
+set -euo pipefail
+input="$(cat)"
+
+result="$(node -e "
+const input = JSON.parse(process.argv[1]);
+const tool = input.tool_name || '';
+if (tool !== 'Edit' && tool !== 'Write') { console.log('ALLOW'); process.exit(0); }
+const file = input.tool_input?.file_path || input.tool_input?.filePath || '';
+// Only check source files
+if (!/\.(ts|tsx|js|jsx|py|rs|go|java|cs|cpp|c|hpp|h)$/.test(file)) { console.log('ALLOW'); process.exit(0); }
+// Skip test files
+if (/\.test\.|\.spec\.|__tests__|\/tests\//.test(file)) { console.log('ALLOW'); process.exit(0); }
+const content = input.tool_input?.new_string || input.tool_input?.content || '';
+if (/\/\/\s*(TODO|FIXME|HACK)\b|\/\*\s*(TODO|FIXME|HACK)\b|#\s*(TODO|FIXME|HACK)\b/.test(content)) { console.log('DENY_TODO'); process.exit(0); }
+if (/\bplaceholder\b|\bstub\b/i.test(content)) { console.log('DENY_STUB'); process.exit(0); }
+console.log('ALLOW');
+" "$input" 2>/dev/null || echo "ALLOW")"
+
+case "$result" in
+  DENY_TODO)
+    echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"DENIED: source code cannot contain // TODO, // FIXME, or // HACK. Implement the logic now. See .claude/rules/no-shortcuts.md"}}'
+    ;;
+  DENY_STUB)
+    echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"DENIED: source code cannot contain placeholders or stubs. Implement real logic. See .claude/rules/no-shortcuts.md"}}'
+    ;;
+  *)
+    echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
+    ;;
+esac

package/templates/hooks/enforce-team-for-background-agents.ps1

@@ -0,0 +1,63 @@
+# Claude Code PreToolUse hook for the Agent tool (PowerShell variant).
+#
+# Policy enforced by @hivehub/rulebook v5.3.0:
+#   - A single Agent call is fine (foreground or background).
+#   - Spawning multiple standalone background Agents is FORBIDDEN.
+#     Parallel multi-agent work MUST go through a Team so agents can
+#     communicate via SendMessage.
+#
+# Block any Agent invocation with run_in_background=true UNLESS it
+# targets subagent_type=team-lead or provides a team_name. This forces
+# background parallel work through a Team.
+
+$ErrorActionPreference = 'Stop'
+
+$input = [Console]::In.ReadToEnd()
+$data = $null
+try { $data = $input | ConvertFrom-Json } catch {}
+
+$toolName = $null
+if ($data -and $data.PSObject.Properties.Name -contains 'tool_name') { $toolName = $data.tool_name }
+
+if ($toolName -ne 'Agent') {
+    Write-Output '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
+    exit 0
+}
+
+$runInBackground = $false
+$subagentType = ''
+$teamName = ''
+if ($data.tool_input) {
+    if ($data.tool_input.PSObject.Properties.Name -contains 'run_in_background') {
+        $runInBackground = [bool]$data.tool_input.run_in_background
+    }
+    if ($data.tool_input.PSObject.Properties.Name -contains 'subagent_type') {
+        $subagentType = [string]$data.tool_input.subagent_type
+    }
+    if ($data.tool_input.PSObject.Properties.Name -contains 'team_name') {
+        $teamName = [string]$data.tool_input.team_name
+    }
+}
+
+if (-not $runInBackground) {
+    Write-Output '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
+    exit 0
+}
+
+if ($subagentType -eq 'team-lead' -or $teamName) {
+    Write-Output '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
+    exit 0
+}
+
+$reason = 'POLICY VIOLATION: Spawning standalone background Agents is forbidden. Multi-agent parallel work MUST use a Team so agents can communicate via SendMessage. Either (a) use TeamCreate to create a team, (b) spawn a team-lead that creates the team, or (c) set team_name on the Agent call. See .claude/rules/multi-agent-teams.md for the policy.'
+
+$out = @{
+    hookSpecificOutput = @{
+        hookEventName            = 'PreToolUse'
+        permissionDecision       = 'deny'
+        permissionDecisionReason = $reason
+    }
+} | ConvertTo-Json -Compress -Depth 4
+
+Write-Output $out
+exit 0

package/templates/hooks/enforce-team-for-background-agents.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Claude Code PreToolUse hook for the Agent tool.
+#
+# Policy enforced by @hivehub/rulebook v5.3.0:
+#   - A single Agent call is fine (foreground or background).
+#   - Spawning multiple standalone Agents for parallel work is FORBIDDEN.
+#     Parallel multi-agent work MUST go through a Team so agents can
+#     communicate via SendMessage.
+#
+# Enforcement strategy:
+#   Block any Agent invocation with `run_in_background: true` UNLESS it
+#   targets `subagent_type: team-lead` or provides a `team_name`. This
+#   forces background parallel work to be coordinated through a Team.
+#
+# The hook reads the tool input JSON from stdin and emits a permission
+# decision JSON on stdout, per Claude Code's PreToolUse hook contract.
+
+set -euo pipefail
+
+input="$(cat)"
+
+tool_name="$(printf '%s' "$input" | jq -r '.tool_name // empty' 2>/dev/null || true)"
+if [[ "$tool_name" != "Agent" ]]; then
+  # Not our concern — allow.
+  printf '%s' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
+  exit 0
+fi
+
+run_in_background="$(printf '%s' "$input" | jq -r '.tool_input.run_in_background // false' 2>/dev/null || echo false)"
+subagent_type="$(printf '%s' "$input" | jq -r '.tool_input.subagent_type // empty' 2>/dev/null || true)"
+team_name="$(printf '%s' "$input" | jq -r '.tool_input.team_name // empty' 2>/dev/null || true)"
+
+# Foreground single agent → always allowed.
+if [[ "$run_in_background" != "true" ]]; then
+  printf '%s' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
+  exit 0
+fi
+
+# Background agents must be part of a team OR be the team-lead coordinator.
+if [[ "$subagent_type" == "team-lead" ]] || [[ -n "$team_name" ]]; then
+  printf '%s' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
+  exit 0
+fi
+
+# Block standalone background agent.
+reason="POLICY VIOLATION: Spawning standalone background Agents is forbidden. Multi-agent parallel work MUST use a Team so agents can communicate via SendMessage. Either (a) use TeamCreate to create a team, (b) spawn a team-lead that creates the team, or (c) set team_name on the Agent call. See .claude/rules/multi-agent-teams.md for the policy."
+
+jq -nc --arg reason "$reason" '{
+  hookSpecificOutput: {
+    hookEventName: "PreToolUse",
+    permissionDecision: "deny",
+    permissionDecisionReason: $reason
+  }
+}'
+exit 0

package/templates/hooks/on-compact-reinject.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Claude Code SessionStart hook (matcher: "compact").
+#
+# Re-injects critical architectural context after a conversation
+# compaction. Claude Code already re-loads CLAUDE.md on compact, so
+# this hook is defense-in-depth: it outputs a short, always-fresh
+# cheat sheet from `.rulebook/COMPACT_CONTEXT.md` so the model has
+# the load-bearing reminders immediately available without waiting
+# for the CLAUDE.md re-read.
+#
+# The file is user-editable. Rulebook seeds it during `init` from a
+# stack-specific template and never overwrites it afterward.
+
+set -euo pipefail
+
+PROJECT_ROOT="$(pwd)"
+CONTEXT_FILE="${PROJECT_ROOT}/.rulebook/COMPACT_CONTEXT.md"
+
+if [[ ! -f "$CONTEXT_FILE" ]]; then
+  # Nothing to inject — emit a benign empty additionalContext.
+  printf '%s' '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":""}}'
+  exit 0
+fi
+
+content="$(cat "$CONTEXT_FILE")"
+
+# Emit as additionalContext via jq so we correctly escape newlines/quotes.
+jq -nc --arg ctx "$content" '{
+  hookSpecificOutput: {
+    hookEventName: "SessionStart",
+    additionalContext: $ctx
+  }
+}'
+exit 0

package/templates/hooks/resume-from-handoff.ps1

@@ -0,0 +1,33 @@
+# Claude Code SessionStart hook — auto-restore from handoff (PowerShell).
+# See resume-from-handoff.sh for the full design rationale.
+
+$ErrorActionPreference = 'Stop'
+
+$ProjectRoot = Get-Location
+$HandoffDir = Join-Path $ProjectRoot '.rulebook/handoff'
+$Pending = Join-Path $HandoffDir '_pending.md'
+$Urgent = Join-Path $HandoffDir '.urgent'
+
+if (-not (Test-Path $Pending)) {
+    Write-Output '{}'
+    exit 0
+}
+
+$content = Get-Content $Pending -Raw
+$timestamp = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH-mm-ss')
+$archiveName = "${timestamp}.md"
+Move-Item $Pending (Join-Path $HandoffDir $archiveName) -Force
+
+if (Test-Path $Urgent) { Remove-Item $Urgent -Force }
+
+$header = "## Session restored from handoff ($archiveName)`n`n"
+$ctx = $header + $content
+$out = @{
+    hookSpecificOutput = @{
+        hookEventName = 'SessionStart'
+        additionalContext = $ctx
+    }
+} | ConvertTo-Json -Compress -Depth 4
+
+Write-Output $out
+exit 0

package/templates/hooks/resume-from-handoff.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Claude Code SessionStart hook — auto-restore from handoff.
+#
+# Checks for `.rulebook/handoff/_pending.md`. If present, emits its
+# contents as additionalContext so the new session begins with full
+# prior-session context loaded, then archives the file to
+# `.rulebook/handoff/<ISO-timestamp>.md` for history.
+
+set -euo pipefail
+
+PROJECT_ROOT="$(pwd)"
+HANDOFF_DIR="${PROJECT_ROOT}/.rulebook/handoff"
+PENDING="${HANDOFF_DIR}/_pending.md"
+URGENT="${HANDOFF_DIR}/.urgent"
+CONFIG_FILE="${PROJECT_ROOT}/.rulebook/rulebook.json"
+
+# No pending handoff — nothing to inject
+if [[ ! -f "$PENDING" ]]; then
+  printf '%s' '{}'
+  exit 0
+fi
+
+content="$(cat "$PENDING")"
+
+# Archive the pending file with ISO timestamp
+timestamp=$(date -u +"%Y-%m-%dT%H-%M-%S")
+archive_name="${timestamp}.md"
+mv "$PENDING" "${HANDOFF_DIR}/${archive_name}"
+
+# Clear urgent sentinel if present
+rm -f "$URGENT"
+
+# Prune old handoff files (keep max N, default 50)
+max_history=50
+if [[ -f "$CONFIG_FILE" ]] && command -v jq &>/dev/null; then
+  max_history=$(jq -r '.handoff.maxHistoryFiles // 50' "$CONFIG_FILE" 2>/dev/null || echo 50)
+fi
+
+# Count and prune (oldest first, skip _pending.md and .urgent)
+history_count=$(find "$HANDOFF_DIR" -maxdepth 1 -name "*.md" -type f 2>/dev/null | wc -l)
+if [[ "$history_count" -gt "$max_history" ]]; then
+  excess=$(( history_count - max_history ))
+  find "$HANDOFF_DIR" -maxdepth 1 -name "*.md" -type f -printf '%T@ %p\n' 2>/dev/null \
+    | sort -n | head -"$excess" | awk '{print $2}' | xargs rm -f
+fi
+
+# Emit the handoff content as additionalContext
+header="## Session restored from handoff (${archive_name})\n\nThe following context was saved by the previous session's /handoff skill:\n\n"
+jq -nc --arg ctx "${header}${content}" '{
+  hookSpecificOutput: {
+    hookEventName: "SessionStart",
+    additionalContext: $ctx
+  }
+}'
+exit 0

package/templates/rules/consult-analysis-before-implementing.md

@@ -0,0 +1,23 @@
+<!-- Generated by @hivehub/rulebook v5.3.0 — delete this comment to prevent regeneration on `rulebook update` -->
+
+# Consult analysis before implementing
+
+When you start working on any task whose `proposal.md` contains a
+`Source: docs/analysis/<slug>/` reference, you MUST first:
+
+1. Read the referenced analysis README and findings
+2. Run `rulebook_knowledge_list` (or `rulebook knowledge list`) and
+   scan for entries tagged `analysis:<slug>`
+3. Run `rulebook_memory_search` with query `analysis:<slug>` to
+   retrieve any prior session context about this analysis
+
+Only after reviewing these results may you begin implementation.
+
+## Why
+
+Analyses accumulate institutional knowledge (patterns, anti-patterns,
+architectural decisions, validated findings). Implementing without
+consulting them means repeating mistakes or contradicting decisions
+that were already made based on evidence.
+
+This rule is part of the `/analysis` workflow (v5.3.0 F-NEW-4).

package/templates/rules/cpp.md

@@ -0,0 +1,46 @@
+---
+paths:
+  - "**/*.cpp"
+  - "**/*.cc"
+  - "**/*.cxx"
+  - "**/*.hpp"
+  - "**/*.hh"
+  - "**/*.h"
+  - "CMakeLists.txt"
+  - "**/CMakeLists.txt"
+  - "**/*.cmake"
+---
+<!-- Generated by @hivehub/rulebook v5.3.0 — delete this comment to prevent regeneration on `rulebook update` -->
+
+# C / C++ rules
+
+Loaded by Claude Code when touching C/C++ or CMake sources.
+
+## Non-negotiables
+
+1. **Build before test.** Run the compiler (`cmake --build <build>` or equivalent) before running tests. Link errors and missing symbols surface at build time — do not waste time running a binary that cannot link.
+2. **Treat warnings as errors.** `-Wall -Wextra -Werror` (gcc/clang) or `/W4 /WX` (MSVC). If a warning is a false positive, document it with a pragma and a comment.
+3. **Use smart pointers.** `std::unique_ptr` by default, `std::shared_ptr` only when ownership is genuinely shared. Raw `new`/`delete` requires justification.
+4. **RAII for every resource.** File handles, sockets, locks, GPU resources — wrap in a class with a destructor. Never match `open`/`close` pairs by hand.
+5. **No undefined behavior shortcuts.** No signed overflow reliance, no strict-aliasing violations, no reinterpret_cast across unrelated types without `memcpy`.
+
+## Conventions
+
+- C++17 baseline; C++20 features only if the project's CMake confirms support.
+- Header guards via `#pragma once` unless the project uses traditional `#ifndef` blocks.
+- `const` everywhere you can — parameters, methods, locals.
+- `auto` for types that are obvious from RHS (iterators, lambdas); spell the type when it aids the reader.
+- Avoid `using namespace std;` in headers (acceptable in .cpp with a tight scope).
+
+## Testing
+
+- Use the project's framework (GoogleTest, Catch2, doctest) — do not add a new one.
+- Run under ASan / UBSan on CI (`-fsanitize=address,undefined`).
+- Prefer property-based / fuzz tests for parsers and serializers.
+
+## Build & tooling
+
+- Out-of-source builds only. `build/` is gitignored.
+- `clang-format` from a committed `.clang-format` is the only formatting authority.
+- `compile_commands.json` exported (`-DCMAKE_EXPORT_COMPILE_COMMANDS=ON`) for clangd / tooling.
+- Never commit object files, binaries, or PDBs.

package/templates/rules/csharp.md

@@ -0,0 +1,44 @@
+---
+paths:
+  - "**/*.cs"
+  - "**/*.csproj"
+  - "**/*.sln"
+  - "Directory.Build.props"
+  - "Directory.Build.targets"
+  - "global.json"
+---
+<!-- Generated by @hivehub/rulebook v5.3.0 — delete this comment to prevent regeneration on `rulebook update` -->
+
+# C# rules
+
+Loaded by Claude Code when touching C# sources or MSBuild files.
+
+## Non-negotiables
+
+1. **Build before test.** `dotnet build` before `dotnet test`. Compilation errors surface faster and cheaper than test failures.
+2. **Nullable reference types enabled.** `<Nullable>enable</Nullable>` in the csproj. Treat warnings as errors where the project configures it.
+3. **No `!` (null-forgiving) without a comment** explaining why the compiler is wrong.
+4. **`async` all the way.** No `.Result` / `.Wait()` in async code paths — deadlocks are the inevitable consequence.
+5. **Dispose or `using`.** Every `IDisposable` is either wrapped in `using` / `await using` or explicitly disposed in a `finally`.
+
+## Conventions
+
+- PascalCase for public members, camelCase for parameters and locals, `_camelCase` for private fields.
+- `var` when the type is obvious from RHS; spell the type otherwise.
+- Prefer records for DTOs (C# 9+); sealed classes by default.
+- `CancellationToken` as the last parameter of async methods.
+- Do not catch `Exception` — catch the specific type or rethrow.
+
+## Testing
+
+- xUnit, NUnit, or MSTest per project config — do not add a new one.
+- FluentAssertions for readable asserts where already used.
+- `[Theory]` / parameterized tests for input-table coverage.
+- Mocks via Moq / NSubstitute; avoid heavy mocking frameworks.
+
+## Build & tooling
+
+- `dotnet format` before committing.
+- Commit `.csproj`, never `bin/` or `obj/`.
+- Target framework pinned via `global.json` when multiple SDKs are installed.
+- Run `dotnet build --warnaserror` on CI.

package/templates/rules/diagnostic-first.md

@@ -0,0 +1,39 @@
+<!-- Generated by @hivehub/rulebook v5.3.0 — delete this comment to prevent regeneration on `rulebook update` -->
+
+# Check before test (diagnostic-first)
+
+**Always run diagnostic tools before the test suite.**
+
+| Language | Check command | Run BEFORE |
+|----------|--------------|------------|
+| TypeScript | `tsc --noEmit` / `npm run type-check` | `npm test` |
+| Rust | `cargo check` | `cargo test` |
+| Python | `mypy .` / `pyright` | `pytest` |
+| Go | `go vet ./...` | `go test ./...` |
+| C/C++ | `cmake --build <dir>` | `ctest` |
+| Java | `mvn compile` | `mvn test` |
+| C# | `dotnet build` | `dotnet test` |
+| TML | `mcp__tml__check` (MCP) / `scripts/build.bat` | `mcp__tml__test` |
+
+## Why
+
+Diagnostic tools (type-checkers, linters, compilers) are **5–10x faster**
+than test suites and catch a different class of errors. Running them first:
+
+1. Surfaces errors that tests would catch slower (or not at all)
+2. Avoids wasting a full test cycle on code that can't compile
+3. Provides faster feedback loops per iteration
+
+**Evidence**: a single "check before test" prompt rule raised diagnostic
+tool adoption from 8.8% to 25.3% in 10 days, accelerating rather than
+plateauing. Default-on features reach 95.7% adoption vs 11.1% for opt-in.
+(Source: LLM-IR-Debugging paper, §5–6)
+
+## Rule
+
+Before running the project's test suite:
+1. Run the project's configured type-checker or compiler
+2. Fix any errors it reports
+3. Only then run tests
+
+This applies to every iteration, not just the final commit check.

package/templates/rules/fail-twice-escalate.md

@@ -0,0 +1,46 @@
+<!-- Generated by @hivehub/rulebook v5.3.0 — delete this comment to prevent regeneration on `rulebook update` -->
+
+# Fail twice → escalate
+
+If a fix attempt fails **twice with the same approach**, you MUST:
+
+1. **Stop** — do not try a third variation of the same approach
+2. **Analyze** what went wrong — identify root causes, not symptoms
+3. **Escalate** — choose one:
+   - Open a **Team** (`TeamCreate`) and bring in a specialist agent
+   - **Research** the problem (read source code, search docs, use diagnostic tools)
+   - **Ask the user** for guidance (only if research does not resolve it)
+4. **Record** the failed approach as context so the next attempt is informed
+
+## Why
+
+LLMs in agentic loops tend to retry the same approach with minor
+variations until the iteration limit is reached. This wastes cycles
+and produces cascading patches that are harder to debug than a clean
+restart. The "fail twice → escalate" pattern breaks the loop early.
+
+**Evidence**: UzEngine's "RULE -3" (FAIL TWICE → OPEN TEAM) has been
+field-validated across 30+ specialized sub-agents. The LLM-IR-debugging
+paper (§6) documents the same failure mode and confirms that structural
+escape mechanisms are effective.
+
+## What counts as "the same approach"
+
+Two attempts are "the same approach" if:
+- They modify the same file(s) in the same function/block
+- They produce the same category of error (e.g. both fail the type-checker)
+- The second attempt is a small variation of the first (e.g. changing a
+  parameter value, adding a cast, swapping an operator)
+
+Two attempts are "different approaches" if:
+- They target different root causes
+- They modify different subsystems
+- The second attempt was informed by new diagnostic information not
+  available during the first
+
+## Interaction with other rules
+
+- **incremental-implementation.md**: "spend more than 3 failed attempts"
+  is the outer limit; this rule fires earlier (at 2)
+- **research-first.md**: escalation via research satisfies both rules
+- **git-safety.md**: never revert as an "escalation" — fix forward