@hivehub/rulebook 5.4.1 → 5.5.0

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

package/templates/rules/follow-task-sequence.md

@@ -1,36 +1,36 @@
----
-name: follow-task-sequence
-tier: 1
-description: "Execute tasks in the exact order defined — no reordering, no cherry-picking"
-alwaysApply: true
-filePatterns: ["*"]
-tools: ["all"]
----
-
-# Follow Task Sequence — No Reordering, No Cherry-Picking
-
-When a `tasks.md` checklist defines a sequence, execute items in EXACTLY that order.
-
-## Forbidden
-
-- Skipping ahead to "easier" or "more interesting" tasks
-- Reordering tasks because you think a different order is better
-- Cherry-picking tasks from the middle of a list
-- Deciding which tasks are "important enough" to do
-- Grouping or batching tasks in a different sequence
-- Starting Phase N+1 before Phase N is 100% complete
-
-## Required Behavior
-
-1. Read `tasks.md` from top to bottom
-2. Find the FIRST unchecked item (`- [ ]`)
-3. Implement THAT item — not the one you prefer
-4. Mark it `[x]` with what was done
-5. Move to the NEXT unchecked item
-6. Repeat until all items are checked
-
-## Why
-
-The human spent time defining the task sequence for a reason. The order reflects dependencies, priorities, and a deliberate implementation strategy. When AI agents skip around, dependencies break, progress tracking becomes unreliable, and work has to be redone.
-
-**The task list is an ORDER, not a MENU.**
+---
+name: follow-task-sequence
+tier: 1
+description: "Execute tasks in the exact order defined — no reordering, no cherry-picking"
+alwaysApply: true
+filePatterns: ["*"]
+tools: ["all"]
+---
+
+# Follow Task Sequence — No Reordering, No Cherry-Picking
+
+When a `tasks.md` checklist defines a sequence, execute items in EXACTLY that order.
+
+## Forbidden
+
+- Skipping ahead to "easier" or "more interesting" tasks
+- Reordering tasks because you think a different order is better
+- Cherry-picking tasks from the middle of a list
+- Deciding which tasks are "important enough" to do
+- Grouping or batching tasks in a different sequence
+- Starting Phase N+1 before Phase N is 100% complete
+
+## Required Behavior
+
+1. Read `tasks.md` from top to bottom
+2. Find the FIRST unchecked item (`- [ ]`)
+3. Implement THAT item — not the one you prefer
+4. Mark it `[x]` with what was done
+5. Move to the NEXT unchecked item
+6. Repeat until all items are checked
+
+## Why
+
+The human spent time defining the task sequence for a reason. The order reflects dependencies, priorities, and a deliberate implementation strategy. When AI agents skip around, dependencies break, progress tracking becomes unreliable, and work has to be redone.
+
+**The task list is an ORDER, not a MENU.**

package/templates/rules/git-safety.md

