@eltonssouza/development-utility-kit 0.10.0

package/dashboard/public/content/docs/hooks-reference.en.md

@@ -0,0 +1,404 @@
+# Hooks Reference
+
+This document describes every Claude Code hook active in the `development-utility-kit` harness. Hooks are extension points executed by the Claude Code runtime on specific lifecycle events — do not confuse them with Git hooks (`pre-commit`, `pre-push`), which live under `.git/hooks/` and are managed by Git.
+
+Claude Code hooks are registered in `.claude/settings.json` (project scope) or in `~/.claude/settings.json` (user global scope). Each hook is an `event + shell command` pair, optionally filtered by a `matcher` that restricts which tool or prompt pattern fires the hook.
+
+Audience: Java/Angular developers working inside the local harness dashboard or in projects that adopted the template.
+
+---
+
+## Overview — Claude Code events
+
+| Event | Fires when | Can block? |
+|---|---|---|
+| `PreToolUse` | Before a tool (Bash, Edit, Write, etc.) runs | Yes — exit != 0 cancels the tool |
+| `PostToolUse` | After a tool completes successfully | No — exit code is informational |
+| `UserPromptSubmit` | Before the user prompt is sent to the model | Stdin/stdout can alter the prompt; exit != 0 cancels |
+| `Stop` | When the session / turn ends | Does not block |
+| `Notification` | When Claude Code needs user attention | Does not block |
+| `SubagentStop` | When a sub-agent (Task tool) finishes | Does not block |
+
+The `matcher` is matched against the tool name (`Bash`, `Edit`, `MultiEdit`, `Write`, `Read`, ...) or uses `*` as wildcard for events that have no tool (`UserPromptSubmit`, `Stop`, `Notification`).
+
+---
+
+## Master table — Active hooks in the harness
+
+The table summarizes every hook registered in `.claude/settings.json`. Per-hook details follow in the next sections.
+
+| Event | Matcher | Script / Command | Purpose | Failure mode |
+|---|---|---|---|---|
+| `PreToolUse` | `Bash` | `scripts/hooks/pre-push-guard.sh` | Block unsafe `git push` (protected branch, no approval) | Exit != 0 blocks the Bash command |
+| `PreToolUse` | `Bash` | `scripts/hooks/block-test-deletion.sh` | Forbid `rm` / destructive edits on test files without justification | Exit != 0 blocks the Bash command |
+| `PostToolUse` | `Edit\|MultiEdit\|Write` | `npx prettier --write` (inline) | Auto-format `.ts/.tsx/.html/.scss/.css` after editing | Silent — prettier failures never break the edit |
+| `PostToolUse` | `Edit\|MultiEdit\|Write` | `scripts/hooks/post-edit-test-reminder.sh` | Remind to run tests / coverage after editing source | Always exit 0 — warning only |
+| `UserPromptSubmit` | `*` | `scripts/hooks/prompt-gate-reminder.sh` | Remind senior+ gate before critical tasks | Always exit 0 — informational |
+| `Stop` | `*` | `scripts/hooks/stop-brain-reminder.sh` | Remind to invoke `brain-keeper` at end of PLAN | Always exit 0 |
+| `Notification` | `*` | inline `notify-send` / `osascript` | Desktop notification when Claude needs attention | Silent |
+| `SubagentStop` (global) | `*` | `scripts/hooks/subagent-telemetry.sh` -> `telemetry-writer.js` | Persist sub-agent execution telemetry to `~/.claude/telemetry.db` | Silent — `exit 0` even on failure |
+
+---
+
+## Harness hooks (`scripts/hooks/`)
+
+### PreToolUse — `pre-push-guard.sh`
+
+**Trigger**: before any execution of the `Bash` tool.
+
+**Command registered in `.claude/settings.json`**:
+
+```json
+{
+  "matcher": "Bash",
+  "hooks": [
+    {
+      "type": "command",
+      "command": "bash \"$CLAUDE_PROJECT_DIR\"/scripts/hooks/pre-push-guard.sh"
+    }
+  ]
+}
+```
+
+**What the script does**: inspects the Bash command about to run. If it contains a `git push` targeting a protected branch (`main`, `develop`, `master`) without expected override flags, it fails with exit code 1 and prints the reason to stderr.
+
+**When it blocks**:
+- `git push origin main` directly, without an approved PR
+- `git push --force` on a shared branch
+- Push to a remote considered "protected" by the harness
+
+**How to debug**:
+
+```bash
+echo '{"command":"git push origin main"}' | bash scripts/hooks/pre-push-guard.sh
+echo $?  # expected: != 0
+```
+
+---
+
+### PreToolUse — `block-test-deletion.sh`
+
+**Trigger**: before any execution of the `Bash` tool.
+
+**Command**:
+
+```json
+{
+  "matcher": "Bash",
+  "hooks": [
+    {
+      "type": "command",
+      "command": "bash \"$CLAUDE_PROJECT_DIR\"/scripts/hooks/block-test-deletion.sh"
+    }
+  ]
+}
+```
+
+**What the script does**: parses the Bash command looking for destructive operations on test files (`rm -rf src/**/*.test.ts`, `git rm src/**/*Test.java`, etc.). Sub-agents must not delete tests — only `tech-lead` approves removal, and it must come with a justification recorded in the PLAN.
+
+**When it blocks**:
+- Direct `rm` on `*.test.ts`, `*.spec.ts`, `*Test.java`, `*IT.java` files
+- `git rm` inside `tests/` or `src/test/` directories
+- `> /dev/null` redirect that wipes test content
+
+**How to debug**:
+
+```bash
+echo '{"command":"rm src/app/foo.spec.ts"}' | bash scripts/hooks/block-test-deletion.sh
+```
+
+---
+
+### PostToolUse — Inline auto-formatting (prettier)
+
+**Trigger**: after `Edit`, `MultiEdit` or `Write` completes successfully.
+
+**Inline command in `.claude/settings.json`**:
+
+```bash
+json=$(cat); file_path=$(echo "$json" | jq -r '.file_path // empty'); \
+  if [[ "$file_path" =~ \.(ts|tsx|html|scss|css)$ ]] \
+     && command -v npx &>/dev/null \
+     && [ -f node_modules/.bin/prettier ]; then \
+       npx prettier --write "$file_path" 2>/dev/null; \
+  fi
+```
+
+**What it does**: reads the hook JSON payload (which contains `file_path`), checks the extension and fires `npx prettier --write` if prettier is installed locally. Keeps formatting consistent with no manual intervention.
+
+**When it blocks**: never. Everything is silenced by `2>/dev/null` and the exit code is ignored.
+
+**How to debug**:
+
+```bash
+echo '{"file_path":"src/app/foo.component.ts"}' | bash -c '<command above>'
+```
+
+**Prerequisite**: `prettier` must exist at `node_modules/.bin/prettier` (install with `npm i -D prettier`).
+
+---
+
+### PostToolUse — `post-edit-test-reminder.sh`
+
+**Trigger**: after `Edit`, `MultiEdit` or `Write`.
+
+**Command**:
+
+```json
+{
+  "matcher": "Edit|MultiEdit|Write",
+  "hooks": [
+    {
+      "type": "command",
+      "command": "bash \"$CLAUDE_PROJECT_DIR\"/scripts/hooks/post-edit-test-reminder.sh"
+    }
+  ]
+}
+```
+
+**What it does**: reminds the running agent to execute the relevant suite (`mvn test` on backend, `npm test` on frontend) if the edited file belongs to `domain/`, `application/` or `src/app/`. Prints the message to stderr; never blocks.
+
+---
+
+### UserPromptSubmit — `prompt-gate-reminder.sh`
+
+**Trigger**: before each user prompt is sent to the model.
+
+**Command**:
+
+```json
+{
+  "matcher": "*",
+  "hooks": [
+    {
+      "type": "command",
+      "command": "bash \"$CLAUDE_PROJECT_DIR\"/scripts/hooks/prompt-gate-reminder.sh"
+    }
+  ]
+}
+```
+
+**What it does**: detects critical keywords in the prompt ("merge", "deploy", "release", "production") and appends a stderr reminder to invoke `gate-keeper` before proceeding. Useful in long sessions where the senior+ gate might have been forgotten.
+
+---
+
+### Stop — `stop-brain-reminder.sh`
+
+**Trigger**: when the session turn ends.
+
+**Command**:
+
+```json
+{
+  "matcher": "*",
+  "hooks": [
+    {
+      "type": "command",
+      "command": "bash \"$CLAUDE_PROJECT_DIR\"/scripts/hooks/stop-brain-reminder.sh"
+    }
+  ]
+}
+```
+
+**What it does**: at the end of a `PLAN_*.md` or a relevant feature, reminds the user to invoke `brain-keeper` to record daily / feature / ADR / bug / tech-debt entries under `docs/brain/`. Does not block.
+
+---
+
+### Notification — Desktop notify
+
+**Trigger**: when Claude Code requires user attention (e.g., waiting for tool approval).
+
+**Inline command**:
+
+```bash
+if command -v notify-send &>/dev/null; then
+  notify-send 'Claude Code' 'Needs your attention'
+elif command -v osascript &>/dev/null; then
+  osascript -e 'display notification "Needs your attention" with title "Claude Code"'
+fi
+```
+
+**What it does**: fires a native notification (Linux via `notify-send`, macOS via `osascript`). On Windows with WSL, you need `notify-send` available in the WSL PATH for it to work.
+
+---
+
+## Telemetry hook — `subagent-telemetry.sh`
+
+**Trigger**: global `SubagentStop`. Fires every time a `Task` call (sub-agent) ends, in any project.
+
+**Script** (`scripts/hooks/subagent-telemetry.sh`):
+
+```bash
+#!/usr/bin/env bash
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WRITER="${SCRIPT_DIR}/telemetry-writer.js"
+
+if [ ! -f "$WRITER" ]; then
+  exit 0
+fi
+
+node "$WRITER" || exit 0
+```
+
+**Writer** (`scripts/hooks/telemetry-writer.js`): reads the `SubagentStop` JSON payload from stdin, normalises the model name (opus / sonnet / haiku / other) and persists the event in `~/.claude/telemetry.db` via `better-sqlite3` (fallback `sql.js`, final fallback NDJSON queue at `~/.claude/telemetry-queue.ndjson`).
+
+**Schema** (created idempotently):
+
+```sql
+CREATE TABLE IF NOT EXISTS events (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  project_path  TEXT    NOT NULL,
+  project_name  TEXT    NOT NULL,
+  model         TEXT    NOT NULL,
+  input_tokens  INTEGER NOT NULL DEFAULT 0,
+  output_tokens INTEGER NOT NULL DEFAULT 0,
+  subagent_type TEXT,
+  session_id    TEXT,
+  agent_id      TEXT,
+  agent_type    TEXT,
+  ts            INTEGER NOT NULL
+);
+```
+
+**Failure behavior**: everything is silent. If `node` is not on PATH, if the writer is missing, if SQLite fails — the hook returns exit 0 and the session proceeds normally. Errors are recorded in `~/.claude/telemetry-errors.log` when possible.
+
+**Historical bug**: see `docs/brain/bugs/bash-source-hook-path.md`. The original script used `$CLAUDE_PROJECT_DIR` to locate the writer, which fails when the hook is registered globally — `$CLAUDE_PROJECT_DIR` resolves to whatever project is active at the moment, not to the harness repo. Fixed by switching to `$(dirname "${BASH_SOURCE[0]}")` in commit `b7397e2`.
+
+---
+
+## Current state — Pending scripts
+
+The following scripts are **referenced** in `.claude/settings.json` but do **not yet exist** under `scripts/hooks/`. They are "configured but not implemented" hooks — create them as the feature demands:
+
+- `scripts/hooks/pre-push-guard.sh`
+- `scripts/hooks/block-test-deletion.sh`
+- `scripts/hooks/post-edit-test-reminder.sh`
+- `scripts/hooks/prompt-gate-reminder.sh`
+- `scripts/hooks/stop-brain-reminder.sh`
+
+While missing, Claude Code merely logs an execution error per hook and moves on — a `PreToolUse` with a missing script does **not** block (the runtime treats the missing-bash error as a config issue, not a gate failure).
+
+To author any of them, follow the next section.
+
+---
+
+## How to add a new hook
+
+1. Edit `.claude/settings.json` and append a block to the desired event array:
+
+   ```json
+   "PreToolUse": [
+     {
+       "matcher": "Bash",
+       "hooks": [
+         {
+           "type": "command",
+           "command": "bash \"$CLAUDE_PROJECT_DIR\"/scripts/hooks/my-hook.sh"
+         }
+       ]
+     }
+   ]
+   ```
+
+2. Create the script at `scripts/hooks/my-hook.sh`:
+
+   ```bash
+   #!/usr/bin/env bash
+   set -uo pipefail
+
+   # Read JSON payload from stdin
+   payload=$(cat)
+
+   # Extract relevant field (depends on event)
+   command=$(echo "$payload" | jq -r '.command // empty')
+
+   # Gate logic
+   if [[ "$command" =~ rm.*-rf ]]; then
+     echo "ERROR: rm -rf blocked by hook" >&2
+     exit 1
+   fi
+
+   exit 0
+   ```
+
+3. Make the script executable (POSIX):
+
+   ```bash
+   chmod +x scripts/hooks/my-hook.sh
+   ```
+
+4. Test by invoking manually with a sample payload:
+
+   ```bash
+   echo '{"command":"rm -rf /"}' | bash scripts/hooks/my-hook.sh
+   echo "exit code: $?"
+   ```
+
+5. Start a new Claude Code session (hooks are loaded at startup). Trigger the target tool and observe behavior.
+
+---
+
+## Common pitfalls
+
+### 1. Always start with shebang + `set -uo pipefail`
+
+```bash
+#!/usr/bin/env bash
+set -uo pipefail
+```
+
+Without `-u` the script silently tolerates undefined variables; without `pipefail` pipe failures stay invisible. **Do not use `set -e`** in hooks — exit code is your gate and you want explicit control.
+
+### 2. Exit 0 vs exit != 0
+
+- `exit 0` on any event = does not block.
+- `exit != 0` on **PreToolUse** = cancels the tool execution (gate).
+- `exit != 0` on **PostToolUse**, **Stop**, **Notification** = informational only; the tool already ran.
+- `exit != 0` on **UserPromptSubmit** = cancels sending the prompt to the model (hard gate).
+
+### 3. Path resolution — global vs project
+
+**Global hooks** (`~/.claude/settings.json`): NEVER use `$CLAUDE_PROJECT_DIR` to point to the hook's own artifacts. That variable resolves to the **currently active project**, which may not contain the script. Use `$(dirname "${BASH_SOURCE[0]}")` (the running Bash script's own directory) or a hardcoded absolute path.
+
+**Project hooks** (`.claude/settings.json`): `$CLAUDE_PROJECT_DIR` correctly resolves to the repo root, so it is safe.
+
+History: the `bash-source-hook-path.md` bug (P1, fixed in `b7397e2`) was precisely this — the global `subagent-telemetry.sh` used `$CLAUDE_PROJECT_DIR` and the writer was never found.
+
+### 4. Windows-friendly
+
+Claude Code on Windows runs hooks via Git Bash or WSL. To stay portable:
+
+- Use forward slashes in paths whenever possible
+- Do not call CMD/PowerShell utilities — POSIX only (`bash`, `jq`, `node`, `git`)
+- Test in Git Bash before committing
+- Windows absolute paths work if prefixed with `/c/...` (Git Bash) or `C:\\...` escaped
+
+### 5. JSON payload via stdin
+
+Most events deliver a JSON payload on stdin. Parse with `jq`:
+
+```bash
+payload=$(cat)
+file_path=$(echo "$payload" | jq -r '.file_path // empty')
+command=$(echo "$payload" | jq -r '.command // empty')
+```
+
+Always use `// empty` in `jq` to avoid the literal `"null"` string when the field is missing.
+
+### 6. Debug logs do not reach the user
+
+Stderr is silenced in Claude Code for non-blocking events. For persistent debugging, write to a file:
+
+```bash
+echo "DEBUG: $(date) - hook fired with $file_path" >> /tmp/my-hook.log
+```
+
+---
+
+## Cross-references
+
+- [Architecture overview](architecture-overview) — how hooks fit into the broader pipeline
+- `docs/brain/bugs/bash-source-hook-path.md` — historical path resolution bug
+- `scripts/hooks/telemetry-writer.js` — SQLite writer that feeds the telemetry dashboard