start-vibing-stacks 2.14.0 → 2.16.0

package/stacks/_shared/skills/docs-tracker/SKILL.md

@@ -1,56 +1,104 @@
 ---
 name: docs-tracker
-version: 1.0.0
+version: 2.0.0
+description: "File → domain mapping rules and changelog templates consumed by `documenter` v2.0.0. Detects modified files via `git diff-tree`, classifies them via `.claude/config/domain-mapping.json`, and emits the actions documenter must apply (Edit known anchors, never Write over existing files; bidirectional connections; cap commit log at 20)."
 ---
 
-# Docs Tracker — Automatic Documentation System
+# Docs Tracker — File → Domain Mapping Rules (v2.0.0)
 
-**ALWAYS invoke AFTER implementation completes.**
+**ALWAYS invoke AFTER `commit-manager` succeeds (so the commit hash is real).**
 
-## Execution Flow
+This skill is the **rule set** consumed by `documenter` v2.0.0. It does not write files itself — it tells documenter what to do with each changed file.
 
+## Detection (one git call, not many)
+
+```bash
+# Files in the LAST commit (after commit-manager pushed)
+git diff-tree --no-commit-id --name-status -r HEAD
 ```
-1. DETECT CHANGES → git diff --name-status
-        ↓
-2. CLASSIFY → A=Added, M=Modified, D=Deleted
-        ↓
-3. CHECK EXISTING DOCS → codebase-knowledge/domains/
-        ↓
-4. CREATE/UPDATE/REMOVE as needed
-        ↓
-5. UPDATE CLAUDE.md "Last Change" section
-```
 
-## What to Document
+Status codes: `A` = added, `M` = modified, `D` = deleted, `R` = renamed, `C` = copied. Treat `R` and `C` as `M` for mapping purposes plus a "renamed from" note in the destination domain.
+
+## File → Domain mapping
+
+Source of truth: `.claude/config/domain-mapping.json` (shipped with this CLI; project may override). A path may map to ≥1 domain. Unmatched paths → `general`.
+
+Skip the entire pass if every changed path matches one of:
 
-| Change Type | Action |
+| Skip pattern | Reason |
 |---|---|
-| New file | Create domain entry if new domain |
-| Modified file | Update domain "Last Update" + "Recent Commits" |
-| Deleted file | Remove from domain "Files" table |
-| New connection | Add to "Connections" in BOTH domains |
-| Bug fix | Add to "Problems & Solutions" |
+| `.claude/**` | meta — does not belong to any product domain |
+| `docs/**` | docs commit — no code drift |
+| `.github/**` | CI — handled by `infrastructure` domain only if pattern is added |
+| `CHANGELOG*`, `*.md` (root only) | release docs |
+| `package.json`, `composer.json`, `pyproject.toml` (deps only — not scripts) | bumps tracked elsewhere |
+
+## Action matrix (applied by `documenter`)
+
+| Git status | Domain file state | Action |
+|---|---|---|
+| `A` | exists | `Edit`: append row to `## Files`, prepend row to `## Recent Commits`, increment `files_count` in frontmatter |
+| `A` | missing | `Write`: create from `TEMPLATE.md`, fill TL;DR, add the file row, add the commit row |
+| `M` | exists | `Edit`: prepend row to `## Recent Commits`; if file's role description changed, update its row in `## Files` |
+| `M` | missing | unusual — investigate; usually means mapping rule was added but file existed before. Treat as `A` |
+| `D` | exists | `Edit`: strike-through (`~~path~~`) row in `## Files`, decrement `files_count`. Prune at the next pass |
+| `R src→dst` | exists | `Edit`: replace `src` row with `dst` row, add note `(renamed from src in <short-sha>)` to Attention Points |
+
+## Bidirectional connections (mandatory)
+
+When a session adds `auth → api` to `auth.md`, **also** add `api ← auth` to `api.md`. The two edits must succeed atomically — if the second fails, roll back the first. The `security-auditor` flags dangling links as a MEDIUM finding.
+
+## Cap and archive (size guard)
 
-## Detection Commands
+After any edit, check the live file:
 
 ```bash
-# What changed?
-git diff --name-status HEAD~1
+[ "$(wc -c < domains/<slug>.md)" -gt 8192 ] && trigger_archive
+```
+
+When triggered, move the **oldest 5 rows** of `## Recent Commits` (and oldest 2 Problems & Solutions, oldest 3 Attention Points) into `<slug>.archive.md`. Live file must stay ≤ 8 KB.
 
-# What's staged?
-git diff --name-only --cached
+## Index regeneration (after every pass)
 
-# What's unstaged?
-git diff --name-only
+```bash
+# Regenerate _index.json from frontmatter of every domain file
+for f in .claude/skills/codebase-knowledge/domains/*.md; do
+  # parse YAML frontmatter, compute summary_sha = sha256(TL;DR block), emit one record
+done | jq -s '{schema_version:1, generated_at:(now|todate), domain_count:length, domains:.}' \
+     > .claude/skills/codebase-knowledge/_index.json
 
-# What's untracked?
-git ls-files --others --exclude-standard
+# Then derive _INDEX.md from _index.json
+```
+
+`_index.json` is the source of truth — `_INDEX.md` is human-readable derivative.
+
+## Pre-commit hook (CI integration)
+
+A repository can add this check to fail builds when documenter forgot to run:
+
+```bash
+HEAD_SHA=$(git rev-parse --short HEAD)
+LAST_INDEXED=$(jq -r '.domains | map(.last_commit) | unique[]' \
+  .claude/skills/codebase-knowledge/_index.json)
+echo "$LAST_INDEXED" | grep -qx "$HEAD_SHA" || {
+  echo "ERROR: _index.json is stale. Run documenter before pushing."
+  exit 1
+}
 ```
 
 ## Rules
 
-1. **RUN AFTER EVERY IMPLEMENTATION** — no exceptions
-2. **DETECT VIA GIT** — don't guess, use git diff
-3. **UPDATE DOMAINS** — not just CLAUDE.md
-4. **BIDIRECTIONAL** — if A↔B connection, update both
-5. **INCLUDE COMMIT HASH** — traceability
+1. **AFTER `commit-manager`** — never before; the hash must be real.
+2. **DETECT VIA GIT** — `git diff-tree -r HEAD`, never guess from session memory.
+3. **EDIT KNOWN ANCHORS** — `documenter` uses `Edit` / `StrReplace` on existing domain files; never `Write` over them.
+4. **BIDIRECTIONAL** — both ends of every connection updated atomically.
+5. **CAP AT 8 KB / 20 commits / 10 attention / 5 P&S** — archive overflow into `<slug>.archive.md`.
+6. **REGENERATE `_index.json` EVERY PASS** — derived; never hand-edited.
+7. **SKIP META PATHS** — `.claude/**`, `docs/**`, `.github/**` do not get domain entries.
+
+## See Also
+
+- `documenter` v2.0.0 — applies the actions defined here
+- `codebase-knowledge` v2.0.0 — reads what documenter wrote
+- `domain-updater` v2.0.0 — appends session wisdom AFTER documenter
+- `.claude/config/domain-mapping.json` — pattern → domain rules

package/stacks/_shared/skills/git-workflow/SKILL.md

@@ -1,40 +1,163 @@
 ---
 name: git-workflow
-version: 1.0.0
+version: 2.0.0
+description: "Git workflow conventions used by commit-manager v2.0.0+: Conventional Commits (no AI-attribution footers), branch naming, direct-to-main vs feature-branch flow, end-on-main rule, push policy, never force-push main, signed commits encouraged. Invoke when starting a feature, creating commits, pushing, or wiring git-related hooks."
 ---
 
 # Git Workflow
 
-## Branch Naming
+**ALWAYS invoke when starting work, creating commits, pushing, or wiring `pre-commit` / `Stop` hooks that touch git.**
+
+> The git history is documentation. A reader six months from now should understand *why*, not just *what*. The commit-manager agent enforces the message format below; this skill defines what counts as compliant.
+
+## 1. Branch naming
 
 ```
-feature/short-description
-fix/bug-description
-refactor/what-changed
-chore/maintenance-task
+feature/<short-kebab-description>
+fix/<bug-id-or-description>
+refactor/<area-changed>
+chore/<maintenance-task>
+docs/<scope>
+ci/<workflow-area>
 ```
 
-## Commit Format (Conventional)
+Rules:
+- Always kebab-case, never spaces or underscores.
+- ≤ 50 chars; longer goes in the PR description.
+- One feature per branch.
+
+## 2. Conventional Commits — required format
+
+```
+<type>(<scope>): <subject>
+
+<body — wrapped at ~72 cols; bullets when ≥ 3 files affected>
+```
+
+| Type | When |
+|---|---|
+| `feat` | New user-visible capability |
+| `fix` | Bug fix |
+| `refactor` | Internal change, no behavior change |
+| `perf` | Performance improvement |
+| `test` | Tests added/changed only |
+| `docs` | Documentation only |
+| `chore` | Build, deps, tooling — nothing user-visible |
+| `ci` | CI/CD config |
+| `style` | Formatting only |
+| `revert` | Reverts a prior commit |
+| `build` | Build system / bundler config |
+
+Subject:
+- ≤ 50 chars
+- imperative ("add login retry", not "added", not "adds")
+- no trailing period
+- lowercase first word (after the type/scope prefix)
+
+Body (only when ≥ 3 files or non-obvious *why*):
+- explain motivation, trade-offs, links to issues
+- bullet list when summarizing multiple changes
+
+### Example
 
 ```
-type(scope): description
+feat(auth): add session refresh with rotating cookies
 
-Body explaining what and why.
+- Issue rotated session id on each login + every 7 days
+- Persist previous id for 30s grace window to avoid races
+- Drop legacy cookie name `sid` from response set; honor on read
+```
 
+### **No AI-attribution footers** *(commit-manager v2.0.0+ rule)*
+
+Do **not** append:
+```
 Generated with Claude Code
 Co-Authored-By: Claude <noreply@anthropic.com>
 ```
 
-## Flow
+The commit message describes the change. Tooling provenance lives in CI artifacts, signed commits, or release metadata — not in every commit body.
+
+## 3. Two valid flows
+
+The repo's CLAUDE.md (or `git-workflow` overlay) declares which is in effect.
+
+### Flow A — direct-to-main (small repos, single contributor, fast iteration)
+
+```
+1. Pull main, ensure clean tree
+2. Make changes
+3. Quality gate green
+4. Commit → push to main
+```
+
+### Flow B — feature branch + merge (multi-contributor, CI gates required)
 
-1. Create branch from main: `git checkout -b feature/name`
+```
+1. From clean main, create branch:    git checkout -b feature/<name>
 2. Work, commit incrementally
-3. When done: merge to main, delete branch
-4. Push main to remote
+3. Quality gate green
+4. Push branch:                       git push -u origin HEAD
+5. Open PR; CI must pass
+6. Merge (squash or rebase — never merge commit on main)
+7. Delete branch local + remote
+8. Checkout main, pull
+```
+
+End state in **both flows**: clean tree, on `main`, in sync with `origin/main`. The Stop validator enforces this.
+
+## 4. Push policy
+
+| Operation | Allowed | Notes |
+|---|---|---|
+| `git push` to feature branch | ✅ Always | Force-push only if branch is yours and not yet reviewed |
+| `git push` to main | ✅ When tree clean and CI green locally | Branch protection should reject otherwise |
+| `git push --force-with-lease` to feature branch | ✅ Preferred over `--force` | Refuses if remote moved since your last fetch |
+| `git push --force` to main | ❌ Never | Re-writes shared history |
+| `git push --no-verify` | ❌ Never | Bypasses hooks intentionally configured to gate |
+
+## 5. Pre-flight checklist (commit-manager runs this internally)
+
+- [ ] Working tree status reviewed (`git status -sb`)
+- [ ] Diff reviewed (`git diff --stat HEAD` then `git diff` if needed)
+- [ ] Quality gate passed (typecheck / lint / tests / build)
+- [ ] Security gate passed (`security-auditor` clean)
+- [ ] No secrets in diff (gitleaks)
+- [ ] CLAUDE.md `Last Change` updated when scope warrants it
+- [ ] Conventional commit message drafted
+- [ ] Push target confirmed (`origin main` vs `origin feature/*`)
+
+## 6. Tags & releases
+
+```bash
+# Annotated tags only — lightweight tags are stripped by some hosts
+git tag -a v1.2.3 -m "Release v1.2.3"
+git push origin v1.2.3
+```
+
+Semver: bump `MAJOR.MINOR.PATCH` per breaking/feature/fix.
+
+## 7. Recovering from mistakes
+
+| Situation | Fix |
+|---|---|
+| Bad commit not pushed | `git reset --soft HEAD~1`, fix, re-commit |
+| Bad commit pushed to feature branch | `git commit --amend` then `git push --force-with-lease` |
+| Bad commit pushed to main | `git revert <sha>` and push the revert (NEVER force-push main) |
+| Pushed a secret | Revoke at provider FIRST, then `git filter-repo` + force-push (one-time, document it) |
+| Wrong branch | `git stash`, `git checkout <correct>`, `git stash pop` |
 
 ## Rules
 
-- NEVER force push main
-- ALWAYS conventional commits
-- ALWAYS end on main branch
-- ONE feature per branch
+- **NEVER** force-push `main` / `master`
+- **NEVER** `--no-verify` to bypass hooks
+- **ALWAYS** Conventional Commits, no AI-attribution footers
+- **ALWAYS** end on `main` with a clean tree (Stop validator enforces)
+- **ONE** feature per branch (or per direct-to-main commit batch)
+
+## See Also
+
+- `commit-manager` agent — drives the message + push pipeline
+- `quality-gate` — the gate the commit-manager waits for
+- `secrets-management` — gitleaks 3-layer (pre-commit, CI, push protection)
+- `ci-pipelines` — branch-protection rules that mirror this skill

package/stacks/_shared/skills/hook-development/SKILL.md

@@ -1,93 +1,271 @@
 ---
 name: hook-development
-version: 1.0.0
+version: 2.0.0
+description: "Claude Code hook development for 2026. Covers all 9 supported events (UserPromptSubmit, PreToolUse, PostToolUse, Notification, Stop, SubagentStop, SessionStart, SessionEnd, PreCompact), stdin/stdout JSON contract, decision/continue/systemMessage outputs, matchers (tool patterns), exit-code semantics, cycle detection (stop_hook_active), settings.json registration, run-hook.sh dispatcher (bun → tsx → node fallback). Invoke when creating or modifying any .claude/hooks/* file or settings.json hook entry."
 ---
 
-# Hook Development — Claude Code Hooks
+# Hook Development — Claude Code Hooks (2026)
 
 **ALWAYS invoke when creating or modifying Claude Code hooks.**
 
-## Hook Types
+> Hooks are user-controlled deterministic gates around the model. Anything you want **enforced**, not asked nicely — put in a hook. The agent cannot disable a hook from inside the conversation.
 
-| Event | When | Use Case |
-|-------|------|----------|
-| `UserPromptSubmit` | Before prompt is sent | Inject workflow, validate input |
-| `Stop` | Before task completion | Validate state, block if dirty |
-| `PreToolUse` | Before tool execution | Approve/block dangerous tools |
-| `PostToolUse` | After tool execution | Log, validate output |
+## 1. Supported events (Claude Code, 2026)
 
-## File Structure
+| Event | Fires | Common use |
+|---|---|---|
+| `SessionStart` | When a session begins (new chat or resume) | Inject onboarding context, restore state |
+| `SessionEnd` | When a session ends cleanly | Flush logs, persist state, run cleanup |
+| `UserPromptSubmit` | After user submits, before model receives | Inject workflow rules, block forbidden phrases |
+| `PreToolUse` | Before any tool is invoked | Approve / block / rewrite tool calls (security gate) |
+| `PostToolUse` | After tool completes | Log, validate output, react to specific tool results |
+| `Notification` | When the agent is idle and notifies (e.g. waiting for input) | Desktop notifications, status forwarding |
+| `Stop` | Before the agent ends its turn | Validate completion (clean tree, tests pass, docs updated) |
+| `SubagentStop` | When a Task() subagent finishes | Validate subagent output, persist artifacts |
+| `PreCompact` | Before transcript compaction is triggered | Snapshot/export full transcript first |
+
+`Stop` and `Subagent` events are the most commonly customized. `PreToolUse` is the security workhorse.
+
+## 2. File layout
 
 ```
-.claude/hooks/
-├── run-hook.sh              # Entry point (bash → bun/tsx fallback)
-├── user-prompt-submit.ts    # Prompt injection
-└── stop-validator.ts        # Task completion gate
+.claude/
+├── hooks/
+│   ├── run-hook.sh           # Entry point: bun → tsx → node fallback
+│   ├── session-start.ts
+│   ├── session-end.ts
+│   ├── user-prompt-submit.ts
+│   ├── pre-tool-use.ts
+│   ├── post-tool-use.ts
+│   ├── stop-validator.ts
+│   ├── subagent-stop.ts
+│   ├── pre-compact.ts
+│   └── lib/                  # shared helpers (cmd(), readStdin(), etc.)
+└── settings.json             # registers hooks
 ```
 
-## Hook Input (stdin JSON)
+## 3. Stdin contract (per event)
+
+All hook input arrives as **a single JSON object on stdin**. Read with a timeout — never hang.
 
 ```typescript
-// UserPromptSubmit
-interface PromptInput {
-  user_prompt: string;
+// Common envelope (most events)
+interface HookInput {
   session_id: string;
+  cwd: string;
+  transcript_path?: string;
+  hook_event_name: string;        // e.g. "Stop"
 }
 
-// Stop
-interface StopInput {
-  stop_hook_active?: boolean;  // Cycle detection
-  transcript?: string;
+interface UserPromptSubmitInput extends HookInput {
+  user_prompt: string;
 }
-```
 
-## Hook Output (stdout JSON)
+interface PreToolUseInput extends HookInput {
+  tool_name: string;              // "Bash" | "Edit" | "Write" | ...
+  tool_input: Record<string, unknown>;
+}
 
-```typescript
-// UserPromptSubmit — inject system message
-{ "continue": true, "systemMessage": "WORKFLOW: ..." }
+interface PostToolUseInput extends PreToolUseInput {
+  tool_response: unknown;
+  tool_error?: string;
+}
 
-// Stop — approve or block
-{ "continue": false, "decision": "approve", "reason": "All checks passed" }
-{ "continue": true, "decision": "block", "reason": "Uncommitted files" }
+interface StopInput extends HookInput {
+  stop_hook_active?: boolean;     // TRUE if a previous Stop hook already blocked — don't loop
+}
+
+interface SubagentStopInput extends StopInput {
+  subagent_id: string;
+}
+
+interface PreCompactInput extends HookInput {
+  trigger: "manual" | "auto";
+}
 ```
 
-## Template: Stop Validator
+## 4. Stdout contract (per event)
 
-```typescript
-#!/usr/bin/env node
-import { execSync } from 'child_process';
+Output a **single JSON object on stdout**. Anything else (or invalid JSON) is treated as advisory only.
 
-function cmd(c: string): string {
-  try { return execSync(c, { encoding: 'utf8' }).trim(); } catch { return ''; }
+```typescript
+// Universal fields
+interface HookOutput {
+  continue?: boolean;             // false = stop the agent now (Stop family)
+  decision?: "approve" | "block"; // gate verdict
+  reason?: string;                // shown to user / logged
+  systemMessage?: string;         // injected as system message (UserPromptSubmit, SessionStart)
+  hookSpecificOutput?: Record<string, unknown>;
 }
+```
 
-const branch = cmd('git rev-parse --abbrev-ref HEAD');
-const dirty = cmd('git status --porcelain');
+PreToolUse — block / approve / rewrite a tool call:
+```json
+{ "decision": "approve", "reason": "Edit on src/ allowed" }
+{ "decision": "block",   "reason": "Write outside src/ rejected" }
+```
 
-const result = (!dirty && (branch === 'main' || branch === 'master'))
-  ? { continue: false, decision: 'approve', reason: 'Clean main branch' }
-  : { continue: true, decision: 'block', reason: `Branch: ${branch}, dirty: ${!!dirty}` };
+Stop — block prevents finalization until issues are fixed:
+```json
+{ "continue": true, "decision": "block", "reason": "Uncommitted files" }
+```
 
-console.log(JSON.stringify(result));
+SessionStart — inject context:
+```json
+{ "systemMessage": "ROUTINE: research → plan → implement → test → commit" }
 ```
 
-## settings.json Registration
+## 5. Exit-code semantics
+
+| Exit | Meaning |
+|---|---|
+| `0` | Success — JSON output applied if present |
+| `2` | **Blocking** — message printed to stderr is shown to the user (alternative to `decision: "block"`) |
+| anything else | Non-blocking error — logged, agent continues |
+
+**Never** exit non-zero on a transient error (e.g. network) unless you intend to block. Hooks must be deterministic.
+
+## 6. `settings.json` registration
 
 ```json
 {
   "hooks": {
-    "Stop": [{ "hooks": [{ "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/run-hook.sh\" stop-validator", "timeout": 30 }] }],
-    "UserPromptSubmit": [{ "matcher": "", "hooks": [{ "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/run-hook.sh\" user-prompt-submit", "timeout": 10 }] }]
+    "SessionStart": [
+      {
+        "hooks": [{
+          "type": "command",
+          "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/run-hook.sh\" session-start",
+          "timeout": 10
+        }]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/run-hook.sh\" user-prompt-submit",
+          "timeout": 10
+        }]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Write|Edit",
+        "hooks": [{
+          "type": "command",
+          "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/run-hook.sh\" pre-tool-use",
+          "timeout": 10
+        }]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [{
+          "type": "command",
+          "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/run-hook.sh\" stop-validator",
+          "timeout": 30
+        }]
+      }
+    ]
   }
 }
 ```
 
-## Rules
+`matcher` is a regex against `tool_name` (PreToolUse / PostToolUse) or empty for "all". Multiple entries per event are run in registration order.
+
+## 7. `run-hook.sh` dispatcher
+
+Survives whichever runtime the user has installed. Always-zero exit so hook errors don't kill the session.
+
+```bash
+#!/usr/bin/env bash
+# .claude/hooks/run-hook.sh
+set -uo pipefail
+HOOK_NAME="${1:?missing hook name}"
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK_FILE="$HOOK_DIR/${HOOK_NAME}.ts"
+
+[[ -f "$HOOK_FILE" ]] || { echo '{"continue":true}'; exit 0; }
+
+if   command -v bun >/dev/null 2>&1; then bun  "$HOOK_FILE"
+elif command -v tsx >/dev/null 2>&1; then tsx  "$HOOK_FILE"
+elif command -v node >/dev/null 2>&1; then npx --yes tsx "$HOOK_FILE"
+else echo '{"continue":true}'; exit 0
+fi
+```
+
+## 8. Stop validator template (gate-aware, with cycle detection)
+
+Use `execFileSync` (not `execSync` with shell strings) — passes args as an array, immune to shell injection.
+
+```typescript
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+
+function git(...args: string[]): string {
+  try { return execFileSync('git', args, { encoding: 'utf8' }).trim(); } catch { return ''; }
+}
+
+const input = JSON.parse(readFileSync(0, 'utf8'));      // stdin
+
+// Cycle detection — if we already blocked once, approve to avoid infinite loop
+if (input.stop_hook_active) {
+  console.log(JSON.stringify({ continue: false, decision: 'approve' }));
+  process.exit(0);
+}
+
+const dirty   = git('status', '--porcelain');
+const issues: string[] = [];
+
+if (dirty)                                                    issues.push(`GIT_TREE_NOT_CLEAN: ${dirty.split('\n').length} file(s)`);
+if (existsSync('CLAUDE.md') &&
+    !readFileSync('CLAUDE.md', 'utf8').includes('Last Change')) issues.push('CLAUDE_MD_NOT_UPDATED');
+
+const result = issues.length === 0
+  ? { continue: false, decision: 'approve', reason: 'All checks passed' }
+  : { continue: true,  decision: 'block',   reason: issues.join(' | ') };
+
+console.log(JSON.stringify(result));
+process.exit(0);
+```
+
+## 9. Performance & safety rules
+
+1. **Timeouts:** 10s for `UserPromptSubmit` / `PreToolUse` / `SessionStart`; 30s for `Stop` / `SubagentStop`.
+2. **Always exit 0** unless intentionally blocking with exit 2 — non-zero kills the session.
+3. **Read stdin with timeout** — `readFileSync(0, 'utf8')` is fine (it returns immediately when EOF).
+4. **Output valid JSON** — invalid JSON is treated as advisory and silently dropped.
+5. **Cycle detection** — check `stop_hook_active` in `Stop` / `SubagentStop`. Without this, a buggy hook can lock the agent in an infinite block-fix-block loop.
+6. **No network calls** in hot-path hooks (`PreToolUse`, `UserPromptSubmit`) — they fire on every tool call / prompt.
+7. **Idempotent** — hooks may be invoked twice (retries, restarts). Don't write to immutable state without a guard.
+8. **Use `execFileSync`, never `execSync` with a shell string** — the latter is shell-injection-prone if any input ever flows in.
+
+## 10. Common patterns
+
+| Goal | Event | Pattern |
+|---|---|---|
+| "Inject the current routine on every prompt" | `UserPromptSubmit` | `{ continue: true, systemMessage: "ROUTINE: ..." }` |
+| "Block writes outside `src/`" | `PreToolUse` | match `Write\|Edit`, inspect `tool_input.path`, `decision: "block"` if outside |
+| "Run quality gate before finishing" | `Stop` | run typecheck/lint/tests, `decision: "block"` if any fail |
+| "Persist subagent output to disk" | `SubagentStop` | parse `tool_response`, write to `.claude/subagent-outputs/{id}.json` |
+| "Snapshot transcript before compaction" | `PreCompact` | copy `transcript_path` to `.claude/transcripts/{session_id}.jsonl` |
+
+## FORBIDDEN
+
+| Pattern | Why |
+|---|---|
+| `process.exit(1)` on transient error | Kills the session |
+| Hook output not valid JSON | Dropped silently — no enforcement |
+| Network call in `PreToolUse` | Adds latency to every tool call |
+| Forgetting `stop_hook_active` check | Infinite block loop |
+| Writing to `CLAUDE.md` from `Stop` hook | Triggers another `Stop` cycle |
+| Hardcoded user paths (`~/Users/me/...`) | Won't run on other machines |
+| Shell-string `execSync` for git/fs commands | Shell-injection surface |
+
+## See Also
 
-1. **Always use `run-hook.sh` as entry** — handles bun/tsx fallback
-2. **Read stdin with timeout** — hooks must not hang
-3. **Exit 0 always** — non-zero kills the session
-4. **Output valid JSON to stdout** — Claude Code parses it
-5. **Cycle detection** — check `stop_hook_active` flag in Stop hooks
-6. **Keep hooks fast** — timeout applies (10s for prompt, 30s for stop)
+- `quality-gate` — the Stop validator's typical payload
+- `git-workflow` — branch / dirty-tree checks
+- `commit-manager` — pairs with Stop validator (validator detects, commit-manager fixes)