@@ -1,29 +1,29 @@
----
-name: git-safety
-tier: 1
-description: "Git safety — explicit allow-list, forbidden destructive operations"
-alwaysApply: true
-filePatterns: ["*"]
-tools: ["all"]
----
-
-# Git Safety Rules
-
-## Allowed (always safe)
-- `git status`, `git diff`, `git log`, `git blame`
-- `git add <files>`, `git commit` (after quality checks)
-
-## Forbidden (require explicit user authorization)
-- `git stash` — hidden state gets forgotten
-- `git rebase` — rewrites history
-- `git reset --hard` — destroys uncommitted changes
-- `git checkout -- .` / `git restore .` — discards all changes
-- `git revert` — creates unexpected commits
-- `git cherry-pick` — can cause conflicts
-- `git merge` — requires human judgment
-- `git branch -D` — permanent branch deletion
-- `git push --force` — NEVER on main/master
-- `git clean -f` — permanently deletes untracked files
-- `git checkout <branch>` / `git switch` — breaks concurrent AI sessions
-
-Multiple AI sessions may share the same working tree. Branch switching or destructive operations affect ALL concurrent sessions.
+---
+name: git-safety
+tier: 1
+description: "Git safety — explicit allow-list, forbidden destructive operations"
+alwaysApply: true
+filePatterns: ["*"]
+tools: ["all"]
+---
+
+# Git Safety Rules
+
+## Allowed (always safe)
+- `git status`, `git diff`, `git log`, `git blame`
+- `git add <files>`, `git commit` (after quality checks)
+
+## Forbidden (require explicit user authorization)
+- `git stash` — hidden state gets forgotten
+- `git rebase` — rewrites history
+- `git reset --hard` — destroys uncommitted changes
+- `git checkout -- .` / `git restore .` — discards all changes
+- `git revert` — creates unexpected commits
+- `git cherry-pick` — can cause conflicts
+- `git merge` — requires human judgment
+- `git branch -D` — permanent branch deletion
+- `git push --force` — NEVER on main/master
+- `git clean -f` — permanently deletes untracked files
+- `git checkout <branch>` / `git switch` — breaks concurrent AI sessions
+
+Multiple AI sessions may share the same working tree. Branch switching or destructive operations affect ALL concurrent sessions.

package/templates/rules/go.md

@@ -1,40 +1,40 @@
----
-paths:
-  - "**/*.go"
-  - "go.mod"
-  - "go.sum"
----
-<!-- Generated by @hivehub/rulebook v5.3.0 — delete this comment to prevent regeneration on `rulebook update` -->
-
-# Go rules
-
-Loaded by Claude Code when touching Go sources.
-
-## Non-negotiables
-
-1. **`go vet ./...` before `go test ./...`.** Vet is near-instant and catches common issues before the slower test runner.
-2. **`gofmt -s -w .` and `goimports -w .`** on every file you touch. There is no formatting debate in Go.
-3. **Error handling is explicit.** Every `err` is either handled, wrapped with `fmt.Errorf("context: %w", err)`, or propagated up. Never `_ = err`.
-4. **No naked returns in functions longer than 5 lines.** They obscure control flow.
-5. **`context.Context` is the first parameter** for any function that does I/O or may block. Never store contexts in structs.
-
-## Conventions
-
-- Package names are short, lowercase, and singular (`user`, not `users` or `userManager`).
-- Interfaces defined by the consumer, not the producer. Keep them small (1–3 methods).
-- Struct fields ordered: exported before unexported, grouped by logical purpose.
-- Use `any` instead of `interface{}` (Go 1.18+).
-- Prefer table-driven tests with `t.Run` subtests.
-
-## Testing
-
-- Test files live in the same package, suffix `_test.go`.
-- `testify/require` or stdlib `testing` — pick one and stick with it.
-- Race detector on CI: `go test -race ./...`.
-- No test skipping without `t.Skip("reason: ...")`.
-
-## Build & tooling
-
-- `go mod tidy` after adding imports; commit both `go.mod` and `go.sum`.
-- Never commit `vendor/` unless the project explicitly vendors.
-- Use `go build ./...` to catch packages you forgot to test.
+---
+paths:
+  - "**/*.go"
+  - "go.mod"
+  - "go.sum"
+---
+<!-- Generated by @hivehub/rulebook v5.3.0 — delete this comment to prevent regeneration on `rulebook update` -->
+
+# Go rules
+
+Loaded by Claude Code when touching Go sources.
+
+## Non-negotiables
+
+1. **`go vet ./...` before `go test ./...`.** Vet is near-instant and catches common issues before the slower test runner.
+2. **`gofmt -s -w .` and `goimports -w .`** on every file you touch. There is no formatting debate in Go.
+3. **Error handling is explicit.** Every `err` is either handled, wrapped with `fmt.Errorf("context: %w", err)`, or propagated up. Never `_ = err`.
+4. **No naked returns in functions longer than 5 lines.** They obscure control flow.
+5. **`context.Context` is the first parameter** for any function that does I/O or may block. Never store contexts in structs.
+
+## Conventions
+
+- Package names are short, lowercase, and singular (`user`, not `users` or `userManager`).
+- Interfaces defined by the consumer, not the producer. Keep them small (1–3 methods).
+- Struct fields ordered: exported before unexported, grouped by logical purpose.
+- Use `any` instead of `interface{}` (Go 1.18+).
+- Prefer table-driven tests with `t.Run` subtests.
+
+## Testing
+
+- Test files live in the same package, suffix `_test.go`.
+- `testify/require` or stdlib `testing` — pick one and stick with it.
+- Race detector on CI: `go test -race ./...`.
+- No test skipping without `t.Skip("reason: ...")`.
+
+## Build & tooling
+
+- `go mod tidy` after adding imports; commit both `go.mod` and `go.sum`.
+- Never commit `vendor/` unless the project explicitly vendors.
+- Use `go build ./...` to catch packages you forgot to test.

