docs(agents): add development guardrails, C++ language server docs, and Claude Code automation

.claude/hooks/block-generated-data.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# PreToolUse hook: block direct edits to generated dictionary data files.
+# These files are produced by the dictionary compiler and must not be edited manually.
+# Exit code 2 blocks the tool from executing.
+
+set -euo pipefail
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+# Reject paths with newlines or path traversal
+if [[ "$FILE_PATH" =~ $'\n' ]] || [[ "$FILE_PATH" == *".."* ]]; then
+  exit 2
+fi
+
+# Block generated data files in Source/Data/ (absolute or relative paths)
+case "$FILE_PATH" in
+  */Source/Data/data.txt|*/Source/Data/data-plain-bpmf.txt|*/Source/Data/associated-phrases-v2.txt| \
+  Source/Data/data.txt|Source/Data/data-plain-bpmf.txt|Source/Data/associated-phrases-v2.txt)
+    echo "Blocked: $FILE_PATH is a generated file. Edit the source and rebuild instead." >&2
+    exit 2
+    ;;
+esac

.claude/hooks/format-cpp.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# PostToolUse hook: auto-format C++/ObjC files with clang-format after edits.
+# Reads the tool input JSON from stdin to extract the edited file path.
+
+set -euo pipefail
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+# Read stdin JSON and extract file_path
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+# Reject paths with newlines, nulls, or path traversal
+if [[ "$FILE_PATH" =~ $'\n' ]] || [[ "$FILE_PATH" =~ $'\0' ]] || [[ "$FILE_PATH" == *".."* ]]; then
+  exit 0
+fi
+
+# Only format C++/ObjC source files
+case "$FILE_PATH" in
+  *.cpp|*.h|*.mm|*.m)
+    if [[ -f "$FILE_PATH" ]]; then
+      xcrun clang-format -i -- "$FILE_PATH"
+    fi
+    ;;
+esac

.claude/settings.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/format-cpp.sh"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/block-generated-data.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

.claude/skills/branch-guard/SKILL.md

@@ -0,0 +1,16 @@
+---
+description: Verify branch and worktree before making edits
+user-invocable: false
+---
+
+# Branch Guard
+
+Before editing files, verify:
+
+1. **Current branch**: Run `git rev-parse --abbrev-ref HEAD` and confirm it matches the expected branch for the current task.
+
+2. **Worktree isolation**: Run `git rev-parse --show-toplevel` and confirm edits target the correct worktree directory.
+
+3. **Clean state**: Run `git status --porcelain` and warn if there are uncommitted changes that might conflict.
+
+If any check fails, stop and alert the user before proceeding.

.claude/skills/engine-test/SKILL.md

@@ -0,0 +1,32 @@
+---
+description: Build and run C++ engine tests
+user-invocable: true
+---
+
+# /engine-test
+
+Build and run the full C++ engine unit tests.
+
+## Steps
+
+1. Create the build directory if needed:
+   ```bash
+   mkdir -p Source/Engine/build
+   ```
+
+2. Configure with CMake:
+   ```bash
+   cd Source/Engine/build && cmake -DENABLE_TEST=ON -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ..
+   ```
+
+3. Build:
+   ```bash
+   cd Source/Engine/build && make -j$(sysctl -n hw.ncpu)
+   ```
+
+4. Run tests:
+   ```bash
+   cd Source/Engine/build && ctest --output-on-failure
+   ```
+
+Report test results. If any tests fail, show the failing test names and output.

.gitignore

@@ -16,4 +16,6 @@ xcuserdata
 .vscode
 __pycache__
 codecov_comment.md
-DerivedData
+DerivedData
+compile_commands.json
+.cache