@hivehub/rulebook 5.5.2 → 5.8.0

package/templates/modules/VECTORIZER.md

@@ -1,63 +1,63 @@
-<!-- VECTORIZER:START -->
-# Vectorizer Instructions
-
-**CRITICAL**: Use MCP Vectorizer as primary data source for project information instead of file reading.
-
-## Core Functions
-
-### Search
-```
-mcp_vectorizer_search - Multiple strategies:
-  - intelligent: AI-powered with query expansion
-  - semantic: Advanced with reranking  
-  - contextual: Context-aware with filtering
-  - multi_collection: Cross-project search
-  - batch: Parallel queries
-  - by_file_type: Filter by extension (.rs, .ts, .py)
-```
-
-### File Operations
-```
-get_content - Retrieve file without disk I/O
-list_files - List indexed files with metadata
-get_summary - File summaries (extractive/structural)
-get_chunks - Progressive reading of large files
-get_outline - Project structure overview
-get_related - Find semantically related files
-```
-
-### Discovery
-```
-full_pipeline - Complete discovery with scoring
-broad_discovery - Multi-query with deduplication
-semantic_focus - Deep semantic search
-expand_queries - Generate query variations
-```
-
-## When to Use
-
-| Task | Tool |
-|------|------|
-| Explore unfamiliar code | intelligent search |
-| Read file | get_content |
-| Understand structure | get_outline |
-| Find related files | get_related |
-| Read large file | get_chunks |
-| Complex question | full_pipeline |
-
-## Best Practices
-
-✅ **DO:**
-- Start with intelligent search for exploration
-- Use file_operations to avoid disk I/O
-- Batch queries for related items
-- Set similarity thresholds (0.6-0.8)
-- Use specific collections when known
-
-❌ **DON'T:**
-- Read files from disk when available in vectorizer
-- Use sequential searches (batch instead)
-- Skip similarity thresholds
-- Search entire codebase when collection is known
-
-<!-- VECTORIZER:END -->
+<!-- VECTORIZER:START -->
+# Vectorizer Instructions
+
+**CRITICAL**: Use MCP Vectorizer as primary data source for project information instead of file reading.
+
+## Core Functions
+
+### Search
+```
+mcp_vectorizer_search - Multiple strategies:
+  - intelligent: AI-powered with query expansion
+  - semantic: Advanced with reranking  
+  - contextual: Context-aware with filtering
+  - multi_collection: Cross-project search
+  - batch: Parallel queries
+  - by_file_type: Filter by extension (.rs, .ts, .py)
+```
+
+### File Operations
+```
+get_content - Retrieve file without disk I/O
+list_files - List indexed files with metadata
+get_summary - File summaries (extractive/structural)
+get_chunks - Progressive reading of large files
+get_outline - Project structure overview
+get_related - Find semantically related files
+```
+
+### Discovery
+```
+full_pipeline - Complete discovery with scoring
+broad_discovery - Multi-query with deduplication
+semantic_focus - Deep semantic search
+expand_queries - Generate query variations
+```
+
+## When to Use
+
+| Task | Tool |
+|------|------|
+| Explore unfamiliar code | intelligent search |
+| Read file | get_content |
+| Understand structure | get_outline |
+| Find related files | get_related |
+| Read large file | get_chunks |
+| Complex question | full_pipeline |
+
+## Best Practices
+
+✅ **DO:**
+- Start with intelligent search for exploration
+- Use file_operations to avoid disk I/O
+- Batch queries for related items
+- Set similarity thresholds (0.6-0.8)
+- Use specific collections when known
+
+❌ **DON'T:**
+- Read files from disk when available in vectorizer
+- Use sequential searches (batch instead)
+- Skip similarity thresholds
+- Search entire codebase when collection is known
+
+<!-- VECTORIZER:END -->

package/templates/modules/sequential-thinking.md

@@ -1,42 +1,42 @@
-<!-- SEQUENTIAL_THINKING:START -->
-# Sequential Thinking MCP
-
-Sequential thinking MCP enables structured, step-by-step problem solving for complex tasks.
-
-## When to Use
-
-Use sequential thinking for:
-- Complex architectural decisions requiring multiple trade-off analyses
-- Debugging hard-to-reproduce issues
-- Planning multi-step implementations before writing code
-- Tasks where mistakes are costly (data migrations, API changes)
-
-## Usage Pattern
-
-```
-mcp__sequential-thinking__sequentialthinking
-```
-
-Call with a thought/problem to explore it step by step before committing to an implementation.
-
-## Integration
-
-When sequential thinking MCP is available:
-1. Start complex tasks with a thinking step to plan the approach
-2. Use it to validate assumptions before writing code
-3. Record key decisions from the thinking process in task spec files
-
-## Install (if not configured)
-
-```bash
-# Add to .mcp.json
-{
-  "mcpServers": {
-    "sequential-thinking": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
-    }
-  }
-}
-```
-<!-- SEQUENTIAL_THINKING:END -->
+<!-- SEQUENTIAL_THINKING:START -->
+# Sequential Thinking MCP
+
+Sequential thinking MCP enables structured, step-by-step problem solving for complex tasks.
+
+## When to Use
+
+Use sequential thinking for:
+- Complex architectural decisions requiring multiple trade-off analyses
+- Debugging hard-to-reproduce issues
+- Planning multi-step implementations before writing code
+- Tasks where mistakes are costly (data migrations, API changes)
+
+## Usage Pattern
+
+```
+mcp__sequential-thinking__sequentialthinking
+```
+
+Call with a thought/problem to explore it step by step before committing to an implementation.
+
+## Integration
+
+When sequential thinking MCP is available:
+1. Start complex tasks with a thinking step to plan the approach
+2. Use it to validate assumptions before writing code
+3. Record key decisions from the thinking process in task spec files
+
+## Install (if not configured)
+
+```bash
+# Add to .mcp.json
+{
+  "mcpServers": {
+    "sequential-thinking": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+    }
+  }
+}
+```
+<!-- SEQUENTIAL_THINKING:END -->

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

@@ -1,23 +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).
+<!-- 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

@@ -1,46 +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.
+---
+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

@@ -1,44 +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.
+---
+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

@@ -1,39 +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.
+<!-- 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

@@ -1,46 +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
+<!-- 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