package/templates/rules/incremental-implementation.md

@@ -1,56 +1,56 @@
----
-name: incremental-implementation
-tier: 1
-description: "Implement step by step, test each step, restart from scratch if stuck"
-alwaysApply: true
-filePatterns: ["*"]
-tools: ["all"]
----
-
-# Incremental Implementation — Step by Step, Test Each Step
-
-NEVER implement everything at once. Build incrementally, verify at every step, and restart from scratch when stuck.
-
-## Required Process
-
-1. **Understand** the full scope before writing any code
-2. **Decompose** into the smallest possible steps
-3. **Implement ONE step** at a time
-4. **Test/verify** that step immediately (compile, run, test)
-5. **Fix any errors** before moving to the next step
-6. **Record learnings** in the knowledge base after each significant discovery
-7. **Repeat** until complete
-
-## The Restart Rule
-
-If you have spent more than 3 failed attempts fixing the same error:
-
-1. **STOP** — do not try a 4th variation of the same approach
-2. **Analyze** what went wrong — write down root causes, not symptoms
-3. **Record** the failed approach as an anti-pattern in the knowledge base
-4. **Remove** the broken code completely — do not patch on top of patches
-5. **Reimplementation from scratch** using a different approach informed by what you learned
-6. **Test each step** of the new approach before proceeding
-
-## Knowledge Base Integration
-
-After every significant implementation:
-
-1. **Check existing knowledge** before starting: `rulebook knowledge list` or search `.rulebook/knowledge/`
-2. **Record patterns** that worked: `rulebook knowledge add pattern "<title>" --category <cat>`
-3. **Record anti-patterns** that failed: `rulebook knowledge add anti-pattern "<title>" --category <cat>`
-4. **Capture learnings** from debugging: `rulebook learn capture --title "<title>" --content "<content>"`
-
-## Forbidden
-
-- Implementing an entire feature in one pass without intermediate verification
-- Spending more than 3 attempts fixing the same error with the same approach
-- Patching broken code on top of broken code instead of restarting clean
-- Ignoring the knowledge base — check it BEFORE implementing, update it AFTER
-- Batching all tests to the end instead of testing each step
-
-## Why
-
-AI agents that implement everything at once produce cascading errors. One early mistake propagates through the entire implementation, and debugging becomes exponentially harder. Step-by-step with immediate verification catches errors at the source. When stuck, restarting from scratch with new knowledge is always faster than patching endlessly. The line between persistence and stubbornness is thin.
-
-**"Slow is smooth, smooth is fast."**
+---
+name: incremental-implementation
+tier: 1
+description: "Implement step by step, test each step, restart from scratch if stuck"
+alwaysApply: true
+filePatterns: ["*"]
+tools: ["all"]
+---
+
+# Incremental Implementation — Step by Step, Test Each Step
+
+NEVER implement everything at once. Build incrementally, verify at every step, and restart from scratch when stuck.
+
+## Required Process
+
+1. **Understand** the full scope before writing any code
+2. **Decompose** into the smallest possible steps
+3. **Implement ONE step** at a time
+4. **Test/verify** that step immediately (compile, run, test)
+5. **Fix any errors** before moving to the next step
+6. **Record learnings** in the knowledge base after each significant discovery
+7. **Repeat** until complete
+
+## The Restart Rule
+
+If you have spent more than 3 failed attempts fixing the same error:
+
+1. **STOP** — do not try a 4th variation of the same approach
+2. **Analyze** what went wrong — write down root causes, not symptoms
+3. **Record** the failed approach as an anti-pattern in the knowledge base
+4. **Remove** the broken code completely — do not patch on top of patches
+5. **Reimplementation from scratch** using a different approach informed by what you learned
+6. **Test each step** of the new approach before proceeding
+
+## Knowledge Base Integration
+
+After every significant implementation:
+
+1. **Check existing knowledge** before starting: `rulebook knowledge list` or search `.rulebook/knowledge/`
+2. **Record patterns** that worked: `rulebook knowledge add pattern "<title>" --category <cat>`
+3. **Record anti-patterns** that failed: `rulebook knowledge add anti-pattern "<title>" --category <cat>`
+4. **Capture learnings** from debugging: `rulebook learn capture --title "<title>" --content "<content>"`
+
+## Forbidden
+
+- Implementing an entire feature in one pass without intermediate verification
+- Spending more than 3 attempts fixing the same error with the same approach
+- Patching broken code on top of broken code instead of restarting clean
+- Ignoring the knowledge base — check it BEFORE implementing, update it AFTER
+- Batching all tests to the end instead of testing each step
+
+## Why
+
+AI agents that implement everything at once produce cascading errors. One early mistake propagates through the entire implementation, and debugging becomes exponentially harder. Step-by-step with immediate verification catches errors at the source. When stuck, restarting from scratch with new knowledge is always faster than patching endlessly. The line between persistence and stubbornness is thin.
+
+**"Slow is smooth, smooth is fast."**

