@hivehub/rulebook 5.5.1 → 5.7.0

package/templates/agents/context-intelligence.md

@@ -1,52 +1,50 @@
----
-name: context-intelligence
-model: haiku
-description: Manages project decisions, knowledge base, and learnings. Use for capturing ADRs, patterns/anti-patterns, and post-implementation learnings.
-tools: Read, Glob, Grep, Bash, Write, Edit
-maxTurns: 15
----
-
-You are a context-intelligence agent. Your primary responsibility is managing the project's institutional knowledge: decisions, patterns, and learnings.
-
-## Responsibilities
-
-- Create and manage Architecture Decision Records (ADRs) via `rulebook decision`
-- Add patterns and anti-patterns to the knowledge base via `rulebook knowledge`
-- Capture and promote learnings via `rulebook learn`
-- Extract learnings from Ralph iteration history
-- Ensure decisions have proper context, alternatives, and consequences
-
-## Workflow
-
-### When creating a decision:
-1. Check existing decisions: `rulebook decision list`
-2. Create: `rulebook decision create "<title>" --context "<context>"`
-3. Enrich the `.rulebook/decisions/NNN-<slug>.md` file with full details
-4. Verify: `rulebook decision show <id>`
-
-### When adding knowledge:
-1. Check existing entries: `rulebook knowledge list`
-2. Create: `rulebook knowledge add <pattern|anti-pattern> "<title>" --category <cat>`
-3. Enrich `.rulebook/knowledge/<type>s/<slug>.md` with examples and guidelines
-4. Verify: `rulebook knowledge show <slug>`
-
-### When capturing learnings:
-1. Capture: `rulebook learn capture --title "<title>" --content "<content>" --tags "tag1,tag2"`
-2. For Ralph learnings: `rulebook learn from-ralph`
-3. Promote significant learnings: `rulebook learn promote <id> knowledge|decision`
-
-## Standards
-
-1. Every decision MUST include context, the decision, alternatives, and consequences
-2. Patterns MUST include concrete code examples (not abstract descriptions)
-3. Anti-patterns MUST explain what to do instead
-4. Learnings should be captured immediately after discovery, not batched
-5. Use descriptive titles — they appear in AGENTS.md for AI context
-
-## Rules
-
-- Do NOT modify production source code — only `.rulebook/` files
-- Do NOT delete decisions — supersede or deprecate them
-- Knowledge entries auto-appear in AGENTS.md after `rulebook update`
-- Tag all entries for searchability
-- When promoting a learning, verify the promoted entry is complete
+---
+name: context-intelligence
+model: haiku
+description: Manages project decisions, knowledge base, and learnings. Use for capturing ADRs, patterns/anti-patterns, and post-implementation learnings.
+tools: Read, Glob, Grep, Bash, Write, Edit
+maxTurns: 15
+---
+
+You are a context-intelligence agent. Your primary responsibility is managing the project's institutional knowledge: decisions, patterns, and learnings.
+
+## Responsibilities
+
+- Create and manage Architecture Decision Records (ADRs) via `rulebook decision`
+- Add patterns and anti-patterns to the knowledge base via `rulebook knowledge`
+- Capture and promote learnings via `rulebook learn`
+- Ensure decisions have proper context, alternatives, and consequences
+
+## Workflow
+
+### When creating a decision:
+1. Check existing decisions: `rulebook decision list`
+2. Create: `rulebook decision create "<title>" --context "<context>"`
+3. Enrich the `.rulebook/decisions/NNN-<slug>.md` file with full details
+4. Verify: `rulebook decision show <id>`
+
+### When adding knowledge:
+1. Check existing entries: `rulebook knowledge list`
+2. Create: `rulebook knowledge add <pattern|anti-pattern> "<title>" --category <cat>`
+3. Enrich `.rulebook/knowledge/<type>s/<slug>.md` with examples and guidelines
+4. Verify: `rulebook knowledge show <slug>`
+
+### When capturing learnings:
+1. Capture: `rulebook learn capture --title "<title>" --content "<content>" --tags "tag1,tag2"`
+2. Promote significant learnings: `rulebook learn promote <id> knowledge|decision`
+
+## Standards
+
+1. Every decision MUST include context, the decision, alternatives, and consequences
+2. Patterns MUST include concrete code examples (not abstract descriptions)
+3. Anti-patterns MUST explain what to do instead
+4. Learnings should be captured immediately after discovery, not batched
+5. Use descriptive titles — they appear in AGENTS.md for AI context
+
+## Rules
+
+- Do NOT modify production source code — only `.rulebook/` files
+- Do NOT delete decisions — supersede or deprecate them
+- Knowledge entries auto-appear in AGENTS.md after `rulebook update`
+- Tag all entries for searchability
+- When promoting a learning, verify the promoted entry is complete

