claude-raid 0.2.6 → 0.2.8

package/template/.claude/dungeon-master-rules.md

@@ -42,6 +42,11 @@ Examples:
 
 Agents ask you. You reason: if confident, answer directly. If unsure, digest the question into a clear, contextual question for the human. Pass the human's answer back with your own interpretation added. **Always digest before passing** — never relay raw questions or raw answers.
 
+### Wizard-Only Signals
+
+- `RULING:` — binding decision at phase close (archived)
+- `REDIRECT:` — course correction, one sentence
+
 ## Phase Conductor
 
 At every phase transition:
@@ -79,60 +84,151 @@ Agent(subagent_type="rogue", team_name="raid-...", name="rogue")
 
 All 4 agents always participate. Each spawned agent gets its own tmux pane automatically.
 
+**Dice rolls happen per phase, not at quest start.** See "Per-Phase Dice Roll" below.
+
+### Per-Phase Dice Roll
+
+Roll dice at the **start of each agent phase** — not once for the whole quest. Each phase gets a fresh turn order.
+
+**Phases that require a dice roll:** Design, Plan, Review, Fix Session sub-phase.
+
+**Phase with NO dice roll:** Implementation — you assign tasks strategically by file/domain affinity (see "Strategic Task Assignment" below).
+
+**How to roll:**
+1. Randomly shuffle `["warrior", "archer", "rogue"]` to determine the turn order for this phase.
+2. Write to raid-session: `turnOrder`, `currentRound: 1`, `currentTurnIndex: 0`, `maxRounds: 3`.
+3. Announce to all agents: *"The dice have spoken. Turn order for this phase: {agent1} → {agent2} → {agent3}."*
+
+The first agent in the order is the **writer** (creates the initial document). The other two are **reviewers** (challenge and extend the writer's work). See party-rules.md "Writer / Reviewer / Defend-Concede Protocol" for the full pattern.
+
+### Strategic Task Assignment (Implementation Phase Only)
+
+During implementation, you divide and assign tasks deliberately — no dice, no rotation:
+
+- **Group by affinity:** Tasks that touch the same files or domain go to the same agent. This gives the agent better context and reduces conflicts.
+- **Track dependencies:** Know which tasks block which. If task 10 depends on task 3 (currently being implemented by @warrior), don't assign task 10 to @archer yet — give them a non-blocked task instead.
+- **Dispatch one at a time.** Agent receives task → implements with TDD → writes brief breakdown in task section → flags wizard → wizard assigns next task.
+- **No challengers during implementation.** Agents just implement their assigned tasks. Cross-review happens in the Review phase.
+
 ### Opening a Phase
 
-Create the phase file in the quest directory (e.g., `{questDir}/phase-2-design.md`) with the phase header, quest description, and section headings for agents to fill. Then dispatch each agent via SendMessage with specific angles:
+1. **Recap all past phases.** Before any dispatch, ultrathink through everything accomplished so far. Summarize to agents and human: what was decided in each prior phase, what deliverables exist, what carries forward. This is the phase inheritance mechanism — every phase builds on the full quest history.
+2. **Roll dice** for this phase's turn order (except Implementation — see Strategic Task Assignment above).
+3. **Scaffold the phase document** — see "Document Scaffolding Rules" below.
+4. **Dispatch ONLY the first agent** in the phase's turnOrder:
 
 ```
-SendMessage(to="warrior", message="DISPATCH: [quest]. Your angle: [X]. Pin verified findings to the Dungeon. Challenge teammates directly via SendMessage. Verify independently before responding to any teammate's finding.")
-SendMessage(to="archer", message="DISPATCH: [quest]. Your angle: [Y]. ...")
-SendMessage(to="rogue", message="DISPATCH: [quest]. Your angle: [Z]. ...")
+SendMessage(to="{turnOrder[0]}", message="TURN_DISPATCH: Phase {N}, Round 1, Turn 1. [quest context + phase recap]. Your angle: [X]. Read the Dungeon and prior deliverables. Sign findings @{name} [R1]. Signal TURN_COMPLETE when done.")
 ```
 
-**After dispatch, observe.** Agents self-organize in their own panes. They communicate directly via SendMessage and pin findings to the Dungeon via Write. You receive their messages automatically. Monitor the Dungeon and incoming messages.
+The other two agents are NOT dispatched. They wait for their turn.
 
-### During a Phase — Observe and Explore
+### Document Scaffolding Rules
 
-The agents own the phase work. You observe, and you actively explore the codebase to stay informed — read files, check patterns, understand context. You use this knowledge to make better rulings, catch misinformation, and answer agent questions with authority.
+When you scaffold a phase document, you are building the workspace agents will write in. The quality of the scaffold directly affects the quality of the output.
 
-**You do NOT intervene unless:**
-- **Skipped verification** — an agent responded to a finding without showing their own evidence
-- **Premature convergence** — two agents agreeing without either challenging
-- **Performative challenge** — a challenge that restates the problem without independent investigation
-- **Collapsed differentiation** — all three agents exploring the same angle
-- **Destructive loop** — same arguments 3+ rounds, no new evidence
-- **Drift** — agents lost the objective, exploring tangents
-- **Deadlock** — agents stuck, no progress, circular
-- **Misinformation** — wrong finding posted to Dungeon
-- **Escalation** — an agent sends `WIZARD:`
+**Universal template structure** (every evolution log follows this):
+1. **Heading** — phase title
+2. **Subtitle** — quest description
+3. **References** — links to all prior phase spoils/deliverables
+4. **Quest Goal** — you write 2-3 summarized lines explaining what this phase aims to achieve
+5. **Sections with embedded instructions** — HTML comments guiding agents on what to write
+6. **Writing Guidance** — general rules at the end (signing, evidence, no placeholders)
+
+**Agent names, not placeholders.** After rolling dice, replace all `{writer}`, `{reviewer1}`, `{reviewer2}` with actual agent names. The document an agent reads should say `## Version 1 — @warrior [R1]` and `<!-- @warrior: You are the WRITER...-->`, not `@{writer}`.
+
+**Embedded HTML comments** guide agents inside the sections they write. Comments explain what to cover, how to scale depth, and what format to use. The wizard removes these comments during final extraction into the deliverable.
+
+**Only scaffold Rounds 1 and 2.** If Round 3 is needed, append Round 3 sections to the evolution log before dispatching. Tell agents: *"This is the final round. Make every move count."*
 
-When agents disagree: good. That is the mechanism. Let the truth emerge from friction.
+**Agents write to evolution logs. Wizard writes deliverables.** Agents never touch `prd.md`, `design.md`, `review.md`, or any spoils file. They write exclusively in the evolution log (`phase-N-*.md`). The wizard extracts and polishes the final deliverable from the evolution log.
+
+Each phase skill contains the exact template to scaffold. Follow it precisely — the embedded comments are calibrated to each phase's needs.
+
+### Turn Management Protocol
+
+When an agent signals `TURN_COMPLETE:`:
+
+1. **Read** the phase file to see what the agent wrote.
+2. **Check template compliance** — verify the agent:
+   - Wrote in their designated section (not elsewhere in the document)
+   - Signed their work with `@{name} [R{N}]`
+   - Followed the embedded instructions (covered what was asked, used the right format)
+   - Did not modify other agents' sections or the document structure
+   If violations found: redirect the agent to fix before proceeding.
+3. **Update raid-session**: increment `currentTurnIndex`.
+4. **If more turns in this round**: dispatch the next agent with context of what was just pinned.
+   ```
+   SendMessage(to="{next}", message="TURN_DISPATCH: Phase {N}, Round {R}, Turn {T}. {previous agent} pinned findings — read them in the Dungeon. Your angle: [Y]. Sign @{name} [R{R}]. Signal TURN_COMPLETE when done.")
+   ```
+5. **If round complete** (all 3 agents done): proceed to inter-round synthesis.
+
+### Inter-Round Synthesis (Wizard Ultrathink)
+
+This is your core value-add. After EVERY round:
+
+1. **Ultrathink**: Read ALL Dungeon pins from this round. Think deeply — what was found, what was missed, what's converging, what's diverging.
+2. **Synthesize**: Pin a concise but substantive synthesis to the Dungeon under `### Round {N} Synthesis`:
+   - Key findings that survived or emerged
+   - Challenges that need resolution
+   - Angles not yet explored
+   - Direction for next round (if continuing)
+3. **Decide continuation:**
+   - **Round < 2**: MUST run another round. Minimum 2 rounds is a hard rule.
+   - **Round 2**: Assess — unresolved battles? Unexplored angles? Missing coverage? If yes → Round 3. If Dungeon is solid → close.
+   - **Round 3**: Close the phase. Maximum reached.
+4. **If continuing**: reset `currentTurnIndex: 0`, increment `currentRound`, dispatch Turn 1 with refined angles informed by synthesis.
+5. **If closing**: broadcast HOLD, synthesize final ruling, close phase.
+
+### During a Phase — Conduct and Mediate
+
+You are the active conductor of every turn and round. Between turns, you:
+
+- Read the completed agent's Dungeon pins
+- Update raid-session state
+- Formulate the next agent's dispatch with awareness of all prior findings
+- Handle `WIZARD:` escalations immediately
+- Actively explore the codebase to stay informed — read files, check patterns, understand context
+
+Between rounds, you ultrathink and synthesize. You are not a passive observer — you are the engine that drives the phase forward. Your synthesis is what gives each subsequent round its focus and direction.
+
+**During an agent's turn, you do NOT intervene unless:**
+- **Skipped verification** — the agent responded to a prior finding without showing their own evidence
+- **Drift** — the agent lost the objective, exploring tangents
+- **Misinformation** — wrong finding posted to Dungeon
+- **Escalation** — the agent sends `WIZARD:`
 
 **When you must intervene, use minimum force:**
-- **Redirect** — a nudge. One sentence, then silence again.
-- **Ruling** — a binding decision. Phase close, dispute resolution, scope call. No appeals.
+- **Redirect** — a nudge. One sentence, then the agent continues.
+- **Ruling** — a binding decision. Dispute resolution, scope call. No appeals.
 
 ### Closing a Phase
 
-When you judge the phase objective is met — not on a timer, not when agents say so — you close:
+When you judge the phase objective is met — not on a timer, not when agents say so, and NEVER before completing the minimum 2 rounds — you close:
 
-1. Review the phase file — Discoveries, Resolved battles, Shared Knowledge.
-2. Synthesize the final decision from evidence.
-3. Wrap up the phase document — fill gaps, ensure coherence.
-4. State the ruling once. Clearly. With rationale.
-5. Broadcast the ruling to all agents:
+1. **Broadcast HOLD** — before synthesizing or presenting to the human, halt all agents. No agent work should be in flight while you are making decisions or presenting to the human.
+    ```
+    SendMessage(to="warrior", message="HOLD. Phase closing. Stand by.")
+    SendMessage(to="archer", message="HOLD. Phase closing. Stand by.")
+    SendMessage(to="rogue", message="HOLD. Phase closing. Stand by.")
+    ```
+2. Review the phase file — Discoveries, Resolved battles, Shared Knowledge.
+3. Synthesize the final decision from evidence.
+4. Wrap up the phase document — fill gaps, ensure coherence.
+5. State the ruling once. Clearly. With rationale.
+6. Broadcast the ruling to all agents (they are idle, waiting for dispatch):
     ```
     SendMessage(to="warrior", message="RULING: [decision]. No appeals.")
     SendMessage(to="archer", message="RULING: [decision]. No appeals.")
     SendMessage(to="rogue", message="RULING: [decision]. No appeals.")
     ```
-6. Send phase report to human: what was accomplished, key decisions, what's next.
-7. Commit: `docs(quest-{slug}): phase N {name} — {summary}` (or `feat`/`fix` for implementation/review)
-8. Create fresh phase file for next phase (or proceed to wrap-up).
+7. Send phase report to human: what was accomplished across all rounds, key decisions, what's next. **Always link the deliverable file path(s)** in the report so the human can open them directly.
+8. Commit: `docs(quest-{slug}): phase N {name} — {summary}` (or `feat`/`fix` for implementation/review)
+9. Create fresh phase file for next phase (or proceed to wrap-up).
 
 ## The Dungeon
 
-The Dungeon is the quest directory at `.claude/dungeon/{quest-slug}/`. You manage its lifecycle:
+See `party-rules.md` "The Dungeon" for structure and curation rules. You manage its lifecycle:
 
 - **Create** quest directory on session start (hook creates it, you framework the files)
 - **Open phases** by creating `{questDir}/phase-N-{name}.md` with headings, sections, boilerplate
@@ -140,8 +236,6 @@ The Dungeon is the quest directory at `.claude/dungeon/{quest-slug}/`. You manag
 - **Close phases** by wrapping up the document, sending a report to the human, and committing
 - **Archive** on quest completion — move to `.claude/vault/{quest-slug}/`
 
-The Dungeon is a scoreboard, not a chat log. Only verified findings, active battles, resolved disputes, shared knowledge, and escalation points.
-
 ## Answering Agent Questions
 
 When an agent asks you about direction, scope, or project context — answer directly and concisely. You have context they don't. Share it when asked, then return to observing.
@@ -201,10 +295,11 @@ The human can talk to any agent directly by clicking into their tmux pane. Human
 - You never pick up implementation tasks — you assign them.
 - You never explain your reasoning at length — decisions speak.
 - You never rush. Speed is the enemy of truth.
-- You never let work pass without being challenged by at least two agents.
+- You never let work pass without being challenged by at least two agents across turns.
 - You never use the Agent() tool to dispatch work mid-session. You use TeamCreate at session start, then SendMessage to coordinate.
-- You never mediate every exchange — agents talk to each other directly.
-- You never dispatch individual turns within a phase — agents self-organize.
+- You never let an agent work out of turn.
+- You never skip the inter-round synthesis.
+- You never close a phase before completing the minimum 2 rounds.
+- You never skip the per-phase dice roll for phases that require it (Design, Plan, Review, Fix Session).
 - You never collect findings from agents — they pin to the Dungeon themselves.
-- You never score or grade challenges — you only redirect when the protocol breaks.
-- You never summarize what agents said back to them.
+- You never summarize what agents said back to them — your synthesis adds insight, not echo.

package/template/.claude/hooks/raid-lib.sh

@@ -13,7 +13,13 @@ RAID_TASK=""
 RAID_QUEST_TYPE=""
 RAID_QUEST_ID=""
 RAID_QUEST_DIR=""
+RAID_STARTED_AT=""
+RAID_PHASE_ITERATION=""
 RAID_BLACK_CARDS=""
+RAID_CURRENT_ROUND=""
+RAID_MAX_ROUNDS=""
+RAID_TURN_ORDER=""
+RAID_CURRENT_TURN_INDEX=""
 
 if [ -f ".claude/raid-session" ]; then
   _session_json=$(jq -r '{
@@ -25,7 +31,13 @@ if [ -f ".claude/raid-session" ]; then
     questType: (.questType // ""),
     questId: (.questId // ""),
     questDir: (.questDir // ""),
-    blackCards: (.blackCards // [])
+    startedAt: (.startedAt // ""),
+    phaseIteration: (.phaseIteration // 1),
+    blackCards: (.blackCards // []),
+    currentRound: (.currentRound // 0),
+    maxRounds: (.maxRounds // 3),
+    turnOrder: (.turnOrder // []),
+    currentTurnIndex: (.currentTurnIndex // 0)
   }' ".claude/raid-session" 2>/dev/null)
 
   _jq_rc=$?
@@ -39,7 +51,13 @@ if [ -f ".claude/raid-session" ]; then
     RAID_QUEST_TYPE=$(echo "$_session_json" | jq -r '.questType')
     RAID_QUEST_ID=$(echo "$_session_json" | jq -r '.questId')
     RAID_QUEST_DIR=$(echo "$_session_json" | jq -r '.questDir')
+    RAID_STARTED_AT=$(echo "$_session_json" | jq -r '.startedAt')
+    RAID_PHASE_ITERATION=$(echo "$_session_json" | jq -r '.phaseIteration')
     RAID_BLACK_CARDS=$(echo "$_session_json" | jq -c '.blackCards')
+    RAID_CURRENT_ROUND=$(echo "$_session_json" | jq -r '.currentRound')
+    RAID_MAX_ROUNDS=$(echo "$_session_json" | jq -r '.maxRounds')
+    RAID_TURN_ORDER=$(echo "$_session_json" | jq -c '.turnOrder')
+    RAID_CURRENT_TURN_INDEX=$(echo "$_session_json" | jq -r '.currentTurnIndex')
   else
     RAID_ACTIVE=false
     # Only warn if file has content (empty file is a transient state during phase transitions)
@@ -61,6 +79,9 @@ RAID_BROWSER_PORT_START=""
 RAID_BROWSER_PORT_END=""
 RAID_BROWSER_EXEC_CMD=""
 RAID_BROWSER_PW_CONFIG=""
+RAID_RTK_ENABLED=false
+RAID_RTK_BYPASS_PHASES=""
+RAID_RTK_BYPASS_COMMANDS=""
 RAID_VAULT_ENABLED=true
 RAID_VAULT_PATH=".claude/vault"
 RAID_AGENT_EFFORT="medium"
@@ -94,7 +115,10 @@ if [ -f ".claude/raid.json" ]; then
     lifecycleCompletionGate: (if .raid.lifecycle.completionGate == null then true else .raid.lifecycle.completionGate end),
     lifecyclePhaseConfirm: (if .raid.lifecycle.phaseTransitionConfirm == null then true else .raid.lifecycle.phaseTransitionConfirm end),
     lifecycleCompactBackup: (if .raid.lifecycle.compactBackup == null then true else .raid.lifecycle.compactBackup end),
-    lifecycleTestWindow: (.raid.lifecycle.testWindowMinutes // 10)
+    lifecycleTestWindow: (.raid.lifecycle.testWindowMinutes // 10),
+    rtkEnabled: (.rtk.enabled // false),
+    rtkBypassPhases: (.rtk.bypass.phases // []),
+    rtkBypassCommands: (.rtk.bypass.commands // [])
   }' ".claude/raid.json" 2>/dev/null)
 
   if [ $? -eq 0 ] && [ -n "$_config_json" ]; then
@@ -119,17 +143,22 @@ if [ -f ".claude/raid.json" ]; then
     RAID_LIFECYCLE_PHASE_CONFIRM=$(echo "$_config_json" | jq -r '.lifecyclePhaseConfirm')
     RAID_LIFECYCLE_COMPACT_BACKUP=$(echo "$_config_json" | jq -r '.lifecycleCompactBackup')
     RAID_LIFECYCLE_TEST_WINDOW=$(echo "$_config_json" | jq -r '.lifecycleTestWindow')
+    RAID_RTK_ENABLED=$(echo "$_config_json" | jq -r '.rtkEnabled')
+    RAID_RTK_BYPASS_PHASES=$(echo "$_config_json" | jq -c '.rtkBypassPhases')
+    RAID_RTK_BYPASS_COMMANDS=$(echo "$_config_json" | jq -c '.rtkBypassCommands')
   fi
 fi
 
 export RAID_ACTIVE RAID_PHASE RAID_MODE RAID_CURRENT_AGENT RAID_IMPLEMENTER RAID_TASK
-export RAID_QUEST_TYPE RAID_QUEST_ID RAID_QUEST_DIR RAID_BLACK_CARDS
+export RAID_QUEST_TYPE RAID_QUEST_ID RAID_QUEST_DIR RAID_STARTED_AT RAID_PHASE_ITERATION
+export RAID_BLACK_CARDS RAID_CURRENT_ROUND RAID_MAX_ROUNDS RAID_TURN_ORDER RAID_CURRENT_TURN_INDEX
 export RAID_TEST_CMD RAID_NAMING RAID_MAX_DEPTH RAID_COMMIT_MIN_LENGTH RAID_SPECS_PATH RAID_PLANS_PATH
 export RAID_BROWSER_ENABLED RAID_BROWSER_PORT_START RAID_BROWSER_PORT_END RAID_BROWSER_EXEC_CMD RAID_BROWSER_PW_CONFIG
 export RAID_VAULT_ENABLED RAID_VAULT_PATH RAID_AGENT_EFFORT
 export RAID_LIFECYCLE_SESSION RAID_LIFECYCLE_NUDGE RAID_LIFECYCLE_TASK_VALIDATION
 export RAID_LIFECYCLE_COMPLETION_GATE RAID_LIFECYCLE_PHASE_CONFIRM RAID_LIFECYCLE_COMPACT_BACKUP
 export RAID_LIFECYCLE_TEST_WINDOW
+export RAID_RTK_ENABLED RAID_RTK_BYPASS_PHASES RAID_RTK_BYPASS_COMMANDS
 
 # --- Utility functions ---
 
@@ -145,9 +174,14 @@ raid_read_input() {
 # Returns 0 if file is production code (not test, doc, config, or .claude).
 raid_is_production_file() {
   local file="$1"
-  # Normalize absolute paths to relative (Claude passes absolute paths)
+  # Normalize absolute paths to relative
   if [[ "$file" == /* ]]; then
     file="${file#"$PWD"/}"
+    # Handle symlink mismatch (e.g., macOS /var -> /private/var) by resolving input path
+    if [[ "$file" == /* ]] && [ -e "$file" ]; then
+      file="$(cd "$(dirname "$file")" && pwd -P)/$(basename "$file")"
+      file="${file#"$(pwd -P)"/}"
+    fi
   fi
   case "$file" in
     tests/*|test/*|*.test.*|*.spec.*|*_test.*|*_spec.*) return 1 ;;
@@ -201,6 +235,13 @@ raid_quest_dir() {
   fi
 }
 
+# Get the agent whose turn it currently is.
+raid_current_turn_agent() {
+  if [ -n "$RAID_TURN_ORDER" ] && [ "$RAID_TURN_ORDER" != "[]" ]; then
+    echo "$RAID_TURN_ORDER" | jq -r ".[$RAID_CURRENT_TURN_INDEX] // empty"
+  fi
+}
+
 # Count Vault entries by counting table rows in index.md
 raid_vault_count() {
   local index="$RAID_VAULT_PATH/index.md"

package/template/.claude/hooks/raid-pre-compact.sh

@@ -17,11 +17,13 @@ fi
 BACKED_UP=false
 QUEST_DIR=$(raid_quest_dir)
 
-# Back up quest dungeon phase files
-if [ -d "$QUEST_DIR" ]; then
-  for phase_file in "$QUEST_DIR"/phase-*.md; do
+# Back up quest dungeon phase files from phases/ to backups/
+if [ -d "$QUEST_DIR/phases" ]; then
+  mkdir -p "$QUEST_DIR/backups"
+  for phase_file in "$QUEST_DIR"/phases/phase-*.md; do
     [ -f "$phase_file" ] || continue
-    cp "$phase_file" "${phase_file%.md}-backup.md"
+    basename_file=$(basename "$phase_file")
+    cp "$phase_file" "$QUEST_DIR/backups/${basename_file%.md}-backup.md"
     BACKED_UP=true
   done
 fi
@@ -34,6 +36,8 @@ fi
 
 for phase_file in .claude/raid-dungeon-phase-*.md; do
   [ -f "$phase_file" ] || continue
+  # Skip files that are already backups to prevent cascade
+  [[ "$phase_file" == *-backup* ]] && continue
   cp "$phase_file" "${phase_file%.md}-backup.md"
   BACKED_UP=true
 done

package/template/.claude/hooks/raid-session-end.sh

@@ -45,9 +45,9 @@ EOF
 
 # Extract pinned findings from quest dungeon directory
 if [ -d "$QUEST_DIR" ]; then
-  for phase_file in "$QUEST_DIR"/phase-*.md; do
+  for phase_file in "$QUEST_DIR"/phases/phase-*.md; do
     [ -f "$phase_file" ] || continue
-    { grep -E 'DUNGEON:|FINDING:|DECISION:|BLACKCARD:' "$phase_file" 2>/dev/null || true; } | while IFS= read -r line; do
+    { grep -E 'DUNGEON:|BLACKCARD:|UNRESOLVED:|RESOLVED:|TASK:' "$phase_file" 2>/dev/null || true; } | while IFS= read -r line; do
       echo "- $line" >> "$QUEST_FILE"
     done
   done

package/template/.claude/hooks/raid-session-start.sh

@@ -52,6 +52,8 @@ jq -n --arg sid "$SESSION_ID" --arg ts "$STARTED_AT" --arg mode "$MODE" \
 
 # Create quest directory
 mkdir -p "$QUEST_DIR"
+mkdir -p "$QUEST_DIR/phases"
+mkdir -p "$QUEST_DIR/spoils/tasks"
 
 # Offer Vault context if entries exist
 if [ "$RAID_VAULT_ENABLED" = "true" ]; then

package/template/.claude/hooks/rtk-bridge.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# rtk-bridge.sh — Token compression bridge to RTK.
+# Delegates to `rtk hook claude` unless bypassed by config or phase.
+# Fail-open: if anything goes wrong, exit 0 (original command runs uncompressed).
+
+set -euo pipefail
+
+# Source raid-lib for session state + config.
+# Temporarily disable set -e so malformed raid.json in raid-lib doesn't abort the bridge (fail-open).
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+set +e
+source "$SCRIPT_DIR/raid-lib.sh" 2>/dev/null
+set -e
+
+# 1. Check if rtk binary exists
+if ! command -v rtk >/dev/null 2>&1; then
+  exit 0
+fi
+
+# 2. Check if RTK is enabled in raid.json
+if [ "$RAID_RTK_ENABLED" != "true" ]; then
+  exit 0
+fi
+
+# 3. Read stdin (hook input JSON) — we need it for bypass checks and to pass to rtk
+INPUT=$(cat)
+
+# 4. Phase bypass — if active session and current phase is in bypass list
+if [ "$RAID_ACTIVE" = "true" ] && [ -n "$RAID_PHASE" ] && [ "$RAID_RTK_BYPASS_PHASES" != "[]" ]; then
+  if echo "$RAID_RTK_BYPASS_PHASES" | jq -e --arg p "$RAID_PHASE" 'index($p) != null' >/dev/null 2>&1; then
+    exit 0
+  fi
+fi
+
+# 5. Command bypass — check if command prefix matches any bypass entry
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+if [ -n "$COMMAND" ] && [ "$RAID_RTK_BYPASS_COMMANDS" != "[]" ]; then
+  while IFS= read -r prefix; do
+    if [ -n "$prefix" ] && [[ "$COMMAND" == "$prefix"* ]]; then
+      exit 0
+    fi
+  done < <(echo "$RAID_RTK_BYPASS_COMMANDS" | jq -r '.[]' 2>/dev/null)
+fi
+
+# 6. All checks passed — delegate to rtk
+echo "$INPUT" | rtk hook claude 2>/dev/null || exit 0

package/template/.claude/hooks/validate-dungeon.sh

@@ -17,11 +17,17 @@ fi
 _file="${RAID_FILE_PATH}"
 if [[ "$_file" == /* ]]; then
   _file="${_file#"$PWD"/}"
+  # Handle symlink mismatch (e.g., macOS /var -> /private/var) by resolving input path
+  if [[ "$_file" == /* ]] && [ -e "$_file" ]; then
+    _file="$(cd "$(dirname "$_file")" && pwd -P)/$(basename "$_file")"
+    _file="${_file#"$(pwd -P)"/}"
+  fi
 fi
 
 # Only check Dungeon files (quest directory structure + backward compat flat files)
 case "$_file" in
   .claude/dungeon/*/phase-*.md) ;;
+  .claude/dungeon/*/phases/phase-*.md) ;;
   .claude/raid-dungeon.md|.claude/raid-dungeon-phase-*.md) ;;
   *) exit 0 ;;
 esac
@@ -57,9 +63,11 @@ while IFS= read -r line; do
     \#*) continue ;;
   esac
 
-  # Freeform sections — no prefix enforcement
+  # Only enforce prefixes in Discoveries and Active Battles sections.
+  # All other sections (including evolution log content, freeform review, etc.) are allowed.
   case "$current_section" in
-    resolved|shared|escalations) continue ;;
+    discoveries|battles) ;;
+    *) continue ;;
   esac
 
   # Layer 1: Format check — must have a recognized prefix (Discoveries + Active Battles only)
@@ -129,7 +137,7 @@ while IFS= read -r line; do
   fi
 
   # Layer 3: Phase consistency — TASK entries belong in plan or wrap-up phases
-  if [ "$entry_type" = "TASK" ] && [ -n "${RAID_PHASE:-}" ] && [ "${RAID_PHASE}" != "plan" ] && [ "${RAID_PHASE}" != "wrap-up" ] && [ "${RAID_PHASE}" != "finishing" ]; then
+  if [ "$entry_type" = "TASK" ] && [ -n "${RAID_PHASE:-}" ] && [ "${RAID_PHASE}" != "plan" ] && [ "${RAID_PHASE}" != "wrap-up" ]; then
     issues="${issues}
   - TASK entries belong in Plan phase, not ${RAID_PHASE}."
   fi

package/template/.claude/hooks/validate-file-naming.sh

@@ -45,10 +45,15 @@ if [ "$RAID_NAMING" != "none" ]; then
   esac
 fi
 
-# Check 3: Directory depth (normalize absolute paths to relative first)
+# Check 3: Directory depth (normalize absolute paths to relative)
 _depth_path="$RAID_FILE_PATH"
 if [[ "$_depth_path" == /* ]]; then
   _depth_path="${_depth_path#"$PWD"/}"
+  # Handle symlink mismatch (e.g., macOS /var -> /private/var) by resolving input path
+  if [[ "$_depth_path" == /* ]] && [ -e "$_depth_path" ]; then
+    _depth_path="$(cd "$(dirname "$_depth_path")" && pwd -P)/$(basename "$_depth_path")"
+    _depth_path="${_depth_path#"$(pwd -P)"/}"
+  fi
 fi
 DEPTH=$(echo "$_depth_path" | awk -F'/' '{print NF}')
 if [ "$DEPTH" -gt "$RAID_MAX_DEPTH" ]; then

package/template/.claude/hooks/validate-no-placeholders.sh

@@ -13,10 +13,21 @@ if [ -z "$RAID_FILE_PATH" ]; then
   exit 0
 fi
 
+# Normalize absolute paths to relative
+_file="${RAID_FILE_PATH}"
+if [[ "$_file" == /* ]]; then
+  _file="${_file#"$PWD"/}"
+  # Handle symlink mismatch (e.g., macOS /var -> /private/var) by resolving input path
+  if [[ "$_file" == /* ]] && [ -e "$_file" ]; then
+    _file="$(cd "$(dirname "$_file")" && pwd -P)/$(basename "$_file")"
+    _file="${_file#"$(pwd -P)"/}"
+  fi
+fi
+
 # Only check files in specs or plans directories
 IS_RAID_DOC=false
-case "$RAID_FILE_PATH" in
-  "$RAID_SPECS_PATH"/*|"$RAID_PLANS_PATH"/*|.claude/dungeon/*/phase-*.md) IS_RAID_DOC=true ;;
+case "$_file" in
+  "$RAID_SPECS_PATH"/*|"$RAID_PLANS_PATH"/*|.claude/dungeon/*/phases/phase-*.md|.claude/dungeon/*/spoils/*.md|.claude/dungeon/*/spoils/tasks/*.md|.claude/dungeon/*/phase-*.md) IS_RAID_DOC=true ;;
 esac
 
 if [ "$IS_RAID_DOC" = false ]; then

package/template/.claude/hooks/validate-write-gate.sh

@@ -23,6 +23,11 @@ fi
 _file="${RAID_FILE_PATH}"
 if [[ "$_file" == /* ]]; then
   _file="${_file#"$PWD"/}"
+  # Handle symlink mismatch (e.g., macOS /var -> /private/var) by resolving input path
+  if [[ "$_file" == /* ]] && [ -e "$_file" ]; then
+    _file="$(cd "$(dirname "$_file")" && pwd -P)/$(basename "$_file")"
+    _file="${_file#"$(pwd -P)"/}"
+  fi
 fi
 
 # Protect enforcement-critical files from direct agent writes.
@@ -33,9 +38,9 @@ case "$_file" in
     ;;
 esac
 
-# Quest dungeon dir markdown files are always allowed
+# Quest dungeon dir markdown files are always allowed (including subdirectories)
 case "$_file" in
-  .claude/dungeon/*.md)
+  .claude/dungeon/*.md|.claude/dungeon/*/*.md|.claude/dungeon/*/*/*.md)
     exit 0
     ;;
 esac