package/templates/rules/incremental-tests.md

@@ -1,29 +1,29 @@
----
-name: incremental-tests
-tier: 2
-description: "Write tests in small batches, verify immediately"
-alwaysApply: true
-filePatterns: ["*.test.*", "*.spec.*", "*_test.*"]
-tools: ["all"]
----
-
-# Incremental Test Development
-
-Write tests 1-3 at a time. Test immediately after writing. Fix errors before proceeding.
-
-## Rules
-
-1. **Write 1-3 tests** at a time, NOT entire test files at once
-2. **Run immediately** after writing — use single-file test execution
-3. **Fix errors** before writing more tests
-4. **Never run full suite** while developing tests — use individual file execution
-5. **Coverage updates** only after completing a block of tests
-
-## Why
-
-Writing full test files at once leads to cascading failures. One early error invalidates all subsequent tests, creating debug fatigue and wasted time.
-
-## Development Testing vs Validation Testing
-
-- **Development**: Run single test file (`vitest run tests/my.test.ts`)
-- **Validation**: Run full suite only when a batch of tests is complete
+---
+name: incremental-tests
+tier: 2
+description: "Write tests in small batches, verify immediately"
+alwaysApply: true
+filePatterns: ["*.test.*", "*.spec.*", "*_test.*"]
+tools: ["all"]
+---
+
+# Incremental Test Development
+
+Write tests 1-3 at a time. Test immediately after writing. Fix errors before proceeding.
+
+## Rules
+
+1. **Write 1-3 tests** at a time, NOT entire test files at once
+2. **Run immediately** after writing — use single-file test execution
+3. **Fix errors** before writing more tests
+4. **Never run full suite** while developing tests — use individual file execution
+5. **Coverage updates** only after completing a block of tests
+
+## Why
+
+Writing full test files at once leads to cascading failures. One early error invalidates all subsequent tests, creating debug fatigue and wasted time.
+
+## Development Testing vs Validation Testing
+
+- **Development**: Run single test file (`vitest run tests/my.test.ts`)
+- **Validation**: Run full suite only when a batch of tests is complete