package/templates/cli/OPENCODE.md

@@ -1,18 +1,85 @@
-<!-- OPENCODE:START -->
-# OpenCode Rules
-
-**Tool**: Open-source AI assistant
-
-## Usage
-
-```
-"Follow @AGENTS.md. Implement [feature] with tests."
-```
-
-## Workflow
-
-1. Reference AGENTS.md
-2. Review code
-3. Run quality checks
-
-<!-- OPENCODE:END -->
+<!-- OPENCODE:START -->
+# OpenCode Rules
+
+**Tool**: [OpenCode](https://opencode.ai) — open-source terminal coding agent (SST).
+
+OpenCode reads `AGENTS.md` natively (with `CLAUDE.md` as fallback). When
+Rulebook is initialized in this project, OpenCode also gets:
+
+- `opencode.json` — declares the rulebook MCP server and lazy-loads the
+  project rule files via the `instructions` array.
+- `.opencode/commands/` — mirrors Rulebook's user-invocable slash commands
+  (`/handoff`, `/rulebook-task-*`, `/rulebook-decision-*`,
+  `/rulebook-knowledge-*`, `/rulebook-memory-*`, `/rulebook-learn-*`).
+- `.opencode/agents/` — mirrors role agents (`researcher`, `implementer`,
+  `tester`, `code-reviewer`, `architect`, etc.) translated to OpenCode's
+  frontmatter schema (`mode`, `model`, `permission`).
+- `.opencode/skills/` — mirrors the dev skill library normalized to
+  OpenCode's strict skill-name regex.
+
+## Quick Start
+
+```bash
+# Install OpenCode
+curl -fsSL https://opencode.ai/install | bash
+
+# In a Rulebook-managed project, OpenCode picks up everything automatically:
+opencode
+```
+
+## Workflow
+
+1. **Reference rules** — `AGENTS.md`, `AGENTS.override.md`, and
+   `.rulebook/specs/*.md` are wired into `instructions` so the model
+   has them on demand without burning context.
+2. **Use slash commands** — type `/rulebook-task-create`,
+   `/rulebook-task-list`, `/handoff`, etc. They're real OpenCode
+   commands, not just prompt text.
+3. **Delegate to role agents** — `@researcher analyze X`,
+   `@implementer add Y`, `@tester cover Z`. Each role has its own
+   `model`, `permission`, and `description` matching the Rulebook
+   delegation table.
+4. **Quality checks** — type-check / lint / test before committing,
+   per `AGENTS.md` quality-gate rules.
+5. **Save learnings** — `rulebook memory save`, `rulebook knowledge add`,
+   `rulebook learn capture`, or invoke the corresponding slash commands.
+
+## Sequential editing
+
+OpenCode is held to the same Rulebook discipline as Claude Code:
+
+- Edit files **one at a time** (Read → Edit → Read → Edit), not in batch.
+- For 3+ files across subsystems, decompose into 1–2 file sub-tasks.
+- Run diagnostics (type-check / lint) **before** the test suite.
+
+## MCP & token usage
+
+The `mcp.rulebook` entry in `opencode.json` exposes the full Rulebook
+MCP toolset (`rulebook_task_*`, `rulebook_memory_*`, `rulebook_decision_*`,
+`rulebook_knowledge_*`, etc.). Prefer MCP tools over shell commands when
+both exist — they're faster, structured, and don't pollute context.
+
+Output discipline: prefer concise output. Don't generate "Quality Checks"
+status tables, "Next Steps" sections, or restate the question. Put
+implementation details in code comments, not markdown.
+
+## Isolation from Claude Code
+
+OpenCode falls back to `CLAUDE.md` if `AGENTS.md` is absent. To force
+OpenCode to ignore a `CLAUDE.md` shared with Claude Code, set:
+
+```bash
+export OPENCODE_DISABLE_CLAUDE_CODE=*
+```
+
+## Documentation
+
+- [opencode.ai/docs/rules](https://opencode.ai/docs/rules/)
+- [opencode.ai/docs/config](https://opencode.ai/docs/config/)
+- [opencode.ai/docs/mcp-servers](https://opencode.ai/docs/mcp-servers/)
+- [opencode.ai/docs/commands](https://opencode.ai/docs/commands/)
+- [opencode.ai/docs/agents](https://opencode.ai/docs/agents/)
+- [opencode.ai/docs/skills](https://opencode.ai/docs/skills/)
+- [opencode.ai/docs/permissions](https://opencode.ai/docs/permissions/)
+
+<!-- OPENCODE:END -->

package/templates/commands/rulebook-learn-capture.md

@@ -1,48 +1,41 @@
----
-name: /rulebook-learn-capture
-id: rulebook-learn-capture
-category: Rulebook
-description: Capture a learning from implementation work for future reference.
----
-<!-- RULEBOOK:START -->
-**Guardrails**
-- Learnings are saved to both the memory system and `.rulebook/learnings/` for offline backup.
-- Learnings can be promoted to patterns/decisions later via `rulebook learn promote`.
-
-**Steps**
-1. **Gather the Learning**:
-   - **Title**: Short description of what was learned
-   - **Content**: Full explanation — what happened, what was discovered, why it matters
-   - **Tags**: Keywords for searchability
-   - **Related Task**: Task ID if this learning came from a specific task
-   - **Source**: `manual` (default), `ralph`, or `task-archive`
-
-2. **Capture**:
-   ```bash
-   rulebook learn capture --title "<title>" --content "<content>" --tags "tag1,tag2" --related-task <task-id>
-   ```
-
-3. **Verify**:
-   ```bash
-   rulebook learn list --limit 5
-   ```
-
-**Promotion Flow**
-If a learning is significant enough to become a team pattern or decision:
-```bash
-rulebook learn promote <id> knowledge    # → creates a pattern
-rulebook learn promote <id> decision     # → creates an ADR
-```
-
-**Ralph Integration**
-Extract learnings from Ralph autonomous loop history:
-```bash
-rulebook learn from-ralph
-```
-This reads `.rulebook/ralph/history/iteration-*.json` and captures entries with non-empty learnings.
-
-**Reference**
-- Learnings are searchable via `rulebook memory search`
-- Use `rulebook learn list` to see all learnings
-- Learnings captured during `rulebook task archive` have source `task-archive`
-<!-- RULEBOOK:END -->
+---
+name: /rulebook-learn-capture
+id: rulebook-learn-capture
+category: Rulebook
+description: Capture a learning from implementation work for future reference.
+---
+<!-- RULEBOOK:START -->
+**Guardrails**
+- Learnings are saved to both the memory system and `.rulebook/learnings/` for offline backup.
+- Learnings can be promoted to patterns/decisions later via `rulebook learn promote`.
+
+**Steps**
+1. **Gather the Learning**:
+   - **Title**: Short description of what was learned
+   - **Content**: Full explanation — what happened, what was discovered, why it matters
+   - **Tags**: Keywords for searchability
+   - **Related Task**: Task ID if this learning came from a specific task
+   - **Source**: `manual` (default) or `task-archive`
+
+2. **Capture**:
+   ```bash
+   rulebook learn capture --title "<title>" --content "<content>" --tags "tag1,tag2" --related-task <task-id>
+   ```
+
+3. **Verify**:
+   ```bash
+   rulebook learn list --limit 5
+   ```
+
+**Promotion Flow**
+If a learning is significant enough to become a team pattern or decision:
+```bash
+rulebook learn promote <id> knowledge    # → creates a pattern
+rulebook learn promote <id> decision     # → creates an ADR
+```
+
+**Reference**
+- Learnings are searchable via `rulebook memory search`
+- Use `rulebook learn list` to see all learnings
+- Learnings captured during `rulebook task archive` have source `task-archive`
+<!-- RULEBOOK:END -->

package/templates/commands/rulebook-learn-list.md

@@ -1,13 +1,13 @@
----
-name: /rulebook-learn-list
-id: rulebook-learn-list
-category: Rulebook
-description: List captured learnings with source and promotion status.
----
-<!-- RULEBOOK:START -->
-**Steps**
-1. Run `rulebook learn list` to see all learnings (newest first).
-2. Optionally limit: `rulebook learn list --limit 10`
-3. Present results with source badge (manual/ralph/archive) and promotion status.
-4. Suggest promotion for significant learnings: `rulebook learn promote <id> knowledge|decision`
-<!-- RULEBOOK:END -->
+---
+name: /rulebook-learn-list
+id: rulebook-learn-list
+category: Rulebook
+description: List captured learnings with source and promotion status.
+---
+<!-- RULEBOOK:START -->
+**Steps**
+1. Run `rulebook learn list` to see all learnings (newest first).
+2. Optionally limit: `rulebook learn list --limit 10`
+3. Present results with source badge (manual/archive) and promotion status.
+4. Suggest promotion for significant learnings: `rulebook learn promote <id> knowledge|decision`
+<!-- RULEBOOK:END -->

package/templates/core/AGENTS_LEAN.md

@@ -157,20 +157,6 @@ LANGUAGE_REFS
 
 MODULE_REFS
 
-## Ralph Autonomous Loop
-
-5-gate quality enforcement (type-check, lint, tests, coverage, security) per iteration, fresh context per iteration, parallel story execution, plan checkpoints, learning extraction.
-
-```bash
-rulebook ralph init                    # Generate PRD from tasks
-rulebook ralph run --max-iterations 10
-rulebook ralph status / history / pause / resume
-```
-
-PRD format: `userStories` array with `id`, `title`, `description`, `acceptanceCriteria`, `priority`, `passes: boolean`, `notes`. Status tracked via `passes`, NOT enum.
-
-Iteration records in `.rulebook/ralph/history/iteration-N.json`. Status: `success` (5/5 gates), `partial` (2-4), `failed` (0-1).
-
 ## Multi-Agent Teams
 
 Requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`. Background `Agent` calls **must** use a Team (`team_name` parameter) — standalone background agents can't communicate via `SendMessage`. Foreground calls and `team-lead` agents are exempt.

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

@@ -1,76 +1,74 @@
-#!/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
-
-# Read the hook input from stdin (Claude Code passes it as JSON)
-input="$(cat)"
-
-# Resolve project root from hook input cwd, NOT $(pwd) — the hook may be
-# invoked from a sub-directory the user is currently editing.
-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"
-HANDOFF_DIR="${PROJECT_ROOT}/.rulebook/handoff"
-
-# Defaults
-WARN_PCT=75
-FORCE_PCT=90
-MAX_CONTEXT_CHARS=1600000  # ~400k tokens ≈ 1.6M 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
-
-# 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
+#!/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
+
+# Read the hook input from stdin (Claude Code passes it as JSON)
+input="$(cat)"
+
+# Resolve project root from hook input cwd, NOT $(pwd) — the hook may be
+# invoked from a sub-directory the user is currently editing.
+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"
+HANDOFF_DIR="${PROJECT_ROOT}/.rulebook/handoff"
+
+# Defaults
+WARN_PCT=75
+FORCE_PCT=90
+MAX_CONTEXT_CHARS=1600000  # ~400k tokens ≈ 1.6M 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
+
+# Resolve transcript size from the payload's transcript_path. Claude Code
+# always passes this in Stop hook stdin (Anthropic hook spec), so we avoid
+# scanning $HOME/.claude/projects — which grows linearly with session count
+# and also returns the wrong file in concurrent sessions.
+transcript_size=0
+
+if [[ -n "$input" ]] && command -v jq &>/dev/null; then
+  transcript_path="$(printf '%s' "$input" | jq -r '.transcript_path // empty' 2>/dev/null || true)"
+  if [[ -n "$transcript_path" && -f "$transcript_path" ]]; then
+    transcript_size=$(stat -c%s "$transcript_path" 2>/dev/null || stat -f%z "$transcript_path" 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-pre-tool.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# PreToolUse hook (v5.6.0): consolidated deny rules.
+#
+# Replaces three legacy hooks (enforce-no-deferred / enforce-no-shortcuts /
+# enforce-mcp-for-tasks) with a single bash + node invocation. Each rule's
+# permissionDecisionReason is preserved verbatim so existing user guidance
+# is unchanged.
+set -euo pipefail
+input="$(cat)"
+
+result="$(node -e "
+const input = JSON.parse(process.argv[1]);
+const tool = input.tool_name || '';
+const ti = input.tool_input || {};
+const file = (ti.file_path || ti.filePath || '').replace(/\\\\/g, '/');
+const content = ti.new_string || ti.content || '';
+const cmd = ti.command || '';
+
+// Rule: mcp-for-tasks — manual creation of task scaffolding is forbidden.
+if (tool === 'Write' || tool === 'Edit') {
+  const m = file.match(/\.rulebook\/tasks\/[^/]+\/(proposal\.md|\.metadata\.json)\$/);
+  if (m) {
+    try { require('fs').accessSync(file); /* existing file: allow edit */ }
+    catch { console.log('DENY_MCP'); process.exit(0); }
+  }
+}
+if (tool === 'Bash' && /mkdir.*\\.rulebook\\/tasks\\//.test(cmd)) {
+  console.log('DENY_MCP'); process.exit(0);
+}
+
+// Rule: no-deferred — tasks.md must not contain deferred / skip / later / TODO.
+if ((tool === 'Edit' || tool === 'Write') && file.endsWith('tasks.md')) {
+  if (/\\b(deferred|skip(ped)?|later|todo)\\b/i.test(content)) {
+    console.log('DENY_DEFERRED'); process.exit(0);
+  }
+}
+
+// Rule: no-shortcuts — source files must not contain TODO/FIXME/HACK or stub/placeholder.
+if (tool === 'Edit' || tool === 'Write') {
+  if (/\\.(ts|tsx|js|jsx|py|rs|go|java|cs|cpp|c|hpp|h)\$/.test(file)
+      && !/\\.test\\.|\\.spec\\.|__tests__|\\/tests\\//.test(file)) {
+    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_MCP)
+    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 })"}}'
+    ;;
+  DENY_DEFERRED)
+    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"}}'
+    ;;
+  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