package/templates/rules/java.md

@@ -1,43 +1,43 @@
----
-paths:
-  - "**/*.java"
-  - "pom.xml"
-  - "**/build.gradle"
-  - "**/build.gradle.kts"
-  - "**/settings.gradle"
-  - "**/settings.gradle.kts"
----
-<!-- Generated by @hivehub/rulebook v5.3.0 — delete this comment to prevent regeneration on `rulebook update` -->
-
-# Java rules
-
-Loaded by Claude Code when touching Java sources or build files.
-
-## Non-negotiables
-
-1. **Compile before test.** `mvn compile` / `gradle classes` before running the test suite. Compilation errors are cheaper to fix than a broken test run.
-2. **Static analysis enabled.** SpotBugs, ErrorProne, or Checkstyle per project config. Warnings count as failures.
-3. **Null safety.** Use `Optional<T>` for values that may be absent at API boundaries. Annotate fields with `@Nullable` / `@NonNull` where the project uses JSR-305 / JSpecify.
-4. **Immutability first.** `final` by default on fields, parameters, and local variables. Prefer records (Java 16+) for data carriers.
-5. **Never swallow exceptions.** Every `catch` either handles, wraps (`throw new X("context", e)`), or logs with context.
-
-## Conventions
-
-- Follow the project's Google Java Style or similar — formatter handles it.
-- Package names all lowercase, reverse-DNS (`com.hivehub.rulebook.foo`).
-- One public class per file; file name matches the class.
-- Prefer composition over inheritance; avoid deep hierarchies.
-- Use `java.time` (not `java.util.Date`) for dates and times.
-
-## Testing
-
-- JUnit 5 is default; use the project's configured framework.
-- AssertJ or Hamcrest for readable assertions.
-- Mockito for mocks; avoid PowerMock unless strictly necessary.
-- One logical assertion per test; multiple mechanical ones allowed.
-
-## Build & tooling
-
-- Commit `pom.xml` / `build.gradle`, never `target/` / `build/`.
-- Pin plugin versions; do not use ranges.
-- Java version declared in the build file, not assumed from the environment.
+---
+paths:
+  - "**/*.java"
+  - "pom.xml"
+  - "**/build.gradle"
+  - "**/build.gradle.kts"
+  - "**/settings.gradle"
+  - "**/settings.gradle.kts"
+---
+<!-- Generated by @hivehub/rulebook v5.3.0 — delete this comment to prevent regeneration on `rulebook update` -->
+
+# Java rules
+
+Loaded by Claude Code when touching Java sources or build files.
+
+## Non-negotiables
+
+1. **Compile before test.** `mvn compile` / `gradle classes` before running the test suite. Compilation errors are cheaper to fix than a broken test run.
+2. **Static analysis enabled.** SpotBugs, ErrorProne, or Checkstyle per project config. Warnings count as failures.
+3. **Null safety.** Use `Optional<T>` for values that may be absent at API boundaries. Annotate fields with `@Nullable` / `@NonNull` where the project uses JSR-305 / JSpecify.
+4. **Immutability first.** `final` by default on fields, parameters, and local variables. Prefer records (Java 16+) for data carriers.
+5. **Never swallow exceptions.** Every `catch` either handles, wraps (`throw new X("context", e)`), or logs with context.
+
+## Conventions
+
+- Follow the project's Google Java Style or similar — formatter handles it.
+- Package names all lowercase, reverse-DNS (`com.hivehub.rulebook.foo`).
+- One public class per file; file name matches the class.
+- Prefer composition over inheritance; avoid deep hierarchies.
+- Use `java.time` (not `java.util.Date`) for dates and times.
+
+## Testing
+
+- JUnit 5 is default; use the project's configured framework.
+- AssertJ or Hamcrest for readable assertions.
+- Mockito for mocks; avoid PowerMock unless strictly necessary.
+- One logical assertion per test; multiple mechanical ones allowed.
+
+## Build & tooling
+
+- Commit `pom.xml` / `build.gradle`, never `target/` / `build/`.
+- Pin plugin versions; do not use ranges.
+- Java version declared in the build file, not assumed from the environment.

package/templates/rules/javascript.md

@@ -1,39 +1,39 @@
----
-paths:
-  - "**/*.js"
-  - "**/*.jsx"
-  - "**/*.mjs"
-  - "**/*.cjs"
-  - "package.json"
----
-<!-- Generated by @hivehub/rulebook v5.3.0 — delete this comment to prevent regeneration on `rulebook update` -->
-
-# JavaScript rules
-
-Loaded by Claude Code when touching JavaScript files.
-
-## Non-negotiables
-
-1. **Lint before test.** Run the project's linter (ESLint / Biome) before the test suite. Lint errors are cheaper to surface than test failures.
-2. **No `var`.** Use `const` by default, `let` only when reassignment is necessary.
-3. **Strict equality.** Always `===` and `!==`, never `==` / `!=`.
-4. **No implicit globals.** Every file that modifies state at the top level should explicitly export it.
-5. **Module type matches the project.** If the project is ESM (`"type": "module"` in package.json), use `import`/`export`; if CommonJS, use `require`/`module.exports`. Do not mix without a clear boundary.
-
-## Conventions
-
-- Prefer arrow functions for callbacks; named `function` declarations for top-level or hoisted functions.
-- `async`/`await` over raw Promise chains.
-- Destructure function arguments when there are 3+ parameters.
-- Never rely on falsy checks for "value exists" — use explicit `=== undefined` / `!= null` where the distinction matters.
-
-## Testing
-
-- Use the project's configured test runner. Do not add a new one.
-- Mock external boundaries (network, filesystem, time).
-- No `describe.skip` / `it.skip` left behind in committed code.
-
-## Dependencies
-
-- Check `package.json` before adding imports. Do not install new dependencies without explicit authorization.
-- Pin `peerDependencies` carefully; they affect consumers of the package.
+---
+paths:
+  - "**/*.js"
+  - "**/*.jsx"
+  - "**/*.mjs"
+  - "**/*.cjs"
+  - "package.json"
+---
+<!-- Generated by @hivehub/rulebook v5.3.0 — delete this comment to prevent regeneration on `rulebook update` -->
+
+# JavaScript rules
+
+Loaded by Claude Code when touching JavaScript files.
+
+## Non-negotiables
+
+1. **Lint before test.** Run the project's linter (ESLint / Biome) before the test suite. Lint errors are cheaper to surface than test failures.
+2. **No `var`.** Use `const` by default, `let` only when reassignment is necessary.
+3. **Strict equality.** Always `===` and `!==`, never `==` / `!=`.
+4. **No implicit globals.** Every file that modifies state at the top level should explicitly export it.
+5. **Module type matches the project.** If the project is ESM (`"type": "module"` in package.json), use `import`/`export`; if CommonJS, use `require`/`module.exports`. Do not mix without a clear boundary.
+
+## Conventions
+
+- Prefer arrow functions for callbacks; named `function` declarations for top-level or hoisted functions.
+- `async`/`await` over raw Promise chains.
+- Destructure function arguments when there are 3+ parameters.
+- Never rely on falsy checks for "value exists" — use explicit `=== undefined` / `!= null` where the distinction matters.
+
+## Testing
+
+- Use the project's configured test runner. Do not add a new one.
+- Mock external boundaries (network, filesystem, time).
+- No `describe.skip` / `it.skip` left behind in committed code.
+
+## Dependencies
+
+- Check `package.json` before adding imports. Do not install new dependencies without explicit authorization.
+- Pin `peerDependencies` carefully; they affect consumers